@hogsend/engine 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.2.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.2.0",
-    "@hogsend/db": "^0.2.0",
-    "@hogsend/email": "^0.1.0",
-    "@hogsend/plugin-posthog": "^0.1.0",
-    "@hogsend/plugin-resend": "^0.1.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/buckets/check-membership.ts

@@ -7,14 +7,17 @@ import {
 } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { bucketMemberships, contacts, type Database } from "@hogsend/db";
-import { and, eq, isNull, sql } from "drizzle-orm";
+import { and, desc, eq, isNotNull, isNull } from "drizzle-orm";
 import { emitBucketTransition } from "../lib/bucket-emit.js";
 import type { Logger } from "../lib/logger.js";
+import {
+  BUCKET_EVENT_PREFIX,
+  computeExpiresAt,
+  computeMaxDwellAt,
+  countPriorMemberships,
+} from "./membership-epoch.js";
 import { getBucketRegistrySingleton } from "./registry-singleton.js";
 
-/** The reserved prefix every bucket transition event carries. */
-const BUCKET_EVENT_PREFIX = "bucket:";
-
 export type BucketTransitionKind = "entered" | "left";
 
 export interface BucketTransition {
@@ -33,7 +36,7 @@ export interface BucketTransition {
  * RETURNING-gated mutation (partial-unique INSERT for joins, compare-and-swap
  * UPDATE for leaves — Section 6.3). On a real transition it emits
  * `bucket:entered:<id>` / `bucket:left:<id>` back through `ingestEvent`, gated on
- * the reentry policy and deferring leaves still inside `minDwell`.
+ * the entryLimit policy and deferring leaves still inside `minDwell`.
  *
  * Returns the computed transition list so a unit test can assert enter/leave/no-op
  * WITHOUT a live Hatchet (Section 14 — the testing seam). Production callers
@@ -221,18 +224,10 @@ async function handleJoin(opts: {
   const { db, registry, hatchet, logger, bucket, userId, userEmail } = opts;
 
   // entryCount ordinal = 1 + count of ALL prior memberships (active + left) for
-  // this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the reentry
-  // gate.
-  const [counted] = await db
-    .select({ priorCount: sql<number>`count(*)::int` })
-    .from(bucketMemberships)
-    .where(
-      and(
-        eq(bucketMemberships.userId, userId),
-        eq(bucketMemberships.bucketId, bucket.id),
-      ),
-    );
-  const priorCount = Number(counted?.priorCount ?? 0);
+  // this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the entryLimit
+  // gate. Shared with the reconcile-discovered join path so the ordinal can
+  // never drift between the two writers.
+  const priorCount = await countPriorMemberships(db, bucket.id, userId);
   const epoch = priorCount + 1;
 
   // INSERT a FRESH active row. ON CONFLICT DO NOTHING targets the partial active
@@ -241,9 +236,7 @@ async function handleJoin(opts: {
   // (the loser mutates nothing — Section 6.3 governing rule).
   const expiresAt = computeExpiresAt(bucket);
   // Unconditional TTL deadline — set once on join, swept by the reconcile cron.
-  const maxDwellAt = bucket.maxDwell
-    ? new Date(Date.now() + durationToMs(bucket.maxDwell))
-    : null;
+  const maxDwellAt = computeMaxDwellAt(bucket);
   const inserted = await db
     .insert(bucketMemberships)
     .values({
@@ -284,8 +277,8 @@ async function handleJoin(opts: {
 
   // The active row is always written (Studio size must reflect reality) and the
   // epoch always advances via the real insert; only the bucket:entered emission
-  // is gated by the reentry policy (Section 6.3).
-  if (shouldEmitJoin(bucket, priorCount)) {
+  // is gated by the entryLimit policy (Section 6.3).
+  if (await shouldEmitJoin({ db, bucket, userId, priorCount })) {
     await emitBucketTransition({
       db,
       registry,
@@ -299,10 +292,10 @@ async function handleJoin(opts: {
       source: "event",
     });
   } else {
-    logger.info("Bucket join emit suppressed by reentry policy", {
+    logger.info("Bucket join emit suppressed by entryLimit policy", {
       bucketId: bucket.id,
       userId,
-      reentry: bucket.reentry ?? "unlimited",
+      entryLimit: bucket.entryLimit ?? "unlimited",
     });
   }
 
@@ -392,28 +385,56 @@ async function handleLeave(opts: {
 }
 
 /**
- * The `reentry` emit gate, consulted on the JOIN transition only (Section 6.3).
+ * The `entryLimit` emit gate, consulted on the JOIN transition only (Section 6.3).
  * Suppressing the emit still wrote the active row and advanced the epoch — only
  * the `bucket:entered` ingestEvent recursion is skipped.
+ *
+ * The engine now enforces `once_per_period` PRECISELY: it reads the most-recent
+ * prior LEAVE (`status:"left"` with `leftAt` set) and emits only once the
+ * configured `entryPeriod` has elapsed since that leave. The journey-side
+ * entryLimit/entryPeriod is a redundant backstop, no longer the sole gate.
  */
-function shouldEmitJoin(bucket: BucketMeta, priorCount: number): boolean {
+export async function shouldEmitJoin(opts: {
+  db: Database;
+  bucket: BucketMeta;
+  userId: string;
+  priorCount: number;
+}): Promise<boolean> {
+  const { db, bucket, userId, priorCount } = opts;
   // First-ever join always emits.
   if (priorCount === 0) return true;
-  switch (bucket.reentry ?? "unlimited") {
+  switch (bucket.entryLimit ?? "unlimited") {
     case "unlimited":
       return true;
     case "once":
       // Any prior membership → suppress (mirrors checkEntryLimit "once").
       return false;
-    case "once_per_period":
-      // Conservative without re-reading prior rows here: a per-period emit gate
-      // needs the most-recent prior transition timestamp. The active row was
-      // just inserted; the prior-row timestamps are not loaded on this path, so
-      // we treat once_per_period as "emit" once the active insert won and let
-      // the journey-side entryLimit/entryPeriod enforce cooldown (the documented
-      // two-layer gating, Section 13). A precise prior-transition lookup is a
-      // later-phase refinement.
-      return true;
+    case "once_per_period": {
+      // Back-compat: with no period configured, preserve 0.2.0 behavior (emit)
+      // and defer cooldown to the journey-side entryLimit/entryPeriod.
+      if (!bucket.entryPeriod) return true;
+      // Look up the most-recent COMPLETED prior cycle. Scoping to status:"left"
+      // (not "any prior row") makes this order-independent and race-safe against
+      // the active row we just inserted at this join — that row has no leftAt and
+      // status:"active", so it can never be mistaken for the prior cycle.
+      const [prior] = await db
+        .select({ leftAt: bucketMemberships.leftAt })
+        .from(bucketMemberships)
+        .where(
+          and(
+            eq(bucketMemberships.userId, userId),
+            eq(bucketMemberships.bucketId, bucket.id),
+            eq(bucketMemberships.status, "left"),
+            isNotNull(bucketMemberships.leftAt),
+          ),
+        )
+        .orderBy(desc(bucketMemberships.leftAt))
+        .limit(1);
+      // No completed prior cycle to cool off from → emit.
+      if (!prior?.leftAt) return true;
+      const elapsed = Date.now() - prior.leftAt.getTime();
+      return elapsed >= durationToMs(bucket.entryPeriod);
+    }
     default:
       return true;
   }
@@ -467,33 +488,3 @@ async function armExpiryTimer(opts: {
     });
   }
 }
-
-/**
- * The persisted membership-expiry / fastExpiry arming epoch. Non-time-based,
- * non-fastExpiry buckets have no deadline (returns null). Time-based / fastExpiry
- * buckets that carry a single `within` window get `now + within`; the reconcile
- * cron (Phase 2) and fastExpiry timer (Phase 3) own the actual leave.
- */
-function computeExpiresAt(bucket: BucketMeta): Date | null {
-  if (!bucket.criteria) return null;
-  if (!bucket.timeBased && !bucket.fastExpiry) return null;
-  const within = firstWithin(bucket.criteria);
-  if (!within) return null;
-  return new Date(Date.now() + durationToMs(within));
-}
-
-/** Find the first EventCondition.within in a criteria tree (depth-first). */
-function firstWithin(
-  criteria: NonNullable<BucketMeta["criteria"]>,
-): NonNullable<BucketMeta["minDwell"]> | null {
-  if (criteria.type === "event" && criteria.within) {
-    return criteria.within;
-  }
-  if (criteria.type === "composite") {
-    for (const child of criteria.conditions) {
-      const found = firstWithin(child);
-      if (found) return found;
-    }
-  }
-  return null;
-}

package/src/buckets/define-bucket.ts

@@ -1,6 +1,24 @@
-import type { BucketMeta } from "@hogsend/core/types";
+import { type CriteriaBuilder, criteriaBuilder } from "@hogsend/core";
+import type { BucketMeta, ConditionEval } from "@hogsend/core/types";
 import type { hatchet } from "../lib/hatchet.js";
 
+/**
+ * `criteria` may be authored two ways:
+ *  - declaratively, as a `ConditionEval` data tree, or
+ *  - with the fluent builder, as `(b) => b.all(b.prop("plan").eq("trial"), ...)`.
+ * The builder form runs ONCE here and returns a `ConditionEval`, so everything
+ * downstream (registry indexes, schema validation, reconcile cron, Studio) only
+ * ever sees the canonical declarative data.
+ */
+export type CriteriaInput =
+  | ConditionEval
+  | ((b: CriteriaBuilder) => ConditionEval);
+
+/** `BucketMeta` as authored — `criteria` accepts the builder function too. */
+export type BucketMetaInput = Omit<BucketMeta, "criteria"> & {
+  criteria?: CriteriaInput;
+};
+
 export interface DefinedBucket {
   meta: BucketMeta;
   /**
@@ -15,15 +33,20 @@ export interface DefinedBucket {
   task?: ReturnType<typeof hatchet.durableTask>;
 }
 
-export function defineBucket(options: { meta: BucketMeta }): DefinedBucket {
-  // bucketMetaSchema.parse happens at BucketRegistry.register (the journey
-  // precedent). defineBucket stays a PURE passthrough — identical in shape to
-  // defineWebhookSource (define-webhook-source.ts:30-34) — and does NOT branch
-  // on meta or construct any task. This keeps the three primitives consistent
-  // and avoids building a Hatchet durableTask at module-load before validation
-  // has run. The fast-expiry durableTask is synthesized later, at worker build,
-  // by selectBucketTasks(buckets, enabled) reading meta.fastExpiry (Section 9.4)
-  // — that is the single place a bucket's task is constructed, AFTER the
-  // registry has validated the meta.
-  return { meta: options.meta };
+export function defineBucket(options: {
+  meta: BucketMetaInput;
+}): DefinedBucket {
+  // The ONLY transform defineBucket performs is resolving a builder-function
+  // `criteria` to its `ConditionEval` (a one-shot, definition-time call). It does
+  // NOT validate or build any task — `bucketMetaSchema.parse` still happens at
+  // BucketRegistry.register, and the fast-expiry durableTask is synthesized later
+  // by selectBucketTasks (Section 9.4). A declarative `criteria` passes straight
+  // through unchanged, so existing buckets are unaffected.
+  const { criteria, ...rest } = options.meta;
+  const meta: BucketMeta = {
+    ...rest,
+    criteria:
+      typeof criteria === "function" ? criteria(criteriaBuilder) : criteria,
+  };
+  return { meta };
 }

package/src/buckets/membership-epoch.ts

@@ -0,0 +1,186 @@
+import {
+  type BucketMeta,
+  type ConditionEval,
+  type DurationObject,
+  durationToMs,
+  type EventCondition,
+} from "@hogsend/core";
+import { bucketMemberships, type Database } from "@hogsend/db";
+import { and, eq, sql } from "drizzle-orm";
+
+/**
+ * The reserved prefix every bucket transition event carries. Single source of
+ * truth shared by the ingest recursion guard (`checkBucketMembership`) and the
+ * fast-expiry arming event (`bucket:arm-expiry`).
+ */
+export const BUCKET_EVENT_PREFIX = "bucket:";
+
+/**
+ * The count of ALL prior memberships (active + left, NO status filter) for a
+ * (userId, bucketId) pair. This is the single source for the entryCount-ordinal
+ * rule (Section 6.3 / 8.2): the next epoch is `1 + countPriorMemberships(...)`,
+ * and the same count drives the entryLimit gate. Both the real-time join path
+ * (`handleJoin`) and the reconcile-discovered join path (`reconcileJoinOne`)
+ * call this so the ordinal can never drift between the two writers.
+ *
+ * The predicate MUST stay status-agnostic — narrowing it (e.g. to active-only)
+ * would corrupt entryCount and the entryLimit cooldown.
+ */
+export async function countPriorMemberships(
+  db: Database,
+  bucketId: string,
+  userId: string,
+): Promise<number> {
+  const [counted] = await db
+    .select({ priorCount: sql<number>`count(*)::int` })
+    .from(bucketMemberships)
+    .where(
+      and(
+        eq(bucketMemberships.userId, userId),
+        eq(bucketMemberships.bucketId, bucketId),
+      ),
+    );
+  return Number(counted?.priorCount ?? 0);
+}
+
+/**
+ * Find the first `EventCondition.within` rolling window in a criteria tree
+ * (depth-first). Returns null when no event leg carries a window. The single
+ * source for the membership-expiry / fastExpiry deadline math — shared so the
+ * three membership writers (real-time join, reconcile join, backfill join) can
+ * never disagree on which window drives `expiresAt`.
+ */
+export function firstWithin(criteria: ConditionEval): DurationObject | null {
+  if (criteria.type === "event" && criteria.within) {
+    return criteria.within;
+  }
+  if (criteria.type === "composite") {
+    for (const child of criteria.conditions) {
+      const found = firstWithin(child);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * The persisted membership-expiry / fastExpiry arming deadline. Non-time-based,
+ * non-fastExpiry buckets have no deadline (returns null). Time-based / fastExpiry
+ * buckets that carry a single `within` window get `now + within`; the reconcile
+ * cron and fastExpiry timer own the actual leave.
+ *
+ * Centralized so the real-time join (check-membership.ts), the reconcile-discovered
+ * join (bucket-reconcile.ts), and the backfill join (bucket-backfill.ts) compute
+ * the SAME deadline — a divergence here would let a membership-writer arm a window
+ * the cron/timer disagrees with.
+ */
+export function computeExpiresAt(bucket: BucketMeta): Date | null {
+  if (!bucket.criteria) return null;
+  if (!bucket.timeBased && !bucket.fastExpiry) return null;
+  const within = firstWithin(bucket.criteria);
+  if (!within) return null;
+  return new Date(Date.now() + durationToMs(within));
+}
+
+/**
+ * The unconditional max-dwell TTL deadline, stamped once on JOIN. null when the
+ * bucket has no `maxDwell`; the TTL sweep filters `isNotNull(maxDwellAt)`, so an
+ * unset value is never force-left. Shared by all three join writers so the TTL
+ * stamp is computed identically.
+ */
+export function computeMaxDwellAt(bucket: BucketMeta): Date | null {
+  return bucket.maxDwell
+    ? new Date(Date.now() + durationToMs(bucket.maxDwell))
+    : null;
+}
+
+/**
+ * The shared windowed event-count operator comparison kernel (`gt/gte/lt/lte/eq`).
+ * Returns the boolean of `count <operator> value`, or null for an unrecognized
+ * operator so each caller keeps its own default (the leave/match wrappers below).
+ * This is the single source for the count-operator math the reconcile SHOULD-LEAVE
+ * and the backfill MATCH paths both depend on.
+ */
+function compareCount(
+  operator: NonNullable<EventCondition["operator"]>,
+  count: number,
+  value: number,
+): boolean | null {
+  switch (operator) {
+    case "gt":
+      return count > value;
+    case "gte":
+      return count >= value;
+    case "lt":
+      return count < value;
+    case "lte":
+      return count <= value;
+    case "eq":
+      return count === value;
+    default:
+      return null;
+  }
+}
+
+/**
+ * True when a windowed `count` satisfies the (exists/not_exists/count) event
+ * criterion — the POSITIVE "is a member by this windowed count" decision. Shared
+ * by the backfill matcher path (selectEventMatchers' positive branch). Behavior is
+ * identical to the prior local `matchesCount`: a `count` check with no
+ * operator/value (or an unrecognized operator) falls back to `count > 0` / `false`
+ * respectively.
+ */
+export function matchesEventCount(
+  criteria: EventCondition,
+  count: number,
+): boolean {
+  switch (criteria.check) {
+    case "exists":
+      return count > 0;
+    case "not_exists":
+      return count === 0;
+    case "count": {
+      if (!criteria.operator || criteria.value === undefined) return count > 0;
+      const result = compareCount(criteria.operator, count, criteria.value);
+      return result ?? false;
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * The SHOULD-LEAVE decision from a windowed count, per criterion shape — a member
+ * leaves when the criterion is NO LONGER satisfied. Shared by the reconcile
+ * cron's set-based leave path. Behavior is identical to the prior local
+ * `shouldLeaveByCount`: it is the per-shape NEGATION of {@link matchesEventCount}
+ * for `exists`/`count`, an event-reappeared check for `not_exists`, and preserves
+ * the `count` `default → false` for an unrecognized operator.
+ */
+export function shouldLeaveByCount(
+  criteria: EventCondition,
+  windowedCount: number,
+): boolean {
+  switch (criteria.check) {
+    case "not_exists":
+      // Absence bucket: SHOULD LEAVE when an event REAPPEARS in the window.
+      return windowedCount > 0;
+    case "exists":
+      // Positive existence: SHOULD LEAVE when NOT EXISTS in the window.
+      return windowedCount === 0;
+    case "count": {
+      // SHOULD LEAVE when the windowed count NO LONGER satisfies the operator.
+      if (!criteria.operator || criteria.value === undefined) {
+        return windowedCount === 0;
+      }
+      const result = compareCount(
+        criteria.operator,
+        windowedCount,
+        criteria.value,
+      );
+      return result == null ? false : !result;
+    }
+    default:
+      return false;
+  }
+}

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;
+  }
+}