Structured `notices` on ComplianceResult / StoryboardResult (warn-on-skip surface)

[bokelley]

Summary

The runner has no structured advisory surface today. Skips carry reason + detail + requirement; there's no severity, no code, no machine-readable way to say "this passed/skipped now but will fail in 4.0" or "you're using a deprecated claim shape." Three open gaps make this load-bearing:

1. Unimplemented SHOULD already in the spec. compliance/{version}/universal/signed-requests.yaml:34 says:

   the runner SHOULD emit an informational notice (not a failure) advising the agent to drop the now-redundant specialism claim and rely solely on request_signing.supported: true.
   The SDK does not emit any notice today. The SHOULD has been silently unimplemented since the deprecated signed-requests specialism enum landed.

2. 4.0 forward-readiness signals have nowhere to live. Per schemas/cache/3.0.11/protocol/get-adcp-capabilities-response.json:892, request_signing is "Required for spend-committing operations in 4.0". Same file at line 966: legacy_hmac_fallback is "Deprecated; removed in AdCP 4.0." A 3.0 seller that legitimately skips signed_requests today (per comply(): autodetect request_signer and oauth_metadata requirements (mirror webhook_receiver autodetect from #1678) #1702) will fail compliance on the 4.0 cut with no advance warning unless the runner surfaces the signal.

3. Skip detail strings are a workaround, not a feature. comply(): autodetect request_signer and oauth_metadata requirements (mirror webhook_receiver autodetect from #1678) #1702 / PR fix(comply): autodetect request_signer + pre-empt oauth_discovery (#1702) #1703 currently rides the 4.0 forward-readiness suffix in skip.detail as a copy-edit. That works for the human report rendering but is unparseable for dashboards, JUnit consumers, or CI gates that want to display "DEPRECATION" / "FUTURE-REQUIRED" badges. The detail string is the wrong shape for downstream automation.

Proposed shape

Add notices: RunnerNotice[] to StoryboardResult (and likely surface it transitively on ComplianceResult):

```ts
export interface RunnerNotice {
/** Severity. `info` = behavior is fine today, here is context. `deprecation` = SHOULD migrate. `future_required` = will be required in a named future version; cite the version. /
severity: 'info' | 'deprecation' | 'future_required';
/* Stable machine-readable identifier so dashboards can render badges / aggregate. /
code: string;
/* Human-readable explanation; first 200 chars suitable for tabular rendering. /
message: string;
/* When `future_required`, the AdCP version that flips the requirement. /
effective_version?: string;
/* When relevant, the structured requirement name (matches `RunnerSkipResult.requirement`). /
requirement?: RequirementName;
/* Path into the agent's capability response that motivated the notice (e.g. `request_signing.supported`). */
capability_path?: string;
}
```

Concrete notices to emit on day one:

Code	Severity	Trigger
`signed_requests_specialism_deprecated`	`deprecation`	agent advertises legacy `specialisms: ['signed-requests']` enum (covers signed-requests.yaml:34)
`request_signing_required_in_4_0`	`future_required`	runner skipped `signed_requests` because `request_signing.supported !== true` (PR #1703 case)
`legacy_hmac_fallback_removed_in_4_0`	`deprecation`	agent advertises `webhook_signing.legacy_hmac_fallback: true`

Why a runner-output shape, not just a CLI report tweak

The runner output is what dashboards, JUnit consumers, and downstream Verified pipelines consume. Anything that wants to surface "passed but plan ahead" needs a stable field on the output contract, not prose in a detail string. Once the field exists, the CLI / HTML / JUnit renderers light it up consistently.

Relationship to upstream

Filing a parallel issue on `adcontextprotocol/adcp` to ask whether `runner-output-contract.yaml` should standardize the notices shape so the AdCP Verified runner and third-party CI gates converge. If upstream picks up the field, the SDK becomes a reference implementation. If upstream stays silent, the SDK keeps it as a runner-output extension. Either path lands real value; I'd rather not bake an opinion the spec can't share.

References

• PR fix(comply): autodetect request_signer + pre-empt oauth_discovery (#1702) #1703 (carries the 4.0 forward-readiness suffix in `skip.detail` as a workaround pending this surface)
• Tracking: ship 1676–1680 as one stance — the SDK is a witness, not a translator #1685 (the SDK is a witness, not a translator — same stance)
• `compliance/cache/3.0.11/universal/signed-requests.yaml` lines 30-37 (deprecated specialism notice SHOULD)
• `schemas/cache/3.0.11/protocol/get-adcp-capabilities-response.json` line 892 (request_signing 4.0 future-required), line 966 (legacy_hmac_fallback removal)

[bokelley]

Triage outcome: Execute — implemented in draft PR #1705.

What landed:

• notices: RunnerNotice[] on StoryboardResult (always-present); notices?: RunnerNotice[] on ComplianceResult (optional, deduped by code)
• New exported types: RunnerNotice, NoticeCode (stable union), NoticeSeverity
• Two spec-grounded day-one notices via collectCapabilityNotices():
  • request_signing_required_in_4_0 (future_required) — on signed_requests / request_signing_probe storyboards when request_signing.supported is absent
  • legacy_hmac_fallback_removed_in_4_0 (deprecation) — on webhook storyboards when webhook_signing.legacy_hmac_fallback: true
• All early-return paths carry notices: [] so the field is always safe to iterate
• 13 tests in test/lib/storyboard-notices.test.js using _profile injection (no live agent needed)
• Minor changeset per release policy

Deferred: signed_requests_specialism_deprecated — the 'signed-requests' specialism value is still active in the upstream spec (see adcontextprotocol/adcp#4418); deferring until upstream formally deprecates it to avoid encoding a storyboard opinion as SDK behavior.

Scoping note: legacy_hmac_fallback_removed_in_4_0 fires only on webhook-related storyboards (id matches /webhook/i or storyboard has expect_webhook* steps). A pre-PR protocol expert review flagged that firing it on every storyboard (e.g. media_buy_guaranteed_seller) is a scope mismatch — the guard mirrors how request_signing_required_in_4_0 is scoped to signing storyboards.

PR #1705 is ready for human review.

---

Generated by Claude Code

[bokelley]

Triage

Classification: Feature request
Bucket(s): library, conformance
Status: ready-for-human

What the experts said:

• code-reviewer: all three notice triggers are spec-grounded; notices 1 + 3 (signed_requests_specialism_deprecated, legacy_hmac_fallback_removed_in_4_0) can ship independently of fix(comply): autodetect request_signer + pre-empt oauth_discovery (#1702) #1703; RunnerNotice.requirement has a transitive dep on 'request_signer' from fix(comply): autodetect request_signer + pre-empt oauth_discovery (#1702) #1703 (not on main); runner-output-contract.yaml must be updated atomically with the SDK type change
• ad-tech-protocol-expert: triggers are schema-annotated facts, not SDK opinion; recommends holding until upstream #4418 defines the notices field in the contract first — cites validations_not_applicable as the exact precedent (was gated on contract-first before SDK emission); capability_path as a dotted string entrenches a form the codebase is already phasing out in favor of JSON Pointer

My take: Both experts agree the shape and triggers are sound. They diverge on timing: updating runner-output-contract.yaml atomically would require a spec-repo change (the contract lives upstream), so the code-reviewer's "atomic" path is effectively the same as the protocol expert's "wait for #4418" path. Two questions for @bokelley: (a) ship notices 1+3 now under Refs #1704 and add notice 2 post-#1703, or wait for all three? (b) capability_path as dotted key or capability_json_pointer (RFC 6901) — dotted is the current internal convention but the codebase is migrating to Pointer on wire types.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01K6V4Ge4adNBxNLtAzXhd4C

---

Generated by Claude Code