# V4 Scope Boundary (Version 4)

This document defines what is and is not included in Version 4 for expanding `Document`-`Person` relationships.

## Purpose

Create a clear implementation boundary before updating full V4 architecture, requirements, schema, and plan documents.

## Why This Is V4 (Not V3.1)

V4 is required because the change is semantic and cross-cutting:

- Expands relationship meaning beyond fixed `author`/`recipient`.
- Introduces a suggestion lifecycle (`suggested` vs `asserted`).
- Introduces policy constraints (role exclusivity matrix).
- Impacts persistence, service contracts, API behavior, UI workflows, and test strategy.

A V3.1 patch would only be appropriate for non-semantic quality-of-life fixes inside existing role semantics.

## In Scope for V4

### 1) Relationship Semantics

- Role taxonomy becomes extensible (not hardcoded to only two role values).
- A `Document` can link to many `Person` records per role.
- Relationship states are explicit:
  - `asserted`: human-confirmed canonical link.
  - `suggested`: machine- or heuristic-proposed link pending review.

### 2) Policy Rules

- Enforce role exclusivity for the same `(document, person)` pair where configured.
- Initial policy decision:
  - `author` + `recipient` are mutually exclusive.
  - `mentioned` may coexist with other roles.

### 3) Persistence and Contracts

- Evolve persistence model to support:
  - extensible roles,
  - suggestion lifecycle metadata,
  - deterministic conflict handling.
- Replace single-value relationship mutation patterns with set-based sync behavior.

### 4) Human-in-the-Loop Workflow

- Add assisted suggestion review flow:
  - list suggestions,
  - accept,
  - reject,
  - promote accepted suggestion to asserted link.
- No silent auto-promotion from suggestion to asserted.

### 5) UI and API Behavior

- Document create/edit/detail workflows support multi-person per role.
- UI surfaces grouped role links and suggestion status.
- API supports role-aware retrieval and suggestion lifecycle operations.

### 6) Verification

- Add tests for:
  - many-per-role behavior,
  - exclusivity enforcement,
  - suggestion lifecycle,
  - migration/conflict detection,
  - regression on delete/link cleanup behavior.

## Out of Scope for V4

- Automatic acceptance of suggested links without human review.
- Full entity resolution/identity merge pipeline across all `Person` records.
- Historical provenance graph redesign beyond relationship-level evidence fields.
- Large-scale NLP research features unrelated to document-person linking.
- Changes to core transcription execution model (`Job`, `JobSource`) except where needed to expose suggestion evidence inputs.

## Locked Design Decisions

### A) Role Extensibility Mechanism

- Adopt role registry tables (data-driven roles).
- Do not use enum-first role expansion for V4.

### B) Suggestion Storage Model

- Adopt a separate `document_person_suggestion` table.
- Keep `document_person` focused on canonical asserted links.
- Revisit only if operational complexity proves materially higher than expected.

### C) Exclusivity Matrix Baseline

- `author` + `recipient` are mutually exclusive for the same `(document, person)` pair.
- `mentioned` remains non-exclusive.
- Hard exclusivity enforcement applies to asserted links.
- Suggestions may be stored even if they would conflict at assert time; promotion to asserted must enforce exclusivity.

### D) API Compatibility Strategy

- Use additive API evolution in V4.
- In development mode, the current revision is authoritative; long-lived legacy compatibility layers are not required.
- Deprecations should be explicit and short-lived, with removals performed in subsequent revisions.

### E) Document Type Rollout Strategy

- Use a minimal registry rollout for the current corpus: no `document_type_alias` helper table.
- Perform a one-time manual mapping of existing document types to canonical registry types.

### F) Suggestion Generation Strategy (Still Open)

- Option A: deterministic rules/NLP over transcribed text.
- Option B: LLM extraction with confidence/evidence spans.

## Compatibility and Rollout

- Existing V3 author links migrate to `asserted` behavior.
- Backfill validation identifies policy conflicts before constraints are enforced.
- Preserve existing V3 core behavior where unaffected by role/suggestion evolution.

## Exit Criteria for Scope Freeze

V4 scope is considered frozen when:

- Suggestion generation strategy is chosen.
- Suggestion acceptance workflow details are approved.
- Additive API change list and deprecation schedule are approved.

## Core V4 Documents (Current Set)

1. `docs/ver4/index_v4.md`
2. `docs/ver4/requirements_v4.md`
3. `docs/ver4/schema_v4.md`
4. `docs/ver4/architecture_v4.md`
5. `docs/ver4/error_handling_v4.md`
6. `docs/ver4/implementation_plan_v4.md`