@polyengine/runtime 0.1.0-pre.g633468a

package/esm/cache/web.js

@@ -0,0 +1,136 @@
+// Cache API backend for the artifact cache (docs/architecture.md §10), for browsers
+// (and other environments implementing the standard `CacheStorage`/`Cache`
+// interfaces). Feature-detects `globalThis.caches`; throws a named error
+// where unavailable (e.g. plain Deno without `--unstable-*` polyfills, or a
+// non-secure-context page) rather than silently no-op'ing.
+//
+// Layout: one synthetic same-origin-ish URL per cache key, stored as a
+// single JSON `Response` body containing `{meta, plan, adapters}` (adapters
+// base64-encoded — `Cache` stores `Response` bodies, not arbitrary trees,
+// so we can't mirror dirCache's file-per-adapter layout; one blob per entry
+// is the natural shape here).
+import { CACHE_LAYOUT_VERSION, keyHex } from "./core.js";
+import { loadPlan } from "../plan/loader.js";
+/** Thrown when the Cache API isn't available in this environment. */
+export class WebCacheUnavailableError extends Error {
+    constructor() {
+        super("artifact cache: the Cache API (globalThis.caches) is not available " +
+            "in this environment");
+        this.name = "WebCacheUnavailableError";
+    }
+}
+function toBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+function fromBase64(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Synthetic request URL an entry is stored under. Same-origin-relative so
+ * it works under any page origin; the path has no filesystem meaning. */
+function entryUrl(hex) {
+    return `https://artifact-cache.invalid/${hex}`;
+}
+class WebCache {
+    cacheName;
+    constructor(cacheName) {
+        this.cacheName = cacheName;
+    }
+    async open() {
+        if (typeof globalThis.caches === "undefined") {
+            throw new WebCacheUnavailableError();
+        }
+        return await globalThis.caches.open(this.cacheName);
+    }
+    /** 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 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) {
+        // `open()` failing (no `globalThis.caches` in this environment) is a
+        // capability/configuration error, not a per-entry I/O failure — it
+        // propagates uncaught (existing behavior, `WebCacheUnavailableError`)
+        // so a caller who tries to use this backend somewhere it can't work
+        // finds out immediately rather than silently always-missing. Once open
+        // succeeds, every failure below (issue #196: poisoned entry, self-heal
+        // eviction, ...) is swallowed to a `null` miss.
+        const cache = await this.open();
+        try {
+            const hex = await keyHex(key);
+            const resp = await cache.match(entryUrl(hex));
+            if (resp === undefined)
+                return null;
+            const entry = await resp.json();
+            const { meta, plan, adapters: adaptersB64 } = entry;
+            if (meta.layoutVersion !== CACHE_LAYOUT_VERSION) {
+                await this.#tryEvict(key);
+                return null;
+            }
+            if (meta.componentSha256 !== key.componentSha256 ||
+                meta.translatorBuildHash !== key.translatorBuildHash ||
+                JSON.stringify([...meta.features].sort()) !==
+                    JSON.stringify([...key.features].sort()) ||
+                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 [file, b64] of Object.entries(adaptersB64)) {
+                adapters.set(file, fromBase64(b64));
+            }
+            return { plan, adapters };
+        }
+        catch {
+            // Poisoned/corrupted entry, or any other I/O failure (issue #196):
+            // miss + best-effort evict, never trust and never throw out of
+            // `get`.
+            await this.#tryEvict(key);
+            return null;
+        }
+    }
+    async put(key, artifacts) {
+        const cache = await this.open();
+        const hex = await keyHex(key);
+        const meta = {
+            layoutVersion: CACHE_LAYOUT_VERSION,
+            componentSha256: key.componentSha256,
+            translatorBuildHash: key.translatorBuildHash,
+            features: key.features,
+        };
+        const adaptersB64 = {};
+        for (const [file, bytes] of artifacts.adapters) {
+            adaptersB64[file] = toBase64(bytes);
+        }
+        const entry = { meta, plan: artifacts.plan, adapters: adaptersB64 };
+        const body = JSON.stringify(entry);
+        await cache.put(entryUrl(hex), new Response(body, { headers: { "content-type": "application/json" } }));
+    }
+    async evict(key) {
+        const cache = await this.open();
+        const hex = await keyHex(key);
+        await cache.delete(entryUrl(hex));
+    }
+}
+/** A `Cache`-API-backed `ArtifactCache` under the given cache name. Throws
+ * `WebCacheUnavailableError` (at call time, not construction time, so
+ * feature-detection failures surface where they're actually hit) when
+ * `globalThis.caches` doesn't exist. */
+export function webCache(name) {
+    return new WebCache(name);
+}

package/esm/digest/digest.js

@@ -0,0 +1,332 @@
+// Canonical world digest — TypeScript side, computed from a *wire* plan
+// (runtime/src/plan/format.ts's `WirePlan`, i.e. the shim's plan.json
+// schema — contracts/plan-format.md). Counterpart:
+// crates/bindgen/src/digest.rs, computed from `wit_parser::Resolve`. Both
+// must produce byte-identical canonical JSON (and therefore identical
+// sha256) for a structurally-equivalent world — this equality IS the
+// design validation (see runtime/tests/digest_test.ts's cross-language
+// fixture test). This resolves contracts/plan-format.md v0.1 amendment #7
+// ("worldDigest needs redesign before M1 bindgen").
+//
+// THE NORMALIZATION SPEC IS DOCUMENTED ONCE, in crates/bindgen/src/digest.rs's
+// module doc comment (kept in sync with this file) — read it first. Short
+// version: sort import/export lists by name; keep everything else
+// (record fields, variant cases, enum/flags label order, function
+// parameter order) positional because it's ABI-relevant; drop parameter
+// *labels* (not ABI-relevant, this runtime has no named-argument calling
+// convention) and all docs/stability metadata (not present in the plan at
+// all); identify resources by qualified name, not by table index.
+//
+// ## Known limitation (plan side only): resourceTables aliasing
+//
+// The plan's `own`/`borrow` `resource: N` indexes into `resourceTables`,
+// and empirically (the `resources` fixture) an `own`/`borrow` occurrence in
+// an exported function's type and the `{kind:"type"}` export that *names*
+// that same nominal resource can reference two *different* resourceTables
+// indices (one per component-linking instance boundary — the type export
+// sits at the sub-instance that defines the resource, `own`/`borrow` sites
+// reference the root instance's re-export of it). Resolving this in
+// general requires walking wasmtime's resource-alias chain, which the plan
+// format does not expose directly — this is exactly the "impedance between
+// wit-parser's view and the plan's types" flagged for the §9 degraded-mode
+// question in the track report. This implementation takes an honest
+// shortcut: when a world has exactly one nominal resource type, every
+// `own`/`borrow` occurrence (regardless of table index) is identified with
+// that resource — correct for every world in the current fixture corpus
+// (each has 0 or 1 resource types), but a world with 2+ resources throws a
+// clearly-labeled `DigestError` rather than silently guessing.
+// cewd = component-engine world digest, the project's pre-rebrand name; kept as an opaque wire constant.
+export const CEWD_VERSION = 1;
+export class DigestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DigestError";
+    }
+}
+/** Compute the canonical world digest from a loaded wire plan. */
+export async function computeWorldDigest(plan) {
+    const resourceNames = buildResourceNameMap(plan);
+    const imports = plan.imports.map((imp) => canonImport(plan, imp, resourceNames));
+    const exports = plan.exports
+        .map((exp) => canonExportItem(plan, exp, resourceNames))
+        .filter((c) => c !== null);
+    const doc = {
+        cewd: CEWD_VERSION,
+        imports: sortByName(imports),
+        exports: sortByName(exports),
+    };
+    const canonicalJson = canonicalStringify(doc);
+    const digestBytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson));
+    const digest = "sha256:" + hex(digestBytes);
+    return { canonicalJson, digest };
+}
+function hex(buf) {
+    return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+// ---------------------------------------------------------------------------
+// Resource naming (plan resourceTables index -> qualified name)
+// ---------------------------------------------------------------------------
+function buildResourceNameMap(plan) {
+    // CONTRACT: plan-format.md v0.1 amendment #2 / v0.2 proposal
+    // `importedResources` (format.ts:23-33). An imported resource occupies
+    // `ResourceIndex` slots *before* every defined (own/exported) resource
+    // (`ResourceIndex = importedResources.length + DefinedResourceIndex`), and
+    // this implementation has no alias map from those imported-resource
+    // indices to a qualified name (no plan-format extension exists yet for
+    // that — see the module-level "Known limitation" comment). Silently
+    // aliasing an own/borrow reference to an imported resource with the lone
+    // exported resource's name (the pre-fix single-resource-world shortcut
+    // below) would produce a digest that matches a WIT world it is NOT
+    // ABI-compatible with — worse than an unresolved-index throw. Refuse
+    // conservatively whenever the plan declares any imported resources, full
+    // stop, regardless of how many named (exported) resources exist.
+    if (plan.importedResources !== undefined && plan.importedResources.length > 0) {
+        throw new DigestError(`digest: plan declares ${plan.importedResources.length} imported ` +
+            `resource(s); resolving which own/borrow occurrences reference an ` +
+            `imported resource (vs. a defined/exported one) requires an ` +
+            `alias map this plan format does not yet provide (see ` +
+            `runtime/src/digest/digest.ts module docs) — refusing rather than ` +
+            `risk a silently-wrong digest`);
+    }
+    const named = new Map(); // resourceTables index -> name, as directly declared by a type export
+    walkExportsForResourceNames(plan.exports, [], named);
+    if (named.size <= 1) {
+        // Single-resource (or zero-resource) world: identify EVERY resourceTables
+        // index with the one named resource, sidestepping the aliasing gap
+        // documented in the module comment above.
+        const theOne = named.size === 1 ? [...named.values()][0] : undefined;
+        const all = new Map();
+        if (theOne !== undefined) {
+            for (let i = 0; i < plan.resourceTables.length; i++)
+                all.set(i, theOne);
+        }
+        return all;
+    }
+    // Multi-resource world: table-index aliasing across instance boundaries
+    // is not resolved by this implementation. Fail loudly.
+    if (named.size < plan.resourceTables.length) {
+        throw new DigestError(`digest: world has ${named.size} named resource type(s) but ` +
+            `${plan.resourceTables.length} resourceTables entries, and more ` +
+            `than one named resource — resourceTables alias resolution across ` +
+            `component-linking instance boundaries is not implemented (see ` +
+            `runtime/src/digest/digest.ts module docs); cannot safely identify ` +
+            `which own/borrow occurrence means which resource`);
+    }
+    return named;
+}
+function walkExportsForResourceNames(exports, path, out) {
+    for (const exp of exports) {
+        if (exp.kind === "instance") {
+            walkExportsForResourceNames(exp.exports, [...path, exp.name], out);
+        }
+        else if (exp.kind === "type" && exp.type.kind === "resource") {
+            out.set(exp.type.resource, [...path, exp.name].join("/"));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Canonicalization
+// ---------------------------------------------------------------------------
+function canonImport(plan, imp, resourceNames) {
+    // CONTRACT: the plan's `imports` list is flat (`{name, path, kind, type}`)
+    // even for interface-qualified imports (plan-format.md v0.1 amendment #4,
+    // "Untested: current corpus has no imports"); no fixture in this repo's
+    // sync corpus (hello/values/resources) has any imports, so this path is
+    // exercised by no test. Best-effort flattened-name treatment, chosen to
+    // be structurally analogous to the export side's nested naming without
+    // requiring the executor to reconstruct nested WorldItem::Interface shape
+    // from a flat list. Revisit when a corpus component actually imports
+    // something (flagged in the track report for §9's degraded-mode
+    // question).
+    const name = imp.path.length > 0 ? [...imp.path, imp.name].join("/") : imp.name;
+    if (imp.kind === "func" && imp.type !== undefined) {
+        return {
+            kind: "func",
+            name,
+            func: canonFuncType(plan, plan.types[imp.type], resourceNames),
+        };
+    }
+    return { kind: imp.kind, name };
+}
+function canonExportItem(plan, exp, resourceNames) {
+    if (exp.kind === "lifted-func") {
+        return {
+            kind: "func",
+            name: exp.name,
+            func: canonFuncType(plan, plan.types[exp.type], resourceNames),
+        };
+    }
+    if (exp.kind === "instance") {
+        return {
+            kind: "instance",
+            name: exp.name,
+            items: sortByName(exp.exports
+                .map((e) => canonExportItem(plan, e, resourceNames))
+                .filter((c) => c !== null)),
+        };
+    }
+    if (exp.kind === "module") {
+        // digest.md's item rule: only functions and resources contribute as
+        // export items. A module export is not WIT-expressible (bindgen can
+        // never emit a digest containing one) and does not affect
+        // positional-calling ABI shape, so it is excluded — plan-format.md v4
+        // amendment 2.
+        return null;
+    }
+    // exp.kind === "type"
+    if (exp.type.kind === "resource") {
+        return { kind: "resource", name: exp.name };
+    }
+    // Non-resource named types (records/variants/etc. declared at
+    // interface/world scope) do not themselves appear as component exports —
+    // only functions and resources do — so they are intentionally NOT
+    // emitted as a top-level item here; they still affect the digest via
+    // whichever function signatures reference them. Mirrors
+    // crates/bindgen/src/digest.rs's `canon_interface`/`canon_items` (both
+    // skip non-resource `TypeDefKind` entries with the identical rationale).
+    // Caller must filter these out of the containing list (see canonExportItem's
+    // caller / the `null`-sentinel handling below), since this returns a
+    // JSON value, not `undefined`, when called directly.
+    return null;
+}
+function canonFuncType(plan, decl, resourceNames) {
+    if (decl.kind !== "func") {
+        throw new DigestError(`digest: expected a func type declaration, got kind ${decl.kind}`);
+    }
+    return {
+        // Parameter LABELS excluded deliberately (see module docs); only
+        // positional types survive into the digest.
+        params: decl.params.map((p) => canonValType(p.type, resourceNames)),
+        results: decl.results.map((r) => canonValType(r, resourceNames)),
+        async: decl.async,
+    };
+}
+function canonValType(t, resourceNames) {
+    switch (t.kind) {
+        case "bool":
+        case "s8":
+        case "u8":
+        case "s16":
+        case "u16":
+        case "s32":
+        case "u32":
+        case "s64":
+        case "u64":
+        case "f32":
+        case "f64":
+        case "char":
+        case "string":
+        case "error-context":
+            return { kind: t.kind };
+        case "list":
+            return {
+                kind: "list",
+                element: canonValType(t.element, resourceNames),
+                ...(t.length !== undefined ? { length: t.length } : {}),
+            };
+        case "record":
+            return {
+                kind: "record",
+                fields: t.fields.map((f) => ({
+                    label: f.label,
+                    type: canonValType(f.type, resourceNames),
+                })),
+            };
+        case "tuple":
+            return {
+                kind: "tuple",
+                elements: t.elements.map((e) => canonValType(e, resourceNames)),
+            };
+        case "variant":
+            return {
+                kind: "variant",
+                cases: t.cases.map((c) => ({
+                    label: c.label,
+                    type: c.type === null ? null : canonValType(c.type, resourceNames),
+                })),
+            };
+        case "enum":
+            return { kind: "enum", labels: [...t.labels] };
+        case "option":
+            return { kind: "option", type: canonValType(t.type, resourceNames) };
+        case "result":
+            return {
+                kind: "result",
+                ok: t.ok === null ? null : canonValType(t.ok, resourceNames),
+                err: t.err === null ? null : canonValType(t.err, resourceNames),
+            };
+        case "map":
+            // Despecialized to list<tuple<K,V>> — matches crates/bindgen/src/
+            // digest.rs's treatment of wit_parser's `TypeDefKind::Map`. Fixture-
+            // only path (descriptor-ir.md "Open items": not emitted by current
+            // translators), unexercised by the sync corpus.
+            return {
+                kind: "list",
+                element: {
+                    kind: "tuple",
+                    elements: [
+                        canonValType(t.key, resourceNames),
+                        canonValType(t.value, resourceNames),
+                    ],
+                },
+            };
+        case "flags":
+            return { kind: "flags", labels: [...t.labels] };
+        case "own":
+        case "borrow": {
+            const name = resourceNames.get(t.resource);
+            if (name === undefined) {
+                throw new DigestError(`digest: ${t.kind}<T> references resourceTables[${t.resource}], ` +
+                    `which has no resolvable qualified name`);
+            }
+            return { kind: t.kind, resource: name };
+        }
+        case "stream":
+            return {
+                kind: "stream",
+                element: t.element === null ? null : canonValType(t.element, resourceNames),
+            };
+        case "future":
+            return {
+                kind: "future",
+                element: t.element === null ? null : canonValType(t.element, resourceNames),
+            };
+        default: {
+            const exhaustive = t;
+            throw new DigestError(`digest: unknown ValType kind ${exhaustive.kind}`);
+        }
+    }
+}
+function sortByName(items) {
+    // `<`/`>` here is UTF-16 code-unit ordering (no `localeCompare`); the Rust
+    // side (`crates/bindgen/src/digest.rs::sort_by_name`) uses `str::cmp`
+    // (byte-wise/UTF-8). These orderings diverge in general, but WIT
+    // identifiers are ASCII-only (kebab-case `[a-z0-9-]`), where byte-wise and
+    // UTF-16-code-unit ordering coincide — so this is not a latent bug; don't
+    // "fix" one side alone if that assumption changes.
+    return [...items].sort((a, b) => {
+        const an = typeof a?.name === "string" ? a.name : "";
+        const bn = typeof b?.name === "string" ? b.name : "";
+        return an < bn ? -1 : an > bn ? 1 : 0;
+    });
+}
+/**
+ * Recursively sort object keys (alphabetically) and serialize with no extra
+ * whitespace. Array order is preserved verbatim — this must match
+ * `crates/bindgen/src/digest.rs::canonical_string` byte-for-byte.
+ */
+export function canonicalStringify(v) {
+    return JSON.stringify(sortKeysDeep(v));
+}
+// deno-lint-ignore no-explicit-any
+function sortKeysDeep(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeysDeep);
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort())
+            out[k] = sortKeysDeep(v[k]);
+        return out;
+    }
+    return v;
+}

package/esm/digest/mod.js

@@ -0,0 +1,3 @@
+// Runtime digest handshake — public surface (docs/architecture.md §9).
+export * from "./digest.js";
+export * from "./verify.js";

package/esm/digest/verify.js

@@ -0,0 +1,129 @@
+// Runtime handshake (docs/architecture.md §9): verify a loaded plan's world against the
+// digest embedded by generated bindgen code, producing a rich mismatch
+// report that names the first divergent import/export/type path rather
+// than just "digests differ".
+import { computeWorldDigest } from "./digest.js";
+/**
+ * Thrown by generated `instantiate` wrappers when the loaded plan's world
+ * digest does not match the constant bindgen embedded at generation time
+ * (contracts/digest.md: "fails fast with a structural diff on mismatch").
+ * Raised BEFORE the component is instantiated, so no guest code has run
+ * when a caller catches this.
+ *
+ * Named and catchable: `err instanceof WorldDigestMismatchError`, or
+ * `err.name === "WorldDigestMismatchError"` across realms.
+ */
+export class WorldDigestMismatchError extends Error {
+    name = "WorldDigestMismatchError";
+    /** The world these bindings were generated from. */
+    world;
+    /** The full mismatch report (expected/actual digest, first divergence). */
+    mismatch;
+    constructor(world, mismatch) {
+        super(`world digest mismatch for \`${world}\`: bindings expect ` +
+            `${mismatch.expected}, loaded plan computes ${mismatch.actual}` +
+            (mismatch.firstDivergence
+                ? ` (first divergence: ${mismatch.firstDivergence})`
+                : "") +
+            " — regenerate the bindings from the component's WIT");
+        this.world = world;
+        this.mismatch = mismatch;
+    }
+    /** Digest the generated bindings were built against. */
+    get expected() {
+        return this.mismatch.expected;
+    }
+    /** Digest computed from the plan actually loaded. */
+    get actual() {
+        return this.mismatch.actual;
+    }
+}
+/**
+ * Verify `plan`'s computed world digest against `expectedDigest` (the
+ * constant bindgen embedded at generation time). Returns `null` on match,
+ * or a `DigestMismatch` report naming the first divergent path on
+ * mismatch.
+ */
+export async function verifyWorldDigest(plan, expectedDigest) {
+    const actual = await computeWorldDigest(plan);
+    if (actual.digest === expectedDigest)
+        return null;
+    return {
+        expected: expectedDigest,
+        actual: actual.digest,
+        firstDivergence: null, // filled in by compareAgainstExpectedJson if available
+    };
+}
+/**
+ * `diffWorldDigest` — richer variant for tests/tooling: compare against
+ * another plan's (or a WIT-derived) canonical JSON directly, walking both
+ * trees in parallel to name the first divergent import/export/type path.
+ * `expectedCanonicalJson` is normally produced by `crates/bindgen`'s
+ * `digest --json` output, or by `computeWorldDigest` on a reference plan.
+ */
+export async function diffWorldDigest(plan, expectedCanonicalJson) {
+    const actual = await computeWorldDigest(plan);
+    const expected = JSON.parse(expectedCanonicalJson);
+    const expectedDigestBytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(expectedCanonicalJson));
+    const expectedDigest = "sha256:" +
+        Array.from(new Uint8Array(expectedDigestBytes)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    if (actual.digest === expectedDigest)
+        return null;
+    const actualParsed = JSON.parse(actual.canonicalJson);
+    return {
+        expected: expectedDigest,
+        actual: actual.digest,
+        firstDivergence: firstDivergentPath(expected, actualParsed, "$"),
+    };
+}
+/**
+ * Walk two canonical world trees in parallel (both already sorted by name
+ * at every `imports`/`exports`/`items` level — see digest.ts), returning a
+ * human-readable path to the first field that differs, or `null` if the
+ * trees are structurally identical (shouldn't happen if the digests
+ * differ, but the digest is a hash — collisions or caller error are
+ * possible, so this is a defensive `null`, not a promise of "same").
+ */
+function firstDivergentPath(expected, actual, path) {
+    if (Array.isArray(expected) && Array.isArray(actual)) {
+        if (expected.length !== actual.length) {
+            return `${path}: length ${expected.length} (expected) vs ${actual.length} (actual)`;
+        }
+        for (let i = 0; i < expected.length; i++) {
+            const label = itemLabel(expected[i]) ?? `[${i}]`;
+            const d = firstDivergentPath(expected[i], actual[i], `${path}.${label}`);
+            if (d)
+                return d;
+        }
+        return null;
+    }
+    if (expected !== null && actual !== null &&
+        typeof expected === "object" && typeof actual === "object" &&
+        !Array.isArray(expected) && !Array.isArray(actual)) {
+        const e = expected;
+        const a = actual;
+        const keys = new Set([...Object.keys(e), ...Object.keys(a)]);
+        for (const k of [...keys].sort()) {
+            if (!(k in a))
+                return `${path}.${k}: present (expected) but missing (actual)`;
+            if (!(k in e))
+                return `${path}.${k}: missing (expected) but present (actual)`;
+            const d = firstDivergentPath(e[k], a[k], `${path}.${k}`);
+            if (d)
+                return d;
+        }
+        return null;
+    }
+    if (expected !== actual) {
+        return `${path}: ${JSON.stringify(expected)} (expected) vs ${JSON.stringify(actual)} (actual)`;
+    }
+    return null;
+}
+function itemLabel(v) {
+    if (v !== null && typeof v === "object" && "name" in v) {
+        const name = v.name;
+        if (typeof name === "string")
+            return JSON.stringify(name);
+    }
+    return undefined;
+}

package/esm/embedder/casing.js

@@ -0,0 +1,56 @@
+// WIT label -> JS identifier casing, and the mangled export/import leaf
+// grammar that carries resource membership.
+//
+// Governing contract: contracts/embedder-api.md §"Naming and casing".
+// Casing applies to *identifiers* only — function/method/static names, record
+// fields, flag names, resource class names. It NEVER applies to data: enum
+// values, variant/result case tags and interface ids stay kebab-case verbatim.
+/**
+ * `get-resolution` -> `getResolution`.
+ *
+ * The rule, stated exactly: split the label on `-`; the first fragment is
+ * unchanged; every later fragment has its first character upper-cased and its
+ * remainder preserved. Preserving the remainder is what keeps acronym
+ * fragments intact — `outgoing-HTTP-request` -> `outgoingHTTPRequest` — which
+ * a naive `toLowerCase()` of the tail would destroy.
+ *
+ * WIT labels are already lower-kebab in practice, so the first fragment needs
+ * no adjustment; nothing here lower-cases anything.
+ */
+export function camelCase(label) {
+    const parts = label.split("-");
+    return parts[0] + parts.slice(1).map(upperFirst).join("");
+}
+/** `tcp-socket` -> `TcpSocket` (resource class names). */
+export function pascalCase(label) {
+    return label.split("-").map(upperFirst).join("");
+}
+function upperFirst(s) {
+    return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}
+const MANGLED = /^\[([a-z-]+)\](.*)$/;
+/** Decode a mangled leaf name; unmangled names come back as `plain`. */
+export function parseLeafName(raw) {
+    const m = MANGLED.exec(raw);
+    if (m === null)
+        return { form: "plain", name: raw };
+    const [, tag, rest] = m;
+    switch (tag) {
+        case "constructor":
+            return { form: "constructor", resource: rest };
+        case "method":
+        case "static": {
+            const dot = rest.indexOf(".");
+            if (dot < 0)
+                break;
+            return {
+                form: tag,
+                resource: rest.slice(0, dot),
+                member: rest.slice(dot + 1),
+            };
+        }
+    }
+    // Unknown bracket forms (`[async]`, `[dtor]`, future spellings) are left
+    // alone rather than guessed at: they surface verbatim, which is loud.
+    return { form: "plain", name: raw };
+}