@amritk/nish-aarch64-darwin 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-aarch64-darwin",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The @amritk/nish native compiler for macOS on ARM64",
   "license": "MIT",
   "os": [

package/runtime/nish.d.ts

@@ -161,6 +161,18 @@ declare function toF64(x: number | boolean): f64;
 declare function f64ToBits(x: f64): i64;
 declare function bitsToF64(bits: i64): f64;
 
+// ---- Constant time (WP34 N6) ------------------------------------------------
+
+/**
+ * `(a & mask) | (b & ~mask)` with the mask hidden from the optimiser, so it is
+ * never turned into a branch: `a` for an all-ones mask, `b` for zero. Every
+ * operand is one type, `u32` or `u64`. Both are `number` here, so one generic
+ * declaration stands for the two.
+ */
+declare function ctSelect<T extends u32 | u64>(mask: T, a: T, b: T): T;
+/** All-ones of the operands' type when `a === b`, zero otherwise, without a branch. */
+declare function ctEq<T extends u32 | u64>(a: T, b: T): T;
+
 // ---- Streams and files (globals: Nish has no package resolution) ---------
 
 /** `s` to stdout with no trailing newline and no conversion. */
@@ -182,6 +194,12 @@ declare function panic(message: string): never;
 declare function readFileSync(path: string): string;
 /** The same read, answering `null` for every path the other exits over. */
 declare function readFileSyncOrNull(path: string): string | null;
+/**
+ * The file's bytes as they are on disk — no UTF-8 assumed, so a zero byte and
+ * a byte of 0x80 or above survive — or `null` for every path
+ * `readFileSyncOrNull` answers `null` for.
+ */
+declare function readFileBytesSync(path: string): u8[] | null;
 declare function writeFileSync(path: string, data: string): void;
 declare function appendFileSync(path: string, data: string): void;
 /** One directory, not recursive; whether a directory is there afterwards. */
@@ -213,6 +231,34 @@ declare function getenv(name: string): string | null;
  * origin is arbitrary, so only the difference between two reads is meaningful.
  */
 declare function monotonicNanos(): i64;
+/**
+ * The modification time of `path` in milliseconds since the epoch, with the
+ * sub-millisecond fraction the file system keeps (Node's `mtimeMs`), or NaN
+ * when it cannot be stat'd. Follows a symbolic link; a directory has one too.
+ */
+declare function statMtimeSync(path: string): f64;
+/**
+ * A descriptor that becomes readable when SIGTERM or SIGINT arrives, whichever
+ * thread the signal lands on, made once (every call answers the same one), or -1.
+ */
+declare function signalFd(): i32;
+/**
+ * Block until SIGTERM or SIGINT arrives and answer its number, 15 or 2; -1 for
+ * any `fd` that is not `signalFd()`'s. No reading under Node, which throws.
+ */
+declare function readSignal(fd: i32): i32;
+
+// ---- `Date` and `crypto` (WP34 N3) -----------------------------------------------
+//
+// `lib.es2022` already declares `Date`, whose `now()` is Nish's one member of it,
+// so nothing is added: `tsc` accepting `new Date()` is `tsc` not being Nish's
+// checker. `crypto` is a Web API that `lib.es2022` leaves out, so it is
+// declared with its one member, typed as Nish types it.
+
+declare var crypto: {
+  /** Every byte of `bytes` from the system's CSPRNG; at most 65,536 bytes a call. */
+  getRandomValues(bytes: u8[]): void;
+};
 
 // ---- The builtin modules (`nish:`) ---------------------------------------------
 //
@@ -229,6 +275,7 @@ declare function monotonicNanos(): i64;
 declare module "nish:fs" {
   export function readFileSync(path: string): string;
   export function readFileSyncOrNull(path: string): string | null;
+  export function readFileBytesSync(path: string): u8[] | null;
   export function writeFileSync(path: string, data: string): void;
   export function appendFileSync(path: string, data: string): void;
   /** `true` when the directory was created, `false` when it already existed. */
@@ -240,6 +287,8 @@ declare module "nish:fs" {
    */
   export function readdirSync(path: string): string[] | null;
   export function realpathSync(path: string): string | null;
+  /** Node's `mtimeMs` for the path, or NaN when it cannot be stat'd. */
+  export function statMtimeSync(path: string): f64;
 }
 
 declare module "nish:process" {
@@ -257,6 +306,10 @@ declare module "nish:process" {
    * difference between two reads is meaningful.
    */
   export function monotonicNanos(): i64;
+  /** A descriptor readable when SIGTERM or SIGINT arrives; the same one every call, or -1. */
+  export function signalFd(): i32;
+  /** Block until SIGTERM or SIGINT arrives: 15 or 2, or -1 for a descriptor that is not `signalFd()`'s. */
+  export function readSignal(fd: i32): i32;
   /** The command line; `argv[0]` is the program path, as in C. Read-only. */
   export const argv: readonly string[];
   /** The operating system the program runs on: `"linux"`, `"darwin"`, or `"unknown"`. */
@@ -303,6 +356,18 @@ declare interface CPtr {
   readonly __nishForeignPointer: unique symbol;
 }
 
+// ---- `set` on an array ----------------------------------------------------------
+//
+// `dst.set(src, offset)` copies all of `src` into `dst` from `offset` on, with
+// `TypedArray.prototype.set`'s meaning (WP34 N2). A `u8[]` is an `Array` to
+// `tsc`, and `lib.es5.d.ts` gives `Array` a `fill` of the same meaning but no
+// `set`, so this is the one method added to it; `runtime/nish.mjs` installs it
+// under Node. Nish admits it on an array of numbers only.
+
+interface Array<T> {
+  set(source: readonly T[], offset?: number): void;
+}
+
 // ---- What this file cannot say ----------------------------------------------
 //
 // The typed-array aliases (`Int32Array`, `Float32Array`, `Float64Array`,

package/runtime/nish.h

@@ -243,6 +243,12 @@ bool nish_is_dir(const nish_str *path);
  * under WASI: `fd_readdir` lists a preopened directory rather than a path, so
  * porting this there is a different contract and not a translation. */
 nish_array *nish_readdir(const nish_str *path);
+/* `readFileBytesSync(path)` (WP34 N2): the file's bytes as a `u8[]` with
+ * `len == cap`, zero bytes and bytes of 0x80 and above kept as they are, or
+ * NULL for every path `nish_read_file_or_null` answers NULL for. The header
+ * and the bytes live in the arena, so copy what you keep before the next reset
+ * or release. */
+nish_array *nish_read_file_bytes(const nish_str *path);
 /* `spawnSync(argv)`: run element 0 of `argv` (searched on `PATH`) with `argv`
  * as its argument vector, wait for it, and answer its exit status, or
  * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
@@ -306,6 +312,31 @@ const nish_str *nish_arch(void);
  * region into one and measure zero. */
 int64_t nish_monotonic_nanos(void);
 
+/* ---- The host (WP34 N3), runtime/runtime-host.c --------------------------
+ * `Date.now()`: the wall clock, `CLOCK_REALTIME`, in whole milliseconds since
+ * the epoch, as JavaScript answers it. Unlike `nish_monotonic_nanos` it can go
+ * backwards when the clock is corrected; it is for a time a person or a
+ * certificate means, not for measuring an interval. */
+double nish_date_now(void);
+/* `crypto.getRandomValues(bytes)`: fills `bytes->len` bytes from the kernel's
+ * CSPRNG (`getrandom` on Linux, `getentropy` elsewhere). More than 65,536
+ * bytes, the Web API's limit for one call, and a failing entropy source both
+ * print a message and exit 1; nothing weaker is ever substituted. */
+void nish_random_fill(nish_array *bytes);
+/* `statMtimeSync(path)`: the modification time in milliseconds with its
+ * sub-millisecond fraction, computed as Node's `mtimeMs` is, or NaN when
+ * `stat` fails. Follows a symbolic link. */
+double nish_stat_mtime(const nish_str *path);
+/* `signalFd()`: a descriptor that becomes readable when SIGTERM or SIGINT
+ * arrives: the read end of a pipe that a `sigaction` handler writes each
+ * signal's number to, whichever thread the signal lands on. Nothing is
+ * blocked. Made once; every call answers the same descriptor, and -1 when it
+ * could not be made. `readSignal(fd)`: block until one arrives and
+ * answer its number (15 or 2), or -1 for any `fd` that is not that descriptor
+ * or a read that fails. */
+int32_t nish_signal_fd(void);
+int32_t nish_read_signal(int32_t fd);
+
 /* String to number (WP7), ASCII whitespace only. mode 0 is `parseFloat`
  * (longest JS decimal literal or `Infinity`, else NaN), mode 1 is `Number`
  * (the whole string, trimmed; blank is 0; `0x` hex accepted, as in JS),

package/runtime/nish.mjs

@@ -84,6 +84,7 @@ provide("writeError", shim.writeError);
 provide("panic", shim.panic);
 provide("readFileSync", shim.readFileSync);
 provide("readFileSyncOrNull", shim.readFileSyncOrNull);
+provide("readFileBytesSync", shim.readFileBytesSync);
 provide("writeFileSync", shim.writeFileSync);
 provide("appendFileSync", shim.appendFileSync);
 provide("mkdirSync", shim.mkdirSync);
@@ -93,6 +94,35 @@ provide("realpathSync", shim.realpathSync);
 provide("spawnSync", shim.spawnSync);
 provide("spawnSyncTo", shim.spawnSyncTo);
 provide("getenv", shim.getenv);
+provide("statMtimeSync", shim.statMtimeSync);
+provide("signalFd", shim.signalFd);
+provide("readSignal", shim.readSignal);
+
+// `crypto.getRandomValues(bytes)` (WP34 N3). Node has the global, but it
+// takes only a typed array and a `u8[]` is a plain `Array` here, so the one
+// method is replaced on Node's own `crypto` object by one that fills a plain
+// array too (and hands a typed array to the original).
+Object.defineProperty(globalThis.crypto, "getRandomValues", {
+  value: shim.getRandomValues,
+  writable: true,
+  configurable: true,
+});
+
+// `dst.set(src, offset)` (WP34 N2). A `u8[]` is a plain `Array` here, which
+// has `fill` with the typed array's meaning already but no `set`, so the one
+// method is added to `Array.prototype` — non-enumerable, as a builtin method is,
+// so no `for...in` sees it — unless something got there first. It copies the
+// source before writing, as the native `memmove` does, and fails a range past
+// the end with the native panic.
+if (!("set" in Array.prototype)) {
+  Object.defineProperty(Array.prototype, "set", {
+    value: function set(source, offset) {
+      shim.arraySet(this, source, offset);
+    },
+    writable: true,
+    configurable: true,
+  });
+}
 
 // The clock. `monotonicNanos()` answers an `i64`, so the value is a BigInt here
 // as it is in the rewritten runner — and unusually for the i64 surface that is
@@ -117,6 +147,11 @@ provide("toU64", (x) => shim.convert(x, "f64", "u64"));
 provide("f64ToBits", shim.f64ToBits);
 provide("bitsToF64", shim.bitsToF64);
 
+// Constant time (WP34 N6). Pure functions of their operands, so the answers
+// agree with a native run; the timing does not, and is not claimed here.
+provide("ctSelect", shim.ctSelect);
+provide("ctEq", shim.ctEq);
+
 // `Result`. Everything works but `orReturn`, which needs the caller's control
 // flow and therefore the rewriter; see the header.
 provide("Ok", shim.Ok);

package/runtime/runtime-host.c

@@ -0,0 +1,178 @@
+/* Nish runtime, the host half: the wall clock, entropy, a file's modification
+ * time and a descriptor that becomes readable when SIGTERM or SIGINT arrives
+ * (WP34 N3) — the four facts a program that runs for days asks of the machine
+ * it runs on.
+ *
+ * A translation unit of its own for the reason runtime-os.c is one: each file
+ * carries its own measured `.text*` ceiling in tests/run.js. runtime-os.c had
+ * 143 bytes of its ceiling left when these arrived, the four measure more than
+ * that, and a ceiling is not raised to make room (docs/MASTER_PLAN.md §2 has
+ * the numbers). Section GC still means a program that calls none of them pays
+ * for none of them, and scripts/build.sh pairs this file with runtime.c like
+ * the other two halves, so a link line still names one runtime.
+ *
+ * Every function here is platform code, and the two platforms differ in three
+ * places: `getrandom` on Linux and `getentropy` elsewhere, `st_mtim`
+ * against Darwin's `st_mtimespec`, and `pipe2` against `pipe` for the signal
+ * descriptor. A WASI build has none of this
+ * (the checker refuses all four under a wasm target), so there the file is
+ * empty.
+ */
+#if defined(__wasi__) || defined(__wasm__)
+/* ISO C wants at least one declaration in a translation unit. */
+typedef int nish_host_unused;
+#else
+#if defined(__linux__)
+/* glibc declares `clock_gettime`, `sigaction` and `pipe2` under `-std=c11`
+   only with a feature macro, and `pipe2` only with this one. Darwin declares
+   everything by default and hides `getentropy` and the `st_mtimespec`
+   spelling behind a strict feature level, so it gets none. */
+#define _GNU_SOURCE
+#endif
+#include <errno.h>
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/random.h>
+
+#include "nish.h"
+
+/* The spelling runtime.c and runtime-os.c use for their cold paths. */
+#define NISH_COLD __attribute__((noreturn, cold, noinline))
+
+/* `Date.now()`: `CLOCK_REALTIME` in whole milliseconds since the epoch, as
+   JavaScript answers it — the milliseconds are counted in integers and then
+   converted, so the answer is exact until the year 287,396 and a negative
+   time floors the way `Date.now` does rather than rounding towards zero. */
+double nish_date_now(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_REALTIME, &ts);
+  return (double)((int64_t)ts.tv_sec * 1000 + ts.tv_nsec / 1000000);
+}
+
+static NISH_COLD void nish_entropy_fail(uint64_t asked) {
+  if (asked > 65536) {
+    dprintf(2, "crypto.getRandomValues: %llu bytes asked for, and one call fills at most 65536\n",
+            (unsigned long long)asked);
+  } else {
+    dprintf(2, "crypto.getRandomValues: the system's entropy source failed\n");
+  }
+  _exit(1);
+}
+
+/* `crypto.getRandomValues(bytes)`: every byte of `bytes` from the kernel's
+   CSPRNG, or a panic. There is no fallback to a weaker source, because a
+   program handed predictable bytes for a key or a nonce cannot tell. The Web
+   API's limit of 65,536 bytes a call is kept, so a program behaves the same
+   under Node. `getrandom` without flags blocks only until the pool is first
+   initialised at boot and can return short or be interrupted, so it loops;
+   `getentropy` fills at most 256 bytes a call and retries nothing itself. */
+void nish_random_fill(nish_array *bytes) {
+  uint64_t n = bytes->len;
+  char *p = bytes->data;
+  if (n > 65536) nish_entropy_fail(n);
+  while (n > 0) {
+#if defined(__linux__)
+    ssize_t got = getrandom(p, n, 0);
+    if (got < 0) {
+      if (errno == EINTR) continue;
+      nish_entropy_fail(0);
+    }
+#else
+    size_t got = n < 256 ? n : 256;
+    if (getentropy(p, got) != 0) nish_entropy_fail(0);
+#endif
+    p += got;
+    n -= (uint64_t)got;
+  }
+}
+
+/* `statMtimeSync(path)`: the modification time in milliseconds, with the
+   sub-millisecond part the file system keeps, or NaN when `stat` fails. The
+   arithmetic is Node's `mtimeMs` operation for operation — seconds times 1e3
+   plus nanoseconds over 1e6, in doubles — so the two readings print the same
+   digits. `stat` follows a symbolic link, as `fs.statSync` does. */
+double nish_stat_mtime(const nish_str *path) {
+  struct stat st;
+  if (stat(path->data, &st) != 0) return __builtin_nan("");
+#if defined(__APPLE__)
+  struct timespec t = st.st_mtimespec;
+#else
+  struct timespec t = st.st_mtim;
+#endif
+  return (double)t.tv_sec * 1e3 + (double)t.tv_nsec / 1e6;
+}
+
+/* ---- Signals: `signalFd()` and `readSignal(fd)`
+ *
+ * A descriptor rather than a handler in the language, because a handler would
+ * be a function value the language does not have, and because a descriptor is
+ * what a loop waiting in `epoll` or `poll` can wait on beside its sockets.
+ *
+ * Underneath it is a C handler writing each signal's number, one byte, to a
+ * pipe. It is not a `signalfd` on Linux, deliberately: a `signalfd` only
+ * hears a signal that is blocked in **every** thread, and a mask reaches only
+ * the calling thread, so a `scope()` task or a parallel worker already
+ * running when `signalFd()` was called would take the signal at its default
+ * action and end the process. A handler runs in whichever thread the kernel
+ * picks, so no thread's mask matters, and nothing is blocked for a child
+ * `spawnSync` starts to inherit: `exec` resets a caught signal to its
+ * default. Installing the handler also overrides a disposition the process
+ * was started with, so a signal its parent ignored is heard, as
+ * `process.on('SIGTERM')` hears it under Node.
+ *
+ * The handler is the whole of what runs in signal context, and `write` is
+ * async-signal-safe. The write end is non-blocking, so a thousand unread
+ * signals lose the newest rather than wedge the handler, and `errno` is put
+ * back for the code the signal interrupted. The descriptor is made once and
+ * every later `signalFd()` answers the same one. */
+static int nish_signal_read_end = -1;
+static int nish_signal_write_end = -1;
+
+static void nish_on_signal(int sig) {
+  int saved = errno;
+  unsigned char b = (unsigned char)sig;
+  (void)!write(nish_signal_write_end, &b, 1);
+  errno = saved;
+}
+
+int32_t nish_signal_fd(void) {
+  if (nish_signal_read_end >= 0) return nish_signal_read_end;
+  int p[2];
+#if defined(__linux__)
+  /* Both ends close-on-exec from the moment they exist, so a child a sibling
+     thread spawns meanwhile cannot inherit either. */
+  if (pipe2(p, O_CLOEXEC) != 0) return -1;
+#else
+  /* Darwin has no `pipe2`, so there is a window between `pipe` and the two
+     `fcntl`s in which a child spawned by another thread inherits the ends. */
+  if (pipe(p) != 0) return -1;
+  fcntl(p[0], F_SETFD, FD_CLOEXEC);
+  fcntl(p[1], F_SETFD, FD_CLOEXEC);
+#endif
+  fcntl(p[1], F_SETFL, O_NONBLOCK);
+  nish_signal_write_end = p[1];
+  struct sigaction sa;
+  sa.sa_handler = nish_on_signal;
+  sa.sa_flags = SA_RESTART;
+  sigemptyset(&sa.sa_mask);
+  sigaction(SIGINT, &sa, 0);
+  sigaction(SIGTERM, &sa, 0);
+  return nish_signal_read_end = p[0];
+}
+
+/* Block until a signal's byte arrives and answer it: 15 or 2, or -1 for any
+   `fd` that is not the signal descriptor and for a read that fails. */
+int32_t nish_read_signal(int32_t fd) {
+  if (fd != nish_signal_read_end) return -1;
+  unsigned char b;
+  ssize_t n;
+  do n = read(fd, &b, 1);
+  while (n < 0 && errno == EINTR);
+  return n == 1 ? (int32_t)b : -1;
+}
+#endif

package/runtime/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);

package/runtime/shim.mjs

@@ -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");
@@ -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
+# 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.
@@ -83,9 +84,9 @@ 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
@@ -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

package/std/README.md

@@ -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: