From 2d47805431ac76099689746d3fe4a13a7b745ead Mon Sep 17 00:00:00 2001 From: fy59 Date: Sun, 6 Sep 2026 09:59:00 +0200 Subject: [PATCH] Align documentation with current TUI state --- docs/database.md | 66 ++++++++++++++++++------ docs/reviews/session_edit_persistence.md | 12 ++++- docs/roadmap.md | 25 +++++---- docs/tui.md | 22 +++----- 4 files changed, 83 insertions(+), 42 deletions(-) diff --git a/docs/database.md b/docs/database.md index 4ff9f6a..9a6c957 100644 --- a/docs/database.md +++ b/docs/database.md @@ -3,9 +3,12 @@ ## 1. Status ```text -GATE_2_REVIEW_01=IMPLEMENTED GATE_2=IN_PROGRESS -DATABASE_SCHEMA_V1=DRAFT +DATABASE_SCHEMA_V2=IMPLEMENTED +SESSION_TYPE_PERSISTENCE=IMPLEMENTED +SESSION_EDIT_PERSISTENCE=IMPLEMENTED +BODY_OBSERVATION_EDIT=IMPLEMENTED +TRAINLOG_FORMAT_V1=FROZEN ``` Gate 2 review #1 establishes the persistence foundation. @@ -26,17 +29,29 @@ Trainlog database schema version uses SQLite: PRAGMA user_version; ``` -Initial schema: +Current schema: ```text -DATABASE_SCHEMA_V1=1 +DATABASE_SCHEMA_V2=2 ``` -A new database starts with `user_version = 0` and is initialized atomically to version 1. +A new database starts with `user_version = 0` and is initialized atomically to +the current schema. + +The implemented historical path is: + +```text +0 -> 2 fresh initialization +1 -> 2 transactional migration +``` + +Schema v2 adds local session classification while leaving the frozen Trainlog +JSON v1 exchange contract unchanged. A database newer than the running binary understands is rejected. -Historical migrations are not invented. They must be explicitly implemented and tested when a schema version 2 is introduced. +Every future schema change requires an explicit migration and dedicated +coverage; metadata-only version rewriting is not an accepted migration. ## 4. Connection rules @@ -83,9 +98,14 @@ id session_id UNIQUE started_at ended_at nullable +session_type training | max_test notes nullable ``` +`session_type` is a local SQLite concern in schema v2. Existing schema-v1 rows +migrate to `training`; no historical workout is retroactively inferred to be a +max test. + Body data is stored separately so standalone body observations can use the same representation. ### 5.3 `session_exercises` @@ -195,7 +215,15 @@ ROLLBACK primitives. -The future JSON import service must perform catalog reconciliation and all session inserts inside one transaction. +The JSON import service must perform catalog reconciliation and all session inserts inside one transaction. + +Persisted session correction also uses an explicit transaction. Editing a +session replaces only its `session_exercises` / `performed_sets` children and +preserves the parent session row, stable `session_id`, timestamps, +`session_type`, session notes, and any linked body observation. + +Body-observation correction preserves observation identity, timestamp, and +optional session link. A hard conflict or validation failure leaves the database unchanged. @@ -207,20 +235,24 @@ Canonical persistent units remain: - body circumference: centimeters; - duration/rest: seconds. -## 9. Gate 2 review #1 boundary +## 9. Current Gate 2 persistence boundary -Review #1 intentionally does not implement: +Implemented persistence includes: -- JSON parsing; -- Unicode exercise-name normalization; -- local catalog reconciliation; -- full session insert APIs; -- body-observation CRUD; -- ncurses. +- SQLite schema v2; +- transactional schema migration v1 -> v2; +- Unicode-aware canonical exercise catalog support; +- complete session insertion; +- session detail loading; +- exact bounded editable-session loading; +- transactional replacement of session exercise/set children; +- body-observation creation, listing, exact lookup, and update; +- stable local identifiers for exercises, sessions, and body observations. -Those belong to subsequent Gate 2 work. +The database remains independent from ncurses rendering. -This split keeps the first compiled C change small enough to review thoroughly. +The frozen Trainlog JSON v1 format remains a separate compatibility boundary +and is not version-coupled to SQLite schema v2. ## 10. Validation diff --git a/docs/reviews/session_edit_persistence.md b/docs/reviews/session_edit_persistence.md index 702833c..8a1c006 100644 --- a/docs/reviews/session_edit_persistence.md +++ b/docs/reviews/session_edit_persistence.md @@ -4,7 +4,7 @@ ```text SESSION_EDIT_PERSISTENCE=IMPLEMENTED -SESSION_EDIT_TUI=NEXT +SESSION_EDIT_TUI=IMPLEMENTED TRAINLOG_FORMAT_V1=FROZEN DATABASE_SCHEMA_V2=UNCHANGED ``` @@ -31,3 +31,13 @@ exercise/set values in bounded caller-owned buffers. It refuses insufficient capacity instead of silently truncating editable data. No schema migration and no JSON v1 change are required. + +## TUI integration + +The persistence foundation is now used by the ncurses editor. + +A persisted workout can be reopened from history or session detail, corrected, +and saved without deleting/recreating the parent `sessions` row. + +Draft editing and persisted editing share the same bounded exercise/set model. +Cancelling with Escape leaves the stored workout unchanged. diff --git a/docs/roadmap.md b/docs/roadmap.md index f393232..02aff9b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -35,11 +35,11 @@ Current TUI capabilities: Current remaining Gate 2 direction: -1. finish the current visual/navigation checkpoint; -2. validate persisted editing on the real database; -3. detect Android over USB/ADB; -4. build the minimal Android recorder; -5. exercise frozen JSON v1 import/export end to end. +1. detect Android over USB/ADB; +2. build the minimal Android recorder; +3. transfer/export one frozen Trainlog JSON v1 document over USB; +4. import it transactionally into the canonical SQLite store; +5. validate the complete Android -> JSON -> TUI -> SQLite path. Measured-max semantics remain a later independent analytics contract. @@ -122,8 +122,10 @@ DASHBOARD_12_MONTHS=IMPLEMENTED ```text TUI_EXERCISE_PERFORMANCE=IMPLEMENTED -MEASURED_MAX_TRACKING=NEXT -PREVIOUS_SESSION_DEFAULTS=AFTER +TUI_SESSION_EDIT=IMPLEMENTED +TUI_BODY_OBSERVATION_EDIT=IMPLEMENTED +ANDROID_USB_DETECTION=NEXT +MEASURED_MAX_TRACKING=LATER ``` ## Session type / measured max foundation @@ -149,14 +151,17 @@ classified as a max test. ```text SESSION_EDIT_PERSISTENCE=IMPLEMENTED -SESSION_EDIT_TUI=NEXT -BODY_OBSERVATION_EDIT=AFTER -USB_PHONE_DETECTION=AFTER_EDITING +SESSION_EDIT_TUI=IMPLEMENTED +BODY_OBSERVATION_EDIT=IMPLEMENTED +USB_PHONE_DETECTION=NEXT ``` Recorded session exercise/set correction uses atomic replacement of child rows while preserving the parent session row and linked body observations. +The TUI exposes correction both while reviewing an in-progress draft and after +persistence. Escape cancels without committing partial edits. + ## Body observation record workflow ```text diff --git a/docs/tui.md b/docs/tui.md index 2a929f0..195ade2 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -392,8 +392,8 @@ are not required for the Android transport milestone. ## 21. Global body evolution graph — implemented -`F4 Corps` keeps its current per-metric graph and gains a global normalized -overlay view. +`F4 Corps` provides a record-oriented observation history plus a global +normalized overlay view. The global graph must not overlay raw kilograms and centimeters directly. @@ -429,20 +429,14 @@ recorded value for each available metric. ## 22. Dashboard graph v2 — implemented -The dashboard body-weight graph becomes a richer summary. +The dashboard body graph is implemented as a compact rolling 12-month +multi-metric summary. -It will show: -- current body weight; -- change from first recorded weight; -- change from previous recorded weight; -- minimum recorded weight; -- maximum recorded weight; -- recent weight graph; -- latest waist measurement when available; -- latest left/right asymmetry alert when meaningful. +It shows available body metrics normalized to their first visible value in the +window, while the legend preserves each latest raw value and percentage change. -The dashboard remains intentionally compact. -The complete multi-metric overlay belongs to `F4 Corps`. +The dashboard remains intentionally compact. Detailed absolute observation +history and the complete normalized overlay belong to `F4 Corps`. ## 23. Current implementation cursor