@hogsend/engine 0.55.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.
Files changed (37) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +5 -10
  3. package/src/buckets/check-membership.ts +91 -6
  4. package/src/index.ts +31 -1
  5. package/src/journeys/execute-journey-run.ts +56 -1
  6. package/src/journeys/journey-context.ts +59 -0
  7. package/src/lib/bucket-emit.test.ts +83 -2
  8. package/src/lib/bucket-emit.ts +16 -0
  9. package/src/lib/contacts.ts +1031 -141
  10. package/src/lib/crm-ingest.ts +9 -0
  11. package/src/lib/enrichment-ledger.ts +1 -1
  12. package/src/lib/feed.ts +64 -3
  13. package/src/lib/identity-service.ts +15 -2
  14. package/src/lib/ingestion.ts +191 -14
  15. package/src/lib/outbound.ts +3 -3
  16. package/src/lib/refine-chain.test.ts +83 -25
  17. package/src/lib/refine-chain.ts +124 -23
  18. package/src/lib/refine-traits.test.ts +74 -41
  19. package/src/lib/refine-traits.ts +107 -52
  20. package/src/lib/refine.ts +28 -27
  21. package/src/lib/tracking-events.ts +33 -6
  22. package/src/routes/admin/agent.ts +26 -0
  23. package/src/routes/admin/contacts.ts +65 -5
  24. package/src/routes/admin/identity.ts +197 -0
  25. package/src/routes/admin/index.ts +2 -0
  26. package/src/routes/contacts/index.ts +50 -7
  27. package/src/routes/events/index.ts +94 -6
  28. package/src/routes/feed/index.ts +36 -0
  29. package/src/routes/feed/recipient.ts +44 -2
  30. package/src/routes/lists/index.ts +21 -0
  31. package/src/routes/tracking/arrive.ts +42 -3
  32. package/src/worker.ts +18 -0
  33. package/src/workflows/bucket-backfill.ts +1 -1
  34. package/src/workflows/bucket-reconcile.ts +129 -4
  35. package/src/workflows/identity-alias-backfill.ts +448 -0
  36. package/src/workflows/import-contacts.ts +10 -0
  37. package/src/workflows/send-campaign.ts +31 -13
package/src/worker.ts CHANGED
@@ -31,6 +31,10 @@ import {
31
31
  reapDueWebhookDeliveriesTask,
32
32
  } from "./workflows/deliver-webhook.js";
33
33
  import { dispatchConversionTask } from "./workflows/dispatch-conversion.js";
34
+ import {
35
+ enqueueIdentityAliasBackfill,
36
+ identityAliasBackfillTask,
37
+ } from "./workflows/identity-alias-backfill.js";
34
38
  import { impactDigestTask } from "./workflows/impact-digest.js";
35
39
  import { importContactsTask } from "./workflows/import-contacts.js";
36
40
  import { importSuppressionsTask } from "./workflows/import-suppressions.js";
@@ -132,6 +136,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
132
136
  impactDigestTask,
133
137
  bucketReconcileTask,
134
138
  bucketBackfillTask,
139
+ identityAliasBackfillTask,
135
140
  crmReconcileTask,
136
141
  dispatchConversionTask,
137
142
  ...journeyTasks,
@@ -228,6 +233,19 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
228
233
  });
229
234
  });
230
235
 
236
+ // PRD 02: fill `contact_aliases` once per deployment (skipped when a
237
+ // non-failed job record exists). Same fire-and-forget, best-effort stance
238
+ // as the bucket backfills above; internally try/caught, `.catch` is the
239
+ // belt-and-suspenders.
240
+ enqueueIdentityAliasBackfill({
241
+ db: container.db,
242
+ logger: container.logger,
243
+ }).catch((err) => {
244
+ container.logger.warn("Identity alias backfill enqueue (boot) failed", {
245
+ error: err instanceof Error ? err.message : String(err),
246
+ });
247
+ });
248
+
231
249
  // Reconcile code-defined campaigns into scheduled rows (create / sync /
232
250
  // expire — see `reconcileDefinedCampaigns`). Same fire-and-forget stance
233
251
  // as the bucket backfills above: best-effort, never blocks the listener.
@@ -353,7 +353,7 @@ async function reevalLeaves(opts: {
353
353
  entryCount: bucketMemberships.entryCount,
354
354
  })
355
355
  .from(bucketMemberships)
356
- .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
356
+ .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
357
357
  .where(
358
358
  and(
359
359
  eq(bucketMemberships.bucketId, bucket.id),
@@ -118,6 +118,14 @@ export const bucketReconcileTask = hatchet.task({
118
118
  if (!timeBased && !bucket.maxDwell && !hasDwell) continue;
119
119
 
120
120
  try {
121
+ // ONE-SHOT COHORT CLAIM — the first-tick guard for the join-key fix.
122
+ // Until this bucket has been claimed, its previously-invisible members
123
+ // (canonical key != external_id) carry age clocks that ran unwatched,
124
+ // so every age-driven emission is due AT ONCE. Reset those clocks
125
+ // instead of firing the backlog, then skip this bucket for this tick so
126
+ // no pass can act on a cohort mid-reset. The next tick is normal.
127
+ if (await claimCoalesceCohort({ db, logger, bucket })) continue;
128
+
121
129
  if (timeBased) {
122
130
  reconciled += await reconcileBucketLeaves({
123
131
  db,
@@ -209,6 +217,15 @@ export interface BucketArmExpiryInput extends JsonObject {
209
217
  armedExpiresAt: string;
210
218
  /** ms from arming to the deadline (the durable sleep). */
211
219
  msUntilExpiry: number;
220
+ /**
221
+ * D1 creation guard inherited from the ingest that armed this timer, present
222
+ * ONLY when that ingest REFUSED (`armExpiryTimer` omits the key otherwise, so
223
+ * an unset value keeps today's create-by-default semantics and no JSON null
224
+ * crosses the wire). Forwarded into the leave `emitBucketTransition` below —
225
+ * the one thing that keeps the woken timer from minting the phantom the
226
+ * synchronous emits already refuse (issue #608, D11 category (iii)).
227
+ */
228
+ allowCreate?: boolean;
212
229
  }
213
230
 
214
231
  export const bucketExpiryTask = hatchet.durableTask({
@@ -290,6 +307,15 @@ export const bucketExpiryTask = hatchet.durableTask({
290
307
  // unforgeable engine-internal provenance the pin requires. A value
291
308
  // lookup here would re-implement exactly the resolution the pin exists
292
309
  // to bypass. Degrades to the pre-pin resolve.
310
+ //
311
+ // The inherited `allowCreate` IS admissible over that same forgeable
312
+ // channel, because its two values are not symmetric in blast radius: a
313
+ // forged `false` can only ever SUPPRESS a write, costing at most a
314
+ // contact the refused ingest would not have created anyway, while a
315
+ // forged `true` is byte-identical to the default this task already had.
316
+ // Neither can fold a transition into a victim's row the way a forged id
317
+ // can — so the boolean rides, and the id stays off the wire.
318
+ allowCreate: input.allowCreate,
293
319
  epoch: flipped.entryCount,
294
320
  source: "reconcile",
295
321
  // Fast-expiry is a criteria re-confirm leave (Section 6.7).
@@ -403,7 +429,7 @@ async function selectEventLeavers(
403
429
  })
404
430
  .from(members)
405
431
  .leftJoin(counted, eq(members.userId, counted.userId))
406
- .innerJoin(contacts, eq(contacts.externalId, members.userId))
432
+ .innerJoin(contacts, eq(contactKeySql(), members.userId))
407
433
  .where(isNull(contacts.deletedAt));
408
434
 
409
435
  return rows
@@ -438,7 +464,7 @@ async function reconcileCompositeLeaves(opts: {
438
464
  properties: contacts.properties,
439
465
  })
440
466
  .from(bucketMemberships)
441
- .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
467
+ .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
442
468
  .where(
443
469
  and(
444
470
  eq(bucketMemberships.bucketId, bucket.id),
@@ -516,7 +542,7 @@ async function reconcileBucketTtlLeaves(opts: {
516
542
  contactId: contacts.id,
517
543
  })
518
544
  .from(bucketMemberships)
519
- .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
545
+ .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
520
546
  .where(
521
547
  and(
522
548
  eq(bucketMemberships.bucketId, bucket.id),
@@ -646,6 +672,105 @@ async function bulkLeave(opts: {
646
672
  * `floor((sweepInstant - anchor) / offsetMs)` (gap-stable, NOT a fire count). For
647
673
  * `after` the ordinal is always 1 (one-shot).
648
674
  */
675
+ /**
676
+ * ONE-SHOT COHORT CLAIM — the first-tick guard for the join-key correction.
677
+ *
678
+ * The leave/dwell passes used to join `contacts.external_id`, while memberships
679
+ * key on the canonical `external_id ?? anonymous_id ?? id`. Every member whose
680
+ * contact carries a NULL `external_id` (email-only, keyed on its uuid;
681
+ * anonymous, keyed on its `anonymous_id`) was therefore enrollable — the join
682
+ * path has always scanned on the coalesce key — but never left, never
683
+ * dwell-fired, never re-evaluated. Their membership-age clocks ran unwatched,
684
+ * frequently for months.
685
+ *
686
+ * Correcting the join makes that whole cohort due AT ONCE. A dwell reaction is
687
+ * a full journey (same `(user, ctx)` shape as a journey `run`), so it can
688
+ * `sendEmail` — the first tick would otherwise deliver a backlog of months-old
689
+ * lifecycle mail to real recipients, which is worse than the bug being fixed.
690
+ *
691
+ * So the first tick RESETS the cohort's age clocks to now instead: the dwell
692
+ * anchor moves to this instant, dwell stamps clear, and a `maxDwell` TTL is
693
+ * re-armed a full window out. Nothing is emitted and nothing is silently
694
+ * swallowed — every age-driven emission still happens, just on an honest
695
+ * schedule measured from the moment the cron could first see the member.
696
+ *
697
+ * Deliberately NOT deferred: criteria-driven leaves. Those evaluate against
698
+ * present-day events and properties, so they are timely rather than stale, and
699
+ * suppressing them would hold members in a bucket they no longer match.
700
+ *
701
+ * Returns `true` ONLY when rows were actually reset — the caller then SKIPS
702
+ * this bucket's passes for this tick so nothing acts on a cohort mid-reset.
703
+ * An EMPTY cohort (the overwhelmingly common case: no email-only or anonymous
704
+ * members, and every deployment that never had any) returns `false` and the
705
+ * tick proceeds normally, so this guard costs nothing where it protects
706
+ * nothing. Either way the claim is recorded on
707
+ * `bucket_configs.coalesceClaimedAt` and never runs again for this bucket:
708
+ * once the join is correct, no member can become stranded, so a member
709
+ * enrolled later starts its age clocks under a cron that can already see it.
710
+ */
711
+ async function claimCoalesceCohort(opts: {
712
+ db: Database;
713
+ logger: Logger;
714
+ bucket: BucketMeta;
715
+ }): Promise<boolean> {
716
+ const { db, logger, bucket } = opts;
717
+
718
+ const config = await db.query.bucketConfigs.findFirst({
719
+ where: eq(bucketConfigs.bucketId, bucket.id),
720
+ });
721
+ if (config?.coalesceClaimedAt != null) return false;
722
+
723
+ const now = new Date();
724
+ const maxDwellMs = bucket.maxDwell ? durationToMs(bucket.maxDwell) : null;
725
+
726
+ // The cohort is exactly "resolves by the canonical key, but NOT by
727
+ // external_id" — the set the old join could not see. A correlated EXISTS
728
+ // keeps this a single UPDATE; the columns mirror the age clocks the
729
+ // dwell/TTL passes read (`coalesce(dwellAnchorAt, enteredAt)` and
730
+ // `maxDwellAt`).
731
+ const claimed = await db
732
+ .update(bucketMemberships)
733
+ .set({
734
+ dwellAnchorAt: now,
735
+ dwellState: {},
736
+ ...(maxDwellMs != null
737
+ ? { maxDwellAt: new Date(now.getTime() + maxDwellMs) }
738
+ : {}),
739
+ lastEvaluatedAt: now,
740
+ updatedAt: now,
741
+ })
742
+ .where(
743
+ and(
744
+ eq(bucketMemberships.bucketId, bucket.id),
745
+ eq(bucketMemberships.status, "active"),
746
+ isNull(bucketMemberships.deletedAt),
747
+ sql`exists (
748
+ select 1 from contacts c
749
+ where coalesce(c.external_id, c.anonymous_id, c.id::text) = ${bucketMemberships.userId}
750
+ and c.deleted_at is null
751
+ and c.external_id is null
752
+ )`,
753
+ ),
754
+ )
755
+ .returning({ id: bucketMemberships.id });
756
+
757
+ await db
758
+ .insert(bucketConfigs)
759
+ .values({ bucketId: bucket.id, coalesceClaimedAt: now })
760
+ .onConflictDoUpdate({
761
+ target: bucketConfigs.bucketId,
762
+ set: { coalesceClaimedAt: now, updatedAt: now },
763
+ });
764
+
765
+ if (claimed.length === 0) return false;
766
+
767
+ logger.info("Bucket coalesce-key cohort claimed — age clocks reset", {
768
+ bucketId: bucket.id,
769
+ memberships: claimed.length,
770
+ });
771
+ return true;
772
+ }
773
+
649
774
  async function reconcileBucketDwell(opts: {
650
775
  db: Database;
651
776
  logger: Logger;
@@ -694,7 +819,7 @@ async function reconcileBucketDwell(opts: {
694
819
  dwellState: bucketMemberships.dwellState,
695
820
  })
696
821
  .from(bucketMemberships)
697
- .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
822
+ .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
698
823
  .where(
699
824
  and(
700
825
  eq(bucketMemberships.bucketId, bucket.id),
@@ -0,0 +1,448 @@
1
+ import type { JsonObject } from "@hatchet-dev/typescript-sdk/v1/types.js";
2
+ import { createDatabase, type Database, importJobs } from "@hogsend/db";
3
+ import { and, eq, inArray, sql } from "drizzle-orm";
4
+ import { ALIAS_REASON_BACKFILL } from "../lib/contacts.js";
5
+ import { hatchet } from "../lib/hatchet.js";
6
+ import type { Logger } from "../lib/logger.js";
7
+ import { createLogger } from "../lib/logger.js";
8
+
9
+ /** `import_jobs.format` discriminator for the reused status record. */
10
+ export const IDENTITY_ALIAS_BACKFILL_FORMAT = "identity-alias-backfill";
11
+
12
+ /** Contacts per keyset batch — the `bucket-backfill.ts` precedent. */
13
+ const BATCH_SIZE = 500;
14
+
15
+ /**
16
+ * PRD 02 T3 — fill `contact_aliases` with a row per identity key of every LIVE
17
+ * contact, so the identity table can become the source of truth `findByKey`
18
+ * reads first. Keyset-paginated on the `contacts` PK; one classify SELECT plus
19
+ * one guarded INSERT per batch; no long-held transaction, no table lock.
20
+ *
21
+ * Invariants, each pinned by a test:
22
+ * - IDEMPOTENT — `ON CONFLICT (alias_kind, alias_value) DO NOTHING` against
23
+ * the plain unique index; a re-run (or a resume from zero) inserts nothing.
24
+ * - NEVER STEALS — a `(kind, value)` already claimed by a DIFFERENT contact is
25
+ * skipped and counted (`conflicting`), never repointed.
26
+ * - Soft-deleted contacts are EXCLUDED (`deleted_at IS NULL`): their keys are
27
+ * either a merged loser's (already aliased to the survivor by
28
+ * `recordMergeAliases`) or an erased person's (must not be resurrected).
29
+ * - Emails land NORMALIZED (`lower(trim(email))`) so the alias row matches the
30
+ * value the resolver's probes always compare against.
31
+ * - The row-uuid pseudo-key (`('external', contacts.id)`) is deliberately NOT
32
+ * backfilled — on a deployment using uuids as external ids it would contend
33
+ * with real keys, a history-theft-shaped outcome for a defensive row. The
34
+ * uuid probe stays last in `findByKey` instead.
35
+ */
36
+ export interface IdentityAliasBackfillInput extends JsonObject {
37
+ jobId: string;
38
+ /** Classify + count only; write nothing. Also reports the mixed-case email
39
+ * count (the datum behind PRD 02 T6's per-deployment decision). */
40
+ dryRun?: boolean;
41
+ }
42
+
43
+ // Extends JsonObject: this is a Hatchet task return value and must be
44
+ // JSON-serializable (the same constraint every workflow output carries).
45
+ export interface IdentityAliasBackfillResult extends JsonObject {
46
+ status: "completed" | "failed";
47
+ dryRun: boolean;
48
+ /** Live contacts scanned. */
49
+ scanned: number;
50
+ /** Alias rows written (projected, in a dry run). */
51
+ inserted: number;
52
+ /** Pairs already aliased to the SAME contact (benign; dominated by the
53
+ * dual-write once it has been live for a while). */
54
+ present: number;
55
+ /** Pairs whose `(kind, value)` is claimed by a DIFFERENT contact — the
56
+ * divergence metric. Never repointed; surfaced via the parity endpoint. */
57
+ conflicting: number;
58
+ /** Live contacts whose stored email differs from `lower(trim(email))` —
59
+ * re-measure per deployment before trusting the read flip for email (T6). */
60
+ mixedCaseEmails: number;
61
+ reason?: string;
62
+ }
63
+
64
+ /** The four identity-column → alias-kind projections of one contacts batch.
65
+ * Fragment shared by the classify SELECT and the INSERT so the two can never
66
+ * disagree about what a "pair" is. */
67
+ function pairsCte(afterId: string | null) {
68
+ return sql`
69
+ batch AS (
70
+ SELECT id, external_id, email, anonymous_id, discord_id
71
+ FROM contacts
72
+ WHERE deleted_at IS NULL
73
+ AND (${afterId}::uuid IS NULL OR id > ${afterId}::uuid)
74
+ ORDER BY id
75
+ LIMIT ${BATCH_SIZE}
76
+ ),
77
+ pairs AS (
78
+ SELECT id, 'external'::text AS kind, external_id AS value
79
+ FROM batch WHERE external_id IS NOT NULL
80
+ UNION ALL
81
+ SELECT id, 'email', lower(trim(email))
82
+ FROM batch WHERE email IS NOT NULL AND trim(email) <> ''
83
+ UNION ALL
84
+ SELECT id, 'anonymous', anonymous_id
85
+ FROM batch WHERE anonymous_id IS NOT NULL
86
+ UNION ALL
87
+ SELECT id, 'discord', discord_id
88
+ FROM batch WHERE discord_id IS NOT NULL
89
+ )`;
90
+ }
91
+
92
+ interface BatchClassification {
93
+ scanned: number;
94
+ lastId: string | null;
95
+ toInsert: number;
96
+ present: number;
97
+ conflicting: number;
98
+ }
99
+
100
+ /** One round trip: how many contacts this batch scans, where the cursor lands,
101
+ * and how each candidate pair classifies against the existing alias rows. */
102
+ async function classifyBatch(
103
+ db: Database,
104
+ afterId: string | null,
105
+ ): Promise<BatchClassification> {
106
+ const rows = await db.execute<{
107
+ scanned: number;
108
+ last_id: string | null;
109
+ to_insert: number;
110
+ present: number;
111
+ conflicting: number;
112
+ }>(sql`
113
+ WITH ${pairsCte(afterId)},
114
+ classified AS (
115
+ SELECT p.id, a.contact_id AS owner
116
+ FROM pairs p
117
+ LEFT JOIN contact_aliases a
118
+ ON a.alias_kind = p.kind AND a.alias_value = p.value
119
+ )
120
+ SELECT (SELECT count(*) FROM batch)::int AS scanned,
121
+ -- no max(uuid) aggregate exists; take the keyset tail explicitly
122
+ (SELECT id FROM batch ORDER BY id DESC LIMIT 1)::text AS last_id,
123
+ count(*) FILTER (WHERE c.owner IS NULL)::int AS to_insert,
124
+ count(*) FILTER (WHERE c.owner = c.id)::int AS present,
125
+ count(*) FILTER (WHERE c.owner IS NOT NULL
126
+ AND c.owner <> c.id)::int AS conflicting
127
+ FROM classified c
128
+ `);
129
+ const row = rows[0];
130
+ return {
131
+ scanned: Number(row?.scanned ?? 0),
132
+ lastId: row?.last_id ?? null,
133
+ toInsert: Number(row?.to_insert ?? 0),
134
+ present: Number(row?.present ?? 0),
135
+ conflicting: Number(row?.conflicting ?? 0),
136
+ };
137
+ }
138
+
139
+ /** True when the error chain carries a Postgres FK violation (23503). Drizzle
140
+ * wraps the driver error, so walk `cause` (the 23505 lesson from the partial-
141
+ * index onConflict work applies to every SQLSTATE). */
142
+ function isFkViolation(err: unknown): boolean {
143
+ let cursor: unknown = err;
144
+ for (let i = 0; i < 5 && cursor; i++) {
145
+ if (
146
+ typeof cursor === "object" &&
147
+ "code" in cursor &&
148
+ (cursor as { code?: unknown }).code === "23503"
149
+ ) {
150
+ return true;
151
+ }
152
+ cursor = (cursor as { cause?: unknown }).cause;
153
+ }
154
+ return false;
155
+ }
156
+
157
+ /**
158
+ * The write half — the PRD's verbatim statement. Returns rows inserted.
159
+ *
160
+ * Retries (bounded) on an FK violation: a contact HARD-deleted between this
161
+ * statement's snapshot and its inserts (a GDPR purge script, a test cleanup)
162
+ * makes the alias row's `contact_id` FK fail even though the batch CTE read the
163
+ * row as live. Each retry re-reads the batch under a fresh snapshot — the
164
+ * deleted contact is gone from it — so a racing purge costs a retry, not the
165
+ * whole job. Any other error, or a third consecutive FK loss, propagates.
166
+ */
167
+ async function insertBatch(db: Database, afterId: string | null) {
168
+ for (let attempt = 0; ; attempt++) {
169
+ try {
170
+ const rows = await db.execute<{ contact_id: string }>(sql`
171
+ WITH ${pairsCte(afterId)}
172
+ INSERT INTO contact_aliases
173
+ (contact_id, alias_kind, alias_value, from_contact_id, reason,
174
+ created_at, updated_at)
175
+ SELECT id, kind, value, NULL, ${ALIAS_REASON_BACKFILL}, now(), now()
176
+ FROM pairs
177
+ ON CONFLICT (alias_kind, alias_value) DO NOTHING
178
+ RETURNING contact_id
179
+ `);
180
+ return rows.length;
181
+ } catch (err) {
182
+ if (attempt >= 2 || !isFkViolation(err)) throw err;
183
+ }
184
+ }
185
+ }
186
+
187
+ /**
188
+ * The task body, exported directly so tests and operator scripts can run it
189
+ * without a Hatchet engine. `jobId` is optional: when present, progress is
190
+ * recorded on the `import_jobs` row (`processedRows` = contacts scanned,
191
+ * `failedRows` = conflicting pairs — the divergence metric, NOT an error
192
+ * count; the full breakdown is in the return value and the completion log).
193
+ */
194
+ export async function runIdentityAliasBackfill(opts: {
195
+ db: Database;
196
+ logger: Logger;
197
+ jobId?: string;
198
+ dryRun?: boolean;
199
+ }): Promise<IdentityAliasBackfillResult> {
200
+ const { db, logger, jobId } = opts;
201
+ const dryRun = opts.dryRun === true;
202
+
203
+ const markJob = async (
204
+ patch: Partial<typeof importJobs.$inferInsert>,
205
+ ): Promise<void> => {
206
+ if (!jobId) return;
207
+ await db
208
+ .update(importJobs)
209
+ .set({ ...patch, updatedAt: new Date() })
210
+ .where(eq(importJobs.id, jobId));
211
+ };
212
+
213
+ try {
214
+ const [totals] = await db.execute<{ live: number; mixed: number }>(sql`
215
+ SELECT count(*)::int AS live,
216
+ count(*) FILTER (
217
+ WHERE email IS NOT NULL
218
+ AND email IS DISTINCT FROM lower(trim(email))
219
+ )::int AS mixed
220
+ FROM contacts
221
+ WHERE deleted_at IS NULL
222
+ `);
223
+ const mixedCaseEmails = Number(totals?.mixed ?? 0);
224
+ await markJob({
225
+ status: "processing",
226
+ totalRows: Number(totals?.live ?? 0),
227
+ });
228
+
229
+ let cursor: string | null = null;
230
+ let scanned = 0;
231
+ let inserted = 0;
232
+ let present = 0;
233
+ let conflicting = 0;
234
+
235
+ for (;;) {
236
+ const batch = await classifyBatch(db, cursor);
237
+ if (batch.scanned === 0) break;
238
+
239
+ if (!dryRun) {
240
+ // The classify → insert pair is two statements, so a resolve committing
241
+ // between them can shrink the insert below `toInsert` — the INSERT's
242
+ // own ON CONFLICT arbiter is the correctness guard; the counts are
243
+ // observability. Count what actually landed.
244
+ inserted += await insertBatch(db, cursor);
245
+ } else {
246
+ inserted += batch.toInsert;
247
+ }
248
+ scanned += batch.scanned;
249
+ present += batch.present;
250
+ conflicting += batch.conflicting;
251
+ cursor = batch.lastId;
252
+
253
+ await markJob({ processedRows: scanned, failedRows: conflicting });
254
+ if (batch.scanned < BATCH_SIZE) break;
255
+ }
256
+
257
+ if (!dryRun) {
258
+ // ERASURE-RACE SWEEP. A contact erased WHILE this job runs can have its
259
+ // keys re-inserted from a batch statement's stale snapshot (the batch
260
+ // read the contact as live; the erasure hook's delete committed first;
261
+ // this insert committed second). That would resurrect an erased person's
262
+ // identity keys — the exact leak PRD 02 T1 exists to close. This final
263
+ // statement runs AFTER every insert has committed, so its snapshot sees
264
+ // any erasure that raced a batch: whichever of the two commits second
265
+ // now cleans up. Scoped to backfill-authored rows — merge-trail aliases
266
+ // pointing at a soft-deleted survivor are `recordMergeAliases`' business,
267
+ // not this job's.
268
+ const swept = await db.execute<{ id: string }>(sql`
269
+ DELETE FROM contact_aliases a
270
+ USING contacts c
271
+ WHERE a.contact_id = c.id
272
+ AND c.deleted_at IS NOT NULL
273
+ AND a.reason = ${ALIAS_REASON_BACKFILL}
274
+ RETURNING a.id
275
+ `);
276
+ if (swept.length > 0) {
277
+ logger.warn("Identity alias backfill swept erased-contact rows", {
278
+ swept: swept.length,
279
+ });
280
+ // Clamp: the sweep can also collect a PREVIOUS run's raced rows,
281
+ // which this run never counted as inserts.
282
+ inserted = Math.max(0, inserted - swept.length);
283
+ }
284
+ }
285
+
286
+ await markJob({
287
+ status: "completed",
288
+ processedRows: scanned,
289
+ failedRows: conflicting,
290
+ });
291
+ logger.info("Identity alias backfill complete", {
292
+ dryRun,
293
+ scanned,
294
+ inserted,
295
+ present,
296
+ conflicting,
297
+ mixedCaseEmails,
298
+ });
299
+ return {
300
+ status: "completed",
301
+ dryRun,
302
+ scanned,
303
+ inserted,
304
+ present,
305
+ conflicting,
306
+ mixedCaseEmails,
307
+ };
308
+ } catch (err) {
309
+ const message = err instanceof Error ? err.message : String(err);
310
+ await markJob({
311
+ status: "failed",
312
+ errors: [{ row: 0, error: message }],
313
+ }).catch(() => undefined);
314
+ logger.error("Identity alias backfill failed", { dryRun, message });
315
+ return {
316
+ status: "failed",
317
+ dryRun,
318
+ scanned: 0,
319
+ inserted: 0,
320
+ present: 0,
321
+ conflicting: 0,
322
+ mixedCaseEmails: 0,
323
+ reason: message,
324
+ };
325
+ }
326
+ }
327
+
328
+ export const identityAliasBackfillTask = hatchet.task({
329
+ name: "identity-alias-backfill",
330
+ retries: 0,
331
+ executionTimeout: "600s",
332
+ fn: async (input: IdentityAliasBackfillInput) => {
333
+ const { db } = createDatabase({ url: process.env.DATABASE_URL ?? "" });
334
+ const logger = createLogger(process.env.LOG_LEVEL ?? "info");
335
+ return runIdentityAliasBackfill({
336
+ db,
337
+ logger,
338
+ jobId: input.jobId,
339
+ dryRun: input.dryRun === true,
340
+ });
341
+ },
342
+ });
343
+
344
+ /**
345
+ * Worker-boot enqueue (mirrors `enqueueBucketBackfills`): fire the backfill
346
+ * once per deployment without an operator having to remember it — the engine
347
+ * is a published dependency, and a manual step every consumer must run before
348
+ * the read flip is how deployments strand. Skips when ANY non-failed job of
349
+ * this format exists (pending/processing/completed); a failed run re-enqueues
350
+ * on the next boot, and `POST /v1/admin/identity/alias-backfill` forces a
351
+ * re-run past a stale record. Re-running is always safe (ON CONFLICT DO
352
+ * NOTHING), just not free — hence the skip. Best-effort: a failure to enqueue
353
+ * must never crash worker boot.
354
+ */
355
+ export async function enqueueIdentityAliasBackfill(opts: {
356
+ db: Database;
357
+ logger: Logger;
358
+ }): Promise<void> {
359
+ const { db, logger } = opts;
360
+ try {
361
+ const existing = await db
362
+ .select({ id: importJobs.id })
363
+ .from(importJobs)
364
+ .where(
365
+ and(
366
+ eq(importJobs.format, IDENTITY_ALIAS_BACKFILL_FORMAT),
367
+ inArray(importJobs.status, ["pending", "processing", "completed"]),
368
+ ),
369
+ )
370
+ .limit(1);
371
+ if (existing[0]) return;
372
+
373
+ const [job] = await db
374
+ .insert(importJobs)
375
+ .values({
376
+ fileName: IDENTITY_ALIAS_BACKFILL_FORMAT,
377
+ format: IDENTITY_ALIAS_BACKFILL_FORMAT,
378
+ status: "pending",
379
+ })
380
+ .returning({ id: importJobs.id });
381
+ if (!job) return;
382
+
383
+ // runNoWait: called from worker boot BEFORE the listener starts — awaiting
384
+ // the run would deadlock (same reasoning as enqueueBucketBackfills).
385
+ await identityAliasBackfillTask.runNoWait({ jobId: job.id, dryRun: false });
386
+ logger.info("Identity alias backfill enqueued", { jobId: job.id });
387
+ } catch (err) {
388
+ logger.warn("Identity alias backfill enqueue failed", {
389
+ error: err instanceof Error ? err.message : String(err),
390
+ });
391
+ }
392
+ }
393
+
394
+ // ---------------------------------------------------------------------------
395
+ // PRD 02 T4 — read-only parity verifier
396
+ // ---------------------------------------------------------------------------
397
+
398
+ export interface AliasParityRow {
399
+ kind: string;
400
+ /** Alias and column resolve to DIFFERENT live contacts. MUST be 0 before
401
+ * trusting alias-first resolution; a non-zero value is a data bug to fix on
402
+ * its own, never to flip over. */
403
+ diverged: number;
404
+ /** Alias target is dead/missing but a live column owner exists — expected,
405
+ * handled by `findByKey`'s live-target fall-through. */
406
+ aliasDead: number;
407
+ /** Alias exists with no column owner — the merge/promote population, and
408
+ * (after PRD 03) the point of the table. */
409
+ aliasOnly: number;
410
+ }
411
+
412
+ /** "Would alias-first return a different contact than column-first?", per kind,
413
+ * over every alias row. Pure read; no writes, no locks beyond the reads. */
414
+ export async function identityAliasParity(
415
+ db: Database,
416
+ ): Promise<AliasParityRow[]> {
417
+ const rows = await db.execute<{
418
+ alias_kind: string;
419
+ diverged: number;
420
+ alias_dead: number;
421
+ alias_only: number;
422
+ }>(sql`
423
+ SELECT a.alias_kind,
424
+ count(*) FILTER (WHERE ac.id IS NOT NULL AND cc.id IS NOT NULL
425
+ AND ac.id <> cc.id)::int AS diverged,
426
+ count(*) FILTER (WHERE ac.id IS NULL
427
+ AND cc.id IS NOT NULL)::int AS alias_dead,
428
+ count(*) FILTER (WHERE ac.id IS NOT NULL
429
+ AND cc.id IS NULL)::int AS alias_only
430
+ FROM contact_aliases a
431
+ LEFT JOIN contacts ac
432
+ ON ac.id = a.contact_id AND ac.deleted_at IS NULL
433
+ LEFT JOIN contacts cc
434
+ ON cc.deleted_at IS NULL AND (
435
+ (a.alias_kind = 'external' AND cc.external_id = a.alias_value)
436
+ OR (a.alias_kind = 'email' AND lower(trim(cc.email)) = a.alias_value)
437
+ OR (a.alias_kind = 'anonymous' AND cc.anonymous_id = a.alias_value)
438
+ OR (a.alias_kind = 'discord' AND cc.discord_id = a.alias_value))
439
+ GROUP BY 1
440
+ ORDER BY 1
441
+ `);
442
+ return rows.map((r) => ({
443
+ kind: r.alias_kind,
444
+ diverged: Number(r.diverged),
445
+ aliasDead: Number(r.alias_dead),
446
+ aliasOnly: Number(r.alias_only),
447
+ }));
448
+ }