@hogsend/engine 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.22.0",
-    "@hogsend/db": "^0.22.0",
-    "@hogsend/email": "^0.22.0",
-    "@hogsend/plugin-posthog": "^0.22.0",
-    "@hogsend/plugin-resend": "^0.22.0"
+    "@hogsend/core": "^0.23.0",
+    "@hogsend/db": "^0.23.0",
+    "@hogsend/email": "^0.23.0",
+    "@hogsend/plugin-posthog": "^0.23.0",
+    "@hogsend/plugin-resend": "^0.23.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.22.0"
+    "@hogsend/plugin-postmark": "^0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/container.ts

@@ -56,6 +56,10 @@ import type {
   FrequencyCapConfig,
 } from "./lib/email-service-types.js";
 import { hatchet } from "./lib/hatchet.js";
+import {
+  createIdentityService,
+  type IdentityService,
+} from "./lib/identity-service.js";
 import { createLogger, type Logger } from "./lib/logger.js";
 import { createTrackedMailer } from "./lib/mailer.js";
 import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
@@ -124,6 +128,15 @@ export interface HogsendClient {
    * treats that as a silent no-op.
    */
   analytics?: AnalyticsProvider;
+  /**
+   * Identity-attach helper that resolves/merges a contact AND propagates the
+   * analytics merge (§5.3) in one call, for identity-attach OUTSIDE the
+   * `/v1/events` ingest path. Discord `/link` (§7) wires its `resolveContact`
+   * callback to `client.identity.linkContact` so a successful contact-merge
+   * folds the discord-keyed person into the canonical one through the SAME
+   * engine emission ingest uses — never bespoke per-consumer plumbing.
+   */
+  identity: IdentityService;
   registry: JourneyRegistry;
   /**
    * The bucket registry (id map + event/property inverted indexes for candidate
@@ -614,6 +627,13 @@ export function createHogsendClient(
   // undefined (no provider configured) — the reads stay no-ops.
   setAnalytics(analytics);
 
+  // Identity-attach helper (§7): bound to THIS container's db + resolved
+  // analytics provider so a contact-merge outside the `/v1/events` ingest path
+  // (Discord `/link`) propagates the analytics merge through the same engine
+  // emission ingest uses. Closes over `analytics` (may be undefined → the merge
+  // emission no-ops; the resolve still happens).
+  const identity = createIdentityService({ db, analytics, logger });
+
   // Build + install the outbound DESTINATION registry (Phase 3) the
   // self-booting delivery task resolves by `webhook_endpoints.kind`. Order is
   // load-bearing: the env-enabled presets come FIRST and the consumer's
@@ -700,6 +720,7 @@ export function createHogsendClient(
     templates,
     analyticsProviders,
     analytics,
+    identity,
     registry,
     bucketRegistry,
     listRegistry,

package/src/index.ts

@@ -165,6 +165,11 @@ export {
   setJourneyRegistry,
 } from "./journeys/registry-singleton.js";
 // --- Analytics provider registry (the analytics sibling) ---
+export {
+  type IdentityMergeReason,
+  logResidualTwins,
+  mergeAnalyticsIdentities,
+} from "./lib/analytics-identity.js";
 export { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
 export { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
 // --- Auth ---
@@ -265,9 +270,16 @@ export { checkEmailPreferences } from "./lib/enrollment-guards.js";
 export { isFrequencyCapped } from "./lib/frequency-cap.js";
 export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
 export { hatchet } from "./lib/hatchet.js";
+// --- Identity service (resolve/merge + analytics merge propagation, §7) ---
+export {
+  createIdentityService,
+  type IdentityService,
+  type LinkContactArgs,
+} from "./lib/identity-service.js";
 export {
   generateIdentityToken,
   type IdentityTokenPayload,
+  type IdentityTokenScope,
   InvalidIdentityTokenError,
   validateIdentityToken,
 } from "./lib/identity-token.js";
@@ -350,6 +362,7 @@ export {
 } from "./lib/tracked.js";
 // --- Tracking ---
 export {
+  createTrackedLink,
   injectOpenPixel,
   prepareTrackedHtml,
   rewriteLinks,

package/src/lib/analytics-identity.ts

@@ -0,0 +1,112 @@
+import type { AnalyticsProvider } from "@hogsend/core";
+import type { Logger } from "./logger.js";
+
+/**
+ * The reason a merge was emitted — surfaced on the `identity.merge.emitted`
+ * structured log so an operator can see WHICH resolver path stitched (§10.5). A
+ * declining `collide_merge` / `key_flip` volume after anon threading lands
+ * (Stage 1) is the empirical "forks prevented" signal.
+ */
+export type IdentityMergeReason =
+  | "collide_merge"
+  | "key_flip"
+  | "click_identify"
+  | "discord_link";
+
+/**
+ * Fan out the provider-neutral `mergeIdentities` primitive (§5.3) once per
+ * loser key, folding each absorbed (anonymous/uuid) key INTO the surviving
+ * canonical contact key. Fire-and-forget and never throws: analytics is
+ * non-load-bearing, so a provider error must not fail the ingest that triggered
+ * the merge.
+ *
+ * Direction is load-bearing (MF-1): `survivorKey` is the SURVIVING/canonical
+ * (identified) id and each `loserKey` is the ABSORBED (anonymous) one — mapped
+ * straight to `mergeIdentities({ distinctId: survivorKey, alias: loserKey })`.
+ *
+ * No-ops cleanly when:
+ * - no provider is injected (`!analytics`),
+ * - the active provider can't merge (`!capabilities.identityMerge` — a legacy
+ *   adapter or a provider without an `alias` wire),
+ * - or it carries no `mergeIdentities` method.
+ *
+ * MF-2: callers MUST pass only the SAFE-to-absorb loser keys (anonymous/uuid,
+ * never an `external_id` that already identified a PostHog person). Aliasing an
+ * already-identified key is the identified→identified merge PostHog refuses
+ * (R2/R4) — it silently no-ops AND spams "Refused to merge" warnings on the
+ * normal merge path. The filtering happens at the emission point (the resolver
+ * splits its loser keys into safe vs. identified); this helper only fans out
+ * what it is given and skips a self-alias (`loserKey === survivorKey`).
+ */
+export function mergeAnalyticsIdentities(opts: {
+  analytics?: AnalyticsProvider;
+  survivorKey: string;
+  loserKeys: string[];
+  /** Stitching path, for the `identity.merge.emitted` observability log. */
+  reason: IdentityMergeReason;
+  /** The contact id, for correlating the merge log to a contact row. */
+  contactId?: string;
+  logger?: Logger;
+}): void {
+  const { analytics, survivorKey, loserKeys, reason, contactId, logger } = opts;
+
+  if (!analytics?.capabilities.identityMerge) {
+    if (loserKeys.length > 0) {
+      logger?.debug("identity.merge.skipped", {
+        reason: analytics ? "no_capability" : "no_provider",
+      });
+    }
+    return;
+  }
+  if (!analytics.mergeIdentities) return;
+
+  for (const loserKey of loserKeys) {
+    if (!loserKey || loserKey === survivorKey) {
+      logger?.debug("identity.merge.skipped", { reason: "self_alias" });
+      continue;
+    }
+    try {
+      analytics.mergeIdentities({ distinctId: survivorKey, alias: loserKey });
+      logger?.info("identity.merge.emitted", {
+        provider: analytics.meta.id,
+        survivorKey,
+        alias: loserKey,
+        reason,
+        ...(contactId ? { contactId } : {}),
+      });
+    } catch (err) {
+      // Best-effort: analytics is non-load-bearing — never throw.
+      logger?.warn("identity.merge.failed", {
+        provider: analytics.meta.id,
+        reason,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+/**
+ * Emit the `identity.merge.residual_twin` observability log (§10.5) for each
+ * loser key MF-2 excluded from the safe fan-out: a loser carrying an
+ * `external_id` is, by the engine's own model, an already-identified PostHog
+ * person, and PostHog refuses to merge two identified persons on the safe path.
+ * These twins are the known steady-state residual (OQ-1) made visible — NOT an
+ * error, just the honest "one email → one person, except across two prior
+ * identified persons" outcome surfaced for monitoring.
+ */
+export function logResidualTwins(opts: {
+  survivorKey: string;
+  identifiedLoserKeys: string[];
+  contactId?: string;
+  logger?: Logger;
+}): void {
+  const { survivorKey, identifiedLoserKeys, contactId, logger } = opts;
+  for (const loserExternalId of identifiedLoserKeys) {
+    if (!loserExternalId || loserExternalId === survivorKey) continue;
+    logger?.info("identity.merge.residual_twin", {
+      survivorKey,
+      loserExternalId,
+      ...(contactId ? { contactId } : {}),
+    });
+  }
+}

package/src/lib/contacts.ts

@@ -353,6 +353,23 @@ export async function resolveOrCreateContact(opts: {
   created: boolean;
   linked: boolean;
   merged: boolean;
+  /**
+   * SAFE-to-absorb loser keys (§5.3 MF-2): the anonymous/uuid keys the resolver
+   * folded INTO `resolvedKey` this call — populated only on a collide-MERGE or a
+   * canonical-key flip that absorbed an anon/uuid key. Callers fan these out via
+   * `mergeAnalyticsIdentities({ distinctId: resolvedKey, alias: <key> })`. An
+   * `external_id` is NEVER listed here (it carried an identified PostHog person;
+   * aliasing it is the merge PostHog refuses — R2/R4); it surfaces in
+   * {@link mergedIdentifiedKeys} instead. Empty/absent ⇒ nothing to stitch.
+   */
+  mergedKeys?: string[];
+  /**
+   * Loser keys MF-2 could NOT safely absorb — already-identified `external_id`s
+   * (and the superseded `external_id` on a key flip). These are the known
+   * steady-state twin residual (§10, OQ-1); callers log them as
+   * `identity.merge.residual_twin` for observability. Never aliased.
+   */
+  mergedIdentifiedKeys?: string[];
 }> {
   const { db, contactProperties } = opts;
   const userId = opts.userId?.trim() || undefined;
@@ -423,7 +440,29 @@ export async function resolveOrCreateContact(opts: {
     // --- CASE: fill-in-link (single existing row) ---
     const single = candidates[0];
     if (candidates.length === 1 && single) {
-      const { id, resolvedKey } = await fillInLink(tx, single, {
+      const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
+        await fillInLink(tx, single, {
+          userId,
+          email,
+          anonymousId,
+          discordId,
+          patch,
+          hasPatch,
+        });
+      return {
+        id,
+        resolvedKey,
+        created: false,
+        linked: true,
+        merged: false,
+        mergedKeys,
+        mergedIdentifiedKeys,
+      };
+    }
+
+    // --- CASE: collide-MERGE (2-3 distinct rows) ---
+    const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
+      await mergeContacts(tx, candidates, {
         userId,
         email,
         anonymousId,
@@ -431,19 +470,15 @@ export async function resolveOrCreateContact(opts: {
         patch,
         hasPatch,
       });
-      return { id, resolvedKey, created: false, linked: true, merged: false };
-    }
-
-    // --- CASE: collide-MERGE (2-3 distinct rows) ---
-    const { id, resolvedKey } = await mergeContacts(tx, candidates, {
-      userId,
-      email,
-      anonymousId,
-      discordId,
-      patch,
-      hasPatch,
-    });
-    return { id, resolvedKey, created: false, linked: true, merged: true };
+    return {
+      id,
+      resolvedKey,
+      created: false,
+      linked: true,
+      merged: true,
+      mergedKeys,
+      mergedIdentifiedKeys,
+    };
   });
 }
 
@@ -465,7 +500,12 @@ async function fillInLink(
   tx: Tx,
   row: ContactRow,
   ctx: ResolveCtx,
-): Promise<{ id: string; resolvedKey: string }> {
+): Promise<{
+  id: string;
+  resolvedKey: string;
+  mergedKeys?: string[];
+  mergedIdentifiedKeys?: string[];
+}> {
   const set: Record<string, unknown> = {
     lastSeenAt: new Date(),
     updatedAt: new Date(),
@@ -513,6 +553,15 @@ async function fillInLink(
   // updated row (with its new email/keys) is what foldJourneyStates/email_sends
   // denormalize into.
   const newKey = nextExternalId ?? nextAnonymousId ?? row.id;
+  // §5.3 emission point 2 (canonical-key flip): when the key flips, the OLD key
+  // is folded into the NEW one. MF-3 gate — only emit a merge when `oldKey` was
+  // an anonymous/uuid key (never an `external_id` being superseded; that is the
+  // twin case, OQ-1). In practice a flip in fillInLink only fires when the row
+  // had NO external_id (attaching one never happens to an already-external row),
+  // so `oldKey` is structurally always anon/uuid here — the explicit gate guards
+  // the invariant regardless.
+  let mergedKeys: string[] | undefined;
+  let mergedIdentifiedKeys: string[] | undefined;
   if (newKey !== oldKey) {
     const updatedRow: ContactRow = {
       ...row,
@@ -521,6 +570,14 @@ async function fillInLink(
       email: (set.email as string | undefined) ?? row.email,
     };
     await repointOwnHistory(tx, oldKey, newKey, updatedRow);
+
+    const oldKeyWasExternalId =
+      row.externalId != null && oldKey === row.externalId;
+    if (oldKeyWasExternalId) {
+      mergedIdentifiedKeys = [oldKey];
+    } else {
+      mergedKeys = [oldKey];
+    }
   }
 
   for (const key of promoted) {
@@ -540,7 +597,7 @@ async function fillInLink(
 
   // `newKey` IS the post-fill canonical key (external_id ?? anonymous_id ?? id) —
   // the same value the old read-back derived.
-  return { id: row.id, resolvedKey: newKey };
+  return { id: row.id, resolvedKey: newKey, mergedKeys, mergedIdentifiedKeys };
 }
 
 /**
@@ -551,10 +608,22 @@ async function mergeContacts(
   tx: Tx,
   candidates: ContactRow[],
   ctx: ResolveCtx,
-): Promise<{ id: string; resolvedKey: string }> {
+): Promise<{
+  id: string;
+  resolvedKey: string;
+  mergedKeys?: string[];
+  mergedIdentifiedKeys?: string[];
+}> {
   const { survivor, losers } = pickSurvivor(candidates);
   const survivorKey = contactKey(survivor);
 
+  // §5.3 emission point 1 (collide-MERGE) accumulators. MF-2: a loser's
+  // anonymous/uuid key is SAFE to absorb (it never identified a PostHog person);
+  // a loser's `external_id` is an already-identified person PostHog refuses to
+  // merge on the safe path — it is recorded as the twin residual, NEVER aliased.
+  const safeLoserKeys: string[] = [];
+  const identifiedLoserKeys: string[] = [];
+
   for (const loser of losers) {
     const loserStrKeys = [loser.externalId, loser.anonymousId, loser.id].filter(
       (k): k is string => Boolean(k),
@@ -563,6 +632,19 @@ async function mergeContacts(
     // anonymous id (its user_id rows were keyed on contacts.id).
     const loserKeysToRewrite = loserStrKeys;
 
+    // MF-2 split: the SAFE-to-absorb key is the loser's anonymous/uuid key —
+    // `loser.anonymousId`, or `loser.id` ONLY when the loser was never
+    // identified (no external_id). When the loser HAS an external_id, that
+    // external_id was its canonical key, so its events were captured under it
+    // (identified) → residual; `loser.id` never carried events in that case, so
+    // there is no safe key to alias from it.
+    if (loser.externalId) {
+      identifiedLoserKeys.push(loser.externalId);
+      if (loser.anonymousId) safeLoserKeys.push(loser.anonymousId);
+    } else {
+      safeLoserKeys.push(loser.anonymousId ?? loser.id);
+    }
+
     // (ii) user_events.user_id rewrite.
     await tx
       .update(userEvents)
@@ -703,8 +785,16 @@ async function mergeContacts(
   }
 
   // `newSurvivorKey` IS the post-merge canonical key of the survivor — the same
-  // value the old read-back derived for the merged row.
-  return { id: survivor.id, resolvedKey: newSurvivorKey };
+  // value the old read-back derived for the merged row. The merge folds every
+  // loser key into it, so callers fan out `mergeAnalyticsIdentities` aliasing
+  // each SAFE loser key into `newSurvivorKey` (§5.3 emission point 1).
+  return {
+    id: survivor.id,
+    resolvedKey: newSurvivorKey,
+    mergedKeys: safeLoserKeys.length > 0 ? safeLoserKeys : undefined,
+    mergedIdentifiedKeys:
+      identifiedLoserKeys.length > 0 ? identifiedLoserKeys : undefined,
+  };
 }
 
 /**
@@ -1121,6 +1211,10 @@ export async function upsertContact(opts: {
   created: boolean;
   linked: boolean;
   merged: boolean;
+  /** §5.3 MF-2: safe-to-absorb loser keys folded this call (anon/uuid). */
+  mergedKeys?: string[];
+  /** §5.3 MF-2: already-identified loser keys (twin residual); never aliased. */
+  mergedIdentifiedKeys?: string[];
 }> {
   return resolveOrCreateContact({
     db: opts.db,

package/src/lib/identity-service.ts

@@ -0,0 +1,107 @@
+import type { AnalyticsProvider } from "@hogsend/core";
+import type { Database } from "@hogsend/db";
+import {
+  logResidualTwins,
+  mergeAnalyticsIdentities,
+} from "./analytics-identity.js";
+import { resolveOrCreateContact } from "./contacts.js";
+import type { Logger } from "./logger.js";
+
+/**
+ * Args for {@link IdentityService.linkContact} — the same identity-attach inputs
+ * `resolveOrCreateContact` accepts (at least one of `userId`/`email`/
+ * `anonymousId`/`discordId` is required by the resolver), minus the `db` (the
+ * service closes over the container's db).
+ */
+export interface LinkContactArgs {
+  userId?: string;
+  email?: string;
+  anonymousId?: string;
+  discordId?: string;
+  contactProperties?: Record<string, unknown>;
+}
+
+/**
+ * The container-held identity helper (`client.identity`). It exists so any
+ * identity-attach OUTSIDE the `/v1/events` ingest path — most notably Discord
+ * `/link` (§7), but also any consumer wiring — folds two keys into one analytics
+ * person through the SAME engine emission used by `ingestEvent` (§5.3), rather
+ * than each consumer hand-rolling its own `resolveOrCreateContact` +
+ * `mergeIdentities` plumbing (the bespoke path the spec calls out as the bug).
+ */
+export interface IdentityService {
+  /**
+   * Resolve / merge a contact AND propagate the analytics merge in one call.
+   *
+   * Wraps `resolveOrCreateContact` (the resolver stays analytics-free — it takes
+   * only `db`) then, on a collide-MERGE or canonical-key flip that absorbed an
+   * anonymous/uuid key, fans out the provider-neutral `mergeIdentities` primitive
+   * via {@link mergeAnalyticsIdentities} with `reason: "discord_link"`. MF-2:
+   * `mergedKeys` already excludes identified `external_id`s (the resolver split
+   * them out) — only the safe anon/uuid keys are aliased; the excluded
+   * identified twins surface as `identity.merge.residual_twin` for observability.
+   *
+   * The SURVIVOR RULE makes `resolvedKey` the survivor (`distinctId`) and each
+   * loser its absorbed `alias` — e.g. on a Discord `/link` that merges the
+   * discord-keyed contact into the email contact, `distinctId = resolvedKey`
+   * (survivor, email/external) and `alias = <discord-contact uuid>` (the
+   * loser's anon/uuid key the Discord-platform events were captured under).
+   *
+   * Best-effort and analytics-non-load-bearing: the merge emission never throws
+   * (the helper swallows provider errors), so a missing/incapable provider
+   * no-ops cleanly — the contact resolve still happened and is returned.
+   */
+  linkContact(args: LinkContactArgs): ReturnType<typeof resolveOrCreateContact>;
+}
+
+/**
+ * Build the {@link IdentityService} bound to a container's db + active analytics
+ * provider. `analytics` is undefined when nothing is configured (the merge
+ * emission no-ops); the resolver itself is unaffected.
+ */
+export function createIdentityService(deps: {
+  db: Database;
+  analytics?: AnalyticsProvider;
+  logger?: Logger;
+}): IdentityService {
+  const { db, analytics, logger } = deps;
+
+  return {
+    async linkContact(args) {
+      const result = await resolveOrCreateContact({ db, ...args });
+
+      const {
+        id: contactId,
+        resolvedKey,
+        mergedKeys,
+        mergedIdentifiedKeys,
+      } = result;
+
+      // §5.3 emission point 1, reused (§7): fire the analytics merge ONLY when
+      // the resolver actually folded keys this call. MF-2: `mergedKeys` carries
+      // the safe anon/uuid losers (the discord-contact uuid on a `/link` merge);
+      // identified `external_id`s are excluded by the resolver and surfaced as
+      // residual twins below — never aliased (the merge PostHog refuses, R2/R4).
+      if (mergedKeys?.length) {
+        mergeAnalyticsIdentities({
+          analytics,
+          survivorKey: resolvedKey,
+          loserKeys: mergedKeys,
+          reason: "discord_link",
+          contactId,
+          logger,
+        });
+      }
+      if (mergedIdentifiedKeys?.length) {
+        logResidualTwins({
+          survivorKey: resolvedKey,
+          identifiedLoserKeys: mergedIdentifiedKeys,
+          contactId,
+          logger,
+        });
+      }
+
+      return result;
+    },
+  };
+}

package/src/lib/identity-token.ts

@@ -8,8 +8,12 @@ import {
 /**
  * Short-lived identity token appended to tracked-link redirects as `hs_t`
  * (opt-in via TRACKING_IDENTITY_TOKEN). The landing site exchanges it at
- * `POST /v1/t/identify` for the distinct id and calls `posthog.identify` —
- * stitching the email click to the web session.
+ * `POST /v1/t/identify`, where the engine fires a SERVER-SIDE `alias` folding
+ * the caller's own anon session into the token's canonical id — stitching the
+ * click to the web session. Minted for EMAIL links by default; non-email
+ * (Discord/referral) links carry a token only when explicitly stitch-bearing
+ * (`tracked_links.distinct_id` set) — referral links are token-less by default
+ * (MF-4 anti-hijack).
  *
  * ENCRYPTED (AES-256-GCM keyed off BETTER_AUTH_SECRET), not merely signed:
  * the distinct id can fall back to an email address, and a signed-but-
@@ -18,11 +22,38 @@ import {
  * auth tag also covers integrity, so tampering fails decryption.
  */
 
+/**
+ * The only merge mode a token may authorize: fold the CALLER's own anonymous
+ * session INTO the token's canonical `distinctId`. There is deliberately no
+ * "become the subject" / overwrite mode — that is the anti-hijack invariant.
+ */
+export type IdentityTokenScope = "anon-absorb";
+
 export interface IdentityTokenPayload {
-  /** The distinct id the landing site should identify as. */
+  /**
+   * The canonical contact key the landing site should fold INTO — the ONLY
+   * ever-identified id. NEVER a per-link or anonymous id.
+   */
   distinctId: string;
-  emailSendId: string;
+  /**
+   * Where the token was minted: `"email:<sendId>"` | `"link:<linkId>"`.
+   * Referral links are excluded by default (they carry no identity token).
+   */
+  src: string;
+  /**
+   * The authorized merge mode. Only `"anon-absorb"` is ever minted. OPTIONAL on
+   * the wire for the rolling-deploy window (MF-7): a token minted by the still-old
+   * click route carries no `scope`, so `validateIdentityToken` treats a MISSING
+   * scope as `"anon-absorb"` (allow) and rejects only a PRESENT-and-wrong value.
+   */
+  scope?: IdentityTokenScope;
   exp: number;
+  /**
+   * @deprecated Alias of `src` for ONE minor (mirrors the `resendId` → `messageId`
+   * deprecation window). Old tokens carry only `emailSendId`; new email tokens
+   * carry both. Reads should prefer `src`.
+   */
+  emailSendId?: string;
 }
 
 export class InvalidIdentityTokenError extends Error {
@@ -43,11 +74,27 @@ function deriveKey(secret: string): Buffer {
 export function generateIdentityToken(opts: {
   secret: string;
   distinctId: string;
-  emailSendId: string;
+  /**
+   * Mint provenance: `"email:<sendId>"` | `"link:<linkId>"`. When omitted, falls
+   * back to `email:<emailSendId>` for the legacy email-link caller.
+   */
+  src?: string;
+  /** Defaults to `"anon-absorb"` — the only mode a token may authorize. */
+  scope?: IdentityTokenScope;
+  /**
+   * @deprecated Pass `src` instead. Kept for the one-minor deprecation window so
+   * existing email-link callers compile unchanged; mirrored into the payload's
+   * deprecated `emailSendId` field and used to synthesize `src` when `src` is
+   * absent.
+   */
+  emailSendId?: string;
   expiresInSeconds?: number;
 }): string {
+  const src = opts.src ?? (opts.emailSendId ? `email:${opts.emailSendId}` : "");
   const payload: IdentityTokenPayload = {
     distinctId: opts.distinctId,
+    src,
+    scope: opts.scope ?? "anon-absorb",
     emailSendId: opts.emailSendId,
     exp:
       Math.floor(Date.now() / 1000) +
@@ -108,5 +155,18 @@ export function validateIdentityToken(opts: {
   if (payload.exp < Math.floor(Date.now() / 1000)) {
     throw new InvalidIdentityTokenError("Token expired");
   }
+  // MF-7 — missing-scope-ALLOW. The API and worker deploy independently from
+  // the same image, so a token minted by the still-old click route carries no
+  // `scope`. Treat a MISSING scope as the only legal mode (`"anon-absorb"`);
+  // reject ONLY a present-and-wrong value. Old tokens (no `scope`, no `src`)
+  // still validate — this check never widened the required-shape gate above.
+  if (payload.scope !== undefined && payload.scope !== "anon-absorb") {
+    throw new InvalidIdentityTokenError("Unsupported token scope");
+  }
+  // Backfill `src` from the deprecated `emailSendId` for old tokens, so the one
+  // response schema (`{ distinctId, src, emailSendId? }`) is always populated.
+  if (typeof payload.src !== "string" || payload.src.length === 0) {
+    payload.src = payload.emailSendId ? `email:${payload.emailSendId}` : "";
+  }
   return payload;
 }