@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/incident-report.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * b.incident.report — generic 3-stage incident-reporting primitive.
+ *
+ * The three stages mirror the deadline pattern that recurs across
+ * regulatory regimes (GDPR Article 33 / NIS2 Article 23 / DORA
+ * Article 19 / CRA Article 14 / HIPAA Breach Notification Rule):
+ *
+ *   1. Initial / early-warning notification — within 24 hours of
+ *      detection. Operators report what they know: scope, suspected
+ *      cause, immediate-mitigation plan.
+ *   2. Intermediate / status update — within 72 hours of detection.
+ *      Updated impact assessment, root-cause analysis progress,
+ *      operator's response posture.
+ *   3. Final report — within 30 days of detection (or per-regime
+ *      deadline). Full incident narrative, affected-data-subject
+ *      count, remediation, lessons learned.
+ *
+ *   var ir = b.incident.report.create({
+ *     audit:    b.audit,
+ *     persist:  async function (record) { await db.run("INSERT ..."); },
+ *     onStage:  function (event) {
+ *       // event = { incidentId, stage: "initial"|"intermediate"|"final",
+ *       //           dueBy, regime, fields }
+ *     },
+ *     deadlines: {                                  // operator-overridable per regime
+ *       initial:      C.TIME.hours(24),
+ *       intermediate: C.TIME.hours(72),
+ *       final:        C.TIME.days(30),
+ *     },
+ *   });
+ *   var incident = await ir.open({
+ *     regime:       "gdpr",                         // identifies the regulatory regime
+ *     detectedAt:   Date.now(),
+ *     scope:        "data-confidentiality-breach",
+ *     summary:      "...",
+ *     impact:       { dataSubjects: 1200, categories: ["pii", "phi"] },
+ *   });
+ *   await ir.recordInitial(incident.id, { ... });
+ *   await ir.recordIntermediate(incident.id, { ... });
+ *   await ir.recordFinal(incident.id, { ... });
+ *
+ * Each stage records a tamper-evident audit event with the regime,
+ * incident ID, stage, due-by timestamp, and operator-supplied
+ * payload. The `persist` hook writes to the operator's incident
+ * registry (DB / SIEM / SOAR system); audits give regulator-friendly
+ * proof-of-process when the primitive is queried later.
+ *
+ * Late-stage detection (filing past the due-by) is recorded with a
+ * `lateBy` field on the audit metadata and `outcome: "late"`, so
+ * regulator audits can distinguish "filed on time" from "filed late
+ * but eventually". Refusing to record at all would lose the data;
+ * the framework's posture is "always record, always flag late".
+ */
+
+var C = require("./constants");
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var IncidentReportError = defineClass("IncidentReportError", { alwaysPermanent: true });
+
+var DEFAULT_DEADLINES = Object.freeze({
+  initial:      C.TIME.hours(24),
+  intermediate: C.TIME.hours(72),
+  final:        C.TIME.days(30),
+});
+
+var VALID_STAGES = Object.freeze({ initial: 1, intermediate: 1, final: 1 });
+
+// Regime defaults — operators select these via opts.regime so the
+// per-regime deadline shape is the framework default, not something
+// the operator has to redefine each time. Operators with mixed
+// regimes per incident pick the shortest deadline (the "first wall
+// to hit" rule). Per-regime overrides go on opts.deadlines and
+// override the regime defaults.
+var REGIME_DEADLINES = Object.freeze({
+  // GDPR Article 33 §1: notify within 72 hours of awareness.
+  // No formal "initial" stage — the framework adds an internal
+  // 24-hour initial-warning checkpoint as a practical posture.
+  gdpr: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(30),
+  }),
+  // NIS2 Directive Article 23 §4: early warning within 24h, full
+  // notification within 72h, final report within 1 month.
+  nis2: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(30),
+  }),
+  // DORA (EU Digital Operational Resilience Act) Article 19: initial
+  // within 4h of classification, intermediate within 24h, final
+  // within 1 month.
+  dora: Object.freeze({
+    initial:      C.TIME.hours(4),
+    intermediate: C.TIME.hours(24),
+    final:        C.TIME.days(30),
+  }),
+  // CRA (EU Cyber Resilience Act) Article 14: early warning within
+  // 24h, vulnerability/incident notification within 72h, final
+  // report within 14 days.
+  cra: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(14),
+  }),
+  // HIPAA Breach Notification Rule (45 CFR §164.404 etc.): notify
+  // affected individuals within 60 days; HHS within 60 days for
+  // breaches affecting 500+ individuals (annually otherwise). The
+  // initial / intermediate stages have no statutory deadline; we
+  // adopt the EU 24/72-hour internal checkpoints as good operator
+  // practice.
+  hipaa: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(60),
+  }),
+});
+
+function _resolveDeadlines(regime, override) {
+  var base = (regime && REGIME_DEADLINES[regime]) || DEFAULT_DEADLINES;
+  if (!override || typeof override !== "object") return base;
+  return Object.freeze({
+    initial:      typeof override.initial      === "number" ? override.initial      : base.initial,
+    intermediate: typeof override.intermediate === "number" ? override.intermediate : base.intermediate,
+    final:        typeof override.final        === "number" ? override.final        : base.final,
+  });
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "persist", "onStage", "deadlines", "now",
+  ], "incident.report");
+
+  var auditOn = opts.audit !== false;
+  var persist = typeof opts.persist === "function" ? opts.persist : null;
+  var onStage = typeof opts.onStage === "function" ? opts.onStage : null;
+  var deadlinesOverride = opts.deadlines || null;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+
+  // In-memory registry — operators wire `persist` for durable
+  // storage. The in-memory map is for unit tests + small operator
+  // deployments that don't yet wire a DB-backed registry.
+  var incidents = new Map();
+  var seq = 0;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "incident.report." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("incident.report." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  function _genIncidentId(regime, detectedAt) {
+    seq += 1;
+    var ts = new Date(detectedAt).toISOString().replace(/[:.]/g, "-");
+    return "incident-" + (regime || "generic") + "-" + ts + "-" + seq;
+  }
+
+  async function open(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new IncidentReportError("incident-report/bad-spec",
+        "incident.report.open: spec must be an object with { regime, detectedAt, scope, summary, impact }");
+    }
+    if (typeof spec.regime !== "string" || spec.regime.length === 0) {
+      throw new IncidentReportError("incident-report/bad-regime",
+        "incident.report.open: spec.regime must be a non-empty string (gdpr / nis2 / dora / cra / hipaa or operator-defined)");
+    }
+    if (typeof spec.detectedAt !== "number" || !isFinite(spec.detectedAt)) {
+      throw new IncidentReportError("incident-report/bad-detected-at",
+        "incident.report.open: spec.detectedAt must be a finite Unix-ms timestamp");
+    }
+    var deadlines = _resolveDeadlines(spec.regime, deadlinesOverride);
+    var id = _genIncidentId(spec.regime, spec.detectedAt);
+    var record = {
+      id:           id,
+      regime:       spec.regime,
+      detectedAt:   spec.detectedAt,
+      scope:        spec.scope || null,
+      summary:      spec.summary || null,
+      impact:       spec.impact || null,
+      deadlines:    deadlines,
+      dueBy: {
+        initial:      spec.detectedAt + deadlines.initial,
+        intermediate: spec.detectedAt + deadlines.intermediate,
+        final:        spec.detectedAt + deadlines.final,
+      },
+      stages:       {},                                                                  // populated by recordInitial / recordIntermediate / recordFinal
+      openedAt:     now(),
+      closedAt:     null,
+    };
+    incidents.set(id, record);
+    _emitAudit("opened", "success", {
+      incidentId: id, regime: spec.regime, detectedAt: spec.detectedAt,
+      dueByInitial:      record.dueBy.initial,
+      dueByIntermediate: record.dueBy.intermediate,
+      dueByFinal:        record.dueBy.final,
+    });
+    _emitMetric("opened", 1, { regime: spec.regime });
+    if (persist) {
+      try { await persist(record); }
+      catch (e) { _emitAudit("persist_failed", "failure", { incidentId: id, error: (e && e.message) || String(e) }); }
+    }
+    return record;
+  }
+
+  async function _recordStage(incidentId, stage, payload) {
+    if (!VALID_STAGES[stage]) {
+      throw new IncidentReportError("incident-report/bad-stage",
+        "incident.report._recordStage: stage must be one of " + Object.keys(VALID_STAGES).join(", "));
+    }
+    var rec = incidents.get(incidentId);
+    if (!rec) {
+      throw new IncidentReportError("incident-report/unknown-incident",
+        "incident.report: no incident with id '" + incidentId + "'");
+    }
+    if (rec.stages[stage]) {
+      throw new IncidentReportError("incident-report/stage-already-filed",
+        "incident.report: incident '" + incidentId + "' already has a '" + stage + "' stage filing");
+    }
+    var nowMs = now();
+    var dueBy = rec.dueBy[stage];
+    var late = nowMs > dueBy;
+    var lateBy = late ? (nowMs - dueBy) : 0;
+    rec.stages[stage] = {
+      filedAt:  nowMs,
+      dueBy:    dueBy,
+      late:     late,
+      lateBy:   lateBy,
+      payload:  payload || {},
+    };
+    if (stage === "final") rec.closedAt = nowMs;
+
+    _emitAudit("stage_recorded", late ? "late" : "success", {
+      incidentId: incidentId, regime: rec.regime, stage: stage,
+      dueBy: dueBy, filedAt: nowMs, late: late, lateBy: lateBy,
+    });
+    _emitMetric("stage_recorded", 1, { regime: rec.regime, stage: stage, late: String(late) });
+    if (onStage) {
+      try { onStage({ incidentId: incidentId, stage: stage, dueBy: dueBy, late: late, regime: rec.regime, fields: payload }); }
+      catch (_e) { /* drop-silent — operator hook */ }
+    }
+    if (persist) {
+      try { await persist(rec); }
+      catch (e) { _emitAudit("persist_failed", "failure", { incidentId: incidentId, stage: stage, error: (e && e.message) || String(e) }); }
+    }
+    return rec;
+  }
+
+  function recordInitial(incidentId, payload)      { return _recordStage(incidentId, "initial",      payload); }
+  function recordIntermediate(incidentId, payload) { return _recordStage(incidentId, "intermediate", payload); }
+  function recordFinal(incidentId, payload)        { return _recordStage(incidentId, "final",        payload); }
+
+  function get(incidentId) { return incidents.get(incidentId) || null; }
+  function list() {
+    var out = [];
+    incidents.forEach(function (rec) { out.push(rec); });
+    return out;
+  }
+
+  // Operator-facing summary for dashboards / regulator-prep — counts
+  // open / late / closed across all tracked regimes.
+  function status() {
+    var nowMs = now();
+    var summary = {
+      total:  incidents.size,
+      open:   0,
+      closed: 0,
+      late:   { initial: 0, intermediate: 0, final: 0 },
+    };
+    incidents.forEach(function (rec) {
+      if (rec.closedAt) summary.closed += 1; else summary.open += 1;
+      ["initial", "intermediate", "final"].forEach(function (s) {
+        if (!rec.stages[s] && nowMs > rec.dueBy[s]) summary.late[s] += 1;
+        else if (rec.stages[s] && rec.stages[s].late) summary.late[s] += 1;
+      });
+    });
+    return summary;
+  }
+
+  return {
+    open:               open,
+    recordInitial:      recordInitial,
+    recordIntermediate: recordIntermediate,
+    recordFinal:        recordFinal,
+    get:                get,
+    list:               list,
+    status:             status,
+    REGIME_DEADLINES:   REGIME_DEADLINES,
+    DEFAULT_DEADLINES:  DEFAULT_DEADLINES,
+  };
+}
+
+module.exports = {
+  create:                create,
+  IncidentReportError:   IncidentReportError,
+  REGIME_DEADLINES:      REGIME_DEADLINES,
+  DEFAULT_DEADLINES:     DEFAULT_DEADLINES,
+  VALID_STAGES:          Object.keys(VALID_STAGES),
+};

package/lib/vendor/blamejs/lib/ip-utils.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * lib/ip-utils.js — internal IP-address helpers shared across
+ * `b.mail.auth` (SPF / DMARC IP-in-CIDR), `b.mail.rbl` (RFC 5782
+ * reverse-DNS), `b.mail.greylist` (RFC 6647 CIDR fingerprint).
+ *
+ * Not exposed on the operator-facing `b` surface; internal compose
+ * point so the three consumers don't drift on IPv6 parsing.
+ *
+ * RFC 4291 §2.2 IPv6 text form: 8 groups of 1-4 hex characters
+ * separated by `:`; one `::` allowed to compress a contiguous run
+ * of zero groups; IPv4-mapped form `::ffff:1.2.3.4` per RFC 5952 §5
+ * + dual-stack `::a.b.c.d` per RFC 4291 §2.5.5.2.
+ */
+
+/**
+ * Expand an IPv6 address to its full 32-hex-character form. Returns
+ * `null` on parse failure (invalid hex group, group count != 8,
+ * multiple `::`, group > 0xffff).
+ *
+ *   expandIpv6Hex("2001:db8::1")       → "20010db8000000000000000000000001"
+ *   expandIpv6Hex("::ffff:192.0.2.1")  → "00000000000000000000ffffc0000201"
+ *   expandIpv6Hex("::1")               → "00000000000000000000000000000001"
+ *   expandIpv6Hex("bad")               → null
+ */
+function expandIpv6Hex(ip) {
+  if (typeof ip !== "string") return null;
+  // RFC 4291 §2.5.5.2 IPv4-mapped / dual-stack: accept ".d.d.d.d" tail.
+  var dual = ip.match(/^(.*?):(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);                                    // allow:regex-no-length-cap — dotted-quad has fixed shape; LHS bounded by IPv6 group cap below
+  if (dual) {
+    var v4 = dual[2].split(".").map(Number);
+    if (v4.some(function (o) { return !(o >= 0 && o <= 255); })) return null;                            // allow:raw-byte-literal — IPv4 octet range
+    var hi = (v4[0] << 8) | v4[1];                                                                       // allow:raw-byte-literal — 16-bit group pack
+    var lo = (v4[2] << 8) | v4[3];                                                                       // allow:raw-byte-literal — 16-bit group pack
+    ip = dual[1] + ":" + hi.toString(16) + ":" + lo.toString(16);
+  }
+  var dblColon = ip.split("::");
+  if (dblColon.length > 2) return null;
+  var leftGroups  = dblColon[0] === "" ? [] : dblColon[0].split(":");
+  var rightGroups = dblColon.length === 2 ? (dblColon[1] === "" ? [] : dblColon[1].split(":")) : [];
+  if (dblColon.length === 1 && leftGroups.length !== 8) return null;                                      // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  var fillCount = 8 - leftGroups.length - rightGroups.length;                                             // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  if (fillCount < 0) return null;
+  var fill = [];
+  for (var f = 0; f < fillCount; f += 1) fill.push("0");
+  var groups = leftGroups.concat(fill).concat(rightGroups);
+  if (groups.length !== 8) return null;                                                                   // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  var hex = "";
+  for (var i = 0; i < 8; i += 1) {                                                                        // allow:raw-byte-literal — RFC 4291 IPv6 group count
+    var g = groups[i];
+    if (g.length === 0 || g.length > 4) return null;                                                      // allow:raw-byte-literal — RFC 4291 IPv6 hex-group max length
+    for (var hc = 0; hc < g.length; hc += 1) {
+      var cp = g.charCodeAt(hc);
+      var isDigit    = cp >= 0x30 && cp <= 0x39;                                                          // allow:raw-byte-literal — ASCII '0'..'9'
+      var isLowerHex = cp >= 0x61 && cp <= 0x66;                                                          // allow:raw-byte-literal — ASCII 'a'..'f'
+      var isUpperHex = cp >= 0x41 && cp <= 0x46;                                                          // allow:raw-byte-literal — ASCII 'A'..'F'
+      if (!isDigit && !isLowerHex && !isUpperHex) return null;
+    }
+    hex += g.toLowerCase().padStart(4, "0");                                                              // allow:raw-byte-literal — 4 hex chars per IPv6 group
+  }
+  return hex;
+}
+
+/**
+ * Expand IPv6 to an 8-element array of 16-bit unsigned integers.
+ * Used by `b.mail.auth` SPF / DMARC IP-in-CIDR evaluation which
+ * does bitwise group-level math.
+ *
+ *   expandIpv6Groups("::1")   → [0,0,0,0,0,0,0,1]
+ *   expandIpv6Groups("bad")   → null
+ */
+function expandIpv6Groups(ip) {
+  var hex = expandIpv6Hex(ip);
+  if (hex === null) return null;
+  var groups = new Array(8);                                                                              // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  for (var i = 0; i < 8; i += 1) {                                                                        // allow:raw-byte-literal — RFC 4291 IPv6 group count
+    groups[i] = parseInt(hex.slice(i * 4, i * 4 + 4), 16);                                                // allow:raw-byte-literal — 4 hex chars per IPv6 group
+  }
+  return groups;
+}
+
+// Loose IPv4 textual-form check — for primitives that need to
+// classify a string as "looks like dotted-quad IPv4" but don't need
+// the strict per-octet bound check (callers that DO need octet
+// bounds use the strict form in `mail-rbl.js` etc.). Shared so
+// `lib/mail.js`, `lib/mail-helo.js`, and `lib/redis-client.js`
+// don't drift on the same shape.
+//
+//   isIPv4Shape("1.2.3.4")     → true
+//   isIPv4Shape("999.0.0.0")   → true (shape only; octets unbounded)
+//   isIPv4Shape("not-an-ip")   → false
+//   isIPv4Shape("1.2.3")       → false
+var IPV4_SHAPE_RE = /^\d+\.\d+\.\d+\.\d+$/;                                                              // allow:regex-no-length-cap — anchored + literal-dot shape; caller bounds length
+function isIPv4Shape(s) {
+  return typeof s === "string" && IPV4_SHAPE_RE.test(s);
+}
+
+module.exports = {
+  expandIpv6Hex:    expandIpv6Hex,
+  expandIpv6Groups: expandIpv6Groups,
+  isIPv4Shape:      isIPv4Shape,
+};

package/lib/vendor/blamejs/lib/jobs.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * jobs — name → handler registry on top of lib/queue.
+ *
+ * lib/queue handles dispatch (queue backend + lease + retry + breaker
+ * + audit emit). lib/jobs is the application-level pattern most apps
+ * actually use: register a handler ahead of time, enqueue by name,
+ * the framework runs the right code without per-call wiring.
+ *
+ *   var jobs = b.jobs.create();
+ *   jobs.define("send-welcome", async function ({ userId }) { … });
+ *   jobs.define("rebuild-index", async function () { … });
+ *
+ *   await jobs.enqueue("send-welcome", { userId: "u-1" });
+ *
+ *   await jobs.start();      // consumers running
+ *   …
+ *   await jobs.shutdown();   // drain in-flight + stop consuming
+ *
+ * Each defined name maps to one queue (queue named after the job
+ * name) with one consumer per jobs instance. Operators wanting
+ * higher concurrency for a specific job pass concurrency in the
+ * define options.
+ *
+ * Built on b.queue, which must be initialized first:
+ *
+ *   b.queue.init({ backends: { primary: { protocol: "local" } } });
+ *   var jobs = b.jobs.create();
+ *   jobs.define(...);
+ *   await jobs.start();
+ *
+ * createApp wires this for you when opts.jobs is a function — the
+ * factory boots queue with the default 'local' backend, instantiates
+ * a jobs registry, calls opts.jobs(jobs) so the operator defines
+ * handlers, and starts consumption before listen().
+ *
+ * Public API:
+ *
+ *   jobs.create(opts?)            → instance
+ *     opts.queueBackend           — backend name to dispatch through
+ *                                   (default 'primary' — the convention
+ *                                    queue.init uses when given a
+ *                                    single-backend config)
+ *     opts.consumerDefaults       — defaults forwarded to queue.consume
+ *                                   ({ concurrency, leaseDurationMs,
+ *                                      pollIntervalMs, fastPollMs })
+ *     opts.allowUnregisteredEnqueue  default false. When true, jobs.enqueue
+ *                                   accepts names not yet defined
+ *                                   (useful in test fixtures or for
+ *                                    apps that expect lazy handler
+ *                                    registration).
+ *
+ *   jobs.define(name, handler, defineOpts?)
+ *     handler signature: async function (job) { … } where job =
+ *     { jobId, queueName, payload, attempts, maxAttempts, traceId,
+ *       classification, enqueuedAt, leaseExpiresAt }.
+ *     defineOpts is forwarded to queue.consume — concurrency etc.
+ *     Throws if name is already defined.
+ *
+ *   await jobs.enqueue(name, payload, enqueueOpts?)
+ *     enqueueOpts is forwarded to queue.enqueue — delaySeconds,
+ *     maxAttempts, traceId, classification.
+ *     Returns { jobId, queueName, enqueuedAt, ... } from queue.enqueue.
+ *
+ *   await jobs.start()
+ *     Begins consuming each defined queue. Idempotent — a second
+ *     start() is a no-op once consumers are already running.
+ *
+ *   await jobs.shutdown(opts?)
+ *     Stops consumers, drains in-flight via queue.shutdown.
+ *     opts.timeoutMs forwards to queue.shutdown.
+ *
+ *   jobs.stats()
+ *     → { defined: [string], started: boolean }
+ */
+var { boot } = require("./log");
+var queue = require("./queue");
+var validateOpts = require("./validate-opts");
+var { JobsError } = require("./framework-error");
+
+var log = boot("jobs");
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "queueBackend", "consumerDefaults", "allowUnregisteredEnqueue",
+  ], "b.jobs");
+  var queueBackend     = opts.queueBackend || "primary";
+  var consumerDefaults = opts.consumerDefaults || {};
+  var allowUnregistered = !!opts.allowUnregisteredEnqueue;
+
+  // name → { handler, defineOpts, consumerHandle (after start) }
+  var registry = new Map();
+  var started = false;
+
+  var _err = JobsError.factory;
+
+  function define(name, handler, defineOpts) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw _err("INVALID_NAME", "jobs.define: name must be a non-empty string", true);
+    }
+    if (typeof handler !== "function") {
+      throw _err("INVALID_HANDLER", "jobs.define: handler must be a function", true);
+    }
+    if (registry.has(name)) {
+      throw _err("DUPLICATE_NAME",
+        "jobs.define: '" + name + "' is already defined", true);
+    }
+    if (started) {
+      // Defining after start would mean the new handler doesn't run
+      // until the next start cycle. Reject loudly so operators don't
+      // wonder why their newly-defined handler is silent.
+      throw _err("ALREADY_STARTED",
+        "jobs.define: cannot register '" + name + "' after start() — " +
+        "define all handlers before calling start()", true);
+    }
+    registry.set(name, {
+      handler:    handler,
+      defineOpts: defineOpts || {},
+    });
+  }
+
+  async function enqueue(name, payload, enqueueOpts) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw _err("INVALID_NAME", "jobs.enqueue: name must be a non-empty string", true);
+    }
+    if (!allowUnregistered && !registry.has(name)) {
+      throw _err("UNDEFINED_NAME",
+        "jobs.enqueue: '" + name + "' has no registered handler. " +
+        "Either define(name, handler) first, or pass " +
+        "{ allowUnregisteredEnqueue: true } to jobs.create.", true);
+    }
+    return await queue.enqueue(name, payload, Object.assign(
+      { backend: queueBackend },
+      enqueueOpts || {}
+    ));
+  }
+
+  async function start() {
+    if (started) return;
+    var consumerOpts = Object.assign({ backend: queueBackend }, consumerDefaults);
+    registry.forEach(function (entry, name) {
+      var perJobOpts = Object.assign({}, consumerOpts, entry.defineOpts);
+      entry.consumerHandle = queue.consume(name, entry.handler, perJobOpts);
+    });
+    started = true;
+  }
+
+  async function shutdown(shutdownOpts) {
+    if (!started) {
+      // Even when not started, queue.shutdown handles its own state.
+      try { await queue.shutdown(shutdownOpts); }
+      catch (e) { log.debug("shutdown-failed", { op: "queue.shutdown", error: e.message }); }
+      return;
+    }
+    started = false;
+    await queue.shutdown(shutdownOpts);
+    // Don't clear the registry — operators inspecting stats() after
+    // shutdown should still see what was defined; only the running
+    // state changes.
+  }
+
+  function stats() {
+    return {
+      defined:  Array.from(registry.keys()),
+      started:  started,
+    };
+  }
+
+  function _resetForTest() {
+    registry.clear();
+    started = false;
+  }
+
+  return {
+    define:        define,
+    enqueue:       enqueue,
+    start:         start,
+    shutdown:      shutdown,
+    stats:         stats,
+    _resetForTest: _resetForTest,
+  };
+}
+
+module.exports = { create: create };