@amritk/nish 0.13.0 → 0.14.0

package/README.md

@@ -306,6 +306,8 @@ nish run [options] <file.ts> [args ...]
                              language spawns a thread yet)
   --no-warn-performance      do not report the `performance` diagnostics (they are on by default,
                              print on stderr, and never change the exit code)
+  --warn-portability         report the `portability` diagnostics: where the program's TypeScript
+                             reading answers differently (off by default; never changes the exit code)
   -g                         emit DWARF debug info (!dbg locations, variables); kept by --link
   --json                     print diagnostics as one JSON object per line on stdout (no excerpt)
   --emit-ast                 print the syntax tree of every module to stdout instead of IR

package/docs/AI.md

@@ -46,16 +46,18 @@ stdout, nothing on stderr, every field 1-based with `endLine`/`endColumn`
 exclusive:
 
 ```json
-{"file":"p.ts","line":3,"column":17,"endLine":3,"endColumn":20,"severity":"error","code":"NL2249","message":"Unknown method `map` on i32[] (supported: push, pop, indexOf, join)"}
+{"file":"p.ts","line":3,"column":17,"endLine":3,"endColumn":20,"severity":"error","code":"NL2249","message":"Unknown method `map` on i32[] (supported: push, pop, indexOf, join, set, fill)"}
 ```
 
 - **Key on `code`, never on `message`.** A code is a promise: `NL2249` means
   the same rule next release. The prose may improve; the code may not.
-- **`severity`** is `"error"` or `"performance"`. A performance warning never
-  changes the exit code — it is advice, not a rejection.
+- **`severity`** is `"error"`, `"performance"` or `"portability"`. A warning
+  of either kind never changes the exit code — it is advice, not a rejection.
+  Portability warnings, the sites where the program's TypeScript reading
+  answers differently, print only under `--warn-portability`.
 - **Bands**: `NL1xxx` the Phase 0 forbidden-syntax sweep, `NL2xxx` the checker,
-  `NL3xxx` the driver and modules, `NL4xxx` the interop sidecars, `NL9xxx`
-  performance, `NL0001` syntax, `NL0002` toolchain, `NL0003` internal,
+  `NL3xxx` the driver and modules, `NL4xxx` the interop sidecars, `NL8xxx`
+  portability, `NL9xxx` performance, `NL0001` syntax, `NL0002` toolchain, `NL0003` internal,
   `NL0000` a diagnostic with no rule yet.
 - **Exit codes**: `0` ok, `1` the program was rejected, `2` usage, `3` the C
   toolchain is unusable, `70` an internal compiler error — that last one is a
@@ -114,31 +116,39 @@ rejects. This table is the highest-value part of the page.
 | `x == y` | `Loose equality is forbidden` | `x === y` |
 | `throw new Error(m)` | `` `throw` is forbidden `` | `return Err(m)`, or `panic(m)` to end the process |
 | `try { … } catch { … }` | `` `try`/`catch`/`finally` is forbidden `` | `Result<T, E>` and `isErr()` |
-| `xs.map(f)`, `.filter`, `.reduce`, `.forEach`, `.slice`, `.sort`, `.shift` | `` Unknown method `map` on i32[] (supported: push, pop, indexOf, join) `` | a `for` loop, or a top-level `map(xs, f)` with a [function parameter](#function-parameters) |
+| `xs.map(f)`, `.filter`, `.reduce`, `.forEach`, `.slice`, `.sort`, `.shift` | `` Unknown method `map` on i32[] (supported: push, pop, indexOf, join, set, fill) `` | a `for` loop, or a top-level `map(xs, f)` with a [function parameter](#function-parameters) |
 | `s.toUpperCase()`, `s.split()`, `s.trim()`, `s.replace()` | `` Unknown method … on string `` | index bytes with `charCodeAt` / `substring` |
 | `a?.b`, `a ?? b` | forbidden, except `m.get(k) ?? d` | `if (a !== null)` first |
-| `x as T`, `<T>x`, `x!` | `Unsupported expression in Phase 1: AsExpression` | there are no casts; `implements` is the only widening |
+| `x as T`, `<T>x`, `x satisfies T` | `Unsupported expression in Phase 1: AsExpression` (to `any` or `unknown`: `` Type assertion to `any` is forbidden ``); `x!` is a syntax error | there are no casts; `implements` is the only widening |
+| `typeof x`, `x instanceof C`, `"k" in o`, `delete o.k`, `void 0`, `a, b` | each refused by name (`` `typeof` is forbidden ``, …) | there is no runtime type information: a value's type is its declared one |
+| `a ** b`, `[...xs]`, `[1, , 2]` | `` Unsupported binary operator `**` `` / `Spread in array literals is not supported` / `Holes in array literals are not supported` | `Math.pow` on `f64`, a loop, every element written out |
 | `any`, `unknown` | forbidden | name the real type |
 | `undefined` | forbidden, except `x === undefined` on a `Map.get` result | `null`, with a `T \| null` type |
 | `let total = 0` at the top level | `` Top-level `let` is not supported `` | a module `const`, or a local |
+| `for (const k in o)` | `` `for...in` is forbidden `` | `for (const x of xs)` over an array, or `for (const k of m.keys())` over a `Map` |
 | a callback stored or returned: `const cb = (n: i32) => n`, a field `cb: (n: i32) => i32` | `An arrow may only be written as the argument for a function-typed parameter` / `` … is a function type, which may only annotate a parameter of a top-level function `` | there are **no function values**; a callback the call names is a [function parameter](#function-parameters) |
-| `type Pair<T>` (a generic alias) | `` expected `=`, found `<` `` (a syntax error) | a generic **function**, **class**, **interface** and **method** all work — see below; an alias renames a type that already exists, so it has nothing to specialise |
+| `type Pair<T>` (a generic alias) | `Generic type parameters are forbidden on a type alias` | a generic **function**, **class**, **interface** and **method** all work — see below; an alias renames a type that already exists, so it has nothing to specialise |
 | `constructor<T>(x: T)` | a syntax error: `a constructor cannot have type parameters` | put the parameter on the class (`class Box<T>`), or on a method |
 | `h.get<i32>(7)` (type argument at a method call) | `Type arguments are not written at a call site in Nish` | `h.get(7)` — a generic method infers like a generic function |
 | `<T>(p: T) => p.x` (a member of a type parameter) | `` Cannot read `x` of `T`: an unconstrained type parameter has no members `` | `<T extends Point>(p: T) => p.x`, where `Point` is a class or interface that declares `x` |
 | `identity<i32>(7)` (type argument at a call) | `Type arguments are not written at a call site in Nish` | `identity(7)` — `T` is inferred from the arguments |
 | `async` / `await` / `Promise` | forbidden (no event loop) | the I/O builtins are synchronous |
+| `namespace N { }`, `declare global { }`, `@decorator` | forbidden | one module per file; a plain function in place of a decorator |
+| `keyof T`, `<T = i32>` (a default type argument) | `` Unsupported type `keyof T` `` / `a default type argument … is not supported` | name the type; a type argument is always inferred |
 | `class B extends A` | `` `extends` is not supported: Nish has no inheritance `` | repeat the fields and `implements` an interface |
-| `static` members, getters/setters | not supported | module `const`s and plain methods |
+| `static` members, `get x()` / `set x(v)` | `` … `static` members are not supported `` / `` Getters and setters are not supported in class `C` (use a method) `` | module `const`s and plain methods |
+| `const [a, b] = xs`, `({ x }: Point) =>`, `(n = 1)`, `(n?: i32)`, `(...ns: i32[])` | `Destructuring is not supported` / `Destructured parameters are not supported` / `Optional/default parameters are not supported` / `Rest parameters are not supported` | one name per binding, every parameter passed; an array for a variable count |
+| `function f(): void;` (an overload), `export default function ()` | `Functions must have a body` / `Functions must be named` | one named function, with its body |
+| a method in an `interface` | `` Interface `I` cannot declare methods (interfaces describe layout only) `` | fields only; a top-level function over the interface |
+| `abstract class`, `declare class`, `constructor(public x: i32)`, `interface B extends A`, `[k: string]: T` | `Abstract classes are not supported` / `` `declare class` is not supported `` / `Parameter properties … are not supported; declare the field and assign it` / ``Interface inheritance (`extends`) is not supported; list every field`` / `Index signatures are not supported …` | a plain class with its fields declared and assigned in the constructor; every field listed; a `Map` for a keyed table |
+| `{ m() { … } }`, `{ "a": 1 }`, `const C = class { }` | ``Unsupported object literal member: MethodDeclaration (only `key: value`)`` / `Object literal keys must be plain identifiers` / `Classes must be named` | fields with identifier keys, a top-level function over the interface, a named top-level class |
 | `type Pair = { a: i32 }` (inline object type) | `` Unsupported type `{ a: i32 }` `` | declare an `interface` |
 | `A \| B` unions | `` Union types other than `T \| null` are forbidden `` | one type, or an `interface` prefix |
 | `String(n)`, `n.toString()` | `` Unknown function `String` `` / `` Unknown method `toString` on i32 `` | `` `${n}` `` |
 | `xs.length = 0` | `` Cannot assign to `length` of i32[] (array length is read-only; use `push`) `` | build a new array |
-| `for (const k in o)` | `Unsupported statement in Phase 1: ForInStatement` | `for (const x of xs)` over an array |
 | `import { readFileSync } from "fs"` | `` Cannot find package `fs` `` — a bare specifier is a **package name**, so it is looked for in `node_modules`; one that is installed but has no `nish` condition is `` Package `fs` has no Nish entry point `` | `readFileSync` is a global; no import needed (or `import { readFileSync } from "nish:fs"`) |
 | `export default f` | `` `export default` / `export =` are not supported `` | `export const f = …` |
-| `export type T = …`, `export enum K` | cannot be exported | declare the alias/enum in each module that needs it |
-| `new Date()`, `Date.now()` | `` Unknown builtin `Date.now` `` | `monotonicNanos()` for elapsed time; there is no wall clock and no calendar |
+| `new Date()` | `` `new Date()` is refused: Nish has no `Date` object; the one `Date` member is `Date.now()`, the wall clock in milliseconds `` | `Date.now()` for the wall clock, `monotonicNanos()` for elapsed time; there is no calendar |
 | `JSON.parse`, `RegExp`, `Promise` | unknown / forbidden | none of these exist; write them or restructure |
 | `for (const [k, v] of m)`, `m.forEach(...)`, `new Map(entries)` | each refused by name | `Map` and `Set` exist, with `size`, `get`, `set` / `add`, `has`, `delete`, `clear`, and `keys()` / `values()` in a `for...of` — see [Map and Set](#map-and-set) |
 | `let v = m.get(k)`, `f(m.get(k))`, `m.get(k) + 1` | `` `m.get(k)` is `i32 \| undefined` and cannot be held in a `let` `` (and one message per place) | `m.get(k) ?? 0`, or `const v = m.get(k); if (v !== undefined) { … }` |
@@ -996,15 +1006,21 @@ export const main = (): i32 => {
   point: `Kind` and `i32` never convert in either direction. Members must be
   numeric literals. `===` and `!==` are the **only** operators — no arithmetic,
   no bitwise, so **bit flags stay `i32` module constants**.
-- **Neither can be exported.** Both are module-local; declare them in every
-  module that needs them. A class or interface is what crosses a module
-  boundary.
+- **Both can be exported.** `export enum Kind` is imported like a function,
+  `import { Kind } from "./kinds"` (renamed with `as` if you like), and in the
+  importer it *is* the exporter's `Kind`: the members fold to the exporter's
+  integers and a `Kind` value crosses a call as itself. A `Kind` a second
+  module declares for itself is a different type, however alike the two are.
+  `export type Conn = Socket | null` is imported the same way and is, in the
+  importer, the type it names; its right-hand side is resolved in the module
+  that wrote it, so the importer need not import `Socket`. A module does not
+  re-export an enum or alias it imported.
 - Both are top-level only.
 
 ### Modules
 
-- `export` goes on `const` (function or constant), `class`, and `interface`
-  declarations. No `export default`, no `export { … }`, no `export *`.
+- `export` goes on `const` (function or constant), `class`, `interface`,
+  `enum` and `type` declarations. No `export default`, no `export { … }`, no `export *`.
 - The only import form is a **named import**:
   `import { square, cube as pow3 } from "./math"`. `.ts` is optional. Default
   imports, namespace imports, side-effect imports and type-only imports are all
@@ -1025,8 +1041,8 @@ export const main = (): i32 => {
   `"engines": {"nish": ">=X.Y.Z"}` is above this compiler `` needs a newer
   compiler ``, and a `package.json` that is not JSON names its line and
   column — each with its own `--json` code (`NL3017`–`NL3021`).
-- Functions may be renamed on import; classes and interfaces may not — the type
-  name is part of the ABI.
+- Functions and enums may be renamed on import; classes and interfaces may
+  not — the type name is part of the ABI.
 - Import cycles are allowed; a shared dependency is compiled once.
 - **A function name is unique across the whole program**, exported or not.
 - An `export`ed function is an external C-ABI symbol; every other function gets
@@ -1048,7 +1064,8 @@ export const main = (): i32 => {
 - `for (init; cond; update)` with every clause optional, and
   `for (const x of xs)` over an **array** only — `x` gets the element type and
   must not be annotated. The array's `length` is re-read each iteration, so a
-  `push` inside the body extends the loop.
+  `push` inside the body extends the loop. `for...in`, `for await` and
+  `for (x of xs)` over an existing `x` are each refused by name.
 - `switch` takes an **integer or enum** discriminant; every `case` label is an
   integer constant expression of that type. **There is no implicit
   fallthrough** — a clause with statements ends in `break`, `return`,
@@ -1133,9 +1150,19 @@ constants `Math.PI` / `Math.E`. The f64-only ones reject an `i32`: write
 `Number(x)`, `parseInt(s)` (base 10, `i32`, no `NaN` — no digits give `0`),
 `parseFloat(s)`.
 
+**Constant time.** `ctSelect(mask, a, b)` is `(a & mask) | (b & ~mask)` and
+`ctEq(a, b)` is all-ones when equal and zero otherwise, both over `u32` or
+`u64` only, every operand one type. The mask sits behind an optimisation
+barrier, so neither ever becomes a branch; select and compare on a secret with
+these, never with `if`, `?:`, `===` or `table[secret]`, which they cannot fix.
+
 **Arrays.** `a.length` (read-only), `a.push(v)`, `a.pop()` (panics when empty —
 there is no `undefined` to return), `a.indexOf(v)`, `a.join(sep)` — **`join` is
-`string[]` only**. That is every array method there is.
+`string[]` only** — and, on an array of numbers only, `dst.set(src[, offset])`
+(one `memmove`; a range past the end panics) and `a.fill(v[, start[, end]])`
+(ends clamped and counted back from the end when negative, as in JavaScript;
+never panics). Both are statements. That is every array method there is. A
+window into a buffer is `(buf, offset, length)`; there is no view type.
 
 **Strings.** `s.length` (**bytes**), `s.charCodeAt(i)` (the byte, bounds-checked),
 `s.substring(start[, end])`, `s.slice(start[, end])`, `s.indexOf(sub)`,
@@ -1151,15 +1178,24 @@ in half is possible.
 `process.platform`, `process.arch`.
 
 **Files and the system.** `readFileSync(path)` (exits 1 on failure),
-`readFileSyncOrNull(path)` (`string | null`), `writeFileSync(path, data)`,
+`readFileSyncOrNull(path)` (`string | null`), `readFileBytesSync(path)`
+(`u8[] | null`, the bytes as they are on disk), `writeFileSync(path, data)`,
 `appendFileSync(path, data)`, `mkdirSync(path)` (one level, `boolean`),
 `isDirectorySync(path)`, `readdirSync(path)` (`string[] | null`, sorted by
 bytes, no `.`/`..`), `spawnSync(argv)`, `spawnSyncTo(argv, outPath, errPath)`,
 `getenv(name)` (`string | null` — unset and empty are different answers),
 `realpathSync(path)` (`string | null`; symbolic links resolved, absolute, and
 `null` when it does not resolve),
-`monotonicNanos()` (`i64`; elapsed time only, **there is no wall clock and no
-`Date`**).
+`monotonicNanos()` (`i64`; elapsed time only).
+
+**The host.** `Date.now()` (an `f64` of whole milliseconds, the wall clock —
+**the only `Date` there is**: `new Date()`, `Date.parse` and the rest are
+refused), `crypto.getRandomValues(bytes)` (a statement over a `u8[]` only, at
+most 65,536 bytes a call, from the kernel's CSPRNG; more panics),
+`statMtimeSync(path)` (an `f64` of milliseconds, **NaN** — not `null` — when the
+path cannot be stat'd, so test `m !== m`), and `signalFd()` / `readSignal(fd)`:
+call `signalFd()` once at the top of `main`, then `readSignal(fd)` blocks until
+SIGTERM or SIGINT and answers 15 or 2. None of them exists on a wasm target.
 
 **Arena.** `Arena.mark()`, `Arena.release(m)`, `Arena.reset()`, `Arena.used()`
 — see below.
@@ -1376,8 +1412,9 @@ export const main = (): i32 => {
 **Optional parameters** — there are none. Write two functions with different
 names, or take the value and document the sentinel.
 
-**A wall clock, regex, JSON, threads of your own** — not in the language. Say
-so rather than emitting code that cannot compile.
+**A calendar, regex, JSON, threads of your own** — not in the language (the
+wall clock is `Date.now()`, and that is all of `Date`). Say so rather than
+emitting code that cannot compile.
 
 ## Before you say it compiles
 

package/llms.txt

@@ -26,7 +26,7 @@ the compiler.
 - [Rules card](https://raw.githubusercontent.com/amritk/nish/main/docs/AI.md): the whole language as rules, sized for one read — the traps first, then types, `Result`, nullables, declarations, statements, the complete builtin inventory, and recipes for what is missing. Ships in the npm package as `docs/AI.md`.
 - [Language reference](https://raw.githubusercontent.com/amritk/nish/main/docs/LANGUAGE.md): normative and exhaustive. Every rule cites the test that pins it and quotes the exact rejection message. Settles any disagreement with the rules card.
 - [Ambient declarations](https://raw.githubusercontent.com/amritk/nish/main/runtime/nish.d.ts): reference this from `tsconfig.json` and `tsc --strict`, your editor and your language server accept `Result<T, E>`, `i32` and the rest. `nish` is still the authority — `tsc` cannot see the flow rules.
-- [Standard library](https://raw.githubusercontent.com/amritk/nish/main/std/README.md): `std/testing`, a suite a program drives to check itself and answer an exit code; `std/text`, the `split` / `trim` / `replace` the language does not have; `std/json`, the value of one field of one flat JSON object — enough to read this compiler's own `--json` output. Source rather than a built library, imported by relative path, and shipped in the npm package under `std/`.
+- [Standard library](https://raw.githubusercontent.com/amritk/nish/main/std/README.md): `std/testing`, a suite a program drives to check itself and answer an exit code; `std/text`, the `split` / `trim` / `replace` the language does not have; `std/json`, the value of one field of one flat JSON object — enough to read this compiler's own `--json` output; `nish/crypto`, SHA-256, SHA-384 and SHA-512, HMAC, HKDF, a constant-time compare, base64url and X25519, one module each (`nish/crypto/sha256` and so on). Source rather than a built library, imported as `nish/<module>`, and shipped in the npm package under `std/`.
 - [FAQ](https://raw.githubusercontent.com/amritk/nish/main/docs/FAQ.md): why no `any`, why `i32`, how to get JavaScript numbers, why no GC, overflow and `--wrapping`, what errors look like.
 - [Install](https://raw.githubusercontent.com/amritk/nish/main/docs/INSTALL.md): prerequisites per OS, hello world, exit codes, troubleshooting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Nish: an ahead-of-time compiler from a static subset of TypeScript to LLVM IR",
   "license": "MIT",
   "type": "module",
@@ -77,10 +77,10 @@
     "nish"
   ],
   "optionalDependencies": {
-    "@amritk/nish-x86_64-linux": "0.13.0",
-    "@amritk/nish-aarch64-linux": "0.13.0",
-    "@amritk/nish-aarch64-darwin": "0.13.0",
-    "@amritk/nish-x86_64-darwin": "0.13.0"
+    "@amritk/nish-x86_64-linux": "0.14.0",
+    "@amritk/nish-aarch64-linux": "0.14.0",
+    "@amritk/nish-aarch64-darwin": "0.14.0",
+    "@amritk/nish-x86_64-darwin": "0.14.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",

package/runtime/nish.d.ts

@@ -161,6 +161,18 @@ declare function toF64(x: number | boolean): f64;
 declare function f64ToBits(x: f64): i64;
 declare function bitsToF64(bits: i64): f64;
 
+// ---- Constant time (WP34 N6) ------------------------------------------------
+
+/**
+ * `(a & mask) | (b & ~mask)` with the mask hidden from the optimiser, so it is
+ * never turned into a branch: `a` for an all-ones mask, `b` for zero. Every
+ * operand is one type, `u32` or `u64`. Both are `number` here, so one generic
+ * declaration stands for the two.
+ */
+declare function ctSelect<T extends u32 | u64>(mask: T, a: T, b: T): T;
+/** All-ones of the operands' type when `a === b`, zero otherwise, without a branch. */
+declare function ctEq<T extends u32 | u64>(a: T, b: T): T;
+
 // ---- Streams and files (globals: Nish has no package resolution) ---------
 
 /** `s` to stdout with no trailing newline and no conversion. */
@@ -182,6 +194,12 @@ declare function panic(message: string): never;
 declare function readFileSync(path: string): string;
 /** The same read, answering `null` for every path the other exits over. */
 declare function readFileSyncOrNull(path: string): string | null;
+/**
+ * The file's bytes as they are on disk — no UTF-8 assumed, so a zero byte and
+ * a byte of 0x80 or above survive — or `null` for every path
+ * `readFileSyncOrNull` answers `null` for.
+ */
+declare function readFileBytesSync(path: string): u8[] | null;
 declare function writeFileSync(path: string, data: string): void;
 declare function appendFileSync(path: string, data: string): void;
 /** One directory, not recursive; whether a directory is there afterwards. */
@@ -213,6 +231,34 @@ declare function getenv(name: string): string | null;
  * origin is arbitrary, so only the difference between two reads is meaningful.
  */
 declare function monotonicNanos(): i64;
+/**
+ * The modification time of `path` in milliseconds since the epoch, with the
+ * sub-millisecond fraction the file system keeps (Node's `mtimeMs`), or NaN
+ * when it cannot be stat'd. Follows a symbolic link; a directory has one too.
+ */
+declare function statMtimeSync(path: string): f64;
+/**
+ * A descriptor that becomes readable when SIGTERM or SIGINT arrives, whichever
+ * thread the signal lands on, made once (every call answers the same one), or -1.
+ */
+declare function signalFd(): i32;
+/**
+ * Block until SIGTERM or SIGINT arrives and answer its number, 15 or 2; -1 for
+ * any `fd` that is not `signalFd()`'s. No reading under Node, which throws.
+ */
+declare function readSignal(fd: i32): i32;
+
+// ---- `Date` and `crypto` (WP34 N3) -----------------------------------------------
+//
+// `lib.es2022` already declares `Date`, whose `now()` is Nish's one member of it,
+// so nothing is added: `tsc` accepting `new Date()` is `tsc` not being Nish's
+// checker. `crypto` is a Web API that `lib.es2022` leaves out, so it is
+// declared with its one member, typed as Nish types it.
+
+declare var crypto: {
+  /** Every byte of `bytes` from the system's CSPRNG; at most 65,536 bytes a call. */
+  getRandomValues(bytes: u8[]): void;
+};
 
 // ---- The builtin modules (`nish:`) ---------------------------------------------
 //
@@ -229,6 +275,7 @@ declare function monotonicNanos(): i64;
 declare module "nish:fs" {
   export function readFileSync(path: string): string;
   export function readFileSyncOrNull(path: string): string | null;
+  export function readFileBytesSync(path: string): u8[] | null;
   export function writeFileSync(path: string, data: string): void;
   export function appendFileSync(path: string, data: string): void;
   /** `true` when the directory was created, `false` when it already existed. */
@@ -240,6 +287,8 @@ declare module "nish:fs" {
    */
   export function readdirSync(path: string): string[] | null;
   export function realpathSync(path: string): string | null;
+  /** Node's `mtimeMs` for the path, or NaN when it cannot be stat'd. */
+  export function statMtimeSync(path: string): f64;
 }
 
 declare module "nish:process" {
@@ -257,6 +306,10 @@ declare module "nish:process" {
    * difference between two reads is meaningful.
    */
   export function monotonicNanos(): i64;
+  /** A descriptor readable when SIGTERM or SIGINT arrives; the same one every call, or -1. */
+  export function signalFd(): i32;
+  /** Block until SIGTERM or SIGINT arrives: 15 or 2, or -1 for a descriptor that is not `signalFd()`'s. */
+  export function readSignal(fd: i32): i32;
   /** The command line; `argv[0]` is the program path, as in C. Read-only. */
   export const argv: readonly string[];
   /** The operating system the program runs on: `"linux"`, `"darwin"`, or `"unknown"`. */
@@ -303,6 +356,18 @@ declare interface CPtr {
   readonly __nishForeignPointer: unique symbol;
 }
 
+// ---- `set` on an array ----------------------------------------------------------
+//
+// `dst.set(src, offset)` copies all of `src` into `dst` from `offset` on, with
+// `TypedArray.prototype.set`'s meaning (WP34 N2). A `u8[]` is an `Array` to
+// `tsc`, and `lib.es5.d.ts` gives `Array` a `fill` of the same meaning but no
+// `set`, so this is the one method added to it; `runtime/nish.mjs` installs it
+// under Node. Nish admits it on an array of numbers only.
+
+interface Array<T> {
+  set(source: readonly T[], offset?: number): void;
+}
+
 // ---- What this file cannot say ----------------------------------------------
 //
 // The typed-array aliases (`Int32Array`, `Float32Array`, `Float64Array`,

package/runtime/nish.h

@@ -243,6 +243,12 @@ bool nish_is_dir(const nish_str *path);
  * under WASI: `fd_readdir` lists a preopened directory rather than a path, so
  * porting this there is a different contract and not a translation. */
 nish_array *nish_readdir(const nish_str *path);
+/* `readFileBytesSync(path)` (WP34 N2): the file's bytes as a `u8[]` with
+ * `len == cap`, zero bytes and bytes of 0x80 and above kept as they are, or
+ * NULL for every path `nish_read_file_or_null` answers NULL for. The header
+ * and the bytes live in the arena, so copy what you keep before the next reset
+ * or release. */
+nish_array *nish_read_file_bytes(const nish_str *path);
 /* `spawnSync(argv)`: run element 0 of `argv` (searched on `PATH`) with `argv`
  * as its argument vector, wait for it, and answer its exit status, or
  * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
@@ -306,6 +312,31 @@ const nish_str *nish_arch(void);
  * region into one and measure zero. */
 int64_t nish_monotonic_nanos(void);
 
+/* ---- The host (WP34 N3), runtime/runtime-host.c --------------------------
+ * `Date.now()`: the wall clock, `CLOCK_REALTIME`, in whole milliseconds since
+ * the epoch, as JavaScript answers it. Unlike `nish_monotonic_nanos` it can go
+ * backwards when the clock is corrected; it is for a time a person or a
+ * certificate means, not for measuring an interval. */
+double nish_date_now(void);
+/* `crypto.getRandomValues(bytes)`: fills `bytes->len` bytes from the kernel's
+ * CSPRNG (`getrandom` on Linux, `getentropy` elsewhere). More than 65,536
+ * bytes, the Web API's limit for one call, and a failing entropy source both
+ * print a message and exit 1; nothing weaker is ever substituted. */
+void nish_random_fill(nish_array *bytes);
+/* `statMtimeSync(path)`: the modification time in milliseconds with its
+ * sub-millisecond fraction, computed as Node's `mtimeMs` is, or NaN when
+ * `stat` fails. Follows a symbolic link. */
+double nish_stat_mtime(const nish_str *path);
+/* `signalFd()`: a descriptor that becomes readable when SIGTERM or SIGINT
+ * arrives: the read end of a pipe that a `sigaction` handler writes each
+ * signal's number to, whichever thread the signal lands on. Nothing is
+ * blocked. Made once; every call answers the same descriptor, and -1 when it
+ * could not be made. `readSignal(fd)`: block until one arrives and
+ * answer its number (15 or 2), or -1 for any `fd` that is not that descriptor
+ * or a read that fails. */
+int32_t nish_signal_fd(void);
+int32_t nish_read_signal(int32_t fd);
+
 /* String to number (WP7), ASCII whitespace only. mode 0 is `parseFloat`
  * (longest JS decimal literal or `Infinity`, else NaN), mode 1 is `Number`
  * (the whole string, trimmed; blank is 0; `0x` hex accepted, as in JS),

package/runtime/nish.mjs

@@ -84,6 +84,7 @@ provide("writeError", shim.writeError);
 provide("panic", shim.panic);
 provide("readFileSync", shim.readFileSync);
 provide("readFileSyncOrNull", shim.readFileSyncOrNull);
+provide("readFileBytesSync", shim.readFileBytesSync);
 provide("writeFileSync", shim.writeFileSync);
 provide("appendFileSync", shim.appendFileSync);
 provide("mkdirSync", shim.mkdirSync);
@@ -93,6 +94,35 @@ provide("realpathSync", shim.realpathSync);
 provide("spawnSync", shim.spawnSync);
 provide("spawnSyncTo", shim.spawnSyncTo);
 provide("getenv", shim.getenv);
+provide("statMtimeSync", shim.statMtimeSync);
+provide("signalFd", shim.signalFd);
+provide("readSignal", shim.readSignal);
+
+// `crypto.getRandomValues(bytes)` (WP34 N3). Node has the global, but it
+// takes only a typed array and a `u8[]` is a plain `Array` here, so the one
+// method is replaced on Node's own `crypto` object by one that fills a plain
+// array too (and hands a typed array to the original).
+Object.defineProperty(globalThis.crypto, "getRandomValues", {
+  value: shim.getRandomValues,
+  writable: true,
+  configurable: true,
+});
+
+// `dst.set(src, offset)` (WP34 N2). A `u8[]` is a plain `Array` here, which
+// has `fill` with the typed array's meaning already but no `set`, so the one
+// method is added to `Array.prototype` — non-enumerable, as a builtin method is,
+// so no `for...in` sees it — unless something got there first. It copies the
+// source before writing, as the native `memmove` does, and fails a range past
+// the end with the native panic.
+if (!("set" in Array.prototype)) {
+  Object.defineProperty(Array.prototype, "set", {
+    value: function set(source, offset) {
+      shim.arraySet(this, source, offset);
+    },
+    writable: true,
+    configurable: true,
+  });
+}
 
 // The clock. `monotonicNanos()` answers an `i64`, so the value is a BigInt here
 // as it is in the rewritten runner — and unusually for the i64 surface that is
@@ -117,6 +147,11 @@ provide("toU64", (x) => shim.convert(x, "f64", "u64"));
 provide("f64ToBits", shim.f64ToBits);
 provide("bitsToF64", shim.bitsToF64);
 
+// Constant time (WP34 N6). Pure functions of their operands, so the answers
+// agree with a native run; the timing does not, and is not claimed here.
+provide("ctSelect", shim.ctSelect);
+provide("ctEq", shim.ctEq);
+
 // `Result`. Everything works but `orReturn`, which needs the caller's control
 // flow and therefore the rewriter; see the header.
 provide("Ok", shim.Ok);

package/runtime/runtime-host.c

@@ -0,0 +1,178 @@
+/* Nish runtime, the host half: the wall clock, entropy, a file's modification
+ * time and a descriptor that becomes readable when SIGTERM or SIGINT arrives
+ * (WP34 N3) — the four facts a program that runs for days asks of the machine
+ * it runs on.
+ *
+ * A translation unit of its own for the reason runtime-os.c is one: each file
+ * carries its own measured `.text*` ceiling in tests/run.js. runtime-os.c had
+ * 143 bytes of its ceiling left when these arrived, the four measure more than
+ * that, and a ceiling is not raised to make room (docs/MASTER_PLAN.md §2 has
+ * the numbers). Section GC still means a program that calls none of them pays
+ * for none of them, and scripts/build.sh pairs this file with runtime.c like
+ * the other two halves, so a link line still names one runtime.
+ *
+ * Every function here is platform code, and the two platforms differ in three
+ * places: `getrandom` on Linux and `getentropy` elsewhere, `st_mtim`
+ * against Darwin's `st_mtimespec`, and `pipe2` against `pipe` for the signal
+ * descriptor. A WASI build has none of this
+ * (the checker refuses all four under a wasm target), so there the file is
+ * empty.
+ */
+#if defined(__wasi__) || defined(__wasm__)
+/* ISO C wants at least one declaration in a translation unit. */
+typedef int nish_host_unused;
+#else
+#if defined(__linux__)
+/* glibc declares `clock_gettime`, `sigaction` and `pipe2` under `-std=c11`
+   only with a feature macro, and `pipe2` only with this one. Darwin declares
+   everything by default and hides `getentropy` and the `st_mtimespec`
+   spelling behind a strict feature level, so it gets none. */
+#define _GNU_SOURCE
+#endif
+#include <errno.h>
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/random.h>
+
+#include "nish.h"
+
+/* The spelling runtime.c and runtime-os.c use for their cold paths. */
+#define NISH_COLD __attribute__((noreturn, cold, noinline))
+
+/* `Date.now()`: `CLOCK_REALTIME` in whole milliseconds since the epoch, as
+   JavaScript answers it — the milliseconds are counted in integers and then
+   converted, so the answer is exact until the year 287,396 and a negative
+   time floors the way `Date.now` does rather than rounding towards zero. */
+double nish_date_now(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_REALTIME, &ts);
+  return (double)((int64_t)ts.tv_sec * 1000 + ts.tv_nsec / 1000000);
+}
+
+static NISH_COLD void nish_entropy_fail(uint64_t asked) {
+  if (asked > 65536) {
+    dprintf(2, "crypto.getRandomValues: %llu bytes asked for, and one call fills at most 65536\n",
+            (unsigned long long)asked);
+  } else {
+    dprintf(2, "crypto.getRandomValues: the system's entropy source failed\n");
+  }
+  _exit(1);
+}
+
+/* `crypto.getRandomValues(bytes)`: every byte of `bytes` from the kernel's
+   CSPRNG, or a panic. There is no fallback to a weaker source, because a
+   program handed predictable bytes for a key or a nonce cannot tell. The Web
+   API's limit of 65,536 bytes a call is kept, so a program behaves the same
+   under Node. `getrandom` without flags blocks only until the pool is first
+   initialised at boot and can return short or be interrupted, so it loops;
+   `getentropy` fills at most 256 bytes a call and retries nothing itself. */
+void nish_random_fill(nish_array *bytes) {
+  uint64_t n = bytes->len;
+  char *p = bytes->data;
+  if (n > 65536) nish_entropy_fail(n);
+  while (n > 0) {
+#if defined(__linux__)
+    ssize_t got = getrandom(p, n, 0);
+    if (got < 0) {
+      if (errno == EINTR) continue;
+      nish_entropy_fail(0);
+    }
+#else
+    size_t got = n < 256 ? n : 256;
+    if (getentropy(p, got) != 0) nish_entropy_fail(0);
+#endif
+    p += got;
+    n -= (uint64_t)got;
+  }
+}
+
+/* `statMtimeSync(path)`: the modification time in milliseconds, with the
+   sub-millisecond part the file system keeps, or NaN when `stat` fails. The
+   arithmetic is Node's `mtimeMs` operation for operation — seconds times 1e3
+   plus nanoseconds over 1e6, in doubles — so the two readings print the same
+   digits. `stat` follows a symbolic link, as `fs.statSync` does. */
+double nish_stat_mtime(const nish_str *path) {
+  struct stat st;
+  if (stat(path->data, &st) != 0) return __builtin_nan("");
+#if defined(__APPLE__)
+  struct timespec t = st.st_mtimespec;
+#else
+  struct timespec t = st.st_mtim;
+#endif
+  return (double)t.tv_sec * 1e3 + (double)t.tv_nsec / 1e6;
+}
+
+/* ---- Signals: `signalFd()` and `readSignal(fd)`
+ *
+ * A descriptor rather than a handler in the language, because a handler would
+ * be a function value the language does not have, and because a descriptor is
+ * what a loop waiting in `epoll` or `poll` can wait on beside its sockets.
+ *
+ * Underneath it is a C handler writing each signal's number, one byte, to a
+ * pipe. It is not a `signalfd` on Linux, deliberately: a `signalfd` only
+ * hears a signal that is blocked in **every** thread, and a mask reaches only
+ * the calling thread, so a `scope()` task or a parallel worker already
+ * running when `signalFd()` was called would take the signal at its default
+ * action and end the process. A handler runs in whichever thread the kernel
+ * picks, so no thread's mask matters, and nothing is blocked for a child
+ * `spawnSync` starts to inherit: `exec` resets a caught signal to its
+ * default. Installing the handler also overrides a disposition the process
+ * was started with, so a signal its parent ignored is heard, as
+ * `process.on('SIGTERM')` hears it under Node.
+ *
+ * The handler is the whole of what runs in signal context, and `write` is
+ * async-signal-safe. The write end is non-blocking, so a thousand unread
+ * signals lose the newest rather than wedge the handler, and `errno` is put
+ * back for the code the signal interrupted. The descriptor is made once and
+ * every later `signalFd()` answers the same one. */
+static int nish_signal_read_end = -1;
+static int nish_signal_write_end = -1;
+
+static void nish_on_signal(int sig) {
+  int saved = errno;
+  unsigned char b = (unsigned char)sig;
+  (void)!write(nish_signal_write_end, &b, 1);
+  errno = saved;
+}
+
+int32_t nish_signal_fd(void) {
+  if (nish_signal_read_end >= 0) return nish_signal_read_end;
+  int p[2];
+#if defined(__linux__)
+  /* Both ends close-on-exec from the moment they exist, so a child a sibling
+     thread spawns meanwhile cannot inherit either. */
+  if (pipe2(p, O_CLOEXEC) != 0) return -1;
+#else
+  /* Darwin has no `pipe2`, so there is a window between `pipe` and the two
+     `fcntl`s in which a child spawned by another thread inherits the ends. */
+  if (pipe(p) != 0) return -1;
+  fcntl(p[0], F_SETFD, FD_CLOEXEC);
+  fcntl(p[1], F_SETFD, FD_CLOEXEC);
+#endif
+  fcntl(p[1], F_SETFL, O_NONBLOCK);
+  nish_signal_write_end = p[1];
+  struct sigaction sa;
+  sa.sa_handler = nish_on_signal;
+  sa.sa_flags = SA_RESTART;
+  sigemptyset(&sa.sa_mask);
+  sigaction(SIGINT, &sa, 0);
+  sigaction(SIGTERM, &sa, 0);
+  return nish_signal_read_end = p[0];
+}
+
+/* Block until a signal's byte arrives and answer it: 15 or 2, or -1 for any
+   `fd` that is not the signal descriptor and for a read that fails. */
+int32_t nish_read_signal(int32_t fd) {
+  if (fd != nish_signal_read_end) return -1;
+  unsigned char b;
+  ssize_t n;
+  do n = read(fd, &b, 1);
+  while (n < 0 && errno == EINTR);
+  return n == 1 ? (int32_t)b : -1;
+}
+#endif

package/runtime/runtime-os.c

@@ -102,6 +102,21 @@ nish_str *nish_read_file_or_null(const nish_str *path) {
   return s;
 }
 
+/* `readFileBytesSync(path)` (WP34 N2): the same read, handed to the language as
+   a `u8[]`. The bytes are not copied a second time: `nish_read_file_or_null`
+   has already put them in the arena behind their 8-byte length, 8-aligned, so
+   the header points `data` there with `len == cap`, and the NUL written after
+   them is simply never indexed. Nothing on the way assumes UTF-8, so a zero
+   byte and a byte of 0x80 or above come back as they are on disk. A `push`
+   onto the result grows it into a fresh block, as it would any full array. */
+nish_array *nish_read_file_bytes(const nish_str *path) {
+  nish_str *s = nish_read_file_or_null(path);
+  if (!s) return 0;
+  nish_array *a = nish_alloc_struct(sizeof *a);
+  *a = (nish_array){ s->len, s->len, s->data };
+  return a;
+}
+
 nish_str *nish_read_file(const nish_str *path) {
   nish_str *s = nish_read_file_or_null(path);
   if (!s) nish_io_fail("read ", path);