@amritk/nish 0.12.0 → 0.13.0

package/README.md

@@ -2,6 +2,8 @@
 
 # Nish
 
+**Native Instruction Static Host AKA Turbo Typescript. A fast subset of typescript without the encumbrance of javascript.**
+
 **An ahead-of-time compiler for a strictly static subset of TypeScript — LLVM IR in the middle, native binaries at the end. No interpreter, no garbage collector, nothing to ship beside the executable.**
 
 ![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square)
@@ -22,12 +24,12 @@ Nish parses source with its own lexer and parser, rejects everything dynamic
 (`any`, prototypes, `eval`, exceptions, a garbage collector), and emits
 textual LLVM IR (`.ll`). LLVM's own toolchain (`clang` / `llc`) then optimises
 and produces native binaries for x86_64, ARM64, or WebAssembly. The compiler
-is itself written in Nish, in `self/`, and ships as a native binary with no
+is itself written in Nish, in `src/`, and ships as a native binary with no
 runtime dependency.
 
 ```
 TypeScript source ──▶ AST ──▶ validator + checker ──▶ LLVM IR (.ll) ──▶ clang/llc ──▶ native binary
-              (self/parser.ts)  (self/checker.ts)      (self/emit*.ts)         + runtime/runtime.c + runtime_os.c
+              (src/parser.ts)  (src/checker.ts)      (src/emit*.ts)         + runtime/runtime.c + runtime-os.c
 ```
 
 If it compiles, every value has one fixed, known memory layout; binaries are
@@ -73,7 +75,7 @@ curl -fsSL https://raw.githubusercontent.com/amritk/nish/main/install.sh | sh
 > `bash scripts/fetch-seed.sh`, `npm run build`, then `build/nish ...` wherever this README says `nish`.
 > The build is a bootstrap: the previous release's `nish` (the seed, fetched
 > by `scripts/fetch-seed.sh`, or named with `NISH_BOOTSTRAP=<path>`) compiles
-> `self/`, and that compiler compiles `self/` again into `build/nish`.
+> `src/`, and that compiler compiles `src/` again into `build/nish`.
 
 `hello.ts`:
 
@@ -210,7 +212,7 @@ dies with its frame, Rust refuses to compile it, Go falls back to the garbage
 collector, and Zig hands the question back to you and an allocator. Nish
 leaves the value in the arena, where it stays until `main` returns.
 
-So [`self/escape.ts`](self/escape.ts) and the whole-program fact
+So [`src/escape.ts`](src/escape.ts) and the whole-program fact
 fixpoint are optimisations and nothing else: a refusal costs memory and never
 correctness, and no program is rejected for a lifetime reason. The compiler
 says so out loud where the cost is real: assigning an allocation to a local
@@ -345,7 +347,7 @@ safe. `-o`, `--link`, `--target`, the `--emit-*` sidecars and
 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`
+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
 it), or step by step with `llvm-as`, `llc -O2 -filetype=obj`, and
@@ -363,7 +365,7 @@ with `--target aarch64-unknown-linux-gnu` / `wasm32-wasi` plus
 Rust-class output is the goal: no GC, no embedded engine, aliasing and
 purity facts handed to LLVM up front, and a link step that strips everything
 unused. `examples/add.ts` + `examples/main.c` + the two runtime translation units
-(`runtime/runtime.c` and `runtime/runtime_os.c`), x86_64 Linux, glibc
+(`runtime/runtime.c` and `runtime/runtime-os.c`), x86_64 Linux, glibc
 dynamically linked (`npm run size-report`):
 
 | Profile | Bytes | What it does |
@@ -380,7 +382,7 @@ core does not grow every time the language reaches further into the operating
 system: `runtime.c` is the 3,480 bytes every program touches (one chunked bump
 arena with O(1) reset and mark/release, strings, JavaScript-exact number
 formatting, string parsing, `Math.random`, `process.argv`, array growth, the
-panic paths), and `runtime_os.c` the 1,190 bytes that wrap a system call (exit,
+panic paths), and `runtime-os.c` the 1,190 bytes that wrap a system call (exit,
 files, directories, subprocesses, the environment, the clock) — see
 [docs/wp7-runtime.md](docs/wp7-runtime.md#runtime-additions-and-budget) for both
 budgets and the reasoning. `Math.*` calls are LLVM intrinsics, so pure functions
@@ -422,7 +424,7 @@ The supported direction is Node importing Nish:
 
 - `scripts/build.sh --profile wasm` produces a module `WebAssembly.instantiate`
   loads directly (`examples/node-host.mjs`); exports use the plain C ABI.
-  Add `runtime/runtime_wasm.c` (arena + arrays, no libc) when a function
+  Add `runtime/runtime-wasm.c` (arena + arrays, no libc) when a function
   takes or returns an array.
 - `--emit-napi` + `scripts/build.sh --profile napi` build a `.node` addon
   with argument type checks (`examples/node-addon.mjs`).
@@ -446,11 +448,11 @@ Details: [docs/wp8-interop.md](docs/wp8-interop.md).
 
 ## The compiler in a browser
 
-`self/` is an Nish program, so the compiler compiles itself to
+`src/` is an Nish program, so the compiler compiles itself to
 WebAssembly like any other one:
 
 ```bash
-nish self/compile.ts --link web/nish.wasm --profile wasi
+nish src/compile.ts --link web/nish.wasm --profile wasi
 node web/compile.mjs web/nish.wasm examples/add.ts     # the IR, from a Web Worker
 ```
 
@@ -464,17 +466,17 @@ refused there. [web/README.md](web/README.md) has the rest.
 
 ## Self-hosting
 
-`self/` is the compiler, and the only one: lexer, parser, checker and emitter,
+`src/` is the compiler, and the only one: lexer, parser, checker and emitter,
 written in Nish, with no `typescript` package underneath. It compiles its own
 source to a fixed point:
 
 ```
-IR(stage1, self/) == IR(stage2, self/)     byte for byte, and stage3 == stage2
+IR(stage1, src/) == IR(stage2, src/)     byte for byte, and stage3 == stage2
 ```
 
 The chain starts from a seed, the previous release's `nish` binary, the way
-Rust and Go build themselves: stage1 is `self/` built by the seed, stage2 is
-`self/` built by stage1 and is what gets installed, and stage3, built by
+Rust and Go build themselves: stage1 is `src/` built by the seed, stage2 is
+`src/` built by stage1 and is what gets installed, and stage3, built by
 stage2, has to reproduce stage2 file for file. `scripts/bootstrap.sh --verify`
 asserts both equalities, and `npm test` re-proves them on every run. Compiling
 the whole compiler costs it **91 ms and 86 MB**; the TypeScript compiler it
@@ -486,15 +488,15 @@ npm run build                       # seed -> stage1 -> stage2 = build/nish
 build/nish hello.ts --link hello    # -o, --link, --profile, its own directories
 ```
 
-Because the seed is the last release, `self/` may only *use* in its own
-source what that release compiles. A new construct is implemented in `self/`
-and becomes usable inside `self/` from the next release on — the rolling
+Because the seed is the last release, `src/` may only *use* in its own
+source what that release compiles. A new construct is implemented in `src/`
+and becomes usable inside `src/` from the next release on — the rolling
 freeze CI's `bootstrap` job checks. Until R6 there was a second compiler, the
-TypeScript one in `src/`, which seeded every bootstrap and served as the
-oracle each `self/` phase was compared against; it was deleted once the
+TypeScript one, stage0, which seeded every bootstrap and served as the
+oracle each phase of `src/` was compared against; it was deleted once the
 self-hosted compiler did everything it did
 ([wp19](docs/wp19-stage0-retirement.md)).
-Details, and the subset `self/` is written in, are in
+Details, and the subset `src/` is written in, are in
 [docs/wp14-selfhost.md](docs/wp14-selfhost.md).
 
 ---
@@ -511,7 +513,7 @@ and the IR any of them lowers to are all still free to change.
 | M2 "Data" | classes and interfaces, arrays, runtime and intrinsics | done |
 | M3 "Rust parity" | interop, memory strategy (stack allocation, arena scopes, `T \| null`), benchmarks with `--target`/`--nsw`/PGO, differential testing against Node | done |
 | M4 "1.0" | frozen language reference, tagged release | next |
-| M5 "Self-hosting" | `self/`: the compiler, written in Nish, compiling itself | done |
+| M5 "Self-hosting" | `src/`: the compiler, written in Nish, compiling itself | done |
 
 Not in the language yet, in the order they are likely to land: optional
 reference counting for objects that must outlive an arena reset, and dynamic
@@ -542,7 +544,7 @@ node tests/run.js locals # only cases whose name contains "locals"
 npm run test:update      # write missing .ll goldens for new cases
 npm run test:diff        # every whole program natively and under Node (runtime/shim.mjs), compared byte for byte
 node tests/differential/fuzz.js --stage1 --count 200   # random integer programs, the released seed's IR against HEAD's; prints the seed
-npm run check            # tsc --noEmit: an ambient type-check of self/, std/ and tests/nish/
+npm run check            # tsc --noEmit: an ambient type-check of src/, std/ and tests/nish/
 npm run lint             # Biome style lint (advisory, never a compile gate)
 npm run smoke            # build and run every example with a main
 scripts/bootstrap.sh --verify   # the whole chain, with IR(stage1) == IR(stage2) and stage3 == stage2 asserted
@@ -555,7 +557,7 @@ the add-a-construct checklist, ABI guard tests) and the conventions in
 [docs/MASTER_PLAN.md §7](docs/MASTER_PLAN.md#7-conventions-for-every-agent):
 every construct ships with a golden `.ll`, an `llvm-as` pass, a native round
 trip, a negative test, and its LANGUAGE.md and cookbook entries; no attribute
-without a proof; layout changes touch `self/runtime.ts` and `runtime/runtime.c` together.
+without a proof; layout changes touch `src/runtime.ts` and `runtime/runtime.c` together.
 CI runs the suite on Ubuntu and macOS with LLVM 18
 ([docs/wp10-ci.md](docs/wp10-ci.md)). The documentation index is
 [docs/README.md](docs/README.md). Coding guidelines for contributors and

package/bin/launcher.js

@@ -16,12 +16,12 @@
  *
  * **A platform with no prebuilt binary is now an error rather than a fallback,
  * and that is a decision rather than an oversight.** Until 0.6.0 this file
- * imported `dist/index.js` -- the TypeScript compiler built from `src/` -- so
+ * imported `dist/index.js` -- the TypeScript compiler built from stage0's `src/` -- so
  * musl, FreeBSD and 32-bit anything got a working compiler that happened to be
- * slower. `src/` was deleted in R6 (`docs/wp19-stage0-retirement.md`), so there
+ * slower. stage0's `src/` was deleted in R6 (`docs/wp19-stage0-retirement.md`), so there
  * is no second compiler in the package to reach for, and the honest answer is
  * the one below: name the platforms a release carries, say there is nothing to
- * fall back to, and exit non-zero. The alternative -- shipping `self/` and
+ * fall back to, and exit non-zero. The alternative -- shipping `src/` and
  * bootstrapping on the user's machine -- was priced in wp12 and turned down,
  * and quietly doing nothing was never on the table: a command that exits 0
  * having compiled nothing is worse than one that refuses.
@@ -29,14 +29,14 @@
  * `bin/` rather than the old `dist/` for the same reason: the command may not
  * be a build artifact of the compiler it installs.
  */
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { assetFor, noCompilerMessage, platformPackageName } from "./packaging.js";
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import { createRequire } from "node:module"
+import { assetFor, noCompilerMessage, platformPackageName } from "./packaging.js"
 
 /** Package root: bin/launcher.js -> `..`, the directory `package.json` sits in. */
-const PKG_ROOT = path.resolve(import.meta.dirname, "..");
+const PKG_ROOT = path.resolve(import.meta.dirname, "..")
 
 /**
  * Exit 3, the toolchain code.
@@ -54,17 +54,17 @@ const PKG_ROOT = path.resolve(import.meta.dirname, "..");
  * below is machine-readable. `scripts/postinstall.mjs`'s generated shim answers
  * 3 for its own version of this, so all three spell one situation the same way.
  */
-const NO_COMPILER = 3;
+const NO_COMPILER = 3
 
 /** This package's own name, or `null` when its `package.json` cannot be read. */
 const packageName = () => {
   try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
-    return typeof pkg.name === "string" ? pkg.name : null;
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"))
+    return typeof pkg.name === "string" ? pkg.name : null
   } catch {
-    return null;
+    return null
   }
-};
+}
 
 /**
  * Whether this invocation asked for machine-readable output.
@@ -75,7 +75,7 @@ const packageName = () => {
  * failure the `--json` contract covers (AGENTS.md, "Machine-readable
  * surfaces").
  */
-const wantsJson = () => process.argv.slice(2).includes("--json");
+const wantsJson = () => process.argv.slice(2).includes("--json")
 
 /**
  * Write and exit, without losing what was written.
@@ -87,9 +87,9 @@ const wantsJson = () => process.argv.slice(2).includes("--json");
  * there is nothing after it to run.
  */
 const writeAndExit = (stream, text, status) => {
-  stream.write(text);
-  process.exitCode = status;
-};
+  stream.write(text)
+  process.exitCode = status
+}
 
 /**
  * Where the native compiler for this machine is, or `null` when this machine
@@ -103,26 +103,30 @@ const writeAndExit = (stream, text, status) => {
  * `build.sh`, the C runtime and the standard library one level up from itself
  * exactly as it does when unpacked by hand.
  */
-const nativeCompiler = (asset) => {
-  const name = packageName();
-  if (name === null) return null;
+const nativeCompiler = (assetName) => {
+  const name = packageName()
+  if (name === null) {
+    return null
+  }
   try {
-    const manifest = createRequire(import.meta.url).resolve(`${platformPackageName(name, asset)}/package.json`);
-    const binary = path.join(path.dirname(manifest), "bin", "nish");
-    return fs.existsSync(binary) ? binary : null;
+    const manifest = createRequire(import.meta.url).resolve(
+      `${platformPackageName(name, assetName)}/package.json`
+    )
+    const binary = path.join(path.dirname(manifest), "bin", "nish")
+    return fs.existsSync(binary) ? binary : null
   } catch {
     // Not installed. On a supported platform that is a partial install; on an
     // unsupported one npm skipped the entry on purpose. `refuse` tells the two
     // apart, because the advice differs.
-    return null;
+    return null
   }
-};
+}
 
 /**
  * Say why there is no compiler to run, and stop.
  *
  * Under `--json` that is one object on stdout and **nothing on stderr**, which
- * is the shape `self/compile.ts`'s own `reportToolchainFailure` uses for the
+ * is the shape `src/compile.ts`'s own `reportToolchainFailure` uses for the
  * same code: stdout carries objects and nothing else, so a tool reading it does
  * not have to strip a human report out of the stream. Otherwise it is the
  * report on stderr. Either way the status is the same.
@@ -137,50 +141,50 @@ const refuse = (unstartable) => {
     // none: it sends the user to install something that does not exist.
     packageName: packageName(),
     unstartable,
-  });
+  })
   if (wantsJson()) {
     writeAndExit(
       process.stdout,
       `${JSON.stringify({ severity: "error", code: why.code, message: why.summary })}\n`,
       NO_COMPILER
-    );
+    )
   } else {
-    writeAndExit(process.stderr, why.report, NO_COMPILER);
+    writeAndExit(process.stderr, why.report, NO_COMPILER)
   }
-};
+}
 
-const asset = assetFor(process.platform, process.arch);
+const asset = assetFor(process.platform, process.arch)
 // No binary for this machine, and none coming: musl, FreeBSD, 32-bit anything.
 // `refuse` sets an exit code rather than exiting, so each of these returns
 // before the next line runs: the sequence below is written as a chain for that
 // reason and `process.exitCode` is what carries the status out.
 if (asset === null) {
-  refuse(null);
+  refuse(null)
 } else {
-  const binary = nativeCompiler(asset);
+  const binary = nativeCompiler(asset)
   if (binary === null) {
     // A binary exists for this platform and this install does not have it.
-    refuse(null);
+    refuse(null)
   } else {
-    handOver(binary);
+    handOver(binary)
   }
 }
 
 /** Run the native compiler and give the caller back exactly what it answered. */
 function handOver(binary) {
-  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" })
   if (result.error !== undefined && result.error !== null) {
     // Installed and will not start -- a broken or partial install rather than an
     // unsupported platform. There is nothing to fall back to, so this is a
     // refusal with the reason in it rather than a warning above a slower compile.
-    refuse({ binary, reason: result.error.message });
-    } else if (result.signal !== null) {
+    refuse({ binary, reason: result.error.message })
+  } else if (result.signal !== null) {
     // Re-raise rather than translating to an exit code, so that a crash or an
     // interrupt reaches the shell as the signal it was. `process.exitCode`
     // cannot express one, and a wrapper that turned SIGINT into exit 130 would
     // make `nish` the one command in a pipeline that did.
-    process.kill(process.pid, result.signal);
+    process.kill(process.pid, result.signal)
   } else {
-    process.exitCode = result.status ?? 0;
+    process.exitCode = result.status ?? 0
   }
 }

package/bin/packaging.js

@@ -21,11 +21,11 @@
  * trusting the two lists to stay equal.
  *
  * **This is plain JavaScript under `bin/`, and that is deliberate.** It used
- * to be `src/packaging.ts`, compiled into `dist/` by `tsc` -- which made the
+ * to be stage0's `src/packaging.ts`, compiled into `dist/` by `tsc` -- which made the
  * command a build artifact of the compiler it is supposed to install. `bin/`
  * is what the tarball carries and what `bin.nish` points into, so the launcher
  * and its platform table now live where they ship, need no build step, and
- * survived the deletion of `src/` (`docs/wp19-stage0-retirement.md` R6). The
+ * survived the deletion of stage0's `src/` (`docs/wp19-stage0-retirement.md` R6). The
  * types they lose are not much of a loss for two string maps; what they gain is
  * that `npm pack` ships the same bytes this repository runs.
  */
@@ -40,7 +40,7 @@
 const ARCH_BY_CPU = {
   x64: "x86_64",
   arm64: "aarch64",
-};
+}
 
 /**
  * The operating-system half. It is an identity map today, because node's
@@ -52,7 +52,7 @@ const ARCH_BY_CPU = {
 const OS_BY_PLATFORM = {
   linux: "linux",
   darwin: "darwin",
-};
+}
 
 /**
  * Every asset a release actually attaches, sorted, in `seed-targets.json`'s
@@ -68,7 +68,7 @@ const OS_BY_PLATFORM = {
  * compares the two, so a literal is exactly as gated as a derivation and says
  * only what is true.
  */
-export const SUPPORTED_ASSETS = ["aarch64-darwin", "aarch64-linux", "x86_64-darwin", "x86_64-linux"];
+export const SUPPORTED_ASSETS = ["aarch64-darwin", "aarch64-linux", "x86_64-darwin", "x86_64-linux"]
 
 /**
  * The `asset` for a node platform/arch pair, or `null` when this project
@@ -81,23 +81,29 @@ export const SUPPORTED_ASSETS = ["aarch64-darwin", "aarch64-linux", "x86_64-darw
  * exits non-zero (`docs/wp12-release.md`, "Which compiler the package ships").
  */
 export const assetFor = (platform, arch) => {
-  const os = OS_BY_PLATFORM[platform];
-  const cpu = ARCH_BY_CPU[arch];
-  if (os === undefined || cpu === undefined) return null;
-  return `${cpu}-${os}`;
-};
+  const os = OS_BY_PLATFORM[platform]
+  const cpu = ARCH_BY_CPU[arch]
+  if (os === undefined || cpu === undefined) {
+    return null
+  }
+  return `${cpu}-${os}`
+}
 
 /** The inverse, for the generator and the tests: an `asset` back to npm's pair. */
 export const targetForAsset = (asset) => {
-  const dash = asset.indexOf("-");
-  if (dash < 0) return null;
-  const arch = asset.slice(0, dash);
-  const os = asset.slice(dash + 1);
-  const cpu = Object.keys(ARCH_BY_CPU).find((key) => ARCH_BY_CPU[key] === arch);
-  const platform = Object.keys(OS_BY_PLATFORM).find((key) => OS_BY_PLATFORM[key] === os);
-  if (cpu === undefined || platform === undefined) return null;
-  return { asset, os: platform, cpu };
-};
+  const dash = asset.indexOf("-")
+  if (dash < 0) {
+    return null
+  }
+  const arch = asset.slice(0, dash)
+  const os = asset.slice(dash + 1)
+  const cpu = Object.keys(ARCH_BY_CPU).find((key) => ARCH_BY_CPU[key] === arch)
+  const platform = Object.keys(OS_BY_PLATFORM).find((key) => OS_BY_PLATFORM[key] === os)
+  if (cpu === undefined || platform === undefined) {
+    return null
+  }
+  return { asset, os: platform, cpu }
+}
 
 /**
  * The package holding the binary for one asset, derived from the main
@@ -108,22 +114,22 @@ export const targetForAsset = (asset) => {
  * is scoped -- docs/wp12-release.md "The npm name"), and a list of five literal
  * names would be five places to edit if it ever moves again.
  */
-export const platformPackageName = (packageName, asset) => `${packageName}-${asset}`;
+export const platformPackageName = (packageName, asset) => `${packageName}-${asset}`
 
 /**
  * The diagnostic code every refusal here carries: `NL0002`, the toolchain code.
  *
- * Not a new code, and that is the point. `self/codes.ts` defines `NL0002` as
+ * Not a new code, and that is the point. `src/codes.ts` defines `NL0002` as
  * "the toolchain `--link` needs could not be used (exit 3)", and a prebuilt
  * compiler that is absent or will not start is the same class of failure seen
  * one step earlier: no source position, nothing wrong with the program, and the
  * thing that could not be run is a binary rather than the input. Reusing it
  * keeps the launcher out of the diagnostic registry entirely -- a code minted
- * here would be one `self/codes.ts` mirrors for a message the compiler can
- * never print, and `tests/diagnostic_coverage.js` would then want a case
+ * here would be one `src/codes.ts` mirrors for a message the compiler can
+ * never print, and `tests/diagnostic-coverage.js` would then want a case
  * provoking a rule that does not exist.
  */
-export const NO_COMPILER_CODE = "NL0002";
+export const NO_COMPILER_CODE = "NL0002"
 
 /**
  * Why there is no compiler to run, and what to do about it: the one-line
@@ -160,13 +166,13 @@ export const NO_COMPILER_CODE = "NL0002";
  * refused wants to know whether the list is the whole list. It is.
  */
 export const noCompilerMessage = ({ platform, arch, packageName, unstartable = null }) => {
-  const asset = assetFor(platform, arch);
-  const published = SUPPORTED_ASSETS.join("  ");
+  const asset = assetFor(platform, arch)
+  const published = SUPPORTED_ASSETS.join("  ")
   const preamble =
     "  This package installs a prebuilt native compiler. One is published for:\n" +
     `    ${published}\n\n` +
     "  There is no compiler inside the package to fall back to, and nothing is\n" +
-    "  compiled on your machine on any path.\n";
+    "  compiled on your machine on any path.\n"
   if (asset === null) {
     return {
       code: NO_COMPILER_CODE,
@@ -182,7 +188,7 @@ export const noCompilerMessage = ({ platform, arch, packageName, unstartable = n
         "    NISH_BOOTSTRAP=<a released nish that runs here> scripts/bootstrap.sh\n" +
         "  docs/INSTALL.md has the detail, including what to do when no released\n" +
         "  binary runs on this platform at all.\n",
-    };
+    }
   }
   if (unstartable !== null) {
     return {
@@ -195,14 +201,14 @@ export const noCompilerMessage = ({ platform, arch, packageName, unstartable = n
         `nish: ${unstartable.binary} could not be started (${unstartable.reason})\n\n${preamble}\n` +
         "  That is a broken or partly written install rather than an unsupported\n" +
         "  platform. Reinstall the package, or run `npm rebuild` if the tree moved.\n",
-    };
+    }
   }
   // A `packageName` of `null` means this package's own `package.json` could not
   // be read, which is a broken install and not the moment to guess: naming the
   // wrong package sends the user to install something that does not exist, so
   // the sentence loses the name instead of inventing one.
-  const named = packageName === null ? null : platformPackageName(packageName, asset);
-  const pkg = named === null ? `the platform package for ${asset}` : named;
+  const named = packageName === null ? null : platformPackageName(packageName, asset)
+  const pkg = named === null ? `the platform package for ${asset}` : named
   return {
     code: NO_COMPILER_CODE,
     summary:
@@ -216,5 +222,5 @@ export const noCompilerMessage = ({ platform, arch, packageName, unstartable = n
       "  `--no-optional`, a lockfile without the platform packages, or a registry that\n" +
       "  does not carry them yet. Reinstall the package, or install the pair by hand as\n" +
       "  docs/INSTALL.md shows.\n",
-  };
-};
+  }
+}

package/docs/AI.md

@@ -198,16 +198,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.
-
-```ts nish:err NL2333
-const clamp = (x: integer): i32 => x;
+**`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: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 +343,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 +388,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 +752,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