41 lines
2.2 KiB
Org Mode
41 lines
2.2 KiB
Org Mode
#+TITLE: Root Cause Analysis: Matrix Gateway & Communication Track Completion
|
|
#+DATE: 2026-04-11
|
|
#+FILETAGS: :rca:gateway:matrix:chat:autonomy:
|
|
|
|
* Executive Summary
|
|
Successfully implemented the third and final external communication channel (Matrix) for OpenCortex 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 OpenCortex 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.
|