agentfootprint 11.1.0 → 11.2.0

package/dist/adapters/observability/file.js

@@ -37,10 +37,14 @@
  * `exportEvent` is sync and never touches the disk: it serializes, buffers, and
  * returns. Batches are appended asynchronously on a size trigger
  * (`maxBufferEvents` / `maxBufferBytes`), on a timer (`flushIntervalMs`), and on
- * `flush()`. A hard kill therefore loses at most the buffer — the price of not
- * making telemetry a term in agent-loop latency. Call `flush()` (or
- * `agent.shutdown()`, which does) at process end; see the 8.12.0 lifecycle laws
- * on {@link BaseStrategy.flush}.
+ * `flush()` — all through ONE queue (`outbox.ts`), so one append is in flight
+ * at a time: this sink's appends never interleave, and lines land in dispatch
+ * order (#223). That is not atomicity — a disk that fails partway through an
+ * append (ENOSPC) can still leave part of a line behind, and that batch is
+ * reported dropped. A hard kill loses the buffer and can interrupt the append
+ * in flight — the price of not making telemetry a term in agent-loop latency.
+ * Call `flush()` (or `agent.shutdown()`, which does) at process end; see the
+ * 8.12.0 lifecycle laws on {@link BaseStrategy.flush}.
  *
  * ## Rotation is ONE generation, and that is deliberate
  *
@@ -75,6 +79,7 @@ exports.fileObservability = void 0;
 const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
 const wireJson_js_1 = require("../../lib/wireJson.js");
 const deliveryErrors_js_1 = require("./deliveryErrors.js");
+const outbox_js_1 = require("./outbox.js");
 // ─── Public factory ──────────────────────────────────────────────────
 /**
  * NDJSON-to-a-local-file observability strategy. See
@@ -120,27 +125,13 @@ function fileObservability(opts) {
             `Fix the path or the permission — this sink refuses to start rather than ` +
             `silently drop every event.`);
     }
-    // Buffered lines — drained by `flush()` / size trigger / timer.
-    const buffer = [];
-    let bufferBytes = 0;
-    let lastFlushPromise = Promise.resolve();
-    let timer;
+    // Set by `stop()`: this sink accepts no more events. It is NOT a guard on
+    // writing — `stop()` does not authorise throwing away what was already
+    // accepted, and `flush()` after it still writes (the 8.11.1 stance).
     let stopped = false;
     // The fallback when the consumer wires nothing. Rate-limited; a
     // consumer-supplied sink is not.
     const consoleSink = (0, deliveryErrors_js_1.rateLimitedConsoleSink)(strategyName);
-    function scheduleTimedFlush() {
-        if (timer || flushIntervalMs <= 0 || stopped)
-            return;
-        timer = setTimeout(() => {
-            timer = undefined;
-            void doFlush();
-        }, flushIntervalMs);
-        // Never hold the process open for telemetry. `unref` exists on Node's
-        // Timeout and not on the browser's number — feature-detected, so a
-        // non-Node runtime with an injected `_fs` still works.
-        timer.unref?.();
-    }
     /** Route a delivery failure through whatever `_onError` IS RIGHT NOW —
      *  reading it at call time, so a consumer who assigns `_onError` after
      *  construction still receives them (the 8.11.0 fix). */
@@ -162,28 +153,29 @@ function fileObservability(opts) {
         await fs.rename(path, rotatedPath);
         bytesOnDisk = 0;
     }
-    async function doFlush() {
-        // `stopped` is deliberately NOT a guard here — same stance as the AWS
-        // adapters since 8.11.1. `stop()` stops this strategy ACCEPTING events; it
-        // does not authorise throwing away events already accepted, and a `flush()`
-        // that cannot make progress after a `stop()` is how shutdown spins forever.
-        if (buffer.length === 0)
-            return;
-        // Snapshot + clear so events emitted during the in-flight write accumulate
-        // into the next batch.
-        const batch = buffer.splice(0);
-        const batchBytes = bufferBytes;
-        bufferBytes = 0;
-        const data = `${batch.join('\n')}\n`;
-        try {
-            await rotateIfNeeded(batchBytes);
-            await fs.appendFile(path, data);
-            bytesOnDisk += byteLength(data);
-        }
-        catch (err) {
-            reportFailure(new Error(`${batch.length} event(s) dropped writing to '${path}': ${errorMessage(err)}`));
-        }
+    /** One batch: rotate if it would cross the ceiling, then append. Runs
+     *  inside the outbox's queue, so no other batch — and no other rotation —
+     *  can start until this one settles. */
+    async function writeBatch(lines) {
+        const data = `${lines.join('\n')}\n`;
+        const bytes = byteLength(data);
+        await rotateIfNeeded(bytes);
+        await fs.appendFile(path, data);
+        bytesOnDisk += bytes;
     }
+    // Buffered lines, and the one queue every write goes through — size
+    // trigger, timer, `flush()`, shutdown (outbox.ts; #223).
+    const outbox = (0, outbox_js_1.createOutbox)({
+        name: strategyName,
+        maxItems: maxBufferEvents,
+        maxBytes: maxBufferBytes,
+        flushIntervalMs,
+        // Never hold the process open for a local write.
+        timerHoldsProcess: false,
+        deliver: writeBatch,
+        dropped: (lines, cause) => new Error(`${lines.length} event(s) dropped writing to '${path}': ${errorMessage(cause)}`),
+        report: reportFailure,
+    });
     function enqueue(event) {
         if (stopped)
             return;
@@ -205,17 +197,11 @@ function fileObservability(opts) {
         // write, and a bare "undefined" line would corrupt the NDJSON stream.
         if (line === undefined)
             return;
-        buffer.push(line);
-        bufferBytes += byteLength(line) + 1; // + the newline this line will carry
-        if (buffer.length >= maxBufferEvents || bufferBytes >= maxBufferBytes) {
-            // Size trigger. Chain onto the last write rather than racing it — the
-            // file's line order IS the dispatch order, and that is the only thing an
-            // offline reader can rely on.
-            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-        }
-        else {
-            scheduleTimedFlush();
-        }
+        // + the newline this line will carry. The outbox decides when it is
+        // written, and writes it after every line accepted before it — the file's
+        // line order IS the dispatch order, the one thing an offline reader can
+        // rely on.
+        outbox.add(line, byteLength(line) + 1);
     }
     const strategy = {
         name: strategyName,
@@ -226,31 +212,22 @@ function fileObservability(opts) {
          * Write what is buffered. Called for you on shutdown (8.12.0) — by the
          * handle `enable.observability()` returns, by `agent.shutdown()`, and by a
          * `standingAgent` closing. Safe at any time, including after `stop()`.
+         *
+         * Resolves once every event accepted before the call is written (or
+         * dropped and reported) — one a timed write already had in flight
+         * included — after one more sweep of what arrived while it waited. It
+         * does not chase a producer that keeps emitting. A write that never
+         * settles holds it: nothing can cancel an in-flight write.
          */
-        async flush() {
-            // BOUNDED BY CONSTRUCTION — every pass must remove at least one buffered
-            // line; a pass that removes none ends the drain instead of retrying. The
-            // shape the CloudWatch adapter arrived at in 8.11.1, for the same reason:
-            // a drain that cannot finish must return, never spin.
-            for (;;) {
-                const pending = buffer.length;
-                lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-                await lastFlushPromise;
-                if (buffer.length === 0)
-                    return;
-                if (buffer.length >= pending)
-                    return;
-            }
+        flush() {
+            return outbox.drain();
         },
         /** Clear the timer and stop accepting events. Terminal: there is no
          *  restart. What it does NOT do is discard the buffer — `flush()` after
          *  `stop()` still writes it. */
         stop() {
             stopped = true;
-            if (timer) {
-                clearTimeout(timer);
-                timer = undefined;
-            }
+            outbox.stop();
         },
         /** Where failures go. Two callers: the dispatch layer (when `exportEvent`
          *  itself throws) and this adapter's own write path. */

package/dist/adapters/observability/file.js.map

@@ -1 +1 @@
-{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/adapters/observability/file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/adapters/observability/file.ts"],"names":[],"mappings":"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"}

package/dist/adapters/observability/outbox.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * outbox — the one owner of buffered, timed, serialized delivery for the
+ * batching sinks in this folder: `file`, `cloudwatch` (and `agentcore`, which
+ * is built on it) and `xray`.
+ *
+ * A sink accepts items on its hot path (sync, no I/O) and hands them here. The
+ * outbox decides WHEN a batch leaves and makes sure only one leaves at a time:
+ *
+ *   - **One queue, every trigger.** The size trigger, the timer and `drain()`
+ *     (the sink's `flush()`, and so every shutdown) all queue a delivery on
+ *     the same promise chain. Nothing calls `deliver` any other way.
+ *   - **One delivery in flight.** A delivery starts only after the previous
+ *     one settled. A large `fs.promises.appendFile` is several `write()`s; two
+ *     of them interleaved tear NDJSON lines (reported in #223, where the timer
+ *     bypassed the chain). Whatever a sink does around its write — the file
+ *     sink's rotation — runs inside its delivery, so it can never be skipped
+ *     or reordered either. This keeps ONE sink's deliveries from interleaving;
+ *     it does not make a delivery atomic (a disk that fails partway through an
+ *     append can still leave part of it behind).
+ *   - **Oldest first, within the receiver's limits.** A delivery takes the
+ *     oldest waiting items, so items leave in the order they were accepted.
+ *     When a receiving service limits one request (`maxItemsPerDelivery`,
+ *     `maxBytesPerDelivery` — CloudWatch's PutLogEvents), a delivery takes
+ *     only the oldest items that fit, and the rest go in the next delivery,
+ *     right after. That matters BECAUSE of the queue: a slow delivery lets a
+ *     backlog build behind it, which one request may not be allowed to carry.
+ *     Each part settles on its own — shipped, or dropped and reported.
+ *   - **`drain()` is bounded.** It resolves once every item accepted BEFORE
+ *     the call has settled (delivered, or dropped and reported), one the timer
+ *     already had in flight included — then makes one sweep of what arrived
+ *     while it waited. It never chases a producer that keeps emitting: under
+ *     steady traffic it ends after about two deliveries.
+ *   - **A failed batch is dropped and reported once**, then the next batch
+ *     goes. It is never requeued, so a full disk or an outage cannot grow the
+ *     outbox. The queue never rejects: a failure report that itself throws is
+ *     said on the console instead of becoming an unhandled rejection.
+ *
+ * What it does NOT do: bound a delivery that never settles. A hung disk holds
+ * the queue, and `drain()` with it; nothing can cancel an in-flight write.
+ *
+ * Role: leaf helper for `adapters/observability/*`. Composed as a field,
+ * never inherited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOutbox = void 0;
+const deliveryErrors_js_1 = require("./deliveryErrors.js");
+/** Build the outbox one sink owns. A per-delivery cap that could take
+ *  nothing is refused: such a delivery could never finish a drain. */
+function createOutbox(opts) {
+    if (opts.maxItemsPerDelivery !== undefined) {
+        requireDeliveryCap(opts.name, opts.maxItemsPerDelivery);
+    }
+    const waiting = [];
+    let waitingBytes = 0;
+    // Running counts. Deliveries take the oldest items, one delivery at a time,
+    // so once `settled` reaches n the first n accepted items are done.
+    let accepted = 0; // handed to `add`
+    let taken = 0; // taken by a delivery (in flight or settled)
+    let settled = 0; // delivered, or dropped and reported
+    // The ONE queue. Every delivery is chained here; `deliverNext` never
+    // rejects, so the chain never does either.
+    let queue = Promise.resolve();
+    // A delivery is queued and has not started yet. It will take everything
+    // waiting when it starts, so another trigger meanwhile has nothing to add —
+    // and the chain cannot grow while a delivery hangs.
+    let deliveryQueued = false;
+    let timer;
+    let stopped = false;
+    const consoleFallback = (0, deliveryErrors_js_1.rateLimitedConsoleSink)(opts.name);
+    function add(item, bytes = 0) {
+        waiting.push({ item, bytes });
+        waitingBytes += bytes;
+        accepted++;
+        if (atSizeTrigger())
+            queueDelivery();
+        else
+            armTimer();
+    }
+    function atSizeTrigger() {
+        if (waiting.length >= opts.maxItems)
+            return true;
+        return opts.maxBytes !== undefined && waitingBytes >= opts.maxBytes;
+    }
+    function armTimer() {
+        if (timer !== undefined || stopped || opts.flushIntervalMs <= 0)
+            return;
+        timer = setTimeout(onTimer, opts.flushIntervalMs);
+        // `unref` exists on Node's Timeout and not on a browser's number, so it
+        // is feature-detected.
+        if (!opts.timerHoldsProcess)
+            timer.unref?.();
+    }
+    function onTimer() {
+        timer = undefined;
+        queueDelivery();
+    }
+    function queueDelivery() {
+        if (deliveryQueued)
+            return;
+        deliveryQueued = true;
+        queue = queue.then(deliverNext);
+    }
+    async function deliverNext() {
+        deliveryQueued = false;
+        const { batch, leftBehind } = takeOldest();
+        if (batch.length === 0)
+            return;
+        try {
+            await opts.deliver(batch);
+        }
+        catch (cause) {
+            reportDropped(batch, cause);
+        }
+        // Settled exactly once, whatever happened to the deliveries around it.
+        settled += batch.length;
+        // Items a per-delivery limit left behind were already due when this
+        // delivery started — deliver them now rather than on the next timer.
+        if (leftBehind)
+            queueDelivery();
+    }
+    /** Take the oldest waiting items one delivery may carry. `leftBehind` says
+     *  a per-delivery limit stopped the take with items still waiting. */
+    function takeOldest() {
+        const entries = waiting.splice(0, countForOneDelivery());
+        for (const entry of entries)
+            waitingBytes -= entry.bytes;
+        if (waiting.length === 0)
+            waitingBytes = 0;
+        taken += entries.length;
+        return { batch: entries.map((entry) => entry.item), leftBehind: waiting.length > 0 };
+    }
+    /** How many of the oldest waiting items fit one delivery: at least one,
+     *  then as many as the item and byte limits allow, in order. */
+    function countForOneDelivery() {
+        const most = Math.min(waiting.length, opts.maxItemsPerDelivery ?? waiting.length);
+        const byteLimit = opts.maxBytesPerDelivery;
+        if (byteLimit === undefined)
+            return most;
+        const overhead = opts.overheadBytesPerItem ?? 0;
+        let count = 0;
+        let bytes = 0;
+        while (count < most) {
+            const entry = waiting[count];
+            if (entry === undefined)
+                break;
+            const cost = entry.bytes + overhead;
+            if (count > 0 && bytes + cost > byteLimit)
+                break;
+            bytes += cost;
+            count++;
+        }
+        return count;
+    }
+    function reportDropped(batch, cause) {
+        let error;
+        try {
+            error = opts.dropped(batch, cause);
+        }
+        catch {
+            error = new Error(`${batch.length} item(s) dropped: ${messageOf(cause)}`);
+        }
+        try {
+            opts.report(error);
+        }
+        catch (hookError) {
+            // The consumer's own `onError` threw. Say both things on the console
+            // rather than letting the queue reject (an unhandled rejection, which
+            // ends a Node process by default).
+            consoleFallback(new Error(`${error.message} — and the onError hook threw: ${messageOf(hookError)}`));
+        }
+    }
+    async function drain() {
+        // Everything accepted before this call, in flight or waiting…
+        await settleThrough(accepted);
+        // …then ONE sweep of what arrived while it waited, so a `stop()` right
+        // after `flush()` strands nothing that was already here. The target is
+        // fixed when the sweep starts, so steady traffic cannot keep it going.
+        await settleThrough(accepted);
+    }
+    /** Wait until the first `target` accepted items have settled. */
+    async function settleThrough(target) {
+        while (settled < target) {
+            const before = settled;
+            // Some of them still wait: make sure a delivery will take them.
+            if (taken < target)
+                queueDelivery();
+            await queue;
+            // A pass that settled nothing would repeat forever. With the cap
+            // refused above it cannot happen; if it ever does, end — never spin.
+            if (settled === before)
+                return;
+        }
+    }
+    function stop() {
+        stopped = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    }
+    return { add, drain, stop };
+}
+exports.createOutbox = createOutbox;
+/** The sink-to-outbox contract: a cap is a whole number above zero. Sinks
+ *  map and refuse their own options first (X-Ray: `segmentsPerPut`), so this
+ *  guards the contract rather than a caller's input. */
+function requireDeliveryCap(name, cap) {
+    if (Number.isInteger(cap) && cap > 0)
+        return;
+    throw new TypeError(`[${name}Observability] the outbox was given a per-delivery cap of ${String(cap)}; ` +
+        `a delivery that may take no items could never finish a drain.`);
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=outbox.js.map

package/dist/adapters/observability/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../../src/adapters/observability/outbox.ts"],"names":[],"mappings":"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"}

package/dist/adapters/observability/xray.js

@@ -73,6 +73,7 @@ exports.xrayObservability = void 0;
 const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
 const wireJson_js_1 = require("../../lib/wireJson.js");
 const deliveryErrors_js_1 = require("./deliveryErrors.js");
+const outbox_js_1 = require("./outbox.js");
 // ─── Strategy factory ────────────────────────────────────────────────
 function xrayObservability(opts) {
     if (!opts.serviceName) {
@@ -86,11 +87,8 @@ function xrayObservability(opts) {
     // multiple in-flight turns; we key the active stack by the run
     // anchor (`meta.runId` — see anchorRunId).
     const activeTurns = new Map();
-    // Outbound segment buffer (flat list of closed segments ready for
-    // PutTraceSegments). Drained by flush() / size-trigger / time-trigger.
-    const outbox = [];
-    let lastFlushPromise = Promise.resolve();
-    let timer;
+    // Set by `stop()`: no more events accepted. NOT a guard on delivery (8.11.1):
+    // segments already closed and queued are still owed to X-Ray.
     let stopped = false;
     // The fallback when the consumer wires nothing. Rate-limited; a
     // consumer-supplied sink is not.
@@ -103,44 +101,32 @@ function xrayObservability(opts) {
         client = createXRayClient(opts.region, opts._sdk);
         return client;
     }
-    function scheduleTimedFlush() {
-        if (timer || flushIntervalMs <= 0 || stopped)
-            return;
-        timer = setTimeout(() => {
-            timer = undefined;
-            void doFlush();
-        }, flushIntervalMs);
-    }
-    async function doFlush() {
-        // `stopped` is deliberately NOT a guard here (8.11.1). `stop()` stops this
-        // strategy ACCEPTING events and cancels its timer; segments already closed
-        // and queued are still owed to X-Ray. Guarding here made `flush()` after
-        // `stop()` loop forever waiting for a drain that could no longer happen —
-        // an infinite microtask spin that starved the event loop of the process
-        // trying to shut down.
-        if (outbox.length === 0)
-            return;
-        const batch = outbox.splice(0, maxBatchSegments);
-        try {
-            await ensureClient().putTraceSegments({
-                TraceSegmentDocuments: batch.map((s) => (0, wireJson_js_1.toWireJson)(s)),
-            });
-        }
-        catch (err) {
-            // Routed through the strategy's CURRENT `_onError` (not a hook captured
-            // at construction), so a consumer who assigns it — or passes `onError`
-            // — actually receives delivery failures. Before 8.11.0 the hook was
-            // installed lazily inside `_onError` itself and was `undefined` here,
-            // so every failed put was silent.
-            strategy._onError?.(new Error(`${batch.length} segment(s) dropped shipping to X-Ray: ` +
-                (err instanceof Error ? err.message : String(err))));
-        }
-        // If outbox grew during the put (size > maxBatchSegments emits
-        // arrived), chain another flush.
-        if (outbox.length > 0 && !stopped) {
-            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-        }
+    /** Ship one batch of closed segments. Throws when it could not — the
+     *  outbox drops the batch and reports it once. */
+    async function shipSegments(batch) {
+        await ensureClient().putTraceSegments({
+            TraceSegmentDocuments: batch.map((s) => (0, wireJson_js_1.toWireJson)(s)),
+        });
     }
+    // Closed segments ready for PutTraceSegments, and the one queue every put
+    // goes through — size trigger, timer, `flush()`, shutdown (outbox.ts;
+    // #223). A put takes at most `maxBatchSegments` (its whole part); what the
+    // cap leaves behind ships right after it.
+    const outbox = (0, outbox_js_1.createOutbox)({
+        name: 'xray',
+        // The trigger compares the value as given, as before the outbox.
+        maxItems: maxBatchSegments,
+        maxItemsPerDelivery: segmentsPerPut(maxBatchSegments),
+        flushIntervalMs,
+        timerHoldsProcess: true,
+        deliver: shipSegments,
+        dropped: (batch, cause) => new Error(`${batch.length} segment(s) dropped shipping to X-Ray: ` +
+            (cause instanceof Error ? cause.message : String(cause))),
+        // Routed through the strategy's CURRENT `_onError` (not a hook captured
+        // at construction), so a consumer who assigns it — or passes `onError`
+        // — actually receives delivery failures (8.11.0).
+        report: (err) => strategy._onError?.(err),
+    });
     function pushSegment(turnState, name) {
         const parent = turnState.stack[turnState.stack.length - 1];
         const seg = {
@@ -199,15 +185,10 @@ function xrayObservability(opts) {
             seg.metadata = { default: { ...(seg.metadata?.default ?? {}), ...extra.metadata } };
         if (turnState.sampled) {
             turnState.closed.push(seg);
-            // Once the root closes, the whole turn graduates to outbox.
+            // Once the root closes, the whole turn graduates to the outbox.
             if (turnState.stack.length === 0) {
-                outbox.push(...turnState.closed);
-                if (outbox.length >= maxBatchSegments) {
-                    lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-                }
-                else {
-                    scheduleTimedFlush();
-                }
+                for (const closed of turnState.closed)
+                    outbox.add(closed);
             }
         }
     }
@@ -415,22 +396,11 @@ function xrayObservability(opts) {
                 while (t.stack.length > 0)
                     closeSegment(t, undefined);
             }
-            // BOUNDED BY CONSTRUCTION — every pass must shrink the outbox (a put
-            // takes up to `maxBatchSegments` at a time, so several passes are
-            // normal); a pass that shrinks nothing ends the drain instead of trying
-            // again. The previous `while (outbox.length > 0)` trusted `doFlush()` to
-            // make progress, which it stopped doing after `stop()` — an infinite
-            // microtask spin that starved the event loop during shutdown.
-            for (;;) {
-                const pending = outbox.length;
-                // Chain, never replace: segments ship in the order they closed.
-                lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
-                await lastFlushPromise;
-                if (outbox.length === 0)
-                    return;
-                if (outbox.length >= pending)
-                    return;
-            }
+            // Segments ship in the order they closed, one put at a time, behind the
+            // put in flight — one the timer started included. Resolves once every
+            // segment closed before this call is shipped (or dropped and reported),
+            // after one more sweep; a put that never settles holds it.
+            await outbox.drain();
         },
         /** Stop the flush timer and stop accepting events. **The framework does
          *  not call this for you** — an un-stopped strategy keeps a `setTimeout`
@@ -441,10 +411,7 @@ function xrayObservability(opts) {
          *  (8.11.1). */
         stop() {
             stopped = true;
-            if (timer) {
-                clearTimeout(timer);
-                timer = undefined;
-            }
+            outbox.stop();
         },
         /**
          * Where errors go. Two callers: the dispatch layer (when `exportEvent`
@@ -460,6 +427,25 @@ function xrayObservability(opts) {
     return strategy;
 }
 exports.xrayObservability = xrayObservability;
+// ─── Batch size ──────────────────────────────────────────────────────
+/**
+ * How many segments one put takes — exactly what `outbox.splice(0,
+ * maxBatchSegments)` took before the shared queue: the whole part of the
+ * value, and every segment for `Infinity` (returned as no cap).
+ *
+ * A value whose whole part is below 1 — `0`, a fraction under 1, a negative
+ * number, `NaN` — took NO segments, so every put was empty and the queue
+ * never emptied: puts in a loop, forever. That never worked, so it is refused
+ * here, by the option's name; every value that did work keeps its meaning.
+ */
+function segmentsPerPut(maxBatchSegments) {
+    const whole = Math.trunc(maxBatchSegments);
+    if (whole === Infinity)
+        return undefined;
+    if (whole >= 1)
+        return whole;
+    throw new TypeError(`[xrayObservability] \`maxBatchSegments\` must be at least 1 (got ${String(maxBatchSegments)}): ` + `it is how many segments one put takes, and a put of none never empties the queue.`);
+}
 // ─── ID + time helpers ───────────────────────────────────────────────
 /**
  * Generate an X-Ray trace ID. Format: