@hogsend/engine 0.38.2 → 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.2",
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.2",
46
- "@hogsend/db": "^0.38.2",
47
- "@hogsend/email": "^0.38.2",
48
- "@hogsend/plugin-posthog": "^0.38.2",
49
- "@hogsend/plugin-resend": "^0.38.2"
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.2"
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 {
@@ -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,
@@ -31,6 +36,7 @@ import {
31
36
  supportsEviction,
32
37
  } from "./journey-boundary.js";
33
38
  import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
39
+ import { logTransition } from "./journey-log.js";
34
40
  import { getJourneyRegistrySingleton } from "./registry-singleton.js";
35
41
 
36
42
  const logger = createLogger(process.env.LOG_LEVEL);
@@ -65,12 +71,111 @@ interface EventPayloadInput {
65
71
  export interface DefinedJourney {
66
72
  meta: JourneyMeta;
67
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;
68
171
  }
69
172
 
70
173
  export function defineJourney(options: {
71
174
  meta: JourneyMetaInput;
72
175
  run: JourneyRunFn;
73
176
  }): DefinedJourney {
177
+ const runSource = safeRunSource(options.run);
178
+ const source = captureCallSite();
74
179
  const { trigger, exitOn, ...rest } = options.meta;
75
180
  const triggerWhere = normalizeWhere(trigger.where);
76
181
  const meta: JourneyMeta = {
@@ -222,6 +327,20 @@ export function defineJourney(options: {
222
327
  }
223
328
 
224
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
+
225
344
  // The replay-stable key anchor: prefer the run id (constant across replays
226
345
  // of this run), fall back to stateId when the engine has no run id.
227
346
  const runAnchor = workflowRunId || stateId;
@@ -339,6 +458,15 @@ export function defineJourney(options: {
339
458
  })
340
459
  .where(eq(journeyStates.id, stateId));
341
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
+
342
470
  await hatchet.events.push("journey:completed", {
343
471
  journeyId: meta.id,
344
472
  stateId,
@@ -414,6 +542,18 @@ export function defineJourney(options: {
414
542
  error: message,
415
543
  });
416
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
+
417
557
  await hatchet.events.push("journey:failed", {
418
558
  journeyId: meta.id,
419
559
  stateId,
@@ -426,5 +566,5 @@ export function defineJourney(options: {
426
566
  },
427
567
  });
428
568
 
429
- return { meta, task };
569
+ return { meta, task, runSource, source };
430
570
  }