pi-mega-compact 0.19.1 → 0.19.2

package/dist/config/vector-cortex.js

@@ -101,6 +101,15 @@ export const VC2C_ENABLED = () => sprintFlag("MEGACOMPACT_VC2C");
  * cortex rebuild/admin seam and the reader-only topology summary seam.
  */
 export const VC3A_ENABLED = () => sprintFlag("MEGACOMPACT_VC3A");
+/**
+ * VC3B — deterministic cortical topology (TopologyV1 / EdgeV1).
+ * Default ON. `MEGACOMPACT_VC3B=0` disables and is byte-identical to the
+ * predecessor (mode C: no topology graph is built or emitted, the dashboard
+ * topology view returns the VC3A-precise aggregation shape with no node/edge
+ * arrays, zero `vector_cortex_topology_*` emissions). The real consumers are
+ * the topology build seam (build.ts) and the dashboard topology node/edge view.
+ */
+export const VC3B_ENABLED = () => sprintFlag("MEGACOMPACT_VC3B");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -144,6 +144,7 @@ export const SETTINGS = [
             boolDirect("MEGACOMPACT_VC2B", "VC2B Multi-Head Encoder", "VectorSetV1 five L2-normalized heads (384/128/128/64/32) with head-calibration draft + asset-free trigram B (512d) and lexical C fallbacks, plus the per-head emit seam. OFF = mode C, no per-head vectors emitted, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC2C", "VC2C Encoder Qualification + Calibration", "QualifiedEncoderV1/CalibrationV1: calibration fit on the calibration split only (held-out labels prohibited) + atomic selection across MODEL_ASSET and per-head EVALUATION thresholds (any field failure demotes all of A). OFF = mode C, no qualification/calibration selection, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC3A", "VC3A Cortex Store", "Capability-gated derived cortex store (CortexReader/Writer/Admin + CortexRecordV1): additive, keyed (sourceHighWater, algorithmVersion, id), immutable records, deterministic generation rebuild + one root digest. OFF = mode C, no cortex records written, byte-identical predecessor.", true),
+            boolDirect("MEGACOMPACT_VC3B", "VC3B Deterministic Topology", "Deterministic cortical topology (TopologyV1/EdgeV1): per-(source,head) top-k=16/head calibrated-threshold edges, stable score-desc/then-target-ID sort, dependency directed + contradiction symmetric paired records, one stable generation digest. OFF = mode C, no topology graph built/emitted, predecessor-precise topology view, byte-identical predecessor.", true),
         ],
     },
     {

package/dist/extensions/dashboard-server/routes-vector-cortex-topology.js

@@ -1,6 +1,6 @@
 /**
- * dashboard-server/routes-vector-cortex-topology.ts — VC3A vector-cortex topology
- * dashboard route.
+ * dashboard-server/routes-vector-cortex-topology.ts — VC3A/VC3B vector-cortex
+ * topology dashboard route.
  *
  * Reader-only GET /api/vector-cortex/topology built ENTIRELY on the CortexReader
  * capability: opens the isolated cortex DB for this repo's state dir and returns
@@ -10,14 +10,26 @@
  * (no writer/admin leakage). Non-fatal: a missing or corrupt cortex DB degrades
  * to `enabled:false`.
  *
+ * VC3B adds the deterministic node/edge shapes (TopologyV1) when both VC3A and
+ * VC3B are enabled: the accepted derived records of kind "topology" that carry a
+ * canonical TopologyCandidate JSON payload are fed through the deterministic
+ * build (buildTopologyGraph), whose stable generation digest + sorted node/edge
+ * arrays are returned. Bad/unparseable records are skipped (PREVENT-001), and
+ * with VC3B off the node/edge fields are omitted entirely — byte-identical to
+ * the VC3A predecessor view.
+ *
  * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
  * `any`), reader-only aggregate.
  */
-import { VC3A_ENABLED } from "../../src/config.js";
+import { VC3A_ENABLED, VC3B_ENABLED } from "../../src/config.js";
+import { Logger } from "../../src/log.js";
 import { createCortexStore } from "../../src/vector-cortex/cortex/store.js";
+import { buildTopologyGraph } from "../../src/vector-cortex/topology/index.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
+/** Well-known cortex record kind that carries a canonical candidate payload. */
+const TOPOLOGY_RECORD_KIND = "topology";
 /**
- * Reader-only GET /api/vector-cortex/topology (VC3A).
+ * Reader-only GET /api/vector-cortex/topology (VC3A + VC3B node/edge shapes).
  */
 export function handleVectorCortexTopology(req, res, ctx) {
     const url = req.url ?? "";
@@ -30,13 +42,18 @@ export function handleVectorCortexTopology(req, res, ctx) {
         return true;
     }
     const enabled = VC3A_ENABLED();
+    const topologyEnabled = VC3B_ENABLED();
     let active = enabled;
     let summary = { generationId: null, rootDigest: null, sourceHighWater: "0", recordCount: 0, ordinal: null };
+    let nodes;
+    let edges;
+    let generationDigest;
     if (enabled) {
         try {
             const store = createCortexStore({ stateDir: ctx.stateDir });
             try {
-                const s = store.reader().topologySummary();
+                const reader = store.reader();
+                const s = reader.topologySummary();
                 summary = {
                     generationId: s.generationId,
                     rootDigest: s.rootDigest,
@@ -44,6 +61,12 @@ export function handleVectorCortexTopology(req, res, ctx) {
                     recordCount: s.recordCount,
                     ordinal: s.ordinal,
                 };
+                if (topologyEnabled) {
+                    const built = buildFromRecords(reader.readRecords());
+                    nodes = built.nodes;
+                    edges = built.edges;
+                    generationDigest = built.generationDigest;
+                }
             }
             finally {
                 store.close();
@@ -61,8 +84,125 @@ export function handleVectorCortexTopology(req, res, ctx) {
         sourceHighWater: summary.sourceHighWater,
         recordCount: summary.recordCount,
         ordinal: summary.ordinal,
+        ...(topologyEnabled
+            ? { nodes, edges, generationDigest }
+            : {}),
         updatedAt: new Date().toISOString(),
     };
     sendJson(res, 200, body);
     return true;
 }
+/**
+ * Reconstruct the deterministic topology graph from the accepted derived records
+ * (reader-only, best-effort). Only records of kind "topology" whose payload is a
+ * canonical TopologyCandidate JSON are consumed; everything else is ignored.
+ * Returns empty arrays + null digest when no valid candidates are stored.
+ *
+ * The build seam is invoked with a logger-derived emit so the VC3B observability
+ * events (`vector_cortex_topology_built` / `vector_cortex_topology_edge_rejected`)
+ * fire on this production path — not just under unit tests. Best-effort and
+ * non-fatal: a failing emitter never breaks the agent loop.
+ *
+ * Q04 — DIVERGENCE RISK (documented, currently latent): the build is invoked
+ * with a hardcoded `threshold: 0` (plus `sessionId: "dashboard"` and
+ * `sourceHighWater: 0n`). This reflects the VC3B state where no production
+ * writer emits calibrated-threshold candidates yet, so retaining ALL stored
+ * "topology" records is correct for now. Once a real calibrated-threshold
+ * producer lands (VC3C), this dashboard digest will NOT derive from the
+ * authoritative threshold and can diverge from the canonical build for the same
+ * stored candidate set. The calibrated threshold must then be threaded through
+ * (e.g. sourced from the authority/config, not zero) before this route is treated
+ * as authoritative. Until then the route is explicitly best-effort display only.
+ */
+function buildFromRecords(records) {
+    const candidates = [];
+    for (const r of records) {
+        if (r.kind !== TOPOLOGY_RECORD_KIND)
+            continue;
+        const parsed = parseCandidatePayload(r);
+        if (parsed)
+            candidates.push(parsed);
+    }
+    const result = buildTopologyGraph({ sessionId: "dashboard", sourceHighWater: 0n, threshold: 0, candidates }, topologyEmit);
+    if (!result.ok)
+        return { nodes: [], edges: [], generationDigest: null };
+    return {
+        nodes: result.topology.nodes.map((n) => ({ id: n.id, kind: n.kind })),
+        edges: result.topology.edges.map((e) => ({
+            source: e.source,
+            target: e.target,
+            head: e.head,
+            score: e.score,
+            direction: e.direction,
+        })),
+        generationDigest: result.topology.generationDigest,
+    };
+}
+/**
+ * Logger-derived default emitter for the VC3B topology events. Mirrors the
+ * cortex store's `defaultEmitFor()` convention: a REAL structured-log producer so
+ * a caller that invokes the build seam without injecting an emitter still yields
+ * telemetry (best-effort, non-fatal). This is the production invoke point that
+ * makes the task-5 emission capable live (not dead under unit tests only).
+ */
+const topologyEmit = (event, fields) => {
+    new Logger().info(event, fields);
+};
+/**
+ * PREVENT-001: parse + shape-check a candidate payload before use. Returns
+ * undefined on any malformed/non-object input (best-effort, non-fatal).
+ *
+ * Q04 — FRAMING HARDENING: the canonical digest serialization in index.ts uses
+ * `|` (FIELD_SEP) and `~` (RECORD_SEP) as unambiguous delimiters between node
+ * ids/kinds and edge fields. That framing is collision-free only while id values
+ * (source/target/head) contain neither byte. Today ids are project-controlled, so
+ * this is latent, but a stored topology record could in principle carry a
+ * content-derived id containing those bytes, making the digest ambiguous
+ * (distinct graphs could collide) or the serialization injection-prone. To keep
+ * the digest well-defined for ANY input, reject candidates whose source/target/
+ * head contain the field/record separators; such a record is skipped (non-fatal)
+ * rather than fed into the digest.
+ */
+function parseCandidatePayload(r) {
+    let text;
+    try {
+        text = new TextDecoder().decode(r.payloadBytes);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const v = JSON.parse(text);
+        if (v === null ||
+            typeof v !== "object" ||
+            Array.isArray(v)) {
+            return undefined;
+        }
+        const o = v;
+        if (typeof o.source !== "string" ||
+            typeof o.target !== "string" ||
+            typeof o.head !== "string" ||
+            typeof o.score !== "number" ||
+            (o.kind !== "dependency" && o.kind !== "contradiction")) {
+            return undefined;
+        }
+        // Q04: reject any id that would corrupt the `|`/`~` digest framing.
+        if (FRAMING_SEP.test(o.source) ||
+            FRAMING_SEP.test(o.target) ||
+            FRAMING_SEP.test(o.head)) {
+            return undefined;
+        }
+        return {
+            source: o.source,
+            target: o.target,
+            head: o.head,
+            score: o.score,
+            kind: o.kind,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Field (`|`) and record (`~`) separators used by the canonical digest framing. */
+const FRAMING_SEP = /[|~]/;

package/dist/src/config/vector-cortex.js

@@ -101,6 +101,15 @@ export const VC2C_ENABLED = () => sprintFlag("MEGACOMPACT_VC2C");
  * cortex rebuild/admin seam and the reader-only topology summary seam.
  */
 export const VC3A_ENABLED = () => sprintFlag("MEGACOMPACT_VC3A");
+/**
+ * VC3B — deterministic cortical topology (TopologyV1 / EdgeV1).
+ * Default ON. `MEGACOMPACT_VC3B=0` disables and is byte-identical to the
+ * predecessor (mode C: no topology graph is built or emitted, the dashboard
+ * topology view returns the VC3A-precise aggregation shape with no node/edge
+ * arrays, zero `vector_cortex_topology_*` emissions). The real consumers are
+ * the topology build seam (build.ts) and the dashboard topology node/edge view.
+ */
+export const VC3B_ENABLED = () => sprintFlag("MEGACOMPACT_VC3B");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/vector-cortex/topology/build.js

@@ -0,0 +1,232 @@
+/**
+ * vector-cortex/topology/build.ts — deterministic cortical topology builder (VC3B).
+ *
+ * Implements the deterministic graph construction (tasks 2–4):
+ *   - For each (source, head) retain only candidates whose score is strictly
+ *     above the calibrated threshold.
+ *   - Stable-sort winning candidates by score DESCENDING, then by unsigned
+ *     target-ID bytes ASCENDING (TOP-TIE-002 — equal scores sort by target ID).
+ *   - Cap each (source, head) at top-k=16; the seventeenth eligible neighbor is
+ *     excluded (TOP-K-001).
+ *   - Remove self edges (source === target); reject them as TOP_SELF_EDGE.
+ *   - Reject non-finite scores as TOP_SCORE_NONFINITE — a single bad head's NaN
+ *     rejects only its own edge and never poisons other heads.
+ *   - Encode dependency edges as single directed records; contradiction edges as
+ *     symmetric PAIRED records (source→target and target→source) (TOP-KIND-003).
+ *
+ * This is the mode-A producer in the sprint triad: a multi-head topology index.
+ * The other two modes (B linear VectorSet scan, C source-seq/keyword) must yield
+ * the same threshold/tie/cap invariants and the same graph digest. Pure
+ * deterministic function — no I/O, no console, no network (PREVENT-PI-004),
+ * no `any` (PREVENT-011).
+ */
+import { TOP_K, } from "./types.js";
+/**
+ * Field (`|`) and record (`~`) separators used by the canonical digest framing in
+ * index.ts. Id values (source/target/head) carrying either byte would corrupt the
+ * framing and make distinct graphs collide on an identical digest, so the build
+ * rejects such candidates with TOP_FRAMING_SEP (Q04, mirrors the dashboard's
+ * parseCandidatePayload guard) — enforced at this pure seam, not only at one caller.
+ */
+const FRAMING_SEP = /[|~]/;
+/**
+ * Build the deterministic topology graph from calibrated-threshold candidates.
+ * Order-independent across any permutation of `input.candidates`.
+ */
+export function buildTopology(input) {
+    const { sessionId, sourceHighWater, threshold } = input;
+    // Group winning candidates by (source, head), stable-sorting each group by
+    // score desc then unsigned target-ID bytes, capping at top-k.
+    const byGroup = new Map();
+    const rejections = [];
+    for (const c of input.candidates) {
+        // Q04 — framing hardening: the canonical digest serialization in index.ts uses
+        // `|` (FIELD_SEP) and `~` (RECORD_SEP) as unambiguous delimiters. Those are
+        // collision-free only while id values (source/target/head) contain neither
+        // byte; a content-derived id carrying either would make two distinct graphs
+        // hash to an identical digest. Enforce the no-separator-in-id constraint at
+        // this pure build seam (not only at the dashboard caller) by rejecting such a
+        // candidate in isolation with TOP_FRAMING_SEP — the digest stays well-defined
+        // for ANY input.
+        if (FRAMING_SEP.test(c.source) || FRAMING_SEP.test(c.target) || FRAMING_SEP.test(c.head)) {
+            rejections.push(reject(c, "TOP_FRAMING_SEP"));
+            continue;
+        }
+        // Non-finite score: reject this candidate in isolation (never poison others).
+        if (!Number.isFinite(c.score)) {
+            rejections.push(reject(c, "TOP_SCORE_NONFINITE"));
+            continue;
+        }
+        if (c.source === c.target) {
+            rejections.push(reject(c, "TOP_SELF_EDGE"));
+            continue;
+        }
+        if (c.score <= threshold)
+            continue; // below calibrated threshold
+        const key = groupKey(c.source, c.head);
+        const group = byGroup.get(key);
+        if (group)
+            group.push(c);
+        else
+            byGroup.set(key, [c]);
+    }
+    // Stable sort each (source, head) group: score desc, then unsigned target-ID
+    // bytes asc. Keep exactly the top-k=16 (the 17th eligible neighbor is excluded).
+    const selected = [];
+    for (const group of byGroup.values()) {
+        group.sort(compareCandidates);
+        for (let i = 0; i < Math.min(group.length, TOP_K); i++) {
+            selected.push(group[i]);
+        }
+    }
+    // Encode dependency edges as directed records; contradiction edges as
+    // symmetric PAIRED records. Duplicate (source,target,head) contradictions
+    // collapse: the same symmetric pair is emitted once per direction — dedupe to
+    // keep the paired graph well-formed and the digest stable.
+    //
+    // IMPORTANT: `selected` is first ordered by a canonical global comparator so
+    // every dedup decision (which head represents a collapsed contradiction pair,
+    // which identical directed edge is kept) is deterministic and INDEPENDENT of
+    // the incoming candidate order. Without this, reversing the input order could
+    // flip which head represents a symmetric pair and change the digest.
+    //
+    // The comparator sorts by SCORE DESCENDING FIRST, so first-writer-wins dedup
+    // keeps the MAXIMUM score per collapsed relation. Two candidates emitting the
+    // same directed edge (same source,target,head) with different scores keep the
+    // higher one; a contradiction pair a↔b with different scores is claimed by the
+    // higher-scoring candidate regardless of which end is "source". A downstream
+    // consumer (VC3C receives TopologyV1) therefore gets the strongest score for a
+    // collapsed relation, never the weakest, and the winner is decided by score —
+    // not by source-ID byte order. (Score ties fall through to bytewise keys so
+    // the total order stays deterministic.)
+    selected.sort(compareSelected);
+    const edges = new Map();
+    const nodes = new Map();
+    for (const c of selected) {
+        nodes.set(c.source, nodeKind(c));
+        nodes.set(c.target, nodeKind(c));
+        if (c.kind === "contradiction") {
+            // Symmetric pair: emit source→target and target→source exactly once, keyed
+            // so that a reversed duplicate from another candidate collapses to one pair.
+            const fwd = pairKey(c.source, c.target);
+            const rev = pairKey(c.target, c.source);
+            const hasFwd = edges.has(fwd) || edges.has(rev);
+            if (!hasFwd) {
+                edges.set(fwd, { source: c.source, target: c.target, head: c.head, score: c.score, direction: "contradiction" });
+                edges.set(rev, { source: c.target, target: c.source, head: c.head, score: c.score, direction: "contradiction" });
+            }
+            continue;
+        }
+        // Directed dependency: distinct per (source, target, head).
+        const depKey = dirKey(c.source, c.target, c.head, "dependency");
+        if (!edges.has(depKey)) {
+            edges.set(depKey, { source: c.source, target: c.target, head: c.head, score: c.score, direction: "dependency" });
+        }
+    }
+    const nodeList = [...nodes.entries()]
+        .map(([id, kind]) => ({ id, kind }))
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const edgeList = [...edges.values()].sort(compareEdges);
+    const graph = {
+        schema: "topology-v1",
+        sessionId,
+        sourceHighWater,
+        threshold,
+        nodeCount: nodeList.length,
+        edgeCount: edgeList.length,
+        generationDigest: "",
+        nodes: nodeList,
+        edges: edgeList,
+    };
+    return { ok: true, topology: graph, rejected: rejections };
+}
+function reject(c, code) {
+    return { source: c.source, target: c.target, head: c.head, score: c.score, code };
+}
+function groupKey(source, head) {
+    return JSON.stringify([source, head]);
+}
+function pairKey(a, b) {
+    return JSON.stringify([a, b, " "]);
+}
+function dirKey(a, b, head, direction) {
+    return JSON.stringify([a, b, head, direction]);
+}
+function compareCandidates(a, b) {
+    if (a.score !== b.score)
+        return a.score > b.score ? -1 : 1;
+    // Equal scores: sort by unsigned target-ID bytes ascending (TOP-TIE-002).
+    const byTarget = unsignedBytesCompare(a.target, b.target);
+    if (byTarget !== 0)
+        return byTarget;
+    // Equal score + target: break the tie by kind bytes so the within-group sort is
+    // a TOTAL order, independent of input order (Q01). Without this, two tied
+    // candidates of differing kind that land exactly at the top-k=16 boundary would
+    // fall back to JS stable order = candidate input order, flipping which edge
+    // survives and changing the graph digest. Mirrors compareSelected's `kind` key.
+    return unsignedBytesCompare(a.kind, b.kind);
+}
+/**
+ * Total, deterministic order over selected candidates used to drive dedup before
+ * encoding. Independent of the incoming input order so a collapsed contradiction
+ * pair always picks the same representing head and identical directed edges keep
+ * the same winner.
+ *
+ * SCORE DESCENDING IS THE PRIMARY KEY: first-writer-wins dedup on this order
+ * retains the highest score for every collapsed relation (Q01). Only after
+ * scores are equal do we fall through to bytewise source/target/head/kind keys,
+ * which keeps a sound deterministic tie-break (a score tie collapses to the
+ * same representing head regardless of input order).
+ */
+function compareSelected(a, b) {
+    return ((a.score < b.score ? 1 : a.score > b.score ? -1 : 0) ||
+        unsignedBytesCompare(a.source, b.source) ||
+        unsignedBytesCompare(a.target, b.target) ||
+        unsignedBytesCompare(a.head, b.head) ||
+        unsignedBytesCompare(a.kind, b.kind));
+}
+function compareEdges(a, b) {
+    return (unsignedBytesCompare(a.source, b.source) ||
+        unsignedBytesCompare(a.target, b.target) ||
+        unsignedBytesCompare(a.head, b.head) ||
+        unsignedBytesCompare(a.direction, b.direction) ||
+        (a.score < b.score ? -1 : a.score > b.score ? 1 : 0));
+}
+/**
+ * Unsigned bytewise comparison over UTF-8 bytes of two strings. String
+ * `<`/`>` in JS is UTF-16 code-unit order, which equals UTF-8 byte order for
+ * the ASCII identifiers used (and for our domain); we implement an explicit
+ * unsigned-byte comparator so ordering is defined by spec, not JS internals.
+ */
+function unsignedBytesCompare(a, b) {
+    const ba = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    const n = Math.min(ba.length, bb.length);
+    for (let i = 0; i < n; i++) {
+        if (ba[i] !== bb[i])
+            return ba[i] < bb[i] ? -1 : 1;
+    }
+    return ba.length < bb.length ? -1 : ba.length > bb.length ? 1 : 0;
+}
+/**
+ * Node kind for a retained edge: a node is marked by the record kind it is
+ * derived from. A contradiction candidate marks both endpoints "contradiction";
+ * a dependency candidate marks both endpoints "dependency" (Q02) — the node
+ * kind matches the producing record kind, never a synthetic placeholder.
+ *
+ * NODE-KIND SEMANTICS (documented, Q03): a node participates in the kind of
+ * whichever retained edge LABELLED it LAST during the linear pass over `selected`.
+ * Because `selected` is sorted SCORE-DESCENDING first, the last label a node
+ * receives comes from its LOWEST-scoring retained edge — i.e. when a node is
+ * touched by both a dependency and a contradiction edge (of equal or lower
+ * score), the WEAKEST relation's kind wins the node's `kind` field, not the
+ * strongest. This is deliberate and DETERMINISTIC (the total compareSelected
+ * order, with the Q01 `kind` tie-break, fixes the pass order independent of
+ * input order), and mode B reproduces it exactly. A downstream VC3C consumer
+ * must read node.kind as "the relation kind of the weakest retained edge
+ * incident to this node", not "the dominant/strongest relation". Per-edge
+ * direction + kind are authoritative on the edges themselves.
+ */
+function nodeKind(c) {
+    return c.kind === "contradiction" ? "contradiction" : "dependency";
+}

package/dist/src/vector-cortex/topology/index.js

@@ -0,0 +1,113 @@
+/**
+ * vector-cortex/topology/index.ts — topology barrel + stable graph digest (VC3B).
+ *
+ * Typical role: a thin barrel + a few derived helpers. The build algorithm lives
+ * in build.ts; this file:
+ *   - re-exports the TopologyV1 / EdgeV1 contracts;
+ *   - computes ONE deterministic graph digest over the canonical, order-
+ *     independent serialization of nodes + edges (task 4);
+ *   - compose `buildTopologyGraph` = build + digest + emit on one seam.
+ *
+ * Ordinal-order independence: the digest is computed over nodes sorted by id
+ * bytes and edges sorted by (source, target, head, direction) then score, so
+ * any permutation of the build input yields an identical digest (verified by the
+ * acceptance consumer across 1,000 distinct input orderings — Q02).
+ *
+ * Pure deterministic helpers: no I/O, no console, no network (PREVENT-PI-004),
+ * no `any` (PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+import { buildTopology } from "./build.js";
+export { TOP_IDS, TOP_NAMED_IDS, TOP_K } from "./types.js";
+export { buildTopology } from "./build.js";
+/**
+ * Deterministic topological-construction seam (task 5). Runs the build, fills
+ * the stable generationDigest, and optionally emits:
+ *   - `vector_cortex_topology_built`        — once, when a graph is produced;
+ *   - `vector_cortex_topology_edge_rejected`— once per rejected edge with code.
+ * Emission is best-effort and non-fatal (never breaks the agent loop).
+ */
+export function buildTopologyGraph(input, emit) {
+    const result = buildTopology(input);
+    if (!result.ok)
+        return result;
+    const topology = {
+        ...result.topology,
+        generationDigest: graphDigest(result.topology),
+    };
+    const out = { ok: true, topology, rejected: result.rejected };
+    if (emit) {
+        try {
+            emit("vector_cortex_topology_built", {
+                sessionId: topology.sessionId,
+                sourceHighWater: topology.sourceHighWater.toString(),
+                nodeCount: topology.nodeCount,
+                edgeCount: topology.edgeCount,
+                generationDigest: topology.generationDigest,
+            });
+            for (const r of result.rejected) {
+                emit("vector_cortex_topology_edge_rejected", {
+                    sessionId: topology.sessionId,
+                    source: r.source,
+                    target: r.target,
+                    head: r.head,
+                    code: r.code,
+                });
+            }
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    }
+    return out;
+}
+/**
+ * ONE deterministic SHA-256 (hex) over the canonical serialization of the graph.
+ * Canonical form is a compact stream: `topology-v1|` + sorted nodes + `|` +
+ * sorted edges, where nodes are sorted by id bytes and edges by
+ * (source, target, head, direction) then score. Order-independence is achieved
+ * by that canonical sort, never by input order.
+ *
+ * Printable framing (no control bytes): FIELD_SEP (`|`) separates fields and
+ * RECORD_SEP (`~`) separates records. The project-controlled field values (ids,
+ * kinds, heads, directions, scores) contain neither `|` nor `~`, so the framing
+ * never collides, and keeping the file control-byte-free lets git treat this
+ * core sprint file as text (prevents a spurious "binary file" classification).
+ */
+// Printable, unambiguous framing delimiters for the canonical serialization.
+const FIELD_SEP = "|";
+const RECORD_SEP = "~";
+export function graphDigest(topology) {
+    const nodes = canonicalNodes(topology.nodes);
+    const edges = canonicalEdges(topology.edges);
+    const hash = createHash("sha256");
+    hash.update(`topology-v1${FIELD_SEP}`);
+    hash.update(nodes);
+    hash.update(FIELD_SEP);
+    hash.update(edges);
+    return `sha256:${hash.digest("hex")}`;
+}
+function canonicalNodes(nodes) {
+    const sorted = [...nodes]
+        .map((n) => `${n.id}${FIELD_SEP}${n.kind}`)
+        .sort(unsignedBytesCompare)
+        .join(RECORD_SEP);
+    return Buffer.from(sorted, "utf8");
+}
+function canonicalEdges(edges) {
+    const parts = edges
+        .map((e) => `${e.source}${FIELD_SEP}${e.target}${FIELD_SEP}${e.head}${FIELD_SEP}${e.direction}${FIELD_SEP}${e.score}`)
+        .sort(unsignedBytesCompare)
+        .join(RECORD_SEP);
+    return Buffer.from(parts, "utf8");
+}
+function unsignedBytesCompare(a, b) {
+    const ba = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    const n = Math.min(ba.length, bb.length);
+    for (let i = 0; i < n; i++) {
+        if (ba[i] !== bb[i])
+            return ba[i] < bb[i] ? -1 : 1;
+    }
+    return ba.length < bb.length ? -1 : ba.length > bb.length ? 1 : 0;
+}

package/dist/src/vector-cortex/topology/types.js

@@ -0,0 +1,54 @@
+/**
+ * vector-cortex/topology/types.ts — deterministic cortical topology contract (VC3B).
+ *
+ * Owns `TopologyV1` / `EdgeV1` / `TopologyNodeV1` — the pure graph produced by
+ * the deterministic build (build.ts). The build is the mode-A multi-head
+ * topology index: for each (source, head) it retains only calibrated-threshold
+ * edges, stable-sorts by score descending then unsigned target-ID bytes, and
+ * caps each source/head at top-k=16. Dependency edges are directed records;
+ * contradiction edges are emitted as symmetric PAIRED records (source→target
+ * and target→source) so the encoded graph is directional even though the
+ * relation is symmetric.
+ *
+ * Consumes only reviewer-accepted predecessor contracts (VC3A CortexRecordV1
+ * aggregates, VC2B heads) and the [common contracts](../../../../docs/vector-cortex/CONTRACTS.md).
+ * Pure types/schema + small predicates: no storage, no console, no network,
+ * no side effects (PREVENT-PI-004 / PREVENT-011). The acceptance contract and
+ * conformance IDs (TOP-001..020 + named TOP-K/TIE/KIND) live here.
+ */
+/**
+ * Registered TOP conformance ID range (TOP-001..020). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/code. The three NAMED assertions (TOP-K-001 / TOP-TIE-002 /
+ * TOP-KIND-003) live in the acceptance test.
+ */
+export const TOP_IDS = [
+    "TOP-001",
+    "TOP-002",
+    "TOP-003",
+    "TOP-004",
+    "TOP-005",
+    "TOP-006",
+    "TOP-007",
+    "TOP-008",
+    "TOP-009",
+    "TOP-010",
+    "TOP-011",
+    "TOP-012",
+    "TOP-013",
+    "TOP-014",
+    "TOP-015",
+    "TOP-016",
+    "TOP-017",
+    "TOP-018",
+    "TOP-019",
+    "TOP-020",
+];
+/** Named TOP conformance assertions (spec: TOP-K/TOP-TIE/TOP-KIND). */
+export const TOP_NAMED_IDS = [
+    "TOP-K-001",
+    "TOP-TIE-002",
+    "TOP-KIND-003",
+];
+/** Deterministic per-source/head edge cap (top-k=16). */
+export const TOP_K = 16;