docs: design plan for removing vault sync (#203)

[drothschild]

Design plan for #203. No code changes — this PR is the design document only.

What this designs

Removal of the Mac-side HTTP bridge: src/sync/, src/helpers/settingsActions.ts, the bridge settings screen, the baseUrl/token settings fields, and the sync_status column. src/interop (markdown contract) and src/export (on-device export, currently wired to no UI) are deliberately kept so the planned Excel backup work has a serializer to build on.

Decisions worth reviewing

Schema — sync_status is undeclared, not dropped. WatermelonDB 0.28 ships no column-removal step; the official docs call deleting columns "not yet implemented" (destroyColumn merged in Nozbe/WatermelonDB#1799 but has not shipped). Guidance is to leave the physical column and omit it from appSchema. The plan bumps to v4 with { toVersion: 4, steps: [] } — verified against the installed schemaMigrations source that an empty steps array validates.

unsafeExecuteSql('ALTER TABLE ... DROP COLUMN') was considered and rejected: transaction guarantees for raw SQL in migrations are undocumented (Nozbe/WatermelonDB#1835 is unanswered by maintainers), and the LokiJS adapter behind adapter.web.ts ignores SQL steps, so the platforms would diverge. The gain would be cosmetic.

The 'bridge_settings' storage key must not be renamed. That blob also holds anthropicKey, openaiKey, and onboardingState. Renaming it orphans every existing API key. The TypeScript type may be renamed; the on-disk key may not.

Phase 1 is hand-audited, not compiler-driven. onCompleteSession reaches sync through a dynamic await import('@/sync/syncService'), which tsc cannot see. Deleting the module without editing activeSession.ts first fails at session completion, not at build. That is why de-wiring is its own phase ahead of deletion.

Three responsibilities become solitary. AGENTS.md documents the zero-total targetSets defaulting and the null → undefined normalization as redundant two-layer defenses. Deleting syncService.ts removes layer 1 of each — including the tests that prove the rule. Phase 2 confirms upsertRoutine's own coverage before removing its twin, and Phase 4 rewrites the AGENTS.md passages that still claim redundancy.

Accepted consequences

• The AI Coach becomes the only routine-authoring path; there is no manual routine builder. Explicitly accepted, not an oversight.
• ~1,600 lines of tests are deleted. Three replacements are specified; net coverage still drops, as expected when removing a feature.
• On-device data is not preserved across the v3→v4 upgrade. The app is pre-release.

Structure

4 phases, each independently mergeable with npm test and tsc --noEmit green. 30 acceptance criteria across 6 groups, each mapped to the phase that covers it.

Closes nothing on its own — implementation follows in a separate PR.

🤖 Generated with Claude Code