dsh-negative-ledger

给编码 Agent 用的失败知识账本。它只记录已被证伪的路径——失败的命令、不存在的文件、被否定的方案、不可用的 API——连同每条结论背后的证据、以及何时可以重试。证据变化时，结论自动失效。

English

不是什么

• 不是 memory：不存正面知识、不做语义回忆。
• 不是 cache：存的是结论，不是工具结果。
• 不是 bug regression tracker：覆盖任意工具调用与文件读取，而非仅 bug 修复。

核心循环

1. 一次工具调用失败（非零退出码、FS_NOT_FOUND 等）→ 记录一条负结论：outcome 见证（退出码、错误码）+ precondition 见证（来自 DSH fs/observed 的文件状态）。
2. 下一次相同尝试按指纹命中（规范化命令 + cwd，或文件路径）。
3. 只要所有 precondition 见证未变，该尝试被提醒（warn 模式）或阻止（block 模式）。
4. 任一 precondition 变化 → 结论变 stale，提醒自动撤销、允许重试；重试成功 → resolved。

差异化：DSH 原生、证据约束的持久负面记忆门禁——失败结论随环境证据自动生效与吊销，并在并发代理之间保持事务一致。

快速开始

# 仅引擎 + CLI
node src/cli.ts --dir .ledger stats

# 三个可复现演示（S1 命令去重 / S2 缺失文件去重 / S3 证据失效），
# 自带验收断言与节省报告
node demos/run-demos.ts

要求 Node ^22.19.0 || >=24.0.0（与官方 DSH 的 engines 范围对齐）。

CLI

node src/cli.ts [--dir 
] [--backend sqlite|jsonl]  | stale | stats>

显式 --backend 优先；否则按目录自动识别（ledger.db → sqlite、ledger.jsonl → jsonl）；两者皆无时使用主后端 sqlite。

命令	输出
list	全部事实：status、kind、id、claim
show	单条事实的格式化 JSON
stale	因证据变化而失效的事实
stats	三个诚实指标：重复失败观察、警告发出、调用阻止

引擎 API

两个存储后端共用同一 LedgerStore seam：默认的事务性 SQLite 存储（SqliteLedgerStore：WAL、revision 乐观并发、操作收据、retry lease、JSONL 导入）与旧版单进程 JSONL 存储（JsonlLedgerStore）。

• / — 当前事实（含 revision 与活跃 lease 摘要）。