@hogsend/engine 0.56.0 → 0.57.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +11 -11
- package/src/buckets/bucket-access.ts +5 -10
- package/src/buckets/check-membership.ts +78 -6
- package/src/index.ts +31 -1
- package/src/journeys/execute-journey-run.ts +56 -1
- package/src/journeys/journey-context.ts +59 -0
- package/src/lib/bucket-emit.test.ts +83 -2
- package/src/lib/bucket-emit.ts +16 -0
- package/src/lib/contacts.ts +1031 -141
- package/src/lib/crm-ingest.ts +9 -0
- package/src/lib/feed.ts +64 -3
- package/src/lib/identity-service.ts +15 -2
- package/src/lib/ingestion.ts +180 -14
- package/src/lib/tracking-events.ts +33 -6
- package/src/routes/admin/agent.ts +26 -0
- package/src/routes/admin/contacts.ts +65 -5
- package/src/routes/admin/identity.ts +197 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/contacts/index.ts +50 -7
- package/src/routes/events/index.ts +94 -6
- package/src/routes/feed/index.ts +36 -0
- package/src/routes/feed/recipient.ts +44 -2
- package/src/routes/lists/index.ts +21 -0
- package/src/routes/tracking/arrive.ts +42 -3
- package/src/worker.ts +18 -0
- package/src/workflows/bucket-backfill.ts +1 -1
- package/src/workflows/bucket-reconcile.ts +129 -4
- package/src/workflows/identity-alias-backfill.ts +448 -0
- package/src/workflows/import-contacts.ts +10 -0
- package/src/workflows/send-campaign.ts +31 -13
package/src/lib/crm-ingest.ts
CHANGED
|
@@ -89,6 +89,15 @@ export async function ingestCrmStageEvents(opts: {
|
|
|
89
89
|
const resolved = await resolveOrCreateContact({
|
|
90
90
|
db,
|
|
91
91
|
email: event.email,
|
|
92
|
+
// PRD 06 T4 (L5 row 20): a CRM webhook asserts identity by email
|
|
93
|
+
// only, so create-on-miss (a named CRM contact is an assertion, not
|
|
94
|
+
// observation), no clamp, and the narrow `trustedKinds` is the
|
|
95
|
+
// honest statement of what this caller supplies. Enforced by T5.
|
|
96
|
+
policy: {
|
|
97
|
+
create: "on-miss",
|
|
98
|
+
allowMerge: "any",
|
|
99
|
+
trustedKinds: ["email"],
|
|
100
|
+
},
|
|
92
101
|
});
|
|
93
102
|
contactId = resolved.id;
|
|
94
103
|
canonicalKey = resolved.resolvedKey;
|
package/src/lib/feed.ts
CHANGED
|
@@ -6,7 +6,13 @@ import {
|
|
|
6
6
|
} from "../journeys/journey-boundary.js";
|
|
7
7
|
import { IN_APP_LIST_ID } from "../lists/channels.js";
|
|
8
8
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
9
|
-
import {
|
|
9
|
+
import {
|
|
10
|
+
ALL_IDENTITY_KINDS,
|
|
11
|
+
type ResolvePolicy,
|
|
12
|
+
resolveContactNoCreate,
|
|
13
|
+
resolveOrCreateContact,
|
|
14
|
+
resolveRecipient,
|
|
15
|
+
} from "./contacts.js";
|
|
10
16
|
import { getDb } from "./db.js";
|
|
11
17
|
import { createLogger } from "./logger.js";
|
|
12
18
|
import { readRecipientPreferences } from "./recipient-preferences.js";
|
|
@@ -136,12 +142,67 @@ export async function sendFeedItem(
|
|
|
136
142
|
// (1) Resolve recipient → canonical key. Throws on a zero-key recipient (same
|
|
137
143
|
// contract as `resolveOrCreateContact`). This is a server/journey-side send —
|
|
138
144
|
// never a browser write — so no `restrictToAnonymous` clamp.
|
|
139
|
-
|
|
145
|
+
//
|
|
146
|
+
// OBSERVATION, NOT ASSERTION (D1) — on the PURE-`anonymousId` arm, and only
|
|
147
|
+
// there. A browser anon id handed to a journey is not an identity anyone
|
|
148
|
+
// asserted; re-resolving it is observation. Left creating, an anonymous in-app
|
|
149
|
+
// visitor gets an `external_id = <anonId>` row — and `resolveFeedRecipient`
|
|
150
|
+
// then rejects a publishable `anonymousId` that collides with an identified
|
|
151
|
+
// contact's canonical key, so the ghost 403-LOCKS that visitor out of their
|
|
152
|
+
// own bell.
|
|
153
|
+
//
|
|
154
|
+
// So a MISS on a recipient carrying ONLY an `anonymousId` refuses to mint.
|
|
155
|
+
// Nothing is lost: `resolveContactNoCreate` returns the SAME `resolvedKey` the
|
|
156
|
+
// create arm would have made canonical (`external_id ?? anonymous_id`), which
|
|
157
|
+
// is byte-identical to the key the bell polls, and `feed_items.contact_id` is
|
|
158
|
+
// nullable with no foreign key (verified against the 0034 DDL), so the row
|
|
159
|
+
// still lands and still reads back. A HIT is untouched — it links/merges
|
|
160
|
+
// exactly as before.
|
|
161
|
+
//
|
|
162
|
+
// THE `userId` ARM KEEPS CREATING, and its mint is LOAD-BEARING FOR
|
|
163
|
+
// CONFIDENTIALITY — not merely a ghost. `sendFeedItem` stores an identified
|
|
164
|
+
// recipient's rows under that recipient's canonical key, and the minted row is
|
|
165
|
+
// the ONLY signal `collidesWithIdentified` (contacts.ts) has that the string is
|
|
166
|
+
// somebody's key. Refuse the mint and nothing collides, so the publishable ANON
|
|
167
|
+
// arm of `resolveFeedRecipient` (routes/feed/recipient.ts) accepts
|
|
168
|
+
// `?anonymousId=<that userId>` as a self-addressing anon id and hands the
|
|
169
|
+
// caller that recipient's feed items — plus mark / mark-all over them.
|
|
170
|
+
// Refusing here silently converts a private feed row into an anon-addressable
|
|
171
|
+
// one. D1 says the same thing from the other end: a server-asserted `userId`
|
|
172
|
+
// IS a minting trigger.
|
|
173
|
+
//
|
|
174
|
+
// The other two conjuncts are D8:
|
|
175
|
+
// - an asserted `email` KEEPS CREATING. It is a durable identity the caller
|
|
176
|
+
// is asserting (D1), and it is never a canonical key — so refusing it
|
|
177
|
+
// would key history on a row uuid that was never minted, which is exactly
|
|
178
|
+
// the misuse `resolveContactNoCreate` THROWS on.
|
|
179
|
+
// - no `anonymousId` ⇒ there is no stable key to refuse WITH; same throw.
|
|
180
|
+
// (A zero-key recipient already threw above.)
|
|
181
|
+
const refusable =
|
|
182
|
+
!recipient.email?.trim() &&
|
|
183
|
+
!recipient.userId?.trim() &&
|
|
184
|
+
!!recipient.anonymousId?.trim();
|
|
185
|
+
// PRD 06 T4 (L5 rows 10-11): trust is DECLARED by this caller. A feed send
|
|
186
|
+
// is a journey/server-side write, never a browser assertion, so it declares
|
|
187
|
+
// full server trust — `allowMerge: "any"` (no clamp) and all four kinds.
|
|
188
|
+
// Only the `create` leg varies, keyed off the SAME `refusable` verdict that
|
|
189
|
+
// selects the entry point below, so the policy and the entry point can
|
|
190
|
+
// never disagree (each entry point throws on a mismatched `create`).
|
|
191
|
+
const policy: ResolvePolicy = {
|
|
192
|
+
create: refusable ? "refuse-on-miss" : "on-miss",
|
|
193
|
+
allowMerge: "any",
|
|
194
|
+
trustedKinds: ALL_IDENTITY_KINDS,
|
|
195
|
+
};
|
|
196
|
+
const resolveOpts = {
|
|
140
197
|
db,
|
|
141
198
|
userId: recipient.userId,
|
|
142
199
|
email: recipient.email,
|
|
143
200
|
anonymousId: recipient.anonymousId,
|
|
144
|
-
|
|
201
|
+
policy,
|
|
202
|
+
};
|
|
203
|
+
const { id: contactId, resolvedKey } = refusable
|
|
204
|
+
? await resolveContactNoCreate(resolveOpts)
|
|
205
|
+
: await resolveOrCreateContact(resolveOpts);
|
|
145
206
|
const recipientKey = resolvedKey;
|
|
146
207
|
|
|
147
208
|
// (2) Replay-safe idempotency key (mirrors `sendEmail`), derived
|
|
@@ -4,7 +4,7 @@ import {
|
|
|
4
4
|
logResidualTwins,
|
|
5
5
|
mergeAnalyticsIdentities,
|
|
6
6
|
} from "./analytics-identity.js";
|
|
7
|
-
import { resolveOrCreateContact } from "./contacts.js";
|
|
7
|
+
import { ALL_IDENTITY_KINDS, resolveOrCreateContact } from "./contacts.js";
|
|
8
8
|
import type { Logger } from "./logger.js";
|
|
9
9
|
|
|
10
10
|
/**
|
|
@@ -68,7 +68,20 @@ export function createIdentityService(deps: {
|
|
|
68
68
|
|
|
69
69
|
return {
|
|
70
70
|
async linkContact(args) {
|
|
71
|
-
|
|
71
|
+
// PRD 06 T4 (L5 row 19): the connector entry point (Discord/Telegram
|
|
72
|
+
// `/link`) declares full server trust — a `discord` key is the whole
|
|
73
|
+
// point of this service, so all four kinds, create-on-miss, no clamp.
|
|
74
|
+
// Declared now, enforced by T5. `args` cannot carry a policy
|
|
75
|
+
// ({@link LinkContactArgs} omits it), so nothing is clobbered.
|
|
76
|
+
const result = await resolveOrCreateContact({
|
|
77
|
+
db,
|
|
78
|
+
...args,
|
|
79
|
+
policy: {
|
|
80
|
+
create: "on-miss",
|
|
81
|
+
allowMerge: "any",
|
|
82
|
+
trustedKinds: ALL_IDENTITY_KINDS,
|
|
83
|
+
},
|
|
84
|
+
});
|
|
72
85
|
|
|
73
86
|
const {
|
|
74
87
|
id: contactId,
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -29,6 +29,8 @@ import {
|
|
|
29
29
|
import { recordAttributionCredits } from "./attribution.js";
|
|
30
30
|
import {
|
|
31
31
|
ContactProvenanceLostError,
|
|
32
|
+
type ResolvePolicy,
|
|
33
|
+
resolveContactNoCreate,
|
|
32
34
|
resolveOrCreateContact,
|
|
33
35
|
} from "./contacts.js";
|
|
34
36
|
import {
|
|
@@ -112,6 +114,19 @@ export interface IngestEvent {
|
|
|
112
114
|
source?: string;
|
|
113
115
|
}
|
|
114
116
|
|
|
117
|
+
/**
|
|
118
|
+
* The shape `ingestEvent` reads a resolve through, whichever entry point
|
|
119
|
+
* produced it: `resolveOrCreateContact`'s result widened at `id` ONLY, so
|
|
120
|
+
* `resolveContactNoCreate`'s refusal (`id: null`) is assignable while the
|
|
121
|
+
* published create-on-miss return type never widens (D3 — three sites annotate
|
|
122
|
+
* on `Awaited<ReturnType<typeof resolveOrCreateContact>>`, one of them the
|
|
123
|
+
* exported `IdentityService.linkContact`).
|
|
124
|
+
*/
|
|
125
|
+
type ResolvedIdentity = Omit<
|
|
126
|
+
Awaited<ReturnType<typeof resolveOrCreateContact>>,
|
|
127
|
+
"id"
|
|
128
|
+
> & { id: string | null };
|
|
129
|
+
|
|
115
130
|
export interface ExitResult {
|
|
116
131
|
journeyId: string;
|
|
117
132
|
stateId: string;
|
|
@@ -149,8 +164,38 @@ export async function ingestTransformResult(opts: {
|
|
|
149
164
|
logger: Logger;
|
|
150
165
|
source: string;
|
|
151
166
|
analytics?: AnalyticsProvider;
|
|
167
|
+
/**
|
|
168
|
+
* D1 creation guard, forwarded VERBATIM to every element (see
|
|
169
|
+
* {@link ingestEvent}). A PER-CALL parameter that defaults to `true` — never
|
|
170
|
+
* a default flip: `routes/webhooks/sources.ts` shares this helper, and a
|
|
171
|
+
* webhook source is a server-side caller that legitimately mints contacts.
|
|
172
|
+
* Only a caller that knows its events are pure OBSERVATION passes `false`.
|
|
173
|
+
*/
|
|
174
|
+
allowCreate?: boolean;
|
|
175
|
+
/**
|
|
176
|
+
* Explicit caller trust (PRD 06 T4, L5 row 28), forwarded VERBATIM to every
|
|
177
|
+
* element's {@link ingestEvent} — including its `create` leg, so a
|
|
178
|
+
* transform-sourced refusal is never silently lost. This helper is a
|
|
179
|
+
* PASS-THROUGH, not a trust boundary: the caller of `ingestTransformResult`
|
|
180
|
+
* IS the caller of the resolve, so the whole declaration travels, not just
|
|
181
|
+
* one leg. Mutually exclusive with the legacy `allowCreate` field —
|
|
182
|
+
* supplying both shapes throws (no precedence rule exists). Absent ⇒ the
|
|
183
|
+
* legacy field (or its default) applies unchanged.
|
|
184
|
+
*/
|
|
185
|
+
policy?: ResolvePolicy;
|
|
152
186
|
}): Promise<{ ingested: number; exits: number }> {
|
|
153
187
|
const { result, db, registry, hatchet, logger, source, analytics } = opts;
|
|
188
|
+
// PRD 06: EITHER trust shape, never both — enforced HERE, before the loop.
|
|
189
|
+
// `ingestEvent` would throw the same complaint per element, but this
|
|
190
|
+
// helper's per-element error isolation would swallow that into a warn and
|
|
191
|
+
// return `{ ingested: 0 }`, silently converting a caller bug into "no
|
|
192
|
+
// events". A misdeclared trust shape must fail loudly instead.
|
|
193
|
+
if (opts.policy && opts.allowCreate !== undefined) {
|
|
194
|
+
throw new Error(
|
|
195
|
+
"ingestTransformResult: pass either `policy` or the legacy " +
|
|
196
|
+
"`allowCreate`, never both — no precedence rule exists",
|
|
197
|
+
);
|
|
198
|
+
}
|
|
154
199
|
if (!result) return { ingested: 0, exits: 0 };
|
|
155
200
|
const events = Array.isArray(result) ? result : [result];
|
|
156
201
|
let ingested = 0;
|
|
@@ -176,6 +221,11 @@ export async function ingestTransformResult(opts: {
|
|
|
176
221
|
logger,
|
|
177
222
|
event: { ...event, source },
|
|
178
223
|
analytics,
|
|
224
|
+
// Exactly one of these is ever set (the mix threw above); an
|
|
225
|
+
// explicit-`undefined` sibling key does not trip `ingestEvent`'s own
|
|
226
|
+
// mutual-exclusion guard (it checks `!== undefined`).
|
|
227
|
+
allowCreate: opts.allowCreate,
|
|
228
|
+
policy: opts.policy,
|
|
179
229
|
});
|
|
180
230
|
ingested++;
|
|
181
231
|
exits += r.exits.length;
|
|
@@ -310,9 +360,52 @@ export async function ingestEvent(opts: {
|
|
|
310
360
|
* their behavior is unchanged.
|
|
311
361
|
*/
|
|
312
362
|
restrictToAnonymous?: boolean;
|
|
363
|
+
/**
|
|
364
|
+
* D1 CREATION GUARD. Defaults to `true` (create-on-miss — every existing
|
|
365
|
+
* caller is byte-for-byte unchanged). `false` resolves the identity WITHOUT
|
|
366
|
+
* minting a `contacts` row: seeing traffic from an unidentified browser is
|
|
367
|
+
* not grounds for a CRM row. Set by callers whose write is pure OBSERVATION.
|
|
368
|
+
*
|
|
369
|
+
* A refusal is NOT an error and loses NO observation (D2): the event still
|
|
370
|
+
* stores in `user_events` under the same canonical key, the Hatchet push and
|
|
371
|
+
* `checkExits` still run, and buckets are still evaluated. What a refused
|
|
372
|
+
* ingest skips is exactly the work that needs a `contacts` row: group
|
|
373
|
+
* association, and — because `conversions.contact_id` / `deals.contact_id` /
|
|
374
|
+
* `funnel_progress.contact_id` are `.notNull()` FKs with no degraded write
|
|
375
|
+
* available — conversions, attribution credits, and funnel progress (D9).
|
|
376
|
+
*
|
|
377
|
+
* PRECONDITION (D8, inherited from `resolveContactNoCreate`): THROWS unless
|
|
378
|
+
* the event's highest-precedence key is `userId` or `anonymousId`. An
|
|
379
|
+
* email-only / discordId-only event has no stable refusal key.
|
|
380
|
+
*/
|
|
381
|
+
allowCreate?: boolean;
|
|
382
|
+
/**
|
|
383
|
+
* Explicit caller trust (PRD 06 T3), forwarded VERBATIM into the identity
|
|
384
|
+
* resolve. The `create` leg also selects the resolver entry point (the D1
|
|
385
|
+
* branch below), replacing `allowCreate` for policy-declaring callers.
|
|
386
|
+
* Mutually exclusive with the legacy `restrictToAnonymous`/`allowCreate`
|
|
387
|
+
* fields — supplying both shapes throws (no precedence rule exists). Absent
|
|
388
|
+
* ⇒ the legacy fields (or their defaults) apply unchanged.
|
|
389
|
+
*/
|
|
390
|
+
policy?: ResolvePolicy;
|
|
313
391
|
}): Promise<IngestResult> {
|
|
314
392
|
const { db, registry, hatchet, logger, event, analytics, eventMirror } = opts;
|
|
315
393
|
|
|
394
|
+
// PRD 06: EITHER trust shape, never both. The resolver enforces the same rule
|
|
395
|
+
// for `restrictToAnonymous`, but `allowCreate` is consumed HERE (it selects
|
|
396
|
+
// the entry point and never reaches the resolver), so the ingest layer must
|
|
397
|
+
// refuse the mix itself rather than silently letting `policy` win the branch.
|
|
398
|
+
if (
|
|
399
|
+
opts.policy &&
|
|
400
|
+
(opts.restrictToAnonymous !== undefined || opts.allowCreate !== undefined)
|
|
401
|
+
) {
|
|
402
|
+
throw new Error(
|
|
403
|
+
"ingestEvent: pass either `policy` or the legacy fields " +
|
|
404
|
+
"(`restrictToAnonymous` / `allowCreate`), never both — no precedence " +
|
|
405
|
+
"rule exists",
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
|
|
316
409
|
// (1) Resolve identity FIRST (awaited — no longer fire-and-forget). The
|
|
317
410
|
// contact-referencing tables join on a NOT NULL text key, so an email-only /
|
|
318
411
|
// anonymous event (D1 optional userId) needs a canonical key resolved before
|
|
@@ -320,9 +413,9 @@ export async function ingestEvent(opts: {
|
|
|
320
413
|
// `contacts.properties` (D2 split) and returns BOTH the canonical contact id
|
|
321
414
|
// AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
|
|
322
415
|
// risk 1/6), so no second read-back of the contact row is needed.
|
|
323
|
-
let resolved:
|
|
416
|
+
let resolved: ResolvedIdentity;
|
|
324
417
|
try {
|
|
325
|
-
|
|
418
|
+
const resolveArgs = {
|
|
326
419
|
db,
|
|
327
420
|
userId: event.userId,
|
|
328
421
|
email: event.userEmail || undefined,
|
|
@@ -334,11 +427,28 @@ export async function ingestEvent(opts: {
|
|
|
334
427
|
contactId: event.contactId,
|
|
335
428
|
contactProperties: event.contactProperties,
|
|
336
429
|
restrictToAnonymous: opts.restrictToAnonymous,
|
|
430
|
+
// Explicit caller trust (PRD 06). Verbatim; `undefined` ⇒ legacy shape.
|
|
431
|
+
policy: opts.policy,
|
|
337
432
|
// First-touch contact provenance from the event's pipeline origin — a
|
|
338
433
|
// Contact Source ("clay"/"attio") or "api"/"posthog"/…; only stamped when
|
|
339
434
|
// the contact is created (or first fill-in-linked) with no prior source.
|
|
340
435
|
source: event.source,
|
|
341
|
-
}
|
|
436
|
+
};
|
|
437
|
+
// D1: BRANCH between the two sibling entry points rather than passing a flag
|
|
438
|
+
// down into one. Two reasons, both load-bearing. (a) `resolveOrCreateContact`
|
|
439
|
+
// must keep `id: string` in its published type (D3), so the refusal lives in
|
|
440
|
+
// a separate function — not an overload, which widens it. (b) A `boolean`
|
|
441
|
+
// VARIABLE cannot select an overload/conditional signature (TS2769), so the
|
|
442
|
+
// branch has to be here, at the one site that knows the literal.
|
|
443
|
+
// (PRD 06: a declared `policy` selects the same branch via its `create`
|
|
444
|
+
// leg — reason (a) keeps this a two-entry branch either way.)
|
|
445
|
+
resolved = (
|
|
446
|
+
opts.policy
|
|
447
|
+
? opts.policy.create !== "on-miss"
|
|
448
|
+
: opts.allowCreate === false
|
|
449
|
+
)
|
|
450
|
+
? await resolveContactNoCreate(resolveArgs)
|
|
451
|
+
: await resolveOrCreateContact(resolveArgs);
|
|
342
452
|
} catch (err) {
|
|
343
453
|
// Provenance pin pointed at a hard-deleted/unfollowable subject: drop the
|
|
344
454
|
// internal re-emit (do NOT value-fall-back — that could mint the very twin
|
|
@@ -357,6 +467,10 @@ export async function ingestEvent(opts: {
|
|
|
357
467
|
}
|
|
358
468
|
throw err;
|
|
359
469
|
}
|
|
470
|
+
// `contactId` is NULL exactly when the resolve REFUSED (allowCreate: false and
|
|
471
|
+
// no live row owned any supplied key). `resolvedKey` is always a real string —
|
|
472
|
+
// that is the whole point of D8 — so every history table below keys the same
|
|
473
|
+
// way it always did; only the eight contact-row consumers change shape.
|
|
360
474
|
const {
|
|
361
475
|
id: contactId,
|
|
362
476
|
resolvedKey,
|
|
@@ -461,7 +575,10 @@ export async function ingestEvent(opts: {
|
|
|
461
575
|
survivorKey: resolvedKey,
|
|
462
576
|
loserKeys: mergedKeys,
|
|
463
577
|
reason: merged ? "collide_merge" : "key_flip",
|
|
464
|
-
contactId,
|
|
578
|
+
// Sites 3/4: `contactId` is an OPTIONAL observability field on both, so
|
|
579
|
+
// a refusal degrades to `undefined`. Unreachable in practice — a merge
|
|
580
|
+
// or key flip means a row matched, which means nothing was refused.
|
|
581
|
+
contactId: contactId ?? undefined,
|
|
465
582
|
logger,
|
|
466
583
|
});
|
|
467
584
|
}
|
|
@@ -469,7 +586,7 @@ export async function ingestEvent(opts: {
|
|
|
469
586
|
logResidualTwins({
|
|
470
587
|
survivorKey: resolvedKey,
|
|
471
588
|
identifiedLoserKeys: mergedIdentifiedKeys,
|
|
472
|
-
contactId,
|
|
589
|
+
contactId: contactId ?? undefined,
|
|
473
590
|
logger,
|
|
474
591
|
});
|
|
475
592
|
}
|
|
@@ -529,7 +646,23 @@ export async function ingestEvent(opts: {
|
|
|
529
646
|
// path has NO idempotency key, so a thrown error + ingest retry would
|
|
530
647
|
// DOUBLE-insert the event) — a group-write hiccup must never fail an
|
|
531
648
|
// already-stored event.
|
|
532
|
-
|
|
649
|
+
// The `contactId !== null` arm is a TYPE guard, not a policy one:
|
|
650
|
+
// `group_memberships.contact_id` is a uuid FK, so there is nothing to join a
|
|
651
|
+
// refusal to. It must never BECOME the policy, because a silently-dropped
|
|
652
|
+
// association is exactly the regression D10 exists to prevent. What keeps it
|
|
653
|
+
// a type guard is enforced at the BOUNDARIES, not here: `/v1/events` is the
|
|
654
|
+
// only producer that can carry a `groups` map into an ingest that may refuse,
|
|
655
|
+
// and it carves `groups` out of `observationOnly` (routes/events/index.ts) so
|
|
656
|
+
// such an event keeps creating. Every other refusing caller — `/v1/t/arrive`
|
|
657
|
+
// and the D11 derived re-ingests (bucket emits, feed marks / `feed_cleared`,
|
|
658
|
+
// `ctx.trigger`, the holdout emit) — builds its own event and carries no
|
|
659
|
+
// `groups` map at all. ANY new refusing caller that can carry `groups` must
|
|
660
|
+
// carve it out at its own boundary rather than leaning on this branch.
|
|
661
|
+
if (
|
|
662
|
+
contactId !== null &&
|
|
663
|
+
event.groups &&
|
|
664
|
+
Object.keys(event.groups).length > 0
|
|
665
|
+
) {
|
|
533
666
|
try {
|
|
534
667
|
await associateGroups({ db, contactId, groups: event.groups });
|
|
535
668
|
} catch (err) {
|
|
@@ -570,7 +703,13 @@ export async function ingestEvent(opts: {
|
|
|
570
703
|
// enrolling on this event can re-emit for the SAME subject by row id
|
|
571
704
|
// (folds, never mints a twin). Additive/optional — consumers ignoring it
|
|
572
705
|
// are unaffected.
|
|
573
|
-
|
|
706
|
+
//
|
|
707
|
+
// Site 2 — the ONE consumer the compiler cannot catch, because the push
|
|
708
|
+
// payload is an untyped JSON envelope. On a refusal the key is OMITTED
|
|
709
|
+
// ENTIRELY: a JSON `null` down the journey wire is NOT the same as absent
|
|
710
|
+
// (`execute-journey-run` falls back to `contact?.id` only for a missing
|
|
711
|
+
// key), and it would ride into every durable input the run replays from.
|
|
712
|
+
...(contactId !== null ? { contactId } : {}),
|
|
574
713
|
// The event's group association map (groupType → groupKey), so a
|
|
575
714
|
// group-scoped wait can match on membership straight off the wire.
|
|
576
715
|
// Always present ({} when the event carries none) so downstream CEL
|
|
@@ -655,7 +794,16 @@ export async function ingestEvent(opts: {
|
|
|
655
794
|
|
|
656
795
|
// (5c) Conversion-point evaluation (plan §5.1) — the unique
|
|
657
796
|
// (definition, event) index makes any replay a no-op.
|
|
658
|
-
|
|
797
|
+
//
|
|
798
|
+
// Site 5 — SKIPPED WHOLE on a refusal (D9). `conversions.contact_id` is
|
|
799
|
+
// `.notNull().references(contacts.id)` and `packages/db` is out of boundary,
|
|
800
|
+
// so no degraded write exists; the conversion, its ad-platform dispatches
|
|
801
|
+
// (which key on `conversionEventId({ contactId, … })`) and its attribution
|
|
802
|
+
// credits all go together. Consequence, stated plainly: an anonymous event
|
|
803
|
+
// that fires a revenue conversion today stops firing under a refusal — which
|
|
804
|
+
// is why a browser event carrying `value` is treated as an identity assertion
|
|
805
|
+
// upstream and keeps creating (PRD 02 site 1).
|
|
806
|
+
if (insertedRow && hookEvent && contactId !== null) {
|
|
659
807
|
try {
|
|
660
808
|
const fired = await evaluateConversionsAtIngest({
|
|
661
809
|
db,
|
|
@@ -724,7 +872,11 @@ export async function ingestEvent(opts: {
|
|
|
724
872
|
// money events it mints (`deal.quoted`/`deal.sold`) recurse through
|
|
725
873
|
// ingestEvent, bounded at define time: `deal.`/`funnel.`/`crm.` events
|
|
726
874
|
// cannot be stage triggers.
|
|
727
|
-
|
|
875
|
+
//
|
|
876
|
+
// Sites 6 + 7 — SKIPPED on a refusal (D9), same reasoning as site 5:
|
|
877
|
+
// `deals.contact_id` (the mover's target) and `funnel_progress.contact_id`
|
|
878
|
+
// (the reporting projection's unique key) are both `.notNull()` FKs.
|
|
879
|
+
if (insertedRow && hookEvent && contactId !== null) {
|
|
728
880
|
const funnelRegistry = getCrmSyncConfig()?.funnels;
|
|
729
881
|
if (funnelRegistry) {
|
|
730
882
|
try {
|
|
@@ -786,11 +938,25 @@ export async function ingestEvent(opts: {
|
|
|
786
938
|
hatchet,
|
|
787
939
|
logger,
|
|
788
940
|
userId: resolvedKey,
|
|
789
|
-
//
|
|
790
|
-
//
|
|
791
|
-
//
|
|
792
|
-
//
|
|
793
|
-
|
|
941
|
+
// Site 8 — the one consumer that must NOT skip. `bucket_memberships` is
|
|
942
|
+
// text-keyed on the canonical key with no contact FK, so an anon key stays
|
|
943
|
+
// fully eligible for event/count buckets and D2 holds: observation is
|
|
944
|
+
// never lost.
|
|
945
|
+
//
|
|
946
|
+
// What it must ALSO not do is degrade the pin to `contactId ?? undefined`.
|
|
947
|
+
// That compiles (the param is `contactId?: string`) and looks like the
|
|
948
|
+
// obvious null-guard, but it re-opens issue #608 from the other side:
|
|
949
|
+
// `emitBucketTransition` would re-ingest `bucket:entered:<id>` with
|
|
950
|
+
// `userId = <anon id>`, `findByKey` misses on `external_id`, and the CREATE
|
|
951
|
+
// arm mints a row with `external_id = <anonId>, email NULL` — a ghost
|
|
952
|
+
// strictly WORSE than the one being removed, because
|
|
953
|
+
// `collidesWithIdentified` then returns true for it and
|
|
954
|
+
// `resolveFeedRecipient` starts 403-ing the visitor out of their own bell.
|
|
955
|
+
//
|
|
956
|
+
// So the refusal is INHERITED instead: pass the pin when there is a row,
|
|
957
|
+
// and `allowCreate: false` when there is not, forwarded into BOTH of
|
|
958
|
+
// `emitBucketTransition`'s re-ingests.
|
|
959
|
+
...(contactId !== null ? { contactId } : { allowCreate: false }),
|
|
794
960
|
userEmail: event.userEmail || null,
|
|
795
961
|
event: event.event,
|
|
796
962
|
eventProperties: event.eventProperties,
|
|
@@ -235,12 +235,37 @@ export interface PushLinkClickEventOpts {
|
|
|
235
235
|
* as the first-party `link.clicked` event so journeys can trigger / await a
|
|
236
236
|
* click of a SPECIFIC managed link (filtered by `linkId`/`campaign`).
|
|
237
237
|
*
|
|
238
|
-
* IDENTITY GATE (crash-guard):
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
238
|
+
* IDENTITY GATE (crash-guard): the resolve THROWS on a zero-key event, so a
|
|
239
|
+
* broadcast/public link (`distinctId == null`) returns `undefined` WITHOUT
|
|
240
|
+
* calling ingest. The click route ALSO suppresses bot/prefetch hits upstream
|
|
241
|
+
* (`isBotOrPrefetch`), so an unfurl bot never reaches here. All six payload
|
|
242
|
+
* keys are scalars (or null) so they survive ingest and reach `trigger.where` +
|
|
243
|
+
* `waitForEvent.properties`.
|
|
244
|
+
*
|
|
245
|
+
* NEVER MINTS (D11). This is a re-ingest DERIVED from an earlier observation,
|
|
246
|
+
* so it inherits that observation's refusal — `allowCreate: false`. `mintLink`
|
|
247
|
+
* copies whatever `distinctId` the caller passes for a `personal` link, so a
|
|
248
|
+
* link minted for a visitor who was never identified carries an ANON key; with
|
|
249
|
+
* creation allowed the create arm wrote `external_id = <anonId>`, the shape
|
|
250
|
+
* #621 calls strictly WORSE than the ghost it replaces (it then answers
|
|
251
|
+
* `collidesWithIdentified` (contacts.ts) and 403-locks the visitor out of their
|
|
252
|
+
* own feed). Safe by construction: a link carrying a `distinctId` was minted for
|
|
253
|
+
* someone already known, so either the key resolves — fill-in-link, unchanged —
|
|
254
|
+
* or it was refused at observation time and must STAY refused.
|
|
255
|
+
*
|
|
256
|
+
* Unlike `sendFeedItem`'s `userId` arm (lib/feed.ts), the mint here has no
|
|
257
|
+
* confidentiality role. There it is load-bearing: the minted row is the only
|
|
258
|
+
* signal `collidesWithIdentified` has, and refusing would convert a private
|
|
259
|
+
* feed row into an anon-addressable one. This is an event ingest, not a
|
|
260
|
+
* feed-read authorization — `collidesWithIdentified` is consulted only by
|
|
261
|
+
* `routes/feed/recipient.ts` and `routes/tracking/arrive.ts`, neither of which
|
|
262
|
+
* reads anything this function writes.
|
|
263
|
+
*
|
|
264
|
+
* Nothing is lost by the refusal: `resolvedKey` is always a real string (D8),
|
|
265
|
+
* so `user_events` still stores under the same key and journeys still trigger.
|
|
266
|
+
* `tracked_links` has no `contact_id` column (only `distinctId`), so inheriting
|
|
267
|
+
* the refusal is the correct fix rather than threading a provenance pin — if a
|
|
268
|
+
* later change adds `contact_id` there, revisit.
|
|
244
269
|
*
|
|
245
270
|
* Distinct from the per-hit OUTBOUND `link.clicked` webhook: that fires for
|
|
246
271
|
* EVERY hit and carries `trackedLinks.id` + the raw mint distinctId; THIS bus
|
|
@@ -257,6 +282,8 @@ export async function pushLinkClickEvent(
|
|
|
257
282
|
registry,
|
|
258
283
|
hatchet,
|
|
259
284
|
logger,
|
|
285
|
+
// D11 — see the header. A derived re-ingest never re-resolves into a mint.
|
|
286
|
+
allowCreate: false,
|
|
260
287
|
event: {
|
|
261
288
|
event: LINK_CLICKED,
|
|
262
289
|
userId: distinctId,
|
|
@@ -21,6 +21,7 @@ import { effectiveTier } from "../../lib/agent/risk.js";
|
|
|
21
21
|
import { buildAgentSystemPrompt } from "../../lib/agent/system-prompt.js";
|
|
22
22
|
import { buildAgentTools } from "../../lib/agent/tools.js";
|
|
23
23
|
import {
|
|
24
|
+
ALL_IDENTITY_KINDS,
|
|
24
25
|
resolveContact,
|
|
25
26
|
resolveOrCreateContact,
|
|
26
27
|
softDeleteContact,
|
|
@@ -297,6 +298,15 @@ agentRouter.post("/confirm", async (c) => {
|
|
|
297
298
|
db,
|
|
298
299
|
userId: args.userId as string | undefined,
|
|
299
300
|
email: args.email as string | undefined,
|
|
301
|
+
// PRD 06 T4 (L5 row 16): the subscribe/unsubscribe tool takes an
|
|
302
|
+
// email/userId only (the 400 above rejects neither-key calls), so
|
|
303
|
+
// the narrow `trustedKinds` is the honest statement; create-on-miss,
|
|
304
|
+
// no clamp. Enforced by T5.
|
|
305
|
+
policy: {
|
|
306
|
+
create: "on-miss",
|
|
307
|
+
allowMerge: "any",
|
|
308
|
+
trustedKinds: ["external", "email"],
|
|
309
|
+
},
|
|
300
310
|
});
|
|
301
311
|
try {
|
|
302
312
|
await applyListMembership({
|
|
@@ -327,6 +337,14 @@ agentRouter.post("/confirm", async (c) => {
|
|
|
327
337
|
email: args.email as string | undefined,
|
|
328
338
|
anonymousId: args.anonymousId as string | undefined,
|
|
329
339
|
contactProperties: (args.properties ?? {}) as Record<string, unknown>,
|
|
340
|
+
// PRD 06 T4 (L5 row 17): an admin-agent upsert may assert any kind
|
|
341
|
+
// (the tool accepts userId/email/anonymousId) — full grant,
|
|
342
|
+
// create-on-miss, no clamp. Enforced by T5.
|
|
343
|
+
policy: {
|
|
344
|
+
create: "on-miss",
|
|
345
|
+
allowMerge: "any",
|
|
346
|
+
trustedKinds: ALL_IDENTITY_KINDS,
|
|
347
|
+
},
|
|
330
348
|
});
|
|
331
349
|
break;
|
|
332
350
|
|
|
@@ -339,6 +357,14 @@ agentRouter.post("/confirm", async (c) => {
|
|
|
339
357
|
email: (args.email as string) ?? current.email ?? undefined,
|
|
340
358
|
anonymousId: current.anonymousId ?? undefined,
|
|
341
359
|
contactProperties: (args.properties ?? {}) as Record<string, unknown>,
|
|
360
|
+
// PRD 06 T4 (L5 row 18): the update tool re-supplies the row's OWN
|
|
361
|
+
// keys to ride the fill-in-link path (mirrors the admin update
|
|
362
|
+
// route) — full grant, create-on-miss, no clamp. Enforced by T5.
|
|
363
|
+
policy: {
|
|
364
|
+
create: "on-miss",
|
|
365
|
+
allowMerge: "any",
|
|
366
|
+
trustedKinds: ALL_IDENTITY_KINDS,
|
|
367
|
+
},
|
|
342
368
|
});
|
|
343
369
|
break;
|
|
344
370
|
}
|