statement-reconciler

明細照合

目次

• 概要
• 入力規約
• 照合式
• ワークフロー
• 診断
• 出力規約
• ガードレール

概要

照合が取れない明細は、正しく解析されていない明細です。このスキルでは、パーサーのあらゆる失敗モードを一度に検出できる唯一のチェックを実施します。つまり、開始残高 + Σ（取引）= 終了残高です。照合に失敗した場合は、その原因（取引の欠落、符号の反転、行の二重計上、外貨換算による丸めなど）を診断し、記帳担当者が不正なデータを確定する前に修正またはエスカレーションできるようにします。

入力規約

呼び出し元は、パーサーの出力を渡します。

• account_id、period_start、period_end。
• opening_balance_cents、closing_balance_cents。
• transactions — {id, date, amount_cents, description_raw} の配列。
• tolerance_cents（既定値は 100 = $1.00）。
• account_type — 符号規則に影響します（以下を参照）。

照合式

現金口座およびクレジット口座の場合：

closing_balance_cents = opening_balance_cents + Σ transactions.amount_cents

符号規則：

口座の種類	出金（例：購入、支払い、引き出し）	入金（例：預け入れ、受取金）
checking / savings	負	正
credit_card（家計簿ビュー）	購入は負	カード支払いは正
credit_card（発行会社の残高ビュー）	正（残高が増加）	負（残高が減少）

このスキルでは、現金口座とクレジットカードについて、家計簿ビューを前提とします。出金は負、入金は正です。パーサーがクレジットカードに発行会社のビューを使用した場合は、照合する前に符号を反転してください。

証券口座／401k／HSAの保有明細には、このスキルは適用されません（これらは期間中の増減ではなく、ある時点の残高を示すものです）。スキップしてください。

ワークフロー

Reconciliation Progress:
- [ ] Step 1: Confirm account_type is in {checking, savings, credit_card, mortgage}
- [ ] Step 2: Sum signed amount_cents
- [ ] Step 3: Compute computed_closing = opening + sum
- [ ] Step 4: Compute diff = closing − computed_closing
- [ ] Step 5: If |diff| <= tolerance, return ok: true
- [ ] Step 6: Else, run diagnostics
- [ ] Step 7: Emit reconciliation report

ステップ1～5

簡単です。ほとんどの明細はステップ5ですぐに合格します。

ステップ6 — 診断

以下のチェックを順番に行い、差額の原因を説明できる最初のチェックを採用します。

診断A — 符号反転の疑い。 |diff| / 2 が、いずれか1件の取引金額の絶対値と$0.50以内で一致する場合、その取引の符号が抽出時に反転した可能性があります。次のように報告します：sign_flip_suspect: tx_id_X。

診断B — 取引の欠落。 |diff| が明細上の「Fees」または「Interest」の行の合計と一致し、それに一致する個別の取引が抽出されていない場合、パーサーがその行を取りこぼしています。次のように報告します：missing_transaction_suspect: <amount> <description>。

診断C — 取引の二重計上。 同じ (date, amount, description) の組み合わせが入力に2回出現し、|diff| がその金額と一致する場合は、片方を削除して再確認します。次のように報告します：double_counted: tx_id_X。

診断D — 手数料・請求の欠落。 diff が小さい（≤ $50）うえ、一般的な手数料と一致する場合は、見落とされた可能性がある「Service Charge」／「Monthly Fee」／「Foreign Transaction Fee」の行を探します。

診断E — 丸め誤差の累積。 N 件の取引に対して |diff| ≤ tolerance × N/100 の場合、行ごとの丸めが累積している可能性があります。整数セントを使っていればまれですが、外貨建ての行では起こり得ます。次のように報告します：rounding_drift_suspect。

診断F — 期間の不一致。 period_end が明細に印字された締め日と一致しない場合、誤った開始残高または終了残高が組み合わされています。次のように報告します：period_mismatch_suspect。

どの診断にも該当しない場合は、記帳担当者がエスカレーションできるよう、ok: false と diagnostic: "unknown" を返します。

ステップ7 — 許容差ポリシー

既定の許容差：$1.00（100 セント）。

発行会社がセント単位で照合するクレジットカード明細では、0 に引き締めます。明示的に求められた場合に限り $5 に緩め、その際は差額を正確に提示してユーザーが把握できるようにします。

出力規約

{
  "account_id": "acc_chk_001",
  "period_start": "2025-12-15",
  "period_end": "2026-01-14",
  "opening_balance_cents": 1124300,
  "closing_balance_cents": 1247500,
  "transactions_sum_cents": 123200,
  "computed_closing_cents": 1247500,
  "diff_cents": 0,
  "tolerance_cents": 100,
  "ok": true,
  "diagnostic": null,
  "suggestions": []
}

失敗例：

{
  "account_id": "acc_cc_001",
  "period_start": "2025-12-15",
  "period_end": "2026-01-14",
  "opening_balance_cents": 0,
  "closing_balance_cents": -284300,
  "transactions_sum_cents": -283100,
  "computed_closing_cents": -283100,
  "diff_cents": -1200,
  "tolerance_cents": 100,
  "ok": false,
  "diagnostic": "missing_transaction_suspect",
  "suggestions": [
    {
      "type": "missing_transaction",
      "expected_amount_cents": -1200,
      "hint": "statement summary lists 'Foreign Transaction Fee $12.00' but no transaction extracted with that amount",
      "action": "re-parse PDF page 3, look for fee line"
    }
  ]
}

ガードレール

• 許容範囲を黙って広げてはいけません。 差分が許容範囲を超えた場合、照合処理はチェックに失敗する必要があります。エスカレーションするか再解析するかは、ブックキーパーエージェントが判断します。
• 照合できていない明細をコミットしてはいけません。 照合に成功するまで、ブックキーパーエージェントはデータを保留する必要があります。照合に失敗した場合は、reports/alerts/ にエントリーを作成し、黙って破棄してはいけません。
• 証券口座／401k／HSA／税務書類は対象外です。 保有資産明細と税務書類には、単一の期末残高の整合性条件がありません。それぞれのエージェントが担当する、別の整合性チェックがあります。
• 冪等性。 同じ入力で照合処理を2回呼び出しても、同じ出力が生成されます。
• 差分の符号の意味。 diff_cents が負の場合、計算上の期末残高が報告値より高いことを意味します（つまり、明細に記載された額より多くの現金を説明する取引がある状態です）。通常は、入金の欠落か、出金の符号の誤りを示します。