@amritk/nish-x86_64-linux 0.15.0 → 0.17.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,9 +411,16 @@ 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
-one level up from wherever it was invoked, then in the working directory, so
-it wants a checkout or an installed package around it the way `nish` does.
+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
+when the compiler itself lies inside that directory, so a checkout you merely
+`cd` into cannot hand it a `scripts/build.sh` to run. Keep `bin/nish` beside
+`scripts/`, `runtime/` and `std/`, as every install above does, and keep that
+directory's parent writable only by you: the package root is the parent of
+the compiler's directory, so a compiler at `/tmp/x/nish` would trust
+`/tmp/scripts/build.sh` (CLI-9 in [docs/security/cli.md](security/cli.md)).
 
 Because the seed is the last release, `src/` may only *use* in its own
 source the constructs that release compiles. A new construct is implemented
@@ -457,9 +473,11 @@ nish run hello.ts
 `$XDG_CACHE_HOME/nish/run` (or `~/.cache/nish/run`) when that program has not
 been linked before, and starts it with the arguments after the file. The first
 run of a new edit pays for one link, and later runs start the cached binary.
-It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set,
-and refuses the run without them rather than keep a binary in a shared
-directory.
+It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set
+to an absolute path (a relative one is ignored, as if it were unset), and
+refuses the run without one rather than keep a binary in a shared directory.
+The first run that builds into the cache makes its root `0700`, so no other
+user can plant a binary in it ([docs/security/cli.md](security/cli.md)).
 
 ## 4. Exit codes
 
@@ -469,7 +487,7 @@ directory.
 | 1 | the program was rejected: compile error (`file:line:col: error: ...`), missing input file, or an `-o` layout that does not fit the module count |
 | 2 | usage error: unknown flag, missing argument, no input files |
 | 3 | toolchain error: `--link` found no `clang` (`CC` overrides), or `scripts/build.sh` failed (its output is shown; the `.ll` files are still written) — or the `nish` command found no prebuilt compiler for this platform, or one that would not start. Under `--json` all of these are one `NL0002` object |
-| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set it answers 3 |
+| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set to an absolute path it answers 3 |
 | 70 | internal compiler error: an unexpected exception. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; `NISH_DEBUG=1` prints the stack trace |
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.15.0",
+  "version": "0.17.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

@@ -63,6 +63,17 @@ typedef struct nish_str {
   char data[];
 } nish_str;
 
+/* The bytes of `s` as the C string a system call takes, or "" when `s` holds
+ * a NUL. The kernel reads a path to its first NUL, so `"secret\0.txt"` would
+ * pass a `.txt` check and open `secret`; "" names nothing, so each caller
+ * answers it as it answers a missing path. The one test every path, name and
+ * argument the runtime hands the OS goes through (docs/security/runtime.md,
+ * RT-3). `__builtin_strlen`, so this header needs no libc header of its own,
+ * and `unused` because a host that includes it may never call it. */
+static inline __attribute__((unused)) const char *nish_cpath(const nish_str *s) {
+  return __builtin_strlen(s->data) == s->len ? s->data : "";
+}
+
 /* ---- Arena --------------------------------------------------------------
  * One bump allocator per process, or one per thread under `-DNISH_THREADS`
  * (WP20 T0; the layout and every function below are the same either way).
@@ -139,7 +150,16 @@ nish_str *nish_str_from_i64(int64_t v);
 nish_str *nish_str_from_u64(uint64_t v);
 
 /* Process and file I/O (WP7). `nish_exit` never returns; the file functions
- * print a message to stderr and exit(1) on a fatal error. Everything from here
+ * print a message to stderr and exit(1) on a fatal error.
+ *
+ * Every function here that takes a path, a name or an argument vector refuses
+ * one holding a NUL, answering as it answers a path that does not exist: the
+ * kernel would read only the bytes before the NUL, which is a different path
+ * from the one the program checked (docs/security/runtime.md, RT-3). A file
+ * longer than 2^31 - 1 bytes is unreadable, as it is to `nish_read_file_or_null`
+ * and `nish_read_file_bytes` too, because no string or array may be longer
+ * (RT-1). The two writers refuse a symbolic link as the last component of the
+ * path rather than follow it (RT-4). Everything from here
  * to the end of the clock section below is implemented in runtime-os.c, with
  * `nish_random` and `nish_argv_init` the exceptions: neither asks the operating
  * system anything (the clock only seeds the first, and the entry point hands the
@@ -194,12 +214,22 @@ typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array
  * `elem_size` is `sizeof` one element, so for a record element type it is
  * `sizeof(struct Point)` and the block is a C array of them. */
 nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
+/* No array grows past 2^31 - 1 elements and no string past 2^31 - 1 bytes:
+ * `nish_array_grow`, `nish_alloc_array` and `nish_str_concat` fail as an
+ * allocation does (`nish: out of memory`, exit 1; a trap on wasm) rather than
+ * make one, because under --number-mode i32 its `length` would read back
+ * negative (docs/security/codegen.md K1-6, docs/security/runtime.md RT-2). */
 /* The cold paths compiled code calls: `push` when len == cap, a failed bounds
  * check. `nish_array_grow` moves `cap * elem_size` bytes into a fresh arena
  * block and writes `data`/`cap`, so for a record element type it relocates the
  * 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
@@ -254,12 +284,12 @@ nish_array *nish_read_file_bytes(const nish_str *path);
  * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
  * child cannot be started or waited for, and always under WASI, which has no
  * processes. The elements are `nish_str *`; the child receives their bytes,
- * so an argument containing a NUL is truncated at it. */
+ * and an argument containing a NUL is refused (-1) rather than truncated. */
 int32_t nish_spawn(const nish_array *argv);
 /* `spawnSyncTo(argv, stdoutPath, stderrPath)`: exactly `nish_spawn` — the same
  * `PATH` search, the same wait, the same status, `128 + n` and -1 — except that
  * each non-empty path receives that stream, created or truncated at 0644 as
- * `nish_write_file` would leave it. An **empty** string leaves that stream
+ * `nish_write_file` would leave it, a symbolic link at the path refused. An **empty** string leaves that stream
  * inherited, so one call can capture stdout and let stderr through to the
  * terminal. The child opens the files, so a failed open is a child that could
  * not start and answers -1 rather than leaving this process redirected. The two
@@ -275,8 +305,8 @@ int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_st
  * arena (so a later `setenv` cannot change a string the program still holds),
  * or NULL when it is unset — the language's `string | null`. An empty value
  * is a set variable and answers a zero-length string, not NULL. `name` is
- * read and never retained; a NUL inside it truncates the lookup, as it does
- * for every other path-like argument here. */
+ * read and never retained; a name holding a NUL is unset, as it is for every
+ * other path-like argument here. */
 nish_str *nish_getenv(const nish_str *name);
 
 /* ---- Symlinks (WP19 §5a item 4) -----------------------------------------
@@ -288,7 +318,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) ------------------------------------
@@ -336,15 +371,26 @@ 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; 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)`:
+ * `access(path, X_OK)`, for the real uid. */
+int64_t nish_lstat_owner_mode(const nish_str *path);
+int64_t nish_euid(void);
+bool nish_is_executable(const nish_str *path);
 
 /* ---- The network (WP34 N5), runtime/runtime-net.c, `nish:net` ------------
  * 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.
@@ -355,6 +401,10 @@ int32_t nish_read_signal(int32_t fd);
  * 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,
@@ -384,6 +434,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);
@@ -405,6 +457,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)`