pi-mega-compact 0.20.13 → 0.20.15

package/src/config/vector-cortex-early.ts

@@ -0,0 +1,99 @@
+/**
+ * config/vector-cortex-early.ts — VC0/VC1/VC2 phase sprint flags.
+ *
+ * Extracted from vector-cortex.ts to keep that file under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-breakers.ts was. These are
+ * the FOUNDATION-phase flags (observability, ledger, conformance, encoder); the
+ * VC3+ derived-state and prompt-path flags stay in vector-cortex.ts alongside
+ * the shared `sprintFlag` reader they are documented against.
+ *
+ * The split is purely mechanical: every flag below is byte-identical in name,
+ * semantics, and default to its previous definition, and vector-cortex.ts
+ * re-exports all of them so no consumer import path changes.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/** VC0A — baseline observability (MetricEventV1 / AnnotationV1). Default ON. */
+export const VC0A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0A");
+
+/**
+ * VC0B — replay correctness (ReplayCutV2 / ReplayReportV2, M3 effective-cut-v2).
+ * Default ON. `MEGACOMPACT_VC0B=0` disables and is byte-identical to the
+ * predecessor (legacy capped-replay behavior preserved; the v2 cut/replay is
+ * only consulted on the vector-cortex path).
+ */
+export const VC0B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0B");
+
+/**
+ * VC1A — canonical byte events (EventV2 / EventCodec).
+ * Default ON. `MEGACOMPACT_VC1A=0` disables and is byte-identical to the
+ * predecessor (mode C: ledger absent, current transcript codec unchanged).
+ * The single real consumer is the ledger emit seam (`ledger/emit.ts`): flag OFF
+ * gates zero observability writes.
+ */
+export const VC1A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1A");
+
+/**
+ * VC1B — occurrence ledger + tool identity + compat journal (LedgerReader/
+ * Writer/Admin, CompatJournalV1, M2 occurrence-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1B=0` disables and is byte-identical to the
+ * predecessor (mode C: the neutral occurrence ledger is not written, no
+ * journal rows, zero `vector_cortex_occurrence_appended` emissions). The real
+ * consumers are the ledger write integration seam and the compat-journal
+ * switch seam.
+ */
+export const VC1B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1B");
+
+/**
+ * VC0C — live safety envelope (TriadResult / Breaker / KillDecision + durable
+ * spool). Default ON. `MEGACOMPACT_VC0C=0` disables and is byte-identical to
+ * the predecessor (mode C: selected before provider invocation, unchanged host
+ * transcript, breaker/spool idle and emitting nothing). The single real
+ * consumer is the resilience emit seam + the safety adapter's triad selection.
+ */
+export const VC0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0C");
+
+/**
+ * VC1C — cross-language conformance v2 (FixtureManifestV2 / DowngradeReport /
+ * MinHashV2 + M4 minhash-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1C=0` disables and is byte-identical to the
+ * predecessor (mode C: a v2 conformance runner that accepts authority fixtures
+ * and the manifest validator idle; the sync dedup scan stays on the v1 path;
+ * zero `vector_cortex_*` VC1C emissions). The real consumers are the conformance
+ * emit seam, the minhash-v2 backfill seam and the downgrade-export seam.
+ */
+export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
+
+/**
+ * VC2A — offline model runtime and asset decision (ModelManifestV1 /
+ * EncoderRuntime).
+ * Default ON. `MEGACOMPACT_VC2A=0` disables and is byte-identical to the
+ * predecessor (mode C: no asset manifest is read/verified, the encoder runtime
+ * idles in mode C, zero `vector_cortex_encoder_*` emissions; the trigram/lexical
+ * paths are unchanged). The real consumers are the encoder emit seam and the
+ * encoder runtime's A/B/C selection.
+ */
+export const VC2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2A");
+
+/**
+ * VC2B — multi-head encoder (VectorSetV1 / HeadCalibrationDraft).
+ * Default ON. `MEGACOMPACT_VC2B=0` disables and is byte-identical to the
+ * predecessor (the encoder emits no per-head vectors and no fallback-selected
+ * event; the trigram/lexical paths themselves are unchanged and are the
+ * predecessor's mode-B/C producers). The real consumers are the encoder-heads
+ * emit seam and the multi-head encoder producers (heads/trigram/lexical).
+ */
+export const VC2B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2B");
+
+/**
+ * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
+ * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
+ * predecessor (mode C: no qualification manifest is read or selected, the
+ * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
+ * emissions; the trigram/lexical paths are unchanged). The real consumers are
+ * the encoder-qualification emit seam and the calibrate/select seams.
+ */
+export const VC2C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2C");

package/src/config/vector-cortex-flag.ts

@@ -0,0 +1,24 @@
+/**
+ * config/vector-cortex-flag.ts — the single positive sprint-flag reader.
+ *
+ * Extracted from vector-cortex.ts so the flag groups split across
+ * vector-cortex.ts and vector-cortex-early.ts share ONE definition of what
+ * "enabled" means. Duplicating this three-line function into each group would
+ * be the classic way a sprint flag silently acquires different off-semantics in
+ * different files; there is exactly one implementation and both groups import it.
+ *
+ * Semantics (unchanged, byte-identical to the original in-place definition):
+ * every sprint flag is POSITIVE and defaults ON. `MEGACOMPACT_<SPRINT>=0` or
+ * `=false` disables it, as does `MEGACOMPACT_<SPRINT>_DISABLED=true`/`=1`.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** Positive sprint flag: `=0` or `_DISABLED=true` disables (default ON). */
+export function sprintFlag(name: string): boolean {
+  const v = process.env[name];
+  if (v === "0" || v === "false") return false;
+  const disabled = process.env[name + "_DISABLED"];
+  if (disabled === "true" || disabled === "1") return false;
+  return true;
+}

package/src/config/vector-cortex.ts

@@ -9,96 +9,22 @@
  * them without re-declaring the ownership boundary. Pi-agnostic, dependency-free.
  */
 
-/** Positive sprint flag: `=0` or `_DISABLED=true` disables (default ON). */
-function sprintFlag(name: string): boolean {
-  const v = process.env[name];
-  if (v === "0" || v === "false") return false;
-  const disabled = process.env[name + "_DISABLED"];
-  if (disabled === "true" || disabled === "1") return false;
-  return true;
-}
+import { sprintFlag } from "./vector-cortex-flag.js";
 
-/** VC0A — baseline observability (MetricEventV1 / AnnotationV1). Default ON. */
-export const VC0A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0A");
-
-/**
- * VC0B — replay correctness (ReplayCutV2 / ReplayReportV2, M3 effective-cut-v2).
- * Default ON. `MEGACOMPACT_VC0B=0` disables and is byte-identical to the
- * predecessor (legacy capped-replay behavior preserved; the v2 cut/replay is
- * only consulted on the vector-cortex path).
- */
-export const VC0B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0B");
-
-/**
- * VC1A — canonical byte events (EventV2 / EventCodec).
- * Default ON. `MEGACOMPACT_VC1A=0` disables and is byte-identical to the
- * predecessor (mode C: ledger absent, current transcript codec unchanged).
- * The single real consumer is the ledger emit seam (`ledger/emit.ts`): flag OFF
- * gates zero observability writes.
- */
-export const VC1A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1A");
-
-/**
- * VC1B — occurrence ledger + tool identity + compat journal (LedgerReader/
- * Writer/Admin, CompatJournalV1, M2 occurrence-v2 migration).
- * Default ON. `MEGACOMPACT_VC1B=0` disables and is byte-identical to the
- * predecessor (mode C: the neutral occurrence ledger is not written, no
- * journal rows, zero `vector_cortex_occurrence_appended` emissions). The real
- * consumers are the ledger write integration seam and the compat-journal
- * switch seam.
- */
-export const VC1B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1B");
-
-/**
- * VC0C — live safety envelope (TriadResult / Breaker / KillDecision + durable
- * spool). Default ON. `MEGACOMPACT_VC0C=0` disables and is byte-identical to
- * the predecessor (mode C: selected before provider invocation, unchanged host
- * transcript, breaker/spool idle and emitting nothing). The single real
- * consumer is the resilience emit seam + the safety adapter's triad selection.
- */
-export const VC0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0C");
-
-/**
- * VC1C — cross-language conformance v2 (FixtureManifestV2 / DowngradeReport /
- * MinHashV2 + M4 minhash-v2 migration).
- * Default ON. `MEGACOMPACT_VC1C=0` disables and is byte-identical to the
- * predecessor (mode C: a v2 conformance runner that accepts authority fixtures
- * and the manifest validator idle; the sync dedup scan stays on the v1 path;
- * zero `vector_cortex_*` VC1C emissions). The real consumers are the conformance
- * emit seam, the minhash-v2 backfill seam and the downgrade-export seam.
- */
-export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
-
-/**
- * VC2A — offline model runtime and asset decision (ModelManifestV1 /
- * EncoderRuntime).
- * Default ON. `MEGACOMPACT_VC2A=0` disables and is byte-identical to the
- * predecessor (mode C: no asset manifest is read/verified, the encoder runtime
- * idles in mode C, zero `vector_cortex_encoder_*` emissions; the trigram/lexical
- * paths are unchanged). The real consumers are the encoder emit seam and the
- * encoder runtime's A/B/C selection.
- */
-export const VC2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2A");
-
-/**
- * VC2B — multi-head encoder (VectorSetV1 / HeadCalibrationDraft).
- * Default ON. `MEGACOMPACT_VC2B=0` disables and is byte-identical to the
- * predecessor (the encoder emits no per-head vectors and no fallback-selected
- * event; the trigram/lexical paths themselves are unchanged and are the
- * predecessor's mode-B/C producers). The real consumers are the encoder-heads
- * emit seam and the multi-head encoder producers (heads/trigram/lexical).
- */
-export const VC2B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2B");
-
-/**
- * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
- * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
- * predecessor (mode C: no qualification manifest is read or selected, the
- * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
- * emissions; the trigram/lexical paths are unchanged). The real consumers are
- * the encoder-qualification emit seam and the calibrate/select seams.
- */
-export const VC2C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2C");
+// VC0/VC1/VC2 foundation-phase flags extracted to vector-cortex-early.ts to keep
+// this file under the 300-line soft limit. Re-exported here so every existing
+// `from "./config/vector-cortex.js"` import keeps resolving unchanged.
+export {
+  VC0A_ENABLED,
+  VC0B_ENABLED,
+  VC0C_ENABLED,
+  VC1A_ENABLED,
+  VC1B_ENABLED,
+  VC1C_ENABLED,
+  VC2A_ENABLED,
+  VC2B_ENABLED,
+  VC2C_ENABLED,
+} from "./vector-cortex-early.js";
 
 /**
  * VC3A — capability-gated cortex store (CortexReader/Writer/Admin, CortexRecordV1).
@@ -273,6 +199,46 @@ export const VC6C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6C");
  */
 export const VC7A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7A");
 
+/**
+ * VC7B — provider cache economics + crystal compiler. Default ON.
+ * `MEGACOMPACT_VC7B=0` disables and is byte-identical to the predecessor
+ * (VC7A): `computeEconomics`, `compileCrystalBoundaries` and `assignExperiment`
+ * STILL RUN (they are PURE — exact integer/rational arithmetic and a SHA-256
+ * session bucket, with no clock, storage, or network), so a session keeps its
+ * SAME experiment arm and the compiler keeps producing the SAME boundaries with
+ * the flag off. Crucially the compiler never changes request identity in either
+ * state, so the outbound canonical request — and therefore the VC7A crystal key
+ * and the predecessor golden bytes — are unaffected by this flag.
+ *
+ * The flag gates ONLY the `vector_cortex_cache_experiment_assigned` /
+ * `vector_cortex_cache_economics_estimated` events and the cache-economics
+ * dashboard seam, which reports `enabled:false` + mode C when off. This flag
+ * MUST also be a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS), mirroring VC4A..VC7A.
+ */
+export const VC7B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7B");
+
+/**
+ * VC7C — cache miss diagnostics, cache-level breakers and the completed M5
+ * request-hash-v2 switch. Default ON. `MEGACOMPACT_VC7C=0` disables and is
+ * byte-identical to the predecessor (VC7B): the miss `classify`, the breaker
+ * demotion decision and the M5 request-hash-v2 ARITHMETIC STILL RUN (they are
+ * PURE — an exclusive ordered comparison over already-computed digests plus a
+ * canonical length-prefixed SHA-256, with no clock, storage, or network), so a
+ * miss is classified into the SAME single class, a collision / stale generation
+ * / digest failure / profile mismatch still demotes BEFORE any cache serve, and
+ * the v2 hash of a given request is unchanged with the flag off. A cache is
+ * never allowed to serve a stale or colliding entry merely because reporting is
+ * off — that would be a correctness change, not a reporting change.
+ *
+ * The flag gates ONLY the `vector_cortex_cache_miss_classified` /
+ * `vector_cortex_cache_serve_blocked` events and the cache-diagnostics dashboard
+ * seam, which reports `enabled:false` + mode C when off. This flag MUST also be
+ * a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS), mirroring VC4A..VC7B.
+ */
+export const VC7C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7C");
+
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker) extracted to
 // vector-cortex-breakers.ts to keep this file under the 300-line soft limit.
 export {

package/src/config.ts

@@ -173,6 +173,8 @@ export {
   VC6B_ENABLED,
   VC6C_ENABLED,
   VC7A_ENABLED,
+  VC7B_ENABLED,
+  VC7C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/cache/_economics-fixture.ts

@@ -0,0 +1,128 @@
+/**
+ * cache/_economics-fixture.ts — conformance fixture I/O for VC7B economics rows.
+ *
+ * Sibling of `./_crystal-fixture.ts`, same job for a different corpus: turn
+ * canonical JSON back into the REAL production types the economics / compiler /
+ * experiments modules consume. Fixtures cannot express bigints, so token counts
+ * stored as numbers are converted here — if that conversion were lossy the
+ * computed digests would diverge and the acceptance rows would fail loudly.
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `ProviderEconomicsV1` / `CacheUsageV1` / `CacheExperimentV1` and are fed
+ * verbatim into `validateProfileEconomics`, `computeEconomics`, `compileCrystalBoundaries`,
+ * and `assignExperiment`.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+
+import { V2, readManifest } from "../heal/_acceptance-fixture.js";
+
+/** A `ProviderProfileExclusion` as it appears in JSON. */
+export interface EconFxExclusion {
+  pointer: string;
+  fixtureId: string;
+  proofDigest: string;
+}
+
+/** A `ProviderProfileV1` as it appears in JSON (exclusions flattened). */
+export interface EconFxProfile {
+  profileId: string;
+  profileVersion: string;
+  exclusionFixtureId: string | null;
+  exclusions: readonly EconFxExclusion[];
+}
+
+/** A `CacheUsageV1` as it appears in JSON (matches `CacheUsageV1` exactly). */
+export interface EconFxUsage {
+  cachedTokens: number;
+  writeCount: number;
+  hitCount: number;
+}
+
+/** A compiler input range as it appears in JSON (matches `DagSpan` minus seq). */
+export interface EconFxCompilerRange {
+  sessionId: string;
+  startSeq: number;
+  endSeq: number;
+  startByte: number;
+  endByte: number;
+  digest: string;
+}
+
+export interface EconFxExperiment {
+  experimentId: string;
+  sessionId: string;
+  arm: "A" | "B" | "C";
+  source: "randomized" | "forced" | "shadow";
+}
+
+export interface EconFxInput {
+  scenario: "economics" | "exclusion" | "compile" | "experiment" | "eligibility";
+  mode: string;
+  economics?: ProviderEconomicsV1Lite;
+  profile?: EconFxProfile;
+  exclusion?: EconFxExclusion;
+  usage?: EconFxUsage;
+  prefixTokens?: number;
+  ageMs?: number;
+  ranges?: readonly EconFxCompilerRange[];
+  experiment?: EconFxExperiment;
+  repeatAssignments?: number;
+  loseJournalAfterFirst?: boolean;
+}
+
+export interface ProviderEconomicsV1Lite {
+  profileId: string;
+  profileVersion: string;
+  basePrice: number;
+  readPrice: number;
+  writePrice: number;
+  ttlMs: number;
+  minPrefix: number;
+  exclusionFixtureId: string | null;
+}
+
+export interface EconFxExpected {
+  ok: boolean;
+  code?: string;
+  netSavings?: number;
+  tokenSavings?: number;
+  breakEvenHits?: number | null;
+  eligible?: boolean;
+  identityPreserved?: boolean;
+  repeatArm?: "A" | "B" | "C";
+}
+
+export interface EconFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: EconFxInput;
+  expected: EconFxExpected;
+}
+
+/** Read one registered cache-economics fixture (asserting it IS registered). */
+export function economicsFixture(id: string): EconFx {
+  const m = readManifest();
+  const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("cache-economics/"));
+  assert.ok(row, `fixture ${id} registered under cache-economics/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row!.path), "utf8")) as EconFx;
+}
+
+/** Flag-pinned wrapper: VC7B gated by MEGACOMPACT_VC7B (defaults ON). */
+export function withVc7bFlag(value: string, fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC7B;
+    process.env.MEGACOMPACT_VC7B = value;
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC7B;
+      else process.env.MEGACOMPACT_VC7B = saved;
+    }
+  };
+}