[bokelley]

Fifth of the series for #3504, and the second of two stacked PRs that write subscription obligations into the reporting ledger. It stacks on #3517 (which stacks on #3509), so it contains every earlier commit. Review only feat(reporting): plan and execute subscription obligations in the service (209ded8). It targets main because CI runs only for PRs into main.

What ships

Engine

• frozenOwedSets(principal, { accountId? }) returns, per (account, subscription):

  • the frozen horizon through
  • the frozen obligations, grouped with byte-sorted media_buy_ids
  • every retained version's configuration

  It never returns the provisional periods owedPeriods computes past through, because ledger obligations are immutable.

• listPrincipals(tenantId) wraps the engine store.

Service

In createReliableReportingService({ reportingSubscriptions }), runCycle first plans each listed principal's frozen owed sets, on the cycle's account. It then plans account configurations as before, and the worker executes both.

• Each (version, offering) generation goes through the same trusted path as installConfiguration. That path is now one shared prepareGeneration:

  • the delivery-offering checks
  • resolveSource, resolveCurrency and resolveCoverage
  • the reserved-key and credential checks on the source scope
  • the frozen schedule identity

  For a generation from a subscription version and its resolved offering:

  • The subscription version supplies identity, feed_purpose and required_finality.
  • The resolved offering supplies the report definition and schedule.
  • Owed-set generations skip only assertSupportedScheduleSemantics and the keyless-predecessor reuse.

• Each obligation freezes the host-authorized constituents of exactly its media buys. If a media buy the engine says is owed has no authorized constituent, that subscription fails closed.

• owedThrough is min(engine through, cycle now).

• Option changes:

  • New and required when subscriptions are advertised:
    • listSubscriptionPrincipals(), for example engine.listPrincipals(tenantId) across your tenants
    • resolveSubscriptionConfiguration({ principal, account, subscription, offering, sourceOffering }), which returns requested metrics and dimensions, source settings, and the finalityPolicy or canonicalization an official or billing subscription needs
  • Optional: resolveSubscriptionAccount(accountId), which defaults to { id, ctx_metadata: {} }, and onPlanningError.

• Failures are isolated per subscription. One subscription never stops another or the account's own configurations. Without onPlanningError, runCycle rejects with an AggregateError after the rest of the cycle has run.

• resolvePrincipal now also scopes reads and status ingest. get_reporting_status, get_media_buy_delivery and sync_reporting_status use it through feat(reporting): hold subscription obligations in the reporting ledger #3517's resolveSubscriptionPrincipal. Without subscriptions no scope is passed, and every handler is exactly the pre-3.3 one.

• Docs: docs/guides/REPORTING-LEDGER.md gains a subscription section.

Tests

test/lib/reporting-subscription-service.test.js:

• Option off, byte for byte. A deterministic transcript covers install, a cycle, the summary and periods views, sync_reporting_status, get_media_buy_delivery, and the ledger records behind them. It is compared against test/fixtures/reporting-subscriptions/ledger-option-off-golden.json, captured by building and running the same transcript on feat(reporting): buyer runtime and durable storage for reporting subscriptions (#3504, 3/3) #3509's head (800adfc). The only normalization replaces real-clock install and creation stamps.
• End to end. Two principals hold the same analytics-daily subscription on one account with different buys. The engine reconciles, and one cycle plans and executes 5 obligations through the inline source. Each source request carries that period's frozen media buys, including a period with two buys. A second cycle is idempotent. Visibility:
  • Principal A sees its 4 periods with offering_id, one generation, and health complete.
  • B sees its 1 period.
  • A principal without a subscription sees nothing.
  • B cannot read A's revision by id.
• Failure isolation. One principal's policy hook throws: the other principal's obligations are still planned and executed, and the cycle rejects with an AggregateError.
• Construction. The service refuses to construct without the required hooks.

reliable-reporting-service.test.js passes the new required options.

Deviations from the brief

• resolveSubscriptionConfiguration is a required host hook. The SDK has no code path that maps a sync_accounts configuration onto install input; the host does that today. sourceSettings (version, digest, snapshot ref) and the official finality policy are seller policy that cannot be derived from the subscription or the offering.
• The service still refuses non-utc/source_timezone and non-whole-day offerings at construction. Lifting that gate would advertise offerings that account configurations cannot install. So in this service, subscription periods are whole-day utc/source_timezone, even though the ledger API (feat(reporting): hold subscription obligations in the reporting ledger #3517) accepts any engine period. Relaxing the construction gate for subscription-only offerings is a follow-up.
• A resolved offering with managed delivery is refused per subscription. That means a method, or a reconciliation_mode other than delivery_only. Managed delivery is out of scope here.

Left for the managed-delivery PR

• Destination. A subscription generation carries subscription.{tenantId, principalId, subscriptionId} and its version. Resolve the destination from that version's destination.destination_id through the principal runtime (listReportingSubscriptions), and expand path_template with expandReportingSubscriptionPathTemplate.
• Managed bindings. Binding install looks generations up by (account, delivery_config_id, delivery_config_version) (managed/postgres.ts), and adcp_reporting_managed_bindings is UNIQUE (account_id, delivery_config_id, delivery_config_version). Both need the configuration id or subscription_key.
• Lifecycle notifications. subscribers receive status transitions of every principal's subscription obligations on an account. Notification fanout should be scoped to the owner.
• Receipts after lost authority. engine.acceptsReceipt still has to be applied in receipt and status ingest.

Local checks

• typecheck, lint:boundaries, check:package-size and Prettier pass.
• 566 tests pass across the ledger, service, status-ingest, calendar, consumer-status and subscription suites, including the engine, coverage, consumer and principal suites.

Update: main's beta release (#3521) changed scripts/check-package-size.mjs, which conflicted with the stack. I merged origin/main into bokelley/reporting-subscription-ledger and carried that merge up through the stacked branches. The only conflict was the file-count budget, and I resolved it by keeping both sides' entries. The merge commits change nothing else.

Refs #3504

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — no blocking or medium findings.

Reviewed the reporting-subscription ledger/service work (focus commit 209ded8 plus the load-bearing paths it builds on). Verified fail-closed behavior where it matters: owed-buy coverage check, owedThrough capped at the cycle clock, per-subscription failure isolation with abort propagating outside the try, and multi-tenant visibility gated by subscription_principal with handler-level defense-in-depth. The postgres migration is catalog-guarded and builds the widened unique index before dropping the legacy constraint — additive/idempotent. Five changesets correctly cover the opt-in additive surface; new 3.3 wire fields are emitted only when the served bundle defines them, satisfying the DR-0033 pathway-back rule.

Decision trace: no critical/high findings (row 1 n/a); gated_paths false (row 2 n/a); high_risk false, no deletions (rows 3/5 n/a); no medium findings (rows 4/8 n/a); no prior decision (row 6 n/a); no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve. Note: review_decision is REVIEW_REQUIRED, but with gated_paths false that does not block auto-approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean pass, no blocking or medium findings.

Checked against the decision table top-down:

• Rows 1 (critical/high) — no findings of any severity.
• Row 2 (gated_paths) — gated_paths is false; does not fire despite review_decision=REVIEW_REQUIRED.
• Row 3/5 (high_risk) — high_risk is false.
• Row 4 (medium data-loss/schema/infra) — no medium findings.
• Row 6 (sticky escalate) — prior decision was approve, not escalate.
• Row 7 (no-auto-approve team) — no team match.
• Row 8 (≥3 medium) — zero medium findings.
• Row 9 — falls through to approve.

Reviewer verified the load-bearing concerns for this SDK: acceptEnvelopeOnClosedResponseRoot is stricter than the removed relaxResponseRoot (closed roots stay additionalProperties:false, body typos still rejected, composing bundles untouched); collectWholesaleProductPages loop is bounded with abort checks and idempotency; per-page invariant failures propagate correctly; witness-not-translator preserved (payload returned verbatim, no fabrication); removed/renamed exports are @internal so changeset impact is minor and appropriate.

No wire-fidelity, changeset-vs-impact, or doc-link concerns surfaced.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean pass, no blocking findings.

Checked: AdCP 3.3.0-beta.1 → beta.2 adoption (version/generated/docs bumps), typed RequestValidationError / isPreDispatchError markers across errors/index.ts, SingleAgentClient.ts, TaskExecutor.ts, client-hooks.ts, schema-errors.ts and the storyboard runner, and the ESM/CJS schema-loader binding for envelope-status checks (envelope-status-compat.ts + schema-loader.ts bindEnvelopeSchemaLoader). Verified RequestValidationError inherits code 'VALIDATION_ERROR' with dispatched:false; FeatureUnsupported/ProtocolFeatureUnsupported inherit the marker. The largest delta file creative-delivery.ts reconcileLegacyAssignmentRefs is the documented, tested per-axis shared-ref design, not a defect. Three changesets present and correctly scoped (minor for beta.2 adoption + typed error, patch for the legacy-ref regression fix) — satisfies changeset-vs-wire-impact.

Decision path: no critical/high/medium findings (table row 1/4/5/8 not triggered). gated_paths is false (row 2 n/a despite REVIEW_REQUIRED). high_risk false (rows 3/5 n/a). Prior decision was approve (row 6 n/a). No no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve.

[aao-secretariat]

Ladon cannot review this PR until merge conflicts are resolved.

[aao-secretariat]

Ladon verdict: Approve

Approve — subsequent pass, clean diff, no findings.

This is a follow-up pass on prior-approved PR #3518. The delta is small (4 files) and CI/test-only: an empty-frontmatter CI changeset, comment-only annotations on the packed-tarball budget in check-package-size.mjs (the 26_520_000 cap unchanged), a pre-dispatch-errors test swapping a retired 3.3.0-beta.1 literal for ADCP_VERSION (seller caps remain 3.3-beta.0, feature-refusal assertion still holds), and a single-line string collapse in reporting-subscription-coverage. No src/lib or bin code touched; changeset-vs-wire and witness-not-translator rules have no new surface.

Decision table walk-through:

• Rows 1 (critical/high): no findings — skip.
• Row 2 (gated_paths + not APPROVED): gated_paths is false — skip.
• Row 3 (deleted high-risk): high_risk false — skip.
• Row 4/5 (medium data-loss/schema/infra or modified high-risk+medium): no medium findings — skip.
• Row 6 (sticky escalate): prior decision was approve — skip.
• Row 7 (no-auto-approve team): no team match — skip.
• Row 8 (≥3 medium): zero medium findings — skip.
• Row 9: approve.

Note: review_decision is REVIEW_REQUIRED, but gated_paths is false, so row 2 does not apply, and REVIEW_REQUIRED alone is not an approve blocker (the protected-branch rule is deprecated). Prior approve stands.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean delta pass, no blocking or medium findings.

What I checked:

• No critical/high/medium findings in this run.
• gated_paths: false → row 2 does not apply even though review_decision is REVIEW_REQUIRED.
• high_risk: false, no deletions.
• No no-auto-approve team match.
• Prior decision was approve; this is a consistent follow-up.

Change summary (all fail-closed and tested):

• calendar.ts refuses sub-daily billing_cycle alignment (adcp#8622) before it would silently align to local midnight — correct witness behavior.
• engine.ts replaces withheld.at(-1) with latestPeriodEnd() for unordered frozen periods; refreshes open action_required pending_action via JCS canonicalize with principal.changed firing.
• server/principal/reporting-subscriptions.ts narrows the flag reset from !== true to === false, so an omitted replace_account_configs no longer drops a committed retry or re-runs the destructive hook.

Changesets present. No decision-table trigger fired (rows 1–8 all clear) → falls through to row 9.

The merge-base changed after approval.