fix: address PR #1196 review — contract boundary, formatting, path-6 reasons, worst-case sizing

- native-ref contract test: deliberately updated to assert the new ADR 0012
  boundary — the preflight's node/preActionNodes ride the INTERNAL runtime
  result and visualization payload only; the public responseData never
  carries node/preActionNodes/targetEvidence (asserted directly against
  buildInteractionResponseData).
- oxfmt formatting on all touched files.
- classifyTargetBindingMatch path 6 now distinguishes decision 3's two
  spec-distinct outcomes: a signal isolating a member that differs from the
  winner ('signal-isolated-wrong', the paths-4/5 comparison class, future
  identity-mismatch) vs true fall-through ('no-signal-isolation', future
  identity-unverifiable), so step 4 can consume the reasons directly.
- writer reduction loop sizes every candidate against the worst-case
  verification value ("unverifiable" is 4 bytes longer than "verified"), so
  a fail-closed self-check downgrade can never push an accepted payload over
  the 4 KiB cap; pinned by a 1-byte-granularity sweep across the boundary
  that fails against the old placeholder-sized check.

Author: thymikee

src/daemon/__tests__/session-target-evidence.test.ts

@@ -187,7 +187,10 @@ test('computeTargetEvidence: max-size labels across K=8 ancestors reduce ancestr
   const evidence = computeTargetEvidence({ node: winner, nodes });
   assert.ok(evidence);
   assert.ok(evidence.ancestry.length <= TARGET_ANNOTATION_MAX_ANCESTRY);
-  assert.ok(evidence.ancestry.length < TARGET_ANNOTATION_MAX_ANCESTRY, 'ancestry must have been reduced');
+  assert.ok(
+    evidence.ancestry.length < TARGET_ANNOTATION_MAX_ANCESTRY,
+    'ancestry must have been reduced',
+  );
   // Nearest-ancestor-first: the first (kept) entries are the leaf-side ones.
   assert.equal(evidence.ancestry[0]?.label, maxLabel);
 
@@ -345,3 +348,62 @@ test('computeTargetEvidence: a node with an over-cap id still matches itself and
   assert.equal(evidence.id, overCapId.slice(0, TARGET_ANNOTATION_MAX_FIELD_BYTES));
   assert.equal(evidence.verification, 'verified');
 });
+
+// ---------------------------------------------------------------------------
+// Worst-case verification sizing: "unverifiable" serializes 4 bytes longer
+// than "verified". The reduction loop must size each candidate against the
+// worst-case value so a fail-closed self-check downgrade can never push an
+// already-accepted payload over the 4 KiB cap. The window is only 4 bytes
+// wide, so sweep a tunable root-side label length across the boundary — some
+// length in the sweep necessarily lands inside the window, where a
+// placeholder-sized ("verified") check would accept a payload whose
+// downgraded form overflows.
+// ---------------------------------------------------------------------------
+
+test('computeTargetEvidence: reduction sizes against the worst-case verification value across the 4 KiB boundary', () => {
+  const maxField = 'x'.repeat(TARGET_ANNOTATION_MAX_FIELD_BYTES);
+
+  const buildChain = (tunableLabelLength: number): SnapshotNode[] => {
+    const raw: RawSnapshotNode[] = [];
+    // Root (index 0) .. leaf's parent (index 7): 8 ancestors total (K=8).
+    // Root-side entries are dropped first, so the tunable label sits at the
+    // root to sweep total payload size in 1-byte steps.
+    raw.push({ index: 0, type: 'Window', label: 'w'.repeat(tunableLabelLength), depth: 0 });
+    raw.push({ index: 1, type: 'View', label: 'v', depth: 1, parentIndex: 0 });
+    for (let depth = 2; depth < 8; depth += 1) {
+      raw.push({ index: depth, type: maxField, label: maxField, depth, parentIndex: depth - 1 });
+    }
+    raw.push({
+      index: 8,
+      type: maxField,
+      label: maxField,
+      rect: { x: 0, y: 0, width: 10, height: 10 },
+      depth: 8,
+      parentIndex: 7,
+    });
+    return toSnapshotNodes(raw);
+  };
+
+  let sawFullAncestry = false;
+  let sawReducedAncestry = false;
+  for (let tunable = 0; tunable <= TARGET_ANNOTATION_MAX_FIELD_BYTES; tunable += 1) {
+    const nodes = buildChain(tunable);
+    const evidence = computeTargetEvidence({ node: nodes.at(-1)!, nodes });
+    assert.ok(evidence);
+    if (evidence.ancestry.length === TARGET_ANNOTATION_MAX_ANCESTRY) sawFullAncestry = true;
+    else sawReducedAncestry = true;
+    // The emitted payload must fit even re-serialized with the longer
+    // verification value — the invariant the worst-case sizing guarantees.
+    const worstCase = serializeTargetAnnotationV1({ ...evidence, verification: 'unverifiable' });
+    assert.ok(
+      utf8ByteLength(worstCase) <= TARGET_ANNOTATION_MAX_PAYLOAD_BYTES,
+      `worst-case payload overflows at tunable label length ${tunable}`,
+    );
+    // And the parser accepts the writer's actual output, as always.
+    parseTargetAnnotationV1Payload(serializeTargetAnnotationV1(evidence));
+  }
+  // The sweep must actually cross the reduction boundary for the window to
+  // have been exercised.
+  assert.ok(sawFullAncestry, 'sweep never produced an unreduced payload — fixture too large');
+  assert.ok(sawReducedAncestry, 'sweep never forced a reduction — fixture too small');
+});

src/daemon/handlers/interaction-common.ts

@@ -114,4 +114,4 @@ function extractTargetEvidenceForRecording(
     return { result: rest, targetEvidence: undefined };
   }
   return { result: rest, targetEvidence: computeTargetEvidence({ node, nodes: preActionNodes }) };
-}
+}

src/daemon/session-target-evidence.ts

@@ -88,7 +88,17 @@ export function computeTargetEvidence(params: {
 
   for (let ancestryLength = fullAncestry.length; ancestryLength >= floor; ancestryLength -= 1) {
     const { candidate, domain } = buildCandidate(ancestryLength);
-    if (utf8ByteLength(serializeTargetAnnotationV1(candidate)) <= TARGET_ANNOTATION_MAX_PAYLOAD_BYTES) {
+    // Size against the WORST-CASE verification value ("unverifiable" is 4
+    // serialized bytes longer than "verified") so the payload provably fits
+    // no matter what the self-check below returns — otherwise a payload
+    // within 4 bytes of the cap could pass this check as "verified" and then
+    // overflow once a fail-closed self-check downgraded it, violating the
+    // writer-parser invariant exactly in the rare capture-anomaly case it
+    // exists for.
+    if (
+      utf8ByteLength(serializeTargetAnnotationV1({ ...candidate, verification: 'unverifiable' })) <=
+      TARGET_ANNOTATION_MAX_PAYLOAD_BYTES
+    ) {
       candidate.verification = runRecordTimeSelfCheck({ node, domain });
       return candidate;
     }
@@ -100,7 +110,9 @@ export function computeTargetEvidence(params: {
       // rect (never compared) as one last, spec-consistent reduction rather
       // than emit a payload the parser would reject.
       candidate.verification = 'unverifiable';
-      if (utf8ByteLength(serializeTargetAnnotationV1(candidate)) > TARGET_ANNOTATION_MAX_PAYLOAD_BYTES) {
+      if (
+        utf8ByteLength(serializeTargetAnnotationV1(candidate)) > TARGET_ANNOTATION_MAX_PAYLOAD_BYTES
+      ) {
         delete candidate.rect;
       }
       return candidate;
@@ -152,8 +164,12 @@ function buildAncestryChain(
   while (current && !visited.has(current.index) && chain.length < limit) {
     visited.add(current.index);
     const identity = boundedLocalIdentity(current);
-    chain.push({ role: identity.role, ...(identity.label !== undefined ? { label: identity.label } : {}) });
-    current = typeof current.parentIndex === 'number' ? byIndex.get(current.parentIndex) : undefined;
+    chain.push({
+      role: identity.role,
+      ...(identity.label !== undefined ? { label: identity.label } : {}),
+    });
+    current =
+      typeof current.parentIndex === 'number' ? byIndex.get(current.parentIndex) : undefined;
   }
   return chain;
 }

src/replay/__tests__/script.test.ts

@@ -395,9 +395,11 @@ const SAVE_EVIDENCE_LINE =
   '# agent-device:target-v1 {"id":"save","role":"button","label":"Save","ancestry":[{"role":"toolbar","label":"Editor"},{"role":"window"}],"sibling":0,"viewportOrder":0,"scrollRegion":{"role":"scrollview","id":"editor-scroll"},"verification":"verified"}';
 
 test('a target-v1 annotation immediately preceding an action line attaches to that action', () => {
-  const script = ['context platform=ios device=iPhone', SAVE_EVIDENCE_LINE, 'click @e12 "Save"'].join(
-    '\n',
-  );
+  const script = [
+    'context platform=ios device=iPhone',
+    SAVE_EVIDENCE_LINE,
+    'click @e12 "Save"',
+  ].join('\n');
   const { actions } = parseReplayScriptDetailed(script);
   assert.equal(actions.length, 1);
   assert.deepEqual(actions[0]?.targetEvidence, SAVE_EVIDENCE);
@@ -438,11 +440,7 @@ test('a malformed target-v1 payload is rejected as INVALID_ARGS, not silently dr
 });
 
 test('an unknown future target-vN comment is an ordinary comment: no binding requirement, no evidence attached', () => {
-  const script = [
-    '# agent-device:target-v2 {"whatever":true}',
-    '',
-    'click @e12 "Save"',
-  ].join('\n');
+  const script = ['# agent-device:target-v2 {"whatever":true}', '', 'click @e12 "Save"'].join('\n');
   const { actions } = parseReplayScriptDetailed(script);
   assert.equal(actions.length, 1);
   assert.equal(actions[0]?.targetEvidence, undefined);

src/replay/__tests__/target-identity.test.ts

@@ -22,10 +22,7 @@ function baseEvidence(overrides: Partial<TargetAnnotationV1> = {}): TargetAnnota
     id: 'save',
     role: 'button',
     label: 'Save',
-    ancestry: [
-      { role: 'toolbar', label: 'Editor' },
-      { role: 'window' },
-    ],
+    ancestry: [{ role: 'toolbar', label: 'Editor' }, { role: 'window' }],
     sibling: 0,
     viewportOrder: 0,
     scrollRegion: { role: 'scrollview', id: 'editor-scroll' },
@@ -171,10 +168,7 @@ test('matchesAncestryPrefix accepts an observed chain that is a superset on the
 });
 
 test('matchesAncestryPrefix rejects an inserted wrapper ancestor (structure is part of identity)', () => {
-  const recorded = [
-    { role: 'toolbar', label: 'Editor' },
-    { role: 'window' },
-  ];
+  const recorded = [{ role: 'toolbar', label: 'Editor' }, { role: 'window' }];
   // A new wrapper view inserted directly above the target shifts every entry
   // one level down — the leaf-anchored prefix no longer matches.
   const observedWithInsertedWrapper = [
@@ -205,10 +199,7 @@ test('matchesLocalIdentity: a recorded id never matches a node without that id',
 
 test('matchesLocalIdentity: with no recorded id, role+label must both match, absent-absent counts as equal', () => {
   assert.equal(matchesLocalIdentity({ role: 'button' }, { role: 'button' }), true);
-  assert.equal(
-    matchesLocalIdentity({ role: 'button', label: 'Save' }, { role: 'button' }),
-    false,
-  );
+  assert.equal(matchesLocalIdentity({ role: 'button', label: 'Save' }, { role: 'button' }), false);
 });
 
 // ---------------------------------------------------------------------------
@@ -249,7 +240,9 @@ test('parser rejects a payload exceeding the 4 KiB cap', () => {
 });
 
 test('parser rejects more than 8 ancestry entries', () => {
-  const ancestry = Array.from({ length: TARGET_ANNOTATION_MAX_ANCESTRY + 1 }, () => ({ role: 'view' }));
+  const ancestry = Array.from({ length: TARGET_ANNOTATION_MAX_ANCESTRY + 1 }, () => ({
+    role: 'view',
+  }));
   assertInvalidArgs(
     () =>
       parseTargetAnnotationV1Payload(
@@ -418,7 +411,7 @@ test('classifyTargetBindingMatch path 6: a scroll region that no longer exists f
     regionMemberRefs: undefined, // region unavailable
     viewportCandidateRef: undefined,
   });
-  assert.deepEqual(result, { path: 6, outcome: 'unverifiable' });
+  assert.deepEqual(result, { path: 6, outcome: 'unverifiable', reason: 'no-signal-isolation' });
 });
 
 test('classifyTargetBindingMatch path 6: an out-of-range recorded viewportOrder falls through to unverifiable', () => {
@@ -430,17 +423,40 @@ test('classifyTargetBindingMatch path 6: an out-of-range recorded viewportOrder
     regionMemberRefs: ['e1', 'e2'],
     viewportCandidateRef: undefined, // ordinal was out of range
   });
-  assert.deepEqual(result, { path: 6, outcome: 'unverifiable' });
+  assert.deepEqual(result, { path: 6, outcome: 'unverifiable', reason: 'no-signal-isolation' });
 });
 
-test('classifyTargetBindingMatch path 6: viewportOrder resolves to a DIFFERENT node than the winner is unverifiable, never a silent pick', () => {
-  const result = classifyTargetBindingMatch({
+test('classifyTargetBindingMatch path 6: a signal isolating a DIFFERENT node than the winner is the paths-4/5 comparison class, not fall-through', () => {
+  // Decision 3 path 6.i/6.ii: when a signal denotes exactly one member,
+  // "compare with W as in paths 4/5" — an isolated-but-different member is
+  // the same class as path 5's unique-but-wrong rebind (a future
+  // identity-mismatch), distinct from true no-isolation fall-through (a
+  // future identity-unverifiable with candidates).
+  const viaViewportOrder = classifyTargetBindingMatch({
     winnerRef: 'e1',
     matchedRefs: ['e1', 'e2'],
     identitySetRefs: ['e1', 'e2'],
     siblingMatchRefs: ['e1', 'e2'],
     regionMemberRefs: ['e1', 'e2'],
     viewportCandidateRef: 'e2',
   });
-  assert.deepEqual(result, { path: 6, outcome: 'unverifiable' });
+  assert.deepEqual(viaViewportOrder, {
+    path: 6,
+    outcome: 'unverifiable',
+    reason: 'signal-isolated-wrong',
+  });
+
+  const viaSibling = classifyTargetBindingMatch({
+    winnerRef: 'e1',
+    matchedRefs: ['e1', 'e2'],
+    identitySetRefs: ['e1', 'e2'],
+    siblingMatchRefs: ['e2'], // sibling isolates e2, not the winner
+    regionMemberRefs: ['e1', 'e2'],
+    viewportCandidateRef: 'e1',
+  });
+  assert.deepEqual(viaSibling, {
+    path: 6,
+    outcome: 'unverifiable',
+    reason: 'signal-isolated-wrong',
+  });
 });

src/replay/target-identity.ts

@@ -80,9 +80,7 @@ export function normalizeRoleField(value: string): string {
 /** label fields: NFC, trim, collapse internal whitespace runs to one space. */
 export function normalizeLabelField(value: string | undefined): string | undefined {
   if (value === undefined) return undefined;
-  const collapsed = nfc(value)
-    .trim()
-    .replace(/\s+/g, ' ');
+  const collapsed = nfc(value).trim().replace(/\s+/g, ' ');
   return collapsed.length > 0 ? collapsed : undefined;
 }
 
@@ -413,12 +411,25 @@ export type TargetBindingClassificationInput = {
   viewportCandidateRef: string | undefined;
 };
 
+/**
+ * Decision 3 keeps two spec-distinct failure classes inside path 6, and the
+ * `reason` field preserves the distinction for migration step 4's divergence
+ * `kind` mapping:
+ *
+ * - a disambiguation signal ISOLATING exactly one member that differs from
+ *   the winner is "compare with W as in paths 4/5" — the same class as path
+ *   5's unique-but-wrong rebind, i.e. a future `identity-mismatch`
+ *   (`signal-isolated-wrong`);
+ * - neither signal isolating any member is the true fall-through — a future
+ *   `identity-unverifiable` with up to 5 candidates (`no-signal-isolation`).
+ */
 export type TargetBindingClassification =
   | { path: 2; outcome: 'unverifiable'; reason: 'selector-miss' }
   | { path: 3; outcome: 'unverifiable'; reason: 'identity-set-empty' }
   | { path: 4; outcome: 'verified' }
   | { path: 5; outcome: 'unverifiable'; reason: 'unique-but-wrong' }
-  | { path: 6; outcome: 'verified' | 'unverifiable' };
+  | { path: 6; outcome: 'verified' }
+  | { path: 6; outcome: 'unverifiable'; reason: 'signal-isolated-wrong' | 'no-signal-isolation' };
 
 /**
  * Decision 3 "Replay-time verification", paths 2-6. `matchCount == 0` (path
@@ -442,18 +453,22 @@ export function classifyTargetBindingMatch(
       : { path: 5, outcome: 'unverifiable', reason: 'unique-but-wrong' };
   }
   if (input.siblingMatchRefs.length === 1) {
+    // The sibling signal isolates exactly one member: the evidence denotes
+    // it — compare with the winner as in paths 4/5 (decision 3, path 6.i).
     return input.siblingMatchRefs[0] === input.winnerRef
       ? { path: 6, outcome: 'verified' }
-      : { path: 6, outcome: 'unverifiable' };
+      : { path: 6, outcome: 'unverifiable', reason: 'signal-isolated-wrong' };
   }
   if (
     input.regionMemberRefs !== undefined &&
     input.regionMemberRefs.length > 0 &&
     input.viewportCandidateRef !== undefined
   ) {
+    // Region-scoped viewportOrder denotes a member: compare as in paths 4/5
+    // (decision 3, path 6.ii).
     return input.viewportCandidateRef === input.winnerRef
       ? { path: 6, outcome: 'verified' }
-      : { path: 6, outcome: 'unverifiable' };
+      : { path: 6, outcome: 'unverifiable', reason: 'signal-isolated-wrong' };
   }
-  return { path: 6, outcome: 'unverifiable' };
+  return { path: 6, outcome: 'unverifiable', reason: 'no-signal-isolation' };
 }

test/integration/interaction-contract/native-ref.contract.test.ts

@@ -4,6 +4,7 @@ import type { InteractionGuarantee } from '../../../src/contracts/interaction-gu
 import type { SnapshotState } from '../../../src/kernel/snapshot.ts';
 import { ref } from '../../../src/commands/index.ts';
 import { scenarioName } from './coverage-manifest.ts';
+import { buildInteractionResponseData } from '../../../src/daemon/handlers/interaction-touch-response.ts';
 import { NATIVE_REF_COVERAGE } from './native-ref.coverage.ts';
 import {
   closedDrawerSnapshot,
@@ -169,5 +170,27 @@ test(scenario('responseConstruction'), async () => {
   assert.deepEqual(result.target, { kind: 'ref', ref: '@e1' });
   assert.deepEqual(result.backendResult, { ref: 'e1' });
   assert.equal(result.point, undefined);
-  assert.equal(result.node, undefined);
+  // ADR 0012 decision 3: the preflight's already-fetched stored-snapshot node
+  // and tree now ride on the INTERNAL runtime result so record-time
+  // target-binding evidence can be computed at zero extra capture cost. This
+  // is the internal boundary only — the shared construction site
+  // (buildInteractionResponseData) attaches them exclusively to the internal
+  // visualization payload, and the public responseData never carries them
+  // (asserted below).
+  assert.equal(result.node?.ref, 'e1');
+  assert.ok(Array.isArray(result.preActionNodes));
+
+  const { result: visualization, responseData } = buildInteractionResponseData({
+    source: { kind: 'runtime', result },
+    referenceFrame: undefined,
+  });
+  // Internal visualization payload: carries the node/tree for the recording
+  // pipeline (stripped again before session-history persistence by
+  // extractTargetEvidenceForRecording).
+  assert.ok(visualization.node);
+  assert.ok(visualization.preActionNodes);
+  // Public payload: the raw node/tree must never reach the wire.
+  assert.equal('node' in responseData, false);
+  assert.equal('preActionNodes' in responseData, false);
+  assert.equal('targetEvidence' in responseData, false);
 });