--- id: CAP-PFM-OPS-003 title: Notify a job’s requester of its outcome feature: FEAT-PFM-OPS-01 product_area: platform module: operations revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 intent_sources: - 'services-platform:docs/hq/rhythm-hq-plan.md#D11 (approved K8, 2026-10-11)' - 'services-platform:docs/hq/rhythm-hq-plan.md#E5' purpose: Let requesters learn the outcome of selected background work without continuously watching it. outcomes: - Requesters can learn outcomes without keeping a monitor open. - >- Completed notice records suppress sequential repeat sends, with duplicate-delivery gaps retained as findings. concepts: - CON-PFM-OPS-001 actors: - ACT-PFM-004 - ACT-PFM-006 surfaces: - job preconditions: - The job registration declares requester notification content. postconditions: - A job-outcome notice record retains delivery state and any recorded failure explanation. permissions: [] rules: - id: BR-CAP-PFM-OPS-003-01 proved_by: [] statement: >- A notifying job kind supplies message content while the shared notification flow resolves the recipient and records delivery outcomes. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/jobs.md#Telling the requester' origin: 'services-platform:docs/hq/rhythm-hq-plan.md#D11' - id: BR-CAP-PFM-OPS-003-02 proved_by: [ATS-PFM-OPS-003-01] statement: >- Only the recorded requester receives the notice; jobs without a requester send nothing, and a requester without an address produces a failed notice record. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/jobs/tests/unit/services/notices/job-notice-email.spec.js#is addressed to the requester alone: the notice is about their own job origin: 'services-platform:docs/hq/rhythm-hq-plan.md#D11' - id: BR-CAP-PFM-OPS-003-03 proved_by: [ATS-PFM-OPS-003-02, ATS-PFM-OPS-003-11, ATS-PFM-OPS-003-13, TST-PFM-OPS-071] statement: >- A notice marked delivered or suppressed cannot be claimed again, while pending and failed notices remain claimable and can be delivered more than once. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-platform:modules/jobs/tests/integration/services/persistence/job-notices.integration.spec.js#answers nothing at all to the second claim, so nothing is sent twice origin: 'services-platform:docs/hq/rhythm-hq-plan.md#E5' - id: BR-CAP-PFM-OPS-003-04 proved_by: [ATS-PFM-OPS-003-03, ATS-PFM-OPS-003-11, TST-PFM-OPS-071] statement: >- A subsequent invocation may reclaim a pending or failed notice and attempt delivery again, favoring eventual delivery over a strict once-only guarantee. kind: policy enforced_at: - service - database must_prove: true provenance: test source: >- services-platform:modules/jobs/tests/integration/services/persistence/job-notices.integration.spec.js#is claimed again, because a notice nobody received is worse than one that arrives twice origin: none - id: BR-CAP-PFM-OPS-003-05 proved_by: [ATS-PFM-OPS-001-16, ATS-PFM-OPS-003-04] statement: >- Notification failure does not fail the job: the notice records a truncated error description, the failure is logged, and no exception reaches the job flow. kind: policy enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/jobs/services/notices/notify-job-requester.ts:notifyJobRequester' origin: none - id: BR-CAP-PFM-OPS-003-06 proved_by: [ATS-PFM-OPS-002-09, ATS-PFM-OPS-003-05, ATS-PFM-OPS-003-08, ATS-PFM-OPS-003-09, ATS-PFM-OPS-004-11, TST-PFM-OPS-119] statement: >- A provisioning failure settled by reconciliation still triggers the requester notice using the reconciled explanation. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/tenants/tests/integration/lifecycle/reconciled-job-failure.integration.spec.js#tells the staff member who asked for the tenant that it failed, though no task of the job ever ran origin: 'services-platform:docs/hq/rhythm-hq-plan.md#D11' - id: BR-CAP-PFM-OPS-003-07 proved_by: [ATS-PFM-OPS-003-06, TST-PFM-OPS-079] statement: Job notices link to the corresponding Rhythm HQ page and identify their sending environment. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/jobs/tests/unit/services/notices/job-notice-email.spec.js#is the job’s own page in Rhythm HQ, by kind and id origin: 'services-platform:docs/hq/rhythm-hq-plan.md#D11' - id: BR-CAP-PFM-OPS-003-08 proved_by: [] statement: >- Workspace provisioning is the only notifying Platform job kind at this snapshot, and a test explicitly checks that declared set. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-platform:modules/jobs/tests/unit/services/notices/job-notice-email.spec.js#is exactly the list this guard names, so a new kind’s silence is a decision and not an omission origin: none - id: BR-CAP-PFM-OPS-003-09 proved_by: [ATS-PFM-OPS-003-10, TST-PFM-OPS-079] statement: >- Notice settings validation refuses delivery when the sending address or console address is absent and names the required configuration. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/jobs/tests/unit/services/notices/job-notice-email.spec.js#refuses to send at all when the sending address is unset, naming both variables origin: none - id: BR-CAP-PFM-OPS-003-10 proved_by: [ATS-PFM-OPS-003-12, TST-PFM-OPS-071] statement: Success and failure notices for the same job use separate outcome identities. kind: invariant enforced_at: - database must_prove: false provenance: test source: >- services-platform:modules/jobs/tests/integration/services/persistence/job-notices.integration.spec.js#are separate notices, because the unique key is the job and the outcome together origin: 'services-platform:docs/hq/rhythm-hq-plan.md#E5' - id: BR-CAP-PFM-OPS-003-11 proved_by: [] statement: >- Two senders can reclaim the same pending notice, and a message sent before its delivery outcome is stored can be sent again. kind: invariant enforced_at: - service - database must_prove: true provenance: observed source: 'services-platform:modules/jobs/services/persistence/job-notices.ts:claimJobNotice' origin: none scenarios: - id: SC-CAP-PFM-OPS-003-01 given: A success notice has already been recorded delivered. when: The success-handling path requests the notice again. then: No further message is sent for that completed notice. provenance: inferred source: >- services-platform:modules/jobs/tests/integration/services/persistence/job-notices.integration.spec.js#answers nothing at all to the second claim, so nothing is sent twice note: >- This illustrative example combines behavior established by the cited test and the capability’s implementation evidence; it is not an independently bound end-to-end proof. - id: SC-CAP-PFM-OPS-003-02 given: A failure notice remains marked failed after a send error. when: Another notification attempt reclaims it. then: The same notice record becomes pending for another delivery attempt. provenance: inferred source: >- services-platform:modules/jobs/tests/integration/services/persistence/job-notices.integration.spec.js#may be claimed again, so a failed send is tried once more note: >- This illustrative example combines behavior established by the cited test and the capability’s implementation evidence; it is not an independently bound end-to-end proof. edge_cases: [] constraints: - The shared email delivery policy can suppress nonproduction messages while marking the notice handled. depends_on: - CAP-PFM-OPS-001 related: - CAP-PFM-OPS-002 - CAP-PFM-SEC-003 journeys: - JNY-PFM-OPS-002 open_questions: - OQ-PFM-OPS-002 evidence: - >- services-platform at ad3f6a6: modules/jobs/services/notices/notify-job-requester.ts, job-notice-email.ts; services/persistence/job-notices.ts; db/job-notices.table.ts; job-notices integration and job-notice-email unit suites; docs/jobs.md "Telling the requester"; docs/hq/rhythm-hq-plan.md §D11, §E5. - 'services-platform at ad3f6a6, tables named by this capability: job-notices.table.ts.' - >- Examination: proposed acceptance matrices retain candidate test references; incomplete proof is recorded by FND-PFM-OPS-028. controls: [TC-AVL-001, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-006, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-OPS-01-02, FAS-PFM-OPS-01-05] suites: [TST-PFM-OPS-071, TST-PFM-OPS-079, TST-PFM-OPS-119] --- # Notify a job’s requester of its outcome ## Purpose Let requesters learn the outcome of selected background work without continuously watching it. ## How It Works The declaring job kind provides the content of the message. The platform looks up the requester recorded on the job and resolves their current address. It obtains a notice record before attempting delivery. A previously completed notice suppresses an ordinary repeat send. An unfinished notice can be attempted again, which creates a duplicate-delivery risk during concurrent sending or an interrupted outcome write. Sending errors are recorded and logged without changing the job result. Provisioning failure notices also run from reconciliation, reaching requesters whose execution never began. The product should resolve the delivery guarantee before describing these messages as strictly once-only. ## Relationships The job record supports reconciliation, notices and both monitors; owning modules retain responsibility for the work itself.