mirror of
https://github.com/block/buzz.git
synced 2026-11-07 18:01:06 +00:00
23f75dac90
Fill all 31 stub pages scaffolded in Phase 1 with content migrated and verified from the root docs, crate READMEs, and source code: - getting-started/ (3): installation, quickstart, local relay (TESTING.md) - architecture/ (8): ARCHITECTURE.md §1–§8, one page per section - guides/ (9): development, testing, agents, workflows, self-hosting, nostr-clients (operational half of NOSTR.md), adding-event-kinds, adding-api-endpoints, releasing - reference/ (5): CLI reference verified against buzz --help and crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted), configuration, known-limitations (ARCHITECTURE §9 + conformance LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical), design-docs index - vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational banners and rewritten links Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get pointer notes marking docs/ as canonical; deletion is a follow-up. All relative links in the new tree verified to resolve. Known limitations are documented honestly, never papered over: rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README drift, one-line GOVERNANCE.md. Note: pre-commit sadscan findings reviewed as false positives (dev-default postgres URI and NIP-OA test vectors, both already on origin/main). Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
42 lines
4.3 KiB
Markdown
42 lines
4.3 KiB
Markdown
# Known Limitations
|
||
|
||
Verified gaps in the current implementation — not design aspirations. The goal of this page is **no surprises** for operators and contributors: if something is stubbed, unenforced, or drifted, it's listed here. Primary source: [`ARCHITECTURE.md` §9](../../ARCHITECTURE.md), cross-checked against code.
|
||
|
||
## Relay
|
||
|
||
| # | Limitation | Detail |
|
||
|---|-----------|--------|
|
||
| 1 | **Rate limiting is not enforced** | The `RateLimiter` trait exists in `buzz-auth`, but the only implementation is `AlwaysAllowRateLimiter` — a test stub gated behind `#[cfg(any(test, feature = "test-utils"))]`. `RateLimitConfig` defines 4 tiers (human, agent-standard, agent-elevated, agent-platform) but none are enforced. Operators should not rely on relay-side rate limiting; put limits at the proxy layer if needed. |
|
||
| 2 | **No sqlx offline query cache** | The codebase uses `sqlx::query()` (runtime-checked) rather than `sqlx::query!()` (compile-time-checked); there is no `.sqlx/` directory. SQL errors surface at runtime, not build time. |
|
||
| 3 | **No dedicated typing REST endpoint** | Typing indicators (kind 20002) are delivered via local fan-out and Redis pub/sub, but there is no REST endpoint to query current typers — `/api/presence` returns online/away status only. |
|
||
| 4 | **Huddle recording/tracks not built** | Voice, room lifecycle, and join/leave/end events are wired. Recording and per-track publishing have reserved event kinds but no producer yet. |
|
||
|
||
## Workflows
|
||
|
||
| # | Limitation | Detail |
|
||
|---|-----------|--------|
|
||
| 5 | **Approval gates not wired end-to-end (🚧 WF-08)** | The executor returns `StepResult::Suspended` and the relay has grant/deny API endpoints with DB CRUD, but the engine intercepts before creating `WaitingApproval` rows — a run that hits an approval gate is marked **Failed**. `buzz workflows approve` exists but has nothing to approve yet. |
|
||
| 6 | **`send_dm` / `set_channel_topic` actions stubbed (🚧 WF-07)** | Both actions are accepted by the workflow YAML schema but return `NotImplemented` at execution — a run that reaches one fails. Use the other five actions (see the [workflows guide](../guides/workflows.md)). |
|
||
|
||
## Conformance gate
|
||
|
||
The runtime conformance harness (`crates/buzz-conformance`) is **observation, not proof**. Its own [`LIMITS.md`](../../crates/buzz-conformance/LIMITS.md) is the authoritative statement; headline caveats:
|
||
|
||
- Coverage is **execution coverage** — a code path that never runs during a traced execution is invisible to the gate.
|
||
- It is armed only at the ingest/auth/read accept-reject boundary; DB-layer leaks the projection doesn't read, cross-pod leaks, timing-dependent bugs, pub/sub fan-out, and spec bugs are all out of scope.
|
||
- The read-seam half of the gate is **not yet armed** (pending a design decision on per-row community labeling).
|
||
- Production default is `NoopTracer` — the gate off loses observability only, never correctness.
|
||
|
||
## Documentation debt
|
||
|
||
| Item | Detail |
|
||
|------|--------|
|
||
| **`crates/buzz-cli/README.md` has drifted** | It documents 13 command groups / 60 subcommands and exit codes 0–4; the CLI actually ships 18 groups / 87 subcommands and exit codes 0–5 (adds `emoji`, `notes`, `patches`, `issues`, `pr`, `mem`, `pack`; exit 5 = write conflict). The [CLI reference](cli.md) is verified against `--help` and source. |
|
||
| **`GOVERNANCE.md` is a one-line pointer** | It contains only a link to the Block-wide [organization governance doc](https://github.com/block/.github/blob/main/GOVERNANCE.md) — there is no project-specific governance yet. |
|
||
| **Root doc originals retained during migration** | `ARCHITECTURE.md`, `NOSTR.md`, `TESTING.md`, `RELEASING.md`, and `VISION*.md` were migrated into `docs/` but the originals remain at the repo root with pointer notes. Deletion is a follow-up decision — until then, `docs/` is canonical for migrated content. |
|
||
| **`docs/nips/`, `docs/spec/`, and loose design docs not relocated** | 55 external references (code, tests, migrations, Helm templates) point at their current paths. They are indexed from [`nips.md`](nips.md) and [`design-docs.md`](design-docs.md) in place. |
|
||
|
||
## Vision vs. reality
|
||
|
||
The [`vision/`](../vision/README.md) section describes aspirational direction, not current behavior. Anything described only there should be assumed unimplemented unless this page or the architecture docs say otherwise.
|