pi-mega-compact 0.19.2 → 0.19.3

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

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;
+}