@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
@@ -0,0 +1,282 @@
1
+ import { createHash } from "node:crypto";
2
+ import { canonicalJsonV1 } from "../source/index.mjs";
3
+ import {
4
+ projectReportingConsumerStatusMismatchV1,
5
+ projectReportingObligationHealthV1,
6
+ projectReportingUnreadableRevisionHealthV1
7
+ } from "./health.mjs";
8
+ import { addReportingInstantOffset, compareReportingInstantToOffset, compareReportingInstants } from "./instant.mjs";
9
+ const REPORTING_ISSUE_EVENT_KINDS_V1 = Object.freeze([
10
+ "opened",
11
+ "escalated",
12
+ "acknowledged",
13
+ "waived",
14
+ "resolved"
15
+ ]);
16
+ function reportingIssueEventIdV1(issueId, consumerId, kind) {
17
+ const digest = createHash("sha256").update(canonicalJsonV1(["reporting-issue-event-v1", issueId, consumerId, kind])).digest("hex");
18
+ return `rpie_${digest.slice(0, 40)}`;
19
+ }
20
+ function occurrenceKey(value) {
21
+ return canonicalJsonV1([value.issueId, value.consumerId]);
22
+ }
23
+ function reportingConsumerMismatchOccurrenceV1(obligation, leaf, revisions) {
24
+ if (!leaf || revisions.length === 0) return void 0;
25
+ const mismatch = projectReportingConsumerStatusMismatchV1(obligation, leaf, revisions, "healthy", leaf.recorded_at);
26
+ if (!mismatch) return void 0;
27
+ return {
28
+ issueId: mismatch.issue.issueId,
29
+ accountId: leaf.account_id,
30
+ consumerId: leaf.consumerId,
31
+ reportingObligationId: obligation.reporting_obligation_id,
32
+ reportingStatusId: leaf.reporting_status_id,
33
+ openedAt: mismatch.issue.openedAt
34
+ };
35
+ }
36
+ function eventRecord(occurrence, kind, occurredAt) {
37
+ return {
38
+ eventId: reportingIssueEventIdV1(occurrence.issueId, occurrence.consumerId, kind),
39
+ kind,
40
+ issueId: occurrence.issueId,
41
+ accountId: occurrence.accountId,
42
+ consumerId: occurrence.consumerId,
43
+ reportingObligationId: occurrence.reportingObligationId,
44
+ reportingStatusId: occurrence.reportingStatusId,
45
+ occurredAt
46
+ };
47
+ }
48
+ function planReportingIssueEventsV1(input) {
49
+ const conflicting = new Set(input.conflicts.map(occurrenceKey));
50
+ const open = new Set(input.open.map(occurrenceKey));
51
+ const resolved = input.open.filter((value) => !conflicting.has(occurrenceKey(value))).map(
52
+ (value) => eventRecord(
53
+ value,
54
+ "resolved",
55
+ compareReportingInstants(input.at, value.occurredAt) < 0 ? value.occurredAt : input.at
56
+ )
57
+ );
58
+ const opened = input.conflicts.filter((value) => !open.has(occurrenceKey(value))).map((value) => eventRecord(value, "opened", value.openedAt));
59
+ return [...resolved, ...opened];
60
+ }
61
+ function reportingIssueEscalationV1(opened, escalationSeconds, now) {
62
+ const window = escalationSeconds * 1e3;
63
+ if (compareReportingInstantToOffset(now, opened.occurredAt, window) < 0) return void 0;
64
+ return eventRecord(opened, "escalated", addReportingInstantOffset(opened.occurredAt, window));
65
+ }
66
+ function supportsReportingIssueEventsV1(store) {
67
+ if (typeof store !== "object" || store === null) return false;
68
+ const candidate = store;
69
+ return candidate.issueEventsSupported === true && typeof candidate.issueEventsReady === "function" && typeof candidate.sweepIssueEscalations === "function" && typeof candidate.claimIssueEvents === "function" && typeof candidate.completeIssueEvent === "function" && typeof candidate.releaseIssueEvent === "function" && typeof candidate.pruneIssueEvents === "function";
70
+ }
71
+ function renderReportingIssueEventV1(lease, context, escalation) {
72
+ const subscription = context?.obligation.subscription;
73
+ return {
74
+ eventId: lease.eventId,
75
+ kind: lease.kind,
76
+ occurredAt: lease.occurredAt,
77
+ accountId: lease.accountId,
78
+ consumerId: lease.consumerId,
79
+ ...subscription ? { principal: { tenantId: subscription.tenantId, principalId: subscription.principalId } } : {},
80
+ issueId: lease.issueId,
81
+ reportingObligationId: lease.reportingObligationId,
82
+ reportingStatusId: lease.reportingStatusId,
83
+ issue: lease.kind === "resolved" || !context ? null : renderIssueOrNull(lease, context, escalation),
84
+ attempt: lease.attempts
85
+ };
86
+ }
87
+ function renderIssueOrNull(lease, context, escalation) {
88
+ const { obligation, revisions, issues, statement } = context;
89
+ if (!revisions || !issues || !statement) return null;
90
+ try {
91
+ return renderIssue(lease, { obligation, revisions, issues, statement }, escalation);
92
+ } catch {
93
+ return null;
94
+ }
95
+ }
96
+ function renderIssue(lease, context, escalation) {
97
+ const at = lease.occurredAt;
98
+ const revisions = context.revisions.filter((value) => compareReportingInstants(value.createdAt, at) <= 0);
99
+ const issues = context.issues.filter(
100
+ (value) => compareReportingInstants(value.observedAt, at) <= 0 && (value.resolvedAt === void 0 || compareReportingInstants(value.resolvedAt, at) > 0)
101
+ );
102
+ const core = projectReportingObligationHealthV1(context.obligation, revisions, at);
103
+ const sellerHealth = projectReportingUnreadableRevisionHealthV1(context.obligation, revisions, issues, core.health);
104
+ const mismatch = projectReportingConsumerStatusMismatchV1(
105
+ context.obligation,
106
+ context.statement,
107
+ revisions,
108
+ sellerHealth,
109
+ at,
110
+ escalation
111
+ );
112
+ return mismatch?.issue.issueId === lease.issueId ? structuredClone(mismatch.issue) : null;
113
+ }
114
+ class ReportingIssueObserverError extends Error {
115
+ name = "ReportingIssueObserverError";
116
+ component;
117
+ /** The event being delivered, for `issue_observer` and `issue_events:snapshot`. */
118
+ eventId;
119
+ constructor(component, cause, eventId) {
120
+ super(
121
+ component === "issue_observer" ? `Reporting issue observer failed for ${eventId}; the event is retried` : component === "issue_events" ? "Reporting issue events could not be swept or claimed" : `Reporting issue event ${eventId} could not be rendered yet; it is retried`,
122
+ { cause }
123
+ );
124
+ this.component = component;
125
+ this.eventId = eventId;
126
+ }
127
+ }
128
+ function createReportingIssueEventDispatcherV1(options) {
129
+ const { store, observer, escalation } = options;
130
+ if (!supportsReportingIssueEventsV1(store)) {
131
+ throw new TypeError(
132
+ "The ledger store does not record issue events. Use memoryStorage(), or postgresStorage({ pool }) from @adcp/reporting-storage with migration 0012 applied."
133
+ );
134
+ }
135
+ if (typeof observer !== "function") throw new TypeError("The issue observer must be a function");
136
+ const timeout = positive(options.observerTimeoutMilliseconds ?? 1e4, "observerTimeoutMilliseconds");
137
+ const batchSize = positive(options.batchSize ?? 10, "batchSize");
138
+ const maxBatches = positive(options.maxBatches ?? 10, "maxBatches");
139
+ const retryBase = positive(options.retryBaseMilliseconds ?? 3e4, "retryBaseMilliseconds");
140
+ const retryCap = positive(options.retryCapMilliseconds ?? 36e5, "retryCapMilliseconds");
141
+ if (retryCap < retryBase) throw new RangeError("retryCapMilliseconds must be at least retryBaseMilliseconds");
142
+ const retention = options.retentionMilliseconds === null ? null : nonNegative(options.retentionMilliseconds ?? 7 * 864e5, "retentionMilliseconds");
143
+ const leaseMilliseconds = batchSize * timeout + 3e4;
144
+ const backoff = (attempts) => Math.min(retryCap, retryBase * 2 ** Math.min(Math.max(attempts - 1, 0), 20));
145
+ return {
146
+ leaseMilliseconds,
147
+ async runOnce(input = {}) {
148
+ const result = { escalationsRecorded: 0, delivered: 0, failed: 0, errors: [] };
149
+ const scope = input.accountId !== void 0 ? { accountId: input.accountId } : {};
150
+ if (escalation) {
151
+ try {
152
+ result.escalationsRecorded = await store.sweepIssueEscalations({
153
+ escalationSeconds: escalation.escalationSeconds,
154
+ ...scope
155
+ });
156
+ } catch (error) {
157
+ result.errors.push(new ReportingIssueObserverError("issue_events", error));
158
+ }
159
+ }
160
+ for (let batch = 0; batch < maxBatches && !input.signal?.aborted; batch += 1) {
161
+ let leases;
162
+ try {
163
+ leases = await store.claimIssueEvents({ leaseMilliseconds, limit: batchSize, ...scope });
164
+ } catch (error) {
165
+ result.errors.push(new ReportingIssueObserverError("issue_events", error));
166
+ break;
167
+ }
168
+ if (leases.length === 0) break;
169
+ const obligations = /* @__PURE__ */ new Map();
170
+ const evidence = /* @__PURE__ */ new Map();
171
+ const obligationOf = (lease) => cached(obligations, lease.reportingObligationId, () => readObligation(store, lease));
172
+ const evidenceOf = (lease) => cached(evidence, lease.reportingObligationId, async () => {
173
+ const obligation = await obligationOf(lease);
174
+ return obligation ? readEvidence(store, lease, obligation) : void 0;
175
+ });
176
+ for (const [index, lease] of leases.entries()) {
177
+ if (input.signal?.aborted) {
178
+ for (const pending of leases.slice(index)) {
179
+ await settle(() => store.releaseIssueEvent(pending, { retryAfterMilliseconds: 0 }));
180
+ }
181
+ break;
182
+ }
183
+ let context;
184
+ try {
185
+ if (lease.kind === "resolved") {
186
+ const obligation = await obligationOf(lease);
187
+ context = obligation ? { obligation } : void 0;
188
+ } else {
189
+ const read = await evidenceOf(lease);
190
+ context = read && lease.statement ? { ...read, statement: lease.statement } : read;
191
+ }
192
+ } catch (error) {
193
+ result.failed += 1;
194
+ result.errors.push(new ReportingIssueObserverError("issue_events:snapshot", error, lease.eventId));
195
+ await settle(() => store.releaseIssueEvent(lease, { retryAfterMilliseconds: backoff(lease.attempts) }));
196
+ continue;
197
+ }
198
+ const event = renderReportingIssueEventV1(lease, context, escalation);
199
+ try {
200
+ await withTimeout(
201
+ Promise.resolve().then(() => observer(Object.freeze(event))),
202
+ timeout
203
+ );
204
+ } catch (error) {
205
+ result.failed += 1;
206
+ result.errors.push(new ReportingIssueObserverError("issue_observer", error, lease.eventId));
207
+ await settle(() => store.releaseIssueEvent(lease, { retryAfterMilliseconds: backoff(lease.attempts) }));
208
+ continue;
209
+ }
210
+ try {
211
+ if (await store.completeIssueEvent(lease)) result.delivered += 1;
212
+ } catch (error) {
213
+ result.errors.push(new ReportingIssueObserverError("issue_events", error, lease.eventId));
214
+ }
215
+ }
216
+ }
217
+ if (retention !== null) {
218
+ try {
219
+ await store.pruneIssueEvents({ olderThanMilliseconds: retention });
220
+ } catch (error) {
221
+ result.errors.push(new ReportingIssueObserverError("issue_events", error));
222
+ }
223
+ }
224
+ return result;
225
+ }
226
+ };
227
+ }
228
+ function cached(cache, key, read) {
229
+ let value = cache.get(key);
230
+ if (!value) {
231
+ value = read();
232
+ cache.set(key, value);
233
+ }
234
+ return value;
235
+ }
236
+ async function readObligation(store, lease) {
237
+ const obligation = await store.getObligation(lease.reportingObligationId, lease.accountId);
238
+ return obligation && obligation.account.account_id === lease.accountId ? obligation : void 0;
239
+ }
240
+ async function readEvidence(store, lease, obligation) {
241
+ const revisions = typeof store.listRevisionMetadata === "function" ? await store.listRevisionMetadata(lease.reportingObligationId, lease.accountId) : (await store.listRevisions(lease.reportingObligationId)).map(({ rows: _rows, ...metadata }) => metadata);
242
+ const issues = await store.listIssues(lease.reportingObligationId);
243
+ return { obligation, revisions, issues };
244
+ }
245
+ async function settle(release) {
246
+ try {
247
+ await release();
248
+ } catch {
249
+ }
250
+ }
251
+ async function withTimeout(value, timeoutMilliseconds) {
252
+ let timer;
253
+ try {
254
+ await Promise.race([
255
+ value,
256
+ new Promise((_, reject) => {
257
+ timer = setTimeout(() => reject(new Error("Reporting issue observer timed out")), timeoutMilliseconds);
258
+ })
259
+ ]);
260
+ } finally {
261
+ if (timer) clearTimeout(timer);
262
+ }
263
+ }
264
+ function positive(value, name) {
265
+ if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${name} must be a positive integer`);
266
+ return value;
267
+ }
268
+ function nonNegative(value, name) {
269
+ if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative integer`);
270
+ return value;
271
+ }
272
+ export {
273
+ REPORTING_ISSUE_EVENT_KINDS_V1,
274
+ ReportingIssueObserverError,
275
+ createReportingIssueEventDispatcherV1,
276
+ planReportingIssueEventsV1,
277
+ renderReportingIssueEventV1,
278
+ reportingConsumerMismatchOccurrenceV1,
279
+ reportingIssueEscalationV1,
280
+ reportingIssueEventIdV1,
281
+ supportsReportingIssueEventsV1
282
+ };
@@ -18,7 +18,7 @@ import type { RequestContext } from '../../server/decisioning/context.mjs';
18
18
  import type { DecisioningPlatform } from '../../server/decisioning/platform.mjs';
19
19
  import type { ReliableReportingPlatform } from '../../server/decisioning/specialisms/reporting.mjs';
20
20
  import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '../../types/tools.generated.mjs';
21
- import { type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingLegacyRevisionReaderV1, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingSourceWithReaderV1 } from '../ledger/index.mjs';
21
+ import { type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingIssueEventDeliveryV1, type ReportingIssueObserverV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingLegacyRevisionReaderV1, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingSourceWithReaderV1 } from '../ledger/index.mjs';
22
22
  import type { InlineReportingReplayRetentionV1 } from '../source/index.mjs';
23
23
  import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source/index.mjs';
24
24
  import type { PrincipalLifecycleRuntime } from '../../server/principal/runtime.mjs';
@@ -186,6 +186,32 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
186
186
  /** Ledger metadata retention commitment advertised to buyers. */
187
187
  statusRetentionDays: number;
188
188
  subscribers?: CreateReportingProducerOptionsV1['subscribers'];
189
+ /**
190
+ * Called once per lifecycle transition of a `CONSUMER_STATUS_MISMATCH` occurrence (`opened`, `escalated`,
191
+ * `resolved`), so the seller hears about a caller-scoped issue without waiting for the buyer to poll.
192
+ *
193
+ * - **When.** The ledger records `opened` and `resolved` in the same transaction as the write that caused
194
+ * them (a `sync_reporting_status` statement, a revision commit). Each `runCycle` sweeps escalations
195
+ * (`escalated` once `openedAt` passes `consumerMismatchEscalation.escalationSeconds`) and then delivers
196
+ * committed events, each occurrence's in recording order. Without `runCycle` (`start()` or your own
197
+ * scheduler) events are recorded but the observer is never called, and `escalated` is never recorded.
198
+ * - **At least once.** A cycle that stops after the observer returned but before the event was marked
199
+ * delivered delivers it again with the same `eventId`. Deduplicate on it.
200
+ * - **Never in the buyer's call.** An observer that throws, or an async one past 10 seconds, is retried on a
201
+ * later cycle after a backoff of 30 seconds doubling to one hour, with no limit. The failure goes to the
202
+ * scheduler's `onError` as a `ReportingIssueObserverError`, and to `runCycle`'s `issueEvents.errors`.
203
+ * - **Kinds.** TypeScript stores never emit `acknowledged` or `waived` yet: the ledger has no operator
204
+ * issue-state API. The kinds are in the type for parity with the Python SDK.
205
+ *
206
+ * Needs a store that records issue events: `memoryStorage()`, or `postgresStorage({ pool })` from
207
+ * `@adcp/reporting-storage` with migration `0012 reporting_issue_events` applied. Refused at construction
208
+ * against any other store, and at the first cycle before the table exists. A closed occurrence (resolved,
209
+ * statement superseded or obligation gone) is pruned seven days after its last event was delivered; an open
210
+ * one is never pruned.
211
+ *
212
+ * @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
213
+ */
214
+ issueObserver?: ReportingIssueObserverV1;
189
215
  /**
190
216
  * Opt in to scheduled ledger maintenance (retention, compaction, change-feed pruning, abandoned-upload
191
217
  * sweeps) for a Core-only deployment. `start()` runs it at most once per `intervalMilliseconds`;
@@ -364,6 +390,13 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
364
390
  * one per principal or subscription. A failure never rejects the cycle.
365
391
  */
366
392
  subscriptionPlanningFailures?: SubscriptionPlanningFailure[];
393
+ /**
394
+ * With `issueObserver`: what this cycle's issue-event delivery did. Observer and store failures are in
395
+ * `errors` (and go to the scheduler's `onError`); they never reject the cycle.
396
+ *
397
+ * @experimental Reliable Reporting issue observer.
398
+ */
399
+ issueEvents?: ReportingIssueEventDeliveryV1;
367
400
  }>;
368
401
  /**
369
402
  * Run one ledger-maintenance pass now and return each task's outcome. For
@@ -378,6 +411,8 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
378
411
  }
379
412
  export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(input: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
380
413
  export { ReportingConfigurationImmutableError, isReportingConfigurationImmutableError } from '../ledger/index.mjs';
414
+ export { ReportingIssueObserverError, createReportingIssueEventDispatcherV1 } from '../ledger/index.mjs';
415
+ export type { ReportingIssueEventDeliveryV1, ReportingIssueEventDispatcherOptionsV1, ReportingIssueEventDispatcherV1, ReportingIssueEventKindV1, ReportingIssueEventV1, ReportingIssueObserverV1, } from '../ledger/index.mjs';
381
416
  export { defaultSubscriptionConfiguration } from './managed.mjs';
382
417
  export { coverageTraceForBuyer, diffCoverageTraces } from '../subscriptions/explain.mjs';
383
418
  export type { CoverageTrace, CoverageTraceDifference, CoverageTraceStep } from '../subscriptions/explain.mjs';
@@ -18,7 +18,7 @@ import type { RequestContext } from '../../server/decisioning/context';
18
18
  import type { DecisioningPlatform } from '../../server/decisioning/platform';
19
19
  import type { ReliableReportingPlatform } from '../../server/decisioning/specialisms/reporting';
20
20
  import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '../../types/tools.generated';
21
- import { type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingLegacyRevisionReaderV1, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingSourceWithReaderV1 } from '../ledger';
21
+ import { type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingIssueEventDeliveryV1, type ReportingIssueObserverV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingLegacyRevisionReaderV1, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingSourceWithReaderV1 } from '../ledger';
22
22
  import type { InlineReportingReplayRetentionV1 } from '../source';
23
23
  import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source';
24
24
  import type { PrincipalLifecycleRuntime } from '../../server/principal/runtime';
@@ -186,6 +186,32 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
186
186
  /** Ledger metadata retention commitment advertised to buyers. */
187
187
  statusRetentionDays: number;
188
188
  subscribers?: CreateReportingProducerOptionsV1['subscribers'];
189
+ /**
190
+ * Called once per lifecycle transition of a `CONSUMER_STATUS_MISMATCH` occurrence (`opened`, `escalated`,
191
+ * `resolved`), so the seller hears about a caller-scoped issue without waiting for the buyer to poll.
192
+ *
193
+ * - **When.** The ledger records `opened` and `resolved` in the same transaction as the write that caused
194
+ * them (a `sync_reporting_status` statement, a revision commit). Each `runCycle` sweeps escalations
195
+ * (`escalated` once `openedAt` passes `consumerMismatchEscalation.escalationSeconds`) and then delivers
196
+ * committed events, each occurrence's in recording order. Without `runCycle` (`start()` or your own
197
+ * scheduler) events are recorded but the observer is never called, and `escalated` is never recorded.
198
+ * - **At least once.** A cycle that stops after the observer returned but before the event was marked
199
+ * delivered delivers it again with the same `eventId`. Deduplicate on it.
200
+ * - **Never in the buyer's call.** An observer that throws, or an async one past 10 seconds, is retried on a
201
+ * later cycle after a backoff of 30 seconds doubling to one hour, with no limit. The failure goes to the
202
+ * scheduler's `onError` as a `ReportingIssueObserverError`, and to `runCycle`'s `issueEvents.errors`.
203
+ * - **Kinds.** TypeScript stores never emit `acknowledged` or `waived` yet: the ledger has no operator
204
+ * issue-state API. The kinds are in the type for parity with the Python SDK.
205
+ *
206
+ * Needs a store that records issue events: `memoryStorage()`, or `postgresStorage({ pool })` from
207
+ * `@adcp/reporting-storage` with migration `0012 reporting_issue_events` applied. Refused at construction
208
+ * against any other store, and at the first cycle before the table exists. A closed occurrence (resolved,
209
+ * statement superseded or obligation gone) is pruned seven days after its last event was delivered; an open
210
+ * one is never pruned.
211
+ *
212
+ * @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
213
+ */
214
+ issueObserver?: ReportingIssueObserverV1;
189
215
  /**
190
216
  * Opt in to scheduled ledger maintenance (retention, compaction, change-feed pruning, abandoned-upload
191
217
  * sweeps) for a Core-only deployment. `start()` runs it at most once per `intervalMilliseconds`;
@@ -364,6 +390,13 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
364
390
  * one per principal or subscription. A failure never rejects the cycle.
365
391
  */
366
392
  subscriptionPlanningFailures?: SubscriptionPlanningFailure[];
393
+ /**
394
+ * With `issueObserver`: what this cycle's issue-event delivery did. Observer and store failures are in
395
+ * `errors` (and go to the scheduler's `onError`); they never reject the cycle.
396
+ *
397
+ * @experimental Reliable Reporting issue observer.
398
+ */
399
+ issueEvents?: ReportingIssueEventDeliveryV1;
367
400
  }>;
368
401
  /**
369
402
  * Run one ledger-maintenance pass now and return each task's outcome. For
@@ -378,6 +411,8 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
378
411
  }
379
412
  export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(input: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
380
413
  export { ReportingConfigurationImmutableError, isReportingConfigurationImmutableError } from '../ledger';
414
+ export { ReportingIssueObserverError, createReportingIssueEventDispatcherV1 } from '../ledger';
415
+ export type { ReportingIssueEventDeliveryV1, ReportingIssueEventDispatcherOptionsV1, ReportingIssueEventDispatcherV1, ReportingIssueEventKindV1, ReportingIssueEventV1, ReportingIssueObserverV1, } from '../ledger';
381
416
  export { defaultSubscriptionConfiguration } from './managed';
382
417
  export { coverageTraceForBuyer, diffCoverageTraces } from '../subscriptions/explain';
383
418
  export type { CoverageTrace, CoverageTraceDifference, CoverageTraceStep } from '../subscriptions/explain';
@@ -21,8 +21,10 @@ var service_exports = {};
21
21
  __export(service_exports, {
22
22
  REPORTING_MANAGED_DELIVERY_COMPOSITION_V1: () => REPORTING_MANAGED_DELIVERY_COMPOSITION_V1,
23
23
  ReportingConfigurationImmutableError: () => import_ledger2.ReportingConfigurationImmutableError,
24
+ ReportingIssueObserverError: () => import_ledger3.ReportingIssueObserverError,
24
25
  coverageTraceForBuyer: () => import_explain.coverageTraceForBuyer,
25
26
  createReliableReportingService: () => createReliableReportingService,
27
+ createReportingIssueEventDispatcherV1: () => import_ledger3.createReportingIssueEventDispatcherV1,
26
28
  defaultSubscriptionConfiguration: () => import_managed2.defaultSubscriptionConfiguration,
27
29
  diffCoverageTraces: () => import_explain.diffCoverageTraces,
28
30
  isReportingConfigurationImmutableError: () => import_ledger2.isReportingConfigurationImmutableError
@@ -44,6 +46,7 @@ var import_capabilities = require('../subscriptions/capabilities.js');
44
46
  var import_subscriptions = require('./subscriptions.js');
45
47
  var import_managed = require('./managed.js');
46
48
  var import_ledger2 = require('../ledger/index.js');
49
+ var import_ledger3 = require('../ledger/index.js');
47
50
  var import_managed2 = require('./managed.js');
48
51
  var import_explain = require('../subscriptions/explain.js');
49
52
  __reExport(service_exports, require('./conformance.js'), module.exports);
@@ -165,6 +168,42 @@ function createReliableReportingService(input) {
165
168
  );
166
169
  const advertisedConsumerMismatchEscalation = hasConsumerStatus ? effectiveConsumerMismatchEscalation : void 0;
167
170
  if (hasConsumerStatus) assertConsumerStatusStore(options.store);
171
+ let issueEvents;
172
+ if (options.issueObserver !== void 0) {
173
+ if (typeof options.issueObserver !== "function") {
174
+ throw new import_validate_platform.PlatformConfigError("issueObserver must be a function.", { configField: "issueObserver" });
175
+ }
176
+ const issueStore = options.store;
177
+ if (!(0, import_ledger.supportsReportingIssueEventsV1)(issueStore)) {
178
+ throw new import_validate_platform.PlatformConfigError(
179
+ "issueObserver needs a ledger store that records issue events. Use storage: memoryStorage() (@adcp/sdk/storage), or postgresStorage({ pool }) from @adcp/reporting-storage with migration 0012 applied (npx adcp-reporting-storage migrate).",
180
+ { configField: "issueObserver" }
181
+ );
182
+ }
183
+ issueEvents = (0, import_ledger.createReportingIssueEventDispatcherV1)({
184
+ store: issueStore,
185
+ observer: options.issueObserver,
186
+ // The same window the reads enforce and the capability document advertises.
187
+ ...effectiveConsumerMismatchEscalation ? { escalation: effectiveConsumerMismatchEscalation } : {}
188
+ });
189
+ }
190
+ let issueEventsChecked;
191
+ const checkIssueEvents = () => {
192
+ if (!issueEvents || !(0, import_ledger.supportsReportingIssueEventsV1)(options.store)) return Promise.resolve();
193
+ const store = options.store;
194
+ issueEventsChecked ??= store.issueEventsReady().then((ready) => {
195
+ if (!ready) {
196
+ throw new import_validate_platform.PlatformConfigError(
197
+ 'issueObserver needs the issue-event table (migration 0012 reporting_issue_events). Run "npx adcp-reporting-storage migrate" against this database.',
198
+ { code: "REPORTING_SCHEMA_BEHIND", configField: "issueObserver" }
199
+ );
200
+ }
201
+ }).catch((error) => {
202
+ issueEventsChecked = void 0;
203
+ throw error;
204
+ });
205
+ return issueEventsChecked;
206
+ };
168
207
  const retentionDays = options.statusRetentionDays;
169
208
  positiveInteger(retentionDays, "statusRetentionDays");
170
209
  let maintenance;
@@ -646,6 +685,7 @@ function createReliableReportingService(input) {
646
685
  simulatedNow = cycle.now;
647
686
  cycle.signal?.throwIfAborted();
648
687
  await checkSchema();
688
+ await checkIssueEvents();
649
689
  const sweepFailures = managed ? await managed.sweep(cycle.signal) : [];
650
690
  const subscriptionPlanning = subscriptionOptions ? await planSubscriptionCycle(subscriptionOptions, accountId, planningNow, cycle.signal) : void 0;
651
691
  const planned = await producer.planObligations(planningNow.toISOString(), {
@@ -664,6 +704,10 @@ function createReliableReportingService(input) {
664
704
  ...cycle.executionDeadlineMilliseconds !== void 0 ? { executionDeadlineMilliseconds: cycle.executionDeadlineMilliseconds } : {},
665
705
  ...cycle.settlementGraceMilliseconds !== void 0 ? { settlementGraceMilliseconds: cycle.settlementGraceMilliseconds } : {}
666
706
  });
707
+ const issueDelivery = issueEvents && !cycle.signal?.aborted ? await issueEvents.runOnce({
708
+ ...accountId !== void 0 ? { accountId } : {},
709
+ ...cycle.signal ? { signal: cycle.signal } : {}
710
+ }) : void 0;
667
711
  if (subscriptionPlanning?.failures.length) {
668
712
  if (subscriptionOptions.onPlanningError) {
669
713
  for (const failure of subscriptionPlanning.failures) {
@@ -679,6 +723,7 @@ function createReliableReportingService(input) {
679
723
  return {
680
724
  planned: planned.length + (subscriptionPlanning?.planned ?? 0),
681
725
  ...result,
726
+ ...issueDelivery ? { issueEvents: issueDelivery } : {},
682
727
  ...managed ? {
683
728
  subscriptionPlanningFailures: [
684
729
  ...sweepFailures,
@@ -766,7 +811,7 @@ async function schedulerLoop(service, options, signal, store, maintenance) {
766
811
  for (const accountId of accountIds) {
767
812
  if (signal.aborted) break;
768
813
  try {
769
- await service.runCycle({
814
+ const cycle = await service.runCycle({
770
815
  ...accountId === void 0 ? { deploymentWide: true } : { accountId },
771
816
  signal,
772
817
  ...options.maxHistoryObligationsPerSource !== void 0 ? { maxHistoryObligationsPerSource: options.maxHistoryObligationsPerSource } : {},
@@ -777,6 +822,9 @@ async function schedulerLoop(service, options, signal, store, maintenance) {
777
822
  ...options.executionDeadlineMilliseconds !== void 0 ? { executionDeadlineMilliseconds: options.executionDeadlineMilliseconds } : {},
778
823
  ...options.settlementGraceMilliseconds !== void 0 ? { settlementGraceMilliseconds: options.settlementGraceMilliseconds } : {}
779
824
  });
825
+ for (const error of cycle.issueEvents?.errors ?? []) {
826
+ await (0, import_scheduler_support.reportReportingSchedulerError)(options, signal, error, { phase: "issue_observer", accountId });
827
+ }
780
828
  } catch (error) {
781
829
  await (0, import_scheduler_support.reportReportingSchedulerError)(options, signal, error, { phase: "cycle", accountId });
782
830
  }
@@ -1220,8 +1268,10 @@ function deepFreeze(value) {
1220
1268
  0 && (module.exports = {
1221
1269
  REPORTING_MANAGED_DELIVERY_COMPOSITION_V1,
1222
1270
  ReportingConfigurationImmutableError,
1271
+ ReportingIssueObserverError,
1223
1272
  coverageTraceForBuyer,
1224
1273
  createReliableReportingService,
1274
+ createReportingIssueEventDispatcherV1,
1225
1275
  defaultSubscriptionConfiguration,
1226
1276
  diffCoverageTraces,
1227
1277
  isReportingConfigurationImmutableError,
@@ -9,7 +9,9 @@ import {
9
9
  createReportingDeliveryHandler,
10
10
  createReportingProducer,
11
11
  createReportingStatusHandler,
12
- createSyncReportingStatusHandler
12
+ createSyncReportingStatusHandler,
13
+ createReportingIssueEventDispatcherV1,
14
+ supportsReportingIssueEventsV1
13
15
  } from "../ledger/index.mjs";
14
16
  import {
15
17
  reportReportingSchedulerError,
@@ -163,6 +165,42 @@ function createReliableReportingService(input) {
163
165
  );
164
166
  const advertisedConsumerMismatchEscalation = hasConsumerStatus ? effectiveConsumerMismatchEscalation : void 0;
165
167
  if (hasConsumerStatus) assertConsumerStatusStore(options.store);
168
+ let issueEvents;
169
+ if (options.issueObserver !== void 0) {
170
+ if (typeof options.issueObserver !== "function") {
171
+ throw new PlatformConfigError("issueObserver must be a function.", { configField: "issueObserver" });
172
+ }
173
+ const issueStore = options.store;
174
+ if (!supportsReportingIssueEventsV1(issueStore)) {
175
+ throw new PlatformConfigError(
176
+ "issueObserver needs a ledger store that records issue events. Use storage: memoryStorage() (@adcp/sdk/storage), or postgresStorage({ pool }) from @adcp/reporting-storage with migration 0012 applied (npx adcp-reporting-storage migrate).",
177
+ { configField: "issueObserver" }
178
+ );
179
+ }
180
+ issueEvents = createReportingIssueEventDispatcherV1({
181
+ store: issueStore,
182
+ observer: options.issueObserver,
183
+ // The same window the reads enforce and the capability document advertises.
184
+ ...effectiveConsumerMismatchEscalation ? { escalation: effectiveConsumerMismatchEscalation } : {}
185
+ });
186
+ }
187
+ let issueEventsChecked;
188
+ const checkIssueEvents = () => {
189
+ if (!issueEvents || !supportsReportingIssueEventsV1(options.store)) return Promise.resolve();
190
+ const store = options.store;
191
+ issueEventsChecked ??= store.issueEventsReady().then((ready) => {
192
+ if (!ready) {
193
+ throw new PlatformConfigError(
194
+ 'issueObserver needs the issue-event table (migration 0012 reporting_issue_events). Run "npx adcp-reporting-storage migrate" against this database.',
195
+ { code: "REPORTING_SCHEMA_BEHIND", configField: "issueObserver" }
196
+ );
197
+ }
198
+ }).catch((error) => {
199
+ issueEventsChecked = void 0;
200
+ throw error;
201
+ });
202
+ return issueEventsChecked;
203
+ };
166
204
  const retentionDays = options.statusRetentionDays;
167
205
  positiveInteger(retentionDays, "statusRetentionDays");
168
206
  let maintenance;
@@ -644,6 +682,7 @@ function createReliableReportingService(input) {
644
682
  simulatedNow = cycle.now;
645
683
  cycle.signal?.throwIfAborted();
646
684
  await checkSchema();
685
+ await checkIssueEvents();
647
686
  const sweepFailures = managed ? await managed.sweep(cycle.signal) : [];
648
687
  const subscriptionPlanning = subscriptionOptions ? await planSubscriptionCycle(subscriptionOptions, accountId, planningNow, cycle.signal) : void 0;
649
688
  const planned = await producer.planObligations(planningNow.toISOString(), {
@@ -662,6 +701,10 @@ function createReliableReportingService(input) {
662
701
  ...cycle.executionDeadlineMilliseconds !== void 0 ? { executionDeadlineMilliseconds: cycle.executionDeadlineMilliseconds } : {},
663
702
  ...cycle.settlementGraceMilliseconds !== void 0 ? { settlementGraceMilliseconds: cycle.settlementGraceMilliseconds } : {}
664
703
  });
704
+ const issueDelivery = issueEvents && !cycle.signal?.aborted ? await issueEvents.runOnce({
705
+ ...accountId !== void 0 ? { accountId } : {},
706
+ ...cycle.signal ? { signal: cycle.signal } : {}
707
+ }) : void 0;
665
708
  if (subscriptionPlanning?.failures.length) {
666
709
  if (subscriptionOptions.onPlanningError) {
667
710
  for (const failure of subscriptionPlanning.failures) {
@@ -677,6 +720,7 @@ function createReliableReportingService(input) {
677
720
  return {
678
721
  planned: planned.length + (subscriptionPlanning?.planned ?? 0),
679
722
  ...result,
723
+ ...issueDelivery ? { issueEvents: issueDelivery } : {},
680
724
  ...managed ? {
681
725
  subscriptionPlanningFailures: [
682
726
  ...sweepFailures,
@@ -764,7 +808,7 @@ async function schedulerLoop(service, options, signal, store, maintenance) {
764
808
  for (const accountId of accountIds) {
765
809
  if (signal.aborted) break;
766
810
  try {
767
- await service.runCycle({
811
+ const cycle = await service.runCycle({
768
812
  ...accountId === void 0 ? { deploymentWide: true } : { accountId },
769
813
  signal,
770
814
  ...options.maxHistoryObligationsPerSource !== void 0 ? { maxHistoryObligationsPerSource: options.maxHistoryObligationsPerSource } : {},
@@ -775,6 +819,9 @@ async function schedulerLoop(service, options, signal, store, maintenance) {
775
819
  ...options.executionDeadlineMilliseconds !== void 0 ? { executionDeadlineMilliseconds: options.executionDeadlineMilliseconds } : {},
776
820
  ...options.settlementGraceMilliseconds !== void 0 ? { settlementGraceMilliseconds: options.settlementGraceMilliseconds } : {}
777
821
  });
822
+ for (const error of cycle.issueEvents?.errors ?? []) {
823
+ await reportReportingSchedulerError(options, signal, error, { phase: "issue_observer", accountId });
824
+ }
778
825
  } catch (error) {
779
826
  await reportReportingSchedulerError(options, signal, error, { phase: "cycle", accountId });
780
827
  }
@@ -1215,6 +1262,7 @@ function deepFreeze(value) {
1215
1262
  return value;
1216
1263
  }
1217
1264
  import { ReportingConfigurationImmutableError, isReportingConfigurationImmutableError } from "../ledger/index.mjs";
1265
+ import { ReportingIssueObserverError, createReportingIssueEventDispatcherV1 as createReportingIssueEventDispatcherV12 } from "../ledger/index.mjs";
1218
1266
  import { defaultSubscriptionConfiguration } from "./managed.mjs";
1219
1267
  import { coverageTraceForBuyer, diffCoverageTraces } from "../subscriptions/explain.mjs";
1220
1268
  export * from "./conformance.mjs";
@@ -1222,8 +1270,10 @@ export * from "./scheduler-support.mjs";
1222
1270
  export {
1223
1271
  REPORTING_MANAGED_DELIVERY_COMPOSITION_V1,
1224
1272
  ReportingConfigurationImmutableError,
1273
+ ReportingIssueObserverError,
1225
1274
  coverageTraceForBuyer,
1226
1275
  createReliableReportingService,
1276
+ createReportingIssueEventDispatcherV12 as createReportingIssueEventDispatcherV1,
1227
1277
  defaultSubscriptionConfiguration,
1228
1278
  diffCoverageTraces,
1229
1279
  isReportingConfigurationImmutableError
@@ -36,7 +36,7 @@ export interface ReportingSchedulerReportingOptionsV1 {
36
36
  }
37
37
  /** Where in the scheduler loop a failure happened. */
38
38
  export interface ReportingSchedulerFailureSiteV1 {
39
- readonly phase: 'roster' | 'cycle' | 'maintenance';
39
+ readonly phase: 'roster' | 'cycle' | 'maintenance' | 'issue_observer';
40
40
  readonly accountId?: string | undefined;
41
41
  }
42
42
  export declare function reportReportingSchedulerError(options: ReportingSchedulerReportingOptionsV1, signal: AbortSignal, error: unknown, site: ReportingSchedulerFailureSiteV1): Promise<void>;