@blamejs/core 0.14.16 → 0.14.18

package/lib/middleware/openapi-serve.js

@@ -22,15 +22,50 @@
  * If `accessControl: "public"` (the default), the middleware emits
  * `Access-Control-Allow-Origin: *` so external doc tooling can fetch.
  * For internal-only docs operators set `accessControl: "same-origin"`
- * which omits the CORS header.
+ * which omits the CORS header. To allow exactly one external origin set
+ * `accessControl: { allowOrigin: "https://docs.example.com" }`; the
+ * origin is validated and echoed verbatim with `Vary: Origin`.
  */
 
 var nodeCrypto    = require("node:crypto");
 var validateOpts  = require("../validate-opts");
 var lazyRequire   = require("../lazy-require");
+var safeUrl       = require("../safe-url");
 var { defineClass } = require("../framework-error");
 var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
 
+// Validate an operator-supplied accessControl.allowOrigin and return the
+// canonical `scheme://host[:port]` string for the Access-Control-Allow-
+// Origin response header. CORS (Fetch Standard §3.2.1) requires a single
+// concrete origin with no path / query / fragment; the empty-string and
+// "*" wildcard forms are spelled separately ("same-origin" / "public").
+// Parsing through safeUrl rejects header-injection bytes (CR/LF) and
+// userinfo, and confirms the value is a real http(s) origin. Throws so
+// the operator catches a typo'd allowOrigin at boot.
+function _canonicalAllowOrigin(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new OpenApiError("openapi/bad-access-control",
+      label + ": accessControl.allowOrigin must be a non-empty origin string " +
+      "(e.g. \"https://docs.example.com\")");
+  }
+  var parsed;
+  try {
+    parsed = safeUrl.parse(value, { allowedProtocols: safeUrl.ALLOW_HTTP_ALL });
+  } catch (e) {
+    throw new OpenApiError("openapi/bad-access-control",
+      label + ": accessControl.allowOrigin '" + value + "' is not a valid " +
+      "http(s) origin: " + ((e && e.message) || String(e)));
+  }
+  var path = parsed.pathname || "";
+  if ((path !== "" && path !== "/") || parsed.search || parsed.hash) {
+    throw new OpenApiError("openapi/bad-access-control",
+      label + ": accessControl.allowOrigin must be a bare origin " +
+      "(scheme://host[:port]) with no path / query / fragment; got '" + value + "'");
+  }
+  var port = parsed.port;
+  return parsed.protocol + "//" + parsed.hostname.toLowerCase() + (port ? ":" + port : "");
+}
+
 var openapiYaml   = lazyRequire(function () { return require("../openapi-yaml"); });
 var audit         = lazyRequire(function () { return require("../audit"); });
 
@@ -45,7 +80,9 @@ var audit         = lazyRequire(function () { return require("../audit"); });
  * else falls through. SHA3-512 ETag enables conditional 304. With
  * `accessControl: "public"` (default) emits
  * `Access-Control-Allow-Origin: *` so external doc tooling can
- * fetch; `same-origin` omits the CORS header for internal-only docs.
+ * fetch; `same-origin` omits the CORS header for internal-only docs;
+ * `{ allowOrigin: "https://docs.example.com" }` echoes one validated
+ * origin with `Vary: Origin`.
  *
  * @opts
  *   {
@@ -84,6 +121,17 @@ function create(opts) {
   var cacheControl  = (typeof opts.cacheControl === "string" && opts.cacheControl.length > 0)
     ? opts.cacheControl : "public, max-age=300";
   var accessControl = opts.accessControl || "public";
+  // Resolve the Access-Control-Allow-Origin value once at config time.
+  // "public" → "*"; an { allowOrigin } object → the canonical origin
+  // (validated, throws on a bad value); "same-origin" / anything else →
+  // null (no CORS header emitted).
+  var allowOriginHeader = null;
+  if (accessControl === "public") {
+    allowOriginHeader = "*";
+  } else if (accessControl && typeof accessControl === "object" &&
+             typeof accessControl.allowOrigin === "string") {
+    allowOriginHeader = _canonicalAllowOrigin(accessControl.allowOrigin, "openapiServe");
+  }
   var auditOn       = opts.audit !== false;
 
   if (typeof pathJson !== "string" || pathJson.charAt(0) !== "/") {
@@ -123,8 +171,12 @@ function create(opts) {
       "Cache-Control":  cacheControl,
       "ETag":           etag,
     };
-    if (accessControl === "public") {
-      headers["Access-Control-Allow-Origin"] = "*";
+    if (allowOriginHeader !== null) {
+      headers["Access-Control-Allow-Origin"] = allowOriginHeader;
+      // A specific (non-"*") origin makes the response vary by Origin;
+      // advertise it so shared caches don't serve one operator's allowed
+      // origin to another's request (Fetch Standard §3.2.1).
+      if (allowOriginHeader !== "*") headers["Vary"] = "Origin";
     }
     res.writeHead(200, headers);                                                    // HTTP 200
     res.end(body);

package/lib/middleware/scim-server.js

@@ -279,10 +279,13 @@ function _readJsonBody(req) {
     return Promise.resolve(safeJson.parse(req.body.toString("utf8"), { maxBytes: MAX }));
   }
   if (req.body && typeof req.body === "object") return Promise.resolve(req.body);
-  return safeBuffer.boundedChunkCollector(req, MAX, ScimServerError, "middleware/scim-server/body-too-large")
-    .then(function (buf) {
-      return safeJson.parse(buf.toString("utf8"), { maxBytes: MAX });
-    });
+  return safeBuffer.collectStream(req, {
+    maxBytes:   MAX,
+    errorClass: ScimServerError,
+    sizeCode:   "middleware/scim-server/body-too-large",
+  }).then(function (buf) {
+    return safeJson.parse(buf.toString("utf8"), { maxBytes: MAX });
+  });
 }
 
 function _assertSchema(body, expectedSchema) {

package/lib/problem-details.js

@@ -313,7 +313,7 @@ function fromError(err, opts2) {
 
 /**
  * @primitive b.problemDetails.respond
- * @signature b.problemDetails.respond(res, problem)
+ * @signature b.problemDetails.respond(res, problem, req?)
  * @since     0.8.84
  * @status    stable
  * @related   b.problemDetails.create, b.problemDetails.fromError
@@ -339,7 +339,7 @@ function fromError(err, opts2) {
  *   // res.body:     <JSON-stringified problem>
  *   // res.statusCode: 400
  */
-function respond(res, problem) {
+function respond(res, problem, req) {
   if (!res || typeof res !== "object" || typeof res.setHeader !== "function" ||
       typeof res.end !== "function") {
     throw new ProblemDetailsError("problem-details/bad-res",
@@ -352,8 +352,20 @@ function respond(res, problem) {
   var status = (typeof problem.status === "number" && Number.isInteger(problem.status) &&
                 problem.status >= 100 && problem.status <= 599) ? problem.status : 500;            // HTTP status range + default 500
   var body = JSON.stringify(problem);
+  // Seal the problem body when an encrypted session is active — the
+  // encoder is present only after a request body decrypted, so its
+  // envelope decrypts identically on the client. Pre-session paths
+  // leave req/encoder absent and keep plaintext problem+json. An
+  // encryption failure falls back to plaintext rather than crashing.
+  var contentType = "application/problem+json";
+  if (req && typeof req.apiEncryptEncode === "function") {
+    try {
+      body = JSON.stringify(req.apiEncryptEncode(problem));
+      contentType = "application/json";
+    } catch (_e) { /* keep plaintext problem+json */ }
+  }
   res.statusCode = status;
-  res.setHeader("Content-Type", "application/problem+json");
+  res.setHeader("Content-Type", contentType);
   res.setHeader("Cache-Control", "no-store");
   res.end(body);
 }

package/lib/queue-local.js

@@ -28,6 +28,18 @@
  * before INSERT; lease unseals the leased rows before returning to
  * the caller. cluster-storage's RETURNING clause hands back sealed
  * blobs which we run through cryptoField.unsealRow explicitly.
+ *
+ * Bring-your-own database: the local backend defaults to the
+ * framework's main DB (single-node) / external-db (cluster) via
+ * cluster-storage, and to the table "_blamejs_jobs". An operator can
+ * point the backend at their own store, table, and schema through the
+ * protocol config — see create(config). The physical table reference
+ * is composed through b.safeSql identifier quoting (never raw string
+ * interpolation), so an operator-supplied table/schema cannot smuggle
+ * SQL through the identifier slot (SQL identifier injection, CWE-89).
+ * Sealing stays keyed off the logical column map registered for
+ * "_blamejs_jobs", so payload + lastError remain sealed regardless of
+ * which physical table the rows land in.
  */
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
@@ -37,11 +49,22 @@ var cryptoField = require("./crypto-field");
 var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var safeJson = require("./safe-json");
+var safeSql = require("./safe-sql");
 var scheduler = require("./scheduler");
 var { QueueError } = require("./framework-error");
 
 var _err = QueueError.factory;
 
+// Logical table name the field-crypto schema is keyed on. This is the
+// COLUMN→seal map registered in db.js's FRAMEWORK_SCHEMA, NOT the
+// physical table the SQL writes to. An operator who points the backend
+// at their own table still seals payload + lastError through this map,
+// so a bring-your-own table inherits the same at-rest protection.
+var SEAL_TABLE = "_blamejs_jobs";
+
+// Default physical table for the local backend.
+var DEFAULT_TABLE = "_blamejs_jobs";
+
 // vault is lazy-required because some flows (sealed lastError) only
 // touch it on retry-with-error paths, and the import order
 // (queue-local → vault → db → audit → cluster) tolerates the late bind.
@@ -84,7 +107,7 @@ function _shapeLeasedRow(raw) {
   // raw is a row coming back from RETURNING — payload is sealed if
   // present. Run through cryptoField's unseal pipeline so the caller
   // gets cleartext.
-  var unsealed = cryptoField.unsealRow("_blamejs_jobs", raw);
+  var unsealed = cryptoField.unsealRow(SEAL_TABLE, raw);
   return {
     jobId:          unsealed._id,
     queueName:      unsealed.queueName,
@@ -102,9 +125,78 @@ function _shapeLeasedRow(raw) {
   };
 }
 
-function create(_config) {
-  // No protocol-level config — uses cluster-storage which dispatches
-  // to the framework's main DB (single-node) or external-db (cluster).
+// Validate a bring-your-own store handle at config time. It must expose
+// the execute / executeOne / executeAll trio that cluster-storage does,
+// since every method here dispatches through that surface.
+var _REQUIRED_STORE_METHODS = ["execute", "executeOne", "executeAll"];
+function _resolveStore(handle) {
+  if (handle === undefined || handle === null) return clusterStorage;
+  if (typeof handle !== "object") {
+    throw _err("INVALID_DB_HANDLE",
+      "queue local config.db must be a storage handle exposing execute/executeOne/executeAll, got " +
+        typeof handle, true);
+  }
+  for (var i = 0; i < _REQUIRED_STORE_METHODS.length; i++) {
+    var m = _REQUIRED_STORE_METHODS[i];
+    if (typeof handle[m] !== "function") {
+      throw _err("INVALID_DB_HANDLE",
+        "queue local config.db is missing required method '" + m + "()'", true);
+    }
+  }
+  return handle;
+}
+
+// Compose the physical table reference from config.table + config.schema,
+// quoting each identifier through b.safeSql so an operator-supplied name
+// cannot interpolate SQL through the identifier slot (CWE-89). Returns
+// the bare default name unquoted when no custom table/schema is given so
+// the framework's cluster-mode table rewrite (resolveTables) still fires
+// on the default jobs table; any custom name is fully validated + quoted.
+function _resolveTableRef(config) {
+  var table = config.table !== undefined && config.table !== null
+    ? config.table : DEFAULT_TABLE;
+  if (typeof table !== "string") {
+    throw _err("INVALID_TABLE",
+      "queue local config.table must be a string identifier, got " + typeof table, true);
+  }
+  var schema = config.schema;
+  if (schema !== undefined && schema !== null && typeof schema !== "string") {
+    throw _err("INVALID_SCHEMA",
+      "queue local config.schema must be a string identifier, got " + typeof schema, true);
+  }
+  var usingDefault = (table === DEFAULT_TABLE) &&
+    (schema === undefined || schema === null);
+  if (usingDefault) {
+    // Byte-identical default SQL — unquoted bare name so cluster-mode
+    // resolveTables continues to recognize and rewrite the jobs table.
+    return DEFAULT_TABLE;
+  }
+  // Any custom table/schema is validated + dialect-quoted. validateIdentifier
+  // / quoteQualified THROW (SafeSqlError) on a bad identifier; surface that
+  // as the queue's config-time error so the operator catches the typo at
+  // boot rather than on first enqueue.
+  try {
+    if (schema !== undefined && schema !== null && schema !== "") {
+      return safeSql.quoteQualified([schema, table]);
+    }
+    return safeSql.quoteIdentifier(table);
+  } catch (e) {
+    throw _err("INVALID_TABLE",
+      "queue local table/schema failed identifier validation: " + e.message, true);
+  }
+}
+
+function create(config) {
+  config = config || {};
+  // Bring-your-own store + table. Defaults preserve the prior behavior
+  // exactly: cluster-storage dispatch to the framework's main DB
+  // (single-node) / external-db (cluster), table "_blamejs_jobs".
+  var store = _resolveStore(config.db);
+  // qTable holds the physical table reference already validated +
+  // dialect-quoted by _resolveTableRef (via safeSql.quoteIdentifier /
+  // quoteQualified, or the framework's bare default name). The `q` prefix
+  // marks it as a safe-to-interpolate identifier so it is never re-quoted.
+  var qTable = _resolveTableRef(config);
 
   async function enqueue(queueName, payload, opts) {
     cluster.requireLeader();
@@ -171,11 +263,11 @@ function create(_config) {
       flowChildName:   flowChildName,
       dependsOn:       dependsOn,
     };
-    var sealed = cryptoField.sealRow("_blamejs_jobs", row);
+    var sealed = cryptoField.sealRow(SEAL_TABLE, row);
     var values = JOB_COLS.map(function (c) { return c in sealed ? sealed[c] : null; });
 
-    await clusterStorage.execute(
-      "INSERT INTO _blamejs_jobs (" + _quotedList(JOB_COLS) + ") " +
+    await store.execute(
+      "INSERT INTO " + qTable + " (" + _quotedList(JOB_COLS) + ") " +
       "VALUES (" + _placeholders(JOB_COLS) + ")",
       values
     );
@@ -201,16 +293,16 @@ function create(_config) {
     // can't be picked twice). RETURNING hands back the leased columns
     // so we don't need a separate SELECT after the UPDATE.
     var sql =
-      "UPDATE _blamejs_jobs " +
+      "UPDATE " + qTable + " " +
       "SET status = 'inflight', leasedAt = ?, leaseExpiresAt = ?, attempts = attempts + 1 " +
       "WHERE _id IN (" +
-      "  SELECT _id FROM _blamejs_jobs " +
+      "  SELECT _id FROM " + qTable + " " +
       "  WHERE queueName = ? AND status = 'pending' AND availableAt <= ? " +
       "  ORDER BY priority DESC, availableAt ASC, enqueuedAt ASC " +
       "  LIMIT ?" +
       ") " +
       "RETURNING " + _quotedList(LEASE_RETURN_COLS);
-    var result = await clusterStorage.execute(
+    var result = await store.execute(
       sql,
       [nowMs, leaseExpiresAt, queueName, nowMs, maxRows]
     );
@@ -232,8 +324,8 @@ function create(_config) {
         "extendLease: additionalMs must be a positive number", true);
     }
     var newExpiry = Date.now() + additionalMs;
-    var result = await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET leaseExpiresAt = ? " +
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET leaseExpiresAt = ? " +
       "WHERE _id = ? AND status = 'inflight'",
       [newExpiry, jobId]
     );
@@ -247,16 +339,16 @@ function create(_config) {
     // the status flip. Single SELECT + UPDATE pair under the same
     // jobId — race-free under SQLite (single-writer); cluster-storage
     // dispatches both calls to the same backend.
-    var rowRes = await clusterStorage.execute(
+    var rowRes = await store.execute(
       "SELECT _id, queueName, payload, repeatCron, repeatTimezone, " +
       "       flowId, flowChildName, priority, classification, traceId " +
-      "FROM _blamejs_jobs WHERE _id = ?",
+      "FROM " + qTable + " WHERE _id = ?",
       [jobId]
     );
     var row = (rowRes && rowRes.rows && rowRes.rows[0]) || null;
 
-    await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET status = 'done', finishedAt = ?, leaseExpiresAt = NULL " +
+    await store.execute(
+      "UPDATE " + qTable + " SET status = 'done', finishedAt = ?, leaseExpiresAt = NULL " +
       "WHERE _id = ? AND status = 'inflight'",
       [nowMs, jobId]
     );
@@ -266,7 +358,7 @@ function create(_config) {
     // re-enqueue — operators investigate before the cron resumes.
     if (row && row.repeatCron) {
       try {
-        var unsealedRow = cryptoField.unsealRow("_blamejs_jobs", row);
+        var unsealedRow = cryptoField.unsealRow(SEAL_TABLE, row);
         var cron = scheduler.parseCron(unsealedRow.repeatCron);
         var nextMs = scheduler.nextCronFire(cron, new Date(nowMs), unsealedRow.repeatTimezone || null);
         await enqueue(unsealedRow.queueName,
@@ -296,8 +388,8 @@ function create(_config) {
   }
 
   async function _maybeReleaseFlowChildren(flowId, completedJobId, completedChildName, nowMs) {
-    var siblingsRes = await clusterStorage.execute(
-      "SELECT _id, dependsOn, flowChildName, status, availableAt FROM _blamejs_jobs " +
+    var siblingsRes = await store.execute(
+      "SELECT _id, dependsOn, flowChildName, status, availableAt FROM " + qTable + " " +
       "WHERE flowId = ? AND status = 'pending' AND availableAt > ?",
       [flowId, nowMs]
     );
@@ -317,16 +409,16 @@ function create(_config) {
         // Quick path: just-completed job matches by id or child name.
         if (dep === completedJobId || (completedChildName && dep === completedChildName)) continue;
         // Otherwise SELECT to confirm done.
-        var depRes = await clusterStorage.execute(
-          "SELECT 1 FROM _blamejs_jobs WHERE flowId = ? AND status = 'done' AND " +
+        var depRes = await store.execute(
+          "SELECT 1 FROM " + qTable + " WHERE flowId = ? AND status = 'done' AND " +
           "  (_id = ? OR flowChildName = ?) LIMIT 1",
           [flowId, dep, dep]
         );
         if (!depRes || !depRes.rows || depRes.rows.length === 0) { allDone = false; break; }
       }
       if (allDone) {
-        await clusterStorage.execute(
-          "UPDATE _blamejs_jobs SET availableAt = ? WHERE _id = ?",
+        await store.execute(
+          "UPDATE " + qTable + " SET availableAt = ? WHERE _id = ?",
           [nowMs, sib._id]
         );
       }
@@ -345,8 +437,8 @@ function create(_config) {
     // status / availableAt / finishedAt updates per branch — same
     // semantics as the previous SELECT-then-UPDATE-in-transaction
     // path, but no cross-dialect transaction primitive needed.
-    await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET " +
+    await store.execute(
+      "UPDATE " + qTable + " SET " +
       "  status = CASE WHEN attempts < maxAttempts THEN 'pending' ELSE 'failed' END, " +
       "  lastError = ?, " +
       "  leaseExpiresAt = NULL, " +
@@ -360,8 +452,8 @@ function create(_config) {
 
   async function sweepExpired() {
     cluster.requireLeader();
-    var result = await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET status = 'pending', leaseExpiresAt = NULL " +
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET status = 'pending', leaseExpiresAt = NULL " +
       "WHERE status = 'inflight' AND leaseExpiresAt < ?",
       [Date.now()]
     );
@@ -369,8 +461,8 @@ function create(_config) {
   }
 
   async function size(queueName) {
-    var row = await clusterStorage.executeOne(
-      "SELECT COUNT(*) AS n FROM _blamejs_jobs " +
+    var row = await store.executeOne(
+      "SELECT COUNT(*) AS n FROM " + qTable + " " +
       "WHERE queueName = ? AND (status = 'pending' OR status = 'inflight')",
       [queueName]
     );
@@ -395,16 +487,16 @@ function create(_config) {
       }
       limit = opts.limit;
     }
-    var rows = await clusterStorage.executeAll(
+    var rows = await store.executeAll(
       "SELECT _id, queueName, payload, status, enqueuedAt, finishedAt, " +
       "       attempts, maxAttempts, lastError, traceId, classification " +
-      "FROM _blamejs_jobs " +
+      "FROM " + qTable + " " +
       "WHERE queueName = ? AND status = 'failed' " +
       "ORDER BY finishedAt DESC LIMIT ?",
       [queueName, limit]
     );
     return rows.map(function (row) {
-      var unsealed = cryptoField.unsealRow("_blamejs_jobs", row);
+      var unsealed = cryptoField.unsealRow(SEAL_TABLE, row);
       return {
         jobId:       row._id,
         queueName:   row.queueName,
@@ -424,8 +516,8 @@ function create(_config) {
   async function dlqRetry(jobId) {
     cluster.requireLeader();
     var nowMs = Date.now();
-    var result = await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET " +
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET " +
       "  status = 'pending', " +
       "  attempts = 0, " +
       "  availableAt = ?, " +
@@ -440,8 +532,8 @@ function create(_config) {
   }
 
   async function dlqSize(queueName) {
-    var row = await clusterStorage.executeOne(
-      "SELECT COUNT(*) AS n FROM _blamejs_jobs " +
+    var row = await store.executeOne(
+      "SELECT COUNT(*) AS n FROM " + qTable + " " +
       "WHERE queueName = ? AND status = 'failed'",
       [queueName]
     );
@@ -450,13 +542,30 @@ function create(_config) {
 
   async function purge(queueName) {
     cluster.requireLeader();
-    var result = await clusterStorage.execute(
-      "DELETE FROM _blamejs_jobs WHERE queueName = ?",
+    var result = await store.execute(
+      "DELETE FROM " + qTable + " WHERE queueName = ?",
       [queueName]
     );
     return result.rowCount || 0;
   }
 
+  // patchFlowDeps — the second pass of enqueueFlow. Writes the resolved
+  // dependsOn jobIds and parks availableAt at MAX_SAFE_INTEGER for a flow
+  // child that has dependencies. Lives on the backend (not in queue.js)
+  // so it targets THIS backend's configured store + table — a
+  // bring-your-own table receives the flow graph the same way the
+  // first-pass enqueue did, instead of the dispatcher writing to the
+  // default jobs table behind the backend's back. depIds is serialized
+  // to JSON for the dependsOn column.
+  async function patchFlowDeps(jobId, depIds) {
+    cluster.requireLeader();
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET dependsOn = ?, availableAt = ? WHERE _id = ?",
+      [JSON.stringify(depIds), FLOW_BLOCKED_AVAILABLE_AT, jobId]
+    );
+    return (result.rowCount || 0) > 0;
+  }
+
   return {
     protocol:       "local",
     enqueue:        enqueue,
@@ -470,6 +579,7 @@ function create(_config) {
     dlqList:        dlqList,
     dlqRetry:       dlqRetry,
     dlqSize:        dlqSize,
+    patchFlowDeps:  patchFlowDeps,
   };
 }
 

package/lib/queue.js

@@ -13,7 +13,9 @@
  *   backend declares a `protocol` plus protocol-specific options. The
  *   built-in `local` protocol is SQLite-backed (rows live in the
  *   framework's main DB so persistence survives crashes / restarts
- *   without external infrastructure). `redis` and `sqs` ship; `amqp`
+ *   without external infrastructure), and can be pointed at an
+ *   operator's own database handle, table, and schema via the `local`
+ *   config (`db` / `table` / `schema`). `redis` and `sqs` ship; `amqp`
  *   and `nats` are listed as deferred and surface a clear error if
  *   selected.
  *
@@ -54,7 +56,6 @@
  *   Durable, pluggable job queue with priority-aware leasing, retry + deterministic backoff, graceful shutdown, parent/child flows, and a dead-letter surface for jobs that exhaust their retries.
  */
 var C = require("./constants");
-var clusterStorage = require("./cluster-storage");
 var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
@@ -107,13 +108,29 @@ var sweepTimer = null;
  * Throws when `opts.backends` is missing — operators catch the typo
  * at boot rather than discovering it on first enqueue.
  *
+ * The `local` protocol defaults to the framework's own database (the
+ * main SQLite in single-node mode, the operator-supplied external DB in
+ * cluster mode) and the `_blamejs_jobs` table. An operator who wants the
+ * queue rows to live in their own database, table, or schema supplies
+ * `db` / `table` / `schema` in the `local` backend config. The `db`
+ * handle must expose the same `execute` / `executeOne` / `executeAll`
+ * surface as `b.clusterStorage`; `table` / `schema` are validated as SQL
+ * identifiers and quoted through `b.safeSql` (an identifier that isn't a
+ * safe name is refused at `init` time, not interpolated into SQL).
+ * Sealed columns (`payload`, `lastError`) stay sealed regardless of
+ * where the rows land.
+ *
  * @opts
  *   backends: {
  *     [name: string]: {
  *       protocol:  "local" | "redis" | "sqs",
  *       breaker?:  { ... },   // see b.retry.CircuitBreaker opts
  *       retry?:    { ... },   // see b.retry.withRetry opts
- *       // ...protocol-specific opts (e.g. redis url, sqs queueUrl)
+ *       // local protocol — bring-your-own database (all optional):
+ *       db?:       object,    // store handle (execute/executeOne/executeAll); default cluster-storage
+ *       table?:    string,    // table name (validated + quoted); default "_blamejs_jobs"
+ *       schema?:   string,    // schema/namespace qualifier (validated + quoted)
+ *       // ...other protocol-specific opts (e.g. redis url, sqs queueUrl)
  *     },
  *   },
  *   defaultBackend?: string,  // name to use when enqueue/consume omit { backend }
@@ -122,11 +139,12 @@ var sweepTimer = null;
  *   b.queue.init({
  *     backends: {
  *       primary: { protocol: "local" },
+ *       app:     { protocol: "local", table: "app_jobs", schema: "work" },
  *     },
  *     defaultBackend: "primary",
  *   });
  *   b.queue.listBackends();
- *   // → [{ name: "primary", protocol: "local", breakerState: "closed" }]
+ *   // → [{ name: "primary", protocol: "local", breakerState: "closed" }, ...]
  */
 function init(opts) {
   if (initialized) return;
@@ -183,6 +201,7 @@ function init(opts) {
       dlqList:       raw.dlqList ? wrapWithRetry(raw.dlqList) : null,
       dlqRetry:      raw.dlqRetry ? wrapWithRetry(raw.dlqRetry) : null,
       dlqSize:       raw.dlqSize ? wrapWithRetry(raw.dlqSize) : null,
+      patchFlowDeps: raw.patchFlowDeps ? wrapWithRetry(raw.patchFlowDeps) : null,
     };
   });
 
@@ -897,6 +916,17 @@ function enqueueFlow(spec) {
 
   var flowId = "flow-" + bCrypto.generateToken(C.BYTES.bytes(8));
 
+  // Resolve the backend up front so the second-pass dependsOn patch
+  // targets the SAME backend (and its configured store + table) that the
+  // first-pass enqueue wrote to. A backend pointed at a bring-your-own
+  // table must receive the flow graph through its own writer, not a
+  // dispatcher-level write to the default jobs table.
+  var flowBackend = _backendFor(spec);
+  if (typeof flowBackend.patchFlowDeps !== "function") {
+    return Promise.reject(_err("FLOW_UNSUPPORTED",
+      "queue backend '" + flowBackend.name + "' does not support enqueueFlow", true));
+  }
+
   return observability.tap("queue.enqueueFlow",
     { queueName: spec.queueName, flowId: flowId, childCount: spec.children.length },
     async function () {
@@ -910,6 +940,7 @@ function enqueueFlow(spec) {
         var ch = spec.children[p];
         // Hold off setting dependsOn until we know all sibling jobIds.
         var enqOpts = {
+          backend:       flowBackend.name,
           flowId:        flowId,
           flowChildName: ch.name,
           priority:      ch.priority || 0,
@@ -917,9 +948,9 @@ function enqueueFlow(spec) {
           traceId:       ch.traceId || null,
           maxAttempts:   ch.maxAttempts,
           // dependsOn intentionally omitted on first pass — will be patched
-          // in via direct UPDATE after all jobIds are known. This means
-          // root children (no deps) are immediately leaseable; deps-bearing
-          // children get patched to MAX_SAFE_INTEGER via second pass.
+          // in via the backend's patchFlowDeps after all jobIds are known.
+          // Root children (no deps) are immediately leaseable; deps-bearing
+          // children get parked at MAX_SAFE_INTEGER via the second pass.
         };
         var result = await enqueue(spec.queueName, ch.payload, enqOpts);
         nameToJobId[ch.name] = result.jobId;
@@ -927,14 +958,13 @@ function enqueueFlow(spec) {
       }
       // Second pass: write dependsOn (translated to jobIds) for children
       // that need it, and parking-lot their availableAt to MAX_SAFE_INTEGER.
+      // Routed through the backend's writer so it lands in the backend's
+      // configured store + table (bring-your-own DB safe).
       for (var q = 0; q < jobs.length; q++) {
         var j = jobs[q];
         if (j.dependsOn.length === 0) continue;
         var depIds = j.dependsOn.map(function (n2) { return nameToJobId[n2]; });
-        await clusterStorage.execute(
-          "UPDATE _blamejs_jobs SET dependsOn = ?, availableAt = ? WHERE _id = ?",
-          [JSON.stringify(depIds), Number.MAX_SAFE_INTEGER, j.jobId]
-        );
+        await flowBackend.patchFlowDeps(j.jobId, depIds);
       }
       _emit("system.queue.flow.enqueue", {
         metadata: {