feat(broker+cli): topics — conversation scope within a mesh (v0.2.0)
Some checks failed
CI / Lint (push) Has been cancelled
CI / Typecheck (push) Has been cancelled
CI / Broker tests (Postgres) (push) Has been cancelled
CI / Docker build (linux/amd64) (push) Has been cancelled

Adds the third axis of mesh organization: mesh = trust boundary,
group = identity tag, topic = conversation scope. Topic-tagged
messages filter delivery by topic_member rows and persist to a
topic_message history table for back-scroll on reconnect.

Schema (additive):
- mesh.topic, mesh.topic_member, mesh.topic_message tables
- topic_visibility (public|private|dm) and topic_member_role
  (lead|member|observer) enums
- migration 0022_topics.sql, hand-written following project convention
  (drizzle journal has been drifting since 0011)

Broker:
- 10 helpers (createTopic, listTopics, findTopicByName, joinTopic,
  leaveTopic, topicMembers, getMemberTopicIds, appendTopicMessage,
  topicHistory, markTopicRead)
- drainForMember matches "#<topicId>" target_specs via member's
  topic memberships
- 7 WS handlers (topic_create/list/join/leave/members/history/mark_read)
  + resolveTopicId helper accepting id-or-name
- handleSend auto-persists topic-tagged messages to history

CLI:
- claudemesh topic create/list/join/leave/members/history/read
- claudemesh send "#deploys" "..." resolves topic name to id
- bundled skill teaches Claude the DM/group/topic decision matrix
- policy-classify recognizes topic create/join/leave as writes

Spec: .artifacts/specs/2026-05-02-v0.2.0-scope.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
2026-05-02 01:53:42 +01:00
parent b4f457fceb
commit 1afae7a507
12 changed files with 1741 additions and 196 deletions

View File

@@ -36,6 +36,31 @@ Every broker-touching verb runs through a policy gate before dispatch. The defau
**Convention:** every operation is `claudemesh <resource> <verb>`. Legacy short forms (`send`, `peers`, `kick`, `remember`, ...) are aliases that keep working forever; prefer the resource form for new code.
### `topic` — conversation scope within a mesh (v0.2.0)
A topic is a named conversation inside a mesh. Mesh = trust boundary. Group = identity tag. **Topic = what you're talking about.** Subscribers receive topic-tagged messages; non-subscribers don't. Topics also persist message history so humans (and opting-in agents) can fetch back-scroll on reconnect.
```bash
claudemesh topic create deploys --description "deploy + on-call"
claudemesh topic create incident-2026-05-02 --visibility private
claudemesh topic list # all topics in mesh
claudemesh topic join deploys # subscribe (by name or id)
claudemesh topic join deploys --role lead # join as lead
claudemesh topic leave deploys
claudemesh topic members deploys # list subscribers
claudemesh topic history deploys --limit 50 # fetch back-scroll
claudemesh topic history deploys --before <msg-id> # paginate older
claudemesh topic read deploys # mark all as read
# Send to a topic — same `send` verb, target starts with #
claudemesh send "#deploys" "rolling out 1.5.1 to staging"
```
When to use topics vs groups vs DM:
- **DM** (`send <peer>`) — 1:1, ephemeral.
- **Group** (`send "@frontend"`) — addresses everyone in a group; ephemeral; for coordinating teams.
- **Topic** (`send "#deploys"`) — durable conversation room; for ongoing work threads, incident channels, build-status feeds.
### `peer` — read connected peers + admin (kick / ban / verify)
```bash