@hogsend/engine 0.59.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +19 -10
  3. package/src/buckets/check-membership.ts +55 -8
  4. package/src/buckets/membership-epoch.ts +11 -1
  5. package/src/campaigns/cohort-sql.ts +3 -0
  6. package/src/index.ts +10 -6
  7. package/src/journeys/execute-journey-run.ts +119 -50
  8. package/src/journeys/journey-context.ts +43 -7
  9. package/src/lib/agent/tools.ts +29 -4
  10. package/src/lib/attribution-backfill.ts +27 -4
  11. package/src/lib/attribution.ts +22 -3
  12. package/src/lib/connector-actions.ts +4 -1
  13. package/src/lib/contacts.ts +408 -152
  14. package/src/lib/conversion-dispatch.ts +16 -2
  15. package/src/lib/enrollment-guards.ts +19 -12
  16. package/src/lib/feed.ts +5 -5
  17. package/src/lib/flags.ts +26 -9
  18. package/src/lib/ingestion.ts +14 -2
  19. package/src/lib/journey-lift.ts +17 -5
  20. package/src/lib/preferences.ts +78 -29
  21. package/src/lib/recipient-preferences.ts +16 -2
  22. package/src/lib/revenue.ts +20 -5
  23. package/src/lib/sms-tracked.ts +18 -1
  24. package/src/lib/tracked.ts +19 -8
  25. package/src/lib/tracking-events.ts +28 -0
  26. package/src/lib/unique-violation.ts +44 -0
  27. package/src/routes/admin/buckets.ts +20 -2
  28. package/src/routes/admin/bulk.ts +14 -2
  29. package/src/routes/admin/contacts.ts +4 -3
  30. package/src/routes/admin/conversions.ts +20 -4
  31. package/src/routes/admin/emails.ts +17 -2
  32. package/src/routes/admin/events.ts +32 -41
  33. package/src/routes/admin/funnels.ts +6 -1
  34. package/src/routes/admin/groups.ts +4 -0
  35. package/src/routes/admin/impact.ts +30 -10
  36. package/src/routes/admin/journey-impact.ts +18 -9
  37. package/src/routes/admin/journeys.ts +8 -1
  38. package/src/routes/admin/maintenance.ts +7 -1
  39. package/src/routes/admin/preferences.ts +85 -46
  40. package/src/routes/admin/reporting.ts +25 -5
  41. package/src/routes/admin/targeting.ts +1 -0
  42. package/src/routes/admin/timeline.ts +16 -10
  43. package/src/routes/email/preferences.ts +18 -1
  44. package/src/routes/lists/index.ts +6 -6
  45. package/src/workflows/backfill-contact-id.ts +210 -30
  46. package/src/workflows/bucket-backfill.ts +145 -67
  47. package/src/workflows/bucket-reconcile.ts +150 -50
  48. package/src/workflows/check-alerts.ts +4 -0
  49. package/src/workflows/impact-digest.ts +10 -3
  50. package/src/workflows/journey-blueprint-interpreter.ts +8 -1
  51. package/src/workflows/send-campaign.ts +18 -11
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.59.0",
3
+ "version": "0.60.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -53,18 +53,18 @@
53
53
  "svix": "^1.95.1",
54
54
  "winston": "^3.19.0",
55
55
  "zod": "^4.4.3",
56
- "@hogsend/attribution": "^0.59.0",
57
- "@hogsend/core": "^0.59.0",
58
- "@hogsend/db": "^0.59.0",
59
- "@hogsend/email": "^0.59.0",
60
- "@hogsend/plugin-posthog": "^0.59.0",
61
- "@hogsend/plugin-resend": "^0.59.0",
62
- "@hogsend/sms": "^0.59.0"
56
+ "@hogsend/attribution": "^0.60.0",
57
+ "@hogsend/core": "^0.60.0",
58
+ "@hogsend/db": "^0.60.0",
59
+ "@hogsend/email": "^0.60.0",
60
+ "@hogsend/plugin-posthog": "^0.60.0",
61
+ "@hogsend/plugin-resend": "^0.60.0",
62
+ "@hogsend/sms": "^0.60.0"
63
63
  },
64
64
  "optionalDependencies": {
65
- "@hogsend/plugin-apollo": "^0.59.0",
66
- "@hogsend/plugin-postmark": "^0.59.0",
67
- "@hogsend/plugin-twilio": "^0.59.0"
65
+ "@hogsend/plugin-apollo": "^0.60.0",
66
+ "@hogsend/plugin-postmark": "^0.60.0",
67
+ "@hogsend/plugin-twilio": "^0.60.0"
68
68
  },
69
69
  "devDependencies": {
70
70
  "@types/node": "^22.15.3",
@@ -57,10 +57,14 @@ function toError(err: unknown): Error {
57
57
  * container re-binds the accessors with a `dbResolver` that returns its own
58
58
  * `db`; the `getDb()` default bypasses the container.
59
59
  *
60
- * Every query `innerJoin`s `contacts` on `externalId` and filters
61
- * `isNull(deletedAt)` on both tables — GDPR parity with every reconcile/admin
62
- * query. No method throws (except the iterator on a page error); failures are
63
- * carried in the result's `error`.
60
+ * Every query `innerJoin`s `contacts` on the membership's OWNING CONTACT
61
+ * (`bucket_memberships.contact_id`) and filters `isNull(deletedAt)` on both
62
+ * tables — GDPR parity with every reconcile/admin query. The join used to run
63
+ * on the mutable text key (`coalesce(external_id, anonymous_id, id) =
64
+ * user_id`); it now runs on the FK, so a membership adopted onto a contact
65
+ * under a since-stale key stays visible instead of dropping out of every count
66
+ * and page. No method throws (except the iterator on a page error); failures
67
+ * are carried in the result's `error`.
64
68
  */
65
69
  export function createBucketAccessor(
66
70
  bucketId: string,
@@ -75,7 +79,7 @@ export function createBucketAccessor(
75
79
  const rows = await db
76
80
  .select({ value: countFn() })
77
81
  .from(bucketMemberships)
78
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
82
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
79
83
  .where(
80
84
  and(
81
85
  eq(bucketMemberships.bucketId, bucketId),
@@ -95,15 +99,20 @@ export function createBucketAccessor(
95
99
  ): Promise<{ data: boolean; error: Error | null }> {
96
100
  try {
97
101
  const db = dbResolver();
98
- // O(1) probe on the partial active unique index (uq_user_bucket_active).
102
+ // The subject predicate moves to the CONTACT side: `userId` is the caller's
103
+ // canonical key, so we name the contact it resolves to and let the FK join
104
+ // find that contact's membership. Probing `bucket_memberships.user_id`
105
+ // instead answers "false" for a member whose row was adopted under an
106
+ // anon-era key — the person is in the bucket, `has()` says they are not,
107
+ // and every gate built on it silently opens.
99
108
  const rows = await db
100
109
  .select({ id: bucketMemberships.id })
101
110
  .from(bucketMemberships)
102
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
111
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
103
112
  .where(
104
113
  and(
105
114
  eq(bucketMemberships.bucketId, bucketId),
106
- eq(bucketMemberships.userId, userId),
115
+ eq(contactKeySql(), userId),
107
116
  eq(bucketMemberships.status, "active"),
108
117
  isNull(bucketMemberships.deletedAt),
109
118
  isNull(contacts.deletedAt),
@@ -145,7 +154,7 @@ export function createBucketAccessor(
145
154
  entryCount: bucketMemberships.entryCount,
146
155
  })
147
156
  .from(bucketMemberships)
148
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
157
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
149
158
  .where(and(...conditions))
150
159
  .orderBy(bucketMemberships.id)
151
160
  // +1 peek to detect a next page.
@@ -153,7 +162,7 @@ export function createBucketAccessor(
153
162
  db
154
163
  .select({ value: countFn() })
155
164
  .from(bucketMemberships)
156
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
165
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
157
166
  .where(
158
167
  and(
159
168
  eq(bucketMemberships.bucketId, bucketId),
@@ -1,6 +1,7 @@
1
1
  import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import {
3
3
  type BucketMeta,
4
+ bySubject,
4
5
  collectPropertyNames,
5
6
  durationToMs,
6
7
  evaluateCondition,
@@ -235,10 +236,17 @@ export async function checkBucketMembership(opts: {
235
236
  if (!bucket.criteria) continue;
236
237
 
237
238
  // wasMember — current active, non-deleted membership row (cheap pre-filter;
238
- // the authoritative guard is the RETURNING-gated mutation below).
239
+ // the authoritative guard is the RETURNING-gated mutation below). Read by
240
+ // SUBJECT: a membership adopted onto this contact under a since-stale key
241
+ // is invisible to a `user_id` probe, and missing it re-runs the JOIN path,
242
+ // which then loses the arbiter-less race and no-ops — a member who silently
243
+ // never re-emits and never leaves.
239
244
  const active = await db.query.bucketMemberships.findFirst({
240
245
  where: and(
241
- eq(bucketMemberships.userId, userId),
246
+ bySubject(bucketMemberships, {
247
+ contactId: contactId ?? null,
248
+ userKey: userId,
249
+ }),
242
250
  eq(bucketMemberships.bucketId, bucket.id),
243
251
  eq(bucketMemberships.status, "active"),
244
252
  isNull(bucketMemberships.deletedAt),
@@ -252,7 +260,16 @@ export async function checkBucketMembership(opts: {
252
260
  // sub-conditions read the merged journeyContext.
253
261
  const isMember = await evaluateCondition({
254
262
  condition: bucket.criteria,
255
- ctx: { db, userId, journeyContext },
263
+ ctx: {
264
+ db,
265
+ userId,
266
+ // `ingestEvent` resolved the subject before calling us, so the event /
267
+ // count legs read this person's whole history — including the rows
268
+ // adopted from an anon-era key — instead of only what the current
269
+ // string key happens to name.
270
+ contactId: contactId ?? null,
271
+ journeyContext,
272
+ },
256
273
  });
257
274
 
258
275
  if (!wasMember && isMember) {
@@ -324,13 +341,27 @@ async function handleJoin(opts: {
324
341
  // this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the entryLimit
325
342
  // gate. Shared with the reconcile-discovered join path so the ordinal can
326
343
  // never drift between the two writers.
327
- const priorCount = await countPriorMemberships(db, bucket.id, userId);
344
+ const priorCount = await countPriorMemberships(
345
+ db,
346
+ bucket.id,
347
+ userId,
348
+ contactId ?? null,
349
+ );
328
350
  const epoch = priorCount + 1;
329
351
 
330
- // INSERT a FRESH active row. ON CONFLICT DO NOTHING targets the partial active
352
+ // INSERT a FRESH active row. ON CONFLICT DO NOTHING covers the partial active
331
353
  // unique index (uq_user_bucket_active): a concurrent emitter that already
332
354
  // inserted the active row makes THIS insert return zero rows → we do NOT emit
333
355
  // (the loser mutates nothing — Section 6.3 governing rule).
356
+ //
357
+ // PRD 05 T3 — the DO NOTHING is deliberately ARBITER-LESS. Two partial unique
358
+ // indexes now guard this table (uq_user_bucket_active and its contact-scoped
359
+ // twin uq_contact_bucket_active), Postgres allows only ONE conflict target per
360
+ // statement, and both must land in the same "already a member" branch: the
361
+ // contact one is what catches an adopted row whose `user_id` still differs.
362
+ // Narrowing this to a column target would let that collision escape as a raw
363
+ // 23505 — and a target naming `contact_id` would additionally miss every
364
+ // contactless (NULL) member.
334
365
  const expiresAt = computeExpiresAt(bucket);
335
366
  // Unconditional TTL deadline — set once on join, swept by the reconcile cron.
336
367
  const maxDwellAt = computeMaxDwellAt(bucket);
@@ -386,7 +417,15 @@ async function handleJoin(opts: {
386
417
  // The active row is always written (Studio size must reflect reality) and the
387
418
  // epoch always advances via the real insert; only the bucket:entered emission
388
419
  // is gated by the entryLimit policy (Section 6.3).
389
- if (await shouldEmitJoin({ db, bucket, userId, priorCount })) {
420
+ if (
421
+ await shouldEmitJoin({
422
+ db,
423
+ bucket,
424
+ userId,
425
+ contactId: contactId ?? null,
426
+ priorCount,
427
+ })
428
+ ) {
390
429
  await emitBucketTransition({
391
430
  db,
392
431
  registry,
@@ -532,9 +571,17 @@ export async function shouldEmitJoin(opts: {
532
571
  db: Database;
533
572
  bucket: BucketMeta;
534
573
  userId: string;
574
+ /**
575
+ * The owning contact's `contacts.id`, or `null` when the caller has none.
576
+ * REQUIRED (not optional) on purpose: the prior-cycle lookup below is the
577
+ * cooldown gate, and an optional field a caller forgets silently drops it
578
+ * back onto the mutable text key — which misses the adopted prior cycle and
579
+ * re-emits a `once` join. Pass `null` explicitly for a contactless subject.
580
+ */
581
+ contactId: string | null;
535
582
  priorCount: number;
536
583
  }): Promise<boolean> {
537
- const { db, bucket, userId, priorCount } = opts;
584
+ const { db, bucket, userId, contactId, priorCount } = opts;
538
585
  // First-ever join always emits.
539
586
  if (priorCount === 0) return true;
540
587
  switch (bucket.entryLimit ?? "unlimited") {
@@ -556,7 +603,7 @@ export async function shouldEmitJoin(opts: {
556
603
  .from(bucketMemberships)
557
604
  .where(
558
605
  and(
559
- eq(bucketMemberships.userId, userId),
606
+ bySubject(bucketMemberships, { contactId, userKey: userId }),
560
607
  eq(bucketMemberships.bucketId, bucket.id),
561
608
  eq(bucketMemberships.status, "left"),
562
609
  isNotNull(bucketMemberships.leftAt),
@@ -1,5 +1,6 @@
1
1
  import {
2
2
  type BucketMeta,
3
+ bySubject,
3
4
  type ConditionEval,
4
5
  type DurationObject,
5
6
  durationToMs,
@@ -25,18 +26,27 @@ export const BUCKET_EVENT_PREFIX = "bucket:";
25
26
  *
26
27
  * The predicate MUST stay status-agnostic — narrowing it (e.g. to active-only)
27
28
  * would corrupt entryCount and the entryLimit cooldown.
29
+ *
30
+ * `contactId` is REQUIRED (not optional) for the same reason
31
+ * `checkEntryLimit`'s is: an optional field silently defaults a new caller onto
32
+ * the mutable text key, and here that under-counts the epoch — a person whose
33
+ * anon-era memberships were adopted would re-enter at ordinal 1 and slip the
34
+ * `once`/`once_per_period` gate. Pass `null` explicitly for a subject with no
35
+ * contact; that is a permanent, supported state (memberships are text-keyed
36
+ * with no contact FK).
28
37
  */
29
38
  export async function countPriorMemberships(
30
39
  db: Database,
31
40
  bucketId: string,
32
41
  userId: string,
42
+ contactId: string | null,
33
43
  ): Promise<number> {
34
44
  const [counted] = await db
35
45
  .select({ priorCount: sql<number>`count(*)::int` })
36
46
  .from(bucketMemberships)
37
47
  .where(
38
48
  and(
39
- eq(bucketMemberships.userId, userId),
49
+ bySubject(bucketMemberships, { contactId, userKey: userId }),
40
50
  eq(bucketMemberships.bucketId, bucketId),
41
51
  ),
42
52
  );
@@ -161,6 +161,9 @@ function eventSql(condition: EventCondition, startedAt: Date): SQL {
161
161
  Date.now() - durationToMs(condition.within),
162
162
  ).toISOString()}::timestamptz`
163
163
  : sql.empty();
164
+ // PRD 05 T8 — this correlation STAYS string-keyed: `campaign_recipients`
165
+ // has no `contact_id` column, so the text key is the only subject available
166
+ // on the outer side of the join.
164
167
  const positive = sql`exists (
165
168
  select 1 from ${userEvents}
166
169
  where ${userEvents.userId} = ${campaignRecipients.userId}
package/src/index.ts CHANGED
@@ -37,14 +37,18 @@ export type {
37
37
  // types) so content can import everything from `@hogsend/engine`.
38
38
  export * from "@hogsend/core";
39
39
  // --- Capability-provider contracts (canonical origin: @hogsend/core) ---
40
- // Email provider contract + analytics contract, re-exported so consumers can
41
- // import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
42
- // omitted here: the engine's public `SendEmailOptions` is the high-level
43
- // journey-facing send options from `./lib/email.js`; the provider-contract
44
- // `SendEmailOptions` remains available via `@hogsend/core`.)
45
- export {
40
+ // Email provider contract + analytics contract, plus `bySubject` (the
41
+ // either/or history scope every engine-side history read is expected to move
42
+ // onto), re-exported so consumers can import them from `@hogsend/engine`.
43
+ // (`SendEmailOptions` is intentionally omitted here: the engine's public
44
+ // `SendEmailOptions` is the high-level journey-facing send options from
45
+ // `./lib/email.js`; the provider-contract `SendEmailOptions` remains available
46
+ // via `@hogsend/core`.)
47
+ export {
48
+ bySubject,
46
49
  defineAnalyticsProvider,
47
50
  defineEmailProvider,
51
+ type Subject,
48
52
  WebhookHandshakeSignal,
49
53
  } from "@hogsend/core";
50
54
  export {
@@ -1,6 +1,6 @@
1
1
  import type { Conditions } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
3
- import { type DurationObject, durationToMs } from "@hogsend/core";
3
+ import { bySubject, type DurationObject, durationToMs } from "@hogsend/core";
4
4
  import type {
5
5
  JourneyMeta,
6
6
  JourneyRunFn,
@@ -28,6 +28,10 @@ import { ingestEvent } from "../lib/ingestion.js";
28
28
  import { createLogger } from "../lib/logger.js";
29
29
  import { emitOutbound } from "../lib/outbound.js";
30
30
  import { resolveTimezoneWithSource } from "../lib/timezone.js";
31
+ import {
32
+ isUniqueViolationOn,
33
+ UQ_CONTACT_JOURNEY_ACTIVE,
34
+ } from "../lib/unique-violation.js";
31
35
  import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
32
36
  import { JourneyExitedError } from "./errors.js";
33
37
  import {
@@ -171,6 +175,17 @@ async function resolveEnrollmentContactId(opts: {
171
175
  * CONFLICT specification") at runtime. The `where` reproduces the index
172
176
  * predicate (`status IN ('active','waiting')`) EXACTLY — see
173
177
  * journey-states.ts:uq_user_journey_active.
178
+ *
179
+ * PRD 05 T3 — the arbiter deliberately STAYS on the string key. The second live
180
+ * index, `uq_contact_journey_active`, cannot be an arbiter here: drizzle's
181
+ * `target` accepts columns only (no expression), and a bare
182
+ * `(contact_id, journey_id)` target would never fire for a NULL `contact_id` —
183
+ * i.e. for every anonymous visitor, a permanent supported state — so an
184
+ * anonymous re-trigger of a live journey would insert a second row and die on
185
+ * the string index. Instead its 23505 is caught below and mapped to the SAME
186
+ * zero-rows outcome, which the caller reads as `already_active`. That is the
187
+ * correct answer: the contact IS already live in this journey, under a different
188
+ * string key that adoption has since folded onto the same contact.
174
189
  */
175
190
  export async function insertEnrollment(opts: {
176
191
  db: Database;
@@ -224,24 +239,39 @@ export async function insertEnrollment(opts: {
224
239
  where: sql`status IN ('active', 'waiting')`,
225
240
  };
226
241
 
227
- if (!opts.serializeWithGraphLock) {
228
- const [row] = await opts.db
229
- .insert(journeyStates)
230
- .values(values)
231
- .onConflictDoNothing(onConflict)
232
- .returning();
233
- return row;
234
- }
242
+ try {
243
+ if (!opts.serializeWithGraphLock) {
244
+ const [row] = await opts.db
245
+ .insert(journeyStates)
246
+ .values(values)
247
+ .onConflictDoNothing(onConflict)
248
+ .returning();
249
+ return row;
250
+ }
235
251
 
236
- return opts.db.transaction(async (tx) => {
237
- await tx.execute(blueprintGraphLock(opts.journeyId));
238
- const [row] = await tx
239
- .insert(journeyStates)
240
- .values(values)
241
- .onConflictDoNothing(onConflict)
242
- .returning();
243
- return row;
244
- });
252
+ // `await` (not a bare return) so a 23505 raised inside the transaction is
253
+ // caught HERE, after the transaction has already rolled back.
254
+ return await opts.db.transaction(async (tx) => {
255
+ await tx.execute(blueprintGraphLock(opts.journeyId));
256
+ const [row] = await tx
257
+ .insert(journeyStates)
258
+ .values(values)
259
+ .onConflictDoNothing(onConflict)
260
+ .returning();
261
+ return row;
262
+ });
263
+ } catch (err) {
264
+ if (!isUniqueViolationOn(err, UQ_CONTACT_JOURNEY_ACTIVE)) throw err;
265
+ // Same contact, DIFFERENT string key, already live in this journey. Zero
266
+ // rows is exactly what the string arbiter returns for the same situation,
267
+ // and the caller maps it to the `already_active` skip.
268
+ logger.info("journey enrollment skipped — contact already live", {
269
+ journeyId: opts.journeyId,
270
+ userId: opts.userId,
271
+ contactId: opts.contactId ?? null,
272
+ });
273
+ return undefined;
274
+ }
245
275
  }
246
276
 
247
277
  export interface ExecuteJourneyRunOptions {
@@ -335,6 +365,26 @@ export async function executeJourneyRun(
335
365
 
336
366
  let state = recovered;
337
367
 
368
+ // The subject this run's ENTRY reads and writes history for, resolved AT MOST
369
+ // ONCE. PRD 05 T4 moved the entry guards off the mutable `user_id` string and
370
+ // onto `bySubject`, so the guards now need the same value the enrollment
371
+ // insert already stamped — memoizing it keeps that at one resolve per run
372
+ // rather than one per reader (`undefined` = not yet resolved; `null` = a
373
+ // resolved-to-nothing subject, which is a permanent supported state and must
374
+ // not re-probe).
375
+ let resolvedContactId: string | null | undefined;
376
+ const enrollmentContactId = async (): Promise<string | null> => {
377
+ if (resolvedContactId === undefined) {
378
+ resolvedContactId = await resolveEnrollmentContactId({
379
+ db,
380
+ userId,
381
+ journeyId: meta.id,
382
+ pushed: input.contactId,
383
+ });
384
+ }
385
+ return resolvedContactId;
386
+ };
387
+
338
388
  // FIRST ENTRY ONLY — the enrollment guards gate ENTRY, not resume. A
339
389
  // recovered enrollment already passed them on first entry, so it skips
340
390
  // straight to resuming the run. (Sends inside `run` still re-check
@@ -364,6 +414,7 @@ export async function executeJourneyRun(
364
414
  db,
365
415
  journey: meta,
366
416
  userId,
417
+ contactId: await enrollmentContactId(),
367
418
  });
368
419
  const entryPolicy = evaluateEnrollmentPolicy({
369
420
  journey: meta,
@@ -374,7 +425,11 @@ export async function executeJourneyRun(
374
425
  return { status: "skipped", reason: entryPolicy.reason };
375
426
  }
376
427
 
377
- const prefs = await checkEmailPreferences({ db, userId });
428
+ const prefs = await checkEmailPreferences({
429
+ db,
430
+ userId,
431
+ contactId: await enrollmentContactId(),
432
+ });
378
433
  const preferencePolicy = evaluateEnrollmentPolicy({
379
434
  journey: meta,
380
435
  properties,
@@ -407,26 +462,23 @@ export async function executeJourneyRun(
407
462
  if (!holdoutPolicy.allowed) {
408
463
  const priorHoldout = await db.query.journeyStates.findFirst({
409
464
  where: and(
410
- eq(journeyStates.userId, userId),
465
+ bySubject(journeyStates, {
466
+ contactId: await enrollmentContactId(),
467
+ userKey: userId,
468
+ }),
411
469
  eq(journeyStates.journeyId, meta.id),
412
470
  eq(journeyStates.status, "held_out"),
413
471
  ),
414
472
  });
415
473
  if (!priorHoldout) {
416
474
  const heldOutAt = new Date();
417
- // PRD 04 dual-write. This is deliberately its OWN D6-wrapped resolve
418
- // rather than a hoist of the `subjectContactId` compute below: that
419
- // compute lives INSIDE the ingest try/catch, and lifting it out would
420
- // change which failures skip the `journey.heldout` re-emit — a
421
- // control-flow change to the identity-provenance path, made for
422
- // bookkeeping. Cost on this once-ever-per-(user, journey) path: one
423
- // live-PK validation probe with a pushed pin, 1-2 probes without.
424
- const heldOutContactId = await resolveEnrollmentContactId({
425
- db,
426
- userId,
427
- journeyId: meta.id,
428
- pushed: input.contactId,
429
- });
475
+ // PRD 04 dual-write, via the run-scoped memo the guard above already
476
+ // paid for (identical arguments, so identical value). Deliberately
477
+ // NOT the `subjectContactId` compute below: that one lives INSIDE the
478
+ // ingest try/catch, and hoisting it would change which failures skip
479
+ // the `journey.heldout` re-emit — a control-flow change to the
480
+ // identity-provenance path, made for bookkeeping.
481
+ const heldOutContactId = await enrollmentContactId();
430
482
  const inserted = await db
431
483
  .insert(journeyStates)
432
484
  .values({
@@ -560,7 +612,10 @@ export async function executeJourneyRun(
560
612
 
561
613
  const activeState = await db.query.journeyStates.findFirst({
562
614
  where: and(
563
- eq(journeyStates.userId, userId),
615
+ bySubject(journeyStates, {
616
+ contactId: await enrollmentContactId(),
617
+ userKey: userId,
618
+ }),
564
619
  eq(journeyStates.journeyId, meta.id),
565
620
  inArray(journeyStates.status, ["active", "waiting"]),
566
621
  ),
@@ -574,6 +629,21 @@ export async function executeJourneyRun(
574
629
  return { status: "skipped", reason: activePolicy.reason };
575
630
  }
576
631
 
632
+ // PRD 04 dual-write — the pushed pin when ingest resolved one, else one
633
+ // D6-wrapped probe. NULL (unknown subject / refused resolve) is a legal
634
+ // stamp: the enrollment proceeds exactly as before. Resolved FRESH here
635
+ // (not via the guard-time memo): the guard chain is long enough for a
636
+ // concurrent identify to mint the subject's contact mid-window, and a
637
+ // stale NULL stamp on the insert would sit outside the contact-scoped
638
+ // unique index that backstops double-enrollment. The memo cache is
639
+ // refreshed with the result so later readers agree with the stamp.
640
+ resolvedContactId = await resolveEnrollmentContactId({
641
+ db,
642
+ userId,
643
+ journeyId: meta.id,
644
+ pushed: input.contactId,
645
+ });
646
+
577
647
  // A successful insert always returns exactly one row, so undefined here
578
648
  // can ONLY mean a burst-race conflict (see insertEnrollment's doc for
579
649
  // the race + arbiter mechanics) — the same outcome as the read guard,
@@ -592,15 +662,7 @@ export async function executeJourneyRun(
592
662
  hatchetRunId: workflowRunId,
593
663
  journeyVersionHash: meta.versionHash ?? null,
594
664
  journeyVersionLabel: meta.version ?? null,
595
- // PRD 04 dual-write — the pushed pin when ingest resolved one, else one
596
- // D6-wrapped probe. NULL (unknown subject / refused resolve) is a legal
597
- // stamp: the enrollment proceeds exactly as before.
598
- contactId: await resolveEnrollmentContactId({
599
- db,
600
- userId,
601
- journeyId: meta.id,
602
- pushed: input.contactId,
603
- }),
665
+ contactId: resolvedContactId,
604
666
  serializeWithGraphLock: options.serializeEnrollment,
605
667
  });
606
668
  if (!state) {
@@ -634,6 +696,9 @@ export async function executeJourneyRun(
634
696
  stateId,
635
697
  journeyId: meta.id,
636
698
  journeyName: meta.name,
699
+ // The enrollment row's OWN stamp — replay-stable (a recovered run reads
700
+ // back what first entry wrote) and NULL for a contactless subject.
701
+ contactId: state.contactId,
637
702
  };
638
703
 
639
704
  // The injected analytics instance (set by createHogsendClient). Same
@@ -708,14 +773,18 @@ export async function executeJourneyRun(
708
773
  journeyId: meta.id,
709
774
  entryLimit: meta.entryLimit,
710
775
  ...(meta.entryPeriod ? { entryPeriod: meta.entryPeriod } : {}),
711
- // Group-scope resolution inputs: the trigger event's association map
712
- // (rides the task input, replay-stable) and the subject contact id —
713
- // the pushed contactId when present, else the contact row already
714
- // fetched for timezone above (best-effort: undefined only defers the
715
- // resolver's no-contact throw to the membership leg).
776
+ // The subject contact id — feeds BOTH the group-scope resolver and (PRD
777
+ // 05 T4) every bySubject history read on the context. `state.contactId`
778
+ // FIRST: it is the enrollment row's own stamp, validated by
779
+ // `resolveEnrollmentContactId` (a merged-away tombstone pin is rejected
780
+ // and re-resolved to the survivor) and replay-stable, where the raw
781
+ // pushed pin can be stale by the queue delay and the `contact` row here
782
+ // is an externalId-only best-effort fetch that misses anon-keyed
783
+ // contacts. The pin/row legs remain only as fallbacks for a NULL stamp
784
+ // (a pre-column-era recovered enrollment the sweep has not reached).
716
785
  ...(input.groups ? { triggerGroups: input.groups } : {}),
717
- ...((input.contactId ?? contact?.id)
718
- ? { contactId: input.contactId ?? contact?.id }
786
+ ...((state.contactId ?? input.contactId ?? contact?.id)
787
+ ? { contactId: state.contactId ?? input.contactId ?? contact?.id }
719
788
  : {}),
720
789
  });
721
790