Phase 1/9: Freeze the immutable job identity contract and migration fixture matrix

[borg-codex-bot]

Parent: #447

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

Freeze the target identity contract and create a representative, sanitized migration fixture matrix before any migration is allowed to modify user data.

Issue #447 touches every job-dependent subsystem. The implementation must start from explicit invariants and reproducible legacy states rather than adapting the schema while write logic is already active.

Scope

Canonical contract

Document and test the final rules for:

• UUIDv4 job_id generation, validation, uniqueness and immutability;
• <job_id>.json canonical metadata filenames;
• editable name, explicit complete archive_prefixes[0], one current repository_key and bounded legacy_job_keys;
• removal of Type ID, backup_type, location and mutable job_key as active identity;
• historical descriptor snapshots that remain readable but are never foreign keys;
• archive-prefix history within the current repository;
• duplicate, import, merge, configuration restore and deletion identity behavior;
• classification of unassigned legacy history without guessing.

Dependency inventory

Turn the inventory in #447 into a code-level checklist that names the active readers and writers for:

• job metadata and discovery;
• repository assignments;
• schedules and cron;
• runtime state, locks, cancellation and recovery;
• statuses, logs and weekly snapshots;
• notifications and reminder state;
• dashboard and external widgets;
• History and Reports;
• Browse and Restore, restore runs and restore history;
• restore-test policy, scheduling, results and proof;
• import/export, settings backup/restore, support bundles, health checks and deletion.

Every current job_key, backup_type or filename-derived join must have an owner phase and target behavior.

Fixture matrix

Create sanitized fixtures and expected outcomes for at least:

• a fresh installation with no jobs;
• one normal legacy job;
• multiple jobs across different storage types and repositories;
• jobs with and without archive_prefixes;
• a job whose Type ID was changed from config to pfsense, leaving config_local schedules, status and reports behind;
• renamed jobs and archive prefixes;
• disabled schedules and overdue state;
• restore-test results and restore history;
• archived and orphaned status records;
• ambiguous aliases and conflicting active references;
• incomplete or corrupt JSON files;
• an interrupted migration with an already journaled UUID mapping;
• production-derived edge cases only after all secrets and personal data are removed.

Each fixture must state whether migration is not_applicable, applicable, blocked, or expected to succeed, and must define the exact post-migration invariants.

Deliverables

• Maintainer-facing identity and migration contract documentation.
• A complete dependency ownership checklist mapped to phases 2-9.
• Sanitized version-controlled fixtures with expected results.
• Reusable assertions for referential integrity and legacy classification.
• Explicit resolution of contradictions found between current code and Introduce immutable job IDs across all job-dependent data and workflows #447 before implementation continues.

Tests

• Fixture schema validation.
• Duplicate UUID and alias detection.
• Archive-prefix normalization expectations.
• Expected classification of every fixture.
• Confirmation that fixture data contains no secrets or production-identifying values.

Test-channel policy

Do not build or publish a test-channel version in this phase. There is no safe user-testable migration or complete application flow yet. Verification is limited to documentation review, fixture validation and local automated tests.

Acceptance criteria

• The target schema and identity invariants are unambiguous.
• Every known mutable-key dependency is assigned to a later phase.
• The support-reported Type ID change failure is represented by a regression fixture.
• Successful, ambiguous, invalid and interrupted migration states have expected outcomes.
• No production data is modified and no migration is registered for startup execution.

[borg-codex-bot]

Phase 1 implemented for contract review

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

Commit: 9ac8715

Single shared draft PR: #480. No separate phase PR and no main merge.

Deliverables:

• Consolidated identity and migration contract.
• Source dependency ownership checklist, with owners across Phase 2/9: Build the inactive migration planner, snapshot, journal, and verifier #472-Phase 9/9: Activate immutable_job_id_v1 and qualify the end-to-end test candidate #479 and a source-scan regression guard.
• 35 synthetic migration cases and their expected observations.
• Reusable assertions for UUIDv4 identity, canonical metadata filenames,
  duplicate aliases/IDs, edit/import/duplicate identity, references,
  unassigned history and byte-preservation/no-write outcomes.

The support-reported config -> pfsense case is represented explicitly:
the orphan active schedule blocks migration; prefix history alone is not
enough evidence to reassign it. Historical records can remain unassigned
without creating ghost dashboard jobs.

Validation: 146 focused tests passed, including 99 new contract/fixture tests
and existing startup, maintenance, source-path, schedule, status and runner
tests. Python compilation and diff whitespace checks passed.

Important limitation: the new tests validate fixture data and the assertion
oracle. They do not claim that a migration has run successfully. #472 must
execute the real detector/planner against these fixtures; #479 must verify
real on-disk conversion, interruptions and the application gate.

No production data, runtime plugin code, startup migration registration or
release artifacts changed. Per the approved phase plan, no test-channel
package was built and final source preflight is deferred to #479.

#471 remains open/In progress for maintainer contract review; it is not in
Test channel or Ready for release. The shared PR remains draft and phases
#472-#479 are not yet implemented.