Prep for GPT-5.3-codex architecture & code review.

docs/ver4.0/implementation_plan_v4.md

@@ -0,0 +1,102 @@
+# Implementation Plan (version 4.0)
+
+## Goal
+
+Implement the version 4.0 project definition from the current repository state while preserving existing data by default.
+
+## Migration Policy
+
+- Database changes are non-destructive by default.
+- Exception: the legacy `document_type` text field may be replaced by a `document_type_id` reference without migrating existing text values.
+- Exception: `document_person` links may be recreated manually.
+
+## Current Project Impact
+
+- `src/transcription/db/models.py` requires full schema alignment with the V4 core documents.
+- `src/transcription/services/documents.py` requires set-based document-person sync and document-type resolution.
+- API modules require additive role-aware relationship behavior and document-type selection behavior.
+- UI pages require grouped role displays, multi-role editing, and registry-backed document-type selection.
+- Existing tests require updates for role enforcement, document-type selection, and regression safety.
+
+## Implementation Phases
+
+### 1. Finalize the Transition Documents
+
+- Confirm the reset scope.
+- Confirm the database exception policy.
+- Keep core V4 documents as the only authoritative product definition.
+
+### 2. Align the Persistence Layer
+
+- Update SQLModel definitions to match the final V4 schema.
+- Add `person_role` and `document_type` support.
+- Replace legacy document-type storage with `document_type_id`.
+- Apply the accepted manual exception strategy for `document_type` and `document_person` data.
+- Preserve all other data structures non-destructively.
+
+### 3. Update Services and Write Semantics
+
+- Organize service ownership around Documents, Sources, Jobs, and People.
+- Centralize Source extension and MIME policy in the Sources service.
+- Treat upload as an interface action and remove it from domain service naming where compatibility permits.
+- Implement set-based synchronization for document-person updates.
+- Implement deterministic uniqueness and relationship-write conflict checks.
+- Remove suggestion-related service behavior.
+- Add document-type resolution and validation by UUID.
+
+### 4. Update API Contracts
+
+- Keep API evolution additive.
+- Add role-aware relationship retrieval and write behavior.
+- Add document-type catalog retrieval and UUID-based selection for document writes.
+- Remove suggestion-related API surfaces from the V4 target state.
+
+### 5. Update UI Workflows
+
+- Replace single-person link editing with grouped multi-role editing.
+- Render grouped role links on document and person detail views.
+- Replace free-text document type entry with registry-backed selection.
+- Preserve clear validation and conflict messaging.
+
+### 6. Verification and Hardening
+
+- Add or update service tests for many-per-role behavior, uniqueness conflict handling, and set-based sync correctness.
+- Add API tests for relationship behavior and document-type selection.
+- Add UI tests or walkthrough coverage for grouped roles and type selection.
+- Add regression coverage for delete and cleanup semantics.
+- Enforce backup-first test execution for AI-run unit tests: backup `./data` before tests, then always prompt for restore after successful tests.
+- Keep restore confirmation-gated by default so code and test outcomes can be reviewed before data is reverted.
+
+## Done When
+
+- Core V4 documents and code paths agree on the final project definition.
+- Relationship-role writes are deterministic and non-destructive.
+- Relationship-write conflict rules are enforced consistently.
+- Document type selection is registry-backed.
+- The accepted manual exceptions for `document_type` and `document_person` are completed.
+- The focused test coverage passes.
+
+## Out of Scope
+
+- Suggested/asserted relationship state.
+- Suggestion review or extraction workflows.
+- Global person entity-resolution engine.
+- Automated semantic document-type classification.
+
+## Delivery Order Recommendation
+
+1. Freeze scope boundary and implementation plan.
+2. Freeze core V4 documents.
+3. Align persistence models.
+4. Align services and API behavior.
+5. Align UI behavior.
+6. Run focused verification and regression checks.
+
+## Related Local References
+
+- [V4 Scope Boundary](scope_boundary_v4.md)
+- [System Overview](index_v4.md)
+- [System Requirements](requirements_v4.md)
+- [Data Model](schema_v4.md)
+- [System Architecture](architecture_v4.md)
+- [Error Handling Policy](error_handling_v4.md)