pi-mega-compact 0.19.1 → 0.19.3

package/dist/config/vector-cortex.js

@@ -101,6 +101,27 @@ export const VC2C_ENABLED = () => sprintFlag("MEGACOMPACT_VC2C");
  * cortex rebuild/admin seam and the reader-only topology summary seam.
  */
 export const VC3A_ENABLED = () => sprintFlag("MEGACOMPACT_VC3A");
+/**
+ * VC3B — deterministic cortical topology (TopologyV1 / EdgeV1).
+ * Default ON. `MEGACOMPACT_VC3B=0` disables and is byte-identical to the
+ * predecessor (mode C: no topology graph is built or emitted, the dashboard
+ * topology view returns the VC3A-precise aggregation shape with no node/edge
+ * arrays, zero `vector_cortex_topology_*` emissions). The real consumers are
+ * the topology build seam (build.ts) and the dashboard topology node/edge view.
+ */
+export const VC3B_ENABLED = () => sprintFlag("MEGACOMPACT_VC3B");
+/**
+ * VC3C — topology query + router invalidation (TopologyQueryV1 / RouterKeyV2,
+ * M6 router-generation-v2 migration).
+ * Default ON. `MEGACOMPACT_VC3C=0` disables and is byte-identical to the
+ * predecessor (mode C: no length-delimited router key, no generation
+ * invalidation, zero `vector_cortex_router_generation_invalidated` /
+ * `vector_cortex_topology_query_demoted` emissions; the predecessor tiered
+ * router keying is unchanged). The real consumers are the topology query seam
+ * (query.ts), the M6 router-generation-v2 migration seam, and the reader-only
+ * dashboard topology query diagnostic view.
+ */
+export const VC3C_ENABLED = () => sprintFlag("MEGACOMPACT_VC3C");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -144,6 +144,8 @@ export const SETTINGS = [
             boolDirect("MEGACOMPACT_VC2B", "VC2B Multi-Head Encoder", "VectorSetV1 five L2-normalized heads (384/128/128/64/32) with head-calibration draft + asset-free trigram B (512d) and lexical C fallbacks, plus the per-head emit seam. OFF = mode C, no per-head vectors emitted, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC2C", "VC2C Encoder Qualification + Calibration", "QualifiedEncoderV1/CalibrationV1: calibration fit on the calibration split only (held-out labels prohibited) + atomic selection across MODEL_ASSET and per-head EVALUATION thresholds (any field failure demotes all of A). OFF = mode C, no qualification/calibration selection, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC3A", "VC3A Cortex Store", "Capability-gated derived cortex store (CortexReader/Writer/Admin + CortexRecordV1): additive, keyed (sourceHighWater, algorithmVersion, id), immutable records, deterministic generation rebuild + one root digest. OFF = mode C, no cortex records written, byte-identical predecessor.", true),
+            boolDirect("MEGACOMPACT_VC3B", "VC3B Deterministic Topology", "Deterministic cortical topology (TopologyV1/EdgeV1): per-(source,head) top-k=16/head calibrated-threshold edges, stable score-desc/then-target-ID sort, dependency directed + contradiction symmetric paired records, one stable generation digest. OFF = mode C, no topology graph built/emitted, predecessor-precise topology view, byte-identical predecessor.", true),
+            boolDirect("MEGACOMPACT_VC3C", "VC3C Topology Query + Router Invalidation", "TopologyQueryV1/RouterKeyV2 structured keys (length-delimited, unsigned-byte order, no prefix ambiguity), exact (session,generation) invalidation, stale-generation rejection (TOP_GENERATION_STALE), and the M6 router-generation-v2 copy/validate/switch migration. OFF = mode C, no structured router key / generation invalidation, byte-identical predecessor.", true),
         ],
     },
     {

package/dist/extensions/dashboard-server/routes-vector-cortex-query.js

@@ -0,0 +1,46 @@
+/**
+ * dashboard-server/routes-vector-cortex-query.ts — VC3C vector-cortex query-layer
+ * diagnostics dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/query. Purely a flag-status + structural
+ * diagnostic: the VC3C query index is in-memory (not durable), so this route
+ * reports whether the VC3C flag is enabled, the router-generation v2 version
+ * constant, and a snapshot timestamp. It NEVER exposes payloads or prompts.
+ * Non-fatal: a missing state dir (or any internal error) degrades to
+ * `enabled:false`.
+ *
+ * Guardrails: PREVENT-PI-004 (local flag/config read only, no network),
+ * PREVENT-011 (no `any`), reader-only aggregate (never payloads/prompts).
+ */
+import { VC3C_ENABLED } from "../../src/config.js";
+import { ROUTER_KEY_VERSION } from "../../src/vector-cortex/topology/query.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+/**
+ * Reader-only GET /api/vector-cortex/query (VC3C query-layer diagnostics).
+ */
+export function handleVectorCortexQuery(req, res, _ctx) {
+    const url = req.url ?? "";
+    const path = url.split("?")[0] ?? url;
+    if (path !== "/api/vector-cortex/query")
+        return false;
+    if (req.method !== "GET") {
+        // Reader-only path: no mutation endpoint lives at /query.
+        sendJson(res, 405, { error: "method_not_allowed" });
+        return true;
+    }
+    let enabled = false;
+    try {
+        enabled = VC3C_ENABLED();
+    }
+    catch {
+        // Non-fatal: a missing/unavailable flag degrades to `enabled:false`.
+        enabled = false;
+    }
+    const body = {
+        enabled,
+        routerVersion: ROUTER_KEY_VERSION,
+        updatedAt: new Date().toISOString(),
+    };
+    sendJson(res, 200, body);
+    return true;
+}

package/dist/extensions/dashboard-server/routes-vector-cortex-topology.js

@@ -1,6 +1,6 @@
 /**
- * dashboard-server/routes-vector-cortex-topology.ts — VC3A vector-cortex topology
- * dashboard route.
+ * dashboard-server/routes-vector-cortex-topology.ts — VC3A/VC3B vector-cortex
+ * topology dashboard route.
  *
  * Reader-only GET /api/vector-cortex/topology built ENTIRELY on the CortexReader
  * capability: opens the isolated cortex DB for this repo's state dir and returns
@@ -10,14 +10,26 @@
  * (no writer/admin leakage). Non-fatal: a missing or corrupt cortex DB degrades
  * to `enabled:false`.
  *
+ * VC3B adds the deterministic node/edge shapes (TopologyV1) when both VC3A and
+ * VC3B are enabled: the accepted derived records of kind "topology" that carry a
+ * canonical TopologyCandidate JSON payload are fed through the deterministic
+ * build (buildTopologyGraph), whose stable generation digest + sorted node/edge
+ * arrays are returned. Bad/unparseable records are skipped (PREVENT-001), and
+ * with VC3B off the node/edge fields are omitted entirely — byte-identical to
+ * the VC3A predecessor view.
+ *
  * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
  * `any`), reader-only aggregate.
  */
-import { VC3A_ENABLED } from "../../src/config.js";
+import { VC3A_ENABLED, VC3B_ENABLED } from "../../src/config.js";
+import { Logger } from "../../src/log.js";
 import { createCortexStore } from "../../src/vector-cortex/cortex/store.js";
+import { buildTopologyGraph } from "../../src/vector-cortex/topology/index.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
+/** Well-known cortex record kind that carries a canonical candidate payload. */
+const TOPOLOGY_RECORD_KIND = "topology";
 /**
- * Reader-only GET /api/vector-cortex/topology (VC3A).
+ * Reader-only GET /api/vector-cortex/topology (VC3A + VC3B node/edge shapes).
  */
 export function handleVectorCortexTopology(req, res, ctx) {
     const url = req.url ?? "";
@@ -30,13 +42,18 @@ export function handleVectorCortexTopology(req, res, ctx) {
         return true;
     }
     const enabled = VC3A_ENABLED();
+    const topologyEnabled = VC3B_ENABLED();
     let active = enabled;
     let summary = { generationId: null, rootDigest: null, sourceHighWater: "0", recordCount: 0, ordinal: null };
+    let nodes;
+    let edges;
+    let generationDigest;
     if (enabled) {
         try {
             const store = createCortexStore({ stateDir: ctx.stateDir });
             try {
-                const s = store.reader().topologySummary();
+                const reader = store.reader();
+                const s = reader.topologySummary();
                 summary = {
                     generationId: s.generationId,
                     rootDigest: s.rootDigest,
@@ -44,6 +61,12 @@ export function handleVectorCortexTopology(req, res, ctx) {
                     recordCount: s.recordCount,
                     ordinal: s.ordinal,
                 };
+                if (topologyEnabled) {
+                    const built = buildFromRecords(reader.readRecords());
+                    nodes = built.nodes;
+                    edges = built.edges;
+                    generationDigest = built.generationDigest;
+                }
             }
             finally {
                 store.close();
@@ -61,8 +84,125 @@ export function handleVectorCortexTopology(req, res, ctx) {
         sourceHighWater: summary.sourceHighWater,
         recordCount: summary.recordCount,
         ordinal: summary.ordinal,
+        ...(topologyEnabled
+            ? { nodes, edges, generationDigest }
+            : {}),
         updatedAt: new Date().toISOString(),
     };
     sendJson(res, 200, body);
     return true;
 }
+/**
+ * Reconstruct the deterministic topology graph from the accepted derived records
+ * (reader-only, best-effort). Only records of kind "topology" whose payload is a
+ * canonical TopologyCandidate JSON are consumed; everything else is ignored.
+ * Returns empty arrays + null digest when no valid candidates are stored.
+ *
+ * The build seam is invoked with a logger-derived emit so the VC3B observability
+ * events (`vector_cortex_topology_built` / `vector_cortex_topology_edge_rejected`)
+ * fire on this production path — not just under unit tests. Best-effort and
+ * non-fatal: a failing emitter never breaks the agent loop.
+ *
+ * Q04 — DIVERGENCE RISK (documented, currently latent): the build is invoked
+ * with a hardcoded `threshold: 0` (plus `sessionId: "dashboard"` and
+ * `sourceHighWater: 0n`). This reflects the VC3B state where no production
+ * writer emits calibrated-threshold candidates yet, so retaining ALL stored
+ * "topology" records is correct for now. Once a real calibrated-threshold
+ * producer lands (VC3C), this dashboard digest will NOT derive from the
+ * authoritative threshold and can diverge from the canonical build for the same
+ * stored candidate set. The calibrated threshold must then be threaded through
+ * (e.g. sourced from the authority/config, not zero) before this route is treated
+ * as authoritative. Until then the route is explicitly best-effort display only.
+ */
+function buildFromRecords(records) {
+    const candidates = [];
+    for (const r of records) {
+        if (r.kind !== TOPOLOGY_RECORD_KIND)
+            continue;
+        const parsed = parseCandidatePayload(r);
+        if (parsed)
+            candidates.push(parsed);
+    }
+    const result = buildTopologyGraph({ sessionId: "dashboard", sourceHighWater: 0n, threshold: 0, candidates }, topologyEmit);
+    if (!result.ok)
+        return { nodes: [], edges: [], generationDigest: null };
+    return {
+        nodes: result.topology.nodes.map((n) => ({ id: n.id, kind: n.kind })),
+        edges: result.topology.edges.map((e) => ({
+            source: e.source,
+            target: e.target,
+            head: e.head,
+            score: e.score,
+            direction: e.direction,
+        })),
+        generationDigest: result.topology.generationDigest,
+    };
+}
+/**
+ * Logger-derived default emitter for the VC3B topology events. Mirrors the
+ * cortex store's `defaultEmitFor()` convention: a REAL structured-log producer so
+ * a caller that invokes the build seam without injecting an emitter still yields
+ * telemetry (best-effort, non-fatal). This is the production invoke point that
+ * makes the task-5 emission capable live (not dead under unit tests only).
+ */
+const topologyEmit = (event, fields) => {
+    new Logger().info(event, fields);
+};
+/**
+ * PREVENT-001: parse + shape-check a candidate payload before use. Returns
+ * undefined on any malformed/non-object input (best-effort, non-fatal).
+ *
+ * Q04 — FRAMING HARDENING: the canonical digest serialization in index.ts uses
+ * `|` (FIELD_SEP) and `~` (RECORD_SEP) as unambiguous delimiters between node
+ * ids/kinds and edge fields. That framing is collision-free only while id values
+ * (source/target/head) contain neither byte. Today ids are project-controlled, so
+ * this is latent, but a stored topology record could in principle carry a
+ * content-derived id containing those bytes, making the digest ambiguous
+ * (distinct graphs could collide) or the serialization injection-prone. To keep
+ * the digest well-defined for ANY input, reject candidates whose source/target/
+ * head contain the field/record separators; such a record is skipped (non-fatal)
+ * rather than fed into the digest.
+ */
+function parseCandidatePayload(r) {
+    let text;
+    try {
+        text = new TextDecoder().decode(r.payloadBytes);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const v = JSON.parse(text);
+        if (v === null ||
+            typeof v !== "object" ||
+            Array.isArray(v)) {
+            return undefined;
+        }
+        const o = v;
+        if (typeof o.source !== "string" ||
+            typeof o.target !== "string" ||
+            typeof o.head !== "string" ||
+            typeof o.score !== "number" ||
+            (o.kind !== "dependency" && o.kind !== "contradiction")) {
+            return undefined;
+        }
+        // Q04: reject any id that would corrupt the `|`/`~` digest framing.
+        if (FRAMING_SEP.test(o.source) ||
+            FRAMING_SEP.test(o.target) ||
+            FRAMING_SEP.test(o.head)) {
+            return undefined;
+        }
+        return {
+            source: o.source,
+            target: o.target,
+            head: o.head,
+            score: o.score,
+            kind: o.kind,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Field (`|`) and record (`~`) separators used by the canonical digest framing. */
+const FRAMING_SEP = /[|~]/;

package/dist/extensions/dashboard-server/routes-vector-cortex.js

@@ -17,3 +17,4 @@ export { handleVectorCortexEvaluation } from "./routes-vector-cortex-eval.js";
 export { handleVectorCortexHealth, handleVectorCortexBreakersReset } from "./routes-vector-cortex-health.js";
 export { handleVectorCortexLedger } from "./routes-vector-cortex-ledger.js";
 export { handleVectorCortexTopology } from "./routes-vector-cortex-topology.js";
+export { handleVectorCortexQuery } from "./routes-vector-cortex-query.js";

package/dist/extensions/dashboard-server/routes.js

@@ -23,4 +23,4 @@ export { handleRagSettings } from "./routes-rag-settings.js";
 export { handleRagMetrics } from "./routes-rag-metrics.js";
 export { handleModelThresholds } from "./routes-model-thresholds.js";
 export { handleWiki } from "./routes-wiki.js";
-export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, } from "./routes-vector-cortex.js";
+export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, } from "./routes-vector-cortex.js";

package/dist/extensions/dashboard-server/server.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { NEW_UI } from "../../src/config.js";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
-import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handlePerfSamples, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handlePerfSamples, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleStatic, } from "./routes.js";
 export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
@@ -251,6 +251,8 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleVectorCortexTopology(req, res, ctx))
             return;
+        if (handleVectorCortexQuery(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/src/config/vector-cortex.js

@@ -101,6 +101,27 @@ export const VC2C_ENABLED = () => sprintFlag("MEGACOMPACT_VC2C");
  * cortex rebuild/admin seam and the reader-only topology summary seam.
  */
 export const VC3A_ENABLED = () => sprintFlag("MEGACOMPACT_VC3A");
+/**
+ * VC3B — deterministic cortical topology (TopologyV1 / EdgeV1).
+ * Default ON. `MEGACOMPACT_VC3B=0` disables and is byte-identical to the
+ * predecessor (mode C: no topology graph is built or emitted, the dashboard
+ * topology view returns the VC3A-precise aggregation shape with no node/edge
+ * arrays, zero `vector_cortex_topology_*` emissions). The real consumers are
+ * the topology build seam (build.ts) and the dashboard topology node/edge view.
+ */
+export const VC3B_ENABLED = () => sprintFlag("MEGACOMPACT_VC3B");
+/**
+ * VC3C — topology query + router invalidation (TopologyQueryV1 / RouterKeyV2,
+ * M6 router-generation-v2 migration).
+ * Default ON. `MEGACOMPACT_VC3C=0` disables and is byte-identical to the
+ * predecessor (mode C: no length-delimited router key, no generation
+ * invalidation, zero `vector_cortex_router_generation_invalidated` /
+ * `vector_cortex_topology_query_demoted` emissions; the predecessor tiered
+ * router keying is unchanged). The real consumers are the topology query seam
+ * (query.ts), the M6 router-generation-v2 migration seam, and the reader-only
+ * dashboard topology query diagnostic view.
+ */
+export const VC3C_ENABLED = () => sprintFlag("MEGACOMPACT_VC3C");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/tieredRouter.js

@@ -15,6 +15,9 @@
 import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { VC3C_ENABLED } from "./config.js";
+import { Logger } from "./log.js";
+import { routerGenerationInvalidationSeam } from "./vector-cortex/topology/query.js";
 import { openStore } from "./store/sqlite/utils.js";
 import { fts5SearchScoped } from "./store/sqlite/fts5-search.js";
 import { listCheckpoints } from "./store/sqlite.js";
@@ -287,6 +290,11 @@ export class TieredRouter {
         this.cacheMap.clear();
         this.embeddingCache.clear();
     }
+    /** VC3C narrow delegate: exact (session,generation) RouterKeyV2 invalidation.
+     * No routing rewrite; `MEGACOMPACT_VC3C=0` is a strict no-op, byte-identical. */
+    invalidateGeneration(key) {
+        routerGenerationInvalidationSeam(key, VC3C_ENABLED(), (e, f) => new Logger().info(e, f));
+    }
     /** Snapshot of current metrics for dashboard / logging. */
     getMetrics() {
         const q = Math.max(this.totalQueries, 1);

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