Storyboard authoring — scoping rules

Compliance storyboards live under static/compliance/source/, the canonical authored source for the compliance bundle. Do not add generated cache artifacts such as domains/ or index.json there; scripts/build-compliance.cjs creates them in dist/compliance/latest/ during development and stamps dist/compliance/{version}/ on release. Each step that invokes a training-agent task that scopes session state by tenant must carry brand or account identity in sample_request. Otherwise the call lands in open:default, and a follow-up step that does carry identity writes to open:<brand> — giving you MEDIA_BUY_NOT_FOUND against your own just-created media buy. This rule is enforced at build time by scripts/lint-storyboard-scoping.cjs, which runs as part of npm run build:compliance.

Canonical identity shape

Use account { brand, operator }. The AccountRef schema requires operator whenever the natural-key form (brand) is used — there is no “just a brand” shape at the spec level.

sample_request:
  account:
    brand:
      domain: "acmeoutdoor.example"
    operator: "pinnacle-agency.example"
  # ...

Explicit-account form (when the seller issued an account_id via list_accounts):

sample_request:
  account:
    account_id: "acc_acme_001"
  # ...

For sync_plans, identity lives inside each plan entry. The sync-plans-request schema defines brand on each plan item and forbids account there — do not use the wrapper form inside plans[]:

sample_request:
  plans:
    - plan_id: "plan-001"
      brand:
        domain: "acmeoutdoor.example"
      # ...

What about top-level `brand`?

Some AdCP requests (create_media_buy, get_products, build_creative) have a top-level brand field. That is the campaign’s brand, a separate schema field — not an identity shorthand. create_media_buy requires both account and brand; one does not substitute for the other. The lint still accepts a bare top-level brand.domain as a fallback because the training agent’s sessionKeyFromArgs reads it — but that is a training-agent routing detail, not a spec-canonical shape. New storyboards should use account { brand, operator }.

Which tasks are session-scoped?

The authoritative list lives in scripts/lint-storyboard-scoping.cjs as TENANT_SCOPED_TASKS. A parity test (tests/lint-storyboard-scoping.test.cjs) asserts every task registered in the training agent’s HANDLER_MAP appears in either TENANT_SCOPED_TASKS or EXEMPT_FROM_LINT. If you add a new tool to the dispatch table and forget to classify it, the parity test fails — you won’t get silent drift. Rule of thumb: if the task’s request schema has a required globally-unique scope-ID (plan_id, rights_id, standards_id, list_id, event_source_id, or proposal IDs inside refinements/declines), the seller can resolve the tenant from that ID alone — envelope identity is redundant and the lint does not require it (see EXEMPT_FROM_LINT bucket (c)). Everything else falls into TENANT_SCOPED_TASKS: create/update mutations without a scope-ID, list/get operations that don’t carry a single resource ID, resource-standards calls without standards_id in schema, etc. These must carry envelope account { brand, operator }.

Identity fields that flow through `$context`

When a step captures a value into $context via context_outputs and a later step consumes it as $context.<name>, the entity type at both ends must match. If the value captured from a field annotated advertiser_brand is consumed as a field annotated rights_holder_brand, the lint will flag it (that’s the #2627 bug: same field name, different entity). See docs/contributing/x-entity-annotation.md for the list of entity types and how schema authors annotate fields. Other exempt categories: payload-array-keyed sync tasks (sync_accounts, sync_governance, sync_catalogs, sync_event_sources), global discovery (get_adcp_capabilities, plus deprecated list_creative_formats compatibility tests), global catalog reads (get_brand_identity, get_rights, update_rights), and the comply_test_controller sandbox primitive.

Why ID-scoped tasks are exempt

check_governance, report_plan_outcome, acquire_rights, log_event, calibrate_content, validate_content_delivery, validate_property_delivery, refine_proposals, and decline_proposals all require one or more globally-unique IDs that were previously provisioned with brand context. At the spec level, a real seller resolves each ID → tenant via its own lookup; the envelope doesn’t need to repeat the identity. Most legacy ID-scoped storyboards still carry envelope identity because the training agent’s sessionKeyFromArgs uses it for sandbox routing. The split proposal-lifecycle schemas deliberately forbid account on refine_proposals and decline_proposals; for those tools, the training agent reverse-resolves the proposal IDs to the originating account scope. The remaining envelope identity is a sandbox routing convention, not a spec claim. Production sellers resolve tenant from the authenticated principal (bearer/OAuth/HMAC), not from envelope payload — see Tenant resolution. They don’t need envelope identity on ID-scoped tasks and wouldn’t rely on it if present.

Intentionally cross-tenant probes

If your step is supposed to probe a session-scoped task without tenant identity — e.g. a negative test that verifies the seller rejects the bare request, or a capability-discovery probe — annotate the step:

- id: probe_without_brand
  task: get_media_buys
  scoping: global
  sample_request:
    # ... no brand/account here by design

Use sparingly. When in doubt, carry brand identity — nearly all real-world calls do.

Fixtures and cross-step captures

Storyboards that need prerequisite state (a qualifying product, a creative already in approved status, a plan the governance flow can reference) have three ways to obtain it: declarative fixtures: at the storyboard root for state that exists before the test runs, optional fixture_resolution: rules when a seller-owned entity may satisfy that state, and step context_outputs: captures for IDs generated during the run.

When to use which

Fixture origin	Pattern	Authored as
Exists before the storyboard and must be injected literally	`fixtures:` at storyboard root	Declarative block; seed-only compatibility default
Exists in the seller’s sandbox catalog	`fixtures:` plus explicit `fixture_resolution:`	Runner seeds or discovers according to the declared strategy order and binds the seller-issued ID
Generated by an earlier step in this run	`context_outputs:` on the generating step, `$context.<name>` on later steps	Captured at runtime; stays inside this run
Runner-supplied (webhook URLs, etc.)	`{{runner.webhook_url:<step_id>}}`	Substitution variable

Never hardcode a literal ID in sample_request if you can avoid it. A literal like media_buy_id: "mb_acme_q2_2026_auction" only works if the agent happens to generate (or accept) that exact ID. Spec-compliant agents auto-generate IDs — the literal won’t match and your storyboard will fail for an implementer who did nothing wrong.

Pattern A — prerequisite fixtures via `fixtures:` + `comply_test_controller`

Declare fixtures at the storyboard root. Set prerequisites.controller_seeding: true to tell the runner to auto-inject a fixtures phase before the main phases.

id: sales_non_guaranteed
prerequisites:
  controller_seeding: true
  description: "Requires a seeded product and approved creative."

fixtures:
  products:
    - product_id: "test-product"
      delivery_type: "non_guaranteed"
      pricing_options:
        - pricing_option_id: "test-pricing"
          pricing_model: "cpm"
          currency: "USD"
  creatives:
    - creative_id: "campaign_hero_video"
      status: "approved"
      format_kind: "video_hosted"

phases:
  - id: place_buy
    steps:
      - id: create_buy
        task: create_media_buy
        sample_request:
          packages:
            - product_id: "test-product"           # ← seeded above
              pricing_option_id: "test-pricing"   # ← seeded above

The runner injects a fixtures phase that calls comply_test_controller with scenario: seed_product, scenario: seed_pricing_option, and scenario: seed_creative (in foreign-key order) before running place_buy. An agent that implements the seed scenarios passes out of the box; an agent that returns UNKNOWN_SCENARIO on the seeds causes the storyboard to grade as not_applicable, not failed — implementers don’t get penalized for missing sandbox-only surface. When a vendor-metric storyboard needs a deterministic external measurement.metrics[] snapshot, add an explicit comply_test_controller step with scenario: seed_measurement_catalog. Use measurement_catalogs[] inside a product fixture only as a compatibility fallback when the same storyboard also needs to carry the seller’s product-level capability fields. See the full list of seed scenarios and their params in Compliance test controller — Scenarios.

Pattern B — seller-catalog fixtures via `fixture_resolution:`

Keep the seed exemplar in fixtures: and add runner-only matching rules in a separate root block. An older runner continues to seed the literal. A 3.2 runner tries the declared strategies in order and may bind the handle to a seller ID.

fixtures:
  products:
    - product_id: "test-product"
      delivery_type: "non_guaranteed"
      channels: ["display"]

fixture_resolution:
  products:
    - handle: "test-product"
      strategies: [seed, discover]
      match:
        - path: /delivery_type
          operator: equals
          value: non_guaranteed
        - path: /channels
          operator: contains_all
          value: [display]

Do not add discover by copying every fixture field into equality clauses. Declare only properties material to the storyboard’s assertions. Presentation copy, sample prices, and other illustrative values should not become accidental eligibility gates. Conversely, a currency-filter storyboard must keep currency as a requirement because changing it changes the behavior under test. Discovery rules are explicit because fixture objects are not generic subset predicates. The source lint rejects malformed strategies, dangling handles, unknown operators, and ambiguous product-scoped pricing handles. See the normative fixture_resolution section in storyboard-schema.yaml for all operators and grading behavior.

Pattern C — flow-derived captures via `context_outputs:` + `$context.<name>`

Capture the ID the generating step returned, then reference it by $context.<name> on downstream steps.

steps:
  - id: create_buy
    task: create_media_buy
    sample_request:
      packages: [...]
    context_outputs:
      - name: media_buy_id
        path: "media_buy_id"        # JSON path against this step's response

  - id: check_buy
    task: get_media_buys
    sample_request:
      media_buy_ids: ["$context.media_buy_id"]   # ← resolved at run time

The runner captures media_buy_id from create_buy’s response (after its validations pass), stores it in the run-scoped context accumulator, then substitutes the literal string $context.media_buy_id in check_buy.sample_request before sending. Agents see the actual ID — never the literal $context.foo token. Capture failures grade the generating step, not the reader: if the response doesn’t contain media_buy_id at the declared path, create_buy fails with capture_path_not_resolvable. This is deliberate — the contract the storyboard declared (“this step produces a media_buy_id”) is what failed, not the step that tried to use it.

Context block and the echo contract

Storyboards that assert on response context MUST send a context: block on the sample_request:

sample_request:
  packages: [...]
  context:
    correlation_id: "sales_non_guaranteed--create_buy"
validations:
  - check: field_value
    path: "context.correlation_id"
    value: "sales_non_guaranteed--create_buy"
    description: "Agent echoes context verbatim"

The runner does NOT auto-inject context: on sample_requests that omit it. Storyboards whose validator expects context.correlation_id in the response but whose sample_request lacks context: are authoring bugs — the agent is allowed (and required) to omit context when the caller sent none. See Context and sessions — Normative echo contract for the agent-side rules.

Asserting on errors

AdCP surfaces errors in two layers (see Error handling — envelope vs. payload). Storyboards MUST assert error shape in a way that works regardless of which layer a conformant agent surfaced the error on. Use check: error_code — not check: field_present, path: "errors".

# ✅ Shape-agnostic — resolves from either adcp_error (envelope) or errors[] (payload)
validations:
  - check: error_code
    value: "BUDGET_TOO_LOW"
    description: "Budget validation rejected with BUDGET_TOO_LOW"

# ✅ Multiple acceptable codes
validations:
  - check: error_code
    allowed_values: ["VALIDATION_ERROR", "INVALID_REQUEST", "BUDGET_TOO_LOW"]

# ❌ Pins to the payload `errors[]` shape — fails against agents that surface
#    errors only via the transport envelope (MCP `adcp_error`, A2A DataPart)
validations:
  - check: field_present
    path: "errors"

Every code used in value: or allowed_values: MUST exist in the canonical error-code enum at static/schemas/source/enums/error-code.json. The lint:error-codes script (wired into npm run test) walks every storyboard and rejects references to codes that aren’t in the enum — a build failure before any test runs. When a rename is required, register the old code in scripts/error-code-aliases.json. The file is pure data (it lives next to the lint script that reads it, not in the schema tree) and ships with an empty aliases map by default:

{
  "aliases": {
    "OLD_CODE": "NEW_CODE"
  }
}

Aliased codes pass the lint as warnings during the deprecation window, giving authors time to migrate storyboards. Once the alias is removed from the file, references to the old code become lint errors. This is how renames land without breaking storyboard authorship across versions.

Asserting on branchable behaviors

Some spec requirements allow multiple conformant agent behaviors — e.g. an operation may return immediate success OR pending_review depending on seller policy. A single-assertion validator that asserts only one branch forces a conformant agent that picked the other branch to silently fail. When the spec allows a branchable outcome, split the storyboard into parallel optional phases and resolve via assert_contribution:

phases:
  - id: reject_path
    optional: true
    steps:
      - id: probe_reject
        expect_error: true
        contributes_to: behavior_handled
        validations:
          - check: error_code
            value: "INVALID_REQUEST"

  - id: adjust_path
    optional: true
    steps:
      - id: probe_adjust
        contributes_to: behavior_handled
        validations:
          - check: response_schema
          - check: field_present
            path: "media_buy_id"

  - id: enforcement
    steps:
      - id: require_either
        task: assert_contribution
        validations:
          - check: any_of
            allowed_values: ["behavior_handled"]
            description: "Agent must exhibit one of the conformant branches."

Failures inside an optional: true phase do NOT fail the storyboard — only the synthetic assert_contribution in the final phase does, and only when no branch contributed. Conformant agents pass exactly one branch and fail the other by design. The non-chosen branch’s failing steps MUST be reported by the runner with skip reason peer_branch_taken, not failed. This keeps runner summaries accurate for conformant agents (the other-branch failures were not real failures) and keeps dashboard coverage signals clean (peer_branch_taken is runtime routing; not_applicable is for protocol coverage gaps). See universal/storyboard-schema.yaml § “Per-step grading in any_of branch patterns” and universal/runner-output-contract.yaml > skip_result.reasons.peer_branch_taken for the normative rule. Use this shape for any spec MAY / any_of where observable outcomes differ across branches. Do not use it for create_media_buy.start_time in the past; that case is now reject-only with INVALID_REQUEST. Single-code check: error_code is still correct when the spec mandates a canonical code for a scenario (e.g. GOVERNANCE_DENIED on a governance-denied outcome, NOT_CANCELLABLE on re-cancel). The split-phase pattern applies only when the spec itself leaves the outcome branchable.

When NOT to use this pattern

The parallel-optional-phases + assert_contribution shape is only appropriate when the spec text itself permits multiple observable outcomes (look for explicit MAY/OR in the normative prose, or an enum of acceptable statuses). It is not a tool for softening a vector because an agent’s behavior drifted from the spec. Do not apply this pattern to:

Idempotency semantics. idempotency_key must be rejected when missing on mutating tasks; replay must return the cached response; conflict must surface IDEMPOTENCY_CONFLICT. The spec mandates single behaviors — any other outcome is non-conformant, not a valid branch.
Context echo. Responses MUST echo context: verbatim when the caller sent it. There is no conformant branch that omits the echo.
Error-code vocabulary. Canonical codes enumerated in static/schemas/source/enums/error-code.json are single-value per scenario. If a storyboard asserts GOVERNANCE_DENIED on a governance-denied outcome, that is the code — not one option among several.
Webhook signing correctness. RFC 9421 signing with AdCP’s covered-components profile is a single verification shape; there is no alternate branch.

If you find yourself reaching for the split-phase pattern to get past a failing vector, first verify the spec actually permits the branch you want to accept. If it doesn’t, the fix is in the agent (or in the spec), not in the vector.

Adding a catalog-substitution-safety phase to a new specialism

If you are adding a specialism that renders catalog-item macros into URLs (catalog-driven sales, generative sellers, retail-media, etc.), your storyboard SHOULD include a substitution-safety phase covering the rule set at docs/creative/universal-macros.mdx#substitution-safety-catalog-item-macros. Start from the template, don’t copy-paste from a sibling specialism. The canonical three-step phase (sync_*_probe_catalog → build_*_probe_creative → expect_substitution_safe) lives as a phase_template: comment block in static/compliance/source/test-kits/substitution-observer-runner.yaml. The block uses <<PLACEHOLDER>> tokens for the specialism-specific bits (brand domain, catalog_id prefix, idempotency prefix) so you can materialize a new phase by doing a simple text substitution against those tokens. Copying a near-clone from sales-catalog-driven or creative-generative works in principle, but the DX reviewer on #2654 flagged that three consumers is the inflection point where trivial drift starts (misspelled item_id, missing require_every_binding_observed: true). The template is the drift-avoidance surface; the lint:substitution-vector-names script (#2655) catches typos in the vector_name references.

Running the lint locally

npm run build:compliance    # includes the lint
node scripts/lint-storyboard-scoping.cjs    # lint only
npm run test:storyboard-scoping    # parity test

Typical failure output:

✗ storyboard scoping lint: 1 violation(s)

  protocols/media-buy/scenarios/invalid_transitions.yaml:setup/create_buy (create_media_buy) — sample_request missing brand/account

Fix: add `account { brand, operator }` to sample_request, e.g.
  sample_request:
    account:
      brand:
        domain: "acmeoutdoor.example"
      operator: "pinnacle-agency.example"

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

Storyboard authoring

Storyboard authoring — scoping rules

Canonical identity shape

What about top-level `brand`?

Which tasks are session-scoped?

Identity fields that flow through `$context`

Why ID-scoped tasks are exempt

Intentionally cross-tenant probes

Fixtures and cross-step captures

When to use which

Pattern A — prerequisite fixtures via `fixtures:` + `comply_test_controller`

Pattern B — seller-catalog fixtures via `fixture_resolution:`

Pattern C — flow-derived captures via `context_outputs:` + `$context.<name>`

Context block and the echo contract

Asserting on errors

Asserting on branchable behaviors

When NOT to use this pattern

Adding a catalog-substitution-safety phase to a new specialism

Running the lint locally

​Storyboard authoring — scoping rules

​Canonical identity shape

​What about top-level brand?

​Which tasks are session-scoped?

​Identity fields that flow through $context

​Why ID-scoped tasks are exempt

​Intentionally cross-tenant probes

​Fixtures and cross-step captures

​When to use which

​Pattern A — prerequisite fixtures via fixtures: + comply_test_controller

​Pattern B — seller-catalog fixtures via fixture_resolution:

​Pattern C — flow-derived captures via context_outputs: + $context.<name>

​Context block and the echo contract

​Asserting on errors

​Asserting on branchable behaviors

​When NOT to use this pattern

​Adding a catalog-substitution-safety phase to a new specialism

​Running the lint locally

Storyboard authoring — scoping rules

Canonical identity shape

What about top-level `brand`?

Which tasks are session-scoped?

Identity fields that flow through `$context`

Why ID-scoped tasks are exempt

Intentionally cross-tenant probes

Fixtures and cross-step captures

When to use which

Pattern A — prerequisite fixtures via `fixtures:` + `comply_test_controller`

Pattern B — seller-catalog fixtures via `fixture_resolution:`

Pattern C — flow-derived captures via `context_outputs:` + `$context.<name>`

Context block and the echo contract

Asserting on errors

Asserting on branchable behaviors

When NOT to use this pattern

Adding a catalog-substitution-safety phase to a new specialism

Running the lint locally