@neurocode-ai/http-recorder 1.18.13 → 1.18.15

package/package.json

@@ -1,6 +1,6 @@
 {
     "$schema":  "https://json.schemastore.org/package.json",
-    "version":  "1.18.13",
+    "version":  "1.18.15",
     "name":  "@neurocode-ai/http-recorder",
     "description":  "Record and replay Effect HTTP client traffic with deterministic cassettes",
     "type":  "module",
@@ -37,6 +37,7 @@
                     "./internal":  "./src/internal.ts"
                 },
     "files":  [
+                  "src",
                   "dist",
                   "README.md",
                   "CHANGELOG.md",

package/src/cassette.ts

@@ -0,0 +1,179 @@
+import { Context, Effect, FileSystem, Layer, Schema, Semaphore } from "effect"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { secretFindings, SecretFindingSchema, type SecretFinding } from "./redaction.js"
+import { CassetteSchema, encodeCassette, type Cassette, type CassetteMetadata, type Interaction } from "./schema.js"
+
+const DEFAULT_RECORDINGS_DIR = path.resolve(process.cwd(), "test", "fixtures", "recordings")
+
+export class CassetteNotFoundError extends Schema.TaggedErrorClass<CassetteNotFoundError>()("CassetteNotFoundError", {
+  cassetteName: Schema.String,
+}) {
+  override get message() {
+    return `Cassette "${this.cassetteName}" not found`
+  }
+}
+
+export class UnsafeCassetteError extends Schema.TaggedErrorClass<UnsafeCassetteError>()("UnsafeCassetteError", {
+  cassetteName: Schema.String,
+  findings: Schema.Array(SecretFindingSchema),
+}) {
+  override get message() {
+    return `Refusing to write cassette "${this.cassetteName}" because it contains possible secrets: ${this.findings
+      .map((finding) => `${finding.path} (${finding.reason})`)
+      .join(", ")}`
+  }
+}
+
+export interface Interface {
+  readonly read: (name: string) => Effect.Effect<ReadonlyArray<Interaction>, CassetteNotFoundError>
+  readonly append: (
+    name: string,
+    interaction: Interaction,
+    metadata?: CassetteMetadata,
+  ) => Effect.Effect<void, UnsafeCassetteError>
+  readonly exists: (name: string) => Effect.Effect<boolean>
+  readonly list: () => Effect.Effect<ReadonlyArray<string>>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@neurocode-ai/http-recorder/Cassette") {}
+
+const cassettePath = (directory: string, name: string) => {
+  if (!name || path.isAbsolute(name) || path.win32.isAbsolute(name) || name.split(/[\\/]/).includes(".."))
+    throw new Error(`Invalid cassette name "${name}"`)
+  const root = path.resolve(directory)
+  const target = path.resolve(root, `${name}.json`)
+  const relative = path.relative(root, target)
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+    throw new Error(`Invalid cassette name "${name}"`)
+  return target
+}
+
+export const hasCassetteSync = (name: string, options: { readonly directory?: string } = {}) =>
+  fs.existsSync(cassettePath(options.directory ?? DEFAULT_RECORDINGS_DIR, name))
+
+const buildCassette = (
+  name: string,
+  interactions: ReadonlyArray<Interaction>,
+  metadata: CassetteMetadata | undefined,
+): Cassette => ({
+  version: 1,
+  metadata: { name, recordedAt: new Date().toISOString(), ...metadata },
+  interactions,
+})
+
+const formatCassette = (cassette: Cassette) => `${JSON.stringify(encodeCassette(cassette), null, 2)}\n`
+
+const parseCassette = Schema.decodeUnknownSync(Schema.fromJsonString(CassetteSchema))
+
+const failIfUnsafe = (name: string, findings: ReadonlyArray<SecretFinding>) =>
+  findings.length === 0 ? Effect.void : Effect.fail(new UnsafeCassetteError({ cassetteName: name, findings }))
+
+export const fileSystem = (
+  options: { readonly directory?: string } = {},
+): Layer.Layer<Service, never, FileSystem.FileSystem> =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem
+      const directory = options.directory ?? DEFAULT_RECORDINGS_DIR
+      const recorded = new Map<string, { interactions: Interaction[]; findings: SecretFinding[] }>()
+      const appendLock = yield* Semaphore.make(1)
+
+      const pathFor = (name: string) => cassettePath(directory, name)
+
+      const walk = (current: string): Effect.Effect<ReadonlyArray<string>> =>
+        Effect.gen(function* () {
+          const entries = yield* fs.readDirectory(current).pipe(Effect.catch(() => Effect.succeed([] as string[])))
+          const nested = yield* Effect.forEach(entries, (entry) => {
+            const full = path.join(current, entry)
+            return fs.stat(full).pipe(
+              Effect.flatMap((stat) => (stat.type === "Directory" ? walk(full) : Effect.succeed([full]))),
+              Effect.catch(() => Effect.succeed([] as string[])),
+            )
+          })
+          return nested.flat()
+        })
+
+      return Service.of({
+        read: (name) =>
+          fs.readFileString(pathFor(name)).pipe(
+            Effect.map((raw) => parseCassette(raw).interactions),
+            Effect.catch(() => Effect.fail(new CassetteNotFoundError({ cassetteName: name }))),
+          ),
+        append: (name, interaction, metadata) =>
+          appendLock.withPermit(
+            Effect.gen(function* () {
+              const entry = recorded.get(name) ?? { interactions: [], findings: [] }
+              const interactions = [...entry.interactions, interaction]
+              const interactionFindings = [...entry.findings, ...secretFindings(interaction)]
+              const cassette = buildCassette(name, interactions, metadata)
+              const findings = [...interactionFindings, ...secretFindings(cassette.metadata ?? {})]
+              yield* failIfUnsafe(name, findings)
+              const target = pathFor(name)
+              yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.orDie)
+              const temporary = `${target}.${crypto.randomUUID()}.tmp`
+              yield* fs.writeFileString(temporary, formatCassette(cassette)).pipe(
+                Effect.flatMap(() => fs.rename(temporary, target)),
+                Effect.ensuring(fs.remove(temporary, { force: true }).pipe(Effect.catch(() => Effect.void))),
+                Effect.orDie,
+              )
+              recorded.set(name, { interactions, findings: interactionFindings })
+            }),
+          ),
+        exists: (name) =>
+          fs.access(pathFor(name)).pipe(
+            Effect.as(true),
+            Effect.catch(() => Effect.succeed(false)),
+          ),
+        list: () =>
+          walk(directory).pipe(
+            Effect.map((files) =>
+              files
+                .filter((file) => file.endsWith(".json"))
+                .map((file) =>
+                  path
+                    .relative(directory, file)
+                    .replace(/\\/g, "/")
+                    .replace(/\.json$/, ""),
+                )
+                .toSorted((a, b) => a.localeCompare(b)),
+            ),
+          ),
+      })
+    }),
+  )
+
+export const memory = (initial: Record<string, ReadonlyArray<Interaction>> = {}): Layer.Layer<Service> =>
+  Layer.sync(Service, () => {
+    const stored = new Map<string, Interaction[]>(
+      Object.entries(initial).map(([name, interactions]) => [name, [...interactions]]),
+    )
+    const accumulatedFindings = new Map<string, SecretFinding[]>()
+    const appendLock = Semaphore.makeUnsafe(1)
+
+    return Service.of({
+      read: (name) =>
+        stored.has(name)
+          ? Effect.succeed(stored.get(name) ?? [])
+          : Effect.fail(new CassetteNotFoundError({ cassetteName: name })),
+      append: (name, interaction, metadata) =>
+        appendLock.withPermit(
+          Effect.suspend(() => {
+            const interactions = [...(stored.get(name) ?? []), interaction]
+            const findings = [...(accumulatedFindings.get(name) ?? []), ...secretFindings(interaction)]
+            const allFindings = metadata ? [...findings, ...secretFindings({ name, ...metadata })] : findings
+            return failIfUnsafe(name, allFindings).pipe(
+              Effect.tap(() =>
+                Effect.sync(() => {
+                  stored.set(name, interactions)
+                  accumulatedFindings.set(name, findings)
+                }),
+              ),
+            )
+          }),
+        ),
+      exists: (name) => Effect.sync(() => stored.has(name)),
+      list: () => Effect.sync(() => Array.from(stored.keys()).toSorted()),
+    })
+  })

package/src/effect.ts

@@ -0,0 +1,25 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import * as Layer from "effect/Layer"
+import { FetchHttpClient } from "effect/unstable/http"
+import type * as HttpClient from "effect/unstable/http/HttpClient"
+import * as CassetteService from "./cassette.js"
+import { recordingLayer } from "./internal-effect.js"
+import { make } from "./redactor.js"
+import type { RecorderOptions } from "./types.js"
+
+/**
+ * Provides a fetch-backed `HttpClient` with cassette recording and replay.
+ *
+ * Locally, a missing cassette is recorded from the real service. Existing
+ * cassettes are replayed, and `CI=true` makes a missing cassette fail.
+ */
+export const http = (name: string, options: RecorderOptions = {}): Layer.Layer<HttpClient.HttpClient> =>
+  recordingLayer(name, {
+    metadata: options.metadata,
+    redactor: make(options.redact),
+    match: options.match,
+  }).pipe(
+    Layer.provide(CassetteService.fileSystem({ directory: options.directory })),
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(NodeFileSystem.layer),
+  )

package/src/index.ts

@@ -0,0 +1,18 @@
+import { http } from "./effect.js"
+import { socket } from "./socket.js"
+
+/** HTTP and WebSocket cassette recording. */
+export const HttpRecorder = { http, socket } as const
+
+export namespace HttpRecorder {
+  /** Additional JSON metadata stored with a cassette. */
+  export type CassetteMetadata = import("./types.js").CassetteMetadata
+  /** Recorder configuration. */
+  export type RecorderOptions = import("./types.js").RecorderOptions
+  /** Additive redaction and header-preservation policy. */
+  export type RedactOptions = import("./types.js").RedactOptions
+  /** Returns whether an incoming HTTP request matches a recorded request. */
+  export type RequestMatcher = import("./types.js").RequestMatcher
+  /** The normalized HTTP request representation used for matching. */
+  export type RequestSnapshot = import("./types.js").RequestSnapshot
+}

package/src/internal-effect.ts

@@ -0,0 +1,189 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { Deferred, Effect, Layer, Option, Ref } from "effect"
+import {
+  FetchHttpClient,
+  Headers,
+  HttpBody,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+  UrlParams,
+} from "effect/unstable/http"
+import * as CassetteService from "./cassette.js"
+import { defaultMatcher, selectSequential } from "./matching.js"
+import { makeReplayState, resolveAutoMode } from "./recorder.js"
+import { make, type Redactor } from "./redactor.js"
+import { redactUrl } from "./redaction.js"
+import { httpInteractions } from "./schema.js"
+import type { CassetteMetadata, HttpInteraction, RequestMatcher, ResponseSnapshot } from "./types.js"
+
+export { defaultMatcher }
+
+export type RecordReplayMode = "auto" | "record" | "replay" | "passthrough"
+
+export interface RecordReplayOptions {
+  readonly mode?: RecordReplayMode
+  readonly directory?: string
+  readonly metadata?: CassetteMetadata
+  readonly redactor?: Redactor
+  readonly match?: RequestMatcher
+}
+
+const TEXT_CONTENT_TYPES = new Set([
+  "application/graphql",
+  "application/javascript",
+  "application/json",
+  "application/sql",
+  "application/x-www-form-urlencoded",
+  "application/xml",
+  "application/yaml",
+  "image/svg+xml",
+])
+
+const isTextContentType = (contentType: string | undefined) => {
+  const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase()
+  if (!mediaType) return false
+  return (
+    mediaType.startsWith("text/") ||
+    mediaType.endsWith("+json") ||
+    mediaType.endsWith("+xml") ||
+    TEXT_CONTENT_TYPES.has(mediaType)
+  )
+}
+
+const captureResponseBody = (response: HttpClientResponse.HttpClientResponse, contentType: string | undefined) =>
+  response.arrayBuffer.pipe(
+    Effect.map((bytes) =>
+      isTextContentType(contentType)
+        ? { body: new TextDecoder().decode(bytes) }
+        : { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" as const },
+    ),
+  )
+
+const decodeResponseBody = (snapshot: ResponseSnapshot) =>
+  snapshot.bodyEncoding === "base64" ? Buffer.from(snapshot.body, "base64") : snapshot.body
+
+const responseFromSnapshot = (request: HttpClientRequest.HttpClientRequest, snapshot: ResponseSnapshot) =>
+  HttpClientResponse.fromWeb(
+    request,
+    new Response(
+      request.method === "HEAD" || snapshot.status === 204 || snapshot.status === 205 || snapshot.status === 304
+        ? null
+        : decodeResponseBody(snapshot),
+      snapshot,
+    ),
+  )
+
+export const redactedErrorRequest = (request: HttpClientRequest.HttpClientRequest) =>
+  HttpClientRequest.makeWith(
+    request.method,
+    redactUrl(request.url),
+    UrlParams.empty,
+    Option.none(),
+    Headers.empty,
+    HttpBody.empty,
+  )
+
+const transportError = (request: HttpClientRequest.HttpClientRequest, description: string) =>
+  new HttpClientError.HttpClientError({
+    reason: new HttpClientError.TransportError({ request: redactedErrorRequest(request), description }),
+  })
+
+export const recordingLayer = (
+  name: string,
+  options: Omit<RecordReplayOptions, "directory"> = {},
+): Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient | CassetteService.Service> =>
+  Layer.effect(
+    HttpClient.HttpClient,
+    Effect.gen(function* () {
+      const upstream = yield* HttpClient.HttpClient
+      const cassetteService = yield* CassetteService.Service
+      const redactor = options.redactor ?? make()
+      const match = options.match ?? defaultMatcher
+      const requested = options.mode ?? "auto"
+      const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
+
+      const snapshotRequest = (request: HttpClientRequest.HttpClientRequest) =>
+        Effect.gen(function* () {
+          const web = yield* HttpClientRequest.toWeb(request).pipe(Effect.orDie)
+          return redactor.request({
+            method: web.method,
+            url: web.url,
+            headers: Object.fromEntries(web.headers.entries()),
+            body: yield* Effect.promise(() => web.text()),
+          })
+        })
+
+      if (mode === "passthrough") return upstream
+
+      if (mode === "record") {
+        const initial = yield* Deferred.make<void>()
+        yield* Deferred.succeed(initial, undefined)
+        const tail = yield* Ref.make(initial)
+        return HttpClient.make((request) =>
+          Effect.gen(function* () {
+            const completed = yield* Deferred.make<void>()
+            const previous = yield* Ref.modify(tail, (current) => [current, completed])
+            return yield* Effect.gen(function* () {
+              const incoming = yield* snapshotRequest(request)
+              const response = yield* upstream.execute(request)
+              const captured = yield* captureResponseBody(response, response.headers["content-type"])
+              const responseSnapshot: ResponseSnapshot = {
+                status: response.status,
+                headers: response.headers as Record<string, string>,
+                ...captured,
+              }
+              const interaction: HttpInteraction = {
+                transport: "http",
+                request: incoming,
+                response: redactor.response(responseSnapshot),
+              }
+              yield* Deferred.await(previous)
+              yield* cassetteService
+                .append(name, interaction, options.metadata)
+                .pipe(
+                  Effect.catchTag("UnsafeCassetteError", (error) =>
+                    Effect.fail(transportError(request, error.message)),
+                  ),
+                )
+              return responseFromSnapshot(request, responseSnapshot)
+            }).pipe(Effect.ensuring(Deferred.succeed(completed, undefined)))
+          }),
+        )
+      }
+
+      const replay = yield* makeReplayState(cassetteService, name, httpInteractions)
+      return HttpClient.make((request) =>
+        Effect.gen(function* () {
+          const incoming = yield* snapshotRequest(request)
+          const claimed = yield* replay
+            .claim((interaction, index, interactions) => {
+              const result = selectSequential(interactions, incoming, match, index)
+              if (result.interaction) return Effect.void
+              return Effect.fail(
+                transportError(request, `Fixture "${name}" does not match the current request: ${result.detail}.`),
+              )
+            })
+            .pipe(
+              Effect.mapError((error) =>
+                error._tag === "CassetteNotFoundError"
+                  ? transportError(
+                      request,
+                      `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`,
+                    )
+                  : error,
+              ),
+            )
+          return responseFromSnapshot(request, claimed.interaction.response)
+        }),
+      )
+    }),
+  )
+
+export const cassetteLayer = (name: string, options: RecordReplayOptions = {}): Layer.Layer<HttpClient.HttpClient> =>
+  recordingLayer(name, options).pipe(
+    Layer.provide(CassetteService.fileSystem({ directory: options.directory })),
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(NodeFileSystem.layer),
+  )

package/src/internal.ts

@@ -0,0 +1,15 @@
+export { CassetteNotFoundError, hasCassetteSync, UnsafeCassetteError } from "./cassette.js"
+export { cassetteLayer, recordingLayer, type RecordReplayMode, type RecordReplayOptions } from "./internal-effect.js"
+export { redactHeaders, redactUrl, secretFindings, type SecretFinding } from "./redaction.js"
+export { socketLayer } from "./socket.js"
+export {
+  makeWebSocketExecutor,
+  type WebSocketConnection,
+  type WebSocketExecutor,
+  type WebSocketRecordReplayOptions,
+  type WebSocketRequest,
+} from "./websocket.js"
+export * as Cassette from "./cassette.js"
+export * as Redactor from "./redactor.js"
+
+export * as HttpRecorderInternal from "./internal.js"

package/src/matching.ts

@@ -0,0 +1,106 @@
+import { Option, Schema } from "effect"
+import { REDACTED, secretFindings } from "./redaction.js"
+import type { HttpInteraction, RequestMatcher, RequestSnapshot } from "./types.js"
+
+const JsonValue = Schema.fromJsonString(Schema.Unknown)
+export const decodeJson = Schema.decodeUnknownOption(JsonValue)
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+
+export const canonicalizeJson = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(canonicalizeJson)
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .toSorted()
+        .map((key) => [key, canonicalizeJson(value[key])]),
+    )
+  }
+  return value
+}
+
+export type { RequestMatcher } from "./types.js"
+
+export const canonicalSnapshot = (snapshot: RequestSnapshot): string =>
+  JSON.stringify({
+    method: snapshot.method,
+    url: snapshot.url,
+    headers: canonicalizeJson(snapshot.headers),
+    body: Option.match(decodeJson(snapshot.body), {
+      onNone: () => snapshot.body,
+      onSome: canonicalizeJson,
+    }),
+  })
+
+export const defaultMatcher: RequestMatcher = (incoming, recorded) =>
+  canonicalSnapshot(incoming) === canonicalSnapshot(recorded)
+
+export const safeText = (value: unknown) => {
+  if (value === undefined) return "undefined"
+  if (secretFindings(value).length > 0) return JSON.stringify(REDACTED)
+  const text = JSON.stringify(value)
+  if (!text) return typeof value
+  return text.length > 300 ? `${text.slice(0, 300)}...` : text
+}
+
+const jsonBody = (body: string) => Option.getOrUndefined(decodeJson(body))
+
+const valueDiffs = (expected: unknown, received: unknown, base = "$", limit = 8): ReadonlyArray<string> => {
+  if (Object.is(expected, received)) return []
+  if (isRecord(expected) && isRecord(received)) {
+    return [...new Set([...Object.keys(expected), ...Object.keys(received)])]
+      .toSorted()
+      .flatMap((key) => valueDiffs(expected[key], received[key], `${base}.${key}`, limit))
+      .slice(0, limit)
+  }
+  if (Array.isArray(expected) && Array.isArray(received)) {
+    return Array.from({ length: Math.max(expected.length, received.length) }, (_, index) => index)
+      .flatMap((index) => valueDiffs(expected[index], received[index], `${base}[${index}]`, limit))
+      .slice(0, limit)
+  }
+  return [`${base} expected ${safeText(expected)}, received ${safeText(received)}`]
+}
+
+const headerDiffs = (expected: Record<string, string>, received: Record<string, string>) =>
+  [...new Set([...Object.keys(expected), ...Object.keys(received)])].toSorted().flatMap((key) => {
+    if (expected[key] === received[key]) return []
+    if (expected[key] === undefined) return [`  ${key} unexpected ${safeText(received[key])}`]
+    if (received[key] === undefined) return [`  ${key} missing expected ${safeText(expected[key])}`]
+    return [`  ${key} expected ${safeText(expected[key])}, received ${safeText(received[key])}`]
+  })
+
+export const requestDiff = (expected: RequestSnapshot, received: RequestSnapshot): ReadonlyArray<string> => {
+  const lines: string[] = []
+  if (expected.method !== received.method) {
+    lines.push("method:", `  expected ${expected.method}, received ${received.method}`)
+  }
+  if (expected.url !== received.url) {
+    lines.push("url:", `  expected ${expected.url}`, `  received ${received.url}`)
+  }
+  const headers = headerDiffs(expected.headers, received.headers)
+  if (headers.length > 0) lines.push("headers:", ...headers.slice(0, 8))
+  const expectedBody = jsonBody(expected.body)
+  const receivedBody = jsonBody(received.body)
+  const body =
+    expectedBody !== undefined && receivedBody !== undefined
+      ? valueDiffs(expectedBody, receivedBody).map((line) => `  ${line}`)
+      : expected.body === received.body
+        ? []
+        : [`  expected ${safeText(expected.body)}, received ${safeText(received.body)}`]
+  if (body.length > 0) lines.push("body:", ...body)
+  return lines
+}
+
+export const selectSequential = (
+  interactions: ReadonlyArray<HttpInteraction>,
+  incoming: RequestSnapshot,
+  match: RequestMatcher,
+  index: number,
+): { readonly interaction: HttpInteraction | undefined; readonly detail: string } => {
+  const interaction = interactions[index]
+  if (!interaction) return { interaction, detail: `interaction ${index + 1} of ${interactions.length} not recorded` }
+  if (!match(incoming, interaction.request))
+    return { interaction: undefined, detail: requestDiff(interaction.request, incoming).join("\n") }
+  return { interaction, detail: "" }
+}

package/src/recorder.ts

@@ -0,0 +1,62 @@
+import { Effect, Scope, SynchronizedRef } from "effect"
+import type * as CassetteService from "./cassette.js"
+import type { CassetteNotFoundError } from "./cassette.js"
+import type { Interaction } from "./schema.js"
+
+const isCI = () => {
+  const value = process.env.CI
+  return value !== undefined && value !== "" && value !== "false" && value !== "0"
+}
+
+export const resolveAutoMode = (
+  cassette: CassetteService.Interface,
+  name: string,
+): Effect.Effect<"record" | "replay" | "passthrough"> =>
+  Effect.gen(function* () {
+    if (isCI()) return "replay"
+    return (yield* cassette.exists(name)) ? "replay" : "record"
+  })
+
+export interface ReplayState<T> {
+  readonly claim: <E>(
+    validate: (interaction: T | undefined, index: number, interactions: ReadonlyArray<T>) => Effect.Effect<void, E>,
+  ) => Effect.Effect<{ readonly interaction: T; readonly index: number }, CassetteNotFoundError | E>
+}
+
+export const makeReplayState = <T>(
+  cassette: CassetteService.Interface,
+  name: string,
+  project: (interactions: ReadonlyArray<Interaction>) => ReadonlyArray<T>,
+): Effect.Effect<ReplayState<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const load = yield* Effect.cached(cassette.read(name).pipe(Effect.map(project)))
+    const position = yield* SynchronizedRef.make(0)
+
+    yield* Effect.addFinalizer(() =>
+      Effect.gen(function* () {
+        const used = yield* SynchronizedRef.get(position)
+        if (used === 0) return yield* Effect.void
+        const interactions = yield* load.pipe(Effect.orDie)
+        if (used < interactions.length)
+          return yield* Effect.die(
+            new Error(`Unused recorded interactions in ${name}: used ${used} of ${interactions.length}`),
+          )
+        return yield* Effect.void
+      }),
+    )
+
+    return {
+      claim: (validate) =>
+        Effect.flatMap(load, (interactions) =>
+          SynchronizedRef.modifyEffect(position, (index) =>
+            Effect.gen(function* () {
+              const interaction = interactions[index]
+              yield* validate(interaction, index, interactions)
+              if (interaction === undefined)
+                return yield* Effect.die("Replay validation accepted a missing interaction")
+              return [{ interaction, index }, index + 1] as const
+            }),
+          ),
+        ),
+    }
+  })