@hogsend/engine 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -35,11 +35,11 @@
     "resend": "^6.12.3",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.3.0",
-    "@hogsend/email": "^0.3.0",
-    "@hogsend/db": "^0.3.0",
-    "@hogsend/plugin-posthog": "^0.3.0",
-    "@hogsend/plugin-resend": "^0.3.0"
+    "@hogsend/core": "^0.4.0",
+    "@hogsend/db": "^0.4.0",
+    "@hogsend/email": "^0.4.0",
+    "@hogsend/plugin-posthog": "^0.4.0",
+    "@hogsend/plugin-resend": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/index.ts

@@ -54,6 +54,7 @@ export {
   type DefinedJourney,
   defineJourney,
 } from "./journeys/define-journey.js";
+export { JourneyExitedError } from "./journeys/errors.js";
 export { createJourneyContext } from "./journeys/journey-context.js";
 export {
   buildJourneyRegistry,

package/src/journeys/constants.ts

@@ -0,0 +1,14 @@
+/**
+ * Max active execution time configured on every journey durable task
+ * (`executionTimeout`). It is the single source of truth shared by
+ * `define-journey` (the task config) and `journey-context` (the `waitForEvent`
+ * timeout ceiling) so the two never drift.
+ *
+ * NOTE: on eviction-capable Hatchet engines (>= v0.80.0) a durable wait evicts
+ * the task and frees the worker slot, so a very long wall-clock wait MAY exceed
+ * this. We still treat it as our ceiling: `waitForEvent` rejects timeouts beyond
+ * it so they fail fast at authoring time rather than risk a mid-wait
+ * termination. Raise this to allow longer waits.
+ */
+export const JOURNEY_EXECUTION_TIMEOUT_HOURS = 720;
+export const JOURNEY_EXECUTION_TIMEOUT = `${JOURNEY_EXECUTION_TIMEOUT_HOURS}h`;

package/src/journeys/define-journey.ts

@@ -6,7 +6,7 @@ import type {
   JourneyUser,
 } from "@hogsend/core/types";
 import { contacts, journeyConfigs, journeyStates } from "@hogsend/db";
-import { and, eq, inArray } from "drizzle-orm";
+import { and, eq, inArray, notInArray } from "drizzle-orm";
 import { getDb } from "../lib/db.js";
 import {
   checkEmailPreferences,
@@ -17,7 +17,9 @@ import { createLogger } from "../lib/logger.js";
 import { getPostHog } from "../lib/posthog.js";
 import { resolveTimezoneWithSource } from "../lib/timezone.js";
 import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
-import { createJourneyContext } from "./journey-context.js";
+import { JOURNEY_EXECUTION_TIMEOUT } from "./constants.js";
+import { JourneyExitedError } from "./errors.js";
+import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
 import { getJourneyRegistrySingleton } from "./registry-singleton.js";
 
 const logger = createLogger(process.env.LOG_LEVEL);
@@ -43,7 +45,7 @@ export function defineJourney(options: {
   const task = hatchet.durableTask({
     name: `journey-${meta.id}`,
     onEvents: [meta.trigger.event],
-    executionTimeout: "720h",
+    executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
     retries: 0,
     fn: async (input: EventPayloadInput, hatchetCtx) => {
       const db = getDb();
@@ -203,17 +205,42 @@ export function defineJourney(options: {
 
         return { stateId, status: "completed" };
       } catch (err) {
+        // The journey reached a terminal state (exitOn / cancel) while suspended
+        // in a durable wait. The state row is already terminal — stop gracefully
+        // without marking it "failed" or re-pushing a journey:failed event.
+        if (err instanceof JourneyExitedError) {
+          return { stateId, status: "exited" };
+        }
+
         const message =
           err instanceof Error ? err.message : "Unknown error during journey";
 
-        await db
+        // Mark "failed" ONLY if the row isn't already terminal. A run cancelled
+        // by exitOn (ingestEvent sets "exited" then `runs.cancel`) or by the
+        // admin route surfaces here as a Hatchet AbortError thrown from the
+        // suspended waitFor/sleepFor — NOT a JourneyExitedError. Guarding on a
+        // non-terminal status prevents clobbering that "exited" row to "failed"
+        // and emitting a spurious journey:failed event.
+        const [failed] = await db
           .update(journeyStates)
           .set({
             status: "failed",
             errorMessage: message,
             updatedAt: new Date(),
           })
-          .where(eq(journeyStates.id, stateId));
+          .where(
+            and(
+              eq(journeyStates.id, stateId),
+              notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
+            ),
+          )
+          .returning({ id: journeyStates.id });
+
+        if (!failed) {
+          // Already terminal (cancelled after exit) — swallow the cancellation
+          // so the run doesn't double-report as failed.
+          return { stateId, status: "exited" };
+        }
 
         await hatchet.events.push("journey:failed", {
           journeyId: meta.id,

package/src/journeys/errors.ts

@@ -0,0 +1,17 @@
+/**
+ * Thrown by durable wait primitives (e.g. `ctx.waitForEvent`) when the journey
+ * reached a terminal state — exited via `exitOn`, or cancelled — while it was
+ * suspended. It is a CONTROL-FLOW SIGNAL, not a failure: `defineJourney` catches
+ * it and stops the run gracefully WITHOUT marking the state `"failed"` (the row
+ * is already terminal). Consumers generally never observe it; it simply aborts
+ * `run()` before any post-wait side effect can fire.
+ */
+export class JourneyExitedError extends Error {
+  readonly stateId: string;
+
+  constructor(stateId: string) {
+    super(`Journey state ${stateId} is no longer active (exited or cancelled)`);
+    this.name = "JourneyExitedError";
+    this.stateId = stateId;
+  }
+}

package/src/journeys/journey-context.ts

@@ -1,6 +1,14 @@
-import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type {
+  Conditions,
+  HatchetClient,
+} from "@hatchet-dev/typescript-sdk/v1/index.js";
+import {
+  Or,
+  SleepCondition,
+  UserEventCondition,
+} from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { DurationObject } from "@hogsend/core";
-import { evaluateEventCondition } from "@hogsend/core";
+import { durationToMs, evaluateEventCondition } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import {
   isValidTimeZone,
@@ -19,10 +27,32 @@ import type {
 } from "@hogsend/core/types";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
 import type { PostHogService } from "@hogsend/plugin-posthog";
-import { and, count, eq, max } from "drizzle-orm";
+import { and, count, eq, 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";
+import {
+  JOURNEY_EXECUTION_TIMEOUT,
+  JOURNEY_EXECUTION_TIMEOUT_HOURS,
+} from "./constants.js";
+import { JourneyExitedError } from "./errors.js";
+
+/** Journey statuses that are terminal — a journey in any of these must never be
+ * resurrected back to "active" by a wait resuming. Exported so the durable task
+ * runner can avoid clobbering a terminal row to "failed" on a cancel. */
+export const TERMINAL_STATUSES = ["completed", "failed", "exited"] as const;
+
+/** Upper bound for a `waitForEvent` timeout — the journey task's executionTimeout. */
+const MAX_WAIT_MS = durationToMs({ hours: JOURNEY_EXECUTION_TIMEOUT_HOURS });
+
+/**
+ * Quote a string as a CEL single-quoted string literal, escaping backslashes
+ * then single quotes. Used to embed an externally-supplied userId into a CEL
+ * filter expression without breaking it or allowing injection.
+ */
+function celStringLiteral(value: string): string {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
 
 interface JourneyContextConfig {
   db: Database;
@@ -31,6 +61,12 @@ interface JourneyContextConfig {
     // Hatchet's real `sleepFor` accepts a number (milliseconds) in addition to
     // duration strings/objects; we use the number-ms form for `sleepUntil`.
     sleepFor: (duration: DurationObject | number) => Promise<unknown>;
+    // The forwarded object is the real Hatchet `DurableContext`, which also has
+    // `waitFor` (used by `waitForEvent`). Param mirrors the SDK signature so the
+    // real context is assignable; we read back the envelope as a plain record.
+    waitFor: (
+      conditions: Conditions | Conditions[],
+    ) => Promise<Record<string, unknown>>;
   };
   registry: JourneyRegistry;
   logger: Logger;
@@ -114,30 +150,103 @@ export function createJourneyContext(
     defaultSendWindow,
   } = config;
 
-  // Shared wait lifecycle: mark the state "waiting", durably sleep, mark it
-  // "active" again. `sleep` passes a DurationObject; `sleepUntil` passes a
-  // precomputed ms delay — Hatchet's `sleepFor` accepts both.
+  // Enter a durable wait: flip "active" → "waiting", but ONLY if the journey
+  // hasn't already reached a terminal state (e.g. exitOn fired before we got
+  // here). A no-op update means the journey is already done — abort the run.
+  const enterWait = async (nodeId: string): Promise<void> => {
+    const entered = await db
+      .update(journeyStates)
+      .set({ status: "waiting", currentNodeId: nodeId, updatedAt: new Date() })
+      .where(
+        and(
+          eq(journeyStates.id, stateId),
+          notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
+        ),
+      )
+      .returning({ id: journeyStates.id });
+
+    if (entered.length === 0) {
+      throw new JourneyExitedError(stateId);
+    }
+  };
+
+  // Resume from a durable wait: flip "waiting" → "active", but ONLY if the row
+  // is still "waiting". If an exit/cancel landed during the wait the row is no
+  // longer "waiting" — abort instead of reviving a terminated journey to active
+  // (which would let a post-wait side effect fire after the journey exited).
+  const resumeFromWait = async (): Promise<void> => {
+    const resumed = await db
+      .update(journeyStates)
+      .set({ status: "active", updatedAt: new Date() })
+      .where(
+        and(eq(journeyStates.id, stateId), eq(journeyStates.status, "waiting")),
+      )
+      .returning({ id: journeyStates.id });
+
+    if (resumed.length === 0) {
+      throw new JourneyExitedError(stateId);
+    }
+  };
+
+  // Durable sleep with the guarded waiting → active lifecycle. `sleep` passes a
+  // DurationObject; `sleepUntil` passes a precomputed ms delay — Hatchet's
+  // `sleepFor` accepts both.
   const performSleep = async (
     durationOrMs: DurationObject | number,
     nodeId: string,
   ): Promise<{ sleptAt: string; resumedAt: string }> => {
     const sleptAt = new Date().toISOString();
+    await enterWait(nodeId);
+    await hatchetCtx.sleepFor(durationOrMs);
+    const resumedAt = new Date().toISOString();
+    await resumeFromWait();
+    return { sleptAt, resumedAt };
+  };
 
-    await db
-      .update(journeyStates)
-      .set({ status: "waiting", currentNodeId: nodeId, updatedAt: new Date() })
-      .where(eq(journeyStates.id, stateId));
+  // Durably wait for THIS user's `event` OR `timeout`, whichever fires first,
+  // sharing the same guarded lifecycle as `performSleep`.
+  const performWaitForEvent = async (
+    event: string,
+    timeout: DurationObject,
+    nodeId: string,
+  ): Promise<{ timedOut: boolean }> => {
+    // 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
+    // JOURNEY_EXECUTION_TIMEOUT to lift it.)
+    if (durationToMs(timeout) > MAX_WAIT_MS) {
+      throw new RangeError(
+        `waitForEvent timeout exceeds the journey execution limit (${JOURNEY_EXECUTION_TIMEOUT})`,
+      );
+    }
 
-    await hatchetCtx.sleepFor(durationOrMs);
+    await enterWait(nodeId);
 
-    const resumedAt = new Date().toISOString();
+    // Wait for the user-scoped event or the timeout. The event branch filters on
+    // the pushed payload's top-level `userId` (see `ingestEvent`); the SDK turns
+    // the ms number into a Go duration string at serialization time.
+    const result = await hatchetCtx.waitFor(
+      Or(
+        new UserEventCondition(
+          event,
+          `input.userId == ${celStringLiteral(userId)}`,
+          "event",
+        ),
+        new SleepCondition(durationToMs(timeout), "timeout"),
+      ),
+    );
 
-    await db
-      .update(journeyStates)
-      .set({ status: "active", updatedAt: new Date() })
-      .where(eq(journeyStates.id, stateId));
+    // Discriminate on which branch's readableDataKey ("event"/"timeout") is
+    // present. The eviction-capable path returns the `{ CREATE: { … } }`
+    // envelope; the pre-eviction path returns the inner object UN-wrapped — so
+    // strip an optional `CREATE` layer first to handle both shapes identically.
+    const fired = (("CREATE" in result ? result.CREATE : result) ??
+      {}) as Record<string, unknown>;
+    const timedOut = !("event" in fired);
 
-    return { sleptAt, resumedAt };
+    await resumeFromWait();
+
+    return { timedOut };
   };
 
   return {
@@ -169,6 +278,14 @@ export function createJourneyContext(
       );
     },
 
+    async waitForEvent({ event, timeout, label }) {
+      return performWaitForEvent(
+        event,
+        timeout,
+        label ?? `wait-event:${event}`,
+      );
+    },
+
     async checkpoint(label) {
       await db
         .update(journeyStates)

package/src/lib/ingestion.ts

@@ -76,7 +76,7 @@ export async function ingestEvent(opts: {
       userEmail: event.userEmail,
       properties: serializableProperties,
     }),
-    checkExits(db, registry, {
+    checkExits(db, registry, hatchet, logger, {
       userId: event.userId,
       eventName: event.event,
       properties: event.properties,
@@ -130,6 +130,8 @@ export async function ingestEvent(opts: {
 async function checkExits(
   db: Database,
   registry: JourneyRegistry,
+  hatchet: HatchetClient,
+  logger: Logger,
   event: {
     userId: string;
     eventName: string;
@@ -147,6 +149,7 @@ async function checkExits(
   });
 
   const statesToExit: string[] = [];
+  const runIdsToCancel: string[] = [];
 
   for (const state of activeStates) {
     const journey = registry.get(state.journeyId);
@@ -163,6 +166,9 @@ async function checkExits(
 
     if (shouldExit) {
       statesToExit.push(state.id);
+      if (state.hatchetRunId) {
+        runIdsToCancel.push(state.hatchetRunId);
+      }
     }
 
     results.push({
@@ -181,6 +187,21 @@ async function checkExits(
         updatedAt: new Date(),
       })
       .where(inArray(journeyStates.id, statesToExit));
+
+    // Cancel the live durable runs so a journey suspended in a sleep or
+    // `waitForEvent` can't resume and fire after it has exited. Best-effort: a
+    // run may have already finished, and the in-run resume guard
+    // (JourneyExitedError) is the backstop if a cancel races a resume.
+    if (runIdsToCancel.length > 0) {
+      try {
+        await hatchet.runs.cancel({ ids: runIdsToCancel });
+      } catch (err) {
+        logger.warn("Failed to cancel exited journey runs", {
+          count: runIdsToCancel.length,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
   }
 
   return results;