# 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

```bash
# 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

1. Prefer **feature docs + code** over domain README diagrams when they conflict.
2. Prefer **code + specs** over LESSONS examples when symbols missing.
3. When fixing behavior, **fix the lying doc in the same PR**.
4. When a lesson was aspirational, relabel it explicitly so the next agent does not skip the work.