Path B partial: per-resource handle table routing complete; outer-boundary handle leak remains

[avrabe]

Tracked under #106 (Epic ADR-0).

Background

Three wit-bindgen runtime fixtures fail with wasm unreachable after meld fusion: resource_floats, resource_with_lists, resource-import-and-export. Root cause: rustc/LLVM assume(ptr.is_aligned()) debug-assert fires when leaf code dereferences the rep as a Box<T> pointer when the rep is actually a small handle integer.

Convergent diagnosis from prototype paths D + E:

• meld-core/src/merger.rs:739 redirected ALL [resource-*] imports of any re-exporter through one shared ht_* regardless of which resource the import was for
• meld-core/src/adapter/fact.rs:582 did the same per-component lookup for borrow handling

Path B (commits e027bb1 + c104b1b)

Rekeyed HandleTableInfo from HashMap<usize, _> to HashMap<(usize, String, String), _>. Per-resource discrimination throughout: redirect logic uses [export] prefix + resource_graph.resource_definer to determine the owner of each [resource-*] import; consumer-side imports (without [export] prefix) fall back to ANY component's handle table for the matching (iface, resource_name); \$N dedup suffix is stripped before lookup.

Status:

• ✅ 73-test wit-bindgen suite: 0 regressions
• ✅ Resource handle routing is now correctly per-resource
• ✅ Original & 7 align trap eliminated (leaf no longer derefs handle as Box)
• ❌ The trio still traps at runtime, but with a different error: unknown handle index 0x110004

Remaining bug

The trap value 0x110004 = table_base_addr + ENTRY_SIZE — the first entry in meld's per-resource handle table memory. wasmtime's canonical-ABI rejects it as an unknown handle.

Hypothesis: in the wit-bindgen-rust pattern, intermediate's exports.float resource is built around a Box<Float { inner_handle: leaf_imports_handle }>. Path B routes intermediate's [resource-new] to ht_new(box_ptr) which returns 0x110004. But when intermediate's Float.add() returns a NEW Float, the cabi-export shim chains through both layers — the outer ht_new and the inner canonical resource.new for leaf — and somewhere a memory-address handle ends up where wasmtime expects a canonical handle.

This is structurally similar to the opaque-rep drop bug from path I (https://github.com/pulseengine/wit-bindgen/tree/feat/opaque-rep-attribute): when wit-bindgen-rust uses Box::new(InnerHandle { ... }) as the rep, the outer handle and inner handle live at different layers, and the canonical-ABI machinery only knows about one.

Reproducer

```bash
git checkout feat/issue-92-shim-module
cargo run --release --bin meld -- fuse tests/wit_bindgen/fixtures/resource_floats.wasm -o /tmp/floats.wasm --component
wasm-tools validate /tmp/floats.wasm # passes
wasmtime --invoke='run()' /tmp/floats.wasm

Error: unknown handle index 1114116 (= 0x110004)

```

Two paths forward

1. Wrap the boundary — insert a memory-address ↔ canonical-handle translation shim in `component_wrap.rs` so the fused module's per-resource handle table values get unwrapped to canonical handles at every cross-boundary point. Estimated: 100-200 LOC, deeper investigation needed to find every leak.
2. Pivot to opaque-rep upstream — extend pulseengine/wit-bindgen feat/opaque-rep-attribute to support methods (constructor-only works today). Once upstream, re-exporter components opt out of the boxed-rep pattern and meld's per-resource routing covers the rest. Estimated: ~50-100 LOC in wit-bindgen `bindgen.rs` + new fixture.

Related

• Commits: e027bb1, c104b1b
• Branch: feat/issue-92-shim-module
• wit-bindgen fork: pulseengine/wit-bindgen feat/opaque-rep-attribute (commit 236ef4bb)

[avrabe]

Update — deeper investigation (commits c104b1b, 254bfab + wit-bindgen fork cb1fa100)

Two more refinement rounds explored the bug; the trap shape is unchanged but the diagnosis is sharper.

What was tried

Wrapper-side per-resource fallback (c104b1b, 254bfab) — the wrapper's ImportResolution::LocalResource now carries an is_definer flag distinguishing [export]-prefixed imports (component owns the resource) from plain imports (consumer). The fallback routes through another component's handle table only for consumers, never definers. Mirroring this in merger.rs:739 prevents a re-exporter from incorrectly routing its own import-side [resource-*] helpers through its own ht (which would write to memory address small_int).

Method-bearing opaque-rep fixture (wit-bindgen cb1fa100) — extended the opaque-rep generator to support methods (Option A from RFC). The new resource_floats_opaque fixture exercises constructor + get + drop end-to-end. Passes in the wit-bindgen test driver standalone, but fails through meld with a different error:

panicked at .../leaf-rust/bindings/leaf.rs:119:44:
misaligned pointer dereference: address must be a multiple of 0x8 but is 0x2

Leaf is dereferencing 0x2 as a Box pointer — meaning leaf's [resource-rep]float returned 0x2, meaning [resource-new] was called with 0x2 as the rep (likely because intermediate's user code returned inner.take_handle() = 2 via opaque-rep, and somewhere meld passed that small int to leaf's canonical [resource-new] instead of routing through proper paths).

Sharper diagnosis

The fundamental issue is layer-mixing at the wrapper boundary, not the redirect logic:

• meld's per-resource handle tables manage handles INSIDE the fused module
• wasmtime's canonical resource tables manage handles at the OUTER component boundary
• When a memory-address handle from ht_new (e.g. 0x110004) escapes to canon resource.drop, wasmtime can't find it in its table → unknown handle index 0x110004
• When a small canonical handle (e.g. 2) gets stored in wasmtime's table as a rep (because meld routed [resource-new] differently), later [resource-rep] returns 2 and the user-code deref traps

The two layers need TRANSLATION, not just routing. Path B's per-resource discrimination ensures the right HANDLER is called, but the right handler still uses the wrong VALUE space for the boundary it's crossing.

Two architectural directions for resolving this

1. Translation shim at every wrapper boundary — when the fused module's exports return an own handle, the wrapper inserts a function that calls ht_rep (memory address → rep) then canonical resource.new (rep → wasmtime handle). When the wrapper's imports receive a wasmtime handle from outside, the inverse. ~150-300 LOC, deep wasmtime canonical-ABI knowledge.
2. Eliminate the parallel handle table entirely — store reps in wasmtime's canonical resource tables directly, even for re-exporter components. Requires intercepting wit-bindgen's [resource-rep] to get back the original value (a small handle integer for re-exporters) without the Box dereferencing assertion. This is essentially what path I (opaque-rep wit-bindgen fork) achieves on the wit-bindgen side.

Direction 2 is what the wit-bindgen fork is doing. Combined with path B's per-resource correctness, opaque-rep components SHOULD work — but the new resource_floats_opaque test still fails through meld because of the same kind of layer-mixing (the OPAQUE rep 0x2 ends up in wasmtime's canonical table where it shouldn't).

State of branches

• meld@feat/issue-92-shim-module — 3 commits: e027bb1, c104b1b, 254bfab. Path B + two refinement rounds. 73/73 suite, 0 regressions. Trio still traps.
• pulseengine/wit-bindgen@feat/opaque-rep-attribute — 5 commits: c7550718, 560d69c7, 236ef4bb, fd6bd8bb, cb1fa100. Generator opt-in + RFC + method support. Passes fork's test driver standalone.

Stopping deep investigation here. Direction 1 (translation shim) is the next concrete attack vector but requires more upfront design work than fits in a single session.

[avrabe]

Update — root architectural finding

Tried disabling handle tables (`MELD_NO_HANDLE_TABLES=1`) on the opaque-rep fixture: trap unchanged. So handle tables aren't the culprit either. Pivoted to inspecting wasmtime's resource type sharing.

The actual root cause: `component_wrap.rs:1176` keys `local_resource_types` by resource_name alone — meaning all "float" resources across all components collapse to a SINGLE wasmtime resource type, sharing one resource table. Comment at the declaration explicitly states this design.

This is correct for standard wit-bindgen (Box-pattern re-exporters need the shared table so box-pointer reps round-trip). But it's catastrophic for opaque-rep (intermediate stores leaf's handle integer `1` as its rep — fine in its own table, fatal when leaf later reads handle `1` from the SHARED table and gets back `0x1` instead of a real Box pointer → `misaligned pointer dereference: address must be a multiple of 0x8 but is 0x2`).

Same root cause produces both observed traps in this issue:

• `unknown handle index 0x110004` — memory-address handle from `ht_new` ends up in the shared table where wasmtime can't find it
• `misaligned pointer dereference` — small-integer rep from opaque-rep retrieved by leaf as a "Box pointer" through the shared table

Spike: rekeying `local_resource_types` by `(component_idx, resource_name)` to give each component its own type:

• ❌ 9 of 73 tests regress (all standard resource fixtures — they DEPEND on the shared type for re-exporter Box-pattern reps)
• ✓ Architecturally cleaner for opaque-rep

Standard wit-bindgen and opaque-rep have opposing architectural requirements. Cannot satisfy both with one global keying choice. The right shape is conditional:

• Per-resource opt-in flag (CLI-level, user knows their components)
• OR runtime detection (e.g., absence of the `& 7; br_if 0; unreachable` Box-deref pattern indicates opaque-rep)

Either lets meld treat opaque-rep resources as "give each component its own type" while keeping standard resources as "share types across components".

Reverted the spike to keep `feat/issue-92-shim-module` clean (73/73). Tracking this as the actual next-step direction for resolving the trio.

cc the wit-bindgen fork's RFC for context: `pulseengine/wit-bindgen@feat/opaque-rep-attribute` discusses Option A (raw u32 borrow) — that pattern is what surfaces this incompatibility.

[avrabe]

🎉 Major progress — resource_floats runtime PASSES

Commit 73f95e6 on feat/conditional-resource-typing fixes the resource_floats trio fixture's runtime trap.

What was wrong

Multiple layers of routing had to align:

1. Definer-side imports ([export]X.[resource-*]float in leaf): when leaf's use test.{float} re-exports test.float as exports.float (via intermediate), wasmtime unifies them at canon-type level. Path B previously refused to redirect definers, leaving leaf's [resource-rep]float going to canon resource.rep — which had never seen the memory-pointer handles minted by intermediate's ht_new. Fix: alias-fallback in merger.rs:864 + component_wrap.rs:1306 (commit 0035441).

2. Consumer-side LocalResource imports: same alias-fallback symmetry needed for non-[export] consumer imports. Fix: mirrored consumer branch (commit 73f95e6).

3. Self-owns check: my initial broad check blocked the redirect when the importing component owned ANY ht ending in the same resource name. This wrongly blocked intermediate's import-side test.float from routing to its own exports.float ht (the unified type). Fix: check by SPECIFIC (component, iface, resource) tuple instead of any-iface (commit 73f95e6).

Status

Trio fixture	Before	After 73f95e6
resource_floats	unknown handle index 0x110004	✅ PASSES
resource_with_lists	Option::unwrap on None	wasm unreachable (likely same class, different shape)
resource-import-and-export	Option::unwrap on None	wasm unreachable (likely same class)

73/73 standard wit-bindgen suite still passes — 0 regressions. The other two trio failures are likely the same routing class manifesting differently; investigation continuing.

Branch

feat/conditional-resource-typing now has 4 commits on top of feat/issue-92-shim-module:

• e166cb4 — --opaque-rep CLI infrastructure
• 0035441 — definer-side alias-fallback
• 73f95e6 — consumer-side alias-fallback + specific self-owns check

[avrabe]

Phase 5 update — dtor wiring landed (9eb1229); 1/3 trio passes, 2/3 still trap differently

Summary

Trio fixture	Original trap	After 73f95e6 (alias-fallback)	After 9eb1229 (+ dtor wiring)
resource_floats	wasm unreachable (& 7 align)	✅ PASSES	✅ PASSES
resource_with_lists	wasm unreachable (& 7 align)	wasm unreachable	wasm unreachable
resource-import-and-export	wasm unreachable (& 7 align)	wasm unreachable	wasm unreachable

73/73 standard suite still passes (0 regressions). The 8 two-component fixtures from the matrix continue to pass as before.

Diagnosis of remaining failures

Both remaining fixtures panic with Option::unwrap() on None at wit-bindgen-generated Thing::get<T>::ptr.as_ref().unwrap() (line 296 of generated bindings). The Option in question is the val field of _ResourceRep<T>, set to Some(T) by _resource_new and only set to None by _resource_dtor (which the dtor wiring at 9eb1229 now invokes properly).

The trace agent's hypothesis: cross-component handle namespace conflation. resource_with_lists has world resource-with-lists { import test; export test; } — a SINGLE test interface used both ways. Three components share ONE canonical resource type for test:resource-with-lists/test/thing. After meld's per-resource-name handle table unification:

• Leaf calls _resource_new(leaf_box) → ht_new returns handle_L (slot stores leaf_box)
• Intermediate calls _resource_new(int_box) → ht_new returns handle_I (different slot, stores int_box)
• When intermediate.foo(handle_I) runs: _resource_rep(handle_I) → returns int_box ✓ (correct slot)
• BUT if intermediate's user code invokes leaf.method(handle_L'), where handle_L' was created by intermediate via the IMPORT side of the same shared interface, it goes through the SAME shared ht. The handles are still distinct, but now leaf's user code may be invoked with what intermediate considers its own handle...

The resource_floats fixture works because it uses THREE distinct interface names (test, imports, exports) — though they all unify at canon-type level via use, the fact that the source interface names differ keeps wit-bindgen's import-vs-export wrappers separate at the rust type level.

Architectural options remaining

1. Per-component handle tables (Option A from the trace report): each (component, resource) gets its own ht; cross-component handle hand-offs translate through bridging shims. ~200-400 LOC; restores the canonical-ABI's per-component namespace.

2. Emit canonical resource types in the wrapper (Option C): define wasmtime resource types at the wrapper level for each (component, resource), use canon resource.* for cross-component value flow, ht_* only for internal storage. Largest change but most faithful to the un-fused semantics.

The cheap wins are exhausted; both options require deeper architectural work. Stopping iteration here for design review.

Branch state

feat/conditional-resource-typing now has 5 commits on top of feat/issue-92-shim-module:

• e166cb4 — --opaque-rep CLI infrastructure
• 0035441 — definer-side alias-fallback
• 73f95e6 — consumer-side alias-fallback + specific self-owns check
• 9eb1229 — ht_drop invokes [dtor] before zeroing

[avrabe]

Mythos slop-hunt + Option A iteration update

Slop-hunt findings (rank → 3 discover stages)

The PR diff was scored 1-5 for risk. Three score-5 findings, all converging on the same heuristic — name-only alias matching:

1. Alias-fallback over-fire (load-bearing-with-known-false-positive-class) — equal-types.wasm has blag.input-stream and wasi-io/streams.input-stream sharing a name. The fallback matches by resource_name only, would route the WASI drop through blag's ht. Not currently triggered (no runtime test), but constructible. Proposed fix: resolver-built explicit (definer_iface, rn) → ht_key map populated from use-alias detection.

2. dtor contains substring match (buggy-but-untested → FIXED in commit 2a1ecad) — name.contains("#[dtor]float") matched 3 dtors in resource_floats; find_map short-circuited on the first. The origin-comp filter didn't disambiguate when one component owned the same resource in multiple ifaces. Tightened to exact <iface>#[dtor]<rn> match. 73/73 + resource_floats still pass.

3. fact.rs key-shape regressions (incomplete — agent stalled on cargo build during excision experiment).

Option A — Phase 1 landed, Phase 2 reverted, Phase 3 deferred

New branch feat/per-component-ht-bridging with one commit 0632ec2:

• Phase 1: broaden reexporter_resources to also include the resource's DEFINER component. resource_with_lists now allocates 2 handle tables (was 1): one for the leaf definer, one for the intermediate re-exporter.
• Phase 2 (reverted): removing the alias-fallback for [export]-prefixed (definer) imports regresses resource_floats. Phase 2 needs Phase 3 (bridging trampolines) to land first.
• Phase 3 (not started): insert bridging trampolines (source_ht_rep → target_ht_new) at adapter sites in fact.rs where own/borrow handles cross component boundaries. Sized 100-200 LOC; principled but needs careful design.

Status: 73/73 standard suite passes on Phase 1. Trio status unchanged: 1/3 runtime passes (resource_floats), 2/3 still trap.

Two paths now visible

• Refine alias-fallback with explicit alias-group map (Discover Testcase proposal #1's recommendation, ~30-50 LOC). Cleanly addresses the slop-hunt false-positive AND likely makes resource_with_lists / resource-import-and-export pass without bridging trampolines. Lower risk, smaller diff.
• Continue Option A Phase 3 (~200 LOC fact.rs bridging). Architecturally cleaner, eliminates the need for fallback entirely, but needs more design work and validation.

I'd lean toward the alias-fallback refinement next: it's smaller, addresses the rank-discovered false-positive, and may unblock the rest of the trio without committing to the larger Phase 3 surgery.

Branches

• feat/conditional-resource-typing head 2a1ecad — current PR feat: per-resource handle tables + alias-fallback (1/3 trio runtime passes) #108 (draft); 8 commits including dtor exact-match
• feat/per-component-ht-bridging head 0632ec2 — new branch with Phase 1; not yet PR'd