V4.4 Complete

docs/ver4/architecture_v4.md

@@ -10,8 +10,8 @@ This document describes the production architecture of the document transcriptio
 - Execute page transcription concurrently with bounded `asyncio` workers.
 - Maintain relational portability across SQLite and PostgreSQL.
 - Keep operator workflows cross-platform and Python-driven.
-- Support many-to-many document-person relationships with extensible roles.
-- Support registry-driven document type classification.
+- Support one role-bearing link per Person and Document through an extensible role registry.
+- Support registry-driven document classification with protected semantic built-ins.
 
 ## Core Capabilities
 
@@ -20,8 +20,8 @@ This document describes the production architecture of the document transcriptio
 - Preserve original source files with SHA-256 digests and byte sizes.
 - Freeze prompt text, prompt hash, model, and explicitly configured sampling parameters on each `Job`.
 - Preserve page-level machine output, normalized metadata, and an SDK-serialized OpenRouter response snapshot on `JobSource`.
-- Organize historical `Person` records through many-to-many Document relationships and extensible roles.
-- Classify Documents through a UUID-identified registry with unique labels.
+- Organize historical `Person` records through UUID-identified Document links and extensible roles.
+- Classify Documents through a UUID-identified registry with hidden semantic built-ins and unique labels.
 - Maintain human revision separately from machine-generated text.
 - Isolate page failures so multi-page jobs can complete with partial success.
 - Operate across supported platforms through Python-based application and maintenance tooling.
@@ -110,8 +110,8 @@ Responsibilities:
 - Jobs own job lifecycle state and transitions.
 - People own person records, relationship roles, document-person links, and portrait media.
 - Apply deterministic conflict handling for relationship-role writes.
-- Use set-based synchronization for many-to-many relationship updates.
-- Resolve and validate registry-backed document types by UUID.
+- Synchronize each Document's complete Person link set in the same transaction as Document fields.
+- Resolve and validate registry records by UUID; use hidden semantic keys only for application-owned built-in behavior.
 
 ### Source Media Policy
 
@@ -146,11 +146,11 @@ Responsibilities:
 
 ### 2. Document-Person Relationship Management
 
-1. User opens a document or person edit flow.
-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 uniqueness and deterministic write semantics before persistence commits.
+1. User opens Document Create or Edit.
+2. UI loads one Linked People table containing Person and Role.
+3. Add, Edit, and Delete operations change staged UI state only.
+4. Service validates the complete desired set and computes deterministic add, update, and remove deltas.
+5. Document fields and links commit once in one transaction; any failure leaves both unchanged.
 
 ### 3. Document Type Management
 
@@ -159,6 +159,14 @@ Responsibilities:
 3. Persistence stores the `document_type_id` reference.
 4. Inactive types remain valid for historical rows but are excluded from default selectors.
 
+### 4. Document Printing
+
+1. User opens Print from persisted Document Detail.
+2. Service builds a safe projection containing archival metadata, semantic Author links, ordered Sources, current text,
+   and oldest-to-newest Job metadata.
+3. The preview renders Facsimile or Text-only HTML without exposing local file paths.
+4. An explicit action opens the browser print dialog; browser Save as PDF remains available.
+
 ## V4 Domain Rules
 
 - `JobSource.raw_transcription` preserves page output for its Job execution.
@@ -169,23 +177,25 @@ Responsibilities:
 - Every V4.2 provider call appends a distinct `ExecutionAttempt`; retries never rewrite earlier attempts.
 - Exact response bytes identify the OpenRouter HTTP boundary and are not labeled as native upstream-provider JSON.
 - Generic `ProcessingArtifact` records use versioned schemas, digests, and one inline or external content location.
-- `DocumentPerson` links are unique for `(document_id, person_id, role_id)`.
-- Relationship mutations are deterministic and set-based.
-- `DocumentType.id` is canonical identity; its unique label may evolve.
+- `DocumentPerson` links are unique for `(document_id, person_id)` and require one `role_id`.
+- Relationship mutations are deterministic, set-based, and atomic with Document writes.
+- `DocumentType.id` and `PersonRole.id` are canonical relationship identities; unique labels may evolve.
+- Nullable immutable `semantic_key` values identify protected application-defined built-ins and are never public selectors.
+- Current printable text uses non-null `Source.revised_text`; otherwise it uses `Source.raw_transcription`.
 
 ## Data Model Summary
 
 - `Document` has one `DocumentType`, many `Source` pages, many `Job` runs, and many `Person` records through `DocumentPerson`.
 - `Source` belongs to one `Document` and may participate in many `JobSource` executions.
 - `Job` has many `JobSource` rows.
-- `PersonRole` defines available relationship roles.
+- `PersonRole` defines available relationship roles; `DocumentType` and `PersonRole` may carry hidden semantic identity.
 
 ## Test Strategy
 
 - Unit tests for models, validation, hashing, and registry resolution.
-- Service tests for CRUD, set-based sync, uniqueness conflicts, and deterministic relationship writes.
+- Service tests for registry protection, atomic link synchronization, uniqueness conflicts, and print projections.
 - 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.
+- UI integration tests for Linked People staging, registry selection, and safe print rendering.
 
 ## Related Local References