@scriptc/compiler 0.2.9 → 0.3.0

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

@@ -1,9 +1,11 @@
 import { type CycleInitFlag } from "./cycle-initialization.js";
 import type { FieldLift } from "./coercions/structural-plans.js";
 import { CoercionState } from "./coercions/state.js";
+import { NarrowingStability } from "./narrowing-stability.js";
 import { StringIndexBounds } from "./string-index-bounds.js";
 import { NanCodedReads } from "./nan-coded-reads.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
+import { type ContractAnnotations } from "../contract-types.js";
 import type { WidthLift } from "./width-lift.js";
 import { type FnCtx } from "./function-context.js";
 import type { FrontendServices } from "../services.js";
@@ -17,10 +19,9 @@ import { type UnionLiteral } from "../union-discriminants.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/ir.js";
-import type { DynamicImportResolution, NpmBuiltinUse, NpmLazyTrap } from "../npm.js";
 import { type StartupCrash } from "../program.js";
 import { ShapeRegistry, type TypeMapperCtx, UnionRegistry } from "../type-mapper.js";
-import { type CompoundOp, type IslandFnEntry, type BuiltinModuleFn } from "./surfaces.js";
+import { type CompoundOp, type StdlibFnEntry, type BuiltinModuleFn } from "./surfaces.js";
 import { type FileParts } from "./lower-modules.js";
 import { type ClassInfo, type ClassIteratorInfo, type GenericClassInfo, findStaticOn } from "./lower-classes.js";
 import { type MixinFnShape } from "./lower-mixins.js";
@@ -64,11 +65,6 @@ export interface LowerStats {
      * statements inside a poisoned construct were never reached and don't). */
     statementsTotal: number;
     statementsFailed: number;
-    /** Statements that LOWERED but contain island constructs (jsOp/jsExit —
-     * package calls, island-backed lib members): they compile, but their
-     * work runs in the embedded engine. Only a --dynamic analysis produces
-     * these; coverage renders them as "compile dynamically". */
-    statementsIsland: number;
     /** Functions whose signature couldn't be analyzed (bodies not counted). */
     functionsSkipped: number;
 }
@@ -76,9 +72,6 @@ export interface LowerStats {
  * identifiers of a (possibly nested) destructuring pattern in source
  * order. */
 export declare function boundIdentifiersOf(name: ts.BindingName): ts.Identifier[];
-/** Inspect executable children directly, without boxing the statement tree
- * into checked-dynamic storage just to calculate coverage. */
-export declare function stmtUsesIsland(stmts: IrStmt | IrStmt[]): boolean;
 /** Statements a never-lowered body would have contributed to the coverage
  * totals: every element of a statement list (blocks, case clauses), plus
  * the single-statement bodies of control flow, nested functions included —
@@ -88,6 +81,9 @@ export interface LowerResult {
     /** Present iff diagnostics is empty. */
     module: IrModule | null;
     diagnostics: ScrDiagnostic[];
+    /** The program's written contract types (@scriptc/types), keyed by the
+     * source locations the IR carries; absent when it writes none. */
+    contracts?: ContractAnnotations;
     /** JS statements whose compile fences DEFERRED to runtime (runtimeFence
      * statements in the module) — off the build, on the coverage report. */
     runtimeFences: ScrDiagnostic[];
@@ -97,7 +93,6 @@ export interface LowerResult {
     statsByFile?: Map<string, {
         total: number;
         failed: number;
-        island: number;
     }>;
     /** --provenance-sources only: diagnostics of elided pure-annotated dead
      * consts in fetched source modules — off the build, on the report. */
@@ -112,21 +107,10 @@ export interface LowerResult {
     /** Compile-time-detectable behavior differences from Node (SC6xxx
      * divergence warnings) in the program's own modules. Never failures. */
     divergences?: ScrDiagnostic[];
-    /** --dynamic only: every Node builtin the embedded npm graph imports,
-     * shimmed or not — the coverage report's island honesty. */
-    npmBuiltins?: NpmBuiltinUse[];
-    /** --dynamic only: unresolvable specifiers reached ONLY by require()/
-     * import() edges — the build embeds Node's call-time error as a runtime
-     * trap; the coverage report lists them beside the builtins. */
-    npmLazyTraps?: NpmLazyTrap[];
 }
 export interface LowerOptions {
     /** Parser/checker services owned by the load; required for npm graph analysis. */
     frontendServices?: FrontendServices | undefined;
-    /** --dynamic: the island engine is linked, so island constructs
-     * (__island_eval) may lower. Off by default — without it they produce a
-     * requires-dynamic diagnostic instead. */
-    dynamic?: boolean;
     /** Coverage: additionally lower the unreached remainder (bodies nothing
      * on the entry path reaches) in a throwaway pass and report its
      * diagnostics and stats under `unreached` — the whole-program analysis
@@ -253,30 +237,13 @@ export interface LowererMode {
  * diagnostics nothing flushed), reported separately: whole-program analysis without
  * letting unreached code fail builds. */
 export declare function lowerToIr(program: ts.Program, entry: ts.SourceFile, moduleOrder: ts.SourceFile[], options?: LowerOptions): LowerResult;
-/** The island-handle type a `import(...)` initializer gives a binding
- * whose DECLARED type has no static mapping (`Promise<typeof
- * import("./m")>` — module-namespace types don't map): the direct form
- * holds the static promise-of-handle, the awaited form holds the handle
- * itself. Null for every other initializer shape. */
-export declare function importCallHandleType(expr: ts.Expression | undefined): IrType | null;
 /** The native namespace type produced by a literal static import() of a
  * compiled program module or supported Node builtin. This syntax-level
  * fallback is used where the checker exposes an anonymous builtin-module
  * object type with no stable module symbol (locals/globals are still
  * represented nominally by the value they actually receive). */
 export declare function staticImportNamespaceType(lowerer: Lowerer, expr: ts.Expression | undefined): IrType | null;
-/** True when `expr` is a call that resolved to an overload SIGNATURE of a
- * source-implemented function whose implementation returns an island value
- * (`any` under --dynamic): tsc never checks overload return types against
- * the body — only the implementation signature is checked — so the
- * overload's return is an unverifiable claim about an island value. The
- * binding stores the HANDLE instead of trap-extracting the claimed type
- * (reconcileOverloadReturn keeps the call jsval by the same rule), and
- * uses dispatch to engine ops — exactly the value Node's binding holds.
- * 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(lowerer: 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
@@ -303,29 +270,6 @@ export declare function neverTaintedJsType(lowerer: Lowerer, node: ts.Node, t: t
  * ledger exactly like a deferred statement fence — nothing silently
  * drops off the coverage report. */
 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:
- *
- * JAVASCRIPT files: `any` and every other inference residue is the
- * checked-dynamic 'unknown' kind, and array types keep their array-ness
- * with the fallback applied to the ELEMENT (any[]/never[] evolving arrays
- * become unknown[], so length/push/index still lower).
- *
- * TYPESCRIPT files: genuine checker-`any` residue ONLY — a bare `any`
- * binding (`flags & Any`), or a single-call-signature function type whose
- * only unmappable pieces are `any` (`(value: any) => value is string` —
- * the arrow the binding holds lowers those params to dyn, so the binding
- * keeps its func-ness with the same per-piece fallback). The honest
- * static subset of `any` is a binding whose VALUES are dyn-representable:
- * the binding is 'unknown' storage with the boundary conversions
- * coerceToExpected already applies (dynFrom into the slot, validated
- * dynCheck out) and per-site SC2011 fences for the operations the checked-dynamic tree
- * cannot carry JS-exactly (the island still lifts those). Every OTHER
- * unmappable TS type keeps its own diagnostic — annotations exist there,
- * and the fence names the real blocker. `--dynamic` builds never reach
- * this fallback for `any` (mapType answers jsval first).
- *
- * Null for void (no value exists to represent). */
 export declare function dynFallbackType(lowerer: Lowerer, node: ts.Node, t: ts.Type): IrType | null;
 /** The JS `Function.prototype.name` of an expression flowing into a dyn
  * slot. Immutable identifier aliases retain their creation-site name; property
@@ -338,7 +282,6 @@ export declare class Lowerer {
     readonly program: ts.Program;
     readonly entry: ts.SourceFile;
     readonly moduleOrder: ts.SourceFile[];
-    readonly dynamic: boolean;
     readonly frontendServices: FrontendServices | undefined;
     readonly checker: ts.TypeChecker;
     readonly diags: ScrDiagnostic[];
@@ -476,6 +419,10 @@ export declare class Lowerer {
      * discriminant was captured. A case match narrows the captured value,
      * not that mutable binding; preserve its tagged representation on reads. */
     readonly unstableSwitchBindings: Set<ts.Symbol>;
+    /** Whether a checker narrowing of a mutable member or closure-assigned
+     * binding still holds at its use (calls do not reset TypeScript's
+     * narrowing). Stale ones read the declared storage or check it. */
+    readonly narrowing: NarrowingStability;
     /** All storage slots widened for runtime absence, including slots whose
      * current control-flow branch has temporarily narrowed the value. */
     readonly runtimeOptionalStorageLocals: Set<IrLocal>;
@@ -754,33 +701,21 @@ export declare class Lowerer {
      * falls back through the shared node (collectGlobals registers both). */
     readonly globalsByDeclNode: Map<import("../ts7/ast-node.js").AstNode, IrGlobal>;
     readonly globalsList: IrGlobal[];
-    /** npm-import init statements (--dynamic), keyed by file AND import
-     * declaration: the island.import assignments/side-effect loads for that
-     * statement. lowerFileInit splices them into the importing file's %init
-     * header at the statement's position — Node evaluates each imported
-     * module (island packages included) where the import appears, so an
-     * `import "polyfill"` before an `import "./app.js"` runs the package
-     * top-level BEFORE app's init, not after. */
     readonly npmInitActions: Map<ts.SourceFile, Map<ts.StatementBase, IrStmt[]>>;
     /** Per-file %init PRELUDE statements for JSON imports: bakeable DATA
      * assignments with no observable evaluation order of their own —
      * prepended by lowerFileInit so the bindings are live before any
      * top-level statement runs. */
     readonly jsonInitActions: Map<ts.SourceFile, IrStmt[]>;
-    /** The embedded npm runtime graph (collectNpmImports), attached to the
-     * emitted module. Null without npm imports or without --dynamic. */
-    npmEmbedded: IrModule["embedded"] | null;
-    npmBuiltins: NpmBuiltinUse[] | null;
-    npmLazyTraps: NpmLazyTrap[] | null;
     /** Dynamic `import("literal")` resolutions, keyed
      * `fileName\u0000specifier` (collectDynamicImports fills it during npm
      * collection; lowerDynamicImportCall reads it per site). */
-    readonly dynImports: Map<string, DynamicImportResolution>;
-    /** createRequire-require resolutions of BARE npm specifiers, keyed
-     * `fileName\u0000specifier` (collectCreateRequires fills it during npm
-     * collection under --dynamic — the require-condition entry key plus its
-     * embedded format; lowerCreateRequireCall reads it per site; "" marks a
-     * failed resolution already reported at collection). */
+    readonly dynImports: Map<string, {
+        kind: "program-module";
+    } | {
+        kind: "static-builtin";
+        module: string;
+    }>;
     readonly createRequireImports: Map<string, "" | {
         entryKey: string;
         format: "esm" | "cjs" | "json";
@@ -789,11 +724,6 @@ export declare class Lowerer {
      * (lowerOwnModuleImport): every `import()` of the same program module
      * shares one builder. */
     readonly dynNsBuilders: Map<ts.SourceFile, string>;
-    /** Parameters forced to the island-handle type (jsval) regardless of
-     * their checker type: then-handler params whose settled value is an
-     * engine handle (a dynamic import's namespace object) — paramShape's
-     * early-out. */
-    readonly jsvalParamOverrides: Set<ts.ParameterDeclaration>;
     readonly checkedCallbackParams: Set<ts.ParameterDeclaration>;
     /** Inline Promise.then parameters whose contextual type is a builtin
      * module namespace anonymous object. The settled native token is the
@@ -1002,13 +932,12 @@ export declare class Lowerer {
     readonly statsByFile: Map<string, {
         total: number;
         failed: number;
-        island: number;
     }>;
     /** Bumps the per-file attribution counter (no-op unless provenance is
      * active and this is the emit/discovery lane — mirror the CALLER's
      * suppressStats guard, this method only gates remainder). */
-    bumpFileStat(file: string, kind: "total" | "failed" | "island"): void;
-    constructor(program: ts.Program, entry: ts.SourceFile, moduleOrder: ts.SourceFile[], dynamic: boolean, mode?: LowererMode);
+    bumpFileStat(file: string, kind: "total" | "failed"): void;
+    constructor(program: ts.Program, entry: ts.SourceFile, moduleOrder: ts.SourceFile[], mode?: LowererMode);
     registerBuiltinErrorClasses(): void;
     private classProtocols;
     classImplementedProtocol(type: ts.Type): boolean;
@@ -1225,19 +1154,10 @@ export declare class Lowerer {
     pushDiag(diag: ScrDiagnostic): void;
     unsupported(code: keyof typeof UNSUPPORTED & `SC${number}`, node: ts.Node, featureOverride?: string, hintOverride?: string): never;
     externalHostFence(specifier: string, node: ts.Node, valueUse?: boolean): never;
-    /** The dynamic-family fence for an OPERATION on an `any`-origin
-     * checked-dynamic value that only the engine can execute (operators,
-     * iteration, computed member names, ...). Carries SC2011 — the same
-     * code as the `any` type fence — so the coverage report groups it with
-     * the dynamic-capable family and the two-tier retry knows the island
-     * lifts the site. Use exactly when the blocking operand IS dyn-typed
-     * and its checker type is `any`-flavored; genuine `unknown` keeps the
-     * SC1100-family fences (tsc constrains what unknown can do, so those
-     * sites are checker-error territory, not engine territory). */
     anyOpFence(feature: string, node: ts.Node): never;
     /** True when this expression's CHECKER type is `any`-flavored — the
      * gate anyOpFence's call sites use to tell `any`-origin dyn values
-     * (the engine could run the operation) from genuine `unknown` ones. */
+     * with an unsupported operation from genuine `unknown` ones. */
     anyOrigin(node: ts.Node): boolean;
     badType(node: ts.Node, type: ts.Type): never;
     /** The lib fence (SC2020): a reached use of standard-library surface
@@ -1252,10 +1172,6 @@ export declare class Lowerer {
     fenceStaticAbortControllerMemberRead(access: ts.PropertyAccessExpression | ts.ElementAccessExpression): IrExpr | null;
     fenceStaticHeadersIteration(node: ts.Node): void;
     fenceFetchObjectAssignment(target: ts.ObjectLiteralExpression, source: ts.Expression): void;
-    lowerDynamicHeadersIteratorCall(call: ts.CallExpression, access: ts.ElementAccessExpression): IrExpr | null;
-    lowerDynamicHeadersSpread(node: ts.Expression, type: IrType & {
-        kind: "array";
-    }): IrExpr | null;
     fenceStaticReadableStreamMember(access: ts.PropertyAccessExpression | ts.ElementAccessExpression, use: "read" | "call"): IrExpr | null;
     typeOf(node: ts.Node): ts.Type;
     /** mapType with this Lowerer's registries and (while a generic instance
@@ -1306,17 +1222,6 @@ export declare class Lowerer {
      * union in field position is JSON-safe (isJsonSafeType), so a record that
      * still fails the fence does so for some other reason. */
     bareUndefinedArmedUnion(t: IrType): boolean;
-    /** canCrossIslandBoundary with this Lowerer's registries — THE test
-     * behind every marshal/exit decision (the implicit coercions, jsvalIn,
-     * the checked island-exit cast). Rejections that follow a false answer
-     * speak through boundaryIntoIslandMsg / boundaryOutOfIslandMsg. */
-    boundarySafe(t: IrType): boolean;
-    /** canExitIslandToType with this Lowerer's registries — the EXIT
-     * direction's slightly wider test (bare undefined-armed unions of
-     * JSON-safe data arms exit; the engine's undefined takes the undefined
-     * arm before the JSON round trip). */
-    boundaryExitSafe(t: IrType): boolean;
-    isIslandExpr(node: ts.Expression): boolean;
     /** True when this node's CHECKER type is proven `any[]`/`unknown[]`,
      * directly or through the intersection tsc builds for a readonly tuple
      * union (`(Model | readonly [Model, Command]) & any[]`; TS7 distributes
@@ -1457,13 +1362,6 @@ export declare class Lowerer {
     narrowedArmHelper(fromId: string, target: IrType, loc: SrcLoc): string | null;
     checkedNarrowCall(helper: string, value: IrExpr, type: IrType, loc: SrcLoc): IrExpr;
     deferredReadHelper(fromId: string, target: IrType, loc: SrcLoc): string | null;
-    jsvalLiftable(t: IrType, visiting?: Set<string>): boolean;
-    jsvalLiftExpr(e: IrExpr, loc: SrcLoc): IrExpr;
-    unionToJsvalHelper(unionId: string, loc: SrcLoc): string;
-    recordToJsvalHelper(shapeId: string, loc: SrcLoc): string;
-    arrayToJsvalHelper(elem: IrType, loc: SrcLoc): string;
-    arrayToJsvalArrayHelper(fromElem: IrType, loc: SrcLoc): string | null;
-    jsvalIn(e: IrExpr, node: ts.Node): IrExpr;
     /** THE coercion path for values flowing into a typed slot: union arms
      * wrap implicitly (coerceToExpected), then the exact-type fence runs
      * (SC2002 for record shapes, SC2003 for unions). Every slot-directed
@@ -1471,9 +1369,8 @@ export declare class Lowerer {
      * directly when the expression was already lowered. */
     coerceInto(node: ts.Node, expr: IrExpr, expected: IrType): IrExpr;
     /** The unit an 'any' expression PROVABLY holds on every run, or null
-     * when no proof exists. Two spellings prove: the lowered value IS the
-     * engine unit literal (`null as any`, an any-contextual `undefined`),
-     * or the node is an identifier whose every declaration is a plain,
+     * when no proof exists. The node must be an identifier whose every
+     * declaration is a plain,
      * non-ambient `var`/`let`/`const` declarator under a variable STATEMENT
      * (catch bindings, for-of/for-in cursors, parameters, and imports all
      * fail this shape test — each receives values from elsewhere), each
@@ -1484,7 +1381,7 @@ export declare class Lowerer {
      * bindings are read-only, so cross-file writes don't exist). A hoisted
      * `var` read before its unit-initialized statement holds undefined —
      * also a unit — so the mixed case reports both names. */
-    provenUnitAnyOf(node: ts.Node, value: IrExpr): string | null;
+    provenUnitAnyOf(node: ts.Node, _value: IrExpr): string | null;
     /** A key conversion may rebox or upcast a reference, but must never copy
      * its referent. Apply the ordinary checked narrowing to absent arms from
      * runtime-optional reads; only present reference arms participate here. */
@@ -1572,14 +1469,6 @@ export declare class Lowerer {
      * undefined-armed union fields, which can be absent, and `true` for
      * every other declared field. */
     recordFieldPresent(obj: IrExpr, shapeId: string, field: string, loc: SrcLoc): IrExpr;
-    /** The entry value of a binding JS initializes to `undefined` (an
-     * initializer-less declaration, a hoisted `var` before its statement):
-     * undefined-armed unions hold the interned undefined arm, and 'any'
-     * slots hold the ENGINE's undefined — tsc's definite-assignment
-     * analysis never guards `any` reads, so a jsval slot IS readable before
-     * any assignment and must never stay a C-level NULL (a validated exit
-     * or engine op on NULL is memory-unsafe, not a TypeError). Null for
-     * every other type: tsc rejects their pre-assignment reads. */
     unassignedSlotInit(type: IrType, loc: SrcLoc): IrExpr | null;
     undefinedArgFor(type: IrType, loc: SrcLoc, blame: ts.Node): IrExpr;
     requireExactArityValue(blame: ts.Node, contextual: ts.Expression | null, shapes: readonly ParamShape[], funcType: IrType): void;
@@ -1793,13 +1682,6 @@ export declare class Lowerer {
      * through arrows (function expressions/declarations reset `this` in JS;
      * their bodies never see an enclosing method's binding). */
     resolveThis(): IrLocal | null;
-    /** READ-ONLY twin of resolveLocal for PROBES (isIslandExpr): answers
-     * the nearest binding entry without boxing, threading, or predeclaring.
-     * resolveKey mutates capture state as a side effect, and a speculative
-     * island-ness query through a context that takes no captures (a plain
-     * declared function between the origin and the reference) was an ICE —
-     * the REAL lowering path still resolves (and diagnoses) the reference
-     * itself. */
     peekLocal(ident: ts.Identifier): IrLocal | null;
     resolveKey(symbol: ts.Symbol | undefined, blame?: ts.Node): IrLocal | null;
     isSelfReference(ident: ts.Identifier): boolean;
@@ -1855,13 +1737,6 @@ export declare class Lowerer {
      * supported-surface provenance check. */
     readonly isStdlibFile: (sf: ts.SourceFile) => boolean;
     nodeTypesOnlySymbol(sym: ts.Symbol | null | undefined): boolean;
-    /** True for an npm package's shipped declaration files — under
-     * 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 — 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;
     npmPackageOf(type: ts.Type): string | null;
     npmMemberFence(access: ts.PropertyAccessExpression): void;
@@ -2096,8 +1971,8 @@ export declare class Lowerer {
     lowerPromiseMethodCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
     lowerPromiseStaticCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
     lowerNumberStaticProperty(expr: ts.PropertyAccessExpression): IrExpr | null;
-    requireDynamicApi(feature: string, node: ts.Node, hint?: string): void;
+    refuseUnsupportedApi(feature: string, node: ts.Node, hint?: string): never;
     lowerMathProperty(expr: ts.PropertyAccessExpression): IrExpr | null;
-    islandGlobalFnOf(ident: ts.Identifier): IslandFnEntry | null;
-    lowerIslandMethodCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+    stdlibGlobalFnOf(ident: ts.Identifier): StdlibFnEntry | null;
+    lowerStdlibMethodCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
 }