Toju/emergency-fix/08-messaging-visibility.md

08 — Messaging visibility (“messages not seen”)

User theme: “I sent a message but they don’t see it / history missing / only some devices have chat.”
Severity: P0.

---

How messaging is supposed to work (user view)

Server text channels

• Send in a text channel → everyone currently in that community sees it quickly.
• If someone was offline or just joined, they still get recent history after connecting to peers (or from their other logged-in device).
• Edits, deletes, reactions converge.
• Typing indicators are ephemeral.
• The signal server does not keep a chat log — history lives on clients.

Direct messages

• 1:1 and group DMs deliver even without a shared community when signaling can reach the peer.
• Delivery ticks: queued → sent → delivered → acknowledged (monotonic).
• Offline: queue until peer/network returns.

Multi-device

• Second device receives live + catch-up via account_sync when siblings are online.

---

How messaging is supposed to work (system)

Path	Role
P2P chat-message / revisions	Primary live + sync plane
WS chat_message	Narrow live fallback to room members
Inventory / sync-batch	Catch-up on DC (limit 20_000, chunk 200)
account_sync chat batches	Sibling devices
DM PeerDelivery	DC → signaling → offline queue

Feature contract: agents-docs/features/messaging.md.
Domain: domains/chat/, domains/direct-message/, store/messages/.

---

Failure modes

1 — Invisible membership → no live fallback

If identify/join failed (04/05), user is not in server membership → server never broadcasts chat_message to them; peers may not offer DC. Classic “chats don’t sync for multi-client users” root cause (serialized identify).

2 — Live works, history doesn’t

DC down: live WS fallback OK; inventory never runs → “they only see new messages after refresh if a peer happens to sync later” / empty history for late joiners.

3 — Sync poll too slow after “clean” cycle

Fast poll 10s while catching up; 15 min when clean. A false “clean” leaves long windows without repair.

4 — Cross-signal identity forks DMs

Incoming DM conversationId carries foreign actor id → second empty thread; replies invisible on the thread the user is watching (09). Lessons claim canonicalize/merge — symbols not in tree.

5 — Recipient alias miss

DM/call ignored if local admission only checks home id. Inbound DM aliases largely fixed; verify call + any new surfaces.

6 — Attachment-only emptiness

Message text arrives; image stuck “Waiting…” — announce/bind race (lesson). Looks like “message incomplete / not really received.”

7 — NgRx prune confusion

Inactive rooms pruned to 100 messages in memory; DB still has more. User switching rooms may think history vanished until reload/sync — document vs bug.

8 — Doc lie on inventory cap

Chat domain README still says 1000; code INVENTORY_LIMIT = 20_000.

---

Investigation checklist (agents)

1. Did both users identify + join_server on the same signal URL as the room?
2. Is there an open DC between them? (connectedPeers, debug metrics)
3. Does live send emit both DC and chat_message?
4. On receive, is roomId in saved/current rooms?
5. For DM: conversation id aliases; delivery state machine stuck at QUEUED?
6. Multi-device: account_sync_peer_online fired; batches received?

---

Proof of done

1. Two clients: send N messages with DC disabled (force) → live still appears via WS.
2. Re-enable DC → inventory brings missing history.
3. Third client late join → receives recent history from a peer with DB.
4. Cross-home users in foreign room: messages visible both ways without authorize prompt.
5. Cross-signal DM: single conversation thread; replies visible to both.
6. Multi-device: second device gets chat-sync-batch after identify.
7. Regression covering identify-before-join (presence + chat broadcast).

---

Fix order

1. Auth + identify (04/05) — without presence, messaging “fixes” are theater.
2. Ensure fallback + DC resync on repair (07).
3. Identity canonicalize for DMs (09).
4. Attachment re-queue invariants.
5. Correct stale chat README inventory number.