@geastack/compiler 1.0.15

package/dist/projection/abi.js

@@ -0,0 +1,349 @@
+import { declarationOfFunction } from '../identity/ids.js';
+import { abiKey, representationKey } from '../representation/model.js';
+import { callableMutationFactsOf, callableOriginsOf } from '../semantics/callable-origins.js';
+import { resultOf } from '../semantics/model/operands.js';
+/**
+ * The carrier the plan selected for one parameter binding's published value.
+ *
+ * Read through the plan rather than re-derived, for the same reason the ABI is:
+ * a parameter's carrier is a fixed-point output, and a second derivation of it
+ * would be a second answer.
+ */
+const parameterCarrierKeys = (input, functionId, bodies) => {
+    const keys = new Map();
+    for (const operation of bodies.get(functionId) ?? []) {
+        // A defaulted parameter's own `binding.initialize` operand no longer cites
+        // `{kind: 'parameter'}` directly -- it cites the `default-value` merge's
+        // result instead, because what it binds is the post-default value, not
+        // the raw argument. The raw argument is what the new `parameter-value`
+        // reference operation cites, so that operation is equally valid evidence
+        // that this ABI position is bound, for the one case the original scan
+        // alone can no longer see.
+        const isDefaultedParameterSource = operation.family === 'reference' && operation.form === 'parameter-value';
+        if (!isDefaultedParameterSource && (operation.family !== 'binding' || operation.action !== 'initialize'))
+            continue;
+        const initializer = operation.operands.find((operand) => operand.source.kind === 'parameter');
+        if (!initializer || initializer.source.kind !== 'parameter')
+            continue;
+        const published = resultOf(operation, 'value');
+        const carrier = published ? input.plan.selected.get(published.id) : undefined;
+        keys.set(initializer.source.ordinal, carrier ? representationKey(carrier) : 'unselected');
+    }
+    return keys;
+};
+const abiOfCarrier = (input, functionId, allocations) => {
+    for (const operation of allocations.get(functionId) ?? []) {
+        const published = resultOf(operation, 'value');
+        const carrier = published ? input.plan.selected.get(published.id) : undefined;
+        if (!carrier)
+            continue;
+        if (carrier.kind === 'function' || carrier.kind === 'function-value-dispatch')
+            return { call: carrier.abi, construct: null };
+        if (carrier.kind === 'function-family' || carrier.kind === 'function-value-family')
+            return { call: carrier.abi, construct: null };
+        // A JS CONSTRUCTOR FUNCTION: one `function F( a, b ) {}` that is both
+        // called and `new`ed, which is how three.js writes almost every internal
+        // module -- `WebGLTextures`, `WebGLProgram`, `WebGLShadowMap`, ten of them
+        // in one program, each blocked here with "no function-object allocation
+        // published a callable carrier" while its allocation had published a
+        // perfectly good one this function had no arm for.
+        //
+        // One body serves both conventions, and its FORMALS are the shared half:
+        // the same parameter list is read whichever way it was entered. The result
+        // is not shared -- `new F()` evaluates to the instance and `F()` to what
+        // the body returns -- and the body's own is the call one, since a
+        // construction takes the instance from `.construct` (`emit-callable.ts`),
+        // never from the body's return value.
+        //
+        // Only when the two frames agree. Where they do not, the two entry points
+        // would need two bodies, and this projection has one to state.
+        if (carrier.kind === 'function-and-constructor' && argumentFrameKey(carrier.call) === argumentFrameKey(carrier.construct)) {
+            return { call: carrier.call, construct: carrier.construct };
+        }
+        // A function boxed to `dynamic` under `--dynamic-fallback` (its own
+        // `.prototype` read or written, `prototypeMutatedConstructorTypes` in
+        // dynamic-fallback.ts) still has to bind a real parameter frame when its
+        // body runs -- a fact about the DECLARATION, never about which carrier a
+        // later census chose for the value. `nativeCallableConventions` answers
+        // exactly that, keyed by the allocation's checker-authenticated FunctionId.
+        // Its structural shape is deliberately not accepted: unrelated functions
+        // with the same signature share that id and may not borrow this frame.
+        if (carrier.kind === 'dynamic' &&
+            operation.family === 'allocation' &&
+            operation.allocated === 'function-object' &&
+            operation.callable === functionId &&
+            input.deriver) {
+            const native = input.deriver.nativeCallableConventions(functionId);
+            if (native)
+                return native;
+        }
+    }
+    return null;
+};
+/**
+ * A convention's ARGUMENT half, as a key -- the part two entry points into one
+ * body have to share, with the result and the receiver deliberately left out.
+ *
+ * The receiver is left out because it is the one slot the two conventions into
+ * a JS constructor function legitimately DISAGREE in, and neither answer is
+ * wrong: `[[Construct]]` manufactures the receiver (ECMA-262 10.2.2, so
+ * `representation/derive.ts` states none for it) while `[[Call]]` is handed
+ * one. Keying on it made every such function's frames compare unequal and
+ * blocked the body -- which is the whole of three.js's renderer -- for a
+ * disagreement that is the language's own.
+ */
+const argumentFrameKey = (abi) => [abi.parameters.map((parameter) => `${representationKey(parameter.value)}/${parameter.ownership}`).join(','), abi.restFrom ?? '-'].join(';');
+/**
+ * The calling convention a Representation states, when it states one -- the
+ * same set of callable carrier kinds `abiOfCarrier` above reads off a
+ * `function-object` allocation, asked instead of an arbitrary published
+ * value. `function-and-constructor` contributes its `call` half alone: unlike
+ * `abiOfCarrier`'s own use of that carrier (which is *becoming* the two-entry
+ * function and so needs both frames to agree), a forwarding candidate is only
+ * ever borrowed as a callee, and a call site only ever needs `[[Call]]`.
+ */
+const callConventionOf = (representation) => {
+    switch (representation.kind) {
+        case 'function':
+        case 'function-family':
+        case 'function-value-dispatch':
+        case 'function-value-family':
+            return representation.abi;
+        case 'native-handle':
+            return representation.call;
+        case 'function-and-constructor':
+            return representation.call;
+        default:
+            return null;
+    }
+};
+/**
+ * Whether a convention is the fiction a checker synthesizes for a JavaScript
+ * function that declares no parameters but reads the `arguments` object --
+ * three.js's `function texImage2D() { gl.texImage2D( ...arguments ) }`, one
+ * of ~2,315 functions across a real application and the majority shape behind
+ * this projection's blockers.
+ *
+ * There is no declared parameter for `structural-parts.ts`'s `parameterOf` to
+ * read a `ts.ParameterDeclaration` from, so the checker's own inferred
+ * signature is the only source that layer has, and what it publishes is one
+ * parameter shaped like the whole `arguments` object: a plain dynamic array,
+ * with no rest marker (a real `...args: T[]` parameter has a declaration, and
+ * derives to whatever `T` is, not to this specific undeclared shape). Naming
+ * the shape precisely -- one parameter, no `restFrom`, an `array-object` of
+ * `dynamic(declared-any-never-narrowed)` -- is what keeps this from ever
+ * matching a real single-parameter function whose declared type happens to be
+ * `any[]`: that function has a `ts.ParameterDeclaration`, and its body binds
+ * one physical parameter the standard check below already accepts.
+ */
+const isArgumentsObjectFiction = (abi) => {
+    if (abi.restFrom !== null || abi.parameters.length !== 1)
+        return false;
+    const value = abi.parameters[0]?.value;
+    return value?.kind === 'array-object' && value.element.kind === 'dynamic' && value.element.reason === 'declared-any-never-narrowed';
+};
+/**
+ * The one other callable this shim forwards its whole `arguments` object to,
+ * when there is exactly one.
+ *
+ * A forwarding shim's entire body is `callee( ...arguments )`, so the
+ * `callee` sub-expression is READ (a `property` or `reference` operation
+ * publishes it) but never itself an operand of anything else in the body --
+ * the spread call that would consume it is exactly the call this compiler has
+ * no primitive to build (`producers/spread-arguments.ts` refuses spreading an
+ * `arguments` object into a callee with no rest formal), so it leaves no
+ * `invocation` operation behind and the read sits unconsumed. That is the
+ * signal: among this body's operations, the callable-valued one nothing else
+ * cites is the callee the source forwarded to. A body with zero or with more
+ * than one such candidate states nothing this projection can act on, and
+ * returns `null` rather than guess between them -- `console.error`'s own
+ * receiver read is exactly this shape's other common case (see the shim
+ * bodies in `.scratch/threejs/abi-arity.mjs`'s output), and is excluded by
+ * being consumed by its own call.
+ *
+ * `isArgumentsObjectFiction` is asked of every candidate too, not only of
+ * this function's own ABI, so a chain of two shims never borrows the nearer
+ * one's fiction instead of walking to the real callee underneath it.
+ */
+const forwardingCalleeAbi = (input, functionId, bodies) => {
+    const operations = bodies.get(functionId) ?? [];
+    const consumed = new Set();
+    for (const operation of operations) {
+        for (const operand of operation.operands) {
+            if (operand.source.kind === 'result')
+                consumed.add(operand.source.result);
+        }
+    }
+    let found = null;
+    for (const operation of operations) {
+        const published = resultOf(operation, 'value');
+        if (!published || consumed.has(published.id))
+            continue;
+        const carrier = input.plan.selected.get(published.id);
+        const abi = carrier ? callConventionOf(carrier) : null;
+        if (!abi || isArgumentsObjectFiction(abi))
+            continue;
+        if (found)
+            return null;
+        found = abi;
+    }
+    return found;
+};
+/**
+ * The `[[Construct]]` convention each call frame is asked for, over the whole
+ * plan, computed once.
+ *
+ * A cast that asserts a construct signature onto a call-only function puts the
+ * second convention on the CAST's carrier; nothing links it back to the
+ * declaration except the call frame the two share. This is that link, read by
+ * the demand test below. Deliberately keyed by the call frame and not by a
+ * declaration: the plan has no declaration to offer here, and matching two
+ * declarations that share one frame costs an unused thunk, never a wrong
+ * construction -- the runtime looks the entry up by the value's own invoke
+ * pointer.
+ *
+ * A carrier nested inside a container is not reached. That is the fail-closed
+ * direction: the conversion then finds no entry and refuses by name.
+ */
+const demandedConstructAbis = (plan) => {
+    const abis = new Map();
+    // Two different construct conventions over one call frame name no single
+    // second entry point for the body, so neither is published. That is the same
+    // "one body states one convention" rule `abiOfCarrier` applies to the
+    // allocation's own carrier, and the conversion then refuses by name.
+    const ambiguous = new Set();
+    for (const carrier of plan.selected.values()) {
+        const payload = carrier.kind === 'optional' ? carrier.payload : carrier;
+        if (payload.kind !== 'function-and-constructor')
+            continue;
+        const key = abiKey(payload.call);
+        const seen = abis.get(key);
+        if (seen !== undefined && abiKey(seen) !== abiKey(payload.construct))
+            ambiguous.add(key);
+        abis.set(key, payload.construct);
+    }
+    for (const key of ambiguous)
+        abis.delete(key);
+    return abis;
+};
+const indexOperations = (graph) => {
+    const bodies = new Map();
+    const allocations = new Map();
+    const add = (into, key, operation) => {
+        const bucket = into.get(key);
+        if (bucket)
+            bucket.push(operation);
+        else
+            into.set(key, [operation]);
+    };
+    for (const operation of graph.operations.values()) {
+        if (operation.caller.kind === 'function')
+            add(bodies, operation.caller.functionId, operation);
+        if (operation.family === 'allocation' && operation.allocated === 'function-object' && operation.callable) {
+            add(allocations, operation.callable, operation);
+        }
+    }
+    return { bodies, allocations };
+};
+export const projectAbis = (input) => {
+    const abis = new Map();
+    const constructs = new Map();
+    const blocked = [];
+    const callableOrigins = callableOriginsOf(input.graph);
+    const callableMutations = callableMutationFactsOf(input.graph, input.plan, callableOrigins);
+    const { bodies, allocations } = indexOperations(input.graph);
+    const demandedConstructs = demandedConstructAbis(input.plan);
+    const functions = new Set();
+    for (const operation of input.graph.operations.values()) {
+        if (operation.caller.kind === 'function')
+            functions.add(operation.caller.functionId);
+        if (operation.family === 'allocation' && operation.callable)
+            functions.add(operation.callable);
+    }
+    // Resolved once per blocked function rather than inline at each push site:
+    // every blocker below names the SAME `functionId`, and `declarationOfFunction`
+    // plus the lookup is one answer, not three.
+    const locationOf = (functionId) => input.locationOfDeclaration?.(declarationOfFunction(functionId)) ?? null;
+    for (const functionId of [...functions].sort()) {
+        const conventions = abiOfCarrier(input, functionId, allocations);
+        if (!conventions) {
+            blocked.push({
+                functionId,
+                reason: 'no function-object allocation published a callable carrier for this function, so it has no stated calling convention',
+                location: locationOf(functionId)
+            });
+            continue;
+        }
+        const abi = conventions.call;
+        const carriers = parameterCarrierKeys(input, functionId, bodies);
+        // A forwarding shim declares no `ts.ParameterDeclaration` at all, so
+        // `carriers` is legitimately empty by source, not by defect -- there is no
+        // named binding the standard check below could ever find. Its checker-
+        // published ABI is not a second, disagreeing authority either: it is a
+        // fiction the checker states for lack of anything better, over a value
+        // this compiler's own plan already carries the real convention for, one
+        // step away at the callee the shim forwards to. Adopting that convention
+        // here is not the reconciliation this file's own module comment refuses --
+        // there was never a real disagreement to reconcile, only one authority
+        // (the checker, over an undeclared parameter) that had nothing to publish
+        // and said so with a fiction.
+        if (carriers.size === 0 && isArgumentsObjectFiction(abi)) {
+            const forwarded = forwardingCalleeAbi(input, functionId, bodies);
+            if (forwarded) {
+                abis.set(functionId, forwarded);
+                continue;
+            }
+        }
+        if (carriers.size !== abi.parameters.length) {
+            blocked.push({
+                functionId,
+                reason: `the body binds ${carriers.size} physical parameter(s) but the ABI declares ${abi.parameters.length}`,
+                location: locationOf(functionId)
+            });
+            continue;
+        }
+        const mismatch = abi.parameters.findIndex((parameter, ordinal) => carriers.get(ordinal) !== representationKey(parameter.value));
+        const declared = abi.parameters[mismatch];
+        if (mismatch >= 0 && declared) {
+            blocked.push({
+                functionId,
+                reason: `parameter ${mismatch} is bound as "${carriers.get(mismatch) ?? 'absent'}" but the ABI declares ` +
+                    `"${representationKey(declared.value)}"`,
+                location: locationOf(functionId)
+            });
+            continue;
+        }
+        abis.set(functionId, abi);
+        if (conventions.construct)
+            constructs.set(functionId, conventions.construct);
+        else {
+            // The allocation published only a `[[Call]]` carrier, and somewhere the
+            // program still names this declaration's `[[Construct]]`: `Factory as
+            // typeof Factory & (new (v: number) => T)` puts the construct half on
+            // the CAST's carrier, never on the allocation's. ECMA-262 gives a
+            // pre-`class` constructor function both internal methods when it is
+            // created, so the second convention is not invented here -- it is taken
+            // from the carrier that demanded it, matched to this declaration by its
+            // call frame, and only where the two entry points share one argument
+            // frame the single body can bind.
+            //
+            // Demand-driven, so a function that is only ever called still emits one
+            // thunk. Two declarations sharing one call frame both get one, and that
+            // costs an unused thunk rather than a wrong answer: the runtime looks
+            // the entry up by the value's own invoke pointer
+            // (`gea::withConstructEntry`), so a construction can never enter another
+            // declaration's body.
+            const demanded = demandedConstructs.get(abiKey(abi));
+            if (demanded && argumentFrameKey(abi) === argumentFrameKey(demanded))
+                constructs.set(functionId, demanded);
+        }
+    }
+    return {
+        abis,
+        constructs,
+        callableOrigins,
+        callableOwnPropertyWrites: callableMutations.ownProperties,
+        functionPrototypePropertyWrites: callableMutations.functionPrototypeProperties,
+        blocked: Object.freeze(blocked)
+    };
+};

package/dist/projection/apply-arguments.d.ts

@@ -0,0 +1,12 @@
+import type { StructuralTypeId } from '../identity/ids.js';
+import type { RepresentationDeriver } from '../representation/derive.js';
+import type { RecordField, Representation } from '../representation/model.js';
+import type { StructuralType } from '../semantics/model/structural-types.js';
+/**
+ * The positions CreateListFromArrayLike reads from a closed typed tuple.
+ * Arity comes from the semantic type; payload carriers come from physical
+ * storage. Homogeneous tuples can use ArrayObject storage, while heterogeneous
+ * tuples use positional records. Neither changes the tuple's stated arity.
+ * Optional/open tuples retain the runtime-sized path.
+ */
+export declare const fixedApplyArgumentFieldsOf: (types: ReadonlyMap<StructuralTypeId, StructuralType>, type: StructuralTypeId, carrier: Representation, deriver: RepresentationDeriver) => readonly RecordField[] | null;

package/dist/projection/apply-arguments.js

@@ -0,0 +1,20 @@
+/**
+ * The positions CreateListFromArrayLike reads from a closed typed tuple.
+ * Arity comes from the semantic type; payload carriers come from physical
+ * storage. Homogeneous tuples can use ArrayObject storage, while heterogeneous
+ * tuples use positional records. Neither changes the tuple's stated arity.
+ * Optional/open tuples retain the runtime-sized path.
+ */
+export const fixedApplyArgumentFieldsOf = (types, type, carrier, deriver) => {
+    const shape = types.get(type)?.shape;
+    if (shape?.kind !== 'tuple' || shape.elements.some((element) => element.optional || element.rest || element.variadic))
+        return null;
+    if (carrier.kind === 'array-object') {
+        return shape.elements.map((_, index) => ({ key: String(index), value: carrier.element, required: true }));
+    }
+    const layout = carrier.kind === 'native-record-ref' ? deriver.layoutOf(carrier.shapeId) : carrier;
+    if (layout.kind !== 'record')
+        return null;
+    const fields = shape.elements.map((_, index) => layout.fields.find((field) => field.key === String(index)));
+    return fields.every((field) => field !== undefined && field.required) ? fields : null;
+};

package/dist/projection/bindings.d.ts

@@ -0,0 +1,250 @@
+import type { DeclarationId, FunctionId, RegionId } from '../identity/ids.js';
+import type { Representation } from '../representation/model.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { HostNamespaceTable } from '../targets/cpp/host/host-members.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+/**
+ * Where each binding cell physically lives.
+ *
+ * A binding is introduced by exactly one operation, and that operation's caller
+ * is the execution context the cell belongs to. Nothing else in the compiler
+ * knows this: the IR carries a `DeclarationId` on every read and write, and a
+ * body seeing one has no way to tell a local of its own from a module-level
+ * cell it merely refers to. Without this projection the emitter treats every
+ * cell as a local, which turns a perfectly ordinary module-scope `const` read
+ * from inside a function into either a capture it must refuse or -- worse -- a
+ * reference to a variable no enclosing block declares.
+ *
+ * A binding introduced with `BindingOperation.external` set is `external`
+ * storage instead of `local`/`region`: `declare const x` names a cell the
+ * *host* defines, not this program, so there is no callable frame or run-once
+ * region that owns it. That is not a defect to route around -- it is a
+ * different, legitimate ownership, gated by its own preflight obligation
+ * (`buildExternalBindingObligation`, preflight/run.ts) rather than by the
+ * carrier-selection one every other binding raises. A declaration with no
+ * introducing operation at all -- an import this program's semantic graph
+ * does not yet model, for instance -- has no entry in the map rather than an
+ * explicit `external` placement; a consumer sees the same absence either way
+ * and refuses by name (`bindingReference`, targets/cpp/emit-context.ts).
+ */
+export type BindingStorage = 
+/** A cell owned by one callable frame. */
+{
+    readonly kind: 'local';
+    readonly owner: FunctionId;
+}
+/** A cell owned by a region that runs once: a module body, an initializer, a static block. */
+ | {
+    readonly kind: 'region';
+    readonly owner: RegionId;
+}
+/**
+ * Named by this program, defined by a host. `linkageName` is the ABI
+ * contract the two sides agree on, carried verbatim from
+ * `BindingOperation.external` (semantics/model/operations.ts) -- the one
+ * place that string is read from the declaration's own spelling.
+ */
+ | {
+    readonly kind: 'external';
+    readonly linkageName: string;
+}
+/**
+ * Named by this program, and defined by NOBODY -- an ambient global an
+ * installed host declared it does not provide
+ * (`PluginCapabilities.absentGlobals`).
+ *
+ * A cell, not an `extern`, and the difference is the whole point. The program
+ * still reads the name, so there has to be something to read; but no object
+ * file defines it, so `extern` would compile and never link. The unit defines
+ * it itself, holding the one value it can have -- `undefined`, which is also
+ * the carrier the type census gave it, so the storage and the value agree by
+ * construction rather than by coincidence.
+ *
+ * `linkageName` is kept for diagnostics only. Nothing links against it.
+ */
+ | {
+    readonly kind: 'absent';
+    readonly linkageName: string;
+}
+/**
+ * A host's class object: named by this program, and no cell anywhere.
+ *
+ * `NSColor` is not a variable a host defines. It is a class, and the only
+ * things a program reaches through it -- constructing one, and its own class
+ * members -- are spelled by the host by naming the class outright
+ * (`[[::NSStackView alloc] init]`, `[::NSColor clearColor]`). Declaring an
+ * `extern` for it invents a C++ global nothing defines, and in Objective-C++
+ * it does worse than fail to link: the ObjC class of the same name is already
+ * a type at global scope, so `extern gea::apple::AppKit::NSColor NSColor;` is
+ * a redefinition as a different kind of symbol and the file does not compile.
+ *
+ * So the read of one produces no C++ at all, exactly as a host METHOD access
+ * does (`emit-host-properties.ts` returns the empty rendering and the call
+ * site spells the whole thing). Anything that genuinely needs a value here
+ * is refused by name rather than handed a cell that does not exist.
+ */
+ | {
+    readonly kind: 'host-class';
+    readonly linkageName: string;
+}
+/**
+ * A host's SINGLETON: one object the host owns, reached by its own name
+ * rather than loaded from a cell.
+ *
+ * `document` is the case. The engine's `gea::embedded::ui::Document` has a
+ * private default constructor and one instance behind `Document::instance()`,
+ * and the member table the host ships spells every call through that -- no
+ * template names a receiver. So there is nothing for a read of the global to
+ * load: `extern gea::embedded::ui::Document document;` names a cell the
+ * engine never defines and would not link, and the local it was copied into
+ * (`gea::embedded::ui::Document v1;`) calls a constructor that is private.
+ *
+ * Physically identical to `host-class` -- the read renders nothing and the
+ * member site spells the whole thing -- and named apart from it because the
+ * two are recognized differently: a class object is one this program can
+ * `new`, and a singleton is one the host states members for and no program
+ * ever constructs.
+ */
+ | {
+    readonly kind: 'host-singleton';
+    readonly linkageName: string;
+}
+/**
+ * A host's constant: named by this program, and the host states the text.
+ *
+ * `NSBoxCustom` is an Objective-C enumerator, not a C++ global, so there is
+ * no cell for it and an `extern` naming one is ill-formed where the
+ * enumerator is already in scope. The host answers with the value instead,
+ * and every read renders that text.
+ */
+ | {
+    readonly kind: 'host-constant';
+    readonly linkageName: string;
+    readonly emit: string;
+}
+/**
+ * A name the host defines as a FUNCTION.
+ *
+ * `installRootViewController` is not a cell -- there is nothing to read and
+ * nothing to declare `extern`, because the host exports a function of that
+ * name and a C++ `extern <callable-carrier> installRootViewController;` would
+ * be a global variable that no object file defines. The read renders
+ * nothing; the call it feeds renders the host's own spelling.
+ */
+ | {
+    readonly kind: 'host-function';
+    readonly linkageName: string;
+    readonly emit: string;
+}
+/**
+ * A name the host defines as a NAMESPACE: a path, not a value.
+ *
+ * `deviceInfo`, `Display` and `navigator` are global objects to the
+ * checker and paths to the host: `deviceInfo.deviceId(...)` is
+ * `gea::host::device_info::deviceId(...)`, and no object of that name exists at run
+ * time. Reading one produces no C++ -- `host-class`'s own convention, for
+ * the same reason -- and what is done THROUGH it renders the host's
+ * spelling. Without this the cell is an ordinary external and the unit
+ * declares `extern std::shared_ptr<gea_record_type_801> deviceInfo;`,
+ * which compiles and never links.
+ */
+ | {
+    readonly kind: 'host-namespace';
+    readonly linkageName: string;
+};
+export interface BindingPlacement {
+    readonly storage: BindingStorage;
+    /** The carrier the plan selected for the value this cell holds, or `null` when the introduction published none. */
+    readonly representation: Representation | null;
+}
+export interface BindingPlacementInput {
+    readonly graph: SemanticGraph;
+    readonly plan: SealedRepresentationPlan;
+    /**
+     * The ABI name a host defines a cell under, for declarations this program
+     * reads but never introduces (`FrontendResult.externalBindings`).
+     *
+     * Only the frontend can produce this, because deciding it means asking the
+     * checker which declaration a name resolves to and whether that declaration
+     * is ambient. Omitted, every such cell simply has no placement -- which is
+     * what it had before this existed.
+     */
+    readonly externals?: ReadonlyMap<DeclarationId, string>;
+    /** Which of those an installed host denied (`FrontendResult.absentBindings`) -- see `absent` storage. */
+    readonly absentBindings?: ReadonlySet<DeclarationId>;
+    /**
+     * The ambient names an installed host defines as constants, to the text each
+     * one is (`PluginCapabilities.nativeConstants`).
+     *
+     * Consulted only for a declaration this program never introduces, and only by
+     * the name the frontend resolved it to -- a program that declares its own
+     * `NSBoxCustom` keeps its own cell, because the loop below runs second and
+     * skips anything already placed.
+     */
+    readonly hostConstants?: ReadonlyMap<string, string>;
+    /** The ambient names this program's hosts define as free functions, to the C++ each is. */
+    readonly hostFunctions?: ReadonlyMap<string, string>;
+    /**
+     * The ECMAScript/WHATWG GLOBAL FUNCTIONS the backend implements itself, to
+     * the C++ each is (`targets/cpp/host/core-globals.ts`).
+     *
+     * Held apart from `hostFunctions` above rather than merged into it, because
+     * the two are admitted differently: a host's name is the host's whatever
+     * declares it, while a language builtin's name is only the language's when
+     * the STANDARD LIBRARY declared it -- see `standardLibraryExternals`.
+     */
+    readonly coreGlobalFunctions?: ReadonlyMap<string, string>;
+    /**
+     * The language's own CLASS OBJECTS -- names whose value is a constructor
+     * this backend spells the construction of, with no cell behind the name.
+     * See `coreGlobalClasses` (targets/cpp/host/core-globals.ts). Same
+     * `standardLibraryExternals` gate as its two siblings.
+     */
+    readonly coreGlobalClasses?: ReadonlySet<string>;
+    /**
+     * The declarations the standard library declares
+     * (`FrontendResult.standardLibraryBindings`).
+     *
+     * The gate on `coreGlobalFunctions`: without it, a program's own ambient
+     * `declare function btoa(...)` would be silently redirected to this
+     * backend's base64 codec by name alone.
+     */
+    readonly standardLibraryExternals?: ReadonlySet<DeclarationId>;
+    /**
+     * The same, for the names one host declares in more than one of its own files
+     * (`PluginCapabilities.hostFunctionsByDeclaration`), keyed by that file.
+     */
+    readonly hostFunctionsByDeclaration?: ReadonlyMap<string, ReadonlyMap<string, string>>;
+    /** The file each external declaration lives in (`FrontendResult.externalBindingFiles`). */
+    readonly externalFiles?: ReadonlyMap<DeclarationId, string>;
+    /**
+     * The same disambiguation `hostFunctionsByDeclaration` gives constants: two
+     * of a host's own files can declare one name as a different ambient
+     * constant, and only the declaration this program actually resolved to says
+     * which was meant.
+     */
+    readonly hostConstantsByDeclaration?: ReadonlyMap<string, ReadonlyMap<string, string>>;
+    /** The ambient names this program's hosts own as namespace paths rather than as values. */
+    readonly hostNamespaces?: HostNamespaceTable;
+    /** The same disambiguation, for a namespace root two of a host's own files both claim. */
+    readonly hostNamespaceRootsByDeclaration?: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Namespace roots authenticated by the frontend against a complete declaration set. */
+    readonly hostNamespaceBindings?: ReadonlySet<DeclarationId>;
+    /** Names with exact declaration rows; these may not fall back to name-only admission. */
+    readonly exactHostNamespaceNames?: ReadonlySet<string>;
+    /** The ambient names this program's hosts own as singleton objects reached by name -- see `host-singleton`. */
+    readonly hostSingletons?: ReadonlySet<string>;
+    /** The same disambiguation, for a singleton name two of a host's own files both claim. */
+    readonly hostSingletonsByDeclaration?: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Singleton values the frontend authenticated from an exact host declaration. */
+    readonly hostSingletonBindings?: ReadonlySet<DeclarationId>;
+}
+/**
+ * Every cell a program introduces, keyed by declaration.
+ *
+ * `initialize`, `declare`, and the `module-link`/`initialize` events of the
+ * declaration-lifecycle family are all introductions, and they are collected
+ * together on purpose: a consumer asking "where does this cell live" must get
+ * one answer regardless of which family happened to introduce it.
+ */
+export declare const projectBindingPlacements: (input: BindingPlacementInput) => ReadonlyMap<DeclarationId, BindingPlacement>;