--- title: Notifications and Communications Design Examination examined_at: '2026-10-23' examiner: codex branch: agent/platform-notifications-desi-exam-1 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f rhythm-v2-docs: 02fcf6ad8c538d9daa9a89a506a1ae534f5b91d1 counts: design_artifacts: 62 domain_objects: 3 invariants: 33 state_models: 15 states: 81 transitions: 94 workflows: 16 hops: 73 service_contracts: 2 operation_rows: 57 screen_contracts: 6 decision_records: 20 new_findings: 9 new_open_questions: 1 examined_artifacts: - SVC-PFM-NOT-communications - SVC-PFM-NOT-notifications - ADR-PFM-NOT-001 - ADR-PFM-NOT-002 - ADR-PFM-NOT-003 - ADR-PFM-NOT-004 - ADR-PFM-NOT-005 - ADR-PFM-NOT-006 - ADR-PFM-NOT-007 - ADR-PFM-NOT-008 - ADR-PFM-NOT-009 - ADR-PFM-NOT-010 - ADR-PFM-NOT-011 - ADR-PFM-NOT-012 - ADR-PFM-NOT-013 - ADR-PFM-NOT-014 - ADR-PFM-NOT-015 - ADR-PFM-NOT-016 - ADR-PFM-NOT-017 - ADR-PFM-NOT-018 - ADR-PFM-NOT-019 - ADR-PFM-NOT-020 - DOM-PFM-NOT-003 - DOM-PFM-NOT-004 - DOM-PFM-NOT-005 - SCR-PFM-NOT-001 - SCR-PFM-NOT-002 - SCR-PFM-NOT-003 - SCR-PFM-NOT-004 - SCR-PFM-NOT-005 - SCR-PFM-NOT-006 - STATE-PFM-NOT-001 - STATE-PFM-NOT-002 - STATE-PFM-NOT-003 - STATE-PFM-NOT-004 - STATE-PFM-NOT-005 - STATE-PFM-NOT-006 - STATE-PFM-NOT-007 - STATE-PFM-NOT-008 - STATE-PFM-NOT-009 - STATE-PFM-NOT-010 - STATE-PFM-NOT-011 - STATE-PFM-NOT-012 - STATE-PFM-NOT-013 - STATE-PFM-NOT-014 - STATE-PFM-NOT-015 - WF-PFM-NOT-001 - WF-PFM-NOT-002 - WF-PFM-NOT-003 - WF-PFM-NOT-004 - WF-PFM-NOT-005 - WF-PFM-NOT-006 - WF-PFM-NOT-007 - WF-PFM-NOT-008 - WF-PFM-NOT-009 - WF-PFM-NOT-010 - WF-PFM-NOT-011 - WF-PFM-NOT-012 - WF-PFM-NOT-013 - WF-PFM-NOT-014 - WF-PFM-NOT-015 - WF-PFM-NOT-016 verification_metadata_changes: - field: SVC-PFM-NOT-communications.operations[16].permission before: platform.communication-messages.read-content (sensitive) after: platform.communication-messages.read-content - field: SVC-PFM-NOT-communications.operations[20].access before: internal after: system - field: SVC-PFM-NOT-communications.operations[20].permission before: platform.communications.request (system callers only) after: platform.communications.request - field: SVC-PFM-NOT-notifications.operations[15].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[15].permission before: platform.notifications.publish (system callers only) after: platform.notifications.publish - field: SVC-PFM-NOT-notifications.operations[16].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[16].permission before: platform.notifications.publish (system callers only) after: platform.notifications.publish - field: SVC-PFM-NOT-notifications.operations[17].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[17].permission before: hq.notifications.read (staff only) after: hq.notifications.read - field: SVC-PFM-NOT-notifications.operations[18].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[18].permission before: hq.notifications.read (staff only) and an active access grant into the workspace after: hq.notifications.read - field: SVC-PFM-NOT-notifications.operations[19].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[19].permission before: hq.notifications.read (staff only) and an active access grant into the workspace after: hq.notifications.read - field: SVC-PFM-NOT-notifications.operations[20].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[20].permission before: hq.notifications.read (staff only); no access-grant check (FND-PFM-NOT-036) after: hq.notifications.read - field: SVC-PFM-NOT-notifications.operations[21].access before: internal after: system - field: SVC-PFM-NOT-notifications.operations[21].permission before: hq.notifications.operate (staff only, sensitive); no access-grant check (FND-PFM-NOT-036) after: hq.notifications.operate - field: DOM-PFM-NOT-004.invariants[5].provenance before: test after: observed - field: DOM-PFM-NOT-004.invariants[5].source before: services-platform:modules/communications/tests/e2e/templates.e2e.spec.js#refuses a stale version as 409 after: services-platform:modules/communications/services/persistence/templates.ts:updateTemplateDraft; services-platform:modules/communications/services/persistence/templates.ts:publishTemplateDraft; services-platform:modules/communications/services/templates/template-publishing.ts:publishTemplate - field: SCR-PFM-NOT-003.actions[0].operation_id before: getNotificationInstance or getNotificationRequest (through SCR-PFM-NOT-004) after: getNotificationRequest - field: SCR-PFM-NOT-004.permission before: platform.notifications.manage (hq.notifications.read with an active access grant from HQ) after: platform.notifications.manage - field: SCR-PFM-NOT-004.displays[1].source before: getNotificationInstance channel resolution after: getNotificationRequest instances and their channel resolution - field: SCR-PFM-NOT-004.displays[2].source before: getNotificationInstance deliveries; getNotificationDelivery events after: getNotificationRequest instance deliveries and their loaded events - field: SCR-PFM-NOT-004.actions[0].operation_id before: getNotificationDelivery after: 'none: local expansion of loaded events' - field: SCR-PFM-NOT-004.actions[1].operation_id before: getNotificationInstance after: getNotificationRequest - field: SCR-PFM-NOT-005.actions[2].operation_id before: getNotificationInstance (through SCR-PFM-NOT-004) after: getNotificationRequest - field: SCR-PFM-NOT-005.actions[2].permission before: hq.notifications.read after: platform.notifications.manage - field: STATE-PFM-NOT-001.transitions[3].provenance before: test after: observed - field: STATE-PFM-NOT-001.transitions[3].source before: services-platform:modules/notifications/tests/integration/services/registration/register-service-notifications.integration.spec.js#retires a definition the manifest no longer declares, and keeps its row after: services-platform:modules/notifications/services/persistence/definitions.ts:upsertDefinition - field: STATE-PFM-NOT-006.transitions[0].provenance before: test after: observed - field: STATE-PFM-NOT-006.transitions[0].source before: services-platform:modules/notifications/tests/integration/services/persistence/identities.integration.spec.js#spends the challenge after five wrong codes, refusing even the right one after: services-platform:modules/notifications/services/persistence/identities.ts:transitionIdentity - field: STATE-PFM-NOT-014.transitions[0].provenance before: observed after: unknown - field: STATE-PFM-NOT-014.transitions[0].source before: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:provisionSenderIdentity after: rhythm-v2-docs:specs/platform/notifications/FINDINGS.md:FND-PFM-NOT-049 - field: WF-PFM-NOT-006.hops[0].anchor before: services-platform:modules/tenants/services/provisioning/publish-provisioning-alert.ts after: FND-PFM-NOT-049 - field: WF-PFM-NOT-006.hops[0].provenance before: documented after: unknown - field: WF-PFM-NOT-006.hops[0].source before: services-platform:docs/notifications.md#9. Producers after: FND-PFM-NOT-049 - field: WF-PFM-NOT-009.hops[0].anchor before: services-platform:modules/responsibilities/responsibilities-notifications.ts after: FND-PFM-NOT-049 - field: WF-PFM-NOT-009.hops[0].provenance before: documented after: unknown - field: WF-PFM-NOT-009.hops[0].source before: services-platform:docs/notifications.md#9. Producers after: FND-PFM-NOT-049 - field: WF-PFM-NOT-009.hops[1].anchor before: services-platform:modules/responsibilities/services/notices/responsibility-notices.ts after: FND-PFM-NOT-049 - field: WF-PFM-NOT-009.hops[1].provenance before: test after: unknown - field: WF-PFM-NOT-009.hops[1].source before: react-console:acceptance/notifications/playwright/journeys/inbox/NT-ACC-0004.spec.ts#NT-ACC-0004 after: FND-PFM-NOT-049 - field: WF-PFM-NOT-009.hops[2].anchor before: services-platform:aws/cdk/platform.notification-nudgers.ts after: FND-PFM-NOT-049 - field: WF-PFM-NOT-009.hops[2].provenance before: documented after: unknown - field: WF-PFM-NOT-009.hops[2].source before: services-platform:docs/notifications.md#9. Producers after: FND-PFM-NOT-049 - field: WF-PFM-NOT-014.hops[1].anchor before: services-crm:modules/entities/services/organization-type-record/organization-type-record.ts (outside this module's read scope) after: FND-PFM-NOT-049 - field: WF-PFM-NOT-014.hops[1].provenance before: documented after: unknown - field: WF-PFM-NOT-014.hops[1].source before: services-platform:docs/communications/architecture.md#2026-10-09 — Final acceptance after: FND-PFM-NOT-049 - field: WF-PFM-NOT-014.hops[2].provenance before: test after: observed - field: WF-PFM-NOT-014.hops[2].source before: services-platform:modules/communications/tests/integration/services/templates/owned-templates.integration.spec.js#keeps every field the partial content left out after: services-platform:modules/communications/tests/integration/services/templates/owned-templates.integration.spec.js#keeps every field the partial content left out; services-platform:modules/communications/services/templates/owned-templates.ts:mergeContent; services-platform:modules/communications/services/templates/owned-templates.ts:publishIfChanged evidence: - rhythm-v2-docs:AGENTS.md; specs/CONVENTIONS.md sections 6 and 9; specs/templates/; specs/platform/notifications/MODULE.md; specs/platform/notifications/planning/; specs/platform/notifications/FINDINGS.md; specs/platform/RESPONSIBILITIES.md - rhythm-v2-docs:briefs/design/platform-notifications.brief.md (absent at starting commit; FND-PFM-NOT-048) - services-platform:modules/notifications/aws/api/notifications.routes.ts; modules/communications/aws/api/communications.routes.ts; aws/platform.service.ts scoped permission groups - services-platform:modules/notifications/db/*.table.ts; modules/communications/db/*.table.ts; scoped persistence, orchestration, registration, dispatch, feedback, template, sender, lifecycle, queue and schedule declarations - services-platform:docs/proposals/notifications/23-decisions.md; docs/milestones/plans/PLAT-M23-plan.humanized.md; docs/communications/architecture.md sections 16 through 22; docs/standards/custom-field-capability.md; docs/standards/submission-compatible-operations.md - react-console:scoped notification pages, components/notifications, components/console/hq/notifications-history.tsx, components/console/alerts-popover.tsx, lib/notifications and cited acceptance records - 'Boundary exclusions: responsibility producer implementation, workspace provisioning producer implementation, CRM compensation, external package internals and deployment-level caller grants (FND-PFM-NOT-049)' - 'Acceptance: npm ci && npm run check; npm test (four tests passed); no service provider, deployed or integration test execution in this examination' --- # Notifications and Communications Design Examination ## Examination Result The examination covers every design artifact and the notification responsibility row against the pinned source and recorded planning decisions. All readable design prose has been rewritten by OpenAI, with verification corrections committed separately from artifact rewrites. Existing approval and intent values remain unchanged; this examination grants no product approval. The corpus contains three domain objects, fifteen lifecycle models, sixteen workflows, two service contracts, six screen contracts and twenty decision records. Examination covers thirty-three invariants, eighty-one states, ninety-four transitions, seventy-three workflow hops and fifty-seven operation rows. The requested design brief is unavailable, so its additional drafting constraints remain unverified. ## Coverage | Inventory | Coverage | Limit | |---|---|---| | Business HTTP operations | All forty-four explicit notification and communication operations have contract rows. | Contract rows also cover two generated health operations; health operation naming depends on the shared builder contract. | | Internal entry points | Eleven grouped library or IAM rows supplement the HTTP inventory. | External package implementations and deployed caller grants remain outside direct verification. | | Tables | All thirty scoped table declarations are represented across the three objects. | The template-version reference is shared; object count follows active concepts rather than tables. Shared registry and job policy exceptions remain explicit. | | Built screens | Three pages and two sheets have contracts. | The sixth contract describes an unbuilt notification section in the header bell. Association content authoring has no scoped console screen. | | Lifecycle models | Fifteen models cover request, notice, delivery, content, protection, sender, quota and dormant configuration lifecycles. | Reserved vocabulary values are distinguished from states with current writers. | | Workflow and queue topology | Sixteen workflows cover requests, chat, text, transactional sending, Marketing sending, provider feedback, schedules and reconciliation. | The six primary queue families have associated flows; text has no consumer. The reconciliation state machine is covered, while shared lifecycle execution and external producers remain dependency boundaries. | | Inference | Both services, all sixteen workflows and all six screens explicitly carry empty inference lists. | Scoped code makes no model call or named inference task, so no inference operation is required. The charter’s missing no-inference sentence remains a finding outside the permitted editing scope. | Direct source and anchor checks resolve the cited files and symbols within the module boundary. Four apparent text-anchor mismatches come from escaped apostrophes in test titles and resolve to existing tests. Cited tests were read as evidence; their historical passing status does not establish a new runtime result. Sources outside the permitted module boundary remain unknown where the design previously treated producer internals as directly verified. ## Changes by Artifact Every entry below also received final OpenAI text in its required sections. Lifecycle and workflow diagrams describe the verified stored states and hop sequence. | Artifact | Examination change | |---|---| | `ADR-PFM-NOT-001` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-002` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-003` | Corrected the guarantee to a committed queue entry rather than a committed notice or message. | | `ADR-PFM-NOT-004` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-005` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-006` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-007` | Retained the registry scope and documented job-policy exceptions. | | `ADR-PFM-NOT-008` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-009` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-010` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-011` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-012` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-013` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-014` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-015` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-016` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-017` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-018` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-019` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `ADR-PFM-NOT-020` | Rewrote context, decision, alternative reasoning and consequences while preserving its recorded origin and intent. | | `DOM-PFM-NOT-003` | Corrected summary consistency, retained the raw-adapter logging exception to the approved privacy restriction, and clarified the absence of an association-template relationship. | | `DOM-PFM-NOT-004` | Qualified stale and archived publication enforcement; corrected the absence of a relationship to staff notices. | | `DOM-PFM-NOT-005` | Allowed address-only sender setup and clarified message-template ownership without a current staff-notice reference. | | `SCR-PFM-NOT-001` | Rewrote inbox displays, actions, permission patterns and the planned bell entry. | | `SCR-PFM-NOT-002` | Rewrote the explanation, channel outcomes and loading behavior. | | `SCR-PFM-NOT-003` | Mapped opening a History row to the request-chain read. | | `SCR-PFM-NOT-004` | Mapped loaded notice and event data to the request response; made event expansion local and authority workspace-management based. | | `SCR-PFM-NOT-005` | Retained granted HQ list reads but corrected the shared sheet’s request operation and workspace management authority. | | `SCR-PFM-NOT-006` | Clearly separated the proposed notification preview from the built attention-only bell. | | `STATE-PFM-NOT-001` | Replaced the retirement-test citation for reactivation with the observed persistence operation. | | `STATE-PFM-NOT-002` | Rewrote request outcomes, tombstones, withdrawal and settlement without changing the planning rules. | | `STATE-PFM-NOT-003` | Removed the claim that every delivery and notice-summary change shares a transaction. | | `STATE-PFM-NOT-004` | Distinguished bulk archived-item exclusion from allowed individual reading. | | `STATE-PFM-NOT-005` | Rewrote claim, retry, exhaustion, skip and operator-retry behavior. | | `STATE-PFM-NOT-006` | Removed an invented challenge check from dormant activation and changed its evidence to observation. | | `STATE-PFM-NOT-007` | Rewrote the dormant override lifecycle and retained its lack of runtime effect. | | `STATE-PFM-NOT-008` | Removed invented digest-count and window checks from delivery claiming. | | `STATE-PFM-NOT-009` | Qualified publication race protection and described separate owned-save writes. | | `STATE-PFM-NOT-010` | Rewrote acceptance outcomes and object-versus-database failure boundaries. | | `STATE-PFM-NOT-011` | Made the default-on exhausted redrive switch and first-receive guard explicit. | | `STATE-PFM-NOT-012` | Recorded suppression after event commit and qualified bounce and complaint meanings. | | `STATE-PFM-NOT-013` | Qualified suppression timing relative to an already claimed send. | | `STATE-PFM-NOT-014` | Added observed verification recovery and purge transitions; marked initial setting creation unknown. | | `STATE-PFM-NOT-015` | Added immediate pause on the first high-usage quota observation and the below-threshold running guard. | | `SVC-PFM-NOT-communications` | Matched system request access and content-read permission; corrected draft test sending and single HTTP readiness checks. | | `SVC-PFM-NOT-notifications` | Matched system route access and exact permission keys; corrected the notice-summary consistency classification. | | `WF-PFM-NOT-001` | Rewrote registration and the non-retried retirement sweep, retaining its notice-withdrawal gap. | | `WF-PFM-NOT-002` | Rewrote producer commit, dispatch recovery, duplicates and request dead-letter visibility. | | `WF-PFM-NOT-003` | Rewrote acceptance, audience, rendering, folding and replacement with post-commit dispatch recovery. | | `WF-PFM-NOT-004` | Rewrote cancellation ordering, folded ownership and already-sent delivery limits. | | `WF-PFM-NOT-005` | Recorded separately committed outcomes and summary refreshes; retained the missing text consumer. | | `WF-PFM-NOT-006` | Marked the out-of-scope provisioning producer anchor unknown while retaining observed system routing. | | `WF-PFM-NOT-007` | Rewrote nightly scheduling, repair, expiry, retention and partition boundaries. | | `WF-PFM-NOT-008` | Rewrote exhausted-delivery retry and retained the global content-access finding. | | `WF-PFM-NOT-009` | Marked three unverified producer anchors unknown and retained documented composition behavior. | | `WF-PFM-NOT-010` | Rewrote stored request publication, rollback orphaning and purpose-lane dispatch. | | `WF-PFM-NOT-011` | Corrected the claim that the final receive always attempts or fails every remaining draft. | | `WF-PFM-NOT-012` | Rewrote locked token allocation, borrowing and quota-to-mapping recovery limits. | | `WF-PFM-NOT-013` | Corrected event-versus-suppression atomicity and documented the duplicate-event repair gap. | | `WF-PFM-NOT-014` | Marked owner internals unknown; corrected draft merge, separate publication and compensation limits. | | `WF-PFM-NOT-015` | Corrected provisioning to preserve verification and separated existence checking from sender readiness. | | `WF-PFM-NOT-016` | Rewrote reset-versus-purge scope and partial cleanup without inventing pipeline shutdown. | The responsibility row now has valid YAML, names all exposed operation rows exactly, and agrees with the object ownership and consumed provider signals. Its prose describes service boundaries and retained implementation limits. The module index records completion of design examination, while approval remains Andrew’s decision. The frontmatter lists every changed source, provenance, anchor, operation mapping, permission and access value. All Submissions publication values remain unpublished; their reason text is rewritten. Other permanent identifiers, existing source pins, intent values and approval statuses remain intact. New finding and question identifiers were allocated before authoring; the planning artifacts were not edited. ## Open Disagreements | Subject | Finding or question | Preparation consequence | |---|---|---| | Delivery summary recovery | `FND-PFM-NOT-044` | Decide how a failed summary refresh is repaired after delivery commit. | | Feedback protection | `FND-PFM-NOT-045` | Make failed suppression retryable after a duplicate event or approve the observed gap. | | Dormant guards | `FND-PFM-NOT-046` | Assign verification and digest eligibility checks to a real caller before enabling these features. | | HQ diagnostic authority | `FND-PFM-NOT-047` | Decide whether the shared sheet needs an HQ read path or workspace management authority. | | Missing drafting brief | `FND-PFM-NOT-048` | Supply the brief for a later constraint check if it contains additional obligations. | | Producer and registration boundary | `FND-PFM-NOT-049` | Examine producer internals, owner compensation, enabling registrations and deployed grants in their owning modules. | | Owned-save recovery | `FND-PFM-NOT-050` | Choose recovery for draft writes committed before publication and competing owner edits. | | Publication race | `FND-PFM-NOT-051` | Recheck the snapshot and active state under the publication lock before promising concurrent protection. | | Final receive and untouched drafts | `FND-PFM-NOT-052` | Resolve the invocation-budget disagreement with the planning expectation without silently changing that expectation. | | Recovery priorities | `OQ-PFM-NOT-009` | Andrew chooses which corrective work is required before implementation preparation. | Earlier findings remain open: definition retirement does not withdraw notices, raw adapter errors can breach the approved logging restriction, uncertain provider submission can be duplicated, adopted sender deletion can affect another workspace, operator content lacks the normal grant boundary, and some template changes lack actor audit. Recorded decisions about ownership, queue transport, channel boundaries and Submissions publication are cited rather than reopened. Later rendering and Marketing extensions retain their proposed status where product confirmation is absent. ## Validation Dependency installation and corpus conformance pass with zero errors. All four repository tests pass. This examination runs no deployed-provider or service integration suite; runtime evidence remains the code and cited tests, and provider proof remains in the existing findings. ## Verdict for Andrew The corrected design is a faithful account of the scoped implementation, with unresolved dependencies and product disagreements explicitly retained. Its weakest areas are recovery across separate commits, concurrent content publication, and authority at cross-module diagnostic and producer boundaries. Before implementation preparation, decide the required repairs for protection and publication, the HQ diagnostic access path, and which missing producer evidence must be supplied.