メインコンテンツまでスキップ

管轄の来歴アテステーション

モデル、リージョン証拠、ログの管轄についての、リクエストごとの署名付き主張です。検証が確立するのは、記録された主張の完全性です。推論の物理的な位置を、独立に確立するものではありません。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 エクスポートは、ライブデータベースへの読み取りアクセスを必要としないオフラインの監査成果物を兼ねます。