itsgoin/IMPLEMENTATION_PLAN_0.6.md

# Implementation Plan: Identity Architecture Rollout (0.6.x beta cycle)

## Context

0.5.3 is stable. The 0.6.x beta line introduces the Network-ID / Posting-ID split, multi-persona support, ephemeral rotating DM identities, file-holder CDN restructure, and CDN-only DM privacy.

Full architectural plan: `/home/sologretto/.claude/plans/woolly-nibbling-glade.md`
Canonical reference: `website/design.html` §28
Memory summary: `reference_identity_architecture.md`

### Backward-compatibility stance

**Beta and stable are separate networks.** A v0.6 node is not expected to interoperate with a v0.5 node. This is an explicit decision to reduce implementation overhead — no dual-writing legacy tables, no "match on either old or new field" handlers, no migration-through-mixed-network testing.

What we DO preserve:
- **Local upgrade path.** A user upgrading their own install from 0.5 → 0.6 must not lose data. Existing posts, follows, keys, blobs continue to work. Migration is one-way (users don't downgrade) but must be data-safe.
- **Free wire-level compat.** If a protocol field is already `#[serde(default, skip_serializing_if = "Option::is_none")]`, new fields simply follow that pattern. Old serialized data with missing new fields deserializes fine. No special effort.
- **User data interop across versions.** An exported 0.5 identity bundle must be importable into 0.6.

What we DROP:
- Dual-writing deprecated tables during a phase transition. When a phase swaps out a data structure, the old one is gone.
- "Works with v0.5 peers" testing. Beta is tested against beta.
- Legacy wire-protocol tolerances beyond what serde defaults give for free.

Each phase is a standalone release. Phases are ordered to satisfy internal code dependencies, not wire-compat boundaries. After all phases ship, 0.7.0-beta consolidates and 0.7.x becomes the candidate for the next stable promotion.

---

## Phase 1 (v0.6.0-beta): Remove direct `PostPush` for encrypted posts

**Goal:** Eliminate the sender→recipient traffic signal. Encrypted DMs propagate via the existing ManifestPush / CDN tree, indistinguishable on the wire from any other encrypted post.

**Scope:**
- Remove `push_post_to_recipients` from `crates/core/src/node.rs` entirely
- Remove the `PostPush` message handler from connection.rs and/or leave it as a stub that logs + ignores (avoid needing to invent a new message type ordering)
- Ensure new encrypted posts still trigger a normal header update on neighbor posts (existing CDN logic already does this) so they propagate
- Verify the existing ManifestPush fan-out path reaches recipients who follow the author's posting ID
- Add a "CDN delivery SLA" doc note: expect ~seconds to tens-of-seconds latency for DMs to followers; minutes worst case for offline-then-online recipients

**Verification:**
- Send an encrypted DM with two test devices. Confirm the recipient receives it without any direct-push message firing (network log inspection)
- Measure p50/p95 delivery latency on a small mesh of 0.6.0 nodes
- Confirm cold-contact DMs (non-follower) don't reach — expected until Phase 3 or comment-intro UX arrives

**Risks:**
- Non-follower DMs don't reach until later phases. Ship with UX messaging: "DMs to new contacts require either following them or commenting on their post first."

---

## Phase 2 (v0.6.1-beta): File-holder CDN + header-diff propagation

**Goal:** Replace the upstream/downstream tree with per-file flat holder sets. Prerequisite for multi-device (because upstream-toward-author doesn't work with multiple authoring network IDs).

**Scope:**
- New `file_holders` table: `(file_id, peer_id, last_interaction_ms, direction)` — direction records whether we sent or received the file with this peer, for potential reuse
- Populate on ManifestPush receive, blob fetch, blob serve, engagement diff exchange
- Cap per file_id at 5 holders (LRU on `last_interaction_ms`)
- Refactor engagement diff delivery: instead of "send to upstream," send to the file's up-to-5 known holders
- **Drop `post_upstream` and `post_downstream` tables in this phase's migration.** No dual-write. (Local upgrade safety: before-drop, scan these tables to seed the new `file_holders` table with any existing peer relationships so we don't start empty.)
- ManifestPush propagation logic: when header of file A changes, look up A's holders, send diff to them
- Receiver behavior: apply header diff, pull any referenced new files

**Wire protocol:**
- `BlobHeaderDiff` and `ManifestPush` messages stay the same on the wire
- What changes is the sender's list of destinations (was: upstreams; now: holders)

**Local migration (user upgrading 0.6.0 → 0.6.1):**
- On first startup with new schema, read `post_upstream` + `post_downstream`, populate `file_holders` with those peers as initial holders for their respective posts
- Drop the old tables after the seed migration
- User's existing posts, follows, blobs all untouched

**Verification:**
- Mesh test: create a post, track its propagation; confirm holders accumulate up to 5 diverse peers
- Engagement propagation: a reaction on a deeply-nested post still reaches the author (now: via the post's holders)
- Migration test: upgrade a populated 0.6.0 DB to 0.6.1; confirm existing posts still have at least one holder in `file_holders`

**Risks:**
- Churn in holder sets during network instability (holders going offline trigger LRU replacement). Need soak testing.
- Potential duplicate diff delivery if holder sets overlap. Idempotent application is already required by existing code.

---

## Phase 3 (v0.6.2-beta): Merged pull + recipient-match

**Goal:** Nodes can find DMs addressed to them without a distinguishable "searching for DMs" traffic pattern. Handles the case where a DM exists on a peer you're connected to but you don't follow the author.

**Scope:**
- Add index on `wrapped_key.recipient` in storage (migration)
- Extend `PullSyncRequestPayload` handling: peer returns posts matching `author ∈ query_ids` OR `wrapped_key.recipient ∈ query_ids`
- Client: always include own NodeId in the pull query's NodeId list
- No new message type; existing PullSync handler gets smarter
- UX: no user-visible change (pull is internal)

**Wire protocol:**
- No wire format change. Same fields, broader server-side matching logic.

**Verification:**
- Send a DM from A to B where A is not followed by B. Verify B receives it on next pull cycle (via the recipient-match).
- Benchmark pull query cost with the new OR-clause. Should be near-zero with the index.

**Risks:**
- Query cost grows with posts held × recipient list length. Index is mandatory.
- Peer can keep a log of "query included NodeId X" — tied to your connection anyway, not new info.

---

## Phase 4 (v0.6.3-beta): Posting-key / network-key split

**Goal:** Decouple signing identity from network identity. Foundation for multi-device and multi-persona. This phase ships WITHOUT UI for creating multiple personas — it's the plumbing.

**Scope:**
- `PostingIdentity` struct in `crates/core/src/types.rs`: `{ node_id, secret_seed, display_name, created_at }`
- Storage: `posting_identities` table (list of all held posting keys), `active_default_posting_id` setting
- Storage: migrate existing identity → single posting identity with the same key as the network key (no behavior change for existing users)
- `crypto.rs`: separate signing primitives — `sign_with_posting_key` vs `sign_with_network_key`. Keep existing `sign_manifest` working by delegating to posting-key variant when available
- `Node`: load posting keys alongside network key at startup
- `BlobHeader.author`: populated from posting key (was: network key, but they were equal)
- Posts signed with posting key; connections still use network key
- Export/import bundle includes posting key (in addition to network key)
- Wire: no new message types; `InitialExchange` doesn't need to change because posting IDs are only relevant for signed content, not connection setup

**Wire protocol:**
- `BlobHeader` already has an `author` field. We just populate it from posting key instead of network key.
- First-run migration for upgrading users: existing identity becomes the first posting identity. `posting_id == network_id` for pre-split content. Users can create additional posting identities after the upgrade.

**Verification:**
- Existing identity still works; no data loss after 0.5→0.6 migration chain
- Posts authored before the upgrade still render and validate
- New posts use posting key; confirm signatures verify with the posting key

**Risks:**
- Signature verification regression if `author` field handling changes subtly. Needs unit tests for both "legacy author = network key" and "posting key ≠ network key" cases.
- Storage migration needs transaction safety.

---

## Phase 5 (v0.6.4-beta): Multi-persona UX

**Goal:** Let users create and use multiple posting identities with clean UX.

**Scope:**
- IPC: `list_posting_identities`, `create_posting_identity(name, avatar)`, `set_default_posting_identity(id)`, `delete_posting_identity(id)`
- Frontend: Settings > Personas page with create/list/delete
- Compose box: persona picker (avatar + name + dropdown)
- Contextual defaults: posting to a circle uses that circle's last-used persona
- Feed: merged view, filter pills per persona
- Reply/comment: default persona = whichever decrypted the post
- Subtle per-post labels showing which persona's follow surfaced each item

**Wire protocol:**
- No changes (posting keys are already supported from Phase 4)

**Verification:**
- Create three personas, post from each, confirm peers see three distinct authors
- DM each persona from a peer; confirm messages route to separate inbox threads locally
- Social graph separation test: follow one peer from Persona A and a different peer from Persona B; confirm merged feed shows both but filter isolates each

**Risks:**
- UX complexity regression — the merged feed with filters is non-trivial. Start with two-persona users and expand.
- Existing users with single identity should see ZERO UI change until they opt in to creating a second persona.

---

## Phase 6 (v0.6.5-beta): Ephemeral rotating DM IDs + local archive

**Goal:** Maximum traffic-graph concealment for DMs. Each thread gets a rotating posting ID, messages include handshake for the next ID, local archive preserves history.

**Scope:**
- Per-thread ephemeral posting ID generation
- Handshake field in encrypted post payload: `next_posting_id: SecretSeed`
- Sliding window of last 10 accepted IDs per thread
- Local archive post: encrypted-to-self, replicates across user's linked devices via the multi-device shared-posting-key mechanism
- UX: DMs appear as continuous thread in the UI despite wire-level rotation
- Group thread rotation

**Wire protocol:**
- No new message types — ephemeral posting IDs are just short-lived posting keys. The handshake field lives inside the encrypted payload.

**Verification:**
- Observer test: capture a DM thread's wire traffic; confirm no cryptographic tie between successive messages
- Resilience: drop a message mid-thread; confirm the next message catches up via the sliding window
- Archive test: scroll back through a 100-message thread; confirm all messages visible via local archive even though wire-level IDs are long forgotten

**Risks:**
- Complexity of rotation + archive is high. Lots of state to get right.
- UX: users need to understand that "they can't recover messages from a new device without importing the archive" — this is true already for any encrypted history, but doubly so here.

---

## Version promotion plan

- **0.5.3 is stable.** Last stable of the pre-split architecture. Maintenance-only (critical bugs, security). No new features.
- **0.6.0 through 0.6.5** are beta releases shipping Phases 1-6. Beta users form a network distinct from stable users.
- **0.7.0-beta** consolidates the complete new architecture; the legacy code paths are already removed as each phase shipped, so 0.7.0 is mostly polish + integration testing.
- **0.7.x-beta** gets real-world soak testing.
- **0.7.N → stable** once the new architecture is proven.

No "migration bridge" version is needed between 0.5 stable and 0.6 beta — users choose a track. Moving between tracks is possible via the existing export/import identity bundle (users can carry their content across, because the bundle format is preserved as a free compat concern).

## Order-of-operations recommendations

- Phases 1 and 2 can overlap (CDN restructure can happen while PostPush is being removed — they touch different code paths).
- Phase 3 depends on Phase 2 being in place (the file-holder refactor touches pull handling).
- Phase 4 is a prerequisite for 5 and 6 but doesn't need to wait for 1-3 (it's local/storage only, wire protocol unchanged).
- Phase 5 UX should wait for Phase 4 to ship and stabilize so persona-aware code is well tested.
- Phase 6 is the most complex; ship last.

## What must not regress

- Existing users upgrading from 0.5.3 should see no behavior change until they explicitly opt in to new features.
- Cross-version interoperability is required at every phase boundary.
- Data integrity: all migrations must be transaction-safe and reversible (keep old tables until N+1 phase).

## Not in scope for 0.6.x

- Search/discovery improvements (existing Worm still used)
- Anchor/directory redesign (separate planned track)
- Erasure-coded CDN replication (separate planned track)
- Reciprocity / Phase 2 economic features (still deferred)