@geastack/compiler 1.0.15

package/dist/semantics/model/coverage.js

@@ -0,0 +1,73 @@
+/**
+ * The reusable primitive families. Every supported behavior reduces to one of
+ * these; a proposed behavior that fits none of them is not yet designed.
+ */
+export const primitiveFamilies = [
+    /** Values and CFG: truthiness, equality, typeof, joins, evaluation order. */
+    'P0',
+    /** Objects and properties: the object internal methods over any carrier. */
+    'P1',
+    /** Callables and closures: call, allocation, capture, escape. */
+    'P2',
+    /** Specialization and narrowing: one authority-connected fixed point. */
+    'P3',
+    /** Iterables and collections: iterator protocol plus Array/Map/Set. */
+    'P4',
+    /** Proxy and Reflect over the same object substrate. */
+    'P5',
+    /** Constructors and classes: newable values and construction semantics. */
+    'P6',
+    /** External host adapter: genuinely external, manifest-authenticated operations. */
+    'H0'
+];
+/**
+ * The dependency order between primitive families.
+ *
+ * A family may only be built on families it depends on. P6 does not depend on
+ * P5: ordinary construction must work before Proxy reuses it, and inverting
+ * that is how proxies end up with a private construction path.
+ */
+export const primitiveDependencies = Object.freeze({
+    P0: [],
+    P1: ['P0'],
+    P2: ['P0'],
+    P3: ['P0', 'P1', 'P2'],
+    P4: ['P1', 'P3'],
+    P6: ['P1', 'P2', 'P3'],
+    P5: ['P1', 'P2', 'P3', 'P6'],
+    H0: ['P1', 'P2']
+});
+/**
+ * Fail closed when a consumer reads a family that has not finished.
+ *
+ * The throw is the point: a consumer that treats `partial` as `complete` will
+ * quietly compile a program whose missing operations were never lowered.
+ */
+export const requireCompleteFamily = (report, consumer) => {
+    if (report.coverage === 'complete')
+        return;
+    throw new Error(`${consumer} read family ${report.family} whose coverage is ${report.coverage}: ` +
+        `${report.operations.length} operation(s) published, ${report.blockers.length} blocker(s) of ${report.censusedCandidates} candidate(s)`);
+};
+/**
+ * A family is internally consistent when every candidate it censused either
+ * published or is a stated blocker.
+ *
+ * The count is of CANDIDATES, not operations. One candidate can mint several
+ * operations -- a compound assignment is a get, a computation and a set -- so
+ * balancing operations against candidates would be a check that passes by
+ * construction and proves nothing.
+ */
+export const validateFamilyReport = (report) => {
+    const accounted = report.publishedCandidates + report.blockers.length;
+    if (accounted !== report.censusedCandidates) {
+        throw new Error(`family ${report.family} censused ${report.censusedCandidates} candidate(s) but accounted for ${accounted}: ` +
+            'every candidate must publish or become a stated blocker');
+    }
+    if (report.coverage === 'complete' && report.blockers.length > 0) {
+        throw new Error(`family ${report.family} claims complete coverage while holding ${report.blockers.length} blocker(s)`);
+    }
+    if (report.coverage === 'not-installed' && report.publishedCandidates > 0) {
+        throw new Error(`family ${report.family} claims not-installed while ${report.publishedCandidates} candidate(s) published`);
+    }
+};

package/dist/semantics/model/edges.d.ts

@@ -0,0 +1,103 @@
+import type { OperationId, SemanticResultId } from '../../identity/ids.js';
+/**
+ * Edges between operations.
+ *
+ * Surface nesting is not a relation. If one operation must run before another,
+ * or one operation's value reaches another, or one operation only runs when a
+ * guard is taken, that must be an edge here. A consumer that recovers ordering
+ * by walking the AST again has left the graph and rediscovered the frontend.
+ */
+/** `from` is evaluated before `to`, and the order is observable. */
+export interface EvaluationEdge {
+    readonly kind: 'evaluation';
+    readonly from: OperationId;
+    readonly to: OperationId;
+}
+/** The value `result` publishes is consumed by `to` in the named operand role. */
+export interface ValueEdge {
+    readonly kind: 'value';
+    readonly result: SemanticResultId;
+    readonly to: OperationId;
+    readonly role: string;
+    readonly ordinal: number;
+}
+/**
+ * `to` observes mutable state that `from` may change, so they cannot be
+ * reordered even though no value flows between them.
+ */
+export interface EffectEdge {
+    readonly kind: 'effect';
+    readonly from: OperationId;
+    readonly to: OperationId;
+}
+/**
+ * `to` executes only when `guard` takes the named branch.
+ *
+ * This is how `a && b`, `a?.b`, and `a ?? b` keep their short-circuiting as a
+ * semantic fact. A producer-to-producer conditional edge names the guard's own
+ * result; it never borrows an operand identity local to the consumer.
+ */
+export interface ConditionalEdge {
+    readonly kind: 'conditional';
+    readonly guard: SemanticResultId;
+    readonly to: OperationId;
+    readonly takenWhen: 'truthy' | 'falsy' | 'nullish' | 'present';
+}
+/** An abrupt completion in `from` transfers control to `to`. */
+export interface CompletionEdge {
+    readonly kind: 'completion';
+    readonly from: OperationId;
+    readonly to: OperationId;
+    readonly completion: 'throw' | 'return' | 'break' | 'continue' | 'suspend';
+}
+/**
+ * `to` executes inside one iteration of `loop`.
+ *
+ * A loop's condition and its body are both inside the iteration; what separates
+ * them is the condition's own `ConditionalEdge`. Stating iteration membership
+ * separately is what lets the lowering put the condition in a block the body can
+ * jump back to, which a guard alone cannot express.
+ */
+export interface LoopEdge {
+    readonly kind: 'loop';
+    readonly loop: OperationId;
+    readonly to: OperationId;
+}
+/**
+ * `to` is the `for` loop's own incrementor, evaluated in a block distinct
+ * from the header.
+ *
+ * ECMA-262's `ForStatement` evaluation re-enters at the update expression on
+ * `continue`, not at the condition -- so the incrementor cannot simply be
+ * "inside the iteration" the way the body is; it needs a scope of its own
+ * that `continue` can jump to and that falls through to the header once it
+ * runs. A `while`, or a `for` with no update clause, mints no operation for
+ * this edge to name, so it never appears for either.
+ */
+export interface LoopLatchEdge {
+    readonly kind: 'loop-latch';
+    readonly loop: OperationId;
+    readonly to: OperationId;
+}
+/**
+ * `to` executes inside one named part (`try`, `catch`, or `finally`) of the
+ * `region` try statement.
+ *
+ * This mirrors `LoopEdge`: a try statement's own operation is not enough to
+ * give its sub-blocks scope membership, because "try", "catch", and "finally"
+ * are three mutually exclusive scopes that share no boolean guard. Publishing
+ * membership as an edge (rather than recovering it positionally from source
+ * ranges) is what lets the flow controller treat a try-region exactly like a
+ * guard or loop: an ordinary `ScopeRef` with its own open/close semantics.
+ */
+export interface RegionEdge {
+    readonly kind: 'region';
+    readonly region: OperationId;
+    readonly part: 'try' | 'catch' | 'finally';
+    readonly to: OperationId;
+}
+export type SemanticEdge = EvaluationEdge | ValueEdge | EffectEdge | ConditionalEdge | CompletionEdge | LoopEdge | LoopLatchEdge | RegionEdge;
+/** The operation an edge originates from, for connectivity traversal. */
+export declare const edgeSource: (edge: SemanticEdge, operationOfResult: (result: SemanticResultId) => OperationId) => OperationId;
+/** The operation an edge terminates at. */
+export declare const edgeTarget: (edge: SemanticEdge) => OperationId;

package/dist/semantics/model/edges.js

@@ -0,0 +1,20 @@
+/** The operation an edge originates from, for connectivity traversal. */
+export const edgeSource = (edge, operationOfResult) => {
+    switch (edge.kind) {
+        case 'evaluation':
+        case 'effect':
+        case 'completion':
+            return edge.from;
+        case 'value':
+            return operationOfResult(edge.result);
+        case 'conditional':
+            return operationOfResult(edge.guard);
+        case 'loop':
+        case 'loop-latch':
+            return edge.loop;
+        case 'region':
+            return edge.region;
+    }
+};
+/** The operation an edge terminates at. */
+export const edgeTarget = (edge) => edge.to;

package/dist/semantics/model/graph.d.ts

@@ -0,0 +1,55 @@
+import type { OperationFamily, OperationId, RegionId, SemanticResultId, StructuralTypeId } from '../../identity/ids.js';
+import type { SemanticEdge } from './edges.js';
+import type { FamilyReport } from './coverage.js';
+import type { SemanticOperation } from './operations.js';
+import type { SemanticCaller } from './operands.js';
+import type { StructuralType } from './structural-types.js';
+/**
+ * The sealed semantic-operation graph.
+ *
+ * This is the frontend/backend boundary. Everything after it consumes these
+ * four tables and the coverage reports; nothing after it may open a TypeScript
+ * AST or ask the checker a question. That restriction is the whole point: it is
+ * what stops two layers from answering the same question differently.
+ */
+/** A non-function execution context. */
+export interface SemanticRegion {
+    readonly id: RegionId;
+    readonly role: 'module-body' | 'field-initializer' | 'static-block' | 'class-evaluation' | 'global';
+    /** The executable subtree, distinct from the declaration that owns it. */
+    readonly bodyNode: string;
+    readonly caller: SemanticCaller | null;
+}
+export interface SemanticGraph {
+    readonly regions: ReadonlyMap<RegionId, SemanticRegion>;
+    readonly structuralTypes: ReadonlyMap<StructuralTypeId, StructuralType>;
+    readonly operations: ReadonlyMap<OperationId, SemanticOperation>;
+    readonly edges: readonly SemanticEdge[];
+    readonly coverage: ReadonlyMap<OperationFamily, FamilyReport>;
+    /** Every published result, so a consumer never re-derives one from an operation. */
+    readonly results: ReadonlyMap<SemanticResultId, OperationId>;
+}
+/** Adjacency built once from the edge table, for authority-connected traversal. */
+export interface SemanticConnectivity {
+    readonly outgoing: ReadonlyMap<OperationId, readonly OperationId[]>;
+    readonly incoming: ReadonlyMap<OperationId, readonly OperationId[]>;
+}
+export declare const buildConnectivity: (graph: SemanticGraph) => SemanticConnectivity;
+/**
+ * The authority-connected component containing `seed`.
+ *
+ * Traversal is undirected because a diagnostic must reach the producer that
+ * failed as well as every consumer left without an answer. The result is sorted
+ * so before/after component counts are comparable across runs.
+ */
+export declare const authorityComponent: (connectivity: SemanticConnectivity, seed: OperationId) => readonly OperationId[];
+export declare const partitionAuthorityComponents: (graph: SemanticGraph) => readonly (readonly OperationId[])[];
+/**
+ * Structural validation of a sealed graph.
+ *
+ * Every check here is an invariant a consumer would otherwise have to re-prove.
+ * A dangling edge, an unpublished result, or a family whose census does not add
+ * up is a producer defect, and finding it at the boundary is far cheaper than
+ * finding it as a wrong answer in emitted C++.
+ */
+export declare const validateGraph: (graph: SemanticGraph) => void;

package/dist/semantics/model/graph.js

@@ -0,0 +1,129 @@
+import { operationOfResult } from '../../identity/ids.js';
+import { edgeSource } from './edges.js';
+import { validateFamilyReport } from './coverage.js';
+export const buildConnectivity = (graph) => {
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const operation of graph.operations.keys()) {
+        outgoing.set(operation, []);
+        incoming.set(operation, []);
+    }
+    const link = (from, to) => {
+        outgoing.get(from)?.push(to);
+        incoming.get(to)?.push(from);
+    };
+    for (const edge of graph.edges)
+        link(edgeSource(edge, operationOfResult), edge.to);
+    // An operand naming another operation's result is an authority link, whether
+    // or not an edge was also minted for it. Reading only the edge table would put
+    // a call and its own callee in different components, which makes a component
+    // one operation and per-component publication meaningless.
+    for (const [id, operation] of graph.operations) {
+        for (const operand of operation.operands) {
+            if (operand.source.kind !== 'result')
+                continue;
+            const producer = graph.results.get(operand.source.result);
+            if (producer !== undefined && producer !== id)
+                link(producer, id);
+        }
+    }
+    return { outgoing, incoming };
+};
+/**
+ * The authority-connected component containing `seed`.
+ *
+ * Traversal is undirected because a diagnostic must reach the producer that
+ * failed as well as every consumer left without an answer. The result is sorted
+ * so before/after component counts are comparable across runs.
+ */
+export const authorityComponent = (connectivity, seed) => {
+    const seen = new Set([seed]);
+    const pending = [seed];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const neighbour of [...(connectivity.outgoing.get(current) ?? []), ...(connectivity.incoming.get(current) ?? [])]) {
+            if (seen.has(neighbour))
+                continue;
+            seen.add(neighbour);
+            pending.push(neighbour);
+        }
+    }
+    return [...seen].sort();
+};
+/**
+ * The partition of one sealed graph, computed once for it.
+ *
+ * Three stages independently ask for this same answer -- carrier publication,
+ * the capability census, and the diagnostic sweep -- and each was paying for its
+ * own full connectivity build plus a sort of every operation identity in the
+ * program. It is a pure function of a graph that is sealed before any of them
+ * runs, so the second and third callers were re-deriving a fact that could not
+ * have changed. Remembered by the graph rather than threaded through three
+ * signatures because the graph is the thing the answer belongs to, and because
+ * a `WeakMap` cannot outlive the compilation that built it.
+ */
+const partitions = new WeakMap();
+export const partitionAuthorityComponents = (graph) => {
+    const remembered = partitions.get(graph);
+    if (remembered)
+        return remembered;
+    const computed = computeAuthorityPartition(graph);
+    partitions.set(graph, computed);
+    return computed;
+};
+const computeAuthorityPartition = (graph) => {
+    const connectivity = buildConnectivity(graph);
+    const assigned = new Set();
+    const components = [];
+    for (const operation of [...graph.operations.keys()].sort()) {
+        if (assigned.has(operation))
+            continue;
+        const component = authorityComponent(connectivity, operation);
+        for (const member of component)
+            assigned.add(member);
+        components.push(component);
+    }
+    return components;
+};
+/**
+ * Structural validation of a sealed graph.
+ *
+ * Every check here is an invariant a consumer would otherwise have to re-prove.
+ * A dangling edge, an unpublished result, or a family whose census does not add
+ * up is a producer defect, and finding it at the boundary is far cheaper than
+ * finding it as a wrong answer in emitted C++.
+ */
+export const validateGraph = (graph) => {
+    for (const report of graph.coverage.values())
+        validateFamilyReport(report);
+    for (const [id, operation] of graph.operations) {
+        if (operation.id !== id)
+            throw new Error(`operation table key ${id} disagrees with operation identity ${operation.id}`);
+        for (const result of operation.results) {
+            const owner = graph.results.get(result.id);
+            if (owner !== id)
+                throw new Error(`result ${result.id} of operation ${id} is registered to ${owner ?? 'nothing'}`);
+            if (!graph.structuralTypes.has(result.type))
+                throw new Error(`result ${result.id} names structural type ${result.type} that is not interned`);
+        }
+        for (const operand of operation.operands) {
+            if (!graph.structuralTypes.has(operand.type)) {
+                throw new Error(`operand ${operand.role}#${operand.ordinal} of ${id} names structural type ${operand.type} that is not interned`);
+            }
+            if (operand.source.kind !== 'result')
+                continue;
+            if (!graph.results.has(operand.source.result)) {
+                throw new Error(`operand ${operand.role}#${operand.ordinal} of ${id} consumes unpublished result ${operand.source.result}`);
+            }
+        }
+    }
+    for (const edge of graph.edges) {
+        const from = edgeSource(edge, operationOfResult);
+        if (!graph.operations.has(from))
+            throw new Error(`edge of kind ${edge.kind} originates at unknown operation ${from}`);
+        if (!graph.operations.has(edge.to))
+            throw new Error(`edge of kind ${edge.kind} terminates at unknown operation ${edge.to}`);
+    }
+};

package/dist/semantics/model/operands.d.ts

@@ -0,0 +1,159 @@
+import type { FunctionId, OperationId, RegionId, ResultRole, SemanticResultId, StructuralTypeId } from '../../identity/ids.js';
+import type { ConversionRoleTarget } from './operations.js';
+/**
+ * Who executes an operation.
+ *
+ * A function caller and a region caller are different identities. `null` is not
+ * a caller: an operation with no owner is a normalization defect, because every
+ * expression in a program executes inside some function body, module body,
+ * initializer, or static block.
+ */
+export type SemanticCaller = {
+    readonly kind: 'function';
+    readonly functionId: FunctionId;
+} | {
+    readonly kind: 'region';
+    readonly regionId: RegionId;
+};
+/**
+ * Where an operand's value comes from.
+ *
+ * `result` is the ordinary case: the value another operation published. A
+ * `constant` carries its own value. `absent` records an operand position the
+ * language defines but this site does not fill -- an omitted array element, a
+ * missing `else` -- and is distinct from an operand whose value is `undefined`.
+ *
+ * `parameter` is the fourth, and it exists because a formal parameter's value
+ * is genuinely none of the other three: the caller's frame supplies it, so no
+ * operation in this body publishes it (`result` is wrong), and its value is
+ * not data known here (`constant` is wrong). Spelling it `absent` would say
+ * the position is unfilled, which is how a parameter ends up read from a cell
+ * nothing ever wrote.
+ *
+ * `receiver` is the same fact for `this`. `ResolveThisBinding` reads the
+ * running execution context's function environment, which the caller
+ * established -- so it is supplied by the frame exactly as a parameter is, and
+ * it carries no ordinal because a convention has at most one receiver.
+ */
+/**
+ * Which of the language's literal forms a constant is.
+ *
+ * The text alone cannot say: the string literal `'undefined'` and the language
+ * value `undefined` both spell themselves `undefined`, and `typeof x !==
+ * 'undefined'` puts the first one in every program that guards an ambient
+ * global. Reading the text and guessing is how the absent value and a five-
+ * letter string become the same operand, so the form is carried rather than
+ * inferred.
+ */
+export type ConstantLiteral = 'string' | 'number' | 'bigint' | 'boolean' | 'null' | 'undefined';
+export type OperandSource = {
+    readonly kind: 'result';
+    readonly result: SemanticResultId;
+} | {
+    readonly kind: 'constant';
+    readonly text: string;
+    readonly literal: ConstantLiteral;
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'parameter';
+    readonly ordinal: number;
+} | {
+    readonly kind: 'receiver';
+};
+/**
+ * Whether an operand is executed here.
+ *
+ * `runtime` operands are evaluated by this operation, in the order they appear.
+ * `provenance` operands are already covered by another operand and must not be
+ * evaluated twice: a member call's callee is one runtime step, and its receiver
+ * is recorded for authority without being re-evaluated.
+ * `conditional` operands are evaluated only when the guard result is taken,
+ * which is how short-circuiting stays a semantic fact rather than an emitter
+ * convention.
+ */
+export type OperandEvaluation = {
+    readonly kind: 'runtime';
+} | {
+    readonly kind: 'provenance';
+} | {
+    readonly kind: 'conditional';
+    readonly guard: SemanticResultId;
+    readonly takenWhen: 'truthy' | 'falsy' | 'nullish' | 'present';
+};
+/** One input to an operation, with its shape and its evaluation behavior. */
+export interface SemanticOperand {
+    /** The role this operand fills in its operation, e.g. `receiver`, `argument`. */
+    readonly role: string;
+    /** Position within a repeated role, so argument order survives normalization. */
+    readonly ordinal: number;
+    readonly source: OperandSource;
+    readonly type: StructuralTypeId;
+    readonly evaluation: OperandEvaluation;
+    /**
+     * For a `spread-argument` operand only: the index its range copy starts
+     * from, when the positions before it were read explicitly. An open-ended
+     * tuple `[A, ...B[]]` spread into `f(a: A, ...rest: B[])` reads `[0]` as
+     * its own positional argument and range-copies the tail from 1
+     * (`spread-arguments.ts`). Absent means 0, the whole source.
+     */
+    readonly from?: number;
+}
+/** One result an operation publishes, keyed by the role it fills. */
+export interface SemanticResult {
+    readonly id: SemanticResultId;
+    readonly role: ResultRole;
+    readonly type: StructuralTypeId;
+}
+/**
+ * How an operation can complete.
+ *
+ * Abrupt completion is part of the operation, not an emitter concern. An
+ * operation that can throw and one that cannot are different semantics, and a
+ * consumer that assumes normal completion must be able to see the difference.
+ */
+export interface CompletionBehavior {
+    readonly canThrow: boolean;
+    readonly canReturn: boolean;
+    readonly canBreak: boolean;
+    readonly canContinue: boolean;
+    readonly canSuspend: boolean;
+}
+export declare const normalCompletion: CompletionBehavior;
+export declare const throwingCompletion: CompletionBehavior;
+/**
+ * Observable effects of an operation.
+ *
+ * These are semantic facts used to order and join operations, never a licence
+ * to skip evaluation. An operation with no recorded effect may still be
+ * ordered by an evaluation edge.
+ */
+export interface EffectBehavior {
+    readonly readsMutableState: boolean;
+    readonly writesMutableState: boolean;
+    readonly allocates: boolean;
+    readonly callsUserCode: boolean;
+}
+export declare const pureEffects: EffectBehavior;
+/** Fields every normalized operation carries regardless of its family. */
+export interface SemanticOperationBase {
+    readonly id: OperationId;
+    readonly caller: SemanticCaller;
+    readonly operands: readonly SemanticOperand[];
+    readonly results: readonly SemanticResult[];
+    readonly completion: CompletionBehavior;
+    readonly effects: EffectBehavior;
+    /** Exact storage targets published by the producer for operand conversion roles it owns. */
+    readonly conversionRoles?: readonly ConversionRoleTarget[];
+    /**
+     * The order this operation's own evaluation occupies within its caller. It
+     * orders siblings; it is not a source offset and carries no file position.
+     */
+    readonly evaluationOrdinal: number;
+}
+/** The operand filling one role, or `undefined` when the site omits it. */
+export declare const operandOf: (operation: SemanticOperationBase, role: string, ordinal?: number) => SemanticOperand | undefined;
+/** The result filling one role, or `undefined` when the operation omits it. */
+export declare const resultOf: (operation: SemanticOperationBase, role: ResultRole) => SemanticResult | undefined;
+/** The operands this operation actually evaluates, in evaluation order. */
+export declare const runtimeOperands: (operation: SemanticOperationBase) => readonly SemanticOperand[];

package/dist/semantics/model/operands.js

@@ -0,0 +1,26 @@
+export const normalCompletion = Object.freeze({
+    canThrow: false,
+    canReturn: false,
+    canBreak: false,
+    canContinue: false,
+    canSuspend: false
+});
+export const throwingCompletion = Object.freeze({
+    canThrow: true,
+    canReturn: false,
+    canBreak: false,
+    canContinue: false,
+    canSuspend: false
+});
+export const pureEffects = Object.freeze({
+    readsMutableState: false,
+    writesMutableState: false,
+    allocates: false,
+    callsUserCode: false
+});
+/** The operand filling one role, or `undefined` when the site omits it. */
+export const operandOf = (operation, role, ordinal = 0) => operation.operands.find((operand) => operand.role === role && operand.ordinal === ordinal);
+/** The result filling one role, or `undefined` when the operation omits it. */
+export const resultOf = (operation, role) => operation.results.find((result) => result.role === role);
+/** The operands this operation actually evaluates, in evaluation order. */
+export const runtimeOperands = (operation) => operation.operands.filter((operand) => operand.evaluation.kind !== 'provenance');