Document Web Sessions V1 evidence

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased — 0.1.2
 
+- Implemented `TRAINLOG_WEB_SESSIONS_V1` with paged preparation, resume and
+  history views, stable details, optimistic/idempotent manual preparation,
+  explicit proposal derivation, desktop schema v23, Android schema v22 and the
+  separate `trainlog-session-preparations` V1 generation participant.
+
 - Added compatible non-destructive generation archival on desktop schema v22
   and Android schema v21. Only exactly acknowledged generations older than the
   two active recovery tips leave admission after a verified durable payload

README.md

@@ -17,7 +17,7 @@ over direct MTP; it never copies SQLite database files between devices.
 |---|---|
 | Android | Capture and quickly correct sets, repetitions, loads, durations, and continuous activities; reorder active and completed-session occurrences; capture feedback, J+1 follow-ups, body measurements, and AI proposals; trigger sync; show quick summaries. |
 | Desktop TUI | Administer, inspect, maintain, import/export, correct canonical history, and provide technical tools. |
-| Local Web (0.1.2 development) | Display the implemented local Dashboard and persist its private layout through typed Trainlog Core/API boundaries. Analyse, Programmes, Sessions, and Exercises remain placeholders. |
+| Local Web (0.1.2 development) | Display the Dashboard and the implemented Sessions inventory, detail, manual preparation, and Android-delivery workflow through typed Trainlog Core/API boundaries. Analyse, Programmes, and Exercises remain placeholders. |
 
 No interface reconstructs business truth from SQLite tables. The local Web is
 a sibling adapter, not an extension of the TUI. On `main`, its loopback-only
@@ -318,7 +318,7 @@ not contain cloud credentials and does not run `rclone`.
 As of 2026-09-17:
 
 - `TRAINLOG_FORMAT_V1=PASS/FROZEN`;
-- desktop SQLite schema v22 and Android SQLite schema v21;
+- desktop SQLite schema v23 and Android SQLite schema v22;
 - Notcurses is the only active desktop terminal backend;
 - direct storage is `/storage/emulated/0/Documents/Trainlog` under Android's
   all-files access setting;
@@ -330,7 +330,8 @@ As of 2026-09-17:
 - `TRAINLOG_AI_SESSION_DRAFT_V1=VALIDATION_PENDING` pending a real Drive plus
   Android-triggered bidirectional smoke test.
 - `WEB_FRONTEND_SHELL_V1=PASS/FROZEN` and
-  `WEB_DASHBOARD_V1=PASS/FROZEN`; the other four Web routes remain placeholders;
+  `WEB_DASHBOARD_V1=PASS/FROZEN` and `TRAINLOG_WEB_SESSIONS_V1=PASS/FROZEN`;
+  Analyse, Programmes, and Exercises remain placeholders;
 - `TRAINLOG_WEB_V1=CONTRACT_FROZEN / IMPLEMENTATION_STARTED`;
 - `TRAINLOG_SYNC_GENERATION_ACK_V1=PASS/FROZEN` through explicit staged
   services; automatic synchronization still selects V3. The opt-in grouped Web

docs/README.md

@@ -14,6 +14,9 @@ evidence and chronology.
 
 ## Interfaces
 
+- [Web Sessions V1](web_sessions.md) owns the implemented preparation, resume,
+  history and Android-delivery workflow.
+
 - [Android](android.md) owns field-companion capture, local persistence,
   glanceable summaries, permissions, and Android interaction rules.
 - [Desktop TUI](tui.md) owns Notcurses navigation, correction, detailed

docs/android.md

@@ -1,5 +1,11 @@
 # Android application
 
+Android schema v22 adds a pending manual-preparation store which is separate
+from AI proposals and the exactly-one active-session singleton. A received
+preparation is inert until explicit start; an occupied singleton is never
+overwritten. Starting preserves the desktop-reserved execution `session_id`,
+copies targets only and creates no performed facts.
+
 ## 1. Purpose
 
 The Android application is Trainlog's low-friction capture client.

docs/architecture.md

@@ -493,7 +493,7 @@ silently rendered as unclassified.
 
 ### Desktop
 
-Desktop SQLite schema v21 is canonical long-term history. Its additive v18 ->
+Desktop SQLite schema v23 is canonical long-term history. Its additive v18 ->
 v19 migration stores causal notes and execution-draft lifecycle state without
 activating a new transport. Its v15 -> v16
 transactional rebuild adds the occurrence-owned `tracking_mode` snapshot; the

docs/current_state.md

@@ -50,8 +50,8 @@ parallel implementation of its rules.
 | Boundary | Current state |
 |---|---|
 | Frozen project exchange | `TRAINLOG_FORMAT_V1=PASS/FROZEN` |
-| Desktop SQLite | schema v22 |
-| Android SQLite | schema v21 |
+| Desktop SQLite | schema v23 |
+| Android SQLite | schema v22 |
 | Mobile snapshot | V3 active; V1/V2 readable legacy inputs; explicit V4 codec staged, not selected by transport |
 | Desktop terminal backend | Notcurses only |
 | Trainlog product version | `0.1.2` development, synchronized across Android and desktop; latest stable release: `v0.1.1` |
@@ -72,6 +72,7 @@ parallel implementation of its rules.
 | Web Dashboard tiles | `WEB_DASHBOARD_TILES_V1=PASS/FROZEN` |
 | Web Dashboard visualizations | `WEB_DASHBOARD_VISUALIZATIONS_V1=PASS/FROZEN` |
 | Web Dashboard V1 | `WEB_DASHBOARD_V1=PASS/FROZEN` |
+| Web Sessions V1 | `TRAINLOG_WEB_SESSIONS_V1=PASS/FROZEN` (isolated software validation; controlled deployment pending) |
 | Sync orchestrator/report V1 | `TRAINLOG_SYNC_ORCHESTRATOR_REPORT_V1=PASS/FROZEN` |
 | Web sync API V1 | `TRAINLOG_WEB_SYNC_API_V1=PASS/FROZEN` |
 | Web sync button V1 | `TRAINLOG_WEB_SYNC_BUTTON_V1=PASS/FROZEN` |
@@ -216,8 +217,16 @@ and linked into the binary. The read-only Dashboard uses one typed Core
 snapshot, a seven-tile responsive grid, factual size-adaptive tiles, an ECharts
 progression series, an original BODY ZONES SVG, and private versioned layout
 persistence with optimistic conflict and CSRF/Origin protection. It provides no
-business mutation or automatic browser launch. Analyse, Programmes, Sessions,
-and Exercises remain explicit placeholders.
+automatic browser launch. Sessions provides complete paged preparation,
+resume and history views, stable details, optimistic manual-preparation writes,
+explicit proposal derivation and generation-backed Android delivery. Analyse,
+Programmes and Exercises remain explicit placeholders.
+
+Desktop schema v23 owns immutable manual-preparation revisions, stable ordered
+occurrences, persistent HTTP idempotency keys and delivery-to-execution identity.
+Android schema v22 stores received preparations separately from AI proposals
+and the active singleton. An exact correlated ACK is required before delivery
+is shown as acknowledged.
 
 The Next Session tile no longer treats the frozen Dashboard
 `next_session.available` placeholder as a durable inventory. A separate bounded
@@ -378,9 +387,8 @@ tests, Android debug assembly, and 211 Android tests (207 passed, four optional
 historical-fixture skips). Strict desktop builds use Clang 22.1.8; the compared
 pre-existing GCC 16.2.1 Web warning gate remains documented rather than green.
 
-- `WEB_NEXT_MODULE_SELECTION_V1`: Analyse, Programmes, Séances and Exercices
-  remain shell placeholders until their Core/API ownership and implementation
-  order are explicitly contracted.
+- `WEB_NEXT_MODULE_SELECTION_V1`: Analyse, Programmes and Exercices remain
+  shell placeholders. Exercises is the next proposed Web module.
 - `APP_SHELL_V1` still awaits the recorded human visual/accessibility review.
 - Session Generator V1 is hidden while V2 planning semantics are developed.
 - Hardware MTP validation requires a connected unlocked Android device.

docs/database.md

@@ -1,5 +1,15 @@
 # Desktop database
 
+## Schema v23: Web session preparations
+
+Schema v23 adds `session_preparations`, immutable
+`session_preparation_revisions` and ordered `session_preparation_entries`.
+`session_preparation_requests` makes Web command replay durable, while
+`session_preparation_deliveries` binds one immutable revision to one reserved
+execution `session_id` and its correlated generation/ACK evidence. These tables
+store no performed sets, MAX results or feedback and do not alter imported AI
+proposal identity.
+
 ## Schema v13: machine-specific exercises
 
 Migration v12→v13 is additive and transactional. It adds exercise-owned load
@@ -16,8 +26,8 @@ is a later, separately versioned migration.
 ## 1. Status
 
 ```text
-TRAINLOG_DATABASE_SCHEMA_VERSION=21
-DATABASE_SCHEMA_V21=IMPLEMENTED
+TRAINLOG_DATABASE_SCHEMA_VERSION=23
+DATABASE_SCHEMA_V23=IMPLEMENTED
 TRAINLOG_FORMAT_V1=FROZEN
 ```
 
@@ -36,7 +46,7 @@ PRAGMA user_version;
 Current value:
 
 ```text
-21
+23
 ```
 
 The independent actual-set loads documented in the current desktop, Android

docs/exchange_format.md

@@ -1,5 +1,15 @@
 # Trainlog Exchange Format v1
 
+## Manual session preparations
+
+`trainlog-session-preparations` V1 has a strict root `format`, `version`,
+`generated_at`, and bounded `deliveries` array. Each delivery contains stable
+delivery, preparation, revision, reserved execution and occurrence identities,
+immutable metadata, and at most 64 ordered target-only occurrences. Null target
+values remain distinct from zero. Performed sets, continuous results, MAX and
+feedback are excluded. This format does not change `TRAINLOG_FORMAT_V1` or any
+mobile snapshot version.
+
 ## TRAINLOG_AI_SESSION_DRAFT_V1
 
 `TRAINLOG_AI_SESSION_DRAFT_V1` is a separately versioned AI-proposal contract,

docs/reviews/web_sessions_v1_evidence.md

@@ -0,0 +1,21 @@
+# Web Sessions V1 evidence matrix
+
+| Requirement | Production owner | Decisive test or check | Result |
+|---|---|---|---|
+| Manual preparation, stable occurrences and causal revisions | `web_sessions.c`, desktop schema v23 | `web_sessions` | PASS |
+| Lost response replay and stale multi-tab conflict | durable request ledger and transactional head compare | `web_sessions` | PASS |
+| Complete lists beyond Dashboard summary | paged Sessions Core query and exhaustive Web consumer | `web_sessions`, `sessions.test.ts` (41 objects over two pages) | PASS |
+| Proposal remains immutable during explicit derivation | provenance-validated creation command | Core transaction and isolated Web flow | PASS |
+| Separate Android pending preparation | Android schema v22 and repository | `SessionPreparationExchangeTest` | PASS |
+| Occupied singleton is never overwritten | `startPreparedSession()` transaction | `SessionPreparationExchangeTest` | PASS |
+| Generation, manifest and exact ACK delivery evidence | generation participant and delivery ledger | `SyncGenerationServiceTest` | PASS |
+| Repeated bidirectional exchange and restart | production generation implementations | `SyncDeploymentConversationTest` (24 conversations) | PASS |
+| Existing transport, deletion and archive behavior | unchanged production suites | canonical Meson suite, 85/85 | PASS |
+| Android migrations and backup | SQLiteOpenHelper v22 and backup verifier | Android unit suite, 221 tests, 0 failures, 5 skips | PASS |
+| Deep links, persisted browser creation and embedded assets | production HTTP server and React route | `test_web_sessions_browser.py`, `web_server`, stored-value inspection | PASS |
+| Catppuccin responsive UI and embedded assets | React Sessions route and existing tokens | typecheck, Vitest 82/82, Vite/Meson builds; Chromium `[390, 844, DPR 1]` captures | PASS |
+
+Physical USB delivery, the installed APK and daily data migration are
+intentionally pending the single controlled-rollout consent gate. Isolated
+real-Firefox functional captures and exact 390 CSS-pixel Chromium captures are
+retained under `docs/reviews/evidence/`.

docs/roadmap.md

@@ -24,7 +24,7 @@ distinction between measured values and estimates.
 
 ## Current baseline
 
-Desktop schema v22, Android schema v21, Notcurses, direct
+Desktop schema v23, Android schema v22, Notcurses, direct
 `Documents/Trainlog` storage, mobile export V3, Training Knowledge V1, Body
 Zones V1, Training Feedback V1/V2, STATS V1, and Session Generator V1 are
 implemented. Session Generator V1 is hidden pending V2. AI session-draft
@@ -33,7 +33,7 @@ exchange and APP_SHELL_V1 retain their explicit manual validation/review gates.
 CLI/HTTP infrastructure, embedded frontend shell and the frozen Dashboard data
 contract, frozen interactive grid, versioned layout persistence and factual
 tile rendering exist. The Dashboard's bounded progression and BODY ZONES
-visualizations are implemented; the other four Web routes remain placeholders.
+visualizations and Sessions V1 are implemented; the other three Web routes remain placeholders.
 The corrective prepared-item projection and bounded phase-owned MTP outbox are
 implemented without opening the Sessions route, changing schemas, or changing
 the frozen Dashboard and exchange contracts.
@@ -53,7 +53,8 @@ transactional consumption, durable correlated ACK and restart/replay entry
 points. The orchestrator, Web API and Web control are complete behind an
 explicit trusted opt-in. The authorized private direct-MTP rollout passed on
 real hardware; automatic V3 selection remains unchanged without that opt-in.
-The next work returns to separately contracted Web surfaces.
+The next separately contracted Web surface is Exercises. Sessions V1 is
+complete in software and is not reopened by that future contract.
 
 `TRAINLOG_SYNC_GAP_CONTRACT_V1=CONTRACT_FROZEN / IMPLEMENTATION_IN_PROGRESS`
 defines the complete-sync target and its bounded dependency order.

docs/sync_exchange.md

@@ -1,5 +1,16 @@
 # Synchronization exchange
 
+## Manual session preparations V1
+
+`trainlog-session-preparations` V1 is a separate optional desktop-to-Android
+generation artifact. It carries immutable ready revision snapshots and stable
+delivery, preparation, occurrence and reserved execution identities. It never
+overloads mobile export, AI proposals or execution-drafts V1. Android validates
+the complete artifact in the generation transaction and stores it as pending;
+start remains an explicit foreground action. Desktop records the exact
+generation relation at capture and changes delivery state to acknowledged only
+after accepting the correlated durable consumption ACK.
+
 ## Causal deletion safety gate
 
 Android and desktop expose staged producers and consumers for the independent
@@ -18,7 +29,7 @@ available because availability is independently guarded by causal state.
 
 ## Machine-exercise Phase 1 compatibility
 
-Desktop schema v22 and Android schema v21 retain mobile export V3, readable V1/V2 imports,
+Desktop schema v23 and Android schema v22 retain mobile export V3, readable V1/V2 imports,
 equipment definitions V1, equipment associations V2, exercise aliases V1, and
 the BODY ZONES companion without wire-format changes. Machine metadata is not
 silently added to a frozen artifact: stable exercise IDs and canonical names

docs/tests.md

@@ -1,5 +1,17 @@
 # Tests and validation
 
+`web_sessions` exercises production preparation creation, durable request
+replay, immutable successor revisions, stale-revision conflict, duplicate
+exercise occurrences, list search and persisted detail serialization. The Web
+Vitest suite covers the shell and API parsers; the embedded frontend is also
+built into the canonical Meson binary.
+
+`SessionPreparationExchangeTest` covers Android import replay, occupied
+singleton refusal, explicit start, reserved execution identity and absence of
+performed facts. `SyncGenerationServiceTest` and
+`SyncDeploymentConversationTest` exercise the real optional artifact through
+generation validation and 24 bidirectional conversations.
+
 `SyncDeploymentConversationTest` executes both production generation services
 and reopens Android storage. `test_web_sync_browser.py` adds a real Firefox click
 through the C adapter, observes the desktop commit at an Android test barrier,

docs/web_sessions.md

@@ -0,0 +1,21 @@
+# Web Sessions V1
+
+The Sessions route implements three distinct views:
+
+- Preparation: manual preparations and immutable AI proposals;
+- Resume: lifecycle-backed execution drafts, continued only on Android;
+- History: completed sessions, including explicit unknown end times.
+
+Manual preparation supports a title, session type, optional calendar date,
+note, catalogue selection, duplicate occurrences, keyboard reordering,
+equipment/load semantics and profile-compatible targets. Draft saves may remain
+incomplete. Marking ready validates executable content; preparing for Android
+then creates a distinct immutable delivery and reserved execution identity.
+
+Opening or deriving from an AI proposal never accepts, starts, deletes or
+rewrites the source. Derivation records the exact proposal identity and imported
+payload fingerprint. The Android screen labels manual preparations separately
+and refuses to overwrite an active draft.
+
+This V1 does not provide live Web capture, historical correction, automatic
+training generation, Programs, Analysis or the standalone Exercises route.