@scriptc/compiler 0.0.35 → 0.1.1

package/dist/frontend/lowering/lowerer.d.ts

@@ -1,16 +1,16 @@
 import * as ts from "../ts7/adapter.js";
 import type { ScrDiagnostic } from "../../diagnostics/diagnostic.js";
 import { UNSUPPORTED } from "../../diagnostics/diagnostic.js";
-import type { IrClassDef, IrExpr, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrParam, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/nodes.js";
+import type { IrClassDef, IrExpr, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrParam, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
 import { type DynamicImportResolution, type NpmBuiltinUse, type NpmLazyTrap } from "../npm.js";
 import { type StartupCrash } from "../program.js";
-import { ShapeRegistry, type TypeMapperCtx, UnionRegistry } from "../types.js";
+import { ShapeRegistry, type TypeMapperCtx, UnionRegistry } from "../type-mapper.js";
 import { CompoundOp, IslandFnEntry, BuiltinModuleFn } from "./surfaces.js";
 import { FileParts } from "./lower-modules.js";
 import { ClassInfo, ClassIteratorInfo, GenericClassInfo, findStaticOn } from "./lower-classes.js";
 import { MixinFnShape } from "./lower-mixins.js";
 import { ParamShape, FnSig, GenericFnInfo, GenericInstance } from "./lower-calls.js";
-import { type EmitSpecCtx, type EmitSpecRequest } from "./lower-emitter.js";
+import { type EmitSpecCtx, type EmitSpecRequest } from "./lower-event-emitter.js";
 import { FieldTarget } from "./lower-exprs.js";
 import type { ExpandoMember } from "./lower-expando.js";
 /** Entry function name. '%' cannot appear in a TS identifier, so a user
@@ -59,10 +59,6 @@ export declare class PoisonError extends Error {
  * NAMES user code can spell now that the real lib declares them; treating
  * an inherited function as a table entry would mis-lower or ICE. */
 export declare function own<T>(table: Record<string, T | undefined>, key: string): T | undefined;
-/** Sentinel binding key for `this` (which has no ts.Symbol): a stable
- * object identity used in the same scope/capture maps as real symbols, so
- * arrows capturing `this` ride the ordinary capture machinery. */
-export declare const THIS_BINDING: ts.Symbol;
 /** Per-function lowering context. A stack of these models nested functions:
  * identifier resolution walks outward, and a hit in an enclosing context
  * turns into a capture (boxing the binding at its origin and threading it
@@ -135,12 +131,6 @@ export interface LowerStats {
     /** Functions whose signature couldn't be analyzed (bodies not counted). */
     functionsSkipped: number;
 }
-/** IrStmt discriminants — the island walk below must not descend into
- * NESTED statements (each is counted individually by its own lowerStmts
- * visit; descending would attribute a nested island statement to every
- * enclosing construct too). The top-level statement object itself is
- * always visited. */
-export declare const IR_STMT_KINDS: Set<string>;
 /** True when a lowered statement's OWN expressions contain island
  * constructs — a generic JSON walk (like moduleUsesRegex): `kind`
  * discriminants live only on IR objects, so user string values can never
@@ -230,6 +220,39 @@ export interface LowerOptions {
      * to their owning external specifier. */
     externalTypeSpecifiersByFile?: ReadonlyMap<string, readonly string[]>;
 }
+interface RuntimeFenceFallback {
+    code: `SC${number}`;
+    message: string;
+}
+interface RuntimeFenceBase {
+    /** Used only by catches that can legitimately have no fresh diagnostic. */
+    fallback?: RuntimeFenceFallback;
+    /** Legacy function-body fences throw the diagnostic text without a site suffix. */
+    bareMessage?: boolean;
+    /** The closure-probe fallback historically applies inside diagnostic captures. */
+    allowDiagSink?: boolean;
+}
+interface RuntimeFenceStatementTarget extends RuntimeFenceBase {
+    kind: "statement";
+}
+interface RuntimeFenceFunctionTarget extends RuntimeFenceBase {
+    kind: "function";
+    name: string | (() => string);
+    params?: IrParam[];
+    returnType: IrType;
+    paramsMutable?: boolean;
+    async?: true;
+    generator?: {
+        yieldT: IrType;
+        nextT: IrType;
+    };
+}
+interface RuntimeFenceClosureTarget extends Omit<RuntimeFenceFunctionTarget, "kind"> {
+    kind: "closure";
+    type: IrType & {
+        kind: "func";
+    };
+}
 /** The Lowerer's pass configuration (see lowerToIr). */
 export interface LowererMode {
     /** Names of bodies a prior reachability pass reached; null lowers everything. */
@@ -296,7 +319,7 @@ export declare function importCallHandleType(expr: ts.Expression | undefined): I
  * Ambient (.d.ts) declarations never reach this: they have no compiled
  * implementation, so their calls lower through the island/builtin paths
  * whose validated exits keep the checker-trust trap. */
-export declare function uncheckedOverloadHandleCall(L: Lowerer, expr: ts.Expression | undefined): boolean;
+export declare function uncheckedOverloadHandleCall(lowerer: Lowerer, expr: ts.Expression | undefined): boolean;
 /** The JavaScript declaration fallback for unmappable binding types (see
  * irTypeOf): `any` and every other inference residue is the checked-
  * dynamic 'unknown' kind, and array types keep their array-ness with the
@@ -314,7 +337,7 @@ export declare function uncheckedOverloadHandleCall(L: Lowerer, expr: ts.Express
  * checked-dynamic fallbacks apply, the pre-never-mapping behavior. Bare
  * `never` at the ROOT stays out (`for (const v of [])`'s loop var — the
  * dead read the f64 mapping is FOR). */
-export declare function neverTaintedJsType(L: Lowerer, node: ts.Node, t: ts.Type): boolean;
+export declare function neverTaintedJsType(lowerer: Lowerer, node: ts.Node, t: ts.Type): boolean;
 /** The dyn undefined value — what an uninitialized checked-dynamic
  * binding holds (JS: declared bindings read `undefined` before any
  * assignment). A NULL dyn slot is a trap, never a value, so every dyn
@@ -337,7 +360,7 @@ export declare function nodeThrowExpr(kind: 0 | 1 | 2, code: string, message: st
  * (scr_throw_lowering_fence). The diagnostic joins the runtime-fence
  * ledger exactly like a deferred statement fence — nothing silently
  * drops off the coverage report. */
-export declare function ladderFenceExpr(L: Lowerer, surface: string, node: ts.Node, hint?: string): IrExpr;
+export declare function ladderFenceExpr(lowerer: Lowerer, surface: string, node: ts.Node, hint?: string): IrExpr;
 /** The checked-dynamic declaration fallback for unmappable binding types
  * (see irTypeOf), two gates over one story:
  *
@@ -361,7 +384,7 @@ export declare function ladderFenceExpr(L: Lowerer, surface: string, node: ts.No
  * this fallback for `any` (mapType answers jsval first).
  *
  * Null for void (no value exists to represent). */
-export declare function dynFallbackType(L: Lowerer, node: ts.Node, t: ts.Type): IrType | null;
+export declare function dynFallbackType(lowerer: Lowerer, node: ts.Node, t: ts.Type): IrType | null;
 /** The best-effort JS `Function.prototype.name` of an expression flowing
  * into a dyn slot (the boxed function kind's inspect/error name):
  * identifier and property reads answer the referenced NAME (a
@@ -481,10 +504,69 @@ export declare class Lowerer {
     /** All storage slots widened for runtime absence, including slots whose
      * current control-flow branch has temporarily narrowed the value. */
     readonly runtimeOptionalStorageLocals: Set<IrLocal>;
+    /** Globals whose checker-bare type was widened because an indexed read can
+     * carry undefined at runtime. Identifier reads keep the union tag so
+     * typeof and later boundaries observe the real value. */
+    readonly runtimeOptionalGlobals: Set<IrGlobal>;
+    /** Bindings whose unchecked string arithmetic can produce either a number
+     * (NaN for an absent read) or a string. Preserve that result union at bare
+     * reads instead of applying the checker-bare string narrowing adapter. */
+    readonly runtimeOptionalArithmeticLocals: Set<IrLocal>;
+    readonly runtimeOptionalArithmeticGlobals: Set<IrGlobal>;
+    /** Binding symbols whose IR storage type was widened by the indexed-read
+     * prepass. This includes explicit annotations: unchecked TS annotations do
+     * not prove that an array property read produced a value. */
+    readonly runtimeOptionalBindingTypes: Map<ts.Symbol, IrType>;
+    /** Concise callback/lambda returns promoted by the HOF callback prepass;
+     * arrows have no declaration symbol to key in fnSigsBySymbol. */
+    readonly runtimeOptionalFunctionReturns: WeakMap<ts.Node, IrType>;
+    /** Arithmetic over an unchecked string read can answer either NaN or a
+     * string. Bindings and returns use this marker to retain that result union
+     * through checker-bare string annotations. */
+    readonly runtimeOptionalArithmeticTypes: WeakMap<ts.Node, IrType>;
+    /** Record fields promoted to an undefined-armed union by an indexed-read
+     * value. The key is the concrete emitted shape and field name. */
+    readonly runtimeOptionalFields: Set<string>;
+    /** Callback pattern parameters carry an optional source without making
+     * every name destructured from a present source optional. */
+    readonly runtimeOptionalPatternTypes: WeakMap<ts.Node, IrType>;
+    readonly runtimeOptionalReduceTypes: WeakMap<ts.CallExpression, IrType>;
     /** Capture entries and their origin share one mutable box. Normalize each
      * entry to the origin so writes and flow proofs stay synchronized. */
     readonly runtimeOptionalRoots: Map<IrLocal, IrLocal>;
     runtimeOptionalRootOf(local: IrLocal): IrLocal;
+    runtimeOptionalBindingType(node: ts.Node): IrType | null;
+    runtimeOptionalBindingType(node: ts.Node, fallback: IrType): IrType;
+    runtimeOptionalIdentifierValue(node: ts.Expression): {
+        value: IrExpr;
+        present: IrType;
+        unionId: string;
+    } | null;
+    /** Recover the original optional union when a checked single-arm helper
+     * was installed before a strict property consumer could name its member.
+     * Recovery is limited to array element reads and storage roots marked by
+     * the optional-read analysis, so ordinary assertions keep their generic
+     * checked-narrow behavior. */
+    runtimeOptionalSourceValue(node: ts.Expression, value: IrExpr): IrExpr | null;
+    /** A strict property or method receiver over an array-derived optional
+     * value. Stabilize the receiver once, throw Node's member-read TypeError
+     * for a unit arm, and extract the expected present arm otherwise. */
+    runtimeOptionalPropertyReceiver(node: ts.Expression, value: IrExpr, expected: IrType, member: string): IrExpr | null;
+    runtimeOptionalFieldKey(shapeId: string, field: string): string;
+    isRuntimeOptionalField(shapeId: string, field: string): boolean;
+    isRuntimeOptionalGlobal(global: IrGlobal): boolean;
+    isRuntimeOptionalArithmeticGlobal(global: IrGlobal): boolean;
+    /** The union produced when an unchecked array read reaches a typed slot
+     * whose checker type is the corresponding bare arm. */
+    runtimeOptionalWidening(actual: IrType, expected: IrType): IrType | null;
+    runtimeOptionalType(t: IrType): IrType;
+    promoteRuntimeOptionalParameter(node: ts.Node, type: IrType): IrType;
+    promoteRuntimeOptionalFunctionReturn(node: ts.Node, type: IrType): IrType;
+    runtimeOptionalFunctionReturnType(node: ts.Node, fallback: IrType): IrType;
+    /** Promote one field of a record storage shape to the value's runtime
+     * type. Shapes are immutable by identity, so this interns a sibling shape
+     * and records the field as runtime-optional for property-read narrowing. */
+    runtimeOptionalRecordField(type: IrType, field: string, fieldType: IrType): IrType;
     /** Runs `fn` with the given aliased-typeof narrows applied (and restored
      * after) — the branch-scoping primitive. */
     narrowingAliases<T>(narrows: readonly {
@@ -510,7 +592,7 @@ export declare class Lowerer {
      * Reachability lowers inits before the declarations they discover, so
      * these rebuild after the worklist restores historical shape metadata. */
     readonly shapeOrderHelperFinalizers: (() => void)[];
-    /** Emit-override specializations (`%C.emit:<event>` — lower-emitter.ts's
+    /** Emit-override specializations (`%C.emit:<event>` — lower-event-emitter.ts's
      * emit-overrides block): interned names, the drive-loop queue, and the
      * currently-lowering specialization's context (the super-forward
      * interception reads it). */
@@ -569,6 +651,10 @@ export declare class Lowerer {
         };
     }>;
     readonly narrowHelpers: Map<string, string>;
+    /** Exact members of narrowHelpers produced by narrowedArmHelper. This
+     * lets property consumers recognize an earlier checked extraction by
+     * provenance instead of relying on its generated-name prefix. */
+    private readonly checkedNarrowHelpers;
     /** Interned `%iter.drain.<n>` helpers (classIteratorDrainCall): one per
      * receiver class — the eager drain of a class iterable's protocol into
      * a fresh element array, behind array/call spreads. */
@@ -888,6 +974,13 @@ export declare class Lowerer {
      * point for deferred collection diagnostics: resolving a reference to a
      * broken declaration reports what collection deferred. */
     resolveValueSymbol(ident: ts.Identifier): ts.Symbol | null;
+    /** Whether this exact direct call belongs to a manifest-validated native
+     * binding. Declaration classification uses this as a probe before normal
+     * expression lowering: resolving must not flush deferred diagnostics or
+     * trigger the merged-namespace fence just because it is asking ownership.
+     * Call lowering remains the authority for every ABI and call-shape
+     * diagnostic once this answers true. */
+    ownsFfiCall(expr: ts.CallExpression): boolean;
     /** The configured external host module owning an expression's runtime
      * value, or null. Alias chains are followed to their declaration file so
      * direct imports and local re-export facades classify identically. Type
@@ -976,6 +1069,12 @@ export declare class Lowerer {
     wantBody(name: string): boolean;
     collectNpmImports(parts: FileParts[]): void;
     collectJsonImports(parts: FileParts[]): void;
+    /** Discover the unchecked-array values that cross static ABI/storage
+     * boundaries before any function body or module initializer is emitted.
+     * TypeScript's default indexed-access type is a useful source annotation,
+     * but it is not a runtime proof; promoting only the affected slots keeps
+     * the rest of the dense ABI unchanged. */
+    analyzeRuntimeOptionalArrayReads(parts: FileParts[]): void;
     run(): LowerResult;
     /** Final retention, pruning, and module assembly shared by ordinary emit
      * and the retained reachability worklist. */
@@ -1030,6 +1129,15 @@ export declare class Lowerer {
         records: IrRecordShape[];
         unions: IrUnionDef[];
     };
+    /** Converts diagnostics recorded since `diagsBefore` into a runtime
+     * fence. ICEs stay on the compile-diagnostic path; every other captured
+     * diagnostic moves to the runtime-fence ledger. Function targets share
+     * the same capture-free trap-function construction, while statement
+     * targets return the fence inline. Null means the conversion was not
+     * eligible (probe mode, no diagnostic/fallback, or an ICE). */
+    deferToRuntimeFence(diagsBefore: number, node: ts.Node, target: RuntimeFenceStatementTarget): IrStmt | null;
+    deferToRuntimeFence(diagsBefore: number, node: ts.Node, target: RuntimeFenceFunctionTarget): IrFunction | null;
+    deferToRuntimeFence(diagsBefore: number, node: ts.Node, target: RuntimeFenceClosureTarget): IrExpr | null;
     /** All diagnostics land here; while a generic instance body is lowering,
      * the instantiation context is appended so the user knows which concrete
      * types made the (source-anchored) construct fail. */
@@ -1103,9 +1211,10 @@ export declare class Lowerer {
      * isArrayValueType so Array.isArray's predicate and its narrowing bridge
      * cannot disagree about fixed tuple arms. */
     arrayValueTags(unionId: string): number[];
-    /** isJsonSafeType with this Lowerer's registries — the shared fence for
-     * what JSON.stringify accepts and what a checked cast can validate. */
+    /** Checked JSON conversion excludes undefined array slots because JSON
+     * text cannot preserve that distinction. */
     jsonSafe(t: IrType): boolean;
+    jsonStringifySafe(t: IrType): boolean;
     /** True when a type is a BARE undefined-armed union — the one JSON-unsafe
      * shape whose rejections deserve their own wording: Node's stringify of
      * bare undefined is not a string at all and JSON text never matches the
@@ -1167,7 +1276,7 @@ export declare class Lowerer {
     /** Unwraps a HYBRID (function-with-properties) record to its callable:
      * a record whose shape carries the reserved `%call` func field reads
      * that field; anything else returns unchanged. The consumer half of
-     * types.ts's chalk-shape mapping — call paths and func-slot coercions
+     * type-mapper.ts's chalk-shape mapping — call paths and func-slot coercions
      * share it. */
     hybridCallUnwrap(expr: IrExpr): IrExpr;
     /** The tag of the union arm equal to `arm`, or -1 (unknown union / no
@@ -1910,7 +2019,7 @@ export declare class Lowerer {
      * node_modules but NOT the standard library (typescript's own lib files
      * live under node_modules too), or inside a registered workspace-linked
      * package (a node_modules symlink whose realpath'd files carry no
-     * node_modules segment — shared.ts). The provenance half of the npm
+     * node_modules segment — workspace-registry.ts). The provenance half of the npm
      * typing rule (package types are island handles) and of the per-package
      * requires-dynamic attribution. */
     readonly isNpmFile: (sf: ts.SourceFile) => boolean;
@@ -1942,6 +2051,8 @@ export declare class Lowerer {
     caughtLocalOf(node: ts.Expression): IrLocal | null;
     caughtToString(node: ts.Expression): IrExpr | null;
     lowerInstanceOf(expr: ts.BinaryExpression, loc: SrcLoc): IrExpr;
+    private withRuntimeOptionalClassValue;
+    private withExpressionOverride;
     lowerCall(expr: ts.CallExpression): IrExpr;
     isTopLevelFnSymbol(ident: ts.Identifier): boolean;
     lowerNestedFunctionDecl(stmt: ts.FunctionDeclaration): IrStmt;
@@ -2141,3 +2252,4 @@ export declare class Lowerer {
     islandGlobalFnOf(ident: ts.Identifier): IslandFnEntry | null;
     lowerIslandMethodCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
 }
+export {};