pi-mega-compact 0.19.1 → 0.19.3

package/dist/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/vector-cortex/topology/query.js

@@ -0,0 +1,342 @@
+/**
+ * vector-cortex/topology/query.ts — topology query + router invalidation (VC3C).
+ *
+ * Owns `RouterKeyV2` (the structured router key) and `TopologyQueryV1` (the
+ * generation query/index surface that serves graphs and invalidates stale
+ * generations). This is the degradation seam of the sprint's failure triad:
+ *
+ *   A = topology index at current generation (serve the active graph);
+ *   B = fresh linear scan forced when a key targets a STALE generation;
+ *   C = authority sequence scan forced when the derived store is unavailable.
+ *
+ * Key encoding is length-delimited with unsigned-byte (prefix) ordering and a
+ * FIXED five-field arity, so no field value can ambiguously prefix another and
+ * two sessions `a` / `aa` can never prefix-collide at the key level
+ * (M6-KEY-001). Invalidation matches the exact `(session,generation)` identity
+ * bytes — never a string-prefix — and a query whose key carries a generation
+ * older than the session's active one is rejected with `TOP_GENERATION_STALE`
+ * (M6-STALE-002), which forces mode B.
+ *
+ * Pure src/ logic over an injected `TopologyQueryHost` (the source of graphs +
+ * linear/authority scans) and an optional `TopologyQueryEmit`. Deterministic,
+ * pi-agnostic, no console, no network (PREVENT-PI-004), no `any`
+ * (PREVENT-011). The caller owns durability; every store write on the caller
+ * side is best-effort and never breaks the agent loop.
+ */
+import { createHash } from "node:crypto";
+/** Query rejected: the key's generation is stale relative to the active one. */
+export const TOP_GENERATION_STALE = "TOP_GENERATION_STALE";
+/** Query rejected: a key could not be decoded (malformed length-delimited bytes). */
+export const TOP_KEY_DECODE_FAILED = "TOP_KEY_DECODE_FAILED";
+/** Query rejected: the derived store is unavailable and no authority scan is possible. */
+export const TOP_AUTHORITY_UNAVAILABLE = "TOP_AUTHORITY_UNAVAILABLE";
+/** Frozen router key schema version carried in every encoded key. */
+export const ROUTER_KEY_VERSION = 2;
+/**
+ * Create the query surface. `emit` is optional and flag-gated (the caller passes
+ * a reporter produced by the same pattern VC3A/VC3B use — zero emissions when
+ * `MEGACOMPACT_VC3C=0`, byte-identical to the predecessor). Pure in-memory index
+ * over the injected host; durability of invalidation is the caller's job.
+ */
+export function createTopologyQuery(host, emit) {
+    // session -> Set of indexed generation strings (exact, byte-identity).
+    const generations = new Map();
+    const fire = (event, fields) => {
+        if (!emit)
+            return;
+        try {
+            emit(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    };
+    const query = (key) => {
+        const active = host.activeGeneration(key.session);
+        // Mode C: derived store unavailable -> authority sequence scan.
+        if (!host.derivedAvailable(key.session)) {
+            const cDigest = host.authorityScan(key.session, key.sourceStart, key.sourceEnd);
+            if (cDigest === undefined) {
+                return { ok: false, code: TOP_AUTHORITY_UNAVAILABLE, mode: "C" };
+            }
+            fire("vector_cortex_topology_query_demoted", {
+                session: key.session,
+                generation: key.generation.toString(),
+                code: "DERIVED_UNAVAILABLE",
+                toMode: "C",
+            });
+            return {
+                ok: true,
+                mode: "C",
+                session: key.session,
+                generation: key.generation,
+                algorithm: key.algorithm,
+                matchedKey: encodeRouterKeyV2(key),
+                digest: cDigest.digest,
+            };
+        }
+        // A key is stale when its generation is below the active one (or the active
+        // generation is unset and the requested generation is non-zero).
+        const stale = active === undefined
+            ? key.generation !== 0n
+            : key.generation < active;
+        if (stale) {
+            // Mode B: fresh linear scan forced by a stale A key.
+            const bDigest = host.linearScan(key.session, key.sourceStart, key.sourceEnd);
+            fire("vector_cortex_topology_query_demoted", {
+                session: key.session,
+                generation: key.generation.toString(),
+                activeGeneration: active === undefined ? null : active.toString(),
+                code: "STALE_GENERATION",
+                toMode: "B",
+            });
+            return {
+                ok: true,
+                mode: "B",
+                session: key.session,
+                generation: key.generation,
+                algorithm: key.algorithm,
+                matchedKey: encodeRouterKeyV2(key),
+                digest: bDigest.digest,
+            };
+        }
+        // Mode A: topology index at the current generation. If the derived store is
+        // up but has not indexed this exact (generation, algorithm) yet, that is a
+        // mode-A miss (no graph to serve) — force the fresh linear scan rather than
+        // fabricate a graph or report a false staleness (Q03: the index cannot be
+        // trusted to hold every current generation; B recomputes from source).
+        const graph = host.graphAt(key.session, key.generation, key.algorithm);
+        if (graph === undefined) {
+            const bDigest = host.linearScan(key.session, key.sourceStart, key.sourceEnd);
+            fire("vector_cortex_topology_query_demoted", {
+                session: key.session,
+                generation: key.generation.toString(),
+                code: "GENERATION_MISS",
+                toMode: "B",
+            });
+            return {
+                ok: true,
+                mode: "B",
+                session: key.session,
+                generation: key.generation,
+                algorithm: key.algorithm,
+                matchedKey: encodeRouterKeyV2(key),
+                digest: bDigest.digest,
+            };
+        }
+        return {
+            ok: true,
+            mode: "A",
+            session: key.session,
+            generation: key.generation,
+            algorithm: key.algorithm,
+            matchedKey: encodeRouterKeyV2(key),
+            digest: graph.digest,
+        };
+    };
+    const invalidate = (session, generation) => {
+        const invalidationIdentity = invalidationKey(session, generation);
+        const set = generations.get(session);
+        if (set)
+            set.delete(invalidationIdentity);
+        fire("vector_cortex_router_generation_invalidated", {
+            session,
+            generation: generation.toString(),
+            key: invalidationIdentity,
+        });
+    };
+    const generationalCount = (session) => {
+        return generations.get(session)?.size ?? 0;
+    };
+    return { query, invalidate, generationalCount };
+}
+// ---------------------------------------------------------------------------
+// Length-delimited, unsigned-byte-ordered key encoding (M6-KEY-001)
+// ---------------------------------------------------------------------------
+/**
+ * Encode one field: `u32BE(byteLength) || bytes`. Non-negative numbers are
+ * encoded as their unsigned big-endian byte form (leading zeros trimmed). This
+ * is the standard big-endian length-prefixed encoding: two fields compare in
+ * unsigned-byte order exactly as their values do, and no value is an ambiguous
+ * prefix of another.
+ */
+function encodeLengthDelimited(bytes) {
+    const out = new Uint8Array(4 + bytes.length);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, bytes.length, false);
+    out.set(bytes, 4);
+    return out;
+}
+/** Big-endian unsigned bytes of a non-negative bigint (length-prefixed below). */
+function bigintBytes(n) {
+    let v = n;
+    const out = [];
+    if (v === 0n)
+        return new Uint8Array([0]);
+    while (v > 0n) {
+        out.unshift(Number(v & 0xffn));
+        v >>= 8n;
+    }
+    return Uint8Array.from(out);
+}
+/** UTF-8 bytes of a string. */
+function strBytes(s) {
+    return new TextEncoder().encode(s);
+}
+function concat(parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/**
+ * Encode a RouterKeyV2 into its canonical, length-delimited, unsigned-byte-ordered
+ * byte form. Version-prefixed (1 byte) + five length-delimited fields in fixed
+ * order (session, sourceStart, sourceEnd, generation, algorithm). Fixed arity +
+ * length-delimiting means no key is a strict prefix of another and sessions `a`
+ * and `aa` never collide (M6-KEY-001).
+ */
+export function encodeRouterKeyV2(key) {
+    const version = Uint8Array.of(ROUTER_KEY_VERSION);
+    const session = encodeLengthDelimited(strBytes(key.session));
+    const sourceStart = encodeLengthDelimited(bigintBytes(key.sourceStart));
+    const sourceEnd = encodeLengthDelimited(bigintBytes(key.sourceEnd));
+    const generation = encodeLengthDelimited(bigintBytes(key.generation));
+    const algorithm = encodeLengthDelimited(strBytes(key.algorithm));
+    return "rk2:" + Buffer.from(concat([version, session, sourceStart, sourceEnd, generation, algorithm])).toString("hex");
+}
+/**
+ * Decode a RouterKeyV2 from its canonical byte form. Returns
+ * TOP_KEY_DECODE_FAILED on malformed bytes (bad version, truncated length, or
+ * trailing garbage). Never parses by string prefix.
+ */
+export function decodeRouterKeyV2(encoded) {
+    if (!encoded.startsWith("rk2:"))
+        return { ok: false, code: "TOP_KEY_DECODE_FAILED" };
+    const hex = encoded.slice(4);
+    if (!/^[0-9a-f]*$/.test(hex) || hex.length % 2 !== 0) {
+        return { ok: false, code: "TOP_KEY_DECODE_FAILED" };
+    }
+    const buf = Buffer.from(hex, "hex");
+    const bytes = new Uint8Array(buf);
+    const reader = new Reader(bytes);
+    const version = reader.u8();
+    if (version !== ROUTER_KEY_VERSION)
+        return { ok: false, code: "TOP_KEY_DECODE_FAILED" };
+    const sessionBytes = reader.lenPrefixed();
+    const ssBytes = reader.lenPrefixed();
+    const seBytes = reader.lenPrefixed();
+    const genBytes = reader.lenPrefixed();
+    const algoBytes = reader.lenPrefixed();
+    if (reader.remaining() !== 0)
+        return { ok: false, code: "TOP_KEY_DECODE_FAILED" };
+    if (sessionBytes === null || ssBytes === null || seBytes === null || genBytes === null || algoBytes === null) {
+        return { ok: false, code: "TOP_KEY_DECODE_FAILED" };
+    }
+    const session = new TextDecoder().decode(sessionBytes);
+    const sourceStart = bytesToBigint(ssBytes);
+    const sourceEnd = bytesToBigint(seBytes);
+    const generation = bytesToBigint(genBytes);
+    const algorithm = new TextDecoder().decode(algoBytes);
+    return { ok: true, key: { session, sourceStart, sourceEnd, generation, algorithm } };
+}
+/** Sequential length-delimited byte reader. */
+class Reader {
+    bytes;
+    off = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    u8() {
+        const v = this.bytes[this.off];
+        this.off += 1;
+        return v;
+    }
+    lenPrefixed() {
+        if (this.off + 4 > this.bytes.length)
+            return null;
+        const view = new DataView(this.bytes.buffer, this.bytes.byteOffset + this.off, 4);
+        const len = view.getUint32(0, false);
+        this.off += 4;
+        if (this.off + len > this.bytes.length)
+            return null;
+        const out = this.bytes.slice(this.off, this.off + len);
+        this.off += len;
+        return out;
+    }
+    remaining() {
+        return this.bytes.length - this.off;
+    }
+}
+/** Non-negative bigint from its unsigned big-endian bytes. */
+function bytesToBigint(bytes) {
+    let n = 0n;
+    for (const b of bytes)
+        n = (n << 8n) | BigInt(b);
+    return n;
+}
+/**
+ * Canonical invalidation identity for an exact (session,generation) pair, using
+ * the SAME length-delimited scheme so two pairs can only match by exact byte
+ * equality (never by string prefix — `a` never matches `aa`). Returned as hex
+ * for use as a registry key.
+ */
+export function invalidationKey(session, generation) {
+    const sessionF = encodeLengthDelimited(strBytes(session));
+    const genF = encodeLengthDelimited(bigintBytes(generation));
+    return "inv:" + Buffer.from(concat([sessionF, genF])).toString("hex");
+}
+/** One deterministic SHA-256 (hex) digest over the canonical key bytes. */
+export function keyDigest(key) {
+    return `sha256:${createHash("sha256").update(Buffer.from(encodeRouterKeyV2(key).slice(4), "hex")).digest("hex")}`;
+}
+/**
+ * Shared invalidation-capability seam (narrow delegate, no routing rewrite).
+ * Records the EXACT (session,generation) identity and, when `enabled`, best-effort
+ * emits `vector_cortex_router_generation_invalidated`. Falsy `enabled` (flag OFF)
+ * is a strict no-op so the predecessor keying is byte-identical to pre-sprint.
+ * Exactness is enforced by `invalidationKey` (length-delimited, never a string
+ * prefix — `a` never matches `aa`), the same identity M6 validates.
+ */
+export function routerGenerationInvalidationSeam(key, enabled, emit) {
+    if (!enabled)
+        return;
+    const identity = invalidationKey(key.session, key.generation);
+    if (emit) {
+        try {
+            emit("vector_cortex_router_generation_invalidated", {
+                session: key.session,
+                generation: key.generation.toString(),
+                key: identity,
+            });
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    }
+}
+/** Registered TOP query conformance ID range (TOP-021..030). */
+export const TOP_QUERY_IDS = [
+    "TOP-021",
+    "TOP-022",
+    "TOP-023",
+    "TOP-024",
+    "TOP-025",
+    "TOP-026",
+    "TOP-027",
+    "TOP-028",
+    "TOP-029",
+    "TOP-030",
+];
+/** Registered named TOP-query conformance IDs. */
+export const TOP_QUERY_NAMED_IDS = [
+    "TOP-QUERY-003",
+    "M6-KEY-001",
+    "M6-STALE-002",
+];

package/dist/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;

package/dist/vector-cortex/vc3b-support.js

@@ -0,0 +1,125 @@
+/**
+ * vector-cortex/vc3b-support.ts — VC3B acceptance test support (mode-B reference
+ * scan + shared helper producers).
+ *
+ * Exact-algorithm sibling to the acceptance aggregator (vc3b-acceptance.test.ts).
+ * Splitting the mode-B linear VectorSet scan into its own file keeps the
+ * aggregator under its headroom limits (Q03) while preserving the forced-triad
+ * A/B digest agreement check: build.ts is mode A (multi-head index), this
+ * linear scan is mode B (same thresholds/cap/encoding), and they must agree on
+ * the graph digest for the same eligible candidate set.
+ *
+ * The scan mirrors build.ts semantics deliberately — including keeping the
+ * MAXIMUM score across a collapsed relation (contradiction pair or duplicate
+ * directed edge) so a real calibrated-threshold builder and the reference scan
+ * agree even when duplicate candidates carry different scores (Q01).
+ *
+ * Test-support only: no production code imports this module, no console, no
+ * network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+import { graphDigest, TOP_K } from "./topology/index.js";
+export function candidates(rows) {
+    return rows.map(([source, target, head, score, kind]) => ({
+        source,
+        target,
+        head,
+        score,
+        kind,
+    }));
+}
+/**
+ * Reference mode-B linear VectorSet scan: same calibrated threshold and cap as
+ * THE documented builder. For each (source, head) it scans ALL records, keeps
+ * those strictly above threshold, sorts by score descending then target bytes,
+ * keeps the top-k, and encodes dependency/contradiction directions. It is a
+ * separate linear implementation from build.ts's grouped byGroup path, so the
+ * two independent implementations must agree on the digest.
+ */
+export function linearScan(input) {
+    const groups = new Map();
+    for (const c of input.candidates) {
+        if (!Number.isFinite(c.score))
+            continue;
+        if (c.source === c.target)
+            continue;
+        if (c.score <= input.threshold)
+            continue;
+        const key = `${c.source}::${c.head}`;
+        const g = groups.get(key);
+        if (g)
+            g.push(c);
+        else
+            groups.set(key, [c]);
+    }
+    const selected = [];
+    for (const g of groups.values()) {
+        g.sort((x, y) => x.score !== y.score ? (x.score > y.score ? -1 : 1) :
+            x.target < y.target ? -1 : x.target > y.target ? 1 :
+                // Equal score + target: break the tie by kind bytes so the within-group sort
+                // is a TOTAL order independent of input order (Q01) — mirrors build.ts's
+                // compareCandidates and keeps the A/B reference-faithfulness claim at the
+                // top-k boundary.
+                x.kind < y.kind ? -1 : x.kind > y.kind ? 1 : 0);
+        for (let i = 0; i < Math.min(g.length, TOP_K); i++)
+            selected.push(g[i]);
+    }
+    // Sort score DESCENDING first so dedup keeps the MAXIMUM score per collapsed
+    // relation, mirroring build.ts (Q01). Score ties fall through to bytewise
+    // source/target/head/kind keys — INCLUDING `kind` as the final tie-break — so
+    // the total order is exactly compareSelected in build.ts (mode A). Without the
+    // `kind` tie-break, two equal-(score,source,target,head) candidates of
+    // differing kind would fall back to stable input order, which depends on input
+    // ordering: the deterministic last-writer for a node's kind (and hence the
+    // graph digest) would diverge from mode A whenever such a pair produces the
+    // node-kind map entry. Adding `kind` keeps mode B reference-faithful to mode A
+    // (Q01: 'contradiction' sorts before 'dependency', bytewise).
+    selected.sort((x, y) => x.score !== y.score ? (x.score > y.score ? -1 : 1) :
+        x.source < y.source ? -1 : x.source > y.source ? 1 :
+            x.target < y.target ? -1 : x.target > y.target ? 1 :
+                x.head < y.head ? -1 : x.head > y.head ? 1 :
+                    x.kind < y.kind ? -1 : x.kind > y.kind ? 1 : 0);
+    const nodes = new Map();
+    const edges = [];
+    const seen = new Set();
+    for (const c of selected) {
+        const kind = c.kind === "contradiction" ? "contradiction" : "dependency";
+        nodes.set(c.source, kind);
+        nodes.set(c.target, kind);
+        if (c.kind === "contradiction") {
+            const fwd = `${c.source}::${c.target}`;
+            const rev = `${c.target}::${c.source}`;
+            if (!seen.has(fwd) && !seen.has(rev)) {
+                seen.add(fwd);
+                seen.add(rev);
+                edges.push({ source: c.source, target: c.target, head: c.head, score: c.score, direction: "contradiction" });
+                edges.push({ source: c.target, target: c.source, head: c.head, score: c.score, direction: "contradiction" });
+            }
+            continue;
+        }
+        const depKey = `${c.source}::${c.target}::${c.head}::dependency`;
+        if (!seen.has(depKey)) {
+            seen.add(depKey);
+            edges.push({ source: c.source, target: c.target, head: c.head, score: c.score, direction: "dependency" });
+        }
+    }
+    const nodeList = [...nodes.entries()]
+        .map(([id, kind]) => ({ id, kind }))
+        .sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
+    const edgeList = [...edges].sort((x, y) => x.source < y.source ? -1 : x.source > y.source ? 1 :
+        x.target < y.target ? -1 : x.target > y.target ? 1 :
+            x.head < y.head ? -1 : x.head > y.head ? 1 :
+                x.direction < y.direction ? -1 : x.direction > y.direction ? 1 :
+                    x.score < y.score ? -1 : x.score > y.score ? 1 : 0);
+    const digest = graphDigest({
+        schema: "topology-v1",
+        sessionId: input.sessionId,
+        sourceHighWater: input.sourceHighWater,
+        threshold: input.threshold,
+        nodeCount: nodeList.length,
+        edgeCount: edgeList.length,
+        generationDigest: "",
+        nodes: nodeList,
+        edges: edgeList,
+    });
+    return { nodes: nodeList, edges: edgeList, digest };
+}