transcription/docs/ver4/scope_boundary_v4.md

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