passepartout/docs/rca/rca-gateway-matrix.org

Root Cause Analysis: Matrix Gateway & Communication Track Completion

• Executive Summary
• 1. Issue: Symbol Casing in JSON Keys
  • Symptoms
  • Root Cause
  • Resolution
• 2. Issue: Since Token Extraction Failure
  • Symptoms
  • Root Cause
  • Resolution
• 3. Issue: Type Error in Authorization Headers
  • Symptoms
  • Root Cause
  • Resolution
• 4. Completion: Communication Track
• 5. Permanent Learnings

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.