@yolk-sdk/conformance 0.1.0-canary.96

package/dist/replay.mjs

@@ -0,0 +1,272 @@
+import { decodeBase64Bytes, headerRecord, isNullBodyStatus, normalizeWireUrl, parseJsonText, redactHeaders, requestBodyText, urlMatchesPattern } from "./wire-internal.mjs";
+import { isWireBase64BodyResponse, isWireStreamResponse } from "./fixture.mjs";
+import { Cause, Context, Data, Effect, Exit, Fiber, Layer, Match, Option, Predicate, Ref, Result } from "effect";
+import { HttpClient, HttpClientError, HttpClientResponse } from "effect/unstable/http";
+//#region src/replay.ts
+/**
+* Offline replay of recorded wire fixtures as an Effect `HttpClient`.
+*
+* Replay never performs network I/O. Requests are matched by method and
+* normalized absolute URL (hash removed, query parameters sorted); each
+* recorded exchange is consumed once, in recorded order among exchanges with
+* the same method and URL. A request with no remaining match fails closed with
+* a typed `HttpClientError` and is still written to the ledger.
+*
+* @experimental
+*/
+const WireFault = Data.taggedEnum();
+/** Cause attached to a body stream failed by `FailAfterChunks`. */
+var WireTransportFault = class extends Data.TaggedError("WireTransportFault") {
+	get message() {
+		return `injected transport failure after ${this.afterChunks} chunks`;
+	}
+};
+var ReplayLedger = class extends Context.Service()("@yolk-sdk/conformance/ReplayLedger") {};
+const requestKey = (method, normalizedUrl) => `${method.toUpperCase()} ${normalizedUrl}`;
+const faultMatches = (match, method, normalizedUrl) => (match?.method === void 0 || match.method.toUpperCase() === method.toUpperCase()) && (match?.url === void 0 || urlMatchesPattern(match.url, normalizedUrl));
+const candidatesFrom = (fixtures) => {
+	const candidates = [];
+	for (const fixture of fixtures) fixture.exchanges.forEach((exchange, exchangeIndex) => {
+		candidates.push({
+			id: candidates.length,
+			key: requestKey(exchange.request.method, normalizeWireUrl(exchange.request.url)),
+			fixtureId: fixture.id,
+			exchangeIndex,
+			exchange
+		});
+	});
+	return candidates;
+};
+const chunkBytes = (chunk) => Predicate.isString(chunk) ? Option.some(new TextEncoder().encode(chunk)) : decodeBase64Bytes(chunk.base64);
+const chunkFaultProblem = (fault, recorded) => {
+	if (!Number.isSafeInteger(fault.chunks) || fault.chunks < 0) return `${fault._tag} needs a non-negative integer chunk count`;
+	return (WireFault.$is("FailAfterChunks")(fault) ? fault.chunks <= recorded : fault.chunks < recorded) ? void 0 : `${fault._tag} after ${fault.chunks} chunk(s) cannot apply to a response with ${recorded} recorded chunk(s)`;
+};
+/** Resolve the exact bytes to replay, or why the recording cannot be replayed as requested. */
+const replayBody = (response, fault) => {
+	if (isWireStreamResponse(response)) {
+		const chunks = Option.all(response.chunks.map(chunkBytes));
+		if (Option.isNone(chunks)) return Result.fail("a recorded chunk is not valid base64");
+		const problem = fault === void 0 ? void 0 : chunkFaultProblem(fault, chunks.value.length);
+		return problem === void 0 ? Result.succeed({
+			kind: "chunks",
+			chunks: chunks.value,
+			fault
+		}) : Result.fail(problem);
+	}
+	if (fault !== void 0) return Result.fail(`${fault._tag} cannot apply to a whole-body response`);
+	if (isWireBase64BodyResponse(response)) return Option.match(decodeBase64Bytes(response.bodyBase64), {
+		onNone: () => Result.fail("the recorded bodyBase64 is not valid base64"),
+		onSome: (bytes) => Result.succeed({
+			kind: "body",
+			body: new Uint8Array(bytes)
+		})
+	});
+	return Result.succeed({
+		kind: "body",
+		body: response.body
+	});
+};
+/**
+* Strictly pull-driven body: one `Uint8Array` per recorded chunk (including
+* empty ones), and chunk `k` is produced only when the consumer pulls it,
+* never ahead of demand. The fault (already validated against the chunk count)
+* applies when the consumer pulls past `fault.chunks` chunks.
+*/
+const bodyReadable = (chunks, fault) => {
+	let next = 0;
+	let faultApplied = false;
+	let cancelled = false;
+	let held;
+	const emitNext = (controller) => {
+		const chunk = chunks[next];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		next += 1;
+		controller.enqueue(chunk);
+	};
+	return new ReadableStream({
+		pull: (controller) => {
+			if (fault === void 0 || faultApplied || next !== fault.chunks) {
+				emitNext(controller);
+				return;
+			}
+			faultApplied = true;
+			return Match.valueTags(fault, {
+				FailAfterChunks: ({ chunks: afterChunks }) => controller.error(new WireTransportFault({ afterChunks })),
+				TruncateAfterChunks: () => controller.close(),
+				HoldAfterChunks: ({ release }) => {
+					const fiber = Effect.runFork(release);
+					held = fiber;
+					if (cancelled) {
+						held = void 0;
+						return Effect.runPromise(Fiber.interrupt(fiber));
+					}
+					return Effect.runPromise(Fiber.await(fiber)).then((exit) => {
+						held = void 0;
+						if (cancelled) return;
+						if (Exit.isSuccess(exit)) emitNext(controller);
+						else controller.error(Cause.squash(exit.cause));
+					});
+				}
+			});
+		},
+		cancel: () => {
+			cancelled = true;
+			if (held === void 0) return;
+			return Effect.runPromise(Fiber.interrupt(held));
+		}
+	}, { highWaterMark: 0 });
+};
+const webResponse = (status, headers, body) => {
+	const init = {
+		status,
+		headers: { ...headers }
+	};
+	if (isNullBodyStatus(status)) return new Response(null, init);
+	if (body.kind === "body") return new Response(body.body, init);
+	return new Response(bodyReadable(body.chunks, body.fault), init);
+};
+const unmatchedError = (request) => new HttpClientError.HttpClientError({ reason: new HttpClientError.TransportError({
+	request,
+	description: "replay has no remaining recorded exchange"
+}) });
+const invalidRecordingError = (request, cause) => new HttpClientError.HttpClientError({ reason: new HttpClientError.TransportError({
+	request,
+	cause,
+	description: "recorded response could not be replayed"
+}) });
+/**
+* Cause attached to the `HttpClientError` (reason `TransportError`) of a request
+* whose recording could not be replayed. Retrying clients may retry past it;
+* check the ledger for an `invalid` outcome.
+*/
+var WireReplayInvalid = class extends Data.TaggedError("WireReplayInvalid") {
+	get message() {
+		return this.reason;
+	}
+};
+/**
+* Build a replay `HttpClient` and its ledger over the given fixtures. Each
+* call has independent consumption, attempt, and ledger state.
+*/
+const makeReplayHttpClient = (fixtures, options = {}) => Effect.gen(function* () {
+	const candidates = candidatesFrom(fixtures);
+	const faults = options.faults ?? [];
+	const state = yield* Ref.make({
+		consumed: /* @__PURE__ */ new Set(),
+		attempts: /* @__PURE__ */ new Map(),
+		entries: []
+	});
+	const decide = (method, normalizedUrl, entry) => Ref.modify(state, (current) => {
+		const key = requestKey(method, normalizedUrl);
+		const attempt = (current.attempts.get(key) ?? 0) + 1;
+		const attempts = new Map(current.attempts).set(key, attempt);
+		const fields = {
+			...entry,
+			attempt,
+			match: { outcome: "unmatched" }
+		};
+		const candidate = candidates.find((item) => item.key === key && !current.consumed.has(item.id));
+		if (candidate === void 0) return [{ kind: "unmatched" }, {
+			...current,
+			attempts,
+			entries: [...current.entries, fields]
+		}];
+		const statusFault = faults.filter(WireFault.$is("StatusOnAttempt")).find((fault) => fault.attempt === attempt && faultMatches(fault.match, method, normalizedUrl));
+		if (statusFault !== void 0) {
+			fields.match = { outcome: "injected" };
+			fields.fault = statusFault._tag;
+			return [{
+				kind: "status",
+				fault: statusFault
+			}, {
+				...current,
+				attempts,
+				entries: [...current.entries, fields]
+			}];
+		}
+		const response = candidate.exchange.response;
+		const chunkFault = faults.filter((fault) => !WireFault.$is("StatusOnAttempt")(fault)).find((fault) => (fault.attempt === void 0 || fault.attempt === attempt) && faultMatches(fault.match, method, normalizedUrl));
+		const body = replayBody(response, chunkFault);
+		const ref = {
+			fixtureId: candidate.fixtureId,
+			exchangeIndex: candidate.exchangeIndex
+		};
+		if (Result.isFailure(body)) {
+			fields.match = {
+				outcome: "invalid",
+				...ref,
+				reason: body.failure
+			};
+			return [{
+				kind: "invalid",
+				reason: body.failure
+			}, {
+				...current,
+				attempts,
+				entries: [...current.entries, fields]
+			}];
+		}
+		fields.match = {
+			outcome: "matched",
+			...ref
+		};
+		if (chunkFault !== void 0) fields.fault = chunkFault._tag;
+		return [{
+			kind: "exchange",
+			response,
+			body: body.success
+		}, {
+			consumed: new Set(current.consumed).add(candidate.id),
+			attempts,
+			entries: [...current.entries, fields]
+		}];
+	});
+	return {
+		client: HttpClient.make((request, url) => Effect.gen(function* () {
+			const normalizedUrl = normalizeWireUrl(url.toString());
+			const bodyText = requestBodyText(request);
+			const entry = {
+				method: request.method,
+				url: normalizedUrl,
+				headers: redactHeaders(headerRecord(request.headers))
+			};
+			if (bodyText !== void 0) {
+				entry.bodyText = bodyText;
+				const bodyJson = yield* parseJsonText(bodyText);
+				if (Option.isSome(bodyJson)) entry.bodyJson = bodyJson.value;
+			}
+			const decision = yield* decide(request.method, normalizedUrl, entry);
+			if (decision.kind === "unmatched") return yield* Effect.fail(unmatchedError(request));
+			if (decision.kind === "invalid") return yield* Effect.fail(invalidRecordingError(request, new WireReplayInvalid({ reason: decision.reason })));
+			const source = yield* Effect.try({
+				try: () => decision.kind === "status" ? webResponse(decision.fault.status, decision.fault.headers ?? {}, {
+					kind: "body",
+					body: decision.fault.body ?? ""
+				}) : webResponse(decision.response.status, decision.response.headers, decision.body),
+				catch: (cause) => invalidRecordingError(request, cause)
+			});
+			return HttpClientResponse.fromWeb(request, source);
+		})),
+		ledger: {
+			entries: Ref.get(state).pipe(Effect.map((current) => current.entries)),
+			remaining: Ref.get(state).pipe(Effect.map((current) => candidates.filter((candidate) => !current.consumed.has(candidate.id)).map((candidate) => ({
+				fixtureId: candidate.fixtureId,
+				exchangeIndex: candidate.exchangeIndex
+			}))))
+		}
+	};
+});
+const ReplayHttpClient = { 
+/**
+* Layer providing a replay `HttpClient` and its `ReplayLedger`. Each layer
+* build gets fresh consumption and ledger state.
+*/
+layer: (fixtures, options = {}) => Layer.unwrap(makeReplayHttpClient(fixtures, options).pipe(Effect.map(({ client, ledger }) => Layer.mergeAll(Layer.succeed(HttpClient.HttpClient, client), Layer.succeed(ReplayLedger, ledger))))) };
+//#endregion
+export { ReplayHttpClient, ReplayLedger, WireFault, WireReplayInvalid, WireTransportFault, makeReplayHttpClient };
+
+//# sourceMappingURL=replay.mjs.map

package/dist/replay.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.mjs","names":[],"sources":["../src/replay.ts"],"sourcesContent":["/**\n * Offline replay of recorded wire fixtures as an Effect `HttpClient`.\n *\n * Replay never performs network I/O. Requests are matched by method and\n * normalized absolute URL (hash removed, query parameters sorted); each\n * recorded exchange is consumed once, in recorded order among exchanges with\n * the same method and URL. A request with no remaining match fails closed with\n * a typed `HttpClientError` and is still written to the ledger.\n *\n * @experimental\n */\nimport {\n  Cause,\n  Context,\n  Data,\n  Effect,\n  Exit,\n  Fiber,\n  Layer,\n  Match,\n  Option,\n  Predicate,\n  Ref,\n  Result\n} from 'effect'\nimport type * as Schema from 'effect/Schema'\nimport {\n  HttpClient,\n  HttpClientError,\n  HttpClientResponse,\n  type HttpClientRequest\n} from 'effect/unstable/http'\nimport {\n  isWireBase64BodyResponse,\n  isWireStreamResponse,\n  type WireChunk,\n  type WireExchange,\n  type WireFixture,\n  type WireHeaders,\n  type WireResponse\n} from './fixture.ts'\nimport {\n  decodeBase64Bytes,\n  headerRecord,\n  isNullBodyStatus,\n  normalizeWireUrl,\n  parseJsonText,\n  redactHeaders,\n  requestBodyText,\n  urlMatchesPattern\n} from './wire-internal.ts'\n\n/**\n * Optional fault filter. `method` compares case-insensitively. `url` matches\n * the normalized request URL exactly, or as a prefix when it ends with `*`.\n * An omitted field matches every request.\n */\nexport type WireFaultMatch = {\n  readonly method?: string\n  readonly url?: string\n}\n\n/**\n * Wire faults injected by the replay client. `attempt` is 1-based and counted\n * per method + normalized URL.\n *\n * - `StatusOnAttempt`: respond with this status instead of consuming a recorded\n *   exchange, so the next attempt still gets the recording. It fires only when\n *   an unconsumed recorded exchange exists for the method + normalized URL;\n *   unknown or exhausted requests still fail closed as `unmatched`.\n * - `FailAfterChunks`: emit the first `chunks` recorded chunks, then fail the\n *   body stream the way a dropped connection does under `FetchHttpClient`.\n * - `TruncateAfterChunks`: emit the first `chunks` recorded chunks, then end\n *   the body cleanly.\n * - `HoldAfterChunks`: emit the first `chunks` recorded chunks, run `release`,\n *   then emit the rest.\n *\n * `attempt` omitted means every matching attempt. A chunk fault that cannot\n * take effect fails the request with a typed `HttpClientError` (and a ledger\n * `invalid` outcome) instead of silently doing nothing: any chunk fault matched\n * against a whole-body response, `TruncateAfterChunks`/`HoldAfterChunks` with\n * `chunks` >= the recorded chunk count, or `FailAfterChunks` with `chunks` >\n * the recorded chunk count. That error's reason is a `TransportError`, so\n * transient-retry policies may retry past it: assert the ledger has no\n * `invalid` outcome when testing through a retrying client.\n */\nexport type WireFault = Data.TaggedEnum<{\n  StatusOnAttempt: {\n    readonly match?: WireFaultMatch\n    readonly attempt: number\n    readonly status: number\n    readonly headers?: WireHeaders\n    readonly body?: string\n  }\n  FailAfterChunks: {\n    readonly match?: WireFaultMatch\n    readonly attempt?: number\n    readonly chunks: number\n  }\n  TruncateAfterChunks: {\n    readonly match?: WireFaultMatch\n    readonly attempt?: number\n    readonly chunks: number\n  }\n  HoldAfterChunks: {\n    readonly match?: WireFaultMatch\n    readonly attempt?: number\n    readonly chunks: number\n    readonly release: Effect.Effect<void>\n  }\n}>\n\nexport const WireFault = Data.taggedEnum<WireFault>()\n\nexport type WireFaultTag = WireFault['_tag']\n\ntype ChunkFault = Exclude<WireFault, { readonly _tag: 'StatusOnAttempt' }>\n\n/** Cause attached to a body stream failed by `FailAfterChunks`. */\nexport class WireTransportFault extends Data.TaggedError('WireTransportFault')<{\n  readonly afterChunks: number\n}> {\n  override get message(): string {\n    return `injected transport failure after ${this.afterChunks} chunks`\n  }\n}\n\n/**\n * How a replayed request was answered: a recorded exchange, a response\n * injected by a `StatusOnAttempt` fault, nothing (fail closed), or a matched\n * exchange that could not be replayed (`invalid`: a chunk fault that cannot\n * take effect, or undecodable base64). `invalid` requests fail with a typed\n * `HttpClientError` and do not consume the exchange.\n */\nexport type ReplayLedgerMatch =\n  | { readonly outcome: 'matched'; readonly fixtureId: string; readonly exchangeIndex: number }\n  | { readonly outcome: 'injected' }\n  | { readonly outcome: 'unmatched' }\n  | {\n      readonly outcome: 'invalid'\n      readonly fixtureId: string\n      readonly exchangeIndex: number\n      /** Why the recording could not be replayed; never contains request or response data. */\n      readonly reason: string\n    }\n\nexport type ReplayLedgerEntry = {\n  readonly method: string\n  /** Normalized absolute URL. */\n  readonly url: string\n  /** Request headers with credential headers replaced by `<redacted>`. */\n  readonly headers: Readonly<Record<string, string>>\n  readonly bodyText?: string\n  /** Parsed request body when `bodyText` is valid JSON. */\n  readonly bodyJson?: Schema.Json\n  /** 1-based attempt number for this method + URL. */\n  readonly attempt: number\n  readonly match: ReplayLedgerMatch\n  /** Tag of the fault that shaped this response, if any (never set for a fault that did not apply). */\n  readonly fault?: WireFaultTag\n}\n\nexport type ReplayExchangeRef = {\n  readonly fixtureId: string\n  readonly exchangeIndex: number\n}\n\nexport type ReplayLedgerApi = {\n  /** Every request seen by the replay client, in arrival order. */\n  readonly entries: Effect.Effect<ReadonlyArray<ReplayLedgerEntry>>\n  /** Recorded exchanges not consumed yet, in fixture order. */\n  readonly remaining: Effect.Effect<ReadonlyArray<ReplayExchangeRef>>\n}\n\nexport class ReplayLedger extends Context.Service<ReplayLedger, ReplayLedgerApi>()(\n  '@yolk-sdk/conformance/ReplayLedger'\n) {}\n\nexport type ReplayHttpClientOptions = {\n  readonly faults?: ReadonlyArray<WireFault>\n}\n\ntype Candidate = {\n  readonly id: number\n  readonly key: string\n  readonly fixtureId: string\n  readonly exchangeIndex: number\n  readonly exchange: WireExchange\n}\n\ntype ReplayState = {\n  readonly consumed: ReadonlySet<number>\n  readonly attempts: ReadonlyMap<string, number>\n  readonly entries: ReadonlyArray<ReplayLedgerEntry>\n}\n\n// Bytes to replay: one whole body, or one Uint8Array per recorded chunk.\ntype ReplayBody =\n  | { readonly kind: 'body'; readonly body: string | Uint8Array<ArrayBuffer> }\n  | {\n      readonly kind: 'chunks'\n      readonly chunks: ReadonlyArray<Uint8Array>\n      readonly fault: ChunkFault | undefined\n    }\n\ntype ReplayDecision =\n  | { readonly kind: 'status'; readonly fault: Extract<WireFault, { _tag: 'StatusOnAttempt' }> }\n  | {\n      readonly kind: 'exchange'\n      readonly response: WireResponse\n      readonly body: ReplayBody\n    }\n  | { readonly kind: 'invalid'; readonly reason: string }\n  | { readonly kind: 'unmatched' }\n\ntype LedgerEntryFields = {\n  method: string\n  url: string\n  headers: Readonly<Record<string, string>>\n  bodyText?: string\n  bodyJson?: Schema.Json\n  attempt: number\n  match: ReplayLedgerMatch\n  fault?: WireFaultTag\n}\n\nconst requestKey = (method: string, normalizedUrl: string) =>\n  `${method.toUpperCase()} ${normalizedUrl}`\n\nconst faultMatches = (\n  match: WireFaultMatch | undefined,\n  method: string,\n  normalizedUrl: string\n): boolean =>\n  (match?.method === undefined || match.method.toUpperCase() === method.toUpperCase()) &&\n  (match?.url === undefined || urlMatchesPattern(match.url, normalizedUrl))\n\nconst candidatesFrom = (fixtures: ReadonlyArray<WireFixture>): ReadonlyArray<Candidate> => {\n  const candidates: Array<Candidate> = []\n\n  for (const fixture of fixtures) {\n    fixture.exchanges.forEach((exchange, exchangeIndex) => {\n      candidates.push({\n        id: candidates.length,\n        key: requestKey(exchange.request.method, normalizeWireUrl(exchange.request.url)),\n        fixtureId: fixture.id,\n        exchangeIndex,\n        exchange\n      })\n    })\n  }\n\n  return candidates\n}\n\nconst chunkBytes = (chunk: WireChunk): Option.Option<Uint8Array> =>\n  Predicate.isString(chunk)\n    ? Option.some(new TextEncoder().encode(chunk))\n    : decodeBase64Bytes(chunk.base64)\n\nconst chunkFaultProblem = (fault: ChunkFault, recorded: number): string | undefined => {\n  if (!Number.isSafeInteger(fault.chunks) || fault.chunks < 0) {\n    return `${fault._tag} needs a non-negative integer chunk count`\n  }\n\n  // `FailAfterChunks` may fail after the last chunk; truncating or holding\n  // there would change nothing.\n  const applies = WireFault.$is('FailAfterChunks')(fault)\n    ? fault.chunks <= recorded\n    : fault.chunks < recorded\n\n  return applies\n    ? undefined\n    : `${fault._tag} after ${fault.chunks} chunk(s) cannot apply to a response with ${recorded} recorded chunk(s)`\n}\n\n/** Resolve the exact bytes to replay, or why the recording cannot be replayed as requested. */\nconst replayBody = (\n  response: WireResponse,\n  fault: ChunkFault | undefined\n): Result.Result<ReplayBody, string> => {\n  if (isWireStreamResponse(response)) {\n    const chunks = Option.all(response.chunks.map(chunkBytes))\n\n    if (Option.isNone(chunks)) {\n      return Result.fail('a recorded chunk is not valid base64')\n    }\n\n    const problem = fault === undefined ? undefined : chunkFaultProblem(fault, chunks.value.length)\n\n    return problem === undefined\n      ? Result.succeed({ kind: 'chunks', chunks: chunks.value, fault })\n      : Result.fail(problem)\n  }\n\n  if (fault !== undefined) {\n    return Result.fail(`${fault._tag} cannot apply to a whole-body response`)\n  }\n\n  if (isWireBase64BodyResponse(response)) {\n    return Option.match(decodeBase64Bytes(response.bodyBase64), {\n      onNone: () => Result.fail('the recorded bodyBase64 is not valid base64'),\n      // Copy into an ArrayBuffer-backed view, as `Response` requires.\n      onSome: bytes => Result.succeed({ kind: 'body', body: new Uint8Array(bytes) })\n    })\n  }\n\n  return Result.succeed({ kind: 'body', body: response.body })\n}\n\n/**\n * Strictly pull-driven body: one `Uint8Array` per recorded chunk (including\n * empty ones), and chunk `k` is produced only when the consumer pulls it,\n * never ahead of demand. The fault (already validated against the chunk count)\n * applies when the consumer pulls past `fault.chunks` chunks.\n */\nconst bodyReadable = (\n  chunks: ReadonlyArray<Uint8Array>,\n  fault: ChunkFault | undefined\n): ReadableStream<Uint8Array> => {\n  let next = 0\n  let faultApplied = false\n  let cancelled = false\n  let held: Fiber.Fiber<void> | undefined\n\n  const emitNext = (controller: ReadableStreamDefaultController<Uint8Array>): void => {\n    const chunk = chunks[next]\n\n    if (chunk === undefined) {\n      controller.close()\n\n      return\n    }\n\n    next += 1\n    controller.enqueue(chunk)\n  }\n\n  return new ReadableStream<Uint8Array>(\n    {\n      pull: controller => {\n        if (fault === undefined || faultApplied || next !== fault.chunks) {\n          emitNext(controller)\n\n          return\n        }\n\n        faultApplied = true\n\n        return Match.valueTags(fault, {\n          FailAfterChunks: ({ chunks: afterChunks }) =>\n            controller.error(new WireTransportFault({ afterChunks })),\n          TruncateAfterChunks: () => controller.close(),\n          HoldAfterChunks: ({ release }) => {\n            // Keep the release fiber so cancelling the body interrupts it (and runs its finalizers).\n            // `runFork` starts `release` synchronously, so a cancel can land before `held` is set.\n            const fiber = Effect.runFork(release)\n            held = fiber\n\n            if (cancelled) {\n              held = undefined\n\n              return Effect.runPromise(Fiber.interrupt(fiber))\n            }\n\n            return Effect.runPromise(Fiber.await(fiber)).then(exit => {\n              held = undefined\n\n              if (cancelled) return\n\n              if (Exit.isSuccess(exit)) {\n                emitNext(controller)\n              } else {\n                controller.error(Cause.squash(exit.cause))\n              }\n            })\n          }\n        })\n      },\n      cancel: () => {\n        cancelled = true\n\n        if (held === undefined) return\n\n        return Effect.runPromise(Fiber.interrupt(held))\n      }\n    },\n    { highWaterMark: 0 }\n  )\n}\n\nconst webResponse = (status: number, headers: WireHeaders, body: ReplayBody): Response => {\n  const init = { status, headers: { ...headers } }\n\n  if (isNullBodyStatus(status)) {\n    return new Response(null, init)\n  }\n\n  if (body.kind === 'body') {\n    return new Response(body.body, init)\n  }\n\n  return new Response(bodyReadable(body.chunks, body.fault), init)\n}\n\nconst unmatchedError = (request: HttpClientRequest.HttpClientRequest) =>\n  new HttpClientError.HttpClientError({\n    reason: new HttpClientError.TransportError({\n      request,\n      description: 'replay has no remaining recorded exchange'\n    })\n  })\n\nconst invalidRecordingError = (request: HttpClientRequest.HttpClientRequest, cause: unknown) =>\n  new HttpClientError.HttpClientError({\n    reason: new HttpClientError.TransportError({\n      request,\n      cause,\n      description: 'recorded response could not be replayed'\n    })\n  })\n\n/**\n * Cause attached to the `HttpClientError` (reason `TransportError`) of a request\n * whose recording could not be replayed. Retrying clients may retry past it;\n * check the ledger for an `invalid` outcome.\n */\nexport class WireReplayInvalid extends Data.TaggedError('WireReplayInvalid')<{\n  readonly reason: string\n}> {\n  override get message(): string {\n    return this.reason\n  }\n}\n\n/**\n * Build a replay `HttpClient` and its ledger over the given fixtures. Each\n * call has independent consumption, attempt, and ledger state.\n */\nexport const makeReplayHttpClient = (\n  fixtures: ReadonlyArray<WireFixture>,\n  options: ReplayHttpClientOptions = {}\n): Effect.Effect<{ readonly client: HttpClient.HttpClient; readonly ledger: ReplayLedgerApi }> =>\n  Effect.gen(function* () {\n    const candidates = candidatesFrom(fixtures)\n    const faults = options.faults ?? []\n\n    const state = yield* Ref.make<ReplayState>({\n      consumed: new Set(),\n      attempts: new Map(),\n      entries: []\n    })\n\n    const decide = (\n      method: string,\n      normalizedUrl: string,\n      entry: Omit<LedgerEntryFields, 'attempt' | 'match' | 'fault'>\n    ) =>\n      Ref.modify(state, (current): [ReplayDecision, ReplayState] => {\n        const key = requestKey(method, normalizedUrl)\n        const attempt = (current.attempts.get(key) ?? 0) + 1\n        const attempts = new Map(current.attempts).set(key, attempt)\n        const fields: LedgerEntryFields = { ...entry, attempt, match: { outcome: 'unmatched' } }\n\n        const candidate = candidates.find(\n          item => item.key === key && !current.consumed.has(item.id)\n        )\n\n        // Fail closed first: faults never answer unknown or exhausted requests.\n        if (candidate === undefined) {\n          return [\n            { kind: 'unmatched' },\n            { ...current, attempts, entries: [...current.entries, fields] }\n          ]\n        }\n\n        const statusFault = faults\n          .filter(WireFault.$is('StatusOnAttempt'))\n          .find(\n            fault => fault.attempt === attempt && faultMatches(fault.match, method, normalizedUrl)\n          )\n\n        if (statusFault !== undefined) {\n          fields.match = { outcome: 'injected' }\n          fields.fault = statusFault._tag\n\n          return [\n            { kind: 'status', fault: statusFault },\n            { ...current, attempts, entries: [...current.entries, fields] }\n          ]\n        }\n\n        const response = candidate.exchange.response\n\n        const chunkFault = faults\n          .filter((fault): fault is ChunkFault => !WireFault.$is('StatusOnAttempt')(fault))\n          .find(\n            fault =>\n              (fault.attempt === undefined || fault.attempt === attempt) &&\n              faultMatches(fault.match, method, normalizedUrl)\n          )\n\n        const body = replayBody(response, chunkFault)\n        const ref = { fixtureId: candidate.fixtureId, exchangeIndex: candidate.exchangeIndex }\n\n        if (Result.isFailure(body)) {\n          // The fault (or recording) did not apply: record the failure, not the\n          // fault, and leave the exchange unconsumed.\n          fields.match = { outcome: 'invalid', ...ref, reason: body.failure }\n\n          return [\n            { kind: 'invalid', reason: body.failure },\n            { ...current, attempts, entries: [...current.entries, fields] }\n          ]\n        }\n\n        fields.match = { outcome: 'matched', ...ref }\n\n        if (chunkFault !== undefined) {\n          fields.fault = chunkFault._tag\n        }\n\n        return [\n          { kind: 'exchange', response, body: body.success },\n          {\n            consumed: new Set(current.consumed).add(candidate.id),\n            attempts,\n            entries: [...current.entries, fields]\n          }\n        ]\n      })\n\n    const client = HttpClient.make((request, url) =>\n      Effect.gen(function* () {\n        const normalizedUrl = normalizeWireUrl(url.toString())\n        const bodyText = requestBodyText(request)\n\n        const entry: Omit<LedgerEntryFields, 'attempt' | 'match' | 'fault'> = {\n          method: request.method,\n          url: normalizedUrl,\n          headers: redactHeaders(headerRecord(request.headers))\n        }\n\n        if (bodyText !== undefined) {\n          entry.bodyText = bodyText\n\n          const bodyJson = yield* parseJsonText(bodyText)\n\n          if (Option.isSome(bodyJson)) {\n            entry.bodyJson = bodyJson.value\n          }\n        }\n\n        const decision = yield* decide(request.method, normalizedUrl, entry)\n\n        if (decision.kind === 'unmatched') {\n          return yield* Effect.fail(unmatchedError(request))\n        }\n\n        if (decision.kind === 'invalid') {\n          return yield* Effect.fail(\n            invalidRecordingError(request, new WireReplayInvalid({ reason: decision.reason }))\n          )\n        }\n\n        const source = yield* Effect.try({\n          try: () =>\n            decision.kind === 'status'\n              ? webResponse(decision.fault.status, decision.fault.headers ?? {}, {\n                  kind: 'body',\n                  body: decision.fault.body ?? ''\n                })\n              : webResponse(decision.response.status, decision.response.headers, decision.body),\n          catch: cause => invalidRecordingError(request, cause)\n        })\n\n        return HttpClientResponse.fromWeb(request, source)\n      })\n    )\n\n    const ledger: ReplayLedgerApi = {\n      entries: Ref.get(state).pipe(Effect.map(current => current.entries)),\n      remaining: Ref.get(state).pipe(\n        Effect.map(current =>\n          candidates\n            .filter(candidate => !current.consumed.has(candidate.id))\n            .map(candidate => ({\n              fixtureId: candidate.fixtureId,\n              exchangeIndex: candidate.exchangeIndex\n            }))\n        )\n      )\n    }\n\n    return { client, ledger }\n  })\n\nexport const ReplayHttpClient = {\n  /**\n   * Layer providing a replay `HttpClient` and its `ReplayLedger`. Each layer\n   * build gets fresh consumption and ledger state.\n   */\n  layer: (\n    fixtures: ReadonlyArray<WireFixture>,\n    options: ReplayHttpClientOptions = {}\n  ): Layer.Layer<HttpClient.HttpClient | ReplayLedger> =>\n    Layer.unwrap(\n      makeReplayHttpClient(fixtures, options).pipe(\n        Effect.map(({ client, ledger }) =>\n          Layer.mergeAll(\n            Layer.succeed(HttpClient.HttpClient, client),\n            Layer.succeed(ReplayLedger, ledger)\n          )\n        )\n      )\n    )\n} as const\n"],"mappings":"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"}

package/dist/runner.d.mts

@@ -0,0 +1,163 @@
+import { ConformanceCase, ConformanceSafety } from "./case.mjs";
+import { ConformanceFixture } from "./fixture.mjs";
+import { Effect, Layer } from "effect";
+
+//#region src/runner.d.ts
+/**
+ * Where cases run. `replay`, `in-process`, and `emulated` never touch a real
+ * account, so every case runs. `live` talks to a real practice account and is
+ * gated by the safety policy (see `conformanceSkipReason`).
+ */
+type ConformanceTarget = {
+  readonly kind: 'replay' | 'in-process' | 'emulated';
+} | {
+  readonly kind: 'live'; /** Synthetic, non-identifying account label (for example `practice`). */
+  readonly account: string; /** `reversible` lets `write-reversible` cases run. Default `none`. */
+  readonly allowWrites?: 'none' | 'reversible'; /** Exact ids of `write-irreversible` cases a person explicitly started. */
+  readonly allowIrreversible?: ReadonlyArray<string>;
+};
+type ConformanceTargetKind = ConformanceTarget['kind'];
+type ConformanceSkipReason = 'writes-not-allowed' | 'manual-only';
+/**
+ * The safety policy. `undefined` means the case may run.
+ *
+ * - `replay` / `in-process` / `emulated`: every case runs.
+ * - `live`: `read` runs; `write-reversible` runs only with
+ *   `allowWrites: 'reversible'` (else `writes-not-allowed`);
+ *   `write-irreversible` runs only when its exact id is in
+ *   `allowIrreversible` (else `manual-only`), independent of `allowWrites`.
+ */
+declare const conformanceSkipReason: (target: ConformanceTarget, testCase: {
+  readonly id: string;
+  readonly safety: ConformanceSafety;
+}) => ConformanceSkipReason | undefined;
+/** Non-fatal findings attached to a case result. */
+type ConformanceWarning = /** The case has no `observed`: its claim was never watched against the real service. */{
+  readonly kind: 'unverified-case';
+} /** `observed.date` is older than the max age (`ageDays` absent when unreadable). */ | {
+  readonly kind: 'stale-observation';
+  readonly ageDays?: number;
+} /** A referenced fixture is a synthetic placeholder (`evidence: 'unverified'`, or a `PortFixture` without `observed`). */ | {
+  readonly kind: 'unverified-fixture';
+  readonly fixtureId: string;
+} /** A referenced fixture is older than the max age (`ageDays` absent when unreadable). */ | {
+  readonly kind: 'stale-fixture';
+  readonly fixtureId: string;
+  readonly ageDays?: number;
+} /** A referenced fixture id is not among the supplied fixtures. */ | {
+  readonly kind: 'missing-fixture';
+  readonly fixtureId: string;
+};
+type ConformanceWarningKind = ConformanceWarning['kind'];
+/**
+ * Sanitized failure. `message` is a `ConformanceMismatch`'s case-authored
+ * message (credential patterns redacted) or, for every other failure, layer
+ * failure, and defect, the error's own message passed through
+ * `sanitizeConformanceMessage` (credential patterns and header lines redacted, JSON
+ * spans elided, whitespace collapsed, length capped). `tag` is the error's
+ * `_tag` only when it is identifier-like. Request bodies, headers, and
+ * `ConformanceMismatch` `expected`/`actual` details are never copied.
+ */
+type ConformanceFailure = {
+  /** `failure`: typed error (including layer build errors); `defect`: unexpected die. */readonly kind: 'failure' | 'defect';
+  readonly tag?: string;
+  readonly message: string;
+};
+type ConformanceCaseStatus = 'passed' | 'failed' | 'skipped';
+type ConformanceCaseResult = {
+  readonly id: string;
+  readonly safety: ConformanceSafety;
+  readonly status: ConformanceCaseStatus;
+  readonly skipReason?: ConformanceSkipReason;
+  readonly failure?: ConformanceFailure;
+  readonly durationMs: number;
+  readonly warnings: ReadonlyArray<ConformanceWarning>;
+};
+type ConformanceReport = {
+  readonly target: {
+    readonly kind: ConformanceTargetKind;
+    readonly account?: string;
+  }; /** ISO timestamp of the run start. */
+  readonly startedAt: string;
+  readonly results: ReadonlyArray<ConformanceCaseResult>;
+  readonly summary: {
+    readonly passed: number;
+    readonly failed: number;
+    readonly skipped: number;
+  };
+};
+/** What a case (or a union of cases) needs from its layer. */
+type ConformanceCaseRequirements<C> = C extends {
+  readonly run: Effect.Effect<void, unknown, infer R>;
+} ? R : never;
+type RunSettings = {
+  readonly target: ConformanceTarget;
+  /**
+   * Fixtures to check referenced ids against (evidence, staleness, missing ids): HTTP
+   * `WireFixture`s and `PortFixture`s alike.
+   */
+  readonly fixtures?: ReadonlyArray<ConformanceFixture>; /** Reference time for staleness and `startedAt`. Defaults to the Effect `Clock`. */
+  readonly now?: Date; /** Fixtures and observations older than this many whole days are stale. Default 30. */
+  readonly maxFixtureAgeDays?: number; /** Cases run in parallel up to this limit. Default 1: live accounts are shared. */
+  readonly concurrency?: number;
+};
+/**
+ * Options for `runConformance` over cases of type `C` (a union when the cases
+ * differ).
+ *
+ * `layer` is called once per case that runs and must provide everything that
+ * case needs (`ConformanceCaseRequirements<C>`; providing more is fine). It is
+ * called and built inside the case's failure boundary, with a fresh memo map
+ * in its own scope, so state the layer allocates when it is built (replay
+ * consumption, ledgers, emulator state) never leaks between cases, even when
+ * the factory returns the same `Layer` value. Services captured in a shared
+ * value (for example one `Layer.succeed(service, instance)`) or supplied by
+ * the caller's environment are not rebuilt and stay shared. Build failures
+ * (`LE`) and a throwing factory are reported as failed cases. `LR` is
+ * whatever the layers still need from the caller (for example a live
+ * `HttpClient`) and becomes the requirement of the whole run.
+ */
+type ConformanceRunOptions<C, LE = never, LR = never> = RunSettings & {
+  readonly layer: (testCase: C) => Layer.Layer<ConformanceCaseRequirements<C>, LE, LR>;
+};
+/**
+ * Warnings for one case. Case-level warnings always apply; fixture-level ones
+ * only on non-live targets and only when `fixtures` were supplied.
+ */
+declare const conformanceCaseWarnings: (testCase: Pick<ConformanceCase<unknown, unknown>, "observed" | "fixtures">, context: {
+  readonly target: ConformanceTarget;
+  readonly now: Date;
+  readonly fixtures?: ReadonlyArray<ConformanceFixture> | undefined;
+  readonly maxFixtureAgeDays?: number | undefined;
+}) => ReadonlyArray<ConformanceWarning>;
+/**
+ * Best-effort sanitizer for failure messages copied into a `ConformanceReport`. Redacts the
+ * credential patterns shared with the fixture secret scan (bearer tokens, API-key prefixes, JWTs,
+ * private keys, credential field pairs, credential query/form parameters, and credential header
+ * lines such as `Cookie:` or `X-Api-Key:` to the end of the line), replaces JSON-looking spans
+ * (balanced `{...}` / `[...]`) with `[json]`, collapses whitespace, and caps the length at 300
+ * characters. Hosts should still keep secrets out of error messages.
+ */
+declare const sanitizeConformanceMessage: (message: string) => string;
+/**
+ * Run cases against a target and report. Skipped cases never build their
+ * layer. Each running case gets a fresh layer and runs under `Effect.exit`:
+ * failures, layer build failures, defects, and a throwing `layer` factory
+ * become `failed` results and the run continues. Interruption is not
+ * captured: interrupting the run (or a case interrupting itself) interrupts
+ * the whole run.
+ *
+ * `C` is inferred as the union of the given case types, so cases with
+ * different errors and requirements can share one run without annotations.
+ */
+declare function runConformance<C extends ConformanceCase<unknown, unknown>, LE = never, LR = never>(cases: ReadonlyArray<C>, options: ConformanceRunOptions<C, LE, LR>): Effect.Effect<ConformanceReport, never, LR>;
+/** True when any case failed. Skipped cases never fail a report. */
+declare const conformanceReportFailed: (report: ConformanceReport) => boolean;
+/**
+ * Compact plain text (no colors): one line per case with status, id, safety,
+ * skip reason or failure message, and warnings, then a summary line.
+ */
+declare const formatConformanceReport: (report: ConformanceReport) => string;
+//#endregion
+export { ConformanceCaseRequirements, ConformanceCaseResult, ConformanceCaseStatus, ConformanceFailure, ConformanceReport, ConformanceRunOptions, ConformanceSkipReason, ConformanceTarget, ConformanceTargetKind, ConformanceWarning, ConformanceWarningKind, conformanceCaseWarnings, conformanceReportFailed, conformanceSkipReason, formatConformanceReport, runConformance, sanitizeConformanceMessage };
+//# sourceMappingURL=runner.d.mts.map

package/dist/runner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.mts","names":[],"sources":["../src/runner.ts"],"mappings":";;;;;;;AA8BgD;AAGhD;;KAZY,iBAAA;EAAA,SACG,IAAA;AAAA;EAAA,SAEA,IAAA,UAWkB;EAAA,SATlB,OAAA,UASkB;EAAA,SAPlB,WAAA,0BAkBF;EAAA,SAhBE,iBAAA,GAAoB,aAAa;AAAA;AAAA,KAGpC,qBAAA,GAAwB,iBAAiB;AAAA,KAEzC,qBAAA;;;;;;;;;;cAWC,qBAAA,GACX,MAAA,EAAQ,iBAAA,EACR,QAAA;EAAA,SAAqB,EAAA;EAAA,SAAqB,MAAA,EAAQ,iBAAA;AAAA,MACjD,qBAAA;;KAgBS,kBAAA;WAEG,IAAA;AAAA;WAEA,IAAA;EAAA,SAAoC,OAAA;AAAA;WAEpC,IAAA;EAAA,SAAqC,SAAA;AAAA;WAErC,IAAA;EAAA,SAAgC,SAAA;EAAA,SAA4B,OAAA;AAAA;WAE5D,IAAA;EAAA,SAAkC,SAAA;AAAA;AAAA,KAErC,sBAAA,GAAyB,kBAAkB;AAerC;AAGlB;;;;AAAiC;AAEjC;;;AALkB,KAJN,kBAAA;EAYO,gGAVR,IAAA;EAAA,SACA,GAAA;EAAA,SACA,OAAA;AAAA;AAAA,KAGC,qBAAA;AAAA,KAEA,qBAAA;EAAA,SACD,EAAA;EAAA,SACA,MAAA,EAAQ,iBAAA;EAAA,SACR,MAAA,EAAQ,qBAAA;EAAA,SACR,UAAA,GAAa,qBAAA;EAAA,SACb,OAAA,GAAU,kBAAA;EAAA,SACV,UAAA;EAAA,SACA,QAAA,EAAU,aAAA,CAAc,kBAAA;AAAA;AAAA,KAGvB,iBAAA;EAAA,SACD,MAAA;IAAA,SAAmB,IAAA,EAAM,qBAAA;IAAA,SAAgC,OAAA;EAAA,GAJf;EAAA,SAM1C,SAAA;EAAA,SACA,OAAA,EAAS,aAAA,CAAc,qBAAA;EAAA,SACvB,OAAA;IAAA,SACE,MAAA;IAAA,SACA,MAAA;IAAA,SACA,OAAA;EAAA;AAAA;;KAKD,2BAAA,MAAiC,CAAA;EAAA,SAClC,GAAA,EAAK,MAAA,CAAO,MAAM;AAAA,IAEzB,CAAA;AAAA,KAGC,WAAA;EAAA,SACM,MAAA,EAAQ,iBAAA;EAhBR;;;;EAAA,SAqBA,QAAA,GAAW,aAAA,CAAc,kBAAA,GAlBvB;EAAA,SAoBF,GAAA,GAAM,IAAA,EAnBG;EAAA,SAqBT,iBAAA,WAhBC;EAAA,SAkBD,WAAA;AAAA;;;;;;;;;;AAfN;AACI;;;;;;KAiCG,qBAAA,8BAAmD,WAAA;EAAA,SACpD,KAAA,GAAQ,QAAA,EAAU,CAAA,KAAM,KAAA,CAAM,KAAA,CAAM,2BAAA,CAA4B,CAAA,GAAI,EAAA,EAAI,EAAA;AAAA;;;;;cA2BtE,uBAAA,GACX,QAAA,EAAU,IAAA,CAAK,eAAA,8CACf,OAAA;EAAA,SACW,MAAA,EAAQ,iBAAA;EAAA,SACR,GAAA,EAAK,IAAA;EAAA,SACL,QAAA,GAAW,aAAA,CAAc,kBAAA;EAAA,SACzB,iBAAA;AAAA,MAEV,aAAA,CAAc,kBAAA;AAvDK;AAmBtB;;;;;;;AAnBsB,cA+LT,0BAAA,GAA8B,OAAe;;;;;;;;;;;;iBAoF1C,cAAA,WAAyB,eAAA,2CAAA,CACvC,KAAA,EAAO,aAAA,CAAc,CAAA,GACrB,OAAA,EAAS,qBAAA,CAAsB,CAAA,EAAG,EAAA,EAAI,EAAA,IACrC,MAAA,CAAO,MAAA,CAAO,iBAAA,SAA0B,EAAA;;cAwE9B,uBAAA,GAA2B,MAAyB,EAAjB,iBAAiB;;;;;cA6CpD,uBAAA,GAA2B,MAAyB,EAAjB,iBAAiB"}