💡 Why dsh-evidence?
Task claims such as "tests passed" need reviewable output files. A recorded snapshot lets a reviewer compare current files with their recorded hashes and inspect the associated claims and local receipt chain. The plugin does not observe or authenticate the command that produced those files.
dsh-evidence records snapshots and checks local consistency:
- ⛓️ Hash-Chained Receipts: Each create/add extends a logical hash chain. Verification checks recorded content, chain structure, and its binding to the manifest.
- 📦 Copied Snapshots (
copy=true): v3 stores files/... paths relative to the bundle. Moving the whole bundle preserves local copy verification; source records provenance and never substitutes for a missing copy.
- ⏱️ Temporal Validity (
validUntil): Reports expired validity dates separately from integrity. stale means content matched while the modification time differed; it does not mean a validity date expired.
- 🤝 Honest Boundary Declarations: Clear definitions of what cryptographic hashing can and cannot prove.
🚀 Quick Start
Installation
# In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-evidence
Typical Usage Flow
- Create evidence bundle:
evidence_create name="bench-2026" description="Performance audit"
- Add snapshots & assertions:
evidence_add name="bench-2026" paths="E:\\project\\bench.json|E:\\project\\verify.py" claim="Recorded benchmark output for review" validUntil="2026-12-31"
- Audit and verify:
evidence_verify name="bench-2026"
Input paths and a stable evidence root
Relative paths resolve against the calling session's project directory exposed by the verified host interface (ToolRunContext.agent.session.header.cwd). A missing, invalid or nonabsolute cwd returns RELATIVE_PATH_REQUIRES_CWD; supply complete absolute input paths in that case. There is no fallback to the plugin's startup directory and no process.chdir(). On Windows, drive-relative C:file.txt and root-relative \file.txt inputs are rejected as ambiguous; use C:\project\file.txt or a complete UNC path.
The evidence root follows a separate rule. The plugin resolves configured evidenceRoot once at apply time. Relative configured roots and relative per-call root overrides always use that same captured process directory, so different calling projects cannot move the evidence store. An absolute root override selects that exact store. With no explicit configuration, the root is DSH_HOME/evidence, or %USERPROFILE%/.dsh/evidence when DSH_HOME is unset. Prefer an absolute configured root for an independently located store.
Integrity, transactions and compatibility
v2 and v3 require a nonempty, valid receipt.jsonl bound to the current manifest. Missing/empty receipts return FAIL with RECEIPT_MISSING / RECEIPT_EMPTY. Ordinary add rejects a damaged or mismatched old chain before staging files. Genuine v1 bundles without receipts remain readable with receiptChain=UNVERIFIED_LEGACY, explicit warnings, and no ordinary append; offline migration preserves the original package.
Tool failures use the host's HarnessError contract so its error result retains the stable code. Write errors include commitState, transactionId, and failed lock cleanup details in the message when available. Cancellation after the commit decision completes publication or leaves a queryable recovery state. A completed write observed after cancellation reports COMMITTED_AFTER_CANCEL with COMMITTED and its transaction ID; later registry cancellation can still be ABORTED, with text identifying the committed outcome. Query evidence_verify / evidence_show before retrying a cancelled write. Cancellation alone does not imply that no write was committed.
status expresses integrity; freshness=CURRENT|EXPIRED separately expresses the validity dates recorded in a readable manifest, including dates on missing or corrupt files. A content-consistent expired file can pass integrity verification.
Writes stage a complete manifest, receipt generation and any copies inside .transaction/. The atomic publication of .transaction/COMMITTED is the commit decision. Before it, failures/cancellation preserve old published artifacts; after it, recovery finishes the new generation. A reported error includes a stable code and, where relevant, commitState and transactionId. Use evidence_verify to recover/query a pending transaction. The two live metadata replacements are separate recoverable publication steps. This protocol is tested for process crashes and injected write failures, not power loss.
Verification holds the bundle lock for the complete file check, so long checks delay append. Waiting and hashing support cancellation. An active owner is never displaced because its lock is old. Lock reclamation and release serialize under the same short gate, and release requires the exact PID/token. Only an ESRCH PID can be reclaimed. A reused PID, legacy/unknown owner, or orphaned .lock.gate fails closed. Verification timeout returns status=BUSY, receiptChain=NOT_CHECKED, and freshness=UNKNOWN; this makes no integrity conclusion.
After an ordinary owner process dies, the next operation can reclaim its lock and recover the transaction. A crash inside the short gate requires offline intervention: stop all writers, preserve the lock/transaction artifacts for inspection, and confirm that no owner remains before manually removing a proven orphan gate. No age-based removal is performed. Do not run old and new lock protocols together. Real desktop end-to-end validation remains a separate deployment check; simulated tool calls do not establish it.
Directory scans, limits and cancellation
evidence_add scans asynchronously without following file or directory links. Skipped links, duplicate physical files, the current bundle and its aliases are reported as exclusions. Broken links/junctions, unreadable directories, failed attributes or unsupported input types return SCAN_INCOMPLETE; they are not silently converted into a successful partial snapshot. The current bundle is excluded in full. In other recognizable bundle folders, internal .lock, .lock.gate, .transaction and named transaction cleanup directories are excluded. Ordinary input files with these names outside recognizable bundle folders remain eligible.
The defaults are maxFiles=10000 and maxTotalBytes=10737418240 (10 GiB). Overrides must be positive safe integers. Exceeding either limit returns SCAN_LIMIT_EXCEEDED without truncating or committing the scan. Empty or separator-only paths returns INPUT_EMPTY; an empty directory or an entirely excluded scan returns SCAN_EMPTY. Successful add returns scan.status=COMPLETE, file/byte totals, up to 100 exclusion paths, excludedTotal and exclusionsTruncated. COMPLETE describes the explicitly stated scan scope, including its exclusions.
For add/verify, traversal, copies and hashes run sequentially with a concurrency bound of one; file IO uses 256 KiB chunks. The host cancellation signal reaches lock waits, scanning, copying, hashing and verification. Relevant handles close before the operation promise settles. Cancellation before the transaction commit decision preserves the old published generation; after that decision, the transaction protocol finishes or reports recovery requirements. File identity and attributes are checked before and after reads and again before add commits. Observed changes return FILE_CHANGED; these checks do not create a strongly consistent snapshot of files being changed by an outside process. Metadata-only create and the offline migration command retain their separate synchronous transaction publication paths; the offline command also retains synchronous copying.
Bounded verification and browsing
evidence_verify detailLimit=20 returns full counts for missing, corrupt, stale, expired and error cases, with bounded path arrays and issues containing a path, code and reason. issueTotal and issuesRemaining disclose truncation; one file can contribute several issues. The text view shows the same full counts and remaining issue count. detailLimit accepts integers from 1 to 100. status=PASS checks current integrity, while freshness=EXPIRED means a recorded validity date has elapsed. freshness=UNKNOWN means no reliable validity conclusion was reached, for example when the bundle was BUSY or its manifest could not be read. stale reports a modification-time difference despite a matching hash.
evidence_list accepts offset=0 and limit=20 (maximum 100), returning total, returned, remaining and nextOffset. Entries are ordered by name. Invalid, missing-manifest and busy bundle directories remain visible with a status and diagnostic. READABLE describes manifest readability; use verify for file and receipt integrity. The query searches the full name/description before display truncation. Pages describe the root at each call, so concurrent additions can change later pages.
evidence_show uses the same file pagination and independent receiptOffset=0, receiptLimit=10 (maximum 100). It returns page and receiptPage, with bounded records from a valid local receipt chain. Invalid or unavailable receipts have an explicit reason. Returned descriptions, claims, sources and receipt notes escape control characters and are limited to 500 display characters; receipt payload path arrays show up to 20 paths with their original totals. Metadata and unrecognized extension fields are omitted from this bounded view. presentation identifies these omissions and the display projection: original manifest/record hashes are retained for reference, but cannot be recomputed from the paginated or sanitized projection. Read the original files to recompute those hashes. Browsing leaves original files unchanged and does not establish content truth or command execution.
The stale advisory allows up to one microsecond of rounding when millisecond metadata and filesystem timestamp APIs convert floating-point units. Active scan/copy/hash change detection compares exact nanosecond attributes and file identities instead.
Portable v3 paths and old formats
v3 entries explicitly use storage: "external" with an absolute key or storage: "copy" with a canonical files/... key. Copies reject traversal, drive/UNC keys, device names, alternate data streams and links/junctions inside the bundle. Repeated basenames receive deterministic -2, -3 suffixes; matching is case-insensitive. These boundary checks cover observed filesystem state, not a hostile process continually replacing paths outside the cooperative lock protocol.
v1/v2 external references remain readable. A legacy copy is mapped only from a recognizable <bundle>/files/<basename> key to that file in the current bundle. Ambiguous mappings return MIGRATION_REQUIRED; missing local copies fail even if the recorded old path or original source still exists. Old copies are never verified through those old locations. v2 external append preserves v2; copied append requires migration to a new v3 bundle.
Offline migration
Run from the installed candidate directory, using isolated copies for trial runs:
node scripts/migrate-bundle.mjs --root 'E:\evidence' --name 'old-bundle' --preflight
node scripts/migrate-bundle.mjs --root 'E:\evidence' --name 'old-bundle'
# Optional: --destination-root 'E:\new-evidence' --destination-name 'reviewed-v3'
The default creates a new sibling old-bundle-migrated-v3 and never overwrites an existing target. The original manifest, receipts and bodies stay intact. Preflight refuses damaged chains, binding errors, missing copies, ambiguous mappings and pending source transactions. Migration holds the source lock, checks copied bytes against the original recorded hashes, and records source metadata digests and verification limits in metadata.migration. Its fresh receipt chain begins with this migration; it does not inherit old receipt history. A v1 source keeps its UNVERIFIED_LEGACY origin visible even when the new package passes current consistency checks. A precommit failure can leave an empty target reservation; use a new name for a retry, or inspect that isolated reservation offline. Never treat this command as a repair for corrupt evidence.
🧩 DSH Power Suite
This plugin is part of the DSH Agent Power Suite — 4 modular, zero-hard-dependency plugins forming a complete closed-loop developer workflow:
flowchart LR
M["🧠 dsh-local-memory<br>(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy<br>(2. Save 80%+ tokens reading code)"]
E --> A["🛡️ dsh-evidence<br>(3. Local audit receipts)"]
A --> S["🔍 dsh-session-index<br>(4. CJK search & bookmarks)"]
S --> M
style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px
| Plugin | Role in Suite | Synergy with Evidence |
|---|
| 🛡️ dsh-evidence | Audit & Receipts (Current) | Records file hashes, local receipts and claims for review. |
| 🧠 dsh-local-memory | Memory Layer | Can associate remembered decisions with reviewed evidence bundles. |
| ⚡ dsh-context-economy | Context Economy | Can register benchmark output files as evidence snapshots. |
| 🔍 dsh-session-index | Session Search | Search past session archives to pinpoint historical evidence receipts and jump back. |
📖 Deep Dive & Reference
🛠️ Available Tools (5 Tools)
| Tool | Purpose |
|---|
evidence_create | Initialize evidence directory, evidence.json (v3), and receipt.jsonl chain. |
evidence_add | Add files/directories (SHA256, size, mtime) with optional claim, validUntil, and copy=true. |
evidence_verify | Check file hashes, receipt consistency and validity dates; return bounded problem paths and full counts. |
evidence_list | Page through local bundle directories, retaining invalid or busy entries with diagnostics. |
evidence_show | Inspect a page of manifest entries and a separate page of local receipt records. |
📁 Bundle Structure & Manifest Format
~/.dsh/evidence/<name>/
evidence.json # Manifest with top-level manifestHash self-integrity
receipt.jsonl # Logical hash-chain receipts; recoverable generation writes
files/ # v3 copies keyed by relative files/... paths
.transaction/ # Pending generation, removed after publication
⚖️ Honest Capability Declarations
- Can Check: Current file hashes against recorded hashes, manifest self-hash, receipt chain structure and manifest binding.
claim, description and receipt timestamps are local recorded assertions.
- Cannot Independently Prove: Command execution, content truth, author identity, deleted complete history suffixes, or resistance to rewriting the entire bundle. Someone able to replace all local files can recompute a self-consistent bundle. Local hashes are not digital signatures or a trusted external timestamp service.
🧪 Building & Testing
node scripts/build.mjs # Compile src ➡️ lib
npm run typecheck
npm test # Run test suite
npm run pack:check # Packaging check
