@hogsend/engine 0.38.2 → 0.40.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/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,13 +15,14 @@ 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 {
21
22
  buildBucketRegistry,
22
23
  collectBucketReactionJourneys,
23
24
  } from "./buckets/registry.js";
25
+ import type { DefinedCampaign } from "./campaigns/define-campaign.js";
24
26
  import {
25
27
  ConnectorActionRegistry,
26
28
  setConnectorActionRegistry,
@@ -41,6 +43,8 @@ import {
41
43
  import { env } from "./env.js";
42
44
  import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
43
45
  import type { DefinedJourney } from "./journeys/define-journey.js";
46
+ import { getJourneySourceLocations } from "./journeys/journey-source-locations-singleton.js";
47
+ import { getJourneySources } from "./journeys/journey-sources-singleton.js";
44
48
  import { buildJourneyRegistry } from "./journeys/registry.js";
45
49
  import {
46
50
  isAnalyticsProvider,
@@ -75,7 +79,11 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
75
79
  import { sendResetPasswordEmail } from "./lib/reset-email.js";
76
80
  import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
77
81
  import { prepareTrackedHtml } from "./lib/tracking.js";
78
- import type { DefinedList } from "./lists/define-list.js";
82
+ import {
83
+ type DefinedList,
84
+ isReservedListId,
85
+ RESERVED_LIST_IDS,
86
+ } from "./lists/define-list.js";
79
87
  import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
80
88
  import {
81
89
  type DefinedWebhookSource,
@@ -147,6 +155,20 @@ export interface HogsendClient {
147
155
  */
148
156
  identity: IdentityService;
149
157
  registry: JourneyRegistry;
158
+ /**
159
+ * Map of enabled journey id → its captured `run` source string. Populated by
160
+ * `buildJourneyRegistry` (skips journeys whose source failed to serialize).
161
+ * Consumed by the Studio journey-graph route, which parses the source lazily
162
+ * with acorn to derive a visual workflow. Empty when no journeys are wired.
163
+ */
164
+ journeySources: Map<string, string>;
165
+ /**
166
+ * Map of enabled journey id → its `defineJourney` call-site `{ path, line }`.
167
+ * Populated by `buildJourneyRegistry`. Consumed by the Studio journey-graph
168
+ * route to build an "open in editor" deep link. Absent ids had no capturable
169
+ * call-site (e.g. bucket-generated reaction journeys).
170
+ */
171
+ journeySourceLocations: Map<string, JourneySourceLocation>;
150
172
  /**
151
173
  * The bucket registry (id map + event/property inverted indexes for candidate
152
174
  * narrowing). Built and installed as the process singleton at client build;
@@ -162,6 +184,12 @@ export interface HogsendClient {
162
184
  * elsewhere via `getListRegistry()`). Empty when no lists are wired.
163
185
  */
164
186
  listRegistry: ListRegistry;
187
+ /**
188
+ * Code-defined one-shot campaigns (broadcasts), verbatim from
189
+ * `opts.campaigns`. The worker's boot reconciler turns them into scheduled
190
+ * `campaigns` rows; empty when none are wired.
191
+ */
192
+ campaigns: DefinedCampaign[];
165
193
  /**
166
194
  * The unified inbound CONNECTOR registry, keyed by `meta.id`. Holds every
167
195
  * transport: webhook (the `:sourceId` dispatch + legacy webhookSources),
@@ -205,6 +233,13 @@ export interface HogsendClientOptions {
205
233
  * preference center. Defaults to none (empty registry ⇒ legacy opt-in).
206
234
  */
207
235
  lists?: DefinedList[];
236
+ /**
237
+ * Code-defined one-shot campaigns (broadcasts) — `defineCampaign()` files.
238
+ * Carried on the client so the worker's boot reconciler can schedule them
239
+ * (see `reconcileDefinedCampaigns`); the API process only stores them.
240
+ * Defaults to none.
241
+ */
242
+ campaigns?: DefinedCampaign[];
208
243
  /**
209
244
  * Email is a first-class channel. Its config is grouped here rather than
210
245
  * spread across top-level args — the engine owns the cohesive email pipeline
@@ -379,16 +414,26 @@ export function createHogsendClient(
379
414
  const created = createDatabase({ url: env.DATABASE_URL });
380
415
  const db = opts.overrides?.db ?? created.db;
381
416
 
417
+ // Resolve buckets + their reaction journeys BEFORE the journey registry so the
418
+ // reaction ids (`bucket-<id>-on-<kind>`, registered separately below) are part
419
+ // of ENABLED_JOURNEYS's known set. They ARE registered journeys, so listing a
420
+ // real reaction id in ENABLED_JOURNEYS must NOT be rejected as a typo.
421
+ const buckets = opts.buckets ?? [];
422
+ const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
423
+ const reactionJourneys = collectBucketReactionJourneys(
424
+ buckets,
425
+ enabledBuckets,
426
+ );
427
+
382
428
  const registry = buildJourneyRegistry(
383
429
  opts.journeys ?? [],
384
430
  opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
431
+ reactionJourneys.map((r) => r.meta.id),
385
432
  );
386
433
 
387
434
  // Installs the bucket registry singleton in BOTH the API and worker processes
388
435
  // (both call createHogsendClient); the real-time ingest path reads it via
389
436
  // getBucketRegistrySingleton().
390
- const buckets = opts.buckets ?? [];
391
- const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
392
437
  const bucketRegistry = buildBucketRegistry(buckets, enabledBuckets);
393
438
 
394
439
  // Register the reaction journeys generated by `bucket.on()` into the journey
@@ -398,10 +443,7 @@ export function createHogsendClient(
398
443
  // be subject to the journeys csv (Section 9). Both API and worker call
399
444
  // createHogsendClient, so the singleton carries reaction metas in both
400
445
  // processes (needed for admin feedsJourneys + the dwell-cron lookup).
401
- for (const reaction of collectBucketReactionJourneys(
402
- buckets,
403
- enabledBuckets,
404
- )) {
446
+ for (const reaction of reactionJourneys) {
405
447
  registry.register(reaction.meta);
406
448
  }
407
449
 
@@ -500,6 +542,81 @@ export function createHogsendClient(
500
542
 
501
543
  const templates = opts.email?.templates ?? ({} as TemplateRegistry);
502
544
 
545
+ // Boot-validate every template's `category` against the resolvable list
546
+ // namespace BEFORE the mailer/emailService is constructed — fail CLOSED.
547
+ //
548
+ // A template's `category` (TemplateDefinition.category) IS the
549
+ // email-preferences list key: at send time `lib/tracked.ts` resolves the
550
+ // effective category and `checkSuppression` gates it through
551
+ // `ListRegistry.isSubscribed`, whose `isSubscribedByDefault` legacy fallback
552
+ // is `this.get(id)?.defaultOptIn ?? true`. So a TYPO'd category (e.g.
553
+ // "product-update" when the opt-in list id is "product-updates") resolves to
554
+ // an UNKNOWN id → `?? true` opt-in default → treated as subscribed → NOT
555
+ // suppressed. The consent/opt-in email would then be delivered to EVERY
556
+ // recipient (including never-subscribed) AND anyone who unsubscribed under the
557
+ // correct key would still receive it — CAN-SPAM/GDPR-grade. This guard makes a
558
+ // mismatched category a loud boot failure so it can never reach that fallback.
559
+ //
560
+ // Known-good set = reserved built-ins ∪ DEFINED lists (`opts.lists`), NOT just
561
+ // the ENABLED registry — mirroring the ENABLED_JOURNEYS lesson (validate
562
+ // against DEFINED, not just ENABLED). A DEFINED-but-registry-EXCLUDED list
563
+ // (removed from the registry by an ENABLED_LISTS allowlist that doesn't name
564
+ // it) does NOT auto-warn: excluding it flips the send-time gate by POLARITY,
565
+ // so we branch on `defaultOptIn` (below). We carry each list's `defaultOptIn`
566
+ // (not just its id) so that branch can decide THROW vs WARN. This does NOT
567
+ // change the send-time suppression logic; it only prevents a bad/consent-
568
+ // flipping category reaching it.
569
+ const definedLists = new Map(
570
+ (opts.lists ?? []).map((l) => [l.meta.id, l.meta.defaultOptIn] as const),
571
+ );
572
+ for (const [templateKey, def] of Object.entries(templates)) {
573
+ const category = (def as TemplateDefinition | undefined)?.category;
574
+ // No category ⇒ no per-list gating for this template; nothing to validate.
575
+ if (!category) continue;
576
+ // Reserved built-in category (transactional / journey) — never a list, but
577
+ // a legitimate `email_preferences.categories` key. OK.
578
+ if (isReservedListId(category)) continue;
579
+ // Category names a REGISTERED list ⇒ suppression/preferences gate correctly.
580
+ // (Note: a `defineList({ enabled:false })` is STILL registered — the
581
+ // registry filters on ENABLED_LISTS only, never `meta.enabled` — so it
582
+ // lands here, not in the excluded branch below.)
583
+ if (listRegistry.has(category)) continue;
584
+ // Category names a DEFINED list that is EXCLUDED from the registry by an
585
+ // ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
586
+ // send-time check fall back to the legacy `?? true` opt-in default, which
587
+ // FLIPS the gate by polarity:
588
+ // • opt-IN list (`defaultOptIn:false`, consent required): enabled →
589
+ // `categories[id] === true` (never-consented = NOT subscribed =
590
+ // suppressed); excluded → `categories[id] !== false` (never-consented =
591
+ // SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
592
+ // never opted in. Disabling un-gates consent → THROW (fail closed).
593
+ // • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
594
+ // `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
595
+ const definedOptIn = definedLists.get(category);
596
+ if (definedOptIn !== undefined) {
597
+ if (definedOptIn === false) {
598
+ throw new Error(
599
+ `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.`,
600
+ );
601
+ }
602
+ logger.warn(
603
+ `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.`,
604
+ );
605
+ continue;
606
+ }
607
+ // Unknown category: neither a reserved built-in nor a defined list. At send
608
+ // time this resolves to the `?? true` opt-in default, bypassing
609
+ // suppression/consent. Fail CLOSED with an actionable message.
610
+ const knownLists = [...definedLists.keys()];
611
+ throw new Error(
612
+ `Email template "${templateKey}" has category "${category}", which is neither a reserved built-in category (${[
613
+ ...RESERVED_LIST_IDS,
614
+ ].join(", ")}) nor a defined email list (${
615
+ knownLists.length ? knownLists.join(", ") : "none"
616
+ }). 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.`,
617
+ );
618
+ }
619
+
503
620
  const emailService =
504
621
  opts.overrides?.mailer ??
505
622
  createTrackedMailer(
@@ -557,6 +674,11 @@ export function createHogsendClient(
557
674
  db,
558
675
  secret: env.BETTER_AUTH_SECRET,
559
676
  baseURL: env.BETTER_AUTH_URL,
677
+ // Give the engine (Studio/dogfood, e.g. t.hogsend.com) its OWN cookie
678
+ // namespace so its session cookie stops colliding with a sibling web
679
+ // app's `.hogsend.com` cross-subdomain SSO cookie. Env default is
680
+ // "hogsend"; no deploy needs to set AUTH_COOKIE_PREFIX explicitly.
681
+ cookiePrefix: env.AUTH_COOKIE_PREFIX,
560
682
  secondaryStorage: authSecondaryStorage,
561
683
  // Always trust the public API origin; add any explicitly configured ones
562
684
  // (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
@@ -611,11 +733,29 @@ export function createHogsendClient(
611
733
  : wrapLegacyAnalyticsService(analyticsOpt as PostHogService);
612
734
  analyticsProviders.register(analytics);
613
735
  } else {
736
+ // Resolve the ONE active analytics provider by id — the analytics sibling of
737
+ // the email-provider resolution above, and fail loud on an unresolved
738
+ // active id exactly like `EMAIL_PROVIDER` does. `env.ANALYTICS_PROVIDER`
739
+ // carries a zod `.default("posthog")`, so the resolved id is never empty —
740
+ // that default is what AUTO-ACTIVATES the PostHog env preset when
741
+ // `POSTHOG_API_KEY` is set. Because of that default we must NOT fail boot
742
+ // merely because the resolved id is unregistered: an operator who wired NO
743
+ // analytics still resolves "posthog" and legitimately has no provider (leave
744
+ // `analytics` undefined — reads/mirror stay no-ops). So the throw is gated on
745
+ // the id being EXPLICITLY requested — a code `defaultProvider` OR a SET
746
+ // `ANALYTICS_PROVIDER` env. The RAW `process.env` read (mirroring the
747
+ // `REDIS_URL` read above) is what distinguishes an explicit request from the
748
+ // zod default; without this gate a bogus `ANALYTICS_PROVIDER` typo would
749
+ // SILENTLY disable analytics (killing tz person-reads + the event mirror)
750
+ // instead of failing loud.
614
751
  const activeId = analyticsGroup?.defaultProvider ?? env.ANALYTICS_PROVIDER;
752
+ const explicitlyRequested = Boolean(
753
+ analyticsGroup?.defaultProvider ?? process.env.ANALYTICS_PROVIDER,
754
+ );
615
755
  analytics = analyticsProviders.get(activeId);
616
- if (analyticsGroup?.defaultProvider && !analytics) {
756
+ if (explicitlyRequested && !analytics) {
617
757
  throw new Error(
618
- `analytics.defaultProvider "${analyticsGroup.defaultProvider}" is not a registered analytics provider (registered: ${analyticsProviders
758
+ `analytics provider "${activeId}" is not registered (registered: ${analyticsProviders
619
759
  .getAll()
620
760
  .map((p) => p.meta.id)
621
761
  .join(", ")})`,
@@ -773,8 +913,11 @@ export function createHogsendClient(
773
913
  analytics,
774
914
  identity,
775
915
  registry,
916
+ journeySources: getJourneySources(),
917
+ journeySourceLocations: getJourneySourceLocations(),
776
918
  bucketRegistry,
777
919
  listRegistry,
920
+ campaigns: opts.campaigns ?? [],
778
921
  connectorRegistry,
779
922
  connectorActionRegistry,
780
923
  hatchet: opts.overrides?.hatchet ?? hatchet,
package/src/env.ts CHANGED
@@ -55,6 +55,20 @@ export const env = createEnv({
55
55
  // comma-separated. Needed when the Studio is served from a different origin
56
56
  // than the API — e.g. the `hogsend studio` CLI pointing at a remote instance.
57
57
  BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
58
+ // Cookie NAMESPACE for the engine's own Better Auth (the Studio/dogfood at
59
+ // e.g. t.hogsend.com). Better Auth derives the session cookie name as
60
+ // `<__Secure->?<prefix>.session_token`; with Better Auth's default
61
+ // "better-auth" prefix the engine cookie shares a NAME with any sibling web
62
+ // app that sets a cross-subdomain cookie on the shared parent (e.g.
63
+ // course/docs on `.hogsend.com`), which the browser also delivers to the
64
+ // Studio host — same name, DIFFERENT database → null session → Studio login
65
+ // loop. Defaulting to "hogsend" gives the engine its own namespace
66
+ // (__Secure-hogsend.session_token) so that sibling cookie is simply ignored
67
+ // here. MUST stay optional-with-default — a required value would fail env
68
+ // validation on every deploy that doesn't set it. Prefix affects the cookie
69
+ // NAME only; it is orthogonal to crossSubDomainCookies (the Domain attr),
70
+ // which the engine never sets (host-only).
71
+ AUTH_COOKIE_PREFIX: z.string().min(1).default("hogsend"),
58
72
  // Optional: a deploy may run a non-Resend provider (Postmark, SES…) and set
59
73
  // no Resend key at all. Read directly ONLY in the lazy-resend default branch
60
74
  // (container.ts) and the future `emailProvidersFromEnv` preset. With this
package/src/index.ts CHANGED
@@ -96,6 +96,18 @@ export {
96
96
  resetBucketRegistry,
97
97
  setBucketRegistry,
98
98
  } from "./buckets/registry-singleton.js";
99
+ // --- Campaigns (one-shot broadcasts) ---
100
+ export {
101
+ type CampaignAudience,
102
+ type CampaignMeta,
103
+ DEFINED_CAMPAIGN_KEY_PREFIX,
104
+ type DefinedCampaign,
105
+ defineCampaign,
106
+ } from "./campaigns/define-campaign.js";
107
+ export {
108
+ type ReconcileResult,
109
+ reconcileDefinedCampaigns,
110
+ } from "./campaigns/reconcile.js";
99
111
  // --- Cold-connect (email-confirmed chat-platform contact linking) ---
100
112
  export {
101
113
  type ColdConnect,
@@ -186,18 +198,41 @@ export {
186
198
  defineJourney,
187
199
  } from "./journeys/define-journey.js";
188
200
  export { JourneyExitedError } from "./journeys/errors.js";
201
+ // --- Journey graph extractor (Studio visual workflow) ---
202
+ export {
203
+ buildJourneyGraph,
204
+ degradedGraphFromMeta,
205
+ } from "./journeys/graph/build-graph.js";
189
206
  export {
190
207
  createMemoize,
191
208
  deriveJourneyKey,
192
209
  getJourneyBoundary,
193
210
  type JourneyBoundary,
211
+ parseJourneySendSite,
194
212
  registerKey,
195
213
  runWithJourneyBoundary,
196
214
  } from "./journeys/journey-boundary.js";
197
215
  export { createJourneyContext } from "./journeys/journey-context.js";
216
+ // --- Journey transition log (journey_logs writer — Phase 2 per-stage metrics) ---
217
+ export {
218
+ type JourneyLogAction,
219
+ type LogTransitionArgs,
220
+ logTransition,
221
+ } from "./journeys/journey-log.js";
222
+ export {
223
+ getJourneySourceLocations,
224
+ resetJourneySourceLocations,
225
+ setJourneySourceLocations,
226
+ } from "./journeys/journey-source-locations-singleton.js";
227
+ export {
228
+ getJourneySources,
229
+ resetJourneySources,
230
+ setJourneySources,
231
+ } from "./journeys/journey-sources-singleton.js";
198
232
  export {
199
233
  buildJourneyRegistry,
200
234
  parseEnabledFilter,
235
+ resolveEnabledFilter,
201
236
  selectJourneyTasks,
202
237
  } from "./journeys/registry.js";
203
238
  export {
@@ -572,7 +607,10 @@ export {
572
607
  type SuppressionImportRow,
573
608
  type SuppressionReason,
574
609
  } from "./workflows/import-suppressions.js";
575
- export { sendCampaignTask } from "./workflows/send-campaign.js";
610
+ export {
611
+ reapStuckCampaignsTask,
612
+ sendCampaignTask,
613
+ } from "./workflows/send-campaign.js";
576
614
  // --- Built-in Hatchet workflow tasks ---
577
615
  export { sendEmailTask } from "./workflows/send-email.js";
578
616
  export { sendFeedTask } from "./workflows/send-feed.js";
@@ -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
  }