fable-anti-churn

Fable Anti-Churn

用途

fable-anti-churn 是 get-fable 中用于防止重复工作和重复利用证据的权威引擎。它由原生 Rust 引擎（crates/fable-anti-churn）和本地 CLI 脚本共同驱动，使用加密方式为工作请求生成指纹（RFC 8785 JCS + SHA-256）、跟踪预留回执、复用完全相同且此前通过的证据、阻止重复操作、在重复出现确定性失败时停止，并以亚毫秒级执行速度验证晋级证明。

适用场景

• 执行重复的测试命令、构建脚本或静态分析工具之前。
• 启动子 Agent、后台工作流或调用外部工具之前。
• 操作或命令发生确定性失败，需要本地修复而不是盲目重试时。
• 评估候选晋级门槛（包完整性、测试通过、权限验证）时。
• 在所有生命周期钩子（SessionStart、PreToolUse、PostToolUse、PostToolUseFailure、Stop）中。

不适用场景

• 不要用于取消或终止整个用户任务——门控只针对特定的重复本地操作。
• 不要将其作为有效代码变更的替代方案；代码发生变更后，应计算带类型的失效信息（candidate_changed 等），再重新运行。
• 不要用它绕过真实的人类授权或安全边界。

输入

• action_event：规范 JSON 载荷，包含 action_kind、action_scope_digest、requirements_digest、candidate_digest 和环境哈希。
• prior_receipts：NDJSON 格式的历史回执账本（.fable/anti-churn/receipts.ndjson）。
• core_policy：策略配置，包含干预级别阈值和重试预算参数。

预期输出

• decision_receipt：经过加密签名的回执，包含 35 个规范字段、decision、reason_code 和 evidence_digest。
• evidence_acceptance：盖戳的证据接受记录，用经过验证的结果更新待处理的预留。
• churn_status：实时账本状态，报告回执总数、待处理预留、通过的证据和被阻止的重复工作循环。

流程

1. 为工作身份生成指纹： 使用 RFC 8785 规范 JSON 和 SHA-256 对范围、需求、候选补丁、依赖项、策略和评估器进行哈希。
2. 查询历史账本： 扫描 .fable/anti-churn/receipts.ndjson，查找匹配的现有预留或通过的证据。
3. 评估幂等性：
   • 如果存在完全匹配且没有失效记录的通过证据：发出 reuse_prior_evidence。
   • 如果存在正在处理的预留：发出 block_this_local_action（防止竞态条件）。
   • 如果存在确定性本地失败且工作区未发生变更：发出 local_fix_required。
   • 如果工作已变更且存在有效的带类型失效信息：发出 allow_reexecution。
   • 如果是首次执行等效操作：发出 allow 并记录预留回执。
4. 执行并记录结果：
   • 成功时：运行 accept，将预留状态转换为 pass。
   • 本地失败时：记录 local_failure 回执，以阻止立即重复执行。
5. 确保钩子不变量： 拦截生命周期事件，确保轮次完成时没有未接受的预留或重复工作循环残留。

决策规则

• ALLOW： 首次执行等效操作，且没有既有预留；预留槽位并生成待处理回执。
• ALLOW_REEXECUTION： 消耗有效且未使用的带类型失效信息后，允许重新运行。
• ALLOW_WITH_ADVISORY： 工作身份信息不完整时允许执行（同时发出速率提示）。
• REUSE_PRIOR_EVIDENCE： 完全匹配的工作已有通过证据；返回已存储的 evidence_digest，不产生任何额外 Token 开销。
• LOCAL_FIX_REQUIRED： 检测到确定性本地失败；必须先编辑代码，才可执行。
• BLOCK_THIS_LOCAL_ACTION： 存在重复的待处理操作、无效的扇出，或工作已变更但没有带类型的失效信息。

工具策略

• 优先使用只读查询进行检查和验证。
• 使用原生 Rust 引擎二进制文件（fable-anti-churn 或 get-fable-native anti-churn），实现亚毫秒级执行。
• 直接更新 NDJSON 状态文件时，使用原子文件系统锁（fs2）进行保护。
• 切勿删除或损坏历史回执；维护不可变的追加式账本。

证据要求

• 已验证的回执包含全部 35 个规范字段，且不含任何禁止字段。
• SHA-256 摘要符合 sha256:[0-9a-f]{64} 格式。
• 通过的自测语料报告确认 23/23 个场景验证成功。
• 将生命周期阶段标记为完成前，确认不存在待处理的预留项。

故障处理

• 遇到 local_fix_required 或 deterministic_local_failure 时：编辑目标源代码以修复缺陷。工作区变更会清除故障锁。
• 如果失效操作遭拒：检查目标回执，并确保原因代码与变更字段相符。
• 如果故障连续次数达到 2：先转交给 fable-recover 诊断根本原因，再尝试编辑代码。

完成标准

• 所有未关闭的预留项均已转为 pass 或明确的终止结果。
• .fable/anti-churn/receipts.ndjson 中未解决的待处理预留项为零。
• 状态账本通过 anti-churn verify 验证，且验证错误为零。
• 已通过的测试使用与当前变更代次相符的新证据完成验证。

CLI 命令

# Evaluate an action event against receipts ledger
bun ./bin/get-fable.js anti-churn decide event.json

# Accept passing evidence for an open reservation
bun ./bin/get-fable.js anti-churn accept <receipt-id> <evidence-digest> [pass|local_failure]

# Quick zero-latency check if an action/command is duplicate
bun ./bin/get-fable.js anti-churn check --action-kind targeted_test --target src/core.ts --command "bun test"

# Verify receipts ledger integrity
bun ./bin/get-fable.js anti-churn verify

# Run native 23-fixture self-test corpus
bun ./bin/get-fable.js anti-churn self-test

# Check anti-churn status & metrics
bun ./bin/get-fable.js anti-churn status

生命周期钩子强制执行

1. SessionStart：扫描 .fable/anti-churn/receipts.ndjson，查找未关闭的预留项或持续发生的本地故障循环。
2. PreToolUse (Bash / Agent)：计算操作键。如果存在重复操作且未进行失效处理，则拦截并阻止。
3. PostToolUse (Write / Edit)：计算新的候选哈希并清除本地故障锁。
4. PostToolUse (Bash Success)：使故障跟踪失效。
5. PostToolUseFailure (Bash Failure)：检测确定性本地故障循环，并阻止盲目重试。
6. Stop：结束本轮之前，确认不存在未结清的预留项或损坏的回执。

渐进式资源

• 决策与回执架构 — 全面的回执架构和 35 个规范字段说明。
• 威胁模型 — 安全边界、信任域和防篡改措施。
• 隐私政策 — 禁止字段和秘密信息脱敏机制。
• 评估协议 — 23 个场景的验证矩阵和基线断言。
• 原则审查 — 防止重复工作的数学和架构基础。
• Claude 集成 — Claude Code 的宿主生命周期钩子设置。
• Codex 集成 — OpenAI Codex 的宿主生命周期钩子设置。
• 事件模板 — 标准操作事件 JSON 模板。
• 回执模板 — 规范决策回执 JSON 模板。