--- id: DOM-PFM-NOT-005 title: Association Communication realises: CON-PFM-NOT-005 product_area: platform module: notifications revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-NOT-communications readable_by: [] lifecycle: STATE-PFM-NOT-011 custom_fields: none identity: Workspace, submitting service and repeat key derive the request identity. The request and recipient key derive each message identity. Canonical addresses identify active workspace suppressions, and each workspace has at most one sender setting. attributes: - name: queue pointer kind: collection required: true computed: false notes: A small transport row identifies the workspace, request, submitting service, repeat key, purpose and stored request object. Successful queue publication removes it. - name: request object kind: collection required: true computed: false notes: The stored submission preserves content selection, source records, actor, recipients, data, Marketing requirements, attachments and expiry. Request objects expire after thirty days. - name: request outcome kind: enum required: true computed: false notes: The retained outcome explains acceptance, configuration blocking, complete suppression or invalidity, with timing and content references. - name: classification and lane kind: enum required: true computed: true notes: The declared purpose determines transactional or Marketing classification; tests use the test classification. - name: Marketing subscription and unsubscribe targets kind: collection required: false computed: false notes: Marketing requests supply subscription identity and unsubscribe destinations; other purposes reject those fields. - name: recipient message kind: collection required: true computed: false notes: Each recipient has a message with a canonical address, copy settings, rendering mode, optional published version, rendered-body location and expiry. - name: dispatch state kind: enum required: true computed: false notes: Dispatch progress records waiting, provider submission, protection refusal, staff cancellation, expiry or failure. - name: delivery state kind: enum required: true computed: true notes: Provider reports raise delivery status through the precedence order, from unknown through deferral and bounce to complaint. - name: engagement counters kind: collection required: true computed: true notes: Open and click counts retain first occurrence times and separate likely human activity from automated signals. Stored click summaries omit query strings. - name: submission attempts kind: collection required: false computed: false notes: Each provider attempt records its number, outcome and accepted provider reference when available. - name: provider events kind: collection required: false computed: false notes: Monthly provider-event records deduplicate reports by a derived identity and retain diagnostic history. - name: suppression entry kind: collection required: false computed: false notes: Suppression records identify a canonical address, cause, related message and any staff note. Release preserves its time, actor and explanation. - name: sender setting kind: collection required: false computed: false notes: One workspace setting selects domain, address or combined verification and retains the sending address, provider identities, DNS instructions and verification times. - name: lane budgets kind: collection required: true computed: true notes: Account-wide lane rows retain reserved rate shares, token balances, last quota read and Marketing pause state. relationships: - to: DOM-PFM-NOT-004 cardinality: many messages to one version ownership: The communication message retains its template publication reference, and Communications owns both records. cross_service: false - to: DOM-PFM-NOT-003 cardinality: none today ownership: Current association messages do not reference staff inbox notices. cross_service: false invariants: - id: INV-DOM-PFM-NOT-005-01 statement: Dispatch requires a committed pointer; a rollback can leave an unsent request object until its storage expiry. enforced_at: - database - service provenance: test source: services-platform:modules/communications/tests/integration/db/communication-request-submissions.table.integration.spec.js#leaves no queue row behind when the caller’s transaction rolls back - id: INV-DOM-PFM-NOT-005-02 statement: The workspace, submitting service and repeat key identify a single request, and repeat submission returns a duplicate receipt. enforced_at: - database - service provenance: test source: services-platform:modules/communications/tests/integration/services/requests/submit-request.integration.spec.js#is still answered duplicate, because the request object says the id was submitted before - id: INV-DOM-PFM-NOT-005-03 statement: A request object that disagrees with its workspace or request pointer is invalid and produces no send. enforced_at: - service provenance: test source: services-platform:modules/communications/tests/integration/services/storage/communication-objects.integration.spec.js#refuses an object that names another tenant, which is what the grant cannot prevent - id: INV-DOM-PFM-NOT-005-04 statement: A request has at most one message for each recipient key; normal redelivery does not resubmit final messages. enforced_at: - database - service provenance: observed source: services-platform:modules/communications/db/communication-messages.table.ts; services-platform:modules/communications/services/persistence/messages.ts:claimMessageForSubmission - id: INV-DOM-PFM-NOT-005-05 statement: A withheld message records a reason, with final protection decisions made while its dispatch state is settled. enforced_at: - database - service provenance: observed source: services-platform:modules/communications/db/communication-messages.table.ts:communication_messages_withheld_check - id: INV-DOM-PFM-NOT-005-06 statement: All classifications obey address suppression; transactional purposes bypass general contact opt-out only. enforced_at: - service provenance: documented source: services-platform:docs/communications/architecture.md#15. Decisions for Andrew - id: INV-DOM-PFM-NOT-005-07 statement: Reserved demonstration domains are withheld everywhere, and nonproduction delivery is limited to permitted addresses and test mailboxes. enforced_at: - service provenance: test source: services-platform:modules/communications/tests/integration/services/dispatch/reserved-domain-suppression.integration.spec.js#withholds its message with the reserved-domain reason, so the history says why it was not sent - id: INV-DOM-PFM-NOT-005-08 statement: Provider delivery state advances only to a higher precedence independently of dispatch state. enforced_at: - service provenance: observed source: services-platform:modules/communications/db/communication-messages.table.ts:DELIVERY_STATE_PRECEDENCE - id: INV-DOM-PFM-NOT-005-09 statement: Platform rendering requires a pinned publication except for draft tests; caller rendering requires no template version. enforced_at: - database provenance: observed source: services-platform:modules/communications/db/communication-messages.table.ts:communication_messages_caller_rendered_check - id: INV-DOM-PFM-NOT-005-10 statement: Workspace policy and service checks confine requests, messages, bodies, attempts, events and suppressions. enforced_at: - database - service provenance: documented source: services-platform:docs/row-level-security.md#What it covers - id: INV-DOM-PFM-NOT-005-11 statement: A domain-based sender uses an address within the configured domain, and a verified setting retains its first verification time. enforced_at: - database provenance: observed source: services-platform:modules/communications/db/communication-sender-identities.table.ts:communication_sender_identities_address_domain_check - id: INV-DOM-PFM-NOT-005-12 statement: Platform supplies association identity and message reference during rendering and chooses the sending address itself. enforced_at: - service provenance: test source: services-platform:modules/communications/tests/integration/services/communication-reads.integration.spec.js#sets the association over whatever the caller sent under that name, so a caller cannot rename the association physical: - communication_request_submissions - communication_requests - communication_messages - communication_message_attempts - communication_message_events - communication_suppressions - communication_sender_identities - communication_lane_budgets - 'platform-communications- bucket: requests/ and messages/ prefixes' evidence: - 'services-platform at ad3f6a65: modules/communications/db/*.table.ts; services/persistence/{requests,request-submissions,messages,suppressions,sender-identities,lane-budgets}.ts; services/storage/communication-objects.ts.' - 'services-platform at ad3f6a65: docs/communications/architecture.md §4, §7, §8, §11, §18, §20, §21; docs/queued-work.md §5 and §8.' --- # Association Communication ## What It Models An association communication combines a workflow’s e-mail request with recipient messages, provider attempts and later reports. Suppression, sender verification and shared lane capacity belong here because they determine whether each message can be submitted. ## Identity and Attributes Workspace, submitting service and repeat key derive the request identity. The request and recipient key derive each message identity. Canonical addresses identify active workspace suppressions, and each workspace has at most one sender setting. ## Relationships The communication message retains its template publication reference, and Communications owns both records. Current association messages do not reference staff inbox notices. ## 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 An uncertain provider acknowledgement can lead to resubmission after fifteen minutes. A suppression failure after feedback commitment can leave a bounced address eligible. Sending lanes have no workspace fairness policy, and purge ownership for adopted provider identities is unresolved. ## Open Design Questions The module findings retain unresolved authority, recovery and source-boundary questions affecting this object.