@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
@@ -252,13 +252,22 @@ export const bucketExpiryTask = hatchet.durableTask({
252
252
  // re-qualified (e.g. fired the event again), do not leave. Load merged
253
253
  // contact properties iff a property leg needs them so property predicates
254
254
  // match the real-time path instead of evaluating against undefined.
255
+ const owner = await resolveLiveContact(db, input.userId);
255
256
  const journeyContext =
256
257
  collectPropertyNames(bucket.criteria).length > 0
257
- ? await loadContactProperties(db, input.userId)
258
+ ? (owner?.properties ?? {})
258
259
  : {};
259
260
  const stillMember = await evaluateCondition({
260
261
  condition: bucket.criteria,
261
- ctx: { db, userId: input.userId, journeyContext },
262
+ ctx: {
263
+ db,
264
+ userId: input.userId,
265
+ // Resolved from the armed key. `null` for a contactless subject is
266
+ // correct and supported — `bySubject` then reads by the text key, which
267
+ // is the only history that subject has.
268
+ contactId: owner?.id ?? null,
269
+ journeyContext,
270
+ },
262
271
  });
263
272
  if (stillMember) {
264
273
  return { status: "skipped", reason: "still_member" };
@@ -390,32 +399,42 @@ async function selectEventLeavers(
390
399
  : null;
391
400
 
392
401
  // Active members of this bucket whose contact is live (GDPR — Section 8.6).
402
+ // The subject key of BOTH sides of this set-based join is now the owning
403
+ // contact, not the mutable text key: `user_id` rides along only because the
404
+ // leave emit re-ingests under it.
393
405
  const members = db
394
- .select({ userId: bucketMemberships.userId })
406
+ .select({
407
+ userId: bucketMemberships.userId,
408
+ contactId: bucketMemberships.contactId,
409
+ })
395
410
  .from(bucketMemberships)
396
411
  .where(
397
412
  and(
398
413
  eq(bucketMemberships.bucketId, bucket.id),
399
414
  eq(bucketMemberships.status, "active"),
400
415
  isNull(bucketMemberships.deletedAt),
416
+ isNotNull(bucketMemberships.contactId),
401
417
  ),
402
418
  )
403
419
  .as("members");
404
420
 
405
- // The windowed count of the criterion's event per member, set-based.
421
+ // The windowed count of the criterion's event per member, set-based. Grouped
422
+ // by the owning contact so a person's anon-era events count toward the window
423
+ // that decides whether they stay in the bucket.
406
424
  const counted = db
407
425
  .select({
408
- userId: userEvents.userId,
426
+ contactId: userEvents.contactId,
409
427
  cnt: sql<number>`count(*)::int`.as("cnt"),
410
428
  })
411
429
  .from(userEvents)
412
430
  .where(
413
431
  and(
414
432
  eq(userEvents.event, criteria.eventName),
433
+ isNotNull(userEvents.contactId),
415
434
  cutoff ? gte(userEvents.occurredAt, cutoff) : undefined,
416
435
  ),
417
436
  )
418
- .groupBy(userEvents.userId)
437
+ .groupBy(userEvents.contactId)
419
438
  .as("counted");
420
439
 
421
440
  // LEFT JOIN members → windowed counts. A missing/zero count is a 0. The
@@ -428,8 +447,8 @@ async function selectEventLeavers(
428
447
  cnt: sql<number>`coalesce(${counted.cnt}, 0)`,
429
448
  })
430
449
  .from(members)
431
- .leftJoin(counted, eq(members.userId, counted.userId))
432
- .innerJoin(contacts, eq(contactKeySql(), members.userId))
450
+ .leftJoin(counted, eq(members.contactId, counted.contactId))
451
+ .innerJoin(contacts, eq(contacts.id, members.contactId))
433
452
  .where(isNull(contacts.deletedAt));
434
453
 
435
454
  return rows
@@ -459,12 +478,12 @@ async function reconcileCompositeLeaves(opts: {
459
478
  .select({
460
479
  userId: bucketMemberships.userId,
461
480
  // Joined contact row → its id is the provenance pin for the leave emit
462
- // (issue #608).
481
+ // (issue #608) AND the subject the per-member criteria evaluate for.
463
482
  contactId: contacts.id,
464
483
  properties: contacts.properties,
465
484
  })
466
485
  .from(bucketMemberships)
467
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
486
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
468
487
  .where(
469
488
  and(
470
489
  eq(bucketMemberships.bucketId, bucket.id),
@@ -485,7 +504,14 @@ async function reconcileCompositeLeaves(opts: {
485
504
  : {};
486
505
  const isMember = await evaluateCondition({
487
506
  condition: criteria,
488
- ctx: { db, userId: member.userId, journeyContext },
507
+ ctx: {
508
+ db,
509
+ userId: member.userId,
510
+ // The joined contact IS the subject, so the event/count legs read the
511
+ // whole person rather than whatever the membership's text key names.
512
+ contactId: member.contactId,
513
+ journeyContext,
514
+ },
489
515
  });
490
516
  if (!isMember) {
491
517
  leavers.push({ userId: member.userId, contactId: member.contactId });
@@ -494,6 +520,11 @@ async function reconcileCompositeLeaves(opts: {
494
520
 
495
521
  // Bump lastEvaluatedAt for the whole chunk so the next tick advances the cursor
496
522
  // (including stable members, which are NOT leavers).
523
+ //
524
+ // NOT a subject read: `evaluatedIds` are the `user_id` values of the rows the
525
+ // SELECT above just returned, so this re-names those exact rows rather than
526
+ // asking who a person is. It stays exact because `uq_user_bucket_active` is
527
+ // retained (PRD 05 D5) — at most one active row per (user_id, bucket).
497
528
  if (evaluatedIds.length > 0) {
498
529
  await db
499
530
  .update(bucketMemberships)
@@ -542,7 +573,7 @@ async function reconcileBucketTtlLeaves(opts: {
542
573
  contactId: contacts.id,
543
574
  })
544
575
  .from(bucketMemberships)
545
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
576
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
546
577
  .where(
547
578
  and(
548
579
  eq(bucketMemberships.bucketId, bucket.id),
@@ -584,8 +615,10 @@ async function bulkLeave(opts: {
584
615
  const { db, logger, journeyRegistry, bucket, leavers, reason } = opts;
585
616
  const userIds = leavers.map((l) => l.userId);
586
617
  // Membership key → resolved contact row id, for the emit's provenance pin.
587
- // Safe to key by userId: the partial-active unique index guarantees one
588
- // active row per (user, bucket), so a flipped row maps to exactly one leaver.
618
+ // Safe to key by userId, and safe for the `inArray` re-selection below: every
619
+ // leaver was read off `bucket_memberships` itself, and the retained
620
+ // `uq_user_bucket_active` (PRD 05 D5) guarantees one active row per
621
+ // (user_id, bucket) — so this names rows, it does not resolve identity.
589
622
  const contactIdByUser = new Map(
590
623
  leavers.map((l) => [l.userId, l.contactId] as const),
591
624
  );
@@ -723,10 +756,13 @@ async function claimCoalesceCohort(opts: {
723
756
  const now = new Date();
724
757
  const maxDwellMs = bucket.maxDwell ? durationToMs(bucket.maxDwell) : null;
725
758
 
726
- // The cohort is exactly "resolves by the canonical key, but NOT by
727
- // external_id" — the set the old join could not see. A correlated EXISTS
728
- // keeps this a single UPDATE; the columns mirror the age clocks the
729
- // dwell/TTL passes read (`coalesce(dwellAnchorAt, enteredAt)` and
759
+ // The cohort is exactly "owned by a live contact that has no external_id" —
760
+ // the set the pre-#625 `external_id` join could not see. The correlated
761
+ // EXISTS now matches on the owning contact (`bucket_memberships.contact_id`)
762
+ // rather than re-deriving the canonical key, which is the same cohort on
763
+ // undivergent data and additionally reaches a membership adopted under a
764
+ // stale key. A single UPDATE either way; the columns mirror the age clocks
765
+ // the dwell/TTL passes read (`coalesce(dwellAnchorAt, enteredAt)` and
730
766
  // `maxDwellAt`).
731
767
  const claimed = await db
732
768
  .update(bucketMemberships)
@@ -746,7 +782,7 @@ async function claimCoalesceCohort(opts: {
746
782
  isNull(bucketMemberships.deletedAt),
747
783
  sql`exists (
748
784
  select 1 from contacts c
749
- where coalesce(c.external_id, c.anonymous_id, c.id::text) = ${bucketMemberships.userId}
785
+ where c.id = ${bucketMemberships.contactId}
750
786
  and c.deleted_at is null
751
787
  and c.external_id is null
752
788
  )`,
@@ -819,7 +855,7 @@ async function reconcileBucketDwell(opts: {
819
855
  dwellState: bucketMemberships.dwellState,
820
856
  })
821
857
  .from(bucketMemberships)
822
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
858
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
823
859
  .where(
824
860
  and(
825
861
  eq(bucketMemberships.bucketId, bucket.id),
@@ -982,20 +1018,26 @@ async function reconcileBucketJoins(opts: {
982
1018
  // never-active signups and bounds the scan to the once-active cohort.
983
1019
  const everFiredEvents = Array.from(new Set(absenceLegs.map((l) => l.event)));
984
1020
  const everFired = db
985
- .selectDistinct({ userId: userEvents.userId })
1021
+ .selectDistinct({ contactId: userEvents.contactId })
986
1022
  .from(userEvents)
987
- .where(inArray(userEvents.event, everFiredEvents))
1023
+ .where(
1024
+ and(
1025
+ inArray(userEvents.event, everFiredEvents),
1026
+ isNotNull(userEvents.contactId),
1027
+ ),
1028
+ )
988
1029
  .as("ever_fired");
989
1030
 
990
1031
  // Users who already have an active membership (skip — they are members).
991
1032
  const activeMembers = db
992
- .select({ userId: bucketMemberships.userId })
1033
+ .select({ contactId: bucketMemberships.contactId })
993
1034
  .from(bucketMemberships)
994
1035
  .where(
995
1036
  and(
996
1037
  eq(bucketMemberships.bucketId, bucket.id),
997
1038
  eq(bucketMemberships.status, "active"),
998
1039
  isNull(bucketMemberships.deletedAt),
1040
+ isNotNull(bucketMemberships.contactId),
999
1041
  ),
1000
1042
  )
1001
1043
  .as("active_members");
@@ -1019,41 +1061,41 @@ async function reconcileBucketJoins(opts: {
1019
1061
  ? selectPresentInAllWindows(db, absenceLegs)
1020
1062
  : null;
1021
1063
 
1022
- // The membership/event tables key on the RESOLVED string key (external_id ??
1023
- // anonymous_id ?? contact.id), NOT necessarily external_id — email-only /
1024
- // anonymous contacts have a NULL external_id and are keyed on their uuid /
1025
- // anonymous_id. Joining on contacts.externalId would force external_id NOT NULL
1026
- // for every candidate (the coalesce would collapse to external_id) and silently
1027
- // drop exactly the dormant email-only contacts this cron exists to reconcile.
1028
- // Join on the SAME coalesce expression so the projected key matches the join.
1064
+ // Every join below is on the OWNING CONTACT (`contacts.id`), not on any
1065
+ // string key. The scan starts from `contacts`, so history and membership are
1066
+ // matched by the FK that names the person — a member whose events or
1067
+ // membership sit under a since-stale key is neither missed as a candidate nor
1068
+ // re-offered as one they already hold.
1069
+ //
1070
+ // `contactKeySql()` survives here as a PROJECTION only: `reconcileJoinOne`
1071
+ // writes `bucket_memberships.user_id` and the join emit re-ingests under it,
1072
+ // so the candidate still has to carry the canonical string key.
1029
1073
  const contactKey = contactKeySql();
1030
1074
 
1031
1075
  const baseQuery = db
1032
1076
  .select({
1033
1077
  userId: contactKey,
1034
- // The candidate scan reads straight off `contacts`, so the row id rides
1035
- // along as the provenance pin for the join emit (issue #608) —
1036
- // load-bearing for exactly the null-external_id contacts this coalesce
1037
- // join exists to include.
1078
+ // The candidate scan reads straight off `contacts`, so the row id is both
1079
+ // the join key and the provenance pin for the join emit (issue #608).
1038
1080
  contactId: contacts.id,
1039
1081
  email: contacts.email,
1040
1082
  })
1041
1083
  .from(contacts)
1042
- .innerJoin(everFired, eq(everFired.userId, contactKey))
1043
- .leftJoin(activeMembers, eq(activeMembers.userId, contactKey));
1084
+ .innerJoin(everFired, eq(everFired.contactId, contacts.id))
1085
+ .leftJoin(activeMembers, eq(activeMembers.contactId, contacts.id));
1044
1086
 
1045
1087
  const candidates = await (presentInAll
1046
1088
  ? baseQuery
1047
- .leftJoin(presentInAll, eq(presentInAll.userId, contactKey))
1089
+ .leftJoin(presentInAll, eq(presentInAll.contactId, contacts.id))
1048
1090
  .where(
1049
1091
  and(
1050
1092
  isNull(contacts.deletedAt),
1051
- isNull(activeMembers.userId),
1052
- isNull(presentInAll.userId),
1093
+ isNull(activeMembers.contactId),
1094
+ isNull(presentInAll.contactId),
1053
1095
  ),
1054
1096
  )
1055
1097
  : baseQuery.where(
1056
- and(isNull(contacts.deletedAt), isNull(activeMembers.userId)),
1098
+ and(isNull(contacts.deletedAt), isNull(activeMembers.contactId)),
1057
1099
  )
1058
1100
  )
1059
1101
  // Deterministic scan order for the bounded re-run (no keyset cursor; the
@@ -1097,11 +1139,18 @@ async function reconcileBucketJoins(opts: {
1097
1139
  for (const candidate of candidates) {
1098
1140
  if (!exact) {
1099
1141
  const journeyContext = needsProps
1100
- ? await loadContactProperties(db, candidate.userId)
1142
+ ? await loadContactProperties(db, candidate.contactId)
1101
1143
  : {};
1102
1144
  const isMember = await evaluateCondition({
1103
1145
  condition: criteria,
1104
- ctx: { db, userId: candidate.userId, journeyContext },
1146
+ ctx: {
1147
+ db,
1148
+ userId: candidate.userId,
1149
+ // The scan reads straight off `contacts`, so the subject is exact and
1150
+ // the confirm sees every event this person owns.
1151
+ contactId: candidate.contactId,
1152
+ journeyContext,
1153
+ },
1105
1154
  });
1106
1155
  if (!isMember) continue;
1107
1156
  }
@@ -1183,27 +1232,61 @@ function selectPresentInAllWindows(db: Database, legs: AbsenceLeg[]) {
1183
1232
  ),
1184
1233
  );
1185
1234
  return db
1186
- .select({ userId: userEvents.userId })
1235
+ .select({ contactId: userEvents.contactId })
1187
1236
  .from(userEvents)
1188
- .where(or(...perLeg))
1189
- .groupBy(userEvents.userId)
1237
+ .where(and(or(...perLeg), isNotNull(userEvents.contactId)))
1238
+ .groupBy(userEvents.contactId)
1190
1239
  .having(sql`count(distinct ${userEvents.event}) >= ${legs.length}`)
1191
1240
  .as("present_all");
1192
1241
  }
1193
1242
 
1194
- /** The merged stored properties of a contact (for property-leg evaluation). */
1243
+ /**
1244
+ * The merged stored properties of a contact (for property-leg evaluation),
1245
+ * looked up by the contact's own id.
1246
+ *
1247
+ * It used to look up `contacts.external_id = <canonical key>`, which never
1248
+ * matched an email-only or anonymous contact (their `external_id` is NULL and
1249
+ * their canonical key is the uuid / `anonymous_id`), so every property leg
1250
+ * silently evaluated against `{}` for exactly the cohort the coalesce join was
1251
+ * added to include. Both callers already hold the contact id.
1252
+ */
1195
1253
  async function loadContactProperties(
1196
1254
  db: Database,
1197
- userId: string,
1255
+ contactId: string,
1198
1256
  ): Promise<Record<string, unknown>> {
1199
1257
  const [contact] = await db
1200
1258
  .select({ properties: contacts.properties })
1201
1259
  .from(contacts)
1202
- .where(eq(contacts.externalId, userId))
1260
+ .where(eq(contacts.id, contactId))
1203
1261
  .limit(1);
1204
1262
  return (contact?.properties as Record<string, unknown> | null) ?? {};
1205
1263
  }
1206
1264
 
1265
+ /**
1266
+ * The live contact a canonical string key resolves to, or `null`. Used by the
1267
+ * fast-expiry timer, which is handed only the key on its Hatchet payload and so
1268
+ * has no contact row in scope. A READ-side lookup is admissible where the
1269
+ * emit's provenance pin is not: the pin must be unforgeable because it decides
1270
+ * which row a WRITE folds into, whereas this only decides whose history the
1271
+ * criteria re-confirm reads — and it reads the same key the task is already
1272
+ * keyed on.
1273
+ */
1274
+ async function resolveLiveContact(
1275
+ db: Database,
1276
+ userKey: string,
1277
+ ): Promise<{ id: string; properties: Record<string, unknown> } | null> {
1278
+ const [contact] = await db
1279
+ .select({ id: contacts.id, properties: contacts.properties })
1280
+ .from(contacts)
1281
+ .where(and(eq(contactKeySql(), userKey), isNull(contacts.deletedAt)))
1282
+ .limit(1);
1283
+ if (!contact) return null;
1284
+ return {
1285
+ id: contact.id,
1286
+ properties: (contact.properties as Record<string, unknown> | null) ?? {},
1287
+ };
1288
+ }
1289
+
1207
1290
  /**
1208
1291
  * Insert ONE reconcile-discovered join (RETURNING-gated on the partial-active
1209
1292
  * unique index) and emit `bucket:entered`. entryCount = 1 + prior memberships.
@@ -1226,7 +1309,12 @@ async function reconcileJoinOne(opts: {
1226
1309
 
1227
1310
  // entryCount ordinal = 1 + ALL prior memberships (active + left). Shared with
1228
1311
  // the real-time join path so the ordinal never drifts between the two writers.
1229
- const priorCount = await countPriorMemberships(db, bucket.id, userId);
1312
+ const priorCount = await countPriorMemberships(
1313
+ db,
1314
+ bucket.id,
1315
+ userId,
1316
+ contactId ?? null,
1317
+ );
1230
1318
  const epoch = priorCount + 1;
1231
1319
 
1232
1320
  const inserted = await db
@@ -1246,6 +1334,10 @@ async function reconcileJoinOne(opts: {
1246
1334
  // this is zero new queries. `undefined` stamps NULL.
1247
1335
  contactId: contactId ?? null,
1248
1336
  })
1337
+ // PRD 05 T3 — ARBITER-LESS by design: it must absorb BOTH partial unique
1338
+ // indexes on this table (uq_user_bucket_active and the contact-scoped
1339
+ // uq_contact_bucket_active) into this one "already a member" branch. See
1340
+ // `checkBucketMembership`'s insert for the full note.
1249
1341
  .onConflictDoNothing()
1250
1342
  .returning({ id: bucketMemberships.id });
1251
1343
 
@@ -1257,7 +1349,15 @@ async function reconcileJoinOne(opts: {
1257
1349
  // epoch always advances via the real insert; only the bucket:entered emission
1258
1350
  // is gated by the entryLimit policy — mirrors the real-time join path so the
1259
1351
  // cron-discovered join cannot bypass entryLimit (Section 6.3).
1260
- if (await shouldEmitJoin({ db, bucket, userId, priorCount })) {
1352
+ if (
1353
+ await shouldEmitJoin({
1354
+ db,
1355
+ bucket,
1356
+ userId,
1357
+ contactId: contactId ?? null,
1358
+ priorCount,
1359
+ })
1360
+ ) {
1261
1361
  await emitBucketTransition({
1262
1362
  db,
1263
1363
  registry: journeyRegistry,
@@ -76,6 +76,10 @@ export async function surfaceStrandedWaiting(opts: {
76
76
  .select({
77
77
  id: journeyStates.id,
78
78
  journeyId: journeyStates.journeyId,
79
+ // Display echo for the alert payload — not a scoping predicate. The
80
+ // sweep is population-wide (`status = 'waiting'`), so there is no
81
+ // subject to scope by; the operator needs the stamped key to find the
82
+ // row in the admin surface.
79
83
  userId: journeyStates.userId,
80
84
  waitDeadline: journeyStates.waitDeadline,
81
85
  updatedAt: journeyStates.updatedAt,
@@ -153,6 +153,13 @@ async function versionCohort(opts: {
153
153
  const { db, journeyId, hash, goal, until } = opts;
154
154
  const untilTs = sql`${until.toISOString()}::timestamptz`;
155
155
  const goalCond = goal === null ? sql`` : sql` and c.definition_id = ${goal}`;
156
+ // Same subject/cohort pair as the /impact routes — see the rationale on
157
+ // `jsSubject`/`convBySubject` in `routes/admin/impact.ts`. The digest MUST
158
+ // count a cohort exactly the way the routes do, or the emailed number and
159
+ // the dashboard disagree. The coalesce is load-bearing: `count(distinct …)`
160
+ // skips NULLs, so a bare `js.contact_id` would drop contactless enrollments.
161
+ const jsSubject = sql`coalesce(js.contact_id::text, js.user_id)`;
162
+ const convBySubject = sql`c.contact_id = js.contact_id`;
156
163
  const rows = [
157
164
  ...(await db.execute<{
158
165
  enrollments: number;
@@ -161,12 +168,12 @@ async function versionCohort(opts: {
161
168
  version_label: string | null;
162
169
  }>(sql`
163
170
  select
164
- count(distinct js.user_id)
171
+ count(distinct ${jsSubject})
165
172
  filter (where js.status != 'held_out')::int as enrollments,
166
- (count(distinct js.user_id)
173
+ (count(distinct ${jsSubject})
167
174
  filter (where js.status != 'held_out' and exists (
168
175
  select 1 from conversions c
169
- where c.user_key = js.user_id
176
+ where ${convBySubject}
170
177
  and c.occurred_at >= js.created_at
171
178
  and c.occurred_at <= ${untilTs}${goalCond}
172
179
  )))::int as converters,
@@ -370,7 +370,14 @@ export async function walkBlueprintGraph(
370
370
  for (const condition of conditions) {
371
371
  const matched = await evaluateCondition({
372
372
  condition,
373
- ctx: { db, userId: user.id, journeyContext: user.properties },
373
+ ctx: {
374
+ db,
375
+ userId: user.id,
376
+ // The enrollment's own stamp — null for a contactless subject,
377
+ // which keeps the evaluator on the text key.
378
+ contactId: user.contactId ?? null,
379
+ journeyContext: user.properties,
380
+ },
374
381
  });
375
382
  if (!matched) return false;
376
383
  }
@@ -19,7 +19,7 @@ import {
19
19
  waveConditionSql,
20
20
  } from "../campaigns/cohort-sql.js";
21
21
  import { campaignSendKey } from "../lib/campaign-send-key.js";
22
- import { contactKeySql, normalizeEmail } from "../lib/contacts.js";
22
+ import { normalizeEmail } from "../lib/contacts.js";
23
23
  import { getDb } from "../lib/db.js";
24
24
  import { getEmailService } from "../lib/email.js";
25
25
  import { hatchet } from "../lib/hatchet.js";
@@ -982,15 +982,16 @@ async function* resolveBucketRecipients(
982
982
  contactEmail: contacts.email,
983
983
  })
984
984
  .from(bucketMemberships)
985
- // Join on the CANONICAL key, not `external_id` alone.
986
- // `bucket_memberships.user_id` holds `coalesce(external_id,
987
- // anonymous_id, id)`, so a contact with a NULL `external_id` — an
988
- // email-only subscriber keyed on its uuid, or an anonymous visitor
989
- // keyed on its `anonymous_id` — matched nothing here and was silently
990
- // dropped from the audience. They were genuine active members of the
991
- // bucket; they simply never received the campaign, and nothing
992
- // surfaced it: a send report showing 40 of 40 delivered looks complete
993
- // whether or not the audience was built correctly.
985
+ // Join on the OWNING CONTACT, not on any string key. This join has
986
+ // been narrowed twice before: on `external_id` it dropped every
987
+ // contact with a NULL one (an email-only subscriber keyed on its
988
+ // uuid, an anonymous visitor keyed on its `anonymous_id`), and on the
989
+ // canonical `coalesce(external_id, anonymous_id, id)` it still drops
990
+ // a member whose membership was adopted under a since-stale key.
991
+ // Either way they are genuine active members who silently never
992
+ // receive the campaign, and nothing surfaces it: a send report
993
+ // showing 40 of 40 delivered looks complete whether or not the
994
+ // audience was built correctly.
994
995
  //
995
996
  // Suppression is unaffected by widening this join. Every gate lives in
996
997
  // the same `conditions` array applied to this query and is keyed on
@@ -998,7 +999,7 @@ async function* resolveBucketRecipients(
998
999
  // and trimmed), not on the join column — so a newly-visible member is
999
1000
  // filtered by the identical unsubscribed/suppressed `NOT EXISTS` as
1000
1001
  // everyone else, and the mailer re-checks preferences per send.
1001
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
1002
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
1002
1003
  .where(and(...conditions))
1003
1004
  .orderBy(bucketMemberships.id)
1004
1005
  .limit(CHUNK_SIZE)
@@ -1092,6 +1093,12 @@ async function* resolveOptInListRecipients(
1092
1093
  map: (row) => {
1093
1094
  const categories = (row.categories ?? {}) as Record<string, boolean>;
1094
1095
  if (!listRegistry.isSubscribed(categories, listId)) return undefined;
1096
+ // PRD 05 T6 — deliberately NOT a subject read. This scan is
1097
+ // population-wide (every opted-in row), so there is no subject to scope
1098
+ // by; `row.userId` is the D9 recipient key the send writes back to
1099
+ // `email_sends.user_id` and the idempotency namespace keys off. It may
1100
+ // be frozen at opt-in time, but the contact RETAINS every key it ever
1101
+ // held, so the mailer's per-send resolve still finds the owner.
1095
1102
  return { email: normalizeEmail(row.email), userId: row.userId };
1096
1103
  },
1097
1104
  });