[bokelley]

Why

adcp==10.0.0b4 with the only published adcp-reporting-storage (0.2.0b0) installs cleanly (adcp>=9.0.0,<11) and fails every PostgreSQL Reliable Reporting turn with column "offering_id" does not exist (#1763). ESA has a production ledger created by 0.1.0b4/0.2.0b0 that cannot be recreated.

Drift audit

Column lists adcp reads the ledger with (adcp.reporting.ledger._record_rows), by release:

adcp	_OBLIGATION_COLUMNS	_CONFIGURATION_COLUMNS	_STATUS_COLUMNS
9.4.0, 10.0.0b2, 10.0.0b3	23 columns	(lived in storage)	22
10.0.0b4, b5, next	+offering_id	19 incl. offering_id	+offering_id

That is the only column-list drift. Storage on next already ships matching DDL and a migration framework (0001–0005, unreleased); 0.1.0b4 and 0.2.0b0 are source-identical. The SDK 9 line has no drift (storage on main == 0.1.0b4; _record_rows unchanged since).

What this PR does

• create_schema() applies and records the versioned migrations inside its bootstrap transaction, under the reporting schema advisory lock, so the store= startup path (what ESA runs) and python -m adcp migrate converge. A 0.1.0b4/0.2.0b0 ledger is upgraded in place: offering_id added with '' for every existing account-level row, generation key and period index widened, managed-delivery FKs re-pointed, versions recorded in adcp_schema_migrations. Re-runnable; concurrent boots serialize; no evidence row rewritten or dropped.
• Storage contract number on both sides: adcp_reporting_storage.STORAGE_CONTRACT = 2, checked when a PgReportingLedgerStore is built. A mismatched adcp is refused at startup with REPORTING_SCHEMA_BEHIND, naming both installed versions, both contracts and the release to install. adcp 10.0.0b4/b5 (no declaration yet) are classified by their column lists; the adcp-side declaration and check come in a follow-up PR.
• Floor adcp>=10.0.0b4,<11, the first adcp release of contract 2, so the incompatible pair no longer resolves.

Test evidence (real PostgreSQL 16, actual published wheels)

New tests/conformance/reporting/test_reporting_storage_published_upgrade_pg.py seeds ledgers with adcp==9.3.1 + adcp-reporting-storage==0.1.0b4 and adcp==10.0.0b2 + 0.2.0b0 (generations, obligations, revisions, rows), then with this checkout:

• reproduces the b4 failure on the published 0.2.0b0 (UndefinedColumn: offering_id);
• create_schema() and migrate() each upgrade in place: every pre-upgrade row survives byte-for-byte plus offering_id='', all records read back, versions 0001–0005 recorded, re-run is a no-op;
• the upgraded catalog (columns, constraints, indexes, triggers) is identical to a freshly migrated schema;
• a ReliableReportingService(store=...) restart rebinds both stored generations with no initialization errors and closes the next period with a new snapshot revision;
• four concurrent create_schema()/migrate() boots serialize and record each version once;
• adcp==10.0.0b4 + this storage (the pair a seller upgrades to) upgrades the 0.2.0b0 ledger and reads everything.

9 passed, 1 skipped in 127.37s

Plus make lint, make typecheck-all, and the existing storage facade / migration / PG ledger tests pass locally.

Operator note

The upgrade is a stopped-worker upgrade (0.2.0b0 workers' configuration writes name the four-column key): stop workers of the earlier release, start the new release (or run python -m adcp migrate), done.

🤖 Generated with Claude Code

---

Open workspace in Conductor

[aao-secretariat]

Ladon verdict: Approve

Approve — clean fix for #1763 with no blocking or medium findings.

What I checked:

• No findings from the reviewer (critical/high/medium all absent).
• high_risk: false; gated_paths: false; no no-auto-approve team match; no prior decision.
• The change moves create_schema() to apply versioned migrations via the new apply_pending inside its bootstrap transaction, and adds a storage-contract integer that fail-closes an incompatible adcp/storage pairing at construction rather than on first ledger read. The _apply extraction is behavior-equivalent to the old _migrate loop.
• Concurrency, in-place upgrade, and evidence-preservation are covered by real-PostgreSQL conformance tests against the published wheels.
• No adcp.* public-surface change, so SDK semver rules do not apply; the floor/contract break is documented 0.x storage-package policy (this is a separate adcp-reporting-storage package, not the adcp namespace).

With no findings and no escalation trigger, rows 1–8 do not fire; the PR falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve.

Clean pass with no blocking or Medium findings. The reviewer verified the core migration-ownership logic: apply_pending(within=...) walks migrations in version order with correct break-not-skip semantics (0004 subscriptions/ stops the walk, leaving 0004/0005 for python -m adcp migrate), and the within posix paths exactly match the -- include: directives of 0001–0003. The conformance test correctly moves check_schema() after migrate() (fail-closed on behind-schema) and asserts the upgraded-vs-fresh catalog invariant. Public-surface changes are additive and snapshot-tracked: STORAGE_CONTRACT/require_adcp_contract exports, contract.py resolving to the public adcp.reporting export, and a consistent adcp>=10.0.0b4,<11 storage floor with matching test.

Checked against repo gates: no public-API break requiring a semver signal, no hand-edits to generated code, no import-layering or forward-compat regressions, no disabled tests or blanket type:ignores.

Decision table: no critical/high findings (row 1 n/a); gated_paths false and review_decision APPROVED (row 2 n/a); high_risk false (rows 3/5 n/a); no medium findings (rows 4/8 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 cannot review this PR until merge conflicts are resolved.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean pass, no findings.

This PR pins a storage contract (version 2) between adcp and adcp-reporting-storage to close #1763 and upgrades the 0.1.0b4/0.2.0b0 ledgers in place. The reviewer confirmed:

• New public symbols (STORAGE_CONTRACT, require_adcp_contract, the storage_contract module) are additive with a matching public_api_snapshot.json entry — no semver break.
• The fail-closed contract guard is symmetric (adcp→store require_storage_contract at service _initialize/postgres_storage; store→adcp require_adcp_contract at PgReportingLedgerStore.__init__), skips in-memory/custom stores, and refuses both older and newer contracts (_Newer/_Older tested).
• Migration apply path (apply_pending/_apply) holds the reporting schema lock, is re-runnable, bounded to owned migrations 0001-0003, and serializes concurrent boots (proven, count==5); test subprocesses carry explicit timeouts.
• Largest-file delta (test_reporting_storage_published_upgrade_pg.py) and _published_ledger_seed.py both reviewed and sound; the #1763 repro is asserted.
• Test plan honest: 9 passed / 1 skipped on real PostgreSQL with actual published wheels.

Gate checks: no critical/high/medium findings (rows 1, 4–6, 8 do not fire). gated_paths false and review_decision APPROVED (row 2 n/a). high_risk false (rows 3, 5 n/a). No no-auto-approve team match (row 7 n/a). Prior decision was approve. Falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve.

The delta since the prior clean pass is docs wording and test infrastructure only. Docstrings/comments in pg.py and the migration/README docs update "0004–0005" to "0004 onward" to name the new migration 0006 (status checkpoint offerings), which lives outside this diff. Tests replace hardcoded ["0004","0005"] version lists with _shipped()/_rest() derived from the actual migrations() manifest, and add a notifications-enabled upgrade test covering the reporting_status_checkpoints/events tables. Helpers are internally consistent and order-preserving.

No product-code logic, public API, wire shape, or credential handling changed in the delta. No critical/high/medium findings surfaced, and no prior blockers to re-surface (prior decision was also approve).

Checks against decision table:

• No critical/high/medium findings (rows 1, 4, 5, 6, 8 don't fire).
• gated_paths false; review_decision APPROVED (row 2 n/a).
• high_risk false (rows 3, 5 n/a).
• No no-auto-approve team match (row 7 n/a).

Falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean delta since prior approve.

The only change since the prior approve (head 1522644) is a single comment reflow in packages/adcp-reporting-storage/src/adcp_reporting_storage/ledger/pg.py (L702-713): the "stay pending for python -m adcp migrate" comment rewrapped across lines with zero semantic change. No code, control flow, or wire surface touched.

Checked:

• No critical/high/medium findings in this run.
• high_risk: false; no deletions in sensitive paths.
• gated_paths: false and review_decision: APPROVED — no path gate holding.
• Author is not on any no-auto-approve team.
• Public-surface / semver, forward-compat union, import-layering, generated-code, ctx_metadata credential, and CI-gate concerns all N/A for a comment reflow.

Decision table: rows 1–8 do not fire (no findings, no gate, no team match, <3 mediums). Falls through to row 9 → approve.