From 1c50d483f2f96a7006cffe81f1529d79fc8165f1 Mon Sep 17 00:00:00 2001 From: fy59 Date: Fri, 2 Oct 2026 08:46:58 +0200 Subject: [PATCH] docs: distinguish paired Bluetooth from legacy USB Drive path --- docs/architecture.md | 15 ++++++++------- docs/current_state.md | 2 +- docs/reviews/documentation_deep_review_v1.md | 1 + docs/web_exercises.md | 4 +++- 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 4302541..c890d86 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -3,12 +3,13 @@ ## Synchronization transport boundary Generation capture, validation, causal import, publication and ACK acceptance -are transport-neutral. `sync_peer_worker.py` owns that conversation; direct MTP -and `sync_drive_transport.py` only move its bounded bytes. Automatic selection -probes the expected MTP peer before preferring USB. A successful USB run is -committed independently, then mirrored to Drive best-effort; Drive failure can -never reopen its SQLite transactions. If MTP is unavailable, the same worker -runs over the Drive byte adapter. +are transport-neutral. `sync_peer_worker.py` owns that conversation. The paired +private automatic path selects authenticated Bluetooth first and direct MTP as +wired recovery. The separately configured legacy USB/Drive workflow probes the +expected MTP peer before selecting USB. A successful USB run is committed +independently, then mirrored to Drive best-effort; Drive failure cannot reopen +its SQLite transactions. If MTP is unavailable in that workflow, the same +worker runs over the Drive byte adapter. No transport carries a SQLite file. Android mirrors that ownership: one `SyncGenerationCoordinator` is called by SyncScreen, the visible USB foreground service, and the private-folder Drive @@ -42,7 +43,7 @@ Android field client Android shared storage Documents/Trainlog | - | direct MTP + | Bluetooth RFCOMM primary; direct MTP recovery v shared desktop sync engine / \ diff --git a/docs/current_state.md b/docs/current_state.md index b085d65..5ed514c 100644 --- a/docs/current_state.md +++ b/docs/current_state.md @@ -511,7 +511,7 @@ catalogue state. Built-in identities cannot be retired, equipment associations are presented read-only, and profile edits affect future use only: occurrence snapshots, performed sets, feedback and MAX history are never rewritten. A successful mutation changes only the canonical desktop database; the existing -USB-priority, Drive mirror/fallback synchronization later carries the existing +configured generation synchronization later carries the existing catalogue/profile/BODY ZONES/causal artifacts. No Web mutation invokes sync. The calendar uses the existing typed Core services `fetchAllPrograms(active)`, diff --git a/docs/reviews/documentation_deep_review_v1.md b/docs/reviews/documentation_deep_review_v1.md index 31350d3..f67b6f5 100644 --- a/docs/reviews/documentation_deep_review_v1.md +++ b/docs/reviews/documentation_deep_review_v1.md @@ -42,6 +42,7 @@ availability was not verified. | 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 | +| Transport narrative | Current Web edits and architecture described USB as universal priority | `docs/sync_exchange.md` Bluetooth selector; `tools/sync_peer_worker.py`; private rollout record | Conflated paired Bluetooth path with separate USB/Drive workflow | Separated automatic paired choice from legacy configured workflow | 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 | diff --git a/docs/web_exercises.md b/docs/web_exercises.md index d34cfa9..e140def 100644 --- a/docs/web_exercises.md +++ b/docs/web_exercises.md @@ -51,5 +51,7 @@ Create, update and retirement first commit only to the desktop database. They do not call synchronization and do not require a phone. The next user-triggered normal synchronization reuses the existing PC catalogue, exercise profile state, BODY ZONES, equipment companions and causal deletion artifacts through -the existing USB-priority engine with Drive as mirror/fallback. No Web +the configured generation engine (Bluetooth primary with direct MTP recovery +on the paired installation, or the separate USB/Drive workflow). Without that +opt-in, the default V3 path retains its documented compatibility limits. No Web Exercises artifact or protocol version was introduced.