@yolk-sdk/emulators 0.1.0-canary.96

package/dist/stateful-emulator.mjs

@@ -0,0 +1,1228 @@
+import { EmulatorHeaderRecord, answeredOutsideCore, emulatorJobHeader, handlerFailedResponse, isCredentialHeaderName, isCredentialQueryKey, redactCredentialFields, redactCredentialQuery, redactedCredentialValue } from "./emulator-http.mjs";
+import { emulatorEvidenceHeader, emulatorRouteKey } from "./route-evidence.mjs";
+import { isRecognisableBearerValue, jsonRepeatsSecret, repeatsSecret, scrubSecrets, textRepeatsSecret, unrecognisedLedgerPath, unrecognisedMethod } from "./stateful-secrets.mjs";
+import { Data, Predicate, Result } from "effect";
+import * as Schema from "effect/Schema";
+//#region src/stateful-emulator.ts
+/**
+* Shared wrapper of the fixture-only stateful connector emulators (internal; used by `/dropbox`,
+* `/notion`, `/todoist`, `/telegram`, `/github`, `/google`, `/linkedin-search`, and `/mcp`, not by
+* the earlier `/fortnox` and `/microsoft` emulators, which keep their own).
+*
+* The emulator state lives in an `@emulators/core` custom runtime that the Node-only subpath
+* creates and hands in (`src/stateful-core.ts`; this module imports no Node builtin and never
+* imports the core); the request ledger, status faults, credential handling, and the
+* `/_emulate/*` control plane live here, because the core reserves `/_emulate`.
+*
+* The owner rule: response behaviour comes only from the committed conformance fixtures. Every
+* request is answered by its route or with one ledgered 400 not-emulated
+* (`{ error: { type: 'not_emulated', message } }`, `notEmulated` in the ledger). Precedence per
+* request:
+*
+* 1. route match on the raw path (path parameters decoded once; unknown routes and methods, and
+*    invalid percent-encoding, are not emulated), and the origin the route is recorded on;
+* 2. a non-empty `Authorization: Bearer` credential (never compared against anything, stored,
+*    forwarded, or ledgered) and the emulator's header rules;
+* 3. the body the route takes (none, JSON with an `application/json` media type, or raw bytes);
+* 4. the route's request-shape check, which reads no state;
+* 5. in the core runtime, the route's plan: a pure, state-reading eligibility check that refuses
+*    what the state cannot answer the way a fixture does, and otherwise returns a commit;
+* 6. the first matching status fault, decided only for an eligible request (nothing is written);
+* 7. the commit, the only step that writes.
+*
+* A request that is not emulated (steps 1 to 5) never uses up a fault. The plan, the fault
+* decision, and the commit run synchronously together, so no other request interleaves. A route
+* that throws answers an evidence-tagged 500 emulator error
+* (`responseError` in the ledger); a closed emulator answers 503. No recovery answer reads the
+* injectable clock, so a failing clock cannot change it. Every response of a matched route
+* carries `x-emulator-evidence: unverified` when the route is unverified. Ledgered bodies and
+* query parameters have credential-named keys redacted.
+*
+* Fail-closed mode (opt-in, `failClosed`; used by `/github`, `/google`, and `/linkedin-search`):
+* every route parameter has a raw pattern (matched in full), and a request is recognised only when
+* its raw path is exactly an emulated route shape under that route's method and any `Authorization`
+* header is exactly `Bearer <at least 8 non-space characters>` (a recognisable bearer, below).
+* Every other request is ledgered and answered with constant text only (`/<unrecognised>`, a
+* standard method or `<other>`, an empty query, no body, a constant reason). A recognised bearer
+* must match the RFC 6750 `b64token` syntax exactly (`^[A-Za-z0-9\-._~+/]+=*$`, at least 8
+* characters), start with a character in `[G-Zg-z\-._~+/]` other than `n`, `r`, `t`, `u`, and hold
+* at least one character outside the JSON-number alphabet `[0-9.eE+-]` (every GitHub and Google
+* token form does: `ghp_…`, `github_pat_…`, `gho_…`, `ya29.…`). So no number's text can contain it;
+* it holds no escape introducer (`%`, `\`, `"`), so no escape starts inside it; and its first
+* character is no hex digit and no JSON escape letter, so no stray `%`, `\`, or partial escape to
+* its left can complete with it, and its characters always decode in place. An `Authorization`
+* header with any other value is unrecognisable. A recognised request that repeats the bearer value
+* in its raw path, any path segment, the raw query or any query key or value, any recorded header,
+* or its body is refused and ledgered with constant text only: a standard method, the path
+* `/<unrecognised>`, its route template, an empty query, no headers or body, and a constant reason
+* (`the query repeats the credential`, for example). Each part is checked through the closure of
+* two total, lexical transforms that cannot fail: a tolerant percent-decode (every `%XX` below
+* `%80` becomes its ASCII character; any other `%` sequence is left as it is) and a tolerant
+* JSON-unescape (in any text, whether or not it parses as JSON, `\uXXXX` below `\u0080` and `\"`,
+* `\\`, `\/`, `\b`, `\f`, `\n`, `\r`, `\t` become their characters). Starting from each part's raw
+* text, either transform is applied to every text of the previous step, deduplicated, until no new
+* text appears (a fixpoint), and every text is checked for the bearer as a substring; both
+* transforms never lengthen a text and shorten it whenever they change it. So any depth of
+* percent-encoding or JSON escaping, in any order, is seen through in every part: the raw path and
+* each raw path segment, the raw query and each query key and value (already decoded once by
+* `URLSearchParams`), each recorded header, and the raw body. The work is capped at 64 rounds, 1024
+* distinct texts, or 8 Mi characters read by the transforms, whichever comes first; a part whose
+* closure hits a cap before its fixpoint counts as repeating the credential and is refused with the
+* same constant entry (uncertainty refuses, it never admits; so any part over 4 Mi characters is
+* always refused). Any other recognised request has the bearer value scrubbed from its ledgered
+* fields and every not-emulated reason (plan-time reasons included); its recorded query is keyed by
+* recorded key; a key recorded more than once lists its values in order (as a JSON array); and
+* recorded headers and query keys and values that start like JSON (`{`, `[`, `"`) are recorded
+* parsed with credential-named keys redacted at any depth, or as `<redacted>` when they do not
+* parse, whatever the header's declared format. Empty query components (a bare `?`, a stray `&`)
+* are refused. Routes check their own query and body keys with `exactQuery` and `exactBodyKeys`,
+* whose reasons never echo a request's own key (`exactQuery`'s opt-in `rawNames`, used by
+* `/linkedin-search`, also refuses a parameter name in any but its plain form, comparing the raw
+* names the wrapper hands routes as `rawQuery`). A template parameter written `{name+}` spans one
+* or more path segments (each decoded once, none may decode to a `/`). The credential helpers live
+* in `src/stateful-secrets.ts`. A route may also name decoded views of its raw body
+* (`decodedViews`, opt-in; `/google` gives the base64url-decoded MIME of a Gmail draft's
+* `message.raw`, which the provider's own wire format wraps): in fail-closed mode each view goes
+* through the same fixpoint check as the raw body, before anything is recorded, a fault is decided,
+* or anything is committed, and a hit is the same constant credential-repeat entry. A view may
+* throw to refuse a body it cannot check completely: that request is ledgered as the same constant
+* entry, as a repeat when the `DecodedViewRefusal` it threw carries cleanly decoded text holding
+* the bearer, else with the refusal's reason when the route declares it in `viewRefusalReasons` (a
+* constant the route owns, scrubbed defensively), else with
+* `the request body cannot be checked for the credential`. A route without `decodedViews` is
+* checked exactly as before. An emulator may also opt in to a per-origin bearer digest
+* (`bearerDigest`, fail-closed mode only; `/linkedin-search` uses it): routes then see a one-way
+* digest of the bearer for the origin the request arrived on (`EmulatedRequest.bearerDigest`),
+* never the bearer, so a seed can mark a key as rejected on one origin by its digest, and the
+* bearer still never reaches the state, the ledger, or `/_emulate/*`. A digest that throws or
+* repeats the bearer answers the 500 emulator error (`responseError`). Without it, routes see no
+* digest, as before.
+*
+* More opt-ins serve `/mcp`, whose JSON-RPC methods share one HTTP endpoint; a route or emulator
+* that does not take them behaves exactly as before. A route may answer several manifest rows
+* (`variants`, for example `RPC <origin><path>#<method>`): its admission names the row, which
+* becomes the request's ledger route, its coverage row, and what a fault's `match.route` compares
+* (a request refused before admission keeps the route template). A fault's `match.route` must name
+* a manifest row (a variant, or the template of a route without variants); any other value is
+* rejected when the fault is added, and `match.method` is always the HTTP method. A plan may return
+* a `StreamedCommit`: the answer it prepares, and the `commit` that writes. Faults are decided
+* against the prepared answer, and a faulted request never runs `commit`; an emulator built with
+* `makeChunkedStatefulEmulator` also takes `truncate-after-chunks` faults, which send the prepared
+* answer cut short and write nothing (one that cannot take effect answers 500 and is not used up).
+* In fail-closed mode: `constantRefusals` ledgers every refusal with constant text only
+* (`/<unrecognised>`, no query, headers, or body), so request text reaches the ledger only once a
+* route admitted the request; `guardAllHeaders` checks every request header name and value but
+* `Authorization` for a credential repeat, not only the recorded ones; and `guardOutput` checks a
+* streamed commit's prepared answer (every header and chunk) and its `persisted` texts (minted ids,
+* for example) for the bearer before any fault is decided or anything is committed, refusing a hit
+* with the constant credential-repeat entry, so no answer or stored value repeats the bearer, while
+* routes still see only its digest. `uniqueJsonKeys` refuses a JSON body in which an object repeats
+* a key (after unescaping). Routes also see every request header name
+* (`EmulatedRequest.headerNames`), never a credential value.
+*
+* Resolved mode (opt-in, `resolveRequest`; not with `failClosed`; used by `/todoist` and
+* `/telegram`) serves an emulator whose credential the wrapper cannot find by itself (a Telegram
+* bot token in a path segment) or that has its own credential rules (a Todoist bearer of any 8
+* non-space characters): the emulator resolves every request itself, failing closed
+* (`StatefulResolution`): an unrecognised request is ledgered with constant text only (the method
+* as sent when standard, else `<other>`), a request it refuses before its body is read keeps its
+* scrubbed fields, and a recognised one names its route, credential-free parameters, ledger path,
+* guarded path, and the credential values to guard. Those values are scrubbed from everything the
+* ledger keeps or a refusal answers (plan-time reasons included), and a query, guarded path, or
+* body that repeats one (raw or percent-decoded once, and in any parsed JSON key, string, or
+* number) is refused with a constant reason before anything else is checked. The ledger records
+* the resolution's path and the query as sent (credential-named keys redacted), faults'
+* `match.path` compares that path, and routes and the core see it too (routes see no header
+* names and read no header but `content-type`), so the credential never reaches a route or the
+* core. The request body is read once, after the query and path checks (so a query or path refusal
+* leaves it unread, and any later refusal finds it read); a body that is already consumed or
+* locked is refused as unreadable; a refusal reason that cannot be percent-encoded (an unpaired
+* surrogate) is a handler failure (500). Fault answers and refusals are decided in the core with
+* the commit, but returned by the wrapper itself, so a reset or a close before they are read never
+* cancels them (only a commit's answer is the core's own); a core that answers without running
+* the dispatch (closed meanwhile) gives the 500 handler failure (`responseError`
+* `the route handler answered no eligibility verdict`). Resolved mode records no request
+* header (`recordHeaders` must be empty). More opt-ins, off by default: a `json-or-empty` route
+* body (JSON of any media type, or none), `makeHeaderlessStatefulEmulator` (ledger entries without
+* a `headers` field), and `errorTexts` (the texts of the recovery answers).
+*
+* @experimental
+*/
+/** A request the emulator does not emulate, with the reason (answered 400 not-emulated). */
+var NotEmulated = class extends Data.TaggedClass("NotEmulated") {};
+/**
+* What a route's decoded view throws to refuse a body with a reason of its own (fail-closed mode;
+* see `StatefulRouteBinding.decodedViews`). `reason` must be one of the route's declared
+* `viewRefusalReasons` (a constant the route owns, never derived from the request); `decoded` holds
+* any text the view did decode cleanly, which is still checked for the bearer first.
+*/
+var DecodedViewRefusal = class extends Data.TaggedError("DecodedViewRefusal") {};
+const notEmulated = (reason) => new NotEmulated({ reason });
+const isNotEmulated = (value) => value instanceof NotEmulated;
+const jsonResponse = (status, body, headers = {}) => {
+	const responseHeaders = new Headers(headers);
+	if (!responseHeaders.has("content-type")) responseHeaders.set("content-type", "application/json");
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: responseHeaders
+	});
+};
+/** The one answer for everything no fixture records. */
+const notEmulatedResponse = (reason) => jsonResponse(400, { error: {
+	type: "not_emulated",
+	message: `Not emulated: ${reason}`
+} });
+const emulatorError = (status, message, headers = {}) => jsonResponse(status, { error: {
+	message,
+	type: "emulator_error"
+} }, headers);
+const FaultStatus = Schema.Int.check(Schema.isBetween({
+	minimum: 400,
+	maximum: 599
+}));
+const FaultCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+const ChunkCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/**
+* Optional fault filter; an omitted field matches every request. `method` is the HTTP method
+* (never a manifest row's `RPC`). `path` is the raw request path (in resolved mode, the
+* resolution's ledger path); ending in `*`, a prefix. `route` is a manifest row path, compared
+* with the request's ledger route: the template of its matched route, or the manifest variant its
+* route admitted it as (see `StatefulRouteBinding.variants`).
+* A `route` that names no manifest row of the emulator could never match, so adding the fault
+* rejects it (a route with variants is matched by its variant rows, never its template).
+*/
+const StatefulFaultMatch = Schema.Struct({
+	method: Schema.optionalKey(Schema.String),
+	path: Schema.optionalKey(Schema.String),
+	route: Schema.optionalKey(Schema.String)
+});
+/**
+* A status fault: answer matching requests with this status (400-599), headers, and body before
+* the route runs, so nothing is written. The body defaults to an emulator-fault body
+* (`{ error: { type: 'emulator_fault', message } }`), never a guessed provider envelope. `count`
+* limits how many requests it answers (omitted: all). `match.path` is the raw request path.
+* Invalid header names or values, `location`, and framing headers are rejected.
+*/
+const StatefulFault = Schema.Struct({
+	kind: Schema.Literal("status"),
+	status: FaultStatus,
+	headers: Schema.optionalKey(EmulatorHeaderRecord),
+	body: Schema.optionalKey(Schema.Json),
+	match: Schema.optionalKey(StatefulFaultMatch),
+	count: Schema.optionalKey(FaultCount)
+});
+/**
+* Opt-in (`makeChunkedStatefulEmulator`): send the first `chunks` body chunks of the answer a
+* streamed commit prepared (`StreamedCommit`), then close the body cleanly (a truncated answer).
+* It is decided where a status fault is, after the plan, and a truncated request writes nothing:
+* its `commit` never runs (no state, counter, or runtime change). One that cannot take effect (the
+* answer is not streamed, or has no more than `chunks` chunks) answers the 500 emulator error and
+* is not used up, never a silent no-op.
+*/
+const StatefulTruncateFault = Schema.Struct({
+	kind: Schema.Literal("truncate-after-chunks"),
+	chunks: ChunkCount,
+	match: Schema.optionalKey(StatefulFaultMatch),
+	count: Schema.optionalKey(FaultCount)
+});
+/** A status fault, or (`makeChunkedStatefulEmulator`) a truncation fault. */
+const StatefulStreamFault = Schema.Union([StatefulFault, StatefulTruncateFault]);
+/** A streamed commit: the prepared `answer`, and the write (none by default) it commits. */
+const streamedCommit = (answer, commit = () => void 0, persisted = []) => ({
+	answer,
+	commit,
+	persisted
+});
+/**
+* A route of the table: its evidence (and recorded origin), the body it takes, its request-shape
+* check `admit` (no state), and `plan`, which only ever sees an admitted input: it reads the state
+* without writing and answers not emulated or the commit that writes.
+*/
+const statefulRoute = (evidence, body, admit, plan) => ({
+	...evidence,
+	body,
+	admit: (request, env) => {
+		const input = admit(request, env);
+		return isNotEmulated(input) ? input : { plan: (state, context) => plan(state, input, context) };
+	}
+});
+/** Route evidence without the handler parts. */
+const routeEvidence = ({ body: _body, admit: _admit, origin: _origin, params: _params, decodedViews: _decodedViews, viewRefusalReasons: _viewRefusalReasons, variants: _variants, ...evidence }) => evidence;
+/** The manifest rows of a route: its variants, or the route itself (`routeEvidence`). */
+const routeManifest = (route) => route.variants ?? [routeEvidence(route)];
+/** A percent-decoded path segment, or `undefined` for invalid percent-encoding. */
+const decodeSegment = (segment) => {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return;
+	}
+};
+const templatePattern = (template) => new RegExp(`^${template.split(/(\{[A-Za-z]+\+?\})/).map((part) => /^\{[A-Za-z]+\}$/.test(part) ? "([^/]+)" : /^\{[A-Za-z]+\+\}$/.test(part) ? "(.+)" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("")}$`);
+const templateNames = (template) => [...template.matchAll(/\{([A-Za-z]+)\+?\}/g)].map((match) => match[1] ?? "");
+/**
+* A multi-segment parameter decoded segment by segment (each once), or `undefined` for an empty
+* segment, invalid percent-encoding, or a segment that decodes to a `/`.
+*/
+const decodeSegments = (raw) => {
+	const segments = raw.split("/").map((segment) => {
+		const decoded = segment === "" ? void 0 : decodeSegment(segment);
+		return decoded === void 0 || decoded.includes("/") ? void 0 : decoded;
+	});
+	return segments.some((segment) => segment === void 0) ? void 0 : segments.join("/");
+};
+/**
+* `pattern` required to match a whole raw parameter: `^(?:source)$` with its flags, so alternation
+* and lazy quantifiers are tried against the whole value, never against a prefix of it.
+*/
+const wholePattern = (pattern) => new RegExp(`^(?:${pattern.source})$`, pattern.flags);
+/**
+* A matcher over a route table: the route answering `method` + raw `path`, with its parameters
+* decoded once, or `undefined` (also for a parameter that is not valid percent-encoding). A raw
+* parameter pattern must match the whole raw parameter; a pattern with the `g` or `y` flag (whose
+* matches depend on earlier ones) is refused when the matcher is built.
+*/
+const routeMatcher = (routes) => {
+	const keys = routes.map((route) => emulatorRouteKey(route.method, route.path));
+	const duplicate = keys.find((key, index) => keys.indexOf(key) !== index);
+	if (duplicate !== void 0) throw new Error(`duplicate emulator route ${duplicate}`);
+	for (const route of routes) for (const [name, pattern] of Object.entries(route.params ?? {})) if (pattern.global || pattern.sticky) {
+		const where = `${route.method} ${route.path} parameter ${name}`;
+		throw new Error(`raw patterns take no g or y flag (${where})`);
+	}
+	const compiled = routes.map((route) => ({
+		route,
+		pattern: templatePattern(route.path),
+		names: templateNames(route.path),
+		whole: new Map(Object.entries(route.params ?? {}).map(([name, raw]) => [name, wholePattern(raw)])),
+		multi: new Set([...route.path.matchAll(/\{([A-Za-z]+)\+\}/g)].map((match) => match[1] ?? ""))
+	}));
+	return (method, path) => {
+		for (const candidate of compiled) {
+			if (candidate.route.method !== method.toUpperCase()) continue;
+			const match = candidate.pattern.exec(path);
+			if (match === null) continue;
+			const raws = candidate.names.map((name, index) => [name, match[index + 1] ?? ""]);
+			if (raws.some(([name, raw]) => {
+				const pattern = candidate.whole.get(name);
+				return pattern !== void 0 && !pattern.test(raw);
+			})) continue;
+			const params = {};
+			for (const [name, raw] of raws) {
+				const value = candidate.multi.has(name) ? decodeSegments(raw) : decodeSegment(raw);
+				if (value === void 0) return void 0;
+				params[name] = value;
+			}
+			return {
+				route: candidate.route,
+				params
+			};
+		}
+	};
+};
+/** The template parameters of a route that have no raw pattern (fail-closed emulators need one). */
+const unpatternedParams = (route) => templateNames(route.path).filter((name) => !route.params?.[name]);
+const decodeJsonText = Schema.decodeUnknownResult(Schema.fromJsonString(Schema.Json));
+/** Parsed JSON, or `undefined` for invalid JSON. */
+const parseJsonText = (text) => {
+	const result = decodeJsonText(text);
+	return Result.isSuccess(result) ? result.success : void 0;
+};
+const isJsonObject = (value) => value !== void 0 && value !== null && Predicate.isObject(value) && !Array.isArray(value);
+/**
+* True when any object of a valid JSON text repeats a key, compared after JSON unescaping (so
+* `"id"` and `"\u0069d"` are one key). `JSON.parse` would keep the last value silently.
+*/
+const repeatsJsonKey = (text) => {
+	const open = [];
+	let index = 0;
+	while (index < text.length) {
+		const character = text[index];
+		if (character === "\"") {
+			let end = index + 1;
+			while (end < text.length && text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
+			const top = open.at(-1);
+			if (top?.keys !== void 0 && top.expectKey) {
+				const key = parseJsonText(text.slice(index, end + 1));
+				if (!Predicate.isString(key) || top.keys.has(key)) return true;
+				top.keys.add(key);
+				top.expectKey = false;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (character === "{") open.push({
+			keys: /* @__PURE__ */ new Set(),
+			expectKey: true
+		});
+		else if (character === "[") open.push({
+			keys: void 0,
+			expectKey: false
+		});
+		else if (character === "}" || character === "]") open.pop();
+		else if (character === ",") {
+			const top = open.at(-1);
+			if (top?.keys !== void 0) top.expectKey = true;
+		}
+		index += 1;
+	}
+	return false;
+};
+/** The media type of a `content-type` value (lower-case, without parameters). */
+const mediaType = (value) => (value ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+/**
+* A JSON object with exactly the `required` keys plus any of the `optional` ones, or not
+* emulated (naming the first missing or unknown key).
+*/
+const exactObject = (value, label, required, optional = []) => {
+	if (!isJsonObject(value)) return notEmulated(`${label} must be a JSON object`);
+	const unknown = Object.keys(value).find((key) => !required.includes(key) && !optional.includes(key));
+	if (unknown !== void 0) return notEmulated(`${label} key '${unknown}' is not emulated`);
+	const missing = required.find((key) => !(key in value));
+	return missing === void 0 ? value : notEmulated(`${label} without '${missing}' is not emulated`);
+};
+/**
+* Constant-text shape check (for fail-closed emulators): a JSON object with exactly the `required`
+* keys plus any of the `optional` ones, or not emulated. Unlike `exactObject`, a reason never
+* echoes a request's own key; it names only `label` and a missing key from the route's own list.
+*/
+const exactBodyKeys = (value, label, required, optional = []) => {
+	if (!isJsonObject(value)) return notEmulated(`${label} must be a JSON object`);
+	const keys = Object.keys(value);
+	if (keys.some((key) => !required.includes(key) && !optional.includes(key))) return notEmulated(`${label} has a key this route does not take`);
+	const missing = required.find((key) => !keys.includes(key));
+	return missing === void 0 ? value : notEmulated(`${label} without '${missing}' is not emulated`);
+};
+/** The raw parameter names of a raw query, in order (`[]` for an empty query). */
+const rawQueryNames = (raw) => raw === "" ? [] : raw.split("&").map((component) => component.split("=", 1)[0] ?? "");
+/**
+* Constant-text query check (for fail-closed emulators): exactly the `required` query keys plus
+* any of the `optional` ones, each once, as a record of their values; or not emulated. A reason
+* never echoes a request's own key; it names only a missing key from the route's own list. With
+* `rawNames`, every raw parameter name must also be the plain name it decodes to.
+*/
+const exactQuery = (request, required, optional = [], options = {}) => {
+	const keys = [...request.query.keys()];
+	if (keys.length !== new Set(keys).size) return notEmulated("repeated query parameters are not emulated");
+	if (keys.some((key) => !required.includes(key) && !optional.includes(key))) return notEmulated("a query parameter this route does not take is not emulated");
+	if (options.rawNames === true) {
+		const raw = rawQueryNames(request.rawQuery ?? "");
+		if (raw.length !== keys.length || raw.some((name, index) => name !== keys[index])) return notEmulated("a query parameter name in any but its plain form is not emulated");
+	}
+	const missing = required.find((key) => !keys.includes(key));
+	return missing === void 0 ? Object.fromEntries(request.query) : notEmulated(`requests without query parameter ${missing} are not emulated on this route`);
+};
+/** An integer in `[minimum, maximum]`, or not emulated. */
+const integerIn = (value, label, minimum, maximum) => Predicate.isNumber(value) && Number.isSafeInteger(value) && value >= minimum && value <= maximum ? value : notEmulated(`${label} must be an integer from ${minimum} to ${maximum}`);
+const defaultErrorTexts = {
+	failed: "the emulator could not build the response",
+	closed: "the emulator is closed",
+	unhandled: "the emulator failed to handle the request"
+};
+const strict = { onExcessProperty: "error" };
+const decodeFault = Schema.decodeUnknownResult(StatefulFault, strict);
+const decodeFaultList = Schema.decodeUnknownResult(Schema.Union([StatefulFault, Schema.Struct({ faults: Schema.Array(StatefulFault) })]), strict);
+const decodeStreamFault = Schema.decodeUnknownResult(StatefulStreamFault, strict);
+const decodeStreamFaultList = Schema.decodeUnknownResult(Schema.Union([StatefulStreamFault, Schema.Struct({ faults: Schema.Array(StatefulStreamFault) })]), strict);
+const issueMessage = (issue) => new Schema.SchemaError(issue).message;
+const bearerPattern = /^bearer\s+\S+/i;
+/**
+* Fail-closed mode: exactly `Bearer `, one space, and one token of at least 8 non-space characters
+* (no other scheme spelling, no extra words, so combined duplicate headers never match). The token
+* must also match the RFC 6750 `b64token` syntax, start with a character that completes no escape
+* (not a hex digit, not `n`, `r`, `t`, `u`), and hold a character outside the JSON-number alphabet
+* (`isRecognisableBearerValue`, which says why). The value is guarded, never compared against
+* anything, stored, or ledgered.
+*/
+const recognisableBearerPattern = /^Bearer ([^\s]{8,})$/;
+/** The fail-closed bearer of an `Authorization` header, or `undefined` when unrecognisable. */
+const recognisableBearer = (authorization) => {
+	const bearer = recognisableBearerPattern.exec(authorization ?? "")?.[1];
+	return bearer !== void 0 && isRecognisableBearerValue(bearer) ? bearer : void 0;
+};
+/** The raw query of a request URL (after `?`, before `#`), or `undefined` when it has none. */
+const rawQuery = (requestUrl) => {
+	const withoutFragment = requestUrl.split("#", 1)[0] ?? "";
+	const start = withoutFragment.indexOf("?");
+	return start === -1 ? void 0 : withoutFragment.slice(start + 1);
+};
+/** True for a bare `?` or an empty `&`-separated component (`URLSearchParams` drops both). */
+const hasEmptyQueryComponent = (requestUrl) => {
+	const query = rawQuery(requestUrl);
+	return query !== void 0 && query.split("&").some((component) => component === "");
+};
+/**
+* Fail-closed mode: a query key or value or a header value that starts like a JSON object, array,
+* or string (`{`, `[`, `"`) is recorded parsed with credential-named keys redacted at any depth, or
+* whole as `<redacted>` when it does not parse; any other text (numbers included) is recorded
+* unchanged. A request whose text repeats a guarded secret never gets here: it is ledgered with
+* constant text only.
+*/
+const recordedJsonLooking = (text) => {
+	const trimmed = text.trimStart();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[") && !trimmed.startsWith("\"")) return text;
+	const parsed = parseJsonText(text);
+	return parsed === void 0 ? redactedCredentialValue : JSON.stringify(redactCredentialFields(parsed));
+};
+/**
+* Fail-closed mode: the recorded query, built from every original pair (never one value per key)
+* and keyed by recorded key: credential-named keys have their values redacted, keys and values are
+* recorded as `recordedJsonLooking` does, and a key recorded more than once (two original keys may
+* record alike, for example two unparseable JSON-looking keys as `<redacted>`) lists its values in
+* order, as a JSON array.
+*/
+const recordedQueryPairs = (query, scrub) => {
+	const values = /* @__PURE__ */ new Map();
+	for (const [key, value] of query) {
+		const recordedKey = scrub(recordedJsonLooking(key));
+		const recordedValue = scrub(isCredentialQueryKey(key) ? redactedCredentialValue : recordedJsonLooking(value));
+		values.set(recordedKey, [...values.get(recordedKey) ?? [], recordedValue]);
+	}
+	return Object.fromEntries([...values].map(([key, list]) => [key, list.length === 1 ? list[0] ?? "" : JSON.stringify(list)]));
+};
+/** The constant reason of a body a route's decoded view refuses to check (the view threw). */
+const uncheckableBodyReason = "the request body cannot be checked for the credential";
+const missingBearerReason = "requests without Authorization: Bearer <token of at least 8 characters> are not emulated";
+const pathMatches = (pattern, path) => pattern.endsWith("*") ? path.startsWith(pattern.slice(0, -1)) : pattern === path;
+const faultMatches = (fault, method, path, route) => (fault.match?.method === void 0 || fault.match.method.toUpperCase() === method) && (fault.match?.path === void 0 || pathMatches(fault.match.path, path)) && (fault.match?.route === void 0 || fault.match.route === route);
+const faultBody = (status) => ({ error: {
+	type: "emulator_fault",
+	message: `Emulator fault: status ${status}.`
+} });
+const readText = (request) => request.text().then((text) => text, () => void 0);
+const readBytes = (request) => request.arrayBuffer().then((buffer) => new Uint8Array(buffer), () => void 0);
+const isControlPath = (path) => path === "/_emulate" || path.startsWith("/_emulate/");
+const withEvidence = (response, evidence) => {
+	const headers = new Headers(response.headers);
+	if (evidence === "unverified") headers.set(emulatorEvidenceHeader, "unverified");
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+};
+/**
+* The recorded query: credential-named keys redacted, and any value that parses as a JSON object or
+* array (Dropbox's browser-style `arg` parameter, for example) recorded with its credential-named
+* keys redacted at any depth, and a JSON-looking value that does not parse recorded as `<redacted>`,
+* as a recorded JSON header is.
+*/
+const recordedQuery = (query) => Object.fromEntries(Object.entries(redactCredentialQuery(query)).map(([key, value]) => {
+	if (!value.trimStart().startsWith("{") && !value.trimStart().startsWith("[")) return [key, value];
+	const parsed = parseJsonText(value);
+	return [key, parsed === void 0 ? redactedCredentialValue : JSON.stringify(redactCredentialFields(parsed))];
+}));
+/** A recorded header value: JSON with credential-named keys redacted, or the plain value. */
+const recordedHeaderValue = (header, value) => {
+	if (!header.json) return value;
+	const parsed = parseJsonText(value);
+	return parsed === void 0 ? redactedCredentialValue : JSON.stringify(redactCredentialFields(parsed));
+};
+/** `constantRefusals`: a refused request's entry keeps only constant text. */
+const blankEntry = (entry) => {
+	entry.method = unrecognisedMethod(entry.method.toUpperCase());
+	entry.path = unrecognisedLedgerPath;
+	entry.query = {};
+	entry.headers = {};
+	delete entry.body;
+	delete entry.bodyBytes;
+};
+const snapshotEntry = (entry) => ({
+	...entry,
+	query: { ...entry.query },
+	headers: { ...entry.headers }
+});
+/** Whether an entry records no truncation fault (only a status fault, if any). */
+const hasStatusFaultOnly = (entry) => entry.fault !== "truncate-after-chunks";
+/** `makeHeaderlessStatefulEmulator`: the entry without its (always empty) `headers` field. */
+const snapshotHeaderlessEntry = ({ headers: _headers, bodyBytes: _bodyBytes, ...entry }) => {
+	const copy = {
+		...entry,
+		query: { ...entry.query }
+	};
+	if (hasStatusFaultOnly(copy)) return copy;
+	throw new Error("a headerless stateful emulator records status faults only");
+};
+/**
+* Resolved mode: the constant reason when the raw query or the resolution's `guardedPath` repeats a
+* guarded secret (`repeatsSecret`: raw, and percent-decoded once), or `undefined`. Checked before
+* the body is read, so such a refusal leaves the request body unread.
+*/
+const partsCredentialRepeat = (url, guardedPath, secrets) => {
+	if (repeatsSecret(url.search, secrets)) return "the query repeats the credential";
+	return repeatsSecret(guardedPath, secrets) ? "the request path repeats the credential" : void 0;
+};
+/**
+* Resolved mode: the constant reason when the body text repeats a guarded secret, or `undefined`:
+* `repeatsSecret` on the raw text, and for a body that parses as JSON also `jsonRepeatsSecret`
+* (every key, string, and number) and as it would be recorded. A body that cannot be read or parsed
+* is left to the route's body check.
+*/
+const bodyCredentialRepeat = (text, secrets) => {
+	if (text === void 0 || text === "") return void 0;
+	const repeat = "the request body repeats the credential";
+	if (repeatsSecret(text, secrets)) return repeat;
+	const json = parseJsonText(text);
+	return json !== void 0 && (jsonRepeatsSecret(json, secrets) || repeatsSecret(JSON.stringify(json), secrets)) ? repeat : void 0;
+};
+/** The body as `Request.text()` reads it: UTF-8, a leading byte order mark dropped. */
+const bodyText = (bytes) => new TextDecoder().decode(bytes);
+const snapshotFault = (state) => ({ ...state });
+const isStreamedCommit = (planned) => !Predicate.isFunction(planned);
+/** The constant reason of a prepared output that would repeat the bearer (`guardOutput`). */
+const outputRepeatReason = "the answer would repeat the credential";
+/**
+* `guardOutput`: whether a streamed commit's answer (every header name and value, every chunk, and
+* the whole body) or any text it would persist repeats a guarded secret, through the closure.
+*/
+const outputRepeatsSecret = (planned, secrets) => {
+	const { answer } = planned;
+	return [
+		...Object.entries(answer.headers).flat(),
+		...answer.chunks,
+		answer.chunks.join(""),
+		...planned.persisted
+	].some((text) => textRepeatsSecret(text, secrets));
+};
+/**
+* A streamed answer's body, strictly pull-driven (one chunk per pull), closed cleanly after
+* `after` chunks when a truncation fault applies; no body at all for an answer without chunks.
+*/
+const streamedResponse = (answer, after) => {
+	if (answer.chunks.length === 0) return new Response(null, {
+		status: answer.status,
+		headers: answer.headers
+	});
+	const encoder = new TextEncoder();
+	const sent = after === void 0 ? answer.chunks : answer.chunks.slice(0, after);
+	let next = 0;
+	const body = new ReadableStream({ pull: (controller) => {
+		const chunk = sent[next];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		next += 1;
+		controller.enqueue(encoder.encode(chunk));
+	} }, { highWaterMark: 0 });
+	return new Response(body, {
+		status: answer.status,
+		headers: answer.headers
+	});
+};
+/**
+* Build the wrapper over a core runtime (`makeStatefulEmulator`, with truncation faults
+* `makeChunkedStatefulEmulator`, or without ledgered headers `makeHeaderlessStatefulEmulator`).
+* `createCore` receives the dispatch the core must run for every request (its only route) and
+* returns the runtime adapter; `snapshotLedgerEntry` copies a ledger entry for readers.
+*/
+const buildStatefulEmulator = async (config, createCore, chunkFaults, snapshotLedgerEntry) => {
+	const credentialHeader = config.recordHeaders.find((header) => isCredentialHeaderName(header.name));
+	if (credentialHeader !== void 0) throw new Error(`the ledger never records the credential header ${credentialHeader.name}`);
+	if (config.resolveRequest !== void 0 && config.failClosed !== void 0) throw new Error("resolveRequest (resolved mode) and failClosed exclude each other");
+	if (config.resolveRequest !== void 0 && config.recordHeaders.length > 0) throw new Error("resolveRequest (resolved mode) records no request header (recordHeaders)");
+	const resolveRequest = config.resolveRequest;
+	const errorTexts = config.errorTexts ?? defaultErrorTexts;
+	if (config.bearerDigest !== void 0 && config.failClosed === void 0) throw new Error("bearerDigest needs fail-closed mode (failClosed)");
+	for (const option of [
+		"constantRefusals",
+		"guardAllHeaders",
+		"guardOutput"
+	]) if (config[option] === true && config.failClosed === void 0) throw new Error(`${option} needs fail-closed mode (failClosed)`);
+	const constantRefusals = config.constantRefusals === true;
+	const templates = new Set(config.routes.map((route) => route.path));
+	const variantRows = /* @__PURE__ */ new Set();
+	for (const route of config.routes) {
+		if (route.variants === void 0) continue;
+		if (route.variants.length === 0) throw new Error(`route ${route.method} ${route.path} has an empty variants list`);
+		for (const variant of route.variants) {
+			const where = `variant ${variant.method} ${variant.path} of ${route.method} ${route.path}`;
+			if (variant.evidence !== route.evidence) throw new Error(`${where} must carry its route's evidence`);
+			if (templates.has(variant.path) || variantRows.has(variant.path)) throw new Error(`${where} repeats a route template or another variant path`);
+			variantRows.add(variant.path);
+		}
+	}
+	if (config.failClosed !== void 0) for (const route of config.routes) {
+		const missing = unpatternedParams(route);
+		if (missing.length > 0) {
+			const where = `fail-closed route ${route.method} ${route.path}`;
+			throw new Error(`${where} needs raw patterns for ${missing.join(", ")}`);
+		}
+	}
+	const match = routeMatcher(config.routes);
+	const manifest = config.routes.flatMap(routeManifest);
+	const manifestPaths = new Set(manifest.map((row) => row.path));
+	const jobs = /* @__PURE__ */ new Map();
+	let nextJobId = 1;
+	const dispatch = (state, request) => {
+		const job = jobs.get(Number(request.headers.get("x-emulator-job-id") ?? "NaN"));
+		if (job === void 0) return handlerFailedResponse();
+		job.dispatched = true;
+		try {
+			const planned = job.admission.plan(state, {
+				env: config.env,
+				seq: job.seq
+			});
+			if (isNotEmulated(planned)) {
+				if (resolveRequest !== void 0 && Result.isFailure(Result.try(() => encodeURIComponent(planned.reason)))) return handlerFailedResponse();
+				const reason = scrubSecrets(planned.reason, job.secrets);
+				job.notEmulated = reason;
+				return resolveRequest === void 0 ? notEmulatedResponse(reason) : answeredOutsideCore();
+			}
+			const streamed = isStreamedCommit(planned);
+			if (config.guardOutput === true) {
+				if (!streamed) return handlerFailedResponse();
+				if (outputRepeatsSecret(planned, job.secrets)) {
+					job.notEmulated = outputRepeatReason;
+					job.credentialRepeat = true;
+					return notEmulatedResponse(outputRepeatReason);
+				}
+			}
+			const decision = job.decideFault(streamed ? planned.answer.chunks.length : void 0);
+			if (decision.kind === "answer") {
+				if (resolveRequest === void 0) return decision.response;
+				job.faultAnswer = decision.response;
+				return answeredOutsideCore();
+			}
+			if (!streamed) return planned();
+			if (decision.kind === "truncate") return streamedResponse(planned.answer, decision.after);
+			planned.commit();
+			return streamedResponse(planned.answer, void 0);
+		} catch {
+			return handlerFailedResponse();
+		}
+	};
+	const core = await createCore(dispatch);
+	let baseline = config.initial;
+	let entries = [];
+	let faultStates = [];
+	let nextSeq = 1;
+	let nextFaultId = 1;
+	let closed = false;
+	const clearLedger = () => {
+		entries = [];
+		nextSeq = 1;
+	};
+	/** Why a fault's `match.route` could never match (it names no manifest row), or `undefined`. */
+	const matchRouteProblem = (fault) => {
+		const route = fault.match?.route;
+		return route === void 0 || manifestPaths.has(route) ? void 0 : "match.route must name a manifest row of this emulator";
+	};
+	const addFault = (input) => {
+		const decoded = chunkFaults ? decodeStreamFault(input) : decodeFault(input);
+		if (Result.isFailure(decoded)) return issueMessage(decoded.failure.issue);
+		const problem = matchRouteProblem(decoded.success);
+		if (problem !== void 0) return problem;
+		const state = {
+			id: nextFaultId++,
+			fault: decoded.success,
+			remaining: decoded.success.count,
+			applied: 0
+		};
+		faultStates.push(state);
+		return snapshotFault(state);
+	};
+	const takeFault = (method, path, route) => faultStates.find((state) => (state.remaining === void 0 || state.remaining > 0) && faultMatches(state.fault, method, path, route));
+	const spend = (state) => {
+		state.applied += 1;
+		if (state.remaining !== void 0) state.remaining -= 1;
+	};
+	/** Build the fault's response first: a response that cannot be built must not consume it. */
+	const applyFault = (state, fault) => {
+		const headers = new Headers(fault.headers ?? {});
+		const body = fault.body ?? faultBody(fault.status);
+		if (!headers.has("content-type")) headers.set("content-type", Predicate.isString(body) ? "text/plain" : "application/json");
+		const response = new Response(Predicate.isString(body) ? body : JSON.stringify(body), {
+			status: fault.status,
+			headers
+		});
+		spend(state);
+		return response;
+	};
+	const reset = async () => {
+		clearLedger();
+		faultStates = [];
+		config.clearRuntime();
+		await core.restore(baseline);
+	};
+	const reseed = async (input) => {
+		const next = config.buildSeed(input);
+		if (Predicate.isString(next)) return next;
+		await core.restore(next);
+		config.clearRuntime();
+		baseline = next;
+		return next;
+	};
+	const coverage = () => ({
+		routes: manifest.map((route) => ({
+			...route,
+			requests: entries.filter((entry) => entry.route === route.path && (variantRows.has(route.path) || entry.method.toUpperCase() === route.method)).length
+		})),
+		unknownRouteRequests: entries.filter((entry) => entry.evidence === "unknown-route").length,
+		notEmulatedRequests: entries.filter((entry) => entry.notEmulated !== void 0).length
+	});
+	/** The ledgered 400; the reason is scrubbed of the request's guarded secrets first. */
+	const refuse = (entry, reason, secrets = []) => {
+		const safe = scrubSecrets(reason, secrets);
+		entry.notEmulated = safe;
+		return notEmulatedResponse(safe);
+	};
+	/**
+	* Fail-closed mode: the constant reason when any part of a recognised request repeats a guarded
+	* secret, or `undefined`. Checked, each through the fixpoint closure of `textRepeatsSecret` (a
+	* capped closure counts as a repeat): the raw path and every path segment, the raw query and
+	* every decoded query key and value, every recorded header, and the body.
+	*/
+	const credentialRepeat = (request, url, body, secrets, binding) => {
+		if (textRepeatsSecret(url.pathname, secrets) || url.pathname.split("/").some((segment) => textRepeatsSecret(segment, secrets))) return "the request path repeats the credential";
+		if (textRepeatsSecret(url.search, secrets) || [...url.searchParams].some(([key, value]) => textRepeatsSecret(key, secrets) || textRepeatsSecret(value, secrets))) return "the query repeats the credential";
+		if (config.recordHeaders.some((recorded) => textRepeatsSecret(request.headers.get(recorded.name) ?? "", secrets))) return "a recorded request header repeats the credential";
+		if (config.guardAllHeaders === true) {
+			const headers = [];
+			request.headers.forEach((value, name) => {
+				if (name !== "authorization") headers.push(name, value);
+			});
+			if (headers.some((text) => textRepeatsSecret(text, secrets))) return "a request header repeats the credential";
+		}
+		if (body === void 0) return void 0;
+		const repeat = "the request body repeats the credential";
+		if (textRepeatsSecret(body, secrets)) return repeat;
+		const { decodedViews, viewRefusalReasons = [] } = binding;
+		const views = Result.try(() => decodedViews === void 0 ? [] : decodedViews(body));
+		if (Result.isFailure(views)) {
+			const refusal = views.failure;
+			if (!(refusal instanceof DecodedViewRefusal)) return uncheckableBodyReason;
+			if (refusal.decoded.some((view) => textRepeatsSecret(view, secrets))) return repeat;
+			return viewRefusalReasons.includes(refusal.reason) ? scrubSecrets(refusal.reason, secrets) : uncheckableBodyReason;
+		}
+		return views.success.some((view) => textRepeatsSecret(view, secrets)) ? repeat : void 0;
+	};
+	/** Everything after the route match: credential, headers, body, shape, then the core. */
+	const routed = async (request, url, entry, matched, secrets, arrivedOn, recorded, guardedPath) => {
+		const header = (name) => isCredentialHeaderName(name) || guardedPath !== void 0 && name.toLowerCase() !== "content-type" ? void 0 : request.headers.get(name) ?? void 0;
+		const refused = (reason) => refuse(entry, reason, secrets);
+		let resolvedBody;
+		if (guardedPath !== void 0) {
+			const partsRepeat = partsCredentialRepeat(url, guardedPath, secrets);
+			if (partsRepeat !== void 0) return refused(partsRepeat);
+			resolvedBody = { bytes: await readBytes(request) };
+			const bodyRepeat = bodyCredentialRepeat(resolvedBody.bytes === void 0 ? void 0 : bodyText(resolvedBody.bytes), secrets);
+			if (bodyRepeat !== void 0) return refused(bodyRepeat);
+		} else if (config.failClosed === void 0) {
+			if (!bearerPattern.test(request.headers.get("authorization") ?? "")) return refused("a non-empty Authorization: Bearer credential is required");
+		} else {
+			if (secrets.length === 0) return refused(missingBearerReason);
+			if (hasEmptyQueryComponent(request.url)) return refused("empty query components (a bare ? or a stray &) are not emulated");
+		}
+		const problem = config.requestProblem?.(header);
+		if (problem !== void 0) return refused(problem);
+		const resolvedText = () => resolvedBody?.bytes === void 0 ? void 0 : bodyText(resolvedBody.bytes);
+		let json;
+		let bytes;
+		switch (matched.route.body) {
+			case "none": {
+				const text = resolvedBody === void 0 ? await readText(request) : resolvedText();
+				if (text === void 0 || text !== "") return refused("this route takes no request body");
+				break;
+			}
+			case "json": {
+				const text = resolvedBody === void 0 ? await readText(request) : resolvedText();
+				if (mediaType(header("content-type")) !== "application/json") return refused("this route takes a content-type: application/json body");
+				const parsed = text === void 0 ? void 0 : parseJsonText(text);
+				if (parsed === void 0) return refused("the request body is not valid JSON");
+				if (config.uniqueJsonKeys === true && text !== void 0 && repeatsJsonKey(text)) return refused("a JSON body with a repeated key is not emulated");
+				recorded.body = redactCredentialFields(parsed);
+				if (!constantRefusals) entry.body = recorded.body;
+				json = parsed;
+				break;
+			}
+			case "json-or-empty": {
+				const text = resolvedBody === void 0 ? await readText(request) : resolvedText();
+				if (text === void 0) return refused("the request body is unreadable");
+				if (text === "") break;
+				const parsed = parseJsonText(text);
+				if (parsed === void 0) return refused("the request body is not JSON");
+				if (config.uniqueJsonKeys === true && repeatsJsonKey(text)) return refused("a JSON body with a repeated key is not emulated");
+				recorded.body = redactCredentialFields(parsed);
+				if (!constantRefusals) entry.body = recorded.body;
+				json = parsed;
+				break;
+			}
+			case "bytes":
+				bytes = resolvedBody === void 0 ? await readBytes(request) : resolvedBody.bytes;
+				if (bytes === void 0) return refused("the request body is unreadable");
+				recorded.bodyBytes = bytes.byteLength;
+				if (!constantRefusals) entry.bodyBytes = recorded.bodyBytes;
+				break;
+		}
+		let bearerDigest;
+		const [bearer] = secrets;
+		if (config.bearerDigest !== void 0 && bearer !== void 0) {
+			const digest = Result.try(() => config.bearerDigest?.(bearer, arrivedOn));
+			if (Result.isFailure(digest) || !Predicate.isString(digest.success) || textRepeatsSecret(digest.success, secrets)) {
+				entry.responseError = "the bearer digest failed";
+				return emulatorError(500, errorTexts.failed);
+			}
+			bearerDigest = digest.success;
+		}
+		const admitted = matched.route.admit({
+			method: request.method.toUpperCase(),
+			path: guardedPath === void 0 ? url.pathname : entry.path,
+			params: matched.params,
+			query: url.searchParams,
+			rawQuery: rawQuery(request.url) ?? "",
+			header,
+			headerNames: guardedPath === void 0 ? [...request.headers.keys()] : [],
+			json,
+			bytes,
+			bearerDigest
+		}, config.env);
+		if (isNotEmulated(admitted)) return refused(admitted.reason);
+		const variants = matched.route.variants;
+		const variant = admitted.variant;
+		if (variants === void 0 ? variant !== void 0 : !variants.some((row) => row.path === variant)) {
+			entry.responseError = "the route admitted the request as no row of its manifest";
+			return emulatorError(500, errorTexts.failed);
+		}
+		if (variant !== void 0) entry.route = variant;
+		if (constantRefusals) {
+			entry.method = recorded.method;
+			entry.path = recorded.path;
+			entry.query = recorded.query;
+			entry.headers = recorded.headers;
+			if (recorded.body !== void 0) entry.body = recorded.body;
+			if (recorded.bodyBytes !== void 0) entry.bodyBytes = recorded.bodyBytes;
+		}
+		const method = request.method.toUpperCase();
+		const jobId = nextJobId++;
+		const requestPath = guardedPath === void 0 ? url.pathname : entry.path;
+		const job = {
+			admission: admitted,
+			seq: entry.seq,
+			secrets,
+			decideFault: (chunks) => {
+				const state = takeFault(method, requestPath, entry.route);
+				if (state === void 0) return { kind: "none" };
+				const fault = state.fault;
+				if (fault.kind === "status") {
+					const response = applyFault(state, fault);
+					entry.fault = "status";
+					return {
+						kind: "answer",
+						response
+					};
+				}
+				if (chunks === void 0 || fault.chunks >= chunks) {
+					entry.responseError = `emulator fault cannot apply: truncate-after-chunks after ${fault.chunks} chunk(s) needs a streamed answer of more chunks`;
+					return {
+						kind: "answer",
+						response: emulatorError(500, "emulator fault cannot apply")
+					};
+				}
+				spend(state);
+				entry.fault = "truncate-after-chunks";
+				return {
+					kind: "truncate",
+					after: fault.chunks
+				};
+			}
+		};
+		jobs.set(jobId, job);
+		try {
+			const response = await core.fetch(new Request(new URL(requestPath, core.baseUrl), {
+				method: "POST",
+				headers: { [emulatorJobHeader]: String(jobId) }
+			}));
+			if (response.headers.has("x-emulator-handler-failed")) {
+				entry.responseError = "the route handler failed";
+				return emulatorError(500, errorTexts.failed);
+			}
+			if (guardedPath !== void 0 && job.dispatched !== true) {
+				entry.responseError = "the route handler answered no eligibility verdict";
+				return emulatorError(500, errorTexts.failed);
+			}
+			if (job.notEmulated !== void 0) {
+				entry.notEmulated = job.notEmulated;
+				if (constantRefusals || job.credentialRepeat === true) blankEntry(entry);
+				if (job.credentialRepeat === true) entry.route = matched.route.path;
+				if (guardedPath !== void 0) return notEmulatedResponse(job.notEmulated);
+			}
+			return job.faultAnswer ?? response;
+		} finally {
+			jobs.delete(jobId);
+		}
+	};
+	/**
+	* Fail closed: an unrecognised request is ledgered and answered with constant text only. `method`
+	* is the request method upper-cased (fail-closed mode) or as sent (resolved mode).
+	*/
+	const unrecognised = (method, reason) => {
+		entries.push({
+			seq: nextSeq++,
+			method: unrecognisedMethod(method),
+			path: unrecognisedLedgerPath,
+			query: {},
+			headers: {},
+			status: 400,
+			evidence: "unknown-route",
+			notEmulated: reason
+		});
+		return notEmulatedResponse(reason);
+	};
+	const emulatedApi = async (request, url, arrivedOn) => {
+		const resolution = resolveRequest?.(request, url);
+		if (resolution?.kind === "unrecognised") return unrecognised(request.method, resolution.reason);
+		const matched = resolution === void 0 ? match(request.method, url.pathname) : {
+			route: resolution.route,
+			params: resolution.kind === "route" ? resolution.params : {}
+		};
+		const failClosed = config.failClosed;
+		let secrets = resolution?.secrets ?? [];
+		if (failClosed !== void 0) {
+			const authorization = request.headers.get("authorization");
+			const bearer = recognisableBearer(authorization);
+			if (authorization !== null && bearer === void 0) return unrecognised(request.method.toUpperCase(), failClosed.unrecognisedAuthorization);
+			if (matched === void 0) return unrecognised(request.method.toUpperCase(), failClosed.unrecognised);
+			secrets = bearer === void 0 ? [] : [bearer];
+			if (secrets.length > 0) {
+				const reason = credentialRepeat(request, url, request.body === null ? void 0 : await readText(request.clone()), secrets, matched.route);
+				if (reason !== void 0) {
+					entries.push({
+						seq: nextSeq++,
+						method: unrecognisedMethod(request.method.toUpperCase()),
+						path: unrecognisedLedgerPath,
+						route: matched.route.path,
+						query: {},
+						headers: {},
+						status: 400,
+						evidence: matched.route.evidence,
+						notEmulated: reason
+					});
+					return withEvidence(notEmulatedResponse(reason), matched.route.evidence);
+				}
+			}
+		}
+		const scrub = (text) => scrubSecrets(text, secrets);
+		const query = failClosed === void 0 ? Object.fromEntries(Object.entries(resolution === void 0 ? recordedQuery(url.searchParams) : redactCredentialQuery(url.searchParams)).map(([key, value]) => [scrub(key), scrub(value)])) : recordedQueryPairs(url.searchParams, scrub);
+		const recorded = {
+			method: scrub(request.method),
+			path: scrub(resolution?.ledgerPath ?? url.pathname),
+			query,
+			headers: {}
+		};
+		for (const header of config.recordHeaders) {
+			const value = request.headers.get(header.name);
+			if (value === null) continue;
+			const text = recordedHeaderValue(header, value);
+			recorded.headers[header.name] = scrub(failClosed === void 0 ? text : recordedJsonLooking(text));
+		}
+		const evidence = matched?.route.evidence ?? "unknown-route";
+		const entry = constantRefusals ? {
+			seq: nextSeq++,
+			method: unrecognisedMethod(request.method.toUpperCase()),
+			path: unrecognisedLedgerPath,
+			query: {},
+			headers: {},
+			status: 0,
+			evidence
+		} : resolution === void 0 ? {
+			seq: nextSeq++,
+			method: recorded.method,
+			path: recorded.path,
+			query: recorded.query,
+			headers: { ...recorded.headers },
+			status: 0,
+			evidence
+		} : {
+			seq: nextSeq++,
+			method: recorded.method,
+			path: recorded.path,
+			route: resolution.route.path,
+			query: recorded.query,
+			headers: { ...recorded.headers },
+			status: 0,
+			evidence
+		};
+		entries.push(entry);
+		if (matched === void 0) {
+			entry.status = 400;
+			return refuse(entry, "no emulated route for this method and path");
+		}
+		entry.route = matched.route.path;
+		if (matched.route.origin !== void 0 && matched.route.origin !== arrivedOn) {
+			entry.status = 400;
+			return withEvidence(refuse(entry, `this route is recorded on ${matched.route.origin} only`, secrets), matched.route.evidence);
+		}
+		if (resolution?.kind === "refused") {
+			const tagged = withEvidence(refuse(entry, resolution.reason, secrets), resolution.route.evidence);
+			entry.status = tagged.status;
+			return tagged;
+		}
+		const guardedPath = resolution?.guardedPath;
+		const tagged = withEvidence(await routed(request, url, entry, matched, secrets, arrivedOn, recorded, guardedPath).catch(() => {
+			entry.responseError = "the emulator could not build or produce the response";
+			return emulatorError(500, errorTexts.failed);
+		}), matched.route.evidence);
+		entry.status = tagged.status;
+		return tagged;
+	};
+	const controlPlane = async (request, path) => {
+		const method = request.method;
+		const allow = (methods) => emulatorError(405, "method not allowed", { allow: methods });
+		const jsonBody = async () => {
+			const text = await readText(request);
+			return text === void 0 ? void 0 : parseJsonText(text);
+		};
+		switch (path) {
+			case "/_emulate/ledger":
+				if (method === "GET") return jsonResponse(200, { entries: entries.map(snapshotLedgerEntry) });
+				if (method === "DELETE") {
+					const cleared = entries.length;
+					clearLedger();
+					return jsonResponse(200, { cleared });
+				}
+				return allow("GET, DELETE");
+			case "/_emulate/faults": {
+				if (method === "GET") return jsonResponse(200, { faults: faultStates.map(snapshotFault) });
+				if (method === "DELETE") {
+					const cleared = faultStates.length;
+					faultStates = [];
+					return jsonResponse(200, { cleared });
+				}
+				if (method !== "POST") return allow("GET, POST, DELETE");
+				const input = await jsonBody();
+				const decoded = chunkFaults ? decodeStreamFaultList(input) : decodeFaultList(input);
+				if (Result.isFailure(decoded)) return emulatorError(400, `invalid fault: ${issueMessage(decoded.failure.issue)}`);
+				const faults = "faults" in decoded.success ? decoded.success.faults : [decoded.success];
+				const problem = faults.map(matchRouteProblem).find(Predicate.isString);
+				if (problem !== void 0) return emulatorError(400, `invalid fault: ${problem}`);
+				return jsonResponse(201, { faults: faults.map((fault) => addFault(fault)) });
+			}
+			case "/_emulate/reset":
+				if (method !== "POST") return allow("POST");
+				await reset();
+				return jsonResponse(200, { reset: true });
+			case "/_emulate/state":
+				if (method !== "GET") return allow("GET");
+				return jsonResponse(200, {
+					state: core.snapshot(),
+					...config.runtimeState(),
+					faults: faultStates.map(snapshotFault),
+					ledgerEntries: entries.length
+				});
+			case "/_emulate/seed": {
+				if (method !== "POST") return allow("POST");
+				const next = await reseed(await jsonBody() ?? null);
+				if (Predicate.isString(next)) return emulatorError(400, `invalid seed: ${next}`);
+				return jsonResponse(200, {
+					seeded: true,
+					...config.seedSummary(next)
+				});
+			}
+			case "/_emulate/coverage":
+				if (method !== "GET") return allow("GET");
+				return jsonResponse(200, coverage());
+			default: return emulatorError(404, "unknown control-plane route");
+		}
+	};
+	/**
+	* Last resort when handling itself fails (for example an unparseable request URL): a 500
+	* emulator error, tagged with the matched route's evidence when there is one (in resolved mode,
+	* whose own resolution may be what failed, never).
+	*/
+	const lastResort = (request) => {
+		const path = URL.canParse(request.url) ? new URL(request.url).pathname : void 0;
+		const failed = emulatorError(500, errorTexts.unhandled);
+		if (path === void 0 || isControlPath(path) || resolveRequest !== void 0) return failed;
+		const matched = match(request.method, path);
+		return matched === void 0 ? failed : withEvidence(failed, matched.route.evidence);
+	};
+	const handle = async (request, origin) => {
+		if (closed) return emulatorError(503, errorTexts.closed);
+		const url = new URL(request.url);
+		return isControlPath(url.pathname) ? controlPlane(request, url.pathname) : emulatedApi(request, url, origin ?? url.origin);
+	};
+	const fetchOn = (origin) => (request) => handle(request, origin).catch(() => lastResort(request));
+	return {
+		fetch: fetchOn(void 0),
+		fetchOn: (origin) => fetchOn(origin),
+		ledger: {
+			entries: () => entries.map(snapshotLedgerEntry),
+			clear: clearLedger
+		},
+		faults: {
+			add: (fault) => {
+				const added = addFault(fault);
+				if (Predicate.isString(added)) throw config.inputInvalid("fault", added);
+				return added;
+			},
+			list: () => faultStates.map(snapshotFault),
+			clear: () => {
+				faultStates = [];
+			}
+		},
+		reset,
+		seed: async (input) => {
+			const next = await reseed(input);
+			if (Predicate.isString(next)) throw config.inputInvalid("seed", next);
+		},
+		snapshot: () => core.snapshot(),
+		coverage,
+		close: () => {
+			closed = true;
+			return core.close();
+		}
+	};
+};
+/** The fault states of an emulator without truncation faults (its decoder takes status faults). */
+const statusFaultStates = (states) => states.flatMap((state) => {
+	const fault = state.fault;
+	return fault.kind === "status" ? [{
+		...state,
+		fault
+	}] : [];
+});
+/** The API of an emulator without truncation faults: its fault methods take status faults only. */
+const withStatusFaults = (api, inputInvalid) => ({
+	...api,
+	faults: {
+		add: (fault) => {
+			const [added] = statusFaultStates([api.faults.add(fault)]);
+			if (added === void 0) throw inputInvalid("fault", "a status fault is required");
+			return added;
+		},
+		list: () => statusFaultStates(api.faults.list()),
+		clear: api.faults.clear
+	}
+});
+/**
+* Build the wrapper over a core runtime. `createCore` receives the dispatch the core must run for
+* every request (its only route) and returns the runtime adapter. Faults are status faults only.
+*/
+const makeStatefulEmulator = async (config, createCore) => withStatusFaults(await buildStatefulEmulator(config, createCore, false, snapshotEntry), config.inputInvalid);
+/**
+* `makeStatefulEmulator` for an emulator that records no request header (opt-in): it takes no
+* `recordHeaders`, and its ledger entries carry no `headers` field
+* (`StatefulHeaderlessLedgerEntry`). Faults are status faults only.
+*/
+const makeHeaderlessStatefulEmulator = async (config, createCore) => withStatusFaults(await buildStatefulEmulator({
+	...config,
+	recordHeaders: []
+}, createCore, false, snapshotHeaderlessEntry), config.inputInvalid);
+/**
+* `makeStatefulEmulator` that also takes `truncate-after-chunks` faults
+* (`StatefulTruncateFault`), which cut a streamed answer (`StreamedCommit`). Opt-in: the other
+* emulators keep status faults only.
+*/
+const makeChunkedStatefulEmulator = (config, createCore) => buildStatefulEmulator(config, createCore, true, snapshotEntry);
+/** Throws `inputInvalid('option', ...)` unless every drill knob is a known boolean (or absent). */
+const checkBooleanDrills = (drills, knobs, inputInvalid) => {
+	for (const [key, value] of Object.entries(drills ?? {})) {
+		if (!knobs.includes(key)) throw inputInvalid("option", `unknown drill knob ${key}`);
+		if (value !== void 0 && !Predicate.isBoolean(value)) throw inputInvalid("option", `drills.${key} must be a boolean`);
+	}
+};
+//#endregion
+export { DecodedViewRefusal, NotEmulated, StatefulFault, StatefulFaultMatch, StatefulStreamFault, StatefulTruncateFault, checkBooleanDrills, decodeSegment, exactBodyKeys, exactObject, exactQuery, integerIn, isJsonObject, isNotEmulated, jsonResponse, makeChunkedStatefulEmulator, makeHeaderlessStatefulEmulator, makeStatefulEmulator, mediaType, notEmulated, notEmulatedResponse, parseJsonText, repeatsJsonKey, routeEvidence, routeManifest, routeMatcher, statefulRoute, streamedCommit, unpatternedParams };
+
+//# sourceMappingURL=stateful-emulator.mjs.map