@hogsend/engine 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -37,11 +37,11 @@
     "resend": "^6.12.3",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@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"
+    "@hogsend/core": "^0.7.0",
+    "@hogsend/db": "^0.7.0",
+    "@hogsend/email": "^0.7.0",
+    "@hogsend/plugin-posthog": "^0.7.0",
+    "@hogsend/plugin-resend": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/buckets/bucket-access.ts

@@ -0,0 +1,213 @@
+import { bucketMemberships, contacts, type Database } from "@hogsend/db";
+import { and, count as countFn, eq, gt, isNull } from "drizzle-orm";
+import { getDb } from "../lib/db.js";
+
+/**
+ * Hard cap on a single page — mirrors the admin `listMembersRoute` `z.max(100)`.
+ * Member access is NEVER an unbounded array; even the iterator pages internally.
+ */
+const MAX_PAGE = 100;
+/** Default page size when the caller does not specify a limit. */
+const DEFAULT_PAGE = 50;
+
+/** A serialized active-membership row returned by `members()` / the iterator. */
+export interface BucketMemberRow {
+  id: string;
+  userId: string;
+  userEmail: string | null;
+  enteredAt: string;
+  entryCount: number;
+}
+
+/** Supabase-shaped paged result — no throw; failures land in `error`. */
+export interface MembersResult {
+  data: BucketMemberRow[];
+  error: Error | null;
+  /**
+   * Per-call snapshot total (active, non-deleted, joined to a live contact).
+   * NOT a consistent paginated total — under churn it can drift page-to-page.
+   * The keyset cursor itself is churn-safe; use `count()` for one authoritative
+   * number.
+   */
+  count: number | null;
+  /** Keyset continuation (last row `id`); `null` when the page is exhausted. */
+  cursor: string | null;
+}
+
+export interface BucketAccessor {
+  count(): Promise<{ data: number | null; error: Error | null }>;
+  has(userId: string): Promise<{ data: boolean; error: Error | null }>;
+  members(opts?: { limit?: number; cursor?: string }): Promise<MembersResult>;
+  membersIterator(opts?: {
+    pageSize?: number;
+  }): AsyncIterableIterator<BucketMemberRow>;
+}
+
+function toError(err: unknown): Error {
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+/**
+ * Build the per-bucket member-access surface (`count`/`has`/`members`/iterator).
+ *
+ * The accessor is constructed at module load (`defineBucket` time), before any
+ * container exists, so it defaults to `getDb()` — the same singleton the
+ * desugared reaction journeys run on. To honor `overrides.db` in tests, the
+ * container re-binds the accessors with a `dbResolver` that returns its own
+ * `db`; the `getDb()` default bypasses the container.
+ *
+ * Every query `innerJoin`s `contacts` on `externalId` and filters
+ * `isNull(deletedAt)` on both tables — GDPR parity with every reconcile/admin
+ * query. No method throws (except the iterator on a page error); failures are
+ * carried in the result's `error`.
+ */
+export function createBucketAccessor(
+  bucketId: string,
+  dbResolver: () => Database = getDb,
+): BucketAccessor {
+  async function count(): Promise<{
+    data: number | null;
+    error: Error | null;
+  }> {
+    try {
+      const db = dbResolver();
+      const rows = await db
+        .select({ value: countFn() })
+        .from(bucketMemberships)
+        .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
+        .where(
+          and(
+            eq(bucketMemberships.bucketId, bucketId),
+            eq(bucketMemberships.status, "active"),
+            isNull(bucketMemberships.deletedAt),
+            isNull(contacts.deletedAt),
+          ),
+        );
+      return { data: rows[0]?.value ?? 0, error: null };
+    } catch (err) {
+      return { data: null, error: toError(err) };
+    }
+  }
+
+  async function has(
+    userId: string,
+  ): Promise<{ data: boolean; error: Error | null }> {
+    try {
+      const db = dbResolver();
+      // O(1) probe on the partial active unique index (uq_user_bucket_active).
+      const rows = await db
+        .select({ id: bucketMemberships.id })
+        .from(bucketMemberships)
+        .innerJoin(contacts, eq(contacts.externalId, bucketMemberships.userId))
+        .where(
+          and(
+            eq(bucketMemberships.bucketId, bucketId),
+            eq(bucketMemberships.userId, userId),
+            eq(bucketMemberships.status, "active"),
+            isNull(bucketMemberships.deletedAt),
+            isNull(contacts.deletedAt),
+          ),
+        )
+        .limit(1);
+      return { data: rows.length > 0, error: null };
+    } catch (err) {
+      return { data: false, error: toError(err) };
+    }
+  }
+
+  async function members(opts?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<MembersResult> {
+    const limit = Math.min(opts?.limit ?? DEFAULT_PAGE, MAX_PAGE);
+    try {
+      const db = dbResolver();
+      const conditions = [
+        eq(bucketMemberships.bucketId, bucketId),
+        eq(bucketMemberships.status, "active"),
+        isNull(bucketMemberships.deletedAt),
+        isNull(contacts.deletedAt),
+      ];
+      // Keyset cursor on `id` (UUID, unique, stable — NOT enteredAt, which ties
+      // on defaultNow). Opaque (UUID asc) order, not chronological.
+      if (opts?.cursor) {
+        conditions.push(gt(bucketMemberships.id, opts.cursor));
+      }
+
+      const [rows, totalRows] = await Promise.all([
+        db
+          .select({
+            id: bucketMemberships.id,
+            userId: bucketMemberships.userId,
+            userEmail: bucketMemberships.userEmail,
+            enteredAt: bucketMemberships.enteredAt,
+            entryCount: bucketMemberships.entryCount,
+          })
+          .from(bucketMemberships)
+          .innerJoin(
+            contacts,
+            eq(contacts.externalId, bucketMemberships.userId),
+          )
+          .where(and(...conditions))
+          .orderBy(bucketMemberships.id)
+          // +1 peek to detect a next page.
+          .limit(limit + 1),
+        db
+          .select({ value: countFn() })
+          .from(bucketMemberships)
+          .innerJoin(
+            contacts,
+            eq(contacts.externalId, bucketMemberships.userId),
+          )
+          .where(
+            and(
+              eq(bucketMemberships.bucketId, bucketId),
+              eq(bucketMemberships.status, "active"),
+              isNull(bucketMemberships.deletedAt),
+              isNull(contacts.deletedAt),
+            ),
+          ),
+      ]);
+
+      const hasMore = rows.length > limit;
+      const page = hasMore ? rows.slice(0, limit) : rows;
+      const data: BucketMemberRow[] = page.map((r) => ({
+        id: r.id,
+        userId: r.userId,
+        userEmail: r.userEmail,
+        enteredAt: r.enteredAt.toISOString(),
+        entryCount: r.entryCount,
+      }));
+      const cursor = hasMore ? (page[page.length - 1]?.id ?? null) : null;
+
+      return {
+        data,
+        error: null,
+        count: totalRows[0]?.value ?? 0,
+        cursor,
+      };
+    } catch (err) {
+      return { data: [], error: toError(err), count: null, cursor: null };
+    }
+  }
+
+  async function* membersIterator(opts?: {
+    pageSize?: number;
+  }): AsyncIterableIterator<BucketMemberRow> {
+    const pageSize = Math.min(opts?.pageSize ?? DEFAULT_PAGE, MAX_PAGE);
+    let cursor: string | null | undefined;
+    // The only full-population traversal — bounded page-by-page via members().
+    while (true) {
+      const page = await members({
+        limit: pageSize,
+        cursor: cursor ?? undefined,
+      });
+      if (page.error) throw page.error;
+      for (const row of page.data) yield row;
+      if (!page.cursor) break;
+      cursor = page.cursor;
+    }
+  }
+
+  return { count, has, members, membersIterator };
+}

package/src/buckets/bucket-reactions.ts

@@ -0,0 +1,225 @@
+import type { DurationObject } from "@hogsend/core";
+import { durationToMs } from "@hogsend/core";
+import type {
+  JourneyContext,
+  JourneyMeta,
+  JourneyUser,
+} from "@hogsend/core/types";
+import {
+  type DefinedJourney,
+  defineJourney,
+} from "../journeys/define-journey.js";
+import type { DefinedBucket } from "./define-bucket.js";
+
+/**
+ * Why a reaction reaches for THIS leave reason. Carried on the emitted
+ * `bucket:left:<id>` event properties and surfaced to a `leave` handler as
+ * `ctx.reason`. `"manual"` is reserved for a future force-leave path.
+ */
+export type BucketLeaveReason = "criteria" | "maxDwell" | "manual";
+
+/** `bucket.on("enter", opts?, handler)` options. */
+export interface EnterOptions {
+  /**
+   * Only run the handler on the user's FIRST entry to this bucket (re-entries
+   * are skipped). Re-entry is a FILTER, never a separate event — the filter runs
+   * inside `run` AFTER enrollment (a filtered-out entry still writes a short
+   * active→completed `journeyStates` row).
+   */
+  firstEntryOnly?: boolean;
+}
+
+/** `bucket.on("leave", opts?, handler)` options. */
+export interface LeaveOptions {
+  /**
+   * Only run the handler when the leave matches this reason (or one of these
+   * reasons). Filter runs inside `run` AFTER enrollment.
+   */
+  reason?: BucketLeaveReason | BucketLeaveReason[];
+}
+
+/**
+ * `bucket.on("dwell", opts, handler)` options — exactly one of `after`/`every`.
+ *  - `after`: one-shot, fires once when the member has dwelt continuously for
+ *    the duration.
+ *  - `every`: recurring, fires (coalescing) once per elapsed interval.
+ */
+export type DwellOptions =
+  | { after: DurationObject; every?: never }
+  | { every: DurationObject; after?: never };
+
+/**
+ * Reaction-specific read-only extras layered onto the canonical
+ * `JourneyContext` for the handler, discriminated by the reaction kind.
+ */
+export type ReactionExtras<K> = K extends "enter"
+  ? { entryCount: number; isFirstEntry: boolean }
+  : K extends "leave"
+    ? { reason: BucketLeaveReason }
+    : { dwellCount: number };
+
+/** The ctx a reaction handler receives: full JourneyContext + kind extras. */
+export type BucketReactionCtx<K extends "enter" | "leave" | "dwell"> =
+  JourneyContext & ReactionExtras<K>;
+
+/** A bucket-reaction handler — same `(user, ctx)` shape as a journey `run`. */
+export type BucketOnHandler<K extends "enter" | "leave" | "dwell"> = (
+  user: JourneyUser,
+  ctx: BucketReactionCtx<K>,
+) => Promise<void>;
+
+/** Coerce a single value or array to an array. */
+export function asArray<T>(value: T | T[]): T[] {
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Stable, schedule-unique label for a dwell reaction: `after-<ms>` / `every-<ms>`.
+ * Hatchet keys workflows by `journey-${id}`, so two dwell reactions on one bucket
+ * (one `after`, one `every`) get distinct, boot-stable ids/events.
+ */
+export function dwellLabel(opts: DwellOptions): string {
+  return opts.after != null
+    ? `after-${durationToMs(opts.after)}`
+    : `every-${durationToMs(opts.every)}`;
+}
+
+/** The schema persisted on the reaction meta (read by the dwell cron). */
+export function parseDwellSchedule(opts: DwellOptions): {
+  label: string;
+  after?: number;
+  every?: number;
+} {
+  return opts.after != null
+    ? { label: dwellLabel(opts), after: durationToMs(opts.after) }
+    : { label: dwellLabel(opts), every: durationToMs(opts.every) };
+}
+
+/** Derive the generated reaction journey id from the bucket id + kind. */
+export function reactionJourneyId(
+  bucketId: string,
+  kind: "enter" | "leave" | "dwell",
+  opts: EnterOptions | LeaveOptions | DwellOptions | undefined,
+): string {
+  return kind === "dwell"
+    ? `bucket-${bucketId}-on-dwell-${dwellLabel(opts as DwellOptions)}`
+    : `bucket-${bucketId}-on-${kind}`;
+}
+
+/**
+ * Discriminate the `(opts?, handler)` overload by argument type: a function in
+ * the first slot is the handler (opts undefined); an object in the first slot is
+ * opts and the second slot is the handler. For `dwell`, opts is mandatory and
+ * must carry exactly one of `after`/`every` — a `TypeError` otherwise.
+ */
+export function normalizeOnArgs(
+  kind: "enter" | "leave" | "dwell",
+  a: unknown,
+  b?: unknown,
+): {
+  opts: EnterOptions | LeaveOptions | DwellOptions | undefined;
+  handler: BucketOnHandler<"enter" | "leave" | "dwell">;
+} {
+  let opts: EnterOptions | LeaveOptions | DwellOptions | undefined;
+  let handler: BucketOnHandler<"enter" | "leave" | "dwell">;
+
+  if (typeof a === "function") {
+    opts = undefined;
+    handler = a as BucketOnHandler<"enter" | "leave" | "dwell">;
+  } else {
+    opts = a as EnterOptions | LeaveOptions | DwellOptions | undefined;
+    handler = b as BucketOnHandler<"enter" | "leave" | "dwell">;
+  }
+
+  if (typeof handler !== "function") {
+    throw new TypeError(`bucket.on("${kind}") requires a handler function`);
+  }
+
+  if (kind === "dwell") {
+    const dwell = opts as DwellOptions | undefined;
+    const hasAfter = dwell?.after != null;
+    const hasEvery = dwell?.every != null;
+    if (hasAfter === hasEvery) {
+      throw new TypeError(
+        'bucket.on("dwell") requires exactly one of `after` or `every`',
+      );
+    }
+  }
+
+  return { opts, handler };
+}
+
+/**
+ * Desugar `bucket.on(kind, opts?, handler)` to a real `defineJourney` output
+ * tagged with `sourceBucketId` + `reactionKind`. The reaction IS a journey, so
+ * it inherits the entire enrollment guard stack, the active-state dedup, the
+ * durable context, and event routing for free.
+ *
+ * The handler ctx is built by SPREAD (`{ ...ctx, ...extras }`), never by
+ * mutating the engine's canonical ctx (which is shared/closed). The
+ * `firstEntryOnly`/`reason` filters run inside `run` AFTER enrollment.
+ */
+export function buildBucketReaction(args: {
+  bucket: DefinedBucket;
+  kind: "enter" | "leave" | "dwell";
+  opts: EnterOptions | LeaveOptions | DwellOptions | undefined;
+  handler: BucketOnHandler<"enter" | "leave" | "dwell">;
+}): DefinedJourney {
+  const { bucket, kind, opts, handler } = args;
+
+  const triggerEvent =
+    kind === "enter"
+      ? bucket.entered
+      : kind === "leave"
+        ? bucket.left
+        : `bucket:dwell:${bucket.meta.id}:${dwellLabel(opts as DwellOptions)}`;
+
+  const meta: JourneyMeta = {
+    id: reactionJourneyId(bucket.meta.id, kind, opts),
+    name: `${bucket.meta.name} — on ${kind}`,
+    enabled: bucket.meta.enabled,
+    trigger: { event: triggerEvent },
+    // Re-entry is a FILTER, never gated here.
+    entryLimit: "unlimited",
+    // Reactions intentionally have no re-entry cool-down.
+    suppress: { seconds: 0 },
+    sourceBucketId: bucket.meta.id,
+    reactionKind: kind,
+    ...(kind === "dwell"
+      ? { dwellSchedule: parseDwellSchedule(opts as DwellOptions) }
+      : {}),
+  };
+
+  return defineJourney({
+    meta,
+    run: async (user, ctx) => {
+      const p = user.properties;
+      if (kind === "enter") {
+        const entryCount = Number(p.entryCount ?? 1);
+        const isFirstEntry = entryCount === 1;
+        if (
+          (opts as EnterOptions | undefined)?.firstEntryOnly &&
+          !isFirstEntry
+        ) {
+          return;
+        }
+        await (handler as BucketOnHandler<"enter">)(user, {
+          ...ctx,
+          entryCount,
+          isFirstEntry,
+        });
+      } else if (kind === "leave") {
+        const reason = (p.reason as BucketLeaveReason) ?? "criteria";
+        const want = (opts as LeaveOptions | undefined)?.reason;
+        if (want && !asArray(want).includes(reason)) return;
+        await (handler as BucketOnHandler<"leave">)(user, { ...ctx, reason });
+      } else {
+        const dwellCount = Number(p.dwellCount ?? 1);
+        await (handler as BucketOnHandler<"dwell">)(user, {
+          ...ctx,
+          dwellCount,
+        });
+      }
+    },
+  });
+}

package/src/buckets/check-membership.ts

@@ -51,7 +51,16 @@ export async function checkBucketMembership(opts: {
   userId: string;
   userEmail: string | null;
   event: string;
-  properties: Record<string, unknown>;
+  /**
+   * D2: the event payload — candidate-narrowing ONLY. It NO LONGER participates
+   * in property eval (the raw-payload overlay was the bucket-side conflation).
+   */
+  eventProperties: Record<string, unknown>;
+  /**
+   * D2: this-ingest contact-property patch, overlaid on the read contact row so
+   * the very first event after a property change evaluates correctly (risk 7).
+   */
+  contactProperties?: Record<string, unknown>;
   /** Optional override; defaults to the process bucket-registry singleton. */
   bucketRegistry?: ReturnType<typeof getBucketRegistrySingleton>;
 }): Promise<BucketTransition[]> {
@@ -63,7 +72,8 @@ export async function checkBucketMembership(opts: {
     userId,
     userEmail,
     event,
-    properties,
+    eventProperties,
+    contactProperties: contactPropertiesPatch,
   } = opts;
 
   // (1) Recursion guard — MUST be first. bucket:-prefixed events are transition
@@ -81,12 +91,18 @@ export async function checkBucketMembership(opts: {
 
   // (2) Candidate narrowing — the UNION of buckets referencing this event name
   // (eventIndex + the degenerate wildcard set) and buckets referencing any
-  // property present in this payload (propertyIndex). Section 6.2.
+  // property present in EITHER bag (propertyIndex): the eventProperties drive
+  // event-shaped criteria narrowing, the contactProperties patch surfaces a
+  // contact-property change so a property-criteria bucket is re-checked on the
+  // first event that mutates it. Section 6.2.
   const candidateMap = new Map<string, BucketMeta>();
   for (const bucket of bucketRegistry.getByReferencedEvent(event)) {
     candidateMap.set(bucket.id, bucket);
   }
-  for (const key of Object.keys(properties ?? {})) {
+  for (const key of [
+    ...Object.keys(eventProperties ?? {}),
+    ...Object.keys(contactPropertiesPatch ?? {}),
+  ]) {
     for (const bucket of bucketRegistry.getByReferencedProperty(key)) {
       candidateMap.set(bucket.id, bucket);
     }
@@ -109,19 +125,20 @@ export async function checkBucketMembership(opts: {
     return [];
   }
 
-  // (3) Property predicates evaluate against MERGED contact state, NOT the bare
-  // event payload (Section 6.1 rule #3). Read the EXISTING contacts row ONCE iff
-  // any surviving candidate references a property — pure event/count buckets skip
-  // the read entirely. We read the row that already exists (not the one
-  // upsertContact is concurrently writing) so we do not depend on the
-  // fire-and-forget upsert having run.
+  // (3) Property predicates evaluate against contact state ⊕ this-ingest
+  // contactProperties patch — NOT the raw event payload (Section 6.1 rule #3 /
+  // D2). Read the EXISTING contacts row ONCE iff any surviving candidate
+  // references a property — pure event/count buckets skip the read entirely.
+  // `ingestEvent` already awaited `resolveOrCreateContact` before us, so the row
+  // exists by the resolved key; the patch overlay still covers the read-after-
+  // write gap on a contact's very first event (risk 7).
   const needsContactState = candidates.some(
     (bucket) =>
       bucket.criteria != null &&
       collectPropertyNames(bucket.criteria).length > 0,
   );
 
-  let contactProperties: Record<string, unknown> = {};
+  let storedContactProps: Record<string, unknown> = {};
   let contactDeleted = false;
   if (needsContactState) {
     const [contact] = await db
@@ -133,7 +150,7 @@ export async function checkBucketMembership(opts: {
       .where(eq(contacts.externalId, userId))
       .limit(1);
     if (contact) {
-      contactProperties =
+      storedContactProps =
         (contact.properties as Record<string, unknown> | null) ?? {};
       contactDeleted = contact.deletedAt != null;
     }
@@ -144,10 +161,12 @@ export async function checkBucketMembership(opts: {
     return [];
   }
 
-  // event payload overlays cumulative contact state.
+  // this-ingest contactProperties patch overlays stored contact state. The raw
+  // event payload is REMOVED from property eval (D2 — bucket prop-criteria see
+  // contact state only).
   const journeyContext: Record<string, unknown> = {
-    ...contactProperties,
-    ...(properties ?? {}),
+    ...storedContactProps,
+    ...(contactPropertiesPatch ?? {}),
   };
 
   const transitions: BucketTransition[] = [];
@@ -379,6 +398,7 @@ async function handleLeave(opts: {
     userEmail,
     epoch: flipped.entryCount,
     source: "event",
+    reason: "criteria",
   });
 
   return { bucketId: bucket.id, transition: "left" };

package/src/buckets/define-bucket.ts

@@ -1,6 +1,16 @@
 import { type CriteriaBuilder, criteriaBuilder } from "@hogsend/core";
 import type { BucketMeta, ConditionEval } from "@hogsend/core/types";
+import type { DefinedJourney } from "../journeys/define-journey.js";
 import type { hatchet } from "../lib/hatchet.js";
+import { type BucketAccessor, createBucketAccessor } from "./bucket-access.js";
+import {
+  type BucketOnHandler,
+  buildBucketReaction,
+  type DwellOptions,
+  type EnterOptions,
+  type LeaveOptions,
+  normalizeOnArgs,
+} from "./bucket-reactions.js";
 
 /**
  * `criteria` may be authored two ways:
@@ -15,12 +25,19 @@ export type CriteriaInput =
   | ((b: CriteriaBuilder) => ConditionEval);
 
 /** `BucketMeta` as authored — `criteria` accepts the builder function too. */
-export type BucketMetaInput = Omit<BucketMeta, "criteria"> & {
-  criteria?: CriteriaInput;
-};
+export type BucketMetaInput<Id extends string = string> = Omit<
+  BucketMeta,
+  "criteria" | "id"
+> & { id: Id; criteria?: CriteriaInput };
 
-export interface DefinedBucket {
+export type { DwellOptions };
+
+export interface DefinedBucket<Id extends string = string> {
   meta: BucketMeta;
+  /** Literal-typed transition ref: `"bucket:entered:<id>"`. */
+  readonly entered: `bucket:entered:${Id}`;
+  /** Literal-typed transition ref: `"bucket:left:<id>"`. */
+  readonly left: `bucket:left:${Id}`;
   /**
    * The only task a bucket ever holds is the opt-in per-user fast-expiry timer,
    * which is a DURABLE task (it `ctx.sleepFor`s — Section 6.5), so the type MUST
@@ -31,11 +48,34 @@ export interface DefinedBucket {
    * `bucketReconcileTask` handles time-based leaves regardless.
    */
   task?: ReturnType<typeof hatchet.durableTask>;
+  /** Reaction journeys generated by `.on()`. Read by the worker + container. */
+  reactions: DefinedJourney[];
+  count: BucketAccessor["count"];
+  has: BucketAccessor["has"];
+  members: BucketAccessor["members"];
+  membersIterator: BucketAccessor["membersIterator"];
+  on(kind: "enter", handler: BucketOnHandler<"enter">): DefinedBucket<Id>;
+  on(
+    kind: "enter",
+    opts: EnterOptions,
+    handler: BucketOnHandler<"enter">,
+  ): DefinedBucket<Id>;
+  on(kind: "leave", handler: BucketOnHandler<"leave">): DefinedBucket<Id>;
+  on(
+    kind: "leave",
+    opts: LeaveOptions,
+    handler: BucketOnHandler<"leave">,
+  ): DefinedBucket<Id>;
+  on(
+    kind: "dwell",
+    opts: DwellOptions,
+    handler: BucketOnHandler<"dwell">,
+  ): DefinedBucket<Id>;
 }
 
-export function defineBucket(options: {
-  meta: BucketMetaInput;
-}): DefinedBucket {
+export function defineBucket<const Id extends string>(options: {
+  meta: BucketMetaInput<Id>;
+}): DefinedBucket<Id> {
   // The ONLY transform defineBucket performs is resolving a builder-function
   // `criteria` to its `ConditionEval` (a one-shot, definition-time call). It does
   // NOT validate or build any task — `bucketMetaSchema.parse` still happens at
@@ -48,5 +88,36 @@ export function defineBucket(options: {
     criteria:
       typeof criteria === "function" ? criteria(criteriaBuilder) : criteria,
   };
-  return { meta };
+
+  // Pure string derivation — synchronous, no cross-module value binding (the
+  // ESM-cycle resolution): entered/left are stable the instant defineBucket
+  // returns, computed from meta.id, NOT bound to any other module's value.
+  const entered = `bucket:entered:${meta.id}` as `bucket:entered:${Id}`;
+  const left = `bucket:left:${meta.id}` as `bucket:left:${Id}`;
+  const reactions: DefinedJourney[] = [];
+  const accessor = createBucketAccessor(meta.id);
+
+  const bucket: DefinedBucket<Id> = {
+    meta,
+    entered,
+    left,
+    reactions,
+    count: accessor.count,
+    has: accessor.has,
+    members: accessor.members,
+    membersIterator: accessor.membersIterator,
+    on(kind: "enter" | "leave" | "dwell", a: unknown, b?: unknown) {
+      const { opts, handler } = normalizeOnArgs(kind, a, b);
+      reactions.push(
+        buildBucketReaction({
+          bucket: bucket as DefinedBucket,
+          kind,
+          opts,
+          handler,
+        }),
+      );
+      return bucket;
+    },
+  };
+  return bucket;
 }