@geastack/compiler 1.0.15

package/dist/targets/cpp/prototype/emit-prototype-iterator.d.ts

@@ -0,0 +1,47 @@
+import type { CallOperation } from '../../../ir/model.js';
+import type { Representation } from '../../../representation/model.js';
+import { type EmitContext } from '../emit-context.js';
+/**
+ * `%GeneratorPrototype%.next`/`.return`/`.throw` (ECMA-262 27.5.1.2-27.5.1.4)
+ * off a generator value, which this backend carries as the cursor
+ * `gea::Iterator<T, TReturn, TNext>` -- one type that is both the coroutine
+ * and the iterator over it (`gea_runtime.h`'s own rationale:
+ * `%GeneratorPrototype%[@@iterator]` returns `this`).
+ *
+ * The call is fused with its deferred `[[Get]]` exactly as a Promise method
+ * is (`emit-prototype-invoke.ts`'s header), and its result is the value the
+ * CHECKER typed the call with: `IteratorResult<T, TReturn>`, which is
+ * `IteratorYieldResult<T> | IteratorReturnResult<TReturn>` in `lib.es2015.iterable.d.ts`
+ * and derives to a tagged union of two records. Nothing here invents a
+ * `{value, done}` carrier of its own -- `CreateIterResultObject` (7.4.14) is
+ * rendered by constructing whichever of the two records the checker already
+ * laid out and tagging the union with it, so every later `.value`/`.done`
+ * read goes through the same union-member path any other two-record union
+ * takes.
+ *
+ * Which arm is which is read off the layout rather than off the union's arm
+ * order (which is the checker's type-id order, and differs from program to
+ * program): the return arm is the one whose `done` is REQUIRED (declared
+ * `done: true`), the yield arm the one whose `done` is optional (declared
+ * `done?: false`). A result with any other shape is refused by name.
+ *
+ * `.return`/`.throw` are claimed ONLY for a generator-sourced cursor
+ * (`carrier.source === 'generator'`, `representation/model.ts`'s `iterator`
+ * kind): the four fixed-storage walks (`Array`/`Set`/`string`/`Map`) and the
+ * `for`-`in` enumerator publish the identical `iterator(E)` carrier but their
+ * real `%ArrayIteratorPrototype%` and siblings define neither method at all
+ * (ECMA-262 27.1.2), so a `'sequence'`-sourced receiver refuses both by name
+ * rather than certifying a method its real prototype does not have.
+ *
+ * What a `'sequence'` cursor's `next` (and a valueless generator's `next`)
+ * still does not carry is refused by name too, never approximated: a
+ * `next(v)`/`.return(v)`'s own value, or a completion value, that resolved to
+ * no native carrier (`representation/derive.ts` collapses an unresolved/
+ * dynamic `TReturn`/`TNext` to `undefined` on purpose, rather than boxing it)
+ * has no storage to read or fill, and the read/call that needs one refuses
+ * here instead.
+ */
+export declare const iteratorPrototypeMethods: ReadonlySet<string>;
+export declare const iteratorCallText: (ctx: EmitContext, member: string, receiverText: string, carrier: Extract<Representation, {
+    kind: "iterator";
+}> | undefined, operation: CallOperation) => string;

package/dist/targets/cpp/prototype/emit-prototype-iterator.js

@@ -0,0 +1,250 @@
+import { thrownValueCarrier } from '../../../ir/lower-exceptions.js';
+import { representationKey } from '../../../representation/model.js';
+import { createCppEmitBlockedError, operandText } from '../emit-context.js';
+import { alignedValueText } from '../emit-narrowing.js';
+import { memberAccessOperator } from '../emit-carrier-members.js';
+import { recordFieldsOfShape } from '../records.js';
+import { cppRecordFieldName, cppRecordFieldPresenceName, cppRecordStructName, cppTypeOf } from '../types.js';
+/**
+ * `%GeneratorPrototype%.next`/`.return`/`.throw` (ECMA-262 27.5.1.2-27.5.1.4)
+ * off a generator value, which this backend carries as the cursor
+ * `gea::Iterator<T, TReturn, TNext>` -- one type that is both the coroutine
+ * and the iterator over it (`gea_runtime.h`'s own rationale:
+ * `%GeneratorPrototype%[@@iterator]` returns `this`).
+ *
+ * The call is fused with its deferred `[[Get]]` exactly as a Promise method
+ * is (`emit-prototype-invoke.ts`'s header), and its result is the value the
+ * CHECKER typed the call with: `IteratorResult<T, TReturn>`, which is
+ * `IteratorYieldResult<T> | IteratorReturnResult<TReturn>` in `lib.es2015.iterable.d.ts`
+ * and derives to a tagged union of two records. Nothing here invents a
+ * `{value, done}` carrier of its own -- `CreateIterResultObject` (7.4.14) is
+ * rendered by constructing whichever of the two records the checker already
+ * laid out and tagging the union with it, so every later `.value`/`.done`
+ * read goes through the same union-member path any other two-record union
+ * takes.
+ *
+ * Which arm is which is read off the layout rather than off the union's arm
+ * order (which is the checker's type-id order, and differs from program to
+ * program): the return arm is the one whose `done` is REQUIRED (declared
+ * `done: true`), the yield arm the one whose `done` is optional (declared
+ * `done?: false`). A result with any other shape is refused by name.
+ *
+ * `.return`/`.throw` are claimed ONLY for a generator-sourced cursor
+ * (`carrier.source === 'generator'`, `representation/model.ts`'s `iterator`
+ * kind): the four fixed-storage walks (`Array`/`Set`/`string`/`Map`) and the
+ * `for`-`in` enumerator publish the identical `iterator(E)` carrier but their
+ * real `%ArrayIteratorPrototype%` and siblings define neither method at all
+ * (ECMA-262 27.1.2), so a `'sequence'`-sourced receiver refuses both by name
+ * rather than certifying a method its real prototype does not have.
+ *
+ * What a `'sequence'` cursor's `next` (and a valueless generator's `next`)
+ * still does not carry is refused by name too, never approximated: a
+ * `next(v)`/`.return(v)`'s own value, or a completion value, that resolved to
+ * no native carrier (`representation/derive.ts` collapses an unresolved/
+ * dynamic `TReturn`/`TNext` to `undefined` on purpose, rather than boxing it)
+ * has no storage to read or fill, and the read/call that needs one refuses
+ * here instead.
+ */
+export const iteratorPrototypeMethods = new Set(['next', 'return', 'throw']);
+const isRecordArm = (representation) => representation.kind === 'record' || representation.kind === 'native-record-ref';
+/** The arm's own declared fields, or `null` for a host-named struct this compiler did not lay out. */
+const armFieldsOf = (ctx, arm) => arm.kind === 'record' ? arm.fields : arm.native === null ? recordFieldsOfShape(ctx.deriver, arm.shapeId) : null;
+const constructionText = (arm) => {
+    switch (arm.ownership) {
+        case 'owned':
+            return `${cppTypeOf(arm)}{}`;
+        case 'shared-refcount':
+            return `gea::makeRef<${cppRecordStructName(arm.shapeId)}>()`;
+        case 'borrowed':
+            throw createCppEmitBlockedError(`physical-cpp-type:${representationKey(arm)}`, 'an IteratorResult arm carries ownership "borrowed", and a fresh iteration result has no other frame to borrow it from');
+    }
+};
+const isValueless = (representation) => representation.kind === 'void' || representation.kind === 'undefined';
+/** `member = <value>;` plus the presence bit an optional field keeps beside its storage (`emitFieldInits`'s own rule). */
+const fieldStoreText = (accessor, field, valueText) => `gea_result${accessor}${cppRecordFieldName(field.key)} = ${valueText}; ` +
+    (field.required ? '' : `gea_result${accessor}${cppRecordFieldPresenceName(field.key)} = true; `);
+/**
+ * A padded `undefined` (an omitted optional argument the lowering fills in)
+ * sends nothing -- `next(undefined)` and `next()` are one `GeneratorResume`
+ * (27.5.1.2 passes the value through unchanged, and the first resumption
+ * discards it) -- and so is the EMPTY rest pack `next(...[value]: [] |
+ * [TNext])`'s variadic convention makes `ir/lower-operands.ts`'s
+ * `packRestArguments` build for a bare `next()`: withheld whole
+ * (`ctx.pendingPacks`), it lists its element expressions, and none is no
+ * value sent.
+ */
+const sendsNothing = (ctx, argument) => argument.representation.kind === 'undefined' ||
+    argument.representation.kind === 'void' ||
+    (argument.representation.kind === 'array-object' && ctx.pendingPacks.get(argument.value)?.elements.length === 0);
+/**
+ * Builds `IteratorYieldResult<T> | IteratorReturnResult<TReturn>` from
+ * whichever `stepText` expression already advanced (or injected an abrupt
+ * completion into) the cursor -- shared by `next`, `return` and `throw`,
+ * which differ only in how they got the frame moving, never in how the
+ * record that comes back is read off it.
+ */
+const iteratorResultText = (ctx, receiverText, carrier, result, stepText) => {
+    if (result.representation.kind !== 'tagged-union') {
+        throw createCppEmitBlockedError(`runtime-helper:protocol:result:${representationKey(carrier)}`, `publishes "${representationKey(result.representation)}", but ` +
+            'IteratorResult<T, TReturn> is a union of two records and this file renders exactly that');
+    }
+    const union = result.representation;
+    const arms = union.arms.map((arm, index) => {
+        const value = arm.value;
+        if (!isRecordArm(value))
+            return null;
+        const fields = armFieldsOf(ctx, value);
+        const done = fields?.find((field) => field.key === 'done');
+        if (fields === null || done === undefined)
+            return null;
+        return { index, value, done, valueField: fields.find((field) => field.key === 'value') ?? null };
+    });
+    const returnArm = arms.find((arm) => arm !== null && arm.done.required) ?? null;
+    const yieldArm = arms.find((arm) => arm !== null && !arm.done.required) ?? null;
+    if (union.arms.length !== 2 || returnArm === null || yieldArm === null) {
+        throw createCppEmitBlockedError(`runtime-helper:protocol:result:${representationKey(carrier)}`, `publishes "${representationKey(union)}", which is not IteratorYieldResult<T> | IteratorReturnResult<TReturn> ` +
+            '(two records, told apart by a required `done: true` against an optional `done?: false`)');
+    }
+    // The return arm's `value` field is the generator's COMPLETION value,
+    // read off the cursor's own `takeCompletionValue()` -- never off
+    // whatever was passed to `next`/`return`, because a `finally` block that
+    // runs during an abrupt completion can override it with its own `return`
+    // (ECMA-262 27.5.3.3's own note), and `promise_type::completion_value` is
+    // exactly the slot both roads write through (`gea_runtime.h`).
+    const completionText = returnArm.valueField === null || isValueless(returnArm.valueField.value)
+        ? null
+        : (() => {
+            if (isValueless(carrier.completion)) {
+                throw createCppEmitBlockedError(`conversion:${representationKey(carrier.completion)}->${representationKey(returnArm.valueField.value)}`, `a generator's completion value is carried as "${representationKey(returnArm.valueField.value)}", and this generator's own ` +
+                    'completion channel is "undefined" -- either TReturn never resolved to a native carrier, or this generator is not ' +
+                    'annotated as one -- so the cursor has no storage to read one back from');
+            }
+            const text = alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:155', carrier.completion, returnArm.valueField.value, `${receiverText}.takeCompletionValue()`);
+            if (text === null) {
+                throw createCppEmitBlockedError(`conversion:${representationKey(carrier.completion)}->${representationKey(returnArm.valueField.value)}`, `the cursor completes with "${representationKey(carrier.completion)}" while the IteratorResult "value" field carries ` +
+                    `"${representationKey(returnArm.valueField.value)}", and no installed conversion reconciles them`);
+            }
+            return text;
+        })();
+    const trueText = alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:165', { kind: 'scalar', domain: 'boolean' }, returnArm.done.value, 'true');
+    const falseText = alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:166', { kind: 'scalar', domain: 'boolean' }, yieldArm.done.value, 'false');
+    if (trueText === null || falseText === null) {
+        throw createCppEmitBlockedError(`conversion:scalar(boolean)->${representationKey((trueText === null ? returnArm : yieldArm).done.value)}`, `an IteratorResult "done" field carries "${representationKey((trueText === null ? returnArm : yieldArm).done.value)}", ` +
+            'and no installed conversion writes a boolean into it');
+    }
+    const yieldValueText = yieldArm.valueField === null || isValueless(yieldArm.valueField.value)
+        ? null
+        : alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:177', carrier.element, yieldArm.valueField.value, 'gea_next');
+    if (yieldArm.valueField !== null && !isValueless(yieldArm.valueField.value) && yieldValueText === null) {
+        throw createCppEmitBlockedError(`conversion:${representationKey(carrier.element)}->${representationKey(yieldArm.valueField.value)}`, `the cursor yields "${representationKey(carrier.element)}" while the IteratorResult "value" field carries ` +
+            `"${representationKey(yieldArm.valueField.value)}", and no installed conversion reconciles them`);
+    }
+    const unionType = cppTypeOf(union);
+    const returnAccessor = memberAccessOperator(returnArm.value.ownership);
+    const yieldAccessor = memberAccessOperator(yieldArm.value.ownership);
+    const returnBranch = `auto gea_result = ${constructionText(returnArm.value)}; ${fieldStoreText(returnAccessor, returnArm.done, trueText)}` +
+        (completionText === null || returnArm.valueField === null ? '' : fieldStoreText(returnAccessor, returnArm.valueField, completionText)) +
+        `return ${unionType}::ofArm<${returnArm.index}>(gea_result);`;
+    const yieldBranch = `auto gea_result = ${constructionText(yieldArm.value)}; ${fieldStoreText(yieldAccessor, yieldArm.done, falseText)}` +
+        (yieldValueText === null || yieldArm.valueField === null ? '' : fieldStoreText(yieldAccessor, yieldArm.valueField, yieldValueText)) +
+        `return ${unionType}::ofArm<${yieldArm.index}>(gea_result);`;
+    return (`([&]() -> ${unionType} { auto gea_next = ${stepText}; (void)gea_next; ` +
+        `if (${receiverText}.done()) { ${returnBranch} } ${yieldBranch} })()`);
+};
+/**
+ * `iter.next(v)` (member already checked to be `"next"`). Builds the step
+ * text -- an ordinary `arrayNext()` when nothing was sent, `resumeWith(v)`
+ * once converted into the cursor's own resume carrier -- and, only when the
+ * call's own result is actually read, the `IteratorResult` on top of it.
+ */
+const nextCallText = (ctx, receiverText, carrier, operation) => {
+    const sent = operation.arguments.filter((argument) => !sendsNothing(ctx, argument));
+    const stepText = sent.length === 0
+        ? `${receiverText}.arrayNext()`
+        : (() => {
+            if (isValueless(carrier.resume)) {
+                throw createCppEmitBlockedError(`runtime-helper:protocol:next:${representationKey(carrier)}`, "a generator's next(v) sends a value back into the suspended yield, and this generator's own resume channel is " +
+                    '"undefined" -- either TNext never resolved to a native carrier, or this generator is not annotated as one -- so the ' +
+                    `cursor has no storage to send it through; the call carries ` +
+                    `${operation.arguments.map((argument) => `"${representationKey(argument.representation)}"`).join(', ')}`);
+            }
+            if (sent.length !== 1) {
+                throw createCppEmitBlockedError('call-abi:next', `next(v) sends more than one value operand (${sent.length}), which is not valid syntax to model`);
+            }
+            const argument = sent[0];
+            const text = alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:235', argument.representation, carrier.resume, operandText(ctx, argument));
+            if (text === null) {
+                throw createCppEmitBlockedError(`conversion:${representationKey(argument.representation)}->${representationKey(carrier.resume)}`, `sends "${representationKey(argument.representation)}" into a resume channel carried as "${representationKey(carrier.resume)}", ` +
+                    'and no installed conversion reconciles them');
+            }
+            return `${receiverText}.resumeWith(${text})`;
+        })();
+    return operation.result === null ? stepText : iteratorResultText(ctx, receiverText, carrier, operation.result, stepText);
+};
+/**
+ * `iter.return(v)`/`iter.throw(e)`, claimed only for `carrier.source ===
+ * 'generator'` -- see this file's own header comment for why. Both read back
+ * through the identical `IteratorResult` construction `next` uses: ECMA-262
+ * 27.5.3.3/27.5.3.4 both resume the frame like an ordinary step, they just
+ * inject an ABRUPT completion at the paused `yield` instead of a normal one
+ * (`gea_runtime.h`'s `resumeReturn`/`resumeThrow`), and a `finally` in scope
+ * can still turn either into an ordinary yield (`{value, done: false}`) --
+ * exactly the shape `iteratorResultText` already renders generically.
+ */
+const abruptCallText = (ctx, member, receiverText, carrier, operation) => {
+    if (carrier.source !== 'generator') {
+        throw createCppEmitBlockedError(`runtime-helper:protocol:${member}:${representationKey(carrier)}`, `"${member}" was recorded as a deferred %GeneratorPrototype% read over a "${carrier.source}"-sourced cursor -- only a real ` +
+            `generator's iterator has a %GeneratorPrototype%.${member}; the four fixed-storage walks and the \`for\`-in enumerator do not`);
+    }
+    const argument = operation.arguments[0];
+    if (member === 'throw') {
+        if (!argument) {
+            throw createCppEmitBlockedError('call-abi:throw', 'throw(e) carries no argument to inject as the abrupt completion');
+        }
+        // The coroutine body's own `catch` clauses match by C++ type, and every
+        // `catch (e)` this backend can ever emit binds `e` as `thrownValueCarrier`
+        // -- see `lower.ts`'s ordinary `throw` terminator, which converts into the
+        // identical carrier before its own native `throw` for the identical
+        // reason. Injecting the raw, unboxed argument here throws a type no
+        // `catch` inside the generator was ever written to match, so ECMA-262's
+        // "the generator catches its own injected exception" silently became "the
+        // exception escapes the coroutine and the process aborts".
+        const text = alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:285', argument.representation, thrownValueCarrier, operandText(ctx, argument));
+        if (text === null) {
+            throw createCppEmitBlockedError(`conversion:${representationKey(argument.representation)}->${representationKey(thrownValueCarrier)}`, `throw(e) sends "${representationKey(argument.representation)}" into the thrown-value carrier, and no installed conversion reconciles them`);
+        }
+        return `${receiverText}.resumeThrow(std::make_exception_ptr(${text}))`;
+    }
+    // `return(v)`'s completion value is whatever this call site passed, not
+    // what the cursor's `completion` carrier declares elsewhere in the
+    // program -- but if THIS generator's completion channel never resolved to
+    // a native carrier, there is still no storage for it, and `v`'s own value
+    // (as opposed to its evaluation, which still has to happen for its
+    // effects) is discarded exactly as a valueless `return` terminator's own
+    // operand already is (`emit-return.ts`).
+    if (isValueless(carrier.completion)) {
+        const discard = argument && !sendsNothing(ctx, argument) ? `(void)(${operandText(ctx, argument)}), ` : '';
+        return `${discard}${receiverText}.resumeReturn({})`;
+    }
+    if (!argument) {
+        throw createCppEmitBlockedError('call-abi:return', "return(v) carries no argument, but this generator's completion channel carries a real value");
+    }
+    const text = alignedValueText(ctx, 'prototype/emit-prototype-iterator.ts:308', argument.representation, carrier.completion, operandText(ctx, argument));
+    if (text === null) {
+        throw createCppEmitBlockedError(`conversion:${representationKey(argument.representation)}->${representationKey(carrier.completion)}`, `return(v) sends "${representationKey(argument.representation)}" into a completion channel carried as "${representationKey(carrier.completion)}", ` +
+            'and no installed conversion reconciles them');
+    }
+    return `${receiverText}.resumeReturn(${text})`;
+};
+export const iteratorCallText = (ctx, member, receiverText, carrier, operation) => {
+    if (!iteratorPrototypeMethods.has(member)) {
+        throw createCppEmitBlockedError('property-access:iterator:get:false', `"${member}" was recorded as a deferred %GeneratorPrototype% read but this file renders no call for it`);
+    }
+    if (carrier === undefined) {
+        throw createCppEmitBlockedError(`host-invocation:GeneratorPrototype.${member}`, `"${member}" was recorded as a deferred iterator read with no cursor carrier to render it off`);
+    }
+    if (member === 'next')
+        return nextCallText(ctx, receiverText, carrier, operation);
+    const stepText = abruptCallText(ctx, member, receiverText, carrier, operation);
+    return operation.result === null ? stepText : iteratorResultText(ctx, receiverText, carrier, operation.result, stepText);
+};

package/dist/targets/cpp/prototype/emit-prototype-promise.d.ts

@@ -0,0 +1,46 @@
+import { type Representation } from '../../../representation/model.js';
+import { type ConversionSite } from '../emit-narrowing.js';
+/**
+ * Resolving a value the way `await` and `Promise.all` both do.
+ *
+ * ECMA-262 27.2.4.7.1 `PromiseResolve` is the one operation behind both: a
+ * thenable is adopted, and anything else resolves to ITSELF. `Awaited<T>` is
+ * TypeScript's name for the same fact, which is why `await 1` is `1`.
+ *
+ * `gea::Promise<V>` is a settled-value box with no job queue (see its own doc
+ * comment in `runtime/gea_runtime.h`), so adoption is reading the value now --
+ * `.awaited()` -- rather than a suspension this substrate has no coroutine
+ * primitive for.
+ *
+ * The case this exists for is the THIRD one, which neither half of that
+ * sentence covers on its own: a union of both. `string | Promise<string>` is
+ * what every `Promise.all` argument and every conditionally-async helper is
+ * made of (hono's `utils/html.ts` is exactly that), and it is neither "a
+ * promise" nor "not a promise" -- it is a discriminant test away from either.
+ * `emitAwait` used to ask only `kind === 'promise'` and pass such a union
+ * through untouched, handing a `TaggedUnion<...>` to a consumer that had been
+ * told it would get the payload.
+ *
+ * `null` for a carrier with nothing to resolve, which is the caller's signal
+ * that the value is already its own resolution and needs no text at all.
+ *
+ * `ctx`/`site` are the conversion census's site: the optional shape below
+ * stores an absence into the result cell, and every cross-carrier store goes
+ * through `alignedValueText` so the census is asked and printer drift is
+ * recorded -- calling the recipe printer's renderer directly would answer the
+ * spelling without recording that the question was put (the architecture
+ * gate counts exactly that).
+ */
+export declare const awaitedText: (ctx: ConversionSite, site: string, carrier: Representation, text: string, target?: Representation | null) => string | null;
+/**
+ * What `awaitedText` resolves a carrier TO -- the carrier's `Awaited<T>`.
+ *
+ * Stated beside the render rather than derived by a caller, so the two cannot
+ * disagree about which arms survive. A union of promises over one payload
+ * resolves to that payload; a union mixing a payload with a promise of the
+ * same payload resolves to the payload as well, which is the ordinary case.
+ * `null` when the arms do not agree, which is a real hole rather than a
+ * missing recipe: `string | Promise<number>` resolves to `string | number`,
+ * a union this cannot mint without the census's own arm ordering.
+ */
+export declare const awaitedRepresentation: (carrier: Representation) => Representation | null;

package/dist/targets/cpp/prototype/emit-prototype-promise.js

@@ -0,0 +1,143 @@
+import { representationKey } from '../../../representation/model.js';
+import { optionalOf } from '../../../representation/optional.js';
+import { alignedValueText } from '../emit-narrowing.js';
+import { cppConstantLiteral } from '../types.js';
+/**
+ * Resolving a value the way `await` and `Promise.all` both do.
+ *
+ * ECMA-262 27.2.4.7.1 `PromiseResolve` is the one operation behind both: a
+ * thenable is adopted, and anything else resolves to ITSELF. `Awaited<T>` is
+ * TypeScript's name for the same fact, which is why `await 1` is `1`.
+ *
+ * `gea::Promise<V>` is a settled-value box with no job queue (see its own doc
+ * comment in `runtime/gea_runtime.h`), so adoption is reading the value now --
+ * `.awaited()` -- rather than a suspension this substrate has no coroutine
+ * primitive for.
+ *
+ * The case this exists for is the THIRD one, which neither half of that
+ * sentence covers on its own: a union of both. `string | Promise<string>` is
+ * what every `Promise.all` argument and every conditionally-async helper is
+ * made of (hono's `utils/html.ts` is exactly that), and it is neither "a
+ * promise" nor "not a promise" -- it is a discriminant test away from either.
+ * `emitAwait` used to ask only `kind === 'promise'` and pass such a union
+ * through untouched, handing a `TaggedUnion<...>` to a consumer that had been
+ * told it would get the payload.
+ *
+ * `null` for a carrier with nothing to resolve, which is the caller's signal
+ * that the value is already its own resolution and needs no text at all.
+ *
+ * `ctx`/`site` are the conversion census's site: the optional shape below
+ * stores an absence into the result cell, and every cross-carrier store goes
+ * through `alignedValueText` so the census is asked and printer drift is
+ * recorded -- calling the recipe printer's renderer directly would answer the
+ * spelling without recording that the question was put (the architecture
+ * gate counts exactly that).
+ */
+export const awaitedText = (ctx, site, carrier, text, target = null) => {
+    if (carrier.kind === 'promise')
+        return `${text}.awaited()`;
+    if (carrier.kind === 'optional')
+        return awaitedOptionalText(ctx, site, carrier, text, target);
+    if (carrier.kind !== 'tagged-union')
+        return null;
+    if (!carrier.arms.some((arm) => arm.value.kind === 'promise'))
+        return null;
+    // Every arm is accounted for, not just the promise ones: an arm that is not
+    // a thenable resolves to itself, so it contributes its own payload. The last
+    // arm is the fall-through and is never tested, because the union holds one
+    // of its arms by construction and a test with no `else` has nothing to
+    // answer -- the same shape `taggedUnionArmText` (emit-narrowing.ts) uses.
+    const armTexts = carrier.arms.map((arm, index) => arm.value.kind === 'promise' ? `${text}.get<${index}>().awaited()` : `${text}.get<${index}>()`);
+    const last = armTexts[armTexts.length - 1];
+    if (last === undefined)
+        return null;
+    let chain = last;
+    for (let index = armTexts.length - 2; index >= 0; index -= 1) {
+        chain = `${text}.is<${index}>() ? ${armTexts[index]} : (${chain})`;
+    }
+    return `(${chain})`;
+};
+/**
+ * The FOURTH shape: a thenable that may also be ABSENT.
+ *
+ * `PromiseResolve` resolves a non-thenable to itself, and `undefined` is a
+ * non-thenable, so `await (Promise<T> | undefined)` is `T | undefined` -- and
+ * the carrier for such a value is an `optional` WRAPPER around the thing that
+ * may be a promise, never a promise or a union of one. Asking only the three
+ * kinds above therefore passed it through untouched, and the result cell was
+ * then told it held the payload while it was handed the wrapper: five of the
+ * @hono/node-server stores clang refused were exactly that
+ * (`responseViaCache`'s `await writeFromReadableStream(...)?.catch(...)`,
+ * `Optional<Promise<undefined>>`, and `responseViaResponseObject`'s
+ * `await options.errorHandler(err)`, an optional over a union).
+ *
+ * The presence test is the resolution: present resolves the payload by the
+ * same three rules one level in, absent resolves to the absence itself. Which
+ * absence is the wrapper's own tag -- `null` and `undefined` are distinguishable
+ * values and a later `=== null` on the result would answer the wrong one --
+ * and it is spelled by `cppConstantLiteral` and stored by `alignedValueText`,
+ * the same pair every other absence store already goes through, rather than a
+ * second hand-written empty-optional spelling that could drift from theirs.
+ *
+ * `target` is the cell the text must produce, and it is the IR's own result
+ * carrier rather than something derived here: the two arms resolve to
+ * DIFFERENT carriers whenever the payload is a union mixing `T` with
+ * `Promise<T | undefined>` (`CustomErrorHandler` is exactly that), so
+ * `awaitedRepresentation` cannot name one and only the consumer knows which
+ * cell is waiting. It falls back to that derivation for the caller that has no
+ * result cell of its own -- `Promise.all`, whose element lambda deduces its
+ * own return type.
+ */
+const awaitedOptionalText = (ctx, site, carrier, text, target) => {
+    const present = awaitedText(ctx, site, carrier.payload, `(*${text})`);
+    // Nothing under the wrapper is a thenable, so the optional is already its
+    // own resolution and needs no text -- the same answer the bare-carrier case
+    // gives, one level out.
+    if (present === null)
+        return null;
+    const resolved = target ?? awaitedRepresentation(carrier);
+    // A `void` result has no value to select between, so there is no ternary to
+    // build; and a payload whose arms resolve to carriers that disagree leaves
+    // the derivation with no name for the cell, which is a real hole rather than
+    // a spelling gap.
+    if (resolved === null || resolved.kind === 'void')
+        return null;
+    const absence = { kind: carrier.absence };
+    const absenceText = cppConstantLiteral(carrier.absence, carrier.absence, absence);
+    const absent = alignedValueText(ctx, site, absence, resolved, absenceText);
+    if (absent === null)
+        return null;
+    return `(${text}.has_value() ? ${present} : ${absent})`;
+};
+/**
+ * What `awaitedText` resolves a carrier TO -- the carrier's `Awaited<T>`.
+ *
+ * Stated beside the render rather than derived by a caller, so the two cannot
+ * disagree about which arms survive. A union of promises over one payload
+ * resolves to that payload; a union mixing a payload with a promise of the
+ * same payload resolves to the payload as well, which is the ordinary case.
+ * `null` when the arms do not agree, which is a real hole rather than a
+ * missing recipe: `string | Promise<number>` resolves to `string | number`,
+ * a union this cannot mint without the census's own arm ordering.
+ */
+export const awaitedRepresentation = (carrier) => {
+    if (carrier.kind === 'promise')
+        return carrier.value;
+    // An absence survives the resolution -- `PromiseResolve(undefined)` is
+    // `undefined` -- so the wrapper is kept over whatever the payload resolves
+    // to. Through `optionalOf` rather than a literal wrapper because the payload
+    // may already carry its own absence (a refcounted instance, a handle, a box,
+    // or a second optional), and stacking a flag onto one of those is the carrier
+    // the census forbids rather than a type this backend can spell.
+    if (carrier.kind === 'optional') {
+        const payload = awaitedRepresentation(carrier.payload);
+        return payload === null ? null : optionalOf(payload, carrier.absence);
+    }
+    if (carrier.kind !== 'tagged-union')
+        return carrier;
+    const resolved = carrier.arms.map((arm) => (arm.value.kind === 'promise' ? arm.value.value : arm.value));
+    const [first, ...rest] = resolved;
+    if (!first)
+        return null;
+    return rest.every((entry) => representationKey(entry) === representationKey(first)) ? first : null;
+};