@hogsend/cli 0.2.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.2.2",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.5.0",
+    "@hogsend/studio": "^0.6.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {

package/skills/hogsend-authoring-buckets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hogsend-authoring-buckets
-description: Use when adding or editing a real-time audience bucket in src/buckets/ — defineBucket() with a criteria condition tree, time-based rolling windows + reconcile, entryLimit, the hand-maintained BucketId literal-union typo-safety ritual, and binding journeys to bucket:entered / bucket:left triggers. Buckets wire into BOTH createHogsendClient and createWorker.
+description: Use when adding or editing a real-time audience bucket in src/buckets/ — defineBucket() with a criteria condition tree, the typed bucket.entered / bucket.left transition refs used as journey trigger/exitOn, colocated bucket.on("enter"|"leave"|"dwell") reactions (dwell fires from the reconcile cron over the EXISTING population), member access (count/has/members/iterator), time-based rolling windows + reconcile, and entryLimit. Buckets wire into BOTH createHogsendClient and createWorker.
 license: MIT
 metadata:
   author: withSeismic
@@ -15,45 +15,213 @@ when it stops. Each transition fires `bucket:entered:<id>` / `bucket:left:<id>`
 through the same ingestion spine a journey trigger binds to, so buckets are how
 you turn "who is in this audience right now" into "start/stop a flow".
 
+A bucket is no longer JUST a membership primitive: the object `defineBucket`
+returns also carries **typed transition refs**, **colocated reactions**, and a
+**member-access surface**. So one bucket file is where you declare the audience,
+attach the behavior, and query it.
+
 This skill is for editing a scaffolded app's `src/buckets/` (content only). You
-import `defineBucket` / `DefinedBucket` from `@hogsend/engine` and the condition
-helpers / duration helpers from `@hogsend/core`. You never touch engine
-internals — the engine owns the registry, the reconcile cron, and the backfill.
+import `defineBucket` / `DefinedBucket` (and `sendEmail`, duration helpers) from
+`@hogsend/engine`, and the condition helpers from `@hogsend/core`. You never
+touch engine internals — the engine owns the registry, the reconcile cron, the
+backfill, and the reaction desugar.
 
 ## Key concepts
 
-- **`defineBucket({ meta })`** — returns a `DefinedBucket`. `meta.criteria` is the
-  membership predicate, authored as a `ConditionEval` data tree OR a fluent
-  `(b) => b.all(...)` builder function. Same condition system journeys use.
+- **`defineBucket({ meta })`** — returns a `DefinedBucket<Id>` generic over the
+  id literal. `meta.criteria` is the membership predicate, authored as a
+  `ConditionEval` data tree OR a fluent `(b) => b.all(...)` builder function. Same
+  condition system journeys use.
+- **Typed transition refs** — `bucket.entered` (`` `bucket:entered:${Id}` ``) and
+  `bucket.left` (`` `bucket:left:${Id}` ``) are literal-typed off the bucket's own
+  id, computed synchronously at `defineBucket` time. Drop them straight into a
+  journey's `trigger.event` / `exitOn`. **These are THE way to bind a journey to a
+  bucket** — typo-safe by construction, no hand-maintained union.
+- **Colocated reactions** — `bucket.on("enter" | "leave" | "dwell", opts?, handler)`.
+  Each desugars to a real durable journey (a `defineJourney` output) tagged with
+  `sourceBucketId`, triggered by the bucket's own transition event. The handler
+  gets the FULL `JourneyContext` (sleep / when / waitForEvent / guard / history /
+  trigger / identify) plus kind-specific read-only extras. `.on()` returns the
+  bucket, so calls chain and the reaction ships with the bucket — no separate
+  registration.
+- **`dwell`** — fires from the reconcile cron (cron resolution, NOT instant) for
+  members who have been CONTINUOUSLY in the bucket for `{ after }` / `{ every }`.
+  Its edge over `on("enter") + ctx.sleep` is that it fires for the EXISTING
+  population (backfill derives a historical anchor), so on first deploy it reaches
+  people already long-resident.
+- **Member access** — `bucket.count()` / `bucket.has(userId)` / `bucket.members({...})`
+  / `bucket.membersIterator()`. Supabase-shaped `{ data, error }` results, keyset
+  cursor, hard cap 100. NEVER an unbounded array.
 - **Real-time path** — on every ingested event the engine re-evaluates candidate
   buckets and writes/flips `bucket_memberships` rows, emitting transitions.
 - **Time-based path** — `criteria` with a rolling `within` window (or `maxDwell`)
   can flip membership with NO inbound event; the engine-wide reconcile cron
-  sweeps those leaves/joins on a cadence (default every 5 min).
+  sweeps those leaves/joins on a cadence (default every 5 min). The same cron runs
+  the `dwell` pass.
 - **`entryLimit` / `entryPeriod`** — gate when a RE-join re-emits `bucket:entered`.
-- **The `BucketId` ritual** — a hand-maintained literal union in
-  `src/journeys/constants/index.ts` plus `bucketEntered`/`bucketLeft` helpers that
-  make a typo'd trigger binding a COMPILE error.
 - **Dual wiring** — buckets thread into BOTH `createHogsendClient({ buckets })`
-  (registry, real-time eval, reconcile) AND `createWorker({ buckets })`
-  (fast-expiry timer task + boot backfill).
+  (registry, real-time eval, reconcile, reaction registration) AND
+  `createWorker({ buckets })` (reaction tasks + fast-expiry timer + boot backfill).
+  Reactions ship automatically on `bucket.reactions` — no separate registration —
+  and are `ENABLED_BUCKETS`-gated, NOT `ENABLED_JOURNEYS`-gated.
 
-Criteria use the same 4-type condition engine (property / event /
-email_engagement / composite) and the same `days()`/`hours()`/`minutes()`
+Criteria and reaction `opts` use the same 4-type condition engine (property /
+event / email_engagement / composite) and the same `days()`/`hours()`/`minutes()`
 duration helpers as journeys — see the hogsend-conditions skill for operator and
 window semantics.
 
+## The shape, end to end
+
+```ts
+import { days, defineBucket, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "../journeys/constants/index.js";
+
+export const wentDormant = defineBucket({
+  meta: {
+    id: "went-dormant",
+    name: "Went dormant",
+    enabled: true,
+    timeBased: true,
+    fastExpiry: true,
+    criteria: (b) =>
+      b.all(
+        b.event(Events.APP_ACTIVE).exists(),
+        b.event(Events.APP_ACTIVE).within(days(7)).notExists(),
+      ),
+  },
+});
+
+// Colocated reaction — desugars to a durable journey owned by the bucket
+// (grouped under it in Studio via sourceBucketId). `.on()` returns the bucket,
+// so it ships with the bucket; no separate registration.
+wentDormant.on("dwell", { after: days(30) }, async (user) => {
+  await sendEmail({
+    to: user.email,
+    userId: user.id,
+    journeyStateId: user.stateId,
+    template: Templates.REACTIVATION_FINAL_NUDGE,
+    subject: "Still here whenever you're ready",
+    journeyName: user.journeyName,
+  });
+});
+
+// Typed refs — bind a journey elsewhere to this bucket's transitions:
+//   defineJourney({ meta: { trigger: { event: wentDormant.entered }, ... } })
+//   defineJourney({ meta: { exitOn: [{ event: wentDormant.left }], ... } })
+```
+
 ## Task playbooks — load the matching reference
 
 - **Author / shape a bucket's `meta`** (id, criteria, time windows, entryLimit,
   dwell, fastExpiry) → `references/bucket-meta.md`
-- **Keep trigger names typo-safe** (the `BucketId` union + `bucketEntered`/
-  `bucketLeft` alias ritual and why it exists) → `references/bucket-id-aliases.md`
+- **Bind a journey to a bucket** (the typed `bucket.entered`/`bucket.left` refs;
+  the deprecated `BucketId` union + `bucketEntered`/`bucketLeft` legacy; the
+  any-bucket generic `Events.BUCKET_ENTERED`/`BUCKET_LEFT`) →
+  `references/bucket-id-aliases.md`
 - **Decide bucket vs journey** (membership vs a one-shot durable flow; how
   `bucket:entered`/`bucket:left` drive journeys) → `references/buckets-vs-journeys.md`
 - **Register + wire a bucket** (export from `src/buckets/index.ts`, thread into
-  `createHogsendClient` AND `createWorker`, the reconcile cron) →
-  `references/register-a-bucket.md`
+  `createHogsendClient` AND `createWorker`, the reconcile cron, reaction
+  registration) → `references/register-a-bucket.md`
+
+## Colocated reactions — `bucket.on(kind, opts?, handler)`
+
+A reaction is NOT an event-emitter listener. Each `.on()` desugars to ONE
+canonical durable journey tagged `sourceBucketId` + `reactionKind`, triggered by
+the bucket's own transition event. Because it IS a `defineJourney` output, it
+inherits the entire enrollment guard stack, the active-state dedup (concurrent
+transitions for one user serialize to a single live run), the durable context,
+and event routing — there is no parallel execution path. A SECOND or DIVERGENT
+reaction to the same transition is just a normal
+`defineJourney({ trigger: { event: bucket.entered } })`, not a second `.on()`.
+
+The handler is `(user, ctx)` — the same signature as a journey `run`. `ctx` is
+the full `JourneyContext` PLUS kind-specific read-only extras (built by spread,
+so the engine's canonical ctx is never mutated):
+
+| kind | trigger event | ctx extras | options (`opts`) |
+|------|---------------|------------|------------------|
+| `enter` | `bucket.entered` | `entryCount: number`, `isFirstEntry: boolean` | optional `{ firstEntryOnly? }` |
+| `leave` | `bucket.left` | `reason: "criteria" \| "maxDwell" \| "manual"` | optional `{ reason? }` (a reason or array) |
+| `dwell` | cron, internal `bucket:dwell:<id>:<label>` | `dwellCount: number` | **mandatory** `{ after }` XOR `{ every }` |
+
+```ts
+wentDormant
+  .on("enter", { firstEntryOnly: true }, async (user, ctx) => {
+    // ctx.entryCount / ctx.isFirstEntry; full JourneyContext too
+    await ctx.sleep({ duration: hours(1) });
+    await sendEmail({ /* ... */ });
+  })
+  .on("leave", { reason: "criteria" }, async (user, ctx) => {
+    // ctx.reason is "criteria" | "maxDwell" | "manual"
+  })
+  .on("dwell", { after: days(30) }, async (user, ctx) => {
+    // ctx.dwellCount — see dwell semantics below
+  });
+```
+
+`firstEntryOnly` and `reason` are FILTERS, never separate events — they run
+inside `run` AFTER enrollment (a filtered-out transition still writes a short
+active→completed `journeyStates` row). For `dwell` you MUST pass exactly one of
+`after` / `every`; passing neither or both is a `TypeError`.
+
+## `dwell` semantics (read before using it)
+
+`dwell` is the headline reaction. It fires from the engine-wide reconcile cron
+(`bucketReconcileTask`), so it is **cron-resolution, not instant** — a fire lands
+within the `BUCKET_RECONCILE_CRON` cadence (default `*/5 * * * *`).
+
+- **Continuous membership only.** It fires while the user has been CONTINUOUSLY a
+  member. A leave-then-rejoin is a NEW membership row with a fresh clock; the
+  dwell counter does not carry over.
+- **Fires for the EXISTING population.** This is the entire reason to reach for
+  `dwell` over `on("enter") + ctx.sleep(days(30))`. The sleep variant only clocks
+  users who enter AFTER you deploy it; `dwell` reads `enteredAt` (and a
+  backfill-derived historical `dwellAnchorAt`) over the active set, so on first
+  deploy it reaches people already long-resident rather than starting everyone's
+  clock at deploy time.
+- **`{ after }`** is one-shot — fires once when the member has dwelt continuously
+  for the duration. **`{ every }`** is recurring, coalescing — at most one fire
+  per sweep, so a multi-interval outage produces a single catch-up fire, not a
+  backlog.
+- **`ctx.dwellCount`** is the elapsed-interval ordinal
+  (`floor((now - anchor) / interval)`), NOT a count of actual fires — it is
+  gap-stable and equals the number of elapsed periods even across an outage. For
+  `after` it is always `1`.
+- **Idempotent** across sweeps (per-membership bookkeeping) and interop-correct
+  with `maxDwell` / `fastExpiry` (a member force-left by the TTL/expiry pass is
+  excluded). A bucket with `after >= maxDwell` simply never dwells (the member
+  leaves first).
+
+## Member access — never an unbounded array
+
+The bucket object exposes a read surface over its active members. Every method is
+`{ data, error }`-shaped (no throws; failures land in `error`), GDPR-joined to
+live contacts, and hard-capped at 100 rows per page.
+
+```ts
+const { data: total } = await wentDormant.count();          // number | null
+const { data: isMember } = await wentDormant.has(userId);   // boolean
+const page = await wentDormant.members({ limit: 50 });      // { data, error, count, cursor }
+for await (const m of wentDormant.membersIterator()) { /* paged internally */ }
+```
+
+- `count()` — one authoritative head-count `{ data, error }`.
+- `has(userId)` — O(1) active-membership probe `{ data, error }`.
+- `members({ limit?, cursor? })` — a single page `{ data, error, count, cursor }`.
+  Keyset cursor on `id` (opaque UUID order, NOT chronological); `cursor` is `null`
+  when exhausted. `count` here is a per-call snapshot that can drift under churn —
+  use `count()` for a single authoritative number.
+- `membersIterator({ pageSize? })` — the only full-population walk; bounded
+  page-by-page internally (throws on a page error).
+
+## Studio grouping
+
+A generated reaction carries `sourceBucketId` on its journey meta, so the admin
+bucket-detail view groups it UNDER its bucket, tagged `owned: true`. A journey
+that binds externally via `bucket.entered` / `bucket.left` (or the generic
+`Events.BUCKET_ENTERED`/`BUCKET_LEFT`) shows up there too, tagged `owned: false`.
+You don't wire any of this — it falls out of the desugar tagging.
 
 ## Golden rules
 
@@ -63,7 +231,18 @@ window semantics.
    valid (time-bounded) anchor.
 2. Never reference a `bucket:*` event name inside `criteria` — it is rejected at
    registration so transition rows can never satisfy a predicate.
-3. Add the new id to the `BucketId` union the moment you add the bucket. Without
-   it, a journey can bind to a misspelled alias that silently never fires.
-4. Wire `buckets` into BOTH factories. The client without the worker means no
-   reconcile/fast-expiry; the worker without the client means an empty registry.
+3. Bind journeys with the typed refs `bucket.entered` / `bucket.left` — they are
+   literal-typed off the bucket id and typo-safe by construction. The
+   `bucketEntered("id")`/`bucketLeft("id")` string helpers and the hand-maintained
+   `BucketId` union are DEPRECATED (kept one release for back-compat). For an
+   any-bucket binding, `Events.BUCKET_ENTERED` / `Events.BUCKET_LEFT` remain the
+   sanctioned generic surface (not deprecated).
+4. Reach for `dwell` only when you need the EXISTING population and
+   cron-resolution timing is acceptable; otherwise `on("enter") + ctx.sleep` is a
+   simpler per-user durable timer.
+5. Member access is read-only and paged — never load all members into an array;
+   use `count()`/`has()` for probes and the iterator for a full walk.
+6. Wire `buckets` into BOTH factories. The client without the worker means no
+   reconcile/fast-expiry/dwell and no reaction tasks; the worker without the
+   client means an empty registry. Reactions ship on `bucket.reactions`
+   automatically and are `ENABLED_BUCKETS`-gated.

package/skills/hogsend-authoring-buckets/references/bucket-id-aliases.md

@@ -1,4 +1,4 @@
-# The `BucketId` union + `bucketEntered` / `bucketLeft` ritual
+# Binding a journey to a bucket — typed refs (and the deprecated ritual)
 
 When a user joins or leaves a bucket the engine emits a per-bucket ALIAS event:
 `bucket:entered:<id>` / `bucket:left:<id>` (e.g. `bucket:entered:power-users`).
@@ -6,62 +6,29 @@ Journeys bind to those alias strings via `trigger.event`. The problem: a
 journey's `trigger.event` is typed `string`, so a misspelled alias compiles fine
 and the journey just silently never fires.
 
-The fix is a hand-maintained literal union plus two typed helper functions, in
-the CONSUMER's `src/journeys/constants/index.ts`. This is the ritual you MUST
-keep in sync whenever you add or rename a bucket.
-
-## The constants block
-
-```ts
-// src/journeys/constants/index.ts
-
-/**
- * The union of bucket ids registered in src/buckets/index.ts. Keep this in sync
- * with the `buckets` array — it is what makes the alias helpers catch a typo at
- * COMPILE time.
- */
-export type BucketId = "power-users";
-
-// Narrow-alias helpers — ONLY accept a registered BucketId, so a typo such as
-// bucketEntered("power-uesrs") is a compile error rather than a silently
-// never-firing trigger. The return type is the EXACT literal event name, so it
-// drops straight into a journey's trigger.event / exitOn rule.
-export const bucketEntered = <T extends BucketId>(id: T) =>
-  `bucket:entered:${id}` as const;
-
-export const bucketLeft = <T extends BucketId>(id: T) =>
-  `bucket:left:${id}` as const;
-```
-
-When you add a second bucket, the union grows by hand:
-
-```ts
-export type BucketId = "power-users" | "went-dormant";
-```
-
-## Why it MUST be a hand-written literal union
-
-You might be tempted to derive the union from the `buckets` array:
+The fix is no longer a hand-maintained union — it is built into the bucket
+object. `defineBucket` is generic over the id literal (`DefinedBucket<Id>`), so
+the bucket exposes two **typed transition refs** computed synchronously at
+`defineBucket` time:
 
 ```ts
-// DON'T — this collapses to `string` and loses all typo-safety.
-type BucketId = (typeof buckets)[number]["meta"]["id"];
+wentDormant.entered; // typed `"bucket:entered:went-dormant"`
+wentDormant.left;    // typed `"bucket:left:went-dormant"`
 ```
 
-`defineBucket` widens `meta.id` to `string` (`BucketMeta.id: string`), so an
-array-derived union evaluates to `string`. Then `bucketEntered("anything")`
-type-checks, and the whole guard is gone. The explicit literal union is the
-source of truth precisely because it can't be widened.
+These are literal-typed off the bucket's own `meta.id`, so binding to them is
+typo-safe by construction — there is nothing to keep in sync. This is THE way to
+bind a journey to a bucket.
 
-## How journeys consume the helpers
+## Use the typed refs in `trigger.event` / `exitOn`
 
-The helpers return the exact literal, so they drop straight into a journey's
-`trigger.event` (and `exitOn`):
+Import the bucket and read `.entered` / `.left` directly:
 
 ```ts
 import { hours } from "@hogsend/core";
 import { defineJourney, sendEmail } from "@hogsend/engine";
-import { bucketEntered, bucketLeft, Templates } from "./constants/index.js";
+import { wentDormant } from "../buckets/went-dormant.js"; // leaf module — see below
+import { Templates } from "./constants/index.js";
 
 export const winback = defineJourney({
   meta: {
@@ -69,12 +36,12 @@ export const winback = defineJourney({
     name: "Win-back",
     enabled: true,
     // Enroll the moment a user lands in the went-dormant bucket.
-    trigger: { event: bucketEntered("went-dormant") },
+    trigger: { event: wentDormant.entered },
     entryLimit: "once_per_period",
     // `suppress` is REQUIRED on every JourneyMeta — the re-entry cool-down.
     suppress: hours(24),
     // Pull them out the instant they re-activate (leave the bucket).
-    exitOn: [{ event: bucketLeft("went-dormant") }],
+    exitOn: [{ event: wentDormant.left }],
   },
   run: async (user) => {
     await sendEmail({
@@ -89,9 +56,23 @@ export const winback = defineJourney({
 });
 ```
 
-A typo'd id — `bucketEntered("went-dorment")` — is now a compile error.
+The refs are byte-identical to the alias the engine emits, so this is a drop-in
+for the old helper return value — only typo-safer. A typo'd ref —
+`wentDormant.entred` — is now a compile error.
+
+## Import the bucket from its LEAF module, not the barrel
 
-## Generic forms vs aliases
+When you read `wentDormant.left` at module-eval inside a top-level
+`defineJourney({ exitOn: [{ event: wentDormant.left }] })`, importing the bucket
+from the `../buckets/index.js` barrel creates a real ESM cycle
+(`journeys/index → this-journey → buckets/index → went-dormant → journeys/constants`).
+Import the bucket from its **leaf module** (`../buckets/went-dormant.js`)
+instead — that keeps the whole bucket barrel out of the journey-barrel cycle. The
+refs themselves are safe to read at module-eval because they are pure string
+concatenation of `meta.id` with no live cross-module value binding, but the leaf
+import keeps the cycle from forming at all.
+
+## Generic forms vs per-bucket refs
 
 The constants file also defines the GENERIC events:
 
@@ -103,15 +84,49 @@ export const Events = {
 } as const;
 ```
 
-These fire for ANY bucket. The engine only emits the generic `bucket:entered` /
-`bucket:left` when a journey actually binds to it (otherwise it's not written at
-all). Prefer the narrowly-routed per-bucket aliases (`bucketEntered(id)`) for
-real journey bindings — bind to the generic forms only if you genuinely want
-"any bucket transition" routing.
+These fire for ANY bucket and are the **sanctioned generic-binding surface — NOT
+deprecated**. The engine only emits the generic `bucket:entered` / `bucket:left`
+when a journey actually binds to it (otherwise it's not written at all). The rule:
+
+- **Per-bucket** (this audience specifically) → `bucket.entered` / `bucket.left`.
+- **Any-bucket** (any transition, whichever bucket) → `Events.BUCKET_ENTERED` /
+  `Events.BUCKET_LEFT`.
+
+## DEPRECATED — the `BucketId` union + `bucketEntered`/`bucketLeft` helpers
+
+The old path was a hand-maintained literal union plus two helper functions in
+`src/journeys/constants/`:
+
+```ts
+/** @deprecated Use the typed ref `bucket.entered` / `bucket.left`. */
+export type BucketId = "power-users" | "went-dormant";
+/** @deprecated Use `bucket.entered` (e.g. `wentDormant.entered`). */
+export const bucketEntered = <T extends BucketId>(id: T) =>
+  `bucket:entered:${id}` as const;
+/** @deprecated Use `bucket.left` (e.g. `wentDormant.left`). */
+export const bucketLeft = <T extends BucketId>(id: T) =>
+  `bucket:left:${id}` as const;
+```
+
+These are **deprecated and kept for ONE release for back-compat, then removed.**
+They still work and return the byte-identical alias, but they require you to
+hand-maintain the `BucketId` union in lockstep with the `buckets` array — exactly
+the chore the typed refs eliminate. Do NOT reach for them in new code; migrate
+existing `bucketEntered("id")` / `bucketLeft("id")` bindings to `bucket.entered` /
+`bucket.left` (importing the bucket from its leaf module).
+
+> Why the union could never just be derived from the array:
+> `defineBucket` widens `meta.id` to `string` on the base `DefinedBucket` type, so
+> `(typeof buckets)[number]["meta"]["id"]` collapses to `string` and loses all
+> typo-safety. The typed refs sidestep this entirely by keeping the `Id` literal
+> on `DefinedBucket<Id>` and deriving the ref type from it — provided the consumer
+> doesn't re-widen the array with a `DefinedBucket[]` annotation (see
+> register-a-bucket).
 
 ## The checklist when adding a bucket
 
 1. Add the `defineBucket(...)` in `src/buckets/`.
-2. Add its `meta.id` literal to the `BucketId` union.
-3. Register it in `src/buckets/index.ts` (see register-a-bucket).
-4. Bind journeys with `bucketEntered("<id>")` / `bucketLeft("<id>")`.
+2. Register it in `src/buckets/index.ts` (see register-a-bucket).
+3. Bind journeys with the typed refs `bucket.entered` / `bucket.left` (import the
+   bucket from its leaf module), or `Events.BUCKET_ENTERED`/`BUCKET_LEFT` for an
+   any-bucket binding.

package/skills/hogsend-authoring-buckets/references/bucket-meta.md

@@ -5,13 +5,12 @@ declaration — the engine derives everything (registry indexes, reconcile
 behavior, Studio size) from it. This is the field-by-field guide.
 
 ```ts
-import { defineBucket } from "@hogsend/engine";
-import { days } from "@hogsend/core";
+import { days, defineBucket } from "@hogsend/engine";
 import { Events } from "../journeys/constants/index.js";
 
 export const powerUsers = defineBucket({
   meta: {
-    id: "power-users",                 // also the alias suffix: bucket:entered:power-users
+    id: "power-users",                 // also the alias suffix → powerUsers.entered === "bucket:entered:power-users"
     name: "Power users",
     description: "Used the key feature 10+ times in the last 30 days.",
     enabled: true,
@@ -34,7 +33,7 @@ export const powerUsers = defineBucket({
 
 | Field | Type | Notes |
 |-------|------|-------|
-| `id` | `string` (required) | Stable identity AND the alias suffix. Changing it makes a NEW bucket. Keep it in the `BucketId` union (see bucket-id-aliases). |
+| `id` | `string` (required) | Stable identity AND the alias suffix — also the literal baked into the typed refs `bucket.entered` / `bucket.left` (see bucket-id-aliases). Changing it makes a NEW bucket. No hand-maintained union to update anymore. |
 | `name` | `string` (required) | Human label, surfaced in Studio + the emitted `bucketName`. |
 | `description` | `string?` | Free text. |
 | `enabled` | `boolean` (required) | Static load-time on/off (guard #1), mirrors a journey's `enabled`. A disabled bucket is not registered. |
@@ -51,6 +50,22 @@ export const powerUsers = defineBucket({
 | `syncToPostHog` | `boolean?` | Mirror membership to a PostHog person property on join/leave. Off by default; no-op without `POSTHOG_API_KEY`. |
 | `postHogPropertyKey` | `string?` | Override the synced property name (default `hogsend_bucket_<id>`). |
 
+## Beyond `meta` — the bucket object surface
+
+`defineBucket` returns a `DefinedBucket<Id>` generic over the id literal. Besides
+`meta`, the returned object carries everything you author or query AGAINST the
+bucket — none of it lives in `meta`:
+
+| On the bucket object | What it is |
+|----------------------|------------|
+| `bucket.entered` / `bucket.left` | Typed transition refs (`` `bucket:entered:${Id}` `` / `` `bucket:left:${Id}` ``), literal-typed off `meta.id`, derived synchronously at `defineBucket` time. Use as a journey `trigger.event` / `exitOn` (see bucket-id-aliases). |
+| `bucket.on(kind, opts?, handler)` | Colocated reaction — `"enter"` / `"leave"` / `"dwell"`. Each desugars to a real durable journey tagged `sourceBucketId`, pushed onto `bucket.reactions`. Returns the bucket, so calls chain. See the main SKILL for kinds, ctx extras, and dwell semantics. |
+| `bucket.reactions` | The array of generated reaction journeys (read by the client + worker). Ships automatically — you never register it. |
+| `bucket.count()` / `has(userId)` / `members({...})` / `membersIterator()` | Member-access read surface. `{ data, error }`-shaped, GDPR-joined, paged (hard cap 100), never an unbounded array. |
+
+So `meta` shapes WHO is in the bucket and HOW membership flips; the rest of the
+object is how you BIND to it, attach behavior, and read it.
+
 ## `criteria` — two authoring forms
 
 Both forms produce the SAME `ConditionEval` data. The builder runs ONCE at

package/skills/hogsend-authoring-buckets/references/buckets-vs-journeys.md

@@ -12,7 +12,9 @@ answer different questions:
   a beginning and an end, durable state, and enrollment guards.
 
 Buckets DRIVE journeys: a join/leave transition emits an event, and a journey
-can trigger (or exit) on that event. That's the whole integration.
+can trigger (or exit) on that event. That's the whole integration. A bucket can
+also carry its OWN behavior inline via `.on()` reactions (which themselves
+desugar to journeys — see below), and you can QUERY a bucket's members directly.
 
 ## Pick a bucket when…
 
@@ -23,7 +25,8 @@ can trigger (or exit) on that event. That's the whole integration.
   cron owns those leaves; a journey cannot observe "nothing happened".
 - You want to reuse the same audience for MANY downstream flows. One bucket, N
   journeys binding to its transitions.
-- You want the audience size visible in Studio.
+- You want the audience size visible in Studio, or you want to query membership
+  in code (`count` / `has` / `members`).
 
 ## Pick a journey when…
 
@@ -37,22 +40,24 @@ can trigger (or exit) on that event. That's the whole integration.
 On a real join the engine emits `bucket:entered:<id>`; on a leave,
 `bucket:left:<id>`. Both flow through the SAME `ingestEvent` pipeline a normal
 event does, so journeys route on them exactly like any other trigger. Bind with
-the typed `bucketEntered`/`bucketLeft` helpers (see bucket-id-aliases):
+the bucket's typed transition refs `bucket.entered` / `bucket.left` (literal-typed
+off the id — see bucket-id-aliases), importing the bucket from its leaf module:
 
 ```ts
 import { days, hours } from "@hogsend/core";
 import { defineJourney, sendEmail } from "@hogsend/engine";
-import { bucketEntered, bucketLeft, Templates } from "./constants/index.js";
+import { powerUsers } from "../buckets/power-users.js"; // leaf module, not the barrel
+import { Templates } from "./constants/index.js";
 
 export const powerUserOnboarding = defineJourney({
   meta: {
     id: "power-user-onboarding",
     name: "Power-user onboarding",
     enabled: true,
-    trigger: { event: bucketEntered("power-users") },   // join → start the flow
+    trigger: { event: powerUsers.entered },   // join → start the flow
     entryLimit: "once_per_period",
-    suppress: hours(24),                                 // required re-entry cool-down
-    exitOn: [{ event: bucketLeft("power-users") }],      // leave → pull them out
+    suppress: hours(24),                        // required re-entry cool-down
+    exitOn: [{ event: powerUsers.left }],      // leave → pull them out
   },
   run: async (user, ctx) => {
     await sendEmail({
@@ -69,6 +74,44 @@ export const powerUserOnboarding = defineJourney({
 });
 ```
 
+## Inline reaction vs a separate journey
+
+A bucket can also carry behavior INLINE with `bucket.on("enter" | "leave" |
+"dwell", ...)`. A reaction is NOT a lightweight listener — it **desugars to a real
+durable journey** tagged `sourceBucketId`, triggered by the bucket's own
+transition event, inheriting the full enrollment-guard stack and durable context.
+So the choice is about colocation, not capability:
+
+- **One canonical behavior per transition** that belongs WITH the audience →
+  colocate it as `bucket.on(...)`. It ships with the bucket and groups under it in
+  Studio.
+- **A SECOND or DIVERGENT behavior on the same transition** → write a normal
+  `defineJourney({ trigger: { event: bucket.entered } })`. There is one canonical
+  reaction per transition; everything beyond that is just another journey binding
+  to the typed ref. Don't stack multiple `.on("enter")` calls expecting an
+  emitter-style fan-out — that's what a separate journey is for.
+
+`dwell` has no journey equivalent: it fires from the reconcile cron over the
+EXISTING continuously-resident population, which `on("enter") + ctx.sleep` (a
+per-user durable timer that only clocks future entrants) cannot do. See the main
+SKILL for dwell semantics.
+
+## Querying a bucket's members
+
+A bucket is also a read surface — you don't need a journey to ask who's in it:
+
+```ts
+const { data: total } = await powerUsers.count();          // number | null
+const { data: isMember } = await powerUsers.has(userId);   // boolean
+const page = await powerUsers.members({ limit: 50 });      // { data, error, count, cursor }
+for await (const m of powerUsers.membersIterator()) { /* paged internally */ }
+```
+
+All results are `{ data, error }`-shaped, GDPR-joined to live contacts, and
+paged (hard cap 100) — never an unbounded array. Reach for these from a workflow,
+a custom route, or a script; reach for a journey when you need per-user durable
+control flow instead.
+
 ## The re-emit / debounce knobs work TOGETHER
 
 A bucket and the journeys it drives both have entry policies; tune them so
@@ -81,7 +124,8 @@ oscillation doesn't spam:
   `bucket:entered` (e.g. `"once_per_period"` with a 7-day `entryPeriod` won't
   re-emit a join within a week of the prior leave).
 - **Journey `entryLimit` / `suppress`** are the journey's own re-entry guard on
-  top of that.
+  top of that. (Generated reactions intentionally use `entryLimit:"unlimited"` +
+  `suppress:{seconds:0}` — re-entry is a filter there, not a cool-down.)
 
 Rule of thumb: shape the audience on the bucket (`criteria`, `minDwell`,
 `entryLimit`), shape the messaging cadence on the journey (`suppress`,