@copilotkit/aimock 1.42.1 → 1.44.0

package/dist/chaos.js

@@ -1,10 +1,21 @@
-import { resolveTestId } from "./helpers.js";
-import { writeErrorResponse } from "./sse-writer.js";
+import { DEFAULT_TEST_ID } from "./constants.js";
+import { describeMatch, parseStrictIntegerText, resolveTestId } from "./helpers.js";
+import { delay, writeErrorResponse } from "./sse-writer.js";
 
 //#region src/chaos.ts
 /**
-* Narrow the server-defaults argument. A `ChaosScope` is distinguishable from a
-* `ChaosConfig` by construction: the latter only ever carries the three rates.
+* Narrow the server-defaults argument. The discrimination is STRUCTURAL: a
+* `ChaosConfig` only ever carries the fault fields (`dropRate`,
+* `malformedRate`, `rateLimitRate`, `disconnectRate`, `latencyMs`), so the
+* presence of a `base` / `byTestId` key means a `ChaosScope`.
+*
+* Both members are optional, so `{}` satisfies BOTH types and is reported here
+* as a config, not a scope. That is not a bug to route around: an empty scope
+* and an empty config resolve to exactly the same thing (no chaos, nothing to
+* select), so no caller can observe which branch ran. The server's own defaults
+* getter (`src/server.ts`) always sets `byTestId`, so a real server's value is
+* never the ambiguous one. A THIRD variant, or a scope whose emptiness became
+* observable, would need a tagged discriminant instead of this shape test.
 */
 function isChaosScope(defaults) {
 	return "base" in defaults || "byTestId" in defaults;
@@ -15,75 +26,520 @@ function isChaosScope(defaults) {
 * resolved by `resolveTestId` — the same helper `getTestId` and the control API
 * use — so a harness that tags by `?testId=` lands in the same scope its chaos
 * override was stored under, and the two sides cannot disagree.
+*
+* SELECTION, NOT MERGE. A scoped override REPLACES the baseline wholesale; it
+* is not layered field-wise over it. A server started with `--chaos-latency
+* 500` whose test installs `{ dropRate: 1 }` sees drops with NO latency on that
+* test's traffic — restate `latencyMs` in the override to keep it. See
+* `ChaosScope` in types.ts for why replacement is the contract (it is what
+* separates `POST /__aimock/chaos {}` from `DELETE`), and note that the two
+* links above this one — fixture and headers, applied below — DO merge
+* field-wise. `POST`/`GET /__aimock/chaos` echo the config actually in effect
+* for the scope, and the control API warns when an install drops a field that
+* was in effect, so nothing is lost silently.
+*
+* PRESENCE of the entry is what selects, not its truthiness: the lookup asks
+* `has`, not `get`. A map built with the key mapped to `undefined` (or to an
+* empty object) is an override that was explicitly installed and says "no
+* chaos for this test" — the `POST /__aimock/chaos {}` case — so it must win
+* over `base` exactly like a populated one. Testing `get(...)` truthiness would
+* quietly demote that one shape back to the baseline, which is the merge
+* behaviour this contract exists to rule out.
 */
 function resolveScopedDefaults(serverDefaults, rawHeaders, url) {
 	if (!serverDefaults) return void 0;
 	if (!isChaosScope(serverDefaults)) return serverDefaults;
-	const scoped = serverDefaults.byTestId?.get(resolveTestId(rawHeaders ?? {}, url));
-	if (scoped) return scoped;
+	const testId = resolveTestId(rawHeaders ?? {}, url);
+	if (serverDefaults.byTestId?.has(testId)) return serverDefaults.byTestId.get(testId) ?? {};
 	return serverDefaults.base;
 }
 /**
-* Resolve chaos config from headers, fixture, and server defaults.
-* Header values override fixture values, which override server defaults
-* (which are themselves per-testId — see `ChaosScope`).
+* Every chaos field, with its accepted upper bound and its header spelling.
+* ONE table: every source — request header, fixture chaos, server default, the
+* `POST /__aimock/chaos` control API and the `--chaos-*` CLI flags — resolves a
+* field through this entry via {@link parseChaosField}, so no source can drift
+* onto its own bound or its own idea of which fields take a whole number.
+*
+* Exported for the two surfaces that live in other modules (`src/server.ts`'s
+* control API, `src/cli.ts`'s flag parsing); in-module callers go through
+* {@link parseChaosField} too.
 */
-function resolveChaosConfig(fixture, serverDefaults, rawHeaders, logger, url) {
-	const base = { ...resolveScopedDefaults(serverDefaults, rawHeaders, url) };
-	if (fixture?.chaos) {
-		if (fixture.chaos.dropRate !== void 0) base.dropRate = fixture.chaos.dropRate;
-		if (fixture.chaos.malformedRate !== void 0) base.malformedRate = fixture.chaos.malformedRate;
-		if (fixture.chaos.disconnectRate !== void 0) base.disconnectRate = fixture.chaos.disconnectRate;
+const CHAOS_FIELDS = {
+	dropRate: {
+		header: "x-aimock-chaos-drop",
+		max: 1,
+		integer: false
+	},
+	malformedRate: {
+		header: "x-aimock-chaos-malformed",
+		max: 1,
+		integer: false
+	},
+	disconnectRate: {
+		header: "x-aimock-chaos-disconnect",
+		max: 1,
+		integer: false
+	},
+	rateLimitRate: {
+		header: "x-aimock-chaos-ratelimit",
+		max: 1,
+		integer: false
+	},
+	latencyMs: {
+		header: "x-aimock-chaos-latency",
+		max: 3e4,
+		integer: true
 	}
-	if (rawHeaders) {
-		const dropHeader = rawHeaders["x-aimock-chaos-drop"];
-		const malformedHeader = rawHeaders["x-aimock-chaos-malformed"];
-		const disconnectHeader = rawHeaders["x-aimock-chaos-disconnect"];
-		if (typeof dropHeader === "string") {
-			const val = parseFloat(dropHeader);
-			if (isNaN(val)) logger?.warn(`[chaos] x-aimock-chaos-drop: invalid value "${dropHeader}", ignoring`);
-			else {
-				if (val < 0 || val > 1) logger?.warn(`[chaos] x-aimock-chaos-drop: value ${val} out of range [0,1], clamping`);
-				base.dropRate = Math.min(1, Math.max(0, val));
-			}
-		}
-		if (typeof malformedHeader === "string") {
-			const val = parseFloat(malformedHeader);
-			if (isNaN(val)) logger?.warn(`[chaos] x-aimock-chaos-malformed: invalid value "${malformedHeader}", ignoring`);
-			else {
-				if (val < 0 || val > 1) logger?.warn(`[chaos] x-aimock-chaos-malformed: value ${val} out of range [0,1], clamping`);
-				base.malformedRate = Math.min(1, Math.max(0, val));
-			}
+};
+const CHAOS_FIELD_NAMES = Object.keys(CHAOS_FIELDS);
+/**
+* A plain decimal RATE: digits with an optional fractional part, and nothing
+* else. Deliberately NOT what `Number()` accepts — `Number` is a full-string
+* parse (unlike `parseFloat`, which would take the `0.5` out of `"0.5abc"`),
+* but it is also a JS *literal* parse, so it happily reads `"0x1e"` as 30,
+* `"0b1"` as 1, `"1e3"` as 1000 and `"Infinity"` as Infinity. None of those is
+* a rate a caller meant to write, and `0x1` silently becoming `dropRate: 1`
+* turns a typo into a 100 % outage. A leading `+`/`-` sign, `_` separators and
+* exponents are rejected for the same reason.
+*/
+const DECIMAL_RATE = /^(?:\d+(?:\.\d*)?|\.\d+)$/;
+/**
+* The ONE way a chaos number is parsed, whatever its source.
+*
+* Two shapes, picked per field by the `CHAOS_FIELDS` table: a RATE is a plain
+* decimal in `[0, max]` (max is always 1), and an INTEGER field (`latencyMs`)
+* is a whole, non-negative count of milliseconds in `[0, max]`. `integer`
+* defaults to false so a caller that omits it gets the rate grammar.
+*
+* The VALUE rules apply to every source alike: `NaN` and non-finite values, a
+* fractional value for an integer field, negative zero, and anything outside
+* `[0, max]` are all rejected (returned as `undefined`) whether they arrived as
+* text or as a typed number. Nothing is ever clamped — a value the caller did
+* not ask for is never substituted for the one they did. Negative zero is
+* rejected rather than folded to `0` so that it matches its own text form
+* (`"-0"`, which the sign-less grammar already refuses) and so that no `-0`
+* escapes into a config object that later gets echoed back over JSON.
+*
+* The GRAMMAR above — the two regexes — is a rule about TEXT, and only a string
+* input passes through it: trailing garbage (`"0.5abc"`), non-numeric text
+* (`"banana"`), the empty string, a sign (`"+1"`, `"-0"`) and the JS
+* numeric-literal forms that are not plain decimals (`"0x1e"`, `"0b1"`,
+* `"1e3"`, `"Infinity"`) are rejected as spellings. A fixture or JSON body that
+* writes `latencyMs: 1e3` has ALREADY been through a JSON/JS parser and hands
+* this function the number `1000`, indistinguishable from a literal `1000` — so
+* it is accepted, while the header `"1e3"` is not. That asymmetry is the point,
+* not a gap: the grammar exists to stop an ambiguous *spelling* on the wire
+* (`0x1` silently becoming `dropRate: 1` turns a typo into a 100 % outage),
+* and a value that reached us as a number has no spelling left to police.
+*/
+function parseChaosNumber(raw, max, integer = false) {
+	let value;
+	if (typeof raw === "number") value = raw;
+	else if (typeof raw === "string") if (integer) {
+		const n = parseStrictIntegerText(raw.trim());
+		if (n === null) return void 0;
+		value = n;
+	} else {
+		const text = raw.trim();
+		if (!DECIMAL_RATE.test(text)) return void 0;
+		value = Number(text);
+	}
+	else return;
+	if (!Number.isFinite(value)) return void 0;
+	if (integer && !Number.isInteger(value)) return void 0;
+	if (Object.is(value, -0)) return void 0;
+	if (value < 0 || value > max) return void 0;
+	return value;
+}
+/**
+* Parse a value for a NAMED chaos field, taking its bound and its integer-ness
+* from `CHAOS_FIELDS` instead of from the call site. Every entry point should
+* call this rather than `parseChaosNumber` with hand-written limits — that is
+* what makes the "ONE table" claim above true instead of aspirational.
+*/
+function parseChaosField(field, raw) {
+	return parseChaosNumber(raw, CHAOS_FIELDS[field].max, CHAOS_FIELDS[field].integer);
+}
+/**
+* The single value a repeated header carries. Node models a repeat two ways —
+* as a `string[]`, and (for most headers) folded into one comma-joined string —
+* and ONE rule covers both shapes, so the two can never diverge: split on
+* commas, trim, drop empties, and the FIRST NON-EMPTY value wins.
+*
+* "Non-empty" is the load-bearing word. `x-aimock-chaos-latency: ` followed by
+* `x-aimock-chaos-latency: 500` reaches the handler as `",500"` or
+* `["", "500"]` depending on the shape; taking element `[0]` blindly made the
+* folded form warn "rejected latencyMs value \"\"" while the array form went
+* silently absent — two behaviours for one wire-level request. An empty value
+* carries no instruction, so it is skipped rather than rejected.
+*
+* A repeat whose values DISAGREE is a real misconfiguration (two different
+* rates asked for on one request), so it warns once and the first wins.
+* "Disagree" is judged on what the values MEAN, not how they are spelled:
+* `0.5, 0.50` is one rate written twice and says nothing worth warning about,
+* whereas a TEXT comparison called it a conflict. Values the parser rejects
+* have no meaning to compare, so they stand for themselves — two different
+* typos still disagree, and a typo still disagrees with a valid number.
+*/
+function firstHeaderValue(raw, field, logger) {
+	const values = (Array.isArray(raw) ? raw : typeof raw === "string" ? [raw] : []).flatMap((part) => part.split(",")).map((part) => part.trim()).filter((part) => part !== "");
+	const first = values[0];
+	if (first === void 0) return void 0;
+	const firstMeaning = headerValueMeaning(first, field);
+	if (values.some((value) => headerValueMeaning(value, field) !== firstMeaning)) logger?.warn(`[chaos] ${CHAOS_FIELDS[field].header}: repeated header with conflicting values ${JSON.stringify(values)} — using the first (${JSON.stringify(first)})`);
+	return first;
+}
+/**
+* What one spelling of a header value MEANS, as a comparable token: the parsed
+* number when the grammar accepts it, else the raw text. Prefixed so a rejected
+* literal `"0.5"` could never compare equal to the parsed number 0.5.
+*/
+function headerValueMeaning(text, field) {
+	const { max, integer } = CHAOS_FIELDS[field];
+	const value = parseChaosNumber(text, max, integer);
+	return value === void 0 ? `raw:${text}` : `num:${value}`;
+}
+/** Placeholder for a level that carries no config, so nothing can be warned about. */
+const NO_SOURCE = { label: "(no chaos config)" };
+/**
+* Static chaos config (a fixture's `chaos`, a server default) is re-read on
+* EVERY request, so an invalid value there used to warn on every request for
+* the life of the process — thousands of identical lines for one typo. Latch
+* those: once per distinct source+field+value, PER SERVER. Per-request HEADERS
+* are dynamic input and keep warning per request, because each request really
+* is a new caller making a new mistake.
+*
+* PER SERVER, not per process. The latch hangs off the server's `Logger` — one
+* is constructed per `createServer` and every handler warns through
+* `defaults.logger`, so the logger IS the server instance as far as this
+* module can see it. A module-global `Set` instead meant two `LLMock`s in one
+* process shared one latch: the second server never reported its own bad
+* value, and one server's `resetChaosWarnings` re-armed the other's. A
+* `WeakMap` so a stopped server's keys go with it — nothing else holds them.
+*
+* Cleared by `resetChaosWarnings`, which `performFullReset` calls alongside the
+* other per-server state, so a suite that resets between tests sees the warning
+* again rather than inheriting the previous test's latch.
+*/
+const warnedStaticRejections = /* @__PURE__ */ new WeakMap();
+/**
+* Cap on distinct latched keys per server. Runtime chaos installs (`POST
+* /__aimock/chaos`, once per test in a long-lived harness) can mint unboundedly
+* many distinct bad values, and a latch that only ever grows is a leak. Past
+* the cap the OLDEST key is evicted (a `Set` iterates in insertion order), so
+* the worst case is that a long-since-warned typo warns a second time — never
+* unbounded memory.
+*/
+const MAX_LATCHED_REJECTIONS = 64;
+/**
+* Clear ONE server's static-config rejection latch, so the next request reports
+* a bad static value again. See `warnedStaticRejections`.
+*
+* Takes that server's logger because the logger is what the latch is keyed by.
+* There is deliberately no "clear every server" form: `performFullReset` is an
+* isolation barrier for the server being reset, and reaching into a concurrent
+* server's latch is exactly the cross-talk this scoping removes.
+*
+* Does NOT clear the `applyChaos` deprecation notice (`warnedSyncApplyChaos`),
+* which is once per process by design — see the latch there.
+*/
+function resetChaosWarnings(logger) {
+	warnedStaticRejections.delete(logger);
+}
+function warnRejected(source, field, raw, logger) {
+	if (!logger) return;
+	if (source.latchKey !== void 0) {
+		const key = `${source.latchKey}\u0000${field}\u0000${JSON.stringify(raw)}`;
+		let latched = warnedStaticRejections.get(logger);
+		if (!latched) {
+			latched = /* @__PURE__ */ new Set();
+			warnedStaticRejections.set(logger, latched);
 		}
-		if (typeof disconnectHeader === "string") {
-			const val = parseFloat(disconnectHeader);
-			if (isNaN(val)) logger?.warn(`[chaos] x-aimock-chaos-disconnect: invalid value "${disconnectHeader}", ignoring`);
-			else {
-				if (val < 0 || val > 1) logger?.warn(`[chaos] x-aimock-chaos-disconnect: value ${val} out of range [0,1], clamping`);
-				base.disconnectRate = Math.min(1, Math.max(0, val));
-			}
+		if (latched.has(key)) return;
+		if (latched.size >= MAX_LATCHED_REJECTIONS) {
+			const oldest = latched.values().next();
+			if (!oldest.done) latched.delete(oldest.value);
 		}
+		latched.add(key);
+	}
+	const shape = CHAOS_FIELDS[field].integer ? "a whole number of ms" : "a number";
+	logger.warn(`[chaos] ${source.label}: rejected ${field} value ${JSON.stringify(raw)} — must be ${shape} in [0,${CHAOS_FIELDS[field].max}]; ignoring it`);
+}
+/**
+* Serial number per fixture OBJECT, minted on demand, so a fixture's latch key
+* is its identity rather than its (possibly colliding) description. Same reason
+* `router.ts` keys its relaxed-turnIndex throttle by object identity. A
+* `WeakMap`, so the serial dies with the fixture.
+*/
+const fixtureSerials = /* @__PURE__ */ new WeakMap();
+let nextFixtureSerial = 0;
+/** Name and latch-identify the fixture whose `chaos` block is being read. */
+function fixtureSource(fixture) {
+	let serial = fixtureSerials.get(fixture);
+	if (serial === void 0) {
+		serial = nextFixtureSerial++;
+		fixtureSerials.set(fixture, serial);
+	}
+	return {
+		label: `fixture chaos ${describeMatch(fixture.match, -1)}`,
+		latchKey: `fixture#${serial}`
+	};
+}
+/**
+* Name and latch-identify the server-level config this request resolved to. A
+* per-testId override and the server-wide baseline are DIFFERENT sources — a
+* typo in one must not latch the other silent — so the testId is part of both
+* the label and the key.
+*
+* Mirrors the selection in `resolveScopedDefaults` (which is the authority):
+* the baseline is the scope's `DEFAULT_TEST_ID` entry, so an untagged request
+* reads as the plain server default rather than an override named after an
+* internal sentinel.
+*/
+function serverSource(serverDefaults, rawHeaders, url) {
+	if (serverDefaults && isChaosScope(serverDefaults)) {
+		const testId = resolveTestId(rawHeaders ?? {}, url);
+		if (testId !== DEFAULT_TEST_ID && serverDefaults.byTestId?.has(testId)) return {
+			label: `server chaos default (testId ${JSON.stringify(testId)})`,
+			latchKey: `server:${testId}`
+		};
+	}
+	return {
+		label: "server chaos default",
+		latchKey: "server"
+	};
+}
+/** Read one field from the request headers. */
+function readHeaderField(rawHeaders, field, logger) {
+	const text = firstHeaderValue(rawHeaders?.[CHAOS_FIELDS[field].header], field, logger);
+	if (text === void 0) return void 0;
+	const value = parseChaosField(field, text);
+	if (value === void 0) warnRejected({ label: CHAOS_FIELDS[field].header }, field, text, logger);
+	return value;
+}
+/** Read one field from a config object — a fixture's chaos, or the server default. */
+function readConfigField(config, field, source, logger) {
+	const raw = config?.[field];
+	if (raw === void 0) return void 0;
+	const value = parseChaosField(field, raw);
+	if (value === void 0) warnRejected(source, field, raw, logger);
+	return value;
+}
+/**
+* Resolve chaos config from headers, fixture, and server defaults.
+* Header values override fixture values, which override server defaults —
+* field-wise at each step, so a level that sets only `dropRate` leaves the
+* level below's `latencyMs` intact. The server defaults are themselves selected
+* per-testId first, and THAT step replaces rather than merges (see
+* `resolveScopedDefaults` and `ChaosScope`).
+*
+* Every source goes through the same parser and the same ONE out-of-range
+* policy — reject and warn, never clamp (see `ChaosConfig`). A rejected value
+* is simply not set, so the next level of precedence applies. All three levels
+* are parsed even when a higher one wins, so a bad value is always reported
+* rather than hidden by the override above it.
+*
+* Exported so a caller that needs BOTH the latency delay and the terminal
+* action resolves once per request and threads the result through, instead of
+* parsing (and re-warning about) the same headers twice on the hot path.
+*/
+function resolveChaosConfig(fixture, serverDefaults, rawHeaders, logger, url) {
+	const serverConfig = resolveScopedDefaults(serverDefaults, rawHeaders, url);
+	const resolved = {};
+	const fixtureFrom = fixture ? fixtureSource(fixture) : NO_SOURCE;
+	const serverFrom = serverConfig ? serverSource(serverDefaults, rawHeaders, url) : NO_SOURCE;
+	for (const field of CHAOS_FIELD_NAMES) {
+		const fromHeader = readHeaderField(rawHeaders, field, logger);
+		const fromFixture = readConfigField(fixture?.chaos, field, fixtureFrom, logger);
+		const fromServer = readConfigField(serverConfig, field, serverFrom, logger);
+		const value = fromHeader ?? fromFixture ?? fromServer;
+		if (value !== void 0) resolved[field] = value;
+	}
+	return resolved;
+}
+/**
+* Resolve the deterministic latency delay (ms) for this request.
+* Precedence is header > fixture > server, same as the rates. Returns 0
+* when no latency is configured. Exported so async handlers can await the
+* delay BEFORE evaluating terminal chaos actions.
+*/
+function resolveChaosLatencyMs(fixture, serverDefaults, rawHeaders, logger, url, resolved) {
+	return (resolved ?? resolveChaosConfig(fixture, serverDefaults, rawHeaders, logger, url)).latencyMs ?? 0;
+}
+/**
+* Responses this module destroyed itself, through the `disconnect` chaos
+* action. A `WeakSet` rather than a marker property on the response: it adds
+* nothing to the object's shape (so a `ServerResponse` test double stays a
+* faithful stand-in) and the entry goes away with the response.
+*/
+const chaosDisconnectedResponses = /* @__PURE__ */ new WeakSet();
+/**
+* The reason this response can no longer carry a fresh status line, or `null`
+* while it can. Checked most-specific first: our own teardown, then an ended
+* body, then a destroyed socket, then a committed status line.
+*/
+function responseUnwritableReason(res) {
+	if (chaosDisconnectedResponses.has(res)) return "chaos-disconnected";
+	if (res.writableEnded) return "already-ended";
+	if (res.destroyed) return "client-gone";
+	if (res.headersSent) return "headers-sent";
+	return null;
+}
+/**
+* The reason this response is GONE — dead for every purpose, chaos or not —
+* or `null` while anything at all can still be done with it. `"headers-sent"`
+* is deliberately NOT one of these.
+*/
+function responseGoneReason(res) {
+	const reason = responseUnwritableReason(res);
+	return reason === null || reason === "headers-sent" ? null : reason;
+}
+/**
+* True once nothing can be delivered on this response at all: the client hung
+* up, the body was already ended, or our own `disconnect` action destroyed it.
+*
+* This is the predicate the streaming surfaces guard their post-`await` writes
+* with (`grok-video.ts`, `veo-video.ts` — which hand-rolled
+* `res.destroyed || res.writableEnded`, i.e. this minus the chaos-teardown
+* case), and the one the SPLIT chaos gates in `src/server.ts` — the ones that
+* call `awaitChaosLatency` and `evaluateChaos` separately instead of going
+* through `applyChaosAsync` — have to re-check themselves after the await.
+* Without that check a client that hangs up mid-delay still gets a full
+* response built, "served" into a dead socket and JOURNALLED (C13).
+*/
+function responseGone(res) {
+	return responseGoneReason(res) !== null;
+}
+/** Human-readable gloss per reason, so a skipped chaos action logs what actually happened. */
+const UNWRITABLE_DESCRIPTION = {
+	"chaos-disconnected": "the chaos disconnect action had already destroyed it",
+	"already-ended": "the response was already ended",
+	"client-gone": "the client disconnected",
+	"headers-sent": "a status line was already committed"
+};
+/** The gloss for one reason. Exported so the split gates in `src/server.ts` log the same words. */
+function describeUnwritableReason(reason) {
+	return UNWRITABLE_DESCRIPTION[reason];
+}
+/**
+* Await the deterministic latency delay configured for this request, if any.
+* Fixed (never randomised or jittered) so replay stays deterministic. Returns
+* immediately when no latency is configured. Handlers that roll the chaos dice
+* themselves (branching on the action before dispatching) call this first;
+* handlers that just need "delay, then maybe fail" use `applyChaosAsync`.
+*
+* Pass `res` so a client that hangs up mid-delay CANCELS the pending timer
+* (via the cancellable `delay(ms, signal)` helper) instead of leaving it armed
+* for up to the 30s cap. The wait resolves early on disconnect — callers must
+* re-check the response is still writable afterwards, which every chaos write
+* path does through `responseUnwritable`.
+*
+* The disconnect signal is taken from the RESPONSE, not the request: an
+* `IncomingMessage` is auto-destroyed as soon as its body has been fully read,
+* so `req.destroyed` / `req`'s `close` event fire on every healthy request and
+* would cancel the delay for everyone. `res`'s `close` before a write can only
+* mean the connection was terminated prematurely.
+*/
+async function awaitChaosLatency(fixture, serverDefaults, rawHeaders, logger, url, res, resolved) {
+	const delayMs = resolveChaosLatencyMs(fixture, serverDefaults, rawHeaders, logger, url, resolved);
+	if (delayMs <= 0) return;
+	if (!res) {
+		await delay(delayMs);
+		return;
+	}
+	const controller = new AbortController();
+	const onClose = () => controller.abort();
+	let unsubscribe;
+	if (responseGone(res)) controller.abort();
+	else if (typeof res.once === "function") {
+		res.once("close", onClose);
+		if (typeof res.off === "function") unsubscribe = () => res.off("close", onClose);
+		else if (typeof res.removeListener === "function") unsubscribe = () => res.removeListener("close", onClose);
+	}
+	try {
+		await delay(delayMs, controller.signal);
+	} finally {
+		unsubscribe?.();
 	}
-	if (base.dropRate !== void 0) base.dropRate = Math.min(1, Math.max(0, base.dropRate));
-	if (base.malformedRate !== void 0) base.malformedRate = Math.min(1, Math.max(0, base.malformedRate));
-	if (base.disconnectRate !== void 0) base.disconnectRate = Math.min(1, Math.max(0, base.disconnectRate));
-	return base;
 }
 /**
 * Evaluate chaos config and return the triggered action, or null if none.
-* Checks in order: drop, malformed, disconnect — first hit wins.
+*
+* THE RATES DO NOT ROLL INDEPENDENTLY. Each is a separate `Math.random()` draw
+* taken in a fixed order — drop → malformed → rateLimit → disconnect — and the
+* first draw that hits returns immediately, so the ones after it are never
+* rolled at all. A rate is therefore the probability that ITS draw hits GIVEN
+* that no earlier rate fired, not the share of requests that end in that fault.
+* Only `dropRate`, first in the chain, is unconditional.
+*
+* Worked example: `{ dropRate: 0.5, rateLimitRate: 0.5 }` yields ~50 % drops
+* and ~25 % rate limits (0.5 x 0.5 — half the requests never reach the second
+* draw), not 50 % of each. To exercise two faults at their nominal frequency,
+* configure them on separate requests rather than in one config.
 */
-function evaluateChaos(fixture, serverDefaults, rawHeaders, logger, url) {
-	const config = resolveChaosConfig(fixture, serverDefaults, rawHeaders, logger, url);
+function evaluateChaos(fixture, serverDefaults, rawHeaders, logger, url, resolved) {
+	const config = resolved ?? resolveChaosConfig(fixture, serverDefaults, rawHeaders, logger, url);
 	if (config.dropRate !== void 0 && config.dropRate > 0 && Math.random() < config.dropRate) return "drop";
 	if (config.malformedRate !== void 0 && config.malformedRate > 0 && Math.random() < config.malformedRate) return "malformed";
+	if (config.rateLimitRate !== void 0 && config.rateLimitRate > 0 && Math.random() < config.rateLimitRate) return "rateLimit";
 	if (config.disconnectRate !== void 0 && config.disconnectRate > 0 && Math.random() < config.disconnectRate) return "disconnect";
 	return null;
 }
 /**
+* Async chaos entrypoint: awaits the deterministic latency delay (when
+* configured) BEFORE rolling terminal actions. Returns true when a terminal
+* action fired (caller returns early), false to proceed.
+*
+* This is the ONLY entrypoint that honours `latencyMs`, so it is the one every
+* route handler must use: `src/__tests__/chaos-async-call-sites.test.ts` fails
+* the build if any module outside this file rolls chaos without an awaited
+* latency dominating the roll. That guard skips this file wholesale — it
+* defines the primitives — so the `applyChaos(...)` delegation below is neither
+* checked by it nor a control for it. The guard proves it is not vacuous its
+* own way: synthetic fixtures for each evasion shape, a floor on the number of
+* files scanned and chaos imports resolved, and a reconciliation of its name
+* sets against this file's real exports.
+*
+* The delay is tied to the response socket, so a client that disconnects during
+* it cancels the timer. When that happens (or the response went away for any
+* other reason while we waited) the dice are never rolled: returns
+* `"unwritable"` so the caller returns early, with nothing written and nothing
+* journalled — a response that was never sent must not appear in the journal.
+*
+* A response that merely has its HEADERS SENT is NOT gone, and is not
+* short-circuited: the delay is still awaited and the dice are still rolled.
+* `disconnect` needs no status line and is applied; the three body actions
+* are skipped and the call reports `false`, because the caller still has a
+* healthy response to finish and `if (outcome) return;` would abandon it.
+*
+* The return value is a {@link ChaosAsyncOutcome}, not a boolean, so callers
+* can tell "chaos fired" from "the response was already dead" — two outcomes
+* the old `true` conflated. Both are truthy, so the standard call shape
+* `if (await applyChaosAsync(...)) return;` keeps working unchanged; a caller
+* that cares compares against `"handled"` / `"unwritable"`.
+*/
+async function applyChaosAsync(res, fixture, serverDefaults, rawHeaders, requestUrl, journal, context, source, registry, logger) {
+	const resolved = resolveChaosConfig(fixture, serverDefaults, rawHeaders, logger, requestUrl);
+	await awaitChaosLatency(fixture, serverDefaults, rawHeaders, logger, requestUrl, res, resolved);
+	const gone = responseGoneReason(res);
+	if (gone !== null) {
+		logger?.debug(`[chaos] not applying chaos to ${context.method} ${context.path}: ${UNWRITABLE_DESCRIPTION[gone]} — nothing written, nothing journalled`);
+		return "unwritable";
+	}
+	return applyChaos(res, fixture, serverDefaults, rawHeaders, requestUrl, journal, context, source, registry, logger, resolved) ? "handled" : false;
+}
+/**
 * Apply chaos to a request. Returns true if chaos was applied (caller should
 * return early), false if the request should proceed normally.
 *
+* Synchronous, and therefore SKIPS the configured `latencyMs` delay — it cannot
+* await. It IS exported (the async wrapper and this module's tests call it by
+* name), but it is not the public surface: no handler may call it —
+* `src/__tests__/chaos-async-call-sites.test.ts` fails the build if one does —
+* and the barrel deliberately publishes `applyChaosDeprecated` under the name
+* `applyChaos` instead, so library consumers who still call it are told about
+* the latency gap. See both below.
+*
 * `requestUrl` is the RAW `req.url` (query string included) — chaos scoping
 * resolves the testId from it exactly as `getTestId` does, so `?testId=` tagged
 * traffic is not silently unscoped. It is required, not optional, so a new
@@ -93,11 +549,48 @@ function evaluateChaos(fixture, serverDefaults, rawHeaders, logger, url) {
 * the <X> phase" is enforced at the type level. A future handler that grows
 * a proxy path MUST pass `"proxy"` explicitly; the default can't drift silently.
 */
-function applyChaos(res, fixture, serverDefaults, rawHeaders, requestUrl, journal, context, source, registry, logger) {
-	const action = evaluateChaos(fixture, serverDefaults, rawHeaders, logger, requestUrl);
+function applyChaos(res, fixture, serverDefaults, rawHeaders, requestUrl, journal, context, source, registry, logger, resolved) {
+	const action = evaluateChaos(fixture, serverDefaults, rawHeaders, logger, requestUrl, resolved);
 	if (!action) return false;
-	applyChaosAction(action, res, fixture, journal, context, source, registry);
-	return true;
+	return applyChaosAction(action, res, fixture, journal, context, source, registry, logger) === "applied";
+}
+/**
+* One-shot latch for the deprecation notice below: warn once per process, not
+* per request.
+*
+* PER PROCESS, and deliberately not cleared by `resetChaosWarnings` /
+* `performFullReset` — unlike `warnedStaticRejections`, which IS per server and
+* IS cleared. The two latches guard different kinds of fact. A rejected static
+* chaos value describes THIS server's configuration, which a reset may change,
+* so a reset suite must hear about it again. This notice describes the
+* EMBEDDER'S CODE — a call site that still imports the sync `applyChaos` — and
+* a `reset()` cannot change that: re-emitting it per test would print the same
+* unchanged migration instruction once per test with nothing new to say. The
+* deprecation policy (`docs/deprecation-policy/index.html`) is about which
+* upstream endpoints aimock keeps mocking and says nothing about notice
+* frequency, so the choice is ours; the message states it ("Warned once per
+* process.") so nobody reads the single line as "it only happened once".
+*/
+let warnedSyncApplyChaos = false;
+/**
+* Public, deprecated wrapper around the synchronous {@link applyChaos}. The
+* barrel (`src/index.ts`) exports this under the name `applyChaos`, which has
+* been part of the published API since v1.10.0 — removing it outright would
+* break embedders silently, so it stays and says so instead.
+*
+* @deprecated Use {@link applyChaosAsync}. The synchronous form cannot await,
+* so it silently ignores the configured chaos latency (`latencyMs`,
+* `--chaos-latency`, `x-aimock-chaos-latency`): the fault rates still roll, but
+* no delay is injected. Every fault behaviour is otherwise identical.
+*/
+function applyChaosDeprecated(res, fixture, serverDefaults, rawHeaders, requestUrl, journal, context, source, registry, logger) {
+	if (!warnedSyncApplyChaos) {
+		warnedSyncApplyChaos = true;
+		const notice = "applyChaos() is deprecated and ignores the configured chaos latency (latencyMs / --chaos-latency / x-aimock-chaos-latency): it is synchronous and cannot await the delay. Use `await applyChaosAsync(...)` instead — same arguments, same fault behaviour, plus the latency. (Warned once per process.)";
+		if (logger) logger.warn(notice);
+		else console.warn(`[aimock] ${notice}`);
+	}
+	return applyChaos(res, fixture, serverDefaults, rawHeaders, requestUrl, journal, context, source, registry, logger);
 }
 /**
 * Apply a specific (already-rolled) chaos action. Exposed so callers that roll
@@ -107,16 +600,46 @@ function applyChaos(res, fixture, serverDefaults, rawHeaders, requestUrl, journa
 *
 * `source` is required (not optional) so callers can't silently omit it on
 * one branch and journal an ambiguous entry. Pass `"fixture"` when a fixture
-* matched (or would have) and `"proxy"` when the request was headed for the
-* proxy path.
+* matched (or would have), `"proxy"` when the request was headed for the proxy
+* path, and `"internal"` — the value most call sites pass — for aimock's own
+* built-in endpoints, which are neither.
+*
+* A chaos action can be dispatched an arbitrarily long time after the request
+* arrived (up to the 30s latency cap), by which point the client may be gone.
+* Writing to a destroyed socket is silently lost, so counting the action and
+* journalling a status the client never received would be a lie. When the
+* response cannot take THIS action this is a no-op: no metric, no journal
+* entry, no write, and the return value says `"skipped"`. The journal
+* vocabulary has no "aborted" chaos status — the entry is omitted rather than
+* invented.
+*
+* "Cannot take this action" is per-action, not one bit. A GONE response
+* (client hung up, body ended, already chaos-destroyed) forecloses everything.
+* A response whose HEADERS ARE SENT forecloses only the three actions that
+* write a status line of their own — `disconnect` is a bare `res.destroy()`
+* and is applied normally.
+*
+* `logger` is REQUIRED (not optional, not defaulted) because every branch
+* above can decline to act, and a skip nobody can see is the bug this
+* parameter exists to prevent: one call site had quietly omitted it. It is
+* typed `Logger | undefined` rather than `Logger` because the public,
+* deprecated `applyChaos` wrapper's own logger is optional and threads through
+* here — arity is what the compiler enforces, and that is what catches the
+* omission.
 */
-function applyChaosAction(action, res, fixture, journal, context, source, registry) {
-	if (registry) registry.incrementCounter("aimock_chaos_triggered_total", {
-		action,
-		source
-	});
+function applyChaosAction(action, res, fixture, journal, context, source, registry, logger) {
+	const unwritable = responseUnwritableReason(res);
+	if (unwritable !== null && (unwritable !== "headers-sent" || action !== "disconnect")) {
+		logger?.debug(`[chaos] skipping ${action} on ${context.method} ${context.path}: ${UNWRITABLE_DESCRIPTION[unwritable]} — no metric, no journal entry, no write`);
+		return "skipped";
+	}
 	switch (action) {
 		case "drop":
+			writeErrorResponse(res, 500, JSON.stringify({ error: {
+				message: "Chaos: request dropped",
+				type: "server_error",
+				code: "chaos_drop"
+			} }));
 			journal.add({
 				...context,
 				response: {
@@ -126,13 +649,10 @@ function applyChaosAction(action, res, fixture, journal, context, source, regist
 					source
 				}
 			});
-			writeErrorResponse(res, 500, JSON.stringify({ error: {
-				message: "Chaos: request dropped",
-				type: "server_error",
-				code: "chaos_drop"
-			} }));
-			return;
+			break;
 		case "malformed":
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end("{malformed json: <<<chaos>>>");
 			journal.add({
 				...context,
 				response: {
@@ -142,25 +662,47 @@ function applyChaosAction(action, res, fixture, journal, context, source, regist
 					source
 				}
 			});
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end("{malformed json: <<<chaos>>>");
-			return;
-		case "disconnect":
+			break;
+		case "rateLimit":
+			writeErrorResponse(res, 429, JSON.stringify({ error: {
+				message: "Chaos: rate limit exceeded",
+				type: "rate_limit_error",
+				code: "chaos_ratelimit"
+			} }));
 			journal.add({
 				...context,
 				response: {
-					status: 0,
+					status: 429,
 					fixture,
-					chaosAction: "disconnect",
+					chaosAction: "rateLimit",
 					source
 				}
 			});
+			break;
+		case "disconnect": {
+			const status = res.headersSent ? res.statusCode : 0;
+			chaosDisconnectedResponses.add(res);
 			res.destroy();
-			return;
-		default: return;
+			journal.add({
+				...context,
+				response: {
+					status,
+					fixture,
+					chaosAction: "disconnect",
+					source
+				}
+			});
+			break;
+		}
+		default: return "skipped";
 	}
+	registry?.incrementCounter("aimock_chaos_triggered_total", {
+		action,
+		source
+	});
+	return "applied";
 }
 
 //#endregion
-export { applyChaos, applyChaosAction, evaluateChaos, isChaosScope };
+export { CHAOS_FIELDS, CHAOS_FIELD_NAMES, applyChaosAction, applyChaosAsync, applyChaosDeprecated, awaitChaosLatency, describeUnwritableReason, evaluateChaos, isChaosScope, parseChaosField, resetChaosWarnings, resolveChaosConfig, resolveChaosLatencyMs, responseGone, responseGoneReason };
 //# sourceMappingURL=chaos.js.map