From e706294cc50888153b1a2373c386188b69a37e53 Mon Sep 17 00:00:00 2001
From: ben <johnmosescarter@gmail.com>
Date: Tue, 14 Apr 2026 15:33:18 -0400
Subject: [PATCH] xmpp stack decision

---
 pm/tasks.org             | 10 ++++---
 pm/xmpp-lib-decision.org | 62 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 4 deletions(-)
 create mode 100644 pm/xmpp-lib-decision.org

diff --git a/pm/tasks.org b/pm/tasks.org
index 903208b..6a8f786 100644
--- a/pm/tasks.org
+++ b/pm/tasks.org
@@ -1,5 +1,6 @@
 #+title: Task Log
 #+updated: [2026-04-14 Tue 13:26]
+#+startup: overview
 
 * [X] 0.1.0: Define v0 bridge contract (estimate 1 commit)
 Write a one-page spec for the first bridge: one XMPP MUC room <-> one Zulip stream/topic, append-only relay, no edits/reactions/history sync.
@@ -49,7 +50,7 @@ Specify the minimal message metadata the bridge must preserve and the exact loop
 - pm note: this is the real core of v0; if this is fuzzy the bridge will thrash.
 
 ** evidence
-- commit:
+- commit: c72b1d8
 - tests: n/a (design note only)
 - datetime: [2026-04-14 Tue 14:40]
 - artifact: pm/0.1.1-relay-envelope-and-loop-rules.org
@@ -83,7 +84,7 @@ Confirm what kind of bot/client should be used on the Zulip side and document an
 ** notes
 - Keep this empirical; document only constraints that affect v0.
 
-* [ ] 0.1.3: Survey XMPP MUC event model + library options (estimate 1 commit)
+* [X] 0.1.3: Survey XMPP MUC event model + library options (estimate 1 commit)
 Pick the first XMPP client library/runtime and document the exact events needed for room relay.
 
 ** Acceptance Criteria
@@ -102,8 +103,9 @@ Pick the first XMPP client library/runtime and document the exact events needed
 
 ** evidence
 - commit:
-- tests:
-- datetime:
+- tests: n/a (design note only)
+- datetime: [2026-04-14 Tue 15:05]
+- artifact: pm/0.1.3-xmpp-event-model-and-library-choice.org
 
 ** notes
 - Goal is “good enough to prototype,” not perfect XMPP abstraction.
diff --git a/pm/xmpp-lib-decision.org b/pm/xmpp-lib-decision.org
new file mode 100644
index 0000000..b4f0987
--- /dev/null
+++ b/pm/xmpp-lib-decision.org
@@ -0,0 +1,62 @@
+#+title: 0.1.3 XMPP Event Model and Library Choice
+#+created: [2026-04-14 Tue 15:05]
+#+updated: [2026-04-14 Tue 15:20]
+
+* initial research and recommendation
+Slixmpp is an MIT-licensed XMPP library for Python 3.11+.
+
+It is a fork of SleekXMPP and uses Rust for some performance-sensitive modules. In practice that means:
+- Python app, not Rust app
+- usually installable via PyPI wheels
+- if wheels are unavailable, cargo may be needed to build the extension module
+- maintained enough to be a sane v0 choice
+
+For this bridge, slixmpp is the best MVP pick.
+
+* minimum viable raw xmpp
+If we do not use a library, we would need to implement the XMPP client plumbing ourselves:
+- TCP + XML stream handling
+- SASL auth
+- TLS
+- stanza parsing/serialization
+- MUC join/leave semantics
+- keepalive/reconnect handling
+- duplicate/self-message suppression rules on top
+
+Pros:
+- maximum control
+- fewer dependencies
+- easier to trim down to exactly what we need
+
+Cons:
+- you are writing a mini XMPP client anyway
+- more edge cases
+- slower to reach a reliable relay
+- easier to get auth/reconnect/MUC details subtly wrong
+
+For v0, that trade is not worth it.
+
+* event model we actually need
+| event                | use                              |
+|----------------------+----------------------------------|
+| connect/auth         | establish session                |
+| self-presence        | confirm MUC join before relaying |
+| groupchat message    | relay input                      |
+| presence join/part   | ignore or log only               |
+| subject/topic change | optional log only                |
+| disconnect/error     | reconnect handling               |
+
+* recommendation
+Use slixmpp for the XMPP side.
+
+Why:
+- it covers the protocol plumbing we do not want to hand-roll
+- it is a straightforward bot/daemon fit
+- it lets us focus on bridge behavior, not XML socket mechanics
+- it is good enough for a single-room relay MVP
+
+* summary
+Use slixmpp unless we deliberately choose to prototype a raw XMPP client first.
+
+The bridge only needs a narrow slice of XMPP. Slixmpp gives us that slice without forcing us to reinvent session management, MUC join semantics, or reconnect logic.
+