docs/plans/sync-architecture-audit.md
Quick Summary: Audit the current sync stack (vxcore + VNote) against the 4-layer Library Integration Contract documented in
libs/vxcore/AGENTS.md. Each task is a DEVIATION CHECK: confirm compliance or file a focused fix. No large refactors; this plan flushes contract drift.Deliverables:
- Documented audit results for 12 deviation checks.
- Focused fixes for any drift found (each fix is a separate atomic commit pair).
Estimated Effort: Small (12 audit tasks + variable fixes) Parallel Execution: YES — audits are independent Critical Path: A1-A12 in parallel → consolidate findings → fix wave → F1 verification
Three recent post-convergence bugs (static-init dead-strip fff4a5f, folder-event propagation loss 144ca4e, vxcore-debounce-swallows-events cba4e21) share one root cause: vxcore and VNote kept being conflated. The library made scheduling decisions; the consumer assumed the library did work it shouldn't. The architecture is now codified (see libs/vxcore/AGENTS.md § Library Integration Contract). This plan sweeps the current code for remaining contract violations.
The principle (one line): vxcore is an embedded library publishing a stable contract; VNote is one consumer. They are TWO PROJECTS. vxcore owns facts; consumers own policy.
Verify every code path in the sync stack respects the 4-layer contract. File a fix for every deviation.
ctest green on both build trees (parent + vxcore). [vxcore: 2/2 PASS; parent: 12/15 PASS — 3 pre-existing temp-state failures unrelated to docs-only commit]include/vxcore/vxcore.h.libs/vxcore/.Per audit task: capture the grep / inspection result verbatim in the task notes. PASS = empty/expected result. FIX-FILED = link to the follow-up commit. Final F1 wave re-runs the same greps to confirm zero regressions.
All 12 audits are independent and read-only; run them in one parallel wave. Consolidate findings. Then a sequential fix wave (atomic commit per deviation, per the per-task commit rule). Final verification re-runs greps.
sync_builtin_backends.cpp registers; no implicit tokens.MaybeEnqueueSync is fact-only. PASS — debounce removed (cba4e21); only nullptr/config-validity guards remain.SyncService::onSyncShouldRun debounce. PASS (coalesce present, debounce absent); deferred Qt-side debounce as future enhancement (B-A4-1, not a contract violation).<git2.h>, no libs/vxcore/src/ includes, no direct internal member access.TriggerSync lifecycle events. PASS — 1×started, 1×finished, optional 1×conflict; EventBridge is the sole Qt subscriber.144ca4e failure mode.RegisterBuiltinBackends call; one make_unique<GitSyncBackend> site (factory).f8513dd) intentional and marked !; no tags exist. Deferred-with-reason: recommend tagging v0.1.0 (operational task, not in audit fix scope).libs/vxcore/src/sync/AGENTS.md.libs/vxcore/src/sync/AGENTS.md — Sync Event Catalog sync.should_run row, Event-Driven Dirty Tracking paragraph (drop "UNCONDITIONALLY", clarify interval_seconds guard), Locking Discipline last_enqueue_time_ bullet.v0.1.0: operational/release-management task; out of audit-fix scope.AGENTS.md:830 "Worker thread (QThread):", sync_backend_registry.h:96 comment about the removed BackendRegistration kGitRegistration).ctest --test-dir build-debug -C Debug -R "^test_sync" — 12/15 PASS. 3 pre-existing failures (test_sync_signal_auto_baseline, test_sync_hooks, test_sync_auto_route) NOT caused by this audit (docs-only commit 00c645f touches zero C++); failures correlate with shared %TEMP%\vxcore_test_* state per libs/vxcore/AGENTS.md "tests commonly fail in the full suite but PASS individually".test_sync + test_event_manager — 2/2 PASS.vnote.exe smoke per AGENTS.md PATH+VTextEdit.dll-loaded pattern — PASS (alive with VTextEdit.dll loaded after 6s).Per AGENTS.md rule 13: random night timestamp (author + commit date). One commit pair per audit fix (vxcore submodule + parent bump). Reference audit task ID and the contract layer/anti-pattern violated.