@amritk/nish 0.10.0 → 0.12.0

package/README.md

@@ -49,22 +49,19 @@ Requirements: Node.js 22.18+ and, to produce binaries, clang (LLVM 18) + lld;
 per-OS install commands are in [docs/INSTALL.md](docs/INSTALL.md).
 
 ```bash
-# Once this is published, the whole install is either of:
-#   npm install -g @amritk/nish
-#   curl -fsSL https://raw.githubusercontent.com/amritk/nish/main/install.sh | sh
+npm install -g @amritk/nish            # or per project: npm i -D @amritk/nish
+npx @amritk/nish --version             # or run it without installing
+# or, with no Node at all:
+curl -fsSL https://raw.githubusercontent.com/amritk/nish/main/install.sh | sh
 # `nish` on the registry is an unrelated package from 2014, so this one is
-# scoped; the command it installs is still `nish`. Nothing is published yet,
-# so take it from a release -- the npm tarball, plus the prebuilt native
-# compiler for your machine, which is what the scoped install would fetch.
-base=https://github.com/amritk/nish/releases/download/v0.4.0
-curl -LO $base/amritk-nish-0.4.0.tgz
-curl -LO $base/amritk-nish-x86_64-linux-0.4.0.tgz    # or the row for your machine
-npm install -g ./amritk-nish-0.4.0.tgz ./amritk-nish-x86_64-linux-0.4.0.tgz
+# scoped; the command it installs is still `nish`. npm fetches the prebuilt
+# native compiler for your machine alongside it.
 ```
 
 > [!NOTE]
-> **Install the pair.** The main package is a launcher and carries no compiler:
-> installed on its own it has nothing to hand over to and says so, exiting 3.
+> **From a release tarball rather than the registry, install the pair.** The
+> main package is a launcher and carries no compiler: installed on its own it
+> has nothing to hand over to and says so, exiting 3.
 > The same is true on a platform this project publishes no binary for — musl,
 > FreeBSD, 32-bit anything — which since 0.6.0 gets a diagnostic naming the four
 > that do rather than the TypeScript compiler under Node that used to ship
@@ -91,6 +88,7 @@ export const main = (): number => {
 nish hello.ts --link hello    # writes hello.ll, then builds hello with clang -O3 -flto
 ./hello                            # hello from Nish
 nish hello.ts -o hello.ll     # IR only
+nish run hello.ts             # build into a cache and run it: a script, still native
 ```
 
 The IR is readable as is. `examples/add.ts` compiles to:
@@ -278,6 +276,7 @@ buys is the output: no GC, no runtime, and the sizes under
 
 ```
 nish <entry.ts> [more.ts ...] [options]
+nish run [options] <file.ts> [args ...]
        nish --version | --help
   -o, --output <file.ll>     output path for a single module (default: <input>.ll)
   -o, --output <dir>/        output directory: one <dir>/<module>.ll per module
@@ -330,6 +329,22 @@ with `2`. `-g` adds a DWARF line table and variables to the IR so
 Multi-file programs: `nish examples/multi/main.ts --link build/multi && ./build/multi; echo $?`
 prints `49`.
 
+**`nish run` is the scripting shape.** `nish run tool.ts a b` compiles
+`tool.ts`, links it into a cache, and starts it with `a b` as its arguments.
+Its stdin, stdout and stderr are the program's, and its exit status is the
+program's once it starts (`128 + n` for a signal). The options before the file
+are the compiler's (`--number-mode f64`, `--profile speed`, `-g`), and
+everything after it is the program's, `--help` included. Nothing is
+interpreted: every run compiles, which takes milliseconds, and links only when
+the IR, the recipe or the runtime is new, so the first run of an edit pays for
+one `--profile debug` link (the default here, and the fast one) and every run
+after that starts the cached binary. The cache is `$XDG_CACHE_HOME/nish/run`,
+or `~/.cache/nish/run`. Each entry is one program, so `rm -rf` of it is always
+safe. `-o`, `--link`, `--target`, the `--emit-*` sidecars and
+`--profile wasi` write something a run keeps to itself, so they are usage
+errors there, and performance warnings are not printed, because stderr belongs
+to the program.
+
 Without `--link`, build the IR yourself: `clang add.ll examples/main.c runtime/runtime.c runtime/runtime_os.c -o app`
 (the `overriding the module target triple` warning is harmless: the IR is
 target-neutral unless you pass `--target`; `-Wno-override-module` silences
@@ -550,4 +565,5 @@ coding agents are in [AGENTS.md](AGENTS.md) and [`.claude/`](.claude/).
 
 ## License
 
-MIT, see [LICENSE](LICENSE).
+MIT, see [LICENSE](LICENSE). Third-party code in the repository keeps its own
+licence; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/docs/AI.md

@@ -37,6 +37,7 @@ and it is the only authority.
 nish program.ts --json            # one JSON object per diagnostic, on stdout
 nish program.ts -o out.ll         # emit LLVM IR
 nish program.ts --link prog       # build a native binary (needs clang)
+nish run program.ts a b           # build into a cache, then run it with `a b`
 nish --help                       # the full flag list, stdout, exit 0
 ```
 
@@ -58,7 +59,9 @@ exclusive:
   `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
-  bug in `nish`, not in your program, and is worth reporting.
+  bug in `nish`, not in your program, and is worth reporting. `nish run`
+  answers the same codes until the program starts, and the program's own
+  status after that.
 - Every failure is a `--json` object, toolchain and internal errors included,
   so you never have to parse stderr to find out why a run failed.
 
@@ -111,14 +114,14 @@ 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; there are no function values to pass |
+| `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) |
 | `s.toUpperCase()`, `s.split()`, `s.trim()`, `s.replace()` | `` Unknown method … on string `` | index bytes with `charCodeAt` / `substring` |
-| `a?.b`, `a ?? b` | forbidden | `if (a !== null)` first |
+| `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 |
 | `any`, `unknown` | forbidden | name the real type |
-| `undefined` | forbidden | `null`, with a `T \| null` 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 |
-| a callback: `xs.forEach(f)`, `(cb: (n: i32) => i32)` | `` Unsupported type `(n: i32) => i32` `` | there are **no function values**; inline the body or write a loop |
+| 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 |
 | `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 |
@@ -136,7 +139,9 @@ rejects. This table is the highest-value part of the page.
 | `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 |
-| `JSON.parse`, `RegExp`, `Map`, `Set`, `Promise` | unknown / forbidden | none of these exist; write them or restructure |
+| `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) { … }` |
 | `let x = 5; x = "s"` | `Cannot initialize …` | types never change and never convert implicitly |
 
 A worked pair. This is the single most common rejection:
@@ -351,7 +356,8 @@ export const main = (): i32 => {
 ```
 
 - Reading anything off an un-narrowed nullable is an error: narrow with
-  `!== null` first. `?.` and `??` are forbidden outright.
+  `!== null` first. `?.` is forbidden outright, and so is `??`, except after
+  `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
@@ -373,11 +379,14 @@ const double = (n: i32): i32 => n * 2;   // a concise body is that one `return`
 
 - A function is a **module-level `const` bound to an arrow**. `let` is
   rejected; annotating the `const` is rejected (the annotation would be a
-  function type, and those are forbidden). The `function` keyword is accepted
-  as the legacy spelling and compiles to identical IR.
+  function type, which only a parameter may have). The `function` keyword is
+  accepted as the legacy spelling and compiles to identical IR.
 - **Every parameter and the return type must be annotated.**
 - **A function is not a value.** `const alias = double` is
-  `` Unknown identifier `double` ``. No callbacks, no function types, ever.
+  `` Unknown identifier `double` ``. A function may be *passed* only for a
+  function-typed parameter, where it is resolved at compile time — see
+  [Function parameters](#function-parameters) — and never stored, returned or
+  held in a field, a local or an array.
 - **Parameters are immutable**: `p = 1`, `p++`, `p += 1` are all rejected. Copy
   into a `let` first.
 - A non-`void` function must return on every path.
@@ -605,6 +614,115 @@ class Box<T> {
 export const main = (): i32 => new Box<i32>(1).value;
 ```
 
+### Function parameters
+
+A parameter of a top-level function may have a **function type**. Its argument
+is a top-level function named at the call, or an arrow written right there, and
+each one is compiled into its **own copy** of the function, with a direct call
+where the parameter is called — there is no function pointer at run time.
+
+```ts nish:ok
+const map = <T, U>(xs: T[], f: (x: T) => U): U[] => {
+  const out: U[] = [];
+  for (const x of xs) {
+    out.push(f(x));
+  }
+  return out;
+};
+
+const fold = <T>(xs: T[], f: (acc: T, x: T) => T, identity: T): T => {
+  let acc = identity;
+  for (const x of xs) {
+    acc = f(acc, x);
+  }
+  return acc;
+};
+
+const add = (a: i32, b: i32): i32 => a + b;
+
+export const main = (): i32 => {
+  const doubled = map([1, 2, 3], (n) => n * 2);   // U is bound from the body
+  return fold(doubled, add, 0) - 12;              // 0
+};
+```
+
+- **Call it, or pass it on to another function parameter. Nothing else**:
+  `const g = f`, `return f` and `[f]` are
+  `` `f` is a function parameter and can only be called or passed on as a function argument ``.
+- **An arrow captures nothing.** It sees its own parameters and top-level
+  names; reading a local of the function around it is
+  `` The arrow reads `k`, which belongs to the function it is written in ``.
+  Pass the value in as another argument of the template instead.
+- **The argument's type must match exactly**: `(x: i32) => i64` for a
+  `(x: i32) => i32` parameter is refused. A generic function cannot be passed
+  by name — write `(x) => identity(x)`.
+- **Annotate what cannot be inferred**: an arrow parameter whose type no value
+  argument binds, and the return type of a block-bodied arrow whose result is a
+  type parameter.
+- **Only a top-level function** may have one: not a method, a constructor, a
+  field, a local, a return type or an alias.
+
+```ts nish:err NL2335
+const apply = (f: (x: i32) => i32, x: i32): i32 => f(x);
+
+export const main = (): i32 => {
+  const k = 3;
+  return apply((x) => x + k, 1);   // captures `k`: pass it to `apply` instead
+};
+```
+
+### Data parallelism: `nish/threads`
+
+`parallelMapInto(src, dst, f)` writes `f(src[i])` into `dst[i]`, and
+`parallelReduce(src, f, identity)` folds `src` with `f` — each on as many
+threads as the array is long enough for. `f` is a [function parameter](#function-parameters).
+Importing the module compiles the program with `--threads`; there is nothing
+else to switch on and no thread count to choose. (A plain block: a program
+importing `nish/threads` writes two `.ll` files, so this one is compiled by
+`tests/link/par_map` and `tests/link/par_reduce` instead.)
+
+```ts
+import { parallelMapInto, parallelReduce } from "nish/threads";
+
+const square = (x: f64): f64 => x * x;
+
+export const main = (): i32 => {
+  const src: f64[] = [1.0, 2.0, 3.0];
+  const dst: f64[] = [0.0, 0.0, 0.0];                        // at least src.length, or it panics
+  parallelMapInto(src, dst, square);
+  const total = parallelReduce(dst, (a, b) => a + b, 0.0);   // 14, the same bits on any core count
+  return toI32(total);
+};
+```
+
+- **`f` writes nothing its caller can see.** No field or element store
+  through its argument and no `console.log` — each is refused at the call,
+  naming the write. Reading is fine; so are a bounds check, an integer
+  division and `panic`.
+- **What `f` allocates is freed after every element.** A string, array or
+  object built on the way to the result compiles, with performance warning
+  NL9012: each element pays for building it and for the release. Storing an
+  allocation into another object (NL2352) and touching `Arena` (NL2351) are
+  refused, because either would make that release unsound.
+- **The result is a number, a `boolean` or an enum.** A string or an object
+  made on another thread would be freed with it.
+- **`dst` may not be reachable from an element of `src`**: mapping `Row[]` into
+  `f64[]` is refused when `Row` holds an `f64[]`, because it could be `dst`.
+- **A reduce's `f` is associative and `identity` is its identity** — `0` for
+  `+`, `1` for `*`. The array is folded in fixed blocks and the blocks combined
+  in order, so `-` or a wrong identity is refused when `f` is an arrow of one
+  operator; a named function is trusted.
+- A short array runs on the calling thread at the cost of the loop, so there
+  is no reason to guard a call by size. How short is sized from what `f`
+  costs: a cheap body is divided only past about a million elements, one with
+  a loop far sooner.
+
+```ts nish:err NL2350
+import { parallelReduce } from "nish/threads";
+
+export const main = (): i32 => parallelReduce([1, 2, 3], (a, b) => a + b, 1);   // `+` folds from 0
+```
+
 ### Calling C
 
 `declare function name(params): T;` declares a C function this program calls but
@@ -837,6 +955,11 @@ export const main = (): i32 => {
   annotation must match **exactly**. `const` freezes the binding, not the
   contents: `xs[0] = 1` and `xs.push(1)` on a `const xs` are fine.
 - `var` is forbidden. Destructuring is not supported.
+- **Semicolons are optional**, where TypeScript would insert one: at a line
+  break, before `}` and at the end of the file. It is TypeScript's rule, so a
+  line starting with `(` or `[` continues the one before it, and `return`
+  followed by a line break returns nothing. Here, the value left on the next
+  line is an unreachable-code error rather than a silent bug.
 - `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
@@ -889,8 +1012,8 @@ export const main = (): i32 => {
 - `++` / `--` work on **numeric mutable locals only**, not fields or elements.
 - Compound assignment `+= -= *= /= %=` requires a numeric target (so `+=` never
   concatenates strings); the bitwise forms need an integer target.
-- **Forbidden**: `,` `??` `?.` `in` `instanceof` `typeof` `delete` `void expr`
-  `==` `!=` `**` unary `+`.
+- **Forbidden**: `,` `?.` `in` `instanceof` `typeof` `delete` `void expr`
+  `==` `!=` `**` unary `+`, and `??` on anything but a `Map.get` result.
 - Element access `a[i]` needs an array and a numeric index, and is
   bounds-checked (negative indices fail too). String-keyed access is forbidden.
   The check comes off where the compiler proves the index in range — a loop
@@ -956,6 +1079,125 @@ bytes, no `.`/`..`), `spawnSync(argv)`, `spawnSyncTo(argv, outPath, errPath)`,
 **Arena.** `Arena.mark()`, `Arena.release(m)`, `Arena.reset()`, `Arena.used()`
 — see below.
 
+### Map and Set
+
+`Map<K, V>` and `Set<T>` are global, as in JavaScript: no import, insertion
+order, SameValueZero keys (`-0` is `+0`, `NaN` finds `NaN`). What they have is
+exactly `size` (a read-only `number`), `get(k)`, `set(k, v)` / `add(x)` (both
+answer the receiver, so they chain), `has(k)`, `delete(k)` (answers whether it
+was there) and `clear()`, and `keys()` / `values()` as the iterable of a
+`for...of` and nowhere else. `entries` and `forEach` are refused by name.
+
+```ts nish:ok-body
+const seen = new Set<string>();
+const counts: Map<string, i32> = new Map();
+seen.add("a").add("b").add("a");
+counts.set("a", 1).set("b", 2);
+counts.delete("b");
+console.log(`${seen.size} ${counts.size} ${seen.has("b")}`);
+```
+
+- Write the type arguments on `new`, or annotate the declaration and write
+  `new Map()`. `new Map(entries)` and `new Set(array)` are refused: start empty
+  and `set` / `add` in a loop.
+- A key is a string, any number type, a `boolean`, an enum or a class instance
+  (by identity). An interface, an array, a nullable type or a `Result` is not a
+  key; a value is anything but `void` or an interface.
+- A module that declares its own `Map` or `Set` keeps it, but then no other
+  module of the program may name the global one.
+
+`m.get(k)` is `V | undefined`, as under `tsc`, and it is read in exactly one of
+three ways: a default with `??`, a `const` tested with `!== undefined` (or
+`=== undefined` and an early `return`), or a bare test. Each is one probe.
+
+```ts nish:ok-body
+const counts = new Map<string, i32>();
+for (const w of ["a", "b", "a"]) {
+  counts.set(w, (counts.get(w) ?? 0) + 1);
+}
+const a = counts.get("a");
+if (a !== undefined) {
+  console.log(`${a} ${counts.get("z") === undefined}`);   // 2 true
+}
+```
+
+- Anywhere else — a `let`, an argument, a `return`, a field or element, a
+  template hole, an arithmetic operand, the default of another `??`, a `const`
+  annotated `i32` — the maybe is refused with a message naming the place.
+  Default it with `??` first: `m.get(a) ?? (m.get(b) ?? 0)`.
+- The only spelling of the type is `const a: i32 | undefined = m.get(k)`.
+- `??` does not mix with `||` or `&&` without parentheses, and its default must
+  be the value type. For a `Map<K, Node | null>` it replaces a stored `null`
+  too, but the result is still `Node | null`.
+
+```ts nish:err-body NL2361
+const m = new Map<string, i32>();
+let v = m.get("a");
+```
+
+Walk a map with `for (const k of m.keys())` or `for (const v of m.values())`,
+and a set with `for (const x of s)`: insertion order, deleted keys skipped. You
+may `set`, `delete` or `clear` the table inside the walk and get exactly what
+JavaScript gives (a new key is visited later in the same walk; a key deleted
+before it is reached is not).
+
+```ts nish:ok-body
+const ages = new Map<string, i32>();
+ages.set("ada", 36).set("alan", 41);
+ages.delete("alan");
+ages.set("grace", 85);
+let total = 0;
+for (const name of ages.keys()) {
+  console.log(name);                     // ada, then grace
+}
+for (const age of ages.values()) {
+  total += age;
+}
+console.log(`${total}`);                 // 121
+```
+
+- An iterator is not a value: `keys()` / `values()` stored, passed, returned or
+  spread are refused. Pass the map itself and walk it where it is used.
+- `for (const e of m)` over a `Map` itself is refused, because it would need
+  `[key, value]` destructuring: walk `m.keys()` and call `m.get(k)`.
+
+```ts nish:err-body NL2375
+const m = new Map<string, i32>();
+for (const e of m) {
+}
+```
+
+Asking about one key twice costs one probe when the second call writes
+through the first: `m.set(k, E)` whose `E` reads `m.get(k)` or `m.has(k)`
+once, and `if (m.has(k)) { m.set(k, E); … }`, `if (!m.has(k)) { m.set(k, E); … }`
+or `if (!s.has(x)) { s.add(x); … }` with the write first in the branch. The
+receiver and key must be a local, a parameter or a `this.<field>` path (the key
+may be a literal), spelled the same in both calls, and nothing in between may
+call anything, allocate (`new`, a literal array or object, a template, a
+string `+`) or assign. Anything else still compiles, as one probe per call.
+`nish/map` adds `getOrInsert(m, k, v)` — the value of `k`, or `v` after
+inserting it — and `reserve(m, n)`, which sizes the table for `n` entries; both
+are one module with the program and run unchanged under Node.
+
+```ts nish:ok
+import { getOrInsert, reserve } from "nish/map";
+
+export const main = (): i32 => {
+  const words = ["to", "be", "or", "not", "to", "be"];
+  const counts = new Map<string, i32>();
+  reserve(counts, words.length);
+  for (const w of words) {
+    counts.set(w, (counts.get(w) ?? 0) + 1);   // one probe per word
+  }
+  const first = new Map<string, i32>();
+  for (let i = 0; i < words.length; i++) {
+    getOrInsert(first, words[i], i);           // one probe; inserts only the first time
+  }
+  console.log(`${counts.get("to") ?? 0} ${first.get("be") ?? -1}`);   // 2 1
+  return 0;
+};
+```
+
 ## Memory
 
 There is **no garbage collector and no `free`**, and nothing about this changes
@@ -1017,8 +1259,9 @@ and return `Pair<A, B>`: an object literal `{ first, second }` at the return,
 exactly as above. It is for returning two values, not storing them — a struct
 kept in an array or a field wants named fields.
 
-**A map or a set** — neither exists. Use parallel arrays with a linear scan, or
-an array indexed by a small integer key, and write the lookup out.
+**A map or a set** — the global `Map` and `Set` ([Map and Set](#map-and-set)).
+Read a value with `m.get(k) ?? d`, and keep the keys in an array beside it when
+you need to walk them, since there is no iteration yet.
 
 **Shared behaviour over several shapes** — there is no inheritance and no
 dispatch. Give each class the interface's fields **first**, `implements` it,
@@ -1064,8 +1307,8 @@ Run it. `nish file.ts --json` is one command and it is the only proof.
    in an object-literal property or a method argument expecting a width?
 6. Is every `Result` read, and is every `.value` behind an `isOk()`?
 7. Is every nullable narrowed with `!== null` before it is touched?
-8. Did you use `throw`, `try`, `any`, `undefined`, `?.`, `??`, a cast, a
-   callback, a generic *alias*, or `extends`?
+8. Did you use `throw`, `try`, `any`, `undefined` or `??` (outside `Map.get`), `?.`, a cast, a
+   stored or returned callback, a generic *alias*, or `extends`?
 9. If you are adding to this repository: `npm run check` and `npm test` green,
    and a new construct ships a golden `.ll`, an `llvm-as` pass, a native round
    trip, a negative test, its `LANGUAGE.md` rule and cookbook entry, and a

package/docs/INSTALL.md

@@ -234,12 +234,13 @@ routes are
 If you need one of these to be a first-class install, that is the conversation
 to have on the issue tracker rather than a workaround to discover here.
 
-**Nothing is published to the registry yet.** The installer is built and
-tested, and what is left is a person publishing a release under it, which
-[docs/wp12-release.md](wp12-release.md#release-procedure) step 4 is about.
-Until that happens, install from a release.
+**On the registry from 0.10.0.** Every release publishes the main package and
+its platform packages to npm from `release.yml`, by trusted publishing
+([docs/wp12-release.md](wp12-release.md#release-procedure) step 4), so
+`npm install -g @amritk/nish` is the whole install. The rest of this section is
+for a machine that cannot reach the registry, or a release before 0.10.0.
 
-From a release tarball on GitHub — the same package `npm publish` would upload,
+From a release tarball on GitHub — the same package `npm publish` uploads,
 carried by the release instead of the registry. The `Release` workflow attaches
 the npm tarball to the release it builds for a `v*` tag. `npm pack` names it
 after `package.json#name`, so it is `amritk-nish-<version>.tgz` from 0.4.0 on
@@ -445,6 +446,21 @@ Other build profiles: `--profile size` (smallest binary), `--profile debug`
 (no optimisation, symbols kept). Run `nish --help` for every flag, and
 see the [README](../README.md) for the language subset.
 
+To use a program as a script rather than keep the binary, run it:
+
+```bash
+nish run hello.ts
+# hello from Nish
+```
+
+`nish run [options] <file.ts> [args ...]` compiles the file, links it into
+`$XDG_CACHE_HOME/nish/run` (or `~/.cache/nish/run`) when that program has not
+been linked before, and starts it with the arguments after the file. The first
+run of a new edit pays for one link, and later runs start the cached binary.
+It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set,
+and refuses the run without them rather than keep a binary in a shared
+directory.
+
 ## 4. Exit codes
 
 | Code | Meaning |
@@ -453,6 +469,7 @@ see the [README](../README.md) for the language subset.
 | 1 | the program was rejected: compile error (`file:line:col: error: ...`), missing input file, or an `-o` layout that does not fit the module count |
 | 2 | usage error: unknown flag, missing argument, no input files |
 | 3 | toolchain error: `--link` found no `clang` (`CC` overrides), or `scripts/build.sh` failed (its output is shown; the `.ll` files are still written) — or the `nish` command found no prebuilt compiler for this platform, or one that would not start. Under `--json` all of these are one `NL0002` object |
+| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set it answers 3 |
 | 70 | internal compiler error: an unexpected exception. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; `NISH_DEBUG=1` prints the stack trace |
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Nish: an ahead-of-time compiler from a static subset of TypeScript to LLVM IR",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "!scripts/arrow-verify.mjs",
     "!scripts/arrowify.mjs",
     "!scripts/fetch-seed.sh",
+    "!scripts/check-filenames.mjs",
     "!scripts/check-pr-body.mjs",
     "!scripts/check-pr-body.test.mjs",
     "!scripts/changelog-gen.test.mjs",
@@ -45,7 +46,7 @@
     "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": "biome check --formatter-enabled=false .",
+    "lint": "node scripts/check-filenames.mjs --advisory && biome check --formatter-enabled=false .",
     "format": "biome format --write .",
     "prepublishOnly": "npm run check && npm test",
     "changelog": "node scripts/changelog-gen.mjs"
@@ -74,10 +75,10 @@
     "nish"
   ],
   "optionalDependencies": {
-    "@amritk/nish-x86_64-linux": "0.10.0",
-    "@amritk/nish-aarch64-linux": "0.10.0",
-    "@amritk/nish-aarch64-darwin": "0.10.0",
-    "@amritk/nish-x86_64-darwin": "0.10.0"
+    "@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"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",

package/runtime/LICENSE-ryu

@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/runtime/nish.d.ts

@@ -25,6 +25,17 @@
  * So a program that `tsc` accepts may still be rejected by `nish`; the
  * reverse should never happen, and a case where it does is a bug in this file.
  * `docs/LANGUAGE.md` is the normative description.
+ *
+ * **`Map` and `Set` are not declared here**, although `nish` has them as
+ * globals: the `"lib": ["ES2022"]` a program is checked against already
+ * declares JavaScript's, and a second declaration would clash with it.
+ * `nish`'s are that surface less what it defers — no `entries`, no `forEach`,
+ * no `for...of` over a `Map` itself — with `keys()` and `values()` admitted
+ * only as the iterable of a `for...of`, and `get`'s `V | undefined` only as a
+ * `const`'s initialiser, the left of `??` or an operand of `=== undefined`,
+ * none of which `tsc` can know (docs/LANGUAGE.md -> `Map` and `Set`).
+ * `nish/map`'s `reserve` and `getOrInsert` are not declared here either: they
+ * are ordinary source, `std/map.ts`, which `tsconfig.json` maps `nish/*` to.
  */
 
 // ---- Numeric widths (docs/LANGUAGE.md -> Types) ------------------------------

package/runtime/nish.h

@@ -179,7 +179,15 @@ void nish_append_file(const nish_str *path, const nish_str *data);
  * `push` that grows it copies the elements into the arena and leaves your
  * buffer behind; the callee must not retain the pointer beyond the call.
  * A returned array lives in the arena (valid until the next reset/release):
- * copy `len` elements out of `data` before recycling. */
+ * copy `len` elements out of `data` before recycling.
+ *
+ * An array field stored inside its object (`self/inline_arrays.ts`) is this
+ * header followed by its `K` slots, `struct { nish_array h; T slots[K]; }`
+ * with `h.data == (char *)slots` and `h.cap == K`; `self/runtime.ts`'s
+ * `ARRAY_TYPE` and `self/structs.ts`'s `INLINE_HEADER_BYTES` are the same 24
+ * bytes, and `tests/layout/inline_array.c` holds the three to it. It only
+ * happens where no header, `.d.ts` or N-API shim describes the class, so a
+ * host that includes a generated header never meets one. */
 typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array;
 /* A fresh arena array of `len` uninitialised elements (`len == cap`), for a
  * host that wants the runtime to own the storage (the wasm loader does).

package/runtime/nish.mjs

@@ -54,6 +54,7 @@
  * harness already uses, so the two cannot drift apart: a semantic fixed there
  * is fixed here in the same commit.
  */
+import { registerHooks } from "node:module";
 import * as shim from "./shim.mjs";
 
 /** Install `value` as a global unless the program declared its own. */
@@ -141,3 +142,15 @@ provide("Arena", {
   reset: shim.arenaReset,
   used: shim.arenaUsed,
 });
+
+// The standard library. A program imports it as `nish/<module>`, which the
+// compiler resolves to `std/<module>.ts` beside itself; this does the same for
+// Node, relative to this file rather than to the program, so the same
+// specifier works from any directory. Only the `nish/` package is answered
+// here, and every other specifier goes to Node as it was written.
+registerHooks({
+  resolve: (specifier, context, next) =>
+    specifier.startsWith("nish/")
+      ? next(new URL(`../std/${specifier.slice("nish/".length)}.ts`, import.meta.url).href, context)
+      : next(specifier, context),
+});

package/runtime/runtime.c

@@ -277,6 +277,13 @@ nish_str *nish_str_from_u64(uint64_t v) { return str_from_digits(v, 0); }
 
 /* ---- Shortest round-trip digits (Ryu)
 
+   Adapted from Ryu (https://github.com/ulfjack/ryu), ryu/d2s.c and
+   ryu/common.h. Copyright 2018 Ulf Adams. Used under the Boost Software
+   License, Version 1.0; see runtime/LICENSE-ryu. The code from here to the end
+   of `nish_shortest_digits` follows upstream's `d2d()` and its helpers, which
+   is why it keeps their names, constants and comments; the two tables are
+   regenerated by scripts/gen-pow5-tables.py rather than copied.
+
    `String(x)` in JavaScript prints the *fewest* digits that read back as the
    same double, and the language promises that spelling. Reaching it by asking
    snprintf for k digits and strtod whether they round-trip -- which is what
@@ -1079,7 +1086,9 @@ nish_str *nish_str_from_f64(double v) {
   return nish_str_new(out, o - out);
 }
 
-/* ---- Math.random: xorshift64*, seeded lazily from time and pid.
+/* ---- Math.random: xorshift64*, seeded lazily from time and pid. The shifts
+   and the multiplier are Marsaglia's and Vigna's published constants, which
+   are public domain.
    Thread-local under -DNISH_THREADS (WP20 T0 §3.2): a shared seed word is a
    race, and a per-thread one also makes each worker's stream its own rather
    than an interleaving of everyone's. Two threads that start in the same