---
id: STATE-PFM-ELG-008
title: Personal response to an attention item
object: DOM-PFM-ELG-005
product_area: platform
module: eligibility
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Responsibilities and attention architecture D-06 (required never dismissible),
  approved by Andrew 2026-10-18 (PLAT-M15 "Decisions")
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: unread
    meaning: >-
      An unacknowledged response facet, counted as unread only if other
      visibility rules permit it.
  - name: acknowledged
    meaning: >-
      Acknowledgement is present and retained across snooze and dismissal
      changes.
  - name: snoozed
    meaning: >-
      A future snooze hides the occurrence from normal personal lists without
      clearing acknowledgement or dismissal.
  - name: dismissed
    meaning: >-
      Dismissal hides a nonrequired occurrence for this person; acknowledgement
      can coexist.
transitions:
  - from: unread
    to: acknowledged
    trigger: acknowledgeMyAttentionItem
    guard: Pre-write item read found open status and an audience match.
    side_effects:
      - Lock an existing response row or insert the first row
      - Audit acknowledgement
    who: Staff member
    provenance: observed
    source: >-
      services-platform:modules/attention/services/persistence/states.ts:applyStateAction
  - from: unread
    to: snoozed
    trigger: snoozeMyAttentionItem
    guard: >-
      Pre-write open audience match and future snooze within required limits or
      the ninety-day nonrequired maximum.
    side_effects:
      - Advance snooze count
      - Audit the new snooze
    who: Staff member
    provenance: observed
    source: 'services-platform:modules/attention/rules.ts:decideStateAction'
  - from: acknowledged
    to: snoozed
    trigger: snoozeMyAttentionItem
    guard: Apply the same snooze validation as for an unacknowledged item.
    side_effects:
      - Retain acknowledgement
      - Audit and advance snooze count
    who: Staff member
    provenance: observed
    source: 'services-platform:modules/attention/rules.ts:decideStateAction'
  - from: snoozed
    to: unread
    trigger: Explicit unsnoozeMyAttentionItem or effective snooze expiry
    guard: >-
      Snooze clears or expires, with neither prior acknowledgement nor
      dismissal.
    side_effects:
      - Restore visibility without erasing other facets
      - Audit explicit unsnooze
    who: Staff member or time
    provenance: observed
    source: >-
      services-platform:modules/attention/services/persistence/states.ts:applyStateAction
  - from: unread
    to: dismissed
    trigger: dismissMyAttentionItem
    guard: Pre-write open audience match and nonrequired class.
    side_effects:
      - Retain other response facets
      - Audit dismissal
    who: Staff member
    provenance: observed
    source: 'services-platform:modules/attention/rules.ts:decideStateAction'
  - from: acknowledged
    to: dismissed
    trigger: dismissMyAttentionItem
    guard: Pre-write open audience match and nonrequired class.
    side_effects:
      - Keep acknowledgement while adding dismissal
    who: Staff member
    provenance: observed
    source: 'services-platform:modules/attention/rules.ts:decideStateAction'
  - from: snoozed
    to: acknowledged
    trigger: Explicit unsnoozeMyAttentionItem or effective snooze expiry
    guard: Snooze ends with acknowledgement present and no dismissal.
    side_effects:
      - Restore visible acknowledged standing
    who: Staff member or time
    provenance: observed
    source: >-
      services-platform:modules/attention/services/persistence/states.ts:applyStateAction
invalid:
  - from: unread
    to: dismissed
    why: Required attention rejects dismissal regardless of its unread facet.
  - from: snoozed
    to: snoozed
    why: >-
      A required snooze exceeding duration or count, or a nonfuture end, is
      refused.
  - from: dismissed
    to: unread
    why: >-
      There is no undismiss operation; another occurrence has separate personal
      response storage.
concurrency: >-
  Existing response rows are locked and versioned without a client
  expected-version precondition. Concurrent first inserts can collide without
  retry. Status and audience are read before the write transaction and can race
  closure or reassignment. Snooze expiry is a read-time calculation.
invariants:
  - INV-DOM-PFM-ELG-005-05
  - INV-DOM-PFM-ELG-005-08
evidence:
  - >-
    services-platform at ad3f6a6: modules/attention/rules.ts;
    services/persistence/states.ts; aws/api/attention.routes.ts;
    db/attention-states.table.ts; docs/attention.md §4, §5.
---
# Personal response to an attention item

## The Lifecycle

```mermaid
stateDiagram-v2
  unread --> acknowledged
  unread --> snoozed
  acknowledged --> snoozed
  snoozed --> unread
  unread --> dismissed
  acknowledged --> dismissed
  snoozed --> acknowledged
```

## Transitions Explained

The diagram is a projection of independent acknowledgement, snooze and dismissal fields, not a mutually exclusive state machine. Unsnoozing an acknowledged item leaves it acknowledged; acknowledging a dismissed item does not undo dismissal.

## What Cannot Happen

Required attention rejects dismissal regardless of its unread facet. A required snooze exceeding duration or count, or a nonfuture end, is refused. There is no undismiss operation; another occurrence has separate personal response storage.

## Concurrency and Timing

Existing response rows are locked and versioned without a client expected-version precondition. Concurrent first inserts can collide without retry. Status and audience are read before the write transaction and can race closure or reassignment. Snooze expiry is a read-time calculation.