--- id: SVC-PFM-OPS-jobs title: Background Jobs product_area: platform module: operations repository: services-platform source_module: modules/jobs revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-OPS-001 does_not_own: - 'Kind owners retain their tables, steps, tasks, submission authority and business failure effects.' - >- Security and workspace lifecycle own access refresh, provisioning, purge and reset work; Jobs monitors and reconciles those records. - Cross-service monitoring reads published views without changing the other owner’s job records. inference: [] operations: - operation_id: getJobsHealth intent: Return technical build health for the jobs function. access: public permission: none realises: [] published_to_submissions: 'not published: a technical health route' - operation_id: listJobs intent: >- Return a page of runs for the caller’s customer and reachable workspaces, ordered by recent activity and applying the supported filters. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: countJobs intent: 'Count matching runs for the caller’s customer and reachable workspaces, including active-only selection.' access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobKinds intent: >- Return present kinds for the caller’s customer and reachable workspaces with catalogue labels and owning applications. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: getJob intent: >- Return one scoped run’s summary, steps, attempts, published definition and history for the caller’s customer and reachable workspaces. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobEvents intent: >- Return history after the requested sequence for one run within the caller’s customer and reachable workspaces. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobsOfTenant intent: >- Return a page of runs for the workspace selected in the path, across compatible services, ordered by recent activity and applying the supported filters. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: countJobsOfTenant intent: >- Count matching runs for the workspace selected in the path, across compatible services, including active-only selection. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobKindsOfTenant intent: >- Return present kinds for the workspace selected in the path, across compatible services with catalogue labels and owning applications. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: getJobOfTenant intent: >- Return one scoped run’s summary, steps, attempts, published definition and history for the workspace selected in the path, across compatible services. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobEventsOfTenant intent: >- Return history after the requested sequence for one run within the workspace selected in the path, across compatible services. access: console permission: platform.jobs.read realises: - CAP-PFM-OPS-005 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobsInHq intent: >- Return a page of runs for all customers under staff authority, optionally narrowed by customer or workspace, ordered by recent activity and applying the supported filters. access: internal permission: hq.jobs.read realises: - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: countJobsInHq intent: >- Count matching runs for all customers under staff authority, optionally narrowed by customer or workspace, including active-only selection. access: internal permission: hq.jobs.read realises: - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobKindsInHq intent: >- Return present kinds for all customers under staff authority, optionally narrowed by customer or workspace with catalogue labels and owning applications. access: internal permission: hq.jobs.read realises: - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: getJobInHq intent: >- Return one scoped run’s summary, steps, attempts, published definition and history for all customers under staff authority, optionally narrowed by customer or workspace. access: internal permission: hq.jobs.read realises: - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' - operation_id: listJobEventsInHq intent: >- Return history after the requested sequence for one run within all customers under staff authority, optionally narrowed by customer or workspace. access: internal permission: hq.jobs.read realises: - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 published_to_submissions: 'not published: a read that captures no business data' events: [] jobs: - name: Job reconciler schedule: every five minutes does: >- Examine silent Platform jobs, recover their recorded outcomes and invoke workspace and website repair in the same invocation. concurrency: Reserve one invocation with a four-minute timeout and an invocation-silence alarm. - name: Requester notice schedule: on a notifying kind’s outcome does: 'Resolve a notifying run’s requester and attempt delivery, recording the claim and outcome.' concurrency: Pending claims permit multiple senders; future retry is eligible but not guaranteed. integrations: - system: AWS Step Functions direction: outbound contract: 'Start, describe or stop the owner’s orchestration execution using the declared kind workflow.' - system: Shared e-mail path (SES) direction: outbound contract: Use the shared sender and environment delivery policy for requester messages. - system: Other macroservices’ job views direction: inbound contract: 'Discover compatible root, step and event views and read them under audience scope.' consistency: - rule: 'The owner can commit its business change and job together, with execution start after commit.' kind: transactional compensation: A pending unstarted job is eligible for failure reconciliation and its kind’s recovery effect. - rule: 'Step reporting commits the step, history event and root summary using version checks.' kind: transactional compensation: Transactional rollback retains the prior account. - rule: >- Each five-minute pass considers at most two hundred jobs silent for fifteen minutes; backlog and unsuccessful passes can delay recovery. kind: eventual compensation: >- Explicit failed settlement applies recovery first; correction of success to failure applies recovery after settlement. - rule: 'Requester delivery can fail or repeat, and another invocation may reclaim a failed or pending notice.' kind: eventual compensation: No separate retry sweep guarantees later requester delivery. - rule: Cross-service lists combine separately read schema pages rather than one shared snapshot. kind: eventual compensation: Read failure returns no combined answer and changes no owner records. evidence: - >- services-platform at ad3f6a6: modules/jobs/aws/api/jobs.routes.ts (makeJobRoutes and its three declarations), aws/lambda/RECONCILER.handler.ts, aws/logic/jobs-reconciler.lambda.ts, services/*, db/*; aws/platform.service.ts (JOBS_PERMISSIONS, HQ_JOBS_PERMISSIONS); docs/jobs.md. - >- macroservice-libraries at 54536a4: packages/jobs src (engine, reconciler, task, workflow, persistence, api, aws). - >- codex examination 2026-10-23: checked the pinned source anchors, planning references and enforcement boundaries; unresolved limits are recorded in module findings. controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Background Jobs ## What This Service Is For Background Jobs provides durable operational accounts and common monitors for work owned by Rhythm modules. The shared engine supplies reporting semantics, while Platform adds requester delivery and reconciliation of its own job families. ## Boundary The kind owner controls business tables, tasks and failure effects. Platform owns requester notices and publishes its own monitoring views. Compatible service views contribute read-only records to the common monitor; recovery does not write another service’s job tables. ## Operations in Words Customer reads cover the caller’s customer and reached workspaces. Workspace-addressed reads include every compatible service’s run for that workspace. HQ reads provide staff-wide scope and optional customer or workspace filters. Each group supplies list, count, kind, snapshot and history reads. Snapshots retain steps, attempts and the definition published for the run, while excluding execution handles and row versions. Retry remains an owning workspace operation and cancellation has no Platform route. The contract records every operation’s Submissions exclusion. ## Events and Jobs No business events are declared. The five-minute reconciler reserves one invocation and hosts the additional workspace and website repair paths. Notifying kinds call requester delivery through their settlement work; the only notifying Platform kind is workspace provisioning. ## Consistency Guarantees Transactional submission does not include orchestration start. Version-checked reporting keeps step and summary writes together. Recovery timing depends on successful bounded passes. The corrected-success path can settle failure before its business effect, and requester delivery has neither a single-sender nor guaranteed-retry contract.