@hogsend/engine 0.5.0 → 0.7.0

package/src/worker.ts

@@ -1,5 +1,8 @@
 import type { DefinedBucket } from "./buckets/define-bucket.js";
-import { selectBucketTasks } from "./buckets/registry.js";
+import {
+  selectBucketReactionTasks,
+  selectBucketTasks,
+} from "./buckets/registry.js";
 import type { HogsendClient } from "./container.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
 import { selectJourneyTasks } from "./journeys/registry.js";
@@ -14,6 +17,10 @@ import {
 import { bucketReconcileTask } from "./workflows/bucket-reconcile.js";
 import { checkAlertsTask } from "./workflows/check-alerts.js";
 import { importContactsTask } from "./workflows/import-contacts.js";
+import {
+  reapStuckCampaignsTask,
+  sendCampaignTask,
+} from "./workflows/send-campaign.js";
 import { sendEmailTask } from "./workflows/send-email.js";
 
 export interface CreateWorkerOptions {
@@ -46,15 +53,27 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
   // reconcile cron (bucketReconcileTask) is ALWAYS registered in baseWorkflows
   // below (Section 10), regardless of fastExpiry.
   const bucketTasks = selectBucketTasks(opts.buckets ?? [], enabledBuckets);
+  // Reaction journeys generated by `bucket.on()` desugar to real durable tasks.
+  // They are bucket-owned, so they are gated by ENABLED_BUCKETS (NOT
+  // ENABLED_JOURNEYS) and wired directly here rather than via the journeys[]
+  // array (Section 9). Throws loudly on a reaction-id collision.
+  const bucketReactionTasks = selectBucketReactionTasks(
+    opts.buckets ?? [],
+    enabledBuckets,
+    journeys.map((j) => j.meta.id),
+  );
 
   const baseWorkflows = [
     sendEmailTask,
     importContactsTask,
+    sendCampaignTask,
+    reapStuckCampaignsTask,
     checkAlertsTask,
     bucketReconcileTask,
     bucketBackfillTask,
     ...journeyTasks,
     ...bucketTasks,
+    ...bucketReactionTasks,
   ];
   const workflows = [
     ...baseWorkflows,
@@ -94,8 +113,12 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
       client: container,
       journeyTasks: journeyTasks.length,
       bucketTasks: bucketTasks.length,
+      bucketReactionTasks: bucketReactionTasks.length,
       builtinTasks:
-        baseWorkflows.length - journeyTasks.length - bucketTasks.length,
+        baseWorkflows.length -
+        journeyTasks.length -
+        bucketTasks.length -
+        bucketReactionTasks.length,
     });
 
     // Publish liveness so the API + Studio can show "worker connected"

package/src/workflows/bucket-backfill.ts

@@ -15,7 +15,7 @@ import {
   importJobs,
   userEvents,
 } from "@hogsend/db";
-import { and, eq, gt, gte, inArray, isNull, sql } from "drizzle-orm";
+import { and, eq, gt, gte, inArray, isNull, max, sql } from "drizzle-orm";
 import {
   computeExpiresAt,
   computeMaxDwellAt,
@@ -24,6 +24,7 @@ import {
 import { getBucketRegistrySingleton } from "../buckets/registry-singleton.js";
 import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
 import { emitBucketTransition } from "../lib/bucket-emit.js";
+import { contactKeySql } from "../lib/contacts.js";
 import { hatchet } from "../lib/hatchet.js";
 import type { Logger } from "../lib/logger.js";
 import { createLogger } from "../lib/logger.js";
@@ -209,6 +210,18 @@ async function backfillJoins(opts: {
   // unset value would never be force-left.
   const maxDwellAt = computeMaxDwellAt(bucket);
 
+  // Historical dwell anchor (Section 6.3 / LOCKED DECISION 1). For a
+  // windowed/event criterion the anchor is `max(occurredAt)` of the qualifying
+  // event = "when they became dormant" (e.g. went-dormant = the last
+  // `app_opened`). The dwell gate reads `coalesce(dwellAnchorAt, enteredAt)`, so
+  // backfilled members start the dwell clock at their real historical instant
+  // rather than the deploy-time `enteredAt`. Shapes with no cheap per-matcher
+  // timestamp leave the anchor NULL (fall back to enteredAt). The live join path
+  // (handleJoin) never sets dwellAnchorAt, so post-deploy joins clock from their
+  // real enteredAt. Computed batched per chunk (one GROUP BY max(occurredAt),
+  // mirroring the priorCounts GROUP BY) — never per-user serial queries.
+  const anchorEvent = resolveDwellAnchorEvent(criteria);
+
   // Fix C (DEFERRED): backfilled fastExpiry rows are NOT armed with a
   // bucket:arm-expiry durable timer here — they are picked up by the next cron
   // sweep instead (reconcileBucketLeaves / reconcileBucketTtlLeaves are the
@@ -219,16 +232,20 @@ async function backfillJoins(opts: {
   for (let i = 0; i < matcherIds.length; i += BATCH_SIZE) {
     const chunk = matcherIds.slice(i, i + BATCH_SIZE);
 
-    // userEmail backfilled from the contacts row where available.
+    // userEmail backfilled from the contacts row where available. The chunk
+    // holds the RESOLVED key (coalesce(external_id, anonymous_id, id)) — for an
+    // email-only / anonymous contact that is the anonymous_id or the uuid id, NOT
+    // the (null) external_id. Looking up by `contacts.externalId` would miss
+    // those rows and write a NULL userEmail despite the contact having an email,
+    // so we key the lookup + the map by the SAME coalesce expression the chunk
+    // carries (matches reconcileBucketJoins, which reads userId + email off one
+    // contacts row).
+    const resolvedKey = contactKeySql();
     const chunkContacts = await db
-      .select({ externalId: contacts.externalId, email: contacts.email })
+      .select({ userKey: resolvedKey, email: contacts.email })
       .from(contacts)
-      .where(
-        and(inArray(contacts.externalId, chunk), isNull(contacts.deletedAt)),
-      );
-    const emailByUser = new Map(
-      chunkContacts.map((c) => [c.externalId, c.email]),
-    );
+      .where(and(inArray(resolvedKey, chunk), isNull(contacts.deletedAt)));
+    const emailByUser = new Map(chunkContacts.map((c) => [c.userKey, c.email]));
 
     // Fix A: entryCount = 1 + prior memberships for each (user, bucket), the
     // same monotonic ordinal the live join computes (check-membership.ts). On a
@@ -253,6 +270,35 @@ async function backfillJoins(opts: {
       priorCounts.map((r) => [r.userId, Number(r.cnt)]),
     );
 
+    // Batched dwell-anchor derivation (LOCKED DECISION 1): one GROUP BY
+    // max(occurredAt) over the qualifying event for THIS chunk, mirroring the
+    // priorCounts GROUP BY above (never per-user serial queries). Only computed
+    // when the criteria shape exposes a cheap per-matcher anchor event; an empty
+    // map leaves dwellAnchorAt NULL → the dwell gate falls back to enteredAt.
+    let anchorByUser = new Map<string, Date>();
+    if (anchorEvent != null) {
+      const anchors = await db
+        .select({
+          userId: userEvents.userId,
+          lastAt: max(userEvents.occurredAt),
+        })
+        .from(userEvents)
+        .where(
+          and(
+            eq(userEvents.event, anchorEvent),
+            inArray(userEvents.userId, chunk),
+          ),
+        )
+        .groupBy(userEvents.userId);
+      anchorByUser = new Map(
+        anchors
+          .filter(
+            (r): r is { userId: string; lastAt: Date } => r.lastAt != null,
+          )
+          .map((r) => [r.userId, r.lastAt]),
+      );
+    }
+
     const rows = chunk.map((userId) => ({
       userId,
       userEmail: emailByUser.get(userId) ?? null,
@@ -262,6 +308,8 @@ async function backfillJoins(opts: {
       entryCount: 1 + (priorByUser.get(userId) ?? 0),
       expiresAt: computeExpiresAt(bucket),
       maxDwellAt,
+      // Historical dwell anchor where derivable; NULL otherwise (→ enteredAt).
+      dwellAnchorAt: anchorByUser.get(userId) ?? null,
       lastEvaluatedAt: new Date(),
     }));
 
@@ -365,6 +413,7 @@ async function reevalLeaves(opts: {
         userEmail: row.userEmail,
         epoch: row.entryCount,
         source: "backfill",
+        reason: "criteria",
       });
     }
     leftCount += flipped.length;
@@ -412,7 +461,9 @@ async function selectEventMatchers(
       .as("present");
 
     const rows = await db
-      .select({ userId: contacts.externalId })
+      .select({
+        userId: contactKeySql(),
+      })
       .from(contacts)
       .innerJoin(everFired, eq(everFired.userId, contacts.externalId))
       .leftJoin(present, eq(present.userId, contacts.externalId))
@@ -452,12 +503,15 @@ async function selectEventMatchers(
  * a per-contact `evaluateCondition` loop over live contacts. Property
  * sub-conditions evaluate against the contact's merged properties.
  *
- * KEYSET PAGINATION by `contacts.externalId` in BATCH_SIZE pages (mirrors
- * reconcileBucketJoins' `externalId asc` paging): each page selects
- * `WHERE externalId > :cursor ORDER BY externalId ASC LIMIT BATCH_SIZE`,
- * evaluates the criteria per contact, then advances the cursor to the last
- * externalId of the page — repeating until a short page ends the scan. The whole
- * contacts table is never held in memory at once.
+ * KEYSET PAGINATION by `contacts.id` in BATCH_SIZE pages: each page selects
+ * `WHERE id > :cursor ORDER BY id ASC LIMIT BATCH_SIZE`, evaluates the criteria
+ * per contact, then advances the cursor to the last `id` of the page — repeating
+ * until a short page ends the scan. The whole contacts table is never held in
+ * memory at once. Paging on `id` (the non-null unique PK) — NOT `external_id`,
+ * which is nullable (email-only / anonymous contacts) and would drop every
+ * null-external_id row and order NULLs unstably. (reconcileBucketJoins is not a
+ * keyset scan — it relies on matchers dropping out as they become active
+ * members — so this no longer mirrors it.)
  */
 async function selectCompositeMatchers(
   db: Database,
@@ -469,17 +523,18 @@ async function selectCompositeMatchers(
   for (;;) {
     const page = await db
       .select({
-        externalId: contacts.externalId,
+        id: contacts.id,
+        userId: contactKeySql(),
         properties: contacts.properties,
       })
       .from(contacts)
       .where(
         and(
           isNull(contacts.deletedAt),
-          cursor != null ? gt(contacts.externalId, cursor) : undefined,
+          cursor != null ? gt(contacts.id, cursor) : undefined,
         ),
       )
-      .orderBy(sql`${contacts.externalId} asc`)
+      .orderBy(sql`${contacts.id} asc`)
       .limit(BATCH_SIZE);
 
     for (const contact of page) {
@@ -487,23 +542,68 @@ async function selectCompositeMatchers(
         condition: criteria,
         ctx: {
           db,
-          userId: contact.externalId,
+          userId: contact.userId,
           journeyContext:
             (contact.properties as Record<string, unknown> | null) ?? {},
         },
       });
-      if (isMember) matchers.push(contact.externalId);
+      if (isMember) matchers.push(contact.userId);
     }
 
     // A short page (fewer than a full batch) means the scan is exhausted.
     if (page.length < BATCH_SIZE) break;
-    cursor = page[page.length - 1]?.externalId ?? null;
+    cursor = page[page.length - 1]?.id ?? null;
     if (cursor == null) break;
   }
 
   return matchers;
 }
 
+/**
+ * Resolve the event whose `max(occurredAt)` is the historical dwell anchor for a
+ * backfilled member (LOCKED DECISION 1 / Section 6.3) — "when they became
+ * dormant". Returns an event name only for the windowed/event shapes that expose
+ * a cheap per-matcher timestamp; `null` for everything else (the anchor stays
+ * NULL and the dwell gate falls back to `enteredAt`):
+ *
+ *   - a single windowed `event` criterion → its `eventName` (the last qualifying
+ *     occurrence is the window boundary, e.g. the last `app_opened`).
+ *   - the lapsed-active composite `all(event(X).exists(),
+ *     event(X).within(W).not_exists())` → event X (the flagship went-dormant
+ *     shape; the last X is when they lapsed).
+ *
+ * Other shapes (property/count composites, OR-of-absence, multi-event) have no
+ * single cheap per-matcher timestamp, so they keep a NULL anchor.
+ */
+function resolveDwellAnchorEvent(criteria: ConditionEval): string | null {
+  if (criteria.type === "event") {
+    return criteria.within != null ? criteria.eventName : null;
+  }
+  // Lapsed-active composite — two legs on the SAME event X: an unwindowed
+  // exists() anchor and a windowed not_exists() leg. Mirrors
+  // isLapsedActiveComposite in bucket-reconcile.ts.
+  if (
+    criteria.type === "composite" &&
+    criteria.operator === "and" &&
+    criteria.conditions.length === 2
+  ) {
+    const existsLeg = criteria.conditions.find(
+      (c) => c.type === "event" && c.check === "exists" && c.within == null,
+    );
+    const notExistsLeg = criteria.conditions.find(
+      (c) => c.type === "event" && c.check === "not_exists" && c.within != null,
+    );
+    if (
+      existsLeg?.type === "event" &&
+      notExistsLeg?.type === "event" &&
+      existsLeg.eventName === notExistsLeg.eventName
+    ) {
+      return notExistsLeg.eventName;
+    }
+  }
+  return null;
+}
+
 /**
  * Upsert the bucket's current criteria fingerprint onto `bucket_configs` (Section
  * 6.6 B). Mirrors the admin enable/disable onConflictDoUpdate target.

package/src/workflows/bucket-reconcile.ts

@@ -7,6 +7,7 @@ import {
   durationToMs,
   evaluateCondition,
 } from "@hogsend/core";
+import type { JourneyMeta } from "@hogsend/core/types";
 import {
   bucketConfigs,
   bucketMemberships,
@@ -27,6 +28,7 @@ import {
   or,
   sql,
 } from "drizzle-orm";
+import type { BucketLeaveReason } from "../buckets/bucket-reactions.js";
 import { shouldEmitJoin } from "../buckets/check-membership.js";
 import {
   BUCKET_EVENT_PREFIX,
@@ -39,6 +41,7 @@ import {
 import { getBucketRegistrySingleton } from "../buckets/registry-singleton.js";
 import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
 import { emitBucketTransition } from "../lib/bucket-emit.js";
+import { contactKeySql } from "../lib/contacts.js";
 import { hatchet } from "../lib/hatchet.js";
 import type { Logger } from "../lib/logger.js";
 import { createLogger } from "../lib/logger.js";
@@ -97,12 +100,21 @@ export const bucketReconcileTask = hatchet.task({
       // kind:"manual" buckets are NEVER auto-recomputed (early-continue).
       if (bucket.kind === "manual" || !bucket.criteria) continue;
 
-      // Process a bucket here iff a clock can flip its membership: a TIME-BASED
-      // criteria window (criteria-driven leaves/joins) OR an unconditional
-      // `maxDwell` TTL (membership-age-driven leaves). timeBased is honoured
-      // explicitly OR inferred from a `within` window.
+      // Process a bucket here iff a clock can flip its membership OR fire a
+      // membership-age dwell: a TIME-BASED criteria window (criteria-driven
+      // leaves/joins), an unconditional `maxDwell` TTL (membership-age-driven
+      // leaves), OR a `dwell` reaction (membership-age-driven fire). timeBased is
+      // honoured explicitly OR inferred from a `within` window. The dwell-only
+      // bucket falls through and runs ONLY the dwell pass (the criteria pass is
+      // behind `if (timeBased)`, the TTL pass behind `if (bucket.maxDwell)`).
       const timeBased = isTimeBased(bucket);
-      if (!timeBased && !bucket.maxDwell) continue;
+      const dwellReactions = journeyRegistry
+        .getAll()
+        .filter(
+          (j) => j.sourceBucketId === bucket.id && j.reactionKind === "dwell",
+        );
+      const hasDwell = dwellReactions.length > 0;
+      if (!timeBased && !bucket.maxDwell && !hasDwell) continue;
 
       try {
         if (timeBased) {
@@ -145,6 +157,21 @@ export const bucketReconcileTask = hatchet.task({
             bucket,
           });
         }
+
+        // Dwell pass — runs AFTER the TTL pass (ordering is load-bearing: a
+        // member force-left by maxDwell earlier this iteration is status='left'
+        // here, so the dwell scan's status='active' filter excludes it). Fires
+        // `bucket:dwell:<id>:<label>` over the continuously-dwelling active
+        // population at cron resolution (Section 6.4–6.6).
+        if (hasDwell) {
+          reconciled += await reconcileBucketDwell({
+            db,
+            logger,
+            journeyRegistry,
+            bucket,
+            dwellReactions,
+          });
+        }
       } catch (err) {
         logger.error("Bucket reconcile failed", {
           bucketId: bucket.id,
@@ -255,6 +282,8 @@ export const bucketExpiryTask = hatchet.durableTask({
       userEmail: input.userEmail,
       epoch: flipped.entryCount,
       source: "reconcile",
+      // Fast-expiry is a criteria re-confirm leave (Section 6.7).
+      reason: "criteria",
     });
 
     return { status: "left", rowId: flipped.id };
@@ -287,6 +316,7 @@ async function reconcileBucketLeaves(opts: {
       journeyRegistry,
       bucket,
       userIds: leaverIds,
+      reason: "criteria",
     });
   }
 
@@ -421,7 +451,14 @@ async function reconcileCompositeLeaves(opts: {
   }
 
   if (leaverIds.length === 0) return 0;
-  return bulkLeave({ db, logger, journeyRegistry, bucket, userIds: leaverIds });
+  return bulkLeave({
+    db,
+    logger,
+    journeyRegistry,
+    bucket,
+    userIds: leaverIds,
+    reason: "criteria",
+  });
 }
 
 /**
@@ -462,6 +499,7 @@ async function reconcileBucketTtlLeaves(opts: {
     journeyRegistry,
     bucket,
     userIds: expired.map((r) => r.userId),
+    reason: "maxDwell",
   });
 }
 
@@ -478,8 +516,10 @@ async function bulkLeave(opts: {
   journeyRegistry: ReturnType<typeof getJourneyRegistrySingleton>;
   bucket: BucketMeta;
   userIds: string[];
+  /** Why these members leave — TTL passes "maxDwell", criteria passes "criteria". */
+  reason: BucketLeaveReason;
 }): Promise<number> {
-  const { db, logger, journeyRegistry, bucket, userIds } = opts;
+  const { db, logger, journeyRegistry, bucket, userIds, reason } = opts;
 
   const dwellMs = bucket.minDwell ? durationToMs(bucket.minDwell) : 0;
   const dwellCutoff = dwellMs > 0 ? new Date(Date.now() - dwellMs) : null;
@@ -524,12 +564,171 @@ async function bulkLeave(opts: {
       userEmail: row.userEmail,
       epoch: row.entryCount,
       source: "reconcile",
+      reason,
     });
   }
 
   return flipped.length;
 }
 
+/**
+ * Dwell pass for one bucket (Section 6.4–6.6). Fires `bucket:dwell:<id>:<label>`
+ * over the EXISTING continuously-dwelling active population at cron resolution —
+ * its unique value over `on("enter") + ctx.sleep`. Idempotent across sweeps,
+ * interoperable with maxDwell/fastExpiry, and routed through
+ * `emitBucketTransition` (NOT a raw push) for `userEvents`/exitOn/history/analytics
+ * parity (Section 6.1):
+ *
+ *  - PUSH FIRST (at-least-once; the deterministic idempotencyKey + the userEvents
+ *    dedup absorb a same-sweep retry), THEN stamp `dwellState` (the inter-sweep
+ *    "already fired this membership" gate). The stamp's `status='active'` clause
+ *    makes the leave/fastExpiry interop correct (a row flipped to `left` between
+ *    SELECT and UPDATE no-ops).
+ *  - The dwell clock is `coalesce(dwellAnchorAt, enteredAt)` — backfilled members
+ *    use their derived historical anchor (LOCKED DECISION 1), live joins use
+ *    enteredAt (anchor NULL).
+ *  - Candidates are ordered `lastEvaluatedAt asc nulls first` (oldest-served-first)
+ *    so a busy `every` bucket cannot starve members past BATCH_SIZE; the stamp
+ *    bumps `lastEvaluatedAt`, advancing the cursor. Hitting BATCH_SIZE is logged
+ *    once per sweep (visibility, not silent).
+ *  - First-deploy quiet window: reuse `firstTimeBackfillIncomplete` so the
+ *    pre-existing/backfilled population is not blasted before the first-time
+ *    backfill has settled.
+ *
+ * `every` is fires-at-most-once-per-sweep, coalescing (one catch-up fire after a
+ * multi-interval outage); `dwellCount` is the deterministic interval ordinal
+ * `floor((sweepInstant - anchor) / offsetMs)` (gap-stable, NOT a fire count). For
+ * `after` the ordinal is always 1 (one-shot).
+ */
+async function reconcileBucketDwell(opts: {
+  db: Database;
+  logger: Logger;
+  journeyRegistry: ReturnType<typeof getJourneyRegistrySingleton>;
+  bucket: BucketMeta;
+  dwellReactions: JourneyMeta[];
+}): Promise<number> {
+  const { db, logger, journeyRegistry, bucket, dwellReactions } = opts;
+
+  // First-deploy quiet window: do not blast the pre-existing/backfilled
+  // population before the first-time backfill has settled (reuse the guard).
+  if (await firstTimeBackfillIncomplete(db, bucket)) return 0;
+
+  // Captured once per invocation and reused for the ordinal. The ordinal is
+  // floor((sweepInstant - anchor) / offsetMs), so it is grid-quantized: a Hatchet
+  // retry (a fresh fn() invocation, seconds–minutes later) lands in the SAME
+  // interval window and recomputes the SAME ordinal → SAME idempotencyKey →
+  // absorbed by the userEvents dedup. `after` is always ordinal 1 (fully stable).
+  // Residual edge: an `every` retry that straddles an interval boundary yields a
+  // new ordinal and thus one extra dwell fire — bounded to a single duplicate by
+  // the key, and only possible for sub-retry-window intervals. Documented, not
+  // load-bearing for the common (hours/days) intervals.
+  const sweepInstant = Date.now();
+  let fired = 0;
+
+  for (const reaction of dwellReactions) {
+    const schedule = reaction.dwellSchedule;
+    if (!schedule) continue;
+    const { label, after, every } = schedule;
+    const offsetMs = after ?? every;
+    if (offsetMs == null) continue;
+    const cutoff = new Date(sweepInstant - offsetMs);
+
+    // Continuous-member gate. coalesce(dwellAnchorAt, enteredAt) is the dwell
+    // clock. Oldest-served-first (Section 6.5).
+    const candidates = await db
+      .select({
+        id: bucketMemberships.id,
+        userId: bucketMemberships.userId,
+        userEmail: bucketMemberships.userEmail,
+        entryCount: bucketMemberships.entryCount,
+        anchor: sql<Date>`coalesce(${bucketMemberships.dwellAnchorAt}, ${bucketMemberships.enteredAt})`,
+        dwellState: bucketMemberships.dwellState,
+      })
+      .from(bucketMemberships)
+      .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
+      .where(
+        and(
+          eq(bucketMemberships.bucketId, bucket.id),
+          eq(bucketMemberships.status, "active"),
+          isNull(bucketMemberships.deletedAt),
+          isNull(contacts.deletedAt),
+          // Fold the comparison into the fragment with an explicit cast: a JS
+          // Date passed to lte() against a raw sql`coalesce(...)` fragment has no
+          // column type to drive param encoding, so the pg driver throws on the
+          // Date (and the per-bucket try/catch would silently swallow it → 0
+          // dwell fires). Binding the ISO string + ::timestamptz is well-typed.
+          sql`coalesce(${bucketMemberships.dwellAnchorAt}, ${bucketMemberships.enteredAt}) <= ${cutoff.toISOString()}::timestamptz`,
+        ),
+      )
+      .orderBy(sql`${bucketMemberships.lastEvaluatedAt} asc nulls first`)
+      .limit(BATCH_SIZE);
+
+    if (candidates.length >= BATCH_SIZE) {
+      logger.warn("Bucket dwell pass bounded to BATCH_SIZE/tick", {
+        bucketId: bucket.id,
+        label,
+        batchSize: BATCH_SIZE,
+      });
+    }
+
+    for (const m of candidates) {
+      const state = (m.dwellState ?? {}) as Record<string, string>;
+      const lastFired = state[label] ? Date.parse(state[label]) : null;
+      const anchorMs = new Date(m.anchor).getTime();
+
+      if (after != null) {
+        // one-shot: already fired for this membership → skip.
+        if (lastFired != null) continue;
+      } else {
+        // every: not yet due since the last fire (or the anchor).
+        const since = lastFired ?? anchorMs;
+        if (sweepInstant - since < offsetMs) continue;
+      }
+
+      // Deterministic per (membership, sweepInstant) so a retry recomputes it.
+      const ordinal =
+        after != null ? 1 : Math.floor((sweepInstant - anchorMs) / offsetMs);
+
+      // PUSH FIRST (at-least-once; idempotencyKey + userEvents dedup absorb
+      // retries), THEN stamp. emitBucketTransition handles the
+      // userEvents/exitOn/analytics parity.
+      await emitBucketTransition({
+        db,
+        registry: journeyRegistry,
+        hatchet,
+        logger,
+        kind: "dwell",
+        bucket,
+        userId: m.userId,
+        userEmail: m.userEmail,
+        epoch: m.entryCount,
+        source: "reconcile",
+        dwellLabel: label,
+        dwellOrdinal: ordinal,
+      });
+
+      // Stamp the membership (inter-sweep gate). status='active' clause = leave
+      // interop (a row flipped to 'left' between SELECT and UPDATE no-ops).
+      await db
+        .update(bucketMemberships)
+        .set({
+          dwellState: sql`jsonb_set(coalesce(${bucketMemberships.dwellState}, '{}'::jsonb), ${`{${label}}`}, ${`"${new Date(sweepInstant).toISOString()}"`}::jsonb)`,
+          lastEvaluatedAt: new Date(),
+          updatedAt: new Date(),
+        })
+        .where(
+          and(
+            eq(bucketMemberships.id, m.id),
+            eq(bucketMemberships.status, "active"),
+          ),
+        );
+      fired += 1;
+    }
+  }
+
+  return fired;
+}
+
 /**
  * reconcileJoins (absence buckets): materialize NEW members the real-time path
  * cannot see — a user who STOPS doing X fires no event, so only the clock can
@@ -643,18 +842,27 @@ async function reconcileBucketJoins(opts: {
     ? selectPresentInAllWindows(db, absenceLegs)
     : null;
 
+  // The membership/event tables key on the RESOLVED string key (external_id ??
+  // anonymous_id ?? contact.id), NOT necessarily external_id — email-only /
+  // anonymous contacts have a NULL external_id and are keyed on their uuid /
+  // anonymous_id. Joining on contacts.externalId would force external_id NOT NULL
+  // for every candidate (the coalesce would collapse to external_id) and silently
+  // drop exactly the dormant email-only contacts this cron exists to reconcile.
+  // Join on the SAME coalesce expression so the projected key matches the join.
+  const contactKey = contactKeySql();
+
   const baseQuery = db
     .select({
-      userId: contacts.externalId,
+      userId: contactKey,
       email: contacts.email,
     })
     .from(contacts)
-    .innerJoin(everFired, eq(everFired.userId, contacts.externalId))
-    .leftJoin(activeMembers, eq(activeMembers.userId, contacts.externalId));
+    .innerJoin(everFired, eq(everFired.userId, contactKey))
+    .leftJoin(activeMembers, eq(activeMembers.userId, contactKey));
 
   const candidates = await (presentInAll
     ? baseQuery
-        .leftJoin(presentInAll, eq(presentInAll.userId, contacts.externalId))
+        .leftJoin(presentInAll, eq(presentInAll.userId, contactKey))
         .where(
           and(
             isNull(contacts.deletedAt),
@@ -666,7 +874,12 @@ async function reconcileBucketJoins(opts: {
         and(isNull(contacts.deletedAt), isNull(activeMembers.userId)),
       )
   )
-    .orderBy(sql`${contacts.externalId} asc`)
+    // Deterministic scan order for the bounded re-run (no keyset cursor; the
+    // scan advances as reconciled matchers become active members and drop out).
+    // Order by contacts.id (the non-null unique PK) so the scan is null-safe and
+    // stable even for null-external_id contacts now that the join is on the
+    // coalesce key.
+    .orderBy(sql`${contacts.id} asc`)
     .limit(BATCH_SIZE);
 
   // SET-BASED / EXACT shapes (Fix #3) — every candidate row is a true matcher,