57 lines
6.2 KiB
Markdown
57 lines
6.2 KiB
Markdown
# Sync Service — Workstream Charter
|
||
|
||
Scope: charters the sync-service workstream — the server-side capability that brings Pro back as "your board beyond your Mac" (the iPhone companion plus sync). It records the settled anchors, the issue map from the architecture brainstorm, the decision surface with its drilling order, and the workstream's mechanics. It makes no new rulings itself; rulings land in this document as dated sections when the workstream's design cards clear review.
|
||
|
||
Drafted: 2026-08-09, from the 2026-08-08 architecture brainstorm; anchors from the 2026-08-07 tier-strategy discussion.
|
||
|
||
## Why this workstream
|
||
|
||
The 2026-08-08 ruling collapsed the base/Pro split: Lanework ships as one free Mac app, and Pro returns later with the iPhone companion and sync as a fresh design pass (`00-charter.md`, note 2026-08-08). This workstream is that design pass.
|
||
|
||
The free Mac app is the acquisition engine; Pro sells "your board beyond your Mac". The iPhone app is the enforceable paywall — transports can leak, Bear-style, but the app cannot. Target price band ~$30–48/yr (the Bear/Obsidian band), which makes per-user service cost a first-class design input.
|
||
|
||
The experience-closed/data-open inversion (`00-charter.md` ▸ The inversion) governs here as everywhere: sync must not close the substrate. Boards remain plain files the user fully owns on every device; the service moves them, it never captives them.
|
||
|
||
## Settled anchors
|
||
|
||
Carried from the 2026-08-07/08 discussions; treated as rulings unless explicitly re-ruled.
|
||
|
||
- Server-side sync service, not a transport hack: iCloud Drive was rejected as the official sync transport (2026-08-07).
|
||
- Two client classes: full clients (the Mac app, agents, git users) hold complete board file trees; worktree clients (iPhone, future web) speak a small API over a server-side virtual worktree, GitHub-Contents-API style.
|
||
- The phone submits semantic ops — move card, edit body — queued offline and replayed; it never syncs raw file trees.
|
||
- The server is (likely) Swift, so the storage-contract code — frontmatter engine, ranks, validation — is shared verbatim across Mac, iPhone, and server. The platform card gives the counter-argument one honest look before this hardens.
|
||
- No end-to-end encryption: the server reads boards. Accepted deliberately — it is what makes server-side materialization, web views, and future cloud agents possible; the compliance card carries the obligations this raises.
|
||
- The ChangeNarrator (`Kanban/Changes/`, harvested from the excised commit-message engine) is the op-describer: every change, native or foreign, narrates itself for the activity feed.
|
||
|
||
## The issue map
|
||
|
||
Named 2026-08-08. Each area is a design card on the workstream board; the card, not this list, carries the full constraints.
|
||
|
||
1. **Source of truth** — the server's canonical representation: file bytes, op log, or hybrid. The one-way door; determines whether full clients speak ops or state, the storage engine, and the shape of conflict resolution.
|
||
2. **Op vocabulary and conflict semantics** — the op set, idempotency, offline replay and rebase, per-card conflict unit, rank conflicts, last-writer-wins granularity, attachment scope.
|
||
3. **Topology** — hub vs relay, and whether service-synced and repo-resident boards are disjoint sets (proposed: they are; it forecloses the three-way-truth problem).
|
||
4. **Mac change-capture** — local files mutate under the app (agents, editors, scripts); observed changes must become uploadable ops, with echo suppression for a device's own ops returning. The deferred foreign-change journal shares this substrate.
|
||
5. **API surface and versioning** — Contents-API style for worktree clients; changed-since-cursor fetch from day one; API version and document schema version as separate axes, because shipped binaries cannot be force-upgraded.
|
||
6. **Server platform, storage engine, hosting** — Vapor vs Hummingbird, Postgres vs SQLite-per-tenant vs object storage, the lab's container path as the small start.
|
||
7. **Identity, authn, device model** — Sign in with Apple primary, magic-link second rail, per-device tokens, no passwords ever; agent tokens as a growth item the schema must not foreclose.
|
||
8. **Entitlement** — StoreKit Server Notifications feed server-side entitlement; lapse semantics; owner/member in the schema from day one so collaboration needs no migration.
|
||
9. **Real-timeness** — a ladder, not a decision: poll → APNs nudge → live streams; the cursor primitive keeps the bottom rung from foreclosing the top.
|
||
10. **Limits and cost** — launch with caps; model per-user cost against the price band.
|
||
11. **Security, privacy, compliance** — the bar no-E2E raises: at-rest encryption, operator access discipline, export/deletion, App Store account deletion, GDPR posture.
|
||
|
||
## Drilling order and one-way doors
|
||
|
||
Source of truth and op semantics rule first — they are the hardest to reverse and everything downstream (API shapes, storage engine, even what "conflict" means) falls out of them. Topology is the cheap early ruling that deletes a swamp in a paragraph. Platform/API follow. Identity, entitlement, real-timeness, and limits have standard answers and are safely incremental; compliance is checklist work whose data-model implications feed back early.
|
||
|
||
The MVP cut is deliberately not defined in this charter: it emerges once the first three rulings land. The only build work filed ahead of rulings is the shape-safe server skeleton.
|
||
|
||
## Growth axes, parked
|
||
|
||
Web worktree client, multi-user collaboration, cloud agents on synced boards. No work before MVP ships; the design cards' only obligation is to avoid foreclosing them (cursor fetch and the streams rung for web, owner/member schema for collaboration, scoped tokens for agents).
|
||
|
||
## Workstream mechanics
|
||
|
||
The tracking board is `Lanework Sync.kanban` (iCloud container, `~/Library/Mobile Documents/iCloud~dev~rzen~indie~Kanban/Documents/`), running the pipeline shape: Ideas → Shaping → Proposed → Approved → Done → Rejected, with Proposed as the human review gate. Labels are phases: design, mvp, growth, parked.
|
||
|
||
An approved design card records its ruling here as a dated `## Ruling — <subject>` section, and the card body points back to it. Per the strategy conventions (`README.md`), a position is open to revision; a ruling stands unless explicitly re-ruled.
|