--- id: WF-PFM-OPS-007 title: Answer job reads across every service product_area: platform module: operations revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] trigger: 'A customer, workspace or HQ monitor requests a job list, count, kinds, snapshot or events.' source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 implements: - CAP-PFM-OPS-005 - CAP-PFM-OPS-006 - CAP-PFM-OPS-007 moves: [] crosses: - SVC-PFM-OPS-jobs idempotency: The reads do not alter any owning service’s job records. concurrency: >- Each service schema is queried independently. Ordered pages are merged under a shared cursor without a common cross-service snapshot. hops: - 'n': 1 actor_or_service: Jobs API action: 'Resolve customer reach, the path-selected workspace or staff-wide scope and permitted staff filters.' anchor: 'services-platform:modules/jobs/services/scope/job-read-scope.ts:resolveJobRead' seam: sync on_failure: Return no scope for inadmissible filters or refuse entry to an unreached workspace. left_inconsistent: No job records are changed by scope resolution. observer: Response is the observation surface. provenance: test source: >- services-platform:modules/jobs/tests/e2e/jobs-tenant-runs.e2e.spec.js#is refused a tenant of the same customer the grant does not name - 'n': 2 actor_or_service: Jobs API action: >- Discover schemas publishing every required root, step and event column, and cache the catalogue in the process. anchor: 'macroservice-libraries:packages/jobs/src/persistence/job-view-schemas.ts' seam: sync on_failure: Exclude incomplete publishers; reset discovery on a discovery-query error. left_inconsistent: A publisher added later may remain invisible to the existing process. observer: None. provenance: test source: >- services-platform:modules/jobs/tests/integration/services/snapshots/cross-service-jobs.integration.spec.js#does not find a schema that holds the same job and publishes no view - 'n': 3 actor_or_service: Jobs API action: 'Read compatible views with caller scope and workspace context as applicable, then merge ordered results.' anchor: 'services-platform:modules/jobs/services/persistence/jobs.ts' seam: sync on_failure: Propagate a query error for the whole requested answer. left_inconsistent: No owning records are changed by a failed read. observer: Response is the observation surface. provenance: test source: >- services-platform:modules/jobs/tests/integration/services/snapshots/cross-service-jobs.integration.spec.js#pages across the two macroservices, the cursor of one continuing into the other - 'n': 4 actor_or_service: Jobs API action: >- Resolve subject wording, kind labels and application; enrich HQ snapshots with readable related names and use the run’s published definition. anchor: 'services-platform:modules/jobs/services/snapshots/job-snapshots.ts' seam: sync on_failure: Keep an unnamed fallback when related business records are absent. left_inconsistent: Presentation can lack a related name while retaining the job account. observer: Response is the observation surface. provenance: test source: >- services-platform:modules/jobs/tests/integration/services/subjects/job-subject.integration.spec.js#names the subject null, and still answers it, for a tenant that no longer reads branches: - condition: A kind no schema publishes path: >- An unknown well-formed kind gives empty list and count answers or a missing single job; invalid kind syntax is rejected. waits: [] evidence: - >- services-platform at ad3f6a6: modules/jobs (aws/api/jobs.routes.ts, services/scope, services/persistence/jobs.ts, services/snapshots, services/subjects, services/kinds/job-kind-labels.ts, db/cross-job-query.view.ts); docs/jobs.md §5. - >- macroservice-libraries at 54536a4: persistence/job-view-schemas.ts, cross-job-query.view.ts, cross-job-history.views.ts, api/job-scope.ts, api/job-wire.ts. - >- 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-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-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Answer job reads across every service ## What It Does The jobs API combines compatible owner-published views so one monitor can display work from multiple services. Platform applies audience reach and merges the results without changing the owner’s records. Root, step and event views form the publishing contract. ## The Flow ```mermaid flowchart TD H0["Resolve customer reach, the path-selected workspace or staff-wide scope and permitted staff filters."] H1["Discover schemas publishing every required root, step and event column, and cache the catalogue in the process."] H0 --> H1 H2["Read compatible views with caller scope and workspace context as applicable, then merge ordered results."] H1 --> H2 H3["Resolve subject wording, kind labels and application; enrich HQ snapshots with readable related names and use the run’s published definition."] H2 --> H3 ``` ## When Something Fails Incomplete publishers are excluded rather than returning a partial view shape. Failed discovery is eligible for a later discovery attempt, but successful discovery stays cached. A schema query failure fails the answer. Missing related records retain an unnamed subject, and jobs outside scope read as absent. ## Open Design Questions New publishing services can remain missing in existing processes until fresh discovery; this visibility limit remains recorded.