@hogsend/engine 0.58.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 +61 -8
- package/src/buckets/membership-epoch.ts +11 -1
- package/src/campaigns/cohort-sql.ts +3 -0
- package/src/index.ts +26 -6
- package/src/journeys/execute-journey-run.ts +180 -29
- 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 +518 -148
- 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 +23 -2
- package/src/lib/journey-lift.ts +17 -5
- package/src/lib/preferences.ts +116 -30
- 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 +50 -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 +18 -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/index.ts +2 -0
- package/src/routes/admin/journey-impact.ts +18 -9
- package/src/routes/admin/journeys.ts +8 -1
- package/src/routes/admin/maintenance.ts +216 -0
- package/src/routes/admin/preferences.ts +85 -38
- 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 +11 -6
- package/src/worker.ts +20 -0
- package/src/workflows/backfill-contact-id.ts +951 -0
- package/src/workflows/bucket-backfill.ts +145 -59
- package/src/workflows/bucket-reconcile.ts +154 -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
|
@@ -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,
|
|
@@ -15,7 +15,7 @@ import {
|
|
|
15
15
|
import { and, eq, inArray, isNull, notInArray, or, sql } from "drizzle-orm";
|
|
16
16
|
import { getAnalytics } from "../lib/analytics-singleton.js";
|
|
17
17
|
import { blueprintGraphLock } from "../lib/blueprint-lock.js";
|
|
18
|
-
import { ALL_IDENTITY_KINDS } from "../lib/contacts.js";
|
|
18
|
+
import { ALL_IDENTITY_KINDS, lookupContactIdByKey } from "../lib/contacts.js";
|
|
19
19
|
import { getDb } from "../lib/db.js";
|
|
20
20
|
import {
|
|
21
21
|
checkEmailPreferences,
|
|
@@ -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 {
|
|
@@ -102,6 +106,55 @@ export interface JourneyDurableCtx {
|
|
|
102
106
|
/** The `journey_states` row an enrollment insert returns. */
|
|
103
107
|
export type JourneyStateRow = typeof journeyStates.$inferSelect;
|
|
104
108
|
|
|
109
|
+
/**
|
|
110
|
+
* PRD 04 dual-write resolve for the two `journey_states` insert sites (the
|
|
111
|
+
* enrollment row and the held_out row).
|
|
112
|
+
*
|
|
113
|
+
* D6 — a bookkeeping resolve may NEVER fail the operation it rides on: every
|
|
114
|
+
* failure degrades to NULL plus a warn, because a missing `contact_id` is a
|
|
115
|
+
* NULL a backfill fills later while a throwing enrollment is an outage.
|
|
116
|
+
*
|
|
117
|
+
* The pushed `input.contactId` is preferred — `ingestEvent` already resolved the
|
|
118
|
+
* subject before routing the event here — but it is VALIDATED, not trusted. The
|
|
119
|
+
* pin was computed at INGEST time and then crossed an unbounded Hatchet queue
|
|
120
|
+
* delay; a contact MERGE inside that window soft-deletes the pinned loser and
|
|
121
|
+
* re-aliases its key onto the survivor. Stamping the pin blindly would write a
|
|
122
|
+
* TOMBSTONE id, and that stamp is PERMANENT: the backfill only fills NULLs (it
|
|
123
|
+
* is not a repair tool) and T3's merge re-point ran before this row existed.
|
|
124
|
+
* Worse, the pin-ABSENT path would have got it right — `lookupContactIdByKey`'s
|
|
125
|
+
* alias probe refuses soft-deleted targets and follows the key to the survivor.
|
|
126
|
+
*
|
|
127
|
+
* So: ONE indexed live-PK probe on the pin, and on a miss FALL THROUGH to the
|
|
128
|
+
* ordinary key probe (survivor, or null). Any failure degrades to NULL per D6.
|
|
129
|
+
*/
|
|
130
|
+
async function resolveEnrollmentContactId(opts: {
|
|
131
|
+
db: Database;
|
|
132
|
+
userId: string;
|
|
133
|
+
journeyId: string;
|
|
134
|
+
pushed?: string;
|
|
135
|
+
}): Promise<string | null> {
|
|
136
|
+
try {
|
|
137
|
+
if (opts.pushed) {
|
|
138
|
+
const live = await opts.db
|
|
139
|
+
.select({ id: contacts.id })
|
|
140
|
+
.from(contacts)
|
|
141
|
+
.where(and(eq(contacts.id, opts.pushed), isNull(contacts.deletedAt)))
|
|
142
|
+
.limit(1);
|
|
143
|
+
if (live[0]) return live[0].id;
|
|
144
|
+
// Pin went stale between ingest and execution (merged away, or hard
|
|
145
|
+
// deleted). Fall through rather than stamping the tombstone.
|
|
146
|
+
}
|
|
147
|
+
return await lookupContactIdByKey(opts.db, opts.userId);
|
|
148
|
+
} catch (err) {
|
|
149
|
+
logger.warn("journey_states contact_id dual-write resolve failed", {
|
|
150
|
+
journeyId: opts.journeyId,
|
|
151
|
+
userId: opts.userId,
|
|
152
|
+
error: err instanceof Error ? err.message : String(err),
|
|
153
|
+
});
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
105
158
|
/**
|
|
106
159
|
* Insert the enrollment row, tolerating the partial-unique-index race.
|
|
107
160
|
*
|
|
@@ -122,6 +175,17 @@ export type JourneyStateRow = typeof journeyStates.$inferSelect;
|
|
|
122
175
|
* CONFLICT specification") at runtime. The `where` reproduces the index
|
|
123
176
|
* predicate (`status IN ('active','waiting')`) EXACTLY — see
|
|
124
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.
|
|
125
189
|
*/
|
|
126
190
|
export async function insertEnrollment(opts: {
|
|
127
191
|
db: Database;
|
|
@@ -148,6 +212,15 @@ export async function insertEnrollment(opts: {
|
|
|
148
212
|
*/
|
|
149
213
|
journeyVersionHash?: string | null;
|
|
150
214
|
journeyVersionLabel?: string | null;
|
|
215
|
+
/**
|
|
216
|
+
* PRD 04 dual-write: the `contacts.id` owning `userId`, stamped alongside the
|
|
217
|
+
* canonical string key. OPTIONAL and defaulting to NULL — this is public API
|
|
218
|
+
* (index.ts) and bookkeeping, so a caller that omits it (dogfood tests, any
|
|
219
|
+
* pre-PRD-04 consumer) behaves exactly as before. The RESOLVE lives in the
|
|
220
|
+
* caller, never here: `executeJourneyRun` already holds the pushed
|
|
221
|
+
* `input.contactId` and only pays for a lookup when it doesn't.
|
|
222
|
+
*/
|
|
223
|
+
contactId?: string | null;
|
|
151
224
|
}): Promise<JourneyStateRow | undefined> {
|
|
152
225
|
const values = {
|
|
153
226
|
userId: opts.userId,
|
|
@@ -159,30 +232,46 @@ export async function insertEnrollment(opts: {
|
|
|
159
232
|
hatchetRunId: opts.hatchetRunId,
|
|
160
233
|
journeyVersionHash: opts.journeyVersionHash ?? null,
|
|
161
234
|
journeyVersionLabel: opts.journeyVersionLabel ?? null,
|
|
235
|
+
contactId: opts.contactId ?? null,
|
|
162
236
|
};
|
|
163
237
|
const onConflict = {
|
|
164
238
|
target: [journeyStates.userId, journeyStates.journeyId],
|
|
165
239
|
where: sql`status IN ('active', 'waiting')`,
|
|
166
240
|
};
|
|
167
241
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
.
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
+
}
|
|
176
251
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
.
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
+
}
|
|
186
275
|
}
|
|
187
276
|
|
|
188
277
|
export interface ExecuteJourneyRunOptions {
|
|
@@ -276,6 +365,26 @@ export async function executeJourneyRun(
|
|
|
276
365
|
|
|
277
366
|
let state = recovered;
|
|
278
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
|
+
|
|
279
388
|
// FIRST ENTRY ONLY — the enrollment guards gate ENTRY, not resume. A
|
|
280
389
|
// recovered enrollment already passed them on first entry, so it skips
|
|
281
390
|
// straight to resuming the run. (Sends inside `run` still re-check
|
|
@@ -305,6 +414,7 @@ export async function executeJourneyRun(
|
|
|
305
414
|
db,
|
|
306
415
|
journey: meta,
|
|
307
416
|
userId,
|
|
417
|
+
contactId: await enrollmentContactId(),
|
|
308
418
|
});
|
|
309
419
|
const entryPolicy = evaluateEnrollmentPolicy({
|
|
310
420
|
journey: meta,
|
|
@@ -315,7 +425,11 @@ export async function executeJourneyRun(
|
|
|
315
425
|
return { status: "skipped", reason: entryPolicy.reason };
|
|
316
426
|
}
|
|
317
427
|
|
|
318
|
-
const prefs = await checkEmailPreferences({
|
|
428
|
+
const prefs = await checkEmailPreferences({
|
|
429
|
+
db,
|
|
430
|
+
userId,
|
|
431
|
+
contactId: await enrollmentContactId(),
|
|
432
|
+
});
|
|
319
433
|
const preferencePolicy = evaluateEnrollmentPolicy({
|
|
320
434
|
journey: meta,
|
|
321
435
|
properties,
|
|
@@ -348,13 +462,23 @@ export async function executeJourneyRun(
|
|
|
348
462
|
if (!holdoutPolicy.allowed) {
|
|
349
463
|
const priorHoldout = await db.query.journeyStates.findFirst({
|
|
350
464
|
where: and(
|
|
351
|
-
|
|
465
|
+
bySubject(journeyStates, {
|
|
466
|
+
contactId: await enrollmentContactId(),
|
|
467
|
+
userKey: userId,
|
|
468
|
+
}),
|
|
352
469
|
eq(journeyStates.journeyId, meta.id),
|
|
353
470
|
eq(journeyStates.status, "held_out"),
|
|
354
471
|
),
|
|
355
472
|
});
|
|
356
473
|
if (!priorHoldout) {
|
|
357
474
|
const heldOutAt = new Date();
|
|
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();
|
|
358
482
|
const inserted = await db
|
|
359
483
|
.insert(journeyStates)
|
|
360
484
|
.values({
|
|
@@ -363,6 +487,7 @@ export async function executeJourneyRun(
|
|
|
363
487
|
journeyId: meta.id,
|
|
364
488
|
currentNodeId: "held-out",
|
|
365
489
|
status: "held_out",
|
|
490
|
+
contactId: heldOutContactId,
|
|
366
491
|
// Reserved record-once namespaces are STRIPPED from event
|
|
367
492
|
// properties before seeding (injection fix): a publishable-key
|
|
368
493
|
// event must never pre-fill __once__/__digest__/__throttle__/
|
|
@@ -487,7 +612,10 @@ export async function executeJourneyRun(
|
|
|
487
612
|
|
|
488
613
|
const activeState = await db.query.journeyStates.findFirst({
|
|
489
614
|
where: and(
|
|
490
|
-
|
|
615
|
+
bySubject(journeyStates, {
|
|
616
|
+
contactId: await enrollmentContactId(),
|
|
617
|
+
userKey: userId,
|
|
618
|
+
}),
|
|
491
619
|
eq(journeyStates.journeyId, meta.id),
|
|
492
620
|
inArray(journeyStates.status, ["active", "waiting"]),
|
|
493
621
|
),
|
|
@@ -501,6 +629,21 @@ export async function executeJourneyRun(
|
|
|
501
629
|
return { status: "skipped", reason: activePolicy.reason };
|
|
502
630
|
}
|
|
503
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
|
+
|
|
504
647
|
// A successful insert always returns exactly one row, so undefined here
|
|
505
648
|
// can ONLY mean a burst-race conflict (see insertEnrollment's doc for
|
|
506
649
|
// the race + arbiter mechanics) — the same outcome as the read guard,
|
|
@@ -519,6 +662,7 @@ export async function executeJourneyRun(
|
|
|
519
662
|
hatchetRunId: workflowRunId,
|
|
520
663
|
journeyVersionHash: meta.versionHash ?? null,
|
|
521
664
|
journeyVersionLabel: meta.version ?? null,
|
|
665
|
+
contactId: resolvedContactId,
|
|
522
666
|
serializeWithGraphLock: options.serializeEnrollment,
|
|
523
667
|
});
|
|
524
668
|
if (!state) {
|
|
@@ -552,6 +696,9 @@ export async function executeJourneyRun(
|
|
|
552
696
|
stateId,
|
|
553
697
|
journeyId: meta.id,
|
|
554
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,
|
|
555
702
|
};
|
|
556
703
|
|
|
557
704
|
// The injected analytics instance (set by createHogsendClient). Same
|
|
@@ -626,14 +773,18 @@ export async function executeJourneyRun(
|
|
|
626
773
|
journeyId: meta.id,
|
|
627
774
|
entryLimit: meta.entryLimit,
|
|
628
775
|
...(meta.entryPeriod ? { entryPeriod: meta.entryPeriod } : {}),
|
|
629
|
-
//
|
|
630
|
-
//
|
|
631
|
-
//
|
|
632
|
-
//
|
|
633
|
-
//
|
|
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).
|
|
634
785
|
...(input.groups ? { triggerGroups: input.groups } : {}),
|
|
635
|
-
...((input.contactId ?? contact?.id)
|
|
636
|
-
? { contactId: input.contactId ?? contact?.id }
|
|
786
|
+
...((state.contactId ?? input.contactId ?? contact?.id)
|
|
787
|
+
? { contactId: state.contactId ?? input.contactId ?? contact?.id }
|
|
637
788
|
: {}),
|
|
638
789
|
});
|
|
639
790
|
|
|
@@ -9,6 +9,7 @@ import {
|
|
|
9
9
|
} from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
10
10
|
import type { DurationObject } from "@hogsend/core";
|
|
11
11
|
import {
|
|
12
|
+
bySubject,
|
|
12
13
|
durationToMs,
|
|
13
14
|
evaluateEventCondition,
|
|
14
15
|
evaluatePropertyConditions,
|
|
@@ -229,6 +230,15 @@ export function createJourneyContext(
|
|
|
229
230
|
defaultSendWindow,
|
|
230
231
|
} = config;
|
|
231
232
|
|
|
233
|
+
// PRD 05 T4 — the subject a history read is about. The run's resolved
|
|
234
|
+
// `contactId` applies ONLY to the ENROLLED user: `ctx.history.*` takes an
|
|
235
|
+
// arbitrary `userId` from author code, and scoping someone else's key to THIS
|
|
236
|
+
// run's contact would read the wrong person. A key that is not the enrolled
|
|
237
|
+
// one has no contact in hand, so it keeps `bySubject`'s text-key arm — which
|
|
238
|
+
// is exactly today's behavior for it.
|
|
239
|
+
const subjectFor = (targetUserId: string): string | null =>
|
|
240
|
+
targetUserId === userId ? (config.contactId ?? null) : null;
|
|
241
|
+
|
|
232
242
|
// Replay-stable clock: the real DurableContext.now() is memoized across
|
|
233
243
|
// replays; a pre-eviction engine (or a test ctx without it) falls back to the
|
|
234
244
|
// live clock. Only RECOMPUTED instants depend on this — never the DB-key
|
|
@@ -477,7 +487,10 @@ export function createJourneyContext(
|
|
|
477
487
|
// association map; user scope keeps the enrolled-user predicate.
|
|
478
488
|
groupScope
|
|
479
489
|
? sql`${userEvents.groups} ->> ${groupScope.type} = ${groupScope.key}`
|
|
480
|
-
:
|
|
490
|
+
: bySubject(userEvents, {
|
|
491
|
+
contactId: config.contactId,
|
|
492
|
+
userKey: userId,
|
|
493
|
+
}),
|
|
481
494
|
eq(userEvents.event, event),
|
|
482
495
|
gte(userEvents.occurredAt, scanSince),
|
|
483
496
|
...eqPreds,
|
|
@@ -676,7 +689,10 @@ export function createJourneyContext(
|
|
|
676
689
|
.from(userEvents)
|
|
677
690
|
.where(
|
|
678
691
|
and(
|
|
679
|
-
|
|
692
|
+
bySubject(userEvents, {
|
|
693
|
+
contactId: config.contactId,
|
|
694
|
+
userKey: userId,
|
|
695
|
+
}),
|
|
680
696
|
eq(userEvents.event, event),
|
|
681
697
|
gte(userEvents.occurredAt, since),
|
|
682
698
|
),
|
|
@@ -815,7 +831,10 @@ export function createJourneyContext(
|
|
|
815
831
|
.from(userEvents)
|
|
816
832
|
.where(
|
|
817
833
|
and(
|
|
818
|
-
|
|
834
|
+
bySubject(userEvents, {
|
|
835
|
+
contactId: config.contactId,
|
|
836
|
+
userKey: userId,
|
|
837
|
+
}),
|
|
819
838
|
eq(userEvents.event, event),
|
|
820
839
|
gte(userEvents.occurredAt, scanSince),
|
|
821
840
|
lte(userEvents.occurredAt, flushInstant),
|
|
@@ -1416,7 +1435,11 @@ export function createJourneyContext(
|
|
|
1416
1435
|
|
|
1417
1436
|
guard: {
|
|
1418
1437
|
async isSubscribed() {
|
|
1419
|
-
const prefs = await checkEmailPreferences({
|
|
1438
|
+
const prefs = await checkEmailPreferences({
|
|
1439
|
+
db,
|
|
1440
|
+
userId,
|
|
1441
|
+
contactId: config.contactId ?? null,
|
|
1442
|
+
});
|
|
1420
1443
|
return !prefs.unsubscribed;
|
|
1421
1444
|
},
|
|
1422
1445
|
},
|
|
@@ -1462,7 +1485,12 @@ export function createJourneyContext(
|
|
|
1462
1485
|
check: "exists",
|
|
1463
1486
|
within,
|
|
1464
1487
|
},
|
|
1465
|
-
ctx: {
|
|
1488
|
+
ctx: {
|
|
1489
|
+
db,
|
|
1490
|
+
userId: targetUserId,
|
|
1491
|
+
contactId: subjectFor(targetUserId),
|
|
1492
|
+
journeyContext,
|
|
1493
|
+
},
|
|
1466
1494
|
});
|
|
1467
1495
|
return { found: result.matched, count: result.count };
|
|
1468
1496
|
},
|
|
@@ -1476,7 +1504,10 @@ export function createJourneyContext(
|
|
|
1476
1504
|
.from(journeyStates)
|
|
1477
1505
|
.where(
|
|
1478
1506
|
and(
|
|
1479
|
-
|
|
1507
|
+
bySubject(journeyStates, {
|
|
1508
|
+
contactId: subjectFor(targetUserId),
|
|
1509
|
+
userKey: targetUserId,
|
|
1510
|
+
}),
|
|
1480
1511
|
eq(journeyStates.journeyId, targetJourneyId),
|
|
1481
1512
|
),
|
|
1482
1513
|
);
|
|
@@ -1549,7 +1580,12 @@ export function createJourneyContext(
|
|
|
1549
1580
|
limit = 50,
|
|
1550
1581
|
within,
|
|
1551
1582
|
}): Promise<RecentEvent[]> {
|
|
1552
|
-
const conditions = [
|
|
1583
|
+
const conditions = [
|
|
1584
|
+
bySubject(userEvents, {
|
|
1585
|
+
contactId: subjectFor(targetUserId),
|
|
1586
|
+
userKey: targetUserId,
|
|
1587
|
+
}),
|
|
1588
|
+
];
|
|
1553
1589
|
if (event) {
|
|
1554
1590
|
conditions.push(eq(userEvents.event, event));
|
|
1555
1591
|
}
|
package/src/lib/agent/tools.ts
CHANGED
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import {
|
|
2
|
+
bySubject,
|
|
3
|
+
criteriaBuilder,
|
|
4
|
+
days,
|
|
5
|
+
evaluateCondition,
|
|
6
|
+
} from "@hogsend/core";
|
|
2
7
|
import {
|
|
3
8
|
contacts,
|
|
4
9
|
emailPreferences,
|
|
@@ -130,6 +135,9 @@ export function buildAgentTools({
|
|
|
130
135
|
return db
|
|
131
136
|
.select({
|
|
132
137
|
event: userEvents.event,
|
|
138
|
+
// Display echo of the stamped key — not a scoping predicate. This
|
|
139
|
+
// tool lists the recent event stream instance-wide; there is no
|
|
140
|
+
// subject to scope by.
|
|
133
141
|
userId: userEvents.userId,
|
|
134
142
|
source: userEvents.source,
|
|
135
143
|
occurredAt: userEvents.occurredAt,
|
|
@@ -169,10 +177,18 @@ export function buildAgentTools({
|
|
|
169
177
|
execute: async ({ id }) => {
|
|
170
178
|
const contact = await resolveContact({ db, id });
|
|
171
179
|
if (!contact) return { error: `No contact for "${id}"` };
|
|
180
|
+
// Was `contact.externalId ?? contact.id` — an inline re-derivation of
|
|
181
|
+
// the canonical key that missed a preferences row written under an
|
|
182
|
+
// anonymous id. The owning contact names it directly.
|
|
172
183
|
const prefs = await db
|
|
173
184
|
.select()
|
|
174
185
|
.from(emailPreferences)
|
|
175
|
-
.where(
|
|
186
|
+
.where(
|
|
187
|
+
bySubject(emailPreferences, {
|
|
188
|
+
contactId: contact.id,
|
|
189
|
+
userKey: contactKey(contact),
|
|
190
|
+
}),
|
|
191
|
+
)
|
|
176
192
|
.limit(1);
|
|
177
193
|
return { contact, preferences: prefs[0] ?? null };
|
|
178
194
|
},
|
|
@@ -189,6 +205,10 @@ export function buildAgentTools({
|
|
|
189
205
|
const contact = await resolveContact({ db, id });
|
|
190
206
|
if (!contact) return { error: `No contact for "${id}"` };
|
|
191
207
|
const key = contactKey(contact);
|
|
208
|
+
// Read by subject: the contact was just resolved, so both legs scope
|
|
209
|
+
// on the `contact_id` FK and pick up activity from keys this person
|
|
210
|
+
// has since moved off.
|
|
211
|
+
const subject = { contactId: contact.id, userKey: key };
|
|
192
212
|
const [events, journeys] = await Promise.all([
|
|
193
213
|
db
|
|
194
214
|
.select({
|
|
@@ -197,7 +217,7 @@ export function buildAgentTools({
|
|
|
197
217
|
occurredAt: userEvents.occurredAt,
|
|
198
218
|
})
|
|
199
219
|
.from(userEvents)
|
|
200
|
-
.where(
|
|
220
|
+
.where(bySubject(userEvents, subject))
|
|
201
221
|
.orderBy(desc(userEvents.occurredAt))
|
|
202
222
|
.limit(limit),
|
|
203
223
|
db
|
|
@@ -209,7 +229,7 @@ export function buildAgentTools({
|
|
|
209
229
|
.from(journeyStates)
|
|
210
230
|
.where(
|
|
211
231
|
and(
|
|
212
|
-
|
|
232
|
+
bySubject(journeyStates, subject),
|
|
213
233
|
isNull(journeyStates.deletedAt),
|
|
214
234
|
),
|
|
215
235
|
)
|
|
@@ -296,6 +316,11 @@ export function buildAgentTools({
|
|
|
296
316
|
ctx: {
|
|
297
317
|
db,
|
|
298
318
|
userId: contactKey(c),
|
|
319
|
+
// Every row here IS a contact, so the evaluator's event leaf
|
|
320
|
+
// counts that contact's whole history — including events stamped
|
|
321
|
+
// under an earlier anonymous key. Without this the audience
|
|
322
|
+
// preview under-counts anyone who registered after being seen.
|
|
323
|
+
contactId: c.id,
|
|
299
324
|
journeyContext: (c.properties ?? {}) as Record<string, unknown>,
|
|
300
325
|
},
|
|
301
326
|
});
|
|
@@ -134,6 +134,7 @@ export async function backfillAttributionBatch(opts: {
|
|
|
134
134
|
id: userEvents.id,
|
|
135
135
|
event: userEvents.event,
|
|
136
136
|
userId: userEvents.userId,
|
|
137
|
+
contactId: userEvents.contactId,
|
|
137
138
|
properties: userEvents.properties,
|
|
138
139
|
value: userEvents.value,
|
|
139
140
|
currency: userEvents.currency,
|
|
@@ -151,9 +152,13 @@ export async function backfillAttributionBatch(opts: {
|
|
|
151
152
|
.orderBy(asc(userEvents.id))
|
|
152
153
|
.limit(limit);
|
|
153
154
|
|
|
154
|
-
//
|
|
155
|
-
//
|
|
156
|
-
|
|
155
|
+
// Owner resolution. A row stamped with `contact_id` already names its
|
|
156
|
+
// owner, so only the unstamped remainder needs the string lookup:
|
|
157
|
+
// canonical keys are externalId or the contact row uuid. MATCH ONLY —
|
|
158
|
+
// backfill never mints contacts.
|
|
159
|
+
const keys = [
|
|
160
|
+
...new Set(rows.filter((row) => !row.contactId).map((row) => row.userId)),
|
|
161
|
+
];
|
|
157
162
|
const uuidKeys = keys.filter((key) => UUID_RE.test(key));
|
|
158
163
|
const contactRows =
|
|
159
164
|
keys.length > 0
|
|
@@ -178,7 +183,7 @@ export async function backfillAttributionBatch(opts: {
|
|
|
178
183
|
let conversionsFired = 0;
|
|
179
184
|
let creditsWritten = 0;
|
|
180
185
|
for (const row of rows) {
|
|
181
|
-
const contactId = contactByKey.get(row.userId);
|
|
186
|
+
const contactId = row.contactId ?? contactByKey.get(row.userId);
|
|
182
187
|
if (!contactId) continue;
|
|
183
188
|
const fired = await evaluateConversionsAtIngest({
|
|
184
189
|
db,
|
|
@@ -206,6 +211,15 @@ export async function backfillAttributionBatch(opts: {
|
|
|
206
211
|
logger,
|
|
207
212
|
conversionId: conversion.conversionId,
|
|
208
213
|
userKey: row.userId,
|
|
214
|
+
// Scope the touchpoint path by the OWNER only when the spine row
|
|
215
|
+
// itself carries the stamp. This function replays HISTORY, and
|
|
216
|
+
// pre-upgrade history predates the `contact_id` dual-write entirely:
|
|
217
|
+
// an unstamped trigger row sits among unstamped touchpoints, which a
|
|
218
|
+
// contact-scoped scan cannot reach at all. When the trigger IS
|
|
219
|
+
// stamped, everything older is too (PRD 04's sweep cursors ascending
|
|
220
|
+
// by id), so the contact arm is both safe and the point — it reaches
|
|
221
|
+
// the anon-era touches adoption moved onto this person.
|
|
222
|
+
contactId: row.contactId,
|
|
209
223
|
value: conversion.value,
|
|
210
224
|
currency: conversion.currency,
|
|
211
225
|
occurredAt: row.occurredAt,
|
|
@@ -240,11 +254,17 @@ export async function backfillAttributionBatch(opts: {
|
|
|
240
254
|
id: conversions.id,
|
|
241
255
|
definitionId: conversions.definitionId,
|
|
242
256
|
userKey: conversions.userKey,
|
|
257
|
+
contactId: conversions.contactId,
|
|
258
|
+
// The trigger row's own stamp — the same "is this spine stamped?" test
|
|
259
|
+
// stage 1 applies, joined in because a conversions row always names an
|
|
260
|
+
// owner even when the history behind it predates `contact_id`.
|
|
261
|
+
spineContactId: userEvents.contactId,
|
|
243
262
|
value: conversions.value,
|
|
244
263
|
currency: conversions.currency,
|
|
245
264
|
occurredAt: conversions.occurredAt,
|
|
246
265
|
})
|
|
247
266
|
.from(conversions)
|
|
267
|
+
.leftJoin(userEvents, eq(conversions.eventId, userEvents.id))
|
|
248
268
|
.where(
|
|
249
269
|
and(
|
|
250
270
|
inArray(conversions.definitionId, defIds),
|
|
@@ -265,6 +285,9 @@ export async function backfillAttributionBatch(opts: {
|
|
|
265
285
|
logger,
|
|
266
286
|
conversionId: row.id,
|
|
267
287
|
userKey: row.userKey,
|
|
288
|
+
// See stage 1: the owner scopes the path only when the spine carries the
|
|
289
|
+
// stamp; unstamped (pre-upgrade) history is reachable by string key only.
|
|
290
|
+
contactId: row.spineContactId ? row.contactId : null,
|
|
268
291
|
value: row.value,
|
|
269
292
|
currency: row.currency,
|
|
270
293
|
occurredAt: row.occurredAt,
|
package/src/lib/attribution.ts
CHANGED
|
@@ -3,6 +3,7 @@ import {
|
|
|
3
3
|
computeAllModels,
|
|
4
4
|
} from "@hogsend/attribution";
|
|
5
5
|
import {
|
|
6
|
+
bySubject,
|
|
6
7
|
type DurationObject,
|
|
7
8
|
durationToMs,
|
|
8
9
|
TOUCHPOINT_EVENTS,
|
|
@@ -120,6 +121,16 @@ export async function recordAttributionCredits(opts: {
|
|
|
120
121
|
conversionId: string;
|
|
121
122
|
/** The contact's canonical event key (`user_events.user_id`). */
|
|
122
123
|
userKey: string;
|
|
124
|
+
/**
|
|
125
|
+
* The trusted owner uuid (`conversions.contact_id`). REQUIRED (not
|
|
126
|
+
* optional) for the same reason the enrollment guards' is: an optional
|
|
127
|
+
* field silently defaults a new caller onto the mutable text key, and the
|
|
128
|
+
* touchpoint path is precisely the history written BEFORE the person was
|
|
129
|
+
* identified — a key-scoped read drops the anonymous half of every journey
|
|
130
|
+
* and credits the conversion to nothing. Pass `null` explicitly for a
|
|
131
|
+
* subject with no contact; `userKey` still serves that case.
|
|
132
|
+
*/
|
|
133
|
+
contactId: string | null;
|
|
123
134
|
value: number | null;
|
|
124
135
|
currency: string | null;
|
|
125
136
|
/** When the conversion happened. */
|
|
@@ -132,8 +143,16 @@ export async function recordAttributionCredits(opts: {
|
|
|
132
143
|
*/
|
|
133
144
|
windows?: Partial<Record<TouchpointChannel, DurationObject>>;
|
|
134
145
|
}): Promise<{ touchpoints: number }> {
|
|
135
|
-
const {
|
|
136
|
-
|
|
146
|
+
const {
|
|
147
|
+
db,
|
|
148
|
+
logger,
|
|
149
|
+
conversionId,
|
|
150
|
+
userKey,
|
|
151
|
+
contactId,
|
|
152
|
+
value,
|
|
153
|
+
currency,
|
|
154
|
+
occurredAt,
|
|
155
|
+
} = opts;
|
|
137
156
|
const defaultWindowMs = opts.windowDays * 24 * 60 * 60 * 1000;
|
|
138
157
|
const channelWindowMs = new Map<TouchpointChannel, number>(
|
|
139
158
|
Object.entries(opts.windows ?? {}).map(([channel, duration]) => [
|
|
@@ -158,7 +177,7 @@ export async function recordAttributionCredits(opts: {
|
|
|
158
177
|
.from(userEvents)
|
|
159
178
|
.where(
|
|
160
179
|
and(
|
|
161
|
-
|
|
180
|
+
bySubject(userEvents, { contactId, userKey }),
|
|
162
181
|
inArray(userEvents.event, [...TOUCHPOINT_EVENTS]),
|
|
163
182
|
gte(userEvents.occurredAt, windowStart),
|
|
164
183
|
lte(userEvents.occurredAt, occurredAt),
|
|
@@ -224,9 +224,12 @@ export async function checkActionAudience(
|
|
|
224
224
|
});
|
|
225
225
|
}
|
|
226
226
|
|
|
227
|
+
// PRD 05 T6 — the contact row is in hand, so the read is contact-scoped
|
|
228
|
+
// directly; the old `externalId ?? id` string derivation is the idiom the
|
|
229
|
+
// flip retires.
|
|
227
230
|
const prefs = await readRecipientPreferences(db, {
|
|
228
231
|
email: contact.email,
|
|
229
|
-
|
|
232
|
+
contactId: contact.id,
|
|
230
233
|
});
|
|
231
234
|
if (prefs.unsubscribedAll) {
|
|
232
235
|
return {
|