Phase 4/9: Cut over job APIs, repository assignments, and schedules to job_id

[borg-codex-bot]

Parent: #447

Depends on: Phase 3/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

Convert the active configuration and control plane from mutable job_key values to immutable job_id values. Job CRUD, repository relationships, schedules and cron must all address the same logical job after name, archive-prefix, repository or storage changes.

Job API and discovery

• Discover canonical jobs by <job_id>.json and validated payload identity.
• Address load, save, enable, disable, run preparation, delete preparation and other job actions by job_id.
• Return current display name, archive prefix and repository descriptors separately.
• Retain a bounded legacy-key request adapter only where Introduce immutable job IDs across all job-dependent data and workflows #447 explicitly permits it.
• Reject ambiguous legacy aliases and log boundary use as deprecated.
• Never write new mutable-key references.

Repository assignments

• Replace repository used_by and source_job_keys identity lists with canonical job ID references.
• Derive display labels from the current job inventory.
• Update old and new assignments atomically when a repository changes.
• Preserve one current repository per job.
• Do not create repository history or move existing archives.
• Reconciliation must report missing or dangling IDs explicitly.
• Repository deletion rules remain unchanged.

Schedules and cron

• Key schedules.json by job_id.
• Make cron requests submit job_id.
• Preserve cron expression and enabled state through migration and edits.
• Remove the current save ordering defect where changing Type ID saves a new job identity but leaves an invalid old schedule key.
• Regenerate the managed crontab only after schedule verification succeeds.
• Keep the restore-test scheduler boundary explicit for its later phase.

Transaction boundaries

Job save operations that affect metadata, repository assignment and schedule identity must not leave a partially renamed job. Define rollback or pre-write validation so that failure cannot produce the support-reported state with a saved new identity and an orphaned config_local schedule.

Tests

• discovery and CRUD by UUID;
• rename, prefix change, repository change and storage change without identity changes;
• atomic repository reassignment;
• schedule migration, save, disable and deletion by ID;
• cron generation and request payloads by ID;
• regression for config_local to pfsense_local showing one logical job and a preserved schedule;
• dangling, duplicate and ambiguous reference rejection;
• bounded unambiguous legacy API resolution;
• no new mutable-key persistence.

Test-channel policy

Do not publish a test-channel version. Backup runtime, status writers and readers are not fully converted yet, so a real installation would not have a complete operational path.

Acceptance criteria

• Job configuration and repository references use only job_id internally.
• Schedules survive every editable job descriptor change.
• Cron invokes jobs by ID.
• A failed save cannot leave metadata and schedule identity out of sync.
• Repository reconciliation and APIs reject invalid ID relationships clearly.

[borg-codex-bot]

Phase 4 configuration checkpoint (#474)

• UUID discovery and job configuration actions, current descriptor-based labels,
  canonical job_ids/source_job_ids assignments and an exact HTTP alias boundary.
• Strict UUID schedules, cron payloads, settings-preserving edits, job disable/
  enable handling and metadata/repository/schedule rollback on ordinary failures.
• Read-only reconciliation; orphan schedules, ambiguous aliases and corrupt
  references block writes without automatic repair or deletion.
• The config_local -> pfsense_local regression retains one metadata file, the
  same schedule, repository assignment identity and authoritative old alias.
• Maintainer contract: docs/maintainer/canonical-job-control.md.

Verification: 466 distinct focused tests passed across phase-1/2 foundation,
canonical wizard/control, repository concurrency and schedule-security runs.
The final combined control/wizard/contract run passed 221 tests; a subsequent
pre-mount rejection test passed separately. Python compilation, JavaScript
syntax, executable DE/EN UI tests and git diff --check passed. Local HTTP smoke
with synthetic data verified authenticated job/repository reads, schedule CRUD,
enable/disable, static assets and the login page. Cron installation was stubbed;
no production data, external storage or installed Unraid runtime was used.

Explicit pending integration: #475 must replace the temporary run-preparation
stop with the UUID runtime (including #463 RAM logs) and implement one retention
policy over the union of current/historical prefixes. Borg 1.4.5 cannot express
arbitrary prefix alternation in its single shell-glob filter. Multi-prefix
manual prune stops before mounting storage; it never prunes prefixes separately.
#478 owns historical artifact/secret cleanup; configuration deletion currently
preserves those artifacts. Remaining runtime/status/restore/transfer tests and
the global crash/rollback recovery gate still require their scheduled phases.
#474 stays open until its retention integration is covered.

No test-channel deployment, full final preflight, stable version bump or release
artifact. The explicit #447 integration exception defers these to #479.

[borg-codex-bot]

The remaining shared-prefix retention integration is implemented in ae5f47f on draft PR #480 (#475).

Automatic and manual retention now apply one calendar policy to the explicit current/historical prefix union. Real Borg 1.4.5 comparison and deletion tests passed, including preservation of an unrelated archive and a subsequent Borg check. The manual worker also passed against a real repository with its source job disabled. The temporary multi-prefix stop has been removed.

The #474 configuration and retention checkpoint is complete on the shared integration branch. This is still not installable: #476-#479 and the final test-channel gate remain pending. See docs/maintainer/canonical-job-runtime.md for scope, ownership checks and external Borg concurrency limits.