@scriptc/compiler 0.3.6 → 0.4.0

package/dist/ir/ir.d.ts

@@ -6,9 +6,9 @@ export interface SrcLoc {
     start: number;
     end: number;
 }
-/** Numeric typed-array element kinds with a native representation. Float16
- * and BigInt typed arrays remain frontend-fenced. */
-export type IrBytesElem = "u8" | "u8c" | "i8" | "u16" | "i16" | "u32" | "i32" | "f32" | "f64";
+/** Numeric typed-array element kinds with a native representation. BigInt
+ * typed arrays remain frontend-fenced. */
+export type IrBytesElem = "u8" | "u8c" | "i8" | "u16" | "i16" | "u32" | "i32" | "f16" | "f32" | "f64";
 export declare const BYTES_ELEMENT_SIZE: Record<IrBytesElem, number>;
 /** Integer element kinds: a valid element read is never NaN. */
 export declare function isIntegerBytesElem(elem: IrBytesElem): boolean;
@@ -361,6 +361,19 @@ export type IrType = {
  | {
     kind: "dyn";
 }
+/** A dynamic-tier value (two-tier design §5.1, stage S3): one 64-bit
+ * NaN-boxed word. Numbers, booleans, undefined and null are immediates
+ * (no allocation); strings and BigInts are the static tier's own objects
+ * under a pointer tag; every other value is a `dyn` cell under the cell
+ * tag. Only dynamic-tier functions operate on it (ir/tiers.ts, I1), and
+ * only through the `js.*` builtins, locals and moves: the jsval pass
+ * (ir/jsval.ts) introduces it after lowering, never the frontend. Static
+ * functions see it only as the operand or result of a boundary
+ * conversion. Refcounted: retain/release skip immediates. 32-bit targets
+ * represent it as a boxed `dyn` cell. */
+ | {
+    kind: "jsval";
+}
 /** A catch binding or its closure capture (never parameters, returns,
  * fields, arms or elements). The one global form is a module's recorded
  * evaluation error, written only from that module's catch binding and
@@ -368,8 +381,8 @@ export type IrType = {
  * Runtime representation is a refcounted snapshot box (ScrCaught) holding
  * the taken exception: a kind tag plus the payload. Even NARROWER than
  * dyn: the only expressions a caught value may appear in are `caughtTest`
- * (kind/instanceof tests), `caughtNarrow` (checker-trusted extraction
- * under a proven test), and the `rethrow` statement — the frontend
+ * (kind/instanceof tests), `caughtNarrow` (extraction under a proven
+ * test, verified at run time), and the `rethrow` statement — the frontend
  * rejects every other use with the narrowing hint. */
  | {
     kind: "caught";
@@ -426,9 +439,9 @@ declare const HANDLE_KIND_LIST: readonly ["stats", "fileHandle", "dir", "spawnRe
 export type HandleKind = (typeof HANDLE_KIND_LIST)[number];
 export declare const HANDLE_KINDS: IrKindSet<"child" | "childStream" | "childWriter" | "cryptoHash" | "cryptoHmac" | "dgramSocket" | "dir" | "fileHandle" | "fsWatcher" | "http2Session" | "http2Stream" | "httpClientReq" | "httpReq" | "httpRes" | "netServer" | "netSocket" | "procStream" | "secureCtx" | "spawnRes" | "stats" | "testCtx">;
 /** The IR kinds represented as pointers in native code. */
-declare const POINTER_KIND_LIST: readonly ["string", "bigint", "array", "map", "set", "regex", "bytes", "url", "searchParams", "symbol", "stats", "fileHandle", "dir", "spawnRes", "child", "netServer", "netSocket", "http2Session", "http2Stream", "dgramSocket", "testCtx", "httpReq", "httpRes", "httpClientReq", "secureCtx", "cryptoHash", "cryptoHmac", "fsWatcher", "childStream", "childWriter", "func", "object", "classval", "moduleNs", "record", "union", "dyn", "caught", "promise", "generator"];
+declare const POINTER_KIND_LIST: readonly ["string", "bigint", "array", "map", "set", "regex", "bytes", "url", "searchParams", "symbol", "stats", "fileHandle", "dir", "spawnRes", "child", "netServer", "netSocket", "http2Session", "http2Stream", "dgramSocket", "testCtx", "httpReq", "httpRes", "httpClientReq", "secureCtx", "cryptoHash", "cryptoHmac", "fsWatcher", "childStream", "childWriter", "func", "object", "classval", "moduleNs", "record", "union", "dyn", "jsval", "caught", "promise", "generator"];
 export type PointerKind = (typeof POINTER_KIND_LIST)[number];
-export declare const POINTER_KINDS: IrKindSet<"array" | "bigint" | "bytes" | "caught" | "child" | "childStream" | "childWriter" | "classval" | "cryptoHash" | "cryptoHmac" | "dgramSocket" | "dir" | "dyn" | "fileHandle" | "fsWatcher" | "func" | "generator" | "http2Session" | "http2Stream" | "httpClientReq" | "httpReq" | "httpRes" | "map" | "moduleNs" | "netServer" | "netSocket" | "object" | "promise" | "record" | "regex" | "searchParams" | "secureCtx" | "set" | "spawnRes" | "stats" | "string" | "symbol" | "testCtx" | "union" | "url">;
+export declare const POINTER_KINDS: IrKindSet<"array" | "bigint" | "bytes" | "caught" | "child" | "childStream" | "childWriter" | "classval" | "cryptoHash" | "cryptoHmac" | "dgramSocket" | "dir" | "dyn" | "fileHandle" | "fsWatcher" | "func" | "generator" | "http2Session" | "http2Stream" | "httpClientReq" | "httpReq" | "httpRes" | "jsval" | "map" | "moduleNs" | "netServer" | "netSocket" | "object" | "promise" | "record" | "regex" | "searchParams" | "secureCtx" | "set" | "spawnRes" | "stats" | "string" | "symbol" | "testCtx" | "union" | "url">;
 /** Runtime RC symbol stem for each IR type kind. An empty stem means the
  * kind is scalar/unit or uses an emitted per-shape helper (object/record).
  * Keeping this exhaustive makes a new runtime handle kind a compile error
@@ -475,6 +488,7 @@ export declare const CHILDWRITER_T: IrType;
 export declare const PROCSTREAM_T: IrType;
 export declare const VOID: IrType;
 export declare const DYN: IrType;
+export declare const JSVAL: IrType;
 export declare const CAUGHT: IrType;
 export declare const UNDEFINED_T: IrType;
 export declare const NULL_T: IrType;
@@ -504,8 +518,8 @@ export declare function isPrimitiveCollectionKey(t: IrType, unionArms?: IrType[]
 export declare function isSupportedMapKey(t: IrType, unionArms?: IrType[]): boolean;
 /** Set elements and Map keys share storage, equality and ownership rules. */
 export declare function isSupportedSetElem(t: IrType, unionArms?: IrType[]): boolean;
-/** The Map VALUE fence: scalars, supported native references and checked
- * values. Functions require checked-value boxing.
+/** The Map VALUE fence: scalars, supported native references, closures
+ * and checked values.
  * Record/object/union values can point back at the map holding them, which
  * is exactly why ref-valued maps are cycle-capable (see the backend's
  * cycle analysis and docs/memory.md). Shared frontend/validator. */
@@ -522,9 +536,17 @@ export declare function isSupportedMapValue(t: IrType): boolean;
 export declare function isSupportedIndexValue(t: IrType): boolean;
 export declare function funcOf(params: IrType[], ret: IrType): IrType;
 /** Maps and sets use tagged union storage and retain their native identity.
- * Promises still require nullable-only unions until their data-arm narrowing
- * and await boundary have a matching contract. */
+ * Joined unions (inferred joins of member reads and array elements) keep
+ * promises nullable-only; declared maybe-promise unions are admitted by
+ * maybePromiseUnionArmsOk. */
 export declare function unionContainerArmsOk(arms: IrType[]): boolean;
+/** The MAYBE-PROMISE union (`T | Promise<T>`, `Promise<R | void> | R |
+ * void`): at most one promise arm, beside unit or data arms. The union tag
+ * is the `instanceof Promise` test, and `await` / async `return` branch on
+ * it (the promise arm awaits or adopts, the other arms take the
+ * non-thenable path). Data arms must not be thenable; the type mapper
+ * checks that against the checker types before minting such a union. */
+export declare function maybePromiseUnionArmsOk(arms: IrType[]): boolean;
 /** Canonical, injective text form of an IrType — the building block of
  * shape/union identity keys, generic-function instantiation keys, and the
  * backend's per-type helper interning (jsonStringify/dynCheck walkers).
@@ -532,6 +554,12 @@ export declare function unionContainerArmsOk(arms: IrType[]): boolean;
  * canonical) shapeId/unionId, so keys stay finite and comparable. Lives in
  * the IR (not the frontend) because both ends need it. */
 export declare function typeKey(t: IrType): string;
+/** The type a CALL SITE (or function value) receives from a module
+ * function: an async body's returnType is the promise's INNER type, so
+ * calls and closures over it see Promise<T>; a generator body's is the
+ * TReturn channel, so call sites see the generator type. The one place
+ * the body/call-site split is spelled out, for the validator and lowering. */
+export declare function callSiteReturnType(fn: IrFunction): IrType;
 export declare function typeEquals(a: IrType, b: IrType): boolean;
 /** True for types whose values are heap-allocated and reference-counted.
  * The single dispatch point for the backend's RC machinery: retains,
@@ -541,7 +569,7 @@ export declare function typeEquals(a: IrType, b: IrType): boolean;
 export declare function isRefCounted(t: IrType): boolean;
 export interface IrModule {
     /** Bumped on any breaking IR change; serialize.ts refuses mismatches. */
-    irVersion: 16;
+    irVersion: 17;
     sourceFile: string;
     functions: IrFunction[];
     /** Class shapes. Constructors and methods are ordinary module functions
@@ -578,6 +606,10 @@ export interface IrModule {
      * ProgramLifetime instance lives in a counted region (the region.*
      * intrinsics; backend/llvm/regions.ts). */
     lifetimeRegions?: true;
+    /** Classes used as ThreadSlots keys (@scriptc/experimental): the root of
+     * each one's hierarchy carries a slot word (the slots.* intrinsics;
+     * backend/llvm/thread-slots.ts). */
+    threadSlotKeys?: string[];
     /** The entry module is CommonJS under Node's classification. Node runs a
      * CommonJS main synchronously and drains process.nextTick callbacks
      * before promise jobs at the first checkpoint; an ES-module main's
@@ -599,6 +631,23 @@ export interface IrModule {
      * write in the program (ir/contract-check.ts). Backends may rely on them
      * unconditionally. Absent when the program writes no contract. */
     contracts?: IrContracts;
+    /** The WebAssembly modules translated into this program (wasm/
+     * translate.ts), present exactly when the program uses the WebAssembly
+     * API (possibly empty). The backend appends each module's translation
+     * and emits the registry the runtime looks modules up in. */
+    wasmModules?: IrWasmModule[];
+    /** The program calls WebAssembly.Module.customSections, so translated
+     * modules keep their custom sections (otherwise they carry none, and
+     * debug sections cost nothing). */
+    wasmCustomSections?: boolean;
+}
+/** A WebAssembly module whose bytes the build saw, validated within the
+ * translatable feature level. */
+export interface IrWasmModule {
+    /** Hex SHA-256 of the bytes. */
+    sha256: string;
+    /** The bytes, base64. */
+    bytes: string;
 }
 /** Verified contract facts, keyed by IR names. */
 export interface IrContracts {
@@ -611,6 +660,14 @@ export interface IrContracts {
     /** Int32 locals (`${function}\0${localId}`, including every capture of a
      * captured binding) and module globals (`\0${globalId}`). */
     int32Locals?: string[];
+    /** Number-array slots whose arrays hold only int32 elements (Int32[]):
+     * every element store into any array that can reach them was proven an
+     * int32, so a present element read through them is an int32 (holes and
+     * missing indices still read as undefined). Keys: `l:${function}\0${localId}`
+     * (locals and parameters), `g:${globalId}`, `f:${field family}`,
+     * `s:${shapeId}\0${field}` (record fields) and `r:${function}` (results);
+     * see int32-slots.ts int32ElementSlot. */
+    int32Elements?: string[];
     /** Functions that cannot throw (NoThrow). */
     noThrow?: string[];
     /** Acyclic classes and object types, as cycle-analysis units
@@ -696,8 +753,8 @@ export interface IrLibExport {
     /** i64/u64 (ask 4): int64_t/uint64_t at the C edge — inbound values
      * range-check in the wrapper (`inboundIntTrap`), internal call sites
      * and returns are compile-time proven before this lands on the IR. */
-    params: ("f64" | "bool" | "string" | "bytes" | "u8" | "u32" | "i32" | "i64" | "u64")[];
-    returns: "f64" | "bool" | "string" | "bytes" | "void" | "i64" | "u64";
+    params: ("f64" | "bool" | "string" | "cstring" | "bytes" | "u8" | "u32" | "i32" | "i64" | "u64")[];
+    returns: "f64" | "bool" | "string" | "cstring" | "bytes" | "void" | "i64" | "u64";
     /** The exact sink-message bytes this wrapper passes to the inbound-bytes
      * marshalling helper's trap — present exactly when a parameter is
      * bytes-classed. Already the assembled structured trap-teaching form
@@ -712,6 +769,10 @@ export interface IrLibExport {
      * value cannot ride f64 exactly (|v| past 2^53−1). Same assembled
      * structured form and the same SC4012 code — one host-contract story. */
     inboundIntTrap?: string;
+    /** The sibling message for a NULL cstring parameter: present exactly
+     * when a parameter is cstring-classed, passed to scr_library_cstr_in.
+     * Same assembled structured form and the same SC4012 code. */
+    inboundCstringTrap?: string;
 }
 /** One runtime-trap overlay row: the profile's teaching (replaces the
  * baseline human line as field 0) and/or remediation (the optional fourth
@@ -736,7 +797,7 @@ export interface IrLibCallback {
     name: string;
     /** The runtime channel slot (profile declaration order). */
     slot: number;
-    params: ("f64" | "bool" | "string" | "bytes" | "u8" | "u32" | "i32")[];
+    params: ("f64" | "bool" | "string" | "cstring" | "bytes" | "u8" | "u32" | "i32")[];
     returns: "f64" | "bool" | "u8" | "u32" | "i32" | "i64" | "u64" | "pointer" | "void";
     /** The unregistered-call trap text (a DETECTED trap: plain bytes the
      * library funnel classifies SC4025 and assembles with the current
@@ -826,6 +887,11 @@ export interface IrClassDef {
      * bag. Its descriptors preserve presence and insertion order independently
      * of native layout order; field values remain in their native slots. */
     tracksOwnFields?: boolean;
+    /** Error subclasses: the field an instance's own `name` follows among its
+     * own properties, or null when it precedes every field. Absent when no
+     * class of the chain sets `name` during construction, and then an own
+     * `name` follows every other own property. */
+    errorNameAfter?: string | null;
     /** Stable module symbol identities for public instance layout fields. */
     symbolFields?: {
         field: string;
@@ -905,6 +971,26 @@ export declare const RUNTIME_ERROR_CLASSES: ReadonlyMap<string, {
  * The emitter hierarchy is UNCONDITIONALLY cycle-capable: the registry
  * owns listener closures, whatever the subclass fields say. */
 export declare const RUNTIME_EMITTER_CLASS = "%EventEmitter";
+/** The function that construction through a class value calls, and the
+ * index of its first argument. A program class constructs through
+ * `%C.constructor(this, ...)` after the thunk allocates; a runtime-provided
+ * class (EventEmitter, the stream and error classes) through the
+ * frontend's `%C.construct(...)`, which allocates through the runtime and
+ * returns the new instance. */
+export declare function classValueConstructor(def: {
+    name: string;
+    runtime?: true;
+}): {
+    fn: string;
+    firstArg: number;
+};
+/** The JavaScript `.name` of a class: its jsName, or the runtime-provided
+ * class's own name (`%TypeError` is TypeError). */
+export declare function classJsName(def: {
+    name: string;
+    runtime?: true;
+    jsName?: string;
+}): string;
 /** The runtime-provided node:stream classes (ScrStream / scr_stream_*,
  * scr_stream.c — link-gated by moduleUsesStream). They root at the
  * emitter class (base chains below), so the emitter method surface and
@@ -983,6 +1069,10 @@ export interface IrRecordShape {
      * fields carry that declaredOrder OMITS are internal '%'-fields (Dirent's
      * %dtype) — hidden from every key-order surface, JSON included. */
     declaredOrder?: string[];
+    /** Shapes with accessor slots: every own key in declaration order, with
+     * an accessor property named once (see accessorSlotProp). The
+     * checked-dynamic copy lists its keys in this order. */
+    accessorOrder?: string[];
 }
 /** fs.Dirent rows: the hidden %dtype entry kind (libuv's UV_DIRENT
  * encoding), then name and parentPath (type-mapper's interned shape). */
@@ -1087,11 +1177,32 @@ export interface IrFunction {
         resultType: IrType & {
             kind: "record";
         };
+        /** The first parameter is a generator this one reads from (an
+         * iterator helper's source): `.return()` before the first `.next()`
+         * closes it. */
+        closesSource?: true;
+        /** The @@toStringTag the object prints with (util.inspect,
+         * Object.prototype.toString) when it is not a generator object:
+         * "Iterator Helper", "Array Iterator", "String Iterator". A tag that
+         * starts with '!' marks a generator standing in for an object of
+         * another class, which those refuse to print. */
+        tag?: string;
+        /** The first parameter is a generator this one adapts: it prints with
+         * that generator's tag. */
+        inheritsTag?: true;
     };
     /** Source function name for native error stack frames. */
     sourceName?: string;
     /** Ordinary authored function declarations/expressions own a prototype. */
     ownsPrototype?: true;
+    /** The function's execution tier (ir/tiers.ts). Absent means static: the
+     * function may use dynamic values only through boundary operations
+     * (dynFrom, dynCheck, kind tests) and moves, which the validator enforces
+     * (invariant I1). "dynamic" admits the dynamic operation vocabulary
+     * (dynKeyGet, dynCall, dyn.* builtins, ...). Lowering assigns the field
+     * from the body (assignLegacyTiers); stage S2 of the two-tier design
+     * keeps it out of serialized IR, so loaders derive it again. */
+    tier?: "dynamic";
     body: IrStmt[];
     loc: SrcLoc;
 }
@@ -1313,13 +1424,21 @@ export type IrStmt =
 }
 /** Field write `obj.f = v` — statement-only, like `assign`/`arraySet`.
  * Evaluation order: obj, then value. The old value is released; ownership
- * of a refcounted new value MOVES into the object. */
+ * of a refcounted new value MOVES into the object. `sloppy` marks a write
+ * in sloppy-mode code, which skips a read-only field instead of throwing.
+ * `define` marks a class field initializer, which defines the property
+ * (a non-extensible instance rejects it). `attributesChecked` marks a
+ * write that already honors the instance's property attributes
+ * (CLASS_ATTRIBUTES). */
  | {
     kind: "fieldSet";
     obj: IrExpr;
     className: string;
     field: string;
     value: IrExpr;
+    sloppy?: true;
+    define?: true;
+    attributesChecked?: true;
     loc: SrcLoc;
 }
 /** Record field write `r.f = v` — mirrors `fieldSet` exactly (evaluation
@@ -1456,6 +1575,11 @@ export type IrStmt =
     /** Resource-management cleanup: if the guarded body and cleanup both
      * throw, raise a SuppressedError instead of replacing the first error. */
     suppressFinallyErrors?: true;
+    /** Iterator closing: if the guarded body threw and the cleanup throws
+     * too, the cleanup's error is dropped and the first one propagates.
+     * After a generator .return() the cleanup's error replaces it, and on
+     * normal exits it propagates. */
+    dropFinallyErrors?: true;
     loc: SrcLoc;
 };
 /** The complete array method/property surface (mirrors ambient/scriptc.d.ts).
@@ -1663,7 +1787,7 @@ export type IrBytesIntrinsicMethod = "buffer" | "length" | "byteLength" | "get"
  * slice, never throws. u8 receivers keep the Buffer fill family above
  * (same observable number-fill result; Buffer's throwing offset
  * validation). */
- | "fillElem" | "copy" | "swap16" | "swap32" | "swap64" | "writeStr" | "byteOffset" | "dataViewNew" | "dvGetUint8" | "dvGetInt8" | "dvGetUint16" | "dvGetInt16" | "dvGetUint32" | "dvGetInt32" | "dvGetFloat32" | "dvGetFloat64" | "dvGetBigUint64Number" | "dvGetBigInt64Number" | "dvSetUint8" | "dvSetInt8" | "dvSetUint16" | "dvSetInt16" | "dvSetUint32" | "dvSetInt32" | "dvSetFloat32" | "dvSetFloat64";
+ | "fillElem" | "copy" | "swap16" | "swap32" | "swap64" | "writeStr" | "byteOffset" | "dataViewNew" | "dvGetUint8" | "dvGetInt8" | "dvGetUint16" | "dvGetInt16" | "dvGetUint32" | "dvGetInt32" | "dvGetFloat16" | "dvGetFloat32" | "dvGetFloat64" | "dvGetBigUint64Number" | "dvGetBigInt64Number" | "dvSetUint8" | "dvSetInt8" | "dvSetUint16" | "dvSetInt16" | "dvSetUint32" | "dvSetInt32" | "dvSetFloat16" | "dvSetFloat32" | "dvSetFloat64";
 /** The bytesIntrinsic methods that can raise a catchable error — backends'
  * may-throw analyses seed on these exactly like MAY_THROW_LIB_FNS. */
 export declare const MAY_THROW_BYTES_METHODS: ReadonlySet<IrBytesIntrinsicMethod>;
@@ -1708,13 +1832,21 @@ export type IrRegexIntrinsicMethod = "test" | "match"
  * unobservable across the lowered surface (strings are immutable; the
  * spec clones the regex at the call, so lastIndex games can't reach the
  * drain either). Non-global regexes THROW Node's exact TypeError
- * (catchable — replaceAll's stance). */
+ * (catchable — replaceAll's stance). Each row carries its index, input
+ * and groups properties. */
  | "matchAll"
+/** matchAll whose rows are read only through their elements
+ * (matchAllRowsReadByElements): the rows carry no index, input or
+ * groups properties. Same result and throw contract as matchAll. */
+ | "matchAllCaptures"
 /** matchAll's companion-index form (the for-of-over-matchAll desugar):
  * args[1] is a number[] the drain ALSO fills with each match's UTF-16
  * start index — the row's `.index`, always present (every drained row
  * matched). Same result and throw contract as matchAll. */
  | "matchAllInto"
+/** matchAllInto whose rows are read only through their elements and the
+ * companion index: the rows carry no index, input or groups properties. */
+ | "matchAllCapturesInto"
 /** `s.search(re)` — the first match's UTF-16 index, or -1. Symbol.search
  * neither reads nor writes lastIndex (a fresh exec from position 0), so
  * no g/y fence applies: /g is irrelevant and /y anchors at 0 — exactly
@@ -1881,15 +2013,12 @@ export type IrExpr =
     type: IrType;
     loc: SrcLoc;
 }
-/** String ordering. Ordinary source comparisons omit `utf16` and retain
- * scriptc's documented code-point order; the default Array sort comparator
- * sets it to request ECMAScript's UTF-16 code-unit order. */
+/** String ordering in ECMAScript's UTF-16 code-unit order. */
  | {
     kind: "strCmp";
     op: IrStrCmpOp;
     left: IrExpr;
     right: IrExpr;
-    utf16?: boolean;
     type: IrType;
     loc: SrcLoc;
 }
@@ -2003,7 +2132,7 @@ export type IrExpr =
 }
 /** A regex literal `/ab+c/gi`. `pattern` is the text between the slashes
  * exactly as written (escapes UNprocessed — the regex engine parses them),
- * `flags` the trailing flags in source order (alphabet fenced to gimsuy by
+ * `flags` the trailing flags in getter order (alphabet fenced to gimsuvy by
  * the frontend). Backends intern ONE immortal static per (pattern, flags)
  * pair — like string literals, so repeated evaluation is free and
  * `re === re` would hold — and compile the pattern lazily at first use
@@ -2519,11 +2648,12 @@ export type IrExpr =
     type: IrType;
     loc: SrcLoc;
 }
-/** Checker-trusted narrowing of a base-class value to a subclass (`type`
- * is the subclass). The frontend emits this only where tsc's control-flow
- * narrowing has already proven the dynamic class (an `instanceof` guard)
- * — the same trust-the-checker contract as unionNarrow: no runtime check,
- * a pointer reinterpret with ownership transferring like upcast. */
+/** Narrowing of a base-class value to a subclass (`type` is the
+ * subclass). The frontend emits this only where tsc's control-flow
+ * narrowing has already proven the dynamic class (an `instanceof` guard),
+ * like unionNarrow. Backends verify the class once and trap on a mismatch
+ * (a compiler bug or a lying type predicate or assertion function), then
+ * reinterpret the pointer with ownership transferring like upcast. */
  | {
     kind: "downcast";
     value: IrExpr;
@@ -2632,26 +2762,30 @@ export type IrExpr =
  * Declared fields are tried FIRST (an emitted string-switch — field
  * access exactness is preserved: a declared name always answers from the
  * struct slot), then the overflow map on index-signature shapes. `type`
- * is the CHECKER's type for the access: the index signature's value type
- * (dyn for `unknown`; with noUncheckedIndexedAccess, its
- * `V | undefined` union). A MISSING key produces: the undefined dyn
- * singleton when `type` is dyn; the undefined arm when `type` is an
- * undefined-armed union; otherwise a TRAP — the checker claimed V and no
- * undefined is representable (the array OOB policy; on declared-only
- * shapes tsc's keyof check makes the trap unreachable without an `as`
- * smuggle). Declared-field values surface as `type`: V-typed fields read
- * directly, dyn results build a dyn COPY of the field value (the dynFrom
- * conversion — deep for composites, documented), union results wrap.
+ * is the index signature's value type armed with undefined (dyn for
+ * `unknown`), so a missing key reads undefined as in JavaScript, or the
+ * declared fields' common type on signature-free shapes. A MISSING key
+ * produces: the undefined dyn singleton when `type` is dyn; the undefined
+ * arm when `type` is an undefined-armed union; NaN with `missNaN`;
+ * otherwise a TRAP (declared-only shapes, where tsc's keyof check makes
+ * the trap unreachable without an `as` smuggle). Declared-field values
+ * surface as `type`: V-typed fields read directly, dyn results build a
+ * dyn COPY of the field value (the dynFrom conversion — deep for
+ * composites, documented), union results wrap.
  * The key and object are borrowed; refcounted results are owned (+1).
  * `overflowOnly` (set when the key is a LITERAL that names no declared
  * field): the read touches only the overflow map — declared fields need
- * not surface as `type`, and the emitted helper skips the string-switch. */
+ * not surface as `type`, and the emitted helper skips the string-switch.
+ * `missNaN` (with an f64 `type`): a missing key produces NaN instead of
+ * trapping, for reads whose every consumer treats undefined like NaN
+ * (nan-coded-reads.ts). */
  | {
     kind: "recordKeyGet";
     obj: IrExpr;
     shapeId: string;
     key: IrExpr;
     overflowOnly?: true;
+    missNaN?: true;
     type: IrType;
     loc: SrcLoc;
 }
@@ -2814,9 +2948,10 @@ export type IrExpr =
 /** Keyed read on a dyn value — `pkg.name` / `pkg["k"]` / the
  * `pkg?.scripts` chain step on a JSON.parse result. `key` is
  * string-typed (a strLit for the dot form); `type` is always dyn. An
- * OBJ receiver answers the member (+1) or the undefined singleton (the
- * own-property answer — prototype members like `toString` answer
- * undefined, SEMANTICS.md); ARR answers `length` and canonical
+ * OBJ receiver answers the member (+1), an inherited Object.prototype
+ * member (the Object constructor and the interned valueOf/toString/
+ * hasOwnProperty/propertyIsEnumerable values), or the undefined singleton;
+ * ARR answers `length` and canonical
  * in-range indices, STR answers `length` (UTF-16-exact), both
  * undefined otherwise; NUM/BOOL/BYTES answer undefined. An
  * undefined/null receiver THROWS the catchable Node-shaped TypeError
@@ -3050,12 +3185,13 @@ export type IrExpr =
     type: IrType;
     loc: SrcLoc;
 }
-/** Checker-trusted extraction of a catch binding's payload as `type` —
- * the caught analog of unionNarrow: the frontend emits this only where
- * tsc's control-flow narrowing has already proven the matching test
- * (`e instanceof C` / `typeof e === "string"`), so the read is
- * kind-UNCHECKED at runtime. `type` is f64, bool, string, or a
- * class object; refcounted results come out retained (+1). */
+/** Extraction of a catch binding's payload as `type` — the caught
+ * analog of unionNarrow: the frontend emits this only where tsc's
+ * control-flow narrowing has already proven the matching test
+ * (`e instanceof C` / `typeof e === "string"`). Backends verify the kind
+ * or class once and trap on a mismatch (a compiler bug or a lying type
+ * predicate or assertion function). `type` is f64, bool, string, or a class object; refcounted results come
+ * out retained (+1). */
  | {
     kind: "caughtNarrow";
     value: IrExpr;
@@ -3097,11 +3233,13 @@ export type IrExpr =
     type: IrType;
     loc: SrcLoc;
 }
-/** Union payload extraction, tag-UNCHECKED: `value` is union-typed,
- * `type` is arms[tag], and the backend reads the payload assuming the tag
- * — SOUNDNESS RESTS ON tsc's control-flow narrowing (the frontend emits
- * this only where the checker has already narrowed the expression to that
- * arm; see docs/ir.md). Refcounted payloads come out retained (+1). */
+/** Union payload extraction: `value` is union-typed and `type` is
+ * arms[tag]. The frontend emits this only where tsc's control-flow
+ * narrowing has already narrowed the expression to that arm; backends
+ * verify the tag once and trap on a mismatch (a compiler bug or a lying
+ * type predicate or assertion function), so a wrong proof cannot read the
+ * payload as another arm.
+ * Refcounted payloads come out retained (+1). */
  | {
     kind: "unionNarrow";
     unionId: string;
@@ -3225,7 +3363,7 @@ export type IrExpr =
  * (a module binding of an import cycle read before its declaration). */
  | {
     kind: "intrinsic";
-    name: "console.log" | "console.error" | "promise.race" | "promise.all" | "promise.allSettled" | "promise.any" | "promise.reject" | "promise.resolve" | "module.await" | "module.tdzCheck" | "threads.publish" | "region.create" | "region.enter" | "region.leave" | "region.release" | "itable.open" | "itable.find" | "itable.insert" | "itable.value" | "itable.size";
+    name: "console.log" | "console.error" | "promise.race" | "promise.all" | "promise.allSettled" | "promise.any" | "promise.reject" | "promise.resolve" | "module.await" | "module.tdzCheck" | "threads.publish" | "region.create" | "region.enter" | "region.leave" | "region.release" | "itable.open" | "itable.find" | "itable.insert" | "itable.value" | "itable.size" | "slots.get" | "slots.has" | "slots.set" | "slots.delete";
     args: IrExpr[];
     type: IrType;
     loc: SrcLoc;
@@ -3249,6 +3387,11 @@ export type IrExpr =
     type: IrType;
     loc: SrcLoc;
     prototypeIdentityOnly?: true;
+    /** A timer call through an ESM named or namespace import of
+     * node:timers. Node's mock.timers replaces the globals and the
+     * module object's properties, which these bindings do not follow,
+     * so the call keeps the loop's timer. */
+    realTimer?: true;
     /** An assertion call made through a node:assert Assert instance: the
      * instance options the runtime applies to this call. Backends set
      * them right before the runtime call, after its arguments are
@@ -3269,11 +3412,14 @@ export type IrExpr =
  * `null` and -0 as `0`, exactly like JS; a record field holding the
  * undefined arm of its union (an optional field) is DROPPED from the
  * output — Node's rule for undefined-valued properties. The value is
- * BORROWED; the result string is owned (+1). Never throws. */
+ * BORROWED; the result string is owned (+1). Never throws. `circular`
+ * is util.format's %j (Node's tryStringify): a circular structure gives
+ * the text "[Circular]" instead of the TypeError. */
  | {
     kind: "jsonStringify";
     value: IrExpr;
     indent?: string;
+    circular?: true;
     type: IrType;
     loc: SrcLoc;
 }
@@ -3335,9 +3481,10 @@ export declare function isJsonSafeType(t: IrType, getRecord: (shapeId: string) =
  * root remains outside the domain because JSON.stringify returns the
  * undefined value instead of a string. */
 export declare function isJsonStringifySafeType(t: IrType, getRecord: (shapeId: string) => IrRecordShape | undefined, getUnion: (unionId: string) => IrUnionDef | undefined): boolean;
-/** A JSON-shaped container with unknown payloads needs the runtime JSON
- * traversal. Its declared structure can be boxed, but payloads may carry
- * omitted values, toJSON methods, or cycles. This predicate does not widen
+/** A JSON-shaped container with unknown payloads, or a class instance at
+ * any position, needs the runtime JSON traversal. Its declared structure can
+ * be boxed, but payloads may carry omitted values, toJSON methods, added
+ * properties, or cycles. This predicate does not widen
  * the type-directed serializer, checked-value boundary, or root-undefined
  * contract; callers must select the checked runtime traversal explicitly. */
 export declare function isJsonStringifyDynamicType(t: IrType, getRecord: (shapeId: string) => IrRecordShape | undefined, getUnion: (unionId: string) => IrUnionDef | undefined): boolean;
@@ -3369,6 +3516,22 @@ export declare function isDynTypedRefType(t: IrType): t is Extract<IrType, {
 export declare function isClassOwnEnumerableFieldName(name: string): boolean;
 /** Compiler-owned storage for properties added through untyped references. */
 export declare const DYN_CLASS_PROPERTIES = "%dynProperties";
+/** Compiler-owned integrity state of a class instance whose hierarchy is
+ * passed to Object.freeze, Object.seal, Object.preventExtensions or
+ * Object.defineProperty: an f64 holding CLASS_NOT_EXTENSIBLE, CLASS_SEALED
+ * and CLASS_FROZEN bits. Other hierarchies have no such field. */
+export declare const CLASS_ATTRIBUTES = "%attributes";
+export declare const CLASS_NOT_EXTENSIBLE = 1;
+export declare const CLASS_SEALED = 2;
+export declare const CLASS_FROZEN = 4;
+/** Compiler-owned attributes of one declared field that Object.defineProperty
+ * changes: an f64 holding FIELD_NOT_WRITABLE, FIELD_NOT_ENUMERABLE and
+ * FIELD_NOT_CONFIGURABLE bits (zero is an ordinary data property). */
+export declare const CLASS_FIELD_ATTRIBUTES_PREFIX = "%attr:";
+export declare const FIELD_NOT_WRITABLE = 1;
+export declare const FIELD_NOT_ENUMERABLE = 2;
+export declare const FIELD_NOT_CONFIGURABLE = 4;
+export declare function classFieldAttributesName(field: string): string;
 /** A class capsule can always preserve its exact native identity. Its
  * optional property view additionally needs converters in both directions;
  * fields such as Maps may remain opaque without preventing the round trip. */