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

方針パイプライン (YPP)

Yabanin 方針パイプライン(YPP)は、ゲートウェイのトラフィック上で動く、プログラム可能な検査と変換のコンベアです。宣言的な YAML 方針、外部 HTTP スキャナ、LLM ジャッジ、コンテンツミューテータ、条件分岐を、ゲートウェイミドルウェアという一箇所で組み立てて実行します。デフォルトではオフです。YABANIN_POLICY_MODE が未設定のとき、パイプラインランタイムは構築されず、リクエスト処理はこの機能のない導入とビット単位で同一です。

方針は組織スコープのセキュリティオブジェクトです。適用が読むのは policystore だけです。リクエストごとの(SDK が供給する)方針設定はないため、クライアントが管理者の方針を回避することはできません。

1. アーキテクチャ​

pkg/pipeline pure core: payload/finding/result types, the Step
contract, YAML compilation, the execution engine.
No DB/HTTP/LLM/logging side effects.
pkg/pipeline/builtins 20 deterministic steps (15 detectors + 5 mutators).
pkg/pipeline/callout external HTTP detector/mutator steps (SSRF-guarded).
pkg/pipeline/llmjudge LLM-judge step through the gateway's own upstream pool.
pkg/pipeline/script `when` condition engines: expr (default), lua, starlark.
pkg/pipeline/streaming SSE primitives: prefix gate, chunk carry, final check.
pkg/policystore versioned policy storage + attachments (migration 0008).
gateway middleware the single integration point: compiles org policies per
version, runs attached pipelines on each hook (OP-8).

ゲートウェイは、プロセスごとに完全なステップレジストリを持つエンジンを 1 つ構築します。組み込みステップ、callout(外部送信の許可リストが設定されている場合のみ)、llm_judge、builtin/toolpolicy のツールガード、decide 判定ステップ、何もしない route_hint プレースホルダ、および 3 つの条件エンジン(expr、lua、starlark)すべてです。

2. 概念​

フックとペイロード種別​

方針は、実行するゲートウェイの面(hooks)を宣言します。フックが、ステップに渡されるペイロード種別を決めます。

フックペイロード種別発火
pre_upstreamrequestアップストリーム呼び出しの前
post_upstreamresponseアップストリーム応答の後
stream_prefixstream_prefixバッファしたストリーム接頭辞(§7 を参照)
stream_finalstream_finalストリーム全体の集約
tool_pretool_argsツール/MCP 呼び出しの前
tool_posttool_resultツール/MCP 呼び出しの後

ペイロードは、メッセージ一覧、生のボディ(stream_* ではチャンクテキスト)、読み取り専用のリクエストメタデータ(org、key、model、provider、ラベル、タグ)を運び、リクエストペイロードではアップストリームのリクエストヘッダも運びます。

アクションと合成​

すべての検出結果は、固定の厳格さの尺度 deny > mask > flag > allow 上のアクションを 1 つ持ちます。

  • deny — リクエスト / ツール呼び出し / ストリームをブロックします(実行を短絡します)。
  • mask — 続行しますが、変換後のペイロードだけを使います。
  • flag — 変更せずに続行し、観察を記録します。
  • allow — 対処するものはありません。

アタッチされた複数の方針がリクエストに一致すると、すべてが実行されます(アタッチメントの優先度順。組織 → キー → モデル)。検出結果は和集合になり、判定は観察されたうち最も厳しいものになり、最初の deny が残りの処理を短絡します(スキップされたステップもトレースに現れます)。バグのあるステップからの未知のアクションは deny として順位付けされます。フェイルクローズです。検出器は常に、方針の境界をまたいでも、最新の変換済みテキストを観察します。

すべての実行について、コンパイル済みの各ステップはちょうど 1 回トレースされます(ran、skipped、error、timeout。所要時間とエラー付き)。判定ログはこの完全性に依存します。

モードとキルスイッチ​

  • mode: enforce — 検出結果が判定を引き上げます。ミューテータはペイロードを書き換えます。
  • mode: shadow — 方針は決して変換せず、判定も決して引き上げません。検出結果は「何が起きていたか」の差分のために記録されます。これが推奨される展開経路です(shadow → 判定ログの確認 → enforce)。

プロセス全体のキルスイッチ YABANIN_POLICY_MODE(デフォルトは off):

値動作
offランタイムは構築されません。すべてのフックは何もしません(デフォルト)
shadowすべての方針がコンパイル時に shadow へ格下げされます
enforce方針は保存されたモードで実行されます

未知の値は警告付きで off に解決されます。ゲートウェイ自身が行うジャッジ呼び出しは内部マーカーを持ちます(§6.2)。ジャッジヘッダを提示する受信トラフィックは免除されず、拒否されます(§6.2)。

3. 方針 YAML(apiVersion ypp/v1)​

1 ドキュメントにつき方針は 1 つです。コードとして管理する場合、ファイル名は方針の name と等しくなければなりません(§8)。実際に動く例は deploy/policies/_example/pii-guard.yaml と deploy/policies/_pack/ のパックにあります。

apiVersion: ypp/v1
kind: Policy
name: pii-guard # required identity (metrics, decision log)
mode: shadow # shadow | enforce
hooks: [pre_upstream] # at least one, no duplicates
steps:
- id: scan # parallel group head: the detectors below
parallel: [pii, secrets] # run concurrently, join before the next step
- id: pii
detector: builtin/national-pii
- id: secrets
detector: builtin/secrets
- id: verdict
decide: |
deny if findings.any(f -> f.category matches 'secrets.*' and f.severity == 'high')
mask if findings.any(f -> f.action == 'mask')
flag otherwise

検証は厳格です。未知の YAML フィールドは読み込みエラーです。apiVersion は ypp/v1、kind は Policy でなければならず、name と mode は必須です。ステップ id は一意であり、すべてのステップは種別フィールドをちょうど 1 つ持ちます(detector | mutator | callout | llm_judge | decide | route_hint)。

ステップごとのオプション:

フィールド意味
when任意の条件ソース(§4)。方針の読み込み時に 1 回コンパイルされます
when_engine条件エンジンを固定します(expr/lua/starlark)。エンジンが複数登録されると必須です
timeoutステップごとの予算。Go の duration 構文(50ms、2s)。タイムアウトは on_error に従います
on_errorfail_closed(デフォルト。失敗は拒否して短絡します)| fail_open | fail_open+flag(合成された step_error の flag 検出結果を追加します)
parallelこのステップと同時に実行し、1 つの結合グループとする、この方針のステップ id。参加者はすべて検出器でなければなりません(グループは読み取り専用です。グループ内のミューテータはコンパイルエラーです)。入れ子はできません
paramsステップファクトリのパラメータ(§5)。種別で予約されたキー(url、model、prompt_ref、expr、target)は衝突するとコンパイルエラーになります

アタッチメント(方針の適用対象)は YAML ではなく方針とともに保存されます。git で宣言する照合ブロックは §8、管理 API は §9 を参照してください。

4. 条件(when)​

when ソースは実行時に、それまでの実行の読み取り専用コンテキストに対して評価されます。記録された検出結果、ステップトレース(所要時間/結果)、リクエストメタです。コンパイルは方針の読み込み時にステップごとに 1 回行われます。登録されたエンジンがない条件は読み込みエラーであり、黙ってスキップされることはありません。条件のエラーはステップの on_error モードに従います(デフォルトはフェイルクローズです)。

3 つのエンジンが同梱され、ゲートウェイによって登録されます。expr(最小限でループなし。想定されるデフォルト)、lua(命令予算付きでサンドボックス化された gopher-lua)、starlark です。エンジンは 1 つのインタフェースの背後で交換できます。言語を切り替えても YAML の方針モデルは変わりません。

decide ステップ種別は、エンジンに依存しない別の判定 DSL です(行ベースで、最初に一致したルールが採用されます)。

deny if findings.any(f -> f.category matches 'secrets.*' and f.severity == 'high')
mask if findings.any(f -> f.action == 'mask')
flag otherwise

フィールドは category、severity、action、step、span です。演算子は == と matches(末尾 * の前方一致)です。otherwise 行はフォールバックを設定します(デフォルトは allow)。decide ステップは判定を引き上げるだけであり、変換も検出結果の追加も行いません。

5. 組み込みステップ​

レジストリ名は凍結されています。方針は文字列でそれらを参照します。すべてのステップに共通する任意パラメータ:

  • kinds — 検査するペイロード種別を制限します(デフォルトは 6 種別すべて。JSON スキーマステップのデフォルトは出力種別であり、リクエスト専用ステップは request に固定します)。
  • action — ステップの検出結果が持つアクション。flag(デフォルト)、mask、または deny(allow は検出器のアクションではありません)。ファクトリ検証の失敗は方針の読み込みエラーです。

検出器​

ステップカテゴリパラメータ(共通以外)
builtin/national-piiinnsnils、pan、ru_passport、ogrn + BR/IN/MY/AE/ZA/NG/KE/EG の識別番号—(固定の RU + 9 法域セット。チェックサム/Luhn 検証)
builtin/secretssecret(+ 資格情報をキーとする JSON 値)—(プロバイダのキー形状、PEM ヘッダ、JWT の形状。証拠は引用されません — [REDACTED_SECRET])
builtin/injectioninjection—(RU + EN のプロンプトインジェクション語句)
builtin/word-countword_countmin、max(少なくとも 1 つの境界が必要。max が 0 なら無制限)
builtin/char-countchar_countmin、max(ルーンであり、バイトではありません)
builtin/sentence-countsentence_countmin、max(オフラインの終端ヒューリスティック)
builtin/containscontainswords(必須のリスト)、mode は any|all|none(デフォルトは any)、case_insensitive(デフォルトは true)
builtin/regexregexpattern(必須、RE2。入れ子の量指定子と展開爆弾は読み込みエラー)、invert、case_insensitive、max_input(デフォルト 1 MiB、上限 64 MiB。超過するとステップは失敗します)
builtin/json-schemajson_schemaschema(必須のインライン JSON Schema。読み込み時にコンパイル)
builtin/json-keysjson_keyskeys(必須のドット区切りパス)、mode は any|all|none(デフォルトは all)
builtin/url-checkurlschemes(デフォルトは ["https","http"])、allow_hosts、deny_hosts(*.suffix ワイルドカード)。完全にオフラインであり、取得は行いません
builtin/code-detectcode.<lang>languages(sql|python|typescript の部分集合。デフォルトはすべて)
builtin/languagelanguageallowed(ru|en|other の空でない必須の部分集合。文字体系優勢のヒューリスティック)
builtin/model-whitelistmodelmodels(必須の glob パターン。未知または空のモデルは違反)
builtin/metadata-requiredmetadatakeys(メタフィールド/ラベル)および/または labels(label=value の組)。少なくとも 1 つが必須

ミューテータ​

ステップ効果パラメータ
builtin/redact実行の検出結果にある機微な範囲(および/または自身のパターン)を [REDACTED:<category>:n] トークンに置き換えますcategories(正確な名前、または末尾の .*)、patterns({category, pattern} のリスト)、max_input
builtin/pseudonymize可逆の仮名化。範囲は安定した {{YPP_n}} エイリアスになります。置換は外向きのみであり、応答への逆置換はありませんcategories、patterns、carry は none(デフォルト)|session、max_input
builtin/header-rewriteアップストリームのリクエストヘッダを編集します(削除は設定より先に適用されます。CRLF/NUL インジェクションは読み込みエラーです)set(マップ)、remove(リスト)。リクエスト専用
builtin/model-rewriteリクエストのモデルを書き換えます(データ境界の継ぎ目。PII を含むリクエストをリージョン内のモデルへ経路します)。すべての書き換えは model_rewrite の flag 検出結果として記録されますto(必須)、from(任意の事前条件)。リクエスト専用
builtin/partials-substitute{{partials.NAME}} トークンを置換します(1 回限り。再スキャンしません)on_missing は skip(デフォルト)|error。ソースストアはサーバ側で接続されます(プロンプトスタジオ、§6.1)

carry: session を指定した builtin/pseudonymize は、セッションキャリアを通じてエイリアスマップを永続化し、同じ原文がターンをまたいで同じエイリアスに対応するようにします。キャリアは、アップストリームまたはクライアントへ送出する前に取り除かれます。

ゲートウェイはさらに 2 つのステップ種別を登録します。builtin/toolpolicy(ツール方針 のツール呼び出しガードレールをパイプラインステップにしたもの)と、decide / route_hint の継ぎ目ステップ(§4)です。route_hint は現在、何もしないプレースホルダです。経路の意味論は後の決定事項です。

6. 外部ステップ​

6.1 Callout(HTTP 検出器/ミューテータ)​

callout: ステップは、ペイロードの射影を外部スキャナへ POST し、応答を検出結果へ対応付けます(モード detect)。または、変換後の内容を適用して戻します(モード mutate)。

- id: presidio
callout: http://presidio.internal:3000/analyze
params:
mode: detect # detect | mutate
expose: messages # messages (default) | body | fields:a,b,c
response: findings # findings (default) | boolean (JSON true/false)
finding_category: presidio # default category for boolean mode
max_response_bytes: 65536
timeout: 250ms
on_error: fail_open+flag

射影(expose)は、ゲートウェイの外に出るものを制限します。messages はメッセージ内容を送ります(detect では \n で結合し、mutate ではメッセージごとに配列要素 1 つです)。body は生のボディを送ります(文書化されたリスクです。同じデータ領域に契約上拘束されたスキャナに対してのみ有効にしてください)。fields:a,b は、JSON オブジェクトボディのそれらのトップレベルフィールドのみを送ります。組織/キー/モデルのメタデータは外に出ません。

応答契約。 detect/findings は {"findings":[{"category","severity","action","span","evidence"}]} を期待します。category は必須であり、未知のアクションは deny として順位付けされます。detect/boolean は JSON の true/false を期待します。mutate は、射影と正確に一致する {"content": ...} で応答しなければなりません。メッセージ数が同じであること、ボディ文字列であること、またはキー集合が射影されたフィールド集合と等しいオブジェクトであることです。スキャナの判定(有効な 2xx)はエラーではありません。ネットワーク障害、非 2xx、契約違反、ブレーカによる拒否は、on_error に従うステップエラーです。

外部送信のセキュリティ(交渉の余地はありません)。 ステップが構築されるのは、運用者が YABANIN_POLICY_CALLOUT_ALLOW_HOSTS(カンマ区切りの正確なドメイン、または *.suffix)を設定したときだけです。すべての URL は、方針のコンパイル時にそのリストと照合されます。ダイヤル時に、SSRF ガードが DNS の応答を固定し、予約済みアドレス(ループバック、RFC1918、リンクローカル/クラウドメタデータ)をすべて拒否して、DNS リバインディングの窓を閉じます。リダイレクトはなく、再試行もなく、URL ごとのサーキットブレーカ、同時の同一呼び出しに対する singleflight による重複排除、ステップごとのタイムアウトがあります。許可リストがないと、callout 方針は読み込み時に失敗します。外部送信が運用者のリストより広くなることはありません。

6.2 LLM ジャッジ​

llm_judge ステップは、会話の 1 ターンを、ゲートウェイ自身のアップストリーム機構を通じてジャッジモデルへ送ります(クライアントトラフィックが使うのと同じ、SSRF ガード付きプールです。ソブリンおよびオンプレミスの分類器は第一級の対象です)。そして判定を検出結果へ対応付けます。

- id: judge_tox
llm_judge:
model: "$(sovereign-classifier)" # required; literal or $(registry indirection)
prompt_ref: "judges/toxicity@2" # required; versioned prompt resource
params:
mode: input # input (last user turn, default) | output (last assistant turn)
threshold: 0.8 # confidence >= threshold → deny; below → flag (default 0.8)
categories: [toxicity]
timeout: 2s
on_error: fail_open+flag

プロンプト参照は、バージョン付きの PromptSource を通じて解決されます。埋め込みファイル(judges/<name>/<version>.md、例: judges/toxicity@1、@2)がデフォルトであり、プロンプトスタジオが組織レベルのソースを供給します。判定を決定的にするため、temperature は 0 に固定されます。ジャッジの検出結果は名前空間 judge.<category> に入り、検出器のカテゴリと衝突することはありません。不正な形式の判定はステップエラーです(on_error が適用されます)。省略された確信度は 1.0 として数えます(フェイルクローズ)。

再帰の除外(厳格な契約)。 ゲートウェイ自身が行うすべてのジャッジ呼び出しは、ペイロードメタに judge=true を持ち、回線上では X-Yabanin-Judge: true ヘッダを持ちます。内部ペイロードマーカーはその合成呼び出しをパイプラインから免除するため、同じゲートウェイが提供するジャッジモデルが再入することはありません。回線ヘッダだけでは何も許可されません。X-Yabanin-Judge を提示する受信リクエストは、値が true、false、任意、空、または繰り返しのいずれであっても信頼されず、認証と経路解決のあと、いかなるアップストリーム呼び出しよりも前に、共有の pre-upstream 境界で 400 judge_reentry_unsupported により拒否されます。enforce モードでのコールドな方針ストア障害は、この拒否に対して既存の 503 の優先順位を保ちます。送信アダプタは、マークのないジャッジ呼び出しの送信を拒否します。

7. ストリーミングの意味論​

ストリーミング方針は、SSE の経路で接頭辞ゲート、チャンクキャリー、最終チェックを使います。

  1. ストリームのデフォルト。 方針ランタイムが適用モードで有効であり、方針が stream_prefix にアタッチされている場合、kinds のない builtin/redact または builtin/pseudonymize はデフォルトで stream_prefix を含みます。同じ kinds なしのデフォルトは、そのフックがアタッチされているとき stream_final を含みます。明示的な kinds リストはステップの範囲を狭めます。これは §5 で述べた共通のデフォルトと同じです。stream_final は発行後の完了したストリームを検査し、すでに送られたバイトを防ぐことも取り消すこともできません。
  2. 接頭辞ゲートとチャンクキャリー。 stream_prefix 方針がアタッチされている場合、ゲートウェイは捕捉した接頭辞スナップショットを 1 つ評価します。デフォルトは、最初の空でないデルタから 64 近似トークン、または 500 ms のうち、先に発火した方です。prefix_tokens または prefix_delay_ms で上書きできます。より短いバッファ済みストリームは、ストリーム終端でフラッシュされます。そのスナップショット内で見つかった完全な値は、解放前に変換できます。チャンクキャリーは、その値について学習した置換を後続の出現へ適用します。チャンクをまたいで分割された出現も含みます。スナップショットにない新しい値、またはパススルー開始後に初めて見えた値は発見しません。そのため、そのような値が発見されること、または隠されることは保証されません。変換された SSE コンテンツフレームは、イベントのフレーミングを保ったまま再エンコードされます。[DONE] と、コンテンツデルタのないフレームは、変更されずに通過します。ストリームのキャッシュが有効な場合、変換はキャッシュ記録ライタの前に実行されるため、クライアントとキャッシュは同じ変換済みバイトを観察します。
  3. 接頭辞の deny。 接頭辞スナップショットからの deny は、保留中のバイトが解放される前に中断します。ゲートウェイは正規のエラーフレームと data: [DONE] を送ります。
  4. 出力が変わらない場合。 方針ランタイムが適用モードで有効であること、方針が意図した組織、モデル、エンドポイント、および stream_prefix フックにアタッチされていること、明示的な kinds リストが stream_prefix を除外していないことを確認してください。完全な合成対象が、フラッシュ前に捕捉された接頭辞へ到着することを確認してください。アタッチメントまたは kinds を修正するか、接頭辞パラメータを調整してから、ローカルの合成ストリームで検証してください。より大きな接頭辞ウィンドウは最初のバイトを遅らせることがあり、それでもパススルー開始後に初めて現れる値の発見は保証できません。
  5. 最終チェック。 配信済みフレームは合成の chat.completion ドキュメントへ蓄積され、stream_final 方針が発行後にそれを検査します。最終の deny は送ったバイトを取り消せません。判定ログとメトリクスに記録される、flag 付きの結果へ格下げされます。

8. コードとしての設定(git → policystore)​

Git は方針宣言の唯一の信頼できる情報源です。完全なワークフローは deploy/policies/README.md を参照してください。短い版は次のとおりです。

  • 宣言は deploy/policies/<org-slug>/<policy-name>.yaml にあります。ドキュメント 1 は方針です(そのまま保存されます)。--- のあとの任意のドキュメント 2 は照合ブロックです(enabled、attachments)。
  • yb policies reconcile は差分を計画します(デフォルトはドライラン)。--apply はデータベースを git へ収束させます。--prune(危険)は、宣言の対象外である DB 上の方針も削除します。CI はドライランを実行するため、壊れた宣言はビルドを失敗させます。
  • ドリフトは報告され、黙ってマージされることはありません。 git を介さない DB 編集は、計画上 DRIFT となり、apply 時に新しいバージョンで上書きされます(バージョンは不変なので、何も破棄されません)。管理 API の GET /api/organizations/{id}/policies/drift は、リポジトリのチェックアウトなしで、方針ごとの状態 managed / drift / unmanaged を報告します。
  • deploy/policies/_pack/sovereign-default.yaml パック(国内 PII + シークレット + インジェクション、shadow モード、組織全体のアタッチメント)は OFF で出荷されます。--include-pack の場合にのみ照合され、その場合でも無効のまま着地します。

適用されたすべての変更は、現在の git SHA をそのバージョンの git_sha として記録するため、判定ログとメトリクスは正確な宣言リビジョンへ紐づきます。

照合の無効化は、CLI とゲートウェイが同じ Postgres 方針ストアと Redis 方針バージョンストアを使うことに依存します。--apply では、方針を変更した組織ごとの apply が成功したあと、CLI はその組織の Redis 方針バージョンキーを更新しようとします。各ゲートウェイはリクエスト時にそのキーを照会し、次のリクエストで、変更された読み取り可能なバージョンを取り込みます。バックグラウンドのプッシュはありません。ドライラン、変更のない apply、失敗した組織ごとの apply は、バージョンを上げません。Redis でバージョンを上げることに失敗すると警告として報告され、データベース書き込みはロールバックされません。組織ごとの apply は複数のストア操作からなるため、後の操作が、先の書き込みがコミットされたあとで失敗することがあります。コマンドはその組織の失敗を報告し、そのキーのバージョンは上げません。原因を修正し、照合を再実行して収束させてください。

既知のキャッシュ済みバージョンと異なる読み取り可能なバージョンは、次のリクエストでストア再読み込みの試行を引き起こします。欠落した Redis キーはバージョン 0 として読まれるため、キャッシュ済みバージョンが既知かつ非ゼロのときにその試行を引き起こします。30 秒のハードキャッシュ年齢の境界が適用されるのは、バージョン照会が利用できない場合、その読み取り可能な値がキャッシュ済みバージョンと等しい場合(キャッシュ済みバージョンも 0 であるときに 0 として読まれる欠落キーを含む)、または成功したストア読み込みがバージョンを捕捉しなかった場合です。これらの照会はキャッシュ年齢を更新しません。年齢は最後に成功した方針ストア読み込みから測られます。境界以降、次のリクエストはストア再読み込みを試みます。失敗したストア読み込みは、最後に既知の良好なスナップショットとその元の年齢を保持します。後のリクエストが再試行し、成功した読み込みが保存された方針を取り込みます。再読み込みはリクエスト駆動であり、方針ストアの可用性は依然として重要です。

9. Policystore と管理 API​

policystore(マイグレーション 0008)は方針を不変にバージョン管理し、組織ごとのアタッチメント(key_label、model_pattern、endpoint、priority。優先度が小さいほど先に実行されます。デフォルトは 100)を保持します。管理面は、組織権限 policies.manage によってゲートされます。

GET /api/organizations/{id}/policies list
POST /api/organizations/{id}/policies create (yaml + attachments)
GET /api/organizations/{id}/policies/drift git-drift status per policy
GET /api/organizations/{id}/policies/{policyId} detail: policy + versions + attachments
PUT /api/organizations/{id}/policies/{policyId} update yaml / enable / active_version / attachments
DELETE /api/organizations/{id}/policies/{policyId} delete (cascades versions + attachments)

管理プレーンは YAML 構文のみを検証します(kind/apiVersion/steps の存在)。完全なコンパイルはゲートウェイがバージョンを読み込むときに行われるため、未知の検出器名を含むドキュメントは問題なく保存され、判定ログで目に見えて失敗します。成功した管理 API による方針の変更は、組織の方針バージョンキーの更新を試みます。ゲートウェイインスタンスはリクエスト時にそのキーを照会し、読み取り可能なバージョンが既知のキャッシュ済みバージョンと異なる場合、次のリクエストでストア再読み込みを試みます。欠落したキーはバージョン 0 として読まれるため、キャッシュ済みバージョンが既知かつ非ゼロのとき、欠落キーはその試行を引き起こします。バージョン照会が利用できない場合、その読み取り可能な値がキャッシュ済みバージョンと等しい場合(キャッシュ済みバージョンが 0 のときの欠落を 0 として扱う場合を含む)、または成功したストア読み込みがバージョンを捕捉しなかった場合、キャッシュ済みエントリは、最後に成功した方針ストア読み込みから 30 秒以降の最初のリクエストで、再読み込みの再検討対象になります。失敗したストア再読み込みは最後に既知の良好なエントリを保持し、後のリクエストで再試行します。これはリクエスト駆動のフォールバックであり、即時のプッシュでも、ストアが利用できないあいだの新しいデータの保証でもありません。

原子的な有効化とロールバック​

前提条件: 組織の方針は、上記の管理 API または yb policies reconcile(§8)で管理されており、拒否の動作のためにゲートウェイのキルスイッチは enforce です(shadow は観察するだけです)。有効化はポインタの移動であり、内容の編集ではありません。active_version を伴う PUT /api/organizations/{id}/policies/{policyId} は、パイプラインを、不変に保存された 1 つのバージョンへ向けます。ロールバックは、より古いバージョン番号を指定した同じ呼び出しです。成功した変更は、組織の方針バージョンキーを上げます。

正常系: 有効化のあと、各ゲートウェイインスタンスは次のリクエストで変更されたキーに気づき、組織の方針セットを再読み込みし、コンパイル済みのコピーを 1 ステップで入れ替えます。再読み込みは、1 つの repeatable-read データベーストランザクションからパイプライン、有効バージョン、アタッチメントを読むため、新しいセットが異なる時刻に書かれた行を混ぜることはありません。

制限と、典型的な障害からの回復:

  • 1 リクエスト、1 スナップショット。 リクエストは、そのストリーミングと再試行の継続を含めて、入口で読み込んだスナップショットを再利用し、有効化の前後に読み込まれた方針を混ぜることはありません。再読み込みはリクエスト駆動です。トラフィックを処理しないインスタンスは再読み込みしません。
  • オールオアナッシングのコンパイル。 再読み込みは、組織の候補セット全体をコンパイルします。無効な有効バージョンが 1 つでもあると(宙ぶらりんのバージョン参照、解析できない YAML、未知のステップ)、候補全体が拒否されます。以前のスナップショットが提供を続け、部分的なセットがインストールされることはありません。
  • 再読み込み中の有効化(バージョンの競合)。 ゲートウェイは、ストア読み取りの前後でバージョンキーを読みます。そのあいだの変更は、読み込みを 1 回再試行します。さらに変更があるとリフレッシュは失敗し、以前のスナップショットが提供を続け、後のリクエストが再試行します。したがってリクエストが見るのは、古い完全なセットか新しい完全なセットのどちらかであり、中間のセットではありません。ただし切り替えの瞬間はゲートウェイインスタンス間で調整されないため、異なるインスタンスが、それぞれ最大 1 リクエストのあいだ、異なる完全なセットを提供できます。
  • コールドな組織における新しいバージョンの不成功。 以前の良好なスナップショットが存在しない場合、無効な有効バージョンは、コールド障害の設定にかかわらず、enforce モードで 503 policy_configuration_unavailable を返します。利用できない方針ストアは、YABANIN_POLICY_COLD_FAILURE_MODE が fail-open でない限り、503 policy_temporarily_unavailable を返します。shadow モードでは、どちらの状態も記録されカウントされ、トラフィックは方針の評価なしで続きます。すでに良好なスナップショットを提供している組織は、それを提供し続けます。読み込みの失敗が、使用できるエントリを退避させることはありません。
  • 回復。 宣言を修正して再適用するか、より古い不変バージョンを有効化してロールバックします。ゲートウェイは後続のリクエストで収束します。収束はバージョンを上げることに依存します。上げることに失敗した場合は、代わりに §8/§9 の 30 秒キャッシュ境界が適用されます。

読み込みの失敗は、失敗クラス(store_read、invalid_config、context_canceled、runtime_unavailable)付きの policy load failed 警告と、メトリクス gateway_policy_load_failures_total(モード × キャッシュ状態: cold = 以前のスナップショットなし、stale = 以前のスナップショットが提供を継続)として見えます。

判定ログ​

すべての実行の判定は判定ログに入ります(マイグレーション 0009、90 日の保持)。ステップごとのトレース、判定、方針 id + バージョン、コンテンツハッシュです。検出結果の証拠はハッシュ化して保存されます。引用されたユーザコンテンツが、shadow/debug の保持の外に残ることはありません。利用分析イベントは policy フィールドを運びます。実行順の判定レコードからなる JSON 配列です(方針の id/名前/バージョン、モード、判定、カテゴリ/深刻度/アクションの検出結果、所要時間)。欠落または空は、パイプラインがリクエストを評価しなかったことを意味します。

GET /api/organizations/{id}/policy-decisions?page=&page_size=&verdict=&mode=&policy_id=

メトリクス​

系列ラベル
gateway_policy_load_failures_totalmode、cache_state(cold = 以前のスナップショットなし、stale = 以前のスナップショットが提供を継続)
gateway_policy_runs_totalpolicy、endpoint、outcome(allow/flag/mask/deny)
gateway_policy_denies_totalpolicy、endpoint
gateway_policy_masks_totalpolicy、endpoint
gateway_policy_shadow_flags_totalpolicy、endpoint(shadow 実行が記録した検出結果)
gateway_policy_duration_mspolicy、endpoint

加えて pipeline_llmjudge_duration_seconds{model,outcome}、pipeline_llmjudge_verdicts_total{model,outcome}、および pipeline_callout_* ファミリがあります。ペイロードの内容、カテゴリ、深刻度がラベル値になることはありません。

10. 環境変数リファレンス​

変数デフォルト意味
YABANIN_POLICY_MODEoffキルスイッチ: off / shadow / enforce(§2)。
YABANIN_POLICY_COLD_FAILURE_MODEfail-closedストアが利用できないあいだのコールドな組織(成功した方針スナップショットがない組織): fail-closed は 503 で拒否し、fail-open は方針評価なしで続行します。無効な方針設定は enforce モードで常に拒否します(§9)。
YABANIN_POLICY_CALLOUT_ALLOW_HOSTS空callout ステップがダイヤルしてよい、カンマ区切りのホストパターン。空だと callout ステップは完全に無効になります。

ストリーミング接頭辞のデフォルト(64 トークン / 500 ms)は、stream_prefix アタッチメント上の方針パラメータであり、環境変数のつまみではありません。