diff --git a/CHANGELOG.md b/CHANGELOG.md index 247a088..43f3671 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index c62c9a0..91b1a2a 100644 --- a/README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index f290bac..7075358 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/android.md b/docs/android.md index d9955e7..16b1ac1 100644 --- a/docs/android.md +++ b/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. diff --git a/docs/architecture.md b/docs/architecture.md index 414eedc..502cc1b 100644 --- a/docs/architecture.md +++ b/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 diff --git a/docs/current_state.md b/docs/current_state.md index 04b464e..12cd47f 100644 --- a/docs/current_state.md +++ b/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. diff --git a/docs/database.md b/docs/database.md index 9d2a831..6926338 100644 --- a/docs/database.md +++ b/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 diff --git a/docs/exchange_format.md b/docs/exchange_format.md index 3afdf7f..697738b 100644 --- a/docs/exchange_format.md +++ b/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, diff --git a/docs/reviews/evidence/web-sessions-detail-desktop.png b/docs/reviews/evidence/web-sessions-detail-desktop.png new file mode 100644 index 0000000..5ed791e Binary files /dev/null and b/docs/reviews/evidence/web-sessions-detail-desktop.png differ diff --git a/docs/reviews/evidence/web-sessions-detail-mobile-390.png b/docs/reviews/evidence/web-sessions-detail-mobile-390.png new file mode 100644 index 0000000..15d863a Binary files /dev/null and b/docs/reviews/evidence/web-sessions-detail-mobile-390.png differ diff --git a/docs/reviews/evidence/web-sessions-editor-mobile-390.png b/docs/reviews/evidence/web-sessions-editor-mobile-390.png new file mode 100644 index 0000000..4d06b6b Binary files /dev/null and b/docs/reviews/evidence/web-sessions-editor-mobile-390.png differ diff --git a/docs/reviews/evidence/web-sessions-editor-mobile.png b/docs/reviews/evidence/web-sessions-editor-mobile.png new file mode 100644 index 0000000..383ae1b Binary files /dev/null and b/docs/reviews/evidence/web-sessions-editor-mobile.png differ diff --git a/docs/reviews/evidence/web-sessions-list-desktop.png b/docs/reviews/evidence/web-sessions-list-desktop.png new file mode 100644 index 0000000..6fa1671 Binary files /dev/null and b/docs/reviews/evidence/web-sessions-list-desktop.png differ diff --git a/docs/reviews/evidence/web-sessions-list-mobile-390.png b/docs/reviews/evidence/web-sessions-list-mobile-390.png new file mode 100644 index 0000000..54b8af3 Binary files /dev/null and b/docs/reviews/evidence/web-sessions-list-mobile-390.png differ diff --git a/docs/reviews/web_sessions_v1_evidence.md b/docs/reviews/web_sessions_v1_evidence.md new file mode 100644 index 0000000..0fe03bd --- /dev/null +++ b/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/`. diff --git a/docs/roadmap.md b/docs/roadmap.md index 55f826d..704aec8 100644 --- a/docs/roadmap.md +++ b/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. diff --git a/docs/sync_exchange.md b/docs/sync_exchange.md index 9b7d2a3..72562b2 100644 --- a/docs/sync_exchange.md +++ b/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 diff --git a/docs/tests.md b/docs/tests.md index 188fe51..7dabf50 100644 --- a/docs/tests.md +++ b/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, diff --git a/docs/web_sessions.md b/docs/web_sessions.md new file mode 100644 index 0000000..f7b2cba --- /dev/null +++ b/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.