From ccf2c78ff4c800dbb6b7309e4ee2d726d9dd4e8a Mon Sep 17 00:00:00 2001 From: Jim Lancaster <40281233+zoltan57@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:34:36 -0500 Subject: [PATCH] V4 final docs --- .vscode/settings.json | 3 +++ docs/ver4/architecture_v4.md | 7 ++----- docs/ver4/error_handling_v4.md | 12 ++++++------ docs/ver4/implementation_plan_v4.md | 10 +++++----- docs/ver4/requirements_v4.md | 4 ++-- docs/ver4/schema_v4.md | 15 +-------------- docs/ver4/scope_boundary_v4.md | 16 +++++----------- 7 files changed, 24 insertions(+), 43 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..318e3d0 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "chat.sessionSync.enabled": true +} \ No newline at end of file diff --git a/docs/ver4/architecture_v4.md b/docs/ver4/architecture_v4.md index 3d05367..0b6c0f4 100644 --- a/docs/ver4/architecture_v4.md +++ b/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. diff --git a/docs/ver4/error_handling_v4.md b/docs/ver4/error_handling_v4.md index 9fce8b7..288a715 100644 --- a/docs/ver4/error_handling_v4.md +++ b/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.", - "suggestion": "Remove recipient before assigning author for this person on this document.", + "message": "Relationship write conflicts with existing links.", + "suggestion": "Adjust the requested relationship links and retry.", "details": { "document_id": "...", "person_id": "...", - "attempted_role": "author", - "conflicting_role": "recipient", - "policy_rule": "author+recipient exclusive" + "attempted_role": "recipient", + "operation": "add_link", + "conflict_reason": "duplicate document-person-role link" }, "timestamp": "2026-08-10T15:00:00Z" } diff --git a/docs/ver4/implementation_plan_v4.md b/docs/ver4/implementation_plan_v4.md index eb75af6..92a74f8 100644 --- a/docs/ver4/implementation_plan_v4.md +++ b/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. diff --git a/docs/ver4/requirements_v4.md b/docs/ver4/requirements_v4.md index 0607944..eb2aa09 100644 --- a/docs/ver4/requirements_v4.md +++ b/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. diff --git a/docs/ver4/schema_v4.md b/docs/ver4/schema_v4.md index 3beac83..359f9e0 100644 --- a/docs/ver4/schema_v4.md +++ b/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)`. -- Initial exclusivity seed blocks `author` and `recipient` for the same person-document pair. +- Relationship writes must be deterministic and use explicit add/remove link intent. ### 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)` diff --git a/docs/ver4/scope_boundary_v4.md b/docs/ver4/scope_boundary_v4.md index d4d6944..1c4bb55 100644 --- a/docs/ver4/scope_boundary_v4.md +++ b/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 - -- `author` and `recipient` are mutually exclusive for the same `(document, person)` pair. -- `mentioned` remains non-exclusive. - -### C. API Compatibility Strategy +### B. 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.