transcription/docs/ver4.2/implementation_plan_v4_2.md

Draft Implementation Plan (Version 4.2)

Goal

Prepare a safe implementation path for Source page reordering and constrained application settings. This plan remains provisional until the V4.2 scope-freeze decisions are resolved.

Planning Constraints

• V4 and V4.1 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.

Expected Project Impact

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.

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.
• Remove the Draft designation only after these decisions are reflected in scope and acceptance criteria.

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

• 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.
• Block deletion or omit deletion entirely; use activation state for lifecycle management.
• 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

• Place filesystem access behind a dedicated Prompt Store/service boundary.
• Resolve all filenames directly beneath the configured prompt root and reject traversal.
• Permit only the agreed markdown extension and reject empty content.
• Implement the approved safe-write strategy, including flush/replace behavior and backup/recovery if selected.
• Preserve file encoding and provide explicit failures for read-only or unavailable storage.
• 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

• Register a Settings landing page and navigation entry.
• 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.
• Do not render raw environment values or secrets.

8. 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.2 must not require users to recreate existing Sources, Documents, People, roles, or types.

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.

Draft Done Criteria

• All V4.2 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.
• No secret or raw environment editor exists.
• V4.1 workflows remain intact.

Related Local References

• Draft V4.2 Scope Boundary
• V4.1 Implementation Plan
• V4 Implementation Plan
• V4 Error Handling Policy