docs: distinguish paired Bluetooth from legacy USB Drive path

This commit is contained in:
fy59 2026-10-02 08:46:58 +02:00
parent 5f16a3e0ff
commit 1c50d483f2
4 changed files with 13 additions and 9 deletions

View file

@ -3,12 +3,13 @@
## Synchronization transport boundary ## Synchronization transport boundary
Generation capture, validation, causal import, publication and ACK acceptance Generation capture, validation, causal import, publication and ACK acceptance
are transport-neutral. `sync_peer_worker.py` owns that conversation; direct MTP are transport-neutral. `sync_peer_worker.py` owns that conversation. The paired
and `sync_drive_transport.py` only move its bounded bytes. Automatic selection private automatic path selects authenticated Bluetooth first and direct MTP as
probes the expected MTP peer before preferring USB. A successful USB run is wired recovery. The separately configured legacy USB/Drive workflow probes the
committed independently, then mirrored to Drive best-effort; Drive failure can expected MTP peer before selecting USB. A successful USB run is committed
never reopen its SQLite transactions. If MTP is unavailable, the same worker independently, then mirrored to Drive best-effort; Drive failure cannot reopen
runs over the Drive byte adapter. 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 Android mirrors that ownership: one `SyncGenerationCoordinator` is called by
SyncScreen, the visible USB foreground service, and the private-folder Drive SyncScreen, the visible USB foreground service, and the private-folder Drive
@ -42,7 +43,7 @@ Android field client
Android shared storage Android shared storage
Documents/Trainlog Documents/Trainlog
| |
| direct MTP | Bluetooth RFCOMM primary; direct MTP recovery
v v
shared desktop sync engine shared desktop sync engine
/ \ / \

View file

@ -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 are presented read-only, and profile edits affect future use only: occurrence
snapshots, performed sets, feedback and MAX history are never rewritten. A snapshots, performed sets, feedback and MAX history are never rewritten. A
successful mutation changes only the canonical desktop database; the existing 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. catalogue/profile/BODY ZONES/causal artifacts. No Web mutation invokes sync.
The calendar uses the existing typed Core services `fetchAllPrograms(active)`, The calendar uses the existing typed Core services `fetchAllPrograms(active)`,

View file

@ -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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 |

View file

@ -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 do not call synchronization and do not require a phone. The next user-triggered
normal synchronization reuses the existing PC catalogue, exercise profile normal synchronization reuses the existing PC catalogue, exercise profile
state, BODY ZONES, equipment companions and causal deletion artifacts through 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. Exercises artifact or protocol version was introduced.