pi-mega-compact 0.20.5 → 0.20.7

package/dist/src/vectorStore/class.js

@@ -1,34 +1,21 @@
-/**
- * class.ts — VectorStore implementation (extracted from vectorStore.ts).
- *
- * One store, three consumers (per PLAN.md): auto-inline on resume, on-demand
- * /recall-context, and the dedup sentinel. All share `add / search / dedupe`.
- *
- * Backed by the gzipped on-disk checkpoint files (store.ts). Similarity is a
- * linear cosine scan — checkpoint counts are small, so no ANN index is needed.
- */
-import { createHash } from "node:crypto";
-import { cosineSimilarity, defaultEmbedder } from "../embedder.js";
+import { defaultEmbedder } from "../embedder.js";
 import { loadDedupConfig, } from "../config/dedup.js";
 import { logDecision } from "../monitoring.js";
 import { repoKey } from "../store/repoKey.js";
-import { getStateDir, normalizeSessionId, compressSmart } from "../store.js";
-import { computeContentDigest } from "../dedup/digest.js";
-import { minhashSignature, SIGNATURE_VERSION, NUM_HASHES, } from "../dedup/l1-minhash.js";
-import { lshBands } from "../dedup/l1-lsh.js";
-import { isNearDuplicate } from "../dedup/l1-verify.js";
-import { openBloom, saveBloom } from "../store/bloom.js";
-import { listCheckpoints, nextCheckpointId, upsertCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, addTokensSaved, bumpDedupStats, } from "../store/sqlite.js";
+import { getStateDir } from "../store.js";
+import { openBloom } from "../store/bloom.js";
 import { migrateJsonToSqlite } from "../store/migrate.js";
-import { computeRegionHash } from "./hash.js";
+import { addCheckpoint } from "./add.js";
 export class VectorStore {
     // These fields are `readonly` (set once in the constructor) but NOT private:
-    // the read/search/dedup helpers split into vector-read.ts, vector-search.ts,
-    // and vector-dedup.ts access them directly. Marking them private would force
-    // ugly `as unknown as` casts in those modules; keeping them package-public
-    // makes VectorStore a thin barrel whose helpers live in sibling files.
+    // the add/read/search/dedup helpers split into add.ts, vector-read.ts,
+    // vector-search.ts, and vector-dedup.ts access them directly. Marking them
+    // private would force ugly `as unknown as` casts in those modules; keeping
+    // them package-public makes VectorStore a thin barrel whose helpers live in
+    // sibling files.
     embedder;
     stateDir;
+    /** L2 semantic firing point (cfg.L2_COSINE, or a direct test override). */
     l2Threshold;
     /** Single source of truth for tier flags + thresholds (Sprint 14). */
     cfg;
@@ -82,275 +69,12 @@ export class VectorStore {
         });
     }
     /**
-     * Add a checkpoint. Dedup cascade:
-     *   1. regionHash exact match (legacy, backward-compat)
-     *   2. summaryHash exact match (new: catches same-topic incremental compactions)
-     *   3. content similarity ≥ dedupSim (catches near-identical summaries)
-     *   4. If none match → create new checkpoint
+     * Add a checkpoint, deduping it against the session's existing checkpoints.
+     *
+     * The cascade itself lives in ./add.ts (sibling-helper pattern) so this class
+     * stays a thin shell over the fields its helpers read.
      */
     add(input) {
-        const t0 = Date.now();
-        const sessionId = normalizeSessionId(input.sessionId);
-        const regionHash = computeRegionHash(input.regionText);
-        const all = listCheckpoints(sessionId, this.stateDir);
-        // Honest "tokens saved" base for this region. For a deduped add the whole
-        // original region is discarded (nothing new stored); for a new checkpoint
-        // we persist (orig − stored). Falls back to stored when orig is unknown.
-        const origTokens = input.originalTokenEstimate ?? input.tokenEstimate ?? 0;
-        const cfg = this.cfg;
-        // Live per-tier progress hook (Phase 1). Sync + optional; fired at each tier
-        // so the UI can paint "L0 ✓ → L1 ✓ → L2 0.91 → stored" during a compaction.
-        const onTier = input.onTier;
-        // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
-        // and which tier.
-        let markOnly = null;
-        // 0. L0 content-hash dedup (Sprint 9) — catches identical content arriving
-        //    under different regionText. Normalization handles case/whitespace/ANSI so
-        //    variants collapse to one row. Dual-hash guards a single-hash collision.
-        //    Sprint 10: bloom is the accelerator — a miss means "definitely new" and
-        //    skips the scan; a hit is only a candidate, confirmed against `all` below.
-        //    Gated by L0_ENABLED (Sprint 14). MARK_ONLY_L0 records the decision but
-        //    does not collapse — the new region is still stored.
-        onTier?.({ tier: "L0", status: "scanning" });
-        const digest = computeContentDigest(input.regionText);
-        const bloom = openBloom(this.stateDir);
-        if (cfg.L0_ENABLED && bloom.maybeHas(digest.contentHash)) {
-            const contentMatch = all.find((cp) => cp.contentHash === digest.contentHash &&
-                cp.contentHash2 === digest.contentHash2);
-            if (contentMatch) {
-                if (cfg.MARK_ONLY_L0) {
-                    markOnly = "L0"; // Record-but-don't-collapse: fall through.
-                }
-                else {
-                    contentMatch.timestamp = input.timestamp;
-                    upsertCheckpoint(contentMatch, this.stateDir);
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: contentMatch,
-                        deduped: true,
-                        reason: "contentHash",
-                    };
-                    this.record("L0", "deduped", "contentHash", Date.now() - t0, 1, contentMatch.checkpointId);
-                    onTier?.({ tier: "L0", status: "deduped", detail: "contentHash" });
-                    return r;
-                }
-            }
-        }
-        // 1. Legacy regionHash dedup (backward-compat) — part of L0 tier gating.
-        if (cfg.L0_ENABLED) {
-            const regionMatch = all.find((cp) => cp.regionHash === regionHash);
-            if (regionMatch) {
-                if (cfg.MARK_ONLY_L0) {
-                    markOnly = "L0"; // fall through
-                }
-                else {
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: regionMatch,
-                        deduped: true,
-                        reason: "regionHash",
-                    };
-                    this.record("L0", "deduped", "regionHash", Date.now() - t0, 1, regionMatch.checkpointId);
-                    onTier?.({ tier: "L0", status: "deduped", detail: "regionHash" });
-                    return r;
-                }
-            }
-        }
-        // 2. SummaryHash dedup — catches same-topic incremental compactions.
-        //    Full 64-hex SHA-256 (was 16-hex in Sprint 8 — collision-prone).
-        const summaryHash = input.topicSummary
-            ? createHash("sha256").update(input.topicSummary).digest("hex")
-            : undefined;
-        if (summaryHash && cfg.L0_ENABLED) {
-            const summaryMatch = all.find((cp) => cp.summaryHash === summaryHash);
-            if (summaryMatch) {
-                if (cfg.MARK_ONLY_L0) {
-                    markOnly = "L0"; // fall through
-                }
-                else {
-                    summaryMatch.timestamp = input.timestamp;
-                    upsertCheckpoint(summaryMatch, this.stateDir);
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: summaryMatch,
-                        deduped: true,
-                        reason: "summaryHash",
-                    };
-                    this.record("L0", "deduped", "summaryHash", Date.now() - t0, 1, summaryMatch.checkpointId);
-                    onTier?.({ tier: "L0", status: "deduped", detail: "summaryHash" });
-                    return r;
-                }
-            }
-        }
-        // L0 did not collapse this region.
-        onTier?.({ tier: "L0", status: "passed" });
-        // 2b. L1 MinHash/LSH near-duplicate dedup (Sprint 11) — catches one-word
-        //     edits / rewordings that L0's exact hash misses. Cheap LSH bucket
-        //     retrieval → trigram verification (pg_trgm-equivalent) as the final gate.
-        //     Gated by L1_ENABLED (Sprint 14); MARK_ONLY_L1 records but doesn't collapse.
-        onTier?.({ tier: "L1", status: "scanning" });
-        if (cfg.L1_ENABLED) {
-            const l1 = this.findL1Duplicate(sessionId, input.regionText, all);
-            if (l1 && !cfg.MARK_ONLY_L1) {
-                l1.timestamp = input.timestamp;
-                upsertCheckpoint(l1, this.stateDir);
-                bumpDedupStats(true, this.stateDir);
-                const r = { checkpoint: l1, deduped: true, reason: "l1MinHash" };
-                this.record("L1", "deduped", "l1MinHash", Date.now() - t0, 1, l1.checkpointId);
-                onTier?.({ tier: "L1", status: "deduped", detail: "l1MinHash" });
-                return r;
-            }
-            if (l1 && cfg.MARK_ONLY_L1)
-                markOnly = "L1";
-        }
-        onTier?.({ tier: "L1", status: "passed" });
-        // 3. L2 semantic dedup — catches near-identical / semantically-similar regions
-        //    via cosine over the embedding. topicSummary is used for summaryHash dedup
-        //    (tier 2); the vector index is keyed on the original region for backward-
-        //    compat search semantics. Threshold from cfg (L2_COSINE trigram honest
-        //    firing point). QA #13 timeout guard: if the O(n) scan exceeds the budget,
-        //    degrade to "store without dedup this pass" so we never lose a checkpoint.
-        //    Gated by L2_ENABLED (Sprint 14); MARK_ONLY_L2 records but doesn't collapse.
-        const SIMILARITY_BUDGET_MS = cfg.SIMILARITY_BUDGET_MS;
-        const simThreshold = this.l2Threshold; // from cfg.L2_COSINE (default 0.85 trigram)
-        const embedding = this.embedder.embed(input.regionText);
-        onTier?.({ tier: "L2", status: "scanning" });
-        if (cfg.L2_ENABLED && all.length > 0) {
-            const start = Date.now();
-            let timedOut = false;
-            const nearest = all.reduce((best, cp) => {
-                if (!timedOut && Date.now() - start > SIMILARITY_BUDGET_MS)
-                    timedOut = true;
-                if (timedOut)
-                    return best;
-                const sim = cosineSimilarity(embedding, cp.embedding);
-                return sim > best.sim ? { checkpoint: cp, sim } : best;
-            }, { checkpoint: all[0], sim: -1 });
-            if (!timedOut && nearest.sim >= simThreshold) {
-                if (!cfg.MARK_ONLY_L2) {
-                    // Near-identical — update timestamp on existing checkpoint
-                    nearest.checkpoint.timestamp = input.timestamp;
-                    upsertCheckpoint(nearest.checkpoint, this.stateDir);
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: nearest.checkpoint,
-                        deduped: true,
-                        reason: "contentSimilarity",
-                    };
-                    this.record("L2", "deduped", "contentSimilarity", Date.now() - t0, nearest.sim, nearest.checkpoint.checkpointId);
-                    onTier?.({
-                        tier: "L2",
-                        status: "deduped",
-                        detail: nearest.sim.toFixed(2),
-                    });
-                    return r;
-                }
-                markOnly = "L2";
-            }
-            onTier?.({
-                tier: "L2",
-                status: "passed",
-                detail: `best ${nearest.sim.toFixed(2)}`,
-            });
-        }
-        // 4. Genuinely new — create checkpoint
-        const checkpointId = nextCheckpointId(sessionId, this.stateDir);
-        const checkpoint = {
-            checkpointId,
-            sessionId,
-            repoId: this.repoId,
-            summary: input.summary,
-            topicSummary: input.topicSummary,
-            summaryHash,
-            keyDecisions: input.keyDecisions ?? [],
-            nextSteps: input.nextSteps ?? [],
-            filesModified: input.filesModified ?? [],
-            tokenEstimate: input.tokenEstimate ?? 0,
-            originalTokenEstimate: input.originalTokenEstimate,
-            regionHash,
-            contentHash: digest.contentHash,
-            contentHash2: digest.contentHash2,
-            contentHashVersion: digest.contentHashVersion,
-            normalizedText: digest.normalizedText,
-            compressedOriginal: compressSmart(Buffer.from(input.regionText, "utf-8"), input.compressionPressure),
-            embedding,
-            timestamp: input.timestamp,
-        };
-        // Persistence is SQLite (store/sqlite.ts). upsertCheckpoint keeps the
-        // idempotent-by-id semantics the old JSON append implied.
-        upsertCheckpoint(checkpoint, this.stateDir);
-        // Cumulative "tokens saved" counter (per-repo SQLite meta). For a NEW
-        // checkpoint the saved amount is (original − stored); for a deduped add the
-        // whole original region is discarded (handled in the deduped return paths
-        // below). Survives sessions and travels with the repo.
-        const stored = input.tokenEstimate ?? 0;
-        addTokensSaved(Math.max(0, origTokens - stored), this.stateDir);
-        // L1: persist this checkpoint's MinHash signature + LSH buckets so future
-        // near-duplicate inserts can find it. Deterministic given the seed.
-        const sig = minhashSignature(input.regionText);
-        upsertMinhashSignature(checkpointId, sessionId, SIGNATURE_VERSION, sig, this.stateDir);
-        insertLshBuckets(checkpointId, sessionId, SIGNATURE_VERSION, lshBands(sig, sessionId, SIGNATURE_VERSION), this.stateDir);
-        // Bloom accelerator: record the new content_hash so a future add() can short-
-        // circuit the scan on a hit (still confirmed by the SELECT-based `all` above).
-        bloom.add(digest.contentHash);
-        saveBloom(this.stateDir);
-        // Track the region hash in session state for fast sentinel checks.
-        const state = loadSessionState(sessionId, this.stateDir);
-        if (!state.storedRegionHashes.includes(regionHash)) {
-            state.storedRegionHashes.push(regionHash);
-            saveSessionState(sessionId, state, this.stateDir);
-        }
-        // A new checkpoint. If a tier matched while MARK_ONLY, record that (the
-        // decision fired but we intentionally did not collapse).
-        if (markOnly) {
-            this.record(markOnly, "mark_only", "mark_only", Date.now() - t0);
-        }
-        else {
-            this.record("L0", "new", undefined, Date.now() - t0);
-        }
-        // Cumulative store-wide dedup accounting (attempt, not collapsed).
-        bumpDedupStats(false, this.stateDir);
-        onTier?.({ tier: "new", status: "stored" });
-        return { checkpoint, deduped: false };
-    }
-    /**
-     * L1 near-duplicate lookup: MinHash → LSH candidate retrieval → trigram verify.
-     * Returns the matching checkpoint or undefined. Bounded by a 100-candidate cap
-     * and a 20ms verify budget (QA #7/#15) so it never hangs a large session.
-     */
-    findL1Duplicate(sessionId, regionText, all) {
-        if (all.length === 0)
-            return undefined;
-        const sig = minhashSignature(regionText);
-        if (sig.length !== NUM_HASHES)
-            return undefined;
-        const bands = lshBands(sig, sessionId, SIGNATURE_VERSION);
-        // Cheap candidate retrieval (single query, capped). Exclude nothing yet —
-        // the new checkpoint has no id, so pass a sentinel that never matches.
-        const candidateIds = lshCandidateChunks(bands, sessionId, "__new__", this.stateDir, 100);
-        if (candidateIds.length === 0)
-            return undefined;
-        const byId = new Map(all.map((cp) => [cp.checkpointId, cp]));
-        const VERIFY_BUDGET_MS = 20;
-        const start = Date.now();
-        for (const id of candidateIds) {
-            if (Date.now() - start > VERIFY_BUDGET_MS)
-                break; // QA #15: abort → "not dup"
-            const cand = byId.get(id);
-            if (!cand)
-                continue;
-            const candText = cand.normalizedText ?? cand.summary ?? "";
-            if (isNearDuplicate(regionText, candText))
-                return cand;
-        }
-        return undefined;
+        return addCheckpoint(this, input);
     }
 }

package/dist/src/vectorStore/dedup-audit.js

@@ -0,0 +1,104 @@
+/**
+ * dedup-audit.ts — durable audit trail for dedup tier decisions
+ * (external-audit item #2).
+ *
+ * Before this module a tier decision existed only as the in-process `onTier`
+ * callback that paints the live UI; nothing survived the process, so an
+ * operator could not answer "which layer collapsed this region, onto what, at
+ * what similarity?" — the inputs needed to tune the thresholds in
+ * config/dedup.ts. Here each decision is appended to the repo's events.log as
+ * one structured JSON line (see `DedupAuditEvent` below).
+ *
+ * The event type and its append helper live HERE rather than in monitoring.ts:
+ * monitoring.ts already owns three concerns (decision events, the dashboard.json
+ * metrics snapshot, FP alerting) and sits close to its 300-line soft limit, so
+ * co-locating the shape with the only recorder that produces it keeps both files
+ * under the headroom gate. monitoring.ts re-exports both for callers (and the
+ * dashboard SSE tail) that treat it as the events.log barrel.
+ *
+ * Design constraints:
+ *  - PURE INSTRUMENTATION. Nothing in this file may influence a dedup outcome.
+ *  - Best-effort/non-fatal: `logDedupAudit` swallows IO errors, and the emitter
+ *    itself is wrapped so a malformed field can never break add().
+ *  - Honest fields only: a value is emitted only where the caller actually
+ *    computed it. L0/L1 are hash/verify tiers and pass no `similarity`.
+ *  - Signal, not chatter: callers emit on DECISIONS (a match, a scored
+ *    candidate, the final outcome), never on every "scanning" transition.
+ *  - Flag-gated by cfg.DEDUP_AUDIT (default ON; OFF writes nothing at all).
+ *
+ * PREVENT-PI-004: local filesystem append only, no network.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { defaultEventsPath } from "../monitoring.js";
+/**
+ * Append one audit event to events.log (best-effort, never throws).
+ *
+ * Same append-one-JSON-line contract as monitoring.ts's logDecision — an
+ * unwritable path is swallowed so instrumentation can never break add().
+ */
+export function logDedupAudit(path, ev) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify(ev)}\n`, "utf-8");
+    }
+    catch {
+        /* best-effort — never break the extension on a log failure */
+    }
+}
+/** Build a recorder bound to one add() cascade. */
+export function dedupAuditRecorder(ctx, scope) {
+    const base = {
+        sessionId: scope.sessionId,
+        originalTokenEstimate: scope.originalTokenEstimate,
+        tokenEstimate: scope.tokenEstimate,
+    };
+    return {
+        deduped: (tier, matchedEntry, dedupReason, similarity) => emitDedupAudit(ctx, {
+            ...base,
+            tier,
+            status: "deduped",
+            matchedEntry,
+            dedupReason,
+            ...(similarity === undefined ? {} : { similarity }),
+        }),
+        passed: (tier, matchedEntry, similarity) => emitDedupAudit(ctx, {
+            ...base,
+            tier,
+            status: "passed",
+            matchedEntry,
+            similarity,
+        }),
+        stored: (storedEntry, dedupReason, tokenEstimate) => emitDedupAudit(ctx, {
+            ...base,
+            tier: "new",
+            status: "stored",
+            storedEntry,
+            dedupReason,
+            tokenEstimate,
+        }),
+    };
+}
+/**
+ * Append one dedup decision to events.log.
+ *
+ * Resolves the target path from the explicit `eventsPath` when a caller opted
+ * in (Sprint 14 monitoring / tests), otherwise from the store's own per-repo
+ * state dir — production never passes `eventsPath`, so defaulting is what makes
+ * the audit trail actually exist on a real device.
+ */
+export function emitDedupAudit(ctx, input) {
+    if (!ctx.auditEnabled)
+        return;
+    try {
+        const path = ctx.eventsPath ?? defaultEventsPath(ctx.stateDir);
+        logDedupAudit(path, {
+            type: "dedup_audit",
+            ts: new Date().toISOString(),
+            ...input,
+        });
+    }
+    catch {
+        /* instrumentation must never break the add() path */
+    }
+}

package/dist/src/vectorStore.js

@@ -8,6 +8,7 @@
  * "./vectorStore.js" are unchanged.
  */
 export { VectorStore } from "./vectorStore/class.js";
+export { addCheckpoint } from "./vectorStore/add.js";
 export { computeRegionHash } from "./vectorStore/hash.js";
 export { L2_ENABLED, } from "./vectorStore/types.js";
 // Re-exports (back-compat): existing call sites keep importing from "./vectorStore.js"

package/dist/vector-cortex/rollout/_acceptance-fixture.js

@@ -0,0 +1,55 @@
+/**
+ * rollout/_acceptance-fixture.ts — conformance fixture I/O for VC5C rollout
+ * acceptance rows.
+ *
+ * Reads the v2 conformance manifest + the per-sprint rollout fixture files, and
+ * exposes the `RolloutFx` shape the acceptance aggregator drives. No
+ * mocks/stubs: the fixtures are the committed canonical corpus.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+const HERE = dirname(fileURLToPath(import.meta.url));
+function repoRoot(from) {
+    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);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+export function readManifest() {
+    return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8"));
+}
+function readFixture(id, prefix) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith(`${prefix}/`));
+    assert.ok(row, `fixture ${id} registered under ${prefix}/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+export function rolloutFixture(id) {
+    return readFixture(id, "rollout");
+}
+/** Flag-pinned wrapper: VC5C gated by MEGACOMPACT_VC5C (defaults ON). */
+export function withFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC5C;
+        process.env.MEGACOMPACT_VC5C = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC5C;
+            else
+                process.env.MEGACOMPACT_VC5C = saved;
+        }
+    };
+}

package/dist/vector-cortex/rollout/_acceptance-helpers.js

@@ -0,0 +1,8 @@
+/**
+ * rollout/_acceptance-helpers.ts — pure barrel re-export of the VC5C rollout
+ * acceptance helpers (fixture I/O + REAL runner). Mirrors the render family's
+ * delegate-shell split so the aggregator stays under the 600-line test hard
+ * limit.
+ */
+export { REPO_ROOT, V2, readManifest, rolloutFixture, withFlagsOn, } from "./_acceptance-fixture.js";
+export { runRolloutScenario } from "./_acceptance-scenario.js";

package/dist/vector-cortex/rollout/_acceptance-scenario.js

@@ -0,0 +1,70 @@
+/**
+ * rollout/_acceptance-scenario.ts — the REAL rollout runner for VC5C acceptance
+ * rows. Drives `assignSession` + `decideGate` (no mocks) against the fixture
+ * `input` and returns the result fields the fixture's `expected` block pins.
+ *
+ * Fake clocks: the gate scenario accepts an injected monotonic clock so the
+ * spec's unique failure injection (restart at 71h59m with a wall-clock jump +1d
+ * but monotonic unchanged) is reproducible. The wall-clock jump is irrelevant to
+ * the safety decision because eligibility uses the MONOTONIC delta only.
+ */
+import { assignSession } from "./assign.js";
+import { decideGate, } from "./gate.js";
+const GATE_MIN_ELAPSED_MS = 72 * 60 * 60 * 1000;
+/** Fixed monotonic clock: elapsed = now - windowStart (the only driver). */
+function clockAt(elapsedMs, windowStartMs) {
+    return {
+        now: () => windowStartMs + elapsedMs, // monotonic delta is the truth
+        wallNow: () => new Date(1_700_000_000_000 + elapsedMs).toISOString(),
+    };
+}
+/** Run a rollout fixture through the REAL assign + gate pipeline. */
+export function runRolloutScenario(fx) {
+    const scenario = fx.input.scenario;
+    if (scenario === "assign-stable") {
+        const a = assignSession(fx.input.sessionId ?? "");
+        const b = assignSession(fx.input.sessionId ?? "");
+        // Determinism: recomputing yields the identical bucket.
+        if (a.bucket !== b.bucket) {
+            return { ok: false };
+        }
+        return { ok: true, bucket: a.bucket };
+    }
+    if (scenario === "gate-power" || scenario === "gate-safety") {
+        const ev = fx.input.evidence ?? {};
+        const windowStartMs = ev.windowStartMs ?? 0;
+        const hardFaults = (ev.hardFaults ?? []).map((f) => ({ kind: f.kind, detail: f.detail }));
+        const evidence = {
+            windowStartMs,
+            powered: ev.powered ?? false,
+            events: ev.events ?? 0,
+            sessions: ev.sessions ?? 0,
+            hardFaults,
+        };
+        // The spec's unique failure injection: wall-clock jump is irrelevant; only the
+        // monotonic elapsed drives eligibility. For the 71h59m row we pass 71h59m; for
+        // the wall-jump row we pass the SAME monotonic elapsed (so it must stay blocked);
+        // for the >=72h row we pass a full 72h+ monotonic delta (so it advances).
+        const start = fx._monotonicElapsedMs;
+        const elapsedMs = start ?? GATE_MIN_ELAPSED_MS; // default: a full 72h window
+        const clock = clockAt(elapsedMs, windowStartMs);
+        // gate-safety with a hard fault forces pre-VC + freezes promotion regardless of
+        // the monotonic window; the gate index stays at the input's prior gate (0 here).
+        if (scenario === "gate-safety") {
+            const outcome = decideGate(0, evidence, clock);
+            return {
+                ok: true,
+                gateIndex: outcome.gateIndex,
+                promotionBlocked: outcome.promotionBlocked,
+                selectsPreVc: outcome.promotionBlocked,
+            };
+        }
+        const outcome = decideGate(0, evidence, clock);
+        return {
+            ok: true,
+            gateIndex: outcome.gateIndex,
+            promotionBlocked: outcome.promotionBlocked,
+        };
+    }
+    throw new Error(`unknown rollout scenario: ${scenario}`);
+}

package/dist/vector-cortex/rollout/assign.js

@@ -0,0 +1,56 @@
+/**
+ * vector-cortex/rollout/assign.ts — deterministic stable-bucket assignment.
+ *
+ * `assignSession(sessionId)` hashes a session id into one of 10,000 stable
+ * buckets (0..9999). The assignment is a PURE function of the session id and
+ * NEVER changes across process restart: it uses a fixed-seed FNV-1a over the
+ * session id bytes, never Date.now / Math.random (PREVENT-PI-004-adjacent
+ * determinism contract; the spec's restart-invariance requirement).
+ *
+ * A bucket `b` is "in" gate `g` (one of [1,5,25,50,100]) iff
+ * `b < g * 100`. So gate 1% covers buckets 0..99, gate 100% covers 0..9999.
+ *
+ * Pure: no I/O, no clock, no network. PREVENT-011: no `any`.
+ */
+import { ROLLOUT_BUCKETS, ROLLOUT_GATES, } from "./types.js";
+/**
+ * Deterministic 32-bit FNV-1a over the session id (UTF-8 bytes). Fixed seed
+ * (2166136261) — restart-invariant by construction. Returns a bucket in
+ * 0..(ROLLOUT_BUCKETS-1).
+ */
+export function assignSession(sessionId) {
+    const enc = new TextEncoder();
+    const bytes = enc.encode(sessionId);
+    let hash = 0x811c9dc5; // FNV offset basis (32-bit)
+    for (let i = 0; i < bytes.length; i++) {
+        hash ^= bytes[i];
+        // hash *= 16777619 (FNV prime) with 32-bit overflow wrap.
+        hash = Math.imul(hash, 0x01000193);
+    }
+    const bucket = (hash >>> 0) % ROLLOUT_BUCKETS;
+    // The bucket's qualifying gate is the HIGHEST gate whose bound it falls under.
+    let gateIndex = 0;
+    for (let i = 0; i < ROLLOUT_GATES.length; i++) {
+        if (bucket < ROLLOUT_GATES[i] * 100) {
+            gateIndex = i;
+            break;
+        }
+    }
+    return {
+        schema: "rollout-assignment-v1",
+        sessionId,
+        bucket,
+        gateIndex,
+    };
+}
+/**
+ * Whether a bucket qualifies for a given gate percentage. Used by the live seam
+ * to decide whether a session's bucket is currently exposed to the VC path.
+ */
+export function bucketInGate(bucket, gatePct) {
+    return bucket < gatePct * 100;
+}
+/** Current gate percentage for a gate index. */
+export function gatePctForIndex(gateIndex) {
+    return ROLLOUT_GATES[gateIndex];
+}