@polyengine/runtime 0.1.0-pre.g633468a

package/types/cabi/context.d.ts

@@ -0,0 +1,59 @@
+import type { MemInst } from "./memory.js";
+import type { StringEncoding } from "./types.js";
+import type { Table } from "./handles.js";
+/**
+ * definitions.py realloc signature: (original_ptr, original_size, alignment,
+ * new_size) -> ptr. Addresses as JS numbers (see memory.ts).
+ */
+export type ReallocFn = (originalPtr: number, originalSize: number, alignment: number, newSize: number) => number;
+export interface LiftOptions {
+    stringEncoding: StringEncoding;
+    memory: MemInst | null;
+}
+export interface LiftLowerOptions extends LiftOptions {
+    realloc: ReallocFn | null;
+}
+export interface CanonicalOptions extends LiftLowerOptions {
+    postReturn: (() => void) | null;
+    async_: boolean;
+    callback: unknown | null;
+}
+export declare function mkCanonicalOptions(partial?: Partial<CanonicalOptions>): CanonicalOptions;
+/** Memory accessor that traps-or-asserts like `cx.opts.memory` derefs. */
+export declare function requireMemory(opts: LiftOptions): MemInst;
+/**
+ * Minimal component-instance stand-in for the value interpreter: a handle
+ * table plus the `may_leave` gate. The full ComponentInstance (may_enter,
+ * backpressure, threads, ...) belongs to the deferred task machinery.
+ */
+export interface ComponentInstanceLike {
+    handles: Table<unknown>;
+    mayLeave: boolean;
+}
+/**
+ * Borrow scopes (definitions.py `LiftLowerContext.borrow_scope`):
+ * - lifting a borrow requires the *subtask* side: `add_lender`.
+ * - lowering a borrow requires the *task* side: `num_borrows`.
+ * The real Task/Subtask classes are deferred; these are the minimal
+ * interfaces the value code needs.
+ */
+export interface SubtaskBorrowScope {
+    addLender(h: import("./handles.js").ResourceHandle): void;
+}
+export interface TaskBorrowScope {
+    numBorrows: number;
+}
+export declare class LiftLowerContext {
+    opts: LiftLowerOptions;
+    inst: ComponentInstanceLike | null;
+    borrowScope: SubtaskBorrowScope | TaskBorrowScope | null;
+    constructor(opts: LiftLowerOptions, inst?: ComponentInstanceLike | null, borrowScope?: SubtaskBorrowScope | TaskBorrowScope | null);
+    /**
+     * definitions.py `LiftLowerContext.reallocate` routes the call through
+     * canon_lift (reentrance bookkeeping and may_leave toggling around a
+     * guest-side realloc export). v1 simplification: call the provided realloc
+     * directly. The full path returns with the task machinery.
+     */
+    reallocate(old: number, oldByteLength: number, alignment: number, newByteLength: number): number;
+    allocate(alignment: number, byteLength: number): number;
+}

package/types/cabi/flatten.d.ts

@@ -0,0 +1,14 @@
+import { type CaseType, type CoreFuncType, type CoreType, type FieldType, type FuncType, type ValType } from "./types.js";
+import type { CanonicalOptions, LiftOptions } from "./context.js";
+export declare const MAX_FLAT_PARAMS = 16;
+export declare const MAX_FLAT_ASYNC_PARAMS = 4;
+export declare let MAX_FLAT_RESULTS: number;
+export declare function setMaxFlatResultsForTesting(n: number): number;
+export type FlattenContext = "lift" | "lower";
+export declare function flattenFunctype(opts: CanonicalOptions, ft: FuncType, context: FlattenContext): CoreFuncType;
+export declare function flattenTypes(ts: ValType[], opts: LiftOptions): CoreType[];
+export declare function flattenType(t: ValType, opts: LiftOptions): CoreType[];
+export declare function flattenList(elemType: ValType, maybeLength: number | null, opts: LiftOptions): CoreType[];
+export declare function flattenRecord(fields: FieldType[], opts: LiftOptions): CoreType[];
+export declare function flattenVariant(cases: CaseType[], opts: LiftOptions): CoreType[];
+export declare function join(a: CoreType, b: CoreType): CoreType;

package/types/cabi/float.d.ts

@@ -0,0 +1,14 @@
+export declare const CANONICAL_FLOAT32_NAN = 2143289344;
+export declare const CANONICAL_FLOAT64_NAN = 9221120237041090560n;
+export declare function coreF32ReinterpretI32(i: number): number;
+export declare function coreF64ReinterpretI64(i: bigint): number;
+export declare function coreI32ReinterpretF32(f: number): number;
+export declare function coreI64ReinterpretF64(f: number): bigint;
+export declare function canonicalizeNan32(f: number): number;
+export declare function canonicalizeNan64(f: number): number;
+export declare function decodeI32AsFloat(i: number): number;
+export declare function decodeI64AsFloat(i: bigint): number;
+export declare function maybeScrambleNan32(f: number): number;
+export declare function maybeScrambleNan64(f: number): number;
+export declare function encodeFloatAsI32(f: number): number;
+export declare function encodeFloatAsI64(f: number): bigint;

package/types/cabi/handles.d.ts

@@ -0,0 +1,70 @@
+import type { ComponentInstanceLike, LiftLowerContext, TaskBorrowScope } from "./context.js";
+import type { BorrowType, OwnType, ResourceTypeInfo } from "./types.js";
+export declare class Table<T> {
+    static readonly MAX_LENGTH: number;
+    array: (T | null)[];
+    free: number[];
+    get(i: number): T;
+    add(e: T): number;
+    remove(i: number): T;
+    [Symbol.iterator](): Iterator<T>;
+}
+export declare class ResourceHandle {
+    rt: ResourceTypeInfo;
+    rep: number;
+    own: boolean;
+    borrowScope: TaskBorrowScope | null;
+    numLends: number;
+    constructor(rt: ResourceTypeInfo, rep: number, own: boolean, borrowScope?: TaskBorrowScope | null);
+}
+export declare function liftOwn(cx: LiftLowerContext, i: number, t: OwnType): number;
+export declare function liftBorrow(cx: LiftLowerContext, i: number, t: BorrowType): number;
+export declare function lowerOwn(cx: LiftLowerContext, rep: number, t: OwnType): number;
+export declare function lowerBorrow(cx: LiftLowerContext, rep: number, t: BorrowType): number;
+export declare function canonResourceNew(inst: ComponentInstanceLike, rt: ResourceTypeInfo, rep: number): number;
+/**
+ * Invoke a resource destructor through the reference's entry bracket.
+ *
+ * definitions.py `canon_resource_drop` (line 2319) does not call `rt.dtor`
+ * directly. It builds the dtor into a function instance and calls it through
+ * `Store.lift` / `Store.lower` (lines 2330-2333):
+ *
+ * ```python
+ *   dtor = rt.dtor or (lambda rep: [])
+ *   callee = inst.store.lift(dtor, ft, opts, rt.impl)
+ *   caller = inst.store.lower(callee, ft, opts, inst)
+ *   caller([h.rep])
+ * ```
+ *
+ * so the dtor inherits `Store.lift`'s gate verbatim (lines 579-584):
+ * `trap_if(not inst.may_enter_from(caller))`, `enter_from(caller)`, the call,
+ * then `leave_to(caller)` — which a trap skips, leaving the *implementing*
+ * instance permanently unenterable (poisoned).
+ *
+ * Two consequences that are easy to get wrong, both taken from the reference
+ * rather than from intuition:
+ *
+ *  - the bracket runs even when `rt.dtor is None` (the `or (lambda rep: [])`
+ *    above), so a dtor-less resource whose impl instance is mid-execution is
+ *    still a trap. `may_enter_from`/`enter_from` walk `entering_set(caller)`
+ *    (line 230), which is empty when the caller *is* the implementing
+ *    instance — that, not a special case, is the same-instance exemption:
+ *    a component dropping a handle to its own resource never traps.
+ *  - poisoning applies to `rt.impl`, not to the dropping instance. The
+ *    dropper's own bracket (its `Store.lift` frame) is broken by the same
+ *    propagating trap at its own level; here only the callee is retired.
+ *
+ * Capability signals (`NeedsJspi`, `PendingCapability`) are not traps — see
+ * `isCapabilitySignal` in exec/boundary.ts — so they release the gate.
+ *
+ * SCOPE (#160): this is the **guest-initiated** path only. A guest-initiated
+ * drop must complete synchronously (the reference lifts the dtor with
+ * `async_ = False`), so a thenable here is a trap. The host-initiated path
+ * used to share this function with an `allowAsync` flag that held the entry
+ * bracket across the dtor's promise; it now goes through the full lift
+ * harness instead (`hostDtorCall` in exec/boundary.ts), which is what
+ * definitions.py actually does and what unwedges #160.
+ */
+export declare function callDtorGated(rt: ResourceTypeInfo, rep: number, caller: unknown): void;
+export declare function canonResourceDrop(inst: ComponentInstanceLike, rt: ResourceTypeInfo, i: number): void;
+export declare function canonResourceRep(inst: ComponentInstanceLike, rt: ResourceTypeInfo, i: number): number;

package/types/cabi/layout.d.ts

@@ -0,0 +1,13 @@
+import { type CaseType, type FieldType, type PtrType, type ValType } from "./types.js";
+export declare function alignTo(ptr: number, alignment: number): number;
+export declare function alignment(t: ValType, ptrType: PtrType): number;
+export declare function alignmentList(elemType: ValType, maybeLength: number | null, ptrType: PtrType): number;
+export declare function alignmentRecord(fields: FieldType[], ptrType: PtrType): number;
+export declare function alignmentVariant(cases: CaseType[], ptrType: PtrType): number;
+export declare function maxCaseAlignment(cases: CaseType[], ptrType: PtrType): number;
+export declare function alignmentFlags(labels: string[]): number;
+export declare function elemSize(t: ValType, ptrType: PtrType): number;
+export declare function elemSizeList(elemType: ValType, maybeLength: number | null, ptrType: PtrType): number;
+export declare function elemSizeRecord(fields: FieldType[], ptrType: PtrType): number;
+export declare function elemSizeVariant(cases: CaseType[], ptrType: PtrType): number;
+export declare function elemSizeFlags(labels: string[]): number;

package/types/cabi/lift.d.ts

@@ -0,0 +1,25 @@
+import { type LiftLowerContext } from "./context.js";
+import { type CaseType, type ComponentValue, type CoreType, type CoreValue, type FieldType, type ValType } from "./types.js";
+/** Anything lift can pull core values from (CoreValueIter or the variant
+ * coercion iterator). */
+export interface ValueIter {
+    next(t: CoreType): CoreValue;
+}
+export declare class CoreValueIter implements ValueIter {
+    values: CoreValue[];
+    i: number;
+    constructor(values: CoreValue[]);
+    next(t: CoreType): CoreValue;
+    done(): boolean;
+}
+export declare function liftFlat(cx: LiftLowerContext, vi: ValueIter, t: ValType): ComponentValue;
+export declare function liftFlatUnsigned32(vi: ValueIter, tWidth: number): number;
+export declare function liftFlatUnsigned64(vi: ValueIter): bigint;
+export declare function liftFlatSigned32(vi: ValueIter, tWidth: number): number;
+export declare function liftFlatSigned64(vi: ValueIter): bigint;
+export declare function liftFlatString(cx: LiftLowerContext, vi: ValueIter): ComponentValue;
+export declare function liftFlatList(cx: LiftLowerContext, vi: ValueIter, elemType: ValType, maybeLength: number | null): ComponentValue;
+export declare function liftFlatRecord(cx: LiftLowerContext, vi: ValueIter, fields: FieldType[]): ComponentValue;
+export declare function liftFlatVariant(cx: LiftLowerContext, vi: ValueIter, cases: CaseType[]): ComponentValue;
+export declare function wrapI64ToI32(i: bigint): number;
+export declare function liftFlatFlags(vi: ValueIter, labels: string[]): ComponentValue;

package/types/cabi/load.d.ts

@@ -0,0 +1,14 @@
+import { type LiftLowerContext } from "./context.js";
+import { type CaseType, type ComponentValue, type FieldType, type ValType } from "./types.js";
+export declare const MAX_LIST_BYTE_LENGTH: number;
+export declare function load(cx: LiftLowerContext, ptr: number, t: ValType): ComponentValue;
+export declare function convertIntToBool(i: number): boolean;
+export declare function loadList(cx: LiftLowerContext, ptr: number, elemType: ValType, maybeLength: number | null): ComponentValue;
+export declare function loadListFromRange(cx: LiftLowerContext, ptr: number | bigint, length: number | bigint, elemType: ValType): ComponentValue;
+export declare function loadListFromValidRange(cx: LiftLowerContext, ptr: number, length: number, elemType: ValType): ComponentValue;
+export declare function loadRecord(cx: LiftLowerContext, ptr: number, fields: FieldType[]): ComponentValue;
+export declare function loadVariant(cx: LiftLowerContext, ptr: number, cases: CaseType[]): ComponentValue;
+export declare function loadFlags(cx: LiftLowerContext, ptr: number, labels: string[]): ComponentValue;
+export declare function unpackFlagsFromInt(i: number, labels: string[]): {
+    [label: string]: ComponentValue;
+};

package/types/cabi/lower.d.ts

@@ -0,0 +1,10 @@
+import { type LiftLowerContext } from "./context.js";
+import { type CaseType, type ComponentValue, type CoreValue, type FieldType, type ValType } from "./types.js";
+export declare function lowerFlat(cx: LiftLowerContext, v: ComponentValue, t: ValType): CoreValue[];
+export declare function lowerFlatSigned32(i: number): CoreValue[];
+export declare function lowerFlatSigned64(i: bigint): CoreValue[];
+export declare function lowerFlatString(cx: LiftLowerContext, v: string): CoreValue[];
+export declare function lowerFlatList(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, elemType: ValType, maybeLength: number | null): CoreValue[];
+export declare function lowerFlatRecord(cx: LiftLowerContext, v: Record<string, ComponentValue>, fields: FieldType[]): CoreValue[];
+export declare function lowerFlatVariant(cx: LiftLowerContext, v: Record<string, ComponentValue>, cases: CaseType[]): CoreValue[];
+export declare function lowerFlatFlags(v: Record<string, ComponentValue>, labels: string[]): CoreValue[];

package/types/cabi/memory.d.ts

@@ -0,0 +1,58 @@
+import type { PtrType } from "./types.js";
+export declare function ptrSize(ptrType: PtrType): 4 | 8;
+/**
+ * `MemInst` caches its `Uint8Array`/`DataView` at construction time and never
+ * re-derives them. That is only sound for a memory that cannot grow within
+ * this instance's lifetime: `memory.grow` (guest-triggered or host-triggered)
+ * detaches the backing `ArrayBuffer`, and a cached view over a detached
+ * buffer reads/writes garbage rather than trapping.
+ *
+ * Production call/lift/lower paths do NOT construct `MemInst` directly against
+ * a live, growable `WebAssembly.Memory` for this reason: the executor
+ * re-derives a fresh view per access via `LiveMemory`
+ * (`exec/boundary.ts:97-160`), which is grow-safe. `MemInst` is for contexts
+ * where the buffer is known fixed for the duration (tests, or a snapshot
+ * already taken).
+ */
+export declare class MemInst {
+    readonly bytes: Uint8Array;
+    readonly view: DataView;
+    readonly addrType: PtrType;
+    constructor(bytes: Uint8Array, addrType: PtrType);
+    get length(): number;
+    ptrType(): PtrType;
+    ptrSize(): 4 | 8;
+}
+/**
+ * Convert a (possibly BigInt) address/length to a JS number index, after the
+ * caller has already trapped on any out-of-bounds condition using exact
+ * (BigInt) arithmetic. Asserts rather than traps: by this point the value is
+ * known small.
+ */
+export declare function asIndex(v: number | bigint): number;
+export declare function loadIntU(mem: MemInst, ptr: number, nbytes: 1 | 2 | 4): number;
+export declare function loadIntU(mem: MemInst, ptr: number, nbytes: 8): bigint;
+export declare function loadIntS(mem: MemInst, ptr: number, nbytes: 1 | 2 | 4): number;
+export declare function loadIntS(mem: MemInst, ptr: number, nbytes: 8): bigint;
+/** Load a pointer-sized unsigned integer (returns bigint for i64 memories). */
+export declare function loadPtr(mem: MemInst, ptr: number): number | bigint;
+export declare function storeInt(mem: MemInst, v: number | bigint, ptr: number, nbytes: 1 | 2 | 4 | 8, signed?: boolean): void;
+/** Store a pointer-sized unsigned integer, taking a JS number. */
+export declare function storePtr(mem: MemInst, v: number, ptr: number): void;
+/** Bounds-checked byte-range read (callers trap on OOB before calling). */
+export declare function bytesOf(mem: MemInst, ptr: number, len: number): Uint8Array;
+/** Copy bytes into memory; used by string/list stores after trap checks. */
+export declare function writeBytes(mem: MemInst, ptr: number, src: Uint8Array): void;
+/**
+ * Exact bounds check usable with i64-lane values: traps when
+ * `ptr + byteLength > len(memory)`, computed without precision loss.
+ *
+ * `what` selects the trap wording only. Callers that are checking a pointer
+ * *returned by realloc* pass wasmtime's phrasing for that case
+ * ("realloc return: beyond end of memory",
+ * `wasmtime/src/runtime/component/func/options.rs:185`) and the string-lift
+ * path passes its own ("string pointer/length out of bounds of memory",
+ * `.../func/typed.rs:1528`), because the official suite matches those texts.
+ * The default is unchanged.
+ */
+export declare function trapIfRangeExceedsMemory(mem: MemInst, ptr: number | bigint, byteLength: number | bigint, what?: string): void;

package/types/cabi/mod.d.ts

@@ -0,0 +1,15 @@
+export * from "./trap.js";
+export * from "./types.js";
+export * from "./memory.js";
+export * from "./layout.js";
+export * from "./float.js";
+export * from "./context.js";
+export * from "./handles.js";
+export * from "./strings.js";
+export * from "./bulk_lists.js";
+export * from "./load.js";
+export * from "./store.js";
+export * from "./flatten.js";
+export * from "./lift.js";
+export * from "./lower.js";
+export * from "./values.js";

package/types/cabi/store.d.ts

@@ -0,0 +1,12 @@
+import { type LiftLowerContext } from "./context.js";
+import { type CaseType, type ComponentValue, type FieldType, type ValType } from "./types.js";
+export declare function store(cx: LiftLowerContext, v: ComponentValue, t: ValType, ptr: number): void;
+export declare function storeList(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, ptr: number, elemType: ValType, maybeLength: number | null): void;
+export declare function storeListIntoRange(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, elemType: ValType): [number, number];
+export declare function storeListIntoValidRange(cx: LiftLowerContext, v: ArrayLike<ComponentValue>, ptr: number, elemType: ValType): void;
+export declare function storeRecord(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, fields: FieldType[]): void;
+/** definitions.py match_case: the value is a single-key object. */
+export declare function matchCase(v: Record<string, ComponentValue>, cases: CaseType[]): [number, ComponentValue];
+export declare function storeVariant(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, cases: CaseType[]): void;
+export declare function storeFlags(cx: LiftLowerContext, v: Record<string, ComponentValue>, ptr: number, labels: string[]): void;
+export declare function packFlagsIntoInt(v: Record<string, ComponentValue>, labels: string[]): number;

package/types/cabi/strings.d.ts

@@ -0,0 +1,23 @@
+import { type LiftLowerContext } from "./context.js";
+import type { PtrType } from "./types.js";
+export declare const REALLOC_I32_MAX: number;
+export declare const REALLOC_MISALIGNED = "realloc return: result not aligned";
+export declare const REALLOC_OOB = "realloc return: beyond end of memory";
+export declare const MAX_STRING_BYTE_LENGTH: number;
+/** definitions.py utf16_tag: the high bit of a pointer-sized integer. */
+export declare function utf16TagBig(ptrType: PtrType): bigint;
+/** WebIDL USVString conversion: unpaired surrogates -> U+FFFD. */
+export declare function toWellFormed(s: string): string;
+export declare function encodeUtf16Le(s: string): Uint8Array;
+export declare function loadString(cx: LiftLowerContext, ptr: number): string;
+export declare function loadStringFromRange(cx: LiftLowerContext, ptr: number | bigint, taggedCodeUnits: number | bigint): string;
+export declare function storeString(cx: LiftLowerContext, v: string, ptr: number): void;
+/**
+ * definitions.py store_string_into_range, specialized to a JS-string source
+ * (src_encoding = 'utf16', src_code_units = s.length — see module comment).
+ * Returns [ptr, tagged_code_units]; tagged units as bigint because the
+ * latin1+utf16 tag bit exceeds Number.MAX_SAFE_INTEGER on i64 memories.
+ */
+export declare function storeStringIntoRange(cx: LiftLowerContext, src: string): [number, bigint];
+export declare function convertI32ToChar(i: number): string;
+export declare function charToI32(c: string): number;

package/types/cabi/trap.d.ts

@@ -0,0 +1,11 @@
+export { isTrap, Trap } from "@polyengine/protocol";
+export declare function trap(message?: string): never;
+export declare function trapIf(cond: boolean, message?: string): void;
+export declare class AssertionError extends Error {
+    constructor(message?: string);
+}
+export declare function assert_(cond: boolean, message?: string): asserts cond;
+/** Marks a definitions.py code path this v1 interpreter does not port yet. */
+export declare class NotImplemented extends Error {
+    constructor(what: string);
+}

package/types/cabi/types.d.ts

@@ -0,0 +1,206 @@
+/** Core wasm value types, as strings (mirrors definitions.py flat types). */
+export type CoreType = "i32" | "i64" | "f32" | "f64";
+/** Pointer type of a linear memory: wasm32 or wasm64. */
+export type PtrType = "i32" | "i64";
+/**
+ * A flat core function signature (definitions.py `CoreFuncType`).
+ * Equality is structural (see `coreFuncTypeEquals`).
+ */
+export interface CoreFuncType {
+    params: CoreType[];
+    results: CoreType[];
+}
+export declare function coreFuncTypeEquals(a: CoreFuncType, b: CoreFuncType): boolean;
+/** String encodings selectable by canonical options. */
+export type StringEncoding = "utf8" | "utf16" | "latin1+utf16";
+/**
+ * Opaque token standing in for the implementing component instance of a
+ * resource type (definitions.py `ResourceType.impl`). The value interpreter
+ * only ever compares these by identity.
+ */
+export interface InstanceLike {
+    handles: unknown;
+    mayLeave: boolean;
+}
+/**
+ * definitions.py `ResourceType`: identity + implementing instance + optional
+ * destructor. Compared by object identity everywhere.
+ *
+ * `dtorHost` is the **host-initiated**-drop entry (#85, reshaped by #160):
+ * the dtor built as a fully LIFTED sync function — definitions.py
+ * `canon_resource_drop` (line 2319) `inst.store.lift(dtor, ft, opts,
+ * rt.impl)` — so the destructor's activation gets a real Task/Thread, the
+ * reentrance bracket is released at its first park, and its suspension
+ * points are resumable by the scheduler. It is wired by exec/executor.ts
+ * (jspi-`promising` entry only when the dtor is suspension-capable, docs §7)
+ * and called through `hostDtorCall` (exec/boundary.ts), which also fills it
+ * in lazily for tokens built directly. It returns `undefined` or a Promise,
+ * so it is NOT callable from inside a guest activation.
+ *
+ * Guest-initiated drops (`callDtorGated`) always use `dtor` directly: they
+ * must complete synchronously (reference lifts the dtor with
+ * `async_ = False`), and any thenable there is a trap.
+ */
+export declare class ResourceTypeInfo {
+    impl: InstanceLike | null;
+    dtor: ((rep: number) => void) | null;
+    dtorHost: ((rep: number) => unknown) | null;
+    constructor(impl: InstanceLike | null, dtor?: ((rep: number) => void) | null, dtorHost?: ((rep: number) => unknown) | null);
+}
+export type PrimKind = "bool" | "s8" | "u8" | "s16" | "u16" | "s32" | "u32" | "s64" | "u64" | "f32" | "f64" | "char" | "string";
+export interface PrimType {
+    kind: PrimKind;
+}
+export interface ErrorContextType {
+    kind: "error-context";
+}
+export interface ListType {
+    kind: "list";
+    element: ValType;
+    /** Fixed-length list when present (list<t, n>). */
+    length?: number;
+}
+export interface FieldType {
+    label: string;
+    type: ValType;
+}
+export interface RecordType {
+    kind: "record";
+    fields: FieldType[];
+}
+export interface TupleType {
+    kind: "tuple";
+    elements: ValType[];
+}
+export interface CaseType {
+    label: string;
+    type: ValType | null;
+}
+export interface VariantType {
+    kind: "variant";
+    cases: CaseType[];
+}
+export interface EnumType {
+    kind: "enum";
+    labels: string[];
+}
+export interface OptionType {
+    kind: "option";
+    type: ValType;
+}
+export interface ResultType {
+    kind: "result";
+    ok: ValType | null;
+    error: ValType | null;
+}
+export interface MapType {
+    kind: "map";
+    key: ValType;
+    value: ValType;
+}
+export interface FlagsType {
+    kind: "flags";
+    labels: string[];
+}
+export interface OwnType {
+    kind: "own";
+    rt: ResourceTypeInfo;
+}
+export interface BorrowType {
+    kind: "borrow";
+    rt: ResourceTypeInfo;
+}
+export interface StreamType {
+    kind: "stream";
+    element: ValType | null;
+}
+export interface FutureType {
+    kind: "future";
+    element: ValType | null;
+}
+export type ValType = PrimType | ErrorContextType | ListType | RecordType | TupleType | VariantType | EnumType | OptionType | ResultType | MapType | FlagsType | OwnType | BorrowType | StreamType | FutureType;
+/**
+ * definitions.py `FuncType`, without parameter/result names (names do not
+ * affect the ABI; bindings generation reads WIT instead — docs/architecture.md §9).
+ * `results` holds zero or one type in current CM, but stays a list to mirror
+ * the reference (`FuncType.result`).
+ */
+export interface FuncType {
+    params: ValType[];
+    results: ValType[];
+    async?: boolean;
+}
+/**
+ * Host-side value representation produced by lifting / consumed by lowering:
+ *   bool         -> boolean
+ *   u8..u32, s8..s32, f32, f64 -> number
+ *   u64, s64     -> bigint
+ *   char         -> single-code-point string
+ *   string       -> string (plain; see README on dropped encoding provenance)
+ *   list<u8>     -> Uint8Array (copy; docs/architecture.md §7) — other lists -> Array
+ *   record       -> { [fieldLabel]: value }
+ *   tuple        -> despecialized record { "0": v0, "1": v1, ... }
+ *   variant/enum/option/result -> single-key object { [caseLabel]: payload|null }
+ *   flags        -> { [label]: boolean }
+ *   own/borrow   -> number (the resource rep at this layer)
+ * These mirror definitions.py's Python shapes; final host-facing bindings
+ * representations are an open question (README).
+ */
+/**
+ * Opaque host token for the async value types.
+ *
+ * `stream`, `future` and `error-context` do not lift to plain data: the
+ * reference's `lift_async_value` (definitions.py line 1530) yields the
+ * *shared* stream/future object itself, because its identity is the value —
+ * two components holding ends of one stream must see each other's copies.
+ * Concretely these are `SharedStreamImpl`, `SharedFutureImpl` and
+ * `ErrorContext` instances (runtime/src/task/streams.ts); they are declared
+ * opaquely here to keep `cabi/types.ts` free of a dependency on the task
+ * layer. Host code should treat one as a token and pass it back unchanged.
+ *
+ * LIMITATION: this brand is *structural*, so an all-optional interface admits
+ * any object — it documents intent, it does not enforce it. The enforcement is
+ * at the lowering sites, which `assert_` on the concrete class before using a
+ * value (`lowerStream`/`lowerFuture` in cabi/async_values.ts check
+ * `instanceof SharedStreamImpl`/`SharedFutureImpl`). A nominal brand would
+ * need a required property, which the real classes could not satisfy without
+ * cabi importing the task layer — the cycle this declaration exists to avoid.
+ */
+export interface AsyncValue {
+    readonly __asyncValue?: never;
+}
+export type ComponentValue = AsyncValue | boolean | number | bigint | string | null | Uint8Array | ComponentValue[] | {
+    [label: string]: ComponentValue;
+};
+/** Core (flat) values: numbers for i32/f32/f64 lanes, bigints for i64 lanes. */
+export type CoreValue = number | bigint;
+export type DespecializedValType = Exclude<ValType, TupleType | EnumType | OptionType | ResultType | MapType>;
+export declare function despecialize(t: ValType): DespecializedValType;
+export declare function discriminantType(cases: CaseType[]): PrimType;
+export declare function containsBorrow(t: ValType | null): boolean;
+export declare function containsAsyncValue(t: ValType | null): boolean;
+export declare function contains(t: ValType | null, p: (t: DespecializedValType) => boolean): boolean;
+/**
+ * Structural `ValType` equality.
+ *
+ * CONTRACT (bugfix, TRACK C2-D; generalized during the #18 tls smoke): naive
+ * `JSON.stringify(a) === JSON.stringify(b)` recurses into `own`/`borrow`'s
+ * `ResourceTypeInfo` — a class whose `impl` field is documented "Compared by
+ * object identity everywhere" (see `ResourceTypeInfo` above) and which cycles
+ * back to the owning instance state (`impl.handles` holds live resource
+ * tables that reference their types), so `JSON.stringify` throws
+ * `TypeError: Converting circular structure to JSON` on ANY type containing
+ * `own<R>`/`borrow<R>` at any depth. First hit by `task.return` result types
+ * (C2-D, polymorph-test's `list<own<test-case>>`), then by stream/future
+ * element types (polymorph-tls streams carrying resource-bearing payloads).
+ * Object-identity types (`ResourceTypeInfo`) are compared by reference, per
+ * the documented invariant.
+ */
+export declare function valTypesEqual(a: ValType[], b: ValType[]): boolean;
+export declare function valTypeEqual(a: ValType, b: ValType): boolean;
+/**
+ * Cycle-safe display form for diagnostics. `JSON.stringify(t)` is UNSAFE on
+ * any resource-bearing type (see `valTypeEqual`'s contract note); this prints
+ * the structural shape and elides `ResourceTypeInfo` identities.
+ */
+export declare function fmtValType(t: ValType | null): string;

package/types/cabi/values.d.ts

@@ -0,0 +1,5 @@
+import { type CoreValueIter, type ValueIter } from "./lift.js";
+import { type LiftLowerContext } from "./context.js";
+import type { ComponentValue, CoreValue, ValType } from "./types.js";
+export declare function liftFlatValues(cx: LiftLowerContext, maxFlat: number, vi: CoreValueIter, ts: ValType[]): ComponentValue[];
+export declare function lowerFlatValues(cx: LiftLowerContext, maxFlat: number, vs: ComponentValue[], ts: ValType[], outParam?: ValueIter | null): CoreValue[];