Pacioli — the ERPNext broker you can hand the books

ERPNext の最小権限ガバナンスと、その上に構築された、ガバナンスの効いたエージェントの窓口です。MCP と A2A の両方を、1 つの基盤で支えます。窓口は受け入れるだけで、決して判断しません。

1494 年、ヴェネツィアでルカ・パチョーリは『スンマ・デ・アリトメティカ』を印刷しました。その中に、複式簿記を世界に広めた論考を収めました。商人が計算できなかったからではなく、信頼できなかったからこそ、彼はこれを書き記しました。彼の規則は一文で言い表せます。借方には必ず貸方が伴う。 すべての取引には、同額で反対側に記録される対応項目があり、帳簿が合わなければ、その場で誤りが明らかになります。500 年にわたる「証明できなければ、起きなかったのと同じ」という考え方です。

このリポジトリは、その論考を新しい書記のために書き直したものです。商人の問題は変わっていません。書記が変わったのです。パチョーリは、すべての書記を見張れない商人のために帳簿を合わせました。この仕組みは、すべてのエージェントを見張れない所有者のために帳簿を合わせます。5 世紀を隔てても、問題は同じ。解決策も同じです。

続きを読む前に、まずご覧ください：デモ。 pip install pacioli pacioli-guard を実行するだけで、何もない環境から、判断を下す基盤と、ひそかに書き換えられることのない封印済みの受領記録を確認できます。すべての判定には、実際に提供されるコードが使われています。演出は一切ありません。

## 異説 I — 2つの仕組みについて

この仕組みには2つの構成要素があり、組み合わせて使いますが、1つに統合するものではありません。 1つ目は、エージェントが関与しているかどうかにかかわらず、サイト上のあらゆる api-key 認証情報を保護します。2つ目は、エージェントが利用できる、統制された唯一の入り口です。1つ目はその入り口を支える土台であり、2つ目はその上に立ち、1つ目に従います。以下では、論考の形式に沿って、それぞれの仕組みが何であり、何を拒否し、どのようにインストールするかを説明します。

土台が対象とする範囲を、明確に説明します。土台が自らの役割を誇張すれば、それは土台ではないからです。 2つの問いに対し、frappe 独自の公開フックをそれぞれ1つずつ、問いの内容が明確になる層で使います。

どの認証情報が使われており、それで何を呼び出せるのか。 認証情報ゲートは auth_hooks に組み込まれており、api-key 認証情報が認証される際に実行されます。すべての REST マウントにおける token／Basic api-key リクエストを統制しますが、OAuth2 Bearer トークン、desk／cookie セッション、バックグラウンドジョブ、スケジューラー、サーバースクリプト、bench コンソールは統制しません。「この認証情報は何か」という問いが成立するのは認証時のみです。そのため、このゲートを配置できるのはここだけであり、この境界はその性質上避けられません。

この行為には同意があったのか。 これはドキュメントの性質に関する問いであるため、ドキュメント上で強制します。before_submit と before_cancel に対する doc_events に加え、guard 0.13.0 以降は before_gl_preview と before_sl_preview も使います。後者の2つは、記帳そのものではなく、記帳のリハーサルをゲートします。ERPNext は台帳をプレビューする際、記帳を実行してからトランザクションをロールバックするため、submit のプレビューには submit と同じマーカーが必要ですが、そのマーカーは消費されません。ORM 経由で台帳に記帳するすべての経路を対象とします。REST、run_doc_method、frappe.client.submit、送信済みの本文を指定した frappe.client.insert、desk の Save／Submit エンドポイント、一括 submit、docstatus フィールドへの直接書き込み後の保存、バックグラウンドジョブ、サーバースクリプト、bench コンソールです。同意の適用範囲は、認証情報ゲートのトランスポート境界を引き継ぎません。

両方を回避できる経路も、後から気付くことのないよう、最初に明記します。

1. ドキュメントのライフサイクルを完全に迂回する書き込み：生の SQL と、db_update／db_set のようなフィールド書き込みです。ERPNext のコアは、再記帳時にこれを自ら使用します。
2. 許可の読み取りを妨害できるアクター。同意ハンドラーはサイト上のすべてのドキュメントで実行されるため、許可の読み取りで例外が発生した場合は、例外を投げずに処理を返します。ワイルドカードハンドラーがクラッシュすれば、サイト全体が巻き込まれるためです。これは意図的なトレードオフであり、実際に残るリスクです。
3. Document.discard。 ホワイトリストに登録されているため呼び出し可能であり、before_cancel ではなく before_discard を発火させながら、db_set で docstatus = 2 に設定します。ドラフト以外は拒否するため、これによって台帳への記帳が取り消されることは決してなく、何も記帳されません。問題となるのは、帳簿が動くことではなく、ドラフトが処理対象から外されることです。これをゲートするには、「キャンセル」に組み込むのではなく、独自の行為タイプが必要です。記帳済みの項目を取り消す同意と、ドラフトを放棄する同意は、異なる権限だからです。丸めた表現で済ませず、ここに明記します。

frappe の拡張ポイントに、すべてを網羅できるものはありません。したがって、ここでのカバレッジは、全体を網羅できるという主張ではなく、残る範囲を明示した組み合わせです。プラットフォームが誰かに与えられるものではないためです。

### The Guard — 出納帳への扉

帳簿に記入できるのは任命された担当者だけであり、その担当者に割り当てられた帳簿に限られます。

Frappe/ERPNext の bench アプリです（PyPI での配布名は pacioli-guard、pacioli_guard bench アプリとしてインストールされます）。あらゆる API 認証情報（インテグレーション、Zapier/n8n のフロー、スクリプト、ベンダートークン、cron ジョブ、AI エージェントなど）を、メソッドの許可リスト（許可された場合は DocType も含む）に紐付け、Frappe の公開 auth_hooks 拡張ポイントを通じて、デフォルト拒否で認証情報レイヤーに適用します。コアをフォークする必要はありません。このサイト上のすべての API キー認証情報を、エージェントかどうかを問わず制御します。適用範囲とその限界については上記の適用範囲に関する注記を、同意を伴う独立したドキュメントレイヤーのゲートについては後述をご覧ください。

# from your bench directory: wheel into the bench env, then install the app
env/bin/pip install pacioli-guard
bench --site <your-site> install-app pacioli_guard

The Broker — 帳簿を預ける

事務員は提案できますが、処分を決めるのは商人だけです。

単独で利用できる pip インストール可能なブローカー（pip install pacioli）です。AI エージェントが ERPNext を統制された方法で操作できるようにします。入口は MCP または A2A から選べ、どちらも同じ基盤を利用します。51 個の統制対象 DocType、265 個のツールで、ERPNext 企業の送信可能なトランザクションをすべてカバーします。すべての書き込みは PLAN → CONSENT → execute → PROVE を経由し、それ以外はデフォルトで拒否されます。入口は通しますが、判断するのは基盤です。

pip install pacioli

各ツールの連携

Guard は基盤であり、ブローカーはその上で動作する利用者の 1 つです。 Guard はサイト上のあらゆる認証情報を制限し、強制適用します。エージェントを運用していなくても必要になることがあります。ブローカーはエージェント向けのフロントドアであり、その ERPNext 認証情報自体も、実行する呼び出し（統制対象の DocType と submit/cancel のベクトル。デプロイキットが適用するデータリストとして同梱）だけに限定して pacioli_guard でスコープ設定する必要があります。このスコープ設定がなければ、ブローカーの生の認証情報を持つ者は誰でも、ERPNext の REST API を直接呼び出し、PLAN、CONSENT、PROVE を完全に回避できます。そのため、ブローカーの README では、このスコープ設定を任意のセキュリティ強化ではなく、必須の前提条件として明記しています。

さらに、スコープ設定だけでは不十分です。これは 2026-07-25 に稼働中の bench で検証済みであり、推測に委ねず明確に述べる価値があります。 ブローカーは請求書を送信できなければなりません。請求書の送信こそがブローカーの目的だからです。したがって、その認証情報には請求書の送信が許可されています。そして、その認証情報を使った run_doc_method の直接呼び出しにより、計画もマーカーもレシートもないまま請求書が送信されました。台帳が更新されたのです。Guard は設計どおりに動作し、許可リストも正確でした。この問題は、呼び出し自体がブローカーの存在理由であるため、どのような許可リストでも防げません。キーを持つことが、記帳する権限を意味していました。

Guard はブローカー内ではなく基盤でこれを防ぎます。API Key Scope.require_consent（オプトインで、デフォルトではオフ）は、対象のドキュメントとその操作の両方に対して発行された、有効かつ一度限りの Pacioli Consent Marker を伴わない限り、docstatus を変更する操作を拒否し、使用時にマーカーを消費します。送信への同意は取消への同意ではありません。取消は同じドキュメントを変更し、反対の GL エントリを書き込むため、送信マーカーを取消に使うことはできません。また、マーカーは、それが認可する認証情報とは別のプリンシパルが書き込む必要があります。基盤は発行者と呼び出し元を照合し、一致する場合は拒否します。自身の同意を発行できる認証情報は、自らの許可証を書く門番にほかならないためです。minted_by は認証済みセッションに基づいてサーバーが設定し、呼び出し元が指定した値は上書きされます。そのため、この分離は自己申告ではなく、確実に担保されます。

このゲートが適用されるのはリクエストではなくドキュメントです。doc_events の before_submit／before_cancel に加え、guard 0.13.0 以降では before_gl_preview／before_sl_preview にも適用されます。これは意図的な設計であり、1 つの入口を制御することと、操作そのものを制御することの違いです。OAuth トークン、desk セッション、バックグラウンドジョブ、サーバースクリプト、bench コンソールなどを使い、API キーの REST 経路を完全に避けた認証情報の保有者にも、このゲートは適用されます。 これを満たすことと、これを通過することは別物であり、その違いは、実際に気づくまで説明せずにおくのではなく、明示する価値があります。マーカーは HTTP ヘッダーで提示されるため、HTTP リクエストがない経路では提示する方法がありません。したがって、同意ゲートが適用されたプリンシパルがバックグラウンドジョブやベンチコンソールを介して操作する場合、そこでは常に拒否されます。これはフェイルクローズであり、意図された動作ですが、上の段落を「これらの経路は同じように動作する」と読まないでください。これらの経路は停止されるという意味で対象に含まれていますが、利用できるという意味ではありません。

オプトインであることには、明確に述べる価値のある帰結があります。アプリをインストールしただけでは何も変わりません。対象となる認証情報に対して誰かが require_consent を有効にするまで、インストールしたアプリは上記のバイパスにさらされたままです。

これは結合ではなく、組み合わせです。Guard はそれ単体でも有用であり、エージェント専用ではありません。2 つの部分はそれぞれ異なる範囲に及びます。この違いを率直に示すことが重要です。認証情報スコープは、あらゆる api-key 認証情報（エージェントかどうかを問いません）に適用され、それ以外には何も検知しません。一方、同意ゲートはドキュメント層で動作し、デスクセッション、バックグラウンドジョブ、スケジューラー、サーバースクリプト、ベンチコンソールなど、ORM を経由するすべての経路を、ゲートを適用した認証情報についてカバーします。ブローカーは、その上に乗り、ほかのすべてに適用するのと同じ基準を守ることを選んだ、唯一のコンポーネントです。

## 第II区分 — 備忘録、仕訳帳、総勘定元帳について

ここで複式記入は比喩ではありません。設計そのものです。 『Summa』 （Particularis de Computis et Scripturis）の簿記論では、商人の真実を三つの帳簿に整理しています。そして、その一つ一つがこのシステムに対応しています。彼の仕訳帳では、各記入の借方には per、貸方には a と記されていました。片側だけで動くものはありません。彼が引いた帳簿の見開きを読み解いてみましょう。

folio	per — 彼の帳簿（1494年）	a — ここでの対応
¹	備忘録（memoriale） — すべての取引を、正式な記入を行う前に、まず大まかに書き留める帳簿	PLAN — plan_submit / plan_cancel が備忘録を記録します。予測される GL とリスクフラグを日付付きで、ドラフトに紐づけて記録します。転記は行いません。
²	仕訳帳（giornale） — 各記入を書式に沿って書き直し、借方には per、貸方には a を記す帳簿	PROVE — ハッシュチェーン方式の受領記録簿です。意図の受領記録が per、結果が a です。結果のない意図は、貸方のない借方であり、試算表で孤立項目として表面化します。
³	総勘定元帳（quaderno） — それ自体が勘定帳です	ERPNext の GL — ブローカーが直接記入することはありません。すべての記入は、仕訳帳の規律を通じて元帳に届きます。

そして、同じ原則がすべての柱に適用されます。あらゆるアクションには、それを記録した対応物があります。

folio	アクション（per）	記録された対応物（a）
⁴	エージェントが書き込みを行おうとする	PLAN — アクションの前に、予測される GL への影響を記録します。対応する記入は、実際の記入に先立ちます。
⁵	プランが存在する	CONSENT — 人間が、帯域外でマーカーを発行します。提案するのはエージェント、決定するのは人間です。すべての転記には、必ず二者が関与します。
⁶	書き込みが実行される	PROVE — 実行前に intent の受領記録、実行後に outcome の受領記録を残します。結果の受領記録が欠けた書き込みは孤立項目となり、試算表の不均衡とまったく同じように表面化します。
⁷	転記が確定する	UNDO — ERPNext 自体のキャンセル／修正も複式記入です。反対仕訳では、同額かつ反対方向の行が転記されます。何も消去されず、すべてに応答があります。
⁸	認証情報が存在する	Guard — 明示的な許可行がなければ、機能を付与しません。デフォルト拒否とは、「承認なしに記入しない」という原則を認証情報レイヤーで適用することです。

すべてのレイヤーで同じ原則が適用されます。対応するものなしに動くものはありません。 同意のないプランは転記されません。受領記録のない書き込みにはフラグが立ちます。許可のない認証情報は拒否されます。信頼できないのは、アクションが単独で実行されるシステムだけです。計画も、同意も、受領記録もないまま実行されるシステムです。パチョーリが拒むものは、まさにそれです。単独の記入です。

## Distinctio III — 計数所の扉について

彼の教えを、認証情報のレイヤーに適用します。

• すべての記帳に二つの手を。 書記が記入し、商人が承認します。同意マーカーはエージェントの手の届かない場所で生成されます（pacioli mint）。一方の権限だけで記帳することはできません。
• 計数所の扉。 任命された担当者以外は帳簿に記入できず、その担当者も任命された帳簿にしか記入できません。これが Guard による、認証情報ごと・文書タイプごとのデフォルト拒否です。
• 登録された帳簿。 帳簿の権限は、帳簿係自身の手の外に保持された印に由来します。pacioli anchor は、受領帳のハッシュ値をマシンの外に保持します。帳簿自身では書き換えられない登録情報なので、切り詰められたり差し替えられたりした帳簿は、それをもって露見します。

Distinctio IV — 帳簿の締めについて

❧ 借方と貸方が一致するまで、眠りについてはなりません。

彼は商人たちにこの規則を説きました。ここでも、それが運用上の規則です。pacioli verify は、まさに就寝前の確認です。試算表を実行し、意図と結果が一致しなければ、帳簿そのものがそれを知らせます。

締め切られた帳簿。 台帳を締めるのは彼自身の操作です。帳簿に線を引き、残高を繰り越します。ブローカーは締め切られた帳簿（会計期間の終了、期間締め伝票の境界、帳簿の凍結日）への記入を拒否し、締め切りをすり抜けて過去日付や未来日付の記入を行うことはありません。

Distinctio V — 棚卸しについて

調査を済ませるまでは、帳簿を開いてはなりません。 彼は商人に、最初の記帳に先立って完全な棚卸しをさせます。何を保有しているか、何を負っているか、何が不足しているかを確認します。pacioli doctor は、この計数所におけるその調査です。何にアクセスできるか、何が許可されているか、何が拒否され、その理由は何かを確認します。医師が ready と告げるまでは先へ進みません。その後の各期間でも、国勢調査（pacioli close）が棚卸しの正確さを保ちます。明細、照合、応答によってすべての発見事項を説明し、そうでなければ帳簿がそれを明示します。

ステータス

（現行バージョンは各パッケージの pyproject.toml／CHANGELOG.md に記載されています。この README では意図的に再掲していません。）

Guard — deny-unknown の姿勢による、デフォルト拒否の認証情報スコープ設定です（認識されない汎用 RPC は、許可されていても拒否されます。利用可能な範囲は、文書タイプごとの許可設定と、厳選された4つの安全なメソッドのみです）。実際の Frappe v16 ベンチで実証済みです（ゲート1、7、10）。

Broker — 管理対象の文書タイプ51種類、ツール265個。実際の ERPNext v16 ベンチで、Guard のスコープが適用されたシートとしてエンドツーエンドで実証済みなのは、51種類中48種類です（ゲート2～10、エンベロープ E1～E8、および2026-07の実証テスト一式）。勘定科目、在庫、資産、製造、外注にわたる管理対象の提出・取消・改訂、Workflow-SoD の同意、従属グラフを伴う連鎖取消（実際の環境で、1つの同意による3ノードの資産グラフを実証）、管理対象の支払照合（ERPNext 自体より厳格です。ERPNext が照合時に省略するクローズドブックス制御を、PHASE X で実環境にて実証）、有効化された予算のコントロールプレーン検証（有効化 → ベンチが PO を拒否 → 無効化 → 同じ PO が通過。各段階を同意前に開示）、マシン外のアンカー、最小権限を証明した参照用シート、そして基礎となる拒否事項（借方に貸方を対応させずに記帳することを実環境で拒否）。全体の経緯は SCOPED-TOKEN-PROOF.md に段階ごとに記録されています（PHASES A–X）。提供内容と非提供内容の詳細は、broker/README.md を参照してください。

ライセンス

Apache-2.0。