[bokelley]

Option 2 of #1831, for the 0.1.x line, so it can ship in 0.1.0b5 (#1834). The docs half went into next in #1855. The rolling-safe upgrade is tracked in #1856.

Problem

adcp-reporting-storage 0.2.0b1+ upgrades a 0.1.x ledger in place, widening the configuration, obligation-period and status-checkpoint keys with offering_id. A 0.1.x process still running through a rolling deploy, or restarted after it, failed in ways that hid the cause:

Where	Before
create_schema() (restart)	RaiseException: Reporting caller ownership requires a stopped-worker maintenance migration, HINT: Use migrate_legacy_reporting (the 8 → 9 ownership migration: wrong, and it quarantines state)
commit_obligation	LedgerConflictError LEDGER_WRITE_FAILED: the ledger write violated an integrity rule (a wrapped 42P10)
put_configuration, status checkpoint write	raw InvalidColumnReference (42P10: no unique index matches the ON CONFLICT target)

Change

• migration.require_owned_schema_or_empty, which every store's bootstrap runs before any DDL, now refuses a ledger whose reporting_configurations has offering_id. It raises the new ReportingSchemaAheadError, a ReportingOperatorActionError, so service startup re-raises it unwrapped. It's exported from adcp_reporting_storage.
• schema_ahead_error() maps 42P10 on the writes whose keys the upgrade widens:
  • obligation writes, through _translate_integrity_error, raise LedgerConflictError with code REPORTING_SCHEMA_AHEAD, so callers that branch on .code keep working;
  • put_configuration and the status checkpoint placeholder insert raise ReportingSchemaAheadError.
• reporting_ledger_account_generations.sql: its key check names contract 2 with the same remedy before falling through to the caller-ownership error, for operators who apply the packaged SQL themselves.

All three carry the same remedy:

• run adcp>=10.0.0b7 with adcp-reporting-storage>=0.2.0b1 on every reporting process;
• downgrading means restoring the pre-upgrade backup;
• don't run migrate_legacy_reporting.

Evidence

• tests/conformance/reporting/test_reporting_storage_contract2_refusal_pg.py has four tests:

  • only 42P10 maps;
  • create_schema refuses and leaves the key unchanged;
  • the DDL alone names contract 2;
  • put_configuration and commit_obligation name the upgrade.

  The tests apply the same key changes as next's 0002. All four fail on main and pass here.

• End to end with the published wheels:

  1. seed a ledger with this branch (adcp 9.6.1 + storage from source);
  2. upgrade it with adcp==10.0.0b8 + adcp-reporting-storage[pg]==0.2.0b1;
  3. run this branch as an old pod.

  create_schema → ReportingSchemaAheadError, commit_obligation → LedgerConflictError[REPORTING_SCHEMA_AHEAD], put_configuration → ReportingSchemaAheadError. Reads still work, and the new pair reads everything back.

• 0.1.0b5 → 0.2.x upgrade path, checked because main has storage schema changes not yet on next (feat(reporting-storage): order the account change feed by xid and seq #1827, feat(reporting-storage): accept 255 character row binding IDs and credential refs #1828, feat(reporting-storage): collect orphaned row objects by listing with a clone fence #1835, perf(reporting-storage): drop the per-object advisory lock where nothing pairs on it #1836): a ledger built by this branch with the change feed on upgrades cleanly through 0.2.0b1's create_schema() and python -m adcp migrate --dsn … (0004–0006 applied, "up to date"). feat(reporting-storage): order the account change feed by xid and seq #1827's extra horizon columns and index are left in place. So releasing 0.1.0b5 doesn't strand anyone, but those features still need porting to next.

• Local CI-equivalent tests/conformance/reporting/ run (CI's ignore list, PostgreSQL 15.18 locally, -n 4): 2669 passed, 20 failed. Rerunning the 20 in fresh databases: 3 fail with this change and 6 on unmodified main. The one that failed only here (test_reporting_materializer_history…[postgres]) passes 3/3 when run alone.

• make lint and make typecheck-all pass.

Refs #1831

🤖 Generated with Claude Code

[aao-secretariat]

Medium: This status-checkpoint refusal arm ships untested. _WIDEN in the new conformance test widens reporting_configurations, reporting_obligations, and adds a bare offering_id column to reporting_consumer_statuses — it never touches reporting_status_scope_checkpoints, so the ON CONFLICT ({_KEY}) here never hits 42P10 in any test. The PR body lists the status-checkpoint write as one of the three sites that fail with a raw InvalidColumnReference on a contract-2 ledger, yet the only path this branch handles is the one with no coverage. If the sqlstate detection regresses here, an old pod degrades to a raw 42P10 on a durable async path with no test to catch it. Extend _WIDEN to widen the checkpoint key and add a case exercising _lock_scopes_on.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean, well-scoped contract-2 refusal change.

What I checked:

• 42P10 (schema_ahead_error) detection keys on index name via sqlstate, not prose — correct shape. _translate_integrity_error checks it first so obligation writes preserve their .code contract (REPORTING_SCHEMA_AHEAD).
• require_owned_schema_or_empty fails closed before any DDL.
• ReportingSchemaAheadError is additive — no semver break, no public-surface break.
• No credentials in ctx_metadata, no generated-code hand-edits, no type-layering violations, CI gates untouched.

Medium findings (1 — non-blocking):

• packages/adcp-reporting-storage/src/adcp_reporting_storage/outbox/status_pg.py:301 — Status-checkpoint contract-2 refusal arm is untested; _WIDEN widens configurations/obligations but never the checkpoint key, so that branch is never exercised.

Decision trace: no critical/high findings (row 1 no). gated_paths is false (row 2 no). high_risk false (rows 3,5 no). The single medium finding is not in {data-loss, schema, infra} (row 4 no). No prior decision (row 6 no). No no-auto-approve team match (row 7 no). Only 1 medium finding, fewer than 3 (row 8 no). Falls through to row 9 → approve.

Medium findings

• packages/adcp-reporting-storage/src/adcp_reporting_storage/outbox/status_pg.py:301 — Status-checkpoint contract-2 refusal arm is untested

[aao-secretariat]

Ladon verdict: Approve

Approve — additive public-API snapshot update, no blocking or medium findings.

This is a subsequent push after a prior approve. The delta since the prior run is a single line adding ReportingSchemaAheadError to tests/fixtures/public_api_snapshot.json, mapped to adcp_reporting_storage.migration. This is the correct additive companion to the new public export (added to migration.py __all__, re-exported via __init__.py), and the schema_ahead_error helper is correctly kept out of __all__. Additive/non-breaking — no semver concern.

The prior medium finding (status_pg.py:301 — untested contract-2 refusal arm) is outside this delta and was not rechecked; note the diff also includes a new conformance test (test_reporting_storage_contract2_refusal_pg.py) consistent with addressing that area.

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); prior decision was approve, not escalate (row 6 n/a); no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve. (review_decision REVIEW_REQUIRED does not block since gated_paths is false.)

[aao-secretariat]

Ladon verdict: Approve

Approve.

This PR is a one-line test-robustness fix: from psycopg import errors moves from function entry into the isolated_reporting_pool(...) context-manager block in tests/conformance/reporting/test_reporting_storage_contract2_refusal_pg.py. The context manager runs pytest.skip/importorskip first, so a runner without psycopg now skips cleanly rather than erroring on the bare import. The change matches the three sibling tests and touches no production code.

No critical/high/medium findings were reported. No author-team gate (no no-auto-approve match). gated_paths is false, so the REVIEW_REQUIRED status does not force escalation. high_risk is false. Prior decision was approve and this delta is a net-neutral/positive refinement.

Decision table: rows 1–8 do not fire (no blocking findings, no gated path, no deletions, no medium findings, no team gate) → row 9 → approve.