@hogsend/engine 0.40.0 → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/package.json +11 -8
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +207 -28
  5. package/src/campaigns/reconcile.ts +105 -11
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +124 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/index.ts +96 -2
  11. package/src/journeys/constants.ts +10 -0
  12. package/src/journeys/define-journey.ts +14 -405
  13. package/src/journeys/execute-journey-run.ts +641 -0
  14. package/src/journeys/graph/build-graph.ts +212 -56
  15. package/src/journeys/journey-boundary.ts +54 -0
  16. package/src/journeys/journey-context.ts +406 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprint-lock.ts +21 -0
  19. package/src/lib/blueprints.ts +803 -0
  20. package/src/lib/campaign-send-key.ts +58 -0
  21. package/src/lib/connector-actions.ts +203 -19
  22. package/src/lib/contacts.ts +54 -0
  23. package/src/lib/email-service-types.ts +4 -1
  24. package/src/lib/email.ts +13 -2
  25. package/src/lib/event-names.ts +143 -0
  26. package/src/lib/feed.ts +77 -57
  27. package/src/lib/frequency-cap.ts +45 -15
  28. package/src/lib/hatchet-duration.ts +22 -0
  29. package/src/lib/html.ts +1 -0
  30. package/src/lib/ingestion.ts +145 -4
  31. package/src/lib/journey-suppress.ts +87 -0
  32. package/src/lib/links.ts +204 -18
  33. package/src/lib/outbound.ts +20 -0
  34. package/src/lib/preferences.ts +80 -1
  35. package/src/lib/tracked.ts +44 -29
  36. package/src/lib/tracking-event-names.ts +8 -0
  37. package/src/lib/tracking.ts +1 -5
  38. package/src/lib/webhook-signing.ts +6 -1
  39. package/src/lists/channels.ts +75 -0
  40. package/src/lists/define-list.ts +34 -0
  41. package/src/lists/registry.ts +29 -2
  42. package/src/mcp/authoring-guide.ts +160 -0
  43. package/src/mcp/blueprint-tools.ts +390 -0
  44. package/src/middleware/require-admin.ts +13 -0
  45. package/src/routes/admin/api-keys.ts +72 -0
  46. package/src/routes/admin/blueprints.ts +795 -0
  47. package/src/routes/admin/campaigns.ts +179 -3
  48. package/src/routes/admin/emails.ts +13 -0
  49. package/src/routes/admin/events.ts +55 -0
  50. package/src/routes/admin/index.ts +4 -0
  51. package/src/routes/admin/journeys.ts +4 -2
  52. package/src/routes/admin/links.ts +303 -36
  53. package/src/routes/admin/lists.ts +51 -0
  54. package/src/routes/campaigns/index.ts +44 -6
  55. package/src/routes/email/preferences.ts +50 -13
  56. package/src/routes/feed/recipient.ts +2 -43
  57. package/src/routes/index.ts +6 -0
  58. package/src/routes/lists/index.ts +138 -18
  59. package/src/routes/tracking/arrive.ts +260 -0
  60. package/src/routes/tracking/click-pipeline.ts +329 -0
  61. package/src/routes/tracking/click.ts +5 -270
  62. package/src/routes/tracking/index.ts +2 -0
  63. package/src/routes/tracking/vanity.ts +64 -0
  64. package/src/worker.ts +5 -0
  65. package/src/workflows/bucket-backfill.ts +4 -2
  66. package/src/workflows/bucket-reconcile.ts +11 -4
  67. package/src/workflows/check-alerts.ts +130 -1
  68. package/src/workflows/journey-blueprint-interpreter.ts +656 -0
  69. package/src/workflows/send-campaign.ts +574 -180
package/src/lib/feed.ts CHANGED
@@ -1,14 +1,15 @@
1
- import { emailPreferences, type FeedBlock, feedItems } from "@hogsend/db";
2
- import { and, eq } from "drizzle-orm";
1
+ import { type FeedBlock, feedItems } from "@hogsend/db";
3
2
  import {
4
3
  deriveJourneyKey,
5
4
  getJourneyBoundary,
6
5
  registerKey,
7
6
  } from "../journeys/journey-boundary.js";
7
+ import { IN_APP_LIST_ID } from "../lists/channels.js";
8
8
  import { getListRegistry } from "../lists/registry-singleton.js";
9
9
  import { resolveOrCreateContact, resolveRecipient } from "./contacts.js";
10
10
  import { getDb } from "./db.js";
11
11
  import { createLogger } from "./logger.js";
12
+ import { readRecipientPreferences } from "./preferences.js";
12
13
  import { getRedis } from "./redis.js";
13
14
 
14
15
  const logger = createLogger(process.env.LOG_LEVEL);
@@ -16,9 +17,11 @@ const logger = createLogger(process.env.LOG_LEVEL);
16
17
  /**
17
18
  * Reserved list id governing in-app feed suppression (mirrors the built-in
18
19
  * `transactional` / `journey` categories). A recipient unsubscribed from
19
- * `in_app` (or `unsubscribed_all`) gets no feed items.
20
+ * `in_app` (or `unsubscribed_all`) gets no feed items. Canonically defined in
21
+ * `../lists/channels.js` (where the in-app channel is synthesized); re-exported
22
+ * here so the engine's existing export surface stays stable.
20
23
  */
21
- export const IN_APP_LIST_ID = "in_app";
24
+ export { IN_APP_LIST_ID };
22
25
 
23
26
  export interface SendFeedItemOptions {
24
27
  recipient: { userId?: string; email?: string; anonymousId?: string };
@@ -88,55 +91,23 @@ export async function sendFeedItem(
88
91
  });
89
92
  const recipientKey = resolvedKey;
90
93
 
91
- // (2) `in_app` suppression check. Suppression is governed by the `in_app` list
92
- // key regardless of the item's own category. `email_preferences` is
93
- // `(user_id, email)`-keyed; an anon-only recipient has no pref row → categories
94
- // = {} → opt-in default → not suppressed (you cannot suppress what has no
95
- // preference surface yet). `unsubscribed_all` on an identified recipient DOES
96
- // suppress, consistent with the email mailer's `checkEmailPreferences`.
97
- let categories: Record<string, boolean> = {};
98
- const recip = await resolveRecipient({
99
- db,
100
- userId: recipient.userId,
101
- email: recipient.email,
102
- });
103
- if (recip) {
104
- const extId = recip.externalId ?? recip.contactId;
105
- const rows = await db
106
- .select()
107
- .from(emailPreferences)
108
- .where(
109
- and(
110
- eq(emailPreferences.userId, extId),
111
- eq(emailPreferences.email, recip.email),
112
- ),
113
- )
114
- .limit(1);
115
- const row = rows[0];
116
- if (row) {
117
- if (row.unsubscribedAll) {
118
- return {
119
- feedItemId: null,
120
- recipientKey,
121
- suppressed: true,
122
- createdAt: null,
123
- };
124
- }
125
- categories = (row.categories ?? {}) as Record<string, boolean>;
126
- }
127
- }
128
- if (!getListRegistry().isSubscribed(categories, IN_APP_LIST_ID)) {
129
- return {
130
- feedItemId: null,
131
- recipientKey,
132
- suppressed: true,
133
- createdAt: null,
134
- };
135
- }
136
-
137
- // (3) Replay-safe idempotency key (mirrors `sendEmail`). The `feed:`-namespaced
94
+ // (2) Replay-safe idempotency key (mirrors `sendEmail`), derived
95
+ // UNCONDITIONALLY — BEFORE any preference decision. The `feed:`-namespaced
138
96
  // discriminant realizes the plan's `feedSend:<runAnchor>:<site>:<type>` shape
139
97
  // through the SAME branch-stable key engine (one primitive, not a fork).
98
+ //
99
+ // THE LAW: the Hatchet journal is positional, and `boundary.memoize` (step 4)
100
+ // is a durable call, so its issuance must never be conditional on a live
101
+ // preference read. A recipient's `in_app`/`unsubscribed_all` state can flip
102
+ // between an original run and a replay-from-top; the OLD code early-returned on
103
+ // that read HERE, before the key derivation + `registerKey` + `memoize`, so a
104
+ // flip made the replay conditionally skip (or add) the memoize durable call →
105
+ // positional journal shift → the run is killed with a non-determinism error.
106
+ // The fix (mirroring the connector gate in lib/connector-actions.ts): derive +
107
+ // register the key and issue the memoize UNCONDITIONALLY, and fold the whole
108
+ // preference verdict INSIDE the memo closure (step 3) so the skip/allow verdict
109
+ // is RECORDED by the durable memo and replays verbatim — the live-flipped
110
+ // preference is never re-read on a replay.
140
111
  const boundary = getJourneyBoundary();
141
112
  let key: string | undefined = opts.idempotencyKey;
142
113
  if (!key && boundary) {
@@ -222,12 +193,61 @@ export async function sendFeedItem(
222
193
  };
223
194
  };
224
195
 
225
- // Layer 1 (eviction-gated, FREE) fast path. When inside a journey on an
226
- // eviction-capable engine, a replay returns the recorded result WITHOUT
227
- // re-hitting the DB; Layer 2 (`onConflictDoNothing`) is the version-independent
228
- // backstop. Outside a journey, run directly.
196
+ // (3) `in_app` suppression gate + insert/publish, folded into ONE closure so
197
+ // the whole verdict (skip OR insert) is recorded by the durable memo (step 4)
198
+ // and replays byte-identically. Suppression is governed by the `in_app`
199
+ // channel list regardless of the item's own category.
200
+ //
201
+ // The preference read is the UNIFIED aggregated `readRecipientPreferences`
202
+ // keyed by BOTH the recipient's `external_id ?? contact_id` AND its email —
203
+ // NOT the old single-row `(extId, email)` lookup. This is a deliberate,
204
+ // suppression-conservative behaviour change: an `unsubscribed_all` (or category
205
+ // opt-out) imported before the contact existed and keyed `(email, email)` now
206
+ // suppresses the feed too, exactly as it already suppresses email. An anon-only
207
+ // recipient has no preference surface (`resolveRecipient` → null), so
208
+ // `unsubscribed_all` is not consulted (you cannot suppress what has no pref row
209
+ // yet); the `in_app` channel check still runs, but empty categories → opt-in
210
+ // default → subscribed, so an anon recipient is never suppressed here.
211
+ const doGatedInsertAndPublish = async (): Promise<SendFeedItemResult> => {
212
+ const suppressedResult: SendFeedItemResult = {
213
+ feedItemId: null,
214
+ recipientKey,
215
+ suppressed: true,
216
+ createdAt: null,
217
+ };
218
+ const recip = await resolveRecipient({
219
+ db,
220
+ userId: recipient.userId,
221
+ email: recipient.email,
222
+ });
223
+ // `external_id ?? contact_id` — the SAME identity key the old single-row read
224
+ // used (and that preference writes key on). Undefined for an anon recipient.
225
+ const extId = recip ? (recip.externalId ?? recip.contactId) : undefined;
226
+ const prefs = await readRecipientPreferences(db, {
227
+ email: recip?.email,
228
+ userId: extId,
229
+ });
230
+ // `unsubscribed_all` on an IDENTIFIED recipient suppresses (consistent with
231
+ // the email mailer's `checkEmailPreferences`); guarded on `recip` so an
232
+ // anon recipient with no preference surface is never blocked.
233
+ if (recip && prefs.unsubscribedAll) {
234
+ return suppressedResult;
235
+ }
236
+ if (!getListRegistry().isSubscribed(prefs.categories, IN_APP_LIST_ID)) {
237
+ return suppressedResult;
238
+ }
239
+ return doInsertAndPublish();
240
+ };
241
+
242
+ // (4) Layer 1 (eviction-gated, FREE) fast path. When inside a journey on an
243
+ // eviction-capable engine, a replay returns the recorded result (a skip verdict
244
+ // OR the insert result) WITHOUT re-reading preferences or re-hitting the DB;
245
+ // Layer 2 (`onConflictDoNothing`) is the version-independent backstop. Outside
246
+ // a journey, run directly. The key derivation, `registerKey`, and this
247
+ // `memoize` call all stay UNCONDITIONAL (THE LAW) — the preference verdict
248
+ // lives inside the closure, never gating the durable call itself.
229
249
  if (boundary && key) {
230
- return boundary.memoize([key], doInsertAndPublish);
250
+ return boundary.memoize([key], doGatedInsertAndPublish);
231
251
  }
232
- return doInsertAndPublish();
252
+ return doGatedInsertAndPublish();
233
253
  }
@@ -6,6 +6,42 @@ import type { FrequencyCapConfig } from "./email-service-types.js";
6
6
 
7
7
  const DEFAULT_EXEMPT = ["transactional"];
8
8
 
9
+ /**
10
+ * The windowed non-failed send count for a recipient — the COUNT behind
11
+ * {@link isFrequencyCapped}, shared with `ctx.throttle` (and later the suppress
12
+ * guard). Served by the `email_sends_freq_cap_idx (to_email, created_at,
13
+ * category)` index. Never-dispatched / failed rows (`status = 'failed'`) are
14
+ * excluded; a `category` narrows the count to that category.
15
+ *
16
+ * NOTE: NO exemption semantics live here — unlike {@link isFrequencyCapped}
17
+ * (which short-circuits an exempt "transactional" category), a `category` passed
18
+ * here genuinely counts that category's sends.
19
+ */
20
+ export async function countRecentSends(opts: {
21
+ db: Database;
22
+ to: string;
23
+ since: Date;
24
+ category?: string;
25
+ }): Promise<number> {
26
+ const { db, to, since, category } = opts;
27
+
28
+ const conditions = [
29
+ eq(emailSends.toEmail, to),
30
+ gte(emailSends.createdAt, since),
31
+ ne(emailSends.status, "failed"),
32
+ ];
33
+ if (category !== undefined) {
34
+ conditions.push(eq(emailSends.category, category));
35
+ }
36
+
37
+ const [row] = await db
38
+ .select({ n: count() })
39
+ .from(emailSends)
40
+ .where(and(...conditions));
41
+
42
+ return row?.n ?? 0;
43
+ }
44
+
9
45
  /**
10
46
  * True if this recipient has hit the configured send cap within the window.
11
47
  *
@@ -35,20 +71,14 @@ export async function isFrequencyCapped(opts: {
35
71
 
36
72
  const since = new Date(Date.now() - durationToMs(rule.window));
37
73
 
38
- const conditions = [
39
- eq(emailSends.toEmail, to),
40
- gte(emailSends.createdAt, since),
41
- ne(emailSends.status, "failed"),
42
- ];
43
- // The byCategory branch counts only sends in that category.
44
- if (override && category) {
45
- conditions.push(eq(emailSends.category, category));
46
- }
47
-
48
- const [row] = await db
49
- .select({ n: count() })
50
- .from(emailSends)
51
- .where(and(...conditions));
74
+ // The byCategory branch counts only sends in that category; the global rule
75
+ // counts ALL of the recipient's non-failed sends in the window.
76
+ const n = await countRecentSends({
77
+ db,
78
+ to,
79
+ since,
80
+ ...(override && category ? { category } : {}),
81
+ });
52
82
 
53
- return (row?.n ?? 0) >= rule.count;
83
+ return n >= rule.count;
54
84
  }
@@ -0,0 +1,22 @@
1
+ import { type DurationObject, durationToMs } from "@hogsend/core";
2
+
3
+ /** Normalize any duration to a SINGLE-UNIT whole-seconds Go string ("120s")
4
+ * before it reaches a Hatchet durable sleep (`sleepFor` or a `SleepCondition`).
5
+ * The SDK renders ms numbers as multi-unit strings ("1m59s"), which some
6
+ * hatchet-lite versions silently fail to honor as sleep conditions (the wait
7
+ * resolves instantly with no match) — pinned empirically 2026-07-10. Whole
8
+ * seconds match the SDK's own `sleepUntil` normalization. EVERY engine call
9
+ * site that hands Hatchet a sleep duration must route through this — a raw ms
10
+ * number reopens the instant-wake bug.
11
+ *
12
+ * Lives beside (not inside) `lib/hatchet.ts` because tests `vi.mock` that
13
+ * module to stub the client singleton; this helper must survive the mock. */
14
+ export const toSleepDuration = (
15
+ durationOrMs: DurationObject | number,
16
+ ): `${number}s` => {
17
+ const ms =
18
+ typeof durationOrMs === "number"
19
+ ? durationOrMs
20
+ : durationToMs(durationOrMs);
21
+ return `${Math.max(1, Math.ceil(ms / 1000))}s`;
22
+ };
package/src/lib/html.ts CHANGED
@@ -12,6 +12,7 @@ export function htmlPage(opts: { title: string; body: string }): string {
12
12
  p { color: #555; line-height: 1.6; }
13
13
  a { color: #2563eb; text-decoration: none; }
14
14
  a:hover { text-decoration: underline; }
15
+ .pref-section { font-size: 0.75rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: #6b7280; margin: 28px 0 4px; }
15
16
  .pref-row { display: flex; justify-content: space-between; align-items: center; padding: 12px 0; border-bottom: 1px solid #e5e7eb; }
16
17
  .pref-label { font-weight: 500; }
17
18
  .pref-status { font-size: 0.875rem; }
@@ -2,12 +2,20 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type {
3
3
  AnalyticsEventMirrorConfig,
4
4
  AnalyticsProvider,
5
+ PropertyCondition,
5
6
  } from "@hogsend/core";
6
7
  import { evaluatePropertyConditions } from "@hogsend/core";
7
8
  import type { JourneyRegistry } from "@hogsend/core/registry";
8
- import { type Database, journeyStates, userEvents } from "@hogsend/db";
9
+ import type { JourneyMeta } from "@hogsend/core/types";
10
+ import {
11
+ type Database,
12
+ journeyBlueprints,
13
+ journeyStates,
14
+ userEvents,
15
+ } from "@hogsend/db";
9
16
  import { and, eq, inArray, isNull } from "drizzle-orm";
10
17
  import { checkBucketMembership } from "../buckets/check-membership.js";
18
+ import { BLUEPRINT_RUN_EVENT } from "../journeys/constants.js";
11
19
  import { logTransition } from "../journeys/journey-log.js";
12
20
  import {
13
21
  logResidualTwins,
@@ -157,6 +165,80 @@ function shouldMirrorEvent(
157
165
  return true;
158
166
  }
159
167
 
168
+ /**
169
+ * Blueprint dispatch (spec §5) — the DB-lookup counterpart of the static
170
+ * `onEvents` registration code journeys get at boot. Code journeys can't gain
171
+ * a trigger without a worker redeploy; a blueprint row created at 3pm must
172
+ * fire at 3:01. So on every ingested event this queries the enabled
173
+ * `journey_blueprints` whose `triggerEvent` matches (served by the
174
+ * `(trigger_event, status)` index), applies `triggerWhere` with the SAME
175
+ * `evaluatePropertyConditions` the interpreter's enrollment guard re-checks
176
+ * with (dispatch and guard must agree, and both see the serializable-scalar
177
+ * payload), and pushes one `blueprint:run` per match to the single
178
+ * statically-registered `journey-blueprint-interpreter` task.
179
+ *
180
+ * Returns the number of dispatched enrollment attempts.
181
+ */
182
+ export async function checkBlueprintTriggers(opts: {
183
+ db: Database;
184
+ hatchet: HatchetClient;
185
+ logger: Logger;
186
+ event: {
187
+ name: string;
188
+ userId: string;
189
+ userEmail: string;
190
+ /** The serializable-scalar subset that will reach the interpreter. */
191
+ properties: Record<string, string | number | boolean | null>;
192
+ };
193
+ }): Promise<number> {
194
+ const { db, hatchet, logger, event } = opts;
195
+
196
+ const candidates = await db
197
+ .select({
198
+ id: journeyBlueprints.id,
199
+ version: journeyBlueprints.version,
200
+ triggerWhere: journeyBlueprints.triggerWhere,
201
+ })
202
+ .from(journeyBlueprints)
203
+ .where(
204
+ and(
205
+ eq(journeyBlueprints.triggerEvent, event.name),
206
+ eq(journeyBlueprints.status, "enabled"),
207
+ ),
208
+ );
209
+
210
+ let dispatched = 0;
211
+ for (const bp of candidates) {
212
+ const where = (bp.triggerWhere ?? []) as unknown as PropertyCondition[];
213
+ if (
214
+ where.length > 0 &&
215
+ !evaluatePropertyConditions({
216
+ conditions: where,
217
+ properties: event.properties,
218
+ })
219
+ ) {
220
+ continue;
221
+ }
222
+ await hatchet.events.push(BLUEPRINT_RUN_EVENT, {
223
+ blueprintId: bp.id,
224
+ blueprintVersion: bp.version,
225
+ userId: event.userId,
226
+ userEmail: event.userEmail,
227
+ triggerProperties: event.properties,
228
+ });
229
+ dispatched += 1;
230
+ }
231
+
232
+ if (dispatched > 0) {
233
+ logger.info("Blueprint runs dispatched", {
234
+ event: event.name,
235
+ userId: event.userId,
236
+ dispatched,
237
+ });
238
+ }
239
+ return dispatched;
240
+ }
241
+
160
242
  export async function ingestEvent(opts: {
161
243
  db: Database;
162
244
  registry: JourneyRegistry;
@@ -402,6 +484,34 @@ export async function ingestEvent(opts: {
402
484
  }
403
485
  const exits = exitsResult.value;
404
486
 
487
+ // (5b) Blueprint dispatch (spec §5) — the DB-driven twin of the Hatchet
488
+ // push in (4): one `blueprint:run` per enabled matching blueprint. Runs
489
+ // AFTER the main push settled, so a dispatched blueprint never observes an
490
+ // event code journeys were not notified of. Best-effort by design: the
491
+ // event row + code-journey push are already committed, so throwing here
492
+ // could not be retried into a redelivery (the idempotency claim survives) —
493
+ // it would only fail the caller for work that half-happened. Mirrors the
494
+ // bucket-membership stance below.
495
+ try {
496
+ await checkBlueprintTriggers({
497
+ db,
498
+ hatchet,
499
+ logger,
500
+ event: {
501
+ name: event.event,
502
+ userId: resolvedKey,
503
+ userEmail: event.userEmail ?? "",
504
+ properties: serializableProperties,
505
+ },
506
+ });
507
+ } catch (err) {
508
+ logger.warn("Blueprint trigger dispatch failed", {
509
+ event: event.event,
510
+ userId: resolvedKey,
511
+ error: err instanceof Error ? err.message : String(err),
512
+ });
513
+ }
514
+
405
515
  // (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
406
516
  // Promise.all above: its property eval reads contact state ⊕ this-ingest
407
517
  // contactProperties patch, and its bucket:entered/left emissions recurse back
@@ -458,14 +568,45 @@ async function checkExits(
458
568
  ),
459
569
  });
460
570
 
571
+ // Blueprint enrollments share journeyStates but are NOT in the code-journey
572
+ // registry — their exitOn lives on the journey_blueprints row (spec §4).
573
+ // Resolve exitOn for any active state whose journeyId the registry doesn't
574
+ // know, in one batched read. Deliberately status-agnostic: disabling a
575
+ // blueprint stops NEW enrollments, but an in-flight run keeps honoring its
576
+ // exit rules (spec §10/§12).
577
+ const unregisteredIds = [
578
+ ...new Set(
579
+ activeStates
580
+ .map((state) => state.journeyId)
581
+ .filter((journeyId) => !registry.get(journeyId)),
582
+ ),
583
+ ];
584
+ const blueprintExitOn = new Map<string, NonNullable<JourneyMeta["exitOn"]>>();
585
+ if (unregisteredIds.length > 0) {
586
+ const rows = await db
587
+ .select({ id: journeyBlueprints.id, exitOn: journeyBlueprints.exitOn })
588
+ .from(journeyBlueprints)
589
+ .where(inArray(journeyBlueprints.id, unregisteredIds));
590
+ for (const row of rows) {
591
+ if (row.exitOn?.length) {
592
+ blueprintExitOn.set(
593
+ row.id,
594
+ row.exitOn as NonNullable<JourneyMeta["exitOn"]>,
595
+ );
596
+ }
597
+ }
598
+ }
599
+
461
600
  const statesToExit: string[] = [];
462
601
  const runIdsToCancel: string[] = [];
463
602
 
464
603
  for (const state of activeStates) {
465
- const journey = registry.get(state.journeyId);
466
- if (!journey?.exitOn) continue;
604
+ const exitOn =
605
+ registry.get(state.journeyId)?.exitOn ??
606
+ blueprintExitOn.get(state.journeyId);
607
+ if (!exitOn) continue;
467
608
 
468
- const shouldExit = journey.exitOn.some((exitCondition) => {
609
+ const shouldExit = exitOn.some((exitCondition) => {
469
610
  if (exitCondition.event !== event.eventName) return false;
470
611
  if (!exitCondition.where?.length) return true;
471
612
  return evaluatePropertyConditions({
@@ -0,0 +1,87 @@
1
+ import type { Database } from "@hogsend/db";
2
+ import { emailSends, journeyStates } from "@hogsend/db";
3
+ import { and, eq, gte, ne } from "drizzle-orm";
4
+ import type { JourneyBoundary } from "../journeys/journey-boundary.js";
5
+ import { recordOnce } from "../journeys/record-once.js";
6
+
7
+ /**
8
+ * True if a non-failed `email_sends` row exists for THIS journey — across ALL
9
+ * of its enrollments — to THIS recipient within the suppress window. The
10
+ * INNER JOIN to `journey_states` on `journey_state_id`, filtered by
11
+ * `journey_id`, is what crosses enrollments: `meta.suppress` is a per-JOURNEY
12
+ * min-gap, not per-enrollment, so a re-enrollment inside the window is still
13
+ * gapped. Failed rows (`status = 'failed'`, never dispatched) are excluded,
14
+ * mirroring {@link countRecentSends}. EXISTS semantics only — `limit(1)`, no
15
+ * count needed.
16
+ */
17
+ export async function hasRecentJourneySend(opts: {
18
+ db: Database;
19
+ journeyId: string;
20
+ to: string;
21
+ since: Date;
22
+ }): Promise<boolean> {
23
+ const rows = await opts.db
24
+ .select({ id: emailSends.id })
25
+ .from(emailSends)
26
+ .innerJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
27
+ .where(
28
+ and(
29
+ eq(journeyStates.journeyId, opts.journeyId),
30
+ eq(emailSends.toEmail, opts.to),
31
+ gte(emailSends.createdAt, opts.since),
32
+ ne(emailSends.status, "failed"),
33
+ ),
34
+ )
35
+ .limit(1);
36
+ return rows.length > 0;
37
+ }
38
+
39
+ /**
40
+ * The RECORDED-once journey-suppress verdict for a boundary send. Returns
41
+ * `{ suppressed }` — `true` means the tracked mailer must skip the send
42
+ * (`journey_suppressed`, no provider call, no `email_sends` row).
43
+ *
44
+ * REPLAY STABILITY (non-negotiable): the live EXISTS check diverges on replay —
45
+ * the run's OWN send lands in the window, so an originally-ALLOWED send would
46
+ * re-check as suppressed (a late duplicate), and an originally-SUPPRESSED send
47
+ * could re-check as allowed if the blocking row was purged. So the verdict is
48
+ * frozen set-once under `context.__throttle__` keyed by the send's resolved
49
+ * idempotency key (already per-run-unique via `registerKey`, so it needs no
50
+ * extra registration) and replayed verbatim thereafter — durable on ANY engine.
51
+ *
52
+ * The guard is INERT (returns `{ suppressed: false }` without touching the DB)
53
+ * when there is no boundary, no `journeyId`, a zero `suppressMs`, or no resolved
54
+ * idempotency key — i.e. every non-journey / transactional send is unaffected.
55
+ */
56
+ export async function checkJourneySuppress(opts: {
57
+ db: Database;
58
+ boundary: JourneyBoundary | undefined;
59
+ to: string;
60
+ idempotencyKey: string | undefined;
61
+ /** Injectable clock for tests; defaults to the live wall clock. */
62
+ now?: number;
63
+ }): Promise<{ suppressed: boolean }> {
64
+ const { db, boundary, to, idempotencyKey } = opts;
65
+ if (
66
+ !boundary?.journeyId ||
67
+ !boundary.suppressMs ||
68
+ boundary.suppressMs <= 0 ||
69
+ !idempotencyKey
70
+ ) {
71
+ return { suppressed: false };
72
+ }
73
+
74
+ const { journeyId, suppressMs, stateId } = boundary;
75
+ return recordOnce<{ suppressed: boolean }>({
76
+ db,
77
+ stateId,
78
+ namespace: "__throttle__",
79
+ key: `suppress:${idempotencyKey}`,
80
+ compute: async () => {
81
+ const since = new Date((opts.now ?? Date.now()) - suppressMs);
82
+ return {
83
+ suppressed: await hasRecentJourneySend({ db, journeyId, to, since }),
84
+ };
85
+ },
86
+ });
87
+ }