evidrift

# Evidrift — replay-verified JSON reductions and API drift evidence

[English](README.md) | [繁體中文](README.zh-TW.md)

[![CI](https://github.com/bm1016bm-svg/evidrift/actions/workflows/ci.yml/badge.svg)](https://github.com/bm1016bm-svg/evidrift/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/evidrift.svg)](https://www.npmjs.com/package/evidrift)
[![Website](https://img.shields.io/badge/docs-GitHub%20Pages-111111.svg)](https://bm1016bm-svg.github.io/evidrift/)
[![Indexed on TensorBlock MCP Index](https://mcp-index.tensorblock.co/v1/servers/github-bm1016bm-svg-evidrift-85713ef9/badge.svg)](https://www.tensorblock.co/mcp/servers/github-bm1016bm-svg-evidrift-85713ef9)

> **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.

![Evidrift — AI dependency lockfile](https://raw.githubusercontent.com/bm1016bm-svg/evidrift/main/docs/assets/evidrift-hero.png)

[![Real Evidrift CLI demo: a dependency contract passes, its TypeScript signature changes, and Evidrift catches the drift before merge](https://raw.githubusercontent.com/bm1016bm-svg/evidrift/main/docs/assets/evidrift-demo.gif)](#quick-start--see-drift-in-one-command)

The animation is rendered from a [captured CLI transcript](https://github.com/bm1016bm-svg/evidrift/blob/main/docs/assets/evidrift-demo-transcript.txt). 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:

```bash
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:

```bash
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:

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

See the complete [ReproMin fixture, guarantees, and replay safety boundary](docs/repro-min.md).

## Quick Start — See Drift in One Command

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

```bash
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](https://github.com/bm1016bm-svg/evidrift).**

## Supported Today

| Surface                                         | Deterministic evidence                                               | Status             |
| ----------------------------------------------- | -------------------------------------------------------------------- | ------------------ |
| Loopback HTTP JSON failure                      | Replayed reduction matching status plus error identity               | CLI only           |
| Installed TypeScript dependency                 | Selected call signature, parameter, package version, and declaration | Supported          |
| Repository OpenAPI / JSON Schema                | Canonical value selected through an RFC 6901 JSON Pointer            | Supported for JSON |
| Contract CLI and local STDIO MCP                | The same record and revalidation core                                | Supported          |
| Remote replay, cURL import, YAML, remote `$ref` | None; Evidrift refuses these inputs instead of guessing              | Not supported      |

## Installation — Add It to a Repository

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

```bash
npx --yes evidrift@latest init
```

To pin Evidrift for a team or CI workflow:

```bash
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.

```bash
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:

```bash
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](docs/mcp.md) is included.

## How It Works

```mermaid
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](docs/architecture.md).

## The Files

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

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

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

```json
{
  "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](docs/receipt-schema.md).

## Add It to CI

Pin Evidrift as a development dependency and expose one stable package script:

```json
{
  "scripts": {
    "evidrift:check": "evidrift check"
  }
}
```

After `npm ci`, make that script a required CI step:

```yaml
- name: Revalidate Evidrift receipts
  run: npm run evidrift:check
```

The complete [GitHub Actions setup](docs/ci.md) uses read-only permissions, locked npm dependencies, and commit-pinned Actions.

The root `action.yml` provides a Marketplace-ready contract check. It runs only the
network-free contract workflow; ReproMin replay is never triggered by that Action.

## CI Behavior

`evidrift check` does not trust saved `matched` or `verified` flags. It validates the Receipt, reloads the source, and recomputes the selected signature or JSON value.

| Result                    | Meaning                                                            | Exit |
| ------------------------- | ------------------------------------------------------------------ | ---: |
| `PASS`                    | The deterministic signature or JSON value still matches            |    0 |
| `WARNING source_changed`  | Source identity/content changed, but the selected contract matches |    0 |
| `WARNING unverifiable`    | Source is missing, invalid, or cannot be inspected                 |    0 |
| `FAIL contract_mismatch`  | Selected TypeScript signature or JSON value changed/disappeared    |    1 |
| `FAIL evidence_integrity` | Lock or Receipt is malformed, missing, forged, or hash-invalid     |    2 |

For CI systems, coding agents, and other tools, request a versioned JSON report without changing those exit codes:

```bash
npx evidrift check --format json
```

The report includes `schemaVersion`, the Evidrift version, summary counts, and the ordered `CheckResult` objects. It contains no timestamp or absolute repository root, so equal results serialize identically. See the [JSON check report contract](docs/check-report.md).

A one-line manual edit to a Receipt produces an actionable integrity report:

```text
FAIL evidence_integrity sha256:...
Message: Receipt content hash mismatch.
Receipt ID: sha256:...
Action: Do not trust or hand-edit this Receipt. Restore it from version control, or intentionally create a new Receipt with `evidrift record`.
```

The project workflow runs the full gate on Linux and Windows with Node.js 22 and 24. Third-party Actions