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