pi-mega-compact 0.19.1 → 0.19.3

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -138,6 +138,41 @@ export interface VectorCortexTopologyView {
   readonly recordCount: number;
   /** Monotonic rebuild ordinal, or null. */
   readonly ordinal: string | null;
+  /**
+   * VC3B deterministic topology node/edge shapes — present ONLY when the VC3B
+   * flag is enabled (flag-off omits them, byte-identical to the VC3A
+   * predecessor view). Built reader-only from the accepted derived records and
+   * best-effort: an unavailable or un-stored graph degrades to empty arrays,
+   * never an error. The exact node (`id`/`kind`) and edge
+   * (`source`/`target`/`head`/`score`/`direction`) shapes match TopologyV1.
+   */
+  readonly nodes?: readonly { id: string; kind: string }[];
+  readonly edges?: readonly {
+    source: string;
+    target: string;
+    head: string;
+    score: number;
+    direction: string;
+  }[];
+  /** Stable graph generation digest (VC3B), when the graph was built. */
+  readonly generationDigest?: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
+/**
+ * Reader-only query-layer diagnostics view for GET /api/vector-cortex/query
+ * (VC3C). Purely a flag-status + structural diagnostic — reports whether the
+ * VC3C flag is enabled and the router-generation v2 version constant. The VC3C
+ * query index is in-memory (not durable), so no payloads, prompts, or index
+ * contents are ever exposed. Non-fatal: a missing state dir or internal error
+ * degrades to `enabled:false`.
+ */
+export interface VectorCortexQueryView {
+  /** Whether the VC3C query-layer flag is enabled in this process. */
+  readonly enabled: boolean;
+  /** Router-generation v2 key version constant (query index format). */
+  readonly routerVersion: number;
   /** ISO timestamp of the snapshot. */
   readonly updatedAt: string;
 }

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -337,6 +337,18 @@ export const SETTINGS: ReadonlyArray<{
 				"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/extensions/dashboard-server/routes-vector-cortex-query.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+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";
+import type { VectorCortexQueryView } from "./api-contracts/vector-cortex.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/query (VC3C query-layer diagnostics).
+ */
+export function handleVectorCortexQuery(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  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: VectorCortexQueryView = {
+    enabled,
+    routerVersion: ROUTER_KEY_VERSION,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/dashboard-server/routes-vector-cortex-topology.ts

@@ -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,19 +10,34 @@
  * (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 type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
-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 type { TopologyCandidate, TopologyEmit } from "../../src/vector-cortex/topology/index.js";
+import type { CortexRecordV1 } from "../../src/vector-cortex/cortex/types.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
 import type { VectorCortexTopologyView } from "./api-contracts/vector-cortex.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: IncomingMessage,
@@ -39,6 +54,7 @@ export function handleVectorCortexTopology(
   }
 
   const enabled = VC3A_ENABLED();
+  const topologyEnabled = VC3B_ENABLED();
   let active = enabled;
   let summary: {
     generationId: string | null;
@@ -47,12 +63,22 @@ export function handleVectorCortexTopology(
     recordCount: number;
     ordinal: string | null;
   } = { generationId: null, rootDigest: null, sourceHighWater: "0", recordCount: 0, ordinal: null };
+  let nodes: { id: string; kind: string }[] | undefined;
+  let edges: {
+    source: string;
+    target: string;
+    head: string;
+    score: number;
+    direction: string;
+  }[] | undefined;
+  let generationDigest: string | null | undefined;
 
   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,
@@ -60,6 +86,12 @@ export function handleVectorCortexTopology(
           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();
       }
@@ -76,8 +108,137 @@ export function handleVectorCortexTopology(
     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: readonly CortexRecordV1[]): {
+  nodes: { id: string; kind: string }[];
+  edges: { source: string; target: string; head: string; score: number; direction: string }[];
+  generationDigest: string | null;
+} {
+  const candidates: TopologyCandidate[] = [];
+  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: 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: CortexRecordV1): TopologyCandidate | undefined {
+  let text: string;
+  try {
+    text = new TextDecoder().decode(r.payloadBytes);
+  } catch {
+    return undefined;
+  }
+  try {
+    const v: unknown = JSON.parse(text);
+    if (
+      v === null ||
+      typeof v !== "object" ||
+      Array.isArray(v)
+    ) {
+      return undefined;
+    }
+    const o = v as Record<string, unknown>;
+    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/extensions/dashboard-server/routes-vector-cortex.ts

@@ -18,3 +18,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/extensions/dashboard-server/routes.ts

@@ -46,4 +46,5 @@ export {
 	handleVectorCortexBreakersReset,
 	handleVectorCortexLedger,
 	handleVectorCortexTopology,
+	handleVectorCortexQuery,
 } from "./routes-vector-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -61,6 +61,7 @@ import {
 	handleVectorCortexBreakersReset,
 	handleVectorCortexLedger,
 	handleVectorCortexTopology,
+	handleVectorCortexQuery,
 	handleStatic,
 } from "./routes.js";
 
@@ -285,6 +286,7 @@ export async function launchDashboardServer(
 		if (handleVectorCortexBreakersReset(req, res, ctx)) return;
 		if (handleVectorCortexLedger(req, res, ctx)) return;
 		if (handleVectorCortexTopology(req, res, ctx)) return;
+		if (handleVectorCortexQuery(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -111,6 +111,29 @@ export const VC2C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2C");
  */
 export const VC3A_ENABLED = (): boolean => 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 = (): boolean => 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 = (): boolean => 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/src/config.ts

@@ -161,6 +161,8 @@ export {
   VC2B_ENABLED,
   VC2C_ENABLED,
   VC3A_ENABLED,
+  VC3B_ENABLED,
+  VC3C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/tieredRouter.ts

@@ -16,6 +16,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, type RouterKeyV2 } 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";
@@ -343,6 +346,12 @@ export class TieredRouter {
     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: RouterKeyV2): void {
+    routerGenerationInvalidationSeam(key, VC3C_ENABLED(), (e, f) => new Logger().info(e, f));
+  }
+
   /** Snapshot of current metrics for dashboard / logging. */
   getMetrics(): TieredRouterMetrics {
     const q = Math.max(this.totalQueries, 1);