From 178347e086960922f6e335ac1a14c1929cf1f5c1 Mon Sep 17 00:00:00 2001 From: Jim Lancaster <40281233+zoltan57@users.noreply.github.com> Date: Fri, 14 Aug 2026 16:08:07 -0500 Subject: [PATCH] Updated v4.3 scope --- docs/ui/README.md | 2 +- docs/ui/pages/sources.md | 2 +- docs/ver4.2/scope_boundary_v4_2.md | 2 +- docs/ver4.3/implementation_plan_v4_3.md | 53 ++++----------------- docs/ver4.3/scope_boundary_v4_3.md | 62 +++++++++---------------- docs/ver4/index_v4.md | 2 +- 6 files changed, 35 insertions(+), 88 deletions(-) diff --git a/docs/ui/README.md b/docs/ui/README.md index 8f04634..e9ab165 100644 --- a/docs/ui/README.md +++ b/docs/ui/README.md @@ -58,4 +58,4 @@ Each page contract contains: ## Current Baseline These contracts describe the V4 baseline with completed V4.1 behavior and V4.2 evidence/provenance behavior. -Draft V4.3 Settings/page-reordering changes are not described as current behavior. +Draft V4.3 Settings changes are not described as current behavior. diff --git a/docs/ui/pages/sources.md b/docs/ui/pages/sources.md index 35c77de..1ef072d 100644 --- a/docs/ui/pages/sources.md +++ b/docs/ui/pages/sources.md @@ -86,4 +86,4 @@ The list accepts optional `document_id` and `job_id` query parameters. Document ## Planned Changes -- Source page reordering is deferred to the [draft V4.3 scope](../../ver4.3/scope_boundary_v4_3.md). +- Source page reordering is deferred beyond V4.3 and may be reconsidered if a demonstrated workflow need emerges. diff --git a/docs/ver4.2/scope_boundary_v4_2.md b/docs/ver4.2/scope_boundary_v4_2.md index ac8b348..eea6a5f 100644 --- a/docs/ver4.2/scope_boundary_v4_2.md +++ b/docs/ver4.2/scope_boundary_v4_2.md @@ -1,6 +1,6 @@ # V4.2 Scope Boundary -This document defines the boundary for the digital-evidence and AI-provenance revision that follows V4.1 and precedes the planned V4.3 page-reordering and settings work. V4 remains the architecture baseline; V4.2 makes the existing evidence claims precise and adds a provider-neutral foundation for future processing artifacts. +This document defines the boundary for the digital-evidence and AI-provenance revision that follows V4.1 and precedes the planned V4.3 settings work. V4 remains the architecture baseline; V4.2 makes the existing evidence claims precise and adds a provider-neutral foundation for future processing artifacts. ## Purpose diff --git a/docs/ver4.3/implementation_plan_v4_3.md b/docs/ver4.3/implementation_plan_v4_3.md index e415a65..47b7857 100644 --- a/docs/ver4.3/implementation_plan_v4_3.md +++ b/docs/ver4.3/implementation_plan_v4_3.md @@ -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. diff --git a/docs/ver4.3/scope_boundary_v4_3.md b/docs/ver4.3/scope_boundary_v4_3.md index bbc3523..c1b8830 100644 --- a/docs/ver4.3/scope_boundary_v4_3.md +++ b/docs/ver4.3/scope_boundary_v4_3.md @@ -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. diff --git a/docs/ver4/index_v4.md b/docs/ver4/index_v4.md index 075ed1e..cb7d9d9 100644 --- a/docs/ver4/index_v4.md +++ b/docs/ver4/index_v4.md @@ -26,4 +26,4 @@ Version 4 is the architecture baseline for the personal-scale application used t - [V4.1 Scope](../ver4.1/scope_boundary_v4_1.md) and [Implementation Plan](../ver4.1/implementation_plan_v4_1.md) - [V4.2 Evidence and Provenance Scope](../ver4.2/scope_boundary_v4_2.md) and [Implementation Plan](../ver4.2/implementation_plan_v4_2.md) -- [Draft V4.3 Page Reordering and Settings Scope](../ver4.3/scope_boundary_v4_3.md) and [Draft Implementation Plan](../ver4.3/implementation_plan_v4_3.md) +- [Draft V4.3 Settings Scope](../ver4.3/scope_boundary_v4_3.md) and [Draft Implementation Plan](../ver4.3/implementation_plan_v4_3.md)