Glossary

A short reference for the vocabulary used across the docs and the Decisions pages.

cassette

A pretty-printed JSON file holding recorded model interactions — the canonicalized request, the recorded response (a generate content array or a stream chunk array), and metadata (version, hash, recordedAt). Hash-addressed cassettes hold one interaction; named cassettes are multi-interaction. Either way they diff cleanly in PRs and are committed alongside the tests that depend on them.

cassette store

The storage backend cassette I/O goes through (read / write / list). The default is the filesystem, loaded lazily; memoryCassetteStore() keeps cassettes in a Map for tests and edge runtimes, and the same three-method interface fits KV/R2 on Cloudflare Workers.

CassetteError family

The shared base class for every error tapedeck throws, so you can catch the whole set with one instanceof CassetteError. Members: CassetteMissError (replay found no matching cassette), CassetteSecretError (a replayed cassette still contains a value a redaction matcher would strip), CassetteCorruptError (invalid JSON, unknown version, or malformed response shape), CassetteModeError (an invalid mode string), and CassetteDriftError (compare found drift and no onCompare handler owned it). See Decisions.

chunk / stream part

One ordered element of a recorded stream — a text-delta, a tool-call, and friends. In record mode tapedeck drains the live stream and captures these parts in order; in replay mode it re-serves the same array through simulateReadableStream.

compare mode

Calls the real model and loads the recorded cassette, reports how the two diverged, and returns the live result. It never writes: the cassette is left byte-identical, which is what separates it from record. A miss still throws, and unhandled drift throws CassetteDriftError, so npx tapedeck compare pnpm test is a CI gate. Because it calls the provider it costs tokens: run it on a schedule, not on every push.

drift

The gap that opens between a committed cassette and what the model does today, when the provider retunes the model underneath a fixture nobody changed. compare mode measures it on three signals: the tool-call trajectory, the unified finish reason, and text (exact, normalized, or different). result.equal is true when the trajectory and finish reason match and the text is no worse than normalized. See Decisions.

hash

The stable, semantic SHA-256 that identifies a cassette. Computed over the canonicalized, sorted JSON of { modelProvider, modelId, prompt, toolSchemas, maxOutputTokens, temperature, topP }. A changed prompt, tool input schema, or sampling param changes the hash and forces a re-record; cosmetic tool-description edits do not, because schemas are normalized first.

live mode

Passthrough. tapedeck does no recording and no lookup — the call goes straight to the real model. The recommended mode in local development.

miss

A replay-mode lookup that finds no cassette matching the request hash. A miss throws CassetteMissError rather than falling back to the network. That is deliberate: a changed prompt or tool schema should fail CI loudly and force a re-record, not silently replay stale data or make a live call. See Decisions.

multi-interaction cassette

The v2 format used by named cassettes (withCassette / cassetteName): one file holding every model call a test makes, as interactions: { hash, request, response }[]. Each call records and replays its own entry keyed by hash, in any order. A withCassette run is one recording session — re-recording starts the file fresh, so stale interactions never linger.

normalization

The canonicalization applied to tool schemas before hashing (normalizeTools): descriptions are stripped and keys are sorted, so a doc-only change to a tool doesn't invalidate an otherwise-identical cassette. The wider request is canonicalized with stableStringify.

record mode

Calls the real model, serializes the request and response into a cassette on disk (after redaction), and returns the live result so your code still runs normally. Used once to capture a fixture.

redaction matcher

A key-name rule that strips secrets at record time, so they never reach disk. Defaults: apiKey, authorization, x-api-key, bearer, token (case-insensitive). Extend via redact: (string | RegExp)[] — strings match field/header names case-insensitively, RegExps test the raw key. A replayed cassette that still contains a value a matcher would strip throws CassetteSecretError.

replay mode

Looks up the cassette by hash and serves it offline, deterministically, and for free. A miss throws. Streams are replayed as genuine streams via simulateReadableStream.

simulateReadableStream

The AI SDK's own helper that tapedeck uses in replay mode to turn a recorded chunk array back into a real ReadableStream. Because replay rides the SDK's own machinery, streamText, UI message streams, and tool-call streaming all see the same surface they would live.

spec version

The version of the AI SDK's language-model middleware surface. ai@6 takes spec v3 and ai@7 takes spec v4; the two concrete types are mutually unassignable. tapedeck types its boundary structurally (TapedeckMiddleware), declaring only the fields it reads and staying generic in the result type, so one middleware object is assignable to both with no cast. specificationVersion stays 'v3' because v4 hosts accept any string while v3 hosts accept only 'v3'. See Compatibility.

stream part

See chunk / stream part.

tool-call trajectory

The ordered sequence of tool calls a response makes: tool names, in order, with their inputs. It is the behavioural contract of an agent, so compare mode treats a changed trajectory as drift while tolerating text that differs only in whitespace or case. Inputs are compared as canonical JSON, so a reordered key is never drift. The toFollowRoute() matcher asserts the same trajectory against a toolroute router.