Evidrift — replay-verified JSON reductions and API drift evidence

English | 繁體中文

Failures arrive noisy. APIs drift quietly. Evidrift turns both into deterministic evidence.

Evidrift has two deliberately separate workflows:

• ReproMin repeatedly removes JSON data, replays each candidate against a disposable local HTTP target, and keeps only reductions that still match the selected failure identity.
• Contract drift records an exact TypeScript call signature or repository JSON value as a content-addressed Receipt, then makes CI recompute it before merge.

Local-first CLI. STDIO MCP server for contract recording only. No account, cloud backend, telemetry, or LLM judge.

The animation is rendered from a captured CLI transcript. The PASS, changed signatures, affected file, and deterministic FAIL come from an actual local evidrift demo run; only the scene headings are editorial.

Quick Start — Minimize a Failing Request

Requires Node.js 22 or newer. The zero-setup demo starts a disposable loopback server, verifies one HTTP failure, minimizes its JSON request, verifies the result again, and shuts the server down:

npx --yes evidrift@latest repro-demo

The result is not selected by an LLM. Every accepted reduction is actually replayed and must match both the expected HTTP status and error identity.

For your own local endpoint:

npx evidrift minimize \
  --request failing-request.json \
  --status 500 \
  --response-pointer /error/code \
  --response-equals '"INVALID_FILTER"' \
  --output minimal-repro.json \
  --confirm-replay yes

Then replay the content-addressed artifact once:

npx evidrift reproduce --artifact minimal-repro.json --confirm-replay yes

See the complete ReproMin fixture, guarantees, and replay safety boundary.

Quick Start — See Drift in One Command

Requires Node.js 22 or newer. Nothing to install globally:

npx --yes evidrift@latest demo

The command creates a disposable local fixture, records the optional options parameter on parseConfig, checks it successfully, changes the fixture so options is required, then proves that evidrift check catches the mismatch. It runs no downloaded package code.

If that is a failure you want caught before merge, star Evidrift on GitHub.

Real-world Lab — React 19 useRef

The synthetic demo is fast; this source-repository lab proves the same workflow against a real, documented ecosystem change. React's official upgrade guide says React 19 makes the first useRef argument required. Evidrift records the no-argument overload from @types/react@18.3.12, upgrades only that type package to @types/react@19.0.1, and reports the missing overload:

git clone https://github.com/bm1016bm-svg/evidrift.git
cd evidrift
npm ci --ignore-scripts
npm run demo:react-19

Both package versions are exact and verified after installation. The lab disables dependency lifecycle scripts, and its final evidrift check must return a deterministic contract mismatch. See the reproduction and complete trust boundary and the official React 19 upgrade guide.

Supported Today

Installation — Add It to a Repository

Initialize the current repository without a global install, account, API key, or cloud backend:

npx --yes evidrift@latest init

To add an idempotent pull-request workflow with file-and-line annotations:

npx --yes evidrift@latest init --github-actions

The initializer detects npm, pnpm, or Yarn, adds scripts.evidrift:check, and creates .github/workflows/evidrift.yml. Existing scripts and workflows are reported and preserved instead of being overwritten.

To pin Evidrift for a team or CI workflow:

npm install --save-dev evidrift
npx evidrift init

That is the product: make an AI assumption reviewable now, then make CI check the same contract later.

Use It in a Repository

The dependency must already be installed inside the target repository, and the affected code path must name a real file.

cd /path/to/your/repository
evidrift init

evidrift record \
  --project . \
  --package your-package \
  --symbol exportedFunction \
  --parameter options \
  --claim "exportedFunction accepts the options used here." \
  --code src/caller.ts:12

evidrift check

When --code includes a line containing an overloaded call, Evidrift asks TypeScript which overload that call actually resolves to. --overload <number> remains an explicit fallback for incomplete or non-compiling call sites.

Lock one value from a repository-local OpenAPI or JSON Schema document:

evidrift record \
  --json openapi.json \
  --pointer /paths/~1users/get/operationId \
  --claim "The generated client calls listUsers." \
  --code src/client.ts:24

JSON Pointer follows RFC 6901, including ~1 for / and ~0 for ~. Evidrift reads .json files only; it never fetches URLs or resolves remote references.

Coding agents call the same core through evidrift_record and evidrift_record_json_pointer. Minimal Codex, Claude Code, and Cursor setup is included.

How It Works

flowchart LR
  Author["Developer"] --> Minimize["Minimize failing JSON"]
  Minimize --> Replay["Replay loopback failure"]
  Replay --> Repro["Content-addressed reproduction"]
  Agent["Coding agent or developer"] --> Record["Record one assumption"]
  Record --> Adapter["TypeScript or JSON adapter"]
  Adapter --> Receipt["Content-addressed Receipt"]
  Receipt --> Review["Git review"]
  Review --> Check["evidrift check in CI"]
  Check --> Result{"Contract still matches?"}
  Result -->|Yes| Pass["PASS"]
  Result -->|Source unavailable| Warn["WARNING"]
  Result -->|No or tampered| Fail["FAIL"]

The CLI and MCP server are thin entry points over the same core. The complete component map, check policy, resource bounds, and trust boundary are documented in Architecture.

The Files

Evidrift writes one lock and one immutable JSON file per Receipt:

.evidrift/
  evidence.lock
  receipts/
    <64-character-sha256>.json

There is no .evidrift/receipts.json. evidence.lock contains only content-addressed Receipt IDs:

{
  "receipts": ["sha256:9bfbb065cff372abe52e8e269123959e9f2ae84cd02230dc751f768ac5e4c274"],
  "schemaVersion": 1
}

Each Receipt stores the claim and affected code plus one deterministic contract: an installed TypeScript symbol signature, or a repository JSON path, pointer, canonical value, and hashes. See the Receipt schema.

Add It to CI

Generate the package script and read-only pull-request workflow:

npx evidrift init --github-actions

The generated package script pins the current Evidrift release:

{
  "scripts": {
    "evidrift:check": "npx --yes evidrift@0.4.1 check"
  }
}

Run the same pinned check locally with npm run evidrift:check.

The generated workflow installs locked repository dependencies with lifecycle scripts disabled, then runs the Marketplace Action. Contract mismatches and integrity failures become PR errors at the affected file and line; source-change and unavailable-evidence results become warnings.

evidrift check --annotations github

With --format json, GitHub workflow commands are written to standard error so standard output remains valid JSON. The complete GitHub Actions setup documents the generated workflow, permissions, package-manager behavior, and manual setup.