transcription/docs/ver4/scope_boundary_v4.md

V4 Scope Boundary

This document defines the scope for the transition from the current repository state to the Version 4 project definition.

Purpose

Define what this revision includes, what it intentionally excludes, and what migration rules govern the transition work.

In Scope

1. Relationship Model

• Extensible role taxonomy for document-person relationships.
• Many-to-many document-person links with many people per role.
• Set-based add/remove synchronization for document-person updates.

2. Document Type Governance

• Registry-driven DocumentType model with UUID identity, unique labels, and controlled selection.
• Minimal rollout for the current corpus with no alias helper table.

3. UI and API Behavior

• Grouped role links on document and person views.
• Multi-role relationship editing on document create/edit flows.
• Role-aware API retrieval and write behavior.
• Additive API evolution with explicit deprecations.

4. Verification

• Tests for many-per-role behavior.
• Tests for set-based relationship mutation behavior.
• Tests for document and person delete/link cleanup regressions.

Out of Scope

• Suggested versus asserted relationship states.
• Suggestion storage, review, acceptance, or rejection workflows.
• Automatic relationship extraction or recommendation features.
• Full entity resolution or identity merge across all people.
• Automated semantic document type classification.
• Redesign of the core transcription execution model.

Locked Design Decisions

A. Role Extensibility Mechanism

• Use registry tables for relationship roles.

B. API Compatibility Strategy

• Use additive API evolution.
• In development mode, the current revision is authoritative.
• Deprecations should be explicit and short-lived.

C. Document Type Rollout Strategy

• Use a minimal registry rollout for the current corpus.
• Do not introduce a document_type_alias helper table.

D. Database Change Policy

• Future schema changes are non-destructive by default.
• Exception: document_type text may be replaced by document_type_id without migrating the legacy text values.
• Exception: document_person links may be recreated manually.

Compatibility and Rollout

• Preserve existing repository behavior where unaffected by the V4 scope.
• Treat scope boundary and implementation plan as the only transition documents.
• Treat core V4 documents as the authoritative project definition once rewritten.

Exit Criteria for Scope Freeze

V4 scope is considered frozen when:

• Relationship model and document-type governance are approved.
• Relationship model and document-type governance are approved.
• Additive API change list and deprecation schedule are approved.
• Migration exceptions are explicitly acknowledged.

Core V4 Documents

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