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

Updated v4.3 scope

Browse Source
This commit is contained in:
Jim Lancaster
2026-08-14 16:08:07 -05:00
parent c9f5dca064
commit 178347e086
6 changed files with 35 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ver4.3/implementation_plan_v4_3.md
+10 -43
View File
@@ -2,12 +2,11 @@
## Goal
Prepare a safe implementation path for Source page reordering and constrained application settings. This plan remains provisional until the V4.3 scope-freeze decisions are resolved.
Prepare a safe implementation path for constrained application settings. This plan remains provisional until the V4.3 scope-freeze decisions are resolved.
## Planning Constraints
- V4, V4.1, and V4.2 remain the behavioral baseline.
- Reordering must be atomic and service-owned.
- Settings must use explicit domain operations rather than direct database, environment-file, or arbitrary filesystem access from UI pages.
- Prompt changes must preserve historical Job provenance and use a defined safe-write policy.
@@ -15,20 +14,16 @@ Prepare a safe implementation path for Source page reordering and constrained ap
| Area | Expected impact |
| --- | --- |
| Sources service | Add validated, transactional set-based page reordering. |
| Documents/Sources UI | Add a reorder entry point and interaction for one Document. |
| Documents service | Expand controlled Document Type maintenance operations. |
| People service | Expand controlled Person Role maintenance operations. |
| Prompt adapter/service | Add constrained listing, reading, validation, and safe writing of prompt artifacts. |
| UI composition/navigation | Register Settings routes and navigation without moving persistence into UI code. |
| Tests | Add transaction, conflict, registry lifecycle, prompt safety, and UI workflow coverage. |
| Tests | Add registry lifecycle, prompt safety, and UI workflow coverage. |
## Proposed Implementation Phases
### 1. Resolve Scope-Freeze Decisions
- Select and document the reorder interaction.
- Define whether active Jobs block reorder.
- Define prompt atomic-write, backup, and recovery policy.
- Decide whether prompt creation/deletion is excluded.
- Finalize registry ordering requirements.
@@ -36,33 +31,12 @@ Prepare a safe implementation path for Source page reordering and constrained ap
### 2. Define Service Contracts
- Define a Source reorder command containing `document_id`, the complete ordered Source ID list, and a concurrency token or equivalent stale-write guard if supported by the current model.
- Define Document Type maintenance commands for create, relabel, sort, activate, and deactivate.
- Define Person Role maintenance commands for create, relabel, activate, and deactivate.
- Define a Prompt Store interface for constrained list/read/write behavior.
- Map validation, conflict, not-found, dependency, and filesystem failures to existing `AppError` categories.
### 3. Implement Transactional Source Reordering
- Load all Sources for the target Document in the same transaction.
- Reject missing, extra, duplicate, or foreign Source IDs.
- Reject stale writes using the selected concurrency policy.
- Apply a collision-safe renumbering strategy suitable for both SQLite and PostgreSQL.
- Finish with contiguous `page_number` values beginning at 1.
- Roll back the entire operation on any failure.
- Add service tests for valid reorder, no-op, reverse order, invalid membership, duplicates, stale submissions, rollback, and backend-compatible SQL behavior.
### 4. Implement the Reorder UI
- Add a Reorder Pages action from a Document-scoped Source view or Document Detail.
- Render Source labels/previews sufficient to identify each page.
- Capture the complete intended order.
- Require explicit Save and provide Cancel without mutation.
- Surface validation and conflict errors through the shared error presenter.
- Return to a Document-scoped ordered view after success.
- Verify keyboard-accessible controls for any drag-and-drop interaction.
### 5. Expand Registry Maintenance Services
### 3. Expand Registry Maintenance Services
- Reuse existing Document and People service ownership.
- Add explicit write methods rather than passing UI-mutated ORM objects directly where practical.
@@ -72,7 +46,7 @@ Prepare a safe implementation path for Source page reordering and constrained ap
- Preserve inactive entries for historical reads.
- Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, and referenced records.
### 6. Add Constrained Prompt Storage
### 4. Add Constrained Prompt Storage
- Place filesystem access behind a dedicated Prompt Store/service boundary.
- Resolve all filenames directly beneath the configured prompt root and reject traversal.
@@ -82,7 +56,7 @@ Prepare a safe implementation path for Source page reordering and constrained ap
- Do not modify any Job row when prompt defaults change.
- Add unit tests for valid reads/writes, traversal, invalid names, empty content, filesystem failures, and unchanged Job provenance.
### 7. Build the Settings UI
### 5. Build the Settings UI
- Register a Settings landing page and navigation entry.
- Add separate pages or panels for Document Types, Person Roles, and Prompts.
@@ -91,19 +65,15 @@ Prepare a safe implementation path for Source page reordering and constrained ap
- Explain stable codes, inactive historical entries, and future-only prompt effects in the UI.
- Do not render raw environment values or secrets.
### 8. Verification and Rollout
### 6. Verification and Rollout
- Run focused service tests before UI integration tests.
- Verify reorder behavior against Documents with one and many Sources.
- Verify ordered transcription rendering and V4.1 previous/next navigation after reorder.
- Verify inactive registry behavior in both historical display and create/edit selectors.
- Verify prompt changes are picked up by newly created Jobs while historical Jobs retain frozen content/hash.
- Run the relevant regression suite.
## Migration and Compatibility Notes
- No new table is expected solely for reordering; `Source.page_number` remains authoritative.
- A uniqueness constraint on `(document_id, page_number)` should be evaluated before scope freeze. If added, migration and collision-safe update behavior must be designed for both supported databases.
- Existing registry records remain valid.
- Prompt editing changes mutable application files, not database provenance already captured on Jobs.
- V4.3 must not require users to recreate existing Sources, Documents, People, roles, or types.
@@ -111,17 +81,14 @@ Prepare a safe implementation path for Source page reordering and constrained ap
## Proposed Delivery Order
1. Freeze the remaining decisions.
2. Implement and verify Source reorder service semantics.
3. Build the reorder UI.
4. Implement registry maintenance service operations.
5. Implement the Prompt Store and safety policy.
6. Build Settings pages.
7. Run integration and regression verification.
2. Implement registry maintenance service operations.
3. Implement the Prompt Store and safety policy.
4. Build Settings pages.
5. Run integration and regression verification.
## Draft Done Criteria
- All V4.3 acceptance criteria are testable and satisfied.
- Reordering is atomic, conflict-aware, contiguous, and cross-database compatible.
- Settings mutations cross explicit service or adapter boundaries.
- Registry codes cannot be accidentally changed.
- Prompt writes cannot escape the configured directory or rewrite historical provenance.
docs/ver4.3/scope_boundary_v4_3.md
+21 -41
View File
@@ -1,32 +1,21 @@
# Draft V4.3 Scope Boundary
This document defines the proposed boundary for the page-reordering and constrained-settings revision that follows the V4.2 evidence-and-provenance work. It is intentionally a draft until the earlier revisions have been used and the remaining workflows have been validated.
This document defines the proposed boundary for the constrained-settings revision that follows the V4.2 evidence-and-provenance work. It is intentionally a draft until the earlier revisions have been used and the remaining workflows have been validated.
## Purpose
- Allow correction of Source page order after import.
- Provide a constrained Settings area for safe maintenance of selected application-managed configuration.
- Avoid exposing secrets, restart-sensitive settings, or unrestricted filesystem editing through the UI.
## Proposed In Scope
### 1. Source Page Reordering
- Allow Sources within one Document to be reordered after import.
- Present the current order using page number and a recognizable source label or preview.
- Persist the complete intended order atomically.
- Renumber the affected Document's Sources to a contiguous sequence beginning at 1.
- Keep all Sources attached to their existing Document.
- Ensure transcription rendering and previous/next navigation use the updated order.
- Detect stale or invalid reorder submissions and fail without partial mutation.
### 2. Settings Navigation
### 1. Settings Navigation
- Add a Settings entry to application navigation.
- Provide separate, clearly described settings areas rather than a raw configuration editor.
- Restrict V4.3 settings to application-managed values that can be validated and safely changed at runtime.
### 3. Document Type Maintenance
### 2. Document Type Maintenance
- List active and inactive Document Types.
- Add new types with a stable unique code and user-facing label.
@@ -35,7 +24,7 @@ This document defines the proposed boundary for the page-reordering and constrai
- Do not allow changing a stable code after creation.
- Do not delete types that are referenced by Documents.
### 4. Person Role Maintenance
### 3. Person Role Maintenance
- List active and inactive Person Roles.
- Add new roles with a stable unique code and user-facing label.
@@ -44,7 +33,7 @@ This document defines the proposed boundary for the page-reordering and constrai
- Do not allow changing a stable code after creation.
- Do not delete roles that are referenced by document-person links.
### 5. Prompt Maintenance
### 4. Prompt Maintenance
- List prompt markdown files from the configured prompt directory.
- View a prompt with a concise explanation of its purpose and use.
@@ -62,7 +51,8 @@ This document defines the proposed boundary for the page-reordering and constrai
- Arbitrary file browsing or arbitrary prompt paths.
- Runtime theme/CSS editing.
- Installing themes or plugins.
- Source movement between Documents as part of reordering.
- Source page renumbering or reordering.
- Source movement between Documents.
- Automatic ordering based on filenames, OCR, or image content.
- FamilySearch API synchronization.
- A generic external-reference registry.
@@ -70,24 +60,18 @@ This document defines the proposed boundary for the page-reordering and constrai
## Proposed Design Decisions
### A. Reordering Is Set-Based
- The client submits the full ordered list of Source IDs for one Document.
- The service validates membership, completeness, duplicates, and authorization/context before writing.
- All page-number updates occur in one transaction.
### B. Registry Codes Are Immutable
### A. Registry Codes Are Immutable
- Document Type and Person Role codes are stable identifiers.
- Labels and active state remain mutable.
- Historical references remain valid when a registry entry is inactive.
### C. No Raw Environment Editor
### B. No Raw Environment Editor
- `.env` may contain secrets and values that are not safely reloadable.
- V4.3 exposes only purpose-built forms backed by explicit validation and service methods.
### D. Prompt Editing Is Constrained
### C. Prompt Editing Is Constrained
- Prompt maintenance is limited to direct children of the configured prompt directory.
- Existing Job provenance is never rewritten when a prompt file changes.
@@ -95,23 +79,19 @@ This document defines the proposed boundary for the page-reordering and constrai
## Decisions Required Before Scope Freeze
1. Choose the reorder interaction: move-up/down controls, drag-and-drop, or both.
2. Decide whether reordering is allowed while the Document has a queued or processing Job.
3. Define prompt backup, atomic-write, and recovery behavior.
4. Decide whether prompt creation and deletion are needed or whether V4.3 edits existing prompts only.
5. Confirm whether registry sort-order maintenance is needed for Person Roles as well as Document Types.
6. Confirm that settings changes remain local to the current installation and do not require an API surface.
1. Define prompt backup, atomic-write, and recovery behavior.
2. Decide whether prompt creation and deletion are needed or whether V4.3 edits existing prompts only.
3. Confirm whether registry sort-order maintenance is needed for Person Roles as well as Document Types.
4. Confirm that settings changes remain local to the current installation and do not require an API surface.
## Draft Acceptance Criteria
1. Reordering a Document's Sources produces contiguous page numbers and updates every ordered view consistently.
2. Invalid, incomplete, duplicate, cross-Document, or stale reorder requests make no changes.
3. Document Type and Person Role maintenance preserves stable codes and historical references.
4. Inactive registry entries remain visible on historical records but are excluded from default create selectors.
5. Prompt edits are restricted to valid markdown files in the configured prompt directory.
6. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.
7. No Settings page exposes secrets or unrestricted filesystem access.
8. Focused service and UI tests pass without regressing V4.1 or V4.2 workflows.
1. Document Type and Person Role maintenance preserves stable codes and historical references.
2. Inactive registry entries remain visible on historical records but are excluded from default create selectors.
3. Prompt edits are restricted to valid markdown files in the configured prompt directory.
4. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.
5. No Settings page exposes secrets or unrestricted filesystem access.
6. Focused service and UI tests pass without regressing V4.1 or V4.2 workflows.
## Scope Freeze Gate
@@ -119,7 +99,7 @@ V4.3 implementation should not begin until:
- V4.1 has been used sufficiently to validate priorities.
- V4.2 evidence and provenance work has been completed and validated.
- The six open decisions above are resolved.
- The four open decisions above are resolved.
- The prompt-write safety policy is documented.
- The implementation plan is revised from draft to committed delivery plan.