@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.
- package/package.json +11 -11
- package/src/buckets/bucket-access.ts +5 -10
- package/src/buckets/check-membership.ts +91 -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/enrichment-ledger.ts +1 -1
- package/src/lib/feed.ts +64 -3
- package/src/lib/identity-service.ts +15 -2
- package/src/lib/ingestion.ts +191 -14
- package/src/lib/outbound.ts +3 -3
- package/src/lib/refine-chain.test.ts +83 -25
- package/src/lib/refine-chain.ts +124 -23
- package/src/lib/refine-traits.test.ts +74 -41
- package/src/lib/refine-traits.ts +107 -52
- package/src/lib/refine.ts +28 -27
- 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/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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
+
}
|