@blamejs/core 0.8.42 → 0.8.49

package/lib/safe-async.js

@@ -1,99 +1,62 @@
 "use strict";
 /**
- * Async resilience + safety primitives.
- *
- * The framework's async surfaces (external-db queries, cluster
- * coordination, queue operations, audit chain writes) all share the
- * same hazards: races between interleaved awaits, unbounded retries
- * masking real failures, hangs from unresponsive backends, and partial
- * results from operator-supplied drivers. This module collects the
- * primitives the framework uses to handle those hazards consistently.
- *
- * Surface includes:
- *   - Async coordination: withTimeout, withSignal, sleep, repeating,
- *     flushLoop, safeAwait, asyncRetry
- *   - Async state objects: Mutex, Semaphore, Once, CircuitBreaker
- *   - Sync helpers used by async pipelines: safeInvoke (callback
- *     wrapper with optional onError), makeDropCallback (factory for
- *     log-stream-style onDrop callbacks), makeScheduledFlush
- *     (idempotent setTimeout coalesce-and-flush helper)
- *
- * Design posture:
- *
- *   - **AbortSignal everywhere.** Every primitive that takes time
- *     accepts an `AbortSignal` and aborts cleanly when the signal
- *     fires. This is the modern Node.js convention (Node 18+) and
- *     replaces the older "cancellation token" pattern. Operators who
- *     don't pass a signal get the legacy non-cancellable behaviour.
- *
- *   - **Error.cause preserved.** Wrapper errors set `.cause` to the
- *     original failure so debugging traces back to the root. Callers
- *     who walk `.cause` chains see the full picture.
- *
- *   - **No leaked Promises.** Mutex / Semaphore release on path-out
- *     in finally blocks — even cancellation. No pending acquirer
- *     stays referenced after its abort.
- *
- *   - **Bounded by default.** Semaphore / Queue have explicit limits
- *     and reject acquisitions over the limit rather than growing
- *     unboundedly. Operators size limits explicitly for their workload.
- *
- *   - **Fail loud.** Errors propagate; primitives never silently
- *     swallow. safeAwait() opt-in for callers who need {error, value}
- *     tuples; everything else throws / rejects.
- *
- * Public API:
- *
- *   withTimeout(promise, ms, opts?)        promise; rejects on timeout
- *   withSignal(promise, signal)            promise; rejects on abort
- *   withTimeoutSignal(signal, ms)          AbortSignal composing user
- *                                          signal + a fresh timeout. Used
- *                                          by I/O primitives that already
- *                                          accept a signal and want to
- *                                          add a wall-clock deadline.
- *   sleep(ms, opts?)                       promise that resolves after ms;
- *                                          opts.signal aborts mid-sleep,
- *                                          timer is unref'd so a pending
- *                                          sleep doesn't keep the process
- *                                          alive
- *   safeAwait(promise)                     [error, value] never throws
- *
- *   Mutex                                  class; .runExclusive(fn)
- *   Semaphore(limit)                       class; .runWith(fn)
- *   Once(fn)                               class; .invoke()
- *
- *   asyncRetry(fn, opts?)                  re-export from object-store-retry
- *   CircuitBreaker(name, opts?)            re-export from object-store-retry
- *
- *   SafeAsyncError                         error class
- *
- * Best-practice notes for callers:
- *
- *   - Always pair `withTimeout` with the external-db / network calls
- *     where operator-supplied drivers might hang. The framework's
- *     external-db wrapper already retries; timeout puts a ceiling on
- *     each individual attempt.
- *
- *   - Wrap chain-writes with Mutex.runExclusive. Audit chain hashing
- *     reads the previous tip and writes a successor; without
- *     serialization, concurrent awaiting record() calls can hash
- *     against the same prev-tip and produce a forked chain. Mutex
- *     prevents this in single-process; for cross-process coordination
- *     the cluster module's leader election is the correct primitive.
- *
- *   - Use Once for boot-time lazy init (counter primer, schema
- *     check). Multiple concurrent first-callers correctly all wait
- *     on the same in-flight init Promise rather than each starting
- *     their own.
- *
- *   - Use safeAwait for fire-and-forget paths (audit hooks in
- *     middleware) that previously used try/catch — preserves the
- *     "log + continue" pattern without unhandled-rejection warnings.
- *
- *   - Prefer Promise.allSettled over Promise.all when partial failure
- *     is acceptable (e.g. emitting to multiple log sinks; one sink
- *     down shouldn't block the others). The framework's log-stream
- *     dispatcher already does this.
+ * @module b.safeAsync
+ * @nav    Validation
+ * @title  Safe Async
+ *
+ * @intro
+ *   Timeout-bounded promises, AbortSignal-aware coordination,
+ *   Promise.race-shaped helpers, and settled-state queries for the
+ *   framework's async surfaces (external-db queries, cluster
+ *   coordination, queue operations, audit chain writes).
+ *
+ *   Hazards this module addresses: races between interleaved awaits,
+ *   unbounded retries masking real failures, hangs from unresponsive
+ *   backends, and partial results from operator-supplied drivers.
+ *
+ *   Surface:
+ *     - Async coordination: withTimeout, withSignal, withTimeoutSignal,
+ *       sleep, repeating, flushLoop, safeAwait, parallel, asyncRetry
+ *     - Async state objects: Mutex, Semaphore, Once, CircuitBreaker
+ *     - Sync helpers used by async pipelines: safeInvoke (callback
+ *       wrapper with optional onError), makeDropCallback (factory for
+ *       log-stream-style onDrop callbacks), makeScheduledFlush
+ *       (idempotent setTimeout coalesce-and-flush helper)
+ *
+ *   Design posture:
+ *     - AbortSignal everywhere. Every time-bounded primitive accepts
+ *       an AbortSignal and aborts cleanly when it fires.
+ *     - Error.cause preserved. Wrapper errors set `.cause` to the
+ *       original failure so debugging traces back to the root.
+ *     - No leaked Promises. Mutex / Semaphore release on path-out
+ *       in finally blocks — even on cancellation.
+ *     - Bounded by default. Semaphore / parallel have explicit limits
+ *       and reject over-the-limit acquisitions rather than growing
+ *       unboundedly.
+ *     - Fail loud. Errors propagate; primitives never silently
+ *       swallow. safeAwait is the opt-in `{error, value}` tuple form
+ *       for callers that want to log-and-continue.
+ *
+ *   Best-practice notes for callers:
+ *     - Pair `withTimeout` with external-db / network calls where
+ *       operator-supplied drivers might hang. Puts a ceiling on each
+ *       individual attempt.
+ *     - Wrap chain-writes with `Mutex.runExclusive`. Audit chain
+ *       hashing reads the previous tip and writes a successor; without
+ *       serialization, concurrent record() calls can hash against the
+ *       same prev-tip and fork the chain.
+ *     - Use `Once` for boot-time lazy init (counter primer, schema
+ *       check). Multiple concurrent first-callers correctly wait on
+ *       the same in-flight init Promise.
+ *     - Use `safeAwait` for fire-and-forget paths (audit hooks in
+ *       middleware) — preserves "log + continue" without unhandled-
+ *       rejection warnings.
+ *     - Prefer Promise.allSettled over Promise.all when partial
+ *       failure is acceptable (multiple log sinks; one down shouldn't
+ *       block the others).
+ *
+ * @card
+ *   Timeout-bounded promises, AbortSignal-aware coordination, Promise.race-shaped helpers, and settled-state queries for the framework's async surfaces (external-db queries, cluster coordination, queue operations, audit chain writes).
  */
 
 var { FrameworkError } = require("./framework-error");
@@ -119,6 +82,41 @@ class SafeAsyncError extends FrameworkError {
 //              with code=async/aborted.
 // opts.name:   diagnostic label included in the timeout message.
 
+/**
+ * @primitive b.safeAsync.withTimeout
+ * @signature b.safeAsync.withTimeout(promise, ms, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeAsync.withSignal, b.safeAsync.withTimeoutSignal, b.safeAsync.sleep
+ *
+ * Race a Promise against a wall-clock deadline. On timeout the
+ * wrapper rejects with `SafeAsyncError` (`.code = "async/timeout"`);
+ * the underlying Promise keeps running in the background since the
+ * framework cannot cancel an arbitrary async operation. Pair with
+ * AbortSignal-aware I/O when the caller also wants the work itself
+ * to stop. `opts.signal` aborts the wrapper with
+ * `.code = "async/aborted"`; `opts.name` is included in the timeout
+ * message for diagnostics.
+ *
+ * @opts
+ *   signal: AbortSignal,  // aborts the wrapper with async/aborted
+ *   name:   string,       // diagnostic label baked into error messages
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Bound an HTTP call to 5s.
+ *   var fetchUser = Promise.resolve({ id: 42, name: "alice" });
+ *   var user = await b.safeAsync.withTimeout(fetchUser, 5000, { name: "fetchUser" });
+ *   user.id;
+ *   // → 42
+ *
+ *   // Timeout surfaces as SafeAsyncError(async/timeout).
+ *   var hang = new Promise(function () {});
+ *   try { await b.safeAsync.withTimeout(hang, 10, { name: "stuck" }); }
+ *   catch (e) { e.code; }
+ *   // → "async/timeout"
+ */
 function withTimeout(promise, ms, opts) {
   opts = opts || {};
   if (typeof ms !== "number" || ms <= 0 || !Number.isFinite(ms)) {
@@ -176,6 +174,32 @@ function withTimeout(promise, ms, opts) {
 // running in the background; only the wrapper's resolution is short-
 // circuited. Useful for plumbing a single signal through a chain of awaits.
 
+/**
+ * @primitive b.safeAsync.withSignal
+ * @signature b.safeAsync.withSignal(promise, signal)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeAsync.withTimeout, b.safeAsync.withTimeoutSignal
+ *
+ * Race a Promise against an AbortSignal. When the signal aborts the
+ * wrapper rejects with `SafeAsyncError` (`.code = "async/aborted"`,
+ * `.cause = signal.reason`). The underlying Promise continues
+ * running in the background — only the wrapper's resolution is
+ * short-circuited. Useful for plumbing one signal through a chain
+ * of awaits where some intermediates aren't signal-aware.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Propagate an AbortSignal through a non-signal-aware Promise.
+ *   var ctrl = new AbortController();
+ *   var slow = new Promise(function (resolve) { setTimeout(resolve, 50, "done"); });
+ *   var wrapped = b.safeAsync.withSignal(slow, ctrl.signal);
+ *   ctrl.abort();
+ *   try { await wrapped; }
+ *   catch (e) { e.code; }
+ *   // → "async/aborted"
+ */
 function withSignal(promise, signal) {
   if (!signal) return Promise.resolve(promise);
   return new Promise(function (resolve, reject) {
@@ -222,6 +246,40 @@ function withSignal(promise, signal) {
 // ms <= 0 resolves immediately (matches setTimeout's clamp-to-1ms but
 // without the wasted tick). Non-finite ms rejects.
 
+/**
+ * @primitive b.safeAsync.sleep
+ * @signature b.safeAsync.sleep(ms, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeAsync.withTimeout, b.safeAsync.repeating
+ *
+ * Promise that resolves after `ms` milliseconds. `opts.signal`
+ * aborts the sleep cleanly — the wrapper rejects with
+ * `SafeAsyncError` (`.code = "async/aborted"`). `opts.unref` flips
+ * the timer to non-process-holding (default `false`, so
+ * `await sleep(ms)` reads naturally as "I'm waiting, this IS my
+ * work"). `ms <= 0` resolves immediately; non-finite `ms` rejects.
+ *
+ * @opts
+ *   signal: AbortSignal,  // aborts mid-sleep with async/aborted
+ *   unref:  boolean,      // default false; true to not keep the process alive
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Backoff between retries.
+ *   var t0 = Date.now();
+ *   await b.safeAsync.sleep(20);
+ *   (Date.now() - t0) >= 18;
+ *   // → true
+ *
+ *   // Abort mid-sleep — propagates as SafeAsyncError(async/aborted).
+ *   var ctrl = new AbortController();
+ *   setTimeout(function () { ctrl.abort(); }, 5);
+ *   try { await b.safeAsync.sleep(1000, { signal: ctrl.signal }); }
+ *   catch (e) { e.code; }
+ *   // → "async/aborted"
+ */
 function sleep(ms, opts) {
   if (typeof ms !== "number" || !Number.isFinite(ms)) {
     return Promise.reject(new SafeAsyncError(
@@ -279,6 +337,35 @@ function sleep(ms, opts) {
 // the result straight to APIs that treat null as "no abort" (the http
 // `signal` option does), with no special-case branching needed.
 
+/**
+ * @primitive b.safeAsync.withTimeoutSignal
+ * @signature b.safeAsync.withTimeoutSignal(signal, ms)
+ * @since     0.7.4
+ * @status    stable
+ * @related   b.safeAsync.withTimeout, b.safeAsync.withSignal
+ *
+ * Compose an existing AbortSignal with a fresh wall-clock timeout.
+ * Returns an AbortSignal that fires when EITHER the input signal
+ * aborts OR `ms` milliseconds elapse — exactly the shape I/O
+ * primitives like `fetch({ signal })` already accept. Edge cases:
+ * neither argument supplied returns `null` (a naturally falsy "no
+ * signal needed" value most signal-accepting APIs treat as no-op);
+ * only `signal` returns it unchanged; only `ms` returns
+ * `AbortSignal.timeout(ms)`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Add a 5s deadline on top of the user's existing AbortSignal.
+ *   var userCtrl = new AbortController();
+ *   var sig = b.safeAsync.withTimeoutSignal(userCtrl.signal, 5000);
+ *   sig instanceof AbortSignal;
+ *   // → true
+ *
+ *   // No user signal + no timeout returns null (no-abort sentinel).
+ *   b.safeAsync.withTimeoutSignal(null, 0);
+ *   // → null
+ */
 function withTimeoutSignal(signal, ms) {
   var hasTimeout = typeof ms === "number" && ms > 0 && Number.isFinite(ms);
   if (!signal && !hasTimeout) return null;
@@ -296,6 +383,46 @@ function withTimeoutSignal(signal, ms) {
 //   var [err, value] = await safeAwait(somePromise);
 //   if (err) { /* log + continue */ }
 
+/**
+ * @primitive b.safeAsync.safeAwait
+ * @signature b.safeAsync.safeAwait(promise)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeAsync.withTimeout, b.safeAsync.parallel
+ *
+ * Go-style `[error, value]` tuple wrapper. Never throws — a rejected
+ * Promise becomes `[error, null]`, a resolved Promise becomes
+ * `[null, value]`. Replaces try/catch scaffolding around
+ * fire-and-forget paths (audit hooks in middleware, optional
+ * lookups) where the caller wants to log-and-continue without
+ * unhandled-rejection warnings. For settled-state inspection of
+ * many concurrent Promises the standard `Promise.allSettled` pairs
+ * naturally with this idiom.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Resolved Promise → [null, value].
+ *   var ok = await b.safeAsync.safeAwait(Promise.resolve(42));
+ *   ok[0];
+ *   // → null
+ *   ok[1];
+ *   // → 42
+ *
+ *   // Rejected Promise → [error, null].
+ *   var bad = await b.safeAsync.safeAwait(Promise.reject(new Error("nope")));
+ *   bad[0].message;
+ *   // → "nope"
+ *
+ *   // Pair with Promise.allSettled for bulk settled-state inspection.
+ *   var results = await Promise.all([
+ *     b.safeAsync.safeAwait(Promise.resolve("a")),
+ *     b.safeAsync.safeAwait(Promise.reject(new Error("b-failed"))),
+ *     b.safeAsync.safeAwait(Promise.resolve("c")),
+ *   ]);
+ *   results.filter(function (r) { return r[0] === null; }).length;
+ *   // → 2
+ */
 async function safeAwait(promise) {
   try {
     var v = await promise;
@@ -314,6 +441,40 @@ async function safeAwait(promise) {
 //
 //   safeInvoke(opts.onDrop, { reason: "buffer-full", batch: rows },
 //              function (e) { log.warn("onDrop threw: " + e.message); });
+/**
+ * @primitive b.safeAsync.safeInvoke
+ * @signature b.safeAsync.safeInvoke(callback, payload, onError)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.safeAsync.makeDropCallback
+ *
+ * Drop-silent operator-callback invoker. Calls `callback(payload)`
+ * if `callback` is a function, routes any throw to `onError(e)` if
+ * supplied, and silently swallows nested throws from `onError`
+ * itself. Used by every drop-callback / completion-callback /
+ * failure-callback site in the framework so a buggy operator
+ * callback can never crash the request that triggered the audit
+ * hook. Hot-path observability sink — drop-silent by design.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Happy path: callback runs with the payload.
+ *   var seen = null;
+ *   b.safeAsync.safeInvoke(function (p) { seen = p; }, { reason: "buffer-full", batch: [1, 2] });
+ *   seen.reason;
+ *   // → "buffer-full"
+ *
+ *   // Throw routed to onError; original caller never sees it.
+ *   var caught = null;
+ *   b.safeAsync.safeInvoke(
+ *     function () { throw new Error("boom"); },
+ *     { batch: [] },
+ *     function (e) { caught = e.message; }
+ *   );
+ *   caught;
+ *   // → "boom"
+ */
 function safeInvoke(callback, payload, onError) {
   if (typeof callback !== "function") return;
   try { callback(payload); }
@@ -334,6 +495,35 @@ function safeInvoke(callback, payload, onError) {
 //   var _emitDrop = safeAsync.makeDropCallback(onDrop,
 //     function (e) { log.warn("onDrop-callback-failed: " + e.message); });
 //   _emitDrop("buffer-full", batch, err);
+/**
+ * @primitive b.safeAsync.makeDropCallback
+ * @signature b.safeAsync.makeDropCallback(onDrop, onError)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.safeAsync.safeInvoke, b.safeAsync.makeScheduledFlush
+ *
+ * Factory for the canonical log-stream-sink onDrop wrapper. Returns
+ * a closure `(reason, batch, err) => void` that calls `onDrop` with
+ * the framework-canonical payload shape `{ reason, batch, error }`,
+ * routing any throw from the operator callback to `onError`. Every
+ * sink (cloudwatch / otlp-grpc / otlp-http / syslog / webhook)
+ * previously rolled its own three-line `_emitDrop` wrapper — this
+ * factory removes that duplication.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var dropped = [];
+ *   var emit = b.safeAsync.makeDropCallback(
+ *     function (info) { dropped.push(info); },
+ *     function (e) { console.warn("onDrop threw: " + e.message); }
+ *   );
+ *   emit("buffer-full", [{ id: 1 }], new Error("queue overflow"));
+ *   dropped[0].reason;
+ *   // → "buffer-full"
+ *   dropped[0].error.message;
+ *   // → "queue overflow"
+ */
 function makeDropCallback(onDrop, onError) {
   return function (reason, batch, err) {
     safeInvoke(onDrop, { reason: reason, batch: batch, error: err || null }, onError);
@@ -355,6 +545,37 @@ function makeDropCallback(onDrop, onError) {
 // Returns { schedule, cancel, isPending }. flushFn may be sync or
 // async — async rejections are swallowed (best-effort sink — operators
 // see drops via onDrop, not via a sea of unhandled promise rejections).
+/**
+ * @primitive b.safeAsync.makeScheduledFlush
+ * @signature b.safeAsync.makeScheduledFlush(delayMs, flushFn)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.safeAsync.flushLoop, b.safeAsync.makeDropCallback
+ *
+ * Idempotent setTimeout coalesce-and-flush scheduler used by every
+ * log-stream sink to batch buffered writes. Returns
+ * `{ schedule, cancel, isPending }` — calling `schedule()` repeatedly
+ * within `delayMs` collapses to a single deferred `flushFn()` call.
+ * The timer is unref'd so a pending flush never keeps the process
+ * alive; async rejections from `flushFn` are swallowed (best-effort
+ * sink — operators see drops via the sink's own onDrop). Throws
+ * `TypeError` on bad arguments at construction time.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Coalesce many schedule() calls into one flush after delayMs.
+ *   var flushed = 0;
+ *   var sched = b.safeAsync.makeScheduledFlush(20, function () { flushed += 1; });
+ *   sched.schedule();
+ *   sched.schedule();
+ *   sched.schedule();
+ *   sched.isPending();
+ *   // → true
+ *   await b.safeAsync.sleep(40);
+ *   flushed;
+ *   // → 1
+ */
 function makeScheduledFlush(delayMs, flushFn) {
   if (typeof delayMs !== "number" || !isFinite(delayMs) || delayMs < 0) {
     throw new TypeError("safeAsync.makeScheduledFlush: delayMs must be a non-negative finite number");
@@ -384,6 +605,163 @@ function makeScheduledFlush(delayMs, flushFn) {
   };
 }
 
+// ---- parallel ----
+//
+// Bounded-concurrency mapAsync. Runs `fn(item, index)` over `items`
+// with at most opts.concurrency in-flight at once; resolves with
+// results in input order (NOT completion order). The first rejection
+// from any `fn` invocation is propagated (other in-flight calls finish
+// in the background; the wrapper does not cancel them — operator-
+// supplied promises may not be signal-aware).
+//
+//   var results = await b.safeAsync.parallel(urls, fetchOne, {
+//     concurrency: 16,
+//     signal:      controller.signal,
+//   });
+//
+// Worker-loop pattern: a fixed pool of `concurrency` workers each pull
+// the next available index from a shared cursor. Avoids the
+// Promise.all-batched-chunks pitfall where the next batch can't start
+// until the slowest item in the current batch finishes (long-pole
+// stragglers leave workers idle). See feedback_lpt_scheduling_for_
+// parallel_tests.md — same shape applied to operator workloads.
+//
+// opts.concurrency: 1..256 (default 8). Throws at config time on
+// out-of-range so operator typos surface immediately.
+// opts.signal:      AbortSignal — cancels by refusing to dispatch
+//                   further items; in-flight promises run to settle.
+
+var PARALLEL_DEFAULT_CONCURRENCY = 8;                                              // allow:raw-byte-literal — worker pool count, not bytes
+var PARALLEL_MAX_CONCURRENCY = 256;                                                // allow:raw-byte-literal — worker pool ceiling, not bytes
+
+/**
+ * @primitive b.safeAsync.parallel
+ * @signature b.safeAsync.parallel(items, fn, opts?)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.safeAsync.safeAwait, b.safeAsync.withTimeout
+ *
+ * Bounded-concurrency `mapAsync`. Runs `fn(item, index)` over `items`
+ * with at most `opts.concurrency` in-flight at a time and resolves
+ * with results in INPUT order (not completion order). Worker-loop
+ * scheduling: a fixed pool of workers each pull the next index from
+ * a shared cursor as soon as their previous task settles — avoids
+ * the Promise.all-batched-chunks pitfall where a long-pole straggler
+ * leaves workers idle. The first rejection is propagated;
+ * still-in-flight calls finish in the background (operator-supplied
+ * promises may not be signal-aware). `opts.concurrency` validates at
+ * config time (1..256, default 8) and throws on out-of-range so
+ * typos surface immediately.
+ *
+ * @opts
+ *   concurrency: number,        // 1..256; default 8
+ *   signal:      AbortSignal,   // refuses to dispatch further items; in-flight run to settle
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var urls = ["a", "b", "c", "d"];
+ *   var fetchOne = function (u) { return Promise.resolve("loaded:" + u); };
+ *   var results = await b.safeAsync.parallel(urls, fetchOne, { concurrency: 2 });
+ *   results;
+ *   // → ["loaded:a", "loaded:b", "loaded:c", "loaded:d"]
+ *
+ *   // First rejection wins; remaining workers drain.
+ *   try {
+ *     await b.safeAsync.parallel([1, 2, 3], function (n) {
+ *       if (n === 2) return Promise.reject(new Error("bad-2"));
+ *       return Promise.resolve(n);
+ *     }, { concurrency: 1 });
+ *   } catch (e) {
+ *     e.message;
+ *     // → "bad-2"
+ *   }
+ */
+function parallel(items, fn, opts) {
+  if (!Array.isArray(items)) {
+    throw new SafeAsyncError("parallel: items must be an array", "async/bad-arg");
+  }
+  if (typeof fn !== "function") {
+    throw new SafeAsyncError("parallel: fn must be a function", "async/bad-arg");
+  }
+  opts = opts || {};
+  var concurrency = opts.concurrency != null ? opts.concurrency : PARALLEL_DEFAULT_CONCURRENCY;
+  if (typeof concurrency !== "number" || !Number.isInteger(concurrency) ||
+      concurrency < 1 || concurrency > PARALLEL_MAX_CONCURRENCY) {
+    throw new SafeAsyncError(
+      "parallel: concurrency must be an integer in [1.." +
+      PARALLEL_MAX_CONCURRENCY + "], got " + concurrency,
+      "async/bad-arg"
+    );
+  }
+  var signal = opts.signal;
+  if (signal && signal.aborted) {
+    return Promise.reject(new SafeAsyncError(
+      "parallel aborted before start", "async/aborted", signal.reason
+    ));
+  }
+  if (items.length === 0) return Promise.resolve([]);
+
+  return new Promise(function (resolve, reject) {
+    var results = new Array(items.length);
+    var cursor = 0;
+    var settled = false;
+    var firstError = null;
+    var activeWorkers = 0;
+    var workerCount = Math.min(concurrency, items.length);
+    var onAbort = null;
+
+    function _finish(err) {
+      if (settled) return;
+      settled = true;
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+      if (err) reject(err); else resolve(results);
+    }
+
+    if (signal) {
+      onAbort = function () {
+        if (firstError) return;
+        firstError = new SafeAsyncError(
+          "parallel aborted", "async/aborted", signal.reason
+        );
+        // In-flight workers finish their current item; new pulls
+        // observe firstError and exit. _finish fires when the last
+        // worker drains.
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    function _workerLoop() {
+      // Continuous worker queue — each worker pulls the next index
+      // from the shared cursor as soon as its previous task settles.
+      // No batched chunks: a slow item never blocks unrelated items
+      // from entering the pool.
+      if (firstError || cursor >= items.length) {
+        activeWorkers -= 1;
+        if (activeWorkers === 0) _finish(firstError);
+        return;
+      }
+      var idx = cursor++;
+      var item = items[idx];
+      var p;
+      try { p = Promise.resolve(fn(item, idx)); }
+      catch (e) { p = Promise.reject(e); }
+      p.then(function (value) {
+        results[idx] = value;
+        _workerLoop();
+      }, function (e) {
+        if (!firstError) firstError = e;
+        _workerLoop();
+      });
+    }
+
+    for (var i = 0; i < workerCount; i++) {
+      activeWorkers += 1;
+      _workerLoop();
+    }
+  });
+}
+
 // ---- Mutex ----
 //
 // Async mutex — only one async region holds the lock at a time. Acquirers
@@ -606,6 +984,43 @@ class Once {
 // that should NOT keep the process alive. Cluster heartbeat etc. set
 // `unref: false` so the lease keeps the leader from exiting silently.
 
+/**
+ * @primitive b.safeAsync.repeating
+ * @signature b.safeAsync.repeating(fn, intervalMs, opts?)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.safeAsync.flushLoop, b.safeAsync.sleep
+ *
+ * Bounded-cadence interval timer with consistent unref + cancel
+ * semantics. Replaces the scattered `setInterval` ceremony where
+ * each caller hand-rolled `t.unref()` and a corresponding
+ * `clearInterval` in shutdown. `fn` may be sync or async; if async,
+ * the next tick fires `intervalMs` after the prior fn() STARTED
+ * (fixed-rate, matching `setInterval`). Promise rejections are
+ * captured by `opts.onError` if provided, otherwise silently
+ * dropped — a repeating timer is fire-and-forget by definition and
+ * an unhandled rejection here would crash the process. `opts.unref`
+ * defaults `true`; set `false` for cluster heartbeat-style timers
+ * that must hold the loop open. Returns `{ stop }`.
+ *
+ * @opts
+ *   unref:   boolean,           // default true
+ *   onError: function(error),   // captures sync throws + Promise rejections
+ *   name:    string,            // diagnostic label
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var ticks = 0;
+ *   var sweep = b.safeAsync.repeating(function () { ticks += 1; }, 10, {
+ *     unref: true,
+ *     name:  "tick-counter",
+ *   });
+ *   await b.safeAsync.sleep(35);
+ *   sweep.stop();
+ *   ticks >= 2;
+ *   // → true
+ */
 function repeating(fn, intervalMs, opts) {
   if (typeof fn !== "function") {
     throw new SafeAsyncError("repeating: fn must be a function", "async/bad-arg");
@@ -661,6 +1076,39 @@ function repeating(fn, intervalMs, opts) {
 // (the operator's b.appShutdown drives the final drain explicitly).
 // onError catches rejections; without one, they're silently dropped.
 
+/**
+ * @primitive b.safeAsync.flushLoop
+ * @signature b.safeAsync.flushLoop(fn, intervalMs, opts?)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.safeAsync.repeating, b.safeAsync.makeScheduledFlush
+ *
+ * After-completion background flusher. Schedules `fn()`, awaits its
+ * settle (resolve OR reject), then schedules the next call
+ * `intervalMs` later. Differs from `repeating` (fixed-rate, no
+ * overlap protection) — `flushLoop` is the right shape for
+ * background flushers that must never overlap two flushes and
+ * shouldn't accumulate backlog when one flush is slow. Always
+ * unref'd; `opts.onError` catches rejections, otherwise they're
+ * silently dropped. Returns `{ stop }`.
+ *
+ * @opts
+ *   onError: function(error),   // captures sync throws + Promise rejections
+ *   name:    string,            // diagnostic label
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   var flushes = 0;
+ *   var loop = b.safeAsync.flushLoop(function () {
+ *     flushes += 1;
+ *     return Promise.resolve();
+ *   }, 10, { name: "telemetry-flush" });
+ *   await b.safeAsync.sleep(35);
+ *   loop.stop();
+ *   flushes >= 1;
+ *   // → true
+ */
 function flushLoop(fn, intervalMs, opts) {
   if (typeof fn !== "function") {
     throw new SafeAsyncError("flushLoop: fn must be a function", "async/bad-arg");
@@ -726,6 +1174,7 @@ module.exports = {
   safeInvoke:         safeInvoke,
   makeDropCallback:   makeDropCallback,
   makeScheduledFlush: makeScheduledFlush,
+  parallel:           parallel,
   Mutex:              Mutex,
   Semaphore:          Semaphore,
   Once:               Once,