prosody 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e796ed66be2610f629c69b181c1cac30155aa0c2196de69fc7a58538816caca
-  data.tar.gz: db008d5d6e205204100eb405ebd01937772a83c1d502cac5a7ef3998bf866099
+  metadata.gz: 052a7e84a72066480eec4ac9ced4e9ab0df381899bda1cd9a643f6e24338863d
+  data.tar.gz: 2f853ea6a2b3e7341513b88256fec70f670c289f58ebc3e5256348816735ee49
 SHA512:
-  metadata.gz: 1b33f8d570c33a9172073f9ab94b8e253d6dd965cec4d06ea0637c030b6013e1c20c95c03a9715abb0de4ab1e68ba292efc3ae85e1e350d5c36d36d29c5c66ee
-  data.tar.gz: 6b8784b0f7dc8fec51a6c4f6b359df0335afb1f77abda27f8210c05a8991f994c17cca29e188a3cf733ee86f3501c24551177416922c32157dc53c081bd9d45d
+  metadata.gz: 5198b84350257b6b0a2b92e1a0a8833fcc4f8ff966b115146096352610a81110323ec78af5b1868f441aface34b6c561063c02303bb1ecb0f35e338c996ce948
+  data.tar.gz: ceebfd36b6ebd53b1462a563b423e168b028fea0fa5d1b3e36d7478bf8ca0a655ac1f8268c8152a0b4d93cb4ca438ef622cd89c7a4ca895e38bc769d529df1e7

data/.cargo/config.toml

@@ -1,2 +1,5 @@
 [env]
 CMAKE_POLICY_VERSION_MINIMUM = { value = "3.5", force = true }
+
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "target-cpu=x86-64-v3"]

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.5.0"
 }

data/AGENTS.md

@@ -0,0 +1,395 @@
+# CLAUDE.md
+
+Development patterns and practices for prosody-rb: Ruby bindings for the
+Prosody Kafka client library. A magnus/rb-sys extension (`ext/prosody`) wraps
+the published `prosody` Rust crate; the Ruby library (`lib/prosody`) carries
+the public API, with RBS signatures in `sig/`. `ARCHITECTURE.md` explains the
+Ruby/Rust bridge in depth — read it before touching the extension.
+
+## Design Principles
+
+These come before everything else. Every change is judged against them.
+
+**Write code that is simple, clear, well-factored, elegant, easy to
+understand, correct, and idiomatic.** A reader should grasp the intent without
+effort. If a change makes the code harder to read, the change is wrong, even
+if it is faster or shorter. If two designs are correct, pick the one that is
+easier to delete.
+
+**Make invalid states unrepresentable in the type system.** When a compiler
+or type checker can prove a contract, no test, comment, or convention has to.
+In Rust, prefer distinct types for distinct concepts, restricted constructors,
+and `enum` sum types over flag fields. In the RBS signatures, give the public
+surface precise types instead of loose ones. If a bug class can be made
+uncompilable, do that instead of writing a runtime check.
+
+**Delete more than you add.** Every change should leave the codebase smaller,
+simpler, or both. If you must add code, look first for duplication you can
+fold, abstractions that no longer pay rent, dead branches, and stale comments.
+The end-state diff should net negative whenever the task allows. Line count is
+not the only axis: plain duplicated arms often read better than generic
+machinery.
+
+**Identify, document, and enforce invariants.** For every load-bearing piece
+of state: name the invariant, write it down near the type or function that
+owns it, enforce it in the type system if you can, otherwise assert it at the
+boundary, and cover it with a test. If you cannot name the invariant, you do
+not yet understand the code well enough to change it.
+
+**Leave the codebase better than you found it.** Drive-by simplifications are
+encouraged when they are scoped to the area you are already touching. Do not
+sprawl — but do not walk past obvious cleanup either.
+
+## Definition of Done
+
+No change is complete until every line below holds. These are acts, not
+aspirations — perform each one; do not merely agree with it:
+
+1. `cargo clippy --manifest-path ext/prosody/Cargo.toml` and the same with
+   `--tests` — zero warnings. `cargo doc` — zero warnings. `make format-check`
+   passes (rustfmt, taplo, standardrb).
+2. `bundle exec rake rbs` and `bundle exec rake steep` — zero errors. They
+   validate the signatures and type-check the library, the typed examples,
+   and the negative fixtures.
+3. `make test 2>&1 | tee /tmp/rspec-output.txt` — re-running slow suites is
+   expensive; grep the file, not the pipe.
+4. Every new or converted test was proved falsifiable once: inject the
+   failure, watch it go red, revert.
+5. Every deleted test names its surviving stronger test in the commit message.
+6. Everything the change replaces is gone — code, tests, signatures, doc
+   vocabulary (see Redesign hygiene). "The new thing works" is half done.
+7. Every claim written this session — doc cross-reference, "covered by" note,
+   exemplar path — was verified to resolve, not recalled from memory.
+8. The diff is net-negative, or each addition is individually justified.
+
+## Development Setup
+
+Start required services with:
+
+```bash
+docker-compose up -d
+```
+
+Services:
+
+- Kafka: localhost:9094
+- Cassandra: localhost:9042
+
+Common commands (`make help` lists them):
+
+```bash
+make compile-dev   # Compile the Rust extension (development mode)
+make compile       # Compile the Rust extension (release mode)
+make test          # Run the RSpec suite (needs Kafka and Cassandra)
+make test-tracing  # Run the tracing suite against a local OTel collector
+make format        # Format Rust, TOML, and Ruby code
+make format-check  # Check formatting without modifying files
+```
+
+`rake` runs the full default gate: `compile spec standard rbs steep`.
+Recompile with `make compile-dev` after any Rust change, or the specs run
+against stale native code.
+
+## Critical Rules
+
+**Error Handling (Rust):**
+
+- Never use `expect`, `unwrap`, `panic`, or `ok()` - forbidden by lints
+- Propagate errors with `?` unless explicitly authorized to swallow
+- Use `thiserror` for structured errors; box only when Clippy warns
+
+**Memory (Rust):**
+
+- **Never leak memory.** `std::mem::forget`, `Box::leak`, and `ManuallyDrop`
+  without an explicit reclamation path are forbidden. If a test must simulate
+  "Drop never ran", seed the underlying state directly; forgetting is never
+  the shortcut.
+- **No unbounded keyed RAM.** Any in-memory structure keyed by message key or
+  collection must have a fixed capacity bound. Every in-memory map names its
+  removal path; self-draining maps are fine, but the drain is still named.
+
+**Allocation and layout (tiger style — https://tigerstyle.dev/):**
+
+- No hot-path allocation that is not upfront and bounded. A steady-state path
+  (per message, per timer fire, per handler call) must not allocate a buffer
+  whose size is discovered at runtime and grown as needed.
+- Pick the buffer by what is known about the size: compile-time constant →
+  stack array; runtime-varying but almost always small → `SmallVec` sized to
+  the common case; genuinely unbounded → `Vec::with_capacity` sized once.
+- `with_capacity` excuses the sizing, never the allocation. A per-call heap
+  allocation on a steady-state path is the defect itself.
+- Never add a gratuitous allocation to satisfy the borrow checker. Reach for
+  a function item, an index, or a borrow before a scratch `Vec`.
+- No amortized resize buffers on the hot path. If a reusable scratch buffer
+  is unavoidable, allocate it once at construction with a fixed bound.
+- **Lay data out for the access pattern.** A hot path that scans one or two
+  fields across many entries must find those fields contiguously. Reach the
+  full record only for the entry the scan selects. An array of `Option<Arc<T>>`
+  turns a two-word decision into one heap dereference per entry, and thrashes
+  the CPU cache. Memory bandwidth is the bottleneck today, so the scan decides
+  the layout, not the record. Don't thrash the cache. False sharing counts:
+  keep atomics that different threads write off one line.
+- Simplicity is not sacrificed for this. When zero-alloc and simple genuinely
+  conflict, keep it simple and leave a comment naming the allocation.
+
+**Code Quality:**
+
+- Lint, doc, type, and format gates live in Definition of Done — zero
+  warnings tolerated.
+- Never suppress warnings with `#[allow(...)]` without permission. All clippy
+  and rustc warnings are fixed properly, not suppressed.
+- Never introduce `dyn` without permission — prefer generics and associated
+  types. The type-erased surface this binding consumes already lives in the
+  published `prosody` crate.
+
+**Ruby/Rust boundary:**
+
+- Rust cannot call Ruby methods from Rust-created threads. Only Ruby-created
+  threads run Ruby code safely. `ARCHITECTURE.md` documents the bridge that
+  upholds this; never bypass it.
+- Release the GVL for blocking work in the extension so other Ruby threads
+  can run.
+
+**JSON codec:**
+
+- This binding never defines its own payload codec. Payload encoding and
+  decoding belong to the `prosody` crate's codec; the binding passes payload
+  bytes through it.
+- `serde_json`, `simd_json`, and the `json!` macro are banned in Rust
+  production code here for payload handling. Tests may use `serde_json::Value`
+  as a concrete payload type.
+
+**Redesign hygiene:**
+
+When a design is replaced, remove *all* of it in the same change —
+half-deleted designs are where bloat and bug re-introduction live:
+
+- Sweep the old design's vocabulary from every doc comment, signature, and
+  example. A stale doc can instruct a reader to re-introduce a fixed bug.
+- Code whose only caller is its own test is dead — delete both together.
+- Struct fields threaded through configs but only read at construction are
+  residue from a superseded design — remove them end-to-end.
+- Do not build surface ahead of a caller: delete zero-caller paths, or make
+  them owner-confirmed, tested features.
+
+**Debugging Discipline:**
+
+- Never claim "found the issue" without rigorous proof
+- Evidence first (logs, tests, reproducible behavior) → hypothesis → test → verify
+
+**Documentation:**
+
+- **All written text for this project must conform to ASD-STE100 (Simplified
+  Technical English). No written text is exempt.** This rule applies to
+  documentation, comments, READMEs, plans, issues, reviews, chat responses,
+  commit messages, PR text, and user-facing text. Apply these primary STE rules:
+  - Use the active voice. Write instructions in the imperative.
+  - Write short sentences. Use 20 words or fewer for instructions. Use 25
+    words or fewer for descriptions.
+  - Write one instruction per sentence. Keep one topic per paragraph. Use a
+    maximum of six sentences in each paragraph.
+  - Use a word with only one meaning. Use the same word for the same thing.
+  - Use simple verb tenses. Do not use an "-ing" form as a verb when a simple
+    tense is correct.
+  - Do not use a noun cluster of more than three nouns.
+  - Use approved technical names and technical verbs consistently.
+- Write doc comments for a reader unfamiliar with the codebase. Lead with
+  what the thing is, how to use it, and what guarantee it gives — not the
+  internal mechanism.
+- Short declarative sentences, one idea each. At most one parenthetical aside
+  per comment, never nested.
+- Never argue with an imagined reviewer. State what the code does and the
+  invariant it upholds. Mention a rejected alternative only when a maintainer
+  would plausibly reintroduce it, as its own plain sentence.
+- No invented compound jargon. Spell the idea out in ordinary words;
+  established terms keep their standard form.
+- State an invariant at the type or function that owns it, once. Reference
+  the owning type elsewhere instead of restating.
+- Be concise. Bad or needless docs hurt readability — prefer fewer, sharper
+  words.
+- Never cite a plan's or spec's section number, phase number, or ordinal in
+  durable docs — code comments, CLAUDE.md, PR and commit text. Name the
+  concept instead.
+- Avoid vague metaphor filler in prose, comments, and commit/PR text ("north
+  star", "surface area", "lean into", "double-click", "first-class citizen").
+  Say the concrete thing instead.
+
+**Style:**
+
+- Prefer `use` statements over fully qualified prefixes
+- Methods without `self` should be functions (except `new` and similar)
+- Ask before large structural changes
+- Default to `pub(crate)`/`pub(super)` in Rust; make something `pub` only as
+  a deliberate API decision.
+- Keep trait constraints as local as possible: put a constraint on the
+  function that needs it, not the struct.
+- When a proposed simplification is examined and rejected, record the ruling
+  in one sentence at the site so the next pass does not re-litigate it.
+- Ruby code follows standardrb; the formatter is the arbiter.
+
+**Git:**
+
+- Never add self-attribution to branch names, commits, PR titles, PR
+  descriptions, or code comments.
+- Use conventional commits for commit titles and PR titles (e.g., `fix:`,
+  `feat:`, `docs:`, `refactor:`).
+- PR titles and descriptions are written for a reader who is not intimately
+  familiar with the project. Lead with what changed and why.
+- Never hard-wrap paragraphs in GitHub PR descriptions, PR comments, or issue
+  text. Each prose paragraph is one single line; blank lines separate
+  paragraphs.
+- PR descriptions never include a test plan or a list of verification steps.
+- Do not reference internal phase numbers, task IDs, or spec sections in
+  commits or code comments.
+- Never run `git reset` or `git checkout` that would destroy uncommitted or
+  committed changes without explicit human permission. Prefer `git stash`, an
+  explicit commit, or `git restore --staged <path>`.
+- Use `gh` for GitHub operations (PRs, issues, API).
+
+## Error Classification
+
+Distinguish permanent from transient errors for retry logic:
+
+```rust
+#[derive(Debug, Clone, Copy)]
+pub enum ErrorType {
+    Permanent,  // Business logic - don't retry
+    Transient,  // Network/timeout - retry with backoff
+}
+```
+
+A permanent error discards the in-flight message. An error the caller's code
+causes (bad input, wrong argument shape) classifies as transient unless the
+caller explicitly declares it permanent — a transient error retries and stays
+visible, so no message is silently lost.
+
+## Concurrency Invariants (inherited from prosody)
+
+- **One handler per key, system-wide.** The framework guarantees at most one
+  message or timer handler for a given key executes anywhere in the cluster
+  at any moment. Never design for concurrent writers on the same key — that
+  scenario cannot occur.
+- **At most one partition owner.** Kafka partition assignment guarantees one
+  consumer group member owns each partition at a time.
+- These invariants are why distributed locks and optimistic concurrency are
+  never needed for per-key state. The framework provides the exclusivity;
+  binding code and examples can assume it.
+
+## Code Organization
+
+**Maximum file size: 500 lines.** A file that exceeds it is subdivided into
+modules. Split along a seam the code already has, and give each module a doc
+comment naming what it owns. Re-export from the parent so the split is
+invisible to callers. A split that only balances line counts is worse than
+the long file; find the real seam.
+
+**Prefer one-word module names** (`bridge`, `client`, `handler`,
+`scheduler`). A two-word name usually means the module owns more than one
+concern, or the name restates its parent's path. A compound name is right
+only when the compound is the domain term.
+
+**Order within Rust files (topological by dependencies):**
+Constants → Statics → Types → Implementations → Functions → Errors (bottom)
+
+## Types, Signatures, and Examples
+
+- `sig/` — public RBS signatures; `sig-private/` — internal signatures.
+  Every API change updates the signatures in the same commit.
+- `lib/prosody/native_stubs.rb` — documented Ruby stubs for the classes and
+  methods the Rust extension implements. Editors and documentation tools read
+  them; the runtime does not (the native extension provides the real
+  definitions), and Steep ignores the file. When the extension's public
+  surface changes, update the matching stub and its YARD doc in the same
+  commit.
+- Steep targets (`Steepfile`): `lib` checks the implementation;
+  `consumer_types` (`typecheck/`) verifies a payload type flows through the
+  public API; `typed_examples` checks every runnable example;
+  `negative_types` (`typecheck_negative/`) holds deliberately-invalid calls
+  with committed expectations — the gate fails if an expected diagnostic
+  disappears.
+- `examples/*.rb` each carry a sibling `.rbs` signature and are type-checked
+  by the `typed_examples` target.
+- Run `bundle exec rake rbs` to validate signatures and
+  `bundle exec rake steep` to type-check.
+
+## Testing
+
+Test suites live in `spec/` (RSpec). Integration specs need the Docker
+Compose services. Run with `make test`; write output to a file:
+
+```bash
+make test 2>&1 | tee /tmp/rspec-output.txt
+grep -i fail /tmp/rspec-output.txt
+```
+
+**Test principles:**
+
+- Drive tests by invariants, not by paths. Name the invariant (round-trip,
+  parity, idempotence) and prefer few broad tests over many narrow example
+  tests. Use realistic inputs, not happy-path toys.
+- A test must be able to fail. When you write or convert a test, prove it can
+  go red once: inject the failure, watch it fail, revert.
+- Never delete a test without naming, in the commit, the surviving test that
+  covers the same invariant at least as strongly.
+- Never use `sleep` except for backpressure simulation. Wait on events,
+  channels, or notifications with a deadline — the deadline is a hang-guard,
+  never the assertion.
+- Root-cause every intermittent failure. A passing re-run proves nothing.
+  Extract the reproducer and land it as a deterministic regression test.
+- In Rust tests, use `assert` or a `Result` with `?` — never
+  `expect`/`unwrap`, never swallow errors.
+
+## Common Patterns (Rust)
+
+- Use `parking_lot` over `std::sync`
+- For concurrent hash sets/maps, use `scc` (`scc::HashSet` / `scc::HashMap`),
+  never a `Mutex<HashSet>` / `Mutex<HashMap>`; pair it with
+  `ahash::RandomState`. In async code prefer its async interface.
+- Use `tokio::sync` primitives (`Notify`, channels, `select!`) for async
+- Independent I/O runs concurrently, never serially. Drive N independent
+  reads through a bounded `buffered(N)` (order-preserving) or
+  `buffer_unordered(N)` (unordered). Reserve serial `await` for genuinely
+  dependent reads, where each result determines the next.
+- Drive futures over non-tokio primitives through the cooperative budget:
+  wrap each per-item future with `tokio::task::coop::cooperative` inside the
+  producing closure, so a drain of ready items cannot starve the worker.
+- Mark builders with `#[must_use]`
+- Use `LazyLock` for expensive static initialization
+
+## Tracing / OpenTelemetry
+
+- Instrument with `#[instrument]`, never a hand-built `info_span!` +
+  `.instrument(...)`. Use `skip_all` plus explicit `fields`, and `err` to
+  record failures on the span.
+- Span level is audience: spans the user's own code causes export at info;
+  framework-internal spans use `level = "debug"`.
+- Record unsigned integers as `i64` — the OTel layer stringifies
+  `u64`/`usize`. Record attribute values with `%` (Display) where the type
+  allows.
+- Import tracing macros from `tracing` directly — never `use tracing::log::…`;
+  no bridge is installed, so events logged through it silently vanish.
+- Never cache a `Span` — cache an `opentelemetry::Context` and recreate spans
+  on read. Cloning a span creates another reference to the same underlying
+  span; finishing one finishes all.
+
+## Workflows
+
+When launching multi-agent workflows:
+
+- Select model and effort per task by complexity — do not let every agent
+  inherit the session model. Never downgrade a stage whose output gates a
+  commit or ship decision.
+- Disable the advisor in every agent prompt.
+- Keep structured-output schemata trivially simple: flat objects with a few
+  short bounded fields; put detail in report files.
+
+## Research
+
+- Automatically use context7 for code generation and library documentation.
+
+## CI planning
+
+- Check Cargo Rail after each CI path or repository layout change.
+- Confirm that README-only changes select documentation jobs only.
+- Confirm that source changes select all required build and test jobs.
+- Add `rail.toml` only when the default rules classify a path incorrectly.

data/ARCHITECTURE.md

@@ -558,7 +558,7 @@ Understanding this architecture helps you write better Prosody applications:
      AuthorizationError       # Permission issues need manual fixing
    ```
 
-3. **Ensure Clean Shutdown**: Always call `unsubscribe` before exiting
+3. **Ensure Clean Shutdown**: Always call `shutdown` before exiting
    ```ruby
    # Set up a shutdown queue
    shutdown = Queue.new
@@ -575,7 +575,7 @@ Understanding this architecture helps you write better Prosody applications:
 
    # Clean shutdown
    puts "Shutting down gracefully..."
-   client.unsubscribe
+   client.shutdown
    ```
 
 4. **Monitor with Traces**: Use OpenTelemetry to understand message processing

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.5.0](https://github.com/prosody-events/prosody-rb/compare/prosody/v0.4.0...prosody/v0.5.0) (2026-08-19)
+
+
+### Features
+
+* add subsystem requests ([#44](https://github.com/prosody-events/prosody-rb/issues/44)) ([672c1de](https://github.com/prosody-events/prosody-rb/commit/672c1de8cbdf883c7cb41e1c82b25851057cf733))
+* add typed excise records and requests ([#45](https://github.com/prosody-events/prosody-rb/issues/45)) ([1581b37](https://github.com/prosody-events/prosody-rb/commit/1581b3768a8ce1ae72677135aabfae04496ce943))
+* expose published keyed state ([#36](https://github.com/prosody-events/prosody-rb/issues/36)) ([bffefa2](https://github.com/prosody-events/prosody-rb/commit/bffefa2908b0d96cc43221babfed1d5ac6554ca2))
+
+
+### Bug Fixes
+
+* **logging:** flush OTel telemetry on exit ([#35](https://github.com/prosody-events/prosody-rb/issues/35)) ([531d22a](https://github.com/prosody-events/prosody-rb/commit/531d22af7b0a8af0e3335b7a706884af6b1e1833))
+* **release:** exclude source-only specs from gem validation ([#33](https://github.com/prosody-events/prosody-rb/issues/33)) ([6d8d745](https://github.com/prosody-events/prosody-rb/commit/6d8d745c0ca9950643566cb11fb21090a6fdb738))
+
 ## [0.4.0](https://github.com/prosody-events/prosody-rb/compare/prosody/v0.3.0...prosody/v0.4.0) (2026-07-21)
 
 

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/CONFIGURATION.md

@@ -0,0 +1,167 @@
+# Configuration
+
+Configure via constructor options or environment variables. Options fall back to environment variables when unset.
+
+The Ruby client reports values it cannot convert to Prosody types. Prosody validates configuration semantics when the client is built.
+
+## Core
+
+| Option / Environment Variable           | Description                                       | Default      |
+|-----------------------------------------|---------------------------------------------------|--------------|
+| `bootstrap_servers` / `PROSODY_BOOTSTRAP_SERVERS` | Kafka servers to connect to             | -            |
+| `group_id` / `PROSODY_GROUP_ID`         | Consumer group name                               | -            |
+| `subscribed_topics` / `PROSODY_SUBSCRIBED_TOPICS` | Topics to read from                     | -            |
+| `allowed_events` / `PROSODY_ALLOWED_EVENTS` | Only process events matching these prefixes   | (all)        |
+| `source_system` / `PROSODY_SOURCE_SYSTEM` | Tag for outgoing messages (prevents reprocessing)| `<group_id>` |
+| `mock` / `PROSODY_MOCK`                 | Use in-memory Kafka for testing                   | false        |
+| `mode` / -                              | Processing mode: `pipeline`, `low_latency`, or `best_effort` | `pipeline` |
+| - / `PROSODY_LOG`                       | Rust log filter, such as `info` or `prosody=debug` | `info` |
+
+## Requests
+
+Requests work with the defaults on one network. Without a network name, peers always use the direct listener address.
+With a network name, peers with the same name use the direct address. Other peers use the advertised connect URI.
+Use a different bind address for each client that shares a host.
+
+| Option / Environment Variable | Description | Default |
+|--------------------------------|-------------|---------|
+| `peer_bind_address` / `PROSODY_PEER_BIND_ADDRESS` | Socket address for the peer gRPC listener | Default network interface address on port 9099 |
+| `peer_advertised_connect` / `PROSODY_PEER_ADVERTISED_CONNECT` | gRPC connect URI that peers on another network use | (none) |
+| `peer_network_name` / `PROSODY_PEER_NETWORK_NAME` | Nonempty network name for direct peer routes | (none) |
+| `peer_cache_capacity` / `PROSODY_PEER_CACHE_CAPACITY` | Maximum channels and peer records in each peer cache | 256 |
+| `peer_registration_ttl` / `PROSODY_PEER_REGISTRATION_TTL` | Directory lease duration; use 5 seconds through 20 years | 30s |
+
+Set `subsystem` to make this client answer requests. Without it, the client consumes messages but does not answer requests.
+
+## Consumer
+
+| Option / Environment Variable           | Description                                          | Default                |
+|-----------------------------------------|------------------------------------------------------|------------------------|
+| `max_concurrency` / `PROSODY_MAX_CONCURRENCY` | Max messages being processed simultaneously     | 32                     |
+| `max_uncommitted` / `PROSODY_MAX_UNCOMMITTED` | Max queued messages before pausing consumption  | 64                     |
+| `timeout` / `PROSODY_TIMEOUT`           | Cancel handler if it runs longer than this           | 80% of stall threshold |
+| `commit_interval` / `PROSODY_COMMIT_INTERVAL` | How often to save progress to Kafka            | 1s                     |
+| `poll_interval` / `PROSODY_POLL_INTERVAL` | How often to fetch new messages from Kafka         | 100ms                  |
+| `shutdown_timeout` / `PROSODY_SHUTDOWN_TIMEOUT` | Shutdown budget; handlers run freely until cancellation fires near the end of the timeout | 30s |
+| `stall_threshold` / `PROSODY_STALL_THRESHOLD` | Report unhealthy if no progress for this long  | 5m                     |
+| `probe_port` / `PROSODY_PROBE_PORT`     | HTTP port for health checks; use `false`, `:disabled`, or the environment value `none` to disable | 8000 |
+| - / `PROSODY_STATISTICS_INTERVAL`       | How often librdkafka reports client statistics; must be between 1ms and 24h | 5s |
+| `failure_topic` / `PROSODY_FAILURE_TOPIC` | Send unprocessable messages here (dead letter queue) | -                     |
+| `idempotence_cache_size` / `PROSODY_IDEMPOTENCE_CACHE_SIZE` | Global shared cache capacity across all partitions for message deduplication. Consumer deduplication is mandatory and cannot be disabled, so this must be at least 1; setting it to 0 in the client configuration is rejected | 8192 |
+| `idempotence_version` / `PROSODY_IDEMPOTENCE_VERSION` | Version string for cache-busting dedup hashes | 1              |
+| `idempotence_ttl` / `PROSODY_IDEMPOTENCE_TTL`         | TTL for dedup records in Cassandra            | 7d (604800 seconds) |
+| `slab_size` / `PROSODY_SLAB_SIZE`       | Timer storage granularity (rarely needs changing)    | 1h                     |
+| `message_spans` / `PROSODY_MESSAGE_SPANS` | Span linking for message execution: `child` (child-of) or `follows_from` | `child` |
+| `timer_spans` / `PROSODY_TIMER_SPANS`   | Span linking for timer execution: `child` (child-of) or `follows_from`   | `follows_from` |
+
+## Producer
+
+| Option / Environment Variable           | Description                     | Default |
+|-----------------------------------------|---------------------------------|---------|
+| `send_timeout` / `PROSODY_SEND_TIMEOUT` | Give up sending after this long | 1s      |
+
+## Retry
+
+Retry backoff applies in pipeline and low-latency modes. `max_retries` controls how many retries low-latency mode performs before routing the failure to `failure_topic`. Pipeline mode uses deferral and does not use this limit.
+
+| Option / Environment Variable           | Description                       | Default |
+|-----------------------------------------|-----------------------------------|---------|
+| `max_retries` / `PROSODY_MAX_RETRIES`   | Low-latency retries before routing to the failure topic | 3       |
+| `retry_base` / `PROSODY_RETRY_BASE`     | Wait this long before first retry | 20ms    |
+| `max_retry_delay` / `PROSODY_RETRY_MAX_DELAY` | Never wait longer than this  | 5m      |
+
+## Deferral (Pipeline Mode)
+
+| Option / Environment Variable           | Description                                       | Default |
+|-----------------------------------------|---------------------------------------------------|---------|
+| `defer_enabled` / `PROSODY_DEFER_ENABLED` | Enable deferral for new messages                | true    |
+| `defer_base` / `PROSODY_DEFER_BASE`     | Wait this long before first deferred retry        | 1s      |
+| `defer_max_delay` / `PROSODY_DEFER_MAX_DELAY` | Never wait longer than this                 | 24h     |
+| `defer_failure_threshold` / `PROSODY_DEFER_FAILURE_THRESHOLD` | Disable deferral when failure rate exceeds this | 0.9 |
+| `defer_failure_window` / `PROSODY_DEFER_FAILURE_WINDOW` | Measure failure rate over this time window | 5m     |
+| `defer_store_cache_size` / `PROSODY_DEFER_STORE_CACHE_SIZE` | Maximum deferred store cache entries per Cassandra defer store | 8192 |
+
+## Kafka Message Loader (All Modes)
+
+The shared loader resolves Kafka messages for deferral and keyed state:
+
+| Option / Environment Variable | Description | Default |
+|--------------------------------|-------------|---------|
+| `loader_cache_size` / `PROSODY_LOADER_CACHE_SIZE` | Maximum messages retained by the shared Kafka loader | 1024 |
+| `loader_seek_timeout` / `PROSODY_LOADER_SEEK_TIMEOUT` | Timeout for Kafka loader seek operations | 30s |
+| `loader_discard_threshold` / `PROSODY_LOADER_DISCARD_THRESHOLD` | Sequential-read distance before the loader seeks | 100 |
+
+## Monopolization Detection (Pipeline Mode)
+
+| Option / Environment Variable           | Description                             | Default |
+|-----------------------------------------|-----------------------------------------|---------|
+| `monopolization_enabled` / `PROSODY_MONOPOLIZATION_ENABLED` | Enable hot key protection   | true    |
+| `monopolization_threshold` / `PROSODY_MONOPOLIZATION_THRESHOLD` | Max handler time as fraction of window | 0.9 |
+| `monopolization_window` / `PROSODY_MONOPOLIZATION_WINDOW` | Measurement window            | 5m      |
+| `monopolization_cache_size` / `PROSODY_MONOPOLIZATION_CACHE_SIZE` | Max distinct keys to track  | 8192    |
+
+## Fair Scheduling (All Modes)
+
+| Option / Environment Variable           | Description                                                      | Default |
+|-----------------------------------------|------------------------------------------------------------------|---------|
+| `scheduler_failure_weight` / `PROSODY_SCHEDULER_FAILURE_WEIGHT` | Fraction of processing time reserved for retries | 0.3    |
+| `scheduler_max_wait` / `PROSODY_SCHEDULER_MAX_WAIT` | Messages waiting this long get maximum priority          | 2m      |
+| `scheduler_wait_weight` / `PROSODY_SCHEDULER_WAIT_WEIGHT` | Priority boost for waiting messages (higher = more aggressive) | 200.0 |
+| `scheduler_cache_size` / `PROSODY_SCHEDULER_CACHE_SIZE` | Max distinct keys to track                             | 8192    |
+
+## Telemetry
+
+Prosody emits message, timer, and producer lifecycle events to a Kafka topic for observability:
+
+| Option / Environment Variable           | Description                                    | Default                    |
+|-----------------------------------------|------------------------------------------------|----------------------------|
+| `telemetry_topic` / `PROSODY_TELEMETRY_TOPIC` | Kafka topic to produce telemetry events to | `prosody.telemetry-events` |
+| `telemetry_enabled` / `PROSODY_TELEMETRY_ENABLED` | Enable or disable the telemetry emitter  | true                       |
+
+Mock mode disables telemetry automatically, regardless of `telemetry_enabled`.
+
+## Cassandra
+
+Persistent storage for timers, deferral, deduplication, and keyed state. It is not needed when `mock: true`.
+
+| Option / Environment Variable           | Description                        | Default |
+|-----------------------------------------|------------------------------------|---------|
+| `cassandra_nodes` / `PROSODY_CASSANDRA_NODES` | Servers to connect to (host:port) | -      |
+| `cassandra_keyspace` / `PROSODY_CASSANDRA_KEYSPACE` | Keyspace name              | prosody |
+| `cassandra_user` / `PROSODY_CASSANDRA_USER` | Username                          | -       |
+| `cassandra_password` / `PROSODY_CASSANDRA_PASSWORD` | Password                   | -       |
+| `cassandra_datacenter` / `PROSODY_CASSANDRA_DATACENTER` | Prefer this datacenter for queries | - |
+| `cassandra_rack` / `PROSODY_CASSANDRA_RACK` | Prefer this rack for queries      | -       |
+| `cassandra_retention` / `PROSODY_CASSANDRA_RETENTION` | Delete data older than this | 1y     |
+
+## Keyed State
+
+Register keyed-state collections before you subscribe. Persistence is backed by Cassandra and is not needed when `mock: true`. See [Keyed State](README.md#keyed-state) for handler usage. Where an option and an environment variable are paired, an explicitly set option wins. Otherwise, the environment variable applies, then the default.
+
+| Option / Environment Variable | Description | Default |
+|-------------------------------|-------------|---------|
+| `state_collections` / - | Keyed-state collections to register before subscribe (array of definitions or config hashes; duplicate names rejected) | (none) |
+| `subsystem` / `PROSODY_SUBSYSTEM` | Subsystem name used to advertise JSON collections whose definitions set `published: true` | (none) |
+| `state_cache_dir` / `PROSODY_STATE_CACHE_DIR` | Disk workspace for the local keyed-state cache; each live client needs its own directory. Set a mounted path in production | per-client temp dir |
+| `state_owned_cache_size` / `PROSODY_STATE_OWNED_CACHE_SIZE` | Capacity of the owning keyed-state cache; accepts sizes such as `64 MiB` or `500 MB` | storage-engine default |
+| `state_read_cache_size` / `PROSODY_STATE_READ_CACHE_SIZE` | Capacity of the published-state read cache; accepts sizes such as `1 MiB` | `state_owned_cache_size` or `PROSODY_STATE_OWNED_CACHE_SIZE` when set; otherwise 1 MiB |
+| `state_read_cache` / `PROSODY_STATE_READ_CACHE_TTL` | Default published-read cache TTL. Use `false` or the environment value `none` to bypass the cache | 5s |
+| `state_recovery_delay` / `PROSODY_STATE_RECOVERY_DELAY` | Whole-second delay between staging a provisional cell and the recovery sweep; every collection TTL must strictly exceed it | 30s |
+
+Prefer the definition constructors from the [API reference](README.md#api-reference). They serialize into `state_collections`, so you can reuse the same object with `context.state`. Each entry has these fields:
+
+Published collections require `subsystem`. Keep it configured for one deployment after removing `published: true` so readers can observe the collection's retirement.
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `name` | Collection name; non-empty and unique within the client | (required) |
+| `kind` | `"value"`, `"map"`, or `"deque"` | (required) |
+| `payload` | `"json"` (JSON values) or `"message"` (the full Kafka message the handler received) | (required) |
+| `ttl_seconds` | Per-write TTL in whole seconds (at least 1; must exceed the recovery delay) | (none) |
+| `read_uncommitted` | Opt out of transactional staging | false |
+| `published` | Allow read-only access from other consumer groups; JSON collections only | false |
+| `read_cache` | Published-read cache override: a positive duration, `false`, or inherit when omitted | inherit |
+| `keyset_limit` | Map-only; ordered-scan bound in `0..=4096` (`0` disables ordered-scan tracking) | 128 |
+| `capacity` | Deque-only window bound (at least 1); keeps at most N slots, enforced lazily on push. Runtime-only and mutable across deploys — not persisted | unbounded |
+
+Constructors set these via keyword arguments (`ttl:`, `keyset_limit:`, `capacity:`, `read_uncommitted:`, `published:`, `read_cache:`). `read_cache` is a positive duration in seconds, `false` to bypass the cache, or `nil` to inherit the client default.