mailery 0.17.1 → 0.19.0

package/dist/testing.cjs

@@ -134,6 +134,42 @@ __export(mongo_exports, {
 function canBeObjectId(s) {
   return typeof s === "string" && /^[a-f0-9]{24}$/i.test(s);
 }
+function getPath(doc, path2) {
+  let cur = doc;
+  for (const part of path2.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function isObjectIdLike(v) {
+  return !!v && typeof v === "object" && typeof v.toHexString === "function" && v._bsontype === "ObjectId";
+}
+function packScalar(v) {
+  if (v instanceof Date) return { d: v.toISOString() };
+  if (isObjectIdLike(v)) return { o: v.toHexString() };
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  return null;
+}
+function unpackScalar(v) {
+  if (v && typeof v === "object") {
+    if ("d" in v) return new Date(v.d);
+    if ("o" in v) return new mongodb.ObjectId(v.o);
+  }
+  return v;
+}
+function encodeSortCursor(value, id) {
+  return Buffer.from(JSON.stringify({ v: packScalar(value), i: packScalar(id) }), "utf8").toString("base64url");
+}
+function decodeSortCursor(cursor) {
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || !("v" in parsed) || !("i" in parsed)) return null;
+    return { value: unpackScalar(parsed.v), id: unpackScalar(parsed.i) };
+  } catch {
+    return null;
+  }
+}
 var MongoContactAdapter;
 var init_mongo = __esm({
   "src/server/adapters/mongo.ts"() {
@@ -183,7 +219,10 @@ var init_mongo = __esm({
         }
         return out;
       }
+      /** `query` honours `opts.sort` — see `querySorted`. */
+      supportsSort = true;
       async query(filter, opts) {
+        if (opts.sort) return this.querySorted(filter, opts.limit, opts.cursor, opts.sort);
         const query = this.translateFilterFn(filter);
         const limit = Math.min(opts.limit, this.batchSize);
         if (opts.cursor) {
@@ -202,6 +241,52 @@ var init_mongo = __esm({
         const query = this.translateFilterFn(filter);
         return await this.col.countDocuments(query);
       }
+      /**
+       * Keyset pagination in (sort.field, idField) order. The cursor encodes the
+       * last row's sort value and id, and the next page is every row strictly
+       * after that position. Mongo sorts a null or missing value lowest, so
+       * `desc` puts contacts without the field last and `asc` puts them first;
+       * the position predicate follows the same rule, so they are neither
+       * skipped nor repeated.
+       *
+       * The field should hold one BSON type (or be absent): range operators only
+       * compare within a type. A value that moves while a pass is paging (a
+       * contact whose `updatedAt` changes mid-dispatch) can be seen twice or not
+       * at all in that pass; broadcast dispatch tolerates both (the per-recipient
+       * dedupe key stops a second send, and a later pass picks up a skipped one).
+       * Index `{ <field>: -1, <idField>: 1 }` on a large collection.
+       */
+      async querySorted(filter, limitIn, cursor, sort) {
+        const base = this.translateFilterFn(filter);
+        const limit = Math.min(limitIn, this.batchSize);
+        const dir = sort.direction === "desc" ? -1 : 1;
+        let query = base;
+        if (cursor) {
+          const pos = decodeSortCursor(cursor);
+          if (!pos) throw new Error("MongoContactAdapter: malformed sort cursor");
+          query = { $and: [base, this.afterPosition(sort.field, dir, pos.value, pos.id)] };
+        }
+        const docs = await this.col.find(query).sort({ [sort.field]: dir, [this.idField]: 1 }).limit(limit + 1).toArray();
+        const hasMore = docs.length > limit;
+        const slice = hasMore ? docs.slice(0, limit) : docs;
+        const last = slice[slice.length - 1];
+        return {
+          contacts: slice.map((d) => this.toContactFn(d)),
+          nextCursor: hasMore && last ? encodeSortCursor(getPath(last, sort.field), last[this.idField]) : void 0
+        };
+      }
+      afterPosition(field, dir, value, id) {
+        const idF = this.idField;
+        const isNull = value === null || value === void 0;
+        if (dir === -1) {
+          if (isNull) return { [field]: null, [idF]: { $gt: id } };
+          return {
+            $or: [{ [field]: { $lt: value } }, { [field]: value, [idF]: { $gt: id } }, { [field]: null }]
+          };
+        }
+        if (isNull) return { $or: [{ [field]: null, [idF]: { $gt: id } }, { [field]: { $ne: null } }] };
+        return { $or: [{ [field]: { $gt: value } }, { [field]: value, [idF]: { $gt: id } }] };
+      }
       addTags;
       removeTags;
       // -------------------------------------------------------------------------
@@ -1941,9 +2026,9 @@ https://typegoose.github.io/mongodb-memory-server/docs/guides/migration/migrate7
     exports.AssertionFallbackError = AssertionFallbackError;
     var ReplsetCountLowError = class extends Error {
       count;
-      constructor(count) {
-        super(`ReplSet Count needs to be 1 or higher! (specified count: "${count}")`);
-        this.count = count;
+      constructor(count2) {
+        super(`ReplSet Count needs to be 1 or higher! (specified count: "${count2}")`);
+        this.count = count2;
       }
     };
     exports.ReplsetCountLowError = ReplsetCountLowError;
@@ -3275,20 +3360,20 @@ var require_range = __commonJS({
       }
       return `${from} ${to}`.trim();
     };
-    var testSet = (set, version, options2) => {
-      for (let i = 0; i < set.length; i++) {
-        if (!set[i].test(version)) {
+    var testSet = (set2, version, options2) => {
+      for (let i = 0; i < set2.length; i++) {
+        if (!set2[i].test(version)) {
           return false;
         }
       }
       if (version.prerelease.length && !options2.includePrerelease) {
-        for (let i = 0; i < set.length; i++) {
-          debug(set[i].semver);
-          if (set[i].semver === Comparator.ANY) {
+        for (let i = 0; i < set2.length; i++) {
+          debug(set2[i].semver);
+          if (set2[i].semver === Comparator.ANY) {
             continue;
           }
-          if (set[i].semver.prerelease.length > 0) {
-            const allowed = set[i].semver;
+          if (set2[i].semver.prerelease.length > 0) {
+            const allowed = set2[i].semver;
             if (allowed.major === version.major && allowed.minor === version.minor && allowed.patch === version.patch) {
               return true;
             }
@@ -3672,7 +3757,7 @@ var require_simplify = __commonJS({
     var satisfies = require_satisfies();
     var compare = require_compare();
     module.exports = (versions, range, options2) => {
-      const set = [];
+      const set2 = [];
       let first = null;
       let prev = null;
       const v = versions.sort((a, b) => compare(a, b, options2));
@@ -3685,17 +3770,17 @@ var require_simplify = __commonJS({
           }
         } else {
           if (prev) {
-            set.push([first, prev]);
+            set2.push([first, prev]);
           }
           prev = null;
           first = null;
         }
       }
       if (first) {
-        set.push([first, null]);
+        set2.push([first, null]);
       }
       const ranges = [];
-      for (const [min, max] of set) {
+      for (const [min, max] of set2) {
         if (min === max) {
           ranges.push(min);
         } else if (!max && min === v[0]) {
@@ -10672,18 +10757,18 @@ var require_semver3 = __commonJS({
       range = range.replace(safeRe[t.CARETTRIM], caretTrimReplace);
       range = range.split(/\s+/).join(" ");
       var compRe = loose ? safeRe[t.COMPARATORLOOSE] : safeRe[t.COMPARATOR];
-      var set = range.split(" ").map(function(comp) {
+      var set2 = range.split(" ").map(function(comp) {
         return parseComparator(comp, this.options);
       }, this).join(" ").split(/\s+/);
       if (this.options.loose) {
-        set = set.filter(function(comp) {
+        set2 = set2.filter(function(comp) {
           return !!comp.match(compRe);
         });
       }
-      set = set.map(function(comp) {
+      set2 = set2.map(function(comp) {
         return new Comparator(comp, this.options);
       }, this);
-      return set;
+      return set2;
     };
     Range.prototype.intersects = function(range, options2) {
       if (!(range instanceof Range)) {
@@ -10911,20 +10996,20 @@ var require_semver3 = __commonJS({
       }
       return false;
     };
-    function testSet(set, version, options2) {
-      for (var i2 = 0; i2 < set.length; i2++) {
-        if (!set[i2].test(version)) {
+    function testSet(set2, version, options2) {
+      for (var i2 = 0; i2 < set2.length; i2++) {
+        if (!set2[i2].test(version)) {
           return false;
         }
       }
       if (version.prerelease.length && !options2.includePrerelease) {
-        for (i2 = 0; i2 < set.length; i2++) {
-          debug(set[i2].semver);
-          if (set[i2].semver === ANY) {
+        for (i2 = 0; i2 < set2.length; i2++) {
+          debug(set2[i2].semver);
+          if (set2[i2].semver === ANY) {
             continue;
           }
-          if (set[i2].semver.prerelease.length > 0) {
-            var allowed = set[i2].semver;
+          if (set2[i2].semver.prerelease.length > 0) {
+            var allowed = set2[i2].semver;
             if (allowed.major === version.major && allowed.minor === version.minor && allowed.patch === version.patch) {
               return true;
             }
@@ -14343,6 +14428,8 @@ var sendOneOffInputSchema = zod.z.object({
   providerOverride: zod.z.string().optional(),
   dedupeKey: zod.z.string().min(1).max(512)
 });
+zod.z.enum(["subscribed", "unsubscribed", "pending_doi", "bounced", "complained"]);
+zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.null()]);
 var flowStepSchema = zod.z.lazy(
   () => zod.z.discriminatedUnion("type", [
     zod.z.object({
@@ -14511,6 +14598,13 @@ var CIRCUIT_BREAKER_DEFAULTS = {
   windowMinutes: 60,
   minSendsBeforeEval: 100
 };
+var BROADCAST_STOP_RULE_DEFAULTS = {
+  enabled: true,
+  hardBounceRatePct: 2,
+  complaintRatePct: 0.1,
+  unsubscribeRatePct: 1,
+  minSample: 100
+};
 function resolveConfig(c) {
   return {
     ...c,
@@ -14538,7 +14632,8 @@ function resolveConfig(c) {
     storeRenderedBody: c.storeRenderedBody ?? DEFAULTS.storeRenderedBody,
     requireSignedTrackingUrls: c.requireSignedTrackingUrls ?? DEFAULTS.requireSignedTrackingUrls,
     trackingUrlLifetimeDays: c.trackingUrlLifetimeDays ?? DEFAULTS.trackingUrlLifetimeDays,
-    circuitBreaker: { ...CIRCUIT_BREAKER_DEFAULTS, ...c.circuitBreaker ?? {} }
+    circuitBreaker: { ...CIRCUIT_BREAKER_DEFAULTS, ...c.circuitBreaker ?? {} },
+    broadcastStopRules: { ...BROADCAST_STOP_RULE_DEFAULTS, ...c.broadcastStopRules ?? {} }
   };
 }
 
@@ -14756,11 +14851,13 @@ function resolveProvider(providers, name) {
 function registeredProviderNames(providers) {
   return Object.keys(providers).filter((name) => resolveProvider(providers, name) !== null).sort();
 }
+var SEND_ID_RE = /^[a-f0-9]{24}$/i;
 function signUnsubscribeToken(payload, secret) {
   const body = JSON.stringify({
     e: payload.email.toLowerCase(),
     s: payload.scope,
-    x: payload.expiresAt.getTime()
+    x: payload.expiresAt.getTime(),
+    ...payload.sendId && SEND_ID_RE.test(payload.sendId) ? { i: payload.sendId } : {}
   });
   const bodyB64 = b64url(Buffer.from(body, "utf8"));
   const hmac = crypto2__default.default.createHmac("sha256", secret).update(bodyB64).digest();
@@ -15319,11 +15416,11 @@ var ZERO_COUNTERS = {
   complained: 0,
   failedToSend: 0
 };
-var ZERO_RATES = {
-  bounceRate: 0,
-  hardBounceRate: 0,
-  complaintRate: 0,
-  failureRate: 0
+var EMPTY_RATES = {
+  bounceRate: null,
+  hardBounceRate: null,
+  complaintRate: null,
+  failureRate: null
 };
 async function recordHealthCounter(ctx, counter2, dims, by = 1) {
   const windowMs = ctx.config.circuitBreaker.windowMinutes * 60 * 1e3;
@@ -15353,7 +15450,7 @@ async function upsertCounter(ctx, _id, senderDomain, kind, counter2, by, windowM
         trippedAt: null,
         trippedReason: null,
         manuallyResumedAt: null,
-        rates: { ...ZERO_RATES }
+        rates: { ...EMPTY_RATES }
       },
       $set: { updatedAt: /* @__PURE__ */ new Date() }
     },
@@ -15380,7 +15477,7 @@ async function evaluateHealth(ctx) {
             windowStartedAt: /* @__PURE__ */ new Date(),
             windowDurationMs: windowMs,
             counters: { ...ZERO_COUNTERS },
-            rates: { ...ZERO_RATES },
+            rates: { ...EMPTY_RATES },
             status: "healthy",
             updatedAt: /* @__PURE__ */ new Date()
           }
@@ -15388,13 +15485,21 @@ async function evaluateHealth(ctx) {
       );
       continue;
     }
-    const c = doc.counters;
-    const total = c.sent || 1;
+    const c = { ...ZERO_COUNTERS, ...doc.counters };
+    const perSent = (n) => c.sent > 0 ? n / c.sent : null;
+    const attempts = c.sent + c.failedToSend;
     const rates = {
-      bounceRate: c.bounced / total,
-      hardBounceRate: c.hardBounced / total,
-      complaintRate: c.complained / total,
-      failureRate: c.failedToSend / total
+      bounceRate: perSent(c.bounced),
+      hardBounceRate: perSent(c.hardBounced),
+      complaintRate: perSent(c.complained),
+      // Failed attempts over all attempts, so it stays within 0–100%.
+      failureRate: attempts > 0 ? c.failedToSend / attempts : null
+    };
+    const pct2 = {
+      bounce: (rates.bounceRate ?? 0) * 100,
+      hardBounce: (rates.hardBounceRate ?? 0) * 100,
+      complaint: (rates.complaintRate ?? 0) * 100,
+      failure: (rates.failureRate ?? 0) * 100
     };
     await ctx.collections.health.updateOne(
       { _id: doc._id },
@@ -15404,12 +15509,12 @@ async function evaluateHealth(ctx) {
     if (c.sent < cb.minSendsBeforeEval) continue;
     if (doc.status === "tripped") continue;
     let trippedReason = null;
-    if (rates.hardBounceRate * 100 >= cb.hardBounceRatePctTrip) {
-      trippedReason = `hard bounce rate ${(rates.hardBounceRate * 100).toFixed(2)}% >= ${cb.hardBounceRatePctTrip}%`;
-    } else if (rates.complaintRate * 100 >= cb.complaintRatePctTrip) {
-      trippedReason = `complaint rate ${(rates.complaintRate * 100).toFixed(2)}% >= ${cb.complaintRatePctTrip}%`;
-    } else if (rates.bounceRate * 100 >= cb.combinedBounceRatePctTrip) {
-      trippedReason = `combined bounce rate ${(rates.bounceRate * 100).toFixed(2)}% >= ${cb.combinedBounceRatePctTrip}%`;
+    if (pct2.hardBounce >= cb.hardBounceRatePctTrip) {
+      trippedReason = `hard bounce rate ${pct2.hardBounce.toFixed(2)}% >= ${cb.hardBounceRatePctTrip}%`;
+    } else if (pct2.complaint >= cb.complaintRatePctTrip) {
+      trippedReason = `complaint rate ${pct2.complaint.toFixed(2)}% >= ${cb.complaintRatePctTrip}%`;
+    } else if (pct2.bounce >= cb.combinedBounceRatePctTrip) {
+      trippedReason = `combined bounce rate ${pct2.bounce.toFixed(2)}% >= ${cb.combinedBounceRatePctTrip}%`;
     }
     if (trippedReason) {
       const result = await ctx.collections.health.updateOne(
@@ -15444,7 +15549,7 @@ async function evaluateHealth(ctx) {
       }
       continue;
     }
-    if (rates.failureRate * 100 >= cb.failedToSendRatePctDegrade) {
+    if (pct2.failure >= cb.failedToSendRatePctDegrade) {
       if (doc.status !== "degraded") {
         await ctx.collections.health.updateOne(
           { _id: doc._id },
@@ -15464,6 +15569,179 @@ async function getBucketStatus(ctx, fromEmail, kind) {
   const id = healthBucketId(domain, kind);
   return ctx.collections.health.findOne({ _id: id });
 }
+function emptyBroadcastStats() {
+  return withRates({
+    total: 0,
+    accepted: 0,
+    delivered: 0,
+    bounced: 0,
+    hardBounced: 0,
+    softBounced: 0,
+    complained: 0,
+    unsubscribed: 0,
+    opened: 0,
+    clicked: 0,
+    outcomes: 0
+  });
+}
+var pct = (n, d) => d > 0 ? Math.round(n / d * 1e4) / 100 : 0;
+function withRates(c) {
+  return {
+    ...c,
+    rates: {
+      deliveryRatePct: pct(c.delivered, c.accepted),
+      bounceRatePct: pct(c.bounced, c.outcomes),
+      hardBounceRatePct: pct(c.hardBounced, c.outcomes),
+      complaintRatePct: pct(c.complained, c.outcomes),
+      unsubscribeRatePct: pct(c.unsubscribed, c.outcomes),
+      openRatePct: pct(c.opened, c.delivered),
+      clickRatePct: pct(c.clicked, c.delivered)
+    }
+  };
+}
+var set = (field) => ({ $ifNull: [field, false] });
+var DELIVERED = {
+  $or: [set("$deliveredAt"), { $eq: ["$status", "delivered"] }, set("$complainedAt"), { $eq: ["$status", "complained"] }]
+};
+var BOUNCED = { $or: [{ $eq: ["$status", "bounced"] }, { $in: [{ $ifNull: ["$bounceType", null] }, ["hard", "soft"]] }] };
+var count = (expr) => ({ $sum: { $cond: [expr, 1, 0] } });
+async function aggregateBroadcastStats(collections, broadcastId) {
+  const rows = await collections.sends.aggregate([
+    { $match: broadcastId ? { broadcastId } : { broadcastId: { $ne: null } } },
+    {
+      $group: {
+        _id: "$broadcastId",
+        total: { $sum: 1 },
+        accepted: count(set("$sentAt")),
+        delivered: count(DELIVERED),
+        bounced: count(BOUNCED),
+        hardBounced: count({ $eq: ["$bounceType", "hard"] }),
+        softBounced: count({ $eq: ["$bounceType", "soft"] }),
+        complained: count({ $or: [set("$complainedAt"), { $eq: ["$status", "complained"] }] }),
+        unsubscribed: count(set("$unsubscribedAt")),
+        opened: count(set("$openedAt")),
+        clicked: count(set("$firstClickAt")),
+        outcomes: count({ $or: [DELIVERED, BOUNCED] })
+      }
+    }
+  ]).toArray();
+  const out = /* @__PURE__ */ new Map();
+  for (const { _id, ...c } of rows) {
+    if (_id) out.set(String(_id), withRates(c));
+  }
+  return out;
+}
+async function broadcastStatsFor(collections, broadcastId) {
+  return (await aggregateBroadcastStats(collections, broadcastId)).get(String(broadcastId)) ?? emptyBroadcastStats();
+}
+function effectiveStopRules(config, b) {
+  return { ...config.broadcastStopRules, ...b.stopRules ?? {} };
+}
+var RULE_COUNTS = [
+  ["complaintRatePct", "complained"],
+  ["hardBounceRatePct", "hardBounced"],
+  ["unsubscribeRatePct", "unsubscribed"]
+];
+function evaluateStopRules(stats, rules) {
+  const sample = stats.outcomes;
+  const evaluated = rules.enabled && sample > 0 && sample >= rules.minSample;
+  const breaches = [];
+  if (evaluated) {
+    for (const [rule, key] of RULE_COUNTS) {
+      const n = stats[key];
+      const exactPct = n / sample * 100;
+      if (exactPct > rules[rule]) {
+        breaches.push({ rule, count: n, ratePct: Math.round(exactPct * 100) / 100, thresholdPct: rules[rule] });
+      }
+    }
+  }
+  return { rules, sample, evaluated, breaches };
+}
+var RULE_LABEL = {
+  complaintRatePct: "complaint rate",
+  hardBounceRatePct: "hard bounce rate",
+  unsubscribeRatePct: "unsubscribe rate"
+};
+var PAUSE_PRECEDENCE = {
+  manual: 1,
+  cap_reached: 1,
+  stop_rule: 2,
+  circuit_breaker: 2
+};
+async function pauseBroadcast(ctx, broadcastId, reason, actor = "system:broadcast") {
+  const weaker = Object.keys(PAUSE_PRECEDENCE).filter(
+    (k) => PAUSE_PRECEDENCE[k] < PAUSE_PRECEDENCE[reason.code]
+  );
+  const b = await ctx.collections.broadcasts.findOneAndUpdate(
+    {
+      _id: broadcastId,
+      $or: [{ status: { $in: ["sending", "sent"] } }, { status: "paused", "pauseReason.code": { $in: weaker } }]
+    },
+    { $set: { status: "paused", pausedAt: reason.at, pauseReason: reason, updatedAt: /* @__PURE__ */ new Date() } },
+    { returnDocument: "after" }
+  );
+  if (!b) return { paused: false, heldSends: 0 };
+  const held = await holdQueuedSends(ctx, broadcastId, reason.code);
+  if (ctx.audit) {
+    await ctx.audit({
+      actor,
+      action: "broadcast.pause",
+      resource: { collection: "mailer_broadcasts", id: String(broadcastId), slug: b.slug },
+      diffSummary: `${reason.code}: ${reason.message} \xB7 held ${held} queued send(s)`
+    }).catch(() => {
+    });
+  }
+  if (ctx.config.onBroadcastPaused) {
+    try {
+      await ctx.config.onBroadcastPaused({ broadcastId: String(broadcastId), slug: b.slug, reason, heldSends: held });
+    } catch {
+    }
+  }
+  return { paused: true, heldSends: held };
+}
+async function holdQueuedSends(ctx, broadcastId, code) {
+  const res = await ctx.collections.sends.updateMany(
+    { broadcastId, status: "queued" },
+    { $set: { status: "held", errorMessage: `held: broadcast paused (${code})`, updatedAt: /* @__PURE__ */ new Date() } }
+  );
+  return res.modifiedCount;
+}
+async function evaluateBroadcastStopRules(ctx, broadcastId) {
+  const b = await ctx.collections.broadcasts.findOne({ _id: broadcastId });
+  if (!b || !["sending", "sent", "paused"].includes(b.status)) return null;
+  if (b.status === "paused" && b.pauseReason && PAUSE_PRECEDENCE[b.pauseReason.code] >= 2) return null;
+  const stats = await broadcastStatsFor(ctx.collections, broadcastId);
+  const evaluation = evaluateStopRules(stats, effectiveStopRules(ctx.config, b));
+  if (evaluation.breaches.length === 0) return evaluation;
+  const now = /* @__PURE__ */ new Date();
+  if (b.status === "sent" && await ctx.collections.sends.countDocuments({ broadcastId, status: "queued" }) === 0) {
+    await ctx.collections.broadcasts.updateOne(
+      { _id: broadcastId, stopRuleBreach: { $in: [null] } },
+      { $set: { stopRuleBreach: { at: now, sample: evaluation.sample, breaches: evaluation.breaches } } }
+    );
+    return evaluation;
+  }
+  const first = evaluation.breaches[0];
+  await pauseBroadcast(ctx, broadcastId, {
+    code: "stop_rule",
+    message: `${RULE_LABEL[first.rule]} ${first.ratePct}% is over ${first.thresholdPct}% (${first.count} of ${evaluation.sample} sends with an outcome)`,
+    at: now,
+    details: { breaches: evaluation.breaches, sample: evaluation.sample, rules: evaluation.rules }
+  });
+  return evaluation;
+}
+var STOP_RULE_WINDOW_MS = 14 * 24 * 60 * 60 * 1e3;
+async function evaluateActiveBroadcastStopRules(ctx) {
+  const live = await ctx.collections.broadcasts.find(
+    { status: { $in: ["sending", "sent", "paused"] }, startedAt: { $gte: new Date(Date.now() - STOP_RULE_WINDOW_MS) } },
+    { projection: { _id: 1 } }
+  ).limit(200).toArray();
+  for (const { _id } of live) {
+    await evaluateBroadcastStopRules(ctx, _id).catch((err) => {
+      console.error("mailery: broadcast stop-rule evaluation failed", { id: String(_id), err });
+    });
+  }
+}
 
 // src/server/runner/webhook.ts
 function dimsFromSend(send) {
@@ -15614,6 +15892,11 @@ async function applyWebhookEvent(event, ctx) {
       );
       break;
   }
+  if (send?.broadcastId && (event.type === "bounce" || event.type === "complaint" || event.type === "spam_report" || event.type === "unsubscribe")) {
+    await evaluateBroadcastStopRules(ctx, send.broadcastId).catch((err) => {
+      console.error("mailery: broadcast stop-rule evaluation failed", { id: String(send.broadcastId), err });
+    });
+  }
 }
 async function suppressOnce(ctx, email, reason, scope) {
   const normalized = email.toLowerCase();
@@ -16011,11 +16294,30 @@ async function isSuppressed(collections, email, kind) {
   if (byEmail) return { suppressed: true, scope: byEmail.scope, reason: byEmail.reason };
   const hashed = await collections.suppressions.findOne({
     emailHash: sha256Hex(normalized),
-    scope: { $in: allowed }
+    scope: { $in: allowed },
+    $or: [{ expiresAt: null }, { expiresAt: { $gt: /* @__PURE__ */ new Date() } }]
   });
   if (hashed) return { suppressed: true, scope: hashed.scope, reason: hashed.reason };
   return { suppressed: false };
 }
+async function suppressedEmails(collections, emails, kind) {
+  const normalized = [...new Set(emails.map((e) => e.toLowerCase()))];
+  if (normalized.length === 0) return /* @__PURE__ */ new Set();
+  const allowed = SCOPES_BY_KIND[kind];
+  const live = { $or: [{ expiresAt: null }, { expiresAt: { $gt: /* @__PURE__ */ new Date() } }] };
+  const byHash = new Map(normalized.map((e) => [sha256Hex(e), e]));
+  const [plain, hashed] = await Promise.all([
+    collections.suppressions.distinct("email", { email: { $in: normalized }, scope: { $in: allowed }, ...live }),
+    collections.suppressions.distinct("emailHash", { emailHash: { $in: [...byHash.keys()] }, scope: { $in: allowed }, ...live })
+  ]);
+  const out = /* @__PURE__ */ new Set();
+  for (const e of plain) if (typeof e === "string") out.add(e);
+  for (const h of hashed) {
+    const e = byHash.get(String(h));
+    if (e) out.add(e);
+  }
+  return out;
+}
 
 // src/server/runner/send.ts
 async function handleSend(run, step2, contact, flow, ctx) {
@@ -16092,6 +16394,27 @@ async function dispatchSend(sendId, ctx) {
     await markFailed(send._id, "template_missing", ctx);
     return;
   }
+  if (send.broadcastId) {
+    const broadcast = await ctx.collections.broadcasts.findOne(
+      { _id: send.broadcastId },
+      { projection: { status: 1, pauseReason: 1 } }
+    );
+    const holding = broadcast?.status === "paused" && broadcast.pauseReason?.code !== "cap_reached";
+    if (holding || broadcast?.status === "cancelled") {
+      const held = holding;
+      await ctx.collections.sends.updateOne(
+        { _id: send._id },
+        {
+          $set: {
+            status: held ? "held" : "cancelled",
+            errorMessage: held ? `held: broadcast paused (${broadcast.pauseReason?.code ?? "unknown"})` : "cancelled: broadcast cancelled",
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        }
+      );
+      return;
+    }
+  }
   const supp = await isSuppressed(ctx.collections, send.emailAtSend, send.kind);
   if (supp.suppressed) {
     await ctx.collections.sends.updateOne(
@@ -16102,6 +16425,19 @@ async function dispatchSend(sendId, ctx) {
   }
   if (send.kind === "marketing") {
     const bucket = await getBucketStatus(ctx, send.fromEmail, send.kind);
+    if (bucket?.status === "tripped" && send.broadcastId) {
+      await ctx.collections.sends.updateOne(
+        { _id: send._id },
+        { $set: { status: "held", errorMessage: "held: circuit breaker tripped", updatedAt: /* @__PURE__ */ new Date() } }
+      );
+      await pauseBroadcast(ctx, send.broadcastId, {
+        code: "circuit_breaker",
+        message: `the ${bucket.senderDomain ?? "sender"} ${send.kind} circuit breaker is tripped: ${bucket.trippedReason ?? "no reason recorded"}`,
+        at: /* @__PURE__ */ new Date(),
+        details: { bucket: bucket._id }
+      });
+      return;
+    }
     if (bucket?.status === "tripped") {
       await ctx.collections.sends.updateOne(
         { _id: send._id },
@@ -16116,6 +16452,10 @@ async function dispatchSend(sendId, ctx) {
     await markFailed(send._id, "contact_missing", ctx);
     return;
   }
+  if (!send.emailAtSend?.trim() || !contact.email?.trim()) {
+    await markFailed(send._id, "no_recipient: the contact has no email address", ctx);
+    return;
+  }
   const run = send.flowRunId ? await ctx.collections.flowRuns.findOne({ _id: send.flowRunId }) : null;
   if (run && run.status === "exited" && run.exitReason?.startsWith("aborted_by_host")) {
     await ctx.collections.sends.updateOne(
@@ -16134,7 +16474,7 @@ async function dispatchSend(sendId, ctx) {
       eventName: run?.triggerEvent?.name,
       eventProperties: run?.triggerEvent?.properties
     });
-    renderCtx = buildRenderContext(contact, run, send.vars ?? {}, ctx, resolved);
+    renderCtx = buildRenderContext(contact, run, send.vars ?? {}, ctx, resolved, String(send._id));
     rendered = await renderTemplate(template, renderCtx, { helpers: ctx.handlebarsHelpers });
   } catch (err) {
     await markFailed(send._id, `render error: ${String(err?.message ?? err)}`, ctx);
@@ -16225,11 +16565,11 @@ function pickProviderName(stepOverride, tpl, ctx) {
   }
   return ctx.config.defaultProvider;
 }
-function buildRenderContext(contact, run, vars, ctx, resolved = {}) {
+function buildRenderContext(contact, run, vars, ctx, resolved = {}, sendId) {
   const scope = "marketing";
   const expiresAt = new Date(Date.now() + ctx.config.unsubscribeTokenLifetimeDays * 24 * 60 * 60 * 1e3);
   const token = signUnsubscribeToken(
-    { email: contact.email, scope, expiresAt },
+    { email: contact.email, scope, expiresAt, ...sendId ? { sendId } : {} },
     ctx.config.unsubscribeSecret
   );
   const unsubscribeUrl = `${ctx.config.publicUrl}/m/unsub/${token}`;
@@ -16312,6 +16652,10 @@ async function processOneRunStep(runId, ctx) {
     await exitFlowRun(run, "contact_missing", ctx);
     return;
   }
+  if (!contact.email?.trim()) {
+    await exitFlowRun(run, "contact_no_email", ctx);
+    return;
+  }
   const sub = await ctx.collections.subscriptions.findOne({ externalId: run.externalId });
   if (sub && sub.status !== "subscribed") {
     await exitFlowRun(run, sub.status, ctx);
@@ -16605,6 +16949,184 @@ async function sweepStrandedFlowRuns(ctx) {
     }
   }
 }
+
+// src/server/runner/segment.ts
+function planSegment(seg) {
+  const hostFilter = {};
+  const postFilters = [];
+  const hostFields = /* @__PURE__ */ new Set();
+  const takeField = (field) => {
+    if (hostFields.has(field)) return false;
+    hostFields.add(field);
+    return true;
+  };
+  for (const f of seg.filters ?? []) {
+    switch (f.kind) {
+      case "hasTag":
+        if (hostFilter.hasTag === void 0) {
+          hostFilter.hasTag = f.tag;
+          continue;
+        }
+        break;
+      case "fieldEquals":
+        if (!hostFilter.fieldEquals && takeField(f.field)) {
+          hostFilter.fieldEquals = { field: f.field, value: f.value };
+          continue;
+        }
+        break;
+      case "fieldIn":
+        if (!hostFilter.fieldIn && takeField(f.field)) {
+          hostFilter.fieldIn = { field: f.field, values: f.values };
+          continue;
+        }
+        break;
+      case "fieldExists":
+        if (!hostFilter.fieldExists && takeField(f.field)) {
+          hostFilter.fieldExists = f.field;
+          continue;
+        }
+        break;
+    }
+    postFilters.push(f);
+  }
+  return { hostFilter, postFilters };
+}
+async function applyPostFilters(contacts, filters, ctx, now = /* @__PURE__ */ new Date()) {
+  if (filters.length === 0 || contacts.length === 0) return contacts;
+  const externalIds = contacts.map((c) => c.externalId);
+  const leaves = /* @__PURE__ */ new Map();
+  collectLookups(filters, leaves);
+  const cache = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...leaves].map(async ([key, f]) => {
+      cache.set(key, await lookup(f, externalIds, ctx, now));
+    })
+  );
+  return contacts.filter((c) => filters.every((f) => matches(c, f, cache)));
+}
+function lookupKey(f) {
+  switch (f.kind) {
+    case "subscriptionStatus":
+      return `sub:${f.equals}`;
+    case "firedEvent":
+    case "notFiredEvent":
+      return `evt:${f.withinDays ?? ""}:${f.eventName}`;
+    case "opened":
+    case "notOpened":
+      return `open:${f.withinDays ?? ""}:${f.templateSlug ?? ""}`;
+    case "subscribedAfter":
+      return `subAfter:${toDate(f.date).getTime()}`;
+    case "subscribedBefore":
+      return `subBefore:${toDate(f.date).getTime()}`;
+    default:
+      return null;
+  }
+}
+function collectLookups(filters, out) {
+  for (const f of filters) {
+    if (f.kind === "any") collectLookups(f.filters, out);
+    else if (f.kind === "not") collectLookups([f.filter], out);
+    else {
+      const key = lookupKey(f);
+      if (key && !out.has(key)) out.set(key, f);
+    }
+  }
+}
+async function lookup(f, externalIds, ctx, now) {
+  const c = ctx.collections;
+  const inPage = { $in: externalIds };
+  const since = (days) => days ? new Date(now.getTime() - days * 864e5) : null;
+  let ids;
+  switch (f.kind) {
+    case "subscriptionStatus":
+      ids = await c.subscriptions.distinct("externalId", { externalId: inPage, status: f.equals });
+      break;
+    case "firedEvent":
+    case "notFiredEvent": {
+      const cutoff = since(f.withinDays);
+      ids = await c.events.distinct("externalId", {
+        externalId: inPage,
+        name: f.eventName,
+        ...cutoff ? { occurredAt: { $gt: cutoff } } : {}
+      });
+      break;
+    }
+    case "opened":
+    case "notOpened": {
+      const cutoff = since(f.withinDays);
+      ids = await c.sends.distinct("externalId", {
+        externalId: inPage,
+        openedAt: cutoff ? { $gt: cutoff } : { $ne: null },
+        ...f.templateSlug ? { templateSlug: f.templateSlug } : {}
+      });
+      break;
+    }
+    case "subscribedAfter":
+      ids = await c.subscriptions.distinct("externalId", { externalId: inPage, subscribedAt: { $gt: toDate(f.date) } });
+      break;
+    case "subscribedBefore":
+      ids = await c.subscriptions.distinct("externalId", { externalId: inPage, subscribedAt: { $lt: toDate(f.date) } });
+      break;
+    default:
+      ids = [];
+  }
+  return new Set(ids.map(String));
+}
+function matches(c, f, cache) {
+  switch (f.kind) {
+    case "subscriptionStatus":
+    case "firedEvent":
+    case "opened":
+    case "subscribedAfter":
+    case "subscribedBefore":
+      return cache.get(lookupKey(f))?.has(c.externalId) ?? false;
+    case "notFiredEvent":
+    case "notOpened":
+      return !(cache.get(lookupKey(f))?.has(c.externalId) ?? false);
+    case "hasTag":
+      return c.tags.includes(f.tag);
+    case "notHasTag":
+      return !c.tags.includes(f.tag);
+    case "fieldEquals":
+      return valuesEqual(fieldValue(c, f.field), f.value);
+    case "fieldIn": {
+      const v = fieldValue(c, f.field);
+      return f.values.some((x) => valuesEqual(v, x));
+    }
+    case "fieldExists":
+      return fieldValue(c, f.field) !== void 0;
+    case "any":
+      return f.filters.some((sub) => matches(c, sub, cache));
+    case "not":
+      return !matches(c, f.filter, cache);
+    default:
+      throw new Error(`mailery: unknown segment filter kind "${f.kind}"`);
+  }
+}
+function fieldValue(c, path2) {
+  let cur = c.fields;
+  for (const part of path2.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function valuesEqual(a, b) {
+  if (a instanceof Date || b instanceof Date) {
+    const ta = a instanceof Date ? a.getTime() : new Date(a).getTime();
+    const tb = b instanceof Date ? b.getTime() : new Date(b).getTime();
+    return !Number.isNaN(ta) && ta === tb;
+  }
+  if (a && typeof a === "object" && typeof a.toHexString === "function") {
+    return String(a) === String(b);
+  }
+  return a === b;
+}
+function toDate(d) {
+  return d instanceof Date ? d : new Date(d);
+}
+
+// src/server/runner/broadcasts.ts
 var STALLED_BROADCAST_THRESHOLD_MS = 10 * 60 * 1e3;
 async function processScheduledBroadcasts(ctx) {
   const now = /* @__PURE__ */ new Date();
@@ -16612,7 +17134,7 @@ async function processScheduledBroadcasts(ctx) {
   for (const b of due) {
     const claimed = await ctx.collections.broadcasts.findOneAndUpdate(
       { _id: b._id, status: "scheduled" },
-      { $set: { status: "sending", startedAt: now, updatedAt: now } },
+      { $set: { status: "sending", startedAt: now, updatedAt: now, dispatchLeaseId: null } },
       { returnDocument: "after" }
     );
     if (!claimed) continue;
@@ -16620,8 +17142,14 @@ async function processScheduledBroadcasts(ctx) {
   }
 }
 async function startBroadcastDispatch(broadcast, ctx) {
+  const bumped = await ctx.collections.broadcasts.findOneAndUpdate(
+    { _id: broadcast._id },
+    { $inc: { dispatchGeneration: 1 } },
+    { returnDocument: "after" }
+  );
+  const current = bumped ?? broadcast;
   if (ctx.config.queue.driver === "noop") {
-    await runBroadcastDispatch(broadcast, ctx);
+    await runBroadcastDispatch(current, ctx);
     return;
   }
   await ctx.queues.advance.add(
@@ -16630,7 +17158,7 @@ async function startBroadcastDispatch(broadcast, ctx) {
     {
       attempts: 3,
       backoff: { type: "exponential", delay: 6e4 },
-      jobId: `broadcast-dispatch:${broadcast._id}`
+      jobId: `broadcast-dispatch:${broadcast._id}:${current.dispatchGeneration ?? 0}`
     }
   );
 }
@@ -16643,10 +17171,11 @@ async function resumeStalledBroadcasts(ctx) {
   const cutoff = new Date(Date.now() - STALLED_BROADCAST_THRESHOLD_MS);
   const stalled = await ctx.collections.broadcasts.find({ status: "sending", updatedAt: { $lt: cutoff } }).toArray();
   for (const b of stalled) {
-    await ctx.collections.broadcasts.updateOne(
-      { _id: b._id },
-      { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+    const reset = await ctx.collections.broadcasts.updateOne(
+      { _id: b._id, status: "sending", updatedAt: { $lt: cutoff } },
+      { $set: { dispatchLeaseId: null, updatedAt: /* @__PURE__ */ new Date() } }
     );
+    if (reset.modifiedCount === 0) continue;
     await startBroadcastDispatch(b, ctx);
   }
 }
@@ -16656,50 +17185,117 @@ async function runBroadcastDispatch(broadcast, ctx) {
   } catch (err) {
     console.error("mailery: broadcast dispatch failed", { id: String(broadcast._id), err });
     await ctx.collections.broadcasts.updateOne(
-      { _id: broadcast._id },
-      { $set: { status: "failed", updatedAt: /* @__PURE__ */ new Date() } }
+      { _id: broadcast._id, status: "sending" },
+      {
+        $set: {
+          status: "failed",
+          failureReason: `dispatch error: ${String(err?.message ?? err)}`,
+          updatedAt: /* @__PURE__ */ new Date(),
+          dispatchLeaseId: null
+        }
+      }
     );
   }
 }
+function broadcastDedupeKey(broadcastId, externalId) {
+  return `broadcast:${broadcastId}:${externalId}`;
+}
+var SENDABLE_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isSendableEmail(email) {
+  return typeof email === "string" && SENDABLE_EMAIL_RE.test(email);
+}
+async function* eligibleRecipientPages(broadcast, kind, ctx) {
+  const { hostFilter, postFilters } = planSegment(broadcast.segmentDefinition);
+  const sort = broadcast.order ?? void 0;
+  if (sort && !ctx.adapter.supportsSort) {
+    throw new Error("mailery: this broadcast has an order but the contact adapter does not support sorted queries");
+  }
+  let cursor;
+  for (; ; ) {
+    const page = await ctx.adapter.query(hostFilter, {
+      limit: ctx.config.broadcastEnqueueBatchSize,
+      cursor,
+      ...sort ? { sort: { field: sort.field, direction: sort.direction } } : {}
+    });
+    if (page.contacts.length === 0) break;
+    const passed = (await applyPostFilters(page.contacts, postFilters, ctx)).filter((c) => isSendableEmail(c.email));
+    const suppressed = await suppressedEmails(ctx.collections, passed.map((c) => c.email), kind);
+    yield passed.filter((c) => !suppressed.has(c.email.toLowerCase()));
+    if (!page.nextCursor) break;
+    cursor = page.nextCursor;
+  }
+}
+async function alreadyDispatched(ctx, broadcastId, contacts) {
+  if (contacts.length === 0) return /* @__PURE__ */ new Set();
+  const keys = contacts.map((c) => broadcastDedupeKey(broadcastId, c.externalId));
+  const found = await ctx.collections.sends.distinct("dedupeKey", { dedupeKey: { $in: keys } });
+  return new Set(found.map(String));
+}
 async function dispatchBroadcast(broadcast, ctx) {
   const template = await ctx.collections.templates.findOne({ slug: broadcast.templateSlug });
-  if (!template) {
+  const failure = !template ? `template "${broadcast.templateSlug}" not found` : template.kind !== "marketing" ? `template "${broadcast.templateSlug}" is ${template.kind}, not marketing` : null;
+  if (failure || !template) {
     await ctx.collections.broadcasts.updateOne(
-      { _id: broadcast._id },
-      { $set: { status: "failed", updatedAt: /* @__PURE__ */ new Date() } }
+      { _id: broadcast._id, status: "sending" },
+      { $set: { status: "failed", failureReason: failure, updatedAt: /* @__PURE__ */ new Date(), dispatchLeaseId: null } }
     );
     return;
   }
-  const hostFilter = toAdapterFilter(broadcast.segmentDefinition);
-  const postFilters = broadcast.segmentDefinition.filters.filter((f) => isMailerSide(f));
-  let cursor = void 0;
-  let total = 0;
-  const batchSize = ctx.config.broadcastEnqueueBatchSize;
+  const leaseId = new mongodb.ObjectId().toHexString();
+  const staleCutoff = new Date(Date.now() - STALLED_BROADCAST_THRESHOLD_MS);
+  const b = await ctx.collections.broadcasts.findOneAndUpdate(
+    {
+      _id: broadcast._id,
+      status: "sending",
+      $or: [{ dispatchLeaseId: null }, { dispatchLeaseId: { $exists: false } }, { updatedAt: { $lt: staleCutoff } }]
+    },
+    { $set: { dispatchLeaseId: leaseId, updatedAt: /* @__PURE__ */ new Date() } },
+    { returnDocument: "after" }
+  );
+  if (!b) return;
+  const holdsLease = async () => (await ctx.collections.broadcasts.updateOne(
+    { _id: b._id, status: "sending", dispatchLeaseId: leaseId },
+    { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+  )).matchedCount === 1;
   const maxWaiting = ctx.config.broadcastEnqueueMaxWaiting;
-  const respectTimezone = broadcast.respectRecipientTimezone === true;
-  const scheduledMs = broadcast.scheduledAt?.getTime() ?? Date.now();
-  for (; ; ) {
-    await ctx.collections.broadcasts.updateOne(
-      { _id: broadcast._id },
-      { $set: { updatedAt: /* @__PURE__ */ new Date() } }
-    );
-    const page = await ctx.adapter.query(hostFilter, { limit: batchSize, cursor });
-    if (page.contacts.length === 0) break;
-    const eligible = await applyPostFilters(page.contacts, postFilters, ctx);
-    if (eligible.length > 0) {
+  const respectTimezone = b.respectRecipientTimezone === true;
+  const scheduledMs = b.scheduledAt?.getTime() ?? Date.now();
+  const cap = typeof b.recipientCap === "number" ? b.recipientCap : null;
+  let capReached = false;
+  try {
+    for await (const eligible of eligibleRecipientPages(b, template.kind, ctx)) {
+      if (!await holdsLease()) return;
+      const bucket = await getBucketStatus(ctx, template.fromEmail, template.kind);
+      if (bucket?.status === "tripped") {
+        await pauseBroadcast(ctx, b._id, {
+          code: "circuit_breaker",
+          message: `the ${bucket.senderDomain ?? "sender"} ${template.kind} circuit breaker is tripped: ${bucket.trippedReason ?? "no reason recorded"}`,
+          at: /* @__PURE__ */ new Date(),
+          details: { bucket: bucket._id }
+        });
+        return;
+      }
+      const seen = await alreadyDispatched(ctx, b._id, eligible);
+      let fresh = eligible.filter((c) => !seen.has(broadcastDedupeKey(b._id, c.externalId)));
+      if (fresh.length === 0) continue;
+      if (cap !== null) {
+        const room = cap - await ctx.collections.sends.countDocuments({ broadcastId: b._id });
+        if (room <= 0) {
+          capReached = true;
+          break;
+        }
+        if (fresh.length > room) {
+          fresh = fresh.slice(0, room);
+          capReached = true;
+        }
+      }
       while (await ctx.queues.send.getWaitingCount() > maxWaiting) {
-        await ctx.collections.broadcasts.updateOne(
-          { _id: broadcast._id },
-          { $set: { updatedAt: /* @__PURE__ */ new Date() } }
-        );
+        if (!await holdsLease()) return;
         await sleep(2e3);
       }
-      const sendDocs = await Promise.all(
-        eligible.map(async (contact) => buildSendDoc(broadcast, template, contact, ctx, scheduledMs, respectTimezone))
-      );
       const inserted = [];
-      for (const { doc, delayMs } of sendDocs) {
-        if (!doc) continue;
+      for (const contact of fresh) {
+        const { doc, delayMs } = buildSendDoc(b, template, contact, ctx, scheduledMs, respectTimezone);
         try {
           await ctx.collections.sends.insertOne(doc);
           inserted.push({ sendId: doc._id, delayMs });
@@ -16707,115 +17303,51 @@ async function dispatchBroadcast(broadcast, ctx) {
           if (err?.code !== 11e3) throw err;
         }
       }
-      if (inserted.length > 0) {
-        await Promise.all(
-          inserted.map(
-            ({ sendId, delayMs }) => ctx.queues.send.add(
-              "send",
-              { sendId: String(sendId) },
-              {
-                attempts: ctx.config.sendRetryAttempts,
-                backoff: { type: "exponential", delay: 6e4 },
-                ...delayMs > 0 ? { delay: delayMs } : {}
-              }
-            )
+      await Promise.all(
+        inserted.map(
+          ({ sendId, delayMs }) => ctx.queues.send.add(
+            "send",
+            { sendId: String(sendId) },
+            {
+              attempts: ctx.config.sendRetryAttempts,
+              backoff: { type: "exponential", delay: 6e4 },
+              ...delayMs > 0 ? { delay: delayMs } : {}
+            }
           )
-        );
-      }
-      total += inserted.length;
-    }
-    if (!page.nextCursor) break;
-    cursor = page.nextCursor;
-  }
-  await ctx.collections.broadcasts.updateOne(
-    { _id: broadcast._id },
-    {
-      $set: {
-        status: "sent",
-        completedAt: /* @__PURE__ */ new Date(),
-        recipientCount: total,
-        updatedAt: /* @__PURE__ */ new Date()
-      }
-    }
-  );
-}
-function toAdapterFilter(seg) {
-  const out = {};
-  for (const f of seg.filters) {
-    switch (f.kind) {
-      case "hasTag":
-        out.hasTag = f.tag;
-        break;
-      case "fieldEquals":
-        out.fieldEquals = { field: f.field, value: f.value };
-        break;
-      case "fieldIn":
-        out.fieldIn = { field: f.field, values: f.values };
-        break;
-      case "fieldExists":
-        out.fieldExists = f.field;
-        break;
-    }
-  }
-  return out;
-}
-function isMailerSide(f) {
-  return f.kind === "subscriptionStatus" || f.kind === "firedEvent" || f.kind === "notFiredEvent" || f.kind === "subscribedAfter" || f.kind === "subscribedBefore" || f.kind === "opened" || f.kind === "notOpened" || f.kind === "notHasTag" || f.kind === "any" || f.kind === "not";
-}
-async function applyPostFilters(contacts, filters, ctx) {
-  if (filters.length === 0) return contacts;
-  const externalIds = contacts.map((c) => c.externalId);
-  const cache = {};
-  for (const f of filters) {
-    if (f.kind === "subscriptionStatus") {
-      const docs = await ctx.collections.subscriptions.find({ externalId: { $in: externalIds }, status: f.equals }).project({ externalId: 1 }).toArray();
-      cache[`sub:${f.equals}`] = new Set(docs.map((d) => d.externalId));
-    }
-    if (f.kind === "firedEvent" || f.kind === "notFiredEvent") {
-      const query = { externalId: { $in: externalIds }, name: f.eventName };
-      if (f.withinDays) {
-        query.occurredAt = { $gt: new Date(Date.now() - f.withinDays * 864e5) };
-      }
-      const docs = await ctx.collections.events.find(query).project({ externalId: 1 }).toArray();
-      cache[`evt:${f.eventName}`] = new Set(docs.map((d) => d.externalId));
+        )
+      );
+      if (capReached) break;
     }
-  }
-  return contacts.filter((c) => filters.every((f) => filterMatches(c, f, cache)));
-}
-function filterMatches(c, f, cache) {
-  switch (f.kind) {
-    case "subscriptionStatus":
-      return cache[`sub:${f.equals}`]?.has(c.externalId) ?? false;
-    case "firedEvent":
-      return cache[`evt:${f.eventName}`]?.has(c.externalId) ?? false;
-    case "notFiredEvent":
-      return !cache[`evt:${f.eventName}`]?.has(c.externalId);
-    case "notHasTag":
-      return !c.tags.includes(f.tag);
-    case "opened":
-    case "notOpened":
-      return true;
-    case "subscribedAfter":
-    case "subscribedBefore":
-      return true;
-    // V2
-    case "any":
-      return f.filters.some((sub) => filterMatches(c, sub, cache));
-    case "not":
-      return !filterMatches(c, f.filter, cache);
-    default:
-      return true;
+    const now = /* @__PURE__ */ new Date();
+    const total = await ctx.collections.sends.countDocuments({ broadcastId: b._id });
+    const set2 = capReached ? {
+      status: "paused",
+      pausedAt: now,
+      pauseReason: {
+        code: "cap_reached",
+        message: `${total} send(s) reached recipientCap ${cap}; eligible recipients remain \u2014 raise recipientCap and resume to send the next wave`,
+        at: now,
+        details: { recipientCap: cap, sendsSoFar: total }
+      }
+    } : { status: "sent", completedAt: now };
+    await ctx.collections.broadcasts.updateOne(
+      { _id: b._id, status: "sending", dispatchLeaseId: leaseId },
+      { $set: { ...set2, recipientCount: total, updatedAt: now, dispatchLeaseId: null } }
+    );
+  } finally {
+    await ctx.collections.broadcasts.updateOne(
+      { _id: b._id, dispatchLeaseId: leaseId },
+      { $set: { dispatchLeaseId: null } }
+    );
   }
 }
-async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, respectTimezone) {
-  const supp = await isSuppressed(ctx.collections, contact.email, template.kind);
-  if (supp.suppressed) return { doc: null, delayMs: 0 };
+function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, respectTimezone) {
   const sendId = new mongodb.ObjectId();
-  const dedupeKey = `broadcast:${broadcast._id}:${contact.externalId}`;
-  let delayMs = Math.max(0, scheduledMs - Date.now());
+  const dedupeKey = broadcastDedupeKey(broadcast._id, contact.externalId);
+  const now = Date.now();
+  let delayMs = Math.max(0, scheduledMs - now);
   if (respectTimezone && contact.timezone) {
-    const offsetMs = perRecipientOffsetMs(scheduledMs, contact.timezone);
-    delayMs = Math.max(0, scheduledMs + offsetMs - Date.now());
+    delayMs = Math.max(0, recipientSlotMs(scheduledMs, contact.timezone, now) - now);
   }
   const doc = {
     _id: sendId,
@@ -16850,16 +17382,29 @@ async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, resp
     queuedAt: /* @__PURE__ */ new Date(),
     updatedAt: /* @__PURE__ */ new Date(),
     sentAt: null,
-    deliveredAt: null
+    deliveredAt: null,
+    notBefore: new Date(Date.now() + delayMs)
   };
   return { doc, delayMs };
 }
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var TZ_SLOT_GRACE_MS = 15 * 60 * 1e3;
+function recipientSlotMs(scheduledMs, timezone, nowMs) {
+  let anchor = scheduledMs;
+  let target = anchor + perRecipientOffsetMs(anchor, timezone);
+  const earliest = nowMs - TZ_SLOT_GRACE_MS;
+  if (target < earliest) {
+    anchor += Math.ceil((earliest - target) / DAY_MS) * DAY_MS;
+    target = anchor + perRecipientOffsetMs(anchor, timezone);
+    if (target < earliest) target += DAY_MS;
+  }
+  return target;
+}
 function perRecipientOffsetMs(scheduledMs, timezone) {
-  const DAY_MS = 24 * 60 * 60 * 1e3;
   try {
     const scheduled = new Date(scheduledMs);
-    const utc = scheduled.toLocaleString("en-US", { timeZone: "UTC", hour12: false });
-    const local = scheduled.toLocaleString("en-US", { timeZone: timezone, hour12: false });
+    const utc = scheduled.toLocaleString("en-US", { timeZone: "UTC", hourCycle: "h23" });
+    const local = scheduled.toLocaleString("en-US", { timeZone: timezone, hourCycle: "h23" });
     const parse = (s) => {
       const m = s.match(/(\d+)\/(\d+)\/(\d+),\s*(\d+):(\d+):(\d+)/);
       if (!m) return 0;
@@ -16979,10 +17524,10 @@ async function runDnsblChecks(ctx, opts = {}) {
   }
   let listedCount = 0;
   async function processPair(p) {
-    const queryName = buildQueryName(p.target, p.targetKind, p.list.host);
-    const lookup = queryName ? await queryDnsbl(resolver, queryName) : { result: "error", returnCodes: [], errorMessage: "unsupported target format" };
-    if (lookup.transient) return;
-    if (lookup.result === "listed") listedCount++;
+    const queryName = buildQueryName(p.target, p.targetKind, spamhausQueryHost(p.list.host, cfg.spamhausDqsKey));
+    const lookup2 = queryName ? await queryDnsbl(resolver, queryName) : { result: "error", returnCodes: [], errorMessage: "unsupported target format" };
+    if (lookup2.transient) return;
+    if (lookup2.result === "listed") listedCount++;
     await ctx.collections.dnsblChecks.updateOne(
       { target: p.target, list: p.list.host },
       {
@@ -16991,9 +17536,9 @@ async function runDnsblChecks(ctx, opts = {}) {
           targetKind: p.targetKind,
           list: p.list.host,
           listLabel: p.list.label,
-          result: lookup.result,
-          returnCodes: lookup.returnCodes,
-          errorMessage: lookup.errorMessage,
+          result: lookup2.result,
+          returnCodes: lookup2.returnCodes,
+          errorMessage: lookup2.errorMessage,
           runAt: /* @__PURE__ */ new Date()
         }
       },
@@ -17026,6 +17571,10 @@ function collectTargets(ctx, cfg) {
     ips: (cfg.dedicatedIps ?? []).filter((ip) => net__default.default.isIP(ip) !== 0)
   };
 }
+function spamhausQueryHost(listHost, dqsKey) {
+  const zone = dqsKey ? /^([a-z0-9-]+)\.spamhaus\.org$/i.exec(listHost)?.[1] : void 0;
+  return zone ? `${dqsKey}.${zone}.dq.spamhaus.net` : listHost;
+}
 function buildQueryName(target, kind, listHost) {
   if (kind === "ip") {
     const v = net__default.default.isIP(target);
@@ -17061,16 +17610,22 @@ async function queryDnsbl(resolver, query) {
     };
   }
 }
+var REFUSAL_REASONS = {
+  "127.255.255.252": "malformed query name for this list",
+  "127.255.255.254": "queried through a public or shared DNS resolver, which Spamhaus blocks. Set dnsbl.spamhausDqsKey (free Spamhaus DQS key) or use a private resolver",
+  "127.255.255.255": "this resolver has exceeded the free query limit"
+};
 function interpretRecords(records) {
   if (!records || records.length === 0) {
     return { result: "clean", returnCodes: [], errorMessage: null };
   }
   const errorish = records.filter((r) => r.startsWith("127.255.255."));
   if (errorish.length === records.length) {
+    const reasons = [...new Set(records.map((r) => REFUSAL_REASONS[r] ?? "unrecognised refusal code"))];
     return {
       result: "error",
       returnCodes: records,
-      errorMessage: `list returned reserved code(s): ${records.join(", ")}`
+      errorMessage: `not a listing \u2014 the list refused the query (${records.join(", ")}): ${reasons.join("; ")}`
     };
   }
   const listed = records.filter((r) => r.startsWith("127.") && !r.startsWith("127.255.255."));
@@ -17834,6 +18389,9 @@ async function runTick(ctx) {
   await resumeStalledBroadcasts(ctx).catch((err) => {
     console.error("mailery: stalled-broadcast resume failed", err);
   });
+  await evaluateActiveBroadcastStopRules(ctx).catch((err) => {
+    console.error("mailery: broadcast stop-rule sweep failed", err);
+  });
   await evaluateHealth(ctx).catch((err) => {
     console.error("mailery: health evaluation failed", err);
   });
@@ -18538,6 +19096,25 @@ var Mailer = class _Mailer {
 };
 
 // src/testing/memory-adapter.ts
+function fieldPath(c, path2) {
+  let cur = c.fields;
+  for (const part of path2.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function compareValues(a, b) {
+  const an = a === null || a === void 0;
+  const bn = b === null || b === void 0;
+  if (an || bn) return an && bn ? 0 : an ? -1 : 1;
+  const av = a instanceof Date ? a.getTime() : a;
+  const bv = b instanceof Date ? b.getTime() : b;
+  if (typeof av === "number" && typeof bv === "number") return av - bv;
+  const as = String(av);
+  const bs = String(bv);
+  return as < bs ? -1 : as > bs ? 1 : 0;
+}
 var MemoryContactAdapter = class {
   byId = /* @__PURE__ */ new Map();
   constructor(initial = []) {
@@ -18572,8 +19149,29 @@ var MemoryContactAdapter = class {
     }
     return out;
   }
+  /** `query` honours `opts.sort` over `contact.fields` (dotted paths), like MongoContactAdapter over documents. */
+  supportsSort = true;
   async query(filter, opts) {
-    const all = Array.from(this.byId.values()).filter((c) => matches(c, filter)).sort((a, b) => a.externalId < b.externalId ? -1 : 1);
+    if (opts.sort) {
+      const { field, direction } = opts.sort;
+      const dir = direction === "desc" ? -1 : 1;
+      const sorted = Array.from(this.byId.values()).filter((c) => matches2(c, filter)).sort((a, b) => {
+        const byValue = compareValues(fieldPath(a, field), fieldPath(b, field)) * dir;
+        if (byValue !== 0) return byValue;
+        return a.externalId < b.externalId ? -1 : a.externalId > b.externalId ? 1 : 0;
+      });
+      let start = 0;
+      if (opts.cursor) {
+        const at = sorted.findIndex((c) => c.externalId === opts.cursor);
+        start = at === -1 ? sorted.length : at + 1;
+      }
+      const page = sorted.slice(start, start + opts.limit);
+      return {
+        contacts: page,
+        nextCursor: start + opts.limit < sorted.length ? page[page.length - 1]?.externalId : void 0
+      };
+    }
+    const all = Array.from(this.byId.values()).filter((c) => matches2(c, filter)).sort((a, b) => a.externalId < b.externalId ? -1 : 1);
     const startIndex = opts.cursor ? all.findIndex((c) => c.externalId > opts.cursor) : 0;
     const slice = all.slice(startIndex === -1 ? all.length : startIndex, (startIndex === -1 ? all.length : startIndex) + opts.limit);
     const hasMore = startIndex !== -1 && startIndex + opts.limit < all.length;
@@ -18584,15 +19182,15 @@ var MemoryContactAdapter = class {
   }
   async count(filter) {
     let n = 0;
-    for (const c of this.byId.values()) if (matches(c, filter)) n++;
+    for (const c of this.byId.values()) if (matches2(c, filter)) n++;
     return n;
   }
   async addTags(externalId, tags) {
     const c = this.byId.get(externalId);
     if (!c) return;
-    const set = new Set(c.tags);
-    for (const t of tags) set.add(t);
-    c.tags = Array.from(set);
+    const set2 = new Set(c.tags);
+    for (const t of tags) set2.add(t);
+    c.tags = Array.from(set2);
   }
   async removeTags(externalId, tags) {
     const c = this.byId.get(externalId);
@@ -18601,7 +19199,7 @@ var MemoryContactAdapter = class {
     c.tags = c.tags.filter((t) => !remove.has(t));
   }
 };
-function matches(c, f) {
+function matches2(c, f) {
   if (f.emailIn && !f.emailIn.map((e) => e.toLowerCase()).includes(c.email)) return false;
   if (f.externalIdIn && !f.externalIdIn.includes(c.externalId)) return false;
   if (f.fieldEquals && c.fields[f.fieldEquals.field] !== f.fieldEquals.value) return false;