@hogsend/engine 0.4.0 → 0.5.0

package/README.md

@@ -5,6 +5,14 @@ The Hogsend framework: `createApp`, `createHogsendClient`, `createWorker`,
 built-in routes, and the registries. This is the public API surface consumers
 build their lifecycle apps on top of.
 
+The engine also re-exports the capability-provider contracts owned by
+`@hogsend/core` — `EmailProvider` and `PostHogService` (plus their supporting
+types) — so `@hogsend/engine` is the **canonical author import** for them when
+writing a custom provider. (The contract-level `SendEmailOptions` is the one
+exception: it stays on `@hogsend/core`, since the engine exports a different,
+higher-level `SendEmailOptions`.) See
+[docs/adr/0001-provider-boundary.md](https://github.com/dougwithseismic/hogsend/blob/main/docs/adr/0001-provider-boundary.md).
+
 Scaffold a consumer app with `pnpm dlx create-hogsend@latest`. The engine line
 (`@hogsend/engine`, `@hogsend/db`, `@hogsend/core`) is versioned in lockstep so a
 new engine migration always bumps the engine and DB together; the boot guard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,8 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./worker": "./src/worker.ts"
+    "./worker": "./src/worker.ts",
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
@@ -32,14 +33,15 @@
     "hono": "^4.12.22",
     "ioredis": "^5.10.1",
     "papaparse": "^5.5.3",
+    "picocolors": "^1.1.1",
     "resend": "^6.12.3",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@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"
+    "@hogsend/core": "^0.5.0",
+    "@hogsend/db": "^0.5.0",
+    "@hogsend/email": "^0.5.0",
+    "@hogsend/plugin-posthog": "^0.5.0",
+    "@hogsend/plugin-resend": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/app.ts

@@ -103,7 +103,7 @@ export function createApp(
   // No-op when no built dist is present, so an unbuilt studio never crashes boot.
   const studio = mountStudio(app);
   if (studio.mounted) {
-    container.logger.info(
+    container.logger.debug(
       `Studio mounted at /studio (dist: ${studio.distPath})`,
     );
   }

package/src/buckets/registry-singleton.ts

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

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,11 +9,9 @@ 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 type { DefinedBucket } from "./buckets/define-bucket.js";
@@ -22,6 +20,7 @@ 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 {
@@ -251,8 +250,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";
@@ -73,6 +89,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,166 @@
+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;
+  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 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,
+      builtinTasks,
+    });
+    return;
+  }
+
+  const dim = color.dim;
+  const ok = color.green("✓");
+  const tasks = [
+    plural(journeyTasks, "journey task"),
+    plural(bucketTasks, "bucket 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-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/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

@@ -3,9 +3,10 @@ import { 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,
@@ -63,21 +64,43 @@ 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,
+      builtinTasks:
+        baseWorkflows.length - journeyTasks.length - bucketTasks.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

package/src/workflows/check-alerts.ts

@@ -16,7 +16,6 @@ export const checkAlertsTask = hatchet.task({
     await checkAlertRules({
       db,
       logger,
-      resendApiKey: process.env.RESEND_API_KEY,
     });
 
     return { checked: true };

package/src/workflows/send-email.ts

@@ -1,22 +1,16 @@
 import { NonRetryableError } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import { createResendClient } from "@hogsend/plugin-resend";
+import { EmailSendError } from "@hogsend/email";
+import { getEmailService } from "../lib/email.js";
 import { hatchet } from "../lib/hatchet.js";
 
-const resend = createResendClient({
-  apiKey: process.env.RESEND_API_KEY ?? "",
-});
-
-const NON_RETRYABLE_CODES = new Set([
-  "validation_error",
-  "missing_required_field",
-  "invalid_api_key",
-  "not_found",
-  "restricted_api_key",
-]);
-
 export const sendEmailTask = hatchet.task({
   name: "send-email",
-  retries: 3,
+  // The EmailProvider owns transient-failure backoff internally (classified
+  // exponential retry in its `send`), and permanent failures fail fast below via
+  // NonRetryableError — so Hatchet's retry is just ONE durability re-attempt for a
+  // worker crash/timeout, not a second transient-retry loop layered on the
+  // provider's. (Previously 3, which multiplied with the provider's own retries.)
+  retries: 1,
   executionTimeout: "30s",
   backoff: { factor: 2, maxSeconds: 30 },
   fn: async (input: {
@@ -28,27 +22,35 @@ export const sendEmailTask = hatchet.task({
     tags?: Array<{ name: string; value: string }>;
     headers?: Record<string, string>;
   }) => {
-    const { data, error } = await resend.emails.send({
-      from:
-        input.from ??
-        process.env.RESEND_FROM_EMAIL ??
-        "Hogsend <noreply@hogsend.com>",
-      to: input.to,
-      subject: input.subject,
-      html: input.html,
-      replyTo: input.replyTo,
-      tags: input.tags,
-      headers: input.headers,
-    });
+    // Deliver through the injected, provider-backed mailer (set by
+    // createHogsendClient → setEmailService). `sendRaw` calls the swappable
+    // EmailProvider's `send`, resolving the default `from` from the mailer
+    // config — so a swapped provider is honored and this task no longer
+    // constructs a raw Resend client of its own. The provider already retries
+    // transient failures internally and surfaces a classified EmailSendError;
+    // map a non-retryable one to Hatchet's NonRetryableError so the task's own
+    // retry/backoff doesn't re-attempt a permanent failure.
+    const emailService = getEmailService();
 
-    if (error) {
-      const name = (error as { name?: string }).name ?? "";
-      if (NON_RETRYABLE_CODES.has(name)) {
-        throw new NonRetryableError(`${name}: ${error.message}`);
+    try {
+      // `from` is optional: when absent the mailer's `resolveFrom` falls back to
+      // its configured defaultFrom (env.RESEND_FROM_EMAIL).
+      const result = await emailService.sendRaw({
+        from: input.from,
+        to: input.to,
+        subject: input.subject,
+        html: input.html,
+        replyTo: input.replyTo,
+        tags: input.tags,
+        headers: input.headers,
+      });
+
+      return { emailId: result.id };
+    } catch (error) {
+      if (error instanceof EmailSendError && !error.retryable) {
+        throw new NonRetryableError(error.message);
       }
-      throw new Error(`Failed to send email: ${error.message}`);
+      throw error;
     }
-
-    return { emailId: data?.id ?? "" };
   },
 });