@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
@@ -1,6 +1,6 @@
1
1
  import type { Conditions } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
3
- import { type DurationObject, durationToMs } from "@hogsend/core";
3
+ import { bySubject, type DurationObject, durationToMs } from "@hogsend/core";
4
4
  import type {
5
5
  JourneyMeta,
6
6
  JourneyRunFn,
@@ -15,7 +15,7 @@ import {
15
15
  import { and, eq, inArray, isNull, notInArray, or, sql } from "drizzle-orm";
16
16
  import { getAnalytics } from "../lib/analytics-singleton.js";
17
17
  import { blueprintGraphLock } from "../lib/blueprint-lock.js";
18
- import { ALL_IDENTITY_KINDS } from "../lib/contacts.js";
18
+ import { ALL_IDENTITY_KINDS, lookupContactIdByKey } from "../lib/contacts.js";
19
19
  import { getDb } from "../lib/db.js";
20
20
  import {
21
21
  checkEmailPreferences,
@@ -28,6 +28,10 @@ import { ingestEvent } from "../lib/ingestion.js";
28
28
  import { createLogger } from "../lib/logger.js";
29
29
  import { emitOutbound } from "../lib/outbound.js";
30
30
  import { resolveTimezoneWithSource } from "../lib/timezone.js";
31
+ import {
32
+ isUniqueViolationOn,
33
+ UQ_CONTACT_JOURNEY_ACTIVE,
34
+ } from "../lib/unique-violation.js";
31
35
  import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
32
36
  import { JourneyExitedError } from "./errors.js";
33
37
  import {
@@ -102,6 +106,55 @@ export interface JourneyDurableCtx {
102
106
  /** The `journey_states` row an enrollment insert returns. */
103
107
  export type JourneyStateRow = typeof journeyStates.$inferSelect;
104
108
 
109
+ /**
110
+ * PRD 04 dual-write resolve for the two `journey_states` insert sites (the
111
+ * enrollment row and the held_out row).
112
+ *
113
+ * D6 — a bookkeeping resolve may NEVER fail the operation it rides on: every
114
+ * failure degrades to NULL plus a warn, because a missing `contact_id` is a
115
+ * NULL a backfill fills later while a throwing enrollment is an outage.
116
+ *
117
+ * The pushed `input.contactId` is preferred — `ingestEvent` already resolved the
118
+ * subject before routing the event here — but it is VALIDATED, not trusted. The
119
+ * pin was computed at INGEST time and then crossed an unbounded Hatchet queue
120
+ * delay; a contact MERGE inside that window soft-deletes the pinned loser and
121
+ * re-aliases its key onto the survivor. Stamping the pin blindly would write a
122
+ * TOMBSTONE id, and that stamp is PERMANENT: the backfill only fills NULLs (it
123
+ * is not a repair tool) and T3's merge re-point ran before this row existed.
124
+ * Worse, the pin-ABSENT path would have got it right — `lookupContactIdByKey`'s
125
+ * alias probe refuses soft-deleted targets and follows the key to the survivor.
126
+ *
127
+ * So: ONE indexed live-PK probe on the pin, and on a miss FALL THROUGH to the
128
+ * ordinary key probe (survivor, or null). Any failure degrades to NULL per D6.
129
+ */
130
+ async function resolveEnrollmentContactId(opts: {
131
+ db: Database;
132
+ userId: string;
133
+ journeyId: string;
134
+ pushed?: string;
135
+ }): Promise<string | null> {
136
+ try {
137
+ if (opts.pushed) {
138
+ const live = await opts.db
139
+ .select({ id: contacts.id })
140
+ .from(contacts)
141
+ .where(and(eq(contacts.id, opts.pushed), isNull(contacts.deletedAt)))
142
+ .limit(1);
143
+ if (live[0]) return live[0].id;
144
+ // Pin went stale between ingest and execution (merged away, or hard
145
+ // deleted). Fall through rather than stamping the tombstone.
146
+ }
147
+ return await lookupContactIdByKey(opts.db, opts.userId);
148
+ } catch (err) {
149
+ logger.warn("journey_states contact_id dual-write resolve failed", {
150
+ journeyId: opts.journeyId,
151
+ userId: opts.userId,
152
+ error: err instanceof Error ? err.message : String(err),
153
+ });
154
+ return null;
155
+ }
156
+ }
157
+
105
158
  /**
106
159
  * Insert the enrollment row, tolerating the partial-unique-index race.
107
160
  *
@@ -122,6 +175,17 @@ export type JourneyStateRow = typeof journeyStates.$inferSelect;
122
175
  * CONFLICT specification") at runtime. The `where` reproduces the index
123
176
  * predicate (`status IN ('active','waiting')`) EXACTLY — see
124
177
  * journey-states.ts:uq_user_journey_active.
178
+ *
179
+ * PRD 05 T3 — the arbiter deliberately STAYS on the string key. The second live
180
+ * index, `uq_contact_journey_active`, cannot be an arbiter here: drizzle's
181
+ * `target` accepts columns only (no expression), and a bare
182
+ * `(contact_id, journey_id)` target would never fire for a NULL `contact_id` —
183
+ * i.e. for every anonymous visitor, a permanent supported state — so an
184
+ * anonymous re-trigger of a live journey would insert a second row and die on
185
+ * the string index. Instead its 23505 is caught below and mapped to the SAME
186
+ * zero-rows outcome, which the caller reads as `already_active`. That is the
187
+ * correct answer: the contact IS already live in this journey, under a different
188
+ * string key that adoption has since folded onto the same contact.
125
189
  */
126
190
  export async function insertEnrollment(opts: {
127
191
  db: Database;
@@ -148,6 +212,15 @@ export async function insertEnrollment(opts: {
148
212
  */
149
213
  journeyVersionHash?: string | null;
150
214
  journeyVersionLabel?: string | null;
215
+ /**
216
+ * PRD 04 dual-write: the `contacts.id` owning `userId`, stamped alongside the
217
+ * canonical string key. OPTIONAL and defaulting to NULL — this is public API
218
+ * (index.ts) and bookkeeping, so a caller that omits it (dogfood tests, any
219
+ * pre-PRD-04 consumer) behaves exactly as before. The RESOLVE lives in the
220
+ * caller, never here: `executeJourneyRun` already holds the pushed
221
+ * `input.contactId` and only pays for a lookup when it doesn't.
222
+ */
223
+ contactId?: string | null;
151
224
  }): Promise<JourneyStateRow | undefined> {
152
225
  const values = {
153
226
  userId: opts.userId,
@@ -159,30 +232,46 @@ export async function insertEnrollment(opts: {
159
232
  hatchetRunId: opts.hatchetRunId,
160
233
  journeyVersionHash: opts.journeyVersionHash ?? null,
161
234
  journeyVersionLabel: opts.journeyVersionLabel ?? null,
235
+ contactId: opts.contactId ?? null,
162
236
  };
163
237
  const onConflict = {
164
238
  target: [journeyStates.userId, journeyStates.journeyId],
165
239
  where: sql`status IN ('active', 'waiting')`,
166
240
  };
167
241
 
168
- if (!opts.serializeWithGraphLock) {
169
- const [row] = await opts.db
170
- .insert(journeyStates)
171
- .values(values)
172
- .onConflictDoNothing(onConflict)
173
- .returning();
174
- return row;
175
- }
242
+ try {
243
+ if (!opts.serializeWithGraphLock) {
244
+ const [row] = await opts.db
245
+ .insert(journeyStates)
246
+ .values(values)
247
+ .onConflictDoNothing(onConflict)
248
+ .returning();
249
+ return row;
250
+ }
176
251
 
177
- return opts.db.transaction(async (tx) => {
178
- await tx.execute(blueprintGraphLock(opts.journeyId));
179
- const [row] = await tx
180
- .insert(journeyStates)
181
- .values(values)
182
- .onConflictDoNothing(onConflict)
183
- .returning();
184
- return row;
185
- });
252
+ // `await` (not a bare return) so a 23505 raised inside the transaction is
253
+ // caught HERE, after the transaction has already rolled back.
254
+ return await opts.db.transaction(async (tx) => {
255
+ await tx.execute(blueprintGraphLock(opts.journeyId));
256
+ const [row] = await tx
257
+ .insert(journeyStates)
258
+ .values(values)
259
+ .onConflictDoNothing(onConflict)
260
+ .returning();
261
+ return row;
262
+ });
263
+ } catch (err) {
264
+ if (!isUniqueViolationOn(err, UQ_CONTACT_JOURNEY_ACTIVE)) throw err;
265
+ // Same contact, DIFFERENT string key, already live in this journey. Zero
266
+ // rows is exactly what the string arbiter returns for the same situation,
267
+ // and the caller maps it to the `already_active` skip.
268
+ logger.info("journey enrollment skipped — contact already live", {
269
+ journeyId: opts.journeyId,
270
+ userId: opts.userId,
271
+ contactId: opts.contactId ?? null,
272
+ });
273
+ return undefined;
274
+ }
186
275
  }
187
276
 
188
277
  export interface ExecuteJourneyRunOptions {
@@ -276,6 +365,26 @@ export async function executeJourneyRun(
276
365
 
277
366
  let state = recovered;
278
367
 
368
+ // The subject this run's ENTRY reads and writes history for, resolved AT MOST
369
+ // ONCE. PRD 05 T4 moved the entry guards off the mutable `user_id` string and
370
+ // onto `bySubject`, so the guards now need the same value the enrollment
371
+ // insert already stamped — memoizing it keeps that at one resolve per run
372
+ // rather than one per reader (`undefined` = not yet resolved; `null` = a
373
+ // resolved-to-nothing subject, which is a permanent supported state and must
374
+ // not re-probe).
375
+ let resolvedContactId: string | null | undefined;
376
+ const enrollmentContactId = async (): Promise<string | null> => {
377
+ if (resolvedContactId === undefined) {
378
+ resolvedContactId = await resolveEnrollmentContactId({
379
+ db,
380
+ userId,
381
+ journeyId: meta.id,
382
+ pushed: input.contactId,
383
+ });
384
+ }
385
+ return resolvedContactId;
386
+ };
387
+
279
388
  // FIRST ENTRY ONLY — the enrollment guards gate ENTRY, not resume. A
280
389
  // recovered enrollment already passed them on first entry, so it skips
281
390
  // straight to resuming the run. (Sends inside `run` still re-check
@@ -305,6 +414,7 @@ export async function executeJourneyRun(
305
414
  db,
306
415
  journey: meta,
307
416
  userId,
417
+ contactId: await enrollmentContactId(),
308
418
  });
309
419
  const entryPolicy = evaluateEnrollmentPolicy({
310
420
  journey: meta,
@@ -315,7 +425,11 @@ export async function executeJourneyRun(
315
425
  return { status: "skipped", reason: entryPolicy.reason };
316
426
  }
317
427
 
318
- const prefs = await checkEmailPreferences({ db, userId });
428
+ const prefs = await checkEmailPreferences({
429
+ db,
430
+ userId,
431
+ contactId: await enrollmentContactId(),
432
+ });
319
433
  const preferencePolicy = evaluateEnrollmentPolicy({
320
434
  journey: meta,
321
435
  properties,
@@ -348,13 +462,23 @@ export async function executeJourneyRun(
348
462
  if (!holdoutPolicy.allowed) {
349
463
  const priorHoldout = await db.query.journeyStates.findFirst({
350
464
  where: and(
351
- eq(journeyStates.userId, userId),
465
+ bySubject(journeyStates, {
466
+ contactId: await enrollmentContactId(),
467
+ userKey: userId,
468
+ }),
352
469
  eq(journeyStates.journeyId, meta.id),
353
470
  eq(journeyStates.status, "held_out"),
354
471
  ),
355
472
  });
356
473
  if (!priorHoldout) {
357
474
  const heldOutAt = new Date();
475
+ // PRD 04 dual-write, via the run-scoped memo the guard above already
476
+ // paid for (identical arguments, so identical value). Deliberately
477
+ // NOT the `subjectContactId` compute below: that one lives INSIDE the
478
+ // ingest try/catch, and hoisting it would change which failures skip
479
+ // the `journey.heldout` re-emit — a control-flow change to the
480
+ // identity-provenance path, made for bookkeeping.
481
+ const heldOutContactId = await enrollmentContactId();
358
482
  const inserted = await db
359
483
  .insert(journeyStates)
360
484
  .values({
@@ -363,6 +487,7 @@ export async function executeJourneyRun(
363
487
  journeyId: meta.id,
364
488
  currentNodeId: "held-out",
365
489
  status: "held_out",
490
+ contactId: heldOutContactId,
366
491
  // Reserved record-once namespaces are STRIPPED from event
367
492
  // properties before seeding (injection fix): a publishable-key
368
493
  // event must never pre-fill __once__/__digest__/__throttle__/
@@ -487,7 +612,10 @@ export async function executeJourneyRun(
487
612
 
488
613
  const activeState = await db.query.journeyStates.findFirst({
489
614
  where: and(
490
- eq(journeyStates.userId, userId),
615
+ bySubject(journeyStates, {
616
+ contactId: await enrollmentContactId(),
617
+ userKey: userId,
618
+ }),
491
619
  eq(journeyStates.journeyId, meta.id),
492
620
  inArray(journeyStates.status, ["active", "waiting"]),
493
621
  ),
@@ -501,6 +629,21 @@ export async function executeJourneyRun(
501
629
  return { status: "skipped", reason: activePolicy.reason };
502
630
  }
503
631
 
632
+ // PRD 04 dual-write — the pushed pin when ingest resolved one, else one
633
+ // D6-wrapped probe. NULL (unknown subject / refused resolve) is a legal
634
+ // stamp: the enrollment proceeds exactly as before. Resolved FRESH here
635
+ // (not via the guard-time memo): the guard chain is long enough for a
636
+ // concurrent identify to mint the subject's contact mid-window, and a
637
+ // stale NULL stamp on the insert would sit outside the contact-scoped
638
+ // unique index that backstops double-enrollment. The memo cache is
639
+ // refreshed with the result so later readers agree with the stamp.
640
+ resolvedContactId = await resolveEnrollmentContactId({
641
+ db,
642
+ userId,
643
+ journeyId: meta.id,
644
+ pushed: input.contactId,
645
+ });
646
+
504
647
  // A successful insert always returns exactly one row, so undefined here
505
648
  // can ONLY mean a burst-race conflict (see insertEnrollment's doc for
506
649
  // the race + arbiter mechanics) — the same outcome as the read guard,
@@ -519,6 +662,7 @@ export async function executeJourneyRun(
519
662
  hatchetRunId: workflowRunId,
520
663
  journeyVersionHash: meta.versionHash ?? null,
521
664
  journeyVersionLabel: meta.version ?? null,
665
+ contactId: resolvedContactId,
522
666
  serializeWithGraphLock: options.serializeEnrollment,
523
667
  });
524
668
  if (!state) {
@@ -552,6 +696,9 @@ export async function executeJourneyRun(
552
696
  stateId,
553
697
  journeyId: meta.id,
554
698
  journeyName: meta.name,
699
+ // The enrollment row's OWN stamp — replay-stable (a recovered run reads
700
+ // back what first entry wrote) and NULL for a contactless subject.
701
+ contactId: state.contactId,
555
702
  };
556
703
 
557
704
  // The injected analytics instance (set by createHogsendClient). Same
@@ -626,14 +773,18 @@ export async function executeJourneyRun(
626
773
  journeyId: meta.id,
627
774
  entryLimit: meta.entryLimit,
628
775
  ...(meta.entryPeriod ? { entryPeriod: meta.entryPeriod } : {}),
629
- // Group-scope resolution inputs: the trigger event's association map
630
- // (rides the task input, replay-stable) and the subject contact id —
631
- // the pushed contactId when present, else the contact row already
632
- // fetched for timezone above (best-effort: undefined only defers the
633
- // resolver's no-contact throw to the membership leg).
776
+ // The subject contact id — feeds BOTH the group-scope resolver and (PRD
777
+ // 05 T4) every bySubject history read on the context. `state.contactId`
778
+ // FIRST: it is the enrollment row's own stamp, validated by
779
+ // `resolveEnrollmentContactId` (a merged-away tombstone pin is rejected
780
+ // and re-resolved to the survivor) and replay-stable, where the raw
781
+ // pushed pin can be stale by the queue delay and the `contact` row here
782
+ // is an externalId-only best-effort fetch that misses anon-keyed
783
+ // contacts. The pin/row legs remain only as fallbacks for a NULL stamp
784
+ // (a pre-column-era recovered enrollment the sweep has not reached).
634
785
  ...(input.groups ? { triggerGroups: input.groups } : {}),
635
- ...((input.contactId ?? contact?.id)
636
- ? { contactId: input.contactId ?? contact?.id }
786
+ ...((state.contactId ?? input.contactId ?? contact?.id)
787
+ ? { contactId: state.contactId ?? input.contactId ?? contact?.id }
637
788
  : {}),
638
789
  });
639
790
 
@@ -9,6 +9,7 @@ import {
9
9
  } from "@hatchet-dev/typescript-sdk/v1/index.js";
10
10
  import type { DurationObject } from "@hogsend/core";
11
11
  import {
12
+ bySubject,
12
13
  durationToMs,
13
14
  evaluateEventCondition,
14
15
  evaluatePropertyConditions,
@@ -229,6 +230,15 @@ export function createJourneyContext(
229
230
  defaultSendWindow,
230
231
  } = config;
231
232
 
233
+ // PRD 05 T4 — the subject a history read is about. The run's resolved
234
+ // `contactId` applies ONLY to the ENROLLED user: `ctx.history.*` takes an
235
+ // arbitrary `userId` from author code, and scoping someone else's key to THIS
236
+ // run's contact would read the wrong person. A key that is not the enrolled
237
+ // one has no contact in hand, so it keeps `bySubject`'s text-key arm — which
238
+ // is exactly today's behavior for it.
239
+ const subjectFor = (targetUserId: string): string | null =>
240
+ targetUserId === userId ? (config.contactId ?? null) : null;
241
+
232
242
  // Replay-stable clock: the real DurableContext.now() is memoized across
233
243
  // replays; a pre-eviction engine (or a test ctx without it) falls back to the
234
244
  // live clock. Only RECOMPUTED instants depend on this — never the DB-key
@@ -477,7 +487,10 @@ export function createJourneyContext(
477
487
  // association map; user scope keeps the enrolled-user predicate.
478
488
  groupScope
479
489
  ? sql`${userEvents.groups} ->> ${groupScope.type} = ${groupScope.key}`
480
- : eq(userEvents.userId, userId),
490
+ : bySubject(userEvents, {
491
+ contactId: config.contactId,
492
+ userKey: userId,
493
+ }),
481
494
  eq(userEvents.event, event),
482
495
  gte(userEvents.occurredAt, scanSince),
483
496
  ...eqPreds,
@@ -676,7 +689,10 @@ export function createJourneyContext(
676
689
  .from(userEvents)
677
690
  .where(
678
691
  and(
679
- eq(userEvents.userId, userId),
692
+ bySubject(userEvents, {
693
+ contactId: config.contactId,
694
+ userKey: userId,
695
+ }),
680
696
  eq(userEvents.event, event),
681
697
  gte(userEvents.occurredAt, since),
682
698
  ),
@@ -815,7 +831,10 @@ export function createJourneyContext(
815
831
  .from(userEvents)
816
832
  .where(
817
833
  and(
818
- eq(userEvents.userId, userId),
834
+ bySubject(userEvents, {
835
+ contactId: config.contactId,
836
+ userKey: userId,
837
+ }),
819
838
  eq(userEvents.event, event),
820
839
  gte(userEvents.occurredAt, scanSince),
821
840
  lte(userEvents.occurredAt, flushInstant),
@@ -1416,7 +1435,11 @@ export function createJourneyContext(
1416
1435
 
1417
1436
  guard: {
1418
1437
  async isSubscribed() {
1419
- const prefs = await checkEmailPreferences({ db, userId });
1438
+ const prefs = await checkEmailPreferences({
1439
+ db,
1440
+ userId,
1441
+ contactId: config.contactId ?? null,
1442
+ });
1420
1443
  return !prefs.unsubscribed;
1421
1444
  },
1422
1445
  },
@@ -1462,7 +1485,12 @@ export function createJourneyContext(
1462
1485
  check: "exists",
1463
1486
  within,
1464
1487
  },
1465
- ctx: { db, userId: targetUserId, journeyContext },
1488
+ ctx: {
1489
+ db,
1490
+ userId: targetUserId,
1491
+ contactId: subjectFor(targetUserId),
1492
+ journeyContext,
1493
+ },
1466
1494
  });
1467
1495
  return { found: result.matched, count: result.count };
1468
1496
  },
@@ -1476,7 +1504,10 @@ export function createJourneyContext(
1476
1504
  .from(journeyStates)
1477
1505
  .where(
1478
1506
  and(
1479
- eq(journeyStates.userId, targetUserId),
1507
+ bySubject(journeyStates, {
1508
+ contactId: subjectFor(targetUserId),
1509
+ userKey: targetUserId,
1510
+ }),
1480
1511
  eq(journeyStates.journeyId, targetJourneyId),
1481
1512
  ),
1482
1513
  );
@@ -1549,7 +1580,12 @@ export function createJourneyContext(
1549
1580
  limit = 50,
1550
1581
  within,
1551
1582
  }): Promise<RecentEvent[]> {
1552
- const conditions = [eq(userEvents.userId, targetUserId)];
1583
+ const conditions = [
1584
+ bySubject(userEvents, {
1585
+ contactId: subjectFor(targetUserId),
1586
+ userKey: targetUserId,
1587
+ }),
1588
+ ];
1553
1589
  if (event) {
1554
1590
  conditions.push(eq(userEvents.event, event));
1555
1591
  }
@@ -1,4 +1,9 @@
1
- import { criteriaBuilder, days, evaluateCondition } from "@hogsend/core";
1
+ import {
2
+ bySubject,
3
+ criteriaBuilder,
4
+ days,
5
+ evaluateCondition,
6
+ } from "@hogsend/core";
2
7
  import {
3
8
  contacts,
4
9
  emailPreferences,
@@ -130,6 +135,9 @@ export function buildAgentTools({
130
135
  return db
131
136
  .select({
132
137
  event: userEvents.event,
138
+ // Display echo of the stamped key — not a scoping predicate. This
139
+ // tool lists the recent event stream instance-wide; there is no
140
+ // subject to scope by.
133
141
  userId: userEvents.userId,
134
142
  source: userEvents.source,
135
143
  occurredAt: userEvents.occurredAt,
@@ -169,10 +177,18 @@ export function buildAgentTools({
169
177
  execute: async ({ id }) => {
170
178
  const contact = await resolveContact({ db, id });
171
179
  if (!contact) return { error: `No contact for "${id}"` };
180
+ // Was `contact.externalId ?? contact.id` — an inline re-derivation of
181
+ // the canonical key that missed a preferences row written under an
182
+ // anonymous id. The owning contact names it directly.
172
183
  const prefs = await db
173
184
  .select()
174
185
  .from(emailPreferences)
175
- .where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
186
+ .where(
187
+ bySubject(emailPreferences, {
188
+ contactId: contact.id,
189
+ userKey: contactKey(contact),
190
+ }),
191
+ )
176
192
  .limit(1);
177
193
  return { contact, preferences: prefs[0] ?? null };
178
194
  },
@@ -189,6 +205,10 @@ export function buildAgentTools({
189
205
  const contact = await resolveContact({ db, id });
190
206
  if (!contact) return { error: `No contact for "${id}"` };
191
207
  const key = contactKey(contact);
208
+ // Read by subject: the contact was just resolved, so both legs scope
209
+ // on the `contact_id` FK and pick up activity from keys this person
210
+ // has since moved off.
211
+ const subject = { contactId: contact.id, userKey: key };
192
212
  const [events, journeys] = await Promise.all([
193
213
  db
194
214
  .select({
@@ -197,7 +217,7 @@ export function buildAgentTools({
197
217
  occurredAt: userEvents.occurredAt,
198
218
  })
199
219
  .from(userEvents)
200
- .where(eq(userEvents.userId, key))
220
+ .where(bySubject(userEvents, subject))
201
221
  .orderBy(desc(userEvents.occurredAt))
202
222
  .limit(limit),
203
223
  db
@@ -209,7 +229,7 @@ export function buildAgentTools({
209
229
  .from(journeyStates)
210
230
  .where(
211
231
  and(
212
- eq(journeyStates.userId, key),
232
+ bySubject(journeyStates, subject),
213
233
  isNull(journeyStates.deletedAt),
214
234
  ),
215
235
  )
@@ -296,6 +316,11 @@ export function buildAgentTools({
296
316
  ctx: {
297
317
  db,
298
318
  userId: contactKey(c),
319
+ // Every row here IS a contact, so the evaluator's event leaf
320
+ // counts that contact's whole history — including events stamped
321
+ // under an earlier anonymous key. Without this the audience
322
+ // preview under-counts anyone who registered after being seen.
323
+ contactId: c.id,
299
324
  journeyContext: (c.properties ?? {}) as Record<string, unknown>,
300
325
  },
301
326
  });
@@ -134,6 +134,7 @@ export async function backfillAttributionBatch(opts: {
134
134
  id: userEvents.id,
135
135
  event: userEvents.event,
136
136
  userId: userEvents.userId,
137
+ contactId: userEvents.contactId,
137
138
  properties: userEvents.properties,
138
139
  value: userEvents.value,
139
140
  currency: userEvents.currency,
@@ -151,9 +152,13 @@ export async function backfillAttributionBatch(opts: {
151
152
  .orderBy(asc(userEvents.id))
152
153
  .limit(limit);
153
154
 
154
- // Batch contact resolution: canonical keys are externalId or the
155
- // contact row uuid. MATCH ONLY — backfill never mints contacts.
156
- const keys = [...new Set(rows.map((row) => row.userId))];
155
+ // Owner resolution. A row stamped with `contact_id` already names its
156
+ // owner, so only the unstamped remainder needs the string lookup:
157
+ // canonical keys are externalId or the contact row uuid. MATCH ONLY —
158
+ // backfill never mints contacts.
159
+ const keys = [
160
+ ...new Set(rows.filter((row) => !row.contactId).map((row) => row.userId)),
161
+ ];
157
162
  const uuidKeys = keys.filter((key) => UUID_RE.test(key));
158
163
  const contactRows =
159
164
  keys.length > 0
@@ -178,7 +183,7 @@ export async function backfillAttributionBatch(opts: {
178
183
  let conversionsFired = 0;
179
184
  let creditsWritten = 0;
180
185
  for (const row of rows) {
181
- const contactId = contactByKey.get(row.userId);
186
+ const contactId = row.contactId ?? contactByKey.get(row.userId);
182
187
  if (!contactId) continue;
183
188
  const fired = await evaluateConversionsAtIngest({
184
189
  db,
@@ -206,6 +211,15 @@ export async function backfillAttributionBatch(opts: {
206
211
  logger,
207
212
  conversionId: conversion.conversionId,
208
213
  userKey: row.userId,
214
+ // Scope the touchpoint path by the OWNER only when the spine row
215
+ // itself carries the stamp. This function replays HISTORY, and
216
+ // pre-upgrade history predates the `contact_id` dual-write entirely:
217
+ // an unstamped trigger row sits among unstamped touchpoints, which a
218
+ // contact-scoped scan cannot reach at all. When the trigger IS
219
+ // stamped, everything older is too (PRD 04's sweep cursors ascending
220
+ // by id), so the contact arm is both safe and the point — it reaches
221
+ // the anon-era touches adoption moved onto this person.
222
+ contactId: row.contactId,
209
223
  value: conversion.value,
210
224
  currency: conversion.currency,
211
225
  occurredAt: row.occurredAt,
@@ -240,11 +254,17 @@ export async function backfillAttributionBatch(opts: {
240
254
  id: conversions.id,
241
255
  definitionId: conversions.definitionId,
242
256
  userKey: conversions.userKey,
257
+ contactId: conversions.contactId,
258
+ // The trigger row's own stamp — the same "is this spine stamped?" test
259
+ // stage 1 applies, joined in because a conversions row always names an
260
+ // owner even when the history behind it predates `contact_id`.
261
+ spineContactId: userEvents.contactId,
243
262
  value: conversions.value,
244
263
  currency: conversions.currency,
245
264
  occurredAt: conversions.occurredAt,
246
265
  })
247
266
  .from(conversions)
267
+ .leftJoin(userEvents, eq(conversions.eventId, userEvents.id))
248
268
  .where(
249
269
  and(
250
270
  inArray(conversions.definitionId, defIds),
@@ -265,6 +285,9 @@ export async function backfillAttributionBatch(opts: {
265
285
  logger,
266
286
  conversionId: row.id,
267
287
  userKey: row.userKey,
288
+ // See stage 1: the owner scopes the path only when the spine carries the
289
+ // stamp; unstamped (pre-upgrade) history is reachable by string key only.
290
+ contactId: row.spineContactId ? row.contactId : null,
268
291
  value: row.value,
269
292
  currency: row.currency,
270
293
  occurredAt: row.occurredAt,
@@ -3,6 +3,7 @@ import {
3
3
  computeAllModels,
4
4
  } from "@hogsend/attribution";
5
5
  import {
6
+ bySubject,
6
7
  type DurationObject,
7
8
  durationToMs,
8
9
  TOUCHPOINT_EVENTS,
@@ -120,6 +121,16 @@ export async function recordAttributionCredits(opts: {
120
121
  conversionId: string;
121
122
  /** The contact's canonical event key (`user_events.user_id`). */
122
123
  userKey: string;
124
+ /**
125
+ * The trusted owner uuid (`conversions.contact_id`). REQUIRED (not
126
+ * optional) for the same reason the enrollment guards' is: an optional
127
+ * field silently defaults a new caller onto the mutable text key, and the
128
+ * touchpoint path is precisely the history written BEFORE the person was
129
+ * identified — a key-scoped read drops the anonymous half of every journey
130
+ * and credits the conversion to nothing. Pass `null` explicitly for a
131
+ * subject with no contact; `userKey` still serves that case.
132
+ */
133
+ contactId: string | null;
123
134
  value: number | null;
124
135
  currency: string | null;
125
136
  /** When the conversion happened. */
@@ -132,8 +143,16 @@ export async function recordAttributionCredits(opts: {
132
143
  */
133
144
  windows?: Partial<Record<TouchpointChannel, DurationObject>>;
134
145
  }): Promise<{ touchpoints: number }> {
135
- const { db, logger, conversionId, userKey, value, currency, occurredAt } =
136
- opts;
146
+ const {
147
+ db,
148
+ logger,
149
+ conversionId,
150
+ userKey,
151
+ contactId,
152
+ value,
153
+ currency,
154
+ occurredAt,
155
+ } = opts;
137
156
  const defaultWindowMs = opts.windowDays * 24 * 60 * 60 * 1000;
138
157
  const channelWindowMs = new Map<TouchpointChannel, number>(
139
158
  Object.entries(opts.windows ?? {}).map(([channel, duration]) => [
@@ -158,7 +177,7 @@ export async function recordAttributionCredits(opts: {
158
177
  .from(userEvents)
159
178
  .where(
160
179
  and(
161
- eq(userEvents.userId, userKey),
180
+ bySubject(userEvents, { contactId, userKey }),
162
181
  inArray(userEvents.event, [...TOUCHPOINT_EVENTS]),
163
182
  gte(userEvents.occurredAt, windowStart),
164
183
  lte(userEvents.occurredAt, occurredAt),
@@ -224,9 +224,12 @@ export async function checkActionAudience(
224
224
  });
225
225
  }
226
226
 
227
+ // PRD 05 T6 — the contact row is in hand, so the read is contact-scoped
228
+ // directly; the old `externalId ?? id` string derivation is the idiom the
229
+ // flip retires.
227
230
  const prefs = await readRecipientPreferences(db, {
228
231
  email: contact.email,
229
- userId: contact.externalId ?? contact.id,
232
+ contactId: contact.id,
230
233
  });
231
234
  if (prefs.unsubscribedAll) {
232
235
  return {