[bokelley]

Part of #1695, slice 3 (storage), per the owner's decision: widen the key to match TS. It stacks on #1728, #1725 and #1723, so it contains their commits. Review only feat(reporting): hold reporting-subscription owed sets in the PostgreSQL ledger.

Maintenance upgrade (breaking storage boundary)

The PostgreSQL generation key becomes (account_id, consumer_id, delivery_config_id, delivery_config_version, offering_id), matching adcontextprotocol/adcp-client#3517's one-generation-per-offering identity. Account-level generations keep offering_id = ''.

Upgrade: stop every reporting worker, run create_schema() once with this release, then restart. Workers of earlier releases refuse the widened schema through their exact manifests, and mixed-version workers are unsupported. next is a beta line, so per the owner the maintenance upgrade is acceptable. It is documented in docs/reporting-ledger-migration.md ("Reporting-subscription generations: the widened key").

The widening lives in reporting_ledger_account_generations.sql, the existing generation-key guard. It runs under the schema advisory lock and ACCESS EXCLUSIVE locks, losslessly and idempotently:

• Configurations: reporting_configurations gains offering_id ('' for existing rows), and the primary key includes it.
• Obligations: reporting_obligations gains offering_id, and the reporting_obligations_period_key unique index includes it.
• Consumer statuses: reporting_consumer_statuses gains offering_id.
• The SDK's own references are re-pointed at the widened key: reporting_reconciliation_records, reporting_materializer_discovery, reporting_status_scope_checkpoints and reporting_production_generations.
  • Each gains offering_id with CHECK (offering_id = ''), so they keep serving account-level generations only until each feature serves subscriptions.
  • Each has a named foreign key.
  • Their fresh CREATE TABLE definitions match.
• A foreign key outside the SDK that references reporting_configurations refuses the upgrade with the maintenance error instead of being dropped.
• Identity check: a fresh schema ends identical to an upgraded one, and to one upgraded twice. I checked all 1,739 reporting_* catalog objects locally.

I chose an in-place upgrade rather than refusing create_schema on the old key, so every historical upgrade gate (new code on an earlier schema) keeps working. Old workers are refused by the manifests, as the repo's guard requires.

Store

• Owed sets: PgReportingLedgerStore implements ReportingSubscriptionLedger, so the planner and service accept it:

  • list_generation_obligations;
  • record_owed_set_progress (monotonic GREATEST, only for subscription generations);
  • owed_set_through.

  Horizons live in the private adcp_reporting_owed_set_progress table. The adcp_ prefix keeps it outside the reporting_* catalog contract, like the lease turns.

• Status snapshots carry the owed-set horizons, so scope_closed matches the in-memory store.

• Queries:

  • Every configuration, obligation and consumer-status query carries offering_id. The row codecs append it as a trailing column.
  • Leasing selects offering_id = '' only, so an owed set is never leased.
  • Production lookups pin account generations. Delivery and materializer lookups select by the key's own offering.

• Legacy import (migrate_legacy_reporting) fills offering_id = ''.

• Status notifications: a store with them enabled refuses an owed set (UNSUPPORTED_FEATURE), because status scope checkpoints are still keyed per account generation.

Manifests

• Regenerated from a clean migration chain, with fingerprints computed by the package's own catalog reader:
  • outbox;
  • outbox/required_status_schema;
  • materializer;
  • production.
• Rule: existing keys get updated fingerprints, replaced foreign keys are swapped for the named ones, and new columns and constraints are added only where the manifest already covered that table.
• Pinned counts: the union of manifests grows 767 → 774 and the materializer manifest 187 → 189. Those pins in the migration tests are updated.

Tests

• New: tests/conformance/reporting/test_reporting_subscription_ledger_pg.py (core Postgres lane) covers:
  • match: all with four offerings in one generation tuple, sparse and idempotent writes, and a horizon that never regresses;
  • no leasing of owed sets, and progress refused for account generations;
  • two principals' visibility, scope_closed, and status ingest storing offering_id;
  • lossless, idempotent widening of a four-column schema with an existing row;
  • an adopter foreign key refusing the widening;
  • status notifications refusing owed sets.
• Locally against PostgreSQL 16:
  • the generation, caller-ownership, reconciliation, production, materializer, receipt and feed migration suites pass;
  • the core lane passes except the wheel and historical-artifact tests, which need more disk than the sandbox has; CI runs them.

This does not adopt beta.2.

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — PostgreSQL reporting-storage slice (key-widening to include offering_id).

No blocking findings. The reviewer confirmed the key-widening migration (reporting_ledger_account_generations.sql) is idempotent (early RETURN on 5-col PK), lossless (DEFAULT ''), and fails closed on outside-SDK FKs with test coverage. Account happy path preserved (offering_id='' pins), owed sets never leased, record_owed_set_progress monotonic under account lock, notifications refuse owed sets, and ledger_asdict keeps digests byte-stable. Public API additions are additive and carry the correct feat: signal.

High-risk flag is true only for src/adcp/decisioning/handler.py (modified), but the reviewer surfaced no medium-or-higher concerns on that file, so the modification is presumed safe (does not trip row 5). gated_paths is false; no author team gate; no prior decision. With zero findings, rows 1–8 do not fire and the outcome falls through to row 9.

Non-blocking note: core wheel/historical-artifact tests deferred to CI for disk; the owed-set path is exercised by the new PG16 conformance suite.

[aao-secretariat]

Ladon verdict: Approve

Approve — subsequent pass, clean.

This is a follow-up to a prior approve (head 7c080b1). The delta since then is three test-only files: catalog count repins (materializer 187→189, scope 794→801, both matching the regenerated manifests' +7/+2 growth pinned in the PR body) and relocating from psycopg.errors import RaiseException inside the isolated_reporting_pool context so the fixture's pytest.importorskip("psycopg") skips cleanly before the import. All sound.

No critical, high, or medium findings in this run. No prior blockers to re-surface.

Gate checks:

• Author team gates: no no-auto-approve match.
• gated_paths: false; review_decision: APPROVED (no hard path gate triggered).
• high_risk: true via src/adcp/decisioning/handler.py (modified), but the reviewer surfaced no medium-or-higher concern on it, so the modification is presumed safe — the flag alone does not escalate.
• No (deleted) high-risk reasons.
• Prior decision was approve, so sticky escalation (row 6) does not apply.

Rows 1–8 do not fire; falls through to row 9 → approve.