pi-mega-compact 0.17.0 → 0.18.0

package/dist/vector-cortex/conformance/triadB-reader.js

@@ -0,0 +1,95 @@
+/**
+ * conformance/triadB-reader.ts — TRIAD-B independent exact reader (VC1C).
+ *
+ * Deliberately shares NO code and NO cached-seed instance with the runner
+ * modules (l1-minhash-v2.ts / l1-lsh-v2.ts). It re-derives the minhash-v2
+ * signature and 64 bucket keys from first principles, using only the PUBLISHED
+ * (a,b) seed pairs passed in (read by the caller from
+ * conformance/.../minhash/seeds-v2.json — the table authored independently by
+ * scripts/gen-fixtures/minhash.mjs, the same process that produced the frozen
+ * fixture bytes). Because B shares no subroutine with the runner, a systematic
+ * error in the runner's splitmix64 / seed-derivation / signature arithmetic
+ * cannot satisfy both triad A and triad B.
+ *
+ * Pure compute, no deps, no storage, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+const MASK64 = 0xffffffffffffffffn;
+const P = (1n << 61n) - 1n; // 2^61 - 1
+const SLOTS = 256;
+const U64 = 8;
+const BANDS = 64;
+/** 64-bit FNV-1a over UTF-8 bytes or a raw byte buffer (own, independent loop). */
+function fnv1a64(input) {
+    let h = 0xcbf29ce484222325n;
+    for (const b of Buffer.from(input)) {
+        h = ((h ^ BigInt(b)) * 0x100000001b3n) & MASK64;
+    }
+    return h;
+}
+/**
+ * Re-derive the 2048-byte minhash-v2 signature and (optionally) the 64 LSH
+ * bucket keys for `text` within `session`, from published seed pairs only —
+ * never the runner module.
+ */
+export function independentReaderV2(text, session, seedPairs, withBuckets) {
+    // Normalization: ANSI-strip, NFC, case-fold, CRLF->LF, whitespace collapse,
+    // 32K cap — mirrored from the frozen VC1C spec.
+    let norm = (text || "")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .normalize("NFC")
+        .toLowerCase()
+        .replace(/\r\n?/g, "\n")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (norm.length > 32768)
+        norm = norm.slice(0, 32768);
+    // Five-code-point shingles (deduped, capped at 50_000).
+    const grams = [];
+    if (norm.length > 0) {
+        const cps = Array.from(norm);
+        const seen = new Set();
+        const short = cps.length < 5;
+        for (let i = 0; i < (short ? 1 : cps.length - 4); i++) {
+            const h = short ? fnv1a64(norm) : fnv1a64(cps.slice(i, i + 5).join(""));
+            if (!seen.has(h)) {
+                seen.add(h);
+                grams.push(h);
+            }
+            if (!short && seen.size >= 50000)
+                break;
+        }
+    }
+    // Signature: slot i = min over shingles of (a_i*x + b_i) mod p (exact BigInt).
+    const sig = new Array(SLOTS).fill(P);
+    for (let i = 0; i < SLOTS && grams.length > 0; i++) {
+        const pair = seedPairs[i];
+        const a = BigInt(pair.a);
+        const b = BigInt(pair.b);
+        let min = P;
+        for (const x of grams) {
+            const h = (a * x + b) % P;
+            if (h < min)
+                min = h;
+        }
+        sig[i] = min;
+    }
+    // Own 256 x u64 little-endian encoder.
+    const buf = Buffer.allocUnsafe(SLOTS * U64);
+    for (let i = 0; i < SLOTS; i++)
+        buf.writeBigUInt64LE(sig[i], i * U64);
+    const bytes = new Uint8Array(buf);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    // 64 buckets: FNV-1a over `<session>|v2|` + each 32-byte band (LE hex).
+    const buckets = [];
+    if (withBuckets) {
+        const prefix = Buffer.from(`${session}|v2|`, "utf8");
+        for (let band = 0; band < BANDS; band++) {
+            const bandBytes = Buffer.from(bytes.slice(band * 32, band * 32 + 32));
+            const out = Buffer.allocUnsafe(U64);
+            out.writeBigUInt64LE(fnv1a64(Buffer.concat([prefix, bandBytes])), 0);
+            buckets.push(`b${band}:${out.toString("hex")}`);
+        }
+    }
+    return { bytes, digest, buckets };
+}

package/dist/vector-cortex/encoder/asset.js

@@ -0,0 +1,142 @@
+/**
+ * vector-cortex/encoder/asset.ts — VC2A asset verification (task 2).
+ *
+ * Verifies a ModelManifestV1 before any allocation: SHA-256 the ONNX and
+ * tokenizer against the manifest digests, require opset 17, batch exactly 1 and
+ * maximum 512 tokens, and confirm the current platform is in the supported
+ * matrix. On ANY of these the caller demotes to mode B (asset-free trigram) —
+ * never a remote fetch (PREVENT-PI-004). A truncated/unreadable asset during
+ * the digest read demotes with ENC_ASSET_UNREADABLE.
+ *
+ * Pi-agnostic. Filesystem reads only, zero network (PREVENT-PI-004).
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_FAIL, ENCODER_BATCH, ENCODER_MAX_TOKENS, ENCODER_OPSET, ENCODER_SUPPORTED_PLATFORMS, } from "./types.js";
+/** True when `p` is a single basename: non-empty, no path separators, no "..",
+ *  no leading dot-segment traversal. Keeps manifest-controlled asset paths
+ *  confined to the asset directory (no path-traversal via join()). */
+function isBasename(p) {
+    if (!p || p.length === 0 || p.includes("/") || p.includes("\\"))
+        return false;
+    if (p === "." || p === "..")
+        return false;
+    return true;
+}
+/** Digest the on-disk bytes of one asset file; "" on unreadable (truncated). */
+function digestFile(path) {
+    try {
+        const buf = readFileSync(path);
+        return createHash("sha256").update(buf).digest("hex");
+    }
+    catch {
+        // Truncated / unreadable during the digest read -> ENC_ASSET_UNREADABLE.
+        return null;
+    }
+}
+/**
+ * Detect the current platform (MODEL_ASSET supported matrix). Unrecognized
+ * hosts return null so verification demotes to mode B (unsupported platform).
+ */
+export function detectPlatform(host = process.platform, arch = process.arch) {
+    if (!host || !arch)
+        return null;
+    // Normalize "win32"/"win32"/"linux"/"darwin" + "x64"/"arm64".
+    const plat = host === "win32" ? "win32" : host === "darwin" ? "darwin" : host === "linux" ? "linux" : "";
+    const a = arch === "x64" ? "x64" : arch === "arm64" ? "arm64" : "";
+    if (!plat || !a)
+        return null;
+    const candidate = `${plat}-${a}`;
+    return ENCODER_SUPPORTED_PLATFORMS.includes(candidate)
+        ? candidate
+        : null;
+}
+function isManifest(m) {
+    const o = m;
+    return (!!o &&
+        typeof o === "object" &&
+        o.schema === "model-manifest-v1" &&
+        typeof o.opset === "number" &&
+        typeof o.batch === "number" &&
+        typeof o.maxTokens === "number" &&
+        typeof o.platform === "string" &&
+        !!o.onnx &&
+        !!o.tokenizer &&
+        typeof o.onnx.path === "string" &&
+        typeof o.onnx.sha256 === "string" &&
+        typeof o.tokenizer.path === "string" &&
+        typeof o.tokenizer.sha256 === "string");
+}
+/**
+ * Verify the asset manifest + digest + constraints BEFORE allocation.
+ *
+ *   - manifest parse/shape failure      -> ENC_MANIFEST_INVALID -> mode B
+ *   - unsupported platform              -> ENC_PLATFORM_UNSUPPORTED -> mode B
+ *   - opset != 17                       -> ENC_OPSET_INVALID -> mode B
+ *   - batch != 1                        -> ENC_BATCH_INVALID -> mode B
+ *   - maxTokens > 512                   -> ENC_TOKENS_EXCEEDED -> mode B
+ *   - on-disk digest != manifest digest -> ENC_DIGEST_MISMATCH (one-byte mutation)
+ *   - unreadable/truncated file         -> ENC_ASSET_UNREADABLE
+ *
+ * Returns ok only when EVERY constraint passes and both files hash to the
+ * declared digests (the "only batch1/max512 verified assets reach inference"
+ * invariant). The ok result surfaces the verified manifest's `maxTokens`
+ * (<= 512) so the runtime can enforce the per-manifest token capacity at
+ * inference (Q03), not just the global 512 ceiling.
+ */
+export function verifyEncoderAsset(assetDir, manifest, platform = detectPlatform()) {
+    if (typeof manifest !== "object" || manifest === null || !isManifest(manifest)) {
+        return { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+    }
+    if (!platform)
+        return { ok: false, code: ENC_FAIL.PLATFORM_UNSUPPORTED };
+    // The manifest's declared platform must match the runtime host (per-platform
+    // asset pinning): a bundle cross-shipped to the wrong arch is not qualified.
+    if (manifest.platform !== platform)
+        return { ok: false, code: ENC_FAIL.PLATFORM_UNSUPPORTED };
+    if (manifest.opset !== ENCODER_OPSET)
+        return { ok: false, code: ENC_FAIL.OPSET_INVALID };
+    if (manifest.batch !== ENCODER_BATCH)
+        return { ok: false, code: ENC_FAIL.BATCH_INVALID };
+    if (manifest.maxTokens > ENCODER_MAX_TOKENS)
+        return { ok: false, code: ENC_FAIL.TOKENS_EXCEEDED };
+    // Constrain asset paths to basenames (no separators / no '..') so a forged
+    // manifest cannot read digests from arbitrary paths off the asset dir.
+    if (!isBasename(manifest.onnx.path) || !isBasename(manifest.tokenizer.path)) {
+        return { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+    }
+    const onnxPath = join(assetDir, manifest.onnx.path);
+    const onnxDigest = digestFile(onnxPath);
+    if (onnxDigest === null)
+        return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+    if (onnxDigest !== manifest.onnx.sha256)
+        return { ok: false, code: ENC_FAIL.DIGEST_MISMATCH };
+    const tokPath = join(assetDir, manifest.tokenizer.path);
+    const tokDigest = digestFile(tokPath);
+    if (tokDigest === null)
+        return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+    if (tokDigest !== manifest.tokenizer.sha256)
+        return { ok: false, code: ENC_FAIL.DIGEST_MISMATCH };
+    let embeddedBytes = 0;
+    try {
+        embeddedBytes = statSync(onnxPath).size + statSync(tokPath).size;
+    }
+    catch {
+        return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+    }
+    return { ok: true, embeddedBytes, maxTokens: manifest.maxTokens, onnxDigest, tokenizerDigest: tokDigest };
+}
+/**
+ * Read + shape-check a committed ModelManifestV1 from an asset directory.
+ * Returns the parsed manifest or null when the file is absent/malformed.
+ */
+export function readEncoderManifest(assetDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(assetDir, "manifest.json"), "utf8"));
+        return isManifest(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * vector-cortex/encoder/emit.ts — VC2A observability seam.
+ *
+ * Emits the two VC2A structured events, gated on `MEGACOMPACT_VC2A` (mode C
+ * parity: flag OFF => zero emissions). Every event is a JSON line with `ts` +
+ * `event` (ENGINEERING_PRACTICES §8); the emitters are never fatal on consumer
+ * failure (non-fatal observability, never breaks the agent loop).
+ *
+ *   vector_cortex_encoder_asset_verified   — a qualified manifest+digest load
+ *   vector_cortex_encoder_runtime_demoted  — a demotion to mode B or C
+ *
+ * No network, no side effects beyond the supplied emit callback
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+import { VC2A_ENABLED } from "../../config/vector-cortex.js";
+/** A flag-gated no-op reporter (zero emissions, default when none injected). */
+export const NOOP_ENCODER_REPORTER = {
+    assetVerified: () => { },
+    runtimeDemoted: () => { },
+};
+/**
+ * Flag-gated emit: no-op when VC2A is off or no emitter is supplied. The
+ * returned reporter is itself flag-gated (`VC2A_ENABLED`), so wiring it into a
+ * runtime seam yields zero emissions when `MEGACOMPACT_VC2A=0` (byte-identical
+ * to the predecessor).
+ */
+export function createEncoderReporter(emit) {
+    const fire = (event, fields) => {
+        if (!VC2A_ENABLED())
+            return;
+        try {
+            emit?.(event, { ...fields, ts: new Date().toISOString() });
+        }
+        catch {
+            /* non-fatal observability */
+        }
+    };
+    return {
+        assetVerified: (fields) => fire("vector_cortex_encoder_asset_verified", fields),
+        runtimeDemoted: (fields) => fire("vector_cortex_encoder_runtime_demoted", fields),
+    };
+}

package/dist/vector-cortex/encoder/runtime.js

@@ -0,0 +1,228 @@
+/**
+ * vector-cortex/encoder/runtime.ts — VC2A EncoderRuntime (task 3).
+ *
+ * Allocates (prepares an inference session) ONLY after manifest verification;
+ * rejects any non (batch 1, tokens <= maxTokens, <=512) input with
+ * ENC_SHAPE_INVALID; caps the encoder's MARGINAL footprint at 150 MiB
+ * (ENC_RSS_BUDGET_EXCEEDED -> mode B); and yields a deterministic mode-A
+ * inference over the verified asset (the trained weights are substituted in
+ * VC2C — the contract, shape gating and budgets all land here).
+ *
+ * MEMORY BUDGET (Q01/Q02): the 150 MiB cap measures the encoder's INCREMENTAL
+ * footprint — an in-process allocation counter (`selfAllocated`) plus any
+ * externally staged asset working set (`host.allocatedBytes()`) — NOT the
+ * whole-process RSS. In a live pi extension the process baseline (node:sqlite
+ * DatabaseSync + dashboard + loaded context) routinely exceeds 150 MiB, so an
+ * absolute-RSS cap would permanently demote a qualified asset to mode B and
+ * make mode A unreachable in production. Bounding the marginal footprint keeps
+ * mode A reachable while still enforcing the budget. `selfAllocated` models a
+ * single REUSABLE 384-float projection buffer (first inference allocates it,
+ * every later inference reuses it), so it is capped at `SEMANTIC_BUFFER_BYTES`
+ * — the marginal footprint can never grow without bound (Q01), and a long-lived
+ * runtime cannot drift over budget from healthy operation. The check runs
+ * BEFORE the allocation on both the load and the inference path
+ * (cap-before-allocation, task 3), and an over-budget inference demotes the
+ * runtime to mode B just as an over-budget load does (consistent demotion per
+ * ENC_FAIL.RSS_BUDGET_EXCEEDED).
+ *
+ * TOKEN CAPACITY (Q03): the per-manifest `maxTokens` (<= 512) is stored at load
+ * and enforced at inference — an input longer than the verified manifest's
+ * declared capacity is rejected with ENC_SHAPE_INVALID, honoring the model
+ * contract rather than a global 512 ceiling.
+ *
+ * FLAG GATING (Q04): the default factory consults `MEGACOMPACT_VC2A`; when the
+ * flag is OFF the runtime is fixed at mode C (rollback, byte-identical to the
+ * predecessor — no asset is read or verified). `forcedMode: "C"` is the
+ * explicit override for the same rollback path.
+ *
+ * Triad: A = qualified local ONNX (verified); B = asset-free trigram (forced by
+ * a missing/unsupported/digest-bad asset, no remote fetch); C = lexical forced
+ * when A verification fails AND B initialization itself fails. Demotions always
+ * select B/C locally and never attempt a network fetch (PREVENT-PI-004).
+ *
+ * Pi-agnostic. No `any` (PREVENT-011). Emits the two VC2A events via the
+ * reporter (non-fatal).
+ */
+import { detectPlatform, readEncoderManifest, verifyEncoderAsset, } from "./asset.js";
+import { createEncoderReporter } from "./emit.js";
+import { VC2A_ENABLED } from "../../config/vector-cortex.js";
+import { ENC_FAIL, ENCODER_MAX_TOKENS, ENCODER_RSS_BUDGET_BYTES, ENCODER_SEMANTIC_WIDTH, } from "./types.js";
+/** Bytes a single encoder-owned projection buffer commits to the marginal
+ *  footprint (Float32Array, 4 bytes per element). */
+const SEMANTIC_BUFFER_BYTES = ENCODER_SEMANTIC_WIDTH * 4;
+const DEFAULT_HOST = {
+    allocatedBytes: () => 0,
+    allocatorFails: () => false,
+    nowMs: () => Date.now(),
+};
+function mergeHost(partial) {
+    return { ...DEFAULT_HOST, ...partial };
+}
+/** A deterministic seeded projection so the mode-A inference path is testable
+ *  end-to-end without onnxruntime (real weights + execution are VC2C). */
+function projectSemantic(seed, n) {
+    const out = new Float32Array(n);
+    let state = (seed >>> 0) ^ 0x9e3779b9;
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        state = (state * 1664525 + 1013904223) >>> 0;
+        out[i] = (state / 4294967296) * 2 - 1;
+        sum += out[i] * out[i];
+    }
+    const norm = Math.sqrt(sum) || 1;
+    for (let i = 0; i < n; i++)
+        out[i] = out[i] / norm;
+    return out;
+}
+/** Deterministic token seed derived from the verified asset bytes count. */
+function seedFromBytes(embeddedBytes) {
+    return (embeddedBytes * 2654435761) >>> 0;
+}
+function modeLabel(mode) {
+    return mode === "A" ? "qualified-onnx" : mode === "B" ? "trigram" : "lexical";
+}
+export function createEncoderRuntime(options = {}) {
+    const reporter = options.reporter ?? createEncoderReporter();
+    const host = mergeHost(options.host);
+    const forced = options.forcedMode;
+    const plat = options.platform ?? detectPlatform;
+    // Q04: rollback contract — MEGACOMPACT_VC2A=0 selects mode C (byte-identical
+    // to the predecessor: no asset read/verify, no learned infer). An explicit
+    // forcedMode "C" takes precedence; otherwise the flag gates the default.
+    const rolledBack = forced === "C" || !VC2A_ENABLED();
+    let mode = rolledBack ? "C" : "C";
+    let embeddedBytes = 0;
+    let verified = false;
+    /** Per-manifest token capacity (<= 512) from the verified asset; enforced at
+     *  inference (Q03). Defaults to the global ceiling before a load. */
+    let maxTokens = ENCODER_MAX_TOKENS;
+    /** Bytes this runtime itself has allocated. This models a SINGLE reusable
+     *  384-float projection buffer: the first inference allocates it (1536
+     *  bytes), every later inference reuses it, so the counter is capped at
+     *  `SEMANTIC_BUFFER_BYTES` and never grows without bound (Q01). Combined
+     *  with `host.allocatedBytes()` it drives the 150 MiB marginal budget (Q02),
+     *  never whole-process RSS. */
+    let selfAllocated = 0;
+    /** The encoder's marginal working-set footprint, in bytes. */
+    const footprint = () => selfAllocated + host.allocatedBytes();
+    const demoteTo = (rmode, code) => {
+        mode = rmode;
+        verified = false;
+        reporter.runtimeDemoted({ reason: code, mode: rmode, platform: plat()?.toString() ?? "unsupported" });
+    };
+    const runtime = {
+        schema: "encoder-runtime-v1",
+        // Live getter so `mode` always reflects the latest load/demote outcome
+        // (a plain property would freeze at its construction-time value forever).
+        get mode() {
+            return mode;
+        },
+        load(assetDir) {
+            if (rolledBack) {
+                // Rollback path (forcedMode "C" or MEGACOMPACT_VC2A=0): mode C restores
+                // the prior derived pointer; no asset is read or verified; no emission.
+                // Q04: report the rollback with its own code, not MANIFEST_INVALID, so a
+                // correctly-shaped, digest-correct asset is not mis-read as corrupted.
+                mode = "C";
+                verified = false;
+                return { ok: false, mode: "C", code: ENC_FAIL.ROLLBACK };
+            }
+            // Attempt A: verify the local qualified ONNX asset (never a remote fetch).
+            const manifest = readEncoderManifest(assetDir);
+            let verify;
+            if (manifest === null) {
+                verify = { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+            }
+            else {
+                verify = verifyEncoderAsset(assetDir, manifest, plat());
+            }
+            if (!verify.ok) {
+                // A failed -> B, unless B init itself fails (allocator) -> C.
+                if (host.allocatorFails()) {
+                    demoteTo("C", ENC_FAIL.ASSET_UNREADABLE);
+                    return { ok: false, mode: "C", code: ENC_FAIL.ASSET_UNREADABLE };
+                }
+                demoteTo("B", verify.code);
+                return { ok: false, mode: "B", code: verify.code };
+            }
+            // Allocate only after verification (task 3). Simulate allocator failure.
+            if (host.allocatorFails()) {
+                demoteTo("B", ENC_FAIL.ASSET_UNREADABLE);
+                return { ok: false, mode: "B", code: ENC_FAIL.ASSET_UNREADABLE };
+            }
+            // Cap the encoder's MARGINAL footprint at 150 MiB (task 3, Q01). This
+            // bounds the encoder's incremental allocation, so a healthy process with
+            // a large baseline RSS still reaches mode A.
+            if (footprint() > ENCODER_RSS_BUDGET_BYTES) {
+                demoteTo("B", ENC_FAIL.RSS_BUDGET_EXCEEDED);
+                return { ok: false, mode: "B", code: ENC_FAIL.RSS_BUDGET_EXCEEDED };
+            }
+            embeddedBytes = verify.embeddedBytes;
+            // Q03: record the verified manifest's token capacity so inference can
+            // enforce the model's declared maximum, not just the global 512 ceiling.
+            maxTokens = verify.maxTokens;
+            verified = true;
+            mode = "A";
+            reporter.assetVerified({
+                mode: "A",
+                embeddedBytes: verify.embeddedBytes,
+                onnxDigest: verify.onnxDigest.slice(0, 12),
+            });
+            return {
+                ok: true,
+                mode: "A",
+                embeddedBytes: verify.embeddedBytes,
+                rssBytes: footprint(),
+                sessionId: `enc-${seedFromBytes(verify.embeddedBytes).toString(16)}`,
+            };
+        },
+        infer(input) {
+            if (!verified || mode !== "A") {
+                // Only batch1/max512 verified assets reach inference (mode B/C do not).
+                return {
+                    ok: false,
+                    code: ENC_FAIL.SHAPE_INVALID,
+                    shapeError: "no verified learned asset; mode is " + modeLabel(mode),
+                };
+            }
+            if (!input || !Array.isArray(input.tokens)) {
+                return { ok: false, code: ENC_FAIL.SHAPE_INVALID, shapeError: "missing tokens array" };
+            }
+            const n = input.tokens.length;
+            // Q03: enforce the per-manifest maxTokens (<= global 512 ceiling), so an
+            // over-cap request against a low-cap verified asset is rejected rather
+            // than silently exceeding the model's declared capacity.
+            if (n < 1 || n > maxTokens) {
+                return {
+                    ok: false,
+                    code: ENC_FAIL.SHAPE_INVALID,
+                    shapeError: `token count ${n} outside 1..${maxTokens} (manifest cap)`,
+                };
+            }
+            // Q03: cap-before-allocation on the inference path too. Check the
+            // marginal footprint BEFORE allocating the projection buffer; an
+            // over-budget inference demotes to mode B consistently with load() (the
+            // ENC_FAIL.RSS_BUDGET_EXCEEDED model: "measured RSS over 150 MiB -> B"),
+            // so a subsequent infer no longer attempts allocation in a stale mode A.
+            if (footprint() > ENCODER_RSS_BUDGET_BYTES) {
+                demoteTo("B", ENC_FAIL.RSS_BUDGET_EXCEEDED);
+                return {
+                    ok: false,
+                    code: ENC_FAIL.RSS_BUDGET_EXCEEDED,
+                    shapeError: "encoder footprint over budget during inference",
+                };
+            }
+            const start = host.nowMs();
+            // Batch is always 1 (single request); shape is (1, n) for n in 1..maxTokens.
+            const semantic = projectSemantic(seedFromBytes(embeddedBytes) ^ n, ENCODER_SEMANTIC_WIDTH);
+            // Q01: the projection buffer is a single reusable 384-float array; the
+            // marginal footprint is a fixed SEMANTIC_BUFFER_BYTES once it exists, so
+            // selfAllocated is SET (never accumulated) — bounded regardless of how
+            // many inferences run on a long-lived runtime.
+            selfAllocated = SEMANTIC_BUFFER_BYTES;
+            const latencyMs = host.nowMs() - start;
+            return { ok: true, semantic, rssBytes: footprint(), latencyMs, shapeError: null };
+        },
+    };
+    return runtime;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * vector-cortex/encoder/types.ts — VC2A contract (ModelManifestV1 /
+ * EncoderRuntime).
+ *
+ * The offline encoder runtime owns the learned-asset path (triad mode A: a
+ * qualified local ONNX). MODEL_ASSET.md is the normative target. This
+ * sprint (VC2A) ships the manifest + verification + shaped-inference contract;
+ * the trained weights are packaged in VC2C (MODEL_ASSET: "package.json changes
+ * occur only in VC2C"), but the verification, digest-before-load, platform
+ * demotion, shape rejection and RSS/latency budget all land here so a later
+ * sprint only substitutes real weights.
+ *
+ * Contract-first (ENGINEERING_PRACTICES §3): this types file is the reviewed
+ * gate; implementations import from it; consumers import only types + factory.
+ *
+ * Pi-agnostic and dependency-free (PREVENT-PI-004 — local assets only, the
+ * runtime never fetches). No `any` (PREVENT-011).
+ */
+/** Supported matrix from MODEL_ASSET.md §qualification. */
+export const ENCODER_SUPPORTED_PLATFORMS = [
+    "linux-x64",
+    "linux-arm64",
+    "darwin-x64",
+    "darwin-arm64",
+    "win32-x64",
+];
+/** ONNX opset required by the normative v1 target (opset 17). */
+export const ENCODER_OPSET = 17;
+/** Batch must be exactly 1 (single-request inference). */
+export const ENCODER_BATCH = 1;
+/** Maximum accepted token count (WordPiece, deterministic truncation). */
+export const ENCODER_MAX_TOKENS = 512;
+/** Caps the encoder's MARGINAL footprint (bytes) at 150 MiB (MODEL_ASSET
+ *  §qualification). The budget bounds the encoder's own incremental allocation
+ *  (a reusable projection buffer + any externally staged asset working set),
+ *  NOT the whole-process RSS — in a live pi extension the process baseline
+ *  routinely exceeds 150 MiB, so measuring absolute RSS would make mode A
+ *  unreachable in production. This is the "RSS" figure the acceptance metric
+ *  and ENC_FAIL.RSS_BUDGET_EXCEEDED refer to: it is the encoder's marginal
+ *  footprint, never the process RSS (code-review Q01/Q02). */
+export const ENCODER_RSS_BUDGET_BYTES = 150 * 1024 * 1024;
+/** p95 inference budget in milliseconds (MODEL_ASSET §qualification). */
+export const ENCODER_LATENCY_P95_MS = 40;
+/** Semantic projection head width (MODEL_ASSET: 384 float32 L2-normalized). */
+export const ENCODER_SEMANTIC_WIDTH = 384;
+/** Exact VC2A failure codes (returned, never thrown across the boundary). */
+export const ENC_FAIL = {
+    /** opset != 17. */
+    OPSET_INVALID: "ENC_OPSET_INVALID",
+    /** batch != 1. */
+    BATCH_INVALID: "ENC_BATCH_INVALID",
+    /** maxTokens > 512. */
+    TOKENS_EXCEEDED: "ENC_TOKENS_EXCEEDED",
+    /** input token count > declared maxTokens / 512, or not batch 1. */
+    SHAPE_INVALID: "ENC_SHAPE_INVALID",
+    /** asset file unreadable (truncated during digest read, allocator failure). */
+    ASSET_UNREADABLE: "ENC_ASSET_UNREADABLE",
+    /** on-disk digest does not match the manifest (one-byte mutation). */
+    DIGEST_MISMATCH: "ENC_DIGEST_MISMATCH",
+    /** platform not in the supported matrix (selects trigram B). */
+    PLATFORM_UNSUPPORTED: "ENC_PLATFORM_UNSUPPORTED",
+    /** manifest missing/invalid (selects trigram B). */
+    MANIFEST_INVALID: "ENC_MANIFEST_INVALID",
+    /** encoder MARGINAL footprint over the 150 MiB budget (selects trigram B).
+     *  This is the encoder's own incremental allocation (a reusable projection
+     *  buffer + any externally staged asset working set), NOT whole-process RSS
+     *  — see ENCODER_RSS_BUDGET_BYTES. */
+    RSS_BUDGET_EXCEEDED: "ENC_RSS_BUDGET_EXCEEDED",
+    /** mode C forced by the rollback path (MEGACOMPACT_VC2A=0 / forcedMode "C").
+     *  Distinct from MANIFEST_INVALID so a non-corrupt, correctly-shaped asset
+     *  present on disk is not mis-reported as "manifest invalid" when the runtime
+     *  is simply rolled back to the predecessor path (code-review Q04). */
+    ROLLBACK: "ENC_ROLLBACK_ACTIVE",
+};
+/** The 8 registered VC2A conformance IDs (task 1: "register ENC-001..008"). */
+export const ENC_IDS = [
+    "ENC-001",
+    "ENC-002",
+    "ENC-003",
+    "ENC-004",
+    "ENC-005",
+    "ENC-006",
+    "ENC-007",
+    "ENC-008",
+];