refactor(slice-85): name lifecycle runs as jobs

Author: rohans0509

docs/codealmanac-launch/decisions.md

@@ -126,6 +126,16 @@ Status: active.
 - Code quality is a first-class launch objective. Refactors should be done when
   they remove split-brain concepts, provider leakage, stale compatibility, or
   unclear ownership; they should not be done for motion alone.
+- Other contributors may push to `codealmanac` or `codealmanac-hosted` while
+  this launch run is active, especially for UX improvements. Treat those
+  commits as collaborative input. Do not revert them merely because they are
+  rough; inspect them, preserve the intended UX/product improvement, and fold
+  them into the ongoing code-quality pass.
+- If an incoming contributor change looks over-defensive, preserves the wrong
+  product model, creates a parallel path, or solves the immediate symptom in a
+  way that fights the long-term architecture, send a RelayForge/Discord alert
+  before absorbing it silently. The alert should name the concern and the safer
+  long-term direction.
 - The README should preserve the old README's banner, feel, and core language
   while updating launch commands and product facts. Do not replace it with a
   generic marketing README.

docs/codealmanac-launch/init-first-build-prompt-restoration.md

@@ -83,7 +83,7 @@ Expected responsibilities:
   writing to `PageRunWorkflow`;
 - page-run workflow: unchanged shared lifecycle machinery for harness events,
   mutation safety, run records, logs, outputs, and index refresh;
-- run queue: accept `RunOperation.INIT` specs alongside ingest/garden;
+- run queue: accept `JobOperation.INIT` specs alongside ingest/garden;
 - CLI: parse flags and call workflows; no internal shelling out to
   `codealmanac`.
 
@@ -149,7 +149,7 @@ Update tests that currently protect the wrong behavior:
 - remove parser/CLI expectations for public `build`;
 - make `init` test the first-build lifecycle path;
 - add background `init` queue tests;
-- add run-spec validation for `RunOperation.INIT`;
+- add run-spec validation for `JobOperation.INIT`;
 - add prompt inventory tests proving the init/ingest/garden prompt resources
   exist;
 - add manual inventory tests for the restored manual resources;

docs/codealmanac-launch/next-agent-brief.md

@@ -12,6 +12,16 @@ Cloud remains the primary product path. Local remains a free/dev surface with a
 parallel conceptual model where it is useful, but not a reason to muddy the
 cloud setup flow.
 
+Other people may push to `codealmanac` or `codealmanac-hosted` while this run
+is active, especially UX work. Treat those commits as collaborative input. If
+they are rough, preserve the intended product improvement and fold the changes
+into the code-quality pass instead of reverting them.
+
+If an incoming commit is over-defensive, creates a parallel path, or looks like
+the wrong long-term solution, send a RelayForge/Discord alert before absorbing
+it silently. The alert should explain the architectural concern and the cleaner
+direction.
+
 ## Current Verified State
 
 - Hosted `main` includes
@@ -588,6 +598,33 @@ repaired.
   routes to AuthKit and does not expose a code-level force-GitHub provider
   option.
 
+## Current Slice 85 Handoff
+
+- Slice 85 completed the repo-local lifecycle job rename.
+- `src/codealmanac/jobs/ledger/` now owns `JobRecord`, `JobLogEvent`,
+  `JobSpec`, `JobStore`, and `JobLedgerService`.
+- `src/codealmanac/jobs/queue/` now owns `JobQueueWorkflow`.
+- Service, CLI, sync, maintenance, viewer API, server API, and tests use
+  `job_id` for repo-local lifecycle records.
+- Cloud runs and branch-triggered local runs intentionally remain under
+  `src/codealmanac/cloud/runs/` and `src/codealmanac/local/runs/`.
+- `src/codealmanac/engine/run_ids.py` now owns engine run ID validation so
+  engine artifacts do not import local control-plane ID types.
+- Architecture tests prevent the removed `services/runs` and
+  `workflows/run_queue` source paths from returning.
+- Verification passed:
+  `uv run pytest tests/test_runs_service.py tests/test_run_queue_workflow.py
+  tests/test_cli.py tests/test_sync_workflow.py tests/test_init_workflow.py
+  tests/test_ingest_workflow.py tests/test_garden_workflow.py
+  tests/test_viewer_service.py tests/test_server.py tests/test_maintenance_api.py
+  tests/test_architecture.py -q --tb=short` (`217 passed`);
+  `uv run ruff check src tests`; `uv run pytest -q --tb=short`
+  (`513 passed`); `git diff --check`.
+- If another contributor pushes while this run continues, treat the commit as
+  collaborative input. Preserve the intended UX/product improvement. If it
+  creates a parallel path or over-defensive architecture, alert Rohan through
+  RelayForge/Discord before silently absorbing it.
+
 ## Remaining Launch Gaps
 
 - Final provider cleanup. CodeAlmanac and hosted branch/main convergence are

docs/codealmanac-launch/progress.md

@@ -8,7 +8,7 @@ Percentages are planning estimates, not accounting metrics.
 
 ## Latest RelayForge Update
 
-Sent: 2026-07-03 after Slice 84 CodeAlmanac local package boundary.
+Sent: 2026-07-03 after Slice 85 CodeAlmanac job ledger naming.
 
 Route:
 
@@ -19,10 +19,12 @@ doppler run --project almanac --config dev -- \
   --binding rohan-almanac-main "..."
 ```
 
-Slice 84 moved the local control plane into `src/codealmanac/local/`, removed
-tracked old local service/workflow source modules, added a `CodeAlmanacLocal`
-composition-root facade, and kept CLI behavior unchanged. Focused local
-verification passed with `131 passed`; full local verification passed with
+Slice 85 moved repo-local lifecycle job storage into
+`src/codealmanac/jobs/ledger/` and the background lifecycle queue into
+`src/codealmanac/jobs/queue/`. Lifecycle records now use `job_id` and
+`JobRecord`/`JobLogEvent` naming across service, CLI, viewer API, sync,
+maintenance, and tests; cloud/local trigger executions remain `runs`. Focused
+verification passed with `217 passed`; full local verification passed with
 `uv run ruff check src tests`, `uv run pytest -q --tb=short` (`513 passed`), and
 `git diff --check`.
 
@@ -48,12 +50,16 @@ verification passed with `131 passed`; full local verification passed with
 - Slice 84 implemented the next CodeAlmanac-side refactor from that audit:
   local control DB, hooks, delivery, run preparation/execution/jobs/worker,
   policies, setup, status, and update now live under `src/codealmanac/local/`.
+- Slice 85 implemented the job-ledger naming cleanup from that audit:
+  repo-local lifecycle jobs now live under `src/codealmanac/jobs/ledger/` and
+  `src/codealmanac/jobs/queue/`, while branch-triggered local/cloud executions
+  remain `runs`.
 
 ## Percentages
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 99.8% | 99.5% | Slice 84 moved the local control plane into `src/codealmanac/local/`, added architecture guards, and passed focused local gates. |
+| CodeAlmanac backend/local | 99.9% | 99.8% | Slice 85 renamed repo-local lifecycle execution to jobs, moved the ledger/queue under `src/codealmanac/jobs/`, added architecture guards, and passed focused/full gates. |
 | CodeAlmanac CLI/public UX | 100% | 100% | Published CLI `0.1.9` passed public install smoke; root uninstall is now scoped to setup-owned artifacts, while automation teardown remains explicit. |
 | CodeAlmanac-hosted backend/auth/API | 100% | 100% | Slice 75 added production `/v1/repositories`; production repo list and repo status pass without per-repo permission fanout. |
 | Hosted frontend/onboarding | 100% | 99% | Slice 76 shipped repository readiness, capture handoff, maintained branches, and per-branch delivery to Vercel; Chrome verified production with no console errors. |

docs/codealmanac-launch/verification-matrix.md

@@ -583,9 +583,9 @@ Current evidence:
   agent-backed first-build runs.
 - `codealmanac init` now accepts `--using`, `--background`, `--force`,
   `--verbose`, and `--json`; public `codealmanac build` is not parsed.
-- `RunOperation.INIT` and init queue specs are durable under the existing
+- `JobOperation.INIT` and init queue specs are durable under the existing
   file-backed run store.
-- `RunQueueWorkflow.start_init_background(...)` queues init work and the hidden
+- `JobQueueWorkflow.start_init_background(...)` queues init work and the hidden
   worker drains it through `InitWorkflow.run_with_run(...)`.
 - `LifecycleMutationPolicy(require_clean_almanac=False)` lets init create its
   starter root while preserving the outside-Almanac mutation safety check.
@@ -609,7 +609,7 @@ Current evidence:
 - Slice 24 moved file-backed lifecycle job state from repo-local
   `<almanac-root>/jobs/` to `~/.codealmanac/jobs/<workspace-id>/`.
 - `AppConfig.jobs_path` defaults to `~/.codealmanac/jobs`.
-- `RunsService` now writes new run records, event logs, queue specs, and
+- `JobLedgerService` now writes new run records, event logs, queue specs, and
   worker locks to the user-level workspace jobs directory while reading
   legacy repo-local run records when needed.
 - `SyncLedgerStore` now writes `sync-ledger.json` under the same user-level
@@ -796,7 +796,7 @@ Current evidence:
   (`306 passed, 1 warning`), `uv run ruff check .`,
   `uv run ruff format --check .`, `python -m compileall backend/src
   backend/modal_app -q`, and `git diff --check`.
-- Slice 33 added hosted `RunStatus.STALE` for expected-head drift during
+- Slice 33 added hosted `JobStatus.STALE` for expected-head drift during
   delivery.
 - `backend/tests/test_github_git_contract.py` proves Git commit delivery raises
   typed `GitHubBranchHeadChanged` when the branch ref no longer matches the
@@ -1202,7 +1202,7 @@ Current evidence:
   `main`; it failed in `uv run pytest` because
   `test_runs_service_streams_attach_until_run_is_terminal` exposed a real
   terminal-record/log-event race in local run attach streaming.
-- Slice 54 fixed the race in `RunAttachStreamer` and pushed commit
+- Slice 54 fixed the race in `JobAttachStreamer` and pushed commit
   `a0c86bfe6bedfdd2cd7bd8ff21c252692a6c4eb6` to `origin/dev` and
   `origin/main`.
 - Slice 54 local gates after the fix passed: focused run-stream tests
@@ -1671,3 +1671,21 @@ Known residue:
   (`131 passed`). Full local verification passed with
   `uv run ruff check src tests`, `uv run pytest -q --tb=short` (`513 passed`), and
   `git diff --check`.
+
+## Slice 85 CodeAlmanac Job Ledger Naming
+
+- Requirement: repo-local lifecycle execution should not share the `run` noun
+  with cloud runs and branch-triggered local runs.
+- Implementation evidence: `src/codealmanac/jobs/ledger/` now owns
+  `JobRecord`, `JobLogEvent`, `JobSpec`, `JobStore`, and `JobLedgerService`;
+  `src/codealmanac/jobs/queue/` now owns `JobQueueWorkflow`.
+- Boundary evidence: `src/codealmanac/cloud/runs/` and
+  `src/codealmanac/local/runs/` keep the run noun for trigger-created
+  executions, while repo-local lifecycle records use `job_id` across service,
+  CLI, sync, maintenance, viewer API, server API, and tests.
+- Engine ID evidence: `src/codealmanac/engine/run_ids.py` owns engine run ID
+  validation, so engine artifact stores do not import local control-plane IDs.
+- Verification evidence: focused lifecycle job, sync, CLI, viewer, server,
+  maintenance, and architecture test set passed (`217 passed`). Full local
+  verification passed with `uv run ruff check src tests`,
+  `uv run pytest -q --tb=short` (`513 passed`), and `git diff --check`.

docs/codealmanac-launch/worklog.md

@@ -509,7 +509,7 @@
   `test_runs_service_streams_attach_until_run_is_terminal` exposed a real
   attach-stream race: the file-backed run ledger can expose a terminal record
   before the terminal status event is visible.
-- Fixed the attach-stream race in `RunAttachStreamer` by waiting through a
+- Fixed the attach-stream race in `JobAttachStreamer` by waiting through a
   bounded terminal-record/log-event settle window. Added a regression test that
   waits through repeated terminal-log race snapshots.
 - Verified the fix locally with focused run-stream tests (`3 passed`), full
@@ -796,7 +796,7 @@
   infra/deploy rename 84%.
 - Planned Slice 44 in
   `docs/plans/2026-07-02-slice-44-cloud-run-cancel.md`.
-- Added hosted `RunStatus.CANCELLED`, `UpdatesStore.mark_cancelled(...)`,
+- Added hosted `JobStatus.CANCELLED`, `UpdatesStore.mark_cancelled(...)`,
   `UpdateCancellation`, and `Updates.cancel_run(...)`.
 - Added Modal worker cancellation through
   `modal.FunctionCall.from_id(call_id).cancel(terminate_containers=False)`.
@@ -1114,7 +1114,7 @@
   `origin/codex/workos-authkit-api-foundation`.
 - Planned Slice 33 in
   `docs/plans/2026-07-02-slice-33-hosted-delivery-stale-outcome.md`.
-- Added hosted `RunStatus.STALE` and `UpdateResult.stale(...)` for runs whose
+- Added hosted `JobStatus.STALE` and `UpdateResult.stale(...)` for runs whose
   target branch moved before delivery.
 - Replaced raw GitHub commit-head drift `ValueError` with typed
   `GitHubBranchHeadChanged`.
@@ -1147,7 +1147,7 @@
 - Added hosted SQL-backed `run_events` with ordered `(run_id, sequence)`
   storage, event kind, message, timestamp, and optional normalized
   `payload_json`.
-- Added hosted `RunEventKind` and `RunEvent` models, `RunEventRow`, and
+- Added hosted `JobEventKind` and `RunEvent` models, `RunEventRow`, and
   `run_event_from_row`.
 - Wired `UpdatesStore` transitions to append lifecycle status events for
   queued, running, delivered, and failed runs in the same transaction as the
@@ -1761,9 +1761,9 @@
 - Added public first-build `codealmanac init` flags for harness selection,
   foreground/background mode, `--force`, `--verbose`, `--guidance`, and
   background JSON output.
-- Added `RunOperation.INIT` and durable init queue specs.
-- Added `RunQueueWorkflow.queue_init(...)` and
-  `RunQueueWorkflow.start_init_background(...)`.
+- Added `JobOperation.INIT` and durable init queue specs.
+- Added `JobQueueWorkflow.queue_init(...)` and
+  `JobQueueWorkflow.start_init_background(...)`.
 - Updated the hidden worker drain path so queued init jobs run through
   `InitWorkflow.run_with_run(...)`.
 - Added init-specific mutation policy behavior:
@@ -1893,9 +1893,9 @@
 - Added hosted `ManualBranchRuns` so the `Updates` facade stays small and the
   product verb owns authorization, GitHub branch-head resolution, delivery
   policy lookup, duplicate-head idempotency, and worker start.
-- Added mirrored frontend `StartRunRequestDTO` to preserve backend/frontend DTO
+- Added mirrored frontend `StartJobRequestDTO` to preserve backend/frontend DTO
   parity.
-- Added CodeAlmanac `CloudRunsService.start_for_repo`,
+- Added CodeAlmanac `CloudJobLedgerService.start_for_repo`,
   `CloudRunsWorkflow.start`, and public
   `codealmanac runs start --branch <branch>`.
 - Pushed hosted commit `14caf8b feat: start cloud runs from CLI` to
@@ -2490,3 +2490,25 @@
   tests/test_deliveries_service.py -q --tb=short` (`131 passed`).
 - Slice 84 full local verification passed with `uv run ruff check src tests`,
   `uv run pytest -q --tb=short` (`513 passed`), and `git diff --check`.
+
+## 2026-07-03 Slice 85 CodeAlmanac Job Ledger Naming
+
+- Slice 85 moved repo-local lifecycle job storage from `services/runs` to
+  `src/codealmanac/jobs/ledger/`.
+- Slice 85 moved the repo-local background lifecycle queue from
+  `workflows/run_queue` to `src/codealmanac/jobs/queue/`.
+- The job ledger now uses `JobRecord`, `JobLogEvent`, `JobSpec`,
+  `JobLedgerService`, `JobStore`, and `job_id` across service, CLI, viewer API,
+  sync, maintenance, and tests.
+- Branch-triggered local/cloud-parallel execution intentionally remains
+  `run`-named under `src/codealmanac/local/runs/` and `src/codealmanac/cloud/runs/`.
+- Added `src/codealmanac/engine/run_ids.py` so engine run artifact IDs do not
+  import local-control types.
+- Focused Slice 85 verification passed:
+  `uv run pytest tests/test_runs_service.py tests/test_run_queue_workflow.py
+  tests/test_cli.py tests/test_sync_workflow.py tests/test_init_workflow.py
+  tests/test_ingest_workflow.py tests/test_garden_workflow.py
+  tests/test_viewer_service.py tests/test_server.py tests/test_maintenance_api.py
+  tests/test_architecture.py -q --tb=short` (`217 passed`).
+- Full Slice 85 verification passed with `uv run ruff check src tests`,
+  `uv run pytest -q --tb=short` (`513 passed`), and `git diff --check`.