[bokelley]

Fourth of the series for #3504, and the first of two stacked PRs that write subscription obligations into the reporting ledger. It stacks on #3509, so it contains the commits of #3505, #3508 and #3509. Review only feat(reporting): hold subscription obligations in the reporting ledger (a74b552). It targets main because CI runs only for PRs into main. The follow-up PR wires the service to the engine.

The engine already computes the seller's owed set, but nothing wrote it into the ledger, so the producer never executed subscription obligations. This PR makes the ledger and the PostgreSQL store hold them, and adds a planner API.

What ships

Identity

There is one ledger generation per (account, owning principal, subscription_id, subscription_version, resolved offering_id).

• delivery_config_id is the subscription_id and delivery_config_version is the subscription_version, as get-reporting-status-response.json subscription_coverage requires.
• ReportingLedgerConfigurationV1.subscription is an immutable block in the fingerprint: { tenantId, principalId, subscriptionId, offeringId, ownership: 'owed_set' }. Obligations copy it, so ownership can be checked from the obligation alone.
• A subscription generation's configurationId digests the owner and offering as well. Account generations keep exactly today's id and fingerprint (tested), and so do their rows.
• installConfiguration refuses a subscription block; subscription generations go only through the planner.

Planner API

producer.planSubscriptionObligations({ account_id, principal, subscriptionId, configurations, obligations, owedThrough, now? }):

1. Installs each (version, offering) generation once, idempotently. A changed input throws ReportingConfigurationImmutableError.
2. Writes each obligation through store.putObligation. Each one carries:
   • its own period
   • media_buy_ids frozen at its scope_resolved_at (the period end)
   • the constituents of exactly those buys
   • periodOrdinal = floor(period_start_ms / 1000)
   • expected_at = period end + the offering's delivery_sla
3. Advances owedSet.through on every generation this subscription owns on the account, after the obligations are durable.

Obligations are never grid-filled: planObligations skips owed-set generations. Retired periods are skipped.

Owed-set completeness

owedSet is mutable and outside the fingerprint, the same way historyStart is. It holds:

• through: the completeness horizon
• from, until and mediaBuyIds: a monotonic summary of the written obligations, used for relevance and media_buy_ids scope matching

The generation's own mediaBuyIds/constituents are empty and never read. evaluateReportingLedgerCoverageV1 has an owed-set branch:

• The obligations present are the owed set by construction, so a gap never raises a continuity error. This holds in both the memory store and PostgreSQL createSnapshot.
• A scope whose end is after through returns owedSetOpen. The handler then reports scope_closed: false and keeps coverage_complete: true, because an owed set still being frozen is not missing history (coverage_complete: false would force HISTORY_UNAVAILABLE).

The other grid paths use only existing obligations for an owed set:

• next_expected_at projects nothing from the grid.
• The successor and history-overlap rules ignore owed sets.
• In status ingest, a status without reporting_obligation_id matches an existing owed obligation by ordinal (new optional findObligationByOrdinal, falling back to listObligations), never a bare grid slot.
• The frozen-calendar proof skips owed sets.

Visibility

ReportingLedgerSnapshotQueryV1.subscription_principal scopes snapshots to account generations plus the caller's own subscription generations and obligations. With no principal, no subscription generation is visible. It is part of the snapshot query, so cursors and changes checkpoints are bound to it.

• createReportingStatusHandler, createReportingDeliveryHandler and createSyncReportingStatusHandler take resolveSubscriptionPrincipal.
• The status handler fails closed if a store returns another principal's generation.
• get_media_buy_delivery answers another principal's revision with REFERENCE_NOT_FOUND and never falls through to the legacy reader.
• Status ingest treats another principal's generation as unknown.
• offering_id is emitted on subscription obligations to callers served 3.3. It is in 3.3.0-beta.1's reporting-obligation.json.

Store contract and PostgreSQL

• New optional ReportingLedgerStore.recordOwedSetProgress (monotonic merge under the account fence) and findObligationByOrdinal. The producer refuses to plan into a store without recordOwedSetProgress.
• REPORTING_LEDGER_MIGRATION changes the generation key:
  • It adds subscription_key TEXT NOT NULL DEFAULT '' under a catalog guard. The key is reportingLedgerSubscriptionKeyV1: a digest of owner and offering, empty for account generations.
  • It creates the unique index adcp_reporting_configurations_generation (account_id, delivery_config_id, delivery_config_version, subscription_key) before dropping the published three-column constraint.
  • A guarded DO $$ block finds that constraint in pg_constraint by its columns, not by name.
  • The migration is idempotent and additive, and existing rows keep their uniqueness. A fresh schema creates the table without the old constraint.
• The version-regression check and history-overlap reads are scoped to subscription_key = ''.
• Snapshot configurations and obligations filter on data->'subscription'.
• The consumer-status snapshot query uses EXISTS instead of a join, since several visible generations can share an (id, version). For account generations the result is the same, because the join matched at most one row.
• The memory test store mirrors all of this.

Tests

• test/lib/reporting-subscription-ledger.test.js (memory store):
  • sparse obligations with no continuity error and no grid fill
  • owedThrough completeness: scope open, then closed, and never regressing
  • several offerings in one version
  • two principals with the same subscription_id: generations, snapshots, revision reads, and a leaky-store refusal
  • frozen media_buy_ids per period, and media-buy scope matching
  • status ingest that accepts only the caller's owed periods
  • unsafe plans refused
  • account generation ids and fingerprints unchanged
• packages/reporting-storage/test/reporting-subscription-ledger-pg.test.js, in the reporting-storage parallel group that CI runs with REPORTING_LEDGER_PG_URL:
  • the migration on a fresh schema and on the published layout with an existing row, twice each
  • the dropped constraint and the widened key
  • two principals and an account generation sharing (account, id, version)
  • owed-set progress and findObligationByOrdinal
  • per-principal snapshots and the status handler

Spec ambiguities

• scope.delivery_config_generations items are (delivery_config_id, delivery_config_version, feed_purpose) with uniqueItems. Every offering one subscription version resolves shares the selector's feed_purpose, so per-offering generations collapse into one wire entry. Obligations tell them apart by offering_id.
• The consumer-status chain identity (delivery_config_id, delivery_config_version, report_definition_id, period) cannot tell apart two offerings of one version that share a report definition and a period. Ingest accepts the status against any matching visible generation.
• next_expected_at in a complete summary "MUST" name the next scheduled period start. An owed set's future periods depend on buys the ledger cannot see, so owed-set generations contribute none.
• The spec says nothing about how a seller signals that an owed set is not yet frozen through a scope's end. I use scope_closed: false and leave coverage_complete true.

Deviations from the brief

• Visibility filters on JSON, with no owner column. It uses data->'subscription' rather than adding a column beside subscription_key.
• The plan input names the account, owner and subscription_id explicitly. That way a cycle with no new obligations still advances the horizon of existing generations.
• owedSet also carries from, until and mediaBuyIds. Relevance and media_buy_ids scope checks need them. All of them only widen.
• No version-regression check for subscription generations. An older version's offering can be frozen after a newer version's generation exists.
• Grid schedule validation is skipped for owed-set generations. The ledger accepts any engine period (P1M, account_timezone, sub-daily) and stores the offering's schedule identity verbatim.

Local checks

• typecheck, typecheck:reporting-storage, lint:boundaries, check:package-size and Prettier pass. The packed budget is +60 KB with a comment; no module files were added.
• The ledger, service, status-ingest and subscription suites pass.
• The new PostgreSQL suite, reporting-history-pg and most of reporting-status-ingest-pg pass against PGlite locally. CI runs them on PostgreSQL 16.

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 — AdCP 3.3 principal-level reporting subscriptions (experimental, opt-in) across 52 files, no blocking findings.

Checked:

• No Critical/High/Medium findings reported.
• Witness-not-translator honored: 3.3-only wire fields (reporting-subscription-release.ts, create-adcp-server L6619-6656, handler offering_id gate) emitted only when the served bundle defines them, not fabricated; handler re-checks visibility (L1671-1681).
• Multi-tenant isolation enforced in SQL via EXISTS keyed on subscription tenant/principal (postgres.ts L389-401, L432-451); migration is additive/idempotent, preserving existing (account,id,version) uniqueness.
• engine.ts fails closed on partial rosters and freezes each elapsed period exactly once (no re-owing); coverage.ts owed-period walk is bounded; producer.ts widens owed-set before obligations land then advances through once durable.
• path_template guarded against traversal / shared-destination collision.
• Changesets correct (4 minor, incl. @adcp/reporting-storage for the migration); CI wires the pg test.

Decision table: no critical/high (row 1 n/a); gated_paths false (row 2 n/a); high_risk false (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 gated_paths is false, so row 2 does not apply.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean subsequent pass over the beta.6/beta.7 delta.

What I checked:

• Task-envelope status preservation: relaxResponseRoot replaced by per-release acceptEnvelopeOnClosedResponseRoot + omitsEnvelopeStatusForRelease. Release-accurate (3.2.x closed arms omit status, 3.3 composes/requires it), witness-preserving (seller payload untouched; status mutation is validation-view only via prepareResponseForSchemaValidation), and backed by the response-envelope-status-gating suite.
• Opt-in collect_product_pages wholesale walker: merged logical view explicitly labelled separate from retained physical pages; per-page schema/invariant grading via onCollectedProductPage; fresh unkeyed reads enforced at loader and dispatch.
• Two new default-on discovery invariants (pricing-currency, required-metric): cite normative ProductFilters basis; report unproven cases as indeterminate rather than fabricating requirements — consistent with witness-not-translator.
• Changesets present and correctly typed (minor/minor/patch).

No Critical/High/Medium findings. Prior pass was also clean (approve). high_risk: false, no gated paths, no team gate. review_decision is REVIEW_REQUIRED but gated_paths is false, so row 2 does not fire. None of rows 1–8 apply → row 9 approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean pass on the AdCP 3.3.0-beta.1→beta.2 adoption.

Checked:

• Regenerated type/wire artifacts + version-string bumps (generated/trivial).
• 3.3.0-beta.2 commercial-terms semantic overrides and the signals SIGNAL_NOT_FOUND→REFERENCE_NOT_FOUND convention, consistent across docstring/example/skill.
• Typed RequestValidationError/isPreDispatchError marker (code='VALIDATION_ERROR' inherited from ValidationError; dispatched:false at every pre-send gate; storyboard runner's caughtError marker check in scope).
• ESM envelope-status loader binding (#3529 — no circular static import; cache cleared on loader swap).
• Largest non-generated file src/lib/v2/projection/creative-delivery.ts: reconcileLegacyAssignmentRefs per-axis merge with independent-set conflict detection and fail-closed on unparseable size/duration constraints is sound; packageSizeAcceptor stated-axis short-circuit is deliberate and locally documented.
• Changesets present and typed correctly for the beta pre-mode train.

No critical/high/medium findings. high_risk false, gated_paths false, no author-team gate. Prior decision was approve; delta remains clean. Row 9 → approve.

Note: review_decision is REVIEW_REQUIRED, but since gated_paths is false, row 2 does not apply.

[aao-secretariat]

Ladon cannot review this PR until merge conflicts are resolved.

[aao-secretariat]

Ladon verdict: Approve

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

This is a follow-up pass to a prior approve. The delta is 67 lines across 4 files, entirely CI/test-only:

• scripts/check-package-size.mjs: tarball budget bump with a measured rationale (26,369,089 bytes after #3541 vs 26,520,000 cap).
• A documentary empty-frontmatter changeset.
• A line-collapse in reporting-subscription-coverage.test.js.
• pre-dispatch-errors.test.js: swaps a retired hardcoded 3.3.0-beta.1 pin for ADCP_VERSION. The release/feature-gate test still asserts ProtocolFeatureUnsupportedError with dispatched:false against a seller advertising only 3.3-beta.0, so coverage holds and is forward-safe.

No src/lib or bin changes, so no changeset is required. Decision-table check: no critical/high/medium findings (row 1, 4-6, 8 don't fire); gated_paths is false (row 2 n/a); high_risk is false (rows 3/5 n/a); no no-auto-approve team match (row 7 n/a); prior decision was approve (row 6 n/a). Falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — subsequent pass on delta (229 lines, 6 files); prior pass was clean and approved.

What I checked:

• Decision table top-down: no critical/high findings (row 1 n/a); gated_paths is false (row 2 n/a despite review_decision REVIEW_REQUIRED — row 2 only fires when gated_paths is true); high_risk is false (rows 3/5 n/a); no medium findings so rows 4/8 n/a; prior decision was approve so sticky row 6 n/a; no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve.
• Reviewer surfaced no findings. Three defensive fixes reviewed as sound and tested: calendar.ts fail-closed refusal of sub-daily billing_cycle (adcp#8622); engine.ts latestPeriodEnd now scans for max period_end instead of trusting last-appended; in-place refresh of open action_required exclusion's pending_action with canonicalize ?? null guard; server replace_account_configs reset narrowed from !== true to === false so an omitted flag no longer wipes a failed-hook pending retry.
• Changesets present (4 reporting-subscription changeset files) covering the src/lib/** changes — changeset-vs-wire-impact satisfied.
• No witness-not-translator concerns; changes are defensive/fail-closed, not fabrication.

No blocking or medium findings. Clean net-positive iteration on an already-clean PR.

The merge-base changed after approval.