--- id: DOM-PFM-ELG-005 title: Attention Item realises: CON-PFM-ELG-005 product_area: platform module: eligibility revision: 1 status: draft design_intent: confirmed origin: >- Responsibilities and attention architecture D-01 to D-13 approved by Andrew 2026-10-18 as recommended (PLAT-M15 "Decisions"), in particular D-03 (persisted, provider-written items), D-04 (audiences at read), D-05 (scope chains from providers), D-06 (fixed classes), D-10 (no automatic tasks or messages) and D-13 (service boundary); PLAT-M15 D2 (every staff member reads their own); PLAT-M16 change (reminders through Notifications) and D1 to D3 (2026-10-21) implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-ELG-attention readable_by: [] lifecycle: STATE-PFM-ELG-007 custom_fields: none identity: >- An occurrence has a generated identity plus its declared kind, deduplication key and generation. The key row allows one open occurrence and increments generations while retained; deletion of an idle key permits numbering to restart. attributes: - name: kind kind: reference required: true computed: false notes: >- The application declaration supplies class, wording, typed facts, destinations, actions and permissions, audience and scope kinds, lifecycle policies, settings, examples, priority and standing. - name: about and subject kind: reference required: true computed: false notes: >- Names the business record concerned and its label, with an optional person or organization subject. - name: scope chain kind: collection required: true computed: false notes: >- Stores up to ten provider-supplied scopes from most specific to workspace level. - name: audiences kind: collection required: true computed: false notes: >- Stores one to ten permitted audience references. Teams currently match nobody; escalation adds audiences that provider refreshes preserve. - name: facts and timing kind: collection required: true computed: false notes: >- Stores declared typed facts, optional due and expiry times and destination parameters. - name: standing kind: enum required: true computed: false notes: >- Tracks open, resolved or expired status with opening, confirmation, resolution and escalation times. - name: rank kind: number required: true computed: true notes: >- Computes class and urgency weights, bounded adjustments and age capped at ten days; the sweep refreshes it. - name: surface mask kind: enum required: true computed: true notes: Combines declared surfaces with workspace narrowing. - name: personal response kind: collection required: false computed: false notes: >- Keeps one response per person and occurrence, with independent acknowledgement, snooze, count and dismissal fields and a record version. - name: workspace settings kind: collection required: false computed: false notes: >- Holds per-kind enablement, surfaces, declared values, bounded rank adjustment, wording and lifecycle overrides with a version. - name: personal preferences kind: collection required: false computed: false notes: >- Keeps private hidden kinds up to two hundred entries, plus the current digest and quiet-hour settings that exceed the approved scope. - name: reminders kind: collection required: false computed: false notes: >- Plans rows by occurrence, person, purpose and reminder cadence occurrence, with sent or skipped outcomes. - name: explanation kind: computed required: false computed: true notes: >- Renders existence, audience, permitted-action and lifecycle explanations from declared data in the workspace time zone. relationships: - to: DOM-PFM-ELG-004 cardinality: Multiple occurrences can address the same responsibility area. ownership: >- Attention stores the area reference and resolves its effective holders when read. cross_service: false invariants: - id: INV-DOM-PFM-ELG-005-01 statement: >- A retained key has one open occurrence; generation numbering can restart after fourteen idle months of key cleanup. enforced_at: - database provenance: observed source: >- services-platform:modules/attention/db/attention-item-keys.table.ts; services-platform:modules/attention/services/persistence/items.ts:deleteOrphans - id: INV-DOM-PFM-ELG-005-02 statement: >- Restricted writes check workspace and service ownership and run within the caller’s transaction. enforced_at: - database provenance: observed source: 'services-platform:docs/attention.md#2. The write functions' - id: INV-DOM-PFM-ELG-005-03 statement: >- Item writes validate declared fact types, a workspace-ended scope chain of at most ten and one to ten permitted audiences. enforced_at: - database provenance: observed source: 'services-platform:docs/attention.md#2. The write functions' - id: INV-DOM-PFM-ELG-005-04 statement: Resolved and expired occurrences cannot be reopened in place. enforced_at: - service - database provenance: observed source: 'services-platform:modules/attention/rules.ts:canTransition' - id: INV-DOM-PFM-ELG-005-05 statement: The service refuses dismissal of required attention. enforced_at: - service provenance: observed source: 'services-platform:modules/attention/rules.ts:decideStateAction' - id: INV-DOM-PFM-ELG-005-06 statement: >- Audience membership grants visibility only; record and action permissions remain independently checked. enforced_at: - service provenance: observed source: >- services-platform:modules/attention/services/read/action-permissions.ts:allowedActionPermissions - id: INV-DOM-PFM-ELG-005-07 statement: >- Escalation stamps each occurrence once and preserves original audiences through provider refresh. enforced_at: - service - database provenance: observed source: >- services-platform:modules/attention/services/persistence/items.ts:escalateOverdueItems - id: INV-DOM-PFM-ELG-005-08 statement: >- Existing response rows are locked, and accepted writes advance version and audit atomically; concurrent first inserts lack an absent-row lock and retry. enforced_at: - service provenance: observed source: >- services-platform:modules/attention/services/persistence/states.ts:applyStateAction - id: INV-DOM-PFM-ELG-005-09 statement: Private preferences cannot hide required kinds. enforced_at: - service provenance: observed source: >- services-platform:modules/attention/services/persistence/preferences.ts:putPreferences - id: INV-DOM-PFM-ELG-005-10 statement: >- Database workspace isolation prevents unscoped reads from returning attention. enforced_at: - database provenance: observed source: 'services-platform:docs/attention.md#1. The tables' physical: - platform.attention_definitions - platform.attention_settings - platform.attention_items - platform.attention_item_keys - platform.attention_item_audiences - platform.attention_states - platform.attention_reminders - platform.attention_preferences - platform.attention_evaluation_runs - platform.attention_sweeps - platform.attention_evaluation_jobs - platform.attention_evaluation_job_steps - platform.attention_evaluation_job_events evidence: - >- services-platform at ad3f6a6: modules/attention/db/*.table.ts; rules.ts; reminders.ts; services/persistence/; services/read/; services/sweep/; services/reminders/; services/evaluate/; docs/attention.md; docs/proposals/responsibilities-and-attention/16-decisions.md; docs/milestones/PLAT-M15-home-attention-and-responsibilities.md, PLAT-M16-attention-follow-up-and-tuning.md. - 'react-console at baf6dae: components/attention/; lib/attention/.' --- # Attention Item ## What It Models An attention occurrence presents a condition that needs someone, such as unposted batches or a gap in accountability. ## Identity and Attributes Kinds describe the condition; occurrences retain facts and timing; personal responses remain separate from lifecycle status. ## Relationships Providers own the business records. Responsibilities and Security supply current audience membership. ## Invariants Occurrence uniqueness, generation retention and response concurrency have different guarantees and are stated separately. ## How It Is Stored and Shared Attention owns declarations, occurrences, audiences, settings, responses and follow-up records. Provider functions enforce transactional writes; no custom fields are declared. ## Open Design Questions Reminder audience checks, delivery deduplication, the Notifications boundary and response races remain unresolved. Portal attention stays held.