feat(graph): convergence-snapshot canonical-id schema + firewalled render-target (#14633) (#14679)

neo-opus-ada · tobiu · Ada (Claude Opus 4.8) · web-flow · commit f20edbc46385 · 2026-07-04T06:36:24.000+02:00
* feat(graph): convergence-snapshot canonical-id schema + firewalled render-target (#14633) Leaf 1 (foundation) of epic #14581 (Convergence-weighted Golden Path). Defines the CONVERGENCE_SNAPSHOT node schema keyed on CANONICAL concept ids (reuses the shipped normalizeConceptKey policy, never re-derived) recording id provenance (OQ1); resolves the render-target to a notAuthority, non-boot-consumable terrain ledger (OQ8 self-fulfilling firewall); binds the shipped four-axis CONTRACT_AXES kept SEPARATE, never flattened; carries the risk-node flag + the born-scheduled longitudinal falsifier (remeasureAt). convergenceWeight + independenceBudget are declared-but-null (Leaf 2 #14634 fills them; the builder never invents a weight). ADR-0024 disposition: additive/fail-open + DECAYING (re-derivable read, not durable authority) — excluded from PROTECTED_EDGE_TYPES. EVOLUTION_GOAL binding is an explicit unresolved stub (#14565 / PR #14626 unmerged), reconciled when it lands. 7 unit tests green. Co-Authored-By: Ada (Claude Opus 4.8) <ada@neomjs.dev> * docs(adr): register CONVERGENCE_SNAPSHOT node class in ADR-0024 §2.2 (#14633) Addresses the cross-family review RC (Euclid): a new node class must be registered in ADR-0024's model ledger, not only in the module JSDoc. Adds an ADR-0024 §2.2 amendment note (mirroring the ADR-0033 EVOLUTION_GOAL precedent) registering CONVERGENCE_SNAPSHOT + its disposition: additive, fail-open, re-derivable, render-only/human-facing, NOT durable authority, node-side non-protected (DECAYING). Node writes + the post-sync integrity canary land with the compute leaf; this leaf is schema-only. Also fixes the module JSDoc's imprecise 'excluded from PROTECTED_EDGE_TYPES' — that enum governs EDGE facts, not node-class membership; the two are orthogonal (per the RC's wording ask). Co-Authored-By: Ada (Claude Opus 4.8) <ada@neomjs.dev> --------- Co-authored-by: tobiu <tobiasuhlig78@gmail.com> Co-authored-by: Ada (Claude Opus 4.8) <ada@neomjs.dev>
diff --git a/ai/services/graph/convergenceSnapshotSchema.mjs b/ai/services/graph/convergenceSnapshotSchema.mjs
@@ -0,0 +1,120 @@
+import {normalizeConceptKey} from './conceptSpineCanonicalization.mjs';
+import {CONTRACT_AXES}       from './conceptNeighborhoodProbe.mjs';
+
+/**
+ * @module ai/services/graph/convergenceSnapshotSchema
+ * @summary Convergence-weighted Golden Path — canonical-id snapshot node schema + firewalled render-target (#14633; ticket-ref-ok: owning-leaf anchor).
+ *
+ * Foundation leaf of epic #14581 (ticket-ref-ok: parent-epic anchor). A convergence snapshot annotates a
+ * goal→sub-goal lattice node with how invariant it is across imagined futures ("structure not events" —
+ * the sub-goals worth doing regardless of which future wins). This module defines ONLY the node schema
+ * plus the two firewall-critical resolutions; the compute (Leaf 2) and the human render-ledger
+ * (Leaf 3) build on it.
+ *
+ * Two hazards are closed at the schema layer:
+ *   - **OQ1 node-identity drift:** every snapshot keys on a CANONICAL concept id (via the shipped
+ *     `normalizeConceptKey` policy — reused, never re-derived) and records that id's provenance.
+ *   - **OQ8 self-fulfilling firewall:** the render-target resolves to a surface NO agent boot-path
+ *     consumes (`resolveRenderTarget`) — decision-support for humans, invisible to future-generation.
+ *
+ * Four-axis contract: annotations bind the shipped `CONTRACT_AXES` (authority / fidelity /
+ * extractionProvenance / lifecycle) from the concept-graph measurement floor — the four axes stay
+ * SEPARATE, never flattened to a composite score.
+ *
+ * ADR-0024 disposition (native-edge-graph-model; ticket-ref-ok: leaf-AC decay anchor; registered in ADR-0024 §2.2):
+ * the `CONVERGENCE_SNAPSHOT` node class is ADDITIVE, FAIL-OPEN, re-derivable, and render-only / human-facing —
+ * a read over the goal→sub-goal lattice, NOT durable authority. It is therefore **node-side non-protected
+ * (DECAYING)**: a snapshot stale past its `remeasureAt` is discarded and recomputed, never trusted.
+ * (`PROTECTED_EDGE_TYPES` governs EDGE facts, not node-class membership — the two are orthogonal.)
+ *
+ * EVOLUTION_GOAL binding: the shared `EVOLUTION_GOAL` schema (from the sibling direction chain) is
+ * unmerged at this leaf's authoring, so the snapshot references it through `EVOLUTION_GOAL_SCHEMA_REF`
+ * — a stub bound to the epic contract, reconciled to the real export when the sibling chain lands.
+ */
+
+export const CONVERGENCE_SNAPSHOT_NODE_TYPE = 'CONVERGENCE_SNAPSHOT';
+
+/**
+ * Stub reference to the shared `EVOLUTION_GOAL` schema (#14565 / PR #14626, unmerged; ticket-ref-ok: cross-lane dependency anchor).
+ * The snapshot only needs the goal-id contract, which the epic fixes; reconcile `resolved` + a real
+ * import when the sibling chain merges.
+ */
+export const EVOLUTION_GOAL_SCHEMA_REF = Object.freeze({
+    ref     : 'EVOLUTION_GOAL',
+    resolved: false,
+    contract: 'canonical goal/sub-goal id + declared-intent axis (shared with the #14565 direction chain)'
+});
+
+/**
+ * @summary The firewalled render-target for convergence output (OQ8). Resolves to a standalone ledger
+ * artifact that NO agent boot-path consumes — the long-run home is the FM-cockpit terrain panel (a
+ * surface agents never boot from). The redaction-filter branch is the reserved fallback, documented
+ * not built.
+ * @returns {Object} frozen `{target, notAuthority, agentBootConsumable, home, fallback}`.
+ */
+export function resolveRenderTarget() {
+    return Object.freeze({
+        target             : 'convergence-terrain-ledger',
+        notAuthority       : true,
+        agentBootConsumable: false,
+        home               : 'fm-cockpit-terrain-panel',
+        fallback           : 'redaction-filter'
+    });
+}
+
+/**
+ * @summary Projects an axis payload onto the four-axis contract, keeping the axes SEPARATE (never a
+ * composite score). Unknown axis keys are dropped; only the four `CONTRACT_AXES` names are retained.
+ * @param {Object} [axes] Caller axis payload keyed by axis name.
+ * @returns {Object} present axes only, among `{authority, fidelity, extractionProvenance, lifecycle}`.
+ */
+export function pickContractAxes(axes = {}) {
+    const out = {};
+
+    for (const axis of Object.keys(CONTRACT_AXES)) {
+        if (axes && axes[axis] !== undefined) {
+            out[axis] = axes[axis];
+        }
+    }
+
+    return out;
+}
+
+/**
+ * @summary Builds a convergence-snapshot node keyed on the CANONICAL concept id of the lattice node it
+ * annotates. Records id provenance (OQ1 — recorded, never invented), the four-axis annotations (never
+ * flattened), the risk-node flag, and the born-scheduled longitudinal falsifier (`remeasureAt`). The
+ * `convergenceWeight` + `independenceBudget` fields are declared but left `null` — the Leaf 2 compute
+ * fills them; this builder never invents a weight.
+ *
+ * @param {Object}  input
+ * @param {String}  input.latticeNodeId    Raw goal/sub-goal id to annotate (canonicalized here).
+ * @param {String}  input.provenance       How the canonical id was derived (OQ1 — recorded verbatim).
+ * @param {Boolean} [input.riskNode=false] Risk-node annotation.
+ * @param {String}  [input.remeasureAt]    ISO time of the born-scheduled longitudinal re-measurement.
+ * @param {Object}  [input.axes]           Four-axis annotations keyed by `CONTRACT_AXES` axis name.
+ * @param {String}  [input.now]            ISO clock injection for deterministic tests.
+ * @returns {Object|null} the snapshot node record, or `null` when the id does not canonicalize.
+ */
+export function buildConvergenceSnapshotNode({latticeNodeId, provenance, riskNode = false, remeasureAt, axes, now} = {}) {
+    const canonicalId = normalizeConceptKey(latticeNodeId);
+
+    if (!canonicalId) return null;
+
+    return {
+        type      : CONVERGENCE_SNAPSHOT_NODE_TYPE,
+        id        : `${CONVERGENCE_SNAPSHOT_NODE_TYPE}:${canonicalId}`,
+        properties: {
+            canonicalId,
+            provenance        : provenance || null,
+            riskNode          : riskNode === true,
+            remeasureAt       : remeasureAt || null,
+            convergenceWeight : null,
+            independenceBudget: null,
+            axes              : pickContractAxes(axes),
+            renderTarget      : resolveRenderTarget().target,
+            evolutionGoalRef  : EVOLUTION_GOAL_SCHEMA_REF.ref,
+            createdAt         : now || null
+        }
+    };
+}
diff --git a/learn/agentos/decisions/0024-native-edge-graph-model.md b/learn/agentos/decisions/0024-native-edge-graph-model.md
@@ -66,6 +66,16 @@ Four named enums (`CONCEPT_EDGE_TYPES`, `ADR_EDGE_TYPES`, `PROTECTED_EDGE_TYPES`
 > PR per this record's own re-review trigger; new node classes ship with the post-sync integrity
 > canary.
 
+> **Amended by #14633 (Convergence-weighted GP, Leaf 1 of #14581):** registers the `CONVERGENCE_SNAPSHOT`
+> node class (`ai/services/graph/convergenceSnapshotSchema.mjs`) — the convergence-terrain sibling of the
+> ADR-0033 `EVOLUTION_GOAL` chain. Disposition: **additive, fail-open, re-derivable** (a read over the
+> goal→sub-goal lattice, not durable authority) and **render-only / human-facing** (its render-target is a
+> `notAuthority` terrain ledger no agent boot-path consumes). It is therefore **node-side non-protected —
+> DECAYING**: a snapshot stale past its `remeasureAt` is discarded and recomputed, never trusted. This is a
+> NODE-class disposition; `PROTECTED_EDGE_TYPES` (§2.3) governs EDGE facts, not node-class membership — the
+> two are orthogonal. Node writes + the post-sync integrity canary land with the compute leaf (#14634); this
+> leaf defines the schema only.
+
 ### 2.4 Topology — how it connects
 
 ```mermaid
diff --git a/test/playwright/unit/ai/services/graph/convergenceSnapshotSchema.spec.mjs b/test/playwright/unit/ai/services/graph/convergenceSnapshotSchema.spec.mjs
@@ -0,0 +1,86 @@
+import {test, expect} from '@playwright/test';
+
+import {
+    CONVERGENCE_SNAPSHOT_NODE_TYPE,
+    EVOLUTION_GOAL_SCHEMA_REF,
+    buildConvergenceSnapshotNode,
+    pickContractAxes,
+    resolveRenderTarget
+} from '../../../../../../ai/services/graph/convergenceSnapshotSchema.mjs';
+
+test.describe('convergenceSnapshotSchema', () => {
+    test('keys the snapshot on the CANONICAL concept id + records provenance, never inventing a weight (OQ1)', () => {
+        const node = buildConvergenceSnapshotNode({
+            latticeNodeId: 'CONCEPT:GoldenPath',
+            provenance   : 'lattice-import:2026-07-04',
+            now          : '2026-07-04T00:00:00.000Z'
+        });
+
+        expect(node.type).toBe('CONVERGENCE_SNAPSHOT');
+        expect(node.id).toBe('CONVERGENCE_SNAPSHOT:golden-path');
+        expect(node.properties.canonicalId).toBe('golden-path');
+        expect(node.properties.provenance).toBe('lattice-import:2026-07-04');
+        // Leaf 2 compute fills these — the schema builder must never invent a weight.
+        expect(node.properties.convergenceWeight).toBeNull();
+        expect(node.properties.independenceBudget).toBeNull();
+        expect(node.properties.createdAt).toBe('2026-07-04T00:00:00.000Z');
+    });
+
+    test('carries the risk-node flag + the born-scheduled longitudinal falsifier', () => {
+        const node = buildConvergenceSnapshotNode({
+            latticeNodeId: 'first-revenue',
+            provenance   : 'p',
+            riskNode     : true,
+            remeasureAt  : '2026-08-04T00:00:00.000Z'
+        });
+
+        expect(node.properties.riskNode).toBe(true);
+        expect(node.properties.remeasureAt).toBe('2026-08-04T00:00:00.000Z');
+    });
+
+    test('defaults are honest: no risk, no schedule, null provenance — nothing fabricated', () => {
+        const node = buildConvergenceSnapshotNode({latticeNodeId: 'x'});
+
+        expect(node.properties.riskNode).toBe(false);
+        expect(node.properties.remeasureAt).toBeNull();
+        expect(node.properties.provenance).toBeNull();
+    });
+
+    test('keeps the four axes SEPARATE — never flattened, unknown axes dropped', () => {
+        const axes = pickContractAxes({
+            authority           : {trustTier: 'system'},
+            fidelity            : {sourceTier: 'curated'},
+            extractionProvenance: {curated: true},
+            lifecycle           : {state: 'candidate'},
+            composite           : 0.87  // a flattened score must NOT survive
+        });
+
+        expect(Object.keys(axes).sort()).toEqual(['authority', 'extractionProvenance', 'fidelity', 'lifecycle']);
+        expect(axes).not.toHaveProperty('composite');
+        expect(axes.lifecycle).toEqual({state: 'candidate'});
+    });
+
+    test('render-target is firewalled (OQ8): notAuthority, NOT agent-boot-consumable, FM-cockpit home', () => {
+        const target = resolveRenderTarget();
+
+        expect(target.target).toBe('convergence-terrain-ledger');
+        expect(target.notAuthority).toBe(true);
+        expect(target.agentBootConsumable).toBe(false);
+        expect(target.home).toBe('fm-cockpit-terrain-panel');
+        expect(target.fallback).toBe('redaction-filter');
+        // The built node's render-target must be the firewalled ledger, not a boot-path surface.
+        expect(buildConvergenceSnapshotNode({latticeNodeId: 'y'}).properties.renderTarget).toBe('convergence-terrain-ledger');
+    });
+
+    test('returns null when the lattice id does not canonicalize (no phantom snapshot)', () => {
+        expect(buildConvergenceSnapshotNode({latticeNodeId: ''})).toBeNull();
+        expect(buildConvergenceSnapshotNode({latticeNodeId: '###'})).toBeNull();
+        expect(buildConvergenceSnapshotNode({})).toBeNull();
+    });
+
+    test('EVOLUTION_GOAL binding is an explicit unresolved stub (#14626 unmerged), reconciled later', () => {
+        expect(EVOLUTION_GOAL_SCHEMA_REF.ref).toBe('EVOLUTION_GOAL');
+        expect(EVOLUTION_GOAL_SCHEMA_REF.resolved).toBe(false);
+        expect(buildConvergenceSnapshotNode({latticeNodeId: 'z'}).properties.evolutionGoalRef).toBe('EVOLUTION_GOAL');
+    });
+});
