chore(http-recorder): remove content-matching dispatch mode (#26792)

packages/http-recorder/README.md

@@ -70,19 +70,15 @@ Cassettes are normal source files — review them, diff them, commit them.
 
 ## Request matching
 
-By default, requests match on canonicalized method, URL, headers, and JSON
-body (object keys sorted). Two dispatch strategies are available:
+Replay walks the cassette in record order via an internal cursor: the Nth
+request executed at runtime is served by the Nth recorded interaction, and
+each one is validated as the cursor advances. Request equality is computed
+on canonicalized method, URL, headers, and JSON body (object keys sorted).
 
-- **`match`** (default) — find the first recorded interaction whose request
-  matches the incoming request. Same request twice returns the same response.
-- **`sequential`** — return interactions in the order they were recorded,
-  validating each one matches as the cursor advances. Use for ordered flows
-  where the same URL is hit multiple times with meaningful state changes
-  (pagination, retries, polling).
-
-```ts
-HttpRecorder.cassetteLayer("flow/poll-until-done", { dispatch: "sequential" })
-```
+This is deliberately strict — content-based dispatch was removed because
+it silently returns the first recorded response for repeated identical
+requests, masking state changes that retry/polling/cache-hit tests need to
+observe. If you reorder requests in a test, re-record the cassette.
 
 Supply your own matcher via `match: (incoming, recorded) => boolean` for
 custom equivalence (e.g. ignoring a timestamp field in the body).
@@ -194,7 +190,6 @@ type RecordReplayOptions = {
   directory?: string // default: <cwd>/test/fixtures/recordings
   metadata?: Record<string, unknown> // merged into cassette.metadata
   redactor?: Redactor // default: Redactor.defaults()
-  dispatch?: "match" | "sequential" // default: "match"
   match?: (incoming, recorded) => boolean // custom matcher
 }
 ```
@@ -211,4 +206,4 @@ type RecordReplayOptions = {
 | `redaction.ts` | Lower-level header/URL primitives + secret pattern detection.                    |
 | `schema.ts`    | Effect Schema definitions for the cassette JSON format.                          |
 | `storage.ts`   | Path resolution, JSON encode/decode, sync existence check.                       |
-| `matching.ts`  | Request matcher, canonicalization, dispatch strategies, mismatch diagnostics.    |
+| `matching.ts`  | Request matcher, canonicalization, sequential cursor, mismatch diagnostics.      |

packages/http-recorder/src/effect.ts

@@ -11,7 +11,7 @@ import {
   UrlParams,
 } from "effect/unstable/http"
 import * as CassetteService from "./cassette"
-import { defaultMatcher, selectMatch, selectSequential, type RequestMatcher } from "./matching"
+import { defaultMatcher, selectSequential, type RequestMatcher } from "./matching"
 import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
 import { defaults, type Redactor } from "./redactor"
 import { redactUrl } from "./redaction"
@@ -24,7 +24,6 @@ export interface RecordReplayOptions {
   readonly directory?: string
   readonly metadata?: CassetteMetadata
   readonly redactor?: Redactor
-  readonly dispatch?: "match" | "sequential"
   readonly match?: RequestMatcher
 }
 
@@ -71,7 +70,6 @@ export const recordingLayer = (
       const match = options.match ?? defaultMatcher
       const requested = options.mode ?? "auto"
       const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
-      const sequential = options.dispatch === "sequential"
       const replay = yield* makeReplayState(cassetteService, name, httpInteractions)
 
       const snapshotRequest = (request: HttpClientRequest.HttpClientRequest) =>
@@ -119,14 +117,12 @@ export const recordingLayer = (
               transportError(request, `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`),
             ),
           )
-          const result = sequential
-            ? selectSequential(interactions, incoming, match, yield* replay.cursor)
-            : selectMatch(interactions, incoming, match)
+          const result = selectSequential(interactions, incoming, match, yield* replay.cursor)
           if (!result.interaction)
             return yield* Effect.fail(
               transportError(request, `Fixture "${name}" does not match the current request: ${result.detail}.`),
             )
-          if (sequential) yield* replay.advance
+          yield* replay.advance
           return HttpClientResponse.fromWeb(
             request,
             new Response(decodeResponseBody(result.interaction.response), result.interaction.response),

packages/http-recorder/src/matching.ts

@@ -92,24 +92,6 @@ export const requestDiff = (expected: RequestSnapshot, received: RequestSnapshot
   return lines
 }
 
-export const mismatchDetail = (interactions: ReadonlyArray<HttpInteraction>, incoming: RequestSnapshot): string => {
-  if (interactions.length === 0) return "cassette has no recorded HTTP interactions"
-  const ranked = interactions
-    .map((interaction, index) => ({ index, lines: requestDiff(interaction.request, incoming) }))
-    .toSorted((a, b) => a.lines.length - b.lines.length || a.index - b.index)
-  const best = ranked[0]
-  return ["no recorded interaction matched", `closest interaction: #${best.index + 1}`, ...best.lines].join("\n")
-}
-
-export const selectMatch = (
-  interactions: ReadonlyArray<HttpInteraction>,
-  incoming: RequestSnapshot,
-  match: RequestMatcher,
-): { readonly interaction: HttpInteraction | undefined; readonly detail: string } => {
-  const interaction = interactions.find((candidate) => match(incoming, candidate.request))
-  return { interaction, detail: interaction ? "" : mismatchDetail(interactions, incoming) }
-}
-
 export const selectSequential = (
   interactions: ReadonlyArray<HttpInteraction>,
   incoming: RequestSnapshot,

packages/http-recorder/test/record-replay.test.ts

@@ -230,19 +230,10 @@ describe("http-recorder", () => {
     )
   })
 
-  test("default matcher dispatches multi-interaction cassettes by request shape", async () => {
-    await run(
-      Effect.gen(function* () {
-        expect(yield* post("https://example.test/echo", { step: 2 })).toBe('{"reply":"second"}')
-        expect(yield* post("https://example.test/echo", { step: 1 })).toBe('{"reply":"first"}')
-      }),
-    )
-  })
-
-  test("sequential dispatch returns recorded responses in order for identical requests", async () => {
+  test("replay returns recorded responses in order for identical requests", async () => {
     await runWith(
       "record-replay/retry",
-      { dispatch: "sequential" },
+      {},
       Effect.gen(function* () {
         expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"pending"}')
         expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"complete"}')
@@ -250,21 +241,8 @@ describe("http-recorder", () => {
     )
   })
 
-  test("default matcher returns the first match for identical requests", async () => {
-    await runWith(
-      "record-replay/retry",
-      {},
-      Effect.gen(function* () {
-        expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"pending"}')
-        expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"pending"}')
-      }),
-    )
-  })
-
-  test("sequential dispatch reports cursor exhaustion when more requests are made than recorded", async () => {
-    await runWith(
-      "record-replay/multi-step",
-      { dispatch: "sequential" },
+  test("replay reports cursor exhaustion when more requests are made than recorded", async () => {
+    await run(
       Effect.gen(function* () {
         yield* post("https://example.test/echo", { step: 1 })
         yield* post("https://example.test/echo", { step: 2 })
@@ -274,10 +252,8 @@ describe("http-recorder", () => {
     )
   })
 
-  test("sequential dispatch still validates each recorded request", async () => {
-    await runWith(
-      "record-replay/multi-step",
-      { dispatch: "sequential" },
+  test("replay validates each recorded request in order", async () => {
+    await run(
       Effect.gen(function* () {
         yield* post("https://example.test/echo", { step: 1 })
         const exit = yield* Effect.exit(post("https://example.test/echo", { step: 3 }))
@@ -331,14 +307,13 @@ describe("http-recorder", () => {
     }
   })
 
-  test("mismatch diagnostics show closest redacted request differences", async () => {
+  test("mismatch diagnostics show redacted request differences against the expected interaction", async () => {
     await run(
       Effect.gen(function* () {
         const exit = yield* Effect.exit(
           post("https://example.test/echo?api_key=secret-value", { step: 3, token: "sk-123456789012345678901234" }),
         )
         const message = failureText(exit)
-        expect(message).toContain("closest interaction: #1")
         expect(message).toContain("url:")
         expect(message).toContain("https://example.test/echo?api_key=%5BREDACTED%5D")
         expect(message).toContain("body:")