@amritk/nish-x86_64-linux 0.25.0 → 0.26.0

package/docs/AI.md

@@ -2137,11 +2137,18 @@ a `\u` escape `nish/json` decodes) is one unit per byte, and counts its bytes.
 it is; `i32`: the length, or a negative errno), `renameSync(from, to)` (`0` or
 a negative errno; atomic on one filesystem, `-18` across two, so write the
 temporary beside the target), `unlinkSync(path)` (`0` or a negative errno; a
-directory is refused), `writeBytes(bytes, off, len)` (a `u8[]` range to stdout
+directory is refused), `writeFileSyncMode(path, data, mode)` (the file left
+at exactly `mode` (`0..0o777`), set before the first byte, written in place; a symbolic link refused; the
+length or a negative errno), `createFileExclusiveSync(path, data, mode)` (the
+same, but `-17` when the name exists: a lock file), `mkdirSyncMode(path, mode)`
+(`0`, `-17` when it exists, the umask applies), `writeBytes(bytes, off, len)` (a `u8[]` range to stdout
 as it is, the length or a negative errno; the range panics like
 `netWrite`'s), `mkdirSync(path)` (one level, `boolean`),
 `isDirectorySync(path)`, `readdirSync(path)` (`string[] | null`, sorted by
 bytes, no `.`/`..`), `spawnSync(argv)`, `spawnSyncTo(argv, outPath, errPath)`,
+`spawnPiped(argv, stdin, stdout, stderr)` (stdin from a `u8[]`, both outputs
+appended to `u8[]`s, the status; `-2` past 16 MiB; the way to hand a child a
+secret, never argv or the environment),
 `getenv(name)` (`string | null` — unset and empty are different answers),
 `realpathSync(path)` (`string | null`; symbolic links resolved, absolute, and
 `null` when it does not resolve),
@@ -2625,6 +2632,20 @@ the array open: end it and send the rest in the next statement. Every other
 guide's [PostgreSQL page](guide/using-nish/postgres.md#array-parameters) its
 walk-through.)
 
+**Read PostgreSQL ids, counts and times without parsing them** — there is no
+driver option for binary results: in `nish/net/postgres`, open the bind with
+`bindStartBinary(name)` instead of `bindStart(name)`, and every result column
+of that execution comes in binary. Read an `int2`/`int4`/`int8` with
+`binaryInt(c)`, a `bool` with `binaryBool(c)`, a `float8` with
+`binaryFloat(c)`, a `timestamptz` with `conn.binary.timestamp(conn.inputBuffer(),
+conn.colStart(c), conn.colLength(c), out, at)` (or its microseconds since 2000
+with `binaryInt(c)`, written out by `conn.binary.iso(micros, out, at)`), and a
+`text` column with `columnText(c)` as before. Cast anything else (`numeric`,
+`text[]`) to `text` in the SQL. (No block, as for `nish/text`;
+`tests/postgres/live`'s `binary` scenario runs it against a server, and the
+user guide's [PostgreSQL page](guide/using-nish/postgres.md#binary-results)
+its walk-through.)
+
 **Batch a server's keyed reads into one PostgreSQL query** — there is no
 DataLoader and no `setTimeout` to collect a tick's keys: in `nish/net/postgres`,
 a `PgBatcher` built from a `PgBatchConfig` (`name`, `select` reading the key as

package/package.json

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

package/runtime/core/host.d.ts

@@ -47,6 +47,9 @@ export declare function appendFileSync(path: string, data: string): void;
 export declare function writeFileBytesSync(path: string, bytes: readonly u8[]): i32;
 export declare function renameSync(from: string, to: string): i32;
 export declare function unlinkSync(path: string): i32;
+export declare function writeFileSyncMode(path: string, data: string, mode: i32): i32;
+export declare function createFileExclusiveSync(path: string, data: string, mode: i32): i32;
+export declare function mkdirSyncMode(path: string, mode: i32): i32;
 export declare function mkdirSync(path: string): boolean;
 export declare function isDirectorySync(path: string): boolean;
 export declare function readdirSync(path: string): string[] | null;
@@ -56,6 +59,7 @@ export declare function arch(): string;
 export declare function getenv(name: string): string | null;
 export declare function spawnSync(argv: string[]): number;
 export declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+export declare function spawnPiped(argv: string[], stdin: readonly u8[], stdout: u8[], stderr: u8[]): i32;
 export declare function kill(pid: i32, sig: i32): i32;
 export declare function availableParallelism(): i32;
 export declare function totalMemory(): i64;

package/runtime/core/host.mjs

@@ -157,6 +157,18 @@ export function unlinkSync(path) {
   return host.call("unlinkSync", [path]);
 }
 
+export function writeFileSyncMode(path, data, mode) {
+  return host.call("writeFileSyncMode", [path, data, mode]);
+}
+
+export function createFileExclusiveSync(path, data, mode) {
+  return host.call("createFileExclusiveSync", [path, data, mode]);
+}
+
+export function mkdirSyncMode(path, mode) {
+  return host.call("mkdirSyncMode", [path, mode]);
+}
+
 export function mkdirSync(path) {
   return host.call("mkdirSync", [path]);
 }
@@ -193,6 +205,18 @@ export function spawnSyncTo(argv, out, err) {
   return host.call("spawnSyncTo", [argv, out, err]);
 }
 
+/**
+ * `spawnPiped(argv, stdin, stdout, stderr)`: the host runs the child and hands
+ * back its status and both streams' bytes, and they are appended here, as the
+ * runtime appends them to the caller's arrays.
+ */
+export function spawnPiped(argv, input, out, err) {
+  const [status, outBytes, errBytes] = host.call("spawnPiped", [argv, input]);
+  for (const b of outBytes) out.push(b);
+  for (const b of errBytes) err.push(b);
+  return status;
+}
+
 export function kill(pid, sig) {
   return host.call("kill", [pid, sig]);
 }

package/runtime/nish.d.ts

@@ -276,6 +276,33 @@ declare function writeFileBytesSync(path: string, bytes: readonly u8[]): i32;
 declare function renameSync(from: string, to: string): i32;
 /** The name `path` removed: 0, or a negative errno. A directory is refused, not removed. */
 declare function unlinkSync(path: string): i32;
+/**
+ * `writeFileSync` with an explicit `mode`: the file is exactly `mode`
+ * (`0o600` for a secret) before a byte of `data` is in it, whatever the umask
+ * or a file already there had, and a symbolic link at the path is refused
+ * (-40). The byte count, or a negative errno: -22 for a mode outside
+ * 0..0o777, the setuid, setgid and sticky bits included. The file is
+ * truncated and written in place, so a crash or a failed write leaves it
+ * empty or partial, and a file this process may write but does not own is
+ * emptied before the mode change answers -1 (`EPERM`). For a file that must
+ * be the old one or the new one, write a temporary name with this and move it
+ * with `renameSync`. Never an exit.
+ */
+declare function writeFileSyncMode(path: string, data: string, mode: i32): i32;
+/**
+ * `data` in a new file of exactly `mode`, created only if nothing is at `path`:
+ * -17 when something is, a dangling symbolic link included. Of several
+ * processes racing for one path exactly one succeeds, so it takes a lock. The
+ * byte count, or a negative errno; a write that fails after the create
+ * removes the file, so the lock is not left taken. Never an exit.
+ */
+declare function createFileExclusiveSync(path: string, data: string, mode: i32): i32;
+/**
+ * One directory made with `mode` less the umask (`0o700` is exact under any
+ * umask that leaves the owner's bits): 0, or a negative errno. A path already
+ * there is -17 and its mode is not changed; -22 for a mode outside 0..0o777.
+ */
+declare function mkdirSyncMode(path: string, mode: i32): i32;
 /** One directory, not recursive; whether a directory is there afterwards. */
 declare function mkdirSync(path: string): boolean;
 /** Whether a directory is at `path` right now. One `stat`, and never an exit. */
@@ -299,6 +326,13 @@ declare function spawnSync(argv: string[]): number;
  * either path is refused, as `writeFileSync` refuses one, and the answer is -1.
  */
 declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+/**
+ * The same run with all three streams on pipes: `stdin` is written to the
+ * child and closed, and what it prints is appended to `stdout` and `stderr`.
+ * The status as `spawnSync` answers it, or -2 when a stream passed 16 MiB:
+ * 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;
 /**
  * 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
@@ -492,6 +526,9 @@ declare var crypto: {
 //
 // `docs/LANGUAGE.md` -> Builtins -> Builtin modules is the normative list.
 
+// Every negative errno a file call answers is the platform's own, untranslated:
+// the numbers shown here are Linux's (-2 ENOENT, -17 EEXIST, -18 EXDEV, -22
+// EINVAL, -40 ELOOP), and Darwin's differ (ELOOP is -62 there).
 declare module "nish:fs" {
   export function readFileSync(path: string): string;
   export function readFileSyncOrNull(path: string): string | null;
@@ -506,6 +543,12 @@ declare module "nish:fs" {
   export function renameSync(from: string, to: string): i32;
   /** 0, or a negative errno: a directory is refused, not removed. */
   export function unlinkSync(path: string): i32;
+  /** The byte count, or a negative errno; the file is exactly `mode` (0..0o777) before it holds a byte, a link refused, written in place. */
+  export function writeFileSyncMode(path: string, data: string, mode: i32): i32;
+  /** As `writeFileSyncMode`, but -17 when anything is at `path`: one racer wins; a failed write removes the file. */
+  export function createFileExclusiveSync(path: string, data: string, mode: i32): i32;
+  /** 0, or a negative errno: -17 for a path already there, whose mode is left alone. */
+  export function mkdirSyncMode(path: string, mode: i32): i32;
   /** `true` when the directory was created, `false` when it already existed. */
   export function mkdirSync(path: string): boolean;
   export function isDirectorySync(path: string): boolean;
@@ -530,6 +573,11 @@ declare module "nish:process" {
    * at either path is refused, and the answer is -1.
    */
   export function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+  /**
+   * The same run with `stdin` written to the child and its stdout and stderr
+   * appended to the two arrays: the status, or -2 past 16 MiB on a stream.
+   */
+  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;
   /** Send 0, 2, 9 or 15 to `pid`: 0, or a negative errno; any other signal is -22. */

package/runtime/nish.h

@@ -403,10 +403,24 @@ nish_array *nish_read_file_bytes(const nish_str *path);
  * errno — -EXDEV for a rename across file systems, which moves nothing, and
  * -EISDIR or -EPERM for a directory handed to `nish_unlink`, which never calls
  * rmdir. A path holding a NUL answers -EINVAL, not -ENOENT, so a program can
- * tell a malformed path from a missing file. */
+ * tell a malformed path from a missing file. The numbers are the platform's
+ * errno values, untranslated: -ELOOP is -40 on Linux and -62 on Darwin. */
 int32_t nish_rename(const nish_str *from, const nish_str *to);
 int32_t nish_unlink(const nish_str *path);
 int32_t nish_write_file_bytes(const nish_str *path, const nish_array *bytes);
+/* `writeFileSyncMode(path, data, mode)`, `createFileExclusiveSync(path, data,
+ * mode)` and `mkdirSyncMode(path, mode)`: a file written, or created only if
+ * nothing is at the path (`O_EXCL`), then `fchmod`ed to exactly `mode` before a
+ * byte is written; a directory made with `mode & ~umask`. A link at a file's
+ * path is refused. The file writers answer the byte count and `nish_mkdir_mode`
+ * 0, or a negative platform errno: -EEXIST for an exclusive create or a mkdir
+ * that finds the path taken (a directory's mode is then left alone), -EINVAL
+ * for a mode outside 0..0777 (the setuid, setgid and sticky bits included) or
+ * a path holding a NUL, -ENOSYS under WASI. A failed exclusive create leaves
+ * no file behind. */
+int32_t nish_write_file_mode(const nish_str *path, const nish_str *data, int32_t mode);
+int32_t nish_create_file_exclusive(const nish_str *path, const nish_str *data, int32_t mode);
+int32_t nish_mkdir_mode(const nish_str *path, int32_t mode);
 /* `writeBytes(bytes, off, len)` (nish:io), in runtime-os.c: the bytes
  * `[off, off + len)` of a `u8[]` on stdout, a short write finished and `EINTR`
  * retried. The caller has range-checked `off` and `len`. Answers `len`, or the
@@ -438,6 +452,17 @@ int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_st
  * own error otherwise, and -ENOSYS under WASI. The child is reaped by
  * `nish_wait_pid`. */
 int32_t nish_spawn_child(const nish_array *argv);
+/* `spawnPiped(argv, stdin, stdout, stderr)`: start element 0 of `argv` as
+ * `nish_spawn` does, with the bytes of `stdin` (a `u8[]`) on its standard input
+ * and its standard output and error appended to `stdout` and `stderr`, wait for
+ * it, and answer `nish_spawn`'s status. -1 is `nish_spawn`'s -1, a pipe or
+ * `poll` that fails included, and always under WASI. -2 is a stream that passed
+ * 16 MiB: the child is killed with SIGKILL and reaped, and that array holds the
+ * stream's first 16 MiB. The two output arrays grow as `push` grows them, so
+ * the compiler treats both as pushed. `stdin` is read in place and never
+ * 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);
 /* `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

package/runtime/nish.mjs

@@ -94,12 +94,16 @@ provide("appendFileSync", shim.appendFileSync);
 provide("writeFileBytesSync", shim.writeFileBytesSync);
 provide("renameSync", shim.renameSync);
 provide("unlinkSync", shim.unlinkSync);
+provide("writeFileSyncMode", shim.writeFileSyncMode);
+provide("createFileExclusiveSync", shim.createFileExclusiveSync);
+provide("mkdirSyncMode", shim.mkdirSyncMode);
 provide("mkdirSync", shim.mkdirSync);
 provide("isDirectorySync", shim.isDirectorySync);
 provide("readdirSync", shim.readdirSync);
 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.
 provide("spawn", shim.spawn);

package/runtime/node.mjs

@@ -102,6 +102,46 @@ const unlinkSync = (path) => errnoOr(0, () => fs.unlinkSync(path));
 const writeFileBytesSync = (path, bytes) =>
   errnoOr(bytes.length, () => fs.writeFileSync(path, Uint8Array.from(bytes), { flag: WRITE_FLAGS, mode: 0o644 }));
 
+/**
+ * `writeFileSyncMode` and `createFileExclusiveSync`'s shared body, as
+ * `runtime-os.c`'s: the file opened with `flag`, `fchmod`ed to exactly `mode`
+ * before a byte is written, then every byte of `data`, then the count, or a
+ * negative errno. A mode outside 0..0o777 is -22 before the file is touched.
+ * After an exclusive create (`"wx"`), any failure unlinks the file it made.
+ */
+function putFileMode(path, data, flag, mode) {
+  if (!(mode >= 0 && mode <= 0o777)) return -22;
+  let fd;
+  try {
+    fd = fs.openSync(path, flag, mode);
+  } catch (e) {
+    return negErrno(e);
+  }
+  let r;
+  try {
+    fs.fchmodSync(fd, mode);
+    const buf = Buffer.from(data, "utf8");
+    for (let done = 0; done < buf.length; ) done += fs.writeSync(fd, buf, done);
+    r = buf.length;
+  } catch (e) {
+    r = negErrno(e);
+  }
+  const closed = errnoOr(0, () => fs.closeSync(fd));
+  const answer = r >= 0 && closed < 0 ? closed : r;
+  if (answer < 0 && flag === "wx") errnoOr(0, () => fs.unlinkSync(path));
+  return answer;
+}
+
+/** `writeFileSyncMode(path, data, mode)`: `WRITE_FLAGS`, so a link at the path is refused. */
+const writeFileSyncMode = (path, data, mode) => putFileMode(path, data, WRITE_FLAGS, mode);
+
+/** `createFileExclusiveSync(path, data, mode)`: `"wx"`, -17 when anything is at the path. */
+const createFileExclusiveSync = (path, data, mode) => putFileMode(path, data, "wx", mode);
+
+/** `mkdirSyncMode(path, mode)`: 0, or a negative errno; -17 for a path already there. */
+const mkdirSyncMode = (path, mode) =>
+  mode >= 0 && mode <= 0o777 ? errnoOr(0, () => fs.mkdirSync(path, { mode })) : -22;
+
 /**
  * `writeBytes`'s write, after the core checked the range `[from, to)`: every
  * byte to stdout, then the count, or a negative errno. `fs.writeSync` may
@@ -268,6 +308,41 @@ function spawnSyncTo(argv, out, err) {
   return spawnImpl(argv, out, err);
 }
 
+/** The bytes `spawnPiped` keeps of one stream, as `runtime-os.c`'s `NISH_PIPED_CAP`. */
+const PIPED_CAP = 16 * 1024 * 1024;
+
+/**
+ * `spawnPiped(argv, stdin)`'s run, after the core took it apart: the status
+ * and the two streams' bytes, which the core appends to the caller's arrays.
+ * The status is `spawnImpl`'s, and -2 when a stream passed `PIPED_CAP`: Node
+ * then kills the child with `SIGKILL`, as the runtime does, and reports
+ * `ENOBUFS`, and what it read is cut to the cap here as the runtime keeps it.
+ * A child that exits without reading its stdin is not an error on either side.
+ */
+function spawnPiped(argv, input) {
+  if (argv.length === 0) return [-1, [], []];
+  let r;
+  // Node throws, rather than reporting, for an empty command or a NUL in any
+  // argument, which the runtime answers -1 for without starting a child.
+  try {
+    r = child_process.spawnSync(argv[0], argv.slice(1), {
+      input: Uint8Array.from(input),
+      maxBuffer: PIPED_CAP,
+      killSignal: "SIGKILL",
+    });
+  } catch {
+    return [-1, [], []];
+  }
+  const bytes = (b) => (b === null || b === undefined ? [] : Array.from(b.subarray(0, PIPED_CAP)));
+  const out = bytes(r.stdout);
+  const err = bytes(r.stderr);
+  // `EPIPE` is the child closing its stdin unread, which Node reports with
+  // the status it still waited for; the runtime ignores it the same way.
+  if (r.error !== undefined && r.error.code !== "EPIPE") return [r.error.code === "ENOBUFS" ? -2 : -1, out, err];
+  if (r.signal !== null && r.signal !== undefined) return [128 + (os.constants.signals[r.signal] ?? 0), out, err];
+  return [r.status === null ? -1 : r.status, out, err];
+}
+
 /**
  * `kill(pid, sig)`: 0, or a negative errno, as `runtime-os.c`'s `nish_kill`
  * answers. Only 0, 2, 9 and 15 are sent and a pid of 0 or below is refused,
@@ -393,6 +468,9 @@ const CALLS = {
   writeFileBytesSync,
   renameSync,
   unlinkSync,
+  writeFileSyncMode,
+  createFileExclusiveSync,
+  mkdirSyncMode,
   writeBytes,
   mkdirSync,
   isDirectorySync,
@@ -403,6 +481,7 @@ const CALLS = {
   getenv,
   spawnSync,
   spawnSyncTo,
+  spawnPiped,
   kill,
   availableParallelism,
   totalMemory,

package/runtime/runtime-os.c

@@ -49,6 +49,7 @@
 #include <unistd.h>
 #ifndef __wasi__
 /* WASI has no processes, so `spawn.h` and `wait.h` do not exist there. */
+#include <poll.h>
 #include <signal.h>
 #include <spawn.h>
 #include <sys/resource.h>
@@ -170,20 +171,9 @@ nish_str *nish_read_file(const nish_str *path) {
   return s;
 }
 
-/* `O_NOFOLLOW` (docs/security/runtime.md, RT-4): a symbolic link as the last
-   component of the path is refused, as an unwritable file is, rather than
-   followed to whatever file it names. `nish file.ts` writes `file.ll` beside
-   its source, so a link planted at that name in a checkout would otherwise
-   truncate any file the user can write. A link among the directories on the
-   way is still followed.
-
-   `O_CLOEXEC` for the reason the read has it (RT-12), and `EINTR` is retried
-   as the read retries it (RT-13): a write cut short is finished, and one that
-   fails is `cannot write`, never a silently short file.
-
-   The loop is `nish_put_all`, which `writeFileBytesSync` and `writeBytes`
-   share: all `n` bytes of `p` to `fd`, answering 0 or the negative errno of
-   the write that failed (-EIO for one that wrote nothing). */
+/* All `n` bytes of `p` to `fd`, answering 0 or the negative errno of the
+   write that failed (-EIO for one that wrote nothing). A write cut short is
+   finished and `EINTR` retried (RT-13). Every writer below shares it. */
 static int32_t nish_put_all(int fd, const char *p, uint64_t n) {
   for (uint64_t done = 0; done < n;) {
     ssize_t k = write(fd, p + done, n - done);
@@ -193,6 +183,17 @@ static int32_t nish_put_all(int fd, const char *p, uint64_t n) {
   }
   return 0;
 }
+
+/* `O_NOFOLLOW` (docs/security/runtime.md, RT-4): a symbolic link as the last
+   component of the path is refused, as an unwritable file is, rather than
+   followed to whatever file it names. `nish file.ts` writes `file.ll` beside
+   its source, so a link planted at that name in a checkout would otherwise
+   truncate any file the user can write. A link among the directories on the
+   way is still followed.
+
+   `O_CLOEXEC` for the reason the read has it (RT-12), and the bytes go out
+   through `nish_put_all`, so a write that fails is `cannot write`, never a
+   silently short file. */
 static void nish_put_file(const nish_str *path, const nish_str *data, int flags) {
   int fd = open(nish_cpath(path), O_WRONLY | O_CREAT | O_NOFOLLOW | O_CLOEXEC | flags, 0644);
   if (fd < 0 || nish_put_all(fd, data->data, data->len) < 0) nish_io_fail("write ", path);
@@ -248,6 +249,73 @@ int32_t nish_write_file_bytes(const nish_str *path, const nish_array *bytes) {
   return r < 0 ? r : (int32_t)bytes->len;
 }
 
+/* ---- Files and directories with an explicit mode (docs/security/runtime.md,
+   RT-24 to RT-26): `writeFileSyncMode`, `createFileExclusiveSync` and
+   `mkdirSyncMode`. Each answers a value and never exits, as the writers just
+   above do. A mode outside 0..0777 is -EINVAL before any system call: the
+   setuid, setgid and sticky bits are refused, not applied, so the mode asked
+   for is the mode the file has. WASI
+   has no file modes to apply, so there each answers -ENOSYS and creates
+   nothing rather than a file whose mode was not set. */
+
+/* The two file writers' shared body: `open(p, O_WRONLY | O_CREAT |
+   O_NOFOLLOW | O_CLOEXEC | flags, mode)`, then `fchmod(fd, mode)` before a
+   byte is written, so the file is exactly `mode` whatever the umask and
+   whatever mode a file already there had: no reader that opens it while it is
+   written finds it wider (RT-24). Then the data through `nish_put_all` and a
+   checked `close`, as `nish_write_file_bytes` does. The open truncates
+   before the `fchmod`, so a file there that this process may write but does
+   not own is emptied and then answers -EPERM. When `flags` holds `O_EXCL`,
+   any failure after the create unlinks the file this call made, so a lock
+   whose write failed does not stay taken. */
+static int32_t nish_put_file_mode(const nish_str *path, const nish_str *data, int flags, int32_t mode) {
+  const char *p = nish_cpath(path);
+  if (p != path->data || mode < 0 || mode > 0777) return -EINVAL;
+  if (data->len > NISH_LENGTH_MAX) return -EFBIG;
+#ifdef __wasi__
+  (void)flags;
+  return -ENOSYS;
+#else
+  int fd = open(p, O_WRONLY | O_CREAT | O_NOFOLLOW | O_CLOEXEC | flags, (mode_t)mode);
+  if (fd < 0) return -errno;
+  int32_t r = fchmod(fd, (mode_t)mode) == 0 ? 0 : -errno;
+  if (r == 0) r = nish_put_all(fd, data->data, data->len);
+  if (close(fd) != 0 && r == 0 && errno != EINTR) r = -errno;
+  if (r < 0 && (flags & O_EXCL)) unlink(p);
+  return r < 0 ? r : (int32_t)data->len;
+#endif
+}
+
+/* `writeFileSyncMode(path, data, mode)`: `writeFileSync` with the mode given
+   and an answer instead of an exit. A link at the path is refused (-ELOOP on
+   Linux) and the file it names is untouched (RT-25). */
+int32_t nish_write_file_mode(const nish_str *path, const nish_str *data, int32_t mode) {
+  return nish_put_file_mode(path, data, O_TRUNC, mode);
+}
+
+/* `createFileExclusiveSync(path, data, mode)`: `O_EXCL`, so the path is
+   created by this call or the call answers -EEXIST, a link there included,
+   dangling or not. Of N processes racing for one path exactly one wins, which
+   is what a lock file needs; a winner whose write then fails removes the file
+   and answers the error. */
+int32_t nish_create_file_exclusive(const nish_str *path, const nish_str *data, int32_t mode) {
+  return nish_put_file_mode(path, data, O_EXCL, mode);
+}
+
+/* `mkdirSyncMode(path, mode)`: mkdir(2) with `mode`, one directory, not
+   recursive. A path already there is -EEXIST and its mode is left as it was.
+   The kernel applies the umask, so the directory is `mode & ~umask`: 0700 is
+   exact under any umask that leaves the owner's bits (RT-26). */
+int32_t nish_mkdir_mode(const nish_str *path, int32_t mode) {
+  const char *p = nish_cpath(path);
+  if (p != path->data || mode < 0 || mode > 0777) return -EINVAL;
+#ifdef __wasi__
+  return -ENOSYS;
+#else
+  return mkdir(p, (mode_t)mode) == 0 ? 0 : -errno;
+#endif
+}
+
 /* `writeBytes(bytes, off, len)` (nish:io): the bytes `[off, off + len)` of a
    `u8[]` on stdout, through `nish_put_all`, so a short write is finished and `EINTR` retried. The
    emitter has range-checked `off` and `len` against `bytes->len`
@@ -290,17 +358,19 @@ _Bool nish_mkdir(const nish_str *path) {
    value rather than through a child that has already run.
 
    `out` and `err` are paths for the child's stdout and stderr, or NULL to let
-   it inherit this process's. Every spawn builtin starts its child here, so the
+   it inherit this process's; `dup`, when not NULL, is three descriptors the
+   child takes as its stdin, stdout and stderr instead (`spawnPiped`'s pipes). Every spawn builtin starts its child here, so the
    argv vector and the redirects are written once; it is `static`, so a program
    that spawns nothing loses it to `--gc-sections`. The answer is the child's
    pid, or a negative errno: -EINVAL for an empty argv or an argument holding a
    NUL, and `posix_spawnp`'s own error otherwise (-ENOENT for a command that is
    not on PATH, on glibc). */
-static int32_t nish_spawn_start(const nish_array *argv, const nish_str *out, const nish_str *err) {
+static int32_t nish_spawn_start(const nish_array *argv, const nish_str *out, const nish_str *err, const int *dup) {
 #ifdef __wasi__
   (void)argv;
   (void)out;
   (void)err;
+  (void)dup;
   return -ENOSYS;
 #else
   if (!argv->len) return -EINVAL; /* argv[0] would read past an empty array */
@@ -323,6 +393,13 @@ static int32_t nish_spawn_start(const nish_array *argv, const nish_str *out, con
   posix_spawn_file_actions_t fa;
   int failed = posix_spawn_file_actions_init(&fa);
   if (failed) return -failed;
+  /* A `dup2` action that could not be recorded would start the child on this
+     process's own stream in its place, so it fails the spawn. */
+  for (int k = 0; dup && k < 3 && !failed; k++) failed = posix_spawn_file_actions_adddup2(&fa, dup[k], k);
+  if (failed) {
+    posix_spawn_file_actions_destroy(&fa);
+    return -failed;
+  }
   const nish_str *to[2] = { out, err };
   for (int k = 0; k < 2; k++) {
     /* The child opens the file, not this process: a redirect that this process
@@ -348,7 +425,7 @@ static int32_t nish_exit_code(int status) {
 /* The two blocking builtins: start, then wait for that one child. A failed
    start is -1, the answer they have always given. */
 static int32_t nish_spawn_impl(const nish_array *argv, const nish_str *out, const nish_str *err) {
-  int32_t pid = nish_spawn_start(argv, out, err);
+  int32_t pid = nish_spawn_start(argv, out, err, 0);
   if (pid < 0) return -1;
 #ifdef __wasi__
   return -1;
@@ -379,7 +456,160 @@ int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_st
 /* `spawn(argv)`: the child's pid, or a negative errno, without waiting. The
    child is this process's until a `waitPid` reaps it; one never reaped stays
    a zombie until the program exits, as it would in C. */
-int32_t nish_spawn_child(const nish_array *argv) { return nish_spawn_start(argv, 0, 0); }
+int32_t nish_spawn_child(const nish_array *argv) { return nish_spawn_start(argv, 0, 0, 0); }
+
+/* `spawnPiped(argv, stdin, stdout, stderr)`: run the child as `nish_spawn`
+   does, with `stdin`'s bytes on its standard input and its standard output
+   and error appended to `stdout` and `stderr`, and answer its status. -1 is
+   `nish_spawn`'s failure (an empty argv, a NUL, a child that cannot start or
+   be waited for, a pipe or `poll` that fails), and -2 is a stream that passed
+   NISH_PIPED_CAP bytes: the child is killed with SIGKILL and reaped, and the
+   array holds the first NISH_PIPED_CAP bytes of that stream.
+
+   The three pipes are close-on-exec, so no other child this process starts
+   inherits an end, and each end is moved off descriptors 0 to 2, where a
+   `dup2` onto itself would leave close-on-exec set and the child without
+   that stream. Darwin has no `pipe2`, so there an end is close-on-exec only
+   once `F_DUPFD_CLOEXEC` has moved it: a child another thread starts in
+   that window inherits it (docs/security/runtime.md, RT-30).
+
+   One `poll` loop over non-blocking ends writes stdin and reads both outputs
+   as each is ready, so a child that fills its stdout before it reads all its
+   stdin, or the reverse, cannot deadlock against this process. A child that
+   exits, or closes its stdin, before reading everything ends the writing
+   with EPIPE rather than SIGPIPE: the signal is blocked on this thread once
+   the child has started, the one a write raised is taken off the pending
+   set, and the mask is put back before the answer (docs/security/runtime.md,
+   RT-29). Ignoring it instead would be process-wide, and every child
+   started meanwhile, this one included, would inherit SIGPIPE ignored and
+   never die of a reader that has gone.
+
+   The bytes are written from the caller's array as they stand, and nothing
+   copies them: the only copies are the kernel's pipe buffer and the child.
+   The length is read once, so `stdout` being the same array as `stdin`
+   appends to it without feeding the output back in, and the pointer at each
+   write, because that array moves when it grows and its stdin bytes stay
+   its first `n`. */
+#define NISH_PIPED_CAP (16u << 20)
+#ifndef __wasi__
+static int nish_pipe(int *p) {
+#ifdef __linux__
+  if (pipe2(p, O_CLOEXEC)) return -1;
+#else
+  if (pipe(p)) return -1;
+#endif
+  for (int k = 0; k < 2; k++) {
+#ifdef __linux__
+    if (p[k] > 2) continue;
+#endif
+    int moved = fcntl(p[k], F_DUPFD_CLOEXEC, 3);
+    close(p[k]);
+    p[k] = moved;
+    if (moved < 0) return -1;
+  }
+  return 0;
+}
+
+#endif
+
+int32_t nish_spawn_piped(const nish_array *argv, const nish_array *in, nish_array *out, nish_array *err) {
+#ifdef __wasi__
+  (void)argv;
+  (void)in;
+  (void)out;
+  (void)err;
+  return -1;
+#else
+  uint64_t n = in->len, sent = 0, got[3] = { 0, 0, 0 };
+  int p[6] = { -1, -1, -1, -1, -1, -1 };
+  int32_t rc = -1;
+  if (nish_pipe(p) || nish_pipe(p + 2) || nish_pipe(p + 4)) goto done;
+  int child[3] = { p[0], p[3], p[5] };
+  int32_t pid = nish_spawn_start(argv, 0, 0, child);
+  /* The child holds its ends now; this process keeps only its own. */
+  for (int k = 0; k < 3; k++) {
+    close(child[k]);
+    p[k ? 2 * k + 1 : 0] = -1;
+  }
+  if (pid < 0) goto done;
+  sigset_t pipe_sig, mask, pending;
+  sigemptyset(&pipe_sig);
+  sigaddset(&pipe_sig, SIGPIPE);
+  pthread_sigmask(SIG_BLOCK, &pipe_sig, &mask);
+  sigpending(&pending);
+  int queued = sigismember(&pending, SIGPIPE);
+  struct pollfd f[3] = { { p[1], POLLOUT, 0 }, { p[2], POLLIN, 0 }, { p[4], POLLIN, 0 } };
+  p[1] = p[2] = p[4] = -1;
+  /* A blocking end could stall the loop on one stream while the child fills
+     another, so an end that stays blocking fails the run: the loop is skipped
+     and the child killed. */
+  rc = 0;
+  for (int k = 0; k < 3; k++)
+    if (fcntl(f[k].fd, F_SETFL, O_NONBLOCK) < 0) rc = -1;
+  if (!n) {
+    close(f[0].fd);
+    f[0].fd = -1;
+  }
+  nish_array *to[3] = { 0, out, err };
+  while (!rc && (f[0].fd >= 0 || f[1].fd >= 0 || f[2].fd >= 0)) {
+    if (poll(f, 3, -1) < 0) {
+      if (errno != EINTR) rc = -1;
+      continue;
+    }
+    if (f[0].revents) {
+      ssize_t k = write(f[0].fd, in->data + sent, n - sent);
+      if (k > 0) sent += k;
+      if (sent == n || (k < 0 && errno != EINTR && errno != EAGAIN)) {
+        close(f[0].fd);
+        f[0].fd = -1;
+      }
+    }
+    for (int s = 1; s < 3 && !rc; s++) {
+      if (!f[s].revents) continue;
+      nish_array *a = to[s];
+      /* Grown as `push` grows it, so the array keeps the shape every other
+         array has, and an ASan build tracks the block the same way. */
+      if (a->len == a->cap) nish_array_grow(a, 1);
+      /* One byte past the cap at most, which is how a stream that ends at
+         exactly the cap is told from one that goes on. */
+      uint64_t room = a->cap - a->len, left = NISH_PIPED_CAP + 1 - got[s];
+      ssize_t k = read(f[s].fd, a->data + a->len, room < left ? room : left);
+      if (k > 0) {
+        a->len += k;
+        got[s] += k;
+        if (got[s] > NISH_PIPED_CAP) {
+          a->len--;
+          rc = -2;
+        }
+      } else if (!k || (errno != EINTR && errno != EAGAIN)) {
+        close(f[s].fd);
+        f[s].fd = -1;
+      }
+    }
+  }
+  sigpending(&pending);
+  if (!queued && sigismember(&pending, SIGPIPE)) {
+    int sig;
+    sigwait(&pipe_sig, &sig);
+  }
+  pthread_sigmask(SIG_SETMASK, &mask, 0);
+  if (rc) kill(pid, SIGKILL);
+  for (int k = 0; k < 3; k++)
+    if (f[k].fd >= 0) close(f[k].fd);
+  int status;
+  while (waitpid(pid, &status, 0) < 0) {
+    if (errno != EINTR) {
+      rc = -1;
+      break;
+    }
+  }
+  if (!rc) rc = nish_exit_code(status);
+done:
+  for (int k = 0; k < 6; k++)
+    if (p[k] >= 0) close(p[k]);
+  return rc;
+#endif
+}
 
 /* `kill(pid, sig)`: 0, or a negative errno. Only the four signals a program
    asks a child to stop or report with are sent -- 0 (is it there), SIGINT,

package/std/README.md

@@ -239,7 +239,7 @@ reads one, and it still takes its randomness as an argument.
 | [`net/webtransport.ts`](./net/webtransport.ts) | `WebTransport`, the server side of WebTransport over HTTP/3 as draft-ietf-webtrans-http3-02 has it and Chrome and `wtransport` 0.7 negotiate it, a layer over one `Http3Connection` whose `Http3Config.webtransportSessions` turns it on (extended CONNECT, SETTINGS_H3_DATAGRAM and the draft's two WebTransport settings): `next()` answers `WT_SESSION` (the program `accept`s or `refuse`s it), `WT_DATAGRAM`, `WT_STREAM`, `WT_STREAM_DATA`, `WT_STREAM_END`, `WT_STREAM_RESET`, `WT_STREAM_STOPPED`, `WT_WRITABLE`, `WT_DRAIN` and `WT_CLOSED`, and passes a plain request's `H3_*` events through; `sendDatagram` (the quarter stream ID, then the payload), `openStream`, `write`, `resetStream`, `stopSending`, `close` (CLOSE_WEBTRANSPORT_SESSION) and `drain`. Streams that arrive before their session wait, bounded; every cap is fixed at start-up, and a warm session allocates nothing per datagram or stream (`docs/security/webtransport.md`) | RFC 9220, RFC 9297 and draft-02: a Nish client over QUIC — sessions, datagrams at the size limits, streams both ways, close and drain from either side, every refusal — and one exchange recorded from a `wtransport` 0.7 client replayed byte for byte (`tests/link/net_webtransport`) |
 | [`net/http-compress.ts`](./net/http-compress.ts) | Content coding for HTTP responses: `httpAcceptEncoding(buf, start, end, offered)` reads an `Accept-Encoding` value (q-values, `*`, `identity`, `x-gzip`) into `HTTP_CODING_GZIP`, `HTTP_CODING_DEFLATE`, `HTTP_CODING_IDENTITY` or `HTTP_CODING_NONE`, allocating nothing; `HttpCompressor(level, minLength, maxLength)` gzips a body into its own buffer when it is worth it (-1 to send it as it is) and builds the response fields (`addFields`: `Content-Encoding: gzip` and, while `vary`, `Vary: Accept-Encoding`). On HTTP/1.1, `Http1Connection.acceptEncoding()` and `respondEncoded(status, names, values, body, off, len, enc, coding)` answer a request in one call with the compressed `Content-Length`, or nothing at all (`H1_AGAIN`, `H1_INVALID`). Opt-in; BREACH is the program's to avoid (`docs/security/compress.md`) | RFC 9110 §8.4 and §12.5.3: the negotiation table, and sans-IO responses gunzipped back (`tests/link/std_http_compress`) |
 | [`net/router.ts`](./net/router.ts) | `Router`, a method and path router that knows no carrier and allocates nothing per match: `add(method, pattern)` answers the route's index (0, 1, 2 in the order added) or a refusal — `ROUTER_BAD_PATTERN`, `ROUTER_BAD_METHOD`, `ROUTER_TOO_LONG`, `ROUTER_AMBIGUOUS` (`*` not last), `ROUTER_DUPLICATE` (the same shape and method, whatever the parameter names) or `ROUTER_FULL`, against `RouterLimits`; `match(method, mStart, mEnd, target, tStart, tEnd, params)` answers the index, `ROUTER_NOT_FOUND` or `ROUTER_METHOD_NOT_ALLOWED`, writing each `:name` and a final `*` as a `[start, end)` pair into the caller's `params` (`ROUTER_TOO_MANY_PARAMS` when it is short). Literal before parameter before `*`, segment by segment, backtracking; a lookup enters each node at most once. The query is left unparsed and nothing is decoded: `routerDecode` decodes one parameter (`ROUTER_BAD_ESCAPE`, `ROUTER_NO_ROOM`) (`docs/security/router.md`) | Every refusal code, precedence and backtracking, 405 against 404, `%2F` kept in one segment, the query, `*` and authority-form targets, a target deeper than any route, the lookup bound, params past storage, and the arena flat over matches (`tests/link/net_router`, `net_router_f64`, five `net_router_negative_*`) |
-| [`net/postgres.ts`](./net/postgres.ts) | `PgConnection`, a PostgreSQL client that reads no socket: the program fills `inputBuffer()` and sends `outputBuffer()`, and `next()` answers `PG_NEED_MORE`, `PG_READY`, `PG_DESCRIBED`, `PG_ROW`, `PG_COMPLETE`, `PG_ERROR`, `PG_NOTICE`, `PG_GROUP_DONE` or the final `PG_FAILED` (`failure`, one of the `PG_ERR_*` codes). Protocol 3.0: startup, `trust` and SCRAM-SHA-256 with the server's signature checked (cleartext and MD5 refused), the extended query protocol — `prepare`, `bindStart`, `paramInt` / `paramText` / `paramBytes` / `paramTextArray` / `paramIntArray` / `paramNull`, an array built element by element into the Bind (`arrayStart`, `arrayElement`, `arrayInt`, `arrayNull`, `arrayEnd`), `bindEnd`, `bindCancel` to drop a Bind not yet ended, `closeStatement`, `sync` — with up to `maxInFlight` groups pipelined. `PgBatcher` queues keyed reads of one statement shape (`addInt`, `addText`) and `take(conn)` binds up to `maxRequests` of them, each key once, as one execution over `unnest($1) with ordinality`; `row`, `end` and `fail` route its rows by their server-supplied ordinal, checked first, to `next(run)`'s per-request `PG_BATCH_ROW` and `PG_BATCH_DONE` / `PG_BATCH_MISSING` / `PG_BATCH_FAILED`; `take` answers a fresh handle each time, so a server's late or repeated event on a spent one is counted in `stray`, never routed or panicked on. It reads no clock and allocates nothing per request or row. A row's columns are windows onto the receive buffer (`colStart`, `colLength`), read in place by `int`, `bool`, `isNull` and `PgText`'s decoders (`timestamptz`, `PgArrayWalker` for `text[]`); no per-row or per-column allocation. The password is a `Secret<u8[]>`, wiped once the proof is made. Caps on message size, columns, groups in flight and SCRAM iterations (`docs/security/postgres.md`) | PostgreSQL 18's frontend/backend protocol chapter, RFC 5802 and RFC 7677: every builder, event and refusal (`tests/link/std_postgres`), and exchanges recorded from PostgreSQL 18 by `tests/postgres/record.mjs` replayed byte for byte (`tests/link/std_postgres_replay`); the batcher's queueing, caps and ordinal refusals (`tests/link/std_postgres_batch`) |
+| [`net/postgres.ts`](./net/postgres.ts) | `PgConnection`, a PostgreSQL client that reads no socket: the program fills `inputBuffer()` and sends `outputBuffer()`, and `next()` answers `PG_NEED_MORE`, `PG_READY`, `PG_DESCRIBED`, `PG_ROW`, `PG_COMPLETE`, `PG_ERROR`, `PG_NOTICE`, `PG_GROUP_DONE` or the final `PG_FAILED` (`failure`, one of the `PG_ERR_*` codes). Protocol 3.0: startup, `trust` and SCRAM-SHA-256 with the server's signature checked (cleartext and MD5 refused), the extended query protocol — `prepare`, `bindStart`, `paramInt` / `paramText` / `paramBytes` / `paramTextArray` / `paramIntArray` / `paramNull`, an array built element by element into the Bind (`arrayStart`, `arrayElement`, `arrayInt`, `arrayNull`, `arrayEnd`), `bindEnd`, `bindStartBinary` for a Bind whose result columns come in binary (read in place by `binaryInt`, `binaryBool`, `binaryFloat` and `PgBinary`'s `timestamp` and `iso`), `bindCancel` to drop a Bind not yet ended, `closeStatement`, `sync` — with up to `maxInFlight` groups pipelined. `PgBatcher` queues keyed reads of one statement shape (`addInt`, `addText`) and `take(conn)` binds up to `maxRequests` of them, each key once, as one execution over `unnest($1) with ordinality`; `row`, `end` and `fail` route its rows by their server-supplied ordinal, checked first, to `next(run)`'s per-request `PG_BATCH_ROW` and `PG_BATCH_DONE` / `PG_BATCH_MISSING` / `PG_BATCH_FAILED`; `take` answers a fresh handle each time, so a server's late or repeated event on a spent one is counted in `stray`, never routed or panicked on. It reads no clock and allocates nothing per request or row. A row's columns are windows onto the receive buffer (`colStart`, `colLength`), read in place by `int`, `bool`, `isNull` and `PgText`'s decoders (`timestamptz`, `PgArrayWalker` for `text[]`); no per-row or per-column allocation. The password is a `Secret<u8[]>`, wiped once the proof is made. Caps on message size, columns, groups in flight and SCRAM iterations (`docs/security/postgres.md`) | PostgreSQL 18's frontend/backend protocol chapter, RFC 5802 and RFC 7677: every builder, event and refusal (`tests/link/std_postgres`), and exchanges recorded from PostgreSQL 18 by `tests/postgres/record.mjs` replayed byte for byte (`tests/link/std_postgres_replay`); the batcher's queueing, caps and ordinal refusals (`tests/link/std_postgres_batch`) |
 
 **How a carrier drives `TlsServer`.** The server speaks in handshake
 *messages*, tagged by level: `TLS_LEVEL_INITIAL` (cleartext — ClientHello,
@@ -496,7 +496,7 @@ have, and all three have since landed as builtins:
 | Was missing | Now |
 | --- | --- |
 | a directory listing | `readdirSync(path): string[] \| null`, sorted by bytes, because there is no `sort` for a caller to reach for |
-| a child's **output** — `spawnSync` answers a status and nothing else | `spawnSyncTo(argv, stdoutPath, stderrPath)`, each stream to a file, an empty path inheriting |
+| a child's **output** — `spawnSync` answers a status and nothing else | `spawnSyncTo(argv, stdoutPath, stderrPath)`, each stream to a file, an empty path inheriting; `spawnPiped(argv, stdin, stdout, stderr)`, stdin from a `u8[]` and both outputs into `u8[]`s, for a secret the child reads on stdin |
 | a clock | `monotonicNanos(): i64` |
 
 So the driver exists, in the language, and it is

package/std/net/postgres.ts

@@ -17,7 +17,9 @@
  *       // PG_READY: authenticated; prepare statements and send queries
  *       //   conn.prepare("by_id", "select id, name from users where id = $1", [23]); conn.sync()
  *       //   conn.bindStart("by_id"); conn.paramInt(7); conn.bindEnd(); conn.sync()
+ *       //   or conn.bindStartBinary("by_id") for binary result columns
  *       // PG_ROW: conn.int(0), conn.colStart(1) .. + conn.colLength(1) in conn.inputBuffer()
+ *       //   after bindStartBinary: conn.binaryInt(0), the text column as before
  *       // PG_COMPLETE: conn.tagRows(); PG_ERROR: conn.lastError.code
  *       // PG_GROUP_DONE: one sync()'s group has been answered
  *       event = conn.next();
@@ -57,18 +59,29 @@
  * does not need: a program prepares a statement and executes it in the same
  * flight.
  *
- * **Text results, no copies.** Every parameter and every result column is in
- * text format. A row is read where it lies in the input buffer: `next()` frames
- * each message once, validates its layout, and records each column's start and
- * length in two reused arrays, so a row costs no allocation. `int`, `bool`,
- * `isNull` and `PgText.timestamp` decode a column in place; `PgArrayWalker`
- * walks a one-dimensional `text[]` in place. `columnText(c)` is the one that
- * allocates, a string. An array parameter is a text array literal too:
- * `paramIntArray` writes an `int8[]` from an `i64[]` window, and `arrayStart`,
- * `arrayElement`, `arrayInt`, `arrayNull` and `arrayEnd` build an array one
- * element at a time into the Bind, so a list needs no string built first. A
- * program whose element was refused for room can drop the whole bind,
- * unsent, with `bindCancel`.
+ * **Text results, no copies.** Every parameter is in text format, and so is
+ * every result column unless the bind asks otherwise. A row is read where it
+ * lies in the input buffer: `next()` frames each message once, validates its
+ * layout, and records each column's start and length in two reused arrays, so
+ * a row costs no allocation. `int`, `bool`, `isNull` and `PgText.timestamp`
+ * decode a column in place; `PgArrayWalker` walks a one-dimensional `text[]`
+ * in place. `columnText(c)` is the one that allocates, a string. An array
+ * parameter is a text array literal too: `paramIntArray` writes an `int8[]`
+ * from an `i64[]` window, and `arrayStart`, `arrayElement`, `arrayInt`,
+ * `arrayNull` and `arrayEnd` build an array one element at a time into the
+ * Bind, so a list needs no string built first. A program whose element was
+ * refused for room can drop the whole bind, unsent, with `bindCancel`.
+ *
+ * **Binary results.** A bind opened with `bindStartBinary` instead of
+ * `bindStart` asks for every result column in binary format: an `int8` is
+ * eight bytes, a `timestamptz` eight bytes of microseconds since 2000, a
+ * `bool` one byte, so there is nothing to parse and less on the wire.
+ * `binaryInt`, `binaryBool` and `binaryFloat` read them in place, and
+ * `PgBinary`'s `timestamp` and `iso` write a time as `PgText.timestamp` does.
+ * A `text` column is the same bytes in either format, so `columnText` and the
+ * column windows read it unchanged. The program knows which of its binds
+ * asked for which, and reads each execution's rows with the matching
+ * decoders.
  *
  * **Authentication.** SCRAM-SHA-256 (RFC 5802, RFC 7677) or none (`trust`).
  * The password arrives as a `Secret<u8[]>`; the connection keeps a copy in a
@@ -100,8 +113,9 @@
  * that needs a socket, `connect(slot, nonce)` starts its connection, and the
  * program moves its bytes as above through `connection(slot)`. A request is a
  * ticket from `request()`; `dispatch()` gives the oldest to the ready
- * connection with the fewest groups in flight, the program builds its group and
- * ends it with `send()`, and `next(slot)` reads that connection's events with
+ * connection with the fewest groups in flight (or, with `PgConfig.pack`, to the
+ * first ready one with room, so a burst fills few connections in fuller
+ * writes), the program builds its group and ends it with `send()`, and `next(slot)` reads that connection's events with
  * `ticket` naming the request. Statements given to `register` are prepared on
  * each connection ahead of its first request. A connection that fails reports
  * `PG_LOST` for each request it took, then `PG_FAILED`; the program closes the
@@ -127,7 +141,7 @@
  * Written from PostgreSQL's "Frontend/Backend Protocol" chapter (version 18)
  * and RFC 5802 and RFC 7677; not ported from another implementation.
  */
-import { copyBytes, getI32BE, getU16BE, setI32BE, setU16BE } from "nish/bytes"
+import { copyBytes, getF64BE, getI32BE, getI64BE, getU16BE, setI32BE, setU16BE } from "nish/bytes"
 import { base64StdPadDecode, base64StdPadEncode } from "nish/crypto/base64url"
 import { timingSafeEqual } from "nish/crypto/ct"
 import { hmacSha256, pbkdf2HmacSha256 } from "nish/crypto/hmac"
@@ -218,6 +232,11 @@ const PG_NONCE_BYTES: i32 = 18
 // take: kept free under `maxOutput` by every other builder call, so that
 // `bindEnd()` and `sync()` are never refused for room.
 const PG_TAIL: i32 = 17
+// What a binary bind's end takes beyond `PG_TAIL`: its one result format code,
+// kept free from `bindStartBinary` on.
+const PG_BINARY_TAIL: i32 = 2
+// The result format code for binary.
+const PG_FORMAT_BINARY: i32 = 1
 // The largest `maxMessage` and `maxOutput`. The input buffer doubles up to one
 // past them; the output buffer doubles only while twice its size fits in an i32.
 const PG_MAX_CAP: i32 = 1073741823
@@ -238,6 +257,15 @@ export class PgConfig {
   maxMessage: i32 = 1048576
   /** The most groups waiting for their answers at once. */
   maxInFlight: i32 = 16
+  /**
+   * Read by `PgPool` only: whether `dispatch()` packs requests onto the
+   * first ready connection with room, filling it to `maxInFlight` before the
+   * next, rather than spreading them over every connection, fewest in flight
+   * first. Fewer connections in use send fuller writes, fewer packets, which
+   * pays on a lossy link to the server; a connection is still wanted only once
+   * every ready one is full.
+   */
+  pack: boolean = false
   /** The input buffer's first size, in bytes; it grows to a message's length, up to `maxMessage` + 1. */
   inputSize: i32 = 8192
   /** The widest row; past it, `PG_ERR_TOO_BIG`. PostgreSQL's own limit is 1664. */
@@ -677,6 +705,159 @@ export class PgText {
   }
 }
 
+// The days from 0000-03-01, where the civil calendar's year starts for the
+// conversion below, to 2000-01-01, where PostgreSQL's binary times count from.
+const PG_EPOCH_DAYS: i64 = 730425
+// The first and last days `PgBinary.iso` writes, counted from 2000-01-01:
+// 0001-01-01 and 9999-12-31, the years four digits spell.
+const PG_FIRST_DAY: i64 = -730119
+const PG_LAST_DAY: i64 = 2921939
+
+/** `value`'s last `width` decimal digits into `out[at, at + width)`. */
+const pgDigits = (out: u8[], at: i32, value: i32, width: i32): void => {
+  let v: i32 = value
+  for (let i: i32 = width - 1; i >= 0; i--) {
+    out[at + i] = toU8((v % 10) + 48)
+    v = v / 10
+  }
+}
+
+/**
+ * Decoders for PostgreSQL's binary format, in place, for the rows of a bind
+ * that `bindStartBinary` opened; a bad input sets `failed`, which stays set.
+ * A `text` or `varchar` column's bytes are the same in either format, so
+ * `columnText`, `colStart` and `colLength` read it as they read a text one.
+ */
+export class PgBinary {
+  /** Whether a decode since the last `reset()` was given something it could not read. */
+  failed: boolean = false
+
+  /** Clears `failed`. */
+  reset(): void {
+    this.failed = false
+  }
+
+  // Whether `[start, start + length)` is inside `b`; sets `failed` when not.
+  private inside(b: u8[], start: i32, length: i32): boolean {
+    if (start < 0 || length < 0 || start > toI32(b.length) - length) {
+      this.failed = true
+      return false
+    }
+    return true
+  }
+
+  /**
+   * An `int2`, `int4` or `int8` column, told apart by its length (2, 4 or 8
+   * bytes, big-endian two's complement); 0 and `failed` for any other length,
+   * NULL's -1 among them. A `timestamptz` or `timestamp` reads as an `int8`:
+   * microseconds since 2000-01-01 00:00:00 UTC, which `iso` writes out.
+   */
+  int(b: u8[], start: i32, length: i32): i64 {
+    if ((length !== 2 && length !== 4 && length !== 8) || !this.inside(b, start, length)) {
+      this.failed = true
+      return 0
+    }
+    if (length === 8) {
+      return getI64BE(b, start)
+    }
+    if (length === 4) {
+      return toI64(getI32BE(b, start))
+    }
+    const v: i32 = toI32(getU16BE(b, start))
+    return toI64(v >= 32768 ? v - 65536 : v)
+  }
+
+  /** A `bool` column: one byte, 1 or 0; false and `failed` otherwise. */
+  bool(b: u8[], start: i32, length: i32): boolean {
+    if (length === 1 && this.inside(b, start, length)) {
+      const c: i32 = toI32(b[start])
+      if (c === 1) {
+        return true
+      }
+      if (c === 0) {
+        return false
+      }
+    }
+    this.failed = true
+    return false
+  }
+
+  /** A `float8` column: eight bytes, IEEE 754 big-endian; 0 and `failed` otherwise. */
+  float(b: u8[], start: i32, length: i32): f64 {
+    if (length !== 8 || !this.inside(b, start, length)) {
+      this.failed = true
+      return 0
+    }
+    return getF64BE(b, start)
+  }
+
+  /**
+   * A `timestamptz` or `timestamp` column, written to `out[at, at + 24)` as
+   * `iso` writes it. Answers 24, or -1 and `failed` for a column that is not
+   * eight bytes or a time `iso` refuses.
+   */
+  timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 {
+    if (length !== 8 || !this.inside(b, start, length)) {
+      this.failed = true
+      return -1
+    }
+    return this.iso(getI64BE(b, start), out, at)
+  }
+
+  /**
+   * `micros`, microseconds since 2000-01-01 00:00:00 UTC, written to
+   * `out[at, at + 24)` as `2024-01-02T03:04:05.123Z`: the microseconds cut,
+   * not rounded, to milliseconds, as `PgText.timestamp` cuts the same time.
+   * Answers 24, or -1 and `failed` with `out` untouched for a year outside
+   * 0001–9999 (`infinity` and `-infinity` among them) or no room in `out`.
+   */
+  iso(micros: i64, out: u8[], at: i32): i32 {
+    if (at < 0 || at > toI32(out.length) - 24) {
+      this.failed = true
+      return -1
+    }
+    // Floored, so that a time before 2000 keeps its day and is cut toward the past.
+    const dayMicros: i64 = toI64(86400000) * 1000
+    let days: i64 = micros / dayMicros
+    let rest: i64 = micros % dayMicros
+    if (rest < 0) {
+      days -= 1
+      rest += dayMicros
+    }
+    if (days < PG_FIRST_DAY || days > PG_LAST_DAY) {
+      this.failed = true
+      return -1
+    }
+    // The civil date of a day count: eras of 400 years (146097 days), each
+    // year starting on 1 March so that a leap day is its last.
+    const z: i64 = days + PG_EPOCH_DAYS
+    const era: i64 = z / 146097
+    const doe: i64 = z - era * 146097
+    const yoe: i64 = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365
+    const doy: i64 = doe - (365 * yoe + yoe / 4 - yoe / 100)
+    const mp: i64 = (5 * doy + 2) / 153
+    const day: i64 = doy - (153 * mp + 2) / 5 + 1
+    const month: i64 = mp < 10 ? mp + 3 : mp - 9
+    const year: i64 = yoe + era * 400 + (month <= 2 ? 1 : 0)
+    const millis: i32 = toI32(rest / 1000)
+    pgDigits(out, at, toI32(year), 4)
+    out[at + 4] = toU8(45)
+    pgDigits(out, at + 5, toI32(month), 2)
+    out[at + 7] = toU8(45)
+    pgDigits(out, at + 8, toI32(day), 2)
+    out[at + 10] = toU8(84)
+    pgDigits(out, at + 11, millis / 3600000, 2)
+    out[at + 13] = toU8(58)
+    pgDigits(out, at + 14, (millis / 60000) % 60, 2)
+    out[at + 16] = toU8(58)
+    pgDigits(out, at + 17, (millis / 1000) % 60, 2)
+    out[at + 19] = toU8(46)
+    pgDigits(out, at + 20, millis % 1000, 3)
+    out[at + 23] = toU8(90)
+    return 24
+  }
+}
+
 /**
  * A walk over a one-dimensional `text[]` column in place: `start` the
  * column, then `next()` until `PG_ARRAY_END` or `PG_ARRAY_BAD`. Each element
@@ -842,10 +1023,11 @@ export class PgConnection {
   lastNotice: PgError | null = null
   /** The decoders `int`, `bool` and `isNull` use; `text.failed` says whether one was given a column it could not read. */
   readonly text: PgText
+  /** The decoders `binaryInt`, `binaryBool` and `binaryFloat` use, for a bind `bindStartBinary` opened; `binary.failed` as `text.failed`. */
+  readonly binary: PgBinary
 
   private readonly config: PgConfig
   private readonly password: PgPassword
-  private state: i32 = 0
   private input: u8[]
   private inStart: i32 = 0
   private inEnd: i32 = 0
@@ -863,12 +1045,15 @@ export class PgConnection {
   groupFailed: boolean = false
   // Whether the open bind opened its group, which `bindCancel` closes again.
   private bindOpened: boolean = false
+  // Whether the open bind asks for its result columns in binary.
+  private bindBinary: boolean = false
   private bindAt: i32 = -1
   private paramCountAt: i32 = 0
   private paramCount: i32 = 0
   // The open array parameter's length word, -1 when none is open, and its elements so far.
   private arrayAt: i32 = -1
   private arrayCount: i32 = 0
+  private state: i32 = 0
   private clientNonce: string = ""
   private serverSignature: u8[]
 
@@ -885,6 +1070,7 @@ export class PgConnection {
     pgCheckConfig(config)
     this.config = config
     this.text = new PgText()
+    this.binary = new PgBinary()
     this.password = new PgPassword(password)
     const inputSize: i32 = config.inputSize < 64 ? 64 : config.inputSize
     this.input = new Array<u8>(inputSize)
@@ -1574,7 +1760,8 @@ export class PgConnection {
    */
   private room(size: i32): boolean {
     const queued: i32 = this.outEnd - this.outStart
-    if (size < 0 || size > this.config.maxOutput - PG_TAIL - queued) {
+    const tail: i32 = this.bindAt >= 0 && this.bindBinary ? PG_TAIL + PG_BINARY_TAIL : PG_TAIL
+    if (size < 0 || size > this.config.maxOutput - tail - queued) {
       return false
     }
     if (this.outStart > 0 && this.outEnd + size > toI32(this.out.length)) {
@@ -1740,11 +1927,31 @@ export class PgConnection {
    * order, then `bindEnd()`. False as `prepare` is.
    */
   bindStart(name: string): boolean {
+    return this.openBind(name, false)
+  }
+
+  /**
+   * `bindStart`, asking for every result column of the execution in binary
+   * format rather than text: fixed-size integers, booleans, floats and
+   * times, read in place by `binaryInt`, `binaryBool`, `binaryFloat` and
+   * `binary.timestamp`. A `text` column's bytes are the same in either
+   * format, so `columnText` and the column windows read it as before; a
+   * `text[]` or `numeric` column comes in PostgreSQL's binary layout, which
+   * no decoder here reads. Its `bindEnd()` writes two bytes more, kept free
+   * under `maxOutput` from here on. False as `prepare` is.
+   */
+  bindStartBinary(name: string): boolean {
+    return this.openBind(name, true)
+  }
+
+  private openBind(name: string, binary: boolean): boolean {
     const opens: boolean = !this.groupOpen
-    if (pgHasNul(name) || toI32(name.length) > PG_MAX_CAP || !this.canOpen(11 + toI32(name.length))) {
+    const extra: i32 = binary ? PG_BINARY_TAIL : 0
+    if (pgHasNul(name) || toI32(name.length) > PG_MAX_CAP || !this.canOpen(11 + extra + toI32(name.length))) {
       return false
     }
     this.bindOpened = opens
+    this.bindBinary = binary
     this.bindAt = this.startMessage(PG_FE_BIND)
     this.putByte(PG_ZERO)
     this.putCString(name)
@@ -2058,9 +2265,10 @@ export class PgConnection {
   }
 
   /**
-   * Ends the Bind (every result column in text) and queues its Execute, for
-   * every row. False, and nothing written, when no bind is open; never for
-   * room, which the calls before it kept.
+   * Ends the Bind (every result column in text, or in binary after
+   * `bindStartBinary`) and queues its Execute, for every row. False, and
+   * nothing written, when no bind is open; never for room, which the calls
+   * before it kept.
    */
   bindEnd(): boolean {
     if (this.bindAt < 0) {
@@ -2069,10 +2277,17 @@ export class PgConnection {
     if (this.arrayAt >= 0) {
       panic("nish/net/postgres: bindEnd() while an array is open")
     }
-    this.tailRoom(PG_TAIL)
+    const binary: boolean = this.bindBinary
+    this.tailRoom(binary ? PG_TAIL + PG_BINARY_TAIL : PG_TAIL)
     const at: i32 = this.bindAt
     setU16BE(this.out, this.paramCountAt, toU16(this.paramCount))
-    this.putI16(PG_ZERO)
+    if (binary) {
+      // One format code, which the server applies to every column.
+      this.putI16(toI32(1))
+      this.putI16(PG_FORMAT_BINARY)
+    } else {
+      this.putI16(PG_ZERO)
+    }
     this.endMessage(at)
     this.bindAt = -1
     const execute: i32 = this.startMessage(PG_FE_EXECUTE)
@@ -2170,6 +2385,21 @@ export class PgConnection {
     return this.text.bool(this.input, this.colStarts[c], this.colLengths[c])
   }
 
+  /** Binary column `c`, an `int2`, `int4`, `int8` or a time's microseconds, as an integer; NULL or another length sets `binary.failed`. */
+  binaryInt(c: i32): i64 {
+    return this.binary.int(this.input, this.colStarts[c], this.colLengths[c])
+  }
+
+  /** Binary column `c` as a boolean; NULL or a bad value sets `binary.failed`. */
+  binaryBool(c: i32): boolean {
+    return this.binary.bool(this.input, this.colStarts[c], this.colLengths[c])
+  }
+
+  /** Binary column `c`, a `float8`, as an f64; NULL or another length sets `binary.failed`. */
+  binaryFloat(c: i32): f64 {
+    return this.binary.float(this.input, this.colStarts[c], this.colLengths[c])
+  }
+
   /** Whether the tag of the execution just completed starts with the word `word` (`INSERT`, `SELECT`, ...). */
   tagIs(word: string): boolean {
     const n: i32 = toI32(word.length)
@@ -2266,7 +2496,8 @@ class PgPoolSlot {
  *
  * A request is a ticket from `request()`, queued in FIFO order. `dispatch()`
  * hands the queue's head to the ready connection with the fewest groups in
- * flight, never past `maxInFlight` on one; the program builds the request's
+ * flight, or under `PgConfig.pack` the lowest-numbered ready one with room,
+ * never past `maxInFlight` on one; the program builds the request's
  * group on `connection(slot)` and ends it with `send()`, not `sync()`.
  * `next(slot)` then reads that connection's events, `ticket` naming the
  * request each is about. A connection that fails reports `PG_LOST` for each
@@ -2367,7 +2598,8 @@ export class PgPool {
   }
 
   /**
-   * Hands the oldest waiting request to a ready connection with room, and
+   * Hands the oldest waiting request to a ready connection with room (the
+   * one with the fewest in flight, or under `PgConfig.pack` the first), and
    * answers its slot, `ticket` set to the request: build its group on
    * `connection(slot)`, then `send()`. `PG_POOL_NONE` when nothing waits, a
    * request is still being built, or no ready connection has room; then a
@@ -2381,6 +2613,7 @@ export class PgPool {
       return PG_POOL_NONE
     }
     const cap: i32 = this.config.maxInFlight
+    const pack: boolean = this.config.pack
     let best: i32 = -1
     let load: i32 = 0
     let starting: i32 = 0
@@ -2389,7 +2622,7 @@ export class PgPool {
       const slot: PgPoolSlot = this.slots[s]
       const conn: PgConnection | null = slot.conn
       if (slot.state === PG_SLOT_READY && conn !== null) {
-        if (conn.inFlight < cap && (best < 0 || conn.inFlight < load)) {
+        if (conn.inFlight < cap && (best < 0 || (!pack && conn.inFlight < load))) {
           best = s
           load = conn.inFlight
         }