SDK relationship graph primitives and lifecycle semantics

.agents/pm/decisions/pm-4jqm.toon

@@ -2,11 +2,12 @@ id: pm-4jqm
 title: "ADR: relationship graph semantics — typed directional, ordering, provenance, evidence, and associative edges with schema-extensible invariants"
 description: "Decide the durable relationship model that distinguishes execution ordering from hierarchy, provenance, evidence, and relevance while permitting domain-specific edge kinds."
 type: Decision
-status: open
+status: closed
 priority: 1
 tags[6]: adr,"area:graph","area:sdk",decision-needed,relationships,schema
 created_at: "2026-07-13T21:57:26.030Z"
-updated_at: "2026-07-13T21:57:26.030Z"
+updated_at: "2026-07-14T07:46:49.297Z"
+closed_at: "2026-07-14T07:46:31.979Z"
 author: codex-root
 estimated_minutes: 180
 acceptance_criteria: "Context and drivers inventory current parent, child, blocks, blocked_by, discovered_from, incident_from, related, and related_to behavior; Alternatives compare fixed enums, extension registries, generic labeled property graphs, event-derived edges, and a hybrid registry; The decision specifies direction, inverse materialization, order-bearing and associative classification, cardinality, payload schema, authorship, timestamps, confidence, and source evidence; Compatibility rules cover legacy aliases, unknown custom kinds, import and export, merge and federation, schema versioning, and rollback; Validation rules define dangling endpoints, self-edges, duplicate canonical edges, order-only cycles, inverse consistency, stale evidence, and safe remediation; Human review records the chosen alternative, consequences, migration path, and explicit non-goals before implementation starts"
@@ -19,12 +20,25 @@ why_now: "The tracker already contains related and related_to drift, parent and
 parent: pm-96h7
 risk: medium
 confidence: medium
+resolution: Adopt hybrid versioned relationship registry plus immutable source events and rebuildable indexes.
+expected_result: Accepted relationship semantics ADR with compatibility and validation rules.
+actual_result: ADR documented and enforced by the public registry and tests.
 dependencies[5]{id,kind,created_at,author,source_kind}:
   pm-6irg,related,"2026-07-13T21:57:26.030Z",null,null
   pm-96h7,related,"2026-07-13T21:57:26.030Z",null,null
   pm-9x6k,related,"2026-07-13T21:57:26.030Z",null,null
   pm-a859,related,"2026-07-13T21:57:26.030Z",null,null
   pm-zwpp,related,"2026-07-13T21:57:26.030Z",null,null
-comments[1]{created_at,author,text}:
+comments[2]{created_at,author,text}:
   "2026-07-13T21:57:26.030Z",codex-root,"Duplicate check 2026-07-13: all-status searches found dependency validation and visualization decisions but no ADR that classifies relationship kinds by graph semantics and defines a schema-extensible registry; this is the decision gate for pm-96h7."
+  "2026-07-14T07:46:27.742Z",codex-gpt5-root,"Decision evidence: accepted hybrid registry plus immutable events plus rebuildable indexes, documented alternatives, semantics, aliases, compatibility/migration/federation/rollback, validation invariants, consequences, and non-goals in docs/RELATIONSHIP_GRAPH.md; the executable registry and 100% covered tests enforce the decision."
+files[1]{path,scope,note}:
+  src/sdk/relationships.ts,project,executable registry contract implements accepted ontology
+tests[1]{command,scope,timeout_seconds}:
+  node scripts/run-tests.mjs test -- tests/unit/sdk/relationships.spec.ts,project,180
+test_runs[1]{run_id,kind,status,started_at,finished_at,recorded_at,passed,failed,skipped}:
+  test-local-mrkckkmi-06nqm1,test,passed,"2026-07-14T07:46:01.383Z","2026-07-14T07:46:11.946Z","2026-07-14T07:46:11.946Z",1,0,0
+docs[1]{path,scope,note}:
+  docs/RELATIONSHIP_GRAPH.md,project,relationship graph ADR
+close_reason: Accepted and implemented the hybrid relationship registry plus immutable-source/rebuildable-index ADR with executable invariants and public documentation.
 body: "## Decision question\n\nWhat relationship contract lets pm represent project execution, knowledge provenance, evidence, organizational structure, domain models, and future non-PM graphs without confusing an associative connection with a prerequisite?\n\n## Drivers\n\nCorrect graph algorithms; immutable and attributable mutations; SDK-first extensibility; backward compatibility; shell-friendly interchange; bounded context assembly; federation; point-in-time replay; and small-project simplicity.\n\n## Alternatives to evaluate\n\n1. Closed built-in enum only.\n2. Extension-registered kinds with a stable built-in core.\n3. Generic property-graph labels with runtime validation.\n4. Relationships derived only from immutable events.\n5. Hybrid registry plus immutable relationship events and materialized indexes.\n\n## Proposed vocabulary dimensions\n\nEach kind declares direction, optional inverse, whether it participates in ordering or hierarchy, allowed endpoint types or statuses, cardinality, payload schema, dedupe identity, lifecycle policy, visibility, confidence and evidence requirements, and compatibility aliases.\n\nThis item intentionally remains open until a maintainer accepts or rejects the decision."

.agents/pm/extensions/.managed-extensions.json

@@ -1,26 +1,27 @@
 {
   "version": 1,
-  "updated_at": "2026-07-14T06:56:26.525Z",
+  "updated_at": "2026-07-14T09:23:55.581Z",
   "entries": [
     {
       "name": "pm-changelog",
       "directory": "pm-changelog",
       "scope": "project",
-      "manifest_version": "2026.7.14-1",
+      "manifest_version": "2026.7.14-2",
       "manifest_entry": "./dist/extension.js",
       "capabilities": [
         "commands",
         "importers",
+        "renderers",
         "schema"
       ],
       "installed_at": "2026-05-23T20:26:03.509Z",
-      "updated_at": "2026-07-14T02:21:54.786Z",
+      "updated_at": "2026-07-14T09:23:50.211Z",
       "source": {
         "kind": "npm",
         "input": "npm:pm-changelog",
         "location": "package",
         "package": "pm-changelog",
-        "version": "2026.7.14-1"
+        "version": "2026.7.14-2"
       }
     }
   ]

.agents/pm/features/pm-ju83.toon

@@ -6,7 +6,7 @@ status: open
 priority: 1
 tags[6]: api,"area:graph","area:sdk",performance,relationships,sdk-first
 created_at: "2026-07-13T21:58:11.171Z"
-updated_at: "2026-07-13T21:58:11.171Z"
+updated_at: "2026-07-14T09:23:46.454Z"
 author: codex-root
 estimated_minutes: 720
 acceptance_criteria: "The registry defines built-in and extension-provided kinds with direction, inverse, order-bearing and hierarchy flags, cardinality, payload schema, lifecycle, aliases, and compatibility version; Mutation APIs validate endpoints and invariants then append attributable immutable events without direct state rewrites; Read APIs cover adjacency, predecessors, successors, ancestors, descendants, shortest and constrained paths, transitive closure, reverse impact, and induced bounded subgraphs; Every query supports deterministic ordering, typed filters, field projection, cursor or streaming continuation, cancellation, snapshot selection, and explicit cost or truncation metadata; Indexes are rebuildable from history, incrementally maintained, crash safe, observable, and optional for small projects; Thin CLI and MCP adapters call public SDK APIs without hidden core imports; shell-safe JSON, JSONL, TOON, and counts-first outputs preserve pipeline composability; Contract, property, replay, concurrency, migration, and scale tests cover legacy kinds, custom kinds, cycles, snapshots, and one million items"
@@ -25,6 +25,25 @@ dependencies[5]{id,kind,created_at,author,source_kind}:
   pm-8xr8,related,"2026-07-13T21:58:11.171Z",null,null
   pm-usfg,related,"2026-07-13T21:58:11.171Z",null,null
   pm-zwpp,blocked_by,"2026-07-13T21:58:11.171Z",null,null
-comments[1]{created_at,author,text}:
+comments[8]{created_at,author,text}:
   "2026-07-13T21:58:11.171Z",codex-root,"Duplicate check 2026-07-13: SDK-first inventory contains generic query and lifecycle promotion slices but no stable typed relationship registry plus bounded graph algorithm API; this is a new promotion slice under pm-96h7 and relates to pm-usfg."
+  "2026-07-14T07:46:26.495Z",codex-gpt5-root,"Evidence: delivered the first broad public graph foundation: versioned built-in/custom relationship registry, alias compatibility, immutable in-memory index construction from item metadata, deterministic adjacency/closure/reverse-impact/shortest-path/subgraph queries with cancellation and explicit cost/truncation metadata, SDK barrel/docs, and validate integration. Packed tarball consumer proved a custom company owns graph plus real CLI lifecycle. Full repository run passed 286 files/5664 tests; focused all-source coverage for relationships.ts is 100/100/100/100. Remaining event mutation, durable incremental index, snapshot/streaming, MCP projection, and million-item scale acceptance stay on this feature, so it will return to open rather than be falsely closed."
+  "2026-07-14T08:15:26.847Z",codex-root,"PR #554 review evidence: addressed all ten first-round findings across construction complexity/performance, bounded closure/path truncation, malformed/custom lifecycle dependencies, immutable payload schemas, canonical dependency conversion, inverse-kind filters, generated changelog accuracy, and duplicate-edge documentation. Focused relationship coverage is exact 100/100/100/100; full repository run passed 286 files and 5664 tests before the final single branch regression was added. The broader durable event/index acceptance remains open."
+  "2026-07-14T08:27:50.810Z",codex-root,"PR #554 second-round evidence: deduplicated bidirectional candidate accounting, changed induced subgraph assembly from whole-graph O(E) filtering to bounded adjacency-index work, enforced alias identifiers, and restored the no-guessing contract for unregistered dependency kinds. Registered custom ordering remains supported by the SDK registry; CLI extension-registry injection belongs to the remaining adapter acceptance. Focused tests pass 95/95, relationship coverage is exact 100/100/100/100, ESLint and build pass."
+  "2026-07-14T08:39:28.907Z",codex-root,"PR #554 third-round evidence: registry resolution, graph nodes/endpoints, and item-derived relationships now defend malformed runtime input with precise behavior; item references normalize whitespace while preserving canonical case-sensitive identifiers. Lifecycle graph construction accepts an injected RelationshipKindRegistry, with tests proving custom ordering kinds participate and custom associative kinds do not. Focused relationship coverage is exact 100/100/100/100; 95 focused tests, ESLint, and build pass."
+  "2026-07-14T08:48:53.052Z",codex-root,"PR #554 fourth-round evidence: closure and shortest-path visitedNodes now count dequeued frontier nodes, max-depth truncation inspects and counts only unseen reachable work, and induced subgraphs apply canonical/inverse kind filters during indexed edge reconstruction. Relationship coverage remains exact 100/100/100/100; focused tests, ESLint, and build pass."
+  "2026-07-14T09:00:21.525Z",codex-root,"PR #554 fifth-round evidence: payload schema freezing is cycle-safe, inverse identifiers normalize and validate with the registry grammar, adjacency avoids duplicate uniqueness work, and BFS resolves neighbors once per dequeued node while checking limits before visit marking. Relationship coverage remains exact 100/100/100/100; ESLint and build pass."
+  "2026-07-14T09:23:45.257Z",codex-root,"PR #554 final-round evidence: shortestPath now uses a parent map and reconstructs only the winning route, reducing traversal state to O(V) while preserving case-sensitive item identity; schema freeze assertions now fail on missing structure. Focused 95 tests pass, relationship coverage is exact 100/100/100/100, ESLint and build pass."
+learnings[1]{created_at,author,text}:
+  "2026-07-14T07:46:27.146Z",codex-gpt5-root,"A storage-independent relationship registry is the semantic boundary: algorithms must consume ordering/hierarchy flags rather than infer meaning from labels, while durable event/index implementations can remain interchangeable."
+files[2]{path,scope,note}:
+  src/sdk/index.ts,project,public SDK barrel export
+  src/sdk/relationships.ts,project,public relationship ontology and bounded graph query kernel
+tests[1]{command,scope,timeout_seconds}:
+  node scripts/run-tests.mjs test -- tests/unit/sdk/relationships.spec.ts,project,180
+test_runs[1]{run_id,kind,status,started_at,finished_at,recorded_at,passed,failed,skipped}:
+  test-local-mrkckbng-g4g06q,test,passed,"2026-07-14T07:45:49.811Z","2026-07-14T07:46:00.316Z","2026-07-14T07:46:00.316Z",1,0,0
+docs[2]{path,scope,note}:
+  docs/RELATIONSHIP_GRAPH.md,project,executable relationship semantics and compatibility decision
+  docs/SDK.md,project,public SDK relationship graph reference
 body: "## Public surface\n\n- RelationshipKindRegistry and schema validation.\n- Append, remove or supersede, and inspect relationship events.\n- Snapshot-aware graph reader and index interfaces.\n- Bounded adjacency, path, closure, impact, and subgraph queries.\n- Explain and cost metadata suitable for token-aware context selection.\n- Import, export, merge, and extension hooks built from the same contract.\n\n## Non-goals\n\nThis item does not choose product-specific relevance weights, silently invent relationships, or force large indexes on scratch projects. Those belong to context-engine policy, audits, and adaptive storage layers."