Context
Leaf 1 of Epic #14565 (direction-weighted Golden Path), graduated from Discussion #14453. GPT's §5.2 STEP_BACK ask D made the Decision-Record path a graduation blocker: "any SUMMARY_ direction field must cite ADR-0028 and any new graph node/edge class must cite/update ADR-0024"* (DC…17528043). This leaf IS that path, and it sequences FIRST — every other leaf's schema claims derive authority from it.
The Problem
Three authority gaps block implementation: (1) ADR-0028's SUMMARY_* schema is direction-blind by design — per-direction sub-aggregates need an amendment, not a workaround; (2) EVOLUTION_GOAL (generalizing #14442's BUSINESS_GOAL) and any direction-mapping edges need ADR-0024 standing — the protected-edge-set lesson from #14422 applies forward: an edge class outside the protected set silently decays and any number built on it rots invisibly; (3) direction identity needs a normative contract or every downstream metric is unfalsifiable.
The Architectural Reality
learn/agentos/decisions/0028-*.md — §2.3 single deterministic aggregation lane (no second writer), §2.4 SUMMARY_* fields, §2.6 partitions. The directionBreakdown map + windowSemantics filter-set declaration extend §2.4; the single-lane invariant is untouched.learn/agentos/decisions/0024-*.md — node/edge vocabulary + PROTECTED_EDGE_TYPES + decay semantics + §2.9 honesty boundary (the non-blocking-dependency precedent this epic reuses for the #14503 cold-start sibling).ai/services/graph/ — canonicalizeConceptId concept-spine (merged); all direction-concept references route through it (#14453 OQ1 AC).- #14433's armed direction-slot (nullable, representation-agnostic) is the consumption point the DR must specify, not re-invent.
The Fix
One ADR document (learn/agentos/decisions/, next free number) specifying: (a) the deterministic direction-key contract — EVOLUTION_GOAL id OR cluster-id+mappingVersion, append-only mapping history, LLM labels never identity; (b) the directionBreakdown field spec on L1/L2 records ({"<directionKey>@<mappingVersion>": share}, one record per window, side-table fallback at the >20%-of-record-bytes cardinality probe); (c) windowSemantics filter-set declaration + the falsifier-symmetry rule (same filters + same version pin on measurement AND falsifying query; cross-filter-set comparison = type error); (d) the conservation invariant Σ_D v_D + v_UNATTRIBUTED = v_total as a build-time check with UNATTRIBUTED as first-class fail-open pool; (e) the fail-open additive HARD AC (direction never gates the base route; routed-nodes-0 class preserved); (f) EVOLUTION_GOAL node class + mapping-edge classes with their ADR-0024 protected-set disposition; (g) the OQ6 producer/consumer boundary map (×6, from the graduated body) as the DR's consumer section.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| ADR-0028 §2.4 SUMMARY_* fields |
ADR-0028 (Accepted) |
AMEND: + directionBreakdown, windowSemantics.filterSets |
absent fields = direction-blind legacy windows, valid |
the new ADR + 0028 delta |
#14453 OQ2 disposition DC…17512853 |
| ADR-0024 node/edge registry |
ADR-0024 (Accepted) |
AMEND/CITE: EVOLUTION_GOAL + mapping edges w/ protected-set disposition |
class absent = feature off, no decay hazard |
the new ADR + 0024 delta |
#14422 durability retraction; #14453 OQ1 |
#14433 direction-slot |
armed design note (Clio) |
DR specifies the slot's key grammar; slot stays nullable |
null = unattributed, conserved |
the new ADR |
#14433 comments |
EVOLUTION_GOAL schema |
#14442 Leaf-2 home (BUSINESS_GOAL generalization) |
shared schema, per #14453/#14548 OQ5 cross-verdict (composable, not merged) |
— |
the new ADR |
#14442; #14548 |
Decision Record impact
This ticket CREATES the DR: amends ADR-0028, amends ADR-0024, aligned-with ADR-0023 (earned-scent/notAuthority boundaries).
Acceptance Criteria
Out of Scope
Any implementation (leaves 2–5); OQ7 lattice vocabulary (REQUIRES/ENABLES/THREATENS — reserved for the ladder's own DR).
Related
Parent: Epic #14565. Source: #14453 (closed). ADR-0023/0024/0028 · #14433 · #14442 · #14548 · #14472.
Origin Session ID: a5af7cf6-45a3-42db-8a30-f04f4241a55c
Retrieval Hint: "direction contract ADR deterministic key directionBreakdown windowSemantics conservation fail-open"
Context
Leaf 1 of Epic #14565 (direction-weighted Golden Path), graduated from Discussion #14453. GPT's §5.2 STEP_BACK ask D made the Decision-Record path a graduation blocker: "any SUMMARY_ direction field must cite ADR-0028 and any new graph node/edge class must cite/update ADR-0024"* (DC…17528043). This leaf IS that path, and it sequences FIRST — every other leaf's schema claims derive authority from it.
The Problem
Three authority gaps block implementation: (1) ADR-0028's SUMMARY_* schema is direction-blind by design — per-direction sub-aggregates need an amendment, not a workaround; (2)
EVOLUTION_GOAL(generalizing #14442'sBUSINESS_GOAL) and any direction-mapping edges need ADR-0024 standing — the protected-edge-set lesson from #14422 applies forward: an edge class outside the protected set silently decays and any number built on it rots invisibly; (3) direction identity needs a normative contract or every downstream metric is unfalsifiable.The Architectural Reality
learn/agentos/decisions/0028-*.md— §2.3 single deterministic aggregation lane (no second writer), §2.4 SUMMARY_* fields, §2.6 partitions. ThedirectionBreakdownmap +windowSemanticsfilter-set declaration extend §2.4; the single-lane invariant is untouched.learn/agentos/decisions/0024-*.md— node/edge vocabulary +PROTECTED_EDGE_TYPES+ decay semantics + §2.9 honesty boundary (the non-blocking-dependency precedent this epic reuses for the #14503 cold-start sibling).ai/services/graph/—canonicalizeConceptIdconcept-spine (merged); all direction-concept references route through it (#14453 OQ1 AC).The Fix
One ADR document (
learn/agentos/decisions/, next free number) specifying: (a) the deterministic direction-key contract —EVOLUTION_GOALid ORcluster-id+mappingVersion, append-only mapping history, LLM labels never identity; (b) thedirectionBreakdownfield spec on L1/L2 records ({"<directionKey>@<mappingVersion>": share}, one record per window, side-table fallback at the >20%-of-record-bytes cardinality probe); (c)windowSemanticsfilter-set declaration + the falsifier-symmetry rule (same filters + same version pin on measurement AND falsifying query; cross-filter-set comparison = type error); (d) the conservation invariantΣ_D v_D + v_UNATTRIBUTED = v_totalas a build-time check with UNATTRIBUTED as first-class fail-open pool; (e) the fail-open additive HARD AC (direction never gates the base route; routed-nodes-0 class preserved); (f)EVOLUTION_GOALnode class + mapping-edge classes with their ADR-0024 protected-set disposition; (g) the OQ6 producer/consumer boundary map (×6, from the graduated body) as the DR's consumer section.Contract Ledger Matrix
directionBreakdown,windowSemantics.filterSetsEVOLUTION_GOAL+ mapping edges w/ protected-set disposition#14433direction-slotEVOLUTION_GOALschemaBUSINESS_GOALgeneralization)Decision Record impact
This ticket CREATES the DR:
amends ADR-0028,amends ADR-0024,aligned-with ADR-0023(earned-scent/notAuthority boundaries).Acceptance Criteria
f2c62c33).Out of Scope
Any implementation (leaves 2–5); OQ7 lattice vocabulary (
REQUIRES/ENABLES/THREATENS— reserved for the ladder's own DR).Related
Parent: Epic #14565. Source: #14453 (closed). ADR-0023/0024/0028 · #14433 · #14442 · #14548 · #14472.
Origin Session ID: a5af7cf6-45a3-42db-8a30-f04f4241a55c Retrieval Hint: "direction contract ADR deterministic key directionBreakdown windowSemantics conservation fail-open"