@hogsend/engine 0.59.0 → 0.60.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 +19 -10
- package/src/buckets/check-membership.ts +55 -8
- package/src/buckets/membership-epoch.ts +11 -1
- package/src/campaigns/cohort-sql.ts +3 -0
- package/src/index.ts +10 -6
- package/src/journeys/execute-journey-run.ts +119 -50
- package/src/journeys/journey-context.ts +43 -7
- package/src/lib/agent/tools.ts +29 -4
- package/src/lib/attribution-backfill.ts +27 -4
- package/src/lib/attribution.ts +22 -3
- package/src/lib/connector-actions.ts +4 -1
- package/src/lib/contacts.ts +408 -152
- package/src/lib/conversion-dispatch.ts +16 -2
- package/src/lib/enrollment-guards.ts +19 -12
- package/src/lib/feed.ts +5 -5
- package/src/lib/flags.ts +26 -9
- package/src/lib/ingestion.ts +14 -2
- package/src/lib/journey-lift.ts +17 -5
- package/src/lib/preferences.ts +78 -29
- package/src/lib/recipient-preferences.ts +16 -2
- package/src/lib/revenue.ts +20 -5
- package/src/lib/sms-tracked.ts +18 -1
- package/src/lib/tracked.ts +19 -8
- package/src/lib/tracking-events.ts +28 -0
- package/src/lib/unique-violation.ts +44 -0
- package/src/routes/admin/buckets.ts +20 -2
- package/src/routes/admin/bulk.ts +14 -2
- package/src/routes/admin/contacts.ts +4 -3
- package/src/routes/admin/conversions.ts +20 -4
- package/src/routes/admin/emails.ts +17 -2
- package/src/routes/admin/events.ts +32 -41
- package/src/routes/admin/funnels.ts +6 -1
- package/src/routes/admin/groups.ts +4 -0
- package/src/routes/admin/impact.ts +30 -10
- package/src/routes/admin/journey-impact.ts +18 -9
- package/src/routes/admin/journeys.ts +8 -1
- package/src/routes/admin/maintenance.ts +7 -1
- package/src/routes/admin/preferences.ts +85 -46
- package/src/routes/admin/reporting.ts +25 -5
- package/src/routes/admin/targeting.ts +1 -0
- package/src/routes/admin/timeline.ts +16 -10
- package/src/routes/email/preferences.ts +18 -1
- package/src/routes/lists/index.ts +6 -6
- package/src/workflows/backfill-contact-id.ts +210 -30
- package/src/workflows/bucket-backfill.ts +145 -67
- package/src/workflows/bucket-reconcile.ts +150 -50
- package/src/workflows/check-alerts.ts +4 -0
- package/src/workflows/impact-digest.ts +10 -3
- package/src/workflows/journey-blueprint-interpreter.ts +8 -1
- package/src/workflows/send-campaign.ts +18 -11
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.60.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -53,18 +53,18 @@
|
|
|
53
53
|
"svix": "^1.95.1",
|
|
54
54
|
"winston": "^3.19.0",
|
|
55
55
|
"zod": "^4.4.3",
|
|
56
|
-
"@hogsend/attribution": "^0.
|
|
57
|
-
"@hogsend/core": "^0.
|
|
58
|
-
"@hogsend/db": "^0.
|
|
59
|
-
"@hogsend/email": "^0.
|
|
60
|
-
"@hogsend/plugin-posthog": "^0.
|
|
61
|
-
"@hogsend/plugin-resend": "^0.
|
|
62
|
-
"@hogsend/sms": "^0.
|
|
56
|
+
"@hogsend/attribution": "^0.60.0",
|
|
57
|
+
"@hogsend/core": "^0.60.0",
|
|
58
|
+
"@hogsend/db": "^0.60.0",
|
|
59
|
+
"@hogsend/email": "^0.60.0",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.60.0",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.60.0",
|
|
62
|
+
"@hogsend/sms": "^0.60.0"
|
|
63
63
|
},
|
|
64
64
|
"optionalDependencies": {
|
|
65
|
-
"@hogsend/plugin-apollo": "^0.
|
|
66
|
-
"@hogsend/plugin-postmark": "^0.
|
|
67
|
-
"@hogsend/plugin-twilio": "^0.
|
|
65
|
+
"@hogsend/plugin-apollo": "^0.60.0",
|
|
66
|
+
"@hogsend/plugin-postmark": "^0.60.0",
|
|
67
|
+
"@hogsend/plugin-twilio": "^0.60.0"
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
70
|
"@types/node": "^22.15.3",
|
|
@@ -57,10 +57,14 @@ function toError(err: unknown): Error {
|
|
|
57
57
|
* container re-binds the accessors with a `dbResolver` that returns its own
|
|
58
58
|
* `db`; the `getDb()` default bypasses the container.
|
|
59
59
|
*
|
|
60
|
-
* Every query `innerJoin`s `contacts` on
|
|
61
|
-
* `isNull(deletedAt)` on both
|
|
62
|
-
*
|
|
63
|
-
*
|
|
60
|
+
* Every query `innerJoin`s `contacts` on the membership's OWNING CONTACT
|
|
61
|
+
* (`bucket_memberships.contact_id`) and filters `isNull(deletedAt)` on both
|
|
62
|
+
* tables — GDPR parity with every reconcile/admin query. The join used to run
|
|
63
|
+
* on the mutable text key (`coalesce(external_id, anonymous_id, id) =
|
|
64
|
+
* user_id`); it now runs on the FK, so a membership adopted onto a contact
|
|
65
|
+
* under a since-stale key stays visible instead of dropping out of every count
|
|
66
|
+
* and page. No method throws (except the iterator on a page error); failures
|
|
67
|
+
* are carried in the result's `error`.
|
|
64
68
|
*/
|
|
65
69
|
export function createBucketAccessor(
|
|
66
70
|
bucketId: string,
|
|
@@ -75,7 +79,7 @@ export function createBucketAccessor(
|
|
|
75
79
|
const rows = await db
|
|
76
80
|
.select({ value: countFn() })
|
|
77
81
|
.from(bucketMemberships)
|
|
78
|
-
.innerJoin(contacts, eq(
|
|
82
|
+
.innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
|
|
79
83
|
.where(
|
|
80
84
|
and(
|
|
81
85
|
eq(bucketMemberships.bucketId, bucketId),
|
|
@@ -95,15 +99,20 @@ export function createBucketAccessor(
|
|
|
95
99
|
): Promise<{ data: boolean; error: Error | null }> {
|
|
96
100
|
try {
|
|
97
101
|
const db = dbResolver();
|
|
98
|
-
//
|
|
102
|
+
// The subject predicate moves to the CONTACT side: `userId` is the caller's
|
|
103
|
+
// canonical key, so we name the contact it resolves to and let the FK join
|
|
104
|
+
// find that contact's membership. Probing `bucket_memberships.user_id`
|
|
105
|
+
// instead answers "false" for a member whose row was adopted under an
|
|
106
|
+
// anon-era key — the person is in the bucket, `has()` says they are not,
|
|
107
|
+
// and every gate built on it silently opens.
|
|
99
108
|
const rows = await db
|
|
100
109
|
.select({ id: bucketMemberships.id })
|
|
101
110
|
.from(bucketMemberships)
|
|
102
|
-
.innerJoin(contacts, eq(
|
|
111
|
+
.innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
|
|
103
112
|
.where(
|
|
104
113
|
and(
|
|
105
114
|
eq(bucketMemberships.bucketId, bucketId),
|
|
106
|
-
eq(
|
|
115
|
+
eq(contactKeySql(), userId),
|
|
107
116
|
eq(bucketMemberships.status, "active"),
|
|
108
117
|
isNull(bucketMemberships.deletedAt),
|
|
109
118
|
isNull(contacts.deletedAt),
|
|
@@ -145,7 +154,7 @@ export function createBucketAccessor(
|
|
|
145
154
|
entryCount: bucketMemberships.entryCount,
|
|
146
155
|
})
|
|
147
156
|
.from(bucketMemberships)
|
|
148
|
-
.innerJoin(contacts, eq(
|
|
157
|
+
.innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
|
|
149
158
|
.where(and(...conditions))
|
|
150
159
|
.orderBy(bucketMemberships.id)
|
|
151
160
|
// +1 peek to detect a next page.
|
|
@@ -153,7 +162,7 @@ export function createBucketAccessor(
|
|
|
153
162
|
db
|
|
154
163
|
.select({ value: countFn() })
|
|
155
164
|
.from(bucketMemberships)
|
|
156
|
-
.innerJoin(contacts, eq(
|
|
165
|
+
.innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
|
|
157
166
|
.where(
|
|
158
167
|
and(
|
|
159
168
|
eq(bucketMemberships.bucketId, bucketId),
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
2
|
import {
|
|
3
3
|
type BucketMeta,
|
|
4
|
+
bySubject,
|
|
4
5
|
collectPropertyNames,
|
|
5
6
|
durationToMs,
|
|
6
7
|
evaluateCondition,
|
|
@@ -235,10 +236,17 @@ export async function checkBucketMembership(opts: {
|
|
|
235
236
|
if (!bucket.criteria) continue;
|
|
236
237
|
|
|
237
238
|
// wasMember — current active, non-deleted membership row (cheap pre-filter;
|
|
238
|
-
// the authoritative guard is the RETURNING-gated mutation below).
|
|
239
|
+
// the authoritative guard is the RETURNING-gated mutation below). Read by
|
|
240
|
+
// SUBJECT: a membership adopted onto this contact under a since-stale key
|
|
241
|
+
// is invisible to a `user_id` probe, and missing it re-runs the JOIN path,
|
|
242
|
+
// which then loses the arbiter-less race and no-ops — a member who silently
|
|
243
|
+
// never re-emits and never leaves.
|
|
239
244
|
const active = await db.query.bucketMemberships.findFirst({
|
|
240
245
|
where: and(
|
|
241
|
-
|
|
246
|
+
bySubject(bucketMemberships, {
|
|
247
|
+
contactId: contactId ?? null,
|
|
248
|
+
userKey: userId,
|
|
249
|
+
}),
|
|
242
250
|
eq(bucketMemberships.bucketId, bucket.id),
|
|
243
251
|
eq(bucketMemberships.status, "active"),
|
|
244
252
|
isNull(bucketMemberships.deletedAt),
|
|
@@ -252,7 +260,16 @@ export async function checkBucketMembership(opts: {
|
|
|
252
260
|
// sub-conditions read the merged journeyContext.
|
|
253
261
|
const isMember = await evaluateCondition({
|
|
254
262
|
condition: bucket.criteria,
|
|
255
|
-
ctx: {
|
|
263
|
+
ctx: {
|
|
264
|
+
db,
|
|
265
|
+
userId,
|
|
266
|
+
// `ingestEvent` resolved the subject before calling us, so the event /
|
|
267
|
+
// count legs read this person's whole history — including the rows
|
|
268
|
+
// adopted from an anon-era key — instead of only what the current
|
|
269
|
+
// string key happens to name.
|
|
270
|
+
contactId: contactId ?? null,
|
|
271
|
+
journeyContext,
|
|
272
|
+
},
|
|
256
273
|
});
|
|
257
274
|
|
|
258
275
|
if (!wasMember && isMember) {
|
|
@@ -324,13 +341,27 @@ async function handleJoin(opts: {
|
|
|
324
341
|
// this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the entryLimit
|
|
325
342
|
// gate. Shared with the reconcile-discovered join path so the ordinal can
|
|
326
343
|
// never drift between the two writers.
|
|
327
|
-
const priorCount = await countPriorMemberships(
|
|
344
|
+
const priorCount = await countPriorMemberships(
|
|
345
|
+
db,
|
|
346
|
+
bucket.id,
|
|
347
|
+
userId,
|
|
348
|
+
contactId ?? null,
|
|
349
|
+
);
|
|
328
350
|
const epoch = priorCount + 1;
|
|
329
351
|
|
|
330
|
-
// INSERT a FRESH active row. ON CONFLICT DO NOTHING
|
|
352
|
+
// INSERT a FRESH active row. ON CONFLICT DO NOTHING covers the partial active
|
|
331
353
|
// unique index (uq_user_bucket_active): a concurrent emitter that already
|
|
332
354
|
// inserted the active row makes THIS insert return zero rows → we do NOT emit
|
|
333
355
|
// (the loser mutates nothing — Section 6.3 governing rule).
|
|
356
|
+
//
|
|
357
|
+
// PRD 05 T3 — the DO NOTHING is deliberately ARBITER-LESS. Two partial unique
|
|
358
|
+
// indexes now guard this table (uq_user_bucket_active and its contact-scoped
|
|
359
|
+
// twin uq_contact_bucket_active), Postgres allows only ONE conflict target per
|
|
360
|
+
// statement, and both must land in the same "already a member" branch: the
|
|
361
|
+
// contact one is what catches an adopted row whose `user_id` still differs.
|
|
362
|
+
// Narrowing this to a column target would let that collision escape as a raw
|
|
363
|
+
// 23505 — and a target naming `contact_id` would additionally miss every
|
|
364
|
+
// contactless (NULL) member.
|
|
334
365
|
const expiresAt = computeExpiresAt(bucket);
|
|
335
366
|
// Unconditional TTL deadline — set once on join, swept by the reconcile cron.
|
|
336
367
|
const maxDwellAt = computeMaxDwellAt(bucket);
|
|
@@ -386,7 +417,15 @@ async function handleJoin(opts: {
|
|
|
386
417
|
// The active row is always written (Studio size must reflect reality) and the
|
|
387
418
|
// epoch always advances via the real insert; only the bucket:entered emission
|
|
388
419
|
// is gated by the entryLimit policy (Section 6.3).
|
|
389
|
-
if (
|
|
420
|
+
if (
|
|
421
|
+
await shouldEmitJoin({
|
|
422
|
+
db,
|
|
423
|
+
bucket,
|
|
424
|
+
userId,
|
|
425
|
+
contactId: contactId ?? null,
|
|
426
|
+
priorCount,
|
|
427
|
+
})
|
|
428
|
+
) {
|
|
390
429
|
await emitBucketTransition({
|
|
391
430
|
db,
|
|
392
431
|
registry,
|
|
@@ -532,9 +571,17 @@ export async function shouldEmitJoin(opts: {
|
|
|
532
571
|
db: Database;
|
|
533
572
|
bucket: BucketMeta;
|
|
534
573
|
userId: string;
|
|
574
|
+
/**
|
|
575
|
+
* The owning contact's `contacts.id`, or `null` when the caller has none.
|
|
576
|
+
* REQUIRED (not optional) on purpose: the prior-cycle lookup below is the
|
|
577
|
+
* cooldown gate, and an optional field a caller forgets silently drops it
|
|
578
|
+
* back onto the mutable text key — which misses the adopted prior cycle and
|
|
579
|
+
* re-emits a `once` join. Pass `null` explicitly for a contactless subject.
|
|
580
|
+
*/
|
|
581
|
+
contactId: string | null;
|
|
535
582
|
priorCount: number;
|
|
536
583
|
}): Promise<boolean> {
|
|
537
|
-
const { db, bucket, userId, priorCount } = opts;
|
|
584
|
+
const { db, bucket, userId, contactId, priorCount } = opts;
|
|
538
585
|
// First-ever join always emits.
|
|
539
586
|
if (priorCount === 0) return true;
|
|
540
587
|
switch (bucket.entryLimit ?? "unlimited") {
|
|
@@ -556,7 +603,7 @@ export async function shouldEmitJoin(opts: {
|
|
|
556
603
|
.from(bucketMemberships)
|
|
557
604
|
.where(
|
|
558
605
|
and(
|
|
559
|
-
|
|
606
|
+
bySubject(bucketMemberships, { contactId, userKey: userId }),
|
|
560
607
|
eq(bucketMemberships.bucketId, bucket.id),
|
|
561
608
|
eq(bucketMemberships.status, "left"),
|
|
562
609
|
isNotNull(bucketMemberships.leftAt),
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import {
|
|
2
2
|
type BucketMeta,
|
|
3
|
+
bySubject,
|
|
3
4
|
type ConditionEval,
|
|
4
5
|
type DurationObject,
|
|
5
6
|
durationToMs,
|
|
@@ -25,18 +26,27 @@ export const BUCKET_EVENT_PREFIX = "bucket:";
|
|
|
25
26
|
*
|
|
26
27
|
* The predicate MUST stay status-agnostic — narrowing it (e.g. to active-only)
|
|
27
28
|
* would corrupt entryCount and the entryLimit cooldown.
|
|
29
|
+
*
|
|
30
|
+
* `contactId` is REQUIRED (not optional) for the same reason
|
|
31
|
+
* `checkEntryLimit`'s is: an optional field silently defaults a new caller onto
|
|
32
|
+
* the mutable text key, and here that under-counts the epoch — a person whose
|
|
33
|
+
* anon-era memberships were adopted would re-enter at ordinal 1 and slip the
|
|
34
|
+
* `once`/`once_per_period` gate. Pass `null` explicitly for a subject with no
|
|
35
|
+
* contact; that is a permanent, supported state (memberships are text-keyed
|
|
36
|
+
* with no contact FK).
|
|
28
37
|
*/
|
|
29
38
|
export async function countPriorMemberships(
|
|
30
39
|
db: Database,
|
|
31
40
|
bucketId: string,
|
|
32
41
|
userId: string,
|
|
42
|
+
contactId: string | null,
|
|
33
43
|
): Promise<number> {
|
|
34
44
|
const [counted] = await db
|
|
35
45
|
.select({ priorCount: sql<number>`count(*)::int` })
|
|
36
46
|
.from(bucketMemberships)
|
|
37
47
|
.where(
|
|
38
48
|
and(
|
|
39
|
-
|
|
49
|
+
bySubject(bucketMemberships, { contactId, userKey: userId }),
|
|
40
50
|
eq(bucketMemberships.bucketId, bucketId),
|
|
41
51
|
),
|
|
42
52
|
);
|
|
@@ -161,6 +161,9 @@ function eventSql(condition: EventCondition, startedAt: Date): SQL {
|
|
|
161
161
|
Date.now() - durationToMs(condition.within),
|
|
162
162
|
).toISOString()}::timestamptz`
|
|
163
163
|
: sql.empty();
|
|
164
|
+
// PRD 05 T8 — this correlation STAYS string-keyed: `campaign_recipients`
|
|
165
|
+
// has no `contact_id` column, so the text key is the only subject available
|
|
166
|
+
// on the outer side of the join.
|
|
164
167
|
const positive = sql`exists (
|
|
165
168
|
select 1 from ${userEvents}
|
|
166
169
|
where ${userEvents.userId} = ${campaignRecipients.userId}
|
package/src/index.ts
CHANGED
|
@@ -37,14 +37,18 @@ export type {
|
|
|
37
37
|
// types) so content can import everything from `@hogsend/engine`.
|
|
38
38
|
export * from "@hogsend/core";
|
|
39
39
|
// --- Capability-provider contracts (canonical origin: @hogsend/core) ---
|
|
40
|
-
// Email provider contract + analytics contract,
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
// `SendEmailOptions`
|
|
45
|
-
|
|
40
|
+
// Email provider contract + analytics contract, plus `bySubject` (the
|
|
41
|
+
// either/or history scope every engine-side history read is expected to move
|
|
42
|
+
// onto), re-exported so consumers can import them from `@hogsend/engine`.
|
|
43
|
+
// (`SendEmailOptions` is intentionally omitted here: the engine's public
|
|
44
|
+
// `SendEmailOptions` is the high-level journey-facing send options from
|
|
45
|
+
// `./lib/email.js`; the provider-contract `SendEmailOptions` remains available
|
|
46
|
+
// via `@hogsend/core`.)
|
|
47
|
+
export {
|
|
48
|
+
bySubject,
|
|
46
49
|
defineAnalyticsProvider,
|
|
47
50
|
defineEmailProvider,
|
|
51
|
+
type Subject,
|
|
48
52
|
WebhookHandshakeSignal,
|
|
49
53
|
} from "@hogsend/core";
|
|
50
54
|
export {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { Conditions } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
2
|
import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
|
|
3
|
-
import { type DurationObject, durationToMs } from "@hogsend/core";
|
|
3
|
+
import { bySubject, type DurationObject, durationToMs } from "@hogsend/core";
|
|
4
4
|
import type {
|
|
5
5
|
JourneyMeta,
|
|
6
6
|
JourneyRunFn,
|
|
@@ -28,6 +28,10 @@ import { ingestEvent } from "../lib/ingestion.js";
|
|
|
28
28
|
import { createLogger } from "../lib/logger.js";
|
|
29
29
|
import { emitOutbound } from "../lib/outbound.js";
|
|
30
30
|
import { resolveTimezoneWithSource } from "../lib/timezone.js";
|
|
31
|
+
import {
|
|
32
|
+
isUniqueViolationOn,
|
|
33
|
+
UQ_CONTACT_JOURNEY_ACTIVE,
|
|
34
|
+
} from "../lib/unique-violation.js";
|
|
31
35
|
import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
|
|
32
36
|
import { JourneyExitedError } from "./errors.js";
|
|
33
37
|
import {
|
|
@@ -171,6 +175,17 @@ async function resolveEnrollmentContactId(opts: {
|
|
|
171
175
|
* CONFLICT specification") at runtime. The `where` reproduces the index
|
|
172
176
|
* predicate (`status IN ('active','waiting')`) EXACTLY — see
|
|
173
177
|
* journey-states.ts:uq_user_journey_active.
|
|
178
|
+
*
|
|
179
|
+
* PRD 05 T3 — the arbiter deliberately STAYS on the string key. The second live
|
|
180
|
+
* index, `uq_contact_journey_active`, cannot be an arbiter here: drizzle's
|
|
181
|
+
* `target` accepts columns only (no expression), and a bare
|
|
182
|
+
* `(contact_id, journey_id)` target would never fire for a NULL `contact_id` —
|
|
183
|
+
* i.e. for every anonymous visitor, a permanent supported state — so an
|
|
184
|
+
* anonymous re-trigger of a live journey would insert a second row and die on
|
|
185
|
+
* the string index. Instead its 23505 is caught below and mapped to the SAME
|
|
186
|
+
* zero-rows outcome, which the caller reads as `already_active`. That is the
|
|
187
|
+
* correct answer: the contact IS already live in this journey, under a different
|
|
188
|
+
* string key that adoption has since folded onto the same contact.
|
|
174
189
|
*/
|
|
175
190
|
export async function insertEnrollment(opts: {
|
|
176
191
|
db: Database;
|
|
@@ -224,24 +239,39 @@ export async function insertEnrollment(opts: {
|
|
|
224
239
|
where: sql`status IN ('active', 'waiting')`,
|
|
225
240
|
};
|
|
226
241
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
.
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
242
|
+
try {
|
|
243
|
+
if (!opts.serializeWithGraphLock) {
|
|
244
|
+
const [row] = await opts.db
|
|
245
|
+
.insert(journeyStates)
|
|
246
|
+
.values(values)
|
|
247
|
+
.onConflictDoNothing(onConflict)
|
|
248
|
+
.returning();
|
|
249
|
+
return row;
|
|
250
|
+
}
|
|
235
251
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
.
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
252
|
+
// `await` (not a bare return) so a 23505 raised inside the transaction is
|
|
253
|
+
// caught HERE, after the transaction has already rolled back.
|
|
254
|
+
return await opts.db.transaction(async (tx) => {
|
|
255
|
+
await tx.execute(blueprintGraphLock(opts.journeyId));
|
|
256
|
+
const [row] = await tx
|
|
257
|
+
.insert(journeyStates)
|
|
258
|
+
.values(values)
|
|
259
|
+
.onConflictDoNothing(onConflict)
|
|
260
|
+
.returning();
|
|
261
|
+
return row;
|
|
262
|
+
});
|
|
263
|
+
} catch (err) {
|
|
264
|
+
if (!isUniqueViolationOn(err, UQ_CONTACT_JOURNEY_ACTIVE)) throw err;
|
|
265
|
+
// Same contact, DIFFERENT string key, already live in this journey. Zero
|
|
266
|
+
// rows is exactly what the string arbiter returns for the same situation,
|
|
267
|
+
// and the caller maps it to the `already_active` skip.
|
|
268
|
+
logger.info("journey enrollment skipped — contact already live", {
|
|
269
|
+
journeyId: opts.journeyId,
|
|
270
|
+
userId: opts.userId,
|
|
271
|
+
contactId: opts.contactId ?? null,
|
|
272
|
+
});
|
|
273
|
+
return undefined;
|
|
274
|
+
}
|
|
245
275
|
}
|
|
246
276
|
|
|
247
277
|
export interface ExecuteJourneyRunOptions {
|
|
@@ -335,6 +365,26 @@ export async function executeJourneyRun(
|
|
|
335
365
|
|
|
336
366
|
let state = recovered;
|
|
337
367
|
|
|
368
|
+
// The subject this run's ENTRY reads and writes history for, resolved AT MOST
|
|
369
|
+
// ONCE. PRD 05 T4 moved the entry guards off the mutable `user_id` string and
|
|
370
|
+
// onto `bySubject`, so the guards now need the same value the enrollment
|
|
371
|
+
// insert already stamped — memoizing it keeps that at one resolve per run
|
|
372
|
+
// rather than one per reader (`undefined` = not yet resolved; `null` = a
|
|
373
|
+
// resolved-to-nothing subject, which is a permanent supported state and must
|
|
374
|
+
// not re-probe).
|
|
375
|
+
let resolvedContactId: string | null | undefined;
|
|
376
|
+
const enrollmentContactId = async (): Promise<string | null> => {
|
|
377
|
+
if (resolvedContactId === undefined) {
|
|
378
|
+
resolvedContactId = await resolveEnrollmentContactId({
|
|
379
|
+
db,
|
|
380
|
+
userId,
|
|
381
|
+
journeyId: meta.id,
|
|
382
|
+
pushed: input.contactId,
|
|
383
|
+
});
|
|
384
|
+
}
|
|
385
|
+
return resolvedContactId;
|
|
386
|
+
};
|
|
387
|
+
|
|
338
388
|
// FIRST ENTRY ONLY — the enrollment guards gate ENTRY, not resume. A
|
|
339
389
|
// recovered enrollment already passed them on first entry, so it skips
|
|
340
390
|
// straight to resuming the run. (Sends inside `run` still re-check
|
|
@@ -364,6 +414,7 @@ export async function executeJourneyRun(
|
|
|
364
414
|
db,
|
|
365
415
|
journey: meta,
|
|
366
416
|
userId,
|
|
417
|
+
contactId: await enrollmentContactId(),
|
|
367
418
|
});
|
|
368
419
|
const entryPolicy = evaluateEnrollmentPolicy({
|
|
369
420
|
journey: meta,
|
|
@@ -374,7 +425,11 @@ export async function executeJourneyRun(
|
|
|
374
425
|
return { status: "skipped", reason: entryPolicy.reason };
|
|
375
426
|
}
|
|
376
427
|
|
|
377
|
-
const prefs = await checkEmailPreferences({
|
|
428
|
+
const prefs = await checkEmailPreferences({
|
|
429
|
+
db,
|
|
430
|
+
userId,
|
|
431
|
+
contactId: await enrollmentContactId(),
|
|
432
|
+
});
|
|
378
433
|
const preferencePolicy = evaluateEnrollmentPolicy({
|
|
379
434
|
journey: meta,
|
|
380
435
|
properties,
|
|
@@ -407,26 +462,23 @@ export async function executeJourneyRun(
|
|
|
407
462
|
if (!holdoutPolicy.allowed) {
|
|
408
463
|
const priorHoldout = await db.query.journeyStates.findFirst({
|
|
409
464
|
where: and(
|
|
410
|
-
|
|
465
|
+
bySubject(journeyStates, {
|
|
466
|
+
contactId: await enrollmentContactId(),
|
|
467
|
+
userKey: userId,
|
|
468
|
+
}),
|
|
411
469
|
eq(journeyStates.journeyId, meta.id),
|
|
412
470
|
eq(journeyStates.status, "held_out"),
|
|
413
471
|
),
|
|
414
472
|
});
|
|
415
473
|
if (!priorHoldout) {
|
|
416
474
|
const heldOutAt = new Date();
|
|
417
|
-
// PRD 04 dual-write
|
|
418
|
-
//
|
|
419
|
-
//
|
|
420
|
-
//
|
|
421
|
-
// control-flow change to the
|
|
422
|
-
//
|
|
423
|
-
|
|
424
|
-
const heldOutContactId = await resolveEnrollmentContactId({
|
|
425
|
-
db,
|
|
426
|
-
userId,
|
|
427
|
-
journeyId: meta.id,
|
|
428
|
-
pushed: input.contactId,
|
|
429
|
-
});
|
|
475
|
+
// PRD 04 dual-write, via the run-scoped memo the guard above already
|
|
476
|
+
// paid for (identical arguments, so identical value). Deliberately
|
|
477
|
+
// NOT the `subjectContactId` compute below: that one lives INSIDE the
|
|
478
|
+
// ingest try/catch, and hoisting it would change which failures skip
|
|
479
|
+
// the `journey.heldout` re-emit — a control-flow change to the
|
|
480
|
+
// identity-provenance path, made for bookkeeping.
|
|
481
|
+
const heldOutContactId = await enrollmentContactId();
|
|
430
482
|
const inserted = await db
|
|
431
483
|
.insert(journeyStates)
|
|
432
484
|
.values({
|
|
@@ -560,7 +612,10 @@ export async function executeJourneyRun(
|
|
|
560
612
|
|
|
561
613
|
const activeState = await db.query.journeyStates.findFirst({
|
|
562
614
|
where: and(
|
|
563
|
-
|
|
615
|
+
bySubject(journeyStates, {
|
|
616
|
+
contactId: await enrollmentContactId(),
|
|
617
|
+
userKey: userId,
|
|
618
|
+
}),
|
|
564
619
|
eq(journeyStates.journeyId, meta.id),
|
|
565
620
|
inArray(journeyStates.status, ["active", "waiting"]),
|
|
566
621
|
),
|
|
@@ -574,6 +629,21 @@ export async function executeJourneyRun(
|
|
|
574
629
|
return { status: "skipped", reason: activePolicy.reason };
|
|
575
630
|
}
|
|
576
631
|
|
|
632
|
+
// PRD 04 dual-write — the pushed pin when ingest resolved one, else one
|
|
633
|
+
// D6-wrapped probe. NULL (unknown subject / refused resolve) is a legal
|
|
634
|
+
// stamp: the enrollment proceeds exactly as before. Resolved FRESH here
|
|
635
|
+
// (not via the guard-time memo): the guard chain is long enough for a
|
|
636
|
+
// concurrent identify to mint the subject's contact mid-window, and a
|
|
637
|
+
// stale NULL stamp on the insert would sit outside the contact-scoped
|
|
638
|
+
// unique index that backstops double-enrollment. The memo cache is
|
|
639
|
+
// refreshed with the result so later readers agree with the stamp.
|
|
640
|
+
resolvedContactId = await resolveEnrollmentContactId({
|
|
641
|
+
db,
|
|
642
|
+
userId,
|
|
643
|
+
journeyId: meta.id,
|
|
644
|
+
pushed: input.contactId,
|
|
645
|
+
});
|
|
646
|
+
|
|
577
647
|
// A successful insert always returns exactly one row, so undefined here
|
|
578
648
|
// can ONLY mean a burst-race conflict (see insertEnrollment's doc for
|
|
579
649
|
// the race + arbiter mechanics) — the same outcome as the read guard,
|
|
@@ -592,15 +662,7 @@ export async function executeJourneyRun(
|
|
|
592
662
|
hatchetRunId: workflowRunId,
|
|
593
663
|
journeyVersionHash: meta.versionHash ?? null,
|
|
594
664
|
journeyVersionLabel: meta.version ?? null,
|
|
595
|
-
|
|
596
|
-
// D6-wrapped probe. NULL (unknown subject / refused resolve) is a legal
|
|
597
|
-
// stamp: the enrollment proceeds exactly as before.
|
|
598
|
-
contactId: await resolveEnrollmentContactId({
|
|
599
|
-
db,
|
|
600
|
-
userId,
|
|
601
|
-
journeyId: meta.id,
|
|
602
|
-
pushed: input.contactId,
|
|
603
|
-
}),
|
|
665
|
+
contactId: resolvedContactId,
|
|
604
666
|
serializeWithGraphLock: options.serializeEnrollment,
|
|
605
667
|
});
|
|
606
668
|
if (!state) {
|
|
@@ -634,6 +696,9 @@ export async function executeJourneyRun(
|
|
|
634
696
|
stateId,
|
|
635
697
|
journeyId: meta.id,
|
|
636
698
|
journeyName: meta.name,
|
|
699
|
+
// The enrollment row's OWN stamp — replay-stable (a recovered run reads
|
|
700
|
+
// back what first entry wrote) and NULL for a contactless subject.
|
|
701
|
+
contactId: state.contactId,
|
|
637
702
|
};
|
|
638
703
|
|
|
639
704
|
// The injected analytics instance (set by createHogsendClient). Same
|
|
@@ -708,14 +773,18 @@ export async function executeJourneyRun(
|
|
|
708
773
|
journeyId: meta.id,
|
|
709
774
|
entryLimit: meta.entryLimit,
|
|
710
775
|
...(meta.entryPeriod ? { entryPeriod: meta.entryPeriod } : {}),
|
|
711
|
-
//
|
|
712
|
-
//
|
|
713
|
-
//
|
|
714
|
-
//
|
|
715
|
-
//
|
|
776
|
+
// The subject contact id — feeds BOTH the group-scope resolver and (PRD
|
|
777
|
+
// 05 T4) every bySubject history read on the context. `state.contactId`
|
|
778
|
+
// FIRST: it is the enrollment row's own stamp, validated by
|
|
779
|
+
// `resolveEnrollmentContactId` (a merged-away tombstone pin is rejected
|
|
780
|
+
// and re-resolved to the survivor) and replay-stable, where the raw
|
|
781
|
+
// pushed pin can be stale by the queue delay and the `contact` row here
|
|
782
|
+
// is an externalId-only best-effort fetch that misses anon-keyed
|
|
783
|
+
// contacts. The pin/row legs remain only as fallbacks for a NULL stamp
|
|
784
|
+
// (a pre-column-era recovered enrollment the sweep has not reached).
|
|
716
785
|
...(input.groups ? { triggerGroups: input.groups } : {}),
|
|
717
|
-
...((input.contactId ?? contact?.id)
|
|
718
|
-
? { contactId: input.contactId ?? contact?.id }
|
|
786
|
+
...((state.contactId ?? input.contactId ?? contact?.id)
|
|
787
|
+
? { contactId: state.contactId ?? input.contactId ?? contact?.id }
|
|
719
788
|
: {}),
|
|
720
789
|
});
|
|
721
790
|
|