@geastack/compiler 1.0.15

package/dist/ir/lower-narrow.js

@@ -0,0 +1,320 @@
+import { carriesMergeAbsence, carriesNoAbsence, carriesUndefined, contributesOnlyAbsence, contributesNoTruthiness, isBooleanShapedMergeTarget, isDeadMergeContribution, mergesAsTruthiness, partialDeadMergeArms, representationKey } from '../representation/model.js';
+import { mergeFalsyAbsence, mergeMaterialization, mergeTaggedAbsence } from '../representation/merge.js';
+import { operandOf } from '../semantics/model/operands.js';
+import { IrLoweringBlockedError } from './lower-graph.js';
+import { convertOrDrift, convertTo, resolveRequiredOperand } from './lower-operands.js';
+/**
+ * A merge arm the census cannot bring into the merge's carrier blocks the
+ * body. This is the certification of a merge: preflight used to rebuild
+ * `mergeIncoming`'s decision tree over the semantic graph and refuse the
+ * same pairs one stage earlier (`buildMergeNarrowingObligations`, deleted in
+ * one authority for narrowing); with one authority left,
+ * "no node" is a refusal here rather than a drift row the printer's own
+ * chain would answer, because nothing downstream is entitled to decide it.
+ */
+const blockedMergeArm = (operation, role, from, to) => new IrLoweringBlockedError(`merge arm "${role}" of ${operation.family === 'computation' ? `${operation.form} ${'operator' in operation ? operation.operator : ''}`.trim() : operation.family}: ` +
+    `no conversion is installed from ${representationKey(from)} into ${representationKey(to)}`);
+/**
+ * Every live arm of a rebuilt union must have somewhere to go: the merge's
+ * own key, a census node, or -- for the `&&` rebuild only -- a boolean-shaped
+ * merge, which `emitMergeLiveArmRebuild` renders by `ToBoolean`, total over
+ * every carrier. The `??` rebuild admits no `ToBoolean` shortcut: its kept
+ * branch proved the value PRESENT, and its payload arms are values, not
+ * truthiness. The same two rules preflight's deleted `partialMergeArmsInstalled`
+ * and `presentOptionalMergeInstalled` applied.
+ */
+const requireLiveArmsConvertible = (ctx, operation, role, arms, merged, admitToBoolean) => {
+    if (admitToBoolean && isBooleanShapedMergeTarget(merged))
+        return;
+    const mergedKey = representationKey(merged);
+    for (const arm of arms) {
+        if (representationKey(arm) === mergedKey)
+            continue;
+        if (ctx.program.conversions.nodeFor(arm, merged).capability.kind === 'never')
+            throw blockedMergeArm(operation, role, arm, merged);
+    }
+};
+/**
+ * One incoming value of a merge, in the carrier the merge publishes.
+ *
+ * A phi's incoming values must already carry the phi's own carrier
+ * (`ir/verify.ts`), so wherever an arm does not, the carrier change is an
+ * explicit instruction in *that arm's own block* rather than something the phi
+ * assumes. `a ?? b` is the standing example: it keeps `a` on the branch where
+ * `a` was proven present, and there the merge publishes the payload while the
+ * operand still carries the optional.
+ *
+ * A constant whose declared type is uninhabited is materialized directly in the
+ * merge's carrier instead. `never` is the checker's answer to "does control
+ * reach here", not to "what storage does this value occupy", and the two part
+ * company at exactly one idiom: `typeof X !== 'undefined' ? X : (undefined as
+ * unknown as typeof X)`, the ambient-global guard. The false arm narrows to
+ * `never` *because* the declared type excludes `undefined` -- yet that arm is
+ * the one that runs whenever the host did not inject `X`. The value really is
+ * absent and the merge is what states which carrier holds it, so the constant
+ * is minted there; `cppConstantLiteral` then spells that carrier's absent value
+ * or refuses outright if it has none.
+ *
+ * A *reference* whose declared type is inhabited can still be dead on this
+ * one arm, the identical fact one step less literal: `a && a.b` keeps `a` on
+ * the branch where `a` tested falsy, and when `a`'s own carrier is an Object
+ * (a class instance, a record, a native reference, an array, a callable, ...)
+ * it has no falsy state at all -- ECMAScript's `ToBoolean` never answers
+ * `false` for one. Only `a`'s own absence, if it has one, can be why this
+ * branch runs; the payload contributes nothing, exactly the way the
+ * constant's `never` type contributes nothing above. `role === 'kept'` names
+ * this arm precisely (`ir/lower.ts` passes it only for `&&`/`||`/`??`'s
+ * reused side, never the freshly-evaluated one), `operator === '&&'` is the
+ * one direction where the reachable state is falsy rather than truthy/
+ * present, and `carriesMergeAbsence` is what the merge's own carrier must
+ * satisfy for "materialize the absence" to have anywhere to land -- an
+ * `optional`, or a `native-handle`, which `optional.ts` collapses `T | null`
+ * onto precisely because it self-encodes absence -- and both it and
+ * `contributesOnlyAbsence` are the facts this one authority asks; preflight's
+ * `buildMergeNarrowingObligations` asked the same until Phase 1.6 deleted it.
+ *
+ * The operand's own null counts as that nothing. A bare
+ * `class-ref(shared-refcount)` -- the collapsed form of `T | null` -- is the
+ * one carrier whose falsy state is a value rather than a hole, and it is a
+ * value the merge's absence already spells; `contributesOnlyAbsence` is the
+ * whole-operand reading that admits it, where the per-arm
+ * `isDeadMergeContribution` beside it must not.
+ */
+export const mergeIncoming = (ctx, block, lineage, operation, role, operand, representation) => {
+    const materialization = mergeMaterialization(ctx.graph.structuralTypes, ctx.constantDeriver, operand, representation);
+    if (materialization === 'constant' && operand.source.kind === 'constant') {
+        return { value: ctx.builder.constant(block, lineage, operand.source.text, operand.source.literal, representation), representation };
+    }
+    if (materialization === 'absence') {
+        // A tagged union can carry both absences; the arm that contributed
+        // `undefined` (a `void` default, an uninhabited branch) must land in the
+        // `undefined` arm, or `[w = c()]` on a short array prints `null`.
+        const absence = representation.kind === 'optional' ? representation.absence : carriesUndefined(representation) ? 'undefined' : 'null';
+        return { value: ctx.builder.constant(block, lineage, absence, absence, representation), representation };
+    }
+    // The same fact one step up from a scalar: an arm whose declared type is
+    // uninhabited is materialized in the merge's carrier rather than converted
+    // into it. `xs ? xs : []` is the standing idiom -- the checker types the
+    // literal `never[]` and the conditional `T[]` -- and a conversion is the
+    // wrong instruction for it in both directions: `array-object(undefined)` and
+    // `array-object(T)` are different C++ types that cannot alias, so nothing
+    // could reinterpret one as the other, and there is nothing to reinterpret
+    // either, because an array of the uninhabited type is empty. The empty array
+    // OF THE MERGE'S OWN ELEMENT TYPE is the whole value, so it is built here, in
+    // this arm's own block, exactly as the constant above is.
+    //
+    // What this gives up is reference identity with the arm's own array, on the
+    // one arm where nothing can observe it: two `never[]`s differ in no element,
+    // no length and no future write, so only a `===` against the arm's own
+    // binding could tell them apart -- and that arm previously did not lower at
+    // all.
+    if (representation.kind === 'array-object' && materialization === 'empty-array') {
+        return { value: ctx.builder.allocateArrayObject(block, lineage, [], representation), representation };
+    }
+    // The same construction where the merge's carrier is a stated-native array
+    // instead of an `ArrayObject`: `path.match(/\/:/g) || []` (hono's
+    // `reg-exp-router/trie.ts:10` and `router.ts:132`) publishes
+    // `gea::runtime::regex::MatchResult`, which IS an `ArrayObject<std::string>`
+    // carrying 22.1.3.13's named members beside it. `mergeMaterialization` is
+    // what proved the empty one is a complete value of that carrier; the
+    // primitive is the record allocation an object/array literal with the same
+    // carrier already lowers through (`ir/lower-allocation.ts`), with no fields,
+    // because an empty array has none to install.
+    if (representation.kind === 'native-record-ref' && materialization === 'empty-array') {
+        return { value: ctx.builder.allocateRecord(block, lineage, [], representation), representation };
+    }
+    // An arm typed `never` (`Debug.fail()`) ran its own operations in its own
+    // block and never completes; the phi still needs an incoming value from
+    // that block, spelled as the dead `&&` arm below spells its own: an
+    // `undefined` converted into the merge carrier, which `emit.ts` renders as
+    // `gea::host::unreachableValue<T>()` when no load exists.
+    if (materialization === 'unreachable') {
+        const absent = { kind: 'undefined' };
+        const dead = { value: ctx.builder.constant(block, lineage, 'undefined', 'undefined', absent), representation: absent };
+        return convertOrDrift(ctx, block, lineage, operation.id, role, operand.ordinal, dead, representation);
+    }
+    const incoming = resolveRequiredOperand(ctx, block, lineage, operand);
+    const from = representationKey(incoming.representation);
+    const to = representationKey(representation);
+    if (from === to)
+        return incoming;
+    const falsyAbsence = mergeFalsyAbsence(incoming.representation, representation);
+    if (role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '&&' &&
+        falsyAbsence) {
+        return { value: ctx.builder.constant(block, lineage, falsyAbsence, falsyAbsence, representation), representation };
+    }
+    if (role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '&&' &&
+        carriesMergeAbsence(representation) &&
+        contributesOnlyAbsence(incoming.representation)) {
+        return { value: ctx.builder.constant(block, lineage, 'undefined', 'undefined', representation), representation };
+    }
+    // The kept operand has NO falsy state and the merge carries no absence for
+    // one to land in: `previousSibling && format & Flag` on a present `Node`.
+    // This branch never runs, and the checker already dropped the object from
+    // the expression's type. The phi still needs an incoming value from the
+    // block, so it gets the one thing a dead arm can honestly hold: an
+    // `undefined` converted into the merge carrier, which `emit.ts`'s convert
+    // renders as `gea::host::unreachableValue<T>()` when no load exists --
+    // the same rendering a default past an empty tuple already gets. Licensed
+    // by the identical predicate in `preflight/obligations-graph.ts`.
+    if (role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '&&' &&
+        isDeadMergeContribution(incoming.representation)) {
+        const absent = { kind: 'undefined' };
+        const dead = { value: ctx.builder.constant(block, lineage, 'undefined', 'undefined', absent), representation: absent };
+        return convertOrDrift(ctx, block, lineage, operation.id, role, operand.ordinal, dead, representation);
+    }
+    // The `||` mirror of the dead arm above: the kept operand has NO truthy
+    // state (`contributesNoTruthiness`), so `a || b` never publishes it.
+    // Licensed by the identical predicate in `preflight/obligations-graph.ts`.
+    if (role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '||' &&
+        contributesNoTruthiness(incoming.representation)) {
+        const absent = { kind: 'undefined' };
+        const dead = { value: ctx.builder.constant(block, lineage, 'undefined', 'undefined', absent), representation: absent };
+        return convertOrDrift(ctx, block, lineage, operation.id, role, operand.ordinal, dead, representation);
+    }
+    // The partial sibling of the whole-dead-arm bypass immediately above: SOME
+    // of `incoming`'s tagged-union arms are dead rather than all of them --
+    // `results[name]` typed `T[] | string`, where `T[]` (object-shaped, always
+    // truthy) can never be why this `&&` fell through but `string` (an empty
+    // one) can. `partialDeadMergeArms` states the split; `requireLiveArmsConvertible`
+    // above is what certifies it (every live arm has a census node or the
+    // merge is boolean-shaped), blocking the body otherwise. `MergeLiveArmRebuildOperation`
+    // (`ir/model.ts`) is why this needs its own operation rather than the
+    // general `convert` below: a dropped arm is sound only at a merge the
+    // checker's own narrowing already proved it for, not everywhere the same
+    // source/result pair recurs, so the proof travels as this operation's own
+    // `liveArms`, computed once here and never re-derived at emission.
+    const split = partialDeadMergeArms(incoming.representation);
+    if (split &&
+        role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '&&' &&
+        (!split.keptIsOptional || carriesMergeAbsence(representation) || mergeTaggedAbsence(incoming.representation, representation) !== null)) {
+        requireLiveArmsConvertible(ctx, operation, role, split.liveIndices.flatMap((index) => (split.payload.arms[index] ? [split.payload.arms[index].value] : [])), representation, true);
+        return {
+            value: ctx.builder.mergeLiveArmRebuild(block, lineage, incoming, representation, split.liveIndices, split.keptIsOptional, ctx.program.conversions),
+            representation
+        };
+    }
+    // `a ?? b` reaches its kept branch only after the presence test succeeded.
+    // When `a` is `Optional<TaggedUnion<...>>`, that proof removes the optional
+    // wrapper's absence while preserving every payload arm. Rebuild the live
+    // payload into the merge carrier at this site rather than installing the
+    // unsound global conversion `optional(T) -> U`, which would have no answer
+    // for absence at unguarded occurrences of the same pair.
+    if (role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '??' &&
+        incoming.representation.kind === 'optional' &&
+        incoming.representation.payload.kind === 'tagged-union') {
+        requireLiveArmsConvertible(ctx, operation, role, incoming.representation.payload.arms.map((arm) => arm.value), representation, false);
+        return {
+            value: ctx.builder.mergeLiveArmRebuild(block, lineage, incoming, representation, incoming.representation.payload.arms.map((_, index) => index), false, ctx.program.conversions),
+            representation
+        };
+    }
+    // A `&&` whose merged type is a plain `boolean`: the kept operand is here
+    // only as its own truthiness, which is the very question `&&` asked of it.
+    // `object && object.isObject3D` over three's `Object3D` is the shape -- the
+    // checker collapsed the whole expression to `boolean`, so no VALUE of the
+    // kept operand survives to be converted, only its `ToBoolean`.
+    // `mergesAsTruthiness` is the identical fact
+    // `preflight/obligations-graph.ts` licenses this with, and the `test`
+    // operation renders through `emit-presence.ts`'s `booleanTestText`, which
+    // is total over every carrier -- including a nullable `class-ref`, whose
+    // truthiness is exactly its presence.
+    //
+    // LAST of the three, on purpose. The whole-dead bypass above materializes an
+    // absence where the merge has somewhere to hold one, and the partial-arm
+    // rebuild converts each still-live arm on its own; both are strictly more
+    // precise than one `ToBoolean` over the operand, and both already covered
+    // the programs that reach them. This answers only what neither did.
+    if (role === 'kept' &&
+        operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        operation.operator === '&&' &&
+        mergesAsTruthiness(representation)) {
+        return { value: ctx.builder.test(block, lineage, incoming), representation };
+    }
+    // Which arms the merge's own test proves present: `a || b` and `a ?? b`
+    // keep `a` only when it is truthy or non-nullish, and a default keeps its
+    // extraction only past the `is-defined` guard. A conditional's arm, or the
+    // falsy operand `&&` keeps, is chosen by something else.
+    const guarded = (operation.family === 'computation' &&
+        operation.form === 'logical' &&
+        (operation.operator === '||' || operation.operator === '??') &&
+        role === 'kept') ||
+        (operation.family === 'destructuring' && operation.form === 'default-value' && role === 'extracted');
+    const converted = convertTo(ctx, block, lineage, incoming, representation, guarded ? 'guard' : 'merge-arm');
+    if (converted !== null)
+        return converted;
+    // The general form of the `optional(tagged-union)` rebuild above, and the
+    // last thing asked rather than the first: a guarded arm whose payload -- not
+    // the optional around it -- is what the merge's carrier accepts.
+    //
+    // `(options?.onError ?? console.error)(e)` (node-server's `websocket.ts`) is
+    // the standing shape. TypeScript reduces the merged type to `console.error`'s
+    // own `(...data: any[]) => void`, because the positional handler really is
+    // assignable to it, so the merge publishes that one frame; the kept operand
+    // still carries `optional((any) => void)` because that is what the FIELD
+    // holds. Both halves are already installed as census nodes -- the presence
+    // load `optional(T) -> T`, and `T -> U`, the callable adapter a conditional
+    // between the same two functions already lowers through -- and the pair
+    // `optional(T) -> U` is not, deliberately: it has no answer for absence at
+    // the unguarded occurrences of the same pair, which is precisely why the
+    // rebuild above refuses to install it globally.
+    //
+    // What licenses composing them here is `guarded`, already computed above:
+    // `??` reached this branch past a nullish test, `||` past a truthiness test
+    // (an absent optional is falsy, so truthy proves present too), and a
+    // destructuring default past its own `is-defined` guard. The presence is the
+    // branch's, so the unwrap is branch-local -- the same thing the constant and
+    // empty-array materializations above are -- and neither step is a new
+    // capability.
+    if (guarded && incoming.representation.kind === 'optional') {
+        const present = convertTo(ctx, block, lineage, incoming, incoming.representation.payload, 'guard');
+        const widened = present === null ? null : convertTo(ctx, block, lineage, present, representation, 'merge-arm');
+        if (widened !== null)
+            return widened;
+    }
+    // The `??` mirror of the dead KEPT arms above, on the other side of the
+    // operator: `a ?? b` evaluates `b` only where `a` was nullish, and a kept
+    // operand whose carrier has no absent state at all was never nullish, so this
+    // arm never runs.
+    //
+    // node-server's `websocket.ts` module body is the shape:
+    // `globalThis.CloseEvent ?? class extends Event {...}`, where the program's
+    // own global read carries a bare `constructor-family`. The fallback class is
+    // a SECOND, unrelated program class, and the conversion asked for between the
+    // two is a nominal identity C++ has no way to state -- which is the right
+    // refusal for a value this arm never produces.
+    //
+    // Asked LAST, after the ordinary conversion has already been tried and
+    // failed, for the same reason `mergesAsTruthiness` above is: an arm that
+    // really does convert keeps converting, so this only ever turns a refusal
+    // into the dead value, never a working merge into one.
+    if (role === 'taken' && operation.family === 'computation' && operation.form === 'logical' && operation.operator === '??') {
+        const kept = operandOf(operation, 'left');
+        const keptCarrier = kept?.source.kind === 'result' ? ctx.plan.selected.get(kept.source.result) : undefined;
+        if (keptCarrier && carriesNoAbsence(keptCarrier)) {
+            const absent = { kind: 'undefined' };
+            const dead = { value: ctx.builder.constant(block, lineage, 'undefined', 'undefined', absent), representation: absent };
+            return convertOrDrift(ctx, block, lineage, operation.id, role, operand.ordinal, dead, representation);
+        }
+    }
+    throw blockedMergeArm(operation, role, incoming.representation, representation);
+};

package/dist/ir/lower-operands.d.ts

@@ -0,0 +1,272 @@
+import type { DeclarationId, FunctionId, IrValueId, OperationId, ResultRole, SemanticResultId } from '../identity/ids.js';
+import type { ConversionCensus } from '../conversion/nodes.js';
+import type { ConversionNode } from '../conversion/algebra.js';
+import type { ClassLayout } from '../projection/classes.js';
+import type { SlotCensus } from '../projection/slots.js';
+import type { RepresentationDeriver } from '../representation/derive.js';
+import { type CallableAbi, type RecordField, type Representation } from '../representation/model.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import { type SemanticOperand } from '../semantics/model/operands.js';
+import type { SemanticOperation } from '../semantics/model/operations.js';
+import type { IrBodyBuilder } from './build.js';
+import type { PendingShortCircuit } from './lower-short-circuit.js';
+import type { IrBlockId, IrOperand } from './model.js';
+/**
+ * Reading an operation's inputs and publishing its result.
+ *
+ * Every lowering step needs the same three answers -- where does this operand's
+ * value come from, which carrier does it arrive in, and under which identity is
+ * the result visible to the next step -- and they have to be the same answers
+ * everywhere. Two lowerings that each resolved a `parameter` operand their own
+ * way would disagree about the frame, which is not a defect any later layer can
+ * see: both would produce a well-formed body, and only one would be reading
+ * what the caller actually pushed.
+ */
+/**
+ * The whole-program answers a body cannot derive from its own operations.
+ *
+ * A class's members and each function's convention are projected once, before
+ * any body lowers, precisely so two bodies cannot disagree about them. A
+ * lowering that needed one and re-derived it locally would be that second
+ * opinion, so the projections are handed in rather than recomputed.
+ */
+export interface LoweringProgram {
+    readonly abis: ReadonlyMap<FunctionId, CallableAbi>;
+    readonly constructs: ReadonlyMap<FunctionId, CallableAbi>;
+    /** Checker-authenticated callable identity carried by semantic values. */
+    readonly callableOrigins: ReadonlyMap<SemanticResultId, FunctionId>;
+    readonly callableOwnPropertyWrites: ReadonlyMap<FunctionId, ReadonlySet<string>>;
+    readonly functionPrototypePropertyWrites: ReadonlySet<string>;
+    readonly classes: ReadonlyMap<DeclarationId, ClassLayout>;
+    /** Which carrier each operand must arrive in (`projection/slots.ts`). */
+    readonly slots: SlotCensus;
+    /** One conversion node per carrier pair (`conversion/nodes.ts`); every `convert` this lowering mints names one. */
+    readonly conversions: ConversionCensus;
+    /**
+     * Every slot `enter` could not fill: the operand's carrier differs from its
+     * slot and the census has no conversion for the pair. The operand went
+     * through unconverted, exactly as it did before slots existed, so the
+     * printer's own per-consumer path still renders (or refuses) it. Counted
+     * rather than refused while that path is still the printer's, so the
+     * refactor can see the pairs the census must learn before the printer's
+     * path is deleted; it becomes a refusal then.
+     */
+    readonly drift: SlotDrift[];
+    /**
+     * Every property read that produced a method VALUE -- a callable carrier
+     * stating a receiver -- keyed by the value it produced, with the object it
+     * was read from and the body it names. `enter` binds the two when such a
+     * value reaches a receiver-less slot (see `BindCallableOperation.detached`).
+     */
+    readonly methodValueReceivers: Map<IrValueId, {
+        readonly receiver: IrOperand;
+        readonly method: FunctionId;
+    }>;
+    /**
+     * The installed plugins' reactive-field statement, merged once for this
+     * lowering run exactly as `compiler.ts` merges it into
+     * `HostSpellings.reactive.fields` -- but gated on a cell actually being
+     * configured (empty when no plugin names one), so a `true` reading of
+     * `GetOperation.reactive`/`BindingReadOperation.reactive` always means a
+     * real cell exists, never merely that some plugin named the field without
+     * anything to render it into. See `GetOperation.reactive`.
+     */
+    readonly reactiveFields: ReadonlyMap<DeclarationId, ReadonlySet<string>>;
+    /**
+     * The FIELD declarations (not the class declarations `reactiveFields` is
+     * keyed by) that are reactive -- the reverse index a resolved-binding
+     * property read needs, since `PropertyOperation.resolvedBinding` names the
+     * field's own declaration directly, with no receiver/key pair left to walk
+     * through `classMemberOf`. Built once from `classes` and `reactiveFields`
+     * (`ir/lower.ts`) rather than per read, because a body cannot see the
+     * classes it does not declare.
+     */
+    readonly reactiveFieldDeclarations: ReadonlySet<DeclarationId>;
+}
+/**
+ * Whether a property read's receiver+key names a field an installed plugin
+ * declared a reactive cell.
+ *
+ * Answered once, here, at the point a `get` is about to be built
+ * (`lower-property.ts`, `lower-destructuring.ts`'s object-pattern step) --
+ * see `GetOperation.reactive` for why this belongs on the operation instead
+ * of being re-asked from a table the target does not publish until struct
+ * rendering. `classMemberOf` finds the field's DECLARING class along the
+ * inheritance chain, which is the class `reactiveFields` is keyed by (own
+ * fields only -- `component-classes.ts`'s `GeaReactiveFields`); a receiver
+ * that is not a class at all (a record, a dictionary, ...) answers `false`
+ * without a lookup, since the plugin's table only ever names class fields.
+ */
+export declare const reactiveFieldReadOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>, receiver: Representation, key: string, reactiveFields: ReadonlyMap<DeclarationId, ReadonlySet<string>>) => boolean;
+export interface SlotDrift {
+    /** The block that would execute this conversion, retained for control-flow pruning. */
+    readonly block: IrBlockId;
+    readonly operation: OperationId;
+    readonly role: string;
+    readonly ordinal: number;
+    readonly source: string;
+    readonly slot: string;
+    readonly reason: string;
+    /** The pair itself, so an instrument can ask the registry about it without re-deriving. */
+    readonly sourceRepresentation: Representation;
+    readonly slotRepresentation: Representation;
+}
+export interface LoweringContext {
+    readonly graph: SemanticGraph;
+    readonly plan: SealedRepresentationPlan;
+    readonly constantDeriver: RepresentationDeriver;
+    readonly program: LoweringProgram;
+    /** This owner's calling convention, or `null` for a region nobody calls. */
+    readonly abi: CallableAbi | null;
+    /**
+     * Why this body has no convention, when the ABI projection refused to give it
+     * one, and `null` otherwise.
+     *
+     * The projection already knows the answer -- it states three distinct failure
+     * modes by name (`projection/abi.ts`) -- and a body whose convention is absent
+     * then refuses with the *symptom*, "reads ABI position 0", which names neither
+     * the cause nor a thing to fix. Carrying the reason turns that report back
+     * into the one the projection already made. `null` covers two different
+     * situations that are both correctly silent here: a region nobody calls, which
+     * genuinely has no convention to refuse, and a function the projection never
+     * considered -- and inventing a reason for either would be this layer guessing
+     * at another's answer.
+     */
+    readonly abiRefusal: string | null;
+    readonly builder: IrBodyBuilder;
+    /** Every result this owner has lowered so far, keyed by the anchor result each defining operation registered. */
+    readonly values: Map<SemanticResultId, IrValueId>;
+    /** Optional-chain expressions whose merge is recorded but not yet closed (`lower-short-circuit.ts`). */
+    readonly shortCircuits: Map<SemanticResultId, PendingShortCircuit>;
+}
+export declare const describeOperand: (operand: SemanticOperand) => string;
+/** A published result's carrier plus the SSA id already minted for it -- the only legal source for an operand that names a prior result. */
+export declare const resolveResultValue: (ctx: LoweringContext, result: SemanticResultId, describe: string) => IrOperand;
+export declare const resolveRequiredOperand: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operand: SemanticOperand) => IrOperand;
+export declare const resolveOptionalOperand: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operand: SemanticOperand | undefined) => IrOperand | null;
+/**
+ * Whether an operand names a result whose carrier is `void`.
+ *
+ * `void` is the carrier for "there is no value": a call that returns it mints
+ * no SSA id at all (`build.ts`'s `mintOptionalResult`). So an operand naming
+ * one cannot be resolved, and a consumer that can legitimately have nothing --
+ * `return f()` in a `void` function, which C++ spells the same way -- has to
+ * ask before resolving rather than be refused for a value that was correctly
+ * never minted.
+ */
+export declare const namesVoidResult: (ctx: LoweringContext, operand: SemanticOperand | undefined) => boolean;
+export declare const namedOperand: (operation: SemanticOperation, role: string, ordinal?: number) => SemanticOperand;
+export declare const orderedOperandsOf: (operation: SemanticOperation, role: string) => readonly SemanticOperand[];
+/** The one non-provenance operand of an operation that has exactly one, when no operand is explicitly named `value`. */
+export declare const singleValueOperand: (operation: SemanticOperation) => SemanticOperand;
+export declare const requireLineage: (operation: SemanticOperation) => SemanticResultId;
+export declare const optionalResultRepresentation: (ctx: LoweringContext, operation: SemanticOperation, role: ResultRole) => Representation | null;
+export declare const requireResultRepresentation: (ctx: LoweringContext, operation: SemanticOperation, role: ResultRole, describe: string) => Representation;
+/** Registers the SSA id an operation's own IR lowering just produced under the same anchor `requireLineage` would cite for it. */
+/**
+ * A value in exactly the carrier a slot declares.
+ *
+ * The one place lowering converts. A consumer that needs an operand in its
+ * slot's carrier asks here rather than converting on its own, so every
+ * `convert` in the IR names a node of the conversion census -- the same node
+ * the certificate checks and the printer renders -- and no consumer decides a
+ * pair for itself. Identity is no conversion at all: the operand is handed
+ * back untouched, so a slot that already agrees costs nothing in the IR.
+ */
+export declare const convertTo: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operand: IrOperand, slot: Representation, via?: string) => IrOperand | null;
+/**
+ * Diagnostic only, under `GEA_SPECULATIVE_LOADS`: every classifier-gated load
+ * lowering minted, with the site that asked for it, so the loads no presence
+ * or membership proof stands behind can be counted by site.
+ */
+export declare const speculativeLoads: {
+    readonly lineage: SemanticResultId;
+    readonly via: string;
+    readonly node: ConversionNode;
+    readonly value: IrValueId;
+}[];
+/**
+ * An operand as its consumer's slot wants it: resolved, then converted into
+ * the slot's carrier when the census names one. A raw operand -- a key, a
+ * callee, a condition, an argument to a host member the printer spells from
+ * its own carrier -- is handed back as it arrived; so is an operand whose
+ * pair the census cannot convert, which is recorded in `program.drift` and
+ * left to the printer's own path (see `LoweringProgram.drift`).
+ */
+export declare const enter: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operation: SemanticOperation, operand: SemanticOperand, resolved: IrOperand) => IrOperand;
+/**
+ * A conversion the lowering itself decides on rather than one a slot asks
+ * for -- a receiver's narrowed view, a dead merge arm's absence, the thrown
+ * carrier, an omitted formal's `undefined`: the census node for the pair,
+ * named on the `convert` instruction like every slot-driven conversion. A
+ * pair the census cannot convert is recorded as drift under the given role
+ * and STILL minted, because the consumer needs the value in `target` (a phi
+ * arm, a `throw`) and the printer's own chain is what answers such a pair
+ * until the census does. Every `convert` a lowering mints goes through here
+ * or `convertTo`: a hand-built use id named a conversion no census had
+ * counted, which is how a pair certified under one authority and refused
+ * under another.
+ */
+export declare const convertOrDrift: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operation: OperationId, role: string, ordinal: number, operand: IrOperand, target: Representation, via?: string) => IrOperand;
+/**
+ * A binding read in the carrier the plan selected for it, which is the cell's
+ * own carrier or a narrowing of it: `x` read as `string` out of a cell placed
+ * `optional(string)` behind the guard that proved it present. The read itself
+ * yields the cell's carrier and the narrowing is a `convert` the conversion
+ * census names, exactly as a store into the cell converts the other way. A
+ * pair the census cannot convert is recorded as drift and the read is minted
+ * in the selected carrier for the printer's own path to narrow.
+ */
+export declare const narrowedBindingRead: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operation: SemanticOperation, declaration: DeclarationId, representation: Representation) => IrValueId;
+/** `resolveRequiredOperand` followed by `enter`, for the consumers whose operand is a value in a slot. */
+export declare const enterRequiredOperand: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operation: SemanticOperation, operand: SemanticOperand) => IrOperand;
+export declare const registerResult: (ctx: LoweringContext, operation: SemanticOperation, value: IrValueId | null) => void;
+export { abiOfCallee, constructAbiOfCallee } from '../projection/callee.js';
+/**
+ * The named fields a record carrier lays out.
+ *
+ * A record type written inline (`function Row(props: {label: string})`) carries
+ * its fields directly; one written as a named interface is carried *by name*,
+ * because that is what makes a self-referential type finite -- so its layout
+ * lives in the sealed structural table and is read back by deriving the shape
+ * the reference names. Both are the same physical object; only the carrier
+ * differs, and a lowering that handled just the first would refuse an ordinary
+ * `interface RowProps` for no reason the program could act on.
+ */
+export declare const recordLayoutOf: (ctx: LoweringContext, props: Representation) => readonly RecordField[] | null;
+/**
+ * A call's arguments with its variadic tail packed.
+ *
+ * A rest parameter is one slot holding an array, not a run of slots, so the
+ * packing belongs where a call's operands are read rather than in each caller:
+ * the convention states where the tail begins and which array carrier holds it,
+ * and a convention that says a rest slot is not an array is refused rather than
+ * packed into something that cannot hold it.
+ */
+/**
+ * A call's arguments with its variadic tail packed.
+ *
+ * A rest parameter is one slot holding an array, not a run of slots, so the
+ * packing belongs where a call's operands are read rather than in each caller:
+ * the convention states where the tail begins and which array carrier holds it,
+ * and a convention that says a rest slot is not an array is refused rather than
+ * packed into something that cannot hold it.
+ */
+/**
+ * One physical argument, and whether it is one value or a whole range.
+ *
+ * A `spread` slot carries the ENTIRE source array of a `f(a, ...xs)` call
+ * (`producers/spread-arguments.ts` publishes it under its own operand role),
+ * so it contributes however many elements that array holds -- which is a
+ * runtime count. That is representable in exactly one place: inside the rest
+ * array `packRestArguments` builds, as the same `spread` element an array
+ * literal's own admitted spread already uses. A `spread` slot anywhere a
+ * FIXED count is required has no rendering at all, and is refused.
+ */
+export type ArgumentSlot = {
+    readonly kind: 'value' | 'spread';
+    readonly value: IrOperand;
+    readonly from?: number;
+};
+export declare const packRestArguments: (ctx: LoweringContext, block: IrBlockId, lineage: SemanticResultId, operation: OperationId, abi: CallableAbi | null, passed: readonly ArgumentSlot[]) => readonly IrOperand[];