refactor(daemon): make admit-before-bind structural with an admitted-plan token; retire the R32 syntax policy

admitRuntimePlan (was inspectRequiredRuntimeUse) now takes the plan and, on
success, returns an AdmittedRuntimePlan<Plan>: the plan plus a module-private
symbol key no other module can name. bindSnapshotCaptureRuntime requires that
token instead of a bare plan, so the snapshot route cannot reach the capture
operations without facts-first admission having run for the very plan whose
use is bound. Forging the token needs a type assertion, and the cutover gate's
manufactured-proof column now rejects a cast to AdmittedRuntimePlan in
src/daemon/ alongside BoundDeviceRuntime.

That retires scripts/layering/runtime-command-cutover-snapshot.ts — R32's
per-command AST policy (exact-call-shape recognition of the admission call and
a text sniff for a locally reimplemented admission) — and the source-regex
test in snapshot-runtime-execution.test.ts. The generic row keeps retirement,
narrowing, and singular-execution claims; nothing snapshot-specific remains
in scripts/layering/. Two @ts-expect-error proofs pin the seam: a literal is
not an admission, and the binder refuses a bare plan.

Author: thymikee

scripts/layering/runtime-command-cutover-policy.test.ts

@@ -22,6 +22,7 @@ test('the parametrized gate goes red on a planted row across every generalized c
             "import { resolvePlantedBackend } from './planted-legacy.ts';",
             "requireCommandSupported('planted', device);",
             'const widened = runtime as PlantedRuntimeOperations;',
+            'const forged = { admitted: true, plan } as AdmittedRuntimePlan<PlantedPlan>;',
             "function handlePlantedCommand() { widened.operations['plantedDump']({}); }",
           ].join('\n'),
         ],
@@ -44,6 +45,9 @@ test('the parametrized gate goes red on a planted row across every generalized c
       'src/daemon/planted-handler.ts: legacy planted route resolvePlantedBackend',
       'src/daemon/planted-handler.ts: legacy planted capability admission requireCommandSupported',
       'src/daemon/planted-handler.ts: widened planted runtime type assertion',
+      // The admission proof is shared across rows: a route that casts its way to an
+      // AdmittedRuntimePlan has manufactured the facts-first admission the binder requires.
+      'src/daemon/planted-handler.ts: widened planted runtime type assertion',
       'src/daemon/planted-handler.ts: bracketed planted operation access',
       'src/core/command-descriptor/registry.ts: planted descriptor retains legacy capability admission',
       'src/core/capabilities.ts: static platform command set retains planted admission',

scripts/layering/runtime-command-cutover-policy.ts

@@ -13,7 +13,11 @@ import { memberName, propertyName, visitAst, type ProductionSource } from './cut
 
 type AstNode = Record<string, unknown>;
 
-const SHARED_RUNTIME_TYPE_NAME = 'BoundDeviceRuntime';
+// Types no daemon route may manufacture with an assertion: the bound runtime itself, and the
+// admission proof a facts-first binder requires (`AdmittedRuntimePlan`, minted only by
+// `admitRuntimePlan`). Together with the row's own runtime type names they are the
+// manufactured-proof column — a cast to any of them is a route repairing missing proof.
+const SHARED_RUNTIME_TYPE_NAMES = ['BoundDeviceRuntime', 'AdmittedRuntimePlan'] as const;
 
 /**
  * The one parametrized runtime-command-cutover gate (ADR 0019 §8). Every migrated
@@ -372,7 +376,7 @@ function narrowingViolations(
   // An inventory row binds no device runtime, so it has nothing to re-widen.
   if (!file.path.startsWith('src/daemon/') || row.execution !== 'device-runtime') return [];
   const violations: UnruledViolation[] = [];
-  const runtimeTypes = new Set([SHARED_RUNTIME_TYPE_NAME, ...row.runtimeTypeNames]);
+  const runtimeTypes = new Set([...SHARED_RUNTIME_TYPE_NAMES, ...row.runtimeTypeNames]);
   visitAst(program, (node) => {
     if (
       (node['type'] === 'TSAsExpression' || node['type'] === 'TSTypeAssertion') &&

scripts/layering/runtime-command-cutover-snapshot.test.ts

@@ -70,11 +70,7 @@ test('R32 snapshot rejects legacy admission and dispatcher projection', () => {
           }
           function dispatchSnapshotViaRuntime() {
             const plan = resolveSnapshotRuntimePlan(normalizedIntent);
-            inspectRequiredRuntimeUse({
-              device,
-              use: plan.use,
-              inspectFacts: params.inspectFacts,
-            });
+            admitRuntimePlan({ device, plan, inspectFacts: params.inspectFacts });
             requireCommandSupported('snapshot', device);
           }
           function handleSnapshotCommands() {

scripts/layering/runtime-command-cutover-snapshot.ts

@@ -10,7 +10,6 @@ import {
   runtimeLifecycleRouteBindingViolations,
   sourceExecutedUsingDeclarationViolations,
 } from './runtime-command-cutover-extensions.ts';
-import { snapshotPlatformPolicyBranchViolations } from './runtime-command-cutover-snapshot.ts';
 import { recordRuntimeDaemonMechanicsViolations } from './record-runtime-mechanics-policy.ts';
 import { retiredDispatchProjectionViolations } from './runtime-command-cutover-descriptor.ts';
 
@@ -470,7 +469,7 @@ export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
         captureSnapshotWithoutActiveApp: ['selectSnapshotWithoutActiveApp'],
       },
     },
-    extensions: [snapshotRetiredDispatchProjectionProof, snapshotPlatformPolicyBranchViolations],
+    extensions: [snapshotRetiredDispatchProjectionProof],
   },
 ];
 

scripts/layering/runtime-command-cutover-table.test.ts

@@ -1,17 +1,7 @@
-import { readFileSync } from 'node:fs';
 import { snapshotRuntimePlanUses } from '@agent-device/contracts/platform';
 import { expect, test } from 'vitest';
 import { commandDescriptors } from '../registry.ts';
 
-const snapshotRuntimeSource = readFileSync(
-  new URL('../../../daemon/snapshot-runtime.ts', import.meta.url),
-  'utf8',
-);
-const snapshotRuntimeBindingSource = readFileSync(
-  new URL('../../../daemon/snapshot-runtime-binding.ts', import.meta.url),
-  'utf8',
-);
-
 test('snapshot descriptor declares its complete planned capture uses with no legacy projection', () => {
   const snapshot = commandDescriptors.find(({ name }) => name === 'snapshot');
 
@@ -28,27 +18,3 @@ test('snapshot descriptor declares its complete planned capture uses with no leg
     ['captureSnapshot', 'captureSnapshotWithCustomActions', 'captureSnapshotWithoutActiveApp'],
   ]);
 });
-
-test('snapshot public route inspects facts and binds the declared use exactly once', () => {
-  const publicRoute = snapshotRuntimeSource.slice(
-    snapshotRuntimeSource.indexOf('export async function dispatchSnapshotViaRuntime'),
-    snapshotRuntimeSource.indexOf('function publishedSnapshotGeneration'),
-  );
-
-  expect(publicRoute.match(/resolveSnapshotRuntimePlan\(\{/g)).toHaveLength(1);
-  expect(publicRoute.match(/inspectRequiredRuntimeUse\(\{/g)).toHaveLength(1);
-  expect(
-    publicRoute.match(/bindSnapshotCaptureRuntime\(params\.bindDevice, device, plan\)/g),
-  ).toHaveLength(1);
-  expect(
-    publicRoute.match(/use: plan\.use,[\s\S]*inspectFacts: params\.inspectFacts/g),
-  ).toHaveLength(1);
-  expect(
-    snapshotRuntimeBindingSource.match(/const bind = requireRuntimeBinding\(bindDevice\)/g),
-  ).toHaveLength(1);
-  expect(publicRoute.match(/runtime\.captureSnapshot\(/g)).toHaveLength(1);
-  expect(publicRoute).not.toContain("requireCommandSupported('snapshot'");
-  for (const policyName of ['isIosFamily', 'isIosSimulator', 'providerOwned']) {
-    expect(snapshotRuntimeBindingSource).not.toContain(policyName);
-  }
-});

scripts/layering/runtime-command-cutover-table.ts

@@ -0,0 +1,25 @@
+import { resolveSnapshotRuntimePlan } from '@agent-device/contracts/platform';
+import { expect, test } from 'vitest';
+import { IOS_SIMULATOR } from '../../__tests__/test-utils/index.ts';
+import { admitRuntimePlan } from '../handlers/session-runtime-admission.ts';
+import { bindSnapshotCaptureRuntime } from '../snapshot-runtime-binding.ts';
+import { snapshotRuntimeFixture } from './snapshot-runtime-fixture.ts';
+
+test('the snapshot binder takes an admission, never a bare plan', () => {
+  const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
+  // Type-level proof that admit-before-bind is enforced at the seam: the binder's parameter is
+  // AdmittedRuntimePlan<SnapshotRuntimePlan>, which only admitRuntimePlan produces. Widening it
+  // back to SnapshotRuntimePlan makes this directive unused and tsc fails.
+  // @ts-expect-error the facts-first binder requires the admission token, not the plan
+  const bindBarePlan = () => bindSnapshotCaptureRuntime(undefined, IOS_SIMULATOR, plan);
+  expect(bindBarePlan).toBeTypeOf('function');
+});
+
+test('binds the operation the admitted plan selected and nothing wider', async () => {
+  const { inspectFacts, bindDevice } = snapshotRuntimeFixture();
+  const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
+  const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
+  if (!admission.admitted) throw new Error('fixture admits captureSnapshot on an iOS simulator');
+  const runtime = await bindSnapshotCaptureRuntime(bindDevice, IOS_SIMULATOR, admission);
+  expect(Object.keys(runtime)).toEqual(['captureSnapshot']);
+});

src/core/command-descriptor/__tests__/snapshot-runtime-execution.test.ts

@@ -0,0 +1,45 @@
+import { resolveSnapshotRuntimePlan } from '@agent-device/contracts/platform';
+import { expect, test } from 'vitest';
+import { ANDROID_EMULATOR, IOS_SIMULATOR } from '../../../__tests__/test-utils/index.ts';
+import { snapshotRuntimeFixture } from '../../__tests__/snapshot-runtime-fixture.ts';
+import { admitRuntimePlan, type AdmittedRuntimePlan } from '../session-runtime-admission.ts';
+
+const { inspectFacts } = snapshotRuntimeFixture();
+
+test('admits the plan whose required operations the owner facts report available', async () => {
+  const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
+  const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
+  expect(admission.admitted).toBe(true);
+  if (!admission.admitted) throw new Error('unreachable');
+  // The token carries the very plan that was admitted, so a binder that takes the token
+  // binds exactly the use the facts were checked against.
+  expect(admission.plan).toBe(plan);
+});
+
+test('refuses on the first required operation the owner facts report unavailable', async () => {
+  const plan = resolveSnapshotRuntimePlan({ customActions: true, hasActiveApp: true });
+  const admission = await admitRuntimePlan({ device: ANDROID_EMULATOR, plan, inspectFacts });
+  expect(admission).toMatchObject({
+    admitted: false,
+    operation: 'captureSnapshotWithCustomActions',
+    fact: { available: false, reason: 'unsupported-platform-leaf' },
+  });
+});
+
+test('throws when no facts inspection seam was supplied', async () => {
+  const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
+  await expect(admitRuntimePlan({ device: IOS_SIMULATOR, plan })).rejects.toThrow(
+    'Device runtime facts inspection is unavailable.',
+  );
+});
+
+test('the admission proof cannot be written down: only admitRuntimePlan mints it', () => {
+  const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
+  // A planted red for the seam itself: delete the proof key from AdmittedRuntimePlan and this
+  // directive becomes unused, which tsc reports. The key is a module-private symbol, so no
+  // literal in any other module can satisfy the type — a route holds a token only by having
+  // called admitRuntimePlan (or by a type assertion, which the cutover gate rejects in src/daemon/).
+  // @ts-expect-error a literal without the module-private proof key is not an admission
+  const forged: AdmittedRuntimePlan<typeof plan> = { admitted: true, plan };
+  expect(forged.plan).toBe(plan);
+});