@hogsend/engine 0.46.1 → 0.50.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/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/connectors/presets/index.ts +8 -2
  4. package/src/container.ts +149 -7
  5. package/src/destinations/presets/posthog.ts +7 -0
  6. package/src/destinations/presets/segment.ts +5 -0
  7. package/src/env.ts +38 -0
  8. package/src/flags/reconcile.ts +195 -0
  9. package/src/index.ts +79 -0
  10. package/src/journeys/authoring.ts +32 -0
  11. package/src/journeys/define-journey.ts +45 -40
  12. package/src/journeys/execute-journey-run.ts +73 -32
  13. package/src/journeys/journey-boundary.ts +76 -0
  14. package/src/journeys/journey-context.ts +128 -70
  15. package/src/journeys/journey-task-factory.ts +31 -0
  16. package/src/journeys/journey-task-runtime.ts +31 -0
  17. package/src/journeys/journey-version.test.ts +236 -0
  18. package/src/journeys/journey-version.ts +158 -0
  19. package/src/journeys/record-once.ts +28 -2
  20. package/src/lib/connector-actions.test.ts +36 -0
  21. package/src/lib/connector-actions.ts +42 -4
  22. package/src/lib/contacts.ts +49 -0
  23. package/src/lib/conversions.test.ts +33 -0
  24. package/src/lib/conversions.ts +8 -0
  25. package/src/lib/email.ts +23 -2
  26. package/src/lib/enrollment-policy.ts +51 -0
  27. package/src/lib/feed.ts +55 -3
  28. package/src/lib/flags-registry.ts +48 -0
  29. package/src/lib/flags.ts +498 -0
  30. package/src/lib/fx.ts +374 -0
  31. package/src/lib/global-control-readout.ts +166 -0
  32. package/src/lib/groups.ts +362 -0
  33. package/src/lib/ingestion.ts +38 -0
  34. package/src/lib/journey-lift.ts +142 -0
  35. package/src/lib/operator-settings.ts +71 -0
  36. package/src/lib/outbound.ts +147 -0
  37. package/src/lib/preferences.ts +6 -80
  38. package/src/lib/recipient-preferences.ts +53 -0
  39. package/src/lib/sms.ts +21 -2
  40. package/src/lib/stable-stringify.test.ts +42 -0
  41. package/src/lib/stable-stringify.ts +23 -0
  42. package/src/lib/variant.ts +99 -0
  43. package/src/lib/webhook-signing.ts +16 -1
  44. package/src/lists/registry.ts +6 -2
  45. package/src/lists/subscription.ts +13 -0
  46. package/src/routes/admin/contacts.ts +53 -4
  47. package/src/routes/admin/conversions.ts +137 -0
  48. package/src/routes/admin/flags.ts +369 -0
  49. package/src/routes/admin/groups.ts +866 -0
  50. package/src/routes/admin/impact-schemas.ts +44 -0
  51. package/src/routes/admin/impact-wire.test.ts +181 -0
  52. package/src/routes/admin/impact.ts +486 -0
  53. package/src/routes/admin/index.ts +12 -0
  54. package/src/routes/admin/journey-impact.ts +446 -0
  55. package/src/routes/admin/journeys.ts +70 -100
  56. package/src/routes/admin/settings.ts +145 -0
  57. package/src/routes/admin/targeting.ts +256 -0
  58. package/src/routes/events/index.ts +11 -0
  59. package/src/routes/flags/index.ts +120 -0
  60. package/src/routes/groups/index.ts +417 -0
  61. package/src/routes/index.ts +23 -1
  62. package/src/testing.ts +25 -0
  63. package/src/webhook-sources/presets/index.ts +5 -1
  64. package/src/webhook-sources/presets/intercom.ts +230 -0
  65. package/src/webhook-sources/presets/segment.ts +56 -4
  66. package/src/worker.ts +3 -0
  67. package/src/workflows/bucket-backfill.ts +1 -14
  68. package/src/workflows/impact-digest.ts +761 -0
  69. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
@@ -15,28 +15,17 @@ import {
15
15
  normalizeWhere,
16
16
  } from "@hogsend/core";
17
17
  import type { JourneyRegistry } from "@hogsend/core/registry";
18
- import {
19
- isValidTimeZone,
20
- resolveAfter,
21
- resolveNextLocalTime,
22
- resolveNextWeekday,
23
- resolveTomorrow,
24
- type SendWindow,
25
- } from "@hogsend/core/schedule";
18
+ import { createWhenBuilder, type SendWindow } from "@hogsend/core/schedule";
26
19
  import type {
27
20
  DigestEvent,
28
21
  DigestOptions,
29
22
  DigestResult,
30
- IfPast,
31
23
  JourneyContext,
32
24
  PropertyCondition,
33
25
  RecentEvent,
34
26
  ThrottleOptions,
35
27
  ThrottleResult,
36
- TimeOfDayBuilder,
37
28
  WaitForEventResult,
38
- Weekday,
39
- WhenBuilder,
40
29
  } from "@hogsend/core/types";
41
30
  import {
42
31
  type Database,
@@ -52,6 +41,7 @@ import {
52
41
  desc,
53
42
  eq,
54
43
  gte,
44
+ isNotNull,
55
45
  lte,
56
46
  max,
57
47
  notInArray,
@@ -62,6 +52,11 @@ import { countRecentSends } from "../lib/frequency-cap.js";
62
52
  import { toSleepDuration } from "../lib/hatchet-duration.js";
63
53
  import { ingestEvent } from "../lib/ingestion.js";
64
54
  import type { Logger } from "../lib/logger.js";
55
+ import {
56
+ pickVariant,
57
+ validateVariantArms,
58
+ validateVariantKey,
59
+ } from "../lib/variant.js";
65
60
  import {
66
61
  JOURNEY_EXECUTION_TIMEOUT,
67
62
  JOURNEY_EXECUTION_TIMEOUT_HOURS,
@@ -98,6 +93,26 @@ const DIGEST_DEFAULT_LOOKBACK: DurationObject = { minutes: 15 };
98
93
  */
99
94
  const digestWarned = new Set<string>();
100
95
 
96
+ /**
97
+ * `journeyId:key` pairs already warned about a recorded-arm / arms-array
98
+ * divergence this process. Warn-once so a replay-from-top (which re-runs the
99
+ * whole `run()`) doesn't spam the log with the same advisory (mirrors
100
+ * digestWarned above).
101
+ */
102
+ const variantWarned = new Set<string>();
103
+
104
+ function warnVariantOnce(
105
+ logger: Logger,
106
+ journeyId: string,
107
+ key: string,
108
+ message: string,
109
+ ): void {
110
+ const warnKey = `${journeyId}:${key}`;
111
+ if (variantWarned.has(warnKey)) return;
112
+ variantWarned.add(warnKey);
113
+ logger.warn(message);
114
+ }
115
+
101
116
  /**
102
117
  * Quote a string as a CEL single-quoted string literal, escaping backslashes
103
118
  * then single quotes. Used to embed an externally-supplied userId into a CEL
@@ -173,64 +188,6 @@ interface JourneyContextConfig {
173
188
  entryPeriod?: DurationObject;
174
189
  }
175
190
 
176
- /**
177
- * Build the timezone-bound fluent scheduler. A thin wrapper over the pure core
178
- * resolvers: it injects the user's resolved tz, the real current instant, and
179
- * the (optionally overridden) send window, returning absolute `Date`s.
180
- */
181
- function createWhenBuilder(opts: {
182
- timezone: string;
183
- window?: SendWindow;
184
- ifPast: IfPast;
185
- /**
186
- * The current instant, supplied by the context so `ctx.when` reads the
187
- * replay-stable (memoized) clock instead of a raw `new Date()` — the resolved
188
- * instant must be identical across a durable replay or a scheduled `.next(...)`
189
- * could land on a different day the second time through.
190
- */
191
- now: () => Date;
192
- }): WhenBuilder {
193
- const baseOpts = () => ({
194
- timezone: opts.timezone,
195
- now: opts.now(),
196
- window: opts.window,
197
- ifPast: opts.ifPast,
198
- });
199
-
200
- const timeBuilder = (resolve: (time: string) => Date): TimeOfDayBuilder => ({
201
- at: (time) => resolve(time),
202
- });
203
-
204
- return {
205
- next(weekday: Weekday) {
206
- return timeBuilder((time) =>
207
- resolveNextWeekday(weekday, time, baseOpts()),
208
- );
209
- },
210
- nextLocal(time: string) {
211
- return resolveNextLocalTime(time, baseOpts());
212
- },
213
- tomorrow() {
214
- return timeBuilder((time) => resolveTomorrow(time, baseOpts()));
215
- },
216
- in(duration: DurationObject) {
217
- return timeBuilder((time) => resolveAfter(duration, time, baseOpts()));
218
- },
219
- tz(timezone: string) {
220
- if (!isValidTimeZone(timezone)) {
221
- throw new TypeError(`ctx.when.tz: invalid timezone "${timezone}"`);
222
- }
223
- return createWhenBuilder({ ...opts, timezone });
224
- },
225
- window(start: string, end: string) {
226
- return createWhenBuilder({ ...opts, window: { start, end } });
227
- },
228
- ifPast(strategy: IfPast) {
229
- return createWhenBuilder({ ...opts, ifPast: strategy });
230
- },
231
- };
232
- }
233
-
234
191
  export function createJourneyContext(
235
192
  config: JourneyContextConfig,
236
193
  ): JourneyContext {
@@ -955,6 +912,103 @@ export function createJourneyContext(
955
912
  });
956
913
  };
957
914
 
915
+ // Deterministic experiment arm (ctx.variant, impact experiments Decision
916
+ // B). Assignment is a pure sha256 bucket (lib/variant.ts), RECORDED once
917
+ // per enrollment under the reserved __variants__ bag; the recorded value
918
+ // wins VERBATIM on every later call within this enrollment — including a
919
+ // replay after a deploy that changed `arms`. compute is SYNCHRONOUS and
920
+ // pure (hash only): no clock, no awaits, no durable calls — ctx.variant is
921
+ // positionally invisible in Hatchet's journal, like ctx.throttle. NO
922
+ // registerRecordLabel: re-reading the same key returning the same arm is
923
+ // intended reuse, not an authoring bug. No boundary-label write, no
924
+ // transition log — the jsonb bag IS the observability.
925
+ const performVariant = async <const A extends readonly [string, ...string[]]>(
926
+ key: string,
927
+ arms: A,
928
+ ): Promise<A[number]> => {
929
+ // 1. KEY SYNTAX ONLY — runs BEFORE the recordOnce read (it gates the
930
+ // jsonb path). Arms validation is deliberately NOT here: a deploy that
931
+ // ships malformed arms must degrade in-flight enrollments to the
932
+ // recorded fast path (no crash), while FRESH assignments still fail
933
+ // loudly in dev via the compute below.
934
+ validateVariantKey(key);
935
+ const journeyId = config.journeyId;
936
+ if (!journeyId) {
937
+ throw new Error(
938
+ "ctx.variant requires the journey id on the context (always set by " +
939
+ "the engine; pass journeyId in test configs)",
940
+ );
941
+ }
942
+
943
+ // 2. RECORD ONCE — first winning writer computes; everyone after
944
+ // (replay, reuse, zombie racer) reads the committed arm back.
945
+ const assigned = await recordOnce({
946
+ db,
947
+ stateId,
948
+ namespace: "__variants__",
949
+ key,
950
+ compute: () => {
951
+ validateVariantArms(arms);
952
+ return pickVariant({ journeyId, key, userId, arms });
953
+ },
954
+ });
955
+
956
+ // 3. TYPE GUARD — a fast-path value that is NOT a string is never
957
+ // returned into author code (defends against pre-stripping legacy rows
958
+ // with injected objects). Recompute from the pure hash (replay-stable by
959
+ // construction) and repair the poisoned slot under a type guard so the
960
+ // impact readout's GROUP BY dimension stays a clean string set. The
961
+ // guarded jsonb_set only ever replaces a NON-string value, so it can
962
+ // never clobber a legitimately committed arm; concurrent repairers
963
+ // compute the identical pure value.
964
+ if (typeof assigned !== "string") {
965
+ warnVariantOnce(
966
+ logger,
967
+ journeyId,
968
+ key,
969
+ `ctx.variant: journey "${journeyId}" key "${key}" carried a ` +
970
+ "non-string recorded value (pre-strip legacy row); recomputed " +
971
+ "the arm deterministically and repaired the record",
972
+ );
973
+ validateVariantArms(arms);
974
+ const fresh = pickVariant({ journeyId, key, userId, arms });
975
+ await db
976
+ .update(journeyStates)
977
+ .set({
978
+ context: sql`jsonb_set(
979
+ coalesce(${journeyStates.context}, '{}'::jsonb),
980
+ ARRAY['__variants__', ${key}]::text[],
981
+ to_jsonb(${fresh}::text),
982
+ true
983
+ )`,
984
+ updatedAt: new Date(),
985
+ })
986
+ .where(
987
+ and(
988
+ eq(journeyStates.id, stateId),
989
+ sql`jsonb_typeof(${journeyStates.context} -> '__variants__' -> ${key}) IS DISTINCT FROM 'string'`,
990
+ ),
991
+ );
992
+ return fresh as A[number];
993
+ }
994
+
995
+ // 4. STALE-ARM ADVISORY — recorded value wins VERBATIM (Decision B),
996
+ // even when a redeploy changed the arms mid-enrollment. Warn once per
997
+ // process per journeyId:key; NEVER throw here.
998
+ if (!(arms as readonly string[]).includes(assigned)) {
999
+ warnVariantOnce(
1000
+ logger,
1001
+ journeyId,
1002
+ key,
1003
+ `ctx.variant: journey "${journeyId}" key "${key}" recorded arm ` +
1004
+ `"${assigned}" is not in the current arms [${arms.join(", ")}]; ` +
1005
+ "returning the recorded arm verbatim (an enrollment keeps its " +
1006
+ "entry-time assignment across deploys)",
1007
+ );
1008
+ }
1009
+ return assigned as A[number];
1010
+ };
1011
+
958
1012
  return {
959
1013
  when: createWhenBuilder({
960
1014
  timezone: resolvedTimezone,
@@ -1139,6 +1193,8 @@ export function createJourneyContext(
1139
1193
  return recordOnce({ db, stateId, namespace: "__once__", key, compute });
1140
1194
  },
1141
1195
 
1196
+ variant: performVariant,
1197
+
1142
1198
  digest(opts) {
1143
1199
  return performDigest(opts);
1144
1200
  },
@@ -1203,6 +1259,7 @@ export function createJourneyContext(
1203
1259
  and(
1204
1260
  eq(emailSends.toEmail, targetEmail),
1205
1261
  eq(emailSends.templateKey, template),
1262
+ isNotNull(emailSends.sentAt),
1206
1263
  ),
1207
1264
  );
1208
1265
 
@@ -1228,6 +1285,7 @@ export function createJourneyContext(
1228
1285
  and(
1229
1286
  eq(smsSends.toPhone, phone),
1230
1287
  eq(smsSends.templateKey, template),
1288
+ isNotNull(smsSends.sentAt),
1231
1289
  ),
1232
1290
  );
1233
1291
 
@@ -0,0 +1,31 @@
1
+ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
+ import type { JourneyMeta, JourneyRunFn } from "@hogsend/core/types";
3
+
4
+ /** The durable Hatchet declaration attached to a production journey. */
5
+ export type JourneyTask = ReturnType<HatchetClient["durableTask"]>;
6
+
7
+ type JourneyTaskFactory = (meta: JourneyMeta, run: JourneyRunFn) => JourneyTask;
8
+
9
+ let taskFactory: JourneyTaskFactory | undefined;
10
+
11
+ /** Install the production Hatchet binding without coupling authoring imports to env. */
12
+ export function installJourneyTaskFactory(factory: JourneyTaskFactory): void {
13
+ taskFactory = factory;
14
+ }
15
+
16
+ export function hasJourneyTaskFactory(): boolean {
17
+ return taskFactory !== undefined;
18
+ }
19
+
20
+ export function createJourneyTask(
21
+ meta: JourneyMeta,
22
+ run: JourneyRunFn,
23
+ ): JourneyTask {
24
+ if (!taskFactory) {
25
+ throw new Error(
26
+ "Journey tasks require the production @hogsend/engine runtime. " +
27
+ "Import createWorker from @hogsend/engine before selecting tasks.",
28
+ );
29
+ }
30
+ return taskFactory(meta, run);
31
+ }
@@ -0,0 +1,31 @@
1
+ import type { JourneyMeta, JourneyRunFn } from "@hogsend/core/types";
2
+ import { hatchet } from "../lib/hatchet.js";
3
+ import {
4
+ JOURNEY_EXECUTION_TIMEOUT,
5
+ JOURNEY_SCHEDULE_TIMEOUT,
6
+ } from "./constants.js";
7
+ import {
8
+ type EventPayloadInput,
9
+ executeJourneyRun,
10
+ } from "./execute-journey-run.js";
11
+ import { installJourneyTaskFactory } from "./journey-task-factory.js";
12
+
13
+ /**
14
+ * Bind pure journey definitions to Hatchet only in production engine entry
15
+ * points. `@hogsend/engine/journeys` deliberately does not import this module,
16
+ * which keeps authoring modules importable without runtime credentials.
17
+ */
18
+ installJourneyTaskFactory((meta: JourneyMeta, run: JourneyRunFn) =>
19
+ hatchet.durableTask({
20
+ name: `journey-${meta.id}`,
21
+ onEvents: [meta.trigger.event],
22
+ executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
23
+ // retries STAYS 0 — deliberately. A retry replays `run()` from the top, and
24
+ // provider delivery cannot yet be made atomic with the durable status flip.
25
+ retries: 0,
26
+ // Give durable-wait resumes enough queue headroom during deploy saturation.
27
+ scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
28
+ fn: async (input: EventPayloadInput, hatchetCtx) =>
29
+ executeJourneyRun({ meta, run, input, hatchetCtx }),
30
+ }),
31
+ );
@@ -0,0 +1,236 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { JourneyMeta, JourneyMetaInput } from "@hogsend/core/types";
4
+ import { stableStringify } from "../lib/stable-stringify.js";
5
+ import { defineJourney } from "./define-journey.js";
6
+ import {
7
+ computeJourneyVersionHash,
8
+ normalizeRunSource,
9
+ } from "./journey-version.js";
10
+
11
+ const GOLDEN_META: JourneyMeta = {
12
+ id: "golden-journey",
13
+ name: "Golden Journey",
14
+ enabled: true,
15
+ trigger: { event: "user.created" },
16
+ entryLimit: "once",
17
+ suppress: { hours: 24 },
18
+ };
19
+
20
+ const GOLDEN_BODY =
21
+ 'async (user, ctx) => {\n // welcome\n await sendEmail({ to: user.email, template: "welcome" });\n}';
22
+
23
+ test("golden values — frozen compatibility contract (hsv1)", () => {
24
+ // Changing normalizeRunSource, stableStringify, the meta exclusion list,
25
+ // or HASH_INPUT_VERSION forks every live cohort exactly once. These
26
+ // literals are the lock: a failing golden means you are knowingly
27
+ // reforking and must bump HASH_INPUT_VERSION instead.
28
+ assert.equal(
29
+ computeJourneyVersionHash({ meta: GOLDEN_META, body: GOLDEN_BODY }),
30
+ "8996a5ccc0e7",
31
+ );
32
+ assert.equal(
33
+ computeJourneyVersionHash({ meta: GOLDEN_META }),
34
+ "8823399b83eb",
35
+ );
36
+ });
37
+
38
+ test("12-hex determinism", () => {
39
+ const h1 = computeJourneyVersionHash({
40
+ meta: GOLDEN_META,
41
+ body: GOLDEN_BODY,
42
+ });
43
+ const h2 = computeJourneyVersionHash({
44
+ meta: GOLDEN_META,
45
+ body: GOLDEN_BODY,
46
+ });
47
+ assert.equal(h1, h2);
48
+ assert.match(h1, /^[0-9a-f]{12}$/);
49
+ });
50
+
51
+ test("whitespace- and comment-only edits do not fork the hash", () => {
52
+ const a = "async (user) => { /* v1 */ await go(user); }";
53
+ const b = "async (user) => {\n // v2 comment\n await go(user);\n}";
54
+ assert.equal(normalizeRunSource(a), "async (user) => { await go(user); }");
55
+ assert.equal(normalizeRunSource(a), normalizeRunSource(b));
56
+ assert.equal(
57
+ computeJourneyVersionHash({ meta: GOLDEN_META, body: a }),
58
+ computeJourneyVersionHash({ meta: GOLDEN_META, body: b }),
59
+ );
60
+ });
61
+
62
+ test("// inside string literals is NOT stripped", () => {
63
+ assert.equal(
64
+ normalizeRunSource('const u = "https://x.dev//a"; // trailing'),
65
+ 'const u = "https://x.dev//a";',
66
+ );
67
+ const withEscapes = 'const s = "a\\"//b"; return s;';
68
+ assert.equal(normalizeRunSource(withEscapes), withEscapes);
69
+ });
70
+
71
+ test("hash forks on every behavior-bearing meta field and on the body", () => {
72
+ const h = (meta: JourneyMeta, body?: string) =>
73
+ computeJourneyVersionHash({ meta, body });
74
+ const H0 = h(GOLDEN_META, GOLDEN_BODY);
75
+ const forks: JourneyMeta[] = [
76
+ { ...GOLDEN_META, trigger: { event: "user.signup" } },
77
+ {
78
+ ...GOLDEN_META,
79
+ trigger: {
80
+ event: "user.created",
81
+ where: [
82
+ { type: "property", property: "plan", operator: "eq", value: "pro" },
83
+ ],
84
+ },
85
+ },
86
+ { ...GOLDEN_META, entryLimit: "unlimited" },
87
+ { ...GOLDEN_META, exitOn: [{ event: "user.churned" }] },
88
+ { ...GOLDEN_META, suppress: { hours: 48 } },
89
+ { ...GOLDEN_META, holdout: { percent: 10 } },
90
+ { ...GOLDEN_META, category: "onboarding" },
91
+ { ...GOLDEN_META, goal: "revenue" },
92
+ ];
93
+ for (const meta of forks) {
94
+ assert.notEqual(h(meta, GOLDEN_BODY), H0);
95
+ }
96
+ assert.notEqual(h(GOLDEN_META, "async () => { await other(); }"), H0);
97
+ });
98
+
99
+ test("display/toggle fields never fork: enabled, name, description, version label", () => {
100
+ const H0 = computeJourneyVersionHash({
101
+ meta: GOLDEN_META,
102
+ body: GOLDEN_BODY,
103
+ });
104
+ const same: JourneyMeta[] = [
105
+ { ...GOLDEN_META, enabled: false },
106
+ { ...GOLDEN_META, name: "Renamed" },
107
+ { ...GOLDEN_META, description: "New copy" },
108
+ { ...GOLDEN_META, version: "v2-label-only" },
109
+ { ...GOLDEN_META, versionHash: "aaaaaaaaaaaa" },
110
+ ];
111
+ for (const meta of same) {
112
+ assert.equal(computeJourneyVersionHash({ meta, body: GOLDEN_BODY }), H0);
113
+ }
114
+ });
115
+
116
+ test("meta key order never forks the hash", () => {
117
+ const reordered = {
118
+ suppress: { hours: 24 },
119
+ entryLimit: "once",
120
+ trigger: { event: "user.created" },
121
+ enabled: true,
122
+ name: "Golden Journey",
123
+ id: "golden-journey",
124
+ } as JourneyMeta;
125
+ assert.equal(
126
+ computeJourneyVersionHash({ meta: reordered, body: GOLDEN_BODY }),
127
+ computeJourneyVersionHash({ meta: GOLDEN_META, body: GOLDEN_BODY }),
128
+ );
129
+ });
130
+
131
+ test("normalizeRunSource never throws and stays deterministic on pathological input", () => {
132
+ // Known limits (spec D1): a // inside a regex literal is misread as a
133
+ // comment start; the scanner exits `template` state at the first
134
+ // backtick, so nested templates / strings / comments inside ${...} are
135
+ // misclassified. In every case the output is a PURE function of the
136
+ // input — determinism is what these assertions lock.
137
+ const cases = [
138
+ 'const s = "unterminated',
139
+ "/* never closed",
140
+ "const t = `a${`b`}c`;",
141
+ 'const t = `x${ /* c */ "y" }z`;',
142
+ "const re = /a//; more();",
143
+ "",
144
+ ];
145
+ for (const input of cases) {
146
+ const once = normalizeRunSource(input);
147
+ assert.equal(normalizeRunSource(input), once);
148
+ assert.equal(typeof once, "string");
149
+ }
150
+ assert.equal(normalizeRunSource(""), "");
151
+ });
152
+
153
+ test("blueprint graph bodies (URLs, escaped quotes) hash stably", () => {
154
+ const graph = {
155
+ journeyId: "bp-golden",
156
+ nodes: [
157
+ {
158
+ id: "start",
159
+ type: "start",
160
+ title: "start",
161
+ meta: { url: "https://example.com/a//b", note: 'she said "hi"' },
162
+ },
163
+ ],
164
+ edges: [],
165
+ };
166
+ const body = stableStringify(graph);
167
+ // The string-aware scanner protects // inside double-quoted JSON string
168
+ // values, including \" escapes.
169
+ assert.ok(normalizeRunSource(body).includes("https://example.com/a//b"));
170
+ const meta: JourneyMeta = {
171
+ id: "bp-golden",
172
+ name: "Blueprint bp-golden",
173
+ enabled: true,
174
+ trigger: { event: "bp.enroll" },
175
+ entryLimit: "unlimited",
176
+ suppress: {},
177
+ };
178
+ const h1 = computeJourneyVersionHash({ meta, body });
179
+ // jsonb round-trip key reordering cannot fork: stableStringify sorts.
180
+ const reorderedGraph = {
181
+ edges: [],
182
+ nodes: [
183
+ {
184
+ meta: { note: 'she said "hi"', url: "https://example.com/a//b" },
185
+ title: "start",
186
+ type: "start",
187
+ id: "start",
188
+ },
189
+ ],
190
+ journeyId: "bp-golden",
191
+ };
192
+ assert.equal(
193
+ computeJourneyVersionHash({ meta, body: stableStringify(reorderedGraph) }),
194
+ h1,
195
+ );
196
+ assert.equal(h1, "858e91668b94");
197
+ });
198
+
199
+ test("defineJourney attaches the content hash and overwrites any authored value", () => {
200
+ const base: JourneyMetaInput = {
201
+ id: "jv-attach",
202
+ name: "Attach",
203
+ enabled: true,
204
+ trigger: { event: "jv.test" },
205
+ entryLimit: "once",
206
+ suppress: {},
207
+ version: "v1",
208
+ };
209
+ const run = async () => {};
210
+ const j1 = defineJourney({ meta: base, run });
211
+ assert.match(j1.meta.versionHash ?? "", /^[0-9a-f]{12}$/);
212
+ // Self-consistent: recomputing over the attached meta + captured source
213
+ // reproduces the hash (versionHash and version are excluded inputs).
214
+ assert.equal(
215
+ computeJourneyVersionHash({ meta: j1.meta, body: j1.runSource }),
216
+ j1.meta.versionHash,
217
+ );
218
+ // Label-only change: same content hash, new label.
219
+ const j2 = defineJourney({ meta: { ...base, version: "v2" }, run });
220
+ assert.equal(j2.meta.versionHash, j1.meta.versionHash);
221
+ assert.equal(j2.meta.version, "v2");
222
+ // An authored versionHash (JS caller — the type omits it) is overwritten.
223
+ const j3 = defineJourney({
224
+ meta: { ...base, versionHash: "aaaaaaaaaaaa" } as JourneyMetaInput,
225
+ run,
226
+ });
227
+ assert.equal(j3.meta.versionHash, j1.meta.versionHash);
228
+ // A body change forks.
229
+ const j4 = defineJourney({
230
+ meta: base,
231
+ run: async () => {
232
+ return;
233
+ },
234
+ });
235
+ assert.notEqual(j4.meta.versionHash, j1.meta.versionHash);
236
+ });