@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
@@ -3395,6 +3395,83 @@ export interface StoryboardResult {
3395
3395
  url: string;
3396
3396
  error: string;
3397
3397
  }>;
3398
+ /**
3399
+ * Why `overall_passed` is false (adcp#8576). Present only on a failing
3400
+ * result; absent on a passing one. A storyboard can fail without any
3401
+ * visible failed step: a storyboard-scoped invariant broke, a required
3402
+ * phase never executed (`missing_test_controller`, `prerequisite_failed`,
3403
+ * a capability gate), controller seeding could not run, or the runner
3404
+ * itself could not proceed. This code names the primary cause; the
3405
+ * `verdict_contributing` rows name every cause the runner found.
3406
+ *
3407
+ * Explanatory only. It never changes `overall_passed`, the counts, or any
3408
+ * track or bundle grade.
3409
+ */
3410
+ verdict_reason?: StoryboardVerdictReason;
3411
+ /**
3412
+ * One-line human-readable explanation of `verdict_reason`, bounded to 600
3413
+ * characters. Runner-authored: it names failed steps without quoting their
3414
+ * errors, but quotes skip details and assertion errors, which can echo
3415
+ * observed values.
3416
+ */
3417
+ verdict_detail?: string;
3418
+ /**
3419
+ * The steps, assertions, phases and requirements behind the verdict, in
3420
+ * the order the runner found them. Bounded; `verdict_detail` says when
3421
+ * rows were omitted.
3422
+ */
3423
+ verdict_contributing?: StoryboardVerdictContributor[];
3424
+ }
3425
+ /**
3426
+ * Primary cause of a failing storyboard verdict. See
3427
+ * `StoryboardResult.verdict_reason`.
3428
+ *
3429
+ * - `step_failed` — a step failed and its failure is visible on the step. Usually
3430
+ * a counted failure; on a storyboard with no required phase it can be a
3431
+ * failed optional step that `failed_count` does not include.
3432
+ * - `assertion_failed` — a storyboard-scoped invariant failed, or an
3433
+ * assertion failed on a step that was skipped, so no counted step carries it.
3434
+ * - `controller_prerequisite_unmet` — the storyboard needed
3435
+ * `comply_test_controller` or controller seeding, and it was absent or
3436
+ * seeding failed, so required steps never ran.
3437
+ * - `required_phase_not_executed` — a required phase did not pass because its
3438
+ * steps were skipped (`prerequisite_failed`, `missing_tool`,
3439
+ * `unsatisfied_contract`, `requirement_unmet`, a capability gate, …).
3440
+ * - `no_executed_steps` — no required phase failed, but none executed a
3441
+ * passing step either, so the run proves nothing and cannot pass.
3442
+ * - `fixture_error` — fixture resolution or preparation failed before the
3443
+ * seller behavior under test could run.
3444
+ * - `coverage_unverified` — the storyboard exists to verify coverage (request
3445
+ * signing) and no probe reached the agent.
3446
+ * - `runner_error` — the runner or host could not proceed (for example a
3447
+ * prepared-fixture authorization refusal). Not an agent failure.
3448
+ * - `unexplained` — the runner could not attribute the verdict. Report it as
3449
+ * a runner bug.
3450
+ */
3451
+ export type StoryboardVerdictReason = 'step_failed' | 'assertion_failed' | 'controller_prerequisite_unmet' | 'required_phase_not_executed' | 'no_executed_steps' | 'fixture_error' | 'coverage_unverified' | 'runner_error' | 'unexplained';
3452
+ /** One cause behind a failing storyboard verdict. */
3453
+ export interface StoryboardVerdictContributor {
3454
+ /** What contributed: a step, an assertion or invariant, a phase, or an unmet requirement. */
3455
+ kind: 'step' | 'assertion' | 'phase' | 'requirement';
3456
+ /** Step id, assertion id, phase id, or requirement name. */
3457
+ id: string;
3458
+ /** The cause this row supports. */
3459
+ reason: StoryboardVerdictReason;
3460
+ /** `failed` for an executed failure, `skipped` for an unexecuted step, `not_passed` for a phase. */
3461
+ status: 'failed' | 'skipped' | 'not_passed';
3462
+ phase_id?: string;
3463
+ /** 1-based pass index in multi-pass mode. */
3464
+ pass_index?: number;
3465
+ /** Detailed runner skip reason, when `status === 'skipped'`. */
3466
+ skip_reason?: string;
3467
+ /** Unmet requirement named by the skip, when any. */
3468
+ requirement?: string;
3469
+ /**
3470
+ * Bounded message: the skip detail, assertion error, or step error. A
3471
+ * failed step's error can quote the agent's response, so treat it as
3472
+ * untrusted text when templating it into prompts or HTML.
3473
+ */
3474
+ message?: string;
3398
3475
  }
3399
3476
  export interface StrictValidationSummary {
3400
3477
  /**
@@ -3395,6 +3395,83 @@ export interface StoryboardResult {
3395
3395
  url: string;
3396
3396
  error: string;
3397
3397
  }>;
3398
+ /**
3399
+ * Why `overall_passed` is false (adcp#8576). Present only on a failing
3400
+ * result; absent on a passing one. A storyboard can fail without any
3401
+ * visible failed step: a storyboard-scoped invariant broke, a required
3402
+ * phase never executed (`missing_test_controller`, `prerequisite_failed`,
3403
+ * a capability gate), controller seeding could not run, or the runner
3404
+ * itself could not proceed. This code names the primary cause; the
3405
+ * `verdict_contributing` rows name every cause the runner found.
3406
+ *
3407
+ * Explanatory only. It never changes `overall_passed`, the counts, or any
3408
+ * track or bundle grade.
3409
+ */
3410
+ verdict_reason?: StoryboardVerdictReason;
3411
+ /**
3412
+ * One-line human-readable explanation of `verdict_reason`, bounded to 600
3413
+ * characters. Runner-authored: it names failed steps without quoting their
3414
+ * errors, but quotes skip details and assertion errors, which can echo
3415
+ * observed values.
3416
+ */
3417
+ verdict_detail?: string;
3418
+ /**
3419
+ * The steps, assertions, phases and requirements behind the verdict, in
3420
+ * the order the runner found them. Bounded; `verdict_detail` says when
3421
+ * rows were omitted.
3422
+ */
3423
+ verdict_contributing?: StoryboardVerdictContributor[];
3424
+ }
3425
+ /**
3426
+ * Primary cause of a failing storyboard verdict. See
3427
+ * `StoryboardResult.verdict_reason`.
3428
+ *
3429
+ * - `step_failed` — a step failed and its failure is visible on the step. Usually
3430
+ * a counted failure; on a storyboard with no required phase it can be a
3431
+ * failed optional step that `failed_count` does not include.
3432
+ * - `assertion_failed` — a storyboard-scoped invariant failed, or an
3433
+ * assertion failed on a step that was skipped, so no counted step carries it.
3434
+ * - `controller_prerequisite_unmet` — the storyboard needed
3435
+ * `comply_test_controller` or controller seeding, and it was absent or
3436
+ * seeding failed, so required steps never ran.
3437
+ * - `required_phase_not_executed` — a required phase did not pass because its
3438
+ * steps were skipped (`prerequisite_failed`, `missing_tool`,
3439
+ * `unsatisfied_contract`, `requirement_unmet`, a capability gate, …).
3440
+ * - `no_executed_steps` — no required phase failed, but none executed a
3441
+ * passing step either, so the run proves nothing and cannot pass.
3442
+ * - `fixture_error` — fixture resolution or preparation failed before the
3443
+ * seller behavior under test could run.
3444
+ * - `coverage_unverified` — the storyboard exists to verify coverage (request
3445
+ * signing) and no probe reached the agent.
3446
+ * - `runner_error` — the runner or host could not proceed (for example a
3447
+ * prepared-fixture authorization refusal). Not an agent failure.
3448
+ * - `unexplained` — the runner could not attribute the verdict. Report it as
3449
+ * a runner bug.
3450
+ */
3451
+ export type StoryboardVerdictReason = 'step_failed' | 'assertion_failed' | 'controller_prerequisite_unmet' | 'required_phase_not_executed' | 'no_executed_steps' | 'fixture_error' | 'coverage_unverified' | 'runner_error' | 'unexplained';
3452
+ /** One cause behind a failing storyboard verdict. */
3453
+ export interface StoryboardVerdictContributor {
3454
+ /** What contributed: a step, an assertion or invariant, a phase, or an unmet requirement. */
3455
+ kind: 'step' | 'assertion' | 'phase' | 'requirement';
3456
+ /** Step id, assertion id, phase id, or requirement name. */
3457
+ id: string;
3458
+ /** The cause this row supports. */
3459
+ reason: StoryboardVerdictReason;
3460
+ /** `failed` for an executed failure, `skipped` for an unexecuted step, `not_passed` for a phase. */
3461
+ status: 'failed' | 'skipped' | 'not_passed';
3462
+ phase_id?: string;
3463
+ /** 1-based pass index in multi-pass mode. */
3464
+ pass_index?: number;
3465
+ /** Detailed runner skip reason, when `status === 'skipped'`. */
3466
+ skip_reason?: string;
3467
+ /** Unmet requirement named by the skip, when any. */
3468
+ requirement?: string;
3469
+ /**
3470
+ * Bounded message: the skip detail, assertion error, or step error. A
3471
+ * failed step's error can quote the agent's response, so treat it as
3472
+ * untrusted text when templating it into prompts or HTML.
3473
+ */
3474
+ message?: string;
3398
3475
  }
3399
3476
  export interface StrictValidationSummary {
3400
3477
  /**
@@ -200,7 +200,7 @@ export interface UpstreamTrafficQueryResult {
200
200
  */
201
201
  export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
202
202
  /** Capability semver emitted in run summaries and used for advisory expiry. */
203
- export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.27";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.28";
204
204
  /** True when a failed validation contributes to the owning step's grade. */
205
205
  export declare function validationFailsStep(result: ValidationResult): boolean;
206
206
  /**
@@ -200,7 +200,7 @@ export interface UpstreamTrafficQueryResult {
200
200
  */
201
201
  export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
202
202
  /** Capability semver emitted in run summaries and used for advisory expiry. */
203
- export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.27";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.28";
204
204
  /** True when a failed validation contributes to the owning step's grade. */
205
205
  export declare function validationFailsStep(result: ValidationResult): boolean;
206
206
  /**
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Explains a failing storyboard verdict (adcp#8576).
3
+ *
4
+ * `overall_passed` can be false while every visible step passed: a
5
+ * storyboard-scoped invariant broke, a required phase never executed, the
6
+ * controller seeding it needed never ran, or the runner itself could not
7
+ * proceed. Consumers then saw a bare "storyboard-level verdict failed". This
8
+ * module reads the finished result and names the cause as structured fields
9
+ * (`verdict_reason`, `verdict_detail`, `verdict_contributing`).
10
+ *
11
+ * It is a pure function of the result. It never changes the verdict, the
12
+ * counts, or any track or bundle grade. The runner calls it on every result
13
+ * it returns; consumers holding a result from an older runner can call it
14
+ * themselves.
15
+ */
16
+ import type { Storyboard, StoryboardResult, StoryboardVerdictContributor, StoryboardVerdictReason } from './types.mjs';
17
+ export interface StoryboardVerdictExplanation {
18
+ verdict_reason: StoryboardVerdictReason;
19
+ verdict_detail: string;
20
+ verdict_contributing: StoryboardVerdictContributor[];
21
+ }
22
+ export interface ExplainStoryboardVerdictOptions {
23
+ /**
24
+ * The storyboard definition, when available. Used to tell required phases
25
+ * from optional ones; without it every phase that did not pass is treated
26
+ * as required.
27
+ */
28
+ storyboard?: Pick<Storyboard, 'phases'>;
29
+ /**
30
+ * The runner's coverage verdict for request-signing storyboards. The
31
+ * runner decides it (`signingCoverageUnverified`); this module only
32
+ * reports it.
33
+ */
34
+ coverageUnverified?: boolean;
35
+ }
36
+ /** Synthetic phase the runner prepends for pre-flight `comply_test_controller` seeding. */
37
+ export declare const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
38
+ /**
39
+ * Explain why `result.overall_passed` is false. Returns `undefined` for a
40
+ * passing result.
41
+ */
42
+ export declare function explainStoryboardVerdict(result: StoryboardResult, options?: ExplainStoryboardVerdictOptions): StoryboardVerdictExplanation | undefined;
43
+ /**
44
+ * Return `result` with the verdict explanation fields set when it fails and
45
+ * removed when it passes. Mutates and returns the same object.
46
+ */
47
+ export declare function applyStoryboardVerdictExplanation<T extends StoryboardResult>(result: T, options?: ExplainStoryboardVerdictOptions): T;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Explains a failing storyboard verdict (adcp#8576).
3
+ *
4
+ * `overall_passed` can be false while every visible step passed: a
5
+ * storyboard-scoped invariant broke, a required phase never executed, the
6
+ * controller seeding it needed never ran, or the runner itself could not
7
+ * proceed. Consumers then saw a bare "storyboard-level verdict failed". This
8
+ * module reads the finished result and names the cause as structured fields
9
+ * (`verdict_reason`, `verdict_detail`, `verdict_contributing`).
10
+ *
11
+ * It is a pure function of the result. It never changes the verdict, the
12
+ * counts, or any track or bundle grade. The runner calls it on every result
13
+ * it returns; consumers holding a result from an older runner can call it
14
+ * themselves.
15
+ */
16
+ import type { Storyboard, StoryboardResult, StoryboardVerdictContributor, StoryboardVerdictReason } from './types';
17
+ export interface StoryboardVerdictExplanation {
18
+ verdict_reason: StoryboardVerdictReason;
19
+ verdict_detail: string;
20
+ verdict_contributing: StoryboardVerdictContributor[];
21
+ }
22
+ export interface ExplainStoryboardVerdictOptions {
23
+ /**
24
+ * The storyboard definition, when available. Used to tell required phases
25
+ * from optional ones; without it every phase that did not pass is treated
26
+ * as required.
27
+ */
28
+ storyboard?: Pick<Storyboard, 'phases'>;
29
+ /**
30
+ * The runner's coverage verdict for request-signing storyboards. The
31
+ * runner decides it (`signingCoverageUnverified`); this module only
32
+ * reports it.
33
+ */
34
+ coverageUnverified?: boolean;
35
+ }
36
+ /** Synthetic phase the runner prepends for pre-flight `comply_test_controller` seeding. */
37
+ export declare const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
38
+ /**
39
+ * Explain why `result.overall_passed` is false. Returns `undefined` for a
40
+ * passing result.
41
+ */
42
+ export declare function explainStoryboardVerdict(result: StoryboardResult, options?: ExplainStoryboardVerdictOptions): StoryboardVerdictExplanation | undefined;
43
+ /**
44
+ * Return `result` with the verdict explanation fields set when it fails and
45
+ * removed when it passes. Mutates and returns the same object.
46
+ */
47
+ export declare function applyStoryboardVerdictExplanation<T extends StoryboardResult>(result: T, options?: ExplainStoryboardVerdictOptions): T;
@@ -0,0 +1,309 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+ var verdict_explanation_exports = {};
20
+ __export(verdict_explanation_exports, {
21
+ CONTROLLER_SEEDING_PHASE_ID: () => CONTROLLER_SEEDING_PHASE_ID,
22
+ applyStoryboardVerdictExplanation: () => applyStoryboardVerdictExplanation,
23
+ explainStoryboardVerdict: () => explainStoryboardVerdict
24
+ });
25
+ module.exports = __toCommonJS(verdict_explanation_exports);
26
+ const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
27
+ const FIXTURE_PHASE_IDS = /* @__PURE__ */ new Set(["fixture_resolution", "prepared_fixtures_preparation_failed"]);
28
+ const RUNNER_ERROR_CHECKS = /* @__PURE__ */ new Set(["prepared_fixtures_authorization"]);
29
+ const CONTROLLER_SKIP_REASONS = /* @__PURE__ */ new Set(["missing_test_controller", "controller_seeding_failed"]);
30
+ const CONTROLLER_REQUIREMENTS = /* @__PURE__ */ new Set(["controller", "seeded_state"]);
31
+ const NEUTRAL_SKIP_REASONS = /* @__PURE__ */ new Set([
32
+ "not_applicable",
33
+ "peer_branch_taken",
34
+ "peer_substituted",
35
+ "missing_test_kit_contract",
36
+ "fixture_unavailable",
37
+ "fixture_unsatisfied",
38
+ "fixture_seed_unsupported",
39
+ "capability_unsupported"
40
+ ]);
41
+ const REASON_PRECEDENCE = [
42
+ "runner_error",
43
+ "step_failed",
44
+ "fixture_error",
45
+ "assertion_failed",
46
+ "controller_prerequisite_unmet",
47
+ "required_phase_not_executed",
48
+ "no_executed_steps",
49
+ "coverage_unverified"
50
+ ];
51
+ const MAX_CONTRIBUTORS = 20;
52
+ const MAX_MESSAGE_LENGTH = 300;
53
+ const MAX_DETAIL_LENGTH = 600;
54
+ function explainStoryboardVerdict(result, options = {}) {
55
+ if (result.overall_passed) return void 0;
56
+ const knownPhases = options.storyboard?.phases ?? [];
57
+ const optionalPhaseIds = new Set(knownPhases.filter((phase) => phase.optional === true).map((phase) => phase.id));
58
+ const optionalOnly = knownPhases.length > 0 && knownPhases.every((phase) => phase.optional === true);
59
+ const isOptionalPhase = (phaseId) => optionalPhaseIds.has(phaseId);
60
+ const phaseViews = result.passes?.length ? result.passes.flatMap((pass) => pass.phases.map((phase) => ({ phase, passIndex: pass.pass_index }))) : result.phases.map((phase) => ({ phase }));
61
+ const contributors = [];
62
+ const add = (row) => {
63
+ contributors.push(row);
64
+ };
65
+ const countedFailures = /* @__PURE__ */ new Set();
66
+ const uncountedFailures = [];
67
+ for (const view of phaseViews) {
68
+ const { phase, passIndex } = view;
69
+ for (const step of phase.steps) {
70
+ if (step.passed || step.skipped) continue;
71
+ if (step.counts_toward_failure === false || isOptionalPhase(phase.phase_id)) {
72
+ uncountedFailures.push({ view, step });
73
+ continue;
74
+ }
75
+ countedFailures.add(step);
76
+ add({
77
+ kind: "step",
78
+ id: step.step_id,
79
+ reason: classifyFailedStep(phase, step),
80
+ status: "failed",
81
+ phase_id: phase.phase_id,
82
+ ...passIndex !== void 0 && { pass_index: passIndex },
83
+ ...messageOf(step.error ?? firstFailedValidationMessage(step))
84
+ });
85
+ }
86
+ }
87
+ const assertionOwners = /* @__PURE__ */ new Set();
88
+ for (const assertion of result.assertions ?? []) {
89
+ if (assertion.passed) continue;
90
+ const owner = assertion.scope === "step" ? findOwningStep(result, phaseViews, assertion) : void 0;
91
+ if (owner) assertionOwners.add(owner);
92
+ if (owner && countedFailures.has(owner)) continue;
93
+ add({
94
+ kind: "assertion",
95
+ id: assertion.assertion_id,
96
+ reason: "assertion_failed",
97
+ status: "failed",
98
+ ...owner && { phase_id: owner.phase_id },
99
+ ...assertion.pass_index !== void 0 && { pass_index: assertion.pass_index },
100
+ ...messageOf(assertionMessage(assertion, owner))
101
+ });
102
+ }
103
+ const namedUncounted = /* @__PURE__ */ new Set();
104
+ const ungradedUncounted = [];
105
+ const uncountedRow = ({
106
+ view,
107
+ step
108
+ }) => ({
109
+ kind: "step",
110
+ id: step.step_id,
111
+ reason: "step_failed",
112
+ status: "failed",
113
+ phase_id: view.phase.phase_id,
114
+ ...view.passIndex !== void 0 && { pass_index: view.passIndex },
115
+ ...messageOf(step.error ?? firstFailedValidationMessage(step))
116
+ });
117
+ for (const failure of uncountedFailures) {
118
+ if (failure.view.phase.passed || assertionOwners.has(failure.step)) continue;
119
+ if (isOptionalPhase(failure.view.phase.phase_id) && !optionalOnly) {
120
+ ungradedUncounted.push(failure);
121
+ continue;
122
+ }
123
+ namedUncounted.add(failure.step);
124
+ add(uncountedRow(failure));
125
+ }
126
+ let requiredPhaseHasExecutedPass = false;
127
+ const vacuousSkips = [];
128
+ for (const view of phaseViews) {
129
+ const { phase, passIndex } = view;
130
+ if (isSyntheticPhase(phase.phase_id) || isOptionalPhase(phase.phase_id) && !optionalOnly) continue;
131
+ if (phase.passed) {
132
+ if (phase.steps.some((step) => !step.skipped && step.passed)) requiredPhaseHasExecutedPass = true;
133
+ for (const step of phase.steps) if (step.skipped) vacuousSkips.push({ view, step });
134
+ continue;
135
+ }
136
+ if (phase.steps.some((step) => countedFailures.has(step) || namedUncounted.has(step) || assertionOwners.has(step))) {
137
+ continue;
138
+ }
139
+ const skipped = phase.steps.filter((step) => step.skipped);
140
+ const causal = skipped.filter((step) => !NEUTRAL_SKIP_REASONS.has(detailedSkipReason(step) ?? ""));
141
+ const named = causal.length > 0 ? causal : skipped;
142
+ if (named.length === 0) {
143
+ add({
144
+ kind: "phase",
145
+ id: phase.phase_id,
146
+ reason: "required_phase_not_executed",
147
+ status: "not_passed",
148
+ phase_id: phase.phase_id,
149
+ ...passIndex !== void 0 && { pass_index: passIndex },
150
+ message: `Phase '${phase.phase_id}' did not pass`
151
+ });
152
+ continue;
153
+ }
154
+ for (const step of named) add(skippedStepContributor(phase, step, passIndex));
155
+ }
156
+ if (contributors.length === 0 && !requiredPhaseHasExecutedPass) {
157
+ const named = vacuousSkips.filter(({ step }) => !NEUTRAL_SKIP_REASONS.has(detailedSkipReason(step) ?? ""));
158
+ for (const { view, step } of named.length > 0 ? named : vacuousSkips) {
159
+ const row = skippedStepContributor(view.phase, step, view.passIndex);
160
+ add(row.reason === "required_phase_not_executed" ? { ...row, reason: "no_executed_steps" } : row);
161
+ }
162
+ if (contributors.length === 0 && !options.coverageUnverified) {
163
+ add({
164
+ kind: "phase",
165
+ id: "storyboard",
166
+ reason: "no_executed_steps",
167
+ status: "not_passed",
168
+ message: "No required step executed and passed"
169
+ });
170
+ }
171
+ }
172
+ if (options.coverageUnverified) {
173
+ const probes = phaseViews.flatMap(
174
+ ({ phase, passIndex }) => phase.steps.filter((step) => step.skipped).map((step) => ({ phase, step, passIndex }))
175
+ );
176
+ if (probes.length === 0) {
177
+ add({
178
+ kind: "phase",
179
+ id: "storyboard",
180
+ reason: "coverage_unverified",
181
+ status: "not_passed",
182
+ message: "No request-signing probe reached the agent"
183
+ });
184
+ }
185
+ for (const { phase, step, passIndex } of probes) {
186
+ add({ ...skippedStepContributor(phase, step, passIndex), reason: "coverage_unverified" });
187
+ }
188
+ }
189
+ if (contributors.length === 0) for (const failure of ungradedUncounted) add(uncountedRow(failure));
190
+ const reason = REASON_PRECEDENCE.find((candidate) => contributors.some((row) => row.reason === candidate)) ?? "unexplained";
191
+ const bounded = contributors.slice(0, MAX_CONTRIBUTORS);
192
+ return {
193
+ verdict_reason: reason,
194
+ verdict_detail: buildDetail(reason, contributors),
195
+ verdict_contributing: bounded
196
+ };
197
+ }
198
+ function applyStoryboardVerdictExplanation(result, options = {}) {
199
+ delete result.verdict_reason;
200
+ delete result.verdict_detail;
201
+ delete result.verdict_contributing;
202
+ const explanation = explainStoryboardVerdict(result, options);
203
+ if (explanation) Object.assign(result, explanation);
204
+ return result;
205
+ }
206
+ function classifyFailedStep(phase, step) {
207
+ if (step.validations.some((validation) => !validation.passed && RUNNER_ERROR_CHECKS.has(validation.check))) {
208
+ return "runner_error";
209
+ }
210
+ if (phase.phase_id === CONTROLLER_SEEDING_PHASE_ID) return "controller_prerequisite_unmet";
211
+ if (FIXTURE_PHASE_IDS.has(phase.phase_id)) return "fixture_error";
212
+ return "step_failed";
213
+ }
214
+ function skippedStepContributor(phase, step, passIndex) {
215
+ const skipReason = detailedSkipReason(step);
216
+ const requirement = step.skip?.requirement;
217
+ const controllerGap = skipReason !== void 0 && CONTROLLER_SKIP_REASONS.has(skipReason) || requirement !== void 0 && CONTROLLER_REQUIREMENTS.has(requirement);
218
+ return {
219
+ kind: "step",
220
+ id: step.step_id,
221
+ reason: controllerGap ? "controller_prerequisite_unmet" : "required_phase_not_executed",
222
+ status: "skipped",
223
+ phase_id: phase.phase_id,
224
+ ...passIndex !== void 0 && { pass_index: passIndex },
225
+ ...skipReason !== void 0 && { skip_reason: skipReason },
226
+ ...requirement !== void 0 && { requirement },
227
+ ...messageOf(step.skip?.detail)
228
+ };
229
+ }
230
+ function detailedSkipReason(step) {
231
+ return step.skip_reason ?? step.skip?.reason;
232
+ }
233
+ function isSyntheticPhase(phaseId) {
234
+ return phaseId === CONTROLLER_SEEDING_PHASE_ID || FIXTURE_PHASE_IDS.has(phaseId);
235
+ }
236
+ function findOwningStep(result, phaseViews, assertion) {
237
+ const phases = assertion.pass_index === void 0 ? result.phases : phaseViews.filter((view) => view.passIndex === assertion.pass_index).map((view) => view.phase);
238
+ for (const phase of phases) {
239
+ const step = phase.steps.find((candidate) => candidate.step_id === assertion.step_id);
240
+ if (step) return step;
241
+ }
242
+ return void 0;
243
+ }
244
+ function assertionMessage(assertion, owner) {
245
+ const base = assertion.error ?? assertion.description;
246
+ if (owner?.skipped) return `${base} (on skipped step '${owner.step_id}')`;
247
+ return base;
248
+ }
249
+ function firstFailedValidationMessage(step) {
250
+ const failed = step.validations.find((validation) => !validation.passed);
251
+ if (!failed) return void 0;
252
+ return failed.error ? `${failed.description}: ${failed.error}` : failed.description;
253
+ }
254
+ function messageOf(text) {
255
+ if (typeof text !== "string") return {};
256
+ const trimmed = text.replace(/\s+/g, " ").trim();
257
+ if (trimmed.length === 0) return {};
258
+ return { message: truncate(trimmed, MAX_MESSAGE_LENGTH) };
259
+ }
260
+ function truncate(text, max) {
261
+ return text.length <= max ? text : `${text.slice(0, max - 1)}\u2026`;
262
+ }
263
+ const REASON_LEADS = {
264
+ step_failed: "A step failed",
265
+ assertion_failed: "A storyboard-level assertion failed",
266
+ controller_prerequisite_unmet: "Required steps did not run because comply_test_controller or its seeding was unavailable",
267
+ required_phase_not_executed: "A required phase did not run",
268
+ no_executed_steps: "No required step executed and passed, so the run proves nothing",
269
+ fixture_error: "Fixture resolution or preparation failed before the behavior under test could run",
270
+ coverage_unverified: "No request-signing probe reached the agent, so signing coverage is unverified",
271
+ runner_error: "The runner or host could not proceed; this is not an agent failure",
272
+ unexplained: "The runner could not attribute this verdict; please report it as a runner bug"
273
+ };
274
+ function buildDetail(reason, contributors) {
275
+ const primary = contributors.filter((row) => row.reason === reason);
276
+ const parts = [REASON_LEADS[reason]];
277
+ const described = primary.slice(0, 3).map(describeContributor);
278
+ if (described.length > 0) parts[0] += `: ${described.join("; ")}`;
279
+ if (primary.length > described.length) parts[0] += ` (+${primary.length - described.length} more)`;
280
+ const others = REASON_PRECEDENCE.filter(
281
+ (candidate) => candidate !== reason && contributors.some((row) => row.reason === candidate)
282
+ );
283
+ if (others.length > 0) parts.push(`Also: ${others.join(", ")}`);
284
+ if (contributors.length > MAX_CONTRIBUTORS) {
285
+ parts.push(`${contributors.length - MAX_CONTRIBUTORS} contributor(s) omitted`);
286
+ }
287
+ return truncate(`${parts.map(stripTrailingPeriods).join(". ")}.`, MAX_DETAIL_LENGTH);
288
+ }
289
+ function stripTrailingPeriods(text) {
290
+ let out = text.trimEnd();
291
+ while (out.endsWith(".")) out = out.slice(0, -1).trimEnd();
292
+ return out;
293
+ }
294
+ function describeContributor(row) {
295
+ const where = row.pass_index !== void 0 ? ` (pass ${row.pass_index})` : "";
296
+ if (row.kind === "assertion") return `${row.id}${where}${row.message ? ` \u2014 ${row.message}` : ""}`;
297
+ if (row.status === "skipped") {
298
+ const why = row.requirement ? `${row.skip_reason ?? "skipped"}: ${row.requirement}` : row.skip_reason ?? "skipped";
299
+ return `${row.id}${where} skipped (${why})`;
300
+ }
301
+ if (row.status === "failed") return `${row.id}${where} failed`;
302
+ return `${row.id}${where}${row.message ? ` \u2014 ${row.message}` : ""}`;
303
+ }
304
+ // Annotate the CommonJS export names for ESM import in node:
305
+ 0 && (module.exports = {
306
+ CONTROLLER_SEEDING_PHASE_ID,
307
+ applyStoryboardVerdictExplanation,
308
+ explainStoryboardVerdict
309
+ });