@adcp/sdk 17.0.0-beta.24 → 17.0.0-beta.26

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 (89) hide show
  1. package/dist/lib/adapters/version/schema-projection.d.mts +11 -0
  2. package/dist/lib/adapters/version/schema-projection.d.ts +11 -0
  3. package/dist/lib/adapters/version/schema-projection.js +52 -0
  4. package/dist/lib/adapters/version/schema-projection.mjs +51 -0
  5. package/dist/lib/discovery/property-crawler.d.mts +11 -0
  6. package/dist/lib/discovery/property-crawler.d.ts +11 -0
  7. package/dist/lib/discovery/property-crawler.js +15 -2
  8. package/dist/lib/discovery/property-crawler.mjs +15 -2
  9. package/dist/lib/discovery/resolve-agent-properties.d.mts +81 -8
  10. package/dist/lib/discovery/resolve-agent-properties.d.ts +81 -8
  11. package/dist/lib/discovery/resolve-agent-properties.js +94 -14
  12. package/dist/lib/discovery/resolve-agent-properties.mjs +91 -13
  13. package/dist/lib/discovery/validate-adagents.d.mts +7 -0
  14. package/dist/lib/discovery/validate-adagents.d.ts +7 -0
  15. package/dist/lib/entrypoints/discovery.d.mts +1 -1
  16. package/dist/lib/entrypoints/discovery.d.ts +1 -1
  17. package/dist/lib/entrypoints/discovery.js +4 -0
  18. package/dist/lib/entrypoints/discovery.mjs +5 -1
  19. package/dist/lib/index.d.mts +1 -1
  20. package/dist/lib/index.d.ts +1 -1
  21. package/dist/lib/index.js +4 -0
  22. package/dist/lib/index.mjs +5 -1
  23. package/dist/lib/reporting/evidence.d.mts +8 -0
  24. package/dist/lib/reporting/evidence.d.ts +8 -0
  25. package/dist/lib/reporting/evidence.js +10 -2
  26. package/dist/lib/reporting/evidence.mjs +8 -1
  27. package/dist/lib/reporting/ledger/index.d.mts +1 -1
  28. package/dist/lib/reporting/ledger/index.d.ts +1 -1
  29. package/dist/lib/reporting/ledger/index.js +3 -1
  30. package/dist/lib/reporting/ledger/index.mjs +4 -2
  31. package/dist/lib/reporting/ledger/status-ingest.js +3 -2
  32. package/dist/lib/reporting/ledger/status-ingest.mjs +3 -2
  33. package/dist/lib/reporting/subscriptions/engine.js +1 -1
  34. package/dist/lib/reporting/subscriptions/engine.mjs +1 -1
  35. package/dist/lib/server/account-response-identity.d.mts +4 -3
  36. package/dist/lib/server/account-response-identity.d.ts +4 -3
  37. package/dist/lib/server/account-response-identity.js +8 -4
  38. package/dist/lib/server/account-response-identity.mjs +8 -4
  39. package/dist/lib/server/credential-policy.js +5 -0
  40. package/dist/lib/server/credential-policy.mjs +5 -0
  41. package/dist/lib/server/decisioning/account.js +14 -3
  42. package/dist/lib/server/decisioning/account.mjs +16 -4
  43. package/dist/lib/server/notification-subscriptions/runtime.d.mts +6 -0
  44. package/dist/lib/server/notification-subscriptions/runtime.d.ts +6 -0
  45. package/dist/lib/server/notification-subscriptions/runtime.js +99 -0
  46. package/dist/lib/server/notification-subscriptions/runtime.mjs +98 -0
  47. package/dist/lib/server/principal/reporting-subscriptions.js +4 -1
  48. package/dist/lib/server/principal/reporting-subscriptions.mjs +4 -1
  49. package/dist/lib/server/reporting-delivery-config.d.mts +2 -2
  50. package/dist/lib/server/reporting-delivery-config.d.ts +2 -2
  51. package/dist/lib/server/reporting-delivery-config.js +9 -3
  52. package/dist/lib/server/reporting-delivery-config.mjs +9 -3
  53. package/dist/lib/server/wire-safe.js +3 -0
  54. package/dist/lib/server/wire-safe.mjs +3 -0
  55. package/dist/lib/supply-path/validation.d.mts +8 -0
  56. package/dist/lib/supply-path/validation.d.ts +8 -0
  57. package/dist/lib/testing/compliance/comply.js +1 -1
  58. package/dist/lib/testing/compliance/comply.mjs +3 -2
  59. package/dist/lib/testing/storyboard/index.d.mts +1 -1
  60. package/dist/lib/testing/storyboard/index.d.ts +1 -1
  61. package/dist/lib/testing/storyboard/index.js +6 -0
  62. package/dist/lib/testing/storyboard/index.mjs +6 -0
  63. package/dist/lib/testing/storyboard/loader.js +52 -28
  64. package/dist/lib/testing/storyboard/loader.mjs +52 -28
  65. package/dist/lib/testing/storyboard/runner.d.mts +24 -1
  66. package/dist/lib/testing/storyboard/runner.d.ts +24 -1
  67. package/dist/lib/testing/storyboard/runner.js +75 -7
  68. package/dist/lib/testing/storyboard/runner.mjs +72 -7
  69. package/dist/lib/testing/storyboard/types.d.mts +51 -6
  70. package/dist/lib/testing/storyboard/types.d.ts +51 -6
  71. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  72. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  73. package/dist/lib/types/wellknown-schemas.generated.d.mts +16 -16
  74. package/dist/lib/types/wellknown-schemas.generated.d.ts +16 -16
  75. package/dist/lib/utils/json-depth.d.mts +8 -0
  76. package/dist/lib/utils/json-depth.d.ts +8 -0
  77. package/dist/lib/utils/json-depth.js +18 -2
  78. package/dist/lib/utils/json-depth.mjs +16 -1
  79. package/dist/lib/version.d.mts +3 -3
  80. package/dist/lib/version.d.ts +3 -3
  81. package/dist/lib/version.js +3 -3
  82. package/dist/lib/version.mjs +3 -3
  83. package/docs/TYPE-SUMMARY.md +2 -2
  84. package/docs/guides/STORYBOARD-CAPABILITY-GATES.md +96 -0
  85. package/docs/guides/VALIDATE-YOUR-AGENT.md +5 -0
  86. package/docs/llms.txt +2 -2
  87. package/docs/migration-14.x-rc-worksheet.md +4 -4
  88. package/docs/migration-16-to-17.md +47 -8
  89. package/package.json +1 -1
@@ -21,9 +21,12 @@ __export(reporting_delivery_config_exports, {
21
21
  projectReportingDeliveryConfigStates: () => projectReportingDeliveryConfigStates
22
22
  });
23
23
  module.exports = __toCommonJS(reporting_delivery_config_exports);
24
+ var import_schema_projection = require('../adapters/version/schema-projection.js');
25
+ var import_json_depth = require('../utils/json-depth.js');
24
26
  var import_schema_loader = require('../validation/schema-loader.js');
25
27
  var import_account_response_identity = require('./account-response-identity.js');
26
28
  const MAX_REPORTING_DELIVERY_CONFIGS = 16;
29
+ const DELIVERY_CONFIG_STATE_SCHEMA = "core/reporting-delivery-config-state.json";
27
30
  const CREDENTIAL_LIKE_URL_COMPONENT = /\b(?:access[_-]?token|api[_-]?key|assertion|authorization|bearer|code|credential|password|passwd|secret|session|signature|token|x-amz-credential|x-amz-security-token|x-amz-signature)\b/i;
28
31
  function isCredentialLikeUrlComponent(value) {
29
32
  try {
@@ -56,9 +59,12 @@ function projectReportingDeliveryConfigStates(states) {
56
59
  if (!Array.isArray(states) || states.length > MAX_REPORTING_DELIVERY_CONFIGS) {
57
60
  throw new Error(`reporting_delivery_configs must contain at most ${MAX_REPORTING_DELIVERY_CONFIGS} state records`);
58
61
  }
59
- const validateState = (0, import_schema_loader.getSchemaValidatorByRef)("core/reporting-delivery-config-state.json");
62
+ const validateState = (0, import_schema_loader.getSchemaValidatorByRef)(DELIVERY_CONFIG_STATE_SCHEMA);
60
63
  if (!validateState) {
61
- throw new Error("Bundled schema core/reporting-delivery-config-state.json is unavailable");
64
+ throw new Error(`Bundled schema ${DELIVERY_CONFIG_STATE_SCHEMA} is unavailable`);
65
+ }
66
+ if (states.some((state) => (0, import_json_depth.exceedsJsonDepth)(state))) {
67
+ throw new Error("reporting_delivery_configs contains a state that exceeds the maximum JSON depth");
62
68
  }
63
69
  const snapshots = states.map((state) => structuredClone(state));
64
70
  for (const state of snapshots) {
@@ -67,7 +73,7 @@ function projectReportingDeliveryConfigStates(states) {
67
73
  }
68
74
  assertSafeSetupUrl(state.setup?.url);
69
75
  }
70
- return snapshots;
76
+ return snapshots.map((state) => (0, import_schema_projection.projectToDeclaredMembers)(DELIVERY_CONFIG_STATE_SCHEMA, state).value);
71
77
  }
72
78
  // Annotate the CommonJS export names for ESM import in node:
73
79
  0 && (module.exports = {
@@ -1,6 +1,9 @@
1
+ import { projectToDeclaredMembers } from "../adapters/version/schema-projection.mjs";
2
+ import { exceedsJsonDepth } from "../utils/json-depth.mjs";
1
3
  import { getSchemaValidatorByRef } from "../validation/schema-loader.mjs";
2
4
  import { retainsNonResponseAccountMember } from "./account-response-identity.mjs";
3
5
  const MAX_REPORTING_DELIVERY_CONFIGS = 16;
6
+ const DELIVERY_CONFIG_STATE_SCHEMA = "core/reporting-delivery-config-state.json";
4
7
  const CREDENTIAL_LIKE_URL_COMPONENT = /\b(?:access[_-]?token|api[_-]?key|assertion|authorization|bearer|code|credential|password|passwd|secret|session|signature|token|x-amz-credential|x-amz-security-token|x-amz-signature)\b/i;
5
8
  function isCredentialLikeUrlComponent(value) {
6
9
  try {
@@ -33,9 +36,12 @@ function projectReportingDeliveryConfigStates(states) {
33
36
  if (!Array.isArray(states) || states.length > MAX_REPORTING_DELIVERY_CONFIGS) {
34
37
  throw new Error(`reporting_delivery_configs must contain at most ${MAX_REPORTING_DELIVERY_CONFIGS} state records`);
35
38
  }
36
- const validateState = getSchemaValidatorByRef("core/reporting-delivery-config-state.json");
39
+ const validateState = getSchemaValidatorByRef(DELIVERY_CONFIG_STATE_SCHEMA);
37
40
  if (!validateState) {
38
- throw new Error("Bundled schema core/reporting-delivery-config-state.json is unavailable");
41
+ throw new Error(`Bundled schema ${DELIVERY_CONFIG_STATE_SCHEMA} is unavailable`);
42
+ }
43
+ if (states.some((state) => exceedsJsonDepth(state))) {
44
+ throw new Error("reporting_delivery_configs contains a state that exceeds the maximum JSON depth");
39
45
  }
40
46
  const snapshots = states.map((state) => structuredClone(state));
41
47
  for (const state of snapshots) {
@@ -44,7 +50,7 @@ function projectReportingDeliveryConfigStates(states) {
44
50
  }
45
51
  assertSafeSetupUrl(state.setup?.url);
46
52
  }
47
- return snapshots;
53
+ return snapshots.map((state) => projectToDeclaredMembers(DELIVERY_CONFIG_STATE_SCHEMA, state).value);
48
54
  }
49
55
  export {
50
56
  projectReportingDeliveryConfigStates
@@ -76,6 +76,9 @@ function scrubExtensions(request, options) {
76
76
  function stripNestedCredentials(value, patterns, fromDepth = 0) {
77
77
  const hits = new Set((0, import_credential_policy.scanArgsForCredentials)(value, patterns));
78
78
  if (hits.size === 0) return value;
79
+ if ([...hits].some((hit) => hit.endsWith("<too-deep>") || hit.endsWith("<unreadable>"))) {
80
+ return Array.isArray(value) ? [] : {};
81
+ }
79
82
  const seen = /* @__PURE__ */ new WeakSet();
80
83
  const walk = (node, path, depth) => {
81
84
  if (node === null || typeof node !== "object") return node;
@@ -51,6 +51,9 @@ function scrubExtensions(request, options) {
51
51
  function stripNestedCredentials(value, patterns, fromDepth = 0) {
52
52
  const hits = new Set(scanArgsForCredentials(value, patterns));
53
53
  if (hits.size === 0) return value;
54
+ if ([...hits].some((hit) => hit.endsWith("<too-deep>") || hit.endsWith("<unreadable>"))) {
55
+ return Array.isArray(value) ? [] : {};
56
+ }
54
57
  const seen = /* @__PURE__ */ new WeakSet();
55
58
  const walk = (node, path, depth) => {
56
59
  if (node === null || typeof node !== "object") return node;
@@ -4,6 +4,14 @@ export declare function records(value: unknown): Record<string, unknown>[];
4
4
  export declare function strings(value: unknown): value is string[];
5
5
  /** Domain identity never strips www or conflates sibling publisher namespaces. */
6
6
  export declare function domain(value: unknown): string | null;
7
+ /**
8
+ * Exact canonical agent URL used by every supply-path leg. Semantics version 1
9
+ * compares `authorized_agents[].url` by exact canonical URL, including an
10
+ * origin-only entry: the 3.3 rule that an origin-only entry authorizes the agent
11
+ * at any path on that origin (adcp#8862) does not apply here until a new
12
+ * supply-path semantics version adopts it, planned for 4.0. Do not swap this for
13
+ * `agentUrlMatchesAuthorizedEntry`. See adcontextprotocol/adcp#8943.
14
+ */
7
15
  export declare function agentIdentity(value: unknown): string | null;
8
16
  export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
9
17
  /** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
@@ -4,6 +4,14 @@ export declare function records(value: unknown): Record<string, unknown>[];
4
4
  export declare function strings(value: unknown): value is string[];
5
5
  /** Domain identity never strips www or conflates sibling publisher namespaces. */
6
6
  export declare function domain(value: unknown): string | null;
7
+ /**
8
+ * Exact canonical agent URL used by every supply-path leg. Semantics version 1
9
+ * compares `authorized_agents[].url` by exact canonical URL, including an
10
+ * origin-only entry: the 3.3 rule that an origin-only entry authorizes the agent
11
+ * at any path on that origin (adcp#8862) does not apply here until a new
12
+ * supply-path semantics version adopts it, planned for 4.0. Do not swap this for
13
+ * `agentUrlMatchesAuthorizedEntry`. See adcontextprotocol/adcp#8943.
14
+ */
7
15
  export declare function agentIdentity(value: unknown): string | null;
8
16
  export declare function validateSupplyPathRequest(input: SupplyPathRequest): SupplyPathRequest;
9
17
  /** Runtime boundary for cached remote verdicts. Unknown extensions are preserved. */
@@ -617,7 +617,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
617
617
  if (predicates.length === 0) return false;
618
618
  if (typeof storyboard.adcp_version !== "string") return false;
619
619
  if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
620
- if (predicates.some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
620
+ if (predicates.flatMap(import_runner.capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
621
621
  return false;
622
622
  }
623
623
  for (const key of Object.keys(result)) {
@@ -15,7 +15,8 @@ import {
15
15
  storyboardCapabilityGateUnmet,
16
16
  storyboardRequiresCapabilityEvidence,
17
17
  storyboardAllowsCapabilityDiagnostic,
18
- storyboardCapabilityPredicates
18
+ storyboardCapabilityPredicates,
19
+ capabilityPathPredicates
19
20
  } from "../storyboard/runner.mjs";
20
21
  import { applyNativeA2AComplianceTransportOptions } from "../storyboard/native-a2a-compliance.mjs";
21
22
  import { validateTestKit } from "../storyboard/test-kit.mjs";
@@ -610,7 +611,7 @@ function isCapabilityUnsupportedSkip(storyboard, result) {
610
611
  if (predicates.length === 0) return false;
611
612
  if (typeof storyboard.adcp_version !== "string") return false;
612
613
  if (compareAdcpVersionStrings(storyboard.adcp_version, CAPABILITY_ROLLUP_MIN_ADCP_VERSION) < 0) return false;
613
- if (predicates.some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
614
+ if (predicates.flatMap(capabilityPathPredicates).some((predicate) => capabilityPathSegments(predicate.path).includes("compliance_testing"))) {
614
615
  return false;
615
616
  }
616
617
  for (const key of Object.keys(result)) {
@@ -17,7 +17,7 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
17
17
  export { createRunnerVariables } from './context.mjs';
18
18
  export type { RunnerVariables } from './context.mjs';
19
19
  export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions.mjs';
20
- export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
20
+ export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, evaluateCapabilityPredicateAgainstCapabilities, isAnyOfCapabilityPredicate, capabilityPathPredicates, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
21
21
  export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader.mjs';
22
22
  export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution.mjs';
23
23
  export type { FixtureContextOutput } from './types.mjs';
@@ -17,7 +17,7 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
17
17
  export { createRunnerVariables } from './context';
18
18
  export type { RunnerVariables } from './context';
19
19
  export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions';
20
- export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner';
20
+ export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, evaluateCapabilityPredicateAgainstCapabilities, isAnyOfCapabilityPredicate, capabilityPathPredicates, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner';
21
21
  export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader';
22
22
  export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution';
23
23
  export type { FixtureContextOutput } from './types';
@@ -56,6 +56,7 @@ __export(storyboard_exports, {
56
56
  buildFixtureResolutionSpecs: () => import_fixture_resolution.buildFixtureResolutionSpecs,
57
57
  buildProtectedResourceMetadataUrl: () => import_oauth_metadata_graph.buildProtectedResourceMetadataUrl,
58
58
  buildRequest: () => import_request_builder.buildRequest,
59
+ capabilityPathPredicates: () => import_runner.capabilityPathPredicates,
59
60
  clearAssertionRegistry: () => import_assertions.clearAssertionRegistry,
60
61
  clearSandboxCache: () => import_sandbox_entities.clearSandboxCache,
61
62
  compareCollectionPairs: () => import_collection_selection.compareCollectionPairs,
@@ -66,6 +67,7 @@ __export(storyboard_exports, {
66
67
  detectContextRejectionHints: () => import_rejection_hints.detectContextRejectionHints,
67
68
  diffCollectionPairSets: () => import_collection_selection.diffCollectionPairSets,
68
69
  evaluateCapabilityPredicate: () => import_runner.evaluateCapabilityPredicate,
70
+ evaluateCapabilityPredicateAgainstCapabilities: () => import_runner.evaluateCapabilityPredicateAgainstCapabilities,
69
71
  evaluateCollectionSelection: () => import_collection_selection.evaluateCollectionSelection,
70
72
  executeStoryboardTask: () => import_task_map.executeStoryboardTask,
71
73
  expandCreativeAssetDirectives: () => import_creative_assets.expandCreativeAssetDirectives,
@@ -87,6 +89,7 @@ __export(storyboard_exports, {
87
89
  gradeOAuthMetadataGraphVector: () => import_oauth_metadata_graph.gradeOAuthMetadataGraphVector,
88
90
  hasRequestBuilder: () => import_request_builder.hasRequestBuilder,
89
91
  injectContext: () => import_context2.injectContext,
92
+ isAnyOfCapabilityPredicate: () => import_runner.isAnyOfCapabilityPredicate,
90
93
  isComplianceVersionSupported: () => import_compliance.isComplianceVersionSupported,
91
94
  isProtectedContextKey: () => import_protected_context.isProtectedContextKey,
92
95
  isSandboxDomain: () => import_sandbox_entities.isSandboxDomain,
@@ -205,6 +208,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
205
208
  buildFixtureResolutionSpecs,
206
209
  buildProtectedResourceMetadataUrl,
207
210
  buildRequest,
211
+ capabilityPathPredicates,
208
212
  clearAssertionRegistry,
209
213
  clearSandboxCache,
210
214
  compareCollectionPairs,
@@ -215,6 +219,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
215
219
  detectContextRejectionHints,
216
220
  diffCollectionPairSets,
217
221
  evaluateCapabilityPredicate,
222
+ evaluateCapabilityPredicateAgainstCapabilities,
218
223
  evaluateCollectionSelection,
219
224
  executeStoryboardTask,
220
225
  expandCreativeAssetDirectives,
@@ -236,6 +241,7 @@ var import_creative_build_probe = require('./creative-build-probe.js');
236
241
  gradeOAuthMetadataGraphVector,
237
242
  hasRequestBuilder,
238
243
  injectContext,
244
+ isAnyOfCapabilityPredicate,
239
245
  isComplianceVersionSupported,
240
246
  isProtectedContextKey,
241
247
  isSandboxDomain,
@@ -25,6 +25,9 @@ import {
25
25
  listStrictOnlyFailures,
26
26
  resolveCapabilityPath,
27
27
  evaluateCapabilityPredicate,
28
+ evaluateCapabilityPredicateAgainstCapabilities,
29
+ isAnyOfCapabilityPredicate,
30
+ capabilityPathPredicates,
28
31
  describeStoryboardCapabilityGates,
29
32
  buildDiscoveryFailedResult
30
33
  } from "./runner.mjs";
@@ -161,6 +164,7 @@ export {
161
164
  buildFixtureResolutionSpecs,
162
165
  buildProtectedResourceMetadataUrl,
163
166
  buildRequest,
167
+ capabilityPathPredicates,
164
168
  clearAssertionRegistry,
165
169
  clearSandboxCache,
166
170
  compareCollectionPairs,
@@ -171,6 +175,7 @@ export {
171
175
  detectContextRejectionHints,
172
176
  diffCollectionPairSets,
173
177
  evaluateCapabilityPredicate,
178
+ evaluateCapabilityPredicateAgainstCapabilities,
174
179
  evaluateCollectionSelection,
175
180
  executeStoryboardTask,
176
181
  expandCreativeAssetDirectives,
@@ -192,6 +197,7 @@ export {
192
197
  gradeOAuthMetadataGraphVector,
193
198
  hasRequestBuilder,
194
199
  injectContext,
200
+ isAnyOfCapabilityPredicate,
195
201
  isComplianceVersionSupported,
196
202
  isProtectedContextKey,
197
203
  isSandboxDomain,
@@ -187,6 +187,10 @@ function validatePhaseSkipIf(storyboardId, phase) {
187
187
  }
188
188
  }
189
189
  function validateRequiresAllCapabilities(storyboard) {
190
+ validateAnyOfGate(storyboard.requires_capability, `[${storyboard.id}] requires_capability`);
191
+ for (const phase of storyboard.phases ?? []) {
192
+ validateAnyOfGate(phase.requires_capability, `[${storyboard.id}] phase '${phase.id}': requires_capability`);
193
+ }
190
194
  const predicates = storyboard.requires_all_capabilities;
191
195
  if (predicates === void 0) return;
192
196
  if (!Array.isArray(predicates) || predicates.length < 2) {
@@ -195,37 +199,57 @@ function validateRequiresAllCapabilities(storyboard) {
195
199
  );
196
200
  }
197
201
  for (let index = 0; index < predicates.length; index++) {
198
- const raw = predicates[index];
199
- const prefix = `[${storyboard.id}] requires_all_capabilities[${index}]`;
200
- if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
201
- throw new Error(`${prefix}: must be a capability predicate object`);
202
- }
203
- const predicate = raw;
204
- if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
205
- throw new Error(`${prefix}.path: must be a non-empty string`);
206
- }
207
- if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
208
- throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
209
- }
210
- const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
211
- (key) => Object.prototype.hasOwnProperty.call(predicate, key)
212
- );
213
- if (matcherKeys.length !== 1) {
214
- throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
215
- }
216
- const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
217
- if (unknownKeys.length > 0) {
218
- throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
219
- }
220
- if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
221
- throw new Error(`${prefix}.present: must be a boolean`);
202
+ validateCapabilityPredicateShape(predicates[index], `[${storyboard.id}] requires_all_capabilities[${index}]`);
203
+ }
204
+ }
205
+ function validateAnyOfGate(raw, prefix) {
206
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
207
+ if (!Object.prototype.hasOwnProperty.call(raw, "any_of")) return;
208
+ validateCapabilityPredicateShape(raw, prefix);
209
+ }
210
+ function validateCapabilityPredicateShape(raw, prefix) {
211
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
212
+ throw new Error(`${prefix}: must be a capability predicate object`);
213
+ }
214
+ const predicate = raw;
215
+ if (Object.prototype.hasOwnProperty.call(predicate, "any_of")) {
216
+ const unknownKeys2 = Object.keys(predicate).filter((key) => key !== "any_of");
217
+ if (unknownKeys2.length > 0) {
218
+ throw new Error(`${prefix}: any_of cannot be combined with ${unknownKeys2.join(", ")}`);
222
219
  }
223
- if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
224
- throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
220
+ const entries = predicate.any_of;
221
+ if (!Array.isArray(entries) || entries.length < 2) {
222
+ throw new Error(`${prefix}.any_of: must list at least two predicates`);
225
223
  }
226
- if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
227
- throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
224
+ for (let index = 0; index < entries.length; index++) {
225
+ validateCapabilityPredicateShape(entries[index], `${prefix}.any_of[${index}]`);
228
226
  }
227
+ return;
228
+ }
229
+ if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
230
+ throw new Error(`${prefix}.path: must be a non-empty string`);
231
+ }
232
+ if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
233
+ throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
234
+ }
235
+ const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
236
+ (key) => Object.prototype.hasOwnProperty.call(predicate, key)
237
+ );
238
+ if (matcherKeys.length !== 1) {
239
+ throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
240
+ }
241
+ const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
242
+ if (unknownKeys.length > 0) {
243
+ throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
244
+ }
245
+ if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
246
+ throw new Error(`${prefix}.present: must be a boolean`);
247
+ }
248
+ if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
249
+ throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
250
+ }
251
+ if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
252
+ throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
229
253
  }
230
254
  }
231
255
  function isJsonCapabilityValue(value, seen = /* @__PURE__ */ new Set()) {
@@ -159,6 +159,10 @@ function validatePhaseSkipIf(storyboardId, phase) {
159
159
  }
160
160
  }
161
161
  function validateRequiresAllCapabilities(storyboard) {
162
+ validateAnyOfGate(storyboard.requires_capability, `[${storyboard.id}] requires_capability`);
163
+ for (const phase of storyboard.phases ?? []) {
164
+ validateAnyOfGate(phase.requires_capability, `[${storyboard.id}] phase '${phase.id}': requires_capability`);
165
+ }
162
166
  const predicates = storyboard.requires_all_capabilities;
163
167
  if (predicates === void 0) return;
164
168
  if (!Array.isArray(predicates) || predicates.length < 2) {
@@ -167,37 +171,57 @@ function validateRequiresAllCapabilities(storyboard) {
167
171
  );
168
172
  }
169
173
  for (let index = 0; index < predicates.length; index++) {
170
- const raw = predicates[index];
171
- const prefix = `[${storyboard.id}] requires_all_capabilities[${index}]`;
172
- if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
173
- throw new Error(`${prefix}: must be a capability predicate object`);
174
- }
175
- const predicate = raw;
176
- if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
177
- throw new Error(`${prefix}.path: must be a non-empty string`);
178
- }
179
- if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
180
- throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
181
- }
182
- const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
183
- (key) => Object.prototype.hasOwnProperty.call(predicate, key)
184
- );
185
- if (matcherKeys.length !== 1) {
186
- throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
187
- }
188
- const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
189
- if (unknownKeys.length > 0) {
190
- throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
191
- }
192
- if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
193
- throw new Error(`${prefix}.present: must be a boolean`);
174
+ validateCapabilityPredicateShape(predicates[index], `[${storyboard.id}] requires_all_capabilities[${index}]`);
175
+ }
176
+ }
177
+ function validateAnyOfGate(raw, prefix) {
178
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
179
+ if (!Object.prototype.hasOwnProperty.call(raw, "any_of")) return;
180
+ validateCapabilityPredicateShape(raw, prefix);
181
+ }
182
+ function validateCapabilityPredicateShape(raw, prefix) {
183
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
184
+ throw new Error(`${prefix}: must be a capability predicate object`);
185
+ }
186
+ const predicate = raw;
187
+ if (Object.prototype.hasOwnProperty.call(predicate, "any_of")) {
188
+ const unknownKeys2 = Object.keys(predicate).filter((key) => key !== "any_of");
189
+ if (unknownKeys2.length > 0) {
190
+ throw new Error(`${prefix}: any_of cannot be combined with ${unknownKeys2.join(", ")}`);
194
191
  }
195
- if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
196
- throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
192
+ const entries = predicate.any_of;
193
+ if (!Array.isArray(entries) || entries.length < 2) {
194
+ throw new Error(`${prefix}.any_of: must list at least two predicates`);
197
195
  }
198
- if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
199
- throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
196
+ for (let index = 0; index < entries.length; index++) {
197
+ validateCapabilityPredicateShape(entries[index], `${prefix}.any_of[${index}]`);
200
198
  }
199
+ return;
200
+ }
201
+ if (typeof predicate.path !== "string" || predicate.path.trim().length === 0) {
202
+ throw new Error(`${prefix}.path: must be a non-empty string`);
203
+ }
204
+ if (!CAPABILITY_PATH_PATTERN.test(predicate.path)) {
205
+ throw new Error(`${prefix}.path: must be a canonical dotted capability path`);
206
+ }
207
+ const matcherKeys = ["equals", "present", "contains", "not_contains"].filter(
208
+ (key) => Object.prototype.hasOwnProperty.call(predicate, key)
209
+ );
210
+ if (matcherKeys.length !== 1) {
211
+ throw new Error(`${prefix}: must declare exactly one of equals, present, contains, or not_contains`);
212
+ }
213
+ const unknownKeys = Object.keys(predicate).filter((key) => key !== "path" && !matcherKeys.includes(key));
214
+ if (unknownKeys.length > 0) {
215
+ throw new Error(`${prefix}: unknown field${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.join(", ")}`);
216
+ }
217
+ if (matcherKeys[0] === "present" && typeof predicate.present !== "boolean") {
218
+ throw new Error(`${prefix}.present: must be a boolean`);
219
+ }
220
+ if (matcherKeys[0] === "equals" && predicate.equals !== null && !["boolean", "string", "number"].includes(typeof predicate.equals)) {
221
+ throw new Error(`${prefix}.equals: must be a boolean, string, number, or null`);
222
+ }
223
+ if ((matcherKeys[0] === "contains" || matcherKeys[0] === "not_contains") && !isJsonCapabilityValue(predicate[matcherKeys[0]])) {
224
+ throw new Error(`${prefix}.${matcherKeys[0]}: must be a JSON-compatible capability value`);
201
225
  }
202
226
  }
203
227
  function isJsonCapabilityValue(value, seen = /* @__PURE__ */ new Set()) {
@@ -6,7 +6,7 @@
6
6
  * - runStoryboardStep(): run a single step (stateless, LLM-friendly)
7
7
  */
8
8
  import { PreparedStoryboardFixtures } from './prepared-fixtures.mjs';
9
- import type { RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types.mjs';
9
+ import type { AnyOfCapabilityPredicate, CapabilityPathPredicate, RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types.mjs';
10
10
  import type { AgentProfile, TestStepResult } from '../types.mjs';
11
11
  export declare function applyStoryboardVersionOptions(storyboard: Storyboard, options: StoryboardRunOptions): StoryboardRunOptions;
12
12
  export declare function applyAdcpVersionRunOptions(defaultAdcpVersion: string | undefined, options: StoryboardRunOptions): StoryboardRunOptions;
@@ -56,10 +56,33 @@ export declare function resolveCapabilityPath(raw: unknown, dottedPath: string):
56
56
  * that does not include `V` (structural JSON equality, no coercion). Missing and
57
57
  * non-array values skip; an empty array satisfies the predicate.
58
58
  *
59
+ * For `contains` and `not_contains`, an object `V` matches an object entry
60
+ * that carries every key of `V` with an equal value; the entry may carry
61
+ * other keys.
62
+ *
63
+ * An `any_of` predicate tests several paths, so it has no single `actual`
64
+ * value: this function throws a `TypeError` for one. Evaluate it with
65
+ * `evaluateCapabilityPredicateAgainstCapabilities`.
66
+ *
59
67
  * Exported for direct testing so the predicate semantics are pinned without
60
68
  * needing a full runStoryboard() roundtrip.
61
69
  */
62
70
  export declare function evaluateCapabilityPredicate(predicate: RequiresCapabilityPredicate, actual: unknown): string | null;
71
+ /** Type guard for the OR-composed `any_of` capability predicate. */
72
+ export declare function isAnyOfCapabilityPredicate(predicate: RequiresCapabilityPredicate): predicate is AnyOfCapabilityPredicate;
73
+ /**
74
+ * Every path predicate a capability gate tests, flattening `any_of` groups.
75
+ * Consumers that key on predicate paths (for example the compliance rollup's
76
+ * `compliance_testing` exclusion) read this instead of `predicate.path`.
77
+ */
78
+ export declare function capabilityPathPredicates(predicate: RequiresCapabilityPredicate): CapabilityPathPredicate[];
79
+ /**
80
+ * Evaluate a capability predicate, including `any_of` groups, against a raw
81
+ * `get_adcp_capabilities` response. Returns `null` when the predicate is
82
+ * satisfied and a human-readable detail otherwise. Path predicates resolve
83
+ * schema defaults on the same terms as the runner's gates.
84
+ */
85
+ export declare function evaluateCapabilityPredicateAgainstCapabilities(predicate: RequiresCapabilityPredicate, rawCapabilities: unknown, adcpVersion?: string): string | null;
63
86
  /**
64
87
  * Every root applicability predicate a storyboard authors, across
65
88
  * `requires_capability` and `requires_all_capabilities`. Exported so the
@@ -6,7 +6,7 @@
6
6
  * - runStoryboardStep(): run a single step (stateless, LLM-friendly)
7
7
  */
8
8
  import { PreparedStoryboardFixtures } from './prepared-fixtures';
9
- import type { RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types';
9
+ import type { AnyOfCapabilityPredicate, CapabilityPathPredicate, RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, PrepareStoryboardFixturesOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types';
10
10
  import type { AgentProfile, TestStepResult } from '../types';
11
11
  export declare function applyStoryboardVersionOptions(storyboard: Storyboard, options: StoryboardRunOptions): StoryboardRunOptions;
12
12
  export declare function applyAdcpVersionRunOptions(defaultAdcpVersion: string | undefined, options: StoryboardRunOptions): StoryboardRunOptions;
@@ -56,10 +56,33 @@ export declare function resolveCapabilityPath(raw: unknown, dottedPath: string):
56
56
  * that does not include `V` (structural JSON equality, no coercion). Missing and
57
57
  * non-array values skip; an empty array satisfies the predicate.
58
58
  *
59
+ * For `contains` and `not_contains`, an object `V` matches an object entry
60
+ * that carries every key of `V` with an equal value; the entry may carry
61
+ * other keys.
62
+ *
63
+ * An `any_of` predicate tests several paths, so it has no single `actual`
64
+ * value: this function throws a `TypeError` for one. Evaluate it with
65
+ * `evaluateCapabilityPredicateAgainstCapabilities`.
66
+ *
59
67
  * Exported for direct testing so the predicate semantics are pinned without
60
68
  * needing a full runStoryboard() roundtrip.
61
69
  */
62
70
  export declare function evaluateCapabilityPredicate(predicate: RequiresCapabilityPredicate, actual: unknown): string | null;
71
+ /** Type guard for the OR-composed `any_of` capability predicate. */
72
+ export declare function isAnyOfCapabilityPredicate(predicate: RequiresCapabilityPredicate): predicate is AnyOfCapabilityPredicate;
73
+ /**
74
+ * Every path predicate a capability gate tests, flattening `any_of` groups.
75
+ * Consumers that key on predicate paths (for example the compliance rollup's
76
+ * `compliance_testing` exclusion) read this instead of `predicate.path`.
77
+ */
78
+ export declare function capabilityPathPredicates(predicate: RequiresCapabilityPredicate): CapabilityPathPredicate[];
79
+ /**
80
+ * Evaluate a capability predicate, including `any_of` groups, against a raw
81
+ * `get_adcp_capabilities` response. Returns `null` when the predicate is
82
+ * satisfied and a human-readable detail otherwise. Path predicates resolve
83
+ * schema defaults on the same terms as the runner's gates.
84
+ */
85
+ export declare function evaluateCapabilityPredicateAgainstCapabilities(predicate: RequiresCapabilityPredicate, rawCapabilities: unknown, adcpVersion?: string): string | null;
63
86
  /**
64
87
  * Every root applicability predicate a storyboard authors, across
65
88
  * `requires_capability` and `requires_all_capabilities`. Exported so the