--- id: CON-PFM-OPS-001 name: Background Job feature: FEAT-PFM-OPS-01 product_area: platform module: operations revision: 1 status: draft product_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A background job is the persistent account of multi-step work that continues beyond its initiating request. It records progress and outcomes for inspection and recovery. owned_by: MOD-PFM-OPS synonyms: - job - job run - durable job - scheduled run not_to_be_confused_with: - Bulk data runs owned by the Data Job Engine - Single-task queue processing - The workflow execution represented by the durable record facets: - name: Kind meaning: The owning module’s declared category of background work. used_for: Naming runs and determining supported recovery. - name: Step definition meaning: The visible work sequence published for the individual run. used_for: Presenting the historical step catalog. - name: Steps and attempts meaning: Recorded progress and repeated task attempts. used_for: Locating interruptions and explaining recovery. - name: History meaning: Numbered events supporting the current job summary. used_for: Reviewing execution and continuing monitor updates. - name: Outcome and business consequence meaning: Final job standing and the meaning of failure for its subject. used_for: Settling work without stranding the affected record. - name: Requester notice meaning: A recorded attempt to inform the originating person of an outcome. used_for: Closing the request loop with delivery evidence. - name: Retry lineage meaning: The predecessor connection and completed work retained for recovery. used_for: Following distinct execution attempts. - name: Subject meaning: The readable description supplied for the work’s target. used_for: Recognizing a run without interpreting internal references. relationships: - to: CON-PFM-OPS-004 statement: >- First application grants prepare missing state synchronously, while background workspace activation enables core applications. provenance: observed source: >- services-platform:modules/licensing/services/enablement/provision-tenant-application.ts:provisionTenantApplication - to: CON-PFM-OPS-003 statement: Completed staff licensing changes request authorization invalidation through a background job. provenance: observed source: 'services-platform:modules/licensing/services/enablement/grant-licence-override.ts:grantLicenceOverride' - to: CON-PFM-SEC-002 statement: Workspace job lifetime follows retirement with explicit preservation of deletion evidence. provenance: observed source: 'services-platform:modules/jobs/services/persistence/tenant-purges.ts' lifecycle: - state: pending meaning: Recorded work awaiting execution. how_it_changes: Task reporting begins or reconciliation establishes an unstarted outcome. - state: running meaning: Execution has begun reporting its steps. how_it_changes: 'Work finishes, permanently fails or is settled by reconciliation.' - state: succeeded meaning: The job has reached successful finality. how_it_changes: The recorded result remains final. - state: failed meaning: The job has reached a failed final outcome. how_it_changes: Recovery creates a separate retry rather than reopening it. - state: cancelled meaning: Requested execution stopping has reached finality. how_it_changes: The cancellation result remains final. acted_on_by: - CAP-PFM-OPS-001 - CAP-PFM-OPS-002 - CAP-PFM-OPS-003 - CAP-PFM-OPS-004 - CAP-PFM-OPS-005 - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 visible_to: - ACT-PFM-001 - ACT-PFM-004 - ACT-PFM-005 - ACT-PFM-006 evidence: - >- services-platform at ad3f6a6: docs/jobs.md (all sections); modules/jobs (routes, scope, snapshots, notices, subjects, kind labels, views, reconciler); docs/hq/rhythm-hq-plan.md §D11, §D12, §E5. - >- macroservice-libraries at 54536a4: packages/jobs README, CHANGELOG 0.5.0 and 0.6.0, persistence/job-persistence-columns.ts (statuses), engine/job-engine.ts (submit, retry, cancel), reconciler/job-reconciler.ts. - >- react-console at baf6dae: components/maintenance/job-runs-screen.tsx, components/console/hq/job/*, lib/hq/job-snapshot.ts. supersedes: [] --- # Background Job ## What It Is A background job gives long-running Rhythm work a continuing record. Staff can follow the work after the request that initiated it returns, even when the work crosses services or takes several minutes. Workspace preparation, search rebuilding and monthly snapshot production are examples. The record supplies a place to inspect what started, what completed and what needs recovery. The job combines a declared kind of work with an individual execution identity. Its steps, attempts, progress and event history describe that particular run. The owning module defines the work and its consequences; the shared engine provides consistent recording. A submission identity connects repeated requests to the same intention. The governing submission and transition contracts are specified in the background-work capabilities. ## What It Is Not The durable job record is distinct from the cloud execution carrying out its tasks. An execution may disappear or fail before starting, while its job still needs an understandable outcome. A data import or bulk-edit run belongs to the separate Data Job Engine. Ordinary queued messages also serve a different purpose: they carry recoverable single tasks without becoming an operator’s multi-step progress record. ## How It Is Used Rhythm staff inspect jobs in HQ when preparing workspaces or investigating failures. A customer administrator uses Scheduled Jobs to review activity within the active workspace. These views answer related questions for different audiences: staff may investigate across customers, while customer readers work within their evaluated reach. A useful job record lets someone distinguish unfinished work from failed work and identify the next recovery action. Reconciliation provides a second way to settle work when ordinary task reporting stops. Retry creates a new execution record rather than erasing the first attempt. A readable monitor therefore supports investigation after the person has left the original screen or the execution has stopped. ## Its Facets **Kind.** The declaration identifies the work, its owning application and the recovery behavior its owner supports. Readable labels make a mixed list understandable. **Step definition.** The published catalog explains the sequence a person watches. It preserves the wording used for the run even when later declarations change. **Steps and attempts.** These describe how execution progresses and whether a task has been attempted more than once. They help staff distinguish ordinary retry from final failure. **History.** Numbered events provide the chronological account behind the current summary. Monitors can request events beyond their last position. **Outcome and consequence.** The final status describes the job, while the registered consequence describes what failure means for its subject. **Requester notice.** Selected work attempts to tell its requester how it ended. Delivery state is recorded separately, and the current mechanism admits duplicate delivery in interruption or concurrency cases. **Retry lineage.** The connection between attempts preserves the recovery story and supports reuse of completed work. **Subject.** A readable subject explains what the job concerns without asking staff to interpret internal references. ## How It Relates Jobs usually serve another module’s records: a workspace, search index, snapshot or population. Those modules retain the meaning of their work. Licensing uses jobs indirectly for authorization-cache invalidation. Compatible publishing views let jobs from other Rhythm services participate in the same monitors. Workspace purge applies the job-lifetime rules while preserving the record of the deletion itself. ## What It Could Become The product should decide which audiences may retry or cancel each declared kind. The engine’s support does not establish that a usable management surface exists. Requester links also need to follow the audience as customer-requested kinds adopt notices. A move to the notifications platform should retain delivery evidence while stating honestly whether the contract guarantees suppression of completed repeats or strictly once-only delivery.