@hogsend/engine 0.59.0 → 0.61.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 (55) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +34 -11
  3. package/src/buckets/check-membership.ts +74 -10
  4. package/src/buckets/membership-epoch.ts +11 -1
  5. package/src/campaigns/cohort-sql.ts +10 -0
  6. package/src/index.ts +10 -6
  7. package/src/journeys/execute-journey-run.ts +139 -70
  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 +35 -4
  11. package/src/lib/attribution.ts +22 -3
  12. package/src/lib/connector-actions.ts +17 -17
  13. package/src/lib/contacts.ts +541 -175
  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/refine.ts +16 -10
  23. package/src/lib/revenue.ts +20 -5
  24. package/src/lib/sms-inbound.ts +6 -1
  25. package/src/lib/sms-tracked.ts +18 -1
  26. package/src/lib/timezone.ts +11 -1
  27. package/src/lib/tracked.ts +19 -8
  28. package/src/lib/tracking-events.ts +28 -0
  29. package/src/lib/unique-violation.ts +44 -0
  30. package/src/routes/admin/buckets.ts +21 -1
  31. package/src/routes/admin/bulk.ts +14 -2
  32. package/src/routes/admin/contacts.ts +20 -7
  33. package/src/routes/admin/conversions.ts +20 -4
  34. package/src/routes/admin/emails.ts +17 -2
  35. package/src/routes/admin/events.ts +32 -41
  36. package/src/routes/admin/funnels.ts +6 -1
  37. package/src/routes/admin/groups.ts +4 -0
  38. package/src/routes/admin/impact.ts +30 -10
  39. package/src/routes/admin/journey-impact.ts +18 -9
  40. package/src/routes/admin/journeys.ts +8 -1
  41. package/src/routes/admin/maintenance.ts +7 -1
  42. package/src/routes/admin/preferences.ts +85 -46
  43. package/src/routes/admin/reporting.ts +25 -5
  44. package/src/routes/admin/targeting.ts +1 -0
  45. package/src/routes/admin/timeline.ts +16 -10
  46. package/src/routes/email/preferences.ts +18 -1
  47. package/src/routes/feed/recipient.ts +5 -0
  48. package/src/routes/lists/index.ts +6 -6
  49. package/src/workflows/backfill-contact-id.ts +210 -30
  50. package/src/workflows/bucket-backfill.ts +145 -67
  51. package/src/workflows/bucket-reconcile.ts +164 -51
  52. package/src/workflows/check-alerts.ts +4 -0
  53. package/src/workflows/impact-digest.ts +10 -3
  54. package/src/workflows/journey-blueprint-interpreter.ts +8 -1
  55. package/src/workflows/send-campaign.ts +18 -11
@@ -41,7 +41,11 @@ import {
41
41
  import { getBucketRegistrySingleton } from "../buckets/registry-singleton.js";
42
42
  import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
43
43
  import { emitBucketTransition } from "../lib/bucket-emit.js";
44
- import { contactKeySql, normalizeEmailOrNull } from "../lib/contacts.js";
44
+ import {
45
+ contactKeySql,
46
+ lookupContactIdByKey,
47
+ normalizeEmailOrNull,
48
+ } from "../lib/contacts.js";
45
49
  import { hatchet } from "../lib/hatchet.js";
46
50
  import { toSleepDuration } from "../lib/hatchet-duration.js";
47
51
  import type { Logger } from "../lib/logger.js";
@@ -252,13 +256,22 @@ export const bucketExpiryTask = hatchet.durableTask({
252
256
  // re-qualified (e.g. fired the event again), do not leave. Load merged
253
257
  // contact properties iff a property leg needs them so property predicates
254
258
  // match the real-time path instead of evaluating against undefined.
259
+ const owner = await resolveLiveContact(db, input.userId);
255
260
  const journeyContext =
256
261
  collectPropertyNames(bucket.criteria).length > 0
257
- ? await loadContactProperties(db, input.userId)
262
+ ? (owner?.properties ?? {})
258
263
  : {};
259
264
  const stillMember = await evaluateCondition({
260
265
  condition: bucket.criteria,
261
- ctx: { db, userId: input.userId, journeyContext },
266
+ ctx: {
267
+ db,
268
+ userId: input.userId,
269
+ // Resolved from the armed key. `null` for a contactless subject is
270
+ // correct and supported — `bySubject` then reads by the text key, which
271
+ // is the only history that subject has.
272
+ contactId: owner?.id ?? null,
273
+ journeyContext,
274
+ },
262
275
  });
263
276
  if (stillMember) {
264
277
  return { status: "skipped", reason: "still_member" };
@@ -390,32 +403,42 @@ async function selectEventLeavers(
390
403
  : null;
391
404
 
392
405
  // Active members of this bucket whose contact is live (GDPR — Section 8.6).
406
+ // The subject key of BOTH sides of this set-based join is now the owning
407
+ // contact, not the mutable text key: `user_id` rides along only because the
408
+ // leave emit re-ingests under it.
393
409
  const members = db
394
- .select({ userId: bucketMemberships.userId })
410
+ .select({
411
+ userId: bucketMemberships.userId,
412
+ contactId: bucketMemberships.contactId,
413
+ })
395
414
  .from(bucketMemberships)
396
415
  .where(
397
416
  and(
398
417
  eq(bucketMemberships.bucketId, bucket.id),
399
418
  eq(bucketMemberships.status, "active"),
400
419
  isNull(bucketMemberships.deletedAt),
420
+ isNotNull(bucketMemberships.contactId),
401
421
  ),
402
422
  )
403
423
  .as("members");
404
424
 
405
- // The windowed count of the criterion's event per member, set-based.
425
+ // The windowed count of the criterion's event per member, set-based. Grouped
426
+ // by the owning contact so a person's anon-era events count toward the window
427
+ // that decides whether they stay in the bucket.
406
428
  const counted = db
407
429
  .select({
408
- userId: userEvents.userId,
430
+ contactId: userEvents.contactId,
409
431
  cnt: sql<number>`count(*)::int`.as("cnt"),
410
432
  })
411
433
  .from(userEvents)
412
434
  .where(
413
435
  and(
414
436
  eq(userEvents.event, criteria.eventName),
437
+ isNotNull(userEvents.contactId),
415
438
  cutoff ? gte(userEvents.occurredAt, cutoff) : undefined,
416
439
  ),
417
440
  )
418
- .groupBy(userEvents.userId)
441
+ .groupBy(userEvents.contactId)
419
442
  .as("counted");
420
443
 
421
444
  // LEFT JOIN members → windowed counts. A missing/zero count is a 0. The
@@ -428,8 +451,8 @@ async function selectEventLeavers(
428
451
  cnt: sql<number>`coalesce(${counted.cnt}, 0)`,
429
452
  })
430
453
  .from(members)
431
- .leftJoin(counted, eq(members.userId, counted.userId))
432
- .innerJoin(contacts, eq(contactKeySql(), members.userId))
454
+ .leftJoin(counted, eq(members.contactId, counted.contactId))
455
+ .innerJoin(contacts, eq(contacts.id, members.contactId))
433
456
  .where(isNull(contacts.deletedAt));
434
457
 
435
458
  return rows
@@ -459,12 +482,12 @@ async function reconcileCompositeLeaves(opts: {
459
482
  .select({
460
483
  userId: bucketMemberships.userId,
461
484
  // Joined contact row → its id is the provenance pin for the leave emit
462
- // (issue #608).
485
+ // (issue #608) AND the subject the per-member criteria evaluate for.
463
486
  contactId: contacts.id,
464
487
  properties: contacts.properties,
465
488
  })
466
489
  .from(bucketMemberships)
467
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
490
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
468
491
  .where(
469
492
  and(
470
493
  eq(bucketMemberships.bucketId, bucket.id),
@@ -485,7 +508,14 @@ async function reconcileCompositeLeaves(opts: {
485
508
  : {};
486
509
  const isMember = await evaluateCondition({
487
510
  condition: criteria,
488
- ctx: { db, userId: member.userId, journeyContext },
511
+ ctx: {
512
+ db,
513
+ userId: member.userId,
514
+ // The joined contact IS the subject, so the event/count legs read the
515
+ // whole person rather than whatever the membership's text key names.
516
+ contactId: member.contactId,
517
+ journeyContext,
518
+ },
489
519
  });
490
520
  if (!isMember) {
491
521
  leavers.push({ userId: member.userId, contactId: member.contactId });
@@ -494,6 +524,11 @@ async function reconcileCompositeLeaves(opts: {
494
524
 
495
525
  // Bump lastEvaluatedAt for the whole chunk so the next tick advances the cursor
496
526
  // (including stable members, which are NOT leavers).
527
+ //
528
+ // NOT a subject read: `evaluatedIds` are the `user_id` values of the rows the
529
+ // SELECT above just returned, so this re-names those exact rows rather than
530
+ // asking who a person is. It stays exact because `uq_user_bucket_active` is
531
+ // retained (PRD 05 D5) — at most one active row per (user_id, bucket).
497
532
  if (evaluatedIds.length > 0) {
498
533
  await db
499
534
  .update(bucketMemberships)
@@ -542,7 +577,7 @@ async function reconcileBucketTtlLeaves(opts: {
542
577
  contactId: contacts.id,
543
578
  })
544
579
  .from(bucketMemberships)
545
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
580
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
546
581
  .where(
547
582
  and(
548
583
  eq(bucketMemberships.bucketId, bucket.id),
@@ -584,8 +619,10 @@ async function bulkLeave(opts: {
584
619
  const { db, logger, journeyRegistry, bucket, leavers, reason } = opts;
585
620
  const userIds = leavers.map((l) => l.userId);
586
621
  // 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.
622
+ // Safe to key by userId, and safe for the `inArray` re-selection below: every
623
+ // leaver was read off `bucket_memberships` itself, and the retained
624
+ // `uq_user_bucket_active` (PRD 05 D5) guarantees one active row per
625
+ // (user_id, bucket) — so this names rows, it does not resolve identity.
589
626
  const contactIdByUser = new Map(
590
627
  leavers.map((l) => [l.userId, l.contactId] as const),
591
628
  );
@@ -723,10 +760,13 @@ async function claimCoalesceCohort(opts: {
723
760
  const now = new Date();
724
761
  const maxDwellMs = bucket.maxDwell ? durationToMs(bucket.maxDwell) : null;
725
762
 
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
763
+ // The cohort is exactly "owned by a live contact that has no external_id" —
764
+ // the set the pre-#625 `external_id` join could not see. The correlated
765
+ // EXISTS now matches on the owning contact (`bucket_memberships.contact_id`)
766
+ // rather than re-deriving the canonical key, which is the same cohort on
767
+ // undivergent data and additionally reaches a membership adopted under a
768
+ // stale key. A single UPDATE either way; the columns mirror the age clocks
769
+ // the dwell/TTL passes read (`coalesce(dwellAnchorAt, enteredAt)` and
730
770
  // `maxDwellAt`).
731
771
  const claimed = await db
732
772
  .update(bucketMemberships)
@@ -746,7 +786,7 @@ async function claimCoalesceCohort(opts: {
746
786
  isNull(bucketMemberships.deletedAt),
747
787
  sql`exists (
748
788
  select 1 from contacts c
749
- where coalesce(c.external_id, c.anonymous_id, c.id::text) = ${bucketMemberships.userId}
789
+ where c.id = ${bucketMemberships.contactId}
750
790
  and c.deleted_at is null
751
791
  and c.external_id is null
752
792
  )`,
@@ -819,7 +859,7 @@ async function reconcileBucketDwell(opts: {
819
859
  dwellState: bucketMemberships.dwellState,
820
860
  })
821
861
  .from(bucketMemberships)
822
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
862
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
823
863
  .where(
824
864
  and(
825
865
  eq(bucketMemberships.bucketId, bucket.id),
@@ -982,20 +1022,26 @@ async function reconcileBucketJoins(opts: {
982
1022
  // never-active signups and bounds the scan to the once-active cohort.
983
1023
  const everFiredEvents = Array.from(new Set(absenceLegs.map((l) => l.event)));
984
1024
  const everFired = db
985
- .selectDistinct({ userId: userEvents.userId })
1025
+ .selectDistinct({ contactId: userEvents.contactId })
986
1026
  .from(userEvents)
987
- .where(inArray(userEvents.event, everFiredEvents))
1027
+ .where(
1028
+ and(
1029
+ inArray(userEvents.event, everFiredEvents),
1030
+ isNotNull(userEvents.contactId),
1031
+ ),
1032
+ )
988
1033
  .as("ever_fired");
989
1034
 
990
1035
  // Users who already have an active membership (skip — they are members).
991
1036
  const activeMembers = db
992
- .select({ userId: bucketMemberships.userId })
1037
+ .select({ contactId: bucketMemberships.contactId })
993
1038
  .from(bucketMemberships)
994
1039
  .where(
995
1040
  and(
996
1041
  eq(bucketMemberships.bucketId, bucket.id),
997
1042
  eq(bucketMemberships.status, "active"),
998
1043
  isNull(bucketMemberships.deletedAt),
1044
+ isNotNull(bucketMemberships.contactId),
999
1045
  ),
1000
1046
  )
1001
1047
  .as("active_members");
@@ -1019,41 +1065,41 @@ async function reconcileBucketJoins(opts: {
1019
1065
  ? selectPresentInAllWindows(db, absenceLegs)
1020
1066
  : null;
1021
1067
 
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.
1068
+ // Every join below is on the OWNING CONTACT (`contacts.id`), not on any
1069
+ // string key. The scan starts from `contacts`, so history and membership are
1070
+ // matched by the FK that names the person — a member whose events or
1071
+ // membership sit under a since-stale key is neither missed as a candidate nor
1072
+ // re-offered as one they already hold.
1073
+ //
1074
+ // `contactKeySql()` survives here as a PROJECTION only: `reconcileJoinOne`
1075
+ // writes `bucket_memberships.user_id` and the join emit re-ingests under it,
1076
+ // so the candidate still has to carry the canonical string key.
1029
1077
  const contactKey = contactKeySql();
1030
1078
 
1031
1079
  const baseQuery = db
1032
1080
  .select({
1033
1081
  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.
1082
+ // The candidate scan reads straight off `contacts`, so the row id is both
1083
+ // the join key and the provenance pin for the join emit (issue #608).
1038
1084
  contactId: contacts.id,
1039
1085
  email: contacts.email,
1040
1086
  })
1041
1087
  .from(contacts)
1042
- .innerJoin(everFired, eq(everFired.userId, contactKey))
1043
- .leftJoin(activeMembers, eq(activeMembers.userId, contactKey));
1088
+ .innerJoin(everFired, eq(everFired.contactId, contacts.id))
1089
+ .leftJoin(activeMembers, eq(activeMembers.contactId, contacts.id));
1044
1090
 
1045
1091
  const candidates = await (presentInAll
1046
1092
  ? baseQuery
1047
- .leftJoin(presentInAll, eq(presentInAll.userId, contactKey))
1093
+ .leftJoin(presentInAll, eq(presentInAll.contactId, contacts.id))
1048
1094
  .where(
1049
1095
  and(
1050
1096
  isNull(contacts.deletedAt),
1051
- isNull(activeMembers.userId),
1052
- isNull(presentInAll.userId),
1097
+ isNull(activeMembers.contactId),
1098
+ isNull(presentInAll.contactId),
1053
1099
  ),
1054
1100
  )
1055
1101
  : baseQuery.where(
1056
- and(isNull(contacts.deletedAt), isNull(activeMembers.userId)),
1102
+ and(isNull(contacts.deletedAt), isNull(activeMembers.contactId)),
1057
1103
  )
1058
1104
  )
1059
1105
  // Deterministic scan order for the bounded re-run (no keyset cursor; the
@@ -1097,11 +1143,18 @@ async function reconcileBucketJoins(opts: {
1097
1143
  for (const candidate of candidates) {
1098
1144
  if (!exact) {
1099
1145
  const journeyContext = needsProps
1100
- ? await loadContactProperties(db, candidate.userId)
1146
+ ? await loadContactProperties(db, candidate.contactId)
1101
1147
  : {};
1102
1148
  const isMember = await evaluateCondition({
1103
1149
  condition: criteria,
1104
- ctx: { db, userId: candidate.userId, journeyContext },
1150
+ ctx: {
1151
+ db,
1152
+ userId: candidate.userId,
1153
+ // The scan reads straight off `contacts`, so the subject is exact and
1154
+ // the confirm sees every event this person owns.
1155
+ contactId: candidate.contactId,
1156
+ journeyContext,
1157
+ },
1105
1158
  });
1106
1159
  if (!isMember) continue;
1107
1160
  }
@@ -1183,27 +1236,70 @@ function selectPresentInAllWindows(db: Database, legs: AbsenceLeg[]) {
1183
1236
  ),
1184
1237
  );
1185
1238
  return db
1186
- .select({ userId: userEvents.userId })
1239
+ .select({ contactId: userEvents.contactId })
1187
1240
  .from(userEvents)
1188
- .where(or(...perLeg))
1189
- .groupBy(userEvents.userId)
1241
+ .where(and(or(...perLeg), isNotNull(userEvents.contactId)))
1242
+ .groupBy(userEvents.contactId)
1190
1243
  .having(sql`count(distinct ${userEvents.event}) >= ${legs.length}`)
1191
1244
  .as("present_all");
1192
1245
  }
1193
1246
 
1194
- /** The merged stored properties of a contact (for property-leg evaluation). */
1247
+ /**
1248
+ * The merged stored properties of a contact (for property-leg evaluation),
1249
+ * looked up by the contact's own id.
1250
+ *
1251
+ * It used to look up `contacts.external_id = <canonical key>`, which never
1252
+ * matched an email-only or anonymous contact (their `external_id` is NULL and
1253
+ * their canonical key is the uuid / `anonymous_id`), so every property leg
1254
+ * silently evaluated against `{}` for exactly the cohort the coalesce join was
1255
+ * added to include. Both callers already hold the contact id.
1256
+ */
1195
1257
  async function loadContactProperties(
1196
1258
  db: Database,
1197
- userId: string,
1259
+ contactId: string,
1198
1260
  ): Promise<Record<string, unknown>> {
1199
1261
  const [contact] = await db
1200
1262
  .select({ properties: contacts.properties })
1201
1263
  .from(contacts)
1202
- .where(eq(contacts.externalId, userId))
1264
+ .where(eq(contacts.id, contactId))
1203
1265
  .limit(1);
1204
1266
  return (contact?.properties as Record<string, unknown> | null) ?? {};
1205
1267
  }
1206
1268
 
1269
+ /**
1270
+ * The live contact a canonical string key resolves to, or `null`. Used by the
1271
+ * fast-expiry timer, which is handed only the key on its Hatchet payload and so
1272
+ * has no contact row in scope. A READ-side lookup is admissible where the
1273
+ * emit's provenance pin is not: the pin must be unforgeable because it decides
1274
+ * which row a WRITE folds into, whereas this only decides whose history the
1275
+ * criteria re-confirm reads — and it reads the same key the task is already
1276
+ * keyed on.
1277
+ *
1278
+ * PRD 07 T7 — resolution goes through the alias-aware primitive instead of a
1279
+ * `coalesce(external_id, anonymous_id, id) = :userKey` probe: an armed timer
1280
+ * whose key was merged away between arming and waking now re-confirms against
1281
+ * the SURVIVOR's properties rather than evaluating against `{}`. Live-only on
1282
+ * both sides (`lookupContactIdByKey` filters `deleted_at IS NULL`, as the
1283
+ * coalesce probe did), so an unowned key still returns null.
1284
+ */
1285
+ async function resolveLiveContact(
1286
+ db: Database,
1287
+ userKey: string,
1288
+ ): Promise<{ id: string; properties: Record<string, unknown> } | null> {
1289
+ const contactId = await lookupContactIdByKey(db, userKey);
1290
+ if (!contactId) return null;
1291
+ const [contact] = await db
1292
+ .select({ properties: contacts.properties })
1293
+ .from(contacts)
1294
+ .where(eq(contacts.id, contactId))
1295
+ .limit(1);
1296
+ if (!contact) return null;
1297
+ return {
1298
+ id: contactId,
1299
+ properties: (contact.properties as Record<string, unknown> | null) ?? {},
1300
+ };
1301
+ }
1302
+
1207
1303
  /**
1208
1304
  * Insert ONE reconcile-discovered join (RETURNING-gated on the partial-active
1209
1305
  * unique index) and emit `bucket:entered`. entryCount = 1 + prior memberships.
@@ -1226,7 +1322,12 @@ async function reconcileJoinOne(opts: {
1226
1322
 
1227
1323
  // entryCount ordinal = 1 + ALL prior memberships (active + left). Shared with
1228
1324
  // the real-time join path so the ordinal never drifts between the two writers.
1229
- const priorCount = await countPriorMemberships(db, bucket.id, userId);
1325
+ const priorCount = await countPriorMemberships(
1326
+ db,
1327
+ bucket.id,
1328
+ userId,
1329
+ contactId ?? null,
1330
+ );
1230
1331
  const epoch = priorCount + 1;
1231
1332
 
1232
1333
  const inserted = await db
@@ -1246,6 +1347,10 @@ async function reconcileJoinOne(opts: {
1246
1347
  // this is zero new queries. `undefined` stamps NULL.
1247
1348
  contactId: contactId ?? null,
1248
1349
  })
1350
+ // PRD 05 T3 — ARBITER-LESS by design: it must absorb BOTH partial unique
1351
+ // indexes on this table (uq_user_bucket_active and the contact-scoped
1352
+ // uq_contact_bucket_active) into this one "already a member" branch. See
1353
+ // `checkBucketMembership`'s insert for the full note.
1249
1354
  .onConflictDoNothing()
1250
1355
  .returning({ id: bucketMemberships.id });
1251
1356
 
@@ -1257,7 +1362,15 @@ async function reconcileJoinOne(opts: {
1257
1362
  // epoch always advances via the real insert; only the bucket:entered emission
1258
1363
  // is gated by the entryLimit policy — mirrors the real-time join path so the
1259
1364
  // cron-discovered join cannot bypass entryLimit (Section 6.3).
1260
- if (await shouldEmitJoin({ db, bucket, userId, priorCount })) {
1365
+ if (
1366
+ await shouldEmitJoin({
1367
+ db,
1368
+ bucket,
1369
+ userId,
1370
+ contactId: contactId ?? null,
1371
+ priorCount,
1372
+ })
1373
+ ) {
1261
1374
  await emitBucketTransition({
1262
1375
  db,
1263
1376
  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
  });