V4 plan created: Adding many-to-many links between Documents & People in the UI. Also adding some new tables for Document Type, Person role.

docs/ver4/implementation_plan_v4.md

@@ -0,0 +1,107 @@
+# Implementation Plan (Version 4)
+
+## Goal
+
+Implement V4 document-person relationship expansion and document type governance with extensible registries, assisted suggestion lifecycle, and policy-enforced exclusivity while preserving V3 transcription behavior.
+
+## Current Project Impact
+
+- `src/transcription/db/models.py` will require relationship schema evolution for role extensibility and suggestion lifecycle support.
+- `src/transcription/db/models.py` will require document type registry entities and document type reference updates.
+- `src/transcription/services/documents.py` will require set-based relationship sync and policy checks.
+- `src/transcription/services/documents.py` will require registry-based document type lookup, validation, and normalization helpers.
+- API modules under `src/transcription/api/**` will require role/state-aware contracts and suggestion lifecycle endpoints.
+- API modules under `src/transcription/api/**` will require additive document type catalog and code-based selection contracts.
+- UI pages under `src/transcription/ui/pages/**` will require multi-role, multi-person editing, suggestion review controls, and registry-backed type selectors.
+- Existing tests under `tests/services`, `tests/api`, and `tests/ui` need expanded coverage for V4 behavior and regression safety.
+
+## Implementation Phases
+
+### 1. Finalize V4 Schema Decisions
+
+- Role extensibility mechanism: use role registry tables.
+- Document type extensibility mechanism: use `document_type` registry tables.
+- Suggestion storage model: use a separate `document_person_suggestion` table.
+- Exclusivity baseline: `author` vs `recipient` exclusive, `mentioned` non-exclusive.
+- Enforce exclusivity on asserted links; evaluate conflicts on suggestion acceptance.
+
+### 2. Evolve Persistence Layer
+
+- Implement selected schema model in SQLModel.
+- Add constraints and indexes for dedupe, filtering, and policy support.
+- Add migration/backfill logic for V3 links to V4 asserted semantics.
+- Add conflict scan tooling for historical records violating exclusivity rules.
+- Perform a one-time manual mapping of existing document type values to registry-backed type references (`document_type_id`) for the current small corpus.
+
+### 3. Implement Service-Layer Policy and Sync Semantics
+
+- Add relationship delta sync operations (set-based add/remove).
+- Implement centralized policy evaluator for exclusivity checks.
+- Add suggestion lifecycle operations (propose/list/accept/reject).
+- Ensure accepted suggestions create/confirm asserted links atomically.
+- Add document type resolution operations by stable `code` and active/inactive state handling.
+
+### 4. Implement API Contract Changes
+
+- Add role-aware and state-aware query parameters/filters.
+- Add suggestion lifecycle endpoints and response models.
+- Add deterministic conflict/error payloads aligned to V4 error policy.
+- Use additive endpoint evolution for V4; during development mode, deprecate then remove without maintaining long-lived legacy runtime compatibility layers.
+- Add document type catalog endpoints with active-only filtering and code-based selection for document writes.
+
+### 5. Update UI Workflows
+
+- Replace single-author controls with grouped multi-role selectors.
+- Replace unconstrained document type free-text entry with registry-backed type selection.
+- Add pending suggestion review panel and accept/reject actions.
+- Update document/person detail cards to group links by role and state.
+- Preserve edit-state ergonomics on validation/conflict failures.
+
+### 6. Verification and Hardening
+
+- Add service tests for:
+  - many-per-role behavior,
+  - exclusivity enforcement,
+  - set-based sync correctness,
+  - suggestion transition validity,
+  - document type code resolution and inactive-type handling.
+- Add API tests for role/state filtering and conflict response shapes.
+- Add API tests for document type catalog retrieval and code-based write validation.
+- Add UI tests/manual walkthroughs for create/edit/review workflows.
+- Add UI tests/manual walkthroughs for registry-backed document type selection and validation messaging.
+- Add regression tests for document/person delete cleanup semantics.
+
+## Done When
+
+- V4 relationship schema and contracts are implemented and validated.
+- V4 document type registry schema and contracts are implemented and validated.
+- Suggestions remain non-canonical until explicit acceptance.
+- Exclusivity policy is enforced deterministically across service/API boundaries.
+- Existing V3 links are migrated to V4 asserted semantics without data loss.
+- Existing document type strings are manually normalized to registry references for the current corpus.
+- Test suite includes V4-specific coverage and passes on supported backends.
+
+## Out of Scope
+
+- Automatic acceptance of suggestions.
+- Global person entity-resolution/merge engine.
+- Core transcription execution redesign unrelated to relationship expansion.
+- Automated semantic document type classification.
+
+## Delivery Order Recommendation
+
+1. Requirements freeze (`requirements_v4.md`).
+2. Schema decision freeze (`schema_v4.md`).
+3. Error policy freeze (`error_handling_v4.md`).
+4. Implementation of persistence and service layer.
+5. API and UI changes.
+6. Final integration and regression validation.
+
+## Related Local References
+
+- [V4 Scope Boundary](scope_boundary_v4.md)
+- [V4 Requirements](requirements_v4.md)
+- [V4 Schema](schema_v4.md)
+- [V4 Architecture](architecture_v4.md)
+- [V4 Error Handling](error_handling_v4.md)
+- [V3 Implementation Plan](../implementation_plan_v3.md)