@blamejs/core 0.8.43 → 0.8.50

package/lib/sandbox.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * b.sandbox - isolation harness for operator-supplied transforms.
+ *
+ * Some primitives (b.template with sandbox: true, custom audit-export
+ * formatters, response-shape rewriters, ETL hooks) need to run JS
+ * source the operator wrote against per-request input. In-process eval
+ * gives that source the framework full module graph: filesystem,
+ * network, process, child_process, the entire b.* surface, vault keys,
+ * and audit-bypass via direct DB writes. b.sandbox runs the source
+ * inside a fresh worker_threads.Worker with strict resource limits and
+ * a hand-built scope that exposes ONLY the globals the operator
+ * allowlists at create() time.
+ *
+ *   var result = await b.sandbox.run({
+ *     source:    "return { upper: input.name.toUpperCase() };",
+ *     input:     { name: "alice" },
+ *     timeoutMs: 250,
+ *     maxBytes:  C.BYTES.mib(8),
+ *     allowed:   ["JSON", "Math", "Date"],
+ *   });
+ *   // result -> { result: { upper: "ALICE" }, runtimeMs: 12, peakBytes: 4194304 }
+ *
+ * Default-deny posture (lib/sandbox-worker.js docstring has the full list):
+ *   - No require / process / Buffer / setTimeout / setImmediate /
+ *     setInterval / queueMicrotask / global. The bootstrap deletes
+ *     each off globalThis BEFORE compiling operator source.
+ *   - No filesystem / network / child_process / spawn / dns -
+ *     unreachable once require is gone.
+ *   - No worker re-entry - worker_threads itself unreachable.
+ *   - Timeout (default: 250ms, max: 10s) terminates the worker.
+ *   - Heap caps (maxOldGenerationSizeMb / maxYoungGenerationSizeMb)
+ *     derived from maxBytes; v8 kills the worker on overflow.
+ *   - Result size cap = maxBytes / 4.
+ *
+ * Allowed-globals list:
+ *   The allowed opt names which extra globals operator source may
+ *   reference. The list is intersected against KNOWN_SAFE_BUILTINS at
+ *   the host before being shipped to the worker - anything outside
+ *   the allowlist refuses at the call site. JS-language primitives
+ *   (Object, Array, String, Number, Boolean, Symbol, Promise, Error,
+ *   TypeError, RangeError, RegExp) survive regardless because they
+ *   cannot be removed without breaking literal expressions.
+ *
+ * Composability with b.template:
+ *   b.template.create({ sandbox: true }) routes operator-supplied
+ *   helper-function bodies through b.sandbox before exposing them as
+ *   helpers in the template scope. The template engine itself remains
+ *   eval-free - sandbox is the secondary defense for the rare cases
+ *   where an operator NEEDS to ship a transform alongside a template
+ *   (date formatters with locale-dependent fallbacks, etc.).
+ *
+ * Audit shape:
+ *   - sandbox.run         - outcome=success; metadata: { runtimeMs, peakBytes, sourceBytes }
+ *   - sandbox.run.refused - outcome=failure; metadata: { reason, runtimeMs, peakBytes, sourceBytes }
+ *
+ * Failure modes (every one throws SandboxError):
+ *   - sandbox/bad-opts            - unknown opts key
+ *   - sandbox/bad-source          - source is not a non-empty string
+ *   - sandbox/bad-allowed         - allowed contains non-string or non-allowlisted name
+ *   - sandbox/bad-timeout         - timeoutMs is not a positive finite int (or > MAX_TIMEOUT_MS)
+ *   - sandbox/bad-max-bytes       - maxBytes is not a positive finite int (or out of range)
+ *   - sandbox/bad-input           - input is not JSON-serializable
+ *   - sandbox/input-too-large     - JSON.stringify(input).length > maxBytes
+ *   - sandbox/timeout             - worker exceeded timeoutMs
+ *   - sandbox/oversized-result    - worker output > maxBytes / 4
+ *   - sandbox/parse-error         - source did not parse inside the worker
+ *   - sandbox/runtime-error       - operator transform threw
+ *   - sandbox/spawn-failed        - worker thread failed to spawn
+ *   - sandbox/worker-error        - worker thread errored after spawn
+ *   - sandbox/worker-nonzero-exit - worker died (heap-cap kill class)
+ *   - sandbox/no-result           - worker exited without posting (heap-cap class)
+ *   - sandbox/no-worker-threads   - runtime lacks node:worker_threads
+ *
+ * Operators feeding untrusted source MUST also pair this with their
+ * own posture (operator-uploaded transforms only after a code-review
+ * gate, etc.) - sandbox is one defense layer, not a license to accept
+ * arbitrary source from the public internet.
+ */
+
+var path = require("path");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var constants = require("./constants");
+var { SandboxError } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// Built-in allowlist for the allowed opt. Filesystem / network /
+// process / require are deliberately absent. JS-language primitives
+// stay reachable inside the worker regardless of this list.
+var KNOWN_SAFE_BUILTINS = Object.freeze({
+  JSON:         true, Math:         true, Date:         true,
+  Map:          true, Set:          true, WeakMap:      true, WeakSet: true,
+  RegExp:       true, Error:        true, TypeError:    true, RangeError: true,
+  Number:       true, String:       true, Boolean:      true,
+  Array:        true, Object:       true, ArrayBuffer:  true,
+  Uint8Array:   true, Uint16Array:  true, Uint32Array:  true,
+  Int8Array:    true, Int16Array:   true, Int32Array:   true,
+  Float32Array: true, Float64Array: true,
+  DataView:     true, Symbol:       true, Promise:      true,
+});
+
+// JS-language primitives that survive regardless of allowlist -
+// stripping these would mean operator transforms cannot evaluate
+// even simple literals. Mirrors lib/sandbox-worker.js.
+var ALWAYS_AVAILABLE = Object.freeze([
+  "Object", "Array", "String", "Number", "Boolean", "Symbol",
+  "Promise", "Error", "TypeError", "RangeError", "RegExp",
+]);
+
+var WORKER_PATH = path.resolve(__dirname, "sandbox-worker.js");
+
+// Default caps. Sourced from C.* helpers so the unit lives at the call site.
+var DEFAULT_TIMEOUT_MS = 250;
+var MAX_TIMEOUT_MS = constants.TIME.seconds(10);
+var DEFAULT_MAX_BYTES = constants.BYTES.mib(64);
+var MAX_MAX_BYTES = constants.BYTES.gib(1);
+var MIN_MAX_BYTES = constants.BYTES.mib(4);
+
+function _validateAllowed(allowed) {
+  if (allowed === undefined || allowed === null) return [];
+  if (!Array.isArray(allowed)) {
+    throw new SandboxError("sandbox/bad-allowed",
+      "sandbox.run: opts.allowed must be an array of identifier strings");
+  }
+  var out = [];
+  for (var i = 0; i < allowed.length; i += 1) {
+    var name = allowed[i];
+    if (typeof name !== "string" || name.length === 0) {
+      throw new SandboxError("sandbox/bad-allowed",
+        "sandbox.run: opts.allowed[" + i + "] must be a non-empty identifier string");
+    }
+    if (!KNOWN_SAFE_BUILTINS[name]) {
+      throw new SandboxError("sandbox/bad-allowed",
+        "sandbox.run: opts.allowed[" + i + "] = " + JSON.stringify(name) +
+        " is not in the sandbox built-in allowlist " +
+        "(known-safe: " + Object.keys(KNOWN_SAFE_BUILTINS).join(", ") + ")");
+    }
+    if (out.indexOf(name) === -1) out.push(name);
+  }
+  return out;
+}
+
+function _emitAudit(action, outcome, metadata) {
+  try {
+    audit().safeEmit({
+      action:   action,
+      outcome:  outcome,
+      metadata: metadata,
+    });
+  } catch (_e) { /* drop-silent - audit best-effort */ }
+}
+
+function run(opts) {
+  opts = opts || {};
+  try {
+    validateOpts(opts, ["source", "input", "timeoutMs", "maxBytes", "allowed"], "sandbox.run");
+  } catch (e) { return Promise.reject(new SandboxError("sandbox/bad-opts", e.message)); }
+
+  try {
+    validateOpts.requireNonEmptyString(opts.source,
+      "sandbox.run: opts.source", SandboxError, "sandbox/bad-source");
+  } catch (e) { return Promise.reject(e); }
+  var sourceBytes = Buffer.byteLength(opts.source, "utf8");
+
+  var timeoutMs;
+  try {
+    timeoutMs = (opts.timeoutMs === undefined) ? DEFAULT_TIMEOUT_MS : opts.timeoutMs;
+    numericBounds.requirePositiveFiniteIntIfPresent(timeoutMs,
+      "sandbox.run: opts.timeoutMs", SandboxError, "sandbox/bad-timeout");
+  } catch (e) { return Promise.reject(e); }
+  if (timeoutMs > MAX_TIMEOUT_MS) {
+    return Promise.reject(new SandboxError("sandbox/bad-timeout",
+      "sandbox.run: opts.timeoutMs (" + timeoutMs + ") exceeds the framework cap of " + MAX_TIMEOUT_MS + " ms"));
+  }
+
+  var maxBytes;
+  try {
+    maxBytes = (opts.maxBytes === undefined) ? DEFAULT_MAX_BYTES : opts.maxBytes;
+    numericBounds.requirePositiveFiniteIntIfPresent(maxBytes,
+      "sandbox.run: opts.maxBytes", SandboxError, "sandbox/bad-max-bytes");
+  } catch (e) { return Promise.reject(e); }
+  if (maxBytes < MIN_MAX_BYTES) {
+    return Promise.reject(new SandboxError("sandbox/bad-max-bytes",
+      "sandbox.run: opts.maxBytes (" + maxBytes + ") below the framework floor of " + MIN_MAX_BYTES + " bytes"));
+  }
+  if (maxBytes > MAX_MAX_BYTES) {
+    return Promise.reject(new SandboxError("sandbox/bad-max-bytes",
+      "sandbox.run: opts.maxBytes (" + maxBytes + ") exceeds the framework cap of " + MAX_MAX_BYTES + " bytes"));
+  }
+
+  var allowedGlobals;
+  try { allowedGlobals = _validateAllowed(opts.allowed); }
+  catch (e) { return Promise.reject(e); }
+
+  var inputJson;
+  try { inputJson = (opts.input === undefined) ? null : JSON.stringify(opts.input); }
+  catch (eSer) {
+    return Promise.reject(new SandboxError("sandbox/bad-input",
+      "sandbox.run: opts.input is not JSON-serializable: " + (eSer && eSer.message)));
+  }
+  if (inputJson !== null && inputJson.length > maxBytes) {
+    return Promise.reject(new SandboxError("sandbox/input-too-large",
+      "sandbox.run: opts.input serialized to " + inputJson.length + " bytes (>" + maxBytes + ")"));
+  }
+
+  var workerThreads;
+  try { workerThreads = require("node:worker_threads"); }
+  catch (_e) {
+    return Promise.reject(new SandboxError("sandbox/no-worker-threads",
+      "sandbox.run: node:worker_threads is unavailable in this runtime"));
+  }
+
+  // resourceLimits in MiB. Derive from maxBytes - keep a small headroom
+  // floor so the worker can boot. Round each cap down to a MiB integer.
+  // Floors / caps are quanta of MiB chosen to fit a small embedded
+  // worker; passed straight to v8's resourceLimits.
+  var oneMib = constants.BYTES.mib(1);
+  // The MiB-unit caps below are integers passed directly to v8's
+  // resourceLimits (already typed in MiB by the v8 API), not byte
+  // counts - the constants helpers don't apply.
+  var minHeapFloorMib = 64;     // allow:raw-byte-literal — MiB unit count, not bytes
+  var youngGenCapMib  = 32;     // allow:raw-byte-literal — MiB unit count, not bytes
+  var youngGenFloorMib = 8;     // allow:raw-byte-literal — MiB unit count, not bytes
+  var codeRangeCapMib = 16;     // allow:raw-byte-literal — MiB unit count, not bytes
+  var codeRangeFloorMib = 8;    // allow:raw-byte-literal — MiB unit count, not bytes
+  var stackMib = 4;             // MiB unit count, not bytes
+  var heapMib = Math.max(minHeapFloorMib, Math.floor(maxBytes / oneMib));
+  var resourceLimits = {
+    maxOldGenerationSizeMb:   heapMib,
+    maxYoungGenerationSizeMb: Math.max(youngGenFloorMib, Math.min(heapMib, youngGenCapMib)),
+    codeRangeSizeMb:          Math.max(codeRangeFloorMib, Math.min(heapMib, codeRangeCapMib)),
+    stackSizeMb:              stackMib,
+  };
+
+  // Reserve 1/4 of maxBytes as the per-result hard cap. The worker
+  // refuses any result whose stringified form exceeds this.
+  var maxResultBytes = Math.floor(maxBytes / 4);
+
+  return new Promise(function (resolve, reject) {
+    var startedAt = Date.now();
+    var settled = false;
+    var worker;
+    try {
+      worker = new workerThreads.Worker(WORKER_PATH, {
+        workerData: {
+          source:          opts.source,
+          input:           opts.input,
+          allowedGlobals:  allowedGlobals,
+          maxResultBytes:  maxResultBytes,
+        },
+        resourceLimits: resourceLimits,
+        stdout: true,
+        stderr: true,
+      });
+    } catch (eSpawn) {
+      var spawnRuntimeMs = Date.now() - startedAt;
+      _emitAudit("sandbox.run.refused", "failure", {
+        reason: "sandbox/spawn-failed", runtimeMs: spawnRuntimeMs, peakBytes: 0, sourceBytes: sourceBytes,
+      });
+      reject(new SandboxError("sandbox/spawn-failed",
+        "sandbox.run: failed to spawn worker: " + (eSpawn && eSpawn.message)));
+      return;
+    }
+
+    var timer = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      try { worker.terminate(); } catch (_e) { /* terminate best-effort */ }
+      var elapsed = Date.now() - startedAt;
+      _emitAudit("sandbox.run.refused", "failure", {
+        reason: "sandbox/timeout", runtimeMs: elapsed, peakBytes: 0, sourceBytes: sourceBytes,
+      });
+      reject(new SandboxError("sandbox/timeout",
+        "sandbox.run: worker exceeded timeoutMs=" + timeoutMs + " (elapsed " + elapsed + "ms)"));
+    }, timeoutMs);
+
+    worker.on("message", function (msg) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { worker.terminate(); } catch (_e) { /* terminate best-effort */ }
+      if (!msg || typeof msg !== "object") {
+        _emitAudit("sandbox.run.refused", "failure", {
+          reason: "sandbox/bad-worker-message", runtimeMs: Date.now() - startedAt, peakBytes: 0, sourceBytes: sourceBytes,
+        });
+        return reject(new SandboxError("sandbox/bad-worker-message",
+          "sandbox.run: worker returned a non-object message"));
+      }
+      var runtimeMs = (typeof msg.runtimeMs === "number") ? msg.runtimeMs : (Date.now() - startedAt);
+      var peakBytes = (typeof msg.peakBytes === "number") ? msg.peakBytes : 0;
+      if (msg.ok) {
+        var parsed;
+        try { parsed = (msg.resultJson === undefined) ? undefined : JSON.parse(msg.resultJson); }   // allow:bare-json-parse — resultJson is produced by lib/sandbox-worker.js via JSON.stringify and bounded by maxResultBytes; never directly from operator/network input
+        catch (eParse) {
+          _emitAudit("sandbox.run.refused", "failure", {
+            reason: "sandbox/bad-result-json", runtimeMs: runtimeMs, peakBytes: peakBytes, sourceBytes: sourceBytes,
+          });
+          return reject(new SandboxError("sandbox/bad-result-json",
+            "sandbox.run: worker result was not parseable JSON: " + (eParse && eParse.message)));
+        }
+        _emitAudit("sandbox.run", "success", {
+          runtimeMs: runtimeMs, peakBytes: peakBytes, sourceBytes: sourceBytes,
+        });
+        return resolve({ result: parsed, runtimeMs: runtimeMs, peakBytes: peakBytes });
+      }
+      _emitAudit("sandbox.run.refused", "failure", {
+        reason: msg.code || "sandbox/runtime-error", runtimeMs: runtimeMs, peakBytes: peakBytes, sourceBytes: sourceBytes,
+      });
+      return reject(new SandboxError(msg.code || "sandbox/runtime-error",
+        msg.message || "sandbox.run: worker reported a refusal"));
+    });
+
+    worker.on("error", function (err) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      var elapsed = Date.now() - startedAt;
+      _emitAudit("sandbox.run.refused", "failure", {
+        reason: "sandbox/worker-error", runtimeMs: elapsed, peakBytes: 0, sourceBytes: sourceBytes,
+      });
+      reject(new SandboxError("sandbox/worker-error",
+        "sandbox.run: worker errored: " + (err && err.message ? err.message : String(err))));
+    });
+
+    worker.on("exit", function (code) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      var elapsed = Date.now() - startedAt;
+      // Code 0 with no message means the worker exited without posting -
+      // usually a heap-cap kill. Surface as oversized.
+      var reason = (code === 0) ? "sandbox/no-result" : "sandbox/worker-nonzero-exit";
+      var message = (code === 0)
+        ? "sandbox.run: worker exited without posting a result (heap cap or premature return)"
+        : "sandbox.run: worker exited with code " + code + " (likely resource-limit kill)";
+      _emitAudit("sandbox.run.refused", "failure", {
+        reason: reason, runtimeMs: elapsed, peakBytes: 0, sourceBytes: sourceBytes,
+      });
+      reject(new SandboxError(reason, message));
+    });
+  });
+}
+
+module.exports = {
+  run:                  run,
+  KNOWN_SAFE_BUILTINS:  KNOWN_SAFE_BUILTINS,
+  ALWAYS_AVAILABLE:     ALWAYS_AVAILABLE,
+  DEFAULT_TIMEOUT_MS:   DEFAULT_TIMEOUT_MS,
+  MAX_TIMEOUT_MS:       MAX_TIMEOUT_MS,
+  DEFAULT_MAX_BYTES:    DEFAULT_MAX_BYTES,
+  MAX_MAX_BYTES:        MAX_MAX_BYTES,
+  MIN_MAX_BYTES:        MIN_MAX_BYTES,
+  WORKER_PATH:          WORKER_PATH,
+  SandboxError:         SandboxError,
+};

package/lib/scheduler.js

@@ -1,76 +1,42 @@
 "use strict";
 /**
- * scheduler — cron + interval scheduler over lib/jobs (or direct fn).
+ * @module b.scheduler
+ * @featured true
+ * @nav    Production
+ * @title  Scheduler
  *
- * The framework's primitive for "run X at Y" — backed by jobs/queue
- * for retries, audit, and cluster-aware dispatch, with a direct-fn
- * escape hatch for the simple cases.
+ * @intro
+ *   Cron-style task scheduler with cluster leader gating, deduplicated
+ *   ticks, drift correction, and an audit event on every tick.
  *
- *   var sched = b.scheduler.create({
- *     jobs:    jobsInstance,    // optional; needed for { job: "name" }
- *     cluster: b.cluster,       // optional; gates fires to leader only
- *     audit:   true,            // default true
- *   });
- *
- *   sched.schedule({
- *     name:     "nightly-cleanup",
- *     cron:     "0 2 * * *",        // POSIX 5-field cron
- *     timezone: "America/New_York", // IANA name; default = server-local
- *     job:      "cleanup",          // dispatched via jobs.enqueue
- *     payload:  { scope: "all" },
- *   });
- *
- *   sched.schedule({
- *     name:     "stats-aggregation",
- *     every:    300000,             // ms between runs
- *     baseline: "00:00",            // HH:MM anchor (optional)
- *     timezone: "America/New_York",
- *     job:      "aggregate-stats",
- *   });
- *
- *   sched.schedule({
- *     name:  "heartbeat",
- *     every: 60000,
- *     run:   async function () { … },  // direct function (no jobs needed)
- *   });
+ *   Two registration shapes share the same engine: 5-field POSIX cron
+ *   (`"0 2 * * *"`) for wall-clock schedules and `every: ms` (with an
+ *   optional `baseline: "HH:MM"` anchor) for interval schedules.
+ *   Timezones are IANA names; without one the schedule follows the
+ *   server's local clock. Cron shorthands `@hourly`, `@daily`,
+ *   `@midnight`, `@weekly`, `@monthly`, `@yearly` and `@annually` are
+ *   accepted.
  *
- *   await sched.start();   // arms timers
- *   await sched.stop();    // clears timers, drops pending fires
+ *   When opts.cluster is wired, fires are gated to the current leader.
+ *   Every fire INSERTs a row into _blamejs_scheduler_ticks keyed on
+ *   (name, scheduledAtUnix); the PRIMARY KEY race deduplicates across a
+ *   split-brain window — losers increment task.tickClaimLost and skip.
+ *   Tick-claim rows older than opts.tickRetentionMs (default 7 days)
+ *   are pruned automatically by the leader, throttled to at most one
+ *   sweep per opts.pruneIntervalMs (default 60s). Operators can force a
+ *   sweep with sched.pruneTickClaims(olderThanMs?).
  *
- *   sched.list();          // → [{ name, when, lastRun, nextRun, running }]
+ *   Drift correction: nextRun is computed forward from now (not from
+ *   the nominal scheduled time) so a long-running fire never queues a
+ *   backlog of catch-up ticks. A watchdog clears the `running` flag if
+ *   a fire's promise hasn't settled after opts.maxJobMs (default 10
+ *   minutes) so a hung handler can't permanently lock out future fires.
+ *   Every state transition emits an audit event under
+ *   `system.scheduler.*` so operators see every fire, miss, watchdog
+ *   reset, and tick-claim race in their audit log.
  *
- * Cron grammar (5 fields, space-separated):
- *
- *   minute (0–59)  hour (0–23)  dom (1–31)  month (1–12)  dow (0–7; 0/7=Sun)
- *
- * Each field accepts:  *  N  N,M,…  A-B  *\/N  A-B/N
- *
- * Shorthands: @hourly @daily @midnight @weekly @monthly @yearly @annually
- *
- * Cluster gating: when opts.cluster is wired and the local node is not
- * the leader, schedule fires no-op. The leader still computes nextRun
- * locally so a leader transition picks up cleanly.
- *
- * Exactly-once-globally: when opts.cluster is wired, every fire first
- * INSERTs a row into _blamejs_scheduler_ticks keyed on (taskName,
- * scheduledAtUnix). The PRIMARY KEY race ensures that even if two
- * nodes briefly believe they are the leader (split-brain on lease
- * boundary), only the row-winner runs the task. The loser increments
- * task.tickClaimLost (visible via list()) and skips silently. Task
- * handlers should still be idempotent — operators may add jobs.enqueue
- * dedup keys for defense-in-depth.
- *
- * Tick-claim retention: rows older than opts.tickRetentionMs (default
- * 7 days) are pruned automatically — at most once per opts.pruneInterval
- * Ms (default 60s) — by the leader on its next successful fire. Operators
- * can also call sched.pruneTickClaims(olderThanMs?) on demand to force
- * a sweep (e.g. from a maintenance script) and observe the count via
- * the system.scheduler.tick.pruned audit event.
- *
- * Watchdog: if a fire's promise hasn't settled after MAX_JOB_MS
- * (10min default; opts.maxJobMs to override), the running flag is
- * force-cleared and a warning emitted, so a hung job doesn't lock out
- * future fires.
+ * @card
+ *   Cron-style task scheduler with cluster leader gating, deduplicated ticks, drift correction, and an audit event on every tick.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -168,6 +134,29 @@ function _parseCronField(text, range) {
   return set;
 }
 
+/**
+ * @primitive b.scheduler.parseCron
+ * @signature b.scheduler.parseCron(expr)
+ * @since     0.5.0
+ * @related   b.scheduler.create, b.scheduler.nextCronFire
+ *
+ * Parse a 5-field POSIX cron expression (or one of the `@hourly`,
+ * `@daily`, `@midnight`, `@weekly`, `@monthly`, `@yearly`, `@annually`
+ * shorthands) into a struct of populated minute / hour / dom / month /
+ * dow sets plus the normalized expression text. Throws SchedulerError
+ * (`scheduler/invalid-cron`) on malformed input — empty fields, bad
+ * step / range syntax, or values outside each field's bounds. The
+ * `dow` field accepts both 0 and 7 for Sunday and normalizes to 0.
+ *
+ * @example
+ *   var cron = b.scheduler.parseCron("0 2 * * *");
+ *   cron.expr;             // → "0 2 * * *"
+ *   cron.minute.has(0);    // → true
+ *   cron.hour.has(2);      // → true
+ *
+ *   var weekly = b.scheduler.parseCron("@weekly");
+ *   weekly.expr;           // → "0 0 * * 0"
+ */
 function parseCron(expr) {
   if (typeof expr !== "string" || expr.length === 0) {
     throw new SchedulerError("scheduler/invalid-cron",
@@ -268,9 +257,27 @@ function _matchesCron(cron, parts) {
   return true; // both fully wild
 }
 
-// nextCronFire — earliest UTC ms ≥ `after` whose wall-clock in `tz`
-// matches the cron sets. Walks minute by minute; bounded at ~530K
-// iterations (1 year of minutes) before giving up with a clear error.
+/**
+ * @primitive b.scheduler.nextCronFire
+ * @signature b.scheduler.nextCronFire(cron, after, timeZone)
+ * @since     0.5.0
+ * @related   b.scheduler.parseCron, b.scheduler.nextBaselineFire
+ *
+ * Earliest UTC millisecond strictly after `after` whose wall-clock in
+ * `timeZone` matches the parsed cron sets. Walks minute-by-minute; the
+ * search is bounded at one year plus a one-hour DST cushion before
+ * throwing SchedulerError (`scheduler/cron-no-fire`) so an impossible
+ * date constraint surfaces loudly instead of looping forever. Pass
+ * `null` for `timeZone` to follow the server's local clock.
+ *
+ * @example
+ *   var cron = b.scheduler.parseCron("0 2 * * *");
+ *   var when = b.scheduler.nextCronFire(cron, new Date("2026-05-09T00:00:00Z"), "UTC");
+ *   new Date(when).toISOString();
+ *   // → "2026-05-09T02:00:00.000Z"
+ */
+// Walks minute by minute; bounded at ~530K iterations (1 year of
+// minutes) before giving up with a clear error.
 function nextCronFire(cron, after, timeZone) {
   var MINUTE_MS = C.TIME.minutes(1);
   // Round up to the next whole minute boundary
@@ -288,7 +295,28 @@ function nextCronFire(cron, after, timeZone) {
     "(impossible date constraint?)", true);
 }
 
-// nextBaselineFire — next UTC ms whose wall-clock in `tz` matches HH:MM.
+/**
+ * @primitive b.scheduler.nextBaselineFire
+ * @signature b.scheduler.nextBaselineFire(timeOfDay, timeZone, after)
+ * @since     0.5.0
+ * @related   b.scheduler.nextCronFire, b.scheduler.create
+ *
+ * Earliest UTC millisecond strictly after `after` whose wall-clock in
+ * `timeZone` matches the supplied `HH:MM` time-of-day. Used internally
+ * to anchor `every`-shaped tasks to a daily baseline; exposed so
+ * operators can compute the same instant for fixtures or external
+ * coordination. Throws SchedulerError on malformed input
+ * (`scheduler/invalid-baseline`) or on a no-fire-within-24h timezone
+ * bug (`scheduler/baseline-no-fire`). Pass `null` for `timeZone` to
+ * follow the server's local clock.
+ *
+ * @example
+ *   var when = b.scheduler.nextBaselineFire(
+ *     "02:30", "UTC", new Date("2026-05-09T01:00:00Z")
+ *   );
+ *   new Date(when).toISOString();
+ *   // → "2026-05-09T02:30:00.000Z"
+ */
 function nextBaselineFire(timeOfDay, timeZone, after) {
   var match = String(timeOfDay).match(/^(\d{1,2}):(\d{2})$/);
   if (!match) {
@@ -316,6 +344,43 @@ function nextBaselineFire(timeOfDay, timeZone, after) {
 
 // ---- Engine ----
 
+/**
+ * @primitive b.scheduler.create
+ * @signature b.scheduler.create(opts)
+ * @since     0.5.0
+ * @related   b.scheduler.parseCron, b.cluster.init, b.jobs.create
+ *
+ * Build a scheduler instance. Returns a facade exposing `schedule`,
+ * `register`, `start`, `stop`, `list`, `getStatus`, and
+ * `pruneTickClaims`. Tasks are registered before `start()`; `start()`
+ * arms timers, `stop()` clears them and drops pending fires. When
+ * `opts.cluster` is supplied, fires are gated to the leader and a
+ * tick-claim row in `_blamejs_scheduler_ticks` deduplicates split-brain
+ * windows. When `opts.jobs` is supplied, tasks declared with
+ * `{ job: "name" }` dispatch via the jobs queue; tasks declared with
+ * `{ run: fn }` execute the function directly.
+ *
+ * @opts
+ *   jobs:            object,    // optional jobs instance for { job: "name" } tasks
+ *   cluster:         object,    // optional cluster instance — gates fires to leader
+ *   audit:           boolean,   // emit system.scheduler.* audit events (default true)
+ *   maxJobMs:        number,    // watchdog reset threshold (default 10 minutes)
+ *   tickRetentionMs: number,    // tick-claim row retention (default 7 days)
+ *   pruneIntervalMs: number,    // throttle for opportunistic prune (default 60s)
+ *
+ * @example
+ *   var sched = b.scheduler.create({ audit: true });
+ *   sched.schedule({
+ *     name: "nightly-cleanup",
+ *     cron: "0 2 * * *",
+ *     timezone: "UTC",
+ *     run: async function () { return "ok"; },
+ *   });
+ *   await sched.start();
+ *   var snapshot = sched.list();
+ *   snapshot[0].name;           // → "nightly-cleanup"
+ *   await sched.stop();
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [