@blamejs/core 0.14.26 → 0.15.0

package/lib/queue-local.js

@@ -50,6 +50,7 @@ var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var scheduler = require("./scheduler");
 var { QueueError } = require("./framework-error");
 
@@ -59,10 +60,16 @@ var _err = QueueError.factory;
 // 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.
+// so a bring-your-own table inherits the same at-rest protection. The KEY
+// must stay byte-identical to db.js's registerTable literal.
+// allow:hand-rolled-sql — cryptoField seal-table registry KEY, not a SQL table.
 var SEAL_TABLE = "_blamejs_jobs";
 
-// Default physical table for the local backend.
+// Default LOGICAL table for the local backend. Passed BARE to b.sql so
+// clusterStorage.resolveTables rewrites it to the configured cluster name
+// (applying the configurable prefix); a custom config.table is quoted at
+// build time instead. b.sql owns the quoting; this is the logical name.
+// allow:hand-rolled-sql — framework logical jobs-table name handed to b.sql, not a SQL literal.
 var DEFAULT_TABLE = "_blamejs_jobs";
 
 // vault is lazy-required because some flows (sealed lastError) only
@@ -111,14 +118,6 @@ var LEASE_RETURN_COLS = [
   "repeatCron", "repeatTimezone", "flowId", "flowChildName",
 ];
 
-function _quotedList(cols) {
-  return cols.map(function (c) { return '"' + c + '"'; }).join(", ");
-}
-
-function _placeholders(cols) {
-  return cols.map(function () { return "?"; }).join(", ");
-}
-
 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
@@ -162,12 +161,19 @@ function _resolveStore(handle) {
   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.
+// Resolve the b.sql table-builder options from config.table + config.schema.
+// Every SQL statement is composed through b.sql, which quotes identifiers
+// through b.safeSql so an operator-supplied name cannot interpolate SQL
+// through the identifier slot (CWE-89). The DEFAULT logical table is passed
+// BARE (quoteName off) so the framework's cluster-mode rewrite
+// (clusterStorage.resolveTables) still fires on the jobs table and applies
+// the configurable prefix; any custom table/schema is validated + quoted at
+// build time instead (no rewrite — it is the operator's own table).
+//
+// Returns { name, opts } where `opts` is spread into every b.sql verb call:
+//   default → { dialect: "sqlite" }                  (bare name, rewritten)
+//   custom  → { dialect: "sqlite", quoteName: true } (quoted, no rewrite)
+//   custom+schema → adds { schema } (b.sql emits the quoted schema.table form)
 function _resolveTableRef(config) {
   var table = config.table !== undefined && config.table !== null
     ? config.table : DEFAULT_TABLE;
@@ -183,23 +189,33 @@ function _resolveTableRef(config) {
   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;
+    // Bare default — b.sql leaves it unquoted so cluster-mode resolveTables
+    // recognizes + rewrites the jobs table (and applies the prefix).
+    return { name: DEFAULT_TABLE, opts: { dialect: "sqlite" } };
   }
-  // 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.
+  // Any custom table/schema is validated + dialect-quoted by b.sql at build
+  // time. validateIdentifier (run inside b.sql's TableRef) THROWs
+  // (SqlBuilderError / 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.
+  var opts = { dialect: "sqlite", quoteName: true };
+  if (schema !== undefined && schema !== null && schema !== "") opts.schema = schema;
   try {
-    if (schema !== undefined && schema !== null && schema !== "") {
-      return safeSql.quoteQualified([schema, table]);
-    }
-    return safeSql.quoteIdentifier(table);
+    // Validate the custom identifier(s) at config time with the STRICTER
+    // policy (allowReserved off — a reserved word like `select` is refused
+    // for a bring-your-own queue table, matching the prior
+    // quoteIdentifier / quoteQualified contract). b.sql then quotes the
+    // already-validated name at build time. validateIdentifier THROWs
+    // (SafeSqlError) on a bad shape / reserved word / injection-shaped
+    // schema, surfaced here as the queue's config-time error so the
+    // operator catches the typo at boot rather than on first enqueue.
+    safeSql.validateIdentifier(table);
+    if (opts.schema) safeSql.validateIdentifier(opts.schema);
   } catch (e) {
     throw _err("INVALID_TABLE",
       "queue local table/schema failed identifier validation: " + e.message, true);
   }
+  return { name: table, opts: opts };
 }
 
 function create(config) {
@@ -208,11 +224,20 @@ function create(config) {
   // 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);
+  // ref = { name, opts } for every b.sql verb call — the bare default
+  // jobs table (clusterStorage rewrites it + applies the configurable
+  // prefix) or a validated + quoted custom table/schema. Small helpers
+  // open each verb builder pre-bound to this table so the table reference
+  // is resolved in exactly one place.
+  var ref = _resolveTableRef(config);
+  function _select() { return sql.select(ref.name, ref.opts); }
+  function _insert() { return sql.insert(ref.name, ref.opts); }
+  function _update() { return sql.update(ref.name, ref.opts); }
+  function _delete() { return sql.delete(ref.name, ref.opts); }
+  // Quoted column expression for a setRaw RHS that references the column's
+  // own pre-update value (attempts/availableAt). dialect-sqlite quoting is
+  // the double-quote form clusterStorage's Postgres path keeps.
+  function _qc(col) { return safeSql.quoteIdentifier(col, "sqlite", { allowReserved: true }); }
 
   async function enqueue(queueName, payload, opts) {
     cluster.requireLeader();
@@ -280,13 +305,16 @@ function create(config) {
       dependsOn:       dependsOn,
     };
     var sealed = cryptoField.sealRow(SEAL_TABLE, row);
-    var values = JOB_COLS.map(function (c) { return c in sealed ? sealed[c] : null; });
-
-    await store.execute(
-      "INSERT INTO " + qTable + " (" + _quotedList(JOB_COLS) + ") " +
-      "VALUES (" + _placeholders(JOB_COLS) + ")",
-      values
-    );
+    // Build the full column→value map in JOB_COLS order (a missing sealed
+    // column binds NULL, matching the prior positional-values shape). b.sql
+    // quotes every column + binds every value as a placeholder.
+    var insertRow = {};
+    for (var ci = 0; ci < JOB_COLS.length; ci++) {
+      var col = JOB_COLS[ci];
+      insertRow[col] = col in sealed ? sealed[col] : null;
+    }
+    var insertBuilt = _insert().columns(JOB_COLS).values(insertRow).toSql();
+    await store.execute(insertBuilt.sql, insertBuilt.params);
     return {
       jobId:          row._id,
       queueName:      queueName,
@@ -307,21 +335,28 @@ function create(config) {
     // rows that still match status='pending' after the lock acquires
     // (Postgres EvalPlanQual; SQLite is single-writer so the same row
     // 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 " + qTable + " " +
-      "SET status = 'inflight', leasedAt = ?, leaseExpiresAt = ?, attempts = attempts + 1 " +
-      "WHERE _id IN (" +
-      "  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 store.execute(
-      sql,
-      [nowMs, leaseExpiresAt, queueName, nowMs, maxRows]
-    );
+    // so we don't need a separate SELECT after the UPDATE. maxRows is a
+    // framework-computed integer emitted inline via b.sql's .limit() (a
+    // bound LIMIT param has no portable form across the subquery path);
+    // attempts = attempts + 1 is a setRaw over the column's own value.
+    var leaseInner = _select()
+      .columns(["_id"])
+      .where("queueName", queueName)
+      .where("status", "pending")
+      .whereOp("availableAt", "<=", nowMs)
+      .orderBy("priority", "desc")
+      .orderBy("availableAt", "asc")
+      .orderBy("enqueuedAt", "asc")
+      .limit(maxRows);
+    var leaseBuilt = _update()
+      .set("status", "inflight")
+      .set("leasedAt", nowMs)
+      .set("leaseExpiresAt", leaseExpiresAt)
+      .setRaw("attempts", _qc("attempts") + " + 1", [])
+      .whereIn("_id", leaseInner)
+      .returning(LEASE_RETURN_COLS)
+      .toSql();
+    var result = await store.execute(leaseBuilt.sql, leaseBuilt.params);
     var leased = [];
     for (var i = 0; i < result.rows.length; i++) {
       leased.push(_shapeLeasedRow(result.rows[i]));
@@ -340,11 +375,12 @@ function create(config) {
         "extendLease: additionalMs must be a positive number", true);
     }
     var newExpiry = Date.now() + additionalMs;
-    var result = await store.execute(
-      "UPDATE " + qTable + " SET leaseExpiresAt = ? " +
-      "WHERE _id = ? AND status = 'inflight'",
-      [newExpiry, jobId]
-    );
+    var built = _update()
+      .set("leaseExpiresAt", newExpiry)
+      .where("_id", jobId)
+      .where("status", "inflight")
+      .toSql();
+    var result = await store.execute(built.sql, built.params);
     return (result.rowCount || 0) > 0;
   }
 
@@ -355,19 +391,22 @@ 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 store.execute(
-      "SELECT _id, queueName, payload, repeatCron, repeatTimezone, " +
-      "       flowId, flowChildName, priority, classification, traceId " +
-      "FROM " + qTable + " WHERE _id = ?",
-      [jobId]
-    );
+    var rowBuilt = _select()
+      .columns(["_id", "queueName", "payload", "repeatCron", "repeatTimezone",
+                "flowId", "flowChildName", "priority", "classification", "traceId"])
+      .where("_id", jobId)
+      .toSql();
+    var rowRes = await store.execute(rowBuilt.sql, rowBuilt.params);
     var row = (rowRes && rowRes.rows && rowRes.rows[0]) || null;
 
-    await store.execute(
-      "UPDATE " + qTable + " SET status = 'done', finishedAt = ?, leaseExpiresAt = NULL " +
-      "WHERE _id = ? AND status = 'inflight'",
-      [nowMs, jobId]
-    );
+    var doneBuilt = _update()
+      .set("status", "done")
+      .set("finishedAt", nowMs)
+      .set("leaseExpiresAt", null)
+      .where("_id", jobId)
+      .where("status", "inflight")
+      .toSql();
+    await store.execute(doneBuilt.sql, doneBuilt.params);
 
     // Repeat-in-queue: cron-recurring job re-enqueues itself for the
     // next firing time. Failures (which take the fail() path) don't
@@ -404,11 +443,13 @@ function create(config) {
   }
 
   async function _maybeReleaseFlowChildren(flowId, completedJobId, completedChildName, nowMs) {
-    var siblingsRes = await store.execute(
-      "SELECT _id, dependsOn, flowChildName, status, availableAt FROM " + qTable + " " +
-      "WHERE flowId = ? AND status = 'pending' AND availableAt > ?",
-      [flowId, nowMs]
-    );
+    var siblingsBuilt = _select()
+      .columns(["_id", "dependsOn", "flowChildName", "status", "availableAt"])
+      .where("flowId", flowId)
+      .where("status", "pending")
+      .whereOp("availableAt", ">", nowMs)
+      .toSql();
+    var siblingsRes = await store.execute(siblingsBuilt.sql, siblingsBuilt.params);
     var siblings = (siblingsRes && siblingsRes.rows) || [];
     for (var i = 0; i < siblings.length; i++) {
       var sib = siblings[i];
@@ -424,19 +465,25 @@ function create(config) {
         var dep = deps[d];
         // 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 store.execute(
-          "SELECT 1 FROM " + qTable + " WHERE flowId = ? AND status = 'done' AND " +
-          "  (_id = ? OR flowChildName = ?) LIMIT 1",
-          [flowId, dep, dep]
-        );
+        // Otherwise SELECT to confirm done. The (_id = ? OR flowChildName = ?)
+        // disjunction is a whereGroup so it AND-composes at one precedence
+        // level with the flowId + status equalities.
+        var depBuilt = _select()
+          .columns(["_id"])
+          .where("flowId", flowId)
+          .where("status", "done")
+          .whereGroup(function (g) { g.where("_id", dep).orWhere("flowChildName", dep); })
+          .limit(1)
+          .toSql();
+        var depRes = await store.execute(depBuilt.sql, depBuilt.params);
         if (!depRes || !depRes.rows || depRes.rows.length === 0) { allDone = false; break; }
       }
       if (allDone) {
-        await store.execute(
-          "UPDATE " + qTable + " SET availableAt = ? WHERE _id = ?",
-          [nowMs, sib._id]
-        );
+        var releaseBuilt = _update()
+          .set("availableAt", nowMs)
+          .where("_id", sib._id)
+          .toSql();
+        await store.execute(releaseBuilt.sql, releaseBuilt.params);
       }
     }
   }
@@ -452,36 +499,46 @@ function create(config) {
     // row's current attempts/maxAttempts. CASE expressions split the
     // 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 store.execute(
-      "UPDATE " + qTable + " SET " +
-      "  status = CASE WHEN attempts < maxAttempts THEN 'pending' ELSE 'failed' END, " +
-      "  lastError = ?, " +
-      "  leaseExpiresAt = NULL, " +
-      "  availableAt = CASE WHEN attempts < maxAttempts THEN ? ELSE availableAt END, " +
-      "  finishedAt  = CASE WHEN attempts < maxAttempts THEN NULL ELSE ? END " +
-      "WHERE _id = ?",
-      [sealedErr, nowMs + retryDelayMs, nowMs, jobId]
-    );
+    // path, but no cross-dialect transaction primitive needed. Each CASE
+    // is a b.sql setRaw value-expression (guarded by b.guardSql) over the
+    // row's own columns; the branch values bind as `?` placeholders (the
+    // prior 'pending'/'failed' SQL literals now bind, which keeps the raw
+    // fragment literal-free).
+    var attemptsLt = _qc("attempts") + " < " + _qc("maxAttempts");
+    var failBuilt = _update()
+      .setRaw("status", "CASE WHEN " + attemptsLt + " THEN ? ELSE ? END", ["pending", "failed"])
+      .set("lastError", sealedErr)
+      .set("leaseExpiresAt", null)
+      .setRaw("availableAt", "CASE WHEN " + attemptsLt + " THEN ? ELSE " + _qc("availableAt") + " END",
+              [nowMs + retryDelayMs])
+      .setRaw("finishedAt", "CASE WHEN " + attemptsLt + " THEN NULL ELSE ? END", [nowMs])
+      .where("_id", jobId)
+      .toSql();
+    await store.execute(failBuilt.sql, failBuilt.params);
     return true;
   }
 
   async function sweepExpired() {
     cluster.requireLeader();
-    var result = await store.execute(
-      "UPDATE " + qTable + " SET status = 'pending', leaseExpiresAt = NULL " +
-      "WHERE status = 'inflight' AND leaseExpiresAt < ?",
-      [Date.now()]
-    );
+    var built = _update()
+      .set("status", "pending")
+      .set("leaseExpiresAt", null)
+      .where("status", "inflight")
+      .whereOp("leaseExpiresAt", "<", Date.now())
+      .toSql();
+    var result = await store.execute(built.sql, built.params);
     return result.rowCount || 0;
   }
 
   async function size(queueName) {
-    var row = await store.executeOne(
-      "SELECT COUNT(*) AS n FROM " + qTable + " " +
-      "WHERE queueName = ? AND (status = 'pending' OR status = 'inflight')",
-      [queueName]
-    );
+    // (status = 'pending' OR status = 'inflight') is an IN-list over the two
+    // active states — b.sql expands it to (?, ?) bound placeholders.
+    var built = _select()
+      .count("*", "n")
+      .where("queueName", queueName)
+      .whereIn("status", ["pending", "inflight"])
+      .toSql();
+    var row = await store.executeOne(built.sql, built.params);
     return row ? Number(row.n) : 0;
   }
 
@@ -503,14 +560,15 @@ function create(config) {
       }
       limit = opts.limit;
     }
-    var rows = await store.executeAll(
-      "SELECT _id, queueName, payload, status, enqueuedAt, finishedAt, " +
-      "       attempts, maxAttempts, lastError, traceId, classification " +
-      "FROM " + qTable + " " +
-      "WHERE queueName = ? AND status = 'failed' " +
-      "ORDER BY finishedAt DESC LIMIT ?",
-      [queueName, limit]
-    );
+    var built = _select()
+      .columns(["_id", "queueName", "payload", "status", "enqueuedAt", "finishedAt",
+                "attempts", "maxAttempts", "lastError", "traceId", "classification"])
+      .where("queueName", queueName)
+      .where("status", "failed")
+      .orderBy("finishedAt", "desc")
+      .limit(limit)
+      .toSql();
+    var rows = await store.executeAll(built.sql, built.params);
     return rows.map(function (row) {
       var unsealed = cryptoField.unsealRow(SEAL_TABLE, row);
       return {
@@ -532,36 +590,39 @@ function create(config) {
   async function dlqRetry(jobId) {
     cluster.requireLeader();
     var nowMs = Date.now();
-    var result = await store.execute(
-      "UPDATE " + qTable + " SET " +
-      "  status = 'pending', " +
-      "  attempts = 0, " +
-      "  availableAt = ?, " +
-      "  finishedAt = NULL, " +
-      "  leasedAt = NULL, " +
-      "  leaseExpiresAt = NULL, " +
-      "  lastError = NULL " +
-      "WHERE _id = ? AND status = 'failed'",
-      [nowMs, jobId]
-    );
+    // NULL resets bind as null params (the prior SQL-literal NULLs); the
+    // string-literal statuses bind too.
+    var built = _update()
+      .set({
+        status:         "pending",
+        attempts:       0,
+        availableAt:    nowMs,
+        finishedAt:     null,
+        leasedAt:       null,
+        leaseExpiresAt: null,
+        lastError:      null,
+      })
+      .where("_id", jobId)
+      .where("status", "failed")
+      .toSql();
+    var result = await store.execute(built.sql, built.params);
     return (result.rowCount || 0) > 0;
   }
 
   async function dlqSize(queueName) {
-    var row = await store.executeOne(
-      "SELECT COUNT(*) AS n FROM " + qTable + " " +
-      "WHERE queueName = ? AND status = 'failed'",
-      [queueName]
-    );
+    var built = _select()
+      .count("*", "n")
+      .where("queueName", queueName)
+      .where("status", "failed")
+      .toSql();
+    var row = await store.executeOne(built.sql, built.params);
     return row ? Number(row.n) : 0;
   }
 
   async function purge(queueName) {
     cluster.requireLeader();
-    var result = await store.execute(
-      "DELETE FROM " + qTable + " WHERE queueName = ?",
-      [queueName]
-    );
+    var built = _delete().where("queueName", queueName).toSql();
+    var result = await store.execute(built.sql, built.params);
     return result.rowCount || 0;
   }
 
@@ -575,10 +636,12 @@ function create(config) {
   // 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]
-    );
+    var built = _update()
+      .set("dependsOn", JSON.stringify(depIds))
+      .set("availableAt", FLOW_BLOCKED_AVAILABLE_AT)
+      .where("_id", jobId)
+      .toSql();
+    var result = await store.execute(built.sql, built.params);
     return (result.rowCount || 0) > 0;
   }
 

package/lib/queue-redis.js

@@ -310,7 +310,10 @@ function create(opts) {
   // contract queue-local returns from _shapeLeasedRow.
   function _shapeLeasedRow(jobId, raw) {
     if (!raw) return null;
-    // Pretend it's a "_blamejs_jobs" row so cryptoField unseals correctly.
+    // The cryptoField seal-table registry KEY (matches db.js's registerTable
+    // literal), not a SQL table name; this adapter holds no SQL (Redis
+    // ZSET/HASH ops). Keep it byte-identical so payload + lastError unseal.
+    // allow:hand-rolled-sql — cryptoField seal-table registry KEY, not SQL.
     var unsealed = cryptoField.unsealRow("_blamejs_jobs", raw);
     return {
       jobId:          jobId,
@@ -368,6 +371,9 @@ function create(opts) {
       dependsOn:       Array.isArray(opts2.dependsOn) && opts2.dependsOn.length > 0
                           ? JSON.stringify(opts2.dependsOn) : null,
     };
+    // cryptoField seal-table registry KEY (db.js registers payload + lastError
+    // under this literal), not a SQL table; this Redis adapter holds no SQL.
+    // allow:hand-rolled-sql — cryptoField seal-table registry KEY, not SQL.
     var sealed = cryptoField.sealRow("_blamejs_jobs", row);
 
     // Pipeline: HSET job + ZADD ready + SADD queues + (if flowId)
@@ -466,6 +472,7 @@ function create(opts) {
 
     if (raw.repeatCron) {
       try {
+        // allow:hand-rolled-sql — cryptoField seal-table registry KEY, not SQL.
         var unsealed = cryptoField.unsealRow("_blamejs_jobs", raw);
         var cron = scheduler.parseCron(unsealed.repeatCron);
         var nextMs = scheduler.nextCronFire(
@@ -689,6 +696,7 @@ function create(opts) {
     for (var i = 0; i < idStrs.length; i++) {
       var raw = _decodeHash(hashes[i]);
       if (!raw) continue;
+      // allow:hand-rolled-sql — cryptoField seal-table registry KEY, not SQL.
       var unsealed = cryptoField.unsealRow("_blamejs_jobs", raw);
       out.push({
         jobId:          idStrs[i],

package/lib/queue-sqs.js

@@ -175,6 +175,11 @@ function create(opts) {
     enqueueOpts = enqueueOpts || {};
     var queueUrl = queueUrlResolver(queueName);
     var jobId = generateToken(C.BYTES.bytes(16));
+    // The cryptoField seal-table registry KEY (matches db.js's registerTable
+    // literal), not a SQL table name; this SQS adapter holds no SQL
+    // (AWSJsonProtocol over HTTPS). Keep it byte-identical so the sealed
+    // message body unseals under the same schema on receive.
+    // allow:hand-rolled-sql — cryptoField seal-table registry KEY, not SQL.
     var sealed = cryptoField.sealRow("_blamejs_jobs", {
       _id:           jobId,
       queueName:     queueName,
@@ -222,6 +227,7 @@ function create(opts) {
       var sealed;
       try { sealed = safeJson.parse(m.Body); }
       catch (_e) { continue; }
+      // allow:hand-rolled-sql — cryptoField seal-table registry KEY, not SQL.
       var unsealed = cryptoField.unsealRow("_blamejs_jobs", sealed);
       var payload;
       try {