Agent Code Evidence · 智能体代码证据校验

Previously contextproof. Package and command names remain unchanged (contextproof). 仓库原名 contextproof，包名及现有命令保持不变。

Versioned source evidence for coding agents.

When a repository changes, a saved caller can still look identical while its dependencies have changed. ContextProof records the source and supported Python references behind that caller, explains which recorded dependency changed, and delivers current source within a measured context allowance.

The graph workflow adds immutable Git snapshots, bounded transitive dependency evidence, verified graph deltas and MCP handles. Full evidence stays in the local store; the model receives a separately budgeted source payload. Dynamic dispatch, ambiguous symbols, unsupported references and missing source remain explicit.

Python 3.11+, macOS/Linux. The core has no third-party runtime dependencies and requires no model, GPU or API key. Hosted-model experiments are separate.

简体中文 · Graph API and contracts · Measured report · Model protocol

Run the three-hop example

git clone https://github.com/hardwork-xu/agent-code-evidence.git
cd agent-code-evidence
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python scripts/demo_graph.py

Open docs/assets/graph-demo.html locally. This clearly labeled synthetic demonstration creates real Git commits, changes a third-hop dependency from 0.05 to 0.20, and runs the actual implementation. It checks that the changed source reaches the model payload, the delta exactly reconstructs the current graph, unrelated changes can retain evidence, and insufficient budgets or unknown references remain incomplete. Fixture code is inspected, never executed.

Related MCP server: metacode-sci

Use it with a repository

Replace REPOSITORY, BEFORE_COMMIT and AFTER_COMMIT with real values:

contextproof graph-capture REPOSITORY "invoice_total" \
  --ref BEFORE_COMMIT --budget 16000 \
  --output work/before.json --payload work/before-context.json

contextproof graph-refresh REPOSITORY work/before.json \
  --ref AFTER_COMMIT --view full --budget 16000 \
  --output work/after.json --payload work/current-context.json \
  --delta work/change.json

contextproof graph-apply work/before.json work/change.json \
  --output work/reconstructed.json

Use --view update when retaining the identified base context. An update is not standalone full context. Commands save full artifacts separately; only the payload file is the bounded model message. Exit 1 means incomplete delivery, which can still contain useful source; exit 2 is an input or operation error. Omitting --ref scans and hashes the working tree without promising an atomic filesystem snapshot. Immutable Git reads never fetch missing objects or execute repository code.

What is checked

Nodes have stable path/symbol/kind identities and separate source fingerprints. Line movement can change citations without retransmitting unchanged source text. ASTs are reused in memory across MCP requests; source hashes and resolution catalogs are checked again. Optional disk AST persistence remains available for measurement, but is not the default after a fair timing comparison found overhead.

The existing exact-span bundle/verify/repair workflow and v1 direct-witness capture/check/refresh APIs remain available. The latter's source-only rendering does not guarantee delivery of a changed dependency; use the graph workflow when the model needs that dependency's code. Historical evaluations remain unchanged.

MCP

Use examples/mcp.json with a fixed absolute repository root. contextproof serve ROOT exposes ten tools. The graph pair is:

• contextproof_graph_capture: choose anchors, save the full graph locally and return bounded source plus its handle.

• contextproof_graph_refresh: read that handle and return current full/update source with explicit coverage.

Their complete returned text is charged to budget in UTF-8 bytes. Tool schemas and outer conversation framing are not part of that string; actual experiment token usage is recorded separately. Legacy tool sidecars have a different budget contract, documented in the v1 report.

Evidence, including negative results

The graph replay measures exact reconstruction, additional transitive observations, delivery failures and fair cache baselines. It preserves the initial renderer's metadata-overflow failures and the slower persistent-cache design. A lexical-scope correctness review also triggered a versioned resolver correction; original artifacts are retained.

The real revision study freezes 30 upstream-derived API probes from four libraries, with 5 development and 25 held-out tasks. It compares six source conditions under a 16,000-byte cap, including a same-anchor source baseline and actual Archex 0.31.2. A capable-model gate passed 5/5 before held-out inference. The public protocol and inputs precede those completions. This is source-conditioned output prediction with supplied localization hints.

The frozen 150-completion comparison scores 8/25 with stale source and 24/25 with graph context, fresh supplied declarations or BM25; Archex scores 21/25. The graph ties the simpler same-anchor baseline and uses more input tokens. These results motivate version tracking and auditable refresh. A separate 25-completion resolver-v2 sensitivity produces the same 24/25 answers; the original 150 records remain available. Full paired results and correction history.

Earlier results remain public: 300 exact-text drift cases, 34 direct-dependency controls, and a 60-generation Qwen study with 0/20 in every condition. Neither contract agreement nor a smaller artifact establishes model effectiveness.

Reproduce and contribute

python -m pip install -e '.[dev]'
ruff check .
pytest -q tests benchmarks/graph/test_scope_audit.py benchmarks/revision_baselines/test_baselines.py
python scripts/check_publication.py
python -m build

For official MCP SDK interoperability, install .[integration] and run python scripts/check_mcp_sdk.py. Benchmark commands and frozen inputs are linked from their reports; CI does not invoke hosted models.

Related work · Security · Publication/privacy policy · Development log

Maintained by hardwork-xu, with AI assistance for design, implementation, experiments and writing. The project claims no new retrieval algorithm or published research result. Source and evaluation records are public; personal plans, account data and raw local diagnostics are kept outside Git.