@amritk/nish-x86_64-linux 0.28.0 → 0.29.0

package/INSTALL.md

@@ -255,7 +255,8 @@ routes are
   clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
     runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
     runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-term.c \
-    runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c -lm -o app
+    runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
+    runtime/runtime-shm.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -391,7 +392,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 — thirteen translation units, the wasm subset and their
+`runtime/` (the C runtime — fourteen translation units, the wasm subset and their
 header — and `runtime/sqlite/`, SQLite's vendored source),
 `scripts/build.sh` (the link pipeline), `std/` (the standard library) and
 `docs/AI.md` (the rules card). The
@@ -404,13 +405,14 @@ 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 thirteen files:
+on the `clang` line, and it is fourteen files:
 
 ```bash
 clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
   runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
   runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-term.c \
-  runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c -lm -o app
+  runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
+  runtime/runtime-shm.c -lm -o app
 ```
 
 `runtime.c` is the part every program touches — the arena, strings, arrays,
@@ -428,7 +430,8 @@ blocks to on a CPU with the SHA instructions (`NISH_SHA256=soft` keeps the
 portable path), `runtime-term.c` the stdin reads and terminal calls of `nish:term`,
 `runtime-bytes.c` the byte-class runs of `nish/bytes`, which `nish/json` steps
 over, `runtime-checksum.c` the CRC-32 kernels of `nish/compress/checksum`,
-and `runtime-sandbox.c` the confinement a `--sandbox` build applies.
+`runtime-sandbox.c` the confinement a `--sandbox` build applies, and
+`runtime-shm.c` the shared-memory regions of `nish/sync/shm`.
 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

package/docs/AI.md

@@ -180,7 +180,7 @@ rejects. This table is the highest-value part of the page.
 | `keyof T`, `<T = i32>` (a default type argument) | `` Unsupported type `keyof T` (Phase 1 supports …) `` / `a default type argument … is not supported` | name the type; a type argument is always inferred |
 | `class B extends A` | `` `extends` is not supported: Nish has no inheritance `` | repeat the fields and `implements` an interface |
 | `static` members, `get x()` / `set x(v)` | `` … `static` members are not supported `` / `` Getters and setters are not supported in class `C` (use a method) `` | module `const`s and plain methods |
-| `const [a, b] = xs`, `({ x }: Point) =>`, `(n = 1)`, `(n?: i32)`, `(...ns: i32[])` | `Destructuring is not supported` / `Destructured parameters are not supported` / `Optional/default parameters are not supported` / `Rest parameters are not supported` | one name per binding, every parameter passed; an array for a variable count |
+| `const [a, b] = xs`, `({ x }: Point) =>`, `(n?: i32)`, `(n = 1)`, `f(...xs)` | `Destructuring is not supported` / `Destructured parameters are not supported` / `Optional parameters are not supported` / `` Parameter `n` has a default and no type annotation `` / `Spread arguments are not supported` | one name per binding; `n: i32 = 1` (a constant or an earlier parameter) for a default; `...ns: i32[]` as the last parameter, or pass the array itself |
 | `function f(): void;` (an overload), `export default function ()` | `Functions must have a body` / `Functions must be named` | one named function, with its body |
 | a method in an `interface` | `` Interface `I` cannot declare methods (interfaces describe layout only) `` | fields only; a top-level function over the interface |
 | `abstract class`, `declare class`, `constructor(public x: i32)`, `interface B extends A`, `[k: string]: T` | `Abstract classes are not supported` / `` `declare class` is not supported `` / `Parameter properties … are not supported; declare the field and assign it` / ``Interface inheritance (`extends`) is not supported; list every field`` / `Index signatures are not supported …` | a plain class with its fields declared and assigned in the constructor; every field listed; a `Map` for a keyed table |
@@ -845,10 +845,14 @@ export const main = (): i32 => {
 - **Call it, or pass it on to another function parameter. Nothing else**:
   `const g = f`, `return f` and `[f]` are
   `` `f` is a function parameter and can only be called or passed on as a function argument ``.
-- **An arrow captures nothing.** It sees its own parameters and top-level
-  names; reading a local of the function around it is
-  `` The arrow reads `k`, which belongs to the function it is written in ``.
-  Pass the value in as another argument of the template instead.
+- **An arrow may read the `const` locals and parameters of the function it is
+  written in**, and write through a captured reference
+  (`(x) => { if (x > limit) { hits.push(x) } }`); each capture becomes one more
+  argument of the direct call. It may not assign to one, read a `let`
+  (`` The arrow reads `k`, a `let` of the function it is written in: ... bind the value to a `const` before the call ``),
+  read `this` (bind `const self = this`), or read a function parameter of its
+  function. An arrow inside another arrow, or given to a method, a
+  constructor, `expose` or `exposeWith`, captures nothing.
 - **The argument's type must match exactly**: `(x: i32) => i64` for a
   `(x: i32) => i32` parameter is refused. A generic function cannot be passed
   by name — write `(x) => identity(x)`.
@@ -858,12 +862,13 @@ export const main = (): i32 => {
 - **Only a top-level function** may have one: not a method, a constructor, a
   field, a local, a return type or an alias.
 
-```ts nish:err NL2335
+```ts nish:err NL2585
 const apply = (f: (x: i32) => i32, x: i32): i32 => f(x);
 
 export const main = (): i32 => {
-  const k = 3;
-  return apply((x) => x + k, 1);   // captures `k`: pass it to `apply` instead
+  let k = 3;
+  k = k + 1;
+  return apply((x) => x + k, 1);   // reads the `let` `k`: bind `const kNow = k` before the call
 };
 ```
 
@@ -976,6 +981,11 @@ export const main = (): i32 => {
   (NL2388): `using s = scope()`.
   The scope is only ever the receiver of a `spawn` statement: never pass it,
   store it or return it.
+- **A task that recurses deeply gets a bigger stack from `scopeWithStack`.**
+  `using s = scopeWithStack(64 * 1024 * 1024)` is a scope whose tasks each run
+  on a new thread with a 64 MiB stack; a thread's default is 8 MiB. Ask for at
+  least 131072 bytes: a number below it is refused (NL2584). Under Node the size
+  is ignored, so run Node with `--stack-size` too.
 - **The task is a top-level function named in the `spawn`, or an arrow written
   there.** `s.spawn(entry, arg)` with no destination runs an entry that
   answers `void`; `s.spawn(() => work(a, b))` runs an arrow that reads the
@@ -1893,32 +1903,52 @@ export const main = (): i32 => {
   `push` inside the body extends the loop. `for...in`, `for await` and
   `for (x of xs)` over an existing `x` are each refused by name.
 - `switch` takes an **integer or enum** discriminant; every `case` label is an
-  integer constant expression of that type. **There is no implicit
-  fallthrough** — a clause with statements ends in `break`, `return`,
-  `continue` or `process.exit`, unless it is the last. An *empty* clause does
-  fall through, which is how `case 1: case 2:` shares a body. A clause cannot
-  declare a variable directly; wrap its body in a block.
-- `break` / `continue` are unlabelled only; labeled statements are forbidden.
+  integer constant expression of that type. A clause that does not end in
+  `break`, `return`, `continue` or `process.exit` **falls through** into the
+  next, as in TypeScript; an *empty* clause is how `case 1: case 2:` shares a
+  body. A clause reached by falling into it is not narrowed by its label. A
+  clause cannot declare a variable directly; wrap its body in a block.
+- **Labels** go on a loop, a block or a `switch`: `break outer` leaves the
+  statement named `outer` from any depth, `continue outer` starts the next
+  turn of the loop named `outer`. A label on any other statement is refused,
+  and a jump cannot leave an arrow for a label outside it.
 - `process.exit(code)` and `panic(msg)` **terminate control flow**, so a
   non-`void` function may end with either.
 - **Unreachable code is an error**, not a warning: anything after a `return`,
   `break`, `continue`, `process.exit`, an `if` whose branches all return, or an
   infinite loop.
 
-```ts nish:err NL2166
-const classify = (n: i32): string => {
+```ts nish:ok
+const firstPair = (limit: i32, target: i32): i32 => {
+  outer: for (let i: i32 = 0; i < limit; i++) {
+    for (let j: i32 = 0; j < limit; j++) {
+      if (i * j === target) {
+        return i * 100 + j;
+      }
+      if (j > i) {
+        continue outer;   // the next `i`
+      }
+    }
+  }
+  return -1;
+};
+
+const classify = (n: i32): i32 => {
+  let score: i32 = 0;
   switch (n) {
     case 0:
-      console.log("zero");   // no `break`: a clause with statements must end in one
+      score += 10;   // no `break`: falls into `case 1`
     case 1:
-      return "one";
+      score += 1;
+      break;
     default:
-      return "many";
+      score = -1;
   }
+  return score;
 };
 
 export const main = (): i32 => {
-  console.log(classify(0));
+  console.log(`${firstPair(10, 12)} ${classify(0)} ${classify(1)}`);   // 304 11 1
   return 0;
 };
 ```
@@ -2181,6 +2211,10 @@ also watches the signal fd. None of `spawn`, `kill`, `waitPid` may be called in
 a task or a parallel body; the two host facts may. `availableParallelism()` (`i32`, at least 1, no `--threads` needed) and
 `totalMemory()` (`i64` bytes, or `-1`) size a program to the machine. None of
 the five exists on a wasm target, and `spawn` and `waitPid` throw under Node.
+`spawnWithFds(argv, fds)` is `spawn` that hands the child `fds[i]` as
+descriptor `3 + i` (systemd's `LISTEN_FDS` numbering); every other descriptor
+still closes at exec. More than 64, or a negative one, is `-22`; it needs
+`process.spawn` under `--sandbox`, refuses a wasm target and throws under Node.
 `setNice(n)` sets the nice value, and it is lower-only even as root: `n` takes
 0..19 (`-22` outside it) and a value below the current one is `-13`, with no
 system call either way. `setIdlePriority()` moves the program to Linux's `SCHED_IDLE`
@@ -2230,8 +2264,42 @@ unread is reported again. Add `signalFd()` to the loop to wake on SIGTERM.
 `NET_SO_KEEPALIVE`, `NET_SO_SNDBUF` and `NET_SO_RCVBUF`, `i32` ids exported
 beside it; any other id is `-22`. Linux drops quick-ACK mode on its own, so set
 it again after each response. The ids are not module constants: pass them
-directly. None
-exists on a wasm target, and under Node each throws.
+directly. `netMss(fd)` answers a connected TCP socket's send MSS, the payload
+bytes one segment carries, and `-1` for anything else (never an errno), so size
+writes by it with a fallback. None but `netMss` exists on a wasm target (there
+it is always `-1`), and under Node each throws.
+
+Unix-domain stream sockets: `unixListen(path, backlog, flags)` listens on a
+socket file left at 0600 (`unixListenMode(path, backlog, flags, mode)` for
+another mode), `unixConnect(path)` and `unixAccept(fd)` answer descriptors
+that `netRead`, `netWrite`, `netShutdown`, `netClose` and the loop take as
+they are, and `unixSocketPair(NET_UNIX_STREAM, fds)` fills `fds: i32[]` with
+two connected ends (`NET_UNIX_SEQPACKET` keeps message boundaries; Linux
+only, `-95` on Darwin). A path starting with `@` is Linux's abstract
+namespace and makes no file (`-95` on Darwin); write `./@name` for a socket
+file so named. A path that exists is `-98`; flag `NET_UNIX_UNLINK_STALE`
+first removes a socket file nobody listens on (Linux; on Darwin it is `-95`
+at a socket file, since a full backlog and a dead file both refuse there).
+`NET_UNIX_UNLINK_STALE`, `NET_UNIX_STREAM` and `NET_TCP_NODELAY` are all `1`,
+so pass the constant each call names. A path as written is at most 107
+bytes (103 on Darwin) and an abstract name at most 107 after its `@`; longer
+is `-36`. A full backlog makes `unixConnect`
+`-11` on Linux and `-111` on Darwin. Under `--sandbox`, a listener on a path
+also needs `fs.write` (`-13` without it); an abstract name does not, and a
+connect to a path is not confined. `sendFd(sock, fd, buf, off, len)` sends
+`buf[off, off + len)` with descriptor `fd` attached (`len` 0 is `-22`) and
+answers the bytes sent, which on a stream socket can be short: the descriptor
+went with the first bytes, so send the rest with `netWrite`; `recvFd(sock, buf, off, len, fd)` reads into the
+range and sets `fd[0]` to the descriptor that came with it, or `-1`; the
+descriptor arrives close-on-exec, its status flags (`O_NONBLOCK` among them)
+the open file's, which the sender shares, any beyond the first are closed,
+and `fd` shorter than 1 is `-22`. `peerCredentials(sock, out)` writes
+`[pid, uid, gid]` of the process that made the connection, as it was at
+connect time, into an `out` of length 3 or more (`-22` shorter, `-107` for a
+listener or a socket never connected); on Darwin the
+pid can be `-1`. All three answer `-88` or `-95` for a socket that is not
+Unix-domain. The Unix calls are refused on a wasm target, and under Node each
+throws.
 
 **Arena.** `Arena.mark()`, `Arena.used()` and `using a = arena()` — see below.
 `Arena.release(m)` and `Arena.reset()` were removed before 1.0: write
@@ -2261,6 +2329,10 @@ console.log(`${seen.size} ${counts.size} ${seen.has("b")}`);
 - A key is a string, any number type, a `boolean`, an enum or a class instance
   (by identity). An interface, an array, a nullable type or a `Result` is not a
   key; a value is anything but `void` or an interface.
+- A pair of `i32`s is one `i64` key, not a string: `(toI64(a) << toI64(32)) |
+  toI64(toU32(b))`. Every operand is an `i64` so it also runs
+  under Node, where `i64` is a `BigInt`; it is exact for every pair. A `+` in
+  place of `|` overflows at `a = -2^31` with a negative `b`.
 - A module that declares its own `Map` or `Set` keeps it, but then no other
   module of the program may name the global one.
 
@@ -2710,8 +2782,11 @@ export const main = (): i32 => {
 };
 ```
 
-**Optional parameters** — there are none. Write two functions with different
-names, or take the value and document the sentinel.
+**Optional parameters** — write a default instead: `(n: i32 = 1)`. A default
+is a literal, an enum member or an earlier parameter, and the call site fills
+it in. `x?: T` is refused. A variable count of one type is a rest parameter,
+`(...ns: i32[])`, last in the list; a call never spreads (`f(...xs)`), it passes
+`xs` to an array parameter.
 
 **A calendar, regex, JSON, threads of your own** — not in the language (the
 wall clock is `Date.now()`, and that is all of `Date`). Say so rather than

package/package.json

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

package/runtime/core/host.d.ts

@@ -73,8 +73,9 @@ export declare function isTerminal(fd: i32): boolean;
 export declare function terminalSize(): i32[];
 /** `crypto.getRandomValues(bytes)` for a `u8[]`; a typed array goes straight through. */
 export declare function getRandomValues<T extends u8[] | Uint8Array>(bytes: T): T;
-/** These four have no synchronous reading: each throws, naming itself, and is typed as `runtime/nish.d.ts` types it. */
+/** These five have no synchronous reading: each throws, naming itself, and is typed as `runtime/nish.d.ts` types it. */
 export declare function spawn(argv: string[]): i32;
+export declare function spawnWithFds(argv: string[], fds: readonly i32[]): i32;
 export declare function waitPid(pid: i32, flags: i32): i32[];
 export declare function signalFd(): i32;
 export declare function readSignal(fd: i32): i32;

package/runtime/core/host.mjs

@@ -309,6 +309,10 @@ export function spawn() {
   return noProcessReading("spawn");
 }
 
+export function spawnWithFds() {
+  return noProcessReading("spawnWithFds");
+}
+
 export function waitPid() {
   return noProcessReading("waitPid");
 }

package/runtime/nish.d.ts

@@ -333,6 +333,14 @@ declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: str
  * the child is then killed and each array keeps at most the first 16 MiB.
  */
 declare function spawnPiped(argv: string[], stdin: readonly u8[], stdout: u8[], stderr: u8[]): i32;
+/**
+ * `spawn` with the child holding `fds[i]` as descriptor `3 + i`, inherited
+ * across the exec; every other descriptor stays close-on-exec. The child's pid,
+ * or a negative errno: -22 more than 64 descriptors or a negative one, -9 one
+ * that is not open, -24 (or -22 above the descriptor limit) a scratch
+ * descriptor the system cannot give. No reading under Node, which throws.
+ */
+declare function spawnWithFds(argv: string[], fds: readonly i32[]): i32;
 /**
  * Start `argv[0]` through `PATH` without waiting: the child's pid, or a
  * negative errno. The child is the program's until `waitPid` reaps it. No
@@ -460,6 +468,11 @@ declare function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
  * a negative errno (-9 a closed descriptor, -88 not a socket).
  */
 declare function netSetOption(fd: i32, option: i32, value: i32): i32;
+/**
+ * A connected TCP socket's send MSS, the payload bytes one segment carries;
+ * -1, never an errno, for anything else, and always on wasm.
+ */
+declare function netMss(fd: i32): i32;
 /** `TCP_NODELAY`: `value` 1 sends a small write at once, 0 lets Nagle batch it. */
 declare const NET_TCP_NODELAY: i32;
 /**
@@ -474,6 +487,57 @@ declare const NET_SO_KEEPALIVE: i32;
 declare const NET_SO_SNDBUF: i32;
 /** `SO_RCVBUF`: the receive buffer, `value` in bytes; Linux doubles the value it stores. */
 declare const NET_SO_RCVBUF: i32;
+/**
+ * A listening Unix stream socket at `path` (`@name`: Linux's abstract
+ * namespace), its file mode 0600. A path that exists is -98, unless `flags`
+ * holds `NET_UNIX_UNLINK_STALE`; -36 a path too long, -22 an empty one.
+ */
+declare function unixListen(path: string, backlog: i32, flags: i32): i32;
+/** `unixListen` with the socket file's mode chosen (0 to 0o777); -22 for an `@name`. */
+declare function unixListenMode(path: string, backlog: i32, flags: i32, mode: i32): i32;
+/** A non-blocking socket connected to the listener at `path`; -11 a full backlog on Linux (-111 on Darwin), -111 nothing listening. */
+declare function unixConnect(path: string): i32;
+/** The next connection on a Unix listener, non-blocking; -11 when none is waiting. */
+declare function unixAccept(fd: i32): i32;
+/**
+ * Two connected sockets into `fds[0]` and `fds[1]`, and 0: `kind` is
+ * `NET_UNIX_STREAM` or `NET_UNIX_SEQPACKET` (-95 on Darwin); -22 another kind
+ * or an `fds` shorter than 2.
+ */
+declare function unixSocketPair(kind: i32, fds: i32[]): i32;
+/**
+ * Send `buf[off..off+len)` over the Unix socket `sock` with a copy of the
+ * descriptor `fd` (`SCM_RIGHTS`): the bytes sent, or a negative errno; -22 a
+ * zero `len` or a negative `fd`, -9 a closed `sock` or `fd`, -88 a `sock`
+ * that is not a socket, -95 one that is not Unix. A stream socket can send
+ * short: the descriptor travels with the first bytes, so send the rest with
+ * `netWrite`.
+ */
+declare function sendFd(sock: i32, fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
+/**
+ * Read at most `len` bytes into `buf[off..]` from the Unix socket `sock`, and
+ * the first descriptor that came with them into `fd[0]`, or -1: the bytes read,
+ * or a negative errno. Every other descriptor in the message is closed; the
+ * one kept is close-on-exec and keeps the sender's blocking mode. -22 a zero
+ * `len` or an empty `fd`, -9 a closed `sock`, -88 not a socket, -95 not
+ * Unix.
+ */
+declare function recvFd(sock: i32, buf: u8[], off: i32, len: i32, fd: i32[]): i32;
+/**
+ * The peer of the Unix socket `fd` as of its connect: `out` gets its pid, uid
+ * and gid, and the answer is 0; the pid is -1 where Darwin has no
+ * `LOCAL_PEERPID`. A uid or gid of 2^31 or above wraps (-2 is uid
+ * 4294967294). -22 an `out` shorter than 3, -9 a closed `fd`, -88 not a
+ * socket, -95 not Unix, -107 a socket with no peer (a listener, or one never
+ * connected).
+ */
+declare function peerCredentials(fd: i32, out: i32[]): i32;
+/** `unixListen` flag: unlink a socket file nothing listens on, then bind. */
+declare const NET_UNIX_UNLINK_STALE: i32;
+/** `unixSocketPair` kind: a byte stream. */
+declare const NET_UNIX_STREAM: i32;
+/** `unixSocketPair` kind: each write one message (`SOCK_SEQPACKET`). */
+declare const NET_UNIX_SEQPACKET: i32;
 
 // ---- `nish:term` ------------------------------------------------------------------
 //
@@ -580,6 +644,13 @@ declare module "nish:process" {
   export function spawnPiped(argv: string[], stdin: readonly u8[], stdout: u8[], stderr: u8[]): i32;
   /** Start a child without waiting: its pid, or a negative errno. */
   export function spawn(argv: string[]): i32;
+  /**
+   * `spawn` with the child holding `fds[i]` as descriptor `3 + i`: its pid, or
+   * a negative errno; -22 more than 64 descriptors or a negative one, -9 one
+   * that is not open, -24 (or -22 above the descriptor limit) a scratch
+   * descriptor the system cannot give.
+   */
+  export function spawnWithFds(argv: string[], fds: readonly i32[]): i32;
   /** Send 0, 2, 9 or 15 to `pid`: 0, or a negative errno; any other signal is -22. */
   export function kill(pid: i32, sig: i32): i32;
   /** `[pid, status]` for a child that exited, `[0, 0]` under WNOHANG (flag 1) with none, or `[-errno, 0]`. */
@@ -667,6 +738,11 @@ declare module "nish:net" {
    * a negative errno (-9 a closed descriptor, -88 not a socket).
    */
   export function netSetOption(fd: i32, option: i32, value: i32): i32;
+  /**
+   * A connected TCP socket's send MSS, the payload bytes one segment carries;
+   * -1, never an errno, for anything else, and always on wasm.
+   */
+  export function netMss(fd: i32): i32;
   /** `TCP_NODELAY`: `value` 1 sends a small write at once, 0 lets Nagle batch it. */
   export const NET_TCP_NODELAY: i32;
   /**
@@ -681,6 +757,57 @@ declare module "nish:net" {
   export const NET_SO_SNDBUF: i32;
   /** `SO_RCVBUF`: the receive buffer, `value` in bytes; Linux doubles the value it stores. */
   export const NET_SO_RCVBUF: i32;
+  /**
+   * A listening Unix stream socket at `path` (`@name`: Linux's abstract
+   * namespace), its file mode 0600. A path that exists is -98, unless `flags`
+   * holds `NET_UNIX_UNLINK_STALE`; -36 a path too long, -22 an empty one.
+   */
+  export function unixListen(path: string, backlog: i32, flags: i32): i32;
+  /** `unixListen` with the socket file's mode chosen (0 to 0o777); -22 for an `@name`. */
+  export function unixListenMode(path: string, backlog: i32, flags: i32, mode: i32): i32;
+  /** A non-blocking socket connected to the listener at `path`; -11 a full backlog on Linux (-111 on Darwin), -111 nothing listening. */
+  export function unixConnect(path: string): i32;
+  /** The next connection on a Unix listener, non-blocking; -11 when none is waiting. */
+  export function unixAccept(fd: i32): i32;
+  /**
+   * Two connected sockets into `fds[0]` and `fds[1]`, and 0: `kind` is
+   * `NET_UNIX_STREAM` or `NET_UNIX_SEQPACKET` (-95 on Darwin); -22 another kind
+   * or an `fds` shorter than 2.
+   */
+  export function unixSocketPair(kind: i32, fds: i32[]): i32;
+  /**
+   * Send `buf[off..off+len)` over the Unix socket `sock` with a copy of the
+   * descriptor `fd` (`SCM_RIGHTS`): the bytes sent, or a negative errno; -22 a
+   * zero `len` or a negative `fd`, -9 a closed `sock` or `fd`, -88 a `sock`
+   * that is not a socket, -95 one that is not Unix. A stream socket can send
+   * short: the descriptor travels with the first bytes, so send the rest with
+   * `netWrite`.
+   */
+  export function sendFd(sock: i32, fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
+  /**
+   * Read at most `len` bytes into `buf[off..]` from the Unix socket `sock`, and
+   * the first descriptor that came with them into `fd[0]`, or -1: the bytes read,
+   * or a negative errno. Every other descriptor in the message is closed; the
+   * one kept is close-on-exec and keeps the sender's blocking mode. -22 a zero
+   * `len` or an empty `fd`, -9 a closed `sock`, -88 not a socket, -95 not
+   * Unix.
+   */
+  export function recvFd(sock: i32, buf: u8[], off: i32, len: i32, fd: i32[]): i32;
+  /**
+   * The peer of the Unix socket `fd` as of its connect: `out` gets its pid, uid
+   * and gid, and the answer is 0; the pid is -1 where Darwin has no
+   * `LOCAL_PEERPID`. A uid or gid of 2^31 or above wraps (-2 is uid
+   * 4294967294). -22 an `out` shorter than 3, -9 a closed `fd`, -88 not a
+   * socket, -95 not Unix, -107 a socket with no peer (a listener, or one never
+   * connected).
+   */
+  export function peerCredentials(fd: i32, out: i32[]): i32;
+  /** `unixListen` flag: unlink a socket file nothing listens on, then bind. */
+  export const NET_UNIX_UNLINK_STALE: i32;
+  /** `unixSocketPair` kind: a byte stream. */
+  export const NET_UNIX_STREAM: i32;
+  /** `unixSocketPair` kind: each write one message (`SOCK_SEQPACKET`). */
+  export const NET_UNIX_SEQPACKET: i32;
 }
 
 declare module "nish:unsafe" {

package/runtime/nish.h

@@ -200,6 +200,16 @@ extern void (*nish_fatal_hook)(void);
 /* Number to string, as `${n}` does: decimal for integers, shortest round-trip (JS Number#toString) for f64. */
 nish_str *nish_str_from_i32(int32_t v);
 nish_str *nish_str_from_f64(double v);
+/* The bytes `nish_str_from_f64` would hold, written into `out` with no NUL;
+   returns the length. 32 bytes is room to spare: the longest spelling,
+   -0.0000012345678901234567, is 25 (runtime.c says why, and runtime-test.c
+   pins it). For a caller that writes numbers into its own buffer. */
+#define NISH_F64_MAX 32
+int nish_f64_format(double v, char out[NISH_F64_MAX]);
+/* `nish_f64_format`'s bytes into `buf[at]` (std/json.ts's JsonWriter): the new
+   end, or -1, with nothing written, when `at < 0` or they do not fit before
+   `len`. `buf` may be null only when nothing fits. */
+int32_t nish_json_put_f64(uint8_t *buf, int32_t len, int32_t at, double v);
 nish_str *nish_str_from_i64(int64_t v);
 /* Unsigned decimal (WP15). u8/u16/u32 are zero-extended by the caller, so one
    symbol serves every unsigned width. */
@@ -514,6 +524,14 @@ int32_t nish_spawn_child(const nish_array *argv);
  * copied; SIGPIPE is blocked on the calling thread for the call, a SIGPIPE the
  * call raised is consumed, and the thread's mask is restored after it. */
 int32_t nish_spawn_piped(const nish_array *argv, const nish_array *in, nish_array *out, nish_array *err);
+/* `spawnWithFds(argv, fds)`: `nish_spawn_child` with the child holding
+ * `fds[i]` (element type `int32_t`) as descriptor `3 + i`, close-on-exec
+ * cleared there. More than 64 descriptors or a negative one is -EINVAL before
+ * anything starts, a source that is not open is -EBADF, and a scratch
+ * descriptor the system cannot give is -EMFILE (-EINVAL above the descriptor
+ * limit); -ENOSYS under
+ * WASI. This process's descriptors are left as they were. */
+int32_t nish_spawn_with_fds(const nish_array *argv, const nish_array *fds);
 /* `kill(pid, sig)`: send `sig` to `pid` and answer 0, or a negative errno. Only
  * 0, 2 (SIGINT), 9 (SIGKILL) and 15 (SIGTERM) are sent; any other signal, and
  * a pid of 0 or below, is -EINVAL. -ESRCH when no process has the pid, -EPERM
@@ -651,6 +669,9 @@ bool nish_is_executable(const nish_str *path);
  * whitelist, by the runtime's own id (1 `TCP_NODELAY`, 2 `TCP_QUICKACK`, 3
  * `SO_KEEPALIVE`, 4 `SO_SNDBUF`, 5 `SO_RCVBUF`); any other id is -22, and
  * `TCP_QUICKACK` off Linux is -95.
+ * `nish_net_mss(fd)`: a connected TCP socket's send MSS, from `TCP_INFO`'s
+ * `tcpi_snd_mss` or else `TCP_MAXSEG`; a plain -1, never an errno, for
+ * anything else (a closed descriptor, an unconnected or non-TCP socket).
  * `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
@@ -675,7 +696,36 @@ bool nish_is_executable(const nish_str *path);
  * into `ready` (element type `int32_t`) a token and its events, 4 added for a
  * hang-up or an error, per ready descriptor: at most `ready->len / 2` pairs
  * and at most 64 in one call. It answers the count, 0 on a timeout or an
- * interrupting signal, and -22 for a `ready` shorter than 2. */
+ * interrupting signal, and -22 for a `ready` shorter than 2.
+ *
+ * Unix-domain sockets. A `path` names a socket file, or with a leading `@`
+ * Linux's abstract namespace (-95 on Darwin); empty, holding a NUL, or a bare
+ * `@` is -22, and one too long for `sun_path` with its NUL is -36, before any
+ * socket exists. `nish_unix_listen(path, backlog, flags)` is a listening
+ * stream socket whose file has mode 0600; a path that exists is -98, unless
+ * flag 1 (`NET_UNIX_UNLINK_STALE`) unlinks a socket file nothing listens on
+ * (anything but a socket is -17, a live listener -98). `nish_unix_listen_mode`
+ * takes the mode (0..0o777, -22 for an abstract name). `nish_unix_connect(path)`
+ * connects, -11 for a full backlog on Linux (-111 on Darwin). `nish_unix_accept(fd)` takes the next
+ * connection, -11 when none waits. `nish_unix_socket_pair(kind, fds)` writes
+ * two connected sockets into `fds` (element type `int32_t`, at least 2): kind
+ * 1 a stream, kind 2 `SOCK_SEQPACKET` (-95 on Darwin). Every descriptor is
+ * non-blocking and close-on-exec.
+ *
+ * Descriptors over a Unix socket: each of the three refuses a descriptor that
+ * is closed with -9, one that is not a socket with -88 and a socket of another
+ * family with -95.
+ * `nish_send_fd(sock, fd, buf, off, len)` sends `len` bytes (at least 1, else
+ * -22, as is a negative `fd`) carrying one `SCM_RIGHTS` copy of `fd`; a
+ * stream socket can send short, the descriptor gone with the first bytes. `nish_recv_fd(sock, buf, off,
+ * len, fd)` reads at most `len` bytes (at least 1, and `fd` at least one
+ * `int32_t` long, else -22) and writes the first descriptor received, or -1,
+ * into `fd[0]`, closing every other; the one kept is close-on-exec and its
+ * status flags are left as the sender's. `nish_peer_credentials(fd, out)`
+ * writes the peer's pid, uid and gid as of the connect into `out` (at least
+ * 3, else -22), wrapping a uid or gid of 2^31 or above into `int32_t`; a
+ * socket with no peer is -ENOTCONN (-107) on both platforms, and Darwin's pid
+ * is -1 where `LOCAL_PEERPID` is missing. */
 int32_t nish_net_address(nish_array *out, const nish_str *host, int32_t port);
 int32_t nish_net_local_port(int32_t fd);
 int32_t nish_tcp_listen(const nish_str *host, int32_t port, int32_t backlog);
@@ -686,6 +736,7 @@ int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t l
 int32_t nish_net_shutdown(int32_t fd, int32_t how);
 int32_t nish_net_close(int32_t fd);
 int32_t nish_net_set_option(int32_t fd, int32_t option, int32_t value);
+int32_t nish_net_mss(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);
@@ -698,6 +749,14 @@ int32_t nish_poll_add(int32_t loop, int32_t fd, int32_t events, int32_t token);
 int32_t nish_poll_modify(int32_t loop, int32_t fd, int32_t events, int32_t token);
 int32_t nish_poll_remove(int32_t loop, int32_t fd);
 int32_t nish_poll_wait(int32_t loop, nish_array *ready, int32_t timeout_ms);
+int32_t nish_unix_listen(const nish_str *path, int32_t backlog, int32_t flags);
+int32_t nish_unix_listen_mode(const nish_str *path, int32_t backlog, int32_t flags, int32_t mode);
+int32_t nish_unix_connect(const nish_str *path);
+int32_t nish_unix_accept(int32_t fd);
+int32_t nish_unix_socket_pair(int32_t kind, nish_array *fds);
+int32_t nish_send_fd(int32_t sock, int32_t fd, const nish_array *buf, int64_t off, int64_t len);
+int32_t nish_recv_fd(int32_t sock, nish_array *buf, int64_t off, int64_t len, nish_array *fd);
+int32_t nish_peer_credentials(int32_t fd, nish_array *out);
 
 /* ---- The terminal, runtime/runtime-term.c, `nish:term` -------------------
  *
@@ -781,9 +840,12 @@ int64_t nish_cpu_online(void);
 /* WP37 `--sandbox` (runtime-sandbox.c): `nish_sandbox` confines the process to
    the capability mask `caps` from `.preinit_array`, `mode` 1 strict and 2
    best-effort, and `nish_sandbox_check` refuses to run at the top of `main`
-   when it never ran. The directory lists are a later stage's and are null.
+   when it never ran. `read_dirs` and `write_dirs` are the directories
+   Landlock scopes `fs.read` and `fs.write` to, `exec_paths` the programs
+   `process.spawn` may execute, each a run of NUL-terminated paths ended by an
+   empty one; null leaves the capability whole.
    `nish_cpu_prime` caches the pool's CPU count while /sys is still readable. */
-void nish_sandbox(int32_t caps, int32_t mode, const char *read_dirs, const char *write_dirs);
+void nish_sandbox(int32_t caps, int32_t mode, const char *read_dirs, const char *write_dirs, const char *exec_paths);
 void nish_sandbox_check(void);
 void nish_cpu_prime(void);
 void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t grain);
@@ -811,6 +873,13 @@ __attribute__((constructor)) static void nish_napi_unpooled(void) { nish_pool_di
  * calling thread, so running short of threads costs speed and never an
  * answer.
  *
+ * `scope` points at a `ThreadScope` (std/threads.ts), whose first `int32_t` is
+ * the stack `scopeWithStack` asked for, or 0. A nonzero one runs every task on
+ * a new thread of its own started with that stack, rounded up to the page,
+ * plus a guard page, none on the calling thread; if one cannot be started the
+ * program ends, saying whether the system was out of threads or memory or
+ * refused the size (`nish_stack_fail`). Without threads the word is ignored.
+ *
  * The preconditions are the language's (docs/LANGUAGE.md, "Scoped tasks"):
  * `run` writes nothing another task or the caller can see, its result is a
  * scalar it writes into its own payload, and only `finish`, on the calling

package/runtime/nish.mjs

@@ -104,9 +104,11 @@ provide("realpathSync", shim.realpathSync);
 provide("spawnSync", shim.spawnSync);
 provide("spawnSyncTo", shim.spawnSyncTo);
 provide("spawnPiped", shim.spawnPiped);
-// WP34 N12. `spawn` and `waitPid` throw, naming themselves: a child is reaped
-// by Node's event loop. `kill`, `availableParallelism` and `totalMemory` answer.
+// WP34 N12. `spawn`, `spawnWithFds` and `waitPid` throw, naming themselves: a
+// child is reaped by Node's event loop. `kill`, `availableParallelism` and
+// `totalMemory` answer.
 provide("spawn", shim.spawn);
+provide("spawnWithFds", shim.spawnWithFds);
 provide("kill", shim.kill);
 provide("waitPid", shim.waitPid);
 provide("availableParallelism", shim.availableParallelism);
@@ -147,16 +149,28 @@ for (const name of [
   "pollRemove",
   "pollWait",
   "netSetOption",
+  "netMss",
+  "unixListen",
+  "unixListenMode",
+  "unixConnect",
+  "unixAccept",
+  "unixSocketPair",
+  "sendFd",
+  "recvFd",
+  "peerCredentials",
 ]) {
   provide(name, () => shim.noNetReading(name));
 }
-// `netSetOption`'s option ids are plain numbers, so they read the same here
-// as natively: only the call that takes one throws.
+// `netSetOption`'s option ids and the `NET_UNIX_` flag and kinds are plain
+// numbers, so they read the same here as natively: only a call throws.
 provide("NET_TCP_NODELAY", 1);
 provide("NET_TCP_QUICKACK", 2);
 provide("NET_SO_KEEPALIVE", 3);
 provide("NET_SO_SNDBUF", 4);
 provide("NET_SO_RCVBUF", 5);
+provide("NET_UNIX_UNLINK_STALE", 1);
+provide("NET_UNIX_STREAM", 1);
+provide("NET_UNIX_SEQPACKET", 2);
 
 // `nish:term`. Whether a descriptor is a terminal and how big stdout's is have
 // Node's answers; reading stdin, waiting for it and raw mode throw, each naming