@geastack/compiler 1.0.15

package/dist/projection/instance-test.js

@@ -0,0 +1,156 @@
+import { extendsClass } from './dispatch.js';
+/** Authenticated constructor protocols map to native payload identities here. */
+export const typedArrayConstructorDomains = new Map([
+    ['Int8ArrayConstructor', 'int8'],
+    ['Uint8ArrayConstructor', 'uint8'],
+    ['Uint8ClampedArrayConstructor', 'uint8-clamped'],
+    ['Int16ArrayConstructor', 'int16'],
+    ['Uint16ArrayConstructor', 'uint16'],
+    ['Int32ArrayConstructor', 'int32'],
+    ['Uint32ArrayConstructor', 'uint32'],
+    ['Float32ArrayConstructor', 'float32'],
+    ['Float64ArrayConstructor', 'float64']
+]);
+/** The object carriers a class instance can be converted into while losing its class (`targets/cpp/conversions.ts`'s record view). */
+export const classViewCarrierKinds = new Set([
+    'record',
+    'record-with-index',
+    'native-record-ref',
+    'dictionary'
+]);
+export const noClassPrototypes = { prototypeOf: null, materialized: new Set(), viewed: new Set() };
+/** A carrier that can hold only a primitive, never an Object. */
+const nonObjectTargetOf = (right) => {
+    switch (right.kind) {
+        case 'undefined':
+        case 'null':
+        case 'string':
+        case 'symbol':
+            return right.kind;
+        case 'scalar':
+            return right.domain === 'boolean' || right.domain === 'bigint' ? right.domain : 'number';
+        default:
+            return null;
+    }
+};
+export const classInstanceTestOf = (left, right, classes, prototypes) => {
+    // The throw precedes every read of the left operand, whatever it carries.
+    const nonObject = nonObjectTargetOf(right);
+    if (nonObject !== null)
+        return { test: { kind: 'throws-non-object', target: nonObject }, nativeFieldProtocol: 'unused' };
+    if (right.kind === 'native-handle') {
+        const domain = typedArrayConstructorDomains.get(right.protocol);
+        if (domain !== undefined)
+            return typedArrayInstanceTestOf(left, domain);
+    }
+    if (right.kind !== 'constructor-family')
+        return undefined;
+    const belongs = (declaration, members) => members.some((member) => declaration === member || extendsClass(classes, declaration, member));
+    const extension = [...classes.keys()].filter((declaration) => belongs(declaration, right.members));
+    const strictlyBelow = (declaration) => right.members.some((member) => extendsClass(classes, declaration, member));
+    if (prototypes.prototypeOf !== null)
+        return { test: { kind: 'constant', value: strictlyBelow(prototypes.prototypeOf) }, nativeFieldProtocol: 'unused' };
+    // A layout test answers `belongs` for D's prototype object and the language
+    // answers `strictlyBelow`: they disagree exactly for the prototype of a
+    // member that extends no other member.
+    const misanswered = [...prototypes.materialized].filter((declaration) => right.members.includes(declaration) && !strictlyBelow(declaration));
+    const mayHoldMisanswered = (declaration) => misanswered.some((prototype) => prototype === declaration || extendsClass(classes, prototype, declaration));
+    // A view carrier holds a family member only if some instance of it exists
+    // and was converted into a view -- through its own class-ref or through an
+    // ancestor's, which may hold it. A prototype object may be viewed as well.
+    const mayBeViewed = () => {
+        const viewed = prototypes.viewed;
+        if (viewed === undefined)
+            return true;
+        // A materialized prototype travels as its class's own class-ref, so a
+        // view of it is a view the census already counted for that class.
+        return extension.some((member) => (prototypes.materialized.has(member) || !classes.get(member)?.uninstantiable) &&
+            (viewed.has(member) || [...viewed].some((holder) => extendsClass(classes, member, holder))));
+    };
+    let native = true;
+    let refused = false;
+    const plan = (value) => {
+        if (value.kind === 'class-ref') {
+            if (belongs(value.declaration, right.members)) {
+                if (!mayHoldMisanswered(value.declaration))
+                    return value.ownership === 'shared-refcount' ? { kind: 'present' } : { kind: 'constant', value: true };
+                // `instanceOfClassFamilyRef` tells a prototype object from an instance
+                // by its method state and walks the prototype's own chain, over the
+                // whole family: the prototype's ancestors may be members themselves.
+                if (value.ownership === 'shared-refcount')
+                    return { kind: 'class-family', members: extension, boxed: false };
+                refused = true;
+                return { kind: 'constant', value: false };
+            }
+            // No ancestor of a class outside the family is in it, so the runtime
+            // chain walk over these descendants answers prototypes exactly too.
+            const members = extension.filter((candidate) => belongs(candidate, [value.declaration]));
+            return members.length === 0 ? { kind: 'constant', value: false } : { kind: 'class-family', members, boxed: false };
+        }
+        if (value.kind === 'dynamic') {
+            native = false;
+            // `instanceOfClassFamily` re-reads a boxed member at its own class and
+            // tells its prototype object from an instance, as the handle test does.
+            return { kind: 'class-family', members: extension, boxed: true };
+        }
+        if (value.kind === 'optional')
+            return { kind: 'optional', payload: plan(value.payload) };
+        // A view of a family member would answer `false` for a `true` value. An
+        // unknown view census proves nothing, so it refuses too.
+        if (classViewCarrierKinds.has(value.kind) && mayBeViewed()) {
+            // Only a shared view has an identity to remember its origin under; the
+            // origin is tested as a box, which tells a prototype object apart.
+            const shared = 'ownership' in value && value.ownership === 'shared-refcount' && value.kind !== 'dictionary';
+            if (!shared) {
+                refused = true;
+                return { kind: 'constant', value: false };
+            }
+            native = false;
+            return { kind: 'view-origin', members: extension };
+        }
+        if (value.kind === 'tagged-union') {
+            const arms = value.arms.flatMap((arm, index) => {
+                if (arm.value.kind === 'class-ref' ||
+                    arm.value.kind === 'optional' ||
+                    arm.value.kind === 'tagged-union' ||
+                    arm.value.kind === 'dynamic')
+                    return [{ index, test: plan(arm.value) }];
+                if (classViewCarrierKinds.has(arm.value.kind)) {
+                    const test = plan(arm.value);
+                    return test.kind === 'view-origin' ? [{ index, test }] : [];
+                }
+                return [];
+            });
+            return { kind: 'union', arms };
+        }
+        return { kind: 'constant', value: false };
+    };
+    const test = plan(left);
+    if (refused)
+        return undefined;
+    return { test, ...(native ? { nativeFieldProtocol: 'unused' } : {}) };
+};
+/** Nested sums retain their discriminant path; an enclosing sum is not an incompatible leaf. */
+const typedArrayInstanceTestOf = (left, domain) => {
+    let native = true;
+    const plan = (value) => {
+        if (value.kind === 'typed-array')
+            return value.element === domain ? { kind: 'present' } : { kind: 'constant', value: false };
+        if (value.kind === 'dynamic') {
+            native = false;
+            return { kind: 'boxed-typed-array', domain };
+        }
+        if (value.kind === 'optional')
+            return { kind: 'optional', payload: plan(value.payload) };
+        if (value.kind === 'tagged-union') {
+            const arms = value.arms.flatMap((arm, index) => {
+                const test = plan(arm.value);
+                return test.kind === 'constant' && !test.value ? [] : [{ index, test }];
+            });
+            return { kind: 'union', arms };
+        }
+        return { kind: 'constant', value: false };
+    };
+    const test = plan(left);
+    return { test, ...(native ? { nativeFieldProtocol: 'unused' } : {}) };
+};

package/dist/projection/slots.d.ts

@@ -0,0 +1,146 @@
+import type { DeclarationId, FunctionId, SemanticResultId } from '../identity/ids.js';
+import type { HostMemberTable } from '../targets/cpp/host/host-members.js';
+import type { RepresentationDeriver } from '../representation/derive.js';
+import { type CallableAbi, type Representation } from '../representation/model.js';
+import type { CoercionOperation } from '../conversion/algebra.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import { type SemanticOperand } from '../semantics/model/operands.js';
+import type { SemanticOperation } from '../semantics/model/operations.js';
+import type { BindingPlacement } from './bindings.js';
+import { type ClassLayout } from './classes.js';
+/**
+ * The slot census: for every operand of every operation, which carrier the
+ * consumer requires the value to arrive in.
+ *
+ * This is the one authority over "does this position need a conversion".
+ * Lowering asks it before it builds an IR operation and emits an explicit
+ * `convert` when the operand's carrier differs from the slot's; the verifier
+ * asks it again over the finished body and refuses any operand whose carrier
+ * is not its slot's. Nothing downstream re-derives the answer.
+ *
+ * Every position is one of three things, and the third is a defect:
+ *
+ * - a `slot`: the position stores the value somewhere with a carrier of its
+ *   own -- a formal, a receiver, a body's result, a cell, a record field, an
+ *   array element, a merge -- and the value must arrive in that carrier;
+ * - `raw`: the position reads the value AS ITSELF and never materializes it
+ *   into another carrier -- a callee, a key, a condition, a compute operand
+ *   -- so no conversion belongs there at all, by construction of the
+ *   consumer, under one of the closed `RawRole` names below;
+ * - `unclassified`: the census has no answer, which fails closed. The corpus
+ *   gate (`scripts/slot-census.mjs`) requires zero of these on every program
+ *   that certifies.
+ *
+ * A plugin that lowers an operation of its own answers for that operation's
+ * operands through `SlotHook`, consulted first; it is the same seam the
+ * plugin's `lower` hook already is, asked one stage earlier.
+ */
+/**
+ * The closed list of reasons a position takes its operand raw. Adding a
+ * consumer that reads a value as itself means adding its reason here, where
+ * the gate can see it, not returning `raw` under an existing name that does
+ * not describe it.
+ */
+export type RawRole = 
+/** The value being called or constructed; dispatched on its own carrier. */
+'callee'
+/** The object a member access, `in`, protocol step, or pattern step reads through. */
+ | 'receiver'
+/** A property, element, or pattern key. */
+ | 'key'
+/** A truthiness/presence test or a switch discriminant: read per carrier, never stored. */
+ | 'condition'
+/** An operand of a compute primitive; the primitive itself is chosen per carrier (`computeSlotsOf`, phase 1.5). */
+ | 'compute-operand'
+/** Evaluation provenance only: the consumer aliases or ignores the value and never reads it as a slot. */
+ | 'provenance'
+/** Source text a producer carries as a constant: template chunks, regexp source, intrinsic tag names. */
+ | 'constant-text'
+/** A whole source range copied into a rest or literal; its ELEMENTS convert, the range itself does not. */
+ | 'spread-range'
+/** A captured cell moved into a callable's environment as the cell's own carrier. */
+ | 'capture'
+/** A method/accessor allocation recorded into a class layout, never stored as a value. */
+ | 'method-allocation'
+/** A class heritage expression, evaluated for its constructor identity. */
+ | 'heritage'
+/** An iterator record or cursor stepped or closed in place. */
+ | 'iterator-record'
+/** The `@@iterator` method a `get-iterator` step invokes. */
+ | 'protocol-method'
+/** A value handed to a host entry point that dispatches on the C++ type itself (`String(x)`, a JSX prop, a child). */
+ | 'host-overload'
+/** A spread source whose entries are reconciled one by one into the receiver. */
+ | 'spread-source'
+/** A value the consumer evaluates and then drops: an extra argument past a fixed arity, a comma's non-final operand. */
+ | 'discarded'
+/** An argument to a call over a generic function set, remapped per dispatched member. */
+ | 'dispatch-argument'
+/** An operand the producer marks absent. */
+ | 'absent';
+/** Where a slot's carrier came from, so a refusal can name the structure that states it. */
+export type SlotSource = 'formal' | 'receiver' | 'result' | 'cell' | 'field' | 'static-field' | 'element' | 'phi' | 'thrown' | 'yield' | 'resume' | 'alias' | 'dynamic';
+export type SlotAnswer = {
+    readonly kind: 'slot';
+    readonly representation: Representation;
+    readonly source: SlotSource;
+} | {
+    readonly kind: 'raw';
+    readonly role: RawRole;
+}
+/**
+ * The position runs an ECMAScript abstract operation on the value before
+ * its consumer reads it: a mixed-carrier binary operator's operand goes
+ * through ToNumber or ToString (13.15.3 ApplyStringOrNumericBinaryOperator,
+ * 7.2.13 IsLessThan) and the operator then runs over two operands in ONE
+ * carrier. Not a `slot`: the conversion is the operation, not a store into
+ * `representation` -- `string` into `scalar(number)` as a store is an exact
+ * tag read that refuses `"3"`; as ToNumber it yields `3`. The census
+ * (`conversion/nodes.ts`'s `coercionFor`) keys the node on the operation.
+ */
+ | {
+    readonly kind: 'coerce';
+    readonly operation: CoercionOperation;
+    readonly representation: Representation;
+} | {
+    readonly kind: 'unclassified';
+    readonly reason: string;
+};
+export type SlotHook = (census: SlotCensus, operation: SemanticOperation, operand: SemanticOperand) => SlotAnswer | null;
+export interface SlotCensusInput {
+    readonly graph: SemanticGraph;
+    readonly plan: SealedRepresentationPlan;
+    readonly deriver: RepresentationDeriver;
+    readonly abis: ReadonlyMap<FunctionId, CallableAbi>;
+    readonly constructs: ReadonlyMap<FunctionId, CallableAbi>;
+    readonly callableOrigins: ReadonlyMap<SemanticResultId, FunctionId>;
+    readonly classes: ReadonlyMap<DeclarationId, ClassLayout>;
+    readonly placements: ReadonlyMap<DeclarationId, BindingPlacement>;
+    /** Declarations that hold one host method forever -- see `projection/callee.ts`'s `hostMethodAliasDeclarations`. */
+    readonly hostMethodAliasDeclarations: ReadonlySet<DeclarationId>;
+    readonly hostMembers?: HostMemberTable;
+    readonly slotHooks?: readonly SlotHook[];
+}
+export interface SlotCensus {
+    readonly input: SlotCensusInput;
+    readonly slotOf: (operation: SemanticOperation, operand: SemanticOperand) => SlotAnswer;
+    /** The carrier an operand arrives in, before any conversion: the plan's, the frame's, or a constant's. */
+    readonly carrierOf: (operation: SemanticOperation, operand: SemanticOperand) => Representation | null;
+    /**
+     * The carrier of the value that actually ENTERS an operand's slot. For all
+     * but one operand that is `carrierOf`; the exception is a class field's
+     * `initializer`, which the frontend publishes as a thunk (`() => T` with
+     * the class as `this`) that lowering and the printer both CALL before
+     * storing -- `ir/lower.ts`'s `lowerClassLifecycle` for a static field,
+     * `class-layout.ts`'s `cppFieldInitializerStatements` for an instance
+     * one. The thunk's result is what the field receives, so the conversion
+     * the slot needs is result-into-field, never thunk-into-field.
+     */
+    readonly enteringCarrierOf: (operation: SemanticOperation, operand: SemanticOperand) => Representation | null;
+    /** The slot a store into a layout's named member fills: its declared field, or its setter's formal. */
+    readonly fieldSlot: (receiver: Representation, key: string) => SlotAnswer;
+}
+/** The formal a physical argument position fills, with the rest tail unpacked to its element or tuple field. */
+export declare const callArgumentSlotOf: (abi: CallableAbi | null, callee: Representation | null, position: number) => SlotAnswer;
+export declare const createSlotCensus: (input: SlotCensusInput) => SlotCensus;