@hogsend/engine 0.1.1 → 0.3.0

package/src/buckets/membership-epoch.ts

@@ -0,0 +1,186 @@
+import {
+  type BucketMeta,
+  type ConditionEval,
+  type DurationObject,
+  durationToMs,
+  type EventCondition,
+} from "@hogsend/core";
+import { bucketMemberships, type Database } from "@hogsend/db";
+import { and, eq, sql } from "drizzle-orm";
+
+/**
+ * The reserved prefix every bucket transition event carries. Single source of
+ * truth shared by the ingest recursion guard (`checkBucketMembership`) and the
+ * fast-expiry arming event (`bucket:arm-expiry`).
+ */
+export const BUCKET_EVENT_PREFIX = "bucket:";
+
+/**
+ * The count of ALL prior memberships (active + left, NO status filter) for a
+ * (userId, bucketId) pair. This is the single source for the entryCount-ordinal
+ * rule (Section 6.3 / 8.2): the next epoch is `1 + countPriorMemberships(...)`,
+ * and the same count drives the entryLimit gate. Both the real-time join path
+ * (`handleJoin`) and the reconcile-discovered join path (`reconcileJoinOne`)
+ * call this so the ordinal can never drift between the two writers.
+ *
+ * The predicate MUST stay status-agnostic — narrowing it (e.g. to active-only)
+ * would corrupt entryCount and the entryLimit cooldown.
+ */
+export async function countPriorMemberships(
+  db: Database,
+  bucketId: string,
+  userId: string,
+): Promise<number> {
+  const [counted] = await db
+    .select({ priorCount: sql<number>`count(*)::int` })
+    .from(bucketMemberships)
+    .where(
+      and(
+        eq(bucketMemberships.userId, userId),
+        eq(bucketMemberships.bucketId, bucketId),
+      ),
+    );
+  return Number(counted?.priorCount ?? 0);
+}
+
+/**
+ * Find the first `EventCondition.within` rolling window in a criteria tree
+ * (depth-first). Returns null when no event leg carries a window. The single
+ * source for the membership-expiry / fastExpiry deadline math — shared so the
+ * three membership writers (real-time join, reconcile join, backfill join) can
+ * never disagree on which window drives `expiresAt`.
+ */
+export function firstWithin(criteria: ConditionEval): DurationObject | null {
+  if (criteria.type === "event" && criteria.within) {
+    return criteria.within;
+  }
+  if (criteria.type === "composite") {
+    for (const child of criteria.conditions) {
+      const found = firstWithin(child);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * The persisted membership-expiry / fastExpiry arming deadline. Non-time-based,
+ * non-fastExpiry buckets have no deadline (returns null). Time-based / fastExpiry
+ * buckets that carry a single `within` window get `now + within`; the reconcile
+ * cron and fastExpiry timer own the actual leave.
+ *
+ * Centralized so the real-time join (check-membership.ts), the reconcile-discovered
+ * join (bucket-reconcile.ts), and the backfill join (bucket-backfill.ts) compute
+ * the SAME deadline — a divergence here would let a membership-writer arm a window
+ * the cron/timer disagrees with.
+ */
+export function computeExpiresAt(bucket: BucketMeta): Date | null {
+  if (!bucket.criteria) return null;
+  if (!bucket.timeBased && !bucket.fastExpiry) return null;
+  const within = firstWithin(bucket.criteria);
+  if (!within) return null;
+  return new Date(Date.now() + durationToMs(within));
+}
+
+/**
+ * The unconditional max-dwell TTL deadline, stamped once on JOIN. null when the
+ * bucket has no `maxDwell`; the TTL sweep filters `isNotNull(maxDwellAt)`, so an
+ * unset value is never force-left. Shared by all three join writers so the TTL
+ * stamp is computed identically.
+ */
+export function computeMaxDwellAt(bucket: BucketMeta): Date | null {
+  return bucket.maxDwell
+    ? new Date(Date.now() + durationToMs(bucket.maxDwell))
+    : null;
+}
+
+/**
+ * The shared windowed event-count operator comparison kernel (`gt/gte/lt/lte/eq`).
+ * Returns the boolean of `count <operator> value`, or null for an unrecognized
+ * operator so each caller keeps its own default (the leave/match wrappers below).
+ * This is the single source for the count-operator math the reconcile SHOULD-LEAVE
+ * and the backfill MATCH paths both depend on.
+ */
+function compareCount(
+  operator: NonNullable<EventCondition["operator"]>,
+  count: number,
+  value: number,
+): boolean | null {
+  switch (operator) {
+    case "gt":
+      return count > value;
+    case "gte":
+      return count >= value;
+    case "lt":
+      return count < value;
+    case "lte":
+      return count <= value;
+    case "eq":
+      return count === value;
+    default:
+      return null;
+  }
+}
+
+/**
+ * True when a windowed `count` satisfies the (exists/not_exists/count) event
+ * criterion — the POSITIVE "is a member by this windowed count" decision. Shared
+ * by the backfill matcher path (selectEventMatchers' positive branch). Behavior is
+ * identical to the prior local `matchesCount`: a `count` check with no
+ * operator/value (or an unrecognized operator) falls back to `count > 0` / `false`
+ * respectively.
+ */
+export function matchesEventCount(
+  criteria: EventCondition,
+  count: number,
+): boolean {
+  switch (criteria.check) {
+    case "exists":
+      return count > 0;
+    case "not_exists":
+      return count === 0;
+    case "count": {
+      if (!criteria.operator || criteria.value === undefined) return count > 0;
+      const result = compareCount(criteria.operator, count, criteria.value);
+      return result ?? false;
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * The SHOULD-LEAVE decision from a windowed count, per criterion shape — a member
+ * leaves when the criterion is NO LONGER satisfied. Shared by the reconcile
+ * cron's set-based leave path. Behavior is identical to the prior local
+ * `shouldLeaveByCount`: it is the per-shape NEGATION of {@link matchesEventCount}
+ * for `exists`/`count`, an event-reappeared check for `not_exists`, and preserves
+ * the `count` `default → false` for an unrecognized operator.
+ */
+export function shouldLeaveByCount(
+  criteria: EventCondition,
+  windowedCount: number,
+): boolean {
+  switch (criteria.check) {
+    case "not_exists":
+      // Absence bucket: SHOULD LEAVE when an event REAPPEARS in the window.
+      return windowedCount > 0;
+    case "exists":
+      // Positive existence: SHOULD LEAVE when NOT EXISTS in the window.
+      return windowedCount === 0;
+    case "count": {
+      // SHOULD LEAVE when the windowed count NO LONGER satisfies the operator.
+      if (!criteria.operator || criteria.value === undefined) {
+        return windowedCount === 0;
+      }
+      const result = compareCount(
+        criteria.operator,
+        windowedCount,
+        criteria.value,
+      );
+      return result == null ? false : !result;
+    }
+    default:
+      return false;
+  }
+}

package/src/buckets/registry-singleton.ts

@@ -0,0 +1,21 @@
+import type { BucketRegistry } from "@hogsend/core/registry";
+
+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;
+}
+
+/** Reset the singleton — only for test cleanup. */
+export function resetBucketRegistry(): void {
+  _registry = undefined;
+}

package/src/buckets/registry.ts

@@ -0,0 +1,62 @@
+import { BucketRegistry } from "@hogsend/core/registry";
+import { parseEnabledFilter } from "../journeys/registry.js";
+import { bucketExpiryTask } from "../workflows/bucket-reconcile.js";
+import type { DefinedBucket } from "./define-bucket.js";
+import { setBucketRegistry } from "./registry-singleton.js";
+
+/**
+ * Build a {@link BucketRegistry} from an injected array of buckets, applying the
+ * enabled filter, and install it as the process singleton (so the real-time
+ * ingest path and the reconcile cron can resolve it). Returns the registry.
+ *
+ * `parseEnabledFilter` (journeys/registry.ts) is reused as-is — `ENABLED_BUCKETS`
+ * honours the same `"*"`-or-csv contract as `ENABLED_JOURNEYS` (Section 9.3).
+ * `BucketRegistry.register()` runs `bucketMetaSchema.parse()` internally, so no
+ * separate validation step is needed here.
+ */
+export function buildBucketRegistry(
+  buckets: DefinedBucket[],
+  enabledFilter?: string,
+): BucketRegistry {
+  const registry = new BucketRegistry();
+  const enabled = parseEnabledFilter(enabledFilter);
+
+  for (const bucket of buckets) {
+    if (enabled === "*" || enabled.has(bucket.meta.id)) {
+      registry.register(bucket.meta);
+    }
+  }
+
+  setBucketRegistry(registry);
+  return registry;
+}
+
+/**
+ * Select the Hatchet durable tasks for the enabled buckets. This is the SINGLE
+ * place a bucket's per-user fast-expiry timer task is constructed (Section
+ * 4.3/9.4) — task construction happens at worker build, AFTER the registry has
+ * validated every meta, never at module-load.
+ *
+ * Only `meta.fastExpiry` buckets contribute a task; the engine-wide
+ * `bucketReconcileTask` (registered separately in `baseWorkflows`) owns
+ * time-based leaves regardless. The fast-expiry timer is a single shared
+ * `durableTask` keyed on `bucket:arm-expiry` (per-bucket arming is by event
+ * payload, not per-bucket task instances), so it is registered once if ANY
+ * enabled bucket opts in.
+ */
+export function selectBucketTasks(
+  buckets: DefinedBucket[],
+  enabledFilter?: string,
+): NonNullable<DefinedBucket["task"]>[] {
+  const enabled = parseEnabledFilter(enabledFilter);
+  const hasFastExpiry = buckets.some(
+    (b) =>
+      (enabled === "*" || enabled.has(b.meta.id)) && b.meta.fastExpiry === true,
+  );
+  if (!hasFastExpiry) return [];
+
+  // The single shared `bucket:arm-expiry` durableTask, registered ONCE because
+  // any enabled bucket opts in (per-bucket arming is by event payload). Cast to
+  // the DefinedBucket task shape — both are `hatchet.durableTask` returns.
+  return [bucketExpiryTask as NonNullable<DefinedBucket["task"]>];
+}

package/src/container.ts

@@ -1,6 +1,6 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { TimeZone } from "@hogsend/core";
-import type { JourneyRegistry } from "@hogsend/core/registry";
+import type { BucketRegistry, JourneyRegistry } from "@hogsend/core/registry";
 import type { SendWindow } from "@hogsend/core/schedule";
 import {
   createDatabase,
@@ -16,6 +16,8 @@ import {
   type EmailProvider,
 } from "@hogsend/plugin-resend";
 import type { Resend } from "resend";
+import type { DefinedBucket } from "./buckets/define-bucket.js";
+import { buildBucketRegistry } 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";
@@ -58,6 +60,13 @@ export interface HogsendClient {
   templates: TemplateRegistry;
   analytics?: PostHogService;
   registry: JourneyRegistry;
+  /**
+   * The bucket registry (id map + event/property inverted indexes for candidate
+   * narrowing). Built and installed as the process singleton at client build;
+   * the real-time ingest path reads it via `getBucketRegistrySingleton()`.
+   * Empty when no buckets are wired.
+   */
+  bucketRegistry: BucketRegistry;
   hatchet: HatchetClient;
   /**
    * The client repo's migration journal (`migrations/meta/_journal.json`),
@@ -77,6 +86,8 @@ export interface HogsendClient {
 export interface HogsendClientOptions {
   /** Journeys to register in the {@link JourneyRegistry}. Defaults to none. */
   journeys?: DefinedJourney[];
+  /** Buckets to register in the {@link BucketRegistry}. Defaults to none. */
+  buckets?: DefinedBucket[];
   /**
    * Email is a first-class channel. Its config is grouped here rather than
    * spread across top-level args — the engine owns the cohesive email pipeline
@@ -112,6 +123,11 @@ export interface HogsendClientOptions {
    * `env.ENABLED_JOURNEYS`.
    */
   enabledJourneys?: string;
+  /**
+   * Comma-separated ids (or `*`) controlling which buckets load. Defaults to
+   * `env.ENABLED_BUCKETS`.
+   */
+  enabledBuckets?: string;
   /**
    * The client repo's migration journal for the `schema.client` health block.
    * Defaults to `{ entries: [] }` (empty client track ⇒ trivially in sync).
@@ -182,6 +198,14 @@ export function createHogsendClient(
     opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
   );
 
+  // 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 provider =
     opts.email?.provider ??
     createResendProvider({
@@ -228,6 +252,7 @@ export function createHogsendClient(
   const analytics = opts.analytics ?? getPostHog();
 
   logger.info(`Journey registry loaded: ${registry.count()} journeys`);
+  logger.info(`Bucket registry loaded: ${bucketRegistry.count()} buckets`);
 
   return {
     env,
@@ -240,6 +265,7 @@ export function createHogsendClient(
     templates,
     analytics,
     registry,
+    bucketRegistry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
     defaults,

package/src/env.ts

@@ -54,6 +54,12 @@ export const env = createEnv({
     ADMIN_API_KEY: z.string().min(1).optional(),
     API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),
     ENABLED_JOURNEYS: z.string().default("*"),
+    // Buckets: same `"*"`-or-csv contract as ENABLED_JOURNEYS (Section 9.3).
+    // Evaluated at worker boot — a toggle requires a worker restart; only the
+    // bucket_configs DB override is hot.
+    ENABLED_BUCKETS: z.string().default("*"),
+    // Cadence for the engine-owned bucket reconcile cron (time-based leaves).
+    BUCKET_RECONCILE_CRON: z.string().default("*/5 * * * *"),
   },
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,

package/src/index.ts

@@ -6,7 +6,10 @@
 // Core helpers used by content journeys (days/hours/minutes, condition + journey
 // types) so content can import everything from `@hogsend/engine`.
 export * from "@hogsend/core";
-export { JourneyRegistry } from "@hogsend/core/registry";
+export {
+  BucketRegistry,
+  JourneyRegistry,
+} from "@hogsend/core/registry";
 // --- Re-exports for content ---
 // Schema/version helpers used by the boot guard and the /v1/health route.
 export {
@@ -19,6 +22,25 @@ export {
 } from "@hogsend/db";
 // --- App / container / worker factories ---
 export { type AppEnv, type CreateAppOptions, createApp } from "./app.js";
+// --- Buckets ---
+export {
+  type BucketTransition,
+  type BucketTransitionKind,
+  checkBucketMembership,
+} from "./buckets/check-membership.js";
+export {
+  type DefinedBucket,
+  defineBucket,
+} from "./buckets/define-bucket.js";
+export {
+  buildBucketRegistry,
+  selectBucketTasks,
+} from "./buckets/registry.js";
+export {
+  getBucketRegistrySingleton,
+  resetBucketRegistry,
+  setBucketRegistry,
+} from "./buckets/registry-singleton.js";
 export {
   createHogsendClient,
   type HogsendClient,
@@ -50,6 +72,11 @@ export {
   type BatchedBackfillResult,
   runBatchedBackfill,
 } from "./lib/backfill.js";
+// --- Bucket transition emission (shared by real-time / cron / fast-expiry) ---
+export {
+  type BucketTransitionSource,
+  emitBucketTransition,
+} from "./lib/bucket-emit.js";
 // --- Infrastructure singletons ---
 export { getDb } from "./lib/db.js";
 // --- Email ---
@@ -121,6 +148,17 @@ export {
   createWorker,
   type Worker,
 } from "./worker.js";
+export {
+  type BucketBackfillInput,
+  bucketBackfillTask,
+  computeCriteriaHash,
+  enqueueBucketBackfills,
+} from "./workflows/bucket-backfill.js";
+export {
+  type BucketArmExpiryInput,
+  bucketExpiryTask,
+  bucketReconcileTask,
+} from "./workflows/bucket-reconcile.js";
 export { checkAlertsTask } from "./workflows/check-alerts.js";
 export { importContactsTask } from "./workflows/import-contacts.js";
 // --- Built-in Hatchet workflow tasks ---

package/src/lib/bucket-emit.ts

@@ -0,0 +1,107 @@
+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 { syncBucketToPostHog } from "./bucket-posthog-sync.js";
+import { ingestEvent } from "./ingestion.js";
+import type { Logger } from "./logger.js";
+
+export type BucketTransitionKind = "entered" | "left";
+
+/** Where a transition originated — carried on the emitted event properties. */
+export type BucketTransitionSource =
+  | "event"
+  | "reconcile"
+  | "backfill"
+  | "manual";
+
+/**
+ * Emit a bucket transition back through `ingestEvent` (the `ctx.trigger`
+ * precedent) — shared by ALL three producers (real-time `checkBucketMembership`,
+ * the reconcile cron, and the fast-expiry timer) so they compute byte-identical
+ * `idempotencyKey`s for the same transition and converge to ONE emission
+ * (Section 6.3 worked example).
+ *
+ * Persists to `userEvents`, pushes to Hatchet (routing to journeys), and runs
+ * `checkExits`. Emits the per-bucket ALIAS (`bucket:<kind>:<id>`) by default; the
+ * generic `bucket:<kind>` is emitted ONLY when a generic-bound journey actually
+ * exists (aliased-only default — Section 8.5). `epoch` is the winning membership
+ * row's `entryCount`, read off the single winning mutation by the caller.
+ */
+export async function emitBucketTransition(opts: {
+  db: Database;
+  /** The JOURNEY registry — forwarded into the recursive emit ingestEvent. */
+  registry: JourneyRegistry;
+  hatchet: HatchetClient;
+  logger: Logger;
+  kind: BucketTransitionKind;
+  bucket: BucketMeta;
+  userId: string;
+  userEmail: string | null;
+  epoch: number;
+  source?: BucketTransitionSource;
+}): Promise<void> {
+  const {
+    db,
+    registry,
+    hatchet,
+    logger,
+    kind,
+    bucket,
+    userId,
+    userEmail,
+    epoch,
+    source = "event",
+  } = opts;
+
+  const properties: Record<string, unknown> = {
+    bucketId: bucket.id,
+    bucketName: bucket.name,
+    userId,
+    transition: kind,
+    source,
+  };
+
+  // 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 });
+
+  // Per-bucket alias — the recommended, narrowly-routed binding. The
+  // deterministic idempotencyKey rides the userEvents dedup short-circuit as
+  // defense-in-depth (Section 6.3).
+  await ingestEvent({
+    db,
+    registry,
+    hatchet,
+    logger,
+    event: {
+      event: `bucket:${kind}:${bucket.id}`,
+      userId,
+      userEmail: userEmail ?? "",
+      properties,
+      idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}`,
+    },
+  });
+
+  // Generic form — emitted ONLY if a journey actually binds to it, so the
+  // recursion-guarded generic event is not written for nothing (Section 8.5).
+  const genericEvent = `bucket:${kind}`;
+  if (registry.getByTriggerEvent(genericEvent).length > 0) {
+    await ingestEvent({
+      db,
+      registry,
+      hatchet,
+      logger,
+      event: {
+        event: genericEvent,
+        userId,
+        userEmail: userEmail ?? "",
+        properties,
+        idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
+      },
+    });
+  }
+}

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

@@ -0,0 +1,63 @@
+import type { BucketMeta } from "@hogsend/core";
+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
+ * 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
+ * same key. `$unset` (NOT `$set false`) is the recommended default: a cohort
+ * `key = true` excludes a false value, but a cohort `key is set` STILL matches a
+ * false value, so `$unset` is the only form where both cohort idioms behave
+ * correctly. The property key defaults to `hogsend_bucket_<id>`, overridable via
+ * `meta.postHogPropertyKey`.
+ *
+ * This reuses the existing `plugin-posthog` capture path (the same one
+ * `identify()` uses at journey-context.ts) — it adds no new integration surface
+ * and never pushes to any non-PostHog destination (the Section 2.4 anti-CDP
+ * invariant). Best-effort: a capture failure is logged and swallowed so a sync
+ * error never blocks a transition emit.
+ */
+export function syncBucketToPostHog(opts: {
+  logger: Logger;
+  kind: "entered" | "left";
+  bucket: BucketMeta;
+  userId: string;
+}): void {
+  const { logger, kind, bucket, userId } = opts;
+
+  if (!bucket.syncToPostHog) return;
+
+  const posthog = getPostHog();
+  if (!posthog) return; // no POSTHOG_API_KEY → silent no-op
+
+  const propertyKey =
+    bucket.postHogPropertyKey ?? `hogsend_bucket_${bucket.id}`;
+
+  try {
+    if (kind === "entered") {
+      // $set { key: true } — mirrors plugin-posthog identify() ($set path).
+      posthog.identify(userId, { [propertyKey]: true });
+    } else {
+      // $unset [key] — RECOMMENDED on leave (Section 12). The property is absent
+      // unless the user is currently a member, so both `key = true` and
+      // `key is set` cohorts behave correctly.
+      posthog.captureEvent({
+        distinctId: userId,
+        event: "$set",
+        properties: { $unset: [propertyKey] },
+      });
+    }
+  } catch (err) {
+    logger.warn("Bucket PostHog sync failed (best-effort)", {
+      bucketId: bucket.id,
+      userId,
+      kind,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/lib/ingestion.ts

@@ -3,6 +3,7 @@ import { evaluatePropertyConditions } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, journeyStates, userEvents } from "@hogsend/db";
 import { and, eq, inArray, isNull } from "drizzle-orm";
+import { checkBucketMembership } from "../buckets/check-membership.js";
 import { upsertContact } from "./contacts.js";
 import type { Logger } from "./logger.js";
 
@@ -93,6 +94,30 @@ export async function ingestEvent(opts: {
     }),
   ]);
 
+  // Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
+  // Promise.all above: its property eval reads MERGED contact state, and its
+  // bucket:entered/left emissions recurse back into ingestEvent (the recursion
+  // guard in checkBucketMembership bounds them). Best-effort: a bucket failure
+  // must not fail the ingest of the originating event.
+  try {
+    await checkBucketMembership({
+      db,
+      registry,
+      hatchet,
+      logger,
+      userId: event.userId,
+      userEmail: event.userEmail || null,
+      event: event.event,
+      properties: event.properties,
+    });
+  } catch (err) {
+    logger.warn("Bucket membership check failed", {
+      event: event.event,
+      userId: event.userId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
   logger.info("Event ingested", {
     event: event.event,
     userId: event.userId,