@polyengine/runtime 0.5.1 → 0.6.0

package/esm/task/streams.js

@@ -142,7 +142,7 @@ export class GuestBuffer {
         }
         this.progress += vs.length;
     }
-    // --- A21 direct-access byte edges (embedder-api amendment A21, #128) ---
+    // --- direct-access byte edges (embedder-api.md §"Streams and futures" (polyengine#128)) ---
     //
     // `ByteWindow`, implemented for the `stream<u8>` case only. The two methods
     // together are the copy `read`/`write` would have done, split so that the
@@ -184,7 +184,7 @@ function isDirectBuffer(b) {
  * Collapses to definitions.py's `dst_buffer.write(src_buffer.read(n))`
  * whenever neither side is a direct session — which is every guest↔guest,
  * guest↔host-chunk and host-chunk↔host-chunk rendezvous, i.e. everything
- * that existed before A21.
+ * that existed before direct-access byte edge.
  */
 function rendezvousCopy(src, dst, n) {
     const srcDirect = isDirectBuffer(src);
@@ -199,12 +199,12 @@ function rendezvousCopy(src, dst, n) {
         ? src.runDirect(dst, n)
         : dst.runDirect(src, n);
 }
-/** The A21 rejection for a rendezvous of two direct sessions. */
+/** The rejection for a rendezvous of two direct-access sessions. */
 function bothDirectError() {
     return new TypeError("at least one side of a host-to-host rendezvous must use the chunk " +
         "forms: two direct-access sessions cannot rendezvous with each other " +
         "because neither side owns the memory the other would write into " +
-        "(embedder-api amendment A21, polyengine#128)");
+        `(embedder-api.md §"Streams and futures" ("Direct-access byte edges"), polyengine#128)`);
 }
 /**
  * definitions.py `none_or_number_type` (line 1070). Guards the "temporary"
@@ -243,7 +243,7 @@ export class SharedStreamImpl {
      * OUT of a guest table. The receiver — the host, or the destination of a
      * guest-to-guest hop, in which case the immediately following lower fires
      * `onLowered` — may now act on the transferred end. Host wrappers use it to
-     * re-arm their activity (#162, embedder-api amendment A15). Guest-owned
+     * re-arm their activity (#162, contracts/embedder-api.md §"Streams and futures"). Guest-owned
      * objects leave it unset.
      */
     onLifted = null;
@@ -261,9 +261,9 @@ export class SharedStreamImpl {
     pendingOnCopyDone = null;
     /**
      * Observers fired once, when this stream becomes dropped — by EITHER
-     * side, including the A7 teardown walk (`dropSharedForTeardown`). The
+     * side, including the loud component fault teardown walk (`dropSharedForTeardown`). The
      * embedder's producer pump uses this to cancel a producer parked on an
-     * external event (amendment A13's cancellation companion: an
+     * external event (§"Streams and futures"'s cancellation companion: an
      * accept-shaped producer holds a live platform resource while parked,
      * and the reader dropping is its only stop signal). `null` = already
      * fired.
@@ -336,7 +336,7 @@ export class SharedStreamImpl {
             if (this.pendingBuffer.remain() > 0) {
                 if (dstBuffer.remain() > 0) {
                     const n = Math.min(dstBuffer.remain(), this.pendingBuffer.remain());
-                    // A21 seam (#128). `"chunk"` is the reference line verbatim.
+                    // direct-access byte edge seam (#128). `"chunk"` is the reference line verbatim.
                     const pendingIsDirect = isDirectBuffer(this.pendingBuffer);
                     const out = rendezvousCopy(this.pendingBuffer, dstBuffer, n);
                     if (out === "both-direct") {
@@ -374,7 +374,7 @@ export class SharedStreamImpl {
             if (this.pendingBuffer.remain() > 0) {
                 if (srcBuffer.remain() > 0) {
                     const n = Math.min(srcBuffer.remain(), this.pendingBuffer.remain());
-                    // A21 seam (#128). `"chunk"` is the reference line verbatim.
+                    // direct-access byte edge seam (#128). `"chunk"` is the reference line verbatim.
                     const pendingIsDirect = isDirectBuffer(this.pendingBuffer);
                     const out = rendezvousCopy(srcBuffer, this.pendingBuffer, n);
                     if (out === "both-direct") {
@@ -404,7 +404,7 @@ export class SharedStreamImpl {
         }
     }
     /**
-     * A21 (#128): route a rendezvous whose direct session did NOT copy.
+     * direct-access byte edge (#128): route a rendezvous whose direct session did NOT copy.
      *
      * Two outcomes land here, and both share one invariant: the peer's parked
      * operation survives, no event is delivered, and the stream is not dropped
@@ -471,7 +471,7 @@ export class SharedFutureImpl {
      * OUT of a guest table. The receiver — the host, or the destination of a
      * guest-to-guest hop, in which case the immediately following lower fires
      * `onLowered` — may now act on the transferred end. Host wrappers use it to
-     * re-arm their activity (#162, embedder-api amendment A15). Guest-owned
+     * re-arm their activity (#162, contracts/embedder-api.md §"Streams and futures"). Guest-owned
      * objects leave it unset.
      */
     onLifted = null;
@@ -511,9 +511,9 @@ export class SharedFutureImpl {
     pendingOnCopyDone = null;
     /**
      * Observers fired once, when this future becomes dropped — by EITHER side,
-     * including the A7 teardown walk (`dropSharedForTeardown`). Streams grew
-     * this for A13 producer cancellation; futures need it as the release hook
-     * for a host wrapper's activity arm (#162, amendment A15): a guest dropping
+     * including the loud component fault teardown walk (`dropSharedForTeardown`). Streams grew
+     * this for resource stream producer cancellation; futures need it as the release hook
+     * for a host wrapper's activity arm (#162, §"Streams and futures"): a guest dropping
      * its end with no host operation parked, and the `readResult()`
      * already-dropped fast path, both bypass every other close site. `null` =
      * already fired.
@@ -677,8 +677,8 @@ export class WritableFutureEnd extends CopyEnd {
 /**
  * Failures recorded against shared stream/future objects whose peer end died
  * inside a trap-poisoned instance's handle table. The embedder layer consults
- * this to reject host operations loudly (contracts/embedder-api.md amendment
- * A7) instead of letting them hang forever or fake a clean end-of-stream.
+ * this to reject host operations loudly (contracts/embedder-api.md
+ * §"Streams and futures") instead of letting them hang forever or fake a clean end-of-stream.
  */
 const poisonFailures = new WeakMap();
 /** The recorded poisoning failure for a shared stream/future value, if any. */
@@ -732,51 +732,35 @@ export function abandonSharedFuture(shared, reason) {
  * **poisoned** guest instance is retired silently via `resetPending`.
  * Notifying it would queue a phantom event into the corpse's waitables, and
  * a later driving loop servicing it would resume machinery whose instance
- * can no longer be entered (`tick` asserts enterability). Host sentinels are
+ * can no longer be entered (`tick` excludes poisoned instances). Host sentinels are
  * not instances at all, so they are always notified.
  *
- * #100: THE HEALTH TEST IS "POISONED", NOT "`mayEnter === false`". The
- * original test used non-enterability as a proxy for deadness. The proxy is
- * unsound in one direction, and the unsoundness stranded healthy tasks:
- *
- *  * (sound half, #84 audit) a healthy guest peer always parks with
- *    `mayEnter === true`. Every park — the callback ABI's waitable-set wait,
- *    and equally a sync-lowered/JSPI peer blocked inside `finishCopy`'s
- *    SITE 4 via `blockCurrentActivation` — yields the thread out of the
- *    scheduler's enter/leave bracket, and the bracket's `leaveTo` runs on the
- *    way out (task/scheduler.ts `Store.tick` :905-917, task/thread.ts
- *    `Thread.resumeWith` :157-179, whose resume-side
- *    `assert_(mayEnterFrom(null))` would fire otherwise). Blocking inside a
- *    wasm frame does NOT hold the enter bracket.
- *  * (unsound converse) `mayEnter === false` does not imply "poisoned". An
- *    instance that is merely mid-call is also non-enterable, and a CALLER
- *    instance stays non-enterable for the whole duration of a
- *    cross-component (FACT) call into an instance that traps
- *    (`ComponentInstanceState.enterFrom` clears `mayEnter` on the callee's
- *    entering set only, task/mod.ts). A *different*, healthy task of that
- *    caller, parked on an end of a stream/future the trapping callee also
- *    held, was classified dead here and retired silently — stranded, the
- *    exact outcome #66 exists to prevent.
+ * #100: THE HEALTH TEST IS "POISONED", NOT "BUSY". Deadness must be judged
+ * by the poison marker and nothing weaker: any liveness proxy that also
+ * covers a merely mid-call instance is unsound in one direction and strands
+ * healthy tasks. Under such a proxy a caller mid cross-component (FACT) call
+ * into an instance that trapped would drag its *other*, healthy tasks down
+ * with it — one parked on an end of a stream/future the trapping callee also
+ * held would be classified dead here and retired silently, the exact outcome
+ * #66 exists to prevent.
  *
  * So the test consults the poison marker itself. It is per-instance and
- * recorded at the single seam every bracket-break site routes through
+ * recorded at the single seam every poisoning site routes through
  * (`notifyInstancePoisoned`, task/scheduler.ts: exec/boundary.ts `poison`,
  * `Store.tick`, `Thread.resumeWith`, the FACT cross-component catches in
  * intrinsics/fact_calls.ts, and cabi/handles.ts's gated destructor call),
  * and it is recorded *before* the retirement walk runs, so an instance's own
  * parked ends still see it during its own walk. `retiredInstances` is
  * consulted alongside it because the walk is also reachable directly (it is
- * set at walk entry, so the two agree); neither ever contains the synthetic
- * per-instantiation root, which every poison site skips or releases (plan v3
- * amendment 4, `releaseSyntheticRootOnPoison`).
+ * set at walk entry, so the two agree).
  *
  * Why this does not re-open review B2 (phantom events into a corpse): the
  * concern is that a DROPPED event queued onto a waitable of an instance that
  * can never be entered again would be serviced by a later driving loop and
- * resume machinery whose `tick` asserts enterability. "Can never be entered
- * again" is precisely poisoning — a mid-call instance's `mayEnter` is
- * restored by its own `leaveTo` when the call returns, and its parked task
- * then resumes normally and consumes the event. The narrowed predicate
+ * resume machinery `tick` deliberately excludes. "Can never be entered
+ * again" is precisely poisoning — a merely mid-call instance is entirely
+ * ordinary, and its parked task resumes normally and consumes the event.
+ * The narrowed predicate
  * therefore excludes exactly the population B2 is about, and admits only
  * peers that will run again.
  *
@@ -798,8 +782,8 @@ export function dropSharedForTeardown(shared) {
     }
     // The drop observers also fire on the teardown path: a stream producer
     // parked behind a trap-poisoned reader must be cancelled the same as behind
-    // a cleanly-dropped one (A13), and a host wrapper's activity arm must be
-    // released the same way (#162, amendment A15). Both classes carry the
+    // a cleanly-dropped one, and a host wrapper's activity arm must be
+    // released the same way (#162, §"Streams and futures"). Both classes carry the
     // observer machinery, so this is unconditional.
     shared.notifyDropped();
 }
@@ -807,8 +791,9 @@ export function dropSharedForTeardown(shared) {
  * Retire every live stream/future end in a trap-poisoned instance's handle
  * table (#66).
  *
- * Rationale: after a trap breaks the enter/leave bracket, `mayEnter` stays
- * false forever, so no task of this instance can ever rendezvous again. Its
+ * Rationale: a trapped instance is a corpse (polyengine's per-instance
+ * poisoning divergence), so no task of this instance can ever rendezvous
+ * again. Its
  * table's `CopyEnd`s are therefore unreachable-forever — leaving their shared
  * objects live strands the peers: a parked HOST operation never settles (its
  * promise hangs), and a LATER host operation would "succeed" against the
@@ -816,7 +801,7 @@ export function dropSharedForTeardown(shared) {
  * Dropping the shared object now converts both into the spec-shaped DROPPED
  * outcome, and the recorded failure lets the embedder layer brand it.
  *
- * Called from every bracket-break site — exec/boundary.ts `poison()` (the
+ * Called from every poisoning site — exec/boundary.ts `poison()` (the
  * sync-lift path), scheduler.ts `Store.tick` and thread.ts
  * `Thread.resumeWith` (traps during a resumed thread), and the FACT
  * cross-component catches (intrinsics/fact_calls.ts, callee side) — with the
@@ -885,7 +870,7 @@ export function retireInstanceAsyncEnds(inst, cause) {
     if (failed)
         throw first;
 }
-// `Store.tick`'s bracket-break site reaches the walk through this seam (its
+// `Store.tick`'s poisoning site reaches the walk through this seam (its
 // module cannot import ours — see `setOnInstancePoisoned`); the sync-lift
 // site (exec/boundary.ts `poison`) imports it directly.
 setOnInstancePoisoned(retireInstanceAsyncEnds);
@@ -902,7 +887,7 @@ export class ErrorContext {
         this.debugMessage = debugMessage;
     }
 }
-// A9 brand (contracts/embedder-api.md §"Module identity"): error-contexts are
+// module identity brand (contracts/embedder-api.md §"Module identity"): error-contexts are
 // STATEFUL — they live in a component instance's handle table — so the brand
 // exists to make a foreign one diagnosable at the lowering sites, never
 // usable. Both this internal class and the embedder-facing wrapper

package/esm/task/subtask.js

@@ -72,8 +72,8 @@ export class Subtask extends Waitable {
     /**
      * Release a never-delivered subtask's lenders after its call broke off a
      * non-poisoning exit — trap-rethrow past the CALLEE, capability bail, or
-     * an abandoned park (contracts/intrinsics.md v0.2 amendment 2, #91 scope
-     * clarification; the park legs are #102/#106).
+     * an abandoned park (contracts/intrinsics.md §A's trap-unwind/lender-release
+     * obligation; the park legs are #102/#106).
      *
      * The reference has no analogue because it never resumes after a trap:
      * the store dies with the lent handles inside it. The resolution state

package/esm/task/thread.js

@@ -107,64 +107,43 @@ export class Thread {
         this.awaiting = null;
         this.#store.awaiting.delete(this);
         this.#state = "suspended";
-        // The reentrance bracket, exactly as `Store.tick` puts around `resume()`.
+        // Not a bracketed resumption: post-CM#705 (definitions.py @ 2f13265)
+        // `Store.tick` resumes a ready thread with no enter/leave bracket at all,
+        // and this path — the same thread body, woken by a Promise instead of a
+        // ready-condition — matches it.
         //
-        // Every thread resumption in the reference runs under the instance's
-        // entered lock, and a trap propagating out of the resumed thread skips
-        // `leave_to` — which is the Component Model's instance poisoning
-        // (definitions.py `Store.tick` line 597; see the matching comment in
-        // scheduler.ts). This path is a resumption too — the value arrived
-        // through a Promise instead of a ready-condition, but the thread body
-        // (and any wasm it runs) is the same — so it takes the same bracket.
-        // Without it, a trap delivered as an `awaitValue` rejection (how EVERY
-        // guest trap in a suspended activation arrives under jspi, pin (e))
-        // unwound cleanly and the instance stayed enterable: the second call of
-        // `builtin-trap-poisons-instance.wast` then re-ran the guest and
-        // reported "cannot drop busy stream" where the suite demands the
+        // What the catch preserves is polyengine's per-instance poisoning, which
+        // must be MARKER-recorded here specifically: a trap delivered as an
+        // `awaitValue` rejection is how EVERY guest trap in a suspended
+        // activation arrives under jspi (pin (e)), and if it unwound silently the
+        // second call of `builtin-trap-poisons-instance.wast` would re-run the
+        // guest and report "cannot drop busy stream" where the suite demands the
         // poisoned-instance "cannot enter component instance".
         //
-        // Capability signals release the lock, for the same reason as in `tick`:
+        // Capability signals do not poison, for the same reason as in `tick`:
         // they mark the RUNTIME incomplete, not the component faulted.
         const inst = this.task.inst;
         // A poisoned instance's parked segments never run again: this settle
         // belongs to an activation that was in flight when a SIBLING activation
-        // trapped (the trap kept the reentrance lock — CM poisoning — and #66
-        // retired the handle tables). Resuming would re-enter the corpse, and
-        // asserting turned one legible trap into an assert cascade (the
-        // wosh-M2 shape: `list too long`, then this assert as second victim).
-        // Retire quietly: the abandoned call's own driver reports, via its
-        // deadlock trap naming the export.
+        // trapped (#66 retired the handle tables). Resuming would re-enter the
+        // corpse, and asserting turned one legible trap into an assert cascade
+        // (the classic double-fault shape: `list too long`, then this assert as second
+        // victim). Retire quietly: the abandoned call's own driver reports, via
+        // its deadlock trap naming the export.
         if (isInstancePoisoned(inst))
             return;
-        // The enterability check below is an internal BACKSTOP, not a live gate:
-        // every dispatch site (`Store.serviceSettled`, `driveAsync`'s race-winner
-        // path) now guards enterable-or-poisoned before calling and DEFERS the
-        // tail otherwise (issue #156) — under the shared synthetic root, a host
-        // entry into any instance of the graph makes every sibling
-        // non-enterable, so this assert was reachable, and (mutating before
-        // asserting) it stranded the thread and lost the settle. It stays to
-        // protect the invariant for any future caller.
-        assert_(inst.mayEnterFrom(null), "resumeWith: parked thread's instance is not enterable from the host");
-        inst.enterFrom(null);
         try {
             this.#resumeInternal(value, failure);
         }
         catch (e) {
-            if (e instanceof NeedsJspi || e instanceof PendingCapability) {
-                inst.leaveTo(null);
-            }
-            else {
-                // The bracket stays broken (instance poisoned, comment above) — same
-                // as `Store.tick`: retire the poisoned table's stream/future ends so
-                // parked host peers settle instead of hanging (#66), and release the
-                // synthetic root so the poisoning stays per-instance (plan v3
-                // amendment 4; `releaseSyntheticRootOnPoison`).
-                inst.releaseSyntheticRootOnPoison();
+            if (!(e instanceof NeedsJspi) && !(e instanceof PendingCapability)) {
+                // Retire the poisoned table's stream/future ends so parked host peers
+                // settle instead of hanging (#66), and record the marker — the whole
+                // entry-refusal mechanism since #251's re-key.
                 notifyInstancePoisoned(inst, e);
             }
             throw e;
         }
-        inst.leaveTo(null);
     }
     resume(cancelled = CANCELLED_FALSE) {
         assert_(!this.running() && !this.done(), "resume() on a running or finished thread");

package/esm/task/waitable.js

@@ -13,7 +13,6 @@ export var EventCode;
     EventCode[EventCode["FUTURE_WRITE"] = 5] = "FUTURE_WRITE";
     EventCode[EventCode["TASK_CANCELLED"] = 6] = "TASK_CANCELLED";
 })(EventCode || (EventCode = {}));
-export const NO_EVENT = [EventCode.NONE, 0, 0];
 /**
  * definitions.py `class Waitable` (line 767).
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyengine/runtime",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "A WebAssembly Component Model host for JavaScript engines: plan executor, canonical ABI, 0.3 task scheduler, JSPI bridge, and embedder API.",
   "homepage": "https://github.com/polymorph-components/polyengine#readme",
   "repository": {
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@polyengine/protocol": "^0.2.3"
+    "@polyengine/protocol": "^0.3.0"
   },
   "_generatedBy": "dnt@0.43.2"
 }

package/types/cabi/async_values.d.ts

@@ -2,8 +2,9 @@ import type { LiftLowerContext } from "./context.js";
 import type { BorrowType, OwnType, ValType } from "./types.js";
 import { ErrorContext, type SharedBase } from "../task/streams.js";
 /**
- * Diagnostic for a handle-table entry that carries the A9 error-context brand
- * without being one of THIS copy's `ErrorContext`s (amendment A9, issue #83).
+ * Diagnostic for a handle-table entry that carries the error-context brand
+ * without being one of THIS copy's `ErrorContext`s (contracts/embedder-api.md
+ * §"Module identity").
  *
  * A backstop, deliberately: the embedder's lowering site (embedder/values.ts)
  * refuses a foreign error-context before it can ever reach a handle table, so

package/types/cabi/bulk_lists.d.ts

@@ -1,8 +1,6 @@
 import { type MemInst } from "./memory.js";
 import type { ComponentValue } from "./types.js";
 export declare const PLATFORM_LITTLE_ENDIAN: boolean;
-/** Kinds these helpers handle (besides them, u8 has its own path). */
-export declare function isBulkListKind(kind: string): boolean;
 /**
  * Bulk lift of `length` elements of `kind` at `ptr`. Returns `null` when the
  * kind is not handled here (caller falls back to the per-element loop) —

package/types/cabi/context.d.ts

@@ -23,13 +23,24 @@ export declare function mkCanonicalOptions(partial?: Partial<CanonicalOptions>):
 export declare function requireMemory(opts: LiftOptions): MemInst;
 /**
  * Minimal component-instance stand-in for the value interpreter: a handle
- * table plus the `may_leave` gate. The full ComponentInstance (may_enter,
- * backpressure, threads, ...) belongs to the deferred task machinery.
+ * table plus the `may_leave` gate. The full ComponentInstance (backpressure,
+ * threads, ...) belongs to the task machinery, which cabi must not import.
  */
 export interface ComponentInstanceLike {
     handles: Table<unknown>;
     mayLeave: boolean;
 }
+/**
+ * Brand marking a value as a REAL component instance (task/mod.ts
+ * `ComponentInstanceState`), as opposed to the many structural
+ * `ComponentInstanceLike` stand-ins — imported/host resources carry no
+ * instance at all, and test harnesses supply bare `{handles, mayLeave}`
+ * doubles. cabi must not depend on task/, so the symbol lives here and
+ * `ComponentInstanceState` declares it; cabi/handles.ts `isComponentInstance`
+ * is the only reader. `ComponentInstanceLike` stays deliberately structural:
+ * the brand is NOT part of it.
+ */
+export declare const COMPONENT_INSTANCE: unique symbol;
 /**
  * Borrow scopes (definitions.py `LiftLowerContext.borrow_scope`):
  * - lifting a borrow requires the *subtask* side: `add_lender`.
@@ -53,9 +64,8 @@ export declare class LiftLowerContext {
      * with `may_leave` cleared, so a realloc that lowers an import traps
      * (`canon_lower`'s `trap_if(not ...may_leave)`, implemented here by
      * exec/boundary.ts `createLoweredImport`). That bracket is implemented
-     * below. What remains deferred is only the reference's routing of the call
-     * through `canon_lift`; upstream component-model PR #705 removes that
-     * routing, leaving this bracket as the whole story. polyengine issue #147.
+     * below, and it is the whole story: the pinned reference does not route
+     * the call through `canon_lift` (CM#705). polyengine issue #147.
      */
     reallocate(old: number, oldByteLength: number, alignment: number, newByteLength: number): number;
     allocate(alignment: number, byteLength: number): number;

package/types/cabi/flatten.d.ts

@@ -2,11 +2,11 @@ import { type CaseType, type CoreFuncType, type CoreType, type FieldType, type F
 import type { CanonicalOptions, LiftOptions } from "./context.js";
 export declare const MAX_FLAT_PARAMS = 16;
 export declare const MAX_FLAT_ASYNC_PARAMS = 4;
-export declare let MAX_FLAT_RESULTS: number;
-export declare function setMaxFlatResultsForTesting(n: number): number;
+export declare const MAX_FLAT_RESULTS = 1;
 export type FlattenContext = "lift" | "lower";
 export declare function flattenFunctype(opts: CanonicalOptions, ft: FuncType, context: FlattenContext): CoreFuncType;
 export declare function flattenTypes(ts: ValType[], opts: LiftOptions): CoreType[];
+export declare function flatCount(ts: ValType[], opts: LiftOptions): number;
 export declare function flattenType(t: ValType, opts: LiftOptions): CoreType[];
 export declare function flattenList(elemType: ValType, maybeLength: number | null, opts: LiftOptions): CoreType[];
 export declare function flattenRecord(fields: FieldType[], opts: LiftOptions): CoreType[];

package/types/cabi/handles.d.ts

@@ -23,11 +23,8 @@ export declare function lowerOwn(cx: LiftLowerContext, rep: number, t: OwnType):
 export declare function lowerBorrow(cx: LiftLowerContext, rep: number, t: BorrowType): number;
 export declare function canonResourceNew(inst: ComponentInstanceLike, rt: ResourceTypeInfo, rep: number): number;
 /**
- * Invoke a resource destructor through the reference's entry bracket.
- *
- * definitions.py `canon_resource_drop` (line 2319) does not call `rt.dtor`
- * directly. It builds the dtor into a function instance and calls it through
- * `Store.lift` / `Store.lower` (lines 2330-2333):
+ * Invoke a resource destructor, as definitions.py `canon_resource_drop`
+ * (@ 2f13265) does — through `Store.lift`/`Store.lower`:
  *
  * ```python
  *   dtor = rt.dtor or (lambda rep: [])
@@ -36,34 +33,26 @@ export declare function canonResourceNew(inst: ComponentInstanceLike, rt: Resour
  *   caller([h.rep])
  * ```
  *
- * so the dtor inherits `Store.lift`'s gate verbatim (lines 579-584):
- * `trap_if(not inst.may_enter_from(caller))`, `enter_from(caller)`, the call,
- * then `leave_to(caller)` — which a trap skips, leaving the *implementing*
- * instance permanently unenterable (poisoned).
- *
- * Two consequences that are easy to get wrong, both taken from the reference
- * rather than from intuition:
+ * That lift carries NO gate (CM#705): dropping a handle whose implementing
+ * instance is mid-execution is VALID, including the dtor-less case.
  *
- *  - the bracket runs even when `rt.dtor is None` (the `or (lambda rep: [])`
- *    above), so a dtor-less resource whose impl instance is mid-execution is
- *    still a trap. `may_enter_from`/`enter_from` walk `entering_set(caller)`
- *    (line 230), which is empty when the caller *is* the implementing
- *    instance — that, not a special case, is the same-instance exemption:
- *    a component dropping a handle to its own resource never traps.
- *  - poisoning applies to `rt.impl`, not to the dropping instance. The
- *    dropper's own bracket (its `Store.lift` frame) is broken by the same
- *    propagating trap at its own level; here only the callee is retired.
+ * What this adds is polyengine's per-instance poisoning divergence, and it
+ * applies to `rt.impl`, not to the dropping instance: a trap out of the dtor
+ * buries the implementing instance (refusal names the original trap,
+ * polyengine#145; its live stream/future ends are retired, #66). The
+ * dropper is poisoned, if at all, by the same trap propagating at its own
+ * level. `entryRefusal`'s `caller !== callee` guard keeps a component
+ * dropping a handle to its OWN resource admissible even against a marked
+ * instance.
  *
  * Capability signals (`NeedsJspi`, `PendingCapability`) are not traps — see
- * `isCapabilitySignal` in exec/boundary.ts — so they release the gate.
+ * `isCapabilitySignal` in exec/boundary.ts — so they do not poison.
  *
  * SCOPE (#160): this is the **guest-initiated** path only. A guest-initiated
  * drop must complete synchronously (the reference lifts the dtor with
  * `async_ = False`), so a thenable here is a trap. The host-initiated path
- * used to share this function with an `allowAsync` flag that held the entry
- * bracket across the dtor's promise; it now goes through the full lift
- * harness instead (`hostDtorCall` in exec/boundary.ts), which is what
- * definitions.py actually does and what unwedges #160.
+ * goes through the full lift harness instead (`hostDtorCall` in
+ * exec/boundary.ts), which is what definitions.py actually does.
  */
 export declare function callDtorGated(rt: ResourceTypeInfo, rep: number, caller: unknown): void;
 export declare function canonResourceDrop(inst: ComponentInstanceLike, rt: ResourceTypeInfo, i: number): void;

package/types/cabi/layout.d.ts

@@ -1,5 +1,26 @@
-import { type CaseType, type FieldType, type PtrType, type ValType } from "./types.js";
+import { type CaseType, type DespecializedValType, type FieldType, type PtrType, type ValType } from "./types.js";
 export declare function alignTo(ptr: number, alignment: number): number;
+/**
+ * Everything the lift/lower paths need to know about one type's byte layout,
+ * computed once and shared (issue #261).
+ *
+ * Deliberately ONE flat interface rather than a discriminated union of
+ * per-kind layouts: every `Layout` then has the same hidden class, so the hot
+ * property loads in `load`/`store` stay monomorphic. Fields that do not apply
+ * to a kind carry null/0 — please do not "improve" this into a union.
+ */
+export interface Layout {
+    /** The despecialized type (definitions.py `despecialize`). */
+    readonly d: DespecializedValType;
+    readonly align: number;
+    readonly size: number;
+    /** record: field i occupies `base + fieldOffsets[i]`; null otherwise. */
+    readonly fieldOffsets: readonly number[] | null;
+    /** variant: discriminant width, and the offset of the case payload; 0 otherwise. */
+    readonly discSize: 0 | 1 | 2 | 4;
+    readonly payloadOffset: number;
+}
+export declare function layoutOf(t: ValType, ptrType: PtrType): Layout;
 export declare function alignment(t: ValType, ptrType: PtrType): number;
 export declare function alignmentList(elemType: ValType, maybeLength: number | null, ptrType: PtrType): number;
 export declare function alignmentRecord(fields: FieldType[], ptrType: PtrType): number;

package/types/cabi/load.d.ts

@@ -6,8 +6,16 @@ export declare function convertIntToBool(i: number): boolean;
 export declare function loadList(cx: LiftLowerContext, ptr: number, elemType: ValType, maybeLength: number | null): ComponentValue;
 export declare function loadListFromRange(cx: LiftLowerContext, ptr: number | bigint, length: number | bigint, elemType: ValType): ComponentValue;
 export declare function loadListFromValidRange(cx: LiftLowerContext, ptr: number, length: number, elemType: ValType): ComponentValue;
-export declare function loadRecord(cx: LiftLowerContext, ptr: number, fields: FieldType[]): ComponentValue;
-export declare function loadVariant(cx: LiftLowerContext, ptr: number, cases: CaseType[]): ComponentValue;
+/**
+ * `offsets[i]` is field i's byte offset from `ptr`, precomputed on the layout
+ * node, so the loop is an indexed read rather than the per-field
+ * `alignTo`/`alignment`/`elemSize` recomputation it used to be (issue #261).
+ * Taking the offsets rather than the whole `Layout` keeps the function
+ * self-consistent: its two arguments are the ones the result depends on, and
+ * there is no unchecked "these came from the same type" invariant to violate.
+ */
+export declare function loadRecord(cx: LiftLowerContext, ptr: number, fields: FieldType[], offsets: readonly number[]): ComponentValue;
+export declare function loadVariant(cx: LiftLowerContext, ptr: number, cases: CaseType[], discSize: 1 | 2 | 4, payloadOffset: number): ComponentValue;
 export declare function loadFlags(cx: LiftLowerContext, ptr: number, labels: string[]): ComponentValue;
 export declare function unpackFlagsFromInt(i: number, labels: string[]): {
     [label: string]: ComponentValue;

package/types/cabi/store.d.ts

@@ -4,9 +4,11 @@ export declare function store(cx: LiftLowerContext, v: ComponentValue, t: ValTyp
 export declare function storeList(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, ptr: number, elemType: ValType, maybeLength: number | null): void;
 export declare function storeListIntoRange(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, elemType: ValType): [number, number];
 export declare function storeListIntoValidRange(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, ptr: number, elemType: ValType): void;
-export declare function storeRecord(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, fields: FieldType[]): void;
+/** The store-side mirror of `loadRecord`: indexed offset writes, no per-field
+ * layout recomputation (issue #261). */
+export declare function storeRecord(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, fields: FieldType[], offsets: readonly number[]): void;
 /** definitions.py match_case: the value is a single-key object. */
 export declare function matchCase(v: Record<string, ComponentValue>, cases: CaseType[]): [number, ComponentValue];
-export declare function storeVariant(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, cases: CaseType[]): void;
+export declare function storeVariant(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, cases: CaseType[], discSize: 1 | 2 | 4, payloadOffset: number): void;
 export declare function storeFlags(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, labels: string[]): void;
 export declare function packFlagsIntoInt(v: Record<string, ComponentValue>, labels: string[]): number;

package/types/cabi/types.d.ts

@@ -176,14 +176,33 @@ export type ComponentValue = AsyncValue | boolean | number | bigint | string | n
 export type CoreValue = number | bigint;
 export type DespecializedValType = Exclude<ValType, TupleType | EnumType | OptionType | ResultType | MapType>;
 export declare function despecialize(t: ValType): DespecializedValType;
+/**
+ * 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 declare function discriminantSize(caseCount: number): 1 | 2 | 4;
+/**
+ * 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 declare function discriminantType(cases: CaseType[]): PrimType;
+export declare function caseIndexOf(cases: CaseType[]): ReadonlyMap<string, number>;
 export declare function containsBorrow(t: ValType | null): boolean;
-export declare function containsAsyncValue(t: ValType | null): boolean;
 export declare function contains(t: ValType | null, p: (t: DespecializedValType) => boolean): boolean;
 /**
  * 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
@@ -191,7 +210,7 @@ export declare function contains(t: ValType | null, p: (t: DespecializedValType)
  * 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/types/digest/mod.d.ts

@@ -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