You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit b789548
Browse filesBrowse the repository at this point in the historyBrowse files
Ian Oberst
committed
Merge remote-tracking branch 'upstream/main' into Areson/pgschema-ignore-runtime-partitions
* upstream/main:
feat(relay): add announce channels with a join_role setting (#8143)
fix(mobile): keep token labels visible in authored Markdown links (#7545)
test(relay): cover system channels in the workflows API and push matcher (#8509)
fix(relay): push system channel events to a lease that names them (#8517)
fix(relay): scope push matches with the read path's channel rule (#8507)
feat(ws-client): send custom headers on the WebSocket upgrade (#8159)
feat(mobile): show inline human typing and outgoing avatars (#8505)
BUZZ-357: feat(cli): token-lean agent output format for event reads (#8234)
fix(desktop): surface a missing DATABRICKS_HOST instead of loading models forever (#8504)
feat(audio-client): accept a client request in connect (#8497)
fix(mobile): lazily lay out new-DM recipients (#8435)
fix(mobile): lazily lay out channel member groups (#8437)
perf(mobile): retain preference crypto across reconnects (#8442)
fix(deps): bump webpki crates for RUSTSEC-2026-0381/0382/0383 (#8499)
fix(mobile): simplify and refine the quick actions menu (#8491)
fix(sdk): reject malformed mention pubkeys before signing p tags (#6372)
fix(mobile): resolve DM display labels once per sort (#8488)
docs(db): database target architecture and schema-change rules (#8273)
fix(mobile): restore channel icons and align chat colors with desktop (#8478)
Signed-off-by: Ian Oberst <[email protected]>
# Conflicts:
# AGENTS.md
Copy file name to clipboardExpand all lines: AGENTS.md
+15-4Lines changed: 15 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,12 @@ Before planning or reviewing a non-trivial change:
14
14
2. Read the `VISION_*.md` documents relevant to the affected product surface.
15
15
3. Read the applicable guidance in [TESTING.md](TESTING.md) and any
16
16
package-local `TESTING.md`.
17
-
4. Check that the proposed design advances, or at least does not contradict,
17
+
4. For any change to `migrations/`, `schema/`, or schema-dependent `buzz-db`
18
+
queries, read [docs/database.md](docs/database.md): no new triggers,
19
+
functions, or foreign keys; no data backfills in migrations; update every
20
+
schema location; and keep every migration compatible with the relay that
21
+
is currently deployed.
22
+
5. Check that the proposed design advances, or at least does not contradict,
18
23
that product intent. Call out any intentional tension explicitly.
19
24
20
25
Implementation describes the product today; the vision documents describe the
@@ -128,7 +133,8 @@ crates/
128
133
desktop/ # Tauri 2 + React 19 desktop app
129
134
web/ # Browser web client (repo browser, served by the relay)
130
135
mobile/ # Flutter mobile app
131
-
migrations/ # SQL migrations (auto-applied on relay startup)
136
+
migrations/ # SQL migrations (run at relay startup when BUZZ_AUTO_MIGRATE is on: binary default off, Helm default on; deployments at scale apply them out of band — see docs/database.md)
137
+
schema/ # Desired-state schema (schema/tables/public/ is the declarative schema source)
132
138
scripts/ # Dev tooling
133
139
.env.example # Config template — copy to .env before running
`--format compact` is a **global** flag — it goes before the subcommand:
374
+
`--format` is a **global** flag — it goes before the subcommand:
369
375
`buzz --format compact channels list`, NOT `buzz channels list --format compact`.
376
+
Without the flag it falls back to `BUZZ_OUTPUT_FORMAT` (unknown values mean
377
+
`json`); buzz-acp sets that to `agent` for agent
378
+
processes, so their event reads drop `sig`, trim the NIP-OA `auth` tag to
379
+
`["auth", <owner>]`, and fold the NIP-10 `root`/`reply` tags into `reply_to`
380
+
(plus `thread_root` on nested replies); other tags remain.
370
381
371
382
See `crates/buzz-cli/TESTING.md` for the full live-testing runbook.
372
383
@@ -602,7 +613,7 @@ description. See [PR #803](https://github.com/block/buzz/pull/803).
602
613
4.**Worktrees: `cd` in the same command** — shell CWD doesn't persist between tool calls. Use `cd /path && cargo build` as one command.
603
614
5.**Desktop crate excluded from root workspace** — `cargo test` at repo root does NOT run desktop tests. Use `cargo test --manifest-path desktop/src-tauri/Cargo.toml` explicitly.
604
615
6.**React render perf: `React.memo` is all-or-nothing** — it only skips a re-render when *every* prop is reference-stable; one unstable prop (inline arrow/JSX, or a hook returning a fresh `{}`/`[]`/`Map` each render) defeats it. Two repeat offenders: (a) React Query results (`useMutation`/`useQuery`) are a **new object each render** — depend on the stable method (`mutation.mutateAsync`), not the object; (b) derived `Map`/array state that recomputes on a version bump — wrap in a content-equality ref cache (`shared/hooks/useStableReference.ts`). When chasing interaction lag, **measure with DevTools closed and no perf probes** (an open Web Inspector + per-keystroke `console.log` inflate the numbers), and isolate by removing one suspect at a time rather than guessing.
605
-
7. **`pgschema` omits seed DML and some storage parameters** — `schema/schema.sql` is an ordered `\i` manifest: `schema/tables/public/<table>.sql` holds only that table's `CREATE TABLE` and `CREATE INDEX` statements (one table per file, the shape SchemaBot reads), and types, functions, partitions, triggers, and seed rows live in the sibling `schema/` directories. Fresh desired-state bootstraps use `./bin/pgschema apply`, which does not execute `INSERT` statements or preserve every table storage parameter from `schema/schema.sql`. Put each unsupported invariant in `scripts/reconcile-schema-after-pgschema.sql` as an idempotent convergence statement plus a live catalog or data assertion. Every `pgschema apply` caller must run that script, and must run pgschema from the repository root so it reads `.pgschemaignore`; from any other directory a re-apply plans to drop the partitions the relay created at runtime. A string assertion against `schema.sql` alone does not prove the pgschema-created database has the intended state.
616
+
7. **`pgschema` omits seed DML and some storage parameters** — `schema/schema.sql` is an ordered `\i` manifest: `schema/tables/public/<table>.sql` holds only that table's `CREATE TABLE` and `CREATE INDEX` statements (one table per file, the shape out-of-band schema tools read), and types, functions, partitions, triggers, and seed rows live in the sibling `schema/` directories. Fresh desired-state bootstraps use `./bin/pgschema apply`, which does not execute `INSERT` statements or preserve every table storage parameter from `schema/schema.sql`. Put each unsupported invariant in `scripts/reconcile-schema-after-pgschema.sql` as an idempotent convergence statement plus a live catalog or data assertion. Every `pgschema apply` caller must run that script, and must run pgschema from the repository root so it reads `.pgschemaignore`; from any other directory a re-apply plans to drop the partitions the relay created at runtime. A string assertion against `schema.sql` alone does not prove the pgschema-created database has the intended state.
|**User profiles (kind:0)**| ✅ | NIP-01 metadata; synced to users table (display_name, avatar, about, NIP-05). NIP-05 handles must canonicalize to this relay's domain — off-domain or invalid handles are silently cleared. If a NIP-05 handle collides with another user's (UNIQUE constraint), the handle is skipped but other profile fields (display_name, avatar, about) are still synced. |
53
53
|**Group creation (kind:9007)**| ✅ | NIP-29; include `name` tag, optional `visibility`, `channel_type` and label `t` tags |
54
-
|**Add user (kind:9000)**| ✅ | Open: any user, subject to target's `channel_add_policy` (`owner_only`/`nobody` can block). Private: owner/admin only. Self-add bypasses agent policy but not private-channel auth. |
54
+
|**Add user (kind:9000)**| ✅ | Open: any user, subject to target's `channel_add_policy` (`owner_only`/`nobody` can block). Private: owner/admin only. Self-add bypasses agent policy but not private-channel auth. A guest cannot add anyone. A new member with no role tag gets the channel's `join_role`; a non-member adding themselves may ask for `join_role` or a lower role. |
|**Edit group metadata (kind:9002)**| ✅ |`name`/`about`/label `t` tags: owner/admin. `topic`/`purpose` tags: any member. |
56
+
|**Edit group metadata (kind:9002)**| ✅ |`name`/`about`/label `t`/`visibility`/`ttl`/`archived`/`join_role` tags: owner/admin. `topic`/`purpose` tags: any member except a guest. Buzz applies 9002 as a partial update: an absent tag leaves that setting unchanged. |
57
57
|**Admin delete event (kind:9005)**| ✅ | Event author can always delete own. Otherwise owner/admin required. Target must be in same channel. |
|**Leave group (kind:9022)**| ✅ | Any member. Last-owner guard prevents orphaned groups. |
60
-
|**Group metadata (kind:39000)**| ✅ | Relay-signed; always `d`, `name`, `closed`, `["t", <channel_type>]`, `["P", <creator>]` and `["created_at", <unix seconds>]` tags; `about` only if description non-empty; `private` if applicable; `hidden` for DM channels and private system channels |
60
+
|**Group metadata (kind:39000)**| ✅ | Relay-signed; always `d`, `name`, `t`, `P`, `created_at`, `join_role`; `public` or `private`; `restricted` and `closed` per the access flags below; `about` only if description non-empty; `hidden` for DM channels and private system channels |
61
61
|**Group admins (kind:39001)**| ✅ | Relay-signed; `d`, channel type `t` and creator `P` tags + `p` tags with roles (`owner`, `admin`) |
62
62
|**Group members (kind:39002)**| ✅ | Relay-signed; `d`, channel type `t` and creator `P` tags + `p` tags for all members |
|**NIP-17 DMs (gift wrap)**| ✅ | kind:1059 accepted with ephemeral signing keys. Stored community-globally (`channel_id=None` inside the connected community). Delivered via `#p`-filtered subscriptions. Not indexed in search. |
73
73
|**DM discovery**| ✅ | DM creation emits kind:39000 (with `hidden` tag) + kind:44100 membership notifications. NIP-29 clients discover DMs via standard group discovery flow. |
74
-
|**Join request (kind:9021)**| ✅ | Open channels only. Adds member, emits system message + group discovery events + kind:44100 membership notification. Private channels rejected at ingest. |
74
+
|**Join request (kind:9021)**| ✅ | Open channels only. Adds the joiner with the channel's `join_role` (`member` by default), emits system message + group discovery events + kind:44100 membership notification. Private channels rejected at ingest. |
75
75
|**Edits (kind:40003)**| ⚠️ | Works on the wire but Buzz-only — no standard NIP-29 client renders these |
76
76
|**Rich content (kind:40002)**| ⚠️ | Works on the wire but Buzz-only — no standard NIP-29 client renders these |
77
77
@@ -100,6 +100,61 @@ relay to specific external Nostr identities without granting full access.
100
100
SELECT encode(pubkey, 'hex'), added_at, note FROM pubkey_allowlist;
101
101
```
102
102
103
+
### Announce channels
104
+
105
+
Roles have the same permissions in every channel. A channel's settings
106
+
decide only who can join and which role a new person gets:
107
+
108
+
-`visibility` (`open` | `private`) decides who can find, join and read.
109
+
-`join_role` (`member` | `guest`) is the role a person gets when nobody
110
+
picks one: a self-join (kind:9021, or a kind:9000 self-add), or a kind:9000
111
+
add with no `role` tag. The default, `member`, keeps today's behavior.
112
+
113
+
An open channel with `join_role = guest` is an **announce channel**: anyone
114
+
can find, read and join it, but people who join are guests and cannot write.
115
+
116
+
What each role can do:
117
+
118
+
| Action | Guest | Member or bot | Admin / owner |
The relay emits NIP-29 group state events when channels are created, updated, or membership changes.
@@ -109,7 +164,7 @@ All discovery events include a `d` tag set to the channel UUID (NIP-29 addressab
109
164
110
165
| Kind | Tags | Content |
111
166
|------|------|---------|
112
-
|**39000**|`d=<uuid>`, `name`, `closed`, `t=<channel_type>`, `P=<creator>`, `created_at=<unix seconds>`(always); `about` (if description non-empty); `private` (if applicable); `hidden` (DM channels and private system channels) | Group metadata. **Note:**`closed` is always emitted per NIP-29 convention (Buzz channels require explicit membership), but open channels are still readable/writable by non-members at runtime. The tag reflects the membership model, not access enforcement. |
167
+
|**39000**|`d=<uuid>`, `name`, `t=<channel_type>`, `P=<creator>`, `created_at=<unix seconds>`, `join_role`(always); `public` or `private`; `restricted` (private channels, and `join_role=guest`); `closed` (private channels only); `about` (if description non-empty); `hidden` (DM channels and private system channels) | Group metadata. The access flags follow the channel settings (see [Announce channels](#announce-channels)). |
113
168
|**39001**|`d=<uuid>`, `t=<channel_type>`, `P=<creator>`, `p` tags with role label (`owner`, `admin`) | Admin list |
114
169
|**39002**|`d=<uuid>`, `t=<channel_type>`, `P=<creator>`, `p` tags for all members | Member list |
115
170
@@ -156,10 +211,11 @@ out unless they ask for it:
156
211
combine with OR, so `#t:["system", <label>]` does not mean "a system
157
212
channel with this label".
158
213
159
-
Push notifications skip system channels. Every kind:44100/44101 membership
160
-
notification carries its channel type as `t`, and a filter without `#t` sees
161
-
only the legacy types, so system channel notices reach only a filter with
162
-
`#t:["system"]` (see NIP-CL).
214
+
Push notifications use the same rule: a lease filter pushes events from a
215
+
system channel only when its `#h` names that channel. Every kind:44100/44101
216
+
membership notification carries its channel type as `t`, and a filter without
217
+
`#t` sees only the legacy types, so system channel notices reach only a filter
218
+
with `#t:["system"]` (see NIP-CL).
163
219
164
220
Events are stored **channel-scoped** so access control applies — private channel member lists are
165
221
only visible to members. Discover groups via historical REQ:
0 commit comments