feat: broker core with single-threaded scheduler loop

[vieiralucas]

Summary

• Implement Redis-inspired single-threaded scheduler architecture with a dedicated std::thread running a tight event loop
• Add SchedulerCommand enum with Enqueue, Ack, Nack, RegisterConsumer, UnregisterConsumer, Shutdown variants using tokio::sync::oneshot for request-response
• Add Broker struct that manages the scheduler thread lifecycle with graceful shutdown and Drop safety
• Add BrokerConfig with TOML deserialization and sensible defaults (server + scheduler sections)
• Add tracing subscriber setup with JSON/pretty-print mode selection
• Command handlers are stubs to be filled in by subsequent stories (1.5-1.8)

Test plan

• 5 scheduler tests (shutdown, FIFO ordering, enqueue/ack reply, channel disconnect)
• 3 broker tests (start/shutdown, enqueue command processing, Drop cleanup)
• 4 config tests (defaults, full TOML override, empty TOML defaults, partial config)
• All 28 tests pass via cargo nextest run
• cargo clippy -- -D warnings passes
• cargo fmt --check passes

---

Summary by cubic

Implements a single-threaded scheduler core with a Broker, structured logging, and graceful shutdown, plus a RocksDB-backed storage layer with ordered keys and atomic batches. Satisfies Story 1.4 (Broker Core & Scheduler Loop) and completes Story 1.3 (Core Domain Types & Storage), laying groundwork for enqueue/ack/nack in later stories.

• New Features

  • Broker spawns the "fila-scheduler" thread with bounded crossbeam commands and clean shutdown.
  • SchedulerCommand enum with oneshot replies where needed; ReadyMessage for consumer delivery.
  • BrokerConfig parses from TOML with defaults; telemetry::init_tracing uses EnvFilter (pretty in debug, JSON in release).

• Bug Fixes and Refactors

  • Broker::send_command uses try_send to avoid blocking; returns ChannelFull/ChannelDisconnected.
  • Explicit, per-command error types and StorageError::ColumnFamilyNotFound; RocksDbStorage uses a cf() helper for safe CF access; documented explicit error mapping in CLAUDE.md.

^{Written for commit acc9695. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 11 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="crates/fila-core/src/broker/mod.rs">

<violation number="1" location="crates/fila-core/src/broker/mod.rs:58">
P2: send_command blocks when the channel is full despite the method contract saying it returns an error on full. Use try_send and map Full vs Disconnected to avoid hanging callers.</violation>
</file>

<file name="_bmad-output/implementation-artifacts/1-4-broker-core-scheduler-loop.md">

<violation number="1" location="_bmad-output/implementation-artifacts/1-4-broker-core-scheduler-loop.md:15">
P3: Acceptance Criteria lists `Admin`, but the rest of the story uses `Shutdown`. This inconsistency makes the required command set unclear. Align AC #3 with the `Shutdown` variant used elsewhere.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[vieiralucas]

Using a StorageError here feels like using it as a fallback for any kind of error. I’d like us to be very diligent about defining and using meaningful, specific errors.

[vieiralucas]

Using a StorageError here feels like using it as a fallback for any kind of error. I’d like us to be very diligent about defining and using meaningful, specific errors.

[vieiralucas]

Using a StorageError here feels like using it as a fallback for any kind of error. I’d like us to be very diligent about defining and using meaningful, specific errors.