From 2a68e5a5052f0d9eef1bfdfce3fd1cccff86a075 Mon Sep 17 00:00:00 2001 From: fy59 Date: Sun, 20 Sep 2026 14:35:42 +0200 Subject: [PATCH] docs(sync): document full-generation daily routing --- CHANGELOG.md | 9 +++++++++ docs/android.md | 11 +++++++++-- docs/architecture.md | 9 +++++---- docs/current_state.md | 11 ++++++++--- docs/sync_exchange.md | 8 +++++--- docs/tests.md | 12 ++++++++++++ 6 files changed, 48 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3873e27..b50760e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,15 @@ Development opened after the stable v0.1.2 release. +- Routed Android foreground and daemon-triggered daily synchronization through + the existing full-generation orchestrator whenever its trusted local + configuration is present. The standalone mobile V3 importer remains strict + and still rejects causally protected live replay; complete generations apply + tombstones before filtering dominated snapshot facts. No schema, exchange + format, causal rule, or synchronization protocol changed. Android backup + manifests now obtain `product_version` from installed package metadata + instead of retaining the historical `0.1.2` literal. + - Unified the Android capture interface around compact dark cards, action tiles, restrained-radius button variants, wrapping selection grids, and two-column performed-set entry. Home now focuses on session capture, recent diff --git a/docs/android.md b/docs/android.md index f10e2a5..a480230 100644 --- a/docs/android.md +++ b/docs/android.md @@ -1056,10 +1056,17 @@ coordinator waits for correlated objects, tolerates stale objects left by interrupted runs, strictly revalidates desktop-retained historical ACKs, and shows completion only after both durable peer acknowledgements. -Each explicit foreground generation attempt publishes the Android peer before -emitting one fresh legacy request signal for `trainlog-syncd`. If transport is +Each explicit foreground synchronization attempt publishes the Android peer +and enters the full-generation coordinator before emitting one fresh request +signal for `trainlog-syncd`. The signal is only admission/correlation; a +configured daemon routes it to the existing desktop orchestrator rather than +the standalone V3 importer. If transport is interrupted after generation publication, a later attempt resumes the exact stored generation instead of recapturing mutable data. An acknowledged Android generation remains resumable only until the desktop generation for that run is durably consumed; a fully completed run is then excluded from foreground selection. This preserves late-ACK recovery without replaying completed runs. + +Backup manifests retain format version 1 and the current Android schema. Their +`product_version` is read from installed package metadata, so development +builds record `0.1.3` without a second hard-coded product-version source. diff --git a/docs/architecture.md b/docs/architecture.md index 834c4ad..c8bd030 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -456,10 +456,11 @@ manifest is published after its member objects. The helper runs inside the orchestrator-owned process group and cannot be selected or parameterized by an HTTP request. -It polls for a new Android request and invokes the same shared C synchronization -engine used by the TUI. - -It does not implement a second synchronization algorithm. +It polls for a new Android request. With trusted full-generation configuration +it admits that request to the existing application orchestrator and peer +worker; without that configuration it retains the shared C/V3 compatibility +engine used by the TUI. It does not implement a second synchronization +algorithm. ## 3. Exercise model diff --git a/docs/current_state.md b/docs/current_state.md index 746da19..eccae91 100644 --- a/docs/current_state.md +++ b/docs/current_state.md @@ -152,15 +152,20 @@ Android inbox/outbox still select V3 and do not move the draft artifact. boundaries, not active storage choices. - Desktop synchronization uses direct libudev/libmtp discovery and object access. No GVFS/FUSE mount is required. -- `trainlog_sync_run()` is shared by the TUI and `trainlog-syncd`. +- `trainlog_sync_run()` remains the strict legacy V3 engine shared with the + TUI and compatibility tooling. When the trusted full-generation + configuration is present, `trainlog-syncd` admits the Android request into + the existing `sync_orchestrator.py`/`sync_peer_worker.py` conversation; + configuration absence retains the legacy fallback. - The desktop imports Android snapshots, publishes catalog/profile/feedback/AI companions, and returns a receipt. Stable IDs, artifact idempotence and the few domain-specific explicit states make defined replay paths idempotent. Explicit staged generation services now provide coherent V4/companion capture, immutable manifests, whole-generation SQLite consumption and - durable peer ACKs. A trusted opt-in configuration may select the bounded + durable peer ACKs. The Android foreground trigger now publishes a complete + generation by default. A trusted desktop configuration selects the bounded production generation MTP adapter; absent configuration leaves V3 as the - default. + compatibility fallback. - SQLite database files are never synchronized. - The desktop AI flow uses external `rclone` for Drive inbox/archive and read-only history export. Android owns no Drive credentials. diff --git a/docs/sync_exchange.md b/docs/sync_exchange.md index 9257caa..cdb7c2d 100644 --- a/docs/sync_exchange.md +++ b/docs/sync_exchange.md @@ -135,9 +135,11 @@ Synchronization artifacts are separate from the frozen Trainlog session JSON v1 format. V4 history and execution-draft V1 are staged codecs with explicit repository -and command-line entry points. They are deliberately absent from -`trainlog_sync_run()`, request/receipt publication and the Android automatic -inbox/outbox. Deployment must stop the old user worker, replace the installed +and command-line entry points. They remain deliberately absent from +`trainlog_sync_run()`: configured Android/daemon requests now route around that +strict legacy V3 engine into the existing full-generation orchestrator. The +request artifact remains only a correlated admission signal. Deployment must +stop the old user worker, replace the installed binary/scripts as one unit, migrate only through the new binary, and restart only after compatibility checks; this ticket performs none of those steps. diff --git a/docs/tests.md b/docs/tests.md index a8caf44..7604d78 100644 --- a/docs/tests.md +++ b/docs/tests.md @@ -1512,6 +1512,18 @@ the `trainlog-syncd` launcher and daemon source, and the generation worker. This prevents a user unit from silently executing a helper from a different checkout than the installed desktop candidate. +`syncd_routing` proves that both Android-labelled and daemon-labelled +admissions invoke the packaged `sync_orchestrator.py` full-generation owner +when trusted configuration is present, and never invoke the legacy +`trainlog-sync-once` command in that mode. The generation-MTP boundary test +proves that polling copies the Android request signal without acknowledging or +deleting it. Session-exchange characterization keeps standalone V3 rejection +strict while its complete-envelope case filters a tombstone-dominated live +fact; the causal Android/Desktop round-trip and generation replay/ACK tests +cover restart, idempotence and non-resurrection. `AndroidBackupServiceTest` +injects a product version and verifies that exact value in the ZIP manifest, +preventing a return to a hard-coded release string. + The isolated JDK 17 harness reports **220 Android tests: 215 passed, five skipped, zero failures/errors**. The skips are optional, externally supplied copy gates: `BridgeBackupMigrationTest.verifiedSchemaSeventeenBridgeBackupMigratesThroughCurrentOwner`,