generated from john/python-template
135 lines
4.7 KiB
Markdown
135 lines
4.7 KiB
Markdown
# 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`
|