@yolk-sdk/emulators 0.1.0-canary.96

package/dist/route-evidence.d.mts

@@ -0,0 +1,45 @@
+//#region src/route-evidence.d.ts
+/** How well an emulated route's wire shape is backed by live observation. */
+type EmulatorEvidence = 'verified' | 'unverified';
+/** One emulated route and the conformance evidence behind its wire shape. */
+type EmulatorRouteEvidence = {
+  readonly method: string; /** Path template, for example `/v1/chat/completions` or `/3/invoices/{DocumentNumber}`. */
+  readonly path: string; /** `provider` for model/provider APIs, `connector` for connector APIs. */
+  readonly kind: 'provider' | 'connector'; /** True when the route changes state in the real service. */
+  readonly write: boolean; /** Conformance case ids whose wire claims this route follows. */
+  readonly caseIds: ReadonlyArray<string>;
+  readonly evidence: EmulatorEvidence; /** Calendar date (`YYYY-MM-DD`, UTC) of the live observation behind `verified` evidence. */
+  readonly observedAt?: string | undefined;
+};
+/** Response header carried by every response from an unverified route. */
+declare const emulatorEvidenceHeader = "x-emulator-evidence";
+/** `METHOD /path` key for a manifest route. */
+declare const emulatorRouteKey: (method: string, path: string) => string;
+declare const EmulatorRouteUnmapped_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: "EmulatorRouteUnmapped";
+} & Readonly<A>;
+/**
+ * An emulator's manifest and its handlers disagree: a manifest route has no
+ * handler, or a handler has no manifest route. A bug in the emulator, thrown
+ * when the emulator is constructed.
+ */
+declare class EmulatorRouteUnmapped extends EmulatorRouteUnmapped_base<{
+  readonly route: string;
+  readonly problem: 'no-handler' | 'no-manifest-route';
+}> {
+  get message(): string;
+}
+type BoundEmulatorRoute<H> = {
+  readonly route: EmulatorRouteEvidence;
+  readonly handler: H;
+};
+/**
+ * Pair every manifest route with its own handler (keyed by
+ * `emulatorRouteKey`). Throws `EmulatorRouteUnmapped` when a manifest route
+ * has no handler or a handler has no manifest route, so a manifest entry can
+ * never be served by another route's handler.
+ */
+declare const bindRouteHandlers: <H>(routes: ReadonlyArray<EmulatorRouteEvidence>, handlers: ReadonlyMap<string, H>) => ReadonlyArray<BoundEmulatorRoute<H>>;
+//#endregion
+export { BoundEmulatorRoute, EmulatorEvidence, EmulatorRouteEvidence, EmulatorRouteUnmapped, bindRouteHandlers, emulatorEvidenceHeader, emulatorRouteKey };
+//# sourceMappingURL=route-evidence.d.mts.map

package/dist/route-evidence.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-evidence.d.mts","names":[],"sources":["../src/route-evidence.ts"],"mappings":";;KAaY,gBAAA;;KAGA,qBAAA;EAAA,SACD,MAAA,UAJiB;EAAA,SAMjB,IAAA,UAHsB;EAAA,SAKtB,IAAA,4BAK0B;EAAA,SAH1B,KAAA,WAJA;EAAA,SAMA,OAAA,EAAS,aAAA;EAAA,SACT,QAAA,EAAU,gBAAgB,EAD1B;EAAA,SAGA,UAAA;AAAA;;cAIE,sBAAA;;cAGA,gBAAA,GAAoB,MAAA,UAAgB,IAAY;AAAA,cAC1B,0BAAA;;;;AAJA;AAGnC;;;cAQa,qBAAA,SAA8B,0BAAA;EAAA,SAChC,KAAA;EAAA,SACA,OAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAAA,KAOH,kBAAA;EAAA,SACD,KAAA,EAAO,qBAAA;EAAA,SACP,OAAA,EAAS,CAAC;AAAA;;;;;;;cASR,iBAAA,MACX,MAAA,EAAQ,aAAA,CAAc,qBAAA,GACtB,QAAA,EAAU,WAAA,SAAoB,CAAA,MAC7B,aAAA,CAAc,kBAAA,CAAmB,CAAA"}

package/dist/route-evidence.mjs

@@ -0,0 +1,56 @@
+import { Data } from "effect";
+//#region src/route-evidence.ts
+/**
+* Route evidence manifests shared by the emulators (internal; re-exported as
+* types by each emulator subpath).
+*
+* Emulators never import SDK code. Each emulated route instead names the
+* conformance case ids whose recorded wire shapes it follows, and how well
+* that shape is backed: `verified` routes follow a live observation (dated by
+* `observedAt`), `unverified` routes follow synthetic placeholders. The repo
+* evidence check (`pnpm packages:evidence`) validates the case ids.
+*/
+/** Response header carried by every response from an unverified route. */
+const emulatorEvidenceHeader = "x-emulator-evidence";
+/** `METHOD /path` key for a manifest route. */
+const emulatorRouteKey = (method, path) => `${method.toUpperCase()} ${path}`;
+/**
+* An emulator's manifest and its handlers disagree: a manifest route has no
+* handler, or a handler has no manifest route. A bug in the emulator, thrown
+* when the emulator is constructed.
+*/
+var EmulatorRouteUnmapped = class extends Data.TaggedError("EmulatorRouteUnmapped") {
+	get message() {
+		return this.problem === "no-handler" ? `Emulator manifest route ${this.route} has no handler` : `Emulator handler ${this.route} has no manifest route`;
+	}
+};
+/**
+* Pair every manifest route with its own handler (keyed by
+* `emulatorRouteKey`). Throws `EmulatorRouteUnmapped` when a manifest route
+* has no handler or a handler has no manifest route, so a manifest entry can
+* never be served by another route's handler.
+*/
+const bindRouteHandlers = (routes, handlers) => {
+	const bound = routes.map((route) => {
+		const key = emulatorRouteKey(route.method, route.path);
+		const handler = handlers.get(key);
+		if (handler === void 0) throw new EmulatorRouteUnmapped({
+			route: key,
+			problem: "no-handler"
+		});
+		return {
+			route,
+			handler
+		};
+	});
+	const manifestKeys = new Set(routes.map((route) => emulatorRouteKey(route.method, route.path)));
+	for (const key of handlers.keys()) if (!manifestKeys.has(key)) throw new EmulatorRouteUnmapped({
+		route: key,
+		problem: "no-manifest-route"
+	});
+	return bound;
+};
+//#endregion
+export { EmulatorRouteUnmapped, bindRouteHandlers, emulatorEvidenceHeader, emulatorRouteKey };
+
+//# sourceMappingURL=route-evidence.mjs.map

package/dist/route-evidence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-evidence.mjs","names":[],"sources":["../src/route-evidence.ts"],"sourcesContent":["/**\n * Route evidence manifests shared by the emulators (internal; re-exported as\n * types by each emulator subpath).\n *\n * Emulators never import SDK code. Each emulated route instead names the\n * conformance case ids whose recorded wire shapes it follows, and how well\n * that shape is backed: `verified` routes follow a live observation (dated by\n * `observedAt`), `unverified` routes follow synthetic placeholders. The repo\n * evidence check (`pnpm packages:evidence`) validates the case ids.\n */\nimport { Data } from 'effect'\n\n/** How well an emulated route's wire shape is backed by live observation. */\nexport type EmulatorEvidence = 'verified' | 'unverified'\n\n/** One emulated route and the conformance evidence behind its wire shape. */\nexport type EmulatorRouteEvidence = {\n  readonly method: string\n  /** Path template, for example `/v1/chat/completions` or `/3/invoices/{DocumentNumber}`. */\n  readonly path: string\n  /** `provider` for model/provider APIs, `connector` for connector APIs. */\n  readonly kind: 'provider' | 'connector'\n  /** True when the route changes state in the real service. */\n  readonly write: boolean\n  /** Conformance case ids whose wire claims this route follows. */\n  readonly caseIds: ReadonlyArray<string>\n  readonly evidence: EmulatorEvidence\n  /** Calendar date (`YYYY-MM-DD`, UTC) of the live observation behind `verified` evidence. */\n  readonly observedAt?: string | undefined\n}\n\n/** Response header carried by every response from an unverified route. */\nexport const emulatorEvidenceHeader = 'x-emulator-evidence'\n\n/** `METHOD /path` key for a manifest route. */\nexport const emulatorRouteKey = (method: string, path: string): string =>\n  `${method.toUpperCase()} ${path}`\n\n/**\n * An emulator's manifest and its handlers disagree: a manifest route has no\n * handler, or a handler has no manifest route. A bug in the emulator, thrown\n * when the emulator is constructed.\n */\nexport class EmulatorRouteUnmapped extends Data.TaggedError('EmulatorRouteUnmapped')<{\n  readonly route: string\n  readonly problem: 'no-handler' | 'no-manifest-route'\n}> {\n  override get message(): string {\n    return this.problem === 'no-handler'\n      ? `Emulator manifest route ${this.route} has no handler`\n      : `Emulator handler ${this.route} has no manifest route`\n  }\n}\n\nexport type BoundEmulatorRoute<H> = {\n  readonly route: EmulatorRouteEvidence\n  readonly handler: H\n}\n\n/**\n * Pair every manifest route with its own handler (keyed by\n * `emulatorRouteKey`). Throws `EmulatorRouteUnmapped` when a manifest route\n * has no handler or a handler has no manifest route, so a manifest entry can\n * never be served by another route's handler.\n */\nexport const bindRouteHandlers = <H>(\n  routes: ReadonlyArray<EmulatorRouteEvidence>,\n  handlers: ReadonlyMap<string, H>\n): ReadonlyArray<BoundEmulatorRoute<H>> => {\n  const bound = routes.map(route => {\n    const key = emulatorRouteKey(route.method, route.path)\n    const handler = handlers.get(key)\n\n    if (handler === undefined) {\n      throw new EmulatorRouteUnmapped({ route: key, problem: 'no-handler' })\n    }\n\n    return { route, handler }\n  })\n\n  const manifestKeys = new Set(routes.map(route => emulatorRouteKey(route.method, route.path)))\n\n  for (const key of handlers.keys()) {\n    if (!manifestKeys.has(key)) {\n      throw new EmulatorRouteUnmapped({ route: key, problem: 'no-manifest-route' })\n    }\n  }\n\n  return bound\n}\n"],"mappings":";;;;;;;;;;;;;AAgCA,MAAa,yBAAyB;;AAGtC,MAAa,oBAAoB,QAAgB,SAC/C,GAAG,OAAO,YAAY,EAAE,GAAG;;;;;;AAO7B,IAAa,wBAAb,cAA2C,KAAK,YAAY,uBAAuB,EAGhF;CACD,IAAa,UAAkB;EAC7B,OAAO,KAAK,YAAY,eACpB,2BAA2B,KAAK,MAAM,mBACtC,oBAAoB,KAAK,MAAM;CACrC;AACF;;;;;;;AAaA,MAAa,qBACX,QACA,aACyC;CACzC,MAAM,QAAQ,OAAO,KAAI,UAAS;EAChC,MAAM,MAAM,iBAAiB,MAAM,QAAQ,MAAM,IAAI;EACrD,MAAM,UAAU,SAAS,IAAI,GAAG;EAEhC,IAAI,YAAY,KAAA,GACd,MAAM,IAAI,sBAAsB;GAAE,OAAO;GAAK,SAAS;EAAa,CAAC;EAGvE,OAAO;GAAE;GAAO;EAAQ;CAC1B,CAAC;CAED,MAAM,eAAe,IAAI,IAAI,OAAO,KAAI,UAAS,iBAAiB,MAAM,QAAQ,MAAM,IAAI,CAAC,CAAC;CAE5F,KAAK,MAAM,OAAO,SAAS,KAAK,GAC9B,IAAI,CAAC,aAAa,IAAI,GAAG,GACvB,MAAM,IAAI,sBAAsB;EAAE,OAAO;EAAK,SAAS;CAAoB,CAAC;CAIhF,OAAO;AACT"}

package/dist/router.d.mts

@@ -0,0 +1,93 @@
+import { Layer } from "effect";
+import { HttpClient } from "effect/unstable/http";
+
+//#region src/router.d.ts
+/** A fetch handler, such as the one returned by an emulator factory. */
+type EmulatorFetch = (request: Request) => Promise<Response>;
+/** A loopback emulator process (http or https on 127.0.0.0/8, `::1`, or `localhost`). */
+type EmulatorUrlTarget = {
+  readonly kind: 'url';
+  readonly baseUrl: string;
+};
+/** An emulator fetch handler called in-process. */
+type EmulatorHandlerTarget = {
+  readonly kind: 'handler';
+  readonly fetch: EmulatorFetch;
+};
+type EmulatorTarget = EmulatorUrlTarget | EmulatorHandlerTarget;
+/**
+ * Maps one real origin (for example `https://ai-gateway.vercel.sh`) to an
+ * emulator target. Path and query of each request are kept.
+ */
+type EmulatorRoute<T extends EmulatorTarget = EmulatorTarget> = {
+  readonly origin: string;
+  readonly target: T;
+};
+declare const EmulatorRoute: {
+  /** Route an origin to a loopback emulator process. */readonly url: (origin: string, baseUrl: string) => EmulatorRoute<EmulatorUrlTarget>; /** Route an origin to an in-process emulator fetch handler. */
+  readonly handler: (origin: string, fetch: EmulatorFetch) => EmulatorRoute<EmulatorHandlerTarget>;
+};
+declare const EmulatorRouteInvalid_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: "EmulatorRouteInvalid";
+} & Readonly<A>;
+/** A route table that cannot be used: bad origin, duplicate origin, wrong target, or non-loopback base URL. */
+declare class EmulatorRouteInvalid extends EmulatorRouteInvalid_base<{
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+declare const EmulatorEnvironmentRefused_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: "EmulatorEnvironmentRefused";
+} & Readonly<A>;
+/** The router refused to build: `NODE_ENV` is `production`, or it could not be read. */
+declare class EmulatorEnvironmentRefused extends EmulatorEnvironmentRefused_base<{
+  readonly reason: 'production' | 'unreadable';
+}> {
+  get message(): string;
+}
+type EmulatorRouterError = EmulatorRouteInvalid | EmulatorEnvironmentRefused;
+declare const EmulatedHttpClient: {
+  /**
+   * `HttpClient` that rewrites each routed origin to its loopback emulator
+   * base URL (keeping path and query) and sends it through the host's real
+   * `HttpClient` underneath. Requests to any other origin fail closed with an
+   * `HttpClientError` that names only the origin.
+   *
+   * The check and rewrite run at the send step (the client's postprocess), so
+   * redirect follow-ups (`HttpClient.followRedirects` on top) and requests
+   * changed by a host's `HttpClient.mapRequest` are routed or refused too.
+   * With `FetchHttpClient` underneath, requests are sent with
+   * `redirect: 'manual'`: a 3xx from an emulator comes back to the caller as
+   * a 3xx and native fetch never follows it. Other `RequestInit` defaults are
+   * kept when they are provided where this layer is built or where the request
+   * runs; defaults provided only to the underlying `FetchHttpClient.layer`
+   * itself are replaced, so provide them around the whole client stack. Put
+   * `HttpClient.followRedirects` on top of this layer, never underneath it: a
+   * redirect loop below the route check sends follow-ups without it. Any
+   * other underlying client must not follow redirects by itself, because a
+   * redirect it follows internally never passes through the route table.
+   *
+   * Building fails with `EmulatorRouteInvalid` when a route is malformed,
+   * duplicated, not a `url` target, or not on loopback, and with
+   * `EmulatorEnvironmentRefused` when `NODE_ENV` is `production` or cannot be read.
+   */
+  readonly layer: (routes: ReadonlyArray<EmulatorRoute<EmulatorUrlTarget>>) => Layer.Layer<HttpClient.HttpClient, EmulatorRouterError, HttpClient.HttpClient>;
+};
+declare const InProcessHttpClient: {
+  /**
+   * `HttpClient` that turns each request to a routed origin into a web
+   * `Request` (method, URL, headers, and an Empty, Uint8Array, or string Raw
+   * body) and calls that route's fetch handler directly; the web `Response`
+   * comes back through `HttpClientResponse.fromWeb`. Other body kinds fail
+   * with an `HttpClientError` (`EncodeError`). Unknown origins fail closed
+   * with an `HttpClientError` that names only the origin.
+   *
+   * Building fails with `EmulatorRouteInvalid` for malformed, duplicated, or
+   * non-`handler` routes and with `EmulatorEnvironmentRefused` when
+   * `NODE_ENV` is `production` or cannot be read.
+   */
+  readonly layer: (routes: ReadonlyArray<EmulatorRoute<EmulatorHandlerTarget>>) => Layer.Layer<HttpClient.HttpClient, EmulatorRouterError>;
+};
+//#endregion
+export { EmulatedHttpClient, EmulatorEnvironmentRefused, EmulatorFetch, EmulatorHandlerTarget, EmulatorRoute, EmulatorRouteInvalid, EmulatorRouterError, EmulatorTarget, EmulatorUrlTarget, InProcessHttpClient };
+//# sourceMappingURL=router.d.mts.map

package/dist/router.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.mts","names":[],"sources":["../src/router.ts"],"mappings":";;;;AA0BkE;AAAA,KAAtD,aAAA,IAAiB,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;;KAG9C,iBAAA;EAAA,SACD,IAAA;EAAA,SACA,OAAO;AAAA;;KAIN,qBAAA;EAAA,SACD,IAAA;EAAA,SACA,KAAA,EAAO,aAAa;AAAA;AAAA,KAGnB,cAAA,GAAiB,iBAAA,GAAoB,qBAAqB;;AAHvC;AAG/B;;KAMY,aAAA,WAAwB,cAAA,GAAiB,cAAA;EAAA,SAC1C,MAAA;EAAA,SACA,MAAA,EAAQ,CAAA;AAAA;AAAA,cAGN,aAAA;EALY,qFAOH,OAAA,aAAoB,aAAA,CAAc,iBAAA,GAPH;EAAA,mCAY3B,KAAA,EAAS,aAAA,KAAgB,aAAA,CAAc,qBAAA;AAAA;AAAA,cAIvD,yBAAA;;;;cAGG,oBAAA,SAA6B,yBAAA;EAAA,SAC/B,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAAA,cAGd,+BAAA;;;;cAGY,0BAAA,SAAmC,+BAAA;EAAA,SACrC,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAAA,KAOH,mBAAA,GAAsB,oBAAA,GAAuB,0BAA0B;AAAA,cAuOtE,kBAAA;;;;;;;;;;;;AAjQyE;AAI5E;;;;;;;;;;;;2BAuRE,aAAA,CAAc,aAAA,CAAc,iBAAA,OACnC,KAAA,CAAM,KAAA,CAAM,UAAA,CAAW,UAAA,EAAY,mBAAA,EAAqB,UAAA,CAAW,UAAA;AAAA;AAAA,cAqE3D,mBAAA;;;;;;;;;;;;;2BAcD,aAAA,CAAc,aAAA,CAAc,qBAAA,OACnC,KAAA,CAAM,KAAA,CAAM,UAAA,CAAW,UAAA,EAAY,mBAAA;AAAA"}

package/dist/router.mjs

@@ -0,0 +1,259 @@
+import { Config, Data, Effect, Layer, Match, Option, Predicate } from "effect";
+import { FetchHttpClient, Headers as Headers$1, HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+//#region src/router.ts
+/**
+* Effect `HttpClient` routing to emulators.
+*
+* Hosts pick a transport by swapping `HttpClient` layers: `EmulatedHttpClient`
+* rewrites real origins to loopback emulator processes over the host's own
+* client, and `InProcessHttpClient` calls emulator fetch handlers directly.
+* Both fail closed on unknown origins and refuse to build when `NODE_ENV` is
+* `production`. The route check runs at the send step, so every request that
+* is actually sent (including redirect follow-ups and requests a host changes
+* with `HttpClient.mapRequest` on top) goes through the route table. Replay
+* lives in `@yolk-sdk/conformance/replay`; live traffic is the host's own
+* client.
+*
+* @experimental
+*/
+const EmulatorRoute = {
+	/** Route an origin to a loopback emulator process. */
+	url: (origin, baseUrl) => ({
+		origin,
+		target: {
+			kind: "url",
+			baseUrl
+		}
+	}),
+	/** Route an origin to an in-process emulator fetch handler. */
+	handler: (origin, fetch) => ({
+		origin,
+		target: {
+			kind: "handler",
+			fetch
+		}
+	})
+};
+/** A route table that cannot be used: bad origin, duplicate origin, wrong target, or non-loopback base URL. */
+var EmulatorRouteInvalid = class extends Data.TaggedError("EmulatorRouteInvalid") {
+	get message() {
+		return `Invalid emulator route: ${this.reason}`;
+	}
+};
+/** The router refused to build: `NODE_ENV` is `production`, or it could not be read. */
+var EmulatorEnvironmentRefused = class extends Data.TaggedError("EmulatorEnvironmentRefused") {
+	get message() {
+		return this.reason === "production" ? "Emulator routing refuses to run when NODE_ENV is production" : "Emulator routing could not read NODE_ENV";
+	}
+};
+/**
+* Fails when `NODE_ENV` is `production`. A missing `NODE_ENV` is allowed; an
+* unreadable one fails closed.
+*/
+const refuseProductionEnvironment = Effect.gen(function* () {
+	const nodeEnv = yield* Config.option(Config.String("NODE_ENV"));
+	return Option.getOrUndefined(nodeEnv);
+}).pipe(Effect.mapError(() => new EmulatorEnvironmentRefused({ reason: "unreadable" })), Effect.flatMap((nodeEnv) => nodeEnv?.trim().toLowerCase() === "production" ? Effect.fail(new EmulatorEnvironmentRefused({ reason: "production" })) : Effect.void));
+const ipv4LoopbackPattern = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+/**
+* True for `http:`/`https:` URLs whose host is loopback: `localhost`, `::1`,
+* or an IPv4 address in 127.0.0.0/8 (after WHATWG URL normalization).
+* IPv4-mapped IPv6 forms such as `[::ffff:127.0.0.1]` are rejected: the
+* allowlist stays minimal, and `127.0.0.1` says the same thing.
+*/
+const isLoopbackUrl = (input) => {
+	if (!URL.canParse(input)) return false;
+	const url = new URL(input);
+	if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+	const host = url.hostname.toLowerCase();
+	return host === "localhost" || host === "[::1]" || ipv4LoopbackPattern.test(host);
+};
+const validOrigin = (origin) => {
+	if (!URL.canParse(origin)) return new EmulatorRouteInvalid({ reason: "a route origin is not an absolute URL" });
+	const url = new URL(origin);
+	if (url.protocol !== "http:" && url.protocol !== "https:") return new EmulatorRouteInvalid({ reason: `origin ${url.origin} must be http or https` });
+	if (url.username !== "" || url.password !== "" || url.pathname !== "/" && url.pathname !== "" || url.search !== "" || url.hash !== "") return new EmulatorRouteInvalid({ reason: `origin ${url.origin} must be a bare origin without credentials, path, query, or hash` });
+	return url.origin;
+};
+const validBaseUrl = (origin, baseUrl) => {
+	if (!isLoopbackUrl(baseUrl)) return new EmulatorRouteInvalid({ reason: `the base URL for ${origin} must be http(s) on loopback (127.0.0.0/8, ::1, or localhost)` });
+	const url = new URL(baseUrl);
+	if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") return new EmulatorRouteInvalid({ reason: `the base URL for ${origin} must not carry credentials, a query, or a hash` });
+	return url;
+};
+const buildTable = (routes, kind, resolve) => Effect.gen(function* () {
+	const table = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const origin = validOrigin(route.origin);
+		if (origin instanceof EmulatorRouteInvalid) return yield* Effect.fail(origin);
+		if (route.target.kind !== kind) return yield* Effect.fail(new EmulatorRouteInvalid({ reason: `the route for ${origin} needs a ${kind} target` }));
+		if (table.has(origin)) return yield* Effect.fail(new EmulatorRouteInvalid({ reason: `duplicate route for ${origin}` }));
+		const resolved = resolve(origin, route.target);
+		if (resolved instanceof EmulatorRouteInvalid) return yield* Effect.fail(resolved);
+		table.set(origin, resolved);
+	}
+	return table;
+});
+const requestOrigin = (url) => URL.canParse(url) ? new URL(url).origin : void 0;
+/**
+* Fail-closed error for a request whose origin has no route. The attached
+* request carries only the method and origin (no path, query, headers, or
+* body), so the message never leaks more than the origin.
+*/
+const unroutedOriginError = (request, origin) => {
+	const label = origin ?? "unparseable-origin";
+	return new HttpClientError.HttpClientError({ reason: new HttpClientError.TransportError({
+		request: HttpClientRequest.make(request.method)(origin ?? ""),
+		description: `no emulator route for origin ${label}`
+	}) });
+};
+const joinPaths = (basePath, requestPath) => {
+	return `${basePath.endsWith("/") ? basePath.slice(0, -1) : basePath}${requestPath.startsWith("/") ? requestPath : `/${requestPath}`}`;
+};
+const rewriteToBase = (requestUrl, base) => {
+	const source = new URL(requestUrl);
+	const target = new URL(base.toString());
+	target.pathname = joinPaths(base.pathname, source.pathname);
+	target.search = source.search;
+	target.hash = source.hash;
+	return target.toString();
+};
+/**
+* Merge `RequestInit` values (later wins; `headers` are merged, not replaced).
+*/
+/** Name/value pairs of any `HeadersInit` shape (web `Headers`, pair list, or record). */
+const requestInitHeaderPairs = (headers) => {
+	if (headers instanceof Headers) return [...headers.entries()];
+	if (Array.isArray(headers)) return headers.flatMap((pair) => {
+		const [name, value] = pair;
+		return name === void 0 || value === void 0 ? [] : [[name, value]];
+	});
+	return Object.entries(headers);
+};
+const mergeRequestInit = (...inits) => {
+	const merged = {};
+	let headers = Headers$1.empty;
+	for (const init of inits) {
+		if (init === void 0) continue;
+		Object.assign(merged, init);
+		if (init.headers !== void 0) headers = Headers$1.merge(headers, Headers$1.fromInput(requestInitHeaderPairs(init.headers)));
+	}
+	return Object.keys(headers).length === 0 ? merged : {
+		...merged,
+		headers: { ...headers }
+	};
+};
+/**
+* Run `effect` with native fetch told not to follow redirects
+* (`redirect: 'manual'`). The `RequestInit` supplied here replaces the one the
+* underlying `FetchHttpClient` layer captured when it was built (Effect merges
+* the request-time context over the captured one), so the defaults visible
+* where the emulated layer is built and where the request runs are merged in
+* and only `redirect` is overridden. Only the `FetchHttpClient` transport reads
+* this service.
+*/
+const withManualRedirects = (buildInit) => (effect) => Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), (init) => Effect.provideService(effect, FetchHttpClient.RequestInit, mergeRequestInit(buildInit, Option.getOrUndefined(init), { redirect: "manual" })));
+const EmulatedHttpClient = { 
+/**
+* `HttpClient` that rewrites each routed origin to its loopback emulator
+* base URL (keeping path and query) and sends it through the host's real
+* `HttpClient` underneath. Requests to any other origin fail closed with an
+* `HttpClientError` that names only the origin.
+*
+* The check and rewrite run at the send step (the client's postprocess), so
+* redirect follow-ups (`HttpClient.followRedirects` on top) and requests
+* changed by a host's `HttpClient.mapRequest` are routed or refused too.
+* With `FetchHttpClient` underneath, requests are sent with
+* `redirect: 'manual'`: a 3xx from an emulator comes back to the caller as
+* a 3xx and native fetch never follows it. Other `RequestInit` defaults are
+* kept when they are provided where this layer is built or where the request
+* runs; defaults provided only to the underlying `FetchHttpClient.layer`
+* itself are replaced, so provide them around the whole client stack. Put
+* `HttpClient.followRedirects` on top of this layer, never underneath it: a
+* redirect loop below the route check sends follow-ups without it. Any
+* other underlying client must not follow redirects by itself, because a
+* redirect it follows internally never passes through the route table.
+*
+* Building fails with `EmulatorRouteInvalid` when a route is malformed,
+* duplicated, not a `url` target, or not on loopback, and with
+* `EmulatorEnvironmentRefused` when `NODE_ENV` is `production` or cannot be read.
+*/
+layer: (routes) => Layer.effect(HttpClient.HttpClient, Effect.gen(function* () {
+	yield* refuseProductionEnvironment;
+	const table = yield* buildTable(routes, "url", (origin, target) => validBaseUrl(origin, target.baseUrl));
+	const underlying = yield* HttpClient.HttpClient;
+	const manualRedirects = withManualRedirects(Option.getOrUndefined(yield* Effect.serviceOption(FetchHttpClient.RequestInit)));
+	const route = (request) => {
+		const origin = requestOrigin(request.url);
+		const base = origin === void 0 ? void 0 : table.get(origin);
+		return base === void 0 ? Effect.fail(unroutedOriginError(request, origin)) : Effect.succeed(HttpClientRequest.setUrl(request, rewriteToBase(request.url, base)));
+	};
+	return HttpClient.makeWith((request) => manualRedirects(underlying.postprocess(Effect.flatMap(request, route))), underlying.preprocess);
+})) };
+/** Error for a request body the in-process client cannot hand to a fetch handler. */
+const unsupportedBodyError = (request, kind) => new HttpClientError.HttpClientError({ reason: new HttpClientError.EncodeError({
+	request,
+	description: `in-process emulators accept only Empty, Uint8Array, and string Raw bodies (got ${kind})`
+}) });
+const webRequestBody = (request) => {
+	const body = request.body;
+	return Match.value(body).pipe(Match.tagsExhaustive({
+		Empty: () => Effect.succeed(void 0),
+		Uint8Array: ({ body: bytes }) => Effect.succeed(new Uint8Array(bytes)),
+		Raw: ({ body: raw }) => Predicate.isString(raw) ? Effect.succeed(raw) : Effect.fail(unsupportedBodyError(request, "non-string Raw")),
+		FormData: () => Effect.fail(unsupportedBodyError(request, "FormData")),
+		Stream: () => Effect.fail(unsupportedBodyError(request, "Stream"))
+	}));
+};
+const headerEntries = (headers) => Object.entries(headers);
+const InProcessHttpClient = { 
+/**
+* `HttpClient` that turns each request to a routed origin into a web
+* `Request` (method, URL, headers, and an Empty, Uint8Array, or string Raw
+* body) and calls that route's fetch handler directly; the web `Response`
+* comes back through `HttpClientResponse.fromWeb`. Other body kinds fail
+* with an `HttpClientError` (`EncodeError`). Unknown origins fail closed
+* with an `HttpClientError` that names only the origin.
+*
+* Building fails with `EmulatorRouteInvalid` for malformed, duplicated, or
+* non-`handler` routes and with `EmulatorEnvironmentRefused` when
+* `NODE_ENV` is `production` or cannot be read.
+*/
+layer: (routes) => Layer.effect(HttpClient.HttpClient, Effect.gen(function* () {
+	yield* refuseProductionEnvironment;
+	const table = yield* buildTable(routes, "handler", (_origin, target) => target.fetch);
+	return HttpClient.make((request, url, signal) => Effect.gen(function* () {
+		const handler = table.get(url.origin);
+		if (handler === void 0) return yield* Effect.fail(unroutedOriginError(request, url.origin));
+		const body = yield* webRequestBody(request);
+		const webRequest = yield* Effect.try({
+			try: () => {
+				const init = {
+					method: request.method,
+					headers: headerEntries(request.headers),
+					signal
+				};
+				if (body !== void 0) init.body = body;
+				return new Request(url.toString(), init);
+			},
+			catch: (cause) => new HttpClientError.HttpClientError({ reason: new HttpClientError.EncodeError({
+				request,
+				cause,
+				description: "could not build a web Request for the in-process emulator"
+			}) })
+		});
+		const response = yield* Effect.tryPromise({
+			try: () => handler(webRequest),
+			catch: (cause) => new HttpClientError.HttpClientError({ reason: new HttpClientError.TransportError({
+				request,
+				cause,
+				description: "the in-process emulator handler failed"
+			}) })
+		});
+		return HttpClientResponse.fromWeb(request, response);
+	}));
+})) };
+//#endregion
+export { EmulatedHttpClient, EmulatorEnvironmentRefused, EmulatorRoute, EmulatorRouteInvalid, InProcessHttpClient };
+
+//# sourceMappingURL=router.mjs.map

package/dist/router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.mjs","names":["HttpHeaders"],"sources":["../src/router.ts"],"sourcesContent":["/**\n * Effect `HttpClient` routing to emulators.\n *\n * Hosts pick a transport by swapping `HttpClient` layers: `EmulatedHttpClient`\n * rewrites real origins to loopback emulator processes over the host's own\n * client, and `InProcessHttpClient` calls emulator fetch handlers directly.\n * Both fail closed on unknown origins and refuse to build when `NODE_ENV` is\n * `production`. The route check runs at the send step, so every request that\n * is actually sent (including redirect follow-ups and requests a host changes\n * with `HttpClient.mapRequest` on top) goes through the route table. Replay\n * lives in `@yolk-sdk/conformance/replay`; live traffic is the host's own\n * client.\n *\n * @experimental\n */\nimport { Config, Data, Effect, Layer, Match, Option, Predicate } from 'effect'\nimport {\n  FetchHttpClient,\n  Headers as HttpHeaders,\n  HttpClient,\n  HttpClientError,\n  HttpClientRequest,\n  HttpClientResponse\n} from 'effect/unstable/http'\n\n/** A fetch handler, such as the one returned by an emulator factory. */\nexport type EmulatorFetch = (request: Request) => Promise<Response>\n\n/** A loopback emulator process (http or https on 127.0.0.0/8, `::1`, or `localhost`). */\nexport type EmulatorUrlTarget = {\n  readonly kind: 'url'\n  readonly baseUrl: string\n}\n\n/** An emulator fetch handler called in-process. */\nexport type EmulatorHandlerTarget = {\n  readonly kind: 'handler'\n  readonly fetch: EmulatorFetch\n}\n\nexport type EmulatorTarget = EmulatorUrlTarget | EmulatorHandlerTarget\n\n/**\n * Maps one real origin (for example `https://ai-gateway.vercel.sh`) to an\n * emulator target. Path and query of each request are kept.\n */\nexport type EmulatorRoute<T extends EmulatorTarget = EmulatorTarget> = {\n  readonly origin: string\n  readonly target: T\n}\n\nexport const EmulatorRoute = {\n  /** Route an origin to a loopback emulator process. */\n  url: (origin: string, baseUrl: string): EmulatorRoute<EmulatorUrlTarget> => ({\n    origin,\n    target: { kind: 'url', baseUrl }\n  }),\n  /** Route an origin to an in-process emulator fetch handler. */\n  handler: (origin: string, fetch: EmulatorFetch): EmulatorRoute<EmulatorHandlerTarget> => ({\n    origin,\n    target: { kind: 'handler', fetch }\n  })\n} as const\n\n/** A route table that cannot be used: bad origin, duplicate origin, wrong target, or non-loopback base URL. */\nexport class EmulatorRouteInvalid extends Data.TaggedError('EmulatorRouteInvalid')<{\n  readonly reason: string\n}> {\n  override get message(): string {\n    return `Invalid emulator route: ${this.reason}`\n  }\n}\n\n/** The router refused to build: `NODE_ENV` is `production`, or it could not be read. */\nexport class EmulatorEnvironmentRefused extends Data.TaggedError('EmulatorEnvironmentRefused')<{\n  readonly reason: 'production' | 'unreadable'\n}> {\n  override get message(): string {\n    return this.reason === 'production'\n      ? 'Emulator routing refuses to run when NODE_ENV is production'\n      : 'Emulator routing could not read NODE_ENV'\n  }\n}\n\nexport type EmulatorRouterError = EmulatorRouteInvalid | EmulatorEnvironmentRefused\n\n/**\n * Fails when `NODE_ENV` is `production`. A missing `NODE_ENV` is allowed; an\n * unreadable one fails closed.\n */\nconst refuseProductionEnvironment: Effect.Effect<void, EmulatorEnvironmentRefused> = Effect.gen(\n  function* () {\n    const nodeEnv = yield* Config.option(Config.String('NODE_ENV'))\n\n    return Option.getOrUndefined(nodeEnv)\n  }\n).pipe(\n  Effect.mapError(() => new EmulatorEnvironmentRefused({ reason: 'unreadable' })),\n  Effect.flatMap(nodeEnv =>\n    nodeEnv?.trim().toLowerCase() === 'production'\n      ? Effect.fail(new EmulatorEnvironmentRefused({ reason: 'production' }))\n      : Effect.void\n  )\n)\n\nconst ipv4LoopbackPattern = /^127\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$/\n\n/**\n * True for `http:`/`https:` URLs whose host is loopback: `localhost`, `::1`,\n * or an IPv4 address in 127.0.0.0/8 (after WHATWG URL normalization).\n * IPv4-mapped IPv6 forms such as `[::ffff:127.0.0.1]` are rejected: the\n * allowlist stays minimal, and `127.0.0.1` says the same thing.\n */\nconst isLoopbackUrl = (input: string): boolean => {\n  if (!URL.canParse(input)) {\n    return false\n  }\n\n  const url = new URL(input)\n\n  if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n    return false\n  }\n\n  const host = url.hostname.toLowerCase()\n\n  return host === 'localhost' || host === '[::1]' || ipv4LoopbackPattern.test(host)\n}\n\nconst validOrigin = (origin: string): string | EmulatorRouteInvalid => {\n  if (!URL.canParse(origin)) {\n    return new EmulatorRouteInvalid({ reason: 'a route origin is not an absolute URL' })\n  }\n\n  const url = new URL(origin)\n\n  if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n    return new EmulatorRouteInvalid({ reason: `origin ${url.origin} must be http or https` })\n  }\n\n  if (\n    url.username !== '' ||\n    url.password !== '' ||\n    (url.pathname !== '/' && url.pathname !== '') ||\n    url.search !== '' ||\n    url.hash !== ''\n  ) {\n    return new EmulatorRouteInvalid({\n      reason: `origin ${url.origin} must be a bare origin without credentials, path, query, or hash`\n    })\n  }\n\n  return url.origin\n}\n\nconst validBaseUrl = (origin: string, baseUrl: string): URL | EmulatorRouteInvalid => {\n  if (!isLoopbackUrl(baseUrl)) {\n    return new EmulatorRouteInvalid({\n      reason: `the base URL for ${origin} must be http(s) on loopback (127.0.0.0/8, ::1, or localhost)`\n    })\n  }\n\n  const url = new URL(baseUrl)\n\n  if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') {\n    return new EmulatorRouteInvalid({\n      reason: `the base URL for ${origin} must not carry credentials, a query, or a hash`\n    })\n  }\n\n  return url\n}\n\ntype RouteTable<A> = ReadonlyMap<string, A>\n\nconst buildTable = <T extends EmulatorTarget, A>(\n  routes: ReadonlyArray<EmulatorRoute<T>>,\n  kind: T['kind'],\n  resolve: (origin: string, target: T) => A | EmulatorRouteInvalid\n): Effect.Effect<RouteTable<A>, EmulatorRouteInvalid> =>\n  Effect.gen(function* () {\n    const table = new Map<string, A>()\n\n    for (const route of routes) {\n      const origin = validOrigin(route.origin)\n\n      if (origin instanceof EmulatorRouteInvalid) {\n        return yield* Effect.fail(origin)\n      }\n\n      if (route.target.kind !== kind) {\n        return yield* Effect.fail(\n          new EmulatorRouteInvalid({ reason: `the route for ${origin} needs a ${kind} target` })\n        )\n      }\n\n      if (table.has(origin)) {\n        return yield* Effect.fail(\n          new EmulatorRouteInvalid({ reason: `duplicate route for ${origin}` })\n        )\n      }\n\n      const resolved = resolve(origin, route.target)\n\n      if (resolved instanceof EmulatorRouteInvalid) {\n        return yield* Effect.fail(resolved)\n      }\n\n      table.set(origin, resolved)\n    }\n\n    return table\n  })\n\nconst requestOrigin = (url: string): string | undefined =>\n  URL.canParse(url) ? new URL(url).origin : undefined\n\n/**\n * Fail-closed error for a request whose origin has no route. The attached\n * request carries only the method and origin (no path, query, headers, or\n * body), so the message never leaks more than the origin.\n */\nconst unroutedOriginError = (\n  request: HttpClientRequest.HttpClientRequest,\n  origin: string | undefined\n) => {\n  const label = origin ?? 'unparseable-origin'\n\n  return new HttpClientError.HttpClientError({\n    reason: new HttpClientError.TransportError({\n      request: HttpClientRequest.make(request.method)(origin ?? ''),\n      description: `no emulator route for origin ${label}`\n    })\n  })\n}\n\nconst joinPaths = (basePath: string, requestPath: string): string => {\n  const prefix = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath\n\n  return `${prefix}${requestPath.startsWith('/') ? requestPath : `/${requestPath}`}`\n}\n\nconst rewriteToBase = (requestUrl: string, base: URL): string => {\n  const source = new URL(requestUrl)\n  const target = new URL(base.toString())\n\n  target.pathname = joinPaths(base.pathname, source.pathname)\n  target.search = source.search\n  target.hash = source.hash\n\n  return target.toString()\n}\n\n/**\n * Merge `RequestInit` values (later wins; `headers` are merged, not replaced).\n */\n/** Name/value pairs of any `HeadersInit` shape (web `Headers`, pair list, or record). */\nconst requestInitHeaderPairs = (headers: HeadersInit): ReadonlyArray<readonly [string, string]> => {\n  if (headers instanceof Headers) return [...headers.entries()]\n\n  if (Array.isArray(headers)) {\n    return headers.flatMap(pair => {\n      const [name, value] = pair\n\n      return name === undefined || value === undefined ? [] : [[name, value] as const]\n    })\n  }\n\n  return Object.entries(headers)\n}\n\nconst mergeRequestInit = (\n  ...inits: ReadonlyArray<globalThis.RequestInit | undefined>\n): globalThis.RequestInit => {\n  const merged: globalThis.RequestInit = {}\n  // Effect's `Headers.fromInput` never throws (unlike web `Headers`), so an invalid host default\n  // surfaces from fetch as a typed transport error instead of a defect here.\n  let headers = HttpHeaders.empty\n\n  for (const init of inits) {\n    if (init === undefined) continue\n\n    Object.assign(merged, init)\n\n    if (init.headers !== undefined) {\n      headers = HttpHeaders.merge(\n        headers,\n        HttpHeaders.fromInput(requestInitHeaderPairs(init.headers))\n      )\n    }\n  }\n\n  return Object.keys(headers).length === 0 ? merged : { ...merged, headers: { ...headers } }\n}\n\n/**\n * Run `effect` with native fetch told not to follow redirects\n * (`redirect: 'manual'`). The `RequestInit` supplied here replaces the one the\n * underlying `FetchHttpClient` layer captured when it was built (Effect merges\n * the request-time context over the captured one), so the defaults visible\n * where the emulated layer is built and where the request runs are merged in\n * and only `redirect` is overridden. Only the `FetchHttpClient` transport reads\n * this service.\n */\nconst withManualRedirects =\n  (buildInit: globalThis.RequestInit | undefined) =>\n  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n    Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), init =>\n      Effect.provideService(\n        effect,\n        FetchHttpClient.RequestInit,\n        mergeRequestInit(buildInit, Option.getOrUndefined(init), { redirect: 'manual' })\n      )\n    )\n\nexport const EmulatedHttpClient = {\n  /**\n   * `HttpClient` that rewrites each routed origin to its loopback emulator\n   * base URL (keeping path and query) and sends it through the host's real\n   * `HttpClient` underneath. Requests to any other origin fail closed with an\n   * `HttpClientError` that names only the origin.\n   *\n   * The check and rewrite run at the send step (the client's postprocess), so\n   * redirect follow-ups (`HttpClient.followRedirects` on top) and requests\n   * changed by a host's `HttpClient.mapRequest` are routed or refused too.\n   * With `FetchHttpClient` underneath, requests are sent with\n   * `redirect: 'manual'`: a 3xx from an emulator comes back to the caller as\n   * a 3xx and native fetch never follows it. Other `RequestInit` defaults are\n   * kept when they are provided where this layer is built or where the request\n   * runs; defaults provided only to the underlying `FetchHttpClient.layer`\n   * itself are replaced, so provide them around the whole client stack. Put\n   * `HttpClient.followRedirects` on top of this layer, never underneath it: a\n   * redirect loop below the route check sends follow-ups without it. Any\n   * other underlying client must not follow redirects by itself, because a\n   * redirect it follows internally never passes through the route table.\n   *\n   * Building fails with `EmulatorRouteInvalid` when a route is malformed,\n   * duplicated, not a `url` target, or not on loopback, and with\n   * `EmulatorEnvironmentRefused` when `NODE_ENV` is `production` or cannot be read.\n   */\n  layer: (\n    routes: ReadonlyArray<EmulatorRoute<EmulatorUrlTarget>>\n  ): Layer.Layer<HttpClient.HttpClient, EmulatorRouterError, HttpClient.HttpClient> =>\n    Layer.effect(\n      HttpClient.HttpClient,\n      Effect.gen(function* () {\n        yield* refuseProductionEnvironment\n\n        const table = yield* buildTable(routes, 'url', (origin, target: EmulatorUrlTarget) =>\n          validBaseUrl(origin, target.baseUrl)\n        )\n\n        const underlying = yield* HttpClient.HttpClient\n\n        // `RequestInit` defaults visible where this layer is built (for example provided around the\n        // whole client stack) are kept for routed requests.\n        const manualRedirects = withManualRedirects(\n          Option.getOrUndefined(yield* Effect.serviceOption(FetchHttpClient.RequestInit))\n        )\n\n        const route = (request: HttpClientRequest.HttpClientRequest) => {\n          const origin = requestOrigin(request.url)\n          const base = origin === undefined ? undefined : table.get(origin)\n\n          return base === undefined\n            ? Effect.fail(unroutedOriginError(request, origin))\n            : Effect.succeed(HttpClientRequest.setUrl(request, rewriteToBase(request.url, base)))\n        }\n\n        // Route in postprocess, not preprocess: every request sent goes through postprocess, while\n        // `followRedirects` skips preprocess for follow-ups and `mapRequest` runs after it.\n        return HttpClient.makeWith(\n          request => manualRedirects(underlying.postprocess(Effect.flatMap(request, route))),\n          underlying.preprocess\n        )\n      })\n    )\n} as const\n\n/** Error for a request body the in-process client cannot hand to a fetch handler. */\nconst unsupportedBodyError = (request: HttpClientRequest.HttpClientRequest, kind: string) =>\n  new HttpClientError.HttpClientError({\n    reason: new HttpClientError.EncodeError({\n      request,\n      description: `in-process emulators accept only Empty, Uint8Array, and string Raw bodies (got ${kind})`\n    })\n  })\n\nconst webRequestBody = (\n  request: HttpClientRequest.HttpClientRequest\n): Effect.Effect<BodyInit | undefined, HttpClientError.HttpClientError> => {\n  const body = request.body\n\n  return Match.value(body).pipe(\n    Match.tagsExhaustive({\n      Empty: () => Effect.succeed(undefined),\n      // Copy into an ArrayBuffer-backed view, as `Request` requires.\n      Uint8Array: ({ body: bytes }) => Effect.succeed<BodyInit>(new Uint8Array(bytes)),\n      Raw: ({ body: raw }) =>\n        Predicate.isString(raw)\n          ? Effect.succeed<BodyInit>(raw)\n          : Effect.fail(unsupportedBodyError(request, 'non-string Raw')),\n      FormData: () => Effect.fail(unsupportedBodyError(request, 'FormData')),\n      Stream: () => Effect.fail(unsupportedBodyError(request, 'Stream'))\n    })\n  )\n}\n\nconst headerEntries = (headers: Readonly<Record<string, string>>): Array<[string, string]> =>\n  Object.entries(headers)\n\nexport const InProcessHttpClient = {\n  /**\n   * `HttpClient` that turns each request to a routed origin into a web\n   * `Request` (method, URL, headers, and an Empty, Uint8Array, or string Raw\n   * body) and calls that route's fetch handler directly; the web `Response`\n   * comes back through `HttpClientResponse.fromWeb`. Other body kinds fail\n   * with an `HttpClientError` (`EncodeError`). Unknown origins fail closed\n   * with an `HttpClientError` that names only the origin.\n   *\n   * Building fails with `EmulatorRouteInvalid` for malformed, duplicated, or\n   * non-`handler` routes and with `EmulatorEnvironmentRefused` when\n   * `NODE_ENV` is `production` or cannot be read.\n   */\n  layer: (\n    routes: ReadonlyArray<EmulatorRoute<EmulatorHandlerTarget>>\n  ): Layer.Layer<HttpClient.HttpClient, EmulatorRouterError> =>\n    Layer.effect(\n      HttpClient.HttpClient,\n      Effect.gen(function* () {\n        yield* refuseProductionEnvironment\n\n        const table = yield* buildTable(\n          routes,\n          'handler',\n          (_origin, target: EmulatorHandlerTarget) => target.fetch\n        )\n\n        return HttpClient.make((request, url, signal) =>\n          Effect.gen(function* () {\n            const handler = table.get(url.origin)\n\n            if (handler === undefined) {\n              return yield* Effect.fail(unroutedOriginError(request, url.origin))\n            }\n\n            const body = yield* webRequestBody(request)\n\n            const webRequest = yield* Effect.try({\n              try: () => {\n                const init: RequestInit = {\n                  method: request.method,\n                  headers: headerEntries(request.headers),\n                  signal\n                }\n\n                if (body !== undefined) {\n                  init.body = body\n                }\n\n                return new Request(url.toString(), init)\n              },\n              catch: cause =>\n                new HttpClientError.HttpClientError({\n                  reason: new HttpClientError.EncodeError({\n                    request,\n                    cause,\n                    description: 'could not build a web Request for the in-process emulator'\n                  })\n                })\n            })\n\n            const response = yield* Effect.tryPromise({\n              try: () => handler(webRequest),\n              catch: cause =>\n                new HttpClientError.HttpClientError({\n                  reason: new HttpClientError.TransportError({\n                    request,\n                    cause,\n                    description: 'the in-process emulator handler failed'\n                  })\n                })\n            })\n\n            return HttpClientResponse.fromWeb(request, response)\n          })\n        )\n      })\n    )\n} as const\n"],"mappings":"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"}

package/dist/stateful-core.d.mts

@@ -0,0 +1,17 @@
+import { CoreDispatch, StatefulCore } from "./stateful-emulator.mjs";
+
+//#region src/stateful-core.d.ts
+type StatefulCoreOptions<State> = {
+  /** The core emulator's name. */readonly name: string; /** The state the runtime starts from (already built from the seed). */
+  readonly initial: State; /** Decode a state the core is handed (a string is why it is invalid). */
+  readonly decodeState: (value: unknown) => State | string; /** The emulator's input-invalid error for an invalid seed. */
+  readonly inputInvalid: (input: 'seed', reason: string) => Error;
+};
+/**
+ * The `createCore` of a stateful emulator: a core custom runtime seeded with `initial`, whose
+ * state the wrapper reads, snapshots, and restores.
+ */
+declare const statefulCoreRuntime: <State extends object>(options: StatefulCoreOptions<State>) => (dispatch: CoreDispatch<State>) => Promise<StatefulCore<State>>;
+//#endregion
+export { StatefulCoreOptions, statefulCoreRuntime };
+//# sourceMappingURL=stateful-core.d.mts.map

package/dist/stateful-core.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful-core.d.mts","names":[],"sources":["../src/stateful-core.ts"],"mappings":";;;KAcY,mBAAA;2CAED,IAAA,UAFoB;EAAA,SAIpB,OAAA,EAAS,KAAA,EAAA;EAAA,SAET,WAAA,GAAc,KAAA,cAAmB,KAAA,WAEgB;EAAA,SAAjD,YAAA,GAAe,KAAA,UAAe,MAAA,aAAmB,KAAA;AAAA;;;;;cAO/C,mBAAA,yBACY,OAAA,EAAS,mBAAA,CAAoB,KAAA,OAC7C,QAAA,EAAU,YAAA,CAAa,KAAA,MAAS,OAAA,CAAQ,YAAA,CAAa,KAAA"}

package/dist/stateful-core.mjs

@@ -0,0 +1,41 @@
+import { Predicate } from "effect";
+//#region src/stateful-core.ts
+/**
+* The `createCore` of a stateful emulator: a core custom runtime seeded with `initial`, whose
+* state the wrapper reads, snapshots, and restores.
+*/
+const statefulCoreRuntime = (options) => async (dispatch) => {
+	const { decodeState, initial, inputInvalid } = options;
+	const core = await import("@emulators/core");
+	const definition = core.defineEmulator({
+		name: options.name,
+		cors: false,
+		state: () => initial,
+		validateSeed: (value) => {
+			const decoded = decodeState(value);
+			if (Predicate.isString(decoded)) throw inputInvalid("seed", decoded);
+			return decoded;
+		},
+		setup: ({ app, state }) => {
+			app.post("*", (context) => dispatch(state, context.req.raw));
+		}
+	});
+	const runtime = await core.createCustomRuntime(definition, { seed: initial });
+	return {
+		fetch: (request) => runtime.fetch(request),
+		baseUrl: runtime.baseUrl,
+		snapshot: () => runtime.snapshot().state,
+		restore: (state) => {
+			const current = runtime.snapshot();
+			return runtime.restore({
+				...current,
+				state
+			});
+		},
+		close: () => runtime.close()
+	};
+};
+//#endregion
+export { statefulCoreRuntime };
+
+//# sourceMappingURL=stateful-core.mjs.map

package/dist/stateful-core.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful-core.mjs","names":[],"sources":["../src/stateful-core.ts"],"sourcesContent":["/**\n * The `@emulators/core` adapter of the stateful wrapper (internal; Node-only): the `createCore`\n * argument of `makeStatefulEmulator` and its variants, shared by every subpath on\n * `src/stateful-emulator.ts`. It loads the core lazily (the core imports Node builtins and reads\n * files at import time), defines a custom emulator whose only route runs the wrapper's dispatch\n * for every forwarded request, and adapts its runtime to `StatefulCore`. The wrapper itself never\n * imports the core, so it stays runtime-portable.\n *\n * @experimental\n */\nimport type { EmulatorSnapshot } from '@emulators/core'\nimport { Predicate } from 'effect'\nimport type { CoreDispatch, StatefulCore } from './stateful-emulator.ts'\n\nexport type StatefulCoreOptions<State> = {\n  /** The core emulator's name. */\n  readonly name: string\n  /** The state the runtime starts from (already built from the seed). */\n  readonly initial: State\n  /** Decode a state the core is handed (a string is why it is invalid). */\n  readonly decodeState: (value: unknown) => State | string\n  /** The emulator's input-invalid error for an invalid seed. */\n  readonly inputInvalid: (input: 'seed', reason: string) => Error\n}\n\n/**\n * The `createCore` of a stateful emulator: a core custom runtime seeded with `initial`, whose\n * state the wrapper reads, snapshots, and restores.\n */\nexport const statefulCoreRuntime =\n  <State extends object>(options: StatefulCoreOptions<State>) =>\n  async (dispatch: CoreDispatch<State>): Promise<StatefulCore<State>> => {\n    const { decodeState, initial, inputInvalid } = options\n\n    // Loaded lazily: the core imports Node builtins and reads files at import time.\n    const core = await import('@emulators/core')\n\n    const definition = core.defineEmulator<State>({\n      name: options.name,\n      cors: false,\n      state: () => initial,\n      validateSeed: value => {\n        const decoded = decodeState(value)\n\n        if (Predicate.isString(decoded)) {\n          throw inputInvalid('seed', decoded)\n        }\n\n        return decoded\n      },\n      // The wrapper matched the route already and forwards every admitted request as a POST.\n      setup: ({ app, state }) => {\n        app.post('*', context => dispatch(state, context.req.raw))\n      }\n    })\n\n    const runtime = await core.createCustomRuntime(definition, { seed: initial })\n\n    return {\n      fetch: request => runtime.fetch(request),\n      baseUrl: runtime.baseUrl,\n      snapshot: () => runtime.snapshot().state,\n      restore: state => {\n        const current: EmulatorSnapshot<State> = runtime.snapshot()\n\n        return runtime.restore({ ...current, state })\n      },\n      close: () => runtime.close()\n    }\n  }\n"],"mappings":";;;;;;AA6BA,MAAa,uBACY,YACvB,OAAO,aAAgE;CACrE,MAAM,EAAE,aAAa,SAAS,iBAAiB;CAG/C,MAAM,OAAO,MAAM,OAAO;CAE1B,MAAM,aAAa,KAAK,eAAsB;EAC5C,MAAM,QAAQ;EACd,MAAM;EACN,aAAa;EACb,eAAc,UAAS;GACrB,MAAM,UAAU,YAAY,KAAK;GAEjC,IAAI,UAAU,SAAS,OAAO,GAC5B,MAAM,aAAa,QAAQ,OAAO;GAGpC,OAAO;EACT;EAEA,QAAQ,EAAE,KAAK,YAAY;GACzB,IAAI,KAAK,MAAK,YAAW,SAAS,OAAO,QAAQ,IAAI,GAAG,CAAC;EAC3D;CACF,CAAC;CAED,MAAM,UAAU,MAAM,KAAK,oBAAoB,YAAY,EAAE,MAAM,QAAQ,CAAC;CAE5E,OAAO;EACL,QAAO,YAAW,QAAQ,MAAM,OAAO;EACvC,SAAS,QAAQ;EACjB,gBAAgB,QAAQ,SAAS,EAAE;EACnC,UAAS,UAAS;GAChB,MAAM,UAAmC,QAAQ,SAAS;GAE1D,OAAO,QAAQ,QAAQ;IAAE,GAAG;IAAS;GAAM,CAAC;EAC9C;EACA,aAAa,QAAQ,MAAM;CAC7B;AACF"}