M2 — Caffeine Block · Session Card

Planning artifact. A build session opens this file (plus the brain — see §5 Handoff) to know exactly what its cell is, what must exist first, and when it is done. One session builds one (module × surface) cell. Surface order is fixed: backend → web → mcp → chrome → apple → android → desktop (doc 13 §3–§4). The backend session MUST land before any client session for this module.

Purpose

The Caffeine Block engine enforces the protocol rule that no caffeine is consumed during the first 90 minutes after waking (the cortisol-window habit for desk professionals). It is its own ToGO plugin: a pure core/ state machine (AwaitingWake → Blocked → Clear) plus plugin.go registration, a schema migration, and endpoints. The backend is the Single Source of Truth for the 90-minute countdown; every client only renders server state (block active/clear, server-provided deadline) and submits log/wake intents. Classification of a logged drink as clean vs. sugar-based is decided server-side against a drink registry (a DB resource carrying is_sugar_based); clients never categorize. Consistent with Core Opinion 1 the engine is categorical — it records a drink by kind, never milligrams — and consistent with Core Opinion 2 a violation is stated as a protocol fact ("caffeine during block window"), never a physiological claim, and any AI commentary defers to "Consult your doctor."

Engine / feature parameters (exact — do not invent)

Parameter	Value	Source / status
Block duration	90 minutes, starting at the wake event (CaffeineBlockMinutes = 90)	Spec-fixed (doc 03 §2.2).
Blocked category	Caffeine-bearing items — categorical membership, not mg	Spec-fixed (Core Opinion 1).
Wake-up anchor source	OPEN QUESTION. Legacy inferred wake = work_start − 1h (never asked). Manual "I'm awake" log vs. wearable sleep-end (HealthKit / Health Connect) vs. both-with-precedence is undefined.	doc 03 §2.2 / §7 item 3; legacy candidate answer (doc 12). PENDING DESIGN.
Drink classification (clean vs. sugar-based)	Decided server-side via drink registry column is_sugar_based. Legacy seed: sugar-based = red bull / monster / energy drink / soda / cola; clean = cold brew / matcha / green tea / espresso / black coffee / americano; unknown kinds treated as clean.	Legacy precedent seed data (doc 12). Registry is a DB resource; classification is not a client concern.
Daily caffeine-log cap	Legacy MaxDailyCaffeineLogs = 8	Legacy precedent, not spec-fixed — PENDING ratification. Do not treat as a protocol constant until ratified.
Caffeine-log cooldown	Legacy CaffeineLogCooldown = 1 min	Legacy precedent, not spec-fixed — PENDING ratification.
Violation handling	Accept-and-flag (store the log, record the violation), not reject-at-API	doc 03 §0.5 / §2.3; global assumption pending ratification.
Fail-safe (no wake logged)	Engine does not guess a wake time; caffeine logs made in AwaitingWake are stored and marked unevaluated; user is prompted to log wake. No retroactive violation invented.	doc 03 §2.7 — hard invariant.

State machine (doc 03 §2.3): AwaitingWake → (wake event) → Blocked → (90 min elapsed, server timer) → Clear. In Blocked, a caffeine-bearing log is a categorical violation recorded accept-and-flag. Day/cycle reset boundary (Clear → AwaitingWake) is an OPEN QUESTION.

REST surface (names from doc 03 §2.6; note divergence below): POST /v1/engines/caffeine/wake (record wake), GET /v1/engines/caffeine/state (snapshot: { state, block_remaining, wake_time, violations_today }), GET /v1/engines/caffeine/violations (history). Caffeine consumption itself is a log event fanned out through the shared intake pipeline (doc 03 §9.1); the engine evaluates those events via a kernel hook. PENDING DESIGN: exact log endpoint path — doc 03/11 imply the shared intake log, doc 05 uses /api/v1/intake/entries, doc 06 uses POST /caffeine/log. Reconcile in the backend session and document the chosen path in the handoff.

Sessions

Session ID pattern: S-<date>-M2-<surface>-NN (<date> = the build date, NN = per-day sequence; fill in at session start).

Session ID	Surface	Scope	Entry deps	Done criteria (doc 13 §5)	Plan docs to read
S-<date>-M2-backend-NN	backend	The caffeineblock ToGO plugin: pure core/ state machine (AwaitingWake/Blocked/Clear, 90-min block, accept-and-flag, no-wake fail-safe); plugin.go registration (routes, hook subscription on the shared intake log, injected clock, migration manifest); expand-contract migration for caffeine state + violations + the drink registry resource (is_sugar_based, name_ar, seeded from legacy lists); is_sugar_based classification done server-side; wake/state/violations endpoints returning computed state; engine unit tests encoding every spec constant literally; integration test vs. real Postgres. Wake anchor: implement a pluggable anchor with the legacy work_start − 1h inference as the default, isolated so a future decision swaps it — flag PENDING.	M0.1–M0.4 (backend foundation: kernel, auth, plugin framework, migration harness); M1 Hydration backend done (reference engine pattern to copy). Coordinate with M4 Trigger Families on the shared categorical catalog / caffeine_bearing flag (doc 03 §4, §9.1) — if M4 catalog is not yet built, the drink registry is defined here and reconciled later.	Backend-engine done when: plugin registered on the kernel; migration is expand-contract and every column is NOT NULL with a default; endpoints return server-computed state; engine unit tests encode every spec constant literally and pass; integration test against real Postgres passes (idempotency replay, log-cooldown/cap races); no protocol constant appears outside the engine's core/ package.	13, 03 §0/§2/§9, 04 §6/§8, 12 (legacy caffeine + drinks registry)
S-<date>-M2-web-NN	web	Caffeine Block card + detail route (/engines/caffeine): renders server state, animates a display-only countdown toward the server-provided block deadline (#00FF33 neon-green glow in dark), log-clean-caffeine intent (kind pick only), wake-time change action. No local "is caffeine allowed?" logic.	M0.5–M0.7 (web shell, theme engine, i18n engine); M2 backend done; M1 Hydration web done (reference card pattern).	Client-engine done when: surface renders the engine endpoint state and submits log intents only; thin-client/SSOT audit passes (grep for 90/block-minute/cooldown constants and classification logic finds nothing in client code); both themes render per the strict color spec; Arabic RTL mirrors correctly (incl. any progress/countdown bar); strings are ICU, none concatenated.	13, 03 §2, 05 §1/§timeline+cards, 04 (response shapes)
S-<date>-M2-mcp-NN	mcp	Two tools wired to the real API with personal-access-token auth: log_caffeine (log a caffeine drink by kind only, never mg; sends Idempotency-Key) and today_status (full computed day incl. caffeine block state, returned verbatim). Holds no protocol logic, no classification, no AI keys.	M0.8 (MCP server + CLI skeleton); M2 backend done.	MCP session done when: each tool calls the real API with PAT auth, returns server state verbatim, holds no protocol logic and no AI keys, and the excluded tools (no complete_break, no diagnosis passthrough) stay excluded.	13, 11, 03 §2
S-<date>-M2-chrome-NN	chrome	Popup clean-caffeine button + caffeine block indicator: badge/popup mirror the server snapshot (GET /protocol/state), 1-click clean-caffeine intent, server rejection during the block rendered verbatim as an alert-state response. No local pre-validation of the block rule.	M2 backend done; M1 chrome (MV3 shell, poller/badge engine, API client) as reference. Block indicator visual is PENDING DESIGN (doc 06).	Client-engine done when: surface renders server snapshot and submits intents only; thin-client/SSOT audit passes (no block/cooldown/classification logic in extension code); both themes per color spec; Arabic RTL mirrors; ICU strings, none concatenated.	13, 06 §snapshot+logging, 03 §2
S-<date>-M2-apple-NN	apple	iOS Caffeine Block card + relevant widget/watch surface: renders server state and block countdown, submits clean-caffeine + wake intents. Wearable sleep-end as a candidate wake anchor source stays PENDING (server decides). No local protocol logic.	M2 backend done; M1 apple as reference (X3 sensors/HealthKit coordination only if a wearable wake anchor is chosen — PENDING).	Client-engine done when: surface renders engine state and submits intents only; thin-client/SSOT audit passes; both themes per color spec; Arabic RTL mirrors; ICU strings, none concatenated.	13, 07, 03 §2
S-<date>-M2-android-NN	android	Phone Caffeine Block card + relevant Wear/Glance surface: renders server state and block countdown, submits clean-caffeine + wake intents. Health Connect sleep-end as a candidate wake anchor stays PENDING (server decides). No local protocol logic.	M2 backend done; M1 android as reference (X3 Health Connect coordination only if a wearable wake anchor is chosen — PENDING).	Client-engine done when: surface renders engine state and submits intents only; thin-client/SSOT audit passes; both themes per color spec; Arabic RTL mirrors; ICU strings, none concatenated.	13, 08, 03 §2
S-<date>-M2-desktop-NN	desktop	Electron Caffeine Block surface, reusing the web card/components; renders server state + block countdown, submits clean-caffeine + wake intents through the shared API client.	M2 backend done; M2 web done (component reuse); M1 desktop as reference.	Client-engine done when: surface renders engine state and submits intents only; thin-client/SSOT audit passes; both themes per color spec; Arabic RTL mirrors; ICU strings, none concatenated.	13, 09, 05, 03 §2

Notes & gotchas

• Reuse M1's shape. Hydration is the reference engine; copy its plugin layout (core/ + plugin.go + sqlc queries), its /today integration, its client card pattern, and its test harness. M2 sessions should be faster because the pattern is set.
• Legacy seed data is ready. The legacy drinks table (with name_ar) and the clean/sugar-based kind lists (doc 12) are a ready seed for the drink registry — reuse the classification lists and the admin-CRUD precedent rather than reinventing. Keep is_sugar_based server-side only.
• Wake anchor is the load-bearing open question (PENDING DESIGN). Do not hardcode a single source. Implement the legacy work_start − 1h inference as an isolated, swappable default so the eventual decision (manual log vs. wearable sleep-end vs. precedence) is a one-place change. Multiple wake events (naps/corrections) precedence and the Clear → AwaitingWake day-reset boundary are also undefined — fail safe, do not guess.
• Categorical only (Core Opinion 1). An espresso and a cola are equally "caffeine-bearing." Never compute mg, half-life, or tolerance. Log by kind. check/classification is boolean membership against the catalog/registry.
• No invented certainty (Core Opinion 2). Violations are protocol facts, not physiological claims; AI commentary on caffeine patterns defers to "Consult your doctor."
• PENDING ratification, not spec-fixed: MaxDailyCaffeineLogs = 8 and CaffeineLogCooldown = 1 min are legacy precedents only — do not encode them as protocol constants until ratified, and if used provisionally, keep them inside core/ and flag them in the handoff.
• Endpoint-path divergence (PENDING DESIGN): docs 03/05/06/11 name the caffeine log path differently (shared intake log vs. /api/v1/intake/entries vs. /caffeine/log). Reconcile in the backend session and record the canonical path in the handoff so all client sessions use it.
• Shared intake pipeline liability. Caffeine, GERD, and Trigger Families all evaluate the same intake log event via kernel hooks (doc 03 §9.1). Coordinate the categorical catalog / caffeine_bearing flag with M4 so the drink registry and the food catalog do not fork.
• NOT-NULL + expand-contract is enforced by CI. Every new column (caffeine state, violations, drink registry) must be NOT NULL with a defined default, and the migration must be expand-contract — the schema lint gate (M0.1) will fail otherwise.
• MCP stays thin. log_caffeine/today_status return server state verbatim; no protocol logic, no classification, no AI keys. Excluded tools stay excluded.

Handoff reminder

At session end, follow doc 13 §6: write one session-handoff memory to the healthdebug brain (retain, then memory/edit to attach metadata) with source_ref: handoff/M2-caffeine-block/<surface>/<n> (unique — never reuse) and metadata {project:"healthdebug", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"M2", title:"Handoff <session-id>", next:"<module+surface>", ...}, using the exact content structure in doc 13 §6. 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 (e.g., the wake-anchor resolution) also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc.