pi-mega-compact 0.20.19 → 0.20.20

package/dist/src/vector-cortex/platform/emit.js

@@ -0,0 +1,54 @@
+/**
+ * platform/emit.ts — VC8C engine parity/selection reporter seam (FLAG-GATED).
+ *
+ * Mirrors the VC8B policy-emit pattern: a thin `safe()` wrapper around an
+ * optional injected `emit`, and the two event names the sprint spec requires:
+ *   - `vector_cortex_engine_parity_checked`   — a parity report was resolved.
+ *   - `vector_cortex_engine_selection_demoted` — the triad dropped from A.
+ *
+ * FLAG SEMANTICS. The engine selector and cross-conformance runner STILL RUN
+ * regardless of `MEGACOMPACT_VC8C`. The flag gates ONLY this reporting +
+ * dashboard seam: flag-off is byte-identical to the predecessor (VC8B).
+ *
+ * PAYLOAD DISCIPLINE. These events carry only ids, the finite mode, the machine
+ * code, and counts — never artifact bytes, output bytes, or free-text.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+import { VC8C_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.
+    }
+}
+/** Report a resolved engine parity check. Gated by the flag. */
+export function reportEngineParityChecked(emit, parity) {
+    if (!VC8C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_engine_parity_checked", {
+        ts: undefined,
+        event: "vector_cortex_engine_parity_checked",
+        reportId: parity.reportId,
+        fixtureCount: parity.fixtureCount,
+        passed: parity.passed,
+        failed: parity.failed,
+    }));
+}
+/** Report an engine selection demotion away from mode A. Gated by the flag. */
+export function reportEngineSelectionDemoted(emit, demotion) {
+    if (!VC8C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_engine_selection_demoted", {
+        ts: undefined,
+        event: "vector_cortex_engine_selection_demoted",
+        from: demotion.from,
+        to: demotion.to,
+        code: demotion.code,
+    }));
+}

package/dist/src/vector-cortex/platform/select.js

@@ -0,0 +1,104 @@
+/**
+ * platform/select.ts — VC8C canary-selection engine selector (PURE).
+ *
+ * `selectEngine` decides the failure triad mode from a reviewer-accepted
+ * `ParityReportV1` and the current host platform. It admits mode A (qualified
+ * external Rust artifact) ONLY when every piece of evidence lines up:
+ *
+ *   1. The report's ABI version matches ABI_VERSION (RUST-ABI-001).
+ *   2. URL metadata is present (artifactUrl is non-empty).
+ *   3. A commit hash is present (commit is a non-empty hex-ish string).
+ *   4. The artifact's Cargo.lock digest matches the report's evidence digest
+ *      (RUST-META-003) — a digest mismatch MUST reject the artifact.
+ *   5. The platform is in SUPPORTED_PLATFORMS (RUST-PLATFORM-*).
+ *   6. EVERY fixture in the report's matrix resolved ok (RUST-001..030).
+ *
+ * Any failure demotes to B (TS reference). If the TS reference breaker has
+ * opened (`allowLegacy` is set by the caller), the selector demotes further to
+ * C (legacy path) instead — the two-bytes-of-safety pyramid never runs an
+ * unqualified artifact and never silently rides a broken reference.
+ *
+ * Everything here is PURE: no clock, no storage, no network, no flag read. The
+ * flag gates only the reporter seam in emit.ts.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+import { ABI_VERSION, RUST_ABI_MISMATCH, RUST_ARTIFACT_MISSING, RUST_CARGO_DIGEST_MISMATCH, RUST_PARITY_MISMATCH, RUST_PLATFORM_UNSUPPORTED, SUPPORTED_PLATFORMS, } from "./types.js";
+/** Construct a selection failure. */
+function fail(code) {
+    return { code };
+}
+/** Type guard: is this a supported host platform? */
+export function isSupportedPlatform(platform) {
+    return SUPPORTED_PLATFORMS.includes(platform);
+}
+/** A 40-char lowercase hex string is the canonical bare git SHA-256 commit. */
+const COMMIT_RE = /^[0-9a-f]{40}$/;
+/** Validate the ABI version matches EngineAbiV1 exactly. Throws on mismatch. */
+export function validateAbi(abi) {
+    if (abi.version !== ABI_VERSION)
+        throw fail(RUST_ABI_MISMATCH);
+}
+/** Validate URL metadata + commit + Cargo.lock evidence are all present. */
+function validateEvidence(report) {
+    if (report.artifactUrl.length === 0)
+        throw fail(RUST_ARTIFACT_MISSING);
+    if (!COMMIT_RE.test(report.commit))
+        throw fail(RUST_ARTIFACT_MISSING);
+    // SHA-256 hex digests are exactly 64 chars; anything else is not evidence.
+    if (report.cargoLockDigest.length !== 64) {
+        throw fail(RUST_ARTIFACT_MISSING);
+    }
+    if (report.artifactCargoLockDigest.length !== 64) {
+        throw fail(RUST_ARTIFACT_MISSING);
+    }
+}
+/** True when every fixture in the matrix resolved ok. */
+export function matrixAllOk(report) {
+    if (report.matrix.length === 0)
+        return false;
+    return report.matrix.every((f) => f.ok && f.code === null);
+}
+/**
+ * Select the engine mode from a parity report and the host platform.
+ *
+ * Returns mode A only when all six admission checks pass and the digest (the
+ * report's own evidence) is internally consistent with the Cargo.lock the
+ * artifact claims. Otherwise demotes to B; if the TS reference breaker is open
+ * (`allowLegacy`), demotes to C.
+ */
+export function selectEngine(abi, report, platform, allowLegacy = false) {
+    try {
+        validateAbi(abi);
+        validateEvidence(report);
+        if (!isSupportedPlatform(platform))
+            throw fail(RUST_PLATFORM_UNSUPPORTED);
+        if (report.platform !== platform)
+            throw fail(RUST_PLATFORM_UNSUPPORTED);
+        // RUST-META-003: the artifact's own Cargo.lock digest must match the
+        // reviewer-accepted evidence; a mismatch rejects the artifact outright.
+        if (report.artifactCargoLockDigest !== report.cargoLockDigest) {
+            throw fail(RUST_CARGO_DIGEST_MISMATCH);
+        }
+        if (!matrixAllOk(report)) {
+            throw fail(RUST_PARITY_MISMATCH);
+        }
+        const artifact = {
+            url: report.artifactUrl,
+            commit: report.commit,
+            cargoLockDigest: report.cargoLockDigest,
+            platform: report.platform,
+            qualified: true,
+        };
+        return { mode: "A", reason: "qualified", artifact };
+    }
+    catch (e) {
+        const code = typeof e === "object" && e !== null && "code" in e
+            ? String(e.code)
+            : RUST_PARITY_MISMATCH;
+        if (allowLegacy) {
+            return { mode: "C", reason: code, artifact: null };
+        }
+        return { mode: "B", reason: code, artifact: null };
+    }
+}

package/dist/src/vector-cortex/platform/types.js

@@ -0,0 +1,57 @@
+/**
+ * platform/types.ts — VC8C engine ABI + parity report + selection types.
+ *
+ * These are the CANARY-SELECTION contracts. This repo has NO Rust workspace and
+ * creates none: an external Rad repo supplies the artifact URL, commit, and
+ * Cargo.lock digest/evidence as `ParityReportV1`. The selector only ever admits
+ * mode A (qualified external Rust) when every piece of that evidence matches;
+ * otherwise it demotes to B (TS reference) or C (legacy).
+ *
+ * EngineAbiV1 is the FINITE, versioned envelope both sides speak: an input
+ * envelope in, an output envelope out, and a machine-coded error envelope. There
+ * is deliberately no free-text field and no unbounded version string — an ABI
+ * whose version or error space can drift at runtime cannot be cross-checked
+ * against a foreign binary.
+ *
+ * Failure triad (private to the runtime; mirrored here for the selector):
+ *   A = qualified external Rust artifact
+ *   B = TS reference (forced by a parity or metadata failure)
+ *   C = legacy path (forced when the TS reference breaker opens)
+ *
+ * Conformance IDs RUST-001..030 are registered here as the single source of
+ * truth for the sprint's conformance rows; the three named fixtures
+ * (RUST-ABI-001, RUST-ERR-002, RUST-META-003) are the headline assertions.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ */
+/** ABI version string shared by every engine implementation. */
+export const ABI_VERSION = "engine-abi-v1";
+/** Supported host platforms; an artifact for any other platform is rejected. */
+export const SUPPORTED_PLATFORMS = [
+    "linux-x64",
+    "linux-arm64",
+    "darwin-x64",
+    "darwin-arm64",
+    "win32-x64",
+];
+/** Failure code: canonical bytes or failure codes disagreed across runners. */
+export const RUST_PARITY_MISMATCH = "RUST_PARITY_MISMATCH";
+/** Failure code: a neutral frame ended mid-record (partial write/read). */
+export const RUST_FRAME_TRUNCATED = "RUST_FRAME_TRUNCATED";
+/** Failure code: the artifact ABI version does not match ABI_VERSION. */
+export const RUST_ABI_MISMATCH = "RUST_ABI_MISMATCH";
+/** Failure code: the artifact Cargo.lock digest does not match the evidence. */
+export const RUST_CARGO_DIGEST_MISMATCH = "RUST_CARGO_DIGEST_MISMATCH";
+/** Failure code: the artifact targets a platform outside SUPPORTED_PLATFORMS. */
+export const RUST_PLATFORM_UNSUPPORTED = "RUST_PLATFORM_UNSUPPORTED";
+/** Failure code: the report names no artifact (URL/commit missing). */
+export const RUST_ARTIFACT_MISSING = "RUST_ARTIFACT_MISSING";
+/** Conformance IDs RUST-001..RUST-030 for the 30 numbered conformance rows. */
+export const RUST_CONFORMANCE_IDS = Array.from({ length: 30 }, (_v, i) => `RUST-${String(i + 1).padStart(3, "0")}`);
+/** Named conformance fixtures for the sprint's headline assertions. */
+export const RUST_NAMED_FIXTURES = [
+    "RUST-ABI-001",
+    "RUST-ERR-002",
+    "RUST-META-003",
+];

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

@@ -1,14 +1,33 @@
 /**
- * cache/_diagnostics-fixture.ts — VC7C acceptance-test fixture helpers.
+ * cache/_diagnostics-fixture.ts — VC7C conformance fixture I/O + host builders.
  *
- * Reads conformance fixtures from the v2 `cache-diagnostics/` domain and provides
- * a flag-toggling wrapper for VC7C parity tests. Mirrors `_economics-fixture.ts`.
+ * Reads conformance fixtures from the v2 `cache-diagnostics/` domain, decodes
+ * them into the REAL production types (`MissObservation`, `M5Host`) and feeds
+ * them verbatim into `classifyMiss` / `migrateRequestHashV2`. Fixtures store
+ * bigints as JSON numbers — converted here (lossy conversion would break
+ * digests and the acceptance rows would fail loudly).
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `MissObservation` / `M5Host` and drive the production functions directly.
+ * Mirrors `_economics-fixture.ts`.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
-const V2 = join(here, "..", "..", "..", "conformance", "vector-cortex", "v2");
+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);
+}
+const V2 = join(repoRoot(here), "conformance", "vector-cortex", "v2");
 const DIR = join(V2, "cache-diagnostics");
 /** Read + parse one conformance fixture by ID. */
 export function diagnosticsFixture(id) {
@@ -29,3 +48,58 @@ export function withVc7cFlag(value, fn) {
             process.env.MEGACOMPACT_VC7C = prior;
     }
 }
+/** Read a cache-diagnostic fixture as a typed CacheFx. */
+export function cacheFx(id) {
+    return diagnosticsFixture(id);
+}
+/** Decode the fixture's JSON observe into the production MissObservation. */
+export function toObservation(fx) {
+    const o = fx.input.observe;
+    return {
+        requestProfileId: o.requestProfileId,
+        requestProfileVersion: o.requestProfileVersion,
+        cachedProfileId: o.cachedProfileId,
+        cachedProfileVersion: o.cachedProfileVersion,
+        requestCoveredDigest: o.requestCoveredDigest,
+        cachedCoveredDigest: o.cachedCoveredDigest,
+        requestedRangeCount: o.requestedRangeCount,
+        cachedRangeCount: o.cachedRangeCount,
+        requestDigest: o.requestDigest,
+        cachedRequestDigest: o.cachedRequestDigest,
+        requestDependencyHighWater: BigInt(o.requestDependencyHighWater),
+        cachedDependencyHighWater: o.cachedDependencyHighWater === null
+            ? null
+            : BigInt(o.cachedDependencyHighWater),
+        generationInvalidated: o.generationInvalidated,
+    };
+}
+/** Read an M5 fixture as a typed M5Fx. */
+export function m5Fx(id) {
+    return diagnosticsFixture(id);
+}
+/** Build an in-memory M5Host from the fixture input. */
+export function toM5Host(fx) {
+    const v1Rows = fx.input.v1Rows.map((r) => ({
+        profileId: r.profileId,
+        requestDigest: r.requestDigest,
+        hash: r.hash,
+    }));
+    const v2Rows = [];
+    let activeVersion = fx.input.activeVersion;
+    const host = {
+        v1Rows: () => v1Rows,
+        economicsVersionOf: (p) => fx.input.econVersionOf[p] ?? "econ-1",
+        sessionOf: (p) => fx.input.sessionOf[p] ?? "s1",
+        liveGenerationOf: (s) => BigInt(fx.input.liveGenerationOf[s] ?? 0),
+        existingV2: () => v2Rows,
+        putV2: (rows) => v2Rows.push(...rows),
+        activeVersion: () => activeVersion,
+        switchToV2: () => {
+            activeVersion = 2;
+        },
+        get activeVersionAfter() {
+            return activeVersion;
+        },
+    };
+    return host;
+}

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

@@ -34,21 +34,30 @@ function advanceDelta(request, cached) {
 }
 /** Collect the payload-free evidence from one observation. */
 export function collectEvidence(o) {
+    // Absence is computed first: "absence is not a mismatch" means a cold key
+    // (null cached fields) classifies `unknown`, never `profile`/`range`/etc.
+    // The cachedRangeCount on a cold key is 0 by convention (not a real count),
+    // so it must not trigger a range mismatch even though isPresent(0) is true.
+    const absent = !isPresent(o.cachedProfileId) &&
+        !isPresent(o.cachedCoveredDigest) &&
+        !isPresent(o.cachedRequestDigest) &&
+        !isPresent(o.cachedDependencyHighWater);
     const profileMismatch = isPresent(o.cachedProfileId) &&
         isPresent(o.cachedProfileVersion) &&
         (o.cachedProfileId !== o.requestProfileId ||
             o.cachedProfileVersion !== o.requestProfileVersion);
-    const rangeMismatch = (isPresent(o.cachedCoveredDigest) &&
-        o.cachedCoveredDigest !== o.requestCoveredDigest) ||
-        (isPresent(o.cachedRangeCount) &&
-            o.cachedRangeCount !== o.requestedRangeCount);
+    // Guard with !absent: a cold key's cachedRangeCount is 0 by convention (not
+    // a real count), so it must not fire a range mismatch even though
+    // isPresent(0) is true. The covered-digest arm is already null-safe but
+    // the rangeCount arm is not — !absent covers both uniformly.
+    const rangeMismatch = !absent &&
+        ((isPresent(o.cachedCoveredDigest) &&
+            o.cachedCoveredDigest !== o.requestCoveredDigest) ||
+            (isPresent(o.cachedRangeCount) &&
+                o.cachedRangeCount !== o.requestedRangeCount));
     const dep = advanceDelta(o.requestDependencyHighWater, o.cachedDependencyHighWater);
     const requestMismatch = isPresent(o.cachedRequestDigest) &&
         o.cachedRequestDigest !== o.requestDigest;
-    const absent = !isPresent(o.cachedProfileId) &&
-        !isPresent(o.cachedCoveredDigest) &&
-        !isPresent(o.cachedRequestDigest) &&
-        !isPresent(o.cachedDependencyHighWater);
     return {
         profileMismatch,
         rangeMismatch,

package/dist/vector-cortex/controller/_adaptive-fixture.js

@@ -0,0 +1,126 @@
+/**
+ * controller/_adaptive-fixture.ts — VC8B conformance fixture I/O + host builders.
+ *
+ * Reads conformance fixtures from the v2 `adaptive-policy/` domain, decodes
+ * them into the REAL production types (`PolicyInput`, `M7Host`) and feeds
+ * them verbatim into `evaluatePolicy` / `evaluateShadow` / `migratePressureV2`.
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE the
+ * production types and drive the production functions directly.
+ * Mirrors `_diagnostics-fixture.ts` (VC7C) and `_economics-fixture.ts` (VC7B).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+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);
+}
+const V2 = join(repoRoot(here), "conformance", "vector-cortex", "v2");
+const DIR = join(V2, "adaptive-policy");
+/** Read + parse one conformance fixture by ID from adaptive-policy/. */
+export function adaptiveFixture(id) {
+    const raw = readFileSync(join(DIR, `${id}.json`), "utf8");
+    return JSON.parse(raw);
+}
+/** Run `fn` with MEGACOMPACT_VC8B set to `value`, restoring the prior value after. */
+export function withVc8bFlag(value, fn) {
+    const prior = process.env.MEGACOMPACT_VC8B;
+    process.env.MEGACOMPACT_VC8B = value;
+    try {
+        return fn();
+    }
+    finally {
+        if (prior === undefined)
+            delete process.env.MEGACOMPACT_VC8B;
+        else
+            process.env.MEGACOMPACT_VC8B = prior;
+    }
+}
+/** Read a policy-decision fixture as a typed PolFx. */
+export function polFx(id) {
+    return adaptiveFixture(id);
+}
+/** Decode the fixture's JSON input into the production PolicyInput. */
+export function toPolicyInput(fx) {
+    return {
+        decisionId: fx.input.decisionId,
+        sessionId: fx.input.sessionId,
+        pressure: fx.input.pressure,
+        requestedBudget: fx.input.requestedBudget,
+        bounds: {
+            minBudget: fx.input.bounds.minBudget,
+            maxBudget: fx.input.bounds.maxBudget,
+        },
+        ts: fx.input.ts,
+    };
+}
+/** Read a policy-shadow fixture as a typed ShadowFx. */
+export function shadowFx(id) {
+    return adaptiveFixture(id);
+}
+/** Decode shadow input rows into production PolicyInput[]. */
+export function toShadowInputs(fx) {
+    return fx.input.inputs.map((i) => ({
+        decisionId: i.decisionId,
+        sessionId: i.sessionId,
+        pressure: i.pressure,
+        requestedBudget: i.requestedBudget,
+        bounds: {
+            minBudget: i.bounds.minBudget,
+            maxBudget: i.bounds.maxBudget,
+        },
+        ts: i.ts,
+    }));
+}
+/** Read an M7 fixture as a typed M7Fx. */
+export function m7Fx(id) {
+    return adaptiveFixture(id);
+}
+/** Build an in-memory M7Host from the fixture input. */
+export function toM7Host(fx) {
+    const v1Rows = fx.input.v1Rows.map((r) => ({
+        sessionId: r.sessionId,
+        label: r.label,
+        effectiveSeq: r.effectiveSeq,
+        ts: r.ts,
+    }));
+    // For inject-after-copy, the injected row carries a non-canonical label.
+    // migratePressureV2 calls m7Copy first, which throws M7_PRESSURE_UNKNOWN for
+    // the bad label — the result is the same: ok:false, pointer on v1.
+    if (fx.input.injectedRow) {
+        v1Rows.push({
+            sessionId: fx.input.injectedRow.sessionId,
+            label: fx.input.injectedRow.label,
+            effectiveSeq: fx.input.injectedRow.effectiveSeq,
+            ts: fx.input.injectedRow.ts,
+        });
+    }
+    const v2Rows = [];
+    let activeVersion = fx.input.activeVersion ?? 1;
+    const host = {
+        v1Rows: () => v1Rows,
+        existingV2: () => v2Rows,
+        putV2: (rows) => v2Rows.push(...rows),
+        activeVersion: () => activeVersion,
+        switchToV2: () => {
+            activeVersion = 2;
+        },
+        get activeVersionAfter() {
+            return activeVersion;
+        },
+        get v2RowCount() {
+            return v2Rows.length;
+        },
+    };
+    return host;
+}

package/dist/vector-cortex/migrations/request-hash-v2-ops.js

@@ -48,15 +48,23 @@ function generationFromEconomics(economicsVersion) {
 }
 export function detectCollision(host) {
     const byHash = new Map();
-    const seenIdentities = new Set();
+    // Track the v1 hash seen for each identity so a genuine collision (same
+    // identity, DIFFERENT v1 hash) is distinguished from a benign duplicate
+    // (same identity, SAME v1 hash — an idempotent resume re-reads the same row).
+    const identityHash = new Map();
     for (const v1 of host.v1Rows()) {
         const row = deriveRequestHashRow(host, v1);
         const id = identity(v1.profileId, v1.requestDigest);
-        // Two distinct v1 rows (different v1 hash) with the same v2 hash collide,
-        // even if they share an identity — the v2 table cannot distinguish them.
-        if (seenIdentities.has(id))
-            return true;
-        seenIdentities.add(id);
+        const priorHash = identityHash.get(id);
+        if (priorHash !== undefined) {
+            // Same identity seen before. Only a collision if the v1 hashes differ —
+            // two genuinely distinct v1 rows collapsing to one v2 hash. Identical
+            // duplicates (same hash) are benign and skipped.
+            if (priorHash !== v1.hash)
+                return true;
+            continue;
+        }
+        identityHash.set(id, v1.hash);
         const prior = byHash.get(row.hash);
         if (prior !== undefined && prior !== id)
             return true;
@@ -73,17 +81,25 @@ export function isGenerationInvalidated(host, row) {
 }
 export function m5Copy(host) {
     const existing = new Map(host.existingV2().map((r) => [identity(r.profileId, r.requestDigest), r]));
+    // Track identities already in the `wanted` batch so a benign duplicate v1
+    // row (same identity, same hash) does not produce a duplicate v2 write that
+    // would later trip COUNT_MISMATCH in verify.
+    const batchSeen = new Set();
     const wanted = [];
     for (const v1 of host.v1Rows()) {
         const fresh = deriveRequestHashRow(host, v1);
         if (isGenerationInvalidated(host, fresh))
             continue;
-        const stored = existing.get(identity(v1.profileId, v1.requestDigest));
+        const id = identity(v1.profileId, v1.requestDigest);
+        if (batchSeen.has(id))
+            continue;
+        const stored = existing.get(id);
         if (stored !== undefined &&
             stored.hash === fresh.hash &&
             stored.economicsVersion === fresh.economicsVersion) {
             continue;
         }
+        batchSeen.add(id);
         wanted.push(fresh);
     }
     if (wanted.length > 0)

package/dist/vector-cortex/platform/cross-read.js

@@ -0,0 +1,98 @@
+/**
+ * platform/cross-read.ts — VC8C neutral stdin/stdout cross-conformance framing.
+ *
+ * Both the TS reference and an external Rust binary speak ONE neutral wire
+ * format: a sequence of length-prefixed JSON records. Each record is:
+ *
+ *   [4-byte big-endian length][exactly that many bytes of canonical JSON]
+ *
+ * The TS side encodes and decodes this framing; the external runner (a local
+ * subprocess, PREVENT-PI-004: never a URL) reads the same frames on stdin and
+ * writes them back on stdout. Parity is then byte-for-byte: the canonical JSON
+ * bytes of each record and the failure code must match in both directions.
+ *
+ * `outputBytes` is the OCAML-free canonical representation of a fixture's
+ * produced bytes as a HEX STRING, so byte-equality is a plain string compare and
+ * the wire JSON never carries raw binary.
+ *
+ * Everything here is PURE: no clock, no storage, no network, no flag read. The
+ * flag gates only the reporter seam in emit.ts.
+ *
+ * PREVENT-011: no `any` type. PREVENT-PI-004: no network.
+ */
+import { RUST_FRAME_TRUNCATED, RUST_PARITY_MISMATCH } from "./types.js";
+/** Canonical JSON bytes for a neutral record (the wire form of a record body). */
+export function encodeRecordJson(record) {
+    return new TextEncoder().encode(JSON.stringify(record));
+}
+/**
+ * Encode a list of neutral records into the length-framed neutral wire format.
+ * Each record is written as a 4-byte big-endian length followed by exactly that
+ * many canonical JSON bytes, concatenated in order.
+ */
+export function encodeNeutralFrame(fixtures) {
+    const parts = [];
+    for (const fixture of fixtures) {
+        const body = encodeRecordJson(fixture);
+        const header = new Uint8Array(4);
+        new DataView(header.buffer).setUint32(0, body.length, false);
+        parts.push(header, body);
+    }
+    const total = parts.reduce((acc, p) => acc + p.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/**
+ * Decode a neutral frame stream back into records. A partial trailing frame
+ * (a length prefix with fewer body bytes than declared) returns
+ * `{ ok: false, code: "RUST_FRAME_TRUNCATED" }` — the invariant the sprint's
+ * unique failure injection exercises.
+ */
+export function decodeNeutralFrame(bytes) {
+    const records = [];
+    let offset = 0;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const decoder = new TextDecoder();
+    while (offset + 4 <= bytes.byteLength) {
+        const len = view.getUint32(offset, false);
+        offset += 4;
+        if (offset + len > bytes.byteLength) {
+            return { ok: false, code: RUST_FRAME_TRUNCATED };
+        }
+        const body = decoder.decode(bytes.subarray(offset, offset + len));
+        offset += len;
+        try {
+            records.push(JSON.parse(body));
+        }
+        catch {
+            return { ok: false, code: RUST_FRAME_TRUNCATED };
+        }
+    }
+    if (offset !== bytes.byteLength) {
+        // Trailing bytes fewer than one length prefix — the frame was cut mid-header.
+        return { ok: false, code: RUST_FRAME_TRUNCATED };
+    }
+    return { ok: true, records };
+}
+/**
+ * Compare one expected record against one actual record. Both the canonical
+ * output bytes (as hex strings) and the failure code must match. Any byte or
+ * code difference returns `{ ok: false, code: "RUST_PARITY_MISMATCH" }`.
+ */
+export function compareFixtureOutput(expected, actual) {
+    if (expected.fixtureId !== actual.fixtureId) {
+        return { ok: false, code: RUST_PARITY_MISMATCH };
+    }
+    if (expected.outputBytes !== actual.outputBytes) {
+        return { ok: false, code: RUST_PARITY_MISMATCH };
+    }
+    if (expected.failureCode !== actual.failureCode) {
+        return { ok: false, code: RUST_PARITY_MISMATCH };
+    }
+    return { ok: true };
+}