@geastack/compiler 1.0.15

package/dist/projection/class-storage.js

@@ -0,0 +1,236 @@
+import { representationKey } from '../representation/model.js';
+import { operandOf } from '../semantics/model/operands.js';
+import { abiOfCallee } from './callee.js';
+import { recordFieldsOfShape } from './fields.js';
+/**
+ * Keep an overlay until every native access through that ancestor has a
+ * descendant-storage dispatch path. An unused overlay needs no such bridge.
+ * Runtime-key accesses use the object's own-property protocol. That protocol
+ * dispatches on the concrete instance and needs its real fields, not a copy
+ * of every possible descendant field in an ancestor.
+ */
+export const nativeClassFieldUsesOf = (graph, plan, deriver, classes, slots, ownerDispatchedReads = new Set()) => {
+    const used = new Map();
+    const mark = (receiver, key) => {
+        if (receiver.kind === 'optional')
+            return mark(receiver.payload, key);
+        if (receiver.kind === 'borrowed-ref')
+            return mark(receiver.referent, key);
+        if (receiver.kind === 'tagged-union') {
+            for (const arm of receiver.arms)
+                mark(arm.value, key);
+            return;
+        }
+        if (receiver.kind !== 'class-ref')
+            return;
+        let declaration = receiver.declaration;
+        const seen = new Set();
+        const shadowed = new Set();
+        while (declaration !== null && !seen.has(declaration)) {
+            seen.add(declaration);
+            const layout = classes.get(declaration);
+            if (!layout)
+                return;
+            for (const field of layout.fields) {
+                if ((key !== null && field.key !== key) || shadowed.has(field.key))
+                    continue;
+                shadowed.add(field.key);
+                if (!field.syntheticSubclassMemberOverlay)
+                    continue;
+                // Demand belongs to the receiver through which code accesses the
+                // member. The ancestor supplied its type, not its allocation site.
+                const fields = used.get(receiver.declaration) ?? new Set();
+                fields.add(field.key);
+                used.set(receiver.declaration, fields);
+            }
+            declaration = layout.base;
+        }
+    };
+    // A structural view reads fields even though the graph contains no `get`
+    // for each copied member. Ask the slot authority for the destination, then
+    // retain the native members that this source/target pair can read. This
+    // records demand only; conversion admission remains the conversion census's.
+    const viewed = new Set();
+    const fieldsOf = (value) => {
+        if (value.kind === 'record' || value.kind === 'record-with-index')
+            return value.fields;
+        if (value.kind === 'class-ref' || value.kind === 'native-record-ref')
+            return recordFieldsOfShape(deriver, value.shapeId) ?? [];
+        return [];
+    };
+    const view = (from, to) => {
+        const fromKey = representationKey(from);
+        const toKey = representationKey(to);
+        if (fromKey === toKey)
+            return;
+        const key = `${fromKey}->${toKey}`;
+        if (viewed.has(key))
+            return;
+        viewed.add(key);
+        if (from.kind === 'optional')
+            return view(from.payload, to);
+        if (to.kind === 'optional')
+            return view(from, to.payload);
+        if (from.kind === 'borrowed-ref')
+            return view(from.referent, to);
+        if (to.kind === 'borrowed-ref')
+            return view(from, to.referent);
+        if (from.kind === 'tagged-union') {
+            for (const arm of from.arms)
+                view(arm.value, to);
+            return;
+        }
+        if (to.kind === 'tagged-union') {
+            for (const arm of to.arms)
+                view(from, arm.value);
+            return;
+        }
+        if (to.kind === 'record' || to.kind === 'record-with-index' || to.kind === 'native-record-ref') {
+            const sourceFields = fieldsOf(from);
+            for (const field of fieldsOf(to)) {
+                if (from.kind === 'class-ref')
+                    mark(from, field.key);
+                const source = sourceFields.find((candidate) => candidate.key === field.key);
+                if (source)
+                    view(source.value, field.value);
+            }
+        }
+        if (from.kind === 'array-object' && to.kind === 'array-object')
+            view(from.element, to.element);
+        if (from.kind === 'dictionary' && to.kind === 'dictionary')
+            view(from.value, to.value);
+        if (from.kind === 'keyed-collection' && to.kind === 'keyed-collection') {
+            view(from.key, to.key);
+            if (from.value && to.value)
+                view(from.value, to.value);
+        }
+        const sourceAbi = abiOfCallee(from);
+        const targetAbi = abiOfCallee(to);
+        if (sourceAbi && targetAbi) {
+            view(sourceAbi.result, targetAbi.result);
+            for (const [index, parameter] of targetAbi.parameters.entries()) {
+                const source = sourceAbi.parameters[index];
+                if (source)
+                    view(parameter.value, source.value);
+            }
+            if (sourceAbi.receiver && targetAbi.receiver)
+                view(targetAbi.receiver, sourceAbi.receiver);
+        }
+    };
+    for (const operation of graph.operations.values()) {
+        for (const operand of operation.operands) {
+            const target = slots.slotOf(operation, operand);
+            if (target.kind !== 'slot')
+                continue;
+            const source = slots.enteringCarrierOf(operation, operand);
+            if (source)
+                view(source, target.representation);
+        }
+        if (operation.family !== 'property' ||
+            operation.internalMethod === 'own-property-keys' ||
+            operation.internalMethod === 'has-property' ||
+            operation.internalMethod === 'delete')
+            continue;
+        if (operation.internalMethod === 'get' && ownerDispatchedReads.has(operation.id))
+            continue;
+        // Presence and deletion dispatch through the concrete object's property
+        // protocol, even for a constant key. Neither loads an ancestor payload;
+        // allocating a synthetic slot for them hides the real descendant owner.
+        const receiver = operandOf(operation, 'receiver');
+        const key = operandOf(operation, 'key');
+        if (!receiver)
+            continue;
+        if (key?.source.kind !== 'constant')
+            continue;
+        const carrier = receiver.source.kind === 'result' ? plan.selected.get(receiver.source.result) : undefined;
+        mark(carrier ?? deriver.derive(receiver.type), key.source.text);
+    }
+    return used;
+};
+/**
+ * Real inherited properties keep one slot. Synthetic fields without a native
+ * ancestor access are removed; real descendant declarations then own their
+ * own storage. Unclassified shape members retain the existing layout.
+ */
+export const projectNativeClassStorage = (classes, deriver, uses) => {
+    const planned = new Map();
+    const visiting = new Set();
+    const rawFields = (layout) => {
+        if (layout.instance?.kind !== 'class-ref')
+            return null;
+        const record = deriver.layoutOf(layout.instance.shapeId);
+        if (record.kind !== 'record' && record.kind !== 'record-with-index')
+            return null;
+        const overrides = layout.methodOverrides ?? [];
+        return [...record.fields.filter((field) => !overrides.some((override) => override.key === field.key)), ...overrides];
+    };
+    const visit = (declaration) => {
+        const known = planned.get(declaration);
+        if (known)
+            return known;
+        if (visiting.has(declaration))
+            return null;
+        const layout = classes.get(declaration);
+        if (!layout)
+            return null;
+        const raw = rawFields(layout);
+        if (!raw)
+            return null;
+        visiting.add(declaration);
+        const base = layout.base === null ? null : classes.get(layout.base);
+        const inherited = layout.base === null ? [] : (visit(layout.base)?.fields ?? (base ? rawFields(base) : null));
+        if (inherited === null)
+            return null;
+        const inheritedKeys = new Set(inherited.map((field) => field.key));
+        const ancestorDeclarations = new Map();
+        const walked = new Set();
+        for (let current = layout.base; current !== null && !walked.has(current);) {
+            walked.add(current);
+            const ancestor = classes.get(current);
+            if (!ancestor)
+                break;
+            for (const field of ancestor.fields)
+                if (!ancestorDeclarations.has(field.key))
+                    ancestorDeclarations.set(field.key, field);
+            current = ancestor.base;
+        }
+        const declared = new Map(layout.fields.map((field) => [field.key, field]));
+        const omittedOverlays = [];
+        const own = raw.filter((field) => {
+            if (inheritedKeys.has(field.key))
+                return false;
+            const evidence = declared.get(field.key);
+            if (evidence?.syntheticSubclassMemberOverlay && !uses.get(declaration)?.has(field.key)) {
+                omittedOverlays.push(field.key);
+                return false;
+            }
+            if (evidence !== undefined || !ancestorDeclarations.has(field.key))
+                return true;
+            return ancestorDeclarations.get(field.key)?.syntheticSubclassMemberOverlay === true && uses.get(declaration)?.has(field.key) === true;
+        });
+        // A retained overlay reserves a typed slot for a base-view access; it does
+        // not create a JavaScript own property. Only a real write makes it present.
+        const storage = {
+            fields: [
+                ...inherited,
+                ...own.map((selected) => {
+                    // A post-lowering ownership publication moves the slot but does
+                    // not change its already-lowered value ABI. All loads and stores
+                    // keep the carrier the original storage census selected.
+                    const held = layout.nativeStorage?.fields.find((field) => field.key === selected.key);
+                    const field = held ? { ...selected, value: held.value, required: held.required } : selected;
+                    return (declared.get(field.key) ?? ancestorDeclarations.get(field.key))?.syntheticSubclassMemberOverlay
+                        ? { ...field, required: false }
+                        : field;
+                })
+            ],
+            omittedOverlays
+        };
+        planned.set(declaration, storage);
+        visiting.delete(declaration);
+        return storage;
+    };
+    for (const declaration of classes.keys())
+        visit(declaration);
+    return planned;
+};

package/dist/projection/classes.d.ts

@@ -0,0 +1,283 @@
+import type { DeclarationId, FunctionId, StructuralTypeId } from '../identity/ids.js';
+import { type CallableAbi, type RecordField, type Representation } from '../representation/model.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { RepresentationDeriver } from '../representation/derive.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import { type StructuralType } from '../semantics/model/structural-types.js';
+import type { NativeClassStorage } from './class-storage.js';
+/**
+ * What each class is made of, assembled from the events its evaluation
+ * published.
+ *
+ * A class is not one operation. `ClassDefinitionEvaluation` creates the
+ * constructor object, then installs each method, then records each field --
+ * and the target needs all of them at once to emit a construction. Recovering
+ * that set by walking syntax would make this file a second authority over
+ * which members a class has; reading the events keeps the graph the only one.
+ *
+ * Order is the order the events were published, which is the order class
+ * evaluation runs them. A field initializer runs in field-declaration order at
+ * every construction, so reordering here would change what the program does.
+ */
+export interface ClassField {
+    readonly declaration: DeclarationId;
+    /** The written property key, from the definition's own key operand. */
+    readonly key: string;
+    /** The function that computes this field's initial value, or `null` for a field declared without one. */
+    readonly initializer: FunctionId | null;
+    /** The field's declared carrier, when its definition published one. */
+    readonly representation: Representation | null;
+    /** The field exists only to type a base-typed duck-property read; it was not declared by the program's class. */
+    readonly syntheticSubclassMemberOverlay: boolean;
+}
+/**
+ * The storage census for one synthetic subclass-member-overlay field.
+ *
+ * `evidenceOwner` is the class whose published field makes a base-typed
+ * access type-check. It is deliberately separate from `physicalOwners`: an
+ * overlay is evidence about the family surface, not a declaration that the
+ * ancestor owns a slot. Each physical owner is a real field declaration in a
+ * descendant and carries the representation that its storage uses. This is
+ * published before target lowering so targets do not have to infer ownership
+ * from flattened record shapes.
+ */
+export interface ClassFieldOwnership {
+    readonly key: string;
+    readonly evidenceOwner: DeclarationId;
+    readonly evidence: ClassField;
+    readonly physicalOwners: readonly {
+        readonly declaration: DeclarationId;
+        readonly field: ClassField;
+    }[];
+}
+/** One prototype method, and the body that implements it. */
+export interface ClassMethod {
+    readonly key: string;
+    readonly callable: FunctionId | null;
+    /** Convention of the installed method object, including its implicit receiver. */
+    readonly representation?: Representation;
+    /** Public mutable member frame, distinct from the original implementation's frame. */
+    readonly storageRepresentation?: Representation;
+}
+/**
+ * One accessor-backed member: the property a reader spells, and the functions
+ * that implement reading and writing it.
+ *
+ * Kept apart from `methods` because a reader of `box.value` is not taking a
+ * function object -- it is *calling* one, and the two lower to different C++.
+ * Either half can be absent: a get-only accessor really has no setter, and
+ * writing through it is a defect the target refuses by name rather than a
+ * lookup that quietly finds a field.
+ */
+export interface ClassAccessor {
+    readonly key: string;
+    readonly getter: FunctionId | null;
+    readonly setter: FunctionId | null;
+    /**
+     * The getter's own callable carrier, whose `abi.result` is what reading the
+     * member yields.
+     *
+     * A class's accessors are NOT members of the instance shape the deriver
+     * lays out -- that shape enumerates storage, and an accessor has none -- so
+     * `record.accessors` is empty for every class body and there is nowhere
+     * else to ask what a class getter publishes. Carried here, from the same
+     * selected representation `ClassMethod.representation` comes from, so the
+     * two halves of "what does this class member hold" have one source.
+     */
+    readonly representation?: Representation;
+}
+export interface ClassLayout {
+    /** Proven layout demand with no reachable class evaluation/construction. */
+    readonly layoutOnly?: boolean;
+    readonly nativeStorage?: NativeClassStorage;
+    /** Typed own-property shadows, initially absent; prototype methods remain methods. */
+    readonly methodOverrides?: readonly RecordField[];
+    /** Methods replaced on this prototype, rather than on ordinary instances. */
+    readonly prototypeMethodMutations?: readonly string[];
+    /** Uses outside the currently supported typed method-only prototype protocol. */
+    readonly prototypeUnsupportedUses?: readonly string[];
+    readonly declaration: DeclarationId;
+    /**
+     * The class this one extends, or `null` for a base class.
+     *
+     * A derived class shares its base's storage and bodies: the base's fields are
+     * its fields, the base's methods accept its instances, and its construction
+     * runs the base's initialization first. None of that is derivable from this
+     * class's own members, so the link is carried rather than rediscovered -- and
+     * without it an inherited member reads a struct field nothing initialized.
+     */
+    readonly base: DeclarationId | null;
+    /**
+     * `base` was linked by a modelled `Object.setPrototypeOf(C.prototype,
+     * B.prototype)` rather than by `extends`: layout and dispatch inherit from
+     * it, but this class's construction never runs the base's -- there is no
+     * `super()` to run it (`semantics/prototype-reparenting.ts`).
+     */
+    readonly prototypeBase?: true;
+    /** No evaluation can produce an instance of this class (`semantics/uninstantiable-classes.ts`). */
+    readonly uninstantiable?: true;
+    /** A built-in native class extended directly; currently the intrinsic Error family. */
+    readonly nativeBase: {
+        readonly protocol: string;
+        readonly instance: Extract<Representation, {
+            readonly kind: 'native-record-ref';
+        }>;
+    } | null;
+    /** The convention `new` invokes, from the constructor object's own carrier. */
+    readonly construct: CallableAbi | null;
+    /** The carrier of an instance, which is what that convention returns. */
+    readonly instance: Representation | null;
+    /** The written constructor's body, or `null` when the class relies on the implicit one. */
+    readonly constructor: FunctionId | null;
+    readonly fields: readonly ClassField[];
+    /** Ownership facts for synthetic overlay evidence declared by this class. */
+    readonly fieldOwnership: readonly ClassFieldOwnership[];
+    readonly methods: readonly ClassMethod[];
+    readonly accessors: readonly ClassAccessor[];
+    /**
+     * The class's own *static* members -- kept apart from `fields`/`methods`/
+     * `accessors` because a static lives on the constructor object, not on an
+     * instance, and is read through a `constructor-family` receiver
+     * (`Quaternion.fromEuler`) rather than a `class-ref` one
+     * (`someQuaternion.multiply`). TypeScript allows a class to declare an
+     * instance and a static member with the same key, so folding both into one
+     * bucket (as this file did before) let a lookup silently return whichever
+     * one the census happened to publish first, for either receiver kind.
+     * `class-lifecycle`'s events already carry which is which
+     * (`descriptor.placement`); these three lists are that fact, kept.
+     */
+    readonly staticFields: readonly ClassField[];
+    readonly staticMethods: readonly ClassMethod[];
+    readonly staticAccessors: readonly ClassAccessor[];
+    /**
+     * The class's `[[Name]]` -- `C.name` when no static member shadows it --
+     * as the constructor-object allocation stated it (`functionName`, the same
+     * field a function allocation fills), or `null` when no allocation of this
+     * class's constructor object was censused.
+     */
+    readonly name: string | null;
+    /** The class's `Function.prototype.length` (`functionLength` on the same allocation), or `null` beside a `null` name. */
+    readonly length: number | null;
+    /**
+     * The census copy ids this physical class was published from (`decl|f0|36@0`,
+     * `decl|f0|36@2`), when it is a generic's; absent for a class that was never
+     * copied. A consumer holding a copy id from a class-lifecycle event resolves
+     * its layout through `classLayoutOfCopy`, never by stripping the suffix --
+     * a generic instantiated at two layouts has two physical classes, and the
+     * root names neither.
+     */
+    readonly copies?: readonly DeclarationId[];
+    /**
+     * The class whose STATIC storage and static members this one shares -- the
+     * generic root, for one physical layout of a generic instantiated at
+     * several. Absent for a class that owns its own statics.
+     *
+     * A generic class is several structs and ONE constructor object: `Box` is
+     * one binding, `Box.count` is one cell every layout's constructor
+     * increments, and `Box.create` is one function. The layouts split what an
+     * INSTANCE is, never what the class value is, so every physical class of
+     * one root carries the same static members and they all resolve to one
+     * storage owner (`ir/class-static-fields.ts`'s `staticFieldOwnerOf`).
+     */
+    readonly staticOwner?: DeclarationId;
+}
+/**
+ * The one class that owns the static storage behind these constructor-family
+ * members, or `null` when they disagree -- which for a family of genuinely
+ * different classes (a base's slot the program stores subclasses into) they
+ * do, and for the layouts of ONE generic they never do.
+ */
+export declare const sharedStaticOwnerOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>, members: readonly DeclarationId[]) => DeclarationId | null;
+/**
+ * The physical class a census copy id belongs to.
+ *
+ * Exact id first (a physical id IS the copy id of its group's lowest copy,
+ * and a non-generic class is its own only copy); then the class that lists
+ * the copy among its `copies`; then the generic root, which is where a copy
+ * with no constructor-object carrier of its own was published.
+ */
+export declare const classLayoutOfCopy: (classes: ReadonlyMap<DeclarationId, ClassLayout>, copy: DeclarationId) => ClassLayout | undefined;
+/** Runtime class candidates exclude definitions retained solely for type layout. */
+/** The class whose construction this class's construction runs first, which a prototype-only base is not. */
+export declare const constructedBaseOf: (layout: Pick<ClassLayout, "base" | "prototypeBase">) => DeclarationId | null;
+export declare const runtimeClassLayoutsOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>) => readonly ClassLayout[];
+/**
+ * The physical facts needed to lay out a class reference.  This deliberately
+ * has no constructor, method, accessor, or field-initializer members: a
+ * class-ref can be retained because a value is typed by the class even when
+ * no class-lifecycle event survived reachability.  Treating that evidence as
+ * a full ClassLayout would invent callable bodies and make the target believe
+ * an implicit constructor was emitted.
+ */
+export interface PhysicalClassLayout {
+    readonly nativeStorage?: NativeClassStorage;
+    readonly declaration: DeclarationId;
+    /** The nearest authenticated base, or null for a root class. */
+    readonly base: DeclarationId | null;
+    /** The exact class-ref carrier whose shape supplies this struct's fields. */
+    readonly instance: Extract<Representation, {
+        readonly kind: 'class-ref';
+    }>;
+    /** Native base facts are preserved for ordinary projected classes. */
+    readonly nativeBase: ClassLayout['nativeBase'];
+}
+export interface PhysicalClassLayoutPublication {
+    readonly layouts: ReadonlyMap<DeclarationId, PhysicalClassLayout>;
+    /** A missing direct base prevents a sound derived layout and must fail closed. */
+    readonly complete: boolean;
+    readonly missingBases: readonly DeclarationId[];
+}
+export type PhysicalClassRefResolver = (declaration: DeclarationId) => Extract<Representation, {
+    readonly kind: 'class-ref';
+}> | null;
+/**
+ * Build the sealed class-ref authority used to close physical ancestry.
+ * Existing runtime class layouts win because their instance carrier is the
+ * projection's canonical shape. For type-only declarations, every
+ * class-instance structural anchor is derived and grouped by declaration;
+ * more than one distinct carrier is ambiguous and therefore resolves to null.
+ */
+export declare const physicalClassInstanceResolverOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>, structuralTypes: ReadonlyMap<StructuralTypeId, StructuralType>, deriver: RepresentationDeriver) => PhysicalClassRefResolver;
+export interface ClassProjectionInput {
+    readonly graph: SemanticGraph;
+    readonly plan: SealedRepresentationPlan;
+    readonly deriver: RepresentationDeriver;
+    /** Classes no evaluation can instantiate (`semantics/uninstantiable-classes.ts`). */
+    readonly uninstantiable?: ReadonlySet<DeclarationId>;
+}
+/**
+ * Publish synthetic overlay ownership after specialization collapse.
+ *
+ * This pass records evidence and physical owners without changing `fields`.
+ * Keeping the existing field list intact is intentional: access recipes and
+ * the target layout must consume this census before any storage can be
+ * removed. A missing representation remains visible as an owner but cannot
+ * be treated as a typed storage recipe by a later consumer.
+ */
+export declare const publishClassFieldOwnership: (layouts: ReadonlyMap<DeclarationId, ClassLayout>) => ReadonlyMap<DeclarationId, ClassLayout>;
+/**
+ * Publish physical class ancestry for the final carrier set.
+ *
+ * `projectClasses` is intentionally event-driven: it describes executable
+ * class lifecycle, so a class used only as a retained field type may have no
+ * entry there.  The target still needs its authenticated base link to avoid
+ * flattening inherited storage into the derived struct.  This pass publishes
+ * only that physical fact from the already-sealed class-ref carriers and
+ * reuses full projected layouts where they exist.  It must run on the final
+ * emission carrier set, after shaking, so a dropped type-only value cannot
+ * root a class merely because it appeared in the plan.
+ */
+export declare const physicalClassLayoutsOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>, representations: readonly Representation[], resolveClassRef?: PhysicalClassRefResolver | null) => PhysicalClassLayoutPublication;
+export declare const projectClasses: (input: ClassProjectionInput) => ReadonlyMap<DeclarationId, ClassLayout>;
+/**
+ * Whether a runtime property key held in `carrier` can never be a Symbol.
+ *
+ * ToPropertyKey (ECMA-262 7.1.19) returns a Symbol only for a Symbol, or for
+ * an object whose ToPrimitive answers one. Every other primitive becomes its
+ * string. So a key carried as a string, a number, a boolean or an absence --
+ * or a union of only those -- spells string keys alone; an object, a symbol
+ * or a dynamic key may spell either and answers `false`.
+ */
+export declare const keyExcludesSymbols: (carrier: Representation) => boolean;
+/** A write creates an own callable property without replacing its prototype declaration. */
+export declare const publishClassMethodOverrides: (layouts: ReadonlyMap<DeclarationId, ClassLayout>, input: ClassProjectionInput) => ReadonlyMap<DeclarationId, ClassLayout>;