bbchops/transcription
1
0
Fork 0
generated from john/python-template
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

V4.4 Scope defined (part 2)

Browse Source
This commit is contained in:
Jim Lancaster
2026-08-15 14:04:58 -05:00
parent 936af9b1d3
commit 63373bf24d
2 changed files with 420 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ver4.4/scope_boundary_v4_4.md
+232
View File
@@ -0,0 +1,232 @@
# V4.4 Scope Boundary
This document defines the frozen boundary for the semantic-registry, linked-people, and document-printing revision that follows the completed V4.3 Settings work. V4 through V4.3 remain the architecture and behavioral baseline except where this document explicitly replaces a registry or document-person contract.
## Purpose
- Keep registry identifiers stable without exposing duplicate machine codes in Settings tables or selectors.
- Replace role-specific person selectors with one coherent Linked People editor.
- Provide an archival print view containing document metadata, source pages, current transcription text, and transcription-job metadata.
## In Scope
### 1. Semantic Registry Identity
- `DocumentType` and `PersonRole` use UUIDs as their canonical record and relationship identity.
- Both registries may carry a nullable, unique, immutable `semantic_key` used only for application-defined built-ins.
- Semantic keys are internal implementation details. Settings tables, selectors, and public API payloads do not display or accept them.
- Labels are trimmed, case-insensitively unique, editable, and used for all user-facing display.
- Active state remains editable. Inactive entries remain valid for historical records and are excluded from default assignment selectors.
- Built-in status is derived from the presence of a semantic key and is displayed as a read-only Yes/No value.
- Built-in entries cannot be deleted or converted to custom entries.
- Custom entries have no semantic key and may be deleted only when unreferenced.
- Users may create custom entries but cannot create, change, or assign semantic keys through the UI or API.
### 2. Built-In Document Types
- Seed these built-in semantic keys and initial labels:
| Semantic key | Initial label |
| --- | --- |
| `book` | Book |
| `letter` | Letter |
| `postcard` | Postcard |
| `photo` | Photo |
| `journal` | Journal |
| `form` | Form |
- The Document Types Settings table contains Select, Label, Documents, Active, and Built-in columns.
- Document Types are ordered alphabetically by normalized label.
- Add, Edit, and Delete actions operate on table selection.
- Add creates a custom type. Edit changes only label and active state.
- The Documents count is the number of Documents referencing the type.
- Document Type selectors display labels only and submit UUIDs.
### 3. Built-In Person Roles
- Seed these built-in semantic keys and initial labels:
| Semantic key | Initial label |
| --- | --- |
| `author` | Author |
| `recipient` | Recipient |
| `mentioned` | Mentioned |
- Application behavior that requires authorship resolves the built-in `author` semantic key rather than matching a mutable label.
- The Person Roles Settings table contains Select, Label, Links, Active, and Built-in columns.
- Person Roles are ordered alphabetically by normalized label.
- Add, Edit, and Delete actions operate on table selection.
- Add creates a custom role. Edit changes only label and active state.
- The Links count is the number of document-person relationships referencing the role.
- Person Role selectors display labels only and submit UUIDs.
### 4. Linked People Editor
- Replace the separate role-specific person selectors on both Create Document and Edit Document with one Linked People table.
- The table contains Select, Person, and Role columns.
- Add opens an inline editor beneath the table with Person and Person Role selectors.
- Edit requires exactly one selected row and loads it into the inline editor.
- Save stages the inline addition or edit in the table.
- Cancel exits the inline editor without changing the staged link set.
- Delete stages removal of one or more selected rows.
- A Person may be linked to a Document only once, regardless of role.
- Every link has exactly one Person Role.
- Already-linked People are unavailable when adding another row.
- Existing links using inactive roles remain visible and unchanged unless explicitly edited.
- Only active roles are available for new links or role changes.
- Create Document preserves the existing `person_id` preselection workflow by staging that Person with the active built-in `author` role. An invalid Person or unavailable Author role produces a warning rather than an invalid link.
- Create Document preserves the existing `return_to=jobs_new` success path.
- Linked People changes remain staged until the main Create Document or Save Changes action.
- The Document and its complete staged link set are persisted atomically. A conflict or validation failure leaves both unchanged.
- The API and service contracts identify roles by `role_id`; role-code selectors and compatibility role strings are removed.
- Persistence enforces uniqueness on `(document_id, person_id)`.
### 5. Document Print View
- Add a Print action to Document Detail.
- The action opens a dedicated print-preview page for the persisted Document.
- The preview offers two formats:
- **Facsimile:** source image on the left and current transcription on the right. Original transcription line breaks are preserved, and each Source begins on a new printed sheet.
- **Text only:** no source images. Single line breaks inside a paragraph are reflowed as spaces, while blank-line paragraph boundaries remain.
- Both formats use browser printing through a dedicated print stylesheet and the browser print dialog.
- Server-generated PDF files are not part of V4.4; users may select the browser's Save as PDF destination.
- Sources are ordered by existing `page_number`, with UUID as a deterministic tie-breaker.
- The current transcription for each Source is the non-null `revised_text`, including an intentionally empty revision, otherwise the latest successful machine-output projection in `raw_transcription`.
- Empty or whitespace-only current text displays the explicit unavailable message rather than falling back past an intentional revision.
- A Source with no current transcription displays an explicit unavailable message.
- Transcription and Notes content is treated as text and escaped; model output is not executed as arbitrary HTML.
- Facsimile images use an application-controlled Source media route. Generated markup does not expose direct machine-local file paths.
### 6. Printed Content Contract
The print view contains, in this order:
1. Document title using the Document name.
2. Archival Metadata table:
- Author, containing People linked through the built-in `author` role.
- Date.
- Location Created.
- Archival Identifier.
3. Notes.
4. Document section containing one numbered section per Source.
5. Transcription Job Metadata table.
Empty metadata values remain visible as `Not set`. Empty Notes display `No notes recorded`.
The job metadata table:
- Lists field names in the first column and adds one column for every Job associated with the Document.
- Orders Job columns from oldest to newest by creation date, then UUID.
- Includes every Job status: `queued`, `processing`, `transcribed`, `completed`, `partial_success`, and `failed`.
- Contains these rows in order:
- Job ID.
- Date, using the Job creation/submission timestamp with timezone.
- Provider.
- Model.
- Prompt, using the frozen prompt filename/name rather than full prompt content.
- Retry Count.
- Status as the final row.
- Displays `Not set` for unavailable optional metadata.
### 7. Clean Development Schema
- V4.4 does not require preservation or migration of rows in the operator-configured development database.
- Implementation may recreate the configured development database, including `data/transcription.db` when it is the explicitly selected target, only through a separate operator-confirmed action that identifies the resolved path. Startup and test execution never delete it automatically.
- Fresh schema creation seeds the agreed built-in Document Types and Person Roles idempotently.
- No test may use, modify, replace, or restore `data/transcription.db`.
- Database, integration, and UI tests use confirmed isolated databases.
- Potentially destructive tests run only through `tools/run_destructive_tests.py`.
## Out of Scope
- User creation, editing, deletion, or direct display of semantic keys.
- Treating custom registry entries as built-ins.
- Additional built-in Document Types or Person Roles beyond the frozen lists.
- Assigning more than one role to the same Person on the same Document.
- Preserving multiple historical links that violate the new one-person-per-document constraint.
- Source page renumbering or reordering.
- Printing unsaved Create/Edit Document state.
- Print actions on Job Detail or other pages.
- Batch printing multiple Documents.
- Server-side PDF generation or PDF file storage.
- Markdown, DOCX, or evidence-package export through the print feature.
- User-editable print templates, fonts, margins, headers, or footers.
- Full frozen prompt content, prompt hashes, transport evidence, API responses, or execution-attempt details in the print footer.
- Rendering transcription text as unrestricted Markdown or HTML.
- Pixel-identical pagination across browsers and printer drivers.
## Locked Design Decisions
### A. UUID Identifies the Row; Semantic Key Identifies Built-In Meaning
- UUIDs remain the only relationship and API identity.
- A hidden semantic key permits reliable built-in behavior after a label is renamed.
- Mutable labels are never used to infer built-in meaning.
### B. Built-Ins Are Protected but Mutable in Presentation
- Built-in labels and active state may change.
- Built-in semantic identity cannot change, and built-ins cannot be deleted.
- Custom entries remain reference-aware and deletable when unreferenced.
### C. Linked People Is a Single-Role Relationship
- One `(document_id, person_id)` row represents the complete relationship.
- Changing a role updates that row rather than adding another relationship.
- The main Document save owns one atomic Document-and-links transaction.
### D. Printing Uses the Current Human-Preferred Text
- Human-revised text takes precedence over the latest successful machine-output projection.
- Job metadata provides processing context but does not claim that a later human revision is raw output from a listed Job.
### E. Printing Is Browser-Native
- A print-specific HTML view and CSS support physical printing and browser Save as PDF.
- Source media is served through application-controlled routes, and all textual content is escaped.
### F. Source Order Is Read-Only in V4.4
- Print order follows existing page numbers.
- Source page reordering remains explicitly excluded.
## Acceptance Criteria
1. Registry selectors and Settings forms never display a machine code or semantic key.
2. Document Types and Person Roles use UUID relationship identity and case-insensitively unique labels.
3. The six Document Type and three Person Role built-ins are seeded with immutable internal semantic keys.
4. Built-ins may be relabeled or disabled but cannot be deleted.
5. Unreferenced custom entries may be deleted; referenced custom entries may only be relabeled or disabled.
6. Settings tables show the agreed columns, alphabetical label order, usage counts, and selection-based actions.
7. Create and Edit Document use one Linked People table with inline staged Add/Edit/Save/Cancel and multi-row Delete.
8. The same Person cannot be staged or persisted twice for one Document, even under different roles.
9. Document fields and Linked People changes commit atomically.
10. Historical inactive roles remain displayable, while only active roles are assignable.
11. Document Detail opens a print preview with Facsimile and Text-only formats.
12. Print pages use current revised text when available and deterministic Source ordering.
13. Printed archival metadata resolves authors through the hidden `author` semantic key after any label change.
14. The job table contains one oldest-to-newest column per Job and ends with the Status row.
15. Print output escapes stored text and does not disclose direct local source paths.
16. Source reordering, server PDF generation, and print-template editing are absent.
17. Database, integration, and UI verification uses isolated test data and never modifies `data/transcription.db`.
## Scope Freeze Gate
V4.4 is sufficiently frozen to begin implementation:
- Built-in registry identity, membership, lifecycle, display, and selector behavior are resolved.
- Linked People selection, editing, uniqueness, inactive-role, staging, and transaction behavior are resolved.
- Print entry point, formats, content order, transcription precedence, page order, job metadata, and output mechanism are resolved.
- Clean development-schema and destructive-test boundaries are resolved.
- Source page reordering remains excluded.
Any expansion of the built-in catalogs, relationship cardinality, print formats, export formats, or print customization requires an explicit V4.4 scope amendment or a later revision.
## Related Local References
- [V4.4 Implementation Plan](implementation_plan_v4_4.md)
- [V4.3 Scope Boundary](../ver4.3/scope_boundary_v4_3.md)
- [V4.3 Implementation Plan](../ver4.3/implementation_plan_v4_3.md)
- [V4 Architecture](../ver4/architecture_v4.md)
- [V4 Schema](../ver4/schema_v4.md)
- [V4 Requirements](../ver4/requirements_v4.md)