@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.
- package/package.json +11 -11
- package/src/buckets/bucket-access.ts +5 -10
- package/src/buckets/check-membership.ts +78 -6
- package/src/index.ts +31 -1
- package/src/journeys/execute-journey-run.ts +56 -1
- package/src/journeys/journey-context.ts +59 -0
- package/src/lib/bucket-emit.test.ts +83 -2
- package/src/lib/bucket-emit.ts +16 -0
- package/src/lib/contacts.ts +1031 -141
- package/src/lib/crm-ingest.ts +9 -0
- package/src/lib/feed.ts +64 -3
- package/src/lib/identity-service.ts +15 -2
- package/src/lib/ingestion.ts +180 -14
- package/src/lib/tracking-events.ts +33 -6
- package/src/routes/admin/agent.ts +26 -0
- package/src/routes/admin/contacts.ts +65 -5
- package/src/routes/admin/identity.ts +197 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/contacts/index.ts +50 -7
- package/src/routes/events/index.ts +94 -6
- package/src/routes/feed/index.ts +36 -0
- package/src/routes/feed/recipient.ts +44 -2
- package/src/routes/lists/index.ts +21 -0
- package/src/routes/tracking/arrive.ts +42 -3
- package/src/worker.ts +18 -0
- package/src/workflows/bucket-backfill.ts +1 -1
- package/src/workflows/bucket-reconcile.ts +129 -4
- package/src/workflows/identity-alias-backfill.ts +448 -0
- package/src/workflows/import-contacts.ts +10 -0
- package/src/workflows/send-campaign.ts +31 -13
package/src/lib/contacts.ts
CHANGED
|
@@ -11,11 +11,38 @@ import {
|
|
|
11
11
|
journeyStates,
|
|
12
12
|
userEvents,
|
|
13
13
|
} from "@hogsend/db";
|
|
14
|
-
import {
|
|
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
|
-
|
|
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)
|
|
227
|
-
*
|
|
228
|
-
*
|
|
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
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
506
|
-
*
|
|
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
|
-
|
|
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
|
-
}
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
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
|
-
|
|
603
|
-
//
|
|
604
|
-
//
|
|
605
|
-
//
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
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 `!
|
|
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) && !
|
|
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:
|
|
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 (
|
|
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
|
-
|
|
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:
|
|
766
|
-
*
|
|
767
|
-
*
|
|
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
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
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
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1647
|
-
|
|
1648
|
-
|
|
1649
|
-
|
|
1650
|
-
|
|
1651
|
-
|
|
1652
|
-
|
|
1653
|
-
|
|
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
|
|
1741
|
-
* top-level db handle, no tx).
|
|
1742
|
-
|
|
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,
|