mosaicstack/stack
25
0
Fork 1
Code Issues 342 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

feat(discord): connector pilot for the Sage seat, reviewed candidate (#1509)

Browse Source 
Zero-dependency Discord connector under packages/discord: binding
validation, REST and gateway clients, pi engine adapter, journal with
append-only inbox, outbox, admissions and notices, and a run.lock
ownership record {pid, start, boot} whose identity is checked three ways
and whose cleanup is gated by STOP. CLI check|run|stop|unlock via
scripts/discord.sh; offline suite scripts/test-discord.sh (28 checks,
87 node tests).

Reviewed by rev-code-02 on #1509 over nine rounds; approved exact tree
4e0feb6758c0a7e4a71483912a8e0d3e3ec95aef at comment 26170. Corrections
(1) to (12) recorded in BUILD-LOG. No listener started, no token read,
no Discord write; the live pilot follows this commit per the brief.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
This commit is contained in:
jason.woltje
2026-09-13 01:15:37 -05:00
co-authored by Claude Fable 5.1
parent b023841c8a
commit 786e379c49
34 changed files with 4641 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/TOOLS.md
+27
View File
@@ -147,6 +147,33 @@ npm-global `mosaic` CLI; run by path. Exit codes: the launch script's own
once it runs; before that 1 could not start, 2 invalid config or seat, 4
usage. Details and the record's fields: `packages/seat/README.md`.
## Discord connector (`scripts/discord.sh`)
```bash
scripts/discord.sh check <binding>
scripts/discord.sh run <binding>
scripts/discord.sh stop <binding>
scripts/discord.sh unlock <binding>
```
One seat's conversation reachable from listed channels of one Discord
server, chat only. `<binding>` names `<dataRoot>/discord/<binding>.json`
(0600, never committed; shape in `packages/discord/fixtures/binding.example.json`).
`check` validates the binding, token file mode, context files and pi, reads
the bot, guild and channels over REST, opens and closes one gateway
connection; it sends nothing. `run` serves turns until `stop`, SIGTERM or
SIGINT and refuses to start when `STOP` exists or a delivery cannot be
reconciled. `stop` writes `STOP` and signals the running process. `unlock`
writes `STOP` and removes a `run.lock` left by a dead process; it refuses
while the owner is alive with an unverifiable identity or its record cannot be
parsed. `run` refuses a stale lock rather than reclaiming it, and releases a
claim that meets `STOP`. Records
under `<dataRoot>/discord/<binding>/`: `inbox.jsonl`, `outbox.jsonl`,
`drops.jsonl`, `admissions.jsonl`, `notices.jsonl`, write-once `turns/<id>.json`. Suite:
`scripts/test-discord.sh`.
Exit codes: 0 ok, 1 operation failed, 2 invalid data or configuration, 4
usage. Details: `packages/discord/README.md`.
## Tools (host-side)
Host-side helpers under `tools/`, outside the `scripts/` command surface.