@scriptc/compiler 0.0.0 → 0.0.2

package/dist/frontend/lowering/lower-containers.d.ts

@@ -0,0 +1,486 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { IrExpr, IrFunction, IrRecordShape, IrStmt, IrType, SrcLoc } from "../../ir/nodes.js";
+/** Ambient array method calls. `push`/`pop`/`indexOf`/`includes`/`join`
+   * lower to arrIntrinsic; the HOF family — `map`/`filter`/`forEach`/
+   * `find`/`some`/`every`/`flatMap`/`reduce`/`reduceRight` — desugars to a
+   * direct call of a synthetic loop function (see lowerArrayHofCall and
+   * friends). Null when this isn't an ambient array method call. tsc has
+   * already checked arity and argument types against ambient/scriptc.d.ts. */
+export declare function lowerArrayMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `a.map(fn)` / `a.filter(fn)` / `a.forEach(fn)` desugar to a direct
+   * call of a synthetic module function — one per method + element/result
+   * type + callback-arity combination, interned — whose body is a plain
+   * loop over EXISTING IR nodes (varDecl/for/arrayGet/callValue/push/
+   * return). No new IR kinds, no backend or runtime involvement. JS
+   * semantics: the length is read ONCE up front (Array.prototype.map/
+   * filter/forEach cache it — elements appended by the callback are not
+   * visited), elements are read fresh each iteration, callbacks run
+   * left-to-right and receive whatever prefix of (element, index, array)
+   * they declare. */
+export declare function lowerArrayHofCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, method: "map" | "filter" | "forEach", elem: IrType): IrExpr;
+/** Interned synthetic loop function for one (method, elem, fnRet, arity)
+   * combo. Named `%arr.<method>.<n>` ('%' keeps it out of the user
+   * namespace); rides `liftedFns` into the module like a lifted lambda (it
+   * is a plain function — no captures). */
+export declare function arrayHofHelper(L: Lowerer, method: "map" | "filter" | "forEach", elem: IrType, fnRet: IrType, arity: number, loc: SrcLoc): string;
+/** READ-ONLY array methods on TUPLE receivers — `t.slice(...)` and
+   * `t.map(f)`: a tuple is a fixed-shape record, but these methods never
+   * write, so the positions snapshot into a fresh array (the for-of-over-
+   * tuples stance — pure receivers only, since the reads re-emit per
+   * position) and the ordinary array machinery runs over it. The element
+   * type is the one position type, or the positions' interned union with
+   * each read wrapped into its arm (exactly the checker's callback
+   * parameter type). Null when this isn't a tuple slice/map — writers and
+   * the rest of the surface keep their fences. */
+export declare function lowerTupleReadMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The OOB-SAFE indexed read for --npm-static package files: `xs[i]`
+   * answers the interned `elem | undefined` union — the element when `i`
+   * is an integer in [0, len), JS's property-miss undefined otherwise —
+   * instead of the trap divergence 4 documents for program code.
+   * Package JS is inference-typed, guard-style code (`registeredArguments
+   * .slice(-1)[0]`, commander's last-element probe), and the trap would
+   * fire on working Node idioms; program files keep the documented trap
+   * (their annotations can prove bounds). Null when the element is
+   * union-typed (the re-tag has no story here) — the caller keeps the
+   * ordinary read. */
+export declare function lowerNpmStaticSafeIndexRead(L: Lowerer, arr: IrExpr & {
+    type: {
+        kind: "array";
+    };
+}, index: IrExpr, loc: SrcLoc): IrExpr | null;
+/** Interned synthetic function for one (elem, argument-shape) concat —
+   * `%arr.concat.<n>(a, x0, x1, ...)`: a fresh array takes a's elements
+   * (pushSpread), then each argument pushes (element) or spreads (array)
+   * in order; the receiver and array arguments are only READ. Rides
+   * liftedFns like the HOF helpers (a plain function — no captures). */
+export declare function arrayConcatHelper(L: Lowerer, elem: IrType, shape: ("e" | "a")[], loc: SrcLoc): string;
+/** The loop body of one synthetic array HOF, from existing IR nodes:
+   *
+   *   map:     out = []; n = a.length; for (i = 0; i < n; i++) out.push(f(a[i])); return out;
+   *   filter:  out = []; n = a.length; for (...) { v = a[i]; if (f(v)) out.push(v); } return out;
+   *   forEach: n = a.length; for (...) f(a[i]);
+   *
+   * `filter` reads the element once into `v` so the callback and the push
+   * see the same value even if the callback mutates `a[i]` (JS-exact).
+   * `arity` is the callback's declared parameter count (1–3): the loop
+   * passes the index and the receiver itself after the element when the
+   * callback names them, exactly the arguments JS supplies. */
+export declare function buildArrayHofFn(L: Lowerer, name: string, method: "map" | "filter" | "forEach", elem: IrType, fnRet: IrType, arity: number, loc: SrcLoc): IrFunction;
+/** `a.find(f)` / `a.findIndex(f)` / `a.findLast(f)` / `a.findLastIndex(f)`
+   * / `a.some(f)` / `a.every(f)` — the early-return HOFs, same
+   * desugar-to-loop machinery. some/every return bool from a short-circuit
+   * loop; findIndex/findLastIndex return the first matching index or -1
+   * (plain f64 — no union). find/findLast return `T | undefined` — the
+   * checker's own result union —
+   * with the found element wrapped into its arm and the miss producing the
+   * undefined unit arm (for REF elements that arm is the unit instance, the
+   * standard union machinery). The Last pair is the SAME loop walked
+   * backwards (`i = n - 1; i >= 0; i--`), exactly the es2023 spec's
+   * descending index walk. All require a bool-returning callback
+   * (JS's ToBoolean of arbitrary predicate results has no lowering). */
+export declare function lowerArrayFindLikeCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, method: "find" | "findIndex" | "findLast" | "findLastIndex" | "some" | "every", elem: IrType): IrExpr;
+/** `a.flatMap(f)` — map plus a one-level flatten. A callback returning
+   * `U[]` appends the returned array's elements per receiver element; a
+   * callback returning a non-array U doesn't flatten (JS pushes it as-is),
+   * which IS map — those calls share map's interned helper. A union return
+   * mixing array and non-array arms would need a per-value flatten decision
+   * — fenced. */
+export declare function lowerArrayFlatMapCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, elem: IrType): IrExpr;
+/** `a.reduce(f)` / `a.reduce(f, init)` and reduceRight — both declared
+   * forms. The accumulator type is the call's own checked result: U with an
+   * initial value, the element type without one. The callback may declare
+   * any prefix of (acc, element, index, array). Without an initial value an
+   * empty receiver throws Node's exact TypeError at runtime. */
+export declare function lowerArrayReduceCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, method: "reduce" | "reduceRight", elem: IrType): IrExpr;
+/** `a.sort(cmp)` — in-place, returns the receiver (JS's `this`), desugared
+   * to an interned synthetic function like the other array HOFs. The loop
+   * is a binary-free INSERTION sort: stable (equal-comparing elements keep
+   * their source order, which is what Node's stable TimSort produces for
+   * any consistent comparator) and JS-faithful on the comparator contract —
+   * an element moves left only while cmp(left, v) > 0, so a NaN or 0
+   * result holds position exactly like the spec's "treat as equal". The
+   * SEQUENCE of comparator calls differs from V8's TimSort (SEMANTICS.md);
+   * results are identical for consistent comparators. The comparator-less
+   * form lowers for STRING elements only — JS's default converts every
+   * element to string and compares UTF-16 units, which for strings is the
+   * relational operator the compiler already has (an interned synthesized
+   * comparator); for numbers that default is the notorious string sort
+   * ([10, 9, 1] → [1, 10, 9]), deliberately fenced toward an explicit
+   * comparator. */
+export declare function lowerArraySortCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, elem: IrType, arrT: IrType & {
+    kind: "array";
+}): IrExpr;
+/** `a.at(i)` — the es2022 relative-index read. Desugars to an interned
+   * helper over existing IR nodes, ToIntegerOrInfinity-exact: the index
+   * truncates toward zero (floor for non-negatives, mirrored floor for
+   * negatives, NaN → 0), negatives wrap by the length once, and anything
+   * still outside [0, n) answers the undefined arm — never a bounds throw.
+   * The result is the checker's own `T | undefined` union, the find
+   * machinery's wrap rules (an undefined-armed element type passes
+   * through). */
+export declare function lowerArrayAtCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, elem: IrType): IrExpr;
+/** `Array.from({ length: n }, mapfn)` — the counted-generation idiom — on
+   * THE stdlib Array global. The source must be an OBJECT LITERAL whose
+   * single property is `length` (the shape the idiom always spells; the
+   * ArrayLike record never exists as a value). Desugars to an interned
+   * synthetic loop calling the mapper with (undefined, i) exactly like JS —
+   * the first argument is the dyn undefined singleton, matching the
+   * checker's own `unknown` for it — and pushing each result. The loop
+   * bound is `i <= n - 1`, which IS ToLength for the finite lengths that
+   * terminate (fractional lengths truncate, negative/NaN produce an empty
+   * array — Node-exact). Every other Array.from shape (arrays, iterables,
+   * no mapper) keeps the fence. Null when the callee isn't an
+   * Array-static access. */
+export declare function lowerArrayFromCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `Array.from(s)` / `[...s]` on a STRING: the code-point split into a
+   * fresh string[], through one interned helper per module. */
+export declare function strCharsCall(L: Lowerer, src: IrExpr, loc: SrcLoc): IrExpr;
+/** Ambient Map method calls. `get`/`set`/`has`/`delete`/`clear` lower to
+   * mapIntrinsic; `forEach` desugars to a direct call of a synthetic loop
+   * function over the iteration primitives (lowerMapForEachCall). Null when
+   * this isn't an ambient Map method call. tsc has already checked arity
+   * and argument types against ambient/scriptc.d.ts. */
+export declare function lowerMapMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `m.forEach(fn)` desugars to a direct call of a synthetic module
+   * function — one per key/value type + callback arity, interned — whose
+   * body is an index loop over the map's ITERATION PRIMITIVES: read
+   * iterCount fresh every pass (entries appended by the callback are
+   * visited), skip tombstones with iterLive (deleted entries are skipped),
+   * and bracket the loop with iterEnter/iterExit inside try/finally so the
+   * runtime never compacts indices out from under it — even when the
+   * callback throws. That is JS's live-iteration contract, Node-verified
+   * (SEMANTICS.md). The callback receives (value, key) like JS; declaring
+   * fewer parameters — (value) or () — is ordinary TS and supported. */
+export declare function lowerMapForEachCall(L: Lowerer, call: ts.CallExpression, receiver: IrExpr, mapT: IrType & {
+    kind: "map";
+}): IrExpr;
+/** The loop body of the Map.forEach desugar, from existing IR nodes:
+   *
+   *   m.iterEnter();
+   *   try {
+   *     for (i = 0; i < m.iterCount; i++) {
+   *       if (m.iterLive(i)) { v = m.iterValue(i); k = m.iterKey(i); f(v, k); }
+   *     }
+   *   } finally { m.iterExit(); }
+   *
+   * The finally keeps the runtime's iteration depth exact when the callback
+   * throws (unwinding runs the finally with the exception pending and
+   * propagation resumes — the emitter's standard contract). */
+export declare function buildMapForEachFn(L: Lowerer, name: string, mapT: IrType & {
+    kind: "map";
+}, arity: number, fnRet: IrType, loc: SrcLoc): IrFunction;
+/** Ambient Set method calls — Map's lowering with the value slot gone.
+   * `add`/`has`/`delete`/`clear` lower to setIntrinsic; `forEach` desugars
+   * like Map's over the shared iteration primitives. Null when this isn't
+   * an ambient Set method call. */
+export declare function lowerSetMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `s.forEach(fn)` — Map's desugar shape over the set primitives. JS
+   * passes (value, value, set): the second parameter IS the element again,
+   * so both one- and two-parameter callbacks receive elem-typed arguments
+   * (iterKey read once, passed twice). Same live-iteration bracketing. */
+export declare function lowerSetForEachCall(L: Lowerer, call: ts.CallExpression, receiver: IrExpr, setT: IrType & {
+    kind: "set";
+}): IrExpr;
+/** The loop body of the Set.forEach desugar — buildMapForEachFn with
+   * iterKey as the (single) element read:
+   *
+   *   s.iterEnter();
+   *   try {
+   *     for (i = 0; i < s.iterCount; i++) {
+   *       if (s.iterLive(i)) { v = s.iterKey(i); f(v, v); }
+   *     }
+   *   } finally { s.iterExit(); }
+   */
+export declare function buildSetForEachFn(L: Lowerer, name: string, setT: IrType & {
+    kind: "set";
+}, arity: number, fnRet: IrType, loc: SrcLoc): IrFunction;
+/** Object.groupBy / Map.groupBy (ES2024): group an ARRAY's elements by a
+   * per-element key. Both lower to one interned helper loop per callback
+   * type — the callback runs synchronously per element (index included in
+   * the two-parameter form), the first occurrence of a key creates its
+   * group in encounter order, and later hits push onto the same array
+   * (JS's exact accumulation — the stored arrays are the live groups).
+   * Map.groupBy keeps typed keys under SameValueZero; Object.groupBy
+   * requires a STRING-KEYED result (Partial<Record<string, T[]>> — a
+   * literal-union key type makes a fixed-field record, which has no
+   * grouping representation) and stringifies number keys like JS property
+   * keys. Node's result carries a null prototype — records here have no
+   * prototype at all, so the difference is unobservable except through
+   * util.inspect's "[Object: null prototype]" prefix (ledgered). Other
+   * iterables fence (spread into an array first); Null when the callee
+   * isn't the stdlib Object/Map groupBy. */
+export declare function lowerGroupByStaticCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The lowered iterator-helper chains: `arr.values()` (the array
+   * iterator) through any run of map/filter/take/drop/flatMap into a
+   * consuming terminal (toArray/forEach/reduce/some/every/find), FUSED
+   * into one per-element loop — which IS the helpers' lazy pull order:
+   * each source element flows through every stage before the next is
+   * touched, take closes the pipeline without pulling upstream again
+   * (budget checked before delivery), and short-circuit terminals stop
+   * the walk at their hit. Stage callbacks take (value) or (value,
+   * counter) — counters count each stage's own input stream, per spec.
+   * take/drop budgets validate eagerly AT THE CALL (Node's RangeError,
+   * raw value in the message) through an interned checker call inserted
+   * at the argument's evaluation position. The source array is iterated
+   * LIVE by index against a re-read length, exactly the array iterator's
+   * contract. Everything else — iterator objects stored in bindings,
+   * generator/Set/Map receivers, Iterator.from — keeps the lib fences.
+   * Null when the callee isn't a terminal over such a chain. */
+export declare function lowerIteratorHelperCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The ES2025 Set composition methods (union/intersection/difference/
+   * symmetricDifference/isSubsetOf/isSupersetOf/isDisjointFrom): one
+   * set-like argument, desugared to an interned two-set helper loop. Only
+   * a REAL Set argument of the receiver's element type lowers — the
+   * desugar substitutes the builtin has/size for the spec's observable
+   * calls, which is exact for Sets and wrong for anything else (a Map or
+   * a custom { has, size, keys } object fences). */
+export declare function lowerSetCombineCall(L: Lowerer, call: ts.CallExpression, name: string, receiver: IrExpr, setT: IrType & {
+    kind: "set";
+}): IrExpr;
+/** `for (const [k, v] of m)` / `for (const e of m)` — for-of over a Map,
+   * desugared IN PLACE (the body is user code, so no helper function) over
+   * the same iteration primitives as the forEach desugar, with the same
+   * Node-exact live-iteration contract: iterCount re-read every pass
+   * (entries appended by the body are visited), tombstones skipped
+   * (deleted entries are not). Shape:
+   *
+   *   %m = <iterable>; %m.iterEnter();
+   *   try {
+   *     for (%i = 0; %i < %m.iterCount; %i++) {
+   *       if (%m.iterLive(%i)) { <bindings>; <body> }
+   *     }
+   *   } catch (%c) { %m.iterExit(); rethrow %c; }
+   *   %m.iterExit();
+   *
+   * catch-and-rethrow instead of a finally because break/continue/return
+   * may not cross a finally (the emitter's documented contract) and a
+   * for-of body legitimately contains all three: break/continue bind to
+   * the desugared loop INSIDE the plain try (jumps out of plain try need
+   * nothing), and every `return` in the body gets an iterExit inserted
+   * before it (exitBeforeReturns) so the depth count stays exact on that
+   * path too. A `[k, v]` head of plain identifiers binds straight from
+   * iterKey/iterValue — the tuple record never materializes; an identifier
+   * head binds the checker's own [K, V] tuple built per iteration. */
+/** The iterator-method projections a for-of can ride directly:
+ * `for (const k of m.keys())`, `.values()`, `.entries()` — the SAME
+ * live-iteration walk as `for..of m` (JS's container iterators are live
+ * views, not snapshots), just yielding the key, the value, or the pair. */
+export type ForOfIterProjection = "keys" | "values" | "entries";
+/** for-of over a URLSearchParams (and its keys()/values()/entries()
+   * projections consumed directly by the head): the LIVE index walk —
+   * sp.size re-reads every pass, so entries appended mid-walk are visited
+   * and deletes shift, the spec's index-based iterator exactly. No
+   * enter/exit bracketing: the pair list compacts immediately (no
+   * tombstones), so there is no iteration depth to keep exact. */
+export declare function lowerForOfSearchParams(L: Lowerer, stmt: ts.ForOfStatement, iterable: IrExpr, proj?: ForOfIterProjection): IrStmt;
+export declare function lowerForOfMap(L: Lowerer, stmt: ts.ForOfStatement, iterable: IrExpr, mapT: IrType & {
+    kind: "map";
+}, proj?: ForOfIterProjection): IrStmt;
+/** `for (const v of s)` — for-of over a Set: the Map desugar with iterKey
+   * as the (single) element read; same live-iteration contract. */
+export declare function lowerForOfSet(L: Lowerer, stmt: ts.ForOfStatement, iterable: IrExpr, setT: IrType & {
+    kind: "set";
+}, proj?: ForOfIterProjection): IrStmt;
+/** `new Map(entries)` from a tuple-array VALUE — any `[K, V][]`-typed
+   * expression (a variable, a .map() result, a sorted entries spread), not
+   * just the pair-literal form lower-classes handles inline. Desugars to a
+   * direct call of a synthetic function that constructs the empty map and
+   * set()s each pair in array order — JS-exact: pairs are visited in
+   * insertion order and a later duplicate key overwrites while keeping the
+   * first occurrence's position (set()'s own contract). Null when the
+   * argument isn't a matching tuple array (the caller keeps its fence). */
+export declare function lowerMapSeedArrayNew(L: Lowerer, argNode: ts.Expression, mapT: IrType & {
+    kind: "map";
+}): IrExpr | null;
+/** Regex method calls, both directions: `re.test(s)` on a regex receiver,
+   * and `s.replace(re, tpl)` / `s.replaceAll(re, tpl)` / `s.split(re)` on a
+   * string receiver whose FIRST ARGUMENT is a regex (the string-pattern
+   * overloads keep their island lowering — the argument's mapped type is
+   * what routes here, before lowerIslandMethodCall can claim the name).
+   * Null when neither shape matches. */
+export declare function lowerRegexMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, dynReceiver?: () => IrExpr): IrExpr | null;
+/** `s.slice(1, 4)` and friends → strIntrinsic. Null when this isn't an
+   * ambient string method call (caller keeps its generic rejection). Missing
+   * optional arguments are omitted from `args` — the backend fills the
+   * documented defaults; the IR never encodes them (Infinity isn't
+   * JSON-safe). tsc has already checked arity and argument types against
+   * ambient/scriptc.d.ts. */
+export declare function lowerStringMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, dynReceiver?: () => IrExpr): IrExpr | null;
+/** `new Uint8Array(...)` / `new Uint32Array(...)` / `new Float32Array(...)`
+   * (stdlib provenance — a user's own class with the name resolves through
+   * classBySymbol). Lowered argument shapes: none (empty), a length
+   * (zero-filled; ToIndex at runtime — invalid lengths throw Node's
+   * RangeError), a same-kind typed array or Buffer (an independent COPY —
+   * the readFile chain's `new Uint8Array(await readFile(p))`), a number[]
+   * literal (element-coerced; its contextual type is the lib's
+   * ArrayLike/Iterable union, which cannot map — the Set-seed pattern), or
+   * a number[]-typed value. ArrayBuffer/view forms are fenced: scriptc
+   * typed arrays own their storage. Null when this isn't a stdlib
+   * typed-array construction. */
+export declare function lowerBytesNew(L: Lowerer, expr: ts.NewExpression, symbol: ts.Symbol | null | undefined): IrExpr | null;
+/** Method calls on typed-array/Buffer receivers: slice and subarray (BOTH
+   * copy — subarray's sharing is the documented divergence), set(src,
+   * offset?), and the u8-only Buffer surface: toString(enc?) plus the
+   * whole numeric read/write family (fixed widths BE/LE and the
+   * variable-width read/writeUIntLE quartet — BUF_NUM_METHODS). Everything
+   * else the lib declares (fill, indexOf, reverse, ...) falls through to
+   * the SC2020 member fence. Null when this isn't a bytes method call. */
+export declare function lowerBytesMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The literal encoding argument of a Buffer surface, normalized — or a
+ * fence when it isn't a literal alias Node knows. */
+export declare function bufEncoding(L: Lowerer, what: string, encNode: ts.Expression): string;
+/** The Buffer statics — `Buffer.from(...)`, `Buffer.alloc(n)`,
+   * `Buffer.concat(list)`, `Buffer.isBuffer(x)` — on THE stdlib Buffer
+   * global (name + provenance; fallback and @types/node alike). Null when
+   * the callee isn't a Buffer-static access. */
+export declare function lowerBufferStaticCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `Object.keys/values/entries` over an INDEX-SIGNATURE (overflow-carrying)
+   * record shape: declared fields answer first from the compile-time field
+   * list (declaration order, undefined-valued fields skipped — exactly the
+   * fixed-shape lowering and SEMANTICS.md 37), then the overflow map's live
+   * keys in JS OWN-KEY order (canonical array indices ascending, then
+   * insertion order — recordOvfKeys). For a PURE index-signature shape
+   * (Record<string, T> — no declared fields, the typical CLI config patterns) the
+   * result order is Node-exact; hybrids inherit the documented
+   * declared-then-overflow divergence. Values surface as the checker's
+   * result element type: identity, an arm-into-union wrap, or (dyn
+   * results) the DOM conversion — recordKeyGet's own surfacing rules for
+   * the overflow, mirrored statically for declared fields. */
+export declare function lowerObjectIterOverIndexShape(L: Lowerer, call: ts.CallExpression, member: "keys" | "values" | "entries", argIr: IrType & {
+    kind: "record";
+}, shape: IrRecordShape): IrExpr;
+/** The construction core, receiver/result pre-resolved — `node` anchors
+ * the fences. for-in reuses the "keys" arm directly (it iterates exactly
+ * the keys Object.keys answers; same intern key, one helper). */
+export declare function objectIterOverIndexShape(L: Lowerer, node: ts.Node, member: "keys" | "values" | "entries", argIr: IrType & {
+    kind: "record";
+}, shape: IrRecordShape, receiver: IrExpr, resultT: IrType & {
+    kind: "array";
+}, loc: SrcLoc): IrExpr;
+/** `Object.fromEntries(pairs)` over a `[string, V][]` VALUE into the
+   * checker's own index-signature result shape (`{ [k: string]: V }` —
+   * always declared-field-free from the lib signature): an interned helper
+   * loops the pairs and keyed-writes each into a fresh record's overflow —
+   * later duplicates overwrite in place (first insertion position wins for
+   * ORDER, last value wins — exactly JS). Values flow into the signature's
+   * value slot (dyn slots convert JSON-safe values, identity otherwise).
+   * The `as ModelPricing` reshape AFTER it is the width-coercion capture
+   * (lowerRecordOvfCaptureHelper). Null when the argument or result shape
+   * is outside this (Maps, richer iterables → the SC2020 fence). */
+export declare function lowerObjectFromEntriesCall(L: Lowerer, call: ts.CallExpression, callee: ts.Expression): IrExpr | null;
+/** Interned `%rec.capture.<n>(s)` — the INDEX-SIGNATURE reshape behind
+   * `Object.fromEntries(entries) as ModelPricing` (hybrid→hybrid width
+   * coercion) and `const r: Record<string, number> = { a: 1, b: 2 }`
+   * (a DECLARED-fields shape narrowing into a pure overflow shape — the
+   * record becomes width-free key/value storage), both called from
+   * widthCoerce after recordWidthHelper declines: builds the target shape
+   * fresh — declared fields default to their undefined arms — then
+   * keyed-writes every source key into it, declared fields first in the
+   * source's DECLARATION order (skipping ones holding the undefined arm,
+   * the unset convention — insertion order is what Object.keys/JSON
+   * answer, stance 37), then the source overflow in JS own-key order. A
+   * key colliding with a target DECLARED field validates through the
+   * keyed write's dynCheck (a mismatch throws the catchable TypeError —
+   * divergence 34), which is exactly what makes the `as` honest. The
+   * result is a COPY (divergence 36's stance). Null when the pair is
+   * outside the supported matrix: the target needs an index signature,
+   * every source value (declared fields, and the overflow slot when the
+   * source carries one) must enter the target's value slot (identity, a
+   * width lift — arm wrap/re-tag/nested reshape, or JSON-safe into a dyn
+   * slot), and every target field must be optional-flavored (the fresh
+   * record's default) and writable at runtime. */
+export declare function lowerRecordOvfCaptureHelper(L: Lowerer, fromId: string, toId: string, loc: SrcLoc): string | null;
+/** `Object.assign(target, ...sources)` into an INDEX-SIGNATURE record:
+   * the capture helper's keyed-write walk aimed at the EXISTING target —
+   * each source's declared fields write in declaration order (unset
+   * optionals skip, stance 37), then its overflow in JS own-key order,
+   * and the result IS the target (identity, like JS — later reads through
+   * the target see every merged key). One interned `%obj.assign.<n>(t, s)`
+   * per (target shape, source shape) pair; multiple sources chain. Null
+   * when outside the matrix: the target needs an index signature, every
+   * source value must enter its value slot (identity, a width lift, or
+   * the dyn conversion), and tsc's `T & U` result type must collapse back
+   * to the target's own record shape (the self-shaped merges init-config
+   * patterns spell). */
+export declare function lowerObjectAssignIndexShape(L: Lowerer, call: ts.CallExpression): IrExpr | null;
+/** One contributor of a pure-index-record MERGE literal: a full spread of
+ * an index-signature record, or one explicit key. */
+export type IndexMergeContributor = {
+    kind: "spread";
+    shapeId: string;
+    value: IrExpr;
+} | {
+    kind: "field";
+    name: string;
+    value: IrExpr;
+}
+/** A RUNTIME-keyed property (`{ ...m, ["a" + "b"]: v }`, `{ [K]: v }`
+ * over a runtime string K): the key is its own helper argument, passed
+ * immediately BEFORE its value (JS's per-property key-then-value order
+ * rides the call's argument evaluation), already stringified by the
+ * caller (ToPropertyKey). */
+ | {
+    kind: "keyedField";
+    key: IrExpr;
+    value: IrExpr;
+}
+/** `...(cond ? { k: v } : {})` at its literal position: the key writes
+ * ONLY when the value isn't the undefined arm (overflow entries model
+ * presence — an absent key stays absent, exactly JS's empty-arm spread).
+ * The caller builds `value` as `cond ? v : <interned undefined arm of
+ * the target's value slot>` — cond evaluates once, `v` lazily — so the
+ * target's index-value type must carry an undefined arm. The explicit
+ * `{ k: undefined }` true-arm collapses to absence, divergence 56's
+ * documented stance. */
+ | {
+    kind: "condField";
+    name: string;
+    value: IrExpr;
+};
+/** The interned merge helper behind `{ ...a, ...b, K: v }` literals whose
+   * TARGET shape is a PURE index-signature record (no declared fields) —
+   * the spawn-env pattern (`{ ...process.env, ...extraEnv }`). Contributors
+   * apply in literal order with keyed writes, so JS's last-write-wins holds
+   * for colliding runtime keys. Spread sources must be index-signature
+   * records whose value slot IS the target's or LIFTS into it (a
+   * `Record<string, string>` spreads into a `string | undefined` target by
+   * wrapping each copied value); their declared fields copy first (skipping
+   * undefined-armed absents — the unset convention), then their overflow in
+   * JS own-key order. Explicit values arrive pre-coerced to the target's
+   * value slot. Null when a spread source is outside that matrix (the
+   * caller keeps its fence). */
+export declare function lowerIndexMergeHelper(L: Lowerer, toId: string, contributors: IndexMergeContributor[], loc: SrcLoc): string | null;
+/** The interned helper flattening an env-shaped record into the
+   * [k0, v0, k1, v1, ...] string[] cp.execSync consumes — declared string
+   * fields first (undefined-armed absents skipped, the Node-drops-undefined
+   * rule), then index-signature overflow in JS own-key order. Every value
+   * source must be a string or a `string | undefined` union whose value arm
+   * is a string. Null when the shape carries a non-string field/value slot
+   * (the caller fences). */
+export declare function lowerEnvToPairsHelper(L: Lowerer, shapeId: string, loc: SrcLoc): string | null;
+/** The validated-STRING extraction of a dyn method receiver — the receiver
+ * expression the string/regex method lowerings consume. */
+export declare function dynStringReceiver(L: Lowerer, recv: IrExpr, access: ts.PropertyAccessExpression): IrExpr;
+/** `d.filter(pred)` on a dyn receiver: the receiver must BE a DOM array
+ * (else the Node-shaped TypeError above); the predicate runs per element
+ * over the DOM value, and each SURVIVOR is validated-extracted into the
+ * result's element type T — the type the checker already committed the
+ * call to (the contextual `RouteMapping[]`/`string[]` slot). Extraction is
+ * the checked-cast machinery: a survivor that doesn't fit T throws the
+ * catchable TypeError instead of misreading (a LYING predicate is the only
+ * way there). The result is a fresh STATIC array of extracted copies —
+ * the dyn boundary's marshal-copy stance (SEMANTICS.md). Null when the
+ * call shape isn't claimable (the method-call fence stays). */
+export declare function lowerDynArrayFilterCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, recv: IrExpr): IrExpr | null;
+/** `.flatMap(f)` on a dyn ('unknown'/`any[]`-narrowed) receiver where the
+   * callback returns a STATIC array (`parsed.flatMap((v) => typeof v ===
+   * "string" ? parseTldList(v) : [])` — the tlds-file shape): the DOM
+   * array walks element-by-element, the callback sees each element as the
+   * DOM value `unknown` code sees, and its typed results concatenate —
+   * depth-1 flatten by construction, no validation needed on the results
+   * (they are already typed; only the RECEIVER is dynamic). Non-array
+   * receivers throw the Node-shaped TypeError. Callbacks returning
+   * NON-array values (JS would keep them as single elements) or dynamic
+   * results keep the fence — nothing drives them yet. */
+export declare function lowerDynArrayFlatMapCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, recv: IrExpr): IrExpr | null;