@geastack/compiler 1.0.15

package/dist/ir/absent-class-arm.js

@@ -0,0 +1,157 @@
+import { extendsClass } from '../projection/dispatch.js';
+import { classMemberOf } from '../projection/fields.js';
+import { canonicalIndexLiteral } from '../representation/array-index.js';
+import { objectPrototypeMemberNames } from '../representation/record-fields.js';
+/**
+ * A union read whose class arm has no such member at all.
+ *
+ * three asks `scene.background` -- a `Texture | Color` there -- for
+ * `isCubeTexture`, `mapping` and `colorSpace`; `Color` declares none of them.
+ * The reflection census used to require EVERY surface of the receiver to
+ * declare the key, so the lacking arm promoted both classes to a full dynamic
+ * protocol and the emitter read the `Color` arm through its expando table.
+ *
+ * In the language, reading a key an object neither owns nor inherits is
+ * `undefined`. For a class instance the inherited half is closed by its
+ * layouts: no class on the arm's chain declares the key, and neither does any
+ * class below it (a `class-ref` arm holds subclass instances too), and the key
+ * is not an `Object.prototype` member. The own half is what the reflection
+ * census exists to decide: every way a program can give an instance an own
+ * property its class does not declare -- a named or computed write, a
+ * definition, a spread target, an escape to `dynamic` or to an unknown call --
+ * promotes that class to a full protocol on its own. So the census does not
+ * promote for this read (`absentClassArmRead`), and once the exposure is
+ * closed, an arm whose class it still left without one provably answers
+ * `undefined` (`finalizeAbsentClassArms`). Where the class did end up full, the
+ * arm keeps the expando lookup, which is exact there.
+ *
+ * The result must hold that `undefined` natively, and its other values must be
+ * primitive: the fallback expando read hands back a box, and only a primitive
+ * payload unboxes without an object protocol the census did not publish.
+ */
+/** Whether a `class-ref(declaration)` value can own or inherit `key` by any declaration in the program. */
+export const classFamilyLacksKey = (classes, declaration, key) => {
+    if (objectPrototypeMemberNames.has(key) || key === '__proto__' || canonicalIndexLiteral(key) !== null)
+        return false;
+    // `unknown-class` is a site too: a chain the layouts cannot see is not closed.
+    if (classMemberOf(classes, declaration, key) !== null)
+        return false;
+    for (const [candidate, layout] of classes) {
+        if (candidate === declaration || !extendsClass(classes, candidate, declaration))
+            continue;
+        if (layout.fields.some((member) => member.key === key) ||
+            layout.methods.some((member) => member.key === key) ||
+            layout.accessors.some((member) => member.key === key))
+            return false;
+    }
+    return true;
+};
+const primitiveLeaf = (representation) => representation.kind === 'undefined' ||
+    representation.kind === 'null' ||
+    representation.kind === 'scalar' ||
+    representation.kind === 'string';
+/** A result that holds `undefined` without a box, and nothing but primitives otherwise. */
+const holdsAbsentPrimitive = (representation) => {
+    if (representation.kind === 'undefined')
+        return true;
+    if (representation.kind === 'optional')
+        return representation.absence === 'undefined' && primitiveLeaf(representation.payload);
+    if (representation.kind === 'tagged-union')
+        return representation.arms.some((arm) => arm.value.kind === 'undefined') && representation.arms.every((arm) => primitiveLeaf(arm.value));
+    return false;
+};
+/**
+ * The union a read dispatches over. A nullable union (`background &&` has not
+ * stripped the carrier) still selects among the same arms once present; its
+ * absent case is the read of a missing receiver, not of a class arm.
+ */
+const unionOf = (receiver) => {
+    if (receiver.kind === 'tagged-union')
+        return receiver;
+    if (receiver.kind === 'optional' && receiver.payload.kind === 'tagged-union')
+        return receiver.payload;
+    return null;
+};
+/** The census half: `surface` is a class arm of the union `receiver` that answers this read with `undefined`. */
+export const absentClassArmRead = (receiver, surface, key, result, classes) => surface.kind === 'class-ref' &&
+    (unionOf(receiver)?.arms.some((arm) => arm.value === surface) ?? false) &&
+    holdsAbsentPrimitive(result) &&
+    classFamilyLacksKey(classes, surface.declaration, key);
+/** A class the closed exposure left without a dynamic protocol. A class it never rowed is fail-closed full. */
+const withoutDynamicProtocol = (exposure, declaration) => {
+    const demand = exposure.classes.get(declaration);
+    return demand !== undefined && demand.level !== 'full';
+};
+/** The class arms of `operation` that provably answer `undefined` for `key`, in arm order. */
+const absentClassArmsOf = (operation, key, classes, exposure) => {
+    const receiver = operation.receiver.representation;
+    const union = unionOf(receiver);
+    if (union === null)
+        return [];
+    const arms = [];
+    for (const arm of union.arms) {
+        const surface = arm.value;
+        if (!absentClassArmRead(receiver, surface, key, operation.result.representation, classes))
+            continue;
+        if (withoutDynamicProtocol(exposure, surface.declaration) && !arms.includes(surface.declaration))
+            arms.push(surface.declaration);
+    }
+    return arms;
+};
+/** Certification's re-check of a published stamp against the same proof and the closed exposure. */
+export const absentClassArmsHold = (operation, key, classes, exposure) => {
+    const stamped = operation.absentClassArms ?? [];
+    if (key === null || !exposure?.complete || stamped.length === 0)
+        return false;
+    const proven = absentClassArmsOf(operation, key, classes, exposure);
+    return stamped.every((declaration) => proven.includes(declaration));
+};
+const constantsOf = (bodies) => {
+    const constants = new Map();
+    for (const body of bodies.values())
+        for (const block of body.blocks.values())
+            for (const operation of block.operations)
+                if (operation.kind === 'constant')
+                    constants.set(String(operation.result.id), operation);
+    return constants;
+};
+/**
+ * Stamp every union read with the class arms the CLOSED exposure proves absent.
+ * Runs after `closePhysicalClassReflection`: closure only ever adds a full
+ * protocol (to a full class's ancestors), and a subclass that could hold the
+ * key as an expando makes its ancestor full there, so the closed verdict on the
+ * arm's own class already covers every instance the arm can hold.
+ */
+export const finalizeAbsentClassArms = (bodies, exposure, classes) => {
+    if (!exposure.complete)
+        return bodies;
+    const constants = constantsOf(bodies);
+    const finalized = new Map();
+    let changedAny = false;
+    for (const [bodyId, body] of bodies) {
+        let changed = false;
+        const blocks = new Map(body.blocks);
+        for (const [blockId, block] of body.blocks) {
+            let blockChanged = false;
+            const operations = block.operations.map((operation) => {
+                if (operation.kind !== 'get' || unionOf(operation.receiver.representation) === null)
+                    return operation;
+                const constant = constants.get(String(operation.key.value));
+                if (!constant || constant.literal !== 'string')
+                    return operation;
+                const arms = absentClassArmsOf(operation, constant.text, classes, exposure);
+                if (arms.length === 0)
+                    return operation;
+                blockChanged = true;
+                changed = true;
+                return { ...operation, absentClassArms: arms };
+            });
+            if (blockChanged)
+                blocks.set(blockId, { ...block, operations });
+        }
+        if (changed)
+            changedAny = true;
+        finalized.set(bodyId, changed ? { ...body, blocks } : body);
+    }
+    return changedAny ? finalized : bodies;
+};

package/dist/ir/borrow-effects.d.ts

@@ -0,0 +1,23 @@
+import type { DeclarationId, FunctionId, IrValueId } from '../identity/ids.js';
+import type { Representation } from '../representation/model.js';
+import type { IrBody, IrNonTerminatorOperation } from './model.js';
+/** Operations that cannot mutate storage supplied by a caller, or re-enter
+ * program code that could. A typed-array element store changes its bytes,
+ * never the caller's handle/string slot. Accessors and coercing calls do not
+ * qualify. Local binding writes still need the owner's placement proof. */
+/**
+ * Whether reading `key` off a value carried as `receiver` is a plain data-field
+ * load: no accessor body to run, no host protocol, no dynamic table. The
+ * target answers this from its class layouts (`projection/fields.ts`'s
+ * `classMemberOf`); the IR alone cannot tell a field from a getter.
+ */
+export type PlainFieldRead = (receiver: Representation, key: string) => boolean;
+export declare const borrowSafeOperationsOf: (body: IrBody, safeCallees?: ReadonlySet<IrValueId>, plainFieldRead?: PlainFieldRead) => ReadonlySet<IrNonTerminatorOperation>;
+/** Compose the existing local effect proof through exact, noncapturing call
+ * targets. A field's speculative candidate is deliberately not an exact
+ * target. Unknown calls and recursive components without an established
+ * effect summary remain unproved. Admission only grows from proved leaves. */
+export declare const borrowEffectsOf: (bodies: readonly IrBody[], directBindings: ReadonlyMap<DeclarationId, FunctionId>, captureFree: (functionId: FunctionId) => boolean, synchronous: (body: IrBody) => boolean, privateWrite: (body: IrBody, declaration: DeclarationId) => boolean, plainFieldRead?: PlainFieldRead) => {
+    readonly operations: ReadonlyMap<string, ReadonlySet<IrNonTerminatorOperation>>;
+    readonly targets: ReadonlyMap<IrValueId, FunctionId>;
+};

package/dist/ir/borrow-effects.js

@@ -0,0 +1,151 @@
+import { stringConstantsOf } from './dead-values.js';
+import { operandsOfIrOperation } from './queries.js';
+const primitive = (value) => {
+    if (value.kind === 'optional')
+        return primitive(value.payload);
+    if (value.kind === 'tagged-union')
+        return value.arms.every((arm) => primitive(arm.value));
+    return ['scalar', 'string', 'null', 'undefined', 'symbol'].includes(value.kind);
+};
+const number = (value) => value.kind === 'scalar' && value.domain === 'number';
+export const borrowSafeOperationsOf = (body, safeCallees = new Set(), plainFieldRead = () => false) => {
+    const keys = stringConstantsOf(body);
+    const nativeCharacterReads = new Set();
+    const safe = new Set();
+    for (const block of body.blocks.values()) {
+        for (const operation of block.operations) {
+            if (operation.kind === 'get' && operation.receiver.representation.kind === 'string' && keys.get(operation.key.value) === 'charCodeAt')
+                nativeCharacterReads.add(operation.result.id);
+        }
+    }
+    for (const block of body.blocks.values()) {
+        for (const operation of block.operations) {
+            switch (operation.kind) {
+                case 'constant':
+                case 'binding-read':
+                case 'binding-write':
+                case 'parameter':
+                case 'receiver':
+                case 'phi':
+                case 'allocate-ordinary-object':
+                    safe.add(operation);
+                    break;
+                case 'compute':
+                    // These language primitives inspect a value without ToPrimitive or
+                    // user callbacks, even when its carrier is genuinely dynamic.
+                    if (operation.form === 'typeof' ||
+                        (operation.form === 'unary' && operation.operator === 'void') ||
+                        ((operation.form === 'equality' || operation.form === 'binary') &&
+                            (operation.operator === '===' || operation.operator === '!=='))) {
+                        safe.add(operation);
+                        break;
+                    }
+                    if (operandsOfIrOperation(operation).every((operand) => primitive(operand.representation)))
+                        safe.add(operation);
+                    break;
+                case 'convert':
+                case 'test':
+                    if (operandsOfIrOperation(operation).every((operand) => primitive(operand.representation)))
+                        safe.add(operation);
+                    break;
+                case 'get': {
+                    const receiver = operation.receiver.representation;
+                    const key = keys.get(operation.key.value);
+                    if ((receiver.kind === 'string' && (key === 'length' || key === 'charCodeAt')) ||
+                        (receiver.kind === 'typed-array' && (key === 'length' || number(operation.key.representation))))
+                        safe.add(operation);
+                    // A data field of a native object: `node.left` on a class instance
+                    // loads a member and runs nothing. Without this, no body that reads
+                    // a field of its parameter could borrow that parameter, so
+                    // `sum(node: TreeNode | null)` copied a `Ref` (retain, release, and
+                    // a cycle-candidate buffered) for every node it visited.
+                    else if (key !== undefined &&
+                        operation.hostMethod === undefined &&
+                        operation.reactive !== true &&
+                        operation.callableOwnPrototype !== true &&
+                        operation.typedComputedRead === undefined &&
+                        plainFieldRead(receiver.kind === 'optional' ? receiver.payload : receiver, key))
+                        safe.add(operation);
+                    break;
+                }
+                case 'set':
+                    if (operation.receiver.representation.kind === 'typed-array' &&
+                        number(operation.key.representation) &&
+                        number(operation.value.representation))
+                        safe.add(operation);
+                    break;
+                case 'call':
+                    if (safeCallees.has(operation.callee.value) ||
+                        (nativeCharacterReads.has(operation.callee.value) &&
+                            operation.arguments.length === 1 &&
+                            operation.arguments.every((argument) => number(argument.representation))))
+                        safe.add(operation);
+                    break;
+            }
+        }
+    }
+    return safe;
+};
+/** Compose the existing local effect proof through exact, noncapturing call
+ * targets. A field's speculative candidate is deliberately not an exact
+ * target. Unknown calls and recursive components without an established
+ * effect summary remain unproved. Admission only grows from proved leaves. */
+export const borrowEffectsOf = (bodies, directBindings, captureFree, synchronous, privateWrite, plainFieldRead = () => false) => {
+    // One source function may own several physical bodies (for example after
+    // generator splitting). An effect-free fragment must never authorize a
+    // call into its effectful sibling. Until summaries cover the whole family,
+    // only owners with a single physical body can publish a call summary.
+    const owners = new Set();
+    const splitOwners = new Set();
+    for (const body of bodies) {
+        const owner = String(body.sourceOwner);
+        if (owners.has(owner))
+            splitOwners.add(owner);
+        owners.add(owner);
+    }
+    const targets = new Map();
+    for (const body of bodies)
+        for (const block of body.blocks.values())
+            for (const operation of block.operations) {
+                if (operation.kind === 'allocate-callable' && captureFree(operation.functionId))
+                    targets.set(operation.result.id, operation.functionId);
+                if (operation.kind === 'binding-read') {
+                    const target = directBindings.get(operation.declaration);
+                    if (target !== undefined)
+                        targets.set(operation.result.id, target);
+                }
+            }
+    const proven = new Set();
+    const operations = new Map();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const safeCallees = new Set([...targets].filter(([, target]) => proven.has(String(target))).map(([value]) => value));
+        for (const body of bodies) {
+            const owner = String(body.sourceOwner);
+            if (proven.has(owner) || splitOwners.has(owner))
+                continue;
+            // A body's calls to ITSELF are assumed safe while proving it: if every
+            // other operation is safe, the recursion only re-runs safe operations
+            // (induction on depth). A monotone fixed point starting from nothing
+            // could never prove a recursive body otherwise -- `sum(node)` calling
+            // `sum(node.left)` stayed unproved forever. The assumption is kept only
+            // when the proof succeeds; an unproved body publishes the safe set
+            // computed without it, so nothing downstream inherits the optimism.
+            const selfCalls = new Set();
+            for (const [value, target] of targets)
+                if (String(target) === owner && !safeCallees.has(value))
+                    selfCalls.add(value);
+            const optimistic = selfCalls.size === 0 ? safeCallees : new Set([...safeCallees, ...selfCalls]);
+            const safe = borrowSafeOperationsOf(body, optimistic, plainFieldRead);
+            const qualifies = synchronous(body) &&
+                [...body.blocks.values()].every((block) => block.operations.every((operation) => safe.has(operation) && (operation.kind !== 'binding-write' || privateWrite(body, operation.declaration))));
+            operations.set(owner, qualifies || selfCalls.size === 0 ? safe : borrowSafeOperationsOf(body, safeCallees, plainFieldRead));
+            if (!qualifies)
+                continue;
+            proven.add(owner);
+            changed = true;
+        }
+    }
+    return { operations, targets };
+};

package/dist/ir/borrowed-call-arguments.d.ts

@@ -0,0 +1,40 @@
+import type { DeclarationId, IrValueId } from '../identity/ids.js';
+import { type Representation } from '../representation/model.js';
+import type { IrBody } from './model.js';
+/** A private cell is owned by this invocation and cannot be assigned through
+ * a closure, global, object property, or host alias. The caller supplies the
+ * binding-placement/capture authority and its physical carrier, or null when
+ * the cell is not private. Being spelled `const` is not proof. */
+export type PrivateBorrowCell = (declaration: DeclarationId) => Representation | null;
+/** Formal positions whose physical body cell can stay a reference. This is
+ * only a READ-ONLY proof, not an admission to borrow an arbitrary actual.
+ * An effectful body needs a stable caller-owned actual or an owning entry
+ * wrapper. Coroutine frames must never use these references across suspension.
+ *
+ * Keep the formal-cell elision contract: one same-carrier seed into a private
+ * cell. Modified/captured/converted formal cells retain the owning convention.
+ * No callee purity is assumed; mutation of a referent is distinct from mutation
+ * of the native string/handle slot containing that referent. */
+export declare const readonlyBorrowFormalsOf: (body: IrBody, privateCell: PrivateBorrowCell, dyingArguments: ReadonlySet<IrValueId>) => ReadonlySet<number>;
+/** Actuals immune to writes made by an invoked function or its callbacks.
+ *
+ * This is about the SLOT, not deep immutability: a private Ref<Array> keeps its
+ * identity while the callee changes array elements, exactly as passing that
+ * reference by value does. An object field containing the Ref is not private.
+ *
+ * Parameter actuals are safe only under the entry contract: their body either
+ * owns them or was itself entered with a stable borrow. An owning ABI wrapper
+ * closes this induction at every external/unknown call. These facts must not
+ * be used to change that ABI or admit an unguarded external borrowed entry.
+ * A receiver actual is under the identical contract -- a method's `this` is
+ * always either owned by its allocation or borrowed from its own caller under
+ * this same induction -- so it is admitted on the same terms as a parameter.
+ *
+ * Deliberately exclude property reads, conversions and call results: an emitter
+ * may defer them as a reference into mutable storage. A future materialization
+ * proof may admit them; the source representation alone cannot do so.
+ *
+ * The consumer must also exclude a call whose other owning arguments can MOVE
+ * one of these slots during argument evaluation. Const-reference binding itself
+ * does not move, even if the operand is spelled std::move by last-use analysis. */
+export declare const stableBorrowActualsOf: (body: IrBody, privateCell: PrivateBorrowCell) => ReadonlySet<IrValueId>;

package/dist/ir/borrowed-call-arguments.js

@@ -0,0 +1,117 @@
+import { representationKey } from '../representation/model.js';
+/** Formal positions whose physical body cell can stay a reference. This is
+ * only a READ-ONLY proof, not an admission to borrow an arbitrary actual.
+ * An effectful body needs a stable caller-owned actual or an owning entry
+ * wrapper. Coroutine frames must never use these references across suspension.
+ *
+ * Keep the formal-cell elision contract: one same-carrier seed into a private
+ * cell. Modified/captured/converted formal cells retain the owning convention.
+ * No callee purity is assumed; mutation of a referent is distinct from mutation
+ * of the native string/handle slot containing that referent. */
+export const readonlyBorrowFormalsOf = (body, privateCell, dyingArguments) => {
+    const result = new Set();
+    if (!body.abi)
+        return result;
+    const parameters = new Map();
+    const writes = new Map();
+    const reads = new Map();
+    for (const block of body.blocks.values())
+        for (const operation of block.operations) {
+            if (operation.kind === 'parameter')
+                parameters.set(operation.result.id, operation.ordinal);
+            if (operation.kind === 'binding-write') {
+                const entries = writes.get(operation.declaration) ?? [];
+                entries.push({ value: operation.value.value, carrier: representationKey(operation.value.representation) });
+                writes.set(operation.declaration, entries);
+            }
+            if (operation.kind === 'binding-read') {
+                const entries = reads.get(operation.declaration) ?? [];
+                entries.push(operation.result.id);
+                reads.set(operation.declaration, entries);
+            }
+        }
+    for (const [value, ordinal] of parameters) {
+        const parameter = body.abi.parameters[ordinal];
+        if (!parameter || parameter.ownership === 'borrowed')
+            continue;
+        let allowed = true;
+        for (const [declaration, entries] of writes) {
+            if (!entries.some((entry) => entry.value === value))
+                continue;
+            const cell = privateCell(declaration);
+            if (cell === null ||
+                representationKey(cell) !== representationKey(parameter.value) ||
+                entries.length !== 1 ||
+                entries[0]?.carrier !== representationKey(parameter.value)) {
+                allowed = false;
+                break;
+            }
+            // A formal already proven to DIE into a consuming use is not merely
+            // unsafe to alias -- making it `const&` silently downgrades the move
+            // that use was built on. `box.label = text` resolves `gea_arg_0->label
+            // = std::move(gea_arg_1)` to the COPY assignment when `gea_arg_1` is a
+            // `const&`, with no diagnostic anywhere. `ir/transfer.ts`'s
+            // `buildDyingArgumentIndex` is the one authority on which values die,
+            // checked here against this formal's own READS of its seeded cell --
+            // never the raw incoming parameter value itself. That raw value always
+            // has exactly one reader, the seed write the formal-cell elision
+            // contract requires, so `buildDyingArgumentIndex` always reports it as
+            // dying into that write; asking about the PARAMETER refused every
+            // formal unconditionally (`readonly` came back empty for every body
+            // whose whole-body proof needed this weaker one), not just the ones
+            // that alias into a consuming use. The stronger `program-facts.ts`
+            // proof (`borrowedFormalsOf`) has always asked this same question the
+            // same way, against the cell's reads, not the parameter's own value.
+            if ((reads.get(declaration) ?? []).some((read) => dyingArguments.has(read))) {
+                allowed = false;
+                break;
+            }
+        }
+        if (allowed)
+            result.add(ordinal);
+    }
+    return result;
+};
+/** Actuals immune to writes made by an invoked function or its callbacks.
+ *
+ * This is about the SLOT, not deep immutability: a private Ref<Array> keeps its
+ * identity while the callee changes array elements, exactly as passing that
+ * reference by value does. An object field containing the Ref is not private.
+ *
+ * Parameter actuals are safe only under the entry contract: their body either
+ * owns them or was itself entered with a stable borrow. An owning ABI wrapper
+ * closes this induction at every external/unknown call. These facts must not
+ * be used to change that ABI or admit an unguarded external borrowed entry.
+ * A receiver actual is under the identical contract -- a method's `this` is
+ * always either owned by its allocation or borrowed from its own caller under
+ * this same induction -- so it is admitted on the same terms as a parameter.
+ *
+ * Deliberately exclude property reads, conversions and call results: an emitter
+ * may defer them as a reference into mutable storage. A future materialization
+ * proof may admit them; the source representation alone cannot do so.
+ *
+ * The consumer must also exclude a call whose other owning arguments can MOVE
+ * one of these slots during argument evaluation. Const-reference binding itself
+ * does not move, even if the operand is spelled std::move by last-use analysis. */
+export const stableBorrowActualsOf = (body, privateCell) => {
+    const result = new Set();
+    for (const block of body.blocks.values())
+        for (const operation of block.operations) {
+            if (operation.kind === 'parameter')
+                result.add(operation.result.id);
+            if (operation.kind === 'constant')
+                result.add(operation.result.id);
+            if (operation.kind === 'binding-read' && privateCell(operation.declaration) !== null)
+                result.add(operation.result.id);
+            // `this` is under the same entry contract as a parameter: THIS body was
+            // entered with it already owned or already borrowed by its own caller,
+            // so it stays alive for this body's whole execution, including any call
+            // this body makes. Forwarding `this` on to another call is exactly the
+            // `helper(this)` shape a method body written across several small
+            // methods takes constantly, and none of that shape could ever borrow
+            // without this: `this` is a reference, never a parameter/binding-read.
+            if (operation.kind === 'receiver')
+                result.add(operation.result.id);
+        }
+    return result;
+};