@amritk/nish 0.12.0 → 0.14.0

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) { … }` |
@@ -198,16 +208,42 @@ const good = (a: i32, b: i64): i64 => {
 };
 ```
 
-**`integer` is reserved, not a type.** It is held for ranged integers
-(`integer<Lo, Hi>`), which the compiler does not build yet, so writing it as a
-type is refused. Declaring a type alias, enum, class, interface or function
-named `integer` is refused too. Use `i32`. A value named `integer` (a local
-or a module constant) is fine.
+**`integer<Lo, Hi>` is an `i32` that stays in `[Lo, Hi]`.** The bounds are two
+integer literals (a sign allowed) inside `i32`, and it is an `i32` everywhere
+the machine can see. Putting a value *into* one is checked: an `i32` or
+another range is compared once and the program panics (exit 1) outside the
+range, a literal outside it is a compile error, and a literal inside it or a
+narrower range costs nothing. So does a value a loop condition or a guard
+already bounds (`b` below), and `toI32` of a `u8`; a check left inside a loop
+is a performance warning (NL9013) naming the guard that removes it. A range
+bounds an index too: `integer<0, 255>`, like `u8`, needs only a length guard of
+256. Taking one *out* is free: every operator reads
+it as `i32`, a `const` keeps the range and a `let` widens to `i32`. A `u8` is
+not an `integer<0, 255>` (convert with `toI32`), and a `declare function` may
+not mention a range. Put the range on the value you use, not on a loop
+counter, which has to leave the range to end the loop.
 
-```ts nish:err NL2333
-const clamp = (x: integer): i32 => x;
+```ts nish:ok
+const getByte = (buf: u8[], i: integer<0, 255>): u8 => buf[i];
+
+const sumAll = (buf: u8[]): i32 => {
+  let sum = 0;
+  for (let i = 0; i < 256 && i < buf.length; i++) {
+    const b: integer<0, 255> = i;
+    sum = sum + toI32(getByte(buf, b));
+  }
+  return sum;
+};
 ```
 
+```ts nish:err-body NL2384
+const digit: integer<0, 9> = 12;
+```
+
+Declaring a type alias, enum, class, interface or function named `integer` is
+refused, because the name is the type. A value named `integer` (a local or a
+module constant) is fine.
+
 ```ts nish:err NL2332
 class integer {
   value: i32 = 0;
@@ -317,6 +353,8 @@ Narrowing follows the same engine as `T | null` below: it applies to a
 **variable**, never a property path; it ends at any assignment to that
 variable; and it is dropped before a loop that assigns it. `if (r.isOk()) A
 else B` narrows in `A`, and after the `if` when `B` cannot fall through.
+The proof stays with `r`: `const y = r`, `c ? r : q` and `[r]` are plain
+`Result`s, so test `y` itself before `y.value`.
 
 `panic(message)` is the other ending: message to stderr, exit 1. It is for an
 invariant that cannot hold, not for a failure a caller should handle. It
@@ -360,8 +398,9 @@ export const main = (): i32 => {
   `Map.get` (see [Map and Set](#map-and-set)).
 - Narrowing applies to a **local or parameter**, never a property path. `if
   (n.next !== null) n.next.v` is rejected — copy into a local first.
-- A narrowing ends at any assignment to the variable, and is dropped before a
-  loop whose body, condition or update assigns it.
+- A narrowing ends at any assignment to the variable, including one in an
+  earlier operand of the same `&&` / `||` chain, and is dropped before a loop
+  whose body, condition or update assigns it.
 - Two nullables cannot be compared with each other; compare each with `null`.
 - `new Array<T | null>(n)` is allowed: the zero fill *is* `null`.
 
@@ -723,6 +762,62 @@ import { parallelReduce } from "nish/threads";
 export const main = (): i32 => parallelReduce([1, 2, 3], (a, b) => a + b, 1);   // `+` folds from 0
 ```
 
+### Scoped tasks: `using s = scope()`
+
+Different functions at once, one thread each: open a scope with `using`, give
+it tasks with `spawn(entry, arg, dst, at)`, and every task has run and stored
+`entry(arg)` into `dst[at]` when the block ends. (A plain block, for the same
+reason as the one above: `tests/link/thread_scope_basic` compiles it.)
+
+```ts
+import { scope } from "nish/threads";
+
+const sumOf = (xs: f64[]): f64 => xs[0] + xs[1];
+const square = (n: i32): i32 => n * n;
+
+export const main = (): i32 => {
+  const xs: f64[] = [1.5, 2.5];
+  const sums: f64[] = [0.0];
+  const squares: i32[] = [0];
+  {
+    using s = scope();
+    s.spawn(sumOf, xs, sums, 0);
+    s.spawn(square, 12, squares, 0);
+  }                                          // joined here, on every exit
+  console.log(`${sums[0]} ${squares[0]}`);   // 4 144
+  return 0;
+};
+```
+
+- **The tasks run when the block ends**, together, and each answer is stored
+  after the last one finishes. So read a destination after the block. A
+  destination is a `const` bound to a fresh array (`[0, 0]`, `new Array`) that
+  you only index; never pass it on. Between the first `spawn` and the block's
+  end, don't read a destination, and don't write memory a task could read (a
+  store into an argument, a call that writes through its argument).
+- **`using` takes only `scope()`**, and `scope()` only comes from `using`.
+  The scope is only ever the receiver of a `spawn` statement: never pass it,
+  store it or return it.
+- **The task is a named top-level function**, not an arrow, and it follows the
+  data-parallel rules: it writes nothing anybody else can see, answers a number,
+  a `boolean` or an enum, and leaves `Arena` alone. A task cannot open a scope
+  of its own or call `parallelMapInto`.
+- **Any argument will do** — an array, an object — because nothing writes
+  memory while the tasks run. There is no thread count: one task, one thread.
+
+```ts nish:err NL2388
+import { scope } from "nish/threads";
+
+const one = (n: i32): i32 => n + 1;
+
+export const main = (): i32 => {
+  const out: i32[] = [0];
+  const s = scope();   // a scope must be introduced by `using`
+  s.spawn(one, 1, out, 0);
+  return out[0];
+};
+```
+
 ### Calling C
 
 `declare function name(params): T;` declares a C function this program calls but
@@ -911,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
@@ -940,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
@@ -963,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`,
@@ -1048,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)`,
@@ -1066,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.
@@ -1291,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/docs/INSTALL.md

@@ -2,7 +2,7 @@
 
 `nish` compiles a static subset of TypeScript to LLVM IR and, with
 `--link`, to a native binary. The compiler is itself a native binary, written
-in Nish (`self/`), and needs nothing to run; the `--link` step (and anything
+in Nish (`src/`), and needs nothing to run; the `--link` step (and anything
 else that turns `.ll` into machine code) needs an LLVM toolchain.
 
 ## 1. Prerequisites
@@ -142,7 +142,7 @@ The npm route installs the **native** compiler, and it is a download rather than
 build: nothing is compiled on your machine. The package declares one
 `nish-<os>-<arch>` package per supported platform as an `optionalDependencies`
 entry with `os` and `cpu` set, so npm fetches exactly the one that matches and
-skips the rest. Each of those carries the self-hosted compiler — `self/`
+skips the rest. Each of those carries the self-hosted compiler — `src/`
 compiled by itself — already built, `--verify`d and smoke-tested on a machine
 of its own architecture by the release workflow.
 
@@ -198,7 +198,7 @@ nish: no prebuilt compiler for freebsd/x64
 
 Until 0.6.0 it ran the TypeScript compiler that shipped in the same package
 instead — the same compiler by every test here, about eight times slower, and
-no C toolchain needed. That compiler was `src/`, which was deleted in R6
+no C toolchain needed. That compiler was stage0, which was deleted in R6
 ([wp19](wp19-stage0-retirement.md)), so there is nothing left in the package to
 fall back to. The cost is stated where the rest of that deletion's costs are,
 in [wp19 §6](wp19-stage0-retirement.md#6-what-retirement-costs-stated-plainly),
@@ -218,7 +218,7 @@ routes are
   # in the glibc container, where build/nish runs
   build/nish app.ts -o app.ll
   # on the musl host, with its own clang and the runtime from this repository
-  clang app.ll runtime/runtime.c runtime/runtime_os.c -lm -o app
+  clang app.ll runtime/runtime.c runtime/runtime-os.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -268,7 +268,7 @@ npm install -g ./amritk-nish-0.4.0.tgz ./amritk-nish-x86_64-linux-0.4.0.tgz
 ```
 
 As a native compiler, which needs no Node at all. A release also attaches the
-self-hosted compiler — the binary `self/` produces by compiling itself — one
+self-hosted compiler — the binary `src/` produces by compiling itself — one
 per supported platform, from the version named in the last column:
 
 | Asset | For | Attached from |
@@ -326,7 +326,7 @@ release exists, take its version from
 Unpack it and run `bin/nish` from wherever you like; put that on `PATH` if you
 want it there. Keep the directory intact rather than moving the binary out of
 it: `--link` runs `scripts/build.sh` and compiles the C runtime
-(`runtime/runtime.c` and `runtime/runtime_os.c`, the system-call half), and the
+(`runtime/runtime.c` and `runtime/runtime-os.c`, the system-call half), and the
 compiler finds all of them relative to its own location — `bin/nish` alone in a
 directory can still emit IR with `-o`, but `--link` will tell you it cannot
 find `scripts/build.sh`.
@@ -367,23 +367,23 @@ Building the IR yourself rather than through `--link` means naming the runtime
 on the `clang` line, and it is two files:
 
 ```bash
-clang app.ll runtime/runtime.c runtime/runtime_os.c -lm -o app
+clang app.ll runtime/runtime.c runtime/runtime-os.c -lm -o app
 ```
 
 `runtime.c` is the half every program touches — the arena, strings, arrays,
-number formatting, the panics — and `runtime_os.c` is the half that wraps the
+number formatting, the panics — and `runtime-os.c` is the half that wraps the
 system calls: files, directories, subprocesses, `getenv`, the monotonic clock.
 They are separate so that each carries its own measured size ceiling
 ([docs/wp7-runtime.md](wp7-runtime.md)); nothing in the core calls into the
 system-call half, so an older line that names `runtime.c` alone still links a
 program that reads no files and spawns nothing. `scripts/build.sh` compiles
-`runtime_os.c` beside any `runtime.c` it is handed, so a build that goes
+`runtime-os.c` beside any `runtime.c` it is handed, so a build that goes
 through it — every `--link`, and every `--profile` recipe in these documents —
 needs to name only the one.
 
 ## 2a. What `npm run build` does
 
-`self/` is the compiler, written in Nish, and it compiles itself
+`src/` is the compiler, written in Nish, and it compiles itself
 ([docs/wp14-selfhost.md](wp14-selfhost.md)). From a checkout, with clang on
 `PATH`, `npm run build` runs `scripts/bootstrap.sh` with the seed from §2:
 
@@ -406,11 +406,11 @@ binary itself. It looks for `scripts/build.sh` and the two `runtime/*.c` files
 one level up from wherever it was invoked, then in the working directory, so
 it wants a checkout or an installed package around it the way `nish` does.
 
-Because the seed is the last release, `self/` may only *use* in its own
+Because the seed is the last release, `src/` may only *use* in its own
 source the constructs that release compiles. A new construct is implemented
-in `self/` and becomes usable inside `self/` from the next release on; CI's
+in `src/` and becomes usable inside `src/` from the next release on; CI's
 `bootstrap` job is what checks that the released seed still builds stage1.
-Until R6 the seed was a TypeScript compiler in `src/`, run under Node; it was
+Until R6 the seed was a TypeScript compiler, stage0, run under Node; it was
 deleted once the native one answered every flag it did
 ([wp19](wp19-stage0-retirement.md)).
 

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.12.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",
@@ -46,7 +46,9 @@
     "test:nish": "build/nish tests/nish/run.ts -o build/nish-runner.ir/ --link build/nish-runner && build/nish-runner",
     "test:cli": "build/nish tests/nish/cli.ts -o build/nish-cli.ir/ --link build/nish-cli && build/nish-cli",
     "test:node": "node tests/differential/unmodified.js",
-    "lint": "node scripts/check-filenames.mjs --advisory && biome check --formatter-enabled=false .",
+    "lint": "node scripts/check-filenames.mjs && biome check .",
+    "lint:fix": "biome check --write .",
+    "lint:dead": "knip --no-progress",
     "format": "biome format --write .",
     "prepublishOnly": "npm run check && npm test",
     "changelog": "node scripts/changelog-gen.mjs"
@@ -75,14 +77,15 @@
     "nish"
   ],
   "optionalDependencies": {
-    "@amritk/nish-x86_64-linux": "0.12.0",
-    "@amritk/nish-aarch64-linux": "0.12.0",
-    "@amritk/nish-aarch64-darwin": "0.12.0",
-    "@amritk/nish-x86_64-darwin": "0.12.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",
     "@types/node": "^22.0.0",
+    "knip": "6.38.0",
     "typescript": "^5.6.0"
   }
 }

package/runtime/nish.d.ts

@@ -54,6 +54,12 @@ type u64 = number;
 type f32 = number;
 type f64 = number;
 
+// ---- Ranged integers (docs/wp31-ranged-integers.md) --------------------------
+//
+// An `i32` the compiler knows lies in `[Lo, Hi]`. The bounds are numeric
+// literal types, and `tsc` checks only that; the range itself is `nish`'s.
+type integer<Lo extends number, Hi extends number> = number;
+
 // ---- Result (docs/LANGUAGE.md -> Result and error handling) ------------------
 //
 // Modelled as the tagged union TypeScript would use anyway, intersected with
@@ -104,6 +110,19 @@ declare function Err<T, E>(error: E): Result<T, E>;
 // `Process` is not that lucky, so a project that needs `@types/node` for other
 // reasons should drop this file's `process` rather than fight it.
 
+/**
+ * The disposable protocol `using` reads (WP29 P2, docs/wp29-thread-surface.md
+ * §5): declared here so that a program using `nish/threads`'s scope needs no
+ * `"ESNext.Disposable"` in its `lib`. `nish` itself takes `using` only for a
+ * `scope()`, and `[Symbol.dispose]` only in `nish/threads`.
+ */
+interface SymbolConstructor {
+  readonly dispose: unique symbol;
+}
+interface Disposable {
+  [Symbol.dispose](): void;
+}
+
 interface Console {
   /** `x` and a newline to stdout. Statement position; exactly one argument. */
   log(x: string | number | boolean): void;
@@ -142,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. */
@@ -152,7 +183,7 @@ declare function writeError(s: string): void;
  * `message` and a newline to stderr, then exit 1. Terminates control flow, so
  * it is `never`: that is what lets `tsc` agree that a function ending in a
  * `panic` returns, and that `x` is not null after `if (x === null) { panic(...); }`
- * — the guard-then-panic shape `self/` uses everywhere in place of an assert.
+ * — the guard-then-panic shape `src/` uses everywhere in place of an assert.
  */
 declare function panic(message: string): never;
 /**
@@ -163,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. */
@@ -194,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:`) ---------------------------------------------
 //
@@ -210,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. */
@@ -221,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" {
@@ -238,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"`. */
@@ -284,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`,