@mark1russell7/kind 0.0.0-stage → 0.1.1

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,143 @@
-# Temporary Holding Version
+# @mark1russell7/kind
 
-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.
+Kubernetes in Docker (kind) as a lab for connection timers. A scenario gives the cluster, and the lab puts the faults of the harness in the namespaces of its pods. Each observation is on the one monotonic clock of the VM, and the ordering law gives the predictions. The package also reads the raw record of a cell and judges it again, without Docker.
+
+```sh
+npm install @mark1russell7/kind zod
+```
+
+## The two entries
+
+| Entry | What it holds | What it loads |
+| --- | --- | --- |
+| `@mark1russell7/kind` | Each part: the cluster, the lab, the image, the faults, the predictions, the runner, and all of `./judge` | Testcontainers, Docker, `kind` and `kubectl` when a lab opens |
+| `@mark1russell7/kind/judge` | The types and the zod schemas of a record, `upgrade`, `judge`, the verdict, the readers of the lines and the report | `@mark1russell7/quantity` and zod only |
+
+The entry `./judge` loads no Docker, no Testcontainers, no child process and no `node:` module. Thus a program that only reads records can use it, in a browser too. Two tests hold it to that. One follows the imports of its source, and one imports it in a new Node process. The smoke test of a release does the same on the built tarball.
+
+```ts
+import { judge, readRecord } from "@mark1russell7/kind/judge";
+
+const record = readRecord(JSON.parse(text)); // a record of /1 or /2, as /2
+const verdict = judge(record); // the verdict of this version, from the cell and the runs
+```
+
+- `readRecord(data)` examines a record of either format with its zod schema, and gives it in the format `/2`.
+- `upgrade(record)` gives a record of `/1` in the format `/2`. It does not examine the record, and it changes nothing in it.
+- `judge(record)` judges a record of either format again, from its cell and its runs. For each of the 31 records of the kind workflow of 2026-10-16, it gives the verdict of the record.
+- `kindCellRecordSchema` and `kindCellRecordV1Schema` are the zod schemas of the two formats.
+- `judgeKind`, `checkRun`, `factsOf` and `unitOf` are the verdict. `cellsTable`, `predictionText`, `medianText`, `calibrationOf` and `timeSpread` are the report.
+
+The judge does not load the harness, because the harness loads its Docker lab. It has its own copy of the median interval, the quantile and δ_rel of the harness, and a test holds the copy to the harness.
+
+## The record formats
+
+The lab writes the raw record of each cell as JSON: `{ format, cell, runs, manifests, loads, verdict, at }`. A cell is all that the measurement needs, as data. A run keeps each line that its sources wrote, thus a holder of the record can judge it again.
+
+- **`systems.kind-cell-record/2`** is the format that the lab writes. Each amount in it is a quantity, `{ "value": 34.244, "unit": "s" }`, from `@mark1russell7/quantity`.
+- **`systems.kind-cell-record/1`** is the first format. Its bands, its medians and the times of its facts are numbers. The lab does not write it again, and a reader reads it through `upgrade`.
+
+These are the changes from `/1` to `/2`. Each value stays the same. Only its form changes.
+
+| Field | `/1` | `/2` |
+| --- | --- | --- |
+| `cell.prediction` bands (`band`, `start.band`, `end.band`) | `{ "lo": 28, "hi": 49 }`, in seconds | `{ "lo": { "value": 28, "unit": "s" }, "hi": { "value": 49, "unit": "s" } }` |
+| `cell.trigger.cpuMax` | `{ "quota": 1000, "period": 1000000 }`, in microseconds | Each part a quantity in `us` |
+| `verdict.median` and `verdict.checks[].value` | A number: seconds or a count, by the prediction | A quantity in the unit of the prediction (`unitOf`) |
+| The times of `verdict.checks[].facts` | Numbers of seconds | Quantities in `s` |
+
+The unit of the main value of a run comes from the prediction of its cell:
+
+- `s` for a time: `removal`, `leaves`, `stalls`, and `restarts` with a band.
+- `{request}` for the failed requests: `none`, `window`, `stays` and `measured`.
+- `{replica}` for the replicas that received SIGTERM: `restarts` without a band.
+
+These values stay numbers in the two formats:
+
+- **A stamp** is a reading of CLOCK_MONOTONIC in milliseconds, a point on a clock, not an amount. The stamps are `start`, `end` and `acts` of a run, `t` of each line, and `first`, `last` and `deletion` of the facts.
+- **A line** stays as its source wrote it. The image writes it, and the record keeps it.
+- **A count** or **a share**: the replicas, the thresholds, the runs and the counts of a verdict. The jitter of a poll and the idle share of a load sample are shares.
+
+The tests read three real records of `/1` (`test/records/`): a cell that holds, a cell that fails and a calibration. Each fixture is a whole record, without its load samples and without the kernel release of the runner. `KIND_RECORDS=<folder> pnpm test` judges each record under a folder again, and holds each verdict to the verdict of its record.
+
+## The cluster
+
+- **The scenario** (`scenario.ts`) is the cluster as data: its nodes, its version, the mode and the sync periods of kube-proxy, its CNI and its subnets. `kindConfig(scenario)` generates the configuration of kind from it.
+- **The node image** is `kindest/node:v1.37.0`, pinned by digest, the default of kind v0.33.0. The research names v1.37.1 for some defaults. The patch release is the mismatch.
+- **The tools** (`tools.ts`) are kind v0.33.0 and kubectl v1.37.0. The lab downloads each one into `.cache/` in this package, and it compares the sha256 with the pinned value at each use. `KIND_CACHE` names another folder. The lab installs nothing on the system, and the same code works on Linux, macOS and Windows.
+- **The isolation.** Each cluster gets its own Docker network, its own kubeconfig and its own cache for kubectl, in its run folder. The lab refuses a pod or service subnet that overlaps a Docker network.
+
+## The lab
+
+`openKindLab(cluster, image)` (`lab.ts`) starts the instruments of a cluster:
+
+- **The agent of each node** is a privileged container in the PID namespace of the node container. It signals a process of a pod by its PID on the node. It writes `cpu.max` in the cgroup of a container, and a flag file in the root of a container.
+- **The rules of each node.** The agent reads the rules of kube-proxy in the namespaces of the node each 50 ms: `iptables-save`, `nft list table ip kube-proxy`, or `/proc/net/ip_vs`. It writes a line when the backends of the Service change (`backends.ts`). A backend of IPVS with the weight zero takes no new connection, thus it is not a backend.
+- **The injector of each node** is the image of the harness, in the PID namespace of the node. `crictl` on the node gives the PID of a container, and `nsenter -n` enters the network namespace of its pod. The injector of the harness then applies its rules there.
+- **The watcher** is a container on the network of the cluster. It watches the pods, the EndpointSlices and the events through the API, and it follows the log of each pod of the cell.
+- **The prober** of the harness watches the network namespace of each pod, by its inode. The lab keeps its resets, errors and retransmissions, and it counts the other records.
+
+Each pod of a cluster shares the kernel of the Docker VM. Thus each stamp of the agent, the injector, the watcher, the clients, the service and the prober is on the same CLOCK_MONOTONIC.
+
+## The image
+
+The lab image (`image/`) holds the service of a cell on `@mark1russell7/service`, its clients, the agent and the watcher, on Node 24.21.0. Its base is pinned by digest, and `npm-lock.json` pins the packages from npm. `stageLabImage()` stages its context, and `labImage()` tags the image by its content.
+
+- **In the workspace** of this repository, the stage builds `@mark1russell7/quantity`, `@mark1russell7/algebra` and `@mark1russell7/service`, and packs each one as npm gets it.
+- **From npm**, the stage packs the installed versions of the same packages. The package holds the files of the image, and `src/compose.ts` and `src/backends.ts`, for that.
+- **The service** (`app.mjs`) is a Node HTTP server. Its one controller needs Redis when the cell has Redis. Its health server gives the probes, and it declares each stage of the shutdown. `compose.ts` composes the service from the declaration of the cell, and `lint()` reads the same composition.
+- **The seams** of the service are a flag file that fails its liveness check, and SIGUSR2. SIGUSR2 blocks its event loop for the time in a file.
+- **The clients** (`client.mjs`) send requests on new connections to the ClusterIP. Each request gives one line with its outcome: ok, 503, refused, reset, timeout or unreachable.
+
+## The triggers
+
+`planOf(cell)` (`faults.ts`) maps each trigger to the acts of the lab:
+
+| Trigger | Acts |
+| --- | --- |
+| `pod-deletion` | `kubectl delete pod` of the first replica |
+| `rolling-update` | a new value of an environment variable of the Deployment |
+| `node-drain` | `kubectl drain` of the node of the first replica, then `uncordon` |
+| `scale-in` | one replica less, then back |
+| `crash` | SIGKILL of the process of the service, from the node |
+| `liveness-restart` | the flag file that fails the liveness check of the first replica |
+| `freeze-process` | SIGSTOP and SIGCONT: of kube-proxy on one node across a deletion (T07), or of Redis (T18) |
+| `rst`, `blackhole` | the injector of the harness in the namespace of Redis, with each replica as a peer |
+| `peer-gone-without-close` | a black hole on Redis, then no Redis pod: its namespace goes away with its rules |
+| `app-stall` | the event loop of the first replica blocked |
+| `rollout` | no Redis pod, then a rolling update |
+| `cpu-throttle` | `cpu.max` in the cgroup of the container of the first replica |
+
+A cgroup path that is not the scope of one container is refused. A write to the root of the node throttles or freezes each pod of the node.
+
+The plan's `event:clock-jump` has no trigger. A step of CLOCK_REALTIME in the VM steps the clock of each container: the kubelet, the API server and the cells of other agents. A time namespace offsets only the monotonic clocks, and the runtime of the service reads only the monotonic clock.
+
+## The predictions
+
+`predict.ts` gives each band from the declaration, the pod settings and the calibration of the propagation:
+
+- **A deletion.** The listener of a leaving pod stays open for its preStop sleep and the hold of `fail readiness`. A connection fails when the rules of its node select the pod after that. `rules.ts` gives O04 with the hold as data, and `lint()` decides it.
+- **A pause of kube-proxy** keeps the rules of one node for its hold. The window on that node ends one propagation after the pause.
+- **A fault of a shared dependency** trips the readiness latch of each replica (`failSpan`). Then the kubelet needs its threshold of probes, and the rules need one propagation.
+- **A restart through a coupling** adds the liveness probes of the kubelet and the preStop sleep to the latch.
+
+`verdict.ts` judges each run, and each cell on its counted runs. Each time lands in its band ± 100 ms: the poll of the rules and the delay of the watcher. A median in a band gets the test of the harness: its order-statistic interval in the band, made 5 % wider.
+
+## Tests
+
+`pnpm --filter @mark1russell7/kind test` starts the tests of the configuration, the tools, the parser of the rules and the fault mapping. It also starts the tests of the predictions, the verdict and the judge of the real records. They do not need Docker.
+
+The catalogs are in `@systems/cells` (`t07.ts`, `t18.ts`). `KIND_LAB=1` starts them in kind.
+
+## CI
+
+The cells operate on the runners of GitHub, and not on a machine that does other work (`.github/workflows/kind.yml`). Each shard gets a runner, and each job makes its own clusters and deletes them.
+
+- **The modes of the kernel.** kube-proxy in a node container uses the modules of the host kernel. Thus the job loads `ip_vs` and `nf_tables` first. A cell of a mode that the kernel cannot do waits, and `summary.ndjson` tells why.
+- **The shards.** `shardOf` gives each shard an equal share of the estimated time, and the cells of one mode stay together. Thus a shard makes few clusters.
+- **The output.** Each job uploads its raw records, `summary.ndjson`, and what the runner is. The run folder of each cluster stays out of the output, because a kubeconfig holds credentials.
+- **A pull request** that changes the workflow starts a smoke run: the calibration of each mode, with 2 runs on one cluster.
+
+## Releases
+
+CI publishes each new version of this package (`.github/workflows/release.yml`). npm trusts the workflow only for a package that exists. Thus the first version of a new package goes out by hand, and then the workflow becomes its trusted publisher. For a package that npm does not have, the workflow gives a warning and publishes nothing.

package/build/index.d.ts

@@ -0,0 +1,393 @@
+import { $ as SliceLine, $t as goDuration, A as TriggerV1, At as showBand, B as RunFacts, Bt as Replica, C as KindCellResult, Ct as LOG_LABEL, D as PredictionV1, Dt as bandOf, E as LoadSample, Et as SERVER, F as KindDecision, Ft as KubeletProbe, G as referenceOf, Gt as KUBE_PROXY_MODES, H as factsOf, Ht as Trigger, I as KindVerdict, It as PodSettings, J as Line, Jt as KubeProxyMode, K as unitOf, Kt as KindConfig, L as LAST_SLACK, Lt as Prediction, M as upgrade, Mt as Declaration, N as upgradeCell, Nt as KindCell, O as RunCheckV1, Ot as seconds, P as KIND_NOISE, Pt as KindRun, Q as RulesLine, Qt as cidrRange, R as Propagated, Rt as RedisDeclaration, S as KindCellRecordV1, St as HEALTH_PORT, T as KindVerdictV1, Tt as REDIS, U as judgeKind, Ut as TriggerKind, V as checkRun, Vt as Template, W as propagationOf, Wt as Workload, X as RecordLine, Xt as NodeImage, Y as PodLine, Yt as NODE_IMAGES, Z as Request, Zt as cidrOverlap, _ as ClusterManifest, _t as sliceDropOf, a as STAGES, at as failuresOf, b as FORMAT_V1, bt as transitionOf, c as readRecord, ct as outcomesOf, d as calibrationOf, dt as recordsOf, en as kindConfig, et as backendsAt, f as cellsTable, ft as requestsOf, g as BandV1, gt as signalsOf, h as timeSpread, ht as signalOf, i as quantileOf, in as scenarioProblems, it as emptyOf, j as judge, jt as Band, k as RunFactsV1, kt as secondsOf, l as Judged, lt as podsAt, m as predictionText, mt as rulesOf, n as medianInterval, nn as nodeNames, nt as deletionOf, o as kindCellRecordSchema, ot as intakeOf, p as medianText, pt as restartsAt, q as Endpoint, qt as KindScenario, r as middle, rn as scenario, rt as dropOf, s as kindCellRecordV1Schema, st as kernelCounts, t as RELATIVE, tn as kubeProxyPatch, tt as byNode, u as TimeSpread, ut as podsOf, v as EnvironmentManifest, vt as sliceEmptyOf, w as KindCellV1, wt as PORT, x as KindCellRecord, xt as CLIENT, y as FORMAT, yt as slicesOf, z as RunCheck, zt as Reference } from "./judge-CDDCr1Z8.js";
+import { Quantity } from "@mark1russell7/quantity";
+import { CheckFn, Finding, HealthServer, Poll, Rule, Scenario, ServiceBuilder, ServiceDescription, Stage, Timing, TransportImpl, Verdict } from "@mark1russell7/service";
+import { RedisClient } from "@mark1russell7/service/redis";
+//#region src/backends.d.ts
+/** A service rule names the Service whose backends the agent reads: its namespace, its name, and its ClusterIP and port for IPVS. */
+interface ServiceRule {
+  readonly mode: "iptables" | "ipvs" | "nftables";
+  readonly ns: string;
+  readonly svc: string;
+  readonly ip: string;
+  readonly port: number;
+}
+/**
+ * This function gives the backends of a Service in a dump of the rules of kube-proxy, as
+ * `ip:port`, sorted. A backend of IPVS with the weight zero takes no new connection, thus it is
+ * not a backend.
+ * - iptables: the `KUBE-SVC` chain of the Service jumps to a `KUBE-SEP` chain for each backend, and that chain does the DNAT.
+ * - nftables: the `service-` chain of the Service does the DNAT to each backend, or it names an `endpoint-` chain for each one.
+ * - IPVS: `/proc/net/ip_vs` has the line of the virtual service, then a line for each real server.
+ */
+export declare const backendsOf: (mode: ServiceRule["mode"], text: string, rule: Pick<ServiceRule, "ns" | "svc" | "ip" | "port">) => string[];
+//#endregion
+//#region src/cluster.d.ts
+/** The credentials of the API, as a container on the network of the cluster reaches it. */
+interface Credentials {
+  readonly server: string;
+  readonly ca: string;
+  readonly cert: string;
+  readonly key: string;
+}
+/** A cluster is one kind cluster that the lab made, with its own kubeconfig and Docker network. */
+interface Cluster {
+  readonly scenario: KindScenario;
+  readonly dir: string;
+  readonly kubeconfig: string;
+  readonly network: string;
+  readonly nodes: readonly string[];
+  kubectl(args: readonly string[], input?: string): Promise<string>;
+  /** This method applies Kubernetes objects, as JSON on standard input. */
+  apply(objects: readonly unknown[]): Promise<void>;
+  /** This method starts a command in a node container. */
+  exec(node: string, argv: readonly string[]): Promise<string>;
+  /** This method copies a local Docker image into each node. */
+  load(image: string): Promise<void>;
+  credentials(): Promise<Credentials>;
+  manifest(): Promise<ClusterManifest>;
+  delete(): Promise<void>;
+}
+/**
+ * This function makes a kind cluster from a scenario, in a folder that holds its config, its
+ * kubeconfig and the cache of kubectl. The cluster gets a Docker network of its own. The function
+ * refuses a pod or service subnet that overlaps a Docker network, because that breaks the traffic
+ * between the nodes.
+ */
+export declare const createCluster: (scenario: KindScenario, dir: string) => Promise<Cluster>;
+//#endregion
+//#region src/compose.d.ts
+/** These are the parts of a running service. A composition for `lint()` gives none of them. */
+interface Parts {
+  readonly redis?: RedisClient | undefined;
+  readonly flag?: CheckFn | undefined;
+  readonly http?: TransportImpl | undefined;
+  readonly health?: HealthServer | undefined;
+}
+/** This name is the controller of the service, and its one route reads Redis when the service has Redis. */
+export declare const CONTROLLER = "work";
+export declare const ROUTE = "GET /work";
+/** This name is the check that a flag file fails: the seam of the liveness restart. */
+export declare const FLAG_CHECK = "self.flag";
+/** This name is the watchdog of the event loop. */
+export declare const WATCHDOG = "self.event-loop";
+/**
+ * This function composes the service of a declaration: its policies, its couplings, its checks,
+ * one server, one controller and each stage of the shutdown. A declaration with Redis needs the
+ * client, because the client declares the dependency and its checks.
+ */
+export declare const compose: (name: string, declaration: Declaration, parts?: Parts) => ServiceBuilder;
+//#endregion
+//#region src/faults.d.ts
+/**
+ * This module maps each trigger of a cell to the acts of the lab, as data. The runner finds each
+ * target at the time of the run. A target is a pod, the PID of a container, the network namespace
+ * of a pod, or a cgroup.
+ */
+/**
+ * A target is a process or a pod of the cell:
+ * - `server` is the first replica of the service, in the sequence of its name.
+ * - `redis` is the Redis pod.
+ * - `kube-proxy` is kube-proxy on the first worker.
+ */
+type Target = "server" | "redis" | "kube-proxy";
+/** A step is one act of a fault, in the sequence of the plan. */
+type Step = {
+  readonly do: "kubectl";
+  readonly args: readonly string[];
+  readonly background?: boolean;
+} | {
+  readonly do: "signal";
+  readonly target: Target;
+  readonly signal: "SIGKILL" | "SIGSTOP" | "SIGCONT";
+} | {
+  readonly do: "pause";
+  readonly target: Target;
+  readonly time: Quantity;
+} | {
+  readonly do: "inject";
+  readonly target: Target;
+  readonly action: "blackhole" | "clear" | "rst" | "clear-rst";
+} | {
+  readonly do: "flag";
+  readonly target: Target;
+  readonly on: boolean;
+} | {
+  readonly do: "cpu";
+  readonly target: Target;
+  readonly max: string;
+} | {
+  readonly do: "stall";
+  readonly target: Target;
+  readonly time: Quantity;
+} | {
+  readonly do: "wait";
+  readonly time: Quantity;
+};
+/**
+ * A fault plan is the steps of a run:
+ * - `inject` starts the trigger. The stamp of its first act is the `fault` reference.
+ * - `heal` ends the fault, `hold` after the fault. A trigger that ends by itself has no heal.
+ * - `restore` brings the cell back to its steady state after the run.
+ */
+interface FaultPlan {
+  readonly inject: readonly Step[];
+  readonly hold: Quantity | null;
+  readonly heal: readonly Step[];
+  readonly restore: readonly Step[];
+}
+/** This function gives the fault plan of a cell. */
+export declare const planOf: (cell: KindCell) => FaultPlan;
+/** This function tells if a trigger stops a pod of the service with its grace: a deletion, an eviction, a scale-in or a rollout. */
+export declare const deletes: (cell: KindCell) => boolean;
+//#endregion
+//#region src/image.d.ts
+/**
+ * This function stages the build context of the lab image. In the workspace, it builds the packages
+ * of the repository and packs each one as npm gets it. From npm, it packs the installed packages.
+ * Then it copies the files of the image.
+ */
+export declare const stageLabImage: () => string;
+/** This function builds the lab image one time for each process, and gives its tag. Docker keeps its layers between builds. */
+export declare const labImage: () => Promise<string>;
+//#endregion
+//#region src/lab.d.ts
+/** A stamp brackets an act on CLOCK_MONOTONIC, in milliseconds. */
+interface Stamp {
+  readonly t0: number;
+  readonly t1: number;
+}
+/** These kinds of kernel record stay in the raw record of a run. The lab counts the other kinds and drops them. */
+export declare const KEPT_KERNEL: ReadonlySet<string>;
+/** A kind lab is the instruments of one cluster: a sidecar pair on each node, the watcher of the API and the prober. */
+interface KindLab {
+  readonly cluster: Cluster;
+  readonly image: string;
+  /** These are the lines since the last `take()`. */
+  readonly lines: Line[];
+  /** This record counts the kernel records that the lab dropped, by kind. */
+  readonly dropped: Record<string, number>;
+  /** This method gives the names of the containers that the lab started: they are not the lab containers of another agent. */
+  own(): string[];
+  /** This method gives the lines since the last call, and starts a new buffer. */
+  take(): Line[];
+  /** This method adds a listener of each line, and gives the function that removes it. */
+  listen(listener: (line: Line) => void): () => void;
+  watch(namespaces: readonly string[]): Promise<void>;
+  probe(netns: readonly number[]): Promise<void>;
+  stopProbe(): Promise<void>;
+  /** This method asks each agent to poll the backends of a Service in the rules of its node, `every` apart, or to stop with null. */
+  rules(rule: (ServiceRule & {
+    readonly every: Quantity;
+  }) | null): Promise<void>;
+  act(node: string, spec: Readonly<Record<string, unknown>>): Promise<Stamp>;
+  inject(node: string, pid: number, args: readonly string[]): Promise<Stamp>;
+  now(): Promise<number>;
+  pidOf(node: string, namespace: string, pod: string, container: string): Promise<number>;
+  netnsOf(node: string, pid: number): Promise<number>;
+  /** This method gives the path of the cgroup of a process, as the agent reaches it through the root of the node. */
+  cgroupOf(node: string, pid: number): Promise<string>;
+  close(): Promise<void>;
+}
+/**
+ * This function opens the instruments of a cluster. Each node gets the agent of the lab and the
+ * injector of the harness, privileged and in the PID namespace of the node. Thus the agent signals
+ * a process of a pod by its PID on the node. The injector enters the network namespace of a pod
+ * with `nsenter`.
+ */
+export declare const openKindLab: (cluster: Cluster, image: string) => Promise<KindLab>;
+/** This function pins a Docker image by digest under a local tag that holds the digest, for `kind load` and `imagePullPolicy: Never`. */
+export declare const localPin: (image: string) => Promise<string>;
+//#endregion
+//#region src/manifests.d.ts
+/** This image is Redis 7.4, the stock target of the harness, pinned by digest. */
+export declare const REDIS_IMAGE = "redis:7.4@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f";
+/** This function gives the namespace of a cell: `lab-` and 10 digits of the sha256 of its name. */
+export declare const namespaceOf: (cell: Pick<KindCell, "name">) => string;
+/** This function gives a probe of the pod: an HTTP GET of the health server, with each field of the cell. */
+export declare const probeOf: (path: string, probe: KubeletProbe) => Record<string, unknown>;
+/** These are the objects of Redis: one replica behind a Service, with no persistence. */
+export declare const redisObjects: (namespace: string, image: string) => unknown[];
+/** These are the objects of the service: a Service of type ClusterIP, and the Deployment with the settings of the cell. */
+export declare const serverObjects: (cell: KindCell, namespace: string, image: string, version?: number) => unknown[];
+/** These are the objects of the clients: a DaemonSet with one client on each node, the control plane too. */
+export declare const clientObjects: (cell: KindCell, namespace: string, image: string, target: string) => unknown[];
+//#endregion
+//#region src/predict.d.ts
+/**
+ * A propagation is the time from a change of an endpoint to the rules of each node. A
+ * calibration measures it for each kube-proxy mode and node count. Without a calibration, its upper
+ * bound is `minSyncPeriod`: an idle kube-proxy syncs a change at once, or one `minSyncPeriod`
+ * after its last sync.
+ */
+interface Propagation extends Band {
+  /** This text tells where the bound comes from: a calibration, or the documented `minSyncPeriod`. */
+  readonly from: string;
+}
+/** This propagation is the documented bound, before a calibration: from zero to one `minSyncPeriod` of 1 s. */
+export declare const DOCUMENTED: Propagation;
+/**
+ * This function gives the time from a flip of the probed state to the decision of the kubelet. The
+ * next probe comes within one period, then `threshold − 1` more periods follow. A probe of an
+ * endpoint that does not answer fails at its timeout.
+ */
+export declare const kubeletBand: (probe: KubeletProbe, hangs: boolean) => Band;
+/**
+ * This function gives the time from a fault of a dependency to the trip of a readiness or liveness
+ * latch. A dependency that refuses fails each poll at once. A silent dependency fails each poll at
+ * the request timeout of its client, or at the timeout of the poll when that is shorter. The
+ * watchdog of the client can close the connection sooner, and then each poll fails at once.
+ */
+export declare const latchBand: (timing: Timing, poll: Poll, failure: "refuses" | "silent", requestTimeout?: Quantity) => Band;
+/** This function gives the time from a fault to the removal of the endpoints from the rules: the latch, then the kubelet, then the propagation. */
+export declare const removalBand: (latch: Band, probe: KubeletProbe, propagation: Propagation) => Band;
+/**
+ * This function gives the time from a fault to the SIGTERM of a replica whose liveness fails with
+ * its readiness. The time is the latch, then the liveness probes of the kubelet, then the preStop sleep.
+ */
+export declare const restartBand: (latch: Band, liveness: KubeletProbe, preStop: Quantity) => Band;
+/**
+ * This function gives the time from the start of a stall of the event loop to the removal of the
+ * replica from the rules. Each probe in the stall fails at its timeout, because the loop does not answer it.
+ */
+export declare const stallRemovalBand: (readiness: KubeletProbe, propagation: Propagation) => Band;
+/** This function gives the cap of a stage in a declaration, or zero when the declaration does not name the stage. */
+export declare const capOf: (declaration: Declaration, stage: Stage) => Quantity;
+/**
+ * This function gives the shortest time from the deletion of a pod to the stop of its intake. It
+ * is the preStop sleep, then the hold of `fail readiness`. The kubelet adds its own delay before
+ * the preStop, thus the real time is longer.
+ */
+export declare const intakeAfter: (declaration: Declaration, preStop: Quantity) => Quantity;
+/**
+ * A deletion window is what a deletion predicts on one node. The listener of the pod closes at the
+ * stop of its intake. The rules of the node stop the new connections to the pod at the
+ * propagation. A connection between the two is refused. Thus the window is empty when the intake
+ * stops after the latest propagation.
+ */
+interface DeletionWindow {
+  /** This flag tells that no connection can meet a closed listener. */
+  readonly empty: boolean;
+  /** This band is the end of the window after the deletion: the propagation. */
+  readonly end: Band;
+  /** This time is the earliest stop of the intake after the deletion. */
+  readonly intake: Quantity;
+}
+/** This function gives the deletion window of a declaration and a preStop sleep on a node with a propagation. */
+export declare const deletionWindow: (declaration: Declaration, preStop: Quantity, propagation: Propagation) => DeletionWindow;
+/**
+ * This function gives the window on a node whose kube-proxy pauses across a deletion. The pause
+ * starts `lead` before the deletion and holds for `hold`. The node then syncs in one propagation
+ * after the end of the pause, at `resume` after the deletion. The window is empty when the intake
+ * stops after that.
+ */
+export declare const pausedWindow: (declaration: Declaration, preStop: Quantity, lead: Quantity, hold: Quantity, propagation: Propagation) => DeletionWindow & {
+  readonly resume: Quantity;
+};
+//#endregion
+//#region src/rules.d.ts
+/**
+ * These are the rules of the ordering law that a drain in Kubernetes meets, as data. The caller of
+ * `lint()` gives the rules, thus they are here and not in the service.
+ */
+/**
+ * O04 with the hold of the service. The listener of a pod stays open through the preStop sleep and
+ * then through the hold of `fail readiness`. Thus the sum of the two must cover the propagation of
+ * the endpoints. The rule of the research is the case without a hold.
+ */
+export declare const O04: Rule;
+/** O09 is W8: readiness detection plus propagation is no longer than liveness detection plus the preStop sleep. */
+export declare const O09: Rule;
+/** O10: the preStop sleep plus the drain of the process fits in the grace period. */
+export declare const O10: Rule;
+/** O16: the cooperative window is shorter than the drain, which is shorter than the grace less the preStop sleep. */
+export declare const O16: Rule;
+/** These are the rules of the drain that each kind cell gets. */
+export declare const DRAIN_RULES: readonly Rule[];
+/**
+ * This function gives the scenario of a cell for `lint()`: the preStop sleep, the grace, the probe
+ * period and the propagation. The probe windows are the period times the threshold of each probe.
+ */
+export declare const scenarioOf: (cell: KindCell, propagation: Propagation) => Scenario;
+/** A verdict set is the verdict of each drain rule for one declaration, by the identifier of the rule. */
+type Verdicts = Readonly<Record<string, Verdict>>;
+/** This function applies the drain rules to the description of a cell, and gives each finding. */
+export declare const lintCell: (description: ServiceDescription, cell: KindCell, propagation: Propagation) => Finding[];
+/** This function gives the verdict of each drain rule, by its identifier. */
+export declare const verdictsOf: (findings: readonly Finding[]) => Verdicts;
+/** This function gives the description of the service of a cell, as the app of the image composes it. Nothing connects. */
+export declare const describeCell: (cell: KindCell) => ServiceDescription;
+//#endregion
+//#region src/run.d.ts
+/** This time is the interval of the poll of the rules on each node. */
+export declare const RULES_EVERY: Quantity;
+/** These options run a catalog of kind cells. */
+interface RunOptions {
+  /** This folder gets the raw record of each cell and `summary.ndjson`. */
+  readonly out: string;
+  readonly log: (line: string) => void;
+  /** This count is the number of environments, each a new cluster. */
+  readonly environments?: number;
+  /** This share of the CPUs of the VM must be idle before a run starts. */
+  readonly idle?: number;
+  /**
+   * This folder holds the run folder of each cluster: its config, its kubeconfig and the cache of
+   * kubectl. It is not the output, because a kubeconfig holds credentials.
+   */
+  readonly work?: string;
+}
+/** This function writes the result of a cell: its raw record, and one line of its verdict in `summary.ndjson`. */
+export declare const writeResult: (out: string, result: KindCellResult) => void;
+/**
+ * This function does the runs of a catalog of kind cells. The cells of one kube-proxy mode and node
+ * count share a cluster. Each group gets new clusters in sequence, one for each environment. Each
+ * environment does its share of the runs of each cell, after one warm-up. The function deletes each
+ * cluster after its cells.
+ */
+export declare const runKindCells: (cells: readonly KindCell[], options: RunOptions) => Promise<KindCellResult[]>;
+/**
+ * This function gives an estimate of the time of a cell: its setup, then each run and each
+ * warm-up. A run waits for the cell at rest, samples the load, does the trigger and waits until the
+ * cell is at rest again.
+ */
+export declare const estimatedTime: (cell: KindCell, environments?: number) => Quantity;
+/**
+ * This function gives the share of a shard of a catalog: cells in sequence. Thus the cells of one
+ * mode stay together and share clusters. Each shard gets an equal share of the estimated time.
+ */
+export declare const shardOf: <T extends KindCell>(cells: readonly T[], index: number, count: number) => T[];
+//#endregion
+//#region src/tools.d.ts
+/**
+ * A tool is a binary that the lab downloads, at one pinned release, for each platform. The lab
+ * keeps it in the cache folder of this package and does not install it on the system. Each use
+ * compares its sha256 with the pinned value.
+ */
+interface Tool {
+  readonly name: "kind" | "kubectl";
+  readonly version: string;
+  /** These are the release assets, by the platform and the architecture of Node: `win32-x64`, `linux-x64`. */
+  readonly assets: Readonly<Record<string, {
+    readonly url: string;
+    readonly sha256: string;
+  }>>;
+}
+/** This release of kind is v0.33.0, from 2026-08-26. Its default node image is Kubernetes 1.37.0. The sums are from its `.sha256sum` assets. */
+export declare const KIND: Tool;
+/** This release of kubectl is v1.37.0, the version of the node image. The sums are from the `.sha256` files of `dl.k8s.io`. */
+export declare const KUBECTL: Tool;
+/** This folder is the cache of the tools: `.cache/` in this package, which git ignores. `KIND_CACHE` names another folder. */
+export declare const cacheFolder: () => string;
+/** This function gives the platform key of this process, as the assets name it. */
+export declare const platformKey: (platform?: string, arch?: string) => string;
+/** This function gives the sha256 of some bytes, in hexadecimal. */
+export declare const sha256: (bytes: Uint8Array) => string;
+/** This function gives the path of a tool in the cache, for a platform. */
+export declare const toolPath: (tool: Tool, key?: string, cache?: string) => string;
+/**
+ * This function gives the path of a tool, after a download when the cache does not have it. It
+ * refuses bytes whose sha256 is not the pinned value, from the cache or from the download.
+ */
+export declare const ensureTool: (tool: Tool, key?: string, cache?: string) => Promise<string>;
+//#endregion
+export { type Band, type BandV1, CLIENT, type Cluster, type ClusterManifest, type Credentials, type Declaration, type DeletionWindow, Endpoint, type EnvironmentManifest, FORMAT, FORMAT_V1, type FaultPlan, HEALTH_PORT, type Judged, KIND_NOISE, KUBE_PROXY_MODES, type KindCell, type KindCellRecord, type KindCellRecordV1, type KindCellResult, type KindCellV1, type KindConfig, type KindDecision, type KindLab, type KindRun, type KindScenario, type KindVerdict, type KindVerdictV1, type KubeProxyMode, type KubeletProbe, LAST_SLACK, LOG_LABEL, Line, type LoadSample, NODE_IMAGES, type NodeImage, PORT, type Parts, PodLine, type PodSettings, type Prediction, type PredictionV1, type Propagated, type Propagation, REDIS, RELATIVE, RecordLine, type RedisDeclaration, type Reference, type Replica, Request, RulesLine, type RunCheck, type RunCheckV1, type RunFacts, type RunFactsV1, type RunOptions, SERVER, STAGES, type ServiceRule, SliceLine, type Stamp, type Step, type Target, type Template, type TimeSpread, type Tool, type Trigger, type TriggerKind, type TriggerV1, type Verdicts, type Workload, backendsAt, bandOf, byNode, calibrationOf, cellsTable, checkRun, cidrOverlap, cidrRange, deletionOf, dropOf, emptyOf, factsOf, failuresOf, goDuration, intakeOf, judge, judgeKind, kernelCounts, kindCellRecordSchema, kindCellRecordV1Schema, kindConfig, kubeProxyPatch, medianInterval, medianText, middle, nodeNames, outcomesOf, podsAt, podsOf, predictionText, propagationOf, quantileOf, readRecord, recordsOf, referenceOf, requestsOf, restartsAt, rulesOf, scenario, scenarioProblems, seconds, secondsOf, showBand, signalOf, signalsOf, sliceDropOf, sliceEmptyOf, slicesOf, timeSpread, transitionOf, unitOf, upgrade, upgradeCell };
+//# sourceMappingURL=index.d.ts.map