V4 final docs

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "chat.sessionSync.enabled": true
+}

docs/ver4/architecture_v4.md

@@ -12,7 +12,6 @@ This document describes the production architecture of the document transcriptio
 - Keep operator workflows cross-platform and Python-driven.
 - Support many-to-many document-person relationships with extensible roles.
 - Support registry-driven document type classification.
-- Enforce relationship-role exclusivity rules consistently across UI, API, and persistence boundaries.
 
 ## Runtime Topology
 
@@ -104,7 +103,7 @@ Responsibilities:
 2. UI loads existing links grouped by role.
 3. User adds or removes people within one or more roles.
 4. Service computes add/remove deltas rather than replacing all links blindly.
-5. Conflict checks enforce exclusivity policy before persistence commits.
+5. Conflict checks enforce uniqueness and deterministic write semantics before persistence commits.
 
 ### 3. Document Type Management
 
@@ -120,7 +119,6 @@ Responsibilities:
 - Prompt and parameter provenance is frozen on `Job` at submission time.
 - Provider output evidence is stored on `JobSource` for each page execution.
 - `DocumentPerson` links are unique for `(document_id, person_id, role_id)`.
-- Configured exclusive role pairs cannot coexist for the same `(document_id, person_id)`.
 - Relationship mutations are deterministic and set-based.
 - `DocumentType.code` is stable; `DocumentType.label` may evolve.
 
@@ -130,12 +128,11 @@ Responsibilities:
 - `Source` belongs to one `Document` and may participate in many `JobSource` executions.
 - `Job` has many `JobSource` rows.
 - `PersonRole` defines available relationship roles.
-- `RoleExclusivity` defines role pairs that cannot coexist for the same document-person pair.
 
 ## Test Strategy
 
 - Unit tests for models, validation, hashing, and registry resolution.
-- Service tests for CRUD, set-based sync, and exclusivity enforcement.
+- Service tests for CRUD, set-based sync, uniqueness conflicts, and deterministic relationship writes.
 - Async workflow tests for page isolation, partial failure handling, and stored evidence.
 - UI integration tests for multi-page rendering, role grouping, and document type selection.
 

docs/ver4/error_handling_v4.md

@@ -27,7 +27,7 @@ This policy governs error behavior across:
 | `validation_error` | Payload, parameter, or schema validation failure | no |
 | `user_input_error` | Unacceptable file, invalid selection, or malformed request from the operator | no |
 | `not_found_error` | Requested `Document`, `Source`, `Person`, `Job`, role, or type does not exist | no |
-| `conflict_error` | Operation violates uniqueness or exclusivity policy | no |
+| `conflict_error` | Operation violates uniqueness or relationship-write policy | no |
 | `external_provider_error` | Provider API failure, rate limit, or execution problem | yes |
 | `infrastructure_transient_error` | Temporary DB, file-system, or network instability | yes |
 | `infrastructure_persistent_error` | Persistent configuration, credential, or database availability failure | no |
@@ -61,14 +61,14 @@ API error responses return a structured envelope:
 {
   "error_id": "err_uuid_12345",
   "category": "conflict_error",
-  "message": "Role assignment violates exclusivity policy.",
+  "message": "Relationship write conflicts with existing links.",
-  "suggestion": "Remove recipient before assigning author for this person on this document.",
+  "suggestion": "Adjust the requested relationship links and retry.",
   "details": {
     "document_id": "...",
     "person_id": "...",
-    "attempted_role": "author",
+    "attempted_role": "recipient",
-    "conflicting_role": "recipient",
+    "operation": "add_link",
-    "policy_rule": "author+recipient exclusive"
+    "conflict_reason": "duplicate document-person-role link"
   },
   "timestamp": "2026-08-10T15:00:00Z"
 }

docs/ver4/implementation_plan_v4.md

@@ -13,7 +13,7 @@ Implement the Version 4 project definition from the current repository state whi
 ## Current Project Impact
 
 - `src/transcription/db/models.py` requires full schema alignment with the V4 core documents.
-- `src/transcription/services/documents.py` requires set-based document-person sync, exclusivity checks, and document-type resolution.
+- `src/transcription/services/documents.py` requires set-based document-person sync and document-type resolution.
 - API modules require additive role-aware relationship behavior and document-type selection behavior.
 - UI pages require grouped role displays, multi-role editing, and registry-backed document-type selection.
 - Existing tests require updates for role enforcement, document-type selection, and regression safety.
@@ -29,7 +29,7 @@ Implement the Version 4 project definition from the current repository state whi
 ### 2. Align the Persistence Layer
 
 - Update SQLModel definitions to match the final V4 schema.
-- Add `person_role`, `role_exclusivity`, and `document_type` support.
+- Add `person_role` and `document_type` support.
 - Replace legacy document-type storage with `document_type_id`.
 - Apply the accepted manual exception strategy for `document_type` and `document_person` data.
 - Preserve all other data structures non-destructively.
@@ -37,7 +37,7 @@ Implement the Version 4 project definition from the current repository state whi
 ### 3. Update Services and Write Semantics
 
 - Implement set-based synchronization for document-person updates.
-- Implement deterministic exclusivity conflict checks.
+- Implement deterministic uniqueness and relationship-write conflict checks.
 - Remove suggestion-related service behavior.
 - Add document-type resolution and validation by stable code or id.
 
@@ -57,7 +57,7 @@ Implement the Version 4 project definition from the current repository state whi
 
 ### 6. Verification and Hardening
 
-- Add or update service tests for many-per-role behavior, exclusivity enforcement, and set-based sync correctness.
+- Add or update service tests for many-per-role behavior, uniqueness conflict handling, and set-based sync correctness.
 - Add API tests for relationship behavior and document-type selection.
 - Add UI tests or walkthrough coverage for grouped roles and type selection.
 - Add regression coverage for delete and cleanup semantics.
@@ -66,7 +66,7 @@ Implement the Version 4 project definition from the current repository state whi
 
 - Core V4 documents and code paths agree on the final project definition.
 - Relationship-role writes are deterministic and non-destructive.
-- Exclusivity rules are enforced consistently.
+- Relationship-write conflict rules are enforced consistently.
 - Document type selection is registry-backed.
 - The accepted manual exceptions for `document_type` and `document_person` are completed.
 - The focused test coverage passes.

docs/ver4/requirements_v4.md

@@ -13,7 +13,7 @@ This document defines the baseline requirements for the document transcription s
 | REQ-4 | Functional | Support job states `queued`, `processing`, `completed`, `partial_success`, and `failed`, plus page states `pending`, `transcribed`, and `failed`. | inspection |
 | REQ-5 | Functional | Allow users to manage historical `Person` records and link multiple people per role to a `Document`. | test |
 | REQ-6 | Functional | Support an extensible role taxonomy for document-person relationships. | inspection |
-| REQ-7 | Policy Constraint | Enforce a role exclusivity matrix for a single `(document_id, person_id)` pair; initial rules must block `author` + `recipient` coexistence while allowing `mentioned` to coexist with other roles. | test |
+| REQ-7 | Policy Constraint | Enforce deterministic relationship-role writes with uniqueness on `(document_id, person_id, role_id)` and explicit conflict responses for invalid duplicate link attempts. | test |
 | REQ-8 | Functional | Use set-based synchronization for document-person mutations so updates add and remove only the intended links. | test |
 | REQ-9 | Functional | Maintain immutable machine output on `Source.raw_transcription` while permitting inline human edits on `Source.revised_text`. | test |
 | REQ-10 | Functional | Support a registry-driven `DocumentType` taxonomy with stable codes, mutable labels, and active/inactive lifecycle control. | test |
@@ -31,7 +31,7 @@ This document defines the baseline requirements for the document transcription s
 
 1. `DocumentType.code` and `PersonRole.code` are stable machine identifiers.
 2. `DocumentType.label` and `PersonRole.label` may evolve without changing canonical identity.
-3. Role-policy enforcement must be consistent across UI, API, services, and persistence.
+3. Relationship-write policy and conflict handling must be consistent across UI, API, services, and persistence.
 4. Many-per-role behavior is required for document-person links.
 5. Relationship conflicts must fail deterministically without partial mutation.
 

docs/ver4/schema_v4.md

@@ -25,13 +25,6 @@ TIMESTAMPTZ created_at
 TIMESTAMPTZ updated_at
 }
 
-ROLE_EXCLUSIVITY {
-UUID id PK
-UUID left_role_id FK
-UUID right_role_id FK
-TIMESTAMPTZ created_at
-}
-
 PERSON {
 UUID id PK
 TEXT full_name
@@ -120,8 +113,6 @@ DOCUMENT_TYPE ||--o{ DOCUMENT : classifies
 DOCUMENT ||--o{ DOCUMENT_PERSON : has_people
 PERSON ||--o{ DOCUMENT_PERSON : appears_in
 PERSON_ROLE ||--o{ DOCUMENT_PERSON : labels
-PERSON_ROLE ||--o{ ROLE_EXCLUSIVITY : left_rule
-PERSON_ROLE ||--o{ ROLE_EXCLUSIVITY : right_rule
 DOCUMENT ||--o{ JOB : has_jobs
 DOCUMENT ||--o{ SOURCE : contains_pages
 JOB ||--o{ JOB_SOURCE : executes
@@ -154,8 +145,7 @@ SOURCE ||--o{ JOB_SOURCE : processed_in
 - Documents support zero, one, or many people per relationship role.
 - Relationship roles are defined by `PERSON_ROLE` rather than hardcoded columns.
 - `DOCUMENT_PERSON` must be unique for `(document_id, person_id, role_id)`.
-- Configured exclusive role pairs from `ROLE_EXCLUSIVITY` cannot coexist for the same `(document_id, person_id)`.
+- Relationship writes must be deterministic and use explicit add/remove link intent.
-- Initial exclusivity seed blocks `author` and `recipient` for the same person-document pair.
 
 ### Document Type Governance
 
@@ -169,8 +159,6 @@ SOURCE ||--o{ JOB_SOURCE : processed_in
 - `DOCUMENT_TYPE.code` is unique.
 - `PERSON_ROLE.code` is unique.
 - `DOCUMENT_PERSON(document_id, person_id, role_id)` is unique.
-- `ROLE_EXCLUSIVITY(left_role_id, right_role_id)` is unique.
-- `ROLE_EXCLUSIVITY` must use canonical ordering to avoid duplicate mirrored pairs.
 
 ## Indexing Guidance
 
@@ -178,7 +166,6 @@ SOURCE ||--o{ JOB_SOURCE : processed_in
 - `document_person(document_id)`
 - `document_person(person_id)`
 - `document_person(role_id)`
-- `role_exclusivity(left_role_id, right_role_id)`
 - `source(document_id, page_number)`
 - `job(document_id, status)`
 - `job_source(job_id)`

docs/ver4/scope_boundary_v4.md

@@ -12,7 +12,6 @@ Define what this revision includes, what it intentionally excludes, and what mig
 
 - Extensible role taxonomy for document-person relationships.
 - Many-to-many document-person links with many people per role.
-- Deterministic exclusivity policy for configured role pairs.
 - Set-based add/remove synchronization for document-person updates.
 
 ### 2. Document Type Governance
@@ -30,7 +29,6 @@ Define what this revision includes, what it intentionally excludes, and what mig
 ### 4. Verification
 
 - Tests for many-per-role behavior.
-- Tests for exclusivity enforcement.
 - Tests for set-based relationship mutation behavior.
 - Tests for document and person delete/link cleanup regressions.
 
@@ -49,23 +47,18 @@ Define what this revision includes, what it intentionally excludes, and what mig
 
 - Use registry tables for relationship roles.
 
-### B. Exclusivity Matrix Baseline
+### B. API Compatibility Strategy
-
-- `author` and `recipient` are mutually exclusive for the same `(document, person)` pair.
-- `mentioned` remains non-exclusive.
-
-### C. API Compatibility Strategy
 
 - Use additive API evolution.
 - In development mode, the current revision is authoritative.
 - Deprecations should be explicit and short-lived.
 
-### D. Document Type Rollout Strategy
+### C. Document Type Rollout Strategy
 
 - Use a minimal registry rollout for the current corpus.
 - Do not introduce a `document_type_alias` helper table.
 
-### E. Database Change Policy
+### 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.
@@ -81,7 +74,8 @@ Define what this revision includes, what it intentionally excludes, and what mig
 
 V4 scope is considered frozen when:
 
-- Relationship model, exclusivity rules, and document-type governance are approved.
+- 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.