@hogsend/engine 0.5.0 → 0.6.0

package/src/container.ts

@@ -14,8 +14,12 @@ import {
   createResendProvider,
 } from "@hogsend/plugin-resend";
 import type { Resend } from "resend";
+import { createBucketAccessor } from "./buckets/bucket-access.js";
 import type { DefinedBucket } from "./buckets/define-bucket.js";
-import { buildBucketRegistry } from "./buckets/registry.js";
+import {
+  buildBucketRegistry,
+  collectBucketReactionJourneys,
+} from "./buckets/registry.js";
 import { env } from "./env.js";
 import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
@@ -200,10 +204,38 @@ export function createHogsendClient(
   // Installs the bucket registry singleton in BOTH the API and worker processes
   // (both call createHogsendClient); the real-time ingest path reads it via
   // getBucketRegistrySingleton().
-  const bucketRegistry = buildBucketRegistry(
-    opts.buckets ?? [],
-    opts.enabledBuckets ?? env.ENABLED_BUCKETS,
-  );
+  const buckets = opts.buckets ?? [];
+  const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
+  const bucketRegistry = buildBucketRegistry(buckets, enabledBuckets);
+
+  // Register the reaction journeys generated by `bucket.on()` into the journey
+  // registry AFTER buildJourneyRegistry, bypassing the ENABLED_JOURNEYS filter:
+  // reactions are bucket-owned and were already gated by ENABLED_BUCKETS
+  // (collectBucketReactionJourneys), so their `bucket-<id>-on-<kind>` ids must NOT
+  // be subject to the journeys csv (Section 9). Both API and worker call
+  // createHogsendClient, so the singleton carries reaction metas in both
+  // processes (needed for admin feedsJourneys + the dwell-cron lookup).
+  for (const reaction of collectBucketReactionJourneys(
+    buckets,
+    enabledBuckets,
+  )) {
+    registry.register(reaction.meta);
+  }
+
+  // Re-bind the member-access accessors on each enabled bucket to THIS
+  // container's db so `overrides.db` flows through (the accessors default to the
+  // getDb() singleton at defineBucket time, before any container exists —
+  // bucket-access.ts dbResolver seam). The enabled set mirrors
+  // buildBucketRegistry's filter.
+  const enabledIds = new Set(bucketRegistry.getAll().map((b) => b.id));
+  for (const bucket of buckets) {
+    if (!enabledIds.has(bucket.meta.id)) continue;
+    const accessor = createBucketAccessor(bucket.meta.id, () => db);
+    bucket.count = accessor.count;
+    bucket.has = accessor.has;
+    bucket.members = accessor.members;
+    bucket.membersIterator = accessor.membersIterator;
+  }
 
   const provider =
     opts.email?.provider ??

package/src/index.ts

@@ -39,6 +39,18 @@ export {
 // --- App / container / worker factories ---
 export { type AppEnv, type CreateAppOptions, createApp } from "./app.js";
 // --- Buckets ---
+export {
+  type BucketAccessor,
+  type BucketMemberRow,
+  createBucketAccessor,
+  type MembersResult,
+} from "./buckets/bucket-access.js";
+export type {
+  BucketLeaveReason,
+  DwellOptions,
+  EnterOptions,
+  LeaveOptions,
+} from "./buckets/bucket-reactions.js";
 export {
   type BucketTransition,
   type BucketTransitionKind,
@@ -50,6 +62,8 @@ export {
 } from "./buckets/define-bucket.js";
 export {
   buildBucketRegistry,
+  collectBucketReactionJourneys,
+  selectBucketReactionTasks,
   selectBucketTasks,
 } from "./buckets/registry.js";
 export {

package/src/lib/boot.ts

@@ -125,12 +125,20 @@ export interface WorkerReadyInfo {
   client: HogsendClient;
   journeyTasks: number;
   bucketTasks: number;
+  /** Reaction journey tasks generated by `bucket.on()` (Section 9). */
+  bucketReactionTasks: number;
   builtinTasks: number;
 }
 
 /** Render the worker "ready" output (banner in dev TTY, structured log otherwise). */
 export function reportWorkerReady(info: WorkerReadyInfo): void {
-  const { client, journeyTasks, bucketTasks, builtinTasks } = info;
+  const {
+    client,
+    journeyTasks,
+    bucketTasks,
+    bucketReactionTasks,
+    builtinTasks,
+  } = info;
   const engineVersion = getEngineVersion();
   const hatchetHost = client.env.HATCHET_CLIENT_HOST_PORT;
 
@@ -141,6 +149,7 @@ export function reportWorkerReady(info: WorkerReadyInfo): void {
       namespace: client.env.HATCHET_CLIENT_NAMESPACE || undefined,
       journeyTasks,
       bucketTasks,
+      bucketReactionTasks,
       builtinTasks,
     });
     return;
@@ -151,6 +160,7 @@ export function reportWorkerReady(info: WorkerReadyInfo): void {
   const tasks = [
     plural(journeyTasks, "journey task"),
     plural(bucketTasks, "bucket task"),
+    plural(bucketReactionTasks, "reaction task"),
     plural(builtinTasks, "built-in task"),
   ].join(dim(" · "));
 

package/src/lib/bucket-emit.ts

@@ -2,11 +2,12 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { BucketMeta } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import type { Database } from "@hogsend/db";
+import type { BucketLeaveReason } from "../buckets/bucket-reactions.js";
 import { syncBucketToPostHog } from "./bucket-posthog-sync.js";
 import { ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";
 
-export type BucketTransitionKind = "entered" | "left";
+export type BucketTransitionKind = "entered" | "left" | "dwell";
 
 /** Where a transition originated — carried on the emitted event properties. */
 export type BucketTransitionSource =
@@ -40,6 +41,16 @@ export async function emitBucketTransition(opts: {
   userEmail: string | null;
   epoch: number;
   source?: BucketTransitionSource;
+  /** Carried on a `left` transition's properties → `ctx.reason`. */
+  reason?: BucketLeaveReason;
+  /** The dwell schedule label (`after-<ms>`/`every-<ms>`) — `dwell` only. */
+  dwellLabel?: string;
+  /**
+   * The deterministic dwell interval ordinal — `dwell` only. Rides the
+   * idempotencyKey so a same-sweep retry recomputes the identical key and is
+   * absorbed by the `userEvents` dedup. Surfaced as `dwellCount`.
+   */
+  dwellOrdinal?: number;
 }): Promise<void> {
   const {
     db,
@@ -52,22 +63,53 @@ export async function emitBucketTransition(opts: {
     userEmail,
     epoch,
     source = "event",
+    reason,
+    dwellLabel,
+    dwellOrdinal,
   } = opts;
 
+  // The dwell transition emits a labelled event so two dwell reactions on one
+  // bucket (one `after`, one `every`) route distinctly; enter/left keep the
+  // canonical `bucket:<kind>:<id>` form. The idempotencyKey is recomputed
+  // identically by a retry: enter/left key on the membership epoch, dwell keys
+  // on the (label, ordinal) so a same-sweep retry rides the userEvents dedup.
+  const eventName =
+    kind === "dwell"
+      ? `bucket:dwell:${bucket.id}:${dwellLabel}`
+      : `bucket:${kind}:${bucket.id}`;
+  const idempotencyKey =
+    kind === "dwell"
+      ? `bucket:${bucket.id}:${userId}:dwell:${dwellLabel}:${dwellOrdinal}`
+      : `bucket:${bucket.id}:${userId}:${kind}:${epoch}`;
+
   const properties: Record<string, unknown> = {
     bucketId: bucket.id,
     bucketName: bucket.name,
     userId,
     transition: kind,
     source,
+    // entryCount is always carried (the membership ordinal); the reaction `run`
+    // derives `isFirstEntry` from it.
+    entryCount: epoch,
   };
+  // reason is carried on a leave so the `leave` reaction can filter on it.
+  if (kind === "left" && reason != null) {
+    properties.reason = reason;
+  }
+  // dwellCount = the interval ordinal, surfaced to the dwell reaction.
+  if (kind === "dwell" && dwellOrdinal != null) {
+    properties.dwellCount = dwellOrdinal;
+  }
 
   // Optional PostHog person-property mirror (Section 12). Off by default; a
   // no-op without POSTHOG_API_KEY. Wired here, the single transition path shared
   // by all three producers (real-time / reconcile / fast-expiry), so the sync
   // fires exactly once per emitted transition. Best-effort — it never blocks the
-  // event emit below.
-  syncBucketToPostHog({ logger, kind, bucket, userId });
+  // event emit below. Dwell is a recurring membership-age tick, not a state
+  // change, so it does NOT mirror a person property.
+  if (kind === "entered" || kind === "left") {
+    syncBucketToPostHog({ logger, kind, bucket, userId });
+  }
 
   // Per-bucket alias — the recommended, narrowly-routed binding. The
   // deterministic idempotencyKey rides the userEvents dedup short-circuit as
@@ -78,11 +120,11 @@ export async function emitBucketTransition(opts: {
     hatchet,
     logger,
     event: {
-      event: `bucket:${kind}:${bucket.id}`,
+      event: eventName,
       userId,
       userEmail: userEmail ?? "",
       properties,
-      idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}`,
+      idempotencyKey,
     },
   });
 

package/src/routes/admin/buckets.ts

@@ -123,6 +123,8 @@ const getRoute = createRoute({
                   id: z.string(),
                   name: z.string(),
                   trigger: z.string(),
+                  sourceBucketId: z.string().nullable(),
+                  owned: z.boolean(),
                 }),
               ),
               recentMembers: z.array(memberSchema),
@@ -332,27 +334,55 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
       counts[row.status as keyof typeof emptyCounts] = row.count;
     }
 
-    // Which journeys this bucket feeds — cross-reference the bucket's emitted
-    // transition events against the journey registry's trigger index. A journey
-    // bound to the per-bucket alias `bucket:entered:<id>` (the recommended,
-    // narrowly-routed binding) or the generic `bucket:entered` is woken by this
-    // bucket's joins.
+    // Which journeys this bucket feeds. Two sources, owned-first:
+    //  1. Owned reactions — journeys generated by `bucket.on()`, tagged with
+    //     `sourceBucketId === id`. Discovered by scanning the registry; surfaced
+    //     with `owned: true`.
+    //  2. External bindings — hand-written journeys bound to the bucket's emitted
+    //     transition events via the per-bucket alias `bucket:entered:<id>` (the
+    //     recommended, narrowly-routed binding) or the generic `bucket:entered`.
+    //     Surfaced with `owned: false`. Owned wins on collision.
+    const feedsMap = new Map<
+      string,
+      {
+        id: string;
+        name: string;
+        trigger: string;
+        sourceBucketId: string | null;
+        owned: boolean;
+      }
+    >();
+
+    // Owned reactions: scan the journey registry for sourceBucketId === id.
+    for (const journey of registry
+      .getAll()
+      .filter((j) => j.sourceBucketId === id)) {
+      feedsMap.set(journey.id, {
+        id: journey.id,
+        name: journey.name,
+        trigger: journey.trigger.event,
+        sourceBucketId: id,
+        owned: true,
+      });
+    }
+
+    // External bindings: the existing alias + generic cross-reference. Skip any
+    // journey already surfaced as owned (owned wins).
     const feedEvents = [
       `bucket:entered:${id}`,
       `bucket:left:${id}`,
       "bucket:entered",
       "bucket:left",
     ];
-    const feedsMap = new Map<
-      string,
-      { id: string; name: string; trigger: string }
-    >();
     for (const evt of feedEvents) {
       for (const journey of registry.getByTriggerEvent(evt)) {
+        if (feedsMap.has(journey.id)) continue;
         feedsMap.set(journey.id, {
           id: journey.id,
           name: journey.name,
           trigger: evt,
+          sourceBucketId: journey.sourceBucketId ?? null,
+          owned: false,
         });
       }
     }

package/src/worker.ts

@@ -1,5 +1,8 @@
 import type { DefinedBucket } from "./buckets/define-bucket.js";
-import { selectBucketTasks } from "./buckets/registry.js";
+import {
+  selectBucketReactionTasks,
+  selectBucketTasks,
+} from "./buckets/registry.js";
 import type { HogsendClient } from "./container.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
 import { selectJourneyTasks } from "./journeys/registry.js";
@@ -46,6 +49,15 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
   // reconcile cron (bucketReconcileTask) is ALWAYS registered in baseWorkflows
   // below (Section 10), regardless of fastExpiry.
   const bucketTasks = selectBucketTasks(opts.buckets ?? [], enabledBuckets);
+  // Reaction journeys generated by `bucket.on()` desugar to real durable tasks.
+  // They are bucket-owned, so they are gated by ENABLED_BUCKETS (NOT
+  // ENABLED_JOURNEYS) and wired directly here rather than via the journeys[]
+  // array (Section 9). Throws loudly on a reaction-id collision.
+  const bucketReactionTasks = selectBucketReactionTasks(
+    opts.buckets ?? [],
+    enabledBuckets,
+    journeys.map((j) => j.meta.id),
+  );
 
   const baseWorkflows = [
     sendEmailTask,
@@ -55,6 +67,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     bucketBackfillTask,
     ...journeyTasks,
     ...bucketTasks,
+    ...bucketReactionTasks,
   ];
   const workflows = [
     ...baseWorkflows,
@@ -94,8 +107,12 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
       client: container,
       journeyTasks: journeyTasks.length,
       bucketTasks: bucketTasks.length,
+      bucketReactionTasks: bucketReactionTasks.length,
       builtinTasks:
-        baseWorkflows.length - journeyTasks.length - bucketTasks.length,
+        baseWorkflows.length -
+        journeyTasks.length -
+        bucketTasks.length -
+        bucketReactionTasks.length,
     });
 
     // Publish liveness so the API + Studio can show "worker connected"

package/src/workflows/bucket-backfill.ts

@@ -15,7 +15,7 @@ import {
   importJobs,
   userEvents,
 } from "@hogsend/db";
-import { and, eq, gt, gte, inArray, isNull, sql } from "drizzle-orm";
+import { and, eq, gt, gte, inArray, isNull, max, sql } from "drizzle-orm";
 import {
   computeExpiresAt,
   computeMaxDwellAt,
@@ -209,6 +209,18 @@ async function backfillJoins(opts: {
   // unset value would never be force-left.
   const maxDwellAt = computeMaxDwellAt(bucket);
 
+  // Historical dwell anchor (Section 6.3 / LOCKED DECISION 1). For a
+  // windowed/event criterion the anchor is `max(occurredAt)` of the qualifying
+  // event = "when they became dormant" (e.g. went-dormant = the last
+  // `app_opened`). The dwell gate reads `coalesce(dwellAnchorAt, enteredAt)`, so
+  // backfilled members start the dwell clock at their real historical instant
+  // rather than the deploy-time `enteredAt`. Shapes with no cheap per-matcher
+  // timestamp leave the anchor NULL (fall back to enteredAt). The live join path
+  // (handleJoin) never sets dwellAnchorAt, so post-deploy joins clock from their
+  // real enteredAt. Computed batched per chunk (one GROUP BY max(occurredAt),
+  // mirroring the priorCounts GROUP BY) — never per-user serial queries.
+  const anchorEvent = resolveDwellAnchorEvent(criteria);
+
   // Fix C (DEFERRED): backfilled fastExpiry rows are NOT armed with a
   // bucket:arm-expiry durable timer here — they are picked up by the next cron
   // sweep instead (reconcileBucketLeaves / reconcileBucketTtlLeaves are the
@@ -253,6 +265,35 @@ async function backfillJoins(opts: {
       priorCounts.map((r) => [r.userId, Number(r.cnt)]),
     );
 
+    // Batched dwell-anchor derivation (LOCKED DECISION 1): one GROUP BY
+    // max(occurredAt) over the qualifying event for THIS chunk, mirroring the
+    // priorCounts GROUP BY above (never per-user serial queries). Only computed
+    // when the criteria shape exposes a cheap per-matcher anchor event; an empty
+    // map leaves dwellAnchorAt NULL → the dwell gate falls back to enteredAt.
+    let anchorByUser = new Map<string, Date>();
+    if (anchorEvent != null) {
+      const anchors = await db
+        .select({
+          userId: userEvents.userId,
+          lastAt: max(userEvents.occurredAt),
+        })
+        .from(userEvents)
+        .where(
+          and(
+            eq(userEvents.event, anchorEvent),
+            inArray(userEvents.userId, chunk),
+          ),
+        )
+        .groupBy(userEvents.userId);
+      anchorByUser = new Map(
+        anchors
+          .filter(
+            (r): r is { userId: string; lastAt: Date } => r.lastAt != null,
+          )
+          .map((r) => [r.userId, r.lastAt]),
+      );
+    }
+
     const rows = chunk.map((userId) => ({
       userId,
       userEmail: emailByUser.get(userId) ?? null,
@@ -262,6 +303,8 @@ async function backfillJoins(opts: {
       entryCount: 1 + (priorByUser.get(userId) ?? 0),
       expiresAt: computeExpiresAt(bucket),
       maxDwellAt,
+      // Historical dwell anchor where derivable; NULL otherwise (→ enteredAt).
+      dwellAnchorAt: anchorByUser.get(userId) ?? null,
       lastEvaluatedAt: new Date(),
     }));
 
@@ -365,6 +408,7 @@ async function reevalLeaves(opts: {
         userEmail: row.userEmail,
         epoch: row.entryCount,
         source: "backfill",
+        reason: "criteria",
       });
     }
     leftCount += flipped.length;
@@ -504,6 +548,51 @@ async function selectCompositeMatchers(
   return matchers;
 }
 
+/**
+ * Resolve the event whose `max(occurredAt)` is the historical dwell anchor for a
+ * backfilled member (LOCKED DECISION 1 / Section 6.3) — "when they became
+ * dormant". Returns an event name only for the windowed/event shapes that expose
+ * a cheap per-matcher timestamp; `null` for everything else (the anchor stays
+ * NULL and the dwell gate falls back to `enteredAt`):
+ *
+ *   - a single windowed `event` criterion → its `eventName` (the last qualifying
+ *     occurrence is the window boundary, e.g. the last `app_opened`).
+ *   - the lapsed-active composite `all(event(X).exists(),
+ *     event(X).within(W).not_exists())` → event X (the flagship went-dormant
+ *     shape; the last X is when they lapsed).
+ *
+ * Other shapes (property/count composites, OR-of-absence, multi-event) have no
+ * single cheap per-matcher timestamp, so they keep a NULL anchor.
+ */
+function resolveDwellAnchorEvent(criteria: ConditionEval): string | null {
+  if (criteria.type === "event") {
+    return criteria.within != null ? criteria.eventName : null;
+  }
+  // Lapsed-active composite — two legs on the SAME event X: an unwindowed
+  // exists() anchor and a windowed not_exists() leg. Mirrors
+  // isLapsedActiveComposite in bucket-reconcile.ts.
+  if (
+    criteria.type === "composite" &&
+    criteria.operator === "and" &&
+    criteria.conditions.length === 2
+  ) {
+    const existsLeg = criteria.conditions.find(
+      (c) => c.type === "event" && c.check === "exists" && c.within == null,
+    );
+    const notExistsLeg = criteria.conditions.find(
+      (c) => c.type === "event" && c.check === "not_exists" && c.within != null,
+    );
+    if (
+      existsLeg?.type === "event" &&
+      notExistsLeg?.type === "event" &&
+      existsLeg.eventName === notExistsLeg.eventName
+    ) {
+      return notExistsLeg.eventName;
+    }
+  }
+  return null;
+}
+
 /**
  * Upsert the bucket's current criteria fingerprint onto `bucket_configs` (Section
  * 6.6 B). Mirrors the admin enable/disable onConflictDoUpdate target.