Files
pipelines/app/notes/synced-attention.md
T

5.0 KiB

Synced attention: clearing on one device clears everywhere

Operator request: "when I clear notifications, it should clear in all places, not only on the web and then I have to clear again on mobile."

What is shared

  • Needs-you dismissals. Dismiss and Clear all in the Needs-you sheet. Each entry's identity is {runId}:{Decision|Failed} (attentionKey).
  • Chat New badges. Opening a chat, and content arriving in the chat this device has open, records a per-session chat_seen watermark in epoch ms.

ntfy notifications already shown on a phone cannot be retracted (see docs/ntfy.md, "Clearing notifications across devices").

Protocol (server, internal/protocol/attention_acks.go)

Direction Envelope
read {"type":"attention_acks"} → {"type":"attention_acks","attention_acks":{"dismissed":[…],"chat_seen":{…}}} (the whole set)
add {"type":"ack_attention","attention_acks":{"dismissed":["42:Failed"],"chat_seen":{"ses_x":1730000000000}}} → same reply (the whole set)
push {"type":"attention_acks_changed","attention_acks":{…}}: only what changed, sent to every other connection

The set only grows: dismissals are added and watermarks only advance. That makes merging a union/max that is safe to apply in any order or twice. Invalid identities, invalid session ids, non-positive times, empty acks and acks with more than 500 items are refused with error, and nothing is written. Dismissals of unknown runs and watermarks for sessions that are not operator sessions are skipped silently. A stored watermark is max(old, client value, operator_sessions.last_used_at).

Storage: two additive SQLite tables, attention_dismissals(key, run_id, dismissed_at) and chat_seen_watermarks(session_id, seen_at, acked_at), created in Store.Open. Each ack prunes rows for deleted runs and sessions, and rows older than 30 days (AttentionAckRetention).

Clear all sends the identities the sheet showed (its snapshot), not a "cleared up to time T" marker. A time marker would hide a run created before T that starts waiting on a person after T. The snapshot keeps the existing "entries that arrive later stay" rule, and the request is bounded to 500 identities per batch.

App

  • features/attention/domain/attention_acks.dart: the value type (merge, without, encode/decode, bounded batches).
  • features/attention/runtime/attention_ack_sync.dart (AttentionAckSync): one per app/gateway, bound with bindAttentionAckSync. It applies local acknowledgements immediately and queues them persistently (attention_ack_queue.dart, SharedPreferences, server-scoped). On every connected transition it flushes the queue and reads the set. It also applies pushed deltas. It sends through the socket's send-only path, so the connect-time read never queues ahead of the first screen's request. A refusal drops the batch. An older server that answers pong keeps the queue and turns syncing off until the next connection, so the local state still applies.
  • AttentionController(sync:): Dismiss and Clear all also acknowledge. Shared identities are unioned into the local set and cached in the existing local store, which acts as the offline copy.
  • ChatSessionsController: looks up the bound sync. Opening a chat stores and acknowledges max(row updated_at, now). A shared watermark newer than this device's own clears the badge and raises the local watermark, so the same acknowledgement cannot later clear newer content. Content arriving in the open chat is acknowledged after 1.5 s of quiet.
  • PipelinesApp creates and binds the sync, loads the queue, and calls connected() on each connection epoch.

The Needs-you sheet layout was not touched.

Known limits

  • The chat watermark compares a device clock with server times, so large clock skew can mis-order a badge.
  • An acknowledgement queued offline for a long time can clear a badge for content that arrived between the offline open and the reconnect.
  • Local dismissals made before this change are not uploaded. Only new dismissals are shared.

Tests

  • Go: internal/pipeline/attention_acks_test.go (persist/reopen, advance-only, unknown skipped, registry lift, prune deleted/expired, malformed refused), internal/server/attention_acks_test.go (two websocket clients: push to the other, no push for malformed/no-op acks), and internal/protocol/attention_acks_test.go.
  • Flutter: test/features/attention/runtime/attention_ack_sync_test.dart (two devices: dismiss, Clear all, late connect, offline queue, restart, refusal, legacy server, send-only path) and test/features/chat/ui/sessions/chat_seen_sync_test.dart (open clears everywhere, an earlier ack never clears later content, open-chat content, and offline open synced on reconnect).

Deployment

The server needs a rebuild and restart to serve the new requests; the tables are created on open. The rebuilt web app and APK also need publishing. Until the server is upgraded, the app keeps working with its local state and its queue.