Skip to content

CAP-PFM-OPS-003Notify a job’s requester of its outcome

Markdown

CAP-PFM-OPS-003

Notify a job’s requester of its outcome

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

KindCapabilityProduct areaPlatformModuleOperational RecordsRevision1

Read atservices-platform ad3f6a65

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Requesters can learn outcomes without keeping a monitor open.Completed notice records suppress sequential repeat sends, with duplicate-delivery gaps retained as findings.
Surfaces
job
Preconditions
The job registration declares requester notification content.
Postconditions
A job-outcome notice record retains delivery state and any recorded failure explanation.
Constraints
The shared email delivery policy can suppress nonproduction messages while marking the notice handled.
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

Controls

25 controls apply, from the corpus control catalogue.

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

Business Rules

11 rules, 8 to be proved before approval. A rule's product intent is derived from its origin: 11 confirmed by a product decision, the rest inheriting this capability's confirmed.

IdRuleKindEnforced atProvenance
01
Confirmed
A notifying job kind supplies message content while the shared notification flow resolves the recipient and records delivery outcomes.
policyservicedocumented
services-platform:docs/jobs.md#Telling the requester
02must prove
Confirmed
Only the recorded requester receives the notice; jobs without a requester send nothing, and a requester without an address produces a failed notice record.
policyservicetest
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
03must prove
Confirmed
A notice marked delivered or suppressed cannot be claimed again, while pending and failed notices remain claimable and can be delivered more than once.
invariantservice, databasetest
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
04must prove
Confirmed
A subsequent invocation may reclaim a pending or failed notice and attempt delivery again, favoring eventual delivery over a strict once-only guarantee.
policyservice, databasetest
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
05must prove
Confirmed
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.
policyserviceobserved
06must prove
Confirmed
A provisioning failure settled by reconciliation still triggers the requester notice using the reconciled explanation.
policyservicetest
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
07must prove
Confirmed
Job notices link to the corresponding Rhythm HQ page and identify their sending environment.
calculationservicetest
08
Confirmed
Workspace provisioning is the only notifying Platform job kind at this snapshot, and a test explicitly checks that declared set.
policyservicetest
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
09must prove
Confirmed
Notice settings validation refuses delivery when the sending address or console address is absent and names the required configuration.
validationservicetest
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
10
Confirmed
Success and failure notices for the same job use separate outcome identities.
invariantdatabasetest
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
11must prove
Confirmed
Two senders can reclaim the same pending notice, and a message sent before its delivery outcome is stored can be sent again.
no proof recorded yet
invariantservice, databaseobserved

Scenarios

IdGivenWhenThenProvenance
01A success notice has already been recorded delivered.The success-handling path requests the notice again.No further message is sent for that completed notice.inferred
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
02A failure notice remains marked failed after a send error.Another notification attempt reclaims it.The same notice record becomes pending for another delivery attempt.inferred

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.