jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-11-02 23:41:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
23f75dac90f60d32507989d36b86f022bfc18b94
buzz/docs/reference/known-limitations.md
npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl 23f75dac90 docs: write full documentation content (Phase 2) 
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>
2026-07-07 12:14:33 -07:00

4.3 KiB
Raw Blame History

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, 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).

Conformance gate

The runtime conformance harness (crates/buzz-conformance) is observation, not proof. Its own 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 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 — 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 and design-docs.md in place.

Vision vs. reality

The vision/ section describes aspirational direction, not current behavior. Anything described only there should be assumed unimplemented unless this page or the architecture docs say otherwise.