@yolk-sdk/emulators 0.1.0-canary.96

package/dist/mcp.d.mts

@@ -0,0 +1,84 @@
+import { EmulatorEvidence, EmulatorRouteEvidence, emulatorEvidenceHeader } from "./route-evidence.mjs";
+import { StatefulCoverage, StatefulEmulatorApi, StatefulFaultMatch, StatefulFaultState, StatefulInputKind, StatefulLedgerEntry, StatefulStreamFault } from "./stateful-emulator.mjs";
+import { McpRecordedExchange, McpRecordedFixture, McpRecordedRequest, McpRecordedResponse, mcpEmulatorFixtures } from "./mcp/recordings.mjs";
+import { McpEmulatorModernListing, McpEmulatorSeed, McpEmulatorSession, McpEmulatorState, McpEmulatorStateSchema, mcpEmulatorLegacyPath, mcpEmulatorModernPath, mcpEmulatorOrigin, mcpEmulatorReservedInvalidCredential, mcpEmulatorSessionCap, mcpEmulatorSessionPrefix } from "./mcp/state.mjs";
+import { McpEmulatorDrills, isMcpEmulatedRequestId, mcpEmulatorDrillKnobs } from "./mcp/api.mjs";
+
+//#region src/mcp.d.ts
+/**
+ * Route evidence manifest: one `RPC <origin><path>#<method>` row per recorded JSON-RPC method of
+ * each profile, plus the legacy `GET` row, with the conformance cases whose (synthetic,
+ * unverified) fixtures each answers. No row writes anything. Kept in sync with the handlers by
+ * construction (both come from one route table).
+ */
+declare const mcpEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence>;
+/**
+ * Optional fault filter; an omitted field matches every request. `method` is the HTTP method
+ * (`POST` or `GET`, never a row's `RPC`); `path` is the raw request path (ending in `*`, a
+ * prefix); `route` is a manifest row path (for example
+ * `https://mcp.example.test/legacy/mcp#tools/list`), and a value naming no row is rejected when
+ * the fault is added.
+ */
+declare const McpFaultMatch: import("effect/Schema").Struct<{
+  readonly method: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+  readonly path: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+  readonly route: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+}>;
+type McpFaultMatch = typeof StatefulFaultMatch.Type;
+/**
+ * A status fault (400-599), or a `truncate-after-chunks` fault that sends the first `chunks`
+ * chunks of the prepared answer and then ends it cleanly (an SSE answer has two chunks, a JSON
+ * answer one). Only a request the emulator would answer reaches a fault: a request that is not
+ * emulated, by its shape or by the state, never uses one up. A faulted request writes nothing (a
+ * truncated `initialize` mints no session; a truncated first page issues no cursor). A truncation
+ * that cannot apply answers 500 and is not used up.
+ */
+declare const McpFault: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+  readonly kind: import("effect/Schema").Literal<"status">;
+  readonly status: import("effect/Schema").Int;
+  readonly headers: import("effect/Schema").optionalKey<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").String>>;
+  readonly body: import("effect/Schema").optionalKey<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>;
+  readonly match: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+    readonly method: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    readonly path: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    readonly route: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+  }>>;
+  readonly count: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+}>, import("effect/Schema").Struct<{
+  readonly kind: import("effect/Schema").Literal<"truncate-after-chunks">;
+  readonly chunks: import("effect/Schema").Int;
+  readonly match: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+    readonly method: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    readonly path: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    readonly route: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+  }>>;
+  readonly count: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+}>]>;
+type McpFault = StatefulStreamFault;
+type McpFaultState = StatefulFaultState<McpFault>;
+type McpLedgerEntry = StatefulLedgerEntry;
+type McpCoverage = StatefulCoverage;
+declare const McpEmulatorInputInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "McpEmulatorInputInvalid";
+} & Readonly<A>;
+/** Invalid emulator input from the JS API: a seed, a fault, or an option. A programmer error. */
+declare class McpEmulatorInputInvalid extends McpEmulatorInputInvalid_base<{
+  readonly input: StatefulInputKind;
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+type McpEmulatorOptions = {
+  /** Typed seed; defaults to the one-page modern listing (sessions are never seeded). */readonly seed?: McpEmulatorSeed; /** Drill knobs (tests only): make the emulator disagree with one conformance claim. */
+  readonly drills?: McpEmulatorDrills;
+};
+type McpEmulator = StatefulEmulatorApi<McpEmulatorState, McpEmulatorSeed, McpFault>;
+/**
+ * Create a stateful MCP emulator on the `@emulators/core` custom runtime. Each call has its own
+ * state, ledger, faults, and session counter. Rejects with `McpEmulatorInputInvalid` for an
+ * invalid seed or option. See `src/stateful-emulator.ts` for the request precedence.
+ */
+declare const makeMcpEmulator: (options?: McpEmulatorOptions) => Promise<McpEmulator>;
+//#endregion
+export { type EmulatorEvidence, type EmulatorRouteEvidence, McpCoverage, McpEmulator, type McpEmulatorDrills, McpEmulatorInputInvalid, McpEmulatorModernListing, McpEmulatorOptions, McpEmulatorSeed, McpEmulatorSession, type McpEmulatorState, McpEmulatorStateSchema, McpFault, McpFaultMatch, McpFaultState, McpLedgerEntry, type McpRecordedExchange, type McpRecordedFixture, type McpRecordedRequest, type McpRecordedResponse, emulatorEvidenceHeader, isMcpEmulatedRequestId, makeMcpEmulator, mcpEmulatorDrillKnobs, mcpEmulatorFixtures, mcpEmulatorLegacyPath, mcpEmulatorModernPath, mcpEmulatorOrigin, mcpEmulatorReservedInvalidCredential, mcpEmulatorRoutes, mcpEmulatorSessionCap, mcpEmulatorSessionPrefix };
+//# sourceMappingURL=mcp.d.mts.map

package/dist/mcp.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.mts","names":[],"sources":["../src/mcp.ts"],"mappings":";;;;;;;;;AA6KmE;AAUnE;;;cAVa,iBAAA,EAAmB,aAAa,CAAC,qBAAA;;;;;;;;cAUjC,aAAA,0BAAa,MAAA;EAAA;;;;KAEd,aAAA,UAAuB,kBAAA,CAAmB,IAAI;;;;AAAA;AAU1D;;;;cAAa,QAAA,0BAAQ,KAAA,mCAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;KAET,QAAA,GAAW,mBAAmB;AAAA,KAE9B,aAAA,GAAgB,kBAAkB,CAAC,QAAA;AAAA,KAEnC,cAAA,GAAiB,mBAAmB;AAAA,KAEpC,WAAA,GAAc,gBAAgB;AAAA,cAAA,4BAAA;;;;cAG7B,uBAAA,SAAgC,4BAAA;EAAA,SAClC,KAAA,EAAO,iBAAA;EAAA,SACP,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAAA,KAKH,kBAAA;kGAED,IAAA,GAAO,eAAA;WAEP,MAAA,GAAS,iBAAiB;AAAA;AAAA,KAGzB,WAAA,GAAc,mBAAA,CAAoB,gBAAA,EAAkB,eAAA,EAAiB,QAAA;;;;;;cAgBpE,eAAA,GAAyB,OAAA,GAAS,kBAAA,KAA0B,OAAA,CAAQ,WAAA"}

package/dist/mcp.mjs

@@ -0,0 +1,241 @@
+import { emulatorEvidenceHeader } from "./route-evidence.mjs";
+import { isRecognisableBearerValue } from "./stateful-secrets.mjs";
+import { StatefulFaultMatch, StatefulStreamFault, checkBooleanDrills, makeChunkedStatefulEmulator, routeManifest } from "./stateful-emulator.mjs";
+import { statefulCoreRuntime } from "./stateful-core.mjs";
+import { mcpEmulatorFixtures } from "./mcp/recordings.mjs";
+import { McpEmulatorModernListing, McpEmulatorSeed, McpEmulatorSession, McpEmulatorStateSchema, buildSeedState, decodeState, makeMcpRuntime, mcpBearerDigest, mcpEmulatorLegacyPath, mcpEmulatorModernPath, mcpEmulatorOrigin, mcpEmulatorReservedInvalidCredential, mcpEmulatorSessionCap, mcpEmulatorSessionPrefix } from "./mcp/state.mjs";
+import { isMcpEmulatedRequestId, mcpApiRoutes, mcpEmulatorDrillKnobs, mcpRecordingProblems } from "./mcp/api.mjs";
+import { Data, Predicate } from "effect";
+//#region src/mcp.ts
+/**
+* Stateful MCP emulator (the two synthetic servers of the MCP conformance fixtures: profile
+* `synthetic-modern` on `https://mcp.example.test/modern/mcp`, stateless `2026-07-28` with JSON
+* answers, and profile `synthetic-legacy` on `https://mcp.example.test/legacy/mcp`, an
+* `initialize` handshake with sessions and SSE answers), built on the upstream `@emulators/core`
+* custom runtime, with a request ledger, status and truncation faults, and an `/_emulate/*`
+* control plane.
+*
+* It never imports SDK code: its answers are the sixteen synthetic `@yolk-sdk/mcp/conformance`
+* fixtures copied as data (`src/mcp/recordings.ts`), and every manifest row names the conformance
+* cases whose fixtures it answers (`mcpEmulatorRoutes`: one `RPC <origin><path>#<method>` row per
+* recorded JSON-RPC method of each profile, plus the legacy `GET` row; no row writes anything in a
+* real service). Response behaviour comes only from the fixtures, byte for byte: a JSON-RPC POST is
+* answered only when it equals a recorded request within the latitude below, with the recorded
+* answer, the request id substituted at exactly the recorded place (the top-level `id` of a JSON
+* answer, or the `id` of the SSE response event's payload; notification events and SSE `id:` lines
+* stay byte for byte; an answer that does not carry the recorded request id, such as the legacy era
+* probe's `id: null` error, is unchanged). The legacy `initialize` mints a session
+* `yolk-emu-session-<n>` (`n` from a counter that never resets, a form no seed holds), answered in
+* the recorded `mcp-session-id` header; `notifications/initialized` on that session answers the
+* recorded 202 and makes it ready; on a ready session `tools/list`, `tools/call`, and the standing
+* `GET` (the recorded 405) answer the recordings with the session's id. At most 256 sessions are
+* held: another `initialize` is refused before any fault. `reset` and `seed` clear the sessions.
+* The seed only selects which recorded modern listing `tools/list` answers (`modernListing`:
+* `one-page`, the default, or `two-pages`, whose first page issues the recorded cursor in the
+* generation that first issues it, and `<cursor>.g<generation>` after a reset or seed; the second
+* page answers only the cursor issued in the current generation). Every plan prepares its answer
+* before anything is written; its commit (minting a session, readying one, issuing a cursor) runs
+* only when no fault answers the request. Status faults (400-599) and `truncate-after-chunks`
+* faults apply only after a request is admitted and planned, and a faulted request writes nothing:
+* a truncation sends the prepared answer cut short and never runs the commit, so a truncated
+* `initialize` holds no session and leaves the counter and the cap where they were, and a truncated
+* first page issues no cursor. `match.route` selects one manifest row (a value naming no row is
+* rejected when the fault is added); `match.method` is the HTTP method. Anything else answers one
+* 400 not-emulated, ledgered with constant text only (`/<unrecognised>`, a standard method or
+* `<other>`, an empty query, no headers or body, a constant reason, and the route template or row),
+* that writes nothing and uses up no fault.
+*
+* Not emulated: `DELETE` (the client never sends it), `ping`, `resources/*`, `prompts/*`,
+* `logging/*`, `completion/*`, `tasks/*`, JSON-RPC batches and client-sent responses, a JSON body
+* repeating a key (the wrapper's opt-in `uniqueJsonKeys`), `mcp-*` headers no recording carries
+* (such as `mcp-param-*`), cursors this emulator did not issue, any other tool or arguments, any
+* other origin or path, and a missing `Authorization` (no fixture records the answer to one).
+*
+* Fail closed, on the shared wrapper's fail-closed mode as `/github`, `/google`, and
+* `/linkedin-search` use it, with its opt-in `constantRefusals`, `guardAllHeaders`, and
+* `guardOutput`: a request is recognised only on an emulated route shape, and any `Authorization`
+* header is exactly `Bearer <token>` with a recognisable bearer (the RFC 6750 `b64token` syntax, at
+* least 8 characters, a first character in `[G-Zg-z\-._~+/]` other than `n`, `r`, `t`, `u`, and a
+* character outside `[0-9.eE+-]`). A recognised request that repeats the bearer anywhere (its raw
+* path, the raw query or any query key or value, any request header name or value other than
+* `Authorization`, or its body, through the wrapper's fixpoint closure of tolerant percent-decoding
+* and JSON-unescaping, capped, where a cap refuses) is ledgered with constant text only. The
+* prepared output is checked the same way before any fault is decided or anything is committed: an
+* answer (every header and chunk) or a minted session id or cursor that would repeat the bearer is
+* refused with the constant credential-repeat entry, no fault used and nothing written, so a bearer
+* such as `yolk-emu-session-1`, or `synthetic-mcp` (inside the recorded `yolk-synthetic-mcp`),
+* never reaches a response, the state, or `/_emulate/*`. The bearer is never stored, forwarded,
+* ledgered, or echoed: routes see only its digest (the wrapper's opt-in `bearerDigest`; SHA-256 of
+* the origin, a space, and the bearer), which they compare only with the digest of the public
+* reserved invalid credential `yolk-conformance-invalid-credential-0000` (itself a recognisable
+* bearer) to answer its recorded 401 byte for byte. Scope: the bearer is never copied from the
+* request into a response, the state, or `/_emulate/*`; the output guard also refuses a prepared
+* fixture answer, minted session id, or cursor that happens to contain it, but the emulator's other
+* constants (state values such as `initializing`, wrapper headers such as `x-emulator-evidence`)
+* and host-configured control-plane data (a fault body) may coincidentally equal a bearer and are
+* not checked. `makeMcpEmulator` also throws when a copied recording is not canonical JSON (every
+* JSON body and SSE `data:` payload equal to `JSON.stringify(JSON.parse(text))`), which id
+* substitution relies on.
+*
+* Request-shape latitude (`/mcp`, the only accepted deviations): any bearer value in the RFC 6750
+* `b64token` syntax (`[A-Za-z0-9\-._~+/]+=*`) of at least 8 characters, starting with a character
+* in `[G-Zg-z\-._~+/]` other than `n`, `r`, `t`, `u`, with at least one outside `[0-9.eE+-]`, that
+* occurs nowhere else in the request (any header name or value included) and in no answer or value
+* the request would store (never stored or ledgered; only its digest is compared, with the digest
+* of the public reserved invalid credential `yolk-conformance-invalid-credential-0000`, which
+* answers the recorded 401 on the era probe); extra request headers, except `mcp-*` headers other
+* than `mcp-method`, `mcp-name`, `mcp-protocol-version`, and `mcp-session-id`; a recorded header
+* value sent as several headers that the HTTP layer joins into the recorded value; JSON key order;
+* any JSON-RPC request id that is an integer from 0 to 2^53 - 1 or 1 to 64 printable ASCII
+* characters where the recording has an id; any non-empty `name` and `version` (and no other key)
+* in the `_meta` client info (`io.modelcontextprotocol/clientInfo`) of a modern request; a session
+* id this emulator minted since the last reset or seed where the recording sends `mcp-session-id`
+* (initializing for `notifications/initialized`, ready otherwise); and, with the seed's `two-pages`
+* listing, the cursor this emulator issued in the current generation on the second page.
+* `Authorization` must be exactly `Bearer <token>` (that spelling, one space). Everything else
+* (another origin or path, any query, other HTTP methods such as `DELETE` or a `GET` on the modern
+* profile, JSON-RPC methods no fixture of the profile records such as `ping`, `resources/*`, or
+* `prompts/*`, batches and client-sent responses, other members, a JSON body repeating a key
+* (compared after unescaping), a `null`, negative, or fractional id, other params (other tools,
+* arguments, protocol versions, or capabilities, extra client-info keys, and a legacy `initialize`
+* client info other than the recorded one), the MCP headers `accept`, `content-type`, `mcp-method`,
+* `mcp-protocol-version`, `mcp-name`, and `last-event-id` other than the recorded values or present
+* where none is recorded, any other `mcp-*` header (such as `mcp-param-*`), `mcp-session-id`
+* missing where recorded or present where not, an unknown session or one in the wrong phase, a
+* cursor not issued in the current generation, the reserved invalid credential on anything but the
+* era probe, a bearer repeated anywhere in the request, and a bearer an answer or a minted session
+* id or cursor would repeat) is not emulated.
+*
+* Node-only: `@emulators/core` imports Node builtins, so the core is loaded lazily by
+* `makeMcpEmulator` (importing this module has no side effects).
+*
+* @experimental
+*/
+/**
+* Route evidence manifest: one `RPC <origin><path>#<method>` row per recorded JSON-RPC method of
+* each profile, plus the legacy `GET` row, with the conformance cases whose (synthetic,
+* unverified) fixtures each answers. No row writes anything. Kept in sync with the handlers by
+* construction (both come from one route table).
+*/
+const mcpEmulatorRoutes = mcpApiRoutes.flatMap(routeManifest);
+/**
+* Optional fault filter; an omitted field matches every request. `method` is the HTTP method
+* (`POST` or `GET`, never a row's `RPC`); `path` is the raw request path (ending in `*`, a
+* prefix); `route` is a manifest row path (for example
+* `https://mcp.example.test/legacy/mcp#tools/list`), and a value naming no row is rejected when
+* the fault is added.
+*/
+const McpFaultMatch = StatefulFaultMatch;
+/**
+* A status fault (400-599), or a `truncate-after-chunks` fault that sends the first `chunks`
+* chunks of the prepared answer and then ends it cleanly (an SSE answer has two chunks, a JSON
+* answer one). Only a request the emulator would answer reaches a fault: a request that is not
+* emulated, by its shape or by the state, never uses one up. A faulted request writes nothing (a
+* truncated `initialize` mints no session; a truncated first page issues no cursor). A truncation
+* that cannot apply answers 500 and is not used up.
+*/
+const McpFault = StatefulStreamFault;
+/** Invalid emulator input from the JS API: a seed, a fault, or an option. A programmer error. */
+var McpEmulatorInputInvalid = class extends Data.TaggedError("McpEmulatorInputInvalid") {
+	get message() {
+		return `Invalid MCP emulator ${this.input}: ${this.reason}`;
+	}
+};
+const inputInvalid = (input, reason) => new McpEmulatorInputInvalid({
+	input,
+	reason
+});
+/** The constant reason of a request on no emulated route shape. */
+const unrecognisedReason = "no emulated MCP route for this method and path";
+/** The constant reason of a request whose `Authorization` header is not one recognisable bearer. */
+const unrecognisedAuthorizationReason = "an unrecognisable Authorization header is not emulated";
+/**
+* Create a stateful MCP emulator on the `@emulators/core` custom runtime. Each call has its own
+* state, ledger, faults, and session counter. Rejects with `McpEmulatorInputInvalid` for an
+* invalid seed or option. See `src/stateful-emulator.ts` for the request precedence.
+*/
+const makeMcpEmulator = async (options = {}) => {
+	const initial = buildSeedState(options.seed ?? {});
+	if (Predicate.isString(initial)) throw inputInvalid("seed", initial);
+	checkBooleanDrills(options.drills, mcpEmulatorDrillKnobs, inputInvalid);
+	if (!isRecognisableBearerValue("yolk-conformance-invalid-credential-0000")) throw new Error("the reserved invalid MCP credential is not a recognisable bearer");
+	const recordingProblems = mcpRecordingProblems(mcpEmulatorFixtures);
+	if (recordingProblems.length > 0) throw new Error(`non-canonical MCP recordings: ${recordingProblems.join("; ")}`);
+	const drills = options.drills ?? {};
+	const runtime = makeMcpRuntime();
+	return makeChunkedStatefulEmulator({
+		routes: mcpApiRoutes,
+		env: {
+			drills: {
+				discoverCarriesErrorResponse: drills.discoverCarriesErrorResponse === true,
+				discoverWithoutResultType: drills.discoverWithoutResultType === true,
+				sessionIdNotVisibleAscii: drills.sessionIdNotVisibleAscii === true,
+				discoverAnsweredTwice: drills.discoverAnsweredTwice === true,
+				writeToolMarkedReadOnly: drills.writeToolMarkedReadOnly === true,
+				readCallAnswersToolError: drills.readCallAnswersToolError === true,
+				invalidCallAnswersRpcError: drills.invalidCallAnswersRpcError === true,
+				absentCallAnswersResult: drills.absentCallAnswersResult === true,
+				unauthorizedWithoutChallenge: drills.unauthorizedWithoutChallenge === true
+			},
+			reservedDigest: mcpBearerDigest(mcpEmulatorReservedInvalidCredential, mcpEmulatorOrigin),
+			runtime
+		},
+		initial,
+		buildSeed: buildSeedState,
+		recordHeaders: [
+			{
+				name: "accept",
+				json: false
+			},
+			{
+				name: "content-type",
+				json: false
+			},
+			{
+				name: "mcp-method",
+				json: false
+			},
+			{
+				name: "mcp-name",
+				json: false
+			},
+			{
+				name: "mcp-protocol-version",
+				json: false
+			},
+			{
+				name: "mcp-session-id",
+				json: false
+			}
+		],
+		failClosed: {
+			unrecognised: unrecognisedReason,
+			unrecognisedAuthorization: unrecognisedAuthorizationReason
+		},
+		bearerDigest: mcpBearerDigest,
+		constantRefusals: true,
+		guardAllHeaders: true,
+		guardOutput: true,
+		uniqueJsonKeys: true,
+		clearRuntime: () => {
+			runtime.generation += 1;
+			runtime.issuedCursor = void 0;
+		},
+		runtimeState: () => ({
+			nextSession: runtime.nextSession,
+			cursorGeneration: runtime.generation,
+			issuedCursor: runtime.issuedCursor ?? null
+		}),
+		seedSummary: (state) => ({ modernListing: state.modernListing }),
+		inputInvalid
+	}, statefulCoreRuntime({
+		name: "mcp",
+		initial,
+		decodeState,
+		inputInvalid
+	}));
+};
+//#endregion
+export { McpEmulatorInputInvalid, McpEmulatorModernListing, McpEmulatorSeed, McpEmulatorSession, McpEmulatorStateSchema, McpFault, McpFaultMatch, emulatorEvidenceHeader, isMcpEmulatedRequestId, makeMcpEmulator, mcpEmulatorDrillKnobs, mcpEmulatorFixtures, mcpEmulatorLegacyPath, mcpEmulatorModernPath, mcpEmulatorOrigin, mcpEmulatorReservedInvalidCredential, mcpEmulatorRoutes, mcpEmulatorSessionCap, mcpEmulatorSessionPrefix };
+
+//# sourceMappingURL=mcp.mjs.map

package/dist/mcp.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.mjs","names":[],"sources":["../src/mcp.ts"],"sourcesContent":["/**\n * Stateful MCP emulator (the two synthetic servers of the MCP conformance fixtures: profile\n * `synthetic-modern` on `https://mcp.example.test/modern/mcp`, stateless `2026-07-28` with JSON\n * answers, and profile `synthetic-legacy` on `https://mcp.example.test/legacy/mcp`, an\n * `initialize` handshake with sessions and SSE answers), built on the upstream `@emulators/core`\n * custom runtime, with a request ledger, status and truncation faults, and an `/_emulate/*`\n * control plane.\n *\n * It never imports SDK code: its answers are the sixteen synthetic `@yolk-sdk/mcp/conformance`\n * fixtures copied as data (`src/mcp/recordings.ts`), and every manifest row names the conformance\n * cases whose fixtures it answers (`mcpEmulatorRoutes`: one `RPC <origin><path>#<method>` row per\n * recorded JSON-RPC method of each profile, plus the legacy `GET` row; no row writes anything in a\n * real service). Response behaviour comes only from the fixtures, byte for byte: a JSON-RPC POST is\n * answered only when it equals a recorded request within the latitude below, with the recorded\n * answer, the request id substituted at exactly the recorded place (the top-level `id` of a JSON\n * answer, or the `id` of the SSE response event's payload; notification events and SSE `id:` lines\n * stay byte for byte; an answer that does not carry the recorded request id, such as the legacy era\n * probe's `id: null` error, is unchanged). The legacy `initialize` mints a session\n * `yolk-emu-session-<n>` (`n` from a counter that never resets, a form no seed holds), answered in\n * the recorded `mcp-session-id` header; `notifications/initialized` on that session answers the\n * recorded 202 and makes it ready; on a ready session `tools/list`, `tools/call`, and the standing\n * `GET` (the recorded 405) answer the recordings with the session's id. At most 256 sessions are\n * held: another `initialize` is refused before any fault. `reset` and `seed` clear the sessions.\n * The seed only selects which recorded modern listing `tools/list` answers (`modernListing`:\n * `one-page`, the default, or `two-pages`, whose first page issues the recorded cursor in the\n * generation that first issues it, and `<cursor>.g<generation>` after a reset or seed; the second\n * page answers only the cursor issued in the current generation). Every plan prepares its answer\n * before anything is written; its commit (minting a session, readying one, issuing a cursor) runs\n * only when no fault answers the request. Status faults (400-599) and `truncate-after-chunks`\n * faults apply only after a request is admitted and planned, and a faulted request writes nothing:\n * a truncation sends the prepared answer cut short and never runs the commit, so a truncated\n * `initialize` holds no session and leaves the counter and the cap where they were, and a truncated\n * first page issues no cursor. `match.route` selects one manifest row (a value naming no row is\n * rejected when the fault is added); `match.method` is the HTTP method. Anything else answers one\n * 400 not-emulated, ledgered with constant text only (`/<unrecognised>`, a standard method or\n * `<other>`, an empty query, no headers or body, a constant reason, and the route template or row),\n * that writes nothing and uses up no fault.\n *\n * Not emulated: `DELETE` (the client never sends it), `ping`, `resources/*`, `prompts/*`,\n * `logging/*`, `completion/*`, `tasks/*`, JSON-RPC batches and client-sent responses, a JSON body\n * repeating a key (the wrapper's opt-in `uniqueJsonKeys`), `mcp-*` headers no recording carries\n * (such as `mcp-param-*`), cursors this emulator did not issue, any other tool or arguments, any\n * other origin or path, and a missing `Authorization` (no fixture records the answer to one).\n *\n * Fail closed, on the shared wrapper's fail-closed mode as `/github`, `/google`, and\n * `/linkedin-search` use it, with its opt-in `constantRefusals`, `guardAllHeaders`, and\n * `guardOutput`: a request is recognised only on an emulated route shape, and any `Authorization`\n * header is exactly `Bearer <token>` with a recognisable bearer (the RFC 6750 `b64token` syntax, at\n * least 8 characters, a first character in `[G-Zg-z\\-._~+/]` other than `n`, `r`, `t`, `u`, and a\n * character outside `[0-9.eE+-]`). A recognised request that repeats the bearer anywhere (its raw\n * path, the raw query or any query key or value, any request header name or value other than\n * `Authorization`, or its body, through the wrapper's fixpoint closure of tolerant percent-decoding\n * and JSON-unescaping, capped, where a cap refuses) is ledgered with constant text only. The\n * prepared output is checked the same way before any fault is decided or anything is committed: an\n * answer (every header and chunk) or a minted session id or cursor that would repeat the bearer is\n * refused with the constant credential-repeat entry, no fault used and nothing written, so a bearer\n * such as `yolk-emu-session-1`, or `synthetic-mcp` (inside the recorded `yolk-synthetic-mcp`),\n * never reaches a response, the state, or `/_emulate/*`. The bearer is never stored, forwarded,\n * ledgered, or echoed: routes see only its digest (the wrapper's opt-in `bearerDigest`; SHA-256 of\n * the origin, a space, and the bearer), which they compare only with the digest of the public\n * reserved invalid credential `yolk-conformance-invalid-credential-0000` (itself a recognisable\n * bearer) to answer its recorded 401 byte for byte. Scope: the bearer is never copied from the\n * request into a response, the state, or `/_emulate/*`; the output guard also refuses a prepared\n * fixture answer, minted session id, or cursor that happens to contain it, but the emulator's other\n * constants (state values such as `initializing`, wrapper headers such as `x-emulator-evidence`)\n * and host-configured control-plane data (a fault body) may coincidentally equal a bearer and are\n * not checked. `makeMcpEmulator` also throws when a copied recording is not canonical JSON (every\n * JSON body and SSE `data:` payload equal to `JSON.stringify(JSON.parse(text))`), which id\n * substitution relies on.\n *\n * Request-shape latitude (`/mcp`, the only accepted deviations): any bearer value in the RFC 6750\n * `b64token` syntax (`[A-Za-z0-9\\-._~+/]+=*`) of at least 8 characters, starting with a character\n * in `[G-Zg-z\\-._~+/]` other than `n`, `r`, `t`, `u`, with at least one outside `[0-9.eE+-]`, that\n * occurs nowhere else in the request (any header name or value included) and in no answer or value\n * the request would store (never stored or ledgered; only its digest is compared, with the digest\n * of the public reserved invalid credential `yolk-conformance-invalid-credential-0000`, which\n * answers the recorded 401 on the era probe); extra request headers, except `mcp-*` headers other\n * than `mcp-method`, `mcp-name`, `mcp-protocol-version`, and `mcp-session-id`; a recorded header\n * value sent as several headers that the HTTP layer joins into the recorded value; JSON key order;\n * any JSON-RPC request id that is an integer from 0 to 2^53 - 1 or 1 to 64 printable ASCII\n * characters where the recording has an id; any non-empty `name` and `version` (and no other key)\n * in the `_meta` client info (`io.modelcontextprotocol/clientInfo`) of a modern request; a session\n * id this emulator minted since the last reset or seed where the recording sends `mcp-session-id`\n * (initializing for `notifications/initialized`, ready otherwise); and, with the seed's `two-pages`\n * listing, the cursor this emulator issued in the current generation on the second page.\n * `Authorization` must be exactly `Bearer <token>` (that spelling, one space). Everything else\n * (another origin or path, any query, other HTTP methods such as `DELETE` or a `GET` on the modern\n * profile, JSON-RPC methods no fixture of the profile records such as `ping`, `resources/*`, or\n * `prompts/*`, batches and client-sent responses, other members, a JSON body repeating a key\n * (compared after unescaping), a `null`, negative, or fractional id, other params (other tools,\n * arguments, protocol versions, or capabilities, extra client-info keys, and a legacy `initialize`\n * client info other than the recorded one), the MCP headers `accept`, `content-type`, `mcp-method`,\n * `mcp-protocol-version`, `mcp-name`, and `last-event-id` other than the recorded values or present\n * where none is recorded, any other `mcp-*` header (such as `mcp-param-*`), `mcp-session-id`\n * missing where recorded or present where not, an unknown session or one in the wrong phase, a\n * cursor not issued in the current generation, the reserved invalid credential on anything but the\n * era probe, a bearer repeated anywhere in the request, and a bearer an answer or a minted session\n * id or cursor would repeat) is not emulated.\n *\n * Node-only: `@emulators/core` imports Node builtins, so the core is loaded lazily by\n * `makeMcpEmulator` (importing this module has no side effects).\n *\n * @experimental\n */\nimport { Data, Predicate } from 'effect'\nimport {\n  mcpApiRoutes,\n  mcpEmulatorDrillKnobs,\n  mcpRecordingProblems,\n  type McpApiEnv,\n  type McpEmulatorDrills\n} from './mcp/api.ts'\nimport { mcpEmulatorFixtures } from './mcp/recordings.ts'\nimport {\n  buildSeedState,\n  decodeState,\n  makeMcpRuntime,\n  mcpBearerDigest,\n  mcpEmulatorOrigin,\n  mcpEmulatorReservedInvalidCredential,\n  type McpEmulatorSeed,\n  type McpEmulatorState\n} from './mcp/state.ts'\nimport type { EmulatorRouteEvidence } from './route-evidence.ts'\nimport {\n  StatefulFaultMatch,\n  StatefulStreamFault,\n  checkBooleanDrills,\n  makeChunkedStatefulEmulator,\n  routeManifest,\n  type StatefulCoverage,\n  type StatefulEmulatorApi,\n  type StatefulFaultState,\n  type StatefulInputKind,\n  type StatefulLedgerEntry\n} from './stateful-emulator.ts'\nimport { statefulCoreRuntime } from './stateful-core.ts'\nimport { isRecognisableBearerValue } from './stateful-secrets.ts'\n\nexport type { EmulatorEvidence, EmulatorRouteEvidence } from './route-evidence.ts'\n\nexport { emulatorEvidenceHeader } from './route-evidence.ts'\n\nexport { isMcpEmulatedRequestId, mcpEmulatorDrillKnobs, type McpEmulatorDrills } from './mcp/api.ts'\n\nexport {\n  McpEmulatorModernListing,\n  McpEmulatorSeed,\n  McpEmulatorSession,\n  McpEmulatorStateSchema,\n  mcpEmulatorLegacyPath,\n  mcpEmulatorModernPath,\n  mcpEmulatorOrigin,\n  mcpEmulatorReservedInvalidCredential,\n  mcpEmulatorSessionCap,\n  mcpEmulatorSessionPrefix,\n  type McpEmulatorState\n} from './mcp/state.ts'\n\nexport {\n  mcpEmulatorFixtures,\n  type McpRecordedExchange,\n  type McpRecordedFixture,\n  type McpRecordedRequest,\n  type McpRecordedResponse\n} from './mcp/recordings.ts'\n\n/**\n * Route evidence manifest: one `RPC <origin><path>#<method>` row per recorded JSON-RPC method of\n * each profile, plus the legacy `GET` row, with the conformance cases whose (synthetic,\n * unverified) fixtures each answers. No row writes anything. Kept in sync with the handlers by\n * construction (both come from one route table).\n */\nexport const mcpEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence> =\n  mcpApiRoutes.flatMap(routeManifest)\n\n/**\n * Optional fault filter; an omitted field matches every request. `method` is the HTTP method\n * (`POST` or `GET`, never a row's `RPC`); `path` is the raw request path (ending in `*`, a\n * prefix); `route` is a manifest row path (for example\n * `https://mcp.example.test/legacy/mcp#tools/list`), and a value naming no row is rejected when\n * the fault is added.\n */\nexport const McpFaultMatch = StatefulFaultMatch\n\nexport type McpFaultMatch = typeof StatefulFaultMatch.Type\n\n/**\n * A status fault (400-599), or a `truncate-after-chunks` fault that sends the first `chunks`\n * chunks of the prepared answer and then ends it cleanly (an SSE answer has two chunks, a JSON\n * answer one). Only a request the emulator would answer reaches a fault: a request that is not\n * emulated, by its shape or by the state, never uses one up. A faulted request writes nothing (a\n * truncated `initialize` mints no session; a truncated first page issues no cursor). A truncation\n * that cannot apply answers 500 and is not used up.\n */\nexport const McpFault = StatefulStreamFault\n\nexport type McpFault = StatefulStreamFault\n\nexport type McpFaultState = StatefulFaultState<McpFault>\n\nexport type McpLedgerEntry = StatefulLedgerEntry\n\nexport type McpCoverage = StatefulCoverage\n\n/** Invalid emulator input from the JS API: a seed, a fault, or an option. A programmer error. */\nexport class McpEmulatorInputInvalid extends Data.TaggedError('McpEmulatorInputInvalid')<{\n  readonly input: StatefulInputKind\n  readonly reason: string\n}> {\n  override get message(): string {\n    return `Invalid MCP emulator ${this.input}: ${this.reason}`\n  }\n}\n\nexport type McpEmulatorOptions = {\n  /** Typed seed; defaults to the one-page modern listing (sessions are never seeded). */\n  readonly seed?: McpEmulatorSeed\n  /** Drill knobs (tests only): make the emulator disagree with one conformance claim. */\n  readonly drills?: McpEmulatorDrills\n}\n\nexport type McpEmulator = StatefulEmulatorApi<McpEmulatorState, McpEmulatorSeed, McpFault>\n\nconst inputInvalid = (input: StatefulInputKind, reason: string) =>\n  new McpEmulatorInputInvalid({ input, reason })\n\n/** The constant reason of a request on no emulated route shape. */\nconst unrecognisedReason = 'no emulated MCP route for this method and path'\n\n/** The constant reason of a request whose `Authorization` header is not one recognisable bearer. */\nconst unrecognisedAuthorizationReason = 'an unrecognisable Authorization header is not emulated'\n\n/**\n * Create a stateful MCP emulator on the `@emulators/core` custom runtime. Each call has its own\n * state, ledger, faults, and session counter. Rejects with `McpEmulatorInputInvalid` for an\n * invalid seed or option. See `src/stateful-emulator.ts` for the request precedence.\n */\nexport const makeMcpEmulator = async (options: McpEmulatorOptions = {}): Promise<McpEmulator> => {\n  const initial = buildSeedState(options.seed ?? {})\n\n  if (Predicate.isString(initial)) {\n    throw inputInvalid('seed', initial)\n  }\n\n  checkBooleanDrills(options.drills, mcpEmulatorDrillKnobs, inputInvalid)\n\n  // The reserved invalid credential must reach the routes as a recognisable bearer's digest; a\n  // value the bearer rule refused would never be answered its recorded 401.\n  if (!isRecognisableBearerValue(mcpEmulatorReservedInvalidCredential)) {\n    throw new Error('the reserved invalid MCP credential is not a recognisable bearer')\n  }\n\n  // Id substitution re-serialises the response message: a recording copied in a non-canonical\n  // JSON form would answer other bytes, so it fails here, loudly.\n  const recordingProblems = mcpRecordingProblems(mcpEmulatorFixtures)\n\n  if (recordingProblems.length > 0) {\n    throw new Error(`non-canonical MCP recordings: ${recordingProblems.join('; ')}`)\n  }\n\n  const drills = options.drills ?? {}\n  const runtime = makeMcpRuntime()\n\n  const env: McpApiEnv = {\n    drills: {\n      discoverCarriesErrorResponse: drills.discoverCarriesErrorResponse === true,\n      discoverWithoutResultType: drills.discoverWithoutResultType === true,\n      sessionIdNotVisibleAscii: drills.sessionIdNotVisibleAscii === true,\n      discoverAnsweredTwice: drills.discoverAnsweredTwice === true,\n      writeToolMarkedReadOnly: drills.writeToolMarkedReadOnly === true,\n      readCallAnswersToolError: drills.readCallAnswersToolError === true,\n      invalidCallAnswersRpcError: drills.invalidCallAnswersRpcError === true,\n      absentCallAnswersResult: drills.absentCallAnswersResult === true,\n      unauthorizedWithoutChallenge: drills.unauthorizedWithoutChallenge === true\n    },\n    reservedDigest: mcpBearerDigest(mcpEmulatorReservedInvalidCredential, mcpEmulatorOrigin),\n    runtime\n  }\n\n  return makeChunkedStatefulEmulator<McpEmulatorState, McpApiEnv, McpEmulatorSeed>(\n    {\n      routes: mcpApiRoutes,\n      env,\n      initial,\n      buildSeed: buildSeedState,\n      recordHeaders: [\n        { name: 'accept', json: false },\n        { name: 'content-type', json: false },\n        { name: 'mcp-method', json: false },\n        { name: 'mcp-name', json: false },\n        { name: 'mcp-protocol-version', json: false },\n        { name: 'mcp-session-id', json: false }\n      ],\n      failClosed: {\n        unrecognised: unrecognisedReason,\n        unrecognisedAuthorization: unrecognisedAuthorizationReason\n      },\n      bearerDigest: mcpBearerDigest,\n      constantRefusals: true,\n      guardAllHeaders: true,\n      guardOutput: true,\n      uniqueJsonKeys: true,\n      // Every reset and seed starts a cursor generation; the session counter never resets.\n      clearRuntime: () => {\n        runtime.generation += 1\n        runtime.issuedCursor = undefined\n      },\n      runtimeState: () => ({\n        nextSession: runtime.nextSession,\n        cursorGeneration: runtime.generation,\n        issuedCursor: runtime.issuedCursor ?? null\n      }),\n      seedSummary: state => ({ modernListing: state.modernListing }),\n      inputInvalid\n    },\n    statefulCoreRuntime({ name: 'mcp', initial, decodeState, inputInvalid })\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6KA,MAAa,oBACX,aAAa,QAAQ,aAAa;;;;;;;;AASpC,MAAa,gBAAgB;;;;;;;;;AAY7B,MAAa,WAAW;;AAWxB,IAAa,0BAAb,cAA6C,KAAK,YAAY,yBAAyB,EAGpF;CACD,IAAa,UAAkB;EAC7B,OAAO,wBAAwB,KAAK,MAAM,IAAI,KAAK;CACrD;AACF;AAWA,MAAM,gBAAgB,OAA0B,WAC9C,IAAI,wBAAwB;CAAE;CAAO;AAAO,CAAC;;AAG/C,MAAM,qBAAqB;;AAG3B,MAAM,kCAAkC;;;;;;AAOxC,MAAa,kBAAkB,OAAO,UAA8B,CAAC,MAA4B;CAC/F,MAAM,UAAU,eAAe,QAAQ,QAAQ,CAAC,CAAC;CAEjD,IAAI,UAAU,SAAS,OAAO,GAC5B,MAAM,aAAa,QAAQ,OAAO;CAGpC,mBAAmB,QAAQ,QAAQ,uBAAuB,YAAY;CAItE,IAAI,CAAC,0BAAA,0CAA8D,GACjE,MAAM,IAAI,MAAM,kEAAkE;CAKpF,MAAM,oBAAoB,qBAAqB,mBAAmB;CAElE,IAAI,kBAAkB,SAAS,GAC7B,MAAM,IAAI,MAAM,iCAAiC,kBAAkB,KAAK,IAAI,GAAG;CAGjF,MAAM,SAAS,QAAQ,UAAU,CAAC;CAClC,MAAM,UAAU,eAAe;CAkB/B,OAAO,4BACL;EACE,QAAQ;EACR,KAAA;GAlBF,QAAQ;IACN,8BAA8B,OAAO,iCAAiC;IACtE,2BAA2B,OAAO,8BAA8B;IAChE,0BAA0B,OAAO,6BAA6B;IAC9D,uBAAuB,OAAO,0BAA0B;IACxD,yBAAyB,OAAO,4BAA4B;IAC5D,0BAA0B,OAAO,6BAA6B;IAC9D,4BAA4B,OAAO,+BAA+B;IAClE,yBAAyB,OAAO,4BAA4B;IAC5D,8BAA8B,OAAO,iCAAiC;GACxE;GACA,gBAAgB,gBAAgB,sCAAsC,iBAAiB;GACvF;EAMI;EACF;EACA,WAAW;EACX,eAAe;GACb;IAAE,MAAM;IAAU,MAAM;GAAM;GAC9B;IAAE,MAAM;IAAgB,MAAM;GAAM;GACpC;IAAE,MAAM;IAAc,MAAM;GAAM;GAClC;IAAE,MAAM;IAAY,MAAM;GAAM;GAChC;IAAE,MAAM;IAAwB,MAAM;GAAM;GAC5C;IAAE,MAAM;IAAkB,MAAM;GAAM;EACxC;EACA,YAAY;GACV,cAAc;GACd,2BAA2B;EAC7B;EACA,cAAc;EACd,kBAAkB;EAClB,iBAAiB;EACjB,aAAa;EACb,gBAAgB;EAEhB,oBAAoB;GAClB,QAAQ,cAAc;GACtB,QAAQ,eAAe,KAAA;EACzB;EACA,qBAAqB;GACnB,aAAa,QAAQ;GACrB,kBAAkB,QAAQ;GAC1B,cAAc,QAAQ,gBAAgB;EACxC;EACA,cAAa,WAAU,EAAE,eAAe,MAAM,cAAc;EAC5D;CACF,GACA,oBAAoB;EAAE,MAAM;EAAO;EAAS;EAAa;CAAa,CAAC,CACzE;AACF"}

package/dist/messages.d.mts

@@ -0,0 +1,183 @@
+import { EmulatorEvidence, EmulatorRouteEvidence } from "./route-evidence.mjs";
+import { EmulatorApi } from "./emulator-kernel.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/messages.d.ts
+/** An Anthropic wire error: `type` (for example `overloaded_error`) and a message. */
+declare const MessagesWireError: Schema.Struct<{
+  readonly type: Schema.NonEmptyString;
+  readonly message: Schema.String;
+}>;
+type MessagesWireError = typeof MessagesWireError.Type;
+/**
+ * Send `chunks` SSE events, then one `event: error` event (default `overloaded_error`) and close
+ * without `message_stop`. Streamed responses only; it must come before `message_stop`.
+ */
+declare const MessagesErrorEventFault: Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-event-after-chunks">;
+  readonly chunks: Schema.Int;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly type: Schema.NonEmptyString;
+    readonly message: Schema.String;
+  }>>;
+}>;
+/**
+ * Wire faults: `status` (the body defaults to an Anthropic error envelope matching the status,
+ * for example `rate_limit_error` for 429 and `overloaded_error` for 529), `error-after-chunks`
+ * (a dropped connection), `truncate-after-chunks` (a clean close, for example before
+ * `message_stop`), and `error-event-after-chunks` (a mid-stream `error` event).
+ */
+declare const MessagesFault: Schema.Union<readonly [Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"status">;
+  readonly status: Schema.Int;
+  readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"truncate-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-event-after-chunks">;
+  readonly chunks: Schema.Int;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly type: Schema.NonEmptyString;
+    readonly message: Schema.String;
+  }>>;
+}>]>;
+type MessagesFault = typeof MessagesFault.Type;
+type MessagesFaultKind = MessagesFault['kind'];
+/** Usage for a scripted turn (sent in `message_start` and `message_delta`). */
+declare const MessagesScriptedUsage: Schema.Struct<{
+  readonly inputTokens: Schema.Int;
+  readonly outputTokens: Schema.Int;
+}>;
+type MessagesScriptedUsage = typeof MessagesScriptedUsage.Type;
+/** One scripted `tool_use` block; its JSON input streams as these `input_json_delta` fragments. */
+declare const MessagesScriptedToolUse: Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly inputFragments: Schema.$Array<Schema.String>;
+  readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type MessagesScriptedToolUse = typeof MessagesScriptedToolUse.Type;
+/**
+ * A scripted message. Every field is exact (nothing is filled in) except: a block is sent only
+ * when its field is present; `usage` omitted is synthesized and `null` drops `usage` from the
+ * wire; `stopReason` omitted is `tool_use` with tool uses, else `end_turn`; `order` defaults to
+ * `thinking-first` (`text-first` sends the thinking block after the text).
+ */
+declare const MessagesScriptedMessage: Schema.Struct<{
+  readonly thinking: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly toolUses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly inputFragments: Schema.$Array<Schema.String>;
+    readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["thinking-first", "text-first"]>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+  }>>>;
+  readonly stopReason: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type MessagesScriptedMessage = typeof MessagesScriptedMessage.Type;
+/** A turn queued for the next Messages request. */
+declare const MessagesScriptedTurn: Schema.Union<readonly [Schema.Struct<{
+  readonly error: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly body: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>;
+}>, Schema.Struct<{
+  readonly thinking: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly toolUses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly inputFragments: Schema.$Array<Schema.String>;
+    readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["thinking-first", "text-first"]>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+  }>>>;
+  readonly stopReason: Schema.optionalKey<Schema.NonEmptyString>;
+}>]>;
+type MessagesScriptedTurn = typeof MessagesScriptedTurn.Type;
+type MessagesLedgerEntry = {
+  /** 1-based arrival order since the last ledger clear or reset. */readonly seq: number;
+  readonly method: string;
+  readonly path: string; /** Parsed JSON request body, when it was valid JSON. */
+  readonly body?: Schema.Json;
+  readonly model?: string;
+  readonly stream?: boolean; /** The request's `max_tokens`, when it is a number (non-positive or fractional answers 400). */
+  readonly maxTokens?: number;
+  readonly thinking?: Schema.Json;
+  readonly toolChoice?: Schema.Json;
+  readonly toolNames: ReadonlyArray<string>; /** Which header carried the credential (the value is never recorded). */
+  readonly credentialHeader?: 'x-api-key' | 'authorization';
+  readonly anthropicVersion?: string;
+  readonly anthropicBeta?: string; /** Kind of the fault that shaped the response. */
+  readonly fault?: MessagesFaultKind; /** Why a matching fault could not take effect (the response was a 500 emulator error). */
+  readonly faultError?: string;
+  /**
+   * Set when the emulator could not build the planned response; the request was answered with a
+   * 500 emulator error (still evidence-tagged) and no fault was used up.
+   */
+  readonly responseError?: string; /** Set when a scripted turn answered the request. */
+  readonly scripted?: 'message' | 'error'; /** Evidence of the matched route; `unknown-route` for requests that failed closed. */
+  readonly evidence: EmulatorEvidence | 'unknown-route';
+  readonly status: number; /** Body chunks handed to the transport so far (each produced when pulled). */
+  readonly bodyChunks: number;
+};
+type MessagesEmulator = EmulatorApi<MessagesScriptedTurn, MessagesFault, MessagesLedgerEntry>;
+type MessagesEmulatorConfig = {
+  /** The Messages path, for example `/v1/messages`. */readonly path: string; /** Route evidence manifest; must list exactly the Messages route. */
+  readonly routes: ReadonlyArray<EmulatorRouteEvidence>;
+  readonly knownModels: ReadonlyArray<string>; /** Builds the error thrown by the JS API (`faults.add`, `script.enqueue`) for invalid input. */
+  readonly inputInvalid: (input: 'fault' | 'turn', reason: string) => Error;
+};
+/** The Anthropic error envelope. */
+declare const messagesErrorEnvelope: (error: MessagesWireError) => Schema.JsonObject;
+/**
+ * Create a Messages emulator from its config. Each call has independent ledger, fault, and
+ * script state.
+ *
+ * Precedence per request: authentication, a supported `anthropic-version`, JSON and request
+ * validation (including a positive integer `max_tokens`, and no `thinking` with a forced
+ * `tool_choice`), then the first matching fault if it is a `status` fault, then the next
+ * scripted turn, then model validation and defaults; a first matching body fault then shapes the
+ * body. Only the first matching fault (in insertion order) applies. Credential headers are never
+ * recorded, and credential values are never checked or stored.
+ */
+declare const makeMessagesEmulator: (config: MessagesEmulatorConfig) => MessagesEmulator;
+//#endregion
+export { MessagesEmulator, MessagesEmulatorConfig, MessagesErrorEventFault, MessagesFault, MessagesFaultKind, MessagesLedgerEntry, MessagesScriptedMessage, MessagesScriptedToolUse, MessagesScriptedTurn, MessagesScriptedUsage, MessagesWireError, makeMessagesEmulator, messagesErrorEnvelope };
+//# sourceMappingURL=messages.d.mts.map

package/dist/messages.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.mts","names":[],"sources":["../src/messages.ts"],"mappings":";;;;;;cAyDa,iBAAA,EAAiB,MAAA,CAAA,MAAA;EAAA;;;KAKlB,iBAAA,UAA2B,iBAAA,CAAkB,IAAI;;;;;cAMhD,uBAAA,EAAuB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;AANyB;AAM7D;;;;cAaa,aAAA,EAAa,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAOd,aAAA,UAAuB,aAAA,CAAc,IAAI;AAAA,KAEzC,iBAAA,GAAoB,aAAa;;cAKhC,qBAAA,EAAqB,MAAA,CAAA,MAAA;EAAA;;;KAKtB,qBAAA,UAA+B,qBAAA,CAAsB,IAAI;;cAGxD,uBAAA,EAAuB,MAAA,CAAA,MAAA;EAAA;;;;KAMxB,uBAAA,UAAiC,uBAAA,CAAwB,IAAI;;;;AA5BzE;;;cAoCa,uBAAA,EAAuB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;KASxB,uBAAA,UAAiC,uBAAA,CAAwB,IAAI;;cAG5D,oBAAA,EAAoB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;KAErB,oBAAA,UAA8B,oBAAA,CAAqB,IAAI;AAAA,KAEvD,mBAAA;6EAED,GAAA;EAAA,SACA,MAAA;EAAA,SACA,IAAA;WAEA,IAAA,GAAO,MAAA,CAAO,IAAA;EAAA,SACd,KAAA;EAAA,SACA,MAAA;WAEA,SAAA;EAAA,SACA,QAAA,GAAW,MAAA,CAAO,IAAA;EAAA,SAClB,UAAA,GAAa,MAAA,CAAO,IAAA;EAAA,SACpB,SAAA,EAAW,aAAA;WAEX,gBAAA;EAAA,SACA,gBAAA;EAAA,SACA,aAAA,WArEe;EAAA,SAuEf,KAAA,GAAQ,iBAAA,EAvEO;EAAA,SAyEf,UAAA;EAzEe;;;;EAAA,SA8Ef,aAAA;WAEA,QAAA;WAEA,QAAA,EAAU,gBAAA;EAAA,SACV,MAAA;WAEA,UAAA;AAAA;AAAA,KAGC,gBAAA,GAAmB,WAAA,CAAY,oBAAA,EAAsB,aAAA,EAAe,mBAAA;AAAA,KAEpE,sBAAA;gEAED,IAAA;WAEA,MAAA,EAAQ,aAAA,CAAc,qBAAA;EAAA,SACtB,WAAA,EAAa,aAAA;WAEb,YAAA,GAAe,KAAA,oBAAyB,MAAA,aAAmB,KAAA;AAAA;;cA2XzD,qBAAA,GAAyB,KAAA,EAAO,iBAAA,KAAoB,MAAA,CAAO,UAGtE;;;;;;;;;;;;cAkFW,oBAAA,GAAwB,MAAA,EAAQ,sBAAA,KAAyB,gBAyMrE"}