Repair the ContentRelease contract-digest migration for populated databases

PM disposition — re-groomed after independent tester FAIL

This remains a P0, release-blocking data-migration bug. The independent tester found the local migration/service/portable verification green, but the first scope could not complete post-merge deployment and external-environment evidence before the required engineer commit, local merge/push, and on-call sequence. Criterion 4 also lacks one dedicated regression test.

This re-grooming defers only the named post-merge or external gates. It does not waive, downgrade, or convert any local migration, service, replay, handoff, or portability requirement into optional work.

Normative contracts

• docs/PROCESS.md
• Migration, rollout, and roadmap, especially rollback and data-migration controls
• Verification strategy, especially database/service, deployment, content-sync, operations, and deployed-gate scenarios
• Platform architecture — content refresh and release identity
• URL/link/SEO compatibility and release/cache contracts
• Structured content authoring and source ownership, especially editing/provenance and release handoff

Confirmed facts and tester disposition

Inspected against origin/main at e575e1a73414131b3241a6a029a0839d62090573:

• content/migrations/0001_initial.py creates ContentRelease.public_contracts_sha256 with default and database check constraint 50f875806217865ef35b74f58ed885c4b5c832284391dbea7f84344d3416f66d.
• content/migrations/0004_remove_contentrelease_content_release_contract_sha_ck_and_more.py removes that constraint, changes the default to 31f505350566bfcde0a30109dadcfb3565042fd395b4c1bd151966f94d361332, and adds the same-named check for the new digest without transitioning existing rows.
• The runtime model and checked public-contract artifact use the new 31f… digest. New content candidates must bind to that exact artifact; historical release provenance must remain readable.
• The first independent tester report (report comment) found the local migration graph, idempotence, verification, and portability evidence passing. It found criterion 4 incomplete because content_sync.dtc_content.preparation._existing_release has no dedicated test proving a legacy-digest replay is rejected.
• The tester did not access AWS, shared development, production data, or a deployed release. Therefore the actual non-disposable applied-0004 state, exact-image deployment, failed-migration preservation, classification, readiness, and deployed-smoke evidence remain unavailable until the normal post-merge/on-call sequence.
• The original deployment evidence remains run 32636739682: application verification passed, while the deployment migration path failed before web/worker mutation with the redacted reason contract_contradiction. That reason alone does not classify the cause.

Scope

1. Keep the forward expand/contract migration repair safe for populated databases and preserve every ContentRelease row, primary key, status, source/release sequence, active-source pointer, child document/relation/asset row, checksum, source commit, and provenance.
2. Keep historical rows carrying the old digest readable and unchanged. New service-created, prepared, and activated releases must use the checked 31f… digest.
3. Add the dedicated local regression coverage for content_sync.dtc_content.preparation._existing_release rejecting a legacy-digest replay before activation, with the existing release, active pointer, and child records unchanged.
4. Keep the clean, populated pre-repair, and already-recorded-0004 migration state matrix, idempotence, service invariants, replay behavior, handoff evidence, and portable Django verification required before technical acceptance.
5. Defer only the authorized post-merge exact-image deployment, failed-migration drill, external applied-0004-state check, failure classification, readiness, and deployed-smoke gates to on-call.
6. Preserve the migration-first, readiness-next, web/worker mutation ordering and all redaction/data-safety boundaries.

The old digest remains immutable historical provenance through the deployment and agreed rollback window. Any later cleanup, normalization, or retirement of legacy values requires a separate groomed issue.

Explicit non-goals

• Do not bulk-update old public_contracts_sha256 values to the new digest merely to satisfy a check constraint.
• Do not delete, truncate, recreate, re-import, or destructively reverse ContentRelease history or child records.
• Do not weaken the requirement that new candidates use the checked contract artifact.
• Do not skip local migration, service, replay, handoff, verification-plan, or portability tests because their deployed counterpart is deferred.
• Do not run the unchanged failing migration against the shared development database.
• Do not relax, bypass, or reorder migration, readiness, web/worker, rollback, or redaction controls.
• Do not change editorial source ownership, rendering, routes, SEO, cache policy, public database-read cutover, or unrelated content-sync behavior.
• This PM re-grooming does not access AWS, production data, or deployment state.

Dependencies and blocked work

• The engineer must first complete the dedicated legacy-digest replay regression and all required local criteria in the uncommitted worktree. The shared development database is not a fixture.
• The exact-image deployment and external applied-0004-state evidence are downstream of technical acceptance and the normal process sequence: engineer commit, local main merge, push, then on-call observation.
• The on-call gate must use the current deployment controller and retain redacted pre-mutation/recovery evidence; it must not use the engineer or tester worktree as a substitute for the merged exact image.
• No product-feature dependency is introduced. The issue is intentionally open until the named human gates pass.

Acceptance criteria

The numbered criteria preserve the first scope for traceability. Criteria tagged [AUTO] are required before technical acceptance and cannot be skipped. Criteria tagged [HUMAN] are deferred gates only; they remain required for final acceptance and closure.

Required automated and pre-merge technical criteria

• 1. [AUTO] A deterministic migration test starts at content.0003 with synthetic active and historical ContentRelease rows using the old digest, related documents/assets/relations, and an active source pointer. Migrating to the repaired leaf succeeds without changing row counts, primary keys, statuses, pointers, child rows, checksums, source commits, or either historical digest value.
• 2. [AUTO] The migration suite covers a clean zero-to-leaf database, the populated pre-repair path, and a database that already has the recorded content.0004 state. All paths converge to the intended schema without duplicate constraints, migration drift, or manual SQL.
• 3. [AUTO] Reapplying the repaired migration path is a no-op. Any data operation is forward, idempotent, provenance-preserving, and limited to an explicitly documented compatibility marker/metadata transition; no content body, asset, relation, release identity, or active pointer is rewritten.
• 4. [AUTO] A dedicated regression test exercises content_sync.dtc_content.preparation._existing_release with a legacy-digest replay and proves the replay is rejected before activation while the existing release, active pointer, and child records remain unchanged. The surrounding service tests must still prove canonical current-digest creation/preparation/activation, safe replay behavior, and legacy rollback selection.
• 5. [AUTO] New service-created, prepared, and activated releases use the exact checked digest 31f505350566bfcde0a30109dadcfb3565042fd395b4c1bd151966f94d361332. A non-canonical new candidate is rejected before activation, while historical old-digest releases remain readable and rollback-selectable.
• 6. [AUTO] Required uv-backed verification passes, including make migrations-check, make test-migrations, the relevant content and content-sync tests, the generated full quality/SQLite change-selective closure, and exact base/head, plan, graph, state, and artifact digests. The migration remains within the portable Django boundary with no PostgreSQL-only application branch or raw vendor SQL.
• 8. [AUTO] Before technical acceptance, the engineer handoff emits the exact migration files/state transitions, fixture provenance, before/after aggregate counts and checksums, active-release identity, and redaction proof. The verification report/check validates this local evidence; this is a required pre-merge handoff criterion, not a [HUMAN] gate.
• 13. [AUTO] Because this issue has no template, route, static-asset, or rendered-content input, the plan and tester report mark the browser screenshot component not_applicable with the required reason. No unrelated screenshot is accepted as migration evidence. If implementation changes rendered behavior, the normal independent desktop/mobile screenshot gate becomes required.

Deferred [HUMAN] / on-call gates after merge and push

• 7. [HUMAN] [on-call] In the authorized target environment, record the actual applied-0004 state and migration history outside disposable CI. Redacted evidence must identify the target/environment and show why the local synthetic state matrix is or is not representative, without exposing credentials, production data, or authorization material.
• 9. [HUMAN] [on-call] Run the merged exact image through the migration task and retain redacted VERSION, full source SHA, image digest, migration task identity/stage, exit code or bounded reason, and the pre-mutation web/worker checkpoint. A failed migration must stop before web/worker mutation.
• 10. [HUMAN] [on-call] Produce the required data-versus-runtime/infrastructure classification matrix. A data/contract defect requires the same exact image to reproduce the invariant/constraint failure against the isolated populated fixture and identify the failing migration/state. A runtime/infrastructure defect requires that exact image to pass the equivalent populated migration while the deployed task fails, with redacted task stop reason, database reachability/configuration, resource/timeout/health evidence, and no data rewrite as remediation. contract_contradiction alone is insufficient.
• 11. [HUMAN] [on-call] Deploy the merged exact image through the current controller: migration succeeds before any web/worker update; database-aware readiness reports the expected schema and no unapplied migrations; web and worker stabilize on the same release identity; and recovery/rollback evidence remains available.
• 12. [HUMAN] [on-call] Exercise the failed-migration path with a controlled synthetic failure or equivalent authorized drill and prove the prior web/worker pair remains active, no partial release is reported, and recovery evidence is retained. Do not use the shared development database.
• 14. [HUMAN] [on-call] Run the existing read-only deployed smoke at https://web.dtcdev.click, checking health/readiness, representative public availability, and absence of a new public 5xx, redirect, or canonical regression. Capture no production export, PII, credentials, tokens, or provider payloads.

Technical handoff and exact disposition

• Local technical acceptance is conditional on every [AUTO] criterion above, including the new criterion 4 regression and criterion 8 handoff evidence, being implemented and independently verified. A passing local suite does not imply final issue acceptance.
• After the automated tester gate passes, the engineer commit and local merge/push must use Refs #219, not Closes #219, because named human verification remains.
• The issue remains OPEN with the human label while criteria 7, 9, 10, 11, 12, and 14 are pending. On-call owns those post-merge gates and must post the redacted evidence/report to #219.
• Final PM acceptance and closure require the on-call evidence, all [HUMAN] criteria checked by the owning role, and no unresolved classification or readiness/smoke exception.

Start with content/migrations/0001_initial.py and content/migrations/0004_remove_contentrelease_content_release_contract_sha_ck_and_more.py, then read content_sync.dtc_content.preparation._existing_release. Run make migrations-check and make test-migrations before the relevant content and content-sync tests. Done requires legacy-digest replay rejection with records unchanged, current-digest service coverage, preserved migration data, and the required handoff evidence.