@amritk/nish 0.12.0 → 0.13.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish",
-  "version": "0.12.0",
+  "version": "0.13.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.13.0",
+    "@amritk/nish-aarch64-linux": "0.13.0",
+    "@amritk/nish-aarch64-darwin": "0.13.0",
+    "@amritk/nish-x86_64-darwin": "0.13.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;
@@ -152,7 +171,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;
 /**

package/runtime/nish.h

@@ -2,10 +2,10 @@
  *
  * Include this from C drivers, N-API shims, or any other host that links the C
  * runtime next to compiled Nish modules. Everything here is a contract shared
- * with `self/runtime.ts` (the IR side) and the implementation, which is
+ * with `src/runtime.ts` (the IR side) and the implementation, which is
  * two translation units: `runtime/runtime.c` holds the core every program
  * touches — the arena, strings, arrays, number formatting, the panics — and
- * `runtime/runtime_os.c` holds everything that wraps a system call: the file
+ * `runtime/runtime-os.c` holds everything that wraps a system call: the file
  * functions, the directory and subprocess calls, `nish_getenv`, the monotonic
  * clock, `nish_platform` / `nish_arch`. They are separate so that each carries
  * its own measured code-size ceiling (docs/wp7-runtime.md, "Runtime additions
@@ -41,7 +41,7 @@ extern "C" {
  * ELF refuses to link that against a non-TLS definition. `scripts/build.sh
  * --threads` passes the macro to every input, which is how `nish --threads
  * --link` keeps the two halves in step. The same definition is in
- * runtime/runtime.c and runtime/runtime_wasm.c. */
+ * runtime/runtime.c and runtime/runtime-wasm.c. */
 #ifdef NISH_THREADS
 #define NISH_TLS _Thread_local
 #else
@@ -73,7 +73,7 @@ typedef struct nish_str {
  * `off` and `cap` are `uint64_t` and not `size_t` because that `i64` is what
  * the inlined fast path bumps and compares on every target: under wasm32 a
  * `size_t` pair would put them at bytes 4 and 8 while compiled code reads 8
- * and 16. runtime.c and runtime_wasm.c static-assert these offsets. */
+ * and 16. runtime.c and runtime-wasm.c static-assert these offsets. */
 struct nish_arena {
   char *buf;
   uint64_t off;
@@ -140,7 +140,7 @@ nish_str *nish_str_from_u64(uint64_t v);
 
 /* Process and file I/O (WP7). `nish_exit` never returns; the file functions
  * print a message to stderr and exit(1) on a fatal error. Everything from here
- * to the end of the clock section below is implemented in runtime_os.c, with
+ * to the end of the clock section below is implemented in runtime-os.c, with
  * `nish_random` and `nish_argv_init` the exceptions: neither asks the operating
  * system anything (the clock only seeds the first, and the entry point hands the
  * second its arguments), so both stay with the core. `nish_random` keeps one seed
@@ -181,11 +181,11 @@ void nish_append_file(const nish_str *path, const nish_str *data);
  * A returned array lives in the arena (valid until the next reset/release):
  * copy `len` elements out of `data` before recycling.
  *
- * An array field stored inside its object (`self/inline_arrays.ts`) is this
+ * An array field stored inside its object (`src/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
+ * with `h.data == (char *)slots` and `h.cap == K`; `src/runtime.ts`'s
+ * `ARRAY_TYPE` and `src/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;
@@ -260,7 +260,7 @@ int32_t nish_spawn(const nish_array *argv);
  * paths must differ: each is opened separately with its own offset, so naming
  * one file twice makes the streams overwrite each other instead of
  * interleaving; capture them apart and concatenate to merge them. One `static`
- * implementation in runtime_os.c backs both spawn builtins, which is what keeps
+ * implementation in runtime-os.c backs both spawn builtins, which is what keeps
  * the argument vector, the wait and the signal convention written once. */
 int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_str *err);
 
@@ -316,7 +316,7 @@ double nish_parse_number(const nish_str *s, int32_t mode);
 /* Checked integer division (Rust semantics): the failed-check path. */
 void nish_panic_div(bool by_zero);
 
-/* ---- Parallel work (WP20 T1 / wp29 stage P1), runtime/runtime_parallel.c ----
+/* ---- Parallel work (WP20 T1 / wp29 stage P1), runtime/runtime-parallel.c ----
  *
  * One region of work, divided. `nish_parallel_range` calls `body(lo, hi, ctx)`
  * once per chunk of a partition of `[0, len)`: contiguous chunks, at most one
@@ -341,6 +341,26 @@ typedef void (*nish_par_body)(int64_t lo, int64_t hi, void *ctx);
 int64_t nish_cpu_count(void);
 void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t grain);
 
+/* ---- A scope's tasks (wp29 stage P2), runtime/runtime-parallel.c ----
+ *
+ * `nish_scope_spawn` files one task under `scope`, an address the caller keeps
+ * alive until it joins: it copies `size` bytes of `payload` and keeps them with
+ * `run` and `finish`, and runs nothing yet. `nish_scope_join` takes every task
+ * filed under `scope`, runs `run(payload)` for each -- the first on the calling
+ * thread and each other on a thread of its own, which frees its arena before it
+ * exits -- waits for all of them, and then calls `finish(payload)` for each on
+ * the calling thread, in the order they were filed. Without `-DNISH_THREADS`,
+ * or when a thread cannot be created, a task runs on the calling thread, so
+ * running short of threads costs speed and never an answer.
+ *
+ * The preconditions are the language's (docs/LANGUAGE.md, "Scoped tasks"):
+ * `run` writes nothing another task or the caller can see, its result is a
+ * scalar it writes into its own payload, and only `finish`, on the calling
+ * thread, stores into memory the caller owns. */
+typedef void (*nish_task_fn)(void *payload);
+void nish_scope_spawn(void *scope, nish_task_fn run, nish_task_fn finish, const void *payload, int64_t size);
+void nish_scope_join(void *scope);
+
 #ifdef __cplusplus
 }
 #endif

package/runtime/nish.mjs

@@ -28,9 +28,9 @@
  *     so is every string offset. ASCII agrees; nothing else does.
  *   - **`a[i]` is unchecked**: out of range is `undefined` here and an exit-1
  *     panic natively. Only a program that indexes out of range can tell.
- *   - **Method dispatch is virtual under Node** and static natively, so an
- *     override reached through a base-typed value differs (LANGUAGE.md,
- *     "Method dispatch is static").
+ *   - **A record put into an array is shared here** and copied natively, and
+ *     `slice`, `new Array<T>(n)` and the typed-array names each differ too;
+ *     the document lists them.
  *   - **`orReturn()` does not propagate.** It throws a marker the rewriter's
  *     `try`/`catch` turns into an early `return`; unmodified there is no
  *     `catch`, so it escapes. `Ok`/`Err`/`isOk`/`isErr`/`value`/`error`/

package/runtime/{runtime_os.c → runtime-os.c}

@@ -319,7 +319,7 @@ nish_str *nish_realpath(const nish_str *path) {
    this file is compiled — a cross build compiles the runtime for the target,
    so the answer is the target's — which is why each is a string in constant
    data handed back by address: no allocation and no load, and `readnone` on
-   the declaration (self/runtime.ts) is a fact rather than a hope. The
+   the declaration (src/runtime.ts) is a fact rather than a hope. The
    spellings are Node's, so a program reads the same answer from this runtime
    and from `runtime/shim.mjs`; anything neither branch names is "unknown",
    which is what `--target host` then refuses. Contracts: nish.h.

package/runtime/{runtime_parallel.c → runtime-parallel.c}

@@ -1,9 +1,9 @@
 /* Nish runtime, the parallel half: how one range of work becomes several
  * threads, and nothing else.
  *
- * A third translation unit rather than a third of `runtime_os.c`, for the
+ * A third translation unit rather than a third of `runtime-os.c`, for the
  * reason that file's header gives for being a second one: a budget should mean
- * one thing. `runtime_os.c` is the syscall wrappers and it had 29 bytes of its
+ * one thing. `runtime-os.c` is the syscall wrappers and it had 29 bytes of its
  * ceiling left; `pthread_create` plus a partitioner does not fit in 29 bytes,
  * and raising the syscall half's ceiling to make room would move the number a
  * reader sees for "the operating-system surface" for a reason that has nothing
@@ -21,11 +21,16 @@
  * function exists. The thread-local arena the divided case needs is WP20 T0 and
  * arrives with the same macro.
  *
- * There is no language surface here and nothing in the language calls this yet:
- * docs/wp29-thread-surface.md is the surface, and this is the stage under it.
+ * docs/wp29-thread-surface.md is the surface this is the stage under: P1's
+ * `parallelMapInto` and `parallelReduce` divide a range here, and P2's scopes
+ * run their tasks here (`nish_scope_spawn`, `nish_scope_join`).
  */
 #include "nish.h"
 
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
 #if defined(NISH_THREADS) && !defined(__wasi__) && !defined(__wasm__)
 #define NISH_PAR_REAL 1
 #include <pthread.h>
@@ -154,3 +159,106 @@ void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t gra
   body(0, len, ctx);
 #endif
 }
+
+/* ---- A scope's tasks (wp29 P2) ----
+ *
+ * A task is filed when it is spawned and run when its scope joins, which is
+ * what keeps a scope race-free without a borrow checker: while the tasks run,
+ * the thread that opened the scope is inside the join and runs nothing else,
+ * the tasks write nothing but their own payloads (the language's rule), and
+ * every store into the caller's memory is a `finish` made on the caller's
+ * thread after the last task has finished.
+ *
+ * The filed tasks are one list per thread, newest first, and each carries the
+ * scope it belongs to. Only the thread that opened a scope files into it or
+ * joins it, so the list needs no lock, and scopes may nest: a join takes its
+ * own scope's tasks out of the list and leaves the rest. */
+typedef struct nish_task {
+  struct nish_task *next;
+  void *scope;
+  nish_task_fn run;
+  nish_task_fn finish;
+#ifdef NISH_PAR_REAL
+  pthread_t th;
+  int started;
+#endif
+  /* The copied payload, aligned for any field it holds. */
+  uint64_t payload[];
+} nish_task;
+
+static NISH_TLS nish_task *nish_tasks = 0;
+
+void nish_scope_spawn(void *scope, nish_task_fn run, nish_task_fn finish, const void *payload, int64_t size) {
+  nish_task *t = (nish_task *)malloc(sizeof(nish_task) + (size_t)size);
+  /* Out of memory is the end of the program, as it is for every other
+   * allocation the runtime makes: running the task here instead would store
+   * its answer ahead of tasks filed before it, and a later spawn into the same
+   * slot has to be the one that stays. */
+  if (!t) {
+    (void)!write(2, "nish: out of memory\n", 20);
+    _exit(1);
+  }
+  t->scope = scope;
+  t->run = run;
+  t->finish = finish;
+  memcpy(t->payload, payload, (size_t)size);
+  t->next = nish_tasks;
+  nish_tasks = t;
+}
+
+#ifdef NISH_PAR_REAL
+static void *nish_task_worker(void *p) {
+  nish_task *t = (nish_task *)p;
+  /* A task is one thread's work, as a chunk is, so a region inside it runs on
+   * this thread rather than multiplying the threads. */
+  nish_par_depth = 1;
+  t->run(t->payload);
+  nish_free_arena(); /* as `nish_par_worker`: this thread's arena, and only it */
+  return 0;
+}
+#endif
+
+void nish_scope_join(void *scope) {
+  /* This scope's tasks, oldest first: the list is newest first, and moving each
+   * one to the front of `mine` reverses it. */
+  nish_task *mine = 0;
+  nish_task **link = &nish_tasks;
+  while (*link) {
+    nish_task *t = *link;
+    if (t->scope == scope) {
+      *link = t->next;
+      t->next = mine;
+      mine = t;
+    } else {
+      link = &t->next;
+    }
+  }
+  if (!mine) return;
+#ifdef NISH_PAR_REAL
+  /* Every task but the first on a thread of its own, and the first on this
+   * one, so N tasks cost N-1 spawns and this thread is not idle. A task inside
+   * a region or another task's thread runs here, as a nested region does. */
+  for (nish_task *t = mine->next; t; t = t->next) {
+    t->started = nish_par_depth == 0 && pthread_create(&t->th, 0, nish_task_worker, t) == 0;
+  }
+  nish_par_depth++;
+  mine->run(mine->payload);
+  for (nish_task *t = mine->next; t; t = t->next) {
+    if (!t->started) t->run(t->payload);
+  }
+  nish_par_depth--;
+  for (nish_task *t = mine->next; t; t = t->next) {
+    if (t->started) pthread_join(t->th, 0);
+  }
+#else
+  for (nish_task *t = mine; t; t = t->next) t->run(t->payload);
+#endif
+  /* The stores, in the order the tasks were spawned, so two tasks with one
+   * destination leave the later one's answer there, as they would in sequence. */
+  while (mine) {
+    nish_task *t = mine;
+    mine = t->next;
+    t->finish(t->payload);
+    free(t);
+  }
+}

package/runtime/{runtime_wasm.c → runtime-wasm.c}

@@ -1,7 +1,7 @@
 /* Nish runtime for the freestanding wasm profile (WP8): the arena and the
  * array cold paths, without libc. Link it next to the module when a function
  * takes or returns an array:
- *   scripts/build.sh x.ll runtime/runtime_wasm.c -o x.wasm --profile wasm
+ *   scripts/build.sh x.ll runtime/runtime-wasm.c -o x.wasm --profile wasm
  *
  * Linear memory past `__heap_base` (the linker's end-of-data symbol) is one
  * arena chunk that grows with `memory.grow`; there is no chunk list because
@@ -97,3 +97,8 @@ void nish_panic_index(uint64_t idx, uint64_t len) { (void)idx; (void)len; __buil
 void nish_panic_slice(int64_t s, int64_t e, int64_t len) { (void)s; (void)e; (void)len; __builtin_trap(); }
 void nish_panic_div(_Bool by_zero) { (void)by_zero; __builtin_trap(); }
 void nish_exit(int32_t code) { (void)code; __builtin_trap(); }
+/* A panic's message (`panic`, `expect`, a failed range entry) has no stderr to
+ * go to here; the `nish_exit` that follows it is the trap. An exported function
+ * with a ranged parameter checks it on entry (WP31 §9), so this is what lets
+ * such a module link; the loader throws a RangeError before the call reaches it. */
+void nish_write(const void *s, int32_t fd, _Bool newline) { (void)s; (void)fd; (void)newline; }

package/runtime/runtime.c

@@ -4,13 +4,13 @@
  * it is also the half with the tighter size budget: the arena, strings, number
  * formatting, the array cold paths, `process.argv`, `Math.random`, and the two
  * panics. Files, directories, subprocesses, the environment and the clock are
- * in runtime_os.c — every one of those wraps a system call, so that surface
+ * in runtime-os.c — every one of those wraps a system call, so that surface
  * grows as the language reaches further into the operating system, and a
  * program that reaches nowhere should not pay for it or be measured with it.
- * runtime_os.c's header comment has the reasoning; tests/run.js gates the two
+ * runtime-os.c's header comment has the reasoning; tests/run.js gates the two
  * `.text*` budgets separately and docs/wp7-runtime.md records both.
  *
- * Nothing here calls into runtime_os.c, which is why an old link line that
+ * Nothing here calls into runtime-os.c, which is why an old link line that
  * names runtime.c alone still builds a program that uses none of that surface.
  * The other direction does happen: `nish_readdir` allocates through
  * `nish_alloc_struct` and `nish_str_new`, so those calls no longer inline into
@@ -50,7 +50,7 @@ int __main_argc_argv(int argc, char **argv) { return nish_c_main(argc, argv); }
    definition. Off by default so the ordinary build pays nothing.
 
    The same definition is in runtime/nish.h (for a host that includes it) and
-   runtime/runtime_wasm.c; they are one contract and move together. */
+   runtime/runtime-wasm.c; they are one contract and move together. */
 #ifdef NISH_THREADS
 #define NISH_TLS _Thread_local
 #else
@@ -59,7 +59,7 @@ int __main_argc_argv(int argc, char **argv) { return nish_c_main(argc, argv); }
 
 /* ---- Arena: %struct.nish_arena = type { i8*, i64, i64, i8* }
 
-   The widths are fixed rather than `size_t` for the reason runtime_wasm.c
+   The widths are fixed rather than `size_t` for the reason runtime-wasm.c
    gives for its own copy: every compiled function inlines the bump allocator
    and reads these fields directly, so the IR's `i64` is what `off` and `cap`
    have to be on every target, not just the 64-bit ones. With `size_t` they

package/runtime/shim.mjs

@@ -4,7 +4,7 @@
  * The differential runner (tests/differential/run.js) rewrites an Nish
  * program into plain JavaScript and runs it under Node with this module as
  * `__nish`. Every helper here reproduces the *runtime* semantics the compiled
- * binary has (runtime/runtime.c and runtime/runtime_os.c, the system-call half,
+ * binary has (runtime/runtime.c and runtime/runtime-os.c, the system-call half,
  * plus the intrinsics in docs/wp7-runtime.md) where JavaScript's own semantics
  * differ:
  *
@@ -486,10 +486,10 @@ export function isDirectorySync(path) {
  * the directory cannot be read. Node throws where the runtime answers a value,
  * so the `catch` is what makes the two agree, and a directory that exists and
  * is empty answers an empty array on both sides. Node's readdir never yields
- * `.` or `..` — the pair `runtime_os.c` skips explicitly — so there is nothing
+ * `.` or `..` — the pair `runtime-os.c` skips explicitly — so there is nothing
  * to filter out here.
  *
- * The sort is the semantic point. `runtime_os.c` orders the names with
+ * The sort is the semantic point. `runtime-os.c` orders the names with
  * `strcmp`, which compares UTF-8 bytes, and `Array#sort` compares UTF-16 code
  * units. The two agree on ASCII names and part company above the BMP, where a
  * surrogate pair sorts below `U+E000`..`U+FFFF` in UTF-16 and above them in
@@ -526,7 +526,7 @@ export function realpathSync(path) {
 
 /**
  * `process.platform` / `process.arch` (WP14 §7a). Node's spellings are the
- * ones `runtime_os.c` answers with, so on any machine this compiler has a
+ * ones `runtime-os.c` answers with, so on any machine this compiler has a
  * triple for the two runtimes give the same string; elsewhere the native build
  * says `unknown` where Node names the platform, which is the one place they
  * part.
@@ -553,7 +553,7 @@ export function getenv(name) {
  * `spawnSync(argv)` and `spawnSyncTo(argv, out, err)` (WP14 D4), which are one
  * run with its streams answered differently: the child's exit status, 128 + n
  * when signal n killed it, -1 for an empty vector or a program that would not
- * start. `runtime_os.c` puts one `static nish_spawn_impl` behind both builtins
+ * start. `runtime-os.c` puts one `static nish_spawn_impl` behind both builtins
  * for the same reason this module puts one function behind both helpers — the
  * argument vector, the wait and the signal convention are written once and
  * cannot drift between the two.
@@ -606,7 +606,7 @@ export function spawnSyncTo(argv, out, err) {
 /**
  * `monotonicNanos()`: `process.hrtime.bigint()`, a monotonic clock in
  * nanoseconds (`CLOCK_MONOTONIC` on every platform that has it, which is the
- * one `runtime_os.c` reads). The value is a BigInt because that is how an `i64`
+ * one `runtime-os.c` reads). The value is a BigInt because that is how an `i64`
  * is held on this side.
  *
  * No rewrite can make a *reading* agree with a native run: both origins are