@hogsend/engine 0.60.0 → 0.62.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.60.0",
3
+ "version": "0.62.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -53,18 +53,18 @@
53
53
  "svix": "^1.95.1",
54
54
  "winston": "^3.19.0",
55
55
  "zod": "^4.4.3",
56
- "@hogsend/attribution": "^0.60.0",
57
- "@hogsend/core": "^0.60.0",
58
- "@hogsend/db": "^0.60.0",
59
- "@hogsend/email": "^0.60.0",
60
- "@hogsend/plugin-posthog": "^0.60.0",
61
- "@hogsend/plugin-resend": "^0.60.0",
62
- "@hogsend/sms": "^0.60.0"
56
+ "@hogsend/attribution": "^0.62.0",
57
+ "@hogsend/core": "^0.62.0",
58
+ "@hogsend/db": "^0.62.0",
59
+ "@hogsend/email": "^0.62.0",
60
+ "@hogsend/plugin-posthog": "^0.62.0",
61
+ "@hogsend/plugin-resend": "^0.62.0",
62
+ "@hogsend/sms": "^0.62.0"
63
63
  },
64
64
  "optionalDependencies": {
65
- "@hogsend/plugin-apollo": "^0.60.0",
66
- "@hogsend/plugin-postmark": "^0.60.0",
67
- "@hogsend/plugin-twilio": "^0.60.0"
65
+ "@hogsend/plugin-apollo": "^0.62.0",
66
+ "@hogsend/plugin-postmark": "^0.62.0",
67
+ "@hogsend/plugin-twilio": "^0.62.0"
68
68
  },
69
69
  "devDependencies": {
70
70
  "@types/node": "^22.15.3",
@@ -1,6 +1,6 @@
1
1
  import { bucketMemberships, contacts, type Database } from "@hogsend/db";
2
2
  import { and, count as countFn, eq, gt, isNull } from "drizzle-orm";
3
- import { contactKeySql } from "../lib/contacts.js";
3
+ import { lookupContactIdByKey } from "../lib/contacts.js";
4
4
  import { getDb } from "../lib/db.js";
5
5
 
6
6
  /**
@@ -105,6 +105,20 @@ export function createBucketAccessor(
105
105
  // instead answers "false" for a member whose row was adopted under an
106
106
  // anon-era key — the person is in the bucket, `has()` says they are not,
107
107
  // and every gate built on it silently opens.
108
+ //
109
+ // PRD 07 T7 — the PRESENTED key goes through the alias-aware primitive
110
+ // rather than a `coalesce(external_id, anonymous_id, id) = :key` probe.
111
+ // That probe is blind to a merged loser's STALE key (its row is
112
+ // soft-deleted), so the survivor's membership read "false" for a key the
113
+ // survivor still owns through the identity table.
114
+ //
115
+ // The no-resolve arm is UNCHANGED: on live contacts a coalesce match
116
+ // implies one of the three identity columns equals the key, so the
117
+ // primitive's column leg is strictly wider — a `null` here is a key the
118
+ // old probe missed too, and the honest answer stays `false`.
119
+ const resolvedId = await lookupContactIdByKey(db, userId);
120
+ if (!resolvedId) return { data: false, error: null };
121
+
108
122
  const rows = await db
109
123
  .select({ id: bucketMemberships.id })
110
124
  .from(bucketMemberships)
@@ -112,7 +126,7 @@ export function createBucketAccessor(
112
126
  .where(
113
127
  and(
114
128
  eq(bucketMemberships.bucketId, bucketId),
115
- eq(contactKeySql(), userId),
129
+ eq(contacts.id, resolvedId),
116
130
  eq(bucketMemberships.status, "active"),
117
131
  isNull(bucketMemberships.deletedAt),
118
132
  isNull(contacts.deletedAt),
@@ -10,7 +10,11 @@ import type { JourneyRegistry } from "@hogsend/core/registry";
10
10
  import { bucketMemberships, contacts, type Database } from "@hogsend/db";
11
11
  import { and, desc, eq, isNotNull, isNull } from "drizzle-orm";
12
12
  import { emitBucketTransition } from "../lib/bucket-emit.js";
13
- import { contactKeySql, normalizeEmailOrNull } from "../lib/contacts.js";
13
+ import {
14
+ contactKeySql,
15
+ lookupContactIdByKey,
16
+ normalizeEmailOrNull,
17
+ } from "../lib/contacts.js";
14
18
  import type { Logger } from "../lib/logger.js";
15
19
  import {
16
20
  BUCKET_EVENT_PREFIX,
@@ -202,13 +206,26 @@ export async function checkBucketMembership(opts: {
202
206
  // the GDPR guard below — "never (re-)evaluate or emit for a
203
207
  // soft-deleted contact" — did not fire for them. A soft-deleted
204
208
  // email-only contact could still transition buckets and emit.
209
+ //
210
+ // PRD 07 T7 — the presented key resolves through the alias-aware primitive
211
+ // FIRST, so a merged-away key reads the SURVIVOR's properties instead of
212
+ // the nothing-found arm the coalesce probe returned for it.
213
+ //
214
+ // The coalesce probe SURVIVES as the fallback, and it is load-bearing, not
215
+ // belt-and-braces: `lookupContactIdByKey` filters `deleted_at IS NULL`, so
216
+ // it returns null for exactly the soft-deleted contact that failure (2)
217
+ // above is about. Stopping at the null would leave `contactDeleted` false
218
+ // and silently re-open the GDPR guard for the rows it exists to protect.
219
+ const resolvedId = await lookupContactIdByKey(db, userId);
205
220
  const [contact] = await db
206
221
  .select({
207
222
  properties: contacts.properties,
208
223
  deletedAt: contacts.deletedAt,
209
224
  })
210
225
  .from(contacts)
211
- .where(eq(contactKeySql(), userId))
226
+ .where(
227
+ resolvedId ? eq(contacts.id, resolvedId) : eq(contactKeySql(), userId),
228
+ )
212
229
  .limit(1);
213
230
  if (contact) {
214
231
  storedContactProps =
@@ -62,6 +62,10 @@ const CONNECTOR_IDENTITY_COLUMNS: Record<string, PgColumn | undefined> = {
62
62
  * members. Failure direction here is under-delivery, never over-delivery.
63
63
  */
64
64
  export function cohortSuppressionSql(): SQL {
65
+ // PRD 07 T7/D9 — the erasure leg is NOT flipped onto the identity table:
66
+ // `campaign_recipients.user_id` is a SEND-TIME ECHO of the key the anchor
67
+ // wrote (the table has no `contact_id`), so joining it back to `contacts` is
68
+ // deliberate. Re-keying the recipient table is out of PRD 07's scope.
65
69
  return sql`not exists (
66
70
  select 1 from ${emailPreferences}
67
71
  where lower(${emailPreferences.email}) = ${campaignRecipients.email}
@@ -189,6 +193,9 @@ function channelIdentitySql(condition: ChannelIdentityCondition): SQL {
189
193
  `Campaign wave \`where\`: channel_identity connector "${condition.connector}" has no linked-identity source in v1 — only "discord" is supported.`,
190
194
  );
191
195
  }
196
+ // PRD 07 T7/D9 — same stance as `cohortSuppressionSql`: the recipient
197
+ // `user_id` is a send-time echo key, not a live identity key, so this join
198
+ // stays string-matched; re-keying `campaign_recipients` is out of scope.
192
199
  const positive = sql`exists (
193
200
  select 1 from ${contacts}
194
201
  where (${contacts.externalId} = ${campaignRecipients.userId}
package/src/env.ts CHANGED
@@ -28,6 +28,15 @@ export const env = createEnv({
28
28
  .enum(["error", "warn", "info", "http", "debug"])
29
29
  .default("info"),
30
30
  DATABASE_URL: z.string().min(1),
31
+ // Connection-pool size for `createDatabase` (`@hogsend/db`). Read RAW off
32
+ // process.env there (packages/db has no dependency on this module);
33
+ // declared here so it is part of the validated env contract — the
34
+ // OUTBOUND_WEBHOOK_* stance. Deliberately a loose string: `packages/db`
35
+ // owns the parse (integer 1-50, anything else warns once and falls back to
36
+ // 10) and must NEVER crash a boot over a bad value. Hogsend Cloud sets this
37
+ // low (e.g. 3) for tenant stacks sharing one Postgres cell — the DSN's own
38
+ // `?max=` param is silently ignored by postgres.js.
39
+ DATABASE_POOL_MAX: z.string().optional(),
31
40
  REDIS_URL: z.string().min(1).default("redis://localhost:6379"),
32
41
  BETTER_AUTH_SECRET: z.string().min(1),
33
42
  BETTER_AUTH_URL: z.string().url().default("http://localhost:3002"),
@@ -264,6 +273,25 @@ export const env = createEnv({
264
273
  RESEND_WEBHOOK_SECRET: z.string().min(1).optional(),
265
274
  ADMIN_API_KEY: z.string().min(1).optional(),
266
275
  API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),
276
+ /**
277
+ * The Hogsend Cloud metering kill-switch. When "true", the PUBLIC event
278
+ * ingest surface (`POST /v1/events`) refuses new events with a 429
279
+ * `{ error: "ingest_suspended" }` BEFORE any DB write or Hatchet push —
280
+ * the soft-block the control plane flips (via the substrate's setEnv +
281
+ * redeploy) when a tenant breaches its plan limit or lands in a billing
282
+ * hold, and un-sets on the new period / upgrade.
283
+ *
284
+ * Deliberately scoped to that one surface. Provider webhooks (email/SMS
285
+ * status), the tracking endpoints (`/v1/t/*`, `/l/:slug`, `/s/:code`),
286
+ * unsubscribe/preferences and health are UNAFFECTED: suspending ingest
287
+ * must not lose delivery telemetry or break compliance surfaces. Events
288
+ * already accepted keep flowing through journeys.
289
+ *
290
+ * An enum, NOT z.coerce.boolean — an explicit "false" must actually
291
+ * disable (coerce treats the string "false" as true; SMS_LINK_TRACKING /
292
+ * HOGSEND_TEST_MODE precedent). Unset ⇒ "false" ⇒ behavior unchanged.
293
+ */
294
+ HOGSEND_INGEST_SUSPENDED: z.enum(["true", "false"]).default("false"),
267
295
  ENABLED_JOURNEYS: z.string().default("*"),
268
296
  // Buckets: same `"*"`-or-csv contract as ENABLED_JOURNEYS (Section 9.3).
269
297
  // Evaluated at worker boot — a toggle requires a worker restart; only the
@@ -12,7 +12,7 @@ import {
12
12
  journeyConfigs,
13
13
  journeyStates,
14
14
  } from "@hogsend/db";
15
- import { and, eq, inArray, isNull, notInArray, or, sql } from "drizzle-orm";
15
+ import { and, eq, inArray, isNull, notInArray, sql } from "drizzle-orm";
16
16
  import { getAnalytics } from "../lib/analytics-singleton.js";
17
17
  import { blueprintGraphLock } from "../lib/blueprint-lock.js";
18
18
  import { ALL_IDENTITY_KINDS, lookupContactIdByKey } from "../lib/contacts.js";
@@ -526,25 +526,16 @@ export async function executeJourneyRun(
526
526
  // real contact, or one asserting an email, must keep creating.
527
527
  // This leg runs BEFORE the timezone `contact` fetch below, so
528
528
  // provenance is resolved locally: the pushed `input.contactId`
529
- // when the entry ingest resolved a row, else ONE indexed lookup
530
- // for the live contact owning this canonical key on either
531
- // identity column (`contactKey = external_id ?? anonymous_id`;
532
- // the tz fetch reads `external_id` only, which misses an
533
- // anon-keyed contact).
529
+ // when the entry ingest resolved a row (that precedence is
530
+ // unchanged), else the alias-aware lookup for the live contact
531
+ // owning this canonical key — every column form
532
+ // (`external_id ?? anonymous_id ?? id`) plus the identity table,
533
+ // so a merged-away key pins the SURVIVOR rather than resolving
534
+ // nothing.
534
535
  const subjectContactId =
535
536
  input.contactId ??
536
- (
537
- await db.query.contacts.findFirst({
538
- where: and(
539
- isNull(contacts.deletedAt),
540
- or(
541
- eq(contacts.externalId, userId),
542
- eq(contacts.anonymousId, userId),
543
- ),
544
- ),
545
- columns: { id: true },
546
- })
547
- )?.id;
537
+ (await lookupContactIdByKey(db, userId)) ??
538
+ undefined;
548
539
  await ingestEvent({
549
540
  db,
550
541
  registry: getJourneyRegistrySingleton(),
@@ -717,8 +708,17 @@ export async function executeJourneyRun(
717
708
  // of the fn BEFORE the try/catch below (which would strand the row —
718
709
  // already inserted "active" — outside the failure handling). The PostHog
719
710
  // leg already `.catch`es; mirror it on the contact read.
720
- db.query.contacts
721
- .findFirst({ where: eq(contacts.externalId, userId) })
711
+ //
712
+ // Alias-aware resolve, then read the row by id. The old
713
+ // `external_id = :userId` probe missed an anon-keyed contact entirely and,
714
+ // carrying no `deleted_at` filter, read a merged-away loser's TOMBSTONE
715
+ // timezone in preference to the live survivor's.
716
+ lookupContactIdByKey(db, userId)
717
+ .then((contactId) =>
718
+ contactId
719
+ ? db.query.contacts.findFirst({ where: eq(contacts.id, contactId) })
720
+ : undefined,
721
+ )
722
722
  .catch(() => undefined),
723
723
  posthog?.getPersonProperties(userId).catch(() => undefined),
724
724
  ]);
@@ -156,6 +156,14 @@ export async function backfillAttributionBatch(opts: {
156
156
  // owner, so only the unstamped remainder needs the string lookup:
157
157
  // canonical keys are externalId or the contact row uuid. MATCH ONLY —
158
158
  // backfill never mints contacts.
159
+ //
160
+ // PRD 07 T7/D9 — BRIDGE MACHINERY: this deliberately string-matches the
161
+ // HISTORICAL `user_events.user_id` written before the dual-write, which is
162
+ // the very gap it exists to close. It is not a resolution read to flip onto
163
+ // `lookupContactIdByKey`: it is a set-based batch match over up to `limit`
164
+ // keys at once (a per-key alias-aware resolve would be N round trips), and
165
+ // widening it to alias-held keys would move which historical rows a
166
+ // recompute credits — a data change smuggled into a read flip.
159
167
  const keys = [
160
168
  ...new Set(rows.filter((row) => !row.contactId).map((row) => row.userId)),
161
169
  ];
package/src/lib/auth.ts CHANGED
@@ -90,6 +90,32 @@ export function createAuth(opts: {
90
90
  // "hogsend" → prod cookie `__Secure-hogsend.session_token`.
91
91
  advanced: {
92
92
  cookiePrefix: cookiePrefix ?? "hogsend",
93
+ /**
94
+ * Client-IP resolution for better-auth's rate limiter. Without this,
95
+ * better-auth (>=1.6.25) reads only `x-forwarded-for` and — with no
96
+ * `trustedProxies` configured — REFUSES any multi-valued XFF
97
+ * (`getIPFromHeader`: `if (forwardedIps.length !== 1) return null`).
98
+ * Railway's edge always sends two values (`<client>, <edge-hop>`), so on
99
+ * Railway every request resolved to null and ALL callers collapsed onto
100
+ * one shared per-path bucket: ten failed logins by anyone locked the
101
+ * `/sign-in/email` path for everyone (observed live 2026-08-03 — the
102
+ * control plane's mint-credentials retries and a customer's Studio
103
+ * sign-ins 429'd each other).
104
+ *
105
+ * `x-real-ip` goes first because it is single-valued and OVERWRITTEN by
106
+ * Railway's edge (verified empirically 2026-08-03 against a Railway echo
107
+ * service: a spoofed `X-Real-Ip: 7.7.7.7` arrived as the caller's true
108
+ * IP, and a spoofed `X-Forwarded-For: 6.6.6.6` was stripped too) — so a
109
+ * direct client cannot forge it to dodge the limiter. Do NOT add
110
+ * `x-envoy-external-address`: Railway passes it through UNTOUCHED (the
111
+ * spoofed value survived), so trusting it would let anyone mint
112
+ * per-request buckets and bypass rate limiting entirely.
113
+ * `x-forwarded-for` stays as the fallback for non-Railway deploys where
114
+ * a single-hop proxy sends a single-valued XFF.
115
+ */
116
+ ipAddress: {
117
+ ipAddressHeaders: ["x-real-ip", "x-forwarded-for"],
118
+ },
93
119
  },
94
120
  ...(trustedOrigins && trustedOrigins.length > 0 ? { trustedOrigins } : {}),
95
121
  // Passing `secondaryStorage` flips better-auth's rate-limit storage from the
@@ -17,6 +17,7 @@ import {
17
17
  isColdChannelAllowed,
18
18
  } from "../sources/define-contact-source.js";
19
19
  import { getContactSourceRegistry } from "../sources/registry.js";
20
+ import { lookupContactIdByKey } from "./contacts.js";
20
21
  import { getDb } from "./db.js";
21
22
  import { createLogger } from "./logger.js";
22
23
  import { readRecipientPreferences } from "./recipient-preferences.js";
@@ -27,15 +28,6 @@ import { readRecipientPreferences } from "./recipient-preferences.js";
27
28
  // validates env at boot.
28
29
  const logger = createLogger(process.env.LOG_LEVEL);
29
30
 
30
- /**
31
- * Matches the canonical UUID form of `contacts.id` (8-4-4-4-12 hex). Gates the
32
- * `eq(contacts.id, ref)` leg so a uuid comparison only runs for a genuinely
33
- * uuid-shaped ref — an email/snowflake ref would otherwise raise a Postgres
34
- * `22P02 invalid input syntax for type uuid`.
35
- */
36
- const CONTACT_ID_UUID =
37
- /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
38
-
39
31
  /**
40
32
  * Matches a NAMESPACED platform ref (`telegram:<chatId>`, `discord:<id>`, …):
41
33
  * a leading `<namespace>:` followed by a non-empty value. Captures the namespace
@@ -49,10 +41,10 @@ const NAMESPACED_REF = /^([a-z][a-z0-9_-]*):(.+)$/i;
49
41
  * when the ref is uuid-shaped — the contact's row `id`. Matching every canonical
50
42
  * key form (the journey subject key is `external_id ?? anonymous_id ?? id`) lets
51
43
  * `member: user.id` resolve a member who has NOT linked (an anonymous Discord
52
- * contact keyed by its uuid) or an email-only member. The uuid `id` leg is
53
- * shape-gated: `contacts.id` is a uuid column and an unguarded `eq(id, ref)`
54
- * against an email/snowflake text ref throws an invalid-uuid cast. First live
55
- * match wins.
44
+ * contact keyed by its uuid) or an email-only member. Those three canonical
45
+ * forms — plus a merged-away key that survives only as an identity row — are
46
+ * resolved by `lookupContactIdByKey` (which owns the uuid shape-gate: an
47
+ * unguarded `id = <text ref>` throws 22P02). First live match wins.
56
48
  *
57
49
  * NAMESPACED refs (`telegram:<chatId>`) ADDITIONALLY match the platform metadata
58
50
  * under `properties.<namespace>` (the `chat_id`/`id` fields). This is load-bearing
@@ -82,6 +74,13 @@ async function resolveContact(
82
74
  sql`${contacts.properties} -> ${nsMatch[1]}::text ->> 'id' = ${nsMatch[2]}`,
83
75
  ]
84
76
  : [];
77
+ // The three CANONICAL-key legs (external_id / anonymous_id / uuid id) are
78
+ // resolved by the alias-aware primitive instead of probed as columns: same
79
+ // row for a live key, same miss for an unknown one, and — new — the SURVIVOR
80
+ // for a merged-away key, which no column probe can see (the loser's row is
81
+ // soft-deleted). The email / discord / namespaced-jsonb legs stay columns:
82
+ // `lookupContactIdByKey` deliberately answers only for canonical keys.
83
+ const canonicalId = await lookupContactIdByKey(db, ref);
85
84
  const rows = await db
86
85
  .select({
87
86
  id: contacts.id,
@@ -96,11 +95,9 @@ async function resolveContact(
96
95
  and(
97
96
  isNull(contacts.deletedAt),
98
97
  or(
98
+ ...(canonicalId ? [eq(contacts.id, canonicalId)] : []),
99
99
  eq(contacts.email, ref),
100
- eq(contacts.externalId, ref),
101
100
  eq(contacts.discordId, ref),
102
- eq(contacts.anonymousId, ref),
103
- ...(CONTACT_ID_UUID.test(ref) ? [eq(contacts.id, ref)] : []),
104
101
  ...namespacedLegs,
105
102
  ),
106
103
  ),
@@ -19,6 +19,7 @@ import {
19
19
  inArray,
20
20
  isNotNull,
21
21
  isNull,
22
+ ne,
22
23
  not,
23
24
  or,
24
25
  type SQL,
@@ -94,11 +95,12 @@ export class UntrustedKeyKindError extends Error {
94
95
  }
95
96
 
96
97
  /**
97
- * True when `value` is the canonical key of an IDENTIFIED contact — i.e. a
98
- * live contact's `external_id`, or its `email` when that is its canonical key
99
- * (no `external_id`). Such a value names an identified person, so a
100
- * token-less publishable/unauthenticated caller must NOT be allowed to claim
101
- * it as an "anon id" (the feed-read and arrival-stamp forgery guard).
98
+ * True when `value` names an IDENTIFIED person: a live contact's canonical
99
+ * `external_id` (or its `email` when that is its canonical key), OR — via the
100
+ * identity table — any non-anonymous key a live contact holds, including a
101
+ * merged loser's STALE key (PRD 07 T6b). Such a value must NOT be claimable by
102
+ * a token-less publishable/unauthenticated caller as an "anon id" (the
103
+ * feed-read and arrival-stamp forgery guard).
102
104
  *
103
105
  * A genuine browser anon id only ever matches a contact via `anonymous_id`
104
106
  * whose canonical key is that same anon id (the contact has no `external_id`)
@@ -112,6 +114,30 @@ export async function collidesWithIdentified(
112
114
  db: Database,
113
115
  value: string,
114
116
  ): Promise<boolean> {
117
+ // Alias leg (PRD 07 T6b). The identity table sees what the columns cannot:
118
+ // a merged loser's STALE key stays aliased to its live survivor while the
119
+ // loser row is soft-deleted and invisible to the column probe below. Any
120
+ // non-anonymous alias on a live contact names an identified person — reject.
121
+ // (Deliberately stricter than the column leg in one case: an identified
122
+ // contact's email is rejected even when an `external_id` exists.)
123
+ const aliasHit = await db
124
+ .select({ id: contactAliases.id })
125
+ .from(contactAliases)
126
+ .innerJoin(contacts, eq(contacts.id, contactAliases.contactId))
127
+ .where(
128
+ and(
129
+ eq(contactAliases.aliasValue, value),
130
+ ne(contactAliases.aliasKind, "anonymous"),
131
+ isNull(contacts.deletedAt),
132
+ ),
133
+ )
134
+ .limit(1);
135
+ if (aliasHit.length > 0) return true;
136
+
137
+ // Column leg — the unbackfilled-registry backstop. A deployment that
138
+ // upgraded past 0.57 without running `identity-alias-backfill` holds
139
+ // pre-upgrade keys in the columns only; a guard that read aliases alone
140
+ // would fail OPEN there. Keep both legs (PRD 07 re-spec).
115
141
  const rows = await db
116
142
  .select({
117
143
  externalId: contacts.externalId,
@@ -164,6 +190,31 @@ async function keysAnotherContact(
164
190
  value: string,
165
191
  selfId: string,
166
192
  ): Promise<boolean> {
193
+ // Alias leg (PRD 07 T6b). A value claimed by ANOTHER live contact — under
194
+ // any kind — refuses the claim: same-kind re-claims are already blocked by
195
+ // the `(kind, value)` unique index, so what this leg actually stops is the
196
+ // CROSS-kind claim (someone else's key asserted as this caller's
197
+ // `anonymousId`), which is the adoption-theft setup. It also sees a merged
198
+ // loser's stale keys (aliased to the live survivor; the soft-deleted loser
199
+ // row is invisible to the column probe below). The live-contact join keeps
200
+ // the merge arm working: mid-merge, the loser is already soft-deleted, so
201
+ // its own alias rows don't refuse the survivor's claim of its keys.
202
+ const aliasHit = await tx
203
+ .select({ id: contactAliases.id })
204
+ .from(contactAliases)
205
+ .innerJoin(contacts, eq(contacts.id, contactAliases.contactId))
206
+ .where(
207
+ and(
208
+ eq(contactAliases.aliasValue, value),
209
+ ne(contactAliases.contactId, selfId),
210
+ isNull(contacts.deletedAt),
211
+ ),
212
+ )
213
+ .limit(1);
214
+ if (aliasHit.length > 0) return true;
215
+
216
+ // Column leg — the unbackfilled-registry backstop (see
217
+ // `collidesWithIdentified`).
167
218
  const rows = await tx
168
219
  .select({
169
220
  id: contacts.id,
@@ -287,20 +338,26 @@ type Tx = Parameters<Parameters<Database["transaction"]>[0]>[0];
287
338
 
288
339
  type ContactRow = typeof contacts.$inferSelect;
289
340
 
290
- export function contactWhereClause(id: string) {
291
- return UUID_REGEX.test(id)
292
- ? eq(contacts.id, id)
293
- : eq(contacts.externalId, id);
294
- }
295
-
296
341
  export async function resolveContact(opts: { db: Database; id: string }) {
297
342
  const { db, id } = opts;
343
+ // uuid → primary-key read (a merged-away row uuid stays a miss; that arm is
344
+ // a PK read, not an identity probe). Anything else is an EXTERNAL key:
345
+ // column probe first, then the identity table, so a stale (merged-away)
346
+ // external id resolves its SURVIVOR (PRD 07 T7).
347
+ if (UUID_REGEX.test(id)) {
348
+ const rows = await db
349
+ .select()
350
+ .from(contacts)
351
+ .where(and(eq(contacts.id, id), isNull(contacts.deletedAt)))
352
+ .limit(1);
353
+ return rows[0] ?? null;
354
+ }
298
355
  const rows = await db
299
356
  .select()
300
357
  .from(contacts)
301
- .where(and(contactWhereClause(id), isNull(contacts.deletedAt)))
358
+ .where(and(eq(contacts.externalId, id), isNull(contacts.deletedAt)))
302
359
  .limit(1);
303
- return rows[0] ?? null;
360
+ return rows[0] ?? (await resolveViaAlias(db, "external", id));
304
361
  }
305
362
 
306
363
  export interface SerializedContact {
@@ -361,11 +418,18 @@ export function serializePrefs(row: typeof emailPreferences.$inferSelect) {
361
418
  }
362
419
 
363
420
  export function contactSearchFilter(search: string) {
421
+ // The alias leg (PRD 07 T6b) finds a contact by ANY of its historical keys —
422
+ // a merged loser's old email, a second device's anon id — which the one-slot
423
+ // columns cannot. The column legs stay: strictly-more-results, and they are
424
+ // the backstop on a deployment whose alias backfill never ran.
364
425
  return or(
365
426
  ilike(contacts.email, `%${search}%`),
366
427
  ilike(contacts.externalId, `%${search}%`),
367
428
  ilike(contacts.anonymousId, `%${search}%`),
368
429
  ilike(contacts.discordId, `%${search}%`),
430
+ sql`exists (select 1 from ${contactAliases}
431
+ where ${contactAliases.contactId} = ${contacts.id}
432
+ and ${contactAliases.aliasValue} ilike ${`%${search}%`})`,
369
433
  );
370
434
  }
371
435
 
@@ -406,6 +470,11 @@ export function contactSearchFilter(search: string) {
406
470
  * (phone is not yet a merge-participating `Kind`), so a phone-only contact has
407
471
  * no non-anonymous alias row. That leg retires only when phone joins the
408
472
  * identity table.
473
+ *
474
+ * PRD 07 verdict (2026-07-29): the swap is NOT taken. The rescope keeps the
475
+ * columns as written mirrors forever, so these `IS NOT NULL` legs stay exact —
476
+ * and the swap would empty the list on a deployment whose alias backfill never
477
+ * ran, for zero benefit. Revisit only if the columns ever actually die.
409
478
  */
410
479
  export function identifiedContactFilter(): SQL {
411
480
  // `or()` is typed `SQL | undefined` because it tolerates undefined operands.
@@ -836,16 +905,19 @@ function adoptedContactId(column: Column, contactId: string): SQL<string> {
836
905
  }
837
906
 
838
907
  /**
839
- * How a fold writes its routed rows (PRD 05 T9).
908
+ * How a fold writes its routed rows (PRD 05 T9, narrowed by PRD 07 T7).
840
909
  *
841
- * - Merge mode (default): the historical shape — rewrite `user_id` onto the
842
- * survivor key, stamp `contact_id` under the {@link adoptedContactId} NULL
843
- * guard, denormalize the survivor's email.
844
- * - `stampOnly` (the adoption path): one column. The loser scope is
845
- * `orphansOnly` (see {@link foldScopes}), so every matched row carries
846
- * `contact_id IS NULL` and a plain stamp cannot re-parent another person's
847
- * history. `user_id` is frozen at its write-time value — reads no longer
848
- * consult it, and D9 keeps writing it on inserts.
910
+ * `user_id` is frozen at its write-time value in BOTH modes — reads no longer
911
+ * consult it, and D9 keeps writing it on inserts. What differs is the stamp:
912
+ *
913
+ * - Merge mode (default): stamp `contact_id` under the {@link adoptedContactId}
914
+ * NULL guard (loser-OWNED rows are re-pointed wholesale by the merge's
915
+ * (vi-b-hist) statements, never here) and denormalize the survivor's email
916
+ * where the table carries one.
917
+ * - `stampOnly` (the adoption path): a plain one-column stamp. The loser scope
918
+ * is `orphansOnly` (see {@link foldScopes}), so every matched row carries
919
+ * `contact_id IS NULL` and the stamp cannot re-parent another person's
920
+ * history.
849
921
  */
850
922
  interface FoldWriteOpts {
851
923
  stampOnly?: boolean;
@@ -1721,12 +1793,11 @@ async function mergeContacts(
1721
1793
  const identifiedLoserKeys: string[] = [];
1722
1794
 
1723
1795
  for (const loser of losers) {
1796
+ // The id is the last-resort key for a loser that has neither external nor
1797
+ // anonymous id (its user_id rows were keyed on contacts.id).
1724
1798
  const loserStrKeys = [loser.externalId, loser.anonymousId, loser.id].filter(
1725
1799
  (k): k is string => Boolean(k),
1726
1800
  );
1727
- // The id is the last-resort key for a loser that has neither external nor
1728
- // anonymous id (its user_id rows were keyed on contacts.id).
1729
- const loserKeysToRewrite = loserStrKeys;
1730
1801
 
1731
1802
  // MF-2 split: the SAFE-to-absorb key is the loser's anonymous/uuid key —
1732
1803
  // `loser.anonymousId`, or `loser.id` ONLY when the loser was never
@@ -1741,41 +1812,37 @@ async function mergeContacts(
1741
1812
  safeLoserKeys.push(loser.anonymousId ?? loser.id);
1742
1813
  }
1743
1814
 
1744
- // (ii) user_events.user_id rewrite. The paired `contact_id` stamp is the
1745
- // ADOPTION half only (NULL rows — history the loser's keys accumulated
1746
- // before any contact existed). Rows already owned by the LOSER keep
1747
- // `loser.id` here and are re-pointed wholesale by (vi-b-hist) below, which
1748
- // is the one statement that may overwrite a non-NULL owner. Splitting it
1749
- // that way keeps a single rule in the fragment (never take a row from
1750
- // another contact) and one explicit, auditable place where a merge does.
1815
+ // (ii) user_events `contact_id` stamp — the ADOPTION half only (NULL rows:
1816
+ // history the loser's keys accumulated before any contact existed). PRD 07
1817
+ // T7 deleted the paired `user_id` rewrite: the key stays frozen at its
1818
+ // write-time value and ownership rides the FK. Rows already owned by the
1819
+ // LOSER keep `loser.id` here and are re-pointed wholesale by (vi-b-hist)
1820
+ // below, which is the one statement that may overwrite a non-NULL owner.
1821
+ // Splitting it that way keeps a single rule in the fragment (never take a
1822
+ // row from another contact) and one explicit, auditable place where a
1823
+ // merge does.
1751
1824
  await tx
1752
1825
  .update(userEvents)
1753
1826
  .set({
1754
- userId: survivorKey,
1755
1827
  contactId: adoptedContactId(userEvents.contactId, survivor.id),
1756
1828
  })
1757
- .where(inArray(userEvents.userId, loserKeysToRewrite));
1829
+ .where(inArray(userEvents.userId, loserStrKeys));
1758
1830
 
1759
1831
  // (iii) journey_states — exit the loser's duplicate active/waiting row when
1760
1832
  // the survivor already holds an active/waiting row in the same journey
1761
1833
  // (respect uq_user_journey_active), THEN rewrite user_id/user_email.
1762
- await foldJourneyStates(
1763
- tx,
1764
- survivorKey,
1765
- loserKeysToRewrite,
1766
- survivor,
1767
- loser.id,
1768
- );
1834
+ await foldJourneyStates(tx, survivorKey, loserStrKeys, survivor, loser.id);
1769
1835
 
1770
- // (iv) email_sends rewrite user_id + userEmail to survivor's.
1836
+ // (iv) email_sends: `contact_id` stamp (NULL-guarded, as (ii)) + the
1837
+ // userEmail denorm. `user_id` frozen (PRD 07 T7); the address denorm still
1838
+ // updates because it feeds person-level send history, not identity.
1771
1839
  await tx
1772
1840
  .update(emailSends)
1773
1841
  .set({
1774
- userId: survivorKey,
1775
1842
  contactId: adoptedContactId(emailSends.contactId, survivor.id),
1776
1843
  ...(survivor.email ? { userEmail: survivor.email } : {}),
1777
1844
  })
1778
- .where(inArray(emailSends.userId, loserKeysToRewrite));
1845
+ .where(inArray(emailSends.userId, loserStrKeys));
1779
1846
 
1780
1847
  // (v) bucket_memberships — soft-leave the loser's duplicate active
1781
1848
  // membership when the survivor already holds one in the same bucket (respect
@@ -1783,7 +1850,7 @@ async function mergeContacts(
1783
1850
  await foldBucketMemberships(
1784
1851
  tx,
1785
1852
  survivorKey,
1786
- loserKeysToRewrite,
1853
+ loserStrKeys,
1787
1854
  survivor.id,
1788
1855
  loser.id,
1789
1856
  );
@@ -1791,7 +1858,7 @@ async function mergeContacts(
1791
1858
  // (vi) email_preferences FOLD (never blind-rewrite — risk 6).
1792
1859
  await foldEmailPreferences(
1793
1860
  tx,
1794
- loserKeysToRewrite,
1861
+ loserStrKeys,
1795
1862
  survivorKey,
1796
1863
  survivor.id,
1797
1864
  loser.id,
@@ -1814,7 +1881,7 @@ async function mergeContacts(
1814
1881
 
1815
1882
  // (vi-b-hist) the five HISTORY tables' `contact_id` re-point (PRD 04 T3).
1816
1883
  // Same shape as the deals/crm_links repoints above: a uuid column the
1817
- // string-key rewrites never touch.
1884
+ // key stamps above never touch.
1818
1885
  //
1819
1886
  // PRD 05 T3: `contact_id` IS now a unique-index column on three of these
1820
1887
  // five (migration 0071), so "plain UPDATEs suffice" is no longer true on its
@@ -1831,14 +1898,14 @@ async function mergeContacts(
1831
1898
  // the other order, every merge in between would strand history rows
1832
1899
  // pointing at a soft-deleted loser contact.
1833
1900
  //
1834
- // It is also the OVERWRITE half of the key rewrites above: those stamp only
1901
+ // It is also the OVERWRITE half of the stamps above: those touch only
1835
1902
  // rows nobody owned (the {@link adoptedContactId} NULL guard), so the
1836
1903
  // loser-OWNED rows arrive here still carrying `loser.id` and this is what
1837
- // moves them. Between the two halves, every row the merge leaves keyed to
1838
- // the survivor also carries the survivor's uuid. Runs after the rewrites
1839
- // rather than before because it filters on `contact_id`, not `user_id` —
1840
- // the order the key rewrites move is irrelevant to it — and re-running the
1841
- // pair changes nothing (`contact_id = loser.id` matches zero rows twice).
1904
+ // moves them. Between the two halves, every row the merge folds carries
1905
+ // the survivor's uuid while `user_id` stays frozen at its write-time
1906
+ // value (PRD 07 T7). Runs after the stamps rather than before because it
1907
+ // filters on `contact_id`, not `user_id`, and re-running the pair changes
1908
+ // nothing (`contact_id = loser.id` matches zero rows twice).
1842
1909
  await tx
1843
1910
  .update(userEvents)
1844
1911
  .set({ contactId: survivor.id })
@@ -2186,7 +2253,10 @@ async function foldJourneyStates(
2186
2253
  opts?.stampOnly
2187
2254
  ? { contactId: survivor.id, updatedAt: new Date() }
2188
2255
  : {
2189
- userId: survivorKey,
2256
+ // PRD 07 T7: `user_id` is FROZEN in merge mode too — ownership
2257
+ // moves on the FK (NULL-guarded here; loser-owned rows re-point
2258
+ // in (vi-b-hist)). The email denorm still updates: it is the
2259
+ // live send address for a re-pointed run, not an identity key.
2190
2260
  contactId: adoptedContactId(journeyStates.contactId, survivor.id),
2191
2261
  ...(survivor.email ? { userEmail: survivor.email } : {}),
2192
2262
  updatedAt: new Date(),
@@ -2271,7 +2341,7 @@ async function foldBucketMemberships(
2271
2341
  opts?.stampOnly
2272
2342
  ? { contactId: survivorId, updatedAt: new Date() }
2273
2343
  : {
2274
- userId: survivorKey,
2344
+ // PRD 07 T7: `user_id` frozen in merge mode (see foldJourneyStates).
2275
2345
  contactId: adoptedContactId(
2276
2346
  bucketMemberships.contactId,
2277
2347
  survivorId,
@@ -2386,16 +2456,15 @@ async function foldEmailPreferences(
2386
2456
  const target = targetRows[0];
2387
2457
 
2388
2458
  if (!target) {
2389
- // The slot is free on BOTH keys. Merge mode re-points the loser row;
2390
- // stamp mode (adoption) writes ownership only — the row is an orphan by
2391
- // scope, so a plain stamp cannot re-parent anything.
2459
+ // The slot is free on BOTH keys. Both modes stamp ownership only (PRD 07
2460
+ // T7: `user_id` frozen in merge mode too); merge mode NULL-guards the
2461
+ // stamp, stamp mode's rows are orphans by scope so a plain stamp is safe.
2392
2462
  await tx
2393
2463
  .update(emailPreferences)
2394
2464
  .set(
2395
2465
  opts?.stampOnly
2396
2466
  ? { contactId: survivorId, updatedAt: new Date() }
2397
2467
  : {
2398
- userId: survivorKey,
2399
2468
  contactId: adoptedContactId(
2400
2469
  emailPreferences.contactId,
2401
2470
  survivorId,
@@ -2770,10 +2839,26 @@ export async function findContacts(opts: {
2770
2839
  if (userId) clauses.push(eq(contacts.externalId, userId));
2771
2840
  if (clauses.length === 0) return [];
2772
2841
 
2773
- return db
2842
+ const rows = await db
2774
2843
  .select()
2775
2844
  .from(contacts)
2776
2845
  .where(and(or(...clauses), isNull(contacts.deletedAt)));
2846
+
2847
+ // Identity-table fallback per supplied key (PRD 07 T7): a STALE
2848
+ // (merged-away) email or external id finds its survivor.
2849
+ const found = new Set(rows.map((r) => r.id));
2850
+ if (email && !rows.some((r) => r.email === email)) {
2851
+ const viaAlias = await resolveViaAlias(db, "email", email);
2852
+ if (viaAlias && !found.has(viaAlias.id)) {
2853
+ rows.push(viaAlias);
2854
+ found.add(viaAlias.id);
2855
+ }
2856
+ }
2857
+ if (userId && !rows.some((r) => r.externalId === userId)) {
2858
+ const viaAlias = await resolveViaAlias(db, "external", userId);
2859
+ if (viaAlias && !found.has(viaAlias.id)) rows.push(viaAlias);
2860
+ }
2861
+ return rows;
2777
2862
  }
2778
2863
 
2779
2864
  /**
@@ -2811,10 +2896,35 @@ export async function softDeleteContact(opts: {
2811
2896
  // back together, so a failure cannot leave identity keys stranded in the
2812
2897
  // alias table for a deleted person.
2813
2898
  const row = await db.transaction(async (tx) => {
2899
+ // Alias-aware target resolution (PRD 07 T7): erasing by a STALE
2900
+ // (merged-away) email or external id erases the SURVIVOR — the live row
2901
+ // that person's data folded into. Resolved inside the tx so the lookup,
2902
+ // the soft-delete and the erasure hook see one consistent state.
2903
+ const direct = await tx
2904
+ .select({
2905
+ id: contacts.id,
2906
+ externalId: contacts.externalId,
2907
+ email: contacts.email,
2908
+ })
2909
+ .from(contacts)
2910
+ .where(and(or(...clauses), isNull(contacts.deletedAt)));
2911
+ const targetIds = new Set(direct.map((r) => r.id));
2912
+ if (email && !direct.some((r) => r.email === email)) {
2913
+ const viaAlias = await resolveViaAlias(tx, "email", email);
2914
+ if (viaAlias) targetIds.add(viaAlias.id);
2915
+ }
2916
+ if (userId && !direct.some((r) => r.externalId === userId)) {
2917
+ const viaAlias = await resolveViaAlias(tx, "external", userId);
2918
+ if (viaAlias) targetIds.add(viaAlias.id);
2919
+ }
2920
+ if (targetIds.size === 0) return undefined;
2921
+
2814
2922
  const updated = await tx
2815
2923
  .update(contacts)
2816
2924
  .set({ deletedAt: new Date(), updatedAt: new Date() })
2817
- .where(and(or(...clauses), isNull(contacts.deletedAt)))
2925
+ .where(
2926
+ and(inArray(contacts.id, [...targetIds]), isNull(contacts.deletedAt)),
2927
+ )
2818
2928
  .returning({
2819
2929
  id: contacts.id,
2820
2930
  externalId: contacts.externalId,
@@ -3000,7 +3110,7 @@ export async function lookupContactIdByKey(
3000
3110
  * device's anon id lives ONLY as an identity row) both fall back to it after
3001
3111
  * their column probes miss. */
3002
3112
  export async function resolveViaAlias(
3003
- db: Database,
3113
+ db: Database | Tx,
3004
3114
  kind: Kind,
3005
3115
  value: string,
3006
3116
  ): Promise<ContactRow | null> {
package/src/lib/refine.ts CHANGED
@@ -1,7 +1,11 @@
1
1
  import { contacts, type Database } from "@hogsend/db";
2
2
  import { and, eq, isNull, type SQL } from "drizzle-orm";
3
3
  import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
4
- import { contactKey, normalizeEmail } from "./contacts.js";
4
+ import {
5
+ contactKey,
6
+ lookupContactIdByKey,
7
+ normalizeEmail,
8
+ } from "./contacts.js";
5
9
  import { getDb } from "./db.js";
6
10
  import {
7
11
  countEnrichmentLookups,
@@ -240,15 +244,17 @@ async function findContactRow(
240
244
  if (row) return row;
241
245
  }
242
246
  if (keys.userId) {
243
- // `userId` is the canonical key — external_id ?? anonymous_id ?? id — so
244
- // try each leg in that same precedence.
245
- const byExternal = await live(eq(contacts.externalId, keys.userId));
246
- if (byExternal) return byExternal;
247
- const byAnonymous = await live(eq(contacts.anonymousId, keys.userId));
248
- if (byAnonymous) return byAnonymous;
249
- if (UUID.test(keys.userId)) {
250
- const byId = await live(eq(contacts.id, keys.userId));
251
- if (byId) return byId;
247
+ // `userId` is the canonical key — external_id ?? anonymous_id ?? id — and
248
+ // `lookupContactIdByKey` owns that whole precedence: the three identity
249
+ // columns (uuid leg regex-guarded) and then the identity table. The alias
250
+ // leg is the new behaviour: a MERGED-AWAY key refines the SURVIVOR instead
251
+ // of missing (the loser's row is soft-deleted, invisible to any column
252
+ // probe). A key nothing owns still resolves nothing — the caller's
253
+ // email-only fallback above is untouched.
254
+ const contactId = await lookupContactIdByKey(db, keys.userId);
255
+ if (contactId) {
256
+ const row = await live(eq(contacts.id, contactId));
257
+ if (row) return row;
252
258
  }
253
259
  }
254
260
  return null;
@@ -167,6 +167,7 @@ async function flipContactChannel(
167
167
  .select({
168
168
  id: contacts.id,
169
169
  externalId: contacts.externalId,
170
+ anonymousId: contacts.anonymousId,
170
171
  email: contacts.email,
171
172
  })
172
173
  .from(contacts)
@@ -174,10 +175,14 @@ async function flipContactChannel(
174
175
  .limit(1);
175
176
  const contact = rows[0];
176
177
  if (!contact?.email) return;
178
+ // PRD 07 T7: ownership rides `contactId`; the string key is a D9 echo of
179
+ // the full canonical derivation (the old inline `externalId ?? id` skipped
180
+ // `anonymousId`, mis-keying anon-only contacts onto their row uuid).
177
181
  await upsertEmailPreference({
178
182
  db,
179
- externalId: contact.externalId ?? contact.id,
183
+ externalId: contact.externalId ?? contact.anonymousId ?? contact.id,
180
184
  email: contact.email,
185
+ contactId: contact.id,
181
186
  update: { categoryKey: SMS_CHANNEL_ID, categoryValue: subscribed },
182
187
  source,
183
188
  });
@@ -1,6 +1,7 @@
1
1
  import { isValidTimeZone, type TimeZone } from "@hogsend/core/schedule";
2
2
  import { contacts, type Database } from "@hogsend/db";
3
3
  import { eq } from "drizzle-orm";
4
+ import { lookupContactIdByKey } from "./contacts.js";
4
5
 
5
6
  export interface ResolveTimezoneInput {
6
7
  /** Explicit per-call override, e.g. from `ctx.when.tz("Area/City")`. */
@@ -116,10 +117,19 @@ export async function setContactTimezone(opts: {
116
117
  throw new TypeError(`setContactTimezone: invalid timezone "${timezone}"`);
117
118
  }
118
119
 
120
+ // Resolve the canonical key the alias-aware way, then write BY ROW ID. The
121
+ // old `external_id = :userId` probe was wrong twice over: it never saw an
122
+ // anon-keyed (or uuid-keyed) contact, and — carrying no `deleted_at` filter —
123
+ // a merged-away loser still holds its `external_id`, so a stale key wrote the
124
+ // timezone onto the TOMBSTONE while the live survivor kept none. A key that
125
+ // owns no live contact still returns `{ updated: false }`, unchanged.
126
+ const contactId = await lookupContactIdByKey(db, userId);
127
+ if (!contactId) return { updated: false };
128
+
119
129
  const rows = await db
120
130
  .update(contacts)
121
131
  .set({ timezone, updatedAt: new Date() })
122
- .where(eq(contacts.externalId, userId))
132
+ .where(eq(contacts.id, contactId))
123
133
  .returning({ id: contacts.id });
124
134
 
125
135
  return { updated: rows.length > 0 };
@@ -1,9 +1,9 @@
1
1
  import { bySubject } from "@hogsend/core";
2
- import { bucketConfigs, bucketMemberships, contacts } from "@hogsend/db";
2
+ import { bucketConfigs, bucketMemberships } from "@hogsend/db";
3
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
4
  import { and, count, desc, eq, inArray, isNull } from "drizzle-orm";
5
5
  import type { AppEnv } from "../../app.js";
6
- import { contactKeySql } from "../../lib/contacts.js";
6
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
7
7
 
8
8
  const bucketSchema = z.object({
9
9
  id: z.string(),
@@ -472,14 +472,16 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
472
472
  // under an earlier key — the exact history Studio is being asked to show.
473
473
  // No live contact for the key → fall back to the string arm, which is
474
474
  // also the right answer for a contactless (anonymous) subject.
475
- const [owner] = await db
476
- .select({ id: contacts.id })
477
- .from(contacts)
478
- .where(and(eq(contactKeySql(), userId), isNull(contacts.deletedAt)))
479
- .limit(1);
475
+ //
476
+ // PRD 07 T7 — resolution runs through the alias-aware primitive (same
477
+ // live-contact scope as the `coalesce(...) = :userId` probe it replaces),
478
+ // so an operator pasting a merged-away key sees the SURVIVOR's rows
479
+ // instead of dropping to the string arm and showing only the fragment
480
+ // still literally keyed on it.
481
+ const ownerId = await lookupContactIdByKey(db, userId);
480
482
  conditions.push(
481
483
  bySubject(bucketMemberships, {
482
- contactId: owner?.id ?? null,
484
+ contactId: ownerId,
483
485
  userKey: userId,
484
486
  }),
485
487
  );
@@ -9,6 +9,7 @@ import { and, asc, count, desc, eq, isNull, not, sql } from "drizzle-orm";
9
9
  import type { AppEnv } from "../../app.js";
10
10
  import {
11
11
  ALL_IDENTITY_KINDS,
12
+ contactKeySql,
12
13
  contactSearchFilter,
13
14
  deleteIdentityAliasesForContact,
14
15
  identifiedContactFilter,
@@ -375,9 +376,17 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
375
376
  : desc(contacts.lastSeenAt),
376
377
  ];
377
378
 
378
- // Valued events are keyed by the contact's canonical event key
379
- // (external_id ?? anonymous_id ?? id) — same precedence ingestEvent
380
- // resolves. Served by the partial user_events_valued_user_idx.
379
+ // Valued events are owned the PRD 05 way: by `contact_id` when the row
380
+ // carries one, and only otherwise by the contact's canonical event key
381
+ // (external_id ?? anonymous_id ?? id — the same precedence `ingestEvent`
382
+ // resolves, served by the partial user_events_valued_user_idx). The FK arm
383
+ // is what the string arm cannot do: adoption stamps `contact_id` WITHOUT
384
+ // rewriting the frozen `user_id`, so a person's pre-identify (or
385
+ // merged-away) revenue sat under a key that no longer equals their
386
+ // canonical one and this filter never counted it. The `contact_id is null`
387
+ // guard on the string arm keeps it to rows nobody owns — an unowned row
388
+ // whose key happens to collide with another contact's is the bug PRD 05
389
+ // exists to close.
381
390
  // Exclusions come from lib/revenue.ts (static machinery events + funnel
382
391
  // milestone triggers + the browser trust gate): one deal's value rides
383
392
  // several rows, and pk_-minted values are forgeable.
@@ -386,7 +395,10 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
386
395
  ? sql`(
387
396
  select coalesce(sum(ue.value), 0)
388
397
  from user_events ue
389
- where ue.user_id = coalesce(${contacts.externalId}, ${contacts.anonymousId}, ${contacts.id}::text)
398
+ where (
399
+ ue.contact_id = ${contacts.id}
400
+ or (ue.contact_id is null and ue.user_id = ${contactKeySql()})
401
+ )
390
402
  and ue.value is not null
391
403
  and ue.event not in (${sql.join(
392
404
  revenueExcludedEvents().map((e) => sql`${e}`),
@@ -50,6 +50,11 @@ const eventRequestSchema = z.object({
50
50
  userToken: z.string().optional(),
51
51
  });
52
52
 
53
+ const suspendedSchema = z.object({
54
+ error: z.literal("ingest_suspended"),
55
+ message: z.string(),
56
+ });
57
+
53
58
  const eventResponseSchema = z.object({
54
59
  stored: z.boolean(),
55
60
  exits: z.array(
@@ -101,9 +106,24 @@ const eventRoute = createRoute({
101
106
  description:
102
107
  "Publishable key attempted to act on another identity without a verified userToken",
103
108
  },
109
+ 429: {
110
+ content: { "application/json": { schema: suspendedSchema } },
111
+ description:
112
+ "Event ingest is suspended for this instance (HOGSEND_INGEST_SUSPENDED)",
113
+ },
104
114
  },
105
115
  });
106
116
 
117
+ /**
118
+ * The documented soft-block body. Verbatim contract — the Hogsend Cloud
119
+ * dashboard and the SDKs match on `error === "ingest_suspended"`.
120
+ */
121
+ export const INGEST_SUSPENDED_BODY = {
122
+ error: "ingest_suspended",
123
+ message:
124
+ "Event ingest is suspended for this instance (plan limit reached or billing hold). Already-accepted events are unaffected.",
125
+ } as const;
126
+
107
127
  export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
108
128
  eventRoute,
109
129
  async (c) => {
@@ -111,6 +131,15 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
111
131
  c.get("container");
112
132
  const body = c.req.valid("json");
113
133
 
134
+ // Cloud metering soft-block (PRD 06 §Tasks 1). Checked FIRST — before the
135
+ // identity gate, before `ingestEvent` writes `user_events`, before the
136
+ // Hatchet push — so a suspended instance costs the tenant DB nothing. Only
137
+ // this public ingest surface is gated: delivery webhooks, tracking and the
138
+ // compliance/preference routes stay live.
139
+ if (env.HOGSEND_INGEST_SUSPENDED === "true") {
140
+ return c.json(INGEST_SUSPENDED_BODY, 429);
141
+ }
142
+
114
143
  const guard = gatePublishableIdentity(c, body, env.BETTER_AUTH_SECRET);
115
144
  if (guard) return guard;
116
145
 
@@ -193,6 +193,11 @@ async function canonicalKey(
193
193
  .limit(1);
194
194
  if (rows[0])
195
195
  return { recipientKey: contactKey(rows[0]), contactId: rows[0].id };
196
+ // Identity-table fallback (PRD 07 T7): a STALE (merged-away) email keys
197
+ // the SURVIVOR's feed instead of stranding rows under the raw address.
198
+ const viaAlias = await resolveViaAlias(db, "email", email);
199
+ if (viaAlias)
200
+ return { recipientKey: contactKey(viaAlias), contactId: viaAlias.id };
196
201
  return { recipientKey: email };
197
202
  }
198
203
  if (ident.userId) {
@@ -41,7 +41,11 @@ import {
41
41
  import { getBucketRegistrySingleton } from "../buckets/registry-singleton.js";
42
42
  import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
43
43
  import { emitBucketTransition } from "../lib/bucket-emit.js";
44
- import { contactKeySql, normalizeEmailOrNull } from "../lib/contacts.js";
44
+ import {
45
+ contactKeySql,
46
+ lookupContactIdByKey,
47
+ normalizeEmailOrNull,
48
+ } from "../lib/contacts.js";
45
49
  import { hatchet } from "../lib/hatchet.js";
46
50
  import { toSleepDuration } from "../lib/hatchet-duration.js";
47
51
  import type { Logger } from "../lib/logger.js";
@@ -1270,19 +1274,28 @@ async function loadContactProperties(
1270
1274
  * which row a WRITE folds into, whereas this only decides whose history the
1271
1275
  * criteria re-confirm reads — and it reads the same key the task is already
1272
1276
  * keyed on.
1277
+ *
1278
+ * PRD 07 T7 — resolution goes through the alias-aware primitive instead of a
1279
+ * `coalesce(external_id, anonymous_id, id) = :userKey` probe: an armed timer
1280
+ * whose key was merged away between arming and waking now re-confirms against
1281
+ * the SURVIVOR's properties rather than evaluating against `{}`. Live-only on
1282
+ * both sides (`lookupContactIdByKey` filters `deleted_at IS NULL`, as the
1283
+ * coalesce probe did), so an unowned key still returns null.
1273
1284
  */
1274
1285
  async function resolveLiveContact(
1275
1286
  db: Database,
1276
1287
  userKey: string,
1277
1288
  ): Promise<{ id: string; properties: Record<string, unknown> } | null> {
1289
+ const contactId = await lookupContactIdByKey(db, userKey);
1290
+ if (!contactId) return null;
1278
1291
  const [contact] = await db
1279
- .select({ id: contacts.id, properties: contacts.properties })
1292
+ .select({ properties: contacts.properties })
1280
1293
  .from(contacts)
1281
- .where(and(eq(contactKeySql(), userKey), isNull(contacts.deletedAt)))
1294
+ .where(eq(contacts.id, contactId))
1282
1295
  .limit(1);
1283
1296
  if (!contact) return null;
1284
1297
  return {
1285
- id: contact.id,
1298
+ id: contactId,
1286
1299
  properties: (contact.properties as Record<string, unknown> | null) ?? {},
1287
1300
  };
1288
1301
  }