diff --git a/AGENTS.md b/AGENTS.md index d02fd8f..9171ec8 100644 --- a/AGENTS.md +++ b/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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 95760fb..c7b8568 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 6b5c448..d5b7ae9 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 diff --git a/android/README.md b/android/README.md index fdb00c0..9e5a07d 100644 --- a/android/README.md +++ b/android/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 50d368b..a7bc46a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/android.md b/docs/android.md index 1b54f5c..dfaed7a 100644 --- a/docs/android.md +++ b/docs/android.md @@ -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 diff --git a/docs/architecture.md b/docs/architecture.md index 6ed0d09..4302541 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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. diff --git a/docs/current_state.md b/docs/current_state.md index ed531db..b085d65 100644 --- a/docs/current_state.md +++ b/docs/current_state.md @@ -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. diff --git a/docs/database.md b/docs/database.md index 95cd7a9..6d629ef 100644 --- a/docs/database.md +++ b/docs/database.md @@ -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 diff --git a/docs/program_format_v1.md b/docs/program_format_v1.md index 544fa10..991f145 100644 --- a/docs/program_format_v1.md +++ b/docs/program_format_v1.md @@ -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. diff --git a/docs/reviews/documentation_deep_review_v1.md b/docs/reviews/documentation_deep_review_v1.md new file mode 100644 index 0000000..31350d3 --- /dev/null +++ b/docs/reviews/documentation_deep_review_v1.md @@ -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. diff --git a/docs/roadmap.md b/docs/roadmap.md index 65bafae..a0db736 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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 diff --git a/docs/sleep_diary.md b/docs/sleep_diary.md new file mode 100644 index 0000000..43a93ca --- /dev/null +++ b/docs/sleep_diary.md @@ -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). diff --git a/docs/sync_exchange.md b/docs/sync_exchange.md index 023a1ad..294ba65 100644 --- a/docs/sync_exchange.md +++ b/docs/sync_exchange.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` diff --git a/docs/sync_rollout_readiness.md b/docs/sync_rollout_readiness.md index 5c0e454..0459abf 100644 --- a/docs/sync_rollout_readiness.md +++ b/docs/sync_rollout_readiness.md @@ -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. diff --git a/docs/tests.md b/docs/tests.md index 51f45b2..a8678e5 100644 --- a/docs/tests.md +++ b/docs/tests.md @@ -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, diff --git a/docs/web_sessions.md b/docs/web_sessions.md index 20a7f49..c102822 100644 --- a/docs/web_sessions.md +++ b/docs/web_sessions.md @@ -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