transcription/docs/ver4.3/scope_boundary_v4_3.md

V4.3 Scope Boundary

This document defines the frozen boundary for the constrained-settings revision that follows the completed V4.2 evidence-and-provenance work. V4, V4.1, and V4.2 remain the behavioral and architecture baseline.

Purpose

• 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.

In Scope

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.

2. Document Type Maintenance

• List active and inactive Document Types.
• Add new types with a stable unique code and user-facing label.
• Edit mutable labels and sort order.
• Activate or deactivate types without invalidating historical Documents.
• Do not allow changing a stable code after creation.
• Allow deletion only when no Document references the type.
• Allow label changes regardless of whether the type is referenced.

3. Person Role Maintenance

• List active and inactive Person Roles.
• Add new roles with a stable unique code and user-facing label.
• Edit mutable labels.
• Activate or deactivate roles without invalidating historical links.
• Do not allow changing a stable code after creation.
• Order roles deterministically by label and then code; do not add persisted role sort order.
• Allow deletion only when no document-person link references the role.
• Allow label changes regardless of whether the role is referenced.

4. Prompt Maintenance

• List prompt markdown files from the configured prompt directory.
• View a prompt with a concise explanation of its purpose and use.
• Edit an existing prompt as plain markdown text.
• Validate the filename boundary and reject empty prompt content.
• Save changes explicitly and report filesystem failures.
• Preserve submission-time prompt text and hash already frozen on existing Jobs.
• Edit existing prompt files only; prompt creation and deletion are excluded.
• Save through a sibling temporary file, flush and sync file content, retain one previous-version backup, and atomically replace the active file.
• Provide an explicit recovery operation that restores the retained backup through the same safe-write path; do not silently roll back a failed or unwanted edit.

5. Deployment Boundary

• Settings changes apply only to the current installation.
• V4.3 adds no settings API endpoints.
• Service contracts must remain independent of the UI so a separately authorized API can be considered later.

Out of Scope

• Viewing or editing raw .env files.
• Displaying or changing provider API keys and other secrets.
• Editing host, port, database connection, upload paths, or other restart-sensitive runtime settings.
• Arbitrary file browsing or arbitrary prompt paths.
• Runtime theme/CSS editing.
• Installing themes or plugins.
• Source page renumbering or reordering.
• Source movement between Documents.
• Automatic ordering based on filenames, OCR, or image content.
• Prompt creation, deletion, and multi-version history.
• Persisted sort-order maintenance for Person Roles.
• Settings read or write API endpoints.
• FamilySearch API synchronization.
• A generic external-reference registry.
• Ancestry references and Google Maps links.

Locked Design Decisions

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.
• Labels may be updated for referenced and unreferenced entries.
• Unreferenced entries may be deleted; referenced entries may only be deactivated.

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.

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.
• The UI must distinguish editing the default for future submissions from inspecting historical Job prompts.

D. Prompt Writes Are Atomic and Recoverable

• Writes use a sibling temporary file and atomic replacement so readers observe either the old or new complete prompt.
• The immediately previous prompt version is retained as the sole backup.
• Recovery is an explicit operator action and uses the same validated safe-write path.
• Prompt creation and deletion are not available in V4.3.

E. Person Role Ordering Is Deterministic, Not Persisted

• Person Roles are ordered by label and then stable code.
• V4.3 does not add a sort_order field to Person Roles.
• Document Type sort-order maintenance remains in scope because DocumentType.sort_order is already part of the V4 schema.

F. Settings Are Installation-Local

• V4.3 provides Settings through the local application UI and domain services only.
• No settings API surface is introduced.

Data and Compatibility Policy

• V4.3 does not rewrite existing Documents, document-person links, Jobs, Sources, execution evidence, or prompt provenance.
• Deactivation preserves referenced registry entries for historical display while excluding them from default create selectors.
• Deletion checks are performed at the service boundary and must fail deterministically when references exist.
• Prompt files are constrained to existing Markdown files that are direct children of the configured prompt root.
• Settings UI code performs no direct database, environment-file, or arbitrary filesystem mutations.
• Source page numbering and ordering behavior is unchanged.

Acceptance Criteria

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. Labels can be changed for referenced or unreferenced registry entries.
4. An unreferenced Document Type or Person Role can be deleted, while deletion of a referenced entry fails without partial mutation.
5. Document Type sort order is maintainable; Person Roles use deterministic label/code ordering without a schema addition.
6. Prompt edits are restricted to existing Markdown files directly beneath the configured prompt directory.
7. Prompt saves use atomic replacement, retain exactly one previous-version backup, and support explicit recovery.
8. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.
9. No Settings page exposes secrets, unrestricted filesystem access, or a settings API.
10. Focused service and UI tests pass without regressing V4.1 or V4.2 workflows.
11. Database, integration, and UI tests use confirmed isolated test data and never modify data/transcription.db; potentially destructive tests run only through tools/run_destructive_tests.py.

Scope Freeze Gate

V4.3 is sufficiently frozen to begin implementation:

• V4.2 is the completed behavioral baseline.
• Registry lifecycle and ordering behavior are resolved.
• Prompt lifecycle, atomic-write, backup, and recovery behavior are resolved.
• The installation-local deployment boundary is resolved.
• The implementation plan is a committed delivery plan.

Related Local References

• V4.3 Implementation Plan
• V4.2 Scope Boundary
• V4.1 Scope Boundary
• V4 Architecture
• V4 Schema