@polyengine/runtime 0.1.0-pre.g633468a

package/esm/embedder/mod.js

@@ -0,0 +1,40 @@
+// Embedder conventions layer (contracts/embedder-api.md; docs/milestones.md C2 / docs/consumers.md).
+//
+// The host-facing surface: camelCase facades, resource classes on both sides,
+// stream/future handles, version-canonical import resolution and the branded
+// error model — all built at instantiate time from the plan's type tables, so
+// the layer works fully untyped. Bindgen (a separate track) emits compile-time
+// types that cast this facade; no generated code participates.
+// Copy registration (contracts/embedder-api.md §"Module identity and
+// @polyengine/protocol", amendment A9; issue #83). Runs at module evaluation, so
+// merely importing the embedder surface puts this copy on the census — which
+// is what makes every cross-copy diagnostic below able to name both sides.
+// Multiple copies are DIAGNOSED, NEVER REFUSED: two isolated bundles on one
+// page that exchange no values are legal.
+import { PROTOCOL_GENERATION, registerRuntimeCopy } from "@polyengine/protocol";
+import { COPY_URL, RUNTIME_VERSION } from "./copy.js";
+registerRuntimeCopy({
+    // `COPY_URL` (embedder/copy.ts) rather than this module's own
+    // `import.meta.url`, so the census and every cross-copy message name the
+    // copy identically — one module owns the identity.
+    url: COPY_URL,
+    runtimeVersion: RUNTIME_VERSION,
+    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, DROPPED, ERROR_CONTEXT, FUTURE, hasBrand, INVALID_HANDLE, isDroppedError, isInvalidHandleError, isPeerTrappedError, isStreamProducerError, isSuspending, isTrap, isComponentException, PEER_TRAPPED, PROTOCOL_GENERATION, registerRuntimeCopy, RESOURCE_STATE, runtimeCopies, STREAM, STREAM_PRODUCER, SUSPENDING, TRAP, COMPONENT_EXCEPTION, } from "@polyengine/protocol";
+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";
+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/resources.js

@@ -0,0 +1,406 @@
+// Resources as classes on both sides of the boundary
+// (contracts/embedder-api.md §"Resources"; C2 checklist item 3).
+//
+// The raw boundary represents `own<R>` / `borrow<R>` as bare **reps**
+// (cabi/handles.ts `liftOwn` returns `rh.rep`; the host never holds a table
+// index). C0 findings 1-3 were embedders turning that into identity tables and
+// hand-transcribed `[method]…` keys by hand. Both become runtime obligations
+// here.
+//
+// Ownership, per the contract's 2x4 table:
+//
+// | position                | guest-implemented R          | host-implemented R        |
+// | host receives own<R>    | new wrapper (host owns)      | instance back, mapping released, NO dispose |
+// | host receives borrow<R> | wrapper valid for the call   | instance, mapping kept    |
+// | host passes own<R>      | wrapper invalidated          | instance registered       |
+// | host passes borrow<R>   | wrapper stays valid          | rep reused/allocated      |
+import { RESOURCE_STATE } from "@polyengine/protocol";
+import { hostDtorCall } from "../exec/boundary.js";
+import { COPY_URL, describeCrossCopy } from "./copy.js";
+import { InvalidHandleError } from "./errors.js";
+import { camelCase, pascalCase } from "./casing.js";
+/**
+ * Internal state of a guest-resource wrapper.
+ *
+ * The KEY is the process-global `polyengine.resourceState/1` brand since amendment
+ * A9 (it used to be a module-local `Symbol(...)`, on the now-repealed
+ * assumption that bundle and source runtimes are never mixed in one process —
+ * issue #83 showed they routinely are). The state SHAPE stays strictly
+ * runtime-internal, exactly as the A9 brand table notes: another copy may
+ * RECOGNIZE a wrapper, and must never read or write this object. `copyUrl` is
+ * what lets this copy tell its own wrappers from a foreign copy's.
+ */
+const STATE = RESOURCE_STATE;
+/** Base of every runtime-built guest-resource class. */
+export class GuestResource {
+    /** Drop the handle (alias of `[Symbol.dispose]`, so TS `using` works). */
+    drop() {
+        dropWrapper(this);
+    }
+    [Symbol.dispose]() {
+        dropWrapper(this);
+    }
+}
+/**
+ * Backstop for leaked handles (docs/architecture.md §7). A wrapper that becomes unreachable
+ * without `drop()` still runs the guest destructor — late, but not never.
+ */
+const runBackstop = (s) => {
+    // Idempotence: `valid` is the single guard. A wrapper that was dropped,
+    // transferred, or invalidated already cleared it (and unregistered), so the
+    // backstop can neither double-run a dtor nor resurrect a dead rep.
+    if (!s.valid || !s.owns)
+        return;
+    s.valid = false;
+    if (s.lends > 0) {
+        // A live guest borrow of this rep is outstanding (#86). Running the dtor
+        // now is exactly the use-after-free the reference forbids
+        // (definitions.py line 2325, `trap_if(h.num_lends != 0)`); the last
+        // `releaseLend` runs it instead. The closure held by the lowering scope
+        // keeps `s` alive, so the deferred drop is not lost with the wrapper.
+        s.pendingDrop = true;
+        return;
+    }
+    runHostDrop(s);
+};
+const leaked = new FinalizationRegistry(runBackstop);
+/**
+ * Simulate the GC backstop firing for `w` (the FinalizationRegistry callback,
+ * verbatim). Test seam: real GC finalization is unschedulable, and #86 is
+ * precisely about what the backstop does in a window a test must control.
+ *
+ * @internal
+ */
+export function simulateFinalizationForTest(w) {
+    const s = wrapperState(w);
+    if (s !== undefined)
+        runBackstop(s);
+}
+/**
+ * Run a host-initiated drop of a guest `own` handle.
+ *
+ * The host holds a rep, never a table index, so there is nothing to remove
+ * from a handle table: the observable remainder of definitions.py
+ * `canon_resource_drop` for an owning handle is the lifted dtor call
+ * (`hostDtorCall`, exec/boundary.ts), with `caller = None` — a host-initiated
+ * call, `Store.invoke`'s `caller = None`.
+ *
+ * Never throws: the two callers are `drop()`/`[Symbol.dispose]()` — where a
+ * trap *is* reportable, so it propagates — and the FinalizationRegistry
+ * callback, where a throw would be swallowed by the engine with no
+ * diagnostic. `runHostDrop` is the latter's form: a trapping dtor poisons the
+ * implementing instance (which the lift harness does) and is additionally
+ * recorded on the store's host-failure channel, so the next driven call
+ * surfaces it instead of silently continuing on a half-destroyed instance
+ * (#86, second defect: the former `catch {}`).
+ */
+function runHostDrop(s) {
+    try {
+        hostDtorCall(s.rt, s.rep);
+    }
+    catch (e) {
+        recordHostFailure(s.rt, e);
+    }
+}
+/** Park a failure that has no frame to propagate into on the store. */
+function recordHostFailure(rt, e) {
+    const store = rt.impl?.store;
+    if (store !== undefined && store.hostFailure === undefined) {
+        store.hostFailure = e;
+    }
+}
+export function initWrapper(w, state) {
+    state.copyUrl ??= COPY_URL;
+    w[STATE] = state;
+    if (state.owns)
+        leaked.register(w, state, w);
+}
+/**
+ * This copy's state for a wrapper, or `undefined`.
+ *
+ * A wrapper minted by ANOTHER copy carries the same (process-global) brand key
+ * but its state belongs to that copy — reading it here would be reading a
+ * foreign copy's private shape (A9). So it is not a state: it is
+ * `undefined` here, and `requireLive` turns that into the named cross-copy
+ * error rather than a misleading "not a resource handle" / "not live".
+ */
+export function wrapperState(w) {
+    const s = w[STATE];
+    if (s === undefined)
+        return undefined;
+    return s.copyUrl === COPY_URL ? s : undefined;
+}
+/**
+ * True iff `w` carries the A9 resource-state key but is not one of ours.
+ *
+ * Note the resource brand is the odd one out in the A9 table: its value is the
+ * state OBJECT, not `true`, so `hasBrand` does not apply — presence of the key
+ * is the recognition. Only meaningful once `wrapperState` has returned
+ * `undefined`, i.e. presence here means "another copy's wrapper".
+ */
+function isForeignWrapper(w) {
+    return w[STATE] !== undefined;
+}
+function requireLive(w, what) {
+    const s = wrapperState(w);
+    if (s === undefined) {
+        if (isForeignWrapper(w)) {
+            throw new InvalidHandleError(`${what}: ${describeCrossCopy("this resource handle", "Resource wrappers hold a rep in the minting copy's tables; there " +
+                "is no by-value form — call through the copy that created it.")}`);
+        }
+        throw new InvalidHandleError(`${what}: not a resource handle`);
+    }
+    if (!s.valid) {
+        throw new InvalidHandleError(`${what}: this ${s.className} handle is no longer valid (it was ` +
+            `transferred as own<…>, dropped, or was a borrow that outlived its ` +
+            `call)`);
+    }
+    return s;
+}
+function dropWrapper(w) {
+    const s = wrapperState(w);
+    if (s === undefined || !s.valid)
+        return;
+    s.valid = false;
+    leaked.unregister(w);
+    if (!s.owns)
+        return; // a borrow was never ours to drop
+    if (s.lends > 0) {
+        // Lent out to an in-flight guest call (#86): defer rather than destroy a
+        // rep the guest still holds a `borrow` of. `drop(): void` stays
+        // non-blocking either way — the deferred dtor runs from `releaseLend`.
+        s.pendingDrop = true;
+        return;
+    }
+    // The dtor runs as an ordinary LIFTED sync call (`hostDtorCall`, #160):
+    // definitions.py `canon_resource_drop` (line 2319) lifts it with
+    // `CanonicalOptions(async_ = False)` rather than calling it bare, and that
+    // is what gives the activation a Task/Thread. A dtor that suspends (a
+    // `promising`-entered dtor calling a `Suspending` import,
+    // docs/architecture.md §7) therefore releases the implementing instance's
+    // entry bracket at its first park, so the scheduler can resume it — the
+    // old held-bracket form wedged exactly there (#160).
+    //
+    // `drop(): void` stays non-blocking: an unfinished dtor's tail is driven
+    // by the store like any other parked activation, and a failure that has no
+    // frame to return into is parked on `store.hostFailure`.
+    hostDtorCall(s.rt, s.rep);
+}
+/**
+ * Record that a host-held `own` wrapper was lowered as `borrow<R>` into a
+ * guest call, and return the (idempotent) release for the end of that call.
+ *
+ * definitions.py: `lift_borrow` -> `Subtask.add_lender` (line 890) on the way
+ * in, `Subtask.deliver_resolve` (line 902) on the way out.
+ */
+export function lendWrapper(w) {
+    const s = wrapperState(w);
+    if (s === undefined)
+        return () => { };
+    s.lends += 1;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        releaseLend(s);
+    };
+}
+function releaseLend(s) {
+    s.lends -= 1;
+    if (s.lends > 0 || !s.pendingDrop)
+        return;
+    s.pendingDrop = false;
+    // The drop that arrived while the handle was lent. `valid` is already
+    // false (both deferral sites clear it first), so nothing can race this.
+    runHostDrop(s);
+}
+/** Host-side `num_lends` — diagnostics and white-box tests. */
+export function wrapperLends(w) {
+    return wrapperState(w)?.lends ?? 0;
+}
+/** Invalidate a wrapper without dropping (used to end a borrow's lifetime). */
+export function invalidateWrapper(w) {
+    const s = wrapperState(w);
+    if (s === undefined)
+        return;
+    s.valid = false;
+    leaked.unregister(w);
+}
+/** Read a wrapper's rep for a lowering site, applying the ownership rule. */
+export function takeRep(w, own, what) {
+    if (typeof w !== "object" || w === null) {
+        throw new InvalidHandleError(`${what}: expected a resource class instance, got ${typeof w}`);
+    }
+    const s = requireLive(w, what);
+    if (own) {
+        // definitions.py `lift_own` (line 1508): `trap_if(h.num_lends != 0)`. A
+        // handle currently lent to an in-flight call cannot be transferred away.
+        if (s.lends > 0) {
+            throw new InvalidHandleError(`${what}: this ${s.className} handle is still lent out as a borrow ` +
+                `to an in-flight call and cannot be transferred`);
+        }
+        // Transfer: the wrapper is invalidated, and must NOT run the destructor.
+        s.valid = false;
+        leaked.unregister(w);
+    }
+    return s.rep;
+}
+/**
+ * Build the class for a guest-implemented resource.
+ *
+ * The JS constructor is **synchronous**: a JS constructor cannot return a
+ * Promise, so the contract's "exports are uniformly Promise-shaped" rule has
+ * one unavoidable exception here. A guest constructor that does not complete
+ * synchronously is reported as such rather than silently returning a
+ * half-built object (see the report's contract-friction list).
+ */
+export function buildGuestResourceClass(spec, rt, adapt, lowerArgs) {
+    const className = pascalCase(spec.name);
+    const cls = class extends GuestResource {
+        constructor(...args) {
+            super();
+            if (spec.ctor === null) {
+                throw new TypeError(`${className} has no WIT constructor; use its static functions`);
+            }
+            const where = `${className} constructor`;
+            const lowered = lowerArgs(args, spec.ctorParams ?? [], where);
+            const rep = spec.ctor(...lowered);
+            if (rep !== null && typeof rep === "object" && "then" in rep) {
+                throw new TypeError(`${where}: the guest constructor did not complete synchronously. ` +
+                    `A JS constructor cannot await; expose an async factory instead.`);
+            }
+            if (typeof rep !== "number") {
+                throw new TypeError(`${where}: expected an own handle rep, got ${typeof rep}`);
+            }
+            initWrapper(this, {
+                rep,
+                valid: true,
+                owns: true,
+                rt,
+                className,
+                lends: 0,
+                pendingDrop: false,
+            });
+        }
+    };
+    Object.defineProperty(cls, "name", { value: className });
+    for (const m of spec.methods) {
+        const js = camelCase(m.member);
+        const where = `${className}.${js}`;
+        Object.defineProperty(cls.prototype, js, {
+            configurable: true,
+            writable: true,
+            value: function (...args) {
+                // params[0] is the `borrow<R>`/`own<R>` self.
+                return adapt(m.raw, m.params, m.results, where, [this, ...args]);
+            },
+        });
+    }
+    for (const s of spec.statics) {
+        const js = camelCase(s.member);
+        const where = `${className}.${js} (static)`;
+        Object.defineProperty(cls, js, {
+            configurable: true,
+            writable: true,
+            value: (...args) => adapt(s.raw, s.params, s.results, where, args),
+        });
+    }
+    return cls;
+}
+/** Materialize an `own`/`borrow` wrapper for a rep coming out of a guest. */
+export function makeWrapper(
+// deno-lint-ignore no-explicit-any
+cls, rep, rt, owns) {
+    const w = Object.create(cls.prototype);
+    initWrapper(w, {
+        rep,
+        valid: true,
+        owns,
+        rt,
+        className: cls.name ?? "resource",
+        lends: 0,
+        pendingDrop: false,
+    });
+    return w;
+}
+// ---------------------------------------------------------------------------
+// Host-implemented resources
+// ---------------------------------------------------------------------------
+/**
+ * Runtime-owned instance <-> rep mapping for a host-implemented resource.
+ *
+ * The rep->instance direction is a **strong** map for exactly as long as the
+ * guest holds handles: the guest's handle is the only reference keeping a
+ * host object alive across calls, and a weak map here would let it be
+ * collected under the guest's feet.
+ */
+export class HostResourceRegistry {
+    className;
+    #byRep = new Map();
+    #byInstance = new WeakMap();
+    #next = 1;
+    constructor(className) {
+        this.className = className;
+    }
+    /** The host is passing an instance to the guest: allocate (or reuse) a rep. */
+    repFor(instance) {
+        if (instance === null || typeof instance !== "object") {
+            throw new TypeError(`${this.className}: expected a class instance, got ${typeof instance}`);
+        }
+        const held = this.#byInstance.get(instance);
+        if (held !== undefined && this.#byRep.has(held))
+            return held;
+        const rep = this.#next++;
+        this.#byRep.set(rep, instance);
+        this.#byInstance.set(instance, rep);
+        return rep;
+    }
+    /** Is this instance already registered with a live rep? */
+    hasInstance(instance) {
+        if (instance === null || typeof instance !== "object")
+            return false;
+        const held = this.#byInstance.get(instance);
+        return held !== undefined && this.#byRep.has(held);
+    }
+    /** Is `rep` live? Diagnostics and white-box tests. */
+    hasRep(rep) {
+        return this.#byRep.has(rep);
+    }
+    /** Release a rep if it is still live; no dtor, no error when already gone. */
+    releaseIfPresent(rep) {
+        this.#byRep.delete(rep);
+    }
+    /** A `borrow<R>` arrived from the guest: the host's own instance, mapping kept. */
+    lookup(rep) {
+        const inst = this.#byRep.get(rep);
+        if (inst === undefined) {
+            throw new InvalidHandleError(`${this.className}: no live instance for rep ${rep}`);
+        }
+        return inst;
+    }
+    /**
+     * An `own<R>` arrived from the guest: the host gets its instance back, the
+     * guest's handle is gone, and **no dispose runs** (the contract's 2x4 table).
+     */
+    release(rep) {
+        const inst = this.lookup(rep);
+        this.#byRep.delete(rep);
+        return inst;
+    }
+    /**
+     * The guest dropped its last own handle: run the destructor. This is the
+     * `HostResourceType` dtor the executor calls from `canon_resource_drop`.
+     */
+    dtor(rep) {
+        const inst = this.#byRep.get(rep);
+        if (inst === undefined)
+            return;
+        this.#byRep.delete(rep);
+        inst[Symbol.dispose]?.();
+    }
+    /** Live handle count — diagnostics and tests. */
+    get liveCount() {
+        return this.#byRep.size;
+    }
+}