# Implementation Plan (Version 4.3)

## Goal

Deliver constrained, installation-local application settings while preserving the completed V4.2 behavioral baseline and historical provenance.

## Planning Constraints

- V4, V4.1, and V4.2 remain the behavioral baseline.
- 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.
- Source Page Reordering is excluded.
- Database, integration, and UI tests must use confirmed isolated test data and must never modify `data/transcription.db`.
- Potentially destructive tests must run only through `tools/run_destructive_tests.py`.

## Expected Project Impact

| Area | Expected impact |
| --- | --- |
| Documents service | Expand controlled Document Type maintenance operations. |
| People service | Expand controlled Person Role maintenance operations. |
| Prompt adapter/service | Add constrained listing, reading, validation, atomic writing, backup, and explicit recovery of existing prompt artifacts. |
| UI composition/navigation | Register Settings routes and navigation without moving persistence into UI code. |
| Tests | Add isolated registry lifecycle, prompt safety, and UI workflow coverage. |

## Implementation Phases

### 1. Define Service Contracts

- Define Document Type maintenance commands for create, relabel, sort, activate, deactivate, and delete-if-unreferenced.
- Define Person Role maintenance commands for create, relabel, activate, deactivate, and delete-if-unreferenced.
- Define a Prompt Store interface for constrained list, read, write, backup-status, and explicit recovery behavior.
- Map validation, conflict, not-found, dependency, and filesystem failures to existing `AppError` categories.

### 2. 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.
- Permit deletion only after a service-owned reference check proves the entry is unreferenced.
- Reject deletion of referenced entries deterministically without partial mutation.
- Permit label changes whether or not an entry is referenced.
- Preserve inactive entries for historical reads.
- Maintain existing Document Type sort order.
- Order Person Roles deterministically by label and then code without adding a schema field.
- Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, ordering, allowed deletion, and blocked referenced deletion.

### 3. 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 existing files with the agreed Markdown extension and reject empty content.
- Exclude prompt creation and deletion.
- Write new content to a sibling temporary file, flush and sync it, preserve the active file as the sole previous-version backup, and atomically replace the active file.
- Expose explicit backup recovery through the same filename validation and safe-write path; never perform automatic rollback.
- Clean up temporary files after failed writes while preserving the active prompt and any valid backup.
- 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, nonexistent-file creation attempts, empty content, atomic replacement failures, single-backup rotation, explicit recovery, filesystem failures, and unchanged Job provenance.

### 4. 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.
- Present deletion only for unreferenced registry entries and preserve clear conflict feedback if references appear before submission.
- Present prompt backup availability and recovery as an explicit operator action.
- Do not render raw environment values or secrets.
- Add no settings API routes.

### 5. Verification and Rollout

- Confirm every database, integration, and UI test is configured for an isolated test database before execution.
- Never run those tests against live data and never modify or replace `data/transcription.db`.
- Invoke potentially destructive tests only through `tools/run_destructive_tests.py`.
- Run focused service tests before UI integration tests.
- Verify inactive registry behavior in both historical display and create/edit selectors.
- Verify referenced entries can be relabeled or deactivated but not deleted.
- Verify unreferenced entries can be deleted.
- 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

- 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.
- Person Role ordering requires no schema migration.
- Registry deletion introduces no cascade behavior; references always block deletion.

## Delivery Order

1. Implement registry maintenance service operations.
2. Implement the Prompt Store and safety policy.
3. Build Settings pages.
4. Run isolated integration and regression verification.

## Done Criteria

- All V4.3 acceptance criteria are testable and satisfied.
- Settings mutations cross explicit service or adapter boundaries.
- Registry codes cannot be accidentally changed.
- Referenced registry entries can be relabeled or deactivated but cannot be deleted.
- Unreferenced registry entries can be deleted without cascade behavior.
- Prompt writes cannot escape the configured directory or rewrite historical provenance.
- Prompt writes are atomic, retain one backup, and support explicit recovery.
- No secret or raw environment editor exists.
- No settings API surface exists.
- V4.1 and V4.2 workflows remain intact.
- Verification does not touch live data or `data/transcription.db`.

## Related Local References

- [V4.3 Scope Boundary](scope_boundary_v4_3.md)
- [V4.2 Implementation Plan](../ver4.2/implementation_plan_v4_2.md)
- [V4.1 Implementation Plan](../ver4.1/implementation_plan_v4_1.md)
- [V4 Implementation Plan](../ver4/implementation_plan_v4.md)
- [V4 Error Handling Policy](../ver4/error_handling_v4.md)