1818
1919import type { RawSnapshotNode } from '@agent-device/kernel/snapshot' ;
2020import { normalizeType } from '@agent-device/contracts/snapshot' ;
21- import type { TargetAncestryEntry , TargetAnnotationV1 } from '@agent-device/contracts/replay' ;
21+ import type {
22+ LocalIdentity ,
23+ NodeStructuralDenotation ,
24+ TargetAncestryEntry ,
25+ TargetAnnotationV1 ,
26+ } from '@agent-device/contracts/replay' ;
2227import {
2328 normalizeIdentifierField ,
2429 normalizeLabelField ,
@@ -31,14 +36,26 @@ import {
3136// Local identity + ancestry-prefix matching (decision 3 "Local identity" /
3237// "Ancestry"). Pure over the small structural shapes above — no tree
3338// dependency, so both the writer (over `SnapshotNode`-derived values) and a
34- // replay verifier can share it verbatim.
39+ // replay verifier can share it verbatim. The type vocabulary (`LocalIdentity`,
40+ // `NodeStructuralDenotation`) lives in `@agent-device/contracts/replay` so the
41+ // guard shapes there reference it nominally; this module re-exports it beside
42+ // the readers that produce it.
3543// ---------------------------------------------------------------------------
3644
37- export type LocalIdentity = { id ?: string ; role : string ; label ?: string } ;
45+ export type { LocalIdentity , NodeStructuralDenotation } ;
3846
3947type IdentityTreeNode = Pick < RawSnapshotNode , 'type' | 'identifier' | 'label' > ;
4048
41- /** The single normalized local-identity reader shared by record and replay paths. */
49+ /**
50+ * ADR 0012 decision 3: the ONE snapshot-node local-identity reader —
51+ * normalized (NFC, label whitespace collapse, `normalizeType` role) AND
52+ * 256-byte field-capped, on every path. Shared by the record-time writer
53+ * (`src/daemon/session-target-evidence.ts`), replay-time verification
54+ * (`src/daemon/handlers/session-replay-target-verification.ts`), and the
55+ * dispatch-side post-resolution guard
56+ * (`src/commands/interaction/runtime/resolution.ts`), so all three compute
57+ * a node's identity with byte-identical semantics.
58+ */
4259export function readNodeLocalIdentity (
4360 node : Pick < RawSnapshotNode , 'type' | 'identifier' | 'label' > ,
4461) : LocalIdentity {
@@ -59,7 +76,22 @@ export function localIdentitiesEqual(a: LocalIdentity, b: LocalIdentity): boolea
5976 return a . id === b . id && a . role === b . role && a . label === b . label ;
6077}
6178
62- /** Counts every node in a tree carrying the canonical identity id. */
79+ /**
80+ * ADR 0012 decision 3 amendment (#1269): how many nodes in `nodes` carry the
81+ * canonical identity `id`. THE single uniqueness predicate behind both
82+ * id-demotion sites — `computeTargetEvidence`'s `target-v1` identity tuple
83+ * and `buildSelectorChainForNode`'s selector chain. Sharing it is the
84+ * correctness guarantee: a non-unique id is dropped from BOTH or NEITHER,
85+ * never half-demoted (dropped from identity while still leading the chain, or
86+ * the reverse — the exact split #1269's fix exists to close).
87+ *
88+ * `id` is a canonical identity id (`readNodeLocalIdentity(node).id`: NFC +
89+ * 256-byte field cap, no trimming), and every candidate is measured through
90+ * the SAME reader, so the count is over exactly the identities the replay
91+ * verifier keys on. There is deliberately NO ancestry / parent-walk
92+ * exclusion: an id is non-selective the moment two nodes anywhere in the tree
93+ * carry it, independent of structural context or a broken parent linkage.
94+ */
6395export function idMatchCountInTree ( nodes : readonly IdentityTreeNode [ ] , id : string ) : number {
6496 let count = 0 ;
6597 for ( const node of nodes ) {
@@ -68,7 +100,17 @@ export function idMatchCountInTree(nodes: readonly IdentityTreeNode[], id: strin
68100 return count ;
69101}
70102
71- /** Drops a non-unique id while preserving the role and label identity tiers. */
103+ /**
104+ * ADR 0012 decision 3 amendment (#1269): `identity` with its `id` demoted
105+ * whenever the id is non-unique in `nodes`, built on the SAME
106+ * `idMatchCountInTree` predicate `buildSelectorChainForNode`'s
107+ * `selectableId` keys off directly. `computeTargetEvidence` uses this
108+ * whole-identity form; extracted so a third call site (#1280's
109+ * press-retarget identity-empty check, `src/core/press-retarget.ts`)
110+ * shares it rather than re-deriving the rule a third way. A demoted id
111+ * falls back to role+label, the same shape an unrecorded id already
112+ * computes.
113+ */
72114export function demoteNonUniqueLocalIdentity (
73115 identity : LocalIdentity ,
74116 nodes : readonly IdentityTreeNode [ ] ,
@@ -79,11 +121,6 @@ export function demoteNonUniqueLocalIdentity(
79121 return { role, ...( label !== undefined ? { label } : { } ) } ;
80122}
81123
82- export type NodeStructuralDenotation = {
83- documentOrder : number ;
84- sibling : number ;
85- } ;
86-
87124type StructuralNode = Pick < RawSnapshotNode , 'index' | 'parentIndex' > ;
88125
89126/** Zero-based ordinal among the node's own parent's children, in document order. */
@@ -104,6 +141,12 @@ export function readNodeStructuralDenotation(
104141 return { documentOrder : node . index , sibling : siblingOrdinal ( nodes , node ) } ;
105142}
106143
144+ /**
145+ * The guard passes only when BOTH structural discriminators agree — a
146+ * fail-closed comparison: two same-local-identity duplicates differ in
147+ * `documentOrder` (always) and usually `sibling`, so the guard refuses
148+ * whenever dispatch resolved a different member than verification isolated.
149+ */
107150export function structuralDenotationsEqual (
108151 a : NodeStructuralDenotation ,
109152 b : NodeStructuralDenotation ,
0 commit comments