@geastack/compiler 1.0.15

package/dist/ir/captures.js

@@ -0,0 +1,335 @@
+import { dominatorTreeOf, isVisible } from './dominance.js';
+const captureFactsOf = (body, placements) => {
+    const direct = [];
+    const allocates = [];
+    let ownReceiverUse = null;
+    const seen = new Set();
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        for (const operation of block.operations) {
+            if (operation.kind === 'allocate-callable') {
+                allocates.push(operation.functionId);
+                continue;
+            }
+            if (operation.kind === 'receiver') {
+                if (ownReceiverUse === null)
+                    ownReceiverUse = operation.result.representation;
+                continue;
+            }
+            if (operation.kind !== 'binding-read' && operation.kind !== 'binding-write')
+                continue;
+            const declaration = operation.declaration;
+            if (seen.has(declaration))
+                continue;
+            const placement = placements.get(declaration);
+            // No placement, `region`, or `external` storage are not this body's
+            // problem: `bindingReference` resolves all three without ever consulting
+            // a `CaptureIndex` (a missing declaration refuses by name, `region`
+            // storage is a file-scope global, `external` storage is host-defined).
+            // Only `local` storage owned by some *other* frame is the case this
+            // index exists for.
+            if (!placement || placement.storage.kind !== 'local' || placement.storage.owner === body.sourceOwner)
+                continue;
+            seen.add(declaration);
+            direct.push(declaration);
+        }
+    }
+    return { direct, allocates, declaresOwnReceiver: body.abi !== null && body.abi.receiver !== null, ownReceiverUse };
+};
+/**
+ * Every cell each body's environment has to carry -- its own captures AND the
+ * captures of every closure it allocates.
+ *
+ * A closure's environment is built in the frame that allocates it, one field
+ * per slot, each field read through `bindingReference` *in that frame*
+ * (`emitAllocateCallable`). So when `outer` allocates `inner`, and `inner`
+ * reads a cell that neither of them owns, `outer` has to be able to read it
+ * too -- and it can only do that out of its own environment. A layout built
+ * from one body's own reads alone leaves that cell out of `outer`'s
+ * environment, and the allocation of `inner` then refuses with "a cell owned by
+ * another callable frame ... not installed": a refusal naming the innermost
+ * frame for a gap one level up.
+ *
+ * A cell `outer` itself owns is deliberately NOT propagated: `outer` reads it
+ * as an ordinary local, so it needs no slot. That subtraction is also what
+ * makes the fixpoint terminate on a recursive nesting -- the set can only
+ * shrink as it moves outward.
+ *
+ * The receiver rides the identical relay: `receiverNeeds` seeds each body
+ * with the representation its OWN operations name (`null` for a body that
+ * declares its own receiver, since that body reads `this` as an ordinary
+ * parameter and needs no capture of it), then the same loop below inherits a
+ * nested closure's receiver need into whichever frame allocates it, stopping
+ * at the first frame that declares its own -- the receiver's counterpart to
+ * `ownsCell` above. Without this, a relay frame that never itself names
+ * `this` -- one that merely allocates a deeper closure which does -- gets no
+ * `receiver` in its own layout, and `emitAllocateCallable` then has nothing
+ * to read `this` out of when it builds that deeper closure's environment.
+ */
+const transitiveCaptures = (facts, placements) => {
+    const needs = new Map();
+    const receiverNeeds = new Map();
+    for (const [owner, body] of facts) {
+        needs.set(owner, [...body.direct]);
+        receiverNeeds.set(owner, body.declaresOwnReceiver ? null : body.ownReceiverUse);
+    }
+    const ownsCell = (owner, declaration) => {
+        const placement = placements.get(declaration);
+        return placement?.storage.kind === 'local' && placement.storage.owner === owner;
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [owner, body] of facts) {
+            const current = needs.get(owner);
+            if (!current)
+                continue;
+            const held = new Set(current);
+            const ownerDeclaresReceiver = body.declaresOwnReceiver;
+            for (const nested of body.allocates) {
+                for (const declaration of needs.get(nested) ?? []) {
+                    if (held.has(declaration) || ownsCell(owner, declaration))
+                        continue;
+                    held.add(declaration);
+                    current.push(declaration);
+                    changed = true;
+                }
+                if (!ownerDeclaresReceiver && receiverNeeds.get(owner) === null) {
+                    const nestedReceiver = receiverNeeds.get(nested);
+                    if (nestedReceiver !== null && nestedReceiver !== undefined) {
+                        receiverNeeds.set(owner, nestedReceiver);
+                        changed = true;
+                    }
+                }
+            }
+        }
+    }
+    return { needs, receiverNeeds };
+};
+const computeCaptureFacts = (bodies, placements, capturingAccessors) => {
+    const allocatedFunctionIds = new Set();
+    // `binding-write` fires once for a `const`/`let` declaration's own
+    // initializer *and* once per later reassignment (`ir/lower.ts`'s
+    // `lowerBinding` lowers `BindingOperation.action` `'write'` and
+    // `'initialize'` to the same IR kind, so the IR alone cannot tell them
+    // apart by kind). What distinguishes a reassignment from the one
+    // initializing write every declaration gets is arithmetic, not kind: a
+    // declaration this program ever reassigns has *more than one* write: the
+    // initializer plus at least one more. Counting is therefore the fact this
+    // module needs, not membership.
+    const writeCounts = new Map();
+    // The value each cell is written with, and which function each callable
+    // allocation names. Together they answer whether a cell holds a closure this
+    // program allocates, which is the fact `closureInitialized` below needs. A
+    // cell written more than once overwrites its entry, which never matters:
+    // `reassigned` refuses every such cell before the answer is consulted.
+    const writtenValues = new Map();
+    const allocatedFunctionOfValue = new Map();
+    for (const body of bodies) {
+        for (const blockId of body.blockOrder) {
+            const block = body.blocks.get(blockId);
+            if (!block)
+                continue;
+            for (const operation of block.operations) {
+                if (operation.kind === 'allocate-callable') {
+                    allocatedFunctionIds.add(operation.functionId);
+                    // An SSA id embeds the physical body it belongs to
+                    // (`identity/ids.ts`'s `irValueId`), so one whole-program map over
+                    // every body walked here is unambiguous without keying by body.
+                    allocatedFunctionOfValue.set(operation.result.id, operation.functionId);
+                }
+                else if (operation.kind === 'binding-write') {
+                    writeCounts.set(operation.declaration, (writeCounts.get(operation.declaration) ?? 0) + 1);
+                    writtenValues.set(operation.declaration, operation.value.value);
+                }
+            }
+        }
+    }
+    const reassigned = new Set();
+    for (const [declaration, count] of writeCounts) {
+        if (count > 1)
+            reassigned.add(declaration);
+    }
+    // Which cells hold a closure, and whose. Read off the write's own value
+    // rather than off the declaration's syntax, so a function declaration's
+    // hoisted cell and a named function expression's funcEnv cell -- the two
+    // forms in the language that name themselves -- are one case here.
+    const closureInitialized = new Map();
+    for (const [declaration, value] of writtenValues) {
+        const allocated = allocatedFunctionOfValue.get(value);
+        if (allocated !== undefined)
+            closureInitialized.set(declaration, allocated);
+    }
+    // Every body's facts, then the closure over them: a body that is never
+    // allocated as a callable still contributes, because a method's body may
+    // allocate a closure whose captures the enclosing frames have to carry.
+    const facts = new Map();
+    for (const body of bodies)
+        facts.set(body.sourceOwner, captureFactsOf(body, placements));
+    const { needs: captured, receiverNeeds } = transitiveCaptures(facts, placements);
+    // A closure can legally be created before a captured `let` receives its
+    // first value. The cell still exists at that point and initially holds
+    // `undefined`; subsequent writes must be visible through the closure's
+    // environment. Lowering omits a storage-free `let x;` initializer, so the
+    // program may contain only the later write. Counting that as a single write
+    // makes it look immutable even though copying it into the environment would
+    // either name no C++ local at all or preserve the initial value forever.
+    //
+    // Decide this from the same IR operations that build the capture index. For
+    // every allocation, an owning-frame write must be visible at that exact
+    // point before a value capture is safe. Dominance handles branch joins; the
+    // same-block position handles ordinary declaration order. Anything else
+    // needs the shared heap cell, just like a reassigned capture.
+    const capturedBeforeInitialization = new Set();
+    for (const body of bodies) {
+        const writes = new Map();
+        const allocations = [];
+        for (const blockId of body.blockOrder) {
+            const block = body.blocks.get(blockId);
+            if (!block)
+                continue;
+            block.operations.forEach((operation, position) => {
+                if (operation.kind === 'binding-write') {
+                    const sites = writes.get(operation.declaration) ?? [];
+                    sites.push({ block: blockId, position });
+                    writes.set(operation.declaration, sites);
+                }
+                else if (operation.kind === 'allocate-callable') {
+                    allocations.push({ functionId: operation.functionId, block: blockId, position });
+                }
+            });
+        }
+        if (allocations.length === 0)
+            continue;
+        const dominance = dominatorTreeOf(body);
+        for (const allocation of allocations) {
+            for (const declaration of captured.get(allocation.functionId) ?? []) {
+                const placement = placements.get(declaration);
+                if (placement?.storage.kind !== 'local' || placement.storage.owner !== body.sourceOwner)
+                    continue;
+                const initialized = (writes.get(declaration) ?? []).some((site) => isVisible(site, allocation.block, allocation.position, dominance));
+                if (!initialized)
+                    capturedBeforeInitialization.add(declaration);
+            }
+        }
+    }
+    // Every declaration this program must share by aliasing rather than by
+    // copying, decided once, whole-program, before any one body's admission
+    // runs -- see `IrBodyFacts.boxed`. Walked over every OWNER an allocated
+    // closure needs the declaration through (the direct capturer AND every
+    // frame that merely relays it to a deeper closure), not only the frame that
+    // directly reads or writes it: a relay frame that copied the raw value
+    // instead of the box would hand the closure it relays to a stale alias of
+    // its own, so the moment ANY owner along the chain needs the box, every
+    // owner touching the same declaration must agree it is boxed. `reassigned`
+    // is already owner-independent (the declaration is unsafe to copy full
+    // stop), and `closureInitialized.get(declaration) === owner` is checked
+    // per owner because self-reference is specifically "this owner's own
+    // closure holds this cell" -- but because the result lands in one flat,
+    // declaration-keyed set, a relay owner picks up a self-reference reason
+    // found through a DIFFERENT owner just as it would a `reassigned` one.
+    const boxed = new Set();
+    for (const [owner, declarations] of captured) {
+        // A record ACCESSOR is never allocated as a value -- it is reached by name
+        // off the shape -- and yet it does receive an environment, carried by the
+        // object itself (`targets/cpp/captures.ts`). So it needs the same boxing
+        // decision an allocated closure gets: without it the environment holds a
+        // COPY of the cell, and a setter's write is invisible to the next read of
+        // the getter beside it, which is a silently wrong answer rather than a
+        // refusal.
+        if (!allocatedFunctionIds.has(owner) && !capturingAccessors.has(owner))
+            continue;
+        for (const declaration of declarations) {
+            if (reassigned.has(declaration) || closureInitialized.get(declaration) === owner || capturedBeforeInitialization.has(declaration)) {
+                boxed.add(declaration);
+            }
+        }
+    }
+    // A body reads `this` when its own operations do, and also when a closure
+    // it allocates does without declaring a receiver of its own: an arrow's
+    // `this` is the enclosing method's, reached through the capture the index
+    // above already installs. Asking only the body's own operations would call
+    // `m() { return () => this.x }` receiver-free and hand its arrow nothing.
+    // Memoized against the allocation graph's own cycles (a body can allocate a
+    // closure that allocates it back), where an unfinished answer is `false`:
+    // the receiver-reading evidence is elsewhere in the cycle, or nowhere.
+    const receiverReaders = new Map();
+    const readsReceiver = (owner) => {
+        const known = receiverReaders.get(owner);
+        if (known !== undefined)
+            return known;
+        receiverReaders.set(owner, false);
+        const body = facts.get(owner);
+        const reads = body !== undefined &&
+            (body.ownReceiverUse !== null ||
+                body.allocates.some((nested) => facts.get(nested)?.declaresOwnReceiver === false && readsReceiver(nested)));
+        receiverReaders.set(owner, reads);
+        return reads;
+    };
+    return { needs: captured, receiverNeeds, allocatedFunctionIds, boxed, earlyBox: capturedBeforeInitialization, readsReceiver };
+};
+/**
+ * Runs `computeCaptureFacts` once over the whole program and attaches its
+ * answer to every body as `IrBody.facts`, the way `ir/generator-split.ts`
+ * rewrites bodies rather than handing back a side index the caller has to
+ * remember to thread everywhere it is needed.
+ *
+ * Called after `splitGeneratorBodies` and after `shakeProgram` -- the SAME
+ * body set `targets/cpp/translation-unit.ts` renders from -- because a body
+ * `shakeProgram` removes as dead must not still contribute a relay edge to
+ * `transitiveCaptures`'s fixpoint: computing this any earlier would let a
+ * capture route through a callable the emitted program never allocates,
+ * widening some surviving owner's environment past what the target's old,
+ * post-shake recomputation ever produced for it.
+ */
+export const publishCaptureFacts = (bodies, placements, 
+/**
+ * The accessor bodies a reachable record shape names
+ * (`projection/fields.ts`'s `recordAccessorBodiesOf`). An accessor is the one
+ * body kind that receives an environment without ever being allocated as a
+ * value, so it is the one kind this walk cannot recognise from the
+ * operations alone -- the shape names it, nothing allocates it.
+ */
+capturingAccessors = new Set()) => {
+    const bodyList = [...bodies.values()];
+    const facts = computeCaptureFacts(bodyList, placements, capturingAccessors);
+    // `boxed`/`earlyBox` are whole-program, declaration-keyed sets; regrouping
+    // them by the declaration's OWNING frame here, once, is what lets
+    // `IrBodyFacts.boxed` stay a per-body set without every reader repeating
+    // this same lookup against `placements`.
+    const boxedByOwner = new Map();
+    for (const declaration of facts.boxed) {
+        const placement = placements.get(declaration);
+        if (placement?.storage.kind !== 'local')
+            continue;
+        const owned = boxedByOwner.get(placement.storage.owner) ?? new Set();
+        owned.add(declaration);
+        boxedByOwner.set(placement.storage.owner, owned);
+    }
+    const earlyBoxByOwner = new Map();
+    for (const declaration of facts.earlyBox) {
+        const placement = placements.get(declaration);
+        if (placement?.storage.kind !== 'local')
+            continue;
+        const owned = earlyBoxByOwner.get(placement.storage.owner) ?? new Set();
+        owned.add(declaration);
+        earlyBoxByOwner.set(placement.storage.owner, owned);
+    }
+    const empty = new Set();
+    const published = new Map();
+    for (const body of bodyList) {
+        const owner = body.sourceOwner;
+        const bodyFacts = {
+            capturedDeclarations: facts.needs.get(owner) ?? [],
+            capturedReceiver: facts.receiverNeeds.get(owner) ?? null,
+            allocatedAsValue: facts.allocatedFunctionIds.has(owner),
+            readsReceiver: facts.readsReceiver(owner),
+            boxed: boxedByOwner.get(owner) ?? empty,
+            requiresEarlyBox: earlyBoxByOwner.get(owner) ?? empty
+        };
+        published.set(body.owner, { ...body, facts: bodyFacts });
+    }
+    return published;
+};

package/dist/ir/certificate.d.ts

@@ -0,0 +1,45 @@
+import type { TargetRuntimeManifest } from '../preflight/obligations.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import type { IrCertification } from './certify.js';
+/**
+ * The whole-pipeline capability certificate.
+ *
+ * A clean IR certification is the only thing emission is allowed to trust;
+ * the certificate is how that trust travels without re-running the census. It
+ * is bound to the exact frozen plan, semantic snapshot, and manifest objects
+ * the certification was computed against, plus the certification itself, by
+ * hashing each with `node:crypto` -- never by accepting a caller-supplied
+ * identity string. A caller cannot forge one by constructing an object with
+ * the right shape: the only way to produce a matching `id` is to hand this
+ * module the actual subjects and have it hash them itself.
+ *
+ * Lived in `preflight/` and hashed the preflight report until certification
+ * moved onto the lowered IR. The certificate now attests the IR walk,
+ * so it hashes the keys that walk demanded -- the census of what this program
+ * asks of the target -- rather than a prediction of them.
+ */
+export interface CapabilityCertificateSubjects {
+    readonly plan: SealedRepresentationPlan;
+    readonly semanticSnapshot: SemanticGraph;
+    readonly manifest: TargetRuntimeManifest;
+}
+export interface CapabilityCertificate {
+    readonly id: string;
+    readonly planDigest: string;
+    readonly semanticSnapshotDigest: string;
+    readonly manifestDigest: string;
+    readonly certificationDigest: string;
+}
+/**
+ * Mints a certificate from a clean certification, or returns `null` for one
+ * that refused anything.
+ *
+ * `null` rather than a throw: minting is a query ("is there a certificate for
+ * this state"), and a pipeline stage that does
+ * `const certificate = mintCapabilityCertificate(...); if (!certificate) ...`
+ * cannot forget the check the way a caught-and-discarded exception can be
+ * forgotten. The certificate gates emission only: lowering runs on the plan's
+ * own verdict.
+ */
+export declare const mintCapabilityCertificate: (certification: IrCertification, subjects: CapabilityCertificateSubjects) => CapabilityCertificate | null;

package/dist/ir/certificate.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+const sha256 = (input) => createHash('sha256').update(input, 'utf8').digest('hex');
+// The same digest as `sha256` over the concatenation, without ever holding
+// the concatenation: the demanded-key list of a large program need not fit in
+// one string.
+const sha256Lines = (lines) => {
+    const hash = createHash('sha256');
+    for (const line of lines)
+        hash.update(line, 'utf8');
+    return hash.digest('hex');
+};
+/**
+ * `Map`/`Set` are not JSON-serializable on their own; this replacer expands
+ * them structurally so the plan's `selected`/`evidence` maps and the graph's
+ * `operations`/`edges`/`results` tables actually contribute to the digest
+ * instead of silently vanishing into `{}`. Functions (`manifest.spellable`)
+ * are dropped by `JSON.stringify` as they always were; the predicate's
+ * answers are what the demanded keys already record.
+ */
+const canonicalize = (value) => JSON.stringify(value, (_key, val) => {
+    if (val instanceof Map)
+        return { __map__: [...val.entries()] };
+    if (val instanceof Set)
+        return { __set__: [...val.values()].sort() };
+    return val;
+});
+/**
+ * Mints a certificate from a clean certification, or returns `null` for one
+ * that refused anything.
+ *
+ * `null` rather than a throw: minting is a query ("is there a certificate for
+ * this state"), and a pipeline stage that does
+ * `const certificate = mintCapabilityCertificate(...); if (!certificate) ...`
+ * cannot forget the check the way a caught-and-discarded exception can be
+ * forgotten. The certificate gates emission only: lowering runs on the plan's
+ * own verdict.
+ */
+export const mintCapabilityCertificate = (certification, subjects) => {
+    if (!certification.certified)
+        return null;
+    const planDigest = sha256(canonicalize(subjects.plan));
+    const semanticSnapshotDigest = sha256(canonicalize(subjects.semanticSnapshot));
+    const manifestDigest = sha256(canonicalize(subjects.manifest));
+    const certificationDigest = sha256Lines(certification.demanded.map((key) => `${key}\n`));
+    const id = sha256([planDigest, semanticSnapshotDigest, manifestDigest, certificationDigest].join('|'));
+    return Object.freeze({ id, planDigest, semanticSnapshotDigest, manifestDigest, certificationDigest });
+};

package/dist/ir/certify/carrier-keys.d.ts

@@ -0,0 +1,73 @@
+import type { RepresentationDeriver } from '../../representation/derive.js';
+import { type Representation } from '../../representation/model.js';
+/**
+ * The pure `(kind, representation[, receiver][, deriver]) => string`
+ * refinements `preflight/runtime-helper-key.ts` used to compute a
+ * `protocol:*`/`allocation:regexp-object:*` carrier key from a SEMANTIC
+ * operand it first had to resolve through the plan. `ir/certify/runtime-helper.ts`
+ * needs the identical spellings for the LOWERED operand, which already
+ * carries its representation directly (`IrOperand.representation`) -- so the
+ * resolution half (operand -> representation, through the plan or the
+ * deriver) stays in `runtime-helper-key.ts`, and only the refinement half
+ * moves here, imported by both, so the two censuses cannot spell one carrier
+ * two different ways.
+ *
+ * Every function here takes `kind` as an explicit argument rather than
+ * deriving it from `representation.kind` internally, because the two are NOT
+ * always the same fact: a semantic operand whose own result exists but was
+ * never selected by the plan reports `kind === 'unselected'` while
+ * `representation` is `undefined` -- a real, distinct outcome from an
+ * operand that does not exist at all (`kind === 'absent'`), and both old
+ * skip-paths return `kind` verbatim in that case. Collapsing the two into
+ * one `representation?.kind ?? 'absent'` computation would silently turn
+ * "unselected" into "absent" and change what the old preflight walk
+ * certified. A lowered `IrOperand`'s representation is always resolved, so
+ * the IR side simply passes `representation.kind` for both arguments.
+ */
+/**
+ * `for`-`in`'s `get-iterator` step, refined the way a `native-record-ref`
+ * receiver (host-bound vs. compiler-owned) and a `dictionary`/`optional`
+ * receiver's own key domain must be to tell a claimed carrier from an
+ * identically-`.kind`ed one this backend cannot walk. See
+ * `preflight/runtime-helper-key.ts`'s own (much longer) doc for the full
+ * reasoning; this is that function's body, unchanged, parameterized by the
+ * representation directly instead of by a semantic operand.
+ */
+export declare const enumerateGetIteratorCarrierKeyOf: (kind: string, representation: Representation | undefined) => string;
+/**
+ * Whether a "record"/"record-with-index" carrier declares its OWN
+ * `[Symbol.iterator]` (or `[Symbol.asyncIterator]`) field -- see
+ * `preflight/runtime-helper-key.ts`'s own doc for the full reasoning
+ * (unchanged here; only moved).
+ */
+export declare const recordHasIteratorMethodField: (deriver: RepresentationDeriver, representation: Representation) => boolean;
+/**
+ * Whether a `record` is a TUPLE's carrier whose elements a single native
+ * cursor can walk -- see `preflight/runtime-helper-key.ts`'s own doc.
+ */
+export declare const isUniformTupleRecord: (representation: Representation) => boolean;
+/**
+ * The `iterator`/`async-iterator` protocol's `get-method`/`get-iterator`
+ * carrier -- see `preflight/runtime-helper-key.ts`'s own doc for the full
+ * reasoning behind the `record(no-iterator-method)`/`record(tuple-values)`
+ * split.
+ */
+export declare const iteratorMethodCarrierKeyOf: (kind: string, representation: Representation | undefined, deriver: RepresentationDeriver) => string;
+/**
+ * `CopyDataProperties`'s source carrier, refined the way a `dictionary`'s key
+ * domain, a `tagged-union`'s per-arm copyability, and an `optional`'s present
+ * payload have to be -- see `preflight/runtime-helper-key.ts`'s own (longer)
+ * doc for the full reasoning; this is that function's body, parameterized by
+ * the two representations directly instead of by a semantic operand pair.
+ */
+export declare const spreadSourceCarrierKeyOf: (kind: string, representation: Representation | undefined, receiver: Representation | undefined, deriver: RepresentationDeriver) => string;
+export type RegexpFlagSupportKey = 'supported-flags' | 'unicode-flags' | 'unicode-ignore-case-flags' | 'unicode-sets-flags';
+/**
+ * `u` selects the runtime's scalar-value matcher, while `v` stays unbuilt --
+ * see `preflight/runtime-helper-key.ts`'s own doc. Unlike that file's
+ * version, `flags` here is always a concrete string: by the time an
+ * `AllocateRegExpOperation` exists, lowering has already required its own
+ * `pattern-flags` operand to be a constant string (`lower-allocation.ts`'s
+ * `textOf`), so there is no `unselected-flags` state left to report.
+ */
+export declare const regexpFlagSupportKeyOf: (flags: string) => RegexpFlagSupportKey;