pi-mega-compact 0.19.1 → 0.19.3

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/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",
+];