@hogsend/engine 0.56.0 → 0.58.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.
@@ -5,10 +5,13 @@ import {
5
5
  groups,
6
6
  } from "@hogsend/db";
7
7
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
8
- import { and, asc, count, desc, eq, isNull, sql } from "drizzle-orm";
8
+ import { and, asc, count, desc, eq, isNull, not, sql } from "drizzle-orm";
9
9
  import type { AppEnv } from "../../app.js";
10
10
  import {
11
+ ALL_IDENTITY_KINDS,
11
12
  contactSearchFilter,
13
+ deleteIdentityAliasesForContact,
14
+ identifiedContactFilter,
12
15
  resolveContact,
13
16
  resolveOrCreateContact,
14
17
  serializeContact as serializeContactRow,
@@ -78,12 +81,33 @@ const listRoute = createRoute({
78
81
  path: "/",
79
82
  tags: ["Admin"],
80
83
  summary: "List contacts",
84
+ description:
85
+ "Paginated contact list. `identity` narrows the list by whether the " +
86
+ "contact has EVER identified — i.e. holds an `externalId`, `email`, " +
87
+ "`discordId` or `phone` (`anonymousId` alone does not count). It " +
88
+ "defaults to `all`, so existing callers (`hogsend contacts list`, the " +
89
+ "Studio contact picker) are unaffected; only Studio's contacts screen " +
90
+ "opts in to `identified`. `identified` and `anonymous` are exact " +
91
+ "complements under the same other filters, and `total` reflects the " +
92
+ "filter.",
81
93
  request: {
82
94
  query: z
83
95
  .object({
84
96
  limit: z.coerce.number().min(1).max(100).default(50),
85
97
  offset: z.coerce.number().min(0).default(0),
86
98
  search: z.string().optional(),
99
+ /**
100
+ * Display filter (PRD 01) over "has this person ever identified?".
101
+ *
102
+ * The default is `all` ON PURPOSE and must stay that way: two
103
+ * consumers other than Studio's contacts list call this route and
104
+ * neither should silently change — the published `hogsend contacts
105
+ * list` CLI (output is scripted against) and Studio's contact
106
+ * picker (an anonymous contact is a legitimate pick when a journey
107
+ * or test is aimed at an anon key). Flipping this default is an
108
+ * API behaviour change, not a display tweak.
109
+ */
110
+ identity: z.enum(["all", "identified", "anonymous"]).default("all"),
87
111
  // Long-tail value filters (plan §4b.3): the "find my value customers"
88
112
  // query surface.
89
113
  minRevenue: z.coerce.number().optional(),
@@ -293,6 +317,7 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
293
317
  limit,
294
318
  offset,
295
319
  search,
320
+ identity,
296
321
  minRevenue,
297
322
  dealStage,
298
323
  orderBy,
@@ -378,8 +403,20 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
378
403
  )`
379
404
  : undefined;
380
405
 
406
+ // PRD 01 — one conjunct, one predicate (`identifiedContactFilter`), so
407
+ // `identified` and `anonymous` stay exact complements. It rides the SAME
408
+ // `where` as every other filter below, which is what keeps the page query
409
+ // and the `count()` in lockstep.
410
+ const identityFilter =
411
+ identity === "identified"
412
+ ? identifiedContactFilter()
413
+ : identity === "anonymous"
414
+ ? not(identifiedContactFilter())
415
+ : undefined;
416
+
381
417
  const where = and(
382
418
  isNull(contacts.deletedAt),
419
+ ...(identityFilter ? [identityFilter] : []),
383
420
  ...(searchFilter ? [searchFilter] : []),
384
421
  ...(revenueFilter ? [revenueFilter] : []),
385
422
  ...(dealStageFilter ? [dealStageFilter] : []),
@@ -488,6 +525,14 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
488
525
  userId: body.externalId,
489
526
  email: body.email,
490
527
  contactProperties: body.properties,
528
+ // PRD 06 T4 (L5 row 14): an admin create asserts identity — the body
529
+ // carries `externalId`/`email` ONLY, so the narrow `trustedKinds` is the
530
+ // honest statement; create-on-miss, no clamp. Enforced by T5.
531
+ policy: {
532
+ create: "on-miss",
533
+ allowMerge: "any",
534
+ trustedKinds: ["external", "email"],
535
+ },
491
536
  });
492
537
 
493
538
  const created = await resolveContact({ db, id });
@@ -540,6 +585,15 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
540
585
  email: body.email ?? current.email ?? undefined,
541
586
  anonymousId: current.anonymousId ?? undefined,
542
587
  contactProperties: body.properties,
588
+ // PRD 06 T4 (L5 row 15): an admin update re-supplies the row's OWN
589
+ // identity keys (externalId/anonymousId/email) to ride the
590
+ // fill-in-link path — an admin may assert any kind, so the full grant
591
+ // is the honest statement; create-on-miss, no clamp. Enforced by T5.
592
+ policy: {
593
+ create: "on-miss",
594
+ allowMerge: "any",
595
+ trustedKinds: ALL_IDENTITY_KINDS,
596
+ },
543
597
  });
544
598
  } else {
545
599
  // Degenerate contact with no identity keys (resolver requires >=1 key):
@@ -591,10 +645,16 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
591
645
  return c.json({ error: "Contact not found" }, 404);
592
646
  }
593
647
 
594
- await db
595
- .update(contacts)
596
- .set({ deletedAt: new Date(), updatedAt: new Date() })
597
- .where(eq(contacts.id, contact.id));
648
+ // Soft-delete + erasure hook in ONE transaction (PRD 02 T1): every
649
+ // contact_aliases row keyed to the erased contact is that person's own
650
+ // identity data, whatever `reason`/`from_contact_id` it carries.
651
+ await db.transaction(async (tx) => {
652
+ await tx
653
+ .update(contacts)
654
+ .set({ deletedAt: new Date(), updatedAt: new Date() })
655
+ .where(eq(contacts.id, contact.id));
656
+ await deleteIdentityAliasesForContact(tx, contact.id);
657
+ });
598
658
 
599
659
  return c.json({ deleted: true }, 200);
600
660
  });
@@ -0,0 +1,197 @@
1
+ import { importJobs } from "@hogsend/db";
2
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
+ import { eq } from "drizzle-orm";
4
+ import type { AppEnv } from "../../app.js";
5
+ import { errorSchema } from "../../lib/schemas.js";
6
+ import {
7
+ IDENTITY_ALIAS_BACKFILL_FORMAT,
8
+ identityAliasBackfillTask,
9
+ identityAliasParity,
10
+ } from "../../workflows/identity-alias-backfill.js";
11
+
12
+ // PRD 02 T3/T4 — the identity-table admin surface: trigger/poll the alias
13
+ // backfill, and the read-only parity verifier that gates trusting alias-first
14
+ // resolution. Mirrors the `/contacts/import` job-trigger + status-poll pattern
15
+ // in `bulk.ts`. Behind `requireAdmin` like the rest of `/v1/admin`.
16
+
17
+ const triggerRoute = createRoute({
18
+ method: "post",
19
+ path: "/identity/alias-backfill",
20
+ tags: ["Admin — Identity"],
21
+ summary: "Run the contact_aliases backfill",
22
+ description:
23
+ "Fills contact_aliases with a row per identity key of every live " +
24
+ "contact (chunked, idempotent, resumable — safe to re-run). The worker " +
25
+ "also enqueues this once at boot; this route forces a re-run, e.g. after " +
26
+ "a failed job or to re-verify. `dryRun: true` classifies and counts " +
27
+ "without writing.",
28
+ request: {
29
+ body: {
30
+ content: {
31
+ "application/json": {
32
+ schema: z.object({ dryRun: z.boolean().default(false) }),
33
+ },
34
+ },
35
+ required: false,
36
+ },
37
+ },
38
+ responses: {
39
+ 202: {
40
+ content: {
41
+ "application/json": {
42
+ schema: z.object({ jobId: z.string(), status: z.string() }),
43
+ },
44
+ },
45
+ description: "Backfill job queued",
46
+ },
47
+ },
48
+ });
49
+
50
+ const statusRoute = createRoute({
51
+ method: "get",
52
+ path: "/identity/alias-backfill/{jobId}",
53
+ tags: ["Admin — Identity"],
54
+ summary: "Get alias-backfill job status",
55
+ description:
56
+ "processedRows = live contacts scanned; failedRows = pairs whose " +
57
+ "(kind, value) is claimed by a DIFFERENT contact (the divergence metric, " +
58
+ "not an error count). The full breakdown is in the worker log line.",
59
+ request: {
60
+ params: z.object({ jobId: z.string().uuid() }),
61
+ },
62
+ responses: {
63
+ 200: {
64
+ content: {
65
+ "application/json": {
66
+ schema: z.object({
67
+ id: z.string(),
68
+ status: z.string(),
69
+ totalRows: z.number().nullable(),
70
+ processedRows: z.number(),
71
+ failedRows: z.number(),
72
+ errors: z
73
+ .array(z.object({ row: z.number(), error: z.string() }))
74
+ .nullable(),
75
+ createdAt: z.string(),
76
+ updatedAt: z.string(),
77
+ }),
78
+ },
79
+ },
80
+ description: "Backfill job details",
81
+ },
82
+ 404: {
83
+ content: { "application/json": { schema: errorSchema } },
84
+ description: "Job not found",
85
+ },
86
+ },
87
+ });
88
+
89
+ const parityRoute = createRoute({
90
+ method: "get",
91
+ path: "/identity/alias-parity",
92
+ tags: ["Admin — Identity"],
93
+ summary: "Alias vs column resolution parity, per kind",
94
+ description:
95
+ "Read-only. `diverged` MUST be 0 before trusting alias-first " +
96
+ "resolution — a non-zero value is a data bug to fix on its own. " +
97
+ "`aliasDead` is expected (handled by the live-target rule); `aliasOnly` " +
98
+ "is the merge/promote population and, after PRD 03, the point of the " +
99
+ "table.",
100
+ responses: {
101
+ 200: {
102
+ content: {
103
+ "application/json": {
104
+ schema: z.object({
105
+ kinds: z.array(
106
+ z.object({
107
+ kind: z.string(),
108
+ diverged: z.number(),
109
+ aliasDead: z.number(),
110
+ aliasOnly: z.number(),
111
+ }),
112
+ ),
113
+ }),
114
+ },
115
+ },
116
+ description: "Parity counts per alias kind",
117
+ },
118
+ },
119
+ });
120
+
121
+ export const identityRouter = new OpenAPIHono<AppEnv>()
122
+ .openapi(triggerRoute, async (c) => {
123
+ const { db, logger } = c.get("container");
124
+ const body = c.req.valid("json") ?? { dryRun: false };
125
+
126
+ const [job] = await db
127
+ .insert(importJobs)
128
+ .values({
129
+ fileName: IDENTITY_ALIAS_BACKFILL_FORMAT,
130
+ format: IDENTITY_ALIAS_BACKFILL_FORMAT,
131
+ status: "pending",
132
+ })
133
+ .returning({ id: importJobs.id });
134
+ if (!job) throw new Error("Failed to create backfill job");
135
+
136
+ // Fire-and-forget 202 + status poll (the bulk.ts contract). A failed
137
+ // enqueue marks the durable row `failed` so pollers get a terminal state.
138
+ void identityAliasBackfillTask
139
+ .runNoWait({ jobId: job.id, dryRun: body.dryRun })
140
+ .catch(async (error: unknown) => {
141
+ const message = error instanceof Error ? error.message : String(error);
142
+ logger.warn("identity/alias-backfill: task enqueue failed", {
143
+ jobId: job.id,
144
+ error: message,
145
+ });
146
+ try {
147
+ await db
148
+ .update(importJobs)
149
+ .set({
150
+ status: "failed",
151
+ errors: [{ row: 0, error: `Task enqueue failed: ${message}` }],
152
+ updatedAt: new Date(),
153
+ })
154
+ .where(eq(importJobs.id, job.id));
155
+ } catch (dbError: unknown) {
156
+ logger.warn("identity/alias-backfill: could not mark job failed", {
157
+ jobId: job.id,
158
+ error: dbError instanceof Error ? dbError.message : String(dbError),
159
+ });
160
+ }
161
+ });
162
+
163
+ return c.json({ jobId: job.id, status: "pending" }, 202);
164
+ })
165
+ .openapi(statusRoute, async (c) => {
166
+ const { db } = c.get("container");
167
+ const { jobId } = c.req.valid("param");
168
+
169
+ const rows = await db
170
+ .select()
171
+ .from(importJobs)
172
+ .where(eq(importJobs.id, jobId))
173
+ .limit(1);
174
+ const job = rows[0];
175
+ if (!job || job.format !== IDENTITY_ALIAS_BACKFILL_FORMAT) {
176
+ return c.json({ error: "Backfill job not found" }, 404);
177
+ }
178
+
179
+ return c.json(
180
+ {
181
+ id: job.id,
182
+ status: job.status,
183
+ totalRows: job.totalRows,
184
+ processedRows: job.processedRows,
185
+ failedRows: job.failedRows,
186
+ errors: job.errors as Array<{ row: number; error: string }> | null,
187
+ createdAt: job.createdAt.toISOString(),
188
+ updatedAt: job.updatedAt.toISOString(),
189
+ },
190
+ 200,
191
+ );
192
+ })
193
+ .openapi(parityRoute, async (c) => {
194
+ const { db } = c.get("container");
195
+ const kinds = await identityAliasParity(db);
196
+ return c.json({ kinds }, 200);
197
+ });
@@ -24,6 +24,7 @@ import { eventsRouter } from "./events.js";
24
24
  import { adminFlagsRouter } from "./flags.js";
25
25
  import { adminFunnelsRouter } from "./funnels.js";
26
26
  import { groupsRouter } from "./groups.js";
27
+ import { identityRouter } from "./identity.js";
27
28
  import { impactOverviewRouter } from "./impact.js";
28
29
  import { journeyImpactRouter } from "./journey-impact.js";
29
30
  import { journeyLogsRouter } from "./journey-logs.js";
@@ -48,6 +49,7 @@ adminRouter.use("*", requireAdmin);
48
49
  adminRouter.use("*", rateLimit);
49
50
  adminRouter.use("*", auditMiddleware);
50
51
  adminRouter.route("/", bulkRouter);
52
+ adminRouter.route("/", identityRouter);
51
53
  adminRouter.route("/contacts", contactsRouter);
52
54
  adminRouter.route("/contacts", preferencesRouter);
53
55
  adminRouter.route("/contacts", timelineRouter);
@@ -1,6 +1,7 @@
1
1
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
2
  import type { AppEnv } from "../../app.js";
3
3
  import {
4
+ ALL_IDENTITY_KINDS,
4
5
  findContacts,
5
6
  PublishableAnonymousMergeError,
6
7
  resolveContact,
@@ -45,8 +46,25 @@ const upsertRoute = createRoute({
45
46
  email: z.string().email().optional(),
46
47
  userId: z.string().min(1).optional(),
47
48
  // §4: caller's analytics anon id — the resolver's 2nd-precedence
48
- // key. An EXTRA, never a third identity arm: `requireIdentity`
49
- // still requires email or userId below.
49
+ // key, normally an EXTRA alongside email/userId rather than an
50
+ // identity arm of its own.
51
+ //
52
+ // NOT a guarantee, on the publishable path. The handler gates with
53
+ // `gatePublishableIdentity`, NOT `requireIdentity`, and that gate
54
+ // returns early for a pk_ caller who claims nothing
55
+ // (`routes/_shared.ts` — "No claimed identity → anon-only,
56
+ // allowed"). The create arm of `resolveContactShared` carries no
57
+ // `restrictToAnonymous` guard either — that flag bites only
58
+ // fill-in-link and collide-merge. So a hand-rolled `pk_` fetch
59
+ // sending ONLY `anonymousId` still MINTS an anonymous-only contact.
60
+ //
61
+ // Known and deliberately deferred (ghost-contacts BACKLOG): refusing
62
+ // here would force `id: z.string().nullable()` on the published
63
+ // response schema plus a `@hogsend/client` type widening. No
64
+ // first-party SDK emits that shape — `@hogsend/js` `identify()`
65
+ // always sends a `userId` — so the residual is a hand-rolled
66
+ // request, not an SDK path. Do not "fix" this comment back into a
67
+ // guarantee the code does not provide.
50
68
  anonymousId: z.string().min(1).max(200).optional(),
51
69
  properties: z.record(z.string(), z.unknown()).optional(),
52
70
  lists: z.record(z.string(), z.boolean()).optional(),
@@ -164,11 +182,36 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
164
182
  // §4: 2nd-precedence resolver key (zero-merge stitch).
165
183
  anonymousId: body.anonymousId,
166
184
  contactProperties: body.properties,
167
- // §Phase 1 GAP-1: a publishable (pk_) browser upsert is anon-clamped —
168
- // its browser-readable `anonymousId` may NOT attach to / merge / poison
169
- // an already-identified victim contact. Secret-key upserts are never
170
- // clamped.
171
- restrictToAnonymous: c.get("publishable") === true,
185
+ // PRD 06 T3 (L5 rows 4-5): trust is DECLARED by this caller, not
186
+ // re-inferred inside the resolver.
187
+ // - `create` — an upsert is an identity assertion, never observation:
188
+ // this route NEVER refuses to create, on either arm.
189
+ // - `allowMerge` — §Phase 1 GAP-1: a publishable (pk_) browser upsert
190
+ // is anon-clamped — its browser-readable `anonymousId` may NOT
191
+ // attach to / merge / poison an already-identified victim contact.
192
+ // Kept "anonymous-only" even when a verified token proves a
193
+ // `userId`: the clamp is inert there by DERIVATION (a non-anon key
194
+ // is present), never by hard-coding "any". Secret-key upserts are
195
+ // never clamped.
196
+ // - `trustedKinds` — from the gate's own evidence: a publishable
197
+ // `userId` reaching this call is token-proven
198
+ // (`gatePublishableIdentity` 403'd every other identity-claiming
199
+ // shape), so pk_ = `anonymous` (+`external` with that proof);
200
+ // secret = all four. Declared now, enforced by T5.
201
+ policy:
202
+ c.get("publishable") === true
203
+ ? {
204
+ create: "on-miss",
205
+ allowMerge: "anonymous-only",
206
+ trustedKinds: body.userId
207
+ ? ["anonymous", "external"]
208
+ : ["anonymous"],
209
+ }
210
+ : {
211
+ create: "on-miss",
212
+ allowMerge: "any",
213
+ trustedKinds: ALL_IDENTITY_KINDS,
214
+ },
172
215
  });
173
216
  } catch (err) {
174
217
  if (err instanceof PublishableAnonymousMergeError) {
@@ -1,6 +1,9 @@
1
1
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
2
  import type { AppEnv } from "../../app.js";
3
- import { PublishableAnonymousMergeError } from "../../lib/contacts.js";
3
+ import {
4
+ ALL_IDENTITY_KINDS,
5
+ PublishableAnonymousMergeError,
6
+ } from "../../lib/contacts.js";
4
7
  import { ingestEvent } from "../../lib/ingestion.js";
5
8
  import { applyListMembership } from "../../lib/preferences.js";
6
9
  import { errorSchema } from "../../lib/schemas.js";
@@ -115,6 +118,61 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
115
118
  const headerKey = c.req.header("idempotency-key");
116
119
  const idempotencyKey = headerKey ?? body.idempotencyKey;
117
120
 
121
+ // D1 — a contact is minted by IDENTITY, not by observation. A publishable
122
+ // (pk_) browser write that asserts nothing is pure traffic: it still stores
123
+ // in `user_events`, still routes to journeys, still checks exits (D2), but
124
+ // it no longer mints a `contacts` row for every unidentified visitor.
125
+ //
126
+ // Every conjunct is load-bearing:
127
+ // - `publishable` — the caller CLASS is the whole guard (D1 is
128
+ // caller-keyed, not endpoint-keyed). A secret-key server caller asserts
129
+ // intent and is never refused.
130
+ // - `!body.userId` — a userId on this path is already token-proven by
131
+ // `gatePublishableIdentity` above, i.e. a server-authorized identity
132
+ // assertion. It keeps creating.
133
+ // - `!body.email` — an asserted email is an identity assertion too. It is
134
+ // also a D8 PRECONDITION: `resolveContactNoCreate` THROWS unless the
135
+ // highest-precedence key is `userId`/`anonymousId`, and `email`
136
+ // outranks `anonymousId` in the resolver. (The gate 403s a publishable
137
+ // email today, so this conjunct is defense in depth against a future
138
+ // email arm silently becoming a 500.)
139
+ // - `body.value === undefined` — D9's escape hatch. `conversions`,
140
+ // `funnel_progress` and `deals` all hold `.notNull()` FKs to
141
+ // `contacts.id` and `packages/db` is out of boundary, so a refused
142
+ // ingest can perform no conversion, funnel or attribution work at all. A
143
+ // money-bearing browser event is therefore treated as an identity
144
+ // assertion so e-commerce revenue conversions and attribution credits
145
+ // keep firing.
146
+ // - `body.groups === undefined` — D10, the same hatch for the same reason.
147
+ // `group_memberships.contact_id` is a fourth `.notNull()` FK to
148
+ // `contacts.id`, so a refused ingest writes NEITHER the `groups` row
149
+ // (minted by `associateGroups` → `resolveGroupId`) NOR the membership.
150
+ // But browser group ASSOCIATION is a documented first-class capability —
151
+ // root `CLAUDE.md`: "Publishable/browser keys may ONLY associate —
152
+ // attach a `groups` map to an event via `hogsend.group()` → /v1/events"
153
+ // — and `@hogsend/js` attaches the map to every capture regardless of
154
+ // identification, so a pre-login `hogsend.group()` sends exactly this
155
+ // shape. A visitor calling `hogsend.group()` is asserting an association
156
+ // INTENT, which is more than pure observation, so it keeps creating.
157
+ // Association-only still: the property writes a group row can receive
158
+ // remain secret-key-only, unchanged by this hatch.
159
+ // - `body.anonymousId` — the other half of D8: refusal is legal only where
160
+ // the key is STABLE. With no key at all the resolve throws either way
161
+ // (today: "requires at least one of…"), so restricting the guard to the
162
+ // shape that has a real refusal key changes no outcome and keeps the
163
+ // thrown message pointing at the actual defect.
164
+ //
165
+ // NOT collapsed into the policy's `allowMerge` clamp even though the
166
+ // conditions overlap here: that leg guards MERGE/poison, this one guards
167
+ // CREATION.
168
+ const observationOnly =
169
+ c.get("publishable") === true &&
170
+ !body.userId &&
171
+ !body.email &&
172
+ body.value === undefined &&
173
+ body.groups === undefined &&
174
+ !!body.anonymousId;
175
+
118
176
  let result: Awaited<ReturnType<typeof ingestEvent>>;
119
177
  try {
120
178
  result = await ingestEvent({
@@ -125,11 +183,41 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
125
183
  // §5.3: thread the active analytics provider so a collide-MERGE /
126
184
  // key-flip fires the provider-neutral `mergeIdentities` stitch.
127
185
  analytics,
128
- // §Phase 1 GAP-1: a publishable (pk_) browser write is anon-clamped —
129
- // its browser-readable `anonymousId` may NOT attach to / merge / poison
130
- // an already-identified victim contact. Secret-key ingest is never
131
- // clamped.
132
- restrictToAnonymous: c.get("publishable") === true,
186
+ // PRD 06 T3 (L5 rows 1-3): trust is DECLARED by this caller, not
187
+ // re-inferred inside the resolver.
188
+ // - `create` — the D1 creation guard (see `observationOnly` above): a
189
+ // token-less pk_ observation refuses to mint; everything else keeps
190
+ // creating. Deliberately a SEPARATE leg from `allowMerge`:
191
+ // merge-clamping and creation-refusal are different questions that
192
+ // only happen to agree on part of this route's input.
193
+ // - `allowMerge` — §Phase 1 GAP-1: a publishable (pk_) browser write
194
+ // is anon-clamped — its browser-readable `anonymousId` may NOT
195
+ // attach to / merge / poison an already-identified victim contact.
196
+ // Declared "anonymous-only" even for a token-proven `userId` (row
197
+ // 2): the clamp is inert there because the DERIVATION sees a
198
+ // non-anon key — hard-coding the conclusion ("any") would silently
199
+ // break on the next key-precedence change. Secret-key ingest is
200
+ // never clamped.
201
+ // - `trustedKinds` — the evidence `gatePublishableIdentity` already
202
+ // computed: a publishable `userId` reaching this call IS
203
+ // token-proven (the gate 403'd every other identity-claiming shape,
204
+ // incl. any pk_ email), so a pk_ caller may assert `anonymous`
205
+ // (+`external` with that proof); a secret caller all four. Declared
206
+ // now, enforced by T5.
207
+ policy:
208
+ c.get("publishable") === true
209
+ ? {
210
+ create: observationOnly ? "refuse-on-miss" : "on-miss",
211
+ allowMerge: "anonymous-only",
212
+ trustedKinds: body.userId
213
+ ? ["anonymous", "external"]
214
+ : ["anonymous"],
215
+ }
216
+ : {
217
+ create: "on-miss",
218
+ allowMerge: "any",
219
+ trustedKinds: ALL_IDENTITY_KINDS,
220
+ },
133
221
  event: {
134
222
  event: body.name,
135
223
  userId: body.userId,
@@ -3,6 +3,7 @@ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
3
  import { and, count, desc, eq, gt, inArray, lt, sql } from "drizzle-orm";
4
4
  import { streamSSE } from "hono/streaming";
5
5
  import type { AppEnv } from "../../app.js";
6
+ import { ALL_IDENTITY_KINDS } from "../../lib/contacts.js";
6
7
  import { ingestEvent } from "../../lib/ingestion.js";
7
8
  import { getRedis } from "../../lib/redis.js";
8
9
  import { errorSchema } from "../../lib/schemas.js";
@@ -50,12 +51,34 @@ function emitMarkEvents(
50
51
  feedId: string;
51
52
  recipientKey: string;
52
53
  contactId?: string;
54
+ allowCreate?: boolean;
53
55
  },
54
56
  ): Promise<unknown> {
55
57
  return Promise.allSettled(
56
58
  args.ids.map((r) =>
57
59
  ingestEvent({
58
60
  ...deps,
61
+ // PRD 06 T3 (L5 rows 8-9) / L4: this is an ENGINE-INTERNAL re-emit.
62
+ // `trustedKinds` describes the keys as supplied by the caller OF THE
63
+ // RESOLVER — here the engine itself, whose subject (`recipientKey` +
64
+ // the `contactId` pin below) was derived server-side by
65
+ // `resolveFeedRecipient` — NOT by whatever authenticated the
66
+ // originating HTTP request. So the policy declares full server trust
67
+ // (`allowMerge: "any"`, all four kinds; deriving them from the pk_
68
+ // request would break every anon bell mark/clear once T5 arms) and
69
+ // inherits exactly ONE thing from that request: the D1 `create`
70
+ // refusal for an UNSEEN anonymous visitor. `resolveFeedRecipient` sets
71
+ // `allowCreate: false` only on the anon arm where BOTH the column
72
+ // probe and the alias probe missed — and there `recipientKey` IS the
73
+ // raw anon id, so D8 holds and the refused re-ingest keys
74
+ // `user_events` exactly as a creating one would. The `contactId` pin
75
+ // is a SUBJECT declaration, orthogonal to this policy — never folded
76
+ // into it.
77
+ policy: {
78
+ create: args.allowCreate === false ? "refuse-on-miss" : "on-miss",
79
+ allowMerge: "any",
80
+ trustedKinds: ALL_IDENTITY_KINDS,
81
+ },
59
82
  event: {
60
83
  event: args.eventType,
61
84
  // recipientKey IS the canonical contact key — pass it as userId so
@@ -419,6 +442,7 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
419
442
  feedId,
420
443
  recipientKey: rec.recipientKey,
421
444
  contactId: rec.contactId,
445
+ allowCreate: rec.allowCreate,
422
446
  },
423
447
  );
424
448
 
@@ -452,6 +476,17 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
452
476
  hatchet,
453
477
  logger,
454
478
  analytics,
479
+ // PRD 06 T3 / L4 (see emitMarkEvents): engine-internal re-emit — full
480
+ // server trust, inheriting ONLY the D1 `create` refusal from the
481
+ // recipient verdict. This emit fires UNCONDITIONALLY — even when
482
+ // `updated` is empty — so a first-time visitor clearing a bell that
483
+ // never held an item drives one re-ingest, and that alone used to
484
+ // mint the ghost that locks them out.
485
+ policy: {
486
+ create: rec.allowCreate === false ? "refuse-on-miss" : "on-miss",
487
+ allowMerge: "any",
488
+ trustedKinds: ALL_IDENTITY_KINDS,
489
+ },
455
490
  event: {
456
491
  event: "inapp.feed_cleared",
457
492
  userId: rec.recipientKey,
@@ -472,6 +507,7 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
472
507
  feedId,
473
508
  recipientKey: rec.recipientKey,
474
509
  contactId: rec.contactId,
510
+ allowCreate: rec.allowCreate,
475
511
  },
476
512
  );
477
513
  }