@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
@@ -3,7 +3,7 @@ import type {
3
3
  ConversionDestination,
4
4
  ConversionDispatchInput,
5
5
  } from "@hogsend/core";
6
- import { CLICK_ID_PARAM_NAMES } from "@hogsend/core";
6
+ import { bySubject, CLICK_ID_PARAM_NAMES } from "@hogsend/core";
7
7
  import {
8
8
  contacts,
9
9
  conversionDispatches,
@@ -98,6 +98,16 @@ export async function createConversionDispatches(opts: {
98
98
  export async function recoverClickContext(opts: {
99
99
  db: Database;
100
100
  userKey: string;
101
+ /**
102
+ * The trusted owner uuid. REQUIRED (not optional) for the same reason the
103
+ * enrollment guards' is: an optional field silently defaults a new caller
104
+ * onto the mutable text key, and an arrival recorded under the visitor's
105
+ * anon-era key would then be invisible — the click id the ad platform needs
106
+ * to match the conversion goes missing exactly when it matters (the click
107
+ * IS the anonymous era). Pass `null` explicitly for a subject with no
108
+ * contact; `userKey` still serves that case.
109
+ */
110
+ contactId: string | null;
101
111
  before: Date;
102
112
  }): Promise<ConversionDispatchInput["clicks"]> {
103
113
  const rows = await opts.db
@@ -108,7 +118,10 @@ export async function recoverClickContext(opts: {
108
118
  .from(userEvents)
109
119
  .where(
110
120
  and(
111
- eq(userEvents.userId, opts.userKey),
121
+ bySubject(userEvents, {
122
+ contactId: opts.contactId,
123
+ userKey: opts.userKey,
124
+ }),
112
125
  eq(userEvents.event, "campaign.arrived"),
113
126
  lte(userEvents.occurredAt, opts.before),
114
127
  ),
@@ -209,6 +222,7 @@ export async function deliverConversionDispatch(opts: {
209
222
  const clicks = await recoverClickContext({
210
223
  db,
211
224
  userKey: row.conversion.userKey,
225
+ contactId: row.conversion.contactId,
212
226
  before: row.conversion.occurredAt,
213
227
  });
214
228
 
@@ -1,22 +1,30 @@
1
- import { durationToMs, hours } from "@hogsend/core";
1
+ import { bySubject, durationToMs, hours } from "@hogsend/core";
2
2
  import type { JourneyMeta } from "@hogsend/core/types";
3
3
  import { type Database, emailPreferences, journeyStates } from "@hogsend/db";
4
4
  import { and, eq } from "drizzle-orm";
5
5
 
6
+ /**
7
+ * The subject these guards read history for. `contactId` is REQUIRED (not
8
+ * optional) for the same reason `ConditionContext.contactId` is: an optional
9
+ * field silently defaults a new caller onto the mutable text key, which is
10
+ * exactly the entry-limit miss this batch exists to close. Pass `null`
11
+ * explicitly for a subject with no contact — a permanent, supported state (the
12
+ * engine refuses to mint a contact on observation).
13
+ */
6
14
  export async function checkEntryLimit(opts: {
7
15
  db: Database;
8
16
  journey: JourneyMeta;
9
17
  userId: string;
18
+ contactId: string | null;
10
19
  }): Promise<{ allowed: boolean; reason?: string }> {
11
- const { db, journey, userId } = opts;
20
+ const { db, journey, userId, contactId } = opts;
12
21
  if (journey.entryLimit === "unlimited") return { allowed: true };
13
22
 
23
+ const subject = bySubject(journeyStates, { contactId, userKey: userId });
24
+
14
25
  if (journey.entryLimit === "once") {
15
26
  const existing = await db.query.journeyStates.findFirst({
16
- where: and(
17
- eq(journeyStates.userId, userId),
18
- eq(journeyStates.journeyId, journey.id),
19
- ),
27
+ where: and(subject, eq(journeyStates.journeyId, journey.id)),
20
28
  });
21
29
  return existing
22
30
  ? { allowed: false, reason: "already_entered_once" }
@@ -28,10 +36,7 @@ export async function checkEntryLimit(opts: {
28
36
  const cutoff = new Date(Date.now() - periodMs);
29
37
 
30
38
  const existing = await db.query.journeyStates.findFirst({
31
- where: and(
32
- eq(journeyStates.userId, userId),
33
- eq(journeyStates.journeyId, journey.id),
34
- ),
39
+ where: and(subject, eq(journeyStates.journeyId, journey.id)),
35
40
  orderBy: (states, { desc }) => [desc(states.createdAt)],
36
41
  });
37
42
 
@@ -43,13 +48,15 @@ export async function checkEntryLimit(opts: {
43
48
  return { allowed: true };
44
49
  }
45
50
 
51
+ /** See {@link checkEntryLimit} for why `contactId` is required. */
46
52
  export async function checkEmailPreferences(opts: {
47
53
  db: Database;
48
54
  userId: string;
55
+ contactId: string | null;
49
56
  }): Promise<{ unsubscribed: boolean }> {
50
- const { db, userId } = opts;
57
+ const { db, userId, contactId } = opts;
51
58
  const prefs = await db.query.emailPreferences.findFirst({
52
- where: eq(emailPreferences.userId, userId),
59
+ where: bySubject(emailPreferences, { contactId, userKey: userId }),
53
60
  });
54
61
 
55
62
  return { unsubscribed: prefs?.unsubscribedAll ?? false };
package/src/lib/feed.ts CHANGED
@@ -312,7 +312,7 @@ export async function sendFeedItem(
312
312
  // channel list regardless of the item's own category.
313
313
  //
314
314
  // The preference read is the UNIFIED aggregated `readRecipientPreferences`
315
- // keyed by BOTH the recipient's `external_id ?? contact_id` AND its email —
315
+ // keyed by BOTH the recipient's resolved `contact_id` AND its email —
316
316
  // NOT the old single-row `(extId, email)` lookup. This is a deliberate,
317
317
  // suppression-conservative behaviour change: an `unsubscribed_all` (or category
318
318
  // opt-out) imported before the contact existed and keyed `(email, email)` now
@@ -333,12 +333,12 @@ export async function sendFeedItem(
333
333
  userId: recipient.userId,
334
334
  email: recipient.email,
335
335
  });
336
- // `external_id ?? contact_id` — the SAME identity key the old single-row read
337
- // used (and that preference writes key on). Undefined for an anon recipient.
338
- const extId = recip ? (recip.externalId ?? recip.contactId) : undefined;
336
+ // PRD 05 T6 — contact-scoped read (the resolved contact id IS the subject);
337
+ // the old `external_id ?? contact_id` string derivation is retired. Null
338
+ // for an anon recipient: email leg only, same as before.
339
339
  const prefs = await readRecipientPreferences(db, {
340
340
  email: recip?.email,
341
- userId: extId,
341
+ contactId: recip?.contactId ?? null,
342
342
  });
343
343
  // `unsubscribed_all` on an IDENTIFIED recipient suppresses (consistent with
344
344
  // the email mailer's `checkEmailPreferences`); guarded on `recip` so an
package/src/lib/flags.ts CHANGED
@@ -6,7 +6,11 @@ import type {
6
6
  FlagVariant,
7
7
  PropertyCondition,
8
8
  } from "@hogsend/core";
9
- import { evaluateCondition, evaluatePropertyConditions } from "@hogsend/core";
9
+ import {
10
+ bySubject,
11
+ evaluateCondition,
12
+ evaluatePropertyConditions,
13
+ } from "@hogsend/core";
10
14
  import {
11
15
  bucketMemberships,
12
16
  contacts,
@@ -72,12 +76,13 @@ export function emptySnapshot(
72
76
  }
73
77
 
74
78
  /**
75
- * Load the FIXED ~4-query targeting snapshot for a contact. `contactKey` is the
76
- * logical id `bucket_memberships`/`journey_states` are keyed on (their `userId`
77
- * is `external_id ?? anonymous_id ?? id`); `contactId` is the trusted uuid used
78
- * for the property + deal reads (see `evaluateFlagsForContact`'s security note).
79
- * An anon contact with no rows yields empty sets — correct (targeting-gated
80
- * flags fall to default).
79
+ * Load the FIXED ~4-query targeting snapshot for a contact. `contactId` is the
80
+ * trusted uuid: it scopes the property + deal reads (see
81
+ * `evaluateFlagsForContact`'s security note) AND, via `bySubject`, the bucket +
82
+ * journey history reads. `contactKey` (`external_id ?? anonymous_id ?? id`) is
83
+ * the fallback those two history reads use when NO contact is resolved — an
84
+ * anonymous visitor, whose rows are still text-keyed. An anon contact with no
85
+ * rows yields empty sets — correct (targeting-gated flags fall to default).
81
86
  */
82
87
  export async function loadTargetingSnapshot(opts: {
83
88
  db: Database;
@@ -99,7 +104,7 @@ export async function loadTargetingSnapshot(opts: {
99
104
  .from(bucketMemberships)
100
105
  .where(
101
106
  and(
102
- eq(bucketMemberships.userId, contactKey),
107
+ bySubject(bucketMemberships, { contactId, userKey: contactKey }),
103
108
  eq(bucketMemberships.status, "active"),
104
109
  isNull(bucketMemberships.deletedAt),
105
110
  ),
@@ -110,7 +115,7 @@ export async function loadTargetingSnapshot(opts: {
110
115
  status: journeyStates.status,
111
116
  })
112
117
  .from(journeyStates)
113
- .where(eq(journeyStates.userId, contactKey)),
118
+ .where(bySubject(journeyStates, { contactId, userKey: contactKey })),
114
119
  contactId
115
120
  ? db
116
121
  .select({
@@ -183,6 +188,14 @@ export interface TargetingEvalContext {
183
188
  mode: "browser" | "server";
184
189
  db?: Database;
185
190
  userId?: string;
191
+ /**
192
+ * The SERVER-TRUSTED `contacts.id` for `userId`, forwarded verbatim to
193
+ * `ConditionContext.contactId` so a scan leaf reads the PERSON's history
194
+ * rather than whatever the mutable `userId` text key happens to name. Absent
195
+ * / null for a subject with no contact (an anonymous visitor), which keeps
196
+ * the scan on the text key exactly as before.
197
+ */
198
+ contactId?: string | null;
186
199
  }
187
200
 
188
201
  /**
@@ -272,6 +285,7 @@ export async function evaluateTargeting(
272
285
  ctx: {
273
286
  db: ctx.db,
274
287
  userId: ctx.userId,
288
+ contactId: ctx.contactId ?? null,
275
289
  // `email_engagement` leaves look up `email_sends.to_email` — key it on the
276
290
  // contact's ACTUAL email (from the loaded snapshot), never the contactKey
277
291
  // (which is external_id/anonymous_id/id, never an address).
@@ -426,6 +440,7 @@ async function evaluateFlagResolved(
426
440
  mode: "browser" | "server";
427
441
  db?: Database;
428
442
  userId?: string;
443
+ contactId?: string | null;
429
444
  },
430
445
  ): Promise<unknown> {
431
446
  if (!flag.enabled) return flag.defaultValue;
@@ -435,6 +450,7 @@ async function evaluateFlagResolved(
435
450
  mode: ctx.mode,
436
451
  db: ctx.db,
437
452
  userId: ctx.userId,
453
+ contactId: ctx.contactId,
438
454
  };
439
455
  const sets = resolveConditionSets(flag);
440
456
  for (let i = 0; i < sets.length; i++) {
@@ -492,6 +508,7 @@ export async function evaluateFlagsForContact(opts: {
492
508
  mode,
493
509
  db: mode === "server" ? db : undefined,
494
510
  userId: mode === "server" ? contactKey : undefined,
511
+ contactId: mode === "server" ? (contactId ?? null) : null,
495
512
  });
496
513
  }
497
514
  return result;
@@ -5,7 +5,7 @@ import type {
5
5
  GroupsAssociation,
6
6
  PropertyCondition,
7
7
  } from "@hogsend/core";
8
- import { evaluatePropertyConditions } from "@hogsend/core";
8
+ import { bySubject, evaluatePropertyConditions } from "@hogsend/core";
9
9
  import type { JourneyRegistry } from "@hogsend/core/registry";
10
10
  import type { JourneyMeta } from "@hogsend/core/types";
11
11
  import {
@@ -728,6 +728,7 @@ export async function ingestEvent(opts: {
728
728
  }),
729
729
  checkExits(db, registry, hatchet, logger, {
730
730
  userId: resolvedKey,
731
+ contactId,
731
732
  eventName: event.event,
732
733
  properties: event.eventProperties,
733
734
  }),
@@ -854,6 +855,7 @@ export async function ingestEvent(opts: {
854
855
  logger,
855
856
  conversionId: firedConversion.conversionId,
856
857
  userKey: resolvedKey,
858
+ contactId,
857
859
  value: firedConversion.value,
858
860
  currency: firedConversion.currency,
859
861
  occurredAt: insertedRow.occurredAt,
@@ -998,6 +1000,13 @@ async function checkExits(
998
1000
  logger: Logger,
999
1001
  event: {
1000
1002
  userId: string;
1003
+ /**
1004
+ * The subject's resolved `contacts.id`, or `null` when the resolve refused
1005
+ * to mint one (an anonymous visitor — a permanent supported state). The
1006
+ * scan MUST still exit that population's journeys, which is why this goes
1007
+ * through `bySubject` rather than a bare `contact_id` predicate.
1008
+ */
1009
+ contactId: string | null;
1001
1010
  eventName: string;
1002
1011
  properties: Record<string, unknown>;
1003
1012
  },
@@ -1006,7 +1015,10 @@ async function checkExits(
1006
1015
 
1007
1016
  const activeStates = await db.query.journeyStates.findMany({
1008
1017
  where: and(
1009
- eq(journeyStates.userId, event.userId),
1018
+ bySubject(journeyStates, {
1019
+ contactId: event.contactId,
1020
+ userKey: event.userId,
1021
+ }),
1010
1022
  inArray(journeyStates.status, ["active", "waiting"]),
1011
1023
  isNull(journeyStates.deletedAt),
1012
1024
  ),
@@ -61,22 +61,34 @@ export async function computeJourneyLift(
61
61
 
62
62
  // Outcome: the contact fired ≥1 qualifying conversion AFTER their state
63
63
  // row was created (post-assignment — the intent-to-treat clock) and at
64
- // or before the asOf snapshot instant.
64
+ // or before the asOf snapshot instant. Joined on the contact FK, not the
65
+ // text key: `conversions.contact_id` is NOT NULL, so a conversion always
66
+ // belongs to a resolved contact and no text fallback is needed — a
67
+ // contactless enrollment has no contact, therefore no conversion, and the
68
+ // NULL comparison correctly matches nothing. The old `c.user_key =
69
+ // js.user_id` string compare missed every conversion recorded under a key
70
+ // the person moved off after enrolling, under-counting converters.
65
71
  const convertedSql = sql`exists (
66
72
  select 1 from conversions c
67
- where c.user_key = ${journeyStates.userId}
73
+ where c.contact_id = ${journeyStates.contactId}
68
74
  and c.occurred_at >= ${journeyStates.createdAt}
69
75
  and c.occurred_at <= ${asOfTs}${definitionSql}
70
76
  )`;
71
77
 
78
+ // WHO a row is about — the owning contact when stamped, else the mutable
79
+ // text key. The coalesce is load-bearing: `count(distinct …)` skips NULLs,
80
+ // so a bare `contact_id` would silently drop every contactless enrollment
81
+ // from the denominator and read as a quiet journey rather than a bug.
82
+ const subjectSql = sql`coalesce(${journeyStates.contactId}::text, ${journeyStates.userId})`;
83
+
72
84
  const cohort = async (control: boolean): Promise<LiftCohort> => {
73
85
  const statusFilter = control
74
86
  ? eq(journeyStates.status, "held_out")
75
87
  : sql`${journeyStates.status} != 'held_out'`;
76
88
  const [row] = await db
77
89
  .select({
78
- contacts: sql<number>`count(distinct ${journeyStates.userId})::int`,
79
- converters: sql<number>`(count(distinct ${journeyStates.userId}) filter (where ${convertedSql}))::int`,
90
+ contacts: sql<number>`count(distinct ${subjectSql})::int`,
91
+ converters: sql<number>`(count(distinct ${subjectSql}) filter (where ${convertedSql}))::int`,
80
92
  })
81
93
  .from(journeyStates)
82
94
  .where(
@@ -125,7 +137,7 @@ export async function computeLiftValues(opts: LiftQueryOpts): Promise<{
125
137
  and js.created_at >= ${sinceTs}
126
138
  and js.created_at < ${asOfTs}
127
139
  and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
128
- and js.user_id = c.user_key
140
+ and js.contact_id = c.contact_id
129
141
  and c.occurred_at >= js.created_at
130
142
  )${definitionSql}
131
143
  group by c.currency
@@ -1,10 +1,14 @@
1
1
  import type { Database } from "@hogsend/db";
2
2
  import { emailPreferences } from "@hogsend/db";
3
- import { sql } from "drizzle-orm";
3
+ import { and, eq, sql } from "drizzle-orm";
4
4
  import { lookupContactIdByKey, resolveRecipient } from "./contacts.js";
5
5
  import { hatchet } from "./hatchet.js";
6
6
  import { createLogger } from "./logger.js";
7
7
  import { emitOutbound } from "./outbound.js";
8
+ import {
9
+ isUniqueViolationOn,
10
+ UQ_CONTACT_EMAIL_PREFERENCES,
11
+ } from "./unique-violation.js";
8
12
 
9
13
  export {
10
14
  type RecipientPreferences,
@@ -113,34 +117,79 @@ export async function upsertEmailPreference(opts: {
113
117
  setClause.categories = sql`jsonb_set(COALESCE(${emailPreferences.categories}, '{}'::jsonb), ${`{${update.categoryKey}}`}, ${jsonValue}::jsonb)`;
114
118
  }
115
119
 
116
- await db
117
- .insert(emailPreferences)
118
- .values({
119
- userId: externalId,
120
- email,
121
- contactId,
122
- ...(update.unsubscribedAll !== undefined
123
- ? { unsubscribedAll: update.unsubscribedAll }
124
- : {}),
125
- ...(update.suppressed !== undefined
126
- ? { suppressed: update.suppressed }
127
- : {}),
128
- ...(update.suppressedAt !== undefined
129
- ? { suppressedAt: update.suppressedAt }
130
- : {}),
131
- ...(update.recordBounce
132
- ? { bounceCount: 1, lastBounceAt: new Date() }
133
- : {}),
134
- ...(update.categoryKey !== undefined
135
- ? {
136
- categories: { [update.categoryKey]: update.categoryValue ?? false },
137
- }
138
- : {}),
139
- })
140
- .onConflictDoUpdate({
141
- target: [emailPreferences.userId, emailPreferences.email],
142
- set: setClause,
143
- });
120
+ const upsertOnStringKey = () =>
121
+ db
122
+ .insert(emailPreferences)
123
+ .values({
124
+ userId: externalId,
125
+ email,
126
+ contactId,
127
+ ...(update.unsubscribedAll !== undefined
128
+ ? { unsubscribedAll: update.unsubscribedAll }
129
+ : {}),
130
+ ...(update.suppressed !== undefined
131
+ ? { suppressed: update.suppressed }
132
+ : {}),
133
+ ...(update.suppressedAt !== undefined
134
+ ? { suppressedAt: update.suppressedAt }
135
+ : {}),
136
+ ...(update.recordBounce
137
+ ? { bounceCount: 1, lastBounceAt: new Date() }
138
+ : {}),
139
+ ...(update.categoryKey !== undefined
140
+ ? {
141
+ categories: {
142
+ [update.categoryKey]: update.categoryValue ?? false,
143
+ },
144
+ }
145
+ : {}),
146
+ })
147
+ .onConflictDoUpdate({
148
+ target: [emailPreferences.userId, emailPreferences.email],
149
+ set: setClause,
150
+ });
151
+
152
+ try {
153
+ await upsertOnStringKey();
154
+ } catch (err) {
155
+ // PRD 05 T3 — the arbiter STAYS on (user_id, email); the contact-scoped
156
+ // index is a pure constraint (drizzle targets columns only, and a bare
157
+ // (contact_id, email) arbiter would never fire for the contactless
158
+ // population — a D6-degraded NULL resolve is legal and permanent). So the
159
+ // one collision the string arbiter cannot see — SAME contact, SAME address,
160
+ // DIFFERENT `user_id` string, which is exactly what adoption produces when
161
+ // it stamps `contact_id` without rewriting `user_id` — arrives here as a
162
+ // 23505 and is converted into the update path by hand.
163
+ if (!contactId || !isUniqueViolationOn(err, UQ_CONTACT_EMAIL_PREFERENCES)) {
164
+ throw err;
165
+ }
166
+ // `contactId` is dropped from the set: it only existed to carry the
167
+ // `excluded.contact_id` coalesce, which has no meaning outside ON CONFLICT,
168
+ // and the row we are about to update already holds THIS id (that is how it
169
+ // collided). Every other entry references the table column, which is legal
170
+ // on the right-hand side of a plain UPDATE.
171
+ const { contactId: _excludedCoalesce, ...contactScopedSet } = setClause;
172
+ const converted = await db
173
+ .update(emailPreferences)
174
+ .set(contactScopedSet)
175
+ .where(
176
+ and(
177
+ eq(emailPreferences.contactId, contactId),
178
+ eq(emailPreferences.email, email),
179
+ ),
180
+ )
181
+ .returning({ id: emailPreferences.id });
182
+
183
+ // ZERO rows means the conflicting row vanished between the INSERT and this
184
+ // UPDATE — a concurrent merge folded it away (`foldEmailPreferences` hard-
185
+ // deletes the row it absorbed) or re-pointed its `contact_id`. Accepting
186
+ // that silently DROPS the write while the emit below still announces an
187
+ // opt-out that never landed. The conflicting row is gone, so the original
188
+ // arbiter INSERT now has somewhere to go: retry it ONCE. A second 23505
189
+ // means another writer re-created the row in this same gap — that throws,
190
+ // which is the loud answer, not a silent loss.
191
+ if (converted.length === 0) await upsertOnStringKey();
192
+ }
144
193
 
145
194
  // OUTBOUND `contact.unsubscribed` — this is the SINGLE choke for ALL preference
146
195
  // writes (token unsub, preference center, list-membership flips), so the emit
@@ -15,16 +15,30 @@ export interface RecipientPreferences {
15
15
  * Read the conservative preference verdict shared by email, feed, and
16
16
  * connector delivery. This module intentionally contains no Hatchet/runtime
17
17
  * imports so journey authoring modules remain safe to load in unit tests.
18
+ *
19
+ * The subject leg follows the `bySubject` law (PRD 05): when `contactId` is
20
+ * known, rows are matched by ownership stamp ONLY — never OR'd with the
21
+ * mutable string key, which goes stale the moment the contact adopts a new
22
+ * canonical key. `contactId` is REQUIRED (pass `null` explicitly for a
23
+ * contactless subject) so a new caller cannot silently default onto the
24
+ * string key. The email leg is orthogonal: address-scoped suppression
25
+ * (imports, bounces) predates the contact and stays an OR leg.
18
26
  */
19
27
  export async function readRecipientPreferences(
20
28
  db: Database,
21
- keys: { email?: string | null; userId?: string | null },
29
+ keys: {
30
+ email?: string | null;
31
+ userId?: string | null;
32
+ contactId: string | null;
33
+ },
22
34
  ): Promise<RecipientPreferences> {
23
35
  const legs = [];
24
36
  if (typeof keys.email === "string" && keys.email.length > 0) {
25
37
  legs.push(eq(emailPreferences.email, keys.email));
26
38
  }
27
- if (typeof keys.userId === "string" && keys.userId.length > 0) {
39
+ if (keys.contactId) {
40
+ legs.push(eq(emailPreferences.contactId, keys.contactId));
41
+ } else if (typeof keys.userId === "string" && keys.userId.length > 0) {
28
42
  legs.push(eq(emailPreferences.userId, keys.userId));
29
43
  }
30
44
 
@@ -1,8 +1,8 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { type Database, userEvents } from "@hogsend/db";
2
3
  import {
3
4
  and,
4
5
  count,
5
- eq,
6
6
  isNotNull,
7
7
  isNull,
8
8
  max,
@@ -77,13 +77,20 @@ export interface ContactRevenue {
77
77
  }
78
78
 
79
79
  /**
80
- * Sum a contact's valued events, per currency. `key` is the contact's
81
- * canonical event key (`external_id ?? anonymous_id ?? id`) — the same key
82
- * `ingestEvent` stamps on `user_events.user_id`.
80
+ * Sum a contact's valued events, per currency. `contactId` is the trusted
81
+ * owner uuid and is REQUIRED (not optional) for the same reason the
82
+ * enrollment guards' is: an optional field silently defaults a new caller
83
+ * onto the mutable text key, so a contact whose valued events were ingested
84
+ * under an earlier key reports zero revenue. Pass `null` explicitly for a
85
+ * subject with no contact — a permanent, supported state (the engine refuses
86
+ * to mint a contact on observation), and the case `key` still serves. `key`
87
+ * is the canonical event key (`external_id ?? anonymous_id ?? id`) — the same
88
+ * key `ingestEvent` stamps on `user_events.user_id`.
83
89
  */
84
90
  export async function getContactRevenue(opts: {
85
91
  db: Database;
86
92
  key: string;
93
+ contactId: string | null;
87
94
  }): Promise<ContactRevenue> {
88
95
  const rows = await opts.db
89
96
  .select({
@@ -93,7 +100,15 @@ export async function getContactRevenue(opts: {
93
100
  lastAt: max(userEvents.occurredAt),
94
101
  })
95
102
  .from(userEvents)
96
- .where(and(eq(userEvents.userId, opts.key), trustedValuedEventFilter()))
103
+ .where(
104
+ and(
105
+ bySubject(userEvents, {
106
+ contactId: opts.contactId,
107
+ userKey: opts.key,
108
+ }),
109
+ trustedValuedEventFilter(),
110
+ ),
111
+ )
97
112
  .groupBy(userEvents.currency);
98
113
 
99
114
  let lastValuedAt: Date | null = null;
@@ -17,6 +17,7 @@ import {
17
17
  } from "../journeys/journey-boundary.js";
18
18
  import { logTransition } from "../journeys/journey-log.js";
19
19
  import { getListRegistry } from "../lists/registry-singleton.js";
20
+ import { lookupContactIdByKey } from "./contacts.js";
20
21
  import type { FrequencyCapConfig } from "./email-service-types.js";
21
22
  import { hatchet } from "./hatchet.js";
22
23
  import { isGlobalControl } from "./holdout.js";
@@ -582,8 +583,24 @@ async function checkSmsSuppression(
582
583
  if (phoneRow && phoneRow.resubscribedAt === null) return "suppressed";
583
584
  const phoneConsent = phoneRow != null;
584
585
 
586
+ // PRD 05 T6 — resolve the subject's contact so the preference read follows
587
+ // the contact when the string key has gone stale (`sms_sends` carries no
588
+ // dual-write stamp, so the resolve happens here). D6-wrapped: a bookkeeping
589
+ // probe may never fail the suppression gate it rides on — a throw degrades
590
+ // to the string-key leg, never to an unchecked send.
591
+ let prefContactId: string | null = null;
592
+ if (opts.userId) {
593
+ try {
594
+ prefContactId = await lookupContactIdByKey(db, opts.userId);
595
+ } catch {
596
+ prefContactId = null;
597
+ }
598
+ }
585
599
  const prefs = opts.userId
586
- ? await readRecipientPreferences(db, { userId: opts.userId })
600
+ ? await readRecipientPreferences(db, {
601
+ userId: opts.userId,
602
+ contactId: prefContactId,
603
+ })
587
604
  : null;
588
605
  if (prefs?.unsubscribedAll) return "unsubscribed";
589
606
 
@@ -223,11 +223,11 @@ async function sendTrackedEmailInner<K extends TemplateName>(
223
223
  const subject = options.subject ?? defaultSubject;
224
224
 
225
225
  if (!options.skipPreferenceCheck) {
226
- const suppression = await checkSuppression(
227
- db,
228
- options.to,
229
- effectiveCategory,
230
- );
226
+ const suppression = await checkSuppression(db, {
227
+ email: options.to,
228
+ contactId: sendContactId,
229
+ category: effectiveCategory,
230
+ });
231
231
  if (suppression) {
232
232
  const rows = await db
233
233
  .insert(emailSends)
@@ -662,13 +662,24 @@ type SuppressionReason = EmailSuppressionError["reason"] | null;
662
662
 
663
663
  async function checkSuppression(
664
664
  db: Database,
665
- email: string,
666
- 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
+ },
667
677
  ): Promise<SuppressionReason> {
678
+ const { email, contactId, category } = opts;
668
679
  // Aggregated across ALL `email_preferences` rows for this address by the shared
669
680
  // reader — an address can legitimately have MORE THAN ONE row (multi-row
670
681
  // (user_id, email) aggregation rationale lives in readRecipientPreferences).
671
- const prefs = await readRecipientPreferences(db, { email });
682
+ const prefs = await readRecipientPreferences(db, { email, contactId });
672
683
 
673
684
  if (prefs.suppressed) return "suppressed";
674
685
  if (prefs.unsubscribedAll) return "unsubscribed";