@hogsend/engine 0.59.0 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +34 -11
  3. package/src/buckets/check-membership.ts +74 -10
  4. package/src/buckets/membership-epoch.ts +11 -1
  5. package/src/campaigns/cohort-sql.ts +10 -0
  6. package/src/index.ts +10 -6
  7. package/src/journeys/execute-journey-run.ts +139 -70
  8. package/src/journeys/journey-context.ts +43 -7
  9. package/src/lib/agent/tools.ts +29 -4
  10. package/src/lib/attribution-backfill.ts +35 -4
  11. package/src/lib/attribution.ts +22 -3
  12. package/src/lib/connector-actions.ts +17 -17
  13. package/src/lib/contacts.ts +541 -175
  14. package/src/lib/conversion-dispatch.ts +16 -2
  15. package/src/lib/enrollment-guards.ts +19 -12
  16. package/src/lib/feed.ts +5 -5
  17. package/src/lib/flags.ts +26 -9
  18. package/src/lib/ingestion.ts +14 -2
  19. package/src/lib/journey-lift.ts +17 -5
  20. package/src/lib/preferences.ts +78 -29
  21. package/src/lib/recipient-preferences.ts +16 -2
  22. package/src/lib/refine.ts +16 -10
  23. package/src/lib/revenue.ts +20 -5
  24. package/src/lib/sms-inbound.ts +6 -1
  25. package/src/lib/sms-tracked.ts +18 -1
  26. package/src/lib/timezone.ts +11 -1
  27. package/src/lib/tracked.ts +19 -8
  28. package/src/lib/tracking-events.ts +28 -0
  29. package/src/lib/unique-violation.ts +44 -0
  30. package/src/routes/admin/buckets.ts +21 -1
  31. package/src/routes/admin/bulk.ts +14 -2
  32. package/src/routes/admin/contacts.ts +20 -7
  33. package/src/routes/admin/conversions.ts +20 -4
  34. package/src/routes/admin/emails.ts +17 -2
  35. package/src/routes/admin/events.ts +32 -41
  36. package/src/routes/admin/funnels.ts +6 -1
  37. package/src/routes/admin/groups.ts +4 -0
  38. package/src/routes/admin/impact.ts +30 -10
  39. package/src/routes/admin/journey-impact.ts +18 -9
  40. package/src/routes/admin/journeys.ts +8 -1
  41. package/src/routes/admin/maintenance.ts +7 -1
  42. package/src/routes/admin/preferences.ts +85 -46
  43. package/src/routes/admin/reporting.ts +25 -5
  44. package/src/routes/admin/targeting.ts +1 -0
  45. package/src/routes/admin/timeline.ts +16 -10
  46. package/src/routes/email/preferences.ts +18 -1
  47. package/src/routes/feed/recipient.ts +5 -0
  48. package/src/routes/lists/index.ts +6 -6
  49. package/src/workflows/backfill-contact-id.ts +210 -30
  50. package/src/workflows/bucket-backfill.ts +145 -67
  51. package/src/workflows/bucket-reconcile.ts +164 -51
  52. package/src/workflows/check-alerts.ts +4 -0
  53. package/src/workflows/impact-digest.ts +10 -3
  54. package/src/workflows/journey-blueprint-interpreter.ts +8 -1
  55. package/src/workflows/send-campaign.ts +18 -11
@@ -13,11 +13,14 @@ import {
13
13
  } from "@hogsend/db";
14
14
  import {
15
15
  and,
16
+ type Column,
16
17
  eq,
17
18
  ilike,
18
19
  inArray,
19
20
  isNotNull,
20
21
  isNull,
22
+ ne,
23
+ not,
21
24
  or,
22
25
  type SQL,
23
26
  sql,
@@ -92,11 +95,12 @@ export class UntrustedKeyKindError extends Error {
92
95
  }
93
96
 
94
97
  /**
95
- * True when `value` is the canonical key of an IDENTIFIED contact — i.e. a
96
- * live contact's `external_id`, or its `email` when that is its canonical key
97
- * (no `external_id`). Such a value names an identified person, so a
98
- * token-less publishable/unauthenticated caller must NOT be allowed to claim
99
- * it as an "anon id" (the feed-read and arrival-stamp forgery guard).
98
+ * True when `value` names an IDENTIFIED person: a live contact's canonical
99
+ * `external_id` (or its `email` when that is its canonical key), OR — via the
100
+ * identity table — any non-anonymous key a live contact holds, including a
101
+ * merged loser's STALE key (PRD 07 T6b). Such a value must NOT be claimable by
102
+ * a token-less publishable/unauthenticated caller as an "anon id" (the
103
+ * feed-read and arrival-stamp forgery guard).
100
104
  *
101
105
  * A genuine browser anon id only ever matches a contact via `anonymous_id`
102
106
  * whose canonical key is that same anon id (the contact has no `external_id`)
@@ -110,6 +114,30 @@ export async function collidesWithIdentified(
110
114
  db: Database,
111
115
  value: string,
112
116
  ): Promise<boolean> {
117
+ // Alias leg (PRD 07 T6b). The identity table sees what the columns cannot:
118
+ // a merged loser's STALE key stays aliased to its live survivor while the
119
+ // loser row is soft-deleted and invisible to the column probe below. Any
120
+ // non-anonymous alias on a live contact names an identified person — reject.
121
+ // (Deliberately stricter than the column leg in one case: an identified
122
+ // contact's email is rejected even when an `external_id` exists.)
123
+ const aliasHit = await db
124
+ .select({ id: contactAliases.id })
125
+ .from(contactAliases)
126
+ .innerJoin(contacts, eq(contacts.id, contactAliases.contactId))
127
+ .where(
128
+ and(
129
+ eq(contactAliases.aliasValue, value),
130
+ ne(contactAliases.aliasKind, "anonymous"),
131
+ isNull(contacts.deletedAt),
132
+ ),
133
+ )
134
+ .limit(1);
135
+ if (aliasHit.length > 0) return true;
136
+
137
+ // Column leg — the unbackfilled-registry backstop. A deployment that
138
+ // upgraded past 0.57 without running `identity-alias-backfill` holds
139
+ // pre-upgrade keys in the columns only; a guard that read aliases alone
140
+ // would fail OPEN there. Keep both legs (PRD 07 re-spec).
113
141
  const rows = await db
114
142
  .select({
115
143
  externalId: contacts.externalId,
@@ -162,6 +190,31 @@ async function keysAnotherContact(
162
190
  value: string,
163
191
  selfId: string,
164
192
  ): Promise<boolean> {
193
+ // Alias leg (PRD 07 T6b). A value claimed by ANOTHER live contact — under
194
+ // any kind — refuses the claim: same-kind re-claims are already blocked by
195
+ // the `(kind, value)` unique index, so what this leg actually stops is the
196
+ // CROSS-kind claim (someone else's key asserted as this caller's
197
+ // `anonymousId`), which is the adoption-theft setup. It also sees a merged
198
+ // loser's stale keys (aliased to the live survivor; the soft-deleted loser
199
+ // row is invisible to the column probe below). The live-contact join keeps
200
+ // the merge arm working: mid-merge, the loser is already soft-deleted, so
201
+ // its own alias rows don't refuse the survivor's claim of its keys.
202
+ const aliasHit = await tx
203
+ .select({ id: contactAliases.id })
204
+ .from(contactAliases)
205
+ .innerJoin(contacts, eq(contacts.id, contactAliases.contactId))
206
+ .where(
207
+ and(
208
+ eq(contactAliases.aliasValue, value),
209
+ ne(contactAliases.contactId, selfId),
210
+ isNull(contacts.deletedAt),
211
+ ),
212
+ )
213
+ .limit(1);
214
+ if (aliasHit.length > 0) return true;
215
+
216
+ // Column leg — the unbackfilled-registry backstop (see
217
+ // `collidesWithIdentified`).
165
218
  const rows = await tx
166
219
  .select({
167
220
  id: contacts.id,
@@ -285,20 +338,26 @@ type Tx = Parameters<Parameters<Database["transaction"]>[0]>[0];
285
338
 
286
339
  type ContactRow = typeof contacts.$inferSelect;
287
340
 
288
- export function contactWhereClause(id: string) {
289
- return UUID_REGEX.test(id)
290
- ? eq(contacts.id, id)
291
- : eq(contacts.externalId, id);
292
- }
293
-
294
341
  export async function resolveContact(opts: { db: Database; id: string }) {
295
342
  const { db, id } = opts;
343
+ // uuid → primary-key read (a merged-away row uuid stays a miss; that arm is
344
+ // a PK read, not an identity probe). Anything else is an EXTERNAL key:
345
+ // column probe first, then the identity table, so a stale (merged-away)
346
+ // external id resolves its SURVIVOR (PRD 07 T7).
347
+ if (UUID_REGEX.test(id)) {
348
+ const rows = await db
349
+ .select()
350
+ .from(contacts)
351
+ .where(and(eq(contacts.id, id), isNull(contacts.deletedAt)))
352
+ .limit(1);
353
+ return rows[0] ?? null;
354
+ }
296
355
  const rows = await db
297
356
  .select()
298
357
  .from(contacts)
299
- .where(and(contactWhereClause(id), isNull(contacts.deletedAt)))
358
+ .where(and(eq(contacts.externalId, id), isNull(contacts.deletedAt)))
300
359
  .limit(1);
301
- return rows[0] ?? null;
360
+ return rows[0] ?? (await resolveViaAlias(db, "external", id));
302
361
  }
303
362
 
304
363
  export interface SerializedContact {
@@ -359,11 +418,18 @@ export function serializePrefs(row: typeof emailPreferences.$inferSelect) {
359
418
  }
360
419
 
361
420
  export function contactSearchFilter(search: string) {
421
+ // The alias leg (PRD 07 T6b) finds a contact by ANY of its historical keys —
422
+ // a merged loser's old email, a second device's anon id — which the one-slot
423
+ // columns cannot. The column legs stay: strictly-more-results, and they are
424
+ // the backstop on a deployment whose alias backfill never ran.
362
425
  return or(
363
426
  ilike(contacts.email, `%${search}%`),
364
427
  ilike(contacts.externalId, `%${search}%`),
365
428
  ilike(contacts.anonymousId, `%${search}%`),
366
429
  ilike(contacts.discordId, `%${search}%`),
430
+ sql`exists (select 1 from ${contactAliases}
431
+ where ${contactAliases.contactId} = ${contacts.id}
432
+ and ${contactAliases.aliasValue} ilike ${`%${search}%`})`,
367
433
  );
368
434
  }
369
435
 
@@ -404,6 +470,11 @@ export function contactSearchFilter(search: string) {
404
470
  * (phone is not yet a merge-participating `Kind`), so a phone-only contact has
405
471
  * no non-anonymous alias row. That leg retires only when phone joins the
406
472
  * identity table.
473
+ *
474
+ * PRD 07 verdict (2026-07-29): the swap is NOT taken. The rescope keeps the
475
+ * columns as written mirrors forever, so these `IS NOT NULL` legs stay exact —
476
+ * and the swap would empty the list on a deployment whose alias backfill never
477
+ * ran, for zero benefit. Revisit only if the columns ever actually die.
407
478
  */
408
479
  export function identifiedContactFilter(): SQL {
409
480
  // `or()` is typed `SQL | undefined` because it tolerates undefined operands.
@@ -804,6 +875,114 @@ export function contactKeySql() {
804
875
  return sql<string>`coalesce(${contacts.externalId}, ${contacts.anonymousId}, ${contacts.id}::text)`;
805
876
  }
806
877
 
878
+ /**
879
+ * The ADOPTION STAMP fragment: `coalesce(<table>.contact_id, :contactId)`.
880
+ *
881
+ * Every statement below that moves a history row's mutable `user_id` string
882
+ * onto an absorbing contact's key ALSO stamps that contact's uuid — so the
883
+ * later read-flip onto `contact_id` leaves no adopted row behind. Two
884
+ * properties make this fragment (rather than a bare `contact_id = :id`) the
885
+ * only correct shape:
886
+ *
887
+ * - SECURITY, not optimization. The `coalesce` is a NULL guard: it stamps only
888
+ * rows nobody owns yet (written while the contact did not exist — the whole
889
+ * point of refusing to mint on observation). A row already carrying ANOTHER
890
+ * contact's id is left alone, so a mis-gated adoption can never re-parent a
891
+ * second person's history even if it does move the string key.
892
+ * - It must ride IN the same UPDATE that rewrites `user_id`. A separate stamp
893
+ * statement afterwards matches zero rows — the key it would filter on has
894
+ * already moved — and one before it would need its own scan of the old key.
895
+ *
896
+ * Idempotent by construction: re-running an adoption finds `contact_id` already
897
+ * non-NULL and changes nothing.
898
+ *
899
+ * The `::uuid` cast pins the bound parameter's type the way {@link
900
+ * contactKeySql}'s `::text` does; without it the param arrives untyped and
901
+ * Postgres has to infer it from the coalesce.
902
+ */
903
+ function adoptedContactId(column: Column, contactId: string): SQL<string> {
904
+ return sql<string>`coalesce(${column}, ${contactId}::uuid)`;
905
+ }
906
+
907
+ /**
908
+ * How a fold writes its routed rows (PRD 05 T9, narrowed by PRD 07 T7).
909
+ *
910
+ * `user_id` is frozen at its write-time value in BOTH modes — reads no longer
911
+ * consult it, and D9 keeps writing it on inserts. What differs is the stamp:
912
+ *
913
+ * - Merge mode (default): stamp `contact_id` under the {@link adoptedContactId}
914
+ * NULL guard (loser-OWNED rows are re-pointed wholesale by the merge's
915
+ * (vi-b-hist) statements, never here) and denormalize the survivor's email
916
+ * where the table carries one.
917
+ * - `stampOnly` (the adoption path): a plain one-column stamp. The loser scope
918
+ * is `orphansOnly` (see {@link foldScopes}), so every matched row carries
919
+ * `contact_id IS NULL` and the stamp cannot re-parent another person's
920
+ * history.
921
+ */
922
+ interface FoldWriteOpts {
923
+ stampOnly?: boolean;
924
+ }
925
+
926
+ /**
927
+ * PRD 05 T3 — "which rows belong to the loser, and which to the survivor", for
928
+ * the three folds below.
929
+ *
930
+ * Migration 0071 adds a CONTACT-scoped partial unique index to `journey_states`,
931
+ * `bucket_memberships` and `email_preferences`. That makes a string-key-only
932
+ * fold unsafe: adoption stamps `contact_id` WITHOUT rewriting `user_id`, so a
933
+ * row the SURVIVOR already owns can sit under a stale key. A fold that looked
934
+ * only at `user_id = survivorKey` would not see it, would call the slot free,
935
+ * and would re-point (or NULL-stamp) a loser row into a second row satisfying
936
+ * the new index — a 23505 raised inside `resolveContact`'s transaction with no
937
+ * handler, which wedges identity resolution for that person permanently (every
938
+ * retry fails identically). So ownership is asked BOTH ways, `user_id` and
939
+ * `contact_id`.
940
+ *
941
+ * `loserId` is the mirror on the other side and is supplied only by the merge
942
+ * path: the adoption path ({@link adoptOrphanHistory}) folds history onto the
943
+ * contact that already owns its key, where the "loser" rows would carry that
944
+ * same `contact_id` and matching on it would swallow the whole contact. The
945
+ * loser test wins the tie — a row is either being adopted or being folded
946
+ * into, never both.
947
+ *
948
+ * `orphansOnly` (the adoption path, PRD 05 T9): the loser side additionally
949
+ * requires `contact_id IS NULL`. This predicate is the anti-theft guard that
950
+ * replaced `keysAnotherContact`'s adoption-gating role — a row another contact
951
+ * owns already carries that owner's id and can never match, so adoption
952
+ * cannot re-parent a second person's history. Never combined with `loserId`
953
+ * (only the merge path supplies one).
954
+ */
955
+ function foldScopes(opts: {
956
+ userIdCol: Column;
957
+ contactIdCol: Column;
958
+ survivorKey: string;
959
+ survivorId: string;
960
+ loserKeys: string[];
961
+ loserId?: string;
962
+ orphansOnly?: boolean;
963
+ }): { isLoser: SQL; isSurvivor: SQL } {
964
+ // `IS NOT DISTINCT FROM`, never `=`. `contact_id` is nullable, and a plain
965
+ // equality against a NULL column is UNKNOWN, not false — which `NOT (… OR
966
+ // UNKNOWN)` then swallows, silently dropping EVERY contactless row out of the
967
+ // survivor set. That is the occupancy the folds dedupe against, so the folds
968
+ // would stop seeing the rows they exist to protect.
969
+ const sameContact = (id: string): SQL =>
970
+ sql`${opts.contactIdCol} IS NOT DISTINCT FROM ${id}::uuid`;
971
+
972
+ const byKey = opts.orphansOnly
973
+ ? (and(
974
+ inArray(opts.userIdCol, opts.loserKeys),
975
+ isNull(opts.contactIdCol),
976
+ ) as SQL)
977
+ : inArray(opts.userIdCol, opts.loserKeys);
978
+ const isLoser = opts.loserId ? or(byKey, sameContact(opts.loserId)) : byKey;
979
+ const isSurvivor = and(
980
+ or(eq(opts.userIdCol, opts.survivorKey), sameContact(opts.survivorId)),
981
+ not(isLoser as SQL),
982
+ );
983
+ return { isLoser: isLoser as SQL, isSurvivor: isSurvivor as SQL };
984
+ }
985
+
807
986
  /**
808
987
  * The identity keys + options EVERY resolve entry point accepts. Named (rather
809
988
  * than inline) so {@link resolveOrCreateContact} and {@link
@@ -1106,35 +1285,36 @@ async function resolveContactShared(
1106
1285
 
1107
1286
  // HISTORY ADOPTION (D2). Once observation stops minting a row, a later
1108
1287
  // identify no longer finds an anon contact to fill-in-link — it lands
1109
- // HERE, in the create arm, which historically had no repoint. Everything
1110
- // already keyed on the anon id (user_events, journey_states,
1111
- // bucket_memberships, email_sends, email_preferences — incl. an
1112
- // unsubscribe) would be silently orphaned under a key no contact owns.
1288
+ // HERE, in the create arm. Everything already keyed on the anon id
1289
+ // (user_events, journey_states, bucket_memberships, email_sends,
1290
+ // email_preferences — incl. an unsubscribe) would otherwise be silently
1291
+ // orphaned under a key no contact owns.
1113
1292
  //
1114
- // So: when the brand-new row's canonical key (`external_id ??
1115
- // anonymous_id ?? id`) is NOT the supplied `anonymousId`, the anon key was
1116
- // just superseded — re-point its history exactly as `fillInLink` does on a
1117
- // key flip. Only ever FROM `anonymousId`: an email/discord-shaped key is
1118
- // never canonical, so it never keyed history and must never be repointed.
1119
- //
1120
- // Gated on `keysAnotherContact`: resolution missed this value in the
1121
- // ANONYMOUS namespace, which does not mean nobody owns it. If it is some
1122
- // other live contact's canonical key, those rows are theirs and adopting
1123
- // them here would hand one person's history to another.
1293
+ // Adoption is self-gating (T9): `adoptOrphanHistory` touches only
1294
+ // `contact_id IS NULL` rows, so a value that is some other live
1295
+ // contact's key cannot surrender their history — those rows carry their
1296
+ // owner's id. `keysAnotherContact` therefore no longer gates adoption;
1297
+ // it survives below ONLY to gate the `mergedKeys` REPORT — a foreign
1298
+ // anon id must never enter the analytics stitch.
1124
1299
  const createdKey = contactKey(createdRow);
1300
+ // History written under the row's OWN key BEFORE it existed. Not a
1301
+ // merge: no key is absorbed, so it reports nothing in `mergedKeys` and
1302
+ // fires no analytics stitch.
1303
+ await adoptOrphanHistory(tx, createdKey, createdRow);
1125
1304
  let mergedKeys: string[] | undefined;
1126
- if (
1127
- anonymousId &&
1128
- anonymousId !== createdKey &&
1129
- !(await keysAnotherContact(tx, anonymousId, createdRow.id))
1130
- ) {
1131
- await repointOwnHistory(tx, anonymousId, createdKey, createdRow);
1132
- // §5.3 emission point 2 (canonical-key flip): report the absorbed anon
1133
- // key so `ingestEvent` still fires `mergeAnalyticsIdentities({ reason:
1134
- // "key_flip" })` — otherwise the DB history is adopted but the PostHog
1135
- // anon→known stitch stays broken. Safe to alias by construction (an
1136
- // anonymous key never identified a person — MF-2).
1137
- mergedKeys = [anonymousId];
1305
+ if (anonymousId && anonymousId !== createdKey) {
1306
+ // The anon key was just superseded as canonical — stamp its orphans.
1307
+ // Only ever FROM `anonymousId`: an email/discord-shaped key is never
1308
+ // canonical, so it never keyed history.
1309
+ await adoptOrphanHistory(tx, anonymousId, createdRow);
1310
+ if (!(await keysAnotherContact(tx, anonymousId, createdRow.id))) {
1311
+ // §5.3 emission point 2 (canonical-key flip): report the absorbed
1312
+ // anon key so `ingestEvent` still fires `mergeAnalyticsIdentities({
1313
+ // reason: "key_flip" })` — otherwise the DB history is adopted but
1314
+ // the PostHog anon→known stitch stays broken. Safe to alias by
1315
+ // construction (an anonymous key never identified a person — MF-2).
1316
+ mergedKeys = [anonymousId];
1317
+ }
1138
1318
  }
1139
1319
 
1140
1320
  return {
@@ -1495,9 +1675,9 @@ async function fillInLink(
1495
1675
 
1496
1676
  await tx.update(contacts).set(set).where(eq(contacts.id, row.id));
1497
1677
 
1498
- // Re-point the contact's own history if the canonical key flipped. The
1499
- // updated row (with its new email/keys) is what foldJourneyStates/email_sends
1500
- // denormalize into.
1678
+ // Adopt the contact's own orphan history (stamp-only since T9; nothing
1679
+ // rewrites the string key anymore). The updated row carries the post-fill
1680
+ // keys the fold scopes resolve ownership with.
1501
1681
  const newKey = nextExternalId ?? nextAnonymousId ?? row.id;
1502
1682
  // §5.3 emission point 2 (canonical-key flip): when the key flips, the OLD key
1503
1683
  // is folded into the NEW one. MF-3 gate — only emit a merge when `oldKey` was
@@ -1518,9 +1698,12 @@ async function fillInLink(
1518
1698
 
1519
1699
  let mergedKeys: string[] | undefined;
1520
1700
  let mergedIdentifiedKeys: string[] | undefined;
1701
+ // T9: adoption is unconditional — with nothing keyed on the canonical key,
1702
+ // "did the key flip" no longer decides whether history is stamped. Orphans
1703
+ // under the pre-fill key are adopted either way (idempotent when there are
1704
+ // none); the flip test now gates only the analytics REPORT.
1705
+ await adoptOrphanHistory(tx, oldKey, updatedRow);
1521
1706
  if (newKey !== oldKey) {
1522
- await repointOwnHistory(tx, oldKey, newKey, updatedRow);
1523
-
1524
1707
  const oldKeyWasExternalId =
1525
1708
  row.externalId != null && oldKey === row.externalId;
1526
1709
  if (oldKeyWasExternalId) {
@@ -1568,7 +1751,7 @@ async function fillInLink(
1568
1751
  for (const key of claimed) {
1569
1752
  if (key.kind !== "anonymous") continue;
1570
1753
  if (key.value === newKey || key.value === oldKey) continue;
1571
- await repointOwnHistory(tx, key.value, newKey, updatedRow);
1754
+ await adoptOrphanHistory(tx, key.value, updatedRow);
1572
1755
  // Reported so `mergeAnalyticsIdentities` still fires the anon→known stitch;
1573
1756
  // appended, since a key flip above may already have folded a uuid/anon key.
1574
1757
  mergedKeys = [...(mergedKeys ?? []), key.value];
@@ -1610,12 +1793,11 @@ async function mergeContacts(
1610
1793
  const identifiedLoserKeys: string[] = [];
1611
1794
 
1612
1795
  for (const loser of losers) {
1796
+ // The id is the last-resort key for a loser that has neither external nor
1797
+ // anonymous id (its user_id rows were keyed on contacts.id).
1613
1798
  const loserStrKeys = [loser.externalId, loser.anonymousId, loser.id].filter(
1614
1799
  (k): k is string => Boolean(k),
1615
1800
  );
1616
- // The id is the last-resort key for a loser that has neither external nor
1617
- // anonymous id (its user_id rows were keyed on contacts.id).
1618
- const loserKeysToRewrite = loserStrKeys;
1619
1801
 
1620
1802
  // MF-2 split: the SAFE-to-absorb key is the loser's anonymous/uuid key —
1621
1803
  // `loser.anonymousId`, or `loser.id` ONLY when the loser was never
@@ -1630,40 +1812,64 @@ async function mergeContacts(
1630
1812
  safeLoserKeys.push(loser.anonymousId ?? loser.id);
1631
1813
  }
1632
1814
 
1633
- // (ii) user_events.user_id rewrite.
1815
+ // (ii) user_events `contact_id` stamp — the ADOPTION half only (NULL rows:
1816
+ // history the loser's keys accumulated before any contact existed). PRD 07
1817
+ // T7 deleted the paired `user_id` rewrite: the key stays frozen at its
1818
+ // write-time value and ownership rides the FK. Rows already owned by the
1819
+ // LOSER keep `loser.id` here and are re-pointed wholesale by (vi-b-hist)
1820
+ // below, which is the one statement that may overwrite a non-NULL owner.
1821
+ // Splitting it that way keeps a single rule in the fragment (never take a
1822
+ // row from another contact) and one explicit, auditable place where a
1823
+ // merge does.
1634
1824
  await tx
1635
1825
  .update(userEvents)
1636
- .set({ userId: survivorKey })
1637
- .where(inArray(userEvents.userId, loserKeysToRewrite));
1826
+ .set({
1827
+ contactId: adoptedContactId(userEvents.contactId, survivor.id),
1828
+ })
1829
+ .where(inArray(userEvents.userId, loserStrKeys));
1638
1830
 
1639
1831
  // (iii) journey_states — exit the loser's duplicate active/waiting row when
1640
1832
  // the survivor already holds an active/waiting row in the same journey
1641
1833
  // (respect uq_user_journey_active), THEN rewrite user_id/user_email.
1642
- await foldJourneyStates(tx, survivorKey, loserKeysToRewrite, survivor);
1834
+ await foldJourneyStates(tx, survivorKey, loserStrKeys, survivor, loser.id);
1643
1835
 
1644
- // (iv) email_sends rewrite user_id + userEmail to survivor's.
1836
+ // (iv) email_sends: `contact_id` stamp (NULL-guarded, as (ii)) + the
1837
+ // userEmail denorm. `user_id` frozen (PRD 07 T7); the address denorm still
1838
+ // updates because it feeds person-level send history, not identity.
1645
1839
  await tx
1646
1840
  .update(emailSends)
1647
1841
  .set({
1648
- userId: survivorKey,
1842
+ contactId: adoptedContactId(emailSends.contactId, survivor.id),
1649
1843
  ...(survivor.email ? { userEmail: survivor.email } : {}),
1650
1844
  })
1651
- .where(inArray(emailSends.userId, loserKeysToRewrite));
1845
+ .where(inArray(emailSends.userId, loserStrKeys));
1652
1846
 
1653
1847
  // (v) bucket_memberships — soft-leave the loser's duplicate active
1654
1848
  // membership when the survivor already holds one in the same bucket (respect
1655
1849
  // uq_user_bucket_active, preserve survivor's dwell clock), THEN rewrite.
1656
- await foldBucketMemberships(tx, survivorKey, loserKeysToRewrite);
1850
+ await foldBucketMemberships(
1851
+ tx,
1852
+ survivorKey,
1853
+ loserStrKeys,
1854
+ survivor.id,
1855
+ loser.id,
1856
+ );
1657
1857
 
1658
1858
  // (vi) email_preferences FOLD (never blind-rewrite — risk 6).
1659
- await foldEmailPreferences(tx, loserKeysToRewrite, survivorKey);
1859
+ await foldEmailPreferences(
1860
+ tx,
1861
+ loserStrKeys,
1862
+ survivorKey,
1863
+ survivor.id,
1864
+ loser.id,
1865
+ );
1660
1866
 
1661
1867
  // (vi-b) deals + crm_links re-point: these carry contact_id uuid FKs
1662
1868
  // (not user keys), which the key rewrites above never touch. Without
1663
1869
  // this, the loser's open deal is orphaned on a soft-deleted row — the
1664
1870
  // survivor's next stage event/trigger would mint a SECOND deal (and a
1665
- // duplicate deal.sold). No unique index involves contact_id, so plain
1666
- // UPDATEs suffice.
1871
+ // duplicate deal.sold). Neither table has a unique index on contact_id,
1872
+ // so plain UPDATEs suffice.
1667
1873
  await tx
1668
1874
  .update(deals)
1669
1875
  .set({ contactId: survivor.id })
@@ -1674,15 +1880,32 @@ async function mergeContacts(
1674
1880
  .where(eq(crmLinks.contactId, loser.id));
1675
1881
 
1676
1882
  // (vi-b-hist) the five HISTORY tables' `contact_id` re-point (PRD 04 T3).
1677
- // Same shape and same reasoning as the deals/crm_links repoints above: a
1678
- // uuid column the string-key rewrites never touch, and no unique index
1679
- // involves `contact_id`, so plain UPDATEs suffice (no fold needed — unlike
1680
- // the (vi)/(vi-c) folds, which exist only to respect a unique index).
1883
+ // Same shape as the deals/crm_links repoints above: a uuid column the
1884
+ // key stamps above never touch.
1885
+ //
1886
+ // PRD 05 T3: `contact_id` IS now a unique-index column on three of these
1887
+ // five (migration 0071), so "plain UPDATEs suffice" is no longer true on its
1888
+ // own — it holds only because the folds above ran FIRST and already know
1889
+ // about `contact_id`. {@link foldScopes} makes each fold read the survivor's
1890
+ // occupancy AND the loser's rows by `user_id` OR `contact_id`, so by the
1891
+ // time these statements run, every loser row that would have duplicated a
1892
+ // survivor row inside a contact-scoped index has been exited, left or
1893
+ // deleted. That is the invariant these three statements depend on; widen a
1894
+ // fold's scope, never this.
1681
1895
  // Deliberately lands AHEAD of the dual-write that populates the column
1682
1896
  // (PRD 04 D9/D10): while every row is still NULL this is a pure no-op, and
1683
1897
  // the moment the dual-write starts, merges are already correct. Shipped in
1684
1898
  // the other order, every merge in between would strand history rows
1685
1899
  // pointing at a soft-deleted loser contact.
1900
+ //
1901
+ // It is also the OVERWRITE half of the stamps above: those touch only
1902
+ // rows nobody owned (the {@link adoptedContactId} NULL guard), so the
1903
+ // loser-OWNED rows arrive here still carrying `loser.id` and this is what
1904
+ // moves them. Between the two halves, every row the merge folds carries
1905
+ // the survivor's uuid while `user_id` stays frozen at its write-time
1906
+ // value (PRD 07 T7). Runs after the stamps rather than before because it
1907
+ // filters on `contact_id`, not `user_id`, and re-running the pair changes
1908
+ // nothing (`contact_id = loser.id` matches zero rows twice).
1686
1909
  await tx
1687
1910
  .update(userEvents)
1688
1911
  .set({ contactId: survivor.id })
@@ -1867,11 +2090,10 @@ async function mergeContacts(
1867
2090
  await ensureIdentityAliases(tx, postSurvivor);
1868
2091
 
1869
2092
  // If the survivor's canonical key flipped (it had no external_id/anonymous_id
1870
- // and the merge promoted one from the call/loser), re-point the survivor's OWN
1871
- // history — including everything the loser rewrites just pointed at the old
1872
- // survivorKey — onto the new key (risk 1). Without this, a survivor whose
1873
- // history was keyed on its uuid/anonymous_id is orphaned the moment it gains
1874
- // an external_id mid-merge.
2093
+ // and the merge promoted one from the call/loser), stamp any orphans still
2094
+ // sitting under the OLD survivor key (risk 1). The loser folds above already
2095
+ // stamped everything they routed, so this reaches only rows that predate the
2096
+ // survivor's own contact_id era.
1875
2097
  const newSurvivorKey =
1876
2098
  (survivorSet.externalId as string | undefined) ??
1877
2099
  survivor.externalId ??
@@ -1887,7 +2109,7 @@ async function mergeContacts(
1887
2109
  (survivorSet.anonymousId as string | undefined) ?? survivor.anonymousId,
1888
2110
  email: (survivorSet.email as string | undefined) ?? survivor.email,
1889
2111
  };
1890
- await repointOwnHistory(tx, survivorKey, newSurvivorKey, updatedSurvivor);
2112
+ await adoptOrphanHistory(tx, survivorKey, updatedSurvivor);
1891
2113
  }
1892
2114
 
1893
2115
  // `newSurvivorKey` IS the post-merge canonical key of the survivor — the same
@@ -1911,43 +2133,56 @@ async function mergeContacts(
1911
2133
  * the survivor key still collides whenever the survivor already holds a live row
1912
2134
  * for that journey.
1913
2135
  *
1914
- * Fix: build the survivor's occupied (journey_id|status) set over ALL statuses.
1915
- * For active/waiting collisions, EXIT the loser's row first (preserve the
2136
+ * Fix: build the survivor's occupancy and route each loser row to exit / delete /
2137
+ * rewrite. For a LIVE collision, EXIT the loser's row first (preserve the
1916
2138
  * survivor's live run) so the rewrite lands an 'exited' (out-of-predicate) row.
1917
- * For any OTHER collision (terminal), DELETE the loser's duplicate — no longer
1918
- * REQUIRED by the constraint (terminal rows are outside the predicate), but kept
1919
- * as hygiene so the survivor doesn't carry two identical terminal rows (which
1920
- * would inflate the count()-based ctx.history.journey.entryCount). Rewrite only
1921
- * the non-colliding remainder onto the survivor key (+ survivor email). Re-check
2139
+ * For a TERMINAL collision, DELETE the loser's duplicate — no longer REQUIRED by
2140
+ * the constraint (terminal rows are outside the predicate), but kept as hygiene
2141
+ * so the survivor doesn't carry two identical terminal rows (which would inflate
2142
+ * the count()-based ctx.history.journey.entryCount). Rewrite only the
2143
+ * non-colliding remainder onto the survivor key (+ survivor email). Re-check
1922
2144
  * 'exited' occupancy after exiting so a just-exited loser row that would now
1923
2145
  * duplicate a pre-existing survivor 'exited' row is dropped rather than rewritten.
2146
+ *
2147
+ * Occupancy is asked BOTH ways (see {@link foldScopes}), and LIVE occupancy is
2148
+ * keyed on the journey ALONE: both unique indexes say `status IN ('active',
2149
+ * 'waiting')`, i.e. the two live statuses share ONE slot, so a survivor 'active'
2150
+ * row and a loser 'waiting' row in the same journey collide even though their
2151
+ * (journey|status) pairs differ.
1924
2152
  */
1925
2153
  async function foldJourneyStates(
1926
2154
  tx: Tx,
1927
2155
  survivorKey: string,
1928
2156
  loserKeys: string[],
1929
2157
  survivor: ContactRow,
2158
+ loserId?: string,
2159
+ opts?: FoldWriteOpts,
1930
2160
  ): Promise<void> {
1931
2161
  const ACTIVE = new Set<string>(["active", "waiting"]);
2162
+ const { isLoser, isSurvivor } = foldScopes({
2163
+ userIdCol: journeyStates.userId,
2164
+ contactIdCol: journeyStates.contactId,
2165
+ survivorKey,
2166
+ survivorId: survivor.id,
2167
+ loserKeys,
2168
+ loserId,
2169
+ orphansOnly: opts?.stampOnly,
2170
+ });
1932
2171
 
1933
- // Every (journey_id|status) pair the survivor already holds (ALL statuses).
1934
2172
  const survivorRows = await tx
1935
2173
  .select({
1936
2174
  journeyId: journeyStates.journeyId,
1937
2175
  status: journeyStates.status,
1938
2176
  })
1939
2177
  .from(journeyStates)
1940
- .where(
1941
- and(
1942
- eq(journeyStates.userId, survivorKey),
1943
- isNull(journeyStates.deletedAt),
1944
- ),
1945
- );
1946
- // Running occupied set — mutated as we exit/rewrite loser rows so two loser
1947
- // rows in the same journey/status (3-way merge) can't collide with each other.
1948
- const occupied = new Set(
1949
- survivorRows.map((s) => `${s.journeyId}|${s.status}`),
2178
+ .where(and(isSurvivor, isNull(journeyStates.deletedAt)));
2179
+
2180
+ // Both sets are mutated as loser rows are routed, so two loser rows from
2181
+ // different keys (3-way merge) can't collide with each other either.
2182
+ const live = new Set(
2183
+ survivorRows.filter((s) => ACTIVE.has(s.status)).map((s) => s.journeyId),
1950
2184
  );
2185
+ const slots = new Set(survivorRows.map((s) => `${s.journeyId}|${s.status}`));
1951
2186
 
1952
2187
  const loserRows = await tx
1953
2188
  .select({
@@ -1956,41 +2191,39 @@ async function foldJourneyStates(
1956
2191
  status: journeyStates.status,
1957
2192
  })
1958
2193
  .from(journeyStates)
1959
- .where(
1960
- and(
1961
- inArray(journeyStates.userId, loserKeys),
1962
- isNull(journeyStates.deletedAt),
1963
- ),
1964
- );
2194
+ .where(and(isLoser, isNull(journeyStates.deletedAt)));
1965
2195
 
1966
2196
  const idsToExit: string[] = [];
1967
2197
  const idsToDelete: string[] = [];
1968
2198
  const idsToRewrite: string[] = [];
1969
2199
 
1970
2200
  for (const l of loserRows) {
1971
- const key = `${l.journeyId}|${l.status}`;
1972
- if (occupied.has(key)) {
1973
- if (ACTIVE.has(l.status)) {
1974
- // Survivor (or a prior loser) already holds a live row in this
1975
- // journey/status — exit the loser's so the live run continues. Only do
1976
- // so if the resulting 'exited' slot is itself free; otherwise drop it.
1977
- const exitedKey = `${l.journeyId}|exited`;
1978
- if (occupied.has(exitedKey)) {
1979
- idsToDelete.push(l.id);
1980
- } else {
1981
- idsToExit.push(l.id);
1982
- occupied.add(exitedKey);
1983
- }
1984
- } else {
1985
- // Terminal collision (both completed/failed/exited the same journey) —
1986
- // the survivor already records this state; drop the loser duplicate.
2201
+ const slot = `${l.journeyId}|${l.status}`;
2202
+ if (ACTIVE.has(l.status)) {
2203
+ if (!live.has(l.journeyId)) {
2204
+ // The one live slot for this journey is free — claim it.
2205
+ idsToRewrite.push(l.id);
2206
+ live.add(l.journeyId);
2207
+ slots.add(slot);
2208
+ continue;
2209
+ }
2210
+ // Survivor (or a prior loser) already holds the live slot — exit the
2211
+ // loser's row so the live run continues. Only do so if the resulting
2212
+ // 'exited' slot is itself free; otherwise drop it.
2213
+ const exitedSlot = `${l.journeyId}|exited`;
2214
+ if (slots.has(exitedSlot)) {
1987
2215
  idsToDelete.push(l.id);
2216
+ } else {
2217
+ idsToExit.push(l.id);
2218
+ slots.add(exitedSlot);
1988
2219
  }
2220
+ } else if (slots.has(slot)) {
2221
+ // Terminal collision (both completed/failed/exited the same journey) —
2222
+ // the survivor already records this state; drop the loser duplicate.
2223
+ idsToDelete.push(l.id);
1989
2224
  } else {
1990
- // Free slot — rewrite onto the survivor key. Claim it so a sibling loser
1991
- // row in the same journey/status routes to exit/delete instead.
1992
2225
  idsToRewrite.push(l.id);
1993
- occupied.add(key);
2226
+ slots.add(slot);
1994
2227
  }
1995
2228
  }
1996
2229
 
@@ -2007,17 +2240,28 @@ async function foldJourneyStates(
2007
2240
  .where(inArray(journeyStates.id, idsToExit));
2008
2241
  }
2009
2242
 
2010
- // Rewrite both the originally non-colliding rows AND the just-exited rows onto
2011
- // the survivor key (the exited rows now sit in claimed-free 'exited' slots).
2243
+ // Route both the originally non-colliding rows AND the just-exited rows to
2244
+ // the survivor (the exited rows now sit in claimed-free 'exited' slots).
2245
+ // Stamp mode (adoption, PRD 05 T9): one column — every matched row is an
2246
+ // orphan (`orphansOnly` scope), so a plain stamp cannot re-parent anything.
2247
+ // The string key and denormalized email stay frozen at write-time values.
2012
2248
  const rewriteIds = [...idsToRewrite, ...idsToExit];
2013
2249
  if (rewriteIds.length > 0) {
2014
2250
  await tx
2015
2251
  .update(journeyStates)
2016
- .set({
2017
- userId: survivorKey,
2018
- ...(survivor.email ? { userEmail: survivor.email } : {}),
2019
- updatedAt: new Date(),
2020
- })
2252
+ .set(
2253
+ opts?.stampOnly
2254
+ ? { contactId: survivor.id, updatedAt: new Date() }
2255
+ : {
2256
+ // PRD 07 T7: `user_id` is FROZEN in merge mode too — ownership
2257
+ // moves on the FK (NULL-guarded here; loser-owned rows re-point
2258
+ // in (vi-b-hist)). The email denorm still updates: it is the
2259
+ // live send address for a re-pointed run, not an identity key.
2260
+ contactId: adoptedContactId(journeyStates.contactId, survivor.id),
2261
+ ...(survivor.email ? { userEmail: survivor.email } : {}),
2262
+ updatedAt: new Date(),
2263
+ },
2264
+ )
2021
2265
  .where(inArray(journeyStates.id, rewriteIds));
2022
2266
  }
2023
2267
  }
@@ -2027,18 +2271,35 @@ async function foldJourneyStates(
2027
2271
  * a bucket where a loser key also holds one, soft-LEAVE the loser's row first
2028
2272
  * (uq_user_bucket_active forbids two active rows for the same (user, bucket);
2029
2273
  * preserve the survivor's dwell clock), then rewrite the rest onto the survivor.
2274
+ *
2275
+ * `survivorId` is the absorbing contact's uuid — the soft-left rows are rewritten
2276
+ * by the same statement as the rest, so both halves of a folded pair leave here
2277
+ * carrying it (see {@link adoptedContactId} for the NULL guard).
2030
2278
  */
2031
2279
  async function foldBucketMemberships(
2032
2280
  tx: Tx,
2033
2281
  survivorKey: string,
2034
2282
  loserKeys: string[],
2283
+ survivorId: string,
2284
+ loserId?: string,
2285
+ opts?: FoldWriteOpts,
2035
2286
  ): Promise<void> {
2287
+ const { isLoser, isSurvivor } = foldScopes({
2288
+ userIdCol: bucketMemberships.userId,
2289
+ contactIdCol: bucketMemberships.contactId,
2290
+ survivorKey,
2291
+ survivorId,
2292
+ loserKeys,
2293
+ loserId,
2294
+ orphansOnly: opts?.stampOnly,
2295
+ });
2296
+
2036
2297
  const survivorActive = await tx
2037
2298
  .select({ bucketId: bucketMemberships.bucketId })
2038
2299
  .from(bucketMemberships)
2039
2300
  .where(
2040
2301
  and(
2041
- eq(bucketMemberships.userId, survivorKey),
2302
+ isSurvivor,
2042
2303
  eq(bucketMemberships.status, "active"),
2043
2304
  isNull(bucketMemberships.deletedAt),
2044
2305
  ),
@@ -2053,15 +2314,19 @@ async function foldBucketMemberships(
2053
2314
  .from(bucketMemberships)
2054
2315
  .where(
2055
2316
  and(
2056
- inArray(bucketMemberships.userId, loserKeys),
2317
+ isLoser,
2057
2318
  eq(bucketMemberships.status, "active"),
2058
2319
  isNull(bucketMemberships.deletedAt),
2059
2320
  ),
2060
2321
  );
2061
2322
 
2062
- const idsToLeave = loserActive
2063
- .filter((l) => occupied.has(l.bucketId))
2064
- .map((l) => l.id);
2323
+ // Claim as we go, so two loser rows active in the SAME bucket (3-way merge)
2324
+ // route the second to 'left' instead of both rewriting onto the survivor.
2325
+ const idsToLeave: string[] = [];
2326
+ for (const l of loserActive) {
2327
+ if (occupied.has(l.bucketId)) idsToLeave.push(l.id);
2328
+ else occupied.add(l.bucketId);
2329
+ }
2065
2330
 
2066
2331
  if (idsToLeave.length > 0) {
2067
2332
  await tx
@@ -2072,8 +2337,19 @@ async function foldBucketMemberships(
2072
2337
 
2073
2338
  await tx
2074
2339
  .update(bucketMemberships)
2075
- .set({ userId: survivorKey, updatedAt: new Date() })
2076
- .where(inArray(bucketMemberships.userId, loserKeys));
2340
+ .set(
2341
+ opts?.stampOnly
2342
+ ? { contactId: survivorId, updatedAt: new Date() }
2343
+ : {
2344
+ // PRD 07 T7: `user_id` frozen in merge mode (see foldJourneyStates).
2345
+ contactId: adoptedContactId(
2346
+ bucketMemberships.contactId,
2347
+ survivorId,
2348
+ ),
2349
+ updatedAt: new Date(),
2350
+ },
2351
+ )
2352
+ .where(isLoser);
2077
2353
  }
2078
2354
 
2079
2355
  /**
@@ -2127,18 +2403,35 @@ async function foldGroupMemberships(
2127
2403
  * 3-way merge where two losers each carry a pref for the SAME email folds
2128
2404
  * loser2 into loser1's already-folded result instead of colliding on
2129
2405
  * `uq(user_id, email)` (risk 3). The loser row is deleted after folding.
2406
+ *
2407
+ * This is the one fold whose SURVIVING row is not the row that moved — a
2408
+ * collision keeps the TARGET and deletes the loser — so `survivorId` is stamped
2409
+ * on both branches: onto the re-pointed row when the slot is free, and onto the
2410
+ * target as part of the fold write when it is not. Same NULL guard either way
2411
+ * (see {@link adoptedContactId}); the fold branch expresses it in TS because the
2412
+ * target row is already in hand.
2130
2413
  */
2131
2414
  async function foldEmailPreferences(
2132
2415
  tx: Tx,
2133
2416
  loserKeys: string[],
2134
2417
  survivorKey: string,
2418
+ survivorId: string,
2419
+ loserId?: string,
2420
+ opts?: FoldWriteOpts,
2135
2421
  ): Promise<void> {
2136
2422
  if (loserKeys.length === 0) return;
2137
2423
 
2138
- const loserPrefs = await tx
2139
- .select()
2140
- .from(emailPreferences)
2141
- .where(inArray(emailPreferences.userId, loserKeys));
2424
+ const { isLoser, isSurvivor } = foldScopes({
2425
+ userIdCol: emailPreferences.userId,
2426
+ contactIdCol: emailPreferences.contactId,
2427
+ survivorKey,
2428
+ survivorId,
2429
+ loserKeys,
2430
+ loserId,
2431
+ orphansOnly: opts?.stampOnly,
2432
+ });
2433
+
2434
+ const loserPrefs = await tx.select().from(emailPreferences).where(isLoser);
2142
2435
 
2143
2436
  if (loserPrefs.length === 0) return;
2144
2437
 
@@ -2149,25 +2442,36 @@ async function foldEmailPreferences(
2149
2442
  };
2150
2443
 
2151
2444
  for (const lp of loserPrefs) {
2152
- // Re-read the CURRENT target row for (survivorKey, lp.email) — it may be the
2153
- // original survivor pref, a prior loser's just-folded pref, or absent.
2445
+ // Re-read the CURRENT target row for this address — it may be the original
2446
+ // survivor pref, a survivor row adoption stamped under a STALE key, a prior
2447
+ // loser's just-folded pref, or absent. A stamped row is preferred when both
2448
+ // exist: it is the row the contact-scoped read resolves, and the row whose
2449
+ // uniqueness a re-point would violate.
2154
2450
  const targetRows = await tx
2155
2451
  .select()
2156
2452
  .from(emailPreferences)
2157
- .where(
2158
- and(
2159
- eq(emailPreferences.userId, survivorKey),
2160
- eq(emailPreferences.email, lp.email),
2161
- ),
2162
- )
2453
+ .where(and(isSurvivor, eq(emailPreferences.email, lp.email)))
2454
+ .orderBy(sql`${emailPreferences.contactId} IS NULL`)
2163
2455
  .limit(1);
2164
2456
  const target = targetRows[0];
2165
2457
 
2166
2458
  if (!target) {
2167
- // The (survivorKey, lp.email) slot is free — re-point the loser row.
2459
+ // The slot is free on BOTH keys. Both modes stamp ownership only (PRD 07
2460
+ // T7: `user_id` frozen in merge mode too); merge mode NULL-guards the
2461
+ // stamp, stamp mode's rows are orphans by scope so a plain stamp is safe.
2168
2462
  await tx
2169
2463
  .update(emailPreferences)
2170
- .set({ userId: survivorKey, updatedAt: new Date() })
2464
+ .set(
2465
+ opts?.stampOnly
2466
+ ? { contactId: survivorId, updatedAt: new Date() }
2467
+ : {
2468
+ contactId: adoptedContactId(
2469
+ emailPreferences.contactId,
2470
+ survivorId,
2471
+ ),
2472
+ updatedAt: new Date(),
2473
+ },
2474
+ )
2171
2475
  .where(eq(emailPreferences.id, lp.id));
2172
2476
  continue;
2173
2477
  }
@@ -2193,6 +2497,7 @@ async function foldEmailPreferences(
2193
2497
  categories: foldedCategories,
2194
2498
  suppressedAt: earliest(target.suppressedAt, lp.suppressedAt),
2195
2499
  lastBounceAt: earliest(target.lastBounceAt, lp.lastBounceAt),
2500
+ contactId: target.contactId ?? survivorId,
2196
2501
  updatedAt: new Date(),
2197
2502
  })
2198
2503
  .where(eq(emailPreferences.id, target.id));
@@ -2204,48 +2509,68 @@ async function foldEmailPreferences(
2204
2509
  }
2205
2510
 
2206
2511
  /**
2207
- * Re-point a contact's OWN string-keyed history when its canonical key flips
2208
- * (risk 1). resolvedKey downstream is `external_id ?? anonymous_id ?? id`, so
2209
- * when fill-in-link attaches an external_id to a previously email-only/anon
2210
- * contact (or merge promotes the survivor's external_id), the contact's
2211
- * canonical key changes and its existing user_events/journey_states/email_sends/
2212
- * bucket_memberships/email_preferences rows (keyed on the OLD key) would be
2213
- * silently orphaned. Rewrite them from `oldKey` to `newKey`, applying the SAME
2214
- * active/terminal dedupe as the merge fold so the rewrite can't violate
2215
- * uq_user_journey_active / uq_user_bucket_active / uq(user_id,email).
2512
+ * Adopt ORPHAN history sitting under `fromKey` onto its owning contact — the
2513
+ * D4 statement, made permanent by PRD 05 T9: `UPDATE <t> SET contact_id = :id
2514
+ * WHERE user_id = :fromKey AND contact_id IS NULL`, on five tables. One
2515
+ * column. The string key is never rewritten again; reads follow `contact_id`
2516
+ * (T4-T8), and D9 keeps writing `user_id` on every insert, so history stays a
2517
+ * frozen record of the key it happened under.
2216
2518
  *
2217
- * No-op when oldKey === newKey (the canonical key did not change).
2519
+ * This replaced two functions:
2520
+ * - `repointOwnHistory`, which rewrote `user_id` from the old canonical key
2521
+ * to the new one on a key flip (with three dedupe folds against the
2522
+ * string-scoped unique indexes), and
2523
+ * - `adoptOwnKeyHistory`, which stamped history already sitting under a
2524
+ * brand-new contact's OWN key.
2525
+ * The "did the canonical key flip" test that distinguished them is meaningless
2526
+ * when nothing is keyed on the canonical key, so both call shapes are one
2527
+ * function now: name the key, stamp its orphans.
2528
+ *
2529
+ * The `contact_id IS NULL` predicate is the anti-theft guard (D6): a row
2530
+ * another contact owns already carries that owner's id and can never match.
2531
+ * `keysAnotherContact` no longer gates adoption — it survives only to gate
2532
+ * the `mergedKeys` REPORT (the analytics stitch must never alias a foreign
2533
+ * key) and the attach path inside `claimIdentityKey`.
2534
+ *
2535
+ * The folds still run, re-expressed on the contact scope (D4/D5): the
2536
+ * adopting contact may ALREADY own a live row for the same journey/bucket (or
2537
+ * a pref row for the same address), and a bare stamp would mint a second row
2538
+ * satisfying `uq_contact_journey_active` / `uq_contact_bucket_active` /
2539
+ * `email_preferences_contact_email_idx` — a 23505 inside the resolve
2540
+ * transaction. Same routing as the merge fold (exit / soft-leave / dedupe /
2541
+ * pref-fold), stamp-only writes.
2542
+ *
2543
+ * Idempotent: a second run finds `contact_id` already set and matches nothing.
2218
2544
  */
2219
- async function repointOwnHistory(
2545
+ async function adoptOrphanHistory(
2220
2546
  tx: Tx,
2221
- oldKey: string,
2222
- newKey: string,
2547
+ fromKey: string,
2223
2548
  row: ContactRow,
2224
2549
  ): Promise<void> {
2225
- if (oldKey === newKey) return;
2550
+ const ownKey = contactKey(row);
2226
2551
 
2227
- // user_events: no unique constraint on user_id — blind rewrite.
2552
+ // user_events + email_sends: no unique constraint involved — plain stamps.
2228
2553
  await tx
2229
2554
  .update(userEvents)
2230
- .set({ userId: newKey })
2231
- .where(eq(userEvents.userId, oldKey));
2232
-
2233
- // journey_states + bucket_memberships: dedupe against the survivor/new key's
2234
- // existing rows (the folds already handle the collision logic).
2235
- await foldJourneyStates(tx, newKey, [oldKey], row);
2236
- await foldBucketMemberships(tx, newKey, [oldKey]);
2237
-
2238
- // email_sends: no unique constraint on user_id — blind rewrite.
2555
+ .set({ contactId: row.id })
2556
+ .where(and(eq(userEvents.userId, fromKey), isNull(userEvents.contactId)));
2239
2557
  await tx
2240
2558
  .update(emailSends)
2241
- .set({
2242
- userId: newKey,
2243
- ...(row.email ? { userEmail: row.email } : {}),
2244
- })
2245
- .where(eq(emailSends.userId, oldKey));
2246
-
2247
- // email_preferences: FOLD into the new key's rows (uq(user_id, email)).
2248
- await foldEmailPreferences(tx, [oldKey], newKey);
2559
+ .set({ contactId: row.id })
2560
+ .where(and(eq(emailSends.userId, fromKey), isNull(emailSends.contactId)));
2561
+
2562
+ // journey_states / bucket_memberships / email_preferences: stamp through
2563
+ // the folds so a collision with a row the contact already owns is routed
2564
+ // (exited / left / folded) instead of violating the contact-scoped index.
2565
+ await foldJourneyStates(tx, ownKey, [fromKey], row, undefined, {
2566
+ stampOnly: true,
2567
+ });
2568
+ await foldBucketMemberships(tx, ownKey, [fromKey], row.id, undefined, {
2569
+ stampOnly: true,
2570
+ });
2571
+ await foldEmailPreferences(tx, [fromKey], ownKey, row.id, undefined, {
2572
+ stampOnly: true,
2573
+ });
2249
2574
  }
2250
2575
 
2251
2576
  /** RECORD a contact_aliases row per loser key → survivor (reason 'merge'). */
@@ -2514,10 +2839,26 @@ export async function findContacts(opts: {
2514
2839
  if (userId) clauses.push(eq(contacts.externalId, userId));
2515
2840
  if (clauses.length === 0) return [];
2516
2841
 
2517
- return db
2842
+ const rows = await db
2518
2843
  .select()
2519
2844
  .from(contacts)
2520
2845
  .where(and(or(...clauses), isNull(contacts.deletedAt)));
2846
+
2847
+ // Identity-table fallback per supplied key (PRD 07 T7): a STALE
2848
+ // (merged-away) email or external id finds its survivor.
2849
+ const found = new Set(rows.map((r) => r.id));
2850
+ if (email && !rows.some((r) => r.email === email)) {
2851
+ const viaAlias = await resolveViaAlias(db, "email", email);
2852
+ if (viaAlias && !found.has(viaAlias.id)) {
2853
+ rows.push(viaAlias);
2854
+ found.add(viaAlias.id);
2855
+ }
2856
+ }
2857
+ if (userId && !rows.some((r) => r.externalId === userId)) {
2858
+ const viaAlias = await resolveViaAlias(db, "external", userId);
2859
+ if (viaAlias && !found.has(viaAlias.id)) rows.push(viaAlias);
2860
+ }
2861
+ return rows;
2521
2862
  }
2522
2863
 
2523
2864
  /**
@@ -2555,10 +2896,35 @@ export async function softDeleteContact(opts: {
2555
2896
  // back together, so a failure cannot leave identity keys stranded in the
2556
2897
  // alias table for a deleted person.
2557
2898
  const row = await db.transaction(async (tx) => {
2899
+ // Alias-aware target resolution (PRD 07 T7): erasing by a STALE
2900
+ // (merged-away) email or external id erases the SURVIVOR — the live row
2901
+ // that person's data folded into. Resolved inside the tx so the lookup,
2902
+ // the soft-delete and the erasure hook see one consistent state.
2903
+ const direct = await tx
2904
+ .select({
2905
+ id: contacts.id,
2906
+ externalId: contacts.externalId,
2907
+ email: contacts.email,
2908
+ })
2909
+ .from(contacts)
2910
+ .where(and(or(...clauses), isNull(contacts.deletedAt)));
2911
+ const targetIds = new Set(direct.map((r) => r.id));
2912
+ if (email && !direct.some((r) => r.email === email)) {
2913
+ const viaAlias = await resolveViaAlias(tx, "email", email);
2914
+ if (viaAlias) targetIds.add(viaAlias.id);
2915
+ }
2916
+ if (userId && !direct.some((r) => r.externalId === userId)) {
2917
+ const viaAlias = await resolveViaAlias(tx, "external", userId);
2918
+ if (viaAlias) targetIds.add(viaAlias.id);
2919
+ }
2920
+ if (targetIds.size === 0) return undefined;
2921
+
2558
2922
  const updated = await tx
2559
2923
  .update(contacts)
2560
2924
  .set({ deletedAt: new Date(), updatedAt: new Date() })
2561
- .where(and(or(...clauses), isNull(contacts.deletedAt)))
2925
+ .where(
2926
+ and(inArray(contacts.id, [...targetIds]), isNull(contacts.deletedAt)),
2927
+ )
2562
2928
  .returning({
2563
2929
  id: contacts.id,
2564
2930
  externalId: contacts.externalId,
@@ -2744,7 +3110,7 @@ export async function lookupContactIdByKey(
2744
3110
  * device's anon id lives ONLY as an identity row) both fall back to it after
2745
3111
  * their column probes miss. */
2746
3112
  export async function resolveViaAlias(
2747
- db: Database,
3113
+ db: Database | Tx,
2748
3114
  kind: Kind,
2749
3115
  value: string,
2750
3116
  ): Promise<ContactRow | null> {