@ferricstore/ferricstore 0.1.6 → 0.2.0

package/docs/api/index.html

@@ -9,6 +9,12 @@
 </code><button type="button">Copy</button></pre>
 
 <p>Requires Node.js 22.22 or newer. The SDK ships ESM and CommonJS builds and is tested with Node 22, 24, and 26.</p>
+<h2 id="compatibility" class="tsd-anchor-link">Compatibility<a href="#compatibility" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>SDK <code>0.2.x</code> requires FerricStore server <code>0.8.0</code> or newer. FerricStore 0.8 is a
+breaking beta API contract update, while the native wire protocol remains v1
+(<code>FSNP</code> framing and existing opcode numbers are unchanged). Capabilities and
+response-size limits are negotiated per connection from the HELLO-shaped
+startup response rather than inferred from a server version table.</p>
 <p>ESM:</p>
 <pre><code class="ts"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">, </span><span class="hl-4">JsonCodec</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@ferricstore/ferricstore&quot;</span><span class="hl-1">;</span>
 </code><button type="button">Copy</button></pre>
@@ -18,24 +24,112 @@
 </code><button type="button">Copy</button></pre>
 
 <h2 id="run-ferricstore-locally" class="tsd-anchor-link">Run FerricStore Locally<a href="#run-ferricstore-locally" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
-<pre><code class="bash"><span class="hl-0">docker</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-5">-p</span><span class="hl-1"> </span><span class="hl-2">6388:6388</span><span class="hl-1"> </span><span class="hl-7">\</span><br/><span class="hl-1">  </span><span class="hl-5">-e</span><span class="hl-1"> </span><span class="hl-2">FERRICSTORE_PROTECTED_MODE=</span><span class="hl-5">false</span><span class="hl-1"> </span><span class="hl-7">\</span><br/><span class="hl-1">  </span><span class="hl-5">-v</span><span class="hl-1"> </span><span class="hl-2">ferricstore_data:/data</span><span class="hl-1"> </span><span class="hl-7">\</span><br/><span class="hl-1">  </span><span class="hl-2">ghcr.io/ferricstore/ferricstore:0.7.5</span>
+<pre><code class="bash"><span class="hl-0">docker</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-5">-p</span><span class="hl-1"> </span><span class="hl-2">6388:6388</span><span class="hl-1"> </span><span class="hl-7">\</span><br/><span class="hl-1">  </span><span class="hl-5">-e</span><span class="hl-1"> </span><span class="hl-2">FERRICSTORE_PROTECTED_MODE=</span><span class="hl-5">false</span><span class="hl-1"> </span><span class="hl-7">\</span><br/><span class="hl-1">  </span><span class="hl-5">-v</span><span class="hl-1"> </span><span class="hl-2">ferricstore_data:/data</span><span class="hl-1"> </span><span class="hl-7">\</span><br/><span class="hl-1">  </span><span class="hl-2">ghcr.io/ferricstore/ferricstore:0.8.0</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="cluster-aware-client" class="tsd-anchor-link">Cluster-aware client<a href="#cluster-aware-client" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
-<p>For a single node, use <code>fromUrl</code>. For a FerricStore cluster, pass multiple seed URLs. The SDK fetches the server <code>SHARDS</code> topology, routes keyed commands to the current shard leader, and refuses learned hosts outside the seed-host trust set by default.</p>
-<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrls</span><span class="hl-1">(</span><br/><span class="hl-1">  [</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;ferric://fs0.example.com:6388&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;ferric://fs1.example.com:6388&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;ferric://fs2.example.com:6388&quot;</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">(),</span><br/><span class="hl-1">    </span><span class="hl-4">nativeOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-8">// Use &quot;any&quot; only inside a trusted private network.</span><br/><span class="hl-1">      </span><span class="hl-4">endpointPolicy:</span><span class="hl-1"> </span><span class="hl-2">&quot;seed_hosts&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-4">warmConnections:</span><span class="hl-1"> </span><span class="hl-5">true</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">refreshTopology</span><span class="hl-1">();</span><br/><span class="hl-4">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">route</span><span class="hl-1">(</span><span class="hl-2">&quot;tenant-a:order-1&quot;</span><span class="hl-1">));</span>
+<p>For a single node, use <code>fromUrl</code>. For a FerricStore cluster, pass multiple seed URLs. The SDK fetches the server <code>SHARDS</code> topology, routes keyed commands to the current shard leader, and refuses learned hosts outside the seed-host trust set by default. The creation promise resolves only after startup and authentication succeed; cluster creation also waits for the initial topology, so connection failures reject the corresponding <code>await</code> directly.</p>
+<p>Cross-shard pipelines are grouped into one native pipeline per leader/lane and
+merged back into caller order. Decomposable multi-key commands (<code>MGET</code>,
+<code>EXISTS</code>, <code>DEL</code>, <code>UNLINK</code>, and <code>FLOW.VALUE.MGET</code>) use the same parallel shard
+fan-out; atomic multi-key commands are never split client-side. Pass
+<code>{ ordered: true }</code> as the second argument to <code>client.pipeline()</code> when later
+commands depend on earlier ones and the transport may need an individual or
+cross-route fallback.</p>
+<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrls</span><span class="hl-1">(</span><br/><span class="hl-1">  [</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;ferric://fs0.example.com:6388&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;ferric://fs1.example.com:6388&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;ferric://fs2.example.com:6388&quot;</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">(),</span><br/><span class="hl-1">    </span><span class="hl-4">nativeOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-8">// Use &quot;any&quot; only inside a trusted private network.</span><br/><span class="hl-1">      </span><span class="hl-4">endpointPolicy:</span><span class="hl-1"> </span><span class="hl-2">&quot;seed_hosts&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-8">// Bound client-side route fan-out; freed slots refill immediately.</span><br/><span class="hl-1">      </span><span class="hl-4">topologyConcurrency:</span><span class="hl-1"> </span><span class="hl-9">16</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-4">warmConnections:</span><span class="hl-1"> </span><span class="hl-5">true</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">refreshTopology</span><span class="hl-1">();</span><br/><span class="hl-4">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">route</span><span class="hl-1">(</span><span class="hl-2">&quot;tenant-a:order-1&quot;</span><span class="hl-1">));</span>
 </code><button type="button">Copy</button></pre>
 
+<p>Learned topology endpoints are checked before connection. The default
+<code>&quot;seed_hosts&quot;</code> policy permits exact seed endpoints plus <code>trustedHosts</code>;
+<code>&quot;none&quot;</code> permits exact seed endpoints only. Use <code>&quot;any&quot;</code> only when every
+server-advertised endpoint is already inside a trusted network boundary.
+All HA seed URLs must use the same <code>ferric://</code> or <code>ferrics://</code> transport;
+<code>tlsOptions</code> configures a secure transport but does not change a URL's scheme.
+Each seed connection uses only the credentials embedded in its own URL. The
+first complete seed credential pair is reused for learned cluster endpoints,
+but never overrides another seed URL, even when that seed is first reached
+through learned topology. Duplicate seed endpoints with conflicting effective
+credentials are rejected. Explicit <code>nativeOptions.username</code> and <code>password</code>
+remain an intentional cluster-wide override.</p>
+<p>The option types follow ownership: <code>NativeAdapterOptions</code> contains direct
+connection settings, <code>TopologyNativeAdapterOptions</code> adds learned-endpoint
+policy, and <code>NativeClientOptions</code> adds reconnect/HA seed selection. Passing a
+higher-layer option to <code>NativeAdapter.fromUrl()</code> is rejected instead of being
+silently ignored.</p>
+<p><code>topologyConcurrency</code> defaults to 16 and bounds client-side per-route work such
+as cross-shard fan-out, split pipelines, warm-up, and shutdown. It uses
+continuous slot filling: when one route finishes, the next waiting route starts
+without waiting for the rest of the current group. This setting is local to one
+client process or pod; it does not configure FerricStore server concurrency.</p>
+<p>Automatic reconnect retries only an operation rejected before it could be
+written. If a connection closes while a request is in flight, the SDK surfaces
+that error because the server may already have applied the command; it does not
+replay an uncertain mutation. A later request reconnects normally. Use
+FerricFlow fencing or command-level idempotency when the caller needs safe
+application retries. <code>ConnectionClosedError.requestDisposition</code> exposes this
+decision as <code>&quot;unsent&quot;</code> or <code>&quot;possibly_sent&quot;</code> when the transport can classify it;
+unclassified failures are treated conservatively as possibly sent.
+<code>RequestTimeoutError.requestDisposition</code> provides the same retry-safety signal:
+timeouts while waiting for a local flow-control or write-queue slot are
+<code>&quot;unsent&quot;</code>, while a request whose frame entered the socket is
+<code>&quot;possibly_sent&quot;</code>. Do not automatically retry a possibly-sent mutation.
+<code>autoReconnect</code> accepts <code>maxRetries</code>, <code>baseDelayMs</code>, <code>maxDelayMs</code>, and
+<code>jitterPct</code>; backoff is applied only after a reconnect attempt itself fails.</p>
+<p>Topology-aware clients retry one routed command or one physical fused pipeline
+after a successful topology refresh only when the server's typed reroute error
+explicitly reports both <code>retryable: true</code> and <code>safe_to_retry: true</code>. Producer
+backpressure follows the same flags and honors <code>retry_after_ms</code> within the
+configured delay cap. Split or scattered pipelines and uncertain connection
+failures are never replayed.</p>
+<p>Connection-local state mutations (<code>AUTH</code>, <code>CLIENT SETNAME</code>, <code>QUIT</code>, <code>RESET</code>,
+and related native controls) are rejected on reconnecting and topology clients
+because they cannot be applied atomically to every current and future socket.
+Configure <code>nativeOptions.username</code>, <code>password</code>, <code>clientName</code>, and <code>events</code> when
+creating those clients, and use <code>close()</code> for shutdown. A directly managed
+single <code>NativeAdapter</code> retains connection-local command semantics. Native
+<code>CLIENT TRACKING</code> and <code>CLIENT CACHING</code> are unsupported; use native event
+subscriptions instead.</p>
+<h3 id="deployment-integration-tests" class="tsd-anchor-link">Deployment integration tests<a href="#deployment-integration-tests" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>The default integration suite targets one local development server. Real HA,
+TLS, and authentication deployments can be verified with the opt-in deployment
+suite:</p>
+<pre><code class="bash"><span class="hl-4">FERRICSTORE_HA_URLS</span><span class="hl-1">=</span><span class="hl-2">ferric://fs0:6388,ferric://fs1:6388</span><span class="hl-1"> </span><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">test:integration:deployment</span><br/><br/><span class="hl-4">FERRICSTORE_TLS_URL</span><span class="hl-1">=</span><span class="hl-2">ferrics://fs0:6389</span><span class="hl-1"> </span><span class="hl-0">\</span><br/><span class="hl-1">FERRICSTORE_TLS_CA_FILE=/path/to/ca.pem </span><span class="hl-7">\</span><br/><span class="hl-1">npm </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">test:integration:deployment</span><br/><br/><span class="hl-4">FERRICSTORE_AUTH_URL</span><span class="hl-1">=</span><span class="hl-2">ferric://app:secret@fs0:6388</span><span class="hl-1"> </span><span class="hl-0">\</span><br/><span class="hl-1">npm </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">test:integration:deployment</span>
+</code><button type="button">Copy</button></pre>
+
+<p>The HA fixture must advertise at least two reachable leader endpoints. The auth
+fixture must require credentials even for the default user. Set
+<code>FERRICSTORE_TLS_PLAINTEXT_URL</code> as well to verify that a TLS-only deployment
+rejects its plaintext listener. HA TLS/auth options are available through
+<code>FERRICSTORE_HA_TLS_CA_FILE</code>, <code>FERRICSTORE_HA_TLS_SERVERNAME</code>,
+<code>FERRICSTORE_HA_USERNAME</code>, and <code>FERRICSTORE_HA_PASSWORD</code>.</p>
 <p>You can also keep one primary URL and add seeds:</p>
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://fs0.example.com:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">nativeOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-4">haRouting:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">seeds:</span><span class="hl-1"> [</span><span class="hl-2">&quot;ferric://fs1.example.com:6388&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;ferric://fs2.example.com:6388&quot;</span><span class="hl-1">]</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
+<p>Native connections honor the flow-control windows advertised by the
+HELLO-shaped <code>STARTUP</code> response and
+<code>WINDOW_UPDATE</code>. Available data-request slots are refilled immediately as
+responses finish; waiting requests are scheduled fairly across protocol lanes.
+The adapter also caps automatic lanes and same-lane work to the advertised lane
+queue, and caps ordered pipeline chunks and outbound frame bodies to the limits
+negotiated during startup. Compact response codecs and aggregate response sizes
+are enabled only when advertised for that connection.
+Set <code>nativeOptions.maxQueuedRequests</code> to bound the local waiter queue (default
+<code>65_536</code>, or <code>0</code> to reject immediately when all advertised slots are occupied).
+Queue waiting counts toward <code>nativeOptions.timeoutMs</code>.</p>
+<p>Control requests do not consume server data credits. Set
+<code>nativeOptions.maxPendingControlRequests</code> to bound correlated control requests
+awaiting responses on each connection (default <code>4_096</code>).</p>
+<p>If Node reports socket backpressure, later encoded frames wait for <code>drain</code> in a
+bounded client queue. Set <code>nativeOptions.maxQueuedWriteBytes</code> to control that
+queue (default 64 MiB, or <code>0</code> to reject subsequent writes immediately). Healthy
+socket writes still go directly to <code>socket.write</code> without entering the queue.</p>
 <h2 id="durable-queue" class="tsd-anchor-link">Durable Queue<a href="#durable-queue" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
-<pre><code class="ts"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">, </span><span class="hl-4">JsonCodec</span><span class="hl-1">, </span><span class="hl-4">QueueClient</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@ferricstore/ferricstore&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">emails</span><span class="hl-1"> = </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">QueueClient</span><span class="hl-1">(</span><span class="hl-4">flow</span><span class="hl-1">).</span><span class="hl-0">queue</span><span class="hl-1">(</span><span class="hl-2">&quot;email&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">enqueue</span><span class="hl-1">(</span><span class="hl-2">&quot;email-1&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">idempotent:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> { </span><span class="hl-4">template:</span><span class="hl-1"> </span><span class="hl-2">&quot;welcome&quot;</span><span class="hl-1">, </span><span class="hl-4">userId:</span><span class="hl-1"> </span><span class="hl-2">&quot;user-1&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">worker</span><span class="hl-1">({ </span><span class="hl-4">batchSize:</span><span class="hl-1"> </span><span class="hl-9">100</span><span class="hl-1">, </span><span class="hl-4">worker:</span><span class="hl-1"> </span><span class="hl-2">&quot;email-worker-1&quot;</span><span class="hl-1"> }).</span><span class="hl-0">run</span><span class="hl-1">(</span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">job</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-4">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">, </span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">payload</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-3">return</span><span class="hl-1"> { </span><span class="hl-4">sent:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> };</span><br/><span class="hl-1">});</span>
+<pre><code class="ts"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">, </span><span class="hl-4">JsonCodec</span><span class="hl-1">, </span><span class="hl-4">QueueClient</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@ferricstore/ferricstore&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">emails</span><span class="hl-1"> = </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">QueueClient</span><span class="hl-1">(</span><span class="hl-4">flow</span><span class="hl-1">).</span><span class="hl-0">queue</span><span class="hl-1">(</span><span class="hl-2">&quot;email&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">enqueue</span><span class="hl-1">(</span><span class="hl-2">&quot;email-1&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">idempotent:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> { </span><span class="hl-4">template:</span><span class="hl-1"> </span><span class="hl-2">&quot;welcome&quot;</span><span class="hl-1">, </span><span class="hl-4">userId:</span><span class="hl-1"> </span><span class="hl-2">&quot;user-1&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">enqueueMany</span><span class="hl-1">([{ </span><span class="hl-4">id:</span><span class="hl-1"> </span><span class="hl-2">&quot;email-2&quot;</span><span class="hl-1">, </span><span class="hl-4">payload:</span><span class="hl-1"> { </span><span class="hl-4">template:</span><span class="hl-1"> </span><span class="hl-2">&quot;receipt&quot;</span><span class="hl-1"> } }], {</span><br/><span class="hl-1">  </span><span class="hl-4">autoPartitionBatchSize:</span><span class="hl-1"> </span><span class="hl-9">1_000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">autoPartitionConcurrency:</span><span class="hl-1"> </span><span class="hl-9">8</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">worker</span><span class="hl-1">({ </span><span class="hl-4">batchSize:</span><span class="hl-1"> </span><span class="hl-9">100</span><span class="hl-1">, </span><span class="hl-4">concurrency:</span><span class="hl-1"> </span><span class="hl-9">16</span><span class="hl-1">, </span><span class="hl-4">worker:</span><span class="hl-1"> </span><span class="hl-2">&quot;email-worker-1&quot;</span><span class="hl-1"> }).</span><span class="hl-0">run</span><span class="hl-1">(</span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">job</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-4">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">, </span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">payload</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-3">return</span><span class="hl-1"> { </span><span class="hl-4">sent:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> };</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="explicit-workflow" class="tsd-anchor-link">Explicit Workflow<a href="#explicit-workflow" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
-<pre><code class="ts"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">, </span><span class="hl-4">JsonCodec</span><span class="hl-1">, </span><span class="hl-4">WorkflowClient</span><span class="hl-1">, </span><span class="hl-4">complete</span><span class="hl-1">, </span><span class="hl-4">transition</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@ferricstore/ferricstore&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">order</span><span class="hl-1"> = </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">WorkflowClient</span><span class="hl-1">(</span><span class="hl-4">flow</span><span class="hl-1">).</span><span class="hl-0">workflow</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">initialState:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;order&quot;</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">state</span><span class="hl-1">(</span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">ctx</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">chargeCard</span><span class="hl-1">(</span><span class="hl-4">ctx</span><span class="hl-1">.</span><span class="hl-4">payload</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-3">return</span><span class="hl-1"> </span><span class="hl-0">transition</span><span class="hl-1">(</span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">state</span><span class="hl-1">(</span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">, </span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">ctx</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">sendReceipt</span><span class="hl-1">(</span><span class="hl-4">ctx</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-3">return</span><span class="hl-1"> </span><span class="hl-0">complete</span><span class="hl-1">({ </span><span class="hl-4">result:</span><span class="hl-1"> { </span><span class="hl-4">ok:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> } });</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">start</span><span class="hl-1">(</span><span class="hl-2">&quot;order-1&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">idempotent:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> { </span><span class="hl-4">amount:</span><span class="hl-1"> </span><span class="hl-9">42</span><span class="hl-1">, </span><span class="hl-4">userId:</span><span class="hl-1"> </span><span class="hl-2">&quot;user-1&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">worker</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">batchSize:</span><span class="hl-1"> </span><span class="hl-9">50</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">states:</span><span class="hl-1"> [</span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">  </span><span class="hl-4">worker:</span><span class="hl-1"> </span><span class="hl-2">&quot;order-worker-1&quot;</span><br/><span class="hl-1">}).</span><span class="hl-0">run</span><span class="hl-1">();</span>
+<pre><code class="ts"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">, </span><span class="hl-4">JsonCodec</span><span class="hl-1">, </span><span class="hl-4">WorkflowClient</span><span class="hl-1">, </span><span class="hl-4">complete</span><span class="hl-1">, </span><span class="hl-4">transition</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@ferricstore/ferricstore&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">order</span><span class="hl-1"> = </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">WorkflowClient</span><span class="hl-1">(</span><span class="hl-4">flow</span><span class="hl-1">).</span><span class="hl-0">workflow</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">initialState:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;order&quot;</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">state</span><span class="hl-1">(</span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">ctx</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">chargeCard</span><span class="hl-1">(</span><span class="hl-4">ctx</span><span class="hl-1">.</span><span class="hl-4">payload</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-3">return</span><span class="hl-1"> </span><span class="hl-0">transition</span><span class="hl-1">(</span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">state</span><span class="hl-1">(</span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">, </span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">ctx</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">sendReceipt</span><span class="hl-1">(</span><span class="hl-4">ctx</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-3">return</span><span class="hl-1"> </span><span class="hl-0">complete</span><span class="hl-1">({ </span><span class="hl-4">result:</span><span class="hl-1"> { </span><span class="hl-4">ok:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> } });</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">start</span><span class="hl-1">(</span><span class="hl-2">&quot;order-1&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">idempotent:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> { </span><span class="hl-4">amount:</span><span class="hl-1"> </span><span class="hl-9">42</span><span class="hl-1">, </span><span class="hl-4">userId:</span><span class="hl-1"> </span><span class="hl-2">&quot;user-1&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">order</span><span class="hl-1">.</span><span class="hl-0">worker</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">batchSize:</span><span class="hl-1"> </span><span class="hl-9">50</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">concurrency:</span><span class="hl-1"> </span><span class="hl-9">8</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">states:</span><span class="hl-1"> [</span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">  </span><span class="hl-4">worker:</span><span class="hl-1"> </span><span class="hl-2">&quot;order-worker-1&quot;</span><br/><span class="hl-1">}).</span><span class="hl-0">run</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
 <p>Handlers return explicit durable outcomes:</p>
@@ -46,10 +140,57 @@
 <li><code>fail({ error })</code></li>
 </ul>
 <p>FerricFlow does not replay TypeScript handler code. Workers claim a durable state, run normal code, then write the next state through the FerricFlow API.</p>
+<p>Per-job <code>run()</code> workers cap every claim to currently available concurrency. They continuously refill slots by default, so if five of ten jobs finish and their terminal writes are acknowledged, one client-side <code>claim(limit: 5)</code> can start five replacements while the other five continue. Queue completions produced in the same event-loop turn remain batched. A slot stays occupied through its <code>complete</code>, <code>retry</code>, or <code>fail</code> acknowledgement; the worker never exceeds its local concurrency limit.</p>
+<p>Full-record claims across multiple states are returned by the claim command itself, including requested payloads and named values. <code>FLOW.GET</code> hydration is retained only for compatibility with a server that unexpectedly returns legacy compact tuples. That fallback preserves result order and is bounded to 16 concurrent reads by default; set <code>legacyClaimHydrationConcurrency</code> on the client to tune it. If a fallback read fails, <code>ClaimHydrationError.claimed</code> contains every already-leased job, while <code>hydratedItems</code> contains the indexed records that finished successfully; <code>failedIndex</code> and <code>cause</code> identify the first observed failure. Set <code>jobOnly: true</code> when compact claim metadata is sufficient; compact state metadata is decoded directly from the claim response without per-job <code>FLOW.GET</code> calls.</p>
+<p>Use <code>refillStrategy: &quot;wave&quot;</code> to wait for the entire current claim to settle before claiming again. <code>refillDelayMs</code> adds a small coalescing window before a continuous refill; the default <code>0</code> still coalesces completions for one event-loop turn. Batchable queue completions and same-route replacement claims share one ordered native pipeline by default; set <code>fuseCompleteClaim: false</code> to keep them as separate requests. <code>runOnce()</code> and batch-handler APIs remain finite and wave-oriented. These controls are local to one worker instance or pod: two pods configured with <code>concurrency: 10</code> can execute up to twenty jobs collectively.</p>
+<p>Worker claim and terminal-write batches use the client's <code>flowManyBatchLimit</code>,
+which defaults to FerricStore's standard 1,000-item limit and should match the
+server's <code>flow_max_batch_items</code> setting. Higher handler concurrency remains
+supported and is filled through multiple bounded claims. <code>completeAsyncDepth</code>
+is normalized to a finite, non-negative integer; non-finite values use the safe
+worker-mode default. If an asynchronous completion fails after earlier writes
+succeed, <code>QueueCompletionError.completed</code> reports every successful completion
+drained by the same call, regardless of where the failed completion appeared.</p>
+<p>When a worker combines <code>blockMs</code> with an <code>AbortSignal</code>, native long polls are
+bounded by <code>abortPollMs</code> (default <code>1_000</code>) so shutdown is observed without
+abandoning an in-flight claim that may already have leased work. Finite server
+blocking time is added to the transport timeout rather than consuming it.</p>
+<p>Unpartitioned <code>enqueueMany</code> calls group items in linear time, preserve caller
+result order, keep chunks for the same auto-partition sequential, and dispatch
+different partitions with bounded concurrency. The defaults above match the
+server's standard 1,000-item Flow batch limit while avoiding unbounded requests.
+Explicit and mixed-partition independent batches use the same hard request cap;
+all Flow many mutations split larger inputs only when <code>independent: true</code>.
+<code>independent: false</code> is never silently split and rejects oversized inputs before
+dispatch. Set <code>flowManyBatchLimit</code> on the client when the server uses a custom
+<code>flow_max_batch_items</code> value. If a later independent chunk fails,
+<code>FlowBatchError.completedItems</code> reports the exact input indices and values whose
+results were already confirmed; the original failure remains available as
+<code>cause</code>.</p>
+<p>Workers renew active leases every half lease by default and stop renewal before the fenced terminal write. Set <code>leaseRenewal: false</code> only when the handler is guaranteed to finish comfortably inside <code>leaseMs</code>; use <code>leaseRenewIntervalMs</code> to override the renewal interval.</p>
+<p><code>ctx.valueMany(names)</code> deduplicates shared references and fetches every missing referenced value with one <code>FLOW.VALUE.MGET</code>. Inline and locally cached values do not consume network work, and a stored JSON <code>null</code> remains distinct from a missing reference.</p>
+<p>Flow fencing tokens remain <code>number</code> values while safe and are returned as
+<code>bigint</code> once they exceed JavaScript's safe integer range. Pass the token back
+unchanged; all fenced mutation APIs accept the exported <code>FencingToken</code> type,
+and native compact claim and batch paths preserve its signed 64-bit value
+exactly.</p>
 <h2 id="low-level-flow-commands" class="tsd-anchor-link">Low-Level Flow Commands<a href="#low-level-flow-commands" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">flow</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">create</span><span class="hl-1">(</span><span class="hl-2">&quot;order-1&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;order&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">state:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> </span><span class="hl-4">Buffer</span><span class="hl-1">.</span><span class="hl-0">from</span><span class="hl-1">(</span><span class="hl-2">&quot;order payload&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-4">idempotent:</span><span class="hl-1"> </span><span class="hl-5">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">jobs</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">claimDue</span><span class="hl-1">(</span><span class="hl-2">&quot;order&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">state:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">worker:</span><span class="hl-1"> </span><span class="hl-2">&quot;worker-1&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">leaseMs:</span><span class="hl-1"> </span><span class="hl-9">30_000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">limit:</span><span class="hl-1"> </span><span class="hl-9">10</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> </span><span class="hl-5">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">for</span><span class="hl-1"> (</span><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">job</span><span class="hl-1"> </span><span class="hl-5">of</span><span class="hl-1"> </span><span class="hl-4">jobs</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">transition</span><span class="hl-1">(</span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">, {</span><br/><span class="hl-1">    </span><span class="hl-4">fromState:</span><span class="hl-1"> </span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">state</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">toState:</span><span class="hl-1"> </span><span class="hl-2">&quot;charged&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">leaseToken:</span><span class="hl-1"> </span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">leaseToken</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">fencingToken:</span><span class="hl-1"> </span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">fencingToken</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">partitionKey:</span><span class="hl-1"> </span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">partitionKey</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
+<p>Flow attributes can be returned without hydrating each record and can be
+updated atomically with the fenced state mutation:</p>
+<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">attributed</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">claimDue</span><span class="hl-1">(</span><span class="hl-2">&quot;order&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">includeAttributes:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">jobOnly:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">state:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">worker:</span><span class="hl-1"> </span><span class="hl-2">&quot;worker-1&quot;</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">transition</span><span class="hl-1">(</span><span class="hl-4">attributed</span><span class="hl-1">[</span><span class="hl-9">0</span><span class="hl-1">]!.</span><span class="hl-4">id</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">attributesDelete:</span><span class="hl-1"> [</span><span class="hl-2">&quot;temporary&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">  </span><span class="hl-4">attributesMerge:</span><span class="hl-1"> { </span><span class="hl-4">processor:</span><span class="hl-1"> </span><span class="hl-2">&quot;payments-v2&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1">  </span><span class="hl-4">fencingToken:</span><span class="hl-1"> </span><span class="hl-4">attributed</span><span class="hl-1">[</span><span class="hl-9">0</span><span class="hl-1">]!.</span><span class="hl-4">fencingToken</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">fromState:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">leaseToken:</span><span class="hl-1"> </span><span class="hl-4">attributed</span><span class="hl-1">[</span><span class="hl-9">0</span><span class="hl-1">]!.</span><span class="hl-4">leaseToken</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">toState:</span><span class="hl-1"> </span><span class="hl-2">&quot;charged&quot;</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<p>The low-level client also exposes the fused <code>startAndClaim</code>, <code>stepContinue</code>,
+and <code>runStepsMany</code> operations, schedule administration, Flow statistics and
+attribute queries, effects, approvals, circuits, budgets, and distributed
+limits. History supports the complete server filter surface, including event,
+time, and version bounds plus cold/consistent reads and payload hydration:</p>
+<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">events</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">history</span><span class="hl-1">(</span><span class="hl-2">&quot;order-1&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">consistentProjection:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">fromVersion:</span><span class="hl-1"> </span><span class="hl-9">2</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">includeCold:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payloadMaxBytes:</span><span class="hl-1"> </span><span class="hl-9">64_000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">toVersion:</span><span class="hl-1"> </span><span class="hl-9">8</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">values:</span><span class="hl-1"> </span><span class="hl-5">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">scheduleCreate</span><span class="hl-1">(</span><span class="hl-2">&quot;orders-every-five-minutes&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">cron:</span><span class="hl-1"> </span><span class="hl-2">&quot;*/5 * * * *&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">kind:</span><span class="hl-1"> </span><span class="hl-2">&quot;cron&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">target:</span><span class="hl-1"> { </span><span class="hl-4">state:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;order&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1">  </span><span class="hl-4">timezone:</span><span class="hl-1"> </span><span class="hl-2">&quot;UTC&quot;</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
 <p>FIFO Flow state policy is opt-in per state:</p>
 <pre><code class="ts"><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">installPolicy</span><span class="hl-1">(</span><span class="hl-2">&quot;email&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">states:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-4">queued:</span><span class="hl-1"> { </span><span class="hl-4">mode:</span><span class="hl-1"> </span><span class="hl-2">&quot;fifo&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">flow</span><span class="hl-1">.</span><span class="hl-0">create</span><span class="hl-1">(</span><span class="hl-2">&quot;email-3&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">partitionKey:</span><span class="hl-1"> </span><span class="hl-2">&quot;tenant-a:email&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">payload:</span><span class="hl-1"> </span><span class="hl-4">Buffer</span><span class="hl-1">.</span><span class="hl-0">from</span><span class="hl-1">(</span><span class="hl-2">&quot;welcome&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-4">state:</span><span class="hl-1"> </span><span class="hl-2">&quot;queued&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;email&quot;</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
@@ -57,9 +198,15 @@
 <p>FIFO states require a <code>partitionKey</code>; priority is for parallel states.</p>
 <h2 id="ferricstore-kv-and-data-structures" class="tsd-anchor-link">FerricStore KV And Data Structures<a href="#ferricstore-kv-and-data-structures" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>The same client exposes typed helpers for FerricStore's Redis-compatible store commands:</p>
-<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">client</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">kv</span><span class="hl-1">.</span><span class="hl-0">set</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">, { </span><span class="hl-4">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;Ada&quot;</span><span class="hl-1"> }, { </span><span class="hl-4">px:</span><span class="hl-1"> </span><span class="hl-9">60_000</span><span class="hl-1"> });</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">user</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">kv</span><span class="hl-1">.</span><span class="hl-0">get</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">hash</span><span class="hl-1">.</span><span class="hl-0">hset</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1:profile&quot;</span><span class="hl-1">, { </span><span class="hl-4">email:</span><span class="hl-1"> </span><span class="hl-2">&quot;ada@example.com&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">lists</span><span class="hl-1">.</span><span class="hl-0">lpush</span><span class="hl-1">(</span><span class="hl-2">&quot;jobs&quot;</span><span class="hl-1">, { </span><span class="hl-4">id:</span><span class="hl-1"> </span><span class="hl-2">&quot;job-1&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">sets</span><span class="hl-1">.</span><span class="hl-0">sadd</span><span class="hl-1">(</span><span class="hl-2">&quot;seen-users&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">);</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">zset</span><span class="hl-1">.</span><span class="hl-0">zadd</span><span class="hl-1">(</span><span class="hl-2">&quot;leaderboard&quot;</span><span class="hl-1">, [{ </span><span class="hl-4">score:</span><span class="hl-1"> </span><span class="hl-9">42</span><span class="hl-1">, </span><span class="hl-4">member:</span><span class="hl-1"> </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1"> }]);</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">stream</span><span class="hl-1">.</span><span class="hl-0">xadd</span><span class="hl-1">(</span><span class="hl-2">&quot;events&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;*&quot;</span><span class="hl-1">, { </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-4">id:</span><span class="hl-1"> </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">json</span><span class="hl-1">.</span><span class="hl-0">set</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1:json&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;$&quot;</span><span class="hl-1">, { </span><span class="hl-4">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;Ada&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">bloom</span><span class="hl-1">.</span><span class="hl-0">add</span><span class="hl-1">(</span><span class="hl-2">&quot;seen-filter&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">);</span>
+<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">client</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">codec:</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-0">JsonCodec</span><span class="hl-1">()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">kv</span><span class="hl-1">.</span><span class="hl-0">set</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">, { </span><span class="hl-4">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;Ada&quot;</span><span class="hl-1"> }, { </span><span class="hl-4">px:</span><span class="hl-1"> </span><span class="hl-9">60_000</span><span class="hl-1"> });</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">user</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">kv</span><span class="hl-1">.</span><span class="hl-0">get</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">hash</span><span class="hl-1">.</span><span class="hl-0">hset</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1:profile&quot;</span><span class="hl-1">, { </span><span class="hl-4">email:</span><span class="hl-1"> </span><span class="hl-2">&quot;ada@example.com&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">lists</span><span class="hl-1">.</span><span class="hl-0">lpush</span><span class="hl-1">(</span><span class="hl-2">&quot;jobs&quot;</span><span class="hl-1">, { </span><span class="hl-4">id:</span><span class="hl-1"> </span><span class="hl-2">&quot;job-1&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">sets</span><span class="hl-1">.</span><span class="hl-0">sadd</span><span class="hl-1">(</span><span class="hl-2">&quot;seen-users&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">);</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">zset</span><span class="hl-1">.</span><span class="hl-0">zadd</span><span class="hl-1">(</span><span class="hl-2">&quot;leaderboard&quot;</span><span class="hl-1">, [{ </span><span class="hl-4">score:</span><span class="hl-1"> </span><span class="hl-9">42</span><span class="hl-1">, </span><span class="hl-4">member:</span><span class="hl-1"> </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1"> }]);</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">stream</span><span class="hl-1">.</span><span class="hl-0">xadd</span><span class="hl-1">(</span><span class="hl-2">&quot;events&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;*&quot;</span><span class="hl-1">, { </span><span class="hl-4">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;created&quot;</span><span class="hl-1">, </span><span class="hl-4">id:</span><span class="hl-1"> </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1"> });</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">bloom</span><span class="hl-1">.</span><span class="hl-0">add</span><span class="hl-1">(</span><span class="hl-2">&quot;seen-filter&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 
+<p>Large unambiguous scalar batches accept an array without spreading, for example
+<code>client.kv.del(keys)</code> and <code>client.tdigest.add(key, values)</code>. Codec-backed APIs,
+where an array may itself be one stored value, expose explicit methods such as
+<code>lpushMany</code>, <code>saddMany</code>, <code>zremMany</code>, <code>maddMany</code>, and <code>queryMany</code>. These forms
+avoid JavaScript's variadic-call limit and build the command in one linear pass;
+the existing rest-argument forms retain their original meaning.</p>
 <p>Available store helpers:</p>
 <ul>
 <li><code>client.kv</code> — strings, key expiry, key management, scans.</li>
@@ -72,21 +219,24 @@
 <li><code>client.hyperloglog</code> — HyperLogLog commands.</li>
 <li><code>client.geo</code> — geospatial commands.</li>
 <li><code>client.bloom</code>, <code>client.cuckoo</code>, <code>client.cms</code>, <code>client.topk</code>, <code>client.tdigest</code> — probabilistic data structures.</li>
-<li><code>client.json</code> — RedisJSON-compatible JSON commands.</li>
 </ul>
-<p>For connection-mode commands such as raw subscription flows or transactions, use <code>client.command(...)</code> directly so protocol behavior stays explicit.</p>
+<p><code>JsonCodec</code> serializes ordinary FerricStore values as JSON; FerricStore does not expose RedisJSON <code>JSON.*</code> commands.</p>
+<p>Transactions and raw subscription flows require an exclusive pinned connection
+session, which the multiplexed native client does not currently expose. The SDK
+rejects those commands before dispatch so a failed transaction cannot partially
+apply mutations.</p>
 <h2 id="auto-batching" class="tsd-anchor-link">Auto-Batching<a href="#auto-batching" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>The default client is latency-first: each SDK call sends its own native request.</p>
 <p>For high-throughput services that issue many independent calls concurrently, enable SDK auto-batching:</p>
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">client</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">FerricStoreClient</span><span class="hl-1">.</span><span class="hl-0">fromUrl</span><span class="hl-1">(</span><span class="hl-2">&quot;ferric://127.0.0.1:6388&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-4">autoBatch:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-4">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">maxCommands:</span><span class="hl-1"> </span><span class="hl-9">512</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">maxDelayMs:</span><span class="hl-1"> </span><span class="hl-9">0</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-10">Promise</span><span class="hl-1">.</span><span class="hl-0">all</span><span class="hl-1">([</span><br/><span class="hl-1">  </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">kv</span><span class="hl-1">.</span><span class="hl-0">set</span><span class="hl-1">(</span><span class="hl-2">&quot;a&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;1&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">kv</span><span class="hl-1">.</span><span class="hl-0">set</span><span class="hl-1">(</span><span class="hl-2">&quot;b&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;2&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-4">client</span><span class="hl-1">.</span><span class="hl-4">hash</span><span class="hl-1">.</span><span class="hl-0">hset</span><span class="hl-1">(</span><span class="hl-2">&quot;user:1&quot;</span><span class="hl-1">, { </span><span class="hl-4">email:</span><span class="hl-1"> </span><span class="hl-2">&quot;ada@example.com&quot;</span><span class="hl-1"> })</span><br/><span class="hl-1">]);</span>
 </code><button type="button">Copy</button></pre>
 
-<p>Auto-batching groups eligible concurrent commands into native <code>PIPELINE</code> frames and resolves each original promise independently. Blocking/session commands such as <code>FLOW.CLAIM_DUE</code>, <code>AUTH</code>, <code>QUIT</code>, <code>SUBSCRIBE</code>, and client-control commands bypass auto-batching.</p>
+<p>Auto-batching groups eligible concurrent commands into native <code>PIPELINE</code> frames and resolves each original promise independently. Across frames and individual-request fallbacks, same-key write dependencies retain invocation order, while read-only and disjoint-key work remains concurrent. Commands whose direct native representation uses a custom binary body are safely wrapped as typed <code>COMMAND_EXEC</code> pipeline items, preserving one pipeline request instead of issuing each command separately. Blocking/session and control commands such as <code>FLOW.CLAIM_DUE</code>, <code>BLPOP</code>, <code>XREAD</code>, <code>AUTH</code>, <code>PING</code>, <code>OPTIONS</code>, and <code>QUIT</code> bypass auto-batching. Explicit pipelines issue unsupported or connection-blocking items individually; blocking fallbacks and state-changing controls are sequenced with dependent data commands. Other fallbacks remain concurrent unless <code>client.pipeline(commands, { ordered: true })</code> is requested. Individual fallbacks continuously refill a bounded pool instead of starting every request at once; the default limit is 64 and <code>fallbackConcurrency</code> on the pipeline options can tune it per call. Native pipeline paths are unchanged. Reconnecting and topology executors reject connection-local mutations before dispatch, and an uncertain native pipeline is never replayed automatically.</p>
 <p>Queue workers are latency-first by default. For high-throughput queue workers, use one profile flag:</p>
-<pre><code class="ts"><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">worker</span><span class="hl-1">({ </span><span class="hl-4">profile:</span><span class="hl-1"> </span><span class="hl-2">&quot;throughput&quot;</span><span class="hl-1"> }).</span><span class="hl-0">run</span><span class="hl-1">(</span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">job</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">sendEmail</span><span class="hl-1">(</span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="ts"><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">emails</span><span class="hl-1">.</span><span class="hl-0">worker</span><span class="hl-1">({ </span><span class="hl-4">profile:</span><span class="hl-1"> </span><span class="hl-2">&quot;throughput&quot;</span><span class="hl-1">, </span><span class="hl-4">concurrency:</span><span class="hl-1"> </span><span class="hl-9">32</span><span class="hl-1"> }).</span><span class="hl-0">run</span><span class="hl-1">(</span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-4">job</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">sendEmail</span><span class="hl-1">(</span><span class="hl-4">job</span><span class="hl-1">.</span><span class="hl-4">id</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
-<p>The throughput profile uses compact claims, larger claim batches, and async completion batching. Explicit worker options still override the profile.</p>
+<p>The throughput profile uses compact claims, a larger batch ceiling, and concurrent completion batching. Per-job claim credit follows currently available <code>concurrency</code> (or its <code>workers</code> alias), capped by <code>batchSize</code>; explicit worker options override profile defaults.</p>
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>Runnable examples live in the <code>examples/</code> directory:</p>
 <ul>
@@ -124,4 +274,4 @@
 <pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">docs</span>
 </code><button type="button">Copy</button></pre>
 
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#ferricstore-typescript-sdk"><span>Ferric<wbr/>Store <wbr/>Type<wbr/>Script <wbr/>SDK</span></a><ul><li><a href="#install"><span>Install</span></a></li><li><a href="#run-ferricstore-locally"><span>Run <wbr/>Ferric<wbr/>Store <wbr/>Locally</span></a></li><li><a href="#cluster-aware-client"><span>Cluster-<wbr/>aware client</span></a></li><li><a href="#durable-queue"><span>Durable <wbr/>Queue</span></a></li><li><a href="#explicit-workflow"><span>Explicit <wbr/>Workflow</span></a></li><li><a href="#low-level-flow-commands"><span>Low-<wbr/>Level <wbr/>Flow <wbr/>Commands</span></a></li><li><a href="#ferricstore-kv-and-data-structures"><span>Ferric<wbr/>Store <wbr/>KV <wbr/>And <wbr/>Data <wbr/>Structures</span></a></li><li><a href="#auto-batching"><span>Auto-<wbr/>Batching</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><a href="#codecs"><span>Codecs</span></a></li><li><a href="#design-notes"><span>Design <wbr/>Notes</span></a></li><li><a href="#development"><span>Development</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@ferricstore/ferricstore</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#ferricstore-typescript-sdk"><span>Ferric<wbr/>Store <wbr/>Type<wbr/>Script <wbr/>SDK</span></a><ul><li><a href="#install"><span>Install</span></a></li><li><a href="#compatibility"><span>Compatibility</span></a></li><li><a href="#run-ferricstore-locally"><span>Run <wbr/>Ferric<wbr/>Store <wbr/>Locally</span></a></li><li><a href="#cluster-aware-client"><span>Cluster-<wbr/>aware client</span></a></li><li><ul><li><a href="#deployment-integration-tests"><span>Deployment integration tests</span></a></li></ul></li><li><a href="#durable-queue"><span>Durable <wbr/>Queue</span></a></li><li><a href="#explicit-workflow"><span>Explicit <wbr/>Workflow</span></a></li><li><a href="#low-level-flow-commands"><span>Low-<wbr/>Level <wbr/>Flow <wbr/>Commands</span></a></li><li><a href="#ferricstore-kv-and-data-structures"><span>Ferric<wbr/>Store <wbr/>KV <wbr/>And <wbr/>Data <wbr/>Structures</span></a></li><li><a href="#auto-batching"><span>Auto-<wbr/>Batching</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><a href="#codecs"><span>Codecs</span></a></li><li><a href="#design-notes"><span>Design <wbr/>Notes</span></a></li><li><a href="#development"><span>Development</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@ferricstore/ferricstore</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>

package/docs/api/interfaces/AdminListOptions.html

@@ -0,0 +1,4 @@
+<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>AdminListOptions | @ferricstore/ferricstore</title><meta name="description" content="Documentation for @ferricstore/ferricstore"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">@ferricstore/ferricstore</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">AdminListOptions</a></li></ul><h1>Interface AdminListOptions</h1></div><div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">AdminListOptions</span> <span class="tsd-signature-symbol">{</span><br/>    <a class="tsd-kind-property" href="#limit">limit</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">number</span><span class="tsd-signature-symbol">;</span><br/>    <a class="tsd-kind-property" href="#partitionkey">partitionKey</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br/>    <a class="tsd-kind-property" href="#scope">scope</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br/><span class="tsd-signature-symbol">}</span></div><section class="tsd-panel tsd-hierarchy" data-refl="1387"><h4>Hierarchy (<a href="../hierarchy.html#AdminListOptions">View Summary</a>)</h4><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-hierarchy-target">AdminListOptions</span><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><a href="LimitListOptions.html" class="tsd-signature-type tsd-kind-interface">LimitListOptions</a></li></ul></li></ul></section><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/ferricstore/ferricstore-typescript/blob/main/src/client-admin-options.ts#L129">src/client-admin-options.ts:129</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h5 class="tsd-index-heading uppercase">Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Properties</h3><div class="tsd-index-list"><a href="#limit" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>limit?</span></a>
+<a href="#partitionkey" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>partition<wbr/>Key?</span></a>
+<a href="#scope" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>scope?</span></a>
+</div></section></div></details></section></section><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Properties"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h2>Properties</h2></summary><section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="limit"><code class="tsd-tag">Optional</code><span>limit</span><a href="#limit" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">limit</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">number</span></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/ferricstore/ferricstore-typescript/blob/main/src/client-admin-options.ts#L132">src/client-admin-options.ts:132</a></li></ul></aside></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="partitionkey"><code class="tsd-tag">Optional</code><span>partition<wbr/>Key</span><a href="#partitionkey" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">partitionKey</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/ferricstore/ferricstore-typescript/blob/main/src/client-admin-options.ts#L131">src/client-admin-options.ts:131</a></li></ul></aside></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="scope"><code class="tsd-tag">Optional</code><span>scope</span><a href="#scope" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">scope</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/ferricstore/ferricstore-typescript/blob/main/src/client-admin-options.ts#L130">src/client-admin-options.ts:130</a></li></ul></aside></section></section></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Properties"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Properties</summary><div><a href="#limit"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>limit</span></a><a href="#partitionkey"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>partition<wbr/>Key</span></a><a href="#scope"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>scope</span></a></div></details></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">@ferricstore/ferricstore</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>