pi-mega-compact 0.19.0 → 0.19.2

package/src/vector-cortex/cortex/store.ts

@@ -0,0 +1,202 @@
+/**
+ * vector-cortex/cortex/store.ts — VC3A capability-separated cortex store contracts.
+ *
+ * Owns the `createCortexStore` factory producing `CortexReader` / `CortexWriter`
+ * / `CortexAdmin` capability views over the isolated cortex SQLite store. The
+ * writer exposes append only, the reader exposes query only, and the admin alone
+ * can rebuild/switch generations (task 2). No callbacks or event emitters flow
+ * from the store; writes are non-fatal (a failure logs and never breaks the agent
+ * loop).
+ *
+ * The two VC3A events (task 5) are emitted by this store:
+ *
+ *   vector_cortex_record_append_failed    — an append was rejected / failed
+ *   vector_cortex_generation_rebuilt      — the admin rebuilt + activated a generation
+ *
+ * Both are gated on `MEGACOMPACT_VC3A` so the flag-OFF path emits zero events
+ * (mode C parity, byte-identical predecessor).
+ *
+ * Capability gating mirrors the host `asReader/asWriter/asAdmin` and VC1B ledger
+ * pattern. Each consumer receives ONLY what it needs. The dashboard reader-only
+ * GET is built on the reader surface alone.
+ *
+ * Pi-agnostic. No console.log. No network (PREVENT-PI-004). No `any`
+ * (PREVENT-011).
+ */
+
+import { VC3A_ENABLED } from "../../config/vector-cortex.js";
+import { Logger } from "../../log.js";
+import type {
+  CortexAdmin,
+  CortexAppendInput,
+  CortexGenerationV1,
+  CortexReader,
+  CortexTopologySummary,
+  CortexWriter,
+} from "./types.js";
+import {
+  openCortexStore,
+  insertCortexRecord,
+  readCortexRecord,
+  countCortexRecords,
+  readCortexRecords,
+  rebuildCortexGeneration,
+  switchCortexGeneration,
+  activeGeneration,
+  listCortexGenerations,
+  maxSourceHighWater,
+} from "./sqlite.js";
+import type { DatabaseSync } from "node:sqlite";
+
+/** Optional structured-event emitter (same shape as the other VC seams). */
+export type CortexEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/** The token that gates closures to a single capability (PREVENT-011-free). */
+const _capability: unique symbol = Symbol("mc-cortex-capability");
+
+interface ReaderToken {
+  readonly [_capability]: "reader";
+}
+interface WriterToken {
+  readonly [_capability]: "writer";
+}
+interface AdminToken {
+  readonly [_capability]: "admin";
+}
+
+/** A capability-gated cortex handle: access only what you were handed. */
+export interface CortexHandle {
+  readonly reader: () => CortexReader & ReaderToken;
+  readonly writer: () => CortexWriter & WriterToken;
+  readonly admin: () => CortexAdmin & AdminToken;
+  /** Close the underlying DB handle (test/sandbox teardown). */
+  readonly close: () => void;
+}
+
+/**
+ * Create the capability-separated cortex derived store over its OWN isolated
+ * SQLite DB. `emit` is optional; the two VC3A events are only emitted when
+ * `VC3A_ENABLED()` and an emitter is supplied (mode-C parity: flag OFF / no
+ * emitter => zero observability writes).
+ *
+ * Normalization: `stateDir` gives the standard daemon location
+ * `<stateDir>/vector-cortex/cortex.db`; a bare `dbPath` overrides it
+ * (tests/rehearsal isolate the cortex store). An injected `db` (an already-open
+ * `DatabaseSync`) is a dependency-injection seam used by the failure-injection
+ * tests to drive the REAL storage-refusal path (e.g. `PRAGMA query_only`) through
+ * the store's own writer — a genuine store, no mock.
+ */
+export function createCortexStore(
+  opts:
+    | { readonly stateDir: string }
+    | { readonly dbPath: string }
+    | { readonly db: DatabaseSync },
+  emit?: CortexEmit,
+): CortexHandle {
+  const db =
+    "db" in opts
+      ? opts.db
+      : openCortexStore(
+          "dbPath" in opts
+            ? opts.dbPath
+            : `${opts.stateDir}/vector-cortex/cortex.db`,
+        );
+
+  // A caller that invokes the writer/admin seam without injecting an emitter gets
+  // a REAL default producer (structured logger) so telemetry is never silently
+  // dropped — an explicit `emit:` replaces it. The dashboard reader-only route
+  // never appends/rebuilds, so it fires nothing regardless; a future writer/admin
+  // host integration enjoys default observability out of the box (VC3B wiring).
+  const sink = emit ?? defaultEmitFor();
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    if (!VC3A_ENABLED()) return;
+    try {
+      sink(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+
+  const asReader = (): CortexReader & ReaderToken => ({
+    kind: "CortexReader",
+    [_capability]: "reader" as const,
+    recordCount: () => countCortexRecords(db),
+    readRecords: () => readCortexRecords(db),
+    readRecord: (sourceHighWater, algorithmVersion, id) =>
+      readCortexRecord(db, sourceHighWater, algorithmVersion, id),
+    latestGeneration: () => activeGeneration(db),
+    topologySummary: () => topologyOf(db, VC3A_ENABLED()),
+  });
+
+  const asWriter = (): CortexWriter & WriterToken => ({
+    kind: "CortexWriter",
+    [_capability]: "writer" as const,
+    append(input) {
+      const result = insertCortexRecord(db, input);
+      // Any rejected/failed append (CTX_KEY_CONFLICT, CTX_APPEND_FAILED, or any
+      // future code) surfaces the SAME event; the `code` field distinguishes a
+      // key-conflict (rejected append) from a storage failure (CTX_APPEND_FAILED).
+      if (!result.ok) {
+        fire("vector_cortex_record_append_failed", {
+          sourceHighWater: input.sourceHighWater.toString(),
+          algorithmVersion: input.algorithmVersion,
+          id: input.id,
+          kind: input.kind,
+          code: result.code,
+        });
+      }
+      return result;
+    },
+  });
+
+  const asAdmin = (): CortexAdmin & AdminToken => ({
+    kind: "CortexAdmin",
+    [_capability]: "admin" as const,
+    rebuild(authorityHighWater?: bigint) {
+      const result = rebuildCortexGeneration(db, { authorityHighWater });
+      if (result.ok) {
+        fire("vector_cortex_generation_rebuilt", {
+          generationId: result.generation.id,
+          ordinal: result.generation.ordinal.toString(),
+          sourceHighWater: result.generation.sourceHighWater.toString(),
+          recordCount: result.generation.recordCount,
+          rootDigest: result.generation.rootDigest,
+        });
+      }
+      return result;
+    },
+    switchGeneration: (generationId) => switchCortexGeneration(db, generationId),
+    listGenerations: () => listCortexGenerations(db),
+  });
+
+  return { reader: asReader, writer: asWriter, admin: asAdmin, close: () => db.close() };
+}
+
+/** Build the reader-only topology summary (the dashboard GET payload). */
+function topologyOf(db: DatabaseSync, enabled: boolean): CortexTopologySummary {
+  const gen = activeGeneration(db);
+  return {
+    enabled,
+    generationId: gen ? gen.id : null,
+    rootDigest: gen ? gen.rootDigest : null,
+    sourceHighWater: (gen ? gen.sourceHighWater : maxSourceHighWater(db)).toString(),
+    recordCount: countCortexRecords(db),
+    ordinal: gen ? gen.ordinal.toString() : null,
+  };
+}
+
+/**
+ * A deterministic default emitter backed by the structured logger. Supplying an
+ * explicit `emit:` replaces it. Making the default a REAL producer means a caller
+ * that just invokes the writer/admin seam without injecting an emitter still
+ * yields structured telemetry instead of silently dropping every event.
+ */
+function defaultEmitFor(): CortexEmit {
+  const logger = new Logger();
+  return (event, fields) => {
+    logger.info(event, fields);
+  };
+}
+
+/** Re-export the generation type for convenience in admin consumers. */
+export type { CortexGenerationV1, CortexAppendInput };

package/src/vector-cortex/cortex/types.ts

@@ -0,0 +1,194 @@
+/**
+ * vector-cortex/cortex/types.ts — capability-gated cortex store contract (VC3A).
+ *
+ * Owns `CortexReader` / `CortexWriter` / `CortexAdmin` and `CortexRecordV1`
+ * (the immutable derived record). Consumes only reviewer-accepted predecessor
+ * contracts and [common contracts](../../CONTRACTS.md §Store and migration
+ * contracts), which are NORMATIVE here: the derived frontier cannot exceed the
+ * contiguous durable authority high-water and cannot advance during
+ * authority/spool outage.
+ *
+ * A CortexRecordV1 is a DERIVED record keyed by
+ * `(sourceHighWater, algorithmVersion, id)`. The same `id` at a different
+ * `algorithmVersion` (or a different `sourceHighWater`) is a DISTINCT record —
+ * never collapsed (CTX-KEY-002). Records are immutable: re-appending an exact
+ * `(sourceHighWater, algorithmVersion, id)` with the SAME `payloadDigest` is an
+ * idempotent acknowledge; the same key with a DIFFERENT digest is a conflict.
+ *
+ * Capability gating mirrors the host `asReader/asWriter/asAdmin` pattern and the
+ * VC1B ledger: the writer exposes append only, the reader exposes query only,
+ * and the admin alone can rebuild / switch generations. No callbacks or event
+ * emitters flow from the store; writes are non-fatal (failures log and never
+ * break the agent loop).
+ *
+ * Pure type/schema definitions + small pure predicates. No storage, no console,
+ * no network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/**
+ * A derived cortex record — byte authority is `payloadBytes`; `payloadDigest` is
+ * the authoritative `sha256:<hex>` over those bytes. `sourceHighWater` is the
+ * durable authority high-water the record was derived AT (the derived frontier
+ * cannot exceed it); `algorithmVersion` is the producing algorithm revision.
+ */
+export interface CortexRecordV1 {
+  readonly schema: "cortex-record-v1";
+  /** Durable contiguous authority high-water this record derives from. */
+  readonly sourceHighWater: bigint;
+  /** Producing algorithm revision (records at distinct versions stay distinct). */
+  readonly algorithmVersion: number;
+  /** Stable record identity within the derived store. */
+  readonly id: string;
+  /** Record kind (semantic / dependency / contradiction / synthetic...). */
+  readonly kind: string;
+  /** Authoritative `sha256:<hex>` of `payloadBytes` (immutability anchor). */
+  readonly payloadDigest: string;
+  /** Immutable derived payload bytes (byte authority for the record). */
+  readonly payloadBytes: Uint8Array;
+}
+
+/**
+ * A derived GENEration — a named, digest-pinned front over the sorted accepted
+ * records. `rootDigest` is ONE deterministic digest over the canonical sorted
+ * key list (order-independent, CTX-REBUILD-003); `sourceHighWater` is the derived
+ * frontier (max sourceHighWater across its records).
+ */
+export interface CortexGenerationV1 {
+  readonly schema: "cortex-generation-v1";
+  readonly id: string;
+  readonly sourceHighWater: bigint;
+  readonly recordCount: number;
+  readonly rootDigest: string;
+  /** Monotonic rebuild ordinal (never regresses for an accepted generation). */
+  readonly ordinal: bigint;
+}
+
+/** Failure codes the writer surfaces on a rejected / failed append. */
+export type CortexAppendCode =
+  /** Storage failure (e.g. SQLITE_FULL). Non-fatal; host continues in mode C. */
+  | "CTX_APPEND_FAILED"
+  /** Same (sourceHighWater, algorithmVersion, id) but a different payloadDigest. */
+  | "CTX_KEY_CONFLICT";
+
+/** Result of a single append attempt. */
+export type CortexAppendResult =
+  | { ok: true; record: CortexRecordV1 }
+  | { ok: false; code: CortexAppendCode; rejected: CortexRecordV1 };
+
+/** Failure codes the admin surfaces on a rejected rebuild. */
+export type CortexRebuildCode =
+  /** A record's payloadDigest does not match its payloadBytes (authority corrupt). */
+  | "CTX_PAYLOAD_DIGEST_MISMATCH"
+  /** A record exceeds the caller's declared generation source high-water. */
+  | "CTX_HIGH_WATER_EXCEEDED"
+  /** The generation INSERT/activate write did not persist (storage failure, e.g. SQLITE_FULL). */
+  | "CTX_REBUILD_FAILED";
+
+/**
+ * Reader capability: query-only. The dashboard's reader-only GET
+ * `GET /api/vector-cortex/topology` is built on exactly this surface and nothing
+ * more — it can read the generation/topology summary and records but never
+ * append, rebuild, or switch generations.
+ */
+export interface CortexReader {
+  readonly kind: "CortexReader";
+  /** Count of accepted derived records. */
+  recordCount(): number;
+  /** Accepted records in ascending `(sourceHighWater, algorithmVersion, id)`. */
+  readRecords(): readonly CortexRecordV1[];
+  /** The single record at a composite key, or undefined. */
+  readRecord(sourceHighWater: bigint, algorithmVersion: number, id: string): CortexRecordV1 | undefined;
+  /** The latest (active) generation, or undefined when none rebuilt yet. */
+  latestGeneration(): CortexGenerationV1 | undefined;
+  /** Reader-only topology summary (the dashboard GET payload). */
+  topologySummary(): CortexTopologySummary;
+}
+
+/**
+ * Writer capability: append-only. Can add immutable derived records — but cannot
+ * query arbitrary history, rebuild, or touch generations. Enforces the composite
+ * key immutability on every append.
+ */
+export interface CortexWriter {
+  readonly kind: "CortexWriter";
+  /** Append one derived record; idempotent ack on exact key+digest, conflict otherwise. */
+  append(input: CortexAppendInput): CortexAppendResult;
+}
+
+/**
+ * Admin capability: maintenance + generation control ONLY. The sole surface with
+ * rebuild / switch-generations capability — never exposed to ingestion or the
+ * dashboard reader.
+ */
+export interface CortexAdmin {
+  readonly kind: "CortexAdmin";
+  /**
+   * Deterministically rebuild a generation from ALL accepted records: sorts keys,
+   * verifies each payload digest, computes ONE root digest, writes + activates a
+   * new generation. Idempotent with respect to unchanged accepted inputs.
+   *
+   * `authorityHighWater` (optional) is the contiguous durable authority high-water
+   * the rebuild must not outrun. When supplied and the derived frontier (max
+   * record sourceHighWater) exceeds it, the rebuild is rejected with
+   * `CTX_HIGH_WATER_EXCEEDED` and NO generation is written — the derived frontier
+   * cannot exceed the durable authority high-water (normative in CONTRACTS.md).
+   * Omit it to rebuild without an authority bound.
+   */
+  rebuild(authorityHighWater?: bigint):
+    | { ok: true; generation: CortexGenerationV1 }
+    | { ok: false; code: CortexRebuildCode };
+  /** Switch the active generation pointer without deleting evidence. */
+  switchGeneration(generationId: string): { ok: boolean; code?: string };
+  /** List every generation id in ascending ordinal order (evidence retained). */
+  listGenerations(): readonly CortexGenerationV1[];
+}
+
+/** Input shape of a single append (record fields minus the readonly full type). */
+export interface CortexAppendInput {
+  readonly sourceHighWater: bigint;
+  readonly algorithmVersion: number;
+  readonly id: string;
+  readonly kind: string;
+  readonly payloadDigest?: string;
+  readonly payloadBytes: Uint8Array;
+}
+
+/**
+ * Reader-only topology summary — the exact payload of the dashboard
+ * `GET /api/vector-cortex/topology` reader-only GET. Aggregate only: root digest
+ * prefix, record count, derived frontier. Never exposes writer/admin surfaces or
+ * raw record payloads.
+ */
+export interface CortexTopologySummary {
+  /** Whether the VC3A cortex-store flag is enabled. */
+  readonly enabled: boolean;
+  /** Active generation id, or null when no generation rebuilt yet. */
+  readonly generationId: string | null;
+  /** Active generation root digest (or null). */
+  readonly rootDigest: string | null;
+  /** Derived frontier (active generation sourceHighWater, or "0"). */
+  readonly sourceHighWater: string;
+  /** Accepted derived record count. */
+  readonly recordCount: number;
+  /** Monotonic rebuild ordinal (or null). */
+  readonly ordinal: string | null;
+}
+
+/**
+ * Registered CTX conformance ID range (CTX-001..010). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest bytes or
+ * exactly its listed failure code. The three NAMED assertions
+ * (CTX-CAP-001 / CTX-KEY-002 / CTX-REBUILD-003) live in the acceptance test.
+ */
+export const CTX_IDS = [
+  "CTX-001",
+  "CTX-002",
+  "CTX-003",
+  "CTX-004",
+  "CTX-005",
+  "CTX-006",
+  "CTX-007",
+  "CTX-008",
+  "CTX-009",
+  "CTX-010",
+] as const;

package/src/vector-cortex/topology/build.ts

@@ -0,0 +1,259 @@
+/**
+ * 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,
+  type TopologyBuildResult,
+  type TopologyCandidate,
+  type TopologyEdgeV1,
+  type TopologyInput,
+  type TopologyNodeV1,
+  type TopologyRejection,
+  type TopologyV1,
+} 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: TopologyInput): TopologyBuildResult {
+  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<string, TopologyCandidate[]>();
+  const rejections: TopologyRejection[] = [];
+
+  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: TopologyCandidate[] = [];
+  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: Map<string, TopologyEdgeV1> = new Map();
+  const nodes = new Map<string, TopologyNodeKind>();
+  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: TopologyNodeV1[] = [...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: TopologyV1 = {
+    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: TopologyCandidate, code: TopologyRejection["code"]): TopologyRejection {
+  return { source: c.source, target: c.target, head: c.head, score: c.score, code };
+}
+
+function groupKey(source: string, head: string): string {
+  return JSON.stringify([source, head]);
+}
+
+function pairKey(a: string, b: string): string {
+  return JSON.stringify([a, b, " "]);
+}
+
+function dirKey(a: string, b: string, head: string, direction: string): string {
+  return JSON.stringify([a, b, head, direction]);
+}
+
+function compareCandidates(a: TopologyCandidate, b: TopologyCandidate): number {
+  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: TopologyCandidate, b: TopologyCandidate): number {
+  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: TopologyEdgeV1, b: TopologyEdgeV1): number {
+  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: string, b: string): number {
+  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: TopologyCandidate): TopologyNodeKind {
+  return c.kind === "contradiction" ? "contradiction" : "dependency";
+}
+
+type TopologyNodeKind = "semantic" | "dependency" | "contradiction" | "synthetic";