管轄の来歴アテステーション
モデル、リージョン証拠、ログの管轄についての、リクエストごとの署名付き主張です。検証が確立するのは、記録された主張の完全性です。推論の物理的な位置を、独立に確立するものではありません。Ed25519 で署名されます。追記専用で、改ざんが明らかになる台帳です。
アーキテクチャ
Gateway:
┌─ RegionResolver ─→ header evidence / pinned endpoint → ISO-3166 region + evidence tier
├─ KeyStore ───────→ EnsureKeyPair(orgID) → Ed25519 keypair (AES-GCM encrypted)
├─ LedgerStore ────→ Append(attestation, signature, keyID)
└─ EventPublisher ─→ InferenceRegion, ModelOriginCountry, LogStorageRegion,
ProviderEntityJurisdiction, AttestationHash, Signature, KeyID
Loggerd:
└─ Consumer ───────→ Extracts lineage fields from Redis event → request_lineage table
Admin API:
GET /api/lineage/{request_id} → attestation JSON
POST /api/lineage/{request_id}/verify → {valid: bool}
GET /api/organizations/{id}/lineage → recent attestations
暗号
- アルゴリズム: Ed25519(標準ライブラリ
crypto/ed25519) - ハッシュ対象: 正規化アテステーション JSON の 16 進 SHA-256(構造体の
json.Marshal) - 鍵の保管: 秘密鍵は組織の暗号化鍵で AES-GCM 暗号化されます(
enc:プレフィックス) - 決定性: Go は構造体フィールドをソース順にマーシャリングします → ビルドをまたいでバイト同一です
証拠の階層(リージョンフィールドが実際に証明すること)
アテステーション内の inference_region は段階付けされています。アテステーションは、解決された階層(region_evidence)を持つため、レビュー担当者は主張の強さを推測する必要がありません。
| 階層 | 意味 | 例 |
|---|---|---|
endpoint_pinned | 宛先エンドポイント自体がリージョンを符号化します — ゲートウェイはリージョン固有のリソースへリクエストを送り、その事実を記録します | 自社運用の vLLM/llama.cpp、Azure OpenAI Japan East、Bedrock ap-northeast-1、GLOBAL 以外のリージョンで登録された任意のモデル |
header_observed | レスポンスヘッダーが位置シグナルを提供します。推論コンピュートではなく CDN エッジを指すことがあります | cf-ray のコロケーション接尾辞、x-served-by |
provider_attested | プロバイダが、信頼されたオプトインヘッダー x-yabanin-region を通じてリージョンを明示的に証明します | プロバイダのオプトイン連携 |
provider_declared | ベンダーはサービングリージョンを開示しません。値はプロバイダの登録済みデフォルトです | api.openai.com のようなグローバルエンドポイント |
正直な範囲: グローバルなベンダーエンドポイントについて、物理的な処理位置を開示するプロバイダはありません。アテステーションは、持っていない知識を示唆するのではなく provider_declared を記録します。レジデンシーパック(フェイルクローズド)を使うと、組織は provider_declared 階層のモデルを完全に禁じられます。これはリージョン固定の購入者にとって正しい姿勢です。
データベーススキーマ
| テーブル | 目的 |
|---|---|
request_lineage(ベースライン 0001_init) | 追記専用の台帳。改ざんが明らかです(トリガーが UPDATE/DELETE をブロックします) |
provider_jurisdictions(ベースライン 0001_init) | プロバイダ→国のマッピング。シードデータ付き |
org_lineage_keys(ベースライン 0001_init) | 組織ごとの Ed25519 鍵ペア。バージョン管理され、失効可能です |
設定
gateway:
lineage_enabled: true # PB1.6 — gate all lineage functionality
無効(false または未設定)のとき、ゲートウェイはリージョン解決と署名を完全にスキップします — レイテンシのオーバーヘッドはゼロです。
他機能との関係
来歴とレジデンシーは補完関係にあり、重複ではありません。
- 来歴は記録します。 リクエストのあと、検証可能な署名とともにリージ ョン証拠を記録します。
- レジデンシーは防ぎます。 データが誤った管轄へ行くことを防ぎます(事前に、方針の適用を通じて)。レジデンシー方針パック を参照してください。
来歴は次の導入コンポーネントと統合します。それらの存在だけでは、法的コンプライアンスは確立しません。
- マルチリージョンのアクティブ-アクティブ — Postgres の行レベルセキュリティにより、データはホームリージョンに固定されます。来歴はリクエストごとにリージョンを証明します。
- エアギャップ/オンプレミス — 同梱の KMS とライセンス/PKI を備えたシングルテナントの導入です。来歴の鍵は顧客環境の外へ出ません。
- ソブリンモデルレジストリ —
model_origin_countryは、記録されたモデルレジストリの主張として、署名付きアテステーションの一部です。 - 管理監査ログ — 変更は
admin_audit_logsへ、改ざんが明らかなハッシュチェーン行として書き込まれます(AF-10、2026-10-02 以降で結線されています。管理の書き込み経路は共有プロトコルauditlog.AppendInTx—pkg/adminstore.InsertAuditLogEntry— を通じて追記します。永続化された変更前/変更後/理由のスナップショットと明示的なhash_version、マイグレーション0019を持ちます。チェーンは、並行性と改ざん検知を含む統合テストにより、実 Postgres に対してエンドツーエン ドで検証されます)。JIT アクセスのパッケージ(pkg/jitaccess)はツリー内に存在しますが、管理の書き込み経路には結線されていません。出荷済みとして提示しないでください。正式な SOC 2/ISO 27001 のコントロールワークシートは内部草案であり、認証ではありません。
耐久性と損失ウィンドウ(設計判断)
ゲートウェイは各アテステーションを pkg/lineage.AsyncLedger を通じてコミットします。境界のあるインメモリキュー(容量 1024)を、単一のバックグラウンドワーカーがバッチで書き出してドレインします(pgx.Batch、100 ms ごと、または 100 行ごとにフラッシュ)。台帳は証拠(監査/コンプライアンス)であるため、設計契約はフォールバックによる無損失です。キューは決してドロップせず、バッチの失敗は同期的な単一行の追記へ劣化します。この節は、失敗の行列と、インメモリのウィンドウを境界づける(または取り除く)アウトボックスの判断を記録します。
書き込み経路(現状)
request ──sign──► AsyncLedger.Append
│ queue has room? ──yes──► chan (≤1024) ──► worker ──► AppendBatch
│ no └─batch err─► sync Append (per row)
└──no (queue full)────────────► sync Append (in caller)
graceful shutdown ──► Close(5s) ──► ctx.Done ──► drain queue ──► final flush
失敗の行列
| 失敗 | 挙動 | 損失ウィンドウ | 備考 |
|---|---|---|---|
| 正常停止(SIGTERM) | Close(5s) がワーカーの ctx をキャンセルします。ワーカーは終了前にキューをドレインし、最終フラッシュを行います | 約 0(5 秒のドレイン期限で境界されます) | 5 秒の予算は srv.Shutdown とドレインの両方をカバーします。シャ ットダウン時に DB が稼働していれば、キューされたものはすべて書き込まれます。 |
| 強制終了(SIGKILL/OOM/電源) | ドレインは走りません。インメモリキューは消えます | 最大 1024 件のアテステーション(キュー全体)+ インフライトのバッチは最大 1 つ | 唯一の真の損失ケースです。時間ではなくキュー容量で境界されます。 |
| DB 障害(Postgres 停止) | バッチフラッシュが失敗 → 各項目は同期的な Append へフォールバックし、DB が停止しているあいだはそれも失敗します | 損失 0、未記録 N — 項目は高速に失敗し、lineage append lost としてログされます。再キューされません | 「DB 停止中はベストエフォート」へ劣化します。リクエストは成功します(来歴はリクエストごとのベストエフォートです)。アテステーションは失われたものとしてログされます。DB が戻ると、新しい追記は再び成功します。 |
| キュー満杯(コンシューマがプロデューサより遅い) | Append はリクエスト経路での同期的な単一行書き込みへ落ちます | 0 | ドロップする代わりに、バックプレッシャー下でリクエストのレイテンシが増えます。台帳は証拠なので、決してドロップしません。 |
| バッチ書き込みエラー(DB は稼働、一時的) | 各項目を同期的に再試行します | 0(行ごとの再試行。それでも失敗した行は lineage append lost とログされます) | バッチの失敗を行 ごとの試行へ変換し、1 つの悪い行がバッチ全体を巻き込みません。 |
| ワーカーのクラッシュ/パニック | ワーカーのゴルーチンが終了します。以降の Append 呼び出しはキューが埋まるのを見て、同期書き込みへフォールバックします | 0(キューが埋まったあと) | Append の default 分岐が安全網です。生きたワーカーがいなくても、書き込みは DB へ直行します。 |
重要な性質: 損失ウィンドウは時間で境界されるのではなく、メモリで境界されます。最悪ケースは、深さ 1024 のキューが満杯のプロセスの強制終了です。DB 側のすべての失敗モードでは、台帳は同期的に書き込むか、アテステーションを大声で失敗させます(ログされます)。黙ってドロップすることは決してありません。
判断: アウトボックステーブル + コンシューマ(採用)対 同期的な追記
インメモリキューをトランザクショナルなアウトボックスへ置き換えることを評価しました。アテステーション行を、リクエストログと同じ Postgres トランザクションでアウトボックステーブルへ書き、その後コンシューマがアウトボックス行を request_lineage へ中継します。
| 基準 | インメモリの AsyncLedger(現状) | アウトボックステーブル + コンシューマ |
|---|---|---|
| 強制終了時の損失ウィンドウ | 最大 1024 件のアテステーション | 0(行はリクエストログと同じコミット済み txn にあります) |
| DB 障害時の挙動 | DB 停止中はアテステーションが失われます(ログされます) | 起こり得ません — DB が停止していればリクエストログの txn もコミットしないため、失うべきアウトボックス行がありません。一貫性は保たれます |
| リクエスト経路のレイテンシ | +0(非同期)。キュー満杯のバックプレッシャー下でのみ +1 ラウンドトリップ | リクエスト txn 内で +1 の INSERT(小さく、同じ接続) |
| 順序/少なくとも 1 回 | プロセス寿命につき高々 1 回(キューは揮発性) | 少なくとも 1 回(コンシューマは request_id で重複排除する必要があります)。冪等なコンシューマが必要です |
| 複雑さ | 低い(ゴルーチン 1 つ、チャネル 1 つ) | 高い(アウトボックススキーマ、コンシューマ、重複排除、バックログ監視、DLQ) |
| バックログの可視性 | キューの深さ(ログのみ) | 問い合わせ可能なテーブル(件数、最古の経過時間、組織ごと) |
採用: アウトボックステーブル + コンシューマ。 根拠: 来歴台帳はコンプライアンスの証拠であり、現在の設計がデータを失う唯一のモード — 満杯キューでの強制終了 — は、まさに監査が突くモードです。アウトボックスはそのウィンドウを完全に取り除き、「DB 停止」を問題でなくします(孤立した証拠がありません)。代償はトランザクション内の挿入 1 回と、重複排除を意識したコンシューマです。インメモリの AsyncLedger は、定常状態の有効な高速経路のままです。アウトボックスは耐久性のバックストップです。
アウトボックスでの損失ウィンドウ: 強制終了と DB 障害のどちらもゼロです。残るギャップは、コミットしたリクエストログのトランザクションのうち、アウトボックス→来歴の中継がまだ走っていないものだけです。それは損失ではなく遅延です(行はアウトボックス内で永続であり、中継されます。コンシューマは冪等です)。
状態(出荷済み): アウトボックスは実装されています(ベースライン 0001_init、pkg/lineage/outbox.go)。AsyncLedger.Append は今やアテステーションを lineage_outbox へ書き込みます — 戻った時点で永続です — そしてバックグラウンドの中継(RelayLoop)が保留行を request_lineage へ移します。中継はチェーンされた行の唯一のライターです(それと競合するバッチライターは、組織ごとのチェーンリンクをインターリーブし得ます)。request_id について冪等です(INSERT … ON CONFLICT DO NOTHING、その後 relayed_at を印付けます)。中継の仕事はパスごとに境界されます(LIMIT 500)。失敗した行は保留のまま再試行されます。不正な行は中継済みと印付けられ、パイプラインを詰 まらせるのではなく大声でログされます。DB 障害時の挙動: Append はエラーを返します(偽の成功はありません)。kill/再起動/DB 障害の testcontainers テストは Docker にゲートされています。
範囲外/前提(判断への入力)
- リクエストログとアウトボックス行は1 つの Postgres トランザクションを共有しなければなりません(同じ
*pgx.Tx)。コンシューマはアウトボックス →request_lineageを中継し、request_idについて冪等です(ユニークキー)。 request_lineageにはすでに改ざんが明らかになるトリガーがあります(UPDATE/DELETE はブロックされます)。アウトボックステーブルは別の可変なステージングテーブルであり、署名済み証拠チェーンの一部ではありません。中継されたrequest_lineage行だけがそうです。- フォローアップの作業項目がアウトボックススキーマ + コンシューマを実装し、ゲートウェイをトランザクション内書き込みへ切り替えます。この節は、それをゲートする判断を記録します。
改ざんの証拠: ハッシュチェーン + WORM エクスポート
このシステムには2 つの独立したハッシュチェーンがあります。混ぜないでください。
| チェーン | テーブル | 範囲 | 起源 | 状態 |
|---|---|---|---|---|
| リクエスト来歴 | request_lineage | 組織ごと、すべての推論リクエスト | ベースライン 0001_init | 出荷済み(チェーン + 検証 + エクスポート) |
| 管理監査ログ | admin_audit_logs | 運用者ごと、管理の変更 | ベースライン 0001_init。チェーンプロトコルは AF-10(0019_audit_snapshots_chain)以降で結線 | 出荷済み(管理の書き込み経路がチェーンを書き込みます。検証 — 統合テスト) |
これらは別々の追記専用台帳であり、スキーマもライターも検証も別です。この節はリクエスト来歴のチェーンだけを文書化します。admin_audit_logs テーブルは別の関心事(管理操作の証拠)であり、独自のチェーンプロトコルを持ちます — 上の注記を参照してください。
リクエスト来歴のチェーンの動き
各 request_lineage 行は追加の 2 列を持ちます(ベースライン 0001_init)。
record_hash—sha256(prev_hash || canonical_record)。行自身のリンクハッシュです。固定順で|区切りのcanonical_record文字列(INSERT の列に対するもの)が、ライターと検証器が共有する唯一の真実の源です。prev_hash— 前の行のrecord_hash(チェーンの先頭ではNULL)。
すべての行が前の行のハッシュを埋め込むため、組織の履歴の途中での編集、挿入、削除は、その後のすべてのリンクを壊します。ライター(pkg/lineage/ledger.go)は追記時に組織ごとのチェーン先頭を計算します。非同期台帳のライターは単一ゴルーチンなので、組織ごとのコミット順は安定しています。
チェーンが出荷される前に書かれたレガシー行は record_hash = '' です。検証器はそれらを数え、スキップします(チェーンの一部ではありません)。破損として扱いません。
検証
yb lineage verify --pg-uri <url> --org <org-id> は、組織の行をタイムスタンプ順に歩き、チェーンされた各行のハッシュを再計算し、prev_hash が前の record_hash と一致すること(先頭は NULL)を確認します。行数、チェーン済み/レガシーの分割、チェーンが無傷かどうか(壊れていれば問題の行)を報告します。壊れたチェーンでは非ゼロで終了するため、定期的なコンプライアンスチェックとして使えます。
WORM エクスポート
yb lineage export --pg-uri <url> --org <org-id> --out <file.jsonl> [--s3 <bucket> --region <r> --lock-compliance --lock-days <n>]
- 組織の行を JSONL として書き出します。行ごとに 1 オブジェクト、加えてファイルの
sha256チェックサムです。 --s3を付けるとアーカイブをアップロードし(--lock-compliance --lock-days Nも付けると)、N日間 COMPLIANCE モードの S3 Object Lock を設定します — ルートアカウントを含め、誰も保持期間中にエクスポートを変更または削除できません。これが「ライトワンス、リードメニー」(WORM)の証拠コピーです。運用のためにライブ DB を可変のままにしつつ、不変で独立に検証可能なスナップショットを保持できます。
エクスポートの検証
エクスポートされた JSONL ファイルは自己記述的です。各行の canonical_record と前の行の record_hash から record_hash を再計算し、ファイルの sha256 チェックサムが一致することを確認します。したがって準拠した WORM エクスポートは、ライブデータベースへの読み取りアクセスを必要としないオフラインの監査成果物を兼ねます。