prosody 0.5.1-x86_64-linux → 0.6.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d88c342cd11f4b6b63529a4b49b6522f03812456155292011833fa09cedeafa0
-  data.tar.gz: 7333aff88c4eb772ed2f34cd9b36e899820a9bea93a550e9fe46d12fbb8d6f13
+  metadata.gz: 270bd58a5f0184bfe26ef85b0a12442f58bc95c036d09f0b2caa5e117dc06c9c
+  data.tar.gz: ec405fbe428a3c282fbbb619643cf477a15f7b095c516253495d1c896d7ca653
 SHA512:
-  metadata.gz: 515b9738def539f1bcb5b66432803c44bee221efcb335c50231b2463d5e4b53e75c62f6dd97484eea61e5244ae2b4dab4a8a3e981e79af35cfd0d8f3d923d564
-  data.tar.gz: e00cf39f69788d4941ced48939e53edb3cc7e5ff601bd88094b659d817e3b1b979f487685271d26f07577c76ad3b6cab3a5d9c837794eb9d9f241ac899309046
+  metadata.gz: 70fc1084d9eaf1edeb3c202c8d973a3a1da426453a290047317b14751852cb7eacbaa6125ff831c260b6dc28d527eb4454c96166227692b537c32838cf7cf2de
+  data.tar.gz: a504e6950613bd803b71882c363311844f49d616f8cb6d8a188dd37eaf6d6d1f25699d10dc12870901f20274f82e9172acef61b4931d83e263d2bab4bf801306

data/.cargo/config.toml

@@ -6,9 +6,9 @@ rustflags = ["-C", "target-cpu=x86-64-v3"]
 [source.crates-io]
 replace-with = "vendored-sources"
 
-[source."git+https://github.com/xonatius/mimalloc_rust.git?rev=6d4c41bb10c6d9da1d1b6f07b38c4cc051667f11"]
-git = "https://github.com/xonatius/mimalloc_rust.git"
-rev = "6d4c41bb10c6d9da1d1b6f07b38c4cc051667f11"
+[source."git+https://github.com/hadronzoo/serde-magnus?rev=27aee737829a6bca399289b6e64ce4bcc08bfd94"]
+git = "https://github.com/hadronzoo/serde-magnus"
+rev = "27aee737829a6bca399289b6e64ce4bcc08bfd94"
 replace-with = "vendored-sources"
 
 [source.vendored-sources]

data/.config/rail.toml

@@ -0,0 +1,26 @@
+[plan.work.ci]
+paths = [".config/rail.toml", ".github/**", ".taplo.toml", "Makefile"]
+scope = "repository"
+
+[plan.work.ruby]
+paths = [
+    ".rspec",
+    ".ruby-version",
+    ".standard.yml",
+    "Gemfile",
+    "Gemfile.lock",
+    "Rakefile",
+    "Steepfile",
+    "bin/**",
+    "examples/**",
+    "ext/prosody/extconf.rb",
+    "lib/**",
+    "prosody.gemspec",
+    "sig-private/**",
+    "sig/**",
+    "spec/**",
+    "steep_expectations.yml",
+    "typecheck/**",
+    "typecheck_negative/**",
+]
+scope = "repository"

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.1"
+  ".": "0.6.0"
 }

data/.ruby-version

@@ -1 +1 @@
-3.3.7
+3.3.12

data/.taplo.toml

@@ -1,4 +1,4 @@
-include = ["*.toml", ".cargo/*.toml", "ext/**/*.toml"]
+include = ["*.toml", ".cargo/*.toml", ".config/*.toml", "ext/**/*.toml"]
 
 [formatting]
 indent_string = "    "

data/AGENTS.md

@@ -10,11 +10,11 @@ Ruby/Rust bridge in depth — read it before touching the extension.
 
 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.
+**Write code that is simple, clear, well-factored, DRY, performant, 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.
@@ -26,9 +26,10 @@ 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.
+The end-state diff should net negative whenever the task allows. Each added
+line must be inherent to the problem, not incidental to the solution. 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
@@ -40,6 +41,15 @@ not yet understand the code well enough to change it.
 encouraged when they are scoped to the area you are already touching. Do not
 sprawl — but do not walk past obvious cleanup either.
 
+**Do not break users without a reason.** The published package has real
+users. A release can break them only for a clear improvement that the
+owner decided on: a fixed defect, an invalid state that the types now
+prevent, or a need of a new feature. "Nothing in this repo calls it" is
+not a reason to remove, rename, or narrow a public member, an error
+class, a log text, or a dependency floor. When you are not sure, keep
+the old shape. List each break under `## Breaking changes` in the PR
+body.
+
 ## Definition of Done
 
 No change is complete until every line below holds. These are acts, not
@@ -60,7 +70,8 @@ aspirations — perform each one; do not merely agree with it:
    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.
+8. The diff is net-negative, or each addition is individually justified as
+   inherent to the problem.
 
 ## Development Setup
 
@@ -216,6 +227,8 @@ half-deleted designs are where bloat and bug re-introduction live:
 
 **Style:**
 
+- Structure function bodies as logical paragraphs. Keep statements for one
+  operation together. Add a blank line before a new concept or operation.
 - Prefer `use` statements over fully qualified prefixes
 - Methods without `self` should be functions (except `new` and similar)
 - Ask before large structural changes
@@ -295,12 +308,13 @@ Constants → Statics → Types → Implementations → Functions → Errors (bo
 
 - `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.
+- Public API docs are YARD comments on the public Ruby classes. A public
+  class that the Rust extension implements (`Client`, `Context`, `Message`,
+  `Timer`) keeps a documented stub in `lib/prosody/native_stubs/`. Do not
+  write stubs for internal native classes or private methods; `sig/` and
+  `sig-private/` type them. The runtime does not load the stubs, and Steep
+  ignores them. When a public native method changes, update its stub 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;

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.6.0](https://github.com/prosody-events/prosody-rb/compare/prosody/v0.5.1...prosody/v0.6.0) (2026-10-02)
+
+
+### Features
+
+* **deps:** upgrade prosody to 0.7.0 ([#51](https://github.com/prosody-events/prosody-rb/issues/51)) ([c9f265c](https://github.com/prosody-events/prosody-rb/commit/c9f265c7c5353c989886d2333afca2142e06763c))
+
 ## [0.5.1](https://github.com/prosody-events/prosody-rb/compare/prosody/v0.5.0...prosody/v0.5.1) (2026-08-20)
 
 

data/CLAUDE.md

@@ -10,11 +10,11 @@ Ruby/Rust bridge in depth — read it before touching the extension.
 
 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.
+**Write code that is simple, clear, well-factored, DRY, performant, 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.
@@ -26,9 +26,10 @@ 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.
+The end-state diff should net negative whenever the task allows. Each added
+line must be inherent to the problem, not incidental to the solution. 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
@@ -40,6 +41,15 @@ not yet understand the code well enough to change it.
 encouraged when they are scoped to the area you are already touching. Do not
 sprawl — but do not walk past obvious cleanup either.
 
+**Do not break users without a reason.** The published package has real
+users. A release can break them only for a clear improvement that the
+owner decided on: a fixed defect, an invalid state that the types now
+prevent, or a need of a new feature. "Nothing in this repo calls it" is
+not a reason to remove, rename, or narrow a public member, an error
+class, a log text, or a dependency floor. When you are not sure, keep
+the old shape. List each break under `## Breaking changes` in the PR
+body.
+
 ## Definition of Done
 
 No change is complete until every line below holds. These are acts, not
@@ -60,7 +70,8 @@ aspirations — perform each one; do not merely agree with it:
    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.
+8. The diff is net-negative, or each addition is individually justified as
+   inherent to the problem.
 
 ## Development Setup
 
@@ -216,6 +227,8 @@ half-deleted designs are where bloat and bug re-introduction live:
 
 **Style:**
 
+- Structure function bodies as logical paragraphs. Keep statements for one
+  operation together. Add a blank line before a new concept or operation.
 - Prefer `use` statements over fully qualified prefixes
 - Methods without `self` should be functions (except `new` and similar)
 - Ask before large structural changes
@@ -295,12 +308,13 @@ Constants → Statics → Types → Implementations → Functions → Errors (bo
 
 - `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.
+- Public API docs are YARD comments on the public Ruby classes. A public
+  class that the Rust extension implements (`Client`, `Context`, `Message`,
+  `Timer`) keeps a documented stub in `lib/prosody/native_stubs/`. Do not
+  write stubs for internal native classes or private methods; `sig/` and
+  `sig-private/` type them. The runtime does not load the stubs, and Steep
+  ignores them. When a public native method changes, update its stub 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;

data/CONFIGURATION.md

@@ -10,12 +10,14 @@ The Ruby client reports values it cannot convert to Prosody types. Prosody valid
 |-----------------------------------------|---------------------------------------------------|--------------|
 | `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                     | -            |
+| `subscribed_topics` / `PROSODY_SUBSCRIBED_TOPICS` | Topics to read from; a client that only reads published state needs none | -            |
 | `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` |
+| - / `PROSODY_LOG`                       | Rust log filter, such as `info` or `prosody=debug` | `info`, with `warn` for `scylla` and `opentelemetry` |
+
+`PROSODY_LOG` directives apply on top of the defaults above. A value that names only targets, such as `prosody=debug`, keeps other targets at `info`. Set `PROSODY_LOG=opentelemetry=info` to restore the OpenTelemetry info events.
 
 ## Requests
 
@@ -45,9 +47,9 @@ Set `subsystem` to make this client answer requests. Without it, the client cons
 | `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 |
+| `statistics_interval` / `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_cache_size` / `PROSODY_IDEMPOTENCE_CACHE_SIZE` | Capacity of the producer idempotence cache and of the consumer deduplication cache. Consumer deduplication cannot be turned off, so the value must be at least 1 | 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                     |
@@ -141,27 +143,28 @@ Register keyed-state collections before you subscribe. Persistence is backed by
 | 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 |
+| `subsystem` / `PROSODY_SUBSYSTEM` | Subsystem name used to advertise JSON and set collections whose definitions set `published: true` | (none) |
+| `state_cache_dir` / `PROSODY_STATE_CACHE_DIR` | Directory for the local keyed-state caches. Each consumer opens its cache in a new subdirectory and removes it when the consumer stops, so clients can share the directory. Set a mounted path in production | `<temp>/prosody/keyed-state` |
 | `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_memtable_size` / `PROSODY_STATE_MEMTABLE_SIZE` | Bytes of in-memory writes the local keyed-state cache holds for each assigned partition before it flushes them to disk; accepts sizes such as `16 MiB`. Memory use scales with the number of assigned partitions | storage-engine default of 64 MiB |
 | `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.
 
+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:
+
 | 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) |
+| `kind` | `"value"`, `"map"`, `"set"`, or `"deque"` | (required) |
+| `payload` | `"json"` (JSON values) or `"message"` (the full Kafka message the handler received). Omit it for a set, which stores membership only | (required for a value, map, or deque) |
+| `ttl_seconds` | Per-write TTL in whole seconds (at least 1) | (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 |
+| `published` | Allow read-only access from other consumer groups; JSON and set collections only | false |
+| `keyset_limit` | Map and set 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.
+Constructors set these via keyword arguments (`ttl:`, `keyset_limit:`, `capacity:`, `read_uncommitted:`, `published:`).
+
+A JSON or set constructor also takes `read_cache:`. It is not a registration field: it applies only to the readers that `client.state` opens with the definition. `read_cache` is a positive duration in seconds, `false` to bypass the cache, or `nil` to inherit the client default.

data/README.md

@@ -277,10 +277,10 @@ You can monitor the stall state programmatically using the client's methods:
 
 ```ruby
 # Get the number of partitions currently assigned to this consumer
-partition_count = client.assigned_partitions
+partition_count = client.assigned_partition_count
 
 # Check if the consumer has stalled partitions
-if client.is_stalled?
+if client.stalled?
   warn 'Consumer has stalled partitions'
 end
 ```
@@ -299,7 +299,7 @@ Send a request from a handler or other application code. The Prosody client does
 
 Do not rely on hash order. The hash contains one entry for each selected subsystem. A missing response becomes a timeout `Failure`; Prosody does not omit the subsystem. The request raises an error for request-level failures, such as invalid input, a Kafka send failure, or shutdown. Do not wait for a request if the current consumer group must process it for the same key. That group cannot process it until the handler returns.
 
-Message and excise handler return values become successful outcomes. Each return value must have a JSON representation.
+Message and excise handler return values become successful outcomes. Each return value must have a JSON representation. A return value without one is a transient handler error, so Prosody retries the message.
 
 Set `subsystem` to `inventory` on the client that subscribes this handler.
 
@@ -626,12 +626,53 @@ State operations look synchronous. They yield the current fiber while Prosody pe
 | Collection | JSON payload | Kafka message | Main operations |
 | --- | --- | --- | --- |
 | Value | `Prosody.value` | `Prosody.message_value` | `get`, `set`, `clear` |
-| Ordered string map | `Prosody.map` | `Prosody.message_map` | `get`, `get_many`, `key?`, `set`, `delete`, `each_pair`, `each_key`, `clear` |
+| Ordered string map | `Prosody.map` | `Prosody.message_map` | `get`, `get_many`, `key?`, `contains_many`, `empty?`, `set`, `delete`, `each_pair`, `each_key`, `clear` |
+| Ordered string set | `Prosody.set` | - | `add` / `<<`, `delete`, `include?`, `contains_many`, `empty?`, `each`, `clear` |
 | Deque | `Prosody.deque` | `Prosody.message_deque` | `push`, `unshift`, `pop`, `shift`, `get`, `length`, `each`, `clear` |
 
-Map and deque scans return enumerators when called without a block. Map keys are strings.
+Map, set, and deque scans return enumerators when called without a block. Map keys and set members are strings. A set stores membership only, so it has no payload type.
 
-`nil` means absence. Do not store this value. Use `clear` or `delete`.
+A value, map, or deque read returns `nil` when no value is present. Do not store `nil` as a value. A `nil` write fails with a `PermanentStateError`. Use `clear` (value, deque) or `delete` (map) to remove a value.
+
+A set handle mirrors Ruby's `Set`:
+
+```ruby
+SEEN_ORDERS = Prosody.set("seen-orders", ttl: 7 * 24 * 60 * 60)
+
+def on_message(context, message)
+  seen = context.state(SEEN_ORDERS)
+  return if seen.include?(message.payload["order_id"])
+
+  seen << message.payload["order_id"]
+  fulfill(message)
+end
+```
+
+### Query keywords
+
+Every traversal method accepts optional query keywords. Prosody applies them in storage, so a query reads only the selected entries. The `each` and `each_*` methods iterate forward. The `reverse_each` and `reverse_each_*` methods iterate backward.
+
+| Keyword | Selects |
+| --- | --- |
+| `from:` / `after:` | Starts at the key or position, or just after it, in iteration order |
+| `to:` / `before:` | Stops at the key or position, or just before it, in iteration order |
+| `range:` | Keeps keys or positions in a Ruby `Range`: `"a".."m"`, `"a"..."m"`, `.."m"`, or `"a"..`. Write the range in ascending order; it applies in both directions. A descending range is empty |
+| `prefix:` | Keeps map keys or set members that start with the string |
+| `limit:` | Stops after this many items; a positive `Integer` |
+
+A reverse traversal starts at the high end. Keywords narrow the selection and never widen it. Pass at most one of `from:` and `after:`, and at most one of `to:` and `before:`. Set traversals select members. Deque positions count from the front and must be non-negative. To read the last N items, use `reverse_each(limit: N)`. Deques have no `prefix:`. A bad keyword raises `ArgumentError` or `TypeError`.
+
+To read a map in pages, pass the last key of the previous page as `after:`:
+
+```ruby
+page = map.each_pair(prefix: "order:", limit: 100).to_a
+until page.empty?
+  page.each { |key, order| archive(key, order) }
+  page = map.each_pair(prefix: "order:", after: page.last.first, limit: 100).to_a
+end
+```
+
+The same pattern works backward with `reverse_each_pair`.
 
 ### When keyed-state changes become visible
 
@@ -643,6 +684,8 @@ This transaction applies only to keyed state. Some workflows need state changes
 - `commit` commits the collection's pending changes before the handler ends. A later handler failure does not remove them.
 - `rollback` discards pending changes since the last `commit`. It cannot undo committed changes.
 
+`commit` and `rollback` return `:applied` when they wrote or discarded pending changes. They return `:no_op` when the collection had no pending changes.
+
 ### Published state
 
 Some callers need only the current value for a key. They can accept a stale value or a race with a concurrent update.
@@ -665,7 +708,7 @@ current_order = context.state(CURRENT_ORDER)
 current_order.set({"sku" => "book"})
 ```
 
-Read published state from a handler or other application code. The Prosody client does not need an active subscription.
+Read published state from a handler or other application code. The Prosody client does not need an active subscription. A client that only reads published state needs no `subscribed_topics`.
 
 Use the subsystem and the same definition to open a reader:
 
@@ -674,9 +717,9 @@ order_reader = client.state("checkout", CURRENT_ORDER)
 current_order = order_reader.get("customer-123")
 ```
 
-The reader cannot see pending changes that exist only in a handler. It cannot change the collection. Each read takes an explicit key because no handler supplies one.
+The reader cannot see pending changes that exist only in a handler. It cannot change the collection. Each read takes an explicit String key because no handler supplies one.
 
-Map and deque readers fetch data in chunks. They do not load the complete collection before iteration starts. Readers return an `Enumerator` without a block.
+Map, set, and deque readers fetch data in chunks. They do not load the complete collection before iteration starts. Readers return an `Enumerator` without a block. Reader traversals accept the same [query keywords](#query-keywords) after the key. A failed read raises `Prosody::TransientStateError` or `Prosody::PermanentStateError`, as an owned handle does, for point reads and traversals alike. A reader that Prosody cannot open, such as one with a zero `read_cache`, raises the same classes.
 
 Use `reverse_each_pair`, `reverse_each_key`, `reverse_each_value`, or `reverse_each` for reverse traversal.
 
@@ -783,9 +826,9 @@ all traces to Ruby.
 To use OpenTelemetry tracing with Prosody, you need to install the following gems:
 
 ```ruby
-gem 'opentelemetry-sdk', '~> 1.10'
-gem 'opentelemetry-api', '~> 1.7'
-gem 'opentelemetry-exporter-otlp', '~> 0.31'
+gem 'opentelemetry-sdk', '~> 1.13'
+gem 'opentelemetry-api', '~> 1.10'
+gem 'opentelemetry-exporter-otlp', '~> 0.36'
 ```
 
 ### Initializing Tracing
@@ -907,6 +950,16 @@ Call `shutdown` when the application terminates. It stops all client services an
 client.shutdown
 ```
 
+To scope a client to a block, use `Prosody::Client.open`. It yields the client and calls `shutdown` when the block exits, also when the block raises. It returns the value of the block.
+
+```ruby
+Prosody::Client.open(bootstrap_servers: "localhost:9092") do |client|
+  client.send_message("my-topic", "key", {"hello" => "world"})
+end
+```
+
+Repeated `shutdown` calls wait for the same operation, so the block can also call `shutdown`.
+
 Handle application shutdown with signal handlers:
 
 ```ruby
@@ -972,6 +1025,18 @@ Best practices:
 - Be cautious with permanent errors as they prevent retries and can result in data loss.
 - Consider system reliability and data consistency when classifying errors.
 
+A handler can tell a retry from a normal delivery through `context.demand`:
+
+```ruby
+def on_message(context, message)
+  demand = context.demand
+  logger.warn("retry #{demand.retries} for #{message.key}") if demand.failure?
+  process(message)
+end
+```
+
+`demand.retries` is the number of retries: 0 for a normal delivery and 1 on the first retry. After Prosody defers an event, the count starts again at 1. The count is an estimate. Keep an exact attempt count in keyed state if you need one.
+
 ### Handling Task Cancellation
 
 Prosody cancels tasks during partition rebalancing, timeout, or shutdown. During shutdown, handlers run freely for most of the `shutdown_timeout` before the cancellation signal fires—giving in-flight work time to complete. When cancelled, your handler receives `Async::Stop` at the next yield point (I/O operation, sleep, etc.).
@@ -1064,23 +1129,24 @@ Ensure you have thoroughly tested your changes before merging to `main`.
 ### Prosody::Client
 
 - `new(config)` or `new(**options)`: Create a client from a `Configuration`, hash, or keyword options.
+- `open(config) { |client| ... }`: Create a client, yield it, and shut it down when the block exits. It returns the value of the block.
 - `send_message(String topic, String key, Prosody::json_value payload)`: Send a JSON-serializable message.
 - `excise(String topic, String key)`: Send an excise record for a key.
 - `request(topic:, key:, payload:, subsystems:, timeout:)`: Return one outcome for each subsystem.
 - `request_excise(topic:, key:, subsystems:, timeout:)`: Return one excise outcome for each subsystem.
 - `consumer_state`: Get the client state (`:shut_down`, `:unconfigured`, `:configured`, or `:running`).
 - `source_system`: Get the source system identifier configured for the client.
-- `state(subsystem, definition)`: Open a typed, read-only published value, map, or deque.
+- `state(subsystem, definition)`: Open a typed, read-only published value, map, set, or deque.
 - `subscribe(handler)`: Start event processing with the specified handler.
 - `unsubscribe`: Stop the consumer. You can subscribe again later.
 - `shutdown`: Stop all client services. Concurrent and repeated calls wait for the same operation.
-- `assigned_partitions`: Get the number of partitions currently assigned to this consumer.
-- `is_stalled?`: Check if the consumer has stalled partitions.
+- `assigned_partition_count`: Get the number of partitions currently assigned to this consumer.
+- `stalled?`: Check if the consumer has stalled partitions.
 
 ### Prosody::AdminClient
 
 - `new(bootstrap_servers)`: Create an admin client for the specified Kafka servers.
-- `create_topic(name, partitions, replication_factor)`: Create a Kafka topic.
+- `create_topic(name, partitions, replication_factor, cleanup_policy: nil, retention: nil)`: Create a Kafka topic. `cleanup_policy` is a Kafka cleanup policy such as `"delete"`, `"compact"`, or `"delete,compact"`. `retention` is the message retention in seconds. A `nil` keyword uses the cluster default.
 - `delete_topic(name)`: Delete a Kafka topic.
 
 ### Prosody::EventHandler
@@ -1144,10 +1210,12 @@ Messages have the following attributes:
 - `timestamp` (Time): The timestamp when the message was created or sent.
 - `key` (String): The message key.
 - `payload` (`Payload`): The JSON-deserialized message payload.
+- `source_system` (String or nil): The source system of the producer that sent the message, or `nil` when the message has none.
+- `response_requested?` (Boolean): Whether the producer requested a response. When it is false, Prosody discards the handler result, so a handler can skip work that only builds the response.
 
 ### Prosody::ExciseMessage
 
-An `ExciseMessage` has `topic`, `partition`, `offset`, `timestamp`, and `key` attributes. It has no `payload` attribute.
+An `ExciseMessage` has `topic`, `partition`, `offset`, `timestamp`, `key`, `source_system`, and `response_requested?` attributes. It has no `payload` attribute.
 
 ### Prosody::Context
 
@@ -1155,7 +1223,8 @@ Represents the current event context:
 
 - `should_cancel?`: Check if cancellation has been requested (includes timeout and shutdown).
 - `on_cancel`: Wait until cancellation occurs.
-- `state(definition)`: Bind a registered collection for the current attempt. An unregistered or mismatched definition raises `PermanentStateError`. See [Keyed State](#keyed-state-2).
+- `demand`: A `Prosody::Demand` that tells whether this call is a normal delivery or a retry. `kind` is `:normal` or `:failure`, and `normal?` and `failure?` test it. `retries` is the number of retries: 0 for a normal delivery and 1 on the first retry. The count is an estimate. Keep an exact attempt count in keyed state if you need one.
+- `state(definition)`: Bind a registered collection for the current attempt. An unregistered or mismatched definition raises `PermanentStateError`. See [Keyed State](#keyed-state).
 
 Timer scheduling methods:
 
@@ -1186,6 +1255,7 @@ Definition constructors (each returns a frozen definition object used both in `C
 
 - `Prosody.value(name, ttl: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
 - `Prosody.map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
+- `Prosody.set(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
 - `Prosody.deque(name, ttl: nil, capacity: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
 - `Prosody.message_value(name, ttl: nil, read_uncommitted: nil)`
 - `Prosody.message_map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil)`
@@ -1195,13 +1265,15 @@ Each constructor returns a `StateDefinition`. It exposes `name`, `kind`, `payloa
 
 Published readers take the user key as their first argument. `Prosody::PublishedValue` provides `get`.
 
-`Prosody::PublishedMap` provides `get`, `get_many`, `key?`, `has_key?`, `include?`, and `member?`.
+`Prosody::PublishedMap` provides `get`, `get_many`, `key?`, `has_key?`, `include?`, `member?`, `contains_many`, and `empty?`.
 
 It provides `each` or `each_pair`, `each_key`, and `each_value`. The reverse methods are `reverse_each_pair`, `reverse_each_key`, and `reverse_each_value`.
 
+`Prosody::PublishedSet` provides `include?` or `member?`, `contains_many`, `empty?`, `each`, and `reverse_each`.
+
 `Prosody::PublishedDeque` provides `get`, `length` or `size`, `empty?`, `first`, `last`, `each`, and `reverse_each`.
 
-Traversal methods return an `Enumerator` without a block.
+Traversal methods return an `Enumerator` without a block. Every traversal accepts the optional [query keywords](#query-keywords) `from:`, `after:`, `to:`, `before:`, `range:`, and `limit:`. Map and set traversals also accept `prefix:`.
 
 `Prosody::ValueState`:
 
@@ -1210,10 +1282,16 @@ Traversal methods return an `Enumerator` without a block.
 `Prosody::MapState` (keys are `String`):
 
 - `get` / `[]`, `get_many`, `set` / `[]=`, `store`, `delete`, and `clear`
-- `key?`, `has_key?`, `include?`, `member?`, `dig`, `slice`, `values_at`, `fetch`, and `fetch_values`
+- `key?`, `has_key?`, `include?`, `member?`, `contains_many`, `empty?`, `dig`, `slice`, `values_at`, `fetch`, and `fetch_values`
 - `each` / `each_pair`, `each_key`, and `each_value`, including each reverse form
 - `commit` and `rollback`
 
+`Prosody::SetState` (members are `String`):
+
+- `add` / `<<`, `delete`, and `clear`, which return the set
+- `include?` / `member?`, `contains_many`, and `empty?`
+- `each` / `reverse_each`, `commit`, and `rollback`
+
 `Prosody::DequeState`:
 
 - `push`, `append`, `<<`, `unshift`, `prepend`, `pop`, and `shift`
@@ -1223,8 +1301,7 @@ Traversal methods return an `Enumerator` without a block.
 Errors:
 
 - `Prosody::TransientStateError < Prosody::TransientError`: Reports a keyed-state error that Prosody can retry.
-- `Prosody::PermanentStateError < Prosody::PermanentError`: Reports a keyed-state error that another attempt cannot resolve.
-- `Prosody::NullValueError < Prosody::TransientStateError`: raised when a `nil` is written; use `clear`/`delete` instead.
+- `Prosody::PermanentStateError < Prosody::PermanentError`: Reports a keyed-state error that another attempt cannot resolve, such as a `nil` write.
 
 Handler error types: