verified-rec

verified-rec

AI エージェントの作業を記録する、ハッシュチェーン付き監査台帳です。 誰でも検証して再生できる追記専用の記録です。エージェントは、本当に申告どおりの作業をしたのでしょうか？

MCP サーバーです。npm 依存関係はゼロです。記録は、所有者自身が管理するプレーンテキストファイルに保存されます。

You:   "ship the release."
Agent: *does the work, records each step into the ledger*
You:   "verify the ledger."
Agent: "chain intact — 14 entries, head 9f3c…, nothing edited."

ツール

ツール	機能
ledger_start	新しい台帳（.vrec）を開始します。ジェネシスエントリとチェーンヘッドを作成します。既存のファイルは上書きしません。
ledger_append	1つのステップを追加します。新しいチェーンヘッドを返します。チェーンが破損している場合は書き込みを拒否します。
ledger_verify	すべてのハッシュを再計算し、すべてのリンクを確認します。誰かがファイルを編集していた場合、最初に破損した行を返します。
ledger_replay	エントリを順番に一覧表示します（範囲の指定も可能です）。
game_verify_rec	決定論的カーネルを使ってゲームの .rec 録画を再生し、チェーンヘッドを計算します。由来を参照してください。

インストール

どの MCP ホストでも、1行でインストールできます。

// ~/.codebuddy/.mcp.json  (WorkBuddy / CodeBuddy)   — user scope
// ~/Library/Application Support/Claude/claude_desktop_config.json  (Claude Desktop)
{
  "mcpServers": {
    "verified-rec": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "verified-rec"]
    }
  }
}

ローカルチェックアウトでも同じように動作します（"command": "node", "args": ["/path/to/verified-rec/src/server.js"]）。 Node ≥ 18。ビルド手順もネイティブモジュールもネットワークも不要です。

使い方

インストール後は、エージェントに話しかけるだけです。ツール名は自然な言葉なので、エージェントが認識して使います。

• 「今日のリリース作業用の台帳を開いてください。」 → ledger_start がジェネシスエントリを含む release.vrec を作成し、最初のチェーンヘッドを返します。
• 「今行った作業を記録してください。」（エージェントの作業中に）→ ledger_append が1つのステップ（action、任意の actor / note）を追加し、新しいヘッドを返します。
• 「台帳を検証してください。」 → ledger_verify がチェーンを再計算し、ok、エントリ数、ヘッドを報告します。編集があった場合は、最初に破損した行番号を報告します。
• 「台帳を見せてください。」 → ledger_replay がエントリを順番に一覧表示します。

ゲームの録画を検証する場合（由来を参照）：

• 「この録画を確認してください：/path/to/play.rec、ヘッドは 9f3c…」 → game_verify_rec が再生し、次の3通りのいずれかを返します。reproduced（登録済みのカーネルがヘッドを再計算できる。真正です）、not-reproduced（どのカーネルも再計算できない。改ざんされているか、未登録のゲームバージョンによる録画です）、premise-broken（録画の事実が、どのカーネルにも一致しません）。期待するヘッドを指定しない場合は、録画が再生可能であることを証明し、ヘッドを報告します。

ヒント：重要な ledger_append を行ったら、チェーンヘッドを公開しましょう（コミットメッセージ、リリースノート、チャットなど）。それによって、「自分は編集していない」が「誰も編集していない」になります。公開したヘッドがチェーンを遡って固定するからです。

検証の仕組み

各エントリはハッシュによって直前のエントリにリンクします。

entry.hash = sha256([seq, ts, actor, action, note, prev].canonical)
entry.prev = previous entry.hash          (genesis prev = 64 zeros)

ledger_verify はチェーン全体を再計算します。1行のフィールドを1つ編集したり、2行を入れ替えたり、1行を削除したりすると、最初に破損した行の番号が報告されます。

脅威モデルについて、正直に説明します： 不注意による編集や軽率な改ざんを検出できます。チェーン全体とそのヘッドを書き換える攻撃者は検出できません。対策は、会計における最も古い手法です。ヘッドを公開することです。コミットしたり、ツイートしたり、リリースノートに記載したりしてください。そうすれば、後からの編集は、どこであっても公開済みのヘッドとの不一致として検出できます。

起源

この台帳は、あるゲームから抽出したものです — 《它在维护一场对话》(It Is Maintaining a Conversation)。 誰かのために記憶を保ち、それを失っていく心を描いた、無料の物語ゲームです。ゲーム内のすべての状態はハッシュチェーンでつながれており、各プレイの記録は .rec ファイルとして保存し、バイト単位で再生できます。このツールが一般化しているのは、その背後にある設計規律（「判断はハッシュ化し、文章はハッシュ化しない。同じ入力なら同じチェーンヘッドになる」）です。

その系譜を一歩さかのぼると、このゲームは dbx-sql-guardから発展しました。SQL 用のハッシュチェーンガードです。同じ発想が、データベースガード、ゲーム、作業台帳という3つの形になっています。

game_verify_recを使うと、その物語を実際に実行して検証できます。.recの記録を、同じ決定論的な物語カーネル（バージョン管理されたコンパイル済みアーティファクト。LICENSE-content.mdとPROVENANCE.mdを参照）で再生し、チェーンヘッドを報告します。これはゲーム独自のハッシュチェーンのヘッドで、各フレームについて head = H(prev ‖ frame ‖ canonical state) となります。expectedHeadを指定すると、次の3つの結果を返す整合性チェックになります。reproduced（登録済みのいずれかのカーネルバージョンでヘッドを再計算できる — 正規の記録）、not-reproduced（どの登録済みカーネルでも再計算できない — 改ざんされているか、未登録のゲームバージョンの記録）、premise-broken（記録の事実ダイジェストが、どのカーネルとも一致しない）。カーネルのアップグレードでは、新しい登録済みバージョンを追加します。古い記録は引き続き古いカーネルで検証されるため、アップグレードによって正当な記録が偽造扱いになることはありません。

カーネルはコンパイル済みアーティファクトであり、監査ツールとして疑念を持つのは当然です。PROVENANCE.mdで、その疑問に答えています。各カーネルバージョンにはソースの wasm と SHA-256 が含まれ、固定された wasm2js コマンド（./gen-kernel.sh）を使ってバイト単位で再現できます。また、ゲームで公開登録されているゴールデンチェーンヘッドにもひも付いています。作者を信頼する必要はなく、数分で自分で検証できます。

ファイル

• *.vrec — 台帳ファイル。改行区切りの JSON です。プレーンテキストのため、差分確認や grep ができます。
• .rec — ゲームの記録（crossgame-slice-recordingの行形式。seed=、facts=、variants=に続いて、各フレームに f=<frame> <tokens> が入ります）。ゲーム内のエクスポートパネルから生成されます。

ライセンス

コード：Apache-2.0。kernel/にコンパイルされる物語コンテンツ（sim-<ver>.wasm / kernel-asm-<ver>.js）：All Rights Reserved（LICENSE-content.mdを参照）。2つの部分については両ファイルで説明しています。エンジンはエンジニアリング、物語は創作です。

---

中文

给 AI Agent 工作用的哈希链账本。 追加式记录，任何人都能校验和重放—— Agent 说它做过的事，链上做没做过，一验便知。

MCP server，零 npm 依赖，账本是你自己机器上的纯文本文件。

工具	作用
ledger_start	开一本新账（.vrec），创世环 + 链头。已存在则拒绝（账不覆盖旧账）
ledger_append	记一环，返回新链头。链断了先修账才准记
ledger_verify	全量重算哈希、环环相扣。谁改过文件，报第一个断链行号
ledger_replay	按序重放（可切片）
game_verify_rec	用版本化确定性内核重放游戏 .rec，算出链头并给三态判定（见下）

安装：上面那段 JSON 照抄进 MCP 配置（WorkBuddy/CodeBuddy 是 ~/.codebuddy/.mcp.json），一行 npx -y verified-rec。Node ≥ 18， 无构建、无原生模块、不碰网络。

使用：装完直接跟 Agent 说话就行，工具会被自动挑中：

• "开一本账记今天的发版工作" → ledger_start 建 .vrec，创世环 + 首个链头
• "把刚才做的事记上"（干活途中随时）→ ledger_append 记一环，返回新链头
• "验一下这本账" → ledger_verify 全量重算：完好报 ok + 条数 + 链头， 被改过就报第一个断链行号
• "把账读一遍" → ledger_replay 按序列出

验游戏录像（见出处段）：

• "验这份录像 /path/to/play.rec，链头 9f3c…" → game_verify_rec 三态回答： reproduced（某登记内核复现链头 ⇒ 真实）/ not-reproduced（都复现不出 ⇒ 篡改或未登记版本）/ premise-broken（facts 对不上任何内核）。不给链头 则只证明可重放并报出链头。

用法要点：重要操作 ledger_append 之后，把链头登记出去（提交信息 / 发布记录 / 聊天里贴一下）——这一步才把"我没改过"升级成"谁都没法改"。

防篡改的诚实边界：抓得住手改和误改；抓不住「重算整条链并伪造链头」的 攻击者。解法是会计行最古老的一招——把链头登记出去（git 提交 / 公开贴文）， 事后改账就与公开链头对不上。

内核的出生证明：kernel/ 里的编译产物不是黑箱——每个版本带源 wasm 与 SHA-256，可用 PROVENANCE.md 里钉死的 wasm2js 命令 （./gen-kernel.sh）逐字节重建，并用游戏公开登记的黄金链头锚定内容。 game_verify_rec 的三态判定：reproduced（某登记版本内核复现链头 ⇒ 真实）/ not-reproduced（所有登记版本都算不出 ⇒ 篡改或录自未登记版本）/ premise-broken（facts 对不上任何内核）。内核升级是追加新版本，老录像 永远用老内核验，升级不会冤枉诚实的录像。

出处：这套账本是从游戏里提出来的。《它在维护一场对话》 ——一个关于记忆衰减的免费叙事游戏，它把每一帧状态都串成哈希链，每一局都能 录成 .rec 逐帧重放。本工具就是那套纪律的通用化。谱系再往前一步：游戏本身 演化自 dbx-sql-guard—— 同一个本能的三种形态：数据库守卫、游戏、工作账本。