@hogsend/engine 0.4.0 → 0.6.0

package/src/lib/bucket-posthog-sync.ts

@@ -1,12 +1,12 @@
 import type { BucketMeta } from "@hogsend/core";
+import { getAnalytics } from "./analytics-singleton.js";
 import type { Logger } from "./logger.js";
-import { getPostHog } from "./posthog.js";
 
 /**
  * Optional PostHog person-property mirror for a bucket transition (Section 12).
  *
  * OFF BY DEFAULT — a no-op unless `meta.syncToPostHog === true`. Also a no-op
- * without `POSTHOG_API_KEY` (`getPostHog()` returns undefined), so self-host
+ * without `POSTHOG_API_KEY` (the injected analytics is undefined), so self-host
  * setups that omit PostHog silently do nothing — documented, not broken.
  *
  * On JOIN it `$set`s a boolean person property `true`; on LEAVE it `$unset`s the
@@ -32,8 +32,10 @@ export function syncBucketToPostHog(opts: {
 
   if (!bucket.syncToPostHog) return;
 
-  const posthog = getPostHog();
-  if (!posthog) return; // no POSTHOG_API_KEY → silent no-op
+  // The injected analytics instance (set by createHogsendClient). Same object as
+  // container.analytics; undefined when POSTHOG_API_KEY is unset.
+  const posthog = getAnalytics();
+  if (!posthog) return; // no analytics configured → silent no-op
 
   const propertyKey =
     bucket.postHogPropertyKey ?? `hogsend_bucket_${bucket.id}`;

package/src/lib/email-service-types.ts

@@ -1,4 +1,11 @@
-import type { DurationObject } from "@hogsend/core";
+import type {
+  BatchEmailItem,
+  DurationObject,
+  SendEmailOptions,
+  SendResult,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/core";
 import type {
   EmailServiceRenderOptions,
   EmailServiceRenderResult,
@@ -7,20 +14,22 @@ import type {
   TemplateRegistry,
   TemplateRegistryMap,
 } from "@hogsend/email";
-import type {
-  BatchEmailItem,
-  SendEmailOptions,
-  SendResult,
-  WebhookEventType,
-  WebhookHandlerMap,
-} from "@hogsend/plugin-resend";
 import type { Logger } from "./logger.js";
 
 export type {
   BatchEmailItem,
   SendEmailOptions,
   SendResult,
-} from "@hogsend/plugin-resend";
+} from "@hogsend/core";
+
+/**
+ * Input to the mailer's low-level {@link EmailService.sendRaw}: the provider
+ * contract's `SendEmailOptions`, but `from` is optional — the mailer resolves it
+ * from `config.defaultFrom` when absent (see `resolveFrom` in mailer.ts). The
+ * wire contract keeps `from` required because the provider always receives a
+ * resolved address.
+ */
+export type SendRawOptions = Omit<SendEmailOptions, "from"> & { from?: string };
 
 // ---------------------------------------------------------------------------
 // Tracked email (high-level API)
@@ -136,7 +145,7 @@ export interface EmailService {
     options: EmailServiceSendOptions<K>,
   ): Promise<TrackedSendResult>;
 
-  sendRaw(options: SendEmailOptions): Promise<SendResult>;
+  sendRaw(options: SendRawOptions): Promise<SendResult>;
 
   sendBatch(options: { emails: BatchEmailItem[] }): Promise<{
     results: SendResult[];

package/src/lib/email.ts

@@ -3,21 +3,23 @@ import type {
   EmailService,
   EmailServiceSendOptions,
 } from "./email-service-types.js";
+import { createSingleton } from "./singleton.js";
 
-let _service: EmailService | null = null;
+const _service = createSingleton<EmailService>("Email service");
 
-export function setEmailService(service: EmailService): void {
-  _service = service;
-}
+export const setEmailService = _service.set;
 
-function getService(): EmailService {
-  if (!_service) {
-    throw new Error(
-      "Email service not initialized. Call setEmailService() at startup.",
-    );
-  }
-  return _service;
-}
+/**
+ * The injected {@link EmailService} (set by `createHogsendClient` →
+ * `setEmailService`). Exposed so module-level task-execution sites with no
+ * client reference (the `send-email` Hatchet task, the alerting task) deliver
+ * through the same provider-backed mailer the container built, honoring a
+ * swapped provider instead of constructing a raw Resend client of their own.
+ * Throws if read before the container has installed the service — same
+ * guarantee as the journey/bucket registry singletons (the container always
+ * runs first in both the API and worker processes).
+ */
+export const getEmailService = _service.get;
 
 export interface SendEmailOptions {
   to: string;
@@ -37,7 +39,7 @@ export interface SendEmailResult {
 export async function sendEmail(
   opts: SendEmailOptions,
 ): Promise<SendEmailResult> {
-  const service = getService();
+  const service = getEmailService();
 
   let unsubscribeUrl: string | undefined;
   if (process.env.API_PUBLIC_URL && process.env.BETTER_AUTH_SECRET) {

package/src/lib/mailer.ts

@@ -1,3 +1,10 @@
+import type {
+  BatchEmailItem,
+  EmailProvider,
+  WebhookEvent,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/core";
 import type { Database } from "@hogsend/db";
 import { emailPreferences, emailSends } from "@hogsend/db";
 import type {
@@ -6,13 +13,6 @@ import type {
   TemplateName,
 } from "@hogsend/email";
 import { getTemplate, renderToHtml, renderToPlainText } from "@hogsend/email";
-import type {
-  BatchEmailItem,
-  EmailProvider,
-  WebhookEvent,
-  WebhookEventType,
-  WebhookHandlerMap,
-} from "@hogsend/plugin-resend";
 import { eq, sql } from "drizzle-orm";
 import type {
   EmailService,
@@ -20,7 +20,7 @@ import type {
   EmailServiceSendOptions,
   EmailServiceWebhookOptions,
   EmailServiceWebhookResult,
-  SendEmailOptions,
+  SendRawOptions,
   SendResult,
   TrackedSendResult,
 } from "./email-service-types.js";
@@ -125,7 +125,7 @@ export function createTrackedMailer(
       };
     },
 
-    async sendRaw(options: SendEmailOptions): Promise<SendResult> {
+    async sendRaw(options: SendRawOptions): Promise<SendResult> {
       return provider.send({ ...options, from: resolveFrom(options.from) });
     },
 

package/src/lib/notifications.ts

@@ -1,3 +1,5 @@
+import { getEmailService } from "./email.js";
+
 export async function sendWebhook(
   url: string,
   payload: Record<string, unknown>,
@@ -32,25 +34,22 @@ export async function sendSlackNotification(
   return sendWebhook(webhookUrl, { text });
 }
 
-import { createResendClient } from "@hogsend/plugin-resend";
-
 export async function sendEmailNotification(opts: {
   to: string;
   subject: string;
   body: string;
-  resendApiKey: string;
 }): Promise<{ ok: boolean; error?: string }> {
   try {
-    const client = createResendClient({ apiKey: opts.resendApiKey });
-    const { error } = await client.emails.send({
+    // Route through the injected EmailProvider (via the mailer's `sendRaw`)
+    // instead of constructing a raw Resend client from process.env. The
+    // alerting task runs under the worker, where createHogsendClient has already
+    // installed the email service.
+    await getEmailService().sendRaw({
       from: "Hogsend Alerts <alerts@hogsend.com>",
       to: opts.to,
       subject: opts.subject,
       html: opts.body,
     });
-    if (error) {
-      return { ok: false, error: error.message };
-    }
     return { ok: true };
   } catch (err) {
     return {

package/src/lib/posthog.ts

@@ -1,7 +1,5 @@
-import {
-  createPostHogService,
-  type PostHogService,
-} from "@hogsend/plugin-posthog";
+import type { PostHogService } from "@hogsend/core";
+import { createPostHogService } from "@hogsend/plugin-posthog";
 import { getRedis } from "./redis.js";
 
 let _posthog: PostHogService | undefined;

package/src/lib/singleton.ts

@@ -0,0 +1,56 @@
+/**
+ * Tiny process-singletons: a value set once by `createHogsendClient` at startup
+ * and read by module-level task-execution sites that have no client reference of
+ * their own (journey/bucket durable tasks, the send-email task). Replaces the
+ * hand-rolled `let _x` + set/get/reset trios that were copied across the engine.
+ *
+ * Two variants:
+ * - `createSingleton` — required: `get()` throws if read before it is set.
+ * - `createOptionalSingleton` — `undefined` is a legitimate value (e.g. analytics
+ *   with no `POSTHOG_API_KEY`); `get()` returns `T | undefined` and never throws.
+ */
+
+export interface Singleton<T> {
+  set(value: T): void;
+  get(): T;
+  reset(): void;
+}
+
+export interface OptionalSingleton<T> {
+  set(value: T | undefined): void;
+  get(): T | undefined;
+  reset(): void;
+}
+
+export function createSingleton<T>(name: string): Singleton<T> {
+  let value: T | undefined;
+  return {
+    set(next: T): void {
+      value = next;
+    },
+    get(): T {
+      if (value === undefined) {
+        throw new Error(`${name} not initialized. Call its setter at startup.`);
+      }
+      return value;
+    },
+    reset(): void {
+      value = undefined;
+    },
+  };
+}
+
+export function createOptionalSingleton<T>(): OptionalSingleton<T> {
+  let value: T | undefined;
+  return {
+    set(next: T | undefined): void {
+      value = next;
+    },
+    get(): T | undefined {
+      return value;
+    },
+    reset(): void {
+      value = undefined;
+    },
+  };
+}

package/src/lib/tracked.ts

@@ -1,3 +1,4 @@
+import type { EmailProvider } from "@hogsend/core";
 import type { Database } from "@hogsend/db";
 import { emailPreferences, emailSends } from "@hogsend/db";
 import type {
@@ -7,7 +8,6 @@ import type {
   TemplateRegistry,
 } from "@hogsend/email";
 import { getTemplate, renderToHtml } from "@hogsend/email";
-import type { EmailProvider } from "@hogsend/plugin-resend";
 import { eq } from "drizzle-orm";
 import type {
   FrequencyCapConfig,

package/src/lib/tracking-events.ts

@@ -1,7 +1,7 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { PostHogService } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
-import type { PostHogService } from "@hogsend/plugin-posthog";
 import { eq } from "drizzle-orm";
 import { ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";

package/src/lib/worker-heartbeat.ts

@@ -0,0 +1,78 @@
+import type { Logger } from "./logger.js";
+import { getRedis } from "./redis.js";
+
+/**
+ * Worker liveness heartbeat. The worker and API are separate processes, so the
+ * API (and the Studio, via `GET /v1/health`) cannot otherwise tell whether a
+ * worker is actually connected — which is exactly the "journeys silently don't
+ * fire because the worker isn't running" footgun. The worker writes a TTL'd key
+ * to Redis on an interval; readers treat its presence as "a worker is alive".
+ *
+ * Redis is the channel because the health route already probes Redis and both
+ * processes can reach it — no direct process-to-process coupling, no migration.
+ * Everything here is best-effort: a missing/unreachable Redis never crashes the
+ * worker and simply reads back as "down".
+ */
+const HEARTBEAT_KEY = "hogsend:worker:heartbeat";
+const TTL_SECONDS = 30;
+const REFRESH_MS = 10_000;
+
+export interface WorkerHeartbeat {
+  /** True when a fresh worker heartbeat is present in Redis. */
+  alive: boolean;
+  /** ISO timestamp the worker last wrote, when alive. */
+  lastSeenAt?: string;
+}
+
+/**
+ * Begin writing the worker heartbeat. Writes once immediately, then refreshes
+ * every {@link REFRESH_MS} with a {@link TTL_SECONDS} expiry — so an ungraceful
+ * worker death is reflected as "down" within the TTL. Returns a stop function
+ * that clears the timer and deletes the key for an immediate "down" signal on
+ * graceful shutdown.
+ */
+export function startWorkerHeartbeat(logger: Logger): () => Promise<void> {
+  let warned = false;
+  const write = async () => {
+    try {
+      await getRedis().set(
+        HEARTBEAT_KEY,
+        new Date().toISOString(),
+        "EX",
+        TTL_SECONDS,
+      );
+    } catch (err) {
+      // Log the first failure only — a Redis-less deploy would otherwise spam.
+      if (!warned) {
+        warned = true;
+        logger.debug("Worker heartbeat write failed (Redis unreachable?)", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  };
+
+  void write();
+  const timer = setInterval(() => void write(), REFRESH_MS);
+  // Never hold the process open for the heartbeat alone.
+  timer.unref?.();
+
+  return async () => {
+    clearInterval(timer);
+    try {
+      await getRedis().del(HEARTBEAT_KEY);
+    } catch {
+      // Best-effort — the TTL expires it anyway.
+    }
+  };
+}
+
+/** Read the current worker heartbeat. Resolves to `{ alive: false }` if Redis is unreachable. */
+export async function getWorkerHeartbeat(): Promise<WorkerHeartbeat> {
+  try {
+    const lastSeenAt = await getRedis().get(HEARTBEAT_KEY);
+    return lastSeenAt ? { alive: true, lastSeenAt } : { alive: false };
+  } catch {
+    return { alive: false };
+  }
+}

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/routes/health.ts

@@ -4,12 +4,21 @@ import { sql } from "drizzle-orm";
 import type { AppEnv } from "../app.js";
 import { API_VERSION } from "../env.js";
 import { getRedis } from "../lib/redis.js";
+import { getWorkerHeartbeat } from "../lib/worker-heartbeat.js";
 
 const componentSchema = z.object({
   status: z.enum(["up", "down"]),
   latencyMs: z.number().optional(),
 });
 
+// Worker connectivity, derived from the Redis heartbeat. Informational only —
+// the worker is a separate service, so its absence does NOT make the API
+// "degraded" (that would falsely fail the API's own healthcheck).
+const workerComponentSchema = z.object({
+  status: z.enum(["up", "down"]),
+  lastSeenAt: z.string().optional(),
+});
+
 // Per-track schema version block. Two tracks: `engine` (bundled @hogsend/db
 // migrations) and `client` (the client repo's own migrations). See
 // docs/UPGRADING.md "Two-track migrations".
@@ -28,6 +37,7 @@ const healthResponseSchema = z.object({
   components: z.object({
     database: componentSchema,
     redis: componentSchema,
+    worker: workerComponentSchema,
   }),
   schema: z.object({
     engine: trackSchema,
@@ -73,7 +83,7 @@ export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
   async (c) => {
     const { db, clientJournal } = c.get("container");
 
-    const [dbCheck, redisCheck, engine, client] = await Promise.all([
+    const [dbCheck, redisCheck, heartbeat, engine, client] = await Promise.all([
       checkComponent(async () => {
         await db.execute(sql`SELECT 1`);
       }),
@@ -86,6 +96,7 @@ export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
         // host is genuinely unreachable → a truthful "down").
         await getRedis().ping();
       }),
+      getWorkerHeartbeat(),
       getEngineSchemaVersion(db),
       getClientSchemaVersion(db, clientJournal ?? { entries: [] }),
     ]);
@@ -123,6 +134,10 @@ export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
         components: {
           database: dbCheck,
           redis: redisCheck,
+          worker: {
+            status: heartbeat.alive ? ("up" as const) : ("down" as const),
+            lastSeenAt: heartbeat.lastSeenAt,
+          },
         },
       },
       200,

package/src/worker.ts

@@ -1,11 +1,15 @@
 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";
+import { reportWorkerReady } from "./lib/boot.js";
 import { hatchet } from "./lib/hatchet.js";
-import { getPostHog } from "./lib/posthog.js";
 import { getRedisIfConnected } from "./lib/redis.js";
+import { startWorkerHeartbeat } from "./lib/worker-heartbeat.js";
 import {
   bucketBackfillTask,
   enqueueBucketBackfills,
@@ -45,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,
@@ -54,6 +67,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     bucketBackfillTask,
     ...journeyTasks,
     ...bucketTasks,
+    ...bucketReactionTasks,
   ];
   const workflows = [
     ...baseWorkflows,
@@ -63,21 +77,47 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
   // Hatchet's worker is created lazily on start so signal wiring can own its
   // lifecycle. `_worker` is captured for stop().
   let _worker: Awaited<ReturnType<typeof hatchet.worker>> | undefined;
+  let _stopHeartbeat: (() => Promise<void>) | undefined;
 
   async function stop(): Promise<void> {
+    // Delete the heartbeat first (an immediate "worker down" signal) before the
+    // Redis connection is torn down below.
+    await _stopHeartbeat?.();
     await Promise.allSettled([
       _worker?.stop(),
-      getPostHog()?.shutdown(),
+      // Shut down the injected analytics instance (same object the worker's
+      // tasks use), not the module singleton. Undefined when no analytics is
+      // configured — the optional chain makes that a no-op.
+      container.analytics?.shutdown(),
       getRedisIfConnected()?.quit(),
     ]);
   }
 
   async function start(): Promise<void> {
+    // Emit BEFORE the Hatchet handshake: proves the process booted past init
+    // even while the connection is still establishing (the worker banner /
+    // "ready" line only fires once `hatchet.worker()` resolves).
+    container.logger.info("Hogsend worker starting", {
+      hatchet: container.env.HATCHET_CLIENT_HOST_PORT,
+    });
+
     _worker = await hatchet.worker("hogsend-worker", { workflows });
 
-    container.logger.info(
-      `Hogsend worker started with ${journeyTasks.length} journey task(s)`,
-    );
+    reportWorkerReady({
+      client: container,
+      journeyTasks: journeyTasks.length,
+      bucketTasks: bucketTasks.length,
+      bucketReactionTasks: bucketReactionTasks.length,
+      builtinTasks:
+        baseWorkflows.length -
+        journeyTasks.length -
+        bucketTasks.length -
+        bucketReactionTasks.length,
+    });
+
+    // Publish liveness so the API + Studio can show "worker connected"
+    // (read via GET /v1/health). Best-effort; never blocks the listener.
+    _stopHeartbeat = startWorkerHeartbeat(container.logger);
 
     // Boot-time backfill / criteria-change re-eval (Section 6.6 B): diff each
     // enabled bucket's criteriaHash against bucket_configs and trigger a