[bokelley]

Sixth of the series for #3504. It delivers subscription obligations through managed delivery. It stacks on #3518 (which stacks on #3517 and #3509), so it contains every earlier commit. Review only feat(reporting): managed delivery of subscription obligations (ff2feb6). It targets main because CI runs only for PRs into main.

What ships

1. Destination resolution

• Binding comes first. createReliableReportingService calls a new reportingSubscriptions.bindManagedGeneration hook, through the planner's new bindGeneration, for each managed generation about to receive its first obligation. The hook runs after the generation is installed and before any obligation is written, because installBinding refuses a configuration that already has obligations.
• A failed bind writes nothing. That generation's obligations wait for the next cycle instead of becoming undeliverable Core obligations.
• No hook, no plan. A subscription that resolves a managed offering without the hook fails to plan, with an explicit error.
• Consumer receipts. A consumer_receipt offering must be managed.
• The production service supplies the hook. It uses createReportingSubscriptionManagedBindingV1 (@adcp/reporting-storage/managed), built from reportingSubscriptions.principal, the principal runtime. For each generation it:
  1. reads the version's destination.destination_id;
  2. finds the owner's current generation of that destination (get_principal destination_ref; the spec says "The seller binds the current generation");
  3. requires that generation to be delivery-eligible, with the offering's pattern and transport, which must also equal the version's frozen destination_method;
  4. calls ensureDestinationAuthorization, which creates or reuses the account's authorization of that destination_ref;
  5. installs an immutable binding: canonical_digest for consumer_receipt, otherwise the adapter's first verification profile, with resource_retention_days from the service, and path_template frozen.
• delivery_only without a destination stays Core. Selection never resolves a managed offering for it.

2. Bindings keyed by the configuration

• REPORTING_MANAGED_DELIVERY_MIGRATION drops the published UNIQUE (account_id, delivery_config_id, delivery_config_version) on adcp_reporting_managed_bindings.
  • It finds the constraint in pg_constraint by its columns, in a guarded DO $$ block.
  • It adds a non-unique lookup index.
  • A fresh schema creates the table without that key.
• The binding's key is its configuration_id primary key. Core configurations stay unique on (…, subscription_key) from feat(reporting): hold subscription obligations in the reporting ledger #3517, so account bindings keep their uniqueness.
• There is no memory managed store; managed delivery is PostgreSQL-only.

3. Path templates and account_id

• Path templates. ReportingManagedDeliveryBindingV1.path_template is immutable and outside account fingerprints. The worker expands it per obligation with expandReportingSubscriptionPathTemplate, filling {account_id}, {subscription_id}, {offering_id} and {period_start}, and passes it to adapter.deliver as delivery_path.
• Object naming. Object-store names keep the collision-free, account- and generation-scoped prefix, with the template between the prefix and the plan:
  adcp-reporting/{namespace_key}/{scope_key}/{delivery_path}/{plan_id}/{index}
  • reportingObjectWriteName takes the optional path. isReportingObjectWriteName validates it for cleanup and reads.
  • The GCS fence and adapter write there.
  • The GCS adapter's status lookup is now scoped to the owner, since a subscription obligation is invisible otherwise.
  • Documented in REPORTING-LEDGER.md.
• account_id on rows. Every row of a subscription revision carries it. The producer stamps it before binding the revision, so the digest covers it, and refuses a row that names another account. Account revisions are unchanged.

4. Per-account destinations

The spec allows exactly one per-account mechanism. A destination is principal-level, with generations per destination, not per account. Per-account separation is the path_template {account_id}, which #3508 requires for multi-account scopes and shared destinations. The managed store already keys authorizations per account, so each covered account gets its own authorization of the shared destination_ref. Nothing beyond that is implemented.

5. Authority at each delivery

• runManagedDeliveryWorker({ authorizeSubscriptionDelivery }) re-checks the owner's account authority twice: after claiming and before delivering, and after delivering and before settling. The production service wires it to the new engine.isAuthorized, and refuses reportingSubscriptions without it.
• What a loss does. A loss calls the new holdMaterialization. It releases the lease, refunds the claim's attempt, and holds the row for authorityHoldMilliseconds, 60 s by default.
• The obligation stays owed. The materialization stays pending and is never failed, and the engine reports the loss in accounts_unauthorized.
• Unchanged. Destination-authority checks are as before. The result gains heldForAuthority only when the check is wired.

6. Subscribers scoped to the owner

• ReportingLedgerSubscriberV1.principal scopes status subscribers. A subscription obligation's transitions reach only subscribers of its owner; account subscribers get none. Account obligations behave as before.
• Production notification activity records ownerPrincipalId and emits with principalId, so status_changed, ledger_changed and delivery_ready fan out only to the owner.
• Production reads now use resolveSubscriptionPrincipal and add subscription_coverage. Before this they used neither.

Tests

• test/lib/reporting-subscription-delivery.test.js (Core service, memory store):
  • binding before the first obligation, with the destination, template and frozen method
  • no rebind on later cycles
  • account_id on every revision row
  • a failing bind writes nothing and retries next cycle
  • a managed offering without the hook fails loudly
  • owner-scoped status subscribers
• packages/reporting-storage/test/reporting-subscription-delivery-pg.test.js (production service end to end):
  • two owners × two offerings (match: all) on one account produce 4 bindings under one (account, id, version), each to its owner's destination_ref
  • B's deliveries carry delivery_path = account/offering/period_start and rows with account_id
  • A loses its grant between claim and settle: held, still pending, never delivered again
  • the binding migration on a published schema with an existing binding, run twice
• Option off. feat(reporting): plan and execute subscription obligations in the service #3518's byte-for-byte golden transcript still passes. reporting-subscription-service.test.js now expects account_id on subscription rows.

Deviations

• Binding uses the destination's current generation. If the destination later mints a new generation, existing generations stay bound to the old destination_ref, which stays resolvable through prior_destination_refs until revoked. New generations bind the new one.
• The check before settling runs after the bytes were written. If authority is lost mid-flight, the provider may hold a written but unrecorded object, which is re-delivered after a re-grant.
• The held row is re-claimed every hold interval while authority stays lost. It never exhausts its attempts.

Spec ambiguities

• account_id columns. "Every delivered row carries account_id" doesn't say whether the reporting profile must declare the column. The SDK adds it to subscription rows only.
• delivery_config_generations. The ambiguity raised in feat(reporting): hold subscription obligations in the reporting ledger #3517 still applies to managed generations.

Local checks

• typecheck, typecheck:reporting-storage, lint:boundaries, check:package-size and Prettier pass.
• 554 tests pass across the reporting, service and subscription suites.
• The new PostgreSQL suite, reporting-ledger-pg, reliable-reporting-production-pg, reporting-managed-router-pg and reporting-subscription-ledger-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 cannot review this PR until merge conflicts are resolved.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean review, no blocking findings.

The reviewer examined the managed-delivery logic in the top commit: path-template expansion (fails-closed, percent-encodes '/' and '.'/'..' so no segment escape), account_id row stamping (witness-safe, refuses conflicting account), binding immutability (path_template inside managedBindingFingerprint with a new charset/length guard ahead of the fingerprint compare), both constraint-drop migrations (guarded, idempotent, not FK-referenced), version-aware field projection (DR-0033 droppable pathway), and the worker's twice-checked owner authority. Six correct minor changesets accompany the src/lib/** changes, satisfying changeset-vs-wire-impact. Documented deviations are disclosed in the PR body.

No critical/high/medium findings. Decision-table walk: no critical/high (row 1 n/a); gated_paths is false (row 2 n/a); high_risk is false (rows 3/5 n/a); no medium findings at all (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 this does not force escalation.

[aao-secretariat]

Ladon verdict: Approve

Approve — subsequent pass on PR #3523, clean.

This is a follow-up pass; the prior decision was also approve with no findings. The 66-file delta is a merge of already-reviewed main commits plus mechanical regeneration: the beta.1→beta.2 bundle bump (#3541) across generated types/wire-spec-fields/docs/version.ts; the typed RequestValidationError/isPreDispatchError work (#3507); the ESM envelope-status loader binding fix (#3529); and the legacy-ref constraint-reconciliation (#3510) in v2/projection/creative-delivery.ts.

The largest delta file (creative-delivery.ts, ~360 added lines) was reviewed: reconcileLegacyAssignmentRefs (L5139-5190) combines per-axis width/height from distinct resolved refs and validates each package's acceptor against the shared size — deliberate, documented, and no correctness defect. Changesets are present and correctly typed (minor for beta.2 adoption and typed error, patch for the reconciliation fix).

No critical/high/medium findings. gated_paths is false; no no-auto-approve team match; high_risk is false. review_decision is REVIEW_REQUIRED, but row 2 only forces escalate when gated_paths is true — it is not here. None of rows 1–8 fire, so the outcome is approve (row 9).

[aao-secretariat]

Ladon verdict: Approve

Approve — clean delta, no blocking findings.

This is a subsequent review; the prior decision was approve (head 6e11b9c) with no findings. The current reviewer pass found nothing actionable.

What was checked:

• 67-line delta across 4 CI/test-only files; no src/lib or wire surface touched.
• Empty-frontmatter changeset — no wire/export impact.
• check-package-size.mjs tarball budget bump to 26,520,000 bytes with documented measurements (~150 KB headroom).
• Pre-dispatch test swaps retired 3.3.0-beta.1 pin for live ADCP_VERSION.
• Cosmetic reformat in coverage test.

No findings. Decision table: no critical/high (row 1 n/a); gated_paths false (row 2 n/a); no deletions (row 3 n/a); no medium findings (rows 4/5/8 n/a); prior decision was approve, so sticky-escalation 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 since gated_paths is false, row 2 does not fire and this does not block auto-approve.

[aao-secretariat]

Ladon verdict: Approve

Approve.

Clean pass with no findings. This is a subsequent review of the new 3.3 reporting-subscriptions feature; the prior decision was also approve. The current delta (229 lines across 6 files) consists of refinements, each with a dedicated new test and covered by existing minor changesets:

• calendar.ts refuses sub-daily billing_cycle (adcp#8622) before the local-midnight branch.
• engine.ts refreshes an open action_required exclusion when pending_action changes and computes last_owed_period_end by max scan rather than trusting last-stored.
• server/principal/reporting-subscriptions.ts narrows the reset to explicit replace_account_configs:false so an omitted flag no longer drops a pending retry.

No critical/high/medium findings. Decision table: rows 1–8 do not fire — no blocking or medium findings, gated_paths is false (row 2 N/A), high_risk is false, no no-auto-approve team match, prior decision was approve (row 6 N/A). Falls through to row 9 → approve.

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