@yolk-sdk/emulators 0.1.0-canary.96

package/dist/emulator-kernel.d.mts

@@ -0,0 +1,176 @@
+import { EmulatorEvidence, EmulatorRouteEvidence } from "./route-evidence.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/emulator-kernel.d.ts
+declare const ChunkCount: Schema.Int;
+/** Optional fault filter; an omitted field matches every request. `path` ending in `*` is a prefix. */
+declare const EmulatorFaultMatch: Schema.Struct<{
+  readonly path: Schema.optionalKey<Schema.String>;
+  readonly model: Schema.optionalKey<Schema.String>;
+}>;
+type EmulatorFaultMatch = typeof EmulatorFaultMatch.Type;
+/** Fields every fault kind carries. */
+declare const emulatorFaultFields: {
+  match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>; /** How many matching requests the fault answers. Omitted: every matching request. */
+  count: Schema.optionalKey<Schema.Int>;
+};
+/** Answer with this status, headers, and body instead of the planned response. */
+declare const EmulatorStatusFault: 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>>;
+}>;
+/** Send `chunks` body chunks, then error the body stream (a dropped connection). */
+declare const EmulatorErrorAfterChunksFault: 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;
+}>;
+/** Send `chunks` body chunks, then close the body cleanly (a truncated response). */
+declare const EmulatorTruncateAfterChunksFault: 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;
+}>;
+/** A scripted error response: status, body (a string is sent as is), and optional headers. */
+declare const EmulatorScriptedError: 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>>;
+  }>;
+}>;
+type EmulatorScriptedError = typeof EmulatorScriptedError.Type;
+/** What the kernel needs from every fault: its kind and optional filter and count. */
+type KernelFault = {
+  readonly kind: string;
+  readonly match?: EmulatorFaultMatch | undefined;
+  readonly count?: number | undefined;
+};
+type EmulatorFaultState<Fault> = {
+  readonly id: number;
+  readonly fault: Fault; /** Remaining matching requests; `undefined` for an unlimited fault. */
+  readonly remaining: number | undefined;
+  readonly applied: number;
+};
+type MutableFaultState<Fault> = {
+  readonly id: number;
+  readonly fault: Fault;
+  remaining: number | undefined;
+  applied: number;
+};
+type EmulatorRouteCoverage = EmulatorRouteEvidence & {
+  /** Ledger requests answered by this route since the last ledger clear or reset. */readonly requests: number;
+};
+type EmulatorCoverage = {
+  readonly routes: ReadonlyArray<EmulatorRouteCoverage>; /** Ledger requests to unknown routes (failed closed). */
+  readonly unknownRouteRequests: number;
+};
+/** Fields an emulator lists first in `/_emulate/state`. */
+type EmulatorStateFields = {
+  readonly knownModels: ReadonlyArray<string>; /** Only for emulators that emulate streamed reasoning. */
+  readonly reasoningModels?: ReadonlyArray<string>;
+};
+/** The ledger fields the kernel owns; each wire core extends it with its request fields. */
+type KernelLedgerEntry<FaultKind extends string> = {
+  seq: number;
+  method: string;
+  path: string;
+  fault?: FaultKind;
+  faultError?: string;
+  responseError?: string;
+  evidence: EmulatorEvidence | 'unknown-route';
+  status: number;
+  bodyChunks: number;
+};
+/** The public shape of every emulator built on the kernel. */
+type EmulatorApi<Turn, Fault, Entry> = {
+  /** The fetch handler (emulated API plus the `/_emulate/*` control plane). Never rejects. */readonly fetch: (request: Request) => Promise<Response>;
+  readonly ledger: {
+    readonly entries: () => ReadonlyArray<Entry>;
+    readonly clear: () => void;
+  }; /** Clear the ledger, faults, and scripted turns. */
+  readonly reset: () => void;
+  readonly faults: {
+    /** Add a fault; throws the emulator's input-invalid error for an invalid fault. */readonly add: (fault: Fault) => EmulatorFaultState<Fault>;
+    readonly list: () => ReadonlyArray<EmulatorFaultState<Fault>>;
+    readonly clear: () => void;
+  };
+  readonly script: {
+    /** Queue a turn for the next emulated request; throws for an invalid turn. */readonly enqueue: (turn: Turn) => void;
+    readonly pending: () => number;
+    readonly clear: () => void;
+  };
+  readonly coverage: () => EmulatorCoverage;
+};
+type EmulatorKernelConfig<Fault extends KernelFault, Turn, Entry extends KernelLedgerEntry<Fault['kind']>, Snapshot> = {
+  /** Route evidence manifest; `serve` needs exactly one handler per route. */readonly routes: ReadonlyArray<EmulatorRouteEvidence>; /** Fault schema (decoded strictly). */
+  readonly faultSchema: Schema.Decoder<Fault>; /** Scripted-turn schema (decoded strictly). */
+  readonly turnSchema: Schema.Decoder<Turn>; /** Adds the wire core's own ledger fields to a fresh kernel entry. */
+  readonly newEntry: (base: KernelLedgerEntry<Fault['kind']>) => Entry; /** Copies an entry for the ledger API (never shares mutable state). */
+  readonly snapshotEntry: (entry: Entry) => Snapshot;
+  /**
+   * Response for an unknown emulated route (fails closed, still written to the ledger with the
+   * status it answers); the core may add its own ledger fields to `entry`.
+   */
+  readonly unknownRoute: (entry: Entry) => Response; /** Fields listed first in `/_emulate/state`. */
+  readonly stateFields: () => EmulatorStateFields; /** Builds the error thrown by the JS API (`faults.add`, `script.enqueue`) for invalid input. */
+  readonly inputInvalid: (input: 'fault' | 'turn', reason: string) => Error;
+};
+type EmulatorRouteHandler<Entry> = (request: Request, entry: Entry, path: string) => Promise<Response>;
+declare const isJsonObject: (value: Schema.Json | undefined) => value is Schema.JsonObject;
+declare const jsonField: (value: Schema.Json | undefined, key: string) => Schema.Json | undefined;
+declare const stringField: (value: Schema.Json | undefined, key: string) => string | undefined;
+/** A JSON response; `body` is any JSON-serializable value (ledger snapshots, fault states, envelopes). */
+declare const jsonResponse: (status: number, body: unknown, headers?: HeadersInit) => Response;
+/** An emulator (not emulated-service) error: control-plane problems and unbuildable responses. */
+declare const controlError: (status: number, message: string, headers?: HeadersInit) => Response;
+/** A scripted or fault body: a string is sent as is, anything else as JSON. */
+declare const bodyText: (body: Schema.Json) => string;
+declare const readText: (request: Request) => Promise<string | undefined>;
+declare const parseJson: (text: string) => Schema.Json | undefined;
+/**
+ * A synthetic value for a JSON Schema: required object properties only,
+ * non-empty strings (or the first `enum` / `const` value), the minimum for
+ * numbers, `true` for booleans, and `minItems` synthetic items for arrays.
+ */
+declare const synthesizeValue: (schema: Schema.Json | undefined, name: string, depth: number) => Schema.Json;
+/** Split text into up to `parts` non-empty fragments (at least one). */
+declare const splitFragments: (text: string, parts: number) => ReadonlyArray<string>;
+/** A rough synthetic token count (about four characters per token, at least one). */
+declare const approximateTokens: (text: string) => number;
+/**
+ * Create the kernel of an emulator. Each call has independent ledger, fault,
+ * and script state. Handlers use the returned helpers, then `serve` binds
+ * them to the manifest (throwing `EmulatorRouteUnmapped` on a mismatch) and
+ * returns the emulator API.
+ */
+declare const makeEmulatorKernel: <Fault extends KernelFault, Turn, Entry extends KernelLedgerEntry<Fault["kind"]>, Snapshot>(config: EmulatorKernelConfig<Fault, Turn, Entry, Snapshot>) => {
+  takeFault: (path: string, model: string | undefined) => MutableFaultState<Fault> | undefined;
+  consumeFault: (state: MutableFaultState<Fault>, entry: Entry) => void;
+  nextTurn: () => Turn | undefined;
+  respondWithBody: (entry: Entry, status: number, headers: HeadersInit, chunks: ReadonlyArray<string>, fault: MutableFaultState<Fault> | undefined) => Response;
+  respondWithStatusFault: (entry: Entry, state: MutableFaultState<Fault>, fault: typeof EmulatorStatusFault.Type, defaultBody: (status: number) => Schema.Json) => Response;
+  respondWithScriptedError: (entry: Entry, error: EmulatorScriptedError["error"], fault: MutableFaultState<Fault> | undefined) => Response;
+  serve: (handlers: ReadonlyMap<string, EmulatorRouteHandler<Entry>>) => EmulatorApi<Turn, Fault, Snapshot>;
+};
+//#endregion
+export { ChunkCount, EmulatorApi, EmulatorCoverage, EmulatorErrorAfterChunksFault, EmulatorFaultMatch, EmulatorFaultState, EmulatorKernelConfig, EmulatorRouteCoverage, EmulatorRouteHandler, EmulatorScriptedError, EmulatorStateFields, EmulatorStatusFault, EmulatorTruncateAfterChunksFault, KernelFault, KernelLedgerEntry, approximateTokens, bodyText, controlError, emulatorFaultFields, isJsonObject, jsonField, jsonResponse, makeEmulatorKernel, parseJson, readText, splitFragments, stringField, synthesizeValue };
+//# sourceMappingURL=emulator-kernel.d.mts.map

package/dist/emulator-kernel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulator-kernel.d.mts","names":[],"sources":["../src/emulator-kernel.ts"],"mappings":";;;;cAwBa,UAAA,EAAU,MAAA,CAAA,GAAqD;;cAK/D,kBAAA,EAAkB,MAAA,CAAA,MAAA;EAAA;;;KAKnB,kBAAA,UAA4B,kBAAA,CAAmB,IAAI;AAL/D;AAAA,cAQa,mBAAA;;;;;;;;cAOA,mBAAA,EAAmB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;cASnB,6BAAA,EAA6B,MAAA,CAAA,MAAA;EAAA;;;;;;;;;cAO7B,gCAAA,EAAgC,MAAA,CAAA,MAAA;EAAA;;;;;;;;;cAOhC,qBAAA,EAAqB,MAAA,CAAA,MAAA;EAAA;;;;;;KAQtB,qBAAA,UAA+B,qBAAA,CAAsB,IAAI;;KAGzD,WAAA;EAAA,SACD,IAAA;EAAA,SACA,KAAA,GAAQ,kBAAkB;EAAA,SAC1B,KAAA;AAAA;AAAA,KAOC,kBAAA;EAAA,SACD,EAAA;EAAA,SACA,KAAA,EAAO,KAAK;WAEZ,SAAA;EAAA,SACA,OAAA;AAAA;AAAA,KAGN,iBAAA;EAAA,SACM,EAAA;EAAA,SACA,KAAA,EAAO,KAAK;EACrB,SAAA;EACA,OAAA;AAAA;AAAA,KAGU,qBAAA,GAAwB,qBAAqB;8FAE9C,QAAQ;AAAA;AAAA,KAGP,gBAAA;EAAA,SACD,MAAA,EAAQ,aAAa,CAAC,qBAAA;WAEtB,oBAAA;AAAA;;KAIC,mBAAA;EAAA,SACD,WAAA,EAAa,aAAA;WAEb,eAAA,GAAkB,aAAa;AAAA;;KAI9B,iBAAA;EACV,GAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA,GAAQ,SAAA;EACR,UAAA;EACA,aAAA;EACA,QAAA,EAAU,gBAAgB;EAC1B,MAAA;EACA,UAAA;AAAA;;KAIU,WAAA;uGAED,KAAA,GAAQ,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;EAAA,SACrC,MAAA;IAAA,SACE,OAAA,QAAe,aAAA,CAAc,KAAA;IAAA,SAC7B,KAAA;EAAA;WAGF,KAAA;EAAA,SACA,MAAA;gGAEE,GAAA,GAAM,KAAA,EAAO,KAAA,KAAU,kBAAA,CAAmB,KAAA;IAAA,SAC1C,IAAA,QAAY,aAAA,CAAc,kBAAA,CAAmB,KAAA;IAAA,SAC7C,KAAA;EAAA;EAAA,SAEF,MAAA;2FAEE,OAAA,GAAU,IAAA,EAAM,IAAA;IAAA,SAChB,OAAA;IAAA,SACA,KAAA;EAAA;EAAA,SAEF,QAAA,QAAgB,gBAAA;AAAA;AAAA,KAGf,oBAAA,eACI,WAAA,sBAEA,iBAAA,CAAkB,KAAA;uFAIvB,MAAA,EAAQ,aAAA,CAAc,qBAAA;WAEtB,WAAA,EAAa,MAAA,CAAO,OAAA,CAAQ,KAAA;WAE5B,UAAA,EAAY,MAAA,CAAO,OAAA,CAAQ,IAAA;WAE3B,QAAA,GAAW,IAAA,EAAM,iBAAA,CAAkB,KAAA,cAAmB,KAAA;WAEtD,aAAA,GAAgB,KAAA,EAAO,KAAA,KAAU,QAAA;;;;;WAKjC,YAAA,GAAe,KAAA,EAAO,KAAA,KAAU,QAAA,EA9H9B;EAAA,SAgIF,WAAA,QAAmB,mBAAA;WAEnB,YAAA,GAAe,KAAA,oBAAyB,MAAA,aAAmB,KAAA;AAAA;AAAA,KAG1D,oBAAA,WACV,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,KAAA,EACP,IAAA,aACG,OAAA,CAAQ,QAAA;AAAA,cAWA,YAAA,GAAgB,KAAA,EAAO,MAAA,CAAO,IAAA,iBAAmB,KAAA,IAAS,MAAA,CAAO,UACe;AAAA,cAEhF,SAAA,GAAa,KAAA,EAAO,MAAA,CAAO,IAAA,cAAkB,GAAA,aAAc,MAAA,CAAO,IAAI;AAAA,cAGtE,WAAA,GAAe,KAAA,EAAO,MAAA,CAAO,IAAI,cAAc,GAAA;;cAS/C,YAAA,GACX,MAAA,UACA,IAAA,WACA,OAAA,GAAS,WAAA,KACR,QAMF;;cAGY,YAAA,GACX,MAAA,UACA,OAAA,UACA,OAAA,GAAS,WAAA,KACR,QAAyF;;cAG/E,QAAA,GAAY,IAAA,EAAM,MAAA,CAAO,IAAI;AAAA,cAc7B,QAAA,GAAY,OAAA,EAAS,OAAA,KAAU,OAAO;AAAA,cAMtC,SAAA,GAAa,IAAA,aAAe,MAAA,CAAO,IAAI;;;;;;cAmFvC,eAAA,GACX,MAAA,EAAQ,MAAA,CAAO,IAAA,cACf,IAAA,UACA,KAAA,aACC,MAAA,CAAO,IAuET;;cAGY,cAAA,GAAkB,IAAA,UAAc,KAAA,aAAgB,aAAa;;cAgB7D,iBAAA,GAAqB,IAAY;;;;;;;cAQjC,kBAAA,iBACG,WAAA,sBAEA,iBAAA,CAAkB,KAAA,qBAGhC,MAAA,EAAQ,oBAAA,CAAqB,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,QAAA;4BAgEnC,KAAA,yBAEX,iBAAA,CAAkB,KAAA;wBAQQ,iBAAA,CAAkB,KAAA,GAAM,KAAA,EAAS,KAAA;kBAUzC,IAAA;2BAqBZ,KAAA,EAAK,MAAA,UACE,OAAA,EACL,WAAA,EAAW,MAAA,EACZ,aAAA,UAAqB,KAAA,EACtB,iBAAA,CAAkB,KAAA,kBACxB,QAAA;kCA8BM,KAAA,EAAK,KAAA,EACL,iBAAA,CAAkB,KAAA,GAAM,KAAA,SACjB,mBAAA,CAAoB,IAAA,EAAI,WAAA,GACxB,MAAA,aAAmB,MAAA,CAAO,IAAA,KACvC,QAAA;oCAiBM,KAAA,EAAK,KAAA,EACL,qBAAA,WAA8B,KAAA,EAC9B,iBAAA,CAAkB,KAAA,kBACxB,QAAA;oBAuIS,WAAA,SAAoB,oBAAA,CAAqB,KAAA,OAClD,WAAA,CAAY,IAAA,EAAM,KAAA,EAAO,QAAA;AAAA"}

package/dist/emulator-kernel.mjs

@@ -0,0 +1,413 @@
+import { EmulatorHeaderRecord, EmulatorResponseStatus } from "./emulator-http.mjs";
+import { bindRouteHandlers, emulatorEvidenceHeader } from "./route-evidence.mjs";
+import { Predicate, Result } from "effect";
+import * as Schema from "effect/Schema";
+//#region src/emulator-kernel.ts
+/**
+* Shared emulator kernel (internal; not a package export).
+*
+* The wire-independent half of every fetch-handler emulator: fault and scripted-turn state, the
+* request ledger, pull-driven bodies with chunk faults, evidence tagging, route binding, and the
+* `/_emulate/*` control plane. Each wire core (`chat-completions.ts`, `messages.ts`) supplies its
+* route handlers, fault and turn schemas, ledger entry shape, and error bodies.
+*
+* Also holds small wire-independent helpers both cores use: JSON field access, synthetic values
+* for a tool's JSON Schema, fragment splitting, and a rough token estimate.
+*
+* Runtime-portable Web APIs only (`Request`, `Response`, `ReadableStream`, `TextEncoder`, `URL`);
+* no Node builtins and no SDK imports.
+*/
+const ChunkCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+const FaultCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+/** Optional fault filter; an omitted field matches every request. `path` ending in `*` is a prefix. */
+const EmulatorFaultMatch = Schema.Struct({
+	path: Schema.optionalKey(Schema.String),
+	model: Schema.optionalKey(Schema.String)
+});
+/** Fields every fault kind carries. */
+const emulatorFaultFields = {
+	match: Schema.optionalKey(EmulatorFaultMatch),
+	/** How many matching requests the fault answers. Omitted: every matching request. */
+	count: Schema.optionalKey(FaultCount)
+};
+/** Answer with this status, headers, and body instead of the planned response. */
+const EmulatorStatusFault = Schema.Struct({
+	kind: Schema.Literal("status"),
+	status: EmulatorResponseStatus,
+	headers: Schema.optionalKey(EmulatorHeaderRecord),
+	body: Schema.optionalKey(Schema.Json),
+	...emulatorFaultFields
+});
+/** Send `chunks` body chunks, then error the body stream (a dropped connection). */
+const EmulatorErrorAfterChunksFault = Schema.Struct({
+	kind: Schema.Literal("error-after-chunks"),
+	chunks: ChunkCount,
+	...emulatorFaultFields
+});
+/** Send `chunks` body chunks, then close the body cleanly (a truncated response). */
+const EmulatorTruncateAfterChunksFault = Schema.Struct({
+	kind: Schema.Literal("truncate-after-chunks"),
+	chunks: ChunkCount,
+	...emulatorFaultFields
+});
+/** A scripted error response: status, body (a string is sent as is), and optional headers. */
+const EmulatorScriptedError = Schema.Struct({ error: Schema.Struct({
+	status: EmulatorResponseStatus,
+	body: Schema.Json,
+	headers: Schema.optionalKey(EmulatorHeaderRecord)
+}) });
+const strict = { onExcessProperty: "error" };
+const decodeJsonText = Schema.decodeUnknownResult(Schema.fromJsonString(Schema.Json));
+const issueMessage = (issue) => new Schema.SchemaError(issue).message;
+const isJsonObject = (value) => value !== null && value !== void 0 && Predicate.isObject(value) && !Array.isArray(value);
+const jsonField = (value, key) => isJsonObject(value) ? value[key] : void 0;
+const stringField = (value, key) => {
+	const field = jsonField(value, key);
+	return Predicate.isString(field) ? field : void 0;
+};
+const textEncoder = new TextEncoder();
+/** A JSON response; `body` is any JSON-serializable value (ledger snapshots, fault states, envelopes). */
+const jsonResponse = (status, body, headers = {}) => {
+	const responseHeaders = new Headers(headers);
+	responseHeaders.set("content-type", "application/json");
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: responseHeaders
+	});
+};
+/** An emulator (not emulated-service) error: control-plane problems and unbuildable responses. */
+const controlError = (status, message, headers = {}) => jsonResponse(status, { error: {
+	message,
+	type: "emulator_error"
+} }, headers);
+/** A scripted or fault body: a string is sent as is, anything else as JSON. */
+const bodyText = (body) => Predicate.isString(body) ? body : JSON.stringify(body);
+/** Headers for a scripted or fault body, with a `content-type` matching the body when unset. */
+const bodyHeaders = (headers, body) => {
+	const result = new Headers(headers ?? {});
+	if (!result.has("content-type")) result.set("content-type", Predicate.isString(body) ? "text/plain" : "application/json");
+	return result;
+};
+const readText = (request) => request.text().then((text) => text, () => void 0);
+const parseJson = (text) => {
+	const result = decodeJsonText(text);
+	return Result.isSuccess(result) ? result.success : void 0;
+};
+const pathMatches = (pattern, path) => pattern.endsWith("*") ? path.startsWith(pattern.slice(0, -1)) : pattern === path;
+const faultMatches = (fault, path, model) => (fault.match?.path === void 0 || pathMatches(fault.match.path, path)) && (fault.match?.model === void 0 || fault.match.model === model);
+const isBodyChunkFault = (fault) => fault.kind === "error-after-chunks" || fault.kind === "truncate-after-chunks";
+const chunkFaultProblem = (fault, chunks) => {
+	return (fault.kind === "error-after-chunks" ? fault.chunks <= chunks : fault.chunks < chunks) ? void 0 : `${fault.kind} after ${fault.chunks} chunk(s) cannot apply to a response with ${chunks} chunk(s)`;
+};
+/**
+* Strictly pull-driven body: chunk `k` is produced only when the consumer
+* pulls it, and `entry.bodyChunks` counts the chunks handed over. The fault
+* (already validated against the chunk count) applies when the consumer pulls
+* past `fault.chunks` chunks.
+*/
+const chunkedBody = (chunks, fault, entry) => {
+	let next = 0;
+	return new ReadableStream({ pull: (controller) => {
+		if (fault !== void 0 && next === fault.chunks) {
+			if (fault.kind === "error-after-chunks") controller.error(/* @__PURE__ */ new Error(`synthetic mid-stream failure after ${next} chunk(s)`));
+			else controller.close();
+			return;
+		}
+		const chunk = chunks[next];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		next += 1;
+		entry.bodyChunks += 1;
+		controller.enqueue(textEncoder.encode(chunk));
+	} }, { highWaterMark: 0 });
+};
+const withEvidence = (response, evidence) => {
+	if (evidence === "unverified") response.headers.set(emulatorEvidenceHeader, "unverified");
+	return response;
+};
+const maxSchemaDepth = 8;
+/**
+* A synthetic value for a JSON Schema: required object properties only,
+* non-empty strings (or the first `enum` / `const` value), the minimum for
+* numbers, `true` for booleans, and `minItems` synthetic items for arrays.
+*/
+const synthesizeValue = (schema, name, depth) => {
+	const constant = jsonField(schema, "const");
+	if (constant !== void 0) return constant;
+	const choices = jsonField(schema, "enum");
+	if (Array.isArray(choices) && choices.length > 0) return choices[0] ?? null;
+	for (const key of [
+		"anyOf",
+		"oneOf",
+		"allOf"
+	]) {
+		const options = jsonField(schema, key);
+		if (Array.isArray(options) && options.length > 0) return synthesizeValue(options.find((option) => stringField(option, "type") !== "null") ?? options[0], name, depth + 1);
+	}
+	const declared = jsonField(schema, "type");
+	const type = Array.isArray(declared) ? declared.find((entry) => Predicate.isString(entry) && entry !== "null") : declared;
+	if (depth > maxSchemaDepth) return null;
+	switch (type) {
+		case "object": {
+			const properties = jsonField(schema, "properties");
+			const required = jsonField(schema, "required");
+			const value = {};
+			for (const key of Array.isArray(required) ? required : []) if (Predicate.isString(key)) value[key] = synthesizeValue(jsonField(properties, key), key, depth + 1);
+			return value;
+		}
+		case "array": {
+			const minItems = jsonField(schema, "minItems");
+			const count = Predicate.isNumber(minItems) && minItems > 0 ? Math.min(minItems, 3) : 0;
+			return Array.from({ length: count }, () => synthesizeValue(jsonField(schema, "items"), name, depth + 1));
+		}
+		case "integer":
+		case "number": {
+			const minimum = jsonField(schema, "minimum");
+			return Predicate.isNumber(minimum) ? minimum : 1;
+		}
+		case "boolean": return true;
+		case "null": return null;
+		default: return `synthetic ${name}`;
+	}
+};
+/** Split text into up to `parts` non-empty fragments (at least one). */
+const splitFragments = (text, parts) => {
+	if (text.length <= 1) return [text];
+	const size = Math.ceil(text.length / Math.min(parts, text.length));
+	const fragments = [];
+	for (let index = 0; index < text.length; index += size) fragments.push(text.slice(index, index + size));
+	return fragments;
+};
+/** A rough synthetic token count (about four characters per token, at least one). */
+const approximateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
+/**
+* Create the kernel of an emulator. Each call has independent ledger, fault,
+* and script state. Handlers use the returned helpers, then `serve` binds
+* them to the manifest (throwing `EmulatorRouteUnmapped` on a mismatch) and
+* returns the emulator API.
+*/
+const makeEmulatorKernel = (config) => {
+	const decodeFault = Schema.decodeUnknownResult(config.faultSchema, strict);
+	const decodeFaultList = Schema.decodeUnknownResult(Schema.Union([config.faultSchema, Schema.Struct({ faults: Schema.Array(config.faultSchema) })]), strict);
+	const decodeTurn = Schema.decodeUnknownResult(config.turnSchema, strict);
+	const decodeTurnList = Schema.decodeUnknownResult(Schema.Union([Schema.Struct({ turns: Schema.Array(config.turnSchema) }), config.turnSchema]), strict);
+	let entries = [];
+	let faultStates = [];
+	let turns = [];
+	let nextSeq = 1;
+	let nextFaultId = 1;
+	const snapshotFault = (state) => ({ ...state });
+	const clearLedger = () => {
+		entries = [];
+		nextSeq = 1;
+	};
+	const addFault = (input) => {
+		const decoded = decodeFault(input);
+		if (Result.isFailure(decoded)) return issueMessage(decoded.failure.issue);
+		const state = {
+			id: nextFaultId++,
+			fault: decoded.success,
+			remaining: decoded.success.count,
+			applied: 0
+		};
+		faultStates.push(state);
+		return snapshotFault(state);
+	};
+	const enqueueTurn = (input) => {
+		const decoded = decodeTurn(input);
+		if (Result.isFailure(decoded)) return issueMessage(decoded.failure.issue);
+		turns.push(decoded.success);
+	};
+	/** The first matching fault with uses left, in insertion order (not yet consumed). */
+	const takeFault = (path, model) => faultStates.find((state) => (state.remaining === void 0 || state.remaining > 0) && faultMatches(state.fault, path, model));
+	/** Use up one application of a fault and record its kind in the ledger entry. */
+	const consumeFault = (state, entry) => {
+		state.applied += 1;
+		entry.fault = state.fault.kind;
+		if (state.remaining !== void 0) state.remaining -= 1;
+	};
+	/** The next scripted turn, used up when its request arrives. */
+	const nextTurn = () => turns.shift();
+	const coverage = () => ({
+		routes: config.routes.map((route) => ({
+			...route,
+			requests: entries.filter((entry) => entry.evidence !== "unknown-route" && entry.method === route.method && entry.path === route.path).length
+		})),
+		unknownRouteRequests: entries.filter((entry) => entry.evidence === "unknown-route").length
+	});
+	/**
+	* Answer with a pull-driven body. A matching `error-after-chunks` or
+	* `truncate-after-chunks` fault shapes it; one that cannot take effect
+	* answers 500 and is not consumed. Other fault kinds are left to the caller.
+	*/
+	const respondWithBody = (entry, status, headers, chunks, fault) => {
+		const chunkFault = fault === void 0 || !isBodyChunkFault(fault.fault) ? void 0 : fault.fault;
+		if (chunkFault !== void 0) {
+			const problem = chunkFaultProblem(chunkFault, chunks.length);
+			if (problem !== void 0) {
+				entry.faultError = problem;
+				entry.status = 500;
+				return controlError(500, `emulator fault cannot apply: ${problem}`);
+			}
+		}
+		const response = new Response(chunkedBody(chunks, chunkFault, entry), {
+			status,
+			headers
+		});
+		if (chunkFault !== void 0 && fault !== void 0) consumeFault(fault, entry);
+		entry.status = response.status;
+		return response;
+	};
+	/** Answer a `status` fault with its status, headers, and body (or `defaultBody`). */
+	const respondWithStatusFault = (entry, state, fault, defaultBody) => {
+		const faultBody = fault.body ?? defaultBody(fault.status);
+		const response = new Response(bodyText(faultBody), {
+			status: fault.status,
+			headers: bodyHeaders(fault.headers, faultBody)
+		});
+		consumeFault(state, entry);
+		entry.status = response.status;
+		return response;
+	};
+	/** Answer a scripted error turn; a matching chunk fault still shapes its body. */
+	const respondWithScriptedError = (entry, error, fault) => respondWithBody(entry, error.status, bodyHeaders(error.headers, error.body), [bodyText(error.body)], fault);
+	const reset = () => {
+		clearLedger();
+		faultStates = [];
+		turns = [];
+	};
+	const state = () => ({
+		...config.stateFields(),
+		pendingTurns: turns.length,
+		faults: faultStates.map(snapshotFault),
+		ledgerEntries: entries.length
+	});
+	const controlPlane = async (request, path) => {
+		const method = request.method;
+		const allow = (methods) => controlError(405, "method not allowed", { allow: methods });
+		const jsonBody = async () => {
+			const text = await readText(request);
+			return text === void 0 ? void 0 : parseJson(text);
+		};
+		switch (path) {
+			case "/_emulate/ledger":
+				if (method === "GET") return jsonResponse(200, { entries: entries.map(config.snapshotEntry) });
+				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 decoded = decodeFaultList(await jsonBody());
+				if (Result.isFailure(decoded)) return controlError(400, `invalid fault: ${issueMessage(decoded.failure.issue)}`);
+				return jsonResponse(201, { faults: ("faults" in decoded.success ? decoded.success.faults : [decoded.success]).map((fault) => addFault(fault)) });
+			}
+			case "/_emulate/script": {
+				if (method !== "POST") return allow("POST");
+				const decoded = decodeTurnList(await jsonBody());
+				if (Result.isFailure(decoded)) return controlError(400, `invalid turn: ${issueMessage(decoded.failure.issue)}`);
+				const queued = Predicate.isObject(decoded.success) && "turns" in decoded.success ? decoded.success.turns : [decoded.success];
+				for (const turn of queued) enqueueTurn(turn);
+				return jsonResponse(201, { pending: turns.length });
+			}
+			case "/_emulate/reset":
+				if (method !== "POST") return allow("POST");
+				reset();
+				return jsonResponse(200, { reset: true });
+			case "/_emulate/state":
+				if (method !== "GET") return allow("GET");
+				return jsonResponse(200, state());
+			case "/_emulate/coverage":
+				if (method !== "GET") return allow("GET");
+				return jsonResponse(200, coverage());
+			default: return controlError(404, "unknown control-plane route");
+		}
+	};
+	/**
+	* Bind one handler per manifest route (keyed by `emulatorRouteKey`) and
+	* return the emulator API. Throws `EmulatorRouteUnmapped` when a manifest
+	* route has no handler or a handler has no manifest route.
+	*/
+	const serve = (handlers) => {
+		const routes = bindRouteHandlers(config.routes, handlers);
+		const emulatedApi = async (request, path) => {
+			const bound = routes.find((candidate) => candidate.route.method === request.method && candidate.route.path === path);
+			const entry = config.newEntry({
+				seq: nextSeq++,
+				method: request.method,
+				path,
+				evidence: bound?.route.evidence ?? "unknown-route",
+				status: 0,
+				bodyChunks: 0
+			});
+			entries.push(entry);
+			if (bound === void 0) {
+				const response = config.unknownRoute(entry);
+				entry.status = response.status;
+				return response;
+			}
+			return withEvidence(await bound.handler(request, entry, path).catch(() => {
+				entry.status = 500;
+				entry.responseError = "the emulator could not build the planned response";
+				return controlError(500, "emulator could not build the response");
+			}), bound.route.evidence);
+		};
+		const handle = (request) => {
+			const path = URL.canParse(request.url) ? new URL(request.url).pathname : "/";
+			return path === "/_emulate" || path.startsWith("/_emulate/") ? controlPlane(request, path) : emulatedApi(request, path);
+		};
+		return {
+			fetch: (request) => handle(request).catch(() => controlError(500, "emulator failed to handle the request")),
+			ledger: {
+				entries: () => entries.map(config.snapshotEntry),
+				clear: clearLedger
+			},
+			reset,
+			faults: {
+				add: (fault) => {
+					const added = addFault(fault);
+					if (Predicate.isString(added)) throw config.inputInvalid("fault", added);
+					return added;
+				},
+				list: () => faultStates.map(snapshotFault),
+				clear: () => {
+					faultStates = [];
+				}
+			},
+			script: {
+				enqueue: (turn) => {
+					const problem = enqueueTurn(turn);
+					if (problem !== void 0) throw config.inputInvalid("turn", problem);
+				},
+				pending: () => turns.length,
+				clear: () => {
+					turns = [];
+				}
+			},
+			coverage
+		};
+	};
+	return {
+		takeFault,
+		consumeFault,
+		nextTurn,
+		respondWithBody,
+		respondWithStatusFault,
+		respondWithScriptedError,
+		serve
+	};
+};
+//#endregion
+export { ChunkCount, EmulatorErrorAfterChunksFault, EmulatorFaultMatch, EmulatorScriptedError, EmulatorStatusFault, EmulatorTruncateAfterChunksFault, approximateTokens, bodyText, controlError, emulatorFaultFields, isJsonObject, jsonField, jsonResponse, makeEmulatorKernel, parseJson, readText, splitFragments, stringField, synthesizeValue };
+
+//# sourceMappingURL=emulator-kernel.mjs.map