@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
@@ -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)));
@@ -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)
@@ -176,6 +176,26 @@ export const impactOverviewRouter = new OpenAPIHono<AppEnv>().openapi(
176
176
  const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
177
177
  const sinceTs = sql`${since.toISOString()}::timestamptz`;
178
178
 
179
+ // WHO a journey_states row is about — `bySubject` written in SQL. The
180
+ // owning contact when the `contact_id` FK is stamped, else the mutable
181
+ // text key (a contactless enrollment is a permanent supported state: the
182
+ // engine refuses to mint a contact on observation). Either/or per row,
183
+ // never both. A bare `count(distinct js.contact_id)` would SILENTLY DROP
184
+ // every contactless enrollment, because `count(distinct …)` skips NULLs —
185
+ // and an under-counted denominator reads as "quiet journey", not as a bug.
186
+ const jsSubject = sql`coalesce(js.contact_id::text, js.user_id)`;
187
+ // The conversion cohort joins on the contact FK, not the text key.
188
+ // `conversions.contact_id` is NOT NULL, so a conversion always belongs to
189
+ // a resolved contact and this needs no text-key fallback: when
190
+ // `js.contact_id` is NULL the subject has no contact, therefore no
191
+ // conversion, and the NULL comparison correctly matches nothing. The
192
+ // uuid-to-uuid compare also uses `conversions_contact_idx`; the old
193
+ // `c.user_key = js.user_id` compare had no index at all. What it FIXES:
194
+ // the string join missed every conversion recorded under a key the person
195
+ // moved off after enrolling (anon → external), silently under-counting
196
+ // converters and inflating apparent lift.
197
+ const convBySubject = sql`c.contact_id = js.contact_id`;
198
+
179
199
  // (a) Journey base rollup — one grouped query, any-definition outcome,
180
200
  // latest-by-created_at version label. No deleted_at filter (matches the
181
201
  // /lift cohort SQL precedent).
@@ -185,20 +205,20 @@ export const impactOverviewRouter = new OpenAPIHono<AppEnv>().openapi(
185
205
  (array_agg(js.journey_version_label order by js.created_at desc)
186
206
  filter (where js.journey_version_label is not null))[1]
187
207
  as version_label,
188
- count(distinct js.user_id)
208
+ count(distinct ${jsSubject})
189
209
  filter (where js.status != 'held_out')::int as enrollments,
190
- (count(distinct js.user_id) filter (where js.status != 'held_out'
210
+ (count(distinct ${jsSubject}) filter (where js.status != 'held_out'
191
211
  and exists (
192
212
  select 1 from conversions c
193
- where c.user_key = js.user_id
213
+ where ${convBySubject}
194
214
  and c.occurred_at >= js.created_at
195
215
  )))::int as converters,
196
- count(distinct js.user_id)
216
+ count(distinct ${jsSubject})
197
217
  filter (where js.status = 'held_out')::int as control_contacts,
198
- (count(distinct js.user_id) filter (where js.status = 'held_out'
218
+ (count(distinct ${jsSubject}) filter (where js.status = 'held_out'
199
219
  and exists (
200
220
  select 1 from conversions c
201
- where c.user_key = js.user_id
221
+ where ${convBySubject}
202
222
  and c.occurred_at >= js.created_at
203
223
  )))::int as control_converters
204
224
  from journey_states js
@@ -265,17 +285,17 @@ export const impactOverviewRouter = new OpenAPIHono<AppEnv>().openapi(
265
285
  control_converters: number;
266
286
  }>(sql`
267
287
  select
268
- (count(distinct js.user_id)
288
+ (count(distinct ${jsSubject})
269
289
  filter (where js.status != 'held_out' and exists (
270
290
  select 1 from conversions c
271
- where c.user_key = js.user_id
291
+ where ${convBySubject}
272
292
  and c.occurred_at >= js.created_at
273
293
  and c.definition_id = ${goal}
274
294
  )))::int as converters,
275
- (count(distinct js.user_id)
295
+ (count(distinct ${jsSubject})
276
296
  filter (where js.status = 'held_out' and exists (
277
297
  select 1 from conversions c
278
- where c.user_key = js.user_id
298
+ where ${convBySubject}
279
299
  and c.occurred_at >= js.created_at
280
300
  and c.definition_id = ${goal}
281
301
  )))::int as control_converters
@@ -243,6 +243,15 @@ export const journeyImpactRouter = new OpenAPIHono<AppEnv>().openapi(
243
243
  ? sql` and c.definition_id = ${definitionId}`
244
244
  : sql``;
245
245
  const sinceTs = sql`${since.toISOString()}::timestamptz`;
246
+ // Same subject/cohort pair as /impact/overview — see the long rationale on
247
+ // `jsSubject`/`convBySubject` in `routes/admin/impact.ts`. In short: the
248
+ // coalesce is load-bearing (a bare `count(distinct js.contact_id)` drops
249
+ // every contactless enrollment, since `count(distinct …)` skips NULLs),
250
+ // and the cohort side needs no fallback because `conversions.contact_id`
251
+ // is NOT NULL. Both readouts MUST use the identical pair or /impact and
252
+ // /journeys/:id/impact report different enrollments for one cohort.
253
+ const jsSubject = sql`coalesce(js.contact_id::text, js.user_id)`;
254
+ const convBySubject = sql`c.contact_id = js.contact_id`;
246
255
  const versionRows = await db.execute<{
247
256
  hash: string | null;
248
257
  label: string | null;
@@ -261,20 +270,20 @@ export const journeyImpactRouter = new OpenAPIHono<AppEnv>().openapi(
261
270
  as first_enrolled_at,
262
271
  max(js.created_at) filter (where js.status != 'held_out')
263
272
  as last_enrolled_at,
264
- count(distinct js.user_id)
273
+ count(distinct ${jsSubject})
265
274
  filter (where js.status != 'held_out')::int as enrollments,
266
- (count(distinct js.user_id) filter (where js.status != 'held_out'
275
+ (count(distinct ${jsSubject}) filter (where js.status != 'held_out'
267
276
  and exists (
268
277
  select 1 from conversions c
269
- where c.user_key = js.user_id
278
+ where ${convBySubject}
270
279
  and c.occurred_at >= js.created_at${definitionSql}
271
280
  )))::int as converters,
272
- count(distinct js.user_id)
281
+ count(distinct ${jsSubject})
273
282
  filter (where js.status = 'held_out')::int as control_contacts,
274
- (count(distinct js.user_id) filter (where js.status = 'held_out'
283
+ (count(distinct ${jsSubject}) filter (where js.status = 'held_out'
275
284
  and exists (
276
285
  select 1 from conversions c
277
- where c.user_key = js.user_id
286
+ where ${convBySubject}
278
287
  and c.occurred_at >= js.created_at${definitionSql}
279
288
  )))::int as control_converters
280
289
  from journey_states js
@@ -339,10 +348,10 @@ export const journeyImpactRouter = new OpenAPIHono<AppEnv>().openapi(
339
348
  select
340
349
  v.key as variant_key,
341
350
  v.arm as arm,
342
- count(distinct js.user_id)::int as enrollments,
343
- (count(distinct js.user_id) filter (where exists (
351
+ count(distinct ${jsSubject})::int as enrollments,
352
+ (count(distinct ${jsSubject}) filter (where exists (
344
353
  select 1 from conversions c
345
- where c.user_key = js.user_id
354
+ where ${convBySubject}
346
355
  and c.occurred_at >= js.created_at${definitionSql}
347
356
  )))::int as converters
348
357
  from journey_states js