Phase 3/9: Introduce canonical ID-based job metadata and replace Type ID in the wizard

[borg-codex-bot]

Parent: #447

Depends on: Phases 1/9 and 2/9

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

Delivery model: This phase is committed to the shared #447 integration branch and the single draft pull request against main. It is not merged or released independently.

Objective

Implement the canonical ID-based job model and the target wizard experience while preserving the frozen migration contract. Type ID must disappear from the new canonical user model and be replaced by an explicit complete archive prefix.

Canonical job metadata

Introduce the target metadata contract:

• generated immutable UUIDv4 job_id;
• metadata filename <job_id>.json;
• editable display name;
• one current repository_key;
• ordered, de-duplicated archive_prefixes with the current complete prefix first;
• bounded legacy_job_keys only for migration and compatibility resolution;
• all existing job-owned operational settings preserved.

Rules:

• creating a job generates a new ID exactly once;
• editing a job always retains the ID;
• duplicating a job always creates a new ID;
• no new canonical job stores job_key, Type ID, backup_type or location as identity;
• location is resolved from the selected repository/storage context;
• a missing ID is never silently generated while merely reading active migrated metadata.

Wizard changes

Replace the current fields with:

Job name
Archive prefix
Repository

The job ID remains internal and non-editable.

The wizard must:

• show the complete exact archive prefix;
• never append a hidden -backup suffix;
• show an exact archive-name preview including the timestamp pattern;
• offer a safe editable suggestion for new jobs;
• retain the previous prefix in archive_prefixes when the current prefix changes;
• explain that old prefixes remain available only in the currently assigned repository;
• preserve the repository-change confirmation owned by Warn and require confirmation before changing a job repository #452;
• preserve all unrelated job settings on name or prefix edits;
• use German and English text throughout.

Archive-prefix contract

• archive_prefixes[0] is used for new archives.
• Remaining entries are previous complete prefixes used by restore and retention scoping.
• Prefixes remain readable and never contain the UUID merely for identity.
• Validation must prevent invalid Borg archive names and argument injection.
• Existing valid prefix order must be preserved during migration normalization.

Compatibility boundary

Legacy job parsing may exist only in explicit migration or boundary adapters. New UI requests and new metadata must use job_id. Do not introduce permanent dual-write behavior.

Tests

• create, edit, rename, prefix change and duplicate operations;
• immutable ID retention across every edit;
• safe prefix validation and exact preview;
• no hidden suffix;
• preservation and de-duplication of previous prefixes;
• repository/location changes without identity changes;
• preservation of all job settings;
• German and English wizard rendering;
• legacy fixtures can be converted into the target metadata model without activating startup migration.

Test-channel policy

Do not publish a test-channel version yet. The wizard and metadata model are not useful or safe on a real installation until schedules, runtime, status readers and all dependent stores use the new identity.

Acceptance criteria

• New target-model jobs have one immutable UUID and an ID-named metadata file.
• Type ID is absent from the new wizard and canonical active model.
• The exact user-visible prefix creates the exact archive prefix.
• Edits cannot change the job ID or create a second logical job.
• Previous archive prefixes are retained correctly.
• Existing job settings remain intact in target-model tests.

[borg-codex-bot]

Phase 3 implementation checkpoint

Implemented on codex/issue-447-immutable-job-ids in commit 4fb6822,
as part of the existing draft PR #480. This issue remains open for integration
and maintainer review; it is not a standalone release.

• Added canonical schema-v4 metadata, full UUIDv4 IDs and ID-named job files.
• Create allocates once on the save path; read/preview never allocates. Edits
  retain the ID; duplicate creates a new one, with empty aliases and a fresh
  prefix scope. Unknown IDs and mutable-key requests are rejected.
• Name/prefix edits retain operational settings, including unknown and
  unexposed nested settings. Previous prefixes remain ordered and unique.
• Wizard uses a complete explicit prefix, exact timestamp-pattern preview,
  editable suggestions, retained history tooltip and DE/EN explanations.
• Repository selection determines location; no repository history is added.
  Strict assignment and shared-repository archive-ownership checks prevent
  silent reassignment repair or overlapping prefix ownership.
• Added stale-editor protection and retry-by-returned-ID after a schedule
  failure, avoiding the old reconstruction from Type ID plus location.
• The inactive planner validates proposed target jobs through the shared model.
  No startup registration or production-data migration was enabled.

Verification

• 539 focused tests passed, including all 343 existing migration foundation
  tests; the final input-validation tightening was also rechecked with 75
  passing targeted tests.
• Python compilation, JS syntax checks and diff whitespace checks passed.
• DE/EN wizard component markup rendered locally with synthetic data at
  1055x687. This does not replace later real Unraid backup/migration testing.

Explicit integration limits

• Phase 4/9: Cut over job APIs, repository assignments, and schedules to job_id #474 must convert general discovery, repository readers/writers, deletion
  guards and schedule APIs. Do not run legacy repository normalizers over
  canonical UUID assignment data.
• Phase 5/9: Cut over backup runtime, status, logs, locks, recovery, and notifications to job_id #475 owns the UUID runner, actual archive creation and runtime continuity.
• Phase 9/9: Activate immutable_job_id_v1 and qualify the end-to-end test candidate #479 owns the global gate, approved manual migration assistant and full
  end-to-end verification. A crash between the two durable job/repository
  replacements is detectable but not claimed to be an atomic transaction.
• Warn and require confirmation before changing a job repository #452 separately owns the repository-change warning/confirmation and is not
  represented as already implemented here.
• No package, test-channel build or final preflight in this intermediate phase,
  as agreed for Introduce immutable job IDs across all job-dependent data and workflows #447.

Detailed boundary documentation:
Canonical job model and wizard.