X1 — Notifications — Session Card

Module: X1 Notifications · Type: cross-cutting X-module (not one of the 8 protocol engines) Closes: Divergence #3 (Notification Center working on iOS, entirely missing on Android) Planning artifact only — no production code. Read alongside docs/plan/13-execution-modules-and-sessions.md (the framework this card implements), 03-protocol-engines.md, 04-backend-togo.md, 12-legacy-reference-map.md, 02-platform-divergences.md, and the relevant platform PRD (05 web, 06 chrome, 07 apple, 08 android, 09 desktop, 11 mcp).

Purpose

X1 builds the notification stack end-to-end: the backend decides what to notify and when (server-side, from Protocol Engine hooks and windows — never a client), stamps notification_items rows that carry a message key plus a vars JSON blob beside the sentence (never interpolated server-side, because Arabic reorders), routes each item through a per-user SSE hub that suppresses push when a live stream is already open, and — critically — finally wires actual delivery that the legacy build never shipped: FCM for Android/Chrome, APNs for Apple, backed by device-token storage. Every client then renders a notification center and handles its platform's push/local-scheduling in a thin, presentation-only way. This is the module that turns "we compute alerts but never deliver them" into working smart alerts across every surface, and it closes Divergence #3 by giving Android the full notification infrastructure it has always lacked.

Feature parameters relevant to this module (exact — do not invent)

Notification rules & routing (legacy precedents — PENDING ratification, not spec-fixed; reuse notify.go / internal/notifier/ / internal/realtime/route.go as reference, do not port wholesale):

• In-process sweeper cadence: 15-minute sweep (legacy internal/notifier/).
• Notice rules: caffeine-window-opened alert 20 min; GERD/shutdown warning 30 min; weigh-in prompt only 07:00–11:00; one notice per kind per user per local calendar day.
• Routing decision (internal/realtime/route.go precedent): live SSE stream open → suppress push; else most-recent device within a 12-hour window → primary device → none — every decision carries a Reason.
• Content: notification_items store the source sentence + vars JSON separately; the client does ICU rendering. Never interpolate server-side.
• Delivery targets: FCM (Android + Chrome), APNs (Apple). Legacy registered no FCM/APNs tokens — delivery is net-new here.

Underlying engine constants that generate notifications (owned by the engines, NOT recomputed here — X1 only fans them out):

• Hydration: 250 ml units, 5000 ml/day max, 30-second cooldown.
• Caffeine Block: no caffeine first 90 minutes post-wakeup.
• GERD Window: 4-hour pre-sleep window (water, chamomile, anise only).
• Medication Grace: 60-minute window.
• Trigger Families: categorical Gout / IBS-GERD / Fatty Liver (Safe vs Trigger-bearing).
• Cycle: 3 consecutive logged cycles before predicting; fails safe on irregularity.
• Kinetic Pomodoro (legacy precedent, PENDING ratification): 25 min work / 5 min short break / 15 min long break / long break every 4 cycles / daily target 8.

Color / i18n (strict): alerts render #FF3333 red glow in dark (#1A1A1A bg); light-mode alert red is genuinely undefined — PENDING DESIGN. All strings ICU Message Format, en/ar, full Arabic RTL (mirrored), no concatenation.

Session table

Surface order within the module (doc 13 §4): backend → web → mcp → chrome → apple → android → desktop. Backend must land before any client session. The backend cell is split into two clearly-bounded slices (doc 13 §1: "when a cell is too big, one clearly-bounded slice of it") because delivery is externally blocked on credentials only Fady can supply.

Session ID	Surface	Scope (this one session builds)	Entry deps	Done criteria (doc 13 §5 template)	Plan docs to read
S-<date>-X1-backend-01-NN	backend	Notification core. Notifications plugin/subscriber registered on the kernel hook bus; rules that react to engine hooks (entry.logged, engine window transitions) + in-process 15-min sweeper producing notification_items rows (message key + vars JSON stored beside the sentence, never interpolated; read-state; engine/kind; user_id). Per-user SSE hub (resource-name events, no state → clients refetch) + push-suppression routing (live stream open → suppress; else most-recent device 12h → primary → none, each with a Reason). Actual push send is stubbed here (a routing decision only), landed in backend-02. Endpoints: GET /api/v1/notifications (list unread), PATCH /api/v1/notifications (mark read).	M0.1–M0.4 (foundation backend); M1 Hydration backend (needs at least one engine emitting hooks/entries to notify on — doc 13 §4 "X1 after M1 exists")	Backend-engine template: plugin registered on kernel; migration expand-contract, every column NOT NULL with a default; endpoints return computed state; unit tests encode every reused notice/routing constant literally (15-min sweep, one-per-kind-per-day, 12h device window, suppress-on-live-stream) and pass; integration test vs real Postgres (idempotent sweep replay, dedup races, suppression decision); no notification/routing constant leaks outside the plugin core/.	13, 04, 03, 12, 02
S-<date>-X1-backend-02-NN	backend	Actual delivery (net-new). device_tokens storage + register/deregister endpoints (POST/DELETE /api/v1/devices/token); FCM adapter (Android/Chrome) + APNs adapter (Apple) driven by backend-01's routing decision; credentials (Firebase project + google-services.json; APNs auth key) loaded from the secrets vault, not code. Turns the backend-01 "suppress vs. push" decision into a real send.	backend-01; EXTERNAL: Fady must supply the Firebase project / google-services.json / APNs key (secrets vault) — likely opens blocked until then	Backend-engine template + a delivery smoke-check: device_tokens migration expand-contract, every column NOT NULL+default; register/deregister endpoints owner-scoped (foreign token 404 not 403); a documented end-to-end send to a real FCM + APNs token succeeds once credentials exist; no secret in code/logs.	13, 04, 10, 02, 12
S-<date>-X1-web-01-NN	web	Notification center slide-over + unread badge. Renders ['notifications'] from /api/v1/notifications, mark-as-read PATCH, unread count badge; ICU-renders vars beside the sentence; browser Notification API accessed only through the web platform adapter (so Electron can substitute). Consumes the SSE hub for live invalidation (falls back to refetch-on-focus).	backend-01; M0.5–M0.7 (web shell, theme engine, i18n engine); M1 web (card pattern)	Client-engine template: renders server notification state and submits mark-read intent only; thin-client/SSOT audit passes (no rule/window/timing logic client-side — grep finds no protocol constant); both themes render per color spec (#FF3333 glow dark; light alert = PENDING DESIGN); Arabic RTL mirrors; strings ICU, none concatenated.	13, 05, 01, 02, 12
S-<date>-X1-mcp-01-NN	mcp	list_notifications tool. Returns unread notification items verbatim from GET /api/v1/notifications via personal-access-token auth.	backend-01; M0.8 (mcp skeleton)	MCP template: tool calls the real API with PAT auth, returns server state verbatim, holds no protocol logic and no AI keys; excluded tools stay excluded (no complete_break, no notification-creation tool — MCP reads notifications, never fabricates them).	13, 11, 04
S-<date>-X1-chrome-01-NN	chrome	chrome.notifications from the service worker. SW polls/subscribes, raises chrome.notifications, renders unread badge, honors server-side notification prefs (GET/PUT /prefs/notifications, cached for display only). Web Push/FCM registration + token handling depends on backend-02.	backend-01 (list/prefs) + backend-02 (for push/token registration); chrome M0/M1 baseline	Client-engine template: SW renders server-emitted notifications and submits mark-read/token intents only; thin-client audit passes (no timing/rules in SW); ICU-rendered content, Arabic included; no protocol constant in extension code.	13, 06, 02, 12
S-<date>-X1-apple-01-NN	apple	Notification center screen + local schedulers + push handling. Renders the notifications list; schedules LOCAL notifications at server-provided fire times (mine the legacy 11 local notification schedulers for structure, not logic — fire times come from the API, never derived locally); APNs registration + token push to backend-02; foreground/background push handling.	backend-01 + backend-02 (APNs); apple M0/M1 baseline	Client-engine template: renders server notification state, schedules only at server-provided times, submits mark-read/token intents only; thin-client audit passes (no window/timing derivation in Swift); both themes; Arabic RTL mirrors; ICU strings, none concatenated.	13, 07, 02, 12
S-<date>-X1-android-01-NN	android	FULL notification infrastructure (Divergence #3 — entirely missing in legacy). core/notifications: NotificationManager + channels partitioned by engine concern; WorkManager/AlarmManager exact local alarms armed from the backend notification schedule (fire under Doze); notification center screen; FCM registration + token push to backend-02; fan-out to handheld (Wear/Auto consume the same layer).	backend-01 + backend-02 (FCM); android M0/M1 baseline	Client-engine template + explicit Divergence #3 closure: renders server notifications, arms alarms at server-provided instants only, submits mark-read/token intents; thin-client audit passes (no rules/windows in Kotlin); scheduled reminders fire under Doze at server instants; both themes on a physical device; full Arabic RTL; ICU strings, none concatenated; channel taxonomy stubbed (names PENDING DESIGN).	13, 08, 02, 12
S-<date>-X1-desktop-01-NN	desktop	Native OS notifications with the window closed. Electron main-process OS notifications via the platform adapter (substituting the web adapter), working when the main window is closed/tray-only; reuses the web notification-center components for the in-app inbox.	backend-01; X1-web-01 (reuses components); desktop M0/M1 baseline	Client-engine template: renders server notifications, submits mark-read intent only; OS notification path goes through the platform adapter (no browser Notification in shared code); thin-client audit passes; both themes; Arabic RTL; ICU strings, none concatenated; notification copy/iconography PENDING DESIGN.	13, 09, 05, 02

Notes & gotchas

• Legacy precedents worth reusing (reference only — greenfield rebuild, nothing ported wholesale): notify.go rules and cadences (20-min caffeine, 30-min GERD, 07:00–11:00 weigh-in, one-per-kind-per-day); the internal/notifier/ 15-min sweeper; the internal/realtime/route.go suppression ladder (live SSE → most-recent device 12h → primary → none, each with a Reason); the iOS 11 local notification schedulers (structure to mine for apple-01, fire times still come from the server); the notification_items + vars-beside-the-sentence pattern. All of these are PENDING ratification, not spec-fixed — treat as candidate answers, confirm before coding.
• Liability to avoid (root cause of the divergences): never let a client compute what/when to notify. The engines emit; X1 fans out. vars are stored beside the sentence and rendered by the client's ICU catalog — do not interpolate server-side (Arabic reorders). A single grep for protocol constants must find nothing in any client notification code.
• The delivery gap is the whole point: legacy computed routing but registered no FCM/APNs tokens, so nothing was ever delivered. backend-02 is where that finally ships — and it is the one session gated on an external human dependency (Fady's Firebase project / google-services.json / APNs key). Expect backend-02 to open blocked; all client push-handling can be scaffolded against backend-01's list/SSE surface, with real end-to-end push verified only once backend-02 unblocks.
• This module resolves a standing open question: docs 02/05/06/08/09 all flagged "push provider / push-vs-poll unspecified." X1 fixes it: per-user SSE for live suppression + FCM/APNs for push. Update those open-question lists when backend-01/02 land.
• PENDING DESIGN (do not invent): notification-center UI, alert grouping, and in-app inbox presentation (all surfaces); Android channel taxonomy and user-facing channel names; desktop notification copy/iconography; light-mode alert red (genuinely undefined in the color spec); Auto/handheld "upcoming constraint" lead times (proposed backend-configured).
• PENDING ratification (not design): the reused legacy notice timings and Pomodoro intervals above — carry them as defaults, flag for Fady's sign-off.
• Ordering: backend-01 requires M1 (Hydration) backend to exist so there is a real engine emitting hooks to notify on (doc 13 §4). Within the module keep surface order backend → web → mcp → chrome → apple → android → desktop.

Handoff reminder

At the end of every X1 session: write one session-handoff memory to the healthdebug brain — retain the content in the doc 13 §6 structure, then memory/edit to attach metadata (category=session-handoff, plus project=healthdebug, module=X1, surface, status, next, era=greenfield, status(record)=current, title, tags). Use a unique source_ref: handoff/X1-notifications/<surface>/<n> (never reuse — reuse supersedes). Then update the single build-ledger memory (source_ref: build-ledger, edited in place) so one recall shows the whole frontier and the recommended next session. Any architectural decision or new open question also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc. See doc 13 §6 and docs/brain/BRAIN-INDEX.md.