@adcp/sdk 13.0.1 → 13.0.3

package/dist/lib/testing/storyboard/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/testing/storyboard/types.ts"],"sourcesContent":["/**\n * Types for storyboard-driven testing.\n *\n * Storyboards are YAML-defined test workflows that walk through\n * AdCP agent interactions step by step. Each step maps to a\n * SingleAgentClient method and includes validations.\n */\n\nimport type { TestOptions } from '../types';\nimport type { BuyerAgent, BuyerAgentBillingMode, BuyerAgentStatus } from '../../server/decisioning/buyer-agent';\nimport type { WebhookConformanceSigningOptions } from '../../conformance/types';\n\n// ────────────────────────────────────────────────────────────\n// Parsed storyboard structure (mirrors YAML schema)\n// ────────────────────────────────────────────────────────────\n\nexport type CapabilityPredicateValue =\n  | boolean\n  | string\n  | number\n  | null\n  | CapabilityPredicateValue[]\n  | { [key: string]: CapabilityPredicateValue };\n\nexport type RequiresCapabilityPredicate =\n  | { path: string; equals: boolean | string | number | null }\n  | { path: string; present: boolean }\n  | { path: string; contains: CapabilityPredicateValue }\n  | { path: string; not_contains: CapabilityPredicateValue };\n\nexport interface Storyboard {\n  id: string;\n  version: string;\n  /**\n   * AdCP compliance cache version this storyboard was loaded from, e.g.\n   * \"3.0.12\" or \"3.1.0-beta.7\". Injected by the local cache loader; not\n   * authored in storyboard YAML.\n   */\n  adcp_version?: string;\n  title: string;\n  category: string;\n  summary: string;\n  narrative: string;\n  /** Maps to a ComplianceTrack for comply() integration */\n  track?: string;\n  /**\n   * AdCP spec version that introduced this storyboard, e.g. \"3.1\".\n   * When set, the runner skips the storyboard for agents whose declared\n   * `adcp.major_versions` does not include the major component — the\n   * storyboard did not exist at the version the agent certified against.\n   * Unset (the default) means the storyboard has always applied.\n   */\n  introduced_in?: string;\n  /** Tools that make this storyboard applicable (at least one must be present) */\n  required_tools?: string[];\n  /**\n   * Strict tool-family advertisement gates. Each family is satisfied when\n   * the agent advertises at least one listed tool; missing a family skips\n   * the whole storyboard with `requirement_unmet` and a\n   * `missing_required_tool_family:` detail prefix. The standard `comply()`\n   * path populates `agentTools` before this gate runs; direct callers that\n   * reuse a client should provide `agentTools` or `_profile.tools` so the\n   * runner can enforce it without discovery ambiguity.\n   */\n  required_any_of_tools?: RequiredToolFamily[];\n  /**\n   * Runtime requirements this storyboard depends on. Each name describes\n   * something the runner detects from the agent or from operator-supplied\n   * options; an unmet requirement skips the whole storyboard with\n   * `skip_reason: 'requirement_unmet'` rather than producing a cascade of\n   * misleading per-step `missing_test_controller` skips.\n   *\n   * Recognised names:\n   *   - `controller` — the agent must advertise `comply_test_controller`.\n   *     Detected from `options.agentTools`, `_profile.tools`, or discovery\n   *     on reused clients. Direct callers that deliberately provide none of\n   *     those surfaces bypass this check; their storyboard runs into the\n   *     per-step `missing_test_controller` cascade instead.\n   *   - `seeded_state` — the operator must pass `--asserts-seeded-state`\n   *     (or set `assertsSeededState: true`) declaring that initial state\n   *     has been provisioned out-of-band (HTTP admin, pre-test script,\n   *     staging fixture). The runner does not verify the assertion;\n   *     scenarios that need state still fail naturally if the seed is\n   *     not actually present.\n   *   - `real_wire` — always available. Tag scenarios that observe\n   *     production behavior with this when you want them excluded from\n   *     a future `--mock-only` mode; today the tag is a no-op gate.\n   *   - `webhook_receiver` — the runner must be configured with a\n   *     webhook receiver (`StoryboardRunOptions.webhook_receiver`).\n   *     Autodetected from token presence: any step whose\n   *     `sample_request` (or nested fields) references\n   *     `{{runner.webhook_url:<step_id>}}` or `{{runner.webhook_base}}`\n   *     declares this requirement implicitly. Authors do not need to\n   *     write `requires: [webhook_receiver]` — the tokens are\n   *     self-describing.\n   *   - `webhook_replay_receiver` — the runner must be configured with an\n   *     inbound buyer/orchestrator receiver URL\n   *     (`StoryboardRunOptions.webhook_replay_receiver.url`). Autodetected\n   *     from any `replay_webhook_vector` step and graded not applicable when\n   *     absent. Spec: adcp-client#2356.\n   *   - `trusted_match_context_router_runner` — the runner must be configured\n   *     with a raw Context Match router URL and operator registration seam.\n   *     Autodetected from `replay_trusted_match_context_vector`; absent\n   *     harnesses grade not_applicable. Spec: adcp-client#2479.\n   *   - `trusted_match_publisher_auth_runner` — the operator supplies exact\n   *     publisher-facing Context/Identity URLs and declarative absent/invalid\n   *     credential configuration. The SDK owns the guarded raw HTTPS probes.\n   *     Capability applicability is evaluated before this requirement, so a\n   *     non-TMP agent grades not_applicable rather than requirement_unmet.\n   *     Spec: adcp-client#2526.\n   *   - `request_signer` — the agent under test MUST advertise\n   *     `request_signing.supported: true` in `get_adcp_capabilities`.\n   *     Autodetected: any storyboard whose `id === 'signed_requests'`\n   *     or contains a `request_signing_probe` step implicitly requires\n   *     this. Skipped (storyboard not applicable) when the agent omits\n   *     the capability claim — absence is a declaration that the agent\n   *     does not offer verified signed requests, per\n   *     `compliance/{version}/universal/signed-requests.yaml` gating\n   *     (\"Agents that do not advertise support are not tested against\n   *     this storyboard — absence of advertisement is not a failure\").\n   *     Spec: adcp-client#1702.\n   *   - `multi_agent` — the run must be configured with\n   *     `StoryboardRunOptions.agents`, and the storyboard's authored\n   *     route keys (`default_agent` plus any step-level `agent:` overrides)\n   *     must resolve to at least two distinct entries in that agents map.\n   *     This checks the routed topology the storyboard actually declares,\n   *     not the raw number of available agents. Spec: adcp-client#2281.\n   *\n   * Default when the field is absent: `[real_wire]` (storyboard runs\n   * everywhere — matches existing pre-tagging behavior). Tagging is\n   * additive opt-in; loader rejects malformed values and an empty array\n   * (`requires: []`) so authoring mistakes fail loud. Unknown string\n   * requirements are forward-compatible: they load successfully, then skip\n   * at runtime with `skip_reason: 'requirement_unmet'` and the authored name\n   * on `RunnerSkipResult.requirement`.\n   *\n   * Spec: adcp-client#1626, adcp-client#2281. The schema may be proposed upstream to\n   * `adcontextprotocol/adcp` once it has bedded in across SDK\n   * storyboards.\n   */\n  requires?: string[];\n  /**\n   * Predicate evaluated against the agent's declared capabilities before any\n   * phase runs. When the predicate is false, the runner emits a single\n   * `{ skipped: true, skip_reason: 'capability_unsupported' }` storyboard\n   * result instead of running phases — avoiding misleading per-phase failures\n   * when the storyboard tests behavior the agent explicitly opted out of.\n   *\n   * `path` is a dotted key path into the raw `get_adcp_capabilities` response\n   * (e.g. `\"adcp.idempotency.supported\"`).\n   *\n   * Four matcher forms — mutually exclusive on a single gate:\n   *\n   * - `equals: V` — scalar equality. The path's resolved value must be\n   *   declared and must equal `V` for the storyboard to run. When the path\n   *   resolves to `undefined` (field absent), the storyboard is skipped as\n   *   `capability_unsupported` unless the `get_adcp_capabilities` response\n   *   schema declares a default for that exact path and the parent capability\n   *   object is present.\n   *\n   * - `present: true|false` — presence-only matcher for spec capabilities whose\n   *   contract is \"presence of this object indicates support\" (e.g.\n   *   `media_buy.conversion_tracking`). `present: true` requires the value at\n   *   `path` to exist (non-null, non-undefined); empty object `{}` counts as\n   *   present. `present: false` requires the value to be absent — useful for\n   *   scenarios that only apply to agents that explicitly do NOT advertise a\n   *   capability. Unlike `equals`, absence is the load-bearing signal: when\n   *   `present: true` and the field is missing, the storyboard is skipped\n   *   (not_applicable) rather than run, because the seller's silence is the\n   *   spec-defined opt-out. Schema defaults are NOT materialized for this\n   *   matcher (unlike `equals`/`contains`): a default would make a defaulted\n   *   field never read as absent, defeating the gate.\n   *\n   * - `contains: V` — array-membership matcher for capabilities whose\n   *   declaration shape is an array of allowed values (e.g.\n   *   `media_buy.conversion_tracking.supported_targets: [\"cost_per\",\n   *   \"per_ad_spend\"]`). The value at `path` MUST be an array and MUST include\n   *   `V` (structural JSON equality, no coercion). Empty arrays fail; paths resolving\n   *   to undefined or non-array values fail unless the `get_adcp_capabilities`\n   *   response schema declares a default for that exact path and the parent\n   *   capability object is present. Like `present:`, absence is otherwise the\n   *   load-bearing signal — a seller that doesn't advertise the array hasn't\n   *   opted into the variant this storyboard tests.\n   *\n   * - `not_contains: V` — negative array-membership matcher. The value at\n   *   `path` MUST be an array and MUST NOT include `V` (structural JSON equality, no\n   *   coercion). This is useful for rejection scenarios that apply only when\n   *   an advertised allowlist omits a value. Missing and non-array values do\n   *   not satisfy the predicate; a separate discovery validation should grade\n   *   a required capability declaration. Schema defaults are materialized on\n   *   the same terms as `contains`.\n   *\n   * When `raw_capabilities` is not available and the discovered profile does\n   * not expose `get_adcp_capabilities`, `equals` gates are treated as\n   * unsupported because there is no declaration proving the agent opted into\n   * the behavior. Other matcher forms remain a no-op without raw capabilities\n   * unless the storyboard contract explicitly requires a raw opt-in (currently\n   * `experimental_features contains trusted_match.core`).\n   */\n  requires_capability?: RequiresCapabilityPredicate;\n  /** Scenario IDs that must pass alongside this storyboard (loaded from storyboards/scenarios/) */\n  requires_scenarios?: string[];\n  agent: {\n    interaction_model: string;\n    capabilities: string[];\n    examples?: string[];\n  };\n  caller: {\n    role: string;\n    example?: string;\n  };\n  prerequisites?: {\n    description: string;\n    test_kit?: string;\n    /**\n     * When true and the storyboard carries a top-level `fixtures:` block,\n     * the runner fires `comply_test_controller` seed_* calls for each fixture\n     * entry before phase 1. Spec: adcontextprotocol/adcp#2585 (fixtures block)\n     * + adcontextprotocol/adcp#2584 (seed_* scenarios). Opts-out per run via\n     * `StoryboardRunOptions.skip_controller_seeding` (for agents that seed via\n     * tests or HTTP admin rather than the MCP controller).\n     */\n    controller_seeding?: boolean;\n  };\n  /**\n   * Fixture entries consumed by the runner's pre-flight controller seeding\n   * (see `prerequisites.controller_seeding`). Each entry is split into id\n   * params + a `fixture` body before being issued as a `seed_*` scenario on\n   * `comply_test_controller`. Entries are spec-shaped objects drawn from the\n   * source storyboard YAML; the runner preserves every field besides the id\n   * field(s) into `params.fixture` verbatim.\n   */\n  fixtures?: StoryboardFixtures;\n  /**\n   * AdCP 3.2 fixture-handle resolution policy. Fixture ids remain authored in\n   * `fixtures:` and in step payloads, but declarations here may allow the\n   * runner to bind those run-scoped handles to real seller catalog ids.\n   * Omitted handles retain the compatibility strategy `[\"seed\"]`.\n   */\n  fixture_resolution?: StoryboardFixtureResolution;\n  /**\n   * Initial context values declared by the storyboard YAML. Runner callers may\n   * override these defaults with `StoryboardRunOptions.context`.\n   */\n  context?: StoryboardContext;\n  phases: StoryboardPhase[];\n  /**\n   * Cross-step assertions that apply to this storyboard. Every assertion\n   * registered with `default: true` (the bundled set: `status.monotonic`,\n   * `idempotency.conflict_no_payload_leak`, `context.no_secret_echo`,\n   * `governance.denial_blocks_mutation`) runs by default — omit the field\n   * entirely and the full default set applies. Per-step checks live inline\n   * on steps; assertions encode specialism- or protocol-wide properties\n   * that must hold across the full run.\n   *\n   * Three shapes are accepted:\n   *   - `undefined` (or field omitted) — run every default-on assertion.\n   *   - `string[]` — legacy additive form. Defaults still run; any ids in\n   *     the list register on top for storyboards that want extra non-default\n   *     assertions registered by the consumer. Every id MUST resolve.\n   *   - `{ disable?: string[]; enable?: string[] }` — object form. `disable`\n   *     removes default-on assertions by id (typo-guarded: unknown ids throw\n   *     at runner start); `enable` adds non-default assertions registered by\n   *     the consumer on top.\n   *\n   * See `./assertions.ts` for the registry API and `./default-invariants.ts`\n   * for the bundled set.\n   */\n  invariants?: StoryboardInvariants;\n}\n\nexport interface RequiredToolFamily {\n  tools: [string, string, ...string[]];\n  rationale?: string;\n}\n\n/**\n * Storyboard-level invariants declaration. `undefined` / array / object\n * shapes all map onto the same \"resolve to AssertionSpec[]\" path in\n * `resolveAssertions(...)`. See `Storyboard.invariants` for the full\n * semantics (bundled defaults are always applied unless explicitly\n * disabled via the object form).\n */\nexport type StoryboardInvariants = string[] | StoryboardInvariantsObject;\n\nexport interface StoryboardInvariantsObject {\n  /**\n   * Default-on assertion ids to suppress for this storyboard. Each id MUST\n   * match an assertion registered with `default: true` — an unknown or\n   * non-default id is a typo and fails fast at runner start rather than\n   * silently no-opping (which would mask genuine coverage gaps).\n   */\n  disable?: string[];\n  /**\n   * Additional (non-default) assertion ids to enable for this storyboard on\n   * top of the default-on set. Consumers use this to attach custom\n   * assertions they've registered via `registerAssertion(...)`. Every id\n   * MUST resolve; unknown ids fail fast at runner start.\n   */\n  enable?: string[];\n}\n\n/**\n * Per-step invariant opt-out. Mirrors `StoryboardInvariantsObject.disable`\n * but scoped to a single step — the runner skips calling the named\n * assertions' `onStep` for that step only. Use when a step deliberately\n * models behavior a default invariant would otherwise flag (e.g. a\n * `check_governance` 200 `status: denied` setting up a buyer-recovery\n * sequence that the `governance.denial_blocks_mutation` invariant would\n * anchor).\n *\n * Step-level is narrower on purpose — there is no `enable`. Enabling an\n * assertion for a single step makes no sense at this scope (assertions\n * reason across steps), and disallowing it at the type level removes a\n * footgun. Only `disable` is accepted.\n *\n * Every id in `disable` MUST be in the assertion set resolved for this\n * run. An unknown id, or an id already suppressed storyboard-wide, is\n * dead code and fails fast at runner start rather than silently no-op.\n *\n * Semantics for stateful invariants: disable means the invariant does\n * not OBSERVE the step. Invariants that accumulate per-step state\n * (e.g. `status.monotonic`'s last-observed transition anchor) will\n * therefore miss any observation the disabling step would have\n * contributed. That's the point for `governance.denial_blocks_mutation`\n * (a deliberate setup is not an anchor); for accumulator-style\n * invariants, prefer disabling run-wide if the missed observation\n * would hide later violations.\n */\nexport interface StepInvariantsObject {\n  disable?: string[];\n}\n\n/**\n * Fixture entries the runner seeds into the seller via `comply_test_controller`\n * pre-flight (adcp#2585, adcp#2743). Each array entry carries its id field(s)\n * alongside the body the runner forwards into `params.fixture` for the\n * corresponding `seed_*` scenario.\n *\n *   - `accounts[]`      → `seed_account`         — requires `account_id`\n *   - `products[]`      → `seed_product`         — requires `product_id`\n *   - `pricing_options[]` → `seed_pricing_option` — requires `product_id` + `pricing_option_id`\n *   - `creative_formats[]` → `seed_creative_format` — requires `format_id`\n *   - `creatives[]`     → `seed_creative`        — requires `creative_id`\n *   - `plans[]`         → `seed_plan`            — requires `plan_id`\n *   - `media_buys[]`    → `seed_media_buy`       — requires `media_buy_id`\n *   - `buyer_agents[]`  → `seed_buyer_agent`     — requires `agent_url`\n *\n * For entity fixtures, every other field on the entry is forwarded verbatim\n * as `params.fixture`. For `buyer_agents[]`, every other field is forwarded\n * as a direct `params` field because the controller scenario models the\n * buyer-agent record itself (`billing_capabilities`, `status`, etc.).\n * Entries without their required id field produce a pre-flight error so the\n * authoring mistake is surfaced before any real step runs.\n */\nexport interface StoryboardFixtures {\n  accounts?: Array<Record<string, unknown> & { account_id?: string }>;\n  products?: Array<Record<string, unknown> & { product_id?: string }>;\n  pricing_options?: Array<Record<string, unknown> & { product_id?: string; pricing_option_id?: string }>;\n  creative_formats?: Array<Record<string, unknown> & { format_id?: string; fixture?: unknown }>;\n  creatives?: Array<Record<string, unknown> & { creative_id?: string }>;\n  plans?: Array<Record<string, unknown> & { plan_id?: string }>;\n  media_buys?: Array<Record<string, unknown> & { media_buy_id?: string }>;\n  buyer_agents?: StoryboardBuyerAgentFixture[];\n}\n\n/** Ordered setup strategies supported by the first AdCP 3.2 runner slice. */\nexport type FixtureResolutionStrategy = 'seed' | 'discover';\n\n/** Operators supported by the closed AdCP 3.2 fixture predicate DSL. */\nexport type FixtureMatchOperator = 'equals' | 'present' | 'contains_all' | 'any_match' | 'canonical_format_satisfies';\n\nexport interface FixtureCanonicalFormatSelector extends Record<string, unknown> {\n  format_kind: string;\n  params?: Record<string, unknown>;\n}\n\n/**\n * One fixture-discovery predicate. `path` is an RFC 6901 JSON Pointer\n * relative to the candidate entity. `any_match` uses `where` recursively,\n * `present` is valueless, and the remaining operators use `value`.\n */\nexport type FixtureMatchClause =\n  | { path: string; operator: 'equals'; value: unknown; where?: never }\n  | { path: string; operator: 'present'; value?: never; where?: never }\n  | { path: string; operator: 'contains_all'; value: unknown[]; where?: never }\n  | { path: string; operator: 'canonical_format_satisfies'; value: FixtureCanonicalFormatSelector; where?: never }\n  | { path: string; operator: 'any_match'; where: FixtureMatchClause[]; value?: never };\n\nexport interface FixtureResolutionDeclaration {\n  /** Authored run-scoped fixture handle. */\n  handle: string;\n  /** Ordered strategy ladder. Omission means `[\"seed\"]`. */\n  strategies?: FixtureResolutionStrategy[];\n  /** Requirements a discovered seller entity must satisfy. */\n  match?: FixtureMatchClause[];\n  /** Default false: one seller entity cannot satisfy two handles. */\n  allow_reuse?: boolean;\n}\n\nexport type ProductFixtureResolutionDeclaration = FixtureResolutionDeclaration;\n\nexport interface PricingOptionFixtureResolutionDeclaration extends FixtureResolutionDeclaration {\n  /** Parent authored product handle for root-level pricing-option declarations. */\n  product_handle: string;\n}\n\nexport interface StoryboardFixtureResolution {\n  products?: ProductFixtureResolutionDeclaration[];\n  pricing_options?: PricingOptionFixtureResolutionDeclaration[];\n}\n\nexport type FixtureResolutionStatus = 'resolved' | 'unsatisfied' | 'failed';\n\nexport interface FixtureResolutionAttempt {\n  strategy: FixtureResolutionStrategy;\n  disposition: 'resolved' | 'unavailable' | 'failed';\n  detail: string;\n  request?: Record<string, unknown>;\n  response?: unknown;\n}\n\n/** @deprecated Use FixtureResolutionAttempt. */\nexport type FixtureResolutionEvidence = FixtureResolutionAttempt;\n\n/** Machine-readable record emitted exactly once for every fixture handle. */\nexport interface FixtureResolutionRecord {\n  fixture_type: 'product' | 'pricing_option';\n  handle: string;\n  product_handle?: string;\n  requirements: FixtureMatchClause[];\n  strategies_attempted: FixtureResolutionAttempt[];\n  status: FixtureResolutionStatus;\n  strategy?: FixtureResolutionStrategy;\n  seller_ids?: {\n    product_id: string;\n    pricing_option_id?: string;\n  };\n}\n\n/** One storyboard-scoped coverage gap produced by fixture resolution. */\nexport interface FixtureResolutionCoverageGap {\n  reason: 'fixture_unsatisfied';\n  detail: string;\n  fixtures: Array<{\n    fixture_type: FixtureResolutionRecord['fixture_type'];\n    handle: string;\n    product_handle?: string;\n    requirements: FixtureMatchClause[];\n  }>;\n}\n\nexport interface StoryboardBuyerAgentFixture {\n  agent_url?: string;\n  display_name?: string;\n  status?: BuyerAgentStatus;\n  billing_capabilities?: BuyerAgentBillingMode[];\n  default_account_terms?: BuyerAgent['default_account_terms'];\n  allowed_brands?: string[];\n  aliases?: string[];\n  sandbox_only?: boolean;\n  [key: string]: unknown;\n}\n\nexport interface StoryboardPhase {\n  id: string;\n  title: string;\n  narrative?: string;\n  steps: StoryboardStep[];\n  /** When true, the phase is allowed to be skipped without failing the storyboard. */\n  optional?: boolean;\n  /**\n   * Predicate evaluated against the agent's declared capabilities before this\n   * phase is set up or any of its steps are dispatched. Uses the same matcher\n   * dialect as `Storyboard.requires_capability` (`equals`, `present`,\n   * `contains`). When false, every step in the phase is emitted as a\n   * `not_applicable` skip and the runner continues with later phases.\n   */\n  requires_capability?: RequiresCapabilityPredicate;\n  /**\n   * Phases this phase depends on for stateful cascade purposes (#1161).\n   *\n   * When ANY listed phase tripped its stateful cascade (a stateful step\n   * failed or skipped for a missing-state reason), every stateful step in\n   * THIS phase cascade-skips with `prerequisite_failed`. When all listed\n   * phases passed their stateful steps, this phase runs normally even if\n   * other unrelated phases tripped — the runner treats independent phases\n   * independently.\n   *\n   * **Default semantics (field absent or undefined): \"all prior phases.\"**\n   * Backward-compatible with the storyboard-scope cascade behavior that\n   * predates #1161 — every phase implicitly depends on every prior phase.\n   * The F6 round-2 cross-phase pattern (e.g. `signal_marketplace/\n   * governance_denied`: setup in phases 1-2, consumption in phase 3) is\n   * preserved without YAML changes.\n   *\n   * **Independent phase: `depends_on: []`** — explicitly declares this\n   * phase has no upstream dependencies and will run even if every prior\n   * phase tripped its cascade. Use for phases whose state derives from\n   * the request body alone (e.g., `audience_sync` carrying its own\n   * account ref via brand+operator) rather than from prior phase state.\n   *\n   * **Targeted dependency: `depends_on: ['phase_id', ...]`** — only the\n   * named phases gate this phase's cascade. Other phases tripping is\n   * irrelevant.\n   *\n   * Listed phase IDs MUST exist in the same storyboard and MUST be\n   * declared earlier in the `phases[]` array (forward references and\n   * self-references are rejected at parse time). Empty list is legal and\n   * means \"no dependencies.\"\n   */\n  depends_on?: string[];\n  /**\n   * Skip expression evaluated against the runtime context. Current grammar:\n   *   - `\"!test_kit.auth.api_key\"` — true when field is missing/falsy\n   *   - `\"test_kit.auth.api_key\"`  — true when field is present/truthy\n   * Other expressions are rejected (unknown → fail closed: phase runs).\n   */\n  skip_if?: string;\n  /**\n   * First-class branch-set declaration (see adcp#2633 / adcp#2646). When\n   * present, contributing steps inside this phase MAY use the boolean\n   * shorthand `contributes: true` in lieu of repeating `contributes_to: <id>`.\n   * The loader resolves the shorthand to `branch_set.id` at parse time, so\n   * downstream runner code continues to read `step.contributes_to`.\n   */\n  branch_set?: BranchSetSpec;\n}\n\nexport interface BranchSetSpec {\n  /** Aggregation flag shared by every contributing step in this phase. */\n  id: string;\n  /**\n   * Grading semantics for the branch set. `any_of` (the only value defined\n   * today) means: at most one peer branch is expected to contribute; failures\n   * in non-contributing peers grade as `peer_branch_taken` rather than\n   * `failed`. Kept as a string so future semantics (`all_of`, `one_of`) do\n   * not require a type change.\n   */\n  semantics: string;\n}\n\nexport interface ContextOutput {\n  /**\n   * JSON path to extract from the response. Mutually exclusive with\n   * `generate` — exactly one of `path` or `generate` must be set.\n   */\n  path?: string;\n  /**\n   * Generator name. When set, the runner mints a fresh opaque value\n   * once per run (or reuses a value already minted for the same `key`\n   * alias via an inline `$generate:…#<alias>` substitution in the same\n   * step's `sample_request`). Mutually exclusive with `path`. The loader\n   * rejects unknown values at storyboard-load time so typos fail loud\n   * before the first run.\n   */\n  generate?: 'uuid_v4' | 'opaque_id';\n  /** Key to store the extracted or generated value under in context */\n  key: string;\n}\n\nexport interface ContextInput {\n  /** Key to look up in context */\n  key: string;\n  /** JSON path in the request to inject the value at */\n  inject_at: string;\n}\n\n/**\n * Per-step authentication override. Lets a step probe the agent with\n * different credentials than the rest of the run — required for the\n * `security_baseline` storyboard's unauthenticated and invalid-key probes.\n */\nexport type StepAuthDirective =\n  /** Strip transport credentials entirely. The step MUST hit the agent unauthenticated. */\n  | 'none'\n  | {\n      type: 'api_key';\n      /** Literal Bearer value sent as `Authorization: Bearer <value>`. */\n      value?: string;\n      /** Pull the value from the runtime `test_kit.auth.api_key` field. */\n      from_test_kit?: boolean;\n      /**\n       * Runner-generated value. Current strategies:\n       *   - `random_invalid` — `invalid-<32 hex bytes>`, fresh per run.\n       */\n      value_strategy?: 'random_invalid';\n    }\n  | {\n      type: 'oauth_bearer';\n      /** Literal Bearer value. */\n      value?: string;\n      /**\n       * Runner-generated value. Current strategies:\n       *   - `random_invalid_jwt` — three base64url segments; valid JSON header/payload, random signature.\n       */\n      value_strategy?: 'random_invalid_jwt';\n    }\n  | {\n      type: 'basic';\n      /** Pull the Basic credential object from the runtime test kit, e.g. `auth.basic`. */\n      from_test_kit?: string | boolean;\n      /** Explicit username. Mutually exclusive with `credentials`. */\n      username?: string;\n      /** Explicit password. Mutually exclusive with `credentials`. */\n      password?: string;\n      /** Unencoded `username:password` pair. Mutually exclusive with `username`/`password`. */\n      credentials?: string;\n      /** Nested Basic credential shape accepted for authoring parity with test kits. */\n      basic?: {\n        username?: string;\n        password?: string;\n        credentials?: string;\n      };\n      /**\n       * Runner-generated value. Current strategies:\n       *   - `random_invalid` — random username/password pair.\n       */\n      value_strategy?: 'random_invalid';\n    };\n\nexport interface StoryboardStep {\n  id: string;\n  title: string;\n  narrative?: string;\n  /**\n   * AdCP task name (snake_case), e.g. \"sync_accounts\", \"get_products\".\n   * May reference a test-kit field with `\"$test_kit.<path>\"` — the runner\n   * resolves to the value at that path, or to `task_default` when the kit\n   * doesn't supply the field.\n   */\n  task: string;\n  /** Fallback task name when `task` is a `$test_kit.*` reference that resolves to null/undefined. */\n  task_default?: string;\n  /**\n   * Explicit per-step routing for multi-agent runs\n   * (`StoryboardRunOptions.agents`). Must reference a key in the agents\n   * map; the runner sends this step to that agent regardless of\n   * `TASK_FEATURE_MAP` resolution.\n   *\n   * This is the canonical primitive for cross-specialism storyboards —\n   * NOT just an escape hatch. A `signal_marketplace/governance_denied`\n   * storyboard NEEDS `agent: governance` on its `sync_governance` step\n   * and `agent: signals` on its `activate_signal` step because those\n   * tools are owned by different specialisms; protocol-based routing\n   * resolves them automatically when the agents map has unique\n   * claimants, but explicit `agent:` is the documentation-friendly form\n   * for storyboard authors who want the routing intent visible at the\n   * step level.\n   *\n   * Also used to disambiguate cross-domain tools (`sync_creatives`,\n   * `list_creative_formats`) when the agents map has multiple claimants\n   * for the same specialism and the runner's protocol-index can't pick\n   * one. Ignored when `agents` is unset. Adcp-client#1066.\n   */\n  agent?: string;\n  schema_ref?: string;\n  response_schema_ref?: string;\n  doc_ref?: string;\n  /** Maps to existing @adcp/sdk test scenario (legacy, partial coverage) */\n  comply_scenario?: string;\n  /**\n   * Select the SDK response projection used for this step. `raw` is reserved\n   * for compatibility storyboards that must grade both legacy and canonical\n   * fields from the same seller response without changing the request wire.\n   */\n  response_projection?: 'raw';\n  /** Whether this step depends on state from a previous step */\n  stateful?: boolean;\n  /**\n   * Declares that this step's pass establishes equivalent state for one or\n   * more peer steps in the same phase. When a target peer skips with\n   * `missing_tool` or `missing_test_controller` (no advertised tool),\n   * the runner defers the cascade and waives it iff this substitute step\n   * passes. Same-phase only; cross-phase substitution is not supported.\n   *\n   * Canonical case: `list_accounts` declares `provides_state_for:\n   * sync_accounts` on explicit-mode social platforms where the buyer never\n   * calls `sync_accounts` because accounts are pre-provisioned out-of-band.\n   *\n   * Without this declaration, a `missing_tool` skip on a stateful step\n   * trips the cascade immediately (state genuinely never materialized).\n   * With it, the runner gives a declared substitute a chance to establish\n   * equivalent state before tripping. When the rescue fires, the target\n   * peer is graded with `skip_reason: 'peer_substituted'` and detail\n   * `\"<target_step_id> state provided by <phase_id>.<substitute_step_id>\"`\n   * per `runner-output-contract.yaml`.\n   *\n   * Use `string[]` for the bulk case (`provides_state_for: [A, B]` is\n   * ALL-OF — one substitute pass establishes state for both A and B).\n   *\n   * Spec source: `compliance/cache/{version}/universal/storyboard-schema.yaml`\n   * (adcp#3734, AdCP 3.0.3+).\n   */\n  provides_state_for?: string | string[];\n\n  /**\n   * @deprecated Renamed to `provides_state_for` to align with the AdCP 3.0.3\n   * spec field (adcp#3734). The old name is still accepted at parse time for\n   * one minor cycle. New storyboards SHOULD use `provides_state_for`. Slated\n   * for removal in the next major.\n   */\n  peer_substitutes_for?: string | string[];\n  /** When true, the step passes if the task returns an error */\n  expect_error?: boolean;\n  /**\n   * Per-step invariant opt-out. See `StepInvariantsObject`. Use when a\n   * specific step deliberately trips a default invariant (e.g. a\n   * `check_governance` 200 `status: denied` that is the setup for a\n   * buyer-recovery sequence, which `governance.denial_blocks_mutation`\n   * would otherwise anchor for the remainder of the run).\n   */\n  invariants?: StepInvariantsObject;\n  /**\n   * When true, suppress the runner's `idempotency_key` auto-injection on a\n   * mutating step so the storyboard can exercise the server's missing-key\n   * rejection path. The runner also disables the SDK's client-side\n   * auto-inject for this step so the request reaches the wire without a key.\n   *\n   * Default (false) matches buyer-agent behavior: every mutating request\n   * carries a fresh UUID v4 so handlers under test run against the actual\n   * error path the storyboard names (GOVERNANCE_DENIED, UNAUTHORIZED, etc.)\n   * rather than short-circuiting on `INVALID_REQUEST: idempotency_key`.\n   */\n  omit_idempotency_key?: boolean;\n  /**\n   * When true, suppress the runner's `account` auto-injection on a\n   * `create_media_buy` step so the storyboard can exercise the server's\n   * missing-account rejection path. Without this flag the runner's\n   * `applyBrandInvariant` synthesises an `account` field before the wire\n   * call (both the natural-key-merge branch and the synthetic-construction\n   * branch), and the SDK's client-side normalizer also throws before the\n   * wire call — both layers are suppressed so the seller sees the request\n   * exactly as authored in `sample_request`.\n   *\n   * Only applicable to `create_media_buy` (the sole tool where `account` is\n   * required by `normalizeRequestParams`). Setting it on any other task type\n   * has no effect and is ignored.\n   *\n   * **Caveat:** this flag does not suppress `account` enrichment performed by\n   * `request-builder.ts` for tasks such as `update_media_buy`. If a future\n   * storyboard step needs to test missing-account rejection on a\n   * request-builder-enriched task, the builder will also need updating.\n   *\n   * Must be paired with `expect_error: true` — the loader rejects steps that\n   * set `omit_account: true` without the flag, because an accountless\n   * `create_media_buy` will always fail and a missing `expect_error` produces\n   * a misleading compliance result.\n   *\n   * Default (false) matches buyer-agent behavior: every `create_media_buy`\n   * request carries an `account` so handlers under test run against the\n   * actual error path the storyboard names rather than short-circuiting on\n   * `INVALID_REQUEST: account`.\n   *\n   * @internal Do not set in production buyer code.\n   */\n  omit_account?: boolean;\n  /** Tool name required for this step to run. Skipped if agent lacks it. */\n  requires_tool?: string;\n  /** Explicit context extraction rules (supplements convention-based extractors) */\n  context_outputs?: ContextOutput[];\n  /** Explicit context injection rules (supplements $context.key placeholders) */\n  context_inputs?: ContextInput[];\n  expected?: string;\n  sample_request?: Record<string, unknown>;\n  sample_response?: Record<string, unknown>;\n  /**\n   * Response-derived gates evaluated after the step's request completes but\n   * before validations/context captures run. Use when applicability is only\n   * knowable from the observed response, not from static capabilities.\n   *\n   * Current gate kind:\n   *   - `terminal_page`: if the response proves the requested page is terminal,\n   *     grade the step `not_applicable` instead of failing continuation-only\n   *     assertions. This supports pagination-walk storyboards for sellers whose\n   *     full result set fits in one page.\n   */\n  not_applicable_if?: ResponseNotApplicableGate | ResponseNotApplicableGate[];\n  validations?: StoryboardValidation[];\n  /** Override auth for this step only (see `StepAuthDirective`). */\n  auth?: StepAuthDirective;\n  /** Contribute a flag to the run-level accumulator on success. Used with `any_of` validations downstream. */\n  contributes_to?: string;\n  /**\n   * Boolean shorthand for `contributes_to: <enclosing phase's branch_set.id>`.\n   * Only legal inside a phase that declares `branch_set:`. The loader\n   * resolves `contributes: true` to the phase's `branch_set.id` and clears\n   * this field, so runner code reads `contributes_to` exclusively.\n   * `contributes: false` (or absent) marks a non-contributing step.\n   * Declaring both `contributes` and `contributes_to` on the same step is a\n   * parse-time authoring error.\n   */\n  contributes?: boolean;\n  /**\n   * Conditional contribution expression. Current grammar:\n   *   - `\"prior_step.<step_id>.passed\"` — contribution fires only if the named step passed.\n   * Unknown expressions → the contribution does NOT fire (fail closed).\n   */\n  contributes_if?: string;\n  // ──────────────────────────────────────────────────────────\n  // Webhook-assertion step fields (only used when task is one\n  // of `expect_webhook`, `expect_no_webhook`,\n  // `expect_webhook_retry_keys_stable`, or\n  // `expect_webhook_signature_valid`). The runner interprets\n  // these pseudo-tasks as receiver observations, not agent calls.\n  // ──────────────────────────────────────────────────────────\n  /**\n   * Step id of the earlier step whose task triggered the webhook under\n   * observation. Used by compliance reports for attribution and (when the\n   * trigger step failed / skipped) to gate the assertion skip.\n   */\n  triggered_by?: string;\n  /** Match predicate scoped to the per-step URL and/or body fields. */\n  filter?: WebhookFilterSpec;\n  /** Seconds to observe for a matching delivery. Default 5 for `expect_no_webhook`, otherwise 30. */\n  timeout_seconds?: number;\n  /** When true (default) assert `idempotency_key` is present and pattern-valid. */\n  expect_idempotency_key?: boolean;\n  /** Optional webhook schema reference; validates the parsed body. */\n  webhook_payload_schema_ref?: string;\n  /** Back-compat alias for older local storyboards. Prefer `webhook_payload_schema_ref`. */\n  response_schema_webhook_ref?: string;\n  /**\n   * Cap on the number of distinct logical webhook events (grouped by\n   * idempotency_key) delivered within the timeout window. Typical use:\n   * `1` on the replay-side-effect invariant to catch publishers that\n   * re-execute on replay and emit a second webhook under a fresh key.\n   */\n  expect_max_deliveries_per_logical_event?: number;\n  /**\n   * Test-kit contract id this assertion depends on. When the contract is\n   * not in scope the step grades `not_applicable` rather than failing —\n   * lets cross-cutting storyboards (idempotency, governance) reference\n   * webhook assertions without forcing every runner to host a receiver.\n   */\n  requires_contract?: string;\n  /** Retry-replay config for `expect_webhook_retry_keys_stable`. */\n  retry_trigger?: WebhookRetryTriggerSpec;\n  /** Min deliveries to observe for `expect_webhook_retry_keys_stable`. Default 2. */\n  expect_min_deliveries?: number;\n  /** Signature-tag sanity check for `expect_webhook_signature_valid`. Default `adcp/webhook-signing/v1`. */\n  require_tag?: string;\n  // ──────────────────────────────────────────────────────────\n  // Webhook receiver replay step fields (only used when task is\n  // `replay_webhook_vector`). The runner sends a canonical webhook POST to\n  // a buyer/orchestrator receiver under test; it does not call the seller.\n  // ──────────────────────────────────────────────────────────\n  /** Compliance vector reference, e.g. `static/test-vectors/webhook-receiver-envelope.json#positive/foo`. */\n  vector_ref?: string;\n  /** Earlier step id that represents the same logical event retry. */\n  same_event_as?: string;\n  /** Expected receiver error label from the vector metadata, when present. */\n  expected_error?: string;\n  /**\n   * Fan-out spec for parallel-dispatch steps. When set, the runner fires\n   * `count` concurrent dispatches of this step (single-process,\n   * `Promise.all`) against the same agent, then aggregates per-response\n   * checks across the resolved set and grades the `cross_response_*`\n   * checks declared in `validations`. Requires the\n   * `parallel_dispatch_runner` test-kit contract to be in scope — runners\n   * (or runs) without it grade the step `not_applicable`. See\n   * {@link ParallelDispatchSpec}.\n   */\n  parallel_dispatch?: ParallelDispatchSpec;\n  /**\n   * Sequential rate-limit trip/replay probe config. When set on\n   * `expect_rate_limit_not_replayed`, the runner sends fresh-key requests\n   * until the seller returns `RATE_LIMITED`, waits the response\n   * `retry_after`, then replays the same idempotency key to assert the\n   * transient rate-limit response was not cached as the canonical replay.\n   * Requires the `rate_limit_trip_runner` test-kit contract.\n   */\n  rate_limit_trip?: RateLimitTripSpec;\n}\n\n/**\n * Contract payload for `test-kits/rate-limit-trip-runner.yaml`.\n */\nexport interface RateLimitTripSpec {\n  /** Mutating AdCP task to burst, e.g. `create_media_buy`. */\n  trip_target_task: string;\n  /** Base request payload; the observer rewrites only idempotency_key and correlation_id. */\n  trip_target_sample_request: Record<string, unknown>;\n  /** Sequential fresh-key attempts before grading the probe `rate_limit_not_triggered`; must be in [50, 500]. */\n  max_attempts: number;\n  /** Maximum retry_after wait the runner will honor. Defaults to 30 seconds. */\n  replay_max_wait_seconds?: number;\n}\n\nexport type StoryboardValidationCheck =\n  | 'response_schema'\n  | 'field_present'\n  | 'field_absent'\n  // Envelope-scoped variants — the asserted path lives on the v3 protocol\n  // envelope (`status`, `task_id`, `message`, `replayed`, `governance_context`,\n  // `timestamp`, `context_id`, `push_notification_config`) rather than the\n  // inner response. Runtime semantics are identical to the un-prefixed checks\n  // (TaskResult merges envelope fields onto its surface); the distinction is\n  // for static drift detection, which walks `protocol-envelope.json` instead\n  // of the per-tool response schema. Added per adcp#3429.\n  | 'envelope_field_present'\n  | 'envelope_field_absent'\n  | 'envelope_field_value'\n  | 'envelope_field_value_or_absent'\n  | 'field_value'\n  | 'field_value_or_absent'\n  /**\n   * Assert that a string field in the task payload matches a JavaScript\n   * regular expression source declared in `pattern`. Fails when the path is\n   * missing, the value is not a string, the pattern is invalid, or the regex\n   * does not match. Failure output carries `expected: { pattern }` and\n   * `actual` as the observed value (or null when missing). Added for\n   * runner-output-contract v2.5.0.\n   */\n  | 'field_pattern'\n  /**\n   * Envelope-scoped `field_pattern`. The path resolves against the union of\n   * protocol-envelope fields (`status`, `task_id`, etc.) and string-valued\n   * version-envelope fields such as `adcp_version`. Runtime matching is the\n   * same as `field_pattern`; the distinct kind lets static linting validate\n   * against the envelope schemas instead of the task payload schema. Numeric\n   * envelope fields such as `adcp_major_version` should use\n   * `envelope_field_value`.\n   */\n  | 'envelope_field_pattern'\n  // Wildcard-aware membership check. `path` may include `[*]` or `[]`\n  // segments that expand to every array element via `resolvePathAll`.\n  // Passes when ANY resolved value matches `value` (or any of\n  // `allowed_values`). Object and array expectations are matched as deep\n  // subsets, so storyboards can assert keyed entries inside unordered arrays\n  // without hardcoding positions — e.g.,\n  // `creatives[0].errors[*].code = PROVENANCE_DISCLOSURE_MISSING` or\n  // `products[0].allowed_actions[]` with\n  // `{ action: \"increase_budget\", modes: [\"self_serve\"] }`.\n  // When the path has no wildcard segments this reduces to scalar equality\n  // / array membership depending on what the path resolves to.\n  | 'field_contains'\n  | 'status_code'\n  | 'error_code'\n  // HTTP-probe checks (for raw_probe tasks)\n  | 'http_status'\n  | 'http_status_in'\n  | 'on_401_require_header'\n  // Cross-cutting\n  | 'resource_equals_agent_url'\n  | 'oauth_metadata_graph'\n  | 'any_of'\n  // A2A wire-shape checks (transport-specific; skipped on non-A2A runs)\n  | 'a2a_submitted_artifact'\n  | 'a2a_context_continuity'\n  // Cross-step checks\n  | 'refs_resolve'\n  /**\n   * Assert a numeric field in the current step's response is strictly less than\n   * a comparand. The comparand is either a context-captured runtime value\n   * (`context_key` on `StoryboardValidation`) or a literal number (`value`).\n   * Fails with a type error when either operand is non-numeric or absent.\n   * When `context_key` is specified but the key is absent from `storyboardContext`,\n   * the check passes with a `context_key_absent` observation (prior step may have\n   * been legitimately skipped on a branch-set path).\n   * Added for adcp#2642 cross-step comparison primitives.\n   */\n  | 'field_less_than'\n  /**\n   * Assert a numeric field in the current step's response is strictly greater\n   * than a comparand. Mirror of `field_less_than` — completes the four-quadrant\n   * numeric comparison vocabulary (`<`, `<=`, `>=`, `>`). Same operand and\n   * `context_key_absent` semantics as `field_less_than`. Added for\n   * adcp-client#1839 four-quadrant symmetry.\n   */\n  | 'field_greater_than'\n  /**\n   * Assert a numeric field in the current step's response is at most (≤) a\n   * comparand. Semantically symmetric with `field_less_than` but with\n   * non-strict comparison — pairs cleanly with cap-style assertions like\n   * \"observed frequency stays at or below the requested cap of 3\".\n   * The comparand is either a context-captured runtime value (`context_key`)\n   * or a literal number (`value`). Fails with a type error when either\n   * operand is non-numeric or absent. When `context_key` is specified but\n   * absent from `storyboardContext`, passes with a `context_key_absent`\n   * observation. Added for adcp-client#1839.\n   */\n  | 'field_at_most'\n  /**\n   * Assert a numeric field in the current step's response is at least (≥) a\n   * comparand. Mirror of `field_at_most` — pairs with floor-style assertions\n   * like \"delivered reach ≥ promised reach\". Same operand and\n   * context_key_absent semantics as `field_at_most`. Added for\n   * adcp-client#1839.\n   */\n  | 'field_at_least'\n  /**\n   * Assert a field in the current step's response deep-equals a value captured\n   * from an earlier step via `context_key`. Unlike `field_value` + `$context.key`\n   * substitution (which resolves the comparand at YAML authoring time), this\n   * check compares against a runtime-captured value — suitable for asserting that\n   * a response echoes back an id or token that was only known at run time.\n   * When `context_key` is absent from `storyboardContext`, passes with a\n   * `context_key_absent` observation.\n   * Added for adcp#2642 cross-step comparison primitives.\n   */\n  | 'field_equals_context'\n  /**\n   * Assert a field in the current response is a member of an array captured\n   * from an earlier step via `context_key`. Missing context keeps the same\n   * branch-safe `context_key_absent` behavior as other cross-step checks;\n   * a present non-array context value fails the check.\n   */\n  | 'field_in_context_array'\n  /**\n   * Resolve every terminal value at a wildcard-aware response path and require\n   * each value to deep-equal a member of a context-captured array. An empty\n   * terminal set passes vacuously; missing context is branch-safe.\n   */\n  | 'all_fields_in_context_array'\n  /**\n   * Asserts upstream side-effects against the adopter's\n   * `comply_test_controller`'s `query_upstream_traffic` scenario. The\n   * load-bearing anti-façade contract: a fully-conformant adapter and a\n   * façade returning shape-valid AdCP responses with synthetic data are\n   * indistinguishable on the AdCP wire — only what the adapter caused\n   * upstream tells them apart. Adopters who do not advertise\n   * `query_upstream_traffic` in `list_scenarios` grade the check\n   * `not_applicable`. Adopters who do but return zero recorded calls in\n   * the assertion window grade `failed` (the façade signal). Spec:\n   * runner-output-contract.yaml v2.0.0, storyboard-schema.yaml >\n   * \"upstream_traffic\".\n   */\n  | 'upstream_traffic'\n  /** Contract check for `rate_limit_trip_runner`: RATE_LIMITED must not replay from the idempotency cache. */\n  | 'replay_not_cached_rate_limit'\n  /**\n   * Cross-response: every resolved response from a `parallel_dispatch` step\n   * carries the same value at the named `path`. Used to assert\n   * first-insert-wins on a concurrent retry — two parallel `create_media_buy`\n   * calls with the same `idempotency_key` must resolve to the same\n   * `media_buy_id`. Fails when any two resolved responses disagree, or when\n   * fewer than 2 dispatches resolved successfully. Spec:\n   * test-kits/parallel-dispatch-runner.yaml; adcp#4435 (rule 9 / rule 10).\n   */\n  | 'cross_response_field_equal'\n  /**\n   * Cross-response: the cardinality of distinct values at `path` across all\n   * resolved responses from a `parallel_dispatch` step is in\n   * `allowed_values`. Used to assert \"exactly one resource was created\" —\n   * `allowed_values: [1]` with `path: media_buy_id` catches a seller that\n   * raced the INSERT and created two resources from one logical create.\n   * Fails when the distinct count is outside `allowed_values`, or when no\n   * dispatch resolved successfully. Spec:\n   * test-kits/parallel-dispatch-runner.yaml.\n   */\n  | 'cross_response_count_distinct'\n  /**\n   * Assert that the `create_media_buy` package format selector outcome matches\n   * canonical product capability satisfaction rules. `value: true` means the\n   * request should be accepted because its selector satisfies the product's\n   * `format_options[]`; `value: false` means the request should be rejected\n   * because the selector does not satisfy those constraints.\n   *\n   * The validator uses the actual runner request plus prior `get_products`\n   * context. It normalizes legacy `format_ids[]` through product\n   * `v1_format_ref[]` / the v1→canonical projection path, resolves canonical\n   * `format_option_refs[]`, and checks directional containment for dimensions,\n   * sizes, duration declarations, and remaining canonical params. Negative\n   * cases only pass on a format-specific rejection, so unrelated auth or tenant\n   * failures do not mask selector bugs. Failure output names the likely bug\n   * class: normalization, directionality, or range containment. Added for\n   * adcp-client#2060.\n   */\n  | 'canonical_format_satisfaction'\n  /**\n   * Assert the cardinality of the array at `path`. Two configurations are\n   * supported: exact-count via `value: N` (passes only when the resolved\n   * array has exactly N entries) and range via `min` / `max` (either bound\n   * is optional; both inclusive). Specifying both `value` and `min`/`max` is\n   * rejected as a misconfigured check; so are non-integer, negative, NaN,\n   * or impossible (`min > max`) operands. Fails with a type error when the\n   * resolved path is absent or not an array — `field_present` paired with\n   * `field_value_or_absent value: null` is unsound for cardinality because\n   * it passes when a seller emits a literal-null pad at `arr[N]`.\n   *\n   * **Non-optional by design.** This check has no tolerant arm — an absent\n   * path fails. Use `field_value_or_absent` (or omit the check) when the\n   * field itself is spec-optional; `array_length` is for asserting the\n   * cardinality of an array that MUST be present.\n   *\n   * Spec: adcp#4685 (cardinality assertions); SDK adcp-client#1830.\n   */\n  | 'array_length';\n\n/**\n * Configuration for a step that fans out to N concurrent dispatches against\n * the same agent, returning the cross-response set for assertion. Drives the\n * `concurrent_retry` phase of the idempotency storyboard (rule 9 /\n * first-insert-wins), where two `create_media_buy` calls with the same\n * `idempotency_key` race the seller's INSERT and must resolve to one\n * resource.\n *\n * Modes:\n *   - `process_local` (default): fire all dispatches via `Promise.all`\n *     through the SDK's batch primitive before awaiting any response.\n *     Single-process, event-loop concurrent — sufficient to exercise the\n *     seller's INSERT race per the contract YAML's\n *     `not_required_to_synthesize_packet_schedule` note.\n *   - `distributed` (future): barrier-synced workers across processes for\n *     true network-level concurrency. Defers to a later spec phase; runners\n *     that do not implement it grade the step `not_applicable`.\n *\n * Spec source: `test-kits/parallel-dispatch-runner.yaml`.\n */\nexport interface ParallelDispatchSpec {\n  /**\n   * How many parallel dispatches to fire. Per spec, `count_min: 2`,\n   * `count_max: 10`. Values outside that range are rejected at run time as a\n   * `parallel_dispatch_misconfigured` step error rather than silently clamped.\n   */\n  count: number;\n  /**\n   * When `true` (default), every dispatch shares the same fresh\n   * `idempotency_key` (the runner mints one UUID and reuses it across the\n   * fan-out). When `false`, every dispatch gets its own fresh key — useful\n   * for soak tests that need parallelism without the race semantics.\n   */\n  same_idempotency_key?: boolean;\n  /**\n   * Maximum total wall-clock time, in milliseconds, the runner waits for all\n   * dispatches to resolve (including any IDEMPOTENCY_IN_FLIGHT retries).\n   * Defaults to `5000`. A dispatch that doesn't terminate within the budget\n   * is marked timed-out; the step grades the surviving set and reports\n   * `parallel_dispatch_barrier_timeout` for the missing arms.\n   */\n  barrier_timeout_ms?: number;\n  /**\n   * Dispatch coordination mode (see interface JSDoc). Defaults to\n   * `'process_local'`.\n   */\n  mode?: 'process_local' | 'distributed';\n}\n\n/**\n * A response-derived step-level not-applicable gate. Kept data-driven so new\n * storyboards can opt in without runner-specific hardcoding.\n */\nexport type ResponseNotApplicableGate = TerminalPageNotApplicableGate;\n\nexport interface TerminalPageNotApplicableGate {\n  kind: 'terminal_page';\n  /**\n   * Array path in the response whose length is compared to the request page\n   * size, e.g. `accounts`, `creatives`, or `formats`.\n   */\n  items_path: string;\n  /**\n   * Path in the request that carries the requested page size. Defaults to\n   * `pagination.max_results`.\n   */\n  request_max_results_path?: string;\n  /**\n   * Optional label prefixed onto skip.detail. Defaults to\n   * `single_page_result`.\n   */\n  reason?: string;\n  /** Optional human-readable detail override for skip.detail. */\n  detail?: string;\n  /**\n   * Context keys whose missing captures should cause downstream consumer\n   * steps to skip as `not_applicable` instead of `prerequisite_failed`.\n   * When omitted, the runner infers keys from context_outputs whose paths\n   * read `pagination.cursor`.\n   */\n  context_keys?: string[];\n}\n\n/**\n * Path/value match predicate for `upstream_traffic.payload_must_contain`.\n * Each entry asserts a JSONPath (`$.users[*].hashed_email`) and a match\n * mode against the recorded call's payload.\n */\nexport interface UpstreamTrafficPayloadMatch {\n  /** JSONPath into recorded_calls[].payload. */\n  path: string;\n  /** Match mode: `present` checks the path resolves; `equals` compares; `contains_any` checks list membership. */\n  match: 'present' | 'equals' | 'contains_any';\n  /** Expected value when `match: equals`. */\n  value?: unknown;\n  /** Allowed values when `match: contains_any`. */\n  allowed_values?: unknown[];\n}\n\n/**\n * Captured A2A wire shape from a `message/send` JSON-RPC response. The\n * runner records this when the protocol is `a2a` and a step's tool\n * dispatch went through the SDK client; A2A wire-shape validations\n * (`a2a_submitted_artifact`) consume it. Absent on MCP runs and on A2A\n * runs where the capture didn't fire (raw probe path, fetch error).\n *\n * The `result` field is typed as `unknown` because the JSON-RPC\n * envelope is observed at the wire — the validation engine narrows it\n * (e.g. asserting `kind === 'task'`) and reports specific failures\n * when the shape doesn't match. Doing the narrowing in the type would\n * lock callers into a specific A2A SDK version; doing it in the\n * validator preserves the runner's \"report what you saw\" contract.\n *\n * **Redaction posture.** The runner runs `redactSecrets` over `result`\n * and `envelope` before populating this struct, matching the\n * redaction the runner applies to `RunnerResponseRecord.payload` on\n * the success path. AdCP-style secret-shaped fields inside the\n * DataPart payload (`api_key`, `client_secret`, `access_token`, etc.)\n * are replaced with `[redacted]`; bearer-token substrings in raw\n * bodies were already redacted at fetch-capture time. Custom\n * validators reading this field don't need to re-redact, but SHOULD\n * avoid logging it through other channels (LLM context, debug sinks,\n * third-party telemetry) without confirming the same redaction\n * posture is acceptable for that channel.\n */\nexport interface A2ATaskEnvelope {\n  /**\n   * Parsed JSON-RPC `result` field — typically an A2A `Task`\n   * (`{ kind: 'task', id, status: { state }, artifacts: [...] }`) on\n   * success. Absent (set to `null`) when the JSON-RPC response was an\n   * error envelope; consumers should also inspect `envelope.error`.\n   */\n  result: unknown;\n  /**\n   * Full JSON-RPC envelope (`{ jsonrpc, id, result?, error? }`).\n   * Useful for assertions that need to distinguish a JSON-RPC error\n   * from a success-with-failure-task (e.g. `Task.state === 'failed'`\n   * is success-with-failure; `error.code === -32602` is a JSON-RPC\n   * error).\n   */\n  envelope: { jsonrpc?: unknown; id?: unknown; result?: unknown; error?: unknown };\n  /** HTTP status of the captured response (200 on JSON-RPC success). */\n  http_status: number;\n}\n\n/**\n * Set of references for `refs_resolve`. `from` picks the root object —\n * `current_step` reads the step's task-result `data`; `context` reads the\n * accumulated `StoryboardContext`. `path` supports `[*]` wildcard segments\n * that flatten into the aggregated result (so `products[*].format_ids[*]`\n * walks every product and flattens every `format_ids` array).\n */\nexport interface RefsResolveSet {\n  from: 'current_step' | 'context';\n  path: string;\n}\n\n/**\n * Scope filter for `refs_resolve`. Only source refs whose `key` matches\n * `equals` (after `$agent_url` substitution and, for URL-ending keys,\n * transport-suffix-stripping canonicalization) are in scope. Out-of-scope\n * refs are graded by `on_out_of_scope`.\n */\nexport interface RefsResolveScope {\n  key: string;\n  /** String to compare against. `$agent_url` expands to the runner target URL. */\n  equals: string;\n}\n\nexport interface StoryboardValidation {\n  /** Stable authored validation identifier echoed into runner results when present. */\n  id?: string;\n  /** Known validation kind, or a future string graded not_applicable by older runners. */\n  check: StoryboardValidationCheck | (string & {});\n  /** Whether a failed validation gates the step. Defaults to `required`. */\n  severity?: 'required' | 'advisory';\n  /**\n   * Runner capability version at which an advisory is promoted to required.\n   * Compared using semver.gte against the runner's self-declared capability.\n   */\n  expires_after_version?: string;\n  /** Structured marker for an advisory that deliberately never auto-promotes. */\n  permanent_advisory?: { reason: string };\n  /** JSON path for field checks, e.g. \"accounts[0].account_id\" */\n  path?: string;\n  /** Expected value for exact-match checks. */\n  value?: unknown;\n  /** Accepted values for list-match checks (passes if actual matches any). */\n  allowed_values?: unknown[];\n  /** JavaScript regular expression source for field_pattern checks. */\n  pattern?: string;\n  description: string;\n  // ─── refs_resolve fields ───────────────────────────────────\n  /** Source refs (the refs being checked). */\n  source?: RefsResolveSet;\n  /** Target refs (the set the source refs must resolve into). */\n  target?: RefsResolveSet;\n  /** Keys to compare between each source ref and each target ref. */\n  match_keys?: string[];\n  /** Only enforce integrity for refs matching this scope. */\n  scope?: RefsResolveScope;\n  /**\n   * How to grade source refs that fall outside `scope`.\n   *  - `warn` (default) — attach observations, pass the check\n   *  - `ignore` — silent, pass the check\n   *  - `fail` — treat as missing\n   */\n  on_out_of_scope?: 'warn' | 'ignore' | 'fail';\n  // ─── Cross-step comparison fields ──────────────────────\n  /**\n   * Key to look up in the accumulated `storyboardContext` for cross-step\n   * comparison checks (`field_less_than`, `field_greater_than`,\n   * `field_at_most`, `field_at_least`, `field_equals_context`,\n   * `field_in_context_array`, `all_fields_in_context_array`).\n   * Only consumed by those check types — ignored on all others.\n   * When set and the key is absent from context, the check passes with a\n   * `context_key_absent` observation rather than failing — the prior step\n   * that was supposed to populate the key may have been legitimately skipped.\n   */\n  context_key?: string;\n  // ─── upstream_traffic fields ──────────────────────────────\n  /**\n   * Minimum number of recorded calls (matching `endpoint_pattern` if set)\n   * the runner MUST observe in the assertion window. Default 1. Use 0 only\n   * for negative assertions (\"step MUST NOT cause upstream traffic\").\n   * Spec: storyboard-schema.yaml > \"upstream_traffic\".\n   */\n  min_count?: number;\n  /**\n   * Glob/path pattern matched against `recorded_calls[].endpoint`\n   * (`<METHOD> <URL>`). Examples: `POST <star>/audience/upload`,\n   * `POST <star>` (where `<star>` is a literal asterisk). When omitted,\n   * every recorded call in the window matches.\n   */\n  endpoint_pattern?: string;\n  /**\n   * Each entry asserts a path/value pair that MUST appear in at least one\n   * matching call's payload. See `UpstreamTrafficPayloadMatch`.\n   */\n  payload_must_contain?: UpstreamTrafficPayloadMatch[];\n  /**\n   * Raw payload introspection requirement. When set to `raw`, controllers\n   * that downgrade the response to digest-only attestations cause this\n   * validation to grade `not_applicable` instead of failed.\n   */\n  attestation_mode_required?: 'raw';\n  /**\n   * Advisory request-mode preference for the runner's\n   * `query_upstream_traffic` prefetch. When omitted, the runner preserves\n   * its legacy inference: digest for identifier-only checks with digestable\n   * vectors, raw otherwise. Raw-required validations and payload\n   * introspection always take precedence over this preference.\n   */\n  preferred_attestation_mode?: 'raw' | 'digest';\n  /**\n   * Paths into the effective request payload that name the load-bearing\n   * identifiers the adapter MUST forward upstream. When the runner has the\n   * actual request payload after context substitution, that payload is the\n   * source of truth; otherwise it falls back to the storyboard's\n   * `sample_request`.\n   *\n   * The runner extracts the values at these paths and asserts each resolved\n   * value appears in at least one matching `recorded_call`'s payload at any\n   * depth. Each path MAY resolve to a single value or an array; ALL resolved\n   * values MUST be present in the recorded payload — single-placeholder\n   * fabrication is the threat model. Portable path syntax is a request-rooted\n   * dotted grammar with optional `[*]` wildcard selectors on segments, for\n   * example `audiences[*].add[*].hashed_email`. Explicit roots (`$.foo`),\n   * reserved roots (`request.*`, `response.*`, `context.*`), bracket-quoted\n   * keys, recursive descent (`$..foo`), numeric indexes, and empty segments\n   * are storyboard authoring errors so controllers do not silently resolve\n   * zero vectors. The runner caps portable digest proofs at 64 unique\n   * identifier values; overflow is graded `not_applicable` because the bound\n   * is runner-side, not a spec value. Per spec PR adcontextprotocol/adcp#3816,\n   * replaces the earlier\n   * `buyer_identifier_echo: boolean` shorthand.\n   */\n  identifier_paths?: string[];\n  /**\n   * Bound the lookup window to traffic recorded since this step's request\n   * timestamp (default) or since the request timestamp of `prior_step_id`\n   * for cumulative-effect assertions.\n   */\n  since?: string;\n  // ─── array_length fields ──────────────────────────────────\n  /**\n   * Inclusive lower bound for `array_length`. Mutually exclusive with\n   * `value`. Pass with `max` omitted to assert \"at least N entries.\"\n   */\n  min?: number;\n  /**\n   * Inclusive upper bound for `array_length`. Mutually exclusive with\n   * `value`. Pass with `min` omitted to assert \"at most N entries.\"\n   */\n  max?: number;\n}\n\n// ────────────────────────────────────────────────────────────\n// Webhook-assertion step types\n//\n// The four `expect_webhook*` tasks are pseudo-tasks: they do not drive the\n// agent over MCP. Instead the runner uses them to observe / assert on the\n// webhook deliveries a prior step triggered. Graded only when the storyboard\n// declares the `webhook_receiver_runner` contract and the runner hosts a\n// receiver. Spec: adcontextprotocol/adcp#2431.\n// ────────────────────────────────────────────────────────────\n\n/** Webhook-body match predicate. Dotted paths, deep equality. */\nexport interface WebhookFilterSpec {\n  /** Match by `operation_id` echoed in the per-step URL path. */\n  operation_id?: string;\n  /** Match by dotted-path → value deep equality against the parsed body. */\n  body?: Record<string, unknown>;\n}\n\n/** Receiver behavior that forces the sender to retry so retry-stability can be graded. */\nexport interface WebhookRetryTriggerSpec {\n  /** How many deliveries to reject before accepting. Default 3. */\n  count?: number;\n  /** HTTP status code to return for the rejected deliveries. Default 503. */\n  http_status?: number;\n}\n\n/**\n * Error codes per spec (webhook-emission universal, storyboard-schema.yaml).\n *\n * Signature-path codes track the verifier's `webhook_signature_*` taxonomy\n * 1:1 so compliance reports distinguish remediation paths: a revoked key\n * needs rotation; a rate-abuse hit signals a compromised key; a\n * window-invalid is a signer clock/config bug. Spec folds every window\n * failure into a single `signature_window_invalid` — there is no\n * `signature_expired`.\n */\nexport type WebhookAssertionErrorCode =\n  // expect_webhook\n  | 'no_webhook_received'\n  | 'schema_violation'\n  | 'missing_idempotency_key'\n  | 'invalid_idempotency_key_format'\n  | 'duplicate_webhook_on_replay'\n  // expect_no_webhook\n  | 'unexpected_webhook_received'\n  // expect_webhook_retry_keys_stable\n  | 'insufficient_retries'\n  | 'idempotency_key_rotated'\n  | 'idempotency_key_format_changed'\n  // expect_webhook_signature_valid\n  | 'signature_invalid'\n  | 'signature_window_invalid'\n  | 'signature_alg_not_allowed'\n  | 'signature_components_incomplete'\n  | 'signature_header_malformed'\n  | 'signature_params_incomplete'\n  | 'signature_key_unknown'\n  | 'signature_key_purpose_invalid'\n  | 'signature_mode_mismatch'\n  | 'signature_target_uri_malformed'\n  | 'signature_key_revoked'\n  | 'signature_revocation_stale'\n  | 'signature_rate_abuse'\n  | 'signature_digest_mismatch'\n  | 'signature_tag_invalid'\n  | 'signature_replayed';\n\n/**\n * Spec pattern for webhook `idempotency_key`: 16–255 chars of base64url-safe\n * punctuation. Shared by all three assertion step types; exported so callers\n * (tests, tooling) can reproduce the grader's exact validation.\n */\nexport const WEBHOOK_IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_.:-]{16,255}$/;\n\n/**\n * Raw HTTP probe result for tasks like `protected_resource_metadata` that\n * bypass the MCP transport. Carried through the runner alongside\n * `TaskResult` so validations like `http_status` and `on_401_require_header`\n * can introspect the response.\n */\nexport interface HttpProbeResult {\n  url: string;\n  status: number;\n  /** Lowercased header names. */\n  headers: Record<string, string>;\n  /** Parsed JSON body when the response declared application/json; raw text otherwise. */\n  body: unknown;\n  /** Optional error — set when the fetch failed (network, SSRF guard, etc.). */\n  error?: string;\n  /**\n   * Probe was intentionally skipped (e.g. operator opted out of a vector,\n   * capability profile mismatch, or test-kit contract not in scope). When\n   * set, the runner marks the step `skipped: true` and does NOT run\n   * validations — skipped probes neither pass nor fail.\n   */\n  skipped?: boolean;\n  skip_reason?: string;\n}\n\n// ────────────────────────────────────────────────────────────\n// Context: accumulated state passed between steps\n// ────────────────────────────────────────────────────────────\n\nexport type StoryboardContext = Record<string, unknown>;\n\n// ────────────────────────────────────────────────────────────\n// Options\n// ────────────────────────────────────────────────────────────\n\n/**\n * One agent in a per-specialism routing map. Used by `runStoryboard()` when\n * a storyboard spans tools that live on different tenants (e.g. signals at\n * `/signals`, governance at `/governance`).\n *\n * `auth` is an optional per-tenant override. The canonical multi-tenant\n * deployment (the prod test-agent's six tenants) uses one shared bearer\n * across every URL — set `StoryboardRunOptions.auth` once at the run\n * level and leave entries' `auth` empty. Set `auth` on an entry only\n * when that tenant uses different credentials (e.g., a publisher whose\n * signals tenant is fronted by a partner like LiveRamp with separate\n * auth from the sales tenant). Adcp-client#1066.\n */\nexport interface AgentEntry {\n  /** MCP or A2A endpoint URL for this agent. */\n  url: string;\n  /** Per-tenant auth override; falls back to `StoryboardRunOptions.auth` when absent. */\n  auth?: TestOptions['auth'];\n  /** Per-tenant transport override; defaults to `StoryboardRunOptions.protocol`. */\n  transport?: 'mcp' | 'a2a';\n}\n\n/** One runner-hosted Context Match provider fixture exposed to the router under test. */\nexport interface TrustedMatchContextProviderEndpoint {\n  /** Publisher-controlled registration id from the packaged conformance vector. */\n  provider_id: string;\n  /** Absolute URL serving this provider's vector response at `POST /context`. */\n  context_url: string;\n}\n\n/** Input to the operator-owned router registration seam. */\nexport interface TrustedMatchContextRegistrationContext {\n  /** Vector profile, currently `adcp/trusted-match/context-targeting-merge/v1`. */\n  profile: string;\n  /** Fixed provider ids paired with the runner-hosted fixture URLs. */\n  providers: TrustedMatchContextProviderEndpoint[];\n  /** Exact Context Match request the runner will send after registration completes. */\n  request: Record<string, unknown>;\n}\n\nexport interface TrustedMatchContextRouterRunnerOptions {\n  /** Router base URL. The runner posts the vector request to `<router_url>/context`. */\n  router_url: string;\n  /**\n   * Operator-owned seam that installs the supplied provider registrations in\n   * the router under test. It may return a cleanup callback, which the runner\n   * invokes after the replay even when the router request fails.\n   */\n  registerProviders(\n    context: TrustedMatchContextRegistrationContext\n  ): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;\n  /** Extra headers sent to the router's `/context` endpoint. */\n  headers?: Record<string, string>;\n  /** Router request timeout in milliseconds. Defaults to 10000. */\n  timeoutMs?: number;\n  /** Optional root directory for resolving the packaged vector file. */\n  vectorsRoot?: string;\n  /** Override fetch for tests or custom runtimes. */\n  fetchImpl?: typeof fetch;\n  /** Configuration for the ephemeral provider fixture server. */\n  provider_server?: {\n    /** Loopback by default; proxy mode advertises `public_url` to remote routers. */\n    mode?: 'loopback_mock' | 'proxy_url';\n    /** Bind host for the local fixture listener. Defaults to `127.0.0.1`. */\n    host?: string;\n    /** Bind port. `0` (default) lets the kernel assign one. */\n    port?: number;\n    /** Public base URL routed to the local listener; required in proxy mode. */\n    public_url?: string;\n  };\n}\n\nexport type TrustedMatchPublisherAuthOperation = 'context' | 'identity';\nexport type TrustedMatchPublisherCredentialState = 'absent' | 'invalid';\n\n/** Declarative TLS material for one runner-owned publisher-auth probe. */\nexport interface TrustedMatchPublisherAuthTls {\n  clientCertificatePem?: string;\n  privateKeyPem?: string;\n  privateKeyPassphrase?: string;\n  caCertificatePem?: string;\n}\n\n/** The only values an operator adapter may contribute to a publisher-auth probe. */\nexport interface TrustedMatchPublisherAuthProbeConfiguration {\n  credentialHeaders?: Record<string, string>;\n  tls?: TrustedMatchPublisherAuthTls;\n}\n\n/**\n * Operator seam for credential-profile-neutral Trusted Match publisher-auth\n * conformance. The SDK, not this adapter, owns endpoint validation, routing,\n * HTTP construction, redirect policy, timeouts, response limits, and output.\n */\nexport interface TrustedMatchPublisherAuthRunner {\n  /** Exact publisher-facing Context Match URL. No path is inferred. */\n  contextEndpoint: string;\n  /** Exact publisher-facing Identity Match URL. No path is inferred. */\n  identityEndpoint: string;\n  preparePublisherAuthProbe(input: {\n    operation: TrustedMatchPublisherAuthOperation;\n    credentialState: TrustedMatchPublisherCredentialState;\n  }): Promise<TrustedMatchPublisherAuthProbeConfiguration>;\n}\n\nexport interface StoryboardRunOptions extends TestOptions {\n  /** Caller-selected compliance cache root for bundle-scoped test kits. */\n  complianceDir?: string;\n  /** Initial context (e.g., from a previous step invocation) */\n  context?: StoryboardContext;\n  /**\n   * Initial context-provenance map, typically threaded from a prior\n   * `runStoryboardStep` invocation's `StoryboardStepResult.context_provenance`.\n   * Lets LLM-orchestrated step-by-step runs accumulate the per-key write\n   * history the runner needs to emit `context_value_rejected` hints when a\n   * later step's seller rejects a value an earlier step extracted. Ignored by\n   * `runStoryboard` (full run builds its own map internally). Closes\n   * adcp-client#880.\n   */\n  context_provenance?: Record<string, ContextProvenanceEntry>;\n  /**\n   * Context keys whose producer step was skipped as response-derived\n   * `not_applicable`, typically threaded from a prior `runStoryboardStep`\n   * invocation's `StoryboardStepResult.response_derived_not_applicable_context_keys`.\n   * Lets stateless step-by-step callers preserve the same cursor-consumer skip\n   * semantics as full `runStoryboard` runs.\n   */\n  response_derived_not_applicable_context_keys?: Record<string, string>;\n  /**\n   * Contribution flags accumulated by prior `runStoryboardStep` invocations.\n   * Thread this from `StoryboardStepResult.contributions` so synthetic\n   * aggregate steps such as `assert_contribution` see the same branch-set\n   * state they would see inside a full `runStoryboard` execution.\n   */\n  contributions?: string[];\n  /** Override the step's sample_request with a custom request */\n  request?: Record<string, unknown>;\n  /** Agent's available tools for storyboard/step-level tool gates. */\n  agentTools?: string[];\n  /**\n   * Allow plain-http agent URLs during compliance runs and permit guarded\n   * raw-HTTP probes to reach private/loopback endpoints. Production agents\n   * MUST terminate TLS; dedicated probes that require HTTPS (including TMP\n   * publisher authentication) keep that requirement even when this flag is\n   * enabled. Intended for local dev loops and private staging harnesses.\n   * Emits an advisory banner in the report when used.\n   */\n  allow_http?: boolean;\n  /**\n   * Operator assertion that initial state has been provisioned out-of-band\n   * (HTTP admin, pre-test script, staging fixture) — flips the\n   * `seeded_state` requirement to available so storyboards declaring\n   * `requires: [seeded_state]` run instead of skipping with\n   * `requirement_unmet`. Default false. The runner does NOT verify the\n   * assertion; if state isn't actually seeded the scenario fails\n   * naturally on its first stateful step, which is the right signal.\n   * CLI: `--asserts-seeded-state`. Spec: adcp-client#1626.\n   */\n  assertsSeededState?: boolean;\n  /**\n   * Request-signing grader knobs (applied when the runner encounters\n   * synthesized `request_signing_probe` steps from the signed-requests\n   * specialism).\n   */\n  request_signing?: {\n    /** Skip the rate-abuse vector — it sends cap+1 requests and is slow. */\n    skipRateAbuse?: boolean;\n    /** Override the per-keyid cap the grader targets. */\n    rateAbuseCap?: number;\n    /**\n     * Vector IDs to skip (e.g., capability-profile mismatches for vectors\n     * 007/018 when the agent's `covers_content_digest` policy differs).\n     */\n    skipVectors?: string[];\n    /**\n     * Run only the named vector ids — all others auto-skip. Takes precedence\n     * over `skipVectors`.\n     */\n    onlyVectors?: string[];\n    /**\n     * Opt in to running vectors that produce live agent-side effects\n     * (016 replay, 020 rate-abuse). Required unless the test-kit declares\n     * `endpoint_scope: sandbox`. This flag controls request-signing vectors\n     * only; use the top-level `allowLiveSideEffects` option separately for\n     * `expect_rate_limit_not_replayed`.\n     */\n    allowLiveSideEffects?: boolean;\n    /**\n     * How the grader dispatches each vector to the agent.\n     *\n     *   - `raw` (default) — POSTs each vector body directly to a per-\n     *     operation AdCP endpoint (e.g. `<baseUrl>/create_media_buy`).\n     *     Works for agents that expose AdCP tools as discrete HTTP\n     *     operations.\n     *   - `mcp` — wraps each vector body in a JSON-RPC `tools/call`\n     *     envelope and POSTs to the agent's single `/mcp` mount. Required\n     *     for MCP-only agents that don't expose per-operation endpoints.\n     *     The operation name is derived from the last path segment of the\n     *     vector's target URL.\n     *\n     * Matches the `adcp grade request-signing --transport <mode>` CLI flag.\n     * Agents that only speak MCP JSON-RPC can't grade under `raw`; use\n     * `mcp` to let the runner round-trip every vector through `tools/call`.\n     */\n    transport?: 'raw' | 'mcp';\n    /**\n     * Pre-provisioned MCP session ID to attach as `Mcp-Session-Id` on every\n     * vector probe after signing. When `transport` is `'mcp'` and this is\n     * omitted, the runner auto-initializes a session via the MCP\n     * `initialize` handshake before each vector call. Pass a pre-acquired ID\n     * (from `initializeMcpSession`) to reuse one session across the whole\n     * storyboard run and avoid the per-vector round-trip overhead.\n     *\n     * Pass `''` (empty string) to disable auto-initialization for stateless\n     * streamable-HTTP agents that do not issue session IDs.\n     */\n    mcpSessionId?: string;\n  };\n  /**\n   * Distribution strategy across agent URLs in multi-instance mode.\n   * Only consulted when the runner is given 2+ URLs. Defaults to 'round-robin'.\n   *\n   *  - `round-robin` (default): step N hits `urls[N % urls.length]`. One pass.\n   *  - `multi-pass` (narrow use case): runs the storyboard `urls.length`\n   *    times, each pass starting the dispatcher at a different replica.\n   *    Surfaces single-replica bugs (stale config, divergent version,\n   *    local-cache miss) that single-pass round-robin may not catch when\n   *    the buggy replica happens to serve only passive steps. N-multiplies\n   *    run time. NOT a full cross-replica state-persistence test at N=2:\n   *    offset-shift preserves pair parity, so write→read pairs with even\n   *    dispatch-index distance (e.g., the property_lists case: write at 0,\n   *    read at 2) land same-replica in every pass. Use single-pass\n   *    round-robin (adjacent pairs) + follow-up dependency-aware dispatch\n   *    (non-adjacent pairs, #607 option 2) for the spec's horizontal-\n   *    scaling requirement. See docs/guides/MULTI-INSTANCE-TESTING.md.\n   */\n  multi_instance_strategy?: 'round-robin' | 'multi-pass';\n  /**\n   * Per-specialism agent routing map. When set, each step's tool name\n   * (`StoryboardStep.task`) is resolved to the agent that claims its\n   * specialism via `TASK_FEATURE_MAP` × per-agent `get_adcp_capabilities`.\n   * An optional explicit `StoryboardStep.agent` override takes precedence.\n   *\n   * Mutually exclusive with `multi_instance_strategy` (which is replica\n   * round-robin, a different concept) and with the legacy `_client`\n   * override (single client cannot serve multiple agents). Both\n   * combinations throw at `runStoryboard()` entry.\n   *\n   * Discovery is parallel across all agents at storyboard start; any agent\n   * whose discovery fails causes the whole storyboard to fail (not skip),\n   * because a topology with one broken tenant is a hard misconfiguration,\n   * not a per-step skip condition.\n   *\n   * Multi-claim conflicts (two agents claim the same specialism) fail-fast\n   * at discovery time for affected steps that lack an explicit `step.agent`\n   * override. Steps WITH an override route per the override and never see\n   * the conflict — the override is the disambiguator, not just an escape\n   * hatch. To resolve a conflict: either remove one of the conflicting\n   * agents from the map, or add `agent: <key>` to each affected step.\n   *\n   * Adcp-client#1066.\n   */\n  agents?: Record<string, AgentEntry>;\n  /**\n   * Fallback agent key (must be present in `agents`) for tasks with no entry\n   * in `TASK_FEATURE_MAP` — e.g., `comply_test_controller`, future tasks\n   * shipped before the SDK adds them to the map. When omitted, unmapped\n   * tasks fail-fast with `unroutable_task`.\n   */\n  default_agent?: string;\n  /**\n   * Opt into resilient discovery (#1367). When `false` (default), any agent\n   * whose `get_adcp_capabilities` probe fails causes the whole storyboard\n   * to fail — correct for production multi-tenant flows where every tenant\n   * in the map is load-bearing.\n   *\n   * When `true`:\n   *   - Discovery failures are logged but not fatal.\n   *   - Failed agents are excluded from the protocol-claim index.\n   *   - Routing throws `RoutingError` only if a step's protocol resolves\n   *     to a failed agent — surfaces as a per-step failure, not a\n   *     storyboard-wide hard failure.\n   *   - A `discovery_failures[]` summary on `StoryboardResult` lists which\n   *     agents failed, so the operator still sees the topology breakage.\n   *\n   * Intended for hello-cluster CI and exploratory runs where one flaky\n   * tenant shouldn't gate a 6-tenant smoke. Production runs should NEVER\n   * set this — a topology with one broken tenant is a hard misconfig.\n   *\n   * Only consulted when `agents` is set (multi-agent routing); single-URL\n   * runs have no roster to be resilient about.\n   */\n  discovery_resilient?: boolean;\n  /**\n   * Host an ephemeral webhook receiver during the run so `expect_webhook*`\n   * pseudo-steps can observe outbound webhooks from the agent under test.\n   * Enables the `webhook_receiver_runner` contract referenced by the\n   * `webhook-emission` universal (adcontextprotocol/adcp#2431).\n   *\n   * When enabled, storyboards can substitute `{{runner.webhook_base}}` and\n   * `{{runner.webhook_url:<step_id>}}` into `push_notification_config.url`\n   * and downstream `expect_webhook*` steps observe the deliveries.\n   *\n   * Mode selection matches the spec's `endpoint_modes`:\n   *   - `loopback_mock` (default): bind an HTTP listener on loopback; URLs\n   *     point at `http://127.0.0.1:<port>`. Zero external network setup.\n   *     Suitable for CI lint gates, SDK self-tests, and local dev.\n   *   - `proxy_url`: operator-supplied public URL (tunnel / ingress) routes\n   *     to a local HTTP listener on the configured port. Suitable for AdCP\n   *     Verified grading where the agent under test is remote.\n   *\n   * **Multi-agent topology** (`options.agents` set): the receiver is **shared**\n   * across all tenants in the routing map — one HTTP server, one base URL,\n   * bound once at storyboard start. This works correctly for cross-specialism\n   * flows because delivery correlation is by **step-keyed URL** (the receiver\n   * mints `/step/<step_id>/<operation_id>` paths), not by source agent. If a\n   * `sync_governance` step on the governance tenant and an `activate_signal`\n   * step on the signals tenant both emit webhooks, the runner disambiguates by\n   * step ID, not tenant identity. Per-tenant receivers are not supported and\n   * are not needed for any current cross-specialism storyboard in the corpus.\n   */\n  webhook_receiver?: {\n    /** Endpoint mode (default: `loopback_mock`). */\n    mode?: 'loopback_mock' | 'proxy_url';\n    /** Bind host for the local listener. Defaults to `127.0.0.1`. */\n    host?: string;\n    /** Bind port. `0` (default) lets the kernel assign one. */\n    port?: number;\n    /**\n     * Public URL to advertise when `mode: 'proxy_url'`. Must terminate at\n     * the local listener on `port`. Stored verbatim; the runner does not\n     * validate reachability.\n     */\n    public_url?: string;\n  };\n  /**\n   * Target receiver for `replay_webhook_vector` storyboards. This is separate\n   * from `webhook_receiver`: that option hosts a local receiver so the runner\n   * can observe seller-emitted webhooks, while this option points at the\n   * buyer/orchestrator receiver the runner should POST canonical vectors to.\n   */\n  webhook_replay_receiver?: {\n    /** Absolute URL of the receiver endpoint under test. */\n    url: string;\n    /** Extra headers to send on every replay. */\n    headers?: Record<string, string>;\n    /** Optional signing profile for raw-body verification tests. */\n    signing?: WebhookConformanceSigningOptions;\n    /** Request timeout in milliseconds. Defaults to 10000. */\n    timeoutMs?: number;\n    /** Optional root directory for resolving vector_ref file paths. */\n    vectorsRoot?: string;\n    /** Override fetch for tests or custom runtimes. */\n    fetchImpl?: typeof fetch;\n  };\n  /**\n   * Raw-HTTP Trusted Match Context router harness used by\n   * `replay_trusted_match_context_vector`. The runner hosts the packaged\n   * provider fixtures, calls `registerProviders`, then posts the vector\n   * request to `<router_url>/context`. Without this option the storyboard\n   * grades `not_applicable`; it never falls back to MCP or A2A.\n   */\n  trusted_match_context_router_runner?: TrustedMatchContextRouterRunnerOptions;\n  /**\n   * Guarded raw-HTTP harness for the four Trusted Match publisher-auth\n   * pseudo-tasks. Only credential headers and declarative PEM TLS material\n   * cross the adapter boundary; the SDK owns every transport decision.\n   */\n  trusted_match_publisher_auth_runner?: TrustedMatchPublisherAuthRunner;\n  /**\n   * Test-kit contract ids that are in scope for this run. A step with\n   * `requires_contract: <id>` grades `not_applicable` when the id is not\n   * listed here. Storyboards that assert webhook behavior typically declare\n   * `webhook_receiver_runner`.\n   */\n  contracts?: string[];\n  /**\n   * Explicitly authorize the `expect_rate_limit_not_replayed` storyboard\n   * probe, which may send hundreds of mutating requests. The probe requires\n   * this opt-in in addition to its `rate_limit_trip_runner` contract;\n   * contract presence alone is not runtime authorization. This does not\n   * authorize request-signing vectors, which use\n   * `request_signing.allowLiveSideEffects`. Default false.\n   */\n  allowLiveSideEffects?: boolean;\n  /**\n   * Opt out of the runner's pre-flight `comply_test_controller` seeding\n   * (adcp-client#778). When true, the runner skips the seed_* loop even if\n   * the storyboard declares `prerequisites.controller_seeding: true` and a\n   * `fixtures:` block. Intended for agents that load fixtures via a non-MCP\n   * path (HTTP admin, test bootstrap, inline Node state) — set the flag so\n   * the runner doesn't race the external seeding or fail against an agent\n   * that doesn't host `comply_test_controller`.\n   */\n  skip_controller_seeding?: boolean;\n  /**\n   * Dependencies for `expect_webhook_signature_valid`. When omitted the step\n   * grades `not_applicable` — matches the spec's \"pending\" gate. Supply the\n   * publisher's JWKS resolver (typically fetched via `brand.json`\n   * `agents[]` `jwks_uri`) to turn the step on. The two optional stores\n   * default to process-local in-memory implementations; override when the\n   * runner needs durable state across runs.\n   */\n  webhook_signing?: {\n    jwks: import('../../signing/jwks').JwksResolver;\n    replayStore?: import('../../signing/replay').ReplayStore;\n    revocationStore?: import('../../signing/revocation').RevocationStore;\n    /** Override the required tag. Defaults to `adcp/webhook-signing/v1`. */\n    required_tag?: string;\n  };\n  /**\n   * Cancel the run when this signal aborts. Threaded down to the per-phase\n   * and per-step loops inside `executeStoryboardPass` so an abort fires\n   * between any two steps, not only between storyboards. Without it,\n   * `comply()`'s timeout would only bound the *next* storyboard's start —\n   * a single in-flight storyboard could exhaust its full timeout budget\n   * inside one fan-out of sequential MCP/A2A calls. (adcp-client#1612)\n   */\n  signal?: AbortSignal;\n}\n\n// ────────────────────────────────────────────────────────────\n// Runner-output contract shapes\n//\n// See `static/compliance/source/universal/runner-output-contract.yaml`\n// (adcontextprotocol/adcp PR #2364). The contract defines the minimum\n// failure-result shape every AdCP compliance runner MUST emit so buyers\n// can self-diagnose agent conformance failures. Optional fields stay\n// `undefined` when they don't apply (e.g., schema_url on a non-schema\n// check).\n// ────────────────────────────────────────────────────────────\n\nexport type RunnerTransport = 'mcp' | 'a2a' | 'http';\n\nexport interface RunnerRequestRecord {\n  transport: RunnerTransport;\n  /** Task/tool/skill name actually invoked (after test-kit resolution). */\n  operation: string;\n  /** Fully-resolved JSON payload with secrets redacted as \"[redacted]\". */\n  payload: unknown;\n  /**\n   * Observed request headers. Deliberately NOT populated today — the runner\n   * builds `Authorization: Bearer <token>` headers in-flight and echoing them\n   * into a shared compliance report would be a credential leak. The field is\n   * kept in the type for future auth-override request captures that carry a\n   * redacted form.\n   */\n  headers?: Record<string, string>;\n  /** Full URL for http/a2a; omitted for stdio MCP. */\n  url?: string;\n}\n\nexport interface RunnerResponseRecord {\n  transport: RunnerTransport;\n  /** Exact response payload, per transport. */\n  payload: unknown;\n  /** HTTP status where applicable. */\n  status?: number;\n  /** Observed response headers. */\n  headers?: Record<string, string>;\n  /** Wall-clock time for the request. */\n  duration_ms?: number;\n}\n\n/**\n * Which MCP extraction path produced the parsed response. Recording this\n * lets implementors distinguish runner extraction bugs from agent bugs.\n * Populated by the response unwrapper (normal SDK path) and by the raw MCP\n * probe (auth-override path); the runner falls back to inference when the\n * provenance tag is missing.\n *\n *   - `structured_content` — parsed from `result.structuredContent`.\n *   - `text_fallback` — parsed from `result.content[].text` JSON.\n *   - `error` — `result.isError` or transport-level failure; payload is the error.\n *   - `none` — no MCP response (HTTP-probe step, synthetic step, or skipped).\n */\nexport type RunnerExtractionPath = 'structured_content' | 'text_fallback' | 'error' | 'none';\n\nexport interface RunnerExtractionRecord {\n  path: RunnerExtractionPath;\n  /** Optional note, e.g. \"structuredContent contained only adcp_error\". */\n  note?: string;\n}\n\n/**\n * Spec skip reasons. Runners MUST distinguish these so an implementor knows\n * whether a skip is informative (agent didn't claim the protocol) or masking\n * (runner couldn't apply the storyboard even though the agent claimed it).\n */\nexport type RunnerSkipReason =\n  | 'not_applicable'\n  | 'no_phases'\n  | 'prerequisite_failed'\n  | 'missing_tool'\n  | 'missing_test_controller'\n  /**\n   * The runner selected the pathway but its test kit cannot synthesize a\n   * valid input for the seller-declared contract. This is a runner-owned\n   * coverage gap: it never fails validations or cascades prerequisites.\n   * Spec: AdCP runner-output-contract v2.8.0,\n   * `skip_result.reasons.fixture_unavailable` (adcp#6276). Early preflight\n   * and whole-storyboard termination semantics: adcp#6278.\n   */\n  | 'fixture_unavailable'\n  | 'unsatisfied_contract'\n  /**\n   * A storyboard-level `requires:` tag named a requirement that is not\n   * available on the current run (e.g. `controller` when the agent doesn't\n   * advertise `comply_test_controller`, or `seeded_state` when the operator\n   * didn't pass `--asserts-seeded-state`). Distinct from `missing_tool` /\n   * `missing_test_controller` (per-step tool gates) and `unsatisfied_contract`\n   * (a declared runner contract is unavailable). The\n   * `RunnerSkipResult.requirement` field carries\n   * the unmet requirement name, including unknown forward-compatible strings.\n   * Spec: adcp-client#1626.\n   */\n  | 'requirement_unmet'\n  /**\n   * A peer optional phase in the same `branch_set` already contributed the\n   * aggregation flag, so this non-chosen branch's failing steps are moot\n   * (see storyboard-schema.yaml > \"Per-step grading in any_of branch\n   * patterns\" and runner-output-contract.yaml). Kept distinct from\n   * `not_applicable` (coverage gap) and raw `failed` (agent misbehavior).\n   */\n  | 'peer_branch_taken'\n  /**\n   * A same-phase peer step declared `provides_state_for: <this_step_id>`\n   * and passed, establishing equivalent state. This step would have graded\n   * `missing_tool` or `missing_test_controller`; the substitute rescued it\n   * so downstream stateful steps can still run. Detail format per\n   * `runner-output-contract.yaml`:\n   * `\"<this_step_id> state provided by <phase_id>.<substitute_step_id>\"`.\n   * Kept distinct from `peer_branch_taken` (branch-set routing) and\n   * `not_applicable` (coverage gap). Spec source: adcp#3734 (AdCP 3.0.3+).\n   */\n  | 'peer_substituted';\n\n/**\n * Grader-specific skip reasons. These are narrower than the canonical\n * `RunnerSkipReason` values — they carry runner-local context (which probe,\n * which operator opt-out) that the contract neither requires nor forbids.\n * The runner records them on `skip_reason` for legacy consumers, and also\n * emits the structured `skip: RunnerSkipResult` block with the canonical\n * equivalent per `DETAILED_SKIP_TO_CANONICAL`.\n */\nexport type RunnerDetailedSkipReason =\n  | 'probe_skipped'\n  | 'rate_abuse_opt_out'\n  | 'missing_test_kit_contract'\n  | 'live_side_effect_opt_in_required'\n  | 'operator_skip'\n  | 'not_in_only_vectors'\n  | 'grader_skipped'\n  /** Request-signing vector is outside the agent's declared signing capability profile. */\n  | 'capability_profile_mismatch'\n  /** Request-signing vector cannot be graded faithfully by the selected transport. */\n  | 'transport_ungradable'\n  /** Request-signing grader's MCP-transport mode collapses URL-edge vectors (#617). */\n  | 'mcp_mode_flattens_url_edges'\n  /** RFC 9728 protected-resource metadata returned 404 → agent is not advertising OAuth, cascade-skip oauth_discovery (#677). */\n  | 'oauth_not_advertised'\n  /** rate_limit_trip_runner did not observe RATE_LIMITED within max_attempts. */\n  | 'rate_limit_not_triggered'\n  /**\n   * Pre-flight `comply_test_controller` seeding failed (adcp-client#778), so\n   * every real phase cascade-skipped rather than run against an unseeded\n   * agent. The structured `skip.reason` resolves to the canonical\n   * `prerequisite_failed` per `DETAILED_SKIP_TO_CANONICAL` — the detailed\n   * form stays on the legacy `skip_reason` field so report consumers can\n   * still distinguish setup breaks from stateful-chain breaks within a\n   * phase.\n   */\n  | 'controller_seeding_failed'\n  /**\n   * A generated pre-flight seed_* call targeted a scenario that the agent's\n   * comply_test_controller does not implement. Maps to canonical\n   * `not_applicable`: the seller cannot accept this storyboard's fixture\n   * setup, so the storyboard is out of scope rather than failed.\n   */\n  | 'fixture_seed_unsupported'\n  /** A valid fixture strategy ladder exhausted without finding a binding. */\n  | 'fixture_unsatisfied'\n  /**\n   * A `requires_capability` predicate on the storyboard evaluated to false —\n   * the agent explicitly declared it does not support the capability this\n   * storyboard tests (e.g. `adcp.idempotency.supported: false`). The whole\n   * storyboard is skipped before any phase runs. Maps to canonical\n   * `not_applicable`: this storyboard does not target the agent's\n   * self-declared capability profile.\n   */\n  | 'capability_unsupported'\n  /**\n   * A `comply_test_controller` step targeted a `force_*` scenario that the\n   * agent advertised the controller for but did not implement. Detected by\n   * the tuple (step.task === 'comply_test_controller', resolved\n   * `scenario` parameter starts with `force_`, response `success: false,\n   * error: UNKNOWN_SCENARIO`). Runners MUST grade the step `not_applicable`\n   * with detail `force_scenario_unsupported` instead of failing the step's\n   * authored validations. Maps to canonical `not_applicable`. AdCP 3.0.12\n   * runner-output-contract: `universal/runner-output-contract.yaml` >\n   * `skip_result.reasons.force_scenario_unsupported`.\n   */\n  | 'force_scenario_unsupported';\n\n/**\n * Map detailed grader skip reasons onto the canonical spec values so\n * consumers reading `skip.reason` get a stable enum regardless of which\n * subsystem produced the skip.\n */\nexport const DETAILED_SKIP_TO_CANONICAL: Record<RunnerDetailedSkipReason, RunnerSkipReason> = {\n  probe_skipped: 'not_applicable',\n  not_in_only_vectors: 'not_applicable',\n  grader_skipped: 'not_applicable',\n  capability_profile_mismatch: 'not_applicable',\n  transport_ungradable: 'not_applicable',\n  mcp_mode_flattens_url_edges: 'not_applicable',\n  oauth_not_advertised: 'not_applicable',\n  rate_limit_not_triggered: 'not_applicable',\n  force_scenario_unsupported: 'not_applicable',\n  fixture_seed_unsupported: 'not_applicable',\n  fixture_unsatisfied: 'not_applicable',\n  capability_unsupported: 'not_applicable',\n  rate_abuse_opt_out: 'unsatisfied_contract',\n  missing_test_kit_contract: 'unsatisfied_contract',\n  live_side_effect_opt_in_required: 'unsatisfied_contract',\n  operator_skip: 'unsatisfied_contract',\n  controller_seeding_failed: 'prerequisite_failed',\n};\n\nexport interface RunnerSkipResult {\n  reason: RunnerSkipReason;\n  detail: string;\n  /**\n   * Set on storyboard-level `requires:` skips to name the requirement that was\n   * not available on this run. Most such skips use\n   * `reason === 'requirement_unmet'`; legacy-preserving mappings such as\n   * `controller -> missing_test_controller` also carry this field. Carries the\n   * same value authored in `Storyboard.requires`, including unknown\n   * forward-compatible strings. Consumers (skip-cause aggregation, dashboards)\n   * key on this field to group not-applicable scenarios by cause. Spec:\n   * adcp-client#1626.\n   */\n  requirement?: string;\n}\n\nexport type RunnerSelectionReason =\n  | 'run_mode_excluded'\n  | 'explicit_scope_excluded'\n  | 'version_excluded'\n  | 'profile_excluded';\n\nexport interface RunnerSelectionResult {\n  reason: RunnerSelectionReason;\n  detail: string;\n}\n\n/**\n * Recognised values for `Storyboard.requires`. See `Storyboard.requires`\n * for what each name detects from. Adding a new value here is a wire\n * surface change; coordinate with the upstream spec proposal before\n * extending.\n *\n * Spec: adcp-client#1626, adcp-client#2281, adcp-client#2356.\n */\nexport type RequirementName =\n  | 'controller'\n  | 'seeded_state'\n  | 'real_wire'\n  | 'webhook_receiver'\n  | 'webhook_replay_receiver'\n  | 'trusted_match_context_router_runner'\n  | 'trusted_match_publisher_auth_runner'\n  | 'request_signer'\n  | 'multi_agent';\n\n/**\n * Enumeration of every requirement this SDK knows how to satisfy. The loader\n * accepts other non-empty strings for forward compatibility; the runner treats\n * those as unmet runtime requirements so future source-authored gates degrade\n * to `requirement_unmet` instead of failing load. Keep in sync with\n * `RequirementName`.\n */\nexport const KNOWN_REQUIREMENTS: ReadonlySet<RequirementName> = new Set([\n  'controller',\n  'seeded_state',\n  'real_wire',\n  'webhook_receiver',\n  'webhook_replay_receiver',\n  'trusted_match_context_router_runner',\n  'trusted_match_publisher_auth_runner',\n  'request_signer',\n  'multi_agent',\n] as const satisfies readonly RequirementName[]);\n\n/**\n * Machine-readable Zod/AJV-style validation error. Emitted in\n * `ValidationResult.actual` for `response_schema` failures.\n */\nexport interface SchemaValidationError {\n  instance_path: string;\n  schema_path: string;\n  keyword: string;\n  message: string;\n}\n\n// ────────────────────────────────────────────────────────────\n// Runner notices\n// ────────────────────────────────────────────────────────────\n\n/**\n * Closed literal union of every notice code the runner can emit.\n *\n * Adopters who narrow on `code` get exhaustiveness checks: when a new\n * code lands in a future SDK release, their switch / discriminated\n * union surfaces the gap at compile time. That's the right signal —\n * a deprecation or future-required advisory is the kind of thing a CI\n * gate or dashboard SHOULD have explicit handling for.\n *\n * Code naming generally follows the dot-namespaced convention `<topic>.<event>`\n * (e.g. `request_signing.required`, `webhook_signing.legacy_hmac_fallback.removed`);\n * prefer the upstream runner-output contract's canonical code when it\n * registers a different spelling. The *when* lives in the `effective_version`\n * field, never in the code. This keeps the surface stable across spec versions\n * — codes don't proliferate `_in_4_0` / `_in_5_0` siblings as the spec evolves.\n *\n * Adding a new code is a wire-surface change AND a TypeScript breaking\n * change for adopters who narrowed on `code`. Coordinate with the upstream\n * spec (adcp#4418) before extending.\n *\n * Spec: adcp-client#1704.\n */\nexport type NoticeCode =\n  /** Agent advertises deprecated `specialisms: ['signed-requests']`. Removed in\n   *  AdCP 4.0 per `effective_version`. */\n  | 'signed_requests_specialism_deprecated'\n  /** Agent lacks `request_signing.supported: true`. Required for spend-committing\n   *  operations in AdCP 4.0 per `effective_version`. */\n  | 'request_signing.required'\n  /** Agent advertises `webhook_signing.legacy_hmac_fallback: true`. Removed in\n   *  AdCP 4.0 per `effective_version`. */\n  | 'webhook_signing.legacy_hmac_fallback.removed'\n  /** Runner stripped request fields missing from the agent's advertised tool input schema. */\n  | 'input_schema_field_stripped'\n  /** The preflight get_adcp_capabilities response failed schema validation. */\n  | 'capabilities_response_schema_invalid';\n\n/**\n * Severity of a runner notice. Deliberately separate from `ObservationSeverity`\n * (which grades behavioral quality). Notices describe the agent's _protocol\n * compliance trajectory_ — a different axis: something is fine today but the\n * spec already signals a future state change.\n *\n * - `info` — non-grading context; it may still identify an actionable defect.\n * - `deprecation` — SHOULD migrate; the field/claim is deprecated in the current\n *   spec version.\n * - `future_required` — behavior is optional today but will be mandatory in a\n *   named future AdCP version (see `effective_version`).\n */\nexport type NoticeSeverity = 'info' | 'deprecation' | 'future_required';\n\n/**\n * A structured advisory produced by the runner for a specific storyboard run.\n * Notices describe protocol compliance trajectory (deprecations, upcoming\n * requirements) rather than behavioral quality (which is `AdvisoryObservation`'s\n * domain). Intended for CI gates and dashboards that need machine-readable badges\n * like \"DEPRECATION\" or \"FUTURE-REQUIRED\" without parsing prose strings.\n *\n * `ComplianceResult.notices` aggregates these across all storyboard runs,\n * deduplicated by `code`, or by (`code`, `capability_pointer`) when a pointer\n * is present. This preserves one schema-invalid notice per response location.\n *\n * Spec: adcp-client#1704.\n */\nexport interface RunnerNotice {\n  severity: NoticeSeverity;\n  /** Stable machine-readable identifier. Dashboards key on this for badge routing. */\n  code: NoticeCode;\n  /** Human-readable explanation; first 200 chars suitable for tabular rendering. */\n  message: string;\n  /**\n   * AdCP protocol version at which the behavior becomes mandatory (for\n   * `future_required`) or was formally removed (for `deprecation`).\n   * e.g. `'4.0'`. Absent when not version-bounded. Field name matches\n   * upstream spec issue adcontextprotocol/adcp#4418.\n   */\n  effective_version?: string;\n  /**\n   * Dot-path into the agent's capability response that motivated the notice\n   * (e.g. `request_signing.supported`). Use as a human-readable pointer only;\n   * not guaranteed to resolve via JSON Pointer.\n   */\n  capability_path?: string;\n  /**\n   * RFC 6901 pointer into the agent's `get_adcp_capabilities` response.\n   * Distinct from `capability_path`, which is a human-readable dotted flag\n   * path. Notices may carry both when they identify the same location.\n   */\n  capability_pointer?: string;\n  /**\n   * Click-through URL for adopters to read the underlying spec section,\n   * migration guide, or AdCP issue. Optional; consumers that surface\n   * notices in dashboards or CI output use this to deep-link the\n   * remediation context. Stable across runs for the same `code`.\n   */\n  docs_url?: string;\n  /**\n   * Storyboard ids that triggered this notice. On `StoryboardResult.notices`\n   * this is always a single-element array (the storyboard the notice came\n   * from). On `ComplianceResult.notices` (the deduplicated cross-storyboard\n   * rollup) this aggregates every storyboard that emitted the same dedupe key\n   * (`code`, or `code` + `capability_pointer` when present), so auditors can\n   * see \"how widespread\" a signal is without re-walking the per-storyboard\n   * arrays. Order is stable across runs (storyboard execution order).\n   */\n  storyboard_ids: string[];\n}\n\n// ────────────────────────────────────────────────────────────\n// Results\n// ────────────────────────────────────────────────────────────\n\nexport interface ValidationResult {\n  /** Stable authored validation identifier, echoed unchanged when provided by the storyboard. */\n  id?: string;\n  check: string;\n  passed: boolean;\n  description: string;\n  /** Effective severity after any capability-version promotion. Defaults to `required`. */\n  severity?: 'required' | 'advisory';\n  /**\n   * Present only for expiry-gated advisories that were graded: true when\n   * promoted to required, false while the runner capability remains older.\n   */\n  severity_promoted_from_advisory?: boolean;\n  /** Dot/bracket JSON path (legacy). See `json_pointer` for the RFC 6901 form. */\n  path?: string;\n  /** Human-readable failure detail. */\n  error?: string;\n  /** RFC 6901 pointer to the failing field. Null when the failure is transport-level. */\n  json_pointer?: string | null;\n  /** Machine-readable expected value / schema $id / acceptable forms. */\n  expected?: unknown;\n  /** Machine-readable actual value / schema errors / observed non-object. */\n  actual?: unknown;\n  /** Schema $id applied; set only for `response_schema`. */\n  schema_id?: string | null;\n  /** Resolvable schema URL; set only for `response_schema`. */\n  schema_url?: string | null;\n  /** Exact request the runner sent (present on failure when available). */\n  request?: RunnerRequestRecord;\n  /** Exact response observed (present on failure when available). */\n  response?: RunnerResponseRecord;\n  /** Optional remediation hint. */\n  remediation?: string;\n  /**\n   * Marker for an implemented check whose declared applicability conditions\n   * were not met. Unknown authored check kinds fail closed; they never set\n   * this flag or contribute a false green result. Entries carrying this flag\n   * contribute to `validations_not_applicable` so consumers can distinguish\n   * inapplicable coverage from clean passes.\n   */\n  not_applicable?: boolean;\n  /**\n   * Human-readable note attached to a passing-but-not-applicable result\n   * (forward-compat path) or other informational annotations. Distinct\n   * from `warning` which signals a soft issue on a successful check.\n   */\n  note?: string;\n  /**\n   * Non-fatal notes emitted by the check — e.g. `refs_resolve` records the\n   * out-of-scope refs it skipped when `on_out_of_scope: warn`. Present only\n   * when the check has something to report; absent otherwise.\n   */\n  observations?: unknown[];\n  /**\n   * Non-fatal human-readable warning attached when a check `passed` but\n   * detected a softer issue the caller should still see — today used only\n   * by `response_schema` to surface the top strict-AJV issue when Zod\n   * accepts and AJV rejects (the \"lenient-passes ∧ strict-fails\" subset\n   * of issue #820). LLM-driven self-correction and CI graphs that scan\n   * `error`/`warning` fields can act on this without the runner flipping\n   * step pass/fail and breaking existing tests.\n   */\n  warning?: string;\n  /**\n   * Issue #820 follow-up — strict JSON-schema (AJV) verdict for\n   * `response_schema` checks. `passed` remains the lenient Zod outcome\n   * (runner's historical pass/fail semantics); `strict` carries the\n   * AJV-with-formats-and-additionalProperties verdict separately so\n   * agent developers can see the strict/lenient delta without the\n   * runner failing a step that the Zod path accepts. Absent on non-\n   * response_schema checks or when no AJV schema is available.\n   */\n  strict?: StrictValidationVerdict;\n}\n\n/**\n * Strict (AJV JSON-schema) verdict attached to a response_schema\n * validation result. Informational — the step's pass/fail is driven by\n * the lenient Zod path. `valid: false` with `valid_lenient: true`\n * indicates the strict/lenient delta: the agent's response passes the\n * generated Zod shape but fails strict JSON-schema (typically a\n * `format` violation or an `additionalProperties: false` breach).\n */\nexport interface StrictValidationVerdict {\n  valid: boolean;\n  /** Response variant AJV ultimately validated against. After fallback: `\"sync\"`. */\n  variant: string;\n  /** Concrete AJV issues (RFC 6901 pointers) when `valid: false`. Absent when valid. */\n  issues?: SchemaValidationError[];\n  /**\n   * True when the agent's response `status` field named an async variant\n   * (`submitted` / `working` / `input-required`) but no compiled schema\n   * existed for that variant, so validation fell back to the sync\n   * response schema. Conformance signal: the agent advertised an async\n   * shape this tool doesn't explicitly schema. Present only on fallback.\n   */\n  variant_fallback_applied?: boolean;\n  /** Variant requested by payload shape before fallback. Set iff `variant_fallback_applied`. */\n  requested_variant?: string;\n}\n\nexport interface StoryboardStepPreview {\n  step_id: string;\n  phase_id: string;\n  title: string;\n  task: string;\n  narrative?: string;\n  expected?: string;\n  /** sample_request with context already injected */\n  sample_request?: Record<string, unknown>;\n}\n\nexport interface StoryboardStepResult {\n  /** Storyboard that produced this step result. */\n  storyboard_id?: string;\n  step_id: string;\n  phase_id: string;\n  title: string;\n  task: string;\n  passed: boolean;\n  /** True when the step was not executed */\n  skipped?: boolean;\n  /**\n   * Skip reason. Accepts either a canonical `RunnerSkipReason` or one of the\n   * grader-specific variants introduced\n   * by the RFC 9421 request-signing grader (#585, #617). The structured\n   * `skip` field below always carries the canonical spec reason so consumers\n   * of the runner-output contract don't need to know the grader vocabulary.\n   * In particular, `rate_limit_not_triggered` is a passing skipped result\n   * with `skip.reason === 'not_applicable'`,\n   * `skip.detail === 'rate_limit_not_triggered'`, and no validations. Its\n   * human-readable diagnostic remains on the legacy `response.error` field.\n   */\n  skip_reason?: RunnerSkipReason | RunnerDetailedSkipReason;\n  /** Structured skip result with canonical spec reason + contract-defined detail. */\n  skip?: RunnerSkipResult;\n  /**\n   * Structured selection result for steps that were outside the caller's\n   * requested run before execution. Kept separate from `skip`: skipped means\n   * selected-but-not-executed, selection means not selected for this run.\n   */\n  selection_result?: RunnerSelectionResult;\n  /** True when the step expected an error (inverted pass/fail) */\n  expect_error?: boolean;\n  duration_ms: number;\n  /** Raw parsed response body (legacy field; new code reads `response_record`). */\n  response?: unknown;\n  validations: ValidationResult[];\n  /** Accumulated context after this step */\n  context: StoryboardContext;\n  /**\n   * Accumulated context-provenance after this step. Each entry records which\n   * step wrote the matching context key and how (convention extractor vs\n   * author-provided `context_outputs` path). Thread back into\n   * `StoryboardRunOptions.context_provenance` on the next `runStoryboardStep`\n   * invocation so hints fire across the stateless step-by-step surface the\n   * same way they do inside `runStoryboard`. adcp-client#880.\n   */\n  context_provenance?: Record<string, ContextProvenanceEntry>;\n  /**\n   * Accumulated response-derived `not_applicable` context-key map after this\n   * step. Thread back into `StoryboardRunOptions.response_derived_not_applicable_context_keys`\n   * on the next `runStoryboardStep` invocation so cursor consumers skip as\n   * `not_applicable` rather than `prerequisite_failed`.\n   */\n  response_derived_not_applicable_context_keys?: Record<string, string>;\n  /**\n   * Contribution flags accumulated after this step. Thread back into\n   * `StoryboardRunOptions.contributions` on the next `runStoryboardStep`\n   * invocation when orchestrating a storyboard step-by-step.\n   */\n  contributions?: string[];\n  error?: string;\n  /**\n   * Structured AdCP error forwarded from the transport layer when the step failed.\n   * Carries `code`, `field`, and `details.validation_errors` so dashboards and\n   * LLM self-correction loops can identify the exact fault address without\n   * re-running the step. Present only when the underlying task returned a\n   * structured `adcp_error` envelope; absent for transport-level failures.\n   */\n  adcp_error?: import('../../core/ConversationTypes').AdcpErrorInfo;\n  /** Preview of the next step (for LLM consumption) */\n  next?: StoryboardStepPreview;\n  /** Agent URL that served this step (multi-instance mode). Absent in single-URL mode. */\n  agent_url?: string;\n  /** 1-based index of the agent instance (multi-instance mode). Absent in single-URL mode. */\n  agent_index?: number;\n  /** Exact request the runner sent (contract-required on failures). */\n  request?: RunnerRequestRecord;\n  /** Exact response observed, including transport, status, headers. */\n  response_record?: RunnerResponseRecord;\n  /** Which extraction path produced the parsed response (required per contract). */\n  extraction: RunnerExtractionRecord;\n  /**\n   * Informational notices scoped to this step. These do not affect pass/fail.\n   * Storyboard-level `notices` aggregates step notices by code.\n   */\n  notices?: RunnerNotice[];\n  /**\n   * Non-fatal diagnostic hints the runner emitted alongside this step —\n   * currently surfaces `context_value_rejected` when a request value came\n   * from a prior-step `$context.*` write and the seller's error response\n   * lists the set of values it would have accepted. Pass/fail is unchanged;\n   * hints help triage collapse from \"SDK bug vs seller bug\" to one line.\n   */\n  hints?: StoryboardStepHint[];\n}\n\n/**\n * Provenance entry for a context key: which step wrote it and how.\n * Populated by the runner as it applies `context_outputs` and convention-\n * based extractors after each successful step, and consumed when emitting\n * `context_value_rejected` hints.\n */\nexport interface ContextProvenanceEntry {\n  /** Step id that produced this context value. */\n  source_step_id: string;\n  /**\n   * `context_outputs`: author-authored extraction from the YAML.\n   * `convention`: task-default extractor in CONTEXT_EXTRACTORS.\n   * `generator`: runner-minted value (no response path involved).\n   */\n  source_kind: 'context_outputs' | 'convention' | 'generator';\n  /** Response path the value was extracted from (set for `context_outputs`). */\n  response_path?: string;\n  /** Task name whose response this value was extracted from. */\n  source_task?: string;\n}\n\n/**\n * Common shape every `StoryboardStepHint` member shares: the discriminator\n * + a pre-formatted human-readable message. Renderers that don't know a\n * specific `kind` can still display `message` verbatim; renderers that do\n * know the `kind` can branch on it and read the structured fields each\n * member adds. Issue #935: \"every runner-side diagnostic with structured\n * fields a renderer can consume\" flows through this surface.\n */\nexport interface StoryboardStepHintBase {\n  /** Discriminator. Each concrete hint kind sets its own literal value.\n   * @provenance runner\n   */\n  kind: string;\n  /**\n   * Pre-formatted human-readable message suitable for a console line.\n   * @provenance seller\n   * Contains pre-interpolated seller-derived bytes for\n   * `context_value_rejected` (rejected value, accepted values, request field\n   * pointer) and `monotonic_violation` (resource id, prior and current status)\n   * hint kinds. Treat as untrusted when rendering into LLM context or any\n   * prompt-injection-sensitive surface; build safe output from the structured\n   * `@provenance runner` / `@provenance storyboard` fields instead, or\n   * sanitize at the boundary.\n   *\n   * `shape_drift` and `missing_required_field` messages are composed entirely\n   * from runner-derived tokens and are safe to render without sanitization.\n   * `format_mismatch` messages are safe under the current AJV configuration\n   * (no custom error-message plugins); if `ajv-errors` or a custom AJV\n   * keyword message factory is added, audit whether it embeds seller data\n   * values before treating `format_mismatch` messages as trusted.\n   */\n  message: string;\n}\n\n/**\n * Non-fatal hint attached to a step result. The discriminator lives on\n * `kind` so consumers that only know how to render a subset can ignore\n * the rest without losing them; `message` is always present as a\n * human-readable fallback (see `StoryboardStepHintBase`). More kinds\n * may be added over time — issue #935 enumerated the canonical taxonomy.\n */\nexport type StoryboardStepHint =\n  | ContextValueRejectedHint\n  | ShapeDriftHint\n  | MissingRequiredFieldHint\n  | FormatMismatchHint\n  | MonotonicViolationHint\n  | ImpairmentCoherenceHint\n  | ImpairmentCoherenceNotApplicableHint;\n\n/**\n * A seller rejected a request value that the runner traced back to a\n * `$context.*` substitution (or a request-builder field populated from the\n * same context key). Without this hint, the rejection in logs looks\n * identical to an SDK bug; with it, the caller can see the substitution\n * chain (step → context key → response path) and go talk to the seller.\n */\nexport interface ContextValueRejectedHint extends StoryboardStepHintBase {\n  kind: 'context_value_rejected';\n  /**\n   * Context key whose value matched the rejected request field.\n   * @provenance storyboard\n   */\n  context_key: string;\n  /**\n   * Step id that wrote the context key.\n   * @provenance runner\n   */\n  source_step_id: string;\n  /**\n   * How the context key was written (`context_outputs` vs convention vs generator).\n   * @provenance runner\n   */\n  source_kind: 'context_outputs' | 'convention' | 'generator';\n  /**\n   * YAML response path set for `context_outputs`; absent for convention extractors and generators.\n   * @provenance storyboard\n   */\n  response_path?: string;\n  /**\n   * Task whose response the value was extracted from.\n   * @provenance storyboard\n   */\n  source_task?: string;\n  /**\n   * The value the seller rejected. Copied verbatim from context (which was\n   * itself extracted from a prior seller response); already embedded in\n   * `message` via string interpolation — sanitize before rendering into LLM\n   * context.\n   * @provenance seller\n   */\n  rejected_value: unknown;\n  /**\n   * Dotted path to the rejected field in the runner's request (when the\n   * seller's error carried an explicit `field` pointer). Absent when the\n   * match was resolved by scanning the request for a context-sourced value\n   * in the rejection set. Sourced from the seller's `errors[].field` pointer\n   * and normalized by `normalizeFieldPath()` (RFC 6901 → dotted form);\n   * already embedded in `message` — sanitize before LLM rendering.\n   * @provenance seller\n   */\n  request_field?: string;\n  /**\n   * The accepted values the seller reported (`available` / `allowed` /\n   * `accepted_values`). Elements are unconstrained seller strings embedded\n   * verbatim in `message`; sanitize before rendering into LLM context or\n   * any prompt-injection-sensitive surface.\n   * @provenance seller\n   */\n  accepted_values: unknown[];\n  /**\n   * Error code from the seller's error (if present).\n   * @provenance seller\n   */\n  error_code?: string;\n}\n\n/**\n * The runner detected that the agent's response payload diverged from the\n * expected shape for the tool — e.g. a list tool returned a bare array\n * instead of `{ <wrapper_key>: [...] }`, or `build_creative` returned\n * platform-native fields at the top level instead of `{ creative_manifest }`.\n *\n * Non-fatal: step pass/fail is unchanged. The runner emits this in place of\n * the legacy `ValidationResult.warning` prose so downstream renderers (CLI,\n * Addie, JUnit) can build per-case fix plans from the structured fields.\n *\n * `instance_path` uses RFC 6901 / `SchemaValidationError.instance_path`\n * conventions: `\"\"` for root-level drift, leading-slash + tokens for nested.\n */\nexport interface ShapeDriftHint extends StoryboardStepHintBase {\n  kind: 'shape_drift';\n  /**\n   * AdCP tool name (snake_case) that produced the drift.\n   * @provenance runner\n   */\n  tool: string;\n  /**\n   * Short token describing the observed (wrong) shape variant. Always a\n   * runner-hardcoded string (`bare_array`, `platform_native_fields`, etc.)\n   * derived from pattern-matching the seller's response shape — not the\n   * seller's payload bytes directly.\n   * @provenance runner\n   */\n  observed_variant: string;\n  /**\n   * Short token or schema fragment describing the expected shape.\n   * @provenance runner\n   */\n  expected_variant: string;\n  /**\n   * RFC 6901 pointer to the drift site; `\"\"` for root-level. Hardcoded by\n   * the runner's shape-detector; not derived from seller response content.\n   * @provenance runner\n   */\n  instance_path: string;\n}\n\n/**\n * Strict (AJV) JSON-schema validation reports a missing required field that\n * the lenient Zod path didn't enforce. Mirrors the `SchemaValidationError`\n * shape so a renderer can drive directly off the structured fields without\n * re-parsing the prose `validation.warning`.\n */\nexport interface MissingRequiredFieldHint extends StoryboardStepHintBase {\n  kind: 'missing_required_field';\n  /**\n   * AdCP tool name (snake_case) the response was validated under.\n   * @provenance runner\n   */\n  tool: string;\n  /**\n   * RFC 6901 pointer to the parent object missing the field. `\"\"` for root.\n   * Generated by AJV from the JSON schema evaluation result.\n   * @provenance runner\n   */\n  instance_path: string;\n  /**\n   * Pointer into the JSON schema that named the requirement.\n   * @provenance runner\n   */\n  schema_path: string;\n  /**\n   * Field name(s) the parent object was required to carry. Every entry is a\n   * bare identifier extracted from the AJV error message (via the pattern\n   * `required property 'X'`). AJV issues whose message does not match that\n   * pattern — e.g. a reworded or locale-variant message from a future AJV\n   * major or a custom AJV instance — are omitted rather than included\n   * verbatim. Callers can rely on every entry being a plain field name.\n   * The raw AJV issue message may still appear in `ValidationResult.warning`\n   * prose for human readers.\n   * @provenance runner\n   */\n  missing_fields: string[];\n  /**\n   * Resolvable schema URL (when the runner could attribute one).\n   * @provenance runner\n   */\n  schema_url?: string;\n}\n\n/**\n * Strict (AJV) JSON-schema validation rejected a value that the lenient Zod\n * path accepted — a `format` keyword breach (uri / date-time / uuid / ...)\n * or other strict-only delta the agent ships today that a strict dispatcher\n * would block (issue #820). Carries enough structured detail for a renderer\n * to write a verify-after-fix recipe.\n */\nexport interface FormatMismatchHint extends StoryboardStepHintBase {\n  kind: 'format_mismatch';\n  /**\n   * AdCP tool name (snake_case).\n   * @provenance runner\n   */\n  tool: string;\n  /**\n   * RFC 6901 pointer to the failing field. Generated by AJV; identifies a\n   * location in the seller's response but the pointer string itself is\n   * runner-derived.\n   * @provenance runner\n   */\n  instance_path: string;\n  /**\n   * Pointer into the JSON schema that named the constraint.\n   * @provenance runner\n   */\n  schema_path: string;\n  /**\n   * AJV keyword that rejected (`format`, `pattern`, `enum`, `minLength`, ...).\n   * Runner-internal pseudo-keyword `truncated` is used when the hint count\n   * is capped.\n   * @provenance runner\n   */\n  keyword: string;\n  /**\n   * Resolvable schema URL (when the runner could attribute one).\n   * @provenance runner\n   */\n  schema_url?: string;\n}\n\n/**\n * The `status.monotonic` invariant observed a resource transition that is\n * not on the spec lifecycle graph for its resource type. Carries the\n * structured fields a renderer needs to point the implementor at the\n * canonical enum schema and the prior step that set the anchor state.\n */\nexport interface MonotonicViolationHint extends StoryboardStepHintBase {\n  kind: 'monotonic_violation';\n  /**\n   * Resource family (`media_buy`, `creative`, `account`, ...). Hardcoded by\n   * the runner's per-resource-type extractors.\n   * @provenance runner\n   */\n  resource_type: string;\n  /**\n   * Resource id observed transitioning. Extracted from the seller's response\n   * (e.g. `media_buy_id`, `creative_id`) and embedded in `message` —\n   * sanitize before rendering into LLM context.\n   * @provenance seller\n   */\n  resource_id: string;\n  /**\n   * Status the resource was in at the anchor step. Recorded by the runner\n   * from a prior step's seller response and stored in the assertion's state\n   * map; embedded in `message` — sanitize before LLM rendering.\n   * @provenance seller\n   */\n  from_status: string;\n  /**\n   * Status the resource transitioned to at the current step. Read directly\n   * from the seller's current response; embedded in `message` — sanitize\n   * before LLM rendering.\n   * @provenance seller\n   */\n  to_status: string;\n  /**\n   * Step id that recorded the previous status. Runner-tracked internal ID.\n   * @provenance runner\n   */\n  from_step_id: string;\n  /**\n   * Legal next-state set per the lifecycle graph. Empty array means the\n   * `from_status` is terminal — the violation is \"any forward transition\n   * from a terminal state\". Derived from the runner's hardcoded transition\n   * tables in `default-invariants.ts`.\n   * @provenance runner\n   */\n  legal_next_states: string[];\n  /**\n   * Canonical enum schema URL for the lifecycle graph. Runner-constructed\n   * from `ADCP_VERSION` and the per-resource enum filename.\n   * @provenance runner\n   */\n  enum_url: string;\n}\n\n/**\n * The `impairment.coherence` invariant observed a mismatch between a media\n * buy's `impairments[]` array and the underlying resource state. Three\n * violation shapes share this hint:\n *   - `forward`: an entry in `impairments[]` references a resource whose\n *     last observed status is NOT an offline value.\n *   - `inverse`: a resource was observed transitioning to an offline state\n *     and is referenced by a non-terminal buy, but is missing from that\n *     buy's `impairments[]`.\n *   - `health`: the buy's `health` field disagrees with `impairments[]`\n *     emptiness — `impaired` iff non-empty (and vice versa).\n *\n * See adcontextprotocol/adcp#2859 for the originating spec issue.\n */\nexport interface ImpairmentCoherenceHint extends StoryboardStepHintBase {\n  kind: 'impairment_coherence_violation';\n  /**\n   * Discriminator for the violation shape (see the union of `forward`,\n   * `inverse`, `health` documented on the type). Renderers can branch on\n   * `violation` to pick a per-shape template.\n   * @provenance runner\n   */\n  violation: 'forward' | 'inverse' | 'health';\n  /**\n   * Media-buy id whose `impairments[]` snapshot the violation was detected\n   * on. Read from `media_buy_id` on the buy response.\n   * @provenance seller\n   */\n  media_buy_id: string;\n  /**\n   * Step id that returned the offending media-buy snapshot.\n   * @provenance runner\n   */\n  buy_step_id: string;\n  /**\n   * Resource family (`creative`, `audience`, `catalog_item`, `event_source`)\n   * the entry references. Present on `forward` and `inverse`.\n   * @provenance seller (forward) / runner (inverse)\n   */\n  resource_type?: string;\n  /**\n   * Resource id the entry references. Present on `forward` and `inverse`.\n   * @provenance seller (forward) / runner (inverse)\n   */\n  resource_id?: string;\n  /**\n   * Status the runner has on file for the referenced resource. Present on\n   * `forward` and `inverse`. On `forward` it is the non-offline status that\n   * makes the impairment a false positive; on `inverse` it is the offline\n   * status the seller failed to propagate.\n   * @provenance seller\n   */\n  resource_status?: string;\n  /**\n   * Step id that recorded `resource_status`.\n   * @provenance runner\n   */\n  resource_step_id?: string;\n  /**\n   * Health value present on the buy snapshot when the violation is `health`.\n   * The literal seller-returned value, undefined when the field is absent.\n   * @provenance seller\n   */\n  buy_health?: string;\n  /**\n   * `impairments[].length` on the buy snapshot. Present on all three shapes.\n   * @provenance seller\n   */\n  impairments_count: number;\n}\n\n/**\n * The `impairment.coherence` invariant observed an offline-state transition\n * for a resource family whose buy → resource reverse-traversal isn't yet\n * implemented (audience / catalog_item / event_source). The forward rule\n * still grades these families; the inverse rule cannot, so the runner\n * surfaces the deferred coverage at the transition step instead of skipping\n * silently. Tracked in adcontextprotocol/adcp#2860.\n */\nexport interface ImpairmentCoherenceNotApplicableHint extends StoryboardStepHintBase {\n  kind: 'impairment_coherence_not_applicable';\n  /**\n   * Always `'inverse'` for this hint — the rule that can't grade.\n   * @provenance runner\n   */\n  violation: 'inverse';\n  /**\n   * Machine-readable reason code. Consumers can filter on this without\n   * matching prose.\n   * @provenance runner\n   */\n  reason: 'resource_traversal_deferred';\n  /**\n   * Resource family the transition was observed on. One of the three\n   * deferred families.\n   * @provenance runner\n   */\n  resource_type: 'audience' | 'catalog_item' | 'event_source';\n  /**\n   * Resource id the transition was observed on.\n   * @provenance seller\n   */\n  resource_id: string;\n  /**\n   * Offline status the resource transitioned to (`suspended` / `withdrawn`\n   * / `insufficient`).\n   * @provenance seller\n   */\n  resource_status: string;\n  /**\n   * Step id that recorded the offline transition.\n   * @provenance runner\n   */\n  resource_step_id: string;\n}\n\nexport interface StoryboardPhaseResult {\n  phase_id: string;\n  phase_title: string;\n  passed: boolean;\n  steps: StoryboardStepResult[];\n  duration_ms: number;\n}\n\nexport interface StoryboardResult {\n  storyboard_id: string;\n  storyboard_title: string;\n  /** Primary agent URL. In multi-instance mode this is the first URL — see agent_urls for the full list. */\n  agent_url: string;\n  /** All agent URLs used in multi-instance mode. Absent (or single-entry) in single-URL mode. */\n  agent_urls?: string[];\n  /** Distribution strategy used across agent_urls. Absent in single-URL mode. */\n  multi_instance_strategy?: 'round-robin' | 'multi-pass';\n  /**\n   * Per-specialism routing map (#1066). Echoes `StoryboardRunOptions.agents`\n   * resolved to `{ key: url }` so JUnit/CI consumers and bug reports show\n   * the topology this run executed against. Absent when not in routed mode.\n   * Each `StoryboardStepResult.agent_url` echoes the URL of the routed\n   * agent for that step.\n   */\n  agent_map?: Record<string, string>;\n  overall_passed: boolean;\n  /** AdCP 3.2 fixture-handle setup/discovery evidence, one row per handle. */\n  fixture_resolutions?: FixtureResolutionRecord[];\n  /** Storyboard-level fixture coverage gaps, emitted once per cause. */\n  coverage_gaps?: FixtureResolutionCoverageGap[];\n  /**\n   * Phases from the first pass. In `multi-pass` mode see `passes` for the full\n   * per-pass detail; `passed_count`/`failed_count`/`skipped_count` and\n   * `overall_passed` aggregate across all passes.\n   */\n  phases: StoryboardPhaseResult[];\n  /**\n   * Per-pass detail in `multi-pass` mode — one entry per starting replica so\n   * each step is served by each replica at least once across passes. Absent\n   * in single-pass modes. Per-pair cross-replica coverage depends on\n   * dispatch-index distance modulo `agent_urls.length` (see\n   * `multi_instance_strategy` on `StoryboardRunOptions`).\n   */\n  passes?: StoryboardPassResult[];\n  /** Final accumulated context */\n  context: StoryboardContext;\n  total_duration_ms: number;\n  passed_count: number;\n  failed_count: number;\n  skipped_count: number;\n  /** Failed advisory validations, counted separately from failed steps. */\n  validations_advisory_failed?: number;\n  /**\n   * Validation results graded `not_applicable` because the runner did not\n   * implement the authored `check` kind (forward-compat default). Surfaces\n   * \"runner is older than the storyboard\" as a distinct signal from clean\n   * passes. Per runner-output-contract.yaml v2.0.0 run_summary.\n   */\n  validations_not_applicable?: number;\n  /** Semver capability used to evaluate advisory validation expiry gates. */\n  runner_capability_version?: string;\n  tested_at: string;\n  /**\n   * Schemas applied during this run. Per the runner-output contract, runners\n   * MUST surface the exact schema identities so implementors can re-validate\n   * locally against the same artifacts.\n   */\n  schemas_used?: Array<{ schema_id: string; schema_url: string }>;\n  /**\n   * Results from cross-step assertions declared on the storyboard's\n   * `invariants` field. Step-scoped failures also surface inside the owning\n   * step's `validations[]` with `check: \"assertion\"`; storyboard-scoped\n   * failures live only here. `overall_passed` is false when any assertion\n   * failed.\n   */\n  assertions?: AssertionResult[];\n  /**\n   * Issue #820 follow-up — strict/lenient `response_schema` delta. Always\n   * emitted by the runner; inspect `observable` first to distinguish\n   * \"observed zero strict-eligible checks\" from \"observed N and graded\n   * them\". Storyboards dominated by non-`response_schema` validations\n   * (`field_present`, `error_code`, pure `assertion` runs) will have\n   * `observable: false` and zeroed counters.\n   */\n  strict_validation_summary?: StrictValidationSummary;\n  /**\n   * Structured protocol-compliance advisories produced for this storyboard\n   * run. Each notice carries a stable `code` (machine-readable, suitable for\n   * CI badge routing) and a non-grading `severity` (`info` | `deprecation` |\n   * `future_required`).\n   * Always present; empty array when no notices were triggered.\n   *\n   * `ComplianceResult.notices` aggregates across all storyboard runs,\n   * deduplicated by `code`, or by (`code`, `capability_pointer`) when a\n   * capability pointer is present. Spec: adcp-client#1704 and adcp#6256.\n   */\n  notices: RunnerNotice[];\n  /**\n   * Agents in the routing map whose `get_adcp_capabilities` probe failed\n   * when `StoryboardRunOptions.discovery_resilient: true` was set. Absent\n   * when resilient mode is off (because failures throw before result\n   * construction) and absent when no failures occurred. Each entry carries\n   * the agent key, URL, and the scrubbed underlying error so operators\n   * see the topology breakage without correlating across log lines.\n   *\n   * **Read together with `overall_passed`.** A passing storyboard with a\n   * non-empty `discovery_failures` means the storyboard did NOT touch any\n   * tools that needed the failed agents — it does NOT mean the topology\n   * was healthy. Dashboards and procurement reports should surface both\n   * fields; a green check next to a populated `discovery_failures` is\n   * legitimate but misleading without the second-axis signal.\n   *\n   * **Buyer-controlled untrusted content.** The `error` string is\n   * upstream-agent-derived and may contain attacker-influenced text from\n   * a malicious or compromised agent. The runner bounds the string\n   * (~512 chars) and runs the existing auth-secret scrub, but the\n   * remaining content is untrusted — validate / fence before templating\n   * into LLM prompts. The `url` field is scrubbed of userinfo\n   * (`//user:pass@host` → `//[REDACTED]@host`) so operator-encoded\n   * credentials don't leak to dashboards.\n   *\n   * Spec: adcp-client#1367.\n   */\n  discovery_failures?: Array<{ agent_key: string; url: string; error: string }>;\n}\n\nexport interface StrictValidationSummary {\n  /**\n   * True when at least one `response_schema` validation had an AJV\n   * validator compiled (the strict path could actually grade something).\n   * False means \"unobservable\": the run exercised only tasks whose JSON\n   * schema isn't registered, or only non-`response_schema` validations —\n   * NOT \"strict-clean with zero findings\". Downstream dashboards and\n   * CI formatters MUST check this before rendering the counts.\n   */\n  observable: boolean;\n  /** Response-schema checks that had an AJV validator compiled. */\n  checked: number;\n  /** Of `checked`, how many passed strict AJV. */\n  passed: number;\n  /** Of `checked`, how many failed strict AJV. Equals `checked - passed`. */\n  failed: number;\n  /**\n   * Count of validations where lenient Zod accepted AND strict AJV\n   * rejected — the \"silent failures\" the agent ships today that a strict\n   * dispatcher would block. Subset of `failed`. This is the actionable\n   * production-readiness signal for agent developers: a green lenient run\n   * with `strict_only_failures > 0` is a migration trap.\n   */\n  strict_only_failures: number;\n  /**\n   * Count of validations where BOTH lenient Zod AND strict AJV rejected —\n   * the step already failed under today's semantics, so strict rejection\n   * isn't new signal. Equals `failed - strict_only_failures`. Useful for\n   * dashboards that want to distinguish \"already-failing\" from\n   * \"silently-failing\" in the same run.\n   */\n  lenient_also_failed: number;\n}\n\n/**\n * Single assertion outcome recorded by the runner. Mirrors the shape of\n * `ValidationResult` so existing consumers can render assertions with the\n * same code path, while adding scope + source fields that identify where\n * the failure originated.\n */\nexport interface AssertionResult {\n  /** Id of the registered assertion that produced this result. */\n  assertion_id: string;\n  passed: boolean;\n  /** Human-readable description of the property being asserted. */\n  description: string;\n  /** Whether this result was raised at a specific step or storyboard-wide. */\n  scope: 'step' | 'storyboard';\n  /** Step that produced the observation, when `scope === \"step\"`. */\n  step_id?: string;\n  /** 1-based pass index when aggregated from a multi-pass run. */\n  pass_index?: number;\n  /** Failure detail. Absent on pass. */\n  error?: string;\n  /**\n   * Structured `StoryboardStepHint` the assertion can attach when it has\n   * machine-readable fields a renderer can consume. The runner mirrors this\n   * into the owning step's `hints[]` for `scope: \"step\"` results so the\n   * hint surfaces alongside `context_value_rejected` / `shape_drift` /\n   * strict-AJV hints under one taxonomy. Absent when the assertion only\n   * has prose to report.\n   */\n  hint?: StoryboardStepHint;\n  /**\n   * Lifecycle resources or transitions an observation-based invariant\n   * saw over the run. Set only by invariants whose verdict is meaningful\n   * exclusively when something was observed (`status.monotonic` today),\n   * emitted on the `onEnd` summary record. The track-level rollup\n   * demotes a passing track to `TrackStatus: 'silent'` when every record\n   * carrying this field reports `0`.\n   *\n   * This MUST count actual lifecycle resources or transitions observed\n   * — never \"the assertion was applicable\" or \"the assertion ran.\" A\n   * future invariant that emits `observation_count` with skip-style\n   * semantics would cause silent demotion for the wrong reason.\n   *\n   * Absent on assertions that don't model observation counts. Companion\n   * to adcontextprotocol/adcp#2834.\n   */\n  observation_count?: number;\n  /**\n   * Distinguishes `'silent'` (wired but no observations) from `'pass'`\n   * (wired and exercised). Per-assertion analog of the track-level\n   * `TrackStatus: 'silent'` rollup — consumers (graders, dashboards) that\n   * render per-assertion results need a direct enum here so the\n   * \"wired-but-not-observed\" outcome doesn't render identically to a real\n   * pass.\n   *\n   * Set by observation-based invariants on their `onEnd` summary record:\n   * `'silent'` when `observation_count === 0` AND `passed === true`,\n   * `'pass'` when `observation_count > 0` AND `passed === true`,\n   * `'fail'` when `passed === false`. Absent on assertions that don't\n   * model observation counts (their `passed` flag is sufficient).\n   *\n   * `'not_applicable'` is emitted at step scope by an invariant that\n   * recognises an observation it could grade in principle but whose\n   * grading path isn't yet implemented in the runner (e.g.\n   * `impairment.coherence` inverse rule for audience / catalog_item /\n   * event_source — tracked in adcontextprotocol/adcp#2860). The\n   * accompanying `hint` carries the deferral reason and resource family\n   * so renderers can distinguish a deferred coverage hint from a clean\n   * pass. Companion to adcontextprotocol/adcp#2834.\n   */\n  status?: 'pass' | 'silent' | 'fail' | 'not_applicable';\n}\n\n/**\n * Single pass in `multi-pass` multi-instance mode. Each pass re-runs the\n * whole storyboard with a different round-robin starting offset so each\n * step is served by each replica at least once across passes. See\n * `multi_instance_strategy` on `StoryboardRunOptions` for the N=2\n * per-pair coverage caveat.\n */\nexport interface StoryboardPassResult {\n  /** 1-based pass index. */\n  pass_index: number;\n  /** 0-based starting replica for this pass's round-robin dispatch. */\n  dispatch_offset: number;\n  overall_passed: boolean;\n  phases: StoryboardPhaseResult[];\n  passed_count: number;\n  failed_count: number;\n  skipped_count: number;\n  /** Failed advisory validations, counted separately from failed steps. */\n  validations_advisory_failed?: number;\n  /** Validations graded `not_applicable` (forward-compat default). */\n  validations_not_applicable?: number;\n  duration_ms: number;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAm7CO,MAAM,kCAAkC;AAsoBxC,MAAM,6BAAiF;AAAA,EAC5F,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,gBAAgB;AAAA,EAChB,6BAA6B;AAAA,EAC7B,sBAAsB;AAAA,EACtB,6BAA6B;AAAA,EAC7B,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,4BAA4B;AAAA,EAC5B,0BAA0B;AAAA,EAC1B,qBAAqB;AAAA,EACrB,wBAAwB;AAAA,EACxB,oBAAoB;AAAA,EACpB,2BAA2B;AAAA,EAC3B,kCAAkC;AAAA,EAClC,eAAe;AAAA,EACf,2BAA2B;AAC7B;AAuDO,MAAM,qBAAmD,oBAAI,IAAI;AAAA,EACtE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAA+C;","names":[]}
+{"version":3,"sources":["../../../../src/lib/testing/storyboard/types.ts"],"sourcesContent":["/**\n * Types for storyboard-driven testing.\n *\n * Storyboards are YAML-defined test workflows that walk through\n * AdCP agent interactions step by step. Each step maps to a\n * SingleAgentClient method and includes validations.\n */\n\nimport type { AgentProfile, TestOptions } from '../types';\nimport type { BuyerAgent, BuyerAgentBillingMode, BuyerAgentStatus } from '../../server/decisioning/buyer-agent';\nimport type { WebhookConformanceSigningOptions } from '../../conformance/types';\n\n// ────────────────────────────────────────────────────────────\n// Parsed storyboard structure (mirrors YAML schema)\n// ────────────────────────────────────────────────────────────\n\nexport type CapabilityPredicateValue =\n  | boolean\n  | string\n  | number\n  | null\n  | CapabilityPredicateValue[]\n  | { [key: string]: CapabilityPredicateValue };\n\nexport type RequiresCapabilityPredicate =\n  | { path: string; equals: boolean | string | number | null }\n  | { path: string; present: boolean }\n  | { path: string; contains: CapabilityPredicateValue }\n  | { path: string; not_contains: CapabilityPredicateValue };\n\nexport interface Storyboard {\n  id: string;\n  version: string;\n  /**\n   * AdCP compliance cache version this storyboard was loaded from, e.g.\n   * \"3.0.12\" or \"3.1.0-beta.7\". Injected by the local cache loader; not\n   * authored in storyboard YAML.\n   */\n  adcp_version?: string;\n  /**\n   * Compliance cache root this storyboard was loaded from. Injected by the\n   * cache loader so synthesized vectors and runtime probes use the same\n   * bundle even when process-level cache environment variables differ.\n   */\n  compliance_dir?: string;\n  title: string;\n  category: string;\n  summary: string;\n  narrative: string;\n  /** Maps to a ComplianceTrack for comply() integration */\n  track?: string;\n  /**\n   * AdCP spec version that introduced this storyboard, e.g. \"3.1\".\n   * When set, the runner skips the storyboard for agents whose declared\n   * `adcp.major_versions` does not include the major component — the\n   * storyboard did not exist at the version the agent certified against.\n   * Unset (the default) means the storyboard has always applied.\n   */\n  introduced_in?: string;\n  /** Tools that make this storyboard applicable (at least one must be present) */\n  required_tools?: string[];\n  /**\n   * Strict tool-family advertisement gates. Each family is satisfied when\n   * the agent advertises at least one listed tool; missing a family skips\n   * the whole storyboard with `requirement_unmet` and a\n   * `missing_required_tool_family:` detail prefix. The standard `comply()`\n   * path populates `agentTools` before this gate runs; direct callers that\n   * reuse a profile should provide `agentTools` or `profile.tools` so the\n   * runner can enforce it without discovery ambiguity.\n   */\n  required_any_of_tools?: RequiredToolFamily[];\n  /**\n   * Runtime requirements this storyboard depends on. Each name describes\n   * something the runner detects from the agent or from operator-supplied\n   * options; an unmet requirement skips the whole storyboard with\n   * `skip_reason: 'requirement_unmet'` rather than producing a cascade of\n   * misleading per-step `missing_test_controller` skips.\n   *\n   * Recognised names:\n   *   - `controller` — the agent must advertise `comply_test_controller`.\n   *     Detected from `options.agentTools`, `profile.tools`, or discovery\n   *     on reused clients. Direct callers that deliberately provide none of\n   *     those surfaces bypass this check; their storyboard runs into the\n   *     per-step `missing_test_controller` cascade instead.\n   *   - `seeded_state` — the operator must pass `--asserts-seeded-state`\n   *     (or set `assertsSeededState: true`) declaring that initial state\n   *     has been provisioned out-of-band (HTTP admin, pre-test script,\n   *     staging fixture). The runner does not verify the assertion;\n   *     scenarios that need state still fail naturally if the seed is\n   *     not actually present.\n   *   - `real_wire` — always available. Tag scenarios that observe\n   *     production behavior with this when you want them excluded from\n   *     a future `--mock-only` mode; today the tag is a no-op gate.\n   *   - `webhook_receiver` — the runner must be configured with a\n   *     webhook receiver (`StoryboardRunOptions.webhook_receiver`).\n   *     Autodetected from token presence: any step whose\n   *     `sample_request` (or nested fields) references\n   *     `{{runner.webhook_url:<step_id>}}` or `{{runner.webhook_base}}`\n   *     declares this requirement implicitly. Authors do not need to\n   *     write `requires: [webhook_receiver]` — the tokens are\n   *     self-describing.\n   *   - `webhook_replay_receiver` — the runner must be configured with an\n   *     inbound buyer/orchestrator receiver URL\n   *     (`StoryboardRunOptions.webhook_replay_receiver.url`). Autodetected\n   *     from any `replay_webhook_vector` step and graded not applicable when\n   *     absent. Spec: adcp-client#2356.\n   *   - `trusted_match_context_router_runner` — the runner must be configured\n   *     with a raw Context Match router URL and operator registration seam.\n   *     Autodetected from `replay_trusted_match_context_vector`; absent\n   *     harnesses grade not_applicable. Spec: adcp-client#2479.\n   *   - `trusted_match_publisher_auth_runner` — the operator supplies exact\n   *     publisher-facing Context/Identity URLs and declarative absent/invalid\n   *     credential configuration. The SDK owns the guarded raw HTTPS probes.\n   *     Capability applicability is evaluated before this requirement, so a\n   *     non-TMP agent grades not_applicable rather than requirement_unmet.\n   *     Spec: adcp-client#2526.\n   *   - `request_signer` — the agent under test MUST advertise\n   *     `request_signing.supported: true` in `get_adcp_capabilities`.\n   *     Autodetected: any storyboard whose `id === 'signed_requests'`\n   *     or contains a `request_signing_probe` step implicitly requires\n   *     this. Skipped (storyboard not applicable) when the agent omits\n   *     the capability claim — absence is a declaration that the agent\n   *     does not offer verified signed requests, per\n   *     `compliance/{version}/universal/signed-requests.yaml` gating\n   *     (\"Agents that do not advertise support are not tested against\n   *     this storyboard — absence of advertisement is not a failure\").\n   *     Spec: adcp-client#1702.\n   *   - `multi_agent` — the run must be configured with\n   *     `StoryboardRunOptions.agents`, and the storyboard's authored\n   *     route keys (`default_agent` plus any step-level `agent:` overrides)\n   *     must resolve to at least two distinct entries in that agents map.\n   *     This checks the routed topology the storyboard actually declares,\n   *     not the raw number of available agents. Spec: adcp-client#2281.\n   *\n   * Default when the field is absent: `[real_wire]` (storyboard runs\n   * everywhere — matches existing pre-tagging behavior). Tagging is\n   * additive opt-in; loader rejects malformed values and an empty array\n   * (`requires: []`) so authoring mistakes fail loud. Unknown string\n   * requirements are forward-compatible: they load successfully, then skip\n   * at runtime with `skip_reason: 'requirement_unmet'` and the authored name\n   * on `RunnerSkipResult.requirement`.\n   *\n   * Spec: adcp-client#1626, adcp-client#2281. The schema may be proposed upstream to\n   * `adcontextprotocol/adcp` once it has bedded in across SDK\n   * storyboards.\n   */\n  requires?: string[];\n  /**\n   * Predicate evaluated against the agent's declared capabilities before any\n   * phase runs. When the predicate is false, the runner emits a single\n   * `{ skipped: true, skip_reason: 'capability_unsupported' }` storyboard\n   * result instead of running phases — avoiding misleading per-phase failures\n   * when the storyboard tests behavior the agent explicitly opted out of.\n   *\n   * `path` is a dotted key path into the raw `get_adcp_capabilities` response\n   * (e.g. `\"adcp.idempotency.supported\"`).\n   *\n   * Four matcher forms — mutually exclusive on a single gate:\n   *\n   * - `equals: V` — scalar equality. The path's resolved value must be\n   *   declared and must equal `V` for the storyboard to run. When the path\n   *   resolves to `undefined` (field absent), the storyboard is skipped as\n   *   `capability_unsupported` unless the `get_adcp_capabilities` response\n   *   schema declares a default for that exact path and the parent capability\n   *   object is present.\n   *\n   * - `present: true|false` — presence-only matcher for spec capabilities whose\n   *   contract is \"presence of this object indicates support\" (e.g.\n   *   `media_buy.conversion_tracking`). `present: true` requires the value at\n   *   `path` to exist (non-null, non-undefined); empty object `{}` counts as\n   *   present. `present: false` requires the value to be absent — useful for\n   *   scenarios that only apply to agents that explicitly do NOT advertise a\n   *   capability. Unlike `equals`, absence is the load-bearing signal: when\n   *   `present: true` and the field is missing, the storyboard is skipped\n   *   (not_applicable) rather than run, because the seller's silence is the\n   *   spec-defined opt-out. Schema defaults are NOT materialized for this\n   *   matcher (unlike `equals`/`contains`): a default would make a defaulted\n   *   field never read as absent, defeating the gate.\n   *\n   * - `contains: V` — array-membership matcher for capabilities whose\n   *   declaration shape is an array of allowed values (e.g.\n   *   `media_buy.conversion_tracking.supported_targets: [\"cost_per\",\n   *   \"per_ad_spend\"]`). The value at `path` MUST be an array and MUST include\n   *   `V` (structural JSON equality, no coercion). Empty arrays fail; paths resolving\n   *   to undefined or non-array values fail unless the `get_adcp_capabilities`\n   *   response schema declares a default for that exact path and the parent\n   *   capability object is present. Like `present:`, absence is otherwise the\n   *   load-bearing signal — a seller that doesn't advertise the array hasn't\n   *   opted into the variant this storyboard tests.\n   *\n   * - `not_contains: V` — negative array-membership matcher. The value at\n   *   `path` MUST be an array and MUST NOT include `V` (structural JSON equality, no\n   *   coercion). This is useful for rejection scenarios that apply only when\n   *   an advertised allowlist omits a value. Missing and non-array values do\n   *   not satisfy the predicate; a separate discovery validation should grade\n   *   a required capability declaration. Schema defaults are materialized on\n   *   the same terms as `contains`.\n   *\n   * When `raw_capabilities` is not available and the discovered profile does\n   * not expose `get_adcp_capabilities`, `equals` gates are treated as\n   * unsupported because there is no declaration proving the agent opted into\n   * the behavior. Other matcher forms remain a no-op without raw capabilities\n   * unless the storyboard contract explicitly requires a raw opt-in (currently\n   * `experimental_features contains trusted_match.core`).\n   */\n  requires_capability?: RequiresCapabilityPredicate;\n  /**\n   * Two or more capability predicates evaluated as one AND-composed\n   * applicability gate. When this field and `requires_capability` are both\n   * present, every predicate across both declarations must pass. A failed\n   * predicate skips the entire storyboard before runtime or tool gates.\n   *\n   * The loader rejects empty and single-entry arrays; use\n   * `requires_capability` for a singular gate.\n   *\n   * Compound gates fail closed when the raw capabilities payload is\n   * unavailable: advertised or auto-registered tools are not capability\n   * declarations. This is intentionally stricter than the compatibility\n   * fallback retained for legacy singular gates.\n   *\n   * Supported by @adcp/sdk starting in 14.0.0-beta.4.\n   */\n  requires_all_capabilities?: RequiresCapabilityPredicate[];\n  /** Scenario IDs that must pass alongside this storyboard (loaded from storyboards/scenarios/) */\n  requires_scenarios?: string[];\n  agent: {\n    interaction_model: string;\n    capabilities: string[];\n    examples?: string[];\n  };\n  caller: {\n    role: string;\n    example?: string;\n  };\n  prerequisites?: {\n    description: string;\n    test_kit?: string;\n    /**\n     * When true and the storyboard carries a top-level `fixtures:` block,\n     * the runner fires `comply_test_controller` seed_* calls for each fixture\n     * entry before phase 1. Spec: adcontextprotocol/adcp#2585 (fixtures block)\n     * + adcontextprotocol/adcp#2584 (seed_* scenarios). Opts-out per run via\n     * `StoryboardRunOptions.skip_controller_seeding` (for agents that seed via\n     * tests or HTTP admin rather than the MCP controller).\n     */\n    controller_seeding?: boolean;\n  };\n  /**\n   * Fixture entries consumed by the runner's pre-flight controller seeding\n   * (see `prerequisites.controller_seeding`). Each entry is split into id\n   * params + a `fixture` body before being issued as a `seed_*` scenario on\n   * `comply_test_controller`. Entries are spec-shaped objects drawn from the\n   * source storyboard YAML; the runner preserves every field besides the id\n   * field(s) into `params.fixture` verbatim.\n   */\n  fixtures?: StoryboardFixtures;\n  /**\n   * AdCP 3.2 fixture-handle resolution policy. Fixture ids remain authored in\n   * `fixtures:` and in step payloads, but declarations here may allow the\n   * runner to bind those run-scoped handles to real seller catalog ids.\n   * Omitted handles retain the compatibility strategy `[\"seed\"]`.\n   */\n  fixture_resolution?: StoryboardFixtureResolution;\n  /**\n   * Initial context values declared by the storyboard YAML. Runner callers may\n   * override these defaults with `StoryboardRunOptions.context`.\n   */\n  context?: StoryboardContext;\n  phases: StoryboardPhase[];\n  /**\n   * Cross-step assertions that apply to this storyboard. Every assertion\n   * registered with `default: true` (the bundled set: `status.monotonic`,\n   * `idempotency.conflict_no_payload_leak`, `context.no_secret_echo`,\n   * `governance.denial_blocks_mutation`) runs by default — omit the field\n   * entirely and the full default set applies. Per-step checks live inline\n   * on steps; assertions encode specialism- or protocol-wide properties\n   * that must hold across the full run.\n   *\n   * Three shapes are accepted:\n   *   - `undefined` (or field omitted) — run every default-on assertion.\n   *   - `string[]` — legacy additive form. Defaults still run; any ids in\n   *     the list register on top for storyboards that want extra non-default\n   *     assertions registered by the consumer. Every id MUST resolve.\n   *   - `{ disable?: string[]; enable?: string[] }` — object form. `disable`\n   *     removes default-on assertions by id (typo-guarded: unknown ids throw\n   *     at runner start); `enable` adds non-default assertions registered by\n   *     the consumer on top.\n   *\n   * See `./assertions.ts` for the registry API and `./default-invariants.ts`\n   * for the bundled set.\n   */\n  invariants?: StoryboardInvariants;\n}\n\nexport interface RequiredToolFamily {\n  tools: [string, string, ...string[]];\n  rationale?: string;\n}\n\n/**\n * Storyboard-level invariants declaration. `undefined` / array / object\n * shapes all map onto the same \"resolve to AssertionSpec[]\" path in\n * `resolveAssertions(...)`. See `Storyboard.invariants` for the full\n * semantics (bundled defaults are always applied unless explicitly\n * disabled via the object form).\n */\nexport type StoryboardInvariants = string[] | StoryboardInvariantsObject;\n\nexport interface StoryboardInvariantsObject {\n  /**\n   * Default-on assertion ids to suppress for this storyboard. Each id MUST\n   * match an assertion registered with `default: true` — an unknown or\n   * non-default id is a typo and fails fast at runner start rather than\n   * silently no-opping (which would mask genuine coverage gaps).\n   */\n  disable?: string[];\n  /**\n   * Additional (non-default) assertion ids to enable for this storyboard on\n   * top of the default-on set. Consumers use this to attach custom\n   * assertions they've registered via `registerAssertion(...)`. Every id\n   * MUST resolve; unknown ids fail fast at runner start.\n   */\n  enable?: string[];\n}\n\n/**\n * Per-step invariant opt-out. Mirrors `StoryboardInvariantsObject.disable`\n * but scoped to a single step — the runner skips calling the named\n * assertions' `onStep` for that step only. Use when a step deliberately\n * models behavior a default invariant would otherwise flag (e.g. a\n * `check_governance` 200 `status: denied` setting up a buyer-recovery\n * sequence that the `governance.denial_blocks_mutation` invariant would\n * anchor).\n *\n * Step-level is narrower on purpose — there is no `enable`. Enabling an\n * assertion for a single step makes no sense at this scope (assertions\n * reason across steps), and disallowing it at the type level removes a\n * footgun. Only `disable` is accepted.\n *\n * Every id in `disable` MUST be in the assertion set resolved for this\n * run. An unknown id, or an id already suppressed storyboard-wide, is\n * dead code and fails fast at runner start rather than silently no-op.\n *\n * Semantics for stateful invariants: disable means the invariant does\n * not OBSERVE the step. Invariants that accumulate per-step state\n * (e.g. `status.monotonic`'s last-observed transition anchor) will\n * therefore miss any observation the disabling step would have\n * contributed. That's the point for `governance.denial_blocks_mutation`\n * (a deliberate setup is not an anchor); for accumulator-style\n * invariants, prefer disabling run-wide if the missed observation\n * would hide later violations.\n */\nexport interface StepInvariantsObject {\n  disable?: string[];\n}\n\n/**\n * Fixture entries the runner seeds into the seller via `comply_test_controller`\n * pre-flight (adcp#2585, adcp#2743). Each array entry carries its id field(s)\n * alongside the body the runner forwards into `params.fixture` for the\n * corresponding `seed_*` scenario.\n *\n *   - `accounts[]`      → `seed_account`         — requires `account_id`\n *   - `products[]`      → `seed_product`         — requires `product_id`\n *   - `pricing_options[]` → `seed_pricing_option` — requires `product_id` + `pricing_option_id`\n *   - `creative_formats[]` → `seed_creative_format` — requires `format_id`\n *   - `creatives[]`     → `seed_creative`        — requires `creative_id`\n *   - `plans[]`         → `seed_plan`            — requires `plan_id`\n *   - `media_buys[]`    → `seed_media_buy`       — requires `media_buy_id`\n *   - `buyer_agents[]`  → `seed_buyer_agent`     — requires `agent_url`\n *\n * For entity fixtures, every other field on the entry is forwarded verbatim\n * as `params.fixture`. For `buyer_agents[]`, every other field is forwarded\n * as a direct `params` field because the controller scenario models the\n * buyer-agent record itself (`billing_capabilities`, `status`, etc.).\n * Entries without their required id field produce a pre-flight error so the\n * authoring mistake is surfaced before any real step runs.\n */\nexport interface StoryboardFixtures {\n  accounts?: Array<Record<string, unknown> & { account_id?: string }>;\n  products?: Array<Record<string, unknown> & { product_id?: string }>;\n  pricing_options?: Array<Record<string, unknown> & { product_id?: string; pricing_option_id?: string }>;\n  creative_formats?: Array<Record<string, unknown> & { format_id?: string; fixture?: unknown }>;\n  creatives?: Array<Record<string, unknown> & { creative_id?: string }>;\n  plans?: Array<Record<string, unknown> & { plan_id?: string }>;\n  media_buys?: Array<Record<string, unknown> & { media_buy_id?: string }>;\n  buyer_agents?: StoryboardBuyerAgentFixture[];\n}\n\n/** Ordered setup strategies supported by the first AdCP 3.2 runner slice. */\nexport type FixtureResolutionStrategy = 'seed' | 'discover';\n\n/** Operators supported by the closed AdCP 3.2 fixture predicate DSL. */\nexport type FixtureMatchOperator = 'equals' | 'present' | 'contains_all' | 'any_match' | 'canonical_format_satisfies';\n\nexport interface FixtureCanonicalFormatSelector extends Record<string, unknown> {\n  format_kind: string;\n  params?: Record<string, unknown>;\n}\n\n/**\n * One fixture-discovery predicate. `path` is an RFC 6901 JSON Pointer\n * relative to the candidate entity. `any_match` uses `where` recursively,\n * `present` is valueless, and the remaining operators use `value`.\n */\nexport type FixtureMatchClause =\n  | { path: string; operator: 'equals'; value: unknown; where?: never }\n  | { path: string; operator: 'present'; value?: never; where?: never }\n  | { path: string; operator: 'contains_all'; value: unknown[]; where?: never }\n  | { path: string; operator: 'canonical_format_satisfies'; value: FixtureCanonicalFormatSelector; where?: never }\n  | { path: string; operator: 'any_match'; where: FixtureMatchClause[]; value?: never };\n\nexport interface FixtureResolutionDeclaration {\n  /** Authored run-scoped fixture handle. */\n  handle: string;\n  /** Ordered strategy ladder. Omission means `[\"seed\"]`. */\n  strategies?: FixtureResolutionStrategy[];\n  /** Requirements a discovered seller entity must satisfy. */\n  match?: FixtureMatchClause[];\n  /** Default false: one seller entity cannot satisfy two handles. */\n  allow_reuse?: boolean;\n}\n\nexport type ProductFixtureResolutionDeclaration = FixtureResolutionDeclaration;\n\nexport interface PricingOptionFixtureResolutionDeclaration extends FixtureResolutionDeclaration {\n  /** Parent authored product handle for root-level pricing-option declarations. */\n  product_handle: string;\n}\n\nexport interface StoryboardFixtureResolution {\n  products?: ProductFixtureResolutionDeclaration[];\n  pricing_options?: PricingOptionFixtureResolutionDeclaration[];\n}\n\nexport type FixtureResolutionStatus = 'resolved' | 'unsatisfied' | 'failed';\n\nexport interface FixtureResolutionAttempt {\n  strategy: FixtureResolutionStrategy;\n  disposition: 'resolved' | 'unavailable' | 'failed';\n  detail: string;\n  request?: Record<string, unknown>;\n  response?: unknown;\n}\n\n/** @deprecated Use FixtureResolutionAttempt. */\nexport type FixtureResolutionEvidence = FixtureResolutionAttempt;\n\n/** Machine-readable record emitted exactly once for every fixture handle. */\nexport interface FixtureResolutionRecord {\n  fixture_type: 'product' | 'pricing_option';\n  handle: string;\n  product_handle?: string;\n  requirements: FixtureMatchClause[];\n  strategies_attempted: FixtureResolutionAttempt[];\n  status: FixtureResolutionStatus;\n  strategy?: FixtureResolutionStrategy;\n  seller_ids?: {\n    product_id: string;\n    pricing_option_id?: string;\n  };\n}\n\n/** One storyboard-scoped coverage gap produced by fixture resolution. */\nexport interface FixtureResolutionCoverageGap {\n  reason: 'fixture_unsatisfied';\n  detail: string;\n  fixtures: Array<{\n    fixture_type: FixtureResolutionRecord['fixture_type'];\n    handle: string;\n    product_handle?: string;\n    requirements: FixtureMatchClause[];\n  }>;\n}\n\nexport interface StoryboardBuyerAgentFixture {\n  agent_url?: string;\n  display_name?: string;\n  status?: BuyerAgentStatus;\n  billing_capabilities?: BuyerAgentBillingMode[];\n  default_account_terms?: BuyerAgent['default_account_terms'];\n  allowed_brands?: string[];\n  aliases?: string[];\n  sandbox_only?: boolean;\n  [key: string]: unknown;\n}\n\nexport interface StoryboardPhase {\n  id: string;\n  title: string;\n  narrative?: string;\n  steps: StoryboardStep[];\n  /** When true, the phase is allowed to be skipped without failing the storyboard. */\n  optional?: boolean;\n  /**\n   * Predicate evaluated against the agent's declared capabilities before this\n   * phase is set up or any of its steps are dispatched. Uses the same matcher\n   * dialect as `Storyboard.requires_capability` (`equals`, `present`,\n   * `contains`). When false, every step in the phase is emitted as a\n   * `not_applicable` skip and the runner continues with later phases.\n   */\n  requires_capability?: RequiresCapabilityPredicate;\n  /**\n   * Phases this phase depends on for stateful cascade purposes (#1161).\n   *\n   * When ANY listed phase tripped its stateful cascade (a stateful step\n   * failed or skipped for a missing-state reason), every stateful step in\n   * THIS phase cascade-skips with `prerequisite_failed`. When all listed\n   * phases passed their stateful steps, this phase runs normally even if\n   * other unrelated phases tripped — the runner treats independent phases\n   * independently.\n   *\n   * **Default semantics (field absent or undefined): \"all prior phases.\"**\n   * Backward-compatible with the storyboard-scope cascade behavior that\n   * predates #1161 — every phase implicitly depends on every prior phase.\n   * The F6 round-2 cross-phase pattern (e.g. `signal_marketplace/\n   * governance_denied`: setup in phases 1-2, consumption in phase 3) is\n   * preserved without YAML changes.\n   *\n   * **Independent phase: `depends_on: []`** — explicitly declares this\n   * phase has no upstream dependencies and will run even if every prior\n   * phase tripped its cascade. Use for phases whose state derives from\n   * the request body alone (e.g., `audience_sync` carrying its own\n   * account ref via brand+operator) rather than from prior phase state.\n   *\n   * **Targeted dependency: `depends_on: ['phase_id', ...]`** — only the\n   * named phases gate this phase's cascade. Other phases tripping is\n   * irrelevant.\n   *\n   * Listed phase IDs MUST exist in the same storyboard and MUST be\n   * declared earlier in the `phases[]` array (forward references and\n   * self-references are rejected at parse time). Empty list is legal and\n   * means \"no dependencies.\"\n   */\n  depends_on?: string[];\n  /**\n   * Skip expression evaluated against the runtime context. Current grammar:\n   *   - `\"!test_kit.auth.api_key\"` — true when field is missing/falsy\n   *   - `\"test_kit.auth.api_key\"`  — true when field is present/truthy\n   * Other expressions are rejected (unknown → fail closed: phase runs).\n   */\n  skip_if?: string;\n  /**\n   * First-class branch-set declaration (see adcp#2633 / adcp#2646). When\n   * present, contributing steps inside this phase MAY use the boolean\n   * shorthand `contributes: true` in lieu of repeating `contributes_to: <id>`.\n   * The loader resolves the shorthand to `branch_set.id` at parse time, so\n   * downstream runner code continues to read `step.contributes_to`.\n   */\n  branch_set?: BranchSetSpec;\n}\n\nexport interface BranchSetSpec {\n  /** Aggregation flag shared by every contributing step in this phase. */\n  id: string;\n  /**\n   * Grading semantics for the branch set. `any_of` (the only value defined\n   * today) means: at most one peer branch is expected to contribute; failures\n   * in non-contributing peers grade as `peer_branch_taken` rather than\n   * `failed`. Kept as a string so future semantics (`all_of`, `one_of`) do\n   * not require a type change.\n   */\n  semantics: string;\n}\n\nexport interface ContextOutput {\n  /**\n   * JSON path to extract from the response. Mutually exclusive with\n   * `generate` — exactly one of `path` or `generate` must be set.\n   */\n  path?: string;\n  /**\n   * Generator name. When set, the runner mints a fresh opaque value\n   * once per run (or reuses a value already minted for the same `key`\n   * alias via an inline `$generate:…#<alias>` substitution in the same\n   * step's `sample_request`). Mutually exclusive with `path`. The loader\n   * rejects unknown values at storyboard-load time so typos fail loud\n   * before the first run.\n   */\n  generate?: 'uuid_v4' | 'opaque_id';\n  /** Key to store the extracted or generated value under in context */\n  key: string;\n}\n\nexport interface ContextInput {\n  /** Key to look up in context */\n  key: string;\n  /** JSON path in the request to inject the value at */\n  inject_at: string;\n}\n\n/**\n * Per-step authentication override. Lets a step probe the agent with\n * different credentials than the rest of the run — required for the\n * `security_baseline` storyboard's unauthenticated and invalid-key probes.\n */\nexport type StepAuthDirective =\n  /** Strip transport credentials entirely. The step MUST hit the agent unauthenticated. */\n  | 'none'\n  | {\n      type: 'api_key';\n      /** Literal Bearer value sent as `Authorization: Bearer <value>`. */\n      value?: string;\n      /** Pull the value from the runtime `test_kit.auth.api_key` field. */\n      from_test_kit?: boolean;\n      /**\n       * Runner-generated value. Current strategies:\n       *   - `random_invalid` — `invalid-<32 hex bytes>`, fresh per run.\n       */\n      value_strategy?: 'random_invalid';\n    }\n  | {\n      type: 'oauth_bearer';\n      /** Literal Bearer value. */\n      value?: string;\n      /**\n       * Runner-generated value. Current strategies:\n       *   - `random_invalid_jwt` — three base64url segments; valid JSON header/payload, random signature.\n       */\n      value_strategy?: 'random_invalid_jwt';\n    }\n  | {\n      type: 'basic';\n      /** Pull the Basic credential object from the runtime test kit, e.g. `auth.basic`. */\n      from_test_kit?: string | boolean;\n      /** Explicit username. Mutually exclusive with `credentials`. */\n      username?: string;\n      /** Explicit password. Mutually exclusive with `credentials`. */\n      password?: string;\n      /** Unencoded `username:password` pair. Mutually exclusive with `username`/`password`. */\n      credentials?: string;\n      /** Nested Basic credential shape accepted for authoring parity with test kits. */\n      basic?: {\n        username?: string;\n        password?: string;\n        credentials?: string;\n      };\n      /**\n       * Runner-generated value. Current strategies:\n       *   - `random_invalid` — random username/password pair.\n       */\n      value_strategy?: 'random_invalid';\n    };\n\nexport interface StoryboardStep {\n  id: string;\n  title: string;\n  narrative?: string;\n  /**\n   * AdCP task name (snake_case), e.g. \"sync_accounts\", \"get_products\".\n   * May reference a test-kit field with `\"$test_kit.<path>\"` — the runner\n   * resolves to the value at that path, or to `task_default` when the kit\n   * doesn't supply the field.\n   */\n  task: string;\n  /** Fallback task name when `task` is a `$test_kit.*` reference that resolves to null/undefined. */\n  task_default?: string;\n  /**\n   * Explicit per-step routing for multi-agent runs\n   * (`StoryboardRunOptions.agents`). Must reference a key in the agents\n   * map; the runner sends this step to that agent regardless of\n   * `TASK_FEATURE_MAP` resolution.\n   *\n   * This is the canonical primitive for cross-specialism storyboards —\n   * NOT just an escape hatch. A `signal_marketplace/governance_denied`\n   * storyboard NEEDS `agent: governance` on its `sync_governance` step\n   * and `agent: signals` on its `activate_signal` step because those\n   * tools are owned by different specialisms; protocol-based routing\n   * resolves them automatically when the agents map has unique\n   * claimants, but explicit `agent:` is the documentation-friendly form\n   * for storyboard authors who want the routing intent visible at the\n   * step level.\n   *\n   * Also used to disambiguate cross-domain tools (`sync_creatives`,\n   * `list_creative_formats`) when the agents map has multiple claimants\n   * for the same specialism and the runner's protocol-index can't pick\n   * one. Ignored when `agents` is unset. Adcp-client#1066.\n   */\n  agent?: string;\n  schema_ref?: string;\n  response_schema_ref?: string;\n  doc_ref?: string;\n  /** Maps to existing @adcp/sdk test scenario (legacy, partial coverage) */\n  comply_scenario?: string;\n  /**\n   * Select the SDK response projection used for this step. `raw` is reserved\n   * for compatibility storyboards that must grade both legacy and canonical\n   * fields from the same seller response without changing the request wire.\n   */\n  response_projection?: 'raw';\n  /** Whether this step depends on state from a previous step */\n  stateful?: boolean;\n  /**\n   * Declares that this step's pass establishes equivalent state for one or\n   * more peer steps in the same phase. When a target peer skips with\n   * `missing_tool` or `missing_test_controller` (no advertised tool),\n   * the runner defers the cascade and waives it iff this substitute step\n   * passes. Same-phase only; cross-phase substitution is not supported.\n   *\n   * Canonical case: `list_accounts` declares `provides_state_for:\n   * sync_accounts` on explicit-mode social platforms where the buyer never\n   * calls `sync_accounts` because accounts are pre-provisioned out-of-band.\n   *\n   * Without this declaration, a `missing_tool` skip on a stateful step\n   * trips the cascade immediately (state genuinely never materialized).\n   * With it, the runner gives a declared substitute a chance to establish\n   * equivalent state before tripping. When the rescue fires, the target\n   * peer is graded with `skip_reason: 'peer_substituted'` and detail\n   * `\"<target_step_id> state provided by <phase_id>.<substitute_step_id>\"`\n   * per `runner-output-contract.yaml`.\n   *\n   * Use `string[]` for the bulk case (`provides_state_for: [A, B]` is\n   * ALL-OF — one substitute pass establishes state for both A and B).\n   *\n   * Spec source: `compliance/cache/{version}/universal/storyboard-schema.yaml`\n   * (adcp#3734, AdCP 3.0.3+).\n   */\n  provides_state_for?: string | string[];\n\n  /**\n   * @deprecated Renamed to `provides_state_for` to align with the AdCP 3.0.3\n   * spec field (adcp#3734). The old name is still accepted at parse time for\n   * one minor cycle. New storyboards SHOULD use `provides_state_for`. Slated\n   * for removal in the next major.\n   */\n  peer_substitutes_for?: string | string[];\n  /** When true, the step passes if the task returns an error */\n  expect_error?: boolean;\n  /**\n   * Per-step invariant opt-out. See `StepInvariantsObject`. Use when a\n   * specific step deliberately trips a default invariant (e.g. a\n   * `check_governance` 200 `status: denied` that is the setup for a\n   * buyer-recovery sequence, which `governance.denial_blocks_mutation`\n   * would otherwise anchor for the remainder of the run).\n   */\n  invariants?: StepInvariantsObject;\n  /**\n   * When true, suppress the runner's `idempotency_key` auto-injection on a\n   * mutating step so the storyboard can exercise the server's missing-key\n   * rejection path. The runner also disables the SDK's client-side\n   * auto-inject for this step so the request reaches the wire without a key.\n   *\n   * Default (false) matches buyer-agent behavior: every mutating request\n   * carries a fresh UUID v4 so handlers under test run against the actual\n   * error path the storyboard names (GOVERNANCE_DENIED, UNAUTHORIZED, etc.)\n   * rather than short-circuiting on `INVALID_REQUEST: idempotency_key`.\n   */\n  omit_idempotency_key?: boolean;\n  /**\n   * When true, suppress the runner's `account` auto-injection on a\n   * `create_media_buy` step so the storyboard can exercise the server's\n   * missing-account rejection path. Without this flag the runner's\n   * `applyBrandInvariant` synthesises an `account` field before the wire\n   * call (both the natural-key-merge branch and the synthetic-construction\n   * branch), and the SDK's client-side normalizer also throws before the\n   * wire call — both layers are suppressed so the seller sees the request\n   * exactly as authored in `sample_request`.\n   *\n   * Only applicable to `create_media_buy` (the sole tool where `account` is\n   * required by `normalizeRequestParams`). Setting it on any other task type\n   * has no effect and is ignored.\n   *\n   * **Caveat:** this flag does not suppress `account` enrichment performed by\n   * `request-builder.ts` for tasks such as `update_media_buy`. If a future\n   * storyboard step needs to test missing-account rejection on a\n   * request-builder-enriched task, the builder will also need updating.\n   *\n   * Must be paired with `expect_error: true` — the loader rejects steps that\n   * set `omit_account: true` without the flag, because an accountless\n   * `create_media_buy` will always fail and a missing `expect_error` produces\n   * a misleading compliance result.\n   *\n   * Default (false) matches buyer-agent behavior: every `create_media_buy`\n   * request carries an `account` so handlers under test run against the\n   * actual error path the storyboard names rather than short-circuiting on\n   * `INVALID_REQUEST: account`.\n   *\n   * @internal Do not set in production buyer code.\n   */\n  omit_account?: boolean;\n  /** Tool name required for this step to run. Skipped if agent lacks it. */\n  requires_tool?: string;\n  /** Explicit context extraction rules (supplements convention-based extractors) */\n  context_outputs?: ContextOutput[];\n  /** Explicit context injection rules (supplements $context.key placeholders) */\n  context_inputs?: ContextInput[];\n  expected?: string;\n  sample_request?: Record<string, unknown>;\n  sample_response?: Record<string, unknown>;\n  /**\n   * Response-derived gates evaluated after the step's request completes but\n   * before validations/context captures run. Use when applicability is only\n   * knowable from the observed response, not from static capabilities.\n   *\n   * Current gate kind:\n   *   - `terminal_page`: if the response proves the requested page is terminal,\n   *     grade the step `not_applicable` instead of failing continuation-only\n   *     assertions. This supports pagination-walk storyboards for sellers whose\n   *     full result set fits in one page.\n   */\n  not_applicable_if?: ResponseNotApplicableGate | ResponseNotApplicableGate[];\n  validations?: StoryboardValidation[];\n  /** Override auth for this step only (see `StepAuthDirective`). */\n  auth?: StepAuthDirective;\n  /** Contribute a flag to the run-level accumulator on success. Used with `any_of` validations downstream. */\n  contributes_to?: string;\n  /**\n   * Boolean shorthand for `contributes_to: <enclosing phase's branch_set.id>`.\n   * Only legal inside a phase that declares `branch_set:`. The loader\n   * resolves `contributes: true` to the phase's `branch_set.id` and clears\n   * this field, so runner code reads `contributes_to` exclusively.\n   * `contributes: false` (or absent) marks a non-contributing step.\n   * Declaring both `contributes` and `contributes_to` on the same step is a\n   * parse-time authoring error.\n   */\n  contributes?: boolean;\n  /**\n   * Conditional contribution expression. Current grammar:\n   *   - `\"prior_step.<step_id>.passed\"` — contribution fires only if the named step passed.\n   * Unknown expressions → the contribution does NOT fire (fail closed).\n   */\n  contributes_if?: string;\n  // ──────────────────────────────────────────────────────────\n  // Webhook-assertion step fields (only used when task is one\n  // of `expect_webhook`, `expect_no_webhook`,\n  // `expect_webhook_retry_keys_stable`, or\n  // `expect_webhook_signature_valid`). The runner interprets\n  // these pseudo-tasks as receiver observations, not agent calls.\n  // ──────────────────────────────────────────────────────────\n  /**\n   * Step id of the earlier step whose task triggered the webhook under\n   * observation. Used by compliance reports for attribution and (when the\n   * trigger step failed / skipped) to gate the assertion skip.\n   */\n  triggered_by?: string;\n  /** Match predicate scoped to the per-step URL and/or body fields. */\n  filter?: WebhookFilterSpec;\n  /** Seconds to observe for a matching delivery. Default 5 for `expect_no_webhook`, otherwise 30. */\n  timeout_seconds?: number;\n  /** When true (default) assert `idempotency_key` is present and pattern-valid. */\n  expect_idempotency_key?: boolean;\n  /** Optional webhook schema reference; validates the parsed body. */\n  webhook_payload_schema_ref?: string;\n  /** Back-compat alias for older local storyboards. Prefer `webhook_payload_schema_ref`. */\n  response_schema_webhook_ref?: string;\n  /**\n   * Cap on the number of distinct logical webhook events (grouped by\n   * idempotency_key) delivered within the timeout window. Typical use:\n   * `1` on the replay-side-effect invariant to catch publishers that\n   * re-execute on replay and emit a second webhook under a fresh key.\n   */\n  expect_max_deliveries_per_logical_event?: number;\n  /**\n   * Test-kit contract id this assertion depends on. When the contract is\n   * not in scope the step grades `not_applicable` rather than failing —\n   * lets cross-cutting storyboards (idempotency, governance) reference\n   * webhook assertions without forcing every runner to host a receiver.\n   */\n  requires_contract?: string;\n  /** Retry-replay config for `expect_webhook_retry_keys_stable`. */\n  retry_trigger?: WebhookRetryTriggerSpec;\n  /** Min deliveries to observe for `expect_webhook_retry_keys_stable`. Default 2. */\n  expect_min_deliveries?: number;\n  /** Signature-tag sanity check for `expect_webhook_signature_valid`. Default `adcp/webhook-signing/v1`. */\n  require_tag?: string;\n  // ──────────────────────────────────────────────────────────\n  // Webhook receiver replay step fields (only used when task is\n  // `replay_webhook_vector`). The runner sends a canonical webhook POST to\n  // a buyer/orchestrator receiver under test; it does not call the seller.\n  // ──────────────────────────────────────────────────────────\n  /** Compliance vector reference, e.g. `static/test-vectors/webhook-receiver-envelope.json#positive/foo`. */\n  vector_ref?: string;\n  /** Earlier step id that represents the same logical event retry. */\n  same_event_as?: string;\n  /** Expected receiver error label from the vector metadata, when present. */\n  expected_error?: string;\n  /**\n   * Fan-out spec for parallel-dispatch steps. When set, the runner fires\n   * `count` concurrent dispatches of this step (single-process,\n   * `Promise.all`) against the same agent, then aggregates per-response\n   * checks across the resolved set and grades the `cross_response_*`\n   * checks declared in `validations`. Requires the\n   * `parallel_dispatch_runner` test-kit contract to be in scope — runners\n   * (or runs) without it grade the step `not_applicable`. See\n   * {@link ParallelDispatchSpec}.\n   */\n  parallel_dispatch?: ParallelDispatchSpec;\n  /**\n   * Sequential rate-limit trip/replay probe config. When set on\n   * `expect_rate_limit_not_replayed`, the runner sends fresh-key requests\n   * until the seller returns `RATE_LIMITED`, waits the response\n   * `retry_after`, then replays the same idempotency key to assert the\n   * transient rate-limit response was not cached as the canonical replay.\n   * Requires the `rate_limit_trip_runner` test-kit contract.\n   */\n  rate_limit_trip?: RateLimitTripSpec;\n}\n\n/**\n * Contract payload for `test-kits/rate-limit-trip-runner.yaml`.\n */\nexport interface RateLimitTripSpec {\n  /** Mutating AdCP task to burst, e.g. `create_media_buy`. */\n  trip_target_task: string;\n  /** Base request payload; the observer rewrites only idempotency_key and correlation_id. */\n  trip_target_sample_request: Record<string, unknown>;\n  /** Sequential fresh-key attempts before grading the probe `rate_limit_not_triggered`; must be in [50, 500]. */\n  max_attempts: number;\n  /** Maximum retry_after wait the runner will honor. Defaults to 30 seconds. */\n  replay_max_wait_seconds?: number;\n}\n\nexport type StoryboardValidationCheck =\n  | 'response_schema'\n  | 'field_present'\n  | 'field_absent'\n  // Envelope-scoped variants — the asserted path lives on the v3 protocol\n  // envelope (`status`, `task_id`, `message`, `replayed`, `governance_context`,\n  // `timestamp`, `context_id`, `push_notification_config`) rather than the\n  // inner response. Runtime semantics are identical to the un-prefixed checks\n  // (TaskResult merges envelope fields onto its surface); the distinction is\n  // for static drift detection, which walks `protocol-envelope.json` instead\n  // of the per-tool response schema. Added per adcp#3429.\n  | 'envelope_field_present'\n  | 'envelope_field_absent'\n  | 'envelope_field_value'\n  | 'envelope_field_value_or_absent'\n  | 'field_value'\n  | 'field_value_or_absent'\n  /**\n   * Assert that a string field in the task payload matches a JavaScript\n   * regular expression source declared in `pattern`. Fails when the path is\n   * missing, the value is not a string, the pattern is invalid, or the regex\n   * does not match. Failure output carries `expected: { pattern }` and\n   * `actual` as the observed value (or null when missing). Added for\n   * runner-output-contract v2.5.0.\n   */\n  | 'field_pattern'\n  /**\n   * Envelope-scoped `field_pattern`. The path resolves against the union of\n   * protocol-envelope fields (`status`, `task_id`, etc.) and string-valued\n   * version-envelope fields such as `adcp_version`. Runtime matching is the\n   * same as `field_pattern`; the distinct kind lets static linting validate\n   * against the envelope schemas instead of the task payload schema. Numeric\n   * envelope fields such as `adcp_major_version` should use\n   * `envelope_field_value`.\n   */\n  | 'envelope_field_pattern'\n  // Wildcard-aware membership check. `path` may include `[*]` or `[]`\n  // segments that expand to every array element via `resolvePathAll`.\n  // Passes when ANY resolved value matches `value` (or any of\n  // `allowed_values`). Object and array expectations are matched as deep\n  // subsets, so storyboards can assert keyed entries inside unordered arrays\n  // without hardcoding positions — e.g.,\n  // `creatives[0].errors[*].code = PROVENANCE_DISCLOSURE_MISSING` or\n  // `products[0].allowed_actions[]` with\n  // `{ action: \"increase_budget\", modes: [\"self_serve\"] }`.\n  // When the path has no wildcard segments this reduces to scalar equality\n  // / array membership depending on what the path resolves to.\n  | 'field_contains'\n  | 'status_code'\n  | 'error_code'\n  // HTTP-probe checks (for raw_probe tasks)\n  | 'http_status'\n  | 'http_status_in'\n  | 'on_401_require_header'\n  // Cross-cutting\n  | 'resource_equals_agent_url'\n  | 'oauth_metadata_graph'\n  | 'any_of'\n  // A2A wire-shape checks (transport-specific; skipped on non-A2A runs)\n  | 'a2a_submitted_artifact'\n  | 'a2a_context_continuity'\n  // Cross-step checks\n  | 'refs_resolve'\n  /**\n   * Assert a numeric field in the current step's response is strictly less than\n   * a comparand. The comparand is either a context-captured runtime value\n   * (`context_key` on `StoryboardValidation`) or a literal number (`value`).\n   * Fails with a type error when either operand is non-numeric or absent.\n   * When `context_key` is specified but the key is absent from `storyboardContext`,\n   * the check passes with a `context_key_absent` observation (prior step may have\n   * been legitimately skipped on a branch-set path).\n   * Added for adcp#2642 cross-step comparison primitives.\n   */\n  | 'field_less_than'\n  /**\n   * Assert a numeric field in the current step's response is strictly greater\n   * than a comparand. Mirror of `field_less_than` — completes the four-quadrant\n   * numeric comparison vocabulary (`<`, `<=`, `>=`, `>`). Same operand and\n   * `context_key_absent` semantics as `field_less_than`. Added for\n   * adcp-client#1839 four-quadrant symmetry.\n   */\n  | 'field_greater_than'\n  /**\n   * Assert a numeric field in the current step's response is at most (≤) a\n   * comparand. Semantically symmetric with `field_less_than` but with\n   * non-strict comparison — pairs cleanly with cap-style assertions like\n   * \"observed frequency stays at or below the requested cap of 3\".\n   * The comparand is either a context-captured runtime value (`context_key`)\n   * or a literal number (`value`). Fails with a type error when either\n   * operand is non-numeric or absent. When `context_key` is specified but\n   * absent from `storyboardContext`, passes with a `context_key_absent`\n   * observation. Added for adcp-client#1839.\n   */\n  | 'field_at_most'\n  /**\n   * Assert a numeric field in the current step's response is at least (≥) a\n   * comparand. Mirror of `field_at_most` — pairs with floor-style assertions\n   * like \"delivered reach ≥ promised reach\". Same operand and\n   * context_key_absent semantics as `field_at_most`. Added for\n   * adcp-client#1839.\n   */\n  | 'field_at_least'\n  /**\n   * Assert a field in the current step's response deep-equals a value captured\n   * from an earlier step via `context_key`. Unlike `field_value` + `$context.key`\n   * substitution (which resolves the comparand at YAML authoring time), this\n   * check compares against a runtime-captured value — suitable for asserting that\n   * a response echoes back an id or token that was only known at run time.\n   * When `context_key` is absent from `storyboardContext`, passes with a\n   * `context_key_absent` observation.\n   * Added for adcp#2642 cross-step comparison primitives.\n   */\n  | 'field_equals_context'\n  /**\n   * Assert a field in the current response is a member of an array captured\n   * from an earlier step via `context_key`. Missing context keeps the same\n   * branch-safe `context_key_absent` behavior as other cross-step checks;\n   * a present non-array context value fails the check.\n   */\n  | 'field_in_context_array'\n  /**\n   * Resolve every terminal value at a wildcard-aware response path and require\n   * each value to deep-equal a member of a context-captured array. An empty\n   * terminal set passes vacuously; missing context is branch-safe.\n   */\n  | 'all_fields_in_context_array'\n  /**\n   * Asserts upstream side-effects against the adopter's\n   * `comply_test_controller`'s `query_upstream_traffic` scenario. The\n   * load-bearing anti-façade contract: a fully-conformant adapter and a\n   * façade returning shape-valid AdCP responses with synthetic data are\n   * indistinguishable on the AdCP wire — only what the adapter caused\n   * upstream tells them apart. Adopters who do not advertise\n   * `query_upstream_traffic` in `list_scenarios` grade the check\n   * `not_applicable`. Adopters who do but return zero recorded calls in\n   * the assertion window grade `failed` (the façade signal). Spec:\n   * runner-output-contract.yaml v2.0.0, storyboard-schema.yaml >\n   * \"upstream_traffic\".\n   */\n  | 'upstream_traffic'\n  /** Contract check for `rate_limit_trip_runner`: RATE_LIMITED must not replay from the idempotency cache. */\n  | 'replay_not_cached_rate_limit'\n  /**\n   * Cross-response: every resolved response from a `parallel_dispatch` step\n   * carries the same value at the named `path`. Used to assert\n   * first-insert-wins on a concurrent retry — two parallel `create_media_buy`\n   * calls with the same `idempotency_key` must resolve to the same\n   * `media_buy_id`. Fails when any two resolved responses disagree, or when\n   * fewer than 2 dispatches resolved successfully. Spec:\n   * test-kits/parallel-dispatch-runner.yaml; adcp#4435 (rule 9 / rule 10).\n   */\n  | 'cross_response_field_equal'\n  /**\n   * Cross-response: the cardinality of distinct values at `path` across all\n   * resolved responses from a `parallel_dispatch` step is in\n   * `allowed_values`. Used to assert \"exactly one resource was created\" —\n   * `allowed_values: [1]` with `path: media_buy_id` catches a seller that\n   * raced the INSERT and created two resources from one logical create.\n   * Fails when the distinct count is outside `allowed_values`, or when no\n   * dispatch resolved successfully. Spec:\n   * test-kits/parallel-dispatch-runner.yaml.\n   */\n  | 'cross_response_count_distinct'\n  /**\n   * Assert that the `create_media_buy` package format selector outcome matches\n   * canonical product capability satisfaction rules. `value: true` means the\n   * request should be accepted because its selector satisfies the product's\n   * `format_options[]`; `value: false` means the request should be rejected\n   * because the selector does not satisfy those constraints.\n   *\n   * The validator uses the actual runner request plus prior `get_products`\n   * context. It normalizes legacy `format_ids[]` through product\n   * `v1_format_ref[]` / the v1→canonical projection path, resolves canonical\n   * `format_option_refs[]`, and checks directional containment for dimensions,\n   * sizes, duration declarations, and remaining canonical params. Negative\n   * cases only pass on a format-specific rejection, so unrelated auth or tenant\n   * failures do not mask selector bugs. Failure output names the likely bug\n   * class: normalization, directionality, or range containment. Added for\n   * adcp-client#2060.\n   */\n  | 'canonical_format_satisfaction'\n  /**\n   * Assert the cardinality of the array at `path`. Two configurations are\n   * supported: exact-count via `value: N` (passes only when the resolved\n   * array has exactly N entries) and range via `min` / `max` (either bound\n   * is optional; both inclusive). Specifying both `value` and `min`/`max` is\n   * rejected as a misconfigured check; so are non-integer, negative, NaN,\n   * or impossible (`min > max`) operands. Fails with a type error when the\n   * resolved path is absent or not an array — `field_present` paired with\n   * `field_value_or_absent value: null` is unsound for cardinality because\n   * it passes when a seller emits a literal-null pad at `arr[N]`.\n   *\n   * **Non-optional by design.** This check has no tolerant arm — an absent\n   * path fails. Use `field_value_or_absent` (or omit the check) when the\n   * field itself is spec-optional; `array_length` is for asserting the\n   * cardinality of an array that MUST be present.\n   *\n   * Spec: adcp#4685 (cardinality assertions); SDK adcp-client#1830.\n   */\n  | 'array_length';\n\n/**\n * Configuration for a step that fans out to N concurrent dispatches against\n * the same agent, returning the cross-response set for assertion. Drives the\n * `concurrent_retry` phase of the idempotency storyboard (rule 9 /\n * first-insert-wins), where two `create_media_buy` calls with the same\n * `idempotency_key` race the seller's INSERT and must resolve to one\n * resource.\n *\n * Modes:\n *   - `process_local` (default): fire all dispatches via `Promise.all`\n *     through the SDK's batch primitive before awaiting any response.\n *     Single-process, event-loop concurrent — sufficient to exercise the\n *     seller's INSERT race per the contract YAML's\n *     `not_required_to_synthesize_packet_schedule` note.\n *   - `distributed` (future): barrier-synced workers across processes for\n *     true network-level concurrency. Defers to a later spec phase; runners\n *     that do not implement it grade the step `not_applicable`.\n *\n * Spec source: `test-kits/parallel-dispatch-runner.yaml`.\n */\nexport interface ParallelDispatchSpec {\n  /**\n   * How many parallel dispatches to fire. Per spec, `count_min: 2`,\n   * `count_max: 10`. Values outside that range are rejected at run time as a\n   * `parallel_dispatch_misconfigured` step error rather than silently clamped.\n   */\n  count: number;\n  /**\n   * When `true` (default), every dispatch shares the same fresh\n   * `idempotency_key` (the runner mints one UUID and reuses it across the\n   * fan-out). When `false`, every dispatch gets its own fresh key — useful\n   * for soak tests that need parallelism without the race semantics.\n   */\n  same_idempotency_key?: boolean;\n  /**\n   * Maximum total wall-clock time, in milliseconds, the runner waits for all\n   * dispatches to resolve (including any IDEMPOTENCY_IN_FLIGHT retries).\n   * Defaults to `5000`. A dispatch that doesn't terminate within the budget\n   * is marked timed-out; the step grades the surviving set and reports\n   * `parallel_dispatch_barrier_timeout` for the missing arms.\n   */\n  barrier_timeout_ms?: number;\n  /**\n   * Dispatch coordination mode (see interface JSDoc). Defaults to\n   * `'process_local'`.\n   */\n  mode?: 'process_local' | 'distributed';\n}\n\n/**\n * A response-derived step-level not-applicable gate. Kept data-driven so new\n * storyboards can opt in without runner-specific hardcoding.\n */\nexport type ResponseNotApplicableGate = TerminalPageNotApplicableGate;\n\nexport interface TerminalPageNotApplicableGate {\n  kind: 'terminal_page';\n  /**\n   * Array path in the response whose length is compared to the request page\n   * size, e.g. `accounts`, `creatives`, or `formats`.\n   */\n  items_path: string;\n  /**\n   * Path in the request that carries the requested page size. Defaults to\n   * `pagination.max_results`.\n   */\n  request_max_results_path?: string;\n  /**\n   * Optional label prefixed onto skip.detail. Defaults to\n   * `single_page_result`.\n   */\n  reason?: string;\n  /** Optional human-readable detail override for skip.detail. */\n  detail?: string;\n  /**\n   * Context keys whose missing captures should cause downstream consumer\n   * steps to skip as `not_applicable` instead of `prerequisite_failed`.\n   * When omitted, the runner infers keys from context_outputs whose paths\n   * read `pagination.cursor`.\n   */\n  context_keys?: string[];\n}\n\n/**\n * Path/value match predicate for `upstream_traffic.payload_must_contain`.\n * Each entry asserts a JSONPath (`$.users[*].hashed_email`) and a match\n * mode against the recorded call's payload.\n */\nexport interface UpstreamTrafficPayloadMatch {\n  /** JSONPath into recorded_calls[].payload. */\n  path: string;\n  /** Match mode: `present` checks the path resolves; `equals` compares; `contains_any` checks list membership. */\n  match: 'present' | 'equals' | 'contains_any';\n  /** Expected value when `match: equals`. */\n  value?: unknown;\n  /** Allowed values when `match: contains_any`. */\n  allowed_values?: unknown[];\n}\n\n/**\n * Captured A2A wire shape from a `message/send` JSON-RPC response. The\n * runner records this when the protocol is `a2a` and a step's tool\n * dispatch went through the SDK client; A2A wire-shape validations\n * (`a2a_submitted_artifact`) consume it. Absent on MCP runs and on A2A\n * runs where the capture didn't fire (raw probe path, fetch error).\n *\n * The `result` field is typed as `unknown` because the JSON-RPC\n * envelope is observed at the wire — the validation engine narrows it\n * (e.g. asserting `kind === 'task'`) and reports specific failures\n * when the shape doesn't match. Doing the narrowing in the type would\n * lock callers into a specific A2A SDK version; doing it in the\n * validator preserves the runner's \"report what you saw\" contract.\n *\n * **Redaction posture.** The runner runs `redactSecrets` over `result`\n * and `envelope` before populating this struct, matching the\n * redaction the runner applies to `RunnerResponseRecord.payload` on\n * the success path. AdCP-style secret-shaped fields inside the\n * DataPart payload (`api_key`, `client_secret`, `access_token`, etc.)\n * are replaced with `[redacted]`; bearer-token substrings in raw\n * bodies were already redacted at fetch-capture time. Custom\n * validators reading this field don't need to re-redact, but SHOULD\n * avoid logging it through other channels (LLM context, debug sinks,\n * third-party telemetry) without confirming the same redaction\n * posture is acceptable for that channel.\n */\nexport interface A2ATaskEnvelope {\n  /**\n   * Parsed JSON-RPC `result` field — typically an A2A `Task`\n   * (`{ kind: 'task', id, status: { state }, artifacts: [...] }`) on\n   * success. Absent (set to `null`) when the JSON-RPC response was an\n   * error envelope; consumers should also inspect `envelope.error`.\n   */\n  result: unknown;\n  /**\n   * Full JSON-RPC envelope (`{ jsonrpc, id, result?, error? }`).\n   * Useful for assertions that need to distinguish a JSON-RPC error\n   * from a success-with-failure-task (e.g. `Task.state === 'failed'`\n   * is success-with-failure; `error.code === -32602` is a JSON-RPC\n   * error).\n   */\n  envelope: { jsonrpc?: unknown; id?: unknown; result?: unknown; error?: unknown };\n  /** HTTP status of the captured response (200 on JSON-RPC success). */\n  http_status: number;\n}\n\n/**\n * Set of references for `refs_resolve`. `from` picks the root object —\n * `current_step` reads the step's task-result `data`; `context` reads the\n * accumulated `StoryboardContext`. `path` supports `[*]` wildcard segments\n * that flatten into the aggregated result (so `products[*].format_ids[*]`\n * walks every product and flattens every `format_ids` array).\n */\nexport interface RefsResolveSet {\n  from: 'current_step' | 'context';\n  path: string;\n}\n\n/**\n * Scope filter for `refs_resolve`. Only source refs whose `key` matches\n * `equals` (after `$agent_url` substitution and, for URL-ending keys,\n * transport-suffix-stripping canonicalization) are in scope. Out-of-scope\n * refs are graded by `on_out_of_scope`.\n */\nexport interface RefsResolveScope {\n  key: string;\n  /** String to compare against. `$agent_url` expands to the runner target URL. */\n  equals: string;\n}\n\nexport interface StoryboardValidation {\n  /** Stable authored validation identifier echoed into runner results when present. */\n  id?: string;\n  /** Known validation kind, or a future string graded not_applicable by older runners. */\n  check: StoryboardValidationCheck | (string & {});\n  /** Whether a failed validation gates the step. Defaults to `required`. */\n  severity?: 'required' | 'advisory';\n  /**\n   * Runner capability version at which an advisory is promoted to required.\n   * Compared using semver.gte against the runner's self-declared capability.\n   */\n  expires_after_version?: string;\n  /** Structured marker for an advisory that deliberately never auto-promotes. */\n  permanent_advisory?: { reason: string };\n  /** JSON path for field checks, e.g. \"accounts[0].account_id\" */\n  path?: string;\n  /** Expected value for exact-match checks. */\n  value?: unknown;\n  /** Accepted values for list-match checks (passes if actual matches any). */\n  allowed_values?: unknown[];\n  /** JavaScript regular expression source for field_pattern checks. */\n  pattern?: string;\n  description: string;\n  // ─── refs_resolve fields ───────────────────────────────────\n  /** Source refs (the refs being checked). */\n  source?: RefsResolveSet;\n  /** Target refs (the set the source refs must resolve into). */\n  target?: RefsResolveSet;\n  /** Keys to compare between each source ref and each target ref. */\n  match_keys?: string[];\n  /** Only enforce integrity for refs matching this scope. */\n  scope?: RefsResolveScope;\n  /**\n   * How to grade source refs that fall outside `scope`.\n   *  - `warn` (default) — attach observations, pass the check\n   *  - `ignore` — silent, pass the check\n   *  - `fail` — treat as missing\n   */\n  on_out_of_scope?: 'warn' | 'ignore' | 'fail';\n  // ─── Cross-step comparison fields ──────────────────────\n  /**\n   * Key to look up in the accumulated `storyboardContext` for cross-step\n   * comparison checks (`field_less_than`, `field_greater_than`,\n   * `field_at_most`, `field_at_least`, `field_equals_context`,\n   * `field_in_context_array`, `all_fields_in_context_array`).\n   * Only consumed by those check types — ignored on all others.\n   * When set and the key is absent from context, the check passes with a\n   * `context_key_absent` observation rather than failing — the prior step\n   * that was supposed to populate the key may have been legitimately skipped.\n   */\n  context_key?: string;\n  // ─── upstream_traffic fields ──────────────────────────────\n  /**\n   * Minimum number of recorded calls (matching `endpoint_pattern` if set)\n   * the runner MUST observe in the assertion window. Default 1. Use 0 only\n   * for negative assertions (\"step MUST NOT cause upstream traffic\").\n   * Spec: storyboard-schema.yaml > \"upstream_traffic\".\n   */\n  min_count?: number;\n  /**\n   * Glob/path pattern matched against `recorded_calls[].endpoint`\n   * (`<METHOD> <URL>`). Examples: `POST <star>/audience/upload`,\n   * `POST <star>` (where `<star>` is a literal asterisk). When omitted,\n   * every recorded call in the window matches.\n   */\n  endpoint_pattern?: string;\n  /**\n   * Each entry asserts a path/value pair that MUST appear in at least one\n   * matching call's payload. See `UpstreamTrafficPayloadMatch`.\n   */\n  payload_must_contain?: UpstreamTrafficPayloadMatch[];\n  /**\n   * Raw payload introspection requirement. When set to `raw`, controllers\n   * that downgrade the response to digest-only attestations cause this\n   * validation to grade `not_applicable` instead of failed.\n   */\n  attestation_mode_required?: 'raw';\n  /**\n   * Advisory request-mode preference for the runner's\n   * `query_upstream_traffic` prefetch. When omitted, the runner preserves\n   * its legacy inference: digest for identifier-only checks with digestable\n   * vectors, raw otherwise. Raw-required validations and payload\n   * introspection always take precedence over this preference.\n   */\n  preferred_attestation_mode?: 'raw' | 'digest';\n  /**\n   * Paths into the effective request payload that name the load-bearing\n   * identifiers the adapter MUST forward upstream. When the runner has the\n   * actual request payload after context substitution, that payload is the\n   * source of truth; otherwise it falls back to the storyboard's\n   * `sample_request`.\n   *\n   * The runner extracts the values at these paths and asserts each resolved\n   * value appears in at least one matching `recorded_call`'s payload at any\n   * depth. Each path MAY resolve to a single value or an array; ALL resolved\n   * values MUST be present in the recorded payload — single-placeholder\n   * fabrication is the threat model. Portable path syntax is a request-rooted\n   * dotted grammar with optional `[*]` wildcard selectors on segments, for\n   * example `audiences[*].add[*].hashed_email`. Explicit roots (`$.foo`),\n   * reserved roots (`request.*`, `response.*`, `context.*`), bracket-quoted\n   * keys, recursive descent (`$..foo`), numeric indexes, and empty segments\n   * are storyboard authoring errors so controllers do not silently resolve\n   * zero vectors. The runner caps portable digest proofs at 64 unique\n   * identifier values; overflow is graded `not_applicable` because the bound\n   * is runner-side, not a spec value. Per spec PR adcontextprotocol/adcp#3816,\n   * replaces the earlier\n   * `buyer_identifier_echo: boolean` shorthand.\n   */\n  identifier_paths?: string[];\n  /**\n   * Bound the lookup window to traffic recorded since this step's request\n   * timestamp (default) or since the request timestamp of `prior_step_id`\n   * for cumulative-effect assertions.\n   */\n  since?: string;\n  // ─── array_length fields ──────────────────────────────────\n  /**\n   * Inclusive lower bound for `array_length`. Mutually exclusive with\n   * `value`. Pass with `max` omitted to assert \"at least N entries.\"\n   */\n  min?: number;\n  /**\n   * Inclusive upper bound for `array_length`. Mutually exclusive with\n   * `value`. Pass with `min` omitted to assert \"at most N entries.\"\n   */\n  max?: number;\n}\n\n// ────────────────────────────────────────────────────────────\n// Webhook-assertion step types\n//\n// The four `expect_webhook*` tasks are pseudo-tasks: they do not drive the\n// agent over MCP. Instead the runner uses them to observe / assert on the\n// webhook deliveries a prior step triggered. Graded only when the storyboard\n// declares the `webhook_receiver_runner` contract and the runner hosts a\n// receiver. Spec: adcontextprotocol/adcp#2431.\n// ────────────────────────────────────────────────────────────\n\n/** Webhook-body match predicate. Dotted paths, deep equality. */\nexport interface WebhookFilterSpec {\n  /** Match by `operation_id` echoed in the per-step URL path. */\n  operation_id?: string;\n  /** Match by dotted-path → value deep equality against the parsed body. */\n  body?: Record<string, unknown>;\n}\n\n/** Receiver behavior that forces the sender to retry so retry-stability can be graded. */\nexport interface WebhookRetryTriggerSpec {\n  /** How many deliveries to reject before accepting. Default 3. */\n  count?: number;\n  /** HTTP status code to return for the rejected deliveries. Default 503. */\n  http_status?: number;\n}\n\n/**\n * Error codes per spec (webhook-emission universal, storyboard-schema.yaml).\n *\n * Signature-path codes track the verifier's `webhook_signature_*` taxonomy\n * 1:1 so compliance reports distinguish remediation paths: a revoked key\n * needs rotation; a rate-abuse hit signals a compromised key; a\n * window-invalid is a signer clock/config bug. Spec folds every window\n * failure into a single `signature_window_invalid` — there is no\n * `signature_expired`.\n */\nexport type WebhookAssertionErrorCode =\n  // expect_webhook\n  | 'no_webhook_received'\n  | 'schema_violation'\n  | 'missing_idempotency_key'\n  | 'invalid_idempotency_key_format'\n  | 'duplicate_webhook_on_replay'\n  // expect_no_webhook\n  | 'unexpected_webhook_received'\n  // expect_webhook_retry_keys_stable\n  | 'insufficient_retries'\n  | 'idempotency_key_rotated'\n  | 'idempotency_key_format_changed'\n  // expect_webhook_signature_valid\n  | 'signature_invalid'\n  | 'signature_window_invalid'\n  | 'signature_alg_not_allowed'\n  | 'signature_components_incomplete'\n  | 'signature_header_malformed'\n  | 'signature_params_incomplete'\n  | 'signature_key_unknown'\n  | 'signature_key_purpose_invalid'\n  | 'signature_mode_mismatch'\n  | 'signature_target_uri_malformed'\n  | 'signature_key_revoked'\n  | 'signature_revocation_stale'\n  | 'signature_rate_abuse'\n  | 'signature_digest_mismatch'\n  | 'signature_tag_invalid'\n  | 'signature_replayed';\n\n/**\n * Spec pattern for webhook `idempotency_key`: 16–255 chars of base64url-safe\n * punctuation. Shared by all three assertion step types; exported so callers\n * (tests, tooling) can reproduce the grader's exact validation.\n */\nexport const WEBHOOK_IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_.:-]{16,255}$/;\n\n/**\n * Raw HTTP probe result for tasks like `protected_resource_metadata` that\n * bypass the MCP transport. Carried through the runner alongside\n * `TaskResult` so validations like `http_status` and `on_401_require_header`\n * can introspect the response.\n */\nexport interface HttpProbeResult {\n  url: string;\n  status: number;\n  /** Lowercased header names. */\n  headers: Record<string, string>;\n  /** Parsed JSON body when the response declared application/json; raw text otherwise. */\n  body: unknown;\n  /** Optional error — set when the fetch failed (network, SSRF guard, etc.). */\n  error?: string;\n  /**\n   * Probe was intentionally skipped (e.g. operator opted out of a vector,\n   * capability profile mismatch, or test-kit contract not in scope). When\n   * set, the runner marks the step `skipped: true` and does NOT run\n   * validations — skipped probes neither pass nor fail.\n   */\n  skipped?: boolean;\n  skip_reason?: string;\n}\n\n// ────────────────────────────────────────────────────────────\n// Context: accumulated state passed between steps\n// ────────────────────────────────────────────────────────────\n\nexport type StoryboardContext = Record<string, unknown>;\n\n// ────────────────────────────────────────────────────────────\n// Options\n// ────────────────────────────────────────────────────────────\n\n/**\n * One agent in a per-specialism routing map. Used by `runStoryboard()` when\n * a storyboard spans tools that live on different tenants (e.g. signals at\n * `/signals`, governance at `/governance`).\n *\n * `auth` is an optional per-tenant override. The canonical multi-tenant\n * deployment (the prod test-agent's six tenants) uses one shared bearer\n * across every URL — set `StoryboardRunOptions.auth` once at the run\n * level and leave entries' `auth` empty. Set `auth` on an entry only\n * when that tenant uses different credentials (e.g., a publisher whose\n * signals tenant is fronted by a partner like LiveRamp with separate\n * auth from the sales tenant). Adcp-client#1066.\n */\nexport interface AgentEntry {\n  /** MCP or A2A endpoint URL for this agent. */\n  url: string;\n  /** Per-tenant auth override; falls back to `StoryboardRunOptions.auth` when absent. */\n  auth?: TestOptions['auth'];\n  /** Per-tenant transport override; defaults to `StoryboardRunOptions.protocol`. */\n  transport?: 'mcp' | 'a2a';\n}\n\n/** One runner-hosted Context Match provider fixture exposed to the router under test. */\nexport interface TrustedMatchContextProviderEndpoint {\n  /** Publisher-controlled registration id from the packaged conformance vector. */\n  provider_id: string;\n  /** Absolute URL serving this provider's vector response at `POST /context`. */\n  context_url: string;\n}\n\n/** Input to the operator-owned router registration seam. */\nexport interface TrustedMatchContextRegistrationContext {\n  /** Vector profile, currently `adcp/trusted-match/context-targeting-merge/v1`. */\n  profile: string;\n  /** Fixed provider ids paired with the runner-hosted fixture URLs. */\n  providers: TrustedMatchContextProviderEndpoint[];\n  /** Exact Context Match request the runner will send after registration completes. */\n  request: Record<string, unknown>;\n}\n\nexport interface TrustedMatchContextRouterRunnerOptions {\n  /** Router base URL. The runner posts the vector request to `<router_url>/context`. */\n  router_url: string;\n  /**\n   * Operator-owned seam that installs the supplied provider registrations in\n   * the router under test. It may return a cleanup callback, which the runner\n   * invokes after the replay even when the router request fails.\n   */\n  registerProviders(\n    context: TrustedMatchContextRegistrationContext\n  ): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;\n  /** Extra headers sent to the router's `/context` endpoint. */\n  headers?: Record<string, string>;\n  /** Router request timeout in milliseconds. Defaults to 10000. */\n  timeoutMs?: number;\n  /** Optional root directory for resolving the packaged vector file. */\n  vectorsRoot?: string;\n  /** Override fetch for tests or custom runtimes. */\n  fetchImpl?: typeof fetch;\n  /** Configuration for the ephemeral provider fixture server. */\n  provider_server?: {\n    /** Loopback by default; proxy mode advertises `public_url` to remote routers. */\n    mode?: 'loopback_mock' | 'proxy_url';\n    /** Bind host for the local fixture listener. Defaults to `127.0.0.1`. */\n    host?: string;\n    /** Bind port. `0` (default) lets the kernel assign one. */\n    port?: number;\n    /** Public base URL routed to the local listener; required in proxy mode. */\n    public_url?: string;\n  };\n}\n\nexport type TrustedMatchPublisherAuthOperation = 'context' | 'identity';\nexport type TrustedMatchPublisherCredentialState = 'absent' | 'invalid';\n\n/** Declarative TLS material for one runner-owned publisher-auth probe. */\nexport interface TrustedMatchPublisherAuthTls {\n  clientCertificatePem?: string;\n  privateKeyPem?: string;\n  privateKeyPassphrase?: string;\n  caCertificatePem?: string;\n}\n\n/** The only values an operator adapter may contribute to a publisher-auth probe. */\nexport interface TrustedMatchPublisherAuthProbeConfiguration {\n  credentialHeaders?: Record<string, string>;\n  tls?: TrustedMatchPublisherAuthTls;\n}\n\n/**\n * Operator seam for credential-profile-neutral Trusted Match publisher-auth\n * conformance. The SDK, not this adapter, owns endpoint validation, routing,\n * HTTP construction, redirect policy, timeouts, response limits, and output.\n */\nexport interface TrustedMatchPublisherAuthRunner {\n  /** Exact publisher-facing Context Match URL. No path is inferred. */\n  contextEndpoint: string;\n  /** Exact publisher-facing Identity Match URL. No path is inferred. */\n  identityEndpoint: string;\n  preparePublisherAuthProbe(input: {\n    operation: TrustedMatchPublisherAuthOperation;\n    credentialState: TrustedMatchPublisherCredentialState;\n  }): Promise<TrustedMatchPublisherAuthProbeConfiguration>;\n}\n\nexport interface StoryboardRunOptions extends TestOptions {\n  /** Compliance cache root for bundle-scoped fixtures and test vectors. */\n  complianceDir?: string;\n  /**\n   * Pre-discovered agent profile to reuse instead of repeating capability\n   * discovery. When `agentTools` is omitted, the runner derives it from\n   * `profile.tools` so storyboard-level `required_tools` and step-level\n   * `requires_tool` gates remain enforced.\n   *\n   * Reuse a profile only for the same agent URL, authentication, AdCP version,\n   * and route that produced it. Route-specific profiles are not interchangeable.\n   * In an `agents` run this value supplies only the run-level/default-agent\n   * gating context; each routed agent is still discovered independently.\n   * Profile reuse does not retain or reuse a client or transport connection.\n   *\n   * `AgentProfile` does not carry the server's exact wire version. Pass\n   * `adcpVersion` separately when version-skew validation depends on it.\n   */\n  profile?: AgentProfile;\n  /** Initial context (e.g., from a previous step invocation) */\n  context?: StoryboardContext;\n  /**\n   * Initial context-provenance map, typically threaded from a prior\n   * `runStoryboardStep` invocation's `StoryboardStepResult.context_provenance`.\n   * Lets LLM-orchestrated step-by-step runs accumulate the per-key write\n   * history the runner needs to emit `context_value_rejected` hints when a\n   * later step's seller rejects a value an earlier step extracted. Ignored by\n   * `runStoryboard` (full run builds its own map internally). Closes\n   * adcp-client#880.\n   */\n  context_provenance?: Record<string, ContextProvenanceEntry>;\n  /**\n   * Context keys whose producer step was skipped as response-derived\n   * `not_applicable`, typically threaded from a prior `runStoryboardStep`\n   * invocation's `StoryboardStepResult.response_derived_not_applicable_context_keys`.\n   * Lets stateless step-by-step callers preserve the same cursor-consumer skip\n   * semantics as full `runStoryboard` runs.\n   */\n  response_derived_not_applicable_context_keys?: Record<string, string>;\n  /**\n   * Contribution flags accumulated by prior `runStoryboardStep` invocations.\n   * Thread this from `StoryboardStepResult.contributions` so synthetic\n   * aggregate steps such as `assert_contribution` see the same branch-set\n   * state they would see inside a full `runStoryboard` execution.\n   */\n  contributions?: string[];\n  /** Override the step's sample_request with a custom request */\n  request?: Record<string, unknown>;\n  /** Agent's available tools for storyboard/step-level tool gates. */\n  agentTools?: string[];\n  /**\n   * Allow plain-http agent URLs during compliance runs and permit guarded\n   * raw-HTTP probes to reach private/loopback endpoints. Production agents\n   * MUST terminate TLS; dedicated probes that require HTTPS (including TMP\n   * publisher authentication) keep that requirement even when this flag is\n   * enabled. Intended for local dev loops and private staging harnesses.\n   * Emits an advisory banner in the report when used.\n   */\n  allow_http?: boolean;\n  /**\n   * Operator assertion that initial state has been provisioned out-of-band\n   * (HTTP admin, pre-test script, staging fixture) — flips the\n   * `seeded_state` requirement to available so storyboards declaring\n   * `requires: [seeded_state]` run instead of skipping with\n   * `requirement_unmet`. Default false. The runner does NOT verify the\n   * assertion; if state isn't actually seeded the scenario fails\n   * naturally on its first stateful step, which is the right signal.\n   * CLI: `--asserts-seeded-state`. Spec: adcp-client#1626.\n   */\n  assertsSeededState?: boolean;\n  /**\n   * Request-signing grader knobs (applied when the runner encounters\n   * synthesized `request_signing_probe` steps from the signed-requests\n   * specialism).\n   */\n  request_signing?: {\n    /** Skip the rate-abuse vector — it sends cap+1 requests and is slow. */\n    skipRateAbuse?: boolean;\n    /** Override the per-keyid cap the grader targets. */\n    rateAbuseCap?: number;\n    /**\n     * Vector IDs to skip (e.g., capability-profile mismatches for vectors\n     * 007/018 when the agent's `covers_content_digest` policy differs).\n     */\n    skipVectors?: string[];\n    /**\n     * Run only the named vector ids — all others auto-skip. Takes precedence\n     * over `skipVectors`.\n     */\n    onlyVectors?: string[];\n    /**\n     * Opt in to running vectors that produce live agent-side effects\n     * (016 replay, 020 rate-abuse). Required unless the test-kit declares\n     * `endpoint_scope: sandbox`. This flag controls request-signing vectors\n     * only; use the top-level `allowLiveSideEffects` option separately for\n     * `expect_rate_limit_not_replayed`.\n     */\n    allowLiveSideEffects?: boolean;\n    /**\n     * How the grader dispatches each vector to the agent.\n     *\n     *   - `raw` — POSTs each vector body directly to a per-\n     *     operation AdCP endpoint (e.g. `<baseUrl>/create_media_buy`).\n     *     Works for agents that expose AdCP tools as discrete HTTP\n     *     operations.\n     *   - `mcp` (default) — wraps each vector body in a JSON-RPC `tools/call`\n     *     envelope and POSTs to the agent's single `/mcp` mount. Required\n     *     for MCP-only agents that don't expose per-operation endpoints.\n     *     The operation name is derived from the last path segment of the\n     *     vector's target URL.\n     *\n     * Matches the `adcp grade request-signing --transport <mode>` CLI flag.\n     * Agents that only speak MCP JSON-RPC can't grade under `raw`; use\n     * `mcp` to let the runner round-trip every vector through `tools/call`.\n     */\n    transport?: 'raw' | 'mcp';\n    /**\n     * Pre-provisioned MCP session ID to attach as `Mcp-Session-Id` on every\n     * vector probe after signing. When `transport` is `'mcp'` and this is\n     * omitted, the runner auto-initializes a session via the MCP\n     * `initialize` handshake before each vector call. Pass a pre-acquired ID\n     * (from `initializeMcpSession`) to reuse one session across the whole\n     * storyboard run and avoid the per-vector round-trip overhead.\n     *\n     * Pass `''` (empty string) to disable auto-initialization for stateless\n     * streamable-HTTP agents that do not issue session IDs.\n     */\n    mcpSessionId?: string;\n    /**\n     * Negotiated MCP protocol version for a pre-provisioned session. When the\n     * runner auto-initializes, it uses the version returned by the server.\n     */\n    mcpProtocolVersion?: string;\n  };\n  /**\n   * Distribution strategy across agent URLs in multi-instance mode.\n   * Only consulted when the runner is given 2+ URLs. Defaults to 'round-robin'.\n   *\n   *  - `round-robin` (default): step N hits `urls[N % urls.length]`. One pass.\n   *  - `multi-pass` (narrow use case): runs the storyboard `urls.length`\n   *    times, each pass starting the dispatcher at a different replica.\n   *    Surfaces single-replica bugs (stale config, divergent version,\n   *    local-cache miss) that single-pass round-robin may not catch when\n   *    the buggy replica happens to serve only passive steps. N-multiplies\n   *    run time. NOT a full cross-replica state-persistence test at N=2:\n   *    offset-shift preserves pair parity, so write→read pairs with even\n   *    dispatch-index distance (e.g., the property_lists case: write at 0,\n   *    read at 2) land same-replica in every pass. Use single-pass\n   *    round-robin (adjacent pairs) + follow-up dependency-aware dispatch\n   *    (non-adjacent pairs, #607 option 2) for the spec's horizontal-\n   *    scaling requirement. See docs/guides/MULTI-INSTANCE-TESTING.md.\n   */\n  multi_instance_strategy?: 'round-robin' | 'multi-pass';\n  /**\n   * Per-specialism agent routing map. When set, each step's tool name\n   * (`StoryboardStep.task`) is resolved to the agent that claims its\n   * specialism via `TASK_FEATURE_MAP` × per-agent `get_adcp_capabilities`.\n   * An optional explicit `StoryboardStep.agent` override takes precedence.\n   *\n   * Mutually exclusive with `multi_instance_strategy` (which is replica\n   * round-robin, a different concept) and with the legacy `_client`\n   * override (single client cannot serve multiple agents). Both\n   * combinations throw at `runStoryboard()` entry.\n   *\n   * Discovery is parallel across all agents at storyboard start; any agent\n   * whose discovery fails causes the whole storyboard to fail (not skip),\n   * because a topology with one broken tenant is a hard misconfiguration,\n   * not a per-step skip condition.\n   *\n   * Multi-claim conflicts (two agents claim the same specialism) fail-fast\n   * at discovery time for affected steps that lack an explicit `step.agent`\n   * override. Steps WITH an override route per the override and never see\n   * the conflict — the override is the disambiguator, not just an escape\n   * hatch. To resolve a conflict: either remove one of the conflicting\n   * agents from the map, or add `agent: <key>` to each affected step.\n   *\n   * Adcp-client#1066.\n   */\n  agents?: Record<string, AgentEntry>;\n  /**\n   * Fallback agent key (must be present in `agents`) for tasks with no entry\n   * in `TASK_FEATURE_MAP` — e.g., `comply_test_controller`, future tasks\n   * shipped before the SDK adds them to the map. When omitted, unmapped\n   * tasks fail-fast with `unroutable_task`.\n   */\n  default_agent?: string;\n  /**\n   * Opt into resilient discovery (#1367). When `false` (default), any agent\n   * whose `get_adcp_capabilities` probe fails causes the whole storyboard\n   * to fail — correct for production multi-tenant flows where every tenant\n   * in the map is load-bearing.\n   *\n   * When `true`:\n   *   - Discovery failures are logged but not fatal.\n   *   - Failed agents are excluded from the protocol-claim index.\n   *   - Routing throws `RoutingError` only if a step's protocol resolves\n   *     to a failed agent — surfaces as a per-step failure, not a\n   *     storyboard-wide hard failure.\n   *   - A `discovery_failures[]` summary on `StoryboardResult` lists which\n   *     agents failed, so the operator still sees the topology breakage.\n   *\n   * Intended for hello-cluster CI and exploratory runs where one flaky\n   * tenant shouldn't gate a 6-tenant smoke. Production runs should NEVER\n   * set this — a topology with one broken tenant is a hard misconfig.\n   *\n   * Only consulted when `agents` is set (multi-agent routing); single-URL\n   * runs have no roster to be resilient about.\n   */\n  discovery_resilient?: boolean;\n  /**\n   * Host an ephemeral webhook receiver during the run so `expect_webhook*`\n   * pseudo-steps can observe outbound webhooks from the agent under test.\n   * Enables the `webhook_receiver_runner` contract referenced by the\n   * `webhook-emission` universal (adcontextprotocol/adcp#2431).\n   *\n   * When enabled, storyboards can substitute `{{runner.webhook_base}}` and\n   * `{{runner.webhook_url:<step_id>}}` into `push_notification_config.url`\n   * and downstream `expect_webhook*` steps observe the deliveries.\n   *\n   * Mode selection matches the spec's `endpoint_modes`:\n   *   - `loopback_mock` (default): bind an HTTP listener on loopback; URLs\n   *     point at `http://127.0.0.1:<port>`. Zero external network setup.\n   *     Suitable for CI lint gates, SDK self-tests, and local dev.\n   *   - `proxy_url`: operator-supplied public URL (tunnel / ingress) routes\n   *     to a local HTTP listener on the configured port. Suitable for AdCP\n   *     Verified grading where the agent under test is remote.\n   *\n   * **Multi-agent topology** (`options.agents` set): the receiver is **shared**\n   * across all tenants in the routing map — one HTTP server, one base URL,\n   * bound once at storyboard start. This works correctly for cross-specialism\n   * flows because delivery correlation is by **step-keyed URL** (the receiver\n   * mints `/step/<step_id>/<operation_id>` paths), not by source agent. If a\n   * `sync_governance` step on the governance tenant and an `activate_signal`\n   * step on the signals tenant both emit webhooks, the runner disambiguates by\n   * step ID, not tenant identity. Per-tenant receivers are not supported and\n   * are not needed for any current cross-specialism storyboard in the corpus.\n   */\n  webhook_receiver?: {\n    /** Endpoint mode (default: `loopback_mock`). */\n    mode?: 'loopback_mock' | 'proxy_url';\n    /** Bind host for the local listener. Defaults to `127.0.0.1`. */\n    host?: string;\n    /** Bind port. `0` (default) lets the kernel assign one. */\n    port?: number;\n    /**\n     * Public URL to advertise when `mode: 'proxy_url'`. Must terminate at\n     * the local listener on `port`. Stored verbatim; the runner does not\n     * validate reachability.\n     */\n    public_url?: string;\n  };\n  /**\n   * Target receiver for `replay_webhook_vector` storyboards. This is separate\n   * from `webhook_receiver`: that option hosts a local receiver so the runner\n   * can observe seller-emitted webhooks, while this option points at the\n   * buyer/orchestrator receiver the runner should POST canonical vectors to.\n   */\n  webhook_replay_receiver?: {\n    /** Absolute URL of the receiver endpoint under test. */\n    url: string;\n    /** Extra headers to send on every replay. */\n    headers?: Record<string, string>;\n    /** Optional signing profile for raw-body verification tests. */\n    signing?: WebhookConformanceSigningOptions;\n    /** Request timeout in milliseconds. Defaults to 10000. */\n    timeoutMs?: number;\n    /** Optional root directory for resolving vector_ref file paths. */\n    vectorsRoot?: string;\n    /** Override fetch for tests or custom runtimes. */\n    fetchImpl?: typeof fetch;\n  };\n  /**\n   * Raw-HTTP Trusted Match Context router harness used by\n   * `replay_trusted_match_context_vector`. The runner hosts the packaged\n   * provider fixtures, calls `registerProviders`, then posts the vector\n   * request to `<router_url>/context`. Without this option the storyboard\n   * grades `not_applicable`; it never falls back to MCP or A2A.\n   */\n  trusted_match_context_router_runner?: TrustedMatchContextRouterRunnerOptions;\n  /**\n   * Guarded raw-HTTP harness for the four Trusted Match publisher-auth\n   * pseudo-tasks. Only credential headers and declarative PEM TLS material\n   * cross the adapter boundary; the SDK owns every transport decision.\n   */\n  trusted_match_publisher_auth_runner?: TrustedMatchPublisherAuthRunner;\n  /**\n   * Test-kit contract ids that are in scope for this run. A step with\n   * `requires_contract: <id>` grades `not_applicable` when the id is not\n   * listed here. Storyboards that assert webhook behavior typically declare\n   * `webhook_receiver_runner`.\n   */\n  contracts?: string[];\n  /**\n   * Explicitly authorize the `expect_rate_limit_not_replayed` storyboard\n   * probe, which may send hundreds of mutating requests. The probe requires\n   * this opt-in in addition to its `rate_limit_trip_runner` contract;\n   * contract presence alone is not runtime authorization. This does not\n   * authorize request-signing vectors, which use\n   * `request_signing.allowLiveSideEffects`. Default false.\n   */\n  allowLiveSideEffects?: boolean;\n  /**\n   * Opt out of the runner's pre-flight `comply_test_controller` seeding\n   * (adcp-client#778). When true, the runner skips the seed_* loop even if\n   * the storyboard declares `prerequisites.controller_seeding: true` and a\n   * `fixtures:` block. Intended for agents that load fixtures via a non-MCP\n   * path (HTTP admin, test bootstrap, inline Node state) — set the flag so\n   * the runner doesn't race the external seeding or fail against an agent\n   * that doesn't host `comply_test_controller`.\n   */\n  skip_controller_seeding?: boolean;\n  /**\n   * Dependencies for `expect_webhook_signature_valid`. When omitted the step\n   * grades `not_applicable` — matches the spec's \"pending\" gate. Supply the\n   * publisher's JWKS resolver (typically fetched via `brand.json`\n   * `agents[]` `jwks_uri`) to turn the step on. The two optional stores\n   * default to process-local in-memory implementations; override when the\n   * runner needs durable state across runs.\n   */\n  webhook_signing?: {\n    jwks: import('../../signing/jwks').JwksResolver;\n    replayStore?: import('../../signing/replay').ReplayStore;\n    revocationStore?: import('../../signing/revocation').RevocationStore;\n    /** Override the required tag. Defaults to `adcp/webhook-signing/v1`. */\n    required_tag?: string;\n  };\n  /**\n   * Cancel the run when this signal aborts. Threaded down to the per-phase\n   * and per-step loops inside `executeStoryboardPass` so an abort fires\n   * between any two steps, not only between storyboards. Without it,\n   * `comply()`'s timeout would only bound the *next* storyboard's start —\n   * a single in-flight storyboard could exhaust its full timeout budget\n   * inside one fan-out of sequential MCP/A2A calls. (adcp-client#1612)\n   */\n  signal?: AbortSignal;\n}\n\n// ────────────────────────────────────────────────────────────\n// Runner-output contract shapes\n//\n// See `static/compliance/source/universal/runner-output-contract.yaml`\n// (adcontextprotocol/adcp PR #2364). The contract defines the minimum\n// failure-result shape every AdCP compliance runner MUST emit so buyers\n// can self-diagnose agent conformance failures. Optional fields stay\n// `undefined` when they don't apply (e.g., schema_url on a non-schema\n// check).\n// ────────────────────────────────────────────────────────────\n\nexport type RunnerTransport = 'mcp' | 'a2a' | 'http';\n\nexport interface RunnerRequestRecord {\n  transport: RunnerTransport;\n  /** Task/tool/skill name actually invoked (after test-kit resolution). */\n  operation: string;\n  /** Fully-resolved JSON payload with secrets redacted as \"[redacted]\". */\n  payload: unknown;\n  /**\n   * Observed request headers. Deliberately NOT populated today — the runner\n   * builds `Authorization: Bearer <token>` headers in-flight and echoing them\n   * into a shared compliance report would be a credential leak. The field is\n   * kept in the type for future auth-override request captures that carry a\n   * redacted form.\n   */\n  headers?: Record<string, string>;\n  /** Full URL for http/a2a; omitted for stdio MCP. */\n  url?: string;\n}\n\nexport interface RunnerResponseRecord {\n  transport: RunnerTransport;\n  /** Exact response payload, per transport. */\n  payload: unknown;\n  /** HTTP status where applicable. */\n  status?: number;\n  /** Observed response headers. */\n  headers?: Record<string, string>;\n  /** Wall-clock time for the request. */\n  duration_ms?: number;\n}\n\n/**\n * Which MCP extraction path produced the parsed response. Recording this\n * lets implementors distinguish runner extraction bugs from agent bugs.\n * Populated by the response unwrapper (normal SDK path) and by the raw MCP\n * probe (auth-override path); the runner falls back to inference when the\n * provenance tag is missing.\n *\n *   - `structured_content` — parsed from `result.structuredContent`.\n *   - `text_fallback` — parsed from `result.content[].text` JSON.\n *   - `error` — `result.isError` or transport-level failure; payload is the error.\n *   - `none` — no MCP response (HTTP-probe step, synthetic step, or skipped).\n */\nexport type RunnerExtractionPath = 'structured_content' | 'text_fallback' | 'error' | 'none';\n\nexport interface RunnerExtractionRecord {\n  path: RunnerExtractionPath;\n  /** Optional note, e.g. \"structuredContent contained only adcp_error\". */\n  note?: string;\n}\n\n/**\n * Spec skip reasons. Runners MUST distinguish these so an implementor knows\n * whether a skip is informative (agent didn't claim the protocol) or masking\n * (runner couldn't apply the storyboard even though the agent claimed it).\n */\nexport type RunnerSkipReason =\n  | 'not_applicable'\n  | 'no_phases'\n  | 'prerequisite_failed'\n  | 'missing_tool'\n  | 'missing_test_controller'\n  /**\n   * The runner selected the pathway but its test kit cannot synthesize a\n   * valid input for the seller-declared contract. This is a runner-owned\n   * coverage gap: it never fails validations or cascades prerequisites.\n   * Spec: AdCP runner-output-contract v2.8.0,\n   * `skip_result.reasons.fixture_unavailable` (adcp#6276). Early preflight\n   * and whole-storyboard termination semantics: adcp#6278.\n   */\n  | 'fixture_unavailable'\n  | 'unsatisfied_contract'\n  /**\n   * A storyboard-level `requires:` tag named a requirement that is not\n   * available on the current run (e.g. `controller` when the agent doesn't\n   * advertise `comply_test_controller`, or `seeded_state` when the operator\n   * didn't pass `--asserts-seeded-state`). Distinct from `missing_tool` /\n   * `missing_test_controller` (per-step tool gates) and `unsatisfied_contract`\n   * (a declared runner contract is unavailable). The\n   * `RunnerSkipResult.requirement` field carries\n   * the unmet requirement name, including unknown forward-compatible strings.\n   * Spec: adcp-client#1626.\n   */\n  | 'requirement_unmet'\n  /**\n   * A peer optional phase in the same `branch_set` already contributed the\n   * aggregation flag, so this non-chosen branch's failing steps are moot\n   * (see storyboard-schema.yaml > \"Per-step grading in any_of branch\n   * patterns\" and runner-output-contract.yaml). Kept distinct from\n   * `not_applicable` (coverage gap) and raw `failed` (agent misbehavior).\n   */\n  | 'peer_branch_taken'\n  /**\n   * A same-phase peer step declared `provides_state_for: <this_step_id>`\n   * and passed, establishing equivalent state. This step would have graded\n   * `missing_tool` or `missing_test_controller`; the substitute rescued it\n   * so downstream stateful steps can still run. Detail format per\n   * `runner-output-contract.yaml`:\n   * `\"<this_step_id> state provided by <phase_id>.<substitute_step_id>\"`.\n   * Kept distinct from `peer_branch_taken` (branch-set routing) and\n   * `not_applicable` (coverage gap). Spec source: adcp#3734 (AdCP 3.0.3+).\n   */\n  | 'peer_substituted';\n\n/**\n * Grader-specific skip reasons. These are narrower than the canonical\n * `RunnerSkipReason` values — they carry runner-local context (which probe,\n * which operator opt-out) that the contract neither requires nor forbids.\n * The runner records them on `skip_reason` for legacy consumers, and also\n * emits the structured `skip: RunnerSkipResult` block with the canonical\n * equivalent per `DETAILED_SKIP_TO_CANONICAL`.\n */\nexport type RunnerDetailedSkipReason =\n  | 'probe_skipped'\n  | 'rate_abuse_opt_out'\n  | 'missing_test_kit_contract'\n  | 'live_side_effect_opt_in_required'\n  | 'operator_skip'\n  | 'not_in_only_vectors'\n  | 'grader_skipped'\n  /** Request-signing vector is outside the agent's declared signing capability profile. */\n  | 'capability_profile_mismatch'\n  /** Request-signing vector cannot be graded faithfully by the selected transport. */\n  | 'transport_ungradable'\n  /** Request-signing grader's MCP-transport mode collapses URL-edge vectors (#617). */\n  | 'mcp_mode_flattens_url_edges'\n  /** RFC 9728 protected-resource metadata returned 404 → agent is not advertising OAuth, cascade-skip oauth_discovery (#677). */\n  | 'oauth_not_advertised'\n  /** rate_limit_trip_runner did not observe RATE_LIMITED within max_attempts. */\n  | 'rate_limit_not_triggered'\n  /**\n   * Pre-flight `comply_test_controller` seeding failed (adcp-client#778), so\n   * every real phase cascade-skipped rather than run against an unseeded\n   * agent. The structured `skip.reason` resolves to the canonical\n   * `prerequisite_failed` per `DETAILED_SKIP_TO_CANONICAL` — the detailed\n   * form stays on the legacy `skip_reason` field so report consumers can\n   * still distinguish setup breaks from stateful-chain breaks within a\n   * phase.\n   */\n  | 'controller_seeding_failed'\n  /**\n   * A generated pre-flight seed_* call targeted a scenario that the agent's\n   * comply_test_controller does not implement. Maps to canonical\n   * `not_applicable`: the seller cannot accept this storyboard's fixture\n   * setup, so the storyboard is out of scope rather than failed.\n   */\n  | 'fixture_seed_unsupported'\n  /** A valid fixture strategy ladder exhausted without finding a binding. */\n  | 'fixture_unsatisfied'\n  /**\n   * A root capability predicate on the storyboard evaluated to false —\n   * the agent explicitly declared it does not support the capability this\n   * storyboard tests (e.g. `adcp.idempotency.supported: false`). The whole\n   * storyboard is skipped before any phase runs. Maps to canonical\n   * `not_applicable`: this storyboard does not target the agent's\n   * self-declared capability profile.\n   */\n  | 'capability_unsupported'\n  /**\n   * A `comply_test_controller` step targeted a `force_*` scenario that the\n   * agent advertised the controller for but did not implement. Detected by\n   * the tuple (step.task === 'comply_test_controller', resolved\n   * `scenario` parameter starts with `force_`, response `success: false,\n   * error: UNKNOWN_SCENARIO`). Runners MUST grade the step `not_applicable`\n   * with detail `force_scenario_unsupported` instead of failing the step's\n   * authored validations. Maps to canonical `not_applicable`. AdCP 3.0.12\n   * runner-output-contract: `universal/runner-output-contract.yaml` >\n   * `skip_result.reasons.force_scenario_unsupported`.\n   */\n  | 'force_scenario_unsupported';\n\n/**\n * Map detailed grader skip reasons onto the canonical spec values so\n * consumers reading `skip.reason` get a stable enum regardless of which\n * subsystem produced the skip.\n */\nexport const DETAILED_SKIP_TO_CANONICAL: Record<RunnerDetailedSkipReason, RunnerSkipReason> = {\n  probe_skipped: 'not_applicable',\n  not_in_only_vectors: 'not_applicable',\n  grader_skipped: 'not_applicable',\n  capability_profile_mismatch: 'not_applicable',\n  transport_ungradable: 'not_applicable',\n  mcp_mode_flattens_url_edges: 'not_applicable',\n  oauth_not_advertised: 'not_applicable',\n  rate_limit_not_triggered: 'not_applicable',\n  force_scenario_unsupported: 'not_applicable',\n  fixture_seed_unsupported: 'not_applicable',\n  fixture_unsatisfied: 'not_applicable',\n  capability_unsupported: 'not_applicable',\n  rate_abuse_opt_out: 'unsatisfied_contract',\n  missing_test_kit_contract: 'unsatisfied_contract',\n  live_side_effect_opt_in_required: 'unsatisfied_contract',\n  operator_skip: 'unsatisfied_contract',\n  controller_seeding_failed: 'prerequisite_failed',\n};\n\nexport interface RunnerSkipResult {\n  reason: RunnerSkipReason;\n  detail: string;\n  /**\n   * Set on storyboard-level `requires:` skips to name the requirement that was\n   * not available on this run. Most such skips use\n   * `reason === 'requirement_unmet'`; legacy-preserving mappings such as\n   * `controller -> missing_test_controller` also carry this field. Carries the\n   * same value authored in `Storyboard.requires`, including unknown\n   * forward-compatible strings. Consumers (skip-cause aggregation, dashboards)\n   * key on this field to group not-applicable scenarios by cause. Spec:\n   * adcp-client#1626.\n   */\n  requirement?: string;\n}\n\nexport type RunnerSelectionReason =\n  | 'run_mode_excluded'\n  | 'explicit_scope_excluded'\n  | 'version_excluded'\n  | 'profile_excluded';\n\nexport interface RunnerSelectionResult {\n  reason: RunnerSelectionReason;\n  detail: string;\n}\n\n/**\n * Recognised values for `Storyboard.requires`. See `Storyboard.requires`\n * for what each name detects from. Adding a new value here is a wire\n * surface change; coordinate with the upstream spec proposal before\n * extending.\n *\n * Spec: adcp-client#1626, adcp-client#2281, adcp-client#2356.\n */\nexport type RequirementName =\n  | 'controller'\n  | 'seeded_state'\n  | 'real_wire'\n  | 'webhook_receiver'\n  | 'webhook_replay_receiver'\n  | 'trusted_match_context_router_runner'\n  | 'trusted_match_publisher_auth_runner'\n  | 'request_signer'\n  | 'multi_agent';\n\n/**\n * Enumeration of every requirement this SDK knows how to satisfy. The loader\n * accepts other non-empty strings for forward compatibility; the runner treats\n * those as unmet runtime requirements so future source-authored gates degrade\n * to `requirement_unmet` instead of failing load. Keep in sync with\n * `RequirementName`.\n */\nexport const KNOWN_REQUIREMENTS: ReadonlySet<RequirementName> = new Set([\n  'controller',\n  'seeded_state',\n  'real_wire',\n  'webhook_receiver',\n  'webhook_replay_receiver',\n  'trusted_match_context_router_runner',\n  'trusted_match_publisher_auth_runner',\n  'request_signer',\n  'multi_agent',\n] as const satisfies readonly RequirementName[]);\n\n/**\n * Machine-readable Zod/AJV-style validation error. Emitted in\n * `ValidationResult.actual` for `response_schema` failures.\n */\nexport interface SchemaValidationError {\n  instance_path: string;\n  schema_path: string;\n  keyword: string;\n  message: string;\n}\n\n// ────────────────────────────────────────────────────────────\n// Runner notices\n// ────────────────────────────────────────────────────────────\n\n/**\n * Closed literal union of every notice code the runner can emit.\n *\n * Adopters who narrow on `code` get exhaustiveness checks: when a new\n * code lands in a future SDK release, their switch / discriminated\n * union surfaces the gap at compile time. That's the right signal —\n * a deprecation or future-required advisory is the kind of thing a CI\n * gate or dashboard SHOULD have explicit handling for.\n *\n * Code naming generally follows the dot-namespaced convention `<topic>.<event>`\n * (e.g. `request_signing.required`, `webhook_signing.legacy_hmac_fallback.removed`);\n * prefer the upstream runner-output contract's canonical code when it\n * registers a different spelling. The *when* lives in the `effective_version`\n * field, never in the code. This keeps the surface stable across spec versions\n * — codes don't proliferate `_in_4_0` / `_in_5_0` siblings as the spec evolves.\n *\n * Adding a new code is a wire-surface change AND a TypeScript breaking\n * change for adopters who narrowed on `code`. Coordinate with the upstream\n * spec (adcp#4418) before extending.\n *\n * Spec: adcp-client#1704.\n */\nexport type NoticeCode =\n  /** Agent advertises deprecated `specialisms: ['signed-requests']`. Removed in\n   *  AdCP 4.0 per `effective_version`. */\n  | 'signed_requests_specialism_deprecated'\n  /** Agent lacks `request_signing.supported: true`. Required for spend-committing\n   *  operations in AdCP 4.0 per `effective_version`. */\n  | 'request_signing.required'\n  /** Agent advertises `webhook_signing.legacy_hmac_fallback: true`. Removed in\n   *  AdCP 4.0 per `effective_version`. */\n  | 'webhook_signing.legacy_hmac_fallback.removed'\n  /** Runner stripped request fields missing from the agent's advertised tool input schema. */\n  | 'input_schema_field_stripped'\n  /** The preflight get_adcp_capabilities response failed schema validation. */\n  | 'capabilities_response_schema_invalid';\n\n/**\n * Severity of a runner notice. Deliberately separate from `ObservationSeverity`\n * (which grades behavioral quality). Notices describe the agent's _protocol\n * compliance trajectory_ — a different axis: something is fine today but the\n * spec already signals a future state change.\n *\n * - `info` — non-grading context; it may still identify an actionable defect.\n * - `deprecation` — SHOULD migrate; the field/claim is deprecated in the current\n *   spec version.\n * - `future_required` — behavior is optional today but will be mandatory in a\n *   named future AdCP version (see `effective_version`).\n */\nexport type NoticeSeverity = 'info' | 'deprecation' | 'future_required';\n\n/**\n * A structured advisory produced by the runner for a specific storyboard run.\n * Notices describe protocol compliance trajectory (deprecations, upcoming\n * requirements) rather than behavioral quality (which is `AdvisoryObservation`'s\n * domain). Intended for CI gates and dashboards that need machine-readable badges\n * like \"DEPRECATION\" or \"FUTURE-REQUIRED\" without parsing prose strings.\n *\n * `ComplianceResult.notices` aggregates these across all storyboard runs,\n * deduplicated by `code`, or by (`code`, `capability_pointer`) when a pointer\n * is present. This preserves one schema-invalid notice per response location.\n *\n * Spec: adcp-client#1704.\n */\nexport interface RunnerNotice {\n  severity: NoticeSeverity;\n  /** Stable machine-readable identifier. Dashboards key on this for badge routing. */\n  code: NoticeCode;\n  /** Human-readable explanation; first 200 chars suitable for tabular rendering. */\n  message: string;\n  /**\n   * AdCP protocol version at which the behavior becomes mandatory (for\n   * `future_required`) or was formally removed (for `deprecation`).\n   * e.g. `'4.0'`. Absent when not version-bounded. Field name matches\n   * upstream spec issue adcontextprotocol/adcp#4418.\n   */\n  effective_version?: string;\n  /**\n   * Dot-path into the agent's capability response that motivated the notice\n   * (e.g. `request_signing.supported`). Use as a human-readable pointer only;\n   * not guaranteed to resolve via JSON Pointer.\n   */\n  capability_path?: string;\n  /**\n   * RFC 6901 pointer into the agent's `get_adcp_capabilities` response.\n   * Distinct from `capability_path`, which is a human-readable dotted flag\n   * path. Notices may carry both when they identify the same location.\n   */\n  capability_pointer?: string;\n  /**\n   * Click-through URL for adopters to read the underlying spec section,\n   * migration guide, or AdCP issue. Optional; consumers that surface\n   * notices in dashboards or CI output use this to deep-link the\n   * remediation context. Stable across runs for the same `code`.\n   */\n  docs_url?: string;\n  /**\n   * Storyboard ids that triggered this notice. On `StoryboardResult.notices`\n   * this is always a single-element array (the storyboard the notice came\n   * from). On `ComplianceResult.notices` (the deduplicated cross-storyboard\n   * rollup) this aggregates every storyboard that emitted the same dedupe key\n   * (`code`, or `code` + `capability_pointer` when present), so auditors can\n   * see \"how widespread\" a signal is without re-walking the per-storyboard\n   * arrays. Order is stable across runs (storyboard execution order).\n   */\n  storyboard_ids: string[];\n}\n\n// ────────────────────────────────────────────────────────────\n// Results\n// ────────────────────────────────────────────────────────────\n\nexport interface ValidationResult {\n  /** Stable authored validation identifier, echoed unchanged when provided by the storyboard. */\n  id?: string;\n  check: string;\n  passed: boolean;\n  description: string;\n  /** Effective severity after any capability-version promotion. Defaults to `required`. */\n  severity?: 'required' | 'advisory';\n  /**\n   * Present only for expiry-gated advisories that were graded: true when\n   * promoted to required, false while the runner capability remains older.\n   */\n  severity_promoted_from_advisory?: boolean;\n  /** Dot/bracket JSON path (legacy). See `json_pointer` for the RFC 6901 form. */\n  path?: string;\n  /** Human-readable failure detail. */\n  error?: string;\n  /** RFC 6901 pointer to the failing field. Null when the failure is transport-level. */\n  json_pointer?: string | null;\n  /** Machine-readable expected value / schema $id / acceptable forms. */\n  expected?: unknown;\n  /** Machine-readable actual value / schema errors / observed non-object. */\n  actual?: unknown;\n  /** Schema $id applied; set only for `response_schema`. */\n  schema_id?: string | null;\n  /** Resolvable schema URL; set only for `response_schema`. */\n  schema_url?: string | null;\n  /** Exact request the runner sent (present on failure when available). */\n  request?: RunnerRequestRecord;\n  /** Exact response observed (present on failure when available). */\n  response?: RunnerResponseRecord;\n  /** Optional remediation hint. */\n  remediation?: string;\n  /**\n   * Marker for an implemented check whose declared applicability conditions\n   * were not met. Unknown authored check kinds fail closed; they never set\n   * this flag or contribute a false green result. Entries carrying this flag\n   * contribute to `validations_not_applicable` so consumers can distinguish\n   * inapplicable coverage from clean passes.\n   */\n  not_applicable?: boolean;\n  /**\n   * Human-readable note attached to a passing-but-not-applicable result\n   * (forward-compat path) or other informational annotations. Distinct\n   * from `warning` which signals a soft issue on a successful check.\n   */\n  note?: string;\n  /**\n   * Non-fatal notes emitted by the check — e.g. `refs_resolve` records the\n   * out-of-scope refs it skipped when `on_out_of_scope: warn`. Present only\n   * when the check has something to report; absent otherwise.\n   */\n  observations?: unknown[];\n  /**\n   * Non-fatal human-readable warning attached when a check `passed` but\n   * detected a softer issue the caller should still see. `response_schema`\n   * uses this for variant-fallback diagnostics and, when strict grading is\n   * explicitly disabled, strict-only AJV findings. LLM-driven self-correction\n   * and CI graphs that scan `error`/`warning` fields can act on the warning.\n   */\n  warning?: string;\n  /**\n   * Issue #820 follow-up — strict JSON-schema (AJV) verdict for\n   * `response_schema` checks. Packaged-schema storyboard runs grade this\n   * verdict by default; `strictResponseSchemaValidation: false` restores the\n   * historical lenient grade while retaining the verdict as diagnostics.\n   * An external `schemaRoot` is always authoritative. Absent on\n   * non-response_schema checks or when no AJV schema is available.\n   */\n  strict?: StrictValidationVerdict;\n}\n\n/**\n * Strict (AJV JSON-schema) verdict attached to a response_schema\n * validation result. Authoritative by default for packaged-cache storyboard\n * runs and always authoritative for runs with an external `schemaRoot`.\n * Packaged-cache callers may explicitly make it informational with\n * `strictResponseSchemaValidation: false` during migrations.\n */\nexport interface StrictValidationVerdict {\n  valid: boolean;\n  /**\n   * Outcome from the SDK's packaged Zod snapshot, captured only as a\n   * comparison signal. `null` means that snapshot has no schema for the tool.\n   * External-schema runs never use this field to decide pass/fail.\n   */\n  lenient_valid?: boolean | null;\n  /** Response variant AJV ultimately validated against. After fallback: `\"sync\"`. */\n  variant: string;\n  /** Concrete AJV issues (RFC 6901 pointers) when `valid: false`. Absent when valid. */\n  issues?: SchemaValidationError[];\n  /**\n   * True when the agent's response `status` field named an async variant\n   * (`submitted` / `working` / `input-required`) but no compiled schema\n   * existed for that variant, so validation fell back to the sync\n   * response schema. Conformance signal: the agent advertised an async\n   * shape this tool doesn't explicitly schema. Present only on fallback.\n   */\n  variant_fallback_applied?: boolean;\n  /** Variant requested by payload shape before fallback. Set iff `variant_fallback_applied`. */\n  requested_variant?: string;\n}\n\nexport interface StoryboardStepPreview {\n  step_id: string;\n  phase_id: string;\n  title: string;\n  task: string;\n  narrative?: string;\n  expected?: string;\n  /** sample_request with context already injected */\n  sample_request?: Record<string, unknown>;\n}\n\nexport interface StoryboardStepResult {\n  /** Storyboard that produced this step result. */\n  storyboard_id?: string;\n  step_id: string;\n  phase_id: string;\n  title: string;\n  task: string;\n  passed: boolean;\n  /** True when the step was not executed */\n  skipped?: boolean;\n  /**\n   * Skip reason. Accepts either a canonical `RunnerSkipReason` or one of the\n   * grader-specific variants introduced\n   * by the RFC 9421 request-signing grader (#585, #617). The structured\n   * `skip` field below always carries the canonical spec reason so consumers\n   * of the runner-output contract don't need to know the grader vocabulary.\n   * In particular, `rate_limit_not_triggered` is a passing skipped result\n   * with `skip.reason === 'not_applicable'`,\n   * `skip.detail === 'rate_limit_not_triggered'`, and no validations. Its\n   * human-readable diagnostic remains on the legacy `response.error` field.\n   */\n  skip_reason?: RunnerSkipReason | RunnerDetailedSkipReason;\n  /** Structured skip result with canonical spec reason + contract-defined detail. */\n  skip?: RunnerSkipResult;\n  /**\n   * Structured selection result for steps that were outside the caller's\n   * requested run before execution. Kept separate from `skip`: skipped means\n   * selected-but-not-executed, selection means not selected for this run.\n   */\n  selection_result?: RunnerSelectionResult;\n  /** True when the step expected an error (inverted pass/fail) */\n  expect_error?: boolean;\n  duration_ms: number;\n  /** Raw parsed response body (legacy field; new code reads `response_record`). */\n  response?: unknown;\n  validations: ValidationResult[];\n  /** Accumulated context after this step */\n  context: StoryboardContext;\n  /**\n   * Accumulated context-provenance after this step. Each entry records which\n   * step wrote the matching context key and how (convention extractor vs\n   * author-provided `context_outputs` path). Thread back into\n   * `StoryboardRunOptions.context_provenance` on the next `runStoryboardStep`\n   * invocation so hints fire across the stateless step-by-step surface the\n   * same way they do inside `runStoryboard`. adcp-client#880.\n   */\n  context_provenance?: Record<string, ContextProvenanceEntry>;\n  /**\n   * Accumulated response-derived `not_applicable` context-key map after this\n   * step. Thread back into `StoryboardRunOptions.response_derived_not_applicable_context_keys`\n   * on the next `runStoryboardStep` invocation so cursor consumers skip as\n   * `not_applicable` rather than `prerequisite_failed`.\n   */\n  response_derived_not_applicable_context_keys?: Record<string, string>;\n  /**\n   * Contribution flags accumulated after this step. Thread back into\n   * `StoryboardRunOptions.contributions` on the next `runStoryboardStep`\n   * invocation when orchestrating a storyboard step-by-step.\n   */\n  contributions?: string[];\n  error?: string;\n  /**\n   * Structured AdCP error forwarded from the transport layer when the step failed.\n   * Carries `code`, `field`, and `details.validation_errors` so dashboards and\n   * LLM self-correction loops can identify the exact fault address without\n   * re-running the step. Present only when the underlying task returned a\n   * structured `adcp_error` envelope; absent for transport-level failures.\n   */\n  adcp_error?: import('../../core/ConversationTypes').AdcpErrorInfo;\n  /** Preview of the next step (for LLM consumption) */\n  next?: StoryboardStepPreview;\n  /** Agent URL that served this step (multi-instance mode). Absent in single-URL mode. */\n  agent_url?: string;\n  /** 1-based index of the agent instance (multi-instance mode). Absent in single-URL mode. */\n  agent_index?: number;\n  /** Exact request the runner sent (contract-required on failures). */\n  request?: RunnerRequestRecord;\n  /** Exact response observed, including transport, status, headers. */\n  response_record?: RunnerResponseRecord;\n  /** Which extraction path produced the parsed response (required per contract). */\n  extraction: RunnerExtractionRecord;\n  /**\n   * Informational notices scoped to this step. These do not affect pass/fail.\n   * Storyboard-level `notices` aggregates step notices by code.\n   */\n  notices?: RunnerNotice[];\n  /**\n   * Non-fatal diagnostic hints the runner emitted alongside this step —\n   * currently surfaces `context_value_rejected` when a request value came\n   * from a prior-step `$context.*` write and the seller's error response\n   * lists the set of values it would have accepted. Pass/fail is unchanged;\n   * hints help triage collapse from \"SDK bug vs seller bug\" to one line.\n   */\n  hints?: StoryboardStepHint[];\n}\n\n/**\n * Provenance entry for a context key: which step wrote it and how.\n * Populated by the runner as it applies `context_outputs` and convention-\n * based extractors after each successful step, and consumed when emitting\n * `context_value_rejected` hints.\n */\nexport interface ContextProvenanceEntry {\n  /** Step id that produced this context value. */\n  source_step_id: string;\n  /**\n   * `context_outputs`: author-authored extraction from the YAML.\n   * `convention`: task-default extractor in CONTEXT_EXTRACTORS.\n   * `generator`: runner-minted value (no response path involved).\n   */\n  source_kind: 'context_outputs' | 'convention' | 'generator';\n  /** Response path the value was extracted from (set for `context_outputs`). */\n  response_path?: string;\n  /** Task name whose response this value was extracted from. */\n  source_task?: string;\n}\n\n/**\n * Common shape every `StoryboardStepHint` member shares: the discriminator\n * + a pre-formatted human-readable message. Renderers that don't know a\n * specific `kind` can still display `message` verbatim; renderers that do\n * know the `kind` can branch on it and read the structured fields each\n * member adds. Issue #935: \"every runner-side diagnostic with structured\n * fields a renderer can consume\" flows through this surface.\n */\nexport interface StoryboardStepHintBase {\n  /** Discriminator. Each concrete hint kind sets its own literal value.\n   * @provenance runner\n   */\n  kind: string;\n  /**\n   * Pre-formatted human-readable message suitable for a console line.\n   * @provenance seller\n   * Contains pre-interpolated seller-derived bytes for\n   * `context_value_rejected` (rejected value, accepted values, request field\n   * pointer) and `monotonic_violation` (resource id, prior and current status)\n   * hint kinds. Treat as untrusted when rendering into LLM context or any\n   * prompt-injection-sensitive surface; build safe output from the structured\n   * `@provenance runner` / `@provenance storyboard` fields instead, or\n   * sanitize at the boundary.\n   *\n   * `shape_drift` and `missing_required_field` messages are composed entirely\n   * from runner-derived tokens and are safe to render without sanitization.\n   * `format_mismatch` messages are safe under the current AJV configuration\n   * (no custom error-message plugins); if `ajv-errors` or a custom AJV\n   * keyword message factory is added, audit whether it embeds seller data\n   * values before treating `format_mismatch` messages as trusted.\n   */\n  message: string;\n}\n\n/**\n * Non-fatal hint attached to a step result. The discriminator lives on\n * `kind` so consumers that only know how to render a subset can ignore\n * the rest without losing them; `message` is always present as a\n * human-readable fallback (see `StoryboardStepHintBase`). More kinds\n * may be added over time — issue #935 enumerated the canonical taxonomy.\n */\nexport type StoryboardStepHint =\n  | ContextValueRejectedHint\n  | ShapeDriftHint\n  | MissingRequiredFieldHint\n  | FormatMismatchHint\n  | MonotonicViolationHint\n  | ImpairmentCoherenceHint\n  | ImpairmentCoherenceNotApplicableHint;\n\n/**\n * A seller rejected a request value that the runner traced back to a\n * `$context.*` substitution (or a request-builder field populated from the\n * same context key). Without this hint, the rejection in logs looks\n * identical to an SDK bug; with it, the caller can see the substitution\n * chain (step → context key → response path) and go talk to the seller.\n */\nexport interface ContextValueRejectedHint extends StoryboardStepHintBase {\n  kind: 'context_value_rejected';\n  /**\n   * Context key whose value matched the rejected request field.\n   * @provenance storyboard\n   */\n  context_key: string;\n  /**\n   * Step id that wrote the context key.\n   * @provenance runner\n   */\n  source_step_id: string;\n  /**\n   * How the context key was written (`context_outputs` vs convention vs generator).\n   * @provenance runner\n   */\n  source_kind: 'context_outputs' | 'convention' | 'generator';\n  /**\n   * YAML response path set for `context_outputs`; absent for convention extractors and generators.\n   * @provenance storyboard\n   */\n  response_path?: string;\n  /**\n   * Task whose response the value was extracted from.\n   * @provenance storyboard\n   */\n  source_task?: string;\n  /**\n   * The value the seller rejected. Copied verbatim from context (which was\n   * itself extracted from a prior seller response); already embedded in\n   * `message` via string interpolation — sanitize before rendering into LLM\n   * context.\n   * @provenance seller\n   */\n  rejected_value: unknown;\n  /**\n   * Dotted path to the rejected field in the runner's request (when the\n   * seller's error carried an explicit `field` pointer). Absent when the\n   * match was resolved by scanning the request for a context-sourced value\n   * in the rejection set. Sourced from the seller's `errors[].field` pointer\n   * and normalized by `normalizeFieldPath()` (RFC 6901 → dotted form);\n   * already embedded in `message` — sanitize before LLM rendering.\n   * @provenance seller\n   */\n  request_field?: string;\n  /**\n   * The accepted values the seller reported (`available` / `allowed` /\n   * `accepted_values`). Elements are unconstrained seller strings embedded\n   * verbatim in `message`; sanitize before rendering into LLM context or\n   * any prompt-injection-sensitive surface.\n   * @provenance seller\n   */\n  accepted_values: unknown[];\n  /**\n   * Error code from the seller's error (if present).\n   * @provenance seller\n   */\n  error_code?: string;\n}\n\n/**\n * The runner detected that the agent's response payload diverged from the\n * expected shape for the tool — e.g. a list tool returned a bare array\n * instead of `{ <wrapper_key>: [...] }`, or `build_creative` returned\n * platform-native fields at the top level instead of `{ creative_manifest }`.\n *\n * Non-fatal: step pass/fail is unchanged. The runner emits this in place of\n * the legacy `ValidationResult.warning` prose so downstream renderers (CLI,\n * Addie, JUnit) can build per-case fix plans from the structured fields.\n *\n * `instance_path` uses RFC 6901 / `SchemaValidationError.instance_path`\n * conventions: `\"\"` for root-level drift, leading-slash + tokens for nested.\n */\nexport interface ShapeDriftHint extends StoryboardStepHintBase {\n  kind: 'shape_drift';\n  /**\n   * AdCP tool name (snake_case) that produced the drift.\n   * @provenance runner\n   */\n  tool: string;\n  /**\n   * Short token describing the observed (wrong) shape variant. Always a\n   * runner-hardcoded string (`bare_array`, `platform_native_fields`, etc.)\n   * derived from pattern-matching the seller's response shape — not the\n   * seller's payload bytes directly.\n   * @provenance runner\n   */\n  observed_variant: string;\n  /**\n   * Short token or schema fragment describing the expected shape.\n   * @provenance runner\n   */\n  expected_variant: string;\n  /**\n   * RFC 6901 pointer to the drift site; `\"\"` for root-level. Hardcoded by\n   * the runner's shape-detector; not derived from seller response content.\n   * @provenance runner\n   */\n  instance_path: string;\n}\n\n/**\n * Strict (AJV) JSON-schema validation reports a missing required field that\n * the lenient Zod path didn't enforce. Mirrors the `SchemaValidationError`\n * shape so a renderer can drive directly off the structured fields without\n * re-parsing the prose `validation.warning`.\n */\nexport interface MissingRequiredFieldHint extends StoryboardStepHintBase {\n  kind: 'missing_required_field';\n  /**\n   * AdCP tool name (snake_case) the response was validated under.\n   * @provenance runner\n   */\n  tool: string;\n  /**\n   * RFC 6901 pointer to the parent object missing the field. `\"\"` for root.\n   * Generated by AJV from the JSON schema evaluation result.\n   * @provenance runner\n   */\n  instance_path: string;\n  /**\n   * Pointer into the JSON schema that named the requirement.\n   * @provenance runner\n   */\n  schema_path: string;\n  /**\n   * Field name(s) the parent object was required to carry. Every entry is a\n   * bare identifier extracted from the AJV error message (via the pattern\n   * `required property 'X'`). AJV issues whose message does not match that\n   * pattern — e.g. a reworded or locale-variant message from a future AJV\n   * major or a custom AJV instance — are omitted rather than included\n   * verbatim. Callers can rely on every entry being a plain field name.\n   * The raw AJV issue message may still appear in `ValidationResult.warning`\n   * prose for human readers.\n   * @provenance runner\n   */\n  missing_fields: string[];\n  /**\n   * Resolvable schema URL (when the runner could attribute one).\n   * @provenance runner\n   */\n  schema_url?: string;\n}\n\n/**\n * Strict (AJV) JSON-schema validation rejected a value that the lenient Zod\n * path accepted — a `format` keyword breach (uri / date-time / uuid / ...)\n * or other strict-only delta the agent ships today that a strict dispatcher\n * would block (issue #820). Carries enough structured detail for a renderer\n * to write a verify-after-fix recipe.\n */\nexport interface FormatMismatchHint extends StoryboardStepHintBase {\n  kind: 'format_mismatch';\n  /**\n   * AdCP tool name (snake_case).\n   * @provenance runner\n   */\n  tool: string;\n  /**\n   * RFC 6901 pointer to the failing field. Generated by AJV; identifies a\n   * location in the seller's response but the pointer string itself is\n   * runner-derived.\n   * @provenance runner\n   */\n  instance_path: string;\n  /**\n   * Pointer into the JSON schema that named the constraint.\n   * @provenance runner\n   */\n  schema_path: string;\n  /**\n   * AJV keyword that rejected (`format`, `pattern`, `enum`, `minLength`, ...).\n   * Runner-internal pseudo-keyword `truncated` is used when the hint count\n   * is capped.\n   * @provenance runner\n   */\n  keyword: string;\n  /**\n   * Resolvable schema URL (when the runner could attribute one).\n   * @provenance runner\n   */\n  schema_url?: string;\n}\n\n/**\n * The `status.monotonic` invariant observed a resource transition that is\n * not on the spec lifecycle graph for its resource type. Carries the\n * structured fields a renderer needs to point the implementor at the\n * canonical enum schema and the prior step that set the anchor state.\n */\nexport interface MonotonicViolationHint extends StoryboardStepHintBase {\n  kind: 'monotonic_violation';\n  /**\n   * Resource family (`media_buy`, `creative`, `account`, ...). Hardcoded by\n   * the runner's per-resource-type extractors.\n   * @provenance runner\n   */\n  resource_type: string;\n  /**\n   * Resource id observed transitioning. Extracted from the seller's response\n   * (e.g. `media_buy_id`, `creative_id`) and embedded in `message` —\n   * sanitize before rendering into LLM context.\n   * @provenance seller\n   */\n  resource_id: string;\n  /**\n   * Status the resource was in at the anchor step. Recorded by the runner\n   * from a prior step's seller response and stored in the assertion's state\n   * map; embedded in `message` — sanitize before LLM rendering.\n   * @provenance seller\n   */\n  from_status: string;\n  /**\n   * Status the resource transitioned to at the current step. Read directly\n   * from the seller's current response; embedded in `message` — sanitize\n   * before LLM rendering.\n   * @provenance seller\n   */\n  to_status: string;\n  /**\n   * Step id that recorded the previous status. Runner-tracked internal ID.\n   * @provenance runner\n   */\n  from_step_id: string;\n  /**\n   * Legal next-state set per the lifecycle graph. Empty array means the\n   * `from_status` is terminal — the violation is \"any forward transition\n   * from a terminal state\". Derived from the runner's hardcoded transition\n   * tables in `default-invariants.ts`.\n   * @provenance runner\n   */\n  legal_next_states: string[];\n  /**\n   * Canonical enum schema URL for the lifecycle graph. Runner-constructed\n   * from `ADCP_VERSION` and the per-resource enum filename.\n   * @provenance runner\n   */\n  enum_url: string;\n}\n\n/**\n * The `impairment.coherence` invariant observed a mismatch between a media\n * buy's `impairments[]` array and the underlying resource state. Three\n * violation shapes share this hint:\n *   - `forward`: an entry in `impairments[]` references a resource whose\n *     last observed status is NOT an offline value.\n *   - `inverse`: a resource was observed transitioning to an offline state\n *     and is referenced by a non-terminal buy, but is missing from that\n *     buy's `impairments[]`.\n *   - `health`: the buy's `health` field disagrees with `impairments[]`\n *     emptiness — `impaired` iff non-empty (and vice versa).\n *\n * See adcontextprotocol/adcp#2859 for the originating spec issue.\n */\nexport interface ImpairmentCoherenceHint extends StoryboardStepHintBase {\n  kind: 'impairment_coherence_violation';\n  /**\n   * Discriminator for the violation shape (see the union of `forward`,\n   * `inverse`, `health` documented on the type). Renderers can branch on\n   * `violation` to pick a per-shape template.\n   * @provenance runner\n   */\n  violation: 'forward' | 'inverse' | 'health';\n  /**\n   * Media-buy id whose `impairments[]` snapshot the violation was detected\n   * on. Read from `media_buy_id` on the buy response.\n   * @provenance seller\n   */\n  media_buy_id: string;\n  /**\n   * Step id that returned the offending media-buy snapshot.\n   * @provenance runner\n   */\n  buy_step_id: string;\n  /**\n   * Resource family (`creative`, `audience`, `catalog_item`, `event_source`)\n   * the entry references. Present on `forward` and `inverse`.\n   * @provenance seller (forward) / runner (inverse)\n   */\n  resource_type?: string;\n  /**\n   * Resource id the entry references. Present on `forward` and `inverse`.\n   * @provenance seller (forward) / runner (inverse)\n   */\n  resource_id?: string;\n  /**\n   * Status the runner has on file for the referenced resource. Present on\n   * `forward` and `inverse`. On `forward` it is the non-offline status that\n   * makes the impairment a false positive; on `inverse` it is the offline\n   * status the seller failed to propagate.\n   * @provenance seller\n   */\n  resource_status?: string;\n  /**\n   * Step id that recorded `resource_status`.\n   * @provenance runner\n   */\n  resource_step_id?: string;\n  /**\n   * Health value present on the buy snapshot when the violation is `health`.\n   * The literal seller-returned value, undefined when the field is absent.\n   * @provenance seller\n   */\n  buy_health?: string;\n  /**\n   * `impairments[].length` on the buy snapshot. Present on all three shapes.\n   * @provenance seller\n   */\n  impairments_count: number;\n}\n\n/**\n * The `impairment.coherence` invariant observed an offline-state transition\n * for a resource family whose buy → resource reverse-traversal isn't yet\n * implemented (audience / catalog_item / event_source). The forward rule\n * still grades these families; the inverse rule cannot, so the runner\n * surfaces the deferred coverage at the transition step instead of skipping\n * silently. Tracked in adcontextprotocol/adcp#2860.\n */\nexport interface ImpairmentCoherenceNotApplicableHint extends StoryboardStepHintBase {\n  kind: 'impairment_coherence_not_applicable';\n  /**\n   * Always `'inverse'` for this hint — the rule that can't grade.\n   * @provenance runner\n   */\n  violation: 'inverse';\n  /**\n   * Machine-readable reason code. Consumers can filter on this without\n   * matching prose.\n   * @provenance runner\n   */\n  reason: 'resource_traversal_deferred';\n  /**\n   * Resource family the transition was observed on. One of the three\n   * deferred families.\n   * @provenance runner\n   */\n  resource_type: 'audience' | 'catalog_item' | 'event_source';\n  /**\n   * Resource id the transition was observed on.\n   * @provenance seller\n   */\n  resource_id: string;\n  /**\n   * Offline status the resource transitioned to (`suspended` / `withdrawn`\n   * / `insufficient`).\n   * @provenance seller\n   */\n  resource_status: string;\n  /**\n   * Step id that recorded the offline transition.\n   * @provenance runner\n   */\n  resource_step_id: string;\n}\n\nexport interface StoryboardPhaseResult {\n  phase_id: string;\n  phase_title: string;\n  passed: boolean;\n  steps: StoryboardStepResult[];\n  duration_ms: number;\n}\n\nexport interface StoryboardResult {\n  storyboard_id: string;\n  storyboard_title: string;\n  /** Primary agent URL. In multi-instance mode this is the first URL — see agent_urls for the full list. */\n  agent_url: string;\n  /** All agent URLs used in multi-instance mode. Absent (or single-entry) in single-URL mode. */\n  agent_urls?: string[];\n  /** Distribution strategy used across agent_urls. Absent in single-URL mode. */\n  multi_instance_strategy?: 'round-robin' | 'multi-pass';\n  /**\n   * Per-specialism routing map (#1066). Echoes `StoryboardRunOptions.agents`\n   * resolved to `{ key: url }` so JUnit/CI consumers and bug reports show\n   * the topology this run executed against. Absent when not in routed mode.\n   * Each `StoryboardStepResult.agent_url` echoes the URL of the routed\n   * agent for that step.\n   */\n  agent_map?: Record<string, string>;\n  overall_passed: boolean;\n  /** AdCP 3.2 fixture-handle setup/discovery evidence, one row per handle. */\n  fixture_resolutions?: FixtureResolutionRecord[];\n  /** Storyboard-level fixture coverage gaps, emitted once per cause. */\n  coverage_gaps?: FixtureResolutionCoverageGap[];\n  /**\n   * Phases from the first pass. In `multi-pass` mode see `passes` for the full\n   * per-pass detail; `passed_count`/`failed_count`/`skipped_count` and\n   * `overall_passed` aggregate across all passes.\n   */\n  phases: StoryboardPhaseResult[];\n  /**\n   * Per-pass detail in `multi-pass` mode — one entry per starting replica so\n   * each step is served by each replica at least once across passes. Absent\n   * in single-pass modes. Per-pair cross-replica coverage depends on\n   * dispatch-index distance modulo `agent_urls.length` (see\n   * `multi_instance_strategy` on `StoryboardRunOptions`).\n   */\n  passes?: StoryboardPassResult[];\n  /** Final accumulated context */\n  context: StoryboardContext;\n  total_duration_ms: number;\n  passed_count: number;\n  failed_count: number;\n  skipped_count: number;\n  /** Failed advisory validations, counted separately from failed steps. */\n  validations_advisory_failed?: number;\n  /**\n   * Validation results graded `not_applicable` because the runner did not\n   * implement the authored `check` kind (forward-compat default). Surfaces\n   * \"runner is older than the storyboard\" as a distinct signal from clean\n   * passes. Per runner-output-contract.yaml v2.0.0 run_summary.\n   */\n  validations_not_applicable?: number;\n  /** Semver capability used to evaluate advisory validation expiry gates. */\n  runner_capability_version?: string;\n  tested_at: string;\n  /**\n   * Schemas applied during this run. Per the runner-output contract, runners\n   * MUST surface the exact schema identities so implementors can re-validate\n   * locally against the same artifacts.\n   */\n  schemas_used?: Array<{ schema_id: string; schema_url: string }>;\n  /**\n   * Results from cross-step assertions declared on the storyboard's\n   * `invariants` field. Step-scoped failures also surface inside the owning\n   * step's `validations[]` with `check: \"assertion\"`; storyboard-scoped\n   * failures live only here. `overall_passed` is false when any assertion\n   * failed.\n   */\n  assertions?: AssertionResult[];\n  /**\n   * Issue #820 follow-up — strict/lenient `response_schema` delta. Always\n   * emitted by the runner; inspect `observable` first to distinguish\n   * \"observed zero strict-eligible checks\" from \"observed N and graded\n   * them\". Storyboards dominated by non-`response_schema` validations\n   * (`field_present`, `error_code`, pure `assertion` runs) will have\n   * `observable: false` and zeroed counters.\n   */\n  strict_validation_summary?: StrictValidationSummary;\n  /**\n   * Structured protocol-compliance advisories produced for this storyboard\n   * run. Each notice carries a stable `code` (machine-readable, suitable for\n   * CI badge routing) and a non-grading `severity` (`info` | `deprecation` |\n   * `future_required`).\n   * Always present; empty array when no notices were triggered.\n   *\n   * `ComplianceResult.notices` aggregates across all storyboard runs,\n   * deduplicated by `code`, or by (`code`, `capability_pointer`) when a\n   * capability pointer is present. Spec: adcp-client#1704 and adcp#6256.\n   */\n  notices: RunnerNotice[];\n  /**\n   * Agents in the routing map whose `get_adcp_capabilities` probe failed\n   * when `StoryboardRunOptions.discovery_resilient: true` was set. Absent\n   * when resilient mode is off (because failures throw before result\n   * construction) and absent when no failures occurred. Each entry carries\n   * the agent key, URL, and the scrubbed underlying error so operators\n   * see the topology breakage without correlating across log lines.\n   *\n   * **Read together with `overall_passed`.** A passing storyboard with a\n   * non-empty `discovery_failures` means the storyboard did NOT touch any\n   * tools that needed the failed agents — it does NOT mean the topology\n   * was healthy. Dashboards and procurement reports should surface both\n   * fields; a green check next to a populated `discovery_failures` is\n   * legitimate but misleading without the second-axis signal.\n   *\n   * **Buyer-controlled untrusted content.** The `error` string is\n   * upstream-agent-derived and may contain attacker-influenced text from\n   * a malicious or compromised agent. The runner bounds the string\n   * (~512 chars) and runs the existing auth-secret scrub, but the\n   * remaining content is untrusted — validate / fence before templating\n   * into LLM prompts. The `url` field is scrubbed of userinfo\n   * (`//user:pass@host` → `//[REDACTED]@host`) so operator-encoded\n   * credentials don't leak to dashboards.\n   *\n   * Spec: adcp-client#1367.\n   */\n  discovery_failures?: Array<{ agent_key: string; url: string; error: string }>;\n}\n\nexport interface StrictValidationSummary {\n  /**\n   * True when at least one `response_schema` validation had an AJV\n   * validator compiled (the strict path could actually grade something).\n   * False means \"unobservable\": the run exercised only tasks whose JSON\n   * schema isn't registered, or only non-`response_schema` validations —\n   * NOT \"strict-clean with zero findings\". Downstream dashboards and\n   * CI formatters MUST check this before rendering the counts.\n   */\n  observable: boolean;\n  /** Response-schema checks that had an AJV validator compiled. */\n  checked: number;\n  /** Of `checked`, how many passed strict AJV. */\n  passed: number;\n  /** Of `checked`, how many failed strict AJV. Equals `checked - passed`. */\n  failed: number;\n  /**\n   * Count of validations where lenient Zod accepted AND strict AJV\n   * rejected — the \"silent failures\" the agent ships today that a strict\n   * dispatcher would block. Subset of `failed`. This is the actionable\n   * production-readiness signal for agent developers. With the default\n   * strict grading these failures make the owning step fail; callers that\n   * explicitly disable strict grading can still use this count as migration\n   * telemetry.\n   */\n  strict_only_failures: number;\n  /**\n   * Count of validations where BOTH lenient Zod AND strict AJV rejected —\n   * the step already failed under today's semantics, so strict rejection\n   * isn't new signal. Useful for dashboards that want to distinguish\n   * \"already-failing\" from \"silently-failing\" in the same run. Strict\n   * failures without a packaged Zod comparator are reported separately as\n   * `lenient_unobserved`.\n   */\n  lenient_also_failed: number;\n  /**\n   * Strict AJV failures for tools with no packaged Zod schema to compare.\n   * Present only when non-zero so older serialized summaries remain stable.\n   */\n  lenient_unobserved?: number;\n}\n\n/**\n * Single assertion outcome recorded by the runner. Mirrors the shape of\n * `ValidationResult` so existing consumers can render assertions with the\n * same code path, while adding scope + source fields that identify where\n * the failure originated.\n */\nexport interface AssertionResult {\n  /** Id of the registered assertion that produced this result. */\n  assertion_id: string;\n  passed: boolean;\n  /** Human-readable description of the property being asserted. */\n  description: string;\n  /** Whether this result was raised at a specific step or storyboard-wide. */\n  scope: 'step' | 'storyboard';\n  /** Step that produced the observation, when `scope === \"step\"`. */\n  step_id?: string;\n  /** 1-based pass index when aggregated from a multi-pass run. */\n  pass_index?: number;\n  /** Failure detail. Absent on pass. */\n  error?: string;\n  /**\n   * Structured `StoryboardStepHint` the assertion can attach when it has\n   * machine-readable fields a renderer can consume. The runner mirrors this\n   * into the owning step's `hints[]` for `scope: \"step\"` results so the\n   * hint surfaces alongside `context_value_rejected` / `shape_drift` /\n   * strict-AJV hints under one taxonomy. Absent when the assertion only\n   * has prose to report.\n   */\n  hint?: StoryboardStepHint;\n  /**\n   * Lifecycle resources or transitions an observation-based invariant\n   * saw over the run. Set only by invariants whose verdict is meaningful\n   * exclusively when something was observed (`status.monotonic` today),\n   * emitted on the `onEnd` summary record. The track-level rollup\n   * demotes a passing track to `TrackStatus: 'silent'` when every record\n   * carrying this field reports `0`.\n   *\n   * This MUST count actual lifecycle resources or transitions observed\n   * — never \"the assertion was applicable\" or \"the assertion ran.\" A\n   * future invariant that emits `observation_count` with skip-style\n   * semantics would cause silent demotion for the wrong reason.\n   *\n   * Absent on assertions that don't model observation counts. Companion\n   * to adcontextprotocol/adcp#2834.\n   */\n  observation_count?: number;\n  /**\n   * Distinguishes `'silent'` (wired but no observations) from `'pass'`\n   * (wired and exercised). Per-assertion analog of the track-level\n   * `TrackStatus: 'silent'` rollup — consumers (graders, dashboards) that\n   * render per-assertion results need a direct enum here so the\n   * \"wired-but-not-observed\" outcome doesn't render identically to a real\n   * pass.\n   *\n   * Set by observation-based invariants on their `onEnd` summary record:\n   * `'silent'` when `observation_count === 0` AND `passed === true`,\n   * `'pass'` when `observation_count > 0` AND `passed === true`,\n   * `'fail'` when `passed === false`. Absent on assertions that don't\n   * model observation counts (their `passed` flag is sufficient).\n   *\n   * `'not_applicable'` is emitted at step scope by an invariant that\n   * recognises an observation it could grade in principle but whose\n   * grading path isn't yet implemented in the runner (e.g.\n   * `impairment.coherence` inverse rule for audience / catalog_item /\n   * event_source — tracked in adcontextprotocol/adcp#2860). The\n   * accompanying `hint` carries the deferral reason and resource family\n   * so renderers can distinguish a deferred coverage hint from a clean\n   * pass. Companion to adcontextprotocol/adcp#2834.\n   */\n  status?: 'pass' | 'silent' | 'fail' | 'not_applicable';\n}\n\n/**\n * Single pass in `multi-pass` multi-instance mode. Each pass re-runs the\n * whole storyboard with a different round-robin starting offset so each\n * step is served by each replica at least once across passes. See\n * `multi_instance_strategy` on `StoryboardRunOptions` for the N=2\n * per-pair coverage caveat.\n */\nexport interface StoryboardPassResult {\n  /** 1-based pass index. */\n  pass_index: number;\n  /** 0-based starting replica for this pass's round-robin dispatch. */\n  dispatch_offset: number;\n  overall_passed: boolean;\n  phases: StoryboardPhaseResult[];\n  passed_count: number;\n  failed_count: number;\n  skipped_count: number;\n  /** Failed advisory validations, counted separately from failed steps. */\n  validations_advisory_failed?: number;\n  /** Validations graded `not_applicable` (forward-compat default). */\n  validations_not_applicable?: number;\n  duration_ms: number;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA08CO,MAAM,kCAAkC;AA2pBxC,MAAM,6BAAiF;AAAA,EAC5F,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,gBAAgB;AAAA,EAChB,6BAA6B;AAAA,EAC7B,sBAAsB;AAAA,EACtB,6BAA6B;AAAA,EAC7B,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,4BAA4B;AAAA,EAC5B,0BAA0B;AAAA,EAC1B,qBAAqB;AAAA,EACrB,wBAAwB;AAAA,EACxB,oBAAoB;AAAA,EACpB,2BAA2B;AAAA,EAC3B,kCAAkC;AAAA,EAClC,eAAe;AAAA,EACf,2BAA2B;AAC7B;AAuDO,MAAM,qBAAmD,oBAAI,IAAI;AAAA,EACtE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAA+C;","names":[]}