fix(runner): attribute Zod schema rejects to response_schema (#1709)

[bokelley]

Closes #1709.

The bug

When the SDK's response unwrapper rejects an agent response against the codegen-emitted Zod schema for the tool, the exception previously propagated as a generic Error('Response validation failed for ${toolName}: ...'). The runner's step-execution catch absorbed it into stepResult.error but never attributed the failure to schema validation in step.validations[]. Step-scope invariants then ran against the malformed payload, and whichever fired first (canonically context.no_secret_echo — the next default-invariant in the registered queue) became the surfaced failure in extractFailures.

BidMachine spent 10+ deploys chasing the no_secret_echo ghost before the strict-Zod root cause surfaced. Full diagnostic trace at adcontextprotocol/adcp#4419.

The fix — three layers

1. Typed error class (src/lib/utils/response-unwrapper.ts).

New ResponseSchemaValidationError extends Error. Carries:

• toolName: string — the AdCP tool whose response failed
• issues: z.core.$ZodIssue[] — raw Zod issues for structured attribution
• data: unknown — the rejected payload for diagnostic reporting
• Stable name === 'ResponseSchemaValidationError' so cross-bundle consumers can detect by string match without instanceof

Replaces the two generic new Error(...) throws in unwrapProtocolResponse.

2. runStep preserves the raw thrown value (src/lib/testing/client.ts).

Return signature widened to { result?, step, caughtError? }. The new caughtError is the raw thrown value (typed unknown) so callers can pattern-match on typed exceptions. Pre-existing callers consuming only result and step are unaffected.

3. Storyboard runner attribution + invariant short-circuit (src/lib/testing/storyboard/runner.ts).

executeStep threads caughtError from the dispatch fn. When caughtError instanceof ResponseSchemaValidationError:

• Synthesizes a response_schema ValidationResult with the structured Zod issues, the failing tool name, an RFC 6901-shaped json_pointer, and the rejection message.
• Prepends it to step.validations[] so extractFailures.find(v => !v.passed) resolves it before any inline or invariant entry.

In executeStoryboardPass, step-scope invariants short-circuit when the synthesized entry is present. Each bypassed invariant emits a single skip marker (passed: true, description: '${spec.id}: skipped — response failed schema validation') so consumers see WHICH invariants were bypassed and why, without crowding out the schema failure in extractFailures.

Tests

New test/lib/storyboard-schema-validation-attribution.test.js:

#	What it verifies
1	Synthesized response_schema entry present in step.validations when unwrapper rejects
2	response_schema is FIRST in step.validations so extractFailures picks it over invariants
3	Step-scope invariants short-circuited via skip markers (runStoryboard full-pass)
4	step.passed === false (schema rejection is a real failure)
5	ResponseSchemaValidationError class shape carries toolName / issues / data
6	name field is the literal string for cross-bundle detection

6/6 pass. Sweep of test/lib/storyboard-*.test.js covered 50+ tests with no regressions through the in-progress monitor.

Sequencing

This PR is the upstream dependency for #1707:

Issue	Status	Sequencing
#1706	merged ✓	sibling drift fix (auto-derived COMPATIBLE_ADCP_VERSIONS)
#1705	merged ✓	RunnerNotice surface — provides the channel #1707's schema_version_fetch_failed advisory needs
#1709	this PR	upstream of #1707
#1707	waiting	dynamic schema fetch + strict→passthrough + codegen regen + notice emission
#1708	auto-triage	parity smoke test — sits AFTER #1707 lands
#1711	reporter follow-up	duplicate-by-scope of #1707; closes when #1707 ships

#1709 lands first so any remaining Zod rejects during #1707's rollout produce honest signal as the strict→passthrough flip reduces reject frequency — instead of misattributing the residual cases.

Validation hook

fgranata (BidMachine) volunteered as a retest target once #1707 + #1709 land. Current comply-suite score is 63/128 (49%) vs CLI runner 45/59 (76%) — the 27-point delta is the diagnostic signal both fixes should close. Filed under adcp-client#1711.

Test plan

• npm run build clean
• npm run format:check clean
• node --test test/lib/storyboard-schema-validation-attribution.test.js — 6/6 pass
• node --test test/lib/storyboard-*.test.js — 50+ tests passing, no regressions
• After merge, the BidMachine sync_accounts failures should attribute to response_schema instead of context.no_secret_echo; one-step verification once they retest.

Part of the #1685 coordinated stance ("the SDK is a witness, not a translator"). Same anti-pattern as adcp-client#1702 / #1705: the SDK was fabricating a different failure (no_secret_echo) than what actually went wrong (schema rejection).

🤖 Generated with Claude Code