pi-mega-compact 0.19.2 → 0.20.0

package/dist/config/vector-cortex.js

@@ -110,6 +110,30 @@ export const VC3A_ENABLED = () => sprintFlag("MEGACOMPACT_VC3A");
  * 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");
+/**
+ * VC4A — dual-tier shard contract (SemanticShardV1 / ExactShardV1 /
+ * ShardManifestV1).
+ * Default ON. `MEGACOMPACT_VC4A=0` disables and is byte-identical to the
+ * predecessor (mode C: exact anchors/current transcript only, no semantic or
+ * exact shard manifest is assembled or emitted, zero
+ * `vector_cortex_shard_manifest_built` / `vector_cortex_protected_span_rejected`
+ * emissions; the predecessor derived pointer and goldens are unchanged). The
+ * real consumers are the shard assembly seam (manifest.ts) and the reader-only
+ * dashboard shards aggregate view.
+ */
+export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
 // ---------------------------------------------------------------------------
 // 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, VC3B_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, VC4A_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-cache.test/_helpers.js

@@ -25,6 +25,7 @@ export function freshDir(prefix) {
 }
 export async function withServer(port, dir, fn) {
     process.env.MEGACOMPACT_DASHBOARD_PORT = port;
+    process.env.MEGACOMPACT_DASHBOARD_HOST = "127.0.0.1";
     const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
     try {
         await waitFor(async () => {
@@ -43,6 +44,7 @@ export async function withServer(port, dir, fn) {
     finally {
         child.kill("SIGTERM");
         delete process.env.MEGACOMPACT_DASHBOARD_PORT;
+        delete process.env.MEGACOMPACT_DASHBOARD_HOST;
         rmSync(dir, { recursive: true, force: true });
     }
 }

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

@@ -145,6 +145,8 @@ export const SETTINGS = [
             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),
+            boolDirect("MEGACOMPACT_VC4A", "VC4A Dual-Tier Shards", "SemanticShardV1/ExactShardV1/ShardManifestV1: partition a session ONLY at complete EventV2 boundaries; exact shards preserve every tool call/result pair, anchor and invalid UTF-8 event as original bytes (pairs never split across exact shards); manifest enforces disjoint sorted ranges + complete protected-span coverage. OFF = mode C, exact anchors/current transcript only, byte-identical predecessor.", true),
         ],
     },
     {

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

@@ -0,0 +1,100 @@
+/**
+ * routes-vector-cortex-helpers.ts — shared spawn-and-fetch harness for the
+ * /api/vector-cortex/* route test files.
+ *
+ * The dashboard-server.js main block fires when the entry argv includes
+ * "dashboard-server", so tests under dist/extensions/dashboard-server/ MUST
+ * spawn the server as a child process rather than import launchDashboardServer.
+ * Extracted from routes-vector-cortex.test.ts so per-sprint route test files
+ * can share the harness without each re-implementing it.
+ *
+ * Reader-only: no payload bytes are ever returned by the routes under test.
+ */
+import { createHash } from "node:crypto";
+import { rmSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+/** Locate the repo root (the directory holding `conformance/vector-cortex`). */
+const HERE = dirname(fileURLToPath(import.meta.url));
+export function repoRoot(from = HERE) {
+    let dir = from;
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "conformance", "vector-cortex")))
+            return dir;
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    throw new Error("conformance corpus not found above " + from);
+}
+const REPO_ROOT = repoRoot();
+/** SHA-256 of the REAL committed ModelManifestV1 — the health card's digest. */
+export function realManifestDigest() {
+    // guardrails-allow PREVENT-PI-004: local committed asset filesystem read (loopback)
+    return createHash("sha256")
+        .update(readFileSync(join(REPO_ROOT, "assets", "vector-cortex", "encoder-v1", "manifest.json")))
+        .digest("hex");
+}
+export const SERVER_ENTRY = new URL("./server.js", import.meta.url).pathname;
+export function waitFor(cond, timeoutMs = 6000) {
+    const start = Date.now();
+    return new Promise((resolve, reject) => {
+        const tick = async () => {
+            if (await cond())
+                return resolve();
+            if (Date.now() - start > timeoutMs)
+                return reject(new Error("timeout"));
+            setTimeout(tick, 50);
+        };
+        tick();
+    });
+}
+export async function withServer(port, dir, fn) {
+    process.env.MEGACOMPACT_DASHBOARD_PORT = port;
+    // Pin loopback so the spawn-and-fetch harness stays hermetic even on a
+    // machine with tailscale0 (the production auto-bind would otherwise grab the
+    // tailnet IP and the localhost probe would connection-refuse). Tests that
+    // need a different host can set MEGACOMPACT_DASHBOARD_HOST before calling.
+    process.env.MEGACOMPACT_DASHBOARD_HOST = "127.0.0.1";
+    const child = spawn(process.execPath, [SERVER_ENTRY, dir], {
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            MEGACOMPACT_INDEX_DIR: dir,
+        },
+    });
+    try {
+        await waitFor(async () => {
+            try {
+                const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+                const res = await fetch(`http://localhost:${raw.port}/api/version`);
+                return res.ok;
+            }
+            catch {
+                return false;
+            }
+        });
+        const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+        return await fn(raw.port);
+    }
+    finally {
+        child.kill("SIGTERM");
+        delete process.env.MEGACOMPACT_DASHBOARD_PORT;
+        delete process.env.MEGACOMPACT_DASHBOARD_HOST;
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Seed redacted metric rows directly on disk so the server's reader sees them. */
+export async function seedEval(dir) {
+    const { appendEvalRow } = await import("../../src/vector-cortex/eval/persist.js");
+    // Buckets (inclusive): 1,5,10,25,50,100,250. 1ms→cell0, 12ms→cell3
+    // (<=25), 250ms→cell6, 300ms→overflow.
+    appendEvalRow(dir, [
+        { session: "s1", seq: 1, event: "encode", value: 1, unit: "ms", mode: "A" },
+        { session: "s1", seq: 2, event: "encode", value: 250, unit: "ms", mode: "A" },
+        { session: "s1", seq: 3, event: "encode", value: 300, unit: "ms", mode: "A" },
+        { session: "s1", seq: 4, event: "encode", value: 12, unit: "ms", mode: "A" },
+    ]);
+}

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-shards.js

@@ -0,0 +1,48 @@
+/**
+ * dashboard-server/routes-vector-cortex-shards.ts — VC4A dual-tier shard
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/shards returning a COUNT/BYTE aggregate
+ * (semantic shards, exact shards, protected byte total) — never shard payloads,
+ * verbatim exact bytes, or prompt text. Flag-gated on MEGACOMPACT_VC4A:
+ * `enabled:false` when off (byte-identical to the pre-VC4A predecessor).
+ *
+ * The VC4A shard partition is PURE IN-MEMORY logic in this sprint (it has no
+ * durable manifest store yet), so the aggregate reports the current status
+ * truthfully: `enabled` reflects the flag, and the count/byte fields are zero
+ * until a future sprint persists a staged manifest. This route is the seam that
+ * sprint will populate. Non-fatal: a missing state dir degrades to
+ * `enabled:false`.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem read only / in-process state),
+ * PREVENT-011 (no `any`), reader-only aggregate (counts/bytes only).
+ */
+import { VC4A_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+/**
+ * Reader-only GET /api/vector-cortex/shards (VC4A).
+ */
+export function handleVectorCortexShards(req, res, _ctx) {
+    const url = req.url ?? "";
+    const path = url.split("?")[0] ?? url;
+    if (path !== "/api/vector-cortex/shards")
+        return false;
+    if (req.method !== "GET") {
+        // Reader-only path: cannot be "off" without a GET; it is genuinely read-only.
+        sendJson(res, 405, { error: "method_not_allowed" });
+        return true;
+    }
+    const enabled = VC4A_ENABLED();
+    const body = {
+        enabled,
+        // No durable shard manifest is staged yet in this sprint (pure in-memory
+        // partition), so the aggregates are truthfully zero.
+        semanticCount: 0,
+        exactCount: 0,
+        byteTotal: 0,
+        protectedByteTotal: 0,
+        updatedAt: new Date().toISOString(),
+    };
+    sendJson(res, 200, body);
+    return true;
+}

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

@@ -17,3 +17,5 @@ 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";
+export { handleVectorCortexShards } from "./routes-vector-cortex-shards.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, handleVectorCortexShards, } from "./routes-vector-cortex.js";

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

@@ -13,7 +13,8 @@ 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 { detectTailscaleIP } from "./tailscale.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, handleVectorCortexShards, 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
@@ -166,13 +167,26 @@ export async function launchDashboardServer(stateDir) {
         serveClientAsset,
         detectCrossRepoDrift,
     });
+    // Bind host resolution: explicit MEGACOMPACT_DASHBOARD_HOST override wins;
+    // otherwise auto-bind to the Tailscale interface (tailnet access); fall back
+    // to loopback when Tailscale is absent. 0.0.0.0 means "all interfaces" and
+    // opts into permissive CORS below.
+    const host = process.env.MEGACOMPACT_DASHBOARD_HOST ??
+        detectTailscaleIP() ??
+        "127.0.0.1";
+    const allInterfaces = host === "0.0.0.0";
+    // guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard server (tailnet-local via Tailscale mesh or loopback); no remote outbound calls.
     const server = createServer((req, res) => {
-        // guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard localhost server (loopback-only) — CORS restricted to same-origin localhost browsers.
-        // CORS for local access — restricted to loopback origins (the dashboard server only binds to localhost).
+        // CORS for local access — restricted to loopback/same-origin tailnet
+        // origins (the dashboard server binds to localhost or the tailscale IP).
+        // With MEGACOMPACT_DASHBOARD_HOST=0.0.0.0 the user opted into
+        // all-interfaces binding, so we allow any origin.
         const origin = req.headers.origin;
-        if (typeof origin === "string" &&
-            /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
-            res.setHeader("Access-Control-Allow-Origin", origin);
+        const originAllowed = allInterfaces ||
+            (typeof origin === "string" &&
+                new RegExp(`^http://(localhost|127\\.0\\.0\\.1|::1|${host.replace(/\./g, "\\.")})(:\\d+)?$`).test(origin));
+        if (originAllowed) {
+            res.setHeader("Access-Control-Allow-Origin", origin ?? "*");
             res.setHeader("Vary", "Origin");
         }
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, OPTIONS");
@@ -251,6 +265,10 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleVectorCortexTopology(req, res, ctx))
             return;
+        if (handleVectorCortexQuery(req, res, ctx))
+            return;
+        if (handleVectorCortexShards(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,
@@ -272,26 +290,33 @@ export async function launchDashboardServer(stateDir) {
                     reject(err);
                 }
             });
-            server.listen(port, "127.0.0.1", () => {
-                const url = `http://localhost:${port}`; // guardrails-allow PREVENT-PI-004: localhost dashboard URL (loopback-only)
-                log("server running", { url });
+            server.listen(port, host, () => {
+                // When bound to the loopback, keep the legacy localhost URL so the
+                // user's browser (which resolves localhost → ::1 or 127.0.0.1) works.
+                // When bound to a tailnet/tailscale IP, surface that address instead.
+                const url = host === "127.0.0.1"
+                    ? `http://localhost:${port}`
+                    : `http://${host}:${port}`; // guardrails-allow PREVENT-PI-004: dashboard URL (tailnet-local via Tailscale mesh or loopback)
+                log("server running", { url, host });
                 // eslint-disable-next-line no-console
                 console.log(`[mega-compact] dashboard server running: ${url}`);
-                // v0.8.2: also bind the IPv6 loopback (::1). On many systems `localhost`
-                // resolves to ::1 first (see /etc/hosts), so an IPv4-only bind makes the
-                // browser hit ::1:port and get connection refused. PREVENT-PI-004
-                // (loopback-only) means BOTH 127.0.0.1 and ::1. Non-fatal: IPv4-only
-                // hosts or a ::1 already in use just skip the mirror.
+                // v0.8.2: also bind the IPv6 loopback (::1) when bound to the IPv4
+                // loopback. On many systems `localhost` resolves to ::1 first (see
+                // /etc/hosts), so an IPv4-only bind makes the browser hit ::1:port and
+                // get connection refused. PREVENT-PI-004 (loopback-only) means BOTH
+                // 127.0.0.1 and ::1. When bound to a tailscale/0.0.0.0 host, we do NOT
+                // bind ::1 — the tailnet address is what the user reaches. Non-fatal:
+                // IPv4-only hosts or a ::1 already in use just skip the mirror.
                 let v6;
                 const v4Handler = server.listeners("request")[0];
-                if (v4Handler) {
+                if (host === "127.0.0.1" && v4Handler) {
                     v6 = createServer((r, s) => v4Handler.call(server, r, s));
                     v6.on("error", (e) => log("ipv6 loopback bind skipped", {
                         port,
                         code: e.code,
                         message: e.message,
                     }));
-                    v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the localhost dashboard server
+                    v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the dashboard server
                 }
                 // Write port.pid
                 try {

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

@@ -1,3 +1,4 @@
+import { networkInterfaces } from "node:os";
 export function setupTailscaleServe(port = 3000, httpsPort = 443) {
     // Tailscale serve: exposes localhost dashboard securely.
     // Only activates when TAILSCALE_ENABLED=1 is set.
@@ -6,3 +7,34 @@ export function setupTailscaleServe(port = 3000, httpsPort = 443) {
     console.log(`[tailscale] Serve enabled on port ${port} (https:${httpsPort})`);
     return true;
 }
+// CGNAT block used by Tailscale for client addresses (100.64.0.0/10).
+const TAILSCALE_CGNAT_PREFIX = "100.";
+/**
+ * Detect the IPv4 address Tailscale has assigned to this host, so the dashboard
+ * server can auto-bind to the tailnet interface and be reachable from other
+ * devices on the tailnet. Returns null when Tailscale is not present.
+ *
+ * The default Tailscale interface name is `tailscale0` on Linux and `Tailscale`
+ * on macOS/Windows. We prefer an address inside Tailscale's CGNAT range
+ * (100.64.0.0/10) when one exists; otherwise we return the first IPv4 address
+ * found on the interface.
+ */
+export function detectTailscaleIP() {
+    const ifaces = networkInterfaces();
+    const candidates = [];
+    for (const [name, addrs] of Object.entries(ifaces)) {
+        if (name !== "tailscale0" && name !== "Tailscale")
+            continue;
+        if (!addrs)
+            continue;
+        for (const addr of addrs) {
+            if (addr.family === "IPv4") {
+                candidates.push(addr.address);
+            }
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    const cgnat = candidates.find((ip) => ip.startsWith(TAILSCALE_CGNAT_PREFIX));
+    return cgnat ?? candidates[0];
+}

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

@@ -110,6 +110,30 @@ export const VC3A_ENABLED = () => sprintFlag("MEGACOMPACT_VC3A");
  * 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");
+/**
+ * VC4A — dual-tier shard contract (SemanticShardV1 / ExactShardV1 /
+ * ShardManifestV1).
+ * Default ON. `MEGACOMPACT_VC4A=0` disables and is byte-identical to the
+ * predecessor (mode C: exact anchors/current transcript only, no semantic or
+ * exact shard manifest is assembled or emitted, zero
+ * `vector_cortex_shard_manifest_built` / `vector_cortex_protected_span_rejected`
+ * emissions; the predecessor derived pointer and goldens are unchanged). The
+ * real consumers are the shard assembly seam (manifest.ts) and the reader-only
+ * dashboard shards aggregate view.
+ */
+export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
 // ---------------------------------------------------------------------------
 // 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, VC3B_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, VC4A_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);