docs(sync): document full-generation daily routing

This commit is contained in:
fy59 2026-09-20 14:35:42 +02:00
parent 1e9c8aa741
commit 2a68e5a505
6 changed files with 48 additions and 12 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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