@prosody-events/prosody 0.3.1 → 0.5.0

package/README.md

@@ -21,56 +21,87 @@ strategies, and integrated OpenTelemetry support for distributed tracing.
 npm install @prosody-events/prosody
 ```
 
+The package ships TypeScript declarations for the public API.
+`EventHandler<P, R>` carries application payload and response types through each
+handler method. Keyed-state definitions carry their item types through
+`context.state()`. Unparameterized API types default to `JsonValue`. See the
+[strict TypeScript examples](examples/) for IDE-ready projects compiled by the
+repository typecheck.
+
 ## Quick Start
 
+Run each example in an asynchronous function unless the example defines one.
+
 ```javascript
-const {ProsodyClient} = require('@prosody-events/prosody');
+const { ProsodyClient } = require("@prosody-events/prosody");
 
-// Initialize the client with Kafka bootstrap servers, consumer group, and topics
-const client = new ProsodyClient({
+async function main() {
+  // Initialize the client with Kafka bootstrap servers, consumer group, and topics
+  const client = await ProsodyClient.create({
     // Bootstrap servers should normally be set using the PROSODY_BOOTSTRAP_SERVERS environment variable
     bootstrapServers: "localhost:9092",
 
-    // To allow loopbacks, the source_system must be different from the group_id.
-    // Normally, the source_system would be left unspecified, which would default to the group_id.
+    // To allow loopbacks, sourceSystem must be different from groupId.
+    // Normally, sourceSystem is omitted and defaults to groupId.
     sourceSystem: "my-application-source",
 
-    // The group_id should be set to the name of your application
+    // groupId should be set to the name of your application
     groupId: "my-consumer-group",
 
     // Topics the client should subscribe to
-    subscribedTopics: "my-topic"
-});
+    subscribedTopics: "my-topic",
+  });
+
+  // Define a message handler
+  const messageHandler = {
+    onExcise: async (context, message, signal) => {
+      console.log(`Excise key: ${message.key}`);
+      await context.clearScheduled();
+      return null;
+    },
 
-// Define a message handler
-const messageHandler = {
     onMessage: async (context, message, signal) => {
-        // Process the received message
-        console.log(`Received message: ${JSON.stringify(message)}`);
-        
-        // Schedule a timer for delayed processing
-        if (message.payload.scheduleFollowup) {
-            const followupTime = new Date(Date.now() + 30000); // 30 seconds from now
-            await context.schedule(followupTime);
-        }
+      // Process the received message
+      console.log(`Received message: ${JSON.stringify(message)}`);
+
+      // Schedule a timer for delayed processing
+      if (message.payload.scheduleFollowup) {
+        const followupTime = new Date(Date.now() + 30000); // 30 seconds from now
+        await context.schedule(followupTime);
+      }
+      return null;
     },
-    
+
     onTimer: async (context, timer, signal) => {
-        // Handle timer firing
-        console.log(`Timer fired for key: ${timer.key} at ${timer.time}`);
-    }
-};
+      // Handle timer firing
+      console.log(`Timer fired for key: ${timer.key} at ${timer.time}`);
+    },
+  };
 
-// Subscribe to messages using the message handler
-client.subscribe(messageHandler);
+  // Subscribe to messages using the message handler
+  await client.subscribe(messageHandler);
+
+  // Send a message to a topic
+  await client.send("my-topic", "message-key", { content: "Hello, Kafka!" });
+  await client.excise("my-topic", "obsolete-key");
 
-// Send a message to a topic
-await client.send("my-topic", "message-key", {content: "Hello, Kafka!"});
+  // Shut down all client services when done
+  await client.shutdown();
+}
 
-// Ensure proper shutdown when done
-await client.unsubscribe();
+main().catch(console.error);
 ```
 
+## Excise records
+
+Applications can copy event data into keyed state and external stores. A regulatory or contractual deletion must remove every copy for one key.
+
+An excise record carries this deletion command. Kafka encodes the command as a key with no payload. During topic compaction, Kafka deletes earlier values for the key. Call `excise(topic, key)` to send the record. Prosody routes the record to `onExcise`. The handler must delete all consumer-owned data for the key.
+
+Each handler must implement `onMessage`, `onExcise`, and `onTimer`. Subscription fails before consumption if a method is missing.
+
+If an excise record is a request, return a response from `onExcise`. Prosody uses this response as the subsystem result.
+
 ## Architecture
 
 Prosody enables efficient, parallel processing of Kafka messages while maintaining order for messages with the same key:
@@ -109,13 +140,13 @@ When the timer fires, reload the message from Kafka and retry.
 
 ```javascript
 // Configure defer behavior
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    deferEnabled: true,           // Enable deferral (default: true)
-    deferBaseMs: 1000,            // Wait 1s before first retry
-    deferMaxDelayMs: 86400000,    // Cap at 24 hours
-    deferFailureThreshold: 0.9    // Disable when >90% failing
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  deferEnabled: true, // Enable deferral (default: true)
+  deferBaseMs: 1000, // Wait 1s before first retry
+  deferMaxDelayMs: 86400000, // Cap at 24 hours
+  deferFailureThreshold: 0.9, // Disable when >90% failing
 });
 ```
 
@@ -131,12 +162,12 @@ with a transient error, routing them through defer.
 
 ```javascript
 // Configure monopolization detection
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    monopolizationEnabled: true,     // Enable detection (default: true)
-    monopolizationThreshold: 0.9,    // Reject keys using >90% of window
-    monopolizationWindowMs: 300000   // 5-minute window
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  monopolizationEnabled: true, // Enable detection (default: true)
+  monopolizationThreshold: 0.9, // Reject keys using >90% of window
+  monopolizationWindowMs: 300000, // 5-minute window
 });
 ```
 
@@ -145,11 +176,11 @@ const client = new ProsodyClient({
 Handlers are automatically cancelled if they exceed a deadline:
 
 ```javascript
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    timeoutMs: 30000,            // Cancel after 30 seconds
-    stallThresholdMs: 60000      // Report unhealthy after 60 seconds
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  timeoutMs: 30000, // Cancel after 30 seconds
+  stallThresholdMs: 60000, // Report unhealthy after 60 seconds
 });
 ```
 
@@ -158,109 +189,11 @@ exit promptly. If not specified, timeout defaults to 80% of `stallThresholdMs`.
 
 ## Configuration
 
-Configure via constructor options or environment variables. Options fall back to environment variables when unset.
-
-### Core
-
-| Option / Environment Variable           | Description                                       | Default      |
-|-----------------------------------------|---------------------------------------------------|--------------|
-| `bootstrapServers` / `PROSODY_BOOTSTRAP_SERVERS` | Kafka servers to connect to               | -            |
-| `groupId` / `PROSODY_GROUP_ID`          | Consumer group name                               | -            |
-| `subscribedTopics` / `PROSODY_SUBSCRIBED_TOPICS` | Topics to read from                      | -            |
-| `allowedEvents` / `PROSODY_ALLOWED_EVENTS` | Only process events matching these prefixes    | (all)        |
-| `sourceSystem` / `PROSODY_SOURCE_SYSTEM` | Tag for outgoing messages (prevents reprocessing)| `<groupId>`  |
-| `mock` / `PROSODY_MOCK`                 | Use in-memory Kafka for testing                   | false        |
-
-### Consumer
-
-| Option / Environment Variable           | Description                                          | Default                |
-|-----------------------------------------|------------------------------------------------------|------------------------|
-| `maxConcurrency` / `PROSODY_MAX_CONCURRENCY` | Max messages being processed simultaneously     | 32                     |
-| `maxUncommitted` / `PROSODY_MAX_UNCOMMITTED` | Max queued messages before pausing consumption  | 64                     |
-| `timeoutMs` / `PROSODY_TIMEOUT`         | Cancel handler if it runs longer than this           | 80% of stall threshold |
-| `commitIntervalMs` / `PROSODY_COMMIT_INTERVAL` | How often to save progress to Kafka            | 1s                     |
-| `pollIntervalMs` / `PROSODY_POLL_INTERVAL` | How often to fetch new messages from Kafka        | 100ms                  |
-| `shutdownTimeoutMs` / `PROSODY_SHUTDOWN_TIMEOUT` | Wait this long for in-flight work before force-quit | 30s              |
-| `stallThresholdMs` / `PROSODY_STALL_THRESHOLD` | Report unhealthy if no progress for this long  | 5m                     |
-| `probePort` / `PROSODY_PROBE_PORT`      | HTTP port for health checks (null to disable)        | 8000                   |
-| `failureTopic` / `PROSODY_FAILURE_TOPIC` | Send unprocessable messages here (dead letter queue) | -                     |
-| `idempotenceCacheSize` / `PROSODY_IDEMPOTENCE_CACHE_SIZE` | Global shared cache capacity across all partitions for deduplicating messages. Set to 0 to disable the entire deduplication middleware (both in-memory cache and Cassandra persistent store) | 8192 |
-| `idempotenceVersion` / `PROSODY_IDEMPOTENCE_VERSION` | Version string for cache-busting dedup hashes | `"1"`          |
-| `idempotenceTtlS` / `PROSODY_IDEMPOTENCE_TTL`       | TTL for dedup records in Cassandra in seconds | 604800  |
-| `slabSizeMs` / `PROSODY_SLAB_SIZE`      | Timer storage granularity (rarely needs changing)    | 1h                     |
-| `messageSpans` / `PROSODY_MESSAGE_SPANS` | Span linking for message execution: `child` (child-of) or `follows_from` | `child` |
-| `timerSpans` / `PROSODY_TIMER_SPANS`    | Span linking for timer execution: `child` (child-of) or `follows_from`   | `follows_from` |
-
-### Producer
-
-| Option / Environment Variable           | Description                     | Default |
-|-----------------------------------------|---------------------------------|---------|
-| `sendTimeoutMs` / `PROSODY_SEND_TIMEOUT` | Give up sending after this long | 1s      |
-
-### Retry
-
-When a handler fails, retry with exponential backoff:
-
-| Option / Environment Variable           | Description                       | Default |
-|-----------------------------------------|-----------------------------------|---------|
-| `maxRetries` / `PROSODY_MAX_RETRIES`    | Give up after this many attempts  | 3       |
-| `retryBaseMs` / `PROSODY_RETRY_BASE`    | Wait this long before first retry | 20ms    |
-| `maxRetryDelayMs` / `PROSODY_RETRY_MAX_DELAY` | Never wait longer than this  | 5m      |
-
-### Deferral (Pipeline Mode)
-
-| Option / Environment Variable           | Description                                       | Default |
-|-----------------------------------------|---------------------------------------------------|---------|
-| `deferEnabled` / `PROSODY_DEFER_ENABLED` | Enable deferral for new messages                 | true    |
-| `deferBaseMs` / `PROSODY_DEFER_BASE`    | Wait this long before first deferred retry        | 1s      |
-| `deferMaxDelayMs` / `PROSODY_DEFER_MAX_DELAY` | Never wait longer than this                  | 24h     |
-| `deferFailureThreshold` / `PROSODY_DEFER_FAILURE_THRESHOLD` | Disable deferral when failure rate exceeds this | 0.9 |
-| `deferFailureWindowMs` / `PROSODY_DEFER_FAILURE_WINDOW` | Measure failure rate over this time window | 5m      |
-| `deferCacheSize` / `PROSODY_DEFER_CACHE_SIZE` | Track this many deferred keys in memory      | 1024    |
-| `deferStoreCacheSize` / `PROSODY_DEFER_STORE_CACHE_SIZE` | Maximum deferred store cache entries per Cassandra defer store | 8192 |
-| `deferSeekTimeoutMs` / `PROSODY_DEFER_SEEK_TIMEOUT` | Timeout when loading deferred messages     | 30s     |
-| `deferDiscardThreshold` / `PROSODY_DEFER_DISCARD_THRESHOLD` | Read optimization (rarely needs changing) | 100   |
+For the complete configuration reference, see [CONFIGURATION.md](CONFIGURATION.md).
 
-### Monopolization Detection (Pipeline Mode)
-
-| Option / Environment Variable           | Description                             | Default |
-|-----------------------------------------|-----------------------------------------|---------|
-| `monopolizationEnabled` / `PROSODY_MONOPOLIZATION_ENABLED` | Enable hot key protection    | true    |
-| `monopolizationThreshold` / `PROSODY_MONOPOLIZATION_THRESHOLD` | Max handler time as fraction of window | 0.9 |
-| `monopolizationWindowMs` / `PROSODY_MONOPOLIZATION_WINDOW` | Measurement window             | 5m      |
-| `monopolizationCacheSize` / `PROSODY_MONOPOLIZATION_CACHE_SIZE` | Max distinct keys to track   | 8192    |
-
-### Fair Scheduling (All Modes)
-
-| Option / Environment Variable           | Description                                                      | Default |
-|-----------------------------------------|------------------------------------------------------------------|---------|
-| `schedulerFailureWeight` / `PROSODY_SCHEDULER_FAILURE_WEIGHT` | Fraction of processing time reserved for retries | 0.3     |
-| `schedulerMaxWaitMs` / `PROSODY_SCHEDULER_MAX_WAIT` | Messages waiting this long get maximum priority           | 2m      |
-| `schedulerWaitWeight` / `PROSODY_SCHEDULER_WAIT_WEIGHT` | Priority boost for waiting messages (higher = more aggressive) | 200.0 |
-| `schedulerCacheSize` / `PROSODY_SCHEDULER_CACHE_SIZE` | Max distinct keys to track                              | 8192    |
-
-### Telemetry Emitter
-
-Produces message and timer lifecycle events to a Kafka topic for observability:
+Constructor options take precedence. Unset options use environment variables, then library defaults.
 
-| Option / Environment Variable           | Description                                       | Default                    |
-|-----------------------------------------|---------------------------------------------------|----------------------------|
-| `telemetryEnabled` / `PROSODY_TELEMETRY_ENABLED` | Produce lifecycle events to Kafka            | true                       |
-| `telemetryTopic` / `PROSODY_TELEMETRY_TOPIC` | Kafka topic for telemetry events             | prosody.telemetry-events   |
-
-### Cassandra
-
-Persistent storage for timers and deferred retries (not needed if `mock: true`):
-
-| Option / Environment Variable           | Description                        | Default |
-|-----------------------------------------|------------------------------------|---------|
-| `cassandraNodes` / `PROSODY_CASSANDRA_NODES` | Servers to connect to (host:port) | -      |
-| `cassandraKeyspace` / `PROSODY_CASSANDRA_KEYSPACE` | Keyspace name                | prosody |
-| `cassandraUser` / `PROSODY_CASSANDRA_USER` | Username                          | -       |
-| `cassandraPassword` / `PROSODY_CASSANDRA_PASSWORD` | Password                    | -       |
-| `cassandraDatacenter` / `PROSODY_CASSANDRA_DATACENTER` | Prefer this datacenter for queries | -  |
-| `cassandraRack` / `PROSODY_CASSANDRA_RACK` | Prefer this rack for queries      | -       |
-| `cassandraRetentionSeconds` / `PROSODY_CASSANDRA_RETENTION` | Delete data older than this | 1y     |
+Client construction is asynchronous. Replace `new ProsodyClient(config)` with `await ProsodyClient.create(config)`.
 
 ## Liveness and Readiness Probes
 
@@ -276,11 +209,11 @@ server is tied to the consumer's lifecycle and offers two main endpoints:
 Configure the probe server using either the client constructor:
 
 ```javascript
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    probePort: 8000,  // Set to null to disable
-    stallThresholdMs: 15000  // 15 seconds before considering a partition stalled
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  probePort: 8000, // Set to null to disable
+  stallThresholdMs: 15000, // 15 seconds before considering a partition stalled
 });
 ```
 
@@ -309,10 +242,64 @@ const partitionCount = client.assignedPartitionCount;
 
 // You can use these in your own health checks or monitoring
 if (client.isStalled) {
-    console.warn('Consumer has stalled partitions');
+  console.warn("Consumer has stalled partitions");
 }
 ```
 
+## Subsystems
+
+A consumer group ID identifies a set of processes that share records and the keyed state that the group owns. A subsystem can include one or more services and consumer groups. If callers use these IDs, a refactor can require changes to each caller.
+
+A subsystem gives requests and published state one stable public name. Callers use this name instead of consumer group IDs. You can change its services and consumer groups without changing callers. Prosody uses the first response to a subsystem request. For each published-state read, it uses one consumer group that publishes the collection.
+
+## Requests
+
+Kafka decouples producers from consumers, so a send does not return consumer results. This asynchronous model lets each service process records independently. Some operations must wait for consumer results before they continue. A request recovers synchrony for the caller while consumers continue asynchronous processing.
+
+Send a request from a handler or other application code. The Prosody client does not need an active subscription. The result map uses canonical subsystem names as keys. Each value is a `Success` or `Failure` outcome. Use `requestExcise` to send an excise record and collect the same outcome type.
+
+Do not rely on map order. The map contains one entry for each selected subsystem. A missing response becomes a timeout `Failure`; Prosody does not omit the subsystem. The request rejects for request-level failures, such as invalid input, a Kafka send failure, or shutdown. Do not await 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.
+
+Set `subsystem` to `inventory` on the client that subscribes this handler.
+
+```javascript
+await client.subscribe({
+  onMessage: async (_context, message) => ({ accepted: message.key }),
+  onExcise: async (_context, message) => ({ accepted: message.key }),
+  onTimer: async () => {},
+});
+```
+
+Send the request:
+
+```javascript
+const subsystems = ["inventory", "billing"];
+const results = await client.request(
+  "orders",
+  "order-1",
+  { type: "order.created" },
+  { subsystems, timeoutMs: 2_000 },
+);
+
+for (const [subsystem, outcome] of results) {
+  if (outcome.ok) console.log(`${subsystem}:`, outcome.value);
+  else console.error(`${subsystem}: ${outcome.error.message}`);
+}
+```
+
+The example can print these results:
+
+```text
+inventory: { accepted: 'order-1' }
+billing: no response arrived before the deadline
+```
+
+Each failure contains one typed response error.
+
+Each response error has one message.
+
 ## Advanced Usage
 
 ### Pipeline Mode
@@ -320,26 +307,27 @@ if (client.isStalled) {
 All messages must be processed. Retries indefinitely. Uses defer and monopolization detection.
 
 **Middleware stack:**
+
 ```
 Kafka → Deduplication → Retry → Defer → Monopolization → Shutdown → Scheduler → Timeout → Telemetry → Handler
 ```
 
-| Layer          | Purpose                                                  |
-|----------------|----------------------------------------------------------|
-| Deduplication  | Skips messages whose ID was already processed            |
-| Retry          | Retries transient errors indefinitely                    |
-| Defer          | Stores failing messages for timer-based retry            |
-| Monopolization | Rejects keys exceeding execution time threshold          |
-| Shutdown       | Drains in-flight work on partition revocation            |
-| Scheduler      | Enforces concurrency limits and VT-based priority        |
-| Timeout        | Cancels handlers exceeding deadline                      |
-| Telemetry      | Emits handler lifecycle events                           |
+| Layer          | Purpose                                           |
+| -------------- | ------------------------------------------------- |
+| Deduplication  | Skips messages whose ID was already processed     |
+| Retry          | Retries transient errors indefinitely             |
+| Defer          | Stores failing messages for timer-based retry     |
+| Monopolization | Rejects keys exceeding execution time threshold   |
+| Shutdown       | Drains in-flight work on partition revocation     |
+| Scheduler      | Enforces concurrency limits and VT-based priority |
+| Timeout        | Cancels handlers exceeding deadline               |
+| Telemetry      | Emits handler lifecycle events                    |
 
 ```javascript
-const client = new ProsodyClient({
-    mode: Mode.Pipeline,  // Default mode
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic"
+const client = await ProsodyClient.create({
+  mode: Mode.Pipeline, // Default mode
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
 });
 ```
 
@@ -352,12 +340,12 @@ Tries a few times, then routes failures to a dead letter topic.
 - Use when you need to keep moving and can reprocess failures later
 
 ```javascript
-const client = new ProsodyClient({
-    mode: Mode.LowLatency,
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    failureTopic: "failed-messages",  // Required for low-latency mode
-    maxRetries: 3                     // Give up after 3 attempts
+const client = await ProsodyClient.create({
+  mode: Mode.LowLatency,
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  failureTopic: "failed-messages", // Required for low-latency mode
+  maxRetries: 3, // Retry up to 3 times after the initial attempt
 });
 ```
 
@@ -370,10 +358,10 @@ Logs failures and moves on.
 - Use for development or when message loss is acceptable
 
 ```javascript
-const client = new ProsodyClient({
-    mode: Mode.BestEffort,
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic"
+const client = await ProsodyClient.create({
+  mode: Mode.BestEffort,
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
 });
 ```
 
@@ -384,10 +372,10 @@ of events:
 
 ```javascript
 // Process only events with types starting with "user." or "account."
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    allowedEvents: ["user.", "account."]
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  allowedEvents: ["user.", "account."],
 });
 ```
 
@@ -420,10 +408,10 @@ Prosody prevents processing loops in distributed systems by tracking the source
 
 ```javascript
 // Consumer and producer in one application
-const client = new ProsodyClient({
-    groupId: "my-service",
-    sourceSystem: "my-service-producer",  // Must differ from groupId to allow loopbacks; defaults to groupId
-    subscribedTopics: "my-topic"
+const client = await ProsodyClient.create({
+  groupId: "my-service",
+  sourceSystem: "my-service-producer", // Must differ from groupId to allow loopbacks; defaults to groupId
+  subscribedTopics: "my-topic",
 });
 ```
 
@@ -453,50 +441,34 @@ Deduplication uses a two-tier approach:
 - **Cassandra-backed persistent store**: Survives restarts and rebalances across instances. TTL controlled by
   `idempotenceTtlS` (default 7 days, i.e. 604800s).
 
-Setting `idempotenceCacheSize` to `0` disables the **entire** deduplication middleware, including both the in-memory
-cache and the Cassandra persistent store. No dedup lookups or writes will occur.
+Deduplication is always active. `idempotenceCacheSize` must be greater than `0`; a value of `0` (via either the option
+or `PROSODY_IDEMPOTENCE_CACHE_SIZE=0`) is rejected when the client is constructed.
 
 ```javascript
 // Messages with IDs are deduplicated per key
 await client.send("my-topic", "key1", {
-    id: "msg-123",      // Message will be processed
-    content: "Hello!"
+  id: "msg-123", // Message will be processed
+  content: "Hello!",
 });
 
 await client.send("my-topic", "key1", {
-    id: "msg-123",      // Message will be skipped (duplicate)
-    content: "Hello again!"
+  id: "msg-123", // Message will be skipped (duplicate)
+  content: "Hello again!",
 });
 
 await client.send("my-topic", "key2", {
-    id: "msg-123",      // Message will be processed (different key)
-    content: "Hello!"
-});
-```
-
-The entire deduplication middleware (both in-memory cache and Cassandra persistent store) can be disabled by setting `idempotenceCacheSize: 0`:
-
-```javascript
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    idempotenceCacheSize: 0  // Disable deduplication entirely
+  id: "msg-123", // Message will be processed (different key)
+  content: "Hello!",
 });
 ```
 
-Or via environment variable:
-
-```bash
-PROSODY_IDEMPOTENCE_CACHE_SIZE=0
-```
-
 To invalidate all previously recorded dedup entries (forcing reprocessing of messages), change the version:
 
 ```javascript
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic",
-    idempotenceVersion: "2"  // Changing this invalidates all previously recorded entries
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
+  idempotenceVersion: "2", // Changing this invalidates all previously recorded entries
 });
 ```
 
@@ -512,27 +484,33 @@ Prosody supports timer-based delayed execution within message handlers. When a t
 
 ```javascript
 const messageHandler = {
-    onMessage: async (context, message, signal) => {
-        // Schedule a timer to fire in 30 seconds
-        const futureTime = new Date(Date.now() + 30000);
-        await context.schedule(futureTime);
-        
-        // Schedule multiple timers
-        const oneMinute = new Date(Date.now() + 60000);
-        const twoMinutes = new Date(Date.now() + 120000);
-        await context.schedule(oneMinute);
-        await context.schedule(twoMinutes);
-        
-        // Check what's scheduled
-        const scheduled = await context.scheduled();
-        console.log(`Scheduled timers: ${scheduled.length}`);
-    },
-    
-    onTimer: async (context, timer, signal) => {
-        console.log('Timer fired!');
-        console.log(`Key: ${timer.key}`);
-        console.log(`Scheduled time: ${timer.time}`);
-    }
+  onMessage: async (context, message, signal) => {
+    // Schedule a timer to fire in 30 seconds
+    const futureTime = new Date(Date.now() + 30000);
+    await context.schedule(futureTime);
+
+    // Schedule multiple timers
+    const oneMinute = new Date(Date.now() + 60000);
+    const twoMinutes = new Date(Date.now() + 120000);
+    await context.schedule(oneMinute);
+    await context.schedule(twoMinutes);
+
+    // Check what's scheduled
+    const scheduled = await context.scheduled();
+    console.log(`Scheduled timers: ${scheduled.length}`);
+    return null;
+  },
+
+  onTimer: async (context, timer, signal) => {
+    console.log("Timer fired!");
+    console.log(`Key: ${timer.key}`);
+    console.log(`Scheduled time: ${timer.time}`);
+  },
+
+  onExcise: async (context) => {
+    await context.clearScheduled();
+    return null;
+  },
 };
 ```
 
@@ -566,11 +544,11 @@ PROSODY_CASSANDRA_NODES=localhost:9042  # Required for timer persistence
 Or programmatically when creating the client:
 
 ```javascript
-const client = new ProsodyClient({
-    bootstrapServers: "localhost:9092",
-    groupId: "my-application",
-    subscribedTopics: "my-topic",
-    cassandraNodes: "localhost:9042"  // Required unless mock: true
+const client = await ProsodyClient.create({
+  bootstrapServers: "localhost:9092",
+  groupId: "my-application",
+  subscribedTopics: "my-topic",
+  cassandraNodes: "localhost:9042", // Required unless mock: true
 });
 ```
 
@@ -578,11 +556,11 @@ For testing, you can use mock mode to avoid Cassandra dependency:
 
 ```javascript
 // Mock mode for testing (timers work but aren't persisted)
-const client = new ProsodyClient({
-    bootstrapServers: "localhost:9092",
-    groupId: "my-application",
-    subscribedTopics: "my-topic",
-    mock: true  // No Cassandra required in mock mode
+const client = await ProsodyClient.create({
+  bootstrapServers: "localhost:9092",
+  groupId: "my-application",
+  subscribedTopics: "my-topic",
+  mock: true, // No Cassandra required in mock mode
 });
 ```
 
@@ -591,24 +569,33 @@ const client = new ProsodyClient({
 Prosody classifies errors as transient (temporary, can be retried) or permanent (won't be resolved by retrying). By
 default, all errors are considered transient.
 
+The error classes and decorators apply to `onMessage`, `onExcise`, and `onTimer`.
+
 #### Using Decorators
 
 If you're using TypeScript or a JavaScript environment that supports decorators, you can use the `@permanent` decorator
 to classify exceptions that should not be retried:
 
 ```javascript
-import {permanent, ProsodyClient} from '@prosody-events/prosody';
+import { permanent, ProsodyClient } from "@prosody-events/prosody";
 
 class MyHandler {
-    @permanent(TypeError, AttributeError)
-    async onMessage(context, message, signal) {
-        // Your message handling logic here
-        // TypeError and AttributeError will be treated as permanent
-        // All other exceptions will be treated as transient (default behavior)
-    }
+  @permanent(TypeError, AttributeError)
+  async onMessage(context, message, signal) {
+    // Your message handling logic here
+    // TypeError and AttributeError will be treated as permanent
+    // All other exceptions will be treated as transient (default behavior)
+    return null;
+  }
+
+  async onExcise() {
+    return null;
+  }
+
+  async onTimer() {}
 }
 
-const client = new ProsodyClient(config);
+const client = await ProsodyClient.create(config);
 client.subscribe(new MyHandler());
 ```
 
@@ -617,23 +604,26 @@ client.subscribe(new MyHandler());
 If you're not using decorators, you can still classify errors as permanent by throwing a `PermanentError`:
 
 ```javascript
-import {PermanentError, ProsodyClient} from '@prosody-events/prosody';
+import { PermanentError, ProsodyClient } from "@prosody-events/prosody";
 
 const messageHandler = {
-    onMessage: async (context, message, signal) => {
-        try {
-            // Your message handling logic here
-        } catch (error) {
-            if (error instanceof TypeError || error instanceof AttributeError) {
-                throw new PermanentError(error.message);
-            }
-            // All other exceptions will be treated as transient (default behavior)
-            throw error;
-        }
+  onMessage: async (context, message, signal) => {
+    try {
+      // Your message handling logic here
+    } catch (error) {
+      if (error instanceof TypeError || error instanceof AttributeError) {
+        throw new PermanentError(error.message);
+      }
+      // All other exceptions will be treated as transient (default behavior)
+      throw error;
     }
+    return null;
+  },
+  onExcise: async () => null,
+  onTimer: async () => {},
 };
 
-const client = new ProsodyClient(config);
+const client = await ProsodyClient.create(config);
 client.subscribe(messageHandler);
 ```
 
@@ -644,6 +634,166 @@ client.subscribe(messageHandler);
 - Be cautious with permanent errors as they prevent retries and can result in data loss.
 - Consider system reliability and data consistency when classifying errors.
 
+## Keyed State
+
+Many stream transformations must reason across multiple events or timer firings. Windows, state machines, aggregates, and complex event processing all require state.
+
+A Kafka key identifies an entity, such as a customer or order. Keyed state gives each key independent working state for these transformations. With Cassandra, the state survives restarts and partition reassignment.
+
+Prosody selects the current message or timer key. It processes one event at a time for that key but can process other keys concurrently. By default, Prosody commits pending keyed-state changes only when the handler succeeds. If the handler returns an error, Prosody discards those changes.
+
+Give most collections a time to live (TTL). Set the TTL beyond the longest timer or workflow that uses the collection. Omit it when state must remain for inactive keys.
+
+### A counter for each key
+
+Declare each collection once. Register it on the client. In a handler, get the current key's state from the event context:
+
+```typescript
+const COUNT = value<number>("count", { ttlSeconds: 30 * 24 * 60 * 60 });
+
+const client = await ProsodyClient.create({
+  ...config,
+  stateCollections: [COUNT],
+});
+
+client.subscribe({
+  async onMessage(context) {
+    const count = context.state(COUNT);
+    await count.set(((await count.get()) ?? 0) + 1);
+    return null;
+  },
+  async onExcise(context) {
+    await context.state(COUNT).clear();
+    return null;
+  },
+  async onTimer() {},
+});
+```
+
+Each Kafka key now has an independent counter. A counter expires when that key has no update for 30 days.
+
+### Window activity into one notification
+
+This example sends the first event for a user immediately. It collects later events for five minutes and then sends one summary.
+
+The user ID is the Kafka key. Each user has an independent window.
+
+```typescript
+const WINDOW = value<boolean>("window", { ttlSeconds: 24 * 60 * 60 });
+const PENDING = messageDeque<Activity>("pending", {
+  capacity: 100,
+  ttlSeconds: 24 * 60 * 60,
+});
+
+const handler = {
+  async onMessage(context, message) {
+    const window = context.state(WINDOW);
+    const pending = context.state(PENDING);
+
+    if (await window.get()) {
+      await pending.push(message);
+      return null;
+    }
+
+    await notify(message.key, [message]);
+    await window.set(true);
+    await context.clearAndSchedule(new Date(Date.now() + 5 * 60_000));
+    return null;
+  },
+
+  async onTimer(context, timer) {
+    const pending = context.state(PENDING);
+    const batch: Message<Activity>[] = [];
+    for await (const message of pending.values()) batch.push(message);
+
+    if (batch.length > 0) await notify(timer.key, batch);
+    await pending.clear();
+    await context.state(WINDOW).clear();
+  },
+  async onExcise(context) {
+    await context.state(PENDING).clear();
+    await context.state(WINDOW).clear();
+    await context.clearScheduled();
+    return null;
+  },
+} satisfies EventHandler<Activity>;
+```
+
+See the complete, type-checked example for imports, types, client setup, and `notify`: [`examples/windowing.ts`](examples/windowing.ts).
+
+Why this works:
+
+- Register both definitions in `stateCollections` before you subscribe. Keyed state uses Cassandra unless `mock: true`.
+- Use `clearAndSchedule`, not `schedule`, so a retried event does not add another timer for the same key.
+- `capacity: 100` and the one-day TTL bound the saved backlog. Overflow drops the oldest message because this example only pushes.
+- A `messageDeque` requires the original Kafka messages during the window. Use `deque` when topic retention or compaction cannot provide them.
+- Prosody runs one handler at a time for each key, so a user's message and timer handlers cannot overlap.
+- A notification is outside the state transaction. A retry can send it again. Use a stable operation ID to reject duplicate notifications.
+
+### Collections and handles
+
+A definition sets a collection's durable name, kind, and options. Register it once. Pass it to `context.state` in a handler.
+
+Do not reuse a durable name for a different collection kind or payload type. Create handles inside the handler. Do not retain handles or iterators.
+
+| Collection         | JSON payload | Kafka message     | Main operations                                                      |
+| ------------------ | ------------ | ----------------- | -------------------------------------------------------------------- |
+| Value              | `value<T>`   | `messageValue<P>` | `get`, `set`, `clear`                                                |
+| Ordered string map | `map<V>`     | `messageMap<P>`   | `get`, `getMany`, `has`, `set`, `delete`, `entries`, `keys`, `clear` |
+| Deque              | `deque<T>`   | `messageDeque<P>` | `push`, `unshift`, `pop`, `shift`, `at`, `length`, `values`, `clear` |
+
+All operations are asynchronous. Map and deque scans are asynchronous iterables. A `for await` loop can stop early safely.
+
+Map keys are strings. `null` and `undefined` mean absence. Do not store these values. Use `clear()` or `delete()`.
+
+### When keyed-state changes become visible
+
+By default, retries do not see pending state from a failed attempt. Reads in a handler see its earlier keyed-state writes. Prosody commits pending changes when the event succeeds and discards them when the handler throws.
+
+This transaction applies only to keyed state. Some workflows need state changes before the handler ends, so each collection also provides explicit controls:
+
+- `readUncommitted: true` persists keyed-state changes before Prosody records the event as complete. If the process stops between these steps, Prosody can process the same event again. The retry sees state changes from the earlier attempt. You must make these keyed-state changes idempotent. Each retry must produce the same state.
+- `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.
+
+### 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.
+
+Use topics and event sourcing when a consumer must process each state change in order. Use published state for direct, read-only lookup of persisted keyed state. The caller does not need to consume the owner's topics or maintain a separate lookup store.
+
+Configure the subsystem name on each publisher. Enable publication on the collection definition. Register the definition on the Prosody client:
+
+```js
+const CURRENT_ORDER = value("current-order", { published: true });
+const owner = await ProsodyClient.create({
+  ...config,
+  subsystem: "checkout",
+  stateCollections: [CURRENT_ORDER],
+});
+
+// The handler uses the key from its current event.
+const currentOrder = context.state(CURRENT_ORDER);
+await currentOrder.set({ sku: "book" });
+```
+
+Read published state from a handler or other application code. The Prosody client does not need an active subscription.
+
+Use the subsystem and the same definition to open a reader:
+
+```js
+const orderReader = await client.state("checkout", CURRENT_ORDER);
+const currentOrder = await orderReader.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.
+
+Map and deque readers fetch data in chunks. They do not load the complete collection before iteration starts.
+
+The default cache window is five seconds. Set `readCache: { ttlMs }` to select a different window. Set `readCache: false` to bypass the cache.
+
+To stop publication, deploy the definition with `published: false`. Keep the definition registered during that deployment. Keep the subsystem configured during that deployment.
+
 ## OpenTelemetry Tracing
 
 Prosody supports OpenTelemetry tracing, allowing you to monitor and analyze the performance of your Kafka-based
@@ -666,19 +816,21 @@ npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-t
 To initialize tracing in your application:
 
 ```javascript
-const opentelemetry = require('@opentelemetry/api');
-const {NodeSDK} = require('@opentelemetry/sdk-node');
-const {OTLPTraceExporter} = require('@opentelemetry/exporter-trace-otlp-http');
+const opentelemetry = require("@opentelemetry/api");
+const { NodeSDK } = require("@opentelemetry/sdk-node");
+const {
+  OTLPTraceExporter,
+} = require("@opentelemetry/exporter-trace-otlp-http");
 
 const sdk = new NodeSDK({
-    traceExporter: new OTLPTraceExporter(),
-    serviceName: 'my-service-name',
+  traceExporter: new OTLPTraceExporter(),
+  serviceName: "my-service-name",
 });
 
 sdk.start();
 
 // Creates a tracer from the global tracer provider
-const tracer = opentelemetry.trace.getTracer('my-service-name');
+const tracer = opentelemetry.trace.getTracer("my-service-name");
 ```
 
 ### Setting OpenTelemetry Environment Variables
@@ -694,34 +846,39 @@ OTEL_SERVICE_NAME=my-service-name
 For more information on these and other OpenTelemetry environment variables, refer to
 the [OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration).
 
+Call `flushTelemetry()` to export pending telemetry. Call `shutdownTelemetry()` before the process exits.
+
 ### Using Tracing in Your Application
 
 After initializing tracing, you can define spans in your application, and they will be properly propagated through
 Kafka:
 
 ```javascript
-const {ProsodyClient} = require('@prosody-events/prosody');
-const opentelemetry = require('@opentelemetry/api');
+const { ProsodyClient } = require("@prosody-events/prosody");
+const opentelemetry = require("@opentelemetry/api");
 
-const tracer = opentelemetry.trace.getTracer('my-service-name');
+const tracer = opentelemetry.trace.getTracer("my-service-name");
 
-const client = new ProsodyClient({
-    groupId: "my-consumer-group",
-    subscribedTopics: "my-topic"
+const client = await ProsodyClient.create({
+  groupId: "my-consumer-group",
+  subscribedTopics: "my-topic",
 });
 
 const messageHandler = {
-    onMessage: async (context, message, signal) => {
-        const span = tracer.startSpan('process-message');
-        try {
-            // Process the received message
-            span.addEvent('message.received', {
-                'message.payload': JSON.stringify(message)
-            });
-        } finally {
-            span.end();
-        }
+  onMessage: async (context, message, signal) => {
+    const span = tracer.startSpan("process-message");
+    try {
+      // Process the received message
+      span.addEvent("message.received", {
+        "message.payload": JSON.stringify(message),
+      });
+    } finally {
+      span.end();
     }
+    return null;
+  },
+  onExcise: async () => null,
+  onTimer: async () => {},
 };
 
 client.subscribe(messageHandler);
@@ -776,55 +933,53 @@ Strategies for achieving idempotence:
 - Each message advances the state machine, allowing for idempotent processing and easy failure recovery.
 - Particularly useful for complex, distributed transactions across multiple services.
 
-### Proper Shutdown
+### Application shutdown
+
+A Prosody client runs a subscription, timers, and other services in the background. Before an application terminates, it must stop all client services. `unsubscribe()` stops only the active subscription.
 
-Always unsubscribe from topics before exiting your application:
+Call `shutdown()` when the application terminates. It stops all client services and rejects new operations. Call `unsubscribe()` only when the application will use the client again. You do not need to call `unsubscribe()` before `shutdown()`.
 
 ```javascript
-// Ensure proper shutdown
-await client.unsubscribe();
+await client.shutdown();
 ```
 
-This ensures:
-
-1. Completion and commitment of all in-flight work
-2. Quick rebalancing, allowing other consumers to take over partitions
-3. Proper release of resources
-
-Implement shutdown handling in your application:
+Handle application shutdown:
 
 ```javascript
-const {ProsodyClient} = require('@prosody-events/prosody');
+const { ProsodyClient } = require("@prosody-events/prosody");
 
 async function main() {
-    const client = new ProsodyClient({
-        groupId: "my-consumer-group",
-        subscribedTopics: "my-topic"
-    });
-
-    const messageHandler = {
-        onMessage: async (context, message, signal) => {
-            // Process the message
-        }
-    };
-
-    client.subscribe(messageHandler);
+  const client = await ProsodyClient.create({
+    groupId: "my-consumer-group",
+    subscribedTopics: "my-topic",
+  });
 
-    // Create a promise that resolves when shutdown is signaled
-    const shutdownPromise = new Promise((resolve) => {
-        const shutdown = async (signal) => {
-            console.log(`Received ${signal}. Initiating shutdown...`);
-            await client.unsubscribe();
-            resolve();
-        };
+  const messageHandler = {
+    onMessage: async (context, message, signal) => {
+      // Process the message.
+      return null;
+    },
+    onExcise: async () => null,
+    onTimer: async () => {},
+  };
+
+  client.subscribe(messageHandler);
+
+  // Resolve this promise after a shutdown signal.
+  const shutdownPromise = new Promise((resolve) => {
+    const shutdown = async (signal) => {
+      console.log(`Received ${signal}. Client shutdown starts.`);
+      await client.shutdown();
+      resolve();
+    };
 
-        process.on('SIGTERM', () => shutdown('SIGTERM'));
-        process.on('SIGINT', () => shutdown('SIGINT'));
-        process.on('SIGHUP', () => shutdown('SIGHUP'));
-    });
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGHUP", () => shutdown("SIGHUP"));
+  });
 
-    // Wait for shutdown to be signaled
-    await shutdownPromise;
+  // Wait for a shutdown signal.
+  await shutdownPromise;
 }
 
 main().catch(console.error);
@@ -852,19 +1007,26 @@ Example of using AbortSignal in message processing:
 
 ```javascript
 const messageHandler = {
-    onMessage: async (context, message, signal) => {
-        // Pass the signal to fetch calls
-        const response = await fetch('https://api.example.com', {signal});
-        const data = await response.json();
-
-        // Pass the signal to database operations
-        await db.query('INSERT INTO messages (payload) VALUES ($1)', [message.payload], {signal});
-
-        // Process the data...
-
-        // Send a message, passing the abort signal
-        await client.send('topic', 'key', {data: 'value'}, signal);
-    }
+  onMessage: async (context, message, signal) => {
+    // Pass the signal to fetch calls
+    const response = await fetch("https://api.example.com", { signal });
+    const data = await response.json();
+
+    // Pass the signal to database operations
+    await db.query(
+      "INSERT INTO messages (payload) VALUES ($1)",
+      [message.payload],
+      { signal },
+    );
+
+    // Process the data...
+
+    // Send a message, passing the abort signal
+    await client.send("topic", "key", { data: "value" }, signal);
+    return null;
+  },
+  onExcise: async () => null,
+  onTimer: async () => {},
 };
 ```
 
@@ -885,16 +1047,16 @@ Prosody uses an automated release process managed by GitHub Actions. Here's an o
 1. **Trigger**: The release process is triggered automatically on pushes to the `main` branch.
 
 2. **Release Please**: The process starts with the "Release Please" action, which:
-    - Analyzes commit messages since the last release.
-    - Creates or updates a release pull request with changelog updates and version bumps.
-    - When the PR is merged, it creates a GitHub release and a git tag.
+   - Analyzes commit messages since the last release.
+   - Creates or updates a release pull request with changelog updates and version bumps.
+   - When the PR is merged, it creates a GitHub release and a git tag.
 
 3. **Build Process**: If a new release is created, the following build jobs are triggered:
-    - Linux builds for x86_64 and aarch64 (glibc).
-    - Windows build for x64.
-    - macOS build for aarch64 (Apple Silicon).
+   - Linux builds for x86_64 and aarch64 (glibc).
+   - Windows build for x64.
+   - macOS build for aarch64 (Apple Silicon).
 
-4. **Testing**: The built binaries are tested on Linux (x86_64 and aarch64) with Node.js 20 and 22.
+4. **Testing**: The built binaries are tested on Linux (x86_64 and aarch64) with Node.js 24.
 
 5. **Artifact Upload**: Each build job uploads its artifacts (Node.js native addons) to GitHub Actions.
 
@@ -924,20 +1086,37 @@ your changes before merging to `main`.
 
 ### ProsodyClient
 
-- `constructor(config: Configuration)`: Initialize a new ProsodyClient with the given configuration.
-- `send(topic: string, key: string, payload: any, signal?: AbortSignal): Promise<void>`: Send a message to a specified
+- `ProsodyClient.create(config: Configuration): Promise<ProsodyClient>`: Initialize a client without blocking the Node.js event loop.
+- `send<P>(topic: string, key: string, payload: P & JsonCompatible<P>, signal?: AbortSignal): Promise<void>`: Send a statically checked JSON-compatible message to a specified
   topic.
-- `consumerState: ConsumerState`: Get the current state of the consumer.
+- `excise(topic: string, key: string, signal?: AbortSignal): Promise<void>`: Send an excise record for a key.
+- `request<R>(topic, key, payload: JsonValue, options): Promise<ReadonlyMap<string, Outcome<R>>>`: Return one outcome for each subsystem.
+- `requestExcise<R>(topic, key, options): Promise<ReadonlyMap<string, Outcome<R>>>`: Return one excise outcome for each subsystem.
+- `consumerState(): Promise<ConsumerState>`: Get the current state of the consumer.
+- `assignedPartitionCount(): Promise<number>`: Get the assigned partition count.
+- `isStalled(): Promise<boolean>`: Test whether the consumer is stalled.
 - `sourceSystem: string`: Get the source system identifier configured for the client.
-- `subscribe(eventHandler: EventHandler): void`: Subscribe to messages using the provided handler.
-- `unsubscribe(): Promise<void>`: Unsubscribe from messages and shut down the consumer.
+- `state<T>(subsystem: string, definition: ValueDefinition<T>): Promise<PublishedValue<T>>`: Open a read-only published value.
+- `state<V>(subsystem: string, definition: MapDefinition<V>): Promise<PublishedMap<V>>`: Open a read-only published map.
+- `state<T>(subsystem: string, definition: DequeDefinition<T>): Promise<PublishedDeque<T>>`: Open a read-only published deque.
+- `subscribe<P = JsonValue, R = JsonValue>(eventHandler: EventHandler<P, R>): Promise<void>`: Subscribe with typed payload and response values.
+- `unsubscribe(): Promise<void>`: Stop the consumer. You can subscribe again later.
+- `shutdown(): Promise<void>`: Stop all client services. Concurrent and repeated calls await the same operation.
+
+### AdminClient
+
+- `new AdminClient(bootstrapServers)`: Create an admin client for the specified Kafka servers.
+- `createTopic(name, partitions, replicationFactor)`: Create a Kafka topic.
+- `deleteTopic(name)`: Delete a Kafka topic.
 
 ### EventHandler
 
 Interface for handling messages and timers:
 
-- `onMessage?: (context: Context, message: Message, signal: AbortSignal) => Promise<void>`: Handles incoming messages
-- `onTimer?: (context: Context, timer: Timer, signal: AbortSignal) => Promise<void>`: Handles timer events
+- `EventHandler<P = JsonValue, R = JsonValue>` carries the payload and response types through each callback.
+- `onMessage: (context, message, signal) => MaybePromise<R & JsonCompatible<R>>`: Handle incoming messages.
+- `onExcise: (context, message, signal) => MaybePromise<R & JsonCompatible<R>>`: Handle excise records.
+- `onTimer: (context, timer, signal) => MaybePromise<void>`: Handle timer events.
 
 ### Message
 
@@ -948,11 +1127,21 @@ Represents a Kafka message with the following properties:
 - `offset: bigint`: The message offset within the partition.
 - `timestamp: Date`: The timestamp when the message was created or sent.
 - `key: string`: The message key.
-- `payload: any`: The message payload as a JSON-serializable value.
+- `payload: P`: The statically typed message payload.
+
+`Message` takes an optional payload type parameter, `Message<P>`, used by handlers and message-backed state collections to type `payload`. Unparameterized `Message` is `Message<JsonValue>`, preserving useful JSON safety without requiring an application-specific payload type.
+
+`JsonValue` describes arbitrary JSON data. `JsonCompatible<T>` checks a known application type recursively.
+
+Ordinary interfaces work with `send()`. TypeScript rejects functions, `undefined`, `Date`, symbols, bigints, and invalid nested fields before serialization.
+
+### ExciseMessage
+
+An `ExciseMessage` has `topic`, `partition`, `offset`, `timestamp`, and `key` properties. It has no `payload` property.
 
 ### Context
 
-Represents the context of message processing:
+Represents the current event context:
 
 - `onCancel(): Promise<void>`: A method that resolves when the context is cancelled.
 - `shouldCancel: boolean`: A property indicating whether the context has been cancelled.
@@ -965,6 +1154,10 @@ Timer scheduling methods:
 - `clearScheduled(): Promise<void>`: Removes all scheduled timers
 - `scheduled(): Promise<Date[]>`: Returns an array of all scheduled timer times
 
+Keyed-state binding:
+
+- `state(definition): ValueState<T> | MapState<V> | DequeState<T>`: Bind a registered collection for the current attempt. Message definitions return handles that contain `Message<P>`. An unregistered or mismatched definition throws `PermanentStateError`. See [Keyed State](#keyed-state-2).
+
 ### Timer
 
 Represents a timer that has fired, provided to the `onTimer` method:
@@ -972,6 +1165,117 @@ Represents a timer that has fired, provided to the `onTimer` method:
 - `key: string`: The entity key identifying what this timer belongs to
 - `time: Date`: The time when this timer was scheduled to fire
 
+### Requests
+
+- `RequestOptions`: Contains `subsystems`, `timeoutMs`, and an optional `signal`.
+- `Outcome<T>`: A `Success<T>` or `Failure` result for one subsystem.
+- `Success<T>`: Contains `ok: true` and `value: T`.
+- `Failure`: Contains `ok: false` and a `ResponseError`.
+- `ResponseError`: A handler, timeout, format-mismatch, or malformed-response error.
+
+### Configuration types
+
+- `Configuration`: Contains the client settings. See [Configuration](CONFIGURATION.md).
+- `ConsumerState`: Identifies the consumer lifecycle state.
+- `Mode`: Selects the client processing mode.
+- `ReadCacheConfiguration`: Configures the default published-state cache.
+- `ReadCacheOptions`: Overrides the cache for one published collection.
+
+### Payload types
+
+- `JsonPrimitive`: A JSON null, boolean, number, or string.
+- `JsonValue`: Any recursively JSON-compatible value.
+- `JsonCompatible<T>`: Rejects non-JSON members in a known application type.
+- `MaybePromise<T>`: A value or a promise-like value.
+
+### Keyed State
+
+Definition constructors (each returns a frozen definition object used both in `Configuration.stateCollections` and with `context.state()`):
+
+- `value<T = JsonValue>(name: string, options?: PublishedStateDefinitionOptions): ValueDefinition<T>`
+- `map<V = JsonValue>(name: string, options?: MapDefinitionOptions): MapDefinition<V>`
+- `deque<T = JsonValue>(name: string, options?: DequeDefinitionOptions): DequeDefinition<T>`
+- `messageValue<P = JsonValue>(name: string, options?: StateDefinitionOptions): MessageValueDefinition<P>`
+- `messageMap<P = JsonValue>(name: string, options?: MessageMapDefinitionOptions): MessageMapDefinition<P>`
+- `messageDeque<P = JsonValue>(name: string, options?: MessageDequeDefinitionOptions): MessageDequeDefinition<P>`
+
+`StateDefinitionOptions`: `{ ttlSeconds?: number; readUncommitted?: boolean }`. `PublishedStateDefinitionOptions` adds `{ published?: boolean; readCache?: { ttlMs: number } | false }` for JSON definitions. Map and deque option types add `keysetLimit` and `capacity`, respectively; their message equivalents omit publication options.
+
+`ValueState<T>`:
+
+- `get(): Promise<T | null>`
+- `set(value: T): Promise<void>`
+- `clear(): Promise<void>`
+- `commit(): Promise<void>`
+- `rollback(): Promise<void>`
+
+`MapState<V>` (keys are `string`):
+
+- `get(key: string): Promise<V | null>`
+- `getMany(keys: readonly string[]): Promise<(V | null)[]>`
+- `has(key: string): Promise<boolean>`
+- `set(key: string, value: V): Promise<void>`
+- `delete(key: string): Promise<void>`
+- `clear(): Promise<void>`
+- `entries(direction?: ScanDirection): AsyncIterableIterator<[string, V]>`
+- `keys(direction?: ScanDirection): AsyncIterableIterator<string>`
+- `values(direction?: ScanDirection): AsyncIterableIterator<V>`
+- `[Symbol.asyncIterator](): AsyncIterableIterator<[string, V]>`
+- `commit(): Promise<void>`
+- `rollback(): Promise<void>`
+
+`DequeState<T>`:
+
+- `push(item: T): Promise<void>`
+- `unshift(item: T): Promise<void>`
+- `pop(): Promise<T | null>`
+- `shift(): Promise<T | null>`
+- `length(): Promise<number>`
+- `isEmpty(): Promise<boolean>`
+- `clear(): Promise<void>`
+- `at(index: number): Promise<T | null>`
+- `values(direction?: ScanDirection): AsyncIterableIterator<T>`
+- `[Symbol.asyncIterator](): AsyncIterableIterator<T>`
+- `commit(): Promise<void>`
+- `rollback(): Promise<void>`
+
+`ScanDirection`: `"forward" | "backward"`.
+
+Published readers take the user key as their first argument. `PublishedValue<T>` provides `get`. `PublishedMap<V>` provides `get`, `getMany`, `has`, `entries`, `keys`, and `values`. `PublishedDeque<T>` provides `at`, `length`, `isEmpty`, and `values`. The scan methods return `AsyncIterableIterator` directly.
+
+`StateCollectionConfig` defines one `stateCollections` entry. It contains `name`, `kind`, `payload`, and the applicable collection options. Use a definition constructor to create this value.
+
+JSON definitions also accept `readCache`. This option applies when the definition opens published state. It is not part of `StateCollectionConfig`.
+
+The public definition types are `ValueDefinition<T>`, `MapDefinition<V>`, `DequeDefinition<T>`, `MessageValueDefinition<P>`, `MessageMapDefinition<P>`, and `MessageDequeDefinition<P>`.
+
+All definitions expose `name`, `kind`, `payload`, `ttlSeconds`, and `readUncommitted`. JSON definitions also expose `published` and `readCache`. Map definitions expose `keysetLimit`. Deque definitions expose `capacity`.
+
+Errors:
+
+- `TransientStateError extends TransientError`: Reports a keyed-state error that Prosody can retry.
+- `PermanentStateError extends PermanentError`: Reports a keyed-state error that another attempt cannot resolve.
+- `isStateError(error: unknown): error is PermanentStateError | TransientStateError`: type-guard narrowing an error to either state error class.
+
+Handler error types and decorators:
+
+- `EventHandlerError`: Base class with an abstract `isPermanent` property.
+- `TransientError`: Has `isPermanent: false` and marks an error as retriable.
+- `PermanentError`: Has `isPermanent: true` and marks an error as final.
+- `transient(...errorTypes)`: Creates a transient-error decorator.
+- `permanent(...errorTypes)`: Creates a permanent-error decorator.
+
+### Logging and telemetry
+
+- `Logger`: Provides `error`, `warn`, `info`, `debug`, and `trace` methods.
+- `initialize()`: Prepare the logging and tracing system during application startup.
+- `loggerIsSet()`: Test whether the application configured a logger.
+- `setLogger(logger)`: Replaces the logger.
+- `setLoggerIfUnset(logger)`: Sets the logger only when no logger exists.
+- `getCurrentLogger()`: Returns the current JavaScript logger.
+- `flushTelemetry()`: Exports pending telemetry.
+- `shutdownTelemetry()`: Exports pending telemetry and stops its providers.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.