@mark1russell7/machines 0.0.0-stage → 0.3.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @mark1russell7/machines
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The machine documents of the systems program, in one place. Each document is a state machine as data, in the format `mark1russell7.machine/1` of [`@mark1russell7/algebra`](https://www.npmjs.com/package/@mark1russell7/algebra). Each document describes one system at one version, from the source of that version.
+
+## The machine document
+
+A machine document gives the states, events, knobs, timers and transitions of one machine.
+
+- **States and transitions.** A transition goes from one or more states to a state, on one or more events. Each transition can name the file and the line that it comes from (`source`).
+- **Events.** Each event has a kind. The kinds are `rx` (a segment in), `tx` (a segment out), `app` (a call of the application), `timer`, `local`, `packet` and `peer`.
+- **Knobs.** Each knob has its key in its system, its scope, its unit and its default.
+- **Timers.** A timer has a duration over the knobs, the events that arm it and cancel it, and the event that it fires. It can also have a lateness and an early bound.
+- **Realizations.** A document can give the time of a mechanism (`realizes`): one of its timers, or a time of its own over its knobs.
+- **Layers.** A document can operate on another machine (`over`), as a driver operates on its kernel socket. `over.machine` names the machine below as `systems.machine.<id>`.
+- **Sources.** Each document names its sources, and each source has a rung. The rung tells the type of the source:
+  - `normative`: a specification, for example an RFC.
+  - `implemented`: the code of the system at the version.
+  - `documented`: the documentation of the system.
+  - `observed`: a measurement of the system.
+  - `derived`: a result of other sources.
+
+The algebra reads these documents. It gives the closed form of each timer, the first detector of a failure, and the recovery after a stall.
+
+## The documents
+
+| Export | Identifier | System and version | Layer | Sources, by rung |
+| --- | --- | --- | --- | --- |
+| `LINUX_TCP` | `linux-tcp` | TCP of Linux 6.6, for kernels from 6.6 to 6.9 | kernel | 4 normative, 7 implemented |
+| `NF_CONNTRACK_TCP` | `nf-conntrack-tcp` | The TCP state machine of conntrack on Linux 6.6.87.2 | middlebox | 4 implemented |
+| `REDIS_CLIENT` | `redis-client` | One client connection of the Redis 8.10.2 server | server | 3 implemented, 1 documented |
+| `IOREDIS_STATUS` | `ioredis-status` | The connection status of ioredis 6.0.0, standalone | driver | 5 implemented |
+| `IOREDIS_SENTINEL` | `ioredis-sentinel` | ioredis 6.0.0 in Sentinel mode | driver | 10 implemented |
+| `SENTINEL` | `valkey-sentinel` | One Sentinel of Valkey 9.1.2, and the failover that it leads | server | 8 implemented, 1 observed |
+| `NODE_HTTP_SERVER` | `node-http-server` | One connection of the `http.Server` of Node 24.21.0 | server | 8 implemented |
+| `NODE_HTTP_AGENT` | `node-http-agent` | One socket of the `http.Agent` of Node 24.21.0 | driver | 9 implemented |
+| `UNDICI_CLIENT` | `undici-client-h1` | The socket of an HTTP/1.1 `Client` of undici 8.12.2 | driver | 8 implemented |
+| `GO_TRANSPORT` | `go-nethttp-transport` | One connection of the `http.Transport` of Go 1.27.2 | driver | 7 implemented |
+| `PROCEDURES_WS_CLIENT` | `procedures-ws-client` | The WebSocket client of `@procedures/client` 0.3.0 | driver | 9 implemented, 1 documented |
+| `PROCEDURES_WS_SERVER` | `procedures-ws-server` | The WebSocket server of `@procedures/client` 0.3.0 | server | 4 implemented |
+| `MONGODB_NODE` | `mongodb-node` | The MongoDB Node driver 7.7.0, for one server of a replica set | driver | 19 implemented |
+| `MONGOD_REPL` | `mongod-replication` | The replication of mongod 9.0.4: one member of a replica set | server | 29 implemented |
+| `MONGOD_SESSION` | `mongod-session` | One client connection of mongod 9.0.4 | server | 6 implemented |
+| `NODE_POSTGRES` | `node-postgres` | node-postgres 8.23.1 with pg-pool 3.14.0: one client of a `pg.Pool` | driver | 30 implemented, 2 documented, 1 derived |
+| `POSTGRES_SESSION` | `postgres-session` | One client connection of a PostgreSQL 17.11 backend | server | 41 implemented, 2 documented |
+| `HIKARICP_PGJDBC` | `hikaricp-pgjdbc` | HikariCP 7.1.0 over pgjdbc 42.7.13: one connection of a pool | driver | 41 implemented, 1 documented, 2 derived |
+| `PGBOUNCER_CLIENT` | `pgbouncer-client` | PgBouncer 1.26.1 in transaction pooling: one client connection | proxy | 29 implemented |
+| `PGBOUNCER_SERVER` | `pgbouncer-server` | PgBouncer 1.26.1 in transaction pooling: one server connection of a pool | proxy | 26 implemented |
+
+Sixteen documents operate on Linux TCP (`over`). Linux TCP, conntrack, the Sentinel and the replication of mongod operate on no other document. The `conditions` of each document give the range where it holds, for example a range of kernels.
+
+The package also gives these parts:
+
+- **`MACHINES`** gives each document by its identifier, for example `MACHINES["linux-tcp"]`.
+- **`MANIFESTATIONS`** gives, for each manifestation of a failure, the incoming events that continue to arrive at Linux TCP. A black hole lets nothing through. The kernel of a frozen process continues to send ACKs, thus `rx.ack` arrives.
+- **The lateness of a user timer.** A Node timer and a Go timer sleep in `epoll_wait`, and the kernel lets that sleep end late. `nodeTimerLateness`, `NODE_TIMER_EARLY` and `goTimerLateness` give these bounds as expressions over the knobs. `nodeLateSeconds`, `nodeEarlySeconds` and `goLateSeconds` give the same bounds as numbers.
+- **The fast timers of undici.** `undiciFastEarly` and `undiciFastLateness` give the bounds of a timer that counts in ticks of `UNDICI_TICK_MS`.
+
+## How a program reads them
+
+Import a document by its name, or find it in `MACHINES` by its identifier. The schema of the algebra examined each document at load, thus a program does not parse it again.
+
+```ts
+import { detection, timerOf } from "@mark1russell7/algebra";
+import { LINUX_TCP, MACHINES, MANIFESTATIONS } from "@mark1russell7/machines";
+
+const values = (name: string) =>
+  ({
+    keepidle: { value: 7200, unit: "s" },
+    keepintvl: { value: 75, unit: "s" },
+    keepcnt: { value: 9, unit: "count" },
+  })[name];
+
+timerOf(LINUX_TCP, "keepalive", values).duration; // { value: 7875, unit: "s" }
+
+const blackhole = { name: "blackhole", passes: MANIFESTATIONS["blackhole"] ?? [] };
+const idle = { state: "ESTABLISHED", inFlight: false };
+detection(LINUX_TCP, idle, blackhole, values).first?.timer; // "keepalive"
+
+MACHINES["ioredis-status"]?.over?.machine; // "systems.machine.linux-tcp"
+```
+
+The workspace of this repository uses the source. The npm package holds the build: ES modules, with each JSON document in the JavaScript.
+
+## How a document changes
+
+A document changes only for one of two reasons:
+
+- **A reason from the source.** The change cites a fact of the source at its version: a file and a line, or a section of a specification. The citation goes in the `source` of a transition, a `note`, or a source of the document.
+- **A measurement.** A run of the harness refutes a time or a transition of the document. The change names the run, and it adds a source with the rung `observed`.
+
+A change to the version of a system changes its sources too. Each fact of the document then cites the new version.
+
+In this repository, a snapshot of the predictions of the cells (`packages/cells/src/__snapshots__/predictions.json`) shows each prediction that a change to a document moves.
+
+### 0.3.7
+
+- **PgBouncer 1.26.1, in transaction pooling.** Two new documents, each from the C source at the tag pgbouncer_1_26_1. Each of them operates on one socket, on Linux TCP:
+  - `pgbouncer-client` is one client connection: its login, its wait in the queue, and its transactions. Between two transactions PgBouncer reads the socket, and in the queue it does not.
+  - `pgbouncer-server` is one server connection of a pool: its connect and its login, its checks, and its close. It also gives the wait of the pool after a failed login (`server_login_retry`).
+  - Each timer of PgBouncer is a check of its janitor, each 333.3 ms, thus up to one period late. Only the TCP connect has its own timer, of libevent.
+  - At the defaults, an idle server older than 30 s gets the empty query as a check before its next use. No timer bounds the reply of the check.
+
+### 0.3.6
+
+- **`hikaricp-pgjdbc`: the queue of the keepalive checks.** The keepalive task of each connection operates on the one thread of the housekeeper (HikariPool.java:644-656). Behind a silent fault, each check waits for its read timeout. Thus the check of one connection can wait for the checks of the other connections. The note of the timer `keepalive` says so. No value of a document changes.
+
+### 0.3.5
+
+- **`postgres-session`: the slack of the SIGALRM of a backend.** The knob `alarm_slack` has the value 10 ms. It is an assumption of the document, as the slack of the two client documents: the source gives no bound. The handler of SIGALRM sets the latch of the backend (timeout.c:364-377). pg_sleep waits on that latch, and it checks for interrupts before each wait (adt/misc.c:391-412). Thus a statement timer ends a sleep at once.
+  - The source of pg_sleep is new. No other part of a document changes.
+
+### 0.3.4
+
+- **`hikaricp-pgjdbc`: the start check of the pool.** At its start, the pool tries once, and after a failure it sleeps 1 s (`start_check`). It tries again while `initializationFailTimeout` has not passed, and then the start fails with PoolInitializationException, with the error of the last try. At the default of 1 ms, the start fails after one try and one sleep. The source is HikariPool.java:567-599.
+  - The knob `initializationFailTimeout`, the state `start-check` and three transitions are new. No other part of a document changes.
+
+### 0.3.3
+
+- **`hikaricp-pgjdbc`: the slack of poll().** The JDK waits for a read or a connect with a timeout in poll() (NioSocketImpl.java at `jdk-21.0.12+8`). Linux ends the wait of poll() up to 0.1 % of its time late, at most 100 ms (fs/select.c of Linux 6.6). Thus four timers get that lateness with the slack of the JVM: the connect, the SSLRequest, the read timeout and the check.
+  - The cells of O13 measured it: a read timeout of 11 s closed its socket up to 11.35 ms late (run 39109649303).
+  - The bands of the HikariCP cells with these timers move in the snapshot. No other document changes.
+
+### 0.3.2
+
+- **`hikaricp-pgjdbc`.** HikariCP 7.1.0 over pgjdbc 42.7.13, for one connection of a pool, from the tags `HikariCP-7.1.0` and `REL42.7.13`. The plan of R3 gives most of its PostgreSQL cells to this client.
+  - HikariCP reads no idle socket. It checks a connection only at a borrow, after more than 500 ms of idle time, and at its keepalive. The keepalive comes each 96 to 120 s from the creation of the connection, and a use does not move it. Each check is an empty query with a read timeout of 5 s.
+  - At the defaults, no timer of pgjdbc bounds a statement or the startup: `socketTimeout` is 0. The connect timeout of 10 s bounds only the TCP connect and the SSLRequest of sslmode `prefer`.
+  - An I/O error of a statement is 08006, and HikariCP closes the connection at once. The lifetime of a connection is 22.5 to 30 min. At the defaults the pool has a fixed size of 10, thus its idle timer has no effect.
+  - The login timeout that HikariCP gives the JVM does not apply, because pgjdbc reads its own `loginTimeout`, which is 0.
+  - No prediction of the snapshot moves.
+
+### 0.3.1
+
+- **PostgreSQL.** Two documents give the first systems of the PG catalog, each from its source at its tag or its npm version:
+  - `node-postgres`: pg 8.23.1 with pg-pool 3.14.0. At the defaults, no timer bounds the connect, a checkout from a full pool or a query. The pool removes an idle client after 10 s, and it emits `error` when an idle client fails. No socket of pg has keepalive, and neither package sends a query again.
+  - `postgres-session`: a backend of PostgreSQL 17.11 (`REL_17_11`, the image `postgres:17.11`). It turns on SO_KEEPALIVE, and at its defaults the keepalive sysctls of the namespace apply. Each timeout is off at 0. A send to a lost client waits with no timeout, thus the kernel or SIGTERM ends it.
+
+### 0.3.0
+
+- **`linux-tcp`: the delayed ACK.** The timer `delayed_ack` arms on each segment of data (`rx.data`), and each segment that goes out stops it. It waits from `TCP_DELACK_MIN` (HZ/25) up to the smoothed round trip, and `TCP_DELACK_MAX` (HZ/5) at most. The models are `linux.delack` and `linux.delack-lateness` of the algebra 0.7.1.
+  - The document realizes the ack delay (`systems.mechanism.ack-delay`): from at once to that wait. The kernel acknowledges at once in quick-ACK mode. Thus a client that sends one request acknowledges its reply at once, and a client of many requests waits.
+  - The sources are `include/net/tcp.h`, `net/ipv4/tcp_output.c`, `net/ipv4/tcp_input.c` and `net/ipv4/tcp.c` of Linux 6.6, and RFC 1122 §4.2.3.2.
+  - One prediction of the snapshot moves. The WST cell `router silent-drop` loses its bound on the round trip, 405 ms. The cap of 200 ms keeps the forget of the router before the first ping at each round trip.
+
+### 0.2.0
+
+- **The MongoDB documents realize the mechanisms of a reader.** In `mongod-replication`, the heartbeat window is the heartbeat detection time, and the liveness check is the step-down window. In `mongodb-node`, the selection timeout is the client retry window.
+- **`redis-client`.** A blocking command holds its client in the state `BLOCKED`. The timer `blocked` gives its reply at its timeout, up to one serverCron tick and 1 ms late. The idle timer arms on the entry to `CONNECTED` and on each read, and it closes the client up to 1 s and one tick late. In 0.1.0 it armed on `accept` only, thus it did not fire at any time.
+  - The knob `redis_hz` gives the tick. The sources are `src/timeout.c`, `src/blocked.c`, `src/ae.c` and `src/server.c` of Redis 8.10.2.
+- **`off`.** Eight knobs give the value that turns their timers off, each 0. They are `tcp_user_timeout`, Redis's `timeout` and `blocking_timeout`, and two timeouts of Node's server. The MongoDB driver adds `connectTimeoutMS`, `socketTimeoutMS` and `waitQueueTimeoutMS`. Each catalog prediction stays the same.
+
+## Installation
+
+```sh
+pnpm add @mark1russell7/machines @mark1russell7/algebra zod
+```
+
+The package uses `@mark1russell7/algebra` for the type `Machine` and the schema `machineSchema`. The algebra does not use this package. Both packages use `zod` as a peer dependency.
+
+## Tests
+
+`pnpm --filter @mark1russell7/machines test` starts the tests. They examine each document with the schema and the consistency checks of the algebra. They also compute the algebra on the real documents: the defaults of Linux 6.6, the backoff waits, recovery after a stall, and detection.
+
+`pnpm --filter @mark1russell7/machines build` writes the package for npm into `build/`.

package/build/index.d.ts

@@ -0,0 +1,341 @@
+import { Expr, Machine } from "@mark1russell7/algebra";
+//#region src/http/go-transport.d.ts
+/**
+ * This document is one connection of the `http.Transport` of Go 1.27.2 at its defaults, over its
+ * Linux TCP socket. Each fact comes from the source at the tag `go1.27.2`. The comments give the
+ * file and the line.
+ *
+ * The idle timeout is the C of the keep-alive race. The transport ignores the `Keep-Alive` hint of
+ * the server. It finds a connection that the server closed when its read loop reads the end of
+ * file. A reused connection can fail before any byte of the reply. Then the transport sends a
+ * request that it can replay again, on a new connection, by itself.
+ */
+export declare const GO_TRANSPORT: Machine;
+//#endregion
+//#region src/http/node-agent.d.ts
+/**
+ * This document is one socket of the `http.Agent` of Node v24.21.0, as its global agent sets it.
+ * Its keep-alive is on, its free socket timeout is 5 s, and it is LIFO. It is over the Linux TCP socket. Each fact
+ * comes from the source at the tag `v24.21.0`, with the file and the line.
+ *
+ * A free socket keeps its connection until the smaller of the timeout of the agent and the hint of
+ * the server less a buffer. An agent without a timeout keeps it with no limit, and then the hint
+ * changes nothing.
+ *
+ * The free socket timer arms on the event loop of the program, when the program has read the
+ * whole response. The time from the last segment that the kernel received to that arm is the time
+ * of the program. No source bounds it, and this document does not hold it. The race of the cells
+ * adds it from a calibration (`HANDLING` in `packages/cells/src/http/race.ts`).
+ */
+export declare const NODE_HTTP_AGENT: Machine;
+//#endregion
+//#region src/http/node-server.d.ts
+/**
+ * This document is one connection as the `http.Server` of Node v24.21.0 holds it, over the Linux
+ * TCP socket of the connection. Each fact comes from the source at the tag `v24.21.0`. The comments
+ * give the file and the line.
+ *
+ * The keep-alive timer is the S of the keep-alive race. It arms when the response ends, not when
+ * the request starts. It is a socket timeout on the timers of libuv, thus it has the lateness of a
+ * Node timer (`timers.ts`). When it fires, the server closes the socket. The kernel sends a FIN, or
+ * a reset when the receive queue has data that nothing read.
+ */
+export declare const NODE_HTTP_SERVER: Machine;
+//#endregion
+//#region src/http/undici.d.ts
+/**
+ * This document is the socket of an HTTP/1.1 `Client` of undici 8.12.2, over its Linux TCP socket.
+ * Each fact comes from the published package at 8.12.2, with the file and the line.
+ *
+ * The keep-alive timeout comes from the hint of the server less a threshold, capped by a maximum.
+ * The headers and body timeouts use the fast timers of undici, which count in ticks of 499 ms. The
+ * client sends no request again by itself. A request that it did not write yet goes on the next
+ * connection.
+ *
+ * The keep-alive timer arms on the event loop of the program, in the check phase after the parse
+ * of the reply. The time from the last segment that the kernel received to that arm is the time of
+ * the program. No source bounds it, and this document does not hold it. The race of the cells adds
+ * it from a calibration (`HANDLING` in `packages/cells/src/http/race.ts`).
+ */
+export declare const UNDICI_CLIENT: Machine;
+//#endregion
+//#region src/ioredis-sentinel.d.ts
+/**
+ * This document is the Sentinel path of ioredis 6.0.0. It tells how ioredis finds the primary of a
+ * group through the Sentinels, loses it, and connects to the new one. The standalone states of
+ * `ioredis-status` stay, and a connect asks a Sentinel first. The driver has no timer that watches
+ * the group: it moves only when its own connection closes. The failover detector, which
+ * subscribes to `+switch-master`, is off by default.
+ */
+export declare const IOREDIS_SENTINEL: Machine;
+//#endregion
+//#region src/json.d.ts
+/** This document is TCP as Linux 6.6 implements it: one full socket, from the source of the kernel and the RFCs. */
+export declare const LINUX_TCP: Machine;
+/** This document is the TCP state machine of conntrack on Linux 6.6.87.2: the state of a router or a NAT for one flow. */
+export declare const NF_CONNTRACK_TCP: Machine;
+/** This document is one client connection as the Redis 8.10.2 server holds it, over its Linux TCP socket. */
+export declare const REDIS_CLIENT: Machine;
+/** This document is the status of one standalone connection of ioredis 6.0.0, over its Linux TCP socket. */
+export declare const IOREDIS_STATUS: Machine;
+/**
+ * This map gives, for each manifestation of a failure, the incoming events that continue to arrive
+ * at Linux TCP while the failure lasts. A black hole lets nothing through. The kernel of a frozen
+ * process continues to send ACKs, thus `rx.ack` arrives.
+ */
+export declare const MANIFESTATIONS: Readonly<Record<string, readonly string[]>>;
+//#endregion
+//#region src/mongo/mongod-replication.d.ts
+/**
+ * This document is the replication of mongod 9.0.4. It gives one member of a replica set, its view
+ * of the primary, and the election that it can hold. The states are the states of the member. The
+ * timers are the heartbeats, the election timeout, the liveness check of a primary, the vote, the
+ * catch-up of a new primary and a step-down.
+ *
+ * Each member sends a heartbeat to each other member. A heartbeat window is 10 s: in it, a failed
+ * request goes again at once, two times at most. A window without a response marks the target
+ * DOWN. A secondary starts an election when it hears nothing from the primary for the election
+ * timeout and a random offset. A primary steps down when it cannot see a majority for the election
+ * timeout.
+ *
+ * A secondary keeps a silent primary as its sync source until its oplog fetcher gives up. That is
+ * two timeouts and a restart: 17 s to 18 s at the defaults. Its reporter keeps a
+ * replSetUpdatePosition in flight to that primary for 30 s. Until then, a new primary learns the
+ * position of that secondary only from the response to each heartbeat.
+ */
+export declare const MONGOD_REPL: Machine;
+//#endregion
+//#region src/mongo/mongod-session.d.ts
+/**
+ * This document is the hold of mongod 9.0.4 on one client connection, over its socket. `mongod`
+ * turns keepalive on for each TCP session. It lowers two keepalive options of the socket to a
+ * maximum: the idle time to 300 s and the interval to 1 s. It does not change the probe count.
+ * Thus the namespace sysctls give the idle time and the interval only when they are lower, and
+ * they always give the count.
+ *
+ * `mongod` writes no warning about keepalive. A failure to read or to set an option goes to the
+ * log at debug level 3 in a release build.
+ *
+ * An awaitable hello of an exhaust stream waits for a change of the topology or `maxAwaitTimeMS`.
+ * Then `mongod` sends the reply, and it starts the next hello of the stream at once.
+ */
+export declare const MONGOD_SESSION: Machine;
+//#endregion
+//#region src/mongo/mongodb-node.d.ts
+/**
+ * This document is the MongoDB Node driver 7.7.0, for one server of a replica set. It gives one
+ * connection of the driver by its role, and the timers that act on it. The roles are the monitor
+ * of the server, the pool connection that an operation uses, and the wait of an operation for a
+ * suitable server. The monitor streams `hello`: the server answers when its topology changes, or
+ * after `heartbeatFrequencyMS`. The monitor writes the server off when its socket is silent for
+ * `connectTimeoutMS + heartbeatFrequencyMS`.
+ *
+ * A knob of the driver at 0 has no timer: give it as no bound (`infinite`). This is true of
+ * `connectTimeoutMS`, `socketTimeoutMS`, `waitQueueTimeoutMS`, `maxIdleTimeMS` and
+ * `serverSelectionTimeoutMS`.
+ */
+export declare const MONGODB_NODE: Machine;
+//#endregion
+//#region src/pg/hikaricp-pgjdbc.d.ts
+/**
+ * This document is HikariCP 7.1.0 over pgjdbc 42.7.13, for one connection of a pool. It gives the
+ * states of the connection, from its creation to its close, and the timers that act on it. The
+ * pool makes its connections one at a time, on one thread. At the defaults the pool has a fixed
+ * size of 10, thus its idle timer has no effect.
+ *
+ * HikariCP reads no idle socket. It finds a dead connection only by a check. A borrow checks a
+ * connection that was idle for more than 500 ms. The keepalive checks an idle connection each 96 to
+ * 120 s from its creation. Each check is `isValid`: pgjdbc sends one Query message with an empty
+ * string, with a read timeout of `validationTimeout`. A read timeout or an I/O error closes the
+ * socket.
+ *
+ * pgjdbc sends nothing on an idle connection. Its only read timeout is `socketTimeout`, which is
+ * off at the defaults, thus no timer of pgjdbc bounds a statement or the startup. Its connect
+ * timeout of 10 s bounds only the TCP connect and the SSLRequest. At sslmode `prefer` (the
+ * default), a read timeout in the connect starts one more connect with SSL off, in what remains of
+ * the 10 s.
+ *
+ * The JDK waits for a read or a connect with a timeout in poll(). Linux ends that wait up to 0.1 % of
+ * its time late, at most 100 ms: 11 ms for a read timeout of 11 s (run 39109649303).
+ *
+ * HikariCP closes a connection at once when a statement fails with an SQLState of the class 08. It
+ * also closes it for 57P01, 57P02, 57P03 and 0A000. pgjdbc gives 08006 for each I/O error of a
+ * statement. Thus a reset, an end of the stream or a give-up of the kernel each close the
+ * connection. HikariCP does not send a statement again.
+ */
+export declare const HIKARICP_PGJDBC: Machine;
+//#endregion
+//#region src/pg/node-postgres.d.ts
+/**
+ * This document is node-postgres 8.23.1 (the npm package pg) with pg-pool 3.14.0, for one client
+ * of a `pg.Pool`. It gives the states of the client, from its connect to its end, and the timers
+ * that act on it. The pool hands out an idle client with no test of its connection. At the
+ * defaults, the client turns no keepalive on and sends nothing on an idle connection. Neither
+ * package sends a query again, and neither package connects again by itself.
+ *
+ * A knob of pg at 0 or false has no timer: give it as no bound (`infinite`). This is true of
+ * `connectionTimeoutMillis`, `query_timeout`, `maxLifetimeSeconds` and `idleTimeoutMillis`. At the
+ * defaults of a pool, only the idle timer of the pool runs, for 10000 ms. Thus no timer of pg
+ * bounds the connect, the startup, a checkout from a full pool or a query.
+ *
+ * Three timeouts are not timers of the client: `statement_timeout`, `lock_timeout` and
+ * `idle_in_transaction_session_timeout`. The client sends each one to the server in the startup
+ * message, and only when it is set.
+ *
+ * The pool emits `error` when an idle client fails. A client that the application holds emits
+ * `error` itself, and the pool does not listen to it. In Node, an `error` event with no listener
+ * throws.
+ */
+export declare const NODE_POSTGRES: Machine;
+//#endregion
+//#region src/pg/pgbouncer.d.ts
+/**
+ * This document is PgBouncer 1.26.1 in transaction pooling, for one client connection. It gives the
+ * states of the client, from its accept to its close, and the timers that act on it.
+ *
+ * In transaction pooling, a client holds a server connection only for a transaction. Between two
+ * transactions the client is idle, and PgBouncer reads its socket: the end of the stream or a reset
+ * closes it at once. A query that finds no idle server waits in a queue, and PgBouncer does not read
+ * the socket of a waiting client. It finds a client that left the queue only when it serves it.
+ *
+ * Each timer of a client is a check of the janitor, which runs each 333.3 ms. A timer thus fires up
+ * to one period after its limit, and a busy loop of events delays it more. At the defaults only two
+ * timers act on a client: client_login_timeout (60 s) and query_wait_timeout (120 s). A timer that
+ * fires, and the failure of the linked server, close the client with a FATAL error of SQLSTATE 08P01.
+ */
+export declare const PGBOUNCER_CLIENT: Machine;
+//#endregion
+//#region src/pg/pgbouncer-server.d.ts
+/**
+ * This document is PgBouncer 1.26.1 in transaction pooling, for one server connection of a pool:
+ * from its launch to its close. It also gives the wait of the pool before its next connection after
+ * a failed login.
+ *
+ * PgBouncer reads the socket of each idle server, thus the end of the stream or a reset of an idle
+ * server closes it at once. A black hole stops nothing that PgBouncer reads. Only a check of the
+ * server, a timer of the kernel, server_idle_timeout or server_lifetime removes such a server. The
+ * check is the empty query before a reuse, when the server was idle for longer than
+ * server_check_delay (30 s). It acts at the defaults, and no timer bounds its reply. Thus behind a
+ * black hole, the client that waits for the check stays in the queue until its query_wait_timeout.
+ *
+ * The TCP connect has a timer of libevent of server_connect_timeout, in whole seconds. The janitor
+ * also bounds the whole login by server_connect_timeout, from the launch. After a failed login the
+ * pool starts no connection for server_login_retry from the launch of the failed one. In that time
+ * each client that needs a server fails at once, and a waiting client stays in the queue.
+ */
+export declare const PGBOUNCER_SERVER: Machine;
+//#endregion
+//#region src/pg/postgres-session.d.ts
+/**
+ * This document is the hold of a PostgreSQL 17.11 backend on one client connection, over its TCP
+ * socket on Linux. The backend turns on SO_KEEPALIVE for each TCP socket. At the defaults of its
+ * four TCP GUCs, it changes no keepalive option and no user timeout. Thus the namespace sysctls
+ * give the idle time, the interval and the count. A GUC above 0 sets its socket option.
+ *
+ * Each timer of a backend is a SIGALRM timeout. At startup, the handler ends the process at once.
+ * After the startup packet, each handler sets a flag and the latch, directly or by a signal. The
+ * backend then acts at its next CHECK_FOR_INTERRUPTS. An idle timer and the transaction timer end
+ * the session with FATAL. The statement timer and the lock timer end the statement with ERROR.
+ *
+ * A send to a slow or a lost client waits for the socket with no timeout. In that wait the
+ * backend acts on SIGTERM and on the death of the postmaster only. A timer that fires there takes
+ * effect after the send. Thus PostgreSQL gives no bound to a send: the kernel ends it, or SIGTERM
+ * does.
+ *
+ * A timeout knob at 0 has no timer: give it as no bound (`infinite`). This is true of
+ * `statement_timeout`, `lock_timeout`, `transaction_timeout`, `idle_in_transaction_session_timeout`,
+ * `idle_session_timeout` and `client_connection_check_interval`.
+ */
+export declare const POSTGRES_SESSION: Machine;
+//#endregion
+//#region src/procedures-ws.d.ts
+/**
+ * This document is the connection of the WebSocket client of `@procedures/client` 0.3.0
+ * (`WebSocketTransport`), over its socket class and its Linux TCP socket.
+ *
+ * - The heartbeat is `heartbeat()` of `@mark1russell7/service` 0.4.0. A tick each interval sends a
+ *   ping only when no pong is awaited. The timeout of the ping starts before its send. A
+ *   ping without a pong at its timeout is a miss, and `misses` misses in sequence drop the
+ *   connection. With a timeout below the interval, each tick after a miss sends the next ping.
+ *   Thus the drop comes (misses − 1) intervals and one timeout after the first ping without an answer.
+ * - A drop ends the socket with `terminate()` when its class has it: the `ws` package. The global
+ *   `WebSocket` of Node has only `close()`, which writes a close frame and destroys nothing.
+ * - Each end of a socket starts the reconnect. The wait of try n is the backoff
+ *   min(initialDelay × multiplier^(n − 1), maxDelay), less a random part: jitter × backoff × r.
+ * - The handshake has a time limit (`connectionTimeout`), and a failed handshake drops at once.
+ * - The heartbeat refreshes an idle flow. Each tick writes a ping, whatever data the connection
+ *   carries, and the pong comes back. Thus the ping timer realizes the idle refresh of O03.
+ */
+export declare const PROCEDURES_WS_CLIENT: Machine;
+/**
+ * This document is one connection as the WebSocket server of `@procedures/client` 0.3.0 holds it
+ * (`WebSocketServerTransport` on the `ws` package), over its Linux TCP socket.
+ *
+ * The heartbeat of the server (roadmap R3) is a `setInterval`. Each beat pings each connection,
+ * and the server ends a connection after `misses` beats without a pong (`terminate()`). Thus the
+ * drop comes `misses` beats after the first ping without an answer, and the lateness of each beat
+ * adds. Its `http.Server` sets no SO_KEEPALIVE when `keepAlive` is off, the default of Node.
+ */
+export declare const PROCEDURES_WS_SERVER: Machine;
+//#endregion
+//#region src/sentinel.d.ts
+/**
+ * This document is the Sentinel of Valkey 9.1.2. It gives the view of one Sentinel on the primary
+ * of a group that it monitors, and the failover that it can lead. The states are the down states
+ * and the states of the failover. The timers are the periods and the timeouts of the Sentinel.
+ * Each timer of a period checks at the next tick of the Sentinel, thus its lateness is one tick.
+ */
+export declare const SENTINEL: Machine;
+//#endregion
+//#region src/http/timers.d.ts
+/**
+ * This function gives the lateness of a Node timer of `ms` milliseconds. The lateness is the slack
+ * of its sleep, 1 ms for the truncation of the loop clock, and the step of the coarse clock. The
+ * arithmetic reads `ms` in milliseconds, and the knob `hz` in Hz.
+ */
+export declare const nodeTimerLateness: (ms: string) => Expr;
+/**
+ * This expression is how early a Node timer can fire. It is 1 ms for the truncation of the loop
+ * clock that stamps its start, and the step of the coarse clock.
+ */
+export declare const NODE_TIMER_EARLY: Expr;
+/** This function gives the lateness of a Go timer of `s` seconds: the slack of its sleep and 1 ms. The arithmetic reads `s` in seconds. */
+export declare const goTimerLateness: (s: string) => Expr;
+/** This function gives the lateness of a Node timer of `seconds` at a HZ, in seconds: the number form of `nodeTimerLateness`. */
+export declare const nodeLateSeconds: (seconds: number, hz: number) => number;
+/** This function gives how early a Node timer can fire at a HZ, in seconds: the number form of `NODE_TIMER_EARLY`. */
+export declare const nodeEarlySeconds: (hz: number) => number;
+/** This function gives the lateness of a Go timer of `seconds`, in seconds: the number form of `goTimerLateness`. */
+export declare const goLateSeconds: (seconds: number) => number;
+/**
+ * This count is the tick of the fast timers of undici 8.12.2, in milliseconds:
+ * `(RESOLUTION_MS >> 1) - 1` with `RESOLUTION_MS` 1000 (`lib/util/timers.js:30-40`).
+ */
+export declare const UNDICI_TICK_MS = 499;
+/**
+ * This function gives how early a fast timer of undici can fire, for a duration of `ms`
+ * milliseconds. Each tick adds the tick to the clock of the fast timers, whatever time passed
+ * (`lib/util/timers.js:115-123`).
+ *
+ * A new timer takes the clock of the next tick less one tick as its
+ * start (`lib/util/timers.js:151-155`). It fires at the first tick where the clock is its start
+ * plus its duration or more (`lib/util/timers.js:156-162`). Thus it fires after
+ * `ceil(ms / 499) - 1` ticks and part of one more tick. Each tick is a Node timer. The loop clock
+ * of each tick has the same lag, thus the early bound of a Node timer comes in one time.
+ */
+export declare const undiciFastEarly: (ms: string) => Expr;
+/**
+ * This function gives how late a fast timer of undici can fire, for a duration of `ms`
+ * milliseconds. It fires after at most `ceil(ms / 499)` whole ticks. Each tick is a Node timer
+ * of 499 ms (`lib/util/timers.js:190-207`), with the lateness of a Node timer.
+ */
+export declare const undiciFastLateness: (ms: string) => Expr;
+//#endregion
+//#region src/index.d.ts
+/**
+ * This map holds each document of the package by its identifier, for example `linux-tcp`. A
+ * document on another machine names that machine in `over.machine` as `systems.machine.<id>`.
+ */
+export declare const MACHINES: Readonly<Record<string, Machine>>;
+//#endregion
+//# sourceMappingURL=index.d.ts.map