@scriptc/compiler 0.0.29 → 0.0.31

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

@@ -215,6 +215,14 @@ export interface LowerOptions {
      * imports; without this option ambient declarations keep Node's ordinary
      * ReferenceError behavior. */
     ffiImports?: readonly IrFfiImport[];
+    /** LIBRARY mode's host-callback surface marker: the `ffiImports` above
+     * are profile-declared callback channels, not native-manifest bindings.
+     * Flips the binding diagnostics to the library flavor (SC4024), keeps a
+     * channel legal when no program declaration references it (an unused
+     * channel is capacity, not an error), and refuses a CALL of any other
+     * program-authored signature-only ambient function with the callback
+     * teaching instead of the ambient ReferenceError lowering. */
+    libraryCallbacks?: boolean;
     /** Coverage-only external host type surfaces. Their declarations inform
      * the checker, while every runtime value use remains an SC1010 fence. */
     externalTypes?: ReadonlyMap<string, string>;
@@ -243,6 +251,8 @@ export interface LowererMode {
     startupCrash?: StartupCrash | null;
     /** The build's outbound native FFI declarations. */
     ffiImports?: readonly IrFfiImport[];
+    /** LowerOptions.libraryCallbacks (see there). */
+    libraryCallbacks?: boolean;
     /** Program-validated ambient declaration symbols for each FFI name.
      * Undefined in discovery's legacy call-local validation path. */
     ffiBindingSymbols?: ReadonlyMap<string, ReadonlySet<ts.Symbol>>;
@@ -446,6 +456,17 @@ export declare class Lowerer {
      * aliases, so this carries the var/let form the checker cannot.
      * Scoped strictly by narrowingAliases (lowerIf / lowerCondition). */
     readonly aliasNarrowTypes: Map<ts.Symbol, ts.Type>;
+    /** Locals widened beyond the checker's type because an inferred indexed
+     * read can be absent at runtime. Bare reads preserve that union until a
+     * surrounding JavaScript guard/default consumes it. */
+    readonly runtimeOptionalLocals: Set<IrLocal>;
+    /** All storage slots widened for runtime absence, including slots whose
+     * current control-flow branch has temporarily narrowed the value. */
+    readonly runtimeOptionalStorageLocals: Set<IrLocal>;
+    /** 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;
     /** Runs `fn` with the given aliased-typeof narrows applied (and restored
      * after) — the branch-scoping primitive. */
     narrowingAliases<T>(narrows: readonly {
@@ -759,6 +780,7 @@ export declare class Lowerer {
     readonly startupCrash: StartupCrash | null;
     /** Outbound native bindings by their source-level ambient name. */
     readonly ffiImports: readonly IrFfiImport[];
+    readonly libraryCallbacks: boolean;
     readonly ffiImportsByName: ReadonlyMap<string, IrFfiImport>;
     /** Non-null after whole-program FFI declaration validation. */
     readonly ffiBindingSymbols: ReadonlyMap<string, ReadonlySet<ts.Symbol>> | null;
@@ -883,10 +905,7 @@ export declare class Lowerer {
     cjsLocalModuleBindingOf(expr: ts.Expression): boolean;
     /** Assignment-target resolution: a function local (possibly captured) or
      * a module global. tsc has already rejected writes to consts. */
-    resolveWritable(ident: ts.Identifier): {
-        id: string;
-        type: IrType;
-    } | null;
+    resolveWritable(ident: ts.Identifier): IrLocal | null;
     fnSigOf(ident: ts.Identifier): FnSig | null;
     globalOf(ident: ts.Identifier): IrGlobal | null;
     splitFiles(): FileParts[];
@@ -1025,6 +1044,15 @@ export declare class Lowerer {
     /** formatIrType with this Lowerer's registries (records and unions expand
      * to their structure in diagnostics). */
     fmt(t: IrType): string;
+    /** Whether an IR value has JavaScript Array identity. Homogeneous arrays
+     * use the native array representation; non-empty fixed tuples use a
+     * positional record shape so their slots can keep distinct types, but
+     * Array.isArray must still answer true for both representations. */
+    isArrayValueType(t: IrType): boolean;
+    /** Runtime tags of every JavaScript-array arm in one union. Kept beside
+     * 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. */
     jsonSafe(t: IrType): boolean;
@@ -1048,14 +1076,24 @@ export declare class Lowerer {
      * arm before the JSON round trip). */
     boundaryExitSafe(t: IrType): boolean;
     isIslandExpr(node: ts.Expression): boolean;
-    /** True when this node's CHECKER type is `any[]`/`unknown[]` — the type
-     * tsc's Array.isArray predicate narrows readonly arrays to (its `arg is
-     * any[]` quirk), and what a union collapses to when such an arm absorbs
-     * its siblings. The VALUE behind it can still be a real static array
-     * (maybeNarrow's isArray bridge extracts the union's array arm), so
-     * receiver-typed dispatch falls back to the LOWERED type under this
-     * test. */
+    /** 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
+     * this over the union arms). These are forms of the `arg is any[]`
+     * Array.isArray predicate; the VALUE behind them can still be a real
+     * static array/tuple (maybeNarrow's bridge extracts the union's one
+     * array-valued arm), so receiver-typed dispatch falls back to the LOWERED
+     * type under this test. */
     checkerAnyArray(node: ts.Expression): boolean;
+    /** Type-level half of checkerAnyArray, for narrowing sites that already
+     * queried the checker type from a general AST node. */
+    checkerAnyArrayType(t: ts.Type): boolean;
+    /** The lowered static array/tuple value behind checkerAnyArray's
+     * synthetic `any[]` spelling. Array.isArray can leave readonly tuple
+     * unions as intersections that do not map directly, while maybeNarrow
+     * still extracts the runtime-proven array arm from the original union.
+     * Receiver dispatchers use this bridge instead of the synthetic type. */
+    checkerArrayValue(node: ts.Expression): IrExpr | null;
     /** Substitutes a bound type parameter anywhere inside mapType's recursion
      * (`T`, `T[]`, `{ v: T }`, `(x: T) => T` all resolve). Inert outside
      * generic instantiation. */
@@ -1836,7 +1874,7 @@ export declare class Lowerer {
     lowerShorthandValue(prop: ts.ShorthandPropertyAssignment): IrExpr;
     rejectThisInObjectMethod(node: ts.Node): void;
     lowerElementAccess(expr: ts.ElementAccessExpression): IrExpr;
-    lowerRecordKeyRead(expr: ts.ElementAccessExpression, shapeId: string, shape: IrRecordShape): IrExpr;
+    lowerRecordKeyRead(expr: ts.ElementAccessExpression, shapeId: string, shape: IrRecordShape, includeUndefined?: boolean): IrExpr;
     lowerElementWrite(expr: ts.BinaryExpression): IrStmt;
     ensureString(e: IrExpr, node: ts.Node): IrExpr;
     lowerTemplate(expr: ts.TemplateExpression): IrExpr;

package/dist/frontend/lowering/lowerer.js

@@ -177,12 +177,14 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         });
     }
     const ffiImports = options.ffiImports ?? [];
+    const libraryCallbacks = options.libraryCallbacks ?? false;
     const externalTypes = options.externalTypes ?? new Map();
     const externalTypeSpecifiersByFile = options.externalTypeSpecifiersByFile ??
         directExternalTypeSpecifiersByFile(externalTypes);
     const validation = new Lowerer(program, entry, moduleOrder, dynamic, {
         targetPlatform,
         ffiImports,
+        libraryCallbacks,
         externalTypes,
         externalTypeSpecifiersByFile,
     });
@@ -198,6 +200,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         : new Lowerer(program, entry, moduleOrder, dynamic, {
             targetPlatform,
             ffiImports,
+            libraryCallbacks,
             externalTypes,
             externalTypeSpecifiersByFile,
             ffiBindingSymbols: ffiValidation.symbolsByName,
@@ -208,6 +211,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         targetPlatform,
         startupCrash,
         ffiImports,
+        libraryCallbacks,
         ffiBindingSymbols: ffiValidation.symbolsByName,
         externalTypes,
         externalTypeSpecifiersByFile,
@@ -225,6 +229,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         alreadyFlushed: emit.flushedSymbols,
         targetPlatform,
         ffiImports,
+        libraryCallbacks,
         ffiBindingSymbols: ffiValidation.symbolsByName,
         externalTypes,
         externalTypeSpecifiersByFile,
@@ -624,6 +629,19 @@ export class Lowerer {
      * aliases, so this carries the var/let form the checker cannot.
      * Scoped strictly by narrowingAliases (lowerIf / lowerCondition). */
     aliasNarrowTypes = new Map();
+    /** Locals widened beyond the checker's type because an inferred indexed
+     * read can be absent at runtime. Bare reads preserve that union until a
+     * surrounding JavaScript guard/default consumes it. */
+    runtimeOptionalLocals = new Set();
+    /** All storage slots widened for runtime absence, including slots whose
+     * current control-flow branch has temporarily narrowed the value. */
+    runtimeOptionalStorageLocals = new Set();
+    /** Capture entries and their origin share one mutable box. Normalize each
+     * entry to the origin so writes and flow proofs stay synchronized. */
+    runtimeOptionalRoots = new Map();
+    runtimeOptionalRootOf(local) {
+        return this.runtimeOptionalRoots.get(local) ?? local;
+    }
     /** Runs `fn` with the given aliased-typeof narrows applied (and restored
      * after) — the branch-scoping primitive. */
     narrowingAliases(narrows, fn) {
@@ -939,6 +957,7 @@ export class Lowerer {
     startupCrash;
     /** Outbound native bindings by their source-level ambient name. */
     ffiImports;
+    libraryCallbacks;
     ffiImportsByName;
     /** Non-null after whole-program FFI declaration validation. */
     ffiBindingSymbols;
@@ -996,6 +1015,7 @@ export class Lowerer {
         this.targetPlatform = mode.targetPlatform ?? process.platform;
         this.startupCrash = mode.startupCrash ?? null;
         this.ffiImports = mode.ffiImports ?? [];
+        this.libraryCallbacks = mode.libraryCallbacks ?? false;
         this.ffiImportsByName = new Map(this.ffiImports.map((entry) => [entry.name, entry]));
         this.ffiBindingSymbols = mode.ffiBindingSymbols ?? null;
         this.externalTypes = mode.externalTypes ?? new Map();
@@ -1545,10 +1565,10 @@ export class Lowerer {
             this.unsupported("SC1090", ident, "assignments to catch bindings");
         }
         if (local)
-            return { id: local.id, type: local.type };
+            return local;
         const g = this.globalOf(ident);
         if (g)
-            return { id: g.id, type: g.type };
+            return g;
         return null;
     }
     fnSigOf(ident) {
@@ -2663,6 +2683,20 @@ export class Lowerer {
     fmt(t) {
         return formatIrType(t, this.shapes, this.unions);
     }
+    /** Whether an IR value has JavaScript Array identity. Homogeneous arrays
+     * use the native array representation; non-empty fixed tuples use a
+     * positional record shape so their slots can keep distinct types, but
+     * Array.isArray must still answer true for both representations. */
+    isArrayValueType(t) {
+        return t.kind === "array" || (t.kind === "record" && this.shapes.get(t.shapeId)?.tuple === true);
+    }
+    /** Runtime tags of every JavaScript-array arm in one union. Kept beside
+     * isArrayValueType so Array.isArray's predicate and its narrowing bridge
+     * cannot disagree about fixed tuple arms. */
+    arrayValueTags(unionId) {
+        const def = this.unions.get(unionId);
+        return def ? def.arms.flatMap((arm, tag) => (this.isArrayValueType(arm) ? [tag] : [])) : [];
+    }
     /** isJsonSafeType with this Lowerer's registries — the shared fence for
      * what JSON.stringify accepts and what a checked cast can validate. */
     jsonSafe(t) {
@@ -2696,18 +2730,49 @@ export class Lowerer {
     isIslandExpr(node) {
         return isIslandExpr(this, node);
     }
-    /** True when this node's CHECKER type is `any[]`/`unknown[]` — the type
-     * tsc's Array.isArray predicate narrows readonly arrays to (its `arg is
-     * any[]` quirk), and what a union collapses to when such an arm absorbs
-     * its siblings. The VALUE behind it can still be a real static array
-     * (maybeNarrow's isArray bridge extracts the union's array arm), so
-     * receiver-typed dispatch falls back to the LOWERED type under this
-     * test. */
+    /** 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
+     * this over the union arms). These are forms of the `arg is any[]`
+     * Array.isArray predicate; the VALUE behind them can still be a real
+     * static array/tuple (maybeNarrow's bridge extracts the union's one
+     * array-valued arm), so receiver-typed dispatch falls back to the LOWERED
+     * type under this test. */
     checkerAnyArray(node) {
-        const t = this.typeOf(node);
-        return (this.checker.isArrayType(t) &&
-            ((this.checker.getTypeArguments(t)[0]?.flags ?? 0) &
-                (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0);
+        return this.checkerAnyArrayType(this.typeOf(node));
+    }
+    /** Type-level half of checkerAnyArray, for narrowing sites that already
+     * queried the checker type from a general AST node. */
+    checkerAnyArrayType(t) {
+        const isAnyArray = (part) => this.checker.isArrayType(part) &&
+            ((this.checker.getTypeArguments(part)[0]?.flags ?? 0) &
+                (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0;
+        const visit = (part) => {
+            if (isAnyArray(part))
+                return true;
+            // 5.9 leaves `(U) & any[]` as one intersection; 7 distributes it
+            // into `(A & any[]) | (B & any[])`. An intersection is array-proven
+            // when one constituent is; a union is array-proven only when EVERY
+            // arm is, so an ordinary `any[] | string` never qualifies.
+            if ((part.flags & ts.TypeFlags.Intersection) !== 0) {
+                return part.getTypes().some(visit);
+            }
+            if (part.isUnionType())
+                return part.getTypes().every(visit);
+            return false;
+        };
+        return visit(t);
+    }
+    /** The lowered static array/tuple value behind checkerAnyArray's
+     * synthetic `any[]` spelling. Array.isArray can leave readonly tuple
+     * unions as intersections that do not map directly, while maybeNarrow
+     * still extracts the runtime-proven array arm from the original union.
+     * Receiver dispatchers use this bridge instead of the synthetic type. */
+    checkerArrayValue(node) {
+        if (!this.checkerAnyArray(node))
+            return null;
+        const value = this.lowerExpr(node);
+        return this.isArrayValueType(value.type) ? value : null;
     }
     /** Substitutes a bound type parameter anywhere inside mapType's recursion
      * (`T`, `T[]`, `{ v: T }`, `(x: T) => T` all resolve). Inert outside
@@ -6575,6 +6640,10 @@ export class Lowerer {
                     ctx.captureBySymbol.set(symbol, entry);
                     ctx.captures.push({ localId: entry.id, name: entry.name, type: entry.type });
                     ctx.captureSources.push(parentEntry.id);
+                    const runtimeOptionalRoot = this.runtimeOptionalRootOf(parentEntry);
+                    if (this.runtimeOptionalStorageLocals.has(runtimeOptionalRoot)) {
+                        this.runtimeOptionalRoots.set(entry, runtimeOptionalRoot);
+                    }
                 }
                 parentEntry = entry;
             }
@@ -6995,8 +7064,8 @@ export class Lowerer {
     lowerElementAccess(expr) {
         return lowerElementAccess(this, expr);
     }
-    lowerRecordKeyRead(expr, shapeId, shape) {
-        return lowerRecordKeyRead(this, expr, shapeId, shape);
+    lowerRecordKeyRead(expr, shapeId, shape, includeUndefined = false) {
+        return lowerRecordKeyRead(this, expr, shapeId, shape, includeUndefined);
     }
     lowerElementWrite(expr) {
         return lowerElementWrite(this, expr);