@geastack/compiler 1.0.15

package/dist/targets/cpp/emit-record-view.d.ts

@@ -0,0 +1,20 @@
+import type { RecordLayoutPolicy } from '../../representation/policies.js';
+import type { Representation } from '../../representation/model.js';
+import { type RecordViewPlan } from '../../conversion/record-view.js';
+import { type ConversionSite } from './emit-narrowing.js';
+export declare const viewPlanFor: (layouts: RecordLayoutPolicy, source: Representation, target: Representation) => RecordViewPlan | null;
+/**
+ * A record viewed as another shape it satisfies: the census's plan
+ * (`conversion/record-view.ts`), rendered. The plan decides which pairs are
+ * views and how each field is reached; this spells it. `null` only where the
+ * plan promised what this context cannot spell -- a bound class method that
+ * captures, whose environment slot is spent on the receiver -- which
+ * `emitConvert` then refuses.
+ *
+ * `viewPlanFor` above is asked rather than `structuralRecordViewPlan`
+ * directly: `conversions.ts`'s `staticRecipe` already built this same plan
+ * to answer whether the census's `view:structural-record` capability exists
+ * at all, and this is that plan's one consumer, not a second derivation of
+ * it.
+ */
+export declare const structuralRecordViewText: (ctx: ConversionSite, source: Representation, target: Representation, text: string) => string | null;

package/dist/targets/cpp/emit-record-view.js

@@ -0,0 +1,354 @@
+import { representationKey } from '../../representation/model.js';
+import { structuralRecordViewPlan } from '../../conversion/record-view.js';
+import { classFamilyOverridesOf, virtualDispatchKey } from '../../projection/dispatch.js';
+import { cppVirtualMemberName } from './virtual-methods.js';
+import { classMemberOf } from './class-layout.js';
+import { alignedValueText, boxedAssertionText, chainConverts, convertedValueText, dynamicCarrierBoxText, recastedUnionFromHomes, recastUnionArmText } from './emit-narrowing.js';
+import { ownedRecordMaterializationText } from './emit-owned-record.js';
+import { cppRecordIndexAttributesNameFor, cppRecordIndexSidecarName, cppRecordIndexSidecarNameFor } from './records.js';
+import { cppAbiParameterType, cppBodyName, cppRecordFieldName, cppRecordFieldPresenceName, cppRecordStructName, cppResultTypeOf, cppTypeOf } from './types.js';
+/**
+ * The renderer of the census's `view:structural-record` recipe
+ * (`conversion/record-view.ts`): a record or class instance viewed as another
+ * shape it satisfies. Its own module because both the chain's caller
+ * (`emit-narrowing.ts`'s `alignedValueText`, which renders whatever recipe
+ * the census names for a pair) and the call renderer (`emit-callable.ts`)
+ * reach it, and the plan is the one authority on which pairs are views.
+ */
+/**
+ * The structural-record-view plan, built once per `(layouts, source,
+ * target)` and shared between the two places that ask for it:
+ * `conversions.ts`'s `staticRecipe`, which tests whether a view exists at
+ * all while the conversion census derives the pair's capability, and
+ * `structuralRecordViewText` below, which spells the plan the census
+ * already built. Without this cache the two independently ran
+ * `structuralRecordViewPlan` -- decided the pair twice, the same defect this
+ * refactor removes for the chain's own steps (`conversionRecipeOf`'s memo).
+ *
+ * Lives here rather than in `conversions.ts`: this module already sits
+ * downstream of `emit-narrowing.ts` (for `chainConverts`) and
+ * `conversions.ts` already sits upstream of `emit-narrowing.ts`, so a
+ * `conversions.ts` import of this file adds one edge to an existing acyclic
+ * chain, while the reverse (this file importing from `conversions.ts`)
+ * would close `emit-narrowing.ts -> emit-record-view.ts -> conversions.ts
+ * -> emit-narrowing.ts` into a cycle through a THIRD file, worse than the
+ * two-file cycle `emit-narrowing.ts`/`emit-record-view.ts` already have.
+ *
+ * Keyed by object identity through nested `WeakMap`s, the same discipline
+ * `emit-narrowing.ts`'s `spellability` memo uses, rather than a string key
+ * built from `representationKey` -- so a compile's representations and its
+ * plans are never retained past the compile that created them, and two
+ * unrelated compiles sharing a coincidentally-equal key string can never
+ * collide. `layouts` is the outermost key rather than an assumed-identical
+ * singleton: the cache stays correct even if a caller ever passes a
+ * different policy for the same pair, at the cost of one more miss, not a
+ * wrong answer.
+ */
+const recordViewPlans = new WeakMap();
+export const viewPlanFor = (layouts, source, target) => {
+    let bySource = recordViewPlans.get(layouts);
+    if (bySource === undefined) {
+        bySource = new WeakMap();
+        recordViewPlans.set(layouts, bySource);
+    }
+    let byTarget = bySource.get(source);
+    if (byTarget === undefined) {
+        byTarget = new WeakMap();
+        bySource.set(source, byTarget);
+    }
+    if (byTarget.has(target))
+        return byTarget.get(target) ?? null;
+    const plan = structuralRecordViewPlan(layouts, source, target, chainConverts);
+    byTarget.set(target, plan);
+    return plan;
+};
+const viewEnvironmentName = 'gea_view_env';
+const viewSlotName = 'gea_view_slot';
+const viewReceiverName = 'gea_view_this';
+const viewArgumentName = (ordinal) => `gea_view_arg_${ordinal}`;
+/**
+ * A class METHOD as the member a structural view of that class needs.
+ *
+ * A class's methods are not storage: they are free functions taking the
+ * instance as a leading formal, which is why `boundMethodValueRepresentation`
+ * (`class-properties/emit-class-properties.ts`) has to ADD a receiver to the
+ * carrier of a plain `obj.method` read. An interface that declares the same
+ * method declares STORAGE for it -- a `gea::CallableObject` member with no
+ * receiver in its frame -- so the two spellings of one method differ by
+ * exactly the receiver, and nothing in `gea::CallableObject`'s four converting
+ * constructors binds one.
+ *
+ * hono is where this stops the compile: `HonoBase.router` is declared
+ * `Router<[H, RouterRoute]>` -- an interface whose members are `name`, `add`
+ * and `match` -- and the constructor stores `new PatternRouter()` into it. The
+ * class provides `name` as a field and the other two as methods, so the view
+ * had two required members with no source field and refused, and the store
+ * fell through to a raw assignment clang rejected.
+ *
+ * The binding is `gea::CallableObject`'s own public `(Invoke, void*)`
+ * constructor over the receiver packed as the environment, which is the exact
+ * shape every closure this backend emits already uses -- `packEnvironment`
+ * keeps a heap copy (and therefore a reference count) for a carrier that can
+ * outlive the frame, and the lambda unpacks it the same way a generated thunk
+ * does. What it does NOT do is preserve identity: the view is a new object, so
+ * a later write through the class reference is not seen through the view. That
+ * is a real deviation, and it is the reason this is reached only after
+ * `convertedValueText` has refused -- a pair with an identity-preserving
+ * conversion never gets here.
+ *
+ * Refused, rather than rendered wrong, for a method that captures anything:
+ * the environment slot is spent on the receiver, and a method with its own
+ * captures needs both.
+ */
+const boundClassMethodText = (ctx, source, member, key, text) => {
+    // A view that refuses names only the PAIR, so which member refused is
+    // invisible in the refusal -- and a record view is all-or-nothing, so one
+    // member is the whole answer. Behind an env var because it is the only way
+    // to attribute one.
+    const trace = (why) => {
+        if (process.env['GEA_RECORD_VIEW_DEBUG'])
+            console.log(`[VIEW] ${representationKey(source)} member ${key}: ${why}`);
+        return null;
+    };
+    if (source.kind !== 'class-ref' || source.ownership !== 'shared-refcount')
+        return trace('source is not a shared-refcount class ref');
+    const abi = 'abi' in member ? member.abi : null;
+    if (abi === null || abi.receiver !== null || abi.restFrom !== null)
+        return trace('member declares no plain callable abi');
+    const site = classMemberOf(ctx.classes, source.declaration, key);
+    if (site === null || site.kind !== 'method' || site.method.callable === null)
+        return trace('class has no callable method of that name');
+    if (ctx.captures.of(site.method.callable).kind !== 'none')
+        return trace('method captures, and the environment slot holds the receiver');
+    const receiverType = cppTypeOf(source);
+    const formals = abi.parameters.map((parameter, ordinal) => `${cppAbiParameterType(parameter)} ${viewArgumentName(ordinal)}`);
+    const actuals = abi.parameters.map((_, ordinal) => viewArgumentName(ordinal));
+    const call = `${cppBodyName(site.method.callable)}(${[`*${viewReceiverName}`, ...actuals].join(', ')})`;
+    // A void-result member needs no conversion at all -- `call` is a statement,
+    // not an expression the lambda hands back -- so only a non-void result asks
+    // for the class's OWN declared signature, `ownAbi`. That is deliberately
+    // NOT `abi`: `abi` is the INTERFACE member's declared signature the view is
+    // being built for, and the two agree on the receiver and (in every program
+    // seen so far) on the parameters, but nothing forces the class's own result
+    // to already be the interface's -- a method the checker types to return
+    // `this` (a typed class ref) can back an interface member the wider census
+    // erased to `gea::Value`, and the body function genuinely returns the
+    // narrower carrier. Symmetric with every other position this file converts
+    // through (`recordFieldsViewText`'s field reads, the union arms below): the
+    // census-backed `alignedValueText` (not a direct `convertedValueText` call
+    // -- see `scripts/architecture.mjs`'s exact-count gate on this file) is the
+    // one authority on turning one carrier into the other. E.g. `gea::Value`
+    // has no implicit constructor from a `gea::Ref<T>`, so an unconverted
+    // `return call;` compiled only when the two happened to already agree.
+    // `representation` is OPTIONAL on a `ClassMethod`, and every callable kind
+    // that carries a convention carries it under the same `abi` key -- `function`
+    // is only the commonest of them. Reading it the same structural way the
+    // member's own abi is read above keeps the two sides symmetric; narrowing to
+    // `kind === 'function'` refused `Duplex.write` here, whose convention is
+    // published under another callable kind entirely.
+    const ownRepresentation = site.method.representation;
+    const ownAbi = ownRepresentation !== undefined && 'abi' in ownRepresentation ? ownRepresentation.abi : null;
+    let returned = call;
+    // No published convention at all means there is nothing to compare against,
+    // which is where this renderer stood before it converted anything: hand the
+    // call back unchanged rather than refuse, since the two agree in every
+    // program the emitted-set gate covers and a refusal here would drop them all.
+    if (abi.result.kind !== 'void' && ownAbi !== null) {
+        const converted = alignedValueText(ctx, 'emit-record-view.ts:158', ownAbi.result, abi.result, call);
+        if (converted === null)
+            return trace(`no conversion from the method's own result ${representationKey(ownAbi.result)} into the member's ${representationKey(abi.result)}`);
+        returned = converted;
+    }
+    const body = `alignas(void*) unsigned char ${viewSlotName}[sizeof(void*)]; ` +
+        `auto* ${viewReceiverName} = gea::unpackEnvironment<${receiverType}>(${viewEnvironmentName}, ${viewSlotName}); ` +
+        `${abi.result.kind === 'void' ? `${call};` : `return ${returned};`}`;
+    const invoke = `+[](void* ${viewEnvironmentName}${formals.length > 0 ? ', ' : ''}${formals.join(', ')}) -> ${cppResultTypeOf(abi.result)} { ${body} }`;
+    return `${cppTypeOf(member)}(${invoke}, gea::packEnvironment<${receiverType}>(${text}))`;
+};
+/**
+ * A getter-backed member, read by CALLING the getter -- the same answer
+ * `emit-class-properties.ts` gives an ordinary `obj.member` read of an
+ * accessor, and the reason a class's accessors can back an interface's plain
+ * fields at all.
+ *
+ * The direct body call is only correct while the family is CLOSED at this
+ * key: a derived class that redeclares the getter must run its own, and
+ * nothing in a struct-building expression dispatches. That case is refused
+ * rather than dispatched here because this renderer has no virtual-dispatch
+ * table to reach for -- `ConversionSite` carries the class map and the
+ * capture index, not the emitted member set -- and a wrong body is worse than
+ * a named refusal.
+ */
+const classAccessorReadText = (ctx, source, member, key, published, text) => {
+    if (source.kind !== 'class-ref')
+        return null;
+    const site = classMemberOf(ctx.classes, source.declaration, key);
+    if (site === null || site.kind !== 'accessor' || site.accessor.getter === null)
+        return null;
+    if (classFamilyOverridesOf(ctx.classes, source.declaration, key).length > 0) {
+        // An overridden getter is read through the family's dispatch member, as a
+        // plain read of it is (`emit-class-properties.ts`).
+        const dispatch = ctx.virtualDispatch?.get(virtualDispatchKey(source.declaration, key, 'get'));
+        if (dispatch === undefined)
+            return null;
+        return alignedValueText(ctx, 'emit-record-view.ts:classAccessorReadText', dispatch.result, member, `${text}->${cppVirtualMemberName(key, 'get')}()`);
+    }
+    return alignedValueText(ctx, 'emit-record-view.ts:classAccessorReadText', published, member, `${cppBodyName(site.accessor.getter)}(${text})`);
+};
+/**
+ * A record viewed as another shape it satisfies: the census's plan
+ * (`conversion/record-view.ts`), rendered. The plan decides which pairs are
+ * views and how each field is reached; this spells it. `null` only where the
+ * plan promised what this context cannot spell -- a bound class method that
+ * captures, whose environment slot is spent on the receiver -- which
+ * `emitConvert` then refuses.
+ *
+ * `viewPlanFor` above is asked rather than `structuralRecordViewPlan`
+ * directly: `conversions.ts`'s `staticRecipe` already built this same plan
+ * to answer whether the census's `view:structural-record` capability exists
+ * at all, and this is that plan's one consumer, not a second derivation of
+ * it.
+ */
+export const structuralRecordViewText = (ctx, source, target, text) => {
+    const plan = viewPlanFor(ctx.layouts, source, target);
+    return plan === null ? boxedAssertionText(source, target, text) : recordViewText(ctx, plan, text);
+};
+const recordViewText = (ctx, plan, text) => {
+    switch (plan.kind) {
+        case 'owned':
+            return ownedRecordMaterializationText(plan.plan, text);
+        case 'arm': {
+            const arm = plan.target.arms[plan.index];
+            if (arm === undefined)
+                return null;
+            const converted = plan.payload === null ? convertedValueText(plan.source, arm.value, text) : recordViewText(ctx, plan.payload, text);
+            return converted === null ? null : `${cppTypeOf(plan.target)}::ofArm<${plan.index}>(${converted})`;
+        }
+        case 'optional': {
+            const built = recordViewText(ctx, plan.payload, plan.sourceOptional ? `(*${text})` : text);
+            if (built === null)
+                return null;
+            const optional = cppTypeOf(plan.target);
+            if (!plan.sourceOptional)
+                return `${optional}(${built})`;
+            return `(${text}.has_value() ? ${optional}(${built}) : ${optional}())`;
+        }
+        case 'assert': {
+            const built = recordViewText(ctx, plan.payload, `(*${text})`);
+            if (built === null)
+                return null;
+            // The language's own `!` is erased at runtime; a later member read of an
+            // actually-absent value throws a TypeError, so the faithful C++ is a
+            // CHECKED unwrap that throws too -- not a bare `*text`, which would be
+            // undefined behaviour on absence. `gea::host::throwGetPropertyOfNullish`
+            // is the same helper `emit-context.ts`/`emit-properties.ts` reach for a
+            // nullish-base property read, and its `[[noreturn]] T` return lets it
+            // stand as an expression of the target's own type in the ternary's other
+            // arm.
+            return `(${text}.has_value() ? ${built} : gea::host::throwGetPropertyOfNullish<${cppTypeOf(plan.target)}>())`;
+        }
+        case 'recast-union': {
+            const homes = [];
+            for (const [index, home] of plan.arms.entries()) {
+                const armText = recastUnionArmText(plan.source, text, index);
+                const from = plan.source.arms[index];
+                const into = plan.target.arms[home.index];
+                if (from === undefined || into === undefined)
+                    return null;
+                const rendered = home.via === 'exact'
+                    ? armText
+                    : home.via === 'convert'
+                        ? convertedValueText(from.value, into.value, armText)
+                        : recordViewText(ctx, home.via, armText);
+                if (rendered === null)
+                    return null;
+                homes.push({ index: home.index, text: rendered });
+            }
+            return recastedUnionFromHomes(plan.source, plan.target, text, homes);
+        }
+        case 'fields':
+            return recordFieldsViewText(ctx, plan, text);
+    }
+};
+const recordFieldsViewText = (ctx, plan, text) => {
+    const { source, target } = plan;
+    // An `owned` record is a value, not a handle: its members are reached with
+    // `.` where every refcounted carrier uses `->`.
+    const arrow = (source.kind === 'record' || source.kind === 'record-with-index') && source.ownership !== 'shared-refcount' ? '.' : '->';
+    const reads = [];
+    const presences = [];
+    const structName = cppRecordStructName(target.shapeId);
+    for (const { field, read } of plan.fields) {
+        if (read.kind === 'bound-method') {
+            const bound = boundClassMethodText(ctx, source, field.value, field.key, text);
+            if (bound === null)
+                return null;
+            reads.push(bound);
+            if (!field.required)
+                presences.push('true');
+            continue;
+        }
+        if (read.kind === 'class-accessor') {
+            const got = classAccessorReadText(ctx, source, field.value, field.key, read.value, text);
+            if (got === null)
+                return null;
+            reads.push(got);
+            if (!field.required)
+                presences.push('true');
+            continue;
+        }
+        if (read.kind === 'absent') {
+            reads.push(`${cppTypeOf(field.value)}{}`);
+            if (!field.required)
+                presences.push('false');
+            continue;
+        }
+        const held = read.held;
+        const converted = convertedValueText(held.value, field.value, `${text}${arrow}${cppRecordFieldName(field.key)}`);
+        if (converted === null)
+            return null;
+        // Inside braces [dcl.init.list]/7 forbids the narrowing every other
+        // position allows: a field the integer census holds in a `long long`
+        // (`{ kind, type }` with `kind: 1 | 2`) is a hard error written into a
+        // `double` member of the layout it is viewed as, though both carriers say
+        // `scalar(number)`. `static_cast` spells the same conversion explicitly --
+        // `emit-narrowing.ts`'s `recastFieldText` answers the identical rule this
+        // way -- and is a no-op where the two already agree. The cast names the
+        // member's OWN declared type, `decltype(Struct::member)`, because the
+        // census's answer lives in the struct declaration `records.ts` emitted
+        // and nowhere this emitter can ask: the representation says `double` for
+        // both sides, and casting to that spelling is the same narrowing error
+        // in the other direction whenever the TARGET member is the narrowed one
+        // (a `Leaf { value: number }` read through a `Branch | Leaf` arm).
+        const arithmetic = field.value.kind === 'scalar' && field.value.domain !== 'bigint';
+        reads.push(arithmetic && held.value.kind === 'scalar'
+            ? `static_cast<decltype(${structName}::${cppRecordFieldName(field.key)})>(${converted})`
+            : converted);
+        if (!field.required) {
+            presences.push(held.required ? 'true' : `${text}${arrow}${cppRecordFieldPresenceName(field.key)}`);
+        }
+    }
+    if (source.kind === 'record-with-index') {
+        for (const { source: sourceIndex } of plan.indexes) {
+            reads.push(`${text}${arrow}${cppRecordIndexSidecarNameFor(sourceIndex, source.indexes)}`);
+            reads.push(`${text}${arrow}${cppRecordIndexAttributesNameFor(sourceIndex, source.indexes)}`);
+        }
+    }
+    reads.push(...presences);
+    const structure = `${structName}{${reads.join(', ')}}`;
+    if (target.ownership !== 'shared-refcount')
+        return structure;
+    const allocated = `gea::makeRef<${structName}>(${structure})`;
+    if (plan.expando)
+        return `gea::record::recastWithExpando(${allocated}, ${text}${arrow}${cppRecordIndexSidecarName})`;
+    // A class instance's view remembers the instance, so `instanceof` and a
+    // narrowing back to the class still answer from it
+    // (`gea::record::viewOrigin`, `projection/instance-test.ts`).
+    if (source.kind === 'class-ref') {
+        const boxed = dynamicCarrierBoxText(source, text);
+        if (boxed === null)
+            return null;
+        return `gea::record::rememberViewOrigin(${allocated}, ${boxed})`;
+    }
+    return allocated;
+};

package/dist/targets/cpp/emit-return.d.ts

@@ -0,0 +1,5 @@
+import type { IrTerminatorOperation } from '../../ir/model.js';
+import type { EmitContext } from './emit-context.js';
+export declare const emitReturn: (ctx: EmitContext, lines: string[], terminator: Extract<IrTerminatorOperation, {
+    kind: "return";
+}>) => void;

package/dist/targets/cpp/emit-return.js

@@ -0,0 +1,237 @@
+import { representationKey } from '../../representation/model.js';
+import { operandText, createCppEmitBlockedError } from './emit-context.js';
+import { cppTypeOf, cppUndefinedIn } from './types.js';
+import { alignedValueText, dynamicPromiseAdoptionText } from './emit-narrowing.js';
+import { structuralRecordViewText } from './emit-record-view.js';
+/**
+ * The `return` terminator: the one place a body's own value meets the calling
+ * convention its callers were compiled against.
+ *
+ * Three ABI results make different demands here -- a generator (`co_return`,
+ * and no completion value), a promise (a SETTLED value rather than a converted
+ * one), and everything else (an ordinary two-direction reconciliation) -- which
+ * is why this lives beside `emit.ts` rather than inside its terminator switch.
+ */
+/**
+ * A derived constructor's own completion rules (ECMA-262 10.2.2 step 13),
+ * decided statically. A body with no `super-initialize` anywhere never binds
+ * `this`, so every normal completion is the ReferenceError the language
+ * throws; a `return` of a primitive is the TypeError. Both were silently
+ * rendered as an ordinary construction before, which is a wrong answer, not
+ * a refusal. `undefined`/`void` returns are the ordinary case and fall
+ * through; a `return` of an OBJECT other than the receiver itself is the
+ * return-override this backend does not implement, and is refused by name
+ * rather than discarded.
+ */
+const constructorCompletionText = (ctx, value) => {
+    const owning = ctx.constructorOf;
+    if (owning === null)
+        return null;
+    if (owning.derived && !owning.callsSuper) {
+        return ('gea::host::throwRuntimeError("ReferenceError", "Must call super constructor in derived class before accessing \'this\' or ' +
+            'returning from derived constructor");');
+    }
+    const kind = value?.representation.kind;
+    if (value === null || kind === undefined || kind === 'void' || kind === 'undefined' || ctx.receiverValues.has(value.value))
+        return null;
+    if (kind === 'string' || kind === 'scalar' || kind === 'null') {
+        if (!owning.derived)
+            return null;
+        return `(void)(${operandText(ctx, value)}); gea::host::throwRuntimeError("TypeError", "Derived constructors may only return object or undefined");`;
+    }
+    throw createCppEmitBlockedError('call-abi:constructor-return-override', `a constructor of class ${owning.layout.declaration} returns a "${representationKey(value.representation)}" value, which would ` +
+        'replace the constructed instance ([[Construct]] step 10.a); this backend does not implement a constructor return override');
+};
+export const emitReturn = (ctx, lines, terminator) => {
+    const completion = constructorCompletionText(ctx, terminator.value ?? null);
+    if (completion !== null) {
+        lines.push(completion);
+        return;
+    }
+    // A coroutine may not use `return` at all -- C++20 [stmt.return] makes it
+    // ill-formed inside one -- so a generator body's every return, implicit
+    // fall-off included, spells `co_return`. A generator's completion VALUE
+    // (`return v` inside a `function*`) is carried when the cursor's own
+    // `completion` slot is a real native carrier (`representation/derive.ts`'s
+    // `GeneratorDeclarationPolicy`, `runtime/gea_runtime.h`'s
+    // `promise_type::return_value`) -- otherwise (an unresolved/dynamic
+    // `TReturn`, collapsed to `undefined` on purpose rather than boxed) a
+    // valued return is refused, since there is no storage to fill with it.
+    //
+    // Keyed on the BODY's own generator-ness, never on its result carrier: an
+    // ordinary `function makeGen() { return g() }` returns the identical
+    // `iterator(source: generator)` cursor a `function*` does, and spelling its
+    // `return` as `co_return` (or refusing it for lacking a completion channel)
+    // mistook the value's shape for the frame's.
+    if (ctx.generatorBody) {
+        const cursor = ctx.abi?.result;
+        if (cursor?.kind !== 'iterator') {
+            throw createCppEmitBlockedError('runtime-helper:boundary:generator-resume', `a generator body's calling convention returns "${cursor ? representationKey(cursor) : 'nothing'}" rather than an iterator cursor`);
+        }
+        if (!terminator.value) {
+            lines.push('co_return;');
+            return;
+        }
+        if (cursor.completion.kind === 'void' || cursor.completion.kind === 'undefined') {
+            throw createCppEmitBlockedError('runtime-helper:boundary:generator-resume', 'returns a value from a generator body whose completion channel is "undefined" -- either TReturn never resolved to a native ' +
+                'carrier, or this generator is not annotated as one -- and this cursor has no storage to fill with it');
+        }
+        const text = operandText(ctx, terminator.value);
+        const converted = alignedValueText(ctx, 'emit-return.ts:92', terminator.value.representation, cursor.completion, text);
+        if (converted === null) {
+            throw createCppEmitBlockedError(`conversion:${representationKey(terminator.value.representation)}->${representationKey(cursor.completion)}`, `returns a ${terminator.value.representation.kind} where this generator's completion channel is ${cursor.completion.kind}, ` +
+                'and no conversion is installed between them');
+        }
+        lines.push(`co_return ${converted};`);
+        return;
+    }
+    if (!terminator.value) {
+        // `Promise<void>` is a real class type, not the literal `void` -- a
+        // bare `return;` inside a function whose ABI result is
+        // `Promise<void>` is a C++ compile error (returning nothing from a
+        // function declared to return a class). `T === void` is the only
+        // payload for which a `return` terminator carries no value operand
+        // at all here, so this is reached exactly once per such function, at
+        // its implicit or explicit valueless return.
+        if (ctx.abi?.result.kind === 'promise' && ctx.abi.result.value.kind === 'void') {
+            lines.push(`return ${cppTypeOf(ctx.abi.result)}::settled_value();`);
+            return;
+        }
+        if (ctx.abi && ctx.abi.result.kind !== 'void') {
+            const result = ctx.abi.result;
+            const payload = result.kind === 'promise' ? result.value : result;
+            const absent = cppUndefinedIn(payload);
+            if (absent === null) {
+                // A valueless return into a result with no absence value is the one
+                // shape TypeScript admits only at an unreachable point: `return
+                // fail(...)` where `fail(): never`. The lowering drops the `never`
+                // carrier (it names no value), the call itself was rendered as its
+                // own statement and does not return, and this is the point after it
+                // -- `[[noreturn]]`, so the function's own result type needs no
+                // value here (`emit-callable.ts` renders an unreachable argument the
+                // same way).
+                lines.push(`return gea::host::unreachableValue<${cppTypeOf(result)}>();`);
+                return;
+            }
+            lines.push(result.kind === 'promise' ? `return ${cppTypeOf(result)}(${absent});` : `return ${absent};`);
+            return;
+        }
+        lines.push('return;');
+        return;
+    }
+    const text = operandText(ctx, terminator.value);
+    // The body's own declared ABI result is the "held" side of the same
+    // reconciliation `emit-bindings.ts` already applies to a binding cell -- see
+    // citations.md finding 1. `ctx.abi` is `null` only for an uncalled region,
+    // which never has a `return` with a value to widen.
+    //
+    // `convertedValueText`, not `widenedStoreText`: the store direction alone
+    // answers only a value WIDENING into the declared result, and returns `null`
+    // for the mirror case -- a `dynamic` value returned where the ABI result is
+    // concrete. That `null` then fell through to the bare `text`, emitting
+    // `return gea_arg_1;` from a `gea::Value` into a
+    // `gea::TaggedUnion<std::string, double>` with no conversion at all: a
+    // certified, preflight-clean program that clang rejects. A JSDoc
+    // `@returns {number|string}` on a JS function whose parameter's call sites
+    // disagree is enough to reach it. `convertedValueText` is the general
+    // reconciliation in both directions -- it asks `unboxedLoadText` for a
+    // dynamic source and falls through to the same `widenedStoreText` otherwise
+    // -- and is already what every argument slot (`emit-callable.ts`) uses.
+    //
+    // An async body's ABI result is `Promise<V>` while its `return v` carries a
+    // bare `V`: that pair is a RESOLUTION, not a conversion, and `Promise`'s
+    // converting constructor exists for this one site and no other -- its own
+    // class comment says so ("TypeScript never lets an ordinary binding or field
+    // hold a bare `T` where `Promise<T>` is declared -- so this is reached only
+    // from a function whose declared return type is `Promise<T>`"). Verified by
+    // RUNNING it: an async arrow returning an awaited `number` emits `return
+    // total;` from a `gea::Promise<double>` function and prints the right answer.
+    // Reconciling against the promise's PAYLOAD rather than against the promise
+    // keeps the guard below fail-closed on the part that really is a conversion.
+    // Returning an already-promise value (a pass-through) reconciles against the
+    // promise itself, so it is left to the general path.
+    // A DYNAMIC value may itself be a promise (hono's `formData()` returns its
+    // `any`-typed `#cachedBody(...)`), and an async return adopts one rather
+    // than fulfilling with it (ECMA-262 27.2.1.3.2) -- decided at run time.
+    // Lowering already converted the value toward the payload, so the dynamic
+    // operand is the convert's source.
+    const dynamicSource = terminator.value.representation.kind === 'dynamic' ? terminator.value : (ctx.conversionSources.get(terminator.value.value) ?? null);
+    if (ctx.abi?.result.kind === 'promise' && dynamicSource?.representation.kind === 'dynamic') {
+        const adopted = dynamicPromiseAdoptionText(ctx.abi.result, operandText(ctx, dynamicSource));
+        if (adopted !== null) {
+            lines.push(`return ${adopted};`);
+            return;
+        }
+    }
+    const settlesIntoPromise = ctx.abi !== null && ctx.abi.result.kind === 'promise' && terminator.value.representation.kind !== 'promise';
+    const abiResult = settlesIntoPromise && ctx.abi ? ctx.abi.result.value : (ctx.abi?.result ?? null);
+    // `Promise<void>` carries no payload at all (`cppResultTypeOf` elides
+    // `void`), so a valued return whose value is itself `void` -- `return f()`
+    // where `f` completes without producing one -- has nothing to settle WITH.
+    // The evaluation still has to happen for its effects, so it is discarded
+    // explicitly and the settled promise minted by the same named factory the
+    // valueless return above uses.
+    if (ctx.abi && ctx.abi.result.kind === 'promise' && abiResult && abiResult.kind === 'void') {
+        lines.push(`(void)(${text});`);
+        lines.push(`return ${cppTypeOf(ctx.abi.result)}::settled_value();`);
+        return;
+    }
+    // A value-returning source statement may still implement a `void` ABI:
+    // `return undefined` and `return sideEffect()` both evaluate an expression,
+    // then expose no result to the caller. Preserve that evaluation and discard
+    // its value explicitly. Passing `void` into the general conversion below is
+    // invalid by construction -- it has no C++ value type for `cppTypeOf` to
+    // compare -- and previously crashed the entire emission after lowering had
+    // already accepted the body.
+    if (abiResult?.kind === 'void') {
+        lines.push(`(void)(${text});`);
+        lines.push('return;');
+        return;
+    }
+    // The same two-step an ARGUMENT already takes (`alignedText`, emit-callable.
+    // ts): `convertedValueText` first, and only when it refuses, the view that
+    // needs both LAYOUTS in hand. A `native-record-ref` carries a shape id and no
+    // field list, so the general conversion cannot reach the target's members --
+    // this is the one place the deriver is available to resolve them. `return
+    // options` out of a method declared to return an overlapping named shape is
+    // ordinary TypeScript and the mongodb driver is built out of it.
+    const converted = abiResult
+        ? (alignedValueText(ctx, 'emit-return.ts:202', terminator.value.representation, abiResult, text) ??
+            structuralRecordViewText(ctx, terminator.value.representation, abiResult, text))
+        : null;
+    // FAIL CLOSED. `convertedValueText` answers `text` unchanged whenever the two
+    // carriers already agree, so `null` here means no recipe exists for this pair
+    // -- and emitting the bare operand anyway is how a `gea::Value` came to be
+    // returned from a function declared `gea::TaggedUnion<std::string, double>`:
+    // certified, preflight-clean, and rejected by clang. A missing conversion is
+    // a refusal, not a silently unconverted store.
+    if (abiResult && converted === null) {
+        throw createCppEmitBlockedError(`conversion:${representationKey(terminator.value.representation)}->${representationKey(abiResult)}`, `returns a ${terminator.value.representation.kind} where this body's ABI result is ${abiResult.kind}, ` +
+            'and no conversion is installed between them');
+    }
+    // ONE user-defined conversion, and the promise already spends it.
+    //
+    // Reconciling against the payload is right, but it leaves the step from the
+    // payload to the promise implicit -- and `convertedValueText` renders a
+    // widening that `gea::Optional<T>`'s (or any other) converting constructor
+    // performs as the operand text UNCHANGED, because for an ordinary store that
+    // single implicit conversion is exactly what happens. Stacked, they are two:
+    // `return v3;` from a `double` in a body whose result is
+    // `gea::Promise<gea::Optional<double>>` needs `double` -> `Optional<double>`
+    // -> `Promise<Optional<double>>`, and C++ [over.ics.user] permits one
+    // user-defined conversion per implicit sequence. clang rejected it -- "no
+    // viable conversion from returned value of type 'double'" -- on a body that
+    // certified clean and emitted. `async next(): Promise<number | null>` with
+    // `return this.index++` is the whole program it takes; mongodb's
+    // `AbstractCursor.next` is the same shape.
+    //
+    // Naming the promise explicitly spends the sequence's one slot on the
+    // payload widening instead, which is the step that actually needs it. The
+    // file's own optional-target comment makes the same argument at the other
+    // end of the same pair.
+    if (settlesIntoPromise && ctx.abi) {
+        lines.push(`return ${cppTypeOf(ctx.abi.result)}(${converted ?? text});`);
+        return;
+    }
+    lines.push(`return ${converted ?? text};`);
+};

package/dist/targets/cpp/emit-sum-widening.d.ts

@@ -0,0 +1,10 @@
+import type { Representation } from '../../representation/model.js';
+import { type NativeSumPlan } from '../../conversion/native-sum.js';
+export { nativeSumWidenable } from '../../conversion/native-sum.js';
+export declare const renderNativeSumPlan: (step: NativeSumPlan, text: string, spell: (target: Representation) => string, dependent?: boolean) => string;
+/**
+ * Own the source while dispatching: lvalues copy once, temporaries move into
+ * the parameter, and the selected payload moves into its destination. Borrowing
+ * a temporary through const& would force an otherwise unnecessary deep copy.
+ */
+export declare const widenedNativeSumText: (source: Representation, target: Representation, text: string) => string | null;