From 0262433615b83513d2489ace0f4cb48dd98d4502 Mon Sep 17 00:00:00 2001 From: fy59 Date: Sun, 20 Sep 2026 19:22:19 +0200 Subject: [PATCH] docs(sync): document decoupled generation admission --- CHANGELOG.md | 7 +++++++ docs/android.md | 1 + docs/current_state.md | 6 +++++- docs/sync_exchange.md | 4 +++- docs/tests.md | 5 +++++ 5 files changed, 21 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf7d168..48aeaf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ ## Unreleased — 0.1.3 +- Decoupled the Android full-generation request from the strict legacy V3 + compatibility signal. One explicit intent now publishes the dedicated + `trainlog-sync-full-generation-request-v1.json` channel first; the legacy + request is published with the same identity only after a fresh V3 snapshot + succeeds. The desktop daemon prioritizes this channel and durably + deduplicates a bounded set of request identities across both channels. + Development opened after the stable v0.1.2 release. - Made explicit Android synchronization intent authoritative over automatic diff --git a/docs/android.md b/docs/android.md index 4c310f6..df816ce 100644 --- a/docs/android.md +++ b/docs/android.md @@ -746,6 +746,7 @@ Android writes: ```text trainlog-sync-request-v1.json +trainlog-sync-full-generation-request-v1.json ``` The request is replaced through the same direct `Documents/Trainlog` directory diff --git a/docs/current_state.md b/docs/current_state.md index 7b0a916..5cb618f 100644 --- a/docs/current_state.md +++ b/docs/current_state.md @@ -47,7 +47,11 @@ Completed history hides the active preparation exclusively through the delivery's stable execution-session identity and retains all provenance. The opt-in full-generation path is operational on the private daily -installation. The loopback Web control and foreground Android coordinator use +installation. Android explicit synchronization uses a dedicated coordination +filename carrying the unchanged request-v1 payload. Legacy V3 signalling is +additive and occurs only after a fresh strict V3 snapshot succeeds; daemon +request identities are deduplicated across both bounded channels. The loopback +Web control and foreground Android coordinator use the production direct-libmtp adapter, correlated manifest/ACK V1 objects, and persistent peer identities. Controlled USB and private Drive validation proved the complete Web-initiated request, generation, import, publication, and ACK diff --git a/docs/sync_exchange.md b/docs/sync_exchange.md index d1524af..04aa403 100644 --- a/docs/sync_exchange.md +++ b/docs/sync_exchange.md @@ -185,6 +185,7 @@ does not publish to it or let it override an artifact in the new endpoint. | PC -> Android | `programs-v1.json` | optional staged `trainlog-programs` v1 companion: full nondeleted snapshot plus unacknowledged 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 | | PC agent -> Android | `trainlog-sync-receipt-v1.json` | `trainlog-sync-receipt` v1 | No SQLite file is transferred. @@ -917,7 +918,8 @@ for its ACK). Objects retained from an interrupted conversation are ignored until atomically replaced by matching objects. After both peer ACKs, Android reports completion directly; it does not enter the legacy receipt wait state. -The peer publication precedes one fresh `trainlog-sync-request-v1` signal on +The peer publication precedes one fresh +`trainlog-sync-full-generation-request-v1` signal on every explicit Android attempt. This wakes the existing user-session daemon; it is not an ACK and does not alter generation identity. A retry may resume an exact `captured`, `published`, or `waiting_acknowledgement` generation. It may diff --git a/docs/tests.md b/docs/tests.md index f507b0a..47c2233 100644 --- a/docs/tests.md +++ b/docs/tests.md @@ -1544,6 +1544,11 @@ fixture's sample draft. ## Private full-generation rollout validation +Routing regressions cover a strict V3 refusal in the presence of causal +deletions, publication of the dedicated full-generation request before legacy +compatibility, same-identity dual-channel deduplication, full-generation +priority over stale legacy requests, and bounded durable seen-request state. + The MTP visibility regression suite uses injected clocks and transport callbacks, with no multi-second sleeps. It covers delayed Android publication, multiple throttled polls, stale run references, a never-visible generation,