@adcp/sdk 17.0.0-beta.27 → 17.0.0-beta.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/bin/adcp-storyboard-summary.js +47 -0
  2. package/bin/adcp.js +4 -0
  3. package/dist/lib/registry/types.generated.d.ts +3 -1
  4. package/dist/lib/testing/compliance/comply.d.mts +16 -1
  5. package/dist/lib/testing/compliance/comply.d.ts +16 -1
  6. package/dist/lib/testing/compliance/comply.js +69 -5
  7. package/dist/lib/testing/compliance/comply.mjs +75 -6
  8. package/dist/lib/testing/compliance/index.d.mts +1 -1
  9. package/dist/lib/testing/compliance/index.d.ts +1 -1
  10. package/dist/lib/testing/compliance/storyboard-tracks.d.mts +6 -0
  11. package/dist/lib/testing/compliance/storyboard-tracks.d.ts +6 -0
  12. package/dist/lib/testing/compliance/storyboard-tracks.js +26 -4
  13. package/dist/lib/testing/compliance/storyboard-tracks.mjs +24 -3
  14. package/dist/lib/testing/compliance/summary.d.mts +3 -1
  15. package/dist/lib/testing/compliance/summary.d.ts +3 -1
  16. package/dist/lib/testing/compliance/summary.js +2 -1
  17. package/dist/lib/testing/compliance/summary.mjs +2 -1
  18. package/dist/lib/testing/compliance/types.d.mts +30 -1
  19. package/dist/lib/testing/compliance/types.d.ts +30 -1
  20. package/dist/lib/testing/index.d.mts +1 -1
  21. package/dist/lib/testing/index.d.ts +1 -1
  22. package/dist/lib/testing/index.js +4 -0
  23. package/dist/lib/testing/index.mjs +4 -0
  24. package/dist/lib/testing/storyboard/index.d.mts +4 -2
  25. package/dist/lib/testing/storyboard/index.d.ts +4 -2
  26. package/dist/lib/testing/storyboard/index.js +7 -0
  27. package/dist/lib/testing/storyboard/index.mjs +6 -1
  28. package/dist/lib/testing/storyboard/runner.d.mts +7 -0
  29. package/dist/lib/testing/storyboard/runner.d.ts +7 -0
  30. package/dist/lib/testing/storyboard/runner.js +15 -0
  31. package/dist/lib/testing/storyboard/runner.mjs +14 -0
  32. package/dist/lib/testing/storyboard/types.d.mts +77 -0
  33. package/dist/lib/testing/storyboard/types.d.ts +77 -0
  34. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  35. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  36. package/dist/lib/testing/storyboard/verdict-explanation.d.mts +47 -0
  37. package/dist/lib/testing/storyboard/verdict-explanation.d.ts +47 -0
  38. package/dist/lib/testing/storyboard/verdict-explanation.js +309 -0
  39. package/dist/lib/testing/storyboard/verdict-explanation.mjs +283 -0
  40. package/dist/lib/testing/types.d.mts +11 -1
  41. package/dist/lib/testing/types.d.ts +11 -1
  42. package/dist/lib/version.d.mts +3 -3
  43. package/dist/lib/version.d.ts +3 -3
  44. package/dist/lib/version.js +3 -3
  45. package/dist/lib/version.mjs +3 -3
  46. package/docs/TYPE-SUMMARY.md +2 -2
  47. package/docs/guides/VALIDATE-YOUR-AGENT.md +28 -0
  48. package/docs/llms.txt +2 -2
  49. package/docs/migration-14.x-rc-worksheet.md +4 -4
  50. package/package.json +1 -1
@@ -0,0 +1,283 @@
1
+ const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
2
+ const FIXTURE_PHASE_IDS = /* @__PURE__ */ new Set(["fixture_resolution", "prepared_fixtures_preparation_failed"]);
3
+ const RUNNER_ERROR_CHECKS = /* @__PURE__ */ new Set(["prepared_fixtures_authorization"]);
4
+ const CONTROLLER_SKIP_REASONS = /* @__PURE__ */ new Set(["missing_test_controller", "controller_seeding_failed"]);
5
+ const CONTROLLER_REQUIREMENTS = /* @__PURE__ */ new Set(["controller", "seeded_state"]);
6
+ const NEUTRAL_SKIP_REASONS = /* @__PURE__ */ new Set([
7
+ "not_applicable",
8
+ "peer_branch_taken",
9
+ "peer_substituted",
10
+ "missing_test_kit_contract",
11
+ "fixture_unavailable",
12
+ "fixture_unsatisfied",
13
+ "fixture_seed_unsupported",
14
+ "capability_unsupported"
15
+ ]);
16
+ const REASON_PRECEDENCE = [
17
+ "runner_error",
18
+ "step_failed",
19
+ "fixture_error",
20
+ "assertion_failed",
21
+ "controller_prerequisite_unmet",
22
+ "required_phase_not_executed",
23
+ "no_executed_steps",
24
+ "coverage_unverified"
25
+ ];
26
+ const MAX_CONTRIBUTORS = 20;
27
+ const MAX_MESSAGE_LENGTH = 300;
28
+ const MAX_DETAIL_LENGTH = 600;
29
+ function explainStoryboardVerdict(result, options = {}) {
30
+ if (result.overall_passed) return void 0;
31
+ const knownPhases = options.storyboard?.phases ?? [];
32
+ const optionalPhaseIds = new Set(knownPhases.filter((phase) => phase.optional === true).map((phase) => phase.id));
33
+ const optionalOnly = knownPhases.length > 0 && knownPhases.every((phase) => phase.optional === true);
34
+ const isOptionalPhase = (phaseId) => optionalPhaseIds.has(phaseId);
35
+ const phaseViews = result.passes?.length ? result.passes.flatMap((pass) => pass.phases.map((phase) => ({ phase, passIndex: pass.pass_index }))) : result.phases.map((phase) => ({ phase }));
36
+ const contributors = [];
37
+ const add = (row) => {
38
+ contributors.push(row);
39
+ };
40
+ const countedFailures = /* @__PURE__ */ new Set();
41
+ const uncountedFailures = [];
42
+ for (const view of phaseViews) {
43
+ const { phase, passIndex } = view;
44
+ for (const step of phase.steps) {
45
+ if (step.passed || step.skipped) continue;
46
+ if (step.counts_toward_failure === false || isOptionalPhase(phase.phase_id)) {
47
+ uncountedFailures.push({ view, step });
48
+ continue;
49
+ }
50
+ countedFailures.add(step);
51
+ add({
52
+ kind: "step",
53
+ id: step.step_id,
54
+ reason: classifyFailedStep(phase, step),
55
+ status: "failed",
56
+ phase_id: phase.phase_id,
57
+ ...passIndex !== void 0 && { pass_index: passIndex },
58
+ ...messageOf(step.error ?? firstFailedValidationMessage(step))
59
+ });
60
+ }
61
+ }
62
+ const assertionOwners = /* @__PURE__ */ new Set();
63
+ for (const assertion of result.assertions ?? []) {
64
+ if (assertion.passed) continue;
65
+ const owner = assertion.scope === "step" ? findOwningStep(result, phaseViews, assertion) : void 0;
66
+ if (owner) assertionOwners.add(owner);
67
+ if (owner && countedFailures.has(owner)) continue;
68
+ add({
69
+ kind: "assertion",
70
+ id: assertion.assertion_id,
71
+ reason: "assertion_failed",
72
+ status: "failed",
73
+ ...owner && { phase_id: owner.phase_id },
74
+ ...assertion.pass_index !== void 0 && { pass_index: assertion.pass_index },
75
+ ...messageOf(assertionMessage(assertion, owner))
76
+ });
77
+ }
78
+ const namedUncounted = /* @__PURE__ */ new Set();
79
+ const ungradedUncounted = [];
80
+ const uncountedRow = ({
81
+ view,
82
+ step
83
+ }) => ({
84
+ kind: "step",
85
+ id: step.step_id,
86
+ reason: "step_failed",
87
+ status: "failed",
88
+ phase_id: view.phase.phase_id,
89
+ ...view.passIndex !== void 0 && { pass_index: view.passIndex },
90
+ ...messageOf(step.error ?? firstFailedValidationMessage(step))
91
+ });
92
+ for (const failure of uncountedFailures) {
93
+ if (failure.view.phase.passed || assertionOwners.has(failure.step)) continue;
94
+ if (isOptionalPhase(failure.view.phase.phase_id) && !optionalOnly) {
95
+ ungradedUncounted.push(failure);
96
+ continue;
97
+ }
98
+ namedUncounted.add(failure.step);
99
+ add(uncountedRow(failure));
100
+ }
101
+ let requiredPhaseHasExecutedPass = false;
102
+ const vacuousSkips = [];
103
+ for (const view of phaseViews) {
104
+ const { phase, passIndex } = view;
105
+ if (isSyntheticPhase(phase.phase_id) || isOptionalPhase(phase.phase_id) && !optionalOnly) continue;
106
+ if (phase.passed) {
107
+ if (phase.steps.some((step) => !step.skipped && step.passed)) requiredPhaseHasExecutedPass = true;
108
+ for (const step of phase.steps) if (step.skipped) vacuousSkips.push({ view, step });
109
+ continue;
110
+ }
111
+ if (phase.steps.some((step) => countedFailures.has(step) || namedUncounted.has(step) || assertionOwners.has(step))) {
112
+ continue;
113
+ }
114
+ const skipped = phase.steps.filter((step) => step.skipped);
115
+ const causal = skipped.filter((step) => !NEUTRAL_SKIP_REASONS.has(detailedSkipReason(step) ?? ""));
116
+ const named = causal.length > 0 ? causal : skipped;
117
+ if (named.length === 0) {
118
+ add({
119
+ kind: "phase",
120
+ id: phase.phase_id,
121
+ reason: "required_phase_not_executed",
122
+ status: "not_passed",
123
+ phase_id: phase.phase_id,
124
+ ...passIndex !== void 0 && { pass_index: passIndex },
125
+ message: `Phase '${phase.phase_id}' did not pass`
126
+ });
127
+ continue;
128
+ }
129
+ for (const step of named) add(skippedStepContributor(phase, step, passIndex));
130
+ }
131
+ if (contributors.length === 0 && !requiredPhaseHasExecutedPass) {
132
+ const named = vacuousSkips.filter(({ step }) => !NEUTRAL_SKIP_REASONS.has(detailedSkipReason(step) ?? ""));
133
+ for (const { view, step } of named.length > 0 ? named : vacuousSkips) {
134
+ const row = skippedStepContributor(view.phase, step, view.passIndex);
135
+ add(row.reason === "required_phase_not_executed" ? { ...row, reason: "no_executed_steps" } : row);
136
+ }
137
+ if (contributors.length === 0 && !options.coverageUnverified) {
138
+ add({
139
+ kind: "phase",
140
+ id: "storyboard",
141
+ reason: "no_executed_steps",
142
+ status: "not_passed",
143
+ message: "No required step executed and passed"
144
+ });
145
+ }
146
+ }
147
+ if (options.coverageUnverified) {
148
+ const probes = phaseViews.flatMap(
149
+ ({ phase, passIndex }) => phase.steps.filter((step) => step.skipped).map((step) => ({ phase, step, passIndex }))
150
+ );
151
+ if (probes.length === 0) {
152
+ add({
153
+ kind: "phase",
154
+ id: "storyboard",
155
+ reason: "coverage_unverified",
156
+ status: "not_passed",
157
+ message: "No request-signing probe reached the agent"
158
+ });
159
+ }
160
+ for (const { phase, step, passIndex } of probes) {
161
+ add({ ...skippedStepContributor(phase, step, passIndex), reason: "coverage_unverified" });
162
+ }
163
+ }
164
+ if (contributors.length === 0) for (const failure of ungradedUncounted) add(uncountedRow(failure));
165
+ const reason = REASON_PRECEDENCE.find((candidate) => contributors.some((row) => row.reason === candidate)) ?? "unexplained";
166
+ const bounded = contributors.slice(0, MAX_CONTRIBUTORS);
167
+ return {
168
+ verdict_reason: reason,
169
+ verdict_detail: buildDetail(reason, contributors),
170
+ verdict_contributing: bounded
171
+ };
172
+ }
173
+ function applyStoryboardVerdictExplanation(result, options = {}) {
174
+ delete result.verdict_reason;
175
+ delete result.verdict_detail;
176
+ delete result.verdict_contributing;
177
+ const explanation = explainStoryboardVerdict(result, options);
178
+ if (explanation) Object.assign(result, explanation);
179
+ return result;
180
+ }
181
+ function classifyFailedStep(phase, step) {
182
+ if (step.validations.some((validation) => !validation.passed && RUNNER_ERROR_CHECKS.has(validation.check))) {
183
+ return "runner_error";
184
+ }
185
+ if (phase.phase_id === CONTROLLER_SEEDING_PHASE_ID) return "controller_prerequisite_unmet";
186
+ if (FIXTURE_PHASE_IDS.has(phase.phase_id)) return "fixture_error";
187
+ return "step_failed";
188
+ }
189
+ function skippedStepContributor(phase, step, passIndex) {
190
+ const skipReason = detailedSkipReason(step);
191
+ const requirement = step.skip?.requirement;
192
+ const controllerGap = skipReason !== void 0 && CONTROLLER_SKIP_REASONS.has(skipReason) || requirement !== void 0 && CONTROLLER_REQUIREMENTS.has(requirement);
193
+ return {
194
+ kind: "step",
195
+ id: step.step_id,
196
+ reason: controllerGap ? "controller_prerequisite_unmet" : "required_phase_not_executed",
197
+ status: "skipped",
198
+ phase_id: phase.phase_id,
199
+ ...passIndex !== void 0 && { pass_index: passIndex },
200
+ ...skipReason !== void 0 && { skip_reason: skipReason },
201
+ ...requirement !== void 0 && { requirement },
202
+ ...messageOf(step.skip?.detail)
203
+ };
204
+ }
205
+ function detailedSkipReason(step) {
206
+ return step.skip_reason ?? step.skip?.reason;
207
+ }
208
+ function isSyntheticPhase(phaseId) {
209
+ return phaseId === CONTROLLER_SEEDING_PHASE_ID || FIXTURE_PHASE_IDS.has(phaseId);
210
+ }
211
+ function findOwningStep(result, phaseViews, assertion) {
212
+ const phases = assertion.pass_index === void 0 ? result.phases : phaseViews.filter((view) => view.passIndex === assertion.pass_index).map((view) => view.phase);
213
+ for (const phase of phases) {
214
+ const step = phase.steps.find((candidate) => candidate.step_id === assertion.step_id);
215
+ if (step) return step;
216
+ }
217
+ return void 0;
218
+ }
219
+ function assertionMessage(assertion, owner) {
220
+ const base = assertion.error ?? assertion.description;
221
+ if (owner?.skipped) return `${base} (on skipped step '${owner.step_id}')`;
222
+ return base;
223
+ }
224
+ function firstFailedValidationMessage(step) {
225
+ const failed = step.validations.find((validation) => !validation.passed);
226
+ if (!failed) return void 0;
227
+ return failed.error ? `${failed.description}: ${failed.error}` : failed.description;
228
+ }
229
+ function messageOf(text) {
230
+ if (typeof text !== "string") return {};
231
+ const trimmed = text.replace(/\s+/g, " ").trim();
232
+ if (trimmed.length === 0) return {};
233
+ return { message: truncate(trimmed, MAX_MESSAGE_LENGTH) };
234
+ }
235
+ function truncate(text, max) {
236
+ return text.length <= max ? text : `${text.slice(0, max - 1)}\u2026`;
237
+ }
238
+ const REASON_LEADS = {
239
+ step_failed: "A step failed",
240
+ assertion_failed: "A storyboard-level assertion failed",
241
+ controller_prerequisite_unmet: "Required steps did not run because comply_test_controller or its seeding was unavailable",
242
+ required_phase_not_executed: "A required phase did not run",
243
+ no_executed_steps: "No required step executed and passed, so the run proves nothing",
244
+ fixture_error: "Fixture resolution or preparation failed before the behavior under test could run",
245
+ coverage_unverified: "No request-signing probe reached the agent, so signing coverage is unverified",
246
+ runner_error: "The runner or host could not proceed; this is not an agent failure",
247
+ unexplained: "The runner could not attribute this verdict; please report it as a runner bug"
248
+ };
249
+ function buildDetail(reason, contributors) {
250
+ const primary = contributors.filter((row) => row.reason === reason);
251
+ const parts = [REASON_LEADS[reason]];
252
+ const described = primary.slice(0, 3).map(describeContributor);
253
+ if (described.length > 0) parts[0] += `: ${described.join("; ")}`;
254
+ if (primary.length > described.length) parts[0] += ` (+${primary.length - described.length} more)`;
255
+ const others = REASON_PRECEDENCE.filter(
256
+ (candidate) => candidate !== reason && contributors.some((row) => row.reason === candidate)
257
+ );
258
+ if (others.length > 0) parts.push(`Also: ${others.join(", ")}`);
259
+ if (contributors.length > MAX_CONTRIBUTORS) {
260
+ parts.push(`${contributors.length - MAX_CONTRIBUTORS} contributor(s) omitted`);
261
+ }
262
+ return truncate(`${parts.map(stripTrailingPeriods).join(". ")}.`, MAX_DETAIL_LENGTH);
263
+ }
264
+ function stripTrailingPeriods(text) {
265
+ let out = text.trimEnd();
266
+ while (out.endsWith(".")) out = out.slice(0, -1).trimEnd();
267
+ return out;
268
+ }
269
+ function describeContributor(row) {
270
+ const where = row.pass_index !== void 0 ? ` (pass ${row.pass_index})` : "";
271
+ if (row.kind === "assertion") return `${row.id}${where}${row.message ? ` \u2014 ${row.message}` : ""}`;
272
+ if (row.status === "skipped") {
273
+ const why = row.requirement ? `${row.skip_reason ?? "skipped"}: ${row.requirement}` : row.skip_reason ?? "skipped";
274
+ return `${row.id}${where} skipped (${why})`;
275
+ }
276
+ if (row.status === "failed") return `${row.id}${where} failed`;
277
+ return `${row.id}${where}${row.message ? ` \u2014 ${row.message}` : ""}`;
278
+ }
279
+ export {
280
+ CONTROLLER_SEEDING_PHASE_ID,
281
+ applyStoryboardVerdictExplanation,
282
+ explainStoryboardVerdict
283
+ };
@@ -5,7 +5,7 @@ import type { FormatReferenceStructuredObject as FormatID } from '../types/core.
5
5
  import type { AdcpVersion } from '../version.mjs';
6
6
  import type { TransportOptions, VersionEnvelopeMode } from '../protocols/index.mjs';
7
7
  import type { AgentRequestSigningConfig } from '../types/adcp.mjs';
8
- import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord } from './storyboard/types.mjs';
8
+ import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord, StoryboardVerdictContributor, StoryboardVerdictReason } from './storyboard/types.mjs';
9
9
  import type { AuthorizationRequirements } from '../auth/oauth/authorization-required.mjs';
10
10
  export type TestScenario = 'health_check' | 'discovery' | 'create_media_buy' | 'full_sales_flow' | 'reporting_flow' | 'creative_sync' | 'creative_inline' | 'creative_reference' | 'pricing_models' | 'creative_flow' | 'creative_lifecycle' | 'signals_flow' | 'error_handling' | 'validation' | 'pricing_edge_cases' | 'temporal_validation' | 'behavior_analysis' | 'response_consistency' | 'governance_property_lists' | 'governance_content_standards' | 'property_list_filters' | 'campaign_governance' | 'campaign_governance_denied' | 'campaign_governance_conditions' | 'campaign_governance_delivery' | 'seller_governance_context' | 'si_session_lifecycle' | 'si_availability' | 'si_handoff' | 'capability_discovery' | 'schema_compliance' | 'sync_audiences' | 'media_buy_lifecycle' | 'terminal_state_enforcement' | 'package_lifecycle' | 'error_codes' | 'error_structure' | 'error_transport' | 'deterministic_creative' | 'deterministic_media_buy' | 'deterministic_account' | 'deterministic_session' | 'deterministic_delivery' | 'deterministic_budget' | 'controller_validation' | 'brand_identity' | 'brand_rights_flow' | 'creative_approval';
11
11
  export interface TestOptions {
@@ -399,6 +399,16 @@ export interface TestResult {
399
399
  total_duration_ms: number;
400
400
  tested_at: string;
401
401
  agent_profile?: AgentProfile;
402
+ /**
403
+ * Storyboard-level verdict explanation (adcp#8576). Set only on the
404
+ * synthetic `<storyboard_id>/storyboard` scenario that `comply()` emits
405
+ * when a storyboard fails without a counted failed step. Mirrors
406
+ * `StoryboardResult.verdict_reason` / `verdict_detail` /
407
+ * `verdict_contributing`.
408
+ */
409
+ verdict_reason?: StoryboardVerdictReason;
410
+ verdict_detail?: string;
411
+ verdict_contributing?: StoryboardVerdictContributor[];
402
412
  }
403
413
  export interface SuiteResult {
404
414
  agent_url: string;
@@ -5,7 +5,7 @@ import type { FormatReferenceStructuredObject as FormatID } from '../types/core.
5
5
  import type { AdcpVersion } from '../version';
6
6
  import type { TransportOptions, VersionEnvelopeMode } from '../protocols';
7
7
  import type { AgentRequestSigningConfig } from '../types/adcp';
8
- import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord } from './storyboard/types';
8
+ import type { RunnerRequestRecord, RunnerResponseRecord, RunnerExtractionRecord, StoryboardVerdictContributor, StoryboardVerdictReason } from './storyboard/types';
9
9
  import type { AuthorizationRequirements } from '../auth/oauth/authorization-required';
10
10
  export type TestScenario = 'health_check' | 'discovery' | 'create_media_buy' | 'full_sales_flow' | 'reporting_flow' | 'creative_sync' | 'creative_inline' | 'creative_reference' | 'pricing_models' | 'creative_flow' | 'creative_lifecycle' | 'signals_flow' | 'error_handling' | 'validation' | 'pricing_edge_cases' | 'temporal_validation' | 'behavior_analysis' | 'response_consistency' | 'governance_property_lists' | 'governance_content_standards' | 'property_list_filters' | 'campaign_governance' | 'campaign_governance_denied' | 'campaign_governance_conditions' | 'campaign_governance_delivery' | 'seller_governance_context' | 'si_session_lifecycle' | 'si_availability' | 'si_handoff' | 'capability_discovery' | 'schema_compliance' | 'sync_audiences' | 'media_buy_lifecycle' | 'terminal_state_enforcement' | 'package_lifecycle' | 'error_codes' | 'error_structure' | 'error_transport' | 'deterministic_creative' | 'deterministic_media_buy' | 'deterministic_account' | 'deterministic_session' | 'deterministic_delivery' | 'deterministic_budget' | 'controller_validation' | 'brand_identity' | 'brand_rights_flow' | 'creative_approval';
11
11
  export interface TestOptions {
@@ -399,6 +399,16 @@ export interface TestResult {
399
399
  total_duration_ms: number;
400
400
  tested_at: string;
401
401
  agent_profile?: AgentProfile;
402
+ /**
403
+ * Storyboard-level verdict explanation (adcp#8576). Set only on the
404
+ * synthetic `<storyboard_id>/storyboard` scenario that `comply()` emits
405
+ * when a storyboard fails without a counted failed step. Mirrors
406
+ * `StoryboardResult.verdict_reason` / `verdict_detail` /
407
+ * `verdict_contributing`.
408
+ */
409
+ verdict_reason?: StoryboardVerdictReason;
410
+ verdict_detail?: string;
411
+ verdict_contributing?: StoryboardVerdictContributor[];
402
412
  }
403
413
  export interface SuiteResult {
404
414
  agent_url: string;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.27";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.28";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.27";
36
+ readonly library: "17.0.0-beta.28";
37
37
  readonly adcp: "3.3.0-beta.6";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.6", "3.3-beta.6"];
39
- readonly generatedAt: "2026-11-14T21:58:26.439Z";
39
+ readonly generatedAt: "2026-11-15T14:00:59.479Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.27";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.28";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.27";
36
+ readonly library: "17.0.0-beta.28";
37
37
  readonly adcp: "3.3.0-beta.6";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.6", "3.3-beta.6"];
39
- readonly generatedAt: "2026-11-14T21:58:26.439Z";
39
+ readonly generatedAt: "2026-11-15T14:00:59.479Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -31,7 +31,7 @@ __export(version_exports, {
31
31
  toReleasePrecisionVersion: () => toReleasePrecisionVersion
32
32
  });
33
33
  module.exports = __toCommonJS(version_exports);
34
- const LIBRARY_VERSION = "17.0.0-beta.27";
34
+ const LIBRARY_VERSION = "17.0.0-beta.28";
35
35
  const ADCP_VERSION = "3.3.0-beta.6";
36
36
  const ADCP_MAJOR_VERSION = 3;
37
37
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -109,10 +109,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
109
109
  "3.3-beta.6"
110
110
  ];
111
111
  const VERSION_INFO = {
112
- library: "17.0.0-beta.27",
112
+ library: "17.0.0-beta.28",
113
113
  adcp: "3.3.0-beta.6",
114
114
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
115
- generatedAt: "2026-11-14T21:58:26.439Z"
115
+ generatedAt: "2026-11-15T14:00:59.479Z"
116
116
  };
117
117
  function getAdcpVersion() {
118
118
  return ADCP_VERSION;
@@ -1,4 +1,4 @@
1
- const LIBRARY_VERSION = "17.0.0-beta.27";
1
+ const LIBRARY_VERSION = "17.0.0-beta.28";
2
2
  const ADCP_VERSION = "3.3.0-beta.6";
3
3
  const ADCP_MAJOR_VERSION = 3;
4
4
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -76,10 +76,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
76
76
  "3.3-beta.6"
77
77
  ];
78
78
  const VERSION_INFO = {
79
- library: "17.0.0-beta.27",
79
+ library: "17.0.0-beta.28",
80
80
  adcp: "3.3.0-beta.6",
81
81
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
82
- generatedAt: "2026-11-14T21:58:26.439Z"
82
+ generatedAt: "2026-11-15T14:00:59.479Z"
83
83
  };
84
84
  function getAdcpVersion() {
85
85
  return ADCP_VERSION;
@@ -1,7 +1,7 @@
1
1
  # AdCP Type Summary
2
2
 
3
- > Generated at: 2026-11-14
4
- > @adcp/sdk v17.0.0-beta.27
3
+ > Generated at: 2026-11-15
4
+ > @adcp/sdk v17.0.0-beta.28
5
5
 
6
6
  Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
7
7
 
@@ -161,6 +161,34 @@ All `expect_webhook*` steps require `webhook_receiver` runner support. If the
161
161
  `triggered_by` step is missing, skipped, or failed, the assertion skips with
162
162
  `prerequisite_failed` instead of treating the absence as a passing result.
163
163
 
164
+ ### Why a storyboard failed when no step did
165
+
166
+ A storyboard's verdict (`overall_passed`) can be `false` while every step you
167
+ can see passed or was skipped. Every failing result says why:
168
+
169
+ | Field | Where | Meaning |
170
+ |---|---|---|
171
+ | `verdict_reason` | `StoryboardResult` (`storyboard run --json`), the `<storyboard_id>/storyboard` scenario in `tracks[].scenarios[]` | Primary cause, one of the codes below. Absent on a passing result. |
172
+ | `verdict_detail` | same | One line of runner-authored text. It names failed steps without quoting their errors. |
173
+ | `verdict_contributing[]` | same | Every step, assertion, phase or requirement behind the verdict: `kind`, `id`, `reason`, `status` (`failed` / `skipped` / `not_passed`), and where known `phase_id`, `pass_index`, `skip_reason`, `requirement`, `message`. At most 20 rows. |
174
+ | `verdict_explanations[]` | `ComplianceResult` (full assessment `--json`) | One entry per failing storyboard, with the fields above, `storyboard_level: true` when no `failures[]` row explains it, and a `fix_command` that re-runs the storyboard. |
175
+
176
+ | `verdict_reason` | What happened | What to do |
177
+ |---|---|---|
178
+ | `step_failed` | A step failed. Usually a counted failure; on a storyboard with only optional phases, a failed optional step. | Read that step's `error` and `validations`. |
179
+ | `assertion_failed` | A storyboard-level invariant (for example `status.monotonic`) failed, or an assertion failed on a skipped step. | Read the assertion row's `message`. |
180
+ | `controller_prerequisite_unmet` | Required steps needed `comply_test_controller` or its pre-flight seeding, and it was absent or seeding failed. | Implement the controller scenarios the storyboard names, or fix the seeding error. |
181
+ | `required_phase_not_executed` | A required phase did not pass because its steps were skipped (`prerequisite_failed`, `missing_tool`, `unsatisfied_contract`, `requirement_unmet`, a capability gate). | Follow each row's `skip_reason`. |
182
+ | `no_executed_steps` | Nothing failed, but no required step executed and passed. | Advertise the tools the storyboard needs. |
183
+ | `fixture_error` | Fixture resolution or preparation failed before the behavior under test ran. | Fix the fixture or test kit. |
184
+ | `coverage_unverified` | A request-signing storyboard never reached the agent. | Use a transport the vectors can frame. |
185
+ | `runner_error` | The runner or host refused to proceed. Not an agent failure. | Report it to whoever runs the grader. |
186
+ | `unexplained` | The runner could not attribute the verdict. | Report it as a runner bug. |
187
+
188
+ The fields explain the verdict. They never change `overall_passed`, the counts,
189
+ or any track or bundle grade. The human output of `adcp storyboard run` prints
190
+ the same reason under the summary line (`Why: [...]`).
191
+
164
192
  ### Running against pre-publish artifacts
165
193
 
166
194
  Use a matching compliance bundle and schema root to validate a protocol build
package/docs/llms.txt CHANGED
@@ -1,7 +1,7 @@
1
1
  # Ad Context Protocol (AdCP)
2
2
 
3
- > Generated at: 2026-11-14
4
- > Library: @adcp/sdk v17.0.0-beta.27
3
+ > Generated at: 2026-11-15
4
+ > Library: @adcp/sdk v17.0.0-beta.28
5
5
  > AdCP major version: 3
6
6
  > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
7
7
  > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
16
16
 
17
17
  | Fact | Value |
18
18
  | --- | --- |
19
- | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.27` |
20
- | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.27 dist.integrity` |
19
+ | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.28` |
20
+ | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.28 dist.integrity` |
21
21
  | Node.js runtime | `^20.19.0 || >=22.12.0` |
22
22
  | Default AdCP wire release | `3.3.0-beta.6` |
23
23
  | Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.1.30`, `3.1.31`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.2.8`, `3.3.0-beta.6`, `3.3-beta.6` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
26
26
  For a checkout at the published release commit, install the exact package version:
27
27
 
28
28
  ```bash
29
- npm install --save-exact '@adcp/sdk@17.0.0-beta.27'
30
- npm view '@adcp/sdk@17.0.0-beta.27' dist.integrity
29
+ npm install --save-exact '@adcp/sdk@17.0.0-beta.28'
30
+ npm view '@adcp/sdk@17.0.0-beta.28' dist.integrity
31
31
  ```
32
32
 
33
33
  ### Required and optional peers
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adcp/sdk",
3
- "version": "17.0.0-beta.27",
3
+ "version": "17.0.0-beta.28",
4
4
  "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
5
5
  "workspaces": [
6
6
  ".",