@adcp/sdk 17.0.0-beta.13 → 17.0.0-beta.16

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 (70) hide show
  1. package/dist/lib/brand/index.d.mts +2 -0
  2. package/dist/lib/brand/index.d.ts +2 -0
  3. package/dist/lib/brand/index.js +3 -0
  4. package/dist/lib/brand/index.mjs +2 -0
  5. package/dist/lib/brand/selection.d.mts +13 -0
  6. package/dist/lib/brand/selection.d.ts +13 -0
  7. package/dist/lib/brand/selection.js +83 -0
  8. package/dist/lib/brand/selection.mjs +59 -0
  9. package/dist/lib/index.d.mts +2 -2
  10. package/dist/lib/index.d.ts +2 -2
  11. package/dist/lib/index.js +2 -0
  12. package/dist/lib/index.mjs +2 -0
  13. package/dist/lib/registry/types.d.mts +5 -0
  14. package/dist/lib/registry/types.d.ts +5 -0
  15. package/dist/lib/registry/types.generated.d.ts +4 -0
  16. package/dist/lib/server/decisioning/runtime/from-platform.js +12 -2
  17. package/dist/lib/server/decisioning/runtime/from-platform.mjs +12 -2
  18. package/dist/lib/server/test-controller.d.mts +9 -35
  19. package/dist/lib/server/test-controller.d.ts +9 -35
  20. package/dist/lib/server/test-controller.js +4 -0
  21. package/dist/lib/server/test-controller.mjs +4 -0
  22. package/dist/lib/testing/comply-controller.d.mts +7 -10
  23. package/dist/lib/testing/comply-controller.d.ts +7 -10
  24. package/dist/lib/testing/reporting/doctor.js +2 -1
  25. package/dist/lib/testing/reporting/doctor.mjs +2 -1
  26. package/dist/lib/testing/storyboard/account-policy.d.mts +42 -0
  27. package/dist/lib/testing/storyboard/account-policy.d.ts +42 -0
  28. package/dist/lib/testing/storyboard/account-policy.js +41 -2
  29. package/dist/lib/testing/storyboard/account-policy.mjs +38 -1
  30. package/dist/lib/testing/storyboard/path.d.mts +6 -0
  31. package/dist/lib/testing/storyboard/path.d.ts +6 -0
  32. package/dist/lib/testing/storyboard/path.js +22 -0
  33. package/dist/lib/testing/storyboard/path.mjs +21 -0
  34. package/dist/lib/testing/storyboard/request-builder.js +1 -1
  35. package/dist/lib/testing/storyboard/request-builder.mjs +1 -1
  36. package/dist/lib/testing/storyboard/runner-owned-task.d.mts +3 -0
  37. package/dist/lib/testing/storyboard/runner-owned-task.d.ts +3 -0
  38. package/dist/lib/testing/storyboard/runner-owned-task.js +38 -0
  39. package/dist/lib/testing/storyboard/runner-owned-task.mjs +13 -0
  40. package/dist/lib/testing/storyboard/runner.d.mts +1 -42
  41. package/dist/lib/testing/storyboard/runner.d.ts +1 -42
  42. package/dist/lib/testing/storyboard/runner.js +14 -47
  43. package/dist/lib/testing/storyboard/runner.mjs +6 -39
  44. package/dist/lib/testing/storyboard/seeding.js +169 -2
  45. package/dist/lib/testing/storyboard/seeding.mjs +169 -2
  46. package/dist/lib/testing/storyboard/types.d.mts +4 -2
  47. package/dist/lib/testing/storyboard/types.d.ts +4 -2
  48. package/dist/lib/testing/storyboard/types.js +1 -0
  49. package/dist/lib/testing/storyboard/types.mjs +1 -0
  50. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  51. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  52. package/dist/lib/testing/storyboard/validations.js +60 -1
  53. package/dist/lib/testing/storyboard/validations.mjs +61 -1
  54. package/dist/lib/testing/storyboard/webhook-assertions.js +10 -9
  55. package/dist/lib/testing/storyboard/webhook-assertions.mjs +11 -10
  56. package/dist/lib/v2/projection/creative-delivery.js +62 -16
  57. package/dist/lib/v2/projection/creative-delivery.mjs +62 -16
  58. package/dist/lib/version.d.mts +3 -3
  59. package/dist/lib/version.d.ts +3 -3
  60. package/dist/lib/version.js +3 -3
  61. package/dist/lib/version.mjs +3 -3
  62. package/docs/TYPE-SUMMARY.md +1 -1
  63. package/docs/guides/BRAND-ENTRY-SELECTION.md +56 -0
  64. package/docs/guides/REPORTING-LEDGER.md +142 -12
  65. package/docs/guides/REPORTING-OPERATIONS.md +18 -5
  66. package/docs/guides/VALIDATE-YOUR-AGENT.md +44 -0
  67. package/docs/llms.txt +1 -1
  68. package/docs/migration-14.x-rc-worksheet.md +4 -4
  69. package/docs/migration-reporting-row-storage-alignment.md +4 -2
  70. package/package.json +1 -1
@@ -16,9 +16,164 @@ import {
16
16
  } from "./fixture-resolution.mjs";
17
17
  import { readCollectionWitness } from "./collection-selection.mjs";
18
18
  import { resolvePath } from "./path.mjs";
19
+ import { injectContext, applyContextInputs } from "./context.mjs";
20
+ import { applyBrandInvariant } from "./account-policy.mjs";
21
+ import { isRunnerOwnedTask } from "./runner-owned-task.mjs";
19
22
  import { redactSecrets } from "../../utils/redact-secrets.mjs";
23
+ import { canonicalize } from "../../utils/jcs.mjs";
20
24
  import { redactDiscoveryEvidence as redactDiscoveryResponse } from "../discovery-evidence.mjs";
21
25
  import { redactCredentialPatterns } from "../../utils/redact-credential-patterns.mjs";
26
+ function storyboardSeedScope(storyboard, context, options, call) {
27
+ if (call.scenario !== "seed_product" && call.scenario !== "seed_pricing_option") return {};
28
+ if (context.account !== void 0) {
29
+ if (!isPlainRecord(context.account) || /\$(?:context\.|generate:)/.test(JSON.stringify(context.account))) {
30
+ throw new Error("Automatic fixture seeding needs a resolved context.account reference");
31
+ }
32
+ if (context.account.sandbox === false) throw new Error("Automatic fixture seeding requires a sandbox account");
33
+ if (typeof context.account.account_id !== "string" && (options.brand || options.brand_manifest) && canonicalize(context.account.brand) !== canonicalize(resolveBrand(options))) {
34
+ throw new Error(
35
+ "Explicit fixture context.account conflicts with the run-scoped brand; choose one account identity"
36
+ );
37
+ }
38
+ return {
39
+ account: { ...context.account, sandbox: true }
40
+ };
41
+ }
42
+ const provisioningAliases = /* @__PURE__ */ new Map();
43
+ const provisioningAccounts = [];
44
+ for (const phase of storyboard.phases)
45
+ for (const step of phase.steps) {
46
+ if (step.task !== "sync_accounts" || step.expect_error) continue;
47
+ const request = injectContext(step.sample_request ?? {}, context);
48
+ if (!Array.isArray(request.accounts) || request.accounts.length !== 1) continue;
49
+ const row = request.accounts[0];
50
+ if (!isPlainRecord(row) || !isPlainRecord(row.brand) || typeof row.operator !== "string") continue;
51
+ const { brand, operator, operator_unit, currency, timezone, sandbox } = row;
52
+ const account = {
53
+ brand,
54
+ operator,
55
+ ...operator_unit !== void 0 && { operator_unit },
56
+ ...currency !== void 0 && { currency },
57
+ ...timezone !== void 0 && { timezone },
58
+ ...sandbox !== void 0 && { sandbox }
59
+ };
60
+ provisioningAccounts.push(account);
61
+ for (const output of step.context_outputs ?? []) {
62
+ if (output.path === "accounts[0].account_id" && output.key) provisioningAliases.set(output.key, account);
63
+ }
64
+ }
65
+ const accounts = /* @__PURE__ */ new Map();
66
+ const resolvedScopes = /* @__PURE__ */ new Set();
67
+ const deferredScopes = /* @__PURE__ */ new Set();
68
+ const seedScopeSteps = [
69
+ ...storyboard.phases.flatMap((phase) => phase.steps),
70
+ ...provisioningAccounts.map((account, index) => ({
71
+ id: `seed-scope-${index}`,
72
+ title: "Seed scope from account provisioning",
73
+ task: "sync_accounts",
74
+ sample_request: { account }
75
+ }))
76
+ ];
77
+ for (const authoredStep of seedScopeSteps) {
78
+ const step = authoredStep.task === "expect_rate_limit_not_replayed" && authoredStep.rate_limit_trip ? {
79
+ ...authoredStep,
80
+ task: authoredStep.rate_limit_trip.trip_target_task,
81
+ sample_request: authoredStep.rate_limit_trip.trip_target_sample_request
82
+ } : authoredStep;
83
+ if (isRunnerOwnedTask(step.task)) continue;
84
+ if (step.expect_error || step.omit_account) continue;
85
+ const source = options.request ?? step.sample_request ?? {};
86
+ if (JSON.stringify(source.account ?? {}).includes("$generate:")) {
87
+ throw new Error("Automatic fixture seeding needs an explicit resolved account for generated identities");
88
+ }
89
+ let request = injectContext(
90
+ {
91
+ ...source.account !== void 0 && { account: source.account },
92
+ buying_mode: source.buying_mode,
93
+ discovery_mode: source.discovery_mode,
94
+ ...step.task === "validate_input" && { targets: source.targets },
95
+ ...step.task === "comply_test_controller" && { scenario: source.scenario }
96
+ },
97
+ context
98
+ );
99
+ if (step.context_inputs?.length) request = applyContextInputs(request, step.context_inputs, context);
100
+ const formatOnlyValidation = step.task === "validate_input" && Array.isArray(request.targets) && request.targets.length > 0 && request.targets.every(
101
+ (target) => isPlainRecord(target) && ["canonical", "third_party_format", "capability"].includes(String(target.kind))
102
+ );
103
+ const controllerMetadata = step.task === "comply_test_controller" && request.scenario === "list_scenarios";
104
+ if (request.account === void 0 && (controllerMetadata || formatOnlyValidation)) continue;
105
+ if (request.account === void 0 && step.task === "comply_test_controller") {
106
+ request.account = { ...resolveAccount(options), sandbox: true };
107
+ }
108
+ request = applyBrandInvariant(request, options, step.task, { omit_account: step.omit_account });
109
+ if (request.account === void 0) continue;
110
+ if (JSON.stringify(request.account).includes("$generate:")) {
111
+ throw new Error("Automatic fixture seeding needs an explicit resolved account for generated identities");
112
+ }
113
+ let injected = request.account;
114
+ if (isPlainRecord(injected) && typeof injected.account_id === "string") {
115
+ const capture = /^\$context\.(\w+)$/.exec(injected.account_id)?.[1];
116
+ if (capture && provisioningAliases.has(capture)) injected = provisioningAliases.get(capture);
117
+ }
118
+ if (!isPlainRecord(injected)) throw new Error("Automatic fixture seeding needs a resolved account reference");
119
+ const account = { ...injected };
120
+ let deferred = false;
121
+ for (const key2 of ["currency", "timezone"]) {
122
+ if (typeof account[key2] === "string" && /^\$context\./.test(account[key2])) {
123
+ delete account[key2];
124
+ deferred = true;
125
+ }
126
+ }
127
+ if (JSON.stringify(account).includes("$context.")) {
128
+ throw new Error("Automatic fixture seeding needs a resolved account reference");
129
+ }
130
+ const hasIdentity = typeof account.account_id === "string" && account.account_id.length > 0 || isPlainRecord(account.brand) && typeof account.brand.domain === "string" && account.brand.domain.length > 0 && typeof account.operator === "string" && account.operator.length > 0;
131
+ if (!hasIdentity) continue;
132
+ if (account.sandbox === false) throw new Error("Automatic fixture seeding requires a sandbox account");
133
+ const sandboxAccount = { ...account, sandbox: true };
134
+ const { currency: _currency, timezone: _timezone, ...identity } = sandboxAccount;
135
+ const key = canonicalize(identity);
136
+ (deferred ? deferredScopes : resolvedScopes).add(key);
137
+ const prior = accounts.get(key);
138
+ if (prior) {
139
+ for (const dimension of ["currency", "timezone"]) {
140
+ if (prior[dimension] !== void 0 && sandboxAccount[dimension] !== void 0 && prior[dimension] !== sandboxAccount[dimension]) {
141
+ throw new Error(
142
+ "Automatic fixture seeding needs an explicit context.account when a storyboard uses multiple accounts"
143
+ );
144
+ }
145
+ }
146
+ }
147
+ accounts.set(key, { ...prior, ...sandboxAccount });
148
+ }
149
+ if ([...deferredScopes].some((key) => !resolvedScopes.has(key))) {
150
+ throw new Error("Automatic fixture seeding needs a resolved account reference before later account enrichment");
151
+ }
152
+ if (accounts.size === 1) return { account: [...accounts.values()][0] };
153
+ if (accounts.size > 1) {
154
+ throw new Error(
155
+ "Automatic fixture seeding needs an explicit context.account when a storyboard uses multiple accounts"
156
+ );
157
+ }
158
+ const sandboxAccounts = (storyboard.fixtures?.accounts ?? []).flatMap((entry) => {
159
+ const fixture = isPlainRecord(entry.fixture) ? entry.fixture : entry;
160
+ if (fixture.sandbox !== true || !isPlainRecord(fixture.brand) || typeof fixture.operator !== "string") return [];
161
+ const { brand, operator, operator_unit, currency, timezone } = fixture;
162
+ return [
163
+ {
164
+ brand,
165
+ operator,
166
+ ...operator_unit !== void 0 && { operator_unit },
167
+ ...currency !== void 0 && { currency },
168
+ ...timezone !== void 0 && { timezone },
169
+ sandbox: true
170
+ }
171
+ ];
172
+ });
173
+ if (sandboxAccounts.length === 1) return { account: sandboxAccounts[0] };
174
+ if (sandboxAccounts.length > 1) throw new Error("Automatic fixture seeding needs an explicit context.account");
175
+ return {};
176
+ }
22
177
  const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
23
178
  function buildSeedCalls(fixtures) {
24
179
  if (!fixtures) return [];
@@ -247,7 +402,12 @@ async function runControllerSeeding(client, storyboard, options, context, discov
247
402
  try {
248
403
  const raw = await callControllerRaw(
249
404
  client,
250
- { scenario: call.scenario, params: call.params, context: seedContext },
405
+ {
406
+ ...storyboardSeedScope(storyboard, context, options, call),
407
+ scenario: call.scenario,
408
+ params: call.params,
409
+ context: seedContext
410
+ },
251
411
  options
252
412
  );
253
413
  const data = raw.data;
@@ -540,6 +700,7 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
540
700
  const raw = await callControllerRaw(
541
701
  seedClient,
542
702
  {
703
+ ...storyboardSeedScope(storyboard, context, seedOptions, call),
543
704
  scenario: call.scenario,
544
705
  params: isPlainRecord(controllerRequest.params) ? controllerRequest.params : call.params,
545
706
  context: seedContext
@@ -570,6 +731,7 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
570
731
  // `call.params` when the bound params are not a plain
571
732
  // record, and adds the seeding correlation context.
572
733
  payload: redactSecrets({
734
+ ...storyboardSeedScope(storyboard, context, seedOptions, call),
573
735
  scenario: call.scenario,
574
736
  params: isPlainRecord(controllerRequest.params) ? controllerRequest.params : call.params,
575
737
  context: seedContext
@@ -936,7 +1098,12 @@ async function executeLegacySeedCall(client, storyboard, call, options, context,
936
1098
  try {
937
1099
  const raw = await callControllerRaw(
938
1100
  client,
939
- { scenario: call.scenario, params: call.params, context: seedContext },
1101
+ {
1102
+ ...storyboardSeedScope(storyboard, context, options, call),
1103
+ scenario: call.scenario,
1104
+ params: call.params,
1105
+ context: seedContext
1106
+ },
940
1107
  options
941
1108
  );
942
1109
  const data = raw.data;
@@ -90,6 +90,8 @@ export interface Storyboard {
90
90
  * not actually present.
91
91
  * - `collect_product_pages_runner` — intrinsic support for explicit wholesale
92
92
  * all-page steps; unavailable on older runners that ignore this metadata.
93
+ * - `field_excludes_runner` — intrinsic full-response negative membership support;
94
+ * older runners skip before seeding instead of ignoring an unknown check.
93
95
  * - `real_wire` — always available. Tag scenarios that observe
94
96
  * production behavior with this when you want them excluded from
95
97
  * a future `--mock-only` mode; today the tag is a no-op gate.
@@ -1017,7 +1019,7 @@ export type StoryboardValidationCheck = 'response_schema' | 'field_present'
1017
1019
  * envelope fields such as `adcp_major_version` should use
1018
1020
  * `envelope_field_value`.
1019
1021
  */
1020
- | 'envelope_field_pattern' | 'field_contains' | 'status_code' | 'error_code' | 'http_status' | 'http_status_in' | 'on_401_require_header'
1022
+ | 'envelope_field_pattern' | 'field_contains' | 'field_excludes' | 'status_code' | 'error_code' | 'http_status' | 'http_status_in' | 'on_401_require_header'
1021
1023
  /**
1022
1024
  * Assert that the step's probe reported no grading error, without asserting
1023
1025
  * anything about an HTTP exchange. For probes whose verdict is decided
@@ -2415,7 +2417,7 @@ export interface RunnerSelectionResult {
2415
2417
  *
2416
2418
  * Spec: adcp-client#1626, adcp-client#2281, adcp-client#2356.
2417
2419
  */
2418
- export type RequirementName = 'controller' | 'collect_product_pages_runner' | 'seeded_state' | 'real_wire' | 'webhook_receiver' | 'webhook_replay_receiver' | 'trusted_match_context_router_runner' | 'trusted_match_publisher_auth_runner' | 'property_list_reference_runner' | 'request_signer' | 'multi_agent';
2420
+ export type RequirementName = 'controller' | 'collect_product_pages_runner' | 'field_excludes_runner' | 'seeded_state' | 'real_wire' | 'webhook_receiver' | 'webhook_replay_receiver' | 'trusted_match_context_router_runner' | 'trusted_match_publisher_auth_runner' | 'property_list_reference_runner' | 'request_signer' | 'multi_agent';
2419
2421
  /**
2420
2422
  * Enumeration of every requirement this SDK knows how to satisfy. The loader
2421
2423
  * accepts other non-empty strings for forward compatibility; the runner treats
@@ -90,6 +90,8 @@ export interface Storyboard {
90
90
  * not actually present.
91
91
  * - `collect_product_pages_runner` — intrinsic support for explicit wholesale
92
92
  * all-page steps; unavailable on older runners that ignore this metadata.
93
+ * - `field_excludes_runner` — intrinsic full-response negative membership support;
94
+ * older runners skip before seeding instead of ignoring an unknown check.
93
95
  * - `real_wire` — always available. Tag scenarios that observe
94
96
  * production behavior with this when you want them excluded from
95
97
  * a future `--mock-only` mode; today the tag is a no-op gate.
@@ -1017,7 +1019,7 @@ export type StoryboardValidationCheck = 'response_schema' | 'field_present'
1017
1019
  * envelope fields such as `adcp_major_version` should use
1018
1020
  * `envelope_field_value`.
1019
1021
  */
1020
- | 'envelope_field_pattern' | 'field_contains' | 'status_code' | 'error_code' | 'http_status' | 'http_status_in' | 'on_401_require_header'
1022
+ | 'envelope_field_pattern' | 'field_contains' | 'field_excludes' | 'status_code' | 'error_code' | 'http_status' | 'http_status_in' | 'on_401_require_header'
1021
1023
  /**
1022
1024
  * Assert that the step's probe reported no grading error, without asserting
1023
1025
  * anything about an HTTP exchange. For probes whose verdict is decided
@@ -2415,7 +2417,7 @@ export interface RunnerSelectionResult {
2415
2417
  *
2416
2418
  * Spec: adcp-client#1626, adcp-client#2281, adcp-client#2356.
2417
2419
  */
2418
- export type RequirementName = 'controller' | 'collect_product_pages_runner' | 'seeded_state' | 'real_wire' | 'webhook_receiver' | 'webhook_replay_receiver' | 'trusted_match_context_router_runner' | 'trusted_match_publisher_auth_runner' | 'property_list_reference_runner' | 'request_signer' | 'multi_agent';
2420
+ export type RequirementName = 'controller' | 'collect_product_pages_runner' | 'field_excludes_runner' | 'seeded_state' | 'real_wire' | 'webhook_receiver' | 'webhook_replay_receiver' | 'trusted_match_context_router_runner' | 'trusted_match_publisher_auth_runner' | 'property_list_reference_runner' | 'request_signer' | 'multi_agent';
2419
2421
  /**
2420
2422
  * Enumeration of every requirement this SDK knows how to satisfy. The loader
2421
2423
  * accepts other non-empty strings for forward compatibility; the runner treats
@@ -63,6 +63,7 @@ const DETAILED_SKIP_TO_CANONICAL = {
63
63
  const KNOWN_REQUIREMENTS = /* @__PURE__ */ new Set([
64
64
  "controller",
65
65
  "collect_product_pages_runner",
66
+ "field_excludes_runner",
66
67
  "seeded_state",
67
68
  "real_wire",
68
69
  "webhook_receiver",
@@ -37,6 +37,7 @@ const DETAILED_SKIP_TO_CANONICAL = {
37
37
  const KNOWN_REQUIREMENTS = /* @__PURE__ */ new Set([
38
38
  "controller",
39
39
  "collect_product_pages_runner",
40
+ "field_excludes_runner",
40
41
  "seeded_state",
41
42
  "real_wire",
42
43
  "webhook_receiver",
@@ -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.13";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.16";
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.13";
203
+ export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.16";
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
  /**
@@ -108,6 +108,7 @@ function runValidation(validation, ctx) {
108
108
  return validateFieldValueOrAbsent(validation, resolveTarget(ctx));
109
109
  case "field_pattern":
110
110
  return validateFieldPattern(validation, resolveTarget(ctx));
111
+ case "field_excludes":
111
112
  case "field_contains":
112
113
  return validateFieldContains(validation, resolveTarget(ctx));
113
114
  case "status_code":
@@ -970,7 +971,7 @@ function validateFieldPattern(validation, taskResult) {
970
971
  }
971
972
  function validateFieldContains(validation, taskResult) {
972
973
  const checkName = validation.check;
973
- if (!validation.path) {
974
+ if (typeof validation.path !== "string" || !validation.path) {
974
975
  return {
975
976
  check: checkName,
976
977
  passed: false,
@@ -982,6 +983,18 @@ function validateFieldContains(validation, taskResult) {
982
983
  actual: null
983
984
  };
984
985
  }
986
+ if (validation.allowed_values !== void 0 && !Array.isArray(validation.allowed_values)) {
987
+ return {
988
+ check: checkName,
989
+ passed: false,
990
+ description: validation.description,
991
+ path: validation.path,
992
+ json_pointer: (0, import_path.toJsonPointer)(validation.path),
993
+ error: `${checkName} allowed_values must be an array`,
994
+ expected: "an array of values",
995
+ actual: validation.allowed_values
996
+ };
997
+ }
985
998
  if (validation.value === void 0 && !validation.allowed_values?.length) {
986
999
  return {
987
1000
  check: checkName,
@@ -994,6 +1007,9 @@ function validateFieldContains(validation, taskResult) {
994
1007
  actual: null
995
1008
  };
996
1009
  }
1010
+ if (checkName === "field_excludes") {
1011
+ return validateFieldExcludes(validation, taskResult);
1012
+ }
997
1013
  const resolved = (0, import_path.resolvePathAll)(taskResult.data, validation.path);
998
1014
  const pointer = (0, import_path.toJsonPointer)(validation.path);
999
1015
  const candidates = validation.allowed_values?.length ? validation.allowed_values : [validation.value];
@@ -1021,6 +1037,49 @@ function validateFieldContains(validation, taskResult) {
1021
1037
  actual: resolved
1022
1038
  };
1023
1039
  }
1040
+ function validateFieldExcludes(validation, taskResult) {
1041
+ const path = validation.path;
1042
+ const candidates = validation.allowed_values?.length ? validation.allowed_values : [validation.value];
1043
+ const expected = { excludes: validation.allowed_values?.length ? validation.allowed_values : validation.value };
1044
+ const base = {
1045
+ check: validation.check,
1046
+ description: validation.description,
1047
+ path,
1048
+ json_pointer: (0, import_path.toJsonPointer)(path)
1049
+ };
1050
+ const unresolvedContext = (value) => {
1051
+ if (typeof value === "string") return /^\$context\./.test(value);
1052
+ if (Array.isArray(value)) return value.some(unresolvedContext);
1053
+ return value !== null && typeof value === "object" && Object.values(value).some(unresolvedContext);
1054
+ };
1055
+ if (candidates.some(unresolvedContext)) {
1056
+ return {
1057
+ ...base,
1058
+ passed: false,
1059
+ error: "field_excludes comparator contains an unresolved context reference",
1060
+ expected: "a resolved value or allowed_values comparator",
1061
+ actual: candidates
1062
+ };
1063
+ }
1064
+ if (path.length > 1024 || !/^[^.[\]]+(?:\[(?:\d+|\*)?\]|\.[^.[\]]+)*$/.test(path) || (0, import_path.parsePathWithWildcards)(path).some(
1065
+ (segment) => typeof segment === "string" && ["__proto__", "constructor", "prototype"].includes(segment)
1066
+ )) {
1067
+ return {
1068
+ ...base,
1069
+ passed: false,
1070
+ error: "Invalid field_excludes path",
1071
+ expected: "a valid safe storyboard path",
1072
+ actual: path
1073
+ };
1074
+ }
1075
+ const comparisonKey = comparisonKeyFromPath(path);
1076
+ for (const actual of (0, import_path.iteratePathAll)(taskResult.data, path)) {
1077
+ if (candidates.some((candidate) => containsValueMatches(actual, candidate, comparisonKey))) {
1078
+ return { ...base, passed: false, error: `Prohibited value found at ${path}`, expected, actual: [actual] };
1079
+ }
1080
+ }
1081
+ return { ...base, passed: true };
1082
+ }
1024
1083
  function validateArrayLength(validation, taskResult) {
1025
1084
  const checkName = "array_length";
1026
1085
  if (!validation.path) {
@@ -18,6 +18,7 @@ import {
18
18
  parsePathWithWildcards,
19
19
  resolvePath,
20
20
  resolvePathAll,
21
+ iteratePathAll,
21
22
  resolvePortableIdentifierPathAll,
22
23
  toJsonPointer,
23
24
  validatePortableIdentifierPath,
@@ -89,6 +90,7 @@ function runValidation(validation, ctx) {
89
90
  return validateFieldValueOrAbsent(validation, resolveTarget(ctx));
90
91
  case "field_pattern":
91
92
  return validateFieldPattern(validation, resolveTarget(ctx));
93
+ case "field_excludes":
92
94
  case "field_contains":
93
95
  return validateFieldContains(validation, resolveTarget(ctx));
94
96
  case "status_code":
@@ -952,7 +954,7 @@ function validateFieldPattern(validation, taskResult) {
952
954
  }
953
955
  function validateFieldContains(validation, taskResult) {
954
956
  const checkName = validation.check;
955
- if (!validation.path) {
957
+ if (typeof validation.path !== "string" || !validation.path) {
956
958
  return {
957
959
  check: checkName,
958
960
  passed: false,
@@ -964,6 +966,18 @@ function validateFieldContains(validation, taskResult) {
964
966
  actual: null
965
967
  };
966
968
  }
969
+ if (validation.allowed_values !== void 0 && !Array.isArray(validation.allowed_values)) {
970
+ return {
971
+ check: checkName,
972
+ passed: false,
973
+ description: validation.description,
974
+ path: validation.path,
975
+ json_pointer: toJsonPointer(validation.path),
976
+ error: `${checkName} allowed_values must be an array`,
977
+ expected: "an array of values",
978
+ actual: validation.allowed_values
979
+ };
980
+ }
967
981
  if (validation.value === void 0 && !validation.allowed_values?.length) {
968
982
  return {
969
983
  check: checkName,
@@ -976,6 +990,9 @@ function validateFieldContains(validation, taskResult) {
976
990
  actual: null
977
991
  };
978
992
  }
993
+ if (checkName === "field_excludes") {
994
+ return validateFieldExcludes(validation, taskResult);
995
+ }
979
996
  const resolved = resolvePathAll(taskResult.data, validation.path);
980
997
  const pointer = toJsonPointer(validation.path);
981
998
  const candidates = validation.allowed_values?.length ? validation.allowed_values : [validation.value];
@@ -1003,6 +1020,49 @@ function validateFieldContains(validation, taskResult) {
1003
1020
  actual: resolved
1004
1021
  };
1005
1022
  }
1023
+ function validateFieldExcludes(validation, taskResult) {
1024
+ const path = validation.path;
1025
+ const candidates = validation.allowed_values?.length ? validation.allowed_values : [validation.value];
1026
+ const expected = { excludes: validation.allowed_values?.length ? validation.allowed_values : validation.value };
1027
+ const base = {
1028
+ check: validation.check,
1029
+ description: validation.description,
1030
+ path,
1031
+ json_pointer: toJsonPointer(path)
1032
+ };
1033
+ const unresolvedContext = (value) => {
1034
+ if (typeof value === "string") return /^\$context\./.test(value);
1035
+ if (Array.isArray(value)) return value.some(unresolvedContext);
1036
+ return value !== null && typeof value === "object" && Object.values(value).some(unresolvedContext);
1037
+ };
1038
+ if (candidates.some(unresolvedContext)) {
1039
+ return {
1040
+ ...base,
1041
+ passed: false,
1042
+ error: "field_excludes comparator contains an unresolved context reference",
1043
+ expected: "a resolved value or allowed_values comparator",
1044
+ actual: candidates
1045
+ };
1046
+ }
1047
+ if (path.length > 1024 || !/^[^.[\]]+(?:\[(?:\d+|\*)?\]|\.[^.[\]]+)*$/.test(path) || parsePathWithWildcards(path).some(
1048
+ (segment) => typeof segment === "string" && ["__proto__", "constructor", "prototype"].includes(segment)
1049
+ )) {
1050
+ return {
1051
+ ...base,
1052
+ passed: false,
1053
+ error: "Invalid field_excludes path",
1054
+ expected: "a valid safe storyboard path",
1055
+ actual: path
1056
+ };
1057
+ }
1058
+ const comparisonKey = comparisonKeyFromPath(path);
1059
+ for (const actual of iteratePathAll(taskResult.data, path)) {
1060
+ if (candidates.some((candidate) => containsValueMatches(actual, candidate, comparisonKey))) {
1061
+ return { ...base, passed: false, error: `Prohibited value found at ${path}`, expected, actual: [actual] };
1062
+ }
1063
+ }
1064
+ return { ...base, passed: true };
1065
+ }
1006
1066
  function validateArrayLength(validation, taskResult) {
1007
1067
  const checkName = "array_length";
1008
1068
  if (!validation.path) {
@@ -362,7 +362,7 @@ async function executeWebhookAssertionStep(step, phaseId, context, allSteps, opt
362
362
  } else
363
363
  switch (step.task) {
364
364
  case "expect_webhook": {
365
- const outcome = await runExpectWebhook(step, filter, receiver);
365
+ const outcome = await runExpectWebhook(step, filter, receiver, options.adcpVersion ?? import_version.ADCP_VERSION);
366
366
  validations = outcome.validations;
367
367
  passed = outcome.passed;
368
368
  let changeKey;
@@ -523,7 +523,7 @@ async function runExpectNoWebhook(step, filter, receiver) {
523
523
  passed: true
524
524
  };
525
525
  }
526
- async function runExpectWebhook(step, filter, receiver) {
526
+ async function runExpectWebhook(step, filter, receiver, adcpVersion) {
527
527
  const timeoutMs = clampTimeoutSeconds(step.timeout_seconds, DEFAULT_TIMEOUT_SECONDS) * 1e3;
528
528
  const checkIdempotency = step.expect_idempotency_key !== false;
529
529
  const capCount = step.expect_max_deliveries_per_logical_event;
@@ -553,7 +553,7 @@ async function runExpectWebhook(step, filter, receiver) {
553
553
  first.raw_body.slice(0, 256)
554
554
  );
555
555
  }
556
- const schemaCheck = validateWebhookPayloadSchema(step, first);
556
+ const schemaCheck = validateWebhookPayloadSchema(step, first, adcpVersion);
557
557
  if (schemaCheck && !schemaCheck.passed) return { validations: [schemaCheck], passed: false };
558
558
  if (checkIdempotency) {
559
559
  const idempotencyCheck = assertIdempotencyKey(first);
@@ -759,11 +759,11 @@ function mapSignatureErrorCode(code) {
759
759
  }
760
760
  }
761
761
  }
762
- function validateWebhookPayloadSchema(step, webhook) {
762
+ function validateWebhookPayloadSchema(step, webhook, adcpVersion) {
763
763
  const schemaRef = step.webhook_payload_schema_ref ?? step.response_schema_webhook_ref;
764
764
  if (!schemaRef) return void 0;
765
- const { schema_id, schema_url } = resolveWebhookSchemaIdentity(schemaRef);
766
- const validator = (0, import_schema_loader.getSchemaValidatorByRef)(schemaRef);
765
+ const { schema_id, schema_url } = resolveWebhookSchemaIdentity(schemaRef, adcpVersion);
766
+ const validator = (0, import_schema_loader.getSchemaValidatorByRef)(schemaRef, adcpVersion);
767
767
  if (!validator) {
768
768
  return {
769
769
  check: "expect_webhook",
@@ -818,9 +818,10 @@ function validateWebhookPayloadSchema(step, webhook) {
818
818
  schema_url
819
819
  };
820
820
  }
821
- function resolveWebhookSchemaIdentity(schemaRef) {
822
- const trimmed = schemaRef.replace(/^\/+/, "");
823
- const schemaId = `/schemas/${import_version.ADCP_VERSION}/${trimmed}`;
821
+ function resolveWebhookSchemaIdentity(schemaRef, adcpVersion) {
822
+ const document = (0, import_schema_loader.getSchemaDocumentByRef)(schemaRef, adcpVersion);
823
+ const ref = document?.schemaRef ?? schemaRef.replace(/^\/+/, "");
824
+ const schemaId = `/schemas/${document?.resolvedVersion ?? adcpVersion}/${ref}`;
824
825
  return { schema_id: schemaId, schema_url: `${SCHEMA_URL_BASE}${schemaId}` };
825
826
  }
826
827
  function ajvErrorToSchemaError(error) {
@@ -7,7 +7,7 @@ import { verifyWebhookSignature } from "../../signing/webhook-verifier.mjs";
7
7
  import { WebhookSignatureError } from "../../signing/errors.mjs";
8
8
  import { InMemoryReplayStore } from "../../signing/replay.mjs";
9
9
  import { InMemoryRevocationStore } from "../../signing/revocation.mjs";
10
- import { getSchemaValidatorByRef } from "../../validation/schema-loader.mjs";
10
+ import { getSchemaDocumentByRef, getSchemaValidatorByRef } from "../../validation/schema-loader.mjs";
11
11
  import { ADCP_VERSION } from "../../version.mjs";
12
12
  import { ConfigurationError } from "../../errors/index.mjs";
13
13
  const RUN_STATE_REPLAY_KEY = "__webhook_signing_replay_store";
@@ -337,7 +337,7 @@ async function executeWebhookAssertionStep(step, phaseId, context, allSteps, opt
337
337
  } else
338
338
  switch (step.task) {
339
339
  case "expect_webhook": {
340
- const outcome = await runExpectWebhook(step, filter, receiver);
340
+ const outcome = await runExpectWebhook(step, filter, receiver, options.adcpVersion ?? ADCP_VERSION);
341
341
  validations = outcome.validations;
342
342
  passed = outcome.passed;
343
343
  let changeKey;
@@ -498,7 +498,7 @@ async function runExpectNoWebhook(step, filter, receiver) {
498
498
  passed: true
499
499
  };
500
500
  }
501
- async function runExpectWebhook(step, filter, receiver) {
501
+ async function runExpectWebhook(step, filter, receiver, adcpVersion) {
502
502
  const timeoutMs = clampTimeoutSeconds(step.timeout_seconds, DEFAULT_TIMEOUT_SECONDS) * 1e3;
503
503
  const checkIdempotency = step.expect_idempotency_key !== false;
504
504
  const capCount = step.expect_max_deliveries_per_logical_event;
@@ -528,7 +528,7 @@ async function runExpectWebhook(step, filter, receiver) {
528
528
  first.raw_body.slice(0, 256)
529
529
  );
530
530
  }
531
- const schemaCheck = validateWebhookPayloadSchema(step, first);
531
+ const schemaCheck = validateWebhookPayloadSchema(step, first, adcpVersion);
532
532
  if (schemaCheck && !schemaCheck.passed) return { validations: [schemaCheck], passed: false };
533
533
  if (checkIdempotency) {
534
534
  const idempotencyCheck = assertIdempotencyKey(first);
@@ -734,11 +734,11 @@ function mapSignatureErrorCode(code) {
734
734
  }
735
735
  }
736
736
  }
737
- function validateWebhookPayloadSchema(step, webhook) {
737
+ function validateWebhookPayloadSchema(step, webhook, adcpVersion) {
738
738
  const schemaRef = step.webhook_payload_schema_ref ?? step.response_schema_webhook_ref;
739
739
  if (!schemaRef) return void 0;
740
- const { schema_id, schema_url } = resolveWebhookSchemaIdentity(schemaRef);
741
- const validator = getSchemaValidatorByRef(schemaRef);
740
+ const { schema_id, schema_url } = resolveWebhookSchemaIdentity(schemaRef, adcpVersion);
741
+ const validator = getSchemaValidatorByRef(schemaRef, adcpVersion);
742
742
  if (!validator) {
743
743
  return {
744
744
  check: "expect_webhook",
@@ -793,9 +793,10 @@ function validateWebhookPayloadSchema(step, webhook) {
793
793
  schema_url
794
794
  };
795
795
  }
796
- function resolveWebhookSchemaIdentity(schemaRef) {
797
- const trimmed = schemaRef.replace(/^\/+/, "");
798
- const schemaId = `/schemas/${ADCP_VERSION}/${trimmed}`;
796
+ function resolveWebhookSchemaIdentity(schemaRef, adcpVersion) {
797
+ const document = getSchemaDocumentByRef(schemaRef, adcpVersion);
798
+ const ref = document?.schemaRef ?? schemaRef.replace(/^\/+/, "");
799
+ const schemaId = `/schemas/${document?.resolvedVersion ?? adcpVersion}/${ref}`;
799
800
  return { schema_id: schemaId, schema_url: `${SCHEMA_URL_BASE}${schemaId}` };
800
801
  }
801
802
  function ajvErrorToSchemaError(error) {