@geastack/compiler 1.0.15

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

@@ -0,0 +1,738 @@
+import type { NativeSelectionHelper } from './native-selection-helpers.js';
+import type { CallableAbi, Representation, TaggedUnionArm } from '../../representation/model.js';
+import type { IrOperand, MergeLiveArmRebuildOperation } from '../../ir/model.js';
+import type { DeclarationId, FunctionId } from '../../identity/ids.js';
+import type { ConversionNode } from '../../conversion/algebra.js';
+import type { ConversionCensus } from '../../conversion/nodes.js';
+import type { RecordLayoutPolicy } from '../../representation/policies.js';
+import type { ClassLayout } from '../../projection/classes.js';
+import type { CaptureIndex } from './emit-context.js';
+import { type EmitContext } from './emit-context.js';
+/**
+ * Whether the C++ backend has a concrete reconciliation recipe for a promise
+ * payload. Promise-to-promise conversion is state adoption plus this payload
+ * conversion, so preflight and emission must ask the same authority rather
+ * than maintaining a second, inevitably drifting list of payload pairs.
+ */
+export declare const promisePayloadConvertible: (source: Representation, target: Representation) => boolean;
+/**
+ * A base-class carrier narrowed to a union of descendant classes.
+ *
+ * The physical carrier intentionally remains one `Ref<Base>`: allocation
+ * identity supplies the target union's discriminant, and checked class-family
+ * downcasts preserve the same native object. This is shared by cell and field
+ * reads because both are projections out of wider storage. An optional target
+ * preserves the source's absence around the projected descendant union.
+ */
+export declare const classFamilyLoadText: (ctx: ConversionSite, held: Representation, read: Representation, text: string) => string | null;
+/**
+ * The load a narrowing licenses, or `null` when the two carriers are the same
+ * and there is nothing to load.
+ *
+ * Returning `null` for "no narrowing needed" and throwing for "no narrowing
+ * possible" keeps the two apart: the first is the ordinary case, the second is
+ * a program this compiler already knows is wrong.
+ */
+export declare const narrowedLoadText: (held: Representation, read: Representation, text: string) => string | null;
+/**
+ * The store a widening needs, or `null` when the value can be assigned as it
+ * stands.
+ *
+ * This is the mirror of `narrowedLoadText` and it exists for the same reason:
+ * `const x: string | number = 3` puts a `double` into a `TaggedUnion`, and the
+ * language really does widen there -- the union is the declared carrier and the
+ * initializer is one arm of it.
+ *
+ * `gea::Optional<T>` needs nothing: it declares a converting assignment from
+ * `T`, so a present value assigns straight in and the presence flag follows.
+ * `gea::TaggedUnion` deliberately declares no such thing, because there is no
+ * one answer -- two arms can share a C++ type, and an implicit conversion would
+ * have to pick one silently. `ofArm<Index>` is where that choice is stated, and
+ * the index is the arm's position in the checker's own order, the same order
+ * the load reads back.
+ *
+ * The first arm carrying the written carrier is the one chosen. When several
+ * do, they are indistinguishable at runtime by construction -- the load
+ * dispatches over exactly that set and reads the same C++ type from any of them
+ * -- so the choice is not observable. What would be observable is choosing an
+ * arm that does *not* carry it, which is what returning `null` prevents.
+ */
+/**
+ * The `gea::Value::Tag` a concrete representation boxes under when it is
+ * written into a `dynamic` cell -- the widening direction `conversion/
+ * derive.ts`'s narrowing-only algebra has no answer for (see citations.md
+ * finding 1). `null` for a carrier this compiler does not yet box (a
+ * container, a proxy, an existing `dynamic` itself, which the
+ * `representationKey` equality check above already short-circuits): an
+ * omission to extend deliberately later, not to guess at here.
+ *
+ * Exported so `targets/cpp/conversions.ts`'s `widening` registry entry can
+ * ask the identical question when the conversion graph -- not just a
+ * `convert` this function already renders -- needs to know whether boxing a
+ * given carrier is a real, installed capability. One answer, asked from both
+ * the preflight authority and the emission authority, rather than a second
+ * table naming the same tags that could drift from this one.
+ */
+export declare const dynamicTagFor: (representation: Representation) => string | null;
+/**
+ * One value, boxed.
+ *
+ * A CALLABLE with a rest parameter takes the ABI-stating form: which formal
+ * absorbs the trailing arguments is invisible in the C++ type -- `(a, xs: T[])`
+ * and `(a, ...xs: T[])` are the same `CallableObject` -- so a dynamic call
+ * through the box would hand the first trailing argument to a slot expecting
+ * the packed array (10.2.11 binds a rest parameter to an Array of ALL the
+ * remaining ones). The emitter is the only reader of the ABI, so it states the
+ * position here and `gea::Value::boxCallable` records the matching thunk.
+ * hono's `this[method] = (args1, ...args) => ...` is every `app.get(path,
+ * handler)` in the program.
+ */
+export declare const boxedText: (representation: Representation, tag: string, text: string) => string;
+/**
+ * How a native carrier boxes into a dynamic cell, rendered over an arbitrary
+ * text naming the storage.
+ *
+ * The dynamic reason is stated HERE rather than at each caller because it is
+ * not a choice: `widenedStoreText` records below that no `DynamicReason` is
+ * consulted on this edge -- every boundary a reason names admits any concrete
+ * value the checker lets reach it -- so a caller asking "box this carrier"
+ * asks this one question and must not be free to spell a different reason for
+ * it.
+ *
+ * `storage` is a TEXT, not a member. The recipe is a function of the
+ * representation and that text alone: no field key, no struct name, no
+ * surrounding statement. So two fields spelling the same carrier spell the
+ * same recipe, and the native field table's read hook can render an optional
+ * or union carrier's arms ONCE over a slot its key chain selects into
+ * (`records.ts`) instead of once per field. `null` is the renderer's own
+ * answer that this carrier needs no widening at all.
+ */
+export declare const dynamicCarrierBoxText: (carrier: Representation, storage: string) => string | null;
+/**
+ * A `dynamic` value an async body returns, settled into its `Promise<V>`
+ * result. The value may itself be a promise, which the return ADOPTS rather
+ * than fulfils with (ECMA-262 27.2.1.3.2), so the choice is made at run time
+ * by `gea::detail::promiseFromDynamic` -- the store-direction recipe below.
+ */
+export declare const dynamicPromiseAdoptionText: (result: Extract<Representation, {
+    kind: "promise";
+}>, text: string) => string | null;
+export declare const widenedStoreText: (held: Representation, written: Representation, text: string) => string | null;
+/**
+ * Rebuilding a tagged union at a different arm ordering than the one it was
+ * built with.
+ *
+ * Two declared unions with the same member set do not have to agree on tag
+ * order -- `boolean | number` and `number | boolean` are two unrelated C++
+ * template instantiations (`gea::TaggedUnion<bool, double>` vs
+ * `gea::TaggedUnion<double, bool>`), which is exactly what a control-flow merge
+ * produces when its two branches arrive through independently-declared unions.
+ * Neither `narrowedLoadText` nor `widenedStoreText` covers it: the target is
+ * not one arm of the source, and the source is not one arm of the target. What
+ * it needs is the same discriminant `narrowedLoadText` reads, dispatched into
+ * the same constructor `widenedStoreText` calls -- read the live arm by
+ * whichever tag the source actually holds, and rebuild it at the target's tag
+ * for that same value type. `null` when some source arm has no same-typed home
+ * in the target: that is a real hole in the target's arm set, not a spelling
+ * gap, and inventing a fallback there would silently drop a live value.
+ */
+/**
+ * A sum converted ARM BY ARM into one payload, or `null` when an arm has no
+ * way there.
+ *
+ * tsc's `visitEachChild<T>` returns `fn === undefined ? node : fn(node, ...)`
+ * where `fn` is a `VisitEachChildFunction<any>`: the conditional merges `T`
+ * with a declared `any` into `tagged-union(native-record-ref | dynamic)`, and
+ * the function returns `T | undefined`. The typed arm IS the payload; the
+ * dynamic arm is the checked unbox every read of a declared-`any` value into
+ * a typed cell already performs (`unboxedLoadText`, which aborts naming the
+ * carrier on a mismatch). So the load dispatches on the live arm, exactly as
+ * `recastedUnionText` does for a sum whose home is another sum. Only a sum
+ * WITH a dynamic arm is answered: without one, a same-keyed arm beside
+ * others is a narrowing (`narrowedLoadText`), which selects an arm and
+ * proves nothing about the rest, and this must not stand in for it.
+ * `targets/cpp/conversions.ts`'s `recasting` admits the pair on the same
+ * predicate -- through this function -- so the admission and the render
+ * cannot drift.
+ */
+export declare const sumIntoPayloadText: (source: Extract<Representation, {
+    kind: "tagged-union";
+}>, payload: Representation, text: string, wrap: (armText: string) => string) => string | null;
+export declare const recastedUnionText: (source: Extract<Representation, {
+    kind: "tagged-union";
+}>, target: Extract<Representation, {
+    kind: "tagged-union";
+}>, text: string, viaLayout?: (source: Representation, target: Representation, text: string) => string | null) => string | null;
+export interface RecastUnionHome {
+    readonly index: number;
+    readonly text: string;
+    /** `text` is already a complete value of the target union (a nested union arm homed as a whole), not an arm payload to wrap in `ofArm`. */
+    readonly whole?: true;
+}
+/** The text an arm of a multi-arm source is read through, bound by `recastedUnionFromHomes`; a single-arm source reads the value itself. */
+export declare const recastUnionArmText: (source: Extract<Representation, {
+    kind: "tagged-union";
+}>, text: string, index: number) => string;
+/**
+ * The dispatch over a sum's arms, given each arm's home in the target: the
+ * discriminant read and the `ofArm` rebuild are one answer, whoever decided
+ * the homes -- the chain probe above or a plan the census owns
+ * (`conversion/record-view.ts`).
+ */
+export declare const recastedUnionFromHomes: (source: Extract<Representation, {
+    kind: "tagged-union";
+}>, target: Extract<Representation, {
+    kind: "tagged-union";
+}>, text: string, homes: readonly RecastUnionHome[]) => string | null;
+/** Two array carriers of one element and ownership whose only difference is the extension an interface adds -- one C++ type. */
+export declare const sameArrayUpToExtension: (left: Representation, right: Representation) => boolean;
+export declare const recordsRecastable: (source: Representation, target: Representation) => boolean;
+/**
+ * Whether an admitted record recast moves any field across the dynamic
+ * boundary: boxes a native field into a `dynamic` destination (the
+ * `to.kind === 'dynamic'` admission of `recastableFieldValue`) or unboxes a
+ * `dynamic` source field into a native one -- through an optional's payload,
+ * a nested record, or a container's element.
+ *
+ * `targets/cpp/conversions.ts` states `nativeFieldProtocol: 'unused'` for a
+ * record recast, which `ir/reflection-demand.ts` reads as "this copy asks no
+ * dynamic field table, so the fields it copies keep their sealed keys-only
+ * protocol". That is true of a recast that only copies native storage. A
+ * recast that boxes a field hands the boxed payload to every later dynamic
+ * read, and those reads DO go through the payload's field protocol -- so the
+ * claim must not be made for it, or the boxed child is emitted without the
+ * protocol the box needs (`reflection-demand.test.ts`, "a boxed destination
+ * still exposes its payload").
+ */
+export declare const recordRecastCrossesDynamic: (source: Representation, target: Representation) => boolean;
+/**
+ * A record recast into a dictionary, one level out from `recordsRecastable`
+ * above.
+ *
+ * A `record`'s field set is CLOSED and known at compile time; a `dictionary`'s
+ * is open and string/number-keyed. Going from the closed shape to the open one
+ * loses no information -- every field the record has, the dictionary can hold
+ * -- so the direction is always sound, unlike the reverse (`derive.ts`'s own
+ * `dictionary` case: "Product needs a complete frozen field list", never
+ * derivable from an open one). Concretely this is `return {}` reaching a
+ * function whose declared result is `Record<string, V>`: TypeScript types the
+ * empty literal as the record with zero fields it is, not as the dictionary
+ * its ABI slot wants, and the two carriers stay genuinely different even
+ * though the empty case rebuilds to zero inserts.
+ *
+ * Every field's own value must have an installed conversion into the
+ * dictionary's declared value carrier. This is the same store each field
+ * would perform if the source literal had been contextualized as the index
+ * signature in the first place: a scalar into a declared `any` slot boxes at
+ * that explicit dynamic boundary, and a typed slot keeps its ordinary native
+ * conversion. A field with no such conversion refuses the whole recast before
+ * any output is rendered.
+ */
+export declare const recordCastableToDictionary: (source: Extract<Representation, {
+    kind: "record";
+}>, target: Extract<Representation, {
+    kind: "dictionary";
+}>) => boolean;
+/**
+ * An open dictionary recast into another open dictionary over the same key
+ * domain whose VALUES it widens into -- `Record<string, string>` reaching a
+ * slot declared `OutgoingHttpHeaders` (`{ [name: string]: string | number |
+ * boolean | readonly string[] | undefined }`). TypeScript's `||` typing
+ * subtype-reduces the two into the wider one, so `@hono/node-server`'s `get
+ * headers()` -- `cache[2] || { 'content-type': defaultContentType }` where
+ * the slot is `Record<string, string> | [string, string][] |
+ * OutgoingHttpHeaders | undefined` -- publishes ONLY the wider dictionary as
+ * the merge's arm, and both the literal and the slot's own string-dictionary
+ * arm have to reach it. Nothing between the two carriers is a view: a
+ * `gea::Dictionary<std::string>` and a `gea::Dictionary<gea::Optional<...>>`
+ * are two template instantiations.
+ *
+ * One level out from `recordCastableToDictionary` above and admitted on the
+ * same terms: every value the source holds converts into the target's value
+ * carrier by the store it would have performed had the entry been written
+ * against the wider index signature in the first place, and the rebuild is a
+ * fresh table -- the same fresh table the record pour builds, with the same
+ * consequence, that a program which keeps writing the SOURCE afterwards and
+ * reads the widened copy does not see the write. The record pour already
+ * stands on that ground for the identical pair one shape narrower; this does
+ * not extend it further.
+ *
+ * String keys only. `gea::NumericDictionary` and `gea::SymbolDictionary` are
+ * different containers with their own iteration, and nothing has asked for
+ * them; a pair over either refuses by name rather than guessing a spelling.
+ */
+export declare const dictionaryCastableToDictionary: (source: Extract<Representation, {
+    kind: "dictionary";
+}>, target: Extract<Representation, {
+    kind: "dictionary";
+}>) => boolean;
+/**
+ * The text a `convert` renders to, or `null` when nothing installed performs it.
+ *
+ * A convert is a carrier change the graph asked for by name -- a merge that
+ * keeps one side, an optional chain's absent arm -- so unlike a narrowing read
+ * it may widen, and unlike a widening store it may be handed an absence rather
+ * than a payload.
+ *
+ * The absence cases are not spelled here. They used to be, and that private
+ * copy was the defect: `widenedStoreText` -- which every ordinary store site
+ * asks, and which this function's own tail already delegates to -- carried no
+ * absence rule, so a `null` reaching a binding, a field or a return came out
+ * unconverted while the same `null` reaching an explicit `convert` came out
+ * right. One question, two answers, and only the quieter one was wrong. The
+ * rule now lives once, on the store side, and this function reaches it through
+ * the same tail it already used for every other widening.
+ */
+/**
+ * The calling convention of a carrier the backend spells
+ * `gea::CallableObject<...>`, or `null` for anything else.
+ *
+ * The constructor carriers are deliberately absent even though they also state
+ * one convention: they spell `gea::ConstructorObject<...>`, which declares no
+ * converting constructor, so the rule below does not hold for them.
+ * `function-and-constructor` is absent for a different reason -- it states two
+ * conventions, and picking one here would answer a question the value does not.
+ */
+export declare const callableObjectAbi: (representation: Representation) => CallableAbi | null;
+/**
+ * An object the program asserts (`env as unknown as Bindings`) or narrows
+ * (`body instanceof Uint8Array` over a declared `string | ReadableStream`)
+ * into a union none of whose arms it can become, even as a structural view. The
+ * assertion went through `unknown`, so it is carried as that: boxed, then
+ * read back out with the exact-type check every box read makes, which aborts
+ * by name when the value is not what the program claimed rather than
+ * inventing a layout. The last resort after `structuralRecordViewText`, and
+ * asked only there and in the census's matching fallback.
+ */
+export declare const boxedAssertionText: (source: Representation, target: Representation, text: string) => string | null;
+/** Whether `source` reaches `target` through a result adapter -- see `resultAdapterOf`. Exported so `conversions.ts` asks the identical question the render below answers. */
+export declare const adaptsResultIntoTarget: (source: Representation, target: Representation) => boolean;
+/** The same adapter selection used by the printer publishes its transport facts to the conversion census. */
+export declare const resultAdapterTransportOf: (source: Representation, target: Representation) => {
+    readonly nativeConventions: {
+        readonly from: CallableAbi;
+        readonly to: CallableAbi;
+    } | null;
+} | null;
+/** The adapter itself, or `null` for a pair that needs none -- see `resultAdapterOf`. */
+export declare const resultAdaptedCallableText: (source: Representation, target: Representation, text: string) => string | null;
+/**
+ * A callable filling a slot that declares MORE parameters than it does, the
+ * extra ones landing after every one the source itself names./**
+ * A callable filling a slot that declares MORE parameters than it does, the
+ * extra ones landing after every one the source itself names.
+ *
+ * ECMA-262 does not bind the extra arguments, so `() => void` really is a
+ * `(time: number) => void` and TypeScript accepts it everywhere, and the same
+ * is true one prefix over: hono's `Hono.getPath` merges two
+ * `(request: Request) => string` values into a field declared
+ * `(request: Request, options?: {env?}) => string` -- one shared leading
+ * parameter, one trailing parameter neither physical function looks at.
+ * `gea::CallableObject`'s own converting constructor (gea_runtime.h) performs
+ * both shapes, so the value converts by being written where the wider one is
+ * expected and needs no text of its own.
+ *
+ * The source's own parameters must be a TYPE-MATCHING PREFIX of the target's,
+ * not merely a shorter count: converting an arbitrary prefix without proving
+ * each shared position's type matches would let a wrong guess pass a value
+ * into a slot expecting something else, which is what the runtime
+ * constructor's own `IsTypePrefix` proves at compile time rather than
+ * assumes, and this predicate re-asks the identical question so the two
+ * cannot disagree about which pairs the constructor actually accepts. Every
+ * position through the source's own last one has to agree, not only the
+ * first -- `(a: string) => void` is not a sound stand-in for
+ * `(a: string, b: number, c: string) => void` merely because position 0
+ * matches; every position the source declares has to. The result and the
+ * receiver must still agree exactly -- neither is dropped by a call, so a
+ * difference in either is a real mismatch, not a binding the language elides.
+ */
+/**
+ * A method value -- its receiver first in its physical convention -- filling
+ * a slot that declares the same convention WITHOUT one: `gea_runtime.h`'s
+ * `CallableObject::bindReceiver`, which packs the receiver the property read
+ * went through in with the value. Everything but the receiver has to agree
+ * exactly, in the C++ spelling the runtime's own signature matching sees
+ * (`cppAbiType`, the one authority on that spelling), so the adapter's
+ * `Result(Receiver, Arguments...)` is the source's own type and nothing is
+ * coerced on the way through.
+ *
+ * Only the SHAPE is decided here; whether the pair can actually be rendered
+ * -- the read's receiver has to be recoverable at the site, and the body must
+ * never read `this` -- is `emit-callable.ts`'s `receiverBoundCallableText`'s
+ * question, a fact of the emitter's context and not of the two carriers.
+ */
+/**
+ * A `this`-TYPED function value, stored in a field and read through the object
+ * whose `this` it names: `gea_runtime.h`'s `CallableObject::bindReceiver`
+ * again, but reached from a fact about the two DECLARATIONS rather than from a
+ * method body.
+ *
+ * hono's `RegExpRouter` writes `match: typeof match<Router<T>, T> = match`
+ * over `function match<R extends Router<T>, T>(this: R, method, path)`, while
+ * `TrieRouter` and `SmartRouter` declare `match` as an ordinary method -- and
+ * `Router<T>` itself declares it as a method, with no `this` at all. So the
+ * field's carrier names a receiver and every read through the interface (or
+ * through the union of the three implementors) publishes one that does not,
+ * and nothing converted between them.
+ *
+ * Binding the read's own receiver is the only call the language admits here,
+ * which is what makes this sound where the detached-METHOD case next door
+ * needs `readsReceiver` to hold: a `this` parameter is a parameter, and
+ * TypeScript refuses a call through the value that does not supply one
+ * (`The 'this' context of type 'void' is not assignable...`). A method has no
+ * such annotation, so a detached call really can reach it with `this`
+ * undefined, and binding there would answer where the program would have
+ * thrown.
+ */
+export declare const receiverBoundFieldText: (ctx: ConversionSite, stored: Representation, published: Representation, storedText: string, receiver: Representation, receiverText: string) => string | null;
+export declare const bindsReceiver: (source: Representation, target: Representation) => boolean;
+export declare const dropsUnboundParameters: (source: Representation, target: Representation) => boolean;
+/**
+ * A zero-parameter callable filling a slot that declares at least one
+ * parameter AND whose result is a tagged union naming the source's own
+ * result as one of its arms -- `dropsUnboundParameters`'s zero-arity special
+ * case (`gea_runtime.h`'s `dropArguments`) composed with
+ * `gea::TaggedUnion::ofArm`, for a source neither alone accepts:
+ * `dropsUnboundParameters` requires an IDENTICAL result, and a bare `ofArm`
+ * conversion has no arity adaptation of its own.
+ *
+ * hono's `Context.notFound`: `this.#notFoundHandler ??=
+ * () => createResponseInstance()` merges a `() => Response` into a field
+ * declared `(c: Context) => Response | Promise<Response>`.
+ * `gea_runtime.h`'s `ResultWidensIntoArm` proves the identical pairing at
+ * the type level; this re-asks the same two-part question so the two cannot
+ * disagree about which pairs the runtime constructor actually accepts.
+ *
+ * Deliberately narrower than `dropsUnboundParameters`: a nonzero source
+ * arity is left entirely to that function (its PREFIX proof does not carry
+ * over once the result itself also changes), and a target result that is
+ * not a tagged union, or a source result that is not EXACTLY one of its
+ * arms, is refused -- the same fail-closed discipline `ResultWidensIntoArm`
+ * documents in the runtime.
+ */
+export declare const dropsAllParametersIntoResultArm: (source: Representation, target: Representation) => boolean;
+/**
+ * A callable filling a slot whose declared result is `void`, its own result
+ * being anything else -- same parameters, in the same order, with the same
+ * types; only the RESULT differs, and only in the direction of being
+ * discarded.
+ *
+ * ECMA-262 makes this sound for a reason distinct from the other two
+ * predicates above: a call's result is simply not read unless something
+ * reads it, so a function returning `T` really is a valid `() => void` (or
+ * any arity's `void`-returning form) wherever the caller never names the
+ * result -- `Array.prototype.forEach`'s callback contract is the textbook
+ * case, and this port's own is `node:http`'s `RequestListener = (req, res)
+ * => void`: `createServer(async (req, res) => { ... })` is an everyday Node
+ * idiom (`apps/hono-hello/server.ts` is one), and TypeScript accepts a
+ * `Promise<void>`-returning callback there for the identical reason -- a
+ * `void`-returning function TYPE is satisfied by ANY return type, precisely
+ * so a caller who ignores the result is never forced to wrap it.
+ *
+ * `gea_runtime.h`'s `CallableObject` composed converting constructor this
+ * asks for discards whatever the source returns; see that constructor's own
+ * comment for why doing so is never lossy for an async body specifically --
+ * this runtime's `Promise<V>` is a settled-value box, never a coroutine
+ * frame, so by the time a call returns here its entire body, `await`s
+ * included, has already run to completion.
+ *
+ * Gated the mirror of `dropsAllParametersIntoResultArm` above: parameters
+ * must agree in COUNT and in every position's TYPE (this is not an arity
+ * change, `dropsUnboundParameters`'s own axis -- it is a pure result
+ * change), the receiver must agree exactly on both sides (a call's receiver
+ * is never dropped), and the target's result must actually BE `void` --
+ * anything else stays a hard compile error, this file's shared fail-closed
+ * rule. Source and target already sharing `void` needs no constructor at
+ * all: `cppTypeOf` equality above already renders that as the identity
+ * text, so this predicate is never even asked.
+ *
+ * Zero parameters is excluded on the runtime constructor's own account, not
+ * this predicate's: `gea_runtime.h`'s matching constructor collapses to the
+ * textually identical signature the `ResultWidensIntoArm`-gated one above it
+ * already declares once `Arguments...` is empty, which fails to COMPILE
+ * (every zero-arity `CallableObject<Result()>` in the header, `Result=void`
+ * or not) rather than merely fails to be selected -- see that constructor's
+ * own comment. Asking this predicate to answer `false` there keeps the two
+ * files agreeing about which pairs the runtime actually accepts, the same
+ * discipline `dropsUnboundParameters` and `dropsAllParametersIntoResultArm`
+ * both already state for their own exclusions.
+ */
+/**
+ * A callable whose parameters already agree with the slot's, position for
+ * position, and whose RESULT is exactly one arm of the tagged union the slot
+ * declares -- `dropsAllParametersIntoResultArm` with the arity change taken
+ * back out, leaving only the widening half.
+ *
+ * That predicate requires a ZERO-parameter source and `dropsUnboundParameters`
+ * an IDENTICAL result, so a pair moving along only the result axis at a nonzero
+ * arity satisfies neither -- hono's `Hono.fetch` is one, a `(Context) =>
+ * Response` assigned into a field declared `(Context) => Response |
+ * Promise<Response>`. Sound for exactly the reason `gea_runtime.h`'s
+ * `ResultWidensIntoArm` states, and asked in the same terms so the two cannot
+ * disagree: the result must equal one arm EXACTLY and every other position --
+ * receiver, arity, each parameter's carrier, the rest slot -- exactly, none
+ * being adapted here. `widenResultIntoArm` is the constructor performing it.
+ */
+export declare const widensResultIntoArm: (source: Representation, target: Representation) => boolean;
+/**
+ * A source whose rest parameter sits at a LATER position than the target's.
+ *
+ * ECMAScript has one calling convention, so `(base?: string, sub?: string,
+ * ...rest: string[]) => string` and `(...paths: string[]) => string` are the
+ * same function -- hono's `utils/url.ts` declares exactly that pair on one
+ * `const mergePath`, the annotation stating the second and the initializer
+ * being the first. C++ sees two unrelated function types, and the store
+ * refused.
+ *
+ * The target has to be a single rest parameter, because that array is the
+ * whole of what the thunk has to unpack. Every leading source parameter has
+ * to be `optional(E, undefined)` over the same element the rest carries: a
+ * position the call never reached has to be ABSENT, and a leading slot must
+ * never be handed an element of a type it did not declare. The source's own
+ * rest must sit exactly after its leading run, since the tail is what is
+ * left when those are taken.
+ *
+ * `gea_runtime.h`'s `RestRebaseAdmits` states the identical conditions over
+ * the C++ types, so a pair this admits and that one does not is a compile
+ * error rather than a wrong call -- the same fail-closed pairing every other
+ * predicate here has with its constructor.
+ */
+export declare const rebasesRestOverLeadingParameters: (source: Representation, target: Representation) => boolean;
+export declare const discardsResultIntoVoid: (source: Representation, target: Representation) => boolean;
+/**
+ * Reading a concrete value back OUT of a box -- the direction this backend did
+ * not have.
+ *
+ * `x as unknown as string` is an ASSERTION, not a coercion: the program states
+ * what the value is and TypeScript erases the statement, so what has to happen
+ * at runtime is a read of the payload the box holds, not a `ToString` of
+ * whatever it happens to be. `gea::unboxValue` (gea_runtime.h) is exactly that
+ * read -- it checks the box's tag AND its payload type and aborts by name when
+ * either disagrees, which is where the consequence of a wrong assertion
+ * belongs. The identical primitive `emit-dynamic-properties.ts` already reads
+ * a dynamic property back through; this states the same fact for an ordinary
+ * carrier reconciliation.
+ *
+ * Every tag that has a payload to read, not only the three primitive ones.
+ * This paragraph used to say the opposite -- that a record, a class instance,
+ * a callable or an array was a box whose payload type the target carrier does
+ * not determine, so there was no `T` to name -- and that premise is false: the
+ * target carrier is exactly what determines the `T`, because `cppTypeOf`
+ * spells it and `Value::box` recorded that same spelling's address in
+ * `payloadType()`. `unboxValue` compares the two, so naming the wrong one
+ * refuses by name instead of reinterpreting bytes.
+ *
+ * The stale claim outlived the code it described and was still being cited as
+ * settled by `targets/cpp/conversions.ts`'s own header, which is how that
+ * file's `classRefMaterializer` stayed uninstalled while the load it needed
+ * was already being rendered right here.
+ */
+/**
+ * Every `(tag, payload type)` pair a box can carry for this carrier.
+ *
+ * `dynamicTagFor` answers ONE tag and `null` for a sum, which is the right
+ * answer to "what tag does `Value::box` write for this" and the wrong one to
+ * "which tags could a box holding this carrier have". A union arm, and an
+ * optional's two states, each answer to several. `payload` is `null` where the
+ * tag IS the whole value (`undefined`, `null`) and there is therefore no
+ * recorded payload type to tiebreak a tag collision with -- two such arms under
+ * one tag are genuinely indistinguishable, and compare equal here so the
+ * caller refuses rather than guessing.
+ */
+export type BoxDiscriminant = {
+    tag: string;
+    payload: string | null;
+    nominal: string | null;
+    /** Exact checker-closed FunctionId membership; null for a non-callable discriminator. */
+    callableMembers: readonly FunctionId[] | null;
+};
+export declare const boxDiscriminantsOf: (carrier: Representation) => BoxDiscriminant[] | null;
+/** The representation arm's carried discriminator and the executable classifier must agree. */
+export declare const boxDiscriminantsOfArm: (arm: TaggedUnionArm) => BoxDiscriminant[] | null;
+export declare const unboxedLoadText: (target: Representation, text: string) => string | null;
+/**
+ * `generic-function-set` into a superset: each source index becomes the
+ * target's index of the same member. A one-member source is a constant; a
+ * wider one is a table lookup. `null` when the pair is not a set widening
+ * (a member the target lacks is a narrowing, and no store performs one).
+ */
+export declare const genericFunctionSetWideningText: (source: Representation, target: Representation, text: string) => string | null;
+/**
+ * `never[]` read where `E[]` is wanted: the one empty array of `E`. See
+ * `conversions.ts`'s `gea::emptyArraySentinel` recipe for why identity, not a
+ * fresh `[]`, is the answer, and which pairs it admits. The dynamic target
+ * decides at runtime (`emptyArraySentinelOrBoxed`): an empty source is the
+ * sentinel, a populated one -- a real `undefined[]`, which the carrier cannot
+ * tell apart -- is boxed element by element.
+ */
+export declare const emptyArraySentinelText: (source: Representation, target: Representation, text: string) => string | null;
+/**
+ * One step of the conversion chain. `undefined` means the step does not
+ * claim the pair and the chain continues; `null` means it claims the pair
+ * and cannot render it, which ends the chain with no rendering (the chain's
+ * original early returns); a string is the rendering.
+ */
+export interface ConversionStep {
+    readonly id: string;
+    readonly apply: (source: Representation, target: Representation, text: string) => string | null | undefined;
+}
+/**
+ * The chain, in the order it has always run. Each entry is one recipe with a
+ * stable id; `conversionRecipeOf` names the entry that claims a pair without
+ * rendering it, so the conversion census (`conversion/nodes.ts`) can state
+ * the same answer this printer gives, from the same table.
+ */
+export declare const conversionChain: readonly ConversionStep[];
+/**
+ * One chain call the printer still makes on a pair the IR did not already
+ * align: after Phase 1.3 every operand that enters a slot arrives converted
+ * by lowering, so a printer site that finds its source and target differing
+ * is a decision the census does not own yet. Recorded per site so the 1.4
+ * work list is measured, not guessed; the row names the site, the body and
+ * the pair, and the chain still renders it.
+ */
+export interface PrinterDrift {
+    readonly owner: string;
+    readonly site: string;
+    /**
+     * `refused`: the census has no recipe for the pair and the chain rendered
+     * it (or refused it too). `converted`: the census answered and the printer
+     * rendered its node -- a site that still converts at all, which after
+     * Phase 1.3 is a decision lowering should have made; the by-category
+     * deletion of chain callers (1.4) works this list down.
+     */
+    readonly kind: 'refused' | 'converted';
+    readonly source: string;
+    readonly target: string;
+    /** The census's stated reason the pair has no recipe (`refused`), or the node's capability kind (`converted`). */
+    readonly reason: string;
+    readonly sourceRepresentation: Representation;
+    readonly targetRepresentation: Representation;
+}
+/**
+ * A printer site's conversion, answered by the census: the node `nodeFor`
+ * mints for the pair, rendered by the recipe it names. The site is a
+ * RESULT-side one -- a call's result into the operation's carrier, a union
+ * arm's field into what the read publishes, a host template's value into
+ * the slot -- where the value is produced inside this printer's own
+ * expression and lowering had nothing to convert; every operand-side pair
+ * already arrived converted (`ir/lower-operands.ts`'s `enter`).
+ *
+ * A pair the census has no recipe for is recorded as printer drift with the
+ * census's reason and STILL handed to the chain, because the chain renders
+ * some pairs the census does not yet own (a `dynamic` source the eager
+ * derivation refused, a callable adapter) and refusing them here would
+ * uncertify programs that run. The drift rows are the list of pairs the
+ * census still has to learn; a row whose chain rendering is also `null` is
+ * the refusal the site reports.
+ */
+/**
+ * What a conversion site needs from its context: the census, the drift list
+ * it reports to, and what the record view renders from. A body's
+ * `EmitContext` is one; the program-level renderers with no body (construct
+ * thunks, field initializers, virtual dispatch adapters in
+ * `translation-unit.ts`) build one over the same census.
+ */
+export interface ConversionSite {
+    readonly conversions: ConversionCensus;
+    readonly nativeSelectionHelpers?: ReadonlyMap<string, NativeSelectionHelper>;
+    readonly printerDrift: PrinterDrift[];
+    readonly owner: string;
+    readonly layouts: RecordLayoutPolicy;
+    readonly classes: ReadonlyMap<DeclarationId, ClassLayout>;
+    readonly captures: CaptureIndex;
+    /** The dispatch members this unit emitted; absent where a site has none to name. */
+    readonly virtualDispatch?: ReadonlyMap<string, CallableAbi>;
+}
+export declare const alignedValueText: (ctx: ConversionSite, site: string, source: Representation, target: Representation, text: string) => string | null;
+/**
+ * A census node's recipe, rendered by one of the two renderers the census
+ * owns. The chain first: the registry's atoms ARE its narrowing, widening
+ * and recasting steps, and its static recipes are named by the step that
+ * claimed the pair (`conversions.ts`'s `staticRecipe`). Then the structural
+ * record view (`conversion/record-view.ts`), which renders both the
+ * `view:structural-record` recipe and the registry's `gea::record::recast`
+ * atom -- the eager graph minted that atom for a by-value record entering
+ * an interface's shared shape before the view plan existed, and the chain's
+ * `record-recast` step spells only the by-reference recast, so the view is
+ * that atom's renderer. Keyed by capability KIND rather than by materializer
+ * id on purpose: a node's id says which table answered, not which text
+ * spells it, and every non-`never` node has exactly one of these two.
+ *
+ * `class-family` is a third renderer, asked before the chain rather than
+ * folded into it: `classFamilyLoadText` orders its cascade over
+ * `ctx.classes`, the whole-program class table, and the chain
+ * (`convertedValueText`) is deliberately ctx-free -- see `algebra.ts`'s doc
+ * on the kind for why an `atom` cannot carry this recipe.
+ */
+export declare const recipeText: (ctx: ConversionSite, node: ConversionNode, text: string) => string | null;
+/**
+ * The text of a node a `convert` instruction NAMES, rather than of the pair
+ * it spans: a coercion node shares its (source, target) pair with the store
+ * node `alignedValueText` would look up -- `string -> scalar(number)` is an
+ * exact tag read as a store and StringToNumber as a coercion -- so the
+ * instruction's own node id is the only thing that says which one runs.
+ */
+export declare const namedConversionText: (ctx: ConversionSite, site: string, node: ConversionNode, text: string) => string | null;
+export declare const convertedValueText: (source: Representation, target: Representation, text: string) => string | null;
+export declare const isSpellable: (representation: Representation) => boolean;
+/**
+ * The chain's answer for a pair, as a predicate: the registry's static recipe
+ * and a record view's field and arm pairs (`conversion/record-view.ts`) ask
+ * this one question, so a view the census admits is a view the printer
+ * renders.
+ */
+export declare const chainConverts: (source: Representation, target: Representation) => boolean;
+export declare const conversionRecipeOf: (source: Representation, target: Representation) => {
+    readonly id: string;
+    readonly renders: boolean;
+} | null;
+/**
+ * A DYING refcounted value moves into the slot that takes it rather than being
+ * copied into it -- see `ir/transfer.ts`'s `buildDyingArgumentIndex` for what
+ * makes a value dying, which is the whole of the safety argument.
+ *
+ * Two conditions here, both about the CARRIER rather than the value's life:
+ * only a carrier that owns a count has anything to hand over, and the slot must
+ * hold exactly what the value already holds. `gea::Ref` has no converting move
+ * constructor, so an upcast to a base class binds `std::move(x)` right back to
+ * the copying `Ref(const Ref<Other>&)` -- and any slot needing a real
+ * conversion has already built a temporary of its own, which moving cannot
+ * make cheaper.
+ */
+export declare const movedValueText: (ctx: EmitContext, value: IrOperand, held: Representation | null, text: string) => string;
+/**
+ * The proven-partial-dead-arm sibling of `emit.ts`'s `emitConvert` -- see
+ * `MergeLiveArmRebuildOperation`'s doc comment (`ir/model.ts`) for why a
+ * general `convert` cannot express this.
+ *
+ * `operation.liveArms` is the proof: which of the source's (optional-
+ * unwrapped) tagged-union arms are not proven dead at this merge, computed
+ * once by the control-flow lowering that owns the guard and carried here
+ * unchanged -- never recomputed. `ir/lower-narrow.ts` derives it from
+ * `partialDeadMergeArms` for `&&`; `ir/lower-destructuring.ts` derives it from
+ * the top-level arms surviving a default's `is-defined` guard. Only those
+ * indices are tested, in source-arm order, on the source's own discriminant
+ * (`.is<N>()`/`.get<N>()`, the
+ * identical accessors this file already renders for a narrowed tagged
+ * union above), and the chain falls through to the last live index without
+ * testing it -- sound because reaching this expression at all already proves
+ * the held arm is one of them. The source's own absence (if it is optional)
+ * reads the result's own absent value instead of testing any arm at all.
+ *
+ * Each live arm converts into the result's carrier through `convertedValueText`
+ * (below) FIRST, unmodified, and only when that finds no installed load AND
+ * the result is boolean-shaped (`isBooleanShapedMergeTarget`) does it fall
+ * back to `ToBoolean` (`emit-presence.ts`'s `booleanTestText`) instead. That
+ * fallback is not a general "any carrier converts to boolean" capability -- it
+ * is not added to `convertedValueText`'s own representation-keyed dispatch,
+ * which would let it fire for any unrelated occurrence of the same
+ * representation pair. It fires only here, for an arm THIS merge's own
+ * partial-dead-arm proof already marked live, because a `&&` merge's own
+ * published type collapsing to `boolean | undefined` is the checker having
+ * already proven the kept contribution meaningful only as its truthiness:
+ * ECMA-262's `&&` picks its kept operand by `ToBoolean` in the first place, so
+ * restating that answer as a plain `bool` is not a new fact about the arm's
+ * carrier, it is the exact question this merge already asked of it.
+ */
+export declare const emitMergeLiveArmRebuild: (ctx: EmitContext, lines: string[], operation: MergeLiveArmRebuildOperation) => void;