stack/tools/matrix-presence-harness/README.md

tools/matrix-presence-harness — RFC-001 P1 validation (A1–A5)

DEV-ONLY. LOCAL SANDBOX. Drives the local infra/matrix Synapse only. Never point it at live infra.

The dev validation harness for the presence slice. It is the minimal P1 provisioner + an end-to-end demo that proves the acceptance criteria against a real Synapse.

Pieces

• provision.ts — the minimal provisioner: registers ≥3 agent MXIDs, creates the fleet presence room, joins the agents. Reuses the existing tested @mosaicstack/appservice intent library (register / createRoom / join). It is deliberately not the P2 appservice (no auto-enroll / taxonomy / token minting).
• agent-proc.ts — one presence agent as its own OS process (via @mosaicstack/comms): joins the fleet room and heartbeats mosaic.presence. Standalone so the harness can SIGKILL it for a true hard-kill (A3).
• validate.ts — provisions, spawns the agents, then asserts:
  • A2 ≥3 agents show online in the fleet room.
  • A3 a SIGKILL'd agent flips to offline within dark_threshold, deterministically (heartbeat-age based, not native-presence timeout), while survivors stay online.
  • A4 prints the human-readable fleet liveness board.
• run.sh — wires dev secrets + env and runs validate.ts over the self-signed TLS endpoint (A1). Exits non-zero on any failed assertion.

Usage

../../infra/matrix/dev-up.sh     # bring Synapse up first
./run.sh                         # provision + validate (A2/A3/A4)

Tunables (env): HEARTBEAT_INTERVAL_MS (1000), MISS_TOLERANCE (2), DARK_THRESHOLD_MS (6000), AGENT_SLUGS (alpha,bravo,charlie), VICTIM_SLUG (charlie), MATRIX_CS_URL (defaults to the TLS endpoint).

Note on NODE_TLS_REJECT_UNAUTHORIZED=0

run.sh sets this only because the dev homeserver uses a self-signed cert. It is a dev convenience for exercising the SDK over TLS and must never be used against a real CA-issued endpoint.