@hogsend/engine 0.13.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.13.1",
+  "version": "0.14.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.13.1",
-    "@hogsend/db": "^0.13.1",
-    "@hogsend/email": "^0.13.1",
-    "@hogsend/plugin-posthog": "^0.13.1",
-    "@hogsend/plugin-resend": "^0.13.1"
+    "@hogsend/core": "^0.14.0",
+    "@hogsend/db": "^0.14.0",
+    "@hogsend/email": "^0.14.0",
+    "@hogsend/plugin-posthog": "^0.14.0",
+    "@hogsend/plugin-resend": "^0.14.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.13.1"
+    "@hogsend/plugin-postmark": "^0.14.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/destinations/presets/posthog.ts

@@ -53,6 +53,41 @@ export const posthogDestination = defineDestination({
       userEmail?: string | null;
     };
     const distinctId = data.userId ?? data.to ?? data.userEmail ?? undefined;
+    // `email.action` is the semantic-link envelope: the CONSUMER's event name
+    // (data.event, e.g. "nps.submitted") is what PostHog should capture, with
+    // the author's properties flattened to the top level. Other catalog events
+    // capture under their spine name (with the optional remap).
+    if (envelope.type === "email.action") {
+      const action = envelope.data as {
+        event: string;
+        properties: Record<string, unknown> | null;
+        emailSendId: string;
+        templateKey: string | null;
+        linkId: string;
+        linkUrl: string;
+        to: string;
+        userId: string | null;
+        at: string;
+      };
+      return {
+        url: `${host}/capture/`,
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          api_key: config.apiKey,
+          event: action.event,
+          distinct_id: distinctId,
+          timestamp: envelope.timestamp,
+          properties: {
+            ...(action.properties ?? {}),
+            emailSendId: action.emailSendId,
+            templateKey: action.templateKey,
+            linkId: action.linkId,
+            $lib: "hogsend",
+          },
+        }),
+      };
+    }
     // Optional event-name remap (identity by default).
     const eventName = config.eventNames?.[envelope.type] ?? envelope.type;
     return {

package/src/index.ts

@@ -229,6 +229,13 @@ export {
 } from "./lib/redis.js";
 // --- Self-service password reset (engine-owned, self-contained email) ---
 export { sendResetPasswordEmail } from "./lib/reset-email.js";
+export {
+  type ConfirmSemanticClickInput,
+  type ConfirmSemanticClickResult,
+  confirmSemanticClick,
+  SEMANTIC_BURST_DISTINCT_LINKS,
+  SEMANTIC_BURST_WINDOW_MS,
+} from "./lib/semantic-click.js";
 export { type MountStudioResult, mountStudio } from "./lib/studio.js";
 export {
   type ResolveTimezoneInput,

package/src/journeys/journey-context.ts

@@ -22,11 +22,17 @@ import type {
   IfPast,
   JourneyContext,
   TimeOfDayBuilder,
+  WaitForEventResult,
   Weekday,
   WhenBuilder,
 } from "@hogsend/core/types";
-import { type Database, emailSends, journeyStates } from "@hogsend/db";
-import { and, count, eq, max, notInArray } from "drizzle-orm";
+import {
+  type Database,
+  emailSends,
+  journeyStates,
+  userEvents,
+} from "@hogsend/db";
+import { and, count, desc, eq, gte, max, notInArray } from "drizzle-orm";
 import { checkEmailPreferences } from "../lib/enrollment-guards.js";
 import { ingestEvent } from "../lib/ingestion.js";
 import type { Logger } from "../lib/logger.js";
@@ -206,7 +212,8 @@ export function createJourneyContext(
     event: string,
     timeout: DurationObject,
     nodeId: string,
-  ): Promise<{ timedOut: boolean }> => {
+    lookback?: DurationObject,
+  ): Promise<WaitForEventResult> => {
     // Reject a timeout longer than the journey task's executionTimeout up front
     // so it fails fast at authoring time. (Eviction-capable engines may allow
     // longer wall-clock waits, but we cap to the configured ceiling — raise
@@ -217,6 +224,41 @@ export function createJourneyContext(
       );
     }
 
+    // Optional lookback: the durable wait only matches events pushed AFTER it
+    // is established, so an answer landing in the gap (between a send and its
+    // wait, or between two back-to-back waits) would otherwise be permanently
+    // unobservable — its first-answer idempotency key is already claimed and
+    // can never re-push. A recent matching user_events row resolves the wait
+    // immediately, payload included.
+    if (lookback) {
+      const since = new Date(Date.now() - durationToMs(lookback));
+      const recent = await db
+        .select({ properties: userEvents.properties })
+        .from(userEvents)
+        .where(
+          and(
+            eq(userEvents.userId, userId),
+            eq(userEvents.event, event),
+            gte(userEvents.occurredAt, since),
+          ),
+        )
+        .orderBy(desc(userEvents.occurredAt))
+        .limit(1);
+      const row = recent[0];
+      if (row) {
+        const scalars = Object.fromEntries(
+          Object.entries(row.properties ?? {}).filter(
+            ([, v]) =>
+              typeof v === "string" ||
+              typeof v === "number" ||
+              typeof v === "boolean" ||
+              v === null,
+          ),
+        ) as NonNullable<WaitForEventResult["properties"]>;
+        return { timedOut: false, properties: scalars };
+      }
+    }
+
     await enterWait(nodeId);
 
     // Wait for the user-scoped event or the timeout. The event branch filters on
@@ -241,9 +283,34 @@ export function createJourneyContext(
       {}) as Record<string, unknown>;
     const timedOut = !("event" in fired);
 
+    // Surface the matched event's payload (best-effort). The engine returns
+    // matches as `[{ id, data }]` where `data` is the pushed ingest payload
+    // ({ userId, userEmail, properties }); the pre-eviction path may hand the
+    // payload back un-wrapped — tolerate both, mirroring the CREATE-strip.
+    let properties: WaitForEventResult["properties"];
+    if (!timedOut) {
+      const matches = fired.event;
+      const first = Array.isArray(matches) ? matches[0] : matches;
+      const payload =
+        first && typeof first === "object" && "data" in first
+          ? (first as { data?: unknown }).data
+          : first;
+      const candidate =
+        payload && typeof payload === "object" && "properties" in payload
+          ? (payload as { properties?: unknown }).properties
+          : undefined;
+      if (
+        candidate &&
+        typeof candidate === "object" &&
+        !Array.isArray(candidate)
+      ) {
+        properties = candidate as NonNullable<WaitForEventResult["properties"]>;
+      }
+    }
+
     await resumeFromWait();
 
-    return { timedOut };
+    return { timedOut, ...(properties ? { properties } : {}) };
   };
 
   return {
@@ -275,11 +342,12 @@ export function createJourneyContext(
       );
     },
 
-    async waitForEvent({ event, timeout, label }) {
+    async waitForEvent({ event, timeout, label, lookback }) {
       return performWaitForEvent(
         event,
         timeout,
         label ?? `wait-event:${event}`,
+        lookback,
       );
     },
 

package/src/lib/ingestion.ts

@@ -68,6 +68,7 @@ export async function ingestEvent(opts: {
 
   // (2) Idempotency dedup + `user_events` insert keyed on the resolved key, with
   // ONLY eventProperties in the properties bag (D2).
+  let idempotentInsertId: string | undefined;
   if (event.idempotencyKey) {
     const result = await db
       .insert(userEvents)
@@ -86,6 +87,7 @@ export async function ingestEvent(opts: {
     if (result.length === 0) {
       return { stored: false, exits: [] };
     }
+    idempotentInsertId = result[0]?.id;
   } else {
     await db.insert(userEvents).values({
       userId: resolvedKey,
@@ -109,7 +111,13 @@ export async function ingestEvent(opts: {
 
   // (4) Hatchet push + (5) checkExits, both keyed on the resolved key. The push
   // payload wire key STAYS `properties` (bucket tests assert on it — risk 9).
-  const [, exits] = await Promise.all([
+  //
+  // An idempotency claim must not outlive a FAILED publish: journeys were never
+  // notified, and the consumed key would make every retry a silent no-op (the
+  // event becomes permanently invisible to journeys/destinations). So on a push
+  // failure the just-inserted row is compensating-deleted before rethrowing —
+  // the caller's retry (same key) can then re-claim and re-publish.
+  const [pushResult, exitsResult] = await Promise.allSettled([
     hatchet.events.push(event.event, {
       userId: resolvedKey,
       userEmail: event.userEmail ?? "",
@@ -121,6 +129,29 @@ export async function ingestEvent(opts: {
       properties: event.eventProperties,
     }),
   ]);
+  if (pushResult.status === "rejected") {
+    if (idempotentInsertId) {
+      try {
+        await db
+          .delete(userEvents)
+          .where(eq(userEvents.id, idempotentInsertId));
+      } catch (cleanupErr) {
+        logger.warn("ingestEvent: failed to roll back idempotency claim", {
+          event: event.event,
+          idempotencyKey: event.idempotencyKey,
+          error:
+            cleanupErr instanceof Error
+              ? cleanupErr.message
+              : String(cleanupErr),
+        });
+      }
+    }
+    throw pushResult.reason;
+  }
+  if (exitsResult.status === "rejected") {
+    throw exitsResult.reason;
+  }
+  const exits = exitsResult.value;
 
   // (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
   // Promise.all above: its property eval reads contact state ⊕ this-ingest

package/src/lib/outbound.ts

@@ -90,6 +90,23 @@ export interface OutboundPayloads {
   "email.delivered": EmailEventPayload;
   "email.opened": EmailEventPayload;
   "email.clicked": EmailEventPayload & { linkUrl?: string; linkId?: string };
+  /**
+   * A SEMANTIC link answered — the in-email action event (consumer-named, e.g.
+   * "nps.submitted"). Emitted at most once per (send, event name): first
+   * answer wins, scanner bursts are suppressed. `event`/`properties` carry the
+   * consumer semantics; the rest is send context.
+   */
+  "email.action": {
+    event: string;
+    properties: Record<string, unknown> | null;
+    emailSendId: string;
+    templateKey: string | null;
+    userId: string | null;
+    to: string;
+    at: string;
+    linkId: string;
+    linkUrl: string;
+  };
   "email.bounced": EmailEventPayload & {
     bounceType?: string;
     bounceReason?: string;

package/src/lib/seed-posthog-destination.ts

@@ -18,6 +18,7 @@ const POSTHOG_FUNNEL_EVENTS = [
   "email.delivered",
   "email.opened",
   "email.clicked",
+  "email.action",
   "email.bounced",
   "email.complained",
 ] as const;
@@ -51,7 +52,11 @@ export async function seedPostHogDestination(opts: {
     );
 
     const existing = await tx
-      .select({ id: webhookEndpoints.id })
+      .select({
+        id: webhookEndpoints.id,
+        url: webhookEndpoints.url,
+        eventTypes: webhookEndpoints.eventTypes,
+      })
       .from(webhookEndpoints)
       .where(
         and(
@@ -61,7 +66,34 @@ export async function seedPostHogDestination(opts: {
       )
       .limit(1);
 
-    if (existing.length > 0) {
+    const found = existing[0];
+    if (found) {
+      // Reconcile the ENGINE-seeded row (identified by its sentinel URL) when
+      // the funnel list has grown since it was inserted — its stored
+      // eventTypes are a snapshot, and emitOutbound matches by jsonb
+      // containment, so a pre-upgrade row would silently never receive newer
+      // events (e.g. email.action). Operator-created endpoints are left
+      // untouched: subscriber-chooses-events is the contract there.
+      if (found.url === "posthog://capture") {
+        const current = Array.isArray(found.eventTypes)
+          ? (found.eventTypes as string[])
+          : [];
+        const missing = POSTHOG_FUNNEL_EVENTS.filter(
+          (e) => !current.includes(e),
+        );
+        if (missing.length > 0) {
+          await tx
+            .update(webhookEndpoints)
+            .set({
+              eventTypes: [...current, ...missing],
+              updatedAt: new Date(),
+            })
+            .where(eq(webhookEndpoints.id, found.id));
+          logger.info("Reconciled seeded PostHog destination event types", {
+            added: missing,
+          });
+        }
+      }
       return { seeded: false };
     }
 

package/src/lib/semantic-click.ts

@@ -0,0 +1,194 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import {
+  type Database,
+  linkClicks,
+  trackedLinks,
+  userEvents,
+} from "@hogsend/db";
+import { and, countDistinct, eq, gte, isNull, lte } from "drizzle-orm";
+import type { Logger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
+import {
+  pushTrackingEvent,
+  resolveEmailSendContext,
+} from "./tracking-events.js";
+
+/**
+ * Scanner-burst window: SafeLinks/Proofpoint-style scanners follow EVERY link
+ * in an email within seconds of delivery; humans don't. Confirmation of a
+ * semantic answer is DEFERRED until the window around the candidate click has
+ * fully elapsed, so the gate sees the WHOLE burst — including clicks that land
+ * AFTER the candidate. An inline check could never suppress a scanner's first
+ * click (the burst isn't visible yet); this one can.
+ */
+export const SEMANTIC_BURST_WINDOW_MS = 30_000;
+export const SEMANTIC_BURST_DISTINCT_LINKS = 3;
+
+// Type alias (NOT interface) so it picks up an implicit index signature and
+// satisfies Hatchet's JsonObject task-input constraint.
+export type ConfirmSemanticClickInput = {
+  trackedLinkId: string;
+  /** ISO instant of the candidate click. */
+  clickedAt: string;
+};
+
+export type ConfirmSemanticClickResult =
+  | { status: "confirmed"; event: string }
+  | { status: "suppressed"; distinctLinks: number }
+  /** Another link's answer claimed this send's slot first. */
+  | { status: "lost" }
+  | { status: "skipped"; reason: string };
+
+export interface ConfirmSemanticClickDeps {
+  db: Database;
+  hatchet: HatchetClient;
+  registry: JourneyRegistry;
+  logger: Logger;
+}
+
+/**
+ * Confirm (or suppress) one provisional semantic-link answer. Idempotent end
+ * to end, so the wrapping Hatchet task can retry safely:
+ *
+ *  1. Sleep out the remainder of the burst window past the candidate click.
+ *  2. Count DISTINCT links of the send clicked inside the window around the
+ *     candidate — at/over the threshold the whole burst is scanner traffic
+ *     and the answer is suppressed (the raw clicks stay recorded).
+ *  3. Claim the send's answer slot via `ingestEvent` with the
+ *     `sem:<emailSendId>:<event>` idempotency key (first answer wins; a
+ *     failed Hatchet publish rolls the claim back inside `ingestEvent`, so a
+ *     retry re-claims).
+ *  4. If we claimed (or a crashed earlier attempt of THIS link did — detected
+ *     by the stored row's `linkId`), stamp `semanticEmittedAt` and emit the
+ *     `email.action` outbound envelope with the same key as `dedupeKey`, so
+ *     re-runs are per-endpoint no-ops.
+ */
+export async function confirmSemanticClick(
+  deps: ConfirmSemanticClickDeps,
+  input: ConfirmSemanticClickInput,
+): Promise<ConfirmSemanticClickResult> {
+  const { db, hatchet, registry, logger } = deps;
+
+  const clickedAtMs = Date.parse(input.clickedAt);
+  if (Number.isNaN(clickedAtMs)) {
+    return { status: "skipped", reason: "bad_clicked_at" };
+  }
+
+  const rows = await db
+    .select({
+      id: trackedLinks.id,
+      emailSendId: trackedLinks.emailSendId,
+      originalUrl: trackedLinks.originalUrl,
+      event: trackedLinks.event,
+      eventProperties: trackedLinks.eventProperties,
+    })
+    .from(trackedLinks)
+    .where(eq(trackedLinks.id, input.trackedLinkId))
+    .limit(1);
+  const link = rows[0];
+  if (!link?.event) {
+    return { status: "skipped", reason: "not_semantic" };
+  }
+  const semanticEvent = link.event;
+
+  // (1) Let the burst window close before judging the click.
+  const remainingMs = clickedAtMs + SEMANTIC_BURST_WINDOW_MS - Date.now();
+  if (remainingMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, remainingMs));
+  }
+
+  // (2) Whole-burst check: distinct links of this send clicked in the window
+  // AROUND the candidate (before AND after — the deferral is what makes the
+  // "after" half visible).
+  const windowStart = new Date(clickedAtMs - SEMANTIC_BURST_WINDOW_MS);
+  const windowEnd = new Date(clickedAtMs + SEMANTIC_BURST_WINDOW_MS);
+  const burst = await db
+    .select({ n: countDistinct(linkClicks.trackedLinkId) })
+    .from(linkClicks)
+    .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
+    .where(
+      and(
+        eq(trackedLinks.emailSendId, link.emailSendId),
+        gte(linkClicks.clickedAt, windowStart),
+        lte(linkClicks.clickedAt, windowEnd),
+      ),
+    );
+  const distinctLinks = burst[0]?.n ?? 0;
+  if (distinctLinks >= SEMANTIC_BURST_DISTINCT_LINKS) {
+    logger.warn("Semantic answer suppressed: scanner-like click burst", {
+      emailSendId: link.emailSendId,
+      linkId: link.id,
+      event: semanticEvent,
+      distinctLinks,
+    });
+    return { status: "suppressed", distinctLinks };
+  }
+
+  const ctx = await resolveEmailSendContext(db, link.emailSendId);
+  if (!ctx) {
+    return { status: "skipped", reason: "no_send_context" };
+  }
+
+  // (3) Claim the answer slot. Duplicate key → stored=false BEFORE the Hatchet
+  // push, so journeys/destinations see at most one answer per (send, event).
+  const semKey = `sem:${link.emailSendId}:${semanticEvent}`;
+  const result = await pushTrackingEvent({
+    db,
+    hatchet,
+    registry,
+    logger,
+    event: semanticEvent,
+    emailSendId: link.emailSendId,
+    properties: {
+      ...(link.eventProperties ?? {}),
+      linkId: link.id,
+    },
+    resolvedContext: ctx,
+    idempotencyKey: semKey,
+  });
+
+  // (4) Claimer determination. stored=false usually means another link won —
+  // but if the stored row carries THIS link's id, it is a crashed earlier
+  // attempt of this very confirmation, and the (idempotent) tail must re-run.
+  let isClaimer = result?.stored ?? false;
+  if (!isClaimer) {
+    const existing = await db
+      .select({ properties: userEvents.properties })
+      .from(userEvents)
+      .where(eq(userEvents.idempotencyKey, semKey))
+      .limit(1);
+    isClaimer = existing[0]?.properties?.linkId === link.id;
+    if (!isClaimer) {
+      return { status: "lost" };
+    }
+  }
+
+  await db
+    .update(trackedLinks)
+    .set({ semanticEmittedAt: new Date(), updatedAt: new Date() })
+    .where(
+      and(eq(trackedLinks.id, link.id), isNull(trackedLinks.semanticEmittedAt)),
+    );
+
+  await emitOutbound({
+    db,
+    hatchet,
+    logger,
+    event: "email.action",
+    dedupeKey: semKey,
+    payload: {
+      event: semanticEvent,
+      properties: link.eventProperties ?? null,
+      emailSendId: link.emailSendId,
+      templateKey: ctx.templateKey ?? null,
+      userId: ctx.userId ?? null,
+      to: ctx.to ?? ctx.userEmail ?? "",
+      at: new Date().toISOString(),
+      linkId: link.id,
+      linkUrl: link.originalUrl,
+    },
+  });
+
+  return { status: "confirmed", event: semanticEvent };
+}

package/src/lib/tracking-events.ts

@@ -2,7 +2,7 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
 import { eq } from "drizzle-orm";
-import { ingestEvent } from "./ingestion.js";
+import { type IngestResult, ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";
 
 interface EmailSendContext {
@@ -122,6 +122,13 @@ export interface PushTrackingEventOpts {
    * lazily.
    */
   resolvedContext?: EmailSendContext | null;
+  /**
+   * Threaded straight into `ingestEvent` — a duplicate key returns
+   * `{ stored: false }` BEFORE the Hatchet push, so journeys never see the
+   * duplicate. Semantic link answers use `sem:<emailSendId>:<event>` for
+   * first-answer-per-send semantics.
+   */
+  idempotencyKey?: string;
 }
 
 /**
@@ -136,14 +143,14 @@ export interface PushTrackingEventOpts {
  */
 export async function pushTrackingEvent(
   opts: PushTrackingEventOpts,
-): Promise<void> {
+): Promise<IngestResult | undefined> {
   const { db, hatchet, registry, logger, event, emailSendId } = opts;
 
   const ctx =
     opts.resolvedContext !== undefined
       ? opts.resolvedContext
       : await resolveEmailSendContext(db, emailSendId);
-  if (!ctx) return;
+  if (!ctx) return undefined;
 
   const properties: Record<string, unknown> = {
     emailSendId,
@@ -151,7 +158,7 @@ export async function pushTrackingEvent(
     ...opts.properties,
   };
 
-  await ingestEvent({
+  return await ingestEvent({
     db,
     registry,
     hatchet,
@@ -161,6 +168,7 @@ export async function pushTrackingEvent(
       userId: ctx.userId,
       userEmail: ctx.userEmail,
       eventProperties: properties,
+      idempotencyKey: opts.idempotencyKey,
     },
   });
 }

package/src/lib/tracking.ts

@@ -1,14 +1,127 @@
+import { randomUUID } from "node:crypto";
 import type { Database } from "@hogsend/db";
 import { trackedLinks } from "@hogsend/db";
+import {
+  EMAIL_ACTION_EVENT_ATTR,
+  EMAIL_ACTION_PROPS_ATTR,
+} from "@hogsend/email";
 
-const HREF_RE = /href="(https?:\/\/[^"]+)"/gi;
+const ANCHOR_RE = /<a\b[^>]*>/gi;
+const HREF_RE = /\bhref="(https?:\/\/[^"]+)"/i;
+const EVENT_ATTR_RE = new RegExp(
+  `\\b${EMAIL_ACTION_EVENT_ATTR}="([^"]*)"`,
+  "i",
+);
+const PROPS_ATTR_RE = new RegExp(
+  `\\b${EMAIL_ACTION_PROPS_ATTR}="([^"]*)"`,
+  "i",
+);
+const STRIP_SEMANTIC_ATTRS_RE = new RegExp(
+  `\\s*(?:${EMAIL_ACTION_EVENT_ATTR}|${EMAIL_ACTION_PROPS_ATTR})="[^"]*"`,
+  "gi",
+);
 
 const SKIP_PATTERNS = ["/v1/email/unsubscribe", "/v1/email/preferences"];
 
+// Engine-owned event vocabularies (both `email.opened` dot-style and
+// `journey:completed` colon-style exist) — a consumer semantic event in these
+// namespaces would corrupt insights or trigger engine-internal logic.
+const RESERVED_EVENT_NAME_RE = /^(?:email|journey|bucket|contact)[.:]/;
+
+// Semantic payloads re-emit on every answer and persist indefinitely — keep
+// them small and scalar (non-scalars don't survive the Hatchet wire anyway).
+const MAX_PROPS_JSON_LENGTH = 2048;
+
 function shouldSkipUrl(url: string): boolean {
   return SKIP_PATTERNS.some((pattern) => url.includes(pattern));
 }
 
+// React entity-escapes attribute values at render time. Decode the five
+// entities it emits; `&amp;` LAST so `&amp;quot;` round-trips to `&quot;`.
+function decodeAttributeValue(value: string): string {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&#x27;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+interface SemanticAttrs {
+  event: string;
+  /** Raw (encoded) props attribute — part of the dedupe key. */
+  propsRaw: string | null;
+  properties: Record<string, unknown> | null;
+}
+
+/**
+ * Extract + validate the semantic metadata off one `<a …>` tag. Returns null
+ * for a plain link. Throws on author error — a semantic link that can't be
+ * honored must fail the SEND loudly, not degrade into a silent plain link.
+ */
+function parseSemanticAttrs(tag: string): SemanticAttrs | null {
+  const eventMatch = tag.match(EVENT_ATTR_RE);
+  if (!eventMatch) return null;
+
+  const event = decodeAttributeValue(eventMatch[1] ?? "").trim();
+  if (!event) {
+    throw new Error(`Semantic link has an empty ${EMAIL_ACTION_EVENT_ATTR}`);
+  }
+  if (RESERVED_EVENT_NAME_RE.test(event)) {
+    throw new Error(
+      `Semantic link event "${event}" uses a reserved namespace (email/journey/bucket/contact)`,
+    );
+  }
+
+  const propsMatch = tag.match(PROPS_ATTR_RE);
+  if (!propsMatch) return { event, propsRaw: null, properties: null };
+
+  const propsRaw = propsMatch[1] ?? "";
+  const decoded = decodeAttributeValue(propsRaw);
+  if (decoded.length > MAX_PROPS_JSON_LENGTH) {
+    throw new Error(
+      `Semantic link "${event}" properties exceed ${MAX_PROPS_JSON_LENGTH} chars`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    throw new Error(
+      `Semantic link "${event}" has unparseable ${EMAIL_ACTION_PROPS_ATTR}`,
+    );
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      `Semantic link "${event}" properties must be a JSON object`,
+    );
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    const t = typeof value;
+    if (value !== null && t !== "string" && t !== "number" && t !== "boolean") {
+      throw new Error(
+        `Semantic link "${event}" property "${key}" must be a scalar (string/number/boolean/null)`,
+      );
+    }
+  }
+
+  return {
+    event,
+    propsRaw,
+    properties: parsed as Record<string, unknown>,
+  };
+}
+
+// One tracked_links row per distinct (url, event, props) tuple: identical
+// semantic links share a row; the same URL under DIFFERENT events/props must
+// NOT collapse (the old URL-only dedupe would merge "yes" and "no" answers
+// that point at the same thanks page).
+function linkKey(url: string, semantic: SemanticAttrs | null): string {
+  const sep = String.fromCharCode(0);
+  return [url, semantic?.event ?? "", semantic?.propsRaw ?? ""].join(sep);
+}
+
 export async function rewriteLinks(opts: {
   html: string;
   emailSendId: string;
@@ -17,32 +130,51 @@ export async function rewriteLinks(opts: {
 }): Promise<string> {
   const { html, emailSendId, baseUrl, db } = opts;
 
-  const uniqueUrls = new Set<string>();
+  const pending = new Map<
+    string,
+    { id: string; url: string; semantic: SemanticAttrs | null }
+  >();
+
+  for (const match of html.matchAll(ANCHOR_RE)) {
+    const tag = match[0];
+    const url = tag.match(HREF_RE)?.[1];
+    const semantic = parseSemanticAttrs(tag);
 
-  for (const match of html.matchAll(HREF_RE)) {
-    const url = match[1];
-    if (url && !shouldSkipUrl(url)) {
-      uniqueUrls.add(url);
+    if (!url || shouldSkipUrl(url)) {
+      if (semantic) {
+        throw new Error(
+          `Semantic link "${semantic.event}" needs an absolute http(s) href outside unsubscribe/preference URLs`,
+        );
+      }
+      continue;
     }
-  }
 
-  if (uniqueUrls.size === 0) return html;
+    const key = linkKey(url, semantic);
+    if (!pending.has(key)) {
+      pending.set(key, { id: randomUUID(), url, semantic });
+    }
+  }
 
-  const urlList = [...uniqueUrls];
-  const rows = await db
-    .insert(trackedLinks)
-    .values(urlList.map((url) => ({ emailSendId, originalUrl: url })))
-    .returning({ id: trackedLinks.id, originalUrl: trackedLinks.originalUrl });
+  if (pending.size === 0) return html;
 
-  const urlToId = new Map<string, string>();
-  for (const row of rows) {
-    urlToId.set(row.originalUrl, row.id);
-  }
+  await db.insert(trackedLinks).values(
+    [...pending.values()].map((link) => ({
+      id: link.id,
+      emailSendId,
+      originalUrl: link.url,
+      event: link.semantic?.event,
+      eventProperties: link.semantic?.properties ?? undefined,
+    })),
+  );
 
-  return html.replace(HREF_RE, (full, url: string) => {
-    if (shouldSkipUrl(url)) return full;
-    const linkId = urlToId.get(url);
-    return linkId ? `href="${baseUrl}/v1/t/c/${linkId}"` : full;
+  return html.replace(ANCHOR_RE, (tag) => {
+    const url = tag.match(HREF_RE)?.[1];
+    if (!url || shouldSkipUrl(url)) return tag;
+    const link = pending.get(linkKey(url, parseSemanticAttrs(tag)));
+    if (!link) return tag;
+    return tag
+      .replace(HREF_RE, `href="${baseUrl}/v1/t/c/${link.id}"`)
+      .replace(STRIP_SEMANTIC_ATTRS_RE, "");
   });
 }
 

package/src/lib/webhook-signing.ts

@@ -25,7 +25,7 @@ import { Webhook } from "svix";
  */
 
 /**
- * The 13-event catalog — the SINGLE source of truth (schema, routes, client,
+ * The 14-event catalog — the SINGLE source of truth (schema, routes, client,
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
  */
@@ -38,6 +38,7 @@ export const WEBHOOK_EVENT_TYPES = [
   "email.delivered",
   "email.opened",
   "email.clicked",
+  "email.action",
   "email.bounced",
   "email.complained",
   "journey.completed",

package/src/routes/tracking/click.ts

@@ -8,6 +8,7 @@ import {
   pushTrackingEvent,
   resolveEmailSendContext,
 } from "../../lib/tracking-events.js";
+import { confirmSemanticClickTask } from "../../workflows/confirm-semantic-click.js";
 
 const clickRoute = createRoute({
   method: "get",
@@ -36,6 +37,8 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
         id: trackedLinks.id,
         originalUrl: trackedLinks.originalUrl,
         emailSendId: trackedLinks.emailSendId,
+        event: trackedLinks.event,
+        eventProperties: trackedLinks.eventProperties,
       })
       .from(trackedLinks)
       .where(eq(trackedLinks.id, id))
@@ -85,6 +88,26 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
 
     const { hatchet, registry, logger } = c.get("container");
 
+    // SEMANTIC link: the click is a PROVISIONAL answer. Confirmation is
+    // deferred past the scanner-burst window (a Hatchet task) so the gate can
+    // see the WHOLE burst — an inline check could never suppress a scanner's
+    // first click. The task claims the send's answer slot (first answer wins)
+    // and emits the consumer event + email.action outbound.
+    if (link.event) {
+      void confirmSemanticClickTask
+        .runNoWait({
+          trackedLinkId: link.id,
+          clickedAt: new Date().toISOString(),
+        })
+        .catch((err: unknown) => {
+          logger.warn("Failed to enqueue semantic click confirmation", {
+            linkId: link.id,
+            event: link.event,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        });
+    }
+
     // Resolve the send context ONCE (off the response path) and feed both the
     // re-ingest and the PER-HIT outbound emit — avoiding a duplicate
     // `resolveEmailSendContext` read on the click hot path. NO `dedupeKey`: a

package/src/worker.ts

@@ -16,6 +16,7 @@ import {
 } from "./workflows/bucket-backfill.js";
 import { bucketReconcileTask } from "./workflows/bucket-reconcile.js";
 import { checkAlertsTask } from "./workflows/check-alerts.js";
+import { confirmSemanticClickTask } from "./workflows/confirm-semantic-click.js";
 import {
   deliverWebhookTask,
   reapDueWebhookDeliveriesTask,
@@ -81,6 +82,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     reapStuckCampaignsTask,
     deliverWebhookTask,
     reapDueWebhookDeliveriesTask,
+    confirmSemanticClickTask,
     checkAlertsTask,
     bucketReconcileTask,
     bucketBackfillTask,

package/src/workflows/confirm-semantic-click.ts

@@ -0,0 +1,37 @@
+import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
+import { getDb } from "../lib/db.js";
+import { hatchet } from "../lib/hatchet.js";
+import { createLogger } from "../lib/logger.js";
+import {
+  type ConfirmSemanticClickInput,
+  confirmSemanticClick,
+} from "../lib/semantic-click.js";
+
+/**
+ * Deferred confirmation of a semantic-link answer, enqueued per candidate
+ * click by the click route. The deferral (≈ the burst window, 30s) is the
+ * point: an inline gate can never suppress a scanner's FIRST click because
+ * the rest of the burst hasn't happened yet — this task judges the click with
+ * the whole window visible on both sides.
+ *
+ * Retries are safe: the claim is an idempotency-keyed `user_events` insert
+ * whose failed-publish path rolls back inside `ingestEvent`, the stamp is
+ * `IS NULL`-guarded, and the outbound emit carries a `dedupeKey`. Self-
+ * bootstraps deps from the process (cron-style; no request container).
+ */
+export const confirmSemanticClickTask = hatchet.task({
+  name: "confirm-semantic-click",
+  retries: 3,
+  executionTimeout: "90s",
+  fn: async (input: ConfirmSemanticClickInput) => {
+    return confirmSemanticClick(
+      {
+        db: getDb(),
+        hatchet,
+        registry: getJourneyRegistrySingleton(),
+        logger: createLogger(process.env.LOG_LEVEL ?? "info"),
+      },
+      input,
+    );
+  },
+});