emb 0.3.0 → 0.4.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aff64eb7fb61e9d6ce29bb76786020087ea90c317ec04344bf1cb8d3b3fd4e8
-  data.tar.gz: ccf361c3c12406e71e778976e63f580b6bd56c0d658f12a2acdef6c75d42143f
+  metadata.gz: 7f3eb540be54e104585249da101c6dd0a77c22c5f7ace642be44b11927d71643
+  data.tar.gz: c963843c42d593640a11201abbb64b698e353c3d674df53d027bbce363ee2df1
 SHA512:
-  metadata.gz: 40ba7fd979d43af7ab056f4c4981245f3d19080d8f19b19026d6f3d132a947d1ae3e14c8cef326a4b65876250ddfc58cd00b5ce48f6301d65e5a21b3bffe945a
-  data.tar.gz: 583dd05fd04481dcdc7f4c3a4312c9464e1660d7e27bf16caebe543ddda8cde7ff8e4f6a156eefcd54b484cc4031551a1e89361ea437ec76082f3e0a4fb44ebe
+  metadata.gz: cd19e8b5017cfa0d377a8940a6ed44ecdc78bb5ac5e0905cff9e364ff02d49f68714b4542d2af0fb5f5b89254c8736294c7a62e0ba1506138fa04c5b5ac6f645
+  data.tar.gz: 3a66bb58df4664a86ccaddf991d584de31b7b7ffce1aacf5c4d1f8f9151e252e4409719fc20af54d2f52aabae6f66df9092546e8c91d19eda52b4804a9017dd4

data/Gemfile

@@ -4,7 +4,6 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'connection_pool'
 gem 'redis-client'
 
 gem 'rake', require: false

data/README.md

@@ -55,7 +55,7 @@ resolve in this order — the first one wins:
 ```ruby
 Emb.configure do |c|
   c.pool = 8
-  c.batch = false   # opt out of lazy batching app-wide
+  c.lazy = :multi   # defer and coalesce embed calls app-wide
 end
 
 Emb.configuration   # => the shared Emb::Configuration
@@ -67,11 +67,28 @@ Emb::Client.new(pool: 20)  # per-call still wins
 
 ### Out-of-the-box defaults
 
-The shipped defaults are benchmark-derived (see `BENCHMARK.md`): **lazy batching is on by
-default** (`batch: true` — each embed coalesces into one `EMB.MULTI`), pool `5`, pure-Ruby
-RESP driver, `protocol: 2`, `reconnect_attempts: 3`. To keep the eager behavior (immediate
-`EMB` per call), opt out globally via `Emb.configure { |c| c.batch = false }` or per client
-with `Emb.new(batch: false)`.
+The shipped defaults are benchmark-derived (see `BENCHMARK.md`) with secure-by-default
+network behavior: **eager execution by default** (`lazy: false` — every `Emb[:model][t]`
+sends one `EMB` round trip), pool `5`, pure-Ruby RESP driver, `protocol: 2`,
+`read_timeout`/`write_timeout` both **10s**, and `reconnect_attempts: 0`. Opt into
+coalescing with `lazy: :multi` or concurrent fan-out with `lazy: :batch` — globally via
+`Emb.configure { |c| c.lazy = :batch }` or per client with `Emb.new(lazy: :batch)`.
+
+**Why the timeout and reconnect defaults matter:** batched `EMB.MULTI` (up to 512 pairs)
+can take over a second of inference on a shared CPU, and redis-client's silent default is
+1.0s — a slower reply times out. The gem therefore defaults to an explicit 10s timeout
+and `reconnect_attempts: 0`: a failing batch fails closed after one attempt and raises
+`Emb::ServerError` (see [Lazy batching](#lazy-batching)). Set
+`Emb.configure { |c| c.reconnect_attempts = 2 }` and redis-client re-sends
+**connection and protocol failures** up to that many extra times before the batch fails
+closed — each re-send re-runs server inference, so keep the budget small. Operation
+errors (unknown model, auth, bad pairs) are never retried, and neither are **read
+timeouts**: redis-client treats `ReadTimeoutError` as terminal, and re-sending a timed-out
+command could duplicate inference the server already did. `lazy: :batch` shares
+additionally retry a refused connection on the next configured instance. Raise the
+timeouts if you raise `batch_size`. `reconnect_attempts` also accepts an Array of
+per-retry delays (a redis-client passthrough); each entry grants one retry and counts
+toward `Emb::ServerError#attempts`.
 
 ### Connection pool
 
@@ -79,11 +96,48 @@ with `Emb.new(batch: false)`.
 Emb.setup(url: "redis://localhost:6379", pool: 10)
 ```
 
-The default pool size is **5**. The pool is usually not the bottleneck for
-inference-bound workloads (small pools are fine); it becomes a knob only at high
-concurrency on a multi-model box — see [Performance](#performance). If a pool checkout
-would wait too long, `RedisClient`'s `connect_timeout`/`read_timeout` (above) bound the
-wait.
+The default pool size is **5**. The client keeps `pool` persistent connections per
+emb **instance** and routes commands through them **in round-robin order** —
+consecutive commands use different connections instead of reusing one hot connection.
+
+`url` also accepts an **array of instances** (interchangeable replicas serving the same
+model set); commands then round-robin across instances first, then across connections
+within the selected instance:
+
+```ruby
+Emb.setup(url: ["redis://emb-a:6379", "redis://emb-b:6379", "redis://emb-c:6379"], pool: 5)
+```
+
+Each url gets its own pool of `pool` connections, so `pool: 5` with three urls maintains
+15 connections total. If an instance refuses a connection **before a command is sent**
+(connection refused/unreachable), the command is retried on the next instance — this is
+why `reconnect_attempts` stays `0`: a retry after a *sent* command could duplicate
+inference, but a never-sent command is safe to move elsewhere.
+
+This matters when emb runs as a pool of instances behind a **connection-level load
+balancer** (AWS Service Connect, an NLB, or Envoy): the balancer assigns each
+keep-alive connection to exactly one instance for its lifetime, so relying on a
+single connection would pin all of a process's embedding traffic to one instance —
+and queue it there even while other instances sit idle. Round-robin spreading across
+`pool` connections spreads traffic across up to `pool` instances, so set `pool` to
+**at least your expected emb instance count** (e.g. `pool: 10` for 10 instances).
+
+Commands beyond the pool's parallelism do **not** time out: when `pool` commands are
+already in flight, later commands wait on the shared connections until one frees
+(there is no checkout timeout — unlike the previous pool's 5s
+`ConnectionPool::TimeoutError`). Only the wait for a free pool connection is
+unbounded — once a command runs, `RedisClient`'s `connect_timeout`,
+`read_timeout`, and `write_timeout` still apply. For inference workloads this
+lets commands ride out token-budget batching instead of erroring.
+
+Locally (a single server) only the backend selection is identical whatever the
+pool size — every command reaches the same server. The pool size still controls
+how many persistent connections the client holds and how many commands run in
+parallel. The pool is usually not the bottleneck for
+inference-bound workloads (small pools are fine); it becomes a knob at high
+concurrency on a multi-model box — see [Performance](#performance). With
+round-robin selection up to `pool` commands run in parallel; beyond that, commands
+share connections and serialize on them.
 
 ### Authentication
 
@@ -124,8 +178,8 @@ Emb.setup(
 ```
 
 See the [redis-client documentation](https://github.com/redis-rb/redis-client) for
-all available options. Only `pool` and `batch` are handled by the gem — everything
-else passes through to `RedisClient.new`.
+all available options. Only `pool`, `lazy`, and `batch_size` are handled by the
+gem — everything else passes through to `RedisClient.new`.
 
 ## Instance-based clients
 
@@ -169,6 +223,12 @@ automatically.
 
 ## Server info & config
 
+> **Per-instance data.** `Emb.server_info`, `stats`, `info`, and `config` read
+> from ONE instance, and with round-robin connection selection that instance
+> may change between calls (with `pool: 1` it never does) — each call is a
+> sample. `Emb.config[key] = value` mutates one (arbitrary) instance. Use
+> per-connection queries if you need a specific or aggregated view.
+
 The server exposes Redis-style `INFO` and `CONFIG` commands; the gem wraps them.
 
 ### `Emb.stats` — server statistics as a hash
@@ -190,15 +250,18 @@ Emb.stats
 ### `Emb.server_info` — sectioned INFO, parsed
 
 The Redis-style `INFO` reply is parsed into a nested Hash. **No arguments = all
-sections**; pass section names to filter (`:server`, `:cache`, `:keyspace`, `:stats`, `:clients`):
+sections**; pass section names to filter (`:server`, `:cache`, `:keyspace`, `:stats`, `:memory`, `:cpu`, `:clients`):
 
 ```ruby
 Emb.server_info
 # => {Server: {redis_version: "0.2.4", emb_version: "0.2.4", uptime_secs: "7", ...},
 #     Cache: {cache_hits: 0, cache_misses: 0, cache_hit_rate: "0.0%", ...},
-#     Keyspace: {db0: "model=minilm,keys=0,hits=0,misses=0,hit_rate=0.0%"}, ...}
+#     Keyspace: {db0: "model=minilm,keys=0,hits=0,misses=0,hit_rate=0.0%"},
+#     Memory: {used_memory_rss_bytes: 262438912, used_memory_heap_bytes: 154960,
+#              goroutines: 4, total_system_memory_bytes: 25769803776},
+#     CPU: {used_cpu_user_usec: 188900, used_cpu_sys_usec: 50462, gomaxprocs: 10}, ...}
 
-Emb.server_info(:server, :cache)   # only those two sections
+Emb.server_info(:memory, :cpu)   # live process resources only
 ```
 
 ### `Emb.config` — hot config read & change
@@ -228,6 +291,28 @@ exceptions (`RedisClient::CommandError`): read-only parameters (`listen`, `tls_*
 `models`), invalid values, and `NOAUTH` on password-protected servers are not
 swallowed.
 
+### Cache lifecycle commands
+
+When server-side caching is enabled, the Ruby client exposes the lifecycle
+commands on module, instance, pooled, and round-robin clients:
+
+```ruby
+Emb.cache_flush             # all models; => removed entry count
+Emb.cache_flush(:minilm)    # one model; => removed entry count
+Emb.save_cache              # => "OK" once the background save is accepted
+
+Emb.stats[:cache_snapshot_in_progress] # 0 or 1
+Emb.server_info(:cache)                # completion, failure, restore limits
+```
+
+Snapshot persistence is configured on the server with `cache_file`,
+`cache_load`, `cache_save`, `cache_save_on_shutdown`, `cache_restore_limit`,
+`cache_restore_reserve`, and `cache_save_rate_limit`. Automatic saves keep
+serving inference and control commands while encoding and I/O run in the
+background. Snapshot files include original input text and embeddings; use
+protected/encrypted storage where appropriate and treat them as disposable
+warm-start data rather than a durable database.
+
 ## Usage
 
 ### Single text
@@ -244,6 +329,32 @@ client = Emb.new(url: "redis://localhost:6379")
 result = client[:minilm]["hello world"]
 ```
 
+### VALUE format (RESP decimal reply)
+
+By default the server replies with the compact float32 binary wire and the gem
+unpacks it. Pass `format: :values` to send the RedisAI-style `VALUES` keyword
+and get the server's self-describing envelope back: `dtype`, `shape`, and the
+embedding values as decimal floats (the float64 widening the server stores, so
+`unpack` is not needed). Single texts return the envelope with flat `values`;
+multiple texts group the values per text (rows of `shape`).
+
+```ruby
+Emb[:minilm]["hello world", format: :values]
+# => { dtype: "FLOAT", shape: [1, 384], values: [0.0123, -0.0456, ...] }
+
+Emb[:minilm]["hello", "world", format: :values]
+# => { dtype: "FLOAT", shape: [2, 384], values: [[...], [...]] }
+```
+
+The batch loaders accept the same keyword; mixed formats within one batch
+raise `ArgumentError`.
+
+> **RESP3 note:** the server emits the decimal values as typed RESP3 doubles when
+> the connection negotiated `HELLO 3` and as decimal bulk strings otherwise.
+> The gem speaks RESP2 (binary default, decimal `values` opt-in) and does not
+> parse RESP3 replies itself — connect with a RESP3-capable client to use the
+> typed doubles on the wire.
+
 ### Multiple texts
 
 ```ruby
@@ -273,38 +384,93 @@ client.multi do |m|
 end
 ```
 
-### Lazy batching (`Emb.batch`)
+### Script replies
+
+`Emb.eval` / `Emb.evalsha` run a Lua script against a model (KEYS = texts,
+ARGV = args) and parse replies through the RESP grammar — hashes, arrays,
+strings, errors. Unlike the embed path, a scripted reply has no fixed shape,
+so packed vectors are **not** auto-decoded: a `float32_bytes` reply comes back
+as the raw bulk String. Decode it per call with the `decode:` keyword:
+
+```ruby
+sha = client.script.load(:siglip2, siglip_source)
+
+# decode: :f32 — the reply is a packed float32 vector (or a numeric array)
+vec = client.evalsha(:siglip2, sha, ["a photo of a cat"], ["normalize"], decode: :f32)
+# => [0.0123, -0.0456, ...]  768 floats
+
+# multi-text replies decode each element
+vecs = client.evalsha(:siglip2, sha, ["a", "b"], ["normalize"], decode: :f32)
+# => [[0.0123, ...], [-0.0456, ...]]
+
+# decode: {field => :f32} — structured replies decode a named field
+out = client.evalsha(:siglip2, sha, ["a"], ["normalize"], decode: { embedding: :f32 })
+# => {"dim" => 768, "embedding" => [0.0123, ...]}
+```
+
+`decode:` defaults to `nil` (no decoding, exactly today's behavior). Supported
+modes are `:f32` and `{field => :f32}`; anything else, or a reply that is not
+actually a float vector / hash at the decodable position, raises
+`ArgumentError`. A raw bulk can always be decoded by hand with
+`reply.unpack("e*")`.
 
-Instead of collecting pairs by hand, `Emb.batch` returns lazy embeddings that all
-coalesce into a single `EMB.MULTI` round trip when the first one is used. This is
-powered by the [batch-loader](https://github.com/exAspArk/batch-loader) gem.
+### Lazy batching
+
+In `:batch` mode the shares fan out across the configured instances (one share per
+instance when the share count allows) or across the instance's pool connections when a
+single url is configured — a batch whose pieces take 60ms and 10ms completes in roughly
+the slowest share (~60ms) instead of the sum (~70ms). Deferred work is powered by the
+[batch-loader](https://github.com/exAspArk/batch-loader) gem:
 
 ```ruby
+Emb.setup(lazy: :multi)  # or :batch — Emb[:minilm] now defers
+
 users = User.all # some application objects
 
 # Create loaders first...
-l1 = Emb.batch[:minilm]["hello"]
-l2 = Emb.batch[:minilm]["world"]
-l3 = Emb.batch[:bge]["bonjour"]
+l1 = Emb[:minilm]["hello"]
+l2 = Emb[:minilm]["world"]
+l3 = Emb[:bge]["bonjour"]
 
-# ...then consume them. The first use sends ONE EMB.MULTI for all three.
+# ...then consume them. The first use sends ONE EMB (single-model scope)
+# or ONE EMB.MULTI (mixed-model scope) for all three.
 l1.sum  # => 12.345
 l2.sum  # => -0.678
 l3.sum  # => 3.141
 ```
 
-Instance clients expose the same API:
-
-```ruby
-client.batch[:minilm]["hello"].sum
-```
-
 Each lazy value materializes to the same shape as the eager API: a single text
-yields an `Array<Float>`, multiple texts yield `Array<Array<Float>>`:
+yields an `Array<Float>`, multiple texts yield `Array<Array<Float>>`. For explicit
+composition that always sends immediately regardless of mode, use `Emb.multi { }`
+(see [Multi-model queries](#multi-model-queries)).
+
+The batch executes in the current thread's scope; the Rack/ActiveJob middleware
+clears that scope after every request/job (`Emb::BatchScope`), so deferred work
+can never accumulate across requests (in eager mode there is nothing to clear).
+
+**Fail-closed batches.** If a batch command fails — a timeout, an operation error, or in
+`:batch` mode a share failure after pre-send retries are exhausted — the batch raises
+**`Emb::ServerError`** to the code that first used it, and every deferred item of that
+batch is removed from the scope — retrying (or using other items of the failed batch)
+**does not re-send the batch** and resolves to `[]` instead. The error's `cause` is the
+underlying redis error (`RedisClient::ReadTimeoutError`, `RedisClient::CommandError`, ...)
+and its message includes the model(s), text count, and attempt count. Transient failures
+(timeout, connection error, protocol error) re-send up to `reconnect_attempts` extra
+times when that option is set above 0 (default 0 = a single attempt); operation errors
+are never retried. A non-redis error raised by the batch call itself (e.g. a `TypeError`
+from bad arguments) is a local bug, not a server failure: the batch's pending items are
+still cleared, but the original error is re-raised. This
+prevents a slow server from turning one failed batch into endless duplicate work
+(retries re-running the whole batch) or growth of the pending set across retries.
+Pair-level failures the server reports as `null` (MGET semantics) are unaffected.
+
+> **Breaking change (gem ≥ next release):** a failed batch raises `Emb::ServerError`
+> instead of the raw `RedisClient::*` error. Rescue `Emb::ServerError` and read `cause`
+> for the original error. Eager `Emb.multi` and the `lazy: false` path are unchanged.
 
 ```ruby
-vec   = Emb.batch[:minilm]["hello"]   # use -> Array of Float
-vecs  = Emb.batch[:minilm]["hello", "world"]  # use -> Array of Array of Float
+vec   = Emb[:minilm]["hello"]            # use -> Array of Float
+vecs  = Emb[:minilm]["hello", "world"]  # use -> Array of Array of Float
 ```
 
 Embeddings are cached per thread, so reusing a lazy value (or creating an
@@ -318,43 +484,59 @@ Loaders only fire when a value is **used**. Create all loaders *first*, then
 consume them, so they share one round trip:
 
 ```ruby
-texts.each { |t| process(Emb.batch[:minilm][t]) }   # wrong: one MULTI per item
-loaders = texts.map { |t| Emb.batch[:minilm][t] }   # right: ONE MULTI for all
+texts.each { |t| process(Emb[:minilm][t]) }   # wrong: one EMB per item
+loaders = texts.map { |t| Emb[:minilm][t] }   # right: ONE EMB for all
 loaders.each { |l| process(l) }
 ```
 
 A loader that is created but never used **never embeds** (unless a sibling batch
 fires first) and is silently dropped when the thread's scope ends. Duration and
-scope: batching is per-thread — a multithreaded app issues one `EMB.MULTI` per
+scope: batching is per-thread — a multithreaded app issues one `EMB`/`EMB.MULTI` per
 thread per flush.
 
-### `batch` configuration option
+### `lazy` configuration option
 
-Setting `batch: true` makes the standard proxy API lazy, so existing call sites
-batch automatically without restructuring:
+Setting `lazy: :multi` or `lazy: :batch` makes the standard proxy API defer, so
+existing call sites batch automatically without restructuring:
 
 ```ruby
-Emb.setup(url: "redis://localhost:6379", batch: true)
+Emb.setup(url: "redis://localhost:6379", lazy: :multi)
 # or
-Emb.new(url: "redis://localhost:6379", batch: true)
+Emb.new(url: "redis://localhost:6379", lazy: :batch)
 ```
 
-With `batch: true`, `Emb[:minilm]["hello"]` returns a lazy embedding that sends
-`EMB.MULTI` on first use. The default is `false` — the proxy API stays eager,
-sending `EMB` immediately. `Emb.batch` works regardless of the option, and
-`Emb.multi` remains the explicit, eager, deterministic batching API.
+Under `lazy: :multi`, `Emb[:minilm]["hello"]` returns a lazy embedding that sends
+`EMB` on first use (serial chunks; `EMB.MULTI` only for mixed-model scopes). Under `lazy: :batch`, the chunk shares
+execute concurrently — with multiple `url`s they fan out across instances. The
+default is eager (`lazy: false`). `Emb.multi` remains the explicit, eager,
+deterministic composition API in every mode.
 
 ### Clearing the cache per request
 
-The per-thread batch scope holds cached embeddings for the life of the thread. In
-request-shaped processes (Rails, Rack apps, Sidekiq) mount `Emb::Middleware` to
-clear the scope at the end of each request:
+The per-thread batch scope holds cached embeddings for the life of the thread.
+In a Rails application the bundled Railtie mounts `Emb::Middleware`
+automatically, so the scope is cleared at the end of every request with no
+configuration:
 
 ```ruby
-# config/application.rb (Rails)
-config.middleware.use Emb::Middleware
+# nothing to do — Emb::Railtie inserts Emb::Middleware for you
+```
+
+Opt out if you want to manage the stack yourself:
 
-# Any Rack app
+```ruby
+# config/application.rb
+config.emb.middleware = false
+```
+
+If your Gemfile loads `emb` before Rails is required (non-standard boot order), the
+guarded railtie require in `emb.rb` is skipped — add `require "emb/railtie"` in
+`config/application.rb` right after `require "rails/all"` (or in an initializer).
+
+The middleware is also safe to mount manually in any Rack app (the Railtie
+skips insertion when it is already present):
+
+```ruby
 use Emb::Middleware
 ```
 
@@ -362,6 +544,46 @@ The scope is cleared even when the app raises, and a fresh scope starts
 automatically with the next request. Loaders created but never used within a
 request are dropped — the create-then-consume contract applies per request.
 
+### Job-scoped cache clearing
+
+The Railtie also registers `Emb::JobMiddleware` — the same per-scope clearing
+for background work — for every job framework present. Each job execution
+starts with a fresh batch scope: cached embeddings and loaders created but
+never used are dropped at the end of the job (even when it raises), so worker
+threads never leak scope state between jobs.
+
+- **ActiveJob** (SolidQueue, Sidekiq, Shoryuken, async, test adapters): an
+  `around_perform` callback on `ActiveJob::Base` registered by the Railtie.
+- **Plain Sidekiq workers** (non-ActiveJob): a server middleware added by the
+  Railtie.
+- **Plain Shoryuken workers** (non-ActiveJob): a server middleware added by the
+  Railtie.
+
+```ruby
+# opt out of all job-scope protection
+config.emb.job_middleware = false
+```
+
+In a non-Rails process, register the middleware manually:
+
+```ruby
+# sidekiq.rb / an initializer
+Sidekiq.configure_server do |config|
+  config.server_middleware { |chain| chain.add Emb::JobMiddleware }
+end
+
+# Shoryuken
+Shoryuken.configure_server do |config|
+  config.server_middleware { |chain| chain.add Emb::JobMiddleware }
+end
+```
+
+The Railtie also registers `Emb::JobMiddleware` into the `Sidekiq::Testing` middleware
+chain when `Sidekiq::Testing` is loaded *before the app finishes booting* (e.g. a dev
+`INLINE_SIDEKIQ` initializer). For RSpec test modes, `sidekiq/testing` typically loads
+after the app boots, so require it before your environment to get per-job clearing in
+fake/inline tests — e.g. `gem "sidekiq", require: ["sidekiq", "sidekiq/testing"]`.
+
 ## Performance
 
 ### Eager-burst pipelining (no new API)
@@ -372,7 +594,7 @@ batching doesn't fit), coalesce them into one packet with `RedisClient#pipelined
 ```ruby
 client = Emb.new(url: "redis://localhost:6379")
 
-a = client.pool.with do |conn|
+a = client.pools.first.with do |conn|
   conn.pipelined do |pipe|
     texts.each { |t| pipe.call("EMB", "minilm", t) }
   end
@@ -380,9 +602,22 @@ end
 # a -> Array of Float32-binary replies; unpack each with r.unpack("e*")
 ```
 
-`Client#pool` exposes the pool's `RedisClient` connections. This measurably beats
-plain per-call round trips; use it for bursts, and `Emb.batch`/`Emb.multi` when you want
-server-side coalescing into one `EMB.MULTI`.
+`Client#pools` exposes the per-instance pools' `RedisClient` connections (the
+first pool for a single-instance client). This measurably beats
+plain per-call round trips; use it for bursts, and `Emb.multi` or a deferred `lazy`
+mode when you want
+server-side coalescing into one packed inference.
+
+### Benchmark harness coverage
+
+The client benchmark harness (`gems/emb/bench/bench.rb`, `just bench-ruby`)
+reports one row per execution mechanism: `eager` (one `EMB` per call), `multi`
+(coalesced `EMB`, or `EMB.MULTI` for mixed models), `batch` (concurrent `EMB` chunk shares),
+`pipelined` (raw RESP pipelining), and `threaded` (eager across threads).
+`just bench-ruby-multi` starts two partitioned emb instances and adds the
+url-array rows `eager-2node` (round-robin distribution) and `batch-2node`
+(concurrent fan-out across instances); the two-node rows are skipped unless a
+second instance is reachable (`EMB_BENCH_PORT2`).
 
 ### RESP driver: pure-Ruby default, `hiredis` on demand
 
@@ -409,7 +644,7 @@ instance. Scale out without a cluster client:
   (optionally seed with `-cache` and a warmup pass).
 
 Lazy batching stays per server (a thread's loaders target one client), so batching and
-horizontal scale compose: each instance receives one `EMB.MULTI` per request.
+horizontal scale compose: each instance receives one `EMB` (single model) or `EMB.MULTI` (mixed) share per request.
 
 ### Commands