@blamejs/core 0.10.7 → 0.10.9

package/lib/promise-pool.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * @module b.promisePool
+ * @nav    Async
+ * @title  Promise Pool
+ *
+ * @intro
+ *   Bounded-concurrency task runner for promise-returning work — the
+ *   common gap between `b.workerPool` (worker_threads for CPU-bound
+ *   work) and `b.queue` (durable cross-process messaging). Wraps the
+ *   typical "I have N parallel I/O fan-outs and want at most K in
+ *   flight at any moment" pattern with back-pressure on enqueue
+ *   (so the caller can't out-run the worker side) and a clean drain
+ *   path that composes with `b.appShutdown`.
+ *
+ *   Two enqueue paths:
+ *
+ *     - `pool.run(taskFn)` returns a Promise that resolves to the
+ *       task's return value (or rejects with the task's error). When
+ *       the pool is at capacity, `run` waits until a slot frees
+ *       BEFORE the task starts — back-pressure is part of the
+ *       contract, not an opt.
+ *
+ *     - `pool.fire(taskFn)` is the synchronous-enqueue variant for
+ *       fan-out from non-async contexts. Returns the same Promise
+ *       but the call itself can't await — useful inside event
+ *       handlers that fire-and-forget.
+ *
+ *   Drain semantics: `pool.drain()` resolves when every queued and
+ *   in-flight task settles. Callers wire this into shutdown via
+ *   `b.appShutdown.create({ priority: 50, run: () => pool.drain() })`
+ *   so the process doesn't tear down with work mid-flight.
+ *
+ *   The pool does NOT retry failed tasks; rejection of a task's
+ *   promise is the caller's signal. Operators that want retry compose
+ *   `b.retry.withRetry` inside the task body.
+ *
+ * @card
+ *   Bounded-concurrency promise pool — back-pressure on enqueue, drain-on-shutdown, no hidden retry. The thing every consumer reaches for p-limit for.
+ */
+
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+
+var PromisePoolError = defineClass("PromisePoolError", { alwaysPermanent: true });
+
+var MAX_CONCURRENCY = 65536;                                                                    // allow:raw-byte-literal — uint16 ceiling on parallel I/O fan-out
+
+/**
+ * @primitive b.promisePool.create
+ * @signature b.promisePool.create(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.workerPool.create, b.appShutdown.create, b.retry.withRetry
+ *
+ * Build a bounded-concurrency pool. Returns
+ * `{ run, fire, drain, size, inFlight, queued, closed }`. The pool is
+ * closed via `drain({ close: true })`; subsequent enqueues throw.
+ *
+ * @opts
+ *   concurrency: number,        // required; integer in [1, 65536]
+ *   queueLimit:  number,        // default Infinity; once exceeded, enqueue throws
+ *
+ * @example
+ *   var pool = b.promisePool.create({ concurrency: 8 });
+ *   var results = await Promise.all(items.map(function (item) {
+ *     return pool.run(function () { return fetchOne(item); });
+ *   }));
+ *   await pool.drain({ close: true });
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "b.promisePool.create",
+    PromisePoolError, "promise-pool/bad-opts");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.concurrency,
+    "b.promisePool.create: concurrency", PromisePoolError, "promise-pool/bad-concurrency");
+  if (opts.concurrency === undefined || opts.concurrency > MAX_CONCURRENCY) {
+    throw new PromisePoolError("promise-pool/bad-concurrency",
+      "b.promisePool.create: concurrency must be an integer in [1, " +
+      MAX_CONCURRENCY + "] (got " + opts.concurrency + ")");
+  }
+  var queueLimit = opts.queueLimit === undefined ? Infinity : opts.queueLimit;
+  if (queueLimit !== Infinity) {
+    numericBounds.requirePositiveFiniteIntIfPresent(queueLimit + 1,
+      "b.promisePool.create: queueLimit (must be non-negative int)", PromisePoolError,
+      "promise-pool/bad-queue-limit");
+  }
+  var concurrency = opts.concurrency;
+  var inFlight = 0;
+  var queue = [];                // FIFO of pending { taskFn, resolve, reject }
+  var drainWaiters = [];
+  var closed = false;
+
+  function _pump() {
+    while (inFlight < concurrency && queue.length > 0) {
+      var slot = queue.shift();
+      inFlight += 1;
+      Promise.resolve().then(function () { return slot.taskFn(); })
+        .then(function (val) { slot.resolve(val); _settle(); })
+        .catch(function (err) { slot.reject(err); _settle(); });
+    }
+    if (inFlight === 0 && queue.length === 0 && drainWaiters.length > 0) {
+      var waiters = drainWaiters.slice();
+      drainWaiters.length = 0;
+      for (var i = 0; i < waiters.length; i += 1) waiters[i]();
+    }
+  }
+
+  function _settle() {
+    inFlight -= 1;
+    _pump();
+  }
+
+  function _enqueue(taskFn) {
+    if (typeof taskFn !== "function") {
+      throw new PromisePoolError("promise-pool/bad-task",
+        "b.promisePool: task must be a function returning a value or Promise");
+    }
+    if (closed) {
+      throw new PromisePoolError("promise-pool/closed",
+        "b.promisePool: pool is closed (drain({close:true}) was called)");
+    }
+    if (queue.length >= queueLimit) {
+      throw new PromisePoolError("promise-pool/queue-full",
+        "b.promisePool: queueLimit=" + queueLimit + " reached");
+    }
+    return new Promise(function (resolve, reject) {
+      queue.push({ taskFn: taskFn, resolve: resolve, reject: reject });
+      _pump();
+    });
+  }
+
+  function run(taskFn)  { return _enqueue(taskFn); }
+  function fire(taskFn) { return _enqueue(taskFn); }
+
+  function drain(drainOpts) {
+    drainOpts = drainOpts || {};
+    return new Promise(function (resolve) {
+      function _done() {
+        if (drainOpts.close === true) closed = true;
+        resolve();
+      }
+      if (inFlight === 0 && queue.length === 0) { _done(); return; }
+      drainWaiters.push(_done);
+    });
+  }
+
+  return {
+    run:      run,
+    fire:     fire,
+    drain:    drain,
+    size:     function () { return concurrency; },
+    inFlight: function () { return inFlight; },
+    queued:   function () { return queue.length; },
+    closed:   function () { return closed; },
+  };
+}
+
+module.exports = {
+  create:           create,
+  PromisePoolError: PromisePoolError,
+};

package/lib/safe-path.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * @module b.safePath
+ * @nav    Filesystem
+ * @title  Safe Path
+ *
+ * @intro
+ *   Path-traversal-safe multi-segment resolve. Operators consuming
+ *   operator-OR-user-supplied path segments (uploaded filenames,
+ *   tarball entries, archive extraction, dynamic include paths) pass
+ *   `base + rel` to `b.safePath.resolve` and get back the absolute
+ *   canonicalized path — guaranteed to lie strictly within `base` —
+ *   or a typed `SafePathError` with a stable `code` on refusal.
+ *
+ *   Refusal classes (each a documented code, never best-effort):
+ *
+ *     - `safe-path/absolute-rel`           — rel is absolute, UNC, or carries a drive letter
+ *     - `safe-path/escapes-base`           — `..` segments escape base after lexical resolve
+ *     - `safe-path/null-byte`              — NUL anywhere (closes Node poison-NUL class)
+ *     - `safe-path/control-char`           — C0 control char other than NUL
+ *     - `safe-path/bidi`                   — bidi-override codepoint (CVE-2021-42574 Trojan Source)
+ *     - `safe-path/win-reserved`           — Windows reserved name (CON/PRN/AUX/NUL/COM0-9/LPT0-9)
+ *                                            on EVERY platform — closes CVE-2025-27210 cross-mount class
+ *     - `safe-path/win-trailing`           — segment ends with `.` or ` ` under windows-mode resolve
+ *     - `safe-path/separator-in-segment`   — encoded path-separator in a segment (URL / fullwidth /
+ *                                            overlong UTF-8 / division-slash)
+ *     - `safe-path/ads-marker`             — NTFS Alternate Data Stream `foo:bar` marker
+ *     - `safe-path/realpath-escapes-base`  — symlink resolution escapes base (opt-in via opts.realpath)
+ *
+ *   Per-segment filename validation composes `b.guardFilename`'s
+ *   reserved-name + overlong UTF-8 + bidi tables; the multi-segment
+ *   resolve + base-escape check is the new code.
+ *
+ * @card
+ *   Traversal-safe multi-segment path resolve. Every documented failure mode → coded refusal. Composes b.guardFilename.
+ */
+
+var nodePath = require("node:path");
+var nodeFs = require("node:fs");
+var { defineClass } = require("./framework-error");
+
+var SafePathError = defineClass("SafePathError", { alwaysPermanent: true });
+
+// Windows reserved device names — CON, PRN, AUX, NUL, COM0–COM9,
+// LPT0–LPT9, CONIN$, CONOUT$. Enforced on EVERY platform to defend
+// the cross-mount case where a POSIX server writes a path that a
+// Windows operator later mounts (closes CVE-2025-27210 class).
+var WIN_RESERVED_RE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)(?:\..*)?$/i;
+// Path separators outside the platform-native set. Each entry MUST
+// be rejected as a segment-internal character. Includes both raw +
+// canonical-encoded forms.
+var ENCODED_SEPARATOR_RE = /(%2[fF]|%5[cC]|%C0%AF|%C1%9C|[／＼∕⧸⁄])/;
+// Bidi-override codepoints (RTL/LTR markers + isolate enclosures).
+var BIDI_RE = /[‪-‮⁦-⁩‎‏]/;
+// C0 control byte range (excluding NUL which has its own dedicated
+// refusal so the error code matches the historical poison-NUL class).
+// eslint-disable-next-line no-control-regex
+var C0_RE = /[\x01-\x1F\x7F]/;
+
+function _refuse(code, message) {
+  throw new SafePathError(code, message);
+}
+
+/**
+ * @primitive b.safePath.resolve
+ * @signature b.safePath.resolve(base, rel, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.safePath.validate, b.guardFilename.validate, b.atomicFile.write
+ *
+ * Resolve `rel` against `base` and return the absolute canonicalized
+ * path — guaranteed to lie strictly within `base`. Throws
+ * `SafePathError` with a stable refusal code on any rejection.
+ *
+ * @opts
+ *   realpath:         boolean,         // default false; true → fs.realpathSync check (symlink-escape)
+ *   platform:         string,          // "windows" forces win-trailing / UNC refusal regardless of host
+ *   allowAbsoluteRel: boolean,         // default false; opt-in for absolute rel that still resolves inside base
+ *
+ * @example
+ *   var p = b.safePath.resolve("/srv/uploads", req.body.path);
+ *   // → "/srv/uploads/<safe-rel>"  OR  throws SafePathError on traversal
+ */
+function resolve(base, rel, opts) {
+  return _resolveCore(base, rel, opts || {});
+}
+
+/**
+ * @primitive b.safePath.resolveOrNull
+ * @signature b.safePath.resolveOrNull(base, rel, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.safePath.resolve, b.safePath.validate
+ *
+ * Same contract as `resolve` but returns `null` on refusal instead of
+ * throwing. Useful for hot-path callers that want a boolean-ish gate
+ * without try/catch overhead.
+ *
+ * @opts
+ *   realpath:         boolean,
+ *   platform:         string,
+ *   allowAbsoluteRel: boolean,
+ *
+ * @example
+ *   var p = b.safePath.resolveOrNull("/srv/uploads", req.body.path);
+ *   if (p === null) { res.statusCode = 400; res.end("bad path"); return; }
+ */
+function resolveOrNull(base, rel, opts) {
+  try { return _resolveCore(base, rel, opts || {}); }
+  catch (_e) { return null; }
+}
+
+/**
+ * @primitive b.safePath.validate
+ * @signature b.safePath.validate(base, rel, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.safePath.resolve
+ *
+ * Same gate as `resolve` but returns a verdict object instead of
+ * throwing — `{ ok: true, resolved }` on success, `{ ok: false,
+ * code, message }` on refusal. Use when the caller wants to log the
+ * refusal class without throw/catch.
+ *
+ * @opts
+ *   realpath:         boolean,
+ *   platform:         string,
+ *   allowAbsoluteRel: boolean,
+ *
+ * @example
+ *   var v = b.safePath.validate("/srv/uploads", req.body.path);
+ *   if (!v.ok) { res.end("rejected: " + v.code); return; }
+ */
+function validate(base, rel, opts) {
+  try { return { ok: true, resolved: _resolveCore(base, rel, opts || {}) }; }
+  catch (e) { return { ok: false, code: e.code || "safe-path/unknown", message: e.message }; }
+}
+
+function _resolveCore(base, rel, opts) {
+  if (typeof base !== "string" || base.length === 0) {
+    _refuse("safe-path/bad-input", "b.safePath.resolve: base must be a non-empty string");
+  }
+  if (typeof rel !== "string") {
+    _refuse("safe-path/bad-input", "b.safePath.resolve: rel must be a string");
+  }
+  var platform = opts.platform || process.platform;
+  var isWin = platform === "win32" || platform === "windows";
+
+  // NUL byte ANYWHERE — its own refusal so the audit code matches
+  // the historical Node poison-NUL class.
+  if (rel.indexOf("\0") !== -1) {
+    _refuse("safe-path/null-byte", "b.safePath.resolve: NUL byte in rel");
+  }
+  // Other C0 + DEL.
+  if (C0_RE.test(rel)) {                                                                              // allow:regex-no-length-cap — anchored C0/DEL set, length bounded by rel
+    _refuse("safe-path/control-char", "b.safePath.resolve: C0 control char in rel");
+  }
+  // Bidi override (Trojan Source).
+  if (BIDI_RE.test(rel)) {                                                                            // allow:regex-no-length-cap — fixed bidi set, length bounded by rel
+    _refuse("safe-path/bidi",
+      "b.safePath.resolve: bidi-override codepoint in rel (CVE-2021-42574 class)");
+  }
+  // Encoded path separators inside what should be a single segment.
+  if (ENCODED_SEPARATOR_RE.test(rel)) {                                                               // allow:regex-no-length-cap — fixed separator-shape set
+    _refuse("safe-path/separator-in-segment",
+      "b.safePath.resolve: encoded path-separator codepoint in rel");
+  }
+  // Absolute rel (POSIX, Windows drive-letter, UNC) — refuse unless
+  // operator opted in.
+  var isAbsolute = nodePath.isAbsolute(rel) ||
+                   /^[A-Za-z]:[\\/]/.test(rel) ||                                                     // allow:regex-no-length-cap — anchored drive-letter shape
+                   /^\\\\/.test(rel) ||                                                               // allow:regex-no-length-cap — UNC `\\` prefix
+                   /^\/\//.test(rel);                                                                 // allow:regex-no-length-cap — POSIX `//` prefix
+  if (isAbsolute && !opts.allowAbsoluteRel) {
+    _refuse("safe-path/absolute-rel",
+      "b.safePath.resolve: rel is absolute/UNC/drive-letter (set opts.allowAbsoluteRel for opt-in)");
+  }
+
+  // Per-segment walk. Reserved-name + ADS + win-trailing + segment-
+  // shape checks happen here.
+  var sep = isWin ? /[\\/]/ : /\//;
+  var segments = rel.split(sep);                                                                      // allow:regex-no-length-cap — fixed separator
+  for (var si = 0; si < segments.length; si += 1) {
+    var seg = segments[si];
+    if (seg.length === 0) continue;            // empty (leading/trailing/double-sep)
+    if (seg === "." || seg === "..") continue; // resolution handled below
+    var segLc = seg.toLowerCase();
+    var baseName = segLc.indexOf(".") === -1 ? segLc : segLc.slice(0, segLc.indexOf("."));
+    if (WIN_RESERVED_RE.test(seg) || WIN_RESERVED_RE.test(baseName)) {                                // allow:regex-no-length-cap — anchored reserved-name set
+      _refuse("safe-path/win-reserved",
+        "b.safePath.resolve: segment '" + seg + "' is a Windows reserved name (CVE-2025-27210 class)");
+    }
+    if (isWin) {
+      var last = seg.charAt(seg.length - 1);
+      if (last === "." || last === " ") {
+        _refuse("safe-path/win-trailing",
+          "b.safePath.resolve: segment '" + seg + "' ends with '.' or ' ' (Windows silently strips)");
+      }
+    }
+    // NTFS Alternate Data Stream marker — refuse `foo:bar` ANYWHERE
+    // except where the colon is part of a Windows drive prefix (the
+    // absolute-rel branch above already refused those).
+    if (seg.indexOf(":") !== -1) {
+      _refuse("safe-path/ads-marker",
+        "b.safePath.resolve: segment '" + seg + "' contains ':' (NTFS Alternate Data Stream marker; CVE-2024-12217 class)");
+    }
+  }
+
+  // Lexical resolve.
+  var baseResolved = nodePath.resolve(base);
+  var joined = nodePath.resolve(baseResolved, rel);
+  // Cross-check via posix.normalize so a Windows host with mixed
+  // separators still surfaces escapes consistently.
+  var sepChar = isWin ? "\\" : "/";
+  if (joined !== baseResolved && joined.slice(0, baseResolved.length + 1) !== baseResolved + sepChar) {
+    _refuse("safe-path/escapes-base",
+      "b.safePath.resolve: rel resolves outside base ('" + joined + "' not inside '" + baseResolved + "')");
+  }
+  if (opts.realpath === true) {
+    var baseRealpath;
+    try { baseRealpath = nodeFs.realpathSync.native(baseResolved); }
+    catch (e) {
+      _refuse("safe-path/realpath-base-unresolvable",
+        "b.safePath.resolve: opts.realpath set but base realpath failed: " + (e && e.message));
+    }
+    // Walk up the joined path from the leaf, finding the longest
+    // ancestor that exists, and check its realpath. Operators want
+    // refusal when ANY ancestor symlink escapes — nodeFs.realpathSync on a
+    // non-existent path would throw.
+    var ancestor = joined;
+    while (ancestor.length > baseResolved.length) {
+      try {
+        var ancRealpath = nodeFs.realpathSync.native(ancestor);
+        if (ancRealpath !== baseRealpath &&
+            ancRealpath.slice(0, baseRealpath.length + 1) !== baseRealpath + sepChar) {
+          _refuse("safe-path/realpath-escapes-base",
+            "b.safePath.resolve: symlink resolution at '" + ancestor +
+            "' escapes base realpath '" + baseRealpath + "'");
+        }
+        break;
+      } catch (_ie) {
+        ancestor = nodePath.dirname(ancestor);
+      }
+    }
+  }
+  return joined;
+}
+
+module.exports = {
+  resolve:        resolve,
+  resolveOrNull:  resolveOrNull,
+  validate:       validate,
+  SafePathError:  SafePathError,
+};

package/lib/sd-notify.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * @module b.sdNotify
+ * @nav    Process
+ * @title  systemd Notify
+ *
+ * @intro
+ *   `sd_notify` protocol surface for daemons running under
+ *   `Type=notify` systemd units. Composes the standard lifecycle
+ *   messages — `READY=1` on boot, `WATCHDOG=1` on heartbeat,
+ *   `STOPPING=1` on shutdown, `RELOADING=1` on hot-reload — against
+ *   the `$NOTIFY_SOCKET` env var systemd populates for the child
+ *   process.
+ *
+ *   Transport: Node has no unix-DGRAM socket support in its `dgram`
+ *   module, so the v1 path shells out to `systemd-notify(1)` via
+ *   `execFile` (NOT `exec` — no shell-string parsing on the
+ *   message bytes). Operators running under systemd already have
+ *   `systemd-tools` installed by definition, so the dependency is
+ *   no expansion of the trust surface.
+ *
+ *   Compose with `b.appShutdown` for the STOPPING signal: register a
+ *   priority-0 phase that calls `b.sdNotify.stopping()` so systemd
+ *   sees the shutdown intent before the framework tears anything
+ *   down. Compose with a periodic `WATCHDOG=1` against the unit's
+ *   `WatchdogSec=` interval so systemd auto-restarts the daemon if
+ *   the event loop wedges.
+ *
+ *   When `$NOTIFY_SOCKET` is unset (process running outside systemd
+ *   — bare invocation, foreground dev, container without
+ *   `--notify-ready`), every call is a no-op that surfaces a single
+ *   boot-time audit entry. Operators get observability of the
+ *   degraded state without per-call log noise.
+ *
+ * @card
+ *   sd_notify protocol for systemd Type=notify daemons — READY / WATCHDOG / STOPPING / RELOADING. Composes b.appShutdown for shutdown signaling.
+ */
+
+var { execFile } = require("node:child_process");
+var C = require("./constants");
+var safeEnv = require("./parsers/safe-env");
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+
+var SdNotifyError = defineClass("SdNotifyError", { alwaysPermanent: true });
+
+// Whitelist of sd_notify state= values we ship as named helpers. The
+// underlying `send({ state })` accepts any string but the helpers are
+// the operator-facing surface — `READY=1` etc. — and the audit log
+// records the named state, not arbitrary payload bytes.
+var KNOWN_STATES = Object.freeze({
+  ready:     "READY=1",
+  stopping:  "STOPPING=1",
+  reloading: "RELOADING=1",
+  watchdog:  "WATCHDOG=1",
+});
+
+function _notifySocketPath() {
+  var p = safeEnv.readVar("NOTIFY_SOCKET");
+  if (typeof p !== "string" || p.length === 0) return null;
+  // Abstract namespace socket (Linux-only) prefixed with `@` —
+  // systemd-notify(1) accepts the same form, so we don't normalize.
+  return p;
+}
+
+function _runNotify(payload) {
+  return new Promise(function (resolve, reject) {
+    var args = [];
+    var lines = String(payload).split("\n");
+    for (var i = 0; i < lines.length; i += 1) {
+      if (lines[i].length > 0) args.push(lines[i]);
+    }
+    if (args.length === 0) { resolve(); return; }
+    // execFile (not exec) — no shell evaluation; the message bytes
+    // pass through argv exactly. systemd-notify accepts one or more
+    // KEY=VALUE arguments. The `--no-block` flag returns immediately
+    // without waiting for the notification to be processed.
+    execFile("systemd-notify", ["--no-block"].concat(args),
+      { timeout: C.TIME.seconds(5), windowsHide: true },
+      function (err) {
+        if (err) reject(err);
+        else resolve();
+      });
+  });
+}
+
+/**
+ * @primitive b.sdNotify.send
+ * @signature b.sdNotify.send(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.ready, b.sdNotify.stopping, b.appShutdown.create
+ *
+ * Generic sd_notify dispatch. Sends one or more `KEY=VALUE` payload
+ * lines to systemd via `systemd-notify(1)`. No-op when
+ * `$NOTIFY_SOCKET` is unset (foreground / container without
+ * `--notify-ready` / non-systemd init). Returns a Promise resolving
+ * on dispatch success.
+ *
+ * @opts
+ *   state:    string,                     // e.g. "READY=1" / "STOPPING=1"
+ *   status:   string,                     // free-form status text → `STATUS=`
+ *   mainpid:  number,                     // PID override → `MAINPID=`
+ *   audit:    boolean,                     // default true
+ *
+ * @example
+ *   await b.sdNotify.send({ state: "READY=1", status: "Listening on :8080" });
+ */
+function send(opts) {
+  opts = opts || {};
+  var lines = [];
+  if (typeof opts.state === "string" && opts.state.length > 0) lines.push(opts.state);
+  if (typeof opts.status === "string" && opts.status.length > 0) {
+    // STATUS= permits arbitrary UTF-8 except newline — refuse newline
+    // so a hostile status string can't smuggle a second key.
+    if (opts.status.indexOf("\n") !== -1 || opts.status.indexOf("\r") !== -1) {
+      throw new SdNotifyError("sd-notify/control-char-in-status",
+        "send: status field must not contain CR/LF (sd_notify framing)");
+    }
+    lines.push("STATUS=" + opts.status);
+  }
+  if (opts.mainpid !== undefined) {
+    if (typeof opts.mainpid !== "number" || !isFinite(opts.mainpid) ||
+        Math.floor(opts.mainpid) !== opts.mainpid || opts.mainpid < 1) {
+      throw new SdNotifyError("sd-notify/bad-mainpid",
+        "send: mainpid must be a positive integer");
+    }
+    lines.push("MAINPID=" + opts.mainpid);
+  }
+  if (lines.length === 0) return Promise.resolve();
+
+  var socketPath = _notifySocketPath();
+  if (socketPath === null) {
+    if (opts.audit !== false) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send.skipped",
+          outcome:  "denied",
+          metadata: { reason: "no-notify-socket", state: opts.state || null },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    return Promise.resolve();
+  }
+  var auditOn = opts.audit !== false;
+  return _runNotify(lines.join("\n")).then(function () {
+    if (auditOn) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send",
+          outcome:  "success",
+          metadata: { state: opts.state || null, status: opts.status || null },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+  }).catch(function (err) {
+    if (auditOn) {
+      try {
+        audit.safeEmit({
+          action:   "sdnotify.send",
+          outcome:  "failure",
+          metadata: { state: opts.state || null, error: (err && err.message) || String(err) },
+        });
+      } catch (_e2) { /* drop-silent */ }
+    }
+    throw new SdNotifyError("sd-notify/dispatch-failed",
+      "send: systemd-notify dispatch failed: " + ((err && err.message) || String(err)));
+  });
+}
+
+/**
+ * @primitive b.sdNotify.ready
+ * @signature b.sdNotify.ready(opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.send, b.sdNotify.stopping
+ *
+ * Send `READY=1` to systemd, signaling boot complete. Use once the
+ * listener is bound and the daemon is accepting work.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   await b.sdNotify.ready({ status: "Listening on :8080" });
+ */
+function ready(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.ready }));
+}
+
+/**
+ * @primitive b.sdNotify.stopping
+ * @signature b.sdNotify.stopping(opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.sdNotify.send, b.appShutdown.create
+ *
+ * Send `STOPPING=1`. Operators wire this into `b.appShutdown` as the
+ * earliest shutdown phase (priority 0) so systemd sees the shutdown
+ * intent before any teardown begins.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   b.appShutdown.create({ name: "sd-notify-stopping", priority: 0,
+ *     run: function () { return b.sdNotify.stopping(); } });
+ */
+function stopping(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.stopping }));
+}
+
+/**
+ * @primitive b.sdNotify.reloading
+ * @signature b.sdNotify.reloading(opts?)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Send `RELOADING=1` then (after the reload completes) `READY=1`.
+ * Use during hot-config-reload paths; systemd treats the unit as
+ * "reloading" until the next `READY=1`.
+ *
+ * @opts
+ *   status:  string,    // free-form status text → STATUS=
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   await b.sdNotify.reloading();
+ *   await reloadConfig();
+ *   await b.sdNotify.ready();
+ */
+function reloading(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.reloading }));
+}
+
+/**
+ * @primitive b.sdNotify.watchdog
+ * @signature b.sdNotify.watchdog(opts?)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Send `WATCHDOG=1`. Operators with `WatchdogSec=` configured on
+ * their unit call this periodically (e.g. every `WatchdogSec/2`)
+ * so systemd auto-restarts the daemon when the event loop wedges.
+ *
+ * @opts
+ *   audit:   boolean,    // default true
+ *
+ * @example
+ *   setInterval(function () { b.sdNotify.watchdog(); }, 15000);
+ */
+function watchdog(opts) {
+  return send(Object.assign({}, opts || {}, { state: KNOWN_STATES.watchdog }));
+}
+
+module.exports = {
+  send:          send,
+  ready:         ready,
+  stopping:      stopping,
+  reloading:     reloading,
+  watchdog:      watchdog,
+  isAvailable:   function () { return _notifySocketPath() !== null; },
+  SdNotifyError: SdNotifyError,
+};

package/package.json

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