V4.3 revision to Document Types

docs/ver4/architecture_v4.md

@@ -21,7 +21,7 @@ This document describes the production architecture of the document transcriptio
 - 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 registry with stable type codes.
+- Classify Documents through a UUID-identified registry with 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.
@@ -111,7 +111,7 @@ Responsibilities:
 - 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.
+- Resolve and validate registry-backed document types by UUID.
 
 ### Source Media Policy
 
@@ -155,7 +155,7 @@ Responsibilities:
 ### 3. Document Type Management
 
 1. User selects a registry-backed document type for a document.
-2. Service resolves the stable type code or id.
+2. Service resolves the Document Type UUID.
 3. Persistence stores the `document_type_id` reference.
 4. Inactive types remain valid for historical rows but are excluded from default selectors.
 
@@ -171,7 +171,7 @@ Responsibilities:
 - 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.code` is stable; `DocumentType.label` may evolve.
+- `DocumentType.id` is canonical identity; its unique label may evolve.
 
 ## Data Model Summary
 

docs/ver4/implementation_plan_v4.md

@@ -42,13 +42,13 @@ Implement the Version 4 project definition from the current repository state whi
 - Implement set-based synchronization for document-person updates.
 - Implement deterministic uniqueness and relationship-write conflict checks.
 - Remove suggestion-related service behavior.
-- Add document-type resolution and validation by stable code or id.
+- Add document-type resolution and validation by UUID.
 
 ### 4. Update API Contracts
 
 - Keep API evolution additive.
 - Add role-aware relationship retrieval and write behavior.
-- Add document-type catalog retrieval and code-based selection for document writes.
+- Add document-type catalog retrieval and UUID-based selection for document writes.
 - Remove suggestion-related API surfaces from the V4 target state.
 
 ### 5. Update UI Workflows

docs/ver4/requirements_v4.md

@@ -16,11 +16,11 @@ This document defines the baseline requirements for the document transcription s
 | 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 |
+| REQ-10 | Functional | Support a UUID-identified `DocumentType` taxonomy with unique user-facing labels and active/inactive lifecycle control. | test |
 | REQ-11 | Data Constraint | Store `Document` type as a controlled reference to `DocumentType`. | test |
 | REQ-12 | Interface | Render multi-page transcriptions sequentially by `page_number` with document, people, and document-type metadata. | demonstration |
 | REQ-13 | Interface | Document create/edit UI must support selecting multiple people per role and selecting an active document type from the registry. | demonstration |
-| REQ-14 | API Constraint | Expose additive, role-aware retrieval and write behavior for document-person links and code-based selection for document types. | test |
+| REQ-14 | API Constraint | Expose additive, role-aware retrieval and write behavior for document-person links and UUID-based selection for document types. | test |
 | REQ-15 | Data Constraint | Calculate and store cryptographic file hashes (SHA-256) and file sizes for uploaded source images. | test |
 | REQ-16 | Data Constraint | Preserve a portable relational model across supported backends using SQLModel, SQLAlchemy, SQLite, and PostgreSQL. | inspection |
 | REQ-17 | Reliability | Ensure delete and update flows for documents, people, and relationship links remain deterministic and safe. | test |
@@ -29,8 +29,8 @@ This document defines the baseline requirements for the document transcription s
 
 ## Clarifying Constraints
 
-1. `DocumentType.code` and `PersonRole.code` are stable machine identifiers.
-2. `DocumentType.label` and `PersonRole.label` may evolve without changing canonical identity.
+1. `DocumentType.id` is its sole identity; labels are unique ignoring case and surrounding whitespace.
+2. `PersonRole.code` is a stable machine identifier; `PersonRole.label` may evolve.
 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

@@ -8,10 +8,9 @@ This document defines the relational schema for the document transcription syste
 erDiagram
 DOCUMENT_TYPE {
 UUID id PK
-TEXT code
 TEXT label
+TEXT normalized_label
 BOOLEAN is_active
-INTEGER sort_order
 TIMESTAMPTZ created_at
 TIMESTAMPTZ updated_at
 }
@@ -207,13 +206,14 @@ EXECUTION_ATTEMPT ||--o{ PROCESSING_ARTIFACT : produces
 ### Document Type Governance
 
 - Every document type is defined by `DOCUMENT_TYPE`.
-- `DOCUMENT_TYPE.code` is a stable machine identifier.
-- `DOCUMENT_TYPE.label` is mutable display text.
+- `DOCUMENT_TYPE.id` is the sole machine identity.
+- `DOCUMENT_TYPE.label` is mutable display text and is unique after trimming and case normalization.
+- `DOCUMENT_TYPE.normalized_label` stores the normalized uniqueness key.
 - Inactive types remain valid for historical rows but should be excluded from default selection UIs.
 
 ## Constraint Summary
 
-- `DOCUMENT_TYPE.code` is unique.
+- `DOCUMENT_TYPE.normalized_label` is unique.
 - `PERSON_ROLE.code` is unique.
 - `DOCUMENT_PERSON(document_id, person_id, role_id)` is unique.
 

docs/ver4/scope_boundary_v4.md

@@ -16,7 +16,7 @@ Define what this revision includes, what it intentionally excludes, and what mig
 
 ### 2. Document Type Governance
 
-- Registry-driven `DocumentType` model with stable codes and controlled selection.
+- 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