itsgoin/IMPLEMENTATION_PLAN_0.6.md

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

Context

0.5.3-beta is graduating to 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

Each phase below is a standalone release. Each phase is backward compatible with peers on earlier versions (they degrade gracefully or stay on the old path). 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 or gate push_post_to_recipients in crates/core/src/node.rs
• Ensure new encrypted posts still trigger a normal header update on neighbor posts (already done by existing CDN logic) so they propagate
• Verify the existing ManifestPush fan-out path reaches recipients who follow the author's posting ID (today they do since follows pull posts)
• 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
• Backward compat: verify a v0.6 client can DM a v0.5 client and vice versa

Risks:

• Latency regression for non-follower recipients (they won't get it until Phase 3 or comment-intro shipping). For Phase 1, keep the push path behind a compile flag for non-follower recipients if safety is a concern — or explicitly document that "DMs to non-followers don't reach yet; follow or comment on their post"

---

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
• Keep post_upstream / post_downstream tables for compat reads during the transition
• 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)

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)
• Backward compat: a v0.6.1 sending to a v0.6.0 holder should still work (v0.6.0 applies header diff normally)

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.
• Backward compat: a v0.6.2 pulling from a v0.6.1 peer still works (peer ignores the "recipient match" intent since it only indexes author)

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.
• For mixed-version networks: v0.6.3 posts signed by a posting_id that happens to equal the author's network_id are indistinguishable from v0.6.2 posts. Backward compat is automatic.
• First-run migration: existing users have network_id == posting_id. Nothing changes for them until they explicitly create a second persona.

Verification:

• Existing identity still works; no data loss
• Posts from upgraded clients still validate on older clients
• Posts from older clients still decrypt and render on upgraded clients

Risks:

• Signature verification regression if author field handling changes subtly. Need extensive cross-version testing.
• 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-beta → stable (this work). Last stable of the pre-split architecture.
• 0.6.0 through 0.6.5 are beta releases shipping Phases 1-6.
• 0.7.0-beta consolidates and cleans up deprecated code paths (post_upstream/downstream tables dropped, old push code removed).
• 0.7.x-beta gets real-world soak testing as the full new architecture.
• 0.7.N → stable once the new architecture is proven.

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)