@polyengine/runtime 0.1.0-pre.g633468a

package/esm/cabi/types.js

@@ -0,0 +1,264 @@
+// Canonical ABI — provisional component value-type model.
+//
+// This is the v1 sketch of the "CABI descriptor IR" of docs/architecture.md §8: the type
+// information the host-boundary lift/lower interpreter walks. It mirrors the
+// type classes of the executable spec
+// (third_party/component-model/design/mvp/canonical-abi/definitions.py) as a
+// TypeScript discriminated union, holding only what lift/lower needs.
+//
+// PROVISIONAL — expected to change when the translator shim (docs/architecture.md §4.2)
+// defines the real plan format. Open questions, tracked in runtime/README.md:
+//   - Serialized encoding (this in-memory shape vs the plan's wire format).
+//   - Whether labels stay strings or become interned indices in the IR.
+//   - Host-facing value representations for tuple/variant/option/result
+//     (currently the despecialized definitions.py shapes; bindgen §9 will
+//     want arrays / tagged unions / undefined-based options).
+//   - Resource types: here an opaque token; the plan will carry resource-type
+//     indices + dtor references instead.
+export function coreFuncTypeEquals(a, b) {
+    return a.params.length === b.params.length &&
+        a.results.length === b.results.length &&
+        a.params.every((p, i) => p === b.params[i]) &&
+        a.results.every((r, i) => r === b.results[i]);
+}
+/**
+ * definitions.py `ResourceType`: identity + implementing instance + optional
+ * destructor. Compared by object identity everywhere.
+ *
+ * `dtorHost` is the **host-initiated**-drop entry (#85, reshaped by #160):
+ * the dtor built as a fully LIFTED sync function — definitions.py
+ * `canon_resource_drop` (line 2319) `inst.store.lift(dtor, ft, opts,
+ * rt.impl)` — so the destructor's activation gets a real Task/Thread, the
+ * reentrance bracket is released at its first park, and its suspension
+ * points are resumable by the scheduler. It is wired by exec/executor.ts
+ * (jspi-`promising` entry only when the dtor is suspension-capable, docs §7)
+ * and called through `hostDtorCall` (exec/boundary.ts), which also fills it
+ * in lazily for tokens built directly. It returns `undefined` or a Promise,
+ * so it is NOT callable from inside a guest activation.
+ *
+ * Guest-initiated drops (`callDtorGated`) always use `dtor` directly: they
+ * must complete synchronously (reference lifts the dtor with
+ * `async_ = False`), and any thenable there is a trap.
+ */
+export class ResourceTypeInfo {
+    impl;
+    dtor;
+    dtorHost;
+    constructor(impl, dtor = null, dtorHost = null) {
+        this.impl = impl;
+        this.dtor = dtor;
+        this.dtorHost = dtorHost;
+    }
+}
+export function despecialize(t) {
+    switch (t.kind) {
+        case "tuple":
+            return {
+                kind: "record",
+                fields: t.elements.map((e, i) => ({ label: String(i), type: e })),
+            };
+        case "enum":
+            return {
+                kind: "variant",
+                cases: t.labels.map((l) => ({ label: l, type: null })),
+            };
+        case "option":
+            return {
+                kind: "variant",
+                cases: [{ label: "none", type: null }, { label: "some", type: t.type }],
+            };
+        case "result":
+            return {
+                kind: "variant",
+                cases: [{ label: "ok", type: t.ok }, { label: "error", type: t.error }],
+            };
+        case "map":
+            return {
+                kind: "list",
+                element: despecialize({
+                    kind: "tuple",
+                    elements: [t.key, t.value],
+                }),
+            };
+        default:
+            return t;
+    }
+}
+// ---------------------------------------------------------------------------
+// Discriminants (definitions.py `discriminant_type`)
+// ---------------------------------------------------------------------------
+export function discriminantType(cases) {
+    const n = cases.length;
+    if (!(0 < n && n < 2 ** 32))
+        throw new Error("assertion failed: case count");
+    // mirrors math.ceil(log2(n)/8): 0|1 -> u8, 2 -> u16, 3 -> u32
+    if (n <= 256)
+        return { kind: "u8" };
+    if (n <= 65536)
+        return { kind: "u16" };
+    return { kind: "u32" };
+}
+// ---------------------------------------------------------------------------
+// Type predicates (definitions.py `contains_borrow` etc.)
+// ---------------------------------------------------------------------------
+export function containsBorrow(t) {
+    return contains(t, (u) => u.kind === "borrow");
+}
+export function containsAsyncValue(t) {
+    return contains(t, (u) => u.kind === "stream" || u.kind === "future");
+}
+export function contains(t, p) {
+    if (t === null)
+        return false;
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "list":
+            return p(d) || contains(d.element, p);
+        case "stream":
+        case "future":
+            return p(d) || contains(d.element, p);
+        case "record":
+            return p(d) || d.fields.some((f) => contains(f.type, p));
+        case "variant":
+            return p(d) || d.cases.some((c) => contains(c.type, p));
+        default:
+            return p(d);
+    }
+}
+// ---------------------------------------------------------------------------
+// Structural ValType equality and display
+// ---------------------------------------------------------------------------
+/**
+ * Structural `ValType` equality.
+ *
+ * CONTRACT (bugfix, TRACK C2-D; generalized during the #18 tls smoke): naive
+ * `JSON.stringify(a) === JSON.stringify(b)` recurses into `own`/`borrow`'s
+ * `ResourceTypeInfo` — a class whose `impl` field is documented "Compared by
+ * object identity everywhere" (see `ResourceTypeInfo` above) and which cycles
+ * back to the owning instance state (`impl.handles` holds live resource
+ * tables that reference their types), so `JSON.stringify` throws
+ * `TypeError: Converting circular structure to JSON` on ANY type containing
+ * `own<R>`/`borrow<R>` at any depth. First hit by `task.return` result types
+ * (C2-D, polymorph-test's `list<own<test-case>>`), then by stream/future
+ * element types (polymorph-tls streams carrying resource-bearing payloads).
+ * Object-identity types (`ResourceTypeInfo`) are compared by reference, per
+ * the documented invariant.
+ */
+export function valTypesEqual(a, b) {
+    return a.length === b.length && a.every((t, i) => valTypeEqual(t, b[i]));
+}
+export function valTypeEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a.kind !== b.kind)
+        return false;
+    switch (a.kind) {
+        case "list": {
+            const bb = b;
+            return a.length === bb.length && valTypeEqual(a.element, bb.element);
+        }
+        case "record": {
+            const bb = b;
+            return a.fields.length === bb.fields.length &&
+                a.fields.every((f, i) => f.label === bb.fields[i].label && valTypeEqual(f.type, bb.fields[i].type));
+        }
+        case "tuple": {
+            const bb = b;
+            return a.elements.length === bb.elements.length &&
+                a.elements.every((e, i) => valTypeEqual(e, bb.elements[i]));
+        }
+        case "variant": {
+            const bb = b;
+            return a.cases.length === bb.cases.length &&
+                a.cases.every((c, i) => {
+                    const other = bb.cases[i];
+                    if (c.label !== other.label)
+                        return false;
+                    if (c.type === null || other.type === null)
+                        return c.type === other.type;
+                    return valTypeEqual(c.type, other.type);
+                });
+        }
+        case "enum":
+        case "flags": {
+            const bb = b;
+            return a.labels.length === bb.labels.length &&
+                a.labels.every((l, i) => l === bb.labels[i]);
+        }
+        case "option": {
+            const bb = b;
+            return valTypeEqual(a.type, bb.type);
+        }
+        case "result": {
+            const bb = b;
+            if ((a.ok === null) !== (bb.ok === null))
+                return false;
+            if ((a.error === null) !== (bb.error === null))
+                return false;
+            return (a.ok === null || valTypeEqual(a.ok, bb.ok)) &&
+                (a.error === null || valTypeEqual(a.error, bb.error));
+        }
+        case "map": {
+            const bb = b;
+            return valTypeEqual(a.key, bb.key) && valTypeEqual(a.value, bb.value);
+        }
+        case "own":
+        case "borrow": {
+            const bb = b;
+            // Object-identity type (documented invariant): reference equality only.
+            return a.rt === bb.rt;
+        }
+        case "stream":
+        case "future": {
+            const bb = b;
+            if ((a.element === null) !== (bb.element === null))
+                return false;
+            return a.element === null || valTypeEqual(a.element, bb.element);
+        }
+        case "error-context":
+            return true;
+        default:
+            // Remaining kinds (primitives) carry no extra fields beyond `kind`.
+            return true;
+    }
+}
+/**
+ * Cycle-safe display form for diagnostics. `JSON.stringify(t)` is UNSAFE on
+ * any resource-bearing type (see `valTypeEqual`'s contract note); this prints
+ * the structural shape and elides `ResourceTypeInfo` identities.
+ */
+export function fmtValType(t) {
+    if (t === null)
+        return "_";
+    switch (t.kind) {
+        case "list":
+            return t.length === undefined
+                ? `list<${fmtValType(t.element)}>`
+                : `list<${fmtValType(t.element)}, ${t.length}>`;
+        case "record":
+            return `record{${t.fields.map((f) => `${f.label}: ${fmtValType(f.type)}`).join(", ")}}`;
+        case "tuple":
+            return `tuple<${t.elements.map(fmtValType).join(", ")}>`;
+        case "variant":
+            return `variant{${t.cases.map((c) => c.type === null ? c.label : `${c.label}(${fmtValType(c.type)})`)
+                .join(", ")}}`;
+        case "enum":
+            return `enum{${t.labels.join(", ")}}`;
+        case "flags":
+            return `flags{${t.labels.join(", ")}}`;
+        case "option":
+            return `option<${fmtValType(t.type)}>`;
+        case "result":
+            return `result<${fmtValType(t.ok)}, ${fmtValType(t.error)}>`;
+        case "map":
+            return `map<${fmtValType(t.key)}, ${fmtValType(t.value)}>`;
+        case "own":
+        case "borrow":
+            return `${t.kind}<resource>`;
+        case "stream":
+        case "future":
+            return `${t.kind}<${fmtValType(t.element)}>`;
+        default:
+            return t.kind;
+    }
+}

package/esm/cabi/values.js

@@ -0,0 +1,64 @@
+// Lifting and lowering of full value lists with spilling (definitions.py
+// `## Lifting and Lowering Values`): parameter/result sequences that exceed
+// the flat maximum are passed indirectly through a tuple in linear memory.
+import { trapIf } from "./trap.js";
+import { alignment, alignTo, elemSize } from "./layout.js";
+import { load } from "./load.js";
+import { store } from "./store.js";
+import { liftFlat } from "./lift.js";
+import { lowerFlat } from "./lower.js";
+import { flattenTypes } from "./flatten.js";
+import { requireMemory } from "./context.js";
+import { asIndex } from "./memory.js";
+export function liftFlatValues(cx, maxFlat, vi, ts) {
+    const flatTypes = flattenTypes(ts, cx.opts);
+    if (flatTypes.length > maxFlat) {
+        const mem = requireMemory(cx.opts);
+        const ptrRaw = vi.next(mem.ptrType());
+        const tupleType = { kind: "tuple", elements: ts };
+        const align = alignment(tupleType, mem.ptrType());
+        const size = elemSize(tupleType, mem.ptrType());
+        trapIf(BigInt(ptrRaw) % BigInt(align) !== 0n, "misaligned spill pointer");
+        trapIf(BigInt(ptrRaw) + BigInt(size) > BigInt(mem.length), "spill tuple out of bounds");
+        const ptr = asIndex(ptrRaw);
+        const tuple = load(cx, ptr, tupleType);
+        return Object.values(tuple);
+    }
+    else {
+        return ts.map((t) => liftFlat(cx, vi, t));
+    }
+}
+export function lowerFlatValues(cx, maxFlat, vs, ts, outParam = null) {
+    const flatTypes = flattenTypes(ts, cx.opts);
+    if (flatTypes.length > maxFlat) {
+        const mem = requireMemory(cx.opts);
+        const tupleType = { kind: "tuple", elements: ts };
+        const tupleValue = {};
+        vs.forEach((v, i) => {
+            tupleValue[String(i)] = v;
+        });
+        let ptr;
+        let flatVals;
+        const align = alignment(tupleType, mem.ptrType());
+        const size = elemSize(tupleType, mem.ptrType());
+        if (outParam === null) {
+            ptr = cx.allocate(align, size);
+            flatVals = mem.ptrType() === "i32" ? [ptr] : [BigInt(ptr)];
+        }
+        else {
+            ptr = asIndex(outParam.next(mem.ptrType()));
+            flatVals = [];
+        }
+        trapIf(ptr !== alignTo(ptr, align), "misaligned spill pointer");
+        trapIf(ptr + size > mem.length, "spill tuple out of bounds");
+        store(cx, tupleValue, tupleType, ptr);
+        return flatVals;
+    }
+    else {
+        const flatVals = [];
+        for (let i = 0; i < vs.length; i++) {
+            flatVals.push(...lowerFlat(cx, vs[i], ts[i]));
+        }
+        return flatVals;
+    }
+}

package/esm/cache/core.js

@@ -0,0 +1,156 @@
+// Artifact cache — platform-neutral core (docs/architecture.md §10, layer 1: ours, bytes
+// only; nothing here depends on the engine's own compiled-module cache,
+// i.e. layer 2).
+//
+// GOAL: content-address a shim translation by
+// `(component sha256, translator build hash, feature flags)` so a reload
+// (same component, same shim build, same features) can skip the
+// translate-with-the-shim step entirely.
+//
+// CACHE FAILURES ARE NEVER FATAL (issue #196): the cache is a pure
+// optimization layered over `Translator.translateRaw` + `loadEnvelope`, both
+// of which already succeed/fail on their own terms. A `get`/`put`/internal
+// self-heal failure — including a read-only or otherwise unwritable cache
+// root — must never turn into a failed translation; at worst it turns into
+// a fresh (uncached) translation. `translateCached` swallows `get`/`put`
+// failures (surfaced only via the opt-in `onCacheError` callback below);
+// the backends (dir.ts, web.ts) swallow their internal self-heal evictions
+// and turn any `get`-path I/O failure into a `null` (miss) rather than a
+// throw. The one exception, by design, is `TranslateError` from
+// `loadEnvelope`: that is a verdict about the *input component*, not a
+// cache failure, and keeps propagating uncached. The public `evict()` also
+// keeps throwing — an explicit caller asked for that specific effect and
+// deserves to know if it didn't happen.
+//
+// PERSISTED-ARTIFACT-SET DECISION (governing: contracts/plan-format.md
+// "Artifact set" + "No duplicate bytes" — plan-format.md:24-31,63-64):
+// we persist `plan.json` (the wire `WirePlan`) and the FACT adapter modules
+// only. We do NOT persist the original component bytes.
+//
+// Evidence this is correct, not merely convenient:
+//   - plan-format.md is explicit: "The original component binary is the
+//     third input at instantiation time; the plan never embeds it" and
+//     "Embedded core modules are referenced as `[offset, len)` byte ranges
+//     into the original component binary — the executor slices them
+//     itself" (decision 3). `instantiateComponent`/`Facade.instantiate`
+//     (runtime/src/embedder/instantiate.ts `ComponentArtifacts`) take
+//     `componentBytes` as a caller-supplied field *alongside* `plan` and
+//     `adapters` — never as something the plan or its loader manufacture.
+//   - Operationally: whoever calls `translateCached` already holds the
+//     component bytes (that's how they'd have a sha256 to form a cache key
+//     in the first place, and how `verifyComponent`'s length check runs
+//     without a bytes store at all). Reload use cases (browser page reload,
+//     Deno process restart) re-fetch/re-read the *component* from its own
+//     source of truth (network, disk) every time; only the *translation*
+//     (the expensive shim call) is worth skipping. Storing componentBytes a
+//     second time would be pure duplication with no consumer.
+//   - `get()` therefore verifies integrity using only the requested
+//     `CacheKey.componentSha256` against the value that was true at `put()`
+//     time (recorded in the stored metadata and cross-checked against the
+//     embedded `plan.component.sha256`) — never against fresh bytes, which
+//     this layer never sees.
+import { loadEnvelope, PlanError, TranslateError } from "../plan/loader.js";
+/** Cache layout version. Bumped on any incompatible on-disk/on-Cache-API
+ * schema change; an unrecognized version is read back as a miss (never a
+ * crash) so stale caches from an older build self-heal by re-translating —
+ * and this self-healing holds even when the cache root itself is
+ * unwritable (issue #196): the eviction attempt that a layout mismatch
+ * triggers is swallowed internally by the backend, so a read-only
+ * pre-warmed cache from an older layout degrades to "always miss, always
+ * re-translate" rather than throwing. */
+export const CACHE_LAYOUT_VERSION = 1;
+async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes.slice().buffer);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * The stable cache key string: sha256 over a canonical JSON encoding of the
+ * `CacheKey` (features sorted so order never causes a spurious miss).
+ */
+export async function keyHex(key) {
+    const canonical = JSON.stringify({
+        componentSha256: key.componentSha256,
+        translatorBuildHash: key.translatorBuildHash,
+        features: [...key.features].sort(),
+    });
+    return await sha256Hex(new TextEncoder().encode(canonical));
+}
+/** Compute the `CacheKey` for a `(translator, componentBytes)` pair. Throws
+ * if the translator has no `buildHash` (constructed from a pre-compiled
+ * `WebAssembly.Module` with no bytes available — see `Translator.create`). */
+export async function keyFor(translator, componentBytes, features = []) {
+    if (translator.buildHash === null) {
+        throw new PlanError("artifact cache: translator has no buildHash (constructed from a " +
+            "WebAssembly.Module without source bytes); pass raw wasm bytes to " +
+            "Translator.create to enable caching");
+    }
+    return {
+        componentSha256: await sha256Hex(componentBytes),
+        translatorBuildHash: translator.buildHash,
+        features,
+    };
+}
+function reportCacheError(opts, op, err) {
+    try {
+        opts.onCacheError?.(op, err);
+    }
+    catch {
+        // A diagnostic callback throwing must not fail the translation either
+        // (issue #196): the caller asked for a diagnostic, not a veto.
+    }
+}
+/**
+ * Orchestration helper: cache hit -> stored artifacts, cache miss ->
+ * translate with the shim, store, return.
+ */
+export async function translateCached(translator, componentBytes, cache, opts = {}) {
+    const key = await keyFor(translator, componentBytes, opts.features ?? []);
+    // A `get` failure (issue #196) reads as a miss: the cache is a pure
+    // optimization, so any way it fails to answer degrades to "translate
+    // fresh" rather than failing the whole translation.
+    let hit;
+    try {
+        hit = await cache.get(key);
+    }
+    catch (e) {
+        reportCacheError(opts, "get", e);
+        hit = null;
+    }
+    if (hit !== null) {
+        return { plan: hit.plan, adapters: hit.adapters, fromCache: true };
+    }
+    const first = translator.translateRaw(componentBytes);
+    if (opts.verifyDeterminism) {
+        const second = translator.translateRaw(componentBytes);
+        if (first !== second) {
+            throw new Error("artifact cache: determinism guard failed — translating the same " +
+                "component bytes twice produced different envelopes");
+        }
+    }
+    // loadEnvelope both validates (throws TranslateError for a validation
+    // verdict — must propagate uncached, per TranslateError's docs: a
+    // validation verdict is a judgment about the *input component*, not
+    // something to cache-and-replay) and gives us the split plan/adapters.
+    let wire;
+    let adapters;
+    try {
+        ({ wire, adapters } = loadEnvelope(first));
+    }
+    catch (e) {
+        if (e instanceof TranslateError)
+            throw e;
+        throw e;
+    }
+    // A `put` failure (issue #196) is swallowed: the translation already
+    // succeeded and was already validated above by `loadEnvelope` — failing
+    // to *store* it says nothing about the result. Return the fresh
+    // artifacts anyway.
+    try {
+        await cache.put(key, { plan: wire, adapters });
+    }
+    catch (e) {
+        reportCacheError(opts, "put", e);
+    }
+    return { plan: wire, adapters, fromCache: false };
+}

package/esm/cache/dir.js

@@ -0,0 +1,170 @@
+// Deno filesystem backend for the artifact cache (docs/architecture.md §10).
+//
+// Layout, under `<path>/<keyhex>/`:
+//   meta.json         CacheMeta (layoutVersion, componentSha256,
+//                      translatorBuildHash, features)
+//   plan.json          the wire WirePlan, JSON-serialized
+//   adapters/<name>    one file per adapter, name = the tail of the wire
+//                       plan's `modules[].file` (which is already
+//                       `adapters/<idx>.wasm` shaped upstream — see
+//                       contracts/plan-format.md "Artifact set" — so this
+//                       backend nests one more `adapters/` level under the
+//                       key directory: `<path>/<keyhex>/adapters/<idx>.wasm`)
+//
+// Deliberately does NOT store component bytes — see core.ts's
+// "PERSISTED-ARTIFACT-SET DECISION" docs for why that's sound, not a gap.
+import { CACHE_LAYOUT_VERSION, keyHex } from "./core.js";
+import { loadPlan, PlanError } from "../plan/loader.js";
+/** Reject any adapter file name that isn't a plain, non-traversing
+ * relative path — defense in depth even though the shim is trusted (a
+ * poisoned/tampered cache directory must not escape it). */
+function safeRelName(name) {
+    if (name.length === 0 ||
+        name.startsWith("/") ||
+        name.split("/").some((seg) => seg === "" || seg === "." || seg === "..")) {
+        throw new PlanError(`artifact cache: unsafe adapter file name '${name}'`);
+    }
+    return name;
+}
+async function exists(path) {
+    try {
+        await Deno.stat(path);
+        return true;
+    }
+    catch (e) {
+        if (e instanceof Deno.errors.NotFound)
+            return false;
+        throw e;
+    }
+}
+async function rmIfExists(path) {
+    try {
+        await Deno.remove(path, { recursive: true });
+    }
+    catch (e) {
+        if (!(e instanceof Deno.errors.NotFound))
+            throw e;
+    }
+}
+class DirCache {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async entryDir(key) {
+        return `${this.root}/${await keyHex(key)}`;
+    }
+    /** Internal self-heal eviction (issue #196): the caller is `get`'s own
+     * recovery path for a poisoned/stale entry, not an explicit caller of
+     * `evict()` — so a failure here (e.g. an unwritable cache root) must not
+     * escape and fail what would otherwise be a clean miss. The public
+     * `evict()` below keeps throwing; only this internal path swallows. */
+    async #tryEvict(key) {
+        try {
+            await this.evict(key);
+        }
+        catch {
+            // Swallowed: see docs above.
+        }
+    }
+    async get(key) {
+        try {
+            const dir = await this.entryDir(key);
+            if (!(await exists(dir)))
+                return null;
+            const metaRaw = await Deno.readTextFile(`${dir}/meta.json`);
+            const meta = JSON.parse(metaRaw);
+            if (meta.layoutVersion !== CACHE_LAYOUT_VERSION) {
+                await this.#tryEvict(key);
+                return null;
+            }
+            // Integrity: the entry must agree with the *requested* key on every
+            // field, not just live at the expected directory name (belt-and-
+            // suspenders against a hand-edited or corrupted cache).
+            if (meta.componentSha256 !== key.componentSha256 ||
+                meta.translatorBuildHash !== key.translatorBuildHash ||
+                JSON.stringify([...meta.features].sort()) !==
+                    JSON.stringify([...key.features].sort())) {
+                await this.#tryEvict(key);
+                return null;
+            }
+            const planRaw = await Deno.readTextFile(`${dir}/plan.json`);
+            const plan = JSON.parse(planRaw);
+            if (plan.component.sha256 !== key.componentSha256) {
+                await this.#tryEvict(key);
+                return null;
+            }
+            loadPlan(plan); // structural validation; throws on a corrupted plan
+            const adapters = new Map();
+            for (const m of plan.modules) {
+                if (m.kind !== "adapter")
+                    continue;
+                const name = safeRelName(m.file);
+                adapters.set(m.file, await Deno.readFile(`${dir}/adapters/${name}`));
+            }
+            return { plan, adapters };
+        }
+        catch {
+            // Any parse/read/structural/I-O failure = a poisoned entry (or an
+            // unreadable/unwritable cache root, issue #196): miss + best-effort
+            // evict, never trust and never throw out of `get` (dispatch
+            // requirement). This also covers `exists()`'s rethrow of non-
+            // `NotFound` stat errors (ENOTDIR, EACCES, ...).
+            await this.#tryEvict(key);
+            return null;
+        }
+    }
+    async put(key, artifacts) {
+        const dir = await this.entryDir(key);
+        // Write to a temp sibling then rename, so a crash mid-write never
+        // leaves a partially-written entry that `get` would (try to) read.
+        const tmp = `${dir}.tmp-${crypto.randomUUID()}`;
+        await rmIfExists(tmp);
+        try {
+            await Deno.mkdir(`${tmp}/adapters`, { recursive: true });
+            const meta = {
+                layoutVersion: CACHE_LAYOUT_VERSION,
+                componentSha256: key.componentSha256,
+                translatorBuildHash: key.translatorBuildHash,
+                features: key.features,
+            };
+            await Deno.writeTextFile(`${tmp}/meta.json`, JSON.stringify(meta));
+            await Deno.writeTextFile(`${tmp}/plan.json`, JSON.stringify(artifacts.plan));
+            for (const [file, bytes] of artifacts.adapters) {
+                const name = safeRelName(file);
+                await Deno.writeFile(`${tmp}/adapters/${name}`, bytes);
+            }
+            await rmIfExists(dir);
+            await Deno.rename(tmp, dir);
+        }
+        catch (e) {
+            // A `put` failure is non-fatal at the `translateCached` layer
+            // (issue #196), but repeated failures must not litter the cache
+            // root with orphaned `.tmp-<uuid>` scratch directories. Cleanup
+            // failures here are themselves swallowed — `put` still throws its
+            // original error either way.
+            try {
+                await rmIfExists(tmp);
+            }
+            catch {
+                // Swallowed: best-effort cleanup only.
+            }
+            throw e;
+        }
+    }
+    async evict(key) {
+        await rmIfExists(await this.entryDir(key));
+    }
+}
+/** A filesystem-backed `ArtifactCache` rooted at `path` (created on first
+ * `put` if missing). Deno only: every method calls `Deno.*` directly. On other
+ * platforms use `webCache()` (./web.ts), or supply your own `ArtifactCache` —
+ * the interface is three methods (./core.ts). */
+export function dirCache(path) {
+    if (typeof Deno === "undefined") {
+        throw new Error("dirCache() is the Deno filesystem backend and this is not Deno — " +
+            "use webCache() (Cache API), or implement ArtifactCache over your " +
+            "platform's storage (see @polyengine/runtime/cache core.ts)");
+    }
+    return new DirCache(path);
+}

package/esm/cache/mod.js

@@ -0,0 +1,4 @@
+// Artifact cache — public surface (docs/architecture.md §10).
+export * from "./core.js";
+export * from "./dir.js";
+export * from "./web.js";