@polyengine/runtime 0.5.0 → 0.6.0

package/esm/cabi/store.js

@@ -3,17 +3,22 @@ import { assert_, trapIf } from "./trap.js";
 import { bytesOf, storeInt, storePtr } from "./memory.js";
 import { tryStoreNumericList } from "./bulk_lists.js";
 import { encodeFloatAsI32, encodeFloatAsI64 } from "./float.js";
-import { alignment, alignTo, elemSize, elemSizeFlags, maxCaseAlignment, } from "./layout.js";
+import { alignTo, elemSizeFlags, layoutOf } from "./layout.js";
 import { charToI32, REALLOC_I32_MAX, REALLOC_MISALIGNED, REALLOC_OOB, storeString, } from "./strings.js";
 import { requireMemory } from "./context.js";
 import { lowerBorrow, lowerOwn } from "./handles.js";
-import { despecialize, discriminantType, } from "./types.js";
+import { caseIndexOf, } from "./types.js";
 import { lowerErrorContext, lowerFuture, lowerStream, } from "./async_values.js";
 export function store(cx, v, t, ptr) {
     const mem = requireMemory(cx.opts);
-    assert_(ptr === alignTo(ptr, alignment(t, mem.ptrType())), "store misaligned");
-    assert_(ptr + elemSize(t, mem.ptrType()) <= mem.length, "store OOB");
-    const d = despecialize(t);
+    // The load-side mirror: one cached layout node carrying the despecialized
+    // type as well (issue #261), and `ptr % align === 0` in place of
+    // `ptr === alignTo(ptr, align)` — identical for power-of-two alignments,
+    // minus the float divide.
+    const L = layoutOf(t, mem.ptrType());
+    assert_(ptr % L.align === 0, "store misaligned");
+    assert_(ptr + L.size <= mem.length, "store OOB");
+    const d = L.d;
     switch (d.kind) {
         case "bool":
             storeInt(mem, Number(Boolean(v)), ptr, 1);
@@ -61,10 +66,12 @@ export function store(cx, v, t, ptr) {
             storeList(cx, v, ptr, d.element, d.length ?? null);
             return;
         case "record":
-            storeRecord(cx, v, ptr, d.fields);
+            storeRecord(cx, v, ptr, d.fields, L.fieldOffsets);
             return;
         case "variant":
-            storeVariant(cx, v, ptr, d.cases);
+            storeVariant(cx, v, ptr, d.cases, 
+            // 0 only on the kinds without a discriminant; see loadVariant's note.
+            L.discSize, L.payloadOffset);
             return;
         case "flags":
             storeFlags(cx, v, ptr, d.labels);
@@ -96,9 +103,9 @@ export function storeList(cx, v, ptr, elemType, maybeLength) {
 }
 export function storeListIntoRange(cx, v, elemType) {
     const mem = requireMemory(cx.opts);
-    const byteLength = v.length * elemSize(elemType, mem.ptrType());
+    const { size, align } = layoutOf(elemType, mem.ptrType());
+    const byteLength = v.length * size;
     assert_(byteLength <= REALLOC_I32_MAX);
-    const align = alignment(elemType, mem.ptrType());
     const ptr = cx.allocate(align, byteLength);
     trapIf(ptr !== alignTo(ptr, align), REALLOC_MISALIGNED);
     trapIf(ptr + byteLength > mem.length, REALLOC_OOB);
@@ -107,7 +114,8 @@ export function storeListIntoRange(cx, v, elemType) {
 }
 export function storeListIntoValidRange(cx, v, ptr, elemType) {
     const mem = requireMemory(cx.opts);
-    const kind = despecialize(elemType).kind;
+    const L = layoutOf(elemType, mem.ptrType());
+    const kind = L.d.kind;
     // docs/architecture.md §7: list<u8> is Uint8Array-shaped on the host, and
     // both directions are bulk copies — this is the store-side mirror of
     // load.ts `loadListFromValidRange`'s u8 fast path (issue #54: the
@@ -135,18 +143,17 @@ export function storeListIntoValidRange(cx, v, ptr, elemType) {
     // platforms.
     if (tryStoreNumericList(mem, v, ptr, kind))
         return;
-    const size = elemSize(elemType, mem.ptrType());
+    const size = L.size;
     for (let i = 0; i < v.length; i++) {
         store(cx, v[i], elemType, ptr + i * size);
     }
 }
-export function storeRecord(cx, v, ptr, fields) {
-    const mem = requireMemory(cx.opts);
-    let p = ptr;
-    for (const f of fields) {
-        p = alignTo(p, alignment(f.type, mem.ptrType()));
-        store(cx, v[f.label], f.type, p);
-        p += elemSize(f.type, mem.ptrType());
+/** The store-side mirror of `loadRecord`: indexed offset writes, no per-field
+ * layout recomputation (issue #261). */
+export function storeRecord(cx, v, ptr, fields, offsets) {
+    for (let i = 0; i < fields.length; i++) {
+        const f = fields[i];
+        store(cx, v[f.label], f.type, ptr + offsets[i]);
     }
 }
 /** definitions.py match_case: the value is a single-key object. */
@@ -154,20 +161,20 @@ export function matchCase(v, cases) {
     const keys = Object.keys(v);
     assert_(keys.length === 1, "variant value must have exactly one case");
     const label = keys[0];
-    const matches = cases.flatMap((c, i) => (c.label === label ? [i] : []));
-    assert_(matches.length === 1, `variant case '${label}' not found`);
-    return [matches[0], v[label]];
+    // `caseIndexOf` is the memoized form of the linear scan this used to run on
+    // every variant stored (issue #261); it maps a duplicated label to -1, so
+    // the "exactly one match" condition below is unchanged.
+    const i = caseIndexOf(cases).get(label);
+    assert_(i !== undefined && i >= 0, `variant case '${label}' not found`);
+    return [i, v[label]];
 }
-export function storeVariant(cx, v, ptr, cases) {
+export function storeVariant(cx, v, ptr, cases, discSize, payloadOffset) {
     const mem = requireMemory(cx.opts);
     const [caseIndex, caseValue] = matchCase(v, cases);
-    const discSize = elemSize(discriminantType(cases), mem.ptrType());
     storeInt(mem, caseIndex, ptr, discSize);
-    let p = ptr + discSize;
-    p = alignTo(p, maxCaseAlignment(cases, mem.ptrType()));
     const c = cases[caseIndex];
     if (c.type !== null) {
-        store(cx, caseValue, c.type, p);
+        store(cx, caseValue, c.type, ptr + payloadOffset);
     }
 }
 export function storeFlags(cx, v, ptr, labels) {

package/esm/cabi/trap.js

@@ -1,7 +1,7 @@
 // Trap and assertion machinery (definitions.py `Trap`, `trap`, `trap_if`).
 //
-// `Trap`'s canonical definition lives in `@polyengine/protocol` since amendment
-// A9 (it is an embedder-contract value and must be recognizable across
+// `Trap`'s canonical definition lives in `@polyengine/protocol`
+// (contracts/embedder-api.md §"Module identity": it is an embedder-contract value and must be recognizable across
 // runtime copies, issue #83); it is re-exported here so every existing
 // `from "../cabi/trap.ts"` import path is unchanged. The protocol package is
 // dependency-free, so this import introduces no cycle.

package/esm/cabi/types.js

@@ -50,36 +50,90 @@ export class ResourceTypeInfo {
         this.dtorHost = dtorHost;
     }
 }
+/**
+ * Despecialization memo, keyed on input identity.
+ *
+ * `ValType` objects are built once per plan by plan/loader.ts `loadValType`
+ * and never mutated, so their identity is stable for the plan's lifetime —
+ * the same justification embedder/values.ts `checkedLabels` relies on. Issue
+ * #261: `despecialize` sits at the top of `load`, `store`, `alignment`,
+ * `elemSize`, `lowerFlat` and `contains`, and allocated a fresh record or
+ * variant on every one of those calls, per element and per field.
+ *
+ * The memo hands every caller the SAME object where each previously got a
+ * fresh one, so it is sound only as long as no caller mutates the result.
+ * That invariant is enforced in HALF the cases and merely relied upon in the
+ * other half, and the difference is worth knowing:
+ *
+ *   - The five specialized kinds return an object built here, and everything
+ *     built here is frozen. These modules are strict-mode, so a later
+ *     mutation throws instead of silently corrupting every other holder.
+ *   - The default branch returns the plan-owned `t` unchanged — which for a
+ *     plan-declared record/variant/list is MOST types in practice — and
+ *     freezing plan types is out of scope. Nothing enforces immutability
+ *     there; it rests on plan/loader.ts `loadValType`, which builds every
+ *     node bottom-up and never writes to one afterwards.
+ *
+ * Violating that second half is now worse than it used to be. Mutating a plan
+ * record's `fields` was previously self-correcting, because every `load`/
+ * `store` recomputed the layout from the current array; with layout.ts's
+ * cache the mutation instead desynchronizes a `Layout` whose `fieldOffsets`
+ * were computed from the pre-mutation shape — wrong bytes at wrong offsets,
+ * no error anywhere. A `ValType` reachable from a plan is immutable; treat
+ * that as a hard invariant of this layer, not a convention.
+ */
+const despecializedCache = new WeakMap();
 export function despecialize(t) {
+    const hit = despecializedCache.get(t);
+    if (hit !== undefined)
+        return hit;
+    const d = despecializeUncached(t);
+    // Cached only after the computation returns: a throwing path must leave no
+    // entry behind, or the failure would be reported exactly once.
+    despecializedCache.set(t, d);
+    return d;
+}
+/**
+ * definitions.py `despecialize` (line 1163), line for line. Only the objects
+ * built HERE are frozen; the default branch returns the plan-owned `t`
+ * unchanged, and freezing plan types is out of scope.
+ */
+function despecializeUncached(t) {
     switch (t.kind) {
         case "tuple":
-            return {
+            return Object.freeze({
                 kind: "record",
-                fields: t.elements.map((e, i) => ({ label: String(i), type: e })),
-            };
+                fields: Object.freeze(t.elements.map((e, i) => Object.freeze({ label: String(i), type: e }))),
+            });
         case "enum":
-            return {
+            return Object.freeze({
                 kind: "variant",
-                cases: t.labels.map((l) => ({ label: l, type: null })),
-            };
+                cases: Object.freeze(t.labels.map((l) => Object.freeze({ label: l, type: null }))),
+            });
         case "option":
-            return {
+            return Object.freeze({
                 kind: "variant",
-                cases: [{ label: "none", type: null }, { label: "some", type: t.type }],
-            };
+                cases: Object.freeze([
+                    Object.freeze({ label: "none", type: null }),
+                    Object.freeze({ label: "some", type: t.type }),
+                ]),
+            });
         case "result":
-            return {
+            return Object.freeze({
                 kind: "variant",
-                cases: [{ label: "ok", type: t.ok }, { label: "error", type: t.error }],
-            };
+                cases: Object.freeze([
+                    Object.freeze({ label: "ok", type: t.ok }),
+                    Object.freeze({ label: "error", type: t.error }),
+                ]),
+            });
         case "map":
-            return {
+            return Object.freeze({
                 kind: "list",
                 element: despecialize({
                     kind: "tuple",
                     elements: [t.key, t.value],
                 }),
-            };
+            });
         default:
             return t;
     }
@@ -87,16 +141,78 @@ export function despecialize(t) {
 // ---------------------------------------------------------------------------
 // Discriminants (definitions.py `discriminant_type`)
 // ---------------------------------------------------------------------------
-export function discriminantType(cases) {
-    const n = cases.length;
+/**
+ * The discriminant WIDTH — the single mirror of definitions.py
+ * `discriminant_type`'s arithmetic (line 1234), including its `assert(0 < n <
+ * (1 << 32))`. `math.ceil(log2(n)/8)`: 0|1 -> u8, 2 -> u16, 3 -> u32.
+ *
+ * The width is what the layout code actually wanted: on every variant lifted
+ * or lowered it used to build a `PrimType` purely to hand it to
+ * `alignment`/`elemSize` (issue #261). u8/u16/u32 each have alignment equal to
+ * their size, so this one number is both the discriminant's size and its
+ * alignment — which is why the variant layout kernels need nothing else.
+ */
+export function discriminantSize(caseCount) {
+    const n = caseCount;
     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" };
+        return 1;
     if (n <= 65536)
-        return { kind: "u16" };
-    return { kind: "u32" };
+        return 2;
+    return 4;
+}
+/**
+ * Module-level singletons rather than fresh literals per call: `flatten.ts`
+ * calls `discriminantType` once per variant flattened and passes the result
+ * to `flattenType`, which despecializes it — a fresh object there is one
+ * `despecializedCache` insert on immediate garbage every time (the same
+ * defeat-the-identity-cache pattern `values.ts` `spillTupleType` avoids).
+ * Frozen for the reason the despecialized nodes are: they are now shared, and
+ * the engine is a better guarantor of "nobody mutates this" than an audit.
+ */
+const U8 = Object.freeze({ kind: "u8" });
+const U16 = Object.freeze({ kind: "u16" });
+const U32 = Object.freeze({ kind: "u32" });
+/**
+ * definitions.py `discriminant_type`. The table itself lives in
+ * `discriminantSize`; this is only the width -> type mapping, so the bound
+ * check, the thresholds and the error string exist once. Flattening
+ * (flatten.ts:157) and layout (layout.ts `alignmentVariant`,
+ * `elemSizeVariant`) therefore cannot drift apart on the discriminant width.
+ */
+export function discriminantType(cases) {
+    switch (discriminantSize(cases.length)) {
+        case 1:
+            return U8;
+        case 2:
+            return U16;
+        case 4:
+            return U32;
+    }
+}
+/**
+ * Label -> case index for a variant's `cases`, memoized on the array's
+ * identity (plan-owned and stable, same argument as the despecialization
+ * memo). Replaces the linear scan `matchCase` ran on every variant stored
+ * (issue #261).
+ *
+ * A label bound to more than one case maps to -1, because the scan this
+ * replaces asserted on finding exactly ONE match: collapsing duplicates to
+ * "last wins" would silently accept a variant the old code rejected.
+ */
+const caseIndexCache = new WeakMap();
+export function caseIndexOf(cases) {
+    const hit = caseIndexCache.get(cases);
+    if (hit !== undefined)
+        return hit;
+    const m = new Map();
+    for (let i = 0; i < cases.length; i++) {
+        const label = cases[i].label;
+        m.set(label, m.has(label) ? -1 : i);
+    }
+    caseIndexCache.set(cases, m);
+    return m;
 }
 // ---------------------------------------------------------------------------
 // Type predicates (definitions.py `contains_borrow` etc.)
@@ -104,9 +220,6 @@ export function discriminantType(cases) {
 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;
@@ -131,7 +244,7 @@ export function contains(t, p) {
 /**
  * Structural `ValType` equality.
  *
- * CONTRACT (bugfix, TRACK C2-D; generalized during the #18 tls smoke): naive
+ * CONTRACT (bugfix, 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
@@ -139,7 +252,7 @@ export function contains(t, p) {
  * 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
+ * (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.

package/esm/cabi/values.js

@@ -7,15 +7,34 @@ 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 { flatCount } from "./flatten.js";
 import { requireMemory } from "./context.js";
 import { asIndex } from "./memory.js";
+/**
+ * The spill tuple for a parameter/result list, memoized on the array's
+ * identity.
+ *
+ * Both spill paths used to synthesize `{ kind: "tuple", elements: ts }` on
+ * every call, which under the identity-keyed layout/despecialization caches
+ * (issue #261) is a guaranteed miss plus a wasted insert — it would make this
+ * path slower, not faster. `ts` is always a plan-owned `ft.params`/
+ * `ft.results` array (exec/boundary.ts, intrinsics/async_builtins.ts), so its
+ * identity is as stable as a `ValType`'s.
+ */
+const spillTuples = new WeakMap();
+function spillTupleType(ts) {
+    const hit = spillTuples.get(ts);
+    if (hit !== undefined)
+        return hit;
+    const t = { kind: "tuple", elements: ts };
+    spillTuples.set(ts, t);
+    return t;
+}
 export function liftFlatValues(cx, maxFlat, vi, ts) {
-    const flatTypes = flattenTypes(ts, cx.opts);
-    if (flatTypes.length > maxFlat) {
+    if (flatCount(ts, cx.opts) > maxFlat) {
         const mem = requireMemory(cx.opts);
         const ptrRaw = vi.next(mem.ptrType());
-        const tupleType = { kind: "tuple", elements: ts };
+        const tupleType = spillTupleType(ts);
         const align = alignment(tupleType, mem.ptrType());
         const size = elemSize(tupleType, mem.ptrType());
         trapIf(BigInt(ptrRaw) % BigInt(align) !== 0n, "misaligned spill pointer");
@@ -29,10 +48,9 @@ export function liftFlatValues(cx, maxFlat, vi, ts) {
     }
 }
 export function lowerFlatValues(cx, maxFlat, vs, ts, outParam = null) {
-    const flatTypes = flattenTypes(ts, cx.opts);
-    if (flatTypes.length > maxFlat) {
+    if (flatCount(ts, cx.opts) > maxFlat) {
         const mem = requireMemory(cx.opts);
-        const tupleType = { kind: "tuple", elements: ts };
+        const tupleType = spillTupleType(ts);
         const tupleValue = {};
         vs.forEach((v, i) => {
             tupleValue[String(i)] = v;

package/esm/cache/core.js

@@ -49,7 +49,7 @@
 //     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";
+import { loadEnvelope, PlanError } 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 —
@@ -135,16 +135,7 @@ export async function translateCached(translator, componentBytes, cache, opts =
     // 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;
-    }
+    const { wire, adapters } = loadEnvelope(first);
     // 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

package/esm/digest/digest.js

@@ -5,8 +5,9 @@
 // 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").
+// fixture test). The wire plan's own `worldDigest` field is legacy
+// (contracts/plan-format.md), retained for wire compatibility only; this
+// module computes the normative digest independently.
 //
 // 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
@@ -72,8 +73,8 @@ function hex(buf) {
 // 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
+    // CONTRACT: the `importedResources` field (contracts/plan-format.md
+    // schema; 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
@@ -134,8 +135,9 @@ function walkExportsForResourceNames(exports, path, out) {
 // ---------------------------------------------------------------------------
 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
+    // even for interface-qualified imports (`imports[].path`,
+    // contracts/plan-format.md schema — "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
@@ -174,8 +176,8 @@ function canonExportItem(plan, exp, resourceNames) {
         // 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.
+        // positional-calling ABI shape, so it is excluded — the `module` export
+        // kind (contracts/plan-format.md schema notes).
         return null;
     }
     // exp.kind === "type"

package/esm/digest/mod.js

@@ -6,7 +6,7 @@
  * **This is not embedder API.** The entry point exists as a support surface
  * for bindgen-generated bindings — whose typed `instantiate` wrapper
  * verifies the digest before instantiating (contracts/embedder-api.md
- * amendment A17) — and for the runtime's own internals. No host program
+ * §"Module wiring and instantiation") — and for the runtime's own internals. No host program
  * should hand-write an import of this module.
  *
  * **Its contents are completely unstable: there is no compatibility promise

package/esm/digest/verify.js

@@ -1,12 +1,11 @@
-// 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".
+// Runtime handshake (docs/architecture.md §9): verify a loaded plan's world
+// against the digest embedded by generated bindgen code, failing fast with
+// the expected/actual digests on mismatch (contracts/digest.md).
 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").
+ * (contracts/digest.md: "fails fast on mismatch").
  * Raised BEFORE the component is instantiated, so no guest code has run
  * when a caller catches this.
  *
@@ -18,14 +17,11 @@ export class WorldDigestMismatchError extends Error {
     name = "WorldDigestMismatchError";
     /** The world these bindings were generated from. */
     world;
-    /** The full mismatch report (expected/actual digest, first divergence). */
+    /** The full mismatch report (expected/actual digest). */
     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;
@@ -42,8 +38,7 @@ export class WorldDigestMismatchError extends Error {
 /**
  * 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.
+ * or a `DigestMismatch` report on mismatch.
  * @internal
  */
 export async function verifyWorldDigest(plan, expectedDigest) {
@@ -53,80 +48,5 @@ export async function verifyWorldDigest(plan, expectedDigest) {
     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.
- * @internal
- */
-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;
-}