@polyengine/runtime 0.1.0-pre.g633468a → 0.2.0-pre.g2125a06

package/README.md

@@ -12,10 +12,10 @@ npm install @polyengine/runtime
 ```
 
 ```js
-import * as api from "@polyengine/runtime/cabi";
+import * as api from "@polyengine/runtime/cache";
 ```
 
-Entry points: `./cabi`, `./cache`, `./digest`, `./embedder`, `./exec`, `./intrinsics`, `./jspi`, `./plan`, `./shim`, `./task`.
+Entry points: `./cache`, `./digest`, `./embedder`, `./plan`, `./shim`.
 
 ESM only, Node >= 22.14. Documentation, examples and the embedder API contract
 live in the [repository](https://github.com/polymorph-components/polyengine).

package/esm/cache/core.js

@@ -57,7 +57,10 @@ import { loadEnvelope, PlanError, TranslateError } from "../plan/loader.js";
  * unwritable (issue #196): the eviction attempt that a layout mismatch
  * triggers is swallowed internally by the backend, so a read-only
  * pre-warmed cache from an older layout degrades to "always miss, always
- * re-translate" rather than throwing. */
+ * re-translate" rather than throwing.
+ *
+ * @internal — on-disk/on-Cache-API schema version, owned by the bundled
+ * cache backends. */
 export const CACHE_LAYOUT_VERSION = 1;
 async function sha256Hex(bytes) {
     const digest = await crypto.subtle.digest("SHA-256", bytes.slice().buffer);

package/esm/digest/digest.js

@@ -36,14 +36,19 @@
 // (each has 0 or 1 resource types), but a world with 2+ resources throws a
 // clearly-labeled `DigestError` rather than silently guessing.
 // cewd = component-engine world digest, the project's pre-rebrand name; kept as an opaque wire constant.
+/** @internal */
 export const CEWD_VERSION = 1;
+/** @internal */
 export class DigestError extends Error {
     constructor(message) {
         super(message);
         this.name = "DigestError";
     }
 }
-/** Compute the canonical world digest from a loaded wire plan. */
+/**
+ * Compute the canonical world digest from a loaded wire plan.
+ * @internal
+ */
 export async function computeWorldDigest(plan) {
     const resourceNames = buildResourceNameMap(plan);
     const imports = plan.imports.map((imp) => canonImport(plan, imp, resourceNames));
@@ -314,6 +319,7 @@ function sortByName(items) {
  * Recursively sort object keys (alphabetically) and serialize with no extra
  * whitespace. Array order is preserved verbatim — this must match
  * `crates/bindgen/src/digest.rs::canonical_string` byte-for-byte.
+ * @internal
  */
 export function canonicalStringify(v) {
     return JSON.stringify(sortKeysDeep(v));

package/esm/digest/mod.js

@@ -1,3 +1,27 @@
-// Runtime digest handshake — public surface (docs/architecture.md §9).
+/**
+ * The world-digest handshake (CEWD, docs/architecture.md §9): computing a
+ * canonical digest over a component's world types, and verifying generated
+ * bindings against the component they are used with.
+ *
+ * **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
+ * should hand-write an import of this module.
+ *
+ * **Its contents are completely unstable: there is no compatibility promise
+ * of any kind, including within a minor line.** This is an explicit
+ * carve-out from the caret-honest versioning policy in README.md
+ * §"Consuming", which otherwise promises backward compatibility within a
+ * minor line — every symbol here may be renamed, reshaped, or removed in
+ * any release, including a patch. Regenerate your bindings when you bump
+ * the runtime.
+ *
+ * The supported host-facing surface is `@polyengine/runtime/embedder`
+ * (contracts/embedder-api.md).
+ *
+ * @module
+ */
+// Runtime digest handshake — package entry point (docs/architecture.md §9).
 export * from "./digest.js";
 export * from "./verify.js";

package/esm/digest/verify.js

@@ -12,6 +12,7 @@ import { computeWorldDigest } from "./digest.js";
  *
  * Named and catchable: `err instanceof WorldDigestMismatchError`, or
  * `err.name === "WorldDigestMismatchError"` across realms.
+ * @internal
  */
 export class WorldDigestMismatchError extends Error {
     name = "WorldDigestMismatchError";
@@ -43,6 +44,7 @@ export class WorldDigestMismatchError extends Error {
  * constant bindgen embedded at generation time). Returns `null` on match,
  * or a `DigestMismatch` report naming the first divergent path on
  * mismatch.
+ * @internal
  */
 export async function verifyWorldDigest(plan, expectedDigest) {
     const actual = await computeWorldDigest(plan);
@@ -60,6 +62,7 @@ export async function verifyWorldDigest(plan, expectedDigest) {
  * trees in parallel to name the first divergent import/export/type path.
  * `expectedCanonicalJson` is normally produced by `crates/bindgen`'s
  * `digest --json` output, or by `computeWorldDigest` on a reference plan.
+ * @internal
  */
 export async function diffWorldDigest(plan, expectedCanonicalJson) {
     const actual = await computeWorldDigest(plan);

package/esm/embedder/casing.js

@@ -16,12 +16,19 @@
  *
  * WIT labels are already lower-kebab in practice, so the first fragment needs
  * no adjustment; nothing here lower-cases anything.
+ * @internal — the runtime applies the naming rules; embedders write the
+ * resulting JS names literally (contracts/embedder-api.md §"Naming and
+ * casing").
  */
 export function camelCase(label) {
     const parts = label.split("-");
     return parts[0] + parts.slice(1).map(upperFirst).join("");
 }
-/** `tcp-socket` -> `TcpSocket` (resource class names). */
+/**
+ * `tcp-socket` -> `TcpSocket` (resource class names).
+ * @internal — the runtime applies the naming rules; embedders write the
+ * resulting class names literally.
+ */
 export function pascalCase(label) {
     return label.split("-").map(upperFirst).join("");
 }
@@ -29,7 +36,11 @@ function upperFirst(s) {
     return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
 }
 const MANGLED = /^\[([a-z-]+)\](.*)$/;
-/** Decode a mangled leaf name; unmangled names come back as `plain`. */
+/**
+ * Decode a mangled leaf name; unmangled names come back as `plain`.
+ * @internal — leaf-name demangling, performed by the runtime and by
+ * bindgen-generated code.
+ */
 export function parseLeafName(raw) {
     const m = MANGLED.exec(raw);
     if (m === null)

package/esm/embedder/copy.js

@@ -10,7 +10,11 @@
 // 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. */
+/**
+ * The URL of this copy of the runtime. Identity of the copy.
+ * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
+ * host-facing.
+ */
 export const COPY_URL = import.meta.url;
 /**
  * The `@polyengine/runtime` version this copy was built from, recorded in the copy
@@ -22,8 +26,10 @@ export const COPY_URL = import.meta.url;
  *
  * INVARIANT: keep in sync with `version` in runtime/deno.json — pinned by
  * runtime/tests/embedder/cross_copy_test.ts.
+ * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
+ * host-facing.
  */
-export const RUNTIME_VERSION = "0.1.0";
+export const RUNTIME_VERSION = "0.2.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.

package/esm/embedder/instantiate.js

@@ -54,6 +54,8 @@ export function artifactsFromEnvelope(envelopeJson, componentBytes) {
  * world-digest handshake (contracts/digest.md) must complete before any
  * guest code runs: generated `instantiate` wrappers call this, verify the
  * plan, and only then delegate to `instantiate` below.
+ * @internal — bindgen-generated code only — the digest handshake needs the
+ * plan before instantiating (amendment A17).
  */
 export async function resolveArtifacts(src) {
     if ("plan" in src)
@@ -102,7 +104,11 @@ export async function instantiate(source, imports = {}, opts = {}) {
     });
     return instance;
 }
-/** Alias matching the C2 dispatch's spelling. */
+/**
+ * Alias matching the C2 dispatch's spelling.
+ * @internal — alias kept for bindgen-generated code only; hosts call
+ * `instantiate`.
+ */
 export const instantiateEmbedder = instantiate;
 /**
  * Symbol-keyed, deliberately NOT re-exported from `mod.ts`: the

package/esm/embedder/resources.js

@@ -334,6 +334,8 @@ cls, rep, rt, owns) {
  * 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.
+ * @internal — runtime-owned instance<->rep mapping; hosts supply a class, not
+ * a registry.
  */
 export class HostResourceRegistry {
     className;

package/esm/embedder/values.js

@@ -28,6 +28,9 @@ import { ErrorContext, Future, lowerFutureSource, lowerStreamSource, Stream, } f
  * Wrappers materialized for `borrow<R>` arguments of one call. The contract:
  * "instance valid **only during the call** (retention throws)", so the scope
  * invalidates them when the call returns.
+ *
+ * @internal — the runtime materializes and invalidates these per call; a
+ * host never constructs or names one.
  */
 export class BorrowScope {
     #invalidate = [];
@@ -82,6 +85,8 @@ export function checkNoCollisions(key, labels, what) {
  * option** boxes as `{ kind: "some", value } | { kind: "none" }`. Only option maps
  * to `undefined`, so this is the only ambiguity, and the flag is set only when
  * descending through an option's payload — every other constructor resets it.
+ * @internal — value-adapter internals; the facade adapts values at the
+ * boundary.
  */
 export function toHost(v, t, o, scope = NO_BORROWS, inOption = false) {
     switch (t.kind) {
@@ -203,6 +208,10 @@ function single(v, o) {
 // ---------------------------------------------------------------------------
 // conventions -> internal
 // ---------------------------------------------------------------------------
+/**
+ * @internal — value-adapter internals; the facade adapts values at the
+ * boundary.
+ */
 export function fromHost(v, t, o, inOption = false) {
     switch (t.kind) {
         case "bool":

package/esm/embedder/version.js

@@ -36,6 +36,7 @@ const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))
  *
  * Last, not first: a package name may not contain `@`, but being explicit
  * costs nothing and matches how wasmtime splits (`name.rfind('@')`).
+ * @internal — version-resolution internals.
  */
 export function parseInterfaceId(id) {
     const at = id.lastIndexOf("@");
@@ -45,6 +46,7 @@ export function parseInterfaceId(id) {
     const version = id.slice(at + 1);
     return { base, version, semver: parseSemver(version) };
 }
+/** @internal — version-resolution internals. */
 export function parseSemver(v) {
     const m = SEMVER.exec(v);
     if (m === null)
@@ -74,6 +76,7 @@ export function parseSemver(v) {
  *
  * Build metadata is ignored for track purposes (`2.1.2+abc` -> `@2`), as
  * semver requires.
+ * @internal — version-resolution internals.
  */
 export function trackKey(id) {
     const p = parseInterfaceId(id);
@@ -96,6 +99,7 @@ function trackKeyOf(base, v) {
  * Note `semver::Version::parse("0.2")` fails — which is exactly why the two
  * mechanisms compose: a track key can never be mistaken for a full version,
  * and a full version never generates a track key equal to itself.
+ * @internal — version-resolution internals.
  */
 export function asTrackKeySpelling(id) {
     const p = parseInterfaceId(id);
@@ -115,6 +119,8 @@ export function asTrackKeySpelling(id) {
  * Only the *interface-id* keys participate: world-level bare imports live at
  * the record's top level under camelCase names and are matched by exact
  * string equality, never by version machinery.
+ * @internal — built by `instantiate` from the embedder's plain imports
+ * record; hosts never construct one.
  */
 export class ImportResolver {
     #exact = new Map();
@@ -236,7 +242,10 @@ export class ImportResolver {
         return undefined;
     }
 }
-/** Semver precedence, prerelease-aware (semver.org §11). */
+/**
+ * Semver precedence, prerelease-aware (semver.org §11).
+ * @internal — version-resolution internals.
+ */
 export function compareSemver(a, b) {
     if (a.major !== b.major)
         return a.major - b.major;

package/esm/plan/loader.js

@@ -11,7 +11,10 @@
 //   - own/borrow `resource: <table index>` (wire) -> `ResourceTypeInfo`
 //     identity tokens created per resource table at load time
 import { ResourceTypeInfo, } from "../cabi/types.js";
-/** Fault in the plan document itself (version/shape/reference errors). */
+/**
+ * Fault in the plan document itself (version/shape/reference errors).
+ * @internal
+ */
 export class PlanError extends Error {
     constructor(message) {
         super(message);
@@ -26,6 +29,7 @@ export class PlanError extends Error {
  * component* and is the only failure that satisfies `assert_invalid` /
  * `assert_malformed`. `PlanError` and the other phases are failures of our
  * own pipeline and must never be scored as conformance passes.
+ * @internal
  */
 export class TranslateError extends Error {
     phase;
@@ -60,11 +64,13 @@ export class TranslateError extends Error {
  * producer and consumer bumped in the same commit), so v0 plans are refused
  * rather than best-effort accepted — a stale cached artifact must be a loud
  * failure, not a subtly different execution.
+ * @internal
  */
 export const SUPPORTED_FORMAT_VERSION = 4;
 /**
  * Validate a plan document and convert its type tables. Fails fast on
  * formatVersion mismatch per contracts/plan-format.md "Executor obligations".
+ * @internal
  */
 export function loadPlan(wire) {
     if (wire.formatVersion !== SUPPORTED_FORMAT_VERSION) {
@@ -206,6 +212,7 @@ export function loadPlan(wire) {
  * field of a `resource` initializer). Mirrors wasmtime
  * `Component::resource_index` (wasmtime-environ 47.0.3
  * `component/info.rs:222`).
+ * @internal
  */
 export function resourceIndexOfDefined(plan, definedIndex) {
     return plan.numImportedResources + definedIndex;
@@ -215,6 +222,7 @@ export function resourceIndexOfDefined(plan, definedIndex) {
  * bytes. The plan is validated (formatVersion, type tables) but returned in
  * wire form: the executor re-runs `loadPlan` per instantiation so resource
  * identity tokens are fresh per component instance.
+ * @internal
  */
 export function loadEnvelope(json) {
     let envelope;
@@ -559,6 +567,7 @@ function loadTypeDecl(t, resourceTokens, where) {
         type: loadValType(t, resourceTokens, where),
     };
 }
+/** @internal */
 export function loadValType(t, resourceTokens, where) {
     switch (t.kind) {
         case "bool":

package/esm/plan/mod.js

@@ -1,3 +1,26 @@
+/**
+ * The translation plan: the wire descriptor IR emitted by the translator
+ * (`Wire*` types, contracts/plan-format.md) plus the loader that validates
+ * it and converts it into the runtime's in-memory type model.
+ *
+ * **This is not embedder API.** The entry point exists as a support surface
+ * for bindgen-generated bindings and for the runtime's own internals, which
+ * import from it directly. No host program should hand-write an import of
+ * this module.
+ *
+ * **Its contents are completely unstable: there is no compatibility promise
+ * of any kind, including within a minor line.** This is an explicit
+ * carve-out from the caret-honest versioning policy in README.md
+ * §"Consuming", which otherwise promises backward compatibility within a
+ * minor line — every symbol here may be renamed, reshaped, or removed in
+ * any release, including a patch. Regenerate your bindings when you bump
+ * the runtime.
+ *
+ * The supported host-facing surface is `@polyengine/runtime/embedder`
+ * (contracts/embedder-api.md).
+ *
+ * @module
+ */
 // Plan format + loader (contracts/plan-format.md v0).
 export * from "./format.js";
 export * from "./loader.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyengine/runtime",
-  "version": "0.1.0-pre.g633468a",
+  "version": "0.2.0-pre.g2125a06",
   "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": {
@@ -11,15 +11,9 @@
   "bugs": {
     "url": "https://github.com/polymorph-components/polyengine/issues"
   },
-  "module": "./esm/cabi/mod.js",
-  "types": "./types/cabi/mod.d.ts",
+  "module": "./esm/cache/mod.js",
+  "types": "./types/cache/mod.d.ts",
   "exports": {
-    "./cabi": {
-      "import": {
-        "types": "./types/cabi/mod.d.ts",
-        "default": "./esm/cabi/mod.js"
-      }
-    },
     "./cache": {
       "import": {
         "types": "./types/cache/mod.d.ts",
@@ -32,18 +26,6 @@
         "default": "./esm/plan/mod.js"
       }
     },
-    "./task": {
-      "import": {
-        "types": "./types/task/mod.d.ts",
-        "default": "./esm/task/mod.js"
-      }
-    },
-    "./exec": {
-      "import": {
-        "types": "./types/exec/mod.d.ts",
-        "default": "./esm/exec/mod.js"
-      }
-    },
     "./embedder": {
       "import": {
         "types": "./types/embedder/mod.d.ts",
@@ -56,24 +38,12 @@
         "default": "./esm/digest/mod.js"
       }
     },
-    "./intrinsics": {
-      "import": {
-        "types": "./types/intrinsics/mod.d.ts",
-        "default": "./esm/intrinsics/mod.js"
-      }
-    },
     "./shim": {
       "import": {
         "types": "./types/shim/mod.d.ts",
         "default": "./esm/shim/mod.js"
       }
     },
-    "./jspi": {
-      "import": {
-        "types": "./types/jspi/mod.d.ts",
-        "default": "./esm/jspi/mod.js"
-      }
-    },
     "./package.json": "./package.json"
   },
   "scripts": {},
@@ -85,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@polyengine/protocol": "0.1.0-pre.g633468a"
+    "@polyengine/protocol": "0.2.0-pre.g2125a06"
   },
   "_generatedBy": "dnt@0.43.2"
 }

package/types/cache/core.d.ts

@@ -16,7 +16,10 @@ export interface TranslatorLike {
  * unwritable (issue #196): the eviction attempt that a layout mismatch
  * triggers is swallowed internally by the backend, so a read-only
  * pre-warmed cache from an older layout degrades to "always miss, always
- * re-translate" rather than throwing. */
+ * re-translate" rather than throwing.
+ *
+ * @internal — on-disk/on-Cache-API schema version, owned by the bundled
+ * cache backends. */
 export declare const CACHE_LAYOUT_VERSION = 1;
 /** The three-part identity a translation is content-addressed by. */
 export interface CacheKey {
@@ -47,7 +50,10 @@ export interface ArtifactCache {
      * internally on a failed integrity check during `get`. */
     evict(key: CacheKey): Promise<void>;
 }
-/** On-disk / on-Cache-API metadata envelope stored alongside the plan. */
+/**
+ * On-disk / on-Cache-API metadata envelope stored alongside the plan.
+ * @internal — the cache backends' own stored metadata envelope.
+ */
 export interface CacheMeta {
     layoutVersion: number;
     componentSha256: string;

package/types/digest/digest.d.ts

@@ -1,17 +1,24 @@
 import type { WirePlan } from "../plan/format.js";
+/** @internal */
 export declare const CEWD_VERSION = 1;
+/** @internal */
 export declare class DigestError extends Error {
     constructor(message: string);
 }
+/** @internal */
 export interface WorldDigestResult {
     canonicalJson: string;
     digest: string;
 }
-/** Compute the canonical world digest from a loaded wire plan. */
+/**
+ * Compute the canonical world digest from a loaded wire plan.
+ * @internal
+ */
 export declare function computeWorldDigest(plan: WirePlan): Promise<WorldDigestResult>;
 /**
  * Recursively sort object keys (alphabetically) and serialize with no extra
  * whitespace. Array order is preserved verbatim — this must match
  * `crates/bindgen/src/digest.rs::canonical_string` byte-for-byte.
+ * @internal
  */
 export declare function canonicalStringify(v: unknown): string;

package/types/digest/mod.d.ts

@@ -1,2 +1,26 @@
+/**
+ * The world-digest handshake (CEWD, docs/architecture.md §9): computing a
+ * canonical digest over a component's world types, and verifying generated
+ * bindings against the component they are used with.
+ *
+ * **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
+ * should hand-write an import of this module.
+ *
+ * **Its contents are completely unstable: there is no compatibility promise
+ * of any kind, including within a minor line.** This is an explicit
+ * carve-out from the caret-honest versioning policy in README.md
+ * §"Consuming", which otherwise promises backward compatibility within a
+ * minor line — every symbol here may be renamed, reshaped, or removed in
+ * any release, including a patch. Regenerate your bindings when you bump
+ * the runtime.
+ *
+ * The supported host-facing surface is `@polyengine/runtime/embedder`
+ * (contracts/embedder-api.md).
+ *
+ * @module
+ */
 export * from "./digest.js";
 export * from "./verify.js";

package/types/digest/verify.d.ts

@@ -1,4 +1,5 @@
 import type { WirePlan } from "../plan/format.js";
+/** @internal */
 export interface DigestMismatch {
     expected: string;
     actual: string;
@@ -18,6 +19,7 @@ export interface DigestMismatch {
  *
  * Named and catchable: `err instanceof WorldDigestMismatchError`, or
  * `err.name === "WorldDigestMismatchError"` across realms.
+ * @internal
  */
 export declare class WorldDigestMismatchError extends Error {
     readonly name = "WorldDigestMismatchError";
@@ -36,6 +38,7 @@ export declare class WorldDigestMismatchError extends Error {
  * constant bindgen embedded at generation time). Returns `null` on match,
  * or a `DigestMismatch` report naming the first divergent path on
  * mismatch.
+ * @internal
  */
 export declare function verifyWorldDigest(plan: WirePlan, expectedDigest: string): Promise<DigestMismatch | null>;
 /**
@@ -44,5 +47,6 @@ export declare function verifyWorldDigest(plan: WirePlan, expectedDigest: string
  * trees in parallel to name the first divergent import/export/type path.
  * `expectedCanonicalJson` is normally produced by `crates/bindgen`'s
  * `digest --json` output, or by `computeWorldDigest` on a reference plan.
+ * @internal
  */
 export declare function diffWorldDigest(plan: WirePlan, expectedCanonicalJson: string): Promise<DigestMismatch | null>;

package/types/embedder/casing.d.ts

@@ -9,9 +9,16 @@
  *
  * WIT labels are already lower-kebab in practice, so the first fragment needs
  * no adjustment; nothing here lower-cases anything.
+ * @internal — the runtime applies the naming rules; embedders write the
+ * resulting JS names literally (contracts/embedder-api.md §"Naming and
+ * casing").
  */
 export declare function camelCase(label: string): string;
-/** `tcp-socket` -> `TcpSocket` (resource class names). */
+/**
+ * `tcp-socket` -> `TcpSocket` (resource class names).
+ * @internal — the runtime applies the naming rules; embedders write the
+ * resulting class names literally.
+ */
 export declare function pascalCase(label: string): string;
 /**
  * A leaf name in `plan.exports` / `plan.imports`, decoded.
@@ -36,5 +43,9 @@ export type LeafName = {
     resource: string;
     member: string;
 };
-/** Decode a mangled leaf name; unmangled names come back as `plain`. */
+/**
+ * Decode a mangled leaf name; unmangled names come back as `plain`.
+ * @internal — leaf-name demangling, performed by the runtime and by
+ * bindgen-generated code.
+ */
 export declare function parseLeafName(raw: string): LeafName;

package/types/embedder/copy.d.ts

@@ -1,4 +1,8 @@
-/** The URL of this copy of the runtime. Identity of the copy. */
+/**
+ * The URL of this copy of the runtime. Identity of the copy.
+ * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
+ * host-facing.
+ */
 export declare const COPY_URL: string;
 /**
  * The `@polyengine/runtime` version this copy was built from, recorded in the copy
@@ -10,8 +14,10 @@ export declare const COPY_URL: string;
  *
  * INVARIANT: keep in sync with `version` in runtime/deno.json — pinned by
  * runtime/tests/embedder/cross_copy_test.ts.
+ * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
+ * host-facing.
  */
-export declare const RUNTIME_VERSION = "0.1.0";
+export declare const RUNTIME_VERSION = "0.2.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.

package/types/embedder/instantiate.d.ts

@@ -47,6 +47,8 @@ export declare function artifactsFromEnvelope(envelopeJson: string, componentByt
  * world-digest handshake (contracts/digest.md) must complete before any
  * guest code runs: generated `instantiate` wrappers call this, verify the
  * plan, and only then delegate to `instantiate` below.
+ * @internal — bindgen-generated code only — the digest handshake needs the
+ * plan before instantiating (amendment A17).
  */
 export declare function resolveArtifacts(src: InstantiateSource): Promise<ComponentArtifacts>;
 export interface EmbedderOptions {
@@ -77,7 +79,11 @@ export interface EmbedderInstance {
  * resolution (see `version.ts`).
  */
 export declare function instantiate(source: InstantiateSource, imports?: Record<string, unknown>, opts?: EmbedderOptions): Promise<EmbedderInstance>;
-/** Alias matching the C2 dispatch's spelling. */
+/**
+ * Alias matching the C2 dispatch's spelling.
+ * @internal — alias kept for bindgen-generated code only; hosts call
+ * `instantiate`.
+ */
 export declare const instantiateEmbedder: typeof instantiate;
 /**
  * Symbol-keyed, deliberately NOT re-exported from `mod.ts`: the

package/types/embedder/resources.d.ts

@@ -127,6 +127,8 @@ export declare function makeWrapper(cls: any, rep: number, rt: ResourceTypeInfo,
  * 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.
+ * @internal — runtime-owned instance<->rep mapping; hosts supply a class, not
+ * a registry.
  */
 export declare class HostResourceRegistry {
     #private;

package/types/embedder/streams.d.ts

@@ -4,7 +4,10 @@ import { type HostFuture, type HostStream } from "../exec/host_streams.js";
 import { ErrorContext as InternalErrorContext } from "../task/mod.js";
 /** `Chunk<u8>` is a `Uint8Array`; every other element type chunks as `T[]`. */
 export type Chunk<T> = T extends number ? Uint8Array | T[] : T[];
-/** Per-element adaptation, supplied by the value adapter. */
+/**
+ * Per-element adaptation, supplied by the value adapter.
+ * @internal — supplied by the value adapter, never by a host.
+ */
 export interface ElemCodec<T> {
     readonly element: ValType | null;
     /** internal component value -> conventions value */

package/types/embedder/values.d.ts

@@ -2,6 +2,8 @@ import type { ComponentValue, ValType } from "../cabi/types.js";
 /**
  * The parts of adaptation that need instance state: resources (identity
  * mapping, ownership) and the borrow scope of the call in flight.
+ * @internal — value-adapter wiring, supplied by the runtime's instance
+ * state.
  */
 export interface ValueBridge {
     /** A guest handed the host an `own<R>`; the host now owns it. */
@@ -35,6 +37,9 @@ export interface ValueBridge {
  * Wrappers materialized for `borrow<R>` arguments of one call. The contract:
  * "instance valid **only during the call** (retention throws)", so the scope
  * invalidates them when the call returns.
+ *
+ * @internal — the runtime materializes and invalidates these per call; a
+ * host never constructs or names one.
  */
 export declare class BorrowScope {
     #private;
@@ -51,6 +56,7 @@ export declare const NO_BORROWS: BorrowScope;
  * no diagnostic anywhere. Contract principle 2: footguns are design defects.
  */
 export declare function checkNoCollisions(key: object, labels: string[], what: string): void;
+/** @internal — value-adapter wiring. */
 export interface AdapterOptions {
     bridge: ValueBridge;
     /** Names the site in error messages (`import 'wasi:x/y'.f`, param 2). */
@@ -64,7 +70,13 @@ export interface AdapterOptions {
  * option** boxes as `{ kind: "some", value } | { kind: "none" }`. Only option maps
  * to `undefined`, so this is the only ambiguity, and the flag is set only when
  * descending through an option's payload — every other constructor resets it.
+ * @internal — value-adapter internals; the facade adapts values at the
+ * boundary.
  */
 export declare function toHost(v: ComponentValue, t: ValType, o: AdapterOptions, scope?: BorrowScope, inOption?: boolean): unknown;
+/**
+ * @internal — value-adapter internals; the facade adapts values at the
+ * boundary.
+ */
 export declare function fromHost(v: unknown, t: ValType, o: AdapterOptions, inOption?: boolean): ComponentValue;
 export declare function describe(v: unknown): string;

package/types/embedder/version.d.ts

@@ -6,7 +6,11 @@ export declare class ImportRegistrationError extends Error {
 export declare class ImportResolutionError extends Error {
     constructor(message: string);
 }
-/** A parsed `name@version` interface id. `version` is null when unversioned. */
+/**
+ * A parsed `name@version` interface id. `version` is null when unversioned.
+ * @internal — interface-id parsing internals; embedders write ids, the
+ * runtime parses them.
+ */
 export interface ParsedId {
     /** The id with the version suffix removed (`wasi:clocks/monotonic-clock`). */
     base: string;
@@ -15,6 +19,10 @@ export interface ParsedId {
     /** Parsed semver, or null when unversioned / unparseable. */
     semver: Semver | null;
 }
+/**
+ * @internal — version-resolution internals; §"Version canonicalization" of
+ * contracts/embedder-api.md is implemented here, not called by hosts.
+ */
 export interface Semver {
     major: number;
     minor: number;
@@ -28,8 +36,10 @@ export interface Semver {
  *
  * Last, not first: a package name may not contain `@`, but being explicit
  * costs nothing and matches how wasmtime splits (`name.rfind('@')`).
+ * @internal — version-resolution internals.
  */
 export declare function parseInterfaceId(id: string): ParsedId;
+/** @internal — version-resolution internals. */
 export declare function parseSemver(v: string): Semver | null;
 /**
  * The compatibility-track key of an interface id, or null when the id belongs
@@ -48,6 +58,7 @@ export declare function parseSemver(v: string): Semver | null;
  *
  * Build metadata is ignored for track purposes (`2.1.2+abc` -> `@2`), as
  * semver requires.
+ * @internal — version-resolution internals.
  */
 export declare function trackKey(id: string): string | null;
 /**
@@ -56,6 +67,7 @@ export declare function trackKey(id: string): string | null;
  * Note `semver::Version::parse("0.2")` fails — which is exactly why the two
  * mechanisms compose: a track key can never be mistaken for a full version,
  * and a full version never generates a track key equal to itself.
+ * @internal — version-resolution internals.
  */
 export declare function asTrackKeySpelling(id: string): string | null;
 /**
@@ -64,6 +76,8 @@ export declare function asTrackKeySpelling(id: string): string | null;
  * Only the *interface-id* keys participate: world-level bare imports live at
  * the record's top level under camelCase names and are matched by exact
  * string equality, never by version machinery.
+ * @internal — built by `instantiate` from the embedder's plain imports
+ * record; hosts never construct one.
  */
 export declare class ImportResolver {
     #private;
@@ -81,5 +95,8 @@ export declare class ImportResolver {
         value: unknown;
     } | undefined;
 }
-/** Semver precedence, prerelease-aware (semver.org §11). */
+/**
+ * Semver precedence, prerelease-aware (semver.org §11).
+ * @internal — version-resolution internals.
+ */
 export declare function compareSemver(a: Semver, b: Semver): number;

package/types/plan/format.d.ts

@@ -1,5 +1,9 @@
-/** Core wasm lane types as emitted in `coreType` and `rep` fields. */
+/**
+ * Core wasm lane types as emitted in `coreType` and `rep` fields.
+ * @internal
+ */
 export type WireCoreType = "i32" | "i64" | "f32" | "f64";
+/** @internal */
 export interface WirePlan {
     formatVersion: number;
     producer: {
@@ -59,6 +63,7 @@ export interface WirePlan {
     exports: WireExport[];
     worldDigest: string;
 }
+/** @internal */
 export type WireModule = {
     kind: "embedded";
     offset: number;
@@ -69,12 +74,14 @@ export type WireModule = {
     len: number;
     intrinsics: WireIntrinsicEntry[];
 };
+/** @internal */
 export interface WireIntrinsicEntry {
     module: string;
     name: string;
     category: string;
     def: WireCoreDef;
 }
+/** @internal */
 export type WireInitializer = {
     op: "instantiate-module";
     module: number;
@@ -111,6 +118,7 @@ export type WireInitializer = {
     dtor: WireCoreDef | null;
     instance: number;
 };
+/** @internal */
 export type WireCoreDef = {
     kind: "export";
     instance: number;
@@ -137,10 +145,12 @@ export type WireCoreDef = {
 } | {
     kind: "task-may-block";
 };
+/** @internal */
 export interface WireCoreExport {
     instance: number;
     item: WireExportItem;
 }
+/** @internal */
 export interface WireExportItem {
     name: string;
     space: "func" | "table" | "memory" | "global" | "tag" | "unknown";
@@ -150,6 +160,7 @@ export interface WireExportItem {
  * Only the M0-relevant variants are given precise field types; the rest are
  * matched by `kind` and rejected at instantiate time with milestone-aware
  * errors (contracts/intrinsics.md §B).
+ * @internal
  */
 export type WireTrampoline = {
     kind: "lower-import";
@@ -197,6 +208,7 @@ export type WireTrampoline = {
     index: number;
     [field: string]: unknown;
 };
+/** @internal */
 export interface WireCanonicalOptions {
     instance: number;
     stringEncoding: "utf8" | "utf16" | "latin1+utf16";
@@ -211,7 +223,10 @@ export interface WireCanonicalOptions {
         results: WireCoreType[];
     };
 }
-/** descriptor-ir.md ValType JSON (nested structurally). */
+/**
+ * descriptor-ir.md ValType JSON (nested structurally).
+ * @internal
+ */
 export type WireValType = {
     kind: "bool" | "s8" | "u8" | "s16" | "u16" | "s32" | "u32" | "s64" | "u64" | "f32" | "f64" | "char" | "string" | "error-context";
 } | {
@@ -263,6 +278,7 @@ export type WireValType = {
     kind: "future";
     element: WireValType | null;
 };
+/** @internal */
 export type WireTypeDecl = {
     kind: "func";
     params: {
@@ -272,6 +288,7 @@ export type WireTypeDecl = {
     results: WireValType[];
     async: boolean;
 } | WireValType;
+/** @internal */
 export type WireResourceTable = {
     kind: "concrete";
     resource: number;
@@ -281,25 +298,34 @@ export type WireResourceTable = {
     id: number;
 };
 /** One stream or future table (plan v2). */
-/** One error-context table: the owning component instance, nothing else. */
+/**
+ * One error-context table: the owning component instance, nothing else.
+ * @internal
+ */
 export interface WireErrorContextTable {
     instance: number;
 }
+/** @internal */
 export interface WireAsyncTable {
     element: WireValType | null;
     instance: number;
 }
-/** One imported resource type: back-reference into `plan.imports`. */
+/**
+ * One imported resource type: back-reference into `plan.imports`.
+ * @internal
+ */
 export interface WireImportedResource {
     /** `RuntimeImportIndex` — index into `plan.imports`. */
     import: number;
 }
+/** @internal */
 export interface WireImport {
     name: string;
     path: string[];
     kind: string;
     type?: number;
 }
+/** @internal */
 export type WireExport = {
     kind: "lifted-func";
     name: string;
@@ -324,6 +350,7 @@ export type WireExport = {
     name: string;
     module: number;
 };
+/** @internal */
 export type WireTypeExport = {
     kind: "resource";
     resource: number;
@@ -335,6 +362,7 @@ export type WireTypeExport = {
  * The shim's C-ABI envelope: plan + adapter artifacts in one JSON document
  * (crates/translator-shim/README.md documents the 1:1 mapping to the
  * contract's artifact set).
+ * @internal
  */
 export interface WireEnvelope {
     plan?: WirePlan;
@@ -360,6 +388,7 @@ export interface WireEnvelope {
  * valid but uses a shape this plan-format version cannot express, and
  * `"internal"` is a shim bug. Neither of the latter two may be scored as a
  * correct rejection.
+ * @internal
  */
 export interface WireErrorDetail {
     phase: "validation" | "unsupported" | "internal";

package/types/plan/loader.d.ts

@@ -1,6 +1,9 @@
 import { type FuncType, ResourceTypeInfo, type ValType } from "../cabi/types.js";
 import type { WireErrorDetail, WirePlan, WireValType } from "./format.js";
-/** Fault in the plan document itself (version/shape/reference errors). */
+/**
+ * Fault in the plan document itself (version/shape/reference errors).
+ * @internal
+ */
 export declare class PlanError extends Error {
     constructor(message: string);
 }
@@ -12,6 +15,7 @@ export declare class PlanError extends Error {
  * component* and is the only failure that satisfies `assert_invalid` /
  * `assert_malformed`. `PlanError` and the other phases are failures of our
  * own pipeline and must never be scored as conformance passes.
+ * @internal
  */
 export declare class TranslateError extends Error {
     readonly phase: WireErrorDetail["phase"];
@@ -39,9 +43,13 @@ export declare class TranslateError extends Error {
  * producer and consumer bumped in the same commit), so v0 plans are refused
  * rather than best-effort accepted — a stale cached artifact must be a loud
  * failure, not a subtly different execution.
+ * @internal
  */
 export declare const SUPPORTED_FORMAT_VERSION = 4;
-/** A types-table entry after conversion. */
+/**
+ * A types-table entry after conversion.
+ * @internal
+ */
 export type LoadedType = {
     kind: "func";
     funcType: FuncType;
@@ -50,6 +58,7 @@ export type LoadedType = {
     kind: "value";
     type: ValType;
 };
+/** @internal */
 export interface LoadedPlan {
     wire: WirePlan;
     /** Converted types table, index-aligned with `wire.types`. */
@@ -91,6 +100,7 @@ export interface LoadedPlan {
 /**
  * Validate a plan document and convert its type tables. Fails fast on
  * formatVersion mismatch per contracts/plan-format.md "Executor obligations".
+ * @internal
  */
 export declare function loadPlan(wire: WirePlan): LoadedPlan;
 /**
@@ -98,6 +108,7 @@ export declare function loadPlan(wire: WirePlan): LoadedPlan;
  * field of a `resource` initializer). Mirrors wasmtime
  * `Component::resource_index` (wasmtime-environ 47.0.3
  * `component/info.rs:222`).
+ * @internal
  */
 export declare function resourceIndexOfDefined(plan: LoadedPlan, definedIndex: number): number;
 /**
@@ -105,9 +116,11 @@ export declare function resourceIndexOfDefined(plan: LoadedPlan, definedIndex: n
  * bytes. The plan is validated (formatVersion, type tables) but returned in
  * wire form: the executor re-runs `loadPlan` per instantiation so resource
  * identity tokens are fresh per component instance.
+ * @internal
  */
 export declare function loadEnvelope(json: string): {
     wire: WirePlan;
     adapters: Map<string, Uint8Array>;
 };
+/** @internal */
 export declare function loadValType(t: WireValType, resourceTokens: ResourceTypeInfo[], where: string): ValType;

package/types/plan/mod.d.ts

@@ -1,2 +1,25 @@
+/**
+ * The translation plan: the wire descriptor IR emitted by the translator
+ * (`Wire*` types, contracts/plan-format.md) plus the loader that validates
+ * it and converts it into the runtime's in-memory type model.
+ *
+ * **This is not embedder API.** The entry point exists as a support surface
+ * for bindgen-generated bindings and for the runtime's own internals, which
+ * import from it directly. No host program should hand-write an import of
+ * this module.
+ *
+ * **Its contents are completely unstable: there is no compatibility promise
+ * of any kind, including within a minor line.** This is an explicit
+ * carve-out from the caret-honest versioning policy in README.md
+ * §"Consuming", which otherwise promises backward compatibility within a
+ * minor line — every symbol here may be renamed, reshaped, or removed in
+ * any release, including a patch. Regenerate your bindings when you bump
+ * the runtime.
+ *
+ * The supported host-facing surface is `@polyengine/runtime/embedder`
+ * (contracts/embedder-api.md).
+ *
+ * @module
+ */
 export * from "./format.js";
 export * from "./loader.js";