compliance pre-flight throws on `signed-requests` specialism claim despite universal/ bundle + #2082 notice

[kapoost]

Problem

Two SDK code paths contradict each other on the deprecated signed-requests specialism claim:

1. createAdcpServer (require the claim):
src/lib/server/create-adcp-server.ts (around the claimsSignedRequests guard) hard-throws when signedRequests: {...} is configured but capabilities.specialisms does not include signed-requests:

Error: createAdcpServer: `signedRequests` is configured but `capabilities.specialisms`
does not include "signed-requests". Add "signed-requests" to the specialisms list...

2. resolveStoryboardsForCapabilities (throw on the claim):
src/lib/testing/storyboard/compliance.ts iterates caps.specialisms, looks up index.specialisms, throws unknown_specialism if missing. signed-requests is in universal/signed-requests.yaml, not specialisms/signed-requests/, so the lookup misses and the entire compliance run is blocked:

CapabilityResolutionError: Agent declared specialism "signed-requests" but no bundle
exists at .../compliance/cache/3.1.0-rc.10/specialisms/signed-requests. Known
specialisms: audience-sync, brand-rights, ...

Reproduces against @adcp/sdk@9.0.0-beta.27 bundling 3.1.0-rc.10.

What the spec says

compliance/cache/3.1.0-rc.10/universal/signed-requests.yaml is explicit about backward-compat:

Backward-compatible specialism claims. The deprecated signed-requests specialism
enum value remains in the schema for back-compat (see adcp#3075). Agents that still
advertise specialisms: ["signed-requests"] are graded via this universal storyboard;
the runner SHOULD emit the signed_requests_specialism_deprecated notice [...]

The notice itself was shipped via #2082 — runner.ts collectCapabilityNotices() emits it correctly when the deprecated claim is present alongside request_signing.supported: true. But the pre-flight throws before any storyboard executes, so the notice never fires.

Reproduction

Minimal seller wiring (Bun, @adcp/sdk@9.0.0-beta.27):

// platform.ts
export const platform = definePlatform({
  capabilities: { specialisms: ['sales-non-guaranteed', 'signed-requests'] as const, ... },
  ...
});

// index.ts
createAdcpServerFromPlatform(platform, {
  ...,
  signedRequests: { jwks, replayStore, revocationStore },
});

Without 'signed-requests' in specialisms → createAdcpServer throws.
With it → boot succeeds, but adcp storyboard run <agent> fails pre-flight:

STORYBOARD-FAIL 1 step(s):
  - pre-flight/comply [core]: Agent declared specialism "signed-requests" but
    no bundle exists at .../specialisms/signed-requests. ...

The full suite never runs. (Workaround: drop both the specialism claim and the signedRequests config, but then we lose the verifier the spec asks us to expose.)

Proposed fix

resolveStoryboardsForCapabilities should special-case deprecated specialism aliases that resolve to a universal/ bundle:

• When iterating declaredSpecialisms, before throwing unknown_specialism, check universal/<id>.yaml. If found AND the id is on a known deprecation list (or has a deprecation_alias_universal: <id> field in the universal bundle), push it as a universal storyboard target instead of throwing.
• The deprecation notice already fires from runner.ts once the storyboard executes, satisfying the YAML contract.

Parallel cleanup (separate concern, may want its own issue):

• createAdcpServer's guard should accept either path: deprecated specialisms: ['signed-requests'] OR capabilities.request_signing.supported === true (the canonical 3.1+ surface). Today it requires the deprecated claim, which is the inverse of what the spec encourages.

Why this matters

Adopters wiring 3.1 signed-requests against current SDK 9.x are blocked from running the full storyboard suite — unknown_specialism aborts pre-flight before any other storyboard can grade. This pushes adopters toward dropping the verifier (loses spec value) or hand-patching the SDK locally (loses upgrade path). Closing this unblocks signed-requests adopters today and removes a paper cut in the 3.1 → 4.0 deprecation runway.

Context

• Found while wiring signed-requests on a production seller (purrsonality-seller-agent, kapoost) against @adcp/sdk@9.0.0-beta.27.
• adcp grade request-signing (the dedicated grader) works fine — bypasses the pre-flight path entirely.
• The seller's e2e suite verifies that the auto-wired verifier correctly rejects unsigned mutating requests, so the SDK plumbing itself is sound. Only the storyboard-runner discovery path is wrong.

Related

• adcp-client#2082 (notice emission, completed)
• adcp-client#1886 (specialisms forwarding, completed)
• spec(3.1): WG-review batch — 10 normative clarifications adcp#4796 (upstream notice contract)
• patch: reclassify signed-requests from specialism to universal capability-gated storyboard adcp#3075 (4.0 enum removal tracking)

[bokelley]

Triage

Classification: Bug
Bucket(s): conformance, library
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: universal/signed-requests.yaml backward-compat note is normative — throwing unknown_specialism violates the spec; check index.universal before throwing and skip. The createAdcpServer guard should also accept request_signing.supported: true (no deprecated specialism) as the canonical 3.1+ path.
• code-reviewer: Fix A must use continue not suppress-then-fall-through — the fall-through would push a specialism bundle from a non-existent path. Unit test for resolveStoryboardsForCapabilities({ specialisms: ['signed-requests'] }) is missing and required to ship. Both fixes must land together — either alone leaves adopters stuck.

My take: Both experts converge; both changes are non-breaking permissive relaxations of incorrect throws. Every 3.1 signed-requests adopter on SDK 9.x is currently blocked from running their full storyboard suite.

• compliance.ts ~L821: Add if (index.universal.includes(specialism)) continue; before the unknown_specialism throw. Must be a continue — suppressing without continuing falls through to push({ kind: 'specialism', ... }) and attempts to load a non-existent specialisms/signed-requests/ bundle.
• create-adcp-server.ts ~L3663: Widen the guard to if (signedRequests && !claimsSignedRequests && capConfig?.request_signing?.supported !== true) — allows the canonical 3.1+ form (request_signing.supported: true without the deprecated specialism) while still catching "config present, nothing advertised."
• Tests: Add a unit test in src/lib/testing/storyboard/ asserting resolveStoryboardsForCapabilities({ specialisms: ['signed-requests'], ... }) does not throw and does not double-load. Update JSDoc at create-adcp-server.ts ~L1083 ("both together or neither") to document the 3.1+ alternative.
• Changeset: patch; npm run ci:quick; one PR covers both files.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code