@loopdive/js2 0.57.0

package/dist/codegen/array-methods.d.ts

@@ -0,0 +1,68 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { VOID_RESULT } from './shared.js';
+/**
+ * Emit a bounds-checked array.get.  Stack must contain [arrayref, i32 index].
+ * If the index is out of bounds (< 0 or >= array.len), a default value for the
+ * element type is produced instead of trapping.
+ *
+ * #1396 — `useUndefinedSentinel` (default false): when true AND `elementType`
+ * is `externref`/`ref_extern`, the OOB else-branch pushes the JS `undefined`
+ * value (via `__get_undefined` host import) instead of `ref.null.extern`.
+ * Required by destructuring callers — JS spec §13.7.5.5 fires defaults only
+ * for `undefined`, not for `null`, and `ref.null.extern` surfaces to JS as
+ * `null` causing `__extern_is_undefined` to return 0 → default never fires
+ * for OOB extern-array reads (~320 fails in `for-of/dstr`, ~171 in
+ * `assignment/dstr`).
+ */
+export declare function emitBoundsCheckedArrayGet(fctx: FunctionContext, arrTypeIdx: number, elementType: ValType, ctx?: CodegenContext, useUndefinedSentinel?: boolean, signedness?: "s" | "u"): void;
+/**
+ * Clamp an index for JS array methods: if idx < 0, idx = max(0, len + idx);
+ * also clamp to max len.  idxLocal is updated in-place.
+ */
+export declare function emitClampIndex(fctx: FunctionContext, idxLocal: number, lenLocal: number): void;
+/**
+ * Clamp a value to be >= 0.  local is updated in-place.
+ */
+export declare function emitClampNonNeg(fctx: FunctionContext, local: number): void;
+/** Resolve array type info from a TS type. Returns null if not a Wasm GC vec struct. */
+export declare function resolveArrayInfo(ctx: CodegenContext, tsType: ts.Type): {
+    vecTypeIdx: number;
+    arrTypeIdx: number;
+    elemType: ValType;
+} | null;
+/**
+ * Compile Array.prototype.METHOD.call(anyReceiver, callback, ...args) for any-typed receivers.
+ * Uses __extern_length + __extern_get_idx to iterate and call_ref for Wasm closure callbacks.
+ * Only handles callbacks that compile to Wasm closures (arrow functions, function declarations).
+ * Returns undefined if the pattern is not handled (caller should fall through).
+ */
+export declare function compileArrayLikePrototypeCall(ctx: CodegenContext, fctx: FunctionContext, callExpr: ts.CallExpression, methodName: string, receiverArg: ts.Expression): ValType | null | typeof VOID_RESULT | undefined;
+/**
+ * Detect and compile Array.prototype.METHOD.call(obj, ...args) patterns.
+ * When `obj` is a shape-inferred array-like variable, we reuse the existing
+ * array method compilers by treating `obj` as the receiver.
+ *
+ * Returns undefined if the pattern is not matched (caller should continue).
+ * Returns ValType | null for successful/failed compilation.
+ */
+export declare function compileArrayPrototypeCall(ctx: CodegenContext, fctx: FunctionContext, callExpr: ts.CallExpression, propAccess: ts.PropertyAccessExpression): ValType | null | typeof VOID_RESULT | undefined;
+/**
+ * Compile array method calls to inline Wasm instructions.
+ * Returns undefined if the call is not an array method (caller should continue).
+ * Returns ValType for successful compilation, VOID_RESULT for void methods,
+ * or null for failed compilation.
+ */
+export declare function compileArrayMethodCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression | ts.ElementAccessExpression, callExpr: ts.CallExpression, receiverType: ts.Type, overrideMethodName?: string, expectedType?: ValType): ValType | null | undefined | typeof VOID_RESULT;
+/**
+ * (#2193 PR-B) Local-driven core of `Array.prototype.slice`: given the receiver
+ * vec already in `vecLocal` and the (already-truncated-to-i32) start in
+ * `startLocal`, produce a new sliced vec. `endLocal === null` means "no explicit
+ * end" (use the receiver length). This is the AST-free entry the proto-member
+ * closure body (`emitArrayProtoMemberBody`) calls after recovering the array
+ * instance from the closure `this` externref. `compileArraySlice` is now a thin
+ * wrapper that compiles the receiver/args into locals then delegates here — so the
+ * direct `a.slice(...)` lowering is behaviour-preserving (pure extraction).
+ */
+export declare function compileArraySliceFromVecLocal(ctx: CodegenContext, fctx: FunctionContext, vecLocal: number, vecTypeIdx: number, arrTypeIdx: number, startLocal: number, endLocal: number | null): ValType;

package/dist/codegen/array-object-proto.d.ts

@@ -0,0 +1,64 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Register `Array.prototype` glue (idempotent) and return its brand, or
+ * `undefined` if the Array brand isn't reserved (should not happen).
+ */
+export declare function ensureArrayNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Object.prototype` glue (idempotent) and return its brand. */
+export declare function ensureObjectNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/**
+ * Register `String.prototype` glue (idempotent) and return its brand. (#1907 /
+ * #1888 S6-b — S4 wrapper protos.) The String brand is pre-reserved in
+ * `BUILTIN_BRAND_TABLE`; this only fills in the member CSV so a bare
+ * `String.prototype` / `String.prototype.<method>` value read resolves host-free
+ * instead of refusing. Reflective member-CLOSURE bodies still degrade to a
+ * catchable TypeError (`emitProtoMemberBodyRefusal`) until per-member native
+ * bodies land — the value-read object itself needs only the member set.
+ */
+export declare function ensureStringNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Number.prototype` glue (idempotent) and return its brand. */
+export declare function ensureNumberNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Boolean.prototype` glue (idempotent) and return its brand. */
+export declare function ensureBooleanNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/**
+ * Register `Date.prototype` glue (idempotent) and return its brand. (#1907 /
+ * #1888 S6-b — S5.) The Date brand is pre-reserved in `BUILTIN_BRAND_TABLE`;
+ * this only fills in the member CSV so a bare `Date.prototype` /
+ * `Date.prototype.<method>` value read resolves host-free instead of refusing.
+ * Reflective member-CLOSURE bodies still degrade to a catchable TypeError until
+ * per-member native bodies land — the value-read OBJECT + `.length`/`.name`
+ * meta folds need only the member set.
+ */
+export declare function ensureDateNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Error.prototype` glue (idempotent) and return its brand. (S6) */
+export declare function ensureErrorNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Map.prototype` glue (idempotent) and return its brand. (S6) */
+export declare function ensureMapNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Set.prototype` glue (idempotent) and return its brand. (S6) */
+export declare function ensureSetNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Function.prototype` glue (idempotent) and return its brand. (S7) */
+export declare function ensureFunctionNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `Symbol.prototype` glue (idempotent) and return its brand. (S7) */
+export declare function ensureSymbolNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `BigInt.prototype` glue (idempotent) and return its brand. (S7) */
+export declare function ensureBigIntNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `WeakMap.prototype` glue (idempotent) and return its brand. (S7) */
+export declare function ensureWeakMapNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/** Register `WeakSet.prototype` glue (idempotent) and return its brand. (S7) */
+export declare function ensureWeakSetNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/**
+ * (#2651 M1 / D2) Register the abstract `%TypedArray%.prototype` glue (idempotent)
+ * and return its brand. This is the single shared member set; every concrete view
+ * proto reuses `TYPED_ARRAY_PROTO_METHODS` (they inherit from this intrinsic), so
+ * binary size stays proportional. The `%TypedArray%` brand is pre-reserved in
+ * `BUILTIN_BRAND_TABLE`.
+ */
+export declare function ensureTypedArrayIntrinsicNativeProtoGlue(ctx: CodegenContext): number | undefined;
+/**
+ * (#2651 M1 / D2) Register a concrete TypedArray view's `<View>.prototype` glue
+ * (idempotent) and return its brand, or `undefined` if `viewName` is not a wired
+ * non-bigint view (caller falls through to the existing refusal). Each view shares
+ * the `%TypedArray%.prototype` member set (`TYPED_ARRAY_PROTO_METHODS`). The brand
+ * is the per-view brand pre-reserved in `BUILTIN_BRAND_TABLE`.
+ */
+export declare function ensureTypedArrayViewNativeProtoGlue(ctx: CodegenContext, viewName: string): number | undefined;

package/dist/codegen/array-reduce-fusion.d.ts

@@ -0,0 +1,31 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext } from './context/types.js';
+/**
+ * A successful match describes which statements to drop from the original
+ * statement list and which to insert in their place. The fused replacement
+ * is two statements: the `let ACC = INIT` declaration (carried over) and a
+ * single fused for-loop.
+ */
+export interface ReduceFusionMatch {
+    /** First index in the parent statement list to remove (the array decl). */
+    startIdx: number;
+    /** Last index (inclusive) to remove (the read-loop). */
+    endIdx: number;
+    /** Synthetic statements to splice in. Length 2: accumulator decl + fused loop. */
+    replacement: ts.Statement[];
+}
+/**
+ * Scan a function body for the fill+reduce shape. Returns matches in
+ * back-to-front order so callers can splice without invalidating later
+ * indices. Empty array means no rewrite.
+ *
+ * Only matches at the top-level of the function body for now — nested
+ * blocks would require alpha-renaming index vars and are out of scope.
+ */
+export declare function detectArrayReduceFusion(ctx: CodegenContext, fnBody: ts.Block | undefined): ReduceFusionMatch[];
+/**
+ * Apply detected fusion matches to the function body's statement list.
+ * Returns a new array of statements with each match replaced by its
+ * synthetic fused-loop pair. Iterates back-to-front so indices stay valid.
+ */
+export declare function applyArrayReduceFusion(stmts: readonly ts.Statement[], matches: ReduceFusionMatch[]): ts.Statement[];

package/dist/codegen/array-to-primitive.d.ts

@@ -0,0 +1,28 @@
+import { CodegenContext } from './context/types.js';
+export declare const ARRAY_TO_PRIMITIVE_STRING = "__array_to_primitive_string";
+/**
+ * Reserve the `__array_to_primitive_string(externref arr) -> externref`
+ * placeholder and return its funcIdx. Body is a bare `unreachable` until
+ * `fillArrayToPrimitive` patches it (after `__extern_length`/`__extern_get_idx`
+ * are registered). Idempotent. Standalone only — the JS-host lane reduces arrays
+ * via the host `__extern_toString` import, so this driver is never reached there.
+ */
+export declare function reserveArrayToPrimitiveString(ctx: CodegenContext): number;
+/**
+ * Fill the reserved `__array_to_primitive_string` body now that
+ * `__extern_length` / `__extern_get_idx` / `$__any_to_string` / `__str_concat`
+ * are all registered. Implements `Array.prototype.join(",")`:
+ *
+ *   result = ""                                   // empty native string
+ *   len    = i32(__extern_length(arr))            // ToLength; non-array → 0 → ""
+ *   for (i = 0; i < len; i++):
+ *     if (i > 0) result = __str_concat(result, ",")
+ *     elem = __extern_get_idx(arr, f64(i))        // externref (null for a hole)
+ *     // §23.1.3.31: a null/undefined element stringifies to "" (NOT "null")
+ *     if (elem != null) result = __str_concat(result, $__any_to_string(any(elem)))
+ *   return extern.convert_any(result)
+ *
+ * No-op when the driver was not reserved or a dependency is missing — the
+ * placeholder `unreachable` stays (unreachable from any live arm in that case).
+ */
+export declare function fillArrayToPrimitive(ctx: CodegenContext): void;

package/dist/codegen/async-cps.d.ts

@@ -0,0 +1,239 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Master gate for the AST-side async CPS lowering.
+ *
+ * Slice 2A (#1042) built the linear single-tail-await state machine and made it
+ * *correct when it runs*: the canonical shapes resolve to the right value
+ * through `Promise_resolve` → `Promise_then2` → continuation, captures and the
+ * `return await` identity tail are handled, and the late-import shift hazard is
+ * removed by the `collectAsyncCpsImports` prepass.
+ *
+ * Flipped **ON** in #1796. The synchronous-consumption regression that kept it
+ * off is resolved by the per-function {@link asyncFnNeedsCps} predicate (#1936):
+ * an async fn is CPS-lowered (returns a real Promise) ONLY when it *genuinely
+ * suspends* — at least one await operand is not statically resolved. Fully
+ * await-elidable bodies (`return await Promise.resolve(42)`, `await 41; ...`)
+ * stay on the legacy synchronous path and keep returning the unwrapped value, so
+ * the `asyncFn() as any as number` "compile away" idiom (#1313/#1727) is
+ * preserved for those. Functions that truly suspend now return a real Promise;
+ * call sites that consume such a result as a raw value cannot be served
+ * synchronously by construction and were already semantically broken under the
+ * legacy fakery — those test cases are migrated to the Promise model in #1796.
+ */
+export declare const ASYNC_CPS_ENABLED = true;
+/**
+ * Result of analysing an async function body for the CPS transform.
+ * Populated by {@link analyzeAsyncBody}, consumed by {@link emitAsyncStateMachine}.
+ */
+export interface AsyncCpsPlan {
+    /** Pre-order list of await points found in the body (by `ts.Node` identity). */
+    readonly awaitPoints: readonly ts.AwaitExpression[];
+    /**
+     * For each await point: the set of live local names that must be captured
+     * into the continuation that resumes after the await. "Live" = referenced in
+     * any statement/expression that executes after the await point.
+     */
+    readonly liveAfterAwait: ReadonlyMap<ts.AwaitExpression, ReadonlySet<string>>;
+    /** Does the body contain a `try`/`catch` that spans an await? (Phase 3B — gated.) */
+    readonly hasTryAcrossAwait: boolean;
+    /** Does the body contain a `throw` that must reject the outer Promise? */
+    readonly hasUncaughtThrow: boolean;
+    /**
+     * For each await point: `true` when its operand is *statically resolved* —
+     * i.e. the awaited value is already settled at compile time and the suspension
+     * is observably a no-op (`await 1`, `await Promise.resolve(x)`, `await` over a
+     * literal/arithmetic-of-literals). When EVERY await in a body is statically
+     * resolved (and the body otherwise matches a CPS-able shape), the function does
+     * not genuinely suspend: it can be compiled as a synchronous function that
+     * returns a fulfilled Promise (compile-time await-elision) instead of paying
+     * the CPS state-machine cost. See {@link asyncFnNeedsCps} (#1936).
+     *
+     * Conservative: only the forms enumerated in {@link awaitIsStaticallyResolved}
+     * count as resolved; anything else (a call result, a member read, an
+     * identifier that might hold a pending Promise) is `false` so the safe CPS /
+     * legacy path is chosen.
+     */
+    readonly awaitedStaticallyResolved: ReadonlyMap<ts.AwaitExpression, boolean>;
+}
+/**
+ * Walk the body of an async function / arrow / method and produce a plan.
+ *
+ * Pure analysis — no codegen side effects, no `ctx`/`fctx` mutation. Safe to
+ * call speculatively (the function-body hook calls it to decide whether a
+ * function needs CPS at all: zero await points ⇒ legacy path).
+ */
+export declare function analyzeAsyncBody(_ctx: CodegenContext, fn: ts.FunctionLikeDeclaration): AsyncCpsPlan;
+/**
+ * Conservative compile-time predicate: is the operand of an `await` already a
+ * *settled* value, so that `await operand` performs no observable suspension?
+ *
+ * Per §27.7.5.3, `await V` ≡ `PromiseResolve(%Promise%, V)` then a job. When `V`
+ * is not a thenable the resumption is a single microtask carrying `V` unchanged;
+ * when `V` is `Promise.resolve(x)` with a non-thenable `x` it likewise settles
+ * to `x`. In both cases the *value* is statically known to be the operand (or
+ * its resolve-argument); only the scheduling differs. js2wasm's synchronous
+ * model already collapses that scheduling, so these awaits are safe to treat as
+ * pass-through.
+ *
+ * Recognised static forms (intentionally narrow — over-approximating here would
+ * mis-elide a genuinely-suspending await):
+ *   - numeric / string / boolean / null literals
+ *   - `void`-prefixed, unary `+`/`-`/`!` over a static operand
+ *   - binary arithmetic / comparison where BOTH operands are static
+ *   - parenthesised / `as`-cast wrappers around a static operand
+ *   - `Promise.resolve(<static>)` and `Promise.resolve()` (settles to undefined)
+ *
+ * Everything else — a call result, a member access, a bare identifier (which may
+ * hold a pending Promise) — returns `false`.
+ */
+export declare function awaitIsStaticallyResolved(operand: ts.Expression): boolean;
+/**
+ * The per-function CPS decision (#1936) — replaces the global
+ * {@link ASYNC_CPS_ENABLED} kill-switch with a per-function predicate. Returns
+ * `true` only when the function *genuinely suspends* and the suspension is in a
+ * shape the state machine can lower:
+ *
+ *   1. at least one await point exists,
+ *   2. at least one await operand is NOT statically resolved (a real suspension —
+ *      otherwise the body is await-elidable and compiles as a sync fn returning
+ *      a fulfilled Promise), and
+ *   3. {@link splitBodyAtAwait} accepts the body shape (single top-level await in
+ *      a canonical position; richer control flow stays on the legacy path with a
+ *      `cps-unsupported-shape` census bucket), and
+ *   4. the single awaited operand is not a `Promise.<combinator>(...)` call —
+ *      those already return a real Promise that the legacy `await`-identity path
+ *      resolves correctly, and routing them through CPS regresses host-method
+ *      argument marshaling pending #2028 (see {@link awaitedExprIsPromiseCombinator}).
+ *
+ * `ASYNC_CPS_ENABLED` is retained as a transitional master kill-switch routed
+ * through this predicate; when it is `false` the predicate always returns
+ * `false` (the pre-#1796 shipped behaviour).
+ */
+export declare function asyncFnNeedsCps(fn: ts.FunctionLikeDeclaration, plan: AsyncCpsPlan): boolean;
+/**
+ * Classification of how an async call's result is consumed at its call site —
+ * the per-call-site half of the async contract migration (#1936). The legacy
+ * boolean `asyncResultConsumedAsValue` only distinguished "raw value" from
+ * "everything else"; the census needs the three-way split so #1796 can migrate
+ * exactly the `value`-but-not-statically-resolved set.
+ *
+ *   - `await`    — consumed by an enclosing `await` (raw-T passthrough today).
+ *   - `value`    — consumed through a non-Promise cast/assertion sink
+ *                  (`f() as number`, `as unknown as number`, `as any`): the
+ *                  synchronous-consumption contract that blocks the global flip.
+ *   - `thenable` — consumed as a real Promise (`.then`, `Promise.all([f()])`,
+ *                  `const p: Promise<T> = f()`, bare `return f()`): already
+ *                  spec-correct, takes the wrap path.
+ */
+export type AsyncConsumerKind = "await" | "value" | "thenable";
+/**
+ * Census classifier for an async call result's consumer (#1936). Pure: depends
+ * only on the AST shape around `expr` and the `checker` for cast target types,
+ * so the offline census script can reuse it without a full `CodegenContext`.
+ *
+ * Walks the transparent wrapper chain (`(...)`, `as`, `!`, `<T>`) from
+ * `expr.parent` exactly as the shipped `asyncResultConsumedAsValue` does, then:
+ *   - if the semantic consumer is an `AwaitExpression` → `await`,
+ *   - else if any wrapper cast targets a non-Promise type → `value`,
+ *   - else → `thenable`.
+ *
+ * Behaviour parity note: `classifyAsyncConsumer(...) !== "thenable"` is exactly
+ * the boolean the legacy `asyncResultConsumedAsValue` returns, so routing the
+ * call site through this classifier is a behaviour-preserving refactor until the
+ * #1796 flip changes the `value`/`thenable` dispatch.
+ */
+export declare function classifyAsyncConsumer(checker: ts.TypeChecker, expr: ts.CallExpression): AsyncConsumerKind;
+/**
+ * Emit a CPS-lowered async function body into `fctx`, replacing the normal
+ * statement loop. Drives the entire body and leaves the result Promise
+ * (externref) on the stack as the function's return value; the caller skips
+ * its own statement loop.
+ *
+ * PR1 scope — a single tail-position await in one of the canonical shapes
+ * (`return await P`, `const x = await P; rest`, `await P; rest`). The
+ * function result type must already have been rewritten to `externref` by the
+ * activation hook (the function returns a Promise object, not the unwrapped
+ * value). Everything is gated behind {@link ASYNC_CPS_ENABLED} + the
+ * function-body activation gate, so this never runs in default compilation
+ * until that gate is flipped.
+ *
+ * Strategy (no funcref table, no manual settle):
+ *   1. Emit the synchronous prefix into `fctx`.
+ *   2. Compile the awaited expression → externref (the promise we suspend on).
+ *   3. Synthesize an exported `__cb_N(captures, awaitValue) -> externref`
+ *      continuation whose body is the post-await suffix; its `return X`
+ *      naturally produces `X` as the cb's externref result.
+ *   4. At the suspension point emit the creation site:
+ *        push cbId; build+push captures struct; `__make_callback` → contCb;
+ *        `Promise_then2(awaited, contCb, null)` → the chained result Promise.
+ *      `.then`'s own returned promise resolves to the continuation's return
+ *      value, so it IS this async function's result promise. A null reject
+ *      callback lets rejections propagate (default rethrow).
+ *
+ * Returns nothing; on an unsupported shape it `reportError`s and leaves the
+ * caller to fall back (the activation hook only calls this for shapes
+ * `splitBodyAtAwait` accepts, so that path is defensive).
+ */
+export declare function emitAsyncStateMachine(ctx: CodegenContext, fctx: FunctionContext, fn: ts.FunctionLikeDeclaration, plan: AsyncCpsPlan): void;
+/**
+ * Compile a nested `await` encountered while the surrounding
+ * {@link emitAsyncStateMachine} is driving the body (e.g. `await (x + await y)`).
+ *
+ * PR1: stub. Nested awaits within a single segment are a follow-up; the joint
+ * spec §6.2 lists `return await` as the only tail case required in Slice 2A.
+ */
+export declare function compileNestedAwait(ctx: CodegenContext, _fctx: FunctionContext, expr: ts.AwaitExpression): never;
+/**
+ * IR entry point (Phase 2B / #1373b). Same machinery, IR input.
+ *
+ * PR1: stub returning `false` (means "did not handle; caller uses legacy
+ * path"). #1373b fills this in.
+ */
+export declare function emitAsyncStateMachineFromIr(): boolean;
+/**
+ * One segment boundary produced by {@link splitBodyAtAwait}.
+ *
+ * PR1 handles a body with **exactly one** top-level await appearing as the
+ * initializer/operand of one of three canonical statement shapes. The split
+ * yields:
+ *   - `prefix`: statements that run synchronously before suspension (the
+ *     await's own statement is NOT included here; its awaited expression is
+ *     surfaced separately as `awaitedExpr`).
+ *   - `awaitedExpr`: the operand of the await (the thing we suspend on).
+ *   - `resumeBinding`: the `{name,type}` the resolved value binds to on resume
+ *     (for `const x = await P`), or `null` for a bare `await P;` /
+ *     `return await P`.
+ *   - `suffix`: statements that run after resumption (the continuation body).
+ *   - `isReturnAwait`: true for `return await P` — the continuation's value IS
+ *     the awaited value, so `suffix` is empty and the resolved value settles
+ *     the outer promise directly.
+ */
+export interface AwaitSplit {
+    readonly prefix: readonly ts.Statement[];
+    readonly awaitedExpr: ts.Expression;
+    readonly resumeBinding: {
+        readonly name: string;
+        readonly type: ts.TypeNode | undefined;
+    } | null;
+    readonly suffix: readonly ts.Statement[];
+    readonly isReturnAwait: boolean;
+}
+/**
+ * Split a single-await async function body into a prefix / awaited-expr /
+ * suffix triple for the canonical PR1 shapes. Returns `null` if the body does
+ * not match one of the three supported shapes (caller falls back to legacy).
+ *
+ * Supported shapes (the await must be the *sole* top-level await and appear at
+ * statement top-level, not nested inside an expression sub-tree):
+ *
+ *   1. `return await P;`                      → isReturnAwait, no suffix
+ *   2. `const x = await P; <rest>`            → resumeBinding=x, suffix=rest
+ *      (also `let`/`var`; single declarator only)
+ *   3. `await P; <rest>`                      → no binding, suffix=rest
+ *
+ * Pure: no `ctx`/`fctx` mutation. The shape gate keeps PR1 small and provably
+ * correct; richer control flow (awaits in loops/branches, multiple awaits in
+ * one segment) is deferred to follow-up slices.
+ */
+export declare function splitBodyAtAwait(fn: ts.FunctionLikeDeclaration, plan: AsyncCpsPlan): AwaitSplit | null;