@hogsend/engine 0.3.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.3.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.3.0",
-    "@hogsend/email": "^0.3.0",
-    "@hogsend/db": "^0.3.0",
-    "@hogsend/plugin-posthog": "^0.3.0",
-    "@hogsend/plugin-resend": "^0.3.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";
@@ -54,6 +70,7 @@ export {
   type DefinedJourney,
   defineJourney,
 } from "./journeys/define-journey.js";
+export { JourneyExitedError } from "./journeys/errors.js";
 export { createJourneyContext } from "./journeys/journey-context.js";
 export {
   buildJourneyRegistry,
@@ -72,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/constants.ts

@@ -0,0 +1,14 @@
+/**
+ * Max active execution time configured on every journey durable task
+ * (`executionTimeout`). It is the single source of truth shared by
+ * `define-journey` (the task config) and `journey-context` (the `waitForEvent`
+ * timeout ceiling) so the two never drift.
+ *
+ * NOTE: on eviction-capable Hatchet engines (>= v0.80.0) a durable wait evicts
+ * the task and frees the worker slot, so a very long wall-clock wait MAY exceed
+ * this. We still treat it as our ceiling: `waitForEvent` rejects timeouts beyond
+ * it so they fail fast at authoring time rather than risk a mid-wait
+ * termination. Raise this to allow longer waits.
+ */
+export const JOURNEY_EXECUTION_TIMEOUT_HOURS = 720;
+export const JOURNEY_EXECUTION_TIMEOUT = `${JOURNEY_EXECUTION_TIMEOUT_HOURS}h`;

package/src/journeys/define-journey.ts

@@ -6,7 +6,8 @@ import type {
   JourneyUser,
 } from "@hogsend/core/types";
 import { contacts, journeyConfigs, journeyStates } from "@hogsend/db";
-import { and, eq, inArray } from "drizzle-orm";
+import { and, eq, inArray, notInArray } from "drizzle-orm";
+import { getAnalytics } from "../lib/analytics-singleton.js";
 import { getDb } from "../lib/db.js";
 import {
   checkEmailPreferences,
@@ -14,10 +15,11 @@ 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 { createJourneyContext } from "./journey-context.js";
+import { JOURNEY_EXECUTION_TIMEOUT } from "./constants.js";
+import { JourneyExitedError } from "./errors.js";
+import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
 import { getJourneyRegistrySingleton } from "./registry-singleton.js";
 
 const logger = createLogger(process.env.LOG_LEVEL);
@@ -43,7 +45,7 @@ export function defineJourney(options: {
   const task = hatchet.durableTask({
     name: `journey-${meta.id}`,
     onEvents: [meta.trigger.event],
-    executionTimeout: "720h",
+    executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
     retries: 0,
     fn: async (input: EventPayloadInput, hatchetCtx) => {
       const db = getDb();
@@ -129,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
@@ -203,17 +207,42 @@ export function defineJourney(options: {
 
         return { stateId, status: "completed" };
       } catch (err) {
+        // The journey reached a terminal state (exitOn / cancel) while suspended
+        // in a durable wait. The state row is already terminal — stop gracefully
+        // without marking it "failed" or re-pushing a journey:failed event.
+        if (err instanceof JourneyExitedError) {
+          return { stateId, status: "exited" };
+        }
+
         const message =
           err instanceof Error ? err.message : "Unknown error during journey";
 
-        await db
+        // Mark "failed" ONLY if the row isn't already terminal. A run cancelled
+        // by exitOn (ingestEvent sets "exited" then `runs.cancel`) or by the
+        // admin route surfaces here as a Hatchet AbortError thrown from the
+        // suspended waitFor/sleepFor — NOT a JourneyExitedError. Guarding on a
+        // non-terminal status prevents clobbering that "exited" row to "failed"
+        // and emitting a spurious journey:failed event.
+        const [failed] = await db
           .update(journeyStates)
           .set({
             status: "failed",
             errorMessage: message,
             updatedAt: new Date(),
           })
-          .where(eq(journeyStates.id, stateId));
+          .where(
+            and(
+              eq(journeyStates.id, stateId),
+              notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
+            ),
+          )
+          .returning({ id: journeyStates.id });
+
+        if (!failed) {
+          // Already terminal (cancelled after exit) — swallow the cancellation
+          // so the run doesn't double-report as failed.
+          return { stateId, status: "exited" };
+        }
 
         await hatchet.events.push("journey:failed", {
           journeyId: meta.id,

package/src/journeys/errors.ts

@@ -0,0 +1,17 @@
+/**
+ * Thrown by durable wait primitives (e.g. `ctx.waitForEvent`) when the journey
+ * reached a terminal state — exited via `exitOn`, or cancelled — while it was
+ * suspended. It is a CONTROL-FLOW SIGNAL, not a failure: `defineJourney` catches
+ * it and stops the run gracefully WITHOUT marking the state `"failed"` (the row
+ * is already terminal). Consumers generally never observe it; it simply aborts
+ * `run()` before any post-wait side effect can fire.
+ */
+export class JourneyExitedError extends Error {
+  readonly stateId: string;
+
+  constructor(stateId: string) {
+    super(`Journey state ${stateId} is no longer active (exited or cancelled)`);
+    this.name = "JourneyExitedError";
+    this.stateId = stateId;
+  }
+}

package/src/journeys/journey-context.ts

@@ -1,6 +1,14 @@
-import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { DurationObject } from "@hogsend/core";
-import { evaluateEventCondition } from "@hogsend/core";
+import type {
+  Conditions,
+  HatchetClient,
+} from "@hatchet-dev/typescript-sdk/v1/index.js";
+import {
+  Or,
+  SleepCondition,
+  UserEventCondition,
+} from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { DurationObject, PostHogService } from "@hogsend/core";
+import { durationToMs, evaluateEventCondition } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import {
   isValidTimeZone,
@@ -18,11 +26,32 @@ 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 } from "drizzle-orm";
+import { and, count, eq, max, notInArray } from "drizzle-orm";
 import { checkEmailPreferences } from "../lib/enrollment-guards.js";
 import { ingestEvent } from "../lib/ingestion.js";
 import type { Logger } from "../lib/logger.js";
+import {
+  JOURNEY_EXECUTION_TIMEOUT,
+  JOURNEY_EXECUTION_TIMEOUT_HOURS,
+} from "./constants.js";
+import { JourneyExitedError } from "./errors.js";
+
+/** Journey statuses that are terminal — a journey in any of these must never be
+ * resurrected back to "active" by a wait resuming. Exported so the durable task
+ * runner can avoid clobbering a terminal row to "failed" on a cancel. */
+export const TERMINAL_STATUSES = ["completed", "failed", "exited"] as const;
+
+/** Upper bound for a `waitForEvent` timeout — the journey task's executionTimeout. */
+const MAX_WAIT_MS = durationToMs({ hours: JOURNEY_EXECUTION_TIMEOUT_HOURS });
+
+/**
+ * Quote a string as a CEL single-quoted string literal, escaping backslashes
+ * then single quotes. Used to embed an externally-supplied userId into a CEL
+ * filter expression without breaking it or allowing injection.
+ */
+function celStringLiteral(value: string): string {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
 
 interface JourneyContextConfig {
   db: Database;
@@ -31,6 +60,12 @@ interface JourneyContextConfig {
     // Hatchet's real `sleepFor` accepts a number (milliseconds) in addition to
     // duration strings/objects; we use the number-ms form for `sleepUntil`.
     sleepFor: (duration: DurationObject | number) => Promise<unknown>;
+    // The forwarded object is the real Hatchet `DurableContext`, which also has
+    // `waitFor` (used by `waitForEvent`). Param mirrors the SDK signature so the
+    // real context is assignable; we read back the envelope as a plain record.
+    waitFor: (
+      conditions: Conditions | Conditions[],
+    ) => Promise<Record<string, unknown>>;
   };
   registry: JourneyRegistry;
   logger: Logger;
@@ -114,30 +149,103 @@ export function createJourneyContext(
     defaultSendWindow,
   } = config;
 
-  // Shared wait lifecycle: mark the state "waiting", durably sleep, mark it
-  // "active" again. `sleep` passes a DurationObject; `sleepUntil` passes a
-  // precomputed ms delay — Hatchet's `sleepFor` accepts both.
+  // Enter a durable wait: flip "active" → "waiting", but ONLY if the journey
+  // hasn't already reached a terminal state (e.g. exitOn fired before we got
+  // here). A no-op update means the journey is already done — abort the run.
+  const enterWait = async (nodeId: string): Promise<void> => {
+    const entered = await db
+      .update(journeyStates)
+      .set({ status: "waiting", currentNodeId: nodeId, updatedAt: new Date() })
+      .where(
+        and(
+          eq(journeyStates.id, stateId),
+          notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
+        ),
+      )
+      .returning({ id: journeyStates.id });
+
+    if (entered.length === 0) {
+      throw new JourneyExitedError(stateId);
+    }
+  };
+
+  // Resume from a durable wait: flip "waiting" → "active", but ONLY if the row
+  // is still "waiting". If an exit/cancel landed during the wait the row is no
+  // longer "waiting" — abort instead of reviving a terminated journey to active
+  // (which would let a post-wait side effect fire after the journey exited).
+  const resumeFromWait = async (): Promise<void> => {
+    const resumed = await db
+      .update(journeyStates)
+      .set({ status: "active", updatedAt: new Date() })
+      .where(
+        and(eq(journeyStates.id, stateId), eq(journeyStates.status, "waiting")),
+      )
+      .returning({ id: journeyStates.id });
+
+    if (resumed.length === 0) {
+      throw new JourneyExitedError(stateId);
+    }
+  };
+
+  // Durable sleep with the guarded waiting → active lifecycle. `sleep` passes a
+  // DurationObject; `sleepUntil` passes a precomputed ms delay — Hatchet's
+  // `sleepFor` accepts both.
   const performSleep = async (
     durationOrMs: DurationObject | number,
     nodeId: string,
   ): Promise<{ sleptAt: string; resumedAt: string }> => {
     const sleptAt = new Date().toISOString();
+    await enterWait(nodeId);
+    await hatchetCtx.sleepFor(durationOrMs);
+    const resumedAt = new Date().toISOString();
+    await resumeFromWait();
+    return { sleptAt, resumedAt };
+  };
 
-    await db
-      .update(journeyStates)
-      .set({ status: "waiting", currentNodeId: nodeId, updatedAt: new Date() })
-      .where(eq(journeyStates.id, stateId));
+  // Durably wait for THIS user's `event` OR `timeout`, whichever fires first,
+  // sharing the same guarded lifecycle as `performSleep`.
+  const performWaitForEvent = async (
+    event: string,
+    timeout: DurationObject,
+    nodeId: string,
+  ): Promise<{ timedOut: boolean }> => {
+    // Reject a timeout longer than the journey task's executionTimeout up front
+    // so it fails fast at authoring time. (Eviction-capable engines may allow
+    // longer wall-clock waits, but we cap to the configured ceiling — raise
+    // JOURNEY_EXECUTION_TIMEOUT to lift it.)
+    if (durationToMs(timeout) > MAX_WAIT_MS) {
+      throw new RangeError(
+        `waitForEvent timeout exceeds the journey execution limit (${JOURNEY_EXECUTION_TIMEOUT})`,
+      );
+    }
 
-    await hatchetCtx.sleepFor(durationOrMs);
+    await enterWait(nodeId);
 
-    const resumedAt = new Date().toISOString();
+    // Wait for the user-scoped event or the timeout. The event branch filters on
+    // the pushed payload's top-level `userId` (see `ingestEvent`); the SDK turns
+    // the ms number into a Go duration string at serialization time.
+    const result = await hatchetCtx.waitFor(
+      Or(
+        new UserEventCondition(
+          event,
+          `input.userId == ${celStringLiteral(userId)}`,
+          "event",
+        ),
+        new SleepCondition(durationToMs(timeout), "timeout"),
+      ),
+    );
 
-    await db
-      .update(journeyStates)
-      .set({ status: "active", updatedAt: new Date() })
-      .where(eq(journeyStates.id, stateId));
+    // Discriminate on which branch's readableDataKey ("event"/"timeout") is
+    // present. The eviction-capable path returns the `{ CREATE: { … } }`
+    // envelope; the pre-eviction path returns the inner object UN-wrapped — so
+    // strip an optional `CREATE` layer first to handle both shapes identically.
+    const fired = (("CREATE" in result ? result.CREATE : result) ??
+      {}) as Record<string, unknown>;
+    const timedOut = !("event" in fired);
 
-    return { sleptAt, resumedAt };
+    await resumeFromWait();
+
+    return { timedOut };
   };
 
   return {
@@ -169,6 +277,14 @@ export function createJourneyContext(
       );
     },
 
+    async waitForEvent({ event, timeout, label }) {
+      return performWaitForEvent(
+        event,
+        timeout,
+        label ?? `wait-event:${event}`,
+      );
+    },
+
     async checkpoint(label) {
       await db
         .update(journeyStates)

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;