@hogsend/engine 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.2.0",
+  "version": "0.3.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.3.0",
+    "@hogsend/email": "^0.3.0",
+    "@hogsend/db": "^0.3.0",
+    "@hogsend/plugin-posthog": "^0.3.0",
+    "@hogsend/plugin-resend": "^0.3.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/routes/admin/buckets.ts

@@ -10,7 +10,7 @@ const bucketSchema = z.object({
   enabled: z.boolean(),
   kind: z.enum(["dynamic", "manual"]),
   timeBased: z.boolean(),
-  reentry: z.enum(["once", "once_per_period", "unlimited"]),
+  entryLimit: z.enum(["once", "once_per_period", "unlimited"]),
   counts: z.object({
     active: z.number(),
     left: z.number(),
@@ -106,7 +106,7 @@ const getRoute = createRoute({
           schema: z.object({
             bucket: bucketSchema.extend({
               criteria: z.record(z.string(), z.unknown()).optional(),
-              reentryPeriod: z
+              entryPeriod: z
                 .record(z.string(), z.unknown())
                 .nullable()
                 .optional(),
@@ -267,7 +267,7 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
         enabled: effectiveEnabled,
         kind: b.kind ?? "dynamic",
         timeBased: b.timeBased ?? false,
-        reentry: b.reentry ?? "unlimited",
+        entryLimit: b.entryLimit ?? "unlimited",
         counts: countsMap.get(b.id) ?? { ...emptyCounts },
       };
     });
@@ -366,11 +366,9 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
           enabled: effectiveEnabled,
           kind: meta.kind ?? "dynamic",
           timeBased: meta.timeBased ?? false,
-          reentry: meta.reentry ?? "unlimited",
+          entryLimit: meta.entryLimit ?? "unlimited",
           criteria: meta.criteria as Record<string, unknown> | undefined,
-          reentryPeriod: meta.reentryPeriod as
-            | Record<string, unknown>
-            | undefined,
+          entryPeriod: meta.entryPeriod as Record<string, unknown> | undefined,
           minDwell: meta.minDwell as Record<string, unknown> | undefined,
           maxDwell: meta.maxDwell as Record<string, unknown> | undefined,
           reconcileEvery: meta.reconcileEvery as

package/src/worker.ts

@@ -79,12 +79,12 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
       `Hogsend worker started with ${journeyTasks.length} journey task(s)`,
     );
 
-    await _worker.start();
-
     // Boot-time backfill / criteria-change re-eval (Section 6.6 B): diff each
-    // enabled bucket's criteriaHash against bucket_configs and enqueue a
-    // backfill/re-eval job where it differs. Best-effort — never block worker
-    // start; the cron is the backstop for time-based leaves regardless.
+    // enabled bucket's criteriaHash against bucket_configs and trigger a
+    // backfill/re-eval run where it differs. Kicked off BEFORE the listener
+    // because `_worker.start()` below does NOT return until the worker stops —
+    // anything after it is dead code at runtime. The triggers are fire-and-forget
+    // (runNoWait) and execute once the listener is up; best-effort, never blocks.
     enqueueBucketBackfills({
       db: container.db,
       logger: container.logger,
@@ -93,6 +93,8 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
         error: err instanceof Error ? err.message : String(err),
       });
     });
+
+    await _worker.start();
   }
 
   return { start, stop };