@polyengine/runtime 0.4.0 → 0.5.1

package/esm/embedder/copy.js

@@ -29,7 +29,7 @@ export const COPY_URL = import.meta.url;
  * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
  * host-facing.
  */
-export const RUNTIME_VERSION = "0.4.0";
+export const RUNTIME_VERSION = "0.5.1";
 /**
  * Compose a cross-copy diagnostic: what was foreign, which copy is speaking,
  * the census of every copy in the graph, and the by-value remediation.

package/esm/embedder/instantiate.js

@@ -13,7 +13,7 @@ import { loadEnvelope, loadPlan, PlanError } from "../plan/loader.js";
 import { Trap } from "../cabi/trap.js";
 import { CONSTRUCTOR_SYNC_ENTRY, hostResourceType, instantiateComponent, } from "../exec/mod.js";
 import { camelCase, parseLeafName, pascalCase } from "./casing.js";
-import { isSuspending, suspending } from "../jspi/suspending.js";
+import { abortable, deferCancel, isAbortable, isDeferCancel, isSuspending, suspending, } from "../jspi/suspending.js";
 import { Translator } from "../shim/mod.js";
 import { copyCensus, isTrap, isComponentException } from "@polyengine/protocol";
 import { NameCollisionError, ComponentException } from "./errors.js";
@@ -23,6 +23,27 @@ import { buildGuestResourceClass, HostResourceRegistry, invalidateWrapper, lendW
 import { BorrowScope, describe, fromHost, toHost, } from "./values.js";
 import { ImportResolver } from "./version.js";
 import { Future, Stream } from "./streams.js";
+/**
+ * Relay the per-declaration host-import marks from the embedder's function
+ * onto the wrapper the executor will actually receive, and return the
+ * wrapper.
+ *
+ * Every `#dispatcher` arm re-wraps the embedder's function in a closure, so a
+ * brand left on the original is INVISIBLE to `buildLoweredImport` — for A1
+ * that surfaced as a `NeedsJspi`, for A23 (`deferCancel()`) it would be a
+ * silently discarded commit, which is precisely the failure the brand exists
+ * to prevent. Both marks are relayed by the same helper so a third one cannot
+ * be added to one arm and forgotten in the other three.
+ */
+function relayMarks(from, to) {
+    if (isSuspending(from))
+        suspending(to);
+    if (isDeferCancel(from))
+        deferCancel(to);
+    if (isAbortable(from))
+        abortable(to);
+    return to;
+}
 /** Per-element codec for a `future<T>` returned in function-result position. */
 function elementCodec(element, o) {
     return {
@@ -433,9 +454,10 @@ class Facade {
             }
             return impl(...raw);
         };
-        // A1 brand relay, layer 2 of 2 (see #dispatcher): the executor reads the
-        // brand off this wrapper, which is what lands in its hostImports record.
-        return isSuspending(dispatch) ? suspending(wrapper) : wrapper;
+        // A1/A23 brand relay, layer 2 of 2 (see #dispatcher): the executor reads
+        // the brands off this wrapper, which is what lands in its hostImports
+        // record.
+        return relayMarks(dispatch, wrapper);
     }
     /** A host-implemented resource type: register the class, own the mapping. */
     #wrapResourceType(leaf, importIndex, provider) {
@@ -471,8 +493,9 @@ class Facade {
                 throw new PlanError(`host import '${label(leaf)}' missing or not a function (got ` +
                     `${describe(fn)}); expected '${camelCase(m.name)}'`);
             }
-            // A1: the `suspending()` brand rides the dispatch closure so #wrapLeaf
-            // can relay it onto the value the executor actually receives.
+            // A1/A23: the `suspending()` and `deferCancel()` brands ride the
+            // dispatch closure so #wrapLeaf can relay them onto the value the
+            // executor actually receives.
             //
             // A2 receiver rule: an interface member is invoked with its containing
             // object as receiver (matching the static arm's `apply(cls)`), so a
@@ -485,7 +508,7 @@ class Facade {
             // liberal-acceptance failure the contract forbids.)
             const receiver = leaf.path.length === 0 ? undefined : provider;
             const dispatch = (args) => fn.apply(receiver, args);
-            return isSuspending(fn) ? suspending(dispatch) : dispatch;
+            return relayMarks(fn, dispatch);
         }
         const clsName = pascalCase(m.resource);
         // World-level member leaves resolved the class itself (`#provider`);
@@ -530,7 +553,7 @@ class Facade {
                     }
                     return fn.apply(self, rest);
                 };
-                return isSuspending(protoFn) ? suspending(dispatch) : dispatch;
+                return relayMarks(protoFn, dispatch);
             }
             case "static": {
                 const fn = cls[camelCase(m.member)];
@@ -542,7 +565,7 @@ class Facade {
                 // static-method decorator marks the function value), readable here
                 // at wrap time.
                 const dispatch = (args) => fn.apply(cls, args);
-                return isSuspending(fn) ? suspending(dispatch) : dispatch;
+                return relayMarks(fn, dispatch);
             }
         }
     }
@@ -615,6 +638,17 @@ class Facade {
         return (...raw) => {
             const scope = new BorrowScope();
             const args = ft.params.map((p, i) => toHost(raw[i], p, o, scope));
+            // CONTRACT (A24): anything the executor appended PAST the WIT-declared
+            // params is a runtime-minted extra, not a component value — today
+            // exactly the `abortable()` signal `createLoweredImport` adds for a
+            // marked import. It is forwarded verbatim (no `toHost` conversion: it
+            // has no `ValType` and must reach the host as the platform object it
+            // is). Without this the facade would silently drop the signal and a
+            // marked import's `signal` parameter would be forever `undefined` —
+            // the failure the mark exists to prevent. The slice is empty for every
+            // unmarked import, so no existing path changes shape.
+            for (let i = ft.params.length; i < raw.length; i++)
+                args.push(raw[i]);
             let out;
             try {
                 out = dispatch(args);

package/esm/embedder/mod.js

@@ -22,19 +22,30 @@ registerRuntimeCopy({
     protocolGeneration: PROTOCOL_GENERATION,
 });
 export { COPY_URL, RUNTIME_VERSION } from "./copy.js";
-// The A9 vocabulary, re-exported unchanged: embedder code needs no import
-// change, and consumers that want the multi-copy-robust spellings get them
-// from the same module they already import.
-export { copyCensus, defineRealmLocal, DROPPED, ERROR_CONTEXT, fromCloneable, FUTURE, hasBrand, INVALID_HANDLE, isDroppedError, isInvalidHandleError, isPeerTrappedError, isRealmLocal, isStreamProducerError, isSuspending, isTrap, isComponentException, PEER_TRAPPED, PROTOCOL_GENERATION, REALM_LOCAL, registerRuntimeCopy, RESOURCE_STATE, runtimeCopies, STREAM, STREAM_PRODUCER, SUSPENDING, toCloneable, TRAP, COMPONENT_EXCEPTION, } from "@polyengine/protocol";
+// Amendment A22 (contracts/embedder-api.md §"The host-ABI surface and its
+// version"): the runtime's exported surface is application-only. The A9
+// courtesy re-exports (error classes, predicates, brands, `suspending`,
+// realm crossing, the copy registry) are removed — host modules import that
+// vocabulary from `@polyengine/protocol` directly. The runtime still
+// registers its own copy on the census above; it just no longer hands out
+// the registry API to callers of this module.
 export { artifactsFromEnvelope, instantiate, instantiateEmbedder, resolveArtifacts, } from "./instantiate.js";
 export { requiredImports } from "./imports.js";
-export { DroppedError, InvalidHandleError, NameCollisionError, PeerTrappedError, Trap, ComponentException, } from "./errors.js";
-export { ErrorContext, Future, Stream, StreamProducerError, StreamWriter, } from "./streams.js";
+// `NameCollisionError` is the one error class that stays here: it's raised
+// while building an instantiation facade, before any handle/value exists —
+// application machinery, not host-ABI vocabulary (contracts/embedder-api.md
+// §"The host-ABI surface and its version", amendment A22).
+export { NameCollisionError } from "./errors.js";
+// `createStream<T>()` — the A22 stream-pair factory (contracts/embedder-api.md
+// §"The host-ABI surface and its version" / §"Streams and futures"): the
+// `Stream.create()` static's application-surface spelling, since the
+// concrete `Stream`/`StreamWriter` classes are no longer exported. Handle
+// TYPES are spelled against `@polyengine/protocol`'s structural interfaces.
+import { Stream as InternalStream } from "./streams.js";
+export function createStream() {
+    return InternalStream.create();
+}
 export { GuestResource, HostResourceRegistry } from "./resources.js";
 export { camelCase, parseLeafName, pascalCase } from "./casing.js";
-// Per-declaration suspendability (contracts/embedder-api.md §"Functions and
-// async", amendment A1): declares that a sync-typed host import may return a
-// Promise, parking the calling wasm frame (JSPI engines only).
-export { suspending } from "../jspi/suspending.js";
 export { asTrackKeySpelling, compareSemver, ImportRegistrationError, ImportResolutionError, ImportResolver, parseInterfaceId, parseSemver, trackKey, } from "./version.js";
 export { BorrowScope, fromHost, toHost, } from "./values.js";

package/esm/embedder/streams.js

@@ -10,7 +10,7 @@
 import { despecialize } from "../cabi/types.js";
 import { hostFuture, hostFutureFor, hostStream, hostStreamFor, } from "../exec/host_streams.js";
 import { CopyResult, dropSharedForTeardown, poisonFailureOf, } from "../task/mod.js";
-import { defineBrand, defineRealmLocal, ERROR_CONTEXT, FUTURE, hasBrand, isStreamProducerError, STREAM, StreamProducerError, } from "@polyengine/protocol";
+import { defineBrand, defineRealmLocal, ERROR_CONTEXT, FUTURE, hasBrand, isStreamProducerError, STREAM, StreamProducerError, STREAM_WRITER, } from "@polyengine/protocol";
 import { describeCrossCopy } from "./copy.js";
 import { DroppedError, PeerTrappedError } from "./errors.js";
 // `StreamProducerError`'s canonical definition moved to `@polyengine/protocol`
@@ -85,6 +85,16 @@ function throwIfPeerTrapped(value, where, progress) {
 export function isU8Element(element) {
     return element !== null && despecialize(element).kind === "u8";
 }
+/**
+ * A21 (#128): the direct-access byte edges are `stream<u8>` only. A
+ * zero-width element type (`t === null`) is not u8 either.
+ */
+function requireU8Direct(codec, who) {
+    if (codec === null || !isU8Element(codec.element)) {
+        throw new TypeError(`${who} is available on stream<u8> only (embedder-api amendment A21, ` +
+            `polyengine#128); use write()/read() for other element types`);
+    }
+}
 /**
  * A stream handle.
  *
@@ -203,6 +213,45 @@ export class Stream {
             throwIfPeerTrapped(host.value, where);
         return this.#chunk(raw);
     }
+    /**
+     * Consume the writer's bytes in place, without an intermediate chunk
+     * (`stream<u8>` only — contracts/embedder-api.md amendment A21,
+     * polyengine#128).
+     *
+     * At every rendezvous with a writer of nonzero capacity, `consume` runs
+     * exactly once, synchronously, with a `DirectSource` over the writer's
+     * unread bytes — guest linear memory when the peer is a guest, so the
+     * consumer's own `set()`/`subarray` copy IS the canonical-ABI copy.
+     * `"more"` keeps the session parked for the next rendezvous; `"done"` ends
+     * it. Resolves with the session's total byte count. Marking a prefix is
+     * normal: the writer re-offers the rest on its own schedule.
+     *
+     * `"done"` with zero bytes marked *retracts*: the session ends and the
+     * writer's operation stays parked, with no event delivered. `"more"` with
+     * zero marked, and a throwing callback, reject — and in both cases the
+     * writer's parked operation survives and the stream stays alive.
+     *
+     * Refusals mirror `read`: an unbound `Stream.create()` handle and a handle
+     * already passed to a guest (the A15 transfer guard) both throw, as does a
+     * non-`u8` element type.
+     */
+    async readDirect(consume) {
+        const host = this.#require();
+        const where = this.#codec?.where ?? "stream read";
+        throwIfFailed(host.value, where);
+        requireU8Direct(this.#codec, "readDirect");
+        const info = { endedByVerdict: false };
+        const n = await host.readable.readDirect(consume, info);
+        // A7 precision, `read`'s rule adapted: a session the CONSUMER itself
+        // ended with `"done"` genuinely completed and keeps its resolution. Any
+        // other way out (the writer dropped, the session was cancelled, the
+        // retirement walk settled us) is a settle-path this consumer did not
+        // cause — so if the peer's instance trapped, reject with the delivered
+        // count rather than fake a clean end.
+        if (!info.endedByVerdict)
+            throwIfPeerTrapped(host.value, where, n);
+        return n;
+    }
     #chunk(raw) {
         const codec = this.#codec;
         if (isU8Element(codec.element)) {
@@ -327,6 +376,44 @@ export class StreamWriter {
             throwIfPeerTrapped(host.value, where, n);
         return n;
     }
+    /**
+     * Fill the reader's landing zone in place, without an intermediate chunk
+     * (`stream<u8>` only — contracts/embedder-api.md amendment A21,
+     * polyengine#128).
+     *
+     * At every rendezvous with a reader of nonzero capacity, `produce` runs
+     * exactly once, synchronously, with a `DirectDestination` over the reader's
+     * unfilled landing zone — guest linear memory when the peer is a guest, so
+     * the producer's own `set()` IS the canonical-ABI copy and an external byte
+     * mover (a websocket frame, a SAB ring segment, a transferred
+     * `ArrayBuffer`) never pays a second copy inside the runtime. `"more"`
+     * keeps the session parked for the next rendezvous; `"done"` ends it.
+     * Resolves with the session's total byte count.
+     *
+     * `"done"` with zero bytes marked *retracts* (the session ends, the
+     * reader's operation stays parked, no event — the speculative-park
+     * correction); `"more"` with zero marked, and a throwing callback, reject.
+     *
+     * Parks until the element type is known, exactly as `write` does — a
+     * `Stream.create()` writer has no element type until the lowering site
+     * binds one — and then requires `u8`.
+     */
+    async writeDirect(produce) {
+        await this.#stream.whenBound();
+        const host = hostOf(this.#stream);
+        const where = this.#stream.codec?.where ?? "stream write";
+        throwIfFailed(host.value, where);
+        requireU8Direct(this.#stream.codec, "writeDirect");
+        const info = { endedByVerdict: false };
+        const n = await host.writable.writeDirect(produce, info);
+        // A7 precision, `write`'s short-take rule adapted: a session the PRODUCER
+        // itself ended with `"done"` keeps its resolution; every other way out is
+        // a settle-path the producer did not cause, so a trapped peer rejects
+        // here carrying the delivered count.
+        if (!info.endedByVerdict)
+            throwIfPeerTrapped(host.value, where, n);
+        return n;
+    }
     /** Offer values until all are taken or the reader goes away. */
     async writeAll(values) {
         await this.#stream.whenBound();
@@ -544,11 +631,15 @@ export class ErrorContext {
         defineRealmLocal(this);
     }
 }
-// A9 brands (contracts/embedder-api.md §"Module identity"): the three
-// STATEFUL embedder-facing handle classes. Their machinery lives in the copy
-// that minted them, so the brand never makes a foreign handle usable — it
-// makes it DIAGNOSABLE, at the lowering sites below.
+// A9 brands (contracts/embedder-api.md §"Module identity"): the STATEFUL
+// embedder-facing handle classes. Their machinery lives in the copy that
+// minted them, so the brand never makes a foreign handle usable — it makes
+// it DIAGNOSABLE, at the lowering sites below. `StreamWriter` gains its
+// brand with amendment A22 (§"The host-ABI surface and its version"):
+// writers carried none before because nothing needed to recognize one, and
+// `isStreamWriter` now does.
 defineBrand(Stream.prototype, STREAM);
+defineBrand(StreamWriter.prototype, STREAM_WRITER);
 defineBrand(Future.prototype, FUTURE);
 defineBrand(ErrorContext.prototype, ERROR_CONTEXT);
 /**

package/esm/exec/boundary.js

@@ -385,7 +385,9 @@ export async function driveStoreAsync(store, done, what) {
  * have always produced concurrent loops, and the host-stream pump's stand-down
  * below is cooperative, so a *bounded overlap window* remains by construction
  * (an export call can start while the pump is parked mid-`await`; the pump
- * only notices at its next `done()` evaluation). The invariant is:
+ * notices at its next `done()` evaluation, which the driver-arrival one-shot
+ * below now makes prompt — before issue #239 it was "whenever the host happens
+ * to answer", i.e. not bounded at all). The invariant is:
  *
  *   **no activation is resumed twice for one settlement, and no activation is
  *   resumed with a value from a settlement it has already consumed.**
@@ -455,6 +457,51 @@ export function whenStoreDriverIdle(store) {
     return w.p;
 }
 // ---------------------------------------------------------------------------
+// Driver arrival: closing the overlap window (issue #239)
+// ---------------------------------------------------------------------------
+//
+// The stand-down above ("the pumps are *fallback* drivers") is evaluated only
+// at a driver's next `done()`, so the doc's "bounded overlap window" is really
+// bounded by whatever the incumbent driver is parked on — and its longest park
+// is `Promise.race([...parked tags, ...pendingHostCalls])`, i.e. HOST-CONTROLLED
+// time. That is a stall in its own right, and it is fatal in combination with
+// the SPECULATIVE resume entry the race holds: `Store.pendingResumptions` is a
+// store-wide scheduling gate, so a second driver on the same store spins at
+// `driveAsync`'s top and dies at the 10,000-hop internal-bug assert in ~311ms
+// (issue #239 — the same-store half of the cross-store stall #210 fixed; see
+// `tests/cross_store_driver_test.ts`, whose header describes this gate being
+// "held for the entire duration of a guest's wait on a slow host import").
+//
+// So drivers announce themselves: every `driveAsync` that finds itself the
+// second (or later) loop on a store fires this one-shot, which every driver
+// races alongside its parked tags. The incumbent wakes within a microtask,
+// drops the speculative entry on its way out of the race, and re-evaluates
+// `done()` — which is exactly the stand-down the pumps were always supposed to
+// perform, now prompt instead of "whenever the host happens to answer".
+const driverArrivals = new WeakMap();
+/** A one-shot that resolves (to `null`, the race's "nothing settled" value)
+ * when another driver starts on `store`. */
+function armDriverArrival(store) {
+    let n = driverArrivals.get(store);
+    if (n === undefined) {
+        let r;
+        const p = new Promise((res) => (r = () => res(null)));
+        n = { p, r };
+        driverArrivals.set(store, n);
+    }
+    return n.p;
+}
+function fireDriverArrival(store) {
+    const n = driverArrivals.get(store);
+    if (n === undefined)
+        return;
+    // Deleted before resolving so the next `armDriverArrival` mints a fresh,
+    // unresolved one-shot: a driver that wakes on this and re-parks must not
+    // pick the settled promise back up and spin.
+    driverArrivals.delete(store);
+    n.r();
+}
+// ---------------------------------------------------------------------------
 // The settlement pump: liveness between export calls
 // ---------------------------------------------------------------------------
 //
@@ -599,7 +646,14 @@ async function settlementPumpLoop(store) {
     }
 }
 async function driveAsync(store, done, what) {
-    driverDepth.set(store, storeDriverDepth(store) + 1);
+    const depth = storeDriverDepth(store) + 1;
+    driverDepth.set(store, depth);
+    // An incumbent driver may be parked in the awaiting-race holding the
+    // speculative resume entry — a store-wide gate this loop would otherwise
+    // spin on until the 10,000-hop assert (issue #239). Announce ourselves so it
+    // stands down within a microtask.
+    if (depth > 1)
+        fireDriverArrival(store);
     try {
         let claimHops = 0;
         for (;;) {
@@ -831,9 +885,14 @@ async function driveAsync(store, done, what) {
                     // Every awaiting thread's settle is deferred on a non-enterable
                     // instance. The way out is the lock holder finishing, and the only
                     // await-spanning host-entry lock is the async-dtor bracket, which
-                    // registers in `pendingHostCalls` — so park on those.
+                    // registers in `pendingHostCalls` — so park on those, plus the
+                    // driver-arrival one-shot: every park in this loop races it, so the
+                    // stand-down below is prompt wherever we happen to be waiting.
                     if (store.pendingHostCalls.size > 0) {
-                        await Promise.race([...store.pendingHostCalls]).catch(() => { });
+                        await Promise.race([
+                            ...store.pendingHostCalls,
+                            armDriverArrival(store),
+                        ]).catch(() => { });
                         continue;
                     }
                     // Per the issue #156 analysis this is unreachable (a spanning lock
@@ -863,13 +922,49 @@ async function driveAsync(store, done, what) {
                 // await — which takes a fresh entry of its own — had that entry
                 // clobbered early, re-opening the window it exists to close. With a set
                 // we can name exactly what we added.
-                store.addPendingResumption(chosen);
+                //
+                // SOLE DRIVER ONLY, AND ONLY UNTIL ONE ARRIVES (issue #239). The entry
+                // is a claim over a window this loop cannot bound: the race settles when
+                // the HOST answers, which may be never. As a store-wide scheduling gate
+                // (`Store.tick` refuses; every driver yields at its top) that is a wedge
+                // the moment a second driver exists — it spins at the top of its own
+                // loop and dies at the 10,000-hop assert in ~311ms, an internal-bug
+                // detector firing on a perfectly ordinary suspended guest. Two concurrent
+                // export calls with one slow suspending import were enough; the reported
+                // shape was a detached guest task cancelling an in-flight import, which
+                // parks mid-frame with no export call outstanding and leaves the
+                // settlement pump holding this entry.
+                //
+                // What the entry protects — "the engine may run `chosen`'s wasm during
+                // this await" — it protects by refusing OTHER `Store.tick` callers, and
+                // this loop is not one of them while it awaits. The tick callers that
+                // can reach a store mid-race are another `driveAsync` loop and
+                // `HostActivity.pump`'s synchronous drain (exec/host_streams.ts) — the
+                // latter is not gated by driver depth, so scoping the entry to "sole
+                // driver" does hand it a window the entry used to close at depth >= 2.
+                // What holds regardless is the invariant the `driverDepth` note names:
+                // a genuine resumption is preceded by `SuspensionPoint.resume`'s OWN
+                // entry (jspi/bridge.ts, minted before the settle), and every
+                // resumption site here re-checks membership, promise identity and
+                // `dispatchableTail` synchronously — mechanisms (a) and (b), which is
+                // where that note already puts the weight.
+                const sole = storeDriverDepth(store) === 1;
+                if (sole)
+                    store.addPendingResumption(chosen);
                 let winner;
                 try {
-                    winner = await Promise.race([chosenTag, ...others]);
+                    // `armDriverArrival` rides the race for every driver, not just the one
+                    // holding the entry: waking on a new arrival is also how a fallback
+                    // pump reaches its next `done()` — i.e. its stand-down — promptly.
+                    winner = await Promise.race([
+                        chosenTag,
+                        ...others,
+                        armDriverArrival(store),
+                    ]);
                 }
                 finally {
-                    store.removePendingResumption(chosen);
+                    if (sole)
+                        store.removePendingResumption(chosen);
                 }
                 // Resume whichever thread actually settled -- not necessarily the one we
                 // claimed. Resuming only the claimed thread would spin: its promise may
@@ -906,7 +1001,18 @@ async function driveAsync(store, done, what) {
             // not ours — this is genuine, unavoidable nondeterminism at the boundary
             // (the reference has the same freedom in `Store.tick`). Everything
             // *inside* the component stays deterministic per scheduler.ts.
-            await Promise.race([...store.pendingHostCalls]).catch(() => { });
+            //
+            // The driver-arrival one-shot rides here too. This is the routine park of
+            // a quiet guest with a real host call outstanding — no speculative entry
+            // is held, so there is no wedge to break, but a fallback pump parked here
+            // would otherwise not reach its `done()` (i.e. its stand-down) until the
+            // HOST answered, leaving two loops interleaving `serviceSettled`/`tick`
+            // for that whole window. That interleaving is what the `driverDepth` note
+            // above calls out as bad for throughput and blame.
+            await Promise.race([
+                ...store.pendingHostCalls,
+                armDriverArrival(store),
+            ]).catch(() => { });
         }
     }
     finally {
@@ -1626,7 +1732,7 @@ function* liftBody(input) {
  *     (`thread.wait_until(subtask.resolved)`, line 2286), so: `needsJspi`.
  */
 export function createLoweredImport(input) {
-    const { name, ft, opts, hostFn, stats, mode, suspendable } = input;
+    const { name, ft, opts, hostFn, stats, mode, suspendable, deferCancel, abortable, } = input;
     const inst = opts.instance;
     const store = inst.store;
     const computed = flattenFunctype(cabiOptions(opts), ft, "lower");
@@ -1677,22 +1783,42 @@ export function createLoweredImport(input) {
         // definitions.py assigns the callee's `OnCancel` here:
         //   `subtask.on_cancel = callee(on_start, on_resolve, caller = ...)`
         //
-        // A host import is a plain JS function and offers no cancellation
-        // channel — there is nothing to forward a request to. The faithful model
-        // is therefore a handler that *accepts and ignores* the request, which is
-        // exactly what the reference permits: `canon_subtask_cancel` (line 2469)
-        // calls `on_cancel` and then re-checks `subtask.resolved()`; a callee that
-        // declines to cancel promptly leaves the subtask unresolved, and the async
-        // form returns BLOCKED while the sync form waits. The subtask still
-        // resolves normally when the promise settles — cancellation is a request,
-        // not a guarantee.
+        // The `OnCancel` is the CALLEE's to supply: `Store.invoke` takes it back
+        // from the callee it invoked (`on_cancel = f(on_start, on_resolve, caller
+        // = None)`, definitions.py line 572), i.e. the reference expects the
+        // embedding to hand back the cancellation behaviour of whatever it is
+        // hosting. A wasmtime host gets a real one for free — dropping a Rust
+        // future IS cancellation. A JS Promise has no such channel, so polyengine
+        // answers on the host's behalf; amendment A23 makes the DEFAULT answer the
+        // reference's prompt-cancel host (`on_cancel = () => on_resolve(None)`),
+        // installed by the async arm below.
+        //
+        // The no-op assigned HERE is only the placeholder for paths where
+        // `subtask.cancel` is unreachable, so no answer can ever be demanded of
+        // it: an eagerly-resolving callee never mints a subtask handle (the
+        // fast-path return below is a bare state), and a sync-typed import's A1
+        // park never mints one either. It is also the FINAL handler for a
+        // `deferCancel()`-branded import — accept and ignore, the pre-A23
+        // behaviour, now per-declaration.
         //
         // Leaving `on_cancel` null instead made a *legal* `subtask.cancel` crash
         // with an internal AssertionError, which is neither reference behaviour
         // nor a sanctioned incompleteness signal.
         subtask.onCancel = () => { };
+        // A24 (contracts/embedder-api.md §"Functions and async"): a marked import
+        // is handed a fresh `AbortSignal` after its WIT-declared parameters. The
+        // mark controls the SIGNATURE UNCONDITIONALLY — a marked function receives
+        // a signal on every call, including the paths where it can never fire
+        // (sync-typed, eager resolve, `deferCancel`) — so the host's arity is a
+        // property of its declaration, not of how a particular call happened to
+        // go. `new AbortController()` is evaluated only for marked imports, which
+        // keeps bare engine shells with no `AbortController` off this path for the
+        // whole unmarked corpus.
+        const controller = abortable ? new AbortController() : null;
         const args = onStart();
-        const raw = hostFn(...args);
+        const raw = controller === null
+            ? hostFn(...args)
+            : hostFn(...args, controller.signal);
         const toResults = (v) => ft.results.length === 0 ? [] : [v];
         if (isPromiseLike(raw)) {
             if (!opts.async) {
@@ -1817,6 +1943,16 @@ export function createLoweredImport(input) {
             }
             const promise = Promise.resolve(raw).then((v) => {
                 store.pendingHostCalls.delete(promise);
+                // A23: the subtask may already be resolved when the host promise
+                // settles — the discard `onCancel` below resolved it
+                // CANCELLED_BEFORE_RETURNED (the only pre-settle resolver on this
+                // arm). The value has no addressee, and `onResolve` would run
+                // straight into its `state === STARTED` assert ("on_resolve on a
+                // subtask that never started") and park that AssertionError on
+                // `store.hostFailure`, poisoning whatever unrelated embedder call
+                // came next.
+                if (subtask.resolved())
+                    return;
                 try {
                     onResolve(toResults(v));
                 }
@@ -1825,9 +1961,64 @@ export function createLoweredImport(input) {
                 }
             }, (e) => {
                 store.pendingHostCalls.delete(promise);
+                // Same guard, different reason: a rejection of a RENOUNCED call is
+                // not a host failure. The guest cancelled and was told so; surfacing
+                // the rejection would fail an unrelated later call with the error of
+                // an operation nobody is waiting for.
+                if (subtask.resolved())
+                    return;
                 store.hostFailure = e;
             });
             store.pendingHostCalls.add(promise);
+            if (!deferCancel) {
+                // A23 DISCARD (contracts/embedder-api.md §"Functions and async";
+                // polyengine#241) — the reference's prompt-cancel host,
+                // `on_cancel = () => on_resolve(None)` (definitions.py canon_lower's
+                // null branch, line ~2267).
+                //
+                // This runs synchronously inside `canon_subtask_cancel`, which already
+                // set `cancellationRequested` before calling us (the assert in
+                // `onResolve`'s null branch relies on that ordering). `onResolve(null)`
+                // arms the SUBTASK event — a delivery-time thunk — and resolves
+                // CANCELLED_BEFORE_RETURNED, so the built-in's `finish()` tail consumes
+                // the event, `deliverResolve` releases the lenders (the #106 class,
+                // discharged exactly as a RETURNED delivery would), and BOTH cancel
+                // forms return the state without blocking. The null path lowers
+                // nothing, so there is no realloc re-entry from inside a built-in.
+                //
+                // The renounced call can no longer wake the guest, so it must stop
+                // counting as externally-wakeable for the driver's deadlock probe:
+                // deregister it NOW. (The settle continuation above also deletes;
+                // `Set.delete` is idempotent.)
+                subtask.onCancel = () => {
+                    store.pendingHostCalls.delete(promise);
+                    onResolve(null);
+                    if (controller !== null) {
+                        // A24: tell the host its result was discarded, so it can stop the
+                        // underlying operation — clear a timer, abort a fetch, close a
+                        // dial. Reachable only from this arm by construction: a
+                        // `deferCancel()` import never discards, so its signal never
+                        // fires.
+                        //
+                        // Deferred one microtask. This closure runs SYNCHRONOUSLY inside
+                        // `canon_subtask_cancel`, i.e. inside a live guest activation, and
+                        // host abort listeners must not execute there — that is the
+                        // issue-#24 attribution class, plus arbitrary re-entrancy into a
+                        // guest mid-built-in. `Promise.resolve().then`, not
+                        // `queueMicrotask`: the latter does not exist in bare engine
+                        // shells (see jspi/bridge.ts's SENTINEL_TICK note).
+                        //
+                        // The resulting order is: the guest observes
+                        // CANCELLED_BEFORE_RETURNED first, the host observes the abort a
+                        // tick later. Any settlement the abort provokes (typically an
+                        // `AbortError` rejection) arrives at the settle continuation above
+                        // with the subtask already resolved, so it lands on the A23
+                        // resolved-subtask guards and is discarded like any other late
+                        // settlement — never a `store.hostFailure`.
+                        Promise.resolve().then(() => controller.abort());
+                    }
+                };
+            }
         }
         else {
             onResolve(toResults(raw));

package/esm/exec/executor.js

@@ -10,7 +10,7 @@
 //   - component hash verification against plan.component
 import { Trap } from "../cabi/trap.js";
 import { ComponentInstanceState, Store } from "../task/mod.js";
-import { anySuspendingImport, assertModeConsistent, chooseMode, isSuspending, planNeedsSuspension, suspendingImport, trampolineCanBlock, trampolineNeedsSuspension, } from "../jspi/mod.js";
+import { anySuspendingImport, assertModeConsistent, chooseMode, isAbortable, isDeferCancel, isSuspending, planNeedsSuspension, suspendingImport, trampolineCanBlock, trampolineNeedsSuspension, } from "../jspi/mod.js";
 import { loadPlan, PlanError, resourceIndexOfDefined, } from "../plan/loader.js";
 import { CONSTRUCTOR_SYNC_ENTRY, createDtorEntry, createLiftedFunction, createLoweredImport, LiveMemory, newStats, } from "./boundary.js";
 import { createTrampoline, createUnsafeIntrinsic, TranscodeMemory, } from "../intrinsics/mod.js";
@@ -931,6 +931,19 @@ class Executor {
         const ft = this.funcType(decl.type, `import '${label}'`);
         const opts = this.resolveOptions(decl.options);
         const suspendable = isSuspending(value);
+        // A23 (contracts/embedder-api.md §"Functions and async"): does this import
+        // opt out of cancel-discard? Unlike `suspendable` above, this needs no
+        // executor-state detour — the brand is consumed by `createLoweredImport`
+        // itself (it only decides which `onCancel` the lowered import installs, not
+        // whether the CoreFn gets wrapped), so nothing downstream has to read a
+        // brand off a replaced function identity.
+        const deferCancel = isDeferCancel(value);
+        // A24 (same section): does this import want a per-call `AbortSignal`?
+        // Read exactly like `deferCancel` above and for the same reason — the
+        // brand is consumed inside `createLoweredImport`, which mints the
+        // controller and appends the signal itself, so no function identity is
+        // replaced downstream of the read.
+        const abortable_ = isAbortable(value);
         // The Suspending-wrap decision is taken in `importValue`, which sees the
         // trampoline only AFTER `createTrampoline`'s trap-recording wrapper has
         // replaced this function's identity — a brand on the CoreFn would die
@@ -948,6 +961,8 @@ class Executor {
             stats: this.stats,
             mode: this.suspensionMode,
             suspendable,
+            deferCancel,
+            abortable: abortable_,
         });
     }
     /**