--- id: DOM-PFM-NOT-003 title: Staff Notification realises: CON-PFM-NOT-003 product_area: platform module: notifications revision: 1 status: draft design_intent: proposed implementation_evidence: partially-observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-NOT-notifications readable_by: [] lifecycle: STATE-PFM-NOT-003 custom_fields: none identity: An application’s permanent key identifies a definition. A submitting service and repeat key derive a request identity, scoped by workspace. A time-ordered notice identity supports paging, while a separate occurrence digest enforces recipient uniqueness across partitions. Each notice has one delivery identity per channel. attributes: - name: definition key, application and release kind: text required: true computed: false notes: The application key identifies the declaration; the recorded release identifies its latest registration. Category and preference mode are fixed for that key. - name: definition classification kind: enum required: true computed: false notes: Nine categories classify staff notices. Severity, preference mode, delivery requirement and audience types use closed vocabularies. - name: supported and default channels kind: collection required: true computed: false notes: Every declaration supports the console. Default channels must be supported; mandatory notices include console and supported e-mail in their defaults. - name: data schema and examples kind: collection required: true computed: false notes: Producer data follows a closed schema. Registration requires one to ten valid examples that exercise the declared wording. - name: localized templates kind: collection required: true computed: false notes: English wording is required. Rendered console titles allow 140 characters, bodies 2,000 and text messages 306. - name: destination and actions kind: collection required: false computed: false notes: A declared destination opens work in the workspace. Up to ten actions can open links, follow routes or name operations with their authority. - name: collapse window, expiry age and replacement scope kind: text required: true computed: false notes: Repeats default to a two-minute collapse window. Requests default to seven-day expiry; replacement can be disabled or tied to an occurrence. - name: definition status kind: enum required: true computed: false notes: The registry retains both active and retired declarations. - name: request envelope kind: collection required: true computed: false notes: The envelope describes the submitting service, repeat key, audience, exclusions, actor, subject, data, timing, replacement and correlation. Stored notification payloads are limited to 32 KB. - name: request outcome kind: enum required: true computed: false notes: Processing records acceptance, empty audience, invalidity, replacement, expiry or cancellation. Problems preserve their field and isolation reason; definition disablement has no current writer. - name: request settlement kind: date required: false computed: false notes: An accepted request remains withdrawable until settlement records the close time. - name: notice content kind: collection required: true computed: false notes: The notice stores rendered content, destination, actions, classification, subject, language and event time. Collapse and withdrawal can revise that content. - name: recipient kind: reference required: false computed: false notes: The person is an eligible console user of the customer. Operational HQ notices in the system workspace have no personal recipient. - name: read and archive instants kind: date required: false computed: false notes: Read and archive timestamps record personal organization independently of delivery progress. Repeating a read preserves its timestamp until an unread action clears it. - name: notice status kind: enum required: true computed: true notes: Channel deliveries determine progress, but some outcomes commit before this summary is refreshed. Withdrawal and expiry preserve their separately assigned terminal states. - name: channel resolution kind: collection required: true computed: false notes: The explanation retains audience selection and chosen or unused channels with their reasons. It also retains the newest fifty collapsed request references. - name: collapsed count kind: number required: true computed: false notes: This counts additional requests represented by the same inbox item. - name: deliveries · events kind: collection required: true computed: false notes: Each channel records an adapter, progress, provider reference and failure or skip reason. Rendered channel content is bounded to 8 KB and delivery history retains the latest fifty events. - name: stored configuration kind: collection required: false computed: false notes: Preferences, workspace settings, overrides, quiet periods, digests, identities, verification challenges and text accounting have persistence support. Current orchestration does not apply them. relationships: - to: DOM-PFM-NOT-005 cardinality: none today; one notice to at most one e-mail message once staff e-mail exists ownership: Association communications owns any future staff e-mail message; notification wording remains part of the staff declaration. cross_service: false - to: DOM-PFM-NOT-004 cardinality: none ownership: Staff notice wording belongs to application declarations; association templates have no current notice reference. cross_service: false invariants: - id: INV-DOM-PFM-NOT-003-01 statement: A producer rollback leaves no dispatchable queue entry; its committed transaction makes that entry available to the dispatcher. enforced_at: - database - service provenance: test source: services-platform:modules/notifications/tests/integration/services/dispatch/dispatch-notifications.integration.spec.js#leaves nothing to claim when the producer’s transaction rolled back, and one row when it committed - id: INV-DOM-PFM-NOT-003-02 statement: A workspace submission is unique by submitting service, repeat key and publish-or-cancel kind; repeated insertion returns the existing identity. enforced_at: - database - service provenance: test source: services-platform:modules/notifications/tests/integration/services/requests/submit-notification-request.integration.spec.js#answers the same request id and a duplicate for a repeat, writing one row - id: INV-DOM-PFM-NOT-003-03 statement: The occurrence key permits no more than one personal notice for the same recipient, including across monthly partitions. enforced_at: - database - service provenance: test source: services-platform:modules/notifications/tests/integration/services/orchestration/orchestrate-request.integration.spec.js#makes one instance for one occurrence however many requests name it - id: INV-DOM-PFM-NOT-003-04 statement: Personal audience resolution retains only active console users of the customer and records refusals for ineligible people. enforced_at: - service provenance: test source: services-platform:modules/notifications/tests/integration/services/orchestration/orchestrate-request.integration.spec.js#drops a user of another customer, an invited user and a portal user, recording isolation_refused - id: INV-DOM-PFM-NOT-003-05 statement: After exclusions, selecting more than two hundred people invalidates the entire audience. enforced_at: - service provenance: test source: services-platform:modules/notifications/tests/unit/audience-planner.spec.js#refuses 201 people as a whole, selecting nobody - id: INV-DOM-PFM-NOT-003-06 statement: Only the Rhythm system workspace accepts a system audience and recipient-free operational notices. enforced_at: - database - service provenance: test source: services-platform:modules/notifications/tests/integration/services/system/system-audience.integration.spec.js#is refused in a customer’s tenant as audience_kind_not_allowed, even for a definition that declares it, and nothing is made - id: INV-DOM-PFM-NOT-003-07 statement: Ordinary delivery transitions cannot reopen a final status, and the guarded send claim admits only one racing consumer. enforced_at: - service - database provenance: test source: services-platform:modules/notifications/tests/integration/services/persistence/deliveries.integration.spec.js#never moves a delivery out of a final status - id: INV-DOM-PFM-NOT-003-08 statement: The unread view and totals exclude read, archived and no-longer-applicable notices. enforced_at: - service provenance: test source: services-platform:modules/notifications/tests/integration/services/centre/notification-centre.integration.spec.js#leaves out a notification that no longer applies - id: INV-DOM-PFM-NOT-003-09 statement: Workspace policy confines notification records and configuration; definitions are shared and job storage has its own policy exceptions. enforced_at: - database provenance: test source: services-platform:modules/notifications/tests/unit/registry-tables.spec.js#exempts exactly the catalog among the module’s tables as a tenantless registry, with a reason - id: INV-DOM-PFM-NOT-003-10 statement: Registration preserves a key’s category and preference mode and retains retired declarations for history. enforced_at: - service provenance: test source: services-platform:modules/notifications/tests/integration/services/registration/register-service-notifications.integration.spec.js#refuses a category that changes between releases, telling the owner to re-key the definition - id: INV-DOM-PFM-NOT-003-11 statement: The approved logging policy excludes content, addresses and secrets; rendered request links are redacted, but raw adapter exception logging remains a known breach risk. enforced_at: - service provenance: documented source: services-platform:docs/milestones/plans/PLAT-M23-plan.humanized.md#PLAT-M23-S16 - id: INV-DOM-PFM-NOT-003-12 statement: Collapse locks matching recipient, definition, subject and scope identities so concurrent repeats produce a single folded notice. enforced_at: - database - service provenance: test source: services-platform:modules/notifications/tests/integration/services/orchestration/cancel-and-supersede.integration.spec.js#folds ten requests dispatched at the same moment into one notification of collapsed count nine physical: - notification_definitions - notification_submissions - notification_requests - notification_instances - notification_instance_keys - notification_deliveries - notification_delivery_events - notification_delivery_work - notification_channel_settings - notification_definition_settings - notification_template_overrides - notification_preferences - notification_user_settings - notification_channel_identities - notification_sms_verifications - notification_sms_usage - notification_digests - notification_reconcile_jobs - notification_reconcile_job_steps - notification_reconcile_job_events evidence: - 'services-platform at ad3f6a65: modules/notifications/db/*.table.ts (twenty tables), notifications.settings.ts (closed lists), instance-status.ts, services/persistence/{requests,instances,deliveries,submissions}.ts, services/orchestration/orchestrate-request.ts.' - 'services-platform at ad3f6a65: docs/notifications.md §1 to §7; docs/proposals/notifications/23-decisions.md (D-03, D-04, D-05, D-12); docs/milestones/plans/PLAT-M23-plan.humanized.md §2, §4 and §7a.' - 'services-platform at ad3f6a65: docs/persistence.md, docs/partitions.md, docs/jobs.md, docs/indexing.md, docs/row-level-security.md and docs/queued-work.md as the standards the mechanisms follow.' --- # Staff Notification ## What It Models A staff notification records an application announcement and the people it reaches. The design groups application declarations, committed requests, personal notices and channel deliveries under one owner. Stored preferences and delivery configuration are facets of the same object, but they are dormant in this release. ## Identity and Attributes An application’s permanent key identifies a definition. A submitting service and repeat key derive a request identity, scoped by workspace. A time-ordered notice identity supports paging, while a separate occurrence digest enforces recipient uniqueness across partitions. Each notice has one delivery identity per channel. ## Relationships Association communications owns any future staff e-mail message; notification wording remains part of the staff declaration. Staff notice wording belongs to application declarations; association templates have no current notice reference. ## Invariants The invariant rows identify the guarantees supported by the cited evidence and the layer enforcing each one. They retain implementation gaps rather than treating intended behavior as complete enforcement. ## How It Is Stored and Shared Retirement settles requests without withdrawing their notices or queued deliveries. Unprocessed requests can dead-letter without appearing in History, and committed delivery outcomes can leave stale notice summaries. Reserved HQ scope, operator content access and future preference activation still need the recorded product decisions. ## Open Design Questions The module findings retain unresolved authority, recovery and source-boundary questions affecting this object.