@polyengine/runtime 0.1.0-pre.g633468a

package/esm/intrinsics/mod.js

@@ -0,0 +1,564 @@
+// Host trampolines (contracts/intrinsics.md §B) and FACT-adapter intrinsic
+// obligations (§A) — the M0 subset, with instantiate-time (never call-time)
+// milestone-aware failures for everything else.
+//
+// Implemented in M0:
+//   lower-import        host function call through descriptor-IR lift/lower
+//   trap                FACT `Trap` import -> ComponentTrap
+//   enter/exit-sync-call  degenerate sync-call bookkeeping (assert-and-count)
+//   resource-new/rep/drop  sync resource paths over cabi handle tables
+//                          (M1 schedule, implemented early: the resources
+//                          fixture references them at instantiation)
+//
+// Everything else fails at instantiate time with the milestone at which
+// intrinsics.md §B schedules it — "this component needs the M2 task core"
+// is a feature, not a crash.
+import { canonResourceDrop, canonResourceNew, canonResourceRep, trap, } from "../cabi/mod.js";
+import { ResourceHandle } from "../cabi/handles.js";
+import { trapIf } from "../cabi/trap.js";
+import { assert_ } from "../cabi/trap.js";
+import { maybeCurrentThread, PendingCapability, withPoisonCause } from "../task/mod.js";
+import { UnsupportedFeatureError } from "./errors.js";
+import { createBackpressureDec, createBackpressureInc, createSubtaskCancel, createSubtaskDrop, createTaskCancel, createTaskReturn, createThreadYield, createWaitableJoin, createWaitableSetDrop, createWaitableSetNew, createWaitableSetPoll, createWaitableSetWait, } from "./async_builtins.js";
+import { createAsyncStartCall, createPrepareCall, createSyncStartCall, } from "./fact_calls.js";
+import { createErrorContextDebugMessage, createErrorContextDrop, createErrorContextNew, createFutureCancelRead, createFutureCancelWrite, createFutureDropReadable, createFutureDropWritable, createFutureNew, createFutureRead, createFutureWrite, createStreamCancelRead, createStreamCancelWrite, createStreamDropReadable, createStreamDropWritable, createStreamNew, createStreamRead, createStreamWrite, createStreamTransfer, createFutureTransfer, createErrorContextTransfer, } from "./stream_builtins.js";
+import { createTranscoder, TRANSCODE_OPS, } from "./transcode.js";
+export * from "./transcode.js";
+export * from "./context.js";
+export * from "./async_builtins.js";
+export * from "./fact_calls.js";
+export * from "./stream_builtins.js";
+/**
+ * Trap-code → message, from wasmtime-environ 47.0.3 `trap_encoding.rs`
+ * (`generate_trap_type!`), whose ordinals are what FACT passes to the
+ * `runtime.trap` import. Only the codes a sync FACT adapter can raise are
+ * listed; anything else falls back to the numeric code.
+ *
+ * Rendered with wasmtime's `"wasm trap: "` prefix (its `impl Display for
+ * Trap`), because that is the text the official suite's `assert_trap`
+ * commands expect for adapter-raised traps
+ * (e.g. `values/realloc.wast:67,94`).
+ */
+const FACT_TRAP_MESSAGES = {
+    9: "wasm `unreachable` instruction executed",
+    17: "cannot enter component instance",
+    23: "cannot leave component instance",
+    24: "cannot block a synchronous task before returning",
+    25: "invalid `char` bit pattern",
+    30: "string content out-of-bounds",
+    31: "list content out-of-bounds",
+    32: "invalid variant discriminant",
+    33: "unaligned pointer",
+    46: "reference count overflow",
+    49: "uncaught exception propagated out of component",
+};
+/** Ordinal of `Trap::UncaughtException` in wasmtime's trap encoding. */
+const TRAP_UNCAUGHT_EXCEPTION = 49;
+export { UnsupportedFeatureError } from "./errors.js";
+/** Milestone at which each trampoline kind stops instantiate-failing. */
+const TRAMPOLINE_MILESTONE = {
+    "lower-import": "M0",
+    "trap": "M0",
+    "enter-sync-call": "M0",
+    "exit-sync-call": "M0",
+    "resource-new": "M1",
+    "resource-rep": "M1",
+    "resource-drop": "M1",
+    "transcoder": "M1",
+    "resource-transfer-own": "M1",
+    "resource-transfer-borrow": "M1",
+};
+function milestoneOf(kind) {
+    return TRAMPOLINE_MILESTONE[kind] ?? "M2";
+}
+/**
+ * The borrow bookkeeping of one in-flight synchronous cross-component call,
+ * bracketed by the FACT adapter's `enter-sync-call` / `exit-sync-call`
+ * imports (wasmtime-environ 47.0.3 `fact/trampoline.rs:810,904`: enter is
+ * emitted *before* argument translation and exit *after* the callee returns,
+ * so every resource transfer for the call happens inside the bracket).
+ *
+ * It plays the role definitions.py gives the callee `Subtask`/`Task`:
+ *
+ *  - `lenders` — handles lent to the callee (`Subtask.lenders`); each
+ *    `num_lends` is dropped again when the call returns, which is what makes
+ *    a lender's own handle liftable again afterwards.
+ *  - `numBorrows` — borrow handles lowered into the callee's table
+ *    (`Task.num_borrows`); the callee must drop them all before returning
+ *    (definitions.py `Task.return_`: `trap_if(self.num_borrows > 0)`).
+ *
+ * Structurally satisfies cabi's `TaskBorrowScope` and `SubtaskBorrowScope`.
+ */
+export class SyncCallScope {
+    numBorrows = 0;
+    lenders = [];
+    /**
+     * definitions.py `Subtask.add_lender` (line 890) — note there is **no**
+     * `own` check, and `lift_borrow` (line 1516) calls it unconditionally: a
+     * component that received a borrow may lend it onward, and the borrow
+     * handle's own `num_lends` is what blocks `resource.drop` on it until the
+     * onward call returns (`canon_resource_drop`, line 2325, traps on
+     * `num_lends != 0` for owning *and* borrowed handles alike).
+     * wasmtime 47.0.3 `vm/component/resources.rs:285` (`resource_lift_borrow`)
+     * agrees.
+     */
+    addLender(h) {
+        h.numLends += 1;
+        this.lenders.push(h);
+    }
+    /** definitions.py `Subtask.deliver_resolve` (lines 902-906): releases lenders at delivery time. */
+    releaseLenders() {
+        for (const h of this.lenders)
+            h.numLends -= 1;
+        this.lenders.length = 0;
+    }
+}
+/**
+ * Create the JS function backing one plan trampoline. Called during
+ * initializer/arg/export resolution — i.e. at instantiate time — so an
+ * unsupported kind fails instantiation, not the first call
+ * (plan-format.md "Executor obligations"). Unreferenced trampolines are
+ * never created and therefore never fail (intrinsics.md §B tolerates e.g.
+ * an unreferenced task-return until M2).
+ */
+export function createTrampoline(decl, ctx) {
+    const fn = createTrampolineBody(decl, ctx);
+    // Remember host traps so the FACT exception barrier cannot swallow them
+    // (see `HostTrapState`). This wraps the `trap` trampoline too, which is
+    // what keeps a specific trap specific across *nested* adapters: the inner
+    // barrier's `trap` trampoline restores and rethrows the real trap, this
+    // wrapper re-records it, and the outer barrier restores it again instead
+    // of reporting the generic `UncaughtException`.
+    return (...args) => {
+        try {
+            return fn(...args);
+        }
+        catch (e) {
+            ctx.trapState.pending = e;
+            throw e;
+        }
+    };
+}
+/**
+ * A trampoline that instantiates fine but fails at its first call, naming the
+ * phase that will implement it. See the CONTRACT note at the stream/future
+ * cases for why these are not instantiate-time failures.
+ */
+function deferredCapability(kind, capability) {
+    return () => {
+        throw new PendingCapability(`built-in '${kind}' is not implemented yet: ${capability}`);
+    };
+}
+/**
+ * The component instance a trampoline is declared in (wasmtime names it in
+ * every instance-scoped `Trampoline` variant). This is the static answer to
+ * definitions.py's `current_instance()`, and unlike it, it is defined during
+ * instantiation — when a core module's start function may already be calling
+ * these built-ins. See the header of ./async_builtins.ts.
+ */
+/** Narrow the trampoline context to what the stream built-ins need. */
+function sctx(ctx) {
+    return ctx;
+}
+function declaredInstance(decl, ctx) {
+    const instance = decl.instance;
+    assert_(typeof instance === "number", `trampoline '${decl.kind}' has no declared component instance`);
+    return ctx.componentInstance(instance);
+}
+/**
+ * The FACT sync-call bracket stack in force right now: the running task's
+ * (activations interleave since background activations exist, so a single
+ * executor-wide stack is not a stack), or the executor's when no task is
+ * running — instantiation-time start functions.
+ */
+// deno-lint-ignore no-explicit-any
+const SCOPE_TRACE = (() => {
+    try {
+        return Deno.env.get("CE_SCOPE_TRACE") === "1";
+    }
+    catch {
+        return false;
+    }
+})();
+const taskIds = new WeakMap();
+let nextTaskId = 1;
+function taskId(t) {
+    if (t === undefined || t === null)
+        return "NONE(->ctx fallback)";
+    let id = taskIds.get(t);
+    if (id === undefined) {
+        id = nextTaskId++;
+        taskIds.set(t, id);
+    }
+    return `T${id}`;
+}
+function syncScopes(ctx, site = "?") {
+    const thread = maybeCurrentThread();
+    const scopes = thread?.syncCallStack ?? ctx.syncCallStack;
+    if (SCOPE_TRACE) {
+        console.error(`[scope] ${site} act=${taskId(thread)} depth=${scopes.length}`);
+    }
+    return scopes;
+}
+function createTrampolineBody(decl, ctx) {
+    switch (decl.kind) {
+        case "lower-import": {
+            const d = decl;
+            return ctx.loweredImport(d);
+        }
+        case "trap":
+            // FACT `runtime.trap` import: `(code: i32) -> ()` followed by
+            // `unreachable` (wasmtime-environ `fact/trampoline.rs:3932`).
+            return (code) => {
+                if (code === TRAP_UNCAUGHT_EXCEPTION) {
+                    const pending = ctx.trapState.pending;
+                    if (pending !== undefined) {
+                        // Deliberately *not* cleared: an enclosing adapter's barrier will
+                        // catch this rethrow and needs to restore the same trap. The slot
+                        // is reset per lifted-export call (exec/boundary.ts), which is
+                        // what bounds its lifetime.
+                        throw pending;
+                    }
+                }
+                const message = code === undefined
+                    ? undefined
+                    : FACT_TRAP_MESSAGES[code];
+                trap(message === undefined
+                    ? `FACT adapter trap (code ${code ?? "?"})`
+                    : `wasm trap: ${message}`);
+            };
+        // Sync-call task bookkeeping (intrinsics.md §A: "degenerate-case
+        // implementation in M0: assert-and-count"). wasmtime 47 signatures:
+        // enter-sync-call carries the caller/callee instance pair, which is what
+        // the reentrance gate below needs; balance of the bracket is asserted at
+        // component teardown by tests.
+        // Signatures (wasmtime-environ 47.0.3 `fact.rs:743,754`):
+        //   async.enter-sync-call(caller_instance: i32, async: i32,
+        //                         callee_instance: i32) -> ()
+        //   async.exit-sync-call() -> ()
+        case "enter-sync-call":
+            return (callerInstance, async_, calleeInstance) => {
+                // Reference reentrance gate. Every guest->guest call in
+                // definitions.py routes through the callee's lift wrapper:
+                //   canon_lower (line 2312) calls
+                //     `callee(on_start, on_resolve, caller = thread.task.inst)`,
+                //   and `callee` is `Store.lift`'s `func_inst` (lines 578-585), whose
+                //   first act is
+                //     `trap_if(not inst.may_enter_from(caller))`   (line 581)
+                //   with `entering_set(caller) = callee.self_and_ancestors()
+                //                                - caller.self_and_ancestors()`
+                //   (lines 230-234).
+                // A sync fused adapter is an *optimization* of that path, so the gate
+                // belongs here (issue #99).
+                //
+                // Note on the shape of the entering set, which is what makes this
+                // check safe for the legal shapes:
+                //   * caller == callee, or either an ancestor of the other -> the
+                //     entering set is empty and this never traps. Those pairs never
+                //     reach this trampoline anyway: FACT emits an unconditional
+                //     `CannotEnterComponent` trap for them at compile time
+                //     (wasmtime-environ 47.0.3 `fact/trampoline.rs:120-127`), which
+                //     is what `test/async/trap-on-reenter.wast` cases 2 and 3 pin.
+                //   * an *idle* sibling -> `mayEnter` is true, no trap. This is what
+                //     `test/async/sync-barges-in.wast` needs: an async callee that is
+                //     merely blocked has already run `leave_to` (its `canon_lift`
+                //     returned), so a sync sibling may barge in.
+                //   * an *entered* sibling -> trap, which is the A -> C -> A cycle.
+                //
+                // CONTRACT / reachability: a pure guest-to-guest sibling cycle is
+                // unreachable by construction, because component instance imports
+                // form a DAG (a callee must be instantiated before its caller, so it
+                // cannot hold an import of its caller; `wasm-tools` rejects the
+                // mutual-import composition outright). wasmtime relies on exactly
+                // that to elide the runtime check in fused adapters -- see the
+                // comment in `may_enter`, wasmtime 47.0.3
+                // `runtime/component/concurrent.rs:1876-1886`, and
+                // `enter_guest_sync_call` (concurrent.rs:1723) which performs no
+                // reentrance check at all. The gate is kept anyway because the
+                // reference mandates it and no corpus test pins the permissive
+                // behaviour; it is cheap, and it is the honest place for the
+                // invariant to be asserted rather than assumed.
+                //
+                // Deliberately *not* done here: `enter_from` / `leave_to` around the
+                // bracket. The reference locks the callee for the duration, which
+                // would additionally trap host-mediated reentrance (host -> A.f ->
+                // C.g -> host import -> host invokes C.g).
+                //
+                // ADJUDICATED 2026-08-20 (polyengine#165; named divergence in
+                // docs/architecture.md section 6): accepted — the bracket stays
+                // omitted. Three grounds: wasmtime parity (`enter_guest_sync_call`
+                // checks nothing); taking the bracket would create a guest-to-guest
+                // lock spanning suspension points, reintroducing the await-spanning
+                // -lock class removed by #156/#160; and upstream is deleting the
+                // trap outright — CM PR #705 ("CABI: remove the may_enter
+                // flag/trap") makes previously-trapping reentrance valid, so this
+                // divergence is a trailing indicator of the removal and
+                // self-resolves at the submodule pin advance (migration map:
+                // polyengine#173). Until that pin advance the reference's checks polyengine
+                // DOES enforce stay in force.
+                if (typeof callerInstance === "number" &&
+                    typeof calleeInstance === "number") {
+                    const callerInst = ctx.componentInstance(callerInstance >>> 0);
+                    const calleeInst = ctx.componentInstance(calleeInstance >>> 0);
+                    // A poisoned callee's refusal names the original trap (polyengine#145).
+                    if (!calleeInst.mayEnterFrom(callerInst)) {
+                        trap(withPoisonCause(calleeInst, "cannot enter component instance"));
+                    }
+                }
+                // `async_` records whether the callee is *async-lifted*. wasmtime
+                // stores it on the guest task it creates here
+                // (`concurrent.rs:1723` `enter_guest_sync_call`, whose `callee_async`
+                // parameter flows into `GuestTask::new`) and never traps on it.
+                //
+                // Before the task core existed this trampoline refused `async_ == 1`
+                // rather than silently treating an async callee as sync. That guard is
+                // now stale and actively wrong: a sync-lowered caller reaching an
+                // async-lifted export is the `sync-start-call` path
+                // (intrinsics/fact_calls.ts), and the task it needs is created by
+                // `prepare-call`, not here. What remains of this bracket for us is the
+                // borrow bookkeeping (`SyncCallScope`), which applies either way.
+                void async_;
+                ctx.stats.enterSyncCalls++;
+                // Per task where there is one; the executor-wide stack is the
+                // fallback for a start function running at instantiation time, which
+                // has no task (see `maybeCurrentTask`).
+                // Invariant, per ACTIVATION: every `enter` is matched by exactly one
+                // `exit` on the same stack. Recorded here so the `exit` side can
+                // assert it structurally rather than only by depth (CE_SCOPE_TRACE
+                // proved this is where the interesting failures live).
+                const scopes = syncScopes(ctx, "enter");
+                scopes.push(new SyncCallScope());
+            };
+        case "exit-sync-call":
+            return (..._args) => {
+                ctx.stats.exitSyncCalls++;
+                assert_(ctx.stats.exitSyncCalls <= ctx.stats.enterSyncCalls, "exit-sync-call without matching enter-sync-call");
+                const scope = syncScopes(ctx, "exit").pop();
+                assert_(scope !== undefined, 
+                // If this fires, an `exit` reached an activation that never ran the
+                // matching `enter` -- the bracket is attached to the wrong unit
+                // again. See `Thread.syncCallStack`.
+                "exit-sync-call with an empty sync-call stack");
+                // definitions.py `Task.return_`: the callee may not return while it
+                // still holds borrow handles. Wording parity with wasmtime's
+                // exit-time check (drop-cross-task-borrow.wast:309 pins the async
+                // path; the sync bracket is the same check).
+                trapIf(scope.numBorrows > 0, "borrow handles still remain at the end of the call");
+                scope.releaseLenders();
+            };
+        // Guest-side resource built-ins (sync paths of docs/architecture.md §7 over the cabi
+        // handle tables). rep is always i32 in current wasmtime.
+        case "resource-new": {
+            const d = decl;
+            const inst = ctx.componentInstance(d.instance);
+            const rt = ctx.resourceToken(d.resource);
+            return (rep) => canonResourceNew(inst, rt, rep >>> 0);
+        }
+        case "resource-rep": {
+            const d = decl;
+            const inst = ctx.componentInstance(d.instance);
+            const rt = ctx.resourceToken(d.resource);
+            return (handle) => canonResourceRep(inst, rt, handle >>> 0);
+        }
+        case "resource-drop": {
+            const d = decl;
+            const inst = ctx.componentInstance(d.instance);
+            const rt = ctx.resourceToken(d.resource);
+            return (handle) => {
+                canonResourceDrop(inst, rt, handle >>> 0);
+            };
+        }
+        // FACT resource transfer (contracts/intrinsics.md §A, wasmtime-environ
+        // 47.0.3 `fact.rs:721` — signature `(i32 src_handle, i32 src_table,
+        // i32 dst_table) -> i32 dst_handle`). These are the fused-adapter form of
+        // `lift_own`/`lower_own` and `lift_borrow`/`lower_borrow`
+        // (definitions.py) with the src/dst tables named by index rather than
+        // implied by the running instance.
+        // FACT string transcoders (contracts/intrinsics.md §B "M1"). The plan
+        // carries the op name plus the source/destination `RuntimeMemoryIndex`es;
+        // `./transcode.ts` holds the twelve operations.
+        case "transcoder": {
+            const d = decl;
+            if (d.from64 || d.to64) {
+                // 64-bit linear memories are out of scope (https://github.com/polymorph-components/polyengine/issues/12); refusing at
+                // instantiate time keeps "instantiate-time, never call-time".
+                throw new UnsupportedFeatureError("M2", `transcoder '${d.op}' over a 64-bit linear memory`);
+            }
+            if (!TRANSCODE_OPS.includes(d.op)) {
+                throw new UnsupportedFeatureError("M2", `unknown string transcode operation '${d.op}'`);
+            }
+            return createTranscoder(d.op, ctx.runtimeMemory(d.from), ctx.runtimeMemory(d.to));
+        }
+        // --- 0.3 async built-ins (contracts/intrinsics.md §B "M2") -------------
+        // All ported in ./async_builtins.ts; the ones that would have to block a
+        // wasm frame fail there, at the call site, with a JSPI-shaped message.
+        case "task-return":
+            return createTaskReturn(decl, ctx);
+        case "task-cancel":
+            return createTaskCancel();
+        // No `backpressure-set` case on purpose: wasmtime-environ 47.0.3 has only
+        // `Trampoline::BackpressureInc` / `BackpressureDec`
+        // (`component/info.rs:775,781`) — there is no `BackpressureSet` variant to
+        // dispatch, so a case for it would be unreachable code implying a wire
+        // shape that cannot occur. definitions.py's own dead
+        // `canon_backpressure_set` was removed upstream (CM PR #690); see
+        // upstream-component-model-repo-findings.md CM-2, RESOLVED.
+        case "backpressure-inc":
+            return createBackpressureInc(declaredInstance(decl, ctx));
+        case "backpressure-dec":
+            return createBackpressureDec(declaredInstance(decl, ctx));
+        case "waitable-set-new":
+            return createWaitableSetNew(declaredInstance(decl, ctx));
+        case "waitable-set-wait":
+            return createWaitableSetWait(decl, ctx, declaredInstance(decl, ctx), ctx.suspensionMode);
+        case "waitable-set-poll":
+            return createWaitableSetPoll(decl, ctx, declaredInstance(decl, ctx));
+        case "waitable-set-drop":
+            return createWaitableSetDrop(declaredInstance(decl, ctx));
+        case "waitable-join":
+            return createWaitableJoin(declaredInstance(decl, ctx));
+        case "subtask-drop":
+            return createSubtaskDrop(declaredInstance(decl, ctx));
+        case "subtask-cancel":
+            return createSubtaskCancel(decl, declaredInstance(decl, ctx), ctx.suspensionMode);
+        case "thread-yield":
+            return createThreadYield(decl, ctx.suspensionMode);
+        // --- FACT cross-component calls (see ./fact_calls.ts) -----------------
+        case "prepare-call":
+            return createPrepareCall(decl, ctx);
+        case "sync-start-call":
+            return createSyncStartCall(decl, ctx);
+        case "async-start-call":
+            return createAsyncStartCall(decl, ctx);
+        // --- stream / future / error-context (see ./stream_builtins.ts) -------
+        case "stream-new":
+            return createStreamNew(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-new":
+            return createFutureNew(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "stream-read":
+            return createStreamRead(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "stream-write":
+            return createStreamWrite(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-read":
+            return createFutureRead(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-write":
+            return createFutureWrite(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "stream-cancel-read":
+            return createStreamCancelRead(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "stream-cancel-write":
+            return createStreamCancelWrite(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-cancel-read":
+            return createFutureCancelRead(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-cancel-write":
+            return createFutureCancelWrite(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "stream-drop-readable":
+            return createStreamDropReadable(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "stream-drop-writable":
+            return createStreamDropWritable(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-drop-readable":
+            return createFutureDropReadable(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "future-drop-writable":
+            return createFutureDropWritable(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "error-context-new":
+            return createErrorContextNew(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "error-context-debug-message":
+            return createErrorContextDebugMessage(decl, sctx(ctx), declaredInstance(decl, ctx));
+        case "error-context-drop":
+            return createErrorContextDrop(declaredInstance(decl, ctx));
+        case "stream-transfer":
+            return createStreamTransfer(ctx);
+        case "future-transfer":
+            return createFutureTransfer(ctx);
+        case "error-context-transfer":
+            return createErrorContextTransfer(ctx, 
+            // plan v3: the transfer's table arguments are
+            // `TypeComponentLocalErrorContextTableIndex`es (fact/trampoline.rs:
+            // 3526-3539), resolved through the plan's own `errorContextTables`
+            // section. Before v3 this went through `resourceTableInstance` — a
+            // different index space, which mis-routed silently whenever a
+            // concrete resource table happened to exist at the colliding slot
+            // (polyengine#89).
+            (t) => ctx.errorContextTableInstance(t));
+        case "resource-transfer-own":
+            return (handle, srcTable, dstTable) => transferOwn(ctx, handle >>> 0, srcTable, dstTable);
+        case "resource-transfer-borrow":
+            return (handle, srcTable, dstTable) => transferBorrow(ctx, handle >>> 0, srcTable, dstTable);
+        default:
+            throw new UnsupportedFeatureError(milestoneOf(decl.kind) === "M1" ? "M1" : "M2", `component requires host trampoline '${decl.kind}'`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Resource transfer (FACT `resource.transfer-own` / `transfer-borrow`)
+// ---------------------------------------------------------------------------
+/**
+ * `lift_own` out of the source table followed by `lower_own` into the
+ * destination table (definitions.py `lift_own` / `lower_own`): the source
+ * handle is *removed* (ownership moves), must be owning, and must not be
+ * lent out.
+ */
+function transferOwn(ctx, handle, srcTable, dstTable) {
+    const src = ctx.resourceTableInstance(srcTable);
+    const dst = ctx.resourceTableInstance(dstTable);
+    const srcRt = ctx.resourceToken(srcTable);
+    const dstRt = ctx.resourceToken(dstTable);
+    const h = src.handles.remove(handle);
+    trapIf(!(h instanceof ResourceHandle), "transfer-own: not a resource handle");
+    const rh = h;
+    trapIf(rh.rt !== srcRt, "transfer-own: resource type mismatch");
+    // definitions.py `lift_own`: `trap_if(h.num_lends != 0)`.
+    trapIf(rh.numLends !== 0, "cannot remove owned resource while borrowed (handle still lent out)");
+    trapIf(!rh.own, "transfer-own: expected an owning handle");
+    return dst.handles.add(new ResourceHandle(dstRt, rh.rep, true));
+}
+/**
+ * `lift_borrow` from the source table followed by `lower_borrow` into the
+ * destination table. The source handle stays in place; the destination gets a
+ * non-owning handle.
+ *
+ * Two deviations from the plain lift/lower pair, both taken from
+ * definitions.py:
+ *
+ *  - `lower_borrow` returns the *rep* directly when the destination instance
+ *    is the one that implements the resource ("own the resource" fast path),
+ *    since a component always has direct access to its own reps.
+ *  - lender / `num_borrows` bookkeeping is attached to the enclosing
+ *    `SyncCallScope` (the `enter-sync-call` / `exit-sync-call` bracket),
+ *    which is this path's stand-in for the callee `Subtask`/`Task` of
+ *    definitions.py.
+ */
+// CONTRACT: contracts/intrinsics.md §A schedules ResourceTransfer* at "M1,
+// resources milestone" and describes them only as "handle-table moves between
+// component instances" — the borrow-scope interaction is unspecified there.
+// The reading implemented here is taken from definitions.py
+// (`lift_borrow`/`lower_borrow` + `Subtask.lenders`/`Task.num_borrows`) and
+// is what makes `test/resources/borrows.wast:162` (`lend-trap`) trap.
+function transferBorrow(ctx, handle, srcTable, dstTable) {
+    const src = ctx.resourceTableInstance(srcTable);
+    const dst = ctx.resourceTableInstance(dstTable);
+    const srcRt = ctx.resourceToken(srcTable);
+    const dstRt = ctx.resourceToken(dstTable);
+    // Innermost-scope resolution. A FACT `[async-start]` copy window is
+    // strictly synchronous and innermost when present (the copy adapters
+    // cannot make nested calls), so it wins over any enclosing sync bracket.
+    const fact = ctx.factStartScopes[ctx.factStartScopes.length - 1];
+    const stack = syncScopes(ctx);
+    const scope = stack[stack.length - 1];
+    assert_(fact !== undefined || scope !== undefined, "transfer-borrow outside an enter-sync-call/exit-sync-call bracket " +
+        "or FACT start window");
+    const h = src.handles.get(handle);
+    trapIf(!(h instanceof ResourceHandle), "transfer-borrow: not a resource handle");
+    const rh = h;
+    trapIf(rh.rt !== srcRt, "transfer-borrow: resource type mismatch");
+    // definitions.py `lift_borrow`: the source handle becomes a lender of the
+    // callee's activation, which is what makes lifting it as an `own` trap for
+    // the duration of the call.
+    (fact?.lenders ?? scope).addLender(rh);
+    // definitions.py `lower_borrow`: `if inst is t.rt.impl: return rep` — a
+    // component that implements the resource is handed the rep directly and
+    // gets no handle (and therefore no `num_borrows` obligation).
+    if (dstRt.impl !== null && dstRt.impl === dst)
+        return rh.rep;
+    const borrowScope = fact !== undefined ? fact.taskScope : scope;
+    borrowScope.numBorrows += 1;
+    return dst.handles.add(new ResourceHandle(dstRt, rh.rep, false, borrowScope));
+}