pi-mega-compact 0.20.11 → 0.20.13

package/dist/src/vector-cortex/cache/store.js

@@ -0,0 +1,196 @@
+/**
+ * vector-cortex/cache/store.ts — content-addressed, write-once crystal store
+ * (VC7A).
+ *
+ * WRITE ONCE, NEVER OVERWRITE. A key that already holds bytes is final. Writing
+ * the SAME bytes again is accepted and idempotent (two concurrent renders raced;
+ * both are right). Writing DIFFERENT bytes under the same key returns
+ * `CRY_KEY_COLLISION` and the stored crystal is left exactly as it was.
+ *
+ * Why refuse rather than take the newer bytes? Because the key already names
+ * everything the render depended on — covered ranges, their digest, the validated
+ * dependency high-water, the renderer, the profile. If two renders of that same
+ * identity disagree, the renderer is NOT deterministic, and that is a bug to
+ * surface loudly, not to paper over by picking a winner. Last-write-wins would
+ * make the failure invisible and let a corrupted render silently displace a good
+ * one. So the store is a one-way ratchet per key.
+ *
+ * CONTENT ADDRESSED. Every crystal carries the SHA-256 of exactly its own bytes
+ * (bare lowercase hex, matching `ExactShardV1.digest`), recomputed HERE from the
+ * bytes rather than trusted from the caller — a caller-supplied digest would let
+ * a mismatched pair be stored and later "verify" against itself.
+ *
+ * ATOMIC COMMIT (the crash invariant). Writes go through a staging slot and are
+ * only published by `commit`. A write interrupted before commit leaves the
+ * staging entry orphaned and the visible map untouched, so `read` can never
+ * observe a partial crystal. On restart, `recover()` DISCARDS staged entries —
+ * it never promotes them — and a fresh write then produces exactly one valid
+ * crystal. This models the real filesystem shape (write temp file → fsync →
+ * rename) without doing any I/O here: persistence is the runtime's job, and
+ * `src/` stays storage-free and pure (PREVENT-PI-004).
+ *
+ * MODE C. `setAvailable(false)` marks the store unavailable: reads serve nothing
+ * and writes refuse with `CRY_STORE_UNAVAILABLE`. Mode C is a real triad state,
+ * not an error path — the caller must fall back to a fresh render and disclose
+ * that nothing came from cache.
+ *
+ * No console, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+/** SHA-256 over bytes, BARE lowercase hex (the content address). */
+export function contentAddress(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Byte equality without allocating — a length check first, then a scan. */
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * An in-memory, content-addressed, write-once crystal store.
+ *
+ * Deliberately holds no filesystem handle: the process-local map IS the store as
+ * far as `src/` is concerned, and durability is layered on by the runtime. That
+ * keeps the write-once/collision arithmetic testable end-to-end with real
+ * modules and no I/O mocking.
+ */
+export class CrystalStore {
+    /** Published crystals, keyed by canonical key digest. */
+    committed = new Map();
+    /** Staged-but-uncommitted writes — invisible to `read` until committed. */
+    staged = new Map();
+    available = true;
+    hits = 0;
+    misses = 0;
+    hitBytes = 0;
+    writes = 0;
+    duplicateWrites = 0;
+    collisions = 0;
+    /** Freeze a crystal object for a key/bytes pair (digest computed here). */
+    static freeze(keyDigest, bytes, key) {
+        const copy = new Uint8Array(bytes);
+        return {
+            schema: "crystal-v1",
+            keyDigest,
+            bytes: copy,
+            contentDigest: contentAddress(copy),
+            byteCount: copy.length,
+            key,
+        };
+    }
+    /** Toggle store availability (mode C when false). */
+    setAvailable(value) {
+        this.available = value;
+    }
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Stage a write without publishing it. Returns the staging handle (the key
+     * digest) so a test — or a crash — can leave it uncommitted.
+     */
+    stage(crystal) {
+        if (!this.available) {
+            return { ok: false, code: "CRY_STORE_UNAVAILABLE", contentDigest: crystal.contentDigest };
+        }
+        this.staged.set(crystal.keyDigest, crystal);
+        return { ok: true, written: false, contentDigest: crystal.contentDigest };
+    }
+    /**
+     * Publish a staged write. Enforces write-once at the commit point: an existing
+     * key with identical bytes is idempotent, with different bytes is a collision
+     * and is NEVER overwritten.
+     */
+    commit(keyDigest) {
+        const pending = this.staged.get(keyDigest);
+        if (pending === undefined) {
+            return { ok: false, code: "CRY_STORE_UNAVAILABLE", contentDigest: "" };
+        }
+        this.staged.delete(keyDigest);
+        if (!this.available) {
+            return { ok: false, code: "CRY_STORE_UNAVAILABLE", contentDigest: pending.contentDigest };
+        }
+        const existing = this.committed.get(keyDigest);
+        if (existing !== undefined) {
+            if (bytesEqual(existing.bytes, pending.bytes)) {
+                this.duplicateWrites += 1;
+                return { ok: true, written: false, contentDigest: existing.contentDigest };
+            }
+            this.collisions += 1;
+            return { ok: false, code: "CRY_KEY_COLLISION", contentDigest: existing.contentDigest };
+        }
+        this.committed.set(keyDigest, pending);
+        this.writes += 1;
+        return { ok: true, written: true, contentDigest: pending.contentDigest };
+    }
+    /** Stage + commit in one step (the normal path). */
+    write(crystal) {
+        const staged = this.stage(crystal);
+        if (!staged.ok)
+            return staged;
+        return this.commit(crystal.keyDigest);
+    }
+    /**
+     * Restart recovery: DISCARD every staged entry. A write interrupted before
+     * commit is never promoted — a fresh write afterwards produces exactly one
+     * valid crystal. Returns how many partial writes were dropped.
+     */
+    recover() {
+        const dropped = this.staged.size;
+        this.staged.clear();
+        return dropped;
+    }
+    /** Read a committed crystal. Mode C (unavailable) serves nothing. */
+    read(keyDigest) {
+        if (!this.available) {
+            this.misses += 1;
+            return undefined;
+        }
+        const found = this.committed.get(keyDigest);
+        if (found === undefined) {
+            this.misses += 1;
+            return undefined;
+        }
+        this.hits += 1;
+        this.hitBytes += found.byteCount;
+        return found;
+    }
+    /** Whether a key holds a committed crystal (does not count as a read). */
+    has(keyDigest) {
+        return this.available && this.committed.has(keyDigest);
+    }
+    /** Number of writes staged but not yet committed (0 after `recover`). */
+    pendingCount() {
+        return this.staged.size;
+    }
+    /**
+     * The triad mode the store is currently in: C when unavailable, A once a read
+     * has been served from the store, B while every read has forced a fresh render.
+     */
+    mode() {
+        if (!this.available)
+            return "C";
+        return this.hits > 0 ? "A" : "B";
+    }
+    /** Reader-only aggregate for the dashboard seam — counts and bytes only. */
+    stats() {
+        let totalBytes = 0;
+        for (const c of this.committed.values())
+            totalBytes += c.byteCount;
+        return {
+            mode: this.mode(),
+            crystalCount: this.committed.size,
+            totalBytes,
+            hits: this.hits,
+            misses: this.misses,
+            hitBytes: this.hitBytes,
+            writes: this.writes,
+            duplicateWrites: this.duplicateWrites,
+            collisions: this.collisions,
+        };
+    }
+}

package/dist/vector-cortex/cache/_crystal-fixture.js

@@ -0,0 +1,71 @@
+/**
+ * cache/_crystal-fixture.ts — conformance fixture I/O for VC7A crystal rows.
+ *
+ * Sibling of `../heal/_restore-fixture.ts`, same job for a different corpus:
+ * turn canonical JSON back into the REAL production types the cache modules
+ * consume. Fixtures cannot express bigints, so `dependencyHighWater` and the
+ * span seq bounds are stored as numbers and converted here — if that conversion
+ * were lossy the encoded keys would diverge and the acceptance rows would fail
+ * loudly, which is exactly the guarantee an identity sprint needs.
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `CrystalKeyV1` / `DagSpan` and are fed verbatim into `encodeCrystalKey` and
+ * `CrystalStore`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { computeCoveredDigest } from "./crystal.js";
+import { V2, readManifest } from "../heal/_acceptance-fixture.js";
+/** Read one registered cache-crystal fixture (asserting it IS registered). */
+export function crystalFixture(id) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("cache-crystals/"));
+    assert.ok(row, `fixture ${id} registered under cache-crystals/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+/** JSON number seq bounds -> the bigint bounds `DagSpan` declares. */
+export function decodeSpan(s) {
+    return {
+        sessionId: s.sessionId,
+        startSeq: BigInt(s.startSeq),
+        endSeq: BigInt(s.endSeq),
+        startByte: s.startByte,
+        endByte: s.endByte,
+        digest: s.digest,
+    };
+}
+/**
+ * Reconstitute a real `CrystalKeyV1`. `coveredDigest` is DERIVED from the ranges
+ * rather than carried in the corpus: the covered digest is a function of the
+ * ranges, so storing it would let a fixture assert a self-inconsistent identity
+ * that the encoder would silently re-derive anyway.
+ */
+export function decodeKey(k) {
+    const sourceRanges = k.sourceRanges.map(decodeSpan);
+    return {
+        profileId: k.profileId,
+        profileVersion: k.profileVersion,
+        requestDigest: k.requestDigest,
+        rendererVersion: k.rendererVersion,
+        dependencyHighWater: BigInt(k.dependencyHighWater),
+        sourceRanges,
+        coveredDigest: computeCoveredDigest(sourceRanges),
+    };
+}
+/** Flag-pinned wrapper: VC7A gated by MEGACOMPACT_VC7A (defaults ON). */
+export function withVc7aFlag(value, fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC7A;
+        process.env.MEGACOMPACT_VC7A = value;
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC7A;
+            else
+                process.env.MEGACOMPACT_VC7A = saved;
+        }
+    };
+}

package/dist/vector-cortex/cache/crystal-emit.js

@@ -0,0 +1,76 @@
+/**
+ * vector-cortex/cache/crystal-emit.ts — VC7A event reporter seam.
+ *
+ * Mirrors `../heal/restore-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit` (unit tests pass `undefined` and stay pure), and the two event
+ * names the sprint spec requires verbatim:
+ *   - `vector_cortex_crystal_written`   — a crystal was frozen and published.
+ *   - `vector_cortex_crystal_collision` — a same-key, different-bytes write was
+ *                                         refused.
+ *
+ * FLAG SEMANTICS. `encodeCrystalKey` and every `CrystalStore` operation are PURE
+ * and run REGARDLESS of `MEGACOMPACT_VC7A`. The flag gates ONLY this reporting +
+ * dashboard seam: with the flag off we still key crystals identically, still
+ * write once, and still refuse collisions — we just do not announce it under the
+ * VC7A event namespace, and the dashboard reports `enabled:false` + mode C. That
+ * is what makes flag-off byte-identical to VC6C: the arithmetic is never skipped,
+ * only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry the KEY DIGEST, byte COUNTS, and the
+ * failure code — never the frozen bytes, never covered source text, never the
+ * span digests of user content. A crystal is a rendered prompt: an unguarded
+ * `payload` field here would dump the entire framed conversation into a log file
+ * (SECURITY_PRIVACY — the exact ledger is not diagnostic data).
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+import { VC7A_ENABLED } from "../../config/vector-cortex.js";
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit, fn) {
+    if (emit === undefined)
+        return;
+    try {
+        fn(emit);
+    }
+    catch {
+        // Non-fatal: a reporting failure must never break the agent loop.
+    }
+}
+/** The event names VC7A emits, exported for the dashboard seam and tests. */
+export const CRYSTAL_EVENT_NAMES = [
+    "vector_cortex_crystal_written",
+    "vector_cortex_crystal_collision",
+];
+/**
+ * Report a published crystal. Key digest + byte count + mode only — enough to
+ * see whether the cache is filling and being hit, without disclosing what was
+ * frozen.
+ */
+export function reportCrystalWritten(emit, payload) {
+    if (!VC7A_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_crystal_written", {
+        ts: undefined,
+        event: "vector_cortex_crystal_written",
+        keyDigest: payload.keyDigest,
+        byteCount: payload.byteCount,
+        mode: payload.mode,
+    }));
+}
+/**
+ * Report a refused write. A collision means two renders of the SAME identity
+ * disagreed — a determinism bug — so the code is surfaced rather than swallowed.
+ * Suppressed under flag-off.
+ */
+export function reportCrystalCollision(emit, payload) {
+    if (!VC7A_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_crystal_collision", {
+        ts: undefined,
+        event: "vector_cortex_crystal_collision",
+        keyDigest: payload.keyDigest,
+        code: payload.code,
+        mode: payload.mode,
+    }));
+}

package/dist/vector-cortex/cache/crystal.js

@@ -0,0 +1,201 @@
+/**
+ * vector-cortex/cache/crystal.ts — canonical crystal key encoding (VC7A).
+ *
+ * Turns a `CrystalKeyV1` into a single stable digest. Everything about the
+ * encoding exists to make two properties simultaneously true:
+ *
+ *   1. IDENTICAL INPUTS ⇒ IDENTICAL KEY, regardless of how the caller ordered
+ *      its ranges or which host produced them. Hence the explicit sort and the
+ *      length-prefixed field framing below.
+ *   2. ANY IDENTITY CHANGE ⇒ DIFFERENT KEY, with no accidental aliasing. Hence
+ *      length prefixes rather than delimiters: a delimiter-joined encoding lets
+ *      an attacker (or an unlucky session name) push a separator into a field
+ *      and forge a collision — `("a|b", "c")` and `("a", "b|c")` hash the same.
+ *      Prefixing every variable-length field with its byte length makes the
+ *      encoding injective, so a collision requires an actual SHA-256 collision.
+ *
+ * WHAT IS DELIBERATELY ABSENT. The global ledger frontier. It is not a
+ * parameter, it is not readable from here, and there is no code path that could
+ * fold it in. An unrelated append advances the frontier constantly; including it
+ * would invalidate every crystal on every turn and the cache would never hit.
+ * The key covers what the render DEPENDED ON, not what the world has since done.
+ *
+ * OVERLAP IS REJECTED, NOT MERGED. Two overlapping ranges in the same session
+ * make "the covered bytes" ambiguous: the overlap region would be hashed twice,
+ * and if the two spans pinned different digests the key would silently encode a
+ * contradiction. `CRY_RANGE_OVERLAP` fails the key closed instead. Ranges in
+ * DIFFERENT sessions never conflict — they cover disjoint byte streams by
+ * construction — so cross-session keys are legal and common.
+ *
+ * PURE. No clock, no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011). Runs identically with `MEGACOMPACT_VC7A` on or off — the flag
+ * gates only the reporter/dashboard seam in `crystal-emit.ts`.
+ */
+import { createHash } from "node:crypto";
+import { CRYSTAL_LIMIT_BYTES, CRYSTAL_LIMIT_RANGES, } from "./types.js";
+/** Encoding version, folded into the digest so a future change cannot alias. */
+const KEY_ENCODING_VERSION = "crystal-key-v1";
+/**
+ * Length-prefixed field append. `<byteLength>:<bytes>` makes the concatenation
+ * injective, so no combination of field contents can impersonate another.
+ */
+function field(parts, value) {
+    parts.push(`${Buffer.byteLength(value, "utf8")}:${value}`);
+}
+/**
+ * Total order over covered ranges: session, then start seq, then start byte.
+ *
+ * Ordering by SOURCE START (not by insertion, not by digest) is what makes the
+ * key independent of how the planner happened to enumerate its spans. `sessionId`
+ * leads because seq numbers are only comparable within a session.
+ */
+export function compareSpans(a, b) {
+    if (a.sessionId !== b.sessionId)
+        return a.sessionId < b.sessionId ? -1 : 1;
+    if (a.startSeq !== b.startSeq)
+        return a.startSeq < b.startSeq ? -1 : 1;
+    if (a.startByte !== b.startByte)
+        return a.startByte - b.startByte;
+    if (a.endSeq !== b.endSeq)
+        return a.endSeq < b.endSeq ? -1 : 1;
+    return a.endByte - b.endByte;
+}
+/** Sort covered ranges into canonical order (never mutates the input array). */
+export function sortSpans(spans) {
+    return [...spans].sort(compareSpans);
+}
+/** A range is malformed if either bound runs backwards or a byte bound is negative. */
+function isMalformed(s) {
+    return (s.endSeq < s.startSeq ||
+        s.startByte < 0 ||
+        s.endByte < s.startByte ||
+        !Number.isSafeInteger(s.startByte) ||
+        !Number.isSafeInteger(s.endByte));
+}
+/**
+ * Byte-range overlap between two spans of the SAME session. Byte bounds are
+ * half-open (`[startByte, endByte)`), so touching ranges (`a.end === b.start`)
+ * are adjacent, not overlapping, and are legal.
+ */
+function overlaps(a, b) {
+    return a.sessionId === b.sessionId && a.startByte < b.endByte && b.startByte < a.endByte;
+}
+/**
+ * Validate covered ranges: non-empty, bounded, well-formed, and disjoint within
+ * each session. Returns deduplicated codes in a deterministic order.
+ */
+export function validateRanges(spans) {
+    const codes = new Set();
+    if (spans.length === 0)
+        codes.add("CRY_RANGE_EMPTY");
+    if (spans.length > CRYSTAL_LIMIT_RANGES)
+        codes.add("CRY_KEY_LIMIT");
+    let totalBytes = 0;
+    for (const s of spans) {
+        if (isMalformed(s))
+            codes.add("CRY_RANGE_INVALID");
+        else
+            totalBytes += s.endByte - s.startByte;
+    }
+    if (totalBytes > CRYSTAL_LIMIT_BYTES)
+        codes.add("CRY_KEY_LIMIT");
+    // Sorted order makes overlap a neighbour check within each session run.
+    const sorted = sortSpans(spans);
+    for (let i = 1; i < sorted.length; i += 1) {
+        const prev = sorted[i - 1];
+        const cur = sorted[i];
+        if (prev !== undefined && cur !== undefined && overlaps(prev, cur)) {
+            codes.add("CRY_RANGE_OVERLAP");
+            break;
+        }
+    }
+    const order = [
+        "CRY_RANGE_EMPTY",
+        "CRY_RANGE_INVALID",
+        "CRY_RANGE_OVERLAP",
+        "CRY_KEY_LIMIT",
+    ];
+    return order.filter((c) => codes.has(c));
+}
+/**
+ * The covered-bytes digest: SHA-256 over the SORTED ranges' identities and their
+ * pinned span digests, `sha256:` prefixed (matching the `DagSpan.digest`
+ * convention the ranges themselves carry).
+ *
+ * The span digests are what make this sensitive to a single covered BYTE: the
+ * ranges alone would be identical if a byte inside an unchanged range mutated,
+ * but the span's pinned digest would not be (CRY-COVERED-002).
+ */
+export function computeCoveredDigest(spans) {
+    const h = createHash("sha256");
+    for (const s of sortSpans(spans)) {
+        const parts = [];
+        field(parts, s.sessionId);
+        field(parts, s.startSeq.toString());
+        field(parts, s.endSeq.toString());
+        field(parts, String(s.startByte));
+        field(parts, String(s.endByte));
+        field(parts, s.digest);
+        h.update(parts.join(""), "utf8");
+    }
+    return `sha256:${h.digest("hex")}`;
+}
+/**
+ * Canonical key bytes. Field order is fixed and every field is length-prefixed;
+ * the ranges are emitted in canonical sort order with an explicit count so a
+ * key with N ranges can never encode the same bytes as one with M.
+ */
+export function encodeCrystalKeyBytes(key) {
+    const parts = [];
+    field(parts, KEY_ENCODING_VERSION);
+    field(parts, key.profileId);
+    field(parts, key.profileVersion);
+    field(parts, key.requestDigest);
+    field(parts, key.rendererVersion);
+    field(parts, key.dependencyHighWater.toString());
+    field(parts, key.coveredDigest);
+    const sorted = sortSpans(key.sourceRanges);
+    field(parts, String(sorted.length));
+    for (const s of sorted) {
+        field(parts, s.sessionId);
+        field(parts, s.startSeq.toString());
+        field(parts, s.endSeq.toString());
+        field(parts, String(s.startByte));
+        field(parts, String(s.endByte));
+        field(parts, s.digest);
+    }
+    return parts.join("");
+}
+/**
+ * Build the canonical key digest for a crystal identity.
+ *
+ * The returned `key` carries the ranges in canonical sorted order and the
+ * RE-DERIVED `coveredDigest`, so a caller that supplied a stale or wrong covered
+ * digest cannot mint a key that disagrees with its own ranges. The digest itself
+ * is bare lowercase hex (it addresses an identity, not source bytes).
+ */
+export function encodeCrystalKey(key) {
+    const codes = validateRanges(key.sourceRanges);
+    if (codes.length > 0)
+        return { ok: false, codes };
+    const normalized = {
+        ...key,
+        sourceRanges: sortSpans(key.sourceRanges),
+        coveredDigest: computeCoveredDigest(key.sourceRanges),
+    };
+    const keyDigest = createHash("sha256")
+        .update(encodeCrystalKeyBytes(normalized), "utf8")
+        .digest("hex");
+    return { ok: true, keyDigest, key: normalized };
+}
+/**
+ * Whether two identities are the same crystal. Used by invalidation fixtures to
+ * state the sprint invariant directly: the key changes IFF an identity field
+ * changes — an unrelated frontier append is not an identity field, so it cannot
+ * appear here at all.
+ */
+export function sameCrystalKey(a, b) {
+    const ea = encodeCrystalKey(a);
+    const eb = encodeCrystalKey(b);
+    return ea.ok && eb.ok && ea.keyDigest === eb.keyDigest;
+}