@blamejs/core 0.4.20 → 0.4.22

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.21** (2026-04-30) — b.queue: repeat-in-queue (cron) + parent-child Flows
+- **0.4.20** (2026-04-30) — b.queue + b.jobs: priority, rate-limit, progress
 - **0.4.19** (2026-04-30) — b.router: schema-validated routes + OpenAPI gen
 - **0.4.18** (2026-04-30) — cookieJar forensic-test strengthening (real crypto, replay, nonce)
 - **0.4.17** (2026-04-30) — b.httpClient.cookieJar (encrypted) + wiki catch-up sweep

package/lib/db.js

@@ -351,12 +351,22 @@ var FRAMEWORK_SCHEMA = [
       traceId:         "TEXT",
       classification:  "TEXT",
       priority:        "INTEGER NOT NULL DEFAULT 0",
+      // Repeat-in-queue: cron-shaped recurring jobs re-enqueue themselves
+      // after each successful completion. NULL = one-shot (no repeat).
+      repeatCron:      "TEXT",
+      repeatTimezone:  "TEXT",
+      // Flows: parent-child job graphs with dependency edges.
+      // flowId groups jobs in the same flow; dependsOn is a JSON array
+      // of jobIds this row waits for; flowChildName is the human-readable
+      // label inside the flow used by dependsOn resolution.
+      flowId:          "TEXT",
+      flowChildName:   "TEXT",
+      dependsOn:       "TEXT",
     },
     indexes: [
       { name: "idx_jobs_lease",    columns: ["queueName", "status", "availableAt"] },
-      // Priority lease index — pickers walk this when ORDER BY priority DESC,
-      // availableAt ASC, enqueuedAt ASC; matches the queue.lease ordering.
       { name: "idx_jobs_priority", columns: ["queueName", "status", "priority", "availableAt"] },
+      { name: "idx_jobs_flow",     columns: ["flowId"] },
       "leaseExpiresAt",
       "finishedAt",
     ],

package/lib/framework-schema.js

@@ -477,11 +477,17 @@ function _jobsDDL(dialect) {
       "  finishedAt       " + t.INT + "," +
       "  traceId          TEXT," +
       "  classification   TEXT," +
-      "  priority         " + t.INT + " NOT NULL DEFAULT 0" +
+      "  priority         " + t.INT + " NOT NULL DEFAULT 0," +
+      "  repeatCron       TEXT," +
+      "  repeatTimezone   TEXT," +
+      "  flowId           TEXT," +
+      "  flowChildName    TEXT," +
+      "  dependsOn        TEXT" +
       ")",
     indexes: [
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_lease ON " + name + " (queueName, status, availableAt)",
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_priority ON " + name + " (queueName, status, priority, availableAt)",
+      "CREATE INDEX IF NOT EXISTS idx_" + name + "_flow ON " + name + " (flowId)",
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_leaseExpiresAt ON " + name + " (leaseExpiresAt)",
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_finishedAt ON " + name + " (finishedAt)",
     ],

package/lib/mail.js

@@ -38,9 +38,24 @@
  *       text:     "plain body"                (at least one of text/html)
  *       html:     "<p>...</p>"
  *       headers:  { "X-Custom": "v" }         (merged with defaults)
+ *       attachments: [{
+ *         filename:           "report.pdf",        // required
+ *         content:             buf,                // Buffer or string
+ *         contentType:         "application/pdf",  // default application/octet-stream
+ *         contentDisposition:  "attachment",       // or "inline"
+ *         cid:                 "logo-1",            // for inline images:
+ *                                                  // <img src="cid:logo-1">
+ *       }, ...]
  *     }
  *     → whatever the transport returned
  *
+ * When attachments are present the SMTP transport wraps the body in
+ * multipart/mixed; text+html bodies still use multipart/alternative
+ * inside. Resend's http preset forwards attachments via the Resend API
+ * shape (base64 content + content_id for inline). Operators wiring
+ * other vendors against httpTransport include attachments in their
+ * own serialize() per-vendor.
+ *
  * Validation surface uses MailError (FrameworkError subclass) with
  * permanent flag. Distinct codes per failure: missing-to, missing-from,
  * missing-body, invalid-recipient, transport-failed, smtp-*, http-*,
@@ -128,6 +143,52 @@ function _validateMessage(message) {
     throw new MailError("mail/missing-body",
       "message must include at least one of text or html", true);
   }
+
+  if (message.attachments !== undefined) {
+    if (!Array.isArray(message.attachments)) {
+      throw new MailError("mail/invalid-attachments",
+        "message.attachments must be an array", true);
+    }
+    for (var i = 0; i < message.attachments.length; i++) {
+      var att = message.attachments[i];
+      if (!att || typeof att !== "object") {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "] must be an object", true);
+      }
+      if (typeof att.filename !== "string" || att.filename.length === 0) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].filename must be a non-empty string", true);
+      }
+      if (/[\r\n\0]/.test(att.filename)) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].filename contains forbidden control characters", true);
+      }
+      if (att.content === undefined || att.content === null) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].content is required (Buffer or string)", true);
+      }
+      if (!Buffer.isBuffer(att.content) && typeof att.content !== "string") {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].content must be a Buffer or string", true);
+      }
+      if (att.contentType !== undefined &&
+          (typeof att.contentType !== "string" || /[\r\n\0]/.test(att.contentType))) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].contentType must be a clean string", true);
+      }
+      if (att.contentDisposition !== undefined &&
+          att.contentDisposition !== "attachment" &&
+          att.contentDisposition !== "inline") {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].contentDisposition must be 'attachment' or 'inline'", true);
+      }
+      if (att.cid !== undefined &&
+          (typeof att.cid !== "string" || /[\r\n\0<>]/.test(att.cid))) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].cid must be a clean string (no <>)", true);
+      }
+    }
+  }
 }
 
 function _mergeMessage(defaults, message) {
@@ -201,6 +262,59 @@ function memoryTransport() {
 // cleartext port the transport always issues STARTTLS and refuses
 // to send AUTH or DATA in cleartext if the upgrade is rejected.
 
+function _newBoundary(label) {
+  return "blamejs-" + label + "-" + Date.now() + "-" + Math.floor(Math.random() * 1e9);
+}
+
+// base64-encode the buffer with line wrapping at 76 chars (RFC 2045
+// §6.8). Most clients tolerate longer lines but the spec maximum is
+// 998 octets per line; sticking to 76 keeps everyone happy.
+function _base64Wrap(buf) {
+  var b64 = buf.toString("base64");
+  var lines = [];
+  for (var i = 0; i < b64.length; i += 76) lines.push(b64.slice(i, i + 76));
+  return lines.join("\r\n");
+}
+
+function _buildAttachmentPart(att) {
+  var content = Buffer.isBuffer(att.content) ? att.content : Buffer.from(String(att.content), "utf8");
+  var contentType = att.contentType || "application/octet-stream";
+  var disposition = att.contentDisposition || (att.cid ? "inline" : "attachment");
+  var lines = [];
+  lines.push("Content-Type: " + contentType + '; name="' + att.filename + '"');
+  lines.push("Content-Transfer-Encoding: base64");
+  lines.push("Content-Disposition: " + disposition + '; filename="' + att.filename + '"');
+  if (att.cid) lines.push("Content-ID: <" + att.cid + ">");
+  lines.push("");
+  lines.push(_base64Wrap(content));
+  return lines.join("\r\n");
+}
+
+function _buildBodyPart(message) {
+  // Text + html → multipart/alternative; otherwise single-part.
+  if (message.text && message.html) {
+    var altBoundary = _newBoundary("alt");
+    return {
+      contentType: 'multipart/alternative; boundary="' + altBoundary + '"',
+      body: [
+        "--" + altBoundary,
+        "Content-Type: text/plain; charset=utf-8",
+        "",
+        message.text,
+        "--" + altBoundary,
+        "Content-Type: text/html; charset=utf-8",
+        "",
+        message.html,
+        "--" + altBoundary + "--",
+      ].join("\r\n"),
+    };
+  }
+  if (message.html) {
+    return { contentType: "text/html; charset=utf-8", body: message.html };
+  }
+  return { contentType: "text/plain; charset=utf-8", body: message.text || "" };
+}
+
 function _buildRfc822(message) {
   var headers = [];
   headers.push("From: " + message.from);
@@ -221,27 +335,32 @@ function _buildRfc822(message) {
     }
   }
 
+  var attachments = Array.isArray(message.attachments) ? message.attachments : [];
+  var inner = _buildBodyPart(message);
   var body;
-  if (message.text && message.html) {
-    var boundary = "blamejs-mail-" + Date.now() + "-" + Math.floor(Math.random() * 1e9);
-    headers.push('Content-Type: multipart/alternative; boundary="' + boundary + '"');
-    body = [
-      "--" + boundary,
-      "Content-Type: text/plain; charset=utf-8",
-      "",
-      message.text,
-      "--" + boundary,
-      "Content-Type: text/html; charset=utf-8",
-      "",
-      message.html,
-      "--" + boundary + "--",
-    ].join("\r\n");
-  } else if (message.html) {
-    headers.push("Content-Type: text/html; charset=utf-8");
-    body = message.html;
+
+  if (attachments.length === 0) {
+    headers.push("Content-Type: " + inner.contentType);
+    body = inner.body;
   } else {
-    headers.push("Content-Type: text/plain; charset=utf-8");
-    body = message.text || "";
+    // multipart/mixed: first part is the body (single or alternative),
+    // subsequent parts are the attachments. Inline disposition + Content-ID
+    // is interpreted correctly by every major client even inside mixed;
+    // operators with strict-RFC-2387 multipart/related needs subscribe
+    // to a future patch when demand surfaces.
+    var mixedBoundary = _newBoundary("mixed");
+    headers.push('Content-Type: multipart/mixed; boundary="' + mixedBoundary + '"');
+    var parts = [];
+    parts.push("--" + mixedBoundary);
+    parts.push("Content-Type: " + inner.contentType);
+    parts.push("");
+    parts.push(inner.body);
+    for (var ai = 0; ai < attachments.length; ai++) {
+      parts.push("--" + mixedBoundary);
+      parts.push(_buildAttachmentPart(attachments[ai]));
+    }
+    parts.push("--" + mixedBoundary + "--");
+    body = parts.join("\r\n");
   }
 
   // Normalize line endings then dot-stuff per SMTP transparency.
@@ -587,6 +706,21 @@ function resendTransport(opts) {
       if (message.html)    payload.html     = message.html;
       if (message.text)    payload.text     = message.text;
       if (message.headers) payload.headers  = message.headers;
+      // Resend attachments shape: [{ filename, content (base64 string),
+      // contentType?, content_id? }]. Inline images via cid go through
+      // the content_id field (Resend renders <img src="cid:...">).
+      if (Array.isArray(message.attachments) && message.attachments.length > 0) {
+        payload.attachments = message.attachments.map(function (att) {
+          var buf = Buffer.isBuffer(att.content) ? att.content : Buffer.from(String(att.content), "utf8");
+          var entry = {
+            filename: att.filename,
+            content:  buf.toString("base64"),
+          };
+          if (att.contentType) entry.contentType = att.contentType;
+          if (att.cid)         entry.content_id  = att.cid;
+          return entry;
+        });
+      }
       return { body: JSON.stringify(payload) };
     },
     interpret: function (res) {
@@ -694,6 +828,9 @@ function create(opts) {
 module.exports = {
   create:     create,
   MailError:  MailError,
+  // Test-only export: lets unit tests inspect the wire format without
+  // standing up a TLS-capable SMTP fixture. Operators don't call this.
+  _buildRfc822ForTest: _buildRfc822,
   transports: {
     console: consoleTransport,
     memory:  memoryTransport,

package/lib/queue-local.js

@@ -51,14 +51,22 @@ var JOB_COLS = [
   "enqueuedAt", "availableAt", "leasedAt", "leaseExpiresAt",
   "attempts", "maxAttempts", "lastError", "finishedAt",
   "traceId", "classification", "priority",
+  "repeatCron", "repeatTimezone",
+  "flowId", "flowChildName", "dependsOn",
 ];
 
+// Sentinel availableAt for flow children that haven't yet had their
+// dependencies satisfied — far future so the lease query never picks
+// them. Parent-completion sets a real availableAt when all deps complete.
+var FLOW_BLOCKED_AVAILABLE_AT = Number.MAX_SAFE_INTEGER;
+
 // Columns returned by lease() / used by RETURNING. Subset of JOB_COLS
 // — only what callers need; fewer bytes over the wire in cluster mode.
 var LEASE_RETURN_COLS = [
   "_id", "queueName", "payload",
   "attempts", "maxAttempts", "traceId", "classification",
   "enqueuedAt", "leaseExpiresAt",
+  "repeatCron", "repeatTimezone", "flowId", "flowChildName",
 ];
 
 function _quotedList(cols) {
@@ -84,6 +92,10 @@ function _shapeLeasedRow(raw) {
     classification: unsealed.classification,
     enqueuedAt:     Number(unsealed.enqueuedAt),
     leaseExpiresAt: Number(unsealed.leaseExpiresAt),
+    repeatCron:     unsealed.repeatCron     || null,
+    repeatTimezone: unsealed.repeatTimezone || null,
+    flowId:         unsealed.flowId         || null,
+    flowChildName:  unsealed.flowChildName  || null,
   };
 }
 
@@ -99,13 +111,25 @@ function create(_config) {
 
     var priority = (typeof opts.priority === "number" && isFinite(opts.priority))
       ? Math.floor(opts.priority) : 0;
+    var repeatCron     = opts.repeat && typeof opts.repeat.cron === "string"
+                            ? opts.repeat.cron : null;
+    var repeatTimezone = opts.repeat && typeof opts.repeat.timezone === "string"
+                            ? opts.repeat.timezone : null;
+    var flowId         = typeof opts.flowId === "string" ? opts.flowId : null;
+    var flowChildName  = typeof opts.flowChildName === "string" ? opts.flowChildName : null;
+    var dependsOn      = Array.isArray(opts.dependsOn) && opts.dependsOn.length > 0
+                            ? JSON.stringify(opts.dependsOn) : null;
+    // Flow children with deps wait at MAX_SAFE_INTEGER until parent
+    // completion bumps availableAt — keeps them out of the lease index.
+    var effectiveAvailableAt = (dependsOn ? FLOW_BLOCKED_AVAILABLE_AT : availableAt);
+
     var row = {
       _id:             generateToken(16),
       queueName:       queueName,
       payload:         payload === undefined ? null : JSON.stringify(payload),
       status:          "pending",
       enqueuedAt:      nowMs,
-      availableAt:     availableAt,
+      availableAt:     effectiveAvailableAt,
       leasedAt:        null,
       leaseExpiresAt:  null,
       attempts:        0,
@@ -115,6 +139,11 @@ function create(_config) {
       traceId:         opts.traceId || null,
       classification:  opts.classification || null,
       priority:        priority,
+      repeatCron:      repeatCron,
+      repeatTimezone:  repeatTimezone,
+      flowId:          flowId,
+      flowChildName:   flowChildName,
+      dependsOn:       dependsOn,
     };
     var sealed = cryptoField.sealRow("_blamejs_jobs", row);
     var values = JOB_COLS.map(function (c) { return c in sealed ? sealed[c] : null; });
@@ -187,14 +216,94 @@ function create(_config) {
 
   async function complete(jobId) {
     cluster.requireLeader();
+    var nowMs = Date.now();
+    // Read the row first so we can act on repeat / flow metadata after
+    // 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(
+      "SELECT _id, queueName, payload, repeatCron, repeatTimezone, " +
+      "       flowId, flowChildName, priority, classification, traceId " +
+      "FROM _blamejs_jobs WHERE _id = ?",
+      [jobId]
+    );
+    var row = (rowRes && rowRes.rows && rowRes.rows[0]) || null;
+
     await clusterStorage.execute(
       "UPDATE _blamejs_jobs SET status = 'done', finishedAt = ?, leaseExpiresAt = NULL " +
       "WHERE _id = ? AND status = 'inflight'",
-      [Date.now(), jobId]
+      [nowMs, jobId]
     );
+
+    // Repeat-in-queue: cron-recurring job re-enqueues itself for the
+    // next firing time. Failures (which take the fail() path) don't
+    // re-enqueue — operators investigate before the cron resumes.
+    if (row && row.repeatCron) {
+      try {
+        var unsealedRow = cryptoField.unsealRow("_blamejs_jobs", row);
+        var scheduler = require("./scheduler");
+        var cron = scheduler.parseCron(unsealedRow.repeatCron);
+        var nextMs = scheduler.nextCronFire(cron, new Date(nowMs), unsealedRow.repeatTimezone || null);
+        await enqueue(unsealedRow.queueName,
+          unsealedRow.payload ? safeJson.parse(unsealedRow.payload) : null,
+          {
+            availableAt:     nextMs,
+            delaySeconds:    Math.max(0, Math.floor((nextMs - nowMs) / 1000)),
+            repeat:          { cron: unsealedRow.repeatCron, timezone: unsealedRow.repeatTimezone },
+            priority:        Number(unsealedRow.priority) || 0,
+            classification:  unsealedRow.classification || null,
+            traceId:         unsealedRow.traceId || null,
+          });
+      } catch (_e) { /* repeat re-enqueue best-effort — cron resumes next tick if op fixes the issue */ }
+    }
+
+    // Flow propagation: walk siblings whose dependsOn includes this
+    // jobId (or this job's flowChildName) and bump availableAt to now
+    // if ALL their deps are now complete.
+    if (row && row.flowId) {
+      await _maybeReleaseFlowChildren(row.flowId, jobId, row.flowChildName, nowMs);
+    }
     return true;
   }
 
+  async function _maybeReleaseFlowChildren(flowId, completedJobId, completedChildName, nowMs) {
+    var siblingsRes = await clusterStorage.execute(
+      "SELECT _id, dependsOn, flowChildName, status, availableAt FROM _blamejs_jobs " +
+      "WHERE flowId = ? AND status = 'pending' AND availableAt > ?",
+      [flowId, nowMs]
+    );
+    var siblings = (siblingsRes && siblingsRes.rows) || [];
+    for (var i = 0; i < siblings.length; i++) {
+      var sib = siblings[i];
+      if (!sib.dependsOn) continue;
+      var deps;
+      try { deps = JSON.parse(sib.dependsOn); }
+      catch (_e) { continue; }
+      if (!Array.isArray(deps) || deps.length === 0) continue;
+      // Resolve which deps are satisfied. Each dep is either a jobId
+      // or a flowChildName; we accept both shapes against the flow.
+      var allDone = true;
+      for (var d = 0; d < deps.length; d++) {
+        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 clusterStorage.execute(
+          "SELECT 1 FROM _blamejs_jobs 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 = ?",
+          [nowMs, sib._id]
+        );
+      }
+    }
+  }
+
   async function fail(jobId, errorMessage, opts) {
     cluster.requireLeader();
     opts = opts || {};

package/lib/queue.js

@@ -488,9 +488,142 @@ function _resetForTest() {
   audit.reset();
 }
 
+// enqueueFlow — atomic registration of a parent-child job graph.
+//
+//   await b.queue.enqueueFlow({
+//     queueName: "ingest",
+//     children: [
+//       { name: "fetch",      payload: { url } },
+//       { name: "transform",  payload: { ... }, dependsOn: ["fetch"] },
+//       { name: "publish",    payload: { ... }, dependsOn: ["transform"] },
+//     ],
+//   });
+//
+// Cycle detection runs at registration (Tier-A throw). Each child enters
+// the queue with availableAt = MAX_SAFE_INTEGER until parent completion
+// bumps it. Returns { flowId, jobs: [{ name, jobId }, ...] }.
+function enqueueFlow(spec) {
+  _requireInit();
+  if (!spec || typeof spec !== "object") {
+    return Promise.reject(_err("BAD_FLOW", "enqueueFlow requires an opts object", true));
+  }
+  if (typeof spec.queueName !== "string" || !spec.queueName) {
+    return Promise.reject(_err("BAD_FLOW", "enqueueFlow requires queueName", true));
+  }
+  if (!Array.isArray(spec.children) || spec.children.length === 0) {
+    return Promise.reject(_err("BAD_FLOW", "enqueueFlow requires children: [...]", true));
+  }
+  // Validate each child's shape.
+  var byName = {};
+  for (var i = 0; i < spec.children.length; i++) {
+    var c = spec.children[i];
+    if (!c || typeof c !== "object") {
+      return Promise.reject(_err("BAD_FLOW", "children[" + i + "] must be an object", true));
+    }
+    if (typeof c.name !== "string" || !c.name) {
+      return Promise.reject(_err("BAD_FLOW", "children[" + i + "].name must be a non-empty string", true));
+    }
+    if (byName[c.name]) {
+      return Promise.reject(_err("BAD_FLOW", "duplicate child name '" + c.name + "'", true));
+    }
+    byName[c.name] = c;
+    if (c.dependsOn !== undefined) {
+      if (!Array.isArray(c.dependsOn)) {
+        return Promise.reject(_err("BAD_FLOW",
+          "children[" + i + "].dependsOn must be an array of names", true));
+      }
+      for (var di = 0; di < c.dependsOn.length; di++) {
+        if (typeof c.dependsOn[di] !== "string") {
+          return Promise.reject(_err("BAD_FLOW",
+            "children[" + i + "].dependsOn[" + di + "] must be a string name", true));
+        }
+      }
+    }
+  }
+  // Cycle detection — depth-first traversal with visited set.
+  function _visit(name, stack) {
+    if (stack.indexOf(name) !== -1) {
+      throw _err("FLOW_CYCLE", "flow cycle detected: " +
+        stack.concat([name]).join(" → "), true);
+    }
+    var child = byName[name];
+    if (!child || !child.dependsOn) return;
+    var nextStack = stack.concat([name]);
+    for (var k = 0; k < child.dependsOn.length; k++) {
+      var dep = child.dependsOn[k];
+      if (!byName[dep]) {
+        throw _err("FLOW_UNKNOWN_DEP",
+          "child '" + name + "' dependsOn unknown name '" + dep + "'", true);
+      }
+      _visit(dep, nextStack);
+    }
+  }
+  try {
+    var names = Object.keys(byName);
+    for (var n = 0; n < names.length; n++) _visit(names[n], []);
+  } catch (e) {
+    return Promise.reject(e);
+  }
+
+  var nodeCrypto = require("node:crypto");
+  var flowId = "flow-" + nodeCrypto.randomBytes(8).toString("hex");
+
+  return observability.tap("queue.enqueueFlow",
+    { queueName: spec.queueName, flowId: flowId, childCount: spec.children.length },
+    async function () {
+      var jobs = [];
+      // Two-pass insert: first pass enqueues all children with their
+      // names attached so the second pass can write dependsOn jobIds
+      // resolved by name. Children with deps land at MAX_SAFE_INTEGER
+      // availableAt automatically (see queue-local enqueue logic).
+      var nameToJobId = {};
+      for (var p = 0; p < spec.children.length; p++) {
+        var ch = spec.children[p];
+        // Hold off setting dependsOn until we know all sibling jobIds.
+        var enqOpts = {
+          flowId:        flowId,
+          flowChildName: ch.name,
+          priority:      ch.priority || 0,
+          classification: ch.classification || null,
+          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.
+        };
+        var result = await enqueue(spec.queueName, ch.payload, enqOpts);
+        nameToJobId[ch.name] = result.jobId;
+        jobs.push({ name: ch.name, jobId: result.jobId, dependsOn: ch.dependsOn || [] });
+      }
+      // Second pass: write dependsOn (translated to jobIds) for children
+      // that need it, and parking-lot their availableAt to MAX_SAFE_INTEGER.
+      var clusterStorage = require("./cluster-storage");
+      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]
+        );
+      }
+      _emit("system.queue.flow.enqueue", {
+        metadata: {
+          queue:      spec.queueName,
+          flowId:     flowId,
+          childCount: spec.children.length,
+        },
+      });
+      return { flowId: flowId, jobs: jobs.map(function (j) { return { name: j.name, jobId: j.jobId }; }) };
+    }
+  );
+}
+
 module.exports = {
   init:               init,
   enqueue:            enqueue,
+  enqueueFlow:        enqueueFlow,
   consume:            consume,
   size:               size,
   purge:              purge,

package/package.json

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