mailery 0.17.1 → 0.19.0

package/dist/index.cjs

@@ -106,6 +106,42 @@ __export(mongo_exports, {
 function canBeObjectId(s) {
   return typeof s === "string" && /^[a-f0-9]{24}$/i.test(s);
 }
+function getPath(doc, path3) {
+  let cur = doc;
+  for (const part of path3.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;
+  }
+}
 exports.MongoContactAdapter = void 0;
 var init_mongo = __esm({
   "src/server/adapters/mongo.ts"() {
@@ -155,7 +191,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) {
@@ -174,6 +213,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;
       // -------------------------------------------------------------------------
@@ -523,6 +608,35 @@ var sendOneOffInputSchema = zod.z.object({
   providerOverride: zod.z.string().optional(),
   dedupeKey: zod.z.string().min(1).max(512)
 });
+var subscriptionStatusEnum = zod.z.enum(["subscribed", "unsubscribed", "pending_doi", "bounced", "complained"]);
+var fieldNameSchema = (strict) => (strict ? zod.z.string().min(1) : zod.z.string()).max(256).regex(/^(?!\$)[^\0]*$/, "must not start with $");
+var segmentValueSchema = zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.null()]);
+function segmentFilterSchema(strict) {
+  const str = strict ? zod.z.string().min(1).max(256) : zod.z.string().max(256);
+  const days = zod.z.number().int().positive().max(36500).optional();
+  const self = zod.z.lazy(
+    () => zod.z.discriminatedUnion("kind", [
+      zod.z.object({ kind: zod.z.literal("fieldEquals"), field: fieldNameSchema(strict), value: segmentValueSchema }),
+      zod.z.object({ kind: zod.z.literal("fieldIn"), field: fieldNameSchema(strict), values: zod.z.array(segmentValueSchema).max(1e3) }),
+      zod.z.object({ kind: zod.z.literal("fieldExists"), field: fieldNameSchema(strict) }),
+      zod.z.object({ kind: zod.z.literal("hasTag"), tag: str }),
+      zod.z.object({ kind: zod.z.literal("notHasTag"), tag: str }),
+      zod.z.object({ kind: zod.z.literal("subscriptionStatus"), equals: subscriptionStatusEnum }),
+      zod.z.object({ kind: zod.z.literal("firedEvent"), eventName: str, withinDays: days }),
+      zod.z.object({ kind: zod.z.literal("notFiredEvent"), eventName: str, withinDays: days }),
+      zod.z.object({ kind: zod.z.literal("subscribedAfter"), date: zod.z.coerce.date() }),
+      zod.z.object({ kind: zod.z.literal("subscribedBefore"), date: zod.z.coerce.date() }),
+      zod.z.object({ kind: zod.z.literal("opened"), templateSlug: slugSchema.optional(), withinDays: days }),
+      zod.z.object({ kind: zod.z.literal("notOpened"), templateSlug: slugSchema.optional(), withinDays: days }),
+      zod.z.object({ kind: zod.z.literal("any"), filters: strict ? zod.z.array(self).min(1).max(50) : zod.z.array(self).max(50) }),
+      zod.z.object({ kind: zod.z.literal("not"), filter: self })
+    ])
+  );
+  return self;
+}
+function segmentDefinitionSchema(strict) {
+  return zod.z.object({ filters: zod.z.array(segmentFilterSchema(strict)).max(50) });
+}
 var flowStepSchema = zod.z.lazy(
   () => zod.z.discriminatedUnion("type", [
     zod.z.object({
@@ -691,6 +805,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,
@@ -718,7 +839,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 ?? {} }
   };
 }
 
@@ -936,11 +1058,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();
@@ -971,7 +1095,8 @@ function verifyUnsubscribeToken(token, secret, now = /* @__PURE__ */ new Date())
   return {
     email: body.e,
     scope: body.s,
-    expiresAt: new Date(body.x)
+    expiresAt: new Date(body.x),
+    ...typeof body.i === "string" && SEND_ID_RE.test(body.i) ? { sendId: body.i } : {}
   };
 }
 var TRACKING_SCOPES = ["open", "click"];
@@ -1592,11 +1717,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;
@@ -1626,7 +1751,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() }
     },
@@ -1653,7 +1778,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()
           }
@@ -1661,13 +1786,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 },
@@ -1677,12 +1810,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(
@@ -1717,7 +1850,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 },
@@ -1746,6 +1879,211 @@ function effectiveOverallStatus(docs) {
   if (buckets.some((d) => d.status === "degraded")) return "degraded";
   return "healthy";
 }
+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 releaseHeldSends(ctx, broadcastId) {
+  const held = await ctx.collections.sends.find({ broadcastId, status: "held" }, { projection: { _id: 1, notBefore: 1 } }).toArray();
+  if (held.length === 0) return 0;
+  await ctx.collections.sends.updateMany(
+    { _id: { $in: held.map((s) => s._id) }, status: "held" },
+    { $set: { status: "queued", errorMessage: null, updatedAt: /* @__PURE__ */ new Date() } }
+  );
+  const now = Date.now();
+  await Promise.all(
+    held.map((s) => {
+      const delay = s.notBefore ? Math.max(0, new Date(s.notBefore).getTime() - now) : 0;
+      return ctx.queues.send.add(
+        "send",
+        { sendId: String(s._id) },
+        {
+          attempts: ctx.config.sendRetryAttempts,
+          backoff: { type: "exponential", delay: 6e4 },
+          ...delay > 0 ? { delay } : {}
+        }
+      );
+    })
+  );
+  return held.length;
+}
+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 });
+    });
+  }
+}
+async function attributeUnsubscribeToSend(ctx, sendId, email) {
+  if (!mongodb.ObjectId.isValid(sendId)) return;
+  const _id = new mongodb.ObjectId(sendId);
+  const send = await ctx.collections.sends.findOne({ _id }, { projection: { emailAtSend: 1, broadcastId: 1 } });
+  if (!send || send.emailAtSend.toLowerCase() !== email.toLowerCase()) return;
+  await ctx.collections.sends.updateOne({ _id, unsubscribedAt: null }, { $set: { unsubscribedAt: /* @__PURE__ */ new Date() } });
+  if (send.broadcastId) await evaluateBroadcastStopRules(ctx, send.broadcastId);
+}
 
 // src/server/runner/webhook.ts
 function dimsFromSend(send) {
@@ -1900,6 +2238,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();
@@ -2311,11 +2654,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, step, contact, flow, ctx) {
@@ -2392,6 +2754,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(
@@ -2402,6 +2785,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 },
@@ -2416,6 +2812,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(
@@ -2434,7 +2834,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);
@@ -2525,11 +2925,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}`;
@@ -2612,6 +3012,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);
@@ -2905,6 +3309,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, path3) {
+  let cur = c.fields;
+  for (const part of path3.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();
@@ -2912,7 +3494,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;
@@ -2920,8 +3502,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(
@@ -2930,7 +3518,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}`
     }
   );
 }
@@ -2943,10 +3531,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);
   }
 }
@@ -2956,166 +3545,196 @@ 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 countBroadcastRecipients(broadcast, kind, ctx) {
+  const t0 = Date.now();
+  const { hostFilter } = planSegment(broadcast.segmentDefinition);
+  const [hostMatched, sendsSoFar] = await Promise.all([
+    ctx.adapter.count(hostFilter),
+    broadcast._id ? ctx.collections.sends.countDocuments({ broadcastId: broadcast._id }) : Promise.resolve(0)
+  ]);
+  let eligible = 0;
+  let alreadySent = 0;
+  for await (const page of eligibleRecipientPages(broadcast, kind, ctx)) {
+    eligible += page.length;
+    if (broadcast._id) alreadySent += (await alreadyDispatched(ctx, broadcast._id, page)).size;
+  }
+  const cap = typeof broadcast.recipientCap === "number" ? broadcast.recipientCap : null;
+  const uncapped = eligible - alreadySent;
+  const recipientCount = cap === null ? uncapped : Math.max(0, Math.min(uncapped, cap - sendsSoFar));
+  return {
+    hostMatched,
+    eligible,
+    alreadySent,
+    sendsSoFar,
+    recipientCap: cap,
+    uncappedRecipientCount: uncapped,
+    recipientCount,
+    computedMs: Date.now() - t0
+  };
+}
 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 });
         } catch (err) {
           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 } : {}
-              }
-            )
-          )
-        );
-      }
-      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));
-    }
-  }
-  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;
+      }
+      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 } : {}
+            }
+          )
+        )
+      );
+      if (capReached) break;
+    }
+    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,
@@ -3150,16 +3769,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_MS2 = 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;
@@ -3168,7 +3800,7 @@ function perRecipientOffsetMs(scheduledMs, timezone) {
     const utcMs = parse(utc);
     const localMs = parse(local);
     const offsetMs = utcMs - localMs;
-    return (offsetMs % DAY_MS2 + DAY_MS2) % DAY_MS2;
+    return (offsetMs % DAY_MS + DAY_MS) % DAY_MS;
   } catch {
     return 0;
   }
@@ -3279,10 +3911,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 },
       {
@@ -3291,9 +3923,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()
         }
       },
@@ -3326,6 +3958,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);
@@ -3361,16 +3997,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."));
@@ -3937,17 +4579,17 @@ function parseDmarcReport(xml) {
   const day = new Date(midMs).toISOString().slice(0, 10);
   for (const rec of records) {
     const row = rec?.row ?? {};
-    const count = Number(row.count ?? 0) || 0;
-    totalMessages += count;
+    const count2 = Number(row.count ?? 0) || 0;
+    totalMessages += count2;
     const evald = row.policy_evaluated ?? {};
     const dkim = evald.dkim ?? "none";
     const spf = evald.spf ?? "none";
     const aligned = dkim === "pass" || spf === "pass";
     if (aligned) {
-      passCount += count;
+      passCount += count2;
       continue;
     }
-    failCount += count;
+    failCount += count2;
     const sourceIp = String(row.source_ip ?? "").trim();
     if (!sourceIp) continue;
     const headerFrom = String(rec?.identifiers?.header_from ?? "").toLowerCase();
@@ -3956,7 +4598,7 @@ function parseDmarcReport(xml) {
       reportId,
       domain,
       sourceIp,
-      count,
+      count: count2,
       headerFrom,
       dkimResult: dkim,
       spfResult: spf,
@@ -4101,11 +4743,11 @@ function suggestPolicyProgression(input) {
     return null;
   }
   if (currentPolicy === "quarantine") {
-    const pct = currentPct ?? 100;
+    const pct2 = currentPct ?? 100;
     if (alignmentRate < 0.995) return null;
-    if (pct < 25) return { policy: "quarantine", pct: 25, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct} to 25.` };
-    if (pct < 50) return { policy: "quarantine", pct: 50, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct} to 50.` };
-    if (pct < 100) return { policy: "quarantine", pct: 100, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct} to 100.` };
+    if (pct2 < 25) return { policy: "quarantine", pct: 25, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct2} to 25.` };
+    if (pct2 < 50) return { policy: "quarantine", pct: 50, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct2} to 50.` };
+    if (pct2 < 100) return { policy: "quarantine", pct: 100, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct2} to 100.` };
     if (alignmentRate >= 0.999) {
       return { policy: "reject", pct: 100, reason: `Alignment at ${(alignmentRate * 100).toFixed(3)}% with policy=quarantine pct=100 \u2014 safe to move to p=reject.` };
     }
@@ -4416,6 +5058,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);
   });
@@ -5817,7 +6462,7 @@ async function checkDnsbl(mailer) {
       label: "DNS block-list checks",
       severity: "warn",
       message: `all ${docs.length} checks errored`,
-      hint: "Lookups against block lists are failing \u2014 usually a DNS-resolution problem on the host running mailery, or a list rate-limiting your public resolver. Verify outbound DNS works."
+      hint: "Lookups against block lists are failing \u2014 usually a DNS-resolution problem on the host running mailery, or a list refusing your public resolver (Spamhaus answers 127.255.255.254; set dnsbl.spamhausDqsKey). Verify outbound DNS works."
     };
   }
   return {
@@ -6123,7 +6768,7 @@ function humanDuration(ms) {
 }
 
 // src/server/runner/hygiene.ts
-var DAY_MS = 864e5;
+var DAY_MS2 = 864e5;
 var HYGIENE_BUCKETS = [
   { label: "Engaged (last 30 days)", maxDays: 30 },
   { label: "Engaged (31-60 days)", minDays: 30, maxDays: 60 },
@@ -6136,7 +6781,7 @@ async function computeListHygiene(ctx, opts = {}) {
   const now = opts.now ?? Date.now();
   const sunsetDays = opts.sunsetThresholdDays ?? 180;
   const recentDays = opts.recentWindowDays ?? 90;
-  const recentCutoff = new Date(now - recentDays * DAY_MS);
+  const recentCutoff = new Date(now - recentDays * DAY_MS2);
   const totalSubscribers = await ctx.collections.subscriptions.countDocuments({ status: "subscribed" });
   const subscribedIds = /* @__PURE__ */ new Set();
   {
@@ -6209,11 +6854,11 @@ async function computeListHygiene(ctx, opts = {}) {
     if (lastEngaged == null) {
       const firstSent = row.firstSent ? new Date(row.firstSent).getTime() : null;
       buckets[5].count++;
-      if (firstSent != null && now - firstSent > sunsetDays * DAY_MS) {
+      if (firstSent != null && now - firstSent > sunsetDays * DAY_MS2) {
         isSunset = true;
       }
     } else {
-      const daysSince = (now - lastEngaged) / DAY_MS;
+      const daysSince = (now - lastEngaged) / DAY_MS2;
       if (daysSince <= 30) buckets[0].count++;
       else if (daysSince <= 60) buckets[1].count++;
       else if (daysSince <= 90) buckets[2].count++;
@@ -6412,6 +7057,462 @@ async function evaluateMailTesterGate(ctx, input) {
   }
   return { allowed: true, reason: null, score: cached, code: null };
 }
+var BroadcastOperationError = class extends Error {
+  constructor(code, message, status = 400, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "BroadcastOperationError";
+  }
+  code;
+  status;
+  details;
+};
+var DEFAULT_SEGMENT = {
+  filters: [{ kind: "subscriptionStatus", equals: "subscribed" }]
+};
+var MAX_RECIPIENT_CAP = 1e7;
+var ORDER_FIELD_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+var recipientCapSchema = zod.z.number().int().positive().max(MAX_RECIPIENT_CAP).nullable();
+var orderSchema = zod.z.object({
+  field: zod.z.string().max(128).regex(ORDER_FIELD_RE, "must be a plain field path, e.g. updatedAt"),
+  direction: zod.z.enum(["asc", "desc"])
+}).nullable();
+var pctSchema = zod.z.number().min(0).max(100);
+var stopRulesSchema = zod.z.object({
+  enabled: zod.z.boolean().optional(),
+  hardBounceRatePct: pctSchema.optional(),
+  complaintRatePct: pctSchema.optional(),
+  unsubscribeRatePct: pctSchema.optional(),
+  minSample: zod.z.number().int().min(1).max(1e6).optional()
+}).strict().nullable();
+var agentCreateBroadcastSchema = zod.z.object({
+  slug: slugSchema,
+  name: zod.z.string().min(1).max(200),
+  templateSlug: slugSchema,
+  segmentDefinition: zod.z.object({ filters: zod.z.array(zod.z.any()) }).optional(),
+  respectRecipientTimezone: zod.z.boolean().optional(),
+  recipientCap: recipientCapSchema.optional(),
+  order: orderSchema.optional(),
+  stopRules: stopRulesSchema.optional()
+});
+var agentPatchBroadcastSchema = zod.z.object({
+  name: zod.z.string().min(1).max(200).optional(),
+  templateSlug: slugSchema.optional(),
+  segmentDefinition: zod.z.object({ filters: zod.z.array(zod.z.any()) }).optional(),
+  respectRecipientTimezone: zod.z.boolean().optional(),
+  recipientCap: recipientCapSchema.optional(),
+  order: orderSchema.optional(),
+  stopRules: stopRulesSchema.optional()
+});
+var agentResumeBroadcastSchema = zod.z.object({
+  recipientCap: recipientCapSchema.optional(),
+  stopRules: stopRulesSchema.optional(),
+  confirmedCount: zod.z.number().int().nonnegative()
+});
+var agentPauseBroadcastSchema = zod.z.object({
+  reason: zod.z.string().max(500).optional()
+});
+function checkWaveSettings(mailer, input) {
+  if (input.stopRules !== void 0 && !stopRulesSchema.safeParse(input.stopRules).success) {
+    throw new BroadcastOperationError(
+      "invalid_stop_rules",
+      "stopRules must be {enabled?, hardBounceRatePct?, complaintRatePct?, unsubscribeRatePct?, minSample?} (percentages 0-100), or null"
+    );
+  }
+  if (input.recipientCap !== void 0 && !recipientCapSchema.safeParse(input.recipientCap).success) {
+    throw new BroadcastOperationError("invalid_recipient_cap", `recipientCap must be a positive integer up to ${MAX_RECIPIENT_CAP}, or null`);
+  }
+  if (input.order !== void 0) {
+    if (!orderSchema.safeParse(input.order).success) {
+      throw new BroadcastOperationError("invalid_order", 'order must be {field: "<host field path>", direction: "asc" | "desc"}, or null');
+    }
+    if (input.order !== null && !mailer.adapter.supportsSort) {
+      throw new BroadcastOperationError(
+        "adapter_cannot_sort",
+        "the contact adapter does not declare supportsSort, so a broadcast cannot be sent in an order; omit order to send in the adapter's own order",
+        422
+      );
+    }
+  }
+}
+var agentScheduleBroadcastSchema = zod.z.object({
+  scheduledAt: zod.z.string().min(1),
+  confirmedCount: zod.z.number().int().nonnegative(),
+  respectRecipientTimezone: zod.z.boolean().optional()
+});
+function parseSegment(seg, strict) {
+  const r = segmentDefinitionSchema(strict).safeParse(seg);
+  if (!r.success) {
+    throw new BroadcastOperationError(
+      "invalid_segment",
+      `segmentDefinition: ${r.error.issues.map((i) => `${i.path.join(".") || "filters"}: ${i.message}`).join("; ")}`,
+      400
+    );
+  }
+  return r.data;
+}
+function assertSubscribedSegment(seg) {
+  const filters = Array.isArray(seg?.filters) ? seg.filters : [];
+  const ok = filters.some((f) => f && f.kind === "subscriptionStatus" && f.equals === "subscribed");
+  if (!ok) {
+    throw new BroadcastOperationError(
+      "segment_requires_subscribed",
+      'the agent API only schedules broadcasts to subscribed contacts: add {"kind": "subscriptionStatus", "equals": "subscribed"} to segmentDefinition.filters (top level)',
+      422
+    );
+  }
+}
+async function loadBroadcast(mailer, slug) {
+  const b = await mailer.collections.broadcasts.findOne({ slug });
+  if (!b) throw new BroadcastOperationError("not_found", `no broadcast with slug "${slug}"`, 404);
+  return b;
+}
+async function loadBroadcastTemplate(mailer, b) {
+  const tpl = await mailer.collections.templates.findOne({ slug: b.templateSlug });
+  if (!tpl) {
+    throw new BroadcastOperationError("template_not_found", `template "${b.templateSlug}" does not exist`, 409);
+  }
+  return tpl;
+}
+async function countRecipients(mailer, b, segment, overrides = {}) {
+  const tpl = await loadBroadcastTemplate(mailer, b);
+  const count2 = await countBroadcastRecipients(
+    {
+      _id: b._id,
+      segmentDefinition: segment ?? b.segmentDefinition,
+      order: b.order ?? null,
+      recipientCap: overrides.recipientCap !== void 0 ? overrides.recipientCap : b.recipientCap ?? null
+    },
+    tpl.kind,
+    mailer.getRunnerContext()
+  );
+  const heldSends = b._id ? await mailer.collections.sends.countDocuments({ broadcastId: b._id, status: "held" }) : 0;
+  return { ...count2, heldSends, templateKind: tpl.kind };
+}
+function stopRuleStatus(mailer, b, stats) {
+  return evaluateStopRules(stats, effectiveStopRules(mailer.config, b));
+}
+async function pauseBroadcastByOperator(mailer, slug, input, actor) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "sending" && b.status !== "sent") {
+    throw new BroadcastOperationError("not_pausable", `broadcast is ${b.status}; only a sending or sent broadcast can be paused (cancel a draft or scheduled one)`, 409);
+  }
+  const out = await pauseBroadcast(
+    mailer.getRunnerContext(),
+    b._id,
+    { code: "manual", message: input.reason?.trim() || `paused by ${actor}`, at: /* @__PURE__ */ new Date(), details: { actor } },
+    actor
+  );
+  if (!out.paused) throw new BroadcastOperationError("not_pausable", "broadcast changed state while being paused", 409);
+  return { broadcast: await mailer.collections.broadcasts.findOne({ _id: b._id }) ?? b, heldSends: out.heldSends };
+}
+async function createBroadcast(mailer, input, actor, opts = {}) {
+  const { slug, name, templateSlug } = input;
+  if (!slug || !name || !templateSlug) {
+    throw new BroadcastOperationError("validation_failed", "slug, name, templateSlug required");
+  }
+  const segmentDefinition = input.segmentDefinition ? parseSegment(input.segmentDefinition, !!opts.strictSegment) : DEFAULT_SEGMENT;
+  if (opts.requireSubscribed) assertSubscribedSegment(segmentDefinition);
+  checkWaveSettings(mailer, input);
+  await assertBroadcastTemplate(mailer, templateSlug, { mustExist: false });
+  const now = /* @__PURE__ */ new Date();
+  const doc = {
+    slug,
+    name,
+    templateSlug,
+    segmentDefinition,
+    status: "draft",
+    scheduledAt: null,
+    startedAt: null,
+    completedAt: null,
+    confirmationRequired: true,
+    confirmedCount: null,
+    confirmedAt: null,
+    confirmedBy: null,
+    recipientCount: null,
+    stats: { sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0 },
+    createdAt: now,
+    createdBy: actor,
+    updatedAt: now
+  };
+  if (input.respectRecipientTimezone) doc.respectRecipientTimezone = true;
+  if (input.recipientCap !== void 0) doc.recipientCap = input.recipientCap;
+  if (input.order !== void 0) doc.order = input.order;
+  if (input.stopRules !== void 0) doc.stopRules = input.stopRules;
+  try {
+    const res = await mailer.collections.broadcasts.insertOne(doc);
+    doc._id = res.insertedId;
+  } catch (err) {
+    if (err?.code === 11e3) throw new BroadcastOperationError("slug_taken", `slug "${slug}" is taken`, 409);
+    throw err;
+  }
+  await mailer.audit({
+    actor,
+    action: "broadcast.create",
+    resource: { collection: "mailer_broadcasts", id: doc._id, slug }
+  });
+  return doc;
+}
+async function patchBroadcast(mailer, slug, patch, actor, opts = {}) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "draft") {
+    throw new BroadcastOperationError("not_draft", `broadcast is ${b.status}; only a draft can be edited`, 409);
+  }
+  const segmentDefinition = patch.segmentDefinition ? parseSegment(patch.segmentDefinition, !!opts.strictSegment) : void 0;
+  if (opts.requireSubscribed && segmentDefinition) assertSubscribedSegment(segmentDefinition);
+  checkWaveSettings(mailer, patch);
+  if (typeof patch.templateSlug === "string") await assertBroadcastTemplate(mailer, patch.templateSlug, { mustExist: false });
+  const set2 = { updatedAt: /* @__PURE__ */ new Date() };
+  if (patch.recipientCap !== void 0) set2.recipientCap = patch.recipientCap;
+  if (patch.order !== void 0) set2.order = patch.order;
+  if (patch.stopRules !== void 0) set2.stopRules = patch.stopRules;
+  if (typeof patch.name === "string") set2.name = patch.name;
+  if (typeof patch.templateSlug === "string") set2.templateSlug = patch.templateSlug;
+  if (segmentDefinition) set2.segmentDefinition = segmentDefinition;
+  if (typeof patch.respectRecipientTimezone === "boolean") set2.respectRecipientTimezone = patch.respectRecipientTimezone;
+  const res = await mailer.collections.broadcasts.findOneAndUpdate(
+    { _id: b._id, status: "draft" },
+    { $set: set2 },
+    { returnDocument: "after" }
+  );
+  if (!res) throw new BroadcastOperationError("not_draft", "broadcast left draft while being edited", 409);
+  await mailer.audit({
+    actor,
+    action: "broadcast.update",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug },
+    diffSummary: Object.keys(set2).filter((k) => k !== "updatedAt").join(", ")
+  });
+  return res;
+}
+async function scheduleBroadcast(mailer, slug, input, actor, opts = {}) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "draft") {
+    throw new BroadcastOperationError("not_draft", `broadcast is ${b.status}; only a draft can be scheduled`, 409);
+  }
+  if (opts.requireSubscribed) assertSubscribedSegment(b.segmentDefinition);
+  parseSegment(b.segmentDefinition, true);
+  await assertBroadcastTemplate(mailer, b.templateSlug, { mustExist: true });
+  if (!input.scheduledAt) throw new BroadcastOperationError("scheduledAt_required", "scheduledAt is required");
+  const scheduled = new Date(input.scheduledAt);
+  if (Number.isNaN(scheduled.getTime())) throw new BroadcastOperationError("bad_scheduledAt", "scheduledAt is not a date");
+  if (typeof input.confirmedCount !== "number") {
+    throw new BroadcastOperationError("confirmedCount_required", "confirmedCount (number) is required");
+  }
+  const confirmedCount = input.confirmedCount;
+  const threshold = mailer.config.broadcastConfirmationThreshold;
+  if (opts.requireExactCount) {
+    const { recipientCount } = await countRecipients(mailer, b);
+    if (confirmedCount !== recipientCount) {
+      throw new BroadcastOperationError(
+        "count_mismatch",
+        `confirmedCount ${confirmedCount} does not match the ${recipientCount} recipient(s) this broadcast would send to now; recount with POST /broadcasts/${b.slug}/count`,
+        409,
+        { expected: recipientCount, confirmedCount }
+      );
+    }
+  }
+  const set2 = {
+    status: "scheduled",
+    scheduledAt: scheduled,
+    confirmedCount,
+    confirmedAt: /* @__PURE__ */ new Date(),
+    confirmedBy: actor,
+    updatedAt: /* @__PURE__ */ new Date()
+  };
+  if (input.respectRecipientTimezone) set2.respectRecipientTimezone = true;
+  const res = await mailer.collections.broadcasts.findOneAndUpdate(
+    { _id: b._id, status: "draft" },
+    { $set: set2 },
+    { returnDocument: "after" }
+  );
+  if (!res) throw new BroadcastOperationError("not_draft", "broadcast left draft while being scheduled", 409);
+  await mailer.audit({
+    actor,
+    action: "broadcast.schedule",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+    diffSummary: `scheduled at ${scheduled.toISOString()} \xB7 confirmedCount=${confirmedCount} \xB7 threshold=${threshold}`
+  });
+  return res;
+}
+async function resumeBroadcast(mailer, slug, input, actor, opts = {}) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "paused") {
+    throw new BroadcastOperationError("not_paused", `broadcast is ${b.status}; only a paused broadcast can be resumed`, 409);
+  }
+  if (opts.requireSubscribed) assertSubscribedSegment(b.segmentDefinition);
+  checkWaveSettings(mailer, { recipientCap: input.recipientCap, stopRules: input.stopRules });
+  const cap = input.recipientCap !== void 0 ? input.recipientCap : b.recipientCap ?? null;
+  const stopRules = input.stopRules === void 0 ? b.stopRules ?? null : input.stopRules === null ? null : { ...b.stopRules ?? {}, ...input.stopRules };
+  if (b.pauseReason?.code === "stop_rule") {
+    const evaluation = evaluateStopRules(
+      await broadcastStatsFor(mailer.collections, b._id),
+      effectiveStopRules(mailer.config, { stopRules })
+    );
+    if (evaluation.breaches.length > 0) {
+      throw new BroadcastOperationError(
+        "stop_rule_still_breached",
+        `the stop rules still fire (${evaluation.breaches.map((x) => `${x.rule} ${x.ratePct}% > ${x.thresholdPct}%`).join(", ")}); investigate, then resume with adjusted stopRules to override`,
+        409,
+        { evaluation }
+      );
+    }
+  }
+  if (b.pauseReason?.code === "circuit_breaker") {
+    const tpl = await loadBroadcastTemplate(mailer, b);
+    const bucket = await getBucketStatus(mailer.getRunnerContext(), tpl.fromEmail, tpl.kind);
+    if (bucket?.status === "tripped") {
+      throw new BroadcastOperationError(
+        "circuit_breaker_tripped",
+        `the ${bucket.senderDomain ?? "sender"} ${tpl.kind} circuit breaker is still tripped (${bucket.trippedReason ?? "no reason recorded"}); resume it first (POST /api/health/resume)`,
+        409,
+        { bucket: bucket._id, trippedReason: bucket.trippedReason }
+      );
+    }
+  }
+  const sendsSoFar = await mailer.collections.sends.countDocuments({ broadcastId: b._id });
+  if (cap !== null && cap <= sendsSoFar && b.pauseReason?.code === "cap_reached") {
+    throw new BroadcastOperationError(
+      "cap_not_raised",
+      `${sendsSoFar} send(s) already count against recipientCap ${cap}; pass a higher recipientCap (or null for no cap) to send the next wave`,
+      409,
+      { recipientCap: cap, sendsSoFar }
+    );
+  }
+  if (cap !== null && cap < sendsSoFar) {
+    throw new BroadcastOperationError("cap_below_sent", `recipientCap ${cap} is below the ${sendsSoFar} send(s) already made`, 400);
+  }
+  let expected = null;
+  if (opts.requireExactCount) {
+    if (typeof input.confirmedCount !== "number") {
+      throw new BroadcastOperationError("confirmedCount_required", "confirmedCount (number) is required");
+    }
+    const count2 = await countRecipients(mailer, b, void 0, { recipientCap: cap });
+    expected = count2.recipientCount + count2.heldSends;
+    if (input.confirmedCount !== expected) {
+      throw new BroadcastOperationError(
+        "count_mismatch",
+        `confirmedCount ${input.confirmedCount} does not match the ${expected} send(s) resuming would release now (${count2.recipientCount} new + ${count2.heldSends} held)`,
+        409,
+        { expected, recipientCount: count2.recipientCount, heldSends: count2.heldSends, confirmedCount: input.confirmedCount }
+      );
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  const resumed = await mailer.collections.broadcasts.findOneAndUpdate(
+    { _id: b._id, status: "paused" },
+    {
+      $set: {
+        status: "sending",
+        recipientCap: cap,
+        stopRules,
+        pausedAt: null,
+        pauseReason: null,
+        dispatchLeaseId: null,
+        updatedAt: now,
+        ...typeof input.confirmedCount === "number" ? { confirmedCount: input.confirmedCount, confirmedAt: now, confirmedBy: actor } : {}
+      }
+    },
+    { returnDocument: "after" }
+  );
+  if (!resumed) throw new BroadcastOperationError("not_paused", "broadcast left paused while being resumed", 409);
+  await mailer.audit({
+    actor,
+    action: "broadcast.resume",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+    diffSummary: `was paused (${b.pauseReason?.code ?? "unknown"}) \xB7 recipientCap ${b.recipientCap ?? "none"} \u2192 ${cap ?? "none"} \xB7 sendsSoFar=${sendsSoFar}${expected !== null ? ` \xB7 confirmedCount=${expected}` : ""}`
+  });
+  const ctx = mailer.getRunnerContext();
+  await releaseHeldSends(ctx, b._id);
+  await startBroadcastDispatch(resumed, ctx);
+  return await mailer.collections.broadcasts.findOne({ _id: b._id }) ?? resumed;
+}
+async function cancelBroadcast(mailer, slug, actor) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status === "cancelled") return { broadcast: b, cancelledSends: 0 };
+  const pending = await mailer.collections.sends.countDocuments({ broadcastId: b._id, status: { $in: ["queued", "held"] } });
+  if ((b.status === "sent" || b.status === "failed") && pending === 0) {
+    throw new BroadcastOperationError("already_finished", `broadcast is ${b.status} with nothing left to send; there is nothing to cancel`, 409);
+  }
+  await mailer.collections.broadcasts.updateOne({ _id: b._id }, { $set: { status: "cancelled", updatedAt: /* @__PURE__ */ new Date() } });
+  const now = /* @__PURE__ */ new Date();
+  const cancelled = await mailer.collections.sends.updateMany(
+    { broadcastId: b._id, status: { $in: ["queued", "held"] } },
+    { $set: { status: "cancelled", errorMessage: `cancelled: broadcast cancelled by ${actor}`, updatedAt: now } }
+  );
+  await mailer.audit({
+    actor,
+    action: "broadcast.cancel",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+    diffSummary: `was ${b.status}; cancelled ${cancelled.modifiedCount} queued/held send(s)`
+  });
+  const after = await mailer.collections.broadcasts.findOne({ _id: b._id });
+  return { broadcast: after ?? b, cancelledSends: cancelled.modifiedCount };
+}
+async function assertBroadcastTemplate(mailer, templateSlug, opts) {
+  const tpl = await mailer.collections.templates.findOne({ slug: templateSlug });
+  if (!tpl) {
+    if (opts.mustExist) throw new BroadcastOperationError("template_not_found", `template "${templateSlug}" does not exist`, 409);
+    return;
+  }
+  if (tpl.kind !== "marketing") {
+    throw new BroadcastOperationError(
+      "template_not_marketing",
+      `template "${templateSlug}" is ${tpl.kind}; a broadcast needs a marketing template (List-Unsubscribe, marketing opt-outs, circuit breaker)`,
+      409
+    );
+  }
+  if (opts.mustExist && !tpl.body?.html && !tpl.body?.mjml) {
+    throw new BroadcastOperationError("template_not_published", `template "${templateSlug}" has no published body`, 409);
+  }
+}
+async function computeBroadcastStats(mailer, idFilter) {
+  return aggregateBroadcastStats(mailer.collections, idFilter);
+}
+function capProgress(b, stats) {
+  const cap = typeof b.recipientCap === "number" ? b.recipientCap : null;
+  return {
+    recipientCap: cap,
+    sendsSoFar: stats.total,
+    remaining: cap === null ? null : Math.max(0, cap - stats.total)
+  };
+}
+async function broadcastStatusBreakdown(mailer, broadcastId) {
+  const rows = await mailer.collections.sends.aggregate([
+    { $match: { broadcastId } },
+    { $group: { _id: "$status", n: { $sum: 1 } } }
+  ]).toArray();
+  return Object.fromEntries(rows.map((r) => [r._id, r.n]));
+}
+function broadcastSummary(b) {
+  return {
+    id: String(b._id),
+    slug: b.slug,
+    name: b.name,
+    templateSlug: b.templateSlug,
+    status: b.status,
+    segmentDefinition: b.segmentDefinition,
+    respectRecipientTimezone: b.respectRecipientTimezone === true,
+    recipientCap: b.recipientCap ?? null,
+    order: b.order ?? null,
+    pausedAt: b.pausedAt ?? null,
+    pauseReason: b.pauseReason ?? null,
+    stopRules: b.stopRules ?? null,
+    stopRuleBreach: b.stopRuleBreach ?? null,
+    failureReason: b.failureReason ?? null,
+    scheduledAt: b.scheduledAt,
+    startedAt: b.startedAt,
+    completedAt: b.completedAt,
+    confirmedCount: b.confirmedCount,
+    confirmedAt: b.confirmedAt,
+    confirmedBy: b.confirmedBy,
+    recipientCount: b.recipientCount,
+    createdAt: b.createdAt,
+    createdBy: b.createdBy,
+    updatedAt: b.updatedAt
+  };
+}
 
 // src/server/api/admin.ts
 var __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
@@ -7214,19 +8315,19 @@ function createAdminApiRouter(mailer, opts = {}) {
       const flow = await c.flows.findOne({ slug: req.params.slug });
       if (!flow) return res.status(404).json({ error: "not_found" });
       const { steps, notes, trigger, name, description, goal, audience } = req.body ?? {};
-      const set = {
+      const set2 = {
         "draft.lastModifiedBy": req.actor,
         "draft.lastModifiedAt": /* @__PURE__ */ new Date(),
         updatedAt: /* @__PURE__ */ new Date()
       };
-      if (Array.isArray(steps)) set["draft.steps"] = steps;
-      if (typeof notes === "string") set["draft.notes"] = notes;
-      if (trigger?.eventName) set.trigger = { type: "event", eventName: trigger.eventName, once: trigger.once !== false };
-      if (typeof name === "string") set.name = name;
-      if (typeof description === "string") set.description = description;
-      if (typeof goal === "string") set.goal = goal;
-      if (typeof audience === "string") set.audience = audience;
-      await c.flows.updateOne({ _id: flow._id }, { $set: set });
+      if (Array.isArray(steps)) set2["draft.steps"] = steps;
+      if (typeof notes === "string") set2["draft.notes"] = notes;
+      if (trigger?.eventName) set2.trigger = { type: "event", eventName: trigger.eventName, once: trigger.once !== false };
+      if (typeof name === "string") set2.name = name;
+      if (typeof description === "string") set2.description = description;
+      if (typeof goal === "string") set2.goal = goal;
+      if (typeof audience === "string") set2.audience = audience;
+      await c.flows.updateOne({ _id: flow._id }, { $set: set2 });
       await mailer.audit({
         actor: req.actor,
         action: "flow.draft.update",
@@ -7387,25 +8488,25 @@ function createAdminApiRouter(mailer, opts = {}) {
           }
         );
       }
-      const set = {
+      const set2 = {
         "draft.lastModifiedBy": req.actor,
         "draft.lastModifiedAt": /* @__PURE__ */ new Date(),
         updatedAt: /* @__PURE__ */ new Date()
       };
-      if (typeof subject === "string") set["draft.subject"] = subject;
-      if (typeof preheader === "string") set["draft.preheader"] = preheader;
-      if (typeof mjml === "string") set["draft.mjml"] = mjml;
-      if (typeof html === "string") set["draft.html"] = html;
-      if (editorJson !== void 0) set["draft.editorJson"] = editorJson;
-      if (typeof notes === "string") set["draft.notes"] = notes;
-      if (typeof name === "string") set.name = name;
-      if (typeof fromName === "string") set.fromName = fromName;
-      if (typeof fromEmail === "string") set.fromEmail = fromEmail;
-      if (typeof replyTo === "string" || replyTo === null) set.replyTo = replyTo;
-      if (kind === "marketing" || kind === "transactional") set.kind = kind;
+      if (typeof subject === "string") set2["draft.subject"] = subject;
+      if (typeof preheader === "string") set2["draft.preheader"] = preheader;
+      if (typeof mjml === "string") set2["draft.mjml"] = mjml;
+      if (typeof html === "string") set2["draft.html"] = html;
+      if (editorJson !== void 0) set2["draft.editorJson"] = editorJson;
+      if (typeof notes === "string") set2["draft.notes"] = notes;
+      if (typeof name === "string") set2.name = name;
+      if (typeof fromName === "string") set2.fromName = fromName;
+      if (typeof fromEmail === "string") set2.fromEmail = fromEmail;
+      if (typeof replyTo === "string" || replyTo === null) set2.replyTo = replyTo;
+      if (kind === "marketing" || kind === "transactional") set2.kind = kind;
       if (typeof fromEmail === "string" || kind === "marketing" || kind === "transactional") {
-        const resultingKind = set.kind ?? tpl.kind;
-        const resultingFromEmail = set.fromEmail ?? tpl.fromEmail;
+        const resultingKind = set2.kind ?? tpl.kind;
+        const resultingFromEmail = set2.fromEmail ?? tpl.fromEmail;
         const senderCheck = validateSenderDomain(resultingFromEmail, resultingKind, mailer.config.senderDomains);
         if (!senderCheck.ok) {
           return res.status(400).json({
@@ -7415,10 +8516,10 @@ function createAdminApiRouter(mailer, opts = {}) {
           });
         }
       }
-      if (TEMPLATE_BODY_FORMATS.includes(bodyFormat)) set.bodyFormat = bodyFormat;
-      if (typeof trackOpens === "boolean") set.trackOpens = trackOpens;
-      if (typeof trackClicks === "boolean") set.trackClicks = trackClicks;
-      await c.templates.updateOne({ _id: tpl._id }, { $set: set });
+      if (TEMPLATE_BODY_FORMATS.includes(bodyFormat)) set2.bodyFormat = bodyFormat;
+      if (typeof trackOpens === "boolean") set2.trackOpens = trackOpens;
+      if (typeof trackClicks === "boolean") set2.trackClicks = trackClicks;
+      await c.templates.updateOne({ _id: tpl._id }, { $set: set2 });
       await mailer.audit({
         actor: req.actor,
         action: "template.draft.update",
@@ -7896,125 +8997,60 @@ function createAdminApiRouter(mailer, opts = {}) {
   );
   r.post(
     "/broadcasts",
-    asyncHandler(async (req, res) => {
-      const { slug, name, templateSlug, segmentDefinition } = req.body ?? {};
-      if (!slug || !name || !templateSlug) {
-        return res.status(400).json({ error: "validation_failed", message: "slug, name, templateSlug required" });
-      }
-      const now = /* @__PURE__ */ new Date();
-      try {
-        await c.broadcasts.insertOne({
-          slug,
-          name,
-          templateSlug,
-          segmentDefinition: segmentDefinition ?? { filters: [{ kind: "subscriptionStatus", equals: "subscribed" }] },
-          status: "draft",
-          scheduledAt: null,
-          startedAt: null,
-          completedAt: null,
-          confirmationRequired: true,
-          confirmedCount: null,
-          confirmedAt: null,
-          confirmedBy: null,
-          recipientCount: null,
-          stats: { sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0 },
-          createdAt: now,
-          createdBy: req.actor,
-          updatedAt: now
-        });
-      } catch (err) {
-        if (err?.code === 11e3) return res.status(409).json({ error: "slug_taken" });
-        throw err;
-      }
-      await mailer.audit({
-        actor: req.actor,
-        action: "broadcast.create",
-        resource: { collection: "mailer_broadcasts", slug }
-      });
+    broadcastHandler(async (req, res) => {
+      const { slug, name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order } = req.body ?? {};
+      await createBroadcast(
+        mailer,
+        { slug, name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order },
+        req.actor
+      );
       return res.json({ ok: true, slug });
     })
   );
   r.patch(
     "/broadcasts/:slug",
-    asyncHandler(async (req, res) => {
-      const b = await c.broadcasts.findOne({ slug: req.params.slug });
-      if (!b) return res.status(404).json({ error: "not_found" });
-      if (b.status !== "draft") return res.status(409).json({ error: "not_draft" });
-      const { name, templateSlug, segmentDefinition } = req.body ?? {};
-      const set = { updatedAt: /* @__PURE__ */ new Date() };
-      if (typeof name === "string") set.name = name;
-      if (typeof templateSlug === "string") set.templateSlug = templateSlug;
-      if (segmentDefinition) set.segmentDefinition = segmentDefinition;
-      await c.broadcasts.updateOne({ _id: b._id }, { $set: set });
+    broadcastHandler(async (req, res) => {
+      const { name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order } = req.body ?? {};
+      await patchBroadcast(
+        mailer,
+        String(req.params.slug),
+        { name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order },
+        req.actor
+      );
       return res.json({ ok: true });
     })
   );
   r.post(
     "/broadcasts/:slug/segment/count",
-    asyncHandler(async (req, res) => {
-      const segmentDefinition = req.body?.segmentDefinition;
-      if (!segmentDefinition?.filters) return res.status(400).json({ error: "segment_required" });
-      const t0 = Date.now();
-      const hostFilter = {};
-      for (const f of segmentDefinition.filters) {
-        if (f.kind === "hasTag") hostFilter.hasTag = f.tag;
-        if (f.kind === "fieldEquals") hostFilter.fieldEquals = { field: f.field, value: f.value };
-      }
-      const hasMailerFilters = segmentDefinition.filters.some(
-        (f) => ["subscriptionStatus", "firedEvent", "notFiredEvent", "notHasTag", "opened", "notOpened", "subscribedAfter", "subscribedBefore"].includes(f.kind)
-      );
-      const upperBound = await mailer.adapter.count(hostFilter);
+    broadcastHandler(async (req, res) => {
+      const raw = req.body?.segmentDefinition;
+      if (!raw?.filters) return res.status(400).json({ error: "segment_required" });
+      const segment = parseSegment(raw, false);
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const count2 = await countRecipients(mailer, b, segment);
       return res.json({
-        upperBound,
-        approximate: hasMailerFilters,
-        computedMs: Date.now() - t0
+        upperBound: count2.recipientCount,
+        approximate: false,
+        computedMs: count2.computedMs,
+        hostMatched: count2.hostMatched,
+        eligible: count2.eligible,
+        alreadySent: count2.alreadySent,
+        recipientCount: count2.recipientCount
       });
     })
   );
   r.post(
     "/broadcasts/:slug/schedule",
-    asyncHandler(async (req, res) => {
-      const b = await c.broadcasts.findOne({ slug: req.params.slug });
-      if (!b) return res.status(404).json({ error: "not_found" });
-      if (b.status !== "draft") return res.status(409).json({ error: "not_draft" });
+    broadcastHandler(async (req, res) => {
       const { scheduledAt, confirmedCount, respectRecipientTimezone } = req.body ?? {};
-      if (!scheduledAt) return res.status(400).json({ error: "scheduledAt_required" });
-      const scheduled = new Date(scheduledAt);
-      if (Number.isNaN(scheduled.getTime())) return res.status(400).json({ error: "bad_scheduledAt" });
-      const threshold = mailer.config.broadcastConfirmationThreshold;
-      if (typeof confirmedCount !== "number") {
-        return res.status(400).json({ error: "confirmedCount_required" });
-      }
-      const set = {
-        status: "scheduled",
-        scheduledAt: scheduled,
-        confirmedCount,
-        confirmedAt: /* @__PURE__ */ new Date(),
-        confirmedBy: req.actor,
-        updatedAt: /* @__PURE__ */ new Date()
-      };
-      if (respectRecipientTimezone) set.respectRecipientTimezone = true;
-      await c.broadcasts.updateOne({ _id: b._id }, { $set: set });
-      await mailer.audit({
-        actor: req.actor,
-        action: "broadcast.schedule",
-        resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
-        diffSummary: `scheduled at ${scheduled.toISOString()} \xB7 confirmedCount=${confirmedCount} \xB7 threshold=${threshold}`
-      });
+      await scheduleBroadcast(mailer, String(req.params.slug), { scheduledAt, confirmedCount, respectRecipientTimezone }, req.actor);
       return res.json({ ok: true });
     })
   );
   r.post(
     "/broadcasts/:slug/cancel",
-    asyncHandler(async (req, res) => {
-      const b = await c.broadcasts.findOne({ slug: req.params.slug });
-      if (!b) return res.status(404).json({ error: "not_found" });
-      await c.broadcasts.updateOne({ _id: b._id }, { $set: { status: "cancelled", updatedAt: /* @__PURE__ */ new Date() } });
-      await mailer.audit({
-        actor: req.actor,
-        action: "broadcast.cancel",
-        resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug }
-      });
+    broadcastHandler(async (req, res) => {
+      await cancelBroadcast(mailer, String(req.params.slug), req.actor);
       return res.json({ ok: true });
     })
   );
@@ -8151,35 +9187,15 @@ async function computeTemplateStats(mailer, slugFilter) {
   }
   return out;
 }
-function emptyBroadcastStats() {
-  return { delivered: 0, opened: 0, clicked: 0, bounced: 0 };
-}
-async function computeBroadcastStats(mailer, idFilter) {
-  const out = /* @__PURE__ */ new Map();
-  const match = { broadcastId: { $ne: null } };
-  if (idFilter) match.broadcastId = idFilter;
-  const rows = await mailer.collections.sends.aggregate([
-    { $match: match },
-    {
-      $group: {
-        _id: "$broadcastId",
-        delivered: { $sum: { $cond: [{ $eq: ["$status", "delivered"] }, 1, 0] } },
-        opened: { $sum: { $cond: [{ $ifNull: ["$openedAt", false] }, 1, 0] } },
-        clicked: { $sum: { $cond: [{ $ifNull: ["$firstClickAt", false] }, 1, 0] } },
-        bounced: { $sum: { $cond: [{ $eq: ["$status", "bounced"] }, 1, 0] } }
+function broadcastHandler(fn) {
+  return (req, res, next) => {
+    fn(req, res, next).catch((err) => {
+      if (err instanceof BroadcastOperationError) {
+        return res.status(err.status).json({ error: err.code, message: err.message, ...err.details ?? {} });
       }
-    }
-  ]).toArray();
-  for (const row of rows) {
-    if (!row._id) continue;
-    out.set(String(row._id), {
-      delivered: row.delivered,
-      opened: row.opened,
-      clicked: row.clicked,
-      bounced: row.bounced
+      next(err);
     });
-  }
-  return out;
+  };
 }
 
 // src/server/api/wrap.ts
@@ -8556,7 +9572,16 @@ function unitToMs2(value, unit) {
 }
 
 // src/server/api/agent.ts
-var VERSION = "0.17.1" ;
+var VERSION = "0.19.0" ;
+var broadcastCountSchema = zod.z.object({
+  recipientCap: zod.z.number().int().positive().max(1e7).nullable().optional()
+});
+var broadcastTestSendSchema = zod.z.object({
+  contactIds: zod.z.array(zod.z.string().min(1).max(256)).min(1).max(10),
+  vars: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+  /** 'queue' leaves the sends queued for the worker instead of dispatching inline. */
+  dispatch: zod.z.enum(["now", "queue"]).optional()
+});
 var agentTagsInputSchema = zod.z.object({
   add: zod.z.array(zod.z.string().min(1).max(128)).max(25).default([]),
   remove: zod.z.array(zod.z.string().min(1).max(128)).max(25).default([])
@@ -8821,7 +9846,7 @@ function createAgentRouter(mailer, opts) {
       }
       const now = /* @__PURE__ */ new Date();
       const publishedBy = input.publishedBy ?? actorOf(req);
-      const set = {
+      const set2 = {
         slug,
         name: input.name,
         description: input.description,
@@ -8852,7 +9877,7 @@ function createAgentRouter(mailer, opts) {
       const result = await c.templates.updateOne(
         { slug },
         {
-          $set: set,
+          $set: set2,
           $setOnInsert: {
             createdAt: now,
             stats: { sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0, lastSentAt: null }
@@ -9234,6 +10259,152 @@ function createAgentRouter(mailer, opts) {
       res.json({ contact: { externalId: contact.externalId, email: contact.email }, removed, subscription });
     })
   );
+  router.get(
+    "/broadcasts",
+    wrap2(async (_req, res) => {
+      const docs = await c.broadcasts.find().sort({ createdAt: -1 }).limit(200).toArray();
+      const stats = await computeBroadcastStats(mailer);
+      res.json(docs.map((b) => ({ ...broadcastSummary(b), stats: stats.get(String(b._id)) ?? emptyBroadcastStats() })));
+    })
+  );
+  router.get(
+    "/broadcasts/:slug",
+    wrap2(async (req, res) => {
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const [statsMap, statusBreakdown] = await Promise.all([
+        computeBroadcastStats(mailer, b._id),
+        broadcastStatusBreakdown(mailer, b._id)
+      ]);
+      const stats = statsMap.get(String(b._id)) ?? emptyBroadcastStats();
+      res.json({
+        broadcast: broadcastSummary(b),
+        stats,
+        statusBreakdown,
+        capProgress: capProgress(b, stats),
+        stopRules: stopRuleStatus(mailer, b, stats)
+      });
+    })
+  );
+  router.post(
+    "/broadcasts",
+    wrap2(async (req, res) => {
+      const parsed = agentCreateBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await createBroadcast(mailer, parsed.data, actorOf(req), { requireSubscribed: true, strictSegment: true });
+      res.status(201).json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.patch(
+    "/broadcasts/:slug",
+    wrap2(async (req, res) => {
+      const parsed = agentPatchBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await patchBroadcast(mailer, String(req.params.slug), parsed.data, actorOf(req), { requireSubscribed: true, strictSegment: true });
+      res.json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/schedule",
+    wrap2(async (req, res) => {
+      const parsed = agentScheduleBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await scheduleBroadcast(mailer, String(req.params.slug), parsed.data, actorOf(req), {
+        requireSubscribed: true,
+        requireExactCount: true
+      });
+      res.json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/count",
+    wrap2(async (req, res) => {
+      const parsed = broadcastCountSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const count2 = await countRecipients(
+        mailer,
+        b,
+        void 0,
+        parsed.data.recipientCap !== void 0 ? { recipientCap: parsed.data.recipientCap } : {}
+      );
+      res.json({
+        slug: b.slug,
+        status: b.status,
+        ...count2,
+        confirmationThreshold: mailer.config.broadcastConfirmationThreshold
+      });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/test-send",
+    wrap2(async (req, res) => {
+      const parsed = broadcastTestSendSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const tpl = await loadBroadcastTemplate(mailer, b);
+      if (!tpl.body?.html && !tpl.body?.mjml) {
+        return res.status(409).json({ error: "not_published", message: `template "${tpl.slug}" has no published body` });
+      }
+      const contacts = [];
+      for (const id of parsed.data.contactIds) {
+        const contact = await loadContact(res, id);
+        if (!contact) return;
+        if (!guardTestContact(res, contact)) return;
+        contacts.push(contact);
+      }
+      const ctx = mailer.getRunnerContext();
+      const dispatchNow = parsed.data.dispatch !== "queue";
+      const sends = [];
+      for (const contact of contacts) {
+        const { sendId } = await mailer.sendOneOff({
+          templateSlug: tpl.slug,
+          externalId: contact.externalId,
+          dedupeKey: `broadcast-test:${b._id}:${contact.externalId}:${crypto2__default.default.randomUUID()}`,
+          vars: parsed.data.vars
+        });
+        const _id = new mongodb.ObjectId(sendId);
+        await c.sends.updateOne({ _id }, { $set: { manualSendBy: `broadcast-test:${b.slug}` } });
+        if (dispatchNow) await dispatchSend(_id, ctx);
+        const row = await c.sends.findOne({ _id });
+        if (row) sends.push(sendSummary(row));
+      }
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.broadcast.test-send",
+        resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+        diffSummary: `template=${tpl.slug} to=${contacts.map((x) => x.email).join(", ")} dispatch=${dispatchNow ? "now" : "queue"}`
+      });
+      res.status(201).json({ broadcast: { slug: b.slug, status: b.status }, templateSlug: tpl.slug, dispatched: dispatchNow, sends });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/pause",
+    wrap2(async (req, res) => {
+      const parsed = agentPauseBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const out = await pauseBroadcastByOperator(mailer, String(req.params.slug), parsed.data, actorOf(req));
+      res.json({ broadcast: broadcastSummary(out.broadcast), heldSends: out.heldSends });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/resume",
+    wrap2(async (req, res) => {
+      const parsed = agentResumeBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await resumeBroadcast(mailer, String(req.params.slug), parsed.data, actorOf(req), {
+        requireSubscribed: true,
+        requireExactCount: true
+      });
+      res.json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/cancel",
+    wrap2(async (req, res) => {
+      const out = await cancelBroadcast(mailer, String(req.params.slug), actorOf(req));
+      res.json({ broadcast: broadcastSummary(out.broadcast), cancelledSends: out.cancelledSends });
+    })
+  );
   router.post(
     "/tick",
     wrap2(async (_req, res) => {
@@ -9323,6 +10494,9 @@ function createAgentRouter(mailer, opts) {
     if (err instanceof FlowOperationError) {
       return res.status(err.status).json({ error: err.code, message: err.message });
     }
+    if (err instanceof BroadcastOperationError) {
+      return res.status(err.status).json({ error: err.code, message: err.message, ...err.details ?? {} });
+    }
     if (err?.name === "ZodError") {
       return res.status(400).json({ error: "validation_failed", issues: err.issues });
     }
@@ -9691,6 +10865,9 @@ function runSummary(r) {
     history: r.history
   };
 }
+function zodMessage(error) {
+  return error.issues.map((i) => `${i.path.join(".") || "body"}: ${i.message}`).join("; ");
+}
 function objectOrUndefined(v) {
   return v && typeof v === "object" && !Array.isArray(v) ? v : void 0;
 }
@@ -9729,6 +10906,16 @@ var ENDPOINTS = [
   { method: "POST", path: "/contacts/:externalId/unsubscribe", summary: "Unsubscribe a test contact (marketing scope).", testContactsOnly: true },
   { method: "POST", path: "/contacts/:externalId/tags", summary: "Add or remove tags on a test contact ({add: [...], remove: [...]}), so a gated flow lets it through.", testContactsOnly: true },
   { method: "POST", path: "/contacts/:externalId/reset", summary: "Delete a test contact's runs, sends, events ({events: [names]} to narrow) and suppressions, then resubscribe. Each part can be turned off with false.", testContactsOnly: true },
+  { method: "GET", path: "/broadcasts", summary: "Every broadcast (newest first, up to 200) with its stats." },
+  { method: "GET", path: "/broadcasts/:slug", summary: "One broadcast: stats (delivered, bounced hard/soft, complained, unsubscribed, opened, clicked, with rates), a per-status count of its send rows, pause reason and cap progress." },
+  { method: "POST", path: "/broadcasts", summary: "Create a draft broadcast: {slug, name, templateSlug, segmentDefinition?, respectRecipientTimezone?}." },
+  { method: "PATCH", path: "/broadcasts/:slug", summary: "Edit a draft broadcast (name, templateSlug, segmentDefinition, respectRecipientTimezone). 409 once it has left draft." },
+  { method: "POST", path: "/broadcasts/:slug/count", summary: "The true recipient count: host filter, post-filters, suppression, minus contacts already sent to, within the cap ({recipientCap} previews another cap). Schedule wants recipientCount; resume wants recipientCount + heldSends." },
+  { method: "POST", path: "/broadcasts/:slug/schedule", summary: "Schedule a draft: {scheduledAt, confirmedCount, respectRecipientTimezone?}. 409 count_mismatch unless confirmedCount equals POST /broadcasts/:slug/count \u2192 recipientCount. The segment must be limited to subscribed contacts." },
+  { method: "POST", path: "/broadcasts/:slug/test-send", summary: `Send the broadcast's template, rendered as each of {contactIds} (test contacts only), through the real pipeline without scheduling it; not counted in the broadcast's stats. {dispatch: "queue"} to leave them queued.`, testContactsOnly: true },
+  { method: "POST", path: "/broadcasts/:slug/pause", summary: "Pause a sending broadcast by hand ({reason?}); its queued sends are held." },
+  { method: "POST", path: "/broadcasts/:slug/resume", summary: "Re-open a paused broadcast: {recipientCap?, stopRules?, confirmedCount}. Next wave: raise recipientCap (null = no cap). confirmedCount = /count recipientCount + heldSends. A stop-rule pause re-opens only when the (adjusted) rules no longer fire; a circuit-breaker pause only once the breaker is reset." },
+  { method: "POST", path: "/broadcasts/:slug/cancel", summary: "Cancel a broadcast." },
   { method: "POST", path: "/tick", summary: "Run the runner tick now (trigger scan, sweeps, outbox, webhook backlog)." },
   { method: "GET", path: "/webhooks/status", summary: "Provider webhook ingest: last event received, counts by type (24h), unprocessed backlog." },
   { method: "GET", path: "/status", summary: "One document with setup checks, health, every flow (enabled, version, watermark, gate, active runs), every template, and 24h counts." }
@@ -9969,12 +11156,15 @@ function createPublicRouter(mailer, opts = {}) {
         return;
       }
       const now = /* @__PURE__ */ new Date();
+      await mailer.collections.sends.updateOne(
+        { _id: sendId, status: "sent" },
+        { $set: { status: "delivered" } }
+      );
       await mailer.collections.sends.updateOne(
         { _id: sendId },
         {
           $set: {
-            openedAt: send.openedAt ?? now,
-            status: "delivered"
+            openedAt: send.openedAt ?? now
           },
           $inc: { openCount: 1 },
           // Per-open user agent, so `hasOpenedExcludingBots` has a signal to
@@ -10113,6 +11303,11 @@ function createPublicRouter(mailer, opts = {}) {
       }
     }
     res.status(200).type("html").send("<!doctype html><html><body><p>You are unsubscribed.</p></body></html>");
+    if (!dbError && decoded.sendId) {
+      void attributeUnsubscribeToSend(mailer.getRunnerContext(), decoded.sendId, decoded.email).catch((err) => {
+        logger.warn?.({ err, sendId: decoded.sendId }, "mailery: unsubscribe attribution failed");
+      });
+    }
   }));
   router.get("/confirm-doi/:token", wrap(logger, async (req, res) => {
     const token = req.params.token;
@@ -10444,7 +11639,7 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION2 = "0.17.1" ;
+var VERSION2 = "0.19.0" ;
 
 exports.DEDUPE_POLICIES = DEDUPE_POLICIES;
 exports.DEFAULT_BOT_UA_RE = DEFAULT_BOT_UA_RE;