@geastack/compiler 1.0.15

package/dist/targets/cpp/emit-binding-reference.d.ts

@@ -0,0 +1,17 @@
+import type { DeclarationId } from '../../identity/ids.js';
+import { type EmitContext } from './emit-context.js';
+/**
+ * A binding cell's name, and whether this body owns it.
+ *
+ * `local` cells are minted on first sight -- a read or a write -- so every
+ * later reference in either operation kind agrees. A cell a region owns is a
+ * file-scope variable instead, because the body that initializes it and the
+ * bodies that read it are different C++ functions: making it a local of the
+ * module body would put the value out of every other body's reach, and the
+ * program would compile with each function reading a name that does not exist.
+ */
+export declare const bindingReference: (ctx: EmitContext, declaration: DeclarationId, what: string) => {
+    name: string;
+    owned: boolean;
+    boxed: boolean;
+};

package/dist/targets/cpp/emit-binding-reference.js

@@ -0,0 +1,120 @@
+import { captureCapabilityOf } from '../../representation/model.js';
+import { cppCaptureFieldName, cppEnvironmentLocalName, createCppEmitBlockedError } from './emit-context.js';
+import { cppGlobalName, cppTypeOf } from './types.js';
+/**
+ * A binding cell's name, and whether this body owns it.
+ *
+ * `local` cells are minted on first sight -- a read or a write -- so every
+ * later reference in either operation kind agrees. A cell a region owns is a
+ * file-scope variable instead, because the body that initializes it and the
+ * bodies that read it are different C++ functions: making it a local of the
+ * module body would put the value out of every other body's reach, and the
+ * program would compile with each function reading a name that does not exist.
+ */
+export const bindingReference = (ctx, declaration, what) => {
+    // A cell the frame's own formal already holds (`EmitContext.formalCells`).
+    // Answered before the placement is read, because the answer is not about
+    // storage this body allocates: there is none to allocate.
+    const formal = ctx.formalCells.get(declaration);
+    if (formal !== undefined)
+        return { name: formal, owned: false, boxed: false };
+    const placement = ctx.placements.get(declaration);
+    if (!placement) {
+        // The same fact `ir/certify.ts`'s `binding-read` case demands
+        // `native-boundary:external-binding` for -- a declaration this program
+        // never introduces, reachable only through an installed host protocol.
+        throw createCppEmitBlockedError('native-boundary:external-binding', `${what} names ${declaration}, which this program never introduces; an ambient or imported declaration needs an installed host protocol`);
+    }
+    if (placement.storage.kind === 'absent') {
+        // The unit defines this cell itself (`translation-unit.ts`), because no
+        // object file does. A read is an ordinary read of that global -- there is a
+        // real object, holding the only value it can hold.
+        return { name: cppGlobalName(declaration), owned: false, boxed: false };
+    }
+    if (placement.storage.kind === 'external') {
+        // A `native-handle` with no host-stated C++ type (`representation.native
+        // === null`) is the bare `gea::NativeHandle<Tag>` template -- opaque,
+        // zero-size, and interchangeable across every instance of the SAME
+        // protocol (`NativeHandle`'s own doc, gea_runtime.h; the reference-
+        // identity fold in `emit.ts` relies on exactly this). That is the shape
+        // of a language-builtin namespace/singleton reached purely by name --
+        // `Math`, `console`, `JSON` -- which every member access already
+        // resolves through the STATIC protocol name (`nativeHandleMemberText`),
+        // never through this cell's own bits. No file anywhere defines a real
+        // `Math`/`console`/... object for `translation-unit.ts`'s `extern` to
+        // link against (there is nothing to hold), so reading it as a bare VALUE
+        // -- `var m = Math` -- must not spell the linkage name as an expression:
+        // it names no C++ symbol and the linker has nothing to resolve it to. A
+        // fresh default-constructed handle is a sound substitute precisely
+        // because every instance of this protocol is equivalent by construction.
+        // A protocol WITH a host-stated native type keeps the raw linkage name:
+        // that one names a real object a host genuinely defines.
+        if (placement.representation?.kind === 'native-handle' && placement.representation.native === null) {
+            return { name: `${cppTypeOf(placement.representation)}{}`, owned: false, boxed: false };
+        }
+        // The host owns this cell; `translation-unit.ts` declares the matching
+        // `extern` once, by the same `linkageName`, and never a defining
+        // statement, so there is nothing here for this body to own either.
+        return { name: placement.storage.linkageName, owned: false, boxed: false };
+    }
+    if (placement.storage.kind === 'host-class') {
+        // A host's class object has no cell anywhere -- see `host-class` in
+        // `projection/bindings.ts`. Reaching here means something asked for its
+        // storage, and the honest answer is that there is none: the host spells
+        // what a program does WITH the class (construct it, read its class
+        // members) by naming the class outright, and a program that wants the
+        // class object itself as a value has no C++ to be handed.
+        throw createCppEmitBlockedError(`host-invocation:${placement.storage.linkageName}.value`, `${what} names ${declaration}, a host's class object; the host states spellings for constructing it and for its own ` +
+            `class members, and none for the class as a value`);
+    }
+    if (placement.storage.kind === 'host-function') {
+        // Reads register and render nothing (`emit-bindings.ts`), and the call
+        // renders the host's spelling, so reaching here is something else asking
+        // for the cell behind the name -- a write, most likely. A host's function
+        // has no cell to write through.
+        throw createCppEmitBlockedError(`host-invocation:${placement.storage.linkageName}.write`, `${what} names ${declaration}, a function this host defines; there is no cell behind it to write through`);
+    }
+    if (placement.storage.kind === 'host-constant') {
+        // Reads render the text directly (`emit-bindings.ts`) and never ask for a
+        // cell, so reaching here is a WRITE to one -- assigning to a host's
+        // constant, which has no storage to assign into.
+        throw createCppEmitBlockedError(`host-invocation:${placement.storage.linkageName}.write`, `${what} names ${declaration}, a constant this host states the value of; there is no cell behind it to write through`);
+    }
+    if (placement.storage.kind === 'host-namespace') {
+        // A namespace read registers its path and renders nothing
+        // (`emit-bindings.ts`), so reaching here is a WRITE through the name --
+        // assigning to `Display` itself. There is no object of that name at run
+        // time, so there is nothing to assign into.
+        throw createCppEmitBlockedError(`host-invocation:${placement.storage.linkageName}.write`, `${what} names ${declaration}, a namespace this host owns; it is a path to the host's spellings, not an object with a cell behind it`);
+    }
+    if (placement.storage.kind === 'host-singleton') {
+        // Same as a namespace, one step further in: a singleton read renders
+        // nothing and registers what it reached, so reaching here is a WRITE to
+        // `document` itself. The host holds the one instance; there is no cell of
+        // that name to assign into.
+        throw createCppEmitBlockedError(`host-invocation:${placement.storage.linkageName}.write`, `${what} names ${declaration}, an object this host holds the one instance of; it is reached by name, not through a cell`);
+    }
+    if (placement.storage.kind === 'region')
+        return { name: cppGlobalName(declaration), owned: false, boxed: false };
+    if (placement.storage.owner !== ctx.owner) {
+        const admission = ctx.captures.of(ctx.owner);
+        if (admission.kind === 'ok') {
+            const index = admission.layout.slots.findIndex((slot) => slot.declaration === declaration);
+            if (index >= 0) {
+                const slot = admission.layout.slots[index];
+                return { name: `${cppEnvironmentLocalName}->${cppCaptureFieldName(index)}`, owned: false, boxed: slot.boxed };
+            }
+        }
+        if (admission.kind === 'refused') {
+            throw createCppEmitBlockedError(`capture:${captureCapabilityOf(placement.representation ?? null)}`, `${what} names ${declaration}, a cell this function captures but cannot safely transport: ${admission.reason}`);
+        }
+        throw createCppEmitBlockedError(`capture:${captureCapabilityOf(placement.representation ?? null)}`, `${what} names ${declaration}, a cell owned by another callable frame; reading or writing it needs the capture path, which is not installed`);
+    }
+    const existing = ctx.bindingNames.get(declaration);
+    if (existing !== undefined)
+        return { name: existing, owned: true, boxed: ctx.captures.isBoxed(declaration) };
+    const name = `b${ctx.nextBindingOrdinal}`;
+    ctx.nextBindingOrdinal += 1;
+    ctx.bindingNames.set(declaration, name);
+    return { name, owned: true, boxed: ctx.captures.isBoxed(declaration) };
+};

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

@@ -0,0 +1,158 @@
+import type { BindingReadOperation, BindingWriteOperation, IrBody } from '../../ir/model.js';
+import type { DeclarationId, IrValueId } from '../../identity/ids.js';
+import type { BindingPlacement } from '../../projection/bindings.js';
+import { type EmitBodyPrepassFacts, type EmitContext } from './emit-context.js';
+/**
+ * The expression a boxed cell's handle reads as an ordinary value, versus the
+ * handle itself.
+ *
+ * `bindingReference` always names the cell's own storage -- a plain `T`
+ * variable, or a `std::shared_ptr<T>` handle when `CaptureSlot.boxed`/
+ * `CaptureIndex.isBoxed` says this declaration is shared by aliasing
+ * (`emit-callable.ts`'s field-copy line wants exactly that raw handle, to
+ * copy the pointer into a deeper environment unchanged). Every OTHER use of
+ * the cell -- a read, or the assignment target of a write -- wants the
+ * pointee, not the pointer, so those two call sites dereference here instead
+ * of inlining the same parenthesized `*` twice.
+ */
+export declare const cellValueText: (cell: {
+    readonly name: string;
+    readonly boxed: boolean;
+}) => string;
+/**
+ * Binding cells: the one place the plan's per-result carrier and the
+ * projection's per-declaration carrier have to be reconciled.
+ *
+ * They disagree routinely and legitimately -- control-flow narrowing makes a
+ * read narrower than its cell, and a declared union makes a cell wider than its
+ * initializer -- so both directions are written out here rather than left to
+ * C++ to interpret.
+ */
+/**
+ * Reading a binding is a load from its cell.
+ *
+ * The carrier the read publishes and the carrier the cell holds are decided by
+ * two different authorities -- the plan selects per result, the placement
+ * projects per declaration -- and control-flow narrowing routinely makes them
+ * disagree: inside `if (tag)` the checker types `tag` as `string`, so the
+ * read's carrier is `string`, while the cell still holds `Optional<string>`
+ * because that is what the declaration binds. `if (typeof x === 'string')` does
+ * the same to a cell holding a tagged union.
+ *
+ * Those loads exist and this renders them -- `gea::Optional::operator*`,
+ * `gea::TaggedUnion::get`. The proof is the checker's: it established presence,
+ * or which arm is live, before this read ever runs, and re-deciding it here
+ * would be a second authority answering a settled question with nowhere to go
+ * when it disagreed. What this file owns is whether the load exists at all, and
+ * it does not decide that either: `targets/cpp/conversions.ts` states the
+ * capability, preflight censuses it, and a program whose narrowed read has no
+ * installed load is refused before emission rather than here.
+ *
+ * Every other disagreement is still refused by name. A cell and a read that
+ * differ in a way no load explains are two unrelated C++ types, and emitting
+ * the bare assignment would hand the C++ compiler a program this one already
+ * knows is wrong.
+ */
+export declare const emitBindingRead: (ctx: EmitContext, lines: string[], operation: BindingReadOperation) => void;
+export declare const emitBindingWrite: (ctx: EmitContext, lines: string[], operation: BindingWriteOperation) => void;
+/**
+ * Allocates captured cells whose writes only initialize them along separate
+ * control-flow paths. No one branch write dominates the later closure
+ * allocation, so making the first rendered write allocate the handle makes
+ * C++ block order decide whether another branch sees a null `Ref`. The capture
+ * index carries the dominance proof; allocate only those cells at function
+ * entry and let every source write fill the already-shared pointee.
+ */
+export declare const earlyCapturedCellPrologue: (ctx: EmitContext, body: IrBody) => readonly string[];
+/**
+ * Which of this body's cells are a formal it already holds.
+ *
+ * A parameter's cell is seeded by one write whose value is the `parameter`
+ * operation itself, and where nothing writes it again the cell and the formal
+ * are the same value in two storages. Naming the formal removes the second --
+ * one `gea::Ref` retain/release, or one `std::string` heap copy, per call.
+ *
+ * Every condition here is a way the two could be different storages rather
+ * than a heuristic. More than one write means a later value the formal would
+ * not have. A boxed cell is shared with a closure this body cannot speak for.
+ * A cell some other frame owns is not this frame's formal at all. And a
+ * narrowed cell is a `long long` where its formal is a `double`, which is the
+ * one case where the C++ spellings genuinely disagree -- so they are compared,
+ * rather than assumed equal because the representations are.
+ */
+export declare const collectFormalCells: (ctx: EmitContext, prepass: EmitBodyPrepassFacts, body: IrBody) => void;
+/**
+ * A call result whose ONLY use is the binding write that immediately follows
+ * it, censused before anything renders.
+ *
+ * `s = JSON.stringify(v)` lowers to a call that mints a fresh `std::string`
+ * and a write that copies -- or moves -- that string into `s`'s cell. The
+ * string the call built is a heap buffer of the whole document, allocated on
+ * every call and freed on the next; a loop that stringifies the same value ten
+ * thousand times allocates and frees ten thousand buffers of the same size,
+ * when the cell already holds one big enough. Serializing straight INTO the
+ * cell reuses its capacity and skips the temporary entirely -- measured on the
+ * five stringify fixtures at 5.3% (number array) to 13.7% (records).
+ *
+ * Only the IMMEDIATELY following write qualifies, and only when the value has
+ * no other use: anything between the call and the write could read the cell,
+ * and the fill has already emptied it by then. A relocated result is excluded
+ * for the same reason -- a loop-invariant call renders in the preheader, which
+ * is not in front of the write at all.
+ *
+ * Who may act on it is `emit-json.ts`'s `jsonStringifyFillLines`; this only
+ * says which results are adjacent to their sink.
+ */
+export declare const collectDirectBindingSinks: (prepass: EmitBodyPrepassFacts, body: IrBody, relocated: ReadonlySet<IrValueId>) => void;
+/**
+ * Which SSA values ARE a PROGRAM class object that this program introduces no
+ * cell for.
+ *
+ * A class object becomes a cell through `bind-class-value` and the name
+ * binding minted beside it (`normalize/producers/class-lifecycle.ts`), and the
+ * census does not walk a generic declaration the program never instantiates
+ * (`normalize/census.ts`: "There is no such function in this program, so
+ * nothing is recorded for it"). A program can still NAME such a class -- a
+ * `ReadableStream` arm the checker types, never constructed, tested for with
+ * `body instanceof ReadableStream` -- and that read then names a declaration
+ * nothing introduced.
+ *
+ * Rendering nothing is the whole answer for that read, because every site that
+ * can use a program class spells it from the DECLARATION its carrier names
+ * rather than from a cell: `new C` goes through the class's construct
+ * convention, `C.m` through the static's own home, and `v instanceof C`
+ * through the hierarchy census's recipe -- `emit-instanceof.ts`'s
+ * `constructor-family` branch never renders this operand at all. Recorded
+ * rather than silently skipped so that a genuine VALUE use -- storing the
+ * class object, passing it -- refuses by name in `operandText` instead of
+ * crashing on a value no operation defined.
+ *
+ * Settled before anything renders, from two authorities' settled answers: the
+ * placement map and the read's own planned carrier.
+ */
+export declare const classObjectReadsOf: (body: IrBody, placements: ReadonlyMap<DeclarationId, BindingPlacement>) => ReadonlyMap<IrValueId, DeclarationId>;
+/**
+ * Which SSA values ARE a host class object or singleton rather than hold one.
+ *
+ * A host's class object produces no C++ at all: there is no cell to load from,
+ * and what the program does with the class -- constructs it, reads its class
+ * members -- is spelled whole by the host at the site that does it. A
+ * singleton is the same physical answer for the same reason. Both are
+ * recorded so a program that instead wants the class as a VALUE refuses by
+ * name (`operandText`) rather than naming a variable nothing declares, and so
+ * `emit-host-properties.ts` can tell a receiver that renders as text from one
+ * that renders as nothing at all.
+ *
+ * Settled before anything renders (invariant 5: no write during render).
+ * Every input is already an authority's answer: the seed is
+ * `BindingPlacement.storage`, which projection decided, and the three
+ * propagation steps carry that identity onto the SSA views a program makes of
+ * it -- a `convert` to a native handle, and a store threading its receiver
+ * onward. Nothing here asks a printer anything, which is why it was never a
+ * render-time write except by history.
+ */
+export declare const hostClassReadsOf: (body: IrBody, placements: ReadonlyMap<DeclarationId, BindingPlacement>) => ReadonlyMap<IrValueId, {
+    readonly kind: "class" | "singleton";
+    readonly declaration: DeclarationId;
+    readonly linkageName: string;
+}>;