# Implementation Plan (Version 4)

## Goal

Implement the Version 4 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

- 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 stable code or id.

### 4. Update API Contracts

- Keep API evolution additive.
- Add role-aware relationship retrieval and write behavior.
- Add document-type catalog retrieval and code-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.

## 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)