docs: Phone Sync engine research & stack recommendation

[porthex]

What

Adds docs/PHONE_SYNC_RESEARCH.md — a cited deep-research survey to pick a tech stack for the roadmap's 📱 Phone Sync item (drive/continue a Portcode coding session from an iOS/Android phone while AFK), scoped to the project's real constraints: end-to-end encryption mandatory, free / self-hostable / open-source only, and maximum reuse of the existing Tauri v2 + Rust core.

Key findings

• Re-frame as remote-control, not peer sync. The desktop stays on and does the file/shell/agent work; the phone is a secure remote-control + continuation surface. So the core problem is a secure real-time relay, not offline-first multi-writer sync.
• A full CRDT (Automerge/Yjs) is overkill for a 1-writer, 1-to-1, append-mostly session log. Roll our own append-only encrypted event log (the SQLite-WAL store already is the log).
• The "no-pay" goal holds on Android but not iOS. Reliable background wake-ups on iOS legally require APNs → a paid Apple Developer account ($99/yr); there is no free/self-hosted path. Android can be 100% free (FCM high-priority) or even Google-free (self-hosted ntfy/UnifiedPush).

Recommended stack

Layer	Pick
Transport	iroh (QUIC, dial-by-key P2P + hole-punch + self-host relay)
E2E crypto	Noise via snow (Noise_XX→KK_25519_ChaChaPoly_BLAKE2s) + QR/SAS pairing
Sync model	roll-your-own append-only encrypted event log (no CRDT, no sync SaaS)
Phone app	Tauri v2 mobile first (reuses Rust core + React UI); uniffi + native UI as escape hatch
Wake (Android)	FCM high-priority or self-hosted ntfy/UnifiedPush — free
Wake (iOS)	APNs — mandatory, $99/yr

Suggested build order: ship Android Phone Sync first (fully free), add iOS once the Apple membership is budgeted.

Docs-only change. Claims are sourced to primary docs (Apple/Android/Firebase, the Noise spec, WireGuard, the Tauri blog, iroh docs); the only flagged uncertainty is the iOS silent-push throttle rate, which Apple doesn't publish.

https://claude.ai/code/session_0153DPQdqN9R3athM4YrZwPA

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Added new architectural research and decision documentation for “Phone Sync,” outlining recommended end-to-end encrypted sync/session-continuation approaches, chosen implementation direction, and platform considerations (desktop always-on model, wake-up/relay strategy, and iOS/Android constraints).

[github-actions]

Thank you for your contribution! Before we can merge it, we need you to agree to our Contributor License Agreement. Please post the following comment to sign (you only need to do this once):

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8ae871e6-7c7c-44be-9c9b-5bf86fc48092

📥 Commits

Reviewing files that changed from the base of the PR and between b5464f4 and 6925df7.

📒 Files selected for processing (1)

• docs/PHONE_SYNC_RESEARCH.md

✅ Files skipped from review due to trivial changes (1)

• docs/PHONE_SYNC_RESEARCH.md

---

📝 Walkthrough

Walkthrough

Adds docs/PHONE_SYNC_RESEARCH.md, a 324-line engineering research and decision document for the Phone Sync roadmap item. It frames the problem (fast, reliable, end-to-end-encrypted phone-driven session continuation), evaluates sync models and transport options, specifies encryption and mobile app paths, surveys background wake mechanisms by platform, reviews turnkey sync frameworks, and concludes with a recommended stack and step-by-step build order with cost and methodology notes.

Changes

Phone Sync Architecture Research Document

Layer / File(s)	Summary
Document framing, TL;DR decisions, and model selection docs/PHONE_SYNC_RESEARCH.md	Introduces the document as a non-shipped research artifact with precise constraints: fast, reliable, end-to-end-encrypted phone session continuation using free/self-hostable/open-source components. States the TL;DR decisions (iOS APNs requirement, relay model selection, CRDT rejection, stack outline) and compares remote-control relay vs. local-first CRDT sync, concluding that the session is 1-writer/1-to-1 append-mostly and should use simple append-log replication rather than CRDT conflict resolution.
Transport evaluation and E2E encryption design docs/PHONE_SYNC_RESEARCH.md	Evaluates WebSocket/TCP, WebRTC DataChannel, and QUIC/HTTP3 transports across HOL blocking and handoff survivability on flaky networks; recommends iroh for QUIC dial-by-key with relay fallback. Defines the Noise (snow crate) XX/KK/IK handshake pattern for pairing and fast reconnects, QR/Short Authentication String anti-MITM verification, ephemeral DH for forward secrecy, and ChaCha20-Poly1305 cipher preference; emphasizes application-layer encryption independent of transport-layer security.
Mobile app paths and background wake strategy docs/PHONE_SYNC_RESEARCH.md	Recommends Tauri v2 mobile as the primary path to maximize existing Rust-core and React/TS UI reuse, lists uniffi FFI-based and Flutter as escape hatches, and frames "fully native" as a last resort. Details iOS constraints (APNs mandatory, $99/year Apple Developer Program, silent-push best-effort throttling with unpublished ceiling) and Android options (Doze behavior, FCM high-priority, UnifiedPush/ntfy). Introduces the "push as doorbell" pattern: pushes wake the app briefly, then the app pulls deltas over the encrypted channel with heavy work remaining on the always-on desktop.
Sync framework survey, recommended stack, build order, and cost/method notes docs/PHONE_SYNC_RESEARCH.md	Surveys Automerge/Yjs, ElectricSQL, PowerSync, Jazz, Triplit, Evolu, Turso/libSQL, and Ditto against OSS/self-hosted/E2E-by-default criteria; concludes that rolling an append-only encrypted event log over the existing SQLite-WAL session storage is the best fit, with Evolu and Jazz as stronger E2E-by-default fallbacks. Presents the recommended concrete layered stack and step-by-step build order from desktop log/command intake through iroh, Noise, Tauri mobile, and platform wake plugins. Documents iOS shipping constraints tied to mandatory Apple Developer Program cost; recommends Android-first deployment; and identifies iOS silent-push throttle behavior as the single uncertain claim in the 5-angle research methodology.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, the research is done,
A doc of decisions, each carefully won!
QUIC and Noise, and a QR code scan,
Push as a doorbell — that's the plan.
APNs costs? Aye, ninety-nine a year,
But the bunny has charted the path loud and clear! 📱✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: a research document with technical stack recommendations for Phone Sync, which is the primary addition in this PR.
Description check	✅ Passed	The description covers the key sections: What (Summary), findings, and recommended stack. However, it lacks the linked issue number, explicit Type of change checkbox, and Quality gates checklist typically required by the template.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/tech-stack-research-tqi1mo

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/PHONE_SYNC_RESEARCH.md (1)

175-175: 💤 Low value

Optional: Improve directness of phrasing on FFI cancellation.

The phrase "matters for aborting in-flight network ops" is clear but slightly hedged. Consider a more direct alternative:

• Current: "build your own cancel channel — matters for aborting in-flight network ops"
• Suggested: "build your own cancel channel — essential for canceling in-flight network ops" or "critical for aborting async operations"

This is a minor style refinement; the meaning is already clear.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/PHONE_SYNC_RESEARCH.md` at line 175, In the PHONE_SYNC_RESEARCH.md file
where the cross-FFI cancellation topic is discussed, replace the hedged phrase
"matters for aborting in-flight network ops" in the sentence containing "build
your own cancel channel" with a more direct alternative such as "essential for
canceling in-flight network ops" or "critical for aborting async operations" to
improve the clarity and directness of the documentation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/PHONE_SYNC_RESEARCH.md`:
- Around line 14-41: The citation to jackson.dev does not support the claim that
CRDTs are overkill for single-writer scenarios, as Jackson's article actually
advocates for CRDTs in offline-first and decentralized contexts. Find the
reference to jackson.dev/post/crdts_as_database in the document (associated with
the single-writer CRDT overkill argument in point `#3`) and either replace it with
a source that actually supports the single-writer argument, or remove the
attribution entirely if a supporting source cannot be found.

---

Nitpick comments:
In `@docs/PHONE_SYNC_RESEARCH.md`:
- Line 175: In the PHONE_SYNC_RESEARCH.md file where the cross-FFI cancellation
topic is discussed, replace the hedged phrase "matters for aborting in-flight
network ops" in the sentence containing "build your own cancel channel" with a
more direct alternative such as "essential for canceling in-flight network ops"
or "critical for aborting async operations" to improve the clarity and
directness of the documentation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: afda1b00-723d-47fb-ad51-cc0c07f3f2eb

📥 Commits

Reviewing files that changed from the base of the PR and between 7b63864 and b5464f4.

📒 Files selected for processing (1)

• docs/PHONE_SYNC_RESEARCH.md

[porthex]

I have read the CLA Document and I hereby sign the CLA

---

Generated by Claude Code