@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.23

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 (223) hide show
  1. package/README.md +26 -2
  2. package/dist/lib/adapters/version/index.d.mts +1 -1
  3. package/dist/lib/adapters/version/index.d.ts +1 -1
  4. package/dist/lib/adapters/version/index.js +2 -0
  5. package/dist/lib/adapters/version/index.mjs +2 -0
  6. package/dist/lib/adapters/version/negotiate.d.mts +13 -0
  7. package/dist/lib/adapters/version/negotiate.d.ts +13 -0
  8. package/dist/lib/adapters/version/negotiate.js +6 -0
  9. package/dist/lib/adapters/version/negotiate.mjs +5 -0
  10. package/dist/lib/client/core.d.mts +4 -0
  11. package/dist/lib/client/core.d.ts +4 -0
  12. package/dist/lib/client/core.js +13 -0
  13. package/dist/lib/client/core.mjs +12 -0
  14. package/dist/lib/conformance/property-lists.d.mts +1 -1
  15. package/dist/lib/conformance/property-lists.d.ts +1 -1
  16. package/dist/lib/conformance/property-lists.js +1 -1
  17. package/dist/lib/conformance/property-lists.mjs +1 -1
  18. package/dist/lib/core/SingleAgentClient.d.mts +23 -1
  19. package/dist/lib/core/SingleAgentClient.d.ts +23 -1
  20. package/dist/lib/core/SingleAgentClient.js +102 -18
  21. package/dist/lib/core/SingleAgentClient.mjs +108 -18
  22. package/dist/lib/core/targeting-helpers.d.mts +123 -0
  23. package/dist/lib/core/targeting-helpers.d.ts +123 -0
  24. package/dist/lib/core/targeting-helpers.js +412 -0
  25. package/dist/lib/core/targeting-helpers.mjs +370 -0
  26. package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
  27. package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
  28. package/dist/lib/entrypoints/client-account-changes.js +28 -0
  29. package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
  30. package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
  31. package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
  32. package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
  33. package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
  34. package/dist/lib/entrypoints/discovery.d.mts +9 -0
  35. package/dist/lib/entrypoints/discovery.d.ts +9 -0
  36. package/dist/lib/entrypoints/discovery.js +72 -0
  37. package/dist/lib/entrypoints/discovery.mjs +56 -0
  38. package/dist/lib/entrypoints/errors.d.mts +11 -0
  39. package/dist/lib/entrypoints/errors.d.ts +11 -0
  40. package/dist/lib/entrypoints/errors.js +159 -0
  41. package/dist/lib/entrypoints/errors.mjs +132 -0
  42. package/dist/lib/entrypoints/media-buy.d.mts +5 -0
  43. package/dist/lib/entrypoints/media-buy.d.ts +5 -0
  44. package/dist/lib/entrypoints/media-buy.js +119 -0
  45. package/dist/lib/entrypoints/media-buy.mjs +100 -0
  46. package/dist/lib/entrypoints/registry.d.mts +5 -0
  47. package/dist/lib/entrypoints/registry.d.ts +5 -0
  48. package/dist/lib/entrypoints/registry.js +61 -0
  49. package/dist/lib/entrypoints/registry.mjs +40 -0
  50. package/dist/lib/entrypoints/utils.d.mts +7 -0
  51. package/dist/lib/entrypoints/utils.d.ts +7 -0
  52. package/dist/lib/entrypoints/utils.js +100 -0
  53. package/dist/lib/entrypoints/utils.mjs +72 -0
  54. package/dist/lib/entrypoints/version.d.mts +3 -0
  55. package/dist/lib/entrypoints/version.d.ts +3 -0
  56. package/dist/lib/entrypoints/version.js +57 -0
  57. package/dist/lib/entrypoints/version.mjs +36 -0
  58. package/dist/lib/index.d.mts +1 -1
  59. package/dist/lib/index.d.ts +1 -1
  60. package/dist/lib/media-buy/action-contracts.js +3 -3
  61. package/dist/lib/media-buy/action-contracts.mjs +1 -1
  62. package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
  63. package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
  64. package/dist/lib/media-buy/creative-start-policy.js +59 -0
  65. package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
  66. package/dist/lib/media-buy/valid-actions.d.mts +47 -0
  67. package/dist/lib/media-buy/valid-actions.d.ts +47 -0
  68. package/dist/lib/media-buy/valid-actions.js +42 -0
  69. package/dist/lib/media-buy/valid-actions.mjs +18 -0
  70. package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
  71. package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
  72. package/dist/lib/net/pin-and-bind-fetch.js +209 -0
  73. package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
  74. package/dist/lib/protocols/mcp-modern.js +20 -4
  75. package/dist/lib/protocols/mcp-modern.mjs +20 -4
  76. package/dist/lib/registry/types.generated.d.ts +224 -3
  77. package/dist/lib/reporting/ledger/index.d.mts +1 -0
  78. package/dist/lib/reporting/ledger/index.d.ts +1 -0
  79. package/dist/lib/reporting/ledger/index.js +3 -1
  80. package/dist/lib/reporting/ledger/index.mjs +1 -0
  81. package/dist/lib/reporting/ledger/instant.d.mts +5 -0
  82. package/dist/lib/reporting/ledger/instant.d.ts +5 -0
  83. package/dist/lib/reporting/ledger/instant.js +10 -0
  84. package/dist/lib/reporting/ledger/instant.mjs +9 -0
  85. package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
  86. package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
  87. package/dist/lib/reporting/ledger/issue-events.js +310 -0
  88. package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
  89. package/dist/lib/reporting/service/index.d.mts +36 -1
  90. package/dist/lib/reporting/service/index.d.ts +36 -1
  91. package/dist/lib/reporting/service/index.js +51 -1
  92. package/dist/lib/reporting/service/index.mjs +52 -2
  93. package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
  94. package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
  95. package/dist/lib/reporting/service/scheduler-support.js +1 -1
  96. package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
  97. package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
  98. package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
  99. package/dist/lib/server/capabilities-release-projection.js +128 -0
  100. package/dist/lib/server/capabilities-release-projection.mjs +112 -0
  101. package/dist/lib/server/create-adcp-server.d.mts +29 -5
  102. package/dist/lib/server/create-adcp-server.d.ts +29 -5
  103. package/dist/lib/server/create-adcp-server.js +97 -24
  104. package/dist/lib/server/create-adcp-server.mjs +108 -23
  105. package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
  106. package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
  107. package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
  108. package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
  109. package/dist/lib/server/declared-input-schema.d.mts +108 -0
  110. package/dist/lib/server/declared-input-schema.d.ts +108 -0
  111. package/dist/lib/server/declared-input-schema.js +167 -0
  112. package/dist/lib/server/declared-input-schema.mjs +137 -0
  113. package/dist/lib/server/envelope-allowlist.d.mts +1 -105
  114. package/dist/lib/server/envelope-allowlist.d.ts +1 -105
  115. package/dist/lib/server/envelope-allowlist.js +3 -79
  116. package/dist/lib/server/envelope-allowlist.mjs +1 -71
  117. package/dist/lib/server/errors.d.mts +1 -186
  118. package/dist/lib/server/errors.d.ts +1 -186
  119. package/dist/lib/server/errors.js +3 -98
  120. package/dist/lib/server/errors.mjs +1 -94
  121. package/dist/lib/server/index.d.mts +1 -1
  122. package/dist/lib/server/index.d.ts +1 -1
  123. package/dist/lib/server/mcp-modern-server.js +21 -4
  124. package/dist/lib/server/mcp-modern-server.mjs +21 -4
  125. package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
  126. package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
  127. package/dist/lib/server/media-buy-action-resolver.js +10 -1
  128. package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
  129. package/dist/lib/server/media-buy-helpers.d.mts +1 -47
  130. package/dist/lib/server/media-buy-helpers.d.ts +1 -47
  131. package/dist/lib/server/media-buy-helpers.js +3 -23
  132. package/dist/lib/server/media-buy-helpers.mjs +1 -18
  133. package/dist/lib/server/pick-safe-details.d.mts +1 -89
  134. package/dist/lib/server/pick-safe-details.d.ts +1 -89
  135. package/dist/lib/server/pick-safe-details.js +3 -61
  136. package/dist/lib/server/pick-safe-details.mjs +1 -56
  137. package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
  138. package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
  139. package/dist/lib/server/pin-and-bind-fetch.js +3 -190
  140. package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
  141. package/dist/lib/server/targeting-helpers.d.mts +1 -123
  142. package/dist/lib/server/targeting-helpers.d.ts +1 -123
  143. package/dist/lib/server/targeting-helpers.js +3 -393
  144. package/dist/lib/server/targeting-helpers.mjs +1 -370
  145. package/dist/lib/server/test-controller.js +7 -3
  146. package/dist/lib/server/test-controller.mjs +7 -3
  147. package/dist/lib/storage/memory-ledger.js +219 -1
  148. package/dist/lib/storage/memory-ledger.mjs +223 -1
  149. package/dist/lib/testing/client.js +26 -5
  150. package/dist/lib/testing/client.mjs +24 -5
  151. package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
  152. package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
  153. package/dist/lib/testing/comply-controller.js +7 -2
  154. package/dist/lib/testing/comply-controller.mjs +7 -2
  155. package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
  156. package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
  157. package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
  158. package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
  159. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
  160. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
  161. package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
  162. package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
  163. package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
  164. package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
  165. package/dist/lib/testing/storyboard/runner.js +4 -4
  166. package/dist/lib/testing/storyboard/runner.mjs +4 -4
  167. package/dist/lib/testing/storyboard/task-map.js +4 -1
  168. package/dist/lib/testing/storyboard/task-map.mjs +4 -1
  169. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  170. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  171. package/dist/lib/utils/adcp-error-response.d.mts +196 -0
  172. package/dist/lib/utils/adcp-error-response.d.ts +196 -0
  173. package/dist/lib/utils/adcp-error-response.js +118 -0
  174. package/dist/lib/utils/adcp-error-response.mjs +95 -0
  175. package/dist/lib/utils/buyer-retry-policy.js +2 -2
  176. package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
  177. package/dist/lib/utils/capabilities.d.mts +6 -0
  178. package/dist/lib/utils/capabilities.d.ts +6 -0
  179. package/dist/lib/utils/capabilities.js +6 -2
  180. package/dist/lib/utils/capabilities.mjs +6 -2
  181. package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
  182. package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
  183. package/dist/lib/utils/envelope-allowlist.js +98 -0
  184. package/dist/lib/utils/envelope-allowlist.mjs +71 -0
  185. package/dist/lib/utils/pick-safe-details.d.mts +89 -0
  186. package/dist/lib/utils/pick-safe-details.d.ts +89 -0
  187. package/dist/lib/utils/pick-safe-details.js +80 -0
  188. package/dist/lib/utils/pick-safe-details.mjs +56 -0
  189. package/dist/lib/v2/projection/augment-response.d.mts +4 -0
  190. package/dist/lib/v2/projection/augment-response.d.ts +4 -0
  191. package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
  192. package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
  193. package/dist/lib/v2/projection/creative-delivery.js +20 -4
  194. package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
  195. package/dist/lib/v2/projection/index.d.mts +2 -2
  196. package/dist/lib/v2/projection/index.d.ts +2 -2
  197. package/dist/lib/v2/projection/index.js +4 -0
  198. package/dist/lib/v2/projection/index.mjs +5 -1
  199. package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
  200. package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
  201. package/dist/lib/v2/projection/legacy-metadata.js +14 -0
  202. package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
  203. package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
  204. package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
  205. package/dist/lib/v2/projection/legacy-routes.js +2 -1
  206. package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
  207. package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
  208. package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
  209. package/dist/lib/v2/projection/v1-to-v2.js +18 -11
  210. package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
  211. package/dist/lib/version.d.mts +3 -3
  212. package/dist/lib/version.d.ts +3 -3
  213. package/dist/lib/version.js +3 -3
  214. package/dist/lib/version.mjs +3 -3
  215. package/docs/TYPE-SUMMARY.md +2 -2
  216. package/docs/guides/CREATIVE-DELIVERY.md +12 -0
  217. package/docs/guides/REPORTING-LEDGER.md +121 -0
  218. package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
  219. package/docs/llms.txt +2 -2
  220. package/docs/migration-14.x-rc-worksheet.md +4 -4
  221. package/docs/migration-16-to-17.md +149 -0
  222. package/docs/migration-reporting-storage-package.md +10 -0
  223. package/package.json +106 -1
@@ -1,4 +1,8 @@
1
- import { legacyFormatRefsForDeclaration, sellerDeclaredFormatOption } from "./legacy-metadata.mjs";
1
+ import {
2
+ isInferredFromIdFormatOption,
3
+ legacyFormatRefsForDeclaration,
4
+ sellerDeclaredFormatOption
5
+ } from "./legacy-metadata.mjs";
2
6
  function undeclaredFormatOptionSelector(declaration) {
3
7
  return {
4
8
  format_kind: typeof declaration.format_kind === "string" ? declaration.format_kind : "",
@@ -103,7 +107,8 @@ function legacyRoutesForProduct(productId, declarations, options = {}) {
103
107
  format_kind: selector.format_kind,
104
108
  ...selector.params !== void 0 && { params: selector.params }
105
109
  }
106
- }
110
+ },
111
+ ...isInferredFromIdFormatOption(declaration) && { inferred_from_id: true }
107
112
  }
108
113
  ];
109
114
  });
@@ -16,7 +16,9 @@
16
16
  * authoritative pairing. Seller-asserted, normative.
17
17
  * 2. **Registry glob match**. Look up `format_id.id` against the
18
18
  * registry's `format_id_glob` entries (including wildcards). First
19
- * match wins per the spec's ordering.
19
+ * match wins per the spec's ordering. At an agent URL other than the
20
+ * AAO's this is a guess, so an adopter's `legacyFormatConverter` runs
21
+ * first there.
20
22
  * 3. **Structural match**. Match against the v1 format's declared
21
23
  * assets + version constraints. Family-level identification
22
24
  * yields a canonical (e.g., "vast 4.x → video_vast"). Less
@@ -76,6 +78,11 @@ export interface LegacyFormatConversionContext {
76
78
  * The SDK adds the source `formatId` as `v1_format_ref`; converters must not
77
79
  * set `canonical_formats_only: true` because a legacy source is, by
78
80
  * definition, round-trippable to that ref.
81
+ *
82
+ * For a ref at any agent URL other than the AAO reference creative agent, the
83
+ * converter runs before the SDK guesses the id's meaning from its name, so
84
+ * its declaration wins over the guess. Return `undefined` to accept the guess.
85
+ * For a ref at the AAO agent, it runs only after the AAO's own mappings fail.
79
86
  */
80
87
  export type LegacyFormatConverter = (context: LegacyFormatConversionContext) => V2ProductFormatDeclaration | null | undefined;
81
88
  /** Safe request context supplied to an asynchronous seller-specific resolver. */
@@ -96,6 +103,19 @@ export interface V1ToV2ProjectionOptions {
96
103
  legacyFormatConverter?: LegacyFormatConverter;
97
104
  /** Pre-resolved exact-owner publisher/community catalogs, highest precedence first. */
98
105
  projectionCatalogs?: readonly ProjectionCatalogSnapshot[];
106
+ /**
107
+ * Resolve a ref only from authoritative sources: catalog snapshots, an exact
108
+ * AAO catalog entry, and `legacyFormatConverter`. Ids under an agent URL
109
+ * other than the AAO reference creative agent skip the AAO naming guesses
110
+ * (the bare-id alias and the registry id glob), because that agent, not the
111
+ * AAO, says what its ids mean. A ref only a guess could resolve gets a
112
+ * `FORMAT_PROJECTION_FAILED` diagnostic instead of a declaration.
113
+ *
114
+ * Default `false`: guesses still apply, and the routes mark each guessed
115
+ * option with `inferred_from_id: true`. Set `true` before comparing a
116
+ * projection against a seller's own `format_options[]`.
117
+ */
118
+ authoritativeOnly?: boolean;
99
119
  }
100
120
  /**
101
121
  * Project a v1 Product to a v2 Product. Drops `format_ids` from the
@@ -16,7 +16,9 @@
16
16
  * authoritative pairing. Seller-asserted, normative.
17
17
  * 2. **Registry glob match**. Look up `format_id.id` against the
18
18
  * registry's `format_id_glob` entries (including wildcards). First
19
- * match wins per the spec's ordering.
19
+ * match wins per the spec's ordering. At an agent URL other than the
20
+ * AAO's this is a guess, so an adopter's `legacyFormatConverter` runs
21
+ * first there.
20
22
  * 3. **Structural match**. Match against the v1 format's declared
21
23
  * assets + version constraints. Family-level identification
22
24
  * yields a canonical (e.g., "vast 4.x → video_vast"). Less
@@ -76,6 +78,11 @@ export interface LegacyFormatConversionContext {
76
78
  * The SDK adds the source `formatId` as `v1_format_ref`; converters must not
77
79
  * set `canonical_formats_only: true` because a legacy source is, by
78
80
  * definition, round-trippable to that ref.
81
+ *
82
+ * For a ref at any agent URL other than the AAO reference creative agent, the
83
+ * converter runs before the SDK guesses the id's meaning from its name, so
84
+ * its declaration wins over the guess. Return `undefined` to accept the guess.
85
+ * For a ref at the AAO agent, it runs only after the AAO's own mappings fail.
79
86
  */
80
87
  export type LegacyFormatConverter = (context: LegacyFormatConversionContext) => V2ProductFormatDeclaration | null | undefined;
81
88
  /** Safe request context supplied to an asynchronous seller-specific resolver. */
@@ -96,6 +103,19 @@ export interface V1ToV2ProjectionOptions {
96
103
  legacyFormatConverter?: LegacyFormatConverter;
97
104
  /** Pre-resolved exact-owner publisher/community catalogs, highest precedence first. */
98
105
  projectionCatalogs?: readonly ProjectionCatalogSnapshot[];
106
+ /**
107
+ * Resolve a ref only from authoritative sources: catalog snapshots, an exact
108
+ * AAO catalog entry, and `legacyFormatConverter`. Ids under an agent URL
109
+ * other than the AAO reference creative agent skip the AAO naming guesses
110
+ * (the bare-id alias and the registry id glob), because that agent, not the
111
+ * AAO, says what its ids mean. A ref only a guess could resolve gets a
112
+ * `FORMAT_PROJECTION_FAILED` diagnostic instead of a declaration.
113
+ *
114
+ * Default `false`: guesses still apply, and the routes mark each guessed
115
+ * option with `inferred_from_id: true`. Set `true` before comparing a
116
+ * projection against a seller's own `format_options[]`.
117
+ */
118
+ authoritativeOnly?: boolean;
99
119
  }
100
120
  /**
101
121
  * Project a v1 Product to a v2 Product. Drops `format_ids` from the
@@ -219,9 +219,12 @@ function projectFormatId(fid, productId, field, options) {
219
219
  const exactCatalogEntry = (0, import_catalog.lookupV1Format)(fid, options?._catalogPath);
220
220
  const canonicalAgentUrl = (0, import_resolve_agent_properties.canonicalizeAgentUrl)(fid.agent_url);
221
221
  const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !(0, import_address_guards.isLikelyPrivateUrl)(canonicalAgentUrl);
222
- const aaoGuessesApply = options?._authoritativeOnly !== true || (0, import_catalog.isAaoAgentUrl)(fid.agent_url);
222
+ const atAaoAgent = (0, import_catalog.isAaoAgentUrl)(fid.agent_url);
223
+ const authoritativeOnly = options?.authoritativeOnly === true || options?._authoritativeOnly === true;
224
+ const aaoGuessesApply = !authoritativeOnly || atAaoAgent;
223
225
  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? (0, import_catalog.lookupUniqueV1FormatById)(fid.id, options?._catalogPath) : void 0;
224
- if (uniqueAliasEntry) {
226
+ const converterBeforeGuesses = uniqueAliasEntry !== void 0 || exactCatalogEntry === void 0 && !atAaoAgent;
227
+ if (converterBeforeGuesses) {
225
228
  const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
226
229
  if (explicit) return explicit;
227
230
  }
@@ -259,11 +262,13 @@ function projectFormatId(fid, productId, field, options) {
259
262
  format_kind: projection.kind,
260
263
  params,
261
264
  v1_format_ref: [fid]
262
- }
265
+ },
266
+ // An entry found only by its bare id describes the AAO's id, not this agent's.
267
+ ...exactCatalogEntry === void 0 && !atAaoAgent && { inferredFromId: true }
263
268
  };
264
269
  }
265
270
  if (catalogEntry && !catalogEntry.canonical) {
266
- const custom2 = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
271
+ const custom2 = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
267
272
  if (custom2) return custom2;
268
273
  return {
269
274
  diagnostic: {
@@ -288,7 +293,8 @@ function projectFormatId(fid, productId, field, options) {
288
293
  format_kind: globMatch.canonical,
289
294
  params: buildParams(fid, globMatch.parameters),
290
295
  v1_format_ref: [fid]
291
- }
296
+ },
297
+ ...!atAaoAgent && { inferredFromId: true }
292
298
  };
293
299
  }
294
300
  if (catalogEntry?.assets) {
@@ -304,7 +310,7 @@ function projectFormatId(fid, productId, field, options) {
304
310
  };
305
311
  }
306
312
  }
307
- const custom = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
313
+ const custom = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
308
314
  if (custom) return custom;
309
315
  return {
310
316
  diagnostic: {
@@ -329,11 +335,11 @@ function projectV1ProductToV2(v1, options) {
329
335
  for (let i = 0; i < inputFormatIds.length; i++) {
330
336
  const fid = inputFormatIds[i];
331
337
  const field = `products[${v1.product_id}].format_ids[${i}]`;
332
- const { decl, diagnostic } = projectFormatId(fid, v1.product_id, field, options);
338
+ const { decl, diagnostic, inferredFromId } = projectFormatId(fid, v1.product_id, field, options);
333
339
  if (decl) {
334
- format_options.push(
335
- typeof decl.format_option_id === "string" && decl.format_option_id.length > 0 ? decl : { ...decl, format_option_id: migratedFormatOptionId(fid) }
336
- );
340
+ const option = typeof decl.format_option_id === "string" && decl.format_option_id.length > 0 ? decl : { ...decl, format_option_id: migratedFormatOptionId(fid) };
341
+ if (inferredFromId) (0, import_legacy_metadata.rememberInferredFromIdFormatOption)(option);
342
+ format_options.push(option);
337
343
  }
338
344
  if (diagnostic) diagnostics.push(diagnostic);
339
345
  }
@@ -391,7 +397,8 @@ function sameIdentity(left, right) {
391
397
  });
392
398
  }
393
399
  function compatible(option, ref) {
394
- const known = canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url });
400
+ const bare = { agent_url: ref.agent_url, id: ref.id };
401
+ const known = projectFormatId(bare, `<bare:${ref.id}>`, `bareFormatId(${ref.id})`, { authoritativeOnly: true }).decl;
395
402
  if (known && known.format_kind !== option.format_kind) return false;
396
403
  const params = record(option.params) ?? {};
397
404
  const knownParams = record(known?.params) ?? {};
@@ -15,6 +15,7 @@ import { legacyRoutesForProduct } from "./legacy-routes.mjs";
15
15
  import {
16
16
  concealLegacyFormatRefs,
17
17
  legacyFormatRefsForDeclaration,
18
+ rememberInferredFromIdFormatOption,
18
19
  rememberSynthesizedFormatOption,
19
20
  transferLegacyCreativeMetadata
20
21
  } from "./legacy-metadata.mjs";
@@ -202,9 +203,12 @@ function projectFormatId(fid, productId, field, options) {
202
203
  const exactCatalogEntry = lookupV1Format(fid, options?._catalogPath);
203
204
  const canonicalAgentUrl = canonicalizeAgentUrl(fid.agent_url);
204
205
  const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !isLikelyPrivateUrl(canonicalAgentUrl);
205
- const aaoGuessesApply = options?._authoritativeOnly !== true || isAaoAgentUrl(fid.agent_url);
206
+ const atAaoAgent = isAaoAgentUrl(fid.agent_url);
207
+ const authoritativeOnly = options?.authoritativeOnly === true || options?._authoritativeOnly === true;
208
+ const aaoGuessesApply = !authoritativeOnly || atAaoAgent;
206
209
  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? lookupUniqueV1FormatById(fid.id, options?._catalogPath) : void 0;
207
- if (uniqueAliasEntry) {
210
+ const converterBeforeGuesses = uniqueAliasEntry !== void 0 || exactCatalogEntry === void 0 && !atAaoAgent;
211
+ if (converterBeforeGuesses) {
208
212
  const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
209
213
  if (explicit) return explicit;
210
214
  }
@@ -242,11 +246,13 @@ function projectFormatId(fid, productId, field, options) {
242
246
  format_kind: projection.kind,
243
247
  params,
244
248
  v1_format_ref: [fid]
245
- }
249
+ },
250
+ // An entry found only by its bare id describes the AAO's id, not this agent's.
251
+ ...exactCatalogEntry === void 0 && !atAaoAgent && { inferredFromId: true }
246
252
  };
247
253
  }
248
254
  if (catalogEntry && !catalogEntry.canonical) {
249
- const custom2 = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
255
+ const custom2 = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
250
256
  if (custom2) return custom2;
251
257
  return {
252
258
  diagnostic: {
@@ -271,7 +277,8 @@ function projectFormatId(fid, productId, field, options) {
271
277
  format_kind: globMatch.canonical,
272
278
  params: buildParams(fid, globMatch.parameters),
273
279
  v1_format_ref: [fid]
274
- }
280
+ },
281
+ ...!atAaoAgent && { inferredFromId: true }
275
282
  };
276
283
  }
277
284
  if (catalogEntry?.assets) {
@@ -287,7 +294,7 @@ function projectFormatId(fid, productId, field, options) {
287
294
  };
288
295
  }
289
296
  }
290
- const custom = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
297
+ const custom = converterBeforeGuesses ? void 0 : projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
291
298
  if (custom) return custom;
292
299
  return {
293
300
  diagnostic: {
@@ -312,11 +319,11 @@ function projectV1ProductToV2(v1, options) {
312
319
  for (let i = 0; i < inputFormatIds.length; i++) {
313
320
  const fid = inputFormatIds[i];
314
321
  const field = `products[${v1.product_id}].format_ids[${i}]`;
315
- const { decl, diagnostic } = projectFormatId(fid, v1.product_id, field, options);
322
+ const { decl, diagnostic, inferredFromId } = projectFormatId(fid, v1.product_id, field, options);
316
323
  if (decl) {
317
- format_options.push(
318
- typeof decl.format_option_id === "string" && decl.format_option_id.length > 0 ? decl : { ...decl, format_option_id: migratedFormatOptionId(fid) }
319
- );
324
+ const option = typeof decl.format_option_id === "string" && decl.format_option_id.length > 0 ? decl : { ...decl, format_option_id: migratedFormatOptionId(fid) };
325
+ if (inferredFromId) rememberInferredFromIdFormatOption(option);
326
+ format_options.push(option);
320
327
  }
321
328
  if (diagnostic) diagnostics.push(diagnostic);
322
329
  }
@@ -374,7 +381,8 @@ function sameIdentity(left, right) {
374
381
  });
375
382
  }
376
383
  function compatible(option, ref) {
377
- const known = canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url });
384
+ const bare = { agent_url: ref.agent_url, id: ref.id };
385
+ const known = projectFormatId(bare, `<bare:${ref.id}>`, `bareFormatId(${ref.id})`, { authoritativeOnly: true }).decl;
378
386
  if (known && known.format_kind !== option.format_kind) return false;
379
387
  const params = record(option.params) ?? {};
380
388
  const knownParams = record(known?.params) ?? {};
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.21";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.23";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.21";
36
+ readonly library: "17.0.0-beta.23";
37
37
  readonly adcp: "3.3.0-beta.5";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.5", "3.3-beta.5"];
39
- readonly generatedAt: "2026-11-08T04:16:26.931Z";
39
+ readonly generatedAt: "2026-11-12T14:23:46.648Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.21";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.23";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.21";
36
+ readonly library: "17.0.0-beta.23";
37
37
  readonly adcp: "3.3.0-beta.5";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.5", "3.3-beta.5"];
39
- readonly generatedAt: "2026-11-08T04:16:26.931Z";
39
+ readonly generatedAt: "2026-11-12T14:23:46.648Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -31,7 +31,7 @@ __export(version_exports, {
31
31
  toReleasePrecisionVersion: () => toReleasePrecisionVersion
32
32
  });
33
33
  module.exports = __toCommonJS(version_exports);
34
- const LIBRARY_VERSION = "17.0.0-beta.21";
34
+ const LIBRARY_VERSION = "17.0.0-beta.23";
35
35
  const ADCP_VERSION = "3.3.0-beta.5";
36
36
  const ADCP_MAJOR_VERSION = 3;
37
37
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -109,10 +109,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
109
109
  "3.3-beta.5"
110
110
  ];
111
111
  const VERSION_INFO = {
112
- library: "17.0.0-beta.21",
112
+ library: "17.0.0-beta.23",
113
113
  adcp: "3.3.0-beta.5",
114
114
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
115
- generatedAt: "2026-11-08T04:16:26.931Z"
115
+ generatedAt: "2026-11-12T14:23:46.648Z"
116
116
  };
117
117
  function getAdcpVersion() {
118
118
  return ADCP_VERSION;
@@ -1,4 +1,4 @@
1
- const LIBRARY_VERSION = "17.0.0-beta.21";
1
+ const LIBRARY_VERSION = "17.0.0-beta.23";
2
2
  const ADCP_VERSION = "3.3.0-beta.5";
3
3
  const ADCP_MAJOR_VERSION = 3;
4
4
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -76,10 +76,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
76
76
  "3.3-beta.5"
77
77
  ];
78
78
  const VERSION_INFO = {
79
- library: "17.0.0-beta.21",
79
+ library: "17.0.0-beta.23",
80
80
  adcp: "3.3.0-beta.5",
81
81
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
82
- generatedAt: "2026-11-08T04:16:26.931Z"
82
+ generatedAt: "2026-11-12T14:23:46.648Z"
83
83
  };
84
84
  function getAdcpVersion() {
85
85
  return ADCP_VERSION;
@@ -1,7 +1,7 @@
1
1
  # AdCP Type Summary
2
2
 
3
- > Generated at: 2026-11-08
4
- > @adcp/sdk v17.0.0-beta.21
3
+ > Generated at: 2026-11-12
4
+ > @adcp/sdk v17.0.0-beta.23
5
5
 
6
6
  Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
7
7
 
@@ -267,6 +267,18 @@ it. Authorization changes and discovery invalidation invalidate the evidence.
267
267
  Request-scoped custom transports require explicit capability or tool-schema
268
268
  support and do not reuse this inferred product evidence.
269
269
 
270
+ Package selectors follow the seller's release even when creatives stay on the
271
+ legacy wire. AdCP 3.1 defines `format_option_refs` on the package request, so
272
+ when `supported_versions` proves a mutually served 3.1 release, a
273
+ `createMediaBuy` package or `updateMediaBuy` new package whose selected options
274
+ have no legacy `format_ids` is sent with its `format_option_refs`, and the
275
+ seller resolves them. Selections with a complete legacy mapping are still sent
276
+ as `format_ids`. AdCP 3.0 does not define the field, so a 3.0 seller, or one
277
+ whose release cannot be proven, gets `CreativeFormatProjectionError` instead:
278
+ dropping the selector would activate every format the product offers.
279
+ Configure `canonicalFormatLegacyResolver` to supply the legacy mapping for
280
+ those sellers.
281
+
270
282
  Assignment-only sync and updates containing only an existing `package_id` keep
271
283
  their existing wire behavior. Pass the matching selectors for this request to
272
284
  use the product-based fallback; package IDs alone do not establish support.
@@ -2479,3 +2479,124 @@ The repository-only fixture at
2479
2479
  23/25-hour cases,
2480
2480
  a calendar-month boundary, and the obligation-missing path with no invented
2481
2481
  obligation ID.
2482
+
2483
+ ### Observe consumer-status mismatches: `issueObserver`
2484
+
2485
+ A `CONSUMER_STATUS_MISMATCH` is caller-scoped: only the buyer whose
2486
+ `sync_reporting_status` statement caused it sees it in `get_reporting_status`.
2487
+ To hear about one without waiting for that buyer to poll, pass an
2488
+ `issueObserver` (adcp-client#3648, the Python SDK's `issue_observer`):
2489
+
2490
+ ```ts
2491
+ import { createReliableReportingService, type ReportingIssueEventV1 } from '@adcp/sdk/reporting/service';
2492
+
2493
+ async function onIssue(event: ReportingIssueEventV1) {
2494
+ // Delivery is at least once: deduplicate on event.eventId.
2495
+ if (event.kind === 'resolved') return alerts.close(event.issueId, { dedupeKey: event.eventId });
2496
+ if (event.issue && event.issue.responsibleParty !== 'buyer') {
2497
+ await alerts.open(event.issueId, {
2498
+ dedupeKey: event.eventId,
2499
+ escalated: event.kind === 'escalated',
2500
+ action: event.issue.recommendedAction,
2501
+ });
2502
+ }
2503
+ }
2504
+
2505
+ const reporting = createReliableReportingService({
2506
+ storage, // memoryStorage(), or postgresStorage({ pool }) with migration 0012 applied
2507
+ resolveConsumerId,
2508
+ consumerMismatchEscalation: {
2509
+ escalationSeconds: 4 * 3_600,
2510
+ operationsContact: { email: 'reporting-ops@seller.example' },
2511
+ },
2512
+ issueObserver: onIssue,
2513
+ // ...adapters, contact, resolveSource, resolveCurrency, resolveCoverage, windows
2514
+ });
2515
+ reporting.start({ intervalMilliseconds: 60_000, deploymentWide: true, onError: reportToSentry });
2516
+ ```
2517
+
2518
+ **When it is called.** Once per lifecycle transition of a mismatch occurrence:
2519
+
2520
+ | `event.kind` | The transition | Recorded |
2521
+ | --- | --- | --- |
2522
+ | `opened` | A consumer's current statement started to conflict with the seller's record: a negative statement landed, or a restatement made a `received` statement stale. | In the same transaction as that `sync_reporting_status` write or revision commit. |
2523
+ | `escalated` | An open occurrence passed `openedAt` plus `consumerMismatchEscalation.escalationSeconds`, where the issue turns `action_required` with a `contact_*` action. | By `runCycle`'s sweep, which settles the obligation first so a cleared condition resolves instead. |
2524
+ | `resolved` | The statement that caused it is no longer the consumer's current leaf (the buyer superseded it), or it no longer conflicts. | In the same transaction as the write that cleared it. |
2525
+
2526
+ An occurrence follows the read path's own projection, with one difference: while the seller's own
2527
+ projection is degraded, `get_reporting_status` publishes the seller's issue instead of the mismatch,
2528
+ but the disagreement still stands, so the occurrence stays open (and can escalate). An occurrence
2529
+ needs at least one revision; a statement filed before the first one opens when it commits.
2530
+
2531
+ The kind union also has `acknowledged` and `waived`, the Python SDK's operator transitions
2532
+ (`set_issue_state`). **No TypeScript store emits them yet**: the TypeScript ledger has no operator
2533
+ issue-state API.
2534
+
2535
+ **Delivery needs `runCycle`.** The ledger records `opened` and `resolved` with the writes, but the
2536
+ observer runs only on `runCycle` (`start()`, or your own scheduler), after the worker: it sweeps
2537
+ escalations, then delivers committed events, each occurrence's in recording order with at most one
2538
+ leased at a time. Without `runCycle` events are recorded but the observer is never called, and
2539
+ `escalated` is never recorded. The Python SDK is the same: its worker turn does both.
2540
+
2541
+ **At least once.** An occurrence is `(issueId, consumerId)`: the `issueId` that `get_reporting_status`
2542
+ publishes names the obligation and the causing `reporting_status_id` but not the consumer, and two
2543
+ consumers may reuse one status id. Each transition is recorded exactly once, even when replicas make it
2544
+ together (`(issueId, consumerId, kind)` is unique). A cycle that stops after the observer returned but
2545
+ before the event was marked delivered delivers it again. Every delivery carries the same `eventId`,
2546
+ `"rpie_" + sha256(canonical_json_utf8_v1(["reporting-issue-event-v1", issueId, consumerId, kind])).hex()[:40]`
2547
+ (`reportingIssueEventIdV1`). That is the Python SDK's scheme with the consumer added: Python's `issue_id` is
2548
+ already consumer-scoped, so it hashes `[tag, issue_id, kind]`. An exact retry of `sync_reporting_status`
2549
+ (`unchanged`) and status reads record nothing.
2550
+
2551
+ **Failures never reach the buyer.** An observer that throws, or an async one past 10 seconds, is
2552
+ retried on a later cycle after a backoff of 30 seconds doubling to one hour, with no limit;
2553
+ `event.attempt` counts deliveries. The failure is handed to the scheduler's `onError` as a
2554
+ `ReportingIssueObserverError` (`component: 'issue_observer'`, with `eventId`; `issue_events` when the
2555
+ sweep or claim failed; `issue_events:snapshot` when the evidence could not be read, which is retried
2556
+ rather than delivered unrendered) and returned in `runCycle(...).issueEvents.errors`.
2557
+
2558
+ **The event.** `eventId`, `kind`, `occurredAt` (the issue's `openedAt`, the escalation boundary, or when
2559
+ it resolved), `accountId`, `consumerId`, `principal` (for a subscription obligation, on every kind including `resolved`, while the obligation is retained; omitted once retention removed it), `issueId`,
2560
+ `reportingObligationId`, `reportingStatusId`, `attempt`, and `issue`: the `ReportingLedgerIssueV1`
2561
+ `get_reporting_status` showed `consumerId` at `occurredAt` (`responsibleParty`, `recommendedAction`,
2562
+ `severity`, `openedAt`). It is `null` for `resolved`, while the seller's own projection suppressed the
2563
+ mismatch at that instant, and when the evidence is no longer retained. Rendering is best effort and
2564
+ leaves Managed Delivery out.
2565
+
2566
+ **Storage.** `memoryStorage()` records issue events. On PostgreSQL, `@adcp/reporting-storage` needs
2567
+ migration `0012 reporting_issue_events` (`npx adcp-reporting-storage migrate`): one new table and its
2568
+ indexes, additive, so workers of an earlier release keep running beside it (they record no events for
2569
+ their own writes). Until it is applied, writes record nothing, `postgresStorage().checkSchema()` names
2570
+ `0012` as pending, and a store constructed directly refuses `issueObserver` at its first cycle. The
2571
+ service refuses `issueObserver` at construction against a store that does not record issue events.
2572
+ Retention prunes only closed occurrences: resolved, every event delivered more than seven days ago, and
2573
+ unable to be derived again because the causing statement is no longer the consumer's current leaf or the
2574
+ obligation is gone. An open occurrence is never pruned, however long ago its events were delivered: the
2575
+ outbox is also the record of which occurrences are open, which a later supersession resolves and the sweep
2576
+ escalates. A resolved occurrence whose statement is still current is kept too, as the anchor that stops a
2577
+ later write recording its delivered events again under the same `eventId`.
2578
+
2579
+ When ledger retention retires a period (`retireExpiredPeriods`), its open occurrences resolve in the same
2580
+ transaction, because nothing can resolve or escalate them once the obligation and statements are gone. The
2581
+ `resolved` event is delivered like any other, with `issue: null` and no `principal`, and the occurrence is
2582
+ then pruned.
2583
+
2584
+ **Production service.** `createPostgresReliableReportingProductionService` (`@adcp/reporting-storage/service`)
2585
+ takes `issueObserver` too: it passes it to the core service whose `runCycle` and `start()` it drives, and
2586
+ adds `REPORTING_ISSUE_EVENTS_MIGRATION` to `service.setup.migrations` when it is set. The Python SDK adds the
2587
+ same in adcp-client-python#1873.
2588
+
2589
+ Composing the ledger without the service? Run
2590
+ `createReportingIssueEventDispatcherV1({ store, observer, escalation }).runOnce({ accountId })` on your
2591
+ own schedule.
2592
+
2593
+ **Known gaps against the Python SDK.**
2594
+ - `acknowledged` and `waived` are never emitted (no operator issue-state API).
2595
+ - A seller-side change never clears a TypeScript mismatch: the read projection only stops conflicting
2596
+ when the buyer supersedes its statement, while Python's `consumer_statement_conflicts` also clears
2597
+ `content_mismatch`, `revision_missing` and `unreadable` on the seller's own record change
2598
+ ([#3653](https://github.com/adcontextprotocol/adcp-client/issues/3653)). `commitRevision` already
2599
+ records `resolved` when the projection stops conflicting, so events follow once that is fixed.
2600
+ - The issue id is per causing statement, not per chain occurrence, so a TypeScript and a Python seller
2601
+ publish different `issueId`s (and therefore `eventId`s) for the same disagreement, and the TypeScript
2602
+ `eventId` also hashes the consumer. Observers should not compare ids across SDKs.
@@ -469,6 +469,7 @@ npx @adcp/sdk@15.9 storyboard run https://sandbox.agent.example/mcp signed_reque
469
469
  - **A2A discovery fails closed.** If the Agent Card cannot resolve to a supported JSON-RPC interface, networked vectors skip with detailed reason `signing_transport_unavailable`; the storyboard cannot pass, the `security_transport` track stays `partial`, and the command exits 3. Publish a resolvable modern or legacy Agent Card, or grade an MCP/REST binding. Do not use `--soft-fail` to dismiss actual A2A verifier failures: once discovery succeeds, they are real grades.
470
470
  - **The in-library vector remains transport-independent.** `025-jwk-alg-crv-mismatch` is decided against the SDK verifier with no wire exchange, so its result does not grade your agent.
471
471
  - **Vectors excluded on their own terms say so, on every protocol.** `026-non-ascii-host` reports `transport_ungradable` (no HTTP client can carry a non-ASCII authority — `fetch` punycodes it first). `028-unsigned-protocol-method-required` reports `capability_profile_mismatch` unless your `get_adcp_capabilities` declares `request_signing.protocol_methods_required_for` — **this applies on MCP runs too, not just A2A**: previously the storyboard dispatched 028 at every agent, so one that never claimed the JSON-RPC bucket could fail it. Declare the bucket (e.g. `['tasks/cancel']`) if you verify signatures on protocol methods; a declaration your AdCP line's schema rejects is discarded rather than treated as "not declared", so it cannot suppress the vector. Note `adcp grade request-signing` does not read your advertisement — it uses the profile you pass it — so the two commands can disagree about 028 by design.
472
+ - **Vector `027-webhook-registration-authentication-unsigned` grades only while legacy HMAC is on.** From 3.3 it declares `applies_when: "webhook_signing.legacy_hmac_fallback == true"`. The storyboard reads your `get_adcp_capabilities` and reports `capability_profile_mismatch` when the flag is false or `webhook_signing` is absent, because such a seller rejects the registration with `UNSUPPORTED_FEATURE` instead. `adcp grade request-signing` does not read your advertisement; library callers can pass `agentCapabilities` to `gradeRequestSigning()` for the same check.
472
473
  - **A run that graded nothing exits nonzero.** Skipped steps are `passed: true`, so a coverage gap used to exit 0. `adcp storyboard step` now exits 3 when the runner could not dispatch the step, and the full assessment exits 3 when a storyboard's signing coverage went unverified — including when your own `--signing-skip-vectors` removed every vector, which is the other way to end up with nothing graded. The message names which of the two happened. Everything else keeps exit 0: other `partial` runs, legacy fixture gaps, and single steps you excluded yourself. `--soft-fail` works on both commands and reports the gap while exiting 0.
473
474
  - **Library callers get the same knobs.** `comply(agentUrl, { request_signing: { transport: 'mcp', skipVectors: [...], onlyVectors: [...], skipRateAbuse: true, rateAbuseCap: 5 } })` from `@adcp/sdk/testing` mirrors the storyboard CLI knobs. The standalone `gradeRequestSigning()` API also accepts `signingProfileVersion: '3.2'`, matching `adcp grade request-signing --signing-profile 3.2`. `storyboard run` prefixes transport and vector-filter flags because `--transport` is already taken by the storyboard's own transport.
474
475
  - **Mistyped flag values are rejected.** `--signing-skip-vectors` validates every id against the shipped vector set (a typo silently skipped nothing before), and `--signing-skip-rate-abuse` refuses a value — `=false` used to read as "on".
package/docs/llms.txt CHANGED
@@ -1,7 +1,7 @@
1
1
  # Ad Context Protocol (AdCP)
2
2
 
3
- > Generated at: 2026-11-08
4
- > Library: @adcp/sdk v17.0.0-beta.21
3
+ > Generated at: 2026-11-12
4
+ > Library: @adcp/sdk v17.0.0-beta.23
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.21` |
20
- | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.21 dist.integrity` |
19
+ | Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.23` |
20
+ | npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.23 dist.integrity` |
21
21
  | Node.js runtime | `^20.19.0 || >=22.12.0` |
22
22
  | Default AdCP wire release | `3.3.0-beta.5` |
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.5`, `3.3-beta.5` |
@@ -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.21'
30
- npm view '@adcp/sdk@17.0.0-beta.21' dist.integrity
29
+ npm install --save-exact '@adcp/sdk@17.0.0-beta.23'
30
+ npm view '@adcp/sdk@17.0.0-beta.23' dist.integrity
31
31
  ```
32
32
 
33
33
  ### Required and optional peers