> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# 既知の仕様の曖昧さ

> コンプライアンステストに影響する未解決の AdCP 仕様ギャップ — 回避策と issue リンク付き。基底の issue がクローズされるとエントリは削除される。

このページは、現在ストーリーボード適合性に影響する仕様ギャップを列挙します。各エントリは 3 つのパターンの 1 つをカバーします: ベクターが 1 つの結果をアサートする仕様の `MAY` ブランチ、スキーマがまだ要求しないがストーリーボードがアサートするレスポンスフィールド、またはベクターがリファレンス SDK を通じてプローブするのを妨げるテストインフラの癖。

**エントリは、タグ付けされた `@adcp/sdk` または仕様リリースで修正が出荷されるまで持続します** — GitHub issue のクローズは削除トリガーではありません。なぜなら、修正に先行する SDK バージョンの実装者は依然として症状に遭遇するからです。各エントリの回避策は、関連するときリリースゲートを名指しします。ここのエントリがあなたが見ているものと一致しない場合、最新の状態について GitHub issue を確認してください — 修正がまだ引いていないリリースに着地したかもしれません。

## このページの使い方

ストーリーボードが仕様準拠と信じる動作で失敗する場合、ストーリーボード名またはアサーションテキストをこのページで検索してください。各エントリは、ギャップ、ブロッカーを越えさせる回避策、修正を追跡する issue を記述します。エントリは、issue がクローズされたときではなくタグ付けされたリリースで修正が出荷されたときに削除されます — 権威ある状態については、このページをリンクされた issue と SDK / 仕様リリースノートとペアにしてください。

反対方向 — このリストに **ない** クリーンな修正のある失敗 — については、[ストーリーボードトラブルシューティングガイド](/docs/building/operating/storyboard-troubleshooting) を参照。

## 現在の曖昧さ

### `check_governance` `conditions` フィールド形状

* **スキーマ**: `check-governance-response.json` は `conditions[]` アイテムを `{ field, required_value?, reason }` と定義し、`field` と `reason` を必須とします。`status: conditions` ステータスは今や `minItems: 1` の `conditions` を要求します。
* **解決**: [#2603](https://github.com/adcontextprotocol/adcp/issues/2603)。スキーマ厳格化は、このエントリの削除に続くプロトコルパッチリリースに着地します。
* **回避策（修正を引くまで）**: すべての `status: conditions` レスポンスで正準の `{ field, reason }` 形状の `conditions[]` を発します。散文の説明に従うエージェントは既にこれをします。スキーマ厳格化は強制を機械的にするだけです。

### 非 OAuth エージェントに必要な PRM

* **ストーリーボード**: `universal/security.yaml` フェーズ `oauth_discovery` + `mechanism_required`。
* **ギャップ**: RFC 9728 / RFC 8414 プローブがデフォルトですべてのエージェントに対して実行されます。API キーのみのサンドボックスは、プローブを「通過」するために偽の発行者 URL を立てていて、それはスキップするより悪いです。
* **解決**: [#2606](https://github.com/adcontextprotocol/adcp/issues/2606) と [#5042](https://github.com/adcontextprotocol/adcp/issues/5042) — ストーリーボードの物語は今や、静的認証情報のみのエージェントに、テストキットで `auth.api_key` または `auth.basic` を宣言し PRM を完全に省略するよう明示的に指示します。任意フェーズのセマンティクスが `oauth_discovery` 失敗を致命的でなくします。`mechanism_required` は一致する静的認証情報パス経由で通過します。
* **回避策**: エージェントに OAuth 発行者がない場合、`/.well-known/oauth-protected-resource/...` を提供しないでください。テストキットのプローブ認証情報を有効として受け入れるようエージェントを設定します。Bearer エージェントについては、デフォルトテストキット（`acme-outdoor`）が `demo-acme-outdoor-v1` でプローブし、エージェントは本番鍵と並んでその値を受け入れなければなりません。Basic エージェントについては、`auth.basic.username`/`auth.basic.password` または `auth.basic.credentials` を持つテストキットを提供します。これは `test_kit.auth.api_key` または `test_kit.auth.basic` のいずれかを満たし一致する静的認証情報フェーズを実行させます。それなしではフェーズがスキップされ `assert_mechanism` が `actual: []` で失敗します。具体的な修正については [ストーリーボードトラブルシューティングガイド — 静的認証情報エージェント: assert\_mechanism](/docs/building/operating/storyboard-troubleshooting#static-credential-agent-no-auth-mechanism-contributed-assert_mechanism) を参照。

### SDK 経由の冪等性 missing-key プローブ

* **ストーリーボード**: `universal/idempotency.yaml` ステップ `missing_key/create_media_buy_missing_key`。
* **ギャップ**: リファレンス `@adcp/sdk` SDK が変更タスクで `idempotency_key` を自動注入するため、「missing key rejection」をプローブしようとするベクターが missing key でエージェントに決して到達しません — ランナーがディスパッチ前に 1 つを注入します。
* **解決**: [#2607](https://github.com/adcontextprotocol/adcp/issues/2607) — ステップが `omit_idempotency_key: true` を宣言し、ランナーに自身の `applyIdempotencyInvariant` と SDK の自動注入の両方をスキップするようシグナルします。リクエストが鍵なしでエージェントに到着し、ベクターが拒否パスを正直にプローブできます。
* **回避策**: 必要なものなし — 既存の仕様要件を尊重する（変更タスクで欠けている `idempotency_key` を `INVALID_REQUEST` または `VALIDATION_ERROR` で拒否）。

### ストーリーボードがアサートするレスポンススキーマフィールド

* **ストーリーボード**: `sales_catalog_driven`（カタログ数）、`creative_ad_server`（pricing\_options）、`media_buy_seller/inventory_list_targeting`（property\_list エコー）、`creative_ad_server`（vendor\_cost 必須）。
* **ギャップ**: ストーリーボードベクターがアサートするものとレスポンススキーマが要求するものの間の歴史的ドリフト。
* **解決**: [#2604](https://github.com/adcontextprotocol/adcp/issues/2604)。監査完了:
  * `sync-catalogs-response.json` は今や `action` が `created`/`updated`/`unchanged` のときカタログエントリに `item_count` を要求。
  * `property_list` / `collection_list` エコー: `packages[].targeting_overlay` 経由で既に正準。
  * `list-creatives-response.json` `pricing_options`: 既に正準（配列、`minItems: 1`、アイテムは `pricing_option_id` を要求）。
  * `report-usage-request.json` `vendor_cost`: 既に必須。
* **回避策**: すべての非失敗/非削除のカタログエントリに `item_count` を発します。準拠エージェントは既にこれをします。スキーマ厳格化が `response_schema` 検証でギャップを捕まえます。

### ブランドプロトコルの権利保持者対広告主 `brand_id`

* **ストーリーボード**: `specialisms/brand-rights/index.yaml` フェーズ `identity_discovery` + `rights_search`。
* **ギャップ**: `get_brand_identity.brand_id` は広告主（例: `acme_outdoor`）を識別します。`get_rights.brand_id` は検索を特定の権利保持者ブランド（例: `daan_janssen` のようなタレント）にスコープします。同じフィールド名、異なるエンティティ — #2627 修正の前はストーリーボードが広告主 id を権利保持者フィルターに通し、準拠エージェントは空の権利を返す（失敗）か「一致なしのとき全返し」フォールバック（バグをマスク）を追加しました。
* **解決**: [#2627](https://github.com/adcontextprotocol/adcp/issues/2627) — ストーリーボードは今や `buyer_brand`（互換性フィルタリング用の広告主）を送り、エージェントが完全なカタログを返すよう権利保持者 `brand_id` フィルターを省略します。
* **回避策**: `get_rights.brand_id` を権利保持者フィルターとしてのみ扱います。バイヤーの `brand.json` に対する互換性フィルタリングのため `buyer_brand` を投入します。

### 再キャンセルエラーコード — `NOT_CANCELLABLE` 対 `INVALID_STATE`

* **ストーリーボード**: `protocols/media-buy/state-machine.yaml > recancel_buy` と `scenarios/invalid_transitions.yaml > double_cancel/second_cancel`。
* **ギャップ**: `specification.mdx` §128（MAY `NOT_CANCELLABLE`）と §129（terminal-state 更新で MUST `INVALID_STATE`）の両方が `canceled` バイの再キャンセルに適用されました。state-machine-first の実装は §129 に従い `INVALID_STATE` を返し、cancellation-first の実装は `NOT_CANCELLABLE` を返しました。ベクターは歴史的に 1 つをピンしました。
* **解決**: [#2617](https://github.com/adcontextprotocol/adcp/issues/2617) / [#2619](https://github.com/adcontextprotocol/adcp/pull/2619) + [#2628](https://github.com/adcontextprotocol/adcp/issues/2628) — §129 は今やキャンセルケースを切り出します: terminal-state 更新がキャンセル試行のとき、エージェントは `NOT_CANCELLABLE` を返さなければなりません（MUST）。他の不正な遷移（canceled での pause/resume）は依然 `INVALID_STATE` を返します。両ストーリーボードは今や再キャンセルで `NOT_CANCELLABLE` をアサートします。
* **回避策**: 既に `canceled` のバイへの `canceled: true` 更新で `NOT_CANCELLABLE` を返します。terminal-state バイの pause/resume で `INVALID_STATE` を返します。キャンセル固有のコードが再キャンセルで勝ち、汎用コードが他のすべてで勝ちます。

### ブランチセットステップグレーディング（`peer_branch_taken`）

* **ストーリーボード**: `contributes_to:` フラグを共有する並列 `optional: true` フェーズを持つ任意のもの。
* **ギャップ**: 準拠エージェントは 1 つのブランチ（例: 即時成功）を選びます。他のブランチのアサーション（例: `status: pending_review`）は、エージェントが反対の動作を取ったため失敗します。#2629 修正の前のランナーは、`any_of` 集計が通過してもこれをサマリーで `× (unknown step)` としてサーフェスしました — 実装者はいないブランチをデバッグしました。
* **解決**: [#2629](https://github.com/adcontextprotocol/adcp/issues/2629) — ランナーは今や、選ばれなかったブランチステップをスキップ理由 `peer_branch_taken`（`not_applicable` とは別、後者はプロトコル/専門分野カバレッジギャップ用に予約）でグレードします。オーサリングルールについては `storyboard-schema.yaml` § "Per-step grading in any\_of branch patterns" を、正準の `detail` 形状については `runner-output-contract.yaml > skip_result.reasons.peer_branch_taken` を参照。
* **回避策**: ランナーが予期しないブランチ失敗をレポートする場合、ピア optional フェーズが同じ `contributes_to` フラグに寄与したかを確認してください。そうなら、選んだブランチで準拠しています — ランナーは #2629 更新が必要です。

### 仕様準拠の `sample_request` を上書きする SDK リクエストビルダー

* **ストーリーボード**: `sales_catalog_driven` `optimization_loop/provide_feedback`、`@adcp/sdk` コンプライアンスランナー経由で公開。
* **ギャップ**: ストーリーボードの `sample_request` は `provide-performance-feedback-request.json` スキーマに従い `performance_index`、`metric_type`、`feedback_source` を正しく宣言します。しかし `@adcp/sdk` の内部 `request-builder.js` に、ペイロードを非仕様の `feedback: { satisfaction, notes }` 形状で置き換える `provide_performance_feedback` のハードコードされた上書きがあったため、準拠エージェントは `INVALID_REQUEST` で拒否しベクターに失敗しました。
* **解決**: 上流 [adcontextprotocol/adcp-client#689](https://github.com/adcontextprotocol/adcp-client/issues/689) + [#2626](https://github.com/adcontextprotocol/adcp/issues/2626) — 上書きを削除しストーリーボードの `sample_request` にペイロードを駆動させます。
* **回避策**: adcp-client#689 修正を含む `@adcp/sdk` リリースに上げます。それまで、`provide_performance_feedback` ベクターは、リクエストを仕様スキーマに対して検証する任意のエージェントで失敗します。

## 曖昧さがリストにないとき

仕様が曖昧に残すと信じる動作でブロックされているがこのリストにない場合、[adcontextprotocol/adcp](https://github.com/adcontextprotocol/adcp/issues/new) で issue を開いてください。ストーリーボード、ベクターのアサーションテキスト、選んだ準拠ブランチ、なぜ仕様が許すと信じるかを含めてください。最速の解決は、特定の仕様段落と特定のベクターアサーションを引用する issue から来ます — それはメンテナーが既存の修正を指すか、ギャップを確認してスケジュールするのに十分です。