pi-mega-compact 0.19.1 → 0.19.3

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;

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

package/dist/vector-cortex/migrations/router-generation-v2.js

@@ -0,0 +1,252 @@
+/**
+ * vector-cortex/migrations/router-generation-v2.ts — M6 copy/validate/switch
+ * migration (VC3C).
+ *
+ * M6 versions the tiered router's query set: the predecessor routed on ad-hoc
+ * per-session keys (no generation identity); VC3C routes on the structured,
+ * length-delimited `RouterKeyV2`. M6 copies the old per-session query set into
+ * v2 `RouterGenV2Row`s BESIDE the legacy state, validates, and only then
+ * atomically switches the active version pointer — the same copy/validate/
+ * switch + resume contract as M4.
+ *
+ *   - copy: resumable per (session, old key) — an interrupted run resumes
+ *     without duplicate rows or active-pointer drift.
+ *   - validate: every old query key has exactly one v2 row, every row's key is
+ *     canonical + re-hashes, and — the VC3C-specific invariant — the new query
+ *     set is partition-preserving: a row derived from an old key of session S
+ *     MUST carry session S. A row whose session differs is rejected as
+ *     cross-session eviction (`M6_CROSS_SESSION_EVICTION`): one session may
+ *     never lose or steal another session's query identity.
+ *   - switch: atomically flips the ACTIVE VERSION pointer from 1 (legacy) to 2
+ *     (router-generation-v2) only after a verified copy; interruption keeps the
+ *     old active pointer.
+ *
+ * Pure logic over an injected M6Host (deterministic + testable; no console).
+ * PREVENT-002/011/PI-004 honored.
+ */
+import { createHash } from "node:crypto";
+import { encodeRouterKeyV2, decodeRouterKeyV2, } from "../topology/query.js";
+/** The active-version value the v2 router generation pointer is switched to. */
+export const ROUTER_GEN_V2_VERSION = 2;
+/** The legacy (predecessor) active-version value before any verified switch. */
+export const ROUTER_GEN_LEGACY_VERSION = 1;
+/** M6 failure codes. */
+export const M6_FAIL = {
+    VERSION_MISMATCH: "M6_VERSION_MISMATCH",
+    COPY_PARTIAL: "M6_COPY_PARTIAL",
+    COUNT_MISMATCH: "M6_COUNT_MISMATCH",
+    DIGEST_MISMATCH: "M6_DIGEST_MISMATCH",
+    BAD_OLD_KEY: "M6_BAD_OLD_KEY",
+    CROSS_SESSION_EVICTION: "M6_CROSS_SESSION_EVICTION",
+    SWITCH_PRECONDITION: "M6_SWITCH_PRECONDITION",
+};
+/** Derive one v2 row from an old key (authoritative bytes). */
+export function deriveRouterGenRow(host, session, oldKey) {
+    const parsed = host.parseOldKey(session, oldKey);
+    if (!parsed.ok)
+        return { ok: false, session, oldKey };
+    const key = parsed.key;
+    // Cross-session guard at COPY time: the structured key's session must equal
+    // the slot session. A key that claims a different session is never copied.
+    if (key.session !== session)
+        return { ok: false, session, oldKey };
+    const encoded = encodeRouterKeyV2(key);
+    return {
+        ok: true,
+        row: {
+            session,
+            generation: key.generation,
+            sourceStart: key.sourceStart,
+            sourceEnd: key.sourceEnd,
+            algorithm: key.algorithm,
+            key: encoded,
+            digest: sha256Hex(Buffer.from(encoded.slice(4), "hex")),
+        },
+    };
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Copy the full old query set into v2 rows (resumable): rows already persisted
+ * with a matching canonical key + digest are left untouched (no duplicates);
+ * absent or corrupt (wrong session / wrong key / stale digest / bad old key)
+ * slots are (re)written from the authoritative derivation. Returns the delta
+ * written this call. The active pointer stays at the legacy version until a
+ * verified switch.
+ */
+export function m6Copy(host) {
+    const existing = new Map(host.existingV2().map((r) => [`${r.session}::${r.key}`, r]));
+    const wanted = [];
+    for (const session of host.sessions()) {
+        for (const oldKey of host.oldKeysOf(session)) {
+            const derived = deriveRouterGenRow(host, session, oldKey);
+            if (!derived.ok)
+                continue; // bad old key surfaced by verify, not lost silently
+            const stored = existing.get(`${session}::${derived.row.key}`);
+            if (stored !== undefined && rowMatches(stored, derived.row))
+                continue; // healthy
+            wanted.push(derived.row);
+        }
+    }
+    if (wanted.length > 0)
+        host.putV2(wanted);
+    return { written: wanted, all: [...host.existingV2()] };
+}
+/** True when a persisted row already matches the authoritative derivation. */
+function rowMatches(stored, fresh) {
+    return (stored.session === fresh.session &&
+        stored.generation === fresh.generation &&
+        stored.sourceStart === fresh.sourceStart &&
+        stored.sourceEnd === fresh.sourceEnd &&
+        stored.algorithm === fresh.algorithm &&
+        stored.key === fresh.key &&
+        stored.digest === fresh.digest);
+}
+/**
+ * Verify the migrated query set: every old query key across every session has a
+ * v2 row (exact-once), every row's key is canonical + re-hashes, and the new set
+ * is partition-preserving — every row's session is exactly the session of the
+ * old key it was derived from (rejects cross-session eviction). Never mutates.
+ *
+ * Comparison of old/new query sets is exact-by-identity (structured key bytes),
+ * never by string prefix.
+ */
+export function m6Verify(host) {
+    const codes = [];
+    const stored = host.existingV2();
+    // Expected slot inventory: (session, canonical key) for every derivable old key.
+    const expectedSlots = [];
+    const badOldKeys = [];
+    for (const session of host.sessions()) {
+        for (const oldKey of host.oldKeysOf(session)) {
+            const parsed = host.parseOldKey(session, oldKey);
+            if (!parsed.ok) {
+                badOldKeys.push({ session, oldKey });
+                continue;
+            }
+            if (parsed.key.session !== session) {
+                // A structured key that claims a different session is a cross-session
+                // eviction attempt — never migrated, never evicted.
+                codes.push(M6_FAIL.CROSS_SESSION_EVICTION);
+                continue;
+            }
+            expectedSlots.push({ session, oldKey });
+        }
+    }
+    if (badOldKeys.length > 0)
+        codes.push(M6_FAIL.BAD_OLD_KEY);
+    // Map stored rows by their (session,key) identity.
+    const byIdentity = new Map();
+    const duplicateCheck = new Map();
+    for (const r of stored) {
+        const ident = `${r.session}::${r.key}`;
+        byIdentity.set(ident, r);
+        duplicateCheck.set(ident, (duplicateCheck.get(ident) ?? 0) + 1);
+    }
+    // Each expected slot must be present exactly once, with a healthy row.
+    for (const slot of expectedSlots) {
+        const parsed = host.parseOldKey(slot.session, slot.oldKey);
+        if (!parsed.ok)
+            continue;
+        const expectedKey = encodeRouterKeyV2(parsed.key);
+        const ident = `${slot.session}::${expectedKey}`;
+        const count = duplicateCheck.get(ident) ?? 0;
+        if (count === 0)
+            codes.push(M6_FAIL.COPY_PARTIAL);
+        if (count > 1)
+            codes.push(M6_FAIL.COUNT_MISMATCH);
+    }
+    // Row health: digest re-hashes + session partition-preserving.
+    for (const r of stored) {
+        if (!r.key.startsWith("rk2:"))
+            codes.push(M6_FAIL.DIGEST_MISMATCH);
+        const expectedDigest = sha256Hex(Buffer.from(r.key.slice(4), "hex"));
+        if (r.digest !== expectedDigest)
+            codes.push(M6_FAIL.DIGEST_MISMATCH);
+        // The row's own structured key must decode and agree with its declared fields.
+        const dec = decodeRow(r);
+        if (!dec)
+            codes.push(M6_FAIL.DIGEST_MISMATCH);
+    }
+    // No stored row may be an orphan (no corresponding old key anywhere).
+    const expectedIdentities = new Set();
+    for (const slot of expectedSlots) {
+        const parsed = host.parseOldKey(slot.session, slot.oldKey);
+        if (!parsed.ok)
+            continue;
+        expectedIdentities.add(`${slot.session}::${encodeRouterKeyV2(parsed.key)}`);
+    }
+    for (const ident of byIdentity.keys()) {
+        if (!expectedIdentities.has(ident))
+            codes.push(M6_FAIL.COUNT_MISMATCH);
+    }
+    const ok = codes.length === 0;
+    return { ok, codes: dedupe(codes) };
+}
+/**
+ * Self-consistent decode of a stored row: its canonical key decodes to a
+ * RouterKeyV2 whose five fields equal the row's declared fields. A row whose key
+ * doesn't round-trip against its own declared session/generation/range/algorithm
+ * is corrupt (cannot be trusted as the query set's identity).
+ */
+function decodeRow(r) {
+    if (!r.key.startsWith("rk2:"))
+        return false;
+    const hex = r.key.slice(4);
+    if (!/^[0-9a-f]+$/.test(hex) || hex.length % 2 !== 0)
+        return false;
+    const dec = decodeRouterKeyV2(r.key);
+    if (!dec.ok)
+        return false;
+    return (dec.key.session === r.session &&
+        dec.key.generation === r.generation &&
+        dec.key.sourceStart === r.sourceStart &&
+        dec.key.sourceEnd === r.sourceEnd &&
+        dec.key.algorithm === r.algorithm);
+}
+/**
+ * Switch the active version to 2. Only call after `m6Verify` reports ok; a
+ * crash/return before switch leaves the legacy pointer active (interruption
+ * keeps old authority, resumable idempotently).
+ */
+export function m6Switch(host) {
+    if (host.activeVersion() !== ROUTER_GEN_LEGACY_VERSION)
+        return;
+    host.switchToV2();
+}
+/** Full M6 lifecycle: copy -> verify -> switch; returns the verify result. */
+export function migrateRouterGenerationV2(host) {
+    m6Copy(host);
+    const v = m6Verify(host);
+    if (v.ok)
+        m6Switch(host);
+    return v;
+}
+/** Registered M6 conformance ID range (M6-001..012). */
+export const M6_IDS = [
+    "M6-001",
+    "M6-002",
+    "M6-003",
+    "M6-004",
+    "M6-005",
+    "M6-006",
+    "M6-007",
+    "M6-008",
+    "M6-009",
+    "M6-010",
+    "M6-011",
+    "M6-012",
+];
+/** Registered named M6 conformance IDs. */
+export const M6_NAMED_IDS = [
+    "M6-KEY-001",
+    "M6-STALE-002",
+];
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}

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