@polyengine/runtime 0.1.0-pre.g633468a

package/types/cache/core.d.ts

@@ -0,0 +1,97 @@
+import type { WirePlan } from "../plan/format.js";
+/**
+ * The minimal surface `translateCached`/`keyFor` need from a translator.
+ * Structural (not `Translator` itself) so tests can substitute a spy that
+ * proves the shim path was/wasn't exercised, without subclassing the real
+ * wasm-backed client.
+ */
+export interface TranslatorLike {
+    readonly buildHash: string | null;
+    translateRaw(componentBytes: Uint8Array): string;
+}
+/** Cache layout version. Bumped on any incompatible on-disk/on-Cache-API
+ * schema change; an unrecognized version is read back as a miss (never a
+ * crash) so stale caches from an older build self-heal by re-translating —
+ * and this self-healing holds even when the cache root itself is
+ * 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. */
+export declare const CACHE_LAYOUT_VERSION = 1;
+/** The three-part identity a translation is content-addressed by. */
+export interface CacheKey {
+    /** hex sha256 of the component bytes (matches `plan.component.sha256`). */
+    componentSha256: string;
+    /**
+     * hex sha256 of the translator (shim) wasm bytes — `Translator.buildHash`.
+     * NOT the envelope's `producer.shimVersion`/`wasmtimeEnviron`: those don't
+     * change across a shim rebuild with identical pinned versions but
+     * different generated code (see `Translator.buildHash` docs).
+     */
+    translatorBuildHash: string;
+    /** wasmparser feature set used, order-insensitive. */
+    features: string[];
+}
+/** What a cache hit returns: enough to instantiate, given the caller's own
+ * (already-in-hand) component bytes. */
+export interface CachedArtifacts {
+    plan: WirePlan;
+    /** Adapter artifacts keyed by `plan.modules[].file`, same shape as
+     * `TranslationResult.adapters`. */
+    adapters: Map<string, Uint8Array>;
+}
+export interface ArtifactCache {
+    get(key: CacheKey): Promise<CachedArtifacts | null>;
+    put(key: CacheKey, artifacts: CachedArtifacts): Promise<void>;
+    /** Remove a poisoned/stale entry. Cache backends also call this
+     * internally on a failed integrity check during `get`. */
+    evict(key: CacheKey): Promise<void>;
+}
+/** On-disk / on-Cache-API metadata envelope stored alongside the plan. */
+export interface CacheMeta {
+    layoutVersion: number;
+    componentSha256: string;
+    translatorBuildHash: string;
+    features: string[];
+}
+/**
+ * The stable cache key string: sha256 over a canonical JSON encoding of the
+ * `CacheKey` (features sorted so order never causes a spurious miss).
+ */
+export declare function keyHex(key: CacheKey): Promise<string>;
+/** Compute the `CacheKey` for a `(translator, componentBytes)` pair. Throws
+ * if the translator has no `buildHash` (constructed from a pre-compiled
+ * `WebAssembly.Module` with no bytes available — see `Translator.create`). */
+export declare function keyFor(translator: TranslatorLike, componentBytes: Uint8Array, features?: string[]): Promise<CacheKey>;
+export interface TranslateCachedOptions {
+    features?: string[];
+    /**
+     * Opt-in determinism guard (tests only, per dispatch): after a cache miss,
+     * translate a second time and assert byte-identical envelope JSON before
+     * trusting/storing the result. Throws `Error` on mismatch.
+     */
+    verifyDeterminism?: boolean;
+    /**
+     * Opt-in diagnostic (issue #196): invoked when a `cache.get`/`cache.put`
+     * failure is swallowed so the degradation is observable without this
+     * library ever writing to the console itself. `op` identifies which
+     * call failed; `err` is the original thrown value, unmodified. Default
+     * is to do nothing. If this callback itself throws, that throw is also
+     * swallowed — a diagnostic hook must never become a new way to fail a
+     * translation.
+     */
+    onCacheError?: (op: "get" | "put", err: unknown) => void;
+}
+export interface TranslateCachedResult {
+    plan: WirePlan;
+    adapters: Map<string, Uint8Array>;
+    /** Whether this result came from the cache (`true`) or a fresh shim
+     * translation (`false`). Exposed for tests/observability; not part of the
+     * `ArtifactCache` contract itself. */
+    fromCache: boolean;
+}
+/**
+ * Orchestration helper: cache hit -> stored artifacts, cache miss ->
+ * translate with the shim, store, return.
+ */
+export declare function translateCached(translator: TranslatorLike, componentBytes: Uint8Array, cache: ArtifactCache, opts?: TranslateCachedOptions): Promise<TranslateCachedResult>;

package/types/cache/dir.d.ts

@@ -0,0 +1,6 @@
+import type { ArtifactCache } from "./core.js";
+/** A filesystem-backed `ArtifactCache` rooted at `path` (created on first
+ * `put` if missing). Deno only: every method calls `Deno.*` directly. On other
+ * platforms use `webCache()` (./web.ts), or supply your own `ArtifactCache` —
+ * the interface is three methods (./core.ts). */
+export declare function dirCache(path: string): ArtifactCache;

package/types/cache/mod.d.ts

@@ -0,0 +1,3 @@
+export * from "./core.js";
+export * from "./dir.js";
+export * from "./web.js";

package/types/cache/web.d.ts

@@ -0,0 +1,10 @@
+import type { ArtifactCache } from "./core.js";
+/** Thrown when the Cache API isn't available in this environment. */
+export declare class WebCacheUnavailableError extends Error {
+    constructor();
+}
+/** A `Cache`-API-backed `ArtifactCache` under the given cache name. Throws
+ * `WebCacheUnavailableError` (at call time, not construction time, so
+ * feature-detection failures surface where they're actually hit) when
+ * `globalThis.caches` doesn't exist. */
+export declare function webCache(name: string): ArtifactCache;

package/types/digest/digest.d.ts

@@ -0,0 +1,17 @@
+import type { WirePlan } from "../plan/format.js";
+export declare const CEWD_VERSION = 1;
+export declare class DigestError extends Error {
+    constructor(message: string);
+}
+export interface WorldDigestResult {
+    canonicalJson: string;
+    digest: string;
+}
+/** Compute the canonical world digest from a loaded wire plan. */
+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.
+ */
+export declare function canonicalStringify(v: unknown): string;

package/types/digest/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./digest.js";
+export * from "./verify.js";

package/types/digest/verify.d.ts

@@ -0,0 +1,48 @@
+import type { WirePlan } from "../plan/format.js";
+export interface DigestMismatch {
+    expected: string;
+    actual: string;
+    /** Human-readable description of the first structural divergence found,
+     * or `null` if a divergence exists but no finer-grained cause could be
+     * isolated (e.g. the two canonical JSON trees have the same top-level
+     * shape but the digest still differs — should not happen in practice
+     * since the digest is a pure hash of that JSON, but guarded anyway). */
+    firstDivergence: string | null;
+}
+/**
+ * Thrown by generated `instantiate` wrappers when the loaded plan's world
+ * digest does not match the constant bindgen embedded at generation time
+ * (contracts/digest.md: "fails fast with a structural diff on mismatch").
+ * Raised BEFORE the component is instantiated, so no guest code has run
+ * when a caller catches this.
+ *
+ * Named and catchable: `err instanceof WorldDigestMismatchError`, or
+ * `err.name === "WorldDigestMismatchError"` across realms.
+ */
+export declare class WorldDigestMismatchError extends Error {
+    readonly name = "WorldDigestMismatchError";
+    /** The world these bindings were generated from. */
+    readonly world: string;
+    /** The full mismatch report (expected/actual digest, first divergence). */
+    readonly mismatch: DigestMismatch;
+    constructor(world: string, mismatch: DigestMismatch);
+    /** Digest the generated bindings were built against. */
+    get expected(): string;
+    /** Digest computed from the plan actually loaded. */
+    get actual(): string;
+}
+/**
+ * Verify `plan`'s computed world digest against `expectedDigest` (the
+ * constant bindgen embedded at generation time). Returns `null` on match,
+ * or a `DigestMismatch` report naming the first divergent path on
+ * mismatch.
+ */
+export declare function verifyWorldDigest(plan: WirePlan, expectedDigest: string): Promise<DigestMismatch | null>;
+/**
+ * `diffWorldDigest` — richer variant for tests/tooling: compare against
+ * another plan's (or a WIT-derived) canonical JSON directly, walking both
+ * 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.
+ */
+export declare function diffWorldDigest(plan: WirePlan, expectedCanonicalJson: string): Promise<DigestMismatch | null>;

package/types/embedder/casing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `get-resolution` -> `getResolution`.
+ *
+ * The rule, stated exactly: split the label on `-`; the first fragment is
+ * unchanged; every later fragment has its first character upper-cased and its
+ * remainder preserved. Preserving the remainder is what keeps acronym
+ * fragments intact — `outgoing-HTTP-request` -> `outgoingHTTPRequest` — which
+ * a naive `toLowerCase()` of the tail would destroy.
+ *
+ * WIT labels are already lower-kebab in practice, so the first fragment needs
+ * no adjustment; nothing here lower-cases anything.
+ */
+export declare function camelCase(label: string): string;
+/** `tcp-socket` -> `TcpSocket` (resource class names). */
+export declare function pascalCase(label: string): string;
+/**
+ * A leaf name in `plan.exports` / `plan.imports`, decoded.
+ *
+ * The Component Model mangles resource membership into the name itself
+ * (`[constructor]counter`, `[method]counter.increment`,
+ * `[static]counter.merge`); C0 finding #2 was embedders hand-transcribing
+ * these. Assembling and disassembling them is a runtime obligation.
+ */
+export type LeafName = {
+    form: "plain";
+    name: string;
+} | {
+    form: "constructor";
+    resource: string;
+} | {
+    form: "method";
+    resource: string;
+    member: string;
+} | {
+    form: "static";
+    resource: string;
+    member: string;
+};
+/** Decode a mangled leaf name; unmangled names come back as `plain`. */
+export declare function parseLeafName(raw: string): LeafName;

package/types/embedder/copy.d.ts

@@ -0,0 +1,24 @@
+/** The URL of this copy of the runtime. Identity of the copy. */
+export declare const COPY_URL: string;
+/**
+ * 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 declare 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 declare function describeCrossCopy(what: string, remedy?: string): string;

package/types/embedder/errors.d.ts

@@ -0,0 +1,11 @@
+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 declare class NameCollisionError extends Error {
+    constructor(message: string);
+}

package/types/embedder/imports.d.ts

@@ -0,0 +1,47 @@
+import type { WirePlan } from "../plan/format.js";
+import type { LoadedPlan } from "../plan/loader.js";
+import type { ValType } from "../cabi/types.js";
+import { type LeafName } from "./casing.js";
+/** Function type summary of an import leaf (names are docs-only; §"Functions"). */
+export interface FuncSummary {
+    params: {
+        name: string;
+        type: ValType;
+    }[];
+    results: ValType[];
+    /** True for an `async func` — an import may then be a plain async function. */
+    async: boolean;
+}
+/** One linkable import leaf. */
+export interface ImportLeaf {
+    /**
+     * The record key this leaf is provided under: a fully-qualified WIT
+     * interface id verbatim (version included) for interface imports, or the
+     * component's bare world-level import name.
+     */
+    interfaceId: string;
+    /** Path from the record key to the leaf, verbatim (mangled names included). */
+    path: string[];
+    /** The raw, still-mangled leaf name (`[method]counter.increment`). */
+    leaf: string;
+    /** `func`, `resource`, `instance`, … — the plan's own kind string. */
+    kind: string;
+    /** Decoded resource membership of `leaf`. */
+    member: LeafName;
+    /**
+     * The JS name this leaf is looked up under: camelCase for functions and
+     * world-level imports, PascalCase for a resource *type* (the class), and —
+     * for a mangled leaf — the JS name of the class **member** it dispatches to.
+     */
+    jsName: string;
+    /** For a mangled leaf: the PascalCase class it belongs to. */
+    jsClass?: string;
+    /** Present for `kind === "func"`. */
+    type?: FuncSummary;
+}
+/** Anything `requiredImports` accepts. */
+export type PlanLike = WirePlan | LoadedPlan | {
+    plan: WirePlan;
+};
+/** Enumerate the component's linkable import leaves. */
+export declare function requiredImports(input: PlanLike): ImportLeaf[];

package/types/embedder/instantiate.d.ts

@@ -0,0 +1,88 @@
+import type { WirePlan } from "../plan/format.js";
+import { type ComponentHandle } from "../exec/mod.js";
+import { Translator } from "../shim/mod.js";
+import { type ImportLeaf } from "./imports.js";
+/** The shim's output plus the component bytes it describes. */
+export interface ComponentArtifacts {
+    plan: WirePlan;
+    componentBytes: Uint8Array;
+    adapters?: Map<string, Uint8Array>;
+}
+/**
+ * Untranslated alternative to `ComponentArtifacts` (embedder-api.md
+ * amendment A3): hand `instantiate` the raw component plus the translator
+ * and it runs the translation internally — the pipeline collapses to
+ * bytes-in, instance-out.
+ *
+ * `translator` accepts the translator-shim wasm bytes (simplest; compiles
+ * the shim per call) or an already-created `Translator` (preferred when
+ * instantiating more than one component, or the same component more than
+ * once — create it once and reuse; translation itself is sub-millisecond
+ * warm, the wasm compile is the cost being shared). `requiredImports`
+ * still needs a plan: translate explicitly when you want to inspect the
+ * import surface before instantiating.
+ */
+export interface UntranslatedArtifacts {
+    componentBytes: Uint8Array;
+    translator: Uint8Array | Translator;
+}
+/** Either artifacts shape accepted by `instantiate`. */
+export type InstantiateSource = ComponentArtifacts | UntranslatedArtifacts;
+/**
+ * Reconstitute `ComponentArtifacts` from a translation ENVELOPE — the
+ * single-file JSON emitted by build-time translation (`tools/translate`,
+ * or `Translator.translateRaw`), carrying the plan and the FACT adapter
+ * modules. The production deploy set is `component.wasm` + its envelope +
+ * the runtime: no translator ships (embedder-api.md amendment A4).
+ *
+ * Pure and fetch-agnostic: acquire the two blobs however the platform
+ * likes (HTTP, fs, bundler asset) and hand them over. The envelope embeds
+ * the component's sha-256, which `instantiate` verifies — a mismatched
+ * pair fails loudly at instantiation, never subtly at runtime.
+ */
+export declare function artifactsFromEnvelope(envelopeJson: string, componentBytes: Uint8Array): ComponentArtifacts;
+/**
+ * Normalize either accepted input form to `ComponentArtifacts` — i.e. make
+ * the PLAN available without instantiating anything. Exported because the
+ * 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.
+ */
+export declare function resolveArtifacts(src: InstantiateSource): Promise<ComponentArtifacts>;
+export interface EmbedderOptions {
+    /** Opt in to JSPI-backed suspension (see `InstantiateInput.jspi`). */
+    jspi?: boolean;
+    /** Verify `plan.component.sha256` against the bytes (default true). */
+    verifyHash?: boolean;
+}
+/** An instantiated component, conventions-shaped. */
+export interface EmbedderInstance {
+    /**
+     * Nested record keyed by verbatim WIT interface id; world-level exports at
+     * the top level under camelCase names.
+     */
+    exports: Record<string, any>;
+    /** The raw runtime handle. Internal surface, no stability promise. */
+    handle: ComponentHandle;
+    /** The leaves this component required (the same list `requiredImports` gives). */
+    imports: ImportLeaf[];
+}
+/**
+ * Instantiate a component behind the embedder conventions.
+ *
+ * `imports` is the canonical nested record of
+ * contracts/embedder-api.md §"Module wiring and instantiation": keys are
+ * verbatim WIT interface ids (version included) or world-level camelCase
+ * names; interface-id keys additionally participate in compatibility-track
+ * 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. */
+export declare const instantiateEmbedder: typeof instantiate;
+/**
+ * Symbol-keyed, deliberately NOT re-exported from `mod.ts`: the
+ * host-resource registries of an instance, by `ResourceIndex`. Diagnostics and
+ * white-box tests only — it is not part of the embedder API surface and no
+ * generated code may depend on it.
+ */
+export declare const INTERNAL_HOST_REGISTRIES: unique symbol;

package/types/embedder/mod.d.ts

@@ -0,0 +1,11 @@
+export { COPY_URL, RUNTIME_VERSION } from "./copy.js";
+export { copyCensus, DROPPED, ERROR_CONTEXT, FUTURE, hasBrand, INVALID_HANDLE, isDroppedError, isInvalidHandleError, isPeerTrappedError, isStreamProducerError, isSuspending, isTrap, isComponentException, PEER_TRAPPED, PROTOCOL_GENERATION, registerRuntimeCopy, RESOURCE_STATE, type RuntimeCopy, runtimeCopies, STREAM, STREAM_PRODUCER, SUSPENDING, TRAP, COMPONENT_EXCEPTION, } from "@polyengine/protocol";
+export { artifactsFromEnvelope, type ComponentArtifacts, type EmbedderInstance, type EmbedderOptions, type InstantiateSource, type UntranslatedArtifacts, instantiate, instantiateEmbedder, resolveArtifacts, } from "./instantiate.js";
+export { type FuncSummary, type ImportLeaf, type PlanLike, requiredImports } from "./imports.js";
+export { DroppedError, InvalidHandleError, NameCollisionError, PeerTrappedError, Trap, ComponentException, } from "./errors.js";
+export { type Chunk, type ElemCodec, ErrorContext, Future, type FutureSource, Stream, StreamProducerError, type StreamSource, StreamWriter, } from "./streams.js";
+export { GuestResource, HostResourceRegistry } from "./resources.js";
+export { camelCase, type LeafName, parseLeafName, pascalCase } from "./casing.js";
+export { suspending } from "../jspi/suspending.js";
+export { asTrackKeySpelling, compareSemver, ImportRegistrationError, ImportResolutionError, ImportResolver, type ParsedId, parseInterfaceId, parseSemver, type Semver, trackKey, } from "./version.js";
+export { type AdapterOptions, BorrowScope, fromHost, toHost, type ValueBridge, } from "./values.js";

package/types/embedder/resources.d.ts

@@ -0,0 +1,158 @@
+import type { ResourceTypeInfo, ValType } from "../cabi/types.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.
+ */
+declare const STATE: symbol;
+interface WrapperState {
+    /** The runtime copy that minted this wrapper (A9). */
+    copyUrl: string;
+    rep: number;
+    /** False once the handle was transferred away or dropped. */
+    valid: boolean;
+    /** True for `own` wrappers, which are responsible for dropping. */
+    owns: boolean;
+    rt: ResourceTypeInfo;
+    className: string;
+    /**
+     * Host-side `ResourceHandle.num_lends` (#86). The reference models a
+     * host-held `own` as a table entry whose `num_lends` is bumped every time
+     * it is lifted as a `borrow` (definitions.py `Subtask.add_lender`, line
+     * 890, reached from `lift_borrow`, line 1516) and decremented when the
+     * borrowing call's subtask delivers its resolution (`deliver_resolve`,
+     * line 902). `lift_own` and `canon_resource_drop` both trap while it is
+     * non-zero (lines 1508 / 2325).
+     *
+     * Here the host holds bare reps rather than table entries, so the counter
+     * lives on the wrapper. Its lifecycle point is the *lowering scope* of the
+     * call the wrapper was passed into (`instantiate.ts` `#lowerParams`), which
+     * is released exactly when that call ends — the host-side analogue of the
+     * subtask's resolve delivery.
+     */
+    lends: number;
+    /**
+     * A drop (explicit or via the GC backstop) that arrived while `lends > 0`.
+     * The reference would trap; the host has no frame to trap into by then, so
+     * the drop is deferred to the last release instead of running the dtor
+     * under a live guest borrow (which is the use-after-free #86 reports).
+     */
+    pendingDrop: boolean;
+}
+/** Base of every runtime-built guest-resource class. */
+export declare class GuestResource {
+    [STATE]: WrapperState;
+    /** Drop the handle (alias of `[Symbol.dispose]`, so TS `using` works). */
+    drop(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * 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 declare function simulateFinalizationForTest(w: object): void;
+export declare function initWrapper(w: GuestResource, state: Omit<WrapperState, "copyUrl"> & {
+    copyUrl?: string;
+}): void;
+/**
+ * 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 declare function wrapperState(w: object): WrapperState | undefined;
+/**
+ * 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 declare function lendWrapper(w: object): () => void;
+/** Host-side `num_lends` — diagnostics and white-box tests. */
+export declare function wrapperLends(w: object): number;
+/** Invalidate a wrapper without dropping (used to end a borrow's lifetime). */
+export declare function invalidateWrapper(w: object): void;
+/** Read a wrapper's rep for a lowering site, applying the ownership rule. */
+export declare function takeRep(w: unknown, own: boolean, what: string): number;
+/** Everything needed to build one guest-resource class. */
+export interface GuestResourceSpec {
+    /** WIT resource name (kebab). */
+    name: string;
+    /** The raw `[constructor]r` lifted function, if the resource has one. */
+    ctor: ((...a: unknown[]) => unknown) | null;
+    ctorParams: ValType[] | null;
+    methods: {
+        member: string;
+        raw: (...a: unknown[]) => unknown;
+        params: ValType[];
+        results: ValType[];
+    }[];
+    statics: {
+        member: string;
+        raw: (...a: unknown[]) => unknown;
+        params: ValType[];
+        results: ValType[];
+    }[];
+}
+export type CallAdapter = (raw: (...a: unknown[]) => unknown, params: ValType[], results: ValType[], where: string, args: unknown[]) => Promise<unknown>;
+/**
+ * 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 declare function buildGuestResourceClass(spec: GuestResourceSpec, rt: ResourceTypeInfo, adapt: CallAdapter, lowerArgs: (args: unknown[], params: ValType[], where: string) => unknown[]): any;
+/** Materialize an `own`/`borrow` wrapper for a rep coming out of a guest. */
+export declare function makeWrapper(cls: any, rep: number, rt: ResourceTypeInfo, owns: boolean): GuestResource;
+/**
+ * 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 declare class HostResourceRegistry {
+    #private;
+    readonly className: string;
+    constructor(className: string);
+    /** The host is passing an instance to the guest: allocate (or reuse) a rep. */
+    repFor(instance: unknown): number;
+    /** Is this instance already registered with a live rep? */
+    hasInstance(instance: unknown): boolean;
+    /** Is `rep` live? Diagnostics and white-box tests. */
+    hasRep(rep: number): boolean;
+    /** Release a rep if it is still live; no dtor, no error when already gone. */
+    releaseIfPresent(rep: number): void;
+    /** A `borrow<R>` arrived from the guest: the host's own instance, mapping kept. */
+    lookup(rep: number): object;
+    /**
+     * 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: number): object;
+    /**
+     * The guest dropped its last own handle: run the destructor. This is the
+     * `HostResourceType` dtor the executor calls from `canon_resource_drop`.
+     */
+    dtor(rep: number): void;
+    /** Live handle count — diagnostics and tests. */
+    get liveCount(): number;
+}
+export {};