@hogsend/engine 0.51.0 → 0.52.1
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 +10 -10
- package/src/index.ts +9 -1
- package/src/journeys/execute-journey-run.ts +15 -0
- package/src/journeys/group-scope.ts +153 -0
- package/src/journeys/journey-context.ts +250 -66
- package/src/journeys/record-once.ts +27 -2
- package/src/lib/ingestion.ts +6 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.52.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -53,17 +53,17 @@
|
|
|
53
53
|
"svix": "^1.95.1",
|
|
54
54
|
"winston": "^3.19.0",
|
|
55
55
|
"zod": "^4.4.3",
|
|
56
|
-
"@hogsend/attribution": "^0.
|
|
57
|
-
"@hogsend/core": "^0.
|
|
58
|
-
"@hogsend/db": "^0.
|
|
59
|
-
"@hogsend/email": "^0.
|
|
60
|
-
"@hogsend/plugin-posthog": "^0.
|
|
61
|
-
"@hogsend/plugin-resend": "^0.
|
|
62
|
-
"@hogsend/sms": "^0.
|
|
56
|
+
"@hogsend/attribution": "^0.52.1",
|
|
57
|
+
"@hogsend/core": "^0.52.1",
|
|
58
|
+
"@hogsend/db": "^0.52.1",
|
|
59
|
+
"@hogsend/email": "^0.52.1",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.52.1",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.52.1",
|
|
62
|
+
"@hogsend/sms": "^0.52.1"
|
|
63
63
|
},
|
|
64
64
|
"optionalDependencies": {
|
|
65
|
-
"@hogsend/plugin-postmark": "^0.
|
|
66
|
-
"@hogsend/plugin-twilio": "^0.
|
|
65
|
+
"@hogsend/plugin-postmark": "^0.52.1",
|
|
66
|
+
"@hogsend/plugin-twilio": "^0.52.1"
|
|
67
67
|
},
|
|
68
68
|
"devDependencies": {
|
|
69
69
|
"@types/node": "^22.15.3",
|
package/src/index.ts
CHANGED
|
@@ -227,6 +227,11 @@ export {
|
|
|
227
227
|
buildJourneyGraph,
|
|
228
228
|
degradedGraphFromMeta,
|
|
229
229
|
} from "./journeys/graph/build-graph.js";
|
|
230
|
+
export {
|
|
231
|
+
type GroupScopeOption,
|
|
232
|
+
GroupScopeUnresolvableError,
|
|
233
|
+
resolveGroupScope,
|
|
234
|
+
} from "./journeys/group-scope.js";
|
|
230
235
|
export {
|
|
231
236
|
createMemoize,
|
|
232
237
|
deriveJourneyKey,
|
|
@@ -242,7 +247,10 @@ export {
|
|
|
242
247
|
registerRecordLabel,
|
|
243
248
|
runWithJourneyBoundary,
|
|
244
249
|
} from "./journeys/journey-boundary.js";
|
|
245
|
-
export {
|
|
250
|
+
export {
|
|
251
|
+
buildGroupEventFilter,
|
|
252
|
+
createJourneyContext,
|
|
253
|
+
} from "./journeys/journey-context.js";
|
|
246
254
|
// --- Journey transition log (journey_logs writer — Phase 2 per-stage metrics) ---
|
|
247
255
|
export {
|
|
248
256
|
type JourneyLogAction,
|
|
@@ -67,6 +67,12 @@ export interface EventPayloadInput {
|
|
|
67
67
|
userId: JsonValue;
|
|
68
68
|
userEmail: JsonValue;
|
|
69
69
|
properties: JsonValue;
|
|
70
|
+
/** The event's groupType→groupKey association map (`ingestEvent` pushes it
|
|
71
|
+
* on every event) — a group-scoped wait's trigger-association scope input. */
|
|
72
|
+
groups?: Record<string, string>;
|
|
73
|
+
/** The resolved subject contact row id (`ingestEvent` pushes it) — group
|
|
74
|
+
* membership auto-resolution input. */
|
|
75
|
+
contactId?: string;
|
|
70
76
|
[key: string]: JsonValue;
|
|
71
77
|
}
|
|
72
78
|
|
|
@@ -565,6 +571,15 @@ export async function executeJourneyRun(
|
|
|
565
571
|
journeyId: meta.id,
|
|
566
572
|
entryLimit: meta.entryLimit,
|
|
567
573
|
...(meta.entryPeriod ? { entryPeriod: meta.entryPeriod } : {}),
|
|
574
|
+
// Group-scope resolution inputs: the trigger event's association map
|
|
575
|
+
// (rides the task input, replay-stable) and the subject contact id —
|
|
576
|
+
// the pushed contactId when present, else the contact row already
|
|
577
|
+
// fetched for timezone above (best-effort: undefined only defers the
|
|
578
|
+
// resolver's no-contact throw to the membership leg).
|
|
579
|
+
...(input.groups ? { triggerGroups: input.groups } : {}),
|
|
580
|
+
...((input.contactId ?? contact?.id)
|
|
581
|
+
? { contactId: input.contactId ?? contact?.id }
|
|
582
|
+
: {}),
|
|
568
583
|
});
|
|
569
584
|
|
|
570
585
|
// The journey boundary makes journey side effects (sendEmail, ctx.trigger)
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import { type Database, groupMemberships, groups } from "@hogsend/db";
|
|
2
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
3
|
+
import { readRecordedValue, recordOnce } from "./record-once.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Thrown when a group-scoped primitive cannot pin its scope to a single group
|
|
7
|
+
* key: the enrolled contact has no live membership of the requested type, has
|
|
8
|
+
* more than one (ambiguous), or no contact was resolvable at all. A loud throw
|
|
9
|
+
* (not a silent skip) — an unresolvable scope is an authoring/data problem the
|
|
10
|
+
* journey must surface, exactly like an intra-run key collision.
|
|
11
|
+
*/
|
|
12
|
+
export class GroupScopeUnresolvableError extends Error {
|
|
13
|
+
readonly journeyId: string;
|
|
14
|
+
readonly groupType: string;
|
|
15
|
+
|
|
16
|
+
constructor(opts: { journeyId: string; groupType: string; detail: string }) {
|
|
17
|
+
super(
|
|
18
|
+
`Journey "${opts.journeyId}" could not resolve a group scope for type ` +
|
|
19
|
+
`"${opts.groupType}": ${opts.detail}`,
|
|
20
|
+
);
|
|
21
|
+
this.name = "GroupScopeUnresolvableError";
|
|
22
|
+
this.journeyId = opts.journeyId;
|
|
23
|
+
this.groupType = opts.groupType;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** The `group` option as authored: a bare type (auto-resolve the key) or an
|
|
28
|
+
* explicit `{ type, key }` pin. */
|
|
29
|
+
export type GroupScopeOption = string | { type: string; key?: string };
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Look up the contact's LIVE memberships of `type` and return the sole group
|
|
33
|
+
* key — throwing {@link GroupScopeUnresolvableError} on 0 or ≥2 rows (the
|
|
34
|
+
* count is named in the ambiguous message, so no LIMIT).
|
|
35
|
+
*/
|
|
36
|
+
async function lookupSoleMembership(opts: {
|
|
37
|
+
db: Database;
|
|
38
|
+
journeyId: string;
|
|
39
|
+
type: string;
|
|
40
|
+
contactId: string | undefined;
|
|
41
|
+
}): Promise<string> {
|
|
42
|
+
const { db, journeyId, type, contactId } = opts;
|
|
43
|
+
if (!contactId) {
|
|
44
|
+
throw new GroupScopeUnresolvableError({
|
|
45
|
+
journeyId,
|
|
46
|
+
groupType: type,
|
|
47
|
+
detail:
|
|
48
|
+
"no membership — no contact was resolvable for this enrollment, so " +
|
|
49
|
+
"membership auto-resolution has nothing to look up",
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
const rows = await db
|
|
53
|
+
.select({ groupKey: groups.groupKey })
|
|
54
|
+
.from(groupMemberships)
|
|
55
|
+
.innerJoin(groups, eq(groupMemberships.groupId, groups.id))
|
|
56
|
+
.where(
|
|
57
|
+
and(
|
|
58
|
+
eq(groupMemberships.contactId, contactId),
|
|
59
|
+
eq(groups.groupType, type),
|
|
60
|
+
isNull(groups.deletedAt),
|
|
61
|
+
),
|
|
62
|
+
);
|
|
63
|
+
const sole = rows[0];
|
|
64
|
+
if (rows.length === 1 && sole) {
|
|
65
|
+
return sole.groupKey;
|
|
66
|
+
}
|
|
67
|
+
if (rows.length === 0) {
|
|
68
|
+
throw new GroupScopeUnresolvableError({
|
|
69
|
+
journeyId,
|
|
70
|
+
groupType: type,
|
|
71
|
+
detail: `no membership — the contact belongs to no live "${type}" group`,
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
throw new GroupScopeUnresolvableError({
|
|
75
|
+
journeyId,
|
|
76
|
+
groupType: type,
|
|
77
|
+
detail: `ambiguous: ${rows.length} memberships of type "${type}"`,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Resolve a `group` option to a concrete replay-stable `{ type, key }` scope.
|
|
83
|
+
* Resolution order (DECISIONS §3.3) — EXACTLY this sequence:
|
|
84
|
+
*
|
|
85
|
+
* 1. **Explicit key** (`{ type, key }`): returned verbatim, NEVER recorded —
|
|
86
|
+
* it wins even over a recorded `__groupKeys__[type]`, and two same-type
|
|
87
|
+
* call sites with different explicit keys stay independent.
|
|
88
|
+
* 2. **Trigger association** (`triggerGroups[type]`): returned, NOT recorded —
|
|
89
|
+
* it rides the task input, so it is replay-stable by construction.
|
|
90
|
+
* 3. **Recorded** `journey_states.context.__groupKeys__[type]`: returned
|
|
91
|
+
* verbatim (only ever holds membership-resolved keys).
|
|
92
|
+
* 4. **Sole live membership**: exactly one live membership of `type` → its
|
|
93
|
+
* key, RECORDED under `__groupKeys__[type]` via `recordOnce` (read-back
|
|
94
|
+
* semantics converge concurrent racers — the committed value is returned,
|
|
95
|
+
* never the locally computed one). 0 or ≥2 rows → throw
|
|
96
|
+
* {@link GroupScopeUnresolvableError}.
|
|
97
|
+
*
|
|
98
|
+
* `record: false` (future ctx.history use) keeps the order identical but step
|
|
99
|
+
* 4 resolves WITHOUT writing.
|
|
100
|
+
*/
|
|
101
|
+
export async function resolveGroupScope(opts: {
|
|
102
|
+
db: Database;
|
|
103
|
+
stateId: string;
|
|
104
|
+
journeyId: string;
|
|
105
|
+
contactId: string | undefined;
|
|
106
|
+
triggerGroups: Record<string, string> | undefined;
|
|
107
|
+
option: GroupScopeOption;
|
|
108
|
+
record?: boolean;
|
|
109
|
+
}): Promise<{ type: string; key: string }> {
|
|
110
|
+
const { db, stateId, journeyId, contactId, triggerGroups, option } = opts;
|
|
111
|
+
const record = opts.record ?? true;
|
|
112
|
+
const type = typeof option === "string" ? option : option.type;
|
|
113
|
+
|
|
114
|
+
// 1. Explicit key — verbatim, never recorded.
|
|
115
|
+
if (typeof option === "object" && option.key !== undefined) {
|
|
116
|
+
return { type, key: option.key };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// 2. Trigger association — replay-stable via the task input, not recorded.
|
|
120
|
+
const triggered = triggerGroups?.[type];
|
|
121
|
+
if (triggered !== undefined) {
|
|
122
|
+
return { type, key: triggered };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
if (record) {
|
|
126
|
+
// 3+4. recordOnce's read-first IS step 3 (a recorded key returns without
|
|
127
|
+
// computing); its compute IS step 4 (the membership lookup, throwing when
|
|
128
|
+
// unresolvable — nothing is written on a throw). The returned value is
|
|
129
|
+
// the committed read-back, so concurrent racers converge.
|
|
130
|
+
const key = await recordOnce({
|
|
131
|
+
db,
|
|
132
|
+
stateId,
|
|
133
|
+
namespace: "__groupKeys__",
|
|
134
|
+
key: type,
|
|
135
|
+
compute: () => lookupSoleMembership({ db, journeyId, type, contactId }),
|
|
136
|
+
});
|
|
137
|
+
return { type, key };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// record: false — same order, no write. 3: read the recorded bag directly.
|
|
141
|
+
const recorded = await readRecordedValue({
|
|
142
|
+
db,
|
|
143
|
+
stateId,
|
|
144
|
+
namespace: "__groupKeys__",
|
|
145
|
+
key: type,
|
|
146
|
+
});
|
|
147
|
+
if (recorded !== undefined) {
|
|
148
|
+
return { type, key: recorded as string };
|
|
149
|
+
}
|
|
150
|
+
// 4 without the record.
|
|
151
|
+
const key = await lookupSoleMembership({ db, journeyId, type, contactId });
|
|
152
|
+
return { type, key };
|
|
153
|
+
}
|
|
@@ -62,6 +62,7 @@ import {
|
|
|
62
62
|
JOURNEY_EXECUTION_TIMEOUT_HOURS,
|
|
63
63
|
} from "./constants.js";
|
|
64
64
|
import { JourneyExitedError } from "./errors.js";
|
|
65
|
+
import { type GroupScopeOption, resolveGroupScope } from "./group-scope.js";
|
|
65
66
|
import {
|
|
66
67
|
deriveJourneyKey,
|
|
67
68
|
getJourneyBoundary,
|
|
@@ -122,6 +123,21 @@ function celStringLiteral(value: string): string {
|
|
|
122
123
|
return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
|
|
123
124
|
}
|
|
124
125
|
|
|
126
|
+
/**
|
|
127
|
+
* CEL filter for a group-scoped wait: matches an event whose pushed payload
|
|
128
|
+
* carries the group association `groups[type] == key`. Membership is tested
|
|
129
|
+
* before indexing so an event with no `groups` map (an older producer) can
|
|
130
|
+
* never error the expression; both literals go through `celStringLiteral` so
|
|
131
|
+
* an externally-supplied type/key cannot break out of the filter.
|
|
132
|
+
*/
|
|
133
|
+
export function buildGroupEventFilter(type: string, key: string): string {
|
|
134
|
+
const typeLit = celStringLiteral(type);
|
|
135
|
+
return (
|
|
136
|
+
`'groups' in input && ${typeLit} in input.groups && ` +
|
|
137
|
+
`input.groups[${typeLit}] == ${celStringLiteral(key)}`
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
|
|
125
141
|
/** SQL eq-pushdown predicates for a `where` — a COARSE narrowing pre-filter,
|
|
126
142
|
* never the verdict: jsonb `->>` extracts TEXT (a stored string "50"
|
|
127
143
|
* text-matches `.eq(50)`), so every consumer MUST re-verify fetched rows with
|
|
@@ -186,6 +202,13 @@ interface JourneyContextConfig {
|
|
|
186
202
|
entryLimit?: "once" | "once_per_period" | "unlimited";
|
|
187
203
|
/** The journey's entry period (for `once_per_period`). */
|
|
188
204
|
entryPeriod?: DurationObject;
|
|
205
|
+
/** The trigger event's groupType→groupKey association map (rides the task
|
|
206
|
+
* input, so replay-stable) — group-scope resolution leg 2. */
|
|
207
|
+
triggerGroups?: Record<string, string>;
|
|
208
|
+
/** The enrolled contact's row id — group membership auto-resolution
|
|
209
|
+
* (leg 4). Undefined defers to the resolver's no-contact throw, which
|
|
210
|
+
* only fires when that leg is actually reached. */
|
|
211
|
+
contactId?: string;
|
|
189
212
|
}
|
|
190
213
|
|
|
191
214
|
export function createJourneyContext(
|
|
@@ -355,17 +378,61 @@ export function createJourneyContext(
|
|
|
355
378
|
nodeId: string,
|
|
356
379
|
where: PropertyCondition[],
|
|
357
380
|
lookback?: DurationObject,
|
|
381
|
+
// When present, the wait matches ANY member's event carrying this group
|
|
382
|
+
// association instead of the enrolled user's events (both the SQL scan
|
|
383
|
+
// and the live CEL filter swap their user predicate for the group one).
|
|
384
|
+
groupScope?: { type: string; key: string },
|
|
358
385
|
): Promise<WaitForEventResult> => {
|
|
359
|
-
//
|
|
386
|
+
// Replay stability (the digest pattern, applied to CONTROL FLOW): Hatchet's
|
|
387
|
+
// journal is positional AND param-checked for COMPLETED entries, so a
|
|
388
|
+
// replay-from-top must re-issue exactly the durable calls the original run
|
|
389
|
+
// made, with identical parameters — skipping the wait (an early-returned
|
|
390
|
+
// recorded outcome) or re-computing a sleep duration from the wall clock
|
|
391
|
+
// makes the next durable call land on the wrong journal slot and the whole
|
|
392
|
+
// run fails with a non-determinism error (#591). The rule here is therefore
|
|
393
|
+
// NEVER skip a durable call; instead FREEZE every non-journaled input the
|
|
394
|
+
// control flow branches on — each scan result (`<nodeId>:scan:<seq>`), each
|
|
395
|
+
// arm's remaining-ms (`<nodeId>:arm:<seq>`, which is also the sleep param),
|
|
396
|
+
// and the deadline itself (`<nodeId>:deadline`; the shared `waitDeadline`
|
|
397
|
+
// column is cleared at resolution so it can't be the replay truth) — so the
|
|
398
|
+
// replay walks the identical branch sequence, Hatchet answers each re-issued
|
|
399
|
+
// waitFor from the journal instantly, and `recordOnce` at the end returns
|
|
400
|
+
// the frozen outcome verbatim. Registering the label makes an intra-run
|
|
401
|
+
// duplicate wait label a loud authoring error instead of a silent
|
|
402
|
+
// stale-outcome replay.
|
|
403
|
+
registerRecordLabel(getJourneyBoundary(), `wait:${nodeId}`);
|
|
404
|
+
const outcomeKey = `${nodeId}:result`;
|
|
405
|
+
const recordOutcome = (o: WaitForEventResult) =>
|
|
406
|
+
recordOnce({
|
|
407
|
+
db,
|
|
408
|
+
stateId,
|
|
409
|
+
namespace: "__waits__",
|
|
410
|
+
key: outcomeKey,
|
|
411
|
+
compute: () => o,
|
|
412
|
+
});
|
|
413
|
+
|
|
414
|
+
// Durable deadline: read-first / set-once. The RECORDED copy is the replay
|
|
415
|
+
// truth; the `waitDeadline` column is still written for observability and
|
|
416
|
+
// as the pre-record source for runs armed by an engine without the record
|
|
417
|
+
// (mixed-version replay keeps the original deadline instead of extending).
|
|
360
418
|
const stateRow = await db
|
|
361
419
|
.select({ waitDeadline: journeyStates.waitDeadline })
|
|
362
420
|
.from(journeyStates)
|
|
363
421
|
.where(eq(journeyStates.id, stateId))
|
|
364
422
|
.limit(1);
|
|
365
423
|
const storedDeadline = stateRow[0]?.waitDeadline ?? null;
|
|
366
|
-
const
|
|
367
|
-
|
|
368
|
-
|
|
424
|
+
const deadlineIso = await recordOnce<string>({
|
|
425
|
+
db,
|
|
426
|
+
stateId,
|
|
427
|
+
namespace: "__waits__",
|
|
428
|
+
key: `${nodeId}:deadline`,
|
|
429
|
+
compute: () =>
|
|
430
|
+
(storedDeadline
|
|
431
|
+
? new Date(storedDeadline)
|
|
432
|
+
: new Date(Date.now() + durationToMs(timeout))
|
|
433
|
+
).toISOString(),
|
|
434
|
+
});
|
|
435
|
+
const deadline = new Date(deadlineIso);
|
|
369
436
|
if (!storedDeadline) {
|
|
370
437
|
await db
|
|
371
438
|
.update(journeyStates)
|
|
@@ -393,15 +460,23 @@ export function createJourneyContext(
|
|
|
393
460
|
// Narrowing only — `scanForMatch` re-verifies every row in JS.
|
|
394
461
|
const eqPreds = eqPushdownPreds(where);
|
|
395
462
|
|
|
396
|
-
const scanForMatch = async (): Promise<
|
|
397
|
-
WaitForEventResult["properties"]
|
|
398
|
-
|
|
463
|
+
const scanForMatch = async (): Promise<{
|
|
464
|
+
properties: NonNullable<WaitForEventResult["properties"]>;
|
|
465
|
+
actorUserId: string;
|
|
466
|
+
} | null> => {
|
|
399
467
|
const recent = await db
|
|
400
|
-
.select({
|
|
468
|
+
.select({
|
|
469
|
+
properties: userEvents.properties,
|
|
470
|
+
userId: userEvents.userId,
|
|
471
|
+
})
|
|
401
472
|
.from(userEvents)
|
|
402
473
|
.where(
|
|
403
474
|
and(
|
|
404
|
-
|
|
475
|
+
// Group scope matches ANY member's row via the persisted
|
|
476
|
+
// association map; user scope keeps the enrolled-user predicate.
|
|
477
|
+
groupScope
|
|
478
|
+
? sql`${userEvents.groups} ->> ${groupScope.type} = ${groupScope.key}`
|
|
479
|
+
: eq(userEvents.userId, userId),
|
|
405
480
|
eq(userEvents.event, event),
|
|
406
481
|
gte(userEvents.occurredAt, scanSince),
|
|
407
482
|
...eqPreds,
|
|
@@ -417,26 +492,42 @@ export function createJourneyContext(
|
|
|
417
492
|
if (
|
|
418
493
|
evaluatePropertyConditions({ conditions: where, properties: props })
|
|
419
494
|
) {
|
|
420
|
-
return narrowScalars(props);
|
|
495
|
+
return { properties: narrowScalars(props), actorUserId: row.userId };
|
|
421
496
|
}
|
|
422
497
|
}
|
|
423
498
|
return null;
|
|
424
499
|
};
|
|
425
500
|
|
|
501
|
+
// Every scan is frozen set-once in call order (misses included — a stored
|
|
502
|
+
// `null` is distinguishable from "not recorded"). On replay the scan
|
|
503
|
+
// sequence returns verbatim, so the loop takes the original branches even
|
|
504
|
+
// though the resolving row is NOW visible in the DB (or a once-visible row
|
|
505
|
+
// aged out of the window).
|
|
506
|
+
let scanSeq = 0;
|
|
507
|
+
const recordedScan = () =>
|
|
508
|
+
recordOnce<Awaited<ReturnType<typeof scanForMatch>>>({
|
|
509
|
+
db,
|
|
510
|
+
stateId,
|
|
511
|
+
namespace: "__waits__",
|
|
512
|
+
key: `${nodeId}:scan:${scanSeq++}`,
|
|
513
|
+
compute: scanForMatch,
|
|
514
|
+
});
|
|
515
|
+
|
|
426
516
|
// Immediate hit (incl. the lookback window) — resolve without a state flip.
|
|
427
|
-
const preHit = await
|
|
517
|
+
const preHit = await recordedScan();
|
|
428
518
|
if (preHit) {
|
|
429
519
|
await clearDeadline();
|
|
430
|
-
return { timedOut: false,
|
|
520
|
+
return recordOutcome({ timedOut: false, ...preHit });
|
|
431
521
|
}
|
|
432
522
|
|
|
433
523
|
await enterWait(nodeId, "wait");
|
|
434
524
|
|
|
435
525
|
let outcome: WaitForEventResult;
|
|
526
|
+
let armSeq = 0;
|
|
436
527
|
while (true) {
|
|
437
|
-
const hit = await
|
|
528
|
+
const hit = await recordedScan();
|
|
438
529
|
if (hit) {
|
|
439
|
-
outcome = { timedOut: false,
|
|
530
|
+
outcome = { timedOut: false, ...hit };
|
|
440
531
|
break;
|
|
441
532
|
}
|
|
442
533
|
|
|
@@ -452,7 +543,16 @@ export function createJourneyContext(
|
|
|
452
543
|
throw new JourneyExitedError(stateId);
|
|
453
544
|
}
|
|
454
545
|
|
|
455
|
-
|
|
546
|
+
// Frozen per arm: both the conclude-without-arming decision AND the
|
|
547
|
+
// sleep-branch parameter must replay identically (a completed waitFor's
|
|
548
|
+
// journal entry is param-checked).
|
|
549
|
+
const remainingMs = await recordOnce<number>({
|
|
550
|
+
db,
|
|
551
|
+
stateId,
|
|
552
|
+
namespace: "__waits__",
|
|
553
|
+
key: `${nodeId}:arm:${armSeq++}`,
|
|
554
|
+
compute: () => deadline.getTime() - Date.now(),
|
|
555
|
+
});
|
|
456
556
|
if (remainingMs <= 0) {
|
|
457
557
|
outcome = { timedOut: true };
|
|
458
558
|
break;
|
|
@@ -462,7 +562,9 @@ export function createJourneyContext(
|
|
|
462
562
|
Or(
|
|
463
563
|
new UserEventCondition(
|
|
464
564
|
event,
|
|
465
|
-
|
|
565
|
+
groupScope
|
|
566
|
+
? buildGroupEventFilter(groupScope.type, groupScope.key)
|
|
567
|
+
: `input.userId == ${celStringLiteral(userId)}`,
|
|
466
568
|
"event",
|
|
467
569
|
),
|
|
468
570
|
new SleepCondition(toSleepDuration(remainingMs), "timeout"),
|
|
@@ -473,10 +575,8 @@ export function createJourneyContext(
|
|
|
473
575
|
if (!("event" in fired)) {
|
|
474
576
|
// Timeout branch — one final scan for an event landing exactly as the
|
|
475
577
|
// sleep expired, then conclude.
|
|
476
|
-
const last = await
|
|
477
|
-
outcome = last
|
|
478
|
-
? { timedOut: false, properties: last }
|
|
479
|
-
: { timedOut: true };
|
|
578
|
+
const last = await recordedScan();
|
|
579
|
+
outcome = last ? { timedOut: false, ...last } : { timedOut: true };
|
|
480
580
|
break;
|
|
481
581
|
}
|
|
482
582
|
// Event branch: loop — the next scan picks up the (already persisted) row
|
|
@@ -485,7 +585,7 @@ export function createJourneyContext(
|
|
|
485
585
|
|
|
486
586
|
await resumeFromWait(nodeId, { timedOut: outcome.timedOut });
|
|
487
587
|
await clearDeadline();
|
|
488
|
-
return outcome;
|
|
588
|
+
return recordOutcome(outcome);
|
|
489
589
|
};
|
|
490
590
|
|
|
491
591
|
// Durably wait for THIS user's `event` OR `timeout`, whichever fires first,
|
|
@@ -496,6 +596,7 @@ export function createJourneyContext(
|
|
|
496
596
|
nodeId: string,
|
|
497
597
|
lookback?: DurationObject,
|
|
498
598
|
where?: PropertyCondition[],
|
|
599
|
+
group?: GroupScopeOption,
|
|
499
600
|
): Promise<WaitForEventResult> => {
|
|
500
601
|
// Reject a timeout longer than the journey task's executionTimeout up front
|
|
501
602
|
// so it fails fast at authoring time. (Eviction-capable engines may allow
|
|
@@ -512,15 +613,34 @@ export function createJourneyContext(
|
|
|
512
613
|
// it — set it before dispatching to either wait path.
|
|
513
614
|
setBoundaryLabel(nodeId);
|
|
514
615
|
|
|
616
|
+
// A group-scoped wait resolves its scope ONCE, up front (explicit key →
|
|
617
|
+
// trigger association → recorded → sole membership; recordOnce is DB-only,
|
|
618
|
+
// so this issues no durable journal node), and ALWAYS takes the filtered
|
|
619
|
+
// leg — the legacy leg below has no re-arm scan and no timeout final scan.
|
|
620
|
+
// An empty `where` there is vacuous (`evaluatePropertyConditions` is
|
|
621
|
+
// Array.every; `eqPushdownPreds([])` is empty).
|
|
622
|
+
let groupScope: { type: string; key: string } | undefined;
|
|
623
|
+
if (group) {
|
|
624
|
+
groupScope = await resolveGroupScope({
|
|
625
|
+
db,
|
|
626
|
+
stateId,
|
|
627
|
+
journeyId: config.journeyId ?? "unknown",
|
|
628
|
+
contactId: config.contactId,
|
|
629
|
+
triggerGroups: config.triggerGroups,
|
|
630
|
+
option: group,
|
|
631
|
+
});
|
|
632
|
+
}
|
|
633
|
+
|
|
515
634
|
// WHERE-filtered wait takes the durable re-arm path; an empty/absent `where`
|
|
516
635
|
// keeps the exact legacy single-wait below byte-for-byte.
|
|
517
|
-
if (where && where.length > 0) {
|
|
636
|
+
if (groupScope || (where && where.length > 0)) {
|
|
518
637
|
return performFilteredWaitForEvent(
|
|
519
638
|
event,
|
|
520
639
|
timeout,
|
|
521
640
|
nodeId,
|
|
522
|
-
where,
|
|
641
|
+
where ?? [],
|
|
523
642
|
lookback,
|
|
643
|
+
groupScope,
|
|
524
644
|
);
|
|
525
645
|
}
|
|
526
646
|
|
|
@@ -531,46 +651,65 @@ export function createJourneyContext(
|
|
|
531
651
|
// can never re-push. A recent matching user_events row resolves the wait
|
|
532
652
|
// immediately, payload included.
|
|
533
653
|
if (lookback) {
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
);
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
(
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
654
|
+
// Recording under this node's key makes an intra-run duplicate wait
|
|
655
|
+
// label a loud error here too (same registry as the filtered leg).
|
|
656
|
+
registerRecordLabel(getJourneyBoundary(), `wait:${nodeId}`);
|
|
657
|
+
// Frozen set-once (miss included): whether the wait resolved via lookback
|
|
658
|
+
// is a control-flow branch in front of a durable call, so a replay must
|
|
659
|
+
// take the SAME side even though the window has shifted and the DB has
|
|
660
|
+
// moved on (the positional-journal rule — see the filtered leg above).
|
|
661
|
+
const lookbackHit = await recordOnce<WaitForEventResult | null>({
|
|
662
|
+
db,
|
|
663
|
+
stateId,
|
|
664
|
+
namespace: "__waits__",
|
|
665
|
+
key: `${nodeId}:lookback`,
|
|
666
|
+
compute: async () => {
|
|
667
|
+
const since = new Date(
|
|
668
|
+
(await refreshNow()).getTime() - durationToMs(lookback),
|
|
669
|
+
);
|
|
670
|
+
const recent = await db
|
|
671
|
+
.select({
|
|
672
|
+
properties: userEvents.properties,
|
|
673
|
+
occurredAt: userEvents.occurredAt,
|
|
674
|
+
})
|
|
675
|
+
.from(userEvents)
|
|
676
|
+
.where(
|
|
677
|
+
and(
|
|
678
|
+
eq(userEvents.userId, userId),
|
|
679
|
+
eq(userEvents.event, event),
|
|
680
|
+
gte(userEvents.occurredAt, since),
|
|
681
|
+
),
|
|
682
|
+
)
|
|
683
|
+
.orderBy(desc(userEvents.occurredAt))
|
|
684
|
+
.limit(1);
|
|
685
|
+
const row = recent[0];
|
|
686
|
+
if (!row) return null;
|
|
687
|
+
const scalars = Object.fromEntries(
|
|
688
|
+
Object.entries(row.properties ?? {}).filter(
|
|
689
|
+
([, v]) =>
|
|
690
|
+
typeof v === "string" ||
|
|
691
|
+
typeof v === "number" ||
|
|
692
|
+
typeof v === "boolean" ||
|
|
693
|
+
v === null,
|
|
694
|
+
),
|
|
695
|
+
) as NonNullable<WaitForEventResult["properties"]>;
|
|
696
|
+
const occurredAt =
|
|
697
|
+
row.occurredAt instanceof Date
|
|
698
|
+
? row.occurredAt.toISOString()
|
|
699
|
+
: row.occurredAt
|
|
700
|
+
? String(row.occurredAt)
|
|
701
|
+
: undefined;
|
|
702
|
+
return {
|
|
703
|
+
timedOut: false,
|
|
704
|
+
properties: scalars,
|
|
705
|
+
...(occurredAt ? { occurredAt } : {}),
|
|
706
|
+
// Lookback rows are user-scoped, so the actor IS the enrolled user.
|
|
707
|
+
actorUserId: userId,
|
|
708
|
+
};
|
|
709
|
+
},
|
|
710
|
+
});
|
|
711
|
+
if (lookbackHit) {
|
|
712
|
+
return lookbackHit;
|
|
574
713
|
}
|
|
575
714
|
}
|
|
576
715
|
|
|
@@ -603,6 +742,7 @@ export function createJourneyContext(
|
|
|
603
742
|
// ({ userId, userEmail, properties }); the pre-eviction path may hand the
|
|
604
743
|
// payload back un-wrapped — tolerate both, mirroring the CREATE-strip.
|
|
605
744
|
let properties: WaitForEventResult["properties"];
|
|
745
|
+
let actorUserId: string | undefined;
|
|
606
746
|
if (!timedOut) {
|
|
607
747
|
const matches = fired.event;
|
|
608
748
|
const first = Array.isArray(matches) ? matches[0] : matches;
|
|
@@ -621,6 +761,13 @@ export function createJourneyContext(
|
|
|
621
761
|
) {
|
|
622
762
|
properties = candidate as NonNullable<WaitForEventResult["properties"]>;
|
|
623
763
|
}
|
|
764
|
+
// This leg's CEL filter is user-scoped, so the actor is the enrolled
|
|
765
|
+
// user; prefer the fired payload's top-level `userId` when carried.
|
|
766
|
+
const actor =
|
|
767
|
+
payload && typeof payload === "object" && "userId" in payload
|
|
768
|
+
? (payload as { userId?: unknown }).userId
|
|
769
|
+
: undefined;
|
|
770
|
+
actorUserId = typeof actor === "string" ? actor : userId;
|
|
624
771
|
}
|
|
625
772
|
|
|
626
773
|
await resumeFromWait(nodeId, { timedOut });
|
|
@@ -628,7 +775,11 @@ export function createJourneyContext(
|
|
|
628
775
|
// reads a replay-stable instant (eviction engine) rather than the seed.
|
|
629
776
|
await refreshNow();
|
|
630
777
|
|
|
631
|
-
return {
|
|
778
|
+
return {
|
|
779
|
+
timedOut,
|
|
780
|
+
...(properties ? { properties } : {}),
|
|
781
|
+
...(actorUserId ? { actorUserId } : {}),
|
|
782
|
+
};
|
|
632
783
|
};
|
|
633
784
|
|
|
634
785
|
// Scan the digest window ONCE at flush: all `event` rows for THIS user in
|
|
@@ -1046,13 +1197,14 @@ export function createJourneyContext(
|
|
|
1046
1197
|
);
|
|
1047
1198
|
},
|
|
1048
1199
|
|
|
1049
|
-
async waitForEvent({ event, timeout, label, lookback, where }) {
|
|
1200
|
+
async waitForEvent({ event, timeout, label, lookback, where, group }) {
|
|
1050
1201
|
return performWaitForEvent(
|
|
1051
1202
|
event,
|
|
1052
1203
|
timeout,
|
|
1053
1204
|
label ?? `wait-event:${event}`,
|
|
1054
1205
|
lookback,
|
|
1055
1206
|
normalizeWhere(where),
|
|
1207
|
+
group,
|
|
1056
1208
|
);
|
|
1057
1209
|
},
|
|
1058
1210
|
|
|
@@ -1211,7 +1363,39 @@ export function createJourneyContext(
|
|
|
1211
1363
|
},
|
|
1212
1364
|
|
|
1213
1365
|
history: {
|
|
1214
|
-
async hasEvent({ userId: targetUserId, event, within }) {
|
|
1366
|
+
async hasEvent({ userId: targetUserId, event, within, group }) {
|
|
1367
|
+
// Group REPLACES the userId scoping: count rows via the persisted
|
|
1368
|
+
// association map (same jsonb predicate as the wait scan). Resolution
|
|
1369
|
+
// is READ-ONLY (`record: false`) — a history read never writes
|
|
1370
|
+
// `__groupKeys__`.
|
|
1371
|
+
if (group) {
|
|
1372
|
+
const scope = await resolveGroupScope({
|
|
1373
|
+
db,
|
|
1374
|
+
stateId,
|
|
1375
|
+
journeyId: config.journeyId ?? "unknown",
|
|
1376
|
+
contactId: config.contactId,
|
|
1377
|
+
triggerGroups: config.triggerGroups,
|
|
1378
|
+
option: group,
|
|
1379
|
+
record: false,
|
|
1380
|
+
});
|
|
1381
|
+
const [row] = await db
|
|
1382
|
+
.select({ count: sql<number>`count(*)` })
|
|
1383
|
+
.from(userEvents)
|
|
1384
|
+
.where(
|
|
1385
|
+
and(
|
|
1386
|
+
sql`${userEvents.groups} ->> ${scope.type} = ${scope.key}`,
|
|
1387
|
+
eq(userEvents.event, event),
|
|
1388
|
+
within
|
|
1389
|
+
? gte(
|
|
1390
|
+
userEvents.occurredAt,
|
|
1391
|
+
new Date(Date.now() - durationToMs(within)),
|
|
1392
|
+
)
|
|
1393
|
+
: undefined,
|
|
1394
|
+
),
|
|
1395
|
+
);
|
|
1396
|
+
const total = Number(row?.count ?? 0);
|
|
1397
|
+
return { found: total > 0, count: total };
|
|
1398
|
+
}
|
|
1215
1399
|
const result = await evaluateEventCondition({
|
|
1216
1400
|
condition: {
|
|
1217
1401
|
type: "event",
|
|
@@ -9,9 +9,11 @@ export type RecordNamespace =
|
|
|
9
9
|
| "__once__"
|
|
10
10
|
| "__digest__"
|
|
11
11
|
| "__throttle__"
|
|
12
|
-
| "__variants__"
|
|
12
|
+
| "__variants__"
|
|
13
|
+
| "__groupKeys__"
|
|
14
|
+
| "__waits__";
|
|
13
15
|
|
|
14
|
-
// Closed-union → validated path token. NOT user input: only these
|
|
16
|
+
// Closed-union → validated path token. NOT user input: only these six literals
|
|
15
17
|
// reach the interpolated jsonb path below, so it is injection-safe. `key` and the
|
|
16
18
|
// JSON-stringified value are ALWAYS bound parameters regardless.
|
|
17
19
|
const NAMESPACE_TOKEN: Record<RecordNamespace, string> = {
|
|
@@ -19,6 +21,8 @@ const NAMESPACE_TOKEN: Record<RecordNamespace, string> = {
|
|
|
19
21
|
__digest__: "__digest__",
|
|
20
22
|
__throttle__: "__throttle__",
|
|
21
23
|
__variants__: "__variants__",
|
|
24
|
+
__groupKeys__: "__groupKeys__",
|
|
25
|
+
__waits__: "__waits__",
|
|
22
26
|
};
|
|
23
27
|
|
|
24
28
|
/** Extract the `(namespace)` sub-bag from an already-fetched context, `{}` when
|
|
@@ -114,6 +118,27 @@ export async function recordOnce<T>(opts: {
|
|
|
114
118
|
return value;
|
|
115
119
|
}
|
|
116
120
|
|
|
121
|
+
/**
|
|
122
|
+
* Read an already-recorded `(stateId, namespace, key)` value WITHOUT computing
|
|
123
|
+
* or writing — `undefined` when nothing is recorded. The read-only companion
|
|
124
|
+
* to {@link recordOnce} for call sites whose compute would issue durable work
|
|
125
|
+
* (recordOnce's `compute` must never add journal nodes).
|
|
126
|
+
*/
|
|
127
|
+
export async function readRecordedValue(opts: {
|
|
128
|
+
db: Database;
|
|
129
|
+
stateId: string;
|
|
130
|
+
namespace: RecordNamespace;
|
|
131
|
+
key: string;
|
|
132
|
+
}): Promise<unknown> {
|
|
133
|
+
const { db, stateId, namespace, key } = opts;
|
|
134
|
+
const row = await db.query.journeyStates.findFirst({
|
|
135
|
+
where: eq(journeyStates.id, stateId),
|
|
136
|
+
columns: { context: true },
|
|
137
|
+
});
|
|
138
|
+
const bag = namespaceBag(row?.context, namespace);
|
|
139
|
+
return Object.hasOwn(bag, key) ? bag[key] : undefined;
|
|
140
|
+
}
|
|
141
|
+
|
|
117
142
|
/**
|
|
118
143
|
* Drop ALL reserved record-once namespace keys from an event-properties bag.
|
|
119
144
|
* Enrollment seeds `journey_states.context` from trigger-event properties
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -563,6 +563,12 @@ export async function ingestEvent(opts: {
|
|
|
563
563
|
// (folds, never mints a twin). Additive/optional — consumers ignoring it
|
|
564
564
|
// are unaffected.
|
|
565
565
|
contactId,
|
|
566
|
+
// The event's group association map (groupType → groupKey), so a
|
|
567
|
+
// group-scoped wait can match on membership straight off the wire.
|
|
568
|
+
// Always present ({} when the event carries none) so downstream CEL
|
|
569
|
+
// filters never key on an absent field. Additive — existing consumers
|
|
570
|
+
// ignore it.
|
|
571
|
+
groups: event.groups ?? {},
|
|
566
572
|
}),
|
|
567
573
|
checkExits(db, registry, hatchet, logger, {
|
|
568
574
|
userId: resolvedKey,
|