myxelium
e49b3ec112
- `LIVE_RELOAD=false npm run dev` keeps the renderer alive across a machine suspend; the reload client otherwise destroys the session under test. - `dev-peer.sh` plus a separate userdata dir runs a second local peer. - `tools/voice-probe.js` samples peer state and RTP counters from a live window, persisting to localStorage so a renderer reload cannot erase it. - e2e helpers for voice pairs, peer-role election, and a TURN relay. - Electron single-instance and dev-client-load decisions move into rules files with colocated specs.
3.8 KiB
10 — Code lies & documentation debt
Agents must verify symbols in the tree before trusting lessons or READMEs. This file lists known mismatches found 2026-08-12.
Critical lies (behavior-affecting)
L1 — Soft data-channel replace (docs yes, code no)
Claims: toju-app/.../realtime/README.md (Data channel section), agents-docs/features/voice-webrtc.md.
Reality: repairUnavailableDataChannel always removePeer + reconnect. replaceDataChannel not used by recovery; specs expect it not called.
Action: Either implement soft replace or rewrite docs in the same PR as the recovery decision (07).
L2 — LESSONS outbound call routing “fixed”
Claims: LESSONS.md — peer-delivery-identity.rules.ts, collectRecipientDeliveryCandidateIds, pickRoutableRecipientId, resolveRoutableRecipientId, call.errors.recipientUnreachable.
Reality: No matches in toju-app/. Phantom APIs.
Action: Implement (09) or rewrite lesson as “desired / unfinished” with Status.
L3 — LESSONS DM conversation canonicalize “fixed”
Claims: resolveDirectConversationId, mergeAliasDirectConversations, direct-message-conversation-identity.rules.ts, etc.
Reality: Absent. Only narrower direct-message-identity.rules.ts.
Action: Same as L2.
L4 — Home identify credentials used as “local peer id” for negotiation
Claims: Deterministic initiator from logical peer ids (implies per-room identity).
Reality: getIdentifyCredentials() returns home credential; used for polite peer / localOderId paths while presence uses actor ids.
Action: Fix in voice/identity packets (06/09); update README after.
Medium lies (wrong paths / stale numbers)
L5 — Authentication domain README API paths
Claims: POST /api/auth/login, /api/auth/register.
Reality: /api/users/login, /api/users/register.
L6 — Chat domain README inventory cap
Claims: capped at 1 000 messages.
Reality: INVENTORY_LIMIT = 20_000 (messaging feature doc correct).
L7 — shared-kernel/signaling-contracts.ts as wire authority
Claims (implicit): types like join / leave / chat / ice-candidate.
Reality: Feature signaling.md correctly says do not treat as authoritative. Live types use join_server, chat_message, ice_candidate, etc.
Action: Mark file deprecated or align types; never generate client sends from it blindly.
Soft / incomplete docs (not lies, but traps)
| Topic | Note |
|---|---|
| Auth feature doc vs missing secret | Doc describes intended offline/authorize rules; primary bug is still open (user story). |
| TURN | Documented STUN-only defaults — accurate; users may think voice “should always work on restrictive NAT”. |
| Domain auth README | Oversimplified sequence diagram (no provision secret / multi-credential). |
| Handoff silent auth | Accurate research; not a code lie — unfinished work. |
Verification commands for agents
# Phantom lesson APIs (should be empty until implemented)
rg -n 'pickRoutableRecipientId|resolveDirectConversationId|mergeAliasDirectConversations|peer-delivery-identity' toju-app
# DC recovery behavior
rg -n 'repairUnavailableDataChannel|replaceDataChannel' toju-app/src/app/infrastructure/realtime
# Inventory limit
rg -n 'INVENTORY_LIMIT' toju-app/src/app/domains/chat
# Auth paths
rg -n 'users/login|auth/login' toju-app/src/app/domains/authentication
Policy for this emergency
- Prefer feature docs + code over domain README diagrams when they conflict.
- Prefer code + specs over LESSONS examples when symbols missing.
- When fixing behavior, fix the lying doc in the same PR.
- When a lesson was aspirational, relabel it explicitly so the next agent does not skip the work.