Train pi 1: lowering fixes on pi's path (generic identity, Proxy slots, shell arguments, stdin as a stream, dictionaries and unions)

docs/content/docs/limitations.mdx

@@ -146,6 +146,8 @@ title: "Limitations"
 
 <include>../limitations/builtin-apis/object-freezing.mdx</include>
 
+<include>../limitations/builtin-apis/proxy.mdx</include>
+
 ### Builtin function values
 
 <include>../limitations/builtin-function-values.mdx</include>

docs/content/limitations/builtin-apis/proxy.mdx

@@ -0,0 +1,12 @@
+- **Proxy:** `new Proxy(target, handler)` builds a Proxy for untyped code and for the binding it initializes: reads, writes, `in`, and key listing through that binding go through the handler's traps.
+  A Proxy cannot stand in for a class instance.
+  A binding, field, parameter, return value, or array element typed as a class holds native instances only, so a Proxy that the build sees entering one, or asserted to the class, is refused at compile time with `SC1090`.
+  For a value that forwards to the current instance, export a binding that is reassigned or a function that returns the instance.
+  A Proxy passed, returned, stored in a field, or asserted where an interface or object type is expected is refused at compile time with `SC1090`, because that slot would hold a copy of the properties, read through the traps once.
+  A Proxy whose handler is the empty object literal is converted there as its target is.
+  A Proxy that reaches a typed slot through a parameter or property typed `any` is converted when the statement runs: a class slot throws a `TypeError`, and an interface or object type takes the copy.
+  A class method that a trap returns is called with the Proxy as `this` and throws a `TypeError`; return the method bound to the instance.
+  The handler is an untyped object when each trap declares its parameters and result as `any`; a handler whose traps take their types from `ProxyHandler<T>` is refused at compile time with `SC1090`.
+  A target that is a class instance or an array is refused at compile time with `SC1090`.
+  A target written as an asserted object literal, such as `{} as Config`, is an untyped object.
+  Traps over a target that is a typed record throw an `Error` when the Proxy is used.

docs/content/limitations/console-and-process-streams.mdx

@@ -46,3 +46,16 @@ The record is a separate value: it is not identical to the stream, and it expose
 A record type that also declares a data member, such as `isTTY`, throws `SC2002`.
 An instance of a stream class such as `Writable` throws `SC2002` in a record type of methods as well.
 For those, pass an object literal that wraps the stream: `const sink: Sink = { write: (text: string) => { process.stdout.write(text); } }`.
+Under `@types/node`, `process.stdin` passed, stored or returned where `stream.Readable` is declared is one `Readable` over the process's input, and `process.stdout` and `process.stderr` where `stream.Writable` is declared are one `Writable` each.
+Every conversion answers the same stream, and a binding of the stream class compares identical to the process stream it was read from.
+The stdin stream receives each chunk once, beside any listener registered on `process.stdin` itself, and ends when the input ends.
+Listeners registered on `process.stdin` and listeners registered on the stream are kept separately, so for one event their relative order can differ from Node's registration order.
+For the same reason `process.stdin.isPaused()` does not report a `pause()` of the stream, and `listenerCount` does not include the listeners Node itself attaches to a pipe or a terminal.
+A process stream held as an untyped value does not convert to a stream class: asserting or passing it as `Readable` or `Writable` throws a TypeError.
+Passing `process.stdin` where `Duplex` or `EventEmitter` is declared throws the same TypeError.
+The bundled declarations declare `process.stdin` by its own members, so these conversions need `@types/node`.
+After `process.stdin.setEncoding`, a `'data'` listener registered on `process.stdin` whose parameter is declared `string` receives the decoded chunks, with a multi-byte sequence split across reads kept whole.
+A listener whose parameter is a `Buffer` or `Uint8Array`, which includes a parameter with no annotation, throws a TypeError with code `SC2020` at the first chunk, because Node delivers a string there.
+`process.stdin.read()` and `for await` over `process.stdin` answer bytes, so after `setEncoding` they throw the same kind of TypeError at the first chunk they would hand out, where Node answers a string.
+A `read()` that hands out no chunk (`read(0)`, or a `read()` with nothing held) answers `null` and an iteration that gets no input ends, as in Node.
+To read text that way, leave the encoding unset and decode the Buffers with a `TextDecoder`.

docs/content/limitations/language-features/generics.mdx

@@ -1,4 +1,6 @@
-- **Generics:** Generic functions declared inside other functions, generic class expressions, and generic methods requiring dynamic dispatch are unsupported.
+- **Generics:** A generic `function` declared inside another function compiles when the enclosing function only calls it: captured values travel as the instance's parameters, or through a shared closure environment when one of them is reassigned.
+  Taking such a declaration as a value, or capturing a value whose type is the enclosing function's own type parameter, remains unsupported.
+  Generic class expressions and generic methods requiring dynamic dispatch are unsupported.
   Generic classes can extend generic bases when each specialization has a concrete layout.
   Independent concrete uses have no specialization-count limit; recursively expanding demands and type layouts produce diagnostics.
   Other generic calls compile when the target resolves statically.

docs/content/limitations/record-identity-and-property-order.mdx

@@ -10,10 +10,17 @@ Assigning an existing value to a binding that keeps its initializer's layout, to
 The refusal covers a short-circuit assignment that stores the value (`&&=`, or `??=` on a binding that can be nullish) like the plain assignment it stands for.
 A member of another binding that kept its initializer's layout carries that layout into the store, so no refusal is reported when the two layouts already match.
 Bracket writes such as `alias["k"] = v` write the field in the kept layout, like their dotted spelling.
+The members of a union type that share one value of its discriminant property, such as two `{ type: "retry" }` members with different other properties, are stored as one record that has the properties of all of them, and a value of one of those member types is that record: it keeps its identity when it is stored in the union, narrowed, or passed as the member type.
+A value whose type is not one of those members but has the properties of one, such as an object held in a binding whose type was inferred, would be copied into that record, so `scriptc build` reports `SC1090` for it; declaring the value with the union's type or the member's type compiles.
+Reading a property that one of those members requires, from a value that an assertion claimed to be that member and that lacks the property, throws a `TypeError` where Node.js answers `undefined`.
 
 Typed records with declared fields, indexed records, and arrays retain identity and mutations through native checked storage.
 A record or class instance converted to a string-keyed dictionary type such as `Record<string, string>`, directly, through a `{}`, `object` or `unknown` binding or parameter, or as an element of a constant `unknown[]` array that holds such records, keeps its identity when the program writes through, compares or inspects values of that dictionary type.
 Every dictionary type with the same value type then uses checked dynamic storage, which is slower than a native dictionary.
+The value type is compared by structure, so a dictionary type is the same type whether it is written inline, through an alias, as a generic instantiation, as `Record<string, V>`, under `Readonly`, in another module or in a declaration file; a `readonly` modifier does not make another type, and arrays, tuples and class instances are the same only as instantiations of one type with the same type arguments.
+A dictionary that keeps its identity is copied where it is converted to a dictionary type with another value type, such as a `Record<string, number>` stored as a `Record<string, number | string>`, and `SC6001` reports the conversion where the copy is then written or compared.
+A union type that refers to itself and holds such a dictionary, such as a JSON value type `string | number | Json[] | { [key: string]: Json }`, uses checked dynamic storage as a whole.
+`scriptc build` reports `SC2009` for such a union when another of its members, such as a `Map`, cannot be held in checked dynamic storage.
 Class instances retain identity at their exact type or a base class, and at any interface or object type that a class instance is passed, stored, returned, or asserted as when the program could tell a copy from the instance: values of such a type are checked views of the original object, so writes, identity comparisons, Set and Map keys, `util.inspect`, and `JSON.stringify` through them reach the instance, as in Node.js.
 These types use checked dynamic storage, which is slower than native record fields, for all of their values, including plain objects.
 A type whose values are only read field by field, from fields the class does not write after construction and does not implement as accessors, stays a native record and holds a copy.

docs/content/limitations/runtime-type-checks.mdx

@@ -50,6 +50,13 @@ Reading a value that does not match the dictionary's value type throws a `TypeEr
 Casts between program classes are checked too: casting an instance to a class it does not extend throws a `TypeError`, where Node.js reads the members structurally.
 `SC6004` reports calls that pass such an instance to a function that casts it.
 
+An object whose methods are typed by a generic interface can be stored as another instantiation of that interface, such as a `Provider<"a" | "b">` listed in a `Provider<Api>[]`.
+Each such method then checks its arguments against its own parameter types when it is called.
+An argument that holds a union member the parameter type does not include throws a `TypeError`, where Node.js passes the object through.
+When that member is an object type with only optional properties, the argument is read as the member of the parameter type that declares the properties the object has, as in Node.js.
+It throws a `TypeError` only when no single member declares all of them.
+The method receives a copy of an argument record whose type differs between the two instantiations, so a write to that argument in the method does not reach the caller's object, and `SC6001` does not report it.
+
 A Promise converted from `unknown` to a typed result validates its fulfilled value.
 A mismatch rejects with a `TypeError`.
 Rejection reasons and reference equality are preserved across conversions.

internal/compatibility/generated/node-v24-internal.json

@@ -52860,6 +52860,7 @@
           "tests/corpus/fetch-headers-copy-cache.ts",
           "tests/corpus/fetch-headers-set-cookie-iteration.ts",
           "tests/corpus/headers-static-accessors.ts",
+          "tests/corpus/headers-typed-iteration.ts",
           "tests/corpus/js-abort-portable.js",
           "tests/corpus/node24-url-factories.ts",
           "tests/corpus/node24-url-mutation.ts",
@@ -53607,6 +53608,7 @@
           "tests/corpus/fetch-headers-copy-cache.ts",
           "tests/corpus/fetch-headers-set-cookie-iteration.ts",
           "tests/corpus/headers-static-accessors.ts",
+          "tests/corpus/headers-typed-iteration.ts",
           "tests/corpus/7735-untyped-headers-iterators.js"
         ]
       },

internal/compatibility/static-support.json

@@ -379,7 +379,7 @@
     { "chapter": "globals", "symbols": ["URL", "URLSearchParams"], "status": "partial", "evidence": ["tests/corpus/1355-url-parse.ts", "tests/corpus/1791-searchparams-core.ts", "tests/corpus/1792-searchparams-encoding.ts", "tests/corpus/1793-searchparams-iteration.ts", "tests/corpus/1794-searchparams-url-live.ts", "tests/corpus/node24-url-mutation.ts", "tests/corpus/node24-url-factories.ts"] },
     { "chapter": "globals", "symbols": ["structuredClone"], "status": "partial", "evidence": ["tests/corpus/2283-structured-clone.cjs", "tests/corpus/5324-structured-clone-documents.ts"] },
     { "chapter": "globals", "signatures": ["Class: `TextEncoder`", "Class: `TextDecoder`"], "status": "partial", "evidence": ["tests/corpus/1423-text-codec.ts", "tests/corpus/text-codec-values/main.ts", "tests/corpus/3133-text-decoder-streaming.ts", "tests/corpus/7747-text-codec-untyped-slot.js"] },
-    { "chapter": "globals", "signatures": ["Class: `Headers`"], "status": "partial", "evidence": ["tests/corpus/fetch-headers-copy-cache.ts", "tests/corpus/fetch-headers-set-cookie-iteration.ts", "tests/corpus/headers-static-accessors.ts", "tests/corpus/7735-untyped-headers-iterators.js"] },
+    { "chapter": "globals", "signatures": ["Class: `Headers`"], "status": "partial", "evidence": ["tests/corpus/fetch-headers-copy-cache.ts", "tests/corpus/fetch-headers-set-cookie-iteration.ts", "tests/corpus/headers-static-accessors.ts", "tests/corpus/headers-typed-iteration.ts", "tests/corpus/7735-untyped-headers-iterators.js"] },
     { "chapter": "globals", "signatures": ["Class: `Blob`", "Class: `File`"], "status": "partial", "evidence": ["tests/corpus/5285-blob-construct.ts", "tests/corpus/5286-blob-readers.ts", "tests/corpus/5287-blob-inspect.ts", "tests/corpus/5288-blob-validation.js", "tests/corpus/5290-blob-dynamic.js"] },
     { "chapter": "buffer", "signatures": ["Class: `Blob`", "Class: `File`"], "status": "partial", "evidence": ["tests/corpus/5285-blob-construct.ts", "tests/corpus/5288-blob-validation.js", "tests/fixtures/node-types/blob-file.ts"] },
     { "chapter": "buffer", "signatures": ["`blob.arrayBuffer()`", "`blob.bytes()`", "`blob.text()`", "`blob.slice([start[, end[, type]]])`", "`blob.size`", "`type` Type: {string}", "`name` Type: {string}", "`lastModified` Type: {number}"], "status": "supported", "evidence": ["tests/corpus/5285-blob-construct.ts", "tests/corpus/5286-blob-readers.ts", "tests/corpus/5288-blob-validation.js", "tests/corpus/5289-blob-read-order.ts", "tests/corpus/5290-blob-dynamic.js", "tests/fixtures/node-types/blob-file.ts"] },

packages/compiler/ambient/node-fallback/child_process.d.ts

@@ -42,10 +42,10 @@ declare module "child_process" {
    * pipes an empty stdin), shell (the complete command line in
    * `command`, with a statically empty args list, run by /bin/sh -c),
    * and windowsHide (a POSIX no-op).
-   * The shell form takes no separate args: Node warns DEP0190 because it
-   * concatenates them unescaped, and a native build has no warning
-   * channel, so the compiler REFUSES `shell: true` with a non-empty args
-   * list. */
+   * The shell form joins a non-empty args list onto the command, as Node
+   * does: the arguments are concatenated unescaped, never quoted, and
+   * the first such call of a process reports the DEP0190 warning on
+   * stderr. */
   export interface SpawnSyncOptions {
     encoding?: "utf8" | "utf-8";
     timeout?: number;
@@ -61,8 +61,8 @@ declare module "child_process" {
     /* Node's shell form: the complete command line in `command`, with
      * an empty args list, runs through /bin/sh -c, so quoting and
      * operators follow the shell's rules. A non-empty args list with
-     * shell: true is a compile error (Node warns DEP0190 for unescaped
-     * shell arguments). */
+     * shell: true joins onto the command unescaped, and Node's DEP0190
+     * warning is shown. */
     shell?: boolean;
   }
   export function spawnSync(
@@ -92,9 +92,9 @@ declare module "child_process" {
     stdio?: "pipe" | "ignore" | "inherit" | ("pipe" | "ignore" | "inherit")[];
     timeout?: number;
     windowsHide?: boolean;
-    /* Read at the call. The call then takes the command-line form only:
-     * a statically non-empty args list is a compile error (Node warns
-     * DEP0190 for unescaped shell arguments). */
+    /* Read at the call. When it is on, a non-empty args list joins onto
+     * the command unescaped and Node's DEP0190 warning is issued; when
+     * off, the list is the arguments passed. */
     shell?: boolean;
   }
 
@@ -202,9 +202,10 @@ declare module "child_process" {
     /* detached gives the child its own session and process group
      * (POSIX_SPAWN_SETSID); env REPLACES the child environment; cwd
      * sets its working directory; windowsHide is a POSIX no-op; shell
-     * runs the complete command string through /bin/sh or cmd.exe (with
-     * an empty args list — a non-empty one is a compile error, because
-     * Node warns DEP0190 for unescaped shell arguments). */
+     * (a literal or a boolean decided at run time) runs the command line
+     * through /bin/sh or cmd.exe. A non-empty args list joins onto the
+     * command unescaped where the shell is on, and Node's DEP0190 warning
+     * is reported for the first such call. */
     detached?: boolean;
     env?: { [k: string]: string | undefined };
     cwd?: string;

packages/compiler/ambient/scriptc-node-fallback.d.ts

@@ -373,8 +373,10 @@ declare var process: {
    * resume, isPaused, read, readableLength), destroy() (full teardown:
    * nothing fires after, the loop stops waiting), and async iteration
    * (`for await (const chunk of process.stdin)` — chunks are Uint8Array
-   * values, ending at EOF). setEncoding has no lowering (chunks stay
-   * bytes; decode with TextDecoder). */
+   * values, ending at EOF). setEncoding decodes the chunks a 'data'
+   * listener with a string parameter receives. read() and async iteration
+   * answer bytes, so once an encoding is set they throw (Node answers
+   * strings there): leave the encoding unset and decode with TextDecoder. */
   stdin: {
     readonly isTTY: boolean;
     /* The descriptor the stream is built over (Node reports 0 here and
@@ -384,6 +386,11 @@ declare var process: {
      * undefined on a non-TTY stdin (the `x || false` idiom). */
     readonly isRaw: boolean;
     on(event: "data", listener: (chunk: Uint8Array) => void): void;
+    /* After setEncoding the chunks are strings: a listener that declares
+     * its parameter string receives the decoded text. A listener compiled
+     * for bytes (the overload above, which an unannotated parameter takes)
+     * throws at the first chunk once an encoding is set. */
+    on(event: "data", listener: (chunk: string) => void): void;
     on(event: "end", listener: () => void): void;
     on(event: "error", listener: (err: Error) => void): void;
     /* Paused mode, as in Node: input stays buffered for read(), and the
@@ -396,6 +403,7 @@ declare var process: {
       listener: (str: string | undefined, key: import("readline").Key) => void,
     ): void;
     once(event: "data", listener: (chunk: Uint8Array) => void): void;
+    once(event: "data", listener: (chunk: string) => void): void;
     once(event: "end", listener: () => void): void;
     once(event: "error", listener: (err: Error) => void): void;
     once(event: "readable", listener: () => void): void;
@@ -1389,6 +1397,9 @@ interface Headers {
     callbackfn: (value: string, key: string, parent: Headers) => void,
     thisArg?: unknown,
   ): void;
+  entries(): IterableIterator<[string, string]>;
+  keys(): IterableIterator<string>;
+  values(): IterableIterator<string>;
   [Symbol.iterator](): IterableIterator<[string, string]>;
 }
 declare var Headers: {

packages/compiler/src/backend/executable-features.ts

@@ -67,8 +67,10 @@ export function executableLinkFeatures(
     ...(features.promiseGeneric ? { promiseGeneric: true } : {}),
     ...(features.dynTier ? { dynTier: true } : {}),
     ...(features.streamDyn ? { streamDyn: true } : {}),
+    ...(features.streamStdin ? { streamStdin: true } : {}),
     ...(features.handleProps ? { handleProps: true } : {}),
     ...(features.childLifecycle ? { childLifecycle: true } : {}),
+    ...(features.childShellLine ? { childShellLine: true } : {}),
     ...(features.childOptionExt ? { childOptionExt: true } : {}),
     ...(features.spawnCaptureBytes ? { spawnCaptureBytes: true } : {}),
     ...(features.childErrorFields ? { childErrorFields: true } : {}),