@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.
@@ -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 { 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 {
@@ -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: Awaited<ReturnType<typeof resolveOrCreateContact>>;
416
+ let resolved: ResolvedIdentity;
324
417
  try {
325
- resolved = await resolveOrCreateContact({
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
- 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
+ ) {
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
- 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 } : {}),
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
- 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) {
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
- 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) {
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
- // The resolved row id rides along as the ENGINE-INTERNAL provenance pin
790
- // for the bucket transition re-ingests: `resolvedKey` may be the
791
- // contact's `anonymous_id`, which a bare re-ingest would treat as an
792
- // external key and mint a phantom twin for (issue #608).
793
- 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 }),
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): `ingestEvent`→`resolveOrCreateContact` THROWS on
239
- * a zero-key event, so a broadcast/public link (`distinctId == null`) returns
240
- * `undefined` WITHOUT calling ingest. The click route ALSO suppresses
241
- * bot/prefetch hits upstream (`isBotOrPrefetch`), so an unfurl bot never reaches
242
- * here. All six payload keys are scalars (or null) so they survive ingest and
243
- * reach `trigger.where` + `waitForEvent.properties`.
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
  }