trainlog/docs/sync_rollout_readiness.md

Full-generation sync rollout readiness

Deployment-readiness candidate

The generation path remains disabled unless desktop configuration authorizes a specific persisted Android peer and Android contains the strict opt-in document Documents/Trainlog/trainlog-sync-generation-opt-in-v1.json. Absence preserves V3; malformed opt-in fails explicitly. The Web coordinator owns a fixed worker, bounded typed progress and its descendant process group. The foreground Android coordinator advertises its real peer identity, publishes manifest-last bytes, consumes the return generation and emits a durable correlated ACK.

The integrated proof uses the production generation adapter with only its typed libudev/libmtp I/O callbacks replaced by an object-store double. This is software evidence for selection, bounds, publication ordering and the complete conversation, but not evidence for a particular phone's physical libmtp behavior. Generation mode must remain disabled until that hardware gate and the separately authorized rollout are complete.

Candidate, backup and recovery

1. Build and validate one revision, then run python3 tools/package_sync_candidate.py --output <new-private-directory>. Its inventory records hashes, schemas, protocols, entry points and dependencies.
2. assembleDebug is development evidence only. Rollout requires the existing release signing identity, verification of its public certificate and a valid increasing versionCode; this mission reads no signing secret.
3. Quiesce old writers only during an authorized rollout. Desktop backup uses backup_trainlog_sqlite.py and SQLite's backup API, then integrity and foreign-key checks.
4. V3 is not an Android backup. Current Android has a complete verified backup container. For the installed schema-v17 release, build the pinned bridge candidate, verify signing/version continuity separately, install only with explicit approval, create and verify the user backup, and retain it before installing current Android. None of those device/user operations occurred in this software mission.
5. Replacing a binary does not roll back a schema. Before any exchange, a mutually compatible captured pair may be restored. After causal writes or ACKs, never restore only one peer: stop synchronization, preserve both stores and all artifacts, and use an explicit paired recovery plan.
6. The eight-generation-per-peer ceiling is an admission gate. Exhaustion must preserve pending generations, tombstones, finalizations and ACK ledgers; it must never trigger hidden eviction.

Actual rollout needs one separate approval for the signed APK, desktop bundle, verified user backups, coordinated service quiescence, pairing, synthetic smoke and non-destructive hardware smoke. Drive remains separate and untested here.

This is a non-executed rollout checklist. The development branch implements the path; the daily installation still uses V3.

Compatible set

• desktop binary containing schema v21, the Web API and the generation worker;
• sync_generation_exchange.py and all matching transaction-neutral codecs;
• Android schema v20 with SyncGenerationService;
• peers advertising manifest V1, ACK V1, causal deletion V1, history V4 and execution draft V1 under their stable peer_<uuid-v4> identities;
• a trusted local orchestrator configuration referencing the packaged peer/MTP helper with fixed arguments.

Controlled sequence

1. Back up both SQLite stores independently and record their schema versions.
2. Stop the user services only during the separately authorized deployment.
3. Install the mutually compatible desktop helper, binary and Android APK.
4. Migrate synthetic copies first; migration rollback means restoring a backup, not merely replacing the binary.
5. Verify peer identities and advertised capabilities without pairing by name.
6. Perform one non-destructive foreground Android publication and desktop run.
7. Verify both manifest digests, both durable ACK records, lineage and readers.
8. Keep V3 selectable until the controlled full-generation smoke is accepted.

Recovery limits

Do not delete an unacknowledged generation, the last acknowledged generation, its previous valid generation, or causal evidence. An ACK timeout is unresolved, not rollback. Eight retained outgoing generations exhaust admission and require operator diagnosis; this tranche adds no tombstone or evidence garbage collection. A migrated database is recovered from its verified backup, never by assuming an older binary reverses its migration.

Physical MTP, actual Drive configuration, service coordination, installed APK, main merge and deployment are intentionally not performed here.