generated from john/python-template
V4 final docs
This commit is contained in:
Jim Lancaster
@@ -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.
|
||||
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+1
-14
@@ -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)`
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user