Phase 9/9: Activate immutable_job_id_v1 and qualify the end-to-end test candidate

[borg-codex-bot]

Parent: #447

Depends on: Phases 1/9 through 8/9

Delivery branch: codex/issue-447-immutable-job-ids

Delivery model: This is the final phase on the shared #447 integration branch and the single draft pull request against main. No phase is merged or released independently.

Objective

Activate migration immutable_job_id_v1 only after every active reader and writer uses the new identity contract, then qualify the first installable test-channel candidate through the complete migration and application lifecycle.

Activation gate

Before enabling guarded startup detection and user-authorized execution, verify that:

• every dependency in the Introduce immutable job IDs across all job-dependent data and workflows #447 inventory is completed or explicitly classified as a bounded legacy read boundary;
• all active writes use job_id;
• all fixture migrations pass with complete snapshots and audit logs;
• ambiguous or invalid active states block before changes;
• the application remains blocked after a migration or verification failure;
• restart and retry reuse the same persisted UUID mapping;
• no later migration executes after the first failure;
• fresh installations are not_applicable and create ID-native jobs directly.

Do not activate a partial migration merely to produce something installable.

Approved user-initiated migration assistant

Maintainer-approved on 2026-09-05. This is a required implementation and acceptance contract for this final phase, not activation of the current inactive #472 foundation.

1. Migration required: On startup, perform read-only detection and keep normal plugin functions and new scheduled/manual jobs blocked when migration is required or uncertain. Installation, restart and opening the assistant are not migration consent. Keep authentication, migration status, safe diagnostics and protected recovery access available. Unraid itself, including array/pool controls, is not blocked.
2. Prepare migration: The administrator explicitly starts preparation. Wait for running jobs and detached workers to finish safely; never kill them to force progress. Validate the actual mounted snapshot location, permissions, supported filesystem operations and space before capturing the quiescent inventory and persisting the complete UUID plan. Unavailable storage blocks without writing to an unmounted path.
3. Create and verify backup: Create the exact pre-change snapshot and automatically verify completeness, sizes and checksums. Show storage path, creation time, size and verification result. Users must not have to inspect internal JSON records to establish technical integrity.
4. Mandatory pause - check and save the backup: Offer a protected authenticated download/export. Require explicit acknowledgement that an independent copy has been saved and checked, with a warning that it may contain credentials or other confidential information. Example: "I have saved and checked a separate copy of the backup. I understand that it may contain confidential data." This cannot prove that an external copy exists and never replaces automatic integrity checks. Snapshot completion, download or acknowledgement must not automatically start conversion.
5. Run migration now: A second explicit administrator action authorizes installation-data conversion, bound to the exact plan ID and snapshot digest. Immediately recheck storage, snapshot, source/cron fingerprints and exclusion of all writers. Changed prerequisites invalidate old approval. Display conversion and final-verification progress. Only successful complete verification and the startup gate allow normal operation and scheduled jobs again.

Show the current step, completed and remaining steps, waiting reasons and actionable masked errors. These are runtime migration steps, not the nine development phases.

Closing the browser or restarting the plugin preserves maintenance, the original plan, UUIDs, snapshot and journal. It is not automatic apply consent or permission to resume normal operation. Reconnect must show the durable stage and offer only validated explicit continuation of interrupted work. If the previously authorized backend operation is still running, reconnect only observes its progress and must not start a duplicate operation. Unexplained partial states remain blocked. The existing failure-free-restart requirement after migration failure remains in force. No generic "cancel and return to normal" or automatic plugin downgrade is allowed after partial conversion.

Backend state and authentication checks must enforce the same gates independently of the UI. Do not blanket-allow nominally read-only routes that invoke lazy writers. Only the explicitly protected migration, diagnostic and recovery paths remain accessible.

Additional acceptance tests for the assistant

• Installation/startup does not persist a migration plan, create a snapshot or start conversion without the respective user actions; read-only detection may analyze proposed mappings in memory.
• Required or uncertain migration blocks new manual and scheduled plugin work while preserving safe diagnostics and Unraid controls.
• Preparation waits for actual writer quiescence and available mounted storage.
• Snapshot creation verifies actual bytes and always reaches the mandatory pause before any production rewrite.
• Download and backup acknowledgement alone cannot trigger apply.
• Missing, unauthenticated, stale or mismatched plan/snapshot approval is rejected through both UI and API paths.
• Browser closure/restart during the pause retains the same state; mid-apply interruption offers only original-plan, journal-backed continuation.
• Source/snapshot/cron changes or lost storage invalidate approval and block unsafe continuation.
• A failed/incomplete final verification never releases normal operation.
• User-facing phase text, acknowledgement, backup/privacy warnings and recovery guidance are available in German and English.

End-to-end migration matrix

Run the complete migration against isolated copies of every Phase 1 fixture and verify:

1. pre-change inventory and expected classification;
2. snapshot creation and checksum validation;
3. deterministic apply actions;
4. post-apply referential-integrity verification;
5. application startup and release of scheduler/writable APIs only after success;
6. idempotent restart with no repeated changes;
7. interrupted-run retry;
8. failure blocking and actionable System Health output;
9. preservation of ambiguous historical data;
10. documented manual recovery from the snapshot using the installed or corrected plugin version.

Production-derived samples must remain sanitized and must never be modified in place.

End-to-end application qualification

On successfully migrated fixtures and a dedicated Unraid test system, verify at minimum:

• the application starts normally after migration;
• exactly one job appears per configured ID;
• job edit, name change and archive-prefix change retain identity;
• schedule and cron execution work after migration;
• one manual backup completes and writes an ID-native status;
• prune uses the correct current and historical prefixes;
• live log, cancellation, locks and recovery work;
• dashboard, widgets, History, Reports and report mail remain continuous;
• Browse and Restore can inspect old and new-prefix archives;
• a restore and restore test complete successfully;
• repository assignment and Warn and require confirmation before changing a job repository #452 warning behavior remain correct;
• import/export, settings backup/restore and deletion follow the ID rules;
• support package and migration audit contain no secrets.

Documentation and release communication

Update German and English documentation with:

• the new Job name / Archive prefix model;
• what remains editable and what the internal ID means;
• migration prerequisites, explicit preparation, the verified pre-change snapshot and mandatory backup-check pause;
• the required recommendation to create an Unraid flash/configuration backup before installing the migration release;
• failure, blocked-startup and manual recovery guidance;
• the absence of an automatic plugin downgrade on Unraid;
• a request for volunteer migration testers before stable promotion.

Prepare a prominent release-note fragment that describes the migration and backup recommendation without exposing internal implementation noise.

Test-channel eligibility gate

A test-channel version may be built only when all of the following are true:

• Phases 1-8 are complete on the integration branch.
• Guarded startup detection and the user-initiated migration assistant are active and pass the complete automated fixture matrix.
• A successful migration reaches a usable application with scheduler and writable APIs enabled.
• At least one complete backup and restore/restore-test path works after migration.
• Failure cases block before unsafe writes or further operation.
• The branch contains all documentation and the migration release note.
• The final branch commit is pushed, clean and synchronized with current origin/main.
• The full mr-preflight.sh passes for that exact commit.

If these conditions are not met, no test-channel package is published. Unit tests, fixture tests and local maintainer tests continue instead.

Test and release sequence

1. Merge current origin/main into the integration branch after the last parallel hotfix.
2. Run focused migration and end-to-end tests.
3. Commit and push the final implementation state.
4. Run the full commit-bound preflight exactly once.
5. Publish and verify one test-channel candidate.
6. Ask volunteer testers to test fresh installation and representative migration copies.
7. Fix findings on the same integration branch; any changed final commit requires a new preflight and candidate.
8. Only after explicit maintainer approval, merge the single Introduce immutable job IDs across all job-dependent data and workflows #447 implementation PR.
9. Promote the exact tested package through the separate stable release PR.

Acceptance criteria

• immutable_job_id_v1 uses guarded detection and explicit user-authorized execution, crash-consistent per-file updates, idempotence, audit and failure blocking; it does not claim a single atomic cross-filesystem transaction.
• Both explicit user actions and the mandatory verified-snapshot pause are enforced by the backend as well as the UI.
• Successful migration results in a fully usable application, not merely converted files.
• Failed or ambiguous migration never releases normal writers or the scheduler.
• All automated, integration and manual qualification checks pass.
• The first test-channel candidate is built only after the end-to-end eligibility gate is satisfied.
• Stable promotion remains a separate explicit decision after volunteer and maintainer testing.