docs: reconcile current architecture workflows and stabilization status
This commit is contained in:
fy59
parent
f4ddcfdb05
commit
5f16a3e0ff
17 changed files with 306 additions and 67 deletions
19
AGENTS.md
19
AGENTS.md
|
|
@ -8,12 +8,13 @@ Trainlog consists of:
|
|||
- a Unix/Linux C17 terminal TUI for durable history, correction, analysis,
|
||||
visualization, and manual synchronization, using Notcurses as its completed
|
||||
active rendering/input backend;
|
||||
- a loopback-only local Web adapter whose Dashboard is implemented on the
|
||||
0.1.2 development branch; its Analyse, Programmes, Sessions, and Exercises
|
||||
routes remain placeholders pending separate contracts;
|
||||
- a loopback-only local Web adapter with implemented Dashboard, Analyse,
|
||||
Programmes, Sessions, and Exercises routes on the 0.1.7 development line;
|
||||
- a small user-session PC agent, `trainlog-syncd`, for Android-triggered
|
||||
synchronization;
|
||||
- versioned JSON synchronization artifacts exchanged over direct MTP.
|
||||
- versioned JSON synchronization artifacts exchanged through configured
|
||||
Bluetooth Classic RFCOMM, direct MTP recovery, or a separate private Drive
|
||||
workflow.
|
||||
|
||||
The desktop SQLite database is the canonical long-term history.
|
||||
|
||||
|
|
@ -170,7 +171,7 @@ It is not the canonical analytics store.
|
|||
The Android UI is driven by exercise metadata, never by exercise-name
|
||||
heuristics.
|
||||
|
||||
Android local SQLite schema v24 retains the exactly-one durable active-session
|
||||
Android local SQLite schema v34 retains the exactly-one durable active-session
|
||||
draft introduced in v4.
|
||||
Every meaningful draft/form mutation is persisted by the repository. Back,
|
||||
backgrounding and process death never delete the draft. Home offers explicit
|
||||
|
|
@ -184,7 +185,7 @@ from actual occurrence data after the additive v10 -> v11 migration. Existing
|
|||
rows retain `load_mode=none`, zero rest and NULL targets. Android v12 adds the
|
||||
durable flattened exercise-alias mapping used to resolve retired creator IDs.
|
||||
Desktop schema v12 owns the same alias compatibility boundary. Later additive
|
||||
desktop migrations reach v26 and Android migrations reach v24 without changing
|
||||
desktop migrations reach v37 and Android migrations reach v34 without changing
|
||||
that identity contract. The active
|
||||
completed-session exchange is the separate strict
|
||||
`trainlog-mobile-export` V3; V1/V2 remain readable and `TRAINLOG_FORMAT_V1`
|
||||
|
|
@ -241,14 +242,16 @@ Desktop SQLite schema is versioned with:
|
|||
PRAGMA user_version;
|
||||
```
|
||||
|
||||
The current desktop schema is v26. Schema v9 added an occurrence-owned explicit
|
||||
The current desktop schema is v37. Schema v9 added an occurrence-owned explicit
|
||||
maximum result; v10/v11 added body-zone and planning metadata; v12 added durable
|
||||
flattened exercise aliases; v13-v18 add machine metadata, feedback and
|
||||
revisions, occurrence tracking snapshots, causal profile state, and AI proposal
|
||||
storage/publication state; v19-v21 add lifecycle, causal deletion, and staged
|
||||
generation/ACK ledgers; v22-v24 add generation archival, manual preparations,
|
||||
and durable preparation withdrawal; v25 adds Programs; and v26 additively adds
|
||||
logical Program deletion. None changes `TRAINLOG_FORMAT_V1`.
|
||||
logical Program deletion. Later additive migrations through v37 add Sleep,
|
||||
heart-rate, Cardio and Program planning state. None changes
|
||||
`TRAINLOG_FORMAT_V1`.
|
||||
|
||||
Every incompatible schema evolution requires an explicit migration and
|
||||
regression coverage.
|
||||
|
|
|
|||
|
|
@ -2,6 +2,13 @@
|
|||
|
||||
## Unreleased — 0.1.7
|
||||
|
||||
- Reconciled the canonical documentation against the `f4ddcfd` development
|
||||
lineage: current source schemas v37/v34, implemented Web routes and Program
|
||||
rescheduling, observed package provenance, Sleep row paging, capability
|
||||
selected exchange, Web packaging requirements and validation limits. The
|
||||
[documentation review](docs/reviews/documentation_deep_review_v1.md) records
|
||||
the evidence matrix. This entry changes no runtime behavior or format.
|
||||
|
||||
- Show the Web Sleep agenda newest first with one 7, 14, 21, 28, or All
|
||||
recorded-night selector (7 by default). Sleep reads its full available history
|
||||
without the Analysis period control; other Analysis sections retain their
|
||||
|
|
|
|||
|
|
@ -145,13 +145,20 @@ cd ..
|
|||
|
||||
meson setup build-web -Dweb=enabled
|
||||
meson compile -C build-web
|
||||
meson test -C build-web --print-errorlogs
|
||||
./build-web/tui/trainlog --web
|
||||
```
|
||||
|
||||
The Web application listens on `127.0.0.1:8080` by default. Use
|
||||
`--port <port>` for an explicit alternative. For an existing build directory,
|
||||
use `meson configure build -Dweb=enabled` instead of running `meson setup`
|
||||
again.
|
||||
again. The separate `npm test` run checks Web source; the enabled Meson build
|
||||
registers embedded frontend tests and places its assets in the executable.
|
||||
The default `web=auto` configuration does not by itself prove embedded assets.
|
||||
For a compatible service bundle, use the versioned candidate packaging
|
||||
procedure in [rollout readiness](docs/sync_rollout_readiness.md); copying only
|
||||
`trainlog` omits its matching synchronization helpers. Restarting a service
|
||||
does not change the package selected by its launcher.
|
||||
|
||||
### Android
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ ANDROID_BODY_SHELL=IMPLEMENTED
|
|||
LOCAL_PERSISTENCE=IMPLEMENTED
|
||||
DIRECT_STORAGE=IMPLEMENTED
|
||||
MTP_SYNC=IMPLEMENTED
|
||||
ANDROID_SCHEMA=33
|
||||
ANDROID_SCHEMA=34
|
||||
```
|
||||
|
||||
## Visual contract
|
||||
|
|
|
|||
|
|
@ -19,6 +19,8 @@ evidence and chronology.
|
|||
existing-artifact synchronization boundary.
|
||||
- [Web Sessions V1](web_sessions.md) owns the implemented preparation, resume,
|
||||
history and Android-delivery workflow.
|
||||
- [Sleep Diary guide](sleep_diary.md) explains capture, agenda row paging,
|
||||
factual sport and heart-rate displays, and independent PDF range selection.
|
||||
- [Program format V1](program_format_v1.md) owns the strict desktop planning
|
||||
import contract and program lifecycle used by the Sessions Programs subtab.
|
||||
|
||||
|
|
@ -80,6 +82,9 @@ evidence and chronology.
|
|||
|
||||
- [Review records](reviews/) retain historical audits, incidents, checkpoints,
|
||||
and validation evidence. Their status and paths are historical.
|
||||
- [Documentation deep review V1](reviews/documentation_deep_review_v1.md)
|
||||
records the audited 0.1.7 source baseline, corrected claims, evidence limits,
|
||||
and coverage matrix.
|
||||
- [Programs presentation / Android delete evidence](reviews/programs_presentation_android_delete_v1_evidence.md)
|
||||
records the implemented, not-deployed validation checkpoint and real-browser
|
||||
screenshot evidence.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Android application
|
||||
|
||||
## Candidate schema v34: read-only Programs V2 projection
|
||||
## Schema v34: read-only Programs V2 projection
|
||||
|
||||
The isolated Program rescheduling candidate additively stores a projection
|
||||
The audited Program rescheduling development line additively stores a projection
|
||||
version and revision sequence on synchronized Programs, plus `current_for` and
|
||||
`planning_state` on synchronized Program sessions. The original `planned_for`
|
||||
and all local completed sessions and drafts remain separate. Existing V1 rows
|
||||
|
|
@ -13,7 +13,8 @@ sequence or a later Programs V1 snapshot cannot overwrite accepted V2 planning.
|
|||
If the singleton active draft refers to a session whose current date or ceded
|
||||
state changes, V2 import rejects the generation; it does not alter the draft.
|
||||
The Program screen uses current dates for unfinished sessions and does not offer
|
||||
Start on a ceded slot. This candidate is not installed on the personal phone.
|
||||
Start on a ceded slot. The private Program rollout records a compatible v34
|
||||
Android installation; this source snapshot alone does not prove another device.
|
||||
|
||||
## Sleep Diary V1 and active V2 companion
|
||||
|
||||
|
|
|
|||
|
|
@ -524,12 +524,14 @@ silently rendered as unclassified.
|
|||
|
||||
### Desktop
|
||||
|
||||
Desktop SQLite schema v26 is canonical long-term history. Its additive v25 ->
|
||||
v26 migration adds terminal Program logical deletion and its durable replay,
|
||||
generation, and acknowledgement ledger without deleting imported definitions,
|
||||
derived preparations, or workout facts. Android schema v24 maintains the
|
||||
separate read-only synchronized Programs projection; the optional staged
|
||||
`trainlog-programs` V1 companion does not replace mobile V3 or change
|
||||
Desktop SQLite schema v37 is canonical long-term history in the audited
|
||||
development source. The additive v37 migration stores absolute Program current
|
||||
dates, ceded slots and revision ordering. The earlier v25 -> v26 migration
|
||||
added terminal Program logical deletion and its durable replay, generation and
|
||||
acknowledgement ledger without deleting imported definitions, derived
|
||||
preparations or workout facts. Android schema v34 extends the read-only
|
||||
Programs projection with capability-selected V2 planning state; v24 introduced
|
||||
its original V1 projection. Neither Programs companion replaces mobile V3 or changes
|
||||
`TRAINLOG_FORMAT_V1`. Its additive desktop v23 -> v24 migration adds durable
|
||||
manual-preparation withdrawal identity without deleting revisions, deliveries
|
||||
or workout facts. Its additive v18 ->
|
||||
|
|
@ -589,7 +591,7 @@ exercise_body_zone_sync
|
|||
|
||||
### Android
|
||||
|
||||
Android has an independent local SQLite schema, currently v14. Completed and
|
||||
Android has an independent local SQLite schema, v34 in the audited source. Completed and
|
||||
draft MAX values use one-to-one `max_results` and `draft_max_results` rows;
|
||||
resuming a completed Test max records its stable source session in the one
|
||||
durable draft.
|
||||
|
|
|
|||
|
|
@ -1,12 +1,20 @@
|
|||
# Current implementation state
|
||||
|
||||
## Private installation and Android body figure parity
|
||||
## Audited development line and private installation
|
||||
|
||||
This snapshot audits `trainlog-sleep-single-selector-weeks-v1` at `f4ddcfd`
|
||||
on 2026-10-02. It includes the Program projection fix `8995843`, the body
|
||||
figure Web change `c2935b8`, and the Sleep PDF, sport and paging changes by
|
||||
ancestry. A later documentation-only commit does not imply a new runtime
|
||||
package. The uncommitted Dashboard layout work in the separate
|
||||
`trainlog-dashboard-polish-v1` worktree is outside this snapshot.
|
||||
|
||||
The private daily installation runs the ordered Program rescheduling rollout
|
||||
from `trainlog-program-recalage-v1` at `3a4ec34`, with desktop schema v37,
|
||||
Android schema v34, and the capability-selected `trainlog-programs` V2
|
||||
projection. The PC/Web bundle from `trainlog-body-figure-android-parity-v1`
|
||||
at `c2935b8` is served; synchronization agents retain the compatible Program
|
||||
projection. The observed PC/Web launcher points to the
|
||||
`sleep-single-selector-weeks-v1-f4ddcfd` package; synchronization agents
|
||||
retain the compatible Program
|
||||
rollout bundle. The previous PC/Web bundle from
|
||||
`trainlog-sleep-pdf-treatments-space-v1` at `3758875` remains available for
|
||||
rollback. The served Web uses Android Compose Canvas head, neck, and 22 body
|
||||
|
|
@ -170,8 +178,8 @@ parallel implementation of its rules.
|
|||
| Boundary | Current state |
|
||||
|---|---|
|
||||
| Frozen project exchange | `TRAINLOG_FORMAT_V1=PASS/FROZEN` |
|
||||
| Desktop SQLite | schema v36; v36 makes Sleep revision payload tables append-only; v35 gives every Sleep medication intake a structured `quantity` (1..99), defaulting historical rows to 1 |
|
||||
| Android SQLite | schema v33; v33 makes Sleep revision payload tables append-only; v32 gives every Sleep medication intake a structured `quantity` (1..99), defaults historical rows to 1, and records a distinct quick-publication tip |
|
||||
| Desktop SQLite | source schema v37; v37 adds Program current dates, ceded slots and revision ordering; v36 makes Sleep revision payload append-only; v35 adds intake quantity |
|
||||
| Android SQLite | source schema v34; v34 adds the read-only Programs V2 projection; v33 makes Sleep revision payload append-only; v32 adds intake quantity and quick publication |
|
||||
| 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.7` bugfix-only development, synchronized across Android and desktop; latest stable release: `v0.1.6` |
|
||||
|
|
@ -235,7 +243,7 @@ parallel implementation of its rules.
|
|||
Desktop and Android schema numbers are independent. Neither changes the frozen
|
||||
Trainlog JSON V1 contract.
|
||||
|
||||
The active Sleep V2 delta reads the complete available Sleep history independently
|
||||
The active Sleep V2 view reads the complete available Sleep history independently
|
||||
of the Analysis period used by other sections. Every returned night remains
|
||||
available on the shared 18:00-to-18:00 geometry. Sleep has one agenda display
|
||||
selector: the newest nights first, seven recorded nights per page by default,
|
||||
|
|
@ -511,18 +519,21 @@ The calendar uses the existing typed Core services `fetchAllPrograms(active)`,
|
|||
or execution state. With no active Program it shows an empty state and
|
||||
navigation to Sessions administration; with one it selects it automatically;
|
||||
with several it offers a non-persisted selector. Its continuous Monday–Sunday
|
||||
weeks derive from Program bounds, imported `planned_for` dates, and the actual
|
||||
weeks derive from Program bounds, each unfinished session's current date
|
||||
(`current_for` when present, otherwise imported `planned_for`), and the actual
|
||||
`sessions.started_at` instant for linked completed executions, presented on the
|
||||
same browser-local civil day as Web session history. The Program detail Web API
|
||||
adds the nullable read-only `execution_started_at` projection field; the
|
||||
Programs synchronization artifact and its strict fields are unchanged. A completed
|
||||
Programs V2 projection carries the current dates and ceded-slot state to
|
||||
capable Android peers without changing the strict Programs V1 artifact. A completed
|
||||
session moved from its imported date shows both dates without changing history
|
||||
or Program identity. Several cards may share a day; rest days contain no
|
||||
invented session. A completed execution with no valid history timestamp stays
|
||||
undated rather than appearing to have occurred on its planned day. Unfinished
|
||||
sessions still show their imported dates because no durable current-plan or
|
||||
ceded-optional-slot state exists in the stabilized Programs exchange. It shows
|
||||
all five Core execution states; only `todo` offers Prepare. Each Prepare result
|
||||
sessions show their current dates; ceded unfinished slots remain visible but
|
||||
are excluded from next-session selection and preparation, and are not counted
|
||||
as performed. It shows all five Core execution states; only eligible `todo`
|
||||
offers Prepare. Each Prepare result
|
||||
is followed by an authoritative Core reread and may expose the returned
|
||||
preparation link. This calendar adds no Android delivery, start, or execution
|
||||
behavior.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Desktop database
|
||||
|
||||
## Candidate schema v37: Program planning
|
||||
## Schema v37: Program planning
|
||||
|
||||
Schema v37 is additive to the isolated Program rescheduling candidate. It
|
||||
Schema v37 is additive to the Program rescheduling development line. It
|
||||
creates `program_session_planning` for absolute current dates and ceded-slot
|
||||
state, `program_reschedule_operations` for exact request replay, and
|
||||
`program_revision_sequences` for monotonically ordered Program snapshots.
|
||||
|
|
@ -12,9 +12,9 @@ historical session mutation is introduced. Missing planning rows mean the
|
|||
original `planned_for` date and active planning state. The source format and
|
||||
published Programs V1 artifact remain strict and unchanged.
|
||||
|
||||
This schema is present only in the candidate worktree/build. The stable
|
||||
installation's database remains at its existing schema until a separately
|
||||
authorized coordinated deployment and backup.
|
||||
This schema is present in the audited development commit. Its presence in
|
||||
source does not establish the schema of another installation; a deployment
|
||||
requires a compatible package, backup and migration verification.
|
||||
|
||||
## Causal heart-rate tail correction (schema v36, no migration)
|
||||
|
||||
|
|
@ -256,8 +256,8 @@ is a later, separately versioned migration.
|
|||
## 1. Status
|
||||
|
||||
```text
|
||||
TRAINLOG_DATABASE_SCHEMA_VERSION=28
|
||||
DATABASE_SCHEMA_V28=IMPLEMENTED
|
||||
TRAINLOG_DATABASE_SCHEMA_VERSION=37
|
||||
DATABASE_SCHEMA_V37=IMPLEMENTED
|
||||
TRAINLOG_FORMAT_V1=FROZEN
|
||||
```
|
||||
|
||||
|
|
@ -276,7 +276,7 @@ PRAGMA user_version;
|
|||
Current value:
|
||||
|
||||
```text
|
||||
27
|
||||
37
|
||||
```
|
||||
|
||||
The independent actual-set loads documented in the current desktop, Android
|
||||
|
|
@ -735,7 +735,7 @@ distance km
|
|||
|
||||
The Android SQLite database is independent.
|
||||
|
||||
Current Android-local version: **17**. The explicit migration chain adds the
|
||||
Current Android-local version: **34**. The historical migration chain adds the
|
||||
durable draft in v4, equipment references in v5, per-set load in v6, occurrence
|
||||
identity/multi-occurrence support in v7, and the widened custom-equipment
|
||||
definition graph in v8. Version 9 adds completed/draft explicit max rows, raw
|
||||
|
|
|
|||
|
|
@ -69,9 +69,9 @@ resurrected or prepared; an archived program cannot be prepared. The optional
|
|||
`trainlog-programs` V1 synchronization companion is a separate PC-to-Android
|
||||
projection and does not alter this import format.
|
||||
|
||||
## Local candidate: explicit ordered rescheduling
|
||||
## Explicit ordered rescheduling in the audited development line
|
||||
|
||||
The isolated `trainlog-program-recalage-v1` candidate adds a separate planning
|
||||
The `trainlog-program-recalage-v1` line adds a separate planning
|
||||
state. `planned_for` remains the imported date. `current_for` is an absolute
|
||||
current target for an active, unfinished session; `ceded` releases one selected
|
||||
future slot without completing or deleting its session identity. Completed
|
||||
|
|
@ -93,7 +93,7 @@ Confirmation binds the preview fingerprint to the current Program projection
|
|||
and writes absolute dates, ceded states, the Program revision and a durable
|
||||
operation response in one transaction. Exact operation replay returns that
|
||||
response; changed content under the same operation ID conflicts. A failed
|
||||
write rolls back every row. The candidate requires a recent acknowledged
|
||||
write rolls back every row. The development implementation requires a recent acknowledged
|
||||
Programs V2 generation for every previously contacted Android peer. A newly
|
||||
started offline Android Program draft remains protected by Android's V2 import
|
||||
rejection; the sync run then reports a conflict for explicit resolution.
|
||||
|
|
|
|||
81
docs/reviews/documentation_deep_review_v1.md
Normal file
81
docs/reviews/documentation_deep_review_v1.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# Documentation deep review V1 — 2026-10-02
|
||||
|
||||
## Scope and evidence hierarchy
|
||||
|
||||
This review covers the linear development source at
|
||||
`f4ddcfdb05e9627397f7225c05f40212e9de1ea6`
|
||||
(`trainlog-sleep-single-selector-weeks-v1`). Its ancestors include `3a4ec34`
|
||||
(Program rollout), `8995843` (current Program projection), `c2935b8` (Web body
|
||||
figures), and the Sleep sport/PDF/paging changes. It does not integrate or
|
||||
describe as delivered the uncommitted Dashboard layout work in the separate
|
||||
`trainlog-dashboard-polish-v1` worktree. Stable v0.1.6 and the 0.1.7
|
||||
development line are different publication states.
|
||||
|
||||
Normative frozen contracts take priority over source implementation; source and
|
||||
tests establish capabilities of this commit; dated rollout records establish
|
||||
only the installation they observed; design/review files retain history. The
|
||||
observed PC/Web launcher path names the `f4ddcfd` package. That observation
|
||||
alone is not a byte comparison of a running process, an Android APK inspection,
|
||||
or proof of every synchronization service's package. The earlier verified
|
||||
Program rollout records desktop/Android schemas v37/v34. No private health
|
||||
data, PDF, database or device identifier was read for this review.
|
||||
|
||||
## Coverage inventory
|
||||
|
||||
The 105 tracked baseline Markdown files include root `README.md`, `AGENTS.md`,
|
||||
`CHANGELOG.md`, `android/README.md`, `format/README.md`, 17 primary `docs/*.md`
|
||||
owners, domain and design records, release notes and historical reviews. This
|
||||
revision adds an indexed Sleep guide and this review. The primary owners were
|
||||
inspected against code, migration constants, Meson/Gradle settings, tests and
|
||||
retained rollout records. Designs, releases and reviews were mapped as dated
|
||||
evidence rather than rewritten into current status. The tracked Markdown
|
||||
relative-link scan found no missing target before publication. External link
|
||||
availability was not verified.
|
||||
|
||||
| Document/section | Claim | Evidence (commit, path, symbol or test) | Gap | Correction | Status |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `AGENTS.md` scope | Analyse, Programmes, Sessions and Exercises are placeholders | `web/src/routes/`; `docs/web_sessions.md`; `docs/web_exercises.md` at `f4ddcfd` | Obsolete present tense | Names implemented routes | Corrected |
|
||||
| `AGENTS.md`, database and Android status | Current schemas v26/v24, v28/v17 or v36/v33 | `tui/include/trainlog/database.h` `TRAINLOG_DATABASE_SCHEMA_VERSION=37`; `TrainlogRepository.kt` helper `version=34`; migration tests | Mixed historical and current versions | Current source v37/v34; historical migration steps retained | Corrected |
|
||||
| `current_state.md`, roadmap | `c2935b8`/`3758875` Web package served | Observed launcher target names `sleep-single-selector-weeks-v1-f4ddcfd`; ancestor graph | Package claim stale; running bytes unverified | Reports launcher observation and separate Program rollout | Corrected with limit |
|
||||
| Sleep agenda | Old selector or calendar-week interpretation | `SleepDiaryWorkspace.tsx` `initialAgendaPageSize`, `recentEntries`, `visibleEntries`; Sleep component tests | Seven recorded rows can span more than seven dates | Current 7/14/21/28/All row counts, default seven; old values migration only | Corrected |
|
||||
| Sleep PDF and sport | Page controls could be confused with export range | `SleepDiaryWorkspace.tsx` `pdfStartDate`/`pdfEndDate`; `sleepVisualProjection`; Web PDF tests | Selection and visible page have different scopes | Documents independent inclusive range and factual sport bands | Verified in source |
|
||||
| Programs | Rescheduling labelled future/candidate | `docs/program_format_v1.md`; `docs/sync_exchange.md`; `tui/tests/test_web_programs.c`; Android v34 projection | Development capability mislabelled future | Describes implemented development contract and partial V1-peer convergence | Corrected |
|
||||
| Web package | `npm test` could be mistaken for embedded runtime proof | `meson_options.txt` `web`; `tui/meson.build` frontend target/tests; `tools/package_sync_candidate.py` asset gate | Source tests and package differ | README requires `-Dweb=enabled`, Meson tests, compatible bundle | Corrected |
|
||||
| Synchronization | One ACK might imply universal convergence | `docs/sync_exchange.md` Programs V2 matrix; generation and ACK implementation | V1-only peer omits rescheduled Program while other domains proceed | Added domain/format/selection/ACK matrix | Corrected |
|
||||
| Rollout readiness | Historical eight-generation limit could look universal/current | `tools/sync_generation_exchange.py` `MAX_RETAINED_PER_PEER=16`; Android `SyncGenerationService.MAX_RETAINED_PER_PEER=8`; `tools/sync_peer_worker.py` MTP timeout | Desktop/Android ceilings differ; timeout is not success proof | Separated limits and historical bridge instructions | Corrected |
|
||||
| Sleep user path | Capture, agenda and PDF behavior had no short indexed guide | `TrainlogRepository.kt`; `SleepDiaryWorkspace.tsx`; Sleep projection/PDF tests | Readers had to assemble workflow from state and code | Added indexed factual guide with privacy and evidence boundaries | Corrected |
|
||||
| Backup/rollback | Old executable could be mistaken for schema rollback | `tools/backup_trainlog_sqlite.py` SQLite backup API; `docs/sync_rollout_readiness.md` | Needs paired compatibility and retained backups | Existing procedure retained and linked from README | Verified in documentation |
|
||||
| Tests | Largest historical totals could look like current validation | `docs/tests.md` dated checkpoints; `tui/meson.build`; Web scripts | Build configuration and skipped tests were implicit | Added evidence-reading rule | Corrected |
|
||||
| 0.1.8 | Possible training ideas could look implemented | `docs/roadmap.md`; present catalog/feedback/Sleep/Cardio owners | No approved algorithm or medical rule | Proposed-only section with human validation | Corrected |
|
||||
|
||||
## Validation performed in the isolated documentation worktree
|
||||
|
||||
`python3 tools/validate_json.py` and
|
||||
`python3 tools/validate_import_contract.py` passed. With a local
|
||||
`-Dweb=enabled` Meson build, strict compilation and **114/114** registered
|
||||
tests passed, including the embedded frontend and package self-containment
|
||||
checks. A preliminary `-Dweb=disabled` run passed 111/112; its deployment
|
||||
package test rejected the intentionally absent Web assets as designed. The
|
||||
changed C/H format gate passed with no changed C/H file. Relative links across
|
||||
the tracked baseline plus new Markdown files and `git diff --check` passed.
|
||||
These checks used build artifacts in this worktree and synthetic test data;
|
||||
they did not exercise a personal device, database or service.
|
||||
|
||||
## Boundaries and open evidence
|
||||
|
||||
The source can prove format selection, persistence rules and test coverage; it
|
||||
cannot prove that a particular uninspected phone or service is currently
|
||||
running that source. The `f4ddcfd` launcher observation identifies a package
|
||||
path, not a live process hash. The private rollout and Firefox/PDF records are
|
||||
dated evidence for their stated configurations. Android path reconstruction for
|
||||
the Web silhouette is source parity evidence, not an Android runtime
|
||||
screenshot. The local desktop 16-generation and Android eight-generation
|
||||
admission limits, and the 90-second MTP operation budget, are bounded
|
||||
configuration, not a guarantee against interruption or proof that transient
|
||||
storage occupation is always lower than either ceiling.
|
||||
|
||||
No code defect was confirmed by this documentation pass. A broad line-by-line
|
||||
revalidation of every historical review and every external URL is outside the
|
||||
verified coverage; their current status must not be inferred from this matrix.
|
||||
No application, database, service, synchronization or personal-data operation
|
||||
belongs to this documentation branch.
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Roadmap
|
||||
|
||||
The Program cascade is deployed in the private daily installation from
|
||||
`trainlog-program-recalage-v1` at `3a4ec34`. The PC/Web bundle from
|
||||
`trainlog-sleep-pdf-treatments-space-v1` at `3758875` is now served; it includes
|
||||
`trainlog-program-recalage-v1` at `3a4ec34`. The observed PC/Web launcher points
|
||||
to the `f4ddcfd` package, which includes
|
||||
the verified blue Sleep sport overlay and the readable paginated treatment and
|
||||
remarks PDF. Synchronization services retain their Program rollout paths. No
|
||||
new personal Program rescheduling is implied by this presentation work.
|
||||
|
|
@ -38,7 +38,8 @@ estimates.
|
|||
## Current baseline
|
||||
|
||||
Stable v0.1.6 is the release baseline for the v0.1.7 stabilization cycle.
|
||||
Desktop schema v36, Android schema v33, Notcurses, direct `Documents/Trainlog`
|
||||
The audited development source has desktop schema v37 and Android schema v34.
|
||||
Stable v0.1.6 had desktop schema v36 and Android schema v33. 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
|
||||
|
|
@ -97,10 +98,10 @@ protocol evolution, new Android/Web/TUI capabilities, and speculative
|
|||
optimization are out of scope. Work outside this boundary waits for a later
|
||||
feature cycle rather than widening 0.1.7.
|
||||
|
||||
### Deferred Program rescheduling
|
||||
### Program rescheduling in the audited development line
|
||||
|
||||
Ordered Program rescheduling requires a separate, versioned shared-contract
|
||||
decision after the actual-date display correction. One explicit user action
|
||||
Ordered Program rescheduling is implemented in the audited development line
|
||||
and deployed in the recorded private Program rollout. One explicit user action
|
||||
must select the starting session, restart date, affected successors, and usable
|
||||
slots; preview the old and new dates; then durably record one decision. Only
|
||||
unfinished sessions move, in Program position order. Explicitly ceded optional
|
||||
|
|
@ -110,12 +111,12 @@ selected slot is a rule for this action, not a limit on other same-day workouts.
|
|||
Rest days and Program bounds cannot be silently overridden. Preparations and
|
||||
in-progress executions require checks before applying the decision.
|
||||
|
||||
The result must not cascade again on display, import, replay, or Bluetooth
|
||||
The result does not cascade again on display, import, replay, or Bluetooth
|
||||
reconnection. PC and Android must receive the same business state; a Web-only
|
||||
plan is insufficient. Compatibility requires proof in both supported exchange
|
||||
directions and across revisions or reexports, including explicit behavior for
|
||||
older clients unable to represent the decision. Payload acceptance alone does
|
||||
not establish convergence. This future contract study does not reopen the
|
||||
not establish convergence. This development contract does not reopen the
|
||||
Bluetooth transport, Sleep, HR, or general sync invariants. Before any real
|
||||
application, reread executions and preparations, confirm the restart date and
|
||||
slot choices, and preview the resulting plan again.
|
||||
|
|
@ -180,7 +181,8 @@ remaining per-installation opt-ins are deployment policy, not the v0.1.3 cursor.
|
|||
TypeScript and Vite shell with its five client routes, Catppuccin Mocha design
|
||||
system, permanent Header/Footer, empty-data states and health status. The
|
||||
Dashboard slices below are complete; this does not authorize implementation of
|
||||
the remaining route placeholders.
|
||||
the then-remaining route placeholders; those routes are implemented on the
|
||||
audited 0.1.7 development line.
|
||||
`WEB_DASHBOARD_GRID_V1=PASS/FROZEN` adds the validated 12-column desktop grid,
|
||||
explicit edit mode, drag/resize, keyboard alternative and derived responsive
|
||||
projections without persisting layout state.
|
||||
|
|
@ -421,6 +423,20 @@ normal capture.
|
|||
|
||||
## Later
|
||||
|
||||
### Proposed 0.1.8 training assistance (not implemented)
|
||||
|
||||
Explore gradual, explained progression or maintaining a load from existing
|
||||
performance and subjective feedback. Compare exercises and equipment only when
|
||||
their context is genuinely comparable; account for effort, discomfort and
|
||||
missing observations. Explore requested or evidenced targeted strengthening,
|
||||
reasoned exercise diversity and dumbbell use without diagnosing weakness.
|
||||
Define cautious cardio reference points before any gradual introduction, with
|
||||
no maximal test or generated prescription from this documentation work. Reuse
|
||||
the existing medication diary, Sleep and Cardio facts as context without a
|
||||
second intake workflow or asserted medical causality. A human must validate
|
||||
any proposed training change before it alters a workout. These are ideas, not
|
||||
an implementation decision, delivery date, recovery score or clinical rule.
|
||||
|
||||
- evolve training analytics only where sufficient real history supports the
|
||||
metric, without aggregating incomparable loads;
|
||||
- add body baseline and trend comparisons while keeping direct measurements
|
||||
|
|
|
|||
63
docs/sleep_diary.md
Normal file
63
docs/sleep_diary.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
# Sleep Diary: capture, review and PDF
|
||||
|
||||
This guide describes the Web and Android behavior in the audited `f4ddcfd`
|
||||
0.1.7 development source. The [current state](current_state.md) owns rollout
|
||||
and validation status; [synchronization exchange](sync_exchange.md) owns the
|
||||
versioned Sleep companion. Sleep facts and medication intakes are not a medical
|
||||
interpretation or an automatic training decision.
|
||||
|
||||
## Capture and correction
|
||||
|
||||
Android's quick actions record bedtime (`Couché`), a waking interval
|
||||
(`Réveil`), final get-up (`Levé`) and time-stamped medication intakes. An intake
|
||||
may be recorded during the day or before bedtime. A pre-bed intake creates or
|
||||
reuses the same durable night/day entry; `Couché` later adds to that entry.
|
||||
There is no separate medicine log to fill out. Quantity is a count of the
|
||||
separately stored per-unit dose. Each meaningful edit advances the entry's
|
||||
causal revision; correction uses the existing entry rather than inventing
|
||||
another night. The Android owner and draft/quick-publication rules are detailed
|
||||
in [Android](android.md#sleep-diary-v1-and-active-v2-companion).
|
||||
|
||||
The Sleep day is assigned using the local 18:00-to-18:00 boundary. Each Web
|
||||
agenda row and its heart-rate detail use that night's exact offset and a
|
||||
24-hour elapsed timeline. A missing factual sleep interval may receive a
|
||||
clearly labelled presentation estimate when both bedtime and final get-up
|
||||
exist: bedtime plus 45 minutes through final get-up minus 10 minutes, minus
|
||||
structured waking overlap for the displayed duration. It does not write a
|
||||
Sleep fact. No missing heart-rate samples or sleep stages are manufactured.
|
||||
|
||||
## Review the agenda
|
||||
|
||||
In Analyse → Sommeil, the agenda is newest first. Its single display selector
|
||||
shows 7, 14, 21, 28 or All **recorded entries** per page; seven is the first-use
|
||||
default. These are row counts, not complete calendar weeks: seven entries can
|
||||
span more than seven dates. The choice is browser-local and survives reload;
|
||||
previous 5/10/15 choices migrate to 7/14/21. The other Analyse sections keep
|
||||
their own period control. Select a night to inspect and edit that entry and
|
||||
its measured heart-rate timeline. Paging does not discard the selected night,
|
||||
editor state, loaded statistics or PDF range.
|
||||
|
||||
Blue sport bands come from completed session start/end history, not the
|
||||
Program plan. A missing or invalid end is shown as a point marker with no
|
||||
invented duration. The Web agenda omits the redundant sport text list; the PDF
|
||||
retains a dated sport appendix. Sport does not become a Sleep event or change a
|
||||
sleep total. If the full read reaches its 3,660-night cap, the Web reports that
|
||||
completeness cannot be established instead of silently treating a truncated
|
||||
set as All. Missing data and load errors have explicit states.
|
||||
|
||||
## Preview and export
|
||||
|
||||
The vector PDF preview and download share an inclusive range of **night start
|
||||
dates**. That range is initialized from loaded history and is independent of
|
||||
both the visible agenda page and selected detail night. Sport is read completely
|
||||
before preview/export. The PDF uses the same 18:00 geometry as Web, prints
|
||||
factual sport intervals in blue, and lists sessions even when there is no
|
||||
matching Sleep row. Treatments and remarks wrap by available width and continue
|
||||
on dated pages instead of truncating silently. Review the chosen range before
|
||||
export; a PDF is a local copy of potentially sensitive information.
|
||||
|
||||
The descriptive heart-rate rise/fall overlays compare measured BPM with a
|
||||
recent reference. They do not infer sleep stages, causes, readiness or medical
|
||||
conditions. The source-backed projection and evidence limits are summarized in
|
||||
[current state](current_state.md#versions-and-compatibility) and the
|
||||
[documentation review](reviews/documentation_deep_review_v1.md).
|
||||
|
|
@ -261,6 +261,28 @@ does not publish to it or let it override an artifact in the new endpoint.
|
|||
|
||||
## 3. Artifact table
|
||||
|
||||
The following is a navigation matrix for the audited `f4ddcfd` source. A
|
||||
capability advertisement selects a companion; file presence alone is not an
|
||||
ACK or proof that every domain converged. The detailed versioned rules below
|
||||
remain authoritative.
|
||||
|
||||
| Domain | Producer → consumer | Format/version | Selection and persistence | ACK/proof and limit |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Completed sessions | Android ↔ desktop | `trainlog-mobile-export` V3; V1/V2 legacy input | Default automatic snapshot; stable IDs in separate SQLite stores | V3 import/replay is idempotent; this is not a full-generation ACK |
|
||||
| Manual preparations | Desktop → Android | `trainlog-session-preparations` V2 | Full generation on capable peer; revisions, deliveries and withdrawals retained | Correlated generation ACK closes delivery/withdrawal; an active draft is preserved |
|
||||
| Programs | Desktop → Android | `trainlog-programs` V1 or V2 | Exactly one selected by peer capability; V2 carries current dates, ceded state and revision sequence; desktop owns plan | Correlated ACK; V1-only peer cannot represent a rescheduled live plan, so Program convergence may remain incomplete while other domains proceed |
|
||||
| Program executions | Android → desktop | `trainlog-program-executions` V1 | Stable in-progress/completed provenance, separate from `trainlog-program` V1 desktop import | Generation validation and ACK; no invented completed session |
|
||||
| Sleep diary | Android ↔ desktop | `sleep-diary-v2`; frozen V1 readable | Current causal revision and immutable history; v2 carries intake quantity | Generation/ACK plus revision validation; concurrent ambiguous edits can reject |
|
||||
| Heart rate and Cardio | Android → desktop | Heart Rate V1, session timeline V1, cardio sessions/calibration/guidance V1; separate heart-rate corrections V1 | Factual captures and versioned companions, selected by capabilities | Correlated generation/ACK; no sensor or medical inference on desktop |
|
||||
| Exercise/equipment context | Both directions | Catalog, aliases, BODY ZONES and equipment companions below | Stable IDs, revision and causal rules apply per domain | A generation ACK does not override a per-domain conflict |
|
||||
|
||||
`trainlog-program` V1 is a strict desktop file import defined in
|
||||
[Program format V1](program_format_v1.md); it is never the synchronized
|
||||
`trainlog-programs` companion. `/api/v1` is the local Web API, not a JSON
|
||||
exchange format. Bluetooth, MTP and private Drive move bytes for the same
|
||||
full-generation business protocol; default V3 compatibility and installation
|
||||
opt-in remain separate from format capability.
|
||||
|
||||
| Direction | File | Format |
|
||||
| --- | --- | --- |
|
||||
| Android -> PC | `trainlog-mobile-export-v1.json` | `trainlog-mobile-export` v1 |
|
||||
|
|
@ -277,7 +299,7 @@ does not publish to it or let it override an artifact in the new endpoint.
|
|||
| PC -> Android | `trainlog-exercise-aliases-v1.json` | `trainlog-exercise-aliases` v1 |
|
||||
| PC -> Android | `trainlog-ai-session-drafts-v1.json` | `trainlog-ai-session-drafts` v1/v2 companion; v2 adds proposal withdrawals |
|
||||
| PC -> Android | `programs-v1.json` | optional staged `trainlog-programs` v1 companion: full nondeleted snapshot plus unacknowledged deletion tombstones |
|
||||
| PC -> Android | `programs-v2.json` | candidate `trainlog-programs` v2 companion: original and current dates, ceded state, ordered revision sequence, and the same deletion tombstones |
|
||||
| PC -> Android | `programs-v2.json` | capability-selected `trainlog-programs` v2 companion: original and current dates, ceded state, ordered revision sequence, and the same deletion tombstones |
|
||||
| Android -> PC | `program-executions-v1.json` | optional `trainlog-program-executions` v1 companion: stable in-progress/completed provenance |
|
||||
| Android -> PC agent | `trainlog-sync-request-v1.json` | `trainlog-sync-request` v1 |
|
||||
| Android -> full-generation daemon | `trainlog-sync-full-generation-request-v1.json` | `trainlog-sync-request` v1 |
|
||||
|
|
@ -300,7 +322,7 @@ V3, `trainlog-pc-catalog` V1, and `trainlog-session-preparations` V2. It does
|
|||
not change `TRAINLOG_FORMAT_V1`, active default V3 transport, or preparation
|
||||
semantics.
|
||||
|
||||
### Isolated candidate: Programs V2 capability matrix
|
||||
### Programs V2 capability matrix in the audited development line
|
||||
|
||||
`trainlog-programs` V2 is a separate strict artifact selected only for a peer
|
||||
advertising `programs-v2`. Its session adds `position`, nullable `current_for`
|
||||
|
|
|
|||
|
|
@ -51,26 +51,29 @@ generalizes pairing to another phone or authorizes an unconfigured desktop.
|
|||
3. Quiesce old writers only during an authorized rollout. Desktop backup uses
|
||||
`backup_trainlog_sqlite.py` and SQLite's backup API, then integrity and
|
||||
foreign-key checks.
|
||||
4. V3 is not an Android backup. Current Android has a complete verified backup
|
||||
container. For the installed schema-v17 release, build the pinned bridge
|
||||
candidate, verify signing/version continuity separately, install only with
|
||||
explicit approval, create and verify the user backup, and retain it before
|
||||
installing current Android. None of those device/user operations occurred in
|
||||
this software mission.
|
||||
4. V3 is not an Android backup. At the original September 2026 rollout, the
|
||||
installed schema-v17 phone required a pinned bridge candidate, verified
|
||||
signing/version continuity, and a complete retained user backup before the
|
||||
newer Android package. That is historical procedure evidence, not a claim
|
||||
about the currently installed phone schema or an instruction to repeat the
|
||||
bridge. A new rollout must inspect its actual versions and backups first.
|
||||
5. Replacing a binary does not roll back a schema. Before any exchange, a
|
||||
mutually compatible captured pair may be restored. After causal writes or
|
||||
ACKs, never restore only one peer: stop synchronization, preserve both stores
|
||||
and all artifacts, and use an explicit paired recovery plan.
|
||||
6. The eight-generation-per-peer ceiling is an admission gate. Exhaustion must
|
||||
preserve pending generations, tombstones, finalizations and ACK ledgers; it
|
||||
must never trigger hidden eviction.
|
||||
6. Per-peer retained-generation ceilings are admission gates: the audited
|
||||
desktop `sync_generation_exchange.py` permits 16 active outgoing entries;
|
||||
Android `SyncGenerationService` permits eight. Exhaustion preserves pending
|
||||
generations, tombstones, finalizations and ACK ledgers; it never triggers
|
||||
hidden eviction. These counts are not a bound on all transient staging or
|
||||
transport objects.
|
||||
|
||||
The grouped rollout approval covered the signed APK, desktop bundle, verified
|
||||
user backups, coordinated service quiescence, pairing, synthetic smoke and
|
||||
non-destructive hardware smoke. Those steps are complete for the recorded
|
||||
private installation. Drive remains separate and untested.
|
||||
|
||||
The latest software-only candidate set was rebuilt under the private root
|
||||
The software-only candidate recorded for the original rollout was rebuilt under the private root
|
||||
`/home/fy59/.cache/trainlog/sync-rollout-candidate-v1.NEoMDx` from source commit
|
||||
`dd8c91a946a9c836965818d8cc35b8f8bce74658`. Its desktop inventory records every
|
||||
packaged file digest plus schemas, protocols, entry points and runtime
|
||||
|
|
@ -84,7 +87,7 @@ synthetic schema-v17 backup SHA-256 is
|
|||
`06eb3999c6f3ce2fd8f551b38727a0a67fe6b48dde4c3244b3d50357afa7e6a3`.
|
||||
These are unsigned development evidence, not deployment authorization.
|
||||
|
||||
## Compatible set
|
||||
## Compatible set for the original rollout
|
||||
|
||||
- desktop binary containing schema v21, the Web API and the generation worker;
|
||||
- `sync_generation_exchange.py` and all matching transaction-neutral codecs;
|
||||
|
|
@ -115,6 +118,11 @@ operator diagnosis; this tranche adds no tombstone or evidence garbage
|
|||
collection. A migrated database is recovered from its verified backup, never by
|
||||
assuming an older binary reverses its migration.
|
||||
|
||||
The audited MTP peer worker has a 90-second per-operation budget, further
|
||||
limited by the remaining conversation deadline. It is a timeout bound, not a
|
||||
success guarantee or proof that an interruption cause has disappeared.
|
||||
|
||||
The recorded private installation completed physical MTP, service coordination
|
||||
and APK/desktop deployment. Actual Drive configuration remains untested; the
|
||||
eight-generation admission bound and foreground-phone requirement remain.
|
||||
Android eight-generation admission bound and foreground-phone requirement
|
||||
remain; the audited desktop limit is 16.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,17 @@
|
|||
# Tests and validation
|
||||
|
||||
## Reading the evidence
|
||||
|
||||
Counts below belong to the stated checkpoint, source revision and build
|
||||
configuration. They are historical evidence, not a claim that the present
|
||||
documentation checkout ran those tests. A native build with `-Dweb=enabled`
|
||||
registers embedded Web asset tests in Meson; `npm test` separately runs Vitest
|
||||
against Web source. A default `web=auto` build can omit embedded assets, so a
|
||||
green source test alone does not validate the packaged Web application.
|
||||
Skipped Android fixture tests, unrun instrumented tests and physical Bluetooth,
|
||||
MTP or Drive evidence are distinct outcomes. The primary personal phone is
|
||||
reserved for authorized manual smoke checks, not host automation.
|
||||
|
||||
## Sleep V2 concurrent-edit selection in 0.1.7
|
||||
|
||||
Synthetic Desktop and Android regressions cover both edit-time orderings,
|
||||
|
|
|
|||
|
|
@ -84,7 +84,8 @@ Inactive execution drafts and completed sessions use the existing causal
|
|||
operation/state boundary. Active or stale drafts conflict, and completed-session
|
||||
deletion records a finalization so older snapshots cannot recreate the session.
|
||||
|
||||
Programs are planning data owned by desktop schema v26. The Programs subtab
|
||||
Programs are planning data owned by desktop SQLite (introduced in v25 and
|
||||
extended through v37). The Programs subtab
|
||||
uses responsive cards and a timeline detail view backed by real imported
|
||||
definitions, sessions, usage, and provenance data. Import first runs the
|
||||
same strict Core validator in preview mode, then commits only after explicit
|
||||
|
|
|
|||
Loading…
Reference in a new issue