@hogsend/engine 0.38.1 → 0.39.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.38.1",
3
+ "version": "0.39.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -31,25 +31,28 @@
31
31
  "@openrouter/ai-sdk-provider": "^2.9.1",
32
32
  "@scalar/hono-api-reference": "^0.10.19",
33
33
  "@t3-oss/env-core": "^0.13.11",
34
+ "acorn": "^8.17.0",
35
+ "acorn-walk": "^8.3.5",
34
36
  "ai": "^6.0.209",
35
37
  "better-auth": "^1.6.11",
36
38
  "drizzle-orm": "^0.45.2",
37
39
  "hono": "^4.12.22",
38
40
  "ioredis": "^5.10.1",
41
+ "launch-editor": "^2.14.1",
39
42
  "papaparse": "^5.5.3",
40
43
  "picocolors": "^1.1.1",
41
44
  "resend": "^6.12.3",
42
45
  "svix": "^1.95.1",
43
46
  "winston": "^3.19.0",
44
47
  "zod": "^4.4.3",
45
- "@hogsend/core": "^0.38.1",
46
- "@hogsend/db": "^0.38.1",
47
- "@hogsend/email": "^0.38.1",
48
- "@hogsend/plugin-posthog": "^0.38.1",
49
- "@hogsend/plugin-resend": "^0.38.1"
48
+ "@hogsend/core": "^0.39.0",
49
+ "@hogsend/db": "^0.39.0",
50
+ "@hogsend/email": "^0.39.0",
51
+ "@hogsend/plugin-posthog": "^0.39.0",
52
+ "@hogsend/plugin-resend": "^0.39.0"
50
53
  },
51
54
  "optionalDependencies": {
52
- "@hogsend/plugin-postmark": "^0.38.1"
55
+ "@hogsend/plugin-postmark": "^0.39.0"
53
56
  },
54
57
  "devDependencies": {
55
58
  "@types/node": "^22.15.3",
package/src/container.ts CHANGED
@@ -3,6 +3,7 @@ import type {
3
3
  AnalyticsEventMirrorConfig,
4
4
  AnalyticsProvider,
5
5
  EmailProvider,
6
+ JourneySourceLocation,
6
7
  PostHogService,
7
8
  TimeZone,
8
9
  } from "@hogsend/core";
@@ -14,7 +15,7 @@ import {
14
15
  type DatabaseClient,
15
16
  type JournalShape,
16
17
  } from "@hogsend/db";
17
- import type { TemplateRegistry } from "@hogsend/email";
18
+ import type { TemplateDefinition, TemplateRegistry } from "@hogsend/email";
18
19
  import { createBucketAccessor } from "./buckets/bucket-access.js";
19
20
  import type { DefinedBucket } from "./buckets/define-bucket.js";
20
21
  import {
@@ -41,6 +42,8 @@ import {
41
42
  import { env } from "./env.js";
42
43
  import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
43
44
  import type { DefinedJourney } from "./journeys/define-journey.js";
45
+ import { getJourneySourceLocations } from "./journeys/journey-source-locations-singleton.js";
46
+ import { getJourneySources } from "./journeys/journey-sources-singleton.js";
44
47
  import { buildJourneyRegistry } from "./journeys/registry.js";
45
48
  import {
46
49
  isAnalyticsProvider,
@@ -75,7 +78,11 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
75
78
  import { sendResetPasswordEmail } from "./lib/reset-email.js";
76
79
  import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
77
80
  import { prepareTrackedHtml } from "./lib/tracking.js";
78
- import type { DefinedList } from "./lists/define-list.js";
81
+ import {
82
+ type DefinedList,
83
+ isReservedListId,
84
+ RESERVED_LIST_IDS,
85
+ } from "./lists/define-list.js";
79
86
  import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
80
87
  import {
81
88
  type DefinedWebhookSource,
@@ -147,6 +154,20 @@ export interface HogsendClient {
147
154
  */
148
155
  identity: IdentityService;
149
156
  registry: JourneyRegistry;
157
+ /**
158
+ * Map of enabled journey id → its captured `run` source string. Populated by
159
+ * `buildJourneyRegistry` (skips journeys whose source failed to serialize).
160
+ * Consumed by the Studio journey-graph route, which parses the source lazily
161
+ * with acorn to derive a visual workflow. Empty when no journeys are wired.
162
+ */
163
+ journeySources: Map<string, string>;
164
+ /**
165
+ * Map of enabled journey id → its `defineJourney` call-site `{ path, line }`.
166
+ * Populated by `buildJourneyRegistry`. Consumed by the Studio journey-graph
167
+ * route to build an "open in editor" deep link. Absent ids had no capturable
168
+ * call-site (e.g. bucket-generated reaction journeys).
169
+ */
170
+ journeySourceLocations: Map<string, JourneySourceLocation>;
150
171
  /**
151
172
  * The bucket registry (id map + event/property inverted indexes for candidate
152
173
  * narrowing). Built and installed as the process singleton at client build;
@@ -379,16 +400,26 @@ export function createHogsendClient(
379
400
  const created = createDatabase({ url: env.DATABASE_URL });
380
401
  const db = opts.overrides?.db ?? created.db;
381
402
 
403
+ // Resolve buckets + their reaction journeys BEFORE the journey registry so the
404
+ // reaction ids (`bucket-<id>-on-<kind>`, registered separately below) are part
405
+ // of ENABLED_JOURNEYS's known set. They ARE registered journeys, so listing a
406
+ // real reaction id in ENABLED_JOURNEYS must NOT be rejected as a typo.
407
+ const buckets = opts.buckets ?? [];
408
+ const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
409
+ const reactionJourneys = collectBucketReactionJourneys(
410
+ buckets,
411
+ enabledBuckets,
412
+ );
413
+
382
414
  const registry = buildJourneyRegistry(
383
415
  opts.journeys ?? [],
384
416
  opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
417
+ reactionJourneys.map((r) => r.meta.id),
385
418
  );
386
419
 
387
420
  // Installs the bucket registry singleton in BOTH the API and worker processes
388
421
  // (both call createHogsendClient); the real-time ingest path reads it via
389
422
  // getBucketRegistrySingleton().
390
- const buckets = opts.buckets ?? [];
391
- const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
392
423
  const bucketRegistry = buildBucketRegistry(buckets, enabledBuckets);
393
424
 
394
425
  // Register the reaction journeys generated by `bucket.on()` into the journey
@@ -398,10 +429,7 @@ export function createHogsendClient(
398
429
  // be subject to the journeys csv (Section 9). Both API and worker call
399
430
  // createHogsendClient, so the singleton carries reaction metas in both
400
431
  // processes (needed for admin feedsJourneys + the dwell-cron lookup).
401
- for (const reaction of collectBucketReactionJourneys(
402
- buckets,
403
- enabledBuckets,
404
- )) {
432
+ for (const reaction of reactionJourneys) {
405
433
  registry.register(reaction.meta);
406
434
  }
407
435
 
@@ -500,6 +528,81 @@ export function createHogsendClient(
500
528
 
501
529
  const templates = opts.email?.templates ?? ({} as TemplateRegistry);
502
530
 
531
+ // Boot-validate every template's `category` against the resolvable list
532
+ // namespace BEFORE the mailer/emailService is constructed — fail CLOSED.
533
+ //
534
+ // A template's `category` (TemplateDefinition.category) IS the
535
+ // email-preferences list key: at send time `lib/tracked.ts` resolves the
536
+ // effective category and `checkSuppression` gates it through
537
+ // `ListRegistry.isSubscribed`, whose `isSubscribedByDefault` legacy fallback
538
+ // is `this.get(id)?.defaultOptIn ?? true`. So a TYPO'd category (e.g.
539
+ // "product-update" when the opt-in list id is "product-updates") resolves to
540
+ // an UNKNOWN id → `?? true` opt-in default → treated as subscribed → NOT
541
+ // suppressed. The consent/opt-in email would then be delivered to EVERY
542
+ // recipient (including never-subscribed) AND anyone who unsubscribed under the
543
+ // correct key would still receive it — CAN-SPAM/GDPR-grade. This guard makes a
544
+ // mismatched category a loud boot failure so it can never reach that fallback.
545
+ //
546
+ // Known-good set = reserved built-ins ∪ DEFINED lists (`opts.lists`), NOT just
547
+ // the ENABLED registry — mirroring the ENABLED_JOURNEYS lesson (validate
548
+ // against DEFINED, not just ENABLED). A DEFINED-but-registry-EXCLUDED list
549
+ // (removed from the registry by an ENABLED_LISTS allowlist that doesn't name
550
+ // it) does NOT auto-warn: excluding it flips the send-time gate by POLARITY,
551
+ // so we branch on `defaultOptIn` (below). We carry each list's `defaultOptIn`
552
+ // (not just its id) so that branch can decide THROW vs WARN. This does NOT
553
+ // change the send-time suppression logic; it only prevents a bad/consent-
554
+ // flipping category reaching it.
555
+ const definedLists = new Map(
556
+ (opts.lists ?? []).map((l) => [l.meta.id, l.meta.defaultOptIn] as const),
557
+ );
558
+ for (const [templateKey, def] of Object.entries(templates)) {
559
+ const category = (def as TemplateDefinition | undefined)?.category;
560
+ // No category ⇒ no per-list gating for this template; nothing to validate.
561
+ if (!category) continue;
562
+ // Reserved built-in category (transactional / journey) — never a list, but
563
+ // a legitimate `email_preferences.categories` key. OK.
564
+ if (isReservedListId(category)) continue;
565
+ // Category names a REGISTERED list ⇒ suppression/preferences gate correctly.
566
+ // (Note: a `defineList({ enabled:false })` is STILL registered — the
567
+ // registry filters on ENABLED_LISTS only, never `meta.enabled` — so it
568
+ // lands here, not in the excluded branch below.)
569
+ if (listRegistry.has(category)) continue;
570
+ // Category names a DEFINED list that is EXCLUDED from the registry by an
571
+ // ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
572
+ // send-time check fall back to the legacy `?? true` opt-in default, which
573
+ // FLIPS the gate by polarity:
574
+ // • opt-IN list (`defaultOptIn:false`, consent required): enabled →
575
+ // `categories[id] === true` (never-consented = NOT subscribed =
576
+ // suppressed); excluded → `categories[id] !== false` (never-consented =
577
+ // SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
578
+ // never opted in. Disabling un-gates consent → THROW (fail closed).
579
+ // • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
580
+ // `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
581
+ const definedOptIn = definedLists.get(category);
582
+ if (definedOptIn !== undefined) {
583
+ if (definedOptIn === false) {
584
+ throw new Error(
585
+ `Email template "${templateKey}" has category "${category}", an OPT-IN email list (defaultOptIn:false) that is DEFINED but EXCLUDED from the active registry by ENABLED_LISTS. At send time an excluded list falls back to the legacy opt-in default, which UN-GATES consent — the opt-in email would ship to recipients who never subscribed. Re-enable the list in ENABLED_LISTS (or change the template's category) — disabling an opt-in list must not silently flip its consent gate open.`,
586
+ );
587
+ }
588
+ logger.warn(
589
+ `Email template "${templateKey}" has category "${category}", a DEFINED email list EXCLUDED from the active registry by ENABLED_LISTS. It is an opt-out list (defaultOptIn:true), so send-time gating is behavior-preserving — but its preference center entry is hidden while excluded. Re-enable the list in ENABLED_LISTS or change the template's category.`,
590
+ );
591
+ continue;
592
+ }
593
+ // Unknown category: neither a reserved built-in nor a defined list. At send
594
+ // time this resolves to the `?? true` opt-in default, bypassing
595
+ // suppression/consent. Fail CLOSED with an actionable message.
596
+ const knownLists = [...definedLists.keys()];
597
+ throw new Error(
598
+ `Email template "${templateKey}" has category "${category}", which is neither a reserved built-in category (${[
599
+ ...RESERVED_LIST_IDS,
600
+ ].join(", ")}) nor a defined email list (${
601
+ knownLists.length ? knownLists.join(", ") : "none"
602
+ }). A template's category is its email-preferences list key, so it MUST match a list id (defineList) or a reserved built-in — otherwise an unknown/typo'd category silently defaults to opt-in and un-gates suppression/consent. Fix the category or define the list.`,
603
+ );
604
+ }
605
+
503
606
  const emailService =
504
607
  opts.overrides?.mailer ??
505
608
  createTrackedMailer(
@@ -611,11 +714,29 @@ export function createHogsendClient(
611
714
  : wrapLegacyAnalyticsService(analyticsOpt as PostHogService);
612
715
  analyticsProviders.register(analytics);
613
716
  } else {
717
+ // Resolve the ONE active analytics provider by id — the analytics sibling of
718
+ // the email-provider resolution above, and fail loud on an unresolved
719
+ // active id exactly like `EMAIL_PROVIDER` does. `env.ANALYTICS_PROVIDER`
720
+ // carries a zod `.default("posthog")`, so the resolved id is never empty —
721
+ // that default is what AUTO-ACTIVATES the PostHog env preset when
722
+ // `POSTHOG_API_KEY` is set. Because of that default we must NOT fail boot
723
+ // merely because the resolved id is unregistered: an operator who wired NO
724
+ // analytics still resolves "posthog" and legitimately has no provider (leave
725
+ // `analytics` undefined — reads/mirror stay no-ops). So the throw is gated on
726
+ // the id being EXPLICITLY requested — a code `defaultProvider` OR a SET
727
+ // `ANALYTICS_PROVIDER` env. The RAW `process.env` read (mirroring the
728
+ // `REDIS_URL` read above) is what distinguishes an explicit request from the
729
+ // zod default; without this gate a bogus `ANALYTICS_PROVIDER` typo would
730
+ // SILENTLY disable analytics (killing tz person-reads + the event mirror)
731
+ // instead of failing loud.
614
732
  const activeId = analyticsGroup?.defaultProvider ?? env.ANALYTICS_PROVIDER;
733
+ const explicitlyRequested = Boolean(
734
+ analyticsGroup?.defaultProvider ?? process.env.ANALYTICS_PROVIDER,
735
+ );
615
736
  analytics = analyticsProviders.get(activeId);
616
- if (analyticsGroup?.defaultProvider && !analytics) {
737
+ if (explicitlyRequested && !analytics) {
617
738
  throw new Error(
618
- `analytics.defaultProvider "${analyticsGroup.defaultProvider}" is not a registered analytics provider (registered: ${analyticsProviders
739
+ `analytics provider "${activeId}" is not registered (registered: ${analyticsProviders
619
740
  .getAll()
620
741
  .map((p) => p.meta.id)
621
742
  .join(", ")})`,
@@ -773,6 +894,8 @@ export function createHogsendClient(
773
894
  analytics,
774
895
  identity,
775
896
  registry,
897
+ journeySources: getJourneySources(),
898
+ journeySourceLocations: getJourneySourceLocations(),
776
899
  bucketRegistry,
777
900
  listRegistry,
778
901
  connectorRegistry,
package/src/index.ts CHANGED
@@ -186,18 +186,41 @@ export {
186
186
  defineJourney,
187
187
  } from "./journeys/define-journey.js";
188
188
  export { JourneyExitedError } from "./journeys/errors.js";
189
+ // --- Journey graph extractor (Studio visual workflow) ---
190
+ export {
191
+ buildJourneyGraph,
192
+ degradedGraphFromMeta,
193
+ } from "./journeys/graph/build-graph.js";
189
194
  export {
190
195
  createMemoize,
191
196
  deriveJourneyKey,
192
197
  getJourneyBoundary,
193
198
  type JourneyBoundary,
199
+ parseJourneySendSite,
194
200
  registerKey,
195
201
  runWithJourneyBoundary,
196
202
  } from "./journeys/journey-boundary.js";
197
203
  export { createJourneyContext } from "./journeys/journey-context.js";
204
+ // --- Journey transition log (journey_logs writer — Phase 2 per-stage metrics) ---
205
+ export {
206
+ type JourneyLogAction,
207
+ type LogTransitionArgs,
208
+ logTransition,
209
+ } from "./journeys/journey-log.js";
210
+ export {
211
+ getJourneySourceLocations,
212
+ resetJourneySourceLocations,
213
+ setJourneySourceLocations,
214
+ } from "./journeys/journey-source-locations-singleton.js";
215
+ export {
216
+ getJourneySources,
217
+ resetJourneySources,
218
+ setJourneySources,
219
+ } from "./journeys/journey-sources-singleton.js";
198
220
  export {
199
221
  buildJourneyRegistry,
200
222
  parseEnabledFilter,
223
+ resolveEnabledFilter,
201
224
  selectJourneyTasks,
202
225
  } from "./journeys/registry.js";
203
226
  export {
@@ -12,3 +12,12 @@
12
12
  */
13
13
  export const JOURNEY_EXECUTION_TIMEOUT_HOURS = 720;
14
14
  export const JOURNEY_EXECUTION_TIMEOUT = `${JOURNEY_EXECUTION_TIMEOUT_HOURS}h`;
15
+
16
+ /**
17
+ * Max time a journey task may wait in the queue for a worker slot before Hatchet
18
+ * cancels it (`scheduleTimeout`). The SDK default (~5m) is too tight for a
19
+ * durable-wait RESUME that re-queues during a redeploy when every worker slot is
20
+ * momentarily saturated — the resume would be cancelled and the enrollment
21
+ * stranded. 15m gives resumes head-room to land on a freed slot.
22
+ */
23
+ export const JOURNEY_SCHEDULE_TIMEOUT = "15m";
@@ -1,5 +1,10 @@
1
+ import { fileURLToPath } from "node:url";
1
2
  import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
2
- import { evaluatePropertyConditions, normalizeWhere } from "@hogsend/core";
3
+ import {
4
+ evaluatePropertyConditions,
5
+ type JourneySourceLocation,
6
+ normalizeWhere,
7
+ } from "@hogsend/core";
3
8
  import type {
4
9
  JourneyMeta,
5
10
  JourneyMetaInput,
@@ -19,7 +24,10 @@ import { createLogger } from "../lib/logger.js";
19
24
  import { emitOutbound } from "../lib/outbound.js";
20
25
  import { resolveTimezoneWithSource } from "../lib/timezone.js";
21
26
  import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
22
- import { JOURNEY_EXECUTION_TIMEOUT } from "./constants.js";
27
+ import {
28
+ JOURNEY_EXECUTION_TIMEOUT,
29
+ JOURNEY_SCHEDULE_TIMEOUT,
30
+ } from "./constants.js";
23
31
  import { JourneyExitedError } from "./errors.js";
24
32
  import {
25
33
  createMemoize,
@@ -28,6 +36,7 @@ import {
28
36
  supportsEviction,
29
37
  } from "./journey-boundary.js";
30
38
  import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
39
+ import { logTransition } from "./journey-log.js";
31
40
  import { getJourneyRegistrySingleton } from "./registry-singleton.js";
32
41
 
33
42
  const logger = createLogger(process.env.LOG_LEVEL);
@@ -62,12 +71,111 @@ interface EventPayloadInput {
62
71
  export interface DefinedJourney {
63
72
  meta: JourneyMeta;
64
73
  task: ReturnType<typeof hatchet.durableTask>;
74
+ /**
75
+ * The journey's `run` function serialized via `Function.prototype.toString()`,
76
+ * captured at definition time. This is the substrate the Studio journey-graph
77
+ * extractor parses (with acorn) to derive a visual workflow. The bundler never
78
+ * minifies (see `tsup` config), so the string is standard, non-minified JS.
79
+ *
80
+ * Best-effort: `undefined` if serialization throws (some exotic runtimes
81
+ * disallow `.toString()`); the extractor degrades to a meta-only graph. Capture
82
+ * is side-effect-free and must NEVER change execution semantics.
83
+ */
84
+ runSource?: string;
85
+ /**
86
+ * Absolute file path + 1-based line of the consumer's `defineJourney(...)`
87
+ * call, captured from the stack at definition time (for the Studio "open in
88
+ * editor" affordance). Best-effort: `undefined` when unavailable. Capture is
89
+ * side-effect-free and must NEVER change execution semantics.
90
+ */
91
+ source?: JourneySourceLocation;
92
+ }
93
+
94
+ /**
95
+ * Serialize a function to source, never throwing. Some engines can refuse
96
+ * `Function.prototype.toString()` (e.g. bound/native shims); a failure here must
97
+ * degrade to `undefined`, not break `defineJourney`.
98
+ */
99
+ function safeRunSource(fn: JourneyRunFn): string | undefined {
100
+ try {
101
+ return fn.toString();
102
+ } catch {
103
+ return undefined;
104
+ }
105
+ }
106
+
107
+ /**
108
+ * Absolute path of THIS module, resolved once. Every stack frame inside
109
+ * define-journey (the capture helper AND `defineJourney` itself) resolves to
110
+ * this path, so the call-site parser skips them and returns the FIRST external
111
+ * frame — the consumer's `defineJourney(...)` site. Works whether the engine
112
+ * runs as `.ts` source (tsx dev, the local dogfood path) or compiled `.js`
113
+ * (dist): self and frames are captured in the same representation.
114
+ */
115
+ const SELF_FILE = fileURLToPath(import.meta.url);
116
+
117
+ /**
118
+ * Capture the consumer's `defineJourney` call-site `{ path, line }` from a fresh
119
+ * stack, so the Studio can deep-link an editor (`cursor://file/<path>:<line>`).
120
+ * Best-effort + side-effect-free: returns `undefined` if the stack is missing
121
+ * or unparseable. NEVER throws and NEVER changes execution semantics.
122
+ *
123
+ * Handles both frame shapes V8 emits:
124
+ * `at fn (/abs/file.ts:LINE:COL)` (named — tsx source-mapped, bare path)
125
+ * `at file:///abs/file.js:LINE:COL` (anonymous top-level — `file://`, no parens)
126
+ * `fileURLToPath` also URL-decodes `file://` paths (spaces, etc). Skips node
127
+ * internals, node_modules, and every frame inside this module (SELF_FILE).
128
+ */
129
+ function captureCallSite(): JourneySourceLocation | undefined {
130
+ const original = Error.stackTraceLimit;
131
+ // Default is 10; the external frame sits ~3 deep. Widen defensively for deep
132
+ // re-export/barrel chains, then restore so we don't perturb global behavior.
133
+ Error.stackTraceLimit = 30;
134
+ const stack = new Error().stack;
135
+ Error.stackTraceLimit = original;
136
+ if (!stack) return undefined;
137
+
138
+ for (const rawLine of stack.split("\n").slice(1)) {
139
+ const line = rawLine.trim();
140
+ if (!line.startsWith("at ")) continue;
141
+
142
+ // Location token = the parenthesized group when present, else the text
143
+ // right after "at " (anonymous frames carry no parens).
144
+ const paren = line.match(/\(([^)]+)\)\s*$/);
145
+ const token = paren?.[1] ?? line.slice(3).trim();
146
+
147
+ // Strip the trailing ":line:col" (col optional) to isolate the file part.
148
+ const m =
149
+ token.match(/^(.*?):(\d+):(\d+)$/) ?? token.match(/^(.*?):(\d+)$/);
150
+ const filePart = m?.[1];
151
+ const lineNo = m?.[2];
152
+ if (!filePart || !lineNo) continue;
153
+
154
+ let file = filePart;
155
+ if (file.startsWith("file://")) {
156
+ try {
157
+ file = fileURLToPath(file);
158
+ } catch {
159
+ continue;
160
+ }
161
+ }
162
+
163
+ // First frame that clears all three is the consumer's call site.
164
+ if (file.startsWith("node:")) continue;
165
+ if (file.includes("node_modules")) continue;
166
+ if (file === SELF_FILE) continue;
167
+
168
+ return { path: file, line: Number(lineNo) };
169
+ }
170
+ return undefined;
65
171
  }
66
172
 
67
173
  export function defineJourney(options: {
68
174
  meta: JourneyMetaInput;
69
175
  run: JourneyRunFn;
70
176
  }): DefinedJourney {
177
+ const runSource = safeRunSource(options.run);
178
+ const source = captureCallSite();
71
179
  const { trigger, exitOn, ...rest } = options.meta;
72
180
  const triggerWhere = normalizeWhere(trigger.where);
73
181
  const meta: JourneyMeta = {
@@ -93,7 +201,20 @@ export function defineJourney(options: {
93
201
  name: `journey-${meta.id}`,
94
202
  onEvents: [meta.trigger.event],
95
203
  executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
204
+ // retries STAYS 0 — deliberately. A retry replays `run()` from the top, and
205
+ // the tracked mailer / connector machinery is "missed > doubled": a `queued`
206
+ // row is RE-DRIVEN and a failed send NULLs its idempotency key (tracked.ts
207
+ // ~150-176, 496-514). That is safe only while nothing re-invokes a run whose
208
+ // `provider.send()` already delivered but whose durable status flip didn't
209
+ // commit — turning retries on would re-deliver that email/connector message
210
+ // (a DUPLICATE). Enabling retries requires making sends provider-idempotent
211
+ // first (Resend/Postmark `Idempotency-Key`); tracked as a follow-up.
96
212
  retries: 0,
213
+ // `scheduleTimeout` widens the queue-wait ceiling (SDK default ~5m) so a
214
+ // durable-wait RESUME re-queued during a redeploy's slot saturation reclaims
215
+ // a slot instead of being cancelled (which strands the enrollment). Unlike
216
+ // retries this adds NO replay — it is pure head-room, so it is safe on its own.
217
+ scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
97
218
  fn: async (input: EventPayloadInput, hatchetCtx) => {
98
219
  const db = getDb();
99
220
  const userId = input.userId as string;
@@ -206,6 +327,20 @@ export function defineJourney(options: {
206
327
  }
207
328
 
208
329
  const stateId = state.id;
330
+
331
+ // Fire-and-forget enrollment transition (FRESH entry only — a replay
332
+ // recovers `state` by run id above and must NOT re-log an entry). Writes
333
+ // `journey_logs` best-effort; never throws into / alters execution.
334
+ if (!recovered) {
335
+ logTransition({
336
+ db,
337
+ journeyStateId: stateId,
338
+ from: null,
339
+ to: "start",
340
+ action: "entered",
341
+ });
342
+ }
343
+
209
344
  // The replay-stable key anchor: prefer the run id (constant across replays
210
345
  // of this run), fall back to stateId when the engine has no run id.
211
346
  const runAnchor = workflowRunId || stateId;
@@ -230,9 +365,14 @@ export function defineJourney(options: {
230
365
  // Independent I/O — fetch the contact row and PostHog person props
231
366
  // concurrently. PostHog failures fall through to undefined.
232
367
  const [contact, posthogProperties] = await Promise.all([
233
- db.query.contacts.findFirst({
234
- where: eq(contacts.externalId, userId),
235
- }),
368
+ // Both legs are best-effort tz inputs: a failure here must fall through
369
+ // to the client-default tz, never reject the `Promise.all` and throw out
370
+ // of `fn` BEFORE the try/catch below (which would strand the row —
371
+ // already inserted "active" — outside the failure handling). The PostHog
372
+ // leg already `.catch`es; mirror it on the contact read.
373
+ db.query.contacts
374
+ .findFirst({ where: eq(contacts.externalId, userId) })
375
+ .catch(() => undefined),
236
376
  posthog?.getPersonProperties(userId).catch(() => undefined),
237
377
  ]);
238
378
 
@@ -318,6 +458,15 @@ export function defineJourney(options: {
318
458
  })
319
459
  .where(eq(journeyStates.id, stateId));
320
460
 
461
+ // Fire-and-forget completion transition (best-effort; never throws).
462
+ logTransition({
463
+ db,
464
+ journeyStateId: stateId,
465
+ from: boundary.currentLabel ?? null,
466
+ to: "end-completed",
467
+ action: "completed",
468
+ });
469
+
321
470
  await hatchet.events.push("journey:completed", {
322
471
  journeyId: meta.id,
323
472
  stateId,
@@ -393,6 +542,18 @@ export function defineJourney(options: {
393
542
  error: message,
394
543
  });
395
544
 
545
+ // Fire-and-forget failure transition — only reached when a row was
546
+ // actually flipped to "failed" (the guard above). `to` is the best-effort
547
+ // last durable node (approximate — see plan Guardrails). Never throws.
548
+ logTransition({
549
+ db,
550
+ journeyStateId: stateId,
551
+ from: null,
552
+ to: boundary.currentLabel ?? state.currentNodeId ?? null,
553
+ action: "failed",
554
+ detail: { error: message },
555
+ });
556
+
396
557
  await hatchet.events.push("journey:failed", {
397
558
  journeyId: meta.id,
398
559
  stateId,
@@ -405,5 +566,5 @@ export function defineJourney(options: {
405
566
  },
406
567
  });
407
568
 
408
- return { meta, task };
569
+ return { meta, task, runSource, source };
409
570
  }