@amritk/nish-x86_64-linux 0.16.0 → 0.18.0

package/INSTALL.md

@@ -61,8 +61,9 @@ The `wasi` profile links the runtime against wasi-libc so that whole programs
 needs a WASI sysroot and compiler-rt's wasm32 builtins next to your clang:
 
 ```bash
-# Ubuntu / Debian: the packaged sysroot lands in /usr/lib/wasi-sysroot
+# Ubuntu / Debian: the packaged sysroot lands in /usr (/usr/include/wasm32-wasi, /usr/lib/wasm32-wasi)
 sudo apt-get install -y wasi-libc libclang-rt-18-dev-wasm32
+export WASI_SYSROOT=/usr                      # add to your shell profile
 
 # Any platform: wasi-sdk's sysroot and builtins tarballs (versions that match your clang)
 curl -L -o - https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-24/wasi-sysroot-24.0.tar.gz | tar -xz -C /opt
@@ -74,7 +75,11 @@ export WASI_SYSROOT=/opt/wasi-sysroot-24.0    # add to your shell profile
 `/usr/lib/wasi-sysroot`, `/opt/wasi-sdk/share/wasi-sysroot` and
 `/usr/share/wasi-sysroot`, and for `libclang_rt.builtins-wasm32.a` in clang's
 resource directory, next to the sysroot (as the tarball above unpacks it),
-in `<sysroot>/lib/wasm32-wasi/`, or at `WASI_BUILTINS=<file>`. Then:
+in `<sysroot>/lib/wasm32-wasi/`, or at `WASI_BUILTINS=<file>`.
+
+The packaged wasi-libc predates wasi-libc's `realpath`, so a module linked
+against it answers `realpathSync` with `null` for every path. Use wasi-sdk's
+sysroot (22 or later) when a program needs `realpathSync` to resolve. Then:
 
 ```bash
 nish examples/argv.ts --link build/argv.wasm --profile wasi
@@ -218,7 +223,8 @@ 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 runtime/runtime-parallel.c \
+    runtime/runtime-host.c runtime/runtime-net.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -285,21 +291,20 @@ to the machine that built it.
 
 The last column is there because a release is a past event and a workflow is
 not. `release.yml` builds all four, but a release already published cannot grow
-an asset: **v0.2.0, the current release, attaches `x86_64-linux` only**. Those
+an asset: **the releases before v0.4.0 attach `x86_64-linux` only**. Those
 versions are not prose — they are `attachedSince` in
 [`.github/seed-targets.json`](https://github.com/amritk/nish/blob/main/.github/seed-targets.json),
 the same file the release workflow builds its matrix from, so this table and
 the assets cannot drift apart without a test failing.
 
-**The three new rows say v0.4.0 rather than v0.3.0 on purpose.** The workflow
-builds all four now, but nothing in this repository has ever run on macOS or on
-ARM Linux, and a row that has never run is not something to put in front of a
-release: `release` needs the whole matrix, so one red row blocks the publish.
-They wait for a release after the run that exercises them. The two macOS rows
-wait on a second thing as well — the bootstrap's `stage3 == stage2` check does
-not hold as a raw byte comparison under `ld64`, and which bytes actually differ
-has not been measured on real hardware, so a darwin row may turn up work rather
-than a green tick. `scripts/verify-binaries.sh`'s header is the long version.
+**The three newer rows say v0.4.0 rather than v0.3.0 on purpose.** Nothing in
+this repository had run on macOS or on ARM Linux before, and a row that has
+never run is not something to put in front of a release: `release` needs the
+whole matrix, so one red row blocks the publish. So they waited until a run on
+their own hardware had exercised them. The two macOS rows waited on a second
+thing as well: the bootstrap's `stage3 == stage2` check did not hold as a raw
+byte comparison under `ld64` until both stages were linked at one output path.
+`scripts/verify-binaries.sh`'s header is the long version.
 
 Check [the releases page](https://github.com/amritk/nish/releases/latest) for
 what a given version actually carries; on a platform whose row has not shipped
@@ -307,15 +312,15 @@ yet, take the npm package above, or build from source below.
 
 ```bash
 # pick the row above that matches `uname -s` and `uname -m`
-curl -LO https://github.com/amritk/nish/releases/download/v0.2.0/nish-0.2.0-x86_64-linux.tar.gz
-tar -xzf nish-0.2.0-x86_64-linux.tar.gz
-nish-0.2.0-x86_64-linux/bin/nish --version
+curl -LO https://github.com/amritk/nish/releases/download/v0.16.0/nish-0.16.0-x86_64-linux.tar.gz
+tar -xzf nish-0.16.0-x86_64-linux.tar.gz
+nish-0.16.0-x86_64-linux/bin/nish --version
 ```
 
 Both URLs name the version rather than using GitHub's version-neutral
 `/releases/latest/download/` form, because that form needs the asset's exact
-file name and every asset name carries the version in it. **v0.2.0 is the
-current release**; v0.1.1 before it was the first one with a binary attached.
+file name and every asset name carries the version in it. The example names
+v0.16.0; v0.1.1 was the first release with a binary attached.
 The `v0.1.0` tag exists but has no release behind it and no assets, so every
 `v0.1.0` download URL is a 404 — the tag was pushed by a workflow, and GitHub
 raises no event for that, so nothing ever built it
@@ -333,8 +338,7 @@ find `scripts/build.sh`.
 
 It still needs `clang` and `lld` on `PATH` for `--link` (§1), because linking
 is the C toolchain's job, not the compiler's; what it does not need is Node.
-x86_64 Linux is the only platform built today — on anything else, take the
-`.tgz` above or build from a checkout.
+On a platform outside the table, build from a checkout.
 
 From a checkout:
 
@@ -354,7 +358,7 @@ it into `build/seed/`; `NISH_BOOTSTRAP=<path>` names one you already have and
 skips the download. §2a has what the build does with it.
 
 The published package ships `bin/` (the `nish` command, which is a launcher),
-`runtime/` (the C runtime — two translation units and their header),
+`runtime/` (the C runtime — five translation units and their header),
 `scripts/build.sh` (the link pipeline) and `std/` (the standard library). The
 compiler itself is not in it: it arrives as one prebuilt
 `@amritk/nish-<asset>` package per platform, and `bin/nish` hands over to
@@ -364,22 +368,27 @@ working directory — and the binary runs from inside its own platform package
 for exactly that reason.
 
 Building the IR yourself rather than through `--link` means naming the runtime
-on the `clang` line, and it is two files:
+on the `clang` line, and it is five 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 runtime/runtime-parallel.c \
+  runtime/runtime-host.c runtime/runtime-net.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
-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
-through it — every `--link`, and every `--profile` recipe in these documents —
-needs to name only the one.
+`runtime.c` is the part every program touches — the arena, strings, arrays,
+number formatting, the panics — and `runtime-os.c` wraps the system calls:
+files, directories, subprocesses, `getenv`, the monotonic clock.
+`runtime-parallel.c` divides work across threads for `nish/threads` (a
+program built with `--threads`, as every importer of `nish/threads` is, also
+needs `-DNISH_THREADS=1 -pthread` on the line), `runtime-host.c` holds the
+wall clock, entropy, file times and signals, and `runtime-net.c` the sockets
+of `nish:net`. 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 others, so a line that names only
+`runtime.c` and `runtime-os.c` still links a program that uses none of the
+other three. `scripts/build.sh` compiles the other four 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
 
@@ -402,7 +411,7 @@ release is expected to move it. `--stages 1` stops one link sooner.
 `build/nish` is then the compiler you run: it takes the same `-o`, `--link`
 and `--profile` spellings as an installed `nish`, because it is the same
 program, and makes every directory in the way of the IR, a sidecar or the
-binary itself. It looks for `scripts/build.sh` and the two `runtime/*.c` files
+binary itself. It looks for `scripts/build.sh` and the `runtime/*.c` files
 one level up from wherever it was invoked (and one level up from the file a
 symbolic link to it names), so it wants a checkout or an installed package
 around it the way `nish` does. It falls back to the working directory only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "The @amritk/nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [

package/runtime/nish.d.ts

@@ -112,9 +112,10 @@ declare function Err<T, E>(error: E): Result<T, E>;
 
 /**
  * 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`.
+ * §5): declared here so that a program using `nish/threads`'s scope or
+ * `arena()` needs no `"ESNext.Disposable"` in its `lib`. `nish` itself takes
+ * `using` only for a `scope()` or an `arena()`, and `[Symbol.dispose]` only in
+ * `nish/threads`.
  */
 interface SymbolConstructor {
   readonly dispose: unique symbol;
@@ -172,6 +173,39 @@ declare function bitsToF64(bits: i64): f64;
 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;
+/**
+ * Every byte of `bytes` set to zero, in stores neither `-O2` nor `-flto` may
+ * drop as dead (#385): how a key, a secret scalar or another secret is cleared
+ * once it is used. A statement.
+ */
+declare function secureZero(bytes: u8[]): void;
+/**
+ * One `lstat` of `path`, so a symbolic link answers for itself: the owner's uid
+ * in the high 32 bits and `st_mode` in the low 32, or -1 when the path does not
+ * resolve (#386).
+ */
+declare function lstatOwnerModeSync(path: string): i64;
+/** The effective user id, the one to compare an owner from `lstatOwnerModeSync` with. */
+declare function geteuid(): i64;
+/** Whether the real user may run `path`: `access(path, X_OK)`. */
+declare function isExecutableSync(path: string): boolean;
+
+// ---- Unsafe (`nish:unsafe`) --------------------------------------------------
+//
+// Declared as globals so `tsc` reads a program that imports them, as every
+// `nish:` export is, but `nish` refuses a call to any of the five that is not
+// imported from `nish:unsafe`: the import is the module's visible opt-in.
+
+/** `xs[i]` with no bounds check: undefined behaviour when `i` is out of range. */
+declare function uncheckedGet<T extends number>(xs: readonly T[], i: i32): T;
+/** `xs[i] = v` with no bounds check: undefined behaviour when `i` is out of range. */
+declare function uncheckedSet<T extends number>(xs: T[], i: i32, v: T): void;
+/** `a + b` wrapped to the operands' width, `i32` or `i64`: defined for every pair. */
+declare function wrappingAdd<T extends i32 | i64>(a: T, b: T): T;
+/** `a - b` wrapped to the operands' width. */
+declare function wrappingSub<T extends i32 | i64>(a: T, b: T): T;
+/** `a * b` wrapped to the operands' width. */
+declare function wrappingMul<T extends i32 | i64>(a: T, b: T): T;
 
 // ---- Streams and files (globals: Nish has no package resolution) ---------
 
@@ -200,7 +234,14 @@ declare function readFileSyncOrNull(path: string): string | null;
  * `readFileSyncOrNull` answers `null` for.
  */
 declare function readFileBytesSync(path: string): u8[] | null;
+/**
+ * The file's contents replaced by `data`, created at 0644 when missing. A
+ * symbolic link as the last component of the path is refused rather than
+ * followed, natively and under Node alike, and a path that cannot be written
+ * prints `nish: cannot write <path>` and exits 1.
+ */
 declare function writeFileSync(path: string, data: string): void;
+/** `data` added at the end of the file, with the same refusal of a symbolic link. */
 declare function appendFileSync(path: string, data: string): void;
 /** One directory, not recursive; whether a directory is there afterwards. */
 declare function mkdirSync(path: string): boolean;
@@ -221,7 +262,8 @@ declare function realpathSync(path: string): string | null;
 declare function spawnSync(argv: string[]): number;
 /**
  * The same run with each non-empty path receiving that stream, created or
- * truncated; an empty string leaves that stream inherited.
+ * truncated; an empty string leaves that stream inherited. A symbolic link at
+ * either path is refused, as `writeFileSync` refuses one, and the answer is -1.
  */
 declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
 /** One environment variable, or `null` when it is unset (an empty value is a set variable). */
@@ -252,9 +294,10 @@ declare function readSignal(fd: i32): i32;
 //
 // Every call answers an `i32`: `>= 0` on success, a negative errno otherwise, in
 // Linux's numbering on every platform for -11 (would block), -95, -32, -104,
-// -98 and -22. An address is 18 bytes of a `u8[]`: 16 of IPv6 address (IPv4 as
-// `::ffff:a.b.c.d`), then the port, big-endian. Every socket is non-blocking and
-// close-on-exec. No reading under Node, where each throws.
+// -98, -111 (refused), -110 (timed out) and -22. An address is 18 bytes of a
+// `u8[]`: 16 of IPv6 address (IPv4 as `::ffff:a.b.c.d`), then the port,
+// big-endian. Every socket is non-blocking and close-on-exec. No reading under
+// Node, where each throws.
 
 /** Write the address form of a numeric `host` and `port` into `out`: 0, or -22. */
 declare function netAddress(out: u8[], host: string, port: i32): i32;
@@ -272,6 +315,10 @@ declare function netWrite(fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
 declare function netShutdown(fd: i32, how: i32): i32;
 /** Close the descriptor. */
 declare function netClose(fd: i32): i32;
+/** A TCP socket connecting to `addr`, answered while it connects: writable once it has, or has failed. */
+declare function tcpConnect(addr: readonly u8[]): i32;
+/** Once `fd` is writable: 0 when the connection is made, else its failure (-111 refused). */
+declare function connectResult(fd: i32): i32;
 /** A UDP socket: flag 1 `SO_REUSEPORT`, flag 2 `UDP_GRO` (-95 on Darwin); ECN is always read. */
 declare function udpBind(host: string, port: i32, flags: i32): i32;
 /** `buf[off, off + len)` to `to`, cut into `segment`-byte datagrams when `segment > 0`, with ECN bits `ecn`. */
@@ -325,7 +372,9 @@ declare module "nish:fs" {
   export function readFileSync(path: string): string;
   export function readFileSyncOrNull(path: string): string | null;
   export function readFileBytesSync(path: string): u8[] | null;
+  /** Refuses a symbolic link as the last component of the path, as the global does. */
   export function writeFileSync(path: string, data: string): void;
+  /** Refuses a symbolic link as the last component of the path, as the global does. */
   export function appendFileSync(path: string, data: string): void;
   /** `true` when the directory was created, `false` when it already existed. */
   export function mkdirSync(path: string): boolean;
@@ -347,7 +396,8 @@ declare module "nish:process" {
   export function spawnSync(argv: string[]): number;
   /**
    * The same run with each non-empty path receiving that stream, created or
-   * truncated; an empty string leaves that stream inherited.
+   * truncated; an empty string leaves that stream inherited. A symbolic link
+   * at either path is refused, and the answer is -1.
    */
   export function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
   /**
@@ -383,6 +433,10 @@ declare module "nish:net" {
   /** Shut the read side (0), the write side (1) or both (2). */
   export function netShutdown(fd: i32, how: i32): i32;
   export function netClose(fd: i32): i32;
+  /** A TCP socket connecting to `addr`, answered while it connects: writable once it has, or has failed. */
+  export function tcpConnect(addr: readonly u8[]): i32;
+  /** Once `fd` is writable: 0 when the connection is made, else its failure (-111 refused). */
+  export function connectResult(fd: i32): i32;
   /** A UDP socket: flag 1 `SO_REUSEPORT`, flag 2 `UDP_GRO` (-95 on Darwin); ECN is always read. */
   export function udpBind(host: string, port: i32, flags: i32): i32;
   /** `buf[off, off + len)` to `to`, cut into `segment`-byte datagrams when `segment > 0`, with ECN bits `ecn`. */
@@ -409,6 +463,19 @@ declare module "nish:net" {
   export function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
 }
 
+declare module "nish:unsafe" {
+  /** `xs[i]` with no bounds check: undefined behaviour when `i` is out of range. */
+  export function uncheckedGet<T extends number>(xs: readonly T[], i: i32): T;
+  /** `xs[i] = v` with no bounds check: undefined behaviour when `i` is out of range. */
+  export function uncheckedSet<T extends number>(xs: T[], i: i32, v: T): void;
+  /** `a + b` wrapped to the operands' width, `i32` or `i64`. */
+  export function wrappingAdd<T extends i32 | i64>(a: T, b: T): T;
+  /** `a - b` wrapped to the operands' width. */
+  export function wrappingSub<T extends i32 | i64>(a: T, b: T): T;
+  /** `a * b` wrapped to the operands' width. */
+  export function wrappingMul<T extends i32 | i64>(a: T, b: T): T;
+}
+
 declare module "nish:io" {
   /** `s` to stdout with no trailing newline and no conversion. */
   export function write(s: string): void;
@@ -418,6 +485,39 @@ declare module "nish:io" {
   export function panic(message: string): never;
 }
 
+// `nish:secret` has source behind it, `std/secret.ts`, but a program imports it
+// by this name, so `tsc` reads these declarations rather than that file. The
+// class is declared with a private constructor and a private field: `tsc` then
+// refuses `new Secret(...)`, `s.value` and a structural look-alike, as `nish`
+// does. Everything else `nish` refuses about a `Secret` — printing it,
+// comparing it, branching on it, dropping it unwiped, an `expose` whose
+// function does I/O — is flow, which `tsc` cannot see
+// (docs/LANGUAGE.md -> Secrets).
+declare module "nish:secret" {
+  /**
+   * Key material: an array of integers or a record of integer fields, held
+   * opaque. Made by `secret`, read only through `expose`, and wiped or
+   * returned by the function that made it.
+   */
+  export class Secret<T> {
+    private constructor();
+    private readonly value: T;
+  }
+  /** `value`, wrapped. A local handed in is moved: it may not be read again. */
+  export function secret<T>(value: T): Secret<T>;
+  /**
+   * `f(value)`. `f` reaches no I/O and no C, keeps nothing of `value`, and
+   * declares a return type that holds no `Secret`: that type is what leaves.
+   */
+  export function expose<T, R>(s: Secret<T>, f: (value: T) => R): R;
+  /** `f(value, arg)`, under `expose`'s rules; `f` may not write `arg` either. */
+  export function exposeWith<T, A, R>(s: Secret<T>, arg: A, f: (value: T, arg: A) => R): R;
+  /** Zero the value's whole storage, with a store the optimiser may not remove. */
+  export function wipe<T>(target: Secret<T>): void;
+  /** Zero an array or record of integers that `expose`'s function holds, likewise. */
+  export function wipe(target: object): void;
+}
+
 // ---- Arena (docs/LANGUAGE.md -> Arena) ---------------------------------------
 
 declare const Arena: {
@@ -431,6 +531,15 @@ declare const Arena: {
   used(): i64;
 };
 
+/**
+ * `using a = arena()` (docs/LANGUAGE.md -> Arena): everything the block
+ * allocates after this declaration is released when the block ends, on every
+ * exit, and the compiler refuses the block if anything allocated in it could
+ * outlive it. Only a `using` initialiser, and the binding is never read; under
+ * Node there is no arena and the disposal does nothing.
+ */
+declare function arena(): Disposable;
+
 /**
  * `CPtr` (WP27 S2): the address a `declare function` hands back, opaque and
  * eight bytes wide. `docs/LANGUAGE.md` has the rules — it may be written in a

package/runtime/nish.h

@@ -3,15 +3,17 @@
  * 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 `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
+ * several translation units: `runtime/runtime.c` holds the core every program
+ * touches — the arena, strings, arrays, number formatting, the panics —
  * `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
+ * clock, `nish_platform` / `nish_arch` — and runtime-parallel.c, runtime-host.c,
+ * runtime-net.c and runtime-simd.c (the byte searches that read a vector at a
+ * time) split off the same way since. They are separate so that each carries
  * its own measured code-size ceiling (docs/wp7-runtime.md, "Runtime additions
- * and budget"); a host links both, which `scripts/build.sh` does for you when
- * handed either. `tests/run.js` checks that every runtime function declared in
- * runtime.ts has a prototype in this file.
+ * and budget"); a host links all of them, which `scripts/build.sh` does for
+ * you when handed runtime.c. `tests/run.js` checks that every runtime function
+ * declared in runtime.ts has a prototype in this file.
  *
  * Headers generated by `nish --emit-header` include this one, so keep
  * it C11-clean under -Wall -Wextra -Werror and usable from C++.
@@ -137,6 +139,18 @@ bool nish_str_at(const nish_str *s, int64_t at, const nish_str *sub);
 /* `s.indexOf(sub)`: the first byte offset where `sub` occurs, or -1. An empty
    needle answers 0 and one longer than `s` answers -1, as in JavaScript. */
 int64_t nish_str_index_of(const nish_str *s, const nish_str *sub);
+/* `s.indexOf(sub, from)`: the same search from byte `from`, which must already
+   be clamped into [0, s->len]; an empty needle answers `from`. Outside that
+   range nothing outside `s` is read: a non-empty needle answers -1 and an
+   empty one answers `from` unchanged. */
+int64_t nish_str_index_of_from(const nish_str *s, const nish_str *sub, int64_t from);
+/* First index i >= from with s[i] in set, or -1.
+   from is already clamped to [0, len] by the caller; set holds 1..16 bytes.
+   It lives in runtime/runtime-simd.c, which picks a scalar, a baseline vector
+   or an AVX2 path on the first call; `NISH_SIMD=scalar|base|avx2` pins it. A
+   set outside 1..16 bytes is answered by the scalar path rather than refused,
+   but only 1..16 is the contract. Variable-time: never call it on a secret. */
+int64_t nish_str_index_of_any(const nish_str *s, const nish_str *set, int64_t from);
 /* `console.log(s)`: one write(2) of the bytes plus a newline to stdout. */
 void nish_print(const nish_str *s);
 /* `console.error` and the newline-free `write` / `writeError`: fd 1 or 2. */
@@ -225,6 +239,11 @@ nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
  * elements themselves — which is why the checker refuses to let a program hold
  * a pointer to one across a `push` (WP15 section 2a). */
 void nish_array_grow(nish_array *a, uint64_t elem_size);
+/* `secureZero(bytes)` (#385): sets every byte of `bytes` to zero through
+ * `volatile` stores, out of line, so that neither `-O2` nor `-flto` can drop
+ * them as dead when the buffer's life ends straight after the call. For
+ * secret material -- a private key, a secret scalar -- once it is used. */
+void nish_wipe(nish_array *bytes);
 void nish_panic_index(uint64_t idx, uint64_t len);
 /* The failed range check of `s.slice(start, end)` (WP15 section 4): prints the
    half-open interval that was asked for and the byte length it left, then
@@ -313,7 +332,12 @@ nish_str *nish_getenv(const nish_str *name);
  * but the last must exist for POSIX `realpath` to answer at all.
  *
  * `path` is read and never retained. The answer is a fresh arena string, so
- * it outlives the call the way every other string here does. */
+ * it outlives the call the way every other string here does.
+ *
+ * Under the wasi profile the answer is the sysroot's `realpath`, which
+ * wasi-sdk 22 and later have. A wasi-libc without one (the one Ubuntu and
+ * Debian package) answers NULL for every path, which a caller already
+ * handles. */
 nish_str *nish_realpath(const nish_str *path);
 
 /* ---- What machine this is (WP14 §7a) ------------------------------------
@@ -361,8 +385,9 @@ double nish_stat_mtime(const nish_str *path);
  * or a read that fails. */
 int32_t nish_signal_fd(void);
 int32_t nish_read_signal(int32_t fd);
-/* Who owns a path, and whether it runs (docs/security/runtime.md, RT-9; no
- * builtin reaches these yet). `nish_lstat_owner_mode(path)`: `lstat`, so a
+/* Who owns a path, and whether it runs (docs/security/runtime.md, RT-9; the
+ * builtins `lstatOwnerModeSync`, `geteuid` and `isExecutableSync`, #386).
+ * `nish_lstat_owner_mode(path)`: `lstat`, so a
  * symbolic link answers for itself, as the owner's uid in the high 32 bits
  * and `st_mode` in the low 32, or exactly -1 when the path does not resolve.
  * `nish_euid()`: the effective uid. `nish_is_executable(path)`:
@@ -375,10 +400,11 @@ bool nish_is_executable(const nish_str *path);
  * Every call answers an `int32_t`: `>= 0` on success (a descriptor, a byte
  * count, 0) and a negative errno otherwise, in Linux's numbering on every
  * platform for -11 (would block), -95 (unsupported), -32 (the peer is gone),
- * -104 (reset), -98 (address in use) and -22 (a bad argument). Every socket
- * is non-blocking and close-on-exec. An address is 18 bytes of a `u8[]`
- * (element type `uint8_t`): 16 of IPv6 address, IPv4 as `::ffff:a.b.c.d`,
- * then the port, big-endian; a shorter array is -22. Nothing allocates.
+ * -104 (reset), -98 (address in use), -111 (refused), -110 (timed out) and
+ * -22 (a bad argument). Every socket is non-blocking and close-on-exec. An
+ * address is 18 bytes of a `u8[]` (element type `uint8_t`): 16 of IPv6
+ * address, IPv4 as `::ffff:a.b.c.d`, then the port, big-endian; a shorter
+ * array is -22. Nothing allocates.
  *
  * `nish_net_address(out, host, port)`: the form of a numeric `host`.
  * `nish_net_local_port(fd)`: the port a socket is bound to.
@@ -389,6 +415,10 @@ bool nish_is_executable(const nish_str *path);
  * len)` of `buf`, which the compiled call has range-checked; a write to a
  * gone peer is -32, never SIGPIPE. `nish_net_shutdown(fd, how)`: 0 read, 1
  * write, 2 both. `nish_net_close(fd)`.
+ * `nish_tcp_connect(addr)`: a new socket connecting to `addr`, answered at
+ * once; its `EINPROGRESS` is not a failure, and any other closes it.
+ * `nish_connect_result(fd)`: `SO_ERROR` once the socket is writable, 0 when
+ * the connection is made.
  *
  * UDP: `nish_udp_bind(host, port, flags)` binds a datagram socket, flag 1
  * `SO_REUSEPORT` and flag 2 `UDP_GRO` (-95 on Darwin). `nish_udp_send_to(fd,
@@ -418,6 +448,8 @@ int32_t nish_net_read(int32_t fd, nish_array *buf, int64_t off, int64_t len);
 int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t len);
 int32_t nish_net_shutdown(int32_t fd, int32_t how);
 int32_t nish_net_close(int32_t fd);
+int32_t nish_tcp_connect(const nish_array *addr);
+int32_t nish_connect_result(int32_t fd);
 int32_t nish_udp_bind(const nish_str *host, int32_t port, int32_t flags);
 int32_t nish_udp_send_to(int32_t fd, const nish_array *buf, int64_t off, int64_t len, const nish_array *to,
                          int32_t segment, int32_t ecn);
@@ -439,6 +471,11 @@ 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);
 
+/* Checked signed arithmetic: the failed-check path. `op` is 0 add, 1
+ * subtract, 2 multiply, 3 negate; prints "attempt to <op> with overflow" and
+ * exits 1. */
+void nish_panic_overflow(uint32_t op);
+
 /* ---- Parallel work (WP20 T1 / wp29 stage P1), runtime/runtime-parallel.c ----
  *
  * One region of work, divided. `nish_parallel_range` calls `body(lo, hi, ctx)`

package/runtime/nish.mjs

@@ -16,14 +16,14 @@
  * That is enough for a real and useful subset — **f64 mode**, where JavaScript's
  * `+ - * / %` on doubles *are* `fadd/fsub/fmul/fdiv/frem` and `Math.*` are the
  * same IEEE operations, so the arithmetic needs no help. It is not enough for
- * i32 mode, and it never will be: `number` is a wrapping 32-bit integer there
- * and every operator would have to change.
+ * i32 mode, and it never will be: `number` is a 32-bit integer there, whose
+ * signed overflow panics, and every operator would have to change.
  *
  * `docs/RUN_UNDER_NODE.md` states the overlap and the whole list of what stays
  * divergent. The short version, because it belongs next to the code too:
  *
- *   - **i32 mode is out.** Wrapping, truncating `/`, and the divide-by-zero
- *     panic are all operator-level and cannot be reached from here.
+ *   - **i32 mode is out.** The overflow panic, truncating `/`, and the
+ *     divide-by-zero panic are all operator-level and cannot be reached from here.
  *   - **`s.length` is UTF-16 units under Node** and UTF-8 bytes natively, and
  *     so is every string offset. ASCII agrees; nothing else does.
  *   - **`a[i]` is unchecked**: out of range is `undefined` here and an exit-1
@@ -109,6 +109,8 @@ for (const name of [
   "netWrite",
   "netShutdown",
   "netClose",
+  "tcpConnect",
+  "connectResult",
   "udpBind",
   "udpSendTo",
   "udpRecvFrom",
@@ -174,6 +176,49 @@ provide("bitsToF64", shim.bitsToF64);
 // agree with a native run; the timing does not, and is not claimed here.
 provide("ctSelect", shim.ctSelect);
 provide("ctEq", shim.ctEq);
+// `secureZero` (#385): the bytes are zero afterwards here too, though what a
+// collector may have copied before is out of reach.
+provide("secureZero", shim.secureZero);
+// The RT-9 owner checks (#386): one `lstat`, the effective uid and
+// `access(X_OK)`, answered as `runtime-host.c` answers them.
+provide("lstatOwnerModeSync", shim.lstatOwnerModeSync);
+provide("geteuid", shim.geteuid);
+provide("isExecutableSync", shim.isExecutableSync);
+
+// `nish:unsafe`. The element access is JavaScript's own, which never checks
+// anything; the wraps are the two's-complement ones the native instructions
+// perform: `| 0` and `Math.imul` at `i32`, and `BigInt.asIntN(64, ...)` on
+// the BigInt an `i64` is here. Pure functions of their operands, so a program
+// that stays in range agrees with a native run.
+const wrapAt = (a, b, wide, narrow) => (typeof a === "bigint" ? BigInt.asIntN(64, wide(a, b)) : narrow(a, b));
+provide("uncheckedGet", (xs, i) => xs[i]);
+provide("uncheckedSet", (xs, i, v) => {
+  xs[i] = v;
+});
+provide("wrappingAdd", (a, b) =>
+  wrapAt(
+    a,
+    b,
+    (x, y) => x + y,
+    (x, y) => (x + y) | 0
+  )
+);
+provide("wrappingSub", (a, b) =>
+  wrapAt(
+    a,
+    b,
+    (x, y) => x - y,
+    (x, y) => (x - y) | 0
+  )
+);
+provide("wrappingMul", (a, b) =>
+  wrapAt(
+    a,
+    b,
+    (x, y) => x * y,
+    (x, y) => Math.imul(x, y)
+  )
+);
 
 // `Result`. Everything works but `orReturn`, which needs the caller's control
 // flow and therefore the rewriter; see the header.
@@ -200,15 +245,34 @@ provide("Arena", {
   reset: shim.arenaReset,
   used: shim.arenaUsed,
 });
+// `using a = arena()` releases nothing here either: what the block allocated
+// is the garbage collector's, and the disposal is a no-op.
+provide("arena", shim.arena);
 
 // The standard library. A program imports it as `nish/<module>`, which the
 // compiler resolves to `std/<module>.ts` beside itself; this does the same for
 // Node, relative to this file rather than to the program, so the same
 // specifier works from any directory. Only the `nish/` package is answered
 // here, and every other specifier goes to Node as it was written.
+//
+// `nish:secret` is answered here as well, because the standard library imports
+// it (`std/crypto/p256.ts` and its neighbours): its names are
+// `runtime/shim.mjs`'s, where a `Secret` is a plain wrapper and `wipe`
+// zero-fills it. `nish:unsafe` is answered by a module that hands back the
+// globals installed above: its functions are globals of this module either
+// way, and the import is what the compiler requires a program to write.
+const UNSAFE_EXPORTS = ["uncheckedGet", "uncheckedSet", "wrappingAdd", "wrappingSub", "wrappingMul"];
+const unsafeSource = UNSAFE_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
 registerHooks({
-  resolve: (specifier, context, next) =>
-    specifier.startsWith("nish/")
+  resolve: (specifier, context, next) => {
+    if (specifier === "nish:secret") {
+      return next(new URL("./shim.mjs", import.meta.url).href, context);
+    }
+    if (specifier === "nish:unsafe") {
+      return { url: `data:text/javascript,${encodeURIComponent(unsafeSource)}`, shortCircuit: true };
+    }
+    return specifier.startsWith("nish/")
       ? next(new URL(`../std/${specifier.slice("nish/".length)}.ts`, import.meta.url).href, context)
-      : next(specifier, context),
+      : next(specifier, context);
+  },
 });