@hogsend/engine 0.58.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 (53) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +19 -10
  3. package/src/buckets/check-membership.ts +61 -8
  4. package/src/buckets/membership-epoch.ts +11 -1
  5. package/src/campaigns/cohort-sql.ts +3 -0
  6. package/src/index.ts +26 -6
  7. package/src/journeys/execute-journey-run.ts +180 -29
  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 +518 -148
  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 +23 -2
  19. package/src/lib/journey-lift.ts +17 -5
  20. package/src/lib/preferences.ts +116 -30
  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 +50 -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 +18 -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/index.ts +2 -0
  37. package/src/routes/admin/journey-impact.ts +18 -9
  38. package/src/routes/admin/journeys.ts +8 -1
  39. package/src/routes/admin/maintenance.ts +216 -0
  40. package/src/routes/admin/preferences.ts +85 -38
  41. package/src/routes/admin/reporting.ts +25 -5
  42. package/src/routes/admin/targeting.ts +1 -0
  43. package/src/routes/admin/timeline.ts +16 -10
  44. package/src/routes/email/preferences.ts +18 -1
  45. package/src/routes/lists/index.ts +11 -6
  46. package/src/worker.ts +20 -0
  47. package/src/workflows/backfill-contact-id.ts +951 -0
  48. package/src/workflows/bucket-backfill.ts +145 -59
  49. package/src/workflows/bucket-reconcile.ts +154 -50
  50. package/src/workflows/check-alerts.ts +4 -0
  51. package/src/workflows/impact-digest.ts +10 -3
  52. package/src/workflows/journey-blueprint-interpreter.ts +8 -1
  53. package/src/workflows/send-campaign.ts +18 -11
@@ -21,6 +21,7 @@ import {
21
21
  } from "../journeys/journey-boundary.js";
22
22
  import { logTransition } from "../journeys/journey-log.js";
23
23
  import { getListRegistry } from "../lists/registry-singleton.js";
24
+ import { lookupContactIdByKey } from "./contacts.js";
24
25
  import type { TestModeState } from "./domain-status.js";
25
26
  import {
26
27
  type FrequencyCapConfig,
@@ -180,6 +181,33 @@ async function sendTrackedEmailInner<K extends TemplateName>(
180
181
  }
181
182
  }
182
183
 
184
+ // PRD 04 dual-write — resolved ONCE here and reused by all three
185
+ // `email_sends` insert sites below (suppressed, test-mode-blocked, real).
186
+ //
187
+ // D7 — keyed on `options.userId` ONLY, never on `options.to`. A raw send
188
+ // (public /v1/emails, password reset, any journeyless dispatch) carries no
189
+ // userId, so its row stamps NULL. Resolving by recipient ADDRESS instead
190
+ // would make that send visible to per-contact queries that cannot see it
191
+ // today — a read-shape change smuggled in through a write.
192
+ //
193
+ // D6 — wrapped: a bookkeeping resolve may never fail the send it rides on.
194
+ // Placed AFTER the idempotency short-circuit so a deduped retry pays nothing.
195
+ let sendContactId: string | null = null;
196
+ if (options.userId) {
197
+ try {
198
+ sendContactId = await lookupContactIdByKey(db, options.userId);
199
+ } catch (err) {
200
+ (logger ?? emitLogger).warn(
201
+ "email_sends contact_id dual-write resolve failed",
202
+ {
203
+ userId: options.userId,
204
+ templateKey: String(options.templateKey),
205
+ error: err instanceof Error ? err.message : String(err),
206
+ },
207
+ );
208
+ }
209
+ }
210
+
183
211
  // Resolve the template ONCE up front so its default category is available to
184
212
  // the suppression check (a public /v1/emails send may omit `category`, in
185
213
  // which case the per-category suppression must still consult the template's
@@ -195,11 +223,11 @@ async function sendTrackedEmailInner<K extends TemplateName>(
195
223
  const subject = options.subject ?? defaultSubject;
196
224
 
197
225
  if (!options.skipPreferenceCheck) {
198
- const suppression = await checkSuppression(
199
- db,
200
- options.to,
201
- effectiveCategory,
202
- );
226
+ const suppression = await checkSuppression(db, {
227
+ email: options.to,
228
+ contactId: sendContactId,
229
+ category: effectiveCategory,
230
+ });
203
231
  if (suppression) {
204
232
  const rows = await db
205
233
  .insert(emailSends)
@@ -213,6 +241,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
213
241
  campaignId: options.campaignId,
214
242
  userId: options.userId,
215
243
  userEmail: options.userEmail ?? options.to,
244
+ contactId: sendContactId,
216
245
  // First-class "suppressed" status: a provider dispatch failure
217
246
  // releases its idempotency key (catch block below), making it
218
247
  // byte-identical to this row EXCEPT for the status — so campaign
@@ -403,6 +432,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
403
432
  campaignId: options.campaignId,
404
433
  userId: options.userId,
405
434
  userEmail: options.userEmail ?? options.to,
435
+ contactId: sendContactId,
406
436
  // Policy-gated like suppression (the provider is never reached), so it
407
437
  // shares the "suppressed" status; metadata.testMode marks the cause.
408
438
  status: "suppressed",
@@ -460,6 +490,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
460
490
  campaignId: options.campaignId,
461
491
  userId: options.userId,
462
492
  userEmail: options.userEmail ?? options.to,
493
+ contactId: sendContactId,
463
494
  status: "queued",
464
495
  idempotencyKey: options.idempotencyKey,
465
496
  ...(redirect
@@ -631,13 +662,24 @@ type SuppressionReason = EmailSuppressionError["reason"] | null;
631
662
 
632
663
  async function checkSuppression(
633
664
  db: Database,
634
- email: string,
635
- category?: string,
665
+ opts: {
666
+ email: string;
667
+ /**
668
+ * The send's resolved contact (the dual-write stamp already in hand at the
669
+ * call site). PRD 05 T6: an opt-out recorded under an earlier address or
670
+ * an earlier canonical key is reachable ONLY through the contact scope —
671
+ * the address leg alone would mail an unsubscribed person who changed
672
+ * email. Null for a journeyless/raw send (address leg only, unchanged).
673
+ */
674
+ contactId: string | null;
675
+ category?: string;
676
+ },
636
677
  ): Promise<SuppressionReason> {
678
+ const { email, contactId, category } = opts;
637
679
  // Aggregated across ALL `email_preferences` rows for this address by the shared
638
680
  // reader — an address can legitimately have MORE THAN ONE row (multi-row
639
681
  // (user_id, email) aggregation rationale lives in readRecipientPreferences).
640
- const prefs = await readRecipientPreferences(db, { email });
682
+ const prefs = await readRecipientPreferences(db, { email, contactId });
641
683
 
642
684
  if (prefs.suppressed) return "suppressed";
643
685
  if (prefs.unsubscribedAll) return "unsubscribed";
@@ -14,6 +14,14 @@ import { LINK_CLICKED } from "./tracking-event-names.js";
14
14
  interface EmailSendContext {
15
15
  userId: string;
16
16
  userEmail: string;
17
+ /**
18
+ * PRD 05 T6 — the send's owning contact (`email_sends.contact_id`, falling
19
+ * back to the enrollment's stamp). The denormalized `userId` string above is
20
+ * FROZEN at send time and goes stale when the contact adopts a new key; the
21
+ * re-ingest pins this id so tracking events land on the contact, not on
22
+ * whatever key happened to be canonical when the mail left.
23
+ */
24
+ contactId: string | null;
17
25
  templateKey: string | null;
18
26
  messageId: string | null;
19
27
  to: string;
@@ -41,9 +49,11 @@ export async function resolveEmailSendContext(
41
49
  templateKey: emailSends.templateKey,
42
50
  messageId: emailSends.messageId,
43
51
  campaignId: emailSends.campaignId,
52
+ sendContactId: emailSends.contactId,
44
53
  userId: journeyStates.userId,
45
54
  userEmail: journeyStates.userEmail,
46
55
  journeyId: journeyStates.journeyId,
56
+ enrollmentContactId: journeyStates.contactId,
47
57
  })
48
58
  .from(emailSends)
49
59
  .leftJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
@@ -56,6 +66,7 @@ export async function resolveEmailSendContext(
56
66
  return {
57
67
  userId: row.userId ?? row.toEmail,
58
68
  userEmail: row.userEmail ?? row.toEmail,
69
+ contactId: row.sendContactId ?? row.enrollmentContactId ?? null,
59
70
  templateKey: row.templateKey,
60
71
  messageId: row.messageId,
61
72
  to: row.toEmail,
@@ -68,6 +79,8 @@ export interface EmailSendContextByMessageId {
68
79
  emailSendId: string;
69
80
  userId: string;
70
81
  userEmail: string;
82
+ /** See {@link EmailSendContext.contactId}. */
83
+ contactId: string | null;
71
84
  templateKey: string | null;
72
85
  to: string;
73
86
  }
@@ -99,8 +112,10 @@ export async function resolveEmailSendContextByMessageId(
99
112
  emailSendId: emailSends.id,
100
113
  toEmail: emailSends.toEmail,
101
114
  templateKey: emailSends.templateKey,
115
+ sendContactId: emailSends.contactId,
102
116
  userId: journeyStates.userId,
103
117
  userEmail: journeyStates.userEmail,
118
+ enrollmentContactId: journeyStates.contactId,
104
119
  sendUserId: emailSends.userId,
105
120
  sendUserEmail: emailSends.userEmail,
106
121
  })
@@ -116,6 +131,7 @@ export async function resolveEmailSendContextByMessageId(
116
131
  emailSendId: row.emailSendId,
117
132
  userId: row.userId ?? row.sendUserId ?? row.toEmail,
118
133
  userEmail: row.userEmail ?? row.sendUserEmail ?? row.toEmail,
134
+ contactId: row.sendContactId ?? row.enrollmentContactId ?? null,
119
135
  templateKey: row.templateKey,
120
136
  to: row.toEmail,
121
137
  };
@@ -193,6 +209,9 @@ export async function pushTrackingEvent(
193
209
  event,
194
210
  userId: ctx.userId,
195
211
  userEmail: ctx.userEmail,
212
+ // PRD 05 T6 — pin the send's owning contact so the tracking event
213
+ // resolves to the contact even when the frozen send-time key went stale.
214
+ contactId: ctx.contactId ?? undefined,
196
215
  eventProperties: properties,
197
216
  source: "tracking",
198
217
  idempotencyKey: opts.idempotencyKey,
@@ -310,6 +329,11 @@ export interface SmsSendContext {
310
329
  */
311
330
  userId: string | null;
312
331
  userEmail: string | null;
332
+ /**
333
+ * PRD 05 T6 — the enrollment's contact stamp (`sms_sends` itself carries no
334
+ * dual-write column). Null for a journeyless send.
335
+ */
336
+ contactId: string | null;
313
337
  templateKey: string | null;
314
338
  messageId: string | null;
315
339
  to: string;
@@ -340,6 +364,7 @@ export async function resolveSmsSendContext(
340
364
  userId: journeyStates.userId,
341
365
  userEmail: journeyStates.userEmail,
342
366
  journeyId: journeyStates.journeyId,
367
+ enrollmentContactId: journeyStates.contactId,
343
368
  })
344
369
  .from(smsSends)
345
370
  .leftJoin(journeyStates, eq(smsSends.journeyStateId, journeyStates.id))
@@ -352,6 +377,7 @@ export async function resolveSmsSendContext(
352
377
  return {
353
378
  userId: row.userId ?? row.sendUserId ?? null,
354
379
  userEmail: row.userEmail ?? null,
380
+ contactId: row.enrollmentContactId ?? null,
355
381
  templateKey: row.templateKey,
356
382
  messageId: row.messageId,
357
383
  to: row.toPhone,
@@ -399,6 +425,8 @@ export async function pushSmsTrackingEvent(
399
425
  event,
400
426
  userId: ctx.userId,
401
427
  userEmail: ctx.userEmail ?? undefined,
428
+ // PRD 05 T6 — see pushTrackingEvent.
429
+ contactId: ctx.contactId ?? undefined,
402
430
  eventProperties: {
403
431
  smsSendId,
404
432
  templateKey: ctx.templateKey,
@@ -0,0 +1,44 @@
1
+ /**
2
+ * PRD 05 T3 — the shared "was this a unique_violation on THAT index?" probe.
3
+ *
4
+ * The contact-scoped uniqueness indexes are pure CONSTRAINTS: no upsert names
5
+ * them as an `ON CONFLICT` arbiter, because drizzle can only target columns and
6
+ * a bare `(contact_id, …)` arbiter would never fire for the NULL (contactless)
7
+ * population — an anonymous re-trigger would then insert a second row and die on
8
+ * the retained string index. So each writer keeps its string arbiter and
9
+ * converts THIS error into its own already-exists branch.
10
+ *
11
+ * Postgres reports the code as 23505 and names the index in `constraint_name`,
12
+ * but drizzle wraps the driver error in a `DrizzleQueryError`, so the real
13
+ * payload lives on `cause` (sometimes nested) — walk the chain, bounded. Mirrors
14
+ * `isSlugUniqueViolation` (lib/links.ts) and `isPhoneUniqueViolation`
15
+ * (lib/contacts.ts); this is the extracted, shared form.
16
+ */
17
+ export function isUniqueViolationOn(err: unknown, index: string): boolean {
18
+ for (let e = err, depth = 0; e && depth < 5; depth++) {
19
+ const candidate = e as {
20
+ code?: string;
21
+ constraint_name?: string;
22
+ constraint?: string;
23
+ message?: string;
24
+ cause?: unknown;
25
+ };
26
+ if (
27
+ candidate.code === "23505" &&
28
+ (candidate.constraint_name === index ||
29
+ candidate.constraint === index ||
30
+ (candidate.message?.includes(index) ?? false))
31
+ ) {
32
+ return true;
33
+ }
34
+ e = candidate.cause;
35
+ }
36
+ return false;
37
+ }
38
+
39
+ /** `journey_states` — one live enrollment per (contact, journey). */
40
+ export const UQ_CONTACT_JOURNEY_ACTIVE = "uq_contact_journey_active";
41
+
42
+ /** `email_preferences` — one row per (contact, email). */
43
+ export const UQ_CONTACT_EMAIL_PREFERENCES =
44
+ "email_preferences_contact_email_idx";
@@ -1,7 +1,9 @@
1
- import { bucketConfigs, bucketMemberships } from "@hogsend/db";
1
+ import { bySubject } from "@hogsend/core";
2
+ import { bucketConfigs, bucketMemberships, contacts } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import { and, count, desc, eq, inArray, isNull } from "drizzle-orm";
4
5
  import type { AppEnv } from "../../app.js";
6
+ import { contactKeySql } from "../../lib/contacts.js";
5
7
 
6
8
  const bucketSchema = z.object({
7
9
  id: z.string(),
@@ -464,7 +466,23 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
464
466
  isNull(bucketMemberships.deletedAt),
465
467
  ];
466
468
  if (userId) {
467
- conditions.push(eq(bucketMemberships.userId, userId));
469
+ // The `userId` filter is a canonical key typed by an operator, so resolve
470
+ // it to the contact it names and scope by SUBJECT. A raw
471
+ // `user_id = :userId` filter hides every row this person accumulated
472
+ // under an earlier key — the exact history Studio is being asked to show.
473
+ // No live contact for the key → fall back to the string arm, which is
474
+ // also the right answer for a contactless (anonymous) subject.
475
+ const [owner] = await db
476
+ .select({ id: contacts.id })
477
+ .from(contacts)
478
+ .where(and(eq(contactKeySql(), userId), isNull(contacts.deletedAt)))
479
+ .limit(1);
480
+ conditions.push(
481
+ bySubject(bucketMemberships, {
482
+ contactId: owner?.id ?? null,
483
+ userKey: userId,
484
+ }),
485
+ );
468
486
  }
469
487
 
470
488
  const where = and(...conditions);
@@ -1,8 +1,12 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { contacts, emailSends, importJobs, userEvents } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import { and, desc, eq, gte, inArray, isNull, lte } from "drizzle-orm";
4
5
  import type { AppEnv } from "../../app.js";
5
- import { contactSearchFilter } from "../../lib/contacts.js";
6
+ import {
7
+ contactSearchFilter,
8
+ lookupContactIdByKey,
9
+ } from "../../lib/contacts.js";
6
10
  import { ingestEvent } from "../../lib/ingestion.js";
7
11
  import { errorSchema } from "../../lib/schemas.js";
8
12
  import { importContactsTask } from "../../workflows/import-contacts.js";
@@ -388,8 +392,16 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
388
392
  if (body.filter?.event) {
389
393
  conditions.push(eq(userEvents.event, body.filter.event));
390
394
  }
395
+ // Replay by subject, not by string: resolve the supplied key to its
396
+ // owning contact so a replay covers the events that person emitted
397
+ // under keys they have since moved off. No contact for the key → the
398
+ // literal string match, as before.
391
399
  if (body.filter?.userId) {
392
- conditions.push(eq(userEvents.userId, body.filter.userId));
400
+ const filterKey = body.filter.userId;
401
+ const contactId = await lookupContactIdByKey(db, filterKey);
402
+ conditions.push(
403
+ bySubject(userEvents, { contactId, userKey: filterKey }),
404
+ );
393
405
  }
394
406
  if (body.filter?.from) {
395
407
  conditions.push(gte(userEvents.occurredAt, new Date(body.filter.from)));
@@ -488,6 +500,10 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
488
500
  toEmail: email.toEmail,
489
501
  subject: email.subject,
490
502
  category: email.category,
503
+ // PRD 04 dual-write: copied verbatim off the source row (the full row
504
+ // is already selected above) — zero queries, and a resend of a send
505
+ // that stamped NULL correctly stays NULL rather than resolving anew.
506
+ contactId: email.contactId,
491
507
  status: "queued",
492
508
  })
493
509
  .returning();
@@ -453,19 +453,20 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
453
453
  return c.json({ error: "Contact not found" }, 404);
454
454
  }
455
455
 
456
- // email_preferences.user_id uses external_id when present, else the contact
457
- // uuid as the deterministic fallback (risk 10 — email-only contacts).
456
+ // PRD 05 T6 — preference rows are read by ownership stamp; the old
457
+ // `external_id ?? id` string derivation goes stale on adoption.
458
458
  const [prefRows, revenue, groupRows] = await Promise.all([
459
459
  db
460
460
  .select()
461
461
  .from(emailPreferences)
462
- .where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
462
+ .where(eq(emailPreferences.contactId, contact.id))
463
463
  .limit(1),
464
464
  // Valued events are keyed by the contact's canonical event key — the
465
465
  // same precedence ingestEvent resolves (`external ?? anon ?? id`).
466
466
  getContactRevenue({
467
467
  db,
468
468
  key: contact.externalId ?? contact.anonymousId ?? contact.id,
469
+ contactId: contact.id,
469
470
  }),
470
471
  // The contact's live group memberships (mirrors the admin groups router's
471
472
  // join idiom): `group_memberships` → `groups`, live groups only, ordered
@@ -313,19 +313,35 @@ export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
313
313
  // Per subject: the anchor instant + its subject key. A journey subject is
314
314
  // one enrollment row (created_at); an event subject is a contact's FIRST
315
315
  // occurrence of the named event in the window.
316
+ //
317
+ // `subject_key` is the owning contact when the `contact_id` FK is stamped,
318
+ // else the mutable text key — `bySubject` written in SQL. Two things the
319
+ // coalesce is protecting, both of which fail SILENTLY:
320
+ // (1) the event leg GROUPS BY this expression, so a bare `contact_id`
321
+ // would collapse every contactless (anonymous) event into ONE group
322
+ // and crush the `anchored` denominator to a single subject;
323
+ // (2) the journey leg would drop nothing but would lose the row's
324
+ // identity entirely for contactless enrollments.
325
+ // The correlated conversion probe below joins `c.contact_id::text` to it:
326
+ // `conversions.contact_id` is NOT NULL, so a text-keyed (contactless)
327
+ // subject correctly matches no conversion — it has no contact, therefore
328
+ // no conversion can belong to it — while still being COUNTED in the
329
+ // denominator, which is what makes the rate honest.
316
330
  const subjects =
317
331
  anchorType === "journey"
318
332
  ? sql`
319
- select js.created_at as anchor_at, js.user_id as subject_key
333
+ select js.created_at as anchor_at,
334
+ coalesce(js.contact_id::text, js.user_id) as subject_key
320
335
  from journey_states js
321
336
  where js.journey_id = ${anchorId}
322
337
  and js.created_at >= ${since}::timestamptz`
323
338
  : sql`
324
- select min(ue.occurred_at) as anchor_at, ue.user_id as subject_key
339
+ select min(ue.occurred_at) as anchor_at,
340
+ coalesce(ue.contact_id::text, ue.user_id) as subject_key
325
341
  from user_events ue
326
342
  where ue.event = ${anchorId}
327
343
  and ue.occurred_at >= ${since}::timestamptz
328
- group by ue.user_id`;
344
+ group by coalesce(ue.contact_id::text, ue.user_id)`;
329
345
 
330
346
  // For each subject, the first conversion of this definition at/after the
331
347
  // anchor (correlated scalar). Latency = first_conv - anchor_at.
@@ -348,7 +364,7 @@ export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
348
364
  (
349
365
  select min(c.occurred_at)
350
366
  from conversions c
351
- where c.user_key = subj.subject_key
367
+ where c.contact_id::text = subj.subject_key
352
368
  and c.definition_id = ${definitionId}
353
369
  and c.occurred_at >= subj.anchor_at
354
370
  ) as first_conv
@@ -1,3 +1,4 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import {
2
3
  type Database,
3
4
  emailSends,
@@ -21,6 +22,7 @@ import {
21
22
  or,
22
23
  } from "drizzle-orm";
23
24
  import type { AppEnv } from "../../app.js";
25
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
24
26
 
25
27
  const emailSchema = z.object({
26
28
  id: z.string(),
@@ -282,10 +284,17 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
282
284
  conditions.push(eq(emailSends.campaignId, campaignId));
283
285
  }
284
286
  // Match the denormalized identity OR the journey-state join, so journeyless
285
- // sends (which only carry the denormalized userId) are still filterable.
287
+ // sends (which only carry the denormalized identity) are still filterable.
288
+ // Both legs go through `bySubject` off ONE resolved contact: the operator
289
+ // typed a text key, and the person's sends may be split across the keys
290
+ // they held over time. The `or` here is across two TABLES (send row vs.
291
+ // its enrollment), not two arms of one subject — `bySubject` still picks
292
+ // exactly one predicate per table.
286
293
  if (userId) {
294
+ const contactId = await lookupContactIdByKey(db, userId);
295
+ const subject = { contactId, userKey: userId };
287
296
  conditions.push(
288
- or(eq(emailSends.userId, userId), eq(journeyStates.userId, userId)),
297
+ or(bySubject(emailSends, subject), bySubject(journeyStates, subject)),
289
298
  );
290
299
  }
291
300
  if (engagement) conditions.push(isNotNull(engagementColumn[engagement]));
@@ -305,6 +314,10 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
305
314
  const [rows, totalRows] = await Promise.all([
306
315
  db
307
316
  .select({
317
+ // Display echo of the text key this send was stamped under, NOT a
318
+ // scoping predicate — the response's `userId` field is a string by
319
+ // contract. Deliberately left on `user_id`; PRD 05 flips scoping
320
+ // reads, not the wire format.
308
321
  ...getTableColumns(emailSends),
309
322
  identityUserId: journeyStates.userId,
310
323
  identityJourneyId: journeyStates.journeyId,
@@ -360,6 +373,8 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
360
373
  ? db
361
374
  .select({
362
375
  journeyId: journeyStates.journeyId,
376
+ // Display echo of the stamped text key (see the list route) —
377
+ // `journeyContext.userId` is a string by contract.
363
378
  userId: journeyStates.userId,
364
379
  status: journeyStates.status,
365
380
  currentNodeId: journeyStates.currentNodeId,
@@ -1,3 +1,4 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { contacts, userEvents } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import {
@@ -11,11 +12,9 @@ import {
11
12
  lte,
12
13
  max,
13
14
  min,
14
- or,
15
- sql,
16
15
  } from "drizzle-orm";
17
16
  import type { AppEnv } from "../../app.js";
18
- import type { HogsendClient } from "../../container.js";
17
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
19
18
  import {
20
19
  eventNameEntrySchema,
21
20
  listEventNameVocabulary,
@@ -30,8 +29,8 @@ const eventSchema = z.object({
30
29
  occurredAt: z.string(),
31
30
  // Where the event entered the pipeline ("posthog", "api", "studio", …).
32
31
  source: z.string().nullable(),
33
- // Resolved from THE live contact whose key (externalId, anonymousId, or
34
- // id) matches user_events.userId — shows WHO an event is from.
32
+ // Resolved from the event's owning contact (`user_events.contact_id`) when
33
+ // that contact is still live — shows WHO an event is from.
35
34
  userEmail: z.string().nullable(),
36
35
  contactId: z.string().nullable(),
37
36
  });
@@ -59,36 +58,21 @@ function serializeEvent(row: JoinedEvent) {
59
58
  }
60
59
 
61
60
  /**
62
- * LATERAL pick of THE live contact for an event's userId. `userEvents.userId`
63
- * holds the resolved canonical key (`external_id ?? anonymous_id ?? id`), so
64
- * match all three — covering email-only/anonymous contacts, not just
65
- * externalId-keyed ones. Each column is partial-unique among live rows, but
66
- * the three namespaces are NOT guaranteed disjoint across contacts: a
67
- * mis-keyed emitter can park one contact's key in another contact's
68
- * anonymous_id, and a bare OR-join then matches BOTH — fanning every event
69
- * out into one display row per matching contact. The lateral picks exactly
70
- * one, by the same precedence ingest resolves keys with.
61
+ * The event's owning contact, named directly by the `contact_id` FK.
62
+ *
63
+ * This replaces a LATERAL that re-derived the owner by matching
64
+ * `user_events.user_id` against all three key columns (external_id,
65
+ * anonymous_id, id::text) under a priority `case`, because the three
66
+ * namespaces are not guaranteed disjoint and a bare OR-join fanned one event
67
+ * into a display row per matching contact. The FK carries the answer, so the
68
+ * three-way guess is gone. `deleted_at IS NULL` stays inside the join
69
+ * condition: a soft-deleted owner must yield NO contact rather than a
70
+ * tombstone.
71
71
  */
72
- function liveContactFor(db: HogsendClient["db"]) {
73
- return db
74
- .select({ id: contacts.id, email: contacts.email })
75
- .from(contacts)
76
- .where(
77
- and(
78
- or(
79
- eq(contacts.externalId, userEvents.userId),
80
- eq(contacts.anonymousId, userEvents.userId),
81
- eq(sql`${contacts.id}::text`, userEvents.userId),
82
- ),
83
- isNull(contacts.deletedAt),
84
- ),
85
- )
86
- .orderBy(
87
- sql`case when ${contacts.externalId} = ${userEvents.userId} then 0 when ${contacts.anonymousId} = ${userEvents.userId} then 1 else 2 end`,
88
- )
89
- .limit(1)
90
- .as("live_contact");
91
- }
72
+ const liveContactJoin = and(
73
+ eq(contacts.id, userEvents.contactId),
74
+ isNull(contacts.deletedAt),
75
+ );
92
76
 
93
77
  const listRoute = createRoute({
94
78
  method: "get",
@@ -308,7 +292,16 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
308
292
  c.req.valid("query");
309
293
 
310
294
  const conditions = [];
311
- if (userId) conditions.push(eq(userEvents.userId, userId));
295
+ // The `userId` filter is a text key an operator typed (or clicked through
296
+ // from a contact row). Resolve it to the owning contact first so the
297
+ // filter returns that person's WHOLE history — including events stamped
298
+ // under a key they have since moved off (anon → external). On a key no
299
+ // contact owns, `bySubject` falls back to the literal string match, which
300
+ // is the pre-flip behaviour.
301
+ if (userId) {
302
+ const contactId = await lookupContactIdByKey(db, userId);
303
+ conditions.push(bySubject(userEvents, { contactId, userKey: userId }));
304
+ }
312
305
  if (event) conditions.push(eq(userEvents.event, event));
313
306
  if (source) conditions.push(eq(userEvents.source, source));
314
307
  if (from) conditions.push(gte(userEvents.occurredAt, new Date(from)));
@@ -316,15 +309,14 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
316
309
 
317
310
  const where = conditions.length > 0 ? and(...conditions) : undefined;
318
311
 
319
- const liveContact = liveContactFor(db);
320
312
  const [rows, totalRows] = await Promise.all([
321
313
  db
322
314
  .select({
323
315
  event: userEvents,
324
- contact: { id: liveContact.id, email: liveContact.email },
316
+ contact: { id: contacts.id, email: contacts.email },
325
317
  })
326
318
  .from(userEvents)
327
- .leftJoinLateral(liveContact, sql`true`)
319
+ .leftJoin(contacts, liveContactJoin)
328
320
  .where(where)
329
321
  .orderBy(desc(userEvents.occurredAt))
330
322
  .limit(limit)
@@ -423,14 +415,13 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
423
415
  const { db } = c.get("container");
424
416
  const { id } = c.req.valid("param");
425
417
 
426
- const liveContact = liveContactFor(db);
427
418
  const rows = await db
428
419
  .select({
429
420
  event: userEvents,
430
- contact: { id: liveContact.id, email: liveContact.email },
421
+ contact: { id: contacts.id, email: contacts.email },
431
422
  })
432
423
  .from(userEvents)
433
- .leftJoinLateral(liveContact, sql`true`)
424
+ .leftJoin(contacts, liveContactJoin)
434
425
  .where(eq(userEvents.id, id))
435
426
  .limit(1);
436
427
 
@@ -140,10 +140,15 @@ export const adminFunnelsRouter = new OpenAPIHono<AppEnv>().openapi(
140
140
  );
141
141
  // Exposure: ≥1 stamped touchpoint BEFORE the outcome instant (the next
142
142
  // stage's reach, or now for non-converters) — association framing.
143
+ // The exposure probe joins the contact FK, not the text key.
144
+ // `funnel_progress.contact_id` is NOT NULL, so there is always a contact
145
+ // to join to and no text fallback is needed — and the events a person
146
+ // emitted before they registered (stamped under an anonymous key) now
147
+ // count as exposure, which the `user_key` string compare missed.
143
148
  const exposed = scopeKey
144
149
  ? sql`exists (
145
150
  select 1 from user_events ue
146
- where ue.user_id = ${funnelProgress.userKey}
151
+ where ue.contact_id = ${funnelProgress.contactId}
147
152
  and ue.event in (${touchEventList})
148
153
  and ue.properties->>${sql.raw(`'${scopeKey}'`)} = ${scopeValue}
149
154
  and ue.occurred_at <= coalesce(${next.reachedAt}, now())
@@ -865,6 +865,10 @@ export const groupsRouter = new OpenAPIHono<AppEnv>()
865
865
  id: userEvents.id,
866
866
  event: userEvents.event,
867
867
  occurredAt: userEvents.occurredAt,
868
+ // Display echo of the key the event was stamped under — not a
869
+ // scoping predicate. The rows are already scoped by the group's
870
+ // jsonb association (`taggedEvents`), and the response field is a
871
+ // string by contract.
868
872
  userId: userEvents.userId,
869
873
  })
870
874
  .from(userEvents)