@geastack/compiler 1.0.15

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

@@ -0,0 +1,904 @@
+import { nodeOfOperation, operationOfResult, withoutSpecialization } from '../../identity/ids.js';
+import { recordLayoutPolicyOf } from '../../projection/fields.js';
+import { noInstantiationFacts } from '../../ir/instantiation.js';
+import { observesEveryCallableIdentity } from '../../ir/callable-identity-demand.js';
+import { hostCallName, hostMemberOf, statedHostIntrinsicLength } from './host/host-members.js';
+import { representationKey } from '../../representation/model.js';
+import { cppBodyName, cppConstructName, cppNarrowedIntegerType, cppStringLiteral, cppTypeOf, cppUndefinedIn } from './types.js';
+import { hostBuiltinFunctionIdentityText, hostClassValueText, hostFunctionValueText, hostJsonMemberValueText, hostMemberValueText } from './host/emit-host-value.js';
+import { createConversionNodes } from '../../conversion/nodes.js';
+import { createCppConversionRegistry } from './conversions.js';
+export const createCppEmitBlockedError = (kind, reason) => Object.assign(new Error(`cpp emission refuses to lower "${kind}": ${reason}`), { cppEmitBlocked: true, kind });
+export const isCppEmitBlockedError = (error) => error instanceof Error && error.cppEmitBlocked === true;
+/**
+ * The standard `Symbol.<name>` identity encoded by a `sym(declaration)`
+ * property key, read straight off the key TEXT.
+ *
+ * A record field's key arrives as text and never as an operand
+ * (`derive.ts`'s `recordFieldKeyOf` mints it), so a reader that only has a
+ * layout cannot go through `wellKnownSymbolMemberOf` below. Both spellings of
+ * the question resolve against the one census the frontend published
+ * (`host-protocols.ts`'s `wellKnownSymbolDeclarationsOf`), which is what keeps
+ * "which declaration is `Symbol.match`" a single answer.
+ */
+export const wellKnownSymbolMemberOfKey = (wellKnownSymbols, key) => {
+    for (const [declaration, member] of wellKnownSymbols) {
+        if (key === `sym(${declaration})`)
+            return member;
+    }
+    return null;
+};
+/** The standard `Symbol.<name>` identity encoded by a static `sym(declaration)` property key. */
+export const wellKnownSymbolMemberOf = (ctx, operand) => {
+    const key = ctx.staticKeyTexts.get(operand.value);
+    if (key === undefined)
+        return null;
+    return wellKnownSymbolMemberOfKey(ctx.wellKnownSymbols, key);
+};
+/** The index a body with no capture information at all reads as: every owner closes over nothing. */
+export const emptyCaptureIndex = {
+    of: () => ({ kind: 'none' }),
+    isBoxed: () => false,
+    isCaptured: () => false,
+    requiresEarlyBox: () => false,
+    readsReceiver: () => false
+};
+/**
+ * The ABI a capturing body itself reads through, as opposed to the one its
+ * callers push.
+ *
+ * A caller of a callable carrier -- `abiOfCallee`, `emitCall`'s own receiver
+ * check, the thunk's own external signature (`translation-unit.ts`'s
+ * `thunkOf`) -- always consults the *real*, unmodified ABI: an arrow still
+ * takes no receiver argument at its call sites, full stop. Only the body's
+ * own frame needs to know that a receiver it declares no ABI slot for is
+ * nonetheless available, because a nested arrow's `this` captured it from the
+ * enclosing method. Overriding `.receiver` here, in one place, is what lets
+ * `emitReceiver` read it exactly as it already reads an ordinary method's own
+ * `this` -- the capture only moves where the value comes from, not how the
+ * body asks for it.
+ */
+export const effectiveAbiOf = (abi, admission) => abi && admission.kind === 'ok' && admission.layout.receiver ? { ...abi, receiver: admission.layout.receiver } : abi;
+/** Every deferred direct callee this body's `call` operations resolved to, straight off `CallOperation.target` -- see `EmitContext.directCallees`'s doc. */
+export const directCalleesOf = (body, abiOfCallable) => {
+    const directCallees = new Map();
+    const directCalleeAbis = new Map();
+    for (const block of body.blocks.values()) {
+        for (const operation of block.operations) {
+            if (operation.kind !== 'call' || operation.target?.kind !== 'direct')
+                continue;
+            directCallees.set(operation.callee.value, cppBodyName(operation.target.functionId));
+            const abi = abiOfCallable(operation.target.functionId);
+            if (abi !== null)
+                directCalleeAbis.set(operation.callee.value, abi);
+        }
+    }
+    return { directCallees, directCalleeAbis };
+};
+export const createEmitContext = (abi, owner, placements, classes, hosts, deriver, bodyFacts, wellKnownSymbols = new Map(), captures = emptyCaptureIndex, symbolKeys = new Map(), templateObjects = new Map(), directCallableBindings = new Map(), virtualDispatch = new Map(), narrowedFormals = new Set(), repeatedConstructors = new Map(), dyingArguments = new Set(), instantiation = noInstantiationFacts, abiOfCallable = () => null, hostMethodAliases = new Map(), callableMemberCandidates = new Map(), borrowableMemberBodies = new Set(), stableBorrowEntries = new Map(), printerDrift = [], 
+// A context built without the program's census (the value-contract
+// checks) gets one over the same tables with nothing pre-minted: the
+// registry answers every pair the eager graph would have, one node later.
+conversions = null, nativeSelections = undefined, callableIdentityDemand = observesEveryCallableIdentity, nativeIntegrityRestricted = true, fixedFieldStateConstant = false) => {
+    const admission = captures.of(owner);
+    const layouts = recordLayoutPolicyOf(deriver, classes);
+    // The thirty-three `EmitBodyPrepassFacts` collections: minted once, here, and
+    // handed to `ctx` (read-only) and to the caller's `prepass` (mutable) as
+    // the SAME instances -- see that type's own doc for why a fact this late
+    // still needs a mutable handle at all.
+    const hoistedResults = new Set();
+    const sharedStringLayouts = new Map();
+    const reusedStringLengths = new Map();
+    const loopInvariantValues = new Set();
+    const numericCalls = new Map();
+    const numericCallOnly = new Set();
+    const integerValues = new Set();
+    const integerBindings = new Set();
+    const typeQueryValues = new Set();
+    const typeQueryBindings = new Set();
+    const typeQueryComparisons = new Map();
+    const remainderForms = new Map();
+    const deadValues = new Set();
+    const unreadValues = new Set();
+    const booleanConstants = new Map();
+    const localIterators = new Set();
+    const callArgumentOnly = new Set();
+    const prototypeMethodReads = new Map();
+    const lazyCalleeReads = new Set();
+    const directCallReceivers = new Map();
+    const virtualCallees = new Map();
+    const unionMethodReads = new Map();
+    const unionMemberTypeofReads = new Map();
+    const reactiveOrigins = new Map();
+    const reactiveBindingOrigins = new Map();
+    const reactiveFieldReads = new Map();
+    const formalCells = new Map();
+    const narrowedFormalValues = new Set();
+    const directBindingSinks = new Map();
+    const forwardedBindings = new Map();
+    const capacityHints = new Map();
+    const fillLoops = new Map();
+    const denseArrays = [];
+    const denseAccesses = new Map();
+    const denseGroups = new Map();
+    const denseLengths = new Map();
+    const deferrable = new Set();
+    const ctx = {
+        abi: effectiveAbiOf(abi, admission),
+        abiOfCallable,
+        owner,
+        placements,
+        classes,
+        captures,
+        deriver,
+        layouts,
+        ...(nativeSelections === undefined ? {} : { nativeSelectionHelpers: nativeSelections }),
+        conversions: conversions ?? createConversionNodes({ registry: createCppConversionRegistry(layouts), nodes: new Map() }),
+        valueNames: new Map(),
+        ownedValues: new Set(),
+        ownedDyingValues: bodyFacts.ownedDyingValues,
+        consumingFormalConversions: bodyFacts.consumingFormalConversions,
+        bindingWriteCounts: bodyFacts.bindingWriteCounts,
+        formalCells,
+        constantTexts: new Map(),
+        staticKeyTexts: bodyFacts.staticKeyTexts,
+        hosts,
+        wellKnownSymbols,
+        reactiveFieldReads,
+        thunkValues: bodyFacts.thunkValues,
+        directCallees: bodyFacts.directCallees,
+        directCalleeAbis: bodyFacts.directCalleeAbis,
+        directCallReceivers,
+        virtualCallees,
+        virtualCalleesUsed: new Set(),
+        unionMethodReads,
+        unionMethodReadsUsed: new Set(),
+        unionMemberTypeofReads,
+        protocolNextResults: new Map(),
+        dynamicIteratorSteps: new Map(),
+        dynamicIteratorDoneStates: new Map(),
+        stringMetadataNames: new Map(),
+        receiverValues: bodyFacts.receiverValues,
+        constructorOf: bodyFacts.constructorOf,
+        generatorBody: bodyFacts.generatorBody,
+        virtualDispatch,
+        directCallableBindings,
+        callableMemberCandidates,
+        borrowableMemberBodies,
+        stableBorrowEntries,
+        stableBorrowActuals: bodyFacts.stableBorrowActuals,
+        repeatedConstructors,
+        dyingArguments,
+        hostMethodAliases,
+        instantiation,
+        callableIdentityDemand,
+        nativeIntegrityRestricted,
+        fixedFieldStateConstant,
+        functionSourceReads: bodyFacts.functionSourceReads,
+        functionSourceSnapshotNames: bodyFacts.functionSourceSnapshotNames,
+        callCallees: bodyFacts.callCallees,
+        calleeOnlyValues: bodyFacts.calleeOnlyValues,
+        conversionSources: bodyFacts.conversionSources,
+        recordFieldSources: bodyFacts.recordFieldSources,
+        reactiveOrigins,
+        reactiveBindingOrigins,
+        printerDrift,
+        hostMemberReads: bodyFacts.hostMemberReads,
+        hostClassReads: bodyFacts.hostClassReads,
+        classObjectReads: bodyFacts.classObjectReads,
+        hostFunctionReads: bodyFacts.hostFunctionReads,
+        hostNamespaceReads: bodyFacts.hostNamespaceReads,
+        hostNamespaceValues: bodyFacts.hostNamespaceValues,
+        hoistedResults,
+        sharedStringLayouts,
+        prototypeMethodReads,
+        lazyCalleeReads,
+        bindingNames: new Map(),
+        deadValues,
+        unreadValues,
+        booleanConstants,
+        localIterators,
+        deferrable,
+        reusedStringLengths,
+        callArgumentOnly,
+        classTableRoots: bodyFacts.classTableRoots,
+        pendingClassTableLines: new Map(),
+        deferredTexts: new Map(),
+        pendingPacks: new Map(),
+        capacityHints,
+        fillLoops,
+        narrowedFormals,
+        narrowedFormalValues,
+        numericCalls,
+        numericCallOnly,
+        integerValues,
+        integerBindings,
+        typeQueryValues,
+        typeQueryBindings,
+        typeQueryComparisons,
+        loopInvariantValues,
+        remainderForms,
+        denseArrays,
+        denseAccesses,
+        denseLengths,
+        denseIndices: new Map(),
+        denseGroups,
+        computeOrigins: bodyFacts.computeOrigins,
+        propertyReadOrigins: bodyFacts.propertyReadOrigins,
+        bindingReadDeclarations: bodyFacts.bindingReadDeclarations,
+        valueCellReads: bodyFacts.valueCellReads,
+        declaredBindings: new Set(),
+        directBindingSinks,
+        forwardedBindings,
+        declarations: [],
+        symbolKeys,
+        templateObjects,
+        nextValueOrdinal: 0,
+        nextBindingOrdinal: 0
+    };
+    return {
+        ctx,
+        prepass: {
+            hoistedResults,
+            sharedStringLayouts,
+            reusedStringLengths,
+            loopInvariantValues,
+            numericCalls,
+            numericCallOnly,
+            integerValues,
+            integerBindings,
+            typeQueryValues,
+            typeQueryBindings,
+            typeQueryComparisons,
+            remainderForms,
+            deadValues,
+            unreadValues,
+            booleanConstants,
+            localIterators,
+            callArgumentOnly,
+            prototypeMethodReads,
+            lazyCalleeReads,
+            directCallReceivers,
+            virtualCallees,
+            unionMethodReads,
+            unionMemberTypeofReads,
+            reactiveOrigins,
+            reactiveBindingOrigins,
+            reactiveFieldReads,
+            formalCells,
+            narrowedFormalValues,
+            directBindingSinks,
+            forwardedBindings,
+            capacityHints,
+            fillLoops,
+            denseArrays,
+            denseAccesses,
+            denseGroups,
+            denseLengths,
+            deferrable
+        }
+    };
+};
+/**
+ * Mints this result's name and records the declaration it needs.
+ *
+ * Throws on a second definition: SSA form makes that an internal-consistency
+ * bug, not a missing feature. `spelling` overrides the type only where the
+ * carrier a value is *read* as differs from the one its result declares -- a
+ * receiver read through the ABI's declared receiver slot, for instance.
+ */
+/**
+ * `long long` where the integer census narrowed this value, and the carrier's
+ * own spelling everywhere else.
+ *
+ * An explicit spelling always wins: a caller that named the type knows
+ * something this does not.
+ */
+export const storageTypeOf = (ctx, value, representation) => ctx.typeQueryValues.has(value) ? 'gea::Value::Tag' : ctx.integerValues.has(value) ? cppNarrowedIntegerType : cppTypeOf(representation);
+/**
+ * Whether a value's rendered text is a `long long`, from every storage that
+ * can make it one: the value census (`integerValues`), the cell a read names
+ * (`integerBindings`, through `bindingReadDeclarations`), or the narrowed
+ * formal a parameter reads. `storageTypeOf` answers only the first, which is
+ * right for a value's OWN declaration -- a read of an integer cell is spelled
+ * as the cell's name and declares nothing -- and wrong for a consumer choosing
+ * an overload by the text's type: `examples/apps/weather` indexed its arrays
+ * with `long long` loop counters through `elementAt(double)`, converting the
+ * index to a double and back on every read, 47 times.
+ */
+export const isIntegerStorageValue = (ctx, value) => {
+    if (ctx.integerValues.has(value) || ctx.narrowedFormalValues.has(value))
+        return true;
+    const declaration = ctx.bindingReadDeclarations.get(value);
+    return declaration !== undefined && ctx.integerBindings.has(declaration) && !ctx.captures.isBoxed(declaration);
+};
+/**
+ * One capture slot's initializer, cast to the field the environment declares.
+ *
+ * The struct's field is `cppTypeOf(slot.representation)` -- the CARRIER -- and
+ * a cell the integer census narrowed is held in a `long long`. A braced init
+ * list forbids that conversion ([dcl.init.list] admits no narrowing), so the
+ * pair that reads fine everywhere else is a hard error here, exactly as it is
+ * for an array literal's elements (`emit-arrays.ts`'s `packElementText`).
+ */
+export const captureFieldText = (ctx, declaration, representation, text) => ctx.integerBindings.has(declaration) && cppTypeOf(representation) !== cppNarrowedIntegerType
+    ? `static_cast<${cppTypeOf(representation)}>(${text})`
+    : text;
+export const defineValue = (ctx, result, spelling) => {
+    if (ctx.valueNames.has(result.id))
+        throw new Error(`ir value ${result.id} is defined twice in one body, which SSA form forbids`);
+    if (spelling === undefined && result.representation.kind === 'void') {
+        throw createCppEmitBlockedError(`physical-cpp-type:${representationKey(result.representation)}`, `tries to define storage for void result ${result.id}, which has no value carrier`);
+    }
+    const name = `v${ctx.nextValueOrdinal}`;
+    ctx.nextValueOrdinal += 1;
+    ctx.valueNames.set(result.id, name);
+    ctx.declarations.push({ name, type: spelling ?? storageTypeOf(ctx, result.id, result.representation) });
+    if (spelling === undefined)
+        ctx.ownedValues.add(result.id);
+    return name;
+};
+/**
+ * Mints this result's name without hoisting a declaration for it.
+ *
+ * For a value some other C++ construct already declares -- the catch clause's
+ * own parameter is the one case today (`CatchBindingOperation`). The region's
+ * own `catch (const gea::Value& vN)` text IS this value's declaration;
+ * hoisting a second one under the same name would redeclare it.
+ */
+export const defineValueBoundElsewhere = (ctx, result) => {
+    if (ctx.valueNames.has(result.id))
+        throw new Error(`ir value ${result.id} is defined twice in one body, which SSA form forbids`);
+    const name = `v${ctx.nextValueOrdinal}`;
+    ctx.nextValueOrdinal += 1;
+    ctx.valueNames.set(result.id, name);
+    return name;
+};
+/**
+ * Publishes this result under storage that already exists, rather than under a
+ * fresh temporary of its own.
+ *
+ * The one use is a read of a HOST OBJECT (`native-handle`) out of its cell. In
+ * the source language that read is not a copy: `const ctx = Display.ctx` binds
+ * a reference to one object, and `ctx.fillStyle = c` then `ctx.fillText(...)`
+ * are two operations on that same object. Minting a temporary and assigning the
+ * cell into it makes each read a fresh C++ VALUE, and every host type that
+ * carries state behind its handle -- `CanvasRenderingContext2D` holds
+ * `batchDepth_`, `presentRecording_`, `fillStyle_`, `fontSizePx_` and the
+ * present-command buffer -- then loses whatever the previous statement set on
+ * it, silently and with no diagnostic. The cell IS the object, so the read
+ * names the cell.
+ */
+export const defineValueAlias = (ctx, result, storage) => {
+    if (ctx.valueNames.has(result.id))
+        throw new Error(`ir value ${result.id} is defined twice in one body, which SSA form forbids`);
+    ctx.valueNames.set(result.id, storage);
+};
+/** Records a local binding cell's declaration, for the same reason values are hoisted. */
+export const declareCell = (ctx, name, type) => {
+    ctx.declarations.push({ name, type });
+};
+/**
+ * The expression a deferred value stands for, or `null` when it has storage of
+ * its own.
+ *
+ * A withheld array literal materializes here rather than at the point it was
+ * withheld: `gea::arrayOf` builds the same Array exotic object the pushed form
+ * did, as one expression, so a consumer that genuinely wants the object gets
+ * it and only the bulk-insert renderer -- which drains it immediately -- gets
+ * to skip building it at all.
+ */
+const deferredText = (ctx, value) => {
+    const text = ctx.deferredTexts.get(value);
+    if (text !== undefined)
+        return text;
+    const pack = ctx.pendingPacks.get(value);
+    if (pack === undefined)
+        return null;
+    return `gea::arrayOf<${pack.elementType}>({${pack.elements.join(', ')}})`;
+};
+/**
+ * Whether a value renders as the expression that computes it rather than as a
+ * cell of its own -- `emitOperation`'s withholding, or a whole withheld array
+ * literal. Such a value is a prvalue at its use: it has no storage anyone could
+ * move FROM, and `std::move` around it is either redundant (gcc's
+ * -Wredundant-move / -Wpessimizing-move, both errors under the boards' -Werror)
+ * or, when the withheld expression happens to name a field, a move out of that
+ * field's storage.
+ */
+export const isDeferredValue = (ctx, value) => deferredText(ctx, value) !== null;
+/** The one name a value was minted under. Reading an undefined value is a dominance bug in the body, not a rendering choice. */
+export const nameOfValue = (ctx, value) => {
+    const deferred = deferredText(ctx, value);
+    if (deferred !== null)
+        return deferred;
+    const name = ctx.valueNames.get(value);
+    if (name === undefined) {
+        const state = [
+            ctx.deadValues.has(value) ? 'dead' : null,
+            ctx.deferrable.has(value) ? 'deferrable' : null,
+            ctx.unreadValues.has(value) ? 'unread' : null
+        ].filter((fact) => fact !== null);
+        throw new Error(`ir value ${value} is read before it is defined in body ${ctx.owner}${state.length === 0 ? '' : ` (${state.join(', ')})`}`);
+    }
+    return name;
+};
+/**
+ * A host method is not a value.
+ *
+ * `storage.getItem` names no C++ symbol on its own -- the host states a
+ * spelling for the *call*, `gea::host::storage::getItem(k)`, and there
+ * is nothing to bind the bare access to. So the access publishes no name, and
+ * any use of it other than as a callee is refused here, by name, rather than
+ * crashing on a value that was never minted.
+ */
+export const operandText = (ctx, operand) => {
+    const host = ctx.hostMemberReads.get(operand.value);
+    if (host) {
+        // Unless the read asks for no call at all. A builtin whose overloads name
+        // no single convention is carried as its identity half, and the function
+        // OBJECT is a thing this backend can build even where the frame is not:
+        // `Array.from.name` reads a fact ECMA-262 states, and the spec's own
+        // `length` for it is stated beside the other host facts. Where it is not
+        // stated there is nothing to fall back to -- a value read has no census
+        // arity behind it -- so that refuses below with the rest.
+        if (operand.representation.kind === 'callable-identity') {
+            const length = statedHostIntrinsicLength(host.protocol, host.member);
+            if (length !== null)
+                return hostBuiltinFunctionIdentityText(host.protocol, host.member, length);
+            throw createCppEmitBlockedError(`host-invocation:${host.protocol}.${host.member}:value`, `"${host.protocol}.${host.member}" is read as a function object with no calling convention, and no host row states its own length`);
+        }
+        // Otherwise the read IS a function object, and the host's own call
+        // template is what it calls -- rendered into a captureless thunk over the
+        // slot's convention, the same closing a free host function's read already
+        // gets. `hostMemberValueText` states which template shapes fill from bare
+        // formals and which cannot.
+        // `JSON` is dispatched by protocol name BEFORE the template fill, exactly
+        // as `hostCallText` dispatches it before the same fill for a real call:
+        // its two rows carry a placeholder `emit`, not a template, because their
+        // C++ is generated per call site. Filling from that placeholder would
+        // splice the placeholder's own comment text in where the call belongs.
+        if (host.protocol === 'JSON') {
+            const json = hostJsonMemberValueText(host.member, operand.representation);
+            if (json !== null)
+                return json;
+            throw createCppEmitBlockedError(`host-invocation:JSON.${host.member}:value`, `"JSON.${host.member}" read as a value renders a thunk only over a carrier "gea_runtime.h" declares its own ` +
+                `gea_json_read/gea_json_write for; this slot carries "${representationKey(operand.representation)}", whose overload is ` +
+                'generated per CALL site and so does not exist for a read');
+        }
+        const row = hostMemberOf(ctx.hosts.members, host.protocol, host.member);
+        if (row) {
+            const thunk = hostMemberValueText(operand.representation, row, recordLayoutPolicyOf(ctx.deriver, ctx.classes));
+            if (thunk !== null)
+                return thunk;
+        }
+        throw createCppEmitBlockedError(`host-invocation:${host.protocol}.${host.member}:value`, `"${host.protocol}.${host.member}" is a host method used as a value carried as "${representationKey(operand.representation)}", and the ` +
+            'captureless thunk over its own call template that renders one does not apply to that shape; hostMemberValueText ' +
+            '(host/emit-host-value.ts) states the shapes it declines');
+    }
+    const hostClass = ctx.hostClassReads.get(operand.value);
+    if (hostClass !== undefined) {
+        const called = hostClassValueText(operand.representation, hostClass.linkageName);
+        if (called !== null)
+            return called;
+        throw createCppEmitBlockedError(`host-invocation:${hostClass.linkageName}:value`, `"${hostClass.linkageName}" is a host class used as a value; the host states spellings for constructing it and for its own class ` +
+            `members, and none for the class itself`);
+    }
+    const classObject = ctx.classObjectReads.get(operand.value);
+    if (classObject !== undefined) {
+        throw createCppEmitBlockedError('native-boundary:uncensused-class-object', `"${classObject}" is a program class this compilation introduces no constructor object for -- a generic the program never instantiates ` +
+            'is not censused -- so its name can be tested against and constructed through, and there is no object of it to read, store or pass');
+    }
+    const hostNamespace = ctx.hostNamespaceReads.get(operand.value);
+    if (hostNamespace !== undefined) {
+        throw createCppEmitBlockedError(`host-invocation:${hostNamespace}:value`, `"${hostNamespace}" is a host namespace used as a value; it is a path to the host's spellings, and no object of that name ` +
+            'exists at run time to be read, stored or passed');
+    }
+    const hostFunction = ctx.hostFunctionReads.get(operand.value);
+    if (hostFunction !== undefined) {
+        const wrapped = hostFunctionValueText(operand.representation, hostFunction);
+        if (wrapped !== null)
+            return wrapped;
+        throw createCppEmitBlockedError(`host-invocation:${hostCallName(hostFunction)}:value`, `"${hostCallName(hostFunction)}" is a host function used as a value, and the captureless thunk over its own ABI that renders one does not apply here; hostFunctionValueText (host/emit-host-value.ts) states the two cases it declines`);
+    }
+    const prototypeMethod = ctx.prototypeMethodReads.get(operand.value);
+    if (prototypeMethod) {
+        throw createCppEmitBlockedError(`property-access:${prototypeMethod.receiverKind}:get:false:value`, `"${prototypeMethod.member}" is a String/Number/Array/Promise.prototype method used as a value; this backend fuses it with its call and never materializes it as a first-class function`);
+    }
+    return nameOfValue(ctx, operand.value);
+};
+/**
+ * The receiver a deferred prototype-method call renders on.
+ *
+ * The mirror of `hostMemberReceiverText` for the other deferral family, and
+ * here for the same reason: the access that recorded the read produced no C++,
+ * so it had no occasion to print anything, and the record it leaves behind
+ * names the operand rather than a spelling of it.
+ */
+export const prototypeMethodReceiverText = (ctx, receiver) => {
+    if (receiver.kind === 'none')
+        return '';
+    const text = operandText(ctx, receiver.operand);
+    return receiver.kind === 'match-elements' ? `gea::runtime::regex::matchElements(${text})` : text;
+};
+/** One dense window's element pointer: the array's own storage, named once at the preheader. */
+export const cppDensePointerName = (ordinal) => `gea_dense_${ordinal}`;
+/** The row a dense window indexes, when the array is itself an element of another: `grid[i]`, taken once at the preheader. */
+export const cppDenseRowName = (ordinal) => `gea_dense_row_${ordinal}`;
+/** One loop's dense-window condition. Loop-invariant by construction, which is what lets the backend version the loop on it. */
+export const cppDenseFlagName = (group) => `gea_dense_ok_${group}`;
+/** A wrapped window's own length, read once at the preheader -- see `DenseLoopPlan.lengths`. */
+export const cppDenseLengthName = (ordinal) => `gea_dense_len_${ordinal}`;
+/** The reciprocal of that length, built once at the preheader rather than re-checked by `gea::preparedDivisor` on every turn. */
+export const cppDenseDivisorName = (ordinal) => `gea_dense_div_${ordinal}`;
+/** The formal this body declares for one ABI position. `translation-unit.ts`'s `formalsOf` spells the same names. */
+export const cppFormalName = (ordinal) => `gea_arg_${ordinal}`;
+/** The formal a body declares for the receiver. `translation-unit.ts`'s `formalsOf` spells the same name. */
+export const cppReceiverName = 'gea_this';
+/** The thunk that adapts one function body to the environment-passing invoke pointer a callable carrier holds. */
+export const cppThunkName = (functionId) => `${cppBodyName(functionId)}_thunk`;
+/** The thunk that adapts one class's construct function to the environment-passing construct pointer a constructor carrier holds. */
+export const cppConstructThunkName = (declaration) => `${cppConstructName(declaration)}_thunk`;
+/**
+ * The same pointer for a pre-`class` JavaScript constructor FUNCTION, whose
+ * construction has no separate construct function to adapt: one body serves
+ * both entry points, so the thunk itself is where the instance is allocated
+ * (`translation-unit.ts`'s `constructThunkOf`). Keyed by the function rather
+ * than by a declaration, because that is the identity the carrier's allocation
+ * site names (`emit-callable.ts`'s `emitAllocateCallable`).
+ */
+export const cppConstructedThunkName = (functionId) => `${cppBodyName(functionId)}_construct_thunk`;
+/**
+ * The environment struct one capturing function's closure allocates.
+ *
+ * One struct per capturing function, not one shared layout: two closures
+ * capture different cells in general, and a shared struct would need every
+ * field every closure ever captures, most of them unused in most instances.
+ */
+export const cppEnvironmentStructName = (functionId) => `${cppBodyName(functionId)}_env`;
+/** One captured cell's field inside its function's environment struct, in capture order. `translation-unit.ts`'s thunk unpacking spells the same name. */
+export const cppCaptureFieldName = (index) => `c${index}`;
+/** The captured-receiver's own field, kept apart from `cppCaptureFieldName` because it has no capture-order index -- there is at most one per environment. */
+export const cppCaptureReceiverFieldName = 'crecv';
+/** The thunk's own `void*` formal, named only when a body actually has an environment to unpack. */
+export const cppEnvironmentParamName = 'gea_env';
+/** The local the thunk casts `cppEnvironmentParamName` to, so the body call and the field reads inside a captured body share one pointer. */
+export const cppEnvironmentLocalName = 'gea_e';
+/** The thunk's own one-pointer stack storage, which a captured state small enough to travel inside the carrier's pointer is copied back into. */
+export const cppEnvironmentSlotName = 'gea_env_slot';
+/**
+ * The environment actual a capturing accessor's body is called with, read in
+ * place out of the object that carries it.
+ *
+ * An accessor is reached by NAME off the shape, so unlike a closure it has no
+ * carrier to hold its captures: the object carries them
+ * (`cppRecordAccessorEnvironmentName`, packed at the allocation). Reading it
+ * back is an EXPRESSION -- `gea::storedEnvironment` casts the member in place
+ * rather than copying an inline environment into a stack slot the way a
+ * thunk's `unpackEnvironment` must -- which is what lets every accessor call
+ * site, including the ones that render a whole call as one expression
+ * (`emit-iterator.ts`), pass it without first emitting statements.
+ */
+export const storedEnvironmentText = (body, member) => `gea::storedEnvironment<${cppEnvironmentStructName(body)}>(${member})`;
+/**
+ * The payload needed to read a property or invoke a nullable carrier.
+ * Optional chaining guards this access, but a TypeScript non-null assertion
+ * erases and proves nothing at runtime. Check presence before unwrapping so
+ * `a!.b` and `(a?.b)!.c` throw on absence instead of dereferencing a default
+ * payload. Name the payload once even when a recipe uses it twice.
+ */
+export const unwrapPresentValue = (ctx, lines, operand) => {
+    if (operand.representation.kind !== 'optional')
+        return operand;
+    const value = `${operand.value}:present`;
+    // The narrowed view's own deferral is already stated by `hostMemberReadsOf`,
+    // which names the `<value>:present` twin of every read it claims -- the same
+    // unconditional statement `hostClassReadsOf` makes just below, and for the
+    // same reason: if a value IS a deferred host member then so is the value
+    // proven present, and nothing reads the twin unless a narrowing minted one.
+    if (ctx.hostMemberReads.has(operand.value))
+        return { value, representation: operand.representation.payload };
+    // The narrowed view's own identity is already stated by
+    // `emit-bindings.ts`'s `hostClassReadsOf`, so this only has to hand it back.
+    if (ctx.hostClassReads.has(value))
+        return { value, representation: operand.representation.payload };
+    if (!ctx.valueNames.has(value)) {
+        const name = `v${ctx.nextValueOrdinal}`;
+        ctx.nextValueOrdinal += 1;
+        ctx.valueNames.set(value, name);
+        ctx.declarations.push({ name, type: cppTypeOf(operand.representation.payload) });
+        lines.push(`if (!(${operandText(ctx, operand)}).has_value()) gea::host::throwGetPropertyOfNullish<void>();`);
+        lines.push(`${name} = *${operandText(ctx, operand)};`);
+    }
+    return { value, representation: operand.representation.payload };
+};
+/**
+ * The arguments a call actually passes, padded out to the frame the callee
+ * declares.
+ *
+ * A JavaScript call may pass fewer arguments than the function has parameters,
+ * and the parameters it skipped are `undefined` -- so a parameter that may be
+ * omitted is carried as an `optional`, and the frame still has a slot for it.
+ * C++ has no such rule: `construct()` against a
+ * `ConstructorObject<T(Optional<double>, Optional<double>, ...)>` is "too few
+ * arguments", full stop. `new Quaternion()` against `constructor(w = 1, x = 0,
+ * y = 0, z = 0)` is exactly that call.
+ *
+ * So the absence is passed, not assumed. Only a slot whose own carrier states
+ * the absence `undefined` can hold an omitted argument; a slot that cannot is
+ * refused by name rather than default-constructed into whatever its carrier
+ * happens to allow -- an `optional` tagged `null` would answer a later
+ * `=== null` with `true`, which is a wrong answer and not a spelling gap. A
+ * rest slot is refused here too: what a caller owes a rest parameter is an
+ * allocated array, and building one is lowering's, not this line's.
+ *
+ * Shared between the generic callable-carrier invoke path (`emit-callable.ts`)
+ * and the plugin-stated host construct-template path (`emit-host-invoke.ts`'s
+ * `nativeHandleInvocationText`): a host that states a fixed-arity construct
+ * template for a protocol whose checker signature has a trailing optional
+ * parameter (`new MediaRecorder(stream)` against `new (stream, options?)`)
+ * needs the identical padding a generic constructor carrier already gets --
+ * without it, only the call sites that happen to pass every optional argument
+ * explicitly would emit, and the ones that rely on the parameter's own
+ * optionality would refuse for no reason the host template states.
+ */
+export const paddedArguments = (abi, args, what) => {
+    const supplied = abi.receiver === null ? args.length : args.length - 1;
+    if (supplied >= abi.parameters.length)
+        return args;
+    const padding = abi.parameters.slice(supplied).map((parameter, offset) => {
+        const position = supplied + offset;
+        if (abi.restFrom !== null && position >= abi.restFrom) {
+            // An omitted rest argument list IS the empty array -- ECMA-262 10.2.11
+            // binds the rest parameter to a fresh Array of the arguments beyond the
+            // fixed ones, and there are none. That is not lowering's judgement to
+            // make; it is the language's answer, and `virtual-methods.ts`'s adapter
+            // already spells it this way for the identical omission. Only an array
+            // carrier is filled: anything else really is a shape this line cannot
+            // build. `it.next()` against `lib.es5.d.ts`'s own
+            // `next(...args: [] | [TNext])` is the case.
+            if (parameter.value.kind === 'array-object')
+                return `gea::makeRef<gea::ArrayObject<${cppTypeOf(parameter.value.element)}>>()`;
+            throw createCppEmitBlockedError(`call-abi:${what}:rest-parameter`, `omits the rest parameter at position ${position}, which the caller must allocate`);
+        }
+        // A `dynamic` slot states the absence the same way it states every other
+        // value: `gea::Value()` is `undefined` (gea_runtime.h -- "a
+        // default-constructed box is `undefined`"), which is exactly what
+        // ECMA-262 10.2.1 binds an omitted argument to. So the box needs no
+        // optional around it to hold one, which is the same fact `optionalOf`
+        // (representation/optional.ts) states when it declines to wrap one.
+        // A slot that spends absence on `null` as well -- `f(x: T | null = null)`,
+        // a three-armed union (`normalize/parameter-slot.ts`) -- states omission by
+        // its `undefined` ARM, since a default-constructed union holds its first
+        // arm, which is not necessarily that one. `ArmType` names the arm's own C++
+        // type so the empty value is spelled once, here, rather than re-derived
+        // from the representation.
+        const omitted = cppUndefinedIn(parameter.value);
+        if (omitted === null) {
+            throw createCppEmitBlockedError(`call-abi:${what}:omitted-argument`, `omits the argument at position ${position}, whose "${representationKey(parameter.value)}" slot cannot hold the \`undefined\` the ` +
+                'language binds an unpassed parameter to');
+        }
+        return omitted;
+    });
+    return [...args, ...padding];
+};
+/**
+ * The identifier this unit uses for one `Symbol.for` key, minting it on first
+ * ask.
+ *
+ * The ordinal, not the sanitized text, is what makes the name unique: two
+ * different keys can sanitize identically (`gea.d.dirty` and `gea/d/dirty`),
+ * and a name collision between two distinct symbols would be a silently wrong
+ * program rather than a build error. The text is still in the name because a
+ * reader of the emitted C++ should be able to see which key a static is.
+ */
+export const internSymbolKey = (symbolKeys, key) => {
+    const existing = symbolKeys.get(key);
+    if (existing !== undefined)
+        return existing;
+    let sanitized = '';
+    for (const character of key) {
+        const ok = (character >= 'a' && character <= 'z') || (character >= 'A' && character <= 'Z') || (character >= '0' && character <= '9');
+        sanitized += ok ? character : '_';
+    }
+    const name = `gea_symbol_${sanitized}_${symbolKeys.size}`;
+    symbolKeys.set(key, name);
+    return name;
+};
+/**
+ * The namespace-scope definitions for every key this unit interned.
+ *
+ * `inline` so a split build's units share one object rather than one each --
+ * and even where they do not (a key only one unit interns), correctness does
+ * not depend on it: the initializer goes THROUGH `gea::symbolFor`, so two
+ * separate statics for one key still resolve to the same registry entry.
+ *
+ * Emitted ahead of every body, because C++ requires a name to be declared
+ * before it is used and these are used from inside bodies.
+ */
+export const symbolKeyDefinitions = (symbolKeys) => [...symbolKeys].map(([key, name]) => `inline const gea::Symbol ${name} = gea::symbolFor(${cppStringLiteral(key)});`);
+/**
+ * Reserves this site's accessor and records its definition.
+ *
+ * The `static` inside the accessor is what makes the object per-site: it is
+ * initialized on the first call and every later call returns the SAME object,
+ * which is exactly `GetTemplateObject`'s per-Parse-Node cache (ECMA-262
+ * 13.2.8.3) and the property a tag's own `WeakMap` cache depends on. A
+ * function-local `static` rather than a namespace-scope object because the
+ * initializer builds a `shared_ptr` graph, and a namespace-scope one would run
+ * during static initialization, before the runtime this unit links against is
+ * necessarily up.
+ *
+ * `inline` so a split build's units share one definition instead of one each --
+ * and unlike an interned symbol key, that sharing is load-bearing rather than
+ * an optimization: two copies of one site's object would be two objects, which
+ * is the one thing this may not be.
+ */
+export const internTemplateObject = (templateObjects, operation, holder, body) => {
+    const site = operation.lineage;
+    if (site === null) {
+        throw createCppEmitBlockedError(`runtime-helper:allocation:template-object:${representationKey(operation.result.representation)}`, 'a template object cites no semantic result, so there is no per-site identity to key its one static on');
+    }
+    // GetTemplateObject is keyed by the Parse Node, not by a monomorphized body
+    // copy and not by the representation view through which that copy reaches
+    // it. Strip the specialization suffix from the operation's source node;
+    // keeping either suffix or `representationKey` here creates two objects for
+    // one source site and breaks tag caches.
+    const key = withoutSpecialization(nodeOfOperation(operationOfResult(site)));
+    const existing = templateObjects.get(key);
+    if (existing !== undefined) {
+        if (existing.holder !== holder) {
+            throw createCppEmitBlockedError(`runtime-helper:allocation:template-object:${representationKey(operation.result.representation)}`, `one tagged-template parse site reached incompatible carrier views "${existing.holder}" and "${holder}"; ` +
+                'GetTemplateObject requires one identity-preserving carrier for every specialization');
+        }
+        return existing.name;
+    }
+    const name = `gea_template_object_${templateObjects.size}`;
+    const text = [
+        `inline const ${holder}& ${name}() {`,
+        `  static const ${holder} gea_template = []() {`,
+        ...body.map((line) => `    ${line}`),
+        '  }();',
+        '  return gea_template;',
+        '}'
+    ].join('\n');
+    templateObjects.set(key, { name, text, holder });
+    return name;
+};
+/** The namespace-scope definitions for every tagged-template site this unit reached, emitted ahead of the bodies that call them. */
+export const templateObjectDefinitions = (templateObjects) => [...templateObjects.values()].map((definition) => definition.text);
+// `bindingReference` moved to its own file when this one crossed the
+// architecture gate's 1200-line limit. Re-exported here because it is the same
+// question every caller was already asking of this module -- "what C++ name
+// does this declaration have here" -- and moving the import sites would have
+// been a rename dressed up as a refactor.
+export { bindingReference } from './emit-binding-reference.js';
+/**
+ * Invariant 5 (invariant 5: no write during render): the printer's context is
+ * immutable for the duration of a body.
+ *
+ * A FACT written while statements render makes what a later statement emits
+ * depend on render ORDER rather than on the program -- the sharp end of which
+ * is `emit-properties.ts`'s `gea_string_metadata_${ctx.prototypeMethodReads
+ * .size}`, a struct whose NAME is however many prototype reads happened to be
+ * registered before it. Section 2.7's shrink (every fact field off
+ * `EmitContext`, leaving naming, interning, spelling tables and buffers) is
+ * what makes the invariant structural; until then this is the instrument that
+ * says which fields are left.
+ *
+ * A grep cannot answer that question: most `ctx.<collection>.set(...)` sites
+ * are reached from `emitBody`'s PREPASS (`admitDenseWindows`, the census
+ * reconciliation, the direct-callee walk), which runs before any operation
+ * renders and is exactly where a fact is supposed to be settled. Only a seal
+ * taken at the block loop tells the two apart, and it names the field and
+ * carries a stack to the site.
+ *
+ * Off unless `GEA_SEAL_EMIT_CONTEXT` is set, and it restores the context it
+ * sealed, so a run that enumerates violations is a run of the same printer.
+ */
+const renderMutableEmitContextFields = new Set([
+    // Naming and interning -- 2.7 keeps both, and both are minted as an
+    // operation renders by construction.
+    'valueNames',
+    'bindingNames',
+    'symbolKeys',
+    'templateObjects',
+    // Output buffers. `ownedValues` is one despite reading like a fact: see
+    // `emit.ts`'s note at the formal-argument seeding -- membership is not
+    // independent of the naming machinery that grows it.
+    'declarations',
+    'printerDrift',
+    'pendingClassTableLines',
+    'deferredTexts',
+    'pendingPacks',
+    'ownedValues',
+    // Render bookkeeping, not a fact: `declaredBindings` is which declarations
+    // have ALREADY emitted their one declaring statement, so a later write is a
+    // plain assignment. Its whole content is what has been printed so far, which
+    // is what a buffer is.
+    'declaredBindings',
+    // Naming again, by the same test as `valueNames`: what these two hold is the
+    // C++ NAME of a scratch local this render minted for a dynamic iterator --
+    // `v<ordinal>` from `nextValueOrdinal`, declared into `declarations` on the
+    // same line that records it. A name that does not exist until something is
+    // printed cannot be settled before printing, and nothing about the body is
+    // being decided here: WHICH values are dynamic iterator records is the
+    // carrier's own answer, asked afresh at every use.
+    'dynamicIteratorDoneStates',
+    'dynamicIteratorSteps',
+    // The same test a third time, for the iterator-record path the two above are
+    // the dynamic twin of: what `protocolNextResults` holds is the NAME of the
+    // once-only `next()` result local, plus the accessor that reads its two
+    // fields back. `emitIteratorNext` mints and declares it, `emitIteratorDone`
+    // reads the same local instead of calling `next()` again -- which is a
+    // caching decision about the text, not about the body.
+    'protocolNextResults',
+    // A wrapped dense window's subscript companion, minted and declared beside
+    // the read that needed it (`denseRemainderCompanion`). WHICH accesses a
+    // window admits is `admitDenseWindows`' prepass answer; this is only what
+    // that access's index is spelled as.
+    'denseIndices',
+    // The same test again: `gea_string_metadata_<N>` is a local this render
+    // minted and declared, and `<N>` is how many it had minted before -- which
+    // is why the ordinal now counts THIS table rather than however many
+    // prototype reads happened to be registered, and why
+    // `scripts/normalize-emitted.mjs` renumbers it positionally like `v<N>`.
+    'stringMetadataNames',
+    // PROOF, the fourth category, and the only one that cannot be settled even
+    // in principle: each records that a deferred read was CONSUMED by a call,
+    // and `emitBody` refuses on any entry still unconsumed once the body has
+    // finished. "Did the rest of this body call it" is a question about the
+    // render, asked after the render, so it is answered during one by
+    // construction. WHICH reads are deferred is the settled fact
+    // (`virtualCallees`, `unionMethodReads`); this is only what became of them.
+    'virtualCalleesUsed',
+    'unionMethodReadsUsed',
+    // The one the seal had simply never been told about -- which meant it could
+    // only pass on programs that happen not to reach this write, so a green run
+    // under `GEA_SEAL_EMIT_CONTEXT` proved less than it looked like it did.
+    //
+    // `constantTexts` is the FOLDING READER half of what used to be one map.
+    // `staticKeyTexts` was split out of it precisely because this half keeps
+    // growing during a render -- a `typeof` whose operand's tag is known folds
+    // to a literal here as it is spelled -- so it is a superset of the settled
+    // constants in exactly the place where a superset would turn a computed key
+    // into a static one. Every claim asks `staticKeyTexts`; this one exists so a
+    // later fold can reuse text an earlier one produced.
+    'constantTexts'
+]);
+const mapMutators = new Set(['set', 'delete', 'clear']);
+const setMutators = new Set(['add', 'delete', 'clear']);
+const sealedCollection = (field, collection, mutators) => new Proxy(collection, {
+    get: (target, property) => {
+        if (typeof property === 'string' && mutators.has(property)) {
+            return () => {
+                throw new Error(`EmitContext.${field}.${property} written during render (invariant 5: no write during render)`);
+            };
+        }
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+    }
+});
+/** Seals every fact collection on `ctx` for the caller's render, and returns the undo. */
+export const sealFactFieldsForRender = (ctx) => {
+    if (process.env['GEA_SEAL_EMIT_CONTEXT'] === undefined)
+        return () => { };
+    const fields = ctx;
+    const original = new Map();
+    for (const [field, value] of Object.entries(fields)) {
+        if (renderMutableEmitContextFields.has(field))
+            continue;
+        if (value instanceof Map) {
+            original.set(field, value);
+            fields[field] = sealedCollection(field, value, mapMutators);
+        }
+        else if (value instanceof Set) {
+            original.set(field, value);
+            fields[field] = sealedCollection(field, value, setMutators);
+        }
+    }
+    return () => {
+        for (const [field, value] of original)
+            fields[field] = value;
+    };
+};