Evidrift — evidence lockfile for AI coding agents
Code compiles. APIs drift. Evidrift is the lockfile for AI assumptions.
Coding agents can write against a dependency contract that changes tomorrow. Evidrift records the exact TypeScript symbol contract as a content-addressed Receipt, then makes CI recompute it before merge.
Local-first CLI. STDIO MCP server. No account, no cloud backend, no LLM judge, and no package code execution.
Installation
Requires Node.js 22 or newer. Run Evidrift directly from npm:
That command initializes the current repository. No global install, Evidrift account, API key, or cloud backend is required.
To pin Evidrift for a team or CI workflow:
npm install --save-dev evidrift
npx evidrift init
Quick Start
Run the self-contained drift demo:
The demo creates an ignored .evidrift-demo/signature-drift workspace, records the optional options parameter on parseConfig, checks it successfully, changes the fixture so options is required, then shows the deterministic failure. It executes no downloaded package code.
FAIL contract_mismatch sha256:...
Claim: parseConfig accepts an optional options parameter used by the demo.
Expected signature: parseConfig(input:string,options?:ParseOptions):ParseResult
Current signature: parseConfig(input:string,options:ParseOptions):ParseResult
Affected code location: app/src/index.ts:3
Receipt ID: sha256:...
Action: Review the dependency change and affected code, then intentionally record a new receipt.
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
Coding agents call the same record path through evidrift_record. Minimal Codex, Claude Code, and Cursor setup is included.
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, affected code, installed package version, resolved declaration path, symbol or parameter, normalized signature, and signature hash. See the Receipt schema.
CI Behavior
evidrift check does not trust saved matched or verified flags. It validates the Receipt, resolves the installed package again, and recomputes the signature.
| Result | Meaning | Exit |
|---|
PASS | The deterministic signature still matches | 0 |
WARNING source_changed | Version or resolved path changed, but the signature matches | 0 |
WARNING unverifiable | Source is missing, invalid, or cannot be inspected | 0 |
FAIL contract_mismatch | Signature, symbol, or supported callable contract changed | 1 |
FAIL evidence_integrity | Lock or Receipt is malformed, missing, forged, or hash-invalid | 2 |
A one-line manual edit to a Receipt produces an actionable integrity report:
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 included GitHub Actions workflow runs the full gate on Node.js 22 and 24. Third-party Actions are pinned to full commit SHAs.
In a human TTY, check, diff, explain, and demo use a spinner plus green ✅, yellow ⚠, and red ❌ status output. Redirected output, CI, TERM=dumb, and NO_COLOR stay ANSI-free and keep the stable plain-text format used by agents and tests.
Why This Is Not RAG, Sonar, or AI Review
| Tool | Its job | Evidrift's job |
|---|
| RAG | Fetch context while an answer is being written | Commit one assumption and check it again later |
| Sonar/static analysis | Find code patterns and quality problems | Revalidate an explicit external dependency contract |
| AI code review | Make a probabilistic judgment | Produce a deterministic result without an LLM CI judge |
Use all of them if they help. Evidrift covers one gap: the reason code was written can go stale even when the code itself did not change.
CLI
evidrift init
evidrift record --project <path> --package <name> --symbol <name> \
[--parameter <name>] [--overload <number>] --claim <text> --code <path[:line]>
evidrift check
evidrift diff
evidrift explain <receipt-id>
evidrift demo
evidrift mcp
All commands accept --root <repo>. record requires an initialized .evidrift/evidence.lock.
evidrift mcp starts the same local STDIO server exposed by the evidrift-mcp bin. It exists so package registries and MCP clients can launch Evidrift deterministically from the main npm package.
Trust Boundary
.evidrift/receipts/*.json is untrusted input. Every check:
- Strictly validates lock and Receipt schemas.
- Derives file paths only from full SHA-256 IDs.
- Recomputes the expected-signature hash and Receipt content hash.
- Resolves declarations without importing package JavaScript, running shell commands, making network requests, or calling an LLM.
- Reports evidence integrity, source drift, semantic support, and runtime correctness separately.
The parser refuses more than 1,024 Receipt IDs or 64 call signatures per symbol. TypeScript evidence is confined to repository files and capped at 256 source files, 2 MiB per file, and 16 MiB total. Dynamic text is rejected or escaped so a Receipt cannot inject terminal controls or fake CI lines.
Content hashes detect inconsistent edits; they do not prove authorship. Someone who rewrites a Receipt, recalculates its ID, and changes evidence.lock can create new internally valid evidence. Git review and branch protection must catch that replacement. See Architecture.
What Evidrift Does Not Prove
Evidrift does not prove code is correct. It does not prove a free-text claim is true, inspect runtime behavior, eliminate hallucinations, scan dependency vulnerabilities, or validate arbitrary URLs.
The v0.2 source tree supports overloaded exported symbols through an explicit, 1-based --overload selector. The index is used only while recording; the Receipt stores the selected normalized signature and hash, so declaration reordering does not cause false drift. Evidrift does not yet infer an overload from the affected call site.
It follows repository-local declaration imports, but does not expand every named type into a deep structural contract. Missing or unreadable source is a visible but non-blocking warning. These are deliberate limits, not hidden guarantees.
The runnable boss-fight test records one of three overloads using a complex cross-file type alias, survives declaration reordering, and deterministically fails when only the selected overload changes.
Development and UAT
npm run format:check
npm run lint
npm run typecheck
npm test
npm run uat
npm run check
npm run verify runs the release gate. Tests use temporary local fixtures and require no secrets, paid APIs, Evidrift backend, or network access. The detailed UAT report maps each acceptance case to an automated test and states the remaining risks.
License
Mozilla Public License 2.0.