V4.3 revision to Document Types

docs/ver4.3/implementation_plan_v4_3.md

@@ -27,7 +27,7 @@ Deliver constrained, installation-local application settings while preserving th
 
 ### 1. Define Service Contracts
 
-- Define Document Type maintenance commands for create, relabel, sort, activate, deactivate, and delete-if-unreferenced.
+- Define Document Type maintenance commands for create, relabel, activate, deactivate, and delete-if-unreferenced.
 - Define Person Role maintenance commands for create, relabel, activate, deactivate, and delete-if-unreferenced.
 - Define a Prompt Store interface for constrained list, read, write, backup-status, and explicit recovery behavior.
 - Map validation, conflict, not-found, dependency, and filesystem failures to existing `AppError` categories.
@@ -36,13 +36,13 @@ Deliver constrained, installation-local application settings while preserving th
 
 - Reuse existing Document and People service ownership.
 - Add explicit write methods rather than passing UI-mutated ORM objects directly where practical.
-- Normalize and validate new stable codes.
-- Reject duplicate codes deterministically.
+- Normalize Document Type labels and reject case-insensitive duplicates deterministically.
+- Keep Person Role stable-code validation and duplicate rejection.
 - Permit deletion only after a service-owned reference check proves the entry is unreferenced.
 - Reject deletion of referenced entries deterministically without partial mutation.
 - Permit label changes whether or not an entry is referenced.
 - Preserve inactive entries for historical reads.
-- Maintain existing Document Type sort order.
+- Order Document Types alphabetically by normalized label.
 - Order Person Roles deterministically by label and then code without adding a schema field.
 - Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, ordering, allowed deletion, and blocked referenced deletion.
 
@@ -65,7 +65,7 @@ Deliver constrained, installation-local application settings while preserving th
 - Add separate pages or panels for Document Types, Person Roles, and Prompts.
 - Keep pages responsible for orchestration and notifications only.
 - Use service callbacks for all mutations.
-- Explain stable codes, inactive historical entries, and future-only prompt effects in the UI.
+- Explain inactive historical entries and future-only prompt effects in the UI.
 - Present deletion only for unreferenced registry entries and preserve clear conflict feedback if references appear before submission.
 - Present prompt backup availability and recovery as an explicit operator action.
 - Do not render raw environment values or secrets.
@@ -102,7 +102,7 @@ Deliver constrained, installation-local application settings while preserving th
 
 - All V4.3 acceptance criteria are testable and satisfied.
 - Settings mutations cross explicit service or adapter boundaries.
-- Registry codes cannot be accidentally changed.
+- Document Types use UUID-only identity and unique labels; Person Role codes cannot be accidentally changed.
 - Referenced registry entries can be relabeled or deactivated but cannot be deleted.
 - Unreferenced registry entries can be deleted without cascade behavior.
 - Prompt writes cannot escape the configured directory or rewrite historical provenance.

docs/ver4.3/scope_boundary_v4_3.md

@@ -18,12 +18,12 @@ This document defines the frozen boundary for the constrained-settings revision
 ### 2. Document Type Maintenance
 
 - List active and inactive Document Types.
-- Add new types with a stable unique code and user-facing label.
-- Edit mutable labels and sort order.
+- Add new types with a unique user-facing label.
+- Edit labels and active state.
 - Activate or deactivate types without invalidating historical Documents.
-- Do not allow changing a stable code after creation.
 - Allow deletion only when no Document references the type.
 - Allow label changes regardless of whether the type is referenced.
+- Display types alphabetically by label.
 
 ### 3. Person Role Maintenance
 
@@ -74,9 +74,10 @@ This document defines the frozen boundary for the constrained-settings revision
 
 ## Locked Design Decisions
 
-### A. Registry Codes Are Immutable
+### A. Registry Identity and Lifecycle
 
-- Document Type and Person Role codes are stable identifiers.
+- Document Types use UUID identity and case-insensitively unique labels; no separate code is exposed or stored.
+- Person Role codes remain stable identifiers.
 - Labels and active state remain mutable.
 - Historical references remain valid when a registry entry is inactive.
 - Labels may be updated for referenced and unreferenced entries.
@@ -104,7 +105,7 @@ This document defines the frozen boundary for the constrained-settings revision
 
 - Person Roles are ordered by label and then stable code.
 - V4.3 does not add a `sort_order` field to Person Roles.
-- Document Type sort-order maintenance remains in scope because `DocumentType.sort_order` is already part of the V4 schema.
+- Document Types use alphabetical label ordering and have no persisted sort order.
 
 ### F. Settings Are Installation-Local
 
@@ -122,11 +123,11 @@ This document defines the frozen boundary for the constrained-settings revision
 
 ## Acceptance Criteria
 
-1. Document Type and Person Role maintenance preserves stable codes and historical references.
+1. Document Type UUID identity and Person Role stable codes preserve historical references.
 2. Inactive registry entries remain visible on historical records but are excluded from default create selectors.
 3. Labels can be changed for referenced or unreferenced registry entries.
 4. An unreferenced Document Type or Person Role can be deleted, while deletion of a referenced entry fails without partial mutation.
-5. Document Type sort order is maintainable; Person Roles use deterministic label/code ordering without a schema addition.
+5. Document Types use alphabetical label ordering; Person Roles use deterministic label/code ordering.
 6. Prompt edits are restricted to existing Markdown files directly beneath the configured prompt directory.
 7. Prompt saves use atomic replacement, retain exactly one previous-version backup, and support explicit recovery.
 8. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.

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