docs: plain up prose in README, guides, CONTEXT and AGENTS (#108)

Author: lesnik512

AGENTS.md

@@ -1,20 +1,20 @@
 # faststream-redis-timers
 
 FastStream broker integration for Redis-backed distributed timer scheduling.
-[`CONTEXT.md`](CONTEXT.md) opens with what it does and owns the vocabulary — read it before naming
+[`CONTEXT.md`](CONTEXT.md) opens with what it does and owns the vocabulary. Read it before naming
 a concept in code, a test name, or an issue title.
 
 ## Commands
 
-`just` (task runner) and `uv` (package manager). The [`justfile`](justfile) is the source of truth —
+`just` (task runner) and `uv` (package manager). The [`justfile`](justfile) is the source of truth:
 `just --list`, or read it. The things it does not say:
 
 - `tests/test_unit.py`, `tests/test_fake.py`, `tests/test_store_seam.py` and
   `tests/test_tuning_defaults.py` need no Redis; the rest (the integration suites) do.
 - Verifying a Python-version / interpreter-compat change: run the **full** suite on the target
   interpreter (the CI matrix, or `just test` in docker), not just the no-Redis subset. An
-  integration-only failure — e.g. a broker-shutdown hang that only bites under a specific
-  interpreter's async timing — won't surface in the no-Redis subset alone.
+  integration-only failure, such as a broker-shutdown hang that only bites under a specific
+  interpreter's async timing, won't surface in the no-Redis subset alone.
 
 ## Workflow
 

CONTEXT.md

@@ -9,24 +9,24 @@ at-least-once delivery across a fleet of workers sharing one Redis.
 A term is listed only when there is a synonym to reject, or a meaning subtle enough that code and
 docs must agree on it. General programming vocabulary does not belong here, however heavily this
 package uses it. Class and method names that mean what they say (`TimerStore`, `cancel_timer`) are
-not listed — read the module.
+not listed; read the module.
 
-FastStream owns the framing vocabulary this package plugs into — broker, subscriber, publisher,
+FastStream owns the framing vocabulary this package plugs into: broker, subscriber, publisher,
 router, message, handler, `ack`/`nack`/`reject`. Nothing here redefines one of those.
 
 **Timer**:
 A scheduled future delivery: a message bound to a Topic that becomes deliverable at its Activation
-time, identified by a `timer_id`. The Timer is the *record*, not the message it carries — a Timer
+time, identified by a `timer_id`. The Timer is the *record*, not the message it carries: a Timer
 has a lifecycle (Scheduled → Due → Claimed → Committed) that its payload does not.
 
 **Topic**:
 The named channel a Timer is Scheduled on and that a subscriber consumes from. Two Redis keys are
 derived per Topic; a Timer only ever exists on one.
-_Avoid_: queue — a Topic is not a work queue, and the difference matters: Timers on a Topic are
+_Avoid_: queue. A Topic is not a work queue: Timers on a Topic are
 ordered by Activation time, not arrival, and a Claimed Timer stays on the Topic rather than leaving
 it. `channel` survives only where FastStream owns the spelling: the `raw_message` field, the
 log-context key, and `channel_labels` with the AsyncAPI document it feeds, where a Topic is a
-channel — say *AsyncAPI channel* there. In our own prose it is Topic.
+channel, so say *AsyncAPI channel* there. In our own prose it is Topic.
 
 **Activation time**:
 The single absolute UTC instant at which a Timer becomes Due. Exactly one of `activate_in` (a
@@ -36,17 +36,17 @@ advances its Activation time rather than moving the Timer anywhere, so "Activati
 differently before and after a Claim.
 
 **Schedule**:
-To register a new Timer to become Due at its Activation time. The method is `publish()` — FastStream
-names every producer entry point that way and this package keeps the parity — but the domain verb is
-Schedule, and prose should use it. There is no separate publish concept.
+To register a new Timer to become Due at its Activation time. The method is `publish()` because FastStream
+names every producer entry point that way and this package keeps the parity. The domain verb is
+still Schedule, and prose should use it. There is no separate publish concept.
 
 **Due**:
 Describes a Timer whose Activation time has passed, and which is therefore eligible to be Claimed.
 Due is derived, never stored: it is a comparison against the current time, which is why the same
 Timer is Due to a poll one moment and not the next.
 
 **Pending**:
-Describes a Timer that has been Scheduled and neither Committed nor cancelled — *including* one
+Describes a Timer that has been Scheduled and neither Committed nor cancelled, *including* one
 currently Claimed, whose Activation time sits in the future under its Lease. `has_pending` is
 therefore true for a Timer whose handler is already running; `get_pending_timers(before=now)`
 excludes those.
@@ -59,7 +59,7 @@ recorded, and nothing to release. A contested Claim returns nothing and is simpl
 **Lease**:
 The time window a Claim buys, `lease_ttl` seconds wide. It expires on its own; a worker that dies
 mid-handler releases nothing, the Timer simply becomes Due again. A handler that outruns its Lease
-can be redelivered while still running — that is what makes delivery at-least-once rather than
+can be redelivered while still running, which is what makes delivery at-least-once rather than
 exactly-once.
 
 **Commit**:

README.md

@@ -24,7 +24,7 @@ Schedule messages to be delivered to subscribers at a future point in time, with
 
 > **Already using Postgres?** Prefer [`faststream-outbox`](https://github.com/modern-python/faststream-outbox), which also supports
 > [timers](https://faststream-outbox.modern-python.org/usage/timers/) and lets you schedule a timer in the **same SQLAlchemy
-> transaction** as the domain write — no dual-write between your DB and Redis. Reach for `faststream-redis-timers` when your stack
+> transaction** as the domain write, which avoids a dual-write between your DB and Redis. Reach for `faststream-redis-timers` when your stack
 > doesn't include Postgres, or when you want timer scheduling decoupled from your relational store.
 
 ```python
@@ -72,10 +72,10 @@ Timers are stored in Redis as two keys **per topic**:
 - A **sorted set** (`timers_timeline:{topic}`) with the activation timestamp as score
 - A **hash** (`timers_payloads:{topic}`) with the serialized message body
 
-So a timer on the `invoices` topic lives under `timers_timeline:invoices` and `timers_payloads:invoices` — handy when poking around in `redis-cli`. A `TimersRouter(prefix="my-service:")` extends the suffix to `my-service:invoices`.
+So a timer on the `invoices` topic lives under `timers_timeline:invoices` and `timers_payloads:invoices`; those are the keys to look up in `redis-cli`. A `TimersRouter(prefix="my-service:")` extends the suffix to `my-service:invoices`.
 
 A polling loop checks for due timers and atomically claims each one via a Lua
-script that pushes its score forward by `lease_ttl` seconds — granting the
+script that pushes its score forward by `lease_ttl` seconds, which grants the
 worker a lease. The timer is removed from Redis only **after** the handler
 completes successfully. If the worker crashes mid-handler or the handler
 raises, the lease eventually expires and another worker re-claims the timer.
@@ -93,7 +93,7 @@ await broker.cancel_timer("invoices", timer_id)
 
 ## Tracing & headers
 
-`publish()` accepts `correlation_id` and `headers` — both round-trip to the handler via the standard FastStream `StreamMessage`:
+`publish()` accepts `correlation_id` and `headers`. Both round-trip to the handler via the standard FastStream `StreamMessage`:
 
 ```python
 await broker.publish(
@@ -120,7 +120,7 @@ async def handle(
 
 ## Connection ownership
 
-`TimersBroker` does **not** close the Redis client you pass in — the caller owns
+`TimersBroker` does **not** close the Redis client you pass in; the caller owns
 its lifecycle. The same client can be shared across multiple brokers, so closing
 it from one broker would surprise the others. Manage the client with `async with`
 or a `try/finally`:
@@ -136,16 +136,16 @@ async with Redis.from_url("redis://localhost:6379") as client:
 
 Per-subscriber knobs (passed to `@broker.subscriber("topic", ...)`):
 
-- `lease_ttl` (default `30` seconds) — how long a worker holds the lease while
+- `lease_ttl` (default `30` seconds): how long a worker holds the lease while
   processing. Handlers must complete within this window or another worker may
   re-deliver the timer (duplicate). Increase if your handlers are slow.
-- `polling_interval` (default `0.05` s) — base poll interval used when the topic
+- `polling_interval` (default `0.05` s): base poll interval used when the topic
   has due timers or just transitioned from idle. Doubles on each consecutive empty
   cycle, capped at `max_polling_interval`, with ±50% jitter applied before the cap.
-- `max_polling_interval` (default `5.0` s) — ceiling for the adaptive idle
+- `max_polling_interval` (default `5.0` s): ceiling for the adaptive idle
   backoff. Lower it for tighter delivery latency on idle topics; raise it to
   reduce Redis load on workloads with long idle stretches.
-- `max_concurrent` (default `5`) — maximum number of handlers running in
+- `max_concurrent` (default `5`): maximum number of handlers running in
   parallel per subscriber. Also caps the fetch batch size per poll cycle.
   Handlers must be safe under concurrency in addition to being idempotent.
 
@@ -155,7 +155,7 @@ Per-subscriber knobs (passed to `@broker.subscriber("topic", ...)`):
   ack failed to land in Redis (network blip) will be retried; a handler that
   takes longer than `lease_ttl` may be re-delivered to another worker.
 - **Buggy handler retries forever.** If a handler always raises, the timer is
-  retried every `lease_ttl` seconds indefinitely — there is no built-in
+  retried every `lease_ttl` seconds indefinitely, since there is no built-in
   attempt counter. Raise `faststream.exceptions.RejectMessage` from your
   handler to drop a poison-pill timer permanently, or track attempts in your
   own state if you need a hard cap.
@@ -188,4 +188,4 @@ broker = TimersBroker(
 ## Part of `modern-python`
 
 Browse the full list of templates and libraries in
-[`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
+[`modern-python`](https://github.com/modern-python); the org profile has the categorized index.

docs/index.md

@@ -14,7 +14,7 @@ Schedule messages to be delivered to subscribers at a future point in time, with
 !!! tip "Already using Postgres? Prefer `faststream-outbox`"
     [`faststream-outbox`](https://github.com/modern-python/faststream-outbox) also supports
     [timers](https://faststream-outbox.modern-python.org/usage/timers/) and lets you schedule a timer in the
-    **same SQLAlchemy transaction** as the domain write — no dual-write between your DB and Redis. Reach for
+    **same SQLAlchemy transaction** as the domain write, which avoids a dual-write between your DB and Redis. Reach for
     `faststream-redis-timers` when your stack doesn't include Postgres, or when you want timer scheduling decoupled
     from your relational store.
 

docs/introduction/how-it-works.md

@@ -16,26 +16,26 @@ ZADD timers_timeline:invoices <activation_ts> abc-123
 HSET timers_payloads:invoices abc-123 <encoded_envelope>
 ```
 
-The envelope is FastStream's `BinaryMessageFormatV1` — a binary-safe wire format that carries the message body alongside `correlation_id`, `content-type`, `reply_to`, and any user-supplied headers. The same format is used by FastStream's built-in Redis broker.
+The envelope is FastStream's `BinaryMessageFormatV1`, a binary-safe wire format that carries the message body alongside `correlation_id`, `content-type`, `reply_to`, and any user-supplied headers. The same format is used by FastStream's built-in Redis broker.
 
 ## Polling loop
 
 Each subscriber runs a background polling loop that:
 
 1. Calls `ZRANGEBYSCORE timers_timeline:{topic} -inf <now> LIMIT 0 <free>` (where `<free>` is the unused capacity from the per-subscriber concurrency limiter) to find due timers
-2. For each due timer, spawns a task that — bounded by the `max_concurrent` capacity limiter — runs an atomic Lua **claim** script that:
+2. For each due timer, spawns a task (bounded by the `max_concurrent` capacity limiter) that runs an atomic Lua **claim** script that:
     - Verifies the timer is still due (score ≤ now)
-    - Pushes its score forward by `lease_ttl` seconds — granting the worker a lease
+    - Pushes its score forward by `lease_ttl` seconds, which grants the worker a lease
     - Returns the payload
 3. Delivers the payload to the user handler
 4. On handler success, runs an atomic Lua **commit** script (`ZREM` + `HDEL`) to remove the timer from Redis
-5. On handler exception, leaves the timer in place — the lease eventually expires and another worker re-claims it
+5. On handler exception, leaves the timer in place; the lease eventually expires and another worker re-claims it
 
-This is the standard SQS-style **visibility-timeout** pattern. The timer's own score in the sorted set acts as the lease deadline — there is no separate lock primitive.
+This is the standard SQS-style **visibility-timeout** pattern. The timer's own score in the sorted set is the lease deadline; there is no separate lock primitive.
 
 ## At-least-once delivery
 
-The lease ensures each due timer is processed by exactly one worker at a time. Because the timer is removed from Redis only after the handler completes successfully, **no timer is lost on crash** — if the worker dies mid-handler, the lease expires and the timer is re-delivered.
+The lease ensures each due timer is processed by exactly one worker at a time. Because the timer is removed from Redis only after the handler completes successfully, **no timer is lost on crash**: if the worker dies mid-handler, the lease expires and the timer is re-delivered.
 
 The trade-off: handlers that take longer than `lease_ttl`, or workers that crash after the handler ran but before the commit landed, may see the timer delivered more than once. Handlers must therefore be **idempotent**.
 
@@ -44,8 +44,8 @@ The trade-off: handlers that take longer than `lease_ttl`, or workers that crash
 | Action | Effect |
 |--------|--------|
 | `ack` | Atomically removes the timer from `timers_timeline` and `timers_payloads` |
-| `nack` | No-op — the lease expires and another worker re-claims the timer |
-| `reject` | Same as `ack` — permanently removes the timer (use for poison-pill messages) |
+| `nack` | No-op; the lease expires and another worker re-claims the timer |
+| `reject` | Same as `ack`: permanently removes the timer (use for poison-pill messages) |
 
 The default ack policy is `NACK_ON_ERROR`: the timer is acknowledged on success, and left for retry on any unhandled exception.
 
@@ -64,7 +64,7 @@ The default ack policy is `NACK_ON_ERROR`: the timer is acknowledged on success,
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `polling_interval` | `0.05` s | Base poll interval used when the topic has due timers or just transitioned from idle |
-| `max_polling_interval` | `5.0` s | Ceiling for the adaptive idle backoff — `polling_interval` doubles up to this value on consecutive empty polls. Jitter is applied before the cap, so worst-case delivery latency on a previously-idle topic is `max_polling_interval` |
+| `max_polling_interval` | `5.0` s | Ceiling for the adaptive idle backoff: `polling_interval` doubles up to this value on consecutive empty polls. Jitter is applied before the cap, so worst-case delivery latency on a previously-idle topic is `max_polling_interval` |
 | `max_concurrent` | `5` | Max handlers running concurrently per subscriber; also bounds fetch batch size |
 | `lease_ttl` | `30` s | How long a worker holds the lease before another worker may re-claim. Set to ~3–5× the P99 handler runtime: lower values speed up recovery from worker death, higher values tolerate handler GC pauses and clock skew |