@geastack/compiler 1.0.15

package/dist/diagnostics/sweep.js

@@ -0,0 +1,112 @@
+import { componentId, nodeOfOperation, operationOfResult } from '../identity/ids.js';
+import { partitionAuthorityComponents } from '../semantics/model/graph.js';
+import { createDiagnosticSink } from './model.js';
+/**
+ * The component a blocked census candidate belongs to.
+ *
+ * A candidate that never became an operation never joined a component, so there
+ * is no real one to name. The synthetic id is per family and says so; deriving a
+ * plausible-looking real component would let a reader join these rows against
+ * the graph and get an answer that is wrong.
+ */
+const censusComponent = (family) => componentId(`op|census|${family}|0`);
+const componentIndexOf = (graph) => {
+    const index = new Map();
+    for (const members of partitionAuthorityComponents(graph)) {
+        const representative = members[0];
+        if (!representative)
+            continue;
+        const id = componentId(representative);
+        for (const member of members)
+            index.set(member, id);
+    }
+    return index;
+};
+const censusDiagnostics = (graph, locate) => [...graph.coverage.values()].flatMap((report) => report.blockers.map((blocker) => ({
+    id: `census/${report.family}/${blocker.source}/${blocker.reason}`,
+    // A withheld member states that it was withheld, so it is derived from
+    // the blocked member of its component rather than a defect of its own.
+    severity: blocker.reason.startsWith('withheld:') ? 'derived' : 'root',
+    component: censusComponent(report.family),
+    operation: null,
+    missingPrimitive: blocker.missingPrimitive,
+    // The candidate is named in the message because the component is
+    // synthetic and identical for every row of a family; without it, thirteen
+    // distinct blocked candidates print as thirteen identical lines.
+    message: `${blocker.reason} (candidate ${blocker.source})`,
+    location: locate(blocker.source),
+    causedBy: []
+})));
+const representationDiagnostics = (publication, components, locate) => publication.violations.map((violation) => {
+    const operation = violation.result ? operationOfResult(violation.result) : null;
+    return {
+        id: `representation/${violation.guard}/${violation.result ?? 'plan'}`,
+        severity: 'root',
+        component: (operation ? components.get(operation) : null) ?? censusComponent('reference'),
+        operation,
+        missingPrimitive: null,
+        message: violation.message,
+        location: operation ? locate(nodeOfOperation(operation)) : null,
+        causedBy: []
+    };
+});
+const preflightDiagnostics = (report, locate) => {
+    // Optional rows are excluded here, not merely de-emphasized. An optional
+    // obligation names a fast path the mandatory generic one already covers, so
+    // an unbuilt devirtualization is not a defect in the program or the backend
+    // -- and a report that fails a build over one trains its reader to ignore it.
+    const rows = report.obligations.filter((obligation) => !obligation.optional && obligation.status !== 'satisfied');
+    // A blocked row is explained by the failing rows of its own component, so the
+    // roots are collected per component before the derived rows cite them.
+    const rootsByComponent = new Map();
+    for (const obligation of rows) {
+        if (obligation.status === 'blocked-by-upstream')
+            continue;
+        const bucket = rootsByComponent.get(obligation.component) ?? [];
+        bucket.push(`preflight/${obligation.id}`);
+        rootsByComponent.set(obligation.component, bucket);
+    }
+    return rows.map((obligation) => {
+        const derived = obligation.status === 'blocked-by-upstream';
+        const operation = operationOfResult(obligation.derivesFrom);
+        return {
+            id: `preflight/${obligation.id}`,
+            severity: derived ? 'derived' : obligation.status === 'unsupported' ? 'unsupported' : 'root',
+            component: obligation.component,
+            operation,
+            missingPrimitive: null,
+            message: `${obligation.kind} obligation ${obligation.predicate.id} is ${obligation.status}: ` +
+                `expected ${obligation.predicate.expected}, found ${obligation.predicate.actual}`,
+            location: locate(nodeOfOperation(operation)),
+            causedBy: derived ? [...(rootsByComponent.get(obligation.component) ?? [])].sort() : []
+        };
+    });
+};
+/**
+ * Collect every layer's failures into one deterministically ordered report.
+ *
+ * Optional preflight obligations are deliberately absent: an unavailable fast
+ * path is not a defect, and reporting one as a failure would train a reader to
+ * ignore the report.
+ */
+export const sweepDiagnostics = (input) => {
+    const components = componentIndexOf(input.graph);
+    const locate = input.locationOfNode ?? (() => null);
+    const sink = createDiagnosticSink();
+    for (const evidence of input.frontend)
+        sink.report({ ...evidence, severity: 'root', causedBy: [] });
+    for (const diagnostic of censusDiagnostics(input.graph, locate))
+        sink.report(diagnostic);
+    for (const diagnostic of representationDiagnostics(input.representations, components, locate))
+        sink.report(diagnostic);
+    // Everything above is the plan's own verdict; everything below is
+    // preflight's plan-level census (carriers, call paths, native boundaries).
+    // Lowering runs on the first alone (`DiagnosticReport.planClean`); the
+    // site-level capabilities are certified off the IR afterwards and are
+    // `CompileResult.refusals`, not diagnostics.
+    const planClean = sink.cleanSoFar();
+    if (input.preflight)
+        for (const diagnostic of preflightDiagnostics(input.preflight, locate))
+            sink.report(diagnostic);
+    return sink.finish([...new Set(components.values())], planClean);
+};

package/dist/identity/ids.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Canonical identities.
+ *
+ * Every later fact in the compiler is keyed by one of these. A source offset,
+ * file name, declaration spelling, or rendered C++ string is never an identity
+ * here: those are display evidence, and admitting them as identity is what lets
+ * two spellings of one operation acquire two answers.
+ *
+ * The identities are opaque strings at runtime and distinct types at compile
+ * time, so a `DeclarationId` cannot be passed where an `OperationId` belongs
+ * even though both are strings once erased.
+ */
+declare const brand: unique symbol;
+/** A string identity that only its own minting function can produce. */
+type Branded<Name extends string> = string & {
+    readonly [brand]: Name;
+};
+/** A syntactic position in the source universe, used for joins and display. */
+export type NodeId = Branded<'NodeId'>;
+/** A checker declaration, stable across every reference that resolves to it. */
+export type DeclarationId = Branded<'DeclarationId'>;
+/** A source function, distinct from the physical bodies it may be lowered into. */
+export type FunctionId = Branded<'FunctionId'>;
+/** A non-function execution context: module body, initializer, static block. */
+export type RegionId = Branded<'RegionId'>;
+/** A canonical structural shape, target-neutral and free of C++ spelling. */
+export type StructuralTypeId = Branded<'StructuralTypeId'>;
+/** One normalized ECMAScript operation. */
+export type OperationId = Branded<'OperationId'>;
+/** One published semantic result: an operation plus the role it fills. */
+export type SemanticResultId = Branded<'SemanticResultId'>;
+/** One authority-connected component of the semantic graph. */
+export type ComponentId = Branded<'ComponentId'>;
+/** An SSA value in typed IR. */
+export type IrValueId = Branded<'IrValueId'>;
+/** A physical function body: one owner plus one ABI variant. */
+export type PhysicalBodyId = Branded<'PhysicalBodyId'>;
+/**
+ * The families a normalized operation can belong to. This list is the semantic
+ * vocabulary of the frontend; a new family is an architecture decision, never a
+ * convenience for one source shape.
+ */
+export declare const operationFamilies: readonly ["invocation", "property", "binding", "allocation", "class-lifecycle", "computation", "control", "reference", "declaration-lifecycle", "destructuring", "protocol", "boundary", "dynamic-language", "element"];
+export type OperationFamily = (typeof operationFamilies)[number];
+/**
+ * The role a value plays in its operation's result. One operation may publish
+ * more than one result -- an optional call publishes both its call result and
+ * its short-circuit path -- and each is a separate authority coordinate.
+ */
+export declare const resultRoles: readonly ["value", "completion", "reference", "iterator-record", "short-circuit"];
+export type ResultRole = (typeof resultRoles)[number];
+/** Identity of a source position. Callers pass the checker's own coordinates. */
+export declare const nodeId: (fileIdentity: string, kind: string, ordinal: number, specialization?: string) => NodeId;
+/**
+ * The same identity with its monomorphization suffix removed -- the ROOT copy's
+ * id, which is the one a source position is indexed under.
+ *
+ * A copy has no source text of its own: `identity<number>` and
+ * `identity<string>` are two functions cut from one body, and only that body is
+ * in a file. So anything that maps an identity back to a `ts.Node` -- which is
+ * every diagnostic that wants to say `file:line:column` -- has to ask about the
+ * root when the copy misses, or a monomorphized program reports its refusals
+ * with no location at all. That was the state: an unmet obligation inside any
+ * generic printed its component id and nothing else.
+ *
+ * Only the LAST segment is trimmed. `@` cannot appear in a file identity (they
+ * are `f<index>`) or in a syntax-kind name, and the suffix is a chain of
+ * ordinals appended after the node's own ordinal, so the first `@` past the
+ * final `|` starts the specialization and nothing else can.
+ */
+export declare const withoutSpecialization: <Id extends NodeId | DeclarationId>(id: Id) => Id;
+/**
+ * The (file, ordinal) coordinate a NodeId and a DeclarationId of the same node
+ * share, with the syntax-kind name -- present only in a NodeId -- and any
+ * monomorphization suffix both dropped.
+ *
+ * `identities.ts`'s ordinal walk assigns one ordinal per node per file
+ * regardless of syntax kind, so kind is never needed to tell two ordinals
+ * apart; it exists only to keep a NodeId's own spelling self-describing. Two
+ * callers that resolve a source position -- `locationOfNode`, keyed by a
+ * NodeId, and a caller holding only a DeclarationId or FunctionId -- are
+ * asking the same question, and this is what lets both resolve through the
+ * ONE index frontend.ts builds, rather than a second index being built to
+ * answer the DeclarationId-shaped question in a different currency.
+ */
+export declare const positionKeyOfNode: (id: NodeId) => string;
+/** `positionKeyOfNode`'s twin for a DeclarationId, which never carries a kind segment to drop. */
+export declare const positionKeyOfDeclaration: (id: DeclarationId) => string;
+/** Identity of a declaration, keyed by the file and declaration ordinal, and by which monomorphized copy it belongs to. */
+export declare const declarationId: (fileIdentity: string, ordinal: number, specialization?: string) => DeclarationId;
+/** Identity of a source function. */
+export declare const functionId: (declaration: DeclarationId) => FunctionId;
+/**
+ * The declaration a source-function identity was minted from.
+ *
+ * Kept beside `functionId` because this file owns the spelling. Consumers
+ * must not strip the `fn|` prefix themselves and thereby become a second
+ * authority over identity structure.
+ */
+export declare const declarationOfFunction: (id: FunctionId) => DeclarationId;
+/** The root source function shared by all monomorphized copies of one declaration. */
+export declare const withoutFunctionSpecialization: (id: FunctionId) => FunctionId;
+/** Identity of a non-function execution region. */
+export declare const regionId: (owner: DeclarationId | NodeId, role: string) => RegionId;
+/**
+ * Identity of a normalized operation.
+ *
+ * One AST node can normalize to several operations -- compound assignment is a
+ * property get, a computation, and a property set -- so the ordinal separates
+ * them. Two source spellings that mean the same thing must reach the same
+ * family and ordinal, and therefore the same identity.
+ */
+export declare const operationId: (source: NodeId, family: OperationFamily, ordinal: number) => OperationId;
+/** Identity of one published result of one operation. */
+export declare const semanticResultId: (operation: OperationId, role: ResultRole) => SemanticResultId;
+/** Identity of an authority-connected component, keyed by its lowest member. */
+export declare const componentId: (representative: OperationId) => ComponentId;
+/** Identity of a typed-IR SSA value inside one physical body. */
+export declare const irValueId: (body: PhysicalBodyId, ordinal: number) => IrValueId;
+/** Identity of a physical body: the owner it lowers and the ABI variant chosen. */
+export declare const physicalBodyId: (owner: FunctionId | RegionId, variantKey: string) => PhysicalBodyId;
+/**
+ * The operation an already-minted result belongs to.
+ *
+ * A result is `result|<operation>|<role>` by construction (`semanticResultId`),
+ * so the operation is everything between the fixed prefix and the last
+ * separator -- one substring, taken directly.
+ *
+ * It was a `split('|')` + `slice` + `join('|')`, which is the same answer built
+ * by allocating an array of every segment and then a fresh string from most of
+ * them. That is invisible per call and decisive in aggregate: this runs at least
+ * once per graph EDGE (`model/graph.ts`), and a large program has hundreds of
+ * thousands, which put `String.prototype.split` at 38% of the whole corpus run's
+ * samples. A role never contains the separator -- the roles are a closed set
+ * (`resultRoles`) -- so `lastIndexOf` finds exactly the boundary the join
+ * reconstructed, and an operation that contains separators of its own is
+ * carried through untouched rather than taken apart and put back together.
+ */
+export declare const operationOfResult: (result: SemanticResultId) => OperationId;
+/**
+ * The source node one operation normalized from.
+ *
+ * The inverse of `operationId`'s own join, and here for the same reason
+ * `operationOfResult` is: this file mints the spelling, so this file is the
+ * only place allowed to read it back. Exact rather than heuristic -- `encode`
+ * escapes every `|` inside a part, so an operation identity has precisely two
+ * separators after its node's, and stripping them cannot cut into the node.
+ *
+ * A DIAGNOSTIC's reason to exist: a report that names a component and no file
+ * cannot tell a reader which module failed to compile, and 334 unmet
+ * obligations printed as component ids were 334 rows nobody could act on.
+ */
+export declare const nodeOfOperation: (operation: OperationId) => NodeId;
+/**
+ * Whether an owner identity names a non-function execution region.
+ *
+ * The one question a consumer may ask about an owner's *shape*, and it lives
+ * here for the same reason `operationOfResult` does: this file mints the
+ * spelling, so this file is the only place allowed to read it back. A caller
+ * that tested the prefix itself would become a second authority over a
+ * structure only `regionId` defines.
+ */
+export declare const isRegionId: (owner: FunctionId | RegionId) => owner is RegionId;
+/**
+ * The file identity a declaration, function or region was minted in.
+ *
+ * Read back here for the same reason `operationOfResult` and `isRegionId` are:
+ * this file writes `decl|<file>|...`, `fn|decl|<file>|...` and
+ * `region|<decl or node>|<file>|...`, so this file is the only place allowed to
+ * take the file segment back out. The identity is an INDEX (`f12`), never a
+ * path -- a consumer that wants to display it asks the frontend's
+ * `sourceFileNames`, which is display evidence and nothing else. The one
+ * consumer today is the per-file translation-unit layout, which groups bodies
+ * by the file that declared them and needs no other fact about that file.
+ */
+export declare const fileIdentityOf: (owner: FunctionId | RegionId | DeclarationId) => string;
+/** The role an already-minted result fills. */
+export declare const roleOfResult: (result: SemanticResultId) => ResultRole;
+export {};

package/dist/identity/ids.js

@@ -0,0 +1,212 @@
+/**
+ * Canonical identities.
+ *
+ * Every later fact in the compiler is keyed by one of these. A source offset,
+ * file name, declaration spelling, or rendered C++ string is never an identity
+ * here: those are display evidence, and admitting them as identity is what lets
+ * two spellings of one operation acquire two answers.
+ *
+ * The identities are opaque strings at runtime and distinct types at compile
+ * time, so a `DeclarationId` cannot be passed where an `OperationId` belongs
+ * even though both are strings once erased.
+ */
+/**
+ * The families a normalized operation can belong to. This list is the semantic
+ * vocabulary of the frontend; a new family is an architecture decision, never a
+ * convenience for one source shape.
+ */
+export const operationFamilies = [
+    'invocation',
+    'property',
+    'binding',
+    'allocation',
+    'class-lifecycle',
+    'computation',
+    'control',
+    'reference',
+    'declaration-lifecycle',
+    'destructuring',
+    'protocol',
+    'boundary',
+    'dynamic-language',
+    'element'
+];
+/**
+ * The role a value plays in its operation's result. One operation may publish
+ * more than one result -- an optional call publishes both its call result and
+ * its short-circuit path -- and each is a separate authority coordinate.
+ */
+export const resultRoles = ['value', 'completion', 'reference', 'iterator-record', 'short-circuit'];
+const encode = (part) => part.replace(/[|]/g, '%7C');
+/** Identity of a source position. Callers pass the checker's own coordinates. */
+export const nodeId = (fileIdentity, kind, ordinal, specialization = '') => `node|${encode(fileIdentity)}|${encode(kind)}|${ordinal}${specializationSuffix(specialization)}`;
+/**
+ * The suffix that separates one monomorphized copy of a body from another.
+ *
+ * A generic body exists once per instantiation, so the copies need distinct
+ * identities -- `identity<number>` and `identity<string>` are two functions with
+ * two ABIs, and one identity for both would make every later stage answer one
+ * question for two programs.
+ *
+ * The suffix is a chain of ORDINALS, never the spelling of a type argument:
+ * `@0` is the first instantiation the deterministic walk reached, exactly as a
+ * node is identified by its position in that same walk. It nests, because a
+ * generic inside a generic is copied once per pair. An empty specialization
+ * adds nothing at all, which keeps every identity in a program with no generics
+ * byte-identical to what it was before monomorphization existed.
+ */
+const specializationSuffix = (specialization) => (specialization === '' ? '' : `@${encode(specialization)}`);
+/**
+ * The same identity with its monomorphization suffix removed -- the ROOT copy's
+ * id, which is the one a source position is indexed under.
+ *
+ * A copy has no source text of its own: `identity<number>` and
+ * `identity<string>` are two functions cut from one body, and only that body is
+ * in a file. So anything that maps an identity back to a `ts.Node` -- which is
+ * every diagnostic that wants to say `file:line:column` -- has to ask about the
+ * root when the copy misses, or a monomorphized program reports its refusals
+ * with no location at all. That was the state: an unmet obligation inside any
+ * generic printed its component id and nothing else.
+ *
+ * Only the LAST segment is trimmed. `@` cannot appear in a file identity (they
+ * are `f<index>`) or in a syntax-kind name, and the suffix is a chain of
+ * ordinals appended after the node's own ordinal, so the first `@` past the
+ * final `|` starts the specialization and nothing else can.
+ */
+export const withoutSpecialization = (id) => {
+    const lastSeparator = id.lastIndexOf('|');
+    const at = id.indexOf('@', lastSeparator + 1);
+    return (at < 0 ? id : id.slice(0, at));
+};
+/**
+ * The (file, ordinal) coordinate a NodeId and a DeclarationId of the same node
+ * share, with the syntax-kind name -- present only in a NodeId -- and any
+ * monomorphization suffix both dropped.
+ *
+ * `identities.ts`'s ordinal walk assigns one ordinal per node per file
+ * regardless of syntax kind, so kind is never needed to tell two ordinals
+ * apart; it exists only to keep a NodeId's own spelling self-describing. Two
+ * callers that resolve a source position -- `locationOfNode`, keyed by a
+ * NodeId, and a caller holding only a DeclarationId or FunctionId -- are
+ * asking the same question, and this is what lets both resolve through the
+ * ONE index frontend.ts builds, rather than a second index being built to
+ * answer the DeclarationId-shaped question in a different currency.
+ */
+export const positionKeyOfNode = (id) => {
+    const parts = withoutSpecialization(id).split('|');
+    return `${parts[1]}|${parts[3]}`;
+};
+/** `positionKeyOfNode`'s twin for a DeclarationId, which never carries a kind segment to drop. */
+export const positionKeyOfDeclaration = (id) => {
+    const parts = withoutSpecialization(id).split('|');
+    return `${parts[1]}|${parts[2]}`;
+};
+/** Identity of a declaration, keyed by the file and declaration ordinal, and by which monomorphized copy it belongs to. */
+export const declarationId = (fileIdentity, ordinal, specialization = '') => `decl|${encode(fileIdentity)}|${ordinal}${specializationSuffix(specialization)}`;
+/** Identity of a source function. */
+export const functionId = (declaration) => `fn|${declaration}`;
+/**
+ * The declaration a source-function identity was minted from.
+ *
+ * Kept beside `functionId` because this file owns the spelling. Consumers
+ * must not strip the `fn|` prefix themselves and thereby become a second
+ * authority over identity structure.
+ */
+export const declarationOfFunction = (id) => id.slice('fn|'.length);
+/** The root source function shared by all monomorphized copies of one declaration. */
+export const withoutFunctionSpecialization = (id) => functionId(withoutSpecialization(declarationOfFunction(id)));
+/** Identity of a non-function execution region. */
+export const regionId = (owner, role) => `region|${owner}|${encode(role)}`;
+/**
+ * Identity of a normalized operation.
+ *
+ * One AST node can normalize to several operations -- compound assignment is a
+ * property get, a computation, and a property set -- so the ordinal separates
+ * them. Two source spellings that mean the same thing must reach the same
+ * family and ordinal, and therefore the same identity.
+ */
+export const operationId = (source, family, ordinal) => `op|${source}|${family}|${ordinal}`;
+/** Identity of one published result of one operation. */
+export const semanticResultId = (operation, role) => `result|${operation}|${role}`;
+/** The fixed prefix `semanticResultId` writes, so readers strip exactly what it wrote. */
+const resultPrefixLength = 'result|'.length;
+/** Identity of an authority-connected component, keyed by its lowest member. */
+export const componentId = (representative) => `component|${representative}`;
+/** Identity of a typed-IR SSA value inside one physical body. */
+export const irValueId = (body, ordinal) => `ssa|${body}|${ordinal}`;
+/** Identity of a physical body: the owner it lowers and the ABI variant chosen. */
+export const physicalBodyId = (owner, variantKey) => `body|${owner}|${encode(variantKey)}`;
+/**
+ * The operation an already-minted result belongs to.
+ *
+ * A result is `result|<operation>|<role>` by construction (`semanticResultId`),
+ * so the operation is everything between the fixed prefix and the last
+ * separator -- one substring, taken directly.
+ *
+ * It was a `split('|')` + `slice` + `join('|')`, which is the same answer built
+ * by allocating an array of every segment and then a fresh string from most of
+ * them. That is invisible per call and decisive in aggregate: this runs at least
+ * once per graph EDGE (`model/graph.ts`), and a large program has hundreds of
+ * thousands, which put `String.prototype.split` at 38% of the whole corpus run's
+ * samples. A role never contains the separator -- the roles are a closed set
+ * (`resultRoles`) -- so `lastIndexOf` finds exactly the boundary the join
+ * reconstructed, and an operation that contains separators of its own is
+ * carried through untouched rather than taken apart and put back together.
+ */
+export const operationOfResult = (result) => result.slice(resultPrefixLength, result.lastIndexOf('|'));
+/**
+ * The source node one operation normalized from.
+ *
+ * The inverse of `operationId`'s own join, and here for the same reason
+ * `operationOfResult` is: this file mints the spelling, so this file is the
+ * only place allowed to read it back. Exact rather than heuristic -- `encode`
+ * escapes every `|` inside a part, so an operation identity has precisely two
+ * separators after its node's, and stripping them cannot cut into the node.
+ *
+ * A DIAGNOSTIC's reason to exist: a report that names a component and no file
+ * cannot tell a reader which module failed to compile, and 334 unmet
+ * obligations printed as component ids were 334 rows nobody could act on.
+ */
+export const nodeOfOperation = (operation) => {
+    const last = operation.lastIndexOf('|');
+    const family = operation.lastIndexOf('|', last - 1);
+    return operation.slice('op|'.length, family);
+};
+/**
+ * Whether an owner identity names a non-function execution region.
+ *
+ * The one question a consumer may ask about an owner's *shape*, and it lives
+ * here for the same reason `operationOfResult` does: this file mints the
+ * spelling, so this file is the only place allowed to read it back. A caller
+ * that tested the prefix itself would become a second authority over a
+ * structure only `regionId` defines.
+ */
+export const isRegionId = (owner) => owner.startsWith('region|');
+const decode = (part) => part.replace(/%7C/g, '|');
+/**
+ * The file identity a declaration, function or region was minted in.
+ *
+ * Read back here for the same reason `operationOfResult` and `isRegionId` are:
+ * this file writes `decl|<file>|...`, `fn|decl|<file>|...` and
+ * `region|<decl or node>|<file>|...`, so this file is the only place allowed to
+ * take the file segment back out. The identity is an INDEX (`f12`), never a
+ * path -- a consumer that wants to display it asks the frontend's
+ * `sourceFileNames`, which is display evidence and nothing else. The one
+ * consumer today is the per-file translation-unit layout, which groups bodies
+ * by the file that declared them and needs no other fact about that file.
+ */
+export const fileIdentityOf = (owner) => {
+    const parts = owner.split('|');
+    const segment = parts[0] === 'decl' ? parts[1] : parts[2];
+    if (segment === undefined)
+        throw new Error(`identity ${owner} carries no file segment`);
+    return decode(segment);
+};
+/** The role an already-minted result fills. */
+export const roleOfResult = (result) => {
+    const role = result.slice(result.lastIndexOf('|') + 1);
+    const known = resultRoles.find((candidate) => candidate === role);
+    if (!known)
+        throw new Error(`semantic result ${result} does not carry a known result role`);
+    return known;
+};

package/dist/ir/absent-class-arm.d.ts

@@ -0,0 +1,48 @@
+import type { DeclarationId, PhysicalBodyId } from '../identity/ids.js';
+import type { ClassLayout } from '../projection/classes.js';
+import type { Representation } from '../representation/model.js';
+import type { GetOperation, IrBody } from './model.js';
+import type { ReflectionExposure } from './reflection-demand.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 declare const classFamilyLacksKey: (classes: ReadonlyMap<DeclarationId, ClassLayout>, declaration: DeclarationId, key: string) => boolean;
+/** The census half: `surface` is a class arm of the union `receiver` that answers this read with `undefined`. */
+export declare const absentClassArmRead: (receiver: Representation, surface: Representation, key: string, result: Representation, classes: ReadonlyMap<DeclarationId, ClassLayout>) => surface is Extract<Representation, {
+    kind: "class-ref";
+}>;
+/** Certification's re-check of a published stamp against the same proof and the closed exposure. */
+export declare const absentClassArmsHold: (operation: GetOperation, key: string | null, classes: ReadonlyMap<DeclarationId, ClassLayout>, exposure: ReflectionExposure | undefined) => boolean;
+/**
+ * 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 declare const finalizeAbsentClassArms: (bodies: ReadonlyMap<PhysicalBodyId, IrBody>, exposure: ReflectionExposure, classes: ReadonlyMap<DeclarationId, ClassLayout>) => ReadonlyMap<PhysicalBodyId, IrBody>;