@amritk/nish-x86_64-linux 0.12.0 → 0.14.0

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

@@ -102,6 +102,21 @@ nish_str *nish_read_file_or_null(const nish_str *path) {
   return s;
 }
 
+/* `readFileBytesSync(path)` (WP34 N2): the same read, handed to the language as
+   a `u8[]`. The bytes are not copied a second time: `nish_read_file_or_null`
+   has already put them in the arena behind their 8-byte length, 8-aligned, so
+   the header points `data` there with `len == cap`, and the NUL written after
+   them is simply never indexed. Nothing on the way assumes UTF-8, so a zero
+   byte and a byte of 0x80 or above come back as they are on disk. A `push`
+   onto the result grows it into a fresh block, as it would any full array. */
+nish_array *nish_read_file_bytes(const nish_str *path) {
+  nish_str *s = nish_read_file_or_null(path);
+  if (!s) return 0;
+  nish_array *a = nish_alloc_struct(sizeof *a);
+  *a = (nish_array){ s->len, s->len, s->data };
+  return a;
+}
+
 nish_str *nish_read_file(const nish_str *path) {
   nish_str *s = nish_read_file_or_null(path);
   if (!s) nish_io_fail("read ", path);
@@ -319,7 +334,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:
  *
@@ -42,6 +42,7 @@
  * The rewrite rules that call these helpers are listed in docs/wp13-differential.md.
  */
 import child_process from "node:child_process";
+import { webcrypto } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 
@@ -91,6 +92,37 @@ export function bitsToF64(b) {
   return BITS.getFloat64(0);
 }
 
+/**
+ * `ctSelect` / `ctEq` (WP34 N6). A `u32` is a `number` here and a `u64` a
+ * BigInt, so the operands' kind picks the width, and a mix of the two — which
+ * the native checker refuses, and which a `u64` written as a bare literal is
+ * under an unrewritten run — throws the `TypeError` BigInt arithmetic throws
+ * rather than comparing a number with a BigInt and answering zero. JavaScript's
+ * `&` reads a `number` as a signed 32-bit integer, so each answer is put back in
+ * range with `>>> 0` or `asUintN(64, ...)`. These branch: only the native
+ * lowering promises constant time.
+ */
+function ctWide(name, first, second, third) {
+  const wide = typeof first === "bigint";
+  if ((typeof second === "bigint") !== wide || (typeof third === "bigint") !== wide) {
+    throw new TypeError(`${name}: cannot mix a u64 (BigInt) with a u32 (number)`);
+  }
+  return wide;
+}
+
+const U64_ONES = (1n << 64n) - 1n;
+
+export function ctSelect(mask, a, b) {
+  if (ctWide("ctSelect", mask, a, b)) return wrapU64((a & mask) | (b & ~mask));
+  return ((a & mask) | (b & ~mask)) >>> 0;
+}
+
+export function ctEq(a, b) {
+  // `ctEq` has two operands, so the second one stands in for the third.
+  if (ctWide("ctEq", a, b, b)) return wrapU64(a ^ b) === 0n ? U64_ONES : 0n;
+  return (a ^ b) === 0 ? 0xffffffff : 0;
+}
+
 /** Wrap a BigInt to the i64 range: every i64 `+ - * /` and unary minus goes through here. */
 export function wrapI64(x) {
   return BigInt.asIntN(64, x);
@@ -401,6 +433,28 @@ export function updIdx(a, i, f) {
   return v;
 }
 
+/**
+ * `dst.set(src, offset)` (WP34 N2): `TypedArray.prototype.set`'s copy on the
+ * plain array a `u8[]` is here. The source is copied first, so a self-copy or
+ * an overlapping one reads what was there before, as `memmove` does natively;
+ * a range past the end fails with the native panic and its words, where a
+ * typed array would throw a `RangeError` for the same offsets.
+ */
+export function arraySet(dst, src, offset) {
+  // `ToIntegerOrInfinity`: NaN is 0, as `llvm.fptosi.sat` makes it natively.
+  // `Math.trunc` rather than `toIndex`, which converts a bigint: an `i64` or
+  // `u64` offset is a bigint here, and it throws the `TypeError` the typed
+  // array and `Array.prototype.fill` throw for one, instead of being rounded
+  // to the nearest double past 2^53 (docs/RUN_UNDER_NODE.md).
+  const at = offset === undefined ? 0 : Math.trunc(offset) || 0;
+  const end = at + src.length;
+  if (!(at >= 0 && end <= dst.length)) panicSlice(at, end, dst.length);
+  // Two plain arrays overlap only when they are one array, which is the one
+  // case that must read the source before writing it.
+  const from = src === dst ? src.slice() : src;
+  for (let i = 0; i < from.length; i++) dst[at + i] = from[i];
+}
+
 /** `new Array<T>(n)`: `n` zero-filled elements (`0`, `0n`, or `false`). */
 export function newArray(n, zero) {
   return new Array(toIndex(n)).fill(zero);
@@ -434,6 +488,15 @@ export function readFileSyncOrNull(path) {
   }
 }
 
+/** `readFileBytesSync(path)` (WP34 N2): the bytes as a plain array of numbers, or null. */
+export function readFileBytesSync(path) {
+  try {
+    return Array.from(fs.readFileSync(path));
+  } catch {
+    return null;
+  }
+}
+
 export function writeFileSync(path, data) {
   try {
     fs.writeFileSync(path, data, "utf8");
@@ -486,10 +549,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 +589,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 +616,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 +669,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
@@ -618,6 +681,65 @@ export function monotonicNanos() {
   return process.hrtime.bigint();
 }
 
+// ---- The host (WP34 N3) ------------------------------------------------------
+
+/**
+ * `statMtimeSync(path)`: Node's `mtimeMs` for the path, or NaN when it cannot
+ * be stat'd, which is the native answer too. `mtimeMs` is the same arithmetic
+ * `runtime-host.c` does, so the two print the same digits, fraction and all.
+ */
+export function statMtimeSync(path) {
+  const st = fs.statSync(path, { throwIfNoEntry: false });
+  if (st === undefined) {
+    return Number.NaN;
+  }
+  return st.mtimeMs;
+}
+
+/**
+ * Node's own fill, taken before `runtime/nish.mjs` puts the one below in its
+ * place on the same object: `webcrypto` is the global `crypto`.
+ */
+const webRandom = webcrypto.getRandomValues.bind(webcrypto);
+
+/**
+ * `crypto.getRandomValues(bytes)` for the plain array a `u8[]` is here. Node's
+ * own takes only a typed array, so the bytes are drawn into one and copied
+ * across. More than 65,536 fails with the native panic and its words, where
+ * Node would throw a `QuotaExceededError`: the exit status is 1 either way. A
+ * typed array goes straight through.
+ */
+export function getRandomValues(bytes) {
+  if (!Array.isArray(bytes)) {
+    return webRandom(bytes);
+  }
+  if (bytes.length > 65536) {
+    panic(`crypto.getRandomValues: ${bytes.length} bytes asked for, and one call fills at most 65536`);
+  }
+  const drawn = webRandom(new Uint8Array(bytes.length));
+  for (let i = 0; i < drawn.length; i++) {
+    bytes[i] = drawn[i];
+  }
+  return bytes;
+}
+
+/**
+ * `signalFd()` and `readSignal(fd)` have no faithful reading under Node, and
+ * these say so rather than answer something else. Node delivers a signal to
+ * its event loop (`process.on("SIGTERM")`), and a blocking read keeps the loop
+ * from ever running, so no synchronous function here can learn that one
+ * arrived. docs/wp33-round-trip.md §3.5 has the row and the translation.
+ */
+export function signalFd() {
+  throw new Error(
+    "signalFd has no synchronous reading under Node: a signal reaches the event loop, which a blocking readSignal never returns to (docs/wp33-round-trip.md)"
+  );
+}
+
+export function readSignal() {
+  return signalFd();
+}
+
 /** `process.argv`: index 0 is the program (the script here, the executable natively), then the arguments. */
 export function argv() {
   return process.argv.slice(1);

package/scripts/build.sh

@@ -3,11 +3,12 @@
 #
 #   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm]
 #
-# The C runtime is three translation units and is named as one: an input
-# <dir>/runtime.c also compiles <dir>/runtime_os.c, the half that wraps the
+# The C runtime is four translation units and is named as one: an input
+# <dir>/runtime.c also compiles <dir>/runtime-os.c, the half that wraps the
 # system calls (files, directories, subprocesses, the environment, the clock),
-# and <dir>/runtime_parallel.c, the half that divides a range of work across
-# threads. Each of those files says why they are compiled and measured apart.
+# <dir>/runtime-parallel.c, the half that divides a range of work across
+# threads, and <dir>/runtime-host.c, the wall clock, entropy, file times and
+# signals. Each of those files says why they are compiled and measured apart.
 #
 # Profiles:
 #   debug  clang defaults: no optimisation, symbols kept. The "before" number.
@@ -15,7 +16,7 @@
 #   size   -Oz + LTO + section GC + strip + no unwind tables. Rust
 #          `opt-level="z"`, `panic="abort"`, `strip=true` equivalent.
 #   wasm   wasm32 freestanding module exporting every non-internal function;
-#          load it from Node. Add runtime/runtime_wasm.c to the inputs when a
+#          load it from Node. Add runtime/runtime-wasm.c to the inputs when a
 #          function uses arrays (the arena and the array cold paths, no libc);
 #          strings and I/O still need a WASI runtime and are not available.
 #   wasm   wasm32 freestanding module exporting every non-internal function
@@ -83,13 +84,13 @@ done
 [ ${#inputs[@]} -gt 0 ] || { echo "error: no input files" >&2; exit 2; }
 [ -n "$out" ] || { echo "error: -o <out> is required" >&2; exit 2; }
 
-# The runtime is three translation units, and a caller names one: whoever passes
-# <dir>/runtime.c gets <dir>/runtime_os.c and <dir>/runtime_parallel.c compiled
-# beside it. They were one file until the operating-system half was split out
+# The runtime is four translation units, and a caller names one: whoever passes
+# <dir>/runtime.c gets <dir>/runtime-os.c, <dir>/runtime-parallel.c and
+# <dir>/runtime-host.c compiled beside it. They were one file until the operating-system half was split out
 # for its own size budget, and the parallel half followed for the same reason
 # (each file's header comment says why), and a link line is where those splits
 # would otherwise leak: `nish --link` builds its command line in
-# self/compile.ts, the published package's recipe in every document and
+# src/compile.ts, the published package's recipe in every document and
 # README names runtime.c, and a user's own clang line does too. Pairing them
 # here keeps every one of those correct, and keeps "the runtime" one thing to
 # name from the outside. A caller that names one itself is left alone, because
@@ -97,7 +98,7 @@ done
 for i in ${inputs[@]+"${inputs[@]}"}; do
   case "$i" in
     */runtime.c|runtime.c)
-      for half in runtime_os.c runtime_parallel.c; do
+      for half in runtime-os.c runtime-parallel.c runtime-host.c; do
         side="${i%runtime.c}$half"
         have=0
         for j in "${inputs[@]}"; do
@@ -133,8 +134,12 @@ case "$(uname -s)" in
     # of one input to one output path, and differing on a link to another. That
     # is what scripts/bootstrap.sh links every comparable stage at one path for,
     # and it is why `stage3 == stage2` holds on Mach-O with the load command in.
-    gc=(-Wl,-dead_strip); strip_flag=(-Wl,-x) ;;
+    # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
+    gc=(-Wl,-dead_strip)
+    # shellcheck disable=SC2054
+    strip_flag=(-Wl,-x) ;;
   *)
+    # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
     gc=(-Wl,--gc-sections -Wl,--as-needed -Wl,-O2 -Wl,--build-id=none); strip_flag=(-s)
     elf=(-fno-plt)
     # GNU ld needs the gold plugin for LTO; prefer lld when clang can find it.
@@ -158,7 +163,7 @@ if [ "$debug" = 1 ]; then common+=(-g); strip_flag=(); fi
 # own command line instead of using `common`; it is empty on every ordinary
 # build, hence the bash 3.2 expansion spelling explained below.
 #
-# -pthread is for runtime_parallel.c, the translation unit that divides a range
+# -pthread is for runtime-parallel.c, the translation unit that divides a range
 # of work across threads: it is compiled in either configuration and only spawns
 # under this macro, so this is the build where the flag has to be on the command
 # line. On a current glibc the library half is already inside libc and the link
@@ -167,7 +172,7 @@ if [ "$debug" = 1 ]; then common+=(-g); strip_flag=(); fi
 #
 # It is deliberately in `common` and not in `tls`: `tls` is the wasm and wasi
 # command lines, which have no threads to link against, and where
-# runtime_parallel.c compiles to its sequential fallback because it tests
+# runtime-parallel.c compiles to its sequential fallback because it tests
 # __wasi__ and __wasm__ as well as the macro.
 tls=()
 if [ "$threads" = 1 ]; then
@@ -265,6 +270,7 @@ case "$profile" in
     shared=(-shared -fPIC)
     # macOS: the napi_* symbols come from the node binary at load time, so the
     # linker must not insist on resolving them. ELF shared objects allow this.
+    # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
     case "$(uname -s)" in Darwin) shared+=(-Wl,-undefined,dynamic_lookup) ;; esac
     # runtime/nish.h is the public ABI header the generated shim includes.
     runtime_inc="$(cd "$(dirname "$0")/../runtime" && pwd)"

package/std/README.md

@@ -4,7 +4,7 @@ Nish modules written in Nish, for Nish programs to import. There is no magic
 here and — with three exceptions, `threads.ts`, `collections.ts` and `map.ts` —
 nothing the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
 whatever program imports it, and subject to the same rules as `examples/` or
-`self/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
+`src/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
 
 | Module | What it is |
 | --- | --- |
@@ -16,6 +16,46 @@ whatever program imports it, and subject to the same rules as `examples/` or
 | [`map.ts`](./map.ts) | `reserve(m, n)` and `getOrInsert(m, k, v)` for the global `Map`. Their bodies are the meaning, and what runs under Node: `reserve` does nothing, and `getOrInsert` is a `get`, and a `set` of `v` when the key was missing. Natively the compiler lowers every call in place — `reserve` to the table's `reserveSlots`, which grows the buckets once so that `n` entries fit without a rebuild, and `getOrInsert` to one `probe` and a `valueAt` or an `insertAt` through its answer — so, like `collections.ts`, it writes no `.ll` of its own ([`docs/wp32-map.md`](../docs/wp32-map.md) §9.2, [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)) |
 | [`threads.ts`](./threads.ts) | `parallelMapInto(src, dst, f)` and `parallelReduce(src, f, identity)`: a function over every element of an array, on as many threads as the length is worth. Its bodies are the sequential meaning, which is what runs under Node; the compiler recognises the two templates by module and name, lowers the one loop in each onto `nish_parallel_range`, holds the function to the rules that make that safe, and compiles an importing program with `--threads` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#data-parallelism-nishthreads)). `tests/link/par_*` are its programs |
 
+## `nish/crypto` — the primitives under TLS 1.3
+
+The first lanes of [WP34](../docs/wp34-hosting-cs.md) §5: K1's hashes, MACs and
+key derivation, and K4's key exchange, in pure Nish (decision S1), each module
+imported by its own specifier. Every one is written from its specification
+rather than ported, and reproduces that specification's published vectors in
+its `tests/link/crypto_*` programs. The performance gate compiles every module
+with no diagnostics under both `--number-mode i32` and `f64`, and the hashes,
+HMAC, HKDF and X25519 also run their vectors in `f64` (`crypto_*_f64`).
+
+| Module | What it is | Reproduces |
+| --- | --- | --- |
+| [`crypto/sha256.ts`](./crypto/sha256.ts) | `sha256(data)`, and `Sha256`, a streaming hasher: `update(buf, off, len)` over a window of a `u8[]`, `copy()` for the hash of a prefix while the original keeps going, and `digest()`, a fresh 32-byte array. `SHA256_SIZE` and `SHA256_BLOCK` | FIPS 180-4 §6.2 |
+| [`crypto/sha512.ts`](./crypto/sha512.ts) | SHA-512 and SHA-384 on one compression function: `sha512` and `sha384`, and the streaming `Sha512` and `Sha384` with `Sha256`'s three methods; digests of 64 and 48 bytes. `SHA512_SIZE`, `SHA384_SIZE` and `SHA512_BLOCK` | FIPS 180-4 §6.4, §6.5 |
+| [`crypto/hmac.ts`](./crypto/hmac.ts) | `hmacSha256` and `hmacSha384`, the streaming `HmacSha256` and `HmacSha384` (keyed in the constructor, then `update` and `digest`), and `hmacSha256Verify` / `hmacSha384Verify`, which compare a received tag with `timingSafeEqual` | RFC 2104, RFC 4231 §4 |
+| [`crypto/hkdf.ts`](./crypto/hkdf.ts) | `hkdfExtractSha256` / `hkdfExtractSha384` (an empty salt is HashLen zeros) and `hkdfExpandSha256` / `hkdfExpandSha384`, which answer `null` for a length below zero or above 255 × HashLen. TLS 1.3's HKDF-Expand-Label is not here; it belongs with TLS | RFC 5869 §2, Appendix A |
+| [`crypto/ct.ts`](./crypto/ct.ts) | `timingSafeEqual(a, b)`, which reads every byte whatever it holds, and `timingSafeEqualAt(a, aOff, b, bOff, len)` over two windows, which answers `false` for a window outside its array. Two lengths that differ answer `false` at once, because a length is public | — |
+| [`crypto/base64url.ts`](./crypto/base64url.ts) | `base64urlEncode(data)` and `base64urlDecode(text)`, unpadded. Decoding is strict, so every byte string has one spelling: a `=`, a character outside the alphabet, a length of 1 mod 4 or nonzero unused low bits answer `null` | RFC 4648 §5, §10 |
+| [`crypto/x25519.ts`](./crypto/x25519.ts) | `x25519(scalar, u)` and `x25519Base(scalar)`, on ten 25.5-bit limbs in `i64`. Either answers `null` unless its arguments are `X25519_SIZE` (32) bytes; the scalar is clamped on a copy | RFC 7748 §5.2, §6.1 |
+
+Three rules hold across the modules:
+
+- **A digest ends the computation.** After `digest()` on a hasher or an HMAC, a
+  further `update` or `digest` panics rather than answering a hash over the
+  padding, and so does a window outside its buffer. `Sha256.copy()` on a
+  digested hasher panics too; `Sha512.copy()` and `Sha384.copy()` answer a copy
+  that is itself spent, so any `update` or `digest` on it panics. Either way,
+  copy *before* `digest` when the computation has to go on.
+- **An all-zero X25519 result is returned, not refused.** It is what a
+  low-order `u` gives, and RFC 7748 §6.1 leaves the check to the protocol; TLS
+  1.3 (WP34 T1) makes it. A key exchange outside TLS has to make it itself.
+- **Constant time by construction, not yet by proof.** No module branches on,
+  or indexes by, a secret: comparisons OR the differences into one word and
+  test it once, the ladder swaps with a mask and always runs 255 steps, and
+  base64url maps characters by arithmetic on range masks rather than a table.
+  Every branch is on a length, a loop counter or a bit position. What checks
+  that the machine code kept that shape is WP34 N6 — the `ctSelect` / `ctEq`
+  builtins behind an optimisation barrier, and a disassembly check — and it is
+  not built yet, so this is the discipline and not a verified property.
+
 ## How a program imports it
 
 By its package specifier:
@@ -130,7 +170,7 @@ that are *not* this package.
   stdout. `tests/link/std_text_f64` is the same corpus under
   `--number-mode f64`, which is where a module that spelled its widths and forgot
   a `toI32` is caught.
-- **`std/` is not on the compiler's dependency list.** Nothing in `self/`
+- **`std/` is not on the compiler's dependency list.** Nothing in `src/`
   imports it, and nothing should: the compiler is the thing that has to
   build before the library means anything.