@amritk/nish-x86_64-linux 0.30.0 → 0.32.0

package/std/net/prefork.ts

@@ -51,6 +51,26 @@
  * gone longer than that. With `restart` off nothing is signalled; a worker sees
  * its peer's exit as a hang-up.
  *
+ * **Listeners and pinning.** With `listenPort` set (0 or above), the
+ * supervisor binds one `SO_REUSEPORT` listener per worker itself, in index
+ * order, keeps them for its whole run and hands listener `k` to every start of
+ * worker `k` after the channel ends; `preforkListener(args)` answers it in the
+ * worker (`--nish-prefork-listener=`, before the channels flag), so a worker
+ * serves that descriptor instead of binding its own. Port 0 binds the first
+ * listener anywhere and the rest to its port. With `pin` on as well, each
+ * listener steers by CPU (`tcpListenFlags`' flag 4): the kernel hands a
+ * connection that arrived on CPU `k` to listener `k`, and a worker that is
+ * restarted takes the same listener, so the order holds across restarts,
+ * which it would not if each worker bound its own. `pin` alone makes each
+ * worker call `setCpuAffinity(k)` before `preforkWith` answers it, so worker
+ * `k` runs on CPU `k` only; a worker the kernel refuses (CPU `k` outside the
+ * process's mask) says so on stderr and runs unpinned. More workers than
+ * `availableParallelism()` is refused with a panic, since a worker past the
+ * last CPU would be pinned nowhere and, steered, handed nothing. Pinning and
+ * steering are Linux's: elsewhere the supervisor says once that the workers
+ * run unpinned, and the listeners are plain `SO_REUSEPORT` ones. Both are off
+ * by default.
+ *
  * **How many.** `NISH_WORKERS` when it is a positive whole number, else
  * `PreforkConfig.workers` when that is positive, else
  * `availableParallelism()` on Linux and 1 elsewhere: Darwin shares a
@@ -83,10 +103,12 @@ import {
   NET_UNIX_SEQPACKET,
   NET_UNIX_STREAM,
   netClose,
+  netLocalPort,
   netRead,
   pollAdd,
   pollCreate,
   pollWait,
+  tcpListenFlags,
   unixSocketPair,
 } from "nish:net"
 import {
@@ -96,6 +118,7 @@ import {
   monotonicNanos,
   platform,
   readSignal,
+  setCpuAffinity,
   signalFd,
   spawn,
   spawnWithFds,
@@ -111,6 +134,12 @@ export const PREFORK_WORKER_FLAG: string = "--nish-prefork-worker="
  * for none.
  */
 export const PREFORK_CHANNELS_FLAG: string = "--nish-prefork-channels="
+/**
+ * The argument before the channels flag, or before the worker flag when there
+ * is none, when the supervisor holds the listeners: the worker's listener's
+ * descriptor.
+ */
+export const PREFORK_LISTENER_FLAG: string = "--nish-prefork-listener="
 
 /** What `preforkWith` answers in the supervisor once its workers are gone. */
 export const PREFORK_STOPPED: i32 = -1
@@ -127,6 +156,8 @@ export const PREFORK_WORKERS_EXITED: i32 = -3
 
 /** The supervisor's numbers; every one is checked by `preforkWith`. */
 export class PreforkConfig {
+  /** The address the listeners of `listenPort` bind. */
+  listenHost: string = "0.0.0.0"
   /** Workers to start; 0 takes `NISH_WORKERS` or the platform's default. */
   workers: i32 = 0
   /** How often, in milliseconds, the supervisor reaps when nothing wakes it. */
@@ -139,6 +170,23 @@ export class PreforkConfig {
   quickExitMs: i32 = 1000
   /** How long the workers get to exit after SIGTERM before SIGKILL. */
   graceMs: i32 = 5000
+  /** The worker every other worker gets a socketpair to; -1 for none. */
+  serviceWorker: i32 = -1
+  /**
+   * What every channel is: `NET_UNIX_STREAM` (1), or `NET_UNIX_SEQPACKET` (2),
+   * which keeps each write one message but only Linux has. Stream is the
+   * default because it works on Darwin too.
+   */
+  channelKind: i32 = 1
+  /**
+   * The port the supervisor binds one listener per worker on, 0 for any; -1,
+   * the default, leaves each worker to bind its own.
+   */
+  listenPort: i32 = -1
+  /** Their backlog. */
+  listenBacklog: i32 = 1024
+  /** Their `tcpListenFlags` beyond `SO_REUSEPORT`, which is always set: 0, or 2 for `TCP_NODELAY`. */
+  listenFlags: i32 = 0
   /**
    * Start a worker that exited again. Off, a worker that exits stays gone,
    * and the supervisor returns once none is left.
@@ -146,14 +194,14 @@ export class PreforkConfig {
   restart: boolean = true
   /** Give each worker a socketpair to the supervisor (`preforkSupervise`). */
   supervisorChannels: boolean = false
-  /** The worker every other worker gets a socketpair to; -1 for none. */
-  serviceWorker: i32 = -1
   /**
-   * What every channel is: `NET_UNIX_STREAM` (1), or `NET_UNIX_SEQPACKET` (2),
-   * which keeps each write one message but only Linux has. Stream is the
-   * default because it works on Darwin too.
+   * Pin worker `k` to CPU `k` (`setCpuAffinity`), and with `listenPort`, steer
+   * each connection to the listener of the CPU that received it. Linux only;
+   * elsewhere the workers run unpinned. `k` is the CPU number, not the `k`-th
+   * allowed CPU: under a mask that skips CPU `k`, worker `k` runs unpinned and
+   * a connection received past the listeners falls back to the kernel's hash.
    */
-  channelKind: i32 = 1
+  pin: boolean = false
 }
 
 /** True when `s` is one or more ASCII digits and nothing else. */
@@ -206,8 +254,8 @@ export const preforkIndex = (args: string[]): i32 => {
 }
 
 /**
- * `args` (`process.argv`) without the worker flag and the channels flag before
- * it, the same in every process.
+ * `args` (`process.argv`) without the worker flag and the channels and
+ * listener flags before it, the same in every process.
  */
 export const preforkArgs = (args: string[]): string[] => {
   let keep: i32 = toI32(args.length)
@@ -216,6 +264,9 @@ export const preforkArgs = (args: string[]): string[] => {
     if (keep > 1 && args[keep - 1].startsWith(PREFORK_CHANNELS_FLAG)) {
       keep = keep - 1
     }
+    if (keep > 1 && args[keep - 1].startsWith(PREFORK_LISTENER_FLAG)) {
+      keep = keep - 1
+    }
   }
   const out: string[] = []
   for (let i: i32 = 0; i < toI32(args.length); i++) {
@@ -258,6 +309,21 @@ export const preforkServiceChannel = (args: string[]): i32 => preforkChannel(arg
 export const preforkServiceChannelOf = (args: string[], index: i32): i32 =>
   index < 0 || index > 2147483645 ? -1 : preforkChannel(args, 2 + index)
 
+/** In a worker, the listener the supervisor bound for it (`listenPort`); -1 when none. */
+export const preforkListener = (args: string[]): i32 => {
+  if (preforkIndex(args) < 0) {
+    return -1
+  }
+  for (let back: i32 = 2; back <= 3 && back < toI32(args.length); back++) {
+    const flag: string = args[toI32(args.length) - back]
+    if (flag.startsWith(PREFORK_LISTENER_FLAG)) {
+      const digits: string = flag.substring(PREFORK_LISTENER_FLAG.length)
+      return preforkDigits(digits) ? parseInt(digits) : -1
+    }
+  }
+  return -1
+}
+
 /** Milliseconds on the monotonic clock. */
 const preforkNowMs = (): i64 => monotonicNanos() / 1000000
 
@@ -298,6 +364,8 @@ class PreforkSupervisor {
   service: i32
   /** The group is being stopped, to be started again once none of it is left. */
   cascading: boolean = false
+  /** Worker i's listener at i, held for the whole run; empty without `listenPort`. */
+  listeners: i32[]
 
   constructor(config: PreforkConfig, args: string[], count: i32, loop: i32) {
     this.config = config
@@ -305,6 +373,7 @@ class PreforkSupervisor {
     this.service = config.serviceWorker
     this.toService = []
     this.fromWorkers = []
+    this.listeners = []
     this.args = preforkArgs(args)
     const self: string | null = platform === "linux" ? realpathSync("/proc/self/exe") : null
     this.program = self !== null ? self : this.args[0]
@@ -359,7 +428,12 @@ class PreforkSupervisor {
     for (let i: i32 = 1; i < toI32(this.args.length); i++) {
       argv.push(this.args[i])
     }
-    if (fds.length > 0) {
+    const channels: boolean = fds.length > 0
+    if (this.listeners.length > 0) {
+      fds.push(this.listeners[index])
+      argv.push(`${PREFORK_LISTENER_FLAG}${2 + fds.length}`)
+    }
+    if (channels) {
       argv.push(`${PREFORK_CHANNELS_FLAG}${fields.join(",")}`)
     }
     argv.push(`${PREFORK_WORKER_FLAG}${index}`)
@@ -576,6 +650,37 @@ class PreforkSupervisor {
     return true
   }
 
+  /**
+   * One listener per worker, in index order, which is the order steering
+   * counts CPUs in; false, with the ones made closed, when one cannot bind.
+   */
+  listen(steer: boolean): boolean {
+    const config: PreforkConfig = this.config
+    const flags: i32 = config.listenFlags | 1 | (steer ? 4 : 0)
+    let port: i32 = config.listenPort
+    for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
+      const fd: i32 = tcpListenFlags(config.listenHost, port, config.listenBacklog, flags)
+      if (fd < 0) {
+        console.error(`nish/net/prefork: cannot listen on ${config.listenHost}:${port} (${fd})`)
+        this.closeListeners()
+        return false
+      }
+      this.listeners.push(fd)
+      if (port === 0) {
+        port = netLocalPort(fd)
+      }
+    }
+    return true
+  }
+
+  /** Close the listeners `listen` made. */
+  closeListeners(): void {
+    for (let i: i32 = 0; i < toI32(this.listeners.length); i++) {
+      netClose(this.listeners[i])
+    }
+    this.listeners = []
+  }
+
   /** Send `sig` to every running worker. */
   signal(sig: i32): void {
     for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
@@ -644,6 +749,15 @@ const preforkInvalid = (config: PreforkConfig): string => {
   if (config.serviceWorker < -1) {
     return "serviceWorker below -1"
   }
+  if (config.listenPort < -1 || config.listenPort > 65535) {
+    return "listenPort not -1 or 0..65535"
+  }
+  if (config.listenBacklog <= 0) {
+    return "listenBacklog not above 0"
+  }
+  if (config.listenFlags !== 0 && config.listenFlags !== 2) {
+    return "listenFlags not 0 or 2"
+  }
   return ""
 }
 
@@ -679,8 +793,11 @@ export const preforkWith = (args: string[], config: PreforkConfig): i32 => {
  * supervisor closes it after a hang-up, when the worker is reaped and when it
  * stops, and a restarted worker comes with a new one. Panics, besides, when
  * `serviceWorker` is not below the worker count or the count is above 64 with
- * a service worker, the most `spawnWithFds` hands one child; and, through
- * `preforkInvalid`, on seqpacket channels off Linux.
+ * a service worker (63 with `listenPort`), the most `spawnWithFds` hands one
+ * child; when `pin`, on Linux, asks for more workers than
+ * `availableParallelism()`; and, through `preforkInvalid`, on seqpacket
+ * channels off Linux. A listener that cannot bind answers
+ * `PREFORK_SPAWN_FAILED` before any worker starts.
  */
 export const preforkSupervise = <S>(
   args: string[],
@@ -692,13 +809,27 @@ export const preforkSupervise = <S>(
   if (invalid !== "") {
     panic(`nish/net/prefork: ${invalid}`)
   }
+  const pin: boolean = config.pin && platform === "linux"
   const index: i32 = preforkIndex(args)
   if (index >= 0) {
+    const pinned: i32 = pin ? setCpuAffinity(index) : 0
+    if (pinned < 0) {
+      console.error(`nish/net/prefork: worker ${index} runs unpinned (${pinned})`)
+    }
     return index
   }
   const count: i32 = preforkWorkerCount(config.workers, getenv("NISH_WORKERS"))
-  if (config.serviceWorker >= count || (config.serviceWorker >= 0 && count > 64)) {
-    panic(`nish/net/prefork: serviceWorker not below ${count} workers, or above 64 workers`)
+  // A held listener is one more descriptor for every worker, the service one too.
+  const fdMax: i32 = config.listenPort >= 0 ? 63 : 64
+  if (config.serviceWorker >= count || (config.serviceWorker >= 0 && count > fdMax)) {
+    panic(`nish/net/prefork: serviceWorker not below ${count} workers, or above ${fdMax} workers`)
+  }
+  const cpus: i32 = pin ? availableParallelism() : 0
+  if (pin && count > cpus) {
+    panic(`nish/net/prefork: pin with ${count} workers on ${cpus} CPUs`)
+  }
+  if (config.pin && !pin) {
+    console.error("nish/net/prefork: pinning needs Linux; the workers run unpinned")
   }
   const signals: i32 = signalFd()
   const loop: i32 = pollCreate()
@@ -712,6 +843,10 @@ export const preforkSupervise = <S>(
     return PREFORK_SPAWN_FAILED
   }
   const supervisor = new PreforkSupervisor(config, args, count, loop)
+  if (config.listenPort >= 0 && !supervisor.listen(pin)) {
+    netClose(loop)
+    return PREFORK_SPAWN_FAILED
+  }
   // Token 0 is the signal pipe, token i + 1 worker i's channel.
   const ready: i32[] = new Array<i32>(2 * count + 2)
   let result: i32 = PREFORK_STOPPED
@@ -748,6 +883,7 @@ export const preforkSupervise = <S>(
     }
   }
   supervisor.stop(loop, signals, ready)
+  supervisor.closeListeners()
   netClose(loop)
   return result
 }

package/std/net/router.ts

@@ -69,7 +69,7 @@ export const ROUTER_BAD_ESCAPE: i32 = -10
 /** `routerDecode`: the decoded bytes do not fit `out`; nothing was written. */
 export const ROUTER_NO_ROOM: i32 = -11
 
-/** The longest method `add` takes, as `nish/net/http1`'s `HTTP1_MAX_METHOD`. */
+/** The longest method `add` takes, as `nish/net/http1-codec`'s `HTTP1_MAX_METHOD`. */
 const ROUTER_MAX_METHOD: i32 = 32
 /** No node or route: an `i32` spelled once, so that `--number-mode f64` does not read a bare `-1` as a double. */
 const ROUTER_NONE: i32 = -1

package/std/net/upstream.ts

@@ -2,7 +2,7 @@
  * `nish/net/upstream` — outbound HTTP/1.1 calls from a route handler that
  * never block its worker: a pool of keep-alive connections to one origin,
  * registered on the `HttpHandler`'s own poll loop and read through the
- * `nish/net/http1-client` codec.
+ * `nish/net/http1-client-codec` codec.
  *
  *     const h = new HttpHandler(new HandlerLimits(), listener, router)
  *     const users = new Upstream(h, "http://127.0.0.1:9000", new UpstreamLimits())
@@ -87,8 +87,8 @@ import {
   HTTP1_HEAD,
   HTTP1_NEED_MORE,
   HTTP1_NO_BODY,
-} from "nish/net/http1"
-import { HTTP1_INFORMATIONAL, Http1ResponseParser, http1WriteRequestHead } from "nish/net/http1-client"
+} from "nish/net/http1-codec"
+import { HTTP1_INFORMATIONAL, Http1ResponseParser, http1WriteRequestHead } from "nish/net/http1-client-codec"
 import { OutboundPolicy, outboundAddressText, outboundFilter, outboundHostAllowed } from "nish/net/outbound"
 import { Url, urlParse } from "nish/net/url"
 import {

package/std/net/websocket.ts

@@ -2,7 +2,7 @@
  * `nish/net/websocket` — RFC 6455 WebSocket framing and both sides of the
  * opening handshake, sans-IO: bytes in, events and bytes out.
  *
- * **The server's handshake.** `nish/net/http1` reads the client's request;
+ * **The server's handshake.** `nish/net/http1-codec` reads the client's request;
  * `websocketRequestKey(parser)` answers its `Sec-WebSocket-Key` when the head
  * is a valid opening handshake (§4.2.1), `websocketOfferedProtocols(parser)`
  * the subprotocols it offers, and `websocketUpgradeResponse(key, protocol)`
@@ -15,7 +15,7 @@
  * random bytes as the key, `websocketUpgradeRequest(host, target, key,
  * protocols)` writes the GET that asks to upgrade, and
  * `websocketCheckResponse(parser, key, offered)` reads the server's answer,
- * parsed by `nish/net/http1-client` after `expectUpgrade()`: it answers the
+ * parsed by `nish/net/http1-client-codec` after `expectUpgrade()`: it answers the
  * negotiated subprotocol, or which rule of §4.1 the response broke. What
  * `HTTP1_UPGRADE`'s `tunnelBytes()` answers is the first input for
  * `WsDecoder(false, …)`. This module draws no randomness: the nonce and every
@@ -77,8 +77,8 @@ import {
   http1ResponseHead,
   http1SameWord,
   http1Text,
-} from "nish/net/http1"
-import { Http1ResponseParser, http1UpgradeRequestHead } from "nish/net/http1-client"
+} from "nish/net/http1-codec"
+import { Http1ResponseParser, http1UpgradeRequestHead } from "nish/net/http1-client-codec"
 
 /** The GUID RFC 6455 §1.3 appends to the client's key before hashing it. */
 export const WS_GUID: string = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
@@ -954,7 +954,7 @@ export const websocketClientKey = (nonce: u8[]): string | null => {
  * with `Host`, `Sec-WebSocket-Key`, `Sec-WebSocket-Version: 13`, the offered
  * `protocols` in one `Sec-WebSocket-Protocol` field when there are any, and
  * `Upgrade: websocket` and `Connection: Upgrade`, written by
- * `nish/net/http1-client`'s `http1UpgradeRequestHead`. Answers `null` for a
+ * `nish/net/http1-client-codec`'s `http1UpgradeRequestHead`. Answers `null` for a
  * key `websocketKeyIsValid` refuses, a protocol that is not a token (an empty
  * one, or one holding a comma, a space, CR or LF), a protocol offered twice, an
  * empty host, and everything the request writer refuses (CR, LF or another

package/std/region.ts

@@ -0,0 +1,95 @@
+/**
+ * `nish:region` — memory a program frees when it says so (docs/LANGUAGE.md,
+ * "Regions").
+ *
+ *     import { Region, enterWith, free, regionWith } from "nish:region"
+ *
+ *     const r: Region<Session> = regionWith(id, open)
+ *     const n: i32 = enterWith(r, out, serve)
+ *     free(r)
+ *
+ * This file is the source behind the builtin module, and it is imported only
+ * by that name: `nish/region` is refused, so there is one spelling for the
+ * checker's rules to be read under (`src/region-check.ts`). What is written
+ * here is the meaning, over five intrinsics the compiler gives bodies of their
+ * own (`src/emit-region.ts`), which swap the thread's arena for the region's
+ * around the function they run:
+ *
+ *   - `region(f)` makes a region, runs `f` with every allocation landing in
+ *     it, and keeps what `f` answers as the region's root;
+ *   - `enter(r, f)` runs `f(root)` the same way, and answers `f`'s scalar;
+ *   - `free(r)` gives the region's memory back. A handle used after it is
+ *     freed, or entered twice, or freed while entered, stops the program.
+ *
+ * A `Region<T>` is a handle, a 64-bit integer, and not a pointer: the root
+ * never leaves the region except through `enter`'s function, and that
+ * function answers a scalar, so nothing outside a region can point into it.
+ *
+ * Under Node the module is answered by `runtime/nish.mjs`, where a region is
+ * an entry in a table and `free` drops it.
+ */
+
+/**
+ * A region whose root is a `T`. The compiler resolves the name to a type of
+ * its own, a 64-bit handle; this declaration is what `tsc` and the editor
+ * read through `runtime/nish.d.ts`.
+ */
+export class Region<T> {
+  /** Never read: the compiler's type has no fields. */
+  root: T | null = null
+}
+
+// The five intrinsics below are the runtime's region calls. Each is written
+// here as a call of itself, so it has a type and nothing more; the compiler
+// gives every instance a body of its own (`src/emit-region.ts`), one call into
+// `runtime/runtime-region.c`.
+
+/** `nish_region_new`: a fresh handle, never 0. */
+const handleNew = (): i64 => handleNew()
+
+/** `nish_region_enter` on a new region, whose root is still null. */
+const open = (h: i64): void => open(h)
+
+/** `nish_region_leave` keeping `root`: the handle, typed by its root. */
+const close = <T>(h: i64, root: T): Region<T> => close(h, root)
+
+/** `nish_region_enter` on a made region: its root. */
+const reopen = <T>(r: Region<T>): T => reopen(r)
+
+/** `nish_region_leave` with the root `reopen` gave. */
+const leave = <T>(r: Region<T>, root: T): void => leave(r, root)
+
+/** A new region, whose root is what `f` answers; everything `f` allocates is in it. */
+export const region = <T>(f: () => T): Region<T> => {
+  const h: i64 = handleNew()
+  open(h)
+  return close(h, f())
+}
+
+/** `region` with one argument for `f`, because the arrow `region` runs captures nothing. */
+export const regionWith = <A, T>(arg: A, f: (arg: A) => T): Region<T> => {
+  const h: i64 = handleNew()
+  open(h)
+  return close(h, f(arg))
+}
+
+/** `f(root)`, allocating in the region: the one way to reach what a region holds. */
+export const enter = <T, R>(r: Region<T>, f: (root: T) => R): R => {
+  const root: T = reopen(r)
+  const result: R = f(root)
+  leave(r, root)
+  return result
+}
+
+/** `enter` with one argument for `f`. */
+export const enterWith = <T, A, R>(r: Region<T>, arg: A, f: (root: T, arg: A) => R): R => {
+  const root: T = reopen(r)
+  const result: R = f(root, arg)
+  leave(r, root)
+  return result
+}
+
+/** Give the region's memory back. The handle is dead after it. The compiler writes the body. */
+export const free = <T>(_r: Region<T>): void => {
+  // `nish_region_free`: see above.
+}

package/std/sort.ts

@@ -0,0 +1,178 @@
+/**
+ * `std/sort` — `xs.sort(cmp)` on an array, in Nish: a stable merge sort,
+ * compiled once per comparator.
+ *
+ * A program does not import this module. A `.sort(cmp)` call is what loads it
+ * (the checker's `importSort`), and the checker routes the call to `sortWith`
+ * here. `cmp` is a compile-time function parameter, so each comparator is an
+ * instantiation of its own whose body calls the comparator directly — there is
+ * no function pointer. Under Node and `tsc` the call is the platform's
+ * `Array.prototype.sort`, so nothing here runs there.
+ *
+ * **Same order as Node.** `Array.prototype.sort` is stable (ES2019), so for a
+ * comparator that is a consistent total preorder there is exactly one answer,
+ * and any stable sort gives it. A comparator's result is read only as "greater
+ * than zero or not": a later element moves before an earlier one only when
+ * the comparator answers a positive number for (earlier, later), so a negative
+ * zero and NaN are zero, as Node treats them.
+ *
+ * **Shape.** The array is copied once into a scratch array of the same
+ * length, the only allocation, which the function's arena scope gives back
+ * before it returns, so a sort leaves `Arena.used()` where it was. Runs of
+ * `RUN` are sorted by insertion from the scratch into the array (a strictly
+ * descending run is copied reversed instead), then merged
+ * bottom-up, alternating between the two, and copied back once if the last
+ * pass ended in the scratch. A pair of runs already in order is copied without
+ * a merge. Every merge takes from the left run on a tie, which is what makes
+ * it stable.
+ *
+ * **No element is held across a write.** An `interface` element is stored
+ * inline, and `const v = xs[i]` is a pointer into the array, so an insertion
+ * sort in place would overwrite the element it is inserting. Every step here
+ * reads from one array and writes the other, and moves a whole slot, which for
+ * an inline record is one copy of its bytes.
+ *
+ * **Proofs.** Every index is proven in range by the guard written beside it,
+ * so no access keeps its bounds check. The run arithmetic wraps only where
+ * the operands are proven to lie in `0..n`, so it cannot wrap: a difference
+ * of two of them, or a sum taken only when it stays below `n`.
+ */
+
+import { wrappingAdd, wrappingSub } from "nish:unsafe"
+
+/** The length of the runs insertion sort makes before the first merge. */
+const RUN: i32 = 32
+
+/**
+ * `lo + step`, or `n` when that is not below `n`. Every caller has
+ * `0 <= lo <= n`, so `n - lo` cannot wrap, and the sum is taken only below `n`.
+ */
+const stepTo = (lo: i32, step: i32, n: i32): i32 => (wrappingSub(n, lo) > step ? wrappingAdd(lo, step) : n)
+
+/**
+ * `src[lo..hi)` sorted by insertion into `dst[lo..hi)`. The comparator call
+ * forgets every array length, so each access after it repeats its guard.
+ */
+const insertionRun = <T>(src: T[], dst: T[], cmp: (a: T, b: T) => number, lo: i32, hi: i32): void => {
+  // A strictly descending run is copied reversed: no two of its elements are
+  // equal, so reversing it keeps the sort stable, and costs one comparison each.
+  // `lo < hi`, and `d` steps only while below `hi`, so neither `+ 1` wraps.
+  let d = wrappingAdd(lo, 1)
+  while (d > 0 && d < hi && d < toI32(src.length)) {
+    const p = d - 1
+    if (!(cmp(src[p], src[d]) > 0)) {
+      break
+    }
+    d = wrappingAdd(d, 1)
+  }
+  if (d >= hi) {
+    // `hi > lo >= 0`, so `hi - 1` does not wrap, and `r` steps down only from `r >= 0`.
+    let r = wrappingSub(hi, 1)
+    for (let k: i32 = lo; k >= 0 && k < hi && k < toI32(dst.length) && r >= 0 && r < toI32(src.length); k++) {
+      dst[k] = src[r]
+      r = wrappingSub(r, 1)
+    }
+    return
+  }
+  for (let i: i32 = lo; i >= 0 && i < hi; i++) {
+    let j = i
+    while (j > lo && j > 0 && j < toI32(dst.length) && i < toI32(src.length)) {
+      const k = j - 1
+      if (!(cmp(dst[k], src[i]) > 0) || k < 0 || k >= toI32(dst.length) || j >= toI32(dst.length)) {
+        break
+      }
+      dst[j] = dst[k]
+      j = k
+    }
+    if (i < toI32(src.length) && j >= 0 && j < toI32(dst.length)) {
+      dst[j] = src[i]
+    }
+  }
+}
+
+/** `src[lo..hi)` copied into `dst[lo..hi)`. */
+const copyRun = <T>(src: T[], dst: T[], lo: i32, hi: i32): void => {
+  for (let k: i32 = lo; k >= 0 && k < hi && k < toI32(src.length) && k < toI32(dst.length); k++) {
+    dst[k] = src[k]
+  }
+}
+
+/**
+ * The sorted runs `src[lo..mid)` and `src[mid..hi)` merged into `dst[lo..hi)`,
+ * or copied when the last of the left run is not after the first of the right.
+ */
+const mergeRuns = <T>(src: T[], dst: T[], cmp: (a: T, b: T) => number, lo: i32, mid: i32, hi: i32): void => {
+  if (mid > 0 && mid < hi && mid < toI32(src.length)) {
+    const last = mid - 1
+    if (last < toI32(src.length) && !(cmp(src[last], src[mid]) > 0)) {
+      copyRun(src, dst, lo, hi)
+      return
+    }
+  }
+  let i = lo
+  let j = mid
+  for (let k: i32 = lo; k >= 0 && k < hi; k++) {
+    let right = i >= mid
+    if (!right && j < hi && i >= 0 && i < toI32(src.length) && j >= 0 && j < toI32(src.length)) {
+      right = cmp(src[i], src[j]) > 0
+    }
+    if (right) {
+      if (j >= 0 && j < toI32(src.length) && k < toI32(dst.length)) {
+        dst[k] = src[j]
+      }
+      // `j` steps at most `hi - mid` times from `mid`, so it stays at most `hi`.
+      j = wrappingAdd(j, 1)
+    } else {
+      if (i >= 0 && i < toI32(src.length) && k < toI32(dst.length)) {
+        dst[k] = src[i]
+      }
+      // `i` steps at most `mid - lo` times from `lo`, so it stays at most `mid`.
+      i = wrappingAdd(i, 1)
+    }
+  }
+}
+
+/** One bottom-up pass: every pair of adjacent `width`-runs of `src` merged into `dst`. */
+const mergePass = <T>(src: T[], dst: T[], cmp: (a: T, b: T) => number, n: i32, width: i32): void => {
+  let lo: i32 = 0
+  while (lo >= 0 && lo < n) {
+    const mid = stepTo(lo, width, n)
+    const hi = stepTo(mid, width, n)
+    mergeRuns(src, dst, cmp, lo, mid, hi)
+    lo = hi
+  }
+}
+
+/** `xs` sorted in place by `cmp`, stably, and answered: what `xs.sort(cmp)` compiles to. */
+export const sortWith = <T>(xs: T[], cmp: (a: T, b: T) => number): T[] => {
+  const n: i32 = toI32(xs.length)
+  if (n < 2) {
+    return xs
+  }
+  // One allocation at full size, every slot written before any is read: the
+  // checker lets this `new Array<T>(n)` hold any `T`, and neither emitter
+  // zero-fills it (`isSortInstance`).
+  const tmp = new Array<T>(n)
+  copyRun(xs, tmp, 0, n)
+  let lo: i32 = 0
+  while (lo >= 0 && lo < n) {
+    const hi = stepTo(lo, RUN, n)
+    insertionRun(tmp, xs, cmp, lo, hi)
+    lo = hi
+  }
+  let inTmp = false
+  let width: i32 = RUN
+  while (width > 0 && width < n) {
+    if (inTmp) {
+      mergePass(tmp, xs, cmp, n, width)
+    } else {
+      mergePass(xs, tmp, cmp, n, width)
+    }
+    inTmp = !inTmp
+    width = stepTo(width, width, n)
+  }
+  if (inTmp) {
+    copyRun(tmp, xs, 0, n)
+  }
+  return xs
+}