@amritk/nish-aarch64-darwin 0.34.0 → 0.35.0

package/INSTALL.md

@@ -54,6 +54,8 @@ export PATH="$(brew --prefix llvm@18)/bin:$PATH"   # add to your shell profile
 Xcode's `clang` (`xcode-select --install`) also works for native binaries;
 the Homebrew LLVM is needed for the `wasm` and `wasi` profiles (`wasm-ld`).
 
+<a id="wasi-optional-for---profile-wasi" style="scroll-margin-top: 65px"></a>
+
 ### WASI (optional, for `--profile wasi`)
 
 The `wasi` profile links the runtime against wasi-libc so that whole programs
@@ -105,7 +107,7 @@ of its own architecture by the release workflow before the release existed, and
 installing is a download and an unpack.
 
 Through npm, which is also how an Nish *program* resolves its dependencies
-([wp21-packages.md](wp21-packages.md)), so this is the one to pick if you want
+([wp21-packages.md](https://github.com/amritk/nish/blob/main/docs/wp21-packages.md)), so this is the one to pick if you want
 the compiler pinned per project in a `package.json`:
 
 ```bash
@@ -169,7 +171,7 @@ release also attaches `nish-<version>.spdx.json`, an SPDX 2.3 software bill of
 materials: every attached file with its SHA-256, the clang, linker, Node.js
 and seed compiler that built each tarball (recorded by the build row itself),
 and the vendored code from
-[THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md) that each of them contains.
+[THIRD_PARTY_NOTICES.md](https://github.com/amritk/nish/blob/main/THIRD_PARTY_NOTICES.md) that each of them contains.
 How these fit the rest of the release's defences is
 [docs/security/supply-chain.md](security/supply-chain.md).
 
@@ -198,13 +200,13 @@ never fails over it.
 > installers above handle it by running the binary through a one-line `exec` of
 > an absolute path. If you unpack a tarball by hand, invoke it by path
 > (`nish-<version>-<asset>/bin/nish`) or write that wrapper yourself. The
-> underlying defect is [wp19 §5a](wp19-stage0-retirement.md#5a-what-r6-is-waiting-on)
+> underlying defect is [wp19 §5a](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md#5a-what-r6-is-waiting-on)
 > item 4.
 
 **The package is `nish` from 0.20.0.** Releases up to 0.18.0 were published
 as `@amritk/nish` (0.19.0's publish to npm failed), which is deprecated and
 points here; `npm install -g nish`
-replaces it ([docs/wp12-release.md](wp12-release.md#the-npm-name)). Versions
+replaces it ([docs/wp12-release.md](https://github.com/amritk/nish/blob/main/docs/wp12-release.md#the-npm-name)). Versions
 0.0.0 and 0.0.1 of `nish` are an unrelated 2014 project that held the name
 before it, so pin `nish@^0.20.0` or later rather than an older range.
 
@@ -233,9 +235,9 @@ nish: no prebuilt compiler for freebsd/x64
 Until 0.6.0 it ran the TypeScript compiler that shipped in the same package
 instead — the same compiler by every test here, about eight times slower, and
 no C toolchain needed. That compiler was stage0, which was deleted in R6
-([wp19](wp19-stage0-retirement.md)), so there is nothing left in the package to
+([wp19](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md)), so there is nothing left in the package to
 fall back to. The cost is stated where the rest of that deletion's costs are,
-in [wp19 §6](wp19-stage0-retirement.md#6-what-retirement-costs-stated-plainly),
+in [wp19 §6](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md#6-what-retirement-costs-stated-plainly),
 and it is a real one: **musl, FreeBSD and 32-bit platforms have no `npm
 install` route to a compiler any more.**
 
@@ -276,7 +278,7 @@ to have on the issue tracker rather than a workaround to discover here.
 `nish` from 0.20.0; 0.19.0 is on GitHub only, because its npm publish
 failed. Every release publishes the main package and its platform packages to
 npm from `release.yml`, by trusted publishing
-([docs/wp12-release.md](wp12-release.md#release-procedure) step 4), so
+([docs/wp12-release.md](https://github.com/amritk/nish/blob/main/docs/wp12-release.md#release-procedure) step 4), so
 `npm install -g nish` is the whole install. The rest of this section is
 for a machine that cannot reach the registry, or a release before 0.10.0.
 
@@ -358,7 +360,7 @@ v0.16.0; v0.1.1 was the first release with a binary attached.
 The `v0.1.0` tag exists but has no release behind it and no assets, so every
 `v0.1.0` download URL is a 404 — the tag was pushed by a workflow, and GitHub
 raises no event for that, so nothing ever built it
-([docs/wp12-release.md](wp12-release.md#release-procedure) step 2). When a newer
+([docs/wp12-release.md](https://github.com/amritk/nish/blob/main/docs/wp12-release.md#release-procedure) step 2). When a newer
 release exists, take its version from
 [the releases page](https://github.com/amritk/nish/releases/latest).
 
@@ -435,7 +437,7 @@ over, `runtime-checksum.c` the CRC-32 kernels of `nish/compress/checksum`,
 `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
+([docs/wp7-runtime.md](https://github.com/amritk/nish/blob/main/docs/wp7-runtime.md)); nothing in the core calls into the
 others, so a line that names only `runtime.c` and `runtime-os.c` still links a
 program that uses none of the other nine. `scripts/build.sh` compiles the other
 nine beside any
@@ -451,7 +453,7 @@ beside `-DNISH_THREADS=1`).
 ## 2a. What `npm run build` does
 
 `src/` is the compiler, written in Nish, and it compiles itself
-([docs/wp14-selfhost.md](wp14-selfhost.md)). From a checkout, with clang on
+([docs/wp14-selfhost.md](https://github.com/amritk/nish/blob/main/docs/wp14-selfhost.md)). From a checkout, with clang on
 `PATH`, `npm run build` runs `scripts/bootstrap.sh` with the seed from §2:
 
 ```bash
@@ -486,7 +488,7 @@ in `src/` and becomes usable inside `src/` from the next release on; CI's
 `bootstrap` job is what checks that the released seed still builds stage1.
 Until R6 the seed was a TypeScript compiler, stage0, run under Node; it was
 deleted once the native one answered every flag it did
-([wp19](wp19-stage0-retirement.md)).
+([wp19](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md)).
 
 ## 3. Hello world
 
@@ -518,7 +520,7 @@ nish hello.ts -o hello.ll
 
 Other build profiles: `--profile size` (smallest binary), `--profile debug`
 (no optimisation, symbols kept). Run `nish --help` for every flag, and
-see the [README](../README.md) for the language subset.
+see the [README](https://github.com/amritk/nish/blob/main/README.md) for the language subset.
 
 To use a program as a script rather than keep the binary, run it:
 
@@ -549,6 +551,8 @@ it cannot make private, compiles the runtime itself as it always did; the
 wasi profile and `scripts/build.sh` called directly never use the cache.
 Removing the directory is always safe.
 
+<a id="4-exit-codes" style="scroll-margin-top: 65px"></a>
+
 ## 4. Exit codes
 
 | Code | Meaning |

package/docs/AI.md

@@ -108,7 +108,9 @@ the difference is a row of [the user guide's table](guide/using-nish/to-typescri
 or a bug in `nish` worth reporting. A program on `nish:net`, the signal
 descriptor or a C declaration (NL4010, NL4011), a compound assignment whose
 index would run twice (NL4012) or a generic whose element type decides its
-code (NL4013, NL4014) is refused and has no TypeScript to run.
+code (NL4013, NL4014) is refused and has no TypeScript to run. An `async`
+program is written as Node async/await, whose spawned tasks may print in
+another order than native.
 
 Two more surfaces worth knowing: `nish --emit-ast f.ts` prints what was parsed
 and `nish --emit-checked f.ts` prints the side tables the emitter reads. Both
@@ -140,7 +142,11 @@ everywhere, a template literal instead of `String(n)`.
 - A module is one `.ts` file. At the top level it may hold **only**
   declarations: `const` arrows (functions), `class`, `interface`, module
   `const`s, `type` aliases, numeric `enum`s, and `import`s. There is no
-  top-level code, so there is no initialisation order to think about.
+  top-level code, so there is no initialisation order to think about. The
+  one exception is an entry module with no `main`: its top-level statements
+  run as `main` (`docs/LANGUAGE.md` → "Top-level code"). Declare every
+  function above the first statement, and pass a function what it needs
+  rather than naming a variable of the code.
 - `export const main` lives in the entry module only, takes no parameters, and
   returns `void` or an `i32`-lowered `number` — the process exit code. Under
   `--number-mode f64`, declare it `main(): i32`.
@@ -175,12 +181,12 @@ rejects. This table is the highest-value part of the page.
 | `h.get<i32>(7)` (type argument at a method call) | `Type arguments are not written at a call site in Nish` | `h.get(7)` — a generic method infers like a generic function |
 | `<T>(p: T) => p.x` (a member of a type parameter) | `` Cannot read `x` of `T`: an unconstrained type parameter has no members `` | `<T extends Point>(p: T) => p.x`, where `Point` is a class or interface that declares `x` |
 | `identity<i32>(7)` (type argument at a call) | `Type arguments are not written at a call site in Nish` | `identity(7)` — `T` is inferred from the arguments |
-| `async` / `await` / `Promise` | forbidden (no event loop) | the I/O builtins are synchronous |
+| a promise in a variable, `.then`, `Promise.all` | forbidden: a promise is never a value | `await` each call where it is made; see [Async functions](#async-functions) |
 | `namespace N { }`, `declare global { }`, `@decorator` | forbidden | one module per file; a plain function in place of a decorator |
 | `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?: 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 |
+| `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, `o: Opts | null = null` for an options argument; `...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 |
@@ -583,8 +589,11 @@ const double = (n: i32): i32 => n * 2;   // a concise body is that one `return`
 - **Parameters are immutable**: `p = 1`, `p++`, `p += 1` are all rejected. Copy
   into a `let` first.
 - A non-`void` function must return on every path.
-- Rejected: generators, `async`, destructured / rest / optional / default
-  parameters, overloads, nested function declarations. Type parameters *are*
+- Rejected: generators, a method that is `async`, destructured and optional
+  (`x?: T`) parameters, overloads, nested function declarations. A default
+  (`n: i32 = 1`) or a rest parameter (`...ns: i32[]`) is allowed on a
+  function, a method, a constructor or a module `const` arrow — see
+  "Optional parameters" in [Recipes for what is missing](#recipes-for-what-is-missing). Type parameters *are*
   allowed — see [Generic functions](#generic-functions).
 
 ### Generic functions
@@ -850,8 +859,8 @@ export const main = (): i32 => {
   (`(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
+  read `this` (bind `const self = this`), or read a function-typed parameter
+  of its function. An arrow inside another arrow, or given to a method, a
   constructor, `expose` or `exposeWith`, captures nothing; `xs.sort(cmp)`'s
   comparator is the exception, and captures as an arrow argument does.
 - **The argument's type must match exactly**: `(x: i32) => i64` for a
@@ -873,6 +882,52 @@ export const main = (): i32 => {
 };
 ```
 
+### Async functions
+
+`async` compiles natively: a function that awaits becomes a frame and a resume
+switch, one that awaits nothing a plain function, and `export async function
+main` runs to its end, then finishes every task it spawned. Nothing waits on
+sockets or timers in this release, so every task runs to completion.
+`--emit-ts` writes it as Node async/await, where `spawn`ed tasks resume in
+Node's order, not the native one. A call
+that can fail answers `Promise<Result<T, E>>`: test the `Result` after the
+`await`. The rules:
+
+- `async` goes on a top-level `function` or an arrow, never a method
+  (`NL1063`). Its return type is `Promise<T>` (`NL2655`), and `Promise<T>`
+  appears nowhere else — not on a parameter, field, local or alias (`NL2654`).
+- **`await` takes a direct call to an `async` function** (`NL2643` for a value,
+  `NL2644` for a plain function's call), **at the top of a statement**: alone,
+  as a `const`/`let` initializer, after `return`, or right of a plain `=`.
+  Anywhere inside a larger expression is `NL2642`, so bind first:
+  `const n = await load(1); console.log(n);`.
+- An `async` call that is not awaited is `NL2645`: a promise is never a value.
+  No `.then` (`NL2650`), no `Promise.all` (`NL2649`), no `for await`
+  (`NL2133`).
+- Several at once: `import { awaitAll, spawn } from "nish:async"`, then
+  `const [a, b] = await awaitAll(f(x), g(y))` (two to eight calls, one name
+  each, `NL2647`). `spawn(f(x))` starts a task without waiting; `f` answers
+  `void` or a `Result` (`NL2646`).
+- No recursion through `await`, direct or mutual (`NL2648`): write a loop.
+- An `async` arrow goes only to a parameter whose function type answers
+  `Promise<T>` (`NL2639`), and only an `async` one goes there (`NL2640`).
+- No `async` under a wasm target or `--profile wasi` (`NL2652`).
+- `spawn(f(x))` runs `f` at once, until it first waits on the outside world,
+  before it returns; Node runs `f` only to its first `await` and the rest
+  after the spawning task yields. Do not rely on either order.
+
+```ts nish:err NL2642
+async function load(id: i32): Promise<i32> {
+  return id;
+}
+
+async function run(): Promise<void> {
+  console.log(await load(1));
+}
+
+export const main = (): i32 => 0;
+```
+
 ### Data parallelism: `nish/threads`
 
 `parallelMapInto(src, dst, f)` writes `f(src[i])` into `dst[i]`, and
@@ -2243,7 +2298,8 @@ backlog)`, `tcpAccept(fd, peer)`, `netRead(fd, buf, off, len)`,
 `i32`: **a negative number is a failure, not an exception** — `-11` means "would
 block, call again", `-32` a peer that has gone (never SIGPIPE), `-98` the port
 is in use, `-111` refused, `-22` a bad argument. Every socket is non-blocking,
-and there is no `async` and no callback: your `main` is the loop. A client calls
+and there is no callback, and an `async` function cannot wait on a socket yet
+(its tasks run on an in-process queue): your `main` is the loop. A client calls
 `tcpConnect(addr)`, which answers the descriptor while it is still connecting;
 wait for it to be writable, then `connectResult(fd)` is 0 or the failure. Buffers
 are `u8[]` only; an address is 18 bytes of one (IPv4 as `::ffff:a.b.c.d`, then
@@ -2254,6 +2310,9 @@ To fetch a URL from a CLI, skip all of this: `nish/net/fetch`'s
 response's head is in and answers it with `body.readAll(limit)`, or null on a
 failure (a `FetchSyncClient` keeps the connection and says why in `error`).
 `netRead` / `netWrite` panic on a range outside the buffer.
+`netWrite2(fd, a, aOff, aLen, b, bOff, bLen)` writes two ranges in one
+`sendmsg` (a header and a body without a copy) and answers the bytes written,
+which may stop inside either range; it checks both ranges, the first one first.
 `tcpListenFlags(host, port, backlog, flags)` is `tcpListen` with flag 1
 `SO_REUSEPORT`, so several listeners, in one process or many, share a port (Linux
 spreads the connections), and flag 2 `TCP_NODELAY` on every socket `tcpAccept`
@@ -2796,13 +2855,16 @@ or `PG_LOST` to `fail(run)` (on a spent handle these do nothing and count in
 `stray`), and after each call `next(run)` until
 `PG_BATCH_NONE`: `PG_BATCH_ROW` (the connection's row answers request `tag`),
 then one of `PG_BATCH_DONE`, `PG_BATCH_MISSING` or `PG_BATCH_FAILED` per
-request. It reads no clock: when to take is the loop's choice, or a `PgBatchClock`'s (`PgBatchClockConfig`: `minCount`, `factor` × the moving average of batch sizes, `maxWaitUs`, the idle bypass `lightCount`; defaults are a fixed window), which `takeDue(conn, clock, nowUs, pool.inFlight())` consults after `clock.arrived(nowUs)` per add; `PgBatchTurns` wakes one collecting connection only when its batch is due. (No block;
+request. `sorted = false` drops `q.ord` from the statement's `order by` (and
+its Sort node, with `orderBy` empty): rows route as they come, and every last
+event waits for `end`. The batcher reads no clock: when to take is the loop's choice, or a `PgBatchClock`'s (`PgBatchClockConfig`: `minCount`, `factor` × the moving average of batch sizes, `maxWaitUs`, the idle bypass `lightCount`; defaults are a fixed window), which `takeDue(conn, clock, nowUs, pool.inFlight())` consults after `clock.arrived(nowUs)` per add; `PgBatchTurns` wakes one collecting connection only when its batch is due. (No block;
 `tests/postgres/live`'s `batch` scenario runs it against a server, and the user
 guide's [PostgreSQL page](guide/using-nish/postgres.md#batching-keyed-reads)
 its walk-through.)
 
 **Call another service from a route handler** — there is no `await fetch()`
-in a handler and no event-loop callback: `nish/net/upstream`'s `Upstream(h,
+in a handler (an `async` task does not wait on a socket yet) and no event-loop
+callback: `nish/net/upstream`'s `Upstream(h,
 origin, limits)` is a pool of keep-alive connections to one `http:` origin on
 the `HttpHandler`'s own loop. `users.get(req, path)` returns at once — test it
 for `UPSTREAM_E_FULL`, which holds nothing — and keeps `req` held; after each
@@ -2857,9 +2919,10 @@ export const main = (): i32 => {
 
 **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.
+it in. An options argument is `(opts: Options | null = null)`: `null` is the
+one default of a `T | null` parameter. `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-aarch64-darwin",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "The nish native compiler for macOS on ARM64",
   "license": "MIT",
   "os": [

package/runtime/async.d.mts

@@ -0,0 +1,49 @@
+// The declarations of `runtime/async.mjs`, `nish:async` under Node.
+
+/** Starts `task` without waiting for it; the launcher waits before it exits. */
+export declare function spawn(task: Promise<void>): void;
+/** Every task's answer, in the order the calls are written, once all of them finish. */
+export declare function awaitAll<A, B>(a: Promise<A>, b: Promise<B>): Promise<[A, B]>;
+export declare function awaitAll<A, B, C>(a: Promise<A>, b: Promise<B>, c: Promise<C>): Promise<[A, B, C]>;
+export declare function awaitAll<A, B, C, D>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+): Promise<[A, B, C, D]>;
+export declare function awaitAll<A, B, C, D, E>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+): Promise<[A, B, C, D, E]>;
+export declare function awaitAll<A, B, C, D, E, F>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+  f: Promise<F>,
+): Promise<[A, B, C, D, E, F]>;
+export declare function awaitAll<A, B, C, D, E, F, G>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+  f: Promise<F>,
+  g: Promise<G>,
+): Promise<[A, B, C, D, E, F, G]>;
+export declare function awaitAll<A, B, C, D, E, F, G, H>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+  f: Promise<F>,
+  g: Promise<G>,
+  h: Promise<H>,
+): Promise<[A, B, C, D, E, F, G, H]>;
+/** Waits for every task `spawn` started, the tasks those tasks start included. */
+export declare function settleTasks(): Promise<void>;

package/runtime/async.mjs

@@ -0,0 +1,27 @@
+// `nish:async` under Node (WP49): what `nish --emit-ts` writes an async
+// program against, and what `runtime/nish.mjs` answers `nish:async` with. A
+// file of its own, not `nish/runtime`, because `nish:process` has a `spawn`
+// there already.
+//
+// `awaitAll` is `Promise.all` over its two to eight tasks. `spawn` starts a
+// task without awaiting it and keeps it, so the launcher's `settleTasks` waits
+// for every task started before the process exits, as the native driver
+// drains its queue after `main` answers. Node runs a task only until its first
+// `await` where native runs it until it first waits, so spawned tasks may print
+// in another order (`docs/RUN_UNDER_NODE.md`). A task that throws is Node's
+// unhandled rejection, which exits 1 as a native panic does.
+
+const pending = [];
+
+export const spawn = (task) => {
+  pending.push(task);
+};
+
+export const awaitAll = (...tasks) => Promise.all(tasks);
+
+export const settleTasks = async () => {
+  for (let i = 0; i < pending.length; i++) {
+    await pending[i];
+  }
+  pending.length = 0;
+};

package/runtime/nish.d.ts

@@ -444,6 +444,16 @@ declare function tcpAccept(fd: i32, peer: u8[]): i32;
 declare function netRead(fd: i32, buf: u8[], off: i32, len: i32): i32;
 /** Up to `len` bytes of `buf` from `off`: the count; a gone peer is -32, never SIGPIPE. */
 declare function netWrite(fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
+/** `netWrite` of `a`'s range then `b`'s, in one system call: the count of both, at most `aLen + bLen`. */
+declare function netWrite2(
+  fd: i32,
+  a: readonly u8[],
+  aOff: i32,
+  aLen: i32,
+  b: readonly u8[],
+  bOff: i32,
+  bLen: i32
+): i32;
 /** Shut the read side (0), the write side (1) or both (2). */
 declare function netShutdown(fd: i32, how: i32): i32;
 /** Close the descriptor. */
@@ -723,6 +733,16 @@ declare module "nish:net" {
   export function netRead(fd: i32, buf: u8[], off: i32, len: i32): i32;
   /** Up to `len` bytes of `buf` from `off`: the count; a gone peer is -32, never SIGPIPE. */
   export function netWrite(fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
+  /** `netWrite` of `a`'s range then `b`'s, in one system call: the count of both, at most `aLen + bLen`. */
+  export function netWrite2(
+    fd: i32,
+    a: readonly u8[],
+    aOff: i32,
+    aLen: i32,
+    b: readonly u8[],
+    bOff: i32,
+    bLen: i32
+  ): i32;
   /** Shut the read side (0), the write side (1) or both (2). */
   export function netShutdown(fd: i32, how: i32): i32;
   export function netClose(fd: i32): i32;
@@ -1059,6 +1079,58 @@ declare module "nish:region" {
   export function free<T>(r: Region<T>): void;
 }
 
+// `nish:async` (WP49, docs/LANGUAGE.md -> Async functions). `tsc` sees ordinary
+// promises; what `nish` adds is that each argument is a direct call to an
+// `async` function, written where it is made, which the checker holds it to
+// (`src/async-check.ts`), and that `awaitAll` takes two to eight of them.
+declare module "nish:async" {
+  /** Start `task` and go on without its answer; it runs until it first waits. */
+  export function spawn(task: Promise<void>): void;
+  /** Await every call at once; the answers come in the order the calls are written. */
+  export function awaitAll<A, B>(a: Promise<A>, b: Promise<B>): Promise<[A, B]>;
+  export function awaitAll<A, B, C>(a: Promise<A>, b: Promise<B>, c: Promise<C>): Promise<[A, B, C]>;
+  export function awaitAll<A, B, C, D>(
+    a: Promise<A>,
+    b: Promise<B>,
+    c: Promise<C>,
+    d: Promise<D>,
+  ): Promise<[A, B, C, D]>;
+  export function awaitAll<A, B, C, D, E>(
+    a: Promise<A>,
+    b: Promise<B>,
+    c: Promise<C>,
+    d: Promise<D>,
+    e: Promise<E>,
+  ): Promise<[A, B, C, D, E]>;
+  export function awaitAll<A, B, C, D, E, F>(
+    a: Promise<A>,
+    b: Promise<B>,
+    c: Promise<C>,
+    d: Promise<D>,
+    e: Promise<E>,
+    f: Promise<F>,
+  ): Promise<[A, B, C, D, E, F]>;
+  export function awaitAll<A, B, C, D, E, F, G>(
+    a: Promise<A>,
+    b: Promise<B>,
+    c: Promise<C>,
+    d: Promise<D>,
+    e: Promise<E>,
+    f: Promise<F>,
+    g: Promise<G>,
+  ): Promise<[A, B, C, D, E, F, G]>;
+  export function awaitAll<A, B, C, D, E, F, G, H>(
+    a: Promise<A>,
+    b: Promise<B>,
+    c: Promise<C>,
+    d: Promise<D>,
+    e: Promise<E>,
+    f: Promise<F>,
+    g: Promise<G>,
+    h: Promise<H>,
+  ): Promise<[A, B, C, D, E, F, G, H]>;
+}
+
 // ---- Arena (docs/LANGUAGE.md -> Arena) ---------------------------------------
 
 declare const Arena: {

package/runtime/nish.h

@@ -714,8 +714,10 @@ bool nish_is_executable(const nish_str *path);
  * `nish_tcp_accept(fd, peer)`: a new descriptor and the peer's address.
  * `nish_net_read` / `nish_net_write(fd, buf, off, len)`: bytes `[off, off +
  * len)` of `buf`, which the compiled call has range-checked; a write to a
- * gone peer is -32, never SIGPIPE. `nish_net_shutdown(fd, how)`: 0 read, 1
- * write, 2 both. `nish_net_close(fd)`.
+ * gone peer is -32, never SIGPIPE. `nish_net_write2(fd, a, aoff, alen, b,
+ * boff, blen)`: both ranges in one `sendmsg`, `a`'s bytes first, answering the
+ * count written (short when the socket buffer fills) or the same errors.
+ * `nish_net_shutdown(fd, how)`: 0 read, 1 write, 2 both. `nish_net_close(fd)`.
  * `nish_net_set_option(fd, option, value)`: one socket option from a
  * 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
@@ -784,6 +786,8 @@ int32_t nish_tcp_listen_flags(const nish_str *host, int32_t port, int32_t backlo
 int32_t nish_tcp_accept(int32_t fd, nish_array *peer);
 int32_t nish_net_read(int32_t fd, nish_array *buf, int64_t off, int64_t len);
 int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t len);
+int32_t nish_net_write2(int32_t fd, const nish_array *a, int64_t aoff, int64_t alen, const nish_array *b,
+                        int64_t boff, int64_t blen);
 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);

package/runtime/nish.mjs

@@ -139,6 +139,7 @@ for (const name of [
   "tcpAccept",
   "netRead",
   "netWrite",
+  "netWrite2",
   "netShutdown",
   "netClose",
   "tcpConnect",
@@ -379,6 +380,9 @@ registerHooks({
     if (specifier === "nish:simd") {
       return next(new URL("./core.mjs", import.meta.url).href, context);
     }
+    if (specifier === "nish:async") {
+      return next(new URL("./async.mjs", import.meta.url).href, context);
+    }
     if (specifier === "nish:region") {
       return { url: `data:text/javascript,${encodeURIComponent(regionSource)}`, shortCircuit: true };
     }

package/runtime/runtime-net.c

@@ -417,6 +417,28 @@ int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t l
   return n < 0 ? nish_net_fail() : (int32_t)n;
 }
 
+/* `netWrite2(fd, a, aoff, alen, b, boff, blen)`: `netWrite` of two ranges in
+   one `sendmsg`, so a response head and its body leave in one system call
+   without being copied together first. Both ranges are checked by the
+   compiled call. The count is at most `alen + blen`; a sum past `INT32_MAX`
+   is offered only up to it, so the answer always fits, and a short write is a
+   count, as `netWrite`'s is. */
+int32_t nish_net_write2(int32_t fd, const nish_array *a, int64_t aoff, int64_t alen, const nish_array *b,
+                        int64_t boff, int64_t blen) {
+  struct iovec iov[2];
+  struct msghdr msg;
+  if (blen > (int64_t)INT32_MAX - alen) blen = (int64_t)INT32_MAX - alen;
+  iov[0].iov_base = a->data + aoff;
+  iov[0].iov_len = (size_t)alen;
+  iov[1].iov_base = b->data + boff;
+  iov[1].iov_len = (size_t)blen;
+  memset(&msg, 0, sizeof msg);
+  msg.msg_iov = iov;
+  msg.msg_iovlen = 2;
+  ssize_t n = sendmsg(fd, &msg, NISH_NOSIGNAL);
+  return n < 0 ? nish_net_fail() : (int32_t)n;
+}
+
 /* `netShutdown(fd, how)`: 0 the read side, 1 the write side, 2 both, which
    are `SHUT_RD`, `SHUT_WR` and `SHUT_RDWR` on both platforms. */
 int32_t nish_net_shutdown(int32_t fd, int32_t how) {