@hogsend/engine 0.50.0 → 0.52.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.50.0",
3
+ "version": "0.52.0",
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.50.0",
57
- "@hogsend/core": "^0.50.0",
58
- "@hogsend/db": "^0.50.0",
59
- "@hogsend/email": "^0.50.0",
60
- "@hogsend/plugin-posthog": "^0.50.0",
61
- "@hogsend/plugin-resend": "^0.50.0",
62
- "@hogsend/sms": "^0.50.0"
56
+ "@hogsend/attribution": "^0.52.0",
57
+ "@hogsend/core": "^0.52.0",
58
+ "@hogsend/db": "^0.52.0",
59
+ "@hogsend/email": "^0.52.0",
60
+ "@hogsend/plugin-posthog": "^0.52.0",
61
+ "@hogsend/plugin-resend": "^0.52.0",
62
+ "@hogsend/sms": "^0.52.0"
63
63
  },
64
64
  "optionalDependencies": {
65
- "@hogsend/plugin-postmark": "^0.50.0",
66
- "@hogsend/plugin-twilio": "^0.50.0"
65
+ "@hogsend/plugin-postmark": "^0.52.0",
66
+ "@hogsend/plugin-twilio": "^0.52.0"
67
67
  },
68
68
  "devDependencies": {
69
69
  "@types/node": "^22.15.3",
@@ -29,7 +29,6 @@ import {
29
29
  } from "@hogsend/db";
30
30
  import { type SQL, sql } from "drizzle-orm";
31
31
  import type { PgColumn } from "drizzle-orm/pg-core";
32
- import { campaignSendKeyPattern } from "../lib/campaign-send-key.js";
33
32
 
34
33
  /**
35
34
  * The v1 linked-identity map: connector id → the `contacts` column that holds
@@ -107,13 +106,13 @@ export function waveConditionSql(opts: {
107
106
  }
108
107
 
109
108
  /**
110
- * Engagement over THIS campaign's prior deliveries. The campaign-level LIKE
111
- * (`campaign:<escaped-id>:%`) is a correct superset of BOTH key formats
112
- * (legacy and step-scoped), so an absent `templateKey` — "any prior send of
113
- * this campaign" — and a template-filtered check both anchor on it. Negative
114
- * checks are NOT EXISTS of the same positive-engagement subquery, so
115
- * `notOpened()` reads "no opened send of this campaign", including members
116
- * who received nothing (e.g. suppressed on the prior wave).
109
+ * Engagement over THIS campaign's prior deliveries, anchored on the indexed
110
+ * `campaign_id` column (stamped on every campaign-dispatched row regardless
111
+ * of key format; suppressed rows carry it too but have no engagement
112
+ * timestamps, so they can never match positively). Negative checks are NOT
113
+ * EXISTS of the same positive-engagement subquery, so `notOpened()` reads
114
+ * "no opened send of this campaign", including members who received nothing
115
+ * (e.g. suppressed on the prior wave).
117
116
  */
118
117
  function engagementSql(
119
118
  condition: EmailEngagementCondition,
@@ -129,7 +128,7 @@ function engagementSql(
129
128
  : sql.empty();
130
129
  const positive = sql`exists (
131
130
  select 1 from ${emailSends}
132
- where ${emailSends.idempotencyKey} like ${campaignSendKeyPattern(campaignId)}
131
+ where ${emailSends.campaignId} = ${campaignId}
133
132
  and ${emailSends.toEmail} = ${campaignRecipients.email}
134
133
  and ${engagedAt} is not null${templateFilter}
135
134
  )`;
package/src/container.ts CHANGED
@@ -490,7 +490,7 @@ export interface HogsendClientOptions {
490
490
  */
491
491
  conversionDestinations?: ConversionDestination[];
492
492
  /**
493
- * CRM sync providers (docs/revenue-attribution-plan.md §4) — the pluggable
493
+ * CRM sync providers — the pluggable
494
494
  * layer that pushes leads INTO client CRMs and lands pipeline stage changes
495
495
  * + deal values back on the event spine as `funnel.stage_changed`. Register
496
496
  * one (`provider`) or many (`providers`); each is webhook-served at
@@ -23,8 +23,8 @@ import type { OutboundEventName } from "../lib/outbound.js";
23
23
  * NOTE: `defineDestination` is for event FAN-OUT to product/data tools
24
24
  * (PostHog, Segment, Slack, a CRM, a warehouse). Ad-platform conversion
25
25
  * forwarding (Meta CAPI, Google Enhanced Conversions) is Hogsend-native but
26
- * lives in its own sibling layer (`defineConversionDestination`, per
27
- * docs/revenue-attribution-plan.md) — it needs identifier hashing, click-id
26
+ * lives in its own sibling layer (`defineConversionDestination`) — it needs
27
+ * identifier hashing, click-id
28
28
  * joins, and deterministic event_id idempotency this generic pipe deliberately
29
29
  * does not have. It is NOT deferred to any third-party CDP: the money path has
30
30
  * no external dependency.
@@ -117,10 +117,15 @@ export async function reconcileDefinedFlags(opts: {
117
117
  }
118
118
 
119
119
  // A same-key flag owned by an operator/Studio (origin != "code") is never
120
- // clobbered by a code definition — leave it and warn.
120
+ // clobbered by a code definition — leave it and warn. The warn names the
121
+ // resolution because this is easy to trip innocently: `origin` defaults
122
+ // to "native" on insert, so any row seeded out-of-band (SQL, a seed
123
+ // script) for a code-defined key lands here on every boot.
121
124
  if (existing.origin !== "code") {
122
125
  logger.warn(
123
- "flags: key already owned by a non-code flag — leaving it untouched",
126
+ `flags: key "${key}" already owned by a non-code flag (origin "${existing.origin}") — leaving it untouched. ` +
127
+ "If this row should be code-owned (contract-synced from defineFlag), set origin = 'code' on it; " +
128
+ "otherwise remove the defineFlag that shares this key.",
124
129
  { key, origin: existing.origin },
125
130
  );
126
131
  result.skipped++;
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,
@@ -69,7 +70,7 @@ import {
69
70
  registerRecordLabel,
70
71
  } from "./journey-boundary.js";
71
72
  import { logTransition } from "./journey-log.js";
72
- import { recordOnce } from "./record-once.js";
73
+ import { readRecordedValue, recordOnce } from "./record-once.js";
73
74
 
74
75
  /** Journey statuses that are terminal — a journey in any of these must never be
75
76
  * resurrected back to "active" by a wait resuming. Exported so the durable task
@@ -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,7 +378,42 @@ 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> => {
386
+ // Terminal mark (the digest pattern): the recorded outcome — NOT the
387
+ // deadline — is what makes this wait replay-stable. `waitDeadline` is a
388
+ // shared column cleared at resolution so the NEXT wait site can mint its
389
+ // own, which means a replay-from-top of an ALREADY-RESOLVED wait re-derives
390
+ // a shifted scan window in which the resolving row is typically invisible —
391
+ // a re-armed wait could then flip to the timeout branch (duplicate-but-
392
+ // different sends downstream: the exact divergence class this engine's
393
+ // replay-safety design forbids). So the outcome is frozen set-once under
394
+ // `__waits__` and a replay returns it verbatim before touching the
395
+ // deadline. Registering the label makes an intra-run duplicate wait label
396
+ // a loud authoring error instead of a silent stale-outcome replay.
397
+ registerRecordLabel(getJourneyBoundary(), `wait:${nodeId}`);
398
+ const outcomeKey = `${nodeId}:result`;
399
+ const priorOutcome = await readRecordedValue({
400
+ db,
401
+ stateId,
402
+ namespace: "__waits__",
403
+ key: outcomeKey,
404
+ });
405
+ if (priorOutcome !== undefined) {
406
+ return priorOutcome as WaitForEventResult;
407
+ }
408
+ const recordOutcome = (o: WaitForEventResult) =>
409
+ recordOnce({
410
+ db,
411
+ stateId,
412
+ namespace: "__waits__",
413
+ key: outcomeKey,
414
+ compute: () => o,
415
+ });
416
+
359
417
  // Durable deadline: read-first / set-once.
360
418
  const stateRow = await db
361
419
  .select({ waitDeadline: journeyStates.waitDeadline })
@@ -393,15 +451,23 @@ export function createJourneyContext(
393
451
  // Narrowing only — `scanForMatch` re-verifies every row in JS.
394
452
  const eqPreds = eqPushdownPreds(where);
395
453
 
396
- const scanForMatch = async (): Promise<NonNullable<
397
- WaitForEventResult["properties"]
398
- > | null> => {
454
+ const scanForMatch = async (): Promise<{
455
+ properties: NonNullable<WaitForEventResult["properties"]>;
456
+ actorUserId: string;
457
+ } | null> => {
399
458
  const recent = await db
400
- .select({ properties: userEvents.properties })
459
+ .select({
460
+ properties: userEvents.properties,
461
+ userId: userEvents.userId,
462
+ })
401
463
  .from(userEvents)
402
464
  .where(
403
465
  and(
404
- eq(userEvents.userId, userId),
466
+ // Group scope matches ANY member's row via the persisted
467
+ // association map; user scope keeps the enrolled-user predicate.
468
+ groupScope
469
+ ? sql`${userEvents.groups} ->> ${groupScope.type} = ${groupScope.key}`
470
+ : eq(userEvents.userId, userId),
405
471
  eq(userEvents.event, event),
406
472
  gte(userEvents.occurredAt, scanSince),
407
473
  ...eqPreds,
@@ -417,7 +483,7 @@ export function createJourneyContext(
417
483
  if (
418
484
  evaluatePropertyConditions({ conditions: where, properties: props })
419
485
  ) {
420
- return narrowScalars(props);
486
+ return { properties: narrowScalars(props), actorUserId: row.userId };
421
487
  }
422
488
  }
423
489
  return null;
@@ -427,7 +493,7 @@ export function createJourneyContext(
427
493
  const preHit = await scanForMatch();
428
494
  if (preHit) {
429
495
  await clearDeadline();
430
- return { timedOut: false, properties: preHit };
496
+ return recordOutcome({ timedOut: false, ...preHit });
431
497
  }
432
498
 
433
499
  await enterWait(nodeId, "wait");
@@ -436,7 +502,7 @@ export function createJourneyContext(
436
502
  while (true) {
437
503
  const hit = await scanForMatch();
438
504
  if (hit) {
439
- outcome = { timedOut: false, properties: hit };
505
+ outcome = { timedOut: false, ...hit };
440
506
  break;
441
507
  }
442
508
 
@@ -462,7 +528,9 @@ export function createJourneyContext(
462
528
  Or(
463
529
  new UserEventCondition(
464
530
  event,
465
- `input.userId == ${celStringLiteral(userId)}`,
531
+ groupScope
532
+ ? buildGroupEventFilter(groupScope.type, groupScope.key)
533
+ : `input.userId == ${celStringLiteral(userId)}`,
466
534
  "event",
467
535
  ),
468
536
  new SleepCondition(toSleepDuration(remainingMs), "timeout"),
@@ -474,9 +542,7 @@ export function createJourneyContext(
474
542
  // Timeout branch — one final scan for an event landing exactly as the
475
543
  // sleep expired, then conclude.
476
544
  const last = await scanForMatch();
477
- outcome = last
478
- ? { timedOut: false, properties: last }
479
- : { timedOut: true };
545
+ outcome = last ? { timedOut: false, ...last } : { timedOut: true };
480
546
  break;
481
547
  }
482
548
  // Event branch: loop — the next scan picks up the (already persisted) row
@@ -485,7 +551,7 @@ export function createJourneyContext(
485
551
 
486
552
  await resumeFromWait(nodeId, { timedOut: outcome.timedOut });
487
553
  await clearDeadline();
488
- return outcome;
554
+ return recordOutcome(outcome);
489
555
  };
490
556
 
491
557
  // Durably wait for THIS user's `event` OR `timeout`, whichever fires first,
@@ -496,6 +562,7 @@ export function createJourneyContext(
496
562
  nodeId: string,
497
563
  lookback?: DurationObject,
498
564
  where?: PropertyCondition[],
565
+ group?: GroupScopeOption,
499
566
  ): Promise<WaitForEventResult> => {
500
567
  // Reject a timeout longer than the journey task's executionTimeout up front
501
568
  // so it fails fast at authoring time. (Eviction-capable engines may allow
@@ -512,15 +579,34 @@ export function createJourneyContext(
512
579
  // it — set it before dispatching to either wait path.
513
580
  setBoundaryLabel(nodeId);
514
581
 
582
+ // A group-scoped wait resolves its scope ONCE, up front (explicit key →
583
+ // trigger association → recorded → sole membership; recordOnce is DB-only,
584
+ // so this issues no durable journal node), and ALWAYS takes the filtered
585
+ // leg — the legacy leg below has no re-arm scan and no timeout final scan.
586
+ // An empty `where` there is vacuous (`evaluatePropertyConditions` is
587
+ // Array.every; `eqPushdownPreds([])` is empty).
588
+ let groupScope: { type: string; key: string } | undefined;
589
+ if (group) {
590
+ groupScope = await resolveGroupScope({
591
+ db,
592
+ stateId,
593
+ journeyId: config.journeyId ?? "unknown",
594
+ contactId: config.contactId,
595
+ triggerGroups: config.triggerGroups,
596
+ option: group,
597
+ });
598
+ }
599
+
515
600
  // WHERE-filtered wait takes the durable re-arm path; an empty/absent `where`
516
601
  // keeps the exact legacy single-wait below byte-for-byte.
517
- if (where && where.length > 0) {
602
+ if (groupScope || (where && where.length > 0)) {
518
603
  return performFilteredWaitForEvent(
519
604
  event,
520
605
  timeout,
521
606
  nodeId,
522
- where,
607
+ where ?? [],
523
608
  lookback,
609
+ groupScope,
524
610
  );
525
611
  }
526
612
 
@@ -570,6 +656,8 @@ export function createJourneyContext(
570
656
  timedOut: false,
571
657
  properties: scalars,
572
658
  ...(occurredAt ? { occurredAt } : {}),
659
+ // Lookback rows are user-scoped, so the actor IS the enrolled user.
660
+ actorUserId: userId,
573
661
  };
574
662
  }
575
663
  }
@@ -603,6 +691,7 @@ export function createJourneyContext(
603
691
  // ({ userId, userEmail, properties }); the pre-eviction path may hand the
604
692
  // payload back un-wrapped — tolerate both, mirroring the CREATE-strip.
605
693
  let properties: WaitForEventResult["properties"];
694
+ let actorUserId: string | undefined;
606
695
  if (!timedOut) {
607
696
  const matches = fired.event;
608
697
  const first = Array.isArray(matches) ? matches[0] : matches;
@@ -621,6 +710,13 @@ export function createJourneyContext(
621
710
  ) {
622
711
  properties = candidate as NonNullable<WaitForEventResult["properties"]>;
623
712
  }
713
+ // This leg's CEL filter is user-scoped, so the actor is the enrolled
714
+ // user; prefer the fired payload's top-level `userId` when carried.
715
+ const actor =
716
+ payload && typeof payload === "object" && "userId" in payload
717
+ ? (payload as { userId?: unknown }).userId
718
+ : undefined;
719
+ actorUserId = typeof actor === "string" ? actor : userId;
624
720
  }
625
721
 
626
722
  await resumeFromWait(nodeId, { timedOut });
@@ -628,7 +724,11 @@ export function createJourneyContext(
628
724
  // reads a replay-stable instant (eviction engine) rather than the seed.
629
725
  await refreshNow();
630
726
 
631
- return { timedOut, ...(properties ? { properties } : {}) };
727
+ return {
728
+ timedOut,
729
+ ...(properties ? { properties } : {}),
730
+ ...(actorUserId ? { actorUserId } : {}),
731
+ };
632
732
  };
633
733
 
634
734
  // Scan the digest window ONCE at flush: all `event` rows for THIS user in
@@ -1046,13 +1146,14 @@ export function createJourneyContext(
1046
1146
  );
1047
1147
  },
1048
1148
 
1049
- async waitForEvent({ event, timeout, label, lookback, where }) {
1149
+ async waitForEvent({ event, timeout, label, lookback, where, group }) {
1050
1150
  return performWaitForEvent(
1051
1151
  event,
1052
1152
  timeout,
1053
1153
  label ?? `wait-event:${event}`,
1054
1154
  lookback,
1055
1155
  normalizeWhere(where),
1156
+ group,
1056
1157
  );
1057
1158
  },
1058
1159
 
@@ -1211,7 +1312,39 @@ export function createJourneyContext(
1211
1312
  },
1212
1313
 
1213
1314
  history: {
1214
- async hasEvent({ userId: targetUserId, event, within }) {
1315
+ async hasEvent({ userId: targetUserId, event, within, group }) {
1316
+ // Group REPLACES the userId scoping: count rows via the persisted
1317
+ // association map (same jsonb predicate as the wait scan). Resolution
1318
+ // is READ-ONLY (`record: false`) — a history read never writes
1319
+ // `__groupKeys__`.
1320
+ if (group) {
1321
+ const scope = await resolveGroupScope({
1322
+ db,
1323
+ stateId,
1324
+ journeyId: config.journeyId ?? "unknown",
1325
+ contactId: config.contactId,
1326
+ triggerGroups: config.triggerGroups,
1327
+ option: group,
1328
+ record: false,
1329
+ });
1330
+ const [row] = await db
1331
+ .select({ count: sql<number>`count(*)` })
1332
+ .from(userEvents)
1333
+ .where(
1334
+ and(
1335
+ sql`${userEvents.groups} ->> ${scope.type} = ${scope.key}`,
1336
+ eq(userEvents.event, event),
1337
+ within
1338
+ ? gte(
1339
+ userEvents.occurredAt,
1340
+ new Date(Date.now() - durationToMs(within)),
1341
+ )
1342
+ : undefined,
1343
+ ),
1344
+ );
1345
+ const total = Number(row?.count ?? 0);
1346
+ return { found: total > 0, count: total };
1347
+ }
1215
1348
  const result = await evaluateEventCondition({
1216
1349
  condition: {
1217
1350
  type: "event",