reporting: replace an all-empty pre-ownership ledger without the archive ceremony #1439

Activity

1. bokelley

   added

   claude-triagingTriage routine is actively working on this issue (1-3 min)Triage routine is actively working on this issue (1-3 min)

   on Oct 7, 2026
2. bokelley commented on Oct 7, 2026

   

   bokelley

   on Oct 7, 2026

   ContributorAuthor

   More actions

   Triage

   Classification: Feature request
   Bucket(s): client (reporting/migration), docs
   Status: ready-to-implement
   Milestone: omitted

   What the experts said:

   • code-reviewer: Both items are worth doing; the workers_stopped-free framing is misleading — ACCESS EXCLUSIVE table locks are still required before the emptiness check (advisory lock alone doesn't block concurrent INSERTs under READ COMMITTED), and the docs addition must reconcile with the existing "mixed-version unsupported" statement.
   • dx-expert: Real pain point; feature is well-motivated — but require_owned_schema_or_empty's error message must surface both paths or the new function is invisible to the operators it helps, and the rolling-deploy section must verify the consumer_id NOT NULL constraint semantics (fail-fast vs. silent corruption) before shipping.

   My take: Both items are ready to implement. The "no maintenance window" promise holds because the database enforces effective quiesce via ACCESS EXCLUSIVE table locks — it's a UX improvement for the empty case, not a correctness shortcut. The docs section is high-value and the only prerequisite is verifying the DDL guarantee and reconciling one sentence in the existing guide.

   Implementation brief:

   Item 1 — replace_empty_legacy_reporting(connection) in src/adcp/reporting/migration.py:

   • Acquire pg_advisory_xact_lock (same key as migrate_legacy_reporting)
   • In the same transaction, acquire ACCESS EXCLUSIVE on every reporting_* / adcp_reporting_* table (same pattern as lines 126–131 of migration.py)
   • After locks are held, count rows in each table; raise ReportingOwnershipMigrationError if any table has > 0 rows
   • Drop all reporting tables, sequences, and functions (no archive schema, no triggers, no workers_stopped assertion needed — the locks are the quiesce)
   • Add to __all__ alongside existing names; do not export from adcp/reporting/__init__.py
   • Update the require_owned_schema_or_empty error message (line 76–78) to surface both paths, e.g.: "If all legacy tables are empty, call replace_empty_legacy_reporting. Otherwise stop all reporting workers and run migrate_legacy_reporting."
   • Tests in tests/conformance/reporting/test_reporting_caller_ownership.py: success (all empty), refusal (any table non-empty), and create_schema succeeds immediately after

   Item 2 — Rolling-deploy section in docs/reporting-caller-ownership-migration.md:

   • Check src/adcp/reporting/ledger/reporting_caller_ownership.sql to confirm consumer_id NOT NULL ships in the DDL (not just a check constraint)
   • Reconcile with the "mixed-version reporting processes are unsupported" statement — narrow it to: unsupported for non-empty ledger transitions; the new NOT NULL constraint makes the failure mode for 8.x pods loud and bounded (constraint violation on write, not silent data corruption)
   • Document the safe rolling-deploy sequence: new schema first, then pods — old 8.x pods hit consumer_id NOT NULL violation on any reporting write and fail fast; no unowned rows are silently written

   ---

   Triaged by Claude Code. Session: https://claude.ai/code/session_01MrsLsYJQjbFqFy3yDZBZ57

   ---

   Generated by Claude Code
3. bokelley

   added

   enhancementNew feature or requestNew feature or request

   claude-triaged

   docs

   and removed

   claude-triagingTriage routine is actively working on this issue (1-3 min)Triage routine is actively working on this issue (1-3 min)

   on Oct 7, 2026
4. bokelley

   closed this as completedin #1443on Oct 7, 2026