trainlog/docs/design/sync_web_end_to_end_v1_evidence.md

Sync Web end-to-end V1 evidence

Status: TRAINLOG_SYNC_WEB_END_TO_END_V1=PASS/FROZEN on the development branch. This status means implemented and validated with isolated stores and a directory transport adapter. It does not mean physical MTP, Drive, deployment, or a merge to main.

Production call graph

React SyncControl
 -> POST /api/v1/sync (Host + Origin + ephemeral CSRF)
 -> C Web admission (trusted opt-in config, one request identity)
 -> owned sync_orchestrator.py process
 -> common XDG sync.lock
 -> trusted peer adapter
 -> Android SyncGenerationService / desktop sync_generation_exchange.py
 -> durable generation and ACK evidence
 -> bounded run report
 -> GET /api/v1/sync/status polling
 -> Dashboard Core snapshot refresh after local commit

The deployed/default path remains V3. Full generation mode is unavailable unless TRAINLOG_SYNC_GENERATION_CONFIG names an absolute, trusted local configuration. HTTP input cannot select a database, executable, transport, capability, path, timeout, or causal bypass.

Requirement-to-proof matrix

Requirement	Production entry point	Exact proof	Observed result
Web admission and passive status	web_server.c /api/v1/sync, /api/v1/sync/status	web_server, sync API	202/409/403/405, passive GET and CSRF header pass
Async owned worker	sync_orchestrator.py	sync_orchestrator, Firefox scenario	HTTP remains responsive and child is reaped
Durable typed phases	atomic .sync-run.json replacement	test_sync_orchestrator.py	correlated completion survives reopen
Common contention	XDG sync.lock	orchestrator conflict test and legacy lock contract	second owner fails without a second import
Strict compatibility	orchestrator capability set	missing-capability test	explicitly_degraded, missing capabilities retained
Generation semantics	desktop and Android generation services	sync_generation_exchange, SyncGenerationServiceTest	coherent capture, whole transaction, ACK and replay pass
Independent producers	public C fixture and Android repository fixture	androidGenerationCapturePublishConsumeAndAckSurviveReopen	both direction chains pass after reopen
All mandatory domains	generation descriptors and apply order	generation suites and causal seven-kind test	required empty artifacts included and validated
Causal immutability	sync_causal_publications	causal multi-generation tests	operation bytes/digests unchanged
Late failure	transaction-neutral apply helpers	desktop and Android late-domain tests	prior writes roll back; no consumed ACK
Lost/late ACK	durable ACK tables	generation restart tests	exact ACK reconstructed; replay unchanged
UI click/reload	SyncControl	test_web_sync_browser.py	real Firefox click, completion, draft details and reload pass
Draft visibility	status drafts projection	SyncControl.test.tsx, Firefox scenario	stable ID/state/type/count shown read-only
Dashboard freshness	onCommitted callback	component test and browser flow	Core snapshot refetched after committed phase
Mutation security	existing Host/Origin/CSRF plus strict body	web_server, sync API	proxy origin retained; no CORS or client paths
Optional AI	separate ai_midpoint and ai_post_sync	orchestrator report validation	not-configured remains explicit, never main success
Default isolation	missing trusted config	C HTTP test	button disabled and POST returns explicit conflict

The Firefox peer command in the browser scenario is the bounded directory transport fixture. Cross-implementation Android/desktop behavior is proven by the production generation suites in the same final validation run. The test does not claim physical-device timing, MTP object behavior, or Drive access.

Bounds

• request body: existing 4 KiB HTTP limit;
• headers: existing 8 KiB limit;
• durable report and each worker output stream: 64 KiB;
• trusted configuration: 16 KiB;
• diagnostic: 1024 UTF-8 bytes;
• draft summaries: 32;
• peer command: 16 fixed arguments, each at most 4096 bytes;
• trusted timeout: 1 to 900 seconds;
• frontend polling: one request at a time, 750 ms between completions;
• generation retention: existing eight outgoing generations per consumer.

Real limitations

Android must participate through its foreground synchronization flow to create a publication correlated to the accepted run. No always-on Android background service was added. A waiting phase is therefore truthful and may require user action. Physical MTP and Drive remain rollout gates. A browser disconnect does not cancel the worker; server shutdown terminates only its owned process group.