fy59/trainlog
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions

docs: document sleep diary v1

Browse source
This commit is contained in:
fy59 2026-09-21 06:24:17 +02:00
parent bf27e05e7a
commit 1096b13939
8 changed files with 58 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
CHANGELOG.md
View file

@ -2,6 +2,12 @@
## Unreleased — 0.1.4
- Added Sleep Diary V1 across desktop schema v29, Android schema v26, Analyse,
full-generation synchronization and a deterministic local vector PDF agenda.
Entries retain causal revisions, absolute timestamped events, the five-value
appreciation scale and user-authored notes; no medical interpretation or
heart-rate data is introduced.
Development opened after stable v0.1.3 release.
- Implemented the loopback-only Web Analyse V1 workspace and shared bounded

4
README.md
View file

@ -24,7 +24,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.4 development) | Display the Dashboard, the operational Programmes calendar, Sessions administration, and the desktop exercise catalogue through typed Trainlog Core/API boundaries. Exercises supports search/filter, detail, creation, editing and causal retirement; equipment is read-only. Analyse is the current implementation cursor. |
| Local Web (0.1.4 development) | Display Dashboard, Programmes, Sessions, Exercises and factual Analyse workspaces. Analyse includes the Sleep Diary editor, 18:00-to-18:00 agenda and local vector PDF export. |
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
@ -335,7 +335,7 @@ not contain cloud credentials and does not run `rclone`.
As of 2026-09-18:
- `TRAINLOG_FORMAT_V1=PASS/FROZEN`;
- desktop SQLite schema v28 and Android SQLite schema v25;
- desktop SQLite schema v29 and Android SQLite schema v26;
- Notcurses is the only active desktop terminal backend;
- direct storage is `/storage/emulated/0/Documents/Trainlog` under Android's
all-files access setting;

8
docs/android.md
View file

@ -1,5 +1,13 @@
# Android application
## Sleep Diary V1
Android schema v26 additively mirrors the Sleep Diary revision/event model for
local-first field capture. Its compact Morning and Day sections edit one
durable night/day entry without reproducing the desktop/PDF grid. Creation,
correction and logical deletion are revision guarded and survive repository
reopen. Full-generation exchange transports the companion, never SQLite.
## Background USB and private Drive synchronization
SyncScreen and the explicitly enabled background service invoke one

5
docs/current_state.md
View file

@ -107,8 +107,8 @@ parallel implementation of its rules.
| Boundary | Current state |
|---|---|
| Frozen project exchange | `TRAINLOG_FORMAT_V1=PASS/FROZEN` |
| Desktop SQLite | schema v28 |
| Android SQLite | schema v25 |
| Desktop SQLite | schema v29; Sleep Diary V1 is additive in v29 |
| Android SQLite | schema v26; Sleep Diary V1 is additive in v26 |
| 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.4` development, synchronized across Android and desktop; latest stable release: `v0.1.3` |
@ -129,6 +129,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` |
| Sleep Diary V1 | Implemented on the 0.1.4 review branch: timestamped causal diary, Web/Android capture, full-generation companion and local vector PDF |
| Web Sessions V1 | `TRAINLOG_WEB_SESSIONS_V1=PASS/FROZEN` (controlled desktop/Android deployment validated) |
| Web Sessions deletion and Programs V1 | `TRAINLOG_WEB_SESSIONS_DELETE_AND_PROGRAMS_V1=PASS` (private grouped rollout validated) |
| Programs presentation, Android projection, and deletion | `TRAINLOG_PROGRAMS_PRESENTATION_ANDROID_DELETE_V1=PASS` (private coordinated deployment and restart/replay validated) |

16
docs/database.md
View file

@ -1,5 +1,21 @@
# Desktop database
## Schema v29: Sleep Diary V1
Schema v29 additively owns `sleep_diary_entries`, immutable
`sleep_diary_revisions`, and revision-owned `sleep_diary_events`. An entry is
one night and its associated day. Point events have an offset-bearing
`start_at`; intervals additionally have an absolute `end_at` strictly after
their start. The 18:00-to-18:00 agenda is only a projection and is never stored
as cells.
Mutations advance `current_revision_id` only when the caller supplies the
current parent. Logical deletion advances the revision and retains the
tombstone. Qualities preserve `TB`, `B`, `Moy`, `M`, and `TM` exactly.
The absolute timestamps are the future heart-rate correlation boundary. Sleep
Diary V1 does not store, infer, or simulate heart-rate data.
## Schema v28: terminal Program execution provenance
Schema v28 extends `program_session_executions.state` with the terminal

6
docs/roadmap.md
View file

@ -29,7 +29,7 @@ distinction between measured values and estimates.
## Current baseline
Stable v0.1.2 is the release baseline for the v0.1.3 development cycle.
Desktop schema v28, Android schema v25, Notcurses, direct `Documents/Trainlog`
Desktop schema v29, Android schema v26, 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 exchange retains its
@ -58,6 +58,10 @@ The v0.1.4 cursor proceeds from stable v0.1.3 and its validated Web, Program
execution, USB/Drive generation, ACK, and causal-deletion contracts without
reopening those completed gates.
Sleep Diary V1 is implemented on `trainlog-0.1.4-sleep-diary-v1` and remains
under grouped review before integration. Heart-rate sensor ingestion remains
future scope; absolute diary timestamps are its prepared extension boundary.
```text
CURRENT_OPERATIONAL_CURSOR=TRAINLOG_WEB_ANALYSIS_V1
```

13
docs/sync_exchange.md
View file

@ -1,5 +1,18 @@
# Synchronization exchange
## Sleep Diary companion
`trainlog-sleep-diary`, version 1, is emitted by full generations on the 0.1.4
Sleep Diary branch. It is optional when consuming an older generation so a
pre-domain artifact remains replayable. It carries bounded complete entry snapshots with
stable identities, the current immutable revision and causal parent,
offset-bearing timestamps, appreciations, notes and logical deletion. Exact
revision replay is unchanged; sibling revisions and resurrection after deletion
are rejected in the generation consumption transaction.
This does not change `TRAINLOG_FORMAT_V1`, manifests, ACKs, MTP or Drive
transport ownership.
## USB-priority and private Drive transport
Full-generation synchronization has one business engine and two byte

5
docs/tests.md
View file

@ -1,5 +1,10 @@
# Tests and validation
Sleep Diary coverage includes schema creation/migration, midnight and DST
offsets, revision conflict, logical deletion/reopen, companion replay and
rollback, Web periods/deep links, Android persistence, and vector PDF
construction/pagination for 7, 14, 21 and 30 synthetic days.
`web_analysis` covers empty history, every 7/30/90/all period selector,
loaded and unloaded repetitions, continuous duration/distance/speed, explicit
persisted MAX, multiple primary BODY ZONES, partial measurements, one- and