@hogsend/engine 0.56.0 → 0.57.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.
@@ -11,11 +11,38 @@ import {
11
11
  journeyStates,
12
12
  userEvents,
13
13
  } from "@hogsend/db";
14
- import { and, eq, ilike, inArray, isNull, or, sql } from "drizzle-orm";
14
+ import {
15
+ and,
16
+ eq,
17
+ ilike,
18
+ inArray,
19
+ isNotNull,
20
+ isNull,
21
+ or,
22
+ type SQL,
23
+ sql,
24
+ } from "drizzle-orm";
25
+ import { createLogger } from "./logger.js";
26
+
27
+ /** Module logger (the house lib idiom — see connector-actions.ts:28). Used only
28
+ * for the alias dual-write's conflict warning; the resolver's option surface
29
+ * stays logger-free. */
30
+ const logger = createLogger(process.env.LOG_LEVEL);
15
31
 
16
32
  const UUID_REGEX =
17
33
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
18
34
 
35
+ /**
36
+ * `contact_aliases.reason` values written by PRD 02's dual-write and backfill.
37
+ * One exported const per value so the writer (here), the backfill job
38
+ * (`workflows/identity-alias-backfill.ts`) and any rollback statement share a
39
+ * single spelling — `reason` is bare text with no CHECK, so a typo would
40
+ * silently escape a string-matched filter. The pre-existing `'promote'` /
41
+ * `'merge'` literals are provenance events and are deliberately not touched.
42
+ */
43
+ export const ALIAS_REASON_RESOLVE = "resolve";
44
+ export const ALIAS_REASON_BACKFILL = "backfill";
45
+
19
46
  /**
20
47
  * Thrown by {@link resolveOrCreateContact} when a PUBLISHABLE (browser, pk_) anon
21
48
  * write would attach to / merge into / mutate a contact that already carries an
@@ -37,6 +64,33 @@ export class PublishableAnonymousMergeError extends Error {
37
64
  }
38
65
  }
39
66
 
67
+ /**
68
+ * Thrown by the resolver when a supplied identity key's kind is absent from
69
+ * the caller's declared `ResolvePolicy.trustedKinds` (PRD 06 T5).
70
+ *
71
+ * INTERNAL — deliberately NOT exported from `index.ts`. This is defence in
72
+ * depth, not a request-shaping tool: every browser-facing route is already
73
+ * gated one layer up (`gatePublishableIdentity` for `/v1/events`,
74
+ * `/v1/contacts` and the `lists` handlers; `arrive`'s keys come from the
75
+ * first-write-wins stamp; `feed`'s re-ingests are engine-internal full-trust
76
+ * with a server-derived subject — the three-legged L3 proof), so this throw
77
+ * is unreachable from every route today. It exists to catch a FUTURE route
78
+ * that forgets the gate — a caller bug, surfaced loudly in dev, never a
79
+ * condition for consumers to branch on. Thrown BEFORE any advisory lock is
80
+ * taken and before the transaction opens, so a refused call leaves no lock
81
+ * and no row behind.
82
+ */
83
+ export class UntrustedKeyKindError extends Error {
84
+ constructor(kind: string, trustedKinds: readonly string[]) {
85
+ super(
86
+ `identity key kind "${kind}" is not in this caller's declared ` +
87
+ `trustedKinds [${trustedKinds.join(", ")}] — the caller supplied a ` +
88
+ "key it is not authorized to assert (PRD 06 T5)",
89
+ );
90
+ this.name = "UntrustedKeyKindError";
91
+ }
92
+ }
93
+
40
94
  /**
41
95
  * True when `value` is the canonical key of an IDENTIFIED contact — i.e. a
42
96
  * live contact's `external_id`, or its `email` when that is its canonical key
@@ -84,6 +138,127 @@ export async function collidesWithIdentified(
84
138
  return false;
85
139
  }
86
140
 
141
+ /**
142
+ * True when some OTHER live contact's canonical key (`external_id ??
143
+ * anonymous_id ?? id`) is exactly `value` — i.e. `value` already keys that
144
+ * person's string-keyed history.
145
+ *
146
+ * This is the precondition for ADOPTING history, and it is strictly stronger
147
+ * than "no contact resolved by this anonymous key". Resolution probes the
148
+ * ANONYMOUS namespace (`contacts.anonymous_id` + anonymous aliases), so a value
149
+ * that is another contact's `external_id` — or, for a contact with neither key,
150
+ * its row uuid — misses every probe while still keying all of that contact's
151
+ * rows. Adopting on a resolution miss alone therefore lets a caller name
152
+ * someone else's canonical key as their own `anonymousId` and have that
153
+ * person's events, journey states, bucket memberships and sends repointed onto
154
+ * the caller's contact.
155
+ *
156
+ * ATTACHING a key (writing the column / recording an alias) is not the same act
157
+ * as ADOPTING one: attaching adds a resolution edge, adoption MOVES rows. Only
158
+ * adoption is gated on this.
159
+ */
160
+ async function keysAnotherContact(
161
+ tx: Tx,
162
+ value: string,
163
+ selfId: string,
164
+ ): Promise<boolean> {
165
+ const rows = await tx
166
+ .select({
167
+ id: contacts.id,
168
+ externalId: contacts.externalId,
169
+ anonymousId: contacts.anonymousId,
170
+ })
171
+ .from(contacts)
172
+ .where(
173
+ and(
174
+ or(
175
+ eq(contacts.externalId, value),
176
+ eq(contacts.anonymousId, value),
177
+ // A contact with neither key is keyed on its row uuid, and that key
178
+ // leaves the system (Hatchet payloads, hs_t tokens), so it is guessable
179
+ // in a way a browser-local anon id is not.
180
+ ...(UUID_REGEX.test(value) ? [eq(contacts.id, value)] : []),
181
+ ),
182
+ isNull(contacts.deletedAt),
183
+ ),
184
+ );
185
+ for (const r of rows) {
186
+ if (r.id === selfId) continue;
187
+ if ((r.externalId ?? r.anonymousId ?? r.id) === value) return true;
188
+ }
189
+ return false;
190
+ }
191
+
192
+ /**
193
+ * PRD 03 — THE single claim executor. Every supplied identity key the columns
194
+ * cannot (or should not) hold becomes an identity row through this one path,
195
+ * on the fill-in-link arm and the merge arm alike. The arms decide WHAT to
196
+ * claim (and whether a free column also gets the legacy dual-write); this
197
+ * function is the only place a claim is gated and recorded — the per-arm
198
+ * inline-side-effect shape is what let the pre-PRD-03 if-arm ship ungated.
199
+ *
200
+ * Gate: `external` and `anonymous` claims are refused when the value is
201
+ * another live contact's CANONICAL key (`keysAnotherContact`) — resolution
202
+ * probes only the kind's own namespace, so "no candidate resolved" does not
203
+ * mean "nobody owns this value", and while history is string-keyed a claim on
204
+ * someone else's canonical key is the setup for theft (the adoption/repoint
205
+ * primitives key on strings until PRD 05). `email`/`discord` need no gate:
206
+ * neither is ever canonical, so neither ever keyed history — nothing to steal.
207
+ * The gate result is memoised per value (`foreignMemo`) so a caller probing
208
+ * the same value twice issues one query.
209
+ *
210
+ * A refused claim is silent + logged (`identity.claim.refused_foreign_key`,
211
+ * kind + contact id, NEVER the value — it is another person's identifier):
212
+ * throwing would 500 an ingest that looks legitimate to its caller.
213
+ *
214
+ * Returns:
215
+ * - "refused" — foreign canonical key; the caller must skip the column write,
216
+ * the adoption and the `mergedKeys` report as well.
217
+ * - "claimed" — THIS call inserted the `(kind, value)` row. The first-claim
218
+ * signal adoption reads: structural idempotence via the unique index +
219
+ * `returning()`, replacing the bespoke `anonAliasAlreadyHeld` probe (a
220
+ * repeat resolve conflicts, returns nothing, and re-fires nothing — the
221
+ * re-stitch-storm guard, now enforced by the index instead of remembered).
222
+ * - "held" — the row already existed (repeat resolve, or a merge/backfill
223
+ * wrote it first); nothing to adopt or report.
224
+ */
225
+ async function claimIdentityKey(
226
+ tx: Tx,
227
+ row: ContactRow,
228
+ key: ResolveKey,
229
+ foreignMemo: Map<string, boolean>,
230
+ ): Promise<"refused" | "claimed" | "held"> {
231
+ if (key.kind === "external" || key.kind === "anonymous") {
232
+ let foreign = foreignMemo.get(key.value);
233
+ if (foreign === undefined) {
234
+ foreign = await keysAnotherContact(tx, key.value, row.id);
235
+ foreignMemo.set(key.value, foreign);
236
+ }
237
+ if (foreign) {
238
+ logger.warn("identity.claim.refused_foreign_key", {
239
+ kind: key.kind,
240
+ contactId: row.id,
241
+ });
242
+ return "refused";
243
+ }
244
+ }
245
+
246
+ const inserted = await tx
247
+ .insert(contactAliases)
248
+ .values({
249
+ contactId: row.id,
250
+ aliasKind: key.kind,
251
+ aliasValue: key.value,
252
+ fromContactId: null,
253
+ reason: "promote",
254
+ })
255
+ .onConflictDoNothing({
256
+ target: [contactAliases.aliasKind, contactAliases.aliasValue],
257
+ })
258
+ .returning({ id: contactAliases.id });
259
+ return inserted.length > 0 ? "claimed" : "held";
260
+ }
261
+
87
262
  /**
88
263
  * Thrown by {@link resolveOrCreateContact}'s engine-internal `contactId` pin when
89
264
  * the pinned subject row no longer exists and no merge-alias chain leads to a live
@@ -192,6 +367,56 @@ export function contactSearchFilter(search: string) {
192
367
  );
193
368
  }
194
369
 
370
+ /**
371
+ * "Has this person EVER identified?" — the single display predicate behind
372
+ * `GET /v1/admin/contacts?identity=…` and Studio's identified-only default.
373
+ *
374
+ * FOUR columns, not two. `external_id` and `email` are the obvious pair, but
375
+ * `contacts.discord_id` and `contacts.phone` are documented in the schema as
376
+ * RESOLVABLE identity keys, NOT properties (`schema/contacts.ts:34-53`), each
377
+ * carrying its own live partial-unique index. A Discord-linked community
378
+ * member and an SMS-only subscriber have both identified; dropping either leg
379
+ * makes a real customer vanish from the default list. `anonymous_id` is
380
+ * deliberately absent — it is exactly what this predicate exists to exclude.
381
+ *
382
+ * The complement is `not(identifiedContactFilter())`, and it is EXACT: every
383
+ * operand is `IS NOT NULL`, which never yields NULL, so three-valued logic
384
+ * cannot swallow a row under the negation. Hence
385
+ * `total(identified) + total(anonymous) === total(all)`, and the rare keyless
386
+ * row (no identity column at all — the engine already handles those by uuid)
387
+ * lands in `anonymous`, which is the truthful bucket for it.
388
+ *
389
+ * FUTURE (PRD 02/03) — the swap is this function body and nothing else:
390
+ *
391
+ * ```ts
392
+ * or(
393
+ * sql`exists (select 1 from contact_aliases ca
394
+ * where ca.contact_id = ${contacts.id} and ca.alias_kind <> 'anonymous')`,
395
+ * isNotNull(contacts.phone),
396
+ * )
397
+ * ```
398
+ *
399
+ * Two ordering rules govern it. (1) It is correct only AFTER PRD 02's alias
400
+ * backfill is verified — today `contact_aliases` is written only on
401
+ * merge/promote, so the `EXISTS` would read as "never identified" for almost
402
+ * everyone and empty the list. (2) The `phone` leg SURVIVES the swap: PRD 02
403
+ * deliberately excludes phone from both the backfill and the dual-write
404
+ * (phone is not yet a merge-participating `Kind`), so a phone-only contact has
405
+ * no non-anonymous alias row. That leg retires only when phone joins the
406
+ * identity table.
407
+ */
408
+ export function identifiedContactFilter(): SQL {
409
+ // `or()` is typed `SQL | undefined` because it tolerates undefined operands.
410
+ // All four here are statically present, so the result is never undefined —
411
+ // the assertion narrows the type, it does not assert anything at runtime.
412
+ return or(
413
+ isNotNull(contacts.externalId),
414
+ isNotNull(contacts.email),
415
+ isNotNull(contacts.discordId),
416
+ isNotNull(contacts.phone),
417
+ ) as SQL;
418
+ }
419
+
195
420
  /**
196
421
  * Normalized, sendable email: `trim` + `toLowerCase`. No dot/+tag stripping —
197
422
  * we store the NORMALIZED RAW email (D1), so the address must still deliver.
@@ -211,7 +436,78 @@ export function normalizeEmailOrNull(
211
436
  // Identity resolution
212
437
  // ---------------------------------------------------------------------------
213
438
 
214
- type Kind = "external" | "email" | "anonymous" | "discord";
439
+ /**
440
+ * The four key kinds identity resolution understands (PRD 06 — the module-local
441
+ * `Kind` promoted to the public API). `phone` is deliberately absent: it is not
442
+ * yet a merge-participating kind (SMS STOP resolves a contact by a direct
443
+ * `contacts.phone` lookup, outside the resolver).
444
+ */
445
+ export type IdentityKind = "external" | "email" | "anonymous" | "discord";
446
+
447
+ // Module-local shorthand retained so this file's existing signatures
448
+ // (`ResolveKey`, `resolveViaAlias`, …) don't churn.
449
+ export type Kind = IdentityKind;
450
+
451
+ /**
452
+ * Explicit, caller-declared trust for ONE resolve call (PRD 06). Replaces the
453
+ * legacy inference from `restrictToAnonymous`/`allowCreate` plus *which keys
454
+ * happen to be present*: trust travels with the call instead of being
455
+ * reconstructed inside the resolver. Pass at most one shape — `policy` OR the
456
+ * legacy fields — never both (the resolver throws; no precedence rule exists).
457
+ */
458
+ export interface ResolvePolicy {
459
+ /**
460
+ * MINT policy. `"on-miss"` is the historic create arm: when no live contact
461
+ * owns any supplied key, insert one. `"refuse-on-miss"` is the D1 observation
462
+ * refusal: return `{ id: null }` and mint nothing (reachable only through
463
+ * {@link resolveContactNoCreate}). The refusal KEY is never accepted from the
464
+ * caller — it stays DERIVED (`userId ?? anonymousId`) and D8-validated inside
465
+ * `resolveContactNoCreate`: a caller-supplied key could diverge from what the
466
+ * create arm would have made canonical and strand the event's history under a
467
+ * key no contact will ever own (A1).
468
+ */
469
+ create: "on-miss" | "refuse-on-miss";
470
+ /**
471
+ * MERGE/ATTACH policy. `"any"` is the historic unrestricted behavior.
472
+ * `"anonymous-only"` is the publishable clamp (§Phase 1 GAP-1, the legacy
473
+ * `restrictToAnonymous`): it bites only when the supplied keys are EXACTLY
474
+ * one `anonymous` key, and then refuses to fill-in-link to / merge with an
475
+ * identified contact and ignores the `contactId` provenance pin.
476
+ *
477
+ * `"never-identified-pair"` is RESERVED and NOT IMPLEMENTED — selecting it
478
+ * throws until it is. It names the rule the current vocabulary cannot
479
+ * express: never merge two ALREADY-IDENTIFIED persons. The concrete harm it
480
+ * will one day prevent: person A signs in on a browser (the browser's anon
481
+ * id `V` is claimed onto A's identified contact), then person B signs in on
482
+ * the SAME browser without `reset()` — the resolve `{ userId: B,
483
+ * anonymousId: V }` finds two candidates, both identified, and
484
+ * `mergeContacts` folds two real humans into one: {@link pickSurvivor}
485
+ * prefers identified-then-oldest and never checks whether BOTH candidates
486
+ * are identified. Shared computers, family devices and kiosks make this an
487
+ * ordinary event, not an attack. Fixing it is a behaviour change and out of
488
+ * this refactor's scope (D8); no built-in caller selects the value.
489
+ */
490
+ allowMerge: "any" | "anonymous-only" | "never-identified-pair";
491
+ /**
492
+ * The key kinds THIS CALLER is authorized to assert. ENFORCED (PRD 06 T5):
493
+ * a supplied key whose kind is absent from this list throws
494
+ * `UntrustedKeyKindError` — after the keys array is built, before any
495
+ * advisory lock is taken and before the transaction opens. The default when
496
+ * no policy is supplied is all four kinds, so legacy-shape callers are
497
+ * unaffected.
498
+ */
499
+ trustedKinds: readonly IdentityKind[];
500
+ }
501
+
502
+ /** Every kind — the legacy shapes' implicit trust grant (the server default).
503
+ * Exported (module-level, not public API) so policy-declaring callers state
504
+ * the full grant without re-spelling the four literals (PRD 06 T3). */
505
+ export const ALL_IDENTITY_KINDS: readonly IdentityKind[] = [
506
+ "external",
507
+ "email",
508
+ "anonymous",
509
+ "discord",
510
+ ];
215
511
 
216
512
  interface ResolveKey {
217
513
  kind: Kind;
@@ -223,11 +519,43 @@ const UUID_PATTERN =
223
519
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
224
520
 
225
521
  /**
226
- * Look up the single live contact owning `(kind, value)`, falling back to
227
- * `contact_aliases` on a miss so a stale (loser/promoted) key still resolves to
228
- * the SURVIVOR (risk 5). Returns the contact row or null.
522
+ * Look up the single live contact owning `(kind, value)`. Probe order (PRD 02
523
+ * T5 — the identity table is the source of truth):
524
+ *
525
+ * 1. ALIAS-FIRST — one joined statement over `contact_aliases` → `contacts`.
526
+ * The `deleted_at IS NULL` predicate lives INSIDE the join on purpose: an
527
+ * alias whose target is soft-deleted must produce NO row, so the probe
528
+ * falls through rather than resolving a tombstone (the live-target rule).
529
+ * 2. Identity-column probe — unchanged; covers keys that predate the alias
530
+ * backfill and keys whose alias row is dead.
531
+ * 3. Row-uuid fallback (external keys only) — unchanged, still last.
532
+ *
533
+ * With an empty `contact_aliases` this behaves exactly as the old column-first
534
+ * order did, which is what makes the flip revertable.
229
535
  */
230
536
  async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
537
+ // (1) Alias probe FIRST. Single round trip; served by the
538
+ // `contact_aliases_kind_value_idx` unique index plus a PK join.
539
+ const viaAlias = await tx
540
+ .select({ contact: contacts })
541
+ .from(contactAliases)
542
+ .innerJoin(
543
+ contacts,
544
+ and(
545
+ eq(contacts.id, contactAliases.contactId),
546
+ isNull(contacts.deletedAt),
547
+ ),
548
+ )
549
+ .where(
550
+ and(
551
+ eq(contactAliases.aliasKind, key.kind),
552
+ eq(contactAliases.aliasValue, key.value),
553
+ ),
554
+ )
555
+ .limit(1);
556
+ if (viaAlias[0]) return viaAlias[0].contact;
557
+
558
+ // (2) Identity-column probe — unchanged.
231
559
  const column =
232
560
  key.kind === "external"
233
561
  ? contacts.externalId
@@ -244,28 +572,6 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
244
572
  .limit(1);
245
573
  if (direct[0]) return direct[0];
246
574
 
247
- // Alias fallback: the key may sit on a soft-deleted loser row.
248
- const alias = await tx
249
- .select({ contactId: contactAliases.contactId })
250
- .from(contactAliases)
251
- .where(
252
- and(
253
- eq(contactAliases.aliasKind, key.kind),
254
- eq(contactAliases.aliasValue, key.value),
255
- ),
256
- )
257
- .limit(1);
258
- if (alias[0]) {
259
- const aliased = await tx
260
- .select()
261
- .from(contacts)
262
- .where(
263
- and(eq(contacts.id, alias[0].contactId), isNull(contacts.deletedAt)),
264
- )
265
- .limit(1);
266
- if (aliased[0]) return aliased[0];
267
- }
268
-
269
575
  // Row-id fallback (external keys only): an email-only / anonymous-only
270
576
  // contact's canonical key (`external_id ?? anonymous_id ?? id`) IS its row id,
271
577
  // and that key leaves the system — in Hatchet event payloads, outbound
@@ -499,24 +805,13 @@ export function contactKeySql() {
499
805
  }
500
806
 
501
807
  /**
502
- * THE resolver (D1). Transactional. Resolves any combination of identity keys
503
- * (external_id / email / anonymous_id, in any subset — incl. anon-only or
504
- * email-only) to a single canonical `contacts` row, handling three cases:
505
- *
506
- * - create — no existing row owns any provided key.
507
- * - fill-in-link — exactly one row matches; missing keys are filled and a
508
- * `'promote'` alias is recorded for each newly-attached key.
509
- * - collide-MERGE — 2-3 distinct rows match; a survivor is chosen (SURVIVOR
510
- * RULE) and the losers are re-pointed across all 5 tables,
511
- * folded, soft-deleted, and aliased (9-step order).
512
- *
513
- * INSERT RACE strategy: a `pg_advisory_xact_lock(hashtext(kind||value))` is taken
514
- * per provided key at the TOP of the tx (before any SELECT). Two concurrent
515
- * resolves for the same key serialize on the lock, so the second sees the first's
516
- * insert and links/merges instead of racing a duplicate row. The lock is held
517
- * until the tx commits/rolls back (xact-scoped) — no manual unlock.
808
+ * The identity keys + options EVERY resolve entry point accepts. Named (rather
809
+ * than inline) so {@link resolveOrCreateContact} and {@link
810
+ * resolveContactNoCreate} declare one option shape over one implementation
811
+ * ({@link resolveContactShared}) and can never drift apart. Purely an
812
+ * extraction — the exported parameter type is structurally unchanged.
518
813
  */
519
- export async function resolveOrCreateContact(opts: {
814
+ interface ResolveContactOptions {
520
815
  db: Database;
521
816
  userId?: string;
522
817
  email?: string;
@@ -533,8 +828,21 @@ export async function resolveOrCreateContact(opts: {
533
828
  * (`get_distinct_id()`), so without this clamp a pk_ key could forge events as
534
829
  * / poison a victim's identified contact via the anon resolution arm. The
535
830
  * secret-key path NEVER sets this, so its behavior is byte-for-byte unchanged.
831
+ *
832
+ * @deprecated PRD 06 — declare {@link ResolvePolicy} instead:
833
+ * `policy: { allowMerge: "anonymous-only", … }`. Still fully accepted and
834
+ * honoured (removal is a breaking change deferred to a later sweep), but
835
+ * mutually exclusive with `policy` — supplying both shapes throws.
536
836
  */
537
837
  restrictToAnonymous?: boolean;
838
+ /**
839
+ * Explicit caller trust (PRD 06). Mutually exclusive with the legacy
840
+ * `restrictToAnonymous` field (and, on the internal shared body, the derived
841
+ * `refuseCreateWithKey` channel): supplying both shapes throws — no
842
+ * precedence rule exists. Absent ⇒ the legacy fields (or their defaults)
843
+ * apply unchanged.
844
+ */
845
+ policy?: ResolvePolicy;
538
846
  /**
539
847
  * ENGINE-INTERNAL provenance — the subject contact's UNFORGEABLE row id
540
848
  * (`contacts.id`, a server-minted uuid). Set ONLY by engine-internal re-emit
@@ -561,36 +869,69 @@ export async function resolveOrCreateContact(opts: {
561
869
  source?: string;
562
870
  /** Timestamp paired with {@link source}; defaults to now() at create time. */
563
871
  sourcedAt?: Date;
564
- }): Promise<{
565
- id: string;
566
- /**
567
- * The contact's canonical text user_id key AFTER this resolve
568
- * (`external_id ?? anonymous_id ?? id`), i.e. {@link contactKey} of the final
569
- * row — for a merge, the SURVIVOR's key. Lets callers (ingestEvent) key the
570
- * history tables without a second read-back of the contact row.
571
- */
872
+ }
873
+
874
+ /**
875
+ * The shared implementation's result. Identical to
876
+ * {@link resolveOrCreateContact}'s (documented there) EXCEPT that `id` is
877
+ * nullable: the refusal arm returns `null`. The two exported entry points
878
+ * re-narrow it — `resolveOrCreateContact` back to `string`, so its published
879
+ * type never widens (D3).
880
+ */
881
+ interface ResolveContactSharedResult {
882
+ id: string | null;
572
883
  resolvedKey: string;
573
884
  created: boolean;
574
885
  linked: boolean;
575
886
  merged: boolean;
576
- /**
577
- * SAFE-to-absorb loser keys (§5.3 MF-2): the anonymous/uuid keys the resolver
578
- * folded INTO `resolvedKey` this call — populated only on a collide-MERGE or a
579
- * canonical-key flip that absorbed an anon/uuid key. Callers fan these out via
580
- * `mergeAnalyticsIdentities({ distinctId: resolvedKey, alias: <key> })`. An
581
- * `external_id` is NEVER listed here (it carried an identified PostHog person;
582
- * aliasing it is the merge PostHog refuses — R2/R4); it surfaces in
583
- * {@link mergedIdentifiedKeys} instead. Empty/absent ⇒ nothing to stitch.
584
- */
585
887
  mergedKeys?: string[];
586
- /**
587
- * Loser keys MF-2 could NOT safely absorb — already-identified `external_id`s
588
- * (and the superseded `external_id` on a key flip). These are the known
589
- * steady-state twin residual (§10, OQ-1); callers log them as
590
- * `identity.merge.residual_twin` for observability. Never aliased.
591
- */
592
888
  mergedIdentifiedKeys?: string[];
593
- }> {
889
+ }
890
+
891
+ /**
892
+ * THE resolver (D1). Transactional. Resolves any combination of identity keys
893
+ * (external_id / email / anonymous_id, in any subset — incl. anon-only or
894
+ * email-only) to a single canonical `contacts` row, handling three cases:
895
+ *
896
+ * - create — no existing row owns any provided key.
897
+ * - fill-in-link — exactly one row matches; missing keys are filled and a
898
+ * `'promote'` alias is recorded for each newly-attached key.
899
+ * - collide-MERGE — 2-3 distinct rows match; a survivor is chosen (SURVIVOR
900
+ * RULE) and the losers are re-pointed across all 5 tables,
901
+ * folded, soft-deleted, and aliased (9-step order).
902
+ *
903
+ * …plus a fourth arm reachable ONLY through {@link resolveContactNoCreate}:
904
+ *
905
+ * - refuse — no existing row owns any provided key AND the caller
906
+ * passed `refuseCreateWithKey`. Returns `id: null` and mints
907
+ * nothing (D1: a contact is minted by identity, not by
908
+ * observation).
909
+ *
910
+ * INSERT RACE strategy: a `pg_advisory_xact_lock(hashtext(kind||value))` is taken
911
+ * per provided key at the TOP of the tx (before any SELECT). Two concurrent
912
+ * resolves for the same key serialize on the lock, so the second sees the first's
913
+ * insert and links/merges instead of racing a duplicate row. The lock is held
914
+ * until the tx commits/rolls back (xact-scoped) — no manual unlock.
915
+ */
916
+ async function resolveContactShared(
917
+ opts: ResolveContactOptions & {
918
+ /**
919
+ * REFUSAL key (D1/D8). When set, the create arm does not insert — it returns
920
+ * `{ id: null, resolvedKey: <this key> }`. The caller
921
+ * ({@link resolveContactNoCreate}) is responsible for supplying the key the
922
+ * create arm WOULD have made canonical, which is why refusal is legal only
923
+ * when the highest-precedence supplied key is `userId` or `anonymousId`:
924
+ * `contactKey = external_id ?? anonymous_id ?? id`, so for any other shape
925
+ * the canonical key is a freshly-minted row uuid that refusal cannot
926
+ * reproduce. Absent ⇒ the historic create-on-miss behavior, unchanged.
927
+ *
928
+ * @deprecated PRD 06 — the legacy internal channel for the derived refusal
929
+ * key. The policy shape re-derives the identical key inside the shared
930
+ * body instead; mutually exclusive with `policy` (supplying both throws).
931
+ */
932
+ refuseCreateWithKey?: string;
933
+ },
934
+ ): Promise<ResolveContactSharedResult> {
594
935
  const { db, contactProperties } = opts;
595
936
  const userId = opts.userId?.trim() || undefined;
596
937
  const email = opts.email ? normalizeEmail(opts.email) : undefined;
@@ -599,16 +940,43 @@ export async function resolveOrCreateContact(opts: {
599
940
  const contactId = opts.contactId?.trim() || undefined;
600
941
  const source = opts.source?.trim() || undefined;
601
942
  const sourcedAt = opts.sourcedAt;
602
- // §Phase 1 GAP-1: the publishable clamp only bites an ANON-ONLY write (the
603
- // only shape a token-less pk_ key can produce — the gate 403s any
604
- // email/userId without a verified userToken before we get here). An identified
605
- // arm (token-authorized userId, or the secret path) is never clamped.
606
- const restrictToAnonymous =
607
- opts.restrictToAnonymous === true &&
608
- !userId &&
609
- !email &&
610
- !discordId &&
611
- !!anonymousId;
943
+
944
+ // --- POLICY NORMALIZATION (PRD 06 T1) --- EITHER input shape — the explicit
945
+ // `policy` object or the legacy fields — normalises into this ONE local.
946
+ // Supplying both shapes at once is a caller bug and throws: no precedence
947
+ // rule ever ships.
948
+ if (
949
+ opts.policy &&
950
+ (opts.restrictToAnonymous !== undefined ||
951
+ opts.refuseCreateWithKey !== undefined)
952
+ ) {
953
+ throw new Error(
954
+ "resolveContact: pass either `policy` or the legacy fields " +
955
+ "(`restrictToAnonymous` / `allowCreate` / `refuseCreateWithKey`), " +
956
+ "never both — no precedence rule exists",
957
+ );
958
+ }
959
+ if (opts.policy?.allowMerge === "never-identified-pair") {
960
+ throw new Error(
961
+ 'ResolvePolicy.allowMerge "never-identified-pair" is reserved and not ' +
962
+ "implemented yet — no caller may select it (see the ResolvePolicy " +
963
+ "docblock for the shared-browser harm it will eventually prevent)",
964
+ );
965
+ }
966
+ const policy: ResolvePolicy = opts.policy ?? {
967
+ create:
968
+ opts.refuseCreateWithKey !== undefined ? "refuse-on-miss" : "on-miss",
969
+ allowMerge: opts.restrictToAnonymous === true ? "anonymous-only" : "any",
970
+ trustedKinds: ALL_IDENTITY_KINDS,
971
+ };
972
+ // The refusal key stays DERIVED, never caller-supplied (PRD 06 A1): the
973
+ // legacy channel carries `resolveContactNoCreate`'s already-D8-validated key
974
+ // verbatim; the policy shape re-derives the IDENTICAL `userId ?? anonymousId`
975
+ // from the same normalized locals above.
976
+ const refuseWithKey =
977
+ policy.create === "on-miss"
978
+ ? undefined
979
+ : (opts.refuseCreateWithKey ?? userId ?? anonymousId);
612
980
 
613
981
  const keys: ResolveKey[] = [];
614
982
  if (userId) keys.push({ kind: "external", value: userId });
@@ -623,6 +991,33 @@ export async function resolveOrCreateContact(opts: {
623
991
  );
624
992
  }
625
993
 
994
+ // --- TRUST ENFORCEMENT (PRD 06 T5) --- Every supplied key's kind must be in
995
+ // the caller's declared `trustedKinds`. Placed AFTER the keys array is built
996
+ // and BEFORE the transaction opens — so a refused call takes no advisory
997
+ // lock, opens no transaction, and writes no row. The default policy (no
998
+ // `policy` supplied) grants all four kinds, so every legacy-shape caller is
999
+ // unaffected. Unreachable from every route today (the three-legged L3
1000
+ // unreachability proof — see {@link UntrustedKeyKindError}); this is defence
1001
+ // in depth against a future route that forgets the gate.
1002
+ for (const key of keys) {
1003
+ if (!policy.trustedKinds.includes(key.kind)) {
1004
+ throw new UntrustedKeyKindError(key.kind, policy.trustedKinds);
1005
+ }
1006
+ }
1007
+
1008
+ // §Phase 1 GAP-1: the publishable clamp only bites an ANON-ONLY write (the
1009
+ // only shape a token-less pk_ key can produce — the gate 403s any
1010
+ // email/userId without a verified userToken before we get here). An identified
1011
+ // arm (token-authorized userId, or the secret path) is never clamped.
1012
+ // Provably identical to the legacy derivation (`opts.restrictToAnonymous ===
1013
+ // true && !userId && !email && !discordId && !!anonymousId`): the
1014
+ // supplied-kinds test IS that key-shape test over the same locals (PRD 06 L2).
1015
+ const suppliedKinds = keys.map((k) => k.kind);
1016
+ const clamped =
1017
+ policy.allowMerge === "anonymous-only" &&
1018
+ suppliedKinds.length === 1 &&
1019
+ suppliedKinds[0] === "anonymous";
1020
+
626
1021
  const patch = contactProperties ?? {};
627
1022
  const hasPatch = Object.keys(patch).length > 0;
628
1023
 
@@ -631,11 +1026,11 @@ export async function resolveOrCreateContact(opts: {
631
1026
  // trusted internal re-emit pins resolution to that exact row (no value-key
632
1027
  // probe, no mint), so a contact's own canonical key round-tripping back as a
633
1028
  // `userId` folds into it instead of minting a phantom `external_id` twin.
634
- // Gated on `!restrictToAnonymous` (mutually exclusive with the publishable
1029
+ // Gated on `!clamped` (mutually exclusive with the publishable
635
1030
  // clamp — a clamped pk_ write can never carry provenance) so it is never an
636
1031
  // attacker-reachable path. Runs BEFORE the value-key advisory locks: the pin
637
1032
  // serializes on the concrete row PK via `FOR UPDATE`, not on value locks.
638
- if (contactId && UUID_REGEX.test(contactId) && !restrictToAnonymous) {
1033
+ if (contactId && UUID_REGEX.test(contactId) && !clamped) {
639
1034
  return resolveByContactId(tx, contactId, { patch, hasPatch });
640
1035
  }
641
1036
 
@@ -660,6 +1055,34 @@ export async function resolveOrCreateContact(opts: {
660
1055
 
661
1056
  // --- CASE: create (no existing row) ---
662
1057
  if (candidates.length === 0) {
1058
+ // --- ARM: refuse (D1) --- Observation is not identity: a caller that
1059
+ // opted out of minting gets `id: null` and the key it supplied, and NO
1060
+ // `contacts` row is written. The event still stores under this key
1061
+ // (D2) — and a later identify ADOPTS that history, so nothing is
1062
+ // orphaned by the refusal. TWO arms do that adoption, and which one runs
1063
+ // depends on whether a contact already exists by the time the anon id
1064
+ // arrives: the create arm below when the identify supplies both keys at
1065
+ // once, and `fillInLink` when identity was folded server-side first (the
1066
+ // shape the docs sign-in produces). Both are gated on the anon key not
1067
+ // naming another contact.
1068
+ if (policy.create !== "on-miss") {
1069
+ if (refuseWithKey === undefined) {
1070
+ // Unreachable: `refuse-on-miss` enters only through
1071
+ // `resolveContactNoCreate`, whose D8 precondition already threw when
1072
+ // neither `userId` nor `anonymousId` was supplied. Narrows without a
1073
+ // cast.
1074
+ throw new Error(
1075
+ "refuse-on-miss resolve without a derivable refusal key",
1076
+ );
1077
+ }
1078
+ return {
1079
+ id: null,
1080
+ resolvedKey: refuseWithKey,
1081
+ created: false,
1082
+ linked: false,
1083
+ merged: false,
1084
+ };
1085
+ }
663
1086
  const inserted = await tx
664
1087
  .insert(contacts)
665
1088
  .values({
@@ -677,12 +1100,50 @@ export async function resolveOrCreateContact(opts: {
677
1100
  .returning();
678
1101
  const createdRow = inserted[0];
679
1102
  if (!createdRow) throw new Error("Contact insert returned no row");
1103
+
1104
+ // PRD 02 dual-write: the create arm historically wrote ZERO alias rows.
1105
+ await ensureIdentityAliases(tx, createdRow);
1106
+
1107
+ // HISTORY ADOPTION (D2). Once observation stops minting a row, a later
1108
+ // 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.
1113
+ //
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.
1124
+ const createdKey = contactKey(createdRow);
1125
+ 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];
1138
+ }
1139
+
680
1140
  return {
681
1141
  id: createdRow.id,
682
- resolvedKey: contactKey(createdRow),
1142
+ resolvedKey: createdKey,
683
1143
  created: true,
684
1144
  linked: false,
685
1145
  merged: false,
1146
+ mergedKeys,
686
1147
  };
687
1148
  }
688
1149
 
@@ -694,7 +1155,7 @@ export async function resolveOrCreateContact(opts: {
694
1155
  // is a forge/poison attempt — the browser-readable anonymousId pointed at
695
1156
  // a victim. Refuse to fill-in-link / mutate it. (Resolving to its OWN
696
1157
  // anonymous-only contact — no external_id, no email — is allowed.)
697
- if (restrictToAnonymous && (single.externalId || single.email)) {
1158
+ if (clamped && (single.externalId || single.email)) {
698
1159
  throw new PublishableAnonymousMergeError();
699
1160
  }
700
1161
  const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
@@ -723,7 +1184,20 @@ export async function resolveOrCreateContact(opts: {
723
1184
  // §Phase 1 GAP-1: an anon-only publishable write must NEVER drive a merge —
724
1185
  // the browser-readable anonymousId would let an attacker fold two of a
725
1186
  // victim's contacts together (identity-graph corruption). Refuse.
726
- if (restrictToAnonymous) {
1187
+ //
1188
+ // UNREACHABLE BY CONSTRUCTION (PRD 06 T1 mutation-gate note) — do not
1189
+ // burn time hunting a test that can kill this guard; none can. `clamped`
1190
+ // requires `suppliedKinds` to be exactly `["anonymous"]`, so `keys` holds
1191
+ // ONE entry, `findByKey` returns at most ONE row per key, and
1192
+ // `candidates.length <= 1` — but this arm runs only when
1193
+ // `candidates.length >= 2`. The same argument means PRD 06 T2's planned
1194
+ // {anon-only key × two-colliding-rows} equivalence cell cannot actually
1195
+ // drive a collide-MERGE — an anon-only fixture lands in the create or
1196
+ // fill-in-link arm no matter what rows are seeded; don't be confused when
1197
+ // that cell never reaches here. The guard stays anyway: it is a behaviour
1198
+ // of record (removing it is not a refactor) and it becomes load-bearing
1199
+ // the moment key construction lets a clamped resolve supply a second key.
1200
+ if (clamped) {
727
1201
  throw new PublishableAnonymousMergeError();
728
1202
  }
729
1203
  const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
@@ -749,6 +1223,140 @@ export async function resolveOrCreateContact(opts: {
749
1223
  });
750
1224
  }
751
1225
 
1226
+ /**
1227
+ * THE resolver (D1) — create-on-miss. A thin entry point over
1228
+ * {@link resolveContactShared} (see there for the create / fill-in-link /
1229
+ * collide-MERGE arms and the INSERT-race lock strategy). Behavior and published
1230
+ * type are unchanged by the extraction: `id` is a plain `string`, never `null`,
1231
+ * because this entry point never passes `refuseCreateWithKey` — the refusal arm
1232
+ * is unreachable from here. That matters concretely (D3): three sites annotate
1233
+ * on `Awaited<ReturnType<typeof resolveOrCreateContact>>`, one of them the
1234
+ * published `IdentityService.linkContact`, so widening `id` here would ripple
1235
+ * into the semver surface. Callers that want the refusal reach for
1236
+ * {@link resolveContactNoCreate} instead.
1237
+ */
1238
+ export async function resolveOrCreateContact(
1239
+ opts: ResolveContactOptions,
1240
+ ): Promise<{
1241
+ id: string;
1242
+ /**
1243
+ * The contact's canonical text user_id key AFTER this resolve
1244
+ * (`external_id ?? anonymous_id ?? id`), i.e. {@link contactKey} of the final
1245
+ * row — for a merge, the SURVIVOR's key. Lets callers (ingestEvent) key the
1246
+ * history tables without a second read-back of the contact row.
1247
+ */
1248
+ resolvedKey: string;
1249
+ created: boolean;
1250
+ linked: boolean;
1251
+ merged: boolean;
1252
+ /**
1253
+ * SAFE-to-absorb loser keys (§5.3 MF-2): the anonymous/uuid keys the resolver
1254
+ * folded INTO `resolvedKey` this call — populated only on a collide-MERGE or a
1255
+ * canonical-key flip that absorbed an anon/uuid key. Callers fan these out via
1256
+ * `mergeAnalyticsIdentities({ distinctId: resolvedKey, alias: <key> })`. An
1257
+ * `external_id` is NEVER listed here (it carried an identified PostHog person;
1258
+ * aliasing it is the merge PostHog refuses — R2/R4); it surfaces in
1259
+ * {@link mergedIdentifiedKeys} instead. Empty/absent ⇒ nothing to stitch.
1260
+ */
1261
+ mergedKeys?: string[];
1262
+ /**
1263
+ * Loser keys MF-2 could NOT safely absorb — already-identified `external_id`s
1264
+ * (and the superseded `external_id` on a key flip). These are the known
1265
+ * steady-state twin residual (§10, OQ-1); callers log them as
1266
+ * `identity.merge.residual_twin` for observability. Never aliased.
1267
+ */
1268
+ mergedIdentifiedKeys?: string[];
1269
+ }> {
1270
+ // PRD 06: this entry point is create-on-miss BY CONTRACT — honouring a
1271
+ // refuse-on-miss policy here would make the refusal arm reachable and force
1272
+ // the published `id: string` to widen (D3). Reject loudly rather than guess.
1273
+ if (opts.policy && opts.policy.create !== "on-miss") {
1274
+ throw new Error(
1275
+ "resolveOrCreateContact is create-on-miss by contract (D3: `id` is " +
1276
+ 'never null) — use resolveContactNoCreate for `create: "refuse-on-miss"`',
1277
+ );
1278
+ }
1279
+ const resolved = await resolveContactShared(opts);
1280
+ if (resolved.id === null) {
1281
+ // Unreachable: `refuseCreateWithKey` is never set on this path (and a
1282
+ // refuse-on-miss policy is rejected above), so every arm either resolves a
1283
+ // row or inserts one. Narrows `id` without a cast.
1284
+ throw new Error("resolveOrCreateContact resolved to no contact");
1285
+ }
1286
+ return { ...resolved, id: resolved.id };
1287
+ }
1288
+
1289
+ /**
1290
+ * THE resolver's refuse-on-miss sibling (D1/D3). Same implementation, same
1291
+ * fill-in-link and collide-MERGE behavior — the ONLY difference is that a miss
1292
+ * returns `{ id: null }` instead of minting a `contacts` row. Use it wherever a
1293
+ * write is pure OBSERVATION (an unidentified browser, a chat-gateway presence
1294
+ * ping): seeing traffic is not grounds for a CRM row, and the event still
1295
+ * stores under `resolvedKey` (D2), so journey routing, exit checks and
1296
+ * analytics mirroring are untouched.
1297
+ *
1298
+ * PRECONDITION (D8) — THROWS unless the highest-precedence supplied key is
1299
+ * `userId` or `anonymousId`. The canonical key is
1300
+ * `contactKey = external_id ?? anonymous_id ?? id`, so `email` and `discord_id`
1301
+ * are NEVER canonical: for an email-only / discord-only call today's code keys
1302
+ * history on the freshly-minted row's uuid, which a refusal cannot reproduce and
1303
+ * for which no repoint path back exists. Refusal there would strand history, so
1304
+ * the shape is rejected as a misuse rather than silently mis-keyed.
1305
+ *
1306
+ * The refusal key is exactly what the create arm would have made canonical for
1307
+ * the two permitted shapes (`userId ?? anonymousId`), so a refused call and a
1308
+ * creating one agree on `resolvedKey` byte-for-byte.
1309
+ */
1310
+ export async function resolveContactNoCreate(
1311
+ opts: ResolveContactOptions,
1312
+ ): Promise<{
1313
+ /** `null` ⇒ REFUSED: no live contact owned any supplied key, and none was
1314
+ * minted. Otherwise the resolved (linked/merged) contact's id. */
1315
+ id: string | null;
1316
+ /** As {@link resolveOrCreateContact}; on a refusal, the supplied key. */
1317
+ resolvedKey: string;
1318
+ /** Always false — this entry point never mints. */
1319
+ created: false;
1320
+ linked: boolean;
1321
+ merged: boolean;
1322
+ mergedKeys?: string[];
1323
+ mergedIdentifiedKeys?: string[];
1324
+ }> {
1325
+ // Mirror the shared body's normalization so the precondition reads the same
1326
+ // keys resolution will (a whitespace-only `userId` is not a supplied key).
1327
+ const userId = opts.userId?.trim() || undefined;
1328
+ const anonymousId = opts.anonymousId?.trim() || undefined;
1329
+ const refuseCreateWithKey = userId ?? anonymousId;
1330
+ if (!refuseCreateWithKey) {
1331
+ throw new Error(
1332
+ "resolveContactNoCreate requires userId or anonymousId as the " +
1333
+ "highest-precedence key (D8): email/discordId are never canonical, so " +
1334
+ "a refusal there would key history on a row uuid that was never minted",
1335
+ );
1336
+ }
1337
+
1338
+ // PRD 06: with a declared policy the legacy internal channel stays UNSET —
1339
+ // the shared body re-derives the identical `userId ?? anonymousId` refusal
1340
+ // key from the same normalized locals (validated present above), so `policy`
1341
+ // and `refuseCreateWithKey` can never collide.
1342
+ if (opts.policy) {
1343
+ if (opts.policy.create !== "refuse-on-miss") {
1344
+ throw new Error(
1345
+ "resolveContactNoCreate never mints (`created` is pinned false) — " +
1346
+ 'its policy must declare `create: "refuse-on-miss"`; use ' +
1347
+ "resolveOrCreateContact for create-on-miss",
1348
+ );
1349
+ }
1350
+ const resolved = await resolveContactShared(opts);
1351
+ return { ...resolved, created: false };
1352
+ }
1353
+
1354
+ const resolved = await resolveContactShared({ ...opts, refuseCreateWithKey });
1355
+ // Structurally always false (the create arm is refused above); pinned in the
1356
+ // type so callers can't branch on a create this entry point cannot perform.
1357
+ return { ...resolved, created: false };
1358
+ }
1359
+
752
1360
  interface ResolveCtx {
753
1361
  userId?: string;
754
1362
  email?: string;
@@ -762,9 +1370,16 @@ interface ResolveCtx {
762
1370
  }
763
1371
 
764
1372
  /**
765
- * Single matching row: fill any identity keys it is missing, record a `'promote'`
766
- * alias for each newly-attached key (provenance + belt-and-suspenders so the key
767
- * still resolves through the alias path), and apply the property patch.
1373
+ * Single matching row: claim every supplied identity key the row does not
1374
+ * already hold (column when free — the legacy dual-write — identity row
1375
+ * ALWAYS), apply the property patch, then repoint/adopt history where the
1376
+ * claims require it.
1377
+ *
1378
+ * PRD 03 shape — the arm PLANS, {@link claimIdentityKey} EXECUTES: one ordered
1379
+ * pass over the supplied keys replaces the old per-kind attach branches, whose
1380
+ * arm-local side effects are how the if-arm shipped without the foreign-key
1381
+ * gate. "The column is taken" is a non-event now: a second/third value per
1382
+ * kind is just another identity row, for every kind alike.
768
1383
  */
769
1384
  async function fillInLink(
770
1385
  tx: Tx,
@@ -780,7 +1395,6 @@ async function fillInLink(
780
1395
  lastSeenAt: new Date(),
781
1396
  updatedAt: new Date(),
782
1397
  };
783
- const promoted: ResolveKey[] = [];
784
1398
 
785
1399
  // The contact's canonical string key BEFORE this fill (external_id ??
786
1400
  // anonymous_id ?? id). Attaching an external_id (or anonymous_id where none
@@ -791,28 +1405,84 @@ async function fillInLink(
791
1405
  let nextExternalId = row.externalId;
792
1406
  let nextAnonymousId = row.anonymousId;
793
1407
 
794
- if (ctx.userId && !row.externalId) {
795
- set.externalId = ctx.userId;
796
- nextExternalId = ctx.userId;
797
- promoted.push({ kind: "external", value: ctx.userId });
798
- }
799
- if (ctx.email && !row.email) {
800
- set.email = ctx.email;
801
- promoted.push({ kind: "email", value: ctx.email });
802
- }
803
- // discord_id is an attachable resolvable key but NEVER the canonical key
804
- // (external_id ?? anonymous_id ?? id), so it does NOT touch
805
- // nextExternalId/nextAnonymousId — gaining it never flips the canonical key,
806
- // so no own-history re-point follows.
807
- if (ctx.discordId && !row.discordId) {
808
- set.discordId = ctx.discordId;
809
- promoted.push({ kind: "discord", value: ctx.discordId });
810
- }
811
- if (ctx.anonymousId && !row.anonymousId) {
812
- set.anonymousId = ctx.anonymousId;
813
- nextAnonymousId = ctx.anonymousId;
814
- promoted.push({ kind: "anonymous", value: ctx.anonymousId });
1408
+ // The supplied keys, in the resolver's precedence order. `current` is the
1409
+ // column value the row holds for that kind today; `column` names the legacy
1410
+ // dual-write slot (retired in PRD 07). Note discord_id / email are attachable
1411
+ // resolvable keys but NEVER the canonical key (external_id ?? anonymous_id ??
1412
+ // id) — gaining either never flips the canonical key, so neither touches
1413
+ // nextExternalId/nextAnonymousId below.
1414
+ const supplied: {
1415
+ kind: Kind;
1416
+ value: string;
1417
+ current: string | null;
1418
+ column: "externalId" | "email" | "anonymousId" | "discordId";
1419
+ }[] = [];
1420
+ if (ctx.userId)
1421
+ supplied.push({
1422
+ kind: "external",
1423
+ value: ctx.userId,
1424
+ current: row.externalId,
1425
+ column: "externalId",
1426
+ });
1427
+ if (ctx.email)
1428
+ supplied.push({
1429
+ kind: "email",
1430
+ value: ctx.email,
1431
+ current: row.email,
1432
+ column: "email",
1433
+ });
1434
+ if (ctx.anonymousId)
1435
+ supplied.push({
1436
+ kind: "anonymous",
1437
+ value: ctx.anonymousId,
1438
+ current: row.anonymousId,
1439
+ column: "anonymousId",
1440
+ });
1441
+ if (ctx.discordId)
1442
+ supplied.push({
1443
+ kind: "discord",
1444
+ value: ctx.discordId,
1445
+ current: row.discordId,
1446
+ column: "discordId",
1447
+ });
1448
+
1449
+ // Keys THIS call was first to claim — the adoption/report signal. Refused
1450
+ // (foreign) keys never enter it; repeat claims conflict on the unique index
1451
+ // and never re-enter it. A person browses from more than one device, and
1452
+ // `contacts.anonymous_id` holds exactly one — `contact_aliases` is the
1453
+ // multi-key table, and `findByKey` reads it first, so any claimed value
1454
+ // resolves back here once recorded.
1455
+ const foreignMemo = new Map<string, boolean>();
1456
+ const claimed: ResolveKey[] = [];
1457
+
1458
+ for (const s of supplied) {
1459
+ // Hottest path there is (every repeat page view from a known device): the
1460
+ // value is already the row's column value — nothing to claim, no queries.
1461
+ if (s.value === s.current) continue;
1462
+
1463
+ const outcome = await claimIdentityKey(
1464
+ tx,
1465
+ row,
1466
+ { kind: s.kind, value: s.value },
1467
+ foreignMemo,
1468
+ );
1469
+ // A refused (foreign-canonical-key) claim skips EVERYTHING for this key:
1470
+ // no column write (an external write would flip the canonical key and
1471
+ // repoint the claimant's history INTO a string someone else's rows key
1472
+ // on), no identity row, no adoption, no mergedKeys report.
1473
+ if (outcome === "refused") continue;
1474
+
1475
+ if (s.current == null) {
1476
+ // Legacy dual-write: the column when it happens to be free (PRD 07
1477
+ // retires the columns; writing them keeps every column-only reader
1478
+ // working until then).
1479
+ set[s.column] = s.value;
1480
+ if (s.kind === "external") nextExternalId = s.value;
1481
+ if (s.kind === "anonymous") nextAnonymousId = s.value;
1482
+ }
1483
+ if (outcome === "claimed") claimed.push({ kind: s.kind, value: s.value });
815
1484
  }
1485
+
816
1486
  // First-touch provenance: only stamp when the row has none, so an inbound
817
1487
  // contact that a Source later re-touches keeps its original origin.
818
1488
  if (ctx.source && !row.source) {
@@ -836,15 +1506,19 @@ async function fillInLink(
836
1506
  // had NO external_id (attaching one never happens to an already-external row),
837
1507
  // so `oldKey` is structurally always anon/uuid here — the explicit gate guards
838
1508
  // the invariant regardless.
1509
+ const updatedRow: ContactRow = {
1510
+ ...row,
1511
+ externalId: nextExternalId,
1512
+ anonymousId: nextAnonymousId,
1513
+ email: (set.email as string | undefined) ?? row.email,
1514
+ // Post-fill discord id: not part of the canonical key, but the PRD 02
1515
+ // dual-write below records an alias per column the row NOW carries.
1516
+ discordId: (set.discordId as string | undefined) ?? row.discordId,
1517
+ };
1518
+
839
1519
  let mergedKeys: string[] | undefined;
840
1520
  let mergedIdentifiedKeys: string[] | undefined;
841
1521
  if (newKey !== oldKey) {
842
- const updatedRow: ContactRow = {
843
- ...row,
844
- externalId: nextExternalId,
845
- anonymousId: nextAnonymousId,
846
- email: (set.email as string | undefined) ?? row.email,
847
- };
848
1522
  await repointOwnHistory(tx, oldKey, newKey, updatedRow);
849
1523
 
850
1524
  const oldKeyWasExternalId =
@@ -856,21 +1530,56 @@ async function fillInLink(
856
1530
  }
857
1531
  }
858
1532
 
859
- for (const key of promoted) {
860
- await tx
861
- .insert(contactAliases)
862
- .values({
863
- contactId: row.id,
864
- aliasKind: key.kind,
865
- aliasValue: key.value,
866
- fromContactId: null,
867
- reason: "promote",
868
- })
869
- .onConflictDoNothing({
870
- target: [contactAliases.aliasKind, contactAliases.aliasValue],
871
- });
1533
+ // ADOPT ORPHANED ANON HISTORY — the second-order effect of refusing to mint
1534
+ // on observation. When an anon id is newly claimed but does NOT become the
1535
+ // canonical key (the row already had an `external_id`), the flip test above is
1536
+ // false, so nothing above this moves the history keyed on that anon id.
1537
+ //
1538
+ // That is the docs sign-in order exactly: the server-side fold resolves
1539
+ // { email, userId } with no anon id and CREATES the row already carrying
1540
+ // `external_id`; the browser's `identify()` then arrives with the anon id and
1541
+ // lands here. Before observation-refusal shipped, a contact row existed for
1542
+ // the anon id and the collide-MERGE arm adopted its history; refusal removed
1543
+ // that row, and with it the only arm that did the adoption. Without this, a
1544
+ // visitor who browses anonymously and then registers keeps their contact but
1545
+ // loses every event, journey state, send and preference recorded before they
1546
+ // signed up.
1547
+ //
1548
+ // It also covers the SECOND-DEVICE shape, which the same refusal broke the
1549
+ // same way: the row's `anonymous_id` column is already taken by the first
1550
+ // device, so the id from a second one is claimed as an identity row above,
1551
+ // and its pre-sign-in history is adopted here.
1552
+ //
1553
+ // Adoption is ANONYMOUS-ONLY (claiming adds a resolution edge; adopting MOVES
1554
+ // rows — a second external/email/discord value never keyed this person's
1555
+ // history, so there is nothing to move; PRD 04 reunites externally-keyed rows
1556
+ // through the identity row instead). Foreign keys never reach this loop: the
1557
+ // claim path refused them before `claimed` was built. That refusal is the
1558
+ // ONLY thing standing between a caller and someone else's rows — this shape
1559
+ // carries a `userId`, so `restrictToAnonymous` is false by construction (it
1560
+ // requires `!userId`) and neither publishable clamp fires. A `userToken`
1561
+ // proves which account the caller is; it says nothing about which
1562
+ // `anonymousId` they may name, and a canonical key is a far weaker secret
1563
+ // than a browser-local id (it is frequently a sequential or public account
1564
+ // id). First-claim-only by construction (`claimed` is populated from the
1565
+ // insert's `returning()`), so a browser that identifies on every page load
1566
+ // cannot re-adopt or re-fire the analytics stitch — the re-stitch storm
1567
+ // guard, structural instead of remembered.
1568
+ for (const key of claimed) {
1569
+ if (key.kind !== "anonymous") continue;
1570
+ if (key.value === newKey || key.value === oldKey) continue;
1571
+ await repointOwnHistory(tx, key.value, newKey, updatedRow);
1572
+ // Reported so `mergeAnalyticsIdentities` still fires the anon→known stitch;
1573
+ // appended, since a key flip above may already have folded a uuid/anon key.
1574
+ mergedKeys = [...(mergedKeys ?? []), key.value];
872
1575
  }
873
1576
 
1577
+ // PRD 02 dual-write, AFTER the claim pass so newly-claimed keys keep their
1578
+ // `promote` provenance and only the row's pre-existing (pre-alias-era)
1579
+ // columns gain `resolve` rows. This is what backfills a hot contact whose
1580
+ // columns predate `contact_aliases`, without waiting for the offline job.
1581
+ await ensureIdentityAliases(tx, updatedRow);
1582
+
874
1583
  // `newKey` IS the post-fill canonical key (external_id ?? anonymous_id ?? id) —
875
1584
  // the same value the old read-back derived.
876
1585
  return { id: row.id, resolvedKey: newKey, mergedKeys, mergedIdentifiedKeys };
@@ -1078,6 +1787,54 @@ async function mergeContacts(
1078
1787
  .set(survivorSet)
1079
1788
  .where(eq(contacts.id, survivor.id));
1080
1789
 
1790
+ // The survivor as it stands AFTER the update above — what the claim step and
1791
+ // the PRD 02 dual-write below both key off.
1792
+ const postSurvivor: ContactRow = {
1793
+ ...survivor,
1794
+ externalId:
1795
+ (survivorSet.externalId as string | undefined) ?? survivor.externalId,
1796
+ email: (survivorSet.email as string | undefined) ?? survivor.email,
1797
+ anonymousId:
1798
+ (survivorSet.anonymousId as string | undefined) ?? survivor.anonymousId,
1799
+ discordId:
1800
+ (survivorSet.discordId as string | undefined) ?? survivor.discordId,
1801
+ };
1802
+
1803
+ // PRD 03 T4 — claim CALL-supplied keys the survivor's columns could not
1804
+ // hold. Loser-held keys already survive as identity rows via
1805
+ // `recordMergeAliases`; the only drop left was a ctx key when the survivor's
1806
+ // column was already occupied — each `if (!survivor.<column>)` block above
1807
+ // picks one value and used to discard the rest. Runs AFTER the loser
1808
+ // soft-delete (the partial-unique live indexes are already free — the same
1809
+ // ordering the survivorSet copy depends on) and AFTER the survivor update.
1810
+ // Same gate as fill-in-link: an external/anonymous value that is another
1811
+ // live contact's canonical key is refused, not aliased — a merge arm reached
1812
+ // with a foreign key (one the candidate probes never matched) must not mint
1813
+ // a resolution edge to someone else's person. NO adoption here: every
1814
+ // absorbed candidate key's history was already folded by the loser rewrites
1815
+ // above; a claimed second value never keyed history at all.
1816
+ {
1817
+ const foreignMemo = new Map<string, boolean>();
1818
+ const unheld: ResolveKey[] = [];
1819
+ if (ctx.userId && ctx.userId !== postSurvivor.externalId)
1820
+ unheld.push({ kind: "external", value: ctx.userId });
1821
+ if (ctx.email && ctx.email !== postSurvivor.email)
1822
+ unheld.push({ kind: "email", value: ctx.email });
1823
+ if (ctx.anonymousId && ctx.anonymousId !== postSurvivor.anonymousId)
1824
+ unheld.push({ kind: "anonymous", value: ctx.anonymousId });
1825
+ if (ctx.discordId && ctx.discordId !== postSurvivor.discordId)
1826
+ unheld.push({ kind: "discord", value: ctx.discordId });
1827
+ for (const key of unheld) {
1828
+ await claimIdentityKey(tx, postSurvivor, key, foreignMemo);
1829
+ }
1830
+ }
1831
+
1832
+ // PRD 02 dual-write on the POST-merge survivor row: a `resolve` alias per
1833
+ // identity column it now carries. Runs AFTER `recordMergeAliases` (inside the
1834
+ // loser loop above), so the loser keys' `merge` provenance wins the conflict
1835
+ // and only the survivor's pre-alias-era keys gain rows here.
1836
+ await ensureIdentityAliases(tx, postSurvivor);
1837
+
1081
1838
  // If the survivor's canonical key flipped (it had no external_id/anonymous_id
1082
1839
  // and the merge promoted one from the call/loser), re-point the survivor's OWN
1083
1840
  // history — including everything the loser rewrites just pointed at the old
@@ -1547,6 +2304,123 @@ async function recordMergeAliases(
1547
2304
  });
1548
2305
  }
1549
2306
 
2307
+ /**
2308
+ * PRD 02 T2 — the identity-table dual-write. Ensures a `contact_aliases` row
2309
+ * exists for EVERY identity column the contact carries after a resolve (create /
2310
+ * fill-in-link / collide-merge survivor). Runs inside the resolver transaction
2311
+ * on the hottest write path in the engine, so it is shaped for the steady
2312
+ * state:
2313
+ *
2314
+ * 1. ONE batched SELECT over the row's `(kind, value)` pairs (≤4 rows via the
2315
+ * unique index). On a repeat resolve every pair already exists and this is
2316
+ * the ONLY statement — no insert, no conflict churn, no `updated_at` writes.
2317
+ * 2. ONE batched INSERT for the missing pairs only, `onConflictDoNothing` on
2318
+ * `(alias_kind, alias_value)` as the race guard (concurrent resolvers for
2319
+ * the same key already serialize on the advisory locks; a cross-key race
2320
+ * lands here and is silently deduped). Never a per-key loop.
2321
+ *
2322
+ * A pair owned by a DIFFERENT contact is never repointed (the backfill's
2323
+ * "never steals" rule, applied online) — it is skipped and logged as
2324
+ * `identity.alias.conflict` with the KIND and contact id only, never the value
2325
+ * (alias values are emails and account ids). Rows written here carry
2326
+ * `reason: 'resolve'` and `from_contact_id: NULL` — "this contact holds this
2327
+ * key right now", the index entry, not a provenance event — so the existing
2328
+ * `promote`/`merge` writers (which always run BEFORE this in their arms) win
2329
+ * the conflict and keep their provenance.
2330
+ *
2331
+ * The email pair is NORMALIZED (`normalizeEmail`) even when the legacy column
2332
+ * value is mixed-case, because the alias probe compares against the normalized
2333
+ * value the resolver always supplies.
2334
+ */
2335
+ async function ensureIdentityAliases(tx: Tx, row: ContactRow): Promise<void> {
2336
+ const email = normalizeEmailOrNull(row.email);
2337
+ const pairs: { kind: Kind; value: string }[] = [];
2338
+ if (row.externalId) pairs.push({ kind: "external", value: row.externalId });
2339
+ if (email) pairs.push({ kind: "email", value: email });
2340
+ if (row.anonymousId)
2341
+ pairs.push({ kind: "anonymous", value: row.anonymousId });
2342
+ if (row.discordId) pairs.push({ kind: "discord", value: row.discordId });
2343
+ if (pairs.length === 0) return;
2344
+
2345
+ const existing = await tx
2346
+ .select({
2347
+ aliasKind: contactAliases.aliasKind,
2348
+ aliasValue: contactAliases.aliasValue,
2349
+ contactId: contactAliases.contactId,
2350
+ })
2351
+ .from(contactAliases)
2352
+ .where(
2353
+ or(
2354
+ ...pairs.map((p) =>
2355
+ and(
2356
+ eq(contactAliases.aliasKind, p.kind),
2357
+ eq(contactAliases.aliasValue, p.value),
2358
+ ),
2359
+ ),
2360
+ ),
2361
+ );
2362
+
2363
+ const held = new Map(
2364
+ existing.map((r) => [`${r.aliasKind}|${r.aliasValue}`, r.contactId]),
2365
+ );
2366
+ const foreignKinds = existing
2367
+ .filter((r) => r.contactId !== row.id)
2368
+ .map((r) => r.aliasKind);
2369
+ if (foreignKinds.length > 0) {
2370
+ logger.warn("identity.alias.conflict", {
2371
+ contactId: row.id,
2372
+ kinds: foreignKinds,
2373
+ });
2374
+ }
2375
+
2376
+ const missing = pairs.filter((p) => !held.has(`${p.kind}|${p.value}`));
2377
+ if (missing.length === 0) return;
2378
+
2379
+ await tx
2380
+ .insert(contactAliases)
2381
+ .values(
2382
+ missing.map((p) => ({
2383
+ contactId: row.id,
2384
+ aliasKind: p.kind,
2385
+ aliasValue: p.value,
2386
+ fromContactId: null,
2387
+ reason: ALIAS_REASON_RESOLVE,
2388
+ })),
2389
+ )
2390
+ .onConflictDoNothing({
2391
+ target: [contactAliases.aliasKind, contactAliases.aliasValue],
2392
+ });
2393
+ }
2394
+
2395
+ /**
2396
+ * PRD 02 T1 — the erasure hook. Deletes EVERY `contact_aliases` row whose
2397
+ * `contact_id` is the erased contact — no `reason` filter, no `from_contact_id`
2398
+ * filter. Two earlier revisions of this rule each kept a subset and each kept a
2399
+ * leak: `promote` rows hold the person's own email; ABSORBED rows
2400
+ * (`from_contact_id` set) hold the same human's pre-merge email in the common
2401
+ * merge. The erasure question is "whose data is this?", and for any row keyed
2402
+ * to the erased contact the answer is always *theirs*.
2403
+ *
2404
+ * This does NOT strand `followToSurvivor`: that walk follows rows by
2405
+ * `from_contact_id = <loser>`, and those rows live under the SURVIVOR's
2406
+ * `contact_id` — erasing a loser touches none of them, and erasing a survivor
2407
+ * makes the chain into it moot (the alias probe only resolves live contacts).
2408
+ *
2409
+ * Called from both soft-delete sites (`softDeleteContact` and the admin
2410
+ * `DELETE /v1/admin/contacts/:id` route) inside their transactions. The merge
2411
+ * path's loser soft-delete is deliberately NOT a caller — a merge is a fold,
2412
+ * not an erasure, and its aliases (pointing at the survivor) are the mechanism
2413
+ * that keeps the loser's stale keys resolving.
2414
+ */
2415
+ export async function deleteIdentityAliasesForContact(
2416
+ db: Database | Tx,
2417
+ contactId: string,
2418
+ ): Promise<void> {
2419
+ await db
2420
+ .delete(contactAliases)
2421
+ .where(eq(contactAliases.contactId, contactId));
2422
+ }
2423
+
1550
2424
  // ---------------------------------------------------------------------------
1551
2425
  // Retained wrapper + public-route helpers
1552
2426
  // ---------------------------------------------------------------------------
@@ -1638,22 +2512,35 @@ export async function softDeleteContact(opts: {
1638
2512
  const email = opts.email ? normalizeEmail(opts.email) : undefined;
1639
2513
  const userId = opts.userId?.trim() || undefined;
1640
2514
 
1641
- const clauses = [];
2515
+ // Annotated (unlike findContacts' evolving-any) because the array is read
2516
+ // inside the transaction closure below, where inference cannot follow it.
2517
+ const clauses: SQL[] = [];
1642
2518
  if (email) clauses.push(eq(contacts.email, email));
1643
2519
  if (userId) clauses.push(eq(contacts.externalId, userId));
1644
2520
  if (clauses.length === 0) return { deleted: false };
1645
2521
 
1646
- const updated = await db
1647
- .update(contacts)
1648
- .set({ deletedAt: new Date(), updatedAt: new Date() })
1649
- .where(and(or(...clauses), isNull(contacts.deletedAt)))
1650
- .returning({
1651
- id: contacts.id,
1652
- externalId: contacts.externalId,
1653
- email: contacts.email,
1654
- });
2522
+ // One transaction: the soft-delete and its erasure hook (PRD 02 T1 — every
2523
+ // contact_aliases row for the erased contact goes with it) commit or roll
2524
+ // back together, so a failure cannot leave identity keys stranded in the
2525
+ // alias table for a deleted person.
2526
+ const row = await db.transaction(async (tx) => {
2527
+ const updated = await tx
2528
+ .update(contacts)
2529
+ .set({ deletedAt: new Date(), updatedAt: new Date() })
2530
+ .where(and(or(...clauses), isNull(contacts.deletedAt)))
2531
+ .returning({
2532
+ id: contacts.id,
2533
+ externalId: contacts.externalId,
2534
+ email: contacts.email,
2535
+ });
2536
+ // The or(email, userId) filter can match TWO distinct contacts in one
2537
+ // call; every soft-deleted row gets its erasure, not just the reported one.
2538
+ for (const deleted of updated) {
2539
+ await deleteIdentityAliasesForContact(tx, deleted.id);
2540
+ }
2541
+ return updated[0];
2542
+ });
1655
2543
 
1656
- const row = updated[0];
1657
2544
  if (!row) return { deleted: false };
1658
2545
 
1659
2546
  return {
@@ -1737,9 +2624,12 @@ export async function resolveRecipient(opts: {
1737
2624
  };
1738
2625
  }
1739
2626
 
1740
- /** Alias-aware lookup helper for resolveRecipient (mirrors findByKey but on the
1741
- * top-level db handle, no tx). */
1742
- async function resolveViaAlias(
2627
+ /** Alias-aware lookup helper (mirrors findByKey's alias probe but on the
2628
+ * top-level db handle, no tx). Engine-internal export: `resolveRecipient`
2629
+ * below and the feed's anonymous-recipient resolver (PRD 03 T5 — a second
2630
+ * device's anon id lives ONLY as an identity row) both fall back to it after
2631
+ * their column probes miss. */
2632
+ export async function resolveViaAlias(
1743
2633
  db: Database,
1744
2634
  kind: Kind,
1745
2635
  value: string,