X4 — Update Gate · Session Card

Per-module session list for X4 Update Gate. Read alongside docs/plan/13-execution-modules-and-sessions.md (the framework), 04-backend-togo.md (resource/migration/REST conventions), 12-legacy-reference-map.md §5.7 (the proven legacy precedent), and the per-surface PRDs (05 web, 07 apple, 08 android, 09 desktop). A future build session opens this card to know exactly what to build for its cell.

Purpose

The Update Gate makes release management server-owned, not store-owned. A single app_releases resource plus a public, unauthenticated GET /api/app/version?platform=&build= endpoint lets the ToGO backend tell any client whether its installed build is up_to_date, update_available, or update_required — the verdict is computed server-side by comparing the client's reported build against the release manifest, never by the client. Admin CRUD plus a Releases admin page mean a new version is published without a code deploy or a psql session. Each client acts on the server verdict in the way its platform allows: Android drives Play In-App Updates (the download mechanism only), Apple deep-links to the App Store (no equivalent API exists), Electron uses electron-updater against the same manifest, and web shows an update banner. This is the module that gates the first store submission (doc 13 §4).

Engine / feature parameters (exact — do not invent)

This module has no protocol-engine constants (it is a backend resource + version-verdict service, not one of the 8 protocol engines). Its fixed contract, carried from the proven legacy pattern (GitHub issue #4, brain memory healthdebug-update-gate-contract):

• Resource app_release fields: platform, version, build, min_supported_build, store_url, release_notes_en, release_notes_ar, is_mandatory, released_at.
• Public endpoint: GET /api/app/version?platform=<>&build=<> → returns one of up_to_date | update_available | update_required, plus store_url, release_notes_en/ar, and is_mandatory.
• Verdict rule (server-computed SSOT): reported build < min_supported_build ⇒ update_required; reported build < latest published build for the platform ⇒ update_available; otherwise up_to_date. is_mandatory on the target release also forces update_required.
• Unauthenticated by necessity: the endpoint must answer for a client whose token was invalidated by the very change that requires the update — so it is on the deny-by-default guard's allowlist as public (no Authorization required).
• Android uses Play In-App Updates (AppUpdateManager) — IMMEDIATE flow for mandatory, FLEXIBLE otherwise — for the download only. Play's own updateAvailability is a fallback, not the source of truth (it cannot express "this build is protocol-incompatible"); the server manifest verdict decides.
• Apple has no equivalent API — the update sheet deep-links to the App Store via store_url.
• Desktop uses electron-updater sharing the same manifest.
• Web shows an update banner.

Sessions

Surface order is backend → web → mcp → chrome → apple → android → desktop (doc 13 §4); backend must land before any client session. mcp and chrome get no session in this module: Chrome extensions auto-update through the Web Store and the MCP server/CLI updates through its package manager, so neither needs an in-app update gate (mirrors how M6/M7 skip chrome). Session-ID <date> and NN are placeholders filled at session start.

Session ID	Surface	Scope (what this one session builds)	Entry deps	Done criteria (doc 13 §5)	Plan docs to read
S-<date>-X4-backend-NN	backend	app_releases table (migration; every column NOT NULL with a default; strictly expand-contract) + sqlc queries. Server-side version-verdict service implementing the up_to_date/update_available/update_required rule. Public unauthenticated GET /api/app/version?platform=&build= on the guard allowlist, returning verdict + store_url + release_notes_en/ar + is_mandatory. Admin CRUD endpoints (authenticated, admin-scoped) so releases are published without a deploy.	M0.1–M0.4 (microkernel, TOGO auth for the admin endpoints, migration harness, error envelope)	Adapted Backend-engine template: migration is expand-contract and every column NOT NULL + default; the public endpoint returns server-computed verdicts; the verdict logic lives server-side and is covered by unit tests that encode all three outcomes + the min_supported_build / is_mandatory edges literally; integration test against real Postgres (unknown/lower/equal/higher build; admin-created release flips a client from up_to_date→update_required); admin endpoints reject non-admin (404-not-403 isolation); the version endpoint answers with no token. (plugin/core clause is N/A — this is a resource+service, not one of the 8 engines — but the verdict comparison is the SSOT and never leaves the server.)	04, 13, 10 (admin auth), 12 §5.7
S-<date>-X4-web-NN	web	End-user update banner that renders the server verdict (dismissible for update_available, blocking for update_required) using release_notes_en/ar + store_url from the API. Plus the Releases admin page: a CRUD form over the admin API so a version is published from the browser (no deploy, no psql).	M0.5–M0.7 (app shell, theme engine, i18n), S-<date>-X4-backend-NN	Client-engine template: renders /api/app/version state and the admin API only; thin-client/SSOT audit passes — grep finds no min_supported_build/build comparison or mandatory logic in client code; both dark-glow and light-flat themes per the strict color spec; Arabic RTL mirrors correctly; banner + admin copy are ICU messages, release notes rendered as server strings (never concatenated).	05, 13, 01 (colors/i18n), 12
S-<date>-X4-apple-NN	apple	Update sheet shown on the server verdict; for update_required it blocks and deep-links to the App Store via store_url, for update_available it offers an optional prompt. No local version math.	S-<date>-X4-backend-NN, Apple app shell (M1 apple)	Client-engine template: renders the server verdict and deep-links only; thin-client audit passes (no build comparison, no client-decided "mandatory"); both themes; Arabic RTL; ICU strings; release notes from release_notes_en/ar.	07, 13, 02 (divergences), 12
S-<date>-X4-android-NN	android	Wire Play In-App Updates (AppUpdateManager): IMMEDIATE flow when the server verdict is update_required/is_mandatory, FLEXIBLE otherwise. Server manifest is the source of truth; Play updateAvailability is only a download fallback.	S-<date>-X4-backend-NN, Android app shell (M1 android)	Client-engine template: the decision to prompt/force comes from the server verdict, not from Play or client math; thin-client audit passes (grep finds no min_supported_build comparison); both themes; Arabic RTL; ICU strings; release notes from the API.	08, 13, 02, 12
S-<date>-X4-desktop-NN	desktop	Configure electron-updater to consult the shared manifest / store_url feed and surface the server verdict (reuses the web banner components where possible); blocking behavior for update_required.	S-<date>-X4-backend-NN, Desktop Electron shell (M0.5 web + Electron scaffold)	Client-engine template: acts on the server verdict, no local version logic; thin-client audit passes; both themes; Arabic RTL; ICU strings.	09, 13, 12

Notes & gotchas

• Legacy precedents worth reusing. The whole pattern is proven in the legacy tree (GitHub issue #4; brain memory healthdebug-update-gate-contract, 9d7ee1e2): legacy Android already shipped an update gate, and legacy desktop/ already carried electron-updater in its scaffold (doc 12 §3). Mine those for the wiring; carry no code forward (doc 12 header rule) — reference only what matches this plan.
• Liability: never let the client decide "mandatory." The is_mandatory / update_required verdict is server-owned. Android must treat Play updateAvailability as a fallback, not the truth, because Play cannot express "this build is protocol-incompatible." A client that computes its own mandatory state re-introduces the duplicated-logic liability the thin-client rule exists to prevent (doc 12 §6).
• Liability: keep the version endpoint unauthenticated. It is deliberately on the deny-by-default allowlist. If it ever required a token it could not answer the exact clients (token invalidated by the update) it exists to serve. Do not add auth "for consistency."
• Do not hardcode store URLs in clients. store_url comes from the manifest so a store move needs no client release.
• PENDING DESIGN.
  • Exact banner/sheet copy and layout and the Releases admin page UI (colors follow the strict spec; composition is a UI-phase decision).
  • FLEXIBLE-update UX: snooze cadence / re-prompt interval for non-mandatory updates.
  • Theme override behavior for the banner/sheet (tracks the M0.6 system-vs-manual override decision, still PENDING DESIGN).
  • Build/version comparison edge policy to confirm at implementation: build is treated as a per-platform monotonic integer; the tie-break and cross-platform semantics of version vs build should be recorded as an architecture-decision memory when fixed.

Handoff reminder

At session end, 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", module:"X4", surface:"<surface>", status:"...", next:"<module+surface>", ...}, with a unique source_ref: handoff/X4-update-gate/<surface>/<n> (never reuse — a repeated source_ref supersedes the prior handoff). 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 (e.g. the build-comparison policy above) 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.