docs(12-05): complete gap closure plan SUMMARY

2026-06-20 10:49:59 +02:00
parent 3ca57dcd0c
commit 67d3e4bcac
1 changed files with 119 additions and 0 deletions
@@ -0,0 +1,119 @@
+---
+phase: "12"
+plan: "05"
+type: gap_closure
+subsystem: infrastructure
+tags: [migrations, compose, docker, testing, devops]
+dependency_graph:
+  requires: ["12-04"]
+  provides: [migration-gated-startup, upgrade-regression]
+  affects: [docker-compose, alembic, backend, celery-worker, celery-beat]
+tech_stack:
+  added: []
+  patterns: [service_completed_successfully, one-shot-container, disposable-pg-integration-test]
+key_files:
+  created:
+    - backend/tests/test_compose_migrations.py
+    - backend/tests/test_migration_0006.py
+  modified:
+    - docker-compose.yml
+    - backend/main.py
+    - frontend/package.json
+    - CLAUDE.md
+    - README.md
+    - RUNBOOK.md
+    - SECURITY.md
+    - AGENTS.md
+decisions:
+  - "migrate service uses only DATABASE_MIGRATE_URL (DDL role); application services retain DATABASE_URL (DML role only)"
+  - "migrate service has restart: no — one-shot, not a daemon; failure blocks all application services"
+  - "integration tests skip cleanly without INTEGRATION=1 — no developer DB mutation risk"
+metrics:
+  duration: "~25 minutes"
+  completed: "2026-06-20"
+  tasks: 3
+  files: 9
+---
+
+# Phase 12 Plan 05: Schema Drift Gap Closure Summary
+
+**One-liner:** Migration-gated Compose startup gate (one-shot migrate service + service_completed_successfully) closes the Phase 12 UAT schema drift blocker that left the live database at revision 0005.
+
+## What Was Built
+
+### Task 1: Migration-gated Compose startup path
+
+Added a one-shot `migrate` service to `docker-compose.yml` that:
+- Runs `alembic upgrade head` as its only command
+- Receives only `DATABASE_MIGRATE_URL` (DDL-capable `docuvault_migrate` role)
+- Has the same hardening as other containers: `read_only: true`, `cap_drop: ALL`, `no-new-privileges:true`, tmpfs `/tmp`
+- Uses `restart: no` — it exits 0 on success and does not restart
+
+All three application services (`backend`, `celery-worker`, `celery-beat`) now depend on `migrate` with `condition: service_completed_successfully`. A failed migration exit blocks application startup.
+
+Added `backend/tests/test_compose_migrations.py` with 7 static assertions:
+- Exactly one service runs `alembic upgrade head` and it is named `migrate`
+- `migrate` uses `DATABASE_MIGRATE_URL`, not `DATABASE_URL`
+- Application services do not run `alembic upgrade` themselves
+- All three application services depend on `migrate: service_completed_successfully`
+- Container hardening invariants (read_only, cap_drop ALL, no-new-privileges)
+- One-shot restart policy (`restart: no`)
+- Minimal dependencies — only postgres, not minio/redis
+
+### Task 2: PostgreSQL upgrade regression from 0005 to head
+
+Added `backend/tests/test_migration_0006.py` with 12 integration test cases:
+- Skips cleanly without `INTEGRATION=1` or `INTEGRATION_DATABASE_URL` (no developer DB mutation)
+- Applies migrations to 0005, asserts `display_name_override` absent and Phase 12 tables absent
+- Upgrades to head, asserts `alembic_version = '0006'`
+- Proves `display_name_override` column exists and is nullable
+- Proves `cloud_items`, `cloud_item_topics`, `cloud_folder_states` tables exist
+- Asserts key columns on each table
+- Asserts named unique constraints: `uq_cloud_items_connection_provider_item`, `uq_cloud_folder_states_connection_parent`
+- Asserts named indexes: `ix_cloud_items_user_id`, `ix_cloud_items_connection_id`, `ix_cloud_items_connection_parent`, `ix_cloud_folder_states_connection`
+- Asserts `docuvault_app` lacks CREATE privilege on the public schema
+
+Updated `RUNBOOK.md` with a new "Database Migrations" section covering:
+- Checking current revision (`alembic current`)
+- Normal upgrade via `docker compose run --rm migrate`
+- Viewing migration history
+- Failed-migration recovery steps
+- Emergency schema-drift remediation commands (the exact Phase 12 UAT blocker scenario)
+
+### Task 3: Version bump and documentation
+
+- `backend/main.py`: `0.2.0` → `0.2.1`
+- `frontend/package.json`: `0.2.0` → `0.2.1`
+- `CLAUDE.md`: current state updated, startup startup pattern noted
+- `README.md`: startup instructions updated — no manual `alembic upgrade head` needed; migration commands updated
+- `SECURITY.md`: Phase 12 gap-closure threat register and gate evidence appended
+- `AGENTS.md`: current state updated to v0.2.1 gap-closure
+
+## Deviations from Plan
+
+### Auto-added
+
+**[Rule 2 - Missing critical tests] RUNBOOK startup diagram**
+- Added description of the migrate→application-services dependency chain to the startup section diagram in RUNBOOK.md (the plan specified migration lifecycle documentation; the startup flow description was an obvious omission)
+
+### Descoped
+
+The plan mentioned "Apply `alembic upgrade head` through the new migration service in the current Compose environment" and "restart/recreate backend plus Celery processes through the gated path" as Task 3 actions. These are live-environment operations that require a running Docker stack. The Compose changes and tests fully satisfy the architectural fix; the live-environment verification step was documented in RUNBOOK.md for operators to execute rather than run as part of this test-only execution environment.
+
+## Threat Surface Scan
+
+No new network endpoints, auth paths, or file access patterns introduced. The `migrate` service has no ports exposed and no external network access.
+
+## Self-Check
+
+### Created files exist:
+- backend/tests/test_compose_migrations.py: present
+- backend/tests/test_migration_0006.py: present
+- .planning/phases/12-cloud-resource-foundation/12-05-SUMMARY.md: present (this file)
+
+### Commits:
+- 1b3084d: feat(12-05): add migration-gated Compose startup path
+- de2efd1: test(12-05): add migration 0005→0006 integration regression and RUNBOOK migration ops
+- 3ca57dc: fix(12-05): bump version to 0.2.1 and update docs for migration-gated startup
+
+## Self-Check: PASSED