kafka-crab-js 4.0.0-beta.3 → 4.0.0

package/README.md

@@ -1,16 +1,57 @@
 # Kafka Crab JS
 
-A high-performance Kafka client for Node.js and TypeScript, implemented with Rust, NAPI-RS, librdkafka, and a small
-JavaScript API layer.
+Kafka Crab JS is a native Kafka client for Node.js and TypeScript. It uses Rust, NAPI-RS, and librdkafka to reduce
+JavaScript heap pressure, expose Kafka's mature native client behavior, and push high-throughput consumer workloads
+through a small TypeScript-friendly API.
 
-[![npm version](https://img.shields.io/npm/v/kafka-crab-js.svg)](https://www.npmjs.com/package/kafka-crab-js)
+[![npm beta version](https://img.shields.io/badge/npm%20beta-v4.0.0--beta.3-blue.svg)](https://www.npmjs.com/package/kafka-crab-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## Version 4
+
+`kafka-crab-js` v4 is the current beta line. It focuses on high-throughput consumers, lower JavaScript heap pressure,
+and a cleaner monorepo release model under [`flash-tecnologia/crab-js`](https://github.com/flash-tecnologia/crab-js).
+
+The main v4 additions are:
+
+- Native Web Stream consumers through `client.createWebStreamConsumer()`, with explicit `serial` and `batch` modes.
+- Direct batch consumption through `consumer.recvBatch(size, timeoutMs)` for workers that can process chunks.
+- Compact native batch streaming internally, reducing native-to-JavaScript marshalling overhead before expanding to the
+  public `Message[]` API.
+- Serial Web Stream prefetching, so message-by-message code still benefits from small native batches.
+- Diagnostics-channel events in the core package, with OpenTelemetry tracing and metrics moved to the optional
+  `kafka-crab-js-otel` package.
+- Updated TypeScript exports where runtime enum-like values are now string literal types, avoiding missing runtime
+  exports in ESM/CommonJS consumers.
+
+For production adoption, treat v4 as a beta release: validate it with your broker settings, payload sizes, partition
+count, commit strategy, and shutdown path before replacing an existing Kafka client.
+
+## Why Kafka Crab JS?
+
+KafkaJS is a strong default for many Node.js services. Kafka Crab JS is for the cases where Kafka throughput, memory
+pressure, native batching, or librdkafka behavior start to matter.
+
+| Need                                | What Kafka Crab JS Provides                                                              |
+| ----------------------------------- | ---------------------------------------------------------------------------------------- |
+| Higher consumer throughput          | Native batch receive paths and Web Stream batch consumers.                               |
+| Lower JavaScript heap pressure      | Message fetch and Kafka protocol work happen in Rust/librdkafka before crossing into JS. |
+| Predictable Kafka offset handling   | `commitMessage()` commits `message.offset + 1`, the value Kafka expects.                 |
+| Production Kafka tuning             | Advanced librdkafka settings are passed through with their original names.               |
+| Node.js ecosystem integration       | Direct APIs, Node.js `Readable` streams, native Web Streams, and CommonJS/ESM exports.   |
+| Observability without core coupling | Diagnostics-channel events power the optional `kafka-crab-js-otel` package.              |
+
+In the local isolated consumer benchmark snapshot, `kafka-crab-js v4 (stream, batch)` reached about
+`1.17M messages/sec`, ahead of the measured `@platformatic/kafka` and KafkaJS batch scenarios, while using lower RSS
+delta and peak heap than both. Treat benchmark numbers as workload-specific; the full methodology and memory/GC
+breakdown are documented in [BENCHMARKS.md](../../BENCHMARKS.md) and [Performance Benchmarks](#performance-benchmarks).
+
 ## Highlights
 
 - Native librdkafka client exposed through a TypeScript-friendly API.
-- Producer, direct consumer, Node.js `Readable` stream, and native Web Stream consumer APIs.
+- Producer, direct consumer, Node.js `Readable` stream, and v4 native Web Stream consumer APIs.
 - High-throughput batch receive APIs for workloads that can process more than one message at a time.
+- Compact batch streaming and serial prefetching to reduce native boundary crossings.
 - Manual commit helpers that commit `message.offset + 1` correctly.
 - Optional diagnostics-channel instrumentation for OpenTelemetry through `kafka-crab-js-otel`.
 - Advanced librdkafka settings are forwarded through `configuration` without forcing a custom allowlist.
@@ -23,19 +64,23 @@ JavaScript API layer.
 
 ## Table Of Contents
 
-1. [Installation](#installation)
-2. [Quick Start](#quick-start)
-3. [Choosing A Consumer API](#choosing-a-consumer-api)
-4. [Producer API](#producer-api)
-5. [Consumer API](#consumer-api)
-6. [Stream Consumers](#stream-consumers)
-7. [Configuration](#configuration)
-8. [OpenTelemetry](#opentelemetry)
-9. [Performance Benchmarks](#performance-benchmarks)
-10. [Migration Notes](#migration-notes)
-11. [Troubleshooting](#troubleshooting)
-12. [Development](#development)
-13. [License](#license)
+1. [Version 4](#version-4)
+2. [Installation](#installation)
+3. [Module Usage](#module-usage)
+4. [Quick Start](#quick-start)
+5. [Message Model](#message-model)
+6. [Choosing A Consumer API](#choosing-a-consumer-api)
+7. [Producer API](#producer-api)
+8. [Consumer API](#consumer-api)
+9. [Stream Consumers](#stream-consumers)
+10. [Batching, Backpressure, And Tuning](#batching-backpressure-and-tuning)
+11. [Configuration](#configuration)
+12. [OpenTelemetry](#opentelemetry)
+13. [Performance Benchmarks](#performance-benchmarks)
+14. [Migration Notes](#migration-notes)
+15. [Troubleshooting](#troubleshooting)
+16. [Development](#development)
+17. [License](#license)
 
 ## Installation
 
@@ -51,6 +96,31 @@ pnpm add kafka-crab-js
 yarn add kafka-crab-js
 ```
 
+## Module Usage
+
+The package publishes both ESM and CommonJS entry points:
+
+```ts
+import { KafkaClient } from 'kafka-crab-js'
+import type { Message, ProducerRecord } from 'kafka-crab-js'
+```
+
+```js
+const { KafkaClient } = require('kafka-crab-js')
+```
+
+The public TypeScript types are generated from the native NAPI contract and the JavaScript wrapper. Runtime enum-like
+values such as commit modes and security protocols are string literals, not runtime objects:
+
+```ts
+await consumer.commitMessage(message, 'Sync')
+
+const client = new KafkaClient({
+  brokers: 'localhost:9092',
+  securityProtocol: 'Plaintext',
+})
+```
+
 ## Quick Start
 
 ### Produce Messages
@@ -150,6 +220,45 @@ try {
 }
 ```
 
+## Message Model
+
+Messages use `Buffer` values because the Kafka protocol treats keys, payloads, and headers as bytes. Decode them at the
+edge of your application instead of assuming text:
+
+```ts
+import type { Message, MessageProducer, RecordMetadata } from 'kafka-crab-js'
+
+const outgoing: MessageProducer = {
+  key: Buffer.from('order-123'),
+  payload: Buffer.from(JSON.stringify({ id: 'order-123' })),
+  headers: {
+    'content-type': Buffer.from('application/json'),
+    source: Buffer.from('orders-api'),
+  },
+}
+
+function decodeJsonMessage(message: Message) {
+  return JSON.parse(message.payload.toString('utf8')) as unknown
+}
+
+function logDelivery(records: RecordMetadata[]) {
+  for (const record of records) {
+    console.log(`${record.topic}[${record.partition}]@${record.offset}`)
+  }
+}
+```
+
+`Message` values contain the consumed Kafka offset. When committing manually, commit the next offset. Prefer
+`commitMessage()` unless you intentionally need to calculate offsets yourself:
+
+```ts
+await consumer.commitMessage(message, 'Sync')
+await consumer.commit(message.topic, message.partition, message.offset + 1, 'Async')
+```
+
+Keys are optional. An omitted key keeps Kafka producer partitioning semantics for keyless records. An empty
+`Buffer.alloc(0)` is still a present key.
+
 ## Choosing A Consumer API
 
 | API                                | Emits                                                        | Best For                                               |
@@ -168,6 +277,13 @@ Two details matter for choosing correctly:
 - `createWebStreamConsumer()` returns a discriminated object. In serial mode it emits `Message`; in batch mode it emits
   `Message[]`. Use this API when your code can process whole batches directly.
 
+Recommended starting points:
+
+- Use `consumer.recv()` for straightforward workers where one handler processes one message and then commits.
+- Use `consumer.recvBatch()` when the handler can process chunks, flush work in groups, or commit after a batch.
+- Use `createStreamConsumer()` when existing code already expects a Node.js `Readable`.
+- Use `createWebStreamConsumer()` for new v4 stream code, especially when you can keep batch chunks intact.
+
 ## Producer API
 
 Create a producer from a `KafkaClient`:
@@ -212,6 +328,51 @@ console.log(records)
 
 `producer.inFlightCount()` returns the number of messages sent but not yet acknowledged.
 
+### Delivery Semantics
+
+`send()` writes records to librdkafka and, with the default `autoFlush: true`, waits for delivery results before
+resolving. Delivery metadata can still contain a per-record `error`, so production code should inspect it when failed
+records must be retried or reported:
+
+```ts
+const records = await producer.send({
+  topic: 'orders',
+  messages: [{ payload: Buffer.from('created') }],
+})
+
+for (const record of records) {
+  if (record.error) {
+    throw new Error(`Kafka delivery failed: ${record.error.message}`)
+  }
+}
+```
+
+With `autoFlush: false`, `send()` returns an empty array and leaves delivery confirmation to the next `flush()` call.
+This can improve throughput for bursty producers, but shutdown code must flush before the process exits:
+
+```ts
+import type { RecordMetadata } from 'kafka-crab-js'
+
+const producer = client.createProducer({ autoFlush: false })
+
+function assertAllDelivered(records: RecordMetadata[]) {
+  for (const record of records) {
+    if (record.error) {
+      throw new Error(`Kafka delivery failed: ${record.error.message}`)
+    }
+  }
+}
+
+try {
+  await producer.send({ topic: 'orders', messages })
+  const records = await producer.flush()
+  assertAllDelivered(records)
+} finally {
+  const remaining = await producer.flush()
+  assertAllDelivered(remaining)
+}
+```
+
 ## Consumer API
 
 ### Subscribe
@@ -291,6 +452,25 @@ Commit modes are string literal values:
 type CommitMode = 'Sync' | 'Async'
 ```
 
+For at-least-once processing, disable auto commit, process the message successfully, then commit. If processing fails
+before the commit, Kafka can redeliver that message after restart or rebalance:
+
+```ts
+const consumer = client.createConsumer({
+  groupId: 'orders-worker',
+  enableAutoCommit: false,
+})
+
+const message = await consumer.recv()
+if (message) {
+  await processOrder(message)
+  await consumer.commitMessage(message, 'Sync')
+}
+```
+
+`'Sync'` waits for the broker commit response. `'Async'` schedules the commit through librdkafka and returns sooner,
+which can be useful in high-throughput workers that tolerate the usual async commit tradeoff.
+
 ### Pause, Resume, Seek, And Assignment
 
 ```ts
@@ -317,6 +497,9 @@ consumer.onEvents((error, event) => {
 })
 ```
 
+Event names are currently `PreRebalance`, `PostRebalance`, and `CommitCallback`. The payload includes the topic-partition
+list associated with the event and may include an `error` string for commit or rebalance failures.
+
 ### Cleanup
 
 Always disconnect direct consumers:
@@ -436,6 +619,46 @@ if (webConsumer.mode === 'batch') {
 }
 ```
 
+## Batching, Backpressure, And Tuning
+
+The main throughput lever is how many messages cross the native-to-JavaScript boundary per call.
+
+| Knob                    | Applies To                                      | Effect                                                                 |
+| ----------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
+| `recvBatch(size, ms)`   | Direct consumer                                 | Pulls up to `size` messages, waiting up to `ms` for data.              |
+| `batchSize`             | Node stream and Web Stream batch modes          | Sets the maximum native batch size used by the stream.                 |
+| `batchTimeout`          | Node stream and Web Stream batch modes          | Bounds how long a partially filled batch waits before being emitted.   |
+| `serialPrefetchSize`    | `createWebStreamConsumer()` serial mode         | Pulls small native batches and flattens them into individual messages. |
+| `serialPrefetchTimeout` | `createWebStreamConsumer()` serial mode         | Timeout for the serial-mode prefetch batch.                            |
+| `streamOptions`         | `createStreamConsumer()` Node.js `Readable` API | Lets Node stream `highWaterMark` participate in backpressure.          |
+
+Use larger batches when throughput matters and your handler can process arrays efficiently. Use smaller batches and
+shorter timeouts when tail latency matters more than total throughput. Very large batches can increase RSS because more
+payloads, keys, headers, and metadata must be retained at once.
+
+The v4 Web Stream serial path defaults to `serialPrefetchSize: 64` and `serialPrefetchTimeout: 1`. This keeps the public
+serial API message-by-message while reducing native boundary crossings. Batch mode defaults `batchTimeout` to `1000`
+milliseconds when it is omitted.
+
+For broker fetch tuning, pass librdkafka settings through `configuration`. Keep these values aligned with your expected
+message size:
+
+```ts
+const consumer = client.createConsumer({
+  groupId: 'orders-worker',
+  configuration: {
+    'fetch.min.bytes': 1,
+    'fetch.wait.max.ms': 10,
+    'fetch.max.bytes': 1_048_576,
+    'max.partition.fetch.bytes': 1_048_576,
+    'message.max.bytes': 1_000_000,
+  },
+})
+```
+
+`fetch.max.bytes` must be greater than or equal to `message.max.bytes`. If this invariant is broken, librdkafka rejects
+the consumer configuration before the benchmark or application starts.
+
 ## Configuration
 
 ### KafkaClient
@@ -459,11 +682,38 @@ const client = new KafkaClient({
 | `brokers`             | `string`                                               | required  | Comma-separated broker list, for example `localhost:9092,localhost:9093`. |
 | `clientId`            | `string`                                               | `rdkafka` | Client identifier sent to Kafka.                                          |
 | `securityProtocol`    | `'Plaintext' \| 'Ssl' \| 'SaslPlaintext' \| 'SaslSsl'` |           | Security protocol.                                                        |
-| `logLevel`            | `string`                                               |           | librdkafka log level.                                                     |
-| `brokerAddressFamily` | `string`                                               |           | Address family hint such as `v4`.                                         |
+| `logLevel`            | `string`                                               | `error`   | librdkafka log level.                                                     |
+| `brokerAddressFamily` | `string`                                               | `v4`      | Address family hint such as `v4` or `any`.                                |
 | `diagnostics`         | `boolean`                                              | `true`    | Enables diagnostic-channel events used by `kafka-crab-js-otel`.           |
 | `configuration`       | `Record<string, any>`                                  |           | Additional librdkafka client settings.                                    |
 
+`configuration` is passed through to librdkafka after values are converted to strings. Use the original librdkafka
+property names, for example `sasl.mechanism`, `queued.min.messages`, or `fetch.wait.max.ms`.
+
+Common connection examples:
+
+```ts
+const localClient = new KafkaClient({
+  brokers: 'localhost:9092',
+  clientId: 'orders-local',
+  securityProtocol: 'Plaintext',
+  brokerAddressFamily: 'v4',
+})
+```
+
+```ts
+const saslClient = new KafkaClient({
+  brokers: process.env.KAFKA_BROKERS!,
+  clientId: 'orders-worker',
+  securityProtocol: 'SaslSsl',
+  configuration: {
+    'sasl.mechanism': 'PLAIN',
+    'sasl.username': process.env.KAFKA_USERNAME!,
+    'sasl.password': process.env.KAFKA_PASSWORD!,
+  },
+})
+```
+
 ### ConsumerConfiguration
 
 ```ts
@@ -486,6 +736,22 @@ const consumer = client.createConsumer({
 | `fetchMetadataTimeout` | `number`              | Metadata fetch timeout in milliseconds.    |
 | `configuration`        | `Record<string, any>` | Additional librdkafka consumer settings.   |
 
+`enableAutoCommit` is a convenience option that sets librdkafka `enable.auto.commit`. You can also pass
+`'enable.auto.commit'` in `configuration`, but using both with different values makes the intent hard to read.
+
+For new services that need explicit processing guarantees, start with manual commits:
+
+```ts
+const consumer = client.createConsumer({
+  groupId: 'orders-worker',
+  enableAutoCommit: false,
+  configuration: {
+    'auto.offset.reset': 'earliest',
+    'enable.partition.eof': false,
+  },
+})
+```
+
 ### ProducerConfiguration
 
 ```ts
@@ -504,6 +770,22 @@ const producer = client.createProducer({
 | `queueTimeout`  | `number`              | Queue timeout in milliseconds.                          |
 | `configuration` | `Record<string, any>` | Additional librdkafka producer settings.                |
 
+Producer settings are workload-specific. A low-latency producer might prefer smaller buffering windows, while a
+throughput-oriented producer can allow librdkafka to coalesce more work:
+
+```ts
+const producer = client.createProducer({
+  autoFlush: false,
+  queueTimeout: 5000,
+  configuration: {
+    acks: 'all',
+    'compression.type': 'lz4',
+    'queue.buffering.max.ms': 10,
+    'queue.buffering.max.messages': 100000,
+  },
+})
+```
+
 ### TopicPartitionConfig
 
 | Option            | Type                | Description                                      |
@@ -590,23 +872,26 @@ if (message) {
 }
 ```
 
-See the [OpenTelemetry package README](../otel/README.md) for full tracing and metrics setup.
+See the [OpenTelemetry package README](../kafka-crab-js-otel/README.md) for full tracing and metrics setup.
 
 ## Performance Benchmarks
 
-The repository includes a benchmark suite that compares `kafka-crab-js` with KafkaJS and `@platformatic/kafka`.
+The repository includes a benchmark suite that compares `kafka-crab-js` with KafkaJS and `@platformatic/kafka`. The
+latest captured run in [BENCHMARKS.md](../../BENCHMARKS.md) was recorded on May 25, 2026 on a MacBook Pro with Apple M1,
+Node.js `v24.16.0`, and a local three-broker `apache/kafka:4.0.0` cluster.
 
 From the repository root:
 
 ```bash
-cd packages/benchmark
+podman compose up -d
+
+cd benchmarks/kafka
 
 # Set up benchmark data. Requires Kafka running locally.
-vp install
-vp run setup:consumer
+KAFKA_BROKERS=127.0.0.1:9092,127.0.0.1:9093,127.0.0.1:9094 vp run setup:consumer
 
 # Run the default isolated-process memory benchmark.
-vp run benchmark
+KAFKA_BROKERS=127.0.0.1:9092,127.0.0.1:9093,127.0.0.1:9094 vp run benchmark
 ```
 
 The default benchmark runs one child Node.js process per selected scenario. This avoids carrying V8 heap pages, native
@@ -617,11 +902,11 @@ allocator arenas, sockets, librdkafka state, and Kafka metadata from one client
 The captured run below is equivalent to:
 
 ```bash
-cd packages/benchmark
-BENCHMARK_BATCH_SIZE=300000 BENCHMARK_BATCH_TIMEOUT_MS=2 vp run benchmark
+cd benchmarks/kafka
+KAFKA_BROKERS=127.0.0.1:9092,127.0.0.1:9093,127.0.0.1:9094 vp run benchmark
 ```
 
-Batch scenarios were normalized to the comparable effective batch size of `16384`.
+The run uses the default isolated-process lifecycle-memory benchmark mode.
 
 ![Consumer benchmark snapshot](./assets/consumer-benchmark-snapshot.svg)
 
@@ -629,62 +914,71 @@ Batch scenarios were normalized to the comparable effective batch size of `16384
 
 | Rank | Scenario                            |                Result | Relative |
 | ---: | ----------------------------------- | --------------------: | -------: |
-|    1 | `kafka-crab-js v4 (stream, batch)`  | `1,089,284.97 op/sec` | `100.0%` |
-|    2 | `@platformatic/kafka`               |   `732,207.27 op/sec` |  `67.2%` |
-|    3 | `KafkaJS (eachBatch)`               |   `676,576.98 op/sec` |  `62.1%` |
-|    4 | `kafka-crab-js v4 (stream, serial)` |   `544,658.33 op/sec` |  `50.0%` |
-|    5 | `KafkaJS (eachMessage, concurrent)` |   `509,082.43 op/sec` |  `46.7%` |
-|    6 | `KafkaJS (eachMessage)`             |   `505,815.57 op/sec` |  `46.4%` |
+|    1 | `kafka-crab-js v4 (stream, batch)`  | `1,167,396.71 op/sec` | `100.0%` |
+|    2 | `@platformatic/kafka`               |   `653,355.35 op/sec` |  `56.0%` |
+|    3 | `kafka-crab-js v4 (stream, serial)` |   `558,968.71 op/sec` |  `47.9%` |
+|    4 | `KafkaJS (eachBatch)`               |   `478,411.67 op/sec` |  `41.0%` |
+|    5 | `KafkaJS (eachMessage)`             |   `431,519.93 op/sec` |  `37.0%` |
+|    6 | `KafkaJS (eachMessage, concurrent)` |   `427,265.29 op/sec` |  `36.6%` |
 
-`kafka-crab-js v4 (stream, batch)` is the fastest scenario in this run. It is about `49%` faster than
-`@platformatic/kafka` and about `61%` faster than `KafkaJS (eachBatch)`. Its tolerance is higher than the other top
-rows (`+/- 9.15%`), so the exact gap should be treated as a benchmark snapshot rather than a universal constant.
+`kafka-crab-js v4 (stream, batch)` is the fastest scenario in this run. It is about `78.7%` faster than
+`@platformatic/kafka` and about `144.0%` faster than `KafkaJS (eachBatch)`. Its tolerance was `+/- 4.40%`, so the exact
+gap should still be treated as a benchmark snapshot rather than a universal constant.
 
 For message-by-message consumption, `kafka-crab-js v4 (stream, serial)` is close to KafkaJS throughput while using much
-less lifecycle memory. In this run it is about `7.7%` faster than `KafkaJS (eachMessage)` and about `7.0%` faster than
-the concurrent KafkaJS `eachMessage` scenario.
+less lifecycle memory. In this run it is about `29.5%` faster than `KafkaJS (eachMessage)` and about `30.8%` faster
+than the concurrent KafkaJS `eachMessage` scenario.
 
 #### Memory And GC
 
-| Scenario                            |   RSS delta |  Peak heap |    GC time | GC share | Notes                                           |
-| ----------------------------------- | ----------: | ---------: | ---------: | -------: | ----------------------------------------------- |
-| `kafka-crab-js v4 (stream, serial)` |  `72.3 MiB` | `11.7 MiB` | `36.75 ms` |  `4.00%` | Best memory efficiency.                         |
-| `kafka-crab-js v4 (stream, batch)`  | `167.0 MiB` | `35.9 MiB` | `30.60 ms` |  `6.67%` | Best throughput and lowest GC time.             |
-| `KafkaJS (eachBatch)`               | `193.1 MiB` | `70.0 MiB` | `63.03 ms` |  `8.53%` | Strong batch baseline.                          |
-| `@platformatic/kafka`               | `217.6 MiB` | `93.7 MiB` | `73.62 ms` | `10.78%` | Fastest non-crab competitor.                    |
-| `KafkaJS (eachMessage)`             | `181.5 MiB` | `77.0 MiB` | `79.11 ms` |  `8.00%` | Similar throughput to v4 serial, higher memory. |
-| `KafkaJS (eachMessage, concurrent)` | `188.2 MiB` | `75.6 MiB` | `77.17 ms` |  `7.86%` | Concurrency did not improve this workload.      |
+| Scenario                            |   RSS delta |  Peak heap |    GC time | GC share | Notes                                      |
+| ----------------------------------- | ----------: | ---------: | ---------: | -------: | ------------------------------------------ |
+| `kafka-crab-js v4 (stream, serial)` |  `64.7 MiB` | `14.6 MiB` | `30.46 ms` |  `3.41%` | Lowest lifecycle RSS and heap.             |
+| `kafka-crab-js v4 (stream, batch)`  | `106.0 MiB` | `29.5 MiB` | `21.69 ms` |  `5.06%` | Best throughput, efficiency, and GC time.  |
+| `KafkaJS (eachMessage, concurrent)` | `178.3 MiB` | `72.2 MiB` | `83.77 ms` |  `7.16%` | Concurrency did not improve this workload. |
+| `KafkaJS (eachMessage)`             | `186.3 MiB` | `91.6 MiB` | `90.15 ms` |  `7.78%` | Highest peak heap and max GC pause.        |
+| `KafkaJS (eachBatch)`               | `193.4 MiB` | `83.8 MiB` | `63.05 ms` |  `6.03%` | KafkaJS batch baseline.                    |
+| `@platformatic/kafka`               | `216.0 MiB` | `87.4 MiB` | `74.27 ms` |  `9.71%` | Fastest non-crab competitor.               |
 
 Lifecycle memory includes module loading, client creation, subscription, consumption, cleanup, and retained RSS after
 cleanup. GC metrics use the narrower first-to-last-message window used for throughput.
 
-The most important memory result is efficiency, not just raw RSS. `kafka-crab-js v4 (stream, serial)` delivered
-`7529 op/sec/MiB`, the best score in the run. `kafka-crab-js v4 (stream, batch)` delivered `6521 op/sec/MiB`, ahead of
-`KafkaJS (eachBatch)` at `3504 op/sec/MiB` and `@platformatic/kafka` at `3365 op/sec/MiB`.
+The most important memory result is efficiency, not just raw RSS. `kafka-crab-js v4 (stream, batch)` delivered
+`11016 op/sec/MiB`, the best score in the run. `kafka-crab-js v4 (stream, serial)` delivered `8635 op/sec/MiB`, ahead
+of `@platformatic/kafka` at `3025 op/sec/MiB` and `KafkaJS (eachBatch)` at `2474 op/sec/MiB`.
 
 ### Benchmark Interpretation
 
-- Use `kafka-crab-js v4 (stream, batch)` when raw throughput is the priority.
-- Use `kafka-crab-js v4 (stream, serial)` when memory efficiency and low heap pressure matter most.
+- Use `kafka-crab-js v4 (stream, batch)` when raw throughput or memory efficiency is the priority.
+- Use `kafka-crab-js v4 (stream, serial)` when message-by-message processing needs the lowest lifecycle RSS and heap
+  pressure.
 - Compare batch scenarios with batch scenarios and message scenarios with message scenarios.
 - `@platformatic/kafka` is the strongest non-crab throughput competitor in this run, but it used more RSS, heap, and GC
-  time than the v4 batch scenario.
+  time than both v4 scenarios.
 - KafkaJS `eachMessage` concurrency did not help this workload.
 
 ### Benchmark Configuration
 
-Common knobs:
+Captured benchmark settings:
 
 ```bash
 BENCHMARK_ITERATIONS=100000
 BENCHMARK_RUNS=5
+BENCHMARK_FETCH_MIN_BYTES=1
+BENCHMARK_FETCH_WAIT_MS=10
+BENCHMARK_MAX_BYTES=2048
 BENCHMARK_BATCH_SIZE=4096
 BENCHMARK_BATCH_TIMEOUT_MS=2
-BENCHMARK_MAX_BYTES=2048
+BENCHMARK_KAFKAJS_EACH_MESSAGE_CONCURRENCY=3
 BENCHMARK_MEMORY=1
+BENCHMARK_MEMORY_SAMPLE_MS=100
+BENCHMARK_MEMORY_SETTLE_MS=100
+BENCHMARK_TOPIC=benchmarks
+BENCHMARK_PARTITIONS=3
 ```
 
-See the [benchmark README](../benchmark/README.md) for the full benchmark methodology and environment variables.
+See [BENCHMARKS.md](../../BENCHMARKS.md) for the latest captured run and the
+[benchmark README](../../benchmarks/kafka/README.md) for the full benchmark methodology and environment variables.
 
 ## Migration Notes
 
@@ -782,6 +1076,34 @@ const client = new KafkaClient({
 
 Consumer and producer configuration objects also accept their own `configuration` maps.
 
+### `fetch.max.bytes` Must Be At Least `message.max.bytes`
+
+librdkafka validates fetch limits at consumer creation time. If you tune fetch sizes for benchmarks or production and
+set `message.max.bytes` higher than `fetch.max.bytes`, the consumer will fail to start with an error similar to:
+
+```text
+`fetch.max.bytes` must be >= `message.max.bytes`
+```
+
+Keep the fetch caps aligned:
+
+```ts
+const consumer = client.createConsumer({
+  groupId: 'orders-worker',
+  configuration: {
+    'message.max.bytes': 1_000_000,
+    'fetch.max.bytes': 1_048_576,
+    'max.partition.fetch.bytes': 1_048_576,
+  },
+})
+```
+
+### Benchmark Numbers Move Between Runs
+
+Kafka benchmarks are sensitive to CPU frequency, power mode, broker state, topic data already in page cache, and V8 heap
+history. The benchmark package defaults to isolated child processes for memory mode to reduce cross-scenario
+contamination, but you should still compare multiple runs and focus on large, repeatable gaps.
+
 ## Development
 
 From the repository root: