Design and gate opt-in multi-device sync and team aggregation

[ekalb81]

Outcome

Produce an evidence-backed architecture and security decision for optional personal sync and team-level aggregate reporting before any production cloud or remote-write feature is implemented.

Why this is a discovery gate

Odometer currently promises local processing and no prompt upload. Sync introduces identity, encryption, conflict resolution, retention, deletion, access control, and potentially public/team aggregation. Those choices must be explicit before code establishes an accidental protocol.

Scope

• Define sync use cases separately: personal multi-device history, self-hosted backup, private team aggregation, budgets/alerts, and optional anonymous leaderboard.
• Threat-model compromised storage, account takeover, malicious peers, metadata leakage, replay, rollback, device loss, and deletion propagation.
• Specify a versioned aggregate-only sync schema derived from the ledger; prompts, replies, source code, raw paths, commands, tool output, and credentials are prohibited.
• Evaluate user-controlled backends such as local file, GitHub, S3-compatible storage, R2/MinIO, and a self-hosted service without coupling the core ledger to one vendor.
• Design device identity, encryption/key ownership, deduplication, conflict handling, offline operation, tombstones, export, account-free mode, and verifiable deletion.
• Define how team/project budgets and leaderboards handle currency, pricing revisions, aliases, missing providers, and intentionally private projects.

Deliverables

• Architecture decision record and data-flow/threat diagrams.
• Versioned protocol/schema draft with sample neutral payloads.
• Compatibility, migration, backup, restore, and deletion policy.
• Small local or self-hosted prototype proving merge/idempotency and encryption boundaries.
• Explicit go/no-go criteria for personal sync, teams, and leaderboard as separate decisions.

Acceptance criteria

• No production upload, hosted service, account system, telemetry, or public leaderboard ships in this issue.
• Synced aggregates reconcile with ledger facts without exposing banned fields.
• Encryption keys are not controlled solely by an Odometer-hosted service.
• Users can inspect exactly what will leave the device before enabling sync.
• Disable/delete flows are tested and do not erase the local ledger unintentionally.

Dependency and ordering

• Phase: 3 — architecture/security gate
• Priority: P2
• Depends on: Add a durable normalized usage ledger separate from the scan cache #38, Add first-class project and repository analytics over the durable ledger #41, Unify pricing, model aliases, cache creation, currencies, and subscription plans #42
• Parent roadmap: Roadmap: close competitive analytics gaps on shared local-first foundations #36