pi-mega-compact 0.16.3 → 0.17.0

package/dist/vector-cortex/eval/types.js

@@ -0,0 +1,33 @@
+/**
+ * vector-cortex/eval/types.ts — MetricEventV1 / AnnotationV1 contract types
+ * and the registered EVAL conformance ID range (EVAL-001..010).
+ *
+ * Owned by VC0A (baseline observability). Consumes reviewer-accepted predecessor
+ * contracts and common contracts only. These are pure type/schema definitions —
+ * no runtime network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+/** Units the evaluator understands. Unknown units reject as EVAL_UNIT_UNKNOWN. */
+export const UNITS = ["ms", "bytes", "count", "ratio"];
+/**
+ * Histogram bucket edges for latency, in milliseconds, inclusive on both
+ * boundaries (EVAL-BUCKET-001): values at exactly 1ms and 250ms land in
+ * those buckets. Overflow (value > largest edge) is kept separate.
+ */
+export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250];
+/**
+ * Registered EVAL conformance ID range (EVAL-001..010). The acceptance test
+ * reads these rows from the v2 manifest and asserts their expected bytes/results.
+ * Registered BEFORE evaluation logic so the manifest/fixture seam is stable.
+ */
+export const EVAL_IDS = [
+    "EVAL-001",
+    "EVAL-002",
+    "EVAL-003",
+    "EVAL-004",
+    "EVAL-005",
+    "EVAL-006",
+    "EVAL-007",
+    "EVAL-008",
+    "EVAL-009",
+    "EVAL-010",
+];

package/dist/vector-cortex/ledger/adapter.js

@@ -0,0 +1,55 @@
+/**
+ * vector-cortex/ledger/adapter.ts — EventV2 ledger adapter (VC1A, task 5).
+ *
+ * A thin, pi-agnostic adapter combining the Mode-A codec, the canonical
+ * validator, and the VC1A emit seam so `vector_cortex_event_decoded` and
+ * `vector_cortex_event_validation_failed` are emitted by REAL code paths (not a
+ * hand-invoked reporter), gated by `VC1A_ENABLED()` inside `createLedgerReporter`.
+ *
+ * The live producer (wiring this into `extensions/mega-compact.ts` /
+ * `src/engine.ts`) is deferred to VC1C/VC1B (mirroring VC0B-I08); this sprint
+ * ships the seam + adapter as the clean single surface, with the acceptance
+ * aggregator exercising the real gated-emission path.
+ *
+ * Pure orchestration — no storage, no network, no side effects (PREVENT-PI-004).
+ */
+import { createEventCodec } from "./event-codec.js";
+import { validateEvents } from "./validator.js";
+import { createLedgerReporter } from "./emit.js";
+/** Build the ledger adapter over an injected emit callback (optional). */
+export function createLedgerAdapter(emit) {
+    const codec = createEventCodec();
+    const reporter = createLedgerReporter(emit);
+    return {
+        encode: (input) => codec.encode(input),
+        decode(event) {
+            const bytes = codec.decode(event);
+            reporter.eventDecoded({
+                session: event.sessionId,
+                seq: event.seq.toString(),
+                eventId: event.eventId,
+                bytes: bytes.length,
+                utf8Valid: event.utf8.valid,
+            });
+            return bytes;
+        },
+        validate(events) {
+            const result = validateEvents(events);
+            if (!result.ok) {
+                // Emit one event per failing occurrence with its REAL locator — a
+                // consumer of the feed can identify WHICH event failed (VC1A-I05).
+                for (const issue of result.issues) {
+                    reporter.validationFailed({
+                        session: issue.sessionId,
+                        seq: issue.seq.toString(),
+                        eventId: issue.eventId,
+                        code: issue.code,
+                    });
+                }
+            }
+            return result;
+        },
+        codec,
+        reporter,
+    };
+}

package/dist/vector-cortex/ledger/compat-journal.js

@@ -0,0 +1,206 @@
+/**
+ * vector-cortex/ledger/compat-journal.ts — CompatJournalV1 (VC1B, task 4).
+ *
+ * The downgrade-safety journal. From v2 activation every accepted v2 append
+ * atomically appends a record holding the original bytes, IDs, and a legacy
+ * projection or an explicit `unrepresentable` marker. The journal tracks its own
+ * lifetime state (prepared → copied → validated → switched) so the M2
+ * downgrade is resumable: a crash mid-journal never corrupts v2, and a restart
+ * resumes idempotently (the unique failure-injection contract).
+ *
+ * `active()` is true once ANY v2 append has been journaled — an old binary may
+ * only open the exported legacy copy, never v2 directly, once the journal is
+ * active (CONTRACTS §Store). Unrepresentable rows (e.g. invalid UTF-8 bytes have
+ * no lossless legacy projection) are listed on prepare and carried through the
+ * copy/validate/switch lifecycle.
+ *
+ * Durable in the same isolated occurrence-v2 SQLite DB as the ledger rows
+ * (append-only provenance: journal records are never UPDATE'd; only the
+ * singleton state row advances phase). PREVENT-002 parameterized; PREVENT-011
+ * no `any`; PREVENT-PI-004 local filesystem only; no console.log.
+ */
+import { createHash } from "node:crypto";
+/** Downgrade-phase validation failure codes (registered as conformance rows). */
+export const MIG_DOWN_FAIL = {
+    NOT_ACTIVE: "MIG_DOWN_NOT_ACTIVE",
+    PHASE_UNREACHED: "MIG_DOWN_PHASE_UNREACHED",
+    SEQ_REGRESSION: "MIG_DOWN_SEQ_REGRESSION",
+    DIGEST_MISMATCH: "MIG_DOWN_DIGEST_MISMATCH",
+    SWITCH_UNSAFE: "MIG_DOWN_SWITCH_UNSAFE",
+};
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS compat_journal_v1 (
+  session             TEXT    NOT NULL,
+  seq                 INTEGER NOT NULL,
+  event_id            TEXT    NOT NULL,
+  digest              TEXT    NOT NULL,
+  kind                TEXT    NOT NULL,
+  legacy_projection   TEXT,
+  unrepresentable     INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (session, seq)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS compat_journal_state (
+  id    INTEGER PRIMARY KEY CHECK (id = 1),
+  phase TEXT NOT NULL
+) STRICT;
+`;
+/** Ensure the journal tables exist and seed the singleton phase row. */
+export function initCompatJournal(db) {
+    db.exec(SCHEMA);
+    db.prepare(`INSERT OR IGNORE INTO compat_journal_state (id, phase) VALUES (1, 'prepared')`).run();
+}
+function phaseOf(db) {
+    const row = db
+        .prepare(`SELECT phase FROM compat_journal_state WHERE id = 1`)
+        .get();
+    return row?.phase ?? "prepared";
+}
+/** Read the durable journal phase (for the M2 migration host seam). */
+export function journalPhase(db) {
+    return phaseOf(db);
+}
+function setPhase(db, phase) {
+    db.prepare(`UPDATE compat_journal_state SET phase = @phase WHERE id = 1`).run({
+        "@phase": phase,
+    });
+}
+/**
+ * Verify a recorded digest by RECOMPUTING sha256 over the base64 source embedded
+ * in the legacy projection and comparing it to the recorded digest (Q03: real
+ * digest parity, not a `sha256:` prefix check). Returns false when the projection
+ * is absent or malformed, or the digest does not match the recomputed hash.
+ */
+export function verifyLegacyDigest(digest, legacyProjection) {
+    if (legacyProjection === null)
+        return false;
+    let rec;
+    try {
+        rec = JSON.parse(legacyProjection);
+    }
+    catch {
+        return false;
+    }
+    const source = rec.source;
+    if (typeof source !== "string")
+        return false;
+    const recomputed = `sha256:${createHash("sha256").update(Buffer.from(source, "base64")).digest("hex")}`;
+    return recomputed === digest;
+}
+/**
+ * Build the CompatJournalV1 over the isolated occurrence-v2 DB. Call
+ * `initCompatJournal` once before use. All record writes are append-only and
+ * best-effort/non-fatal so the agent loop is never broken (PREVENT-PI-004).
+ */
+export function createCompatJournal(db) {
+    return {
+        active() {
+            try {
+                const row = db
+                    .prepare(`SELECT 1 AS hit FROM compat_journal_v1 LIMIT 1`)
+                    .get();
+                return row !== undefined;
+            }
+            catch {
+                return false;
+            }
+        },
+        record(input) {
+            const { occurrence, legacyProjection } = input;
+            try {
+                const unrep = legacyProjection === null;
+                db.prepare(`INSERT INTO compat_journal_v1
+             (session, seq, event_id, digest, kind, legacy_projection, unrepresentable)
+           VALUES (@session, @seq, @event_id, @digest, @kind, @legacy, @unrep)
+           ON CONFLICT(session, seq) DO NOTHING`).run({
+                    "@session": occurrence.session,
+                    "@seq": Number(occurrence.seq),
+                    "@event_id": occurrence.eventId,
+                    "@digest": occurrence.digest,
+                    "@kind": occurrence.kind,
+                    // Q06: an unrepresentable row stores NO projection (legacy_projection
+                    // stays NULL); we never write a base64 body we cannot round-trip.
+                    "@legacy": legacyProjection,
+                    "@unrep": unrep ? 1 : 0,
+                });
+            }
+            catch {
+                /* non-fatal journal write — never break the agent loop */
+            }
+        },
+        isUnrepresentable(eventId, digest) {
+            try {
+                const row = db
+                    .prepare(`SELECT unrepresentable AS u FROM compat_journal_v1
+             WHERE event_id = @event_id AND digest = @digest
+             ORDER BY seq DESC LIMIT 1`)
+                    .get({ "@event_id": eventId, "@digest": digest });
+                return row?.u === 1;
+            }
+            catch {
+                return false;
+            }
+        },
+        prepare() {
+            const rows = db
+                .prepare(`SELECT session, seq, event_id, digest, kind, legacy_projection, unrepresentable
+           FROM compat_journal_v1 ORDER BY session ASC, seq ASC`)
+                .all();
+            setPhase(db, "prepared");
+            return rows.filter((r) => r.unrepresentable === 1).map((r) => r.event_id);
+        },
+        copied() {
+            setPhase(db, "copied");
+        },
+        validate() {
+            const codes = [];
+            const phase = phaseOf(db);
+            if (!isRepresentableState(phase, "copied"))
+                codes.push(MIG_DOWN_FAIL.PHASE_UNREACHED);
+            if (!this.active())
+                codes.push(MIG_DOWN_FAIL.NOT_ACTIVE);
+            // Seq must be strictly increasing within a session (no regression).
+            const prev = new Map();
+            const rows = db
+                .prepare(`SELECT session, seq FROM compat_journal_v1 ORDER BY session ASC, seq ASC`)
+                .all();
+            for (const r of rows) {
+                const last = prev.get(r.session);
+                if (last !== undefined && r.seq <= last)
+                    codes.push(MIG_DOWN_FAIL.SEQ_REGRESSION);
+                prev.set(r.session, r.seq);
+            }
+            // Digests must verify: recompute sha256 over the stored source and compare
+            // to the recorded digest (Q03 — real parity, not just a `sha256:` prefix).
+            for (const r of db
+                .prepare(`SELECT digest, legacy_projection FROM compat_journal_v1 WHERE unrepresentable = 0`)
+                .all()) {
+                if (r.legacy_projection === null)
+                    continue;
+                if (!verifyLegacyDigest(r.digest, r.legacy_projection)) {
+                    codes.push(MIG_DOWN_FAIL.DIGEST_MISMATCH);
+                }
+            }
+            const ok = codes.length === 0;
+            if (ok)
+                setPhase(db, "validated");
+            return { ok, codes: dedupe(codes) };
+        },
+        switched() {
+            if (this.active())
+                setPhase(db, "switched");
+        },
+    };
+}
+/** A phase has reached at least `required` in the prepare→…→switched order. */
+function isRepresentableState(phase, required) {
+    const order = ["prepared", "copied", "validated", "switched"];
+    return order.indexOf(phase) >= order.indexOf(required);
+}
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}

package/dist/vector-cortex/ledger/emit.js

@@ -0,0 +1,53 @@
+/**
+ * vector-cortex/ledger/emit.ts — VC1A ledger emit seam.
+ *
+ * The single structured-event surface for the EventV2 ledger path. It mirrors
+ * the VC0B replay emit seam (`src/vector-cortex/replay/emit.ts`): the same
+ * non-fatal, structured-JSON `ts`+`event` contract (`src/log.ts` LogEntry),
+ * delivered through an injected emit callback so it stays pi-agnostic,
+ * deterministically testable, and network-free (PREVENT-PI-004).
+ *
+ * Carries only the two EventV2 events:
+ *   - vector_cortex_event_decoded          (a V2 occurrence was byte-decoded)
+ *   - vector_cortex_event_validation_failed (a V2 conformity check failed)
+ *
+ * Flag gating: this is VC1A's single real consumer of `VC1A_ENABLED()`. When the
+ * flag is OFF the reporter emits NOTHING (zero observability writes) — the
+ * VC1A mode-C byte-identical behavior — while the codec/validator still operate.
+ * The flag is read per-call so a live toggle takes effect immediately.
+ */
+import { VC1A_ENABLED } from "../../config/vector-cortex.js";
+function safe(fn) {
+    return (event, fields) => {
+        try {
+            fn(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    };
+}
+/**
+ * Build a typed reporter over an injected emit callback. Emission is gated on
+ * `VC1A_ENABLED()` — flag OFF means zero ledger observability writes (mode-C
+ * parity). `emit` is optional: absent (or flag off) degrades to a no-op.
+ */
+export function createLedgerReporter(emit) {
+    const fire = safe((event, fields) => {
+        if (VC1A_ENABLED())
+            emit?.(event, fields);
+    });
+    return {
+        eventDecoded(fields) {
+            fire("vector_cortex_event_decoded", fields);
+        },
+        validationFailed(fields) {
+            fire("vector_cortex_event_validation_failed", fields);
+        },
+    };
+}
+/** Export the event names for consumers that match on them. */
+export const LEDGER_EVENTS = [
+    "vector_cortex_event_decoded",
+    "vector_cortex_event_validation_failed",
+];

package/dist/vector-cortex/ledger/event-codec.js

@@ -0,0 +1,72 @@
+/**
+ * vector-cortex/ledger/event-codec.ts — EventV2 byte-authority codec, Mode A
+ * (VC1A, TRIAD_RESILIENCE).
+ *
+ * A retains `originalBytes` + a SHA-256 `bytesDigest` and classifies strict
+ * UTF-8 (success) vs invalid-byte content WITHOUT replacement decoding:
+ * `TextDecoder(..., {fatal:true})` either yields text or throws — invalid input
+ * is represented only as `{valid:false, base64}` and is NEVER lossy-replaced.
+ * `canonicalNfc` is computed ONLY as a derived field for valid UTF-8 and is
+ * NEVER used for identity, digest, or byte reconstruction — `decode` returns the
+ * authoritative `originalBytes` exactly.
+ *
+ * Mode B (`./event-codecB.ts`) is a genuinely independent implementation of the
+ * same byte rule; A and B share no subroutine and must agree byte-for-byte.
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+import nodeCrypto from "node:crypto";
+/** Mode-A internal SHA-256 helper (NOT shared with mode B). */
+function digestSha256A(bytes) {
+    const hex = nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+    return `sha256:${hex}`;
+}
+/** Mode-A internal base64 (NOT shared with mode B). */
+function base64EncodeA(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+/**
+ * Strict UTF-8 classification with FATAL decoding (never replaces invalid bytes
+ * with U+FFFD). Returns the decoded text, or `{valid:false, base64}`.
+ */
+export function classifyUtf8(bytes) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return { valid: true, text };
+    }
+    catch {
+        return { valid: false, base64: base64EncodeA(bytes) };
+    }
+}
+/** Build the Mode-A byte-authority codec. */
+export function createEventCodec() {
+    return {
+        encode(input) {
+            const bytes = input.bytes;
+            const bytesDigest = digestSha256A(bytes);
+            const utf8 = classifyUtf8(bytes);
+            const event = {
+                schema: "event-v2",
+                sessionId: input.sessionId,
+                seq: input.seq,
+                eventId: input.eventId,
+                role: input.role,
+                kind: input.kind,
+                originalBytes: bytes,
+                bytesDigest,
+                utf8,
+                occurredAtMs: input.occurredAtMs,
+            };
+            if (input.toolCallId !== undefined)
+                event.toolCallId = input.toolCallId;
+            // canonicalNfc is a DERIVED search key — valid UTF-8 only, never identity.
+            if (utf8.valid)
+                event.canonicalNfc = utf8.text.normalize("NFC");
+            return event;
+        },
+        decode(event) {
+            return event.originalBytes;
+        },
+        classifyUtf8,
+    };
+}

package/dist/vector-cortex/ledger/event-codecB.js

@@ -0,0 +1,76 @@
+/**
+ * vector-cortex/ledger/event-codecB.ts — EventV2 byte-authority codec, Mode B
+ * (VC1A, TRIAD_RESILIENCE).
+ *
+ * B is a GENUINELY independent raw-byte record implementation of the SAME byte
+ * rule as Mode A (`./event-codec.ts`). It shares NO subroutine with A: its own
+ * SHA-256 helper, its own base64 helper, its own strict-UTF-8 classifier, and
+ * its own raw record — the lesson from VC0B-I09 (a mode-B tested against code
+ * identical to A is a tautology). Because the digest of given bytes is a pure
+ * function, two independent implementations MUST agree byte-for-byte; the
+ * acceptance test asserts `bytesDigest` parity across the fixture corpus.
+ *
+ * B retains `originalBytes` + `bytesDigest` and classifies strict UTF-8 with no
+ * lossy replacement; `canonicalNfc` is derived for valid UTF-8 but never used
+ * for identity, digest, or reconstruction.
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+import nodeCrypto from "node:crypto";
+/** Mode-B internal SHA-256 helper (independent of A's — no shared subroutine). */
+function digestSha256B(bytes) {
+    const d = nodeCrypto.createHash("sha256");
+    d.update(bytes);
+    const hex = d.digest("hex");
+    return `sha256:${hex}`;
+}
+/** Mode-B internal base64 (independent of A's). */
+function base64EncodeB(bytes) {
+    let out = "";
+    const buf = Buffer.from(bytes);
+    for (let i = 0; i < buf.length; i += 3) {
+        const b0 = buf[i];
+        const b1 = i + 1 < buf.length ? buf[i + 1] : -1;
+        const b2 = i + 2 < buf.length ? buf[i + 2] : -1;
+        out += CHARS[(b0 >> 2) & 63];
+        out += CHARS[((b0 & 3) << 4) | (b1 < 0 ? 0 : (b1 >> 4) & 15)];
+        if (b1 >= 0)
+            out += CHARS[((b1 & 15) << 2) | (b2 < 0 ? 0 : (b2 >> 6) & 3)];
+        if (b2 >= 0)
+            out += CHARS[b2 & 63];
+    }
+    // Padding (independent reconstruction of standard base64).
+    const pad = (3 - (buf.length % 3)) % 3;
+    for (let i = 0; i < pad; i++)
+        out += "=";
+    return out;
+}
+const CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Mode-B strict UTF-8 classifier (fatal decode; no replacement). */
+function classifyUtf8B(bytes) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return { valid: true, text };
+    }
+    catch {
+        return { valid: false, base64: base64EncodeB(bytes) };
+    }
+}
+/** Independently digest + classify raw bytes into a B record. */
+export function recordRawBytesB(bytes) {
+    const bytesDigest = digestSha256B(bytes);
+    const utf8 = classifyUtf8B(bytes);
+    const record = { originalBytes: bytes, bytesDigest, utf8 };
+    if (utf8.valid) {
+        return { originalBytes: bytes, bytesDigest, utf8, canonicalNfc: utf8.text.normalize("NFC") };
+    }
+    return record;
+}
+/**
+ * Independent digest check: recompute the SHA-256 over an EventV2's
+ * `originalBytes` via B's OWN algorithm and compare to the stored digest.
+ * Returns the recomputed digest string (parity-checked by the caller).
+ */
+export function digestCheckB(event) {
+    return digestSha256B(event.originalBytes);
+}