@geastack/compiler 1.0.15

package/dist/ir/lower-graph.d.ts

@@ -0,0 +1,218 @@
+import type { FunctionId, OperationId, RegionId, SemanticResultId } from '../identity/ids.js';
+import type { Representation } from '../representation/model.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { SemanticEdge } from '../semantics/model/edges.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import { type SemanticCaller } from '../semantics/model/operands.js';
+import type { SemanticOperation } from '../semantics/model/operations.js';
+/**
+ * Shared owner-grouping, ordering, and lookup primitives for IR lowering.
+ *
+ * `lowerToIr` must abort one owner without harming another, so every failure
+ * here is thrown as `IrLoweringBlockedError` and caught once, at the single
+ * per-owner boundary in `lower.ts`. That keeps every helper a plain function
+ * that either returns an answer or fails closed -- never a `Result` type
+ * threaded through a dozen call sites, and never a silent partial answer.
+ */
+/** Thrown to abort lowering of exactly one owner. The message states the missing capability, never a source site. */
+export declare class IrLoweringBlockedError extends Error {
+    constructor(reason: string);
+}
+export type OwnerId = FunctionId | RegionId;
+export declare const callerOwner: (caller: SemanticCaller) => OwnerId;
+/** Every operation, bucketed by the owner that executes it. One bucket becomes one `IrBody`. */
+export declare const groupOperationsByOwner: (graph: SemanticGraph) => ReadonlyMap<OwnerId, readonly OperationId[]>;
+/**
+ * The published result an operation's own IR lowering cites as `lineage`.
+ *
+ * `null` when the operation published no result at all. That is a real gap
+ * between the semantic model (a step may publish nothing) and the IR model
+ * (`IrOperationBase.lineage` is mandatory): lowering cannot invent a
+ * `SemanticResultId` the operation never published without becoming a second,
+ * competing authority over what that operation's identity is, so the caller
+ * must fail closed instead.
+ */
+export declare const anchorResultOf: (operation: SemanticOperation) => SemanticResultId | null;
+/** The one authoritative carrier for a published result, or a thrown blocker naming why it cannot materialize. */
+export declare const requireRepresentation: (plan: SealedRepresentationPlan, result: SemanticResultId, describe: string) => Representation;
+/**
+ * A deterministic execution order for one owner's operations.
+ *
+ * Precedence comes only from graph facts: an operand that consumes another
+ * operation's result must run after it, `EvaluationEdge`/`EffectEdge` state an
+ * explicit "before" relation, and a `ConditionalEdge` orders a guard before
+ * whatever it gates (the branch itself is built later; only cycle-free
+ * sequencing is decided here). Source order never enters this computation.
+ *
+ * Among operations the graph leaves mutually unordered, conditional membership
+ * decides which runs next: an order is only executable if one branch's
+ * operations are *contiguous*. Blocks are how a branch exists, and a block that
+ * has been left cannot be appended to -- so an order that runs an arm, then
+ * something outside the guard, then that same arm again describes control flow
+ * no basic-block graph can express. That is not hypothetical: the module body
+ * of `sky-hop-jsx`'s `Controls.tsx` computes one `?:` while a dozen unrelated
+ * import bindings sit at the same evaluation ordinal, and ordering by ordinal
+ * alone interleaved them -- the arm was re-entered after it had jumped to its
+ * join, the lowering opened an unreachable block to hold the rest of the arm,
+ * and the owner was rejected for sealing a block reached from nothing.
+ *
+ * Contiguity is a preference over the *ready* set, never an override of
+ * precedence: the operation whose scope chain shares the longest prefix with
+ * the one just emitted wins, and `evaluationOrdinal` still breaks every
+ * remaining tie. Nothing that is not yet legal to run becomes legal.
+ *
+ * A cycle means the graph asked for two operations to each run before the
+ * other, which is a producer defect -- not something an emitter may resolve
+ * by picking one direction, so it is reported as a blocker instead.
+ */
+/**
+ * Every `region` edge's target, grouped by the region part it belongs to.
+ *
+ * Built from the WHOLE edge table and shared by every owner, deliberately, and
+ * this is the one table here that may NOT be split per owner. The opener below
+ * is `members.find(... family === 'boundary')` -- the FIRST boundary operation
+ * in the group, across the entire program. Handing an owner only its own share
+ * of the group can hand it a different first element than the whole group has,
+ * and `addPrecedence` would then add a real ordering edge where the whole-group
+ * answer added none (the whole-group opener belongs to another owner, so the
+ * precedence was silently dropped). That is a change to emitted order, not an
+ * optimization, so the grouping stays global and only the *scan* is hoisted out
+ * of the per-owner loop.
+ */
+export type RegionPartMembers = ReadonlyMap<string, readonly OperationId[]>;
+export declare const collectRegionParts: (graph: SemanticGraph) => RegionPartMembers;
+/** What `orderOwnerOperations` answers: the owner's execution order, plus which of its own operations belong to `FunctionDeclarationInstantiation`'s own phase -- parameter reads, defaulted-parameter binding, and pattern extraction over a parameter -- see `parameterPrologue` below. */
+export interface OrderedOwnerOperations {
+    readonly order: readonly OperationId[];
+    /**
+     * Every operation this owner's own formals need bound before the body may
+     * run: each parameter's own `binding:initialize` (`parameterInitialization
+     * === true`, set for EVERY parameter whether or not it defaults or
+     * destructures) and everything that operation transitively depends on --
+     * a default's guard and both its arms, a pattern's own extraction steps.
+     *
+     * Named after ECMA-262's own phase (10.2.1 step 8's
+     * `FunctionDeclarationInstantiation`, before `EvaluateGeneratorBody` ever
+     * runs) because that is exactly what this set is: the work a generator's
+     * `[[Call]]` must finish before `GeneratorStart` ever suspends it, which
+     * `ir/lower.ts`'s generator split reads to decide where a coroutine's
+     * OUTER (ordinary) half ends and its INNER (suspending) half begins.
+     *
+     * Computed here rather than published as its own capability because the
+     * ordering pass already builds every fact it needs -- `parameterRoots` and
+     * the `predecessors` graph -- to keep hoisted declarations behind it; a
+     * second walk elsewhere would be a second authority re-deriving the exact
+     * same predecessor closure.
+     */
+    readonly parameterPrologue: ReadonlySet<OperationId>;
+}
+export declare const orderOwnerOperations: (graph: SemanticGraph, operations: readonly OperationId[], membership: ConditionalMembership, 
+/**
+ * The edges whose target this owner holds, in `graph.edges` order.
+ *
+ * Every use of the edge table below is a filter that keeps only edges landing
+ * inside `operations` -- `addPrecedence` refuses any pair with an endpoint
+ * outside `members` -- so passing the owner's own share is the same answer as
+ * passing the whole table, reached without walking owners x edges to get it.
+ * Order is preserved because the share is dealt in table order.
+ */
+ownerEdges: readonly SemanticEdge[], 
+/** The whole program's region-part groups; see `collectRegionParts` for why this one is not split. */
+regionParts: RegionPartMembers) => OrderedOwnerOperations;
+/**
+ * One scope an operation's execution sits inside, innermost last.
+ *
+ * A guard is one side of a branch; a loop is one iteration. They are the same
+ * kind of fact -- "this does not simply run in sequence" -- and the lowering
+ * opens and closes both the same way, so one chain carries both.
+ */
+export type ScopeRef = {
+    readonly kind: 'guard';
+    readonly guard: SemanticResultId;
+    readonly takenWhen: 'truthy' | 'falsy' | 'nullish' | 'present';
+} | {
+    readonly kind: 'loop';
+    readonly loop: OperationId;
+} | {
+    readonly kind: 'loop-latch';
+    readonly loop: OperationId;
+} | {
+    readonly kind: 'region';
+    readonly region: OperationId;
+    readonly part: 'try' | 'catch' | 'finally';
+};
+/**
+ * The two-sided arm a `ScopeRef`'s four-valued `takenWhen` selects, independent
+ * of which predicate reads it.
+ *
+ * `nullish`/`present` are not a third and fourth kind of arm -- they are the
+ * same two arms tested differently -- so everything that compares scopes has
+ * to apply this mapping first. A `ScopeRef` compared before it is mapped is a
+ * `ScopeRef` compared in the wrong vocabulary.
+ */
+export declare const armSideOf: (takenWhen: "truthy" | "falsy" | "present" | "nullish") => "truthy" | "falsy";
+/**
+ * One scope's identity. Two refs with the same key name the same block-level
+ * nesting, and the ordering and the flow controller must agree on that or one
+ * of them will think a scope was left when it was not.
+ */
+export declare const scopeKeyOf: (ref: ScopeRef) => string;
+/** Whether a guard's dependents were ever recorded on its truthy side, its falsy side, or both. */
+export interface GuardArms {
+    readonly hasTruthy: boolean;
+    readonly hasFalsy: boolean;
+}
+/** Which question a guard's branch asks of its operand. */
+export type TestPredicate = 'to-boolean' | 'is-present' | 'is-defined';
+export interface ConditionalMembership {
+    /** The exact, ordered scope chain an operation requires -- outermost first. Empty means it runs in sequence. */
+    readonly requiredScopeOf: (operation: OperationId) => readonly ScopeRef[];
+    readonly armsOf: (guard: SemanticResultId) => GuardArms;
+    /**
+     * The predicate this guard's branch tests with.
+     *
+     * The census decides it, by which `takenWhen` its conditional edges carry:
+     * `truthy`/`falsy` is `ToBoolean`, `nullish`/`present` is a nullish check.
+     * Reading it here rather than at the branch keeps one authority -- the
+     * lowering must not re-derive from the guard's carrier which question the
+     * language asked, because `if (x)` and `x ?? y` over the same `x` ask
+     * different ones and would derive the same answer.
+     */
+    readonly predicateOf: (guard: SemanticResultId) => TestPredicate;
+    /** The loop this guard tests, when it is a head-tested loop's own condition; `null` for an ordinary branch. */
+    readonly loopOfGuard: (guard: SemanticResultId) => OperationId | null;
+    /** The condition a head-tested loop is driven by, which is also what decides where its exit is. */
+    readonly guardOfLoop: (loop: OperationId) => SemanticResultId | null;
+    /**
+     * Whether `loop` reserves a latch scope -- the `for` incrementor's own
+     * block, structurally distinct from the header it re-tests.
+     *
+     * A `for` loop's `continue` must run the incrementor before the condition
+     * is re-tested (ECMA-262 `ForStatement` evaluation: `continue` re-enters at
+     * the update expression, not at the test). A `while` has no incrementor and
+     * no latch, so its `continue` still targets the header directly.
+     * `gating.ts`'s `loop-latch` gate is what marks which loops have one; this
+     * is where that fact is read back, the same way every other scope fact
+     * here is.
+     */
+    readonly hasLatch: (loop: OperationId) => boolean;
+    /**
+     * The condition a *tail*-tested loop repeats on -- `do`/`while`'s own test.
+     *
+     * Deliberately a second question rather than a wider `guardOfLoop`: a head
+     * test's result gates the body, so the arms that guard already owns are what
+     * write the loop's back edge and its exit. A tail test gates nothing at all
+     * -- the body ran before it was evaluated -- so it has no arms, no join, and
+     * the back edge is built directly from it. Answering both from one map would
+     * have `ensureGuardBlocks` open a branch with two empty arms for every
+     * `do`/`while`, and send both of them to a join the loop never reaches.
+     *
+     * `null` for a head-tested loop, and for `do { ... } while (true)`, whose
+     * back edge is unconditional and whose loop-tail operation therefore carries
+     * no condition operand at all.
+     */
+    readonly tailTestOf: (loop: OperationId) => SemanticResultId | null;
+}
+export declare const collectConditionalMembership: (graph: SemanticGraph, operations: readonly OperationId[], 
+/** This owner's share of the edge table, in `graph.edges` order; the walk below keeps only edges landing inside `operations` anyway. */
+ownerEdges: readonly SemanticEdge[]) => ConditionalMembership;