@hogsend/engine 0.4.0 → 0.6.0

package/src/buckets/registry.ts

@@ -1,4 +1,5 @@
 import { BucketRegistry } from "@hogsend/core/registry";
+import type { DefinedJourney } from "../journeys/define-journey.js";
 import { parseEnabledFilter } from "../journeys/registry.js";
 import { bucketExpiryTask } from "../workflows/bucket-reconcile.js";
 import type { DefinedBucket } from "./define-bucket.js";
@@ -60,3 +61,83 @@ export function selectBucketTasks(
   // the DefinedBucket task shape — both are `hatchet.durableTask` returns.
   return [bucketExpiryTask as NonNullable<DefinedBucket["task"]>];
 }
+
+/**
+ * Select the Hatchet durable tasks for the reaction journeys generated by
+ * `bucket.on()` across the ENABLED buckets (Section 9). Reactions are
+ * bucket-owned, so they are gated by `ENABLED_BUCKETS` — NOT `ENABLED_JOURNEYS`
+ * (their `bucket-<id>-on-<kind>` ids never appear in a consumer's
+ * `ENABLED_JOURNEYS` csv, so folding them into the journeys[] array would drop
+ * every reaction whenever ENABLED_JOURNEYS is a csv).
+ *
+ * Asserts no reaction-id collision (a build-time loud failure) before returning.
+ */
+export function selectBucketReactionTasks(
+  buckets: DefinedBucket[],
+  enabledFilter?: string,
+  userJourneyIds?: Iterable<string>,
+): NonNullable<DefinedBucket["task"]>[] {
+  const enabled = parseEnabledFilter(enabledFilter);
+  const enabledBuckets = buckets.filter(
+    (b) => enabled === "*" || enabled.has(b.meta.id),
+  );
+  // Loud boot failure on a duplicate reaction id / user-journey collision
+  // instead of a silent register-last-wins drop (Section 9). Pass the consumer
+  // journey ids so a reaction id colliding with a hand-written journey throws.
+  assertNoReactionIdCollisions(enabledBuckets, userJourneyIds);
+  return enabledBuckets.flatMap((b) =>
+    b.reactions.map((r) => r.task),
+  ) as NonNullable<DefinedBucket["task"]>[];
+}
+
+/**
+ * Collect the reaction `DefinedJourney`s across the ENABLED buckets (Section 9).
+ * Bucket-gated by `ENABLED_BUCKETS` for the same reason as
+ * {@link selectBucketReactionTasks}. The container registers their metas into the
+ * journey registry directly (bypassing the ENABLED_JOURNEYS filter) so the admin
+ * `feedsJourneys` and the dwell cron can resolve them.
+ */
+export function collectBucketReactionJourneys(
+  buckets: DefinedBucket[],
+  enabledFilter?: string,
+): DefinedJourney[] {
+  const enabled = parseEnabledFilter(enabledFilter);
+  return buckets
+    .filter((b) => enabled === "*" || enabled.has(b.meta.id))
+    .flatMap((b) => b.reactions);
+}
+
+/**
+ * Reaction tasks register on Hatchet under `journey-${meta.id}`. Two buckets
+ * sharing an id, two reactions colliding on a generated id, or a user journey
+ * named `bucket-<id>-on-<kind>` collide silently (register-last-wins) or throw on
+ * boot. Throw a descriptive build-time error instead (Section 9).
+ *
+ * @param enabledBuckets the already-enabled buckets to scan.
+ * @param userJourneyIds ids of the consumer's hand-written journeys (optional);
+ *   a reaction id colliding with one of these throws.
+ */
+export function assertNoReactionIdCollisions(
+  enabledBuckets: DefinedBucket[],
+  userJourneyIds?: Iterable<string>,
+): void {
+  const seen = new Set<string>();
+  const userIds = new Set(userJourneyIds ?? []);
+
+  for (const bucket of enabledBuckets) {
+    for (const reaction of bucket.reactions) {
+      const id = reaction.meta.id;
+      if (seen.has(id)) {
+        throw new Error(
+          `Bucket reaction id collision: "${id}" is generated by more than one reaction (check for duplicate bucket ids or two reactions of the same kind on bucket "${bucket.meta.id}").`,
+        );
+      }
+      if (userIds.has(id)) {
+        throw new Error(
+          `Bucket reaction id collision: generated reaction "${id}" (bucket "${bucket.meta.id}") collides with a user journey of the same id.`,
+        );
+      }
+      seen.add(id);
+    }
+  }
+}

package/src/container.ts

@@ -1,5 +1,5 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { TimeZone } from "@hogsend/core";
+import type { EmailProvider, PostHogService, TimeZone } from "@hogsend/core";
 import type { BucketRegistry, JourneyRegistry } from "@hogsend/core/registry";
 import type { SendWindow } from "@hogsend/core/schedule";
 import {
@@ -9,19 +9,22 @@ import {
   type JournalShape,
 } from "@hogsend/db";
 import type { TemplateRegistry } from "@hogsend/email";
-import type { PostHogService } from "@hogsend/plugin-posthog";
 import {
   createResendClient,
   createResendProvider,
-  type EmailProvider,
 } 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";
 import { buildJourneyRegistry } from "./journeys/registry.js";
+import { setAnalytics } from "./lib/analytics-singleton.js";
 import { type Auth, createAuth } from "./lib/auth.js";
 import { setEmailService } from "./lib/email.js";
 import type {
@@ -201,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 ??
@@ -251,8 +282,17 @@ export function createHogsendClient(
 
   const analytics = opts.analytics ?? getPostHog();
 
-  logger.info(`Journey registry loaded: ${registry.count()} journeys`);
-  logger.info(`Bucket registry loaded: ${bucketRegistry.count()} buckets`);
+  // Expose the resolved analytics instance to the module-level task-execution
+  // sites that have no client reference (the journey durable task in
+  // define-journey, the bucket PostHog sync). `createHogsendClient` runs in both
+  // the API and worker, so this is installed before any worker task runs. May be
+  // undefined (no POSTHOG_API_KEY) — the reads stay no-ops.
+  setAnalytics(analytics);
+
+  // Counts are surfaced by the boot banner / structured ready log (lib/boot.ts);
+  // keep these at debug for non-boot contexts (tests, REPL, library use).
+  logger.debug(`Journey registry loaded: ${registry.count()} journeys`);
+  logger.debug(`Bucket registry loaded: ${bucketRegistry.count()} buckets`);
 
   return {
     env,

package/src/env.ts

@@ -1,6 +1,13 @@
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
+/**
+ * The HTTP API contract version — surfaced in the OpenAPI document
+ * (`info.version`) and the `GET /v1/health` body. This is the WIRE contract
+ * version and is independent of the `@hogsend/engine` npm package version: bump
+ * it only on an API-breaking change (a new `/vN` route family), NOT on every
+ * package release. The `/v1` route prefix is hardcoded separately.
+ */
 export const API_VERSION = "0.0.1";
 
 export const env = createEnv({

package/src/index.ts

@@ -3,6 +3,22 @@
 // Content (journeys, webhook sources, workflows) is injected into these
 // factories by client app code; the engine never imports content.
 
+// --- Capability-provider contracts (canonical origin: @hogsend/core) ---
+// Email provider contract + analytics contract, re-exported so consumers can
+// import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
+// omitted here: the engine's public `SendEmailOptions` is the high-level
+// journey-facing send options from `./lib/email.js`; the provider-contract
+// `SendEmailOptions` remains available via `@hogsend/core`.)
+export type {
+  BatchEmailItem,
+  CaptureOptions,
+  EmailProvider,
+  PostHogService,
+  SendResult,
+  WebhookEvent,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/core";
 // Core helpers used by content journeys (days/hours/minutes, condition + journey
 // types) so content can import everything from `@hogsend/engine`.
 export * from "@hogsend/core";
@@ -23,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,
@@ -34,6 +62,8 @@ export {
 } from "./buckets/define-bucket.js";
 export {
   buildBucketRegistry,
+  collectBucketReactionJourneys,
+  selectBucketReactionTasks,
   selectBucketTasks,
 } from "./buckets/registry.js";
 export {
@@ -73,6 +103,14 @@ export {
   type BatchedBackfillResult,
   runBatchedBackfill,
 } from "./lib/backfill.js";
+// --- Boot output (engine-owned startup banner / structured ready log) ---
+export {
+  type ApiReadyInfo,
+  getEngineVersion,
+  reportApiReady,
+  reportWorkerReady,
+  type WorkerReadyInfo,
+} from "./lib/boot.js";
 // --- Bucket transition emission (shared by real-time / cron / fast-expiry) ---
 export {
   type BucketTransitionSource,

package/src/journeys/define-journey.ts

@@ -7,6 +7,7 @@ import type {
 } from "@hogsend/core/types";
 import { contacts, journeyConfigs, journeyStates } from "@hogsend/db";
 import { and, eq, inArray, notInArray } from "drizzle-orm";
+import { getAnalytics } from "../lib/analytics-singleton.js";
 import { getDb } from "../lib/db.js";
 import {
   checkEmailPreferences,
@@ -14,7 +15,6 @@ import {
 } from "../lib/enrollment-guards.js";
 import { hatchet } from "../lib/hatchet.js";
 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 { JOURNEY_EXECUTION_TIMEOUT } from "./constants.js";
@@ -131,7 +131,9 @@ export function defineJourney(options: {
         journeyName: meta.name,
       };
 
-      const posthog = getPostHog();
+      // The injected analytics instance (set by createHogsendClient). Same
+      // object as container.analytics; undefined when POSTHOG_API_KEY is unset.
+      const posthog = getAnalytics();
       const scheduleDefaults = getClientScheduleDefaults();
 
       // Resolve the user's timezone via the precedence chain (explicit is N/A

package/src/journeys/journey-context.ts

@@ -7,7 +7,7 @@ import {
   SleepCondition,
   UserEventCondition,
 } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { DurationObject } from "@hogsend/core";
+import type { DurationObject, PostHogService } from "@hogsend/core";
 import { durationToMs, evaluateEventCondition } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import {
@@ -26,7 +26,6 @@ import type {
   WhenBuilder,
 } from "@hogsend/core/types";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
-import type { PostHogService } from "@hogsend/plugin-posthog";
 import { and, count, eq, max, notInArray } from "drizzle-orm";
 import { checkEmailPreferences } from "../lib/enrollment-guards.js";
 import { ingestEvent } from "../lib/ingestion.js";

package/src/journeys/registry-singleton.ts

@@ -1,21 +1,9 @@
 import type { JourneyRegistry } from "@hogsend/core/registry";
+import { createSingleton } from "../lib/singleton.js";
 
-let _registry: JourneyRegistry | undefined;
-
-export function setJourneyRegistry(registry: JourneyRegistry): void {
-  _registry = registry;
-}
-
-export function getJourneyRegistrySingleton(): JourneyRegistry {
-  if (!_registry) {
-    throw new Error(
-      "Journey registry not initialized. Call setJourneyRegistry() at startup.",
-    );
-  }
-  return _registry;
-}
+const singleton = createSingleton<JourneyRegistry>("Journey registry");
 
+export const setJourneyRegistry = singleton.set;
+export const getJourneyRegistrySingleton = singleton.get;
 /** Reset the singleton — only for test cleanup. */
-export function resetJourneyRegistry(): void {
-  _registry = undefined;
-}
+export const resetJourneyRegistry = singleton.reset;

package/src/lib/alerting.ts

@@ -17,7 +17,6 @@ async function dispatchAlert(opts: {
   rule: typeof alertRules.$inferSelect;
   message: string;
   payload: Record<string, unknown>;
-  resendApiKey?: string;
 }): Promise<{ deliveryStatus: string; error?: string }> {
   const config = opts.rule.channelConfig as Record<string, string>;
   switch (opts.rule.channel) {
@@ -45,7 +44,6 @@ async function dispatchAlert(opts: {
         to: config.to ?? "",
         subject: `[Hogsend Alert] ${opts.rule.name}`,
         body: `<p>${opts.message}</p><pre>${JSON.stringify(opts.payload, null, 2)}</pre>`,
-        resendApiKey: opts.resendApiKey ?? "",
       });
       return result.ok
         ? { deliveryStatus: "sent" }
@@ -62,7 +60,6 @@ async function dispatchAlert(opts: {
 export async function checkAlertRules(opts: {
   db: Database;
   logger: Logger;
-  resendApiKey?: string;
 }): Promise<void> {
   const { db, logger } = opts;
 
@@ -174,7 +171,6 @@ export async function checkAlertRules(opts: {
         rule,
         message,
         payload,
-        resendApiKey: opts.resendApiKey,
       });
 
       await Promise.all([

package/src/lib/analytics-singleton.ts

@@ -0,0 +1,25 @@
+import type { PostHogService } from "@hogsend/core";
+import { createOptionalSingleton } from "./singleton.js";
+
+/**
+ * The injected analytics service, set once by `createHogsendClient` and read by
+ * the module-level task-execution sites that have no client reference of their
+ * own (the journey durable task in `define-journey`, the bucket PostHog sync).
+ *
+ * Mirrors the journey/bucket-registry + client-schedule-defaults singletons:
+ * `createHogsendClient` runs in BOTH the API and worker processes, so by the
+ * time any worker task executes, the container has already installed the
+ * resolved `analytics` instance here — the SAME object exposed on
+ * `HogsendClient.analytics`. This makes a swapped `opts.analytics` actually
+ * load-bearing at those sites instead of falling back to the module singleton.
+ *
+ * `undefined` is a first-class value: when `POSTHOG_API_KEY` is unset the
+ * container resolves `analytics` to `undefined` and installs it here, so every
+ * read remains a no-op exactly as before — hence the optional singleton variant.
+ */
+const singleton = createOptionalSingleton<PostHogService>();
+
+export const setAnalytics = singleton.set;
+export const getAnalytics = singleton.get;
+/** Reset the singleton — only for test cleanup. */
+export const resetAnalytics = singleton.reset;

package/src/lib/boot.ts

@@ -0,0 +1,176 @@
+import { createRequire } from "node:module";
+import color from "picocolors";
+import type { HogsendClient } from "../container.js";
+import { API_VERSION } from "../env.js";
+
+/**
+ * Engine-owned boot output. ONE place renders the "we're up" message for the
+ * API and the worker, so every scaffolded `create-hogsend` app gets the same
+ * polished startup for free — the entry points just call these.
+ *
+ * Two modes, picked from the environment (never a flag):
+ *  - banner: a branded, minimal box (the `create-hogsend` look — magenta badge,
+ *    ✓ checks, cyan links) printed straight to stdout. Only when stdout is a TTY
+ *    AND `NODE_ENV === "development"`, i.e. an interactive `pnpm dev`.
+ *  - structured: a single `logger.info("… ready", { … })` line. Everywhere else
+ *    (production, CI, piped output, tests) so log scraping stays intact.
+ *
+ * The scattered `registry loaded` / `studio mounted` / `server running` lines
+ * are demoted to `debug`; this banner is the single source of truth on boot.
+ */
+
+// Last-resort value when the runtime manifest read below fails (e.g. a pruned
+// node_modules behind a bundler). The read is authoritative in every normal dev
+// run and deploy, so this is effectively never hit — `"unknown"` keeps it honest
+// rather than risking a stale hard-coded version slipping into structured logs.
+const FALLBACK_ENGINE_VERSION = "unknown";
+
+// Conventional Vite dev-server origin for the Studio package (`pnpm dev` starts
+// it). In production the Studio is served by the API at `${API_PUBLIC_URL}/studio`.
+const STUDIO_DEV_URL = "http://localhost:5173";
+const DOCS_URL = "https://docs.hogsend.com";
+
+let cachedEngineVersion: string | undefined;
+
+/** The running `@hogsend/engine` package version (e.g. "0.4.0"). */
+export function getEngineVersion(): string {
+  if (cachedEngineVersion) return cachedEngineVersion;
+  try {
+    // Resolve the engine's own manifest from the consumer's module graph —
+    // correct under tsx (workspace symlink) and a bundled deploy alike. Needs
+    // `"./package.json"` in this package's `exports`.
+    const require = createRequire(import.meta.url);
+    const pkg = require("@hogsend/engine/package.json") as { version?: string };
+    cachedEngineVersion = pkg.version ?? FALLBACK_ENGINE_VERSION;
+  } catch {
+    cachedEngineVersion = FALLBACK_ENGINE_VERSION;
+  }
+  return cachedEngineVersion;
+}
+
+const BADGE = color.bgMagenta(color.black(" hogsend "));
+
+/** Interactive `pnpm dev` in a real terminal — the only place the banner shows. */
+function bannerMode(client: HogsendClient): boolean {
+  return Boolean(process.stdout.isTTY) && client.env.NODE_ENV === "development";
+}
+
+function plural(n: number, word: string): string {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+function writeBanner(lines: (string | null)[]): void {
+  const body = lines.filter((l): l is string => l !== null).join("\n");
+  process.stdout.write(`\n${body}\n\n`);
+}
+
+export interface ApiReadyInfo {
+  client: HogsendClient;
+  /** The port the HTTP server bound to. */
+  port: number;
+  /** Applied engine-track schema version, when the boot guard ran. */
+  schemaVersion?: string | null;
+}
+
+/** Render the API "ready" output (banner in dev TTY, structured log otherwise). */
+export function reportApiReady(info: ApiReadyInfo): void {
+  const { client, port } = info;
+  const engineVersion = getEngineVersion();
+  const journeys = client.registry.count();
+  const buckets = client.bucketRegistry.count();
+  const templates = Object.keys(client.templates).length;
+  const localUrl = `http://localhost:${port}`;
+
+  if (!bannerMode(client)) {
+    client.logger.info("Hogsend API ready", {
+      engineVersion,
+      apiVersion: API_VERSION,
+      port,
+      url: client.env.API_PUBLIC_URL,
+      journeys,
+      buckets,
+      templates,
+      schema: info.schemaVersion ?? undefined,
+    });
+    return;
+  }
+
+  const dim = color.dim;
+  const ok = color.green("✓");
+  const loaded = [
+    plural(journeys, "journey"),
+    plural(buckets, "bucket"),
+    plural(templates, "template"),
+  ].join(dim(" · "));
+  const label = (text: string) => dim(text.padEnd(7));
+
+  writeBanner([
+    `${BADGE} ${dim(`engine ${engineVersion} · api ${API_VERSION}`)}`,
+    "",
+    `  ${ok} ${loaded}`,
+    info.schemaVersion
+      ? `  ${ok} schema in sync ${dim(`(${info.schemaVersion})`)}`
+      : null,
+    "",
+    `  ${label("API")}${color.cyan(localUrl)}`,
+    `  ${label("Docs")}${color.cyan(`${localUrl}/docs`)}`,
+    `  ${label("Studio")}${color.cyan(STUDIO_DEV_URL)}`,
+    `  ${label("Guides")}${color.cyan(DOCS_URL)}`,
+    "",
+    `  ${dim("Next")}  fire a test event in ${color.cyan("Studio › Debug")} ${dim("·")} run the worker: ${color.cyan("pnpm worker:dev")}`,
+  ]);
+}
+
+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,
+    bucketReactionTasks,
+    builtinTasks,
+  } = info;
+  const engineVersion = getEngineVersion();
+  const hatchetHost = client.env.HATCHET_CLIENT_HOST_PORT;
+
+  if (!bannerMode(client)) {
+    client.logger.info("Hogsend worker ready", {
+      engineVersion,
+      hatchet: hatchetHost,
+      namespace: client.env.HATCHET_CLIENT_NAMESPACE || undefined,
+      journeyTasks,
+      bucketTasks,
+      bucketReactionTasks,
+      builtinTasks,
+    });
+    return;
+  }
+
+  const dim = color.dim;
+  const ok = color.green("✓");
+  const tasks = [
+    plural(journeyTasks, "journey task"),
+    plural(bucketTasks, "bucket task"),
+    plural(bucketReactionTasks, "reaction task"),
+    plural(builtinTasks, "built-in task"),
+  ].join(dim(" · "));
+
+  writeBanner([
+    `${BADGE} ${dim(`worker · engine ${engineVersion}`)}`,
+    "",
+    `  ${ok} registered on Hatchet ${dim(`(${hatchetHost})`)}`,
+    `  ${ok} ${tasks}`,
+    "",
+    `  ${dim("Listening — journeys fire as events arrive.")}`,
+    `  ${dim("Send one:")} ${color.cyan("POST /v1/ingest")} ${dim("· or Studio › Debug")}`,
+  ]);
+}

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,
     },
   });