@blamejs/core 0.9.41 → 0.9.43

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.43 (2026-05-15) — **Three downstream-consumer DX primitives bundled: `b.testHarness.start` + `b.middleware.composePipeline` + `b.watcher` `mode: "auto"`.** Closes the second batch of operator-friction gaps. (1) **`b.testHarness.start(opts?)`** — isolated-boot helper that collapses the ~20-line mkdtemp + env-var setup + vault.init + teardown pattern every consumer was reinventing in `tests/helpers/`. Returns a handle exposing `{ dataDir, dbPath, vaultDir, env, stop() }`. Generates a mkdtemp-based isolated dataDir under `os.tmpdir()` with `b.crypto.generateToken(4)` random suffix, sets `<prefix>_DATA_DIR` / `_DB_PATH` / `_VAULT_DIR` env vars, optionally awaits `b.vault.init` in plaintext mode. Concurrent harnesses with `initVault: true` share the process-global vault state via internal reference counting; the last `stop()` releases vault. (2) **`b.middleware.composePipeline(entries, opts?)`** — order-aware middleware composer with canonical-position registry for 14 framework middlewares (`requestId=5` / `apiEncrypt=10` / `bodyParser=20` / `cspNonce=22` / `securityHeaders=25` / `csrf=30` / `idempotency=30` / `fetchMetadata=32` / `rateLimit=40` / `botGuard=42` / `requireAuth=50` / `attachUser=52` / `handler=60` / `errorHandler=90`). Conflict detection at registration time refuses duplicate names, duplicate explicit-position values, and non-monotonic positions. Strict mode (`opts.strict: true`) refuses canonical-name position mismatches; default `false` runs but emits `system.middleware.compose.canonical_mismatch` audit. Sync throws inside middleware propagate to `finalNext`. Boot-time `system.middleware.compose.pipeline_built` audit lists final ordered entries. (3) **`b.watcher.create({ root, mode: "auto", ... })`** — Docker bind-mount / non-inotify-fs auto-fallback. Inside a Linux container with a host bind-mount, `fs.watch` returns no events across gRPC-FUSE / VirtioFS / 9p / NFS / CIFS / vboxsf boundaries; `mode: "auto"` reads `/proc/self/mountinfo`, finds the mount carrying the watcher root, and falls back to `mode: "poll"` when the fstype is non-inotify OR when `/.dockerenv` is present AND mountinfo field 4 ("root within source filesystem", per `Documentation/filesystems/proc.rst §3.5`) is `!= "/"` (bind-mount signature — the kernel exposes the bound source path in this field; regular mounts always carry `/`). Native Linux mounts + non-Linux hosts (FSEvents / ReadDirectoryChangesW) keep `mode: "fs"`. The chosen backend + reason emits as `watcher.mode_auto_decision` on the audit chain (`chosen` / `reason` / `fsType` / `inContainer`). `mode: "fs"` (default) and `mode: "poll"` (explicit) unchanged; `mode: "auto"` is opt-in.
+- v0.9.42 (2026-05-15) — **`b.middleware.idempotencyKey` `bodyFingerprint` hook + misordered-mount detector.** New `opts.bodyFingerprint: (req) => Buffer|string|object|null` lets operators supply a custom body extractor instead of relying on the default `req._rawBody || req.body` lookup; useful when the parsed-body shape needs canonicalization (sorted keys, stripped metadata) before the fingerprint hash so retry-with-equivalent-payload doesn't trip the §4.3 same-key-different-body refusal. Hook return is normalized to Buffer (Buffer passthrough; string → UTF-8 bytes; object/array → `JSON.stringify` → bytes; null/undefined → empty fingerprint). Throws inside the hook emit `idempotency.body_fingerprint_failed` audit (warning) and treat the body as empty. **Mount-order constraint:** idempotency must run AFTER body-parser; the hook reads request state at the moment idempotency executes, so a misordered mount silently degrades the fingerprint to method+path. `b.middleware.composePipeline` (v0.9.44) places bodyParser=20 / idempotency=30 by default. Body-bearing methods (POST/PUT/PATCH) that arrive without parsed-body OR raw-body data now emit `idempotency.empty_body_fingerprint` audit (warning) carrying `hasRawBody` / `hasParsedBody` / `hasFingerprintHook` so a misconfigured pipeline is detectable from audit logs.
 - v0.9.41 (2026-05-15) — **Operator-friction ergonomic helpers surfaced from downstream-consumer gap audit.** Three small additive surfaces, no behavior change for existing callers. (1) **`b.storage.listBackends()`** now surfaces `rootDir` for local-protocol backends, sourced from the live backend (with config-reload propagation) so downstream path-traversal guards + scratch-dir derivation read the canonical path directly from the framework instead of re-deriving from operator-supplied opts. Remote protocols (sigv4 / gcs / azure-blob / http-put) don't carry a rootDir; the field stays absent for those. (2) **`b.problemDetails.send(res, fields)`** — bare wire-shape emit shortcut that lets routes migrate incrementally from inline `res.status(400).json({ error: ... })` to RFC 9457 problem-details without restructuring the handler around an error throw. Equivalent to `respond(res, create(fields))` in one call; same `application/problem+json` content type + `Cache-Control: no-store`. (3) **`b.mail.send` CR/LF/NUL refusal** confirmed already in place at `lib/mail.js:275` / `:309` / `:1808` per RFC 5321 §2.3.8 + RFC 5322 §3.2.5 header-injection defense — operators with inline `validateEmailAddr` wrappers can retire them. No new API, just confirmation that the existing primitive already covers the wire-protocol injection class (CVE-2026-32178 .NET System.Net.Mail header injection defended at the framework boundary).
 - v0.9.40 (2026-05-15) — **`b.guardListId` — RFC 2919 List-Id header validator.** Companion to v0.9.39 `b.guardListUnsubscribe`; gates outbound mailing-list mail so the List-Id carries a well-formed identifier downstream filters + bulk-sender pipelines reliably route on. (1) **`b.guardListId.validate(headerValue, opts?)`** — parses bracketed (`<my-list.example.com>`), phrase-prefixed (`My Newsletter <my-list.example.com>`), and bare-identifier forms per RFC 2919 §2. Returns `{ action, listId, label, namespace, phrase, reason }`. Action one of `accept` / `refuse`. (2) **RFC 2919 §3 caps + ABNF** — list-id capped at 255 octets; header value capped at RFC 5322 §2.1.1 line cap (998 bytes); per-label shape per RFC 5322 §3.2.3 dot-atom-text. (3) **Phrase-smuggling defense** — phrase MUST NOT contain `<` / `>` (would smuggle a second bracketed identifier through the parser). Trailing content after `>` refused. Nested or unmatched brackets refused. (4) **CRLF / NUL / C0 / DEL refusal** — header-injection defense per RFC 5322 §3.2.5 + CVE-2026-32178 wire-protocol surface class. (5) **`localhost` namespace handling** (RFC 2919 §3) — strict requires the recommended 32-hex random component in the label (the SHOULD becomes operator-strict for HIPAA / PCI / GDPR / SOC2 postures); balanced / permissive accept without. (6) **FQDN namespace enforcement** under strict / balanced — list-id with single-label namespace (e.g. `mylist.test`) refused unless permissive. (7) Heuristic label / namespace split — last 2 dot-segments → namespace (matches typical DNS delegation); consumers needing PSL-accurate org-domain extraction compose `b.publicSuffix.organizationalDomain`. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-list-id.fuzz.js`. Registered as standalone guard with `KIND="list-id"`. Threat-model: List-Id forging (RFC 2919 §8 explicitly notes the identifier is NOT an authentication signal; operators wanting authentication compose b.mail.auth.dmarc / arc.verify), bulk-sender bucket-drop (Gmail 2024 keys on List-Id presence for Precedence: list / 5000+ daily-send mail).
 - v0.9.39 (2026-05-15) — **`b.guardListUnsubscribe` — RFC 2369 + RFC 8058 List-Unsubscribe / List-Unsubscribe-Post validator.** Gates the outbound submission path so messages carrying a List-Id (or any mailing-list shape) emit headers Gmail / Yahoo / Outlook one-click unsubscribe machinery actually accepts. (1) **`b.guardListUnsubscribe.validate({ listUnsubscribe, listUnsubscribePost }, opts?)`** — returns `{ action, reason, uris, hasHttpsUri, hasMailtoUri, postHeaderOk, oneClickReady }`. (2) **Gmail / Yahoo bulk-sender 2024 enforcement** — under strict requires at least one `https://` URI in the header (mailto: alone refused) + the paired `List-Unsubscribe-Post: List-Unsubscribe=One-Click` value EXACTLY (case-sensitive — Gmail silently fails one-click on mixed-case variants). (3) **Always-refused schemes** — `javascript:` / `data:` / `file:` / `vbscript:` / `blob:` refused regardless of profile (XSS / file-read class in mail-client rendering). (4) **`http://` refused under strict / balanced** — one-click endpoint MUST be TLS per RFC 8058 §2. Permissive accepts http for audit-only legacy use. (5) **Header-injection defense** — CRLF, NUL, C0 controls, DEL refused at validate time (RFC 5322 §3.2.5). (6) **Bounded surface** — per-URI byte cap (2 KiB strict / 4 KiB permissive), URI-count cap (4 / 8 / 16), header total byte cap (4 / 4 / 8 KiB). RFC 3986 §3.1 scheme shape; RFC 2369 §3.1 angle-bracket URI list. HTTPS URIs validated through `b.safeUrl.parse` with the framework's HTTPS allowlist. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-list-unsubscribe.fuzz.js`. Registered as a standalone guard with KIND="list-unsubscribe". Threat-model coverage: unsubscribe-link injection via AI-generated newsletter templates, open-redirect via List-Unsubscribe (operator validates target host downstream via own safeRedirect allowlist), mail-client mishandling (Outlook's mailto: auto-fetch history).

package/index.js

@@ -147,6 +147,7 @@ var compliance = Object.assign({}, require("./lib/compliance"), {
 });
 var dataAct = require("./lib/data-act");
 var problemDetails = require("./lib/problem-details");
+var testHarness = require("./lib/test-harness");
 var cacheStatus = require("./lib/cache-status");
 var cdnCacheControl = require("./lib/cdn-cache-control");
 var clientHints = require("./lib/client-hints");
@@ -417,6 +418,7 @@ module.exports = {
   nistCrosswalk:    nistCrosswalk,
   dataAct:          dataAct,
   problemDetails:   problemDetails,
+  testHarness:      testHarness,
   cacheStatus:      cacheStatus,
   cdnCacheControl:  cdnCacheControl,
   clientHints:      clientHints,

package/lib/middleware/compose-pipeline.js

@@ -0,0 +1,355 @@
+"use strict";
+/**
+ * @module     b.middleware.composePipeline
+ * @nav        Middleware
+ * @title      Compose Pipeline
+ * @order      550
+ *
+ * @intro
+ *   Order-aware middleware composer. Replaces the per-project pattern
+ *   of N separate `app.use(mw)` calls — where mount order silently
+ *   matters (apiEncrypt must precede body-parser; body-parser must
+ *   precede idempotency-key + csrf; csrf must precede require-auth) —
+ *   with a single declarative pipeline that documents the order +
+ *   detects conflicts at registration time.
+ *
+ *   ## What this primitive owns
+ *
+ *   - **Single mount point**: one `app.use(pipeline)` instead of N.
+ *   - **Order documented in code**: the entry array IS the order;
+ *     reading the registration tells the reviewer the canonical
+ *     order without grepping `app.use` calls.
+ *   - **Conflict detection at registration**: duplicate names refused;
+ *     duplicate explicit positions refused; non-monotonic positions
+ *     refused (a later entry with a smaller position is a
+ *     mis-registration).
+ *   - **Canonical-position warnings**: when an entry's `name` matches
+ *     a known framework primitive's recommended position
+ *     (`apiEncrypt` → 10, `bodyParser` → 20, `csrf` → 30,
+ *     `idempotency` → 30, `rateLimit` → 40, `requireAuth` → 50,
+ *     `handler` → 60, `errorHandler` → 90), the composer emits an
+ *     `system.middleware.compose.canonical_mismatch` audit at warning when
+ *     the operator-supplied order deviates. Refusal is opt-in via
+ *     `opts.strict: true`; default is warn-and-continue so operators
+ *     with intentional non-canonical ordering aren't blocked.
+ *
+ *   ## What this primitive does NOT own
+ *
+ *   - **The middlewares themselves** — the composer is a sequencer,
+ *     not a registry. Each middleware retains its own
+ *     `b.middleware.X(opts)` factory + behavior.
+ *   - **Async-context propagation** — async middleware works (the
+ *     composer awaits the previous `next()` via Promise wrap), but
+ *     primitives that need `AsyncLocalStorage` should attach it at
+ *     the middleware itself, not the composer.
+ *   - **Error handling** — the composer dispatches through `next(err)`
+ *     in the standard way; operators register a tail error-handler
+ *     (`name: "errorHandler"`) for the canonical position 90 slot.
+ *
+ *   ## Audit
+ *
+ *   Each composed pipeline is registered at boot time with a unique
+ *   `pipelineId` (sha3-512 of the sorted entry names) and emits a
+ *   `system.middleware.compose.pipeline_built` audit with the entry list
+ *   and canonical-mismatch flags. Per-request dispatch is NOT
+ *   audited (would blow up the audit pipeline volume) — composers
+ *   that need per-request observability compose `b.observability`
+ *   inside their own middleware.
+ *
+ * @card
+ *   Order-aware middleware composer. Single mount point replacing N app.use calls, with conflict detection at registration + canonical-position warnings for framework middlewares. Operator's pipeline order documented in code; the entry array IS the order.
+ */
+
+var bCrypto         = require("../crypto");
+var { defineClass } = require("../framework-error");
+var lazyRequire     = require("../lazy-require");
+var validateOpts    = require("../validate-opts");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var ComposePipelineError = defineClass("ComposePipelineError", { alwaysPermanent: true });
+
+// Canonical positions for framework middlewares. The composer
+// surfaces mismatches as warnings; refusal is opt-in via
+// `opts.strict: true`. Operators with intentional non-canonical
+// ordering aren't blocked.
+//
+// Position groupings (relative — exact numbers can drift, the
+// classes are what matter):
+//   < 10  : request-id, connection-tracking (must be earliest)
+//   10-19 : api-encrypt (must decrypt before any read)
+//   20-29 : body-parser (must precede idempotency, csrf, validation)
+//   30-39 : csrf, idempotency, header policy (need body parsed)
+//   40-49 : rate-limit, bot-guard (after auth context if any)
+//   50-59 : require-auth, ACL (after body + csrf)
+//   60-89 : application handlers
+//   >= 90 : error-handler (must be last; trailing catch)
+var CANONICAL_POSITIONS = Object.freeze({
+  requestId:     5,                                                                                       // allow:raw-byte-literal — canonical position bucket
+  apiEncrypt:    10,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  bodyParser:    20,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  cspNonce:      22,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  securityHeaders: 25,                                                                                    // allow:raw-byte-literal — canonical position bucket
+  csrf:          30,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  idempotency:   30,                                                                                      // allow:raw-byte-literal — canonical position bucket (same as csrf)
+  fetchMetadata: 32,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  rateLimit:     40,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  botGuard:      42,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  requireAuth:   50,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  attachUser:    52,                                                                                      // allow:raw-byte-literal — canonical position bucket
+  handler:       60,                                                                                      // allow:raw-byte-literal — canonical position bucket // allow:raw-time-literal — pipeline position int, not seconds
+  errorHandler:  90,                                                                                      // allow:raw-byte-literal — canonical position bucket
+});
+
+/**
+ * @primitive b.middleware.composePipeline
+ * @signature b.middleware.composePipeline(entries, opts?)
+ * @since     0.9.44
+ * @status    stable
+ * @related   b.middleware.requestId, b.middleware.requireAuth, b.middleware.idempotencyKey
+ *
+ * Compose an ordered middleware pipeline into a single Express-shaped
+ * middleware. Each `entries[i]` is `{ name: string, mw: function,
+ * position?: number }`. Returns the composed `(req, res, next) =>
+ * void` middleware. Throws at registration time on duplicate names,
+ * duplicate positions, non-monotonic positions, or (with strict)
+ * canonical-position mismatches.
+ *
+ * @opts
+ *   strict:  boolean,    // refuse on canonical-position mismatch (default false: warn-and-continue)
+ *   name:    string,     // optional pipeline name for audit
+ *
+ * @example
+ *   var pipeline = b.middleware.composePipeline([
+ *     { name: "apiEncrypt", mw: apiEncryptMw },
+ *     { name: "bodyParser", mw: bodyParserMw },
+ *     { name: "csrf",       mw: csrfMw },
+ *     { name: "idempotency", mw: idempotencyMw, position: 35 },
+ *     { name: "requireAuth", mw: requireAuthMw },
+ *   ]);
+ *   app.use(pipeline);
+ */
+function composePipeline(entries, opts) {
+  opts = opts || {};
+  validateOpts.optionalBoolean(opts.strict, "composePipeline.strict",
+    ComposePipelineError, "compose-pipeline/bad-strict");
+
+  if (!Array.isArray(entries)) {
+    throw new ComposePipelineError("compose-pipeline/bad-entries",
+      "composePipeline: entries must be an array of { name, mw, position? } objects");
+  }
+  if (entries.length === 0) {
+    throw new ComposePipelineError("compose-pipeline/bad-entries",
+      "composePipeline: entries must contain at least one middleware");
+  }
+
+  var seenNames     = Object.create(null);
+  var seenPositions = Object.create(null);
+  var canonicalMismatches = [];
+  var resolved = [];
+
+  for (var i = 0; i < entries.length; i += 1) {
+    var e = entries[i];
+    if (!e || typeof e !== "object") {
+      throw new ComposePipelineError("compose-pipeline/bad-entry",
+        "composePipeline: entry at index " + i + " must be an object");
+    }
+    if (typeof e.name !== "string" || e.name.length === 0 || e.name.length > 64) {                       // allow:raw-byte-literal — middleware-name cap
+      throw new ComposePipelineError("compose-pipeline/bad-entry",
+        "composePipeline: entries[" + i + "].name must be a non-empty string ≤ 64 bytes");
+    }
+    if (typeof e.mw !== "function") {
+      throw new ComposePipelineError("compose-pipeline/bad-entry",
+        "composePipeline: entries[" + i + "].mw must be a function (got " + typeof e.mw + ")");
+    }
+    if (seenNames[e.name]) {
+      throw new ComposePipelineError("compose-pipeline/duplicate-name",
+        "composePipeline: duplicate entry name '" + e.name + "' at index " + i);
+    }
+    seenNames[e.name] = true;
+
+    var position;
+    if (e.position !== undefined) {
+      if (typeof e.position !== "number" || !Number.isFinite(e.position) || e.position < 0) {
+        throw new ComposePipelineError("compose-pipeline/bad-position",
+          "composePipeline: entries[" + i + "].position must be a non-negative finite number");
+      }
+      position = e.position;
+    } else if (Object.prototype.hasOwnProperty.call(CANONICAL_POSITIONS, e.name)) {
+      // Operator-supplied name matches a canonical framework
+      // middleware — use the canonical position by default. Operator
+      // can still override by passing an explicit position.
+      position = CANONICAL_POSITIONS[e.name];
+    } else {
+      // Operator-defined middleware without explicit position —
+      // synthesize a position from the array index times 100 so
+      // operators that don't care about explicit ordering get a
+      // natural sequential flow. Use 100 so canonical positions
+      // (5..90) can interleave without colliding when an operator
+      // mixes named + unnamed entries.
+      position = (i + 1) * 100;                                                                          // allow:raw-byte-literal — index→position scale; canonical-pos ceiling is 90
+    }
+
+    if (Object.prototype.hasOwnProperty.call(seenPositions, position)) {
+      // Same explicit position from two entries — refuse (would make
+      // dispatch order undefined). Two canonical entries CAN land at
+      // the same position (csrf + idempotency are both 30); allowed
+      // only when operator didn't supply an explicit position for
+      // either. Surface this via a less-severe error code so
+      // operators with intentional ties can override with explicit
+      // distinct positions.
+      var prevName = seenPositions[position];
+      var bothExplicit = entries[_findIndex(resolved, prevName)] &&
+                          entries[_findIndex(resolved, prevName)].position !== undefined &&
+                          e.position !== undefined;
+      if (bothExplicit) {
+        throw new ComposePipelineError("compose-pipeline/duplicate-position",
+          "composePipeline: entries[" + i + "].position=" + position +
+          " collides with '" + prevName + "'; supply explicit distinct positions to disambiguate");
+      }
+    }
+    seenPositions[position] = e.name;
+
+    if (resolved.length > 0 && position < resolved[resolved.length - 1].position) {
+      throw new ComposePipelineError("compose-pipeline/non-monotonic",
+        "composePipeline: entries[" + i + "] ('" + e.name + "', position=" + position +
+        ") declared before entries with higher position; entries must be in non-decreasing position order");
+    }
+
+    if (Object.prototype.hasOwnProperty.call(CANONICAL_POSITIONS, e.name) &&
+        e.position !== undefined && e.position !== CANONICAL_POSITIONS[e.name]) {
+      canonicalMismatches.push({
+        name:              e.name,
+        suppliedPosition:  e.position,
+        canonicalPosition: CANONICAL_POSITIONS[e.name],
+      });
+    }
+
+    resolved.push({ name: e.name, mw: e.mw, position: position });
+  }
+
+  if (canonicalMismatches.length > 0) {
+    if (opts.strict === true) {
+      throw new ComposePipelineError("compose-pipeline/canonical-mismatch",
+        "composePipeline: strict=true; " + canonicalMismatches.length +
+        " canonical-position mismatch(es): " +
+        canonicalMismatches.map(function (m) {
+          return m.name + " supplied=" + m.suppliedPosition + " canonical=" + m.canonicalPosition;
+        }).join(", "));
+    }
+    _emitAudit("system.middleware.compose.canonical_mismatch", {
+      pipelineName: opts.name || null,
+      mismatches:   canonicalMismatches,
+    });
+  }
+
+  var pipelineId = bCrypto.namespaceHash("system.middleware.compose.pipeline",
+    resolved.map(function (r) { return r.name; }).join("\n"));
+
+  _emitAudit("system.middleware.compose.pipeline_built", {
+    pipelineId:   pipelineId,
+    pipelineName: opts.name || null,
+    entryCount:   resolved.length,
+    entries:      resolved.map(function (r) { return { name: r.name, position: r.position }; }),
+  });
+
+  // Composed middleware — sequentially invokes each entry's mw via
+  // next() chaining. Standard Express idiom: each mw receives
+  // (req, res, next) and either calls next() to continue or
+  // next(err) to bail out to the error-handler.
+  //
+  // composedPipeline returns a Promise that resolves AFTER `finalNext`
+  // has been called by the chain. The framework router awaits this
+  // promise; without it, async middleware (bodyParser / apiEncrypt
+  // reading the request stream) leave the router with `next` still
+  // false when composedPipeline returns synchronously, and the
+  // router exits the request before the chain has actually advanced.
+  //
+  // Middleware do NOT await next() — that's the Express contract.
+  // So we can't rely on `await entry.mw(...)` to wait for the rest
+  // of the chain. Instead, the outer Promise resolves only when the
+  // chain reaches its end via finalNext, regardless of how many
+  // hops of async middleware have happened along the way.
+  //
+  // When a middleware calls `next(err)`, the chain skips non-error
+  // middleware (3-arg) and dispatches the error to the first 4-arg
+  // entry (`(err, req, res, next)` — Express's error-handler shape).
+  // If no error-handler entry is found, `finalNext(err)` carries the
+  // error up to the framework router.
+  return function composedPipeline(req, res, finalNext) {
+    return new Promise(function (resolve, reject) {
+      var idx = 0;
+      var finished = false;
+      function _finishOnce(err) {
+        if (finished) return;
+        finished = true;
+        try { finalNext(err); }
+        catch (finalErr) { return reject(finalErr); }
+        resolve();
+      }
+      async function dispatch(err) {
+        if (finished) return;
+        if (idx >= resolved.length) return _finishOnce(err);
+        var entry = resolved[idx];
+        idx += 1;
+        // 4-arg entries are error handlers (Express convention).
+        // Regular entries run on the success path; error entries on
+        // the error path. Skip entries that don't match the current
+        // path until one matches OR the chain ends.
+        var isErrorHandler = entry.mw.length === 4;
+        if (err && !isErrorHandler) return dispatch(err);
+        if (!err && isErrorHandler) return dispatch();
+        // Track whether the middleware called its next() argument.
+        // If a 4-arg error handler runs to completion without calling
+        // next, the error is considered handled and the chain ends
+        // cleanly (Express convention). Same applies to a 3-arg
+        // middleware that doesn't call next — the chain stops, but
+        // we don't invoke finalNext to avoid the router proceeding
+        // to the route handler after a middleware decided to halt.
+        var advanced = false;
+        function _next(passErr) {
+          advanced = true;
+          return dispatch(passErr);
+        }
+        try {
+          if (err) {
+            // Error handler: (err, req, res, next)
+            await entry.mw(err, req, res, _next);
+            if (!advanced) _finishOnce();
+          } else {
+            // Regular middleware: (req, res, next)
+            await entry.mw(req, res, _next);
+            // 3-arg middleware that doesn't call next — chain halts.
+            // The middleware presumably wrote the response itself.
+          }
+        } catch (syncErr) {
+          // Synchronous throw OR rejected promise — route through
+          // the error path so a downstream error-handler can format
+          // the response.
+          dispatch(syncErr).catch(reject);
+        }
+      }
+      dispatch().catch(reject);
+    });
+  };
+}
+
+composePipeline.CANONICAL_POSITIONS = CANONICAL_POSITIONS;
+composePipeline.ComposePipelineError = ComposePipelineError;
+
+function _emitAudit(action, metadata) {
+  try {
+    if (audit && typeof audit().safeEmit === "function") {
+      audit().safeEmit({ action: action, outcome: "success", metadata: metadata });
+    }
+  } catch (_e) { /* drop-silent — audit failure must not break pipeline registration */ }
+}
+
+function _findIndex(arr, name) {
+  for (var i = 0; i < arr.length; i += 1) {
+    if (arr[i].name === name) return i;
+  }
+  return -1;
+}
+
+module.exports = composePipeline;

package/lib/middleware/idempotency-key.js

@@ -43,6 +43,7 @@
 var nodeCrypto    = require("node:crypto");
 var lazyRequire   = require("../lazy-require");
 var numericBounds = require("../numeric-bounds");
+var validateOpts  = require("../validate-opts");
 var safeBuffer    = require("../safe-buffer");
 var safeJson      = require("../safe-json");
 var safeSql       = require("../safe-sql");
@@ -458,6 +459,21 @@ function _emitAudit(action, metadata, outcome) {
  *   methods:               string[], // default: ["POST","PUT","PATCH","DELETE"]
  *   headerName:            string,   // default: "idempotency-key"
  *   requireIdempotencyKey: boolean,  // default: false — refuse missing-key
+ *   bodyFingerprint:       function, // (req) => Buffer|string|object|null — operator-supplied body extractor
+ *   maxBodyBytes:          number,   // default: 1 MiB — replay-cache body cap
+ *
+ * **Mount order — idempotency MUST run AFTER body-parser.** The hook
+ * (and the default `req._rawBody||req.body` lookup) reads request
+ * state at the moment the idempotency middleware runs; if it runs
+ * before body-parser, `req.body` is still unset and the fingerprint
+ * silently degrades to method+path only — which fails the §4.3
+ * "same key, different body" guarantee. `b.middleware.composePipeline`
+ * places bodyParser=20 / idempotency=30 by default so the canonical
+ * order is correct; operators wiring middleware manually must mount
+ * idempotency AFTER bodyParser. The runtime emits
+ * `idempotency.empty_body_fingerprint` audit (warning) whenever a
+ * body-bearing request reaches the middleware with no body data,
+ * so the misordering is detectable from audit logs.
  *
  * @example
  *   var store = b.middleware.idempotencyKey.memoryStore({ maxEntries: 10000 });
@@ -465,6 +481,11 @@ function _emitAudit(action, metadata, outcome) {
  *     store:     store,
  *     ttlMs:     C.TIME.hours(24),
  *     methods:   ["POST", "PUT", "PATCH"],
+ *     // Optional: provide a body-fingerprint extractor that pulls
+ *     // from the parsed body shape. The extractor only runs against
+ *     // state populated by upstream middleware; mount idempotency
+ *     // AFTER bodyParser (composePipeline does this by default).
+ *     bodyFingerprint: function (req) { return req.body || null; },
  *   });
  *   app.use(mw);
  */
@@ -484,6 +505,20 @@ function create(opts) {
     ? opts.headerName.toLowerCase()
     : "idempotency-key";
   var requireKey = opts.requireIdempotencyKey === true;
+  // Operator-supplied body-fingerprint extractor. When provided,
+  // the middleware calls this instead of the inline
+  // `req._rawBody || req.body` lookup. Lets operators mount
+  // body-parser BEFORE the idempotency middleware and surface the
+  // parsed body shape (req.body is the typical post-parser
+  // attachment point); the inline lookup runs BEFORE body-parser
+  // by default, so the fingerprint silently degrades to
+  // method+path-only when body-parser mounts after. With this
+  // hook the middleware reads the body shape the operator
+  // canonically attached, regardless of mount order.
+  var bodyFingerprintFn = validateOpts.optionalFunction(
+    opts.bodyFingerprint, "idempotencyKey.bodyFingerprint",
+    IdempotencyError, "idempotency/bad-body-fingerprint"
+  ) || null;
 
   // Per-response collector cap. Idempotency replay only makes sense
   // for response bodies that fit in memory; the cap is operator-
@@ -522,17 +557,59 @@ function create(opts) {
       return problemDetails().respond(res, bad);
     }
 
-    var bodyBytes = req._rawBody || req.body || null;
-    if (bodyBytes && typeof bodyBytes === "object" && !Buffer.isBuffer(bodyBytes)) {
-      // Buffer-ize a non-buffer body (already-parsed JSON, etc.) so the
-      // hash is stable. JSON.stringify with sorted keys would be more
-      // robust but the operator-attached body shape is whatever the
-      // upstream parser produced; canonicalization is operator-side.
+    var bodyBytes;
+    if (bodyFingerprintFn) {
+      // Operator-supplied hook — called after body-parser so req.body
+      // is populated. Hook returns Buffer / string / null.
       try {
-        bodyBytes = Buffer.from(JSON.stringify(bodyBytes), "utf8");
-      } catch (_e) {
+        var fpVal = bodyFingerprintFn(req);
+        if (fpVal === null || fpVal === undefined) {
+          bodyBytes = null;
+        } else if (Buffer.isBuffer(fpVal)) {
+          bodyBytes = fpVal;
+        } else if (typeof fpVal === "string") {
+          bodyBytes = Buffer.from(fpVal, "utf8");
+        } else {
+          // Object / array — JSON-stringify so the hash is stable.
+          bodyBytes = Buffer.from(JSON.stringify(fpVal), "utf8");
+        }
+      } catch (e) {
+        _emitAudit("idempotency.body_fingerprint_failed",
+          { error: String(e && e.message || e) }, "warning");
         bodyBytes = null;
       }
+    } else {
+      bodyBytes = req._rawBody || req.body || null;
+      if (bodyBytes && typeof bodyBytes === "object" && !Buffer.isBuffer(bodyBytes)) {
+        // Buffer-ize a non-buffer body (already-parsed JSON, etc.) so the
+        // hash is stable. JSON.stringify with sorted keys would be more
+        // robust but the operator-attached body shape is whatever the
+        // upstream parser produced; canonicalization is operator-side.
+        try {
+          bodyBytes = Buffer.from(JSON.stringify(bodyBytes), "utf8");
+        } catch (_e) {
+          bodyBytes = null;
+        }
+      }
+    }
+
+    // Misordered-mount detector — body-bearing method reached us
+    // with neither a parsed body nor a raw-body buffer. Most likely
+    // body-parser hasn't run yet, which silently degrades the
+    // fingerprint to method+path. Emit a warning so the audit log
+    // surfaces the misconfiguration. (Genuinely empty POST bodies
+    // also trip this — acceptable cost; the audit field captures the
+    // distinction via `hasRawBody`/`hasParsedBody`.)
+    if (!bodyBytes && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      _emitAudit("idempotency.empty_body_fingerprint",
+        {
+          method:          method,
+          path:            req.url,
+          hasRawBody:      Boolean(req._rawBody),
+          hasParsedBody:   req.body !== undefined && req.body !== null,
+          hasFingerprintHook: Boolean(bodyFingerprintFn),
+        },
+        "warning");
     }
 
     var fingerprint = _fingerprintRequest(req, bodyBytes);

package/lib/middleware/index.js

@@ -68,6 +68,7 @@ var protectedResourceMetadata = require("./protected-resource-metadata");
 var scimServer = require("./scim-server");
 var idempotencyKey = require("./idempotency-key");
 var noCache = require("./no-cache");
+var composePipeline = require("./compose-pipeline");
 
 module.exports = {
   requestId:        requestId.create,
@@ -126,6 +127,7 @@ module.exports = {
     IdempotencyError: idempotencyKey.IdempotencyError,
   }),
   noCache:          noCache.create,
+  composePipeline:  composePipeline,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {

package/lib/test-harness.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * @module     b.testHarness
+ * @nav        DX
+ * @title      Test Harness
+ * @order      820
+ *
+ * @intro
+ *   Isolated-boot helper for framework-consumer test suites. Replaces
+ *   the per-project pattern of:
+ *
+ *     - mkdtemp a fresh data directory
+ *     - set `MYAPP_DATA_DIR` / `MYAPP_DB_PATH` env vars so the app's
+ *       boot path reads the test paths instead of production
+ *     - init `b.vault` in plaintext mode against the test dataDir so
+ *       primitives that compose vault don't try to read a real key
+ *     - tear down: close vault, remove the temp directory, restore
+ *       env vars
+ *
+ *   That pattern lands as ~50-100 lines in every framework consumer's
+ *   `tests/helpers/test-server.js`. This primitive owns it once.
+ *
+ *   ## Lifecycle
+ *
+ *   ```js
+ *   var h = await b.testHarness.start({
+ *     envPrefix:   "MYAPP",            // optional — env vars prefixed with this
+ *     env:         { LOG_LEVEL: "error" },  // optional — additional env vars to set
+ *     initVault:   true,               // optional — init b.vault in plaintext mode
+ *     resetCaches: true,               // optional — call framework _resetForTest() hooks
+ *   });
+ *   // h.dataDir   — operator-supplied or framework-generated mkdtemp path
+ *   // h.dbPath    — `<dataDir>/db.sqlite` unless operator overrides
+ *   // h.vaultDir  — `<dataDir>/vault`
+ *
+ *   // ... operator's app boot reads process.env.MYAPP_DATA_DIR etc.
+ *
+ *   await h.stop();   // teardown: close vault, remove dataDir, restore env
+ *   ```
+ *
+ *   ## Concurrent test isolation
+ *
+ *   Tests using `SMOKE_PARALLEL=N` against the framework boot N processes
+ *   in parallel — each one running this primitive gets its own
+ *   `mkdtemp`-generated dataDir (collision-free) and its own env-var
+ *   override scope (process-local). The harness does NOT use
+ *   shared state; multiple `start()` calls in the same process create
+ *   parallel handles.
+ *
+ *   ## What the harness does NOT own
+ *
+ *   - **The operator's HTTP server**. Consumers boot their own
+ *     `app.listen(port)`. The harness only sets up paths + env +
+ *     vault + cache-reset. The pattern in HS's
+ *     `tests/helpers/test-server.js` mounts an Express app onto the
+ *     harness's prepared paths.
+ *   - **Per-request authentication state**. The harness doesn't
+ *     mint session cookies / JWTs; tests that need that compose
+ *     `b.session.create({ store: ... })` against the harness's
+ *     paths.
+ *   - **Audit replay tracking**. The harness emits no audit; the
+ *     framework primitives the operator boots emit their own.
+ *
+ *   ## When to use this vs the existing `_resetForTest()` hooks
+ *
+ *   Framework primitives (vault, audit, db, …) expose
+ *   `_resetForTest()` so a single test can scrub in-memory state
+ *   without process-restart. The harness composes those resets +
+ *   adds filesystem isolation. Use the harness when your test
+ *   needs WRITE access to a fresh dataDir (file uploads, sealed
+ *   db, audit-chain on disk); use the bare `_resetForTest()` hooks
+ *   when in-memory state is enough.
+ *
+ * @card
+ *   Isolated-boot helper for framework-consumer test suites. Owns the mkdtemp + env-vars + vault.init + teardown pattern that every consumer reinvents in their tests/helpers/test-server.js.
+ */
+
+var nodeFs   = require("node:fs");
+var os       = require("node:os");
+var nodePath = require("node:path");
+var bCrypto      = require("./crypto");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+var lazyRequire     = require("./lazy-require");
+
+var vault = lazyRequire(function () { return require("./vault"); });
+
+var TestHarnessError = defineClass("TestHarnessError", { alwaysPermanent: true });
+
+// Reference count of harnesses with initVault=true currently alive.
+// vault state is process-global + idempotent across init() calls, so
+// concurrent harnesses share a single initialized vault. The last
+// harness to stop() releases the vault via _resetForTest; earlier
+// stops decrement without tearing down so the still-running peers
+// keep working.
+var _vaultRefCount = 0;
+
+/**
+ * @primitive b.testHarness.start
+ * @signature b.testHarness.start(opts?)
+ * @since     0.9.43
+ * @status    stable
+ * @related   b.vault.init
+ *
+ * Boot an isolated test harness. Returns a promise resolving to a
+ * handle exposing `dataDir`, `dbPath`, `vaultDir`, `env` (the env-var
+ * overrides set), and an async `stop()` that tears the harness down
+ * (releases vault, removes the temp directory, restores env). Always
+ * `await` the call — vault.init is async, and unawaited failures
+ * become unhandled rejections.
+ *
+ * Concurrent harnesses with `initVault: true` share the
+ * process-global vault state via reference counting; stopping one
+ * harness leaves vault initialized for the remaining peers. The
+ * last `stop()` releases vault.
+ *
+ * @opts
+ *   dataDir:     string,    // optional — pre-existing dir to use; harness mkdtemps if absent
+ *   dbPath:      string,    // optional — defaults to `<dataDir>/db.sqlite`
+ *   vaultDir:    string,    // optional — defaults to `<dataDir>/vault`
+ *   envPrefix:   string,    // optional — env vars `<PREFIX>_DATA_DIR` / `_DB_PATH` / `_VAULT_DIR`; default no prefix
+ *   env:         object,    // optional — additional env-var overrides; restored on stop()
+ *   initVault:   boolean,   // optional — boot b.vault in plaintext mode against vaultDir; default true
+ *   keepOnStop:  boolean,   // optional — leave dataDir in place after stop(); default false (rm -rf)
+ *
+ * @example
+ *   var h = await b.testHarness.start({ envPrefix: "MYAPP", initVault: true });
+ *   try {
+ *     // ... operator's app boot reads process.env.MYAPP_DATA_DIR etc.
+ *     // ... run tests ...
+ *   } finally {
+ *     await h.stop();
+ *   }
+ */
+async function start(opts) {
+  opts = opts || {};
+  validateOpts.optionalNonEmptyString(opts.dataDir, "start.dataDir",
+    TestHarnessError, "test-harness/bad-input");
+  if (opts.envPrefix !== undefined && (typeof opts.envPrefix !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(opts.envPrefix))) {  // allow:regex-no-length-cap — env-var prefix shape
+    throw new TestHarnessError("test-harness/bad-input",
+      "start: opts.envPrefix must be uppercase ASCII identifier (A-Z, 0-9, _)");
+  }
+  if (opts.env !== undefined && (opts.env === null || typeof opts.env !== "object" || Array.isArray(opts.env))) {
+    throw new TestHarnessError("test-harness/bad-input",
+      "start: opts.env must be a plain object if provided");
+  }
+
+  // Resolve / create dataDir.
+  var dataDir;
+  var weCreatedDataDir = false;
+  if (opts.dataDir) {
+    dataDir = nodePath.resolve(opts.dataDir);
+    nodeFs.mkdirSync(dataDir, { recursive: true });
+  } else {
+    // mkdtemp uses os.tmpdir + cryptographic suffix; collision-free
+    // even under SMOKE_PARALLEL=64 fan-out. Prefix surfaces the
+    // process owner for grep-on-leak diagnosis.
+    var prefix = nodePath.join(os.tmpdir(),
+      "blamejs-harness-" + bCrypto.generateToken(4) + "-");                                              // allow:raw-byte-literal — 4-byte token (8 hex) suffix
+    dataDir = nodeFs.mkdtempSync(prefix);
+    weCreatedDataDir = true;
+  }
+
+  var dbPath   = opts.dbPath   || nodePath.join(dataDir, "db.sqlite");
+  var vaultDir = opts.vaultDir || nodePath.join(dataDir, "vault");
+  nodeFs.mkdirSync(vaultDir, { recursive: true });
+
+  // Capture + set env vars. We restore on stop() — values absent
+  // pre-start are unset; values present are restored to their prior
+  // value. The harness is process-local; concurrent harnesses share
+  // process.env so the operator's envPrefix should be unique per
+  // harness (or omitted, in which case no env vars are set).
+  var envBackup = {};
+  function _setEnv(key, value) {
+    // First-write-wins on the backup so multiple writes to the same
+    // key (e.g. envPrefix + opts.env naming the same var) restore the
+    // ORIGINAL pre-harness value on stop(), not a harness-written
+    // intermediate. Object.prototype.hasOwnProperty.call guards
+    // against the `__proto__` / `constructor` key class.
+    if (!Object.prototype.hasOwnProperty.call(envBackup, key)) {
+      envBackup[key] = Object.prototype.hasOwnProperty.call(process.env, key)
+        ? process.env[key] : null;
+    }
+    process.env[key] = value;
+  }
+  if (opts.envPrefix) {
+    _setEnv(opts.envPrefix + "_DATA_DIR", dataDir);
+    _setEnv(opts.envPrefix + "_DB_PATH",  dbPath);
+    _setEnv(opts.envPrefix + "_VAULT_DIR", vaultDir);
+  }
+  if (opts.env) {
+    for (var k in opts.env) {
+      if (Object.prototype.hasOwnProperty.call(opts.env, k)) {
+        _setEnv(k, String(opts.env[k]));
+      }
+    }
+  }
+
+  // Optional vault init. Default ON for the typical case where the
+  // operator's primitives compose vault. Operator opts out via
+  // `initVault: false` for tests that exercise vault.init themselves.
+  var initVault = opts.initVault !== false;
+  var ownsVaultRef = false;
+  if (initVault) {
+    try {
+      // vault.init is async; awaiting it ensures failures surface as
+      // a thrown TestHarnessError from start() (not an unhandled
+      // promise rejection after start() returns).
+      await vault().init({ dataDir: vaultDir, mode: "plaintext" });
+      _vaultRefCount += 1;
+      ownsVaultRef = true;
+    } catch (e) {
+      // Reset env + remove dataDir before re-throwing so the test
+      // doesn't leak a half-initialized state.
+      _restoreEnv(envBackup);
+      if (weCreatedDataDir && !opts.keepOnStop) {
+        try { nodeFs.rmSync(dataDir, { recursive: true, force: true }); }
+        catch (_e) { /* best-effort cleanup */ }
+      }
+      throw new TestHarnessError("test-harness/vault-init-failed",
+        "start: vault.init failed: " + (e && e.message || String(e)));
+    }
+  }
+
+  var stopped = false;
+  async function stop() {
+    if (stopped) return;
+    stopped = true;
+
+    // Vault teardown — _resetForTest is the framework convention for
+    // primitive scrub. Reference-counted so concurrent harnesses
+    // sharing the process-global vault don't tear it out from under
+    // each other; only the LAST owning harness's stop() resets.
+    if (initVault && ownsVaultRef) {
+      ownsVaultRef = false;
+      _vaultRefCount = Math.max(0, _vaultRefCount - 1);
+      if (_vaultRefCount === 0) {
+        try {
+          var v = vault();
+          if (typeof v._resetForTest === "function") v._resetForTest();
+        } catch (_e) { /* best-effort */ }
+      }
+    }
+
+    _restoreEnv(envBackup);
+
+    if (weCreatedDataDir && !opts.keepOnStop) {
+      try { nodeFs.rmSync(dataDir, { recursive: true, force: true }); }
+      catch (_e) { /* best-effort — operator can inspect on leak */ }
+    }
+  }
+
+  return {
+    dataDir:   dataDir,
+    dbPath:    dbPath,
+    vaultDir:  vaultDir,
+    envPrefix: opts.envPrefix || null,
+    initVault: initVault,
+    stop:      stop,
+    TestHarnessError: TestHarnessError,
+  };
+}
+
+function _restoreEnv(backup) {
+  for (var k in backup) {
+    if (!Object.prototype.hasOwnProperty.call(backup, k)) continue;
+    if (backup[k] === null) delete process.env[k];
+    else                    process.env[k] = backup[k];
+  }
+}
+
+module.exports = {
+  start:              start,
+  TestHarnessError:   TestHarnessError,
+};

package/lib/watcher.js

@@ -178,7 +178,145 @@ function _compileIgnore(patterns) {
   };
 }
 
-var ALLOWED_MODES = ["fs", "poll"];
+var ALLOWED_MODES = ["fs", "poll", "auto"];
+
+// Filesystem types that the recursive fs.watch backend doesn't deliver
+// events on in practice. Detected from /proc/self/mountinfo when the
+// watcher's root resolves into one of these mounts.
+//
+// - fuse / fuse.<driver>: Docker Desktop on macOS uses gRPC-FUSE for
+//   bind-mounts; Windows Docker Desktop with VirtioFS-backed WSL2 ships
+//   in the same family. Native Linux containers running on overlayfs
+//   inside a bind-mounted host directory don't propagate inotify events
+//   across the gRPC-FUSE boundary; libuv's recursive fs.watch
+//   silently observes no events for the lifetime of the watcher.
+// - 9p: WSL2 host-to-Linux filesystem when running on Windows;
+//   doesn't propagate change events to Linux inotify.
+// - virtiofs: newer Docker Desktop default on Apple Silicon Macs;
+//   inotify is forwarded but recursive coverage is unreliable.
+// - cifs / smbfs / nfs / nfs4: network filesystems where the server
+//   doesn't push change notifications to the client kernel.
+//
+// Operators on a container running over one of these mounts default
+// to poll under mode: "auto".
+var AUTO_PROBE_POLL_FSTYPES = new Set([
+  "fuse",
+  "fuse.gcsfuse",
+  "fuse.grpcfuse",
+  "fuse.virtiofs",
+  "9p",
+  "virtiofs",
+  "cifs",
+  "smbfs",
+  "nfs",
+  "nfs4",
+  "vboxsf",
+]);
+
+function _detectAutoMode(rootPath) {
+  // Sync probe — looks at the kernel's view of the mount carrying the
+  // watcher's root and decides whether fs.watch will deliver events.
+  // Three signals contribute, in priority order:
+  //   1. /proc/self/mountinfo entry for the root's longest-matching
+  //      mount — if its fstype is in AUTO_PROBE_POLL_FSTYPES, poll.
+  //   2. Bind-mount detection — mountinfo field 4 ("root within source
+  //      filesystem", per Documentation/filesystems/proc.rst §3.5) is
+  //      "/" for a regular mount but the bound source path for a bind
+  //      mount. Inside a container, a field-4 != "/" indicates a host
+  //      bind-mount whose inotify chain may not propagate across the
+  //      virtualization boundary; poll.
+  //   3. Otherwise — fs.
+  //
+  // Returns { mode, reason, fsType, inContainer }.
+  if (process.platform !== "linux") {
+    // macOS + Windows fs.watch backends use FSEvents + ReadDirectoryChangesW
+    // respectively, which DO deliver recursive events natively for
+    // operator-owned local filesystems. Containerized Linux is the
+    // failure mode this probe is built for.
+    return { mode: "fs", reason: "non-linux-host", fsType: null, inContainer: false };
+  }
+
+  var inContainer = false;
+  try { inContainer = nodeFs.existsSync("/.dockerenv"); }
+  catch (_e) { inContainer = false; }
+
+  var mountInfoRaw = null;
+  try { mountInfoRaw = nodeFs.readFileSync("/proc/self/mountinfo", "utf8"); }
+  catch (_e) { mountInfoRaw = null; }
+
+  if (!mountInfoRaw) {
+    // No mountinfo available — fall back to fs. Operator can still
+    // override explicitly via mode: "poll".
+    return { mode: "fs", reason: "no-mountinfo", fsType: null, inContainer: inContainer };
+  }
+
+  // Find the mount whose mount-point is the longest prefix of rootPath.
+  var lines = mountInfoRaw.split("\n");
+  var bestMatch = null;
+  var bestLen   = -1;
+  for (var i = 0; i < lines.length; i += 1) {
+    var ln = lines[i];
+    if (!ln) continue;
+    // Format: <id> <parent> <major:minor> <root> <mountpoint> <options>
+    //         [<optional-fields>...] - <fstype> <source> <super-options>
+    // The separator " - " divides the optional-fields half from the post-fields half.
+    var sepIdx = ln.indexOf(" - ");
+    if (sepIdx === -1) continue;
+    var preFields  = ln.slice(0, sepIdx).split(" ");
+    var postFields = ln.slice(sepIdx + 3).split(" ");
+    if (preFields.length < 6 || postFields.length < 1) continue;
+    var rootField  = preFields[3];        // "/" for regular mount; bound-source path for bind
+    var mountPoint = preFields[4];
+    var fstype     = postFields[0];
+    if (typeof mountPoint !== "string" || mountPoint.length === 0) continue;
+    if (rootPath === mountPoint ||
+        (rootPath.length > mountPoint.length &&
+         rootPath.indexOf(mountPoint) === 0 &&
+         (mountPoint === "/" || rootPath.charCodeAt(mountPoint.length) === 47 /* / */))) {
+      if (mountPoint.length > bestLen) {
+        bestLen = mountPoint.length;
+        bestMatch = { mountPoint: mountPoint, rootField: rootField, fstype: fstype };
+      }
+    }
+  }
+
+  if (!bestMatch) {
+    return { mode: "fs", reason: "no-mount-match", fsType: null, inContainer: inContainer };
+  }
+
+  if (AUTO_PROBE_POLL_FSTYPES.has(bestMatch.fstype)) {
+    return {
+      mode:        "poll",
+      reason:      "fstype-non-inotify",
+      fsType:      bestMatch.fstype,
+      inContainer: inContainer,
+    };
+  }
+
+  // Bind-mount detection via mountinfo field 4 ("root"). For a regular
+  // mount this is "/" — the entire source filesystem is mounted. For a
+  // bind-mount it's the path within the source filesystem that was
+  // bound onto the mount point (e.g. "/Users/me/data" on a Docker
+  // Desktop bind from macOS). When we're inside a container AND the
+  // best-matching mount carries a non-"/" root, the mount is a bind
+  // and inotify chains across the host/guest boundary are unreliable.
+  // (Operator can still force fs via mode: "fs"; force poll via mode: "poll".)
+  if (inContainer && bestMatch.rootField && bestMatch.rootField !== "/") {
+    return {
+      mode:        "poll",
+      reason:      "container-bind-mount",
+      fsType:      bestMatch.fstype,
+      inContainer: inContainer,
+    };
+  }
+
+  return {
+    mode:        "fs",
+    reason:      "native-fs",
+    fsType:      bestMatch.fstype,
+    inContainer: inContainer,
+  };
+}
 
 function _validateOpts(opts) {
   validateOpts.requireObject(opts, "watcher.create", WatcherError, "watcher/bad-opts");
@@ -215,7 +353,12 @@ function create(opts) {
   var root        = nodePath.resolve(opts.root);
   var debounceMs  = (opts.debounceMs !== undefined) ? opts.debounceMs : DEFAULT_DEBOUNCE_MS;
   var maxPending  = (opts.maxPending !== undefined) ? opts.maxPending : DEFAULT_MAX_PENDING;
-  var mode        = opts.mode || "fs";
+  var requestedMode = opts.mode || "fs";
+  var autoDecision  = null;
+  if (requestedMode === "auto") {
+    autoDecision = _detectAutoMode(root);
+  }
+  var mode = autoDecision ? autoDecision.mode : requestedMode;
   var pollIntervalMs = opts.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS;
   var pollMaxFiles   = opts.pollMaxFiles   || DEFAULT_POLL_MAX_FILES;
   var onChange    = opts.onChange || function () {};
@@ -438,7 +581,16 @@ function create(opts) {
     }
   }
 
-  _safeEmitAudit("watcher.started", { root: root, mode: mode });
+  if (autoDecision) {
+    _safeEmitAudit("watcher.mode_auto_decision", {
+      root:        root,
+      chosen:      autoDecision.mode,
+      reason:      autoDecision.reason,
+      fsType:      autoDecision.fsType,
+      inContainer: autoDecision.inContainer,
+    });
+  }
+  _safeEmitAudit("watcher.started", { root: root, mode: mode, requestedMode: requestedMode });
 
   function stop() {
     if (stopped) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.41",
+  "version": "0.9.43",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:2ba814f6-24ab-4017-914e-f9ddba6c50ef",
+  "serialNumber": "urn:uuid:25095753-dd82-4e38-95b9-70ee29c706f8",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-15T14:40:55.638Z",
+    "timestamp": "2026-05-15T17:05:04.296Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.41",
+      "bom-ref": "@blamejs/core@0.9.43",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.41",
+      "version": "0.9.43",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.41",
+      "purl": "pkg:npm/%40blamejs/core@0.9.43",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.41",
+      "ref": "@blamejs/core@0.9.43",
       "dependsOn": []
     }
   ]