@geastack/compiler 1.0.15

package/dist/ir/certify.js

@@ -0,0 +1,481 @@
+import { operationOfResult } from '../identity/ids.js';
+import { captureCapabilityOf, representationKey } from '../representation/model.js';
+import { propertyAccessKeysOf } from './certify/property-access.js';
+import { runtimeHelperKeysOf } from './certify/runtime-helper.js';
+import { allOperationsOf } from './model.js';
+import { resultOfIrOperation } from './queries.js';
+import { nativeMergeTransportMatches } from './native-merge-transport.js';
+import { nativeFieldOwnerReadMatches } from './native-field-owner.js';
+import { absentClassArmsHold } from './absent-class-arm.js';
+import { objectValueConversionInputsOf, objectValueConversionsMatch } from './object-value-conversions.js';
+/**
+ * Certification of the lowered IR.
+ *
+ * Preflight certified a program by predicting, from the semantic graph and
+ * the plan, what lowering and the printer would do with it: seven builders
+ * re-derived slots, receivers and key literalness so they could ask the
+ * manifest the question the printer would later ask. This walks the IR that
+ * lowering actually built. Every operation states its operands' carriers,
+ * every `convert` cites the census node it applies, every allocation names
+ * its captures -- so each capability the printer will need is a function of
+ * the operation alone, spelled once here in the manifest's own vocabulary
+ * and looked up in the manifest's own sets. The certificate is the empty
+ * refusal list.
+ *
+ * One namespace. A key is `${family}:${discriminator}`; the family names the
+ * manifest set the discriminator is a member of (`property-access` ->
+ * `propertyRecipes`, `runtime-helper` -> `runtimeHelpers`, ...), or the
+ * census that answers it (`conversion` -> the conversion census by node id).
+ * A refusal anywhere in the compiler that names a key outside this union is
+ * a type error, which is what closes the gap `scripts/refusal-keys.mjs`
+ * measures.
+ */
+export const capabilityFamilies = [
+    'physical-cpp-type',
+    'call-abi',
+    'host-invocation',
+    'host-member-call',
+    'property-access',
+    'capture',
+    'conversion',
+    'native-boundary',
+    'runtime-helper',
+    'abrupt-edge'
+];
+export const familyOf = (key) => key.slice(0, key.indexOf(':'));
+export const isCapabilityKey = (key) => capabilityFamilies.includes(key.slice(0, key.indexOf(':')));
+const discriminatorOf = (key) => key.slice(key.indexOf(':') + 1);
+/**
+ * Whether the target can spell a carrier. The manifest's `physicalTypes` set
+ * is the plan's projection of the target's own predicate; the IR carries
+ * carriers the plan never selected (a slot's carrier, a `convert`'s result),
+ * so a manifest that publishes the predicate itself is asked directly, and
+ * one that does not falls back to the set -- fail-closed, as every optional
+ * manifest field reads when absent.
+ */
+const spellable = (manifest, representation) => manifest.spellable ? manifest.spellable(representation) : manifest.physicalTypes.has(representationKey(representation));
+const physicalTypeDemand = (manifest, representation) => {
+    const key = representationKey(representation);
+    return spellable(manifest, representation)
+        ? { key: `physical-cpp-type:${key}`, verdict: 'installed' }
+        : { key: `physical-cpp-type:${key}`, verdict: 'missing', detail: `the target cannot spell ${key}` };
+};
+/** `native-handle` is admissible only behind a versioned, authenticated host protocol; the key is the target's own tag name where the host stated one. */
+const nativeBoundaryDemand = (representation) => representation.kind === 'native-handle'
+    ? { key: `native-boundary:${representation.native ?? representation.protocol}@${representation.version}` }
+    : null;
+const abiDemands = (manifest, abi) => {
+    if (abi === null)
+        return [];
+    const carriers = [...abi.parameters.map((parameter) => parameter.value), abi.result];
+    if (abi.receiver !== null)
+        carriers.push(abi.receiver);
+    return carriers.flatMap((carrier) => {
+        const boundary = nativeBoundaryDemand(carrier);
+        return boundary ? [physicalTypeDemand(manifest, carrier), boundary] : [physicalTypeDemand(manifest, carrier)];
+    });
+};
+/**
+ * The demands this module derives itself: the ones whose fact is a single
+ * field of the operation. The property families and the runtime-helper
+ * families each live in their own module because their key spellings are
+ * refinements of a carrier (`iterator(next):get:false`,
+ * `protocol:spread:dictionary(string->record)`) that the manifest's tables
+ * spell the same way, and that vocabulary is one subject per module.
+ */
+const ownDemandsOf = (operation, ctx) => {
+    switch (operation.kind) {
+        case 'merge-live-arm-rebuild': {
+            const recipe = operation.nativeTransport;
+            if (!recipe)
+                return [];
+            if (!nativeMergeTransportMatches(operation, ctx.conversions))
+                return [
+                    {
+                        key: 'runtime-helper:merge-live-arm-rebuild:native-transport',
+                        verdict: 'missing',
+                        detail: 'native merge transport disagrees with its live arms or conversion nodes'
+                    }
+                ];
+            return [
+                ...recipe.arms.map((arm) => ({ key: `conversion:${arm.conversion}` })),
+                ...(recipe.absence ? [{ key: `conversion:${recipe.absence}` }] : [])
+            ];
+        }
+        case 'convert':
+            // The node the instruction cites decides the pair; a `never` node here
+            // is one lowering minted deliberately (`convertOrDrift`) so the printer's
+            // own path could still try, and certification refuses it by name.
+            return [{ key: `conversion:${operation.conversionUse}` }];
+        case 'call':
+        case 'construct': {
+            const demands = [{ key: 'call-abi:generic' }];
+            if (operation.kind === 'call' && operation.objectValueConversions) {
+                const semantic = ctx.semanticOperationOf(operation.lineage);
+                const expected = objectValueConversionInputsOf(semantic?.family === 'invocation' ? semantic.intrinsicMutation : undefined, operation.arguments, ctx.deriver);
+                if (operation.argumentsAreSpread || !objectValueConversionsMatch(expected, operation.objectValueConversions, ctx.conversions))
+                    demands.push({
+                        key: 'call-abi:object-value-conversions',
+                        verdict: 'missing',
+                        detail: 'Object value conversions do not match the authenticated field sources'
+                    });
+                for (const value of operation.objectValueConversions)
+                    demands.push({ key: `conversion:${value.conversion}` });
+            }
+            if (operation.kind === 'call' && operation.fixedDataDefinition) {
+                const recipe = operation.fixedDataDefinition;
+                const target = operation.arguments[0]?.representation;
+                const descriptor = operation.arguments[2]?.representation;
+                const semantic = ctx.semanticOperationOf(operation.lineage);
+                const key = semantic?.operands.find((operand) => operand.role === 'argument' && operand.ordinal === 1);
+                const node = ctx.conversions.nodeById(recipe.conversion);
+                const native = node?.capability.kind === 'identity' ||
+                    ((node?.capability.kind === 'atom' || node?.capability.kind === 'static') &&
+                        node.capability.materializer.nativeFieldProtocol === 'unused');
+                if (!target ||
+                    !descriptor ||
+                    operation.argumentsAreSpread ||
+                    operation.arguments.length !== 3 ||
+                    recipe.target !== representationKey(target) ||
+                    recipe.descriptor !== representationKey(descriptor) ||
+                    !operation.result ||
+                    representationKey(operation.result.representation) !== recipe.target ||
+                    semantic?.family !== 'invocation' ||
+                    semantic.intrinsicMutation !== 'object-define-property' ||
+                    key?.source.kind !== 'constant' ||
+                    key.source.literal !== 'string' ||
+                    key.source.text !== recipe.field.key ||
+                    (recipe.nativeFieldProtocol === 'unused' && (!semantic.intrinsicDataDefinition || !native))) {
+                    demands.push({
+                        key: 'call-abi:fixed-data-definition',
+                        verdict: 'missing',
+                        detail: 'fixed data definition does not match its authenticated call'
+                    });
+                }
+                if (node !== null &&
+                    (representationKey(node.source) !== representationKey(recipe.value.value) ||
+                        representationKey(node.target) !== representationKey(recipe.held))) {
+                    demands.push({
+                        key: `conversion:${recipe.conversion}`,
+                        verdict: 'missing',
+                        detail: 'fixed data definition conversion disagrees with its field'
+                    });
+                }
+                else
+                    demands.push({ key: `conversion:${recipe.conversion}` });
+            }
+            const callee = operation.callee.representation;
+            if (callee.kind === 'dynamic')
+                demands.push({ key: 'call-abi:dynamic' });
+            // A plugin host's own spelling table is consulted only for a host
+            // carrier; core constructors keep `native: null` and render from the
+            // target's own table, so asking the plugin set about them would refuse
+            // a complete implementation (`preflight/host-invocation.ts`).
+            if (callee.kind === 'native-handle' && callee.native !== null) {
+                demands.push({ key: `host-invocation:${operation.kind === 'call' ? `${callee.native}.call` : callee.native}` });
+            }
+            return demands;
+        }
+        case 'allocate-callable':
+        case 'allocate-constructor':
+            // Each captured slot crosses a body boundary in its own ownership; the
+            // capture path transports the ownerships the manifest lists and no other.
+            return operation.captures.map((capture) => ({ key: `capture:${captureCapabilityOf(capture.representation)}` }));
+        case 'binding-read':
+            return ctx.externalBindings.has(operation.declaration) ? [{ key: 'native-boundary:external-binding' }] : [];
+        case 'get': {
+            if (operation.absentClassArms !== undefined) {
+                const key = ctx.definitionOf(operation.key.value);
+                if (!absentClassArmsHold(operation, key?.kind === 'constant' && key.literal === 'string' ? key.text : null, ctx.classes, ctx.reflection))
+                    return [
+                        {
+                            key: 'property-access:union:get:absent-class-arm',
+                            verdict: 'missing',
+                            detail: 'an absent class arm is declared on its family or its class holds a dynamic protocol'
+                        }
+                    ];
+            }
+            if (operation.nativeFieldOwnerRead) {
+                const key = ctx.definitionOf(operation.key.value);
+                if (!nativeFieldOwnerReadMatches(operation, key?.kind === 'constant' && key.literal === 'string' ? key.text : null, ctx.classes, ctx.conversions, ctx.reflection))
+                    return [
+                        {
+                            key: 'runtime-helper:native-field-owner-read',
+                            verdict: 'missing',
+                            detail: 'native field-owner read disagrees with its layout, exposure or conversions'
+                        }
+                    ];
+                return [
+                    ...(operation.nativeFieldOwnerRead.arms.length > 0
+                        ? [{ key: 'runtime-helper:computation:instanceof:class-ref:constructor-family' }]
+                        : []),
+                    ...[operation.nativeFieldOwnerRead.missing, ...operation.nativeFieldOwnerRead.arms.map((arm) => arm.conversion)].map((id) => ({
+                        key: `conversion:${id}`
+                    }))
+                ];
+            }
+            const recipe = operation.typedComputedRead;
+            if (recipe === undefined)
+                return [];
+            const recipeKey = 'property-access:record:get:typed-computed-read';
+            const demands = [];
+            if (recipe.receiver !== representationKey(operation.receiver.representation) ||
+                recipe.result !== representationKey(operation.result.representation) ||
+                (recipe.receiverBounded !== undefined && recipe.receiverBounded.carrier !== representationKey(operation.key.representation)) ||
+                recipe.arms.length === 0) {
+                demands.push({
+                    key: recipeKey,
+                    verdict: 'missing',
+                    detail: 'the sealed computed-read recipe does not match the get operation carriers'
+                });
+            }
+            if (recipe.receiverBounded !== undefined) {
+                const node = ctx.conversions.nodeById(recipe.receiverBounded.missing);
+                const key = `conversion:${recipe.receiverBounded.missing}`;
+                if (node !== null && (node.source.kind !== 'undefined' || representationKey(node.target) !== recipe.result))
+                    demands.push({ key, verdict: 'missing', detail: 'the numeric computed-read absence conversion does not match its result' });
+                else
+                    demands.push({ key });
+            }
+            for (const arm of recipe.arms) {
+                const key = `conversion:${arm.conversion}`;
+                const node = ctx.conversions.nodeById(arm.conversion);
+                if (node !== null &&
+                    (representationKey(node.source) !== representationKey(arm.source) ||
+                        representationKey(node.target) !== representationKey(operation.result.representation))) {
+                    demands.push({
+                        key,
+                        verdict: 'missing',
+                        detail: `the sealed conversion for field "${arm.key}" does not match the computed-read recipe`
+                    });
+                }
+                else {
+                    // The conversion census remains the authority for existence and
+                    // capability. The emitter receives only this authenticated node id.
+                    demands.push({ key });
+                }
+            }
+            return demands;
+        }
+        case 'set': {
+            // The write twin of the sealed read recipe above, and validated the same
+            // way: a demand is raised ONLY when the certificate has gone stale
+            // against the operation it rides on. A well-formed one asks for nothing
+            // new -- the emitter renders it as ordinary constant-key stores, whose
+            // storage the receiver's own `:set:` claims already cover.
+            const recipe = operation.typedComputedWrite;
+            if (recipe === undefined)
+                return [];
+            if (recipe.receiver === representationKey(operation.receiver.representation) && recipe.keys.length > 0)
+                return [];
+            return [
+                {
+                    key: `property-access:${operation.receiver.representation.kind}:set:typed-computed-write`,
+                    verdict: 'missing',
+                    detail: 'the sealed computed-write recipe does not match the set operation receiver'
+                }
+            ];
+        }
+        case 'throw':
+            return [{ key: 'abrupt-edge:throw' }];
+        case 'await':
+        case 'yield':
+            return [{ key: 'abrupt-edge:suspend' }];
+        case 'return':
+            // A return that leaves a try region runs its finally clause on the way
+            // out; a body with no region completes the ordinary way and asks nothing.
+            return ctx.body.tryRegions.length > 0 ? [{ key: 'abrupt-edge:return' }] : [];
+        default:
+            return [];
+    }
+};
+/** Every capability one operation needs, in the manifest's namespace. */
+export const capabilityKeysOf = (operation, ctx) => [
+    ...ownDemandsOf(operation, ctx),
+    ...propertyAccessKeysOf(operation, ctx),
+    ...runtimeHelperKeysOf(operation, ctx)
+];
+const registered = (installed, family, discriminator) => installed
+    ? { verdict: 'installed', reason: '' }
+    : { verdict: 'missing', reason: `the target manifest registers no ${family} "${discriminator}"` };
+/**
+ * The one lookup. Each family names the manifest set (or the census) that
+ * answers it; a family with no set is decided by the demand itself, and a
+ * demand in such a family that arrives undecided is refused -- fail closed,
+ * never silently installed.
+ */
+const verdictOf = (demand, ctx) => {
+    if (demand.verdict !== undefined)
+        return { verdict: demand.verdict, reason: demand.detail ?? '' };
+    const family = familyOf(demand.key);
+    const discriminator = discriminatorOf(demand.key);
+    const manifest = ctx.manifest;
+    switch (family) {
+        case 'physical-cpp-type':
+        case 'host-member-call':
+            return { verdict: 'missing', reason: `${demand.key} was demanded without a verdict` };
+        case 'call-abi':
+            return registered(discriminator === 'generic' ? manifest.hasGenericCallPath : manifest.hasDynamicCallPath, family, discriminator);
+        case 'host-invocation':
+            return registered((manifest.hostInvocations?.has(discriminator) ||
+                manifest.hostConstructors?.has(discriminator) ||
+                manifest.hostMembers?.has(discriminator)) ??
+                false, family, discriminator);
+        case 'property-access':
+            return registered(manifest.propertyRecipes.has(discriminator), family, discriminator);
+        case 'capture':
+            return registered(manifest.captureOwnershipSupport.has(discriminator), family, discriminator);
+        case 'conversion': {
+            const node = ctx.conversions.nodeById(discriminator);
+            if (node === null)
+                return { verdict: 'missing', reason: `no conversion node was minted for ${discriminator}` };
+            return node.capability.kind === 'never'
+                ? { verdict: 'unsupported', reason: node.capability.reason }
+                : { verdict: 'installed', reason: '' };
+        }
+        case 'native-boundary':
+            return discriminator === 'external-binding'
+                ? registered(manifest.supportsExternalBindings ?? false, family, discriminator)
+                : registered(manifest.nativeProtocols.has(discriminator), family, discriminator);
+        case 'runtime-helper':
+            if (manifest.runtimeHelpers.has(discriminator))
+                return { verdict: 'installed', reason: '' };
+            if (manifest.unsupportedRuntimeHelpers.has(discriminator)) {
+                return { verdict: 'unsupported', reason: `the target declares runtime helper "${discriminator}" unsupported` };
+            }
+            return registered(false, family, discriminator);
+        case 'abrupt-edge':
+            return registered(manifest.abruptEdgeHandlers.has(discriminator), family, discriminator);
+    }
+};
+const contextFor = (input, body) => {
+    const definitions = new Map();
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        for (const operation of allOperationsOf(block)) {
+            const result = resultOfIrOperation(operation);
+            if (result)
+                definitions.set(result.id, operation);
+        }
+    }
+    return {
+        ...input,
+        body,
+        definitionOf: (value) => definitions.get(value) ?? null,
+        semanticOperationOf: (lineage) => input.graph.operations.get(operationOfResult(lineage)) ?? null,
+        isDead: (lineage) => input.deadTypeofGuards.isDeadOperation(operationOfResult(lineage))
+    };
+};
+/**
+ * What one body's environment must transport, as `capture:` demands.
+ *
+ * Read off `IrBody.facts` -- `ir/captures.ts`'s whole-program answer, sealed
+ * onto the body after the shake -- and NOT off `allocate-callable`'s
+ * `captures` operand, which no producer fills. Until this existed the capture
+ * question was certified by nobody and decided only at print time, so a
+ * carrier the target could not transport certified clean and then emitted
+ * nothing: precisely the certify/print disagreement 2.3's gate exists to
+ * catch.
+ *
+ * The rules mirror `targets/cpp/captures.ts`'s admission exactly, because
+ * they are the same rule asked at two stages rather than two rules:
+ * a declaration with no placement is not a capture the environment carries; a
+ * BOXED one is shared by aliasing, so copying its `std::shared_ptr` handle is
+ * safe whatever its own carrier's ownership tier says, and only a carrier the
+ * plan never selected (or left `unresolved`) is refusable there; everything
+ * else, receiver included, must name an ownership the manifest publishes.
+ */
+const captureDemandsOf = (body, placements, boxed) => {
+    const facts = body.facts;
+    if (!facts)
+        return [];
+    const demands = [];
+    for (const declaration of facts.capturedDeclarations) {
+        const placement = placements.get(declaration);
+        if (!placement)
+            continue;
+        const representation = placement.representation ?? null;
+        if (boxed.has(declaration)) {
+            if (representation === null || representation.kind === 'unresolved')
+                demands.push({ key: `capture:${captureCapabilityOf(representation)}` });
+            continue;
+        }
+        demands.push({ key: `capture:${captureCapabilityOf(representation)}` });
+    }
+    if (facts.capturedReceiver)
+        demands.push({ key: `capture:${captureCapabilityOf(facts.capturedReceiver)}` });
+    return demands;
+};
+/**
+ * Walks every body and decides every demand. One refusal per (owner, key):
+ * the same missing recipe demanded at forty sites of one function is one
+ * capability the target lacks, not forty, and the row names which.
+ */
+export const certifyIr = (input) => {
+    const demanded = new Set();
+    const refusals = [];
+    const refused = new Set();
+    const decide = (owner, demand, ctx) => {
+        demanded.add(demand.key);
+        const decision = verdictOf(demand, ctx);
+        if (decision.verdict === 'installed')
+            return;
+        const dedupe = `${owner}|${demand.key}`;
+        if (refused.has(dedupe))
+            return;
+        refused.add(dedupe);
+        refusals.push({ stage: 'certify', key: demand.key, owner, reason: decision.reason || `${demand.key} is ${decision.verdict}` });
+    };
+    for (const row of input.slotDrift) {
+        // No body context is needed: the row already carries the pair and the
+        // census's own reason, and there is no lookup left to do.
+        demanded.add(`conversion:${row.source}->${row.slot}`);
+        const dedupe = `${row.operation}|conversion:${row.source}->${row.slot}`;
+        if (refused.has(dedupe))
+            continue;
+        refused.add(dedupe);
+        refusals.push({ stage: 'certify', key: `conversion:${row.source}->${row.slot}`, owner: String(row.operation), reason: row.reason });
+    }
+    // The whole-program boxed set: a declaration belongs to exactly one physical
+    // frame, so the union of every body's own set is the answer every frame
+    // touching the cell shares -- the same union `CaptureIndex.isBoxed` takes.
+    const boxed = new Set();
+    for (const body of input.bodies.values())
+        for (const declaration of body.facts?.boxed ?? [])
+            boxed.add(declaration);
+    for (const body of input.bodies.values()) {
+        const ctx = contextFor(input, body);
+        const owner = String(body.sourceOwner);
+        for (const demand of captureDemandsOf(body, input.placements, boxed))
+            decide(owner, demand, ctx);
+        for (const demand of abiDemands(input.manifest, body.abi))
+            decide(owner, demand, ctx);
+        for (const demand of abiDemands(input.manifest, body.construct))
+            decide(owner, demand, ctx);
+        // Every SSA value's carrier must be spellable, and a `native-handle` among
+        // them must name an authenticated protocol -- the two facts preflight read
+        // off each published result, read here off the body's own value index.
+        for (const representation of body.values.values()) {
+            decide(owner, physicalTypeDemand(input.manifest, representation), ctx);
+            const boundary = nativeBoundaryDemand(representation);
+            if (boundary)
+                decide(owner, boundary, ctx);
+        }
+        for (const blockId of body.blockOrder) {
+            const block = body.blocks.get(blockId);
+            if (!block)
+                continue;
+            for (const operation of allOperationsOf(block)) {
+                for (const demand of capabilityKeysOf(operation, ctx))
+                    decide(owner, demand, ctx);
+            }
+        }
+    }
+    return Object.freeze({
+        certified: refusals.length === 0 && input.blocked.length === 0,
+        refusals: Object.freeze(refusals),
+        demanded: Object.freeze([...demanded].sort())
+    });
+};

package/dist/ir/class-evaluation.d.ts

@@ -0,0 +1,26 @@
+import type { DeclarationId } from '../identity/ids.js';
+import type { IrBody } from './model.js';
+/**
+ * The classes the program evaluates exactly once.
+ *
+ * A class declaration is an `allocate-constructor` operation, and every
+ * evaluation of it mints a fresh `gea::NativeClassMethodState` -- the
+ * prototype object, the method identities, the `instanceof` chain -- which is
+ * why every instance carries a `gea_method_state` handle to the evaluation
+ * that constructed it: two evaluations of one declaration are two classes,
+ * and their instances must not answer for each other.
+ *
+ * When the declaration is evaluated ONCE there is only one such state for the
+ * whole program, and a handle per instance says nothing the class itself
+ * could not say. `records.ts` then states it once, as a `static` member of
+ * the struct, and the construct function fills it in. On
+ * `bench/comparison/fixtures/binary_trees.ts` that is eight bytes off every
+ * one of a million nodes.
+ *
+ * "Once" is the operation sitting in a region body -- a module body or a
+ * static block, which the language runs a single time -- outside any cyclic
+ * block, at the declaration's only allocation site. A class declared inside a
+ * function, or inside a top-level loop, is evaluated per call or per
+ * iteration and keeps its per-instance handle.
+ */
+export declare const singleEvaluationClassesOf: (bodies: readonly IrBody[]) => ReadonlySet<DeclarationId>;

package/dist/ir/class-evaluation.js

@@ -0,0 +1,50 @@
+import { isRegionId } from '../identity/ids.js';
+import { cyclicBlocksOf } from './dominance.js';
+/**
+ * The classes the program evaluates exactly once.
+ *
+ * A class declaration is an `allocate-constructor` operation, and every
+ * evaluation of it mints a fresh `gea::NativeClassMethodState` -- the
+ * prototype object, the method identities, the `instanceof` chain -- which is
+ * why every instance carries a `gea_method_state` handle to the evaluation
+ * that constructed it: two evaluations of one declaration are two classes,
+ * and their instances must not answer for each other.
+ *
+ * When the declaration is evaluated ONCE there is only one such state for the
+ * whole program, and a handle per instance says nothing the class itself
+ * could not say. `records.ts` then states it once, as a `static` member of
+ * the struct, and the construct function fills it in. On
+ * `bench/comparison/fixtures/binary_trees.ts` that is eight bytes off every
+ * one of a million nodes.
+ *
+ * "Once" is the operation sitting in a region body -- a module body or a
+ * static block, which the language runs a single time -- outside any cyclic
+ * block, at the declaration's only allocation site. A class declared inside a
+ * function, or inside a top-level loop, is evaluated per call or per
+ * iteration and keeps its per-instance handle.
+ */
+export const singleEvaluationClassesOf = (bodies) => {
+    const once = new Set();
+    const repeated = new Set();
+    for (const body of bodies) {
+        const region = isRegionId(body.sourceOwner);
+        const cyclic = region ? cyclicBlocksOf(body) : null;
+        for (const [blockId, block] of body.blocks) {
+            for (const operation of block.operations) {
+                if (operation.kind !== 'allocate-constructor')
+                    continue;
+                const { declaration } = operation;
+                // A second allocation site -- a physical variant of the same body, or
+                // a declaration lowered twice -- is a second evaluation as far as this
+                // census can tell, so it fails closed.
+                if (!region || cyclic.has(blockId) || once.has(declaration))
+                    repeated.add(declaration);
+                else
+                    once.add(declaration);
+            }
+        }
+    }
+    for (const declaration of repeated)
+        once.delete(declaration);
+    return once;
+};

package/dist/ir/class-static-fields.d.ts

@@ -0,0 +1,60 @@
+import type { DeclarationId } from '../identity/ids.js';
+import type { ClassLayout } from '../projection/classes.js';
+import { type Representation } from '../representation/model.js';
+import type { IrBody } from './model.js';
+/**
+ * Every `ClassName.KEY = value` site the whole program's lowered bodies
+ * contain, folded into one table keyed by (class declaration, key).
+ *
+ * Walked over the IR, not the semantic graph: whether a receiver's carrier
+ * really is `constructor-family`, and which class(es) it names, is a
+ * representation-plan answer, and a lowered `IrOperand` already carries it
+ * (`operation.receiver.representation`) -- re-deriving that from the semantic
+ * graph would risk a second opinion that could disagree with the one the plan
+ * actually selected.
+ *
+ * This lives in `ir/` rather than in the C++ target, which is where it was
+ * first written, because two unrelated consumers need the same answer and the
+ * fact itself is an IR fact. The target adds the mangled C++ storage name it
+ * renders through; the reflection census asks only whether the slot exists and
+ * what carrier it holds. Had the census stayed in the target, the census would
+ * have had to re-derive it -- exactly the two-authorities drift the original
+ * comment warns about.
+ *
+ * A computed key, or a key no `constant` operation in the SAME body accounts
+ * for, is skipped rather than guessed at: nothing downstream can declare
+ * storage for a name it cannot read back off the body's own operations. A
+ * static METHOD or ACCESSOR key is skipped because each already has a callable
+ * home. Declared static fields are claimed from the store their class-lifecycle
+ * event lowers: that store carries the initializer's selected representation
+ * and runs in the enclosing region's source order, so the census needs no
+ * second opinion about either the field's type or its initial value.
+ *
+ * Two writes to the same (declaration,key) whose VALUE representations
+ * disagree are refused together (`conflicts`) rather than one silently
+ * overwriting the storage the other implied: a consumer that later widened one
+ * writer's value into the other's carrier would be inventing a conversion this
+ * census never proved sound. `conflicts` names each such pair as
+ * `"<declaration>.<key>"`; the caller decides what a non-empty list means.
+ */
+export interface ClassStaticFieldSlots {
+    readonly slots: ReadonlyMap<DeclarationId, ReadonlyMap<string, Representation>>;
+    readonly conflicts: readonly string[];
+}
+/**
+ * Which class of a `constructor-family`'s members owns `key`'s static storage.
+ *
+ * The one selection rule, so the census and every later lookup name the same
+ * class for the same receiver. A key no static member declares is the
+ * assignment-only idiom and belongs to the first member that could hold it. A
+ * declared static FIELD has the same storage requirement, since its
+ * class-lifecycle event has already become an ordinary `set` at the exact
+ * evaluation point. Methods and accessors remain callable members and must not
+ * acquire a second storage location.
+ */
+export declare const staticFieldOwnerOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>, members: readonly DeclarationId[], key: string) => DeclarationId | undefined;
+/** The class one class's static storage lives in: itself, or the generic root whose layouts it is one of. */
+export declare const staticStorageOwnerOf: (classes: ReadonlyMap<DeclarationId, ClassLayout>, declaration: DeclarationId) => DeclarationId;
+/** The carrier `ClassName.KEY` is stored in, or null when the census proved none. */
+export declare const staticFieldSlotOf: (census: ClassStaticFieldSlots, classes: ReadonlyMap<DeclarationId, ClassLayout>, members: readonly DeclarationId[], key: string) => Representation | null;
+export declare const censusClassStaticFieldSlots: (bodies: readonly IrBody[], classes: ReadonlyMap<DeclarationId, ClassLayout>) => ClassStaticFieldSlots;