@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.
Files changed (37) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +5 -10
  3. package/src/buckets/check-membership.ts +91 -6
  4. package/src/index.ts +31 -1
  5. package/src/journeys/execute-journey-run.ts +56 -1
  6. package/src/journeys/journey-context.ts +59 -0
  7. package/src/lib/bucket-emit.test.ts +83 -2
  8. package/src/lib/bucket-emit.ts +16 -0
  9. package/src/lib/contacts.ts +1031 -141
  10. package/src/lib/crm-ingest.ts +9 -0
  11. package/src/lib/enrichment-ledger.ts +1 -1
  12. package/src/lib/feed.ts +64 -3
  13. package/src/lib/identity-service.ts +15 -2
  14. package/src/lib/ingestion.ts +191 -14
  15. package/src/lib/outbound.ts +3 -3
  16. package/src/lib/refine-chain.test.ts +83 -25
  17. package/src/lib/refine-chain.ts +124 -23
  18. package/src/lib/refine-traits.test.ts +74 -41
  19. package/src/lib/refine-traits.ts +107 -52
  20. package/src/lib/refine.ts +28 -27
  21. package/src/lib/tracking-events.ts +33 -6
  22. package/src/routes/admin/agent.ts +26 -0
  23. package/src/routes/admin/contacts.ts +65 -5
  24. package/src/routes/admin/identity.ts +197 -0
  25. package/src/routes/admin/index.ts +2 -0
  26. package/src/routes/contacts/index.ts +50 -7
  27. package/src/routes/events/index.ts +94 -6
  28. package/src/routes/feed/index.ts +36 -0
  29. package/src/routes/feed/recipient.ts +44 -2
  30. package/src/routes/lists/index.ts +21 -0
  31. package/src/routes/tracking/arrive.ts +42 -3
  32. package/src/worker.ts +18 -0
  33. package/src/workflows/bucket-backfill.ts +1 -1
  34. package/src/workflows/bucket-reconcile.ts +129 -4
  35. package/src/workflows/identity-alias-backfill.ts +448 -0
  36. package/src/workflows/import-contacts.ts +10 -0
  37. package/src/workflows/send-campaign.ts +31 -13
@@ -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 `refined_*` patch the paid answer produced. */
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 { resolveOrCreateContact, resolveRecipient } from "./contacts.js";
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
- const { id: contactId, resolvedKey } = await resolveOrCreateContact({
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
- const result = await resolveOrCreateContact({ db, ...args });
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,
@@ -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: Awaited<ReturnType<typeof resolveOrCreateContact>>;
416
+ let resolved: ResolvedIdentity;
316
417
  try {
317
- resolved = await resolveOrCreateContact({
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
- if (event.groups && Object.keys(event.groups).length > 0) {
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
- contactId,
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
- if (insertedRow && hookEvent) {
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
- if (insertedRow && hookEvent) {
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
- // The resolved row id rides along as the ENGINE-INTERNAL provenance pin
782
- // for the bucket transition re-ingests: `resolvedKey` may be the
783
- // contact's `anonymous_id`, which a bare re-ingest would treat as an
784
- // external key and mint a phantom twin for (issue #608).
785
- contactId,
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", {
@@ -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 mapped trait KEY NAMES only — `["refined_title",
117
- * "refined_company_domain"]` — never their values. That is deliberate: the
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 `refined_at`). */
135
+ /** ISO — the lookup instant (the same value as `enrichment.at`). */
136
136
  at: string;
137
137
  };
138
138
  "email.sent": {