git:20260503.79c2835 to git:20260503.91c1ff8

- description: Use when building an AdCP governance agent — a platform that evaluates media buys against spending authority, manages property lists, and enforces content standards.

- ## Overview

-

- A governance agent sits between buyers and sellers, evaluating proposed media buys against organizational policies. Three domains: campaign governance (spending authority, approval/denial), property governance (inclusion/exclusion lists for brand safety), and content standards (creative compliance rules). Determine which domains the user needs.

-

- ## When to Use

-

- - User wants to build an agent that evaluates or approves media buys

- - User mentions governance, brand safety, spending authority, property lists, or content standards

- - User references `check_governance`, `sync_plans`, `create_property_list`, or `calibrate_content`

-

- **Not this skill:**

-

- - Selling ad inventory → `skills/build-seller-agent/`

- - Serving audience segments → `skills/build-signals-agent/`

- - Managing brand identity and licensing → `skills/build-brand-rights-agent/`

-

- **Often claimed alongside:** `measurement-verification` _(preview)_ + `content-standards` — governance vendors (IAS, DV) typically claim all three together. See [Common multi-specialism bundles](../../examples/README.md#common-multi-specialism-bundles).

-

- ## Specialisms This Skill Covers

-

- Your compliance obligations come from the specialisms you claim in `get_adcp_capabilities`. Each maps to a storyboard at `compliance/cache/latest/specialisms/<id>/`:

-

- | Specialism | Status | Delta from baseline | See |

- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |

- | `governance-spend-authority` | stable | `check_governance` evaluates `binding` against Plan's `budget.total`, `human_review_required`, and `custom_policies`; return `approved`, `conditions`, or `denied` | [§ governance-spend-authority](#specialism-governance-spend-authority) |

- | `governance-delivery-monitor` | stable | `check_governance` with `phase: 'delivery'` + `delivery_metrics`; compute drift vs Plan's `budget.reallocation_threshold`; return `BUDGET_DRIFT_EXCEEDED` findings | [§ governance-delivery-monitor](#specialism-governance-delivery-monitor) |

- | `property-lists` | stable | Tool family `property_list` — implement CRUD plus `validate_property_delivery` with full `violations[]` | [§ property-lists](#specialism-property-lists) |

- | `collection-lists` | stable | Tool family `collection_list` — program-level brand safety (shows, series, podcasts) identified by platform-independent IDs: IMDb, Gracenote, EIDR. Mirrors property-lists CRUD plus collection resolution. | [§ collection-lists](#specialism-collection-lists) |

- | `content-standards` | stable | `policies[]` is an array of `{ policy_id, enforcement, policy, policy_categories?, channels? }`; `validate_content_delivery` uses `records[].artifact` (not `creative_id`); re-read policies per call for `standards_version_change` | [§ content-standards](#specialism-content-standards) |

- | `measurement-verification` | preview | v3.1 placeholder (empty `phases`). Pass universal + governance baseline only. Advertise `measurement_verification` capability for discoverability. | Baseline only |

-

- **Not in this skill:** `audience-sync` lives under `protocol: media-buy`. Build it in `skills/build-seller-agent/` instead — it uses `sync_audiences` (overloaded for discovery, add, and delete) and `list_accounts` under the `accounts` / `eventTracking` domain groups.

-

- Specialism ID (kebab-case) = storyboard directory. Storyboard `id:` (snake_case, e.g. `campaign_governance_conditions`) is the category name — multiple specialisms can reference the same storyboard category.

-

- ## Protocol-Wide Requirements

-

- Every production governance agent — regardless of specialism — must wire these. Full treatment in `skills/build-seller-agent/SKILL.md` §Protocol-Wide Requirements and §Composing OAuth, signing, and idempotency; minimum-viable pointers:

-

- - **`idempotency_key`** on every mutating request (`sync_plans`, `create_property_list`/`update_property_list`/`delete_property_list`, `create_collection_list`/`update_collection_list`/`delete_collection_list`, `create_content_standards`/`update_content_standards`, `calibrate_content`). Pass `createIdempotencyStore` to `createAdcpServerFromPlatform(platform, { idempotency })`.

- - **Authentication** via `serve({ authenticate: verifyApiKey(...)/verifyBearer(...) })` from `@adcp/sdk/server`. Unauthenticated agents fail the universal `security_baseline` storyboard.

- - **Signature-header transparency**: don't reject requests that carry `Signature-Input`/`Signature` headers even if you don't claim `signed-requests`.

- - **Resolve-then-authorize** on id lookups (`get_property_list`, `get_content_standards`, `get_collection_list`): return byte-equivalent errors whether the id is cross-tenant or nonexistent — always `REFERENCE_NOT_FOUND`, never `PERMISSION_DENIED`. `adcp fuzz` runs a paired-probe invariant that enforces this; stand up two test tenants and pass `--auth-token` + `--auth-token-cross-tenant` for full coverage. See `skills/build-seller-agent/SKILL.md` §Resolve-then-authorize for the full rules.

- - **`comply_test_controller`** — required to pass the `governance_spend_authority` and `property_lists` storyboards. Each seeds fixtures via `comply_test_controller.seed_plan` / `seed_property_list` before running the business-logic phases. Register via `createComplyController({ seed: { plan, property_list, collection_list, content_standards } })` and call `controller.register(server)` — same pattern as seller. Full treatment in `skills/build-seller-agent/SKILL.md` §Compliance Testing. Without it, all business-logic steps skip with `missing_test_controller` and the track vacuously "passes" (no tests run, vacuous green detected by the grader as fail).

-

- ## Before Writing Code

-

- ### 1. Which Governance Domains?

-

- - **Campaign governance** — evaluates media buys against spending authority. Returns approved, denied, or approved with conditions.

- - **Property governance** — maintains inclusion/exclusion lists of publisher properties for brand safety.

- - **Content standards** — defines creative compliance rules and validates delivery against them.

-

- Most governance agents start with campaign governance. Add property and content standards as needed.

-

- ### 2. Decision Logic

-

- For campaign governance, how should the agent decide?

-

- - **Budget threshold** — deny buys over a per-transaction limit

- - **Policy conditions** — approve with conditions (e.g., "weekly reporting required for CTV")

- - **Channel restrictions** — deny certain channels or require review

- - **Delivery monitoring** — re-evaluate when spend drifts past threshold

-

- ### 3. Property List Types

-

- - **Inclusion lists** — only serve ads on these properties

- - **Exclusion lists** — never serve ads on these properties

- - **GARM category filters** — exclude by IAB/GARM category

-

- ## Tools and Required Response Shapes

-

- > **Before writing any handler's return statement, fetch [`docs/llms.txt`](../../docs/llms.txt) and grep for `#### \`<tool_name>\``(e.g.`#### \`check_governance\``) to read the exact required + optional field list.** The schema-derived contract lives there; this skill covers patterns, gotchas, and domain-specific examples. Strict response validation is on by default in dev — it will tell you the exact field path if you drift, so write the obvious thing and trust the contract.

- >

- > **Cross-cutting pitfalls matrix runs keep catching:**

- >

- > - **Declare `capabilities.specialisms: ['governance-spend-authority', 'property-lists'] as const` on the `DecisioningPlatform` you pass to `createAdcpServerFromPlatform`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.

- > - Every mutating-tool response (`create_property_list`, `create_collection_list`, `create_content_standards`, etc.) has `additionalProperties: false` — don't add extra fields. Return exactly what the schema declares.

-

- ### Campaign Governance

-

- **`get_adcp_capabilities`** — register first, empty `{}` schema

-

- ```

- capabilitiesResponse({

- adcp: { major_versions: [3] },

- supported_protocols: ['governance'],

- })

- ```

-

- **`sync_plans`** — `SyncPlansRequestSchema.shape`

-

- Register governance plans. Each plan in the response needs `plan_id`, `status`, and `version`.

-

- ```

- taskToolResponse({

- plans: [{

- plan_id: string, // required — echo from request

- status: 'active', // required — 'active' | 'paused'

- version: 1, // required — integer version number

- }],

- })

- ```

-

- **`check_governance`** — `CheckGovernanceRequestSchema.shape`

-

- Evaluate a media buy against the registered plan. The request carries a `binding` (what is being evaluated) and a `phase`:

-

- ```

- // Request shape:

- {

- plan_id: string, // required — registered via sync_plans

- phase?: 'create' | 'delivery', // optional — authoritative when present

- binding: { // what to evaluate (create-phase)

- type: 'media_buy',

- media_buy_id?: string, // on delivery phase, the already-created buy

- account: { brand: {...}, operator: string },

- total_budget: { amount: number, currency: string },

- packages: [{ product_id, pricing_option_id, budget }],

- },

- delivery_metrics?: { // on delivery-phase checks — NOT delivery_evidence

- reporting_period: { start: string, end: string },

- spend: number,

- cumulative_spend: number,

- channel_distribution: { [channel: string]: number }, // percent by channel

- pacing: 'ahead' | 'on_pace' | 'behind',

- },

- governance_context?: string, // prior check's context, for re-evaluation

- }

- ```

-

- `phase` is an optional top-level field (`'create' | 'delivery'`). When present, it is authoritative — use it to route. When absent, the presence of `delivery_metrics` is the corroborating signal. The storyboard sends both for delivery-phase checks.

-

- The Plan object (stored via `sync_plans`) drives decisions. Expected shape:

-

- ```

- {

- plan_id: string,

- brand: { domain: string },

- objectives: string,

- budget: {

- total: number,

- currency: string,

- // Exactly one of the next two is required:

- reallocation_threshold?: number, // absolute currency amount the orchestrator can reallocate without human escalation

- reallocation_unlimited?: boolean, // set true for full autonomy up to total (prefer this over threshold == total)

- },

- flight: { start: string, end: string },

- countries: string[],

- human_review_required?: boolean, // GDPR Art 22 / EU AI Act Annex III — when true, every action on this plan needs human review regardless of budget. Set automatically by the agent if any resolved policy has requires_human_review: true.

- custom_policies: [ // array of structured policy objects — NOT bare strings

- {

- policy_id: string,

- enforcement: 'must' | 'should',

- policy: string, // prose description of the rule

- },

- ],

- }

- ```

-

- Authority is split into two independent concerns:

-

- - **`budget.reallocation_threshold` / `reallocation_unlimited`** — budget autonomy. Dollar-denominated cap on how much the orchestrator can shift around without asking.

- - **`human_review_required`** — decisions affecting data subjects (targeting, creative, delivery). Fires regardless of budget. Driven by regulation, not finance.

-

- Both can be true simultaneously on the same plan.

-

- The response needs `check_id`, `status`, `plan_id`, and `explanation`.

-

- ```

- // Approved:

- taskToolResponse({

- check_id: string, // required — unique check identifier

- status: 'approved', // required — enum: 'approved' | 'denied' | 'conditions'

- plan_id: string, // required — echo from request

- explanation: string, // required — human-readable explanation

- governance_context: string, // pass to create_media_buy

- })

-

- // Approved with conditions — status is literally 'conditions' (not 'approved' plus a conditions array):

- taskToolResponse({

- check_id: string,

- status: 'conditions',

- plan_id: string,

- explanation: 'Approved with conditions',

- conditions: [{ // array of binding conditions

- field: string, // required — what the condition applies to

- reason: string, // required — why the condition exists

- required_value: string, // optional — specific value required

- }],

- governance_context: string,

- })

-

- // Denied — also the way human review is signalled (no separate 'escalate' status):

- taskToolResponse({

- check_id: string,

- status: 'denied',

- plan_id: string,

- explanation: 'Exceeds spending authority',

- findings: [{ // array of policy findings

- category_id: string, // required — policy category ID

- severity: 'info' | 'warning' | 'critical', // required — human-review signal uses 'critical'

- explanation: string, // required — human-readable

- }],

- })

- ```

-

- **`get_plan_audit_logs`** — `GetPlanAuditLogsRequestSchema.shape`

-

- ```

- taskToolResponse({

- plan_id: string,

- logs: [{

- timestamp: string, // ISO timestamp

- action: string,

- actor: string,

- }],

- })

- ```

-

- ### Property Governance

-

- **`create_property_list`** — `CreatePropertyListRequestSchema.shape`

-

- Response must include `list` object and `auth_token`.

-

- ```

- taskToolResponse({

- list: {

- list_id: string, // required

- name: string, // required — echo from request

- description: string,

- property_count: 0,

- },

- auth_token: string, // required — token for subsequent operations

- })

- ```

-

- **`get_property_list`** — `GetPropertyListRequestSchema.shape`

-

- ```

- taskToolResponse({

- list: {

- list_id: string,

- name: string,

- },

- })

- ```

-

- **`update_property_list`** — `UpdatePropertyListRequestSchema.shape`

-

- ```

- taskToolResponse({

- list: {

- list_id: string,

- name: string,

- },

- })

- ```

-

- **`list_property_lists`** — `ListPropertyListsRequestSchema.shape`

-

- ```

- taskToolResponse({

- lists: [{

- list_id: string,

- name: string,

- }],

- })

- ```

-

- **`delete_property_list`** — `DeletePropertyListRequestSchema.shape`

-

- ```

- taskToolResponse({

- deleted: true, // required — boolean

- list_id: string, // required — echo from request

- })

- ```

-

- **`validate_property_delivery`** — no generated schema, use `{}` for input

-

- The storyboard's enforcement phase asserts per-record `violations` with list reference and severity. A minimal `{property, compliant}` response will pass schema but fail the behavioral checks.

-

- ```

- // Request:

- {

- list_id: string,

- records: [{

- record_id: string,

- property: { type: 'domain' | 'bundle_id' | ..., value: string },

- impressions: number,

- }],

- }

-

- // Response:

- taskToolResponse({

- compliant: true, // required — overall compliance

- list_id: string, // echo from request

- results: [{

- record_id: string, // echo

- property: { type, value }, // echo

- impressions: number,

- compliant: boolean,

- violations: [{ // empty when compliant

- list_id: string,

- list_type: 'inclusion' | 'exclusion',

- severity: 'critical',

- explanation: string, // e.g. "Property {value} is not on inclusion list {name}"

- }],

- }],

- violations: [], // flattened — all violations across results

- })

- ```

-

- ### Content Standards

-

- **`list_content_standards`** — `ListContentStandardsRequestSchema.shape`

-

- ```

- taskToolResponse({

- standards: [{

- standards_id: string,

- name: string,

- }],

- })

- ```

-

- **`create_content_standards`** — `CreateContentStandardsRequestSchema.shape`

-

- ```

- taskToolResponse({

- standards_id: string, // required — generated ID

- })

- ```

-

- **`get_content_standards`** — `GetContentStandardsRequestSchema.shape`

-

- `policies` is an array of structured rules. Each entry has a `policy_id`, enforcement level (`must` or `should`), a prose `policy` description, optional `policy_categories`, and optional `channels` scope. The prose lives **inside each entry**, not at the container level.

-

- ```

- taskToolResponse({

- standards_id: string,

- name: string,

- policies: [

- {

- policy_id: 'no_violent_imagery',

- policy_categories: ['brand_safety'],

- enforcement: 'must',

- policy: 'No violent or controversial imagery',

- },

- {

- policy_id: 'min_display_dpi',

- policy_categories: ['imagery_quality'],

- enforcement: 'should',

- channels: ['display'],

- policy: 'Minimum 72 DPI for display assets',

- },

- ],

- scope: { languages_any: ['en'], description: 'Acme Outdoor creative standards' },

- })

- ```

-

- On `create_content_standards` / `update_content_standards`, the buyer sends the same `policies[]` array. Store it indexed by `standards_id` and re-read on every `calibrate_content` / `validate_content_delivery` call — the `standards_version_change` storyboard phase re-issues policies and expects the next calibration to reflect the update (a memoized calibration will fail that phase).

-

- **`update_content_standards`** — `UpdateContentStandardsRequestSchema.shape`

-

- ```

- taskToolResponse({

- success: true,

- standards_id: string,

- })

- ```

-

- **`calibrate_content`** — `CalibrateContentRequestSchema.shape`

-

- Verdict mapping: any `enforcement: 'must'` violation → `'fail'`. Only `'should'` violations → `'review'`. No violations → `'pass'`. The `standards_version_change` phase depends on this — after policies update, the same artifact must flip verdicts.

-

- ```

- taskToolResponse({

- verdict: 'pass' | 'fail' | 'review',

- confidence: 0.95,

- explanation: string,

- features: [],

- })

- ```

-

- **`validate_content_delivery`** — `ValidateContentDeliveryRequestSchema.shape`

-

- The request uses `records[].artifact`, not `creative_id`. Each record scopes a served impression with `property_rid`, `artifact_id`, and `assets`. Response returns per-record compliance plus a `summary`.

-

- ```

- // Request:

- {

- standards_id: string,

- records: [{

- record_id: string,

- property_rid: string,

- artifact: {

- artifact_id: string,

- property_rid: string,

- description?: string, // optional prose describing the ad — used by calibration matchers

- assets: [{ // ARRAY of assets — not an object

- type: 'image' | 'video' | 'html' | 'text',

- url: string,

- width?: number,

- height?: number,

- duration_ms?: number,

- }],

- },

- impressions: number,

- }],

- }

-

- // Response:

- taskToolResponse({

- summary: {

- compliant: true,

- total_impressions: number,

- non_compliant_impressions: 0,

- },

- results: [{

- record_id: string, // echo from request

- artifact: {

- artifact_id: string,

- property_rid: string,

- description?: string, // optional prose describing the ad — used by calibration matchers

- assets: [{ // ARRAY of assets — not an object

- type: 'image' | 'video' | 'html' | 'text',

- url: string,

- width?: number,

- height?: number,

- duration_ms?: number,

- }],

- },

- impressions: number,

- compliant: boolean,

- violations: [{ // empty when compliant

- rule: string, // e.g. "No tobacco advertising"

- severity: 'must' | 'should',

- evidence: string, // why it failed

- remediation: string, // how to fix

- }],

- }],

- })

- ```

-

- ### Context and Ext Passthrough

-

- The framework auto-echoes the request's `context` into every response — **do not set `context` yourself in your handler return values.** It's injected post-handler only when the field isn't already present.

-

- **Crucial:** `context` is schema-typed as an object. If your handler hand-sets a string or narrative description, validation fails with `/context: must be object` and the framework does not overwrite. Leave the field out entirely; the framework handles it.

-

- Some schemas also define an `ext` field for vendor-namespaced extensions. If your request schema includes `ext`, accept it without error. Tools with explicit `ext` support: `sync_governance`.

-

- ## SDK Quick Reference

-

- | SDK piece | Usage |

- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |

- | `createAdcpServerFromPlatform(platform, opts)` | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-generated capabilities, ctx_metadata round-trip |

- | `createAdcpServer(config)` _(legacy)_ | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5` |

- | `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp` |

- | `ctx.store` | State persistence — `get/put/patch/delete/list` domain objects |

- | `adcpError(code, { message })` | Structured error |

-

- Handlers return raw data objects. The framework auto-wraps responses and auto-generates `get_adcp_capabilities` from registered handlers.

-

- Import: `import { createAdcpServerFromPlatform, serve, adcpError } from '@adcp/sdk/server';`

-

- ## Setup

-

- ```bash

- npm init -y

- npm install @adcp/sdk

- npm install -D typescript @types/node

- ```

-

- Minimal `tsconfig.json`:

-

- ```json

- {

- "compilerOptions": {

- "target": "ES2022",

- "module": "Node16",

- "moduleResolution": "Node16",

- "strict": true,

- "skipLibCheck": true,

- "outDir": "dist"

- }

- }

- ```

- `skipLibCheck: true` avoids false-positive errors from transitive `.d.ts` files (e.g., `@opentelemetry/api`).

- ## Implementation

- 1. Single `.ts` file — `class MyGovernance implements DecisioningPlatform` with `campaignGovernance`, `propertyLists`, `collectionLists`, `contentStandards` typed sub-platforms

- 2. Do not register `get_adcp_capabilities` — the framework generates it from registered handlers

- 3. Return raw data objects from handlers — the framework wraps responses automatically

- 4. Use `ctx.store` to persist plans, property lists, and content standards

- 5. Set `sandbox: true` on all mock/demo responses

- 6. Handlers receive `(params, ctx)` — `ctx.store` for state, `ctx.account` for resolved account

- ```typescript

- import { randomUUID } from 'node:crypto';

- import {

- createAdcpServerFromPlatform,

- serve,

- createIdempotencyStore,

- memoryBackend,

- type DecisioningPlatform,

- type CampaignGovernancePlatform,

- type PropertyListsPlatform,

- type AccountStore,

- } from '@adcp/sdk/server';

- const idempotency = createIdempotencyStore({

- backend: memoryBackend(),

- ttlSeconds: 86400,

- });

- class MyGovernance implements DecisioningPlatform {

- capabilities = {

- specialisms: ['governance-spend-authority', 'property-lists'] as const,

- config: {},

- };

- accounts: AccountStore = {

- resolve: async ref => ({

- id: 'account_id' in ref ? ref.account_id : 'gov_acc_1',

- operator: 'me',

- ctx_metadata: {},

- }),

- upsert: async () => ({ ok: true, items: [] }),

- list: async () => ({ items: [], nextCursor: null }),

- };

- campaignGovernance: CampaignGovernancePlatform = {

- syncPlans: async (req, ctx) => {

- for (const plan of req.plans) {

- await ctx.store.put('plan', plan.plan_id, plan);

- }

- return {

- plans: req.plans.map(p => ({

- plan_id: p.plan_id,

- status: 'active' as const,

- version: 1,

- })),

- };

- },

- checkGovernance: async (req, ctx) => {

- const plan = await ctx.store.get('plan', req.plan_id);

- // ... decision logic ...

- return {

- check_id: `chk_${randomUUID()}`,

- status: 'approved' as const,

- plan_id: req.plan_id,

- explanation: 'Within spending authority',

- };

- },

- // ... reportPlanOutcome, getPlanAuditLogs, etc.

- };

- propertyLists: PropertyListsPlatform = {

- listPropertyLists: async (req, ctx) => ({ property_lists: [] }),

- createPropertyList: async (req, ctx) => ({

- /* ... */

- }),

- updatePropertyList: async (req, ctx) => ({

- /* ... */

- }),

- deletePropertyList: async (req, ctx) => ({

- /* ... */

- }),

- };

- }

- const platform = new MyGovernance();

- serve(() =>

- createAdcpServerFromPlatform(platform, {

- name: 'Governance Agent',

- version: '1.0.0',

- idempotency,

- })

- );

- ```

- **Decision logic for check_governance:**

- Route decisions based on the plan state and request parameters:

- - Compare request budget against plan's `budget.total`; enforce reallocation autonomy using `budget.reallocation_threshold` (denominated in `budget.currency`) or `budget.reallocation_unlimited: true` — exactly one must be set

- - If `reallocation_threshold` is set and a reallocation exceeds it → require human review / deny

- - If `plan.human_review_required: true` → action must escalate regardless of `mode` (advisory/audit cannot downgrade)

- - Auto-flip `plan.human_review_required: true` when resolved `policy_categories` include `fair_housing | fair_lending | fair_employment | pharmaceutical_advertising`, or when `policy_ids` include `eu_ai_act_annex_iii`

- - If `human_review_required: true` but the brand/brand-ref has no `data_subject_contestation` contact → emit a critical finding

- - Require a `human_override` artifact (reason ≥20 chars, approver email) on re-sync to downgrade `human_review_required: true → false`

- - If policy conditions match → approve with conditions

- - If `phase: 'delivery'` → check delivery_metrics for drift

- ## Idempotency

- AdCP v3 requires an `idempotency_key` on every mutating request — for governance agents that's `create_property_list` / `update_property_list` / `delete_property_list`, `create_content_standards` / `update_content_standards`, `sync_plans`, and `report_plan_outcome` (`check_governance` and the various `get_*` / `list_*` tools are read-only and exempt). Pass `createIdempotencyStore` from `@adcp/sdk/server` to `createAdcpServerFromPlatform(platform, { idempotency })` and the framework handles missing-key rejection (`INVALID_REQUEST`), JCS-canonicalized payload hashing, `IDEMPOTENCY_CONFLICT` on same-key-different-payload (no payload leaked in the error), `IDEMPOTENCY_EXPIRED` past the TTL, `replayed: true` envelope injection on cache hits, and automatic declaration of `adcp.idempotency.replay_ttl_seconds` on `get_adcp_capabilities`. Only successful responses cache — errors re-execute on retry so a failed `sync_plans` or outcome report can be retried cleanly. Scoping is per-principal via `resolveSessionKey` (or override with `resolveIdempotencyPrincipal`) — typically the operator / tenant id.

- ```typescript

- import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';

- const idempotency = createIdempotencyStore({

- backend: memoryBackend(), // or pgBackend(pool) for production

- ttlSeconds: 86400, // 3600–604800 per spec; throws if out of range

- });

- const server = createAdcpServerFromPlatform(platform, {

- name: '...',

- version: '...',

- idempotency,

- // MUST never return undefined — or every mutating request rejects as

- // SERVICE_UNAVAILABLE. A constant works for a demo; production uses

- // `(ctx) => ctx.account?.id` against the typed `Account<MyMeta>`.

- resolveSessionKey: () => 'default-principal',

- });

- ```

- ## Protecting your agent

- **An AdCP agent that accepts unauthenticated requests is non-compliant** (see `security_baseline` in the universal storyboard bundle). Ask the operator: "API key, OAuth, or both?" — then wire one of these into `serve()`.

- ```typescript

- import { serve } from '@adcp/sdk';

- import { verifyApiKey, verifyBearer, anyOf } from '@adcp/sdk/server';

- // API key — simplest, good for B2B integrations

- serve(createAgent, {

- authenticate: verifyApiKey({

- verify: async token => {

- const row = await db.api_keys.findUnique({ where: { token } });

- return row ? { principal: row.account_id } : null;

- },

- }),

- });

- // OAuth — best when buyers authenticate as themselves

- const AGENT_URL = 'https://my-agent.example.com/mcp';

- serve(createAgent, {

- publicUrl: AGENT_URL, // canonical RFC 8707 audience — also served as `resource` in protected-resource metadata

- authenticate: verifyBearer({

- jwksUri: 'https://auth.example.com/.well-known/jwks.json',

- issuer: 'https://auth.example.com',

- audience: AGENT_URL, // MUST equal publicUrl

- }),

- protectedResource: { authorization_servers: ['https://auth.example.com'] },

- });

- // Both

- serve(createAgent, {

- publicUrl: AGENT_URL,

- authenticate: anyOf(verifyApiKey({ verify: lookupKey }), verifyBearer({ jwksUri, issuer, audience: AGENT_URL })),

- protectedResource: { authorization_servers: [issuer] },

- });

- ```

- The framework produces RFC 6750-compliant `WWW-Authenticate: Bearer` 401s on failure, and serves `/.well-known/oauth-protected-resource<mountPath>` with `publicUrl` as the `resource` field so buyers get tokens bound to the right audience. The default JWT allowlist is asymmetric-only (RS*/ES*/PS\*/EdDSA) to prevent algorithm-confusion attacks.

- ## Validate Locally

- **Full validation checklist:** [docs/guides/VALIDATE-YOUR-AGENT.md](../../docs/guides/VALIDATE-YOUR-AGENT.md). Governance-specific commands:

- # Boot

- npx tsx agent.ts &

-

- # Happy paths — run the storyboards matching your claimed specialisms

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp \

- --storyboards governance_spend_authority,governance_spend_authority/denied,governance_delivery_monitor \

- --auth $TOKEN

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp \

- --storyboards property_lists,collection_lists,content_standards \

- --auth $TOKEN

-

- # Cross-cutting obligations

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp \

- --storyboards security_baseline,idempotency,schema_validation,error_compliance --auth $TOKEN

-

- # Rejection-surface fuzz — includes update_property_list / update_content_standards (Tier 3)

- npx @adcp/sdk@latest fuzz http://localhost:3001/mcp --auto-seed --auth-token $TOKEN

- ```

-

- Common failure decoder:

-

- - `authority_level` field present → 3.0 GA removed it; use `human_review_required: boolean` instead

- - `status: 'escalated'` on `check_governance` → enum is `approved` / `denied` / `conditions`

- - Missing `check_id` on `check_governance` response → required; generate a unique ID per check

- - `finding.code` / `finding.message` → schema requires `category_id`, `severity`, `explanation`

-

- **Keep iterating until all steps pass.** Can't bind ports? `npm run compliance:skill-matrix -- --filter governance` runs an isolated end-to-end test.

-

- ## Common Mistakes

-

- | Mistake | Fix |

- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |

- | Manually registering `get_adcp_capabilities` | Framework auto-generates it from registered handlers — do not register it yourself |

- | Using `server.tool()` instead of domain groups | Use `governance: { syncPlans, checkGovernance, ... }` — framework wires schemas and response builders |

- | Using in-memory Maps for state | Use `ctx.store.put/get/patch/delete/list` — built-in state persistence |

- | `check_governance` missing `check_id` | Generate a unique ID per check — required field |

- | `check_governance` returns `decision` not `status` | Field is `status`, not `decision`. Values: `approved`, `denied`, `conditions` |

- | Conditions use `description` instead of `reason` | Condition schema requires `field` and `reason`, not `condition_id` and `description` |

- | Findings use `code`/`message` instead of proper fields | Finding schema requires `category_id`, `severity`, `explanation` |

- | `sync_plans` response missing `version` | Each plan needs `version: 1` (integer) — required field |

- | `delete_property_list` missing `deleted: true` | Boolean `deleted` field is required in response |

- | `create_property_list` missing `auth_token` | `auth_token` is required — generate a token string |

- | Dropping `context` from responses | Echo `args.context` back unchanged in every response — buyers use it for correlation |

-

- ## Storyboards

-

- | Storyboard | Tests |

- | -------------------------------- | ------------------------------------------------------------------ |

- | `campaign_governance_conditions` | Approved with conditions flow |

- | `campaign_governance_delivery` | Delivery monitoring with drift re-evaluation |

- | `campaign_governance_denied` | Denied — buy exceeds spending authority |

- | `property_lists` | Property list lifecycle: create, query, update, delete, validate |

- | `collection_lists` | Collection list lifecycle: create, query (resolve), update, delete |

- | `content_standards` | Content standards lifecycle: create, calibrate, validate |

-

- ## Specialism Details

-

- ### <a name="specialism-governance-spend-authority"></a>governance-spend-authority

-

- Storyboard category: `campaign_governance_*`. The agent holds a Plan and evaluates each binding against it.

-

- Minimal decision logic:

-

- ```typescript

- checkGovernance: async (params, ctx) => {

- const plan = await ctx.store.get('plan', params.plan_id);

- if (!plan) return adcpError('NOT_FOUND', { message: `Plan ${params.plan_id} not found` });

-

- const budget = params.binding.total_budget.amount;

-

- // 1. Human-review gate — GDPR Art 22 / EU AI Act.

- // Every action on a human_review_required plan must be escalated, regardless of budget.

- // Signal as `denied` + a critical-severity finding.

- // The buyer resolves review off-protocol and re-calls check_governance with a fresh governance_context.

- if (plan.human_review_required) {

- return {

- check_id: `chk_${Date.now()}`,

- status: 'denied' as const,

- plan_id: params.plan_id,

- explanation: 'Plan requires human review before this action can proceed',

- findings: [{

- category_id: 'HUMAN_REVIEW_REQUIRED',

- severity: 'critical',

- explanation: 'plan.human_review_required is true — resolve off-protocol and retry with a fresh governance_context',

- }],

- };

- }

-

- // 2. Budget ceiling — cannot exceed plan.budget.total.

- if (budget > plan.budget.total) {

- return { check_id: `chk_${Date.now()}`, status: 'denied' as const, plan_id: params.plan_id,

- explanation: `Budget ${budget} exceeds plan ceiling ${plan.budget.total}`,

- findings: [{ category_id: 'BUDGET_EXCEEDED', severity: 'critical',

- explanation: `Over plan ceiling by ${budget - plan.budget.total}` }],

- };

- }

-

- // 3. Custom policy matching — custom_policies is an array of structured objects

- const conditions = [];

- for (const policy of plan.custom_policies ?? []) {

- if (policy.policy.toLowerCase().includes('ctv') && hasCtv(params.binding)) {

- conditions.push({ field: 'reporting.frequency', reason: policy.policy, policy_id: policy.policy_id });

- }

- }

-

- return {

- check_id: `chk_${Date.now()}`,

- status: conditions.length ? 'conditions' as const : 'approved' as const, // 3-value enum, pick one

- plan_id: params.plan_id,

- explanation: conditions.length ? 'Approved with conditions' : 'Within spending authority',

- conditions,

- governance_context: `gov_ctx_${params.plan_id}_${Date.now()}`, // opaque string — buyer echoes back to create_media_buy

- };

- },

- ```

-

- `governance_context` is an opaque string your agent mints and the buyer echoes back. Use it to tie a specific approval to a specific `create_media_buy` call — sign it or tag it with the plan revision if you care about tamper-resistance.

-

- ### <a name="specialism-governance-delivery-monitor"></a>governance-delivery-monitor

-

- Storyboard: `governance_delivery_monitor`. Same `check_governance` tool, but the request carries `delivery_metrics` instead of a bare binding — that's the cue to run drift logic.

-

- ```typescript

- checkGovernance: async (params, ctx) => {

- if (params.phase === 'delivery' || params.delivery_metrics) {

- const plan = await ctx.store.get('plan', params.plan_id);

- const reallocationThreshold = plan.budget.reallocation_threshold; // absolute $, e.g. 8000

-

- // Check total-spend drift against the reallocation threshold

- const cumulative = params.delivery_metrics.cumulative_spend;

- const overage = cumulative - plan.budget.total;

- const exceeded = Math.abs(overage) > reallocationThreshold;

-

- // Also flag pacing mismatches that imply channel reallocation

- const driftedChannels = Object.entries(params.delivery_metrics.channel_distribution ?? {})

- .filter(([channel, percent]) => {

- const planAllocation = plan.channel_allocations?.[channel];

- return planAllocation != null && Math.abs(percent - planAllocation) > 10; // 10pp threshold

- });

-

- if (!exceeded && driftedChannels.length === 0) {

- return { check_id: `chk_${Date.now()}`, status: 'approved' as const, plan_id: params.plan_id,

- explanation: 'Delivery within reallocation threshold',

- governance_context: params.governance_context ?? `gov_ctx_${params.plan_id}_delivery_approved` };

- }

-

- return {

- check_id: `chk_${Date.now()}`,

- status: 'conditions' as const, // approved-with-reallocation — use the 'conditions' status, not 'approved'

- plan_id: params.plan_id,

- explanation: `Drift exceeded threshold: ${overage > 0 ? 'overage' : 'underage'} of ${Math.abs(overage)}`,

- conditions: driftedChannels.map(([channel, percent]) => ({

- field: `channel_distribution.${channel}`,

- reason: `Rebalance away from ${channel} — currently ${percent}%, plan targets ${plan.channel_allocations?.[channel] ?? 'unspecified'}%`,

- })),

- findings: [{ category_id: 'BUDGET_DRIFT_EXCEEDED', severity: 'warning',

- explanation: `Cumulative spend ${cumulative} outside reallocation threshold ±${reallocationThreshold}` }],

- };

- }

- // ... create-phase logic above

- },

-

- // Policy matching in create-phase checks — custom_policies is an array of objects, not strings:

- for (const policy of plan.custom_policies ?? []) {

- if (policy.policy.toLowerCase().includes('ctv') && hasCtv(params.binding)) {

- conditions.push({ field: 'reporting.frequency', reason: policy.policy });

- }

- }

- ```

-

- The `findings[].category_id` / `severity: 'info' | 'warning' | 'critical'` enum is the schema-canonical shape per [adcontextprotocol/adcp#2286](https://github.com/adcontextprotocol/adcp/issues/2286). Storyboard validations today only check `field_present: findings`, so either spelling passes — but use the schema shape.

-

- ### <a name="specialism-property-lists"></a>property-lists

-

- Storyboard: `property_lists`. Specialism and tool family share the same name. Your agent owns both inclusion and exclusion list semantics — track `list_type` on the stored list. Wrap identifiers with `selection_type: 'identifiers'`:

-

- ```typescript

- createPropertyList: async (params, ctx) => {

- const list_id = `plist_${Date.now()}`;

- const stored = {

- list_id,

- name: params.name,

- description: params.description,

- list_type: 'inclusion' as const, // caller-modeled — infer from context or add as ext

- base_properties: params.base_properties ?? [], // each entry: { selection_type: 'identifiers', identifiers: [{ type, value }] }

- property_count: countIdentifiers(params.base_properties),

- status: 'active' as const,

- };

- await ctx.store.put('property_list', list_id, stored);

- return {

- list: summarize(stored),

- auth_token: `tok_${list_id}`,

- };

- },

-

- // Shape of a base_properties entry (matches the storyboard sample):

- type BaseProperty = {

- selection_type: 'identifiers';

- identifiers: Array<{

- type: 'domain' | 'bundle_id' | 'app_store_url' | 'podcast_rss_feed' | 'property_rid';

- value: string;

- }>;

- };

- ```

-

- **`list_property_lists` / `list_collection_lists`** — destructure `ctx.store.list`. It returns `{ items, nextCursor? }`, never a bare array. Calling `.map` / `.filter` on the raw result throws `TypeError` and the dispatcher wraps it as `SERVICE_UNAVAILABLE`. Use the typed response helper so you can't accidentally ship a bare `[...]` at the top level (the storyboard runner flags that as shape drift):

-

- ```typescript

- import { listPropertyListsResponse } from '@adcp/sdk/server';

-

- listPropertyLists: async (params, ctx) => {

- const { items } = await ctx.store.list('property_list');

- return listPropertyListsResponse({

- lists: items.map(list => ({ list_id: list.list_id, name: list.name })),

- });

- },

- ```

-

- The same pattern applies to `list_collection_lists` (use `listCollectionListsResponse`) and `list_content_standards` (use `listContentStandardsResponse`). Both wrap the same `lists` / `standards` shape and guard against the bare-array drift at compile time.

-

- `validate_property_delivery` returns `violations[]` with `list_id`, `list_type`, `severity: 'critical'`, and an explanation per non-compliant record — see the response shape in the tool section above.

-

- The three mutating tools (`create_property_list`, `update_property_list`, `delete_property_list`) require `idempotency_key` per AdCP 3.0 GA — cache the response and return the same object on replay.

-

- ### <a name="specialism-collection-lists"></a>collection-lists

-

- Storyboard: `collection_lists`. Where `property-lists` curate surfaces (domains, app bundle IDs), `collection-lists` curate **content programs** (shows, series, podcasts, series arcs) identified by platform-independent IDs: IMDb (`tt0944947`), Gracenote, EIDR. Program-level brand safety — "keep my ads out of all episodes of [show]" cuts across every surface that carries that show.

-

- **Request shape** — `base_collections[]` wraps identifiers with a `selection_type`, and `filters` is an object (not an array):

-

- ```typescript

- createCollectionList: async (params, ctx) => {

- const list_id = `clist_${Date.now()}`;

- const stored = {

- list_id,

- name: params.name,

- description: params.description,

- base_collections: params.base_collections ?? [], // see shape below

- filters: params.filters ?? {}, // object — e.g. { kinds: ['series'] }

- collection_count: resolveCollectionCount(params.base_collections, params.filters),

- status: 'active' as const,

- };

- await ctx.store.put('collection_list', list_id, stored);

- return { list: summarize(stored), auth_token: `tok_${list_id}` };

- },

-

- // Shape of a base_collections entry:

- type BaseCollection = {

- selection_type: 'distribution_ids';

- identifiers: Array<{

- type: 'imdb_id' | 'gracenote_id' | 'eidr';

- value: string; // e.g. "tt9999901"

- }>;

- };

-

- // Shape of filters:

- type Filters = {

- kinds?: ('series' | 'movie' | 'podcast' | 'episode')[];

- // other filter families added in 3.1

- };

- ```

-

- **`get_collection_list`** with `resolve: true` returns the concrete `collections[]` (not `resolved_programs`) — the resolved list of program IDs after filters are applied. Sellers cache this at bid time.

-

- ```typescript

- {

- list: {

- list_id: string,

- name: string,

- collection_count: number,

- collections: Array<{ type, value }>, // resolved programs

- cache_valid_until: string, // ISO timestamp — sellers respect this TTL

- },

- }

- ```

-

- No `validate_collection_delivery` tool exists yet (preview in 3.1). Delivery enforcement is a receiving-seller concern; the governance agent's job ends at publishing the resolved list with a `cache_valid_until`.

-

- ### <a name="specialism-content-standards"></a>content-standards

-

- Storyboard: `content_standards`. Two load-bearing protocol shapes the baseline above does not cover:

-

- 1. **`policies` is an array of structured entries**, not a prose string. Each entry carries its own `enforcement` level — don't parse severity from inline `(must)` / `(should)` markers; read it off the `enforcement` field:

- ```typescript

- type Policy = {

- policy_id: string;

- enforcement: 'must' | 'should';

- policy: string; // prose description of the rule

- policy_categories?: string[]; // e.g. ['brand_safety', 'imagery_quality']

- channels?: string[]; // e.g. ['display'] — scoped enforcement

- };

- function applies(p: Policy, artifact: { channel: string }): boolean {

- return !p.channels || p.channels.includes(artifact.channel);

- }

- 2. **`validate_content_delivery` uses `records[].artifact`**, not `results[].creative_id`. See the tool section above for the full shape.

- **Re-read policies per call.** The `standards_version_change` phase issues an update, then re-calibrates the same artifact and expects the new verdict. A memoized calibrator that caches by artifact_id will fail that phase. Always fetch the latest policies from `ctx.store.get('content_standards', standards_id)` inside `calibrate_content` / `validate_content_delivery`.

- `calibrate_content` should return per-rule results, not just a top-level verdict:

- ```typescript

- calibrateContent: async (params, ctx) => ({

- verdict: 'fail' as const,

- confidence: 0.95,

- explanation: 'Content violates tobacco-free rule',

- rules: [

- { rule: 'No tobacco advertising', severity: 'must', passed: false,

- evidence: 'Detected cigarette imagery in primary asset',

- remediation: 'Remove cigarette imagery or select a compliant creative' },

- { rule: 'Weekly pacing reports required for CTV', severity: 'should', passed: true,

- evidence: 'Agent has reporting_capabilities frequencies: ["weekly"]', remediation: null },

- ],

- features: [],

- }),

- ```

- ## Reference

- - `storyboards/campaign_governance_conditions.yaml` — conditional approval flow

- - `storyboards/campaign_governance_denied.yaml` — denial flow

- - `storyboards/property_lists.yaml` — property list lifecycle

- - `storyboards/collection_lists.yaml` — collection list lifecycle

- - `storyboards/content_standards.yaml` — content standards lifecycle

- - `docs/guides/BUILD-AN-AGENT.md` — SDK patterns

- - `docs/TYPE-SUMMARY.md` — curated type signatures

- - `docs/llms.txt` — full protocol reference