#+TITLE: Root Cause Analysis: Matrix Gateway & Communication Track Completion
#+DATE: 2026-04-11
#+FILETAGS: :rca:gateway:matrix:chat:psf:

* Executive Summary
Successfully implemented the third and final external communication channel (Matrix) for Org-agent v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.

* 1. Issue: Symbol Casing in JSON Keys
** Symptoms
The `TEST-MATRIX-INBOUND-NORMALIZATION` test failed because `room-id` was being extracted as `"!ROOM:HS.ORG"` (uppercase) instead of `"!room:hs.org"`.
** Root Cause
Common Lisp's default reader converts symbol names to uppercase. When `(string car-of-alist)` was called on a symbol generated by `cl-json`, it produced an uppercase string.
** Resolution
Updated the implementation to use `(string-downcase (string ...))` for room IDs and other case-sensitive Matrix identifiers.

* 2. Issue: Since Token Extraction Failure
** Symptoms
The sync loop failed to update the `*matrix-since-token*`, causing duplicate message processing risk.
** Root Cause
Anticipating `:next-batch` but receiving `:next--batch` (or vice versa) due to inconsistent `cl-json` behavior across different environments or structures.
** Resolution
Implemented a robust `(or (cdr (assoc :next-batch json)) (cdr (assoc :next--batch json)))` lookup to handle both hyphenation styles.

* 3. Issue: Type Error in Authorization Headers
** Symptoms
`dex:put` crashed with a `TYPE-ERROR`.
** Root Cause
I was passing a single string or an incorrectly nested list where `dexador` expected a strict alist of header pairs `(("Key" . "Value") ...)`.
** Resolution
Standardized all gateway HTTP calls to use proper alist nesting for headers.

* 4. Completion: Communication Track
With Telegram, Signal, and Matrix gateways now verified and passing tests, the Org-agent has achieved full multi-channel parity.
- **Telegram:** Polling via Bot API.
- **Signal:** Wrapping `signal-cli`.
- **Matrix:** Polling via `/sync` Client API.

* 5. Permanent Learnings
- **Case Sensitivity:** Matrix IDs (rooms, users) are case-sensitive; Lisp symbols are not. Always force downcasing or use strings for storage.
- **Header Alists:** Always use dotted pairs `("Key" . "Value")` for `dexador` headers.