@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.51.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.51.0",
57
- "@hogsend/core": "^0.51.0",
58
- "@hogsend/db": "^0.51.0",
59
- "@hogsend/email": "^0.51.0",
60
- "@hogsend/plugin-posthog": "^0.51.0",
61
- "@hogsend/plugin-resend": "^0.51.0",
62
- "@hogsend/sms": "^0.51.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.51.0",
66
- "@hogsend/plugin-twilio": "^0.51.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 { createJourneyContext } from "./journeys/journey-context.js";
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
- // Durable deadline: read-first / set-once.
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 deadline = storedDeadline
367
- ? new Date(storedDeadline)
368
- : new Date(Date.now() + durationToMs(timeout));
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<NonNullable<
397
- WaitForEventResult["properties"]
398
- > | null> => {
463
+ const scanForMatch = async (): Promise<{
464
+ properties: NonNullable<WaitForEventResult["properties"]>;
465
+ actorUserId: string;
466
+ } | null> => {
399
467
  const recent = await db
400
- .select({ properties: userEvents.properties })
468
+ .select({
469
+ properties: userEvents.properties,
470
+ userId: userEvents.userId,
471
+ })
401
472
  .from(userEvents)
402
473
  .where(
403
474
  and(
404
- eq(userEvents.userId, userId),
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 scanForMatch();
517
+ const preHit = await recordedScan();
428
518
  if (preHit) {
429
519
  await clearDeadline();
430
- return { timedOut: false, properties: preHit };
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 scanForMatch();
528
+ const hit = await recordedScan();
438
529
  if (hit) {
439
- outcome = { timedOut: false, properties: hit };
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
- const remainingMs = deadline.getTime() - Date.now();
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
- `input.userId == ${celStringLiteral(userId)}`,
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 scanForMatch();
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
- const since = new Date(
535
- (await refreshNow()).getTime() - durationToMs(lookback),
536
- );
537
- const recent = await db
538
- .select({
539
- properties: userEvents.properties,
540
- occurredAt: userEvents.occurredAt,
541
- })
542
- .from(userEvents)
543
- .where(
544
- and(
545
- eq(userEvents.userId, userId),
546
- eq(userEvents.event, event),
547
- gte(userEvents.occurredAt, since),
548
- ),
549
- )
550
- .orderBy(desc(userEvents.occurredAt))
551
- .limit(1);
552
- const row = recent[0];
553
- if (row) {
554
- const scalars = Object.fromEntries(
555
- Object.entries(row.properties ?? {}).filter(
556
- ([, v]) =>
557
- typeof v === "string" ||
558
- typeof v === "number" ||
559
- typeof v === "boolean" ||
560
- v === null,
561
- ),
562
- ) as NonNullable<WaitForEventResult["properties"]>;
563
- const occurredAt =
564
- row.occurredAt instanceof Date
565
- ? row.occurredAt.toISOString()
566
- : row.occurredAt
567
- ? String(row.occurredAt)
568
- : undefined;
569
- return {
570
- timedOut: false,
571
- properties: scalars,
572
- ...(occurredAt ? { occurredAt } : {}),
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 { timedOut, ...(properties ? { properties } : {}) };
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 four literals
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
@@ -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,