@polyengine/runtime 0.1.0-pre.g633468a

package/esm/embedder/copy.js

@@ -0,0 +1,42 @@
+// This runtime copy's identity (contracts/embedder-api.md §"Module identity
+// and @polyengine/protocol", amendment A9; issue #83).
+//
+// One module owns the copy's URL so every diagnostic composes the same
+// message, and so lowering sites deep in the value adapters can name the copy
+// without threading it through their signatures.
+//
+// `import.meta.url` is the identity: it is what distinguishes the source
+// checkout from a bundled `polyengine-embedder.mjs`, and two bundles from each
+// other. It is stable per module instance and needs no permissions (unlike
+// reading deno.json, which embedder paths must never do — no fs perms).
+import { copyCensus } from "@polyengine/protocol";
+/** The URL of this copy of the runtime. Identity of the copy. */
+export const COPY_URL = import.meta.url;
+/**
+ * The `@polyengine/runtime` version this copy was built from, recorded in the copy
+ * registry alongside the URL.
+ *
+ * Hardcoded on purpose: embedder code paths run without filesystem
+ * permissions (and a browser bundle has no filesystem at all), so reading
+ * `runtime/deno.json` at runtime is not an option.
+ *
+ * INVARIANT: keep in sync with `version` in runtime/deno.json — pinned by
+ * runtime/tests/embedder/cross_copy_test.ts.
+ */
+export const RUNTIME_VERSION = "0.1.0";
+/**
+ * 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.
+ *
+ * Kept to one line but complete — the whole point of A9's stateful half is
+ * that "recognized but foreign" is a NAMED failure, never a silent
+ * adaptation (a foreign `Stream` pumped as an async iterable) and never a
+ * misleading generic ("handle is not an error-context").
+ */
+export function describeCrossCopy(what, remedy) {
+    const census = copyCensus();
+    return `${what} was minted by a DIFFERENT polyengine runtime copy and cannot ` +
+        `be used through this one (this copy: ${COPY_URL}${census === "" ? "" : `; ${census}`}). Handles are stateful — their machinery lives in the copy that minted ` +
+        `them (contracts/embedder-api.md amendment A9, issue #83)` +
+        `${remedy === undefined ? "" : `. ${remedy}`}`;
+}

package/esm/embedder/errors.js

@@ -0,0 +1,26 @@
+// The embedder-facing error model (contracts/embedder-api.md §"Error model").
+//
+// The canonical definitions live in `@polyengine/protocol` since amendment A9 —
+// this module is the unchanged import path for them (every existing
+// `from "./errors.ts"` / `@polyengine/runtime/embedder` import keeps working) plus
+// the runtime-local `NameCollisionError`, which never crosses a copy boundary
+// (it is raised while BUILDING a facade, before any value exists) and
+// therefore carries no brand: the A9 table's omissions are deliberate.
+//
+// Recognition at the runtime's own boundaries is by BRAND, not class: use the
+// `is*` predicates re-exported below, never `instanceof`, for any value that
+// arrives from embedder code (issue #83).
+export { DroppedError, InvalidHandleError, isDroppedError, isInvalidHandleError, isPeerTrappedError, isStreamProducerError, isTrap, isComponentException, PeerTrappedError, Trap, ComponentException, } from "@polyengine/protocol";
+/**
+ * Two WIT labels in one scope camelCase to the same JS name.
+ *
+ * A footgun is a design defect (contract principle 2): silently letting one
+ * field/flag/function shadow another would corrupt values at the boundary with
+ * no diagnostic anywhere. Refused at facade build instead.
+ */
+export class NameCollisionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NameCollisionError";
+    }
+}

package/esm/embedder/imports.js

@@ -0,0 +1,63 @@
+// `requiredImports()` — the supported enumeration of a component's linkable
+// import leaves (contracts/embedder-api.md §"Module wiring and
+// instantiation"; C2 checklist item 2).
+//
+// C0 finding #8: `plan.imports` proved the right authority, and every embedder
+// that needed it hand-rolled the same walk (tools/smoke-c0/wasi_stub.ts).
+// Blessing it removes that. It is also this layer's own input: the facade
+// builds its import wrappers from exactly this list.
+import { loadPlan } from "../plan/loader.js";
+import { camelCase, parseLeafName, pascalCase } from "./casing.js";
+function toLoaded(input) {
+    if ("wire" in input && "types" in input)
+        return input;
+    const wire = "plan" in input ? input.plan : input;
+    return loadPlan(wire);
+}
+/** Enumerate the component's linkable import leaves. */
+export function requiredImports(input) {
+    const loaded = toLoaded(input);
+    return loaded.wire.imports.map((imp) => {
+        const leaf = imp.path.length === 0
+            ? imp.name
+            : imp.path[imp.path.length - 1];
+        const member = parseLeafName(leaf);
+        const out = {
+            interfaceId: imp.name,
+            path: [...imp.path],
+            leaf,
+            kind: imp.kind,
+            member,
+            jsName: jsNameOf(member, imp.kind),
+        };
+        if (member.form !== "plain")
+            out.jsClass = pascalCase(member.resource);
+        if (imp.type !== undefined) {
+            const t = loaded.types[imp.type];
+            if (t !== undefined && t.kind === "func") {
+                out.type = {
+                    params: t.funcType.params.map((p, i) => ({
+                        name: t.paramNames[i] ?? String(i),
+                        type: p,
+                    })),
+                    results: t.funcType.results,
+                    async: t.funcType.async === true,
+                };
+            }
+        }
+        return out;
+    });
+}
+function jsNameOf(member, kind) {
+    switch (member.form) {
+        case "plain":
+            return kind === "resource"
+                ? pascalCase(member.name)
+                : camelCase(member.name);
+        case "constructor":
+            return "constructor";
+        case "method":
+        case "static":
+            return camelCase(member.member);
+    }
+}