@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
@@ -131,7 +131,11 @@ service runs for you. See
131
131
  cannot hold the table indefinitely.
132
132
  5. **Warehouse sink.** Apply `REPORTING_WAREHOUSE_SINK_MIGRATION`, create the
133
133
  tables, and the `current_rows` view, then schedule `runOnce`. Point analysts
134
- at `current_rows`. Set the sink's `location` to the dataset's location: replay
134
+ at `current_rows`. The sink loads two tables per batch, rows first and then the
135
+ required revisions table that `current_rows` reads through, so rows can be
136
+ visible before their revision metadata and `current_rows` shows only revisions
137
+ whose metadata has loaded (`docs/guides/REPORTING-LEDGER.md`, "The two-table
138
+ contract"). Set the sink's `location` to the dataset's location: replay
135
139
  lookups of load jobs need it outside the US and EU multi-regions, and the sink
136
140
  warns once per process when it is unset. When upgrading from 15.9.0, stop
137
141
  every 15.9.0 sink worker before starting newer ones, then re-apply
@@ -180,10 +184,13 @@ service runs for you. See
180
184
  `minAgeSeconds` ago (default 7 days, never less than 1 day, which must stay
181
185
  well above the write deadline plus intent expiry); no row set that is not yet
182
186
  `pruned` has a chunk at that key and no write intent lists it, at any version;
183
- and, under the per-object advisory lock every other delete takes, no `live` or
184
- `unavailable` row set references that exact version and no open intent
185
- created it, checked under every binding because two bindings can share a
186
- bucket and prefix (a retired binding kept `readOnly` next to its successor).
187
+ and, under the per-object advisory lock (the only delete that takes it: a
188
+ commit that adopts an object its own intent did not record takes the same
189
+ lock, so the two cannot interleave), no `live` or `unavailable` row set
190
+ references that exact version and no open intent created it, checked under
191
+ every binding because two bindings can share a bucket and prefix (a retired
192
+ binding kept `readOnly` next to its successor). Retirement, compaction and the
193
+ intent sweep take no lock and hold no connection across their provider deletes.
187
194
  `readOnly` bindings are skipped unless `includeReadOnly: true`. A binding
188
195
  whose provider has no `list` is reported as `unsupported` (and as a
189
196
  maintenance warning), never silently skipped. Everything under the owned prefix
@@ -294,6 +301,12 @@ Alert on these row-storage signals:
294
301
  `listCurrentRevisions`. A first read with no cursor can also throw it when a
295
302
  prune commits mid-read; retry it. A new warehouse sink stuck on it after such
296
303
  a race recovers with `sink.reset()`.
304
+ - The warehouse sink's `runOnce()` keeps rejecting and the anti-join in "The
305
+ two-table contract" returns the same revision IDs run after run: rows are in the
306
+ rows table with no row in the revisions table. The revisions load is failing. The plan is retained and the rows are
307
+ already loaded, so fix the cause (usually a column the revisions table lacks) and
308
+ keep running: the retry loads only the revisions and `current_rows` catches up.
309
+ Do not edit the tables by hand and do not `reset()`.
297
310
  - A non-empty `missing` from the warehouse sink's `runOnce()`. The sink was down
298
311
  longer than `maxFeedHoldDays`, retention stopped waiting for it, and the
299
312
  warehouse lacks those revisions. Backfill them or accept the gap, and keep
@@ -288,6 +288,41 @@ Either way, subsequent runs reuse the cached tokens (auto-refresh on expiry via
288
288
 
289
289
  **Output:** JSON with `tracks[].status` (`passed`/`failed`/`skipped`), `steps[]` with diagnostics, and validations per step.
290
290
 
291
+ ### Account-scoped fixtures and negative membership
292
+
293
+ Automatic `seed_product` and `seed_pricing_option` calls use the complete account
294
+ reference used by the storyboard: `context.account`, otherwise the single resolved
295
+ account in its effective sample requests or single-account provisioning request,
296
+ otherwise a single sandbox account fixture. Request overrides, context inputs, and
297
+ the run brand use the same account rules as public requests. Account provisioning
298
+ seeds retain their independent targets; only product and pricing seeds need a
299
+ shared catalog scope. Natural
300
+ keys retain brand countries, operator, operator unit, currency, and timezone. Opaque
301
+ `account_id` references stay opaque. A storyboard that uses several accounts must
302
+ provide an explicit `context.account` for its seeds; unresolved or ambiguous scope
303
+ fails setup rather than seeding a different default account. This is account
304
+ scoping, not a sandbox reset: fixtures for the same account may still coexist.
305
+
306
+ For product-filter checks, exclude a known negative control rather than assuming
307
+ only one product can match. A validation entry can use:
308
+
309
+ ```yaml
310
+ check: field_excludes
311
+ path: products[*].product_id
312
+ value: filter_negative_control
313
+ description: The seeded display control is absent from an OLV result
314
+ ```
315
+
316
+ Declare `requires: [field_excludes_runner]` at the storyboard root (alongside
317
+ `controller` when needed). Supporting SDKs satisfy this intrinsic requirement;
318
+ older SDKs skip the scenario before seeding instead of silently ignoring an unknown
319
+ check. The matcher has the same scalar, deep-subset, and `allowed_values` semantics
320
+ as `field_contains`, inverted over **every** resolved terminal. Empty arrays pass;
321
+ additional matching products are allowed. Failed checks report the prohibited
322
+ terminal in the `actual` array and `expected.excludes` while preserving the
323
+ seller's response. Diagnostic evidence is bounded to the matching terminal;
324
+ absence is checked across the complete result.
325
+
291
326
  ### `adcp fuzz` — property-based schema fuzzing
292
327
 
293
328
  Generates schema-valid requests, calls your agent, checks every response under the two-path oracle (schema-valid success *or* well-formed AdCP error envelope with uppercase reason code). Anything else — 500, stack traces, lowercase error codes, token leaks — fails.
@@ -840,3 +875,12 @@ Random seed on nightly broadens the surface; fixed seed on per-PR keeps reproduc
840
875
  For creative evaluator security fixtures, see
841
876
  [Creative evaluator build probes](CREATIVE-BUILD-PROBE.md) for valid route/input
842
877
  preparation, provisioned legacy selectors and explicit coverage gaps.
878
+
879
+ SDK 17 controller registration preserves complete account identity and requires
880
+ `account: { sandbox: true }` on every controller call, including `list_scenarios`.
881
+ Callers that used the AdCP 3.0 account-less form must add this assertion before
882
+ upgrading default MCP registration. `account_id` may accompany the assertion on
883
+ the controller carrier; ordinary public opaque AccountRefs remain `{account_id}`.
884
+ The platform wrapper retains its optional-account compatibility shape and trusted
885
+ principal/target sandbox authorization. A caller assertion never grants sandbox
886
+ authority by itself.
package/docs/llms.txt CHANGED
@@ -1,7 +1,7 @@
1
1
  # Ad Context Protocol (AdCP)
2
2
 
3
3
  > Generated at: 2026-11-03
4
- > Library: @adcp/sdk v17.0.0-beta.13
4
+ > Library: @adcp/sdk v17.0.0-beta.16
5
5
  > AdCP major version: 3
6
6
  > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
7
7
  > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
16
16
 
17
17
  | Fact | Value |
18
18
  | --- | --- |
19
- | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.13` |
20
- | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.13 dist.integrity` |
19
+ | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.16` |
20
+ | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.16 dist.integrity` |
21
21
  | Node.js runtime | `^20.19.0 || >=22.12.0` |
22
22
  | Default AdCP wire release | `3.3.0-beta.3` |
23
23
  | Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.1.30`, `3.1.31`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.2.8`, `3.3.0-beta.3`, `3.3-beta.3` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
26
26
  For a checkout at the published release commit, install the exact package version:
27
27
 
28
28
  ```bash
29
- npm install --save-exact '@adcp/sdk@17.0.0-beta.13'
30
- npm view '@adcp/sdk@17.0.0-beta.13' dist.integrity
29
+ npm install --save-exact '@adcp/sdk@17.0.0-beta.16'
30
+ npm view '@adcp/sdk@17.0.0-beta.16' dist.integrity
31
31
  ```
32
32
 
33
33
  ### Required and optional peers
@@ -62,8 +62,10 @@ read-only binding is exempt from the requirement, is never chosen for new
62
62
  writes, and is still used for reads and retirement (`readyRowStorage` still
63
63
  probes it, so keep its location reachable). Compaction ignores read-only
64
64
  bindings, because nothing can adopt through them. The
65
- reference-checked deletes and the per-object lock are unchanged, because
66
- header-only revisions still share chunks within an obligation.
65
+ reference-checked deletes are unchanged, because header-only revisions still
66
+ share chunks within an obligation. (The per-object lock this note once said was
67
+ unchanged has since been removed from every path but the orphan collector; see
68
+ `docs/guides/REPORTING-LEDGER.md`.)
67
69
 
68
70
  ## Renamed fields
69
71
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adcp/sdk",
3
- "version": "17.0.0-beta.13",
3
+ "version": "17.0.0-beta.16",
4
4
  "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
5
5
  "workspaces": [
6
6
  ".",