@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.
- package/README.md +6 -0
- package/package.json +13 -10
- package/src/connectors/presets/index.ts +8 -2
- package/src/container.ts +149 -7
- package/src/destinations/presets/posthog.ts +7 -0
- package/src/destinations/presets/segment.ts +5 -0
- package/src/env.ts +38 -0
- package/src/flags/reconcile.ts +195 -0
- package/src/index.ts +79 -0
- package/src/journeys/authoring.ts +32 -0
- package/src/journeys/define-journey.ts +45 -40
- package/src/journeys/execute-journey-run.ts +73 -32
- package/src/journeys/journey-boundary.ts +76 -0
- package/src/journeys/journey-context.ts +128 -70
- package/src/journeys/journey-task-factory.ts +31 -0
- package/src/journeys/journey-task-runtime.ts +31 -0
- package/src/journeys/journey-version.test.ts +236 -0
- package/src/journeys/journey-version.ts +158 -0
- package/src/journeys/record-once.ts +28 -2
- package/src/lib/connector-actions.test.ts +36 -0
- package/src/lib/connector-actions.ts +42 -4
- package/src/lib/contacts.ts +49 -0
- package/src/lib/conversions.test.ts +33 -0
- package/src/lib/conversions.ts +8 -0
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- package/src/lib/feed.ts +55 -3
- package/src/lib/flags-registry.ts +48 -0
- package/src/lib/flags.ts +498 -0
- package/src/lib/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- package/src/lib/operator-settings.ts +71 -0
- package/src/lib/outbound.ts +147 -0
- package/src/lib/preferences.ts +6 -80
- package/src/lib/recipient-preferences.ts +53 -0
- package/src/lib/sms.ts +21 -2
- package/src/lib/stable-stringify.test.ts +42 -0
- package/src/lib/stable-stringify.ts +23 -0
- package/src/lib/variant.ts +99 -0
- package/src/lib/webhook-signing.ts +16 -1
- package/src/lists/registry.ts +6 -2
- package/src/lists/subscription.ts +13 -0
- package/src/routes/admin/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +137 -0
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +866 -0
- package/src/routes/admin/impact-schemas.ts +44 -0
- package/src/routes/admin/impact-wire.test.ts +181 -0
- package/src/routes/admin/impact.ts +486 -0
- package/src/routes/admin/index.ts +12 -0
- package/src/routes/admin/journey-impact.ts +446 -0
- package/src/routes/admin/journeys.ts +70 -100
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +256 -0
- package/src/routes/events/index.ts +11 -0
- package/src/routes/flags/index.ts +120 -0
- package/src/routes/groups/index.ts +417 -0
- package/src/routes/index.ts +23 -1
- package/src/testing.ts +25 -0
- package/src/webhook-sources/presets/index.ts +5 -1
- package/src/webhook-sources/presets/intercom.ts +230 -0
- package/src/webhook-sources/presets/segment.ts +56 -4
- package/src/worker.ts +3 -0
- package/src/workflows/bucket-backfill.ts +1 -14
- package/src/workflows/impact-digest.ts +761 -0
- 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
|
+
});
|