@polyengine/runtime 0.1.0-pre.g633468a

package/types/jspi/bridge.d.ts

@@ -0,0 +1,227 @@
+import { type SuspendingImport } from "./mechanics.js";
+import type { Cancelled, SchedulableThread, Store } from "../task/mod.js";
+/** Which suspension discipline an instantiation runs under. */
+export type SuspensionMode = "plain" | "jspi";
+/**
+ * Decide the mode for one instantiation.
+ *
+ * `requested` is the embedder's opt-in. We additionally require the engine to
+ * actually implement JSPI: on an engine without it every blocking site falls
+ * back to the precise `NeedsJspi` it raised before this module existed, which
+ * is the M3 browser-matrix degradation path (docs/milestones.md M3).
+ */
+export declare function chooseMode(requested: boolean | undefined, needed?: boolean): SuspensionMode;
+/**
+ * Does a call through this trampoline declaration genuinely block — i.e. is
+ * it a reason a component NEEDS suspension support at all?
+ *
+ * Sharper than a kind list, and it must be: the async *form* of every copy /
+ * cancel built-in NEVER blocks — it returns `BLOCKED` and delivers the result
+ * through an event (definitions.py `stream_copy` line 2530 / `cancel_copy`
+ * 2636 / `canon_subtask_cancel` 2469, each `if not async_: ... else return
+ * BLOCKED`). Classifying by kind alone marked every instance that imports an
+ * async-form built-in as suspension-capable, which promising-wrapped its
+ * eagerly-completing FACT callees — and a wrapped eager callee reports
+ * STARTED where the reference reports RETURNED, and parks on a
+ * non-cancellable `awaitValue` where the reference delivers a synchronous
+ * cancellation (both asserted by big-interleaving-test.wast's expect-codes).
+ *
+ * Where the async-ness lives varies by kind, following wasmtime's trampoline
+ * layout (component/info.rs): copy built-ins carry an options index (the
+ * flag is `canonicalOptions[i].async`); the cancel forms and `subtask.cancel`
+ * carry `async` on the declaration itself; `waitable-set.wait`,
+ * `thread.yield` and `sync-start-call` are unconditionally block-capable
+ * (their non-blocking counterparts are separate kinds: poll, the YIELD
+ * callback code, async-start-call).
+ */
+export declare function trampolineNeedsSuspension(t: {
+    kind: string;
+    async?: unknown;
+    options?: unknown;
+}, optionsAsync: (index: number) => boolean): boolean;
+/**
+ * Must the executor hand this trampoline to wasm as a `Suspending` import in
+ * jspi mode?
+ *
+ * A superset of `trampolineNeedsSuspension` by exactly two kinds, both for
+ * the same reason: they never block in the reference or in plain mode, but
+ * under jspi they may park the CALLER until a callee's state is determinate,
+ * because the engine defers a resumed activation's continuation to a
+ * microtask (jspi pin (j), `fastpath_hop_test.ts`):
+ *
+ *   * `async-start-call` — parks until the freshly-started callee reaches
+ *     resolution / completion / a genuine block (fact_calls.ts);
+ *   * the async form of `subtask.cancel` — parks until a cancellation
+ *     delivered by settling the callee's suspension has actually landed
+ *     (async_builtins.ts; cancellable.wast asserts the reference's
+ *     synchronous-delivery answers).
+ *
+ * Neither is a *reason* to choose jspi mode, and neither marks its importer
+ * suspendable (`Executor.suspendableFuncs`): their parks only ever trigger
+ * when the nested callee is itself promising-wrapped, i.e. when a genuine
+ * blocker has already contaminated the adapter through the transitive import
+ * rule. Marking on these kinds is not only unnecessary — it is wrong: the
+ * FACT adapter's `[adapter-callee]*` pass-through exports are what get
+ * passed to `*-start-call` as lift callees, and marking the whole adapter
+ * instance promoted every eagerly-completing callee to promising, recreating
+ * the STARTED-vs-RETURNED divergence one level up.
+ */
+export declare function trampolineCanBlock(t: {
+    kind: string;
+    async?: unknown;
+    options?: unknown;
+}, optionsAsync: (index: number) => boolean): boolean;
+/**
+ * Does this component contain anything that can block a wasm frame?
+ *
+ * Computed from the plan, on the runtime side, so embedders (and the
+ * conformance harness) stay dumb — no plan v3 field, no flag to thread
+ * through. Deliberately a slight over-approximation: it asks "could this
+ * component ever reach a blocking built-in", not "will this call". A false
+ * positive costs a promising-wrapped entry (the export returns a Promise); a
+ * false negative would be a hard trap at the blocking site, so the bias is the
+ * safe one.
+ *
+ * The two sources of blocking, both straight from the reference:
+ *
+ *   * a **stackful async lift** — async canonical options with no callback
+ *     (`canon_lift` line 2179 runs the callee to completion on its own stack);
+ *   * a **blocking built-in** reached synchronously — see
+ *     `trampolineNeedsSuspension`.
+ */
+export declare function planNeedsSuspension(plan: {
+    canonicalOptions: {
+        async: boolean;
+        callback: number | null;
+    }[];
+    trampolines: {
+        kind: string;
+        async?: unknown;
+        options?: unknown;
+    }[];
+}): boolean;
+/**
+ * Wrap a JS→wasm entry according to the mode.
+ *
+ * In `plain` mode this is the identity. In `jspi` mode the returned function
+ * always yields a Promise (empirical fact (e)), which is why the mode is an
+ * embedder opt-in: it changes the shape of every lifted export.
+ */
+export declare function enterWasm<T extends (...a: never[]) => unknown>(fn: T, mode: SuspensionMode): T;
+export declare function suspendingImport<T extends (...a: never[]) => unknown>(fn: T, mode: SuspensionMode): T | SuspendingImport;
+/**
+ * Fail loudly at instantiate time if the two wrapping sites disagree.
+ *
+ * The dangerous direction, per jspi pin (c), is a `Suspending` import
+ * reachable from a non-`promising` activation — that traps unconditionally,
+ * even on the plain-value path. Entry wrapping in jspi mode is unconditional
+ * (every lifted export, callback, and block-capable FACT callee), so the
+ * structural invariant is `importsWrapped ⇒ entriesWrapped`, per mode.
+ *
+ * Entries-without-imports is legitimate: per-declaration classification
+ * (`trampolineNeedsSuspension`) wraps no imports in a component whose
+ * built-ins are all non-blocking async forms, while the mode can still be
+ * jspi via the lift-shape over-approximation in `planNeedsSuspension`
+ * (canonical options carrying `async` with no callback are counted whether
+ * they belong to a lift or to a copy built-in — the plan does not say which,
+ * and the false positive only costs Promise-shaped exports).
+ */
+export declare function assertModeConsistent(mode: SuspensionMode, entriesWrapped: boolean, importsWrapped: boolean): void;
+export declare class SuspensionPoint<T = unknown> implements SchedulableThread {
+    #private;
+    readonly task: any;
+    /** Resumable once this holds; `null` = only an explicit resume. */
+    readonly readyFunc: (() => boolean) | null;
+    readonly cancellable: boolean;
+    /** Produces the value to hand back to wasm at resume time. */
+    private readonly produce;
+    /**
+     * `finally`-style hook: runs EXACTLY ONCE, on whichever terminal
+     * transition this point takes — produce-success, produce-throw, or
+     * `abandon` (issue #102). It is the seam a blocking built-in uses to
+     * discharge state it owns for the duration of the park (the FACT
+     * start-calls' borrow-lender scopes, contracts/intrinsics.md v0.2
+     * amendment 2) without having to trust that `produce` runs.
+     *
+     * INVARIANTS this hook must respect, so bridge.ts's own contracts are
+     * not disturbed:
+     *   * it must not throw (a throw here would escape `resume` *after* the
+     *     import's Promise was settled, i.e. into whatever drained the
+     *     scheduler); it is called inside a `try`/`catch` that reports such
+     *     a throw rather than propagating it;
+     *   * it must be idempotent-safe by construction anyway, because it runs
+     *     AFTER `produce` on the success path — a built-in that already did
+     *     its cleanup inside `produce` (to pin cleanup ordering relative to
+     *     the produced value) sees this as a no-op backstop;
+     *   * it must not resume/abandon this or any other suspension point.
+     */
+    private readonly onSettled?;
+    readonly promise: Promise<T>;
+    /**
+     * WHO the engine will resume when this point's promise settles.
+     *
+     * Captured HERE, at construction, and not derived at resume time: the
+     * blocking built-in that mints this point is running under the suspending
+     * activation's own ambient, so the ambient names that activation exactly.
+     * This is the replacement for the async-context store the scheduler
+     * used to rely on (M3A-1): same value, obtained by construction instead of
+     * by asking the platform to carry a context across the engine's resumption.
+     * `task.implicitThread` is the fallback for the one shape that has no
+     * ambient at all — a built-in reached during instantiation.
+     */
+    readonly owner: any;
+    constructor(store: Store, task: any, 
+    /** Resumable once this holds; `null` = only an explicit resume. */
+    readyFunc: (() => boolean) | null, cancellable: boolean, 
+    /** Produces the value to hand back to wasm at resume time. */
+    produce: (cancelled: Cancelled) => T, owner?: any, 
+    /**
+     * `finally`-style hook: runs EXACTLY ONCE, on whichever terminal
+     * transition this point takes — produce-success, produce-throw, or
+     * `abandon` (issue #102). It is the seam a blocking built-in uses to
+     * discharge state it owns for the duration of the park (the FACT
+     * start-calls' borrow-lender scopes, contracts/intrinsics.md v0.2
+     * amendment 2) without having to trust that `produce` runs.
+     *
+     * INVARIANTS this hook must respect, so bridge.ts's own contracts are
+     * not disturbed:
+     *   * it must not throw (a throw here would escape `resume` *after* the
+     *     import's Promise was settled, i.e. into whatever drained the
+     *     scheduler); it is called inside a `try`/`catch` that reports such
+     *     a throw rather than propagating it;
+     *   * it must be idempotent-safe by construction anyway, because it runs
+     *     AFTER `produce` on the success path — a built-in that already did
+     *     its cleanup inside `produce` (to pin cleanup ordering relative to
+     *     the produced value) sees this as a no-op backstop;
+     *   * it must not resume/abandon this or any other suspension point.
+     */
+    onSettled?: (() => void) | undefined);
+    waiting(): boolean;
+    ready(): boolean;
+    /** Settle the import's Promise; the engine resumes the wasm activation. */
+    resume(cancelled?: Cancelled): void;
+    /** Abandon this suspension without resuming the guest (teardown paths). */
+    abandon(reason: unknown): void;
+}
+/**
+ * The single shape every blocking built-in needs: "park the calling wasm frame
+ * until `readyFunc` holds, then hand it `produce()`".
+ *
+ * In `plain` mode the caller must not reach here — it raises `NeedsJspi` at
+ * its own site, with a message naming the operation, exactly as before. In
+ * `jspi` mode this returns a Promise, and because the built-in was
+ * `Suspending`-wrapped the engine suspends the activation on it.
+ */
+export declare function blockCurrentActivation<T>(input: {
+    store: Store;
+    task: any;
+    readyFunc: (() => boolean) | null;
+    cancellable: boolean;
+    produce: (cancelled: Cancelled) => T;
+    /**
+     * Optional `finally`-style hook — see `SuspensionPoint.onSettled`. Use it
+     * for state that must be discharged however the park ends, including the
+     * settle paths that never call `produce` (issue #102).
+     */
+    onSettled?: () => void;
+}): Promise<T>;

package/types/jspi/mechanics.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Opaque public alias for `WebAssembly.Suspending` instances.
+ *
+ * JSPI is not in the standard TS libs and JSR forbids global-type
+ * augmentation, so the engine surface is module-scoped (`jspiApi()` in
+ * ./types.ts) and the public API names this opaque brand; the value is
+ * exactly a `WebAssembly.Suspending`, usable anywhere an import value is
+ * expected.
+ */
+export type SuspendingImport = {
+    readonly __polyengineSuspending: unique symbol;
+};
+/** True if the current engine implements `WebAssembly.promising` and
+ * `WebAssembly.Suspending`. Both are phase-4 API surface (docs/architecture.md §3): no
+ * fallback path exists or is planned for engines without them. */
+export declare function isSupported(): boolean;
+/** Throws if JSPI is not available in the current engine. Call this before
+ * using anything else in this module if you want a clear error instead of a
+ * `TypeError: WebAssembly.promising is not a function`. */
+export declare function assertSupported(): void;
+/**
+ * Wrap a wasm-exported function (as retrieved from
+ * `instance.exports.someExport`) so that calling it:
+ *   - always returns a Promise,
+ *   - suspends the underlying wasm activation (rather than trapping) the
+ *     first time it calls a `Suspending`-wrapped import that itself returns
+ *     a genuine Promise,
+ *   - resolves that Promise with the export's return value once the wasm
+ *     activation runs to completion (after zero or more suspend/resume
+ *     cycles).
+ *
+ * This is a direct type-safe pass-through of `WebAssembly.promising`; it
+ * does no extra bookkeeping. `TArgs`/`TReturn` are the caller's own
+ * annotation of the underlying export's signature (not reflected — see
+ * docs/architecture.md §3's note on js-types being flagged/phase-3).
+ */
+export declare function makePromising<TArgs extends unknown[] = unknown[], TReturn = unknown>(wasmExport: (...args: TArgs) => TReturn): (...args: TArgs) => Promise<TReturn>;
+/**
+ * Wrap a JS function as a `Suspending` import: when a `promising`-suspendable
+ * wasm activation calls it (per the frame rule above) and it returns a
+ * genuine Promise, the wasm activation suspends until that Promise settles;
+ * if it returns a non-Promise value (or the call site is not suspension-
+ * eligible), the value passes straight through — the "fast path", pinned in
+ * `suspending_import_test.ts::non_promise_return_is_fast_path`.
+ *
+ * The returned value is an opaque `WebAssembly.Suspending` instance; hand it
+ * directly to the instantiation `imports` object in the slot the wasm module
+ * expects a function import.
+ */
+export declare function makeSuspending<TArgs extends unknown[] = unknown[], TReturn = unknown>(fn: (...args: TArgs) => TReturn | Promise<TReturn>): SuspendingImport;

package/types/jspi/mod.d.ts

@@ -0,0 +1,3 @@
+export * from "./mechanics.js";
+export * from "./bridge.js";
+export * from "./suspending.js";

package/types/jspi/suspending.d.ts

@@ -0,0 +1 @@
+export { anySuspendingImport, isSuspending, suspending } from "@polyengine/protocol";

package/types/jspi/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The engine's JSPI surface, as probed.
+ *
+ * `Suspending` wraps a JS function that returns a Promise (or any value —
+ * the fast path pinned in `suspending_import_test.ts`) so it can be called
+ * as a wasm import that may suspend the calling wasm activation. It must
+ * only actually suspend while every frame between the nearest enclosing
+ * `promising`-wrapped entry and the call is a wasm frame — the "frame
+ * rule" (docs/architecture.md §5; `frame_rule_test.ts` pins the observed
+ * error shape).
+ *
+ * `promising` wraps a wasm-exported function so that calling it returns a
+ * Promise instead of (potentially) suspending the JS caller: the wasm
+ * activation becomes suspendable, and any `Suspending` import it calls
+ * transfers control back to the event loop instead of trapping.
+ */
+export interface JspiApi {
+    Suspending: new (fn: (...args: any[]) => any) => object;
+    promising: (fn: (...args: any[]) => any) => (...args: any[]) => Promise<any>;
+}
+/**
+ * The engine's JSPI API, or `null` where the proposal is not implemented.
+ * The one sanctioned way to reach `WebAssembly.Suspending`/`promising`
+ * from this codebase's published modules.
+ */
+export declare function jspiApi(): JspiApi | null;

package/types/plan/format.d.ts

@@ -0,0 +1,369 @@
+/** Core wasm lane types as emitted in `coreType` and `rep` fields. */
+export type WireCoreType = "i32" | "i64" | "f32" | "f64";
+export interface WirePlan {
+    formatVersion: number;
+    producer: {
+        shimVersion: string;
+        wasmtimeEnviron: string;
+        features: string[];
+    };
+    component: {
+        sha256: string;
+        len: number;
+    };
+    modules: WireModule[];
+    initializers: WireInitializer[];
+    trampolines: WireTrampoline[];
+    canonicalOptions: WireCanonicalOptions[];
+    types: WireTypeDecl[];
+    resourceTables: WireResourceTable[];
+    /**
+     * Stream-table metadata (plan v2), index space == wasmtime's
+     * `TypeStreamTableIndex`; referenced by the `streamTable` field of every
+     * `stream.*` trampoline. `element` is the `T` of `stream<T>`, `null` for the
+     * zero-width payload.
+     *
+     * ISSUE #94(2): the shim never `skip_serializing_if`s this field
+     * (crates/translator-shim/src/plan.rs), so every v2 plan the producer
+     * emits carries it (`[]` when empty). Required, not optional: the loader
+     * only ever accepts `formatVersion === 2` (strict equality,
+     * `SUPPORTED_FORMAT_VERSION`), so there is no live v1-compat path that
+     * needs this to be absent.
+     */
+    streamTables: WireAsyncTable[];
+    /** Future-table metadata (plan v2); see `streamTables`. */
+    futureTables: WireAsyncTable[];
+    /**
+     * Error-context-table metadata (plan v3), index space == wasmtime's
+     * `TypeComponentLocalErrorContextTableIndex` — the space the
+     * `error-context-transfer` trampoline's `srcTable`/`dstTable` *runtime*
+     * arguments live in. No element type: wasmtime's `TypeErrorContextTable`
+     * is `{ instance }` and nothing else.
+     *
+     * Required for the same reason as `streamTables`/`futureTables`: the shim
+     * always serializes it and the loader accepts only `formatVersion === 3`.
+     */
+    errorContextTables: WireErrorContextTable[];
+    /**
+     * Resource types the component imports, in `ResourceIndex` order:
+     * `ResourceIndex = importedResources.length + DefinedResourceIndex`
+     * (wasmtime `Component::resource_index`).
+     *
+     * plan-format.md v0.1 amendment #2 documents this as a *gap*; the field is
+     * a **v0.2 proposal** emitted by the shim. Optional here so plans produced
+     * by a v0.1 shim still load — absent is read as "no imported resources",
+     * which is exactly what v0.1 asserted.
+     */
+    importedResources?: WireImportedResource[];
+    imports: WireImport[];
+    exports: WireExport[];
+    worldDigest: string;
+}
+export type WireModule = {
+    kind: "embedded";
+    offset: number;
+    len: number;
+} | {
+    kind: "adapter";
+    file: string;
+    len: number;
+    intrinsics: WireIntrinsicEntry[];
+};
+export interface WireIntrinsicEntry {
+    module: string;
+    name: string;
+    category: string;
+    def: WireCoreDef;
+}
+export type WireInitializer = {
+    op: "instantiate-module";
+    module: number;
+    instance: number | null;
+    args: WireCoreDef[];
+} | {
+    op: "lower-import";
+    index: number;
+    import: number;
+} | {
+    op: "extract-memory";
+    index: number;
+    export: WireCoreExport;
+} | {
+    op: "extract-realloc";
+    index: number;
+    def: WireCoreDef;
+} | {
+    op: "extract-callback";
+    index: number;
+    def: WireCoreDef;
+} | {
+    op: "extract-post-return";
+    index: number;
+    def: WireCoreDef;
+} | {
+    op: "extract-table";
+    index: number;
+    export: WireCoreExport;
+} | {
+    op: "resource";
+    index: number;
+    rep: WireCoreType;
+    dtor: WireCoreDef | null;
+    instance: number;
+};
+export type WireCoreDef = {
+    kind: "export";
+    instance: number;
+    item: WireExportItem;
+} | {
+    kind: "instance-flags";
+    instance: number;
+} | {
+    kind: "trampoline";
+    index: number;
+}
+/**
+ * `CoreDef::UnsafeIntrinsic` (plan v1 / contracts/plan-format.md v0.3).
+ * `intrinsic` is wasmtime's stable symbol name
+ * (`UnsafeIntrinsic::name()`), not an enum ordinal. The executor
+ * materializes `context-{get,set}-i32-{0,1}` as host functions over the
+ * current thread's context storage (definitions.py `canon_context_get` /
+ * `canon_context_set`, lines 2348/2358) and fails at instantiate time on
+ * every other symbol.
+ */
+ | {
+    kind: "unsafe-intrinsic";
+    intrinsic: string;
+} | {
+    kind: "task-may-block";
+};
+export interface WireCoreExport {
+    instance: number;
+    item: WireExportItem;
+}
+export interface WireExportItem {
+    name: string;
+    space: "func" | "table" | "memory" | "global" | "tag" | "unknown";
+}
+/**
+ * Trampoline declarations, tag-for-tag with the wasmtime `Trampoline` enum.
+ * 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).
+ */
+export type WireTrampoline = {
+    kind: "lower-import";
+    index: number;
+    lowered: number;
+    options: number;
+    type: number;
+} | {
+    kind: "trap";
+    index: number;
+} | {
+    kind: "enter-sync-call";
+    index: number;
+} | {
+    kind: "exit-sync-call";
+    index: number;
+} | {
+    kind: "task-return";
+    index: number;
+    instance: number;
+    /**
+     * The **raw** wasmtime `TypeTupleIndex` of the task's declared results
+     * (plan v3; in v2 this field held the interned `plan.types` index that
+     * `resultType` now carries). It is the key FACT's `prepare-call` passes
+     * as `task_return_type` at runtime, so it is what lets a FACT callee task
+     * find its own declared result type.
+     */
+    results: number;
+    /**
+     * `results` interned into `plan.types` as a tuple type (plan v3,
+     * contracts/plan-format.md v3 amendment 3). `null` is accepted on the
+     * wire for a task with no declared result type; the current producer
+     * never emits it (wasmtime's `TaskReturn.results` is not an `Option` —
+     * a no-result task carries the empty tuple).
+     */
+    resultType: number | null;
+    options: number;
+} | {
+    kind: "resource-drop" | "resource-new" | "resource-rep";
+    index: number;
+    instance: number;
+    resource: number;
+} | {
+    kind: string;
+    index: number;
+    [field: string]: unknown;
+};
+export interface WireCanonicalOptions {
+    instance: number;
+    stringEncoding: "utf8" | "utf16" | "latin1+utf16";
+    memory: number | null;
+    realloc: number | null;
+    postReturn: number | null;
+    callback: number | null;
+    async: boolean;
+    cancellable: boolean;
+    coreType: {
+        params: WireCoreType[];
+        results: WireCoreType[];
+    };
+}
+/** descriptor-ir.md ValType JSON (nested structurally). */
+export type WireValType = {
+    kind: "bool" | "s8" | "u8" | "s16" | "u16" | "s32" | "u32" | "s64" | "u64" | "f32" | "f64" | "char" | "string" | "error-context";
+} | {
+    kind: "list";
+    element: WireValType;
+    length?: number;
+} | {
+    kind: "record";
+    fields: {
+        label: string;
+        type: WireValType;
+    }[];
+} | {
+    kind: "tuple";
+    elements: WireValType[];
+} | {
+    kind: "variant";
+    cases: {
+        label: string;
+        type: WireValType | null;
+    }[];
+} | {
+    kind: "enum";
+    labels: string[];
+} | {
+    kind: "option";
+    type: WireValType;
+} | {
+    kind: "result";
+    ok: WireValType | null;
+    err: WireValType | null;
+} | {
+    kind: "map";
+    key: WireValType;
+    value: WireValType;
+} | {
+    kind: "flags";
+    labels: string[];
+} | {
+    kind: "own";
+    resource: number;
+} | {
+    kind: "borrow";
+    resource: number;
+} | {
+    kind: "stream";
+    element: WireValType | null;
+} | {
+    kind: "future";
+    element: WireValType | null;
+};
+export type WireTypeDecl = {
+    kind: "func";
+    params: {
+        label: string;
+        type: WireValType;
+    }[];
+    results: WireValType[];
+    async: boolean;
+} | WireValType;
+export type WireResourceTable = {
+    kind: "concrete";
+    resource: number;
+    instance: number;
+} | {
+    kind: "abstract";
+    id: number;
+};
+/** One stream or future table (plan v2). */
+/** One error-context table: the owning component instance, nothing else. */
+export interface WireErrorContextTable {
+    instance: number;
+}
+export interface WireAsyncTable {
+    element: WireValType | null;
+    instance: number;
+}
+/** One imported resource type: back-reference into `plan.imports`. */
+export interface WireImportedResource {
+    /** `RuntimeImportIndex` — index into `plan.imports`. */
+    import: number;
+}
+export interface WireImport {
+    name: string;
+    path: string[];
+    kind: string;
+    type?: number;
+}
+export type WireExport = {
+    kind: "lifted-func";
+    name: string;
+    coreDef: WireCoreDef;
+    options: number;
+    type: number;
+} | {
+    kind: "instance";
+    name: string;
+    exports: WireExport[];
+} | {
+    kind: "type";
+    name: string;
+    type: WireTypeExport;
+}
+/**
+ * An exported embedded core module; `module` indexes the static module
+ * space (`modules`). plan-format.md v4 amendment 2.
+ */
+ | {
+    kind: "module";
+    name: string;
+    module: number;
+};
+export type WireTypeExport = {
+    kind: "resource";
+    resource: number;
+} | {
+    kind: "value";
+    type: number;
+};
+/**
+ * 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).
+ */
+export interface WireEnvelope {
+    plan?: WirePlan;
+    adapters?: {
+        file: string;
+        wasm: string;
+    }[];
+    /** Failure message (v0.1 shape; unchanged meaning). */
+    error?: string;
+    /**
+     * Structured verdict accompanying `error` (contracts v0.2 proposal). Absent
+     * from v0.1 producers; consumers must tolerate that (treat as phase
+     * `"internal"`, i.e. "not a statement about the component").
+     */
+    errorDetail?: WireErrorDetail;
+}
+/**
+ * Structured translation failure.
+ *
+ * `phase` is the load-bearing field: only `"validation"` means *the component
+ * is invalid/malformed* — the verdict the official suite's `assert_invalid` /
+ * `assert_malformed` commands require. `"unsupported"` means the component is
+ * 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.
+ */
+export interface WireErrorDetail {
+    phase: "validation" | "unsupported" | "internal";
+    message: string;
+    /** Full error chain, diagnostics only. */
+    detail?: string;
+}