@hogsend/engine 0.55.0 → 0.57.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +11 -11
- package/src/buckets/bucket-access.ts +5 -10
- package/src/buckets/check-membership.ts +91 -6
- package/src/index.ts +31 -1
- package/src/journeys/execute-journey-run.ts +56 -1
- package/src/journeys/journey-context.ts +59 -0
- package/src/lib/bucket-emit.test.ts +83 -2
- package/src/lib/bucket-emit.ts +16 -0
- package/src/lib/contacts.ts +1031 -141
- package/src/lib/crm-ingest.ts +9 -0
- package/src/lib/enrichment-ledger.ts +1 -1
- package/src/lib/feed.ts +64 -3
- package/src/lib/identity-service.ts +15 -2
- package/src/lib/ingestion.ts +191 -14
- package/src/lib/outbound.ts +3 -3
- package/src/lib/refine-chain.test.ts +83 -25
- package/src/lib/refine-chain.ts +124 -23
- package/src/lib/refine-traits.test.ts +74 -41
- package/src/lib/refine-traits.ts +107 -52
- package/src/lib/refine.ts +28 -27
- package/src/lib/tracking-events.ts +33 -6
- package/src/routes/admin/agent.ts +26 -0
- package/src/routes/admin/contacts.ts +65 -5
- package/src/routes/admin/identity.ts +197 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/contacts/index.ts +50 -7
- package/src/routes/events/index.ts +94 -6
- package/src/routes/feed/index.ts +36 -0
- package/src/routes/feed/recipient.ts +44 -2
- package/src/routes/lists/index.ts +21 -0
- package/src/routes/tracking/arrive.ts +42 -3
- package/src/worker.ts +18 -0
- package/src/workflows/bucket-backfill.ts +1 -1
- package/src/workflows/bucket-reconcile.ts +129 -4
- package/src/workflows/identity-alias-backfill.ts +448 -0
- package/src/workflows/import-contacts.ts +10 -0
- package/src/workflows/send-campaign.ts +31 -13
package/src/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;
|
|
@@ -22,7 +22,7 @@ export interface EnrichmentLookupRow {
|
|
|
22
22
|
refinedAt: Date;
|
|
23
23
|
expiresAt: Date;
|
|
24
24
|
raw: Record<string, unknown> | null;
|
|
25
|
-
/** The normalized
|
|
25
|
+
/** The normalized canonical trait patch the paid answer produced. */
|
|
26
26
|
traits: Record<string, unknown> | null;
|
|
27
27
|
spendWindow: Date | null;
|
|
28
28
|
spendCount: number;
|
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 {
|
|
@@ -71,6 +73,14 @@ export interface IngestEvent {
|
|
|
71
73
|
eventProperties: Record<string, unknown>;
|
|
72
74
|
/** D2: → `contacts.properties` merge ONLY. */
|
|
73
75
|
contactProperties?: Record<string, unknown>;
|
|
76
|
+
/**
|
|
77
|
+
* Extra property NAMES to re-evaluate buckets for — candidate-narrowing ONLY,
|
|
78
|
+
* NOT written and NOT in value eval. Lets a producer whose write patch omits a
|
|
79
|
+
* key (e.g. refinement's fill-if-absent, which drops already-held facts so it
|
|
80
|
+
* never clobbers first-party data) still trigger a fit bucket that references
|
|
81
|
+
* that key. Off by default; only engine-internal callers set it.
|
|
82
|
+
*/
|
|
83
|
+
touchProperties?: string[];
|
|
74
84
|
/**
|
|
75
85
|
* The groupType→groupKey association map for this event — persisted on
|
|
76
86
|
* `user_events.groups`, drives group membership (each group row is ensured +
|
|
@@ -104,6 +114,19 @@ export interface IngestEvent {
|
|
|
104
114
|
source?: string;
|
|
105
115
|
}
|
|
106
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
|
+
|
|
107
130
|
export interface ExitResult {
|
|
108
131
|
journeyId: string;
|
|
109
132
|
stateId: string;
|
|
@@ -141,8 +164,38 @@ export async function ingestTransformResult(opts: {
|
|
|
141
164
|
logger: Logger;
|
|
142
165
|
source: string;
|
|
143
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;
|
|
144
186
|
}): Promise<{ ingested: number; exits: number }> {
|
|
145
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
|
+
}
|
|
146
199
|
if (!result) return { ingested: 0, exits: 0 };
|
|
147
200
|
const events = Array.isArray(result) ? result : [result];
|
|
148
201
|
let ingested = 0;
|
|
@@ -168,6 +221,11 @@ export async function ingestTransformResult(opts: {
|
|
|
168
221
|
logger,
|
|
169
222
|
event: { ...event, source },
|
|
170
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,
|
|
171
229
|
});
|
|
172
230
|
ingested++;
|
|
173
231
|
exits += r.exits.length;
|
|
@@ -302,9 +360,52 @@ export async function ingestEvent(opts: {
|
|
|
302
360
|
* their behavior is unchanged.
|
|
303
361
|
*/
|
|
304
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;
|
|
305
391
|
}): Promise<IngestResult> {
|
|
306
392
|
const { db, registry, hatchet, logger, event, analytics, eventMirror } = opts;
|
|
307
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
|
+
|
|
308
409
|
// (1) Resolve identity FIRST (awaited — no longer fire-and-forget). The
|
|
309
410
|
// contact-referencing tables join on a NOT NULL text key, so an email-only /
|
|
310
411
|
// anonymous event (D1 optional userId) needs a canonical key resolved before
|
|
@@ -312,9 +413,9 @@ export async function ingestEvent(opts: {
|
|
|
312
413
|
// `contacts.properties` (D2 split) and returns BOTH the canonical contact id
|
|
313
414
|
// AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
|
|
314
415
|
// risk 1/6), so no second read-back of the contact row is needed.
|
|
315
|
-
let resolved:
|
|
416
|
+
let resolved: ResolvedIdentity;
|
|
316
417
|
try {
|
|
317
|
-
|
|
418
|
+
const resolveArgs = {
|
|
318
419
|
db,
|
|
319
420
|
userId: event.userId,
|
|
320
421
|
email: event.userEmail || undefined,
|
|
@@ -326,11 +427,28 @@ export async function ingestEvent(opts: {
|
|
|
326
427
|
contactId: event.contactId,
|
|
327
428
|
contactProperties: event.contactProperties,
|
|
328
429
|
restrictToAnonymous: opts.restrictToAnonymous,
|
|
430
|
+
// Explicit caller trust (PRD 06). Verbatim; `undefined` ⇒ legacy shape.
|
|
431
|
+
policy: opts.policy,
|
|
329
432
|
// First-touch contact provenance from the event's pipeline origin — a
|
|
330
433
|
// Contact Source ("clay"/"attio") or "api"/"posthog"/…; only stamped when
|
|
331
434
|
// the contact is created (or first fill-in-linked) with no prior source.
|
|
332
435
|
source: event.source,
|
|
333
|
-
}
|
|
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);
|
|
334
452
|
} catch (err) {
|
|
335
453
|
// Provenance pin pointed at a hard-deleted/unfollowable subject: drop the
|
|
336
454
|
// internal re-emit (do NOT value-fall-back — that could mint the very twin
|
|
@@ -349,6 +467,10 @@ export async function ingestEvent(opts: {
|
|
|
349
467
|
}
|
|
350
468
|
throw err;
|
|
351
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.
|
|
352
474
|
const {
|
|
353
475
|
id: contactId,
|
|
354
476
|
resolvedKey,
|
|
@@ -453,7 +575,10 @@ export async function ingestEvent(opts: {
|
|
|
453
575
|
survivorKey: resolvedKey,
|
|
454
576
|
loserKeys: mergedKeys,
|
|
455
577
|
reason: merged ? "collide_merge" : "key_flip",
|
|
456
|
-
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,
|
|
457
582
|
logger,
|
|
458
583
|
});
|
|
459
584
|
}
|
|
@@ -461,7 +586,7 @@ export async function ingestEvent(opts: {
|
|
|
461
586
|
logResidualTwins({
|
|
462
587
|
survivorKey: resolvedKey,
|
|
463
588
|
identifiedLoserKeys: mergedIdentifiedKeys,
|
|
464
|
-
contactId,
|
|
589
|
+
contactId: contactId ?? undefined,
|
|
465
590
|
logger,
|
|
466
591
|
});
|
|
467
592
|
}
|
|
@@ -521,7 +646,23 @@ export async function ingestEvent(opts: {
|
|
|
521
646
|
// path has NO idempotency key, so a thrown error + ingest retry would
|
|
522
647
|
// DOUBLE-insert the event) — a group-write hiccup must never fail an
|
|
523
648
|
// already-stored event.
|
|
524
|
-
|
|
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
|
+
) {
|
|
525
666
|
try {
|
|
526
667
|
await associateGroups({ db, contactId, groups: event.groups });
|
|
527
668
|
} catch (err) {
|
|
@@ -562,7 +703,13 @@ export async function ingestEvent(opts: {
|
|
|
562
703
|
// enrolling on this event can re-emit for the SAME subject by row id
|
|
563
704
|
// (folds, never mints a twin). Additive/optional — consumers ignoring it
|
|
564
705
|
// are unaffected.
|
|
565
|
-
|
|
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 } : {}),
|
|
566
713
|
// The event's group association map (groupType → groupKey), so a
|
|
567
714
|
// group-scoped wait can match on membership straight off the wire.
|
|
568
715
|
// Always present ({} when the event carries none) so downstream CEL
|
|
@@ -647,7 +794,16 @@ export async function ingestEvent(opts: {
|
|
|
647
794
|
|
|
648
795
|
// (5c) Conversion-point evaluation (plan §5.1) — the unique
|
|
649
796
|
// (definition, event) index makes any replay a no-op.
|
|
650
|
-
|
|
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) {
|
|
651
807
|
try {
|
|
652
808
|
const fired = await evaluateConversionsAtIngest({
|
|
653
809
|
db,
|
|
@@ -716,7 +872,11 @@ export async function ingestEvent(opts: {
|
|
|
716
872
|
// money events it mints (`deal.quoted`/`deal.sold`) recurse through
|
|
717
873
|
// ingestEvent, bounded at define time: `deal.`/`funnel.`/`crm.` events
|
|
718
874
|
// cannot be stage triggers.
|
|
719
|
-
|
|
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) {
|
|
720
880
|
const funnelRegistry = getCrmSyncConfig()?.funnels;
|
|
721
881
|
if (funnelRegistry) {
|
|
722
882
|
try {
|
|
@@ -778,15 +938,32 @@ export async function ingestEvent(opts: {
|
|
|
778
938
|
hatchet,
|
|
779
939
|
logger,
|
|
780
940
|
userId: resolvedKey,
|
|
781
|
-
//
|
|
782
|
-
//
|
|
783
|
-
//
|
|
784
|
-
//
|
|
785
|
-
|
|
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 }),
|
|
786
960
|
userEmail: event.userEmail || null,
|
|
787
961
|
event: event.event,
|
|
788
962
|
eventProperties: event.eventProperties,
|
|
789
963
|
contactProperties: event.contactProperties ?? {},
|
|
964
|
+
...(event.touchProperties
|
|
965
|
+
? { touchProperties: event.touchProperties }
|
|
966
|
+
: {}),
|
|
790
967
|
});
|
|
791
968
|
} catch (err) {
|
|
792
969
|
logger.warn("Bucket membership check failed", {
|
package/src/lib/outbound.ts
CHANGED
|
@@ -113,8 +113,8 @@ export interface OutboundPayloads {
|
|
|
113
113
|
* ONLY on a genuine `status: "refined"` — never on `cached`, `not_found` or
|
|
114
114
|
* `skipped`, because a cache hit is a spend decision, not a change.
|
|
115
115
|
*
|
|
116
|
-
* `traits` carries the
|
|
117
|
-
* "
|
|
116
|
+
* `traits` carries the canonical trait KEY NAMES only — `["title",
|
|
117
|
+
* "company_domain"]` — never their values. That is deliberate: the
|
|
118
118
|
* payload says WHAT CHANGED, and a subscriber that wants the values reads
|
|
119
119
|
* the contact (`GET /v1/contacts`). So vendor-licensed person data never
|
|
120
120
|
* leaves the building inside a webhook body, and the envelope stays a fixed
|
|
@@ -132,7 +132,7 @@ export interface OutboundPayloads {
|
|
|
132
132
|
provider: string;
|
|
133
133
|
/** Mapped trait key NAMES, sorted. Values are deliberately absent. */
|
|
134
134
|
traits: string[];
|
|
135
|
-
/** ISO — the lookup instant (the same value as `
|
|
135
|
+
/** ISO — the lookup instant (the same value as `enrichment.at`). */
|
|
136
136
|
at: string;
|
|
137
137
|
};
|
|
138
138
|
"email.sent": {
|