@hogsend/core 0.0.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
     "./types": "./src/types/index.ts",
     "./registry": "./src/registry/index.ts",
     "./conditions": "./src/conditions/index.ts",
+    "./schedule": "./src/schedule/index.ts",
     "./schemas": "./src/schemas/index.ts"
   },
   "files": [
@@ -26,15 +27,20 @@
     "access": "public"
   },
   "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1",
     "drizzle-orm": "^0.45.2",
+    "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.0.1"
+    "@hogsend/db": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "latest",
+    "vitest": "^4.1.8",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
-    "check-types": "tsc --noEmit"
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/index.ts

@@ -11,6 +11,12 @@ export {
   hours,
   minutes,
 } from "./duration.js";
-export { JourneyRegistry } from "./registry/index.js";
-export { journeyMetaSchema } from "./schemas/index.js";
+export {
+  BucketRegistry,
+  collectEventNames,
+  collectPropertyNames,
+  JourneyRegistry,
+} from "./registry/index.js";
+export * from "./schedule/index.js";
+export { bucketMetaSchema, journeyMetaSchema } from "./schemas/index.js";
 export * from "./types/index.js";

package/src/registry/bucket.ts

@@ -0,0 +1,119 @@
+import { bucketMetaSchema } from "../schemas/index.js";
+import type { BucketMeta, ConditionEval } from "../types/index.js";
+
+/**
+ * Walk a ConditionEval tree, collecting every EventCondition.eventName. Pure
+ * tree walk over the discriminated union, mirroring core/conditions/event.ts.
+ */
+export function collectEventNames(criteria: ConditionEval): string[] {
+  const names: string[] = [];
+  const visit = (condition: ConditionEval): void => {
+    switch (condition.type) {
+      case "event":
+        names.push(condition.eventName);
+        break;
+      case "composite":
+        for (const child of condition.conditions) {
+          visit(child);
+        }
+        break;
+      default:
+        break;
+    }
+  };
+  visit(criteria);
+  return names;
+}
+
+/**
+ * Walk a ConditionEval tree, collecting every PropertyCondition.property. Pure
+ * tree walk over the discriminated union.
+ */
+export function collectPropertyNames(criteria: ConditionEval): string[] {
+  const names: string[] = [];
+  const visit = (condition: ConditionEval): void => {
+    switch (condition.type) {
+      case "property":
+        names.push(condition.property);
+        break;
+      case "composite":
+        for (const child of condition.conditions) {
+          visit(child);
+        }
+        break;
+      default:
+        break;
+    }
+  };
+  visit(criteria);
+  return names;
+}
+
+export class BucketRegistry {
+  private buckets: Map<string, BucketMeta> = new Map();
+  private eventIndex: Map<string, BucketMeta[]> = new Map();
+  private propertyIndex: Map<string, BucketMeta[]> = new Map();
+  // degenerate: criteria reference neither a concrete event nor any property
+  private wildcard: BucketMeta[] = [];
+
+  register(bucket: BucketMeta): void {
+    const parsed = bucketMetaSchema.parse(bucket);
+    const validated = parsed as unknown as BucketMeta;
+
+    this.buckets.set(validated.id, validated);
+
+    // manual buckets are not criteria-driven → not indexed for real-time eval
+    if (validated.kind === "manual" || !validated.criteria) {
+      return;
+    }
+
+    const events = collectEventNames(validated.criteria);
+    const props = collectPropertyNames(validated.criteria);
+
+    for (const eventName of events) {
+      const existing = this.eventIndex.get(eventName) ?? [];
+      existing.push(validated);
+      this.eventIndex.set(eventName, existing);
+    }
+
+    for (const propName of props) {
+      const existing = this.propertyIndex.get(propName) ?? [];
+      existing.push(validated);
+      this.propertyIndex.set(propName, existing);
+    }
+
+    // "*" ONLY for criteria referencing neither a concrete event nor a property
+    // (degenerate; rare under the at-least-one-positive rule).
+    if (events.length === 0 && props.length === 0) {
+      this.wildcard.push(validated);
+    }
+  }
+
+  get(id: string): BucketMeta | undefined {
+    return this.buckets.get(id);
+  }
+
+  getByReferencedEvent(eventName: string): BucketMeta[] {
+    return [...(this.eventIndex.get(eventName) ?? []), ...this.wildcard];
+  }
+
+  getByReferencedProperty(propName: string): BucketMeta[] {
+    return this.propertyIndex.get(propName) ?? [];
+  }
+
+  getAll(): BucketMeta[] {
+    return Array.from(this.buckets.values());
+  }
+
+  getEnabled(): BucketMeta[] {
+    return this.getAll().filter((b) => b.enabled);
+  }
+
+  has(id: string): boolean {
+    return this.buckets.has(id);
+  }
+
+  count(): number {
+    return this.buckets.size;
+  }
+}

package/src/registry/index.ts

@@ -1,6 +1,12 @@
 import { journeyMetaSchema } from "../schemas/index.js";
 import type { JourneyMeta } from "../types/index.js";
 
+export {
+  BucketRegistry,
+  collectEventNames,
+  collectPropertyNames,
+} from "./bucket.js";
+
 export class JourneyRegistry {
   private journeys: Map<string, JourneyMeta> = new Map();
   private triggerIndex: Map<string, JourneyMeta[]> = new Map();

package/src/schedule/index.ts

@@ -0,0 +1,10 @@
+export {
+  resolveAfter,
+  resolveNextLocalTime,
+  resolveNextWeekday,
+  resolveTomorrow,
+  type ScheduleOptions,
+} from "./resolvers.js";
+export { parseTimeOfDay, weekdayToIso } from "./time.js";
+export { isValidTimeZone, type TimeZone } from "./tz.js";
+export { clampToWindow, type SendWindow } from "./window.js";

package/src/schedule/resolvers.ts

@@ -0,0 +1,136 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DurationObject } from "../duration.js";
+import { durationToMs } from "../duration.js";
+import type { IfPast, Weekday } from "../types/journey-context.js";
+import { parseTimeOfDay, weekdayToIso } from "./time.js";
+import { clampToWindow, type SendWindow } from "./window.js";
+
+export interface ScheduleOptions {
+  /** Resolved IANA timezone, e.g. "America/New_York". */
+  timezone: string;
+  /** Explicit "current" instant — no ambient `Date.now()`. */
+  now: Date;
+  /** Optional quiet-hours window in the same tz. */
+  window?: SendWindow;
+  /** How to treat a naive resolved instant that is already <= now. */
+  ifPast?: IfPast;
+}
+
+/**
+ * Convert a `ZonedDateTime` to a `Date`, applying the `ifPast` policy and the
+ * optional send window. This is the shared tail of every resolver:
+ *
+ * 1. `ifPast` — `"next"` (default) rolls the instant forward by `rollDays` when
+ *    it is at/before `now` (never fewer than 1 day, so a snapped past instant
+ *    always lands in the future); `"now"` clamps it to the current instant.
+ * 2. `clampToWindow` — if a window is configured, the final instant is mapped
+ *    into the open window (the LAST step, after `ifPast`).
+ */
+function finalize(
+  candidate: Temporal.ZonedDateTime,
+  opts: ScheduleOptions,
+  rollDays: number,
+): Date {
+  const nowMs = opts.now.getTime();
+  let resolved = candidate;
+
+  if (resolved.epochMilliseconds <= nowMs) {
+    if ((opts.ifPast ?? "next") === "now") {
+      resolved = Temporal.Instant.fromEpochMilliseconds(
+        nowMs,
+      ).toZonedDateTimeISO(opts.timezone);
+    } else {
+      // ifPast "next": always roll forward. Resolvers that snap to an
+      // arbitrary HH:mm (resolveAfter / resolveTomorrow) pass rollDays 0, so a
+      // snapped time landing at/before now must still advance at least one day
+      // — otherwise a past instant would be returned and fire immediately.
+      resolved = resolved.add({ days: Math.max(rollDays, 1) });
+    }
+  }
+
+  const instant = new Date(resolved.epochMilliseconds);
+  return opts.window
+    ? clampToWindow(instant, opts.window, opts.timezone)
+    : instant;
+}
+
+/**
+ * Build the wall-clock `HH:mm` instant on `date` in `opts.timezone`.
+ *
+ * Disambiguation `"compatible"` (the JS-`Date` rule) is the documented choice:
+ * on a spring-forward gap it yields the post-gap instant ("first valid instant
+ * going forward"); on a fall-back overlap it yields the earlier occurrence.
+ */
+function atTime(
+  date: Temporal.PlainDate,
+  time: string,
+  timezone: string,
+): Temporal.ZonedDateTime {
+  const { hour, minute } = parseTimeOfDay(time);
+  return date
+    .toPlainDateTime(Temporal.PlainTime.from({ hour, minute }))
+    .toZonedDateTime(timezone, { disambiguation: "compatible" });
+}
+
+function nowZoned(opts: ScheduleOptions): Temporal.ZonedDateTime {
+  return Temporal.Instant.fromEpochMilliseconds(
+    opts.now.getTime(),
+  ).toZonedDateTimeISO(opts.timezone);
+}
+
+/**
+ * Next occurrence of `HH:mm` local: today if still in the future (per
+ * `ifPast`), otherwise tomorrow.
+ */
+export function resolveNextLocalTime(
+  time: string,
+  opts: ScheduleOptions,
+): Date {
+  const candidate = atTime(nowZoned(opts).toPlainDate(), time, opts.timezone);
+  return finalize(candidate, opts, 1);
+}
+
+/**
+ * Upcoming `weekday` at `HH:mm` local. If today IS the weekday and the time is
+ * still in the future, returns today; otherwise the next matching weekday
+ * (1..7 days ahead).
+ */
+export function resolveNextWeekday(
+  weekday: Weekday,
+  time: string,
+  opts: ScheduleOptions,
+): Date {
+  const targetIso = weekdayToIso(weekday);
+  const today = nowZoned(opts).toPlainDate();
+  const delta = (targetIso - today.dayOfWeek + 7) % 7;
+  const candidate = atTime(today.add({ days: delta }), time, opts.timezone);
+  // If the chosen day is today (delta === 0) but the time already passed, roll
+  // a full week forward rather than a single day.
+  return finalize(candidate, opts, 7);
+}
+
+/** Tomorrow (now + 1 calendar day in tz) at `HH:mm` local. */
+export function resolveTomorrow(time: string, opts: ScheduleOptions): Date {
+  const tomorrow = nowZoned(opts).toPlainDate().add({ days: 1 });
+  const candidate = atTime(tomorrow, time, opts.timezone);
+  // Tomorrow at HH:mm is already in the future; rollDays 0 means finalize only
+  // intervenes for ifPast="now" or the defensive 1-day roll if it ever lands
+  // at/before now.
+  return finalize(candidate, opts, 0);
+}
+
+/**
+ * `now` + `duration`, then snapped to `HH:mm` local on the resulting calendar
+ * day.
+ */
+export function resolveAfter(
+  duration: DurationObject,
+  time: string,
+  opts: ScheduleOptions,
+): Date {
+  const shifted = Temporal.Instant.fromEpochMilliseconds(
+    opts.now.getTime() + durationToMs(duration),
+  ).toZonedDateTimeISO(opts.timezone);
+  const candidate = atTime(shifted.toPlainDate(), time, opts.timezone);
+  return finalize(candidate, opts, 0);
+}

package/src/schedule/schedule.test.ts

@@ -0,0 +1,283 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { describe, expect, it } from "vitest";
+import { days, hours } from "../duration.js";
+import {
+  clampToWindow,
+  isValidTimeZone,
+  parseTimeOfDay,
+  resolveAfter,
+  resolveNextLocalTime,
+  resolveNextWeekday,
+  resolveTomorrow,
+  weekdayToIso,
+} from "./index.js";
+
+const NY = "America/New_York";
+
+/** Build a Date from a wall-clock time in a tz (compatible disambiguation). */
+function at(
+  tz: string,
+  y: number,
+  m: number,
+  d: number,
+  h: number,
+  min: number,
+): Date {
+  const zdt = Temporal.PlainDateTime.from({
+    year: y,
+    month: m,
+    day: d,
+    hour: h,
+    minute: min,
+  }).toZonedDateTime(tz, { disambiguation: "compatible" });
+  return new Date(zdt.epochMilliseconds);
+}
+
+/** UTC offset string ("-04:00") of a Date in a tz. */
+function offsetOf(date: Date, tz: string): string {
+  return Temporal.Instant.fromEpochMilliseconds(
+    date.getTime(),
+  ).toZonedDateTimeISO(tz).offset;
+}
+
+/** Local wall-clock "HH:mm" of a Date in a tz. */
+function wall(date: Date, tz: string): string {
+  const zdt = Temporal.Instant.fromEpochMilliseconds(
+    date.getTime(),
+  ).toZonedDateTimeISO(tz);
+  return `${String(zdt.hour).padStart(2, "0")}:${String(zdt.minute).padStart(
+    2,
+    "0",
+  )}`;
+}
+
+describe("parseTimeOfDay", () => {
+  it("parses HH:mm", () => {
+    expect(parseTimeOfDay("08:30")).toEqual({ hour: 8, minute: 30 });
+    expect(parseTimeOfDay("23:59")).toEqual({ hour: 23, minute: 59 });
+  });
+  it("throws on malformed / out-of-range", () => {
+    expect(() => parseTimeOfDay("8h")).toThrow();
+    expect(() => parseTimeOfDay("24:00")).toThrow();
+    expect(() => parseTimeOfDay("12:60")).toThrow();
+  });
+});
+
+describe("weekdayToIso", () => {
+  it("maps short and full names to the same ISO weekday", () => {
+    expect(weekdayToIso("tue")).toBe(2);
+    expect(weekdayToIso("tuesday")).toBe(2);
+    expect(weekdayToIso("sun")).toBe(7);
+    expect(weekdayToIso("monday")).toBe(1);
+  });
+});
+
+describe("resolveNextLocalTime", () => {
+  it("returns same-day when time is still future", () => {
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveNextLocalTime("14:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 1, 14, 0));
+  });
+
+  it("rolls to next day when past (ifPast default 'next')", () => {
+    const now = at(NY, 2026, 6, 1, 15, 0);
+    const got = resolveNextLocalTime("14:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 14, 0));
+  });
+
+  it("ifPast 'now' clamps to the current instant", () => {
+    const now = at(NY, 2026, 6, 1, 15, 0);
+    const got = resolveNextLocalTime("14:00", {
+      timezone: NY,
+      now,
+      ifPast: "now",
+    });
+    expect(got.getTime()).toBe(now.getTime());
+  });
+
+  it("exact equality (now == target) rolls forward under 'next'", () => {
+    const now = at(NY, 2026, 6, 1, 14, 0);
+    const got = resolveNextLocalTime("14:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 14, 0));
+  });
+});
+
+describe("resolveNextWeekday", () => {
+  it("short/full names produce identical instants", () => {
+    const now = at(NY, 2026, 6, 1, 9, 0); // Monday
+    const a = resolveNextWeekday("tue", "08:00", { timezone: NY, now });
+    const b = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(a).toEqual(b);
+  });
+
+  it("Mon → next Tuesday is tomorrow", () => {
+    const now = at(NY, 2026, 6, 1, 9, 0); // Monday 2026-06-01
+    const got = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("Tue 06:00 → today 08:00 (same-day future)", () => {
+    const now = at(NY, 2026, 6, 2, 6, 0); // Tuesday
+    const got = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("Tue 09:00 → next Tuesday (7 days)", () => {
+    const now = at(NY, 2026, 6, 2, 9, 0); // Tuesday
+    const got = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 9, 8, 0));
+  });
+
+  it("Sunday → next Monday is tomorrow (week wrap)", () => {
+    const now = at(NY, 2026, 6, 7, 12, 0); // Sunday 2026-06-07
+    const got = resolveNextWeekday("monday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 8, 8, 0));
+  });
+});
+
+describe("resolveTomorrow", () => {
+  it("returns tomorrow at HH:mm", () => {
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveTomorrow("08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+});
+
+describe("resolveAfter", () => {
+  it("now + 2 days snapped to 08:00 local", () => {
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveAfter(days(2), "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 3, 8, 0));
+  });
+
+  it("in 1 hour crossing midnight snaps to next day's HH:mm", () => {
+    const now = at(NY, 2026, 6, 1, 23, 30);
+    const got = resolveAfter(hours(1), "08:00", { timezone: NY, now });
+    // now + 1h => 2026-06-02 00:30 local => snapped to 08:00 that day.
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("snapped HH:mm earlier than now on the same day rolls forward (not past)", () => {
+    // now 09:00, +1h => 10:00 same day, but .at('08:00') pulls back to 08:00
+    // which is already in the past. Must roll to tomorrow's 08:00, never < now.
+    const now = at(NY, 2026, 6, 1, 9, 0);
+    const got = resolveAfter(hours(1), "08:00", { timezone: NY, now });
+    expect(got.getTime()).toBeGreaterThan(now.getTime());
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("snapped HH:mm earlier than now with ifPast 'now' clamps to current instant", () => {
+    const now = at(NY, 2026, 6, 1, 9, 0);
+    const got = resolveAfter(hours(1), "08:00", {
+      timezone: NY,
+      now,
+      ifPast: "now",
+    });
+    expect(got.getTime()).toBe(now.getTime());
+  });
+});
+
+describe("DST handling (America/New_York)", () => {
+  it("spring-forward gap (2026-03-08 02:30) picks post-gap EDT instant", () => {
+    // Clocks jump 02:00 -> 03:00; 02:30 does not exist.
+    const now = at(NY, 2026, 3, 8, 0, 0);
+    const got = resolveNextLocalTime("02:30", { timezone: NY, now });
+    // "compatible" => later instant; resulting offset is EDT (-04:00).
+    expect(offsetOf(got, NY)).toBe("-04:00");
+    expect(wall(got, NY)).toBe("03:30");
+  });
+
+  it("fall-back overlap (2026-11-01 01:30) picks earlier (EDT) instant", () => {
+    const now = at(NY, 2026, 11, 1, 0, 0);
+    const got = resolveNextLocalTime("01:30", { timezone: NY, now });
+    // The earlier of the two 01:30s is still EDT (-04:00).
+    expect(offsetOf(got, NY)).toBe("-04:00");
+    expect(wall(got, NY)).toBe("01:30");
+  });
+
+  it("resolveTomorrow across spring-forward uses calendar add (not +24h)", () => {
+    const now = at(NY, 2026, 3, 7, 23, 0); // EST
+    const got = resolveTomorrow("08:00", { timezone: NY, now });
+    expect(wall(got, NY)).toBe("08:00");
+    expect(offsetOf(got, NY)).toBe("-04:00"); // 2026-03-08 is EDT
+  });
+});
+
+describe("clampToWindow", () => {
+  const win = { start: "09:00", end: "17:00" };
+
+  it("inside window is unchanged", () => {
+    const inst = at(NY, 2026, 6, 1, 12, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(inst);
+  });
+
+  it("before open snaps to today's open", () => {
+    const inst = at(NY, 2026, 6, 1, 7, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(at(NY, 2026, 6, 1, 9, 0));
+  });
+
+  it("after close snaps to tomorrow's open", () => {
+    const inst = at(NY, 2026, 6, 1, 19, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(at(NY, 2026, 6, 2, 9, 0));
+  });
+
+  it("exactly at close (17:00) is treated as after-close", () => {
+    const inst = at(NY, 2026, 6, 1, 17, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(at(NY, 2026, 6, 2, 9, 0));
+  });
+
+  it("exactly at open (09:00) is unchanged (inclusive)", () => {
+    const inst = at(NY, 2026, 6, 1, 9, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(inst);
+  });
+
+  it("start === end is always open", () => {
+    const inst = at(NY, 2026, 6, 1, 3, 0);
+    const allDay = { start: "00:00", end: "00:00" };
+    expect(clampToWindow(inst, allDay, NY)).toEqual(inst);
+  });
+
+  describe("overnight window 22:00-06:00", () => {
+    const overnight = { start: "22:00", end: "06:00" };
+    it("23:00 is in the open tail", () => {
+      const inst = at(NY, 2026, 6, 1, 23, 0);
+      expect(clampToWindow(inst, overnight, NY)).toEqual(inst);
+    });
+    it("03:00 is in the early-morning open", () => {
+      const inst = at(NY, 2026, 6, 1, 3, 0);
+      expect(clampToWindow(inst, overnight, NY)).toEqual(inst);
+    });
+    it("12:00 quiet gap snaps forward to tonight's open", () => {
+      const inst = at(NY, 2026, 6, 1, 12, 0);
+      expect(clampToWindow(inst, overnight, NY)).toEqual(
+        at(NY, 2026, 6, 1, 22, 0),
+      );
+    });
+  });
+
+  it("clamp into next-open via resolver window option", () => {
+    // 19:00 local resolved with a 09:00-17:00 window => next day 09:00.
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveNextLocalTime("19:00", {
+      timezone: NY,
+      now,
+      window: win,
+    });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 9, 0));
+  });
+});
+
+describe("isValidTimeZone", () => {
+  it("accepts valid IANA zones", () => {
+    expect(isValidTimeZone("America/New_York")).toBe(true);
+    expect(isValidTimeZone("UTC")).toBe(true);
+    expect(isValidTimeZone("Europe/London")).toBe(true);
+  });
+  it("rejects invalid / empty without throwing", () => {
+    expect(isValidTimeZone("Not/AZone")).toBe(false);
+    expect(isValidTimeZone("")).toBe(false);
+    expect(isValidTimeZone("garbage")).toBe(false);
+    // @ts-expect-error testing non-string robustness
+    expect(isValidTimeZone(null)).toBe(false);
+  });
+});

package/src/schedule/time.ts

@@ -0,0 +1,53 @@
+import type { Weekday } from "../types/journey-context.js";
+
+export type { IfPast, Weekday } from "../types/journey-context.js";
+
+/**
+ * Map of accepted weekday names (short + full, lowercase) to ISO weekday
+ * numbers (Monday = 1 … Sunday = 7), matching `Temporal.PlainDate#dayOfWeek`.
+ */
+const WEEKDAY_TO_ISO: Record<Weekday, number> = {
+  mon: 1,
+  monday: 1,
+  tue: 2,
+  tuesday: 2,
+  wed: 3,
+  wednesday: 3,
+  thu: 4,
+  thursday: 4,
+  fri: 5,
+  friday: 5,
+  sat: 6,
+  saturday: 6,
+  sun: 7,
+  sunday: 7,
+};
+
+/**
+ * Resolve a {@link Weekday} name to its ISO weekday number (1..7). Throws on an
+ * unknown name — this is author error, not a runtime fall-through case.
+ */
+export function weekdayToIso(weekday: Weekday): number {
+  const iso = WEEKDAY_TO_ISO[weekday.toLowerCase() as Weekday];
+  if (iso === undefined) {
+    throw new TypeError(`Unknown weekday: "${weekday}"`);
+  }
+  return iso;
+}
+
+/**
+ * Parse a `"HH:mm"` string into `{ hour, minute }`. Throws on malformed input
+ * (author error — the scheduling API takes a literal time-of-day string).
+ */
+export function parseTimeOfDay(time: string): { hour: number; minute: number } {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!match) {
+    throw new TypeError(`Invalid time-of-day (expected "HH:mm"): "${time}"`);
+  }
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new TypeError(`Time-of-day out of range: "${time}"`);
+  }
+  return { hour, minute };
+}

package/src/schedule/tz.ts

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { TimezoneCode } from "iana-db-timezones";
+
+/**
+ * A valid IANA timezone identifier (e.g. `"America/New_York"`, `"Europe/London"`)
+ * — the full canonical + alias set, as a string-literal union. Sourced from
+ * `iana-db-timezones` (type-only import, erased at build). Use this for
+ * author-supplied timezones (`ctx.when.tz(...)`, client `defaults.timezone`) to
+ * get autocomplete and compile-time typo-catching. Timezones that arrive as
+ * runtime *data* (PostHog props, contact rows) stay plain `string` and are
+ * validated via {@link isValidTimeZone}.
+ */
+export type TimeZone = TimezoneCode;
+
+/**
+ * True if `tz` is a usable IANA timezone identifier. Probes the zone via
+ * Temporal inside a try/catch — it never throws, even on garbage input, so it
+ * is safe to use as a validity gate in a precedence chain.
+ */
+export function isValidTimeZone(tz: string): boolean {
+  if (typeof tz !== "string" || tz.length === 0) {
+    return false;
+  }
+  try {
+    // `Temporal.Now.zonedDateTimeISO(tz)` throws RangeError on an unknown zone.
+    Temporal.Now.zonedDateTimeISO(tz);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/schedule/window.ts

@@ -0,0 +1,91 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseTimeOfDay } from "./time.js";
+
+/** A quiet-hours / send window as wall-clock `"HH:mm"` edges in some tz. */
+export interface SendWindow {
+  start: string;
+  end: string;
+}
+
+/**
+ * Build the absolute instant for a `PlainDate` at `HH:mm` in `timezone`.
+ *
+ * All wall-clock → instant conversions use disambiguation `"compatible"` (the
+ * JS-`Date`-equivalent rule): on a spring-forward gap it picks the later (post-
+ * gap) instant; on a fall-back overlap it picks the earlier occurrence. This
+ * keeps window edges DST-safe.
+ */
+function instantAt(
+  date: Temporal.PlainDate,
+  hour: number,
+  minute: number,
+  timezone: string,
+): Temporal.ZonedDateTime {
+  return date
+    .toPlainDateTime(Temporal.PlainTime.from({ hour, minute }))
+    .toZonedDateTime(timezone, { disambiguation: "compatible" });
+}
+
+/**
+ * Map an instant into the open send window in `timezone`. No-op if the instant
+ * is already inside the window.
+ *
+ * - Normal window (`start < end`, e.g. `09:00`–`17:00`): open means
+ *   `open <= instant < close`. Before open → today's open; at/after close →
+ *   tomorrow's open.
+ * - Overnight window (`start > end`, e.g. `22:00`–`06:00`): wraps midnight.
+ *   Open means `instant >= open` OR `instant < close`. In the quiet daytime
+ *   gap → tonight's open.
+ * - `start === end` → always open (no clamp).
+ *
+ * "Next day" uses Temporal calendar arithmetic (`add({ days: 1 })`), so a 23/25-
+ * hour DST day still lands on the correct `HH:mm` wall-clock.
+ */
+export function clampToWindow(
+  instant: Date,
+  window: SendWindow,
+  timezone: string,
+): Date {
+  const { hour: openH, minute: openM } = parseTimeOfDay(window.start);
+  const { hour: closeH, minute: closeM } = parseTimeOfDay(window.end);
+
+  // start === end → always open.
+  if (openH === closeH && openM === closeM) {
+    return instant;
+  }
+
+  const zdt = Temporal.Instant.fromEpochMilliseconds(
+    instant.getTime(),
+  ).toZonedDateTimeISO(timezone);
+  const date = zdt.toPlainDate();
+
+  const todayOpen = instantAt(date, openH, openM, timezone);
+  const todayClose = instantAt(date, closeH, closeM, timezone);
+  const normal = openH < closeH || (openH === closeH && openM < closeM);
+
+  if (normal) {
+    if (Temporal.ZonedDateTime.compare(zdt, todayOpen) < 0) {
+      return new Date(todayOpen.epochMilliseconds);
+    }
+    if (Temporal.ZonedDateTime.compare(zdt, todayClose) >= 0) {
+      const tomorrowOpen = instantAt(
+        date.add({ days: 1 }),
+        openH,
+        openM,
+        timezone,
+      );
+      return new Date(tomorrowOpen.epochMilliseconds);
+    }
+    return instant;
+  }
+
+  // Overnight window (start > end): close is in the morning, open in the evening.
+  if (Temporal.ZonedDateTime.compare(zdt, todayClose) < 0) {
+    return instant; // early-morning open tail
+  }
+  if (Temporal.ZonedDateTime.compare(zdt, todayOpen) >= 0) {
+    return instant; // late-evening open head
+  }
+  // Quiet daytime gap [close, open) → snap forward to tonight's open.
+  return new Date(todayOpen.epochMilliseconds);
+}

package/src/schemas/bucket.schema.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { durationToMs } from "../duration.js";
+import type {
+  CompositeCondition,
+  ConditionEval,
+  EmailEngagementCondition,
+  EventCondition,
+  PropertyCondition,
+} from "../types/conditions.js";
+import { conditionEvalSchema } from "./journey.schema.js";
+
+const durationObjectSchema = z.object({
+  hours: z.number().optional(),
+  minutes: z.number().optional(),
+  seconds: z.number().optional(),
+});
+
+/**
+ * Walk a ConditionEval tree, yielding every leaf node (property / event /
+ * email_engagement). Composites recurse into their `conditions` array. Mirrors
+ * the pure discriminated-union walks in core/conditions.
+ */
+function* walkConditions(
+  condition: ConditionEval,
+): Generator<PropertyCondition | EventCondition | EmailEngagementCondition> {
+  if (condition.type === "composite") {
+    for (const child of (condition as CompositeCondition).conditions) {
+      yield* walkConditions(child);
+    }
+    return;
+  }
+  yield condition;
+}
+
+/**
+ * A leaf condition is "negative" when satisfying the bucket means the absence /
+ * inequality of data. A dynamic bucket whose every leaf is negative is
+ * degenerate/unbounded (the Customer.io rule), so at least one positive leaf is
+ * required.
+ *
+ * Exception: a TIME-BOUNDED behavioral absence — `event` `not_exists` with a
+ * `within` window ("did NOT do X in the last N") — is the canonical
+ * dormancy/churn predicate (e.g. the `went-dormant` bucket and the whole
+ * cron-reconcile leave path exist for it). It is bounded by its window, so it
+ * is NOT degenerate and counts as a legitimate anchor. Only an UNBOUNDED
+ * absence (`not_exists` with no `within`) matches nearly everyone and is
+ * treated as a pure-negation leaf.
+ */
+function isNegativeLeaf(
+  leaf: PropertyCondition | EventCondition | EmailEngagementCondition,
+): boolean {
+  switch (leaf.type) {
+    case "property":
+      return leaf.operator === "neq" || leaf.operator === "not_exists";
+    case "event":
+      return leaf.check === "not_exists" && leaf.within === undefined;
+    case "email_engagement":
+      return leaf.check === "not_opened" || leaf.check === "not_clicked";
+    default:
+      return false;
+  }
+}
+
+export const bucketMetaSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    enabled: z.boolean(),
+
+    kind: z.enum(["dynamic", "manual"]).optional(),
+
+    criteria: conditionEvalSchema.optional(),
+
+    reentry: z.enum(["once", "once_per_period", "unlimited"]).optional(),
+    reentryPeriod: durationObjectSchema.optional(),
+
+    minDwell: durationObjectSchema.optional(),
+    maxDwell: durationObjectSchema.optional(),
+
+    timeBased: z.boolean().optional(),
+    reconcileEvery: durationObjectSchema.optional(),
+    reconcileJoins: z.boolean().optional(),
+    fastExpiry: z.boolean().optional(),
+
+    syncToPostHog: z.boolean().optional(),
+    postHogPropertyKey: z.string().optional(),
+  })
+  .superRefine((meta, ctx) => {
+    const kind = meta.kind ?? "dynamic";
+    const criteria = meta.criteria as ConditionEval | undefined;
+
+    // minDwell is a floor, maxDwell an unconditional ceiling. A ceiling below the
+    // floor is contradictory — the TTL leave would be permanently blocked by the
+    // minDwell guard. Applies regardless of kind.
+    if (
+      meta.minDwell &&
+      meta.maxDwell &&
+      durationToMs(meta.maxDwell) < durationToMs(meta.minDwell)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["maxDwell"],
+        message: "maxDwell must be greater than or equal to minDwell.",
+      });
+    }
+
+    // Rule 4: kind/criteria coherence. Manual buckets skip rules 1–3.
+    if (kind === "manual") {
+      if (criteria !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["criteria"],
+          message: 'kind:"manual" buckets must not declare `criteria`.',
+        });
+      }
+      return;
+    }
+
+    // kind:"dynamic" (or omitted) REQUIRES a non-empty criteria.
+    if (criteria === undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["criteria"],
+        message: 'kind:"dynamic" buckets require a non-empty `criteria`.',
+      });
+      return;
+    }
+
+    const leaves = Array.from(walkConditions(criteria));
+
+    // Rule 1: at-least-one-positive-condition (dynamic buckets only).
+    if (leaves.length > 0 && leaves.every(isNegativeLeaf)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["criteria"],
+        message:
+          "Dynamic buckets must contain at least one positive condition; " +
+          "pure-negation criteria are degenerate/unbounded.",
+      });
+    }
+
+    for (const leaf of leaves) {
+      // Rule 2: reserved-prefix rejection on EventCondition.eventName.
+      if (leaf.type === "event" && leaf.eventName.startsWith("bucket:")) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["criteria"],
+          message:
+            "criteria must not reference a reserved `bucket:*` event name " +
+            `(found "${leaf.eventName}").`,
+        });
+      }
+
+      // Rule 3: email_engagement forbidden anywhere in v1.
+      if (leaf.type === "email_engagement") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["criteria"],
+          message:
+            "email_engagement conditions are not allowed in bucket criteria " +
+            "in v1.",
+        });
+      }
+    }
+  });

package/src/schemas/index.ts

@@ -1 +1,2 @@
+export { bucketMetaSchema } from "./bucket.schema.js";
 export { journeyMetaSchema } from "./journey.schema.js";

package/src/types/bucket.ts

@@ -0,0 +1,93 @@
+import type { DurationObject } from "../duration.js";
+import type { ConditionEval } from "./conditions.js";
+
+export interface BucketMeta {
+  id: string;
+  name: string;
+  description?: string;
+  /** Static load-time flag (guard #1), mirrors JourneyMeta.enabled. */
+  enabled: boolean;
+
+  /**
+   * Discriminator, declared NOW for forward-compat even though "manual" ships in
+   * Phase 4. "dynamic" (default) = membership auto-recomputed from `criteria`;
+   * "manual" = membership mutated only by explicit API/import, NO criteria,
+   * skipped by checkBucketMembership and the reconcile cron (early-continue, the
+   * Laudspeaker pattern). Declaring it up front keeps Phase 4 genuinely additive
+   * — no breaking change to BucketMeta later. Default "dynamic".
+   */
+  kind?: "dynamic" | "manual";
+
+  /**
+   * Membership predicate — the existing 4-type condition engine
+   * (packages/core/src/conditions/evaluate.ts). Inclusion AND exclusion come
+   * for free via neq / not_exists / not_opened and event check:"not_exists".
+   * REQUIRED for kind:"dynamic" (omit/empty for kind:"manual"). Dynamic buckets
+   * MUST contain at least one positive condition (validated; pure-negation
+   * buckets are degenerate/unbounded — the Customer.io rule). The
+   * at-least-one-positive refine applies to dynamic buckets only.
+   * NOTE: criteria MUST NOT reference a reserved `bucket:*` event name in any
+   * EventCondition.eventName (rejected at registration — see 4.2), so transition
+   * rows can never satisfy a bucket predicate.
+   */
+  criteria?: ConditionEval;
+
+  /**
+   * Re-entry policy for EMITTED join events (maps onto checkEntryLimit
+   * semantics). "once" = emit bucket:entered once ever; "once_per_period" =
+   * re-emit only after a prior leave + period elapses; "unlimited" = always.
+   * Default "unlimited".
+   */
+  reentry?: "once" | "once_per_period" | "unlimited";
+  reentryPeriod?: DurationObject;
+
+  /**
+   * Anti-flap: suppress bucket:left until membership has existed at least this
+   * long (debounce). Guards journeys from re-enroll spam on oscillation.
+   */
+  minDwell?: DurationObject;
+
+  /**
+   * Maximum dwell — an UNCONDITIONAL membership TTL. `maxDwell` after the user
+   * joined, the reconcile cron force-leaves them REGARDLESS of whether the
+   * criteria still match (contrast `within`, which is criteria-driven, and
+   * `minDwell`, which is a floor). Use it for time-boxed membership: "in this
+   * bucket for exactly N days, then out".
+   *
+   * Re-entry after a maxDwell exit is governed by `reentry` (per-bucket): pair
+   * with `reentry:"once"` / `"once_per_period"` for a HARD time-box (they stay
+   * out / cool off), or leave the default `"unlimited"` for a PERIODIC FLUSH
+   * (they re-join on their next qualifying event). Independent of `within` and
+   * `fastExpiry`; if `minDwell` is also set it must be <= `maxDwell` (validated).
+   * Enforced by the reconcile cron, so the exit lands within the reconcile
+   * cadence (default 5m), not to-the-second.
+   */
+  maxDwell?: DurationObject;
+
+  /**
+   * Reconciliation knobs.
+   * timeBased: criteria contain an event `within` window a clock can expire —
+   *   the ONLY kind the cron sweep touches (candidate narrowing). Inferred from
+   *   a criteria walk if omitted; an explicit value overrides.
+   * reconcileEvery: advisory cadence surfaced in Studio (the single engine-wide
+   *   cron sweeps all time-based buckets; per-bucket cadence is informational).
+   * reconcileJoins: also re-evaluate JOINS in the sweep (default false — the
+   *   real-time path already catches joins on event arrival; keep the sweep
+   *   O(active members)).
+   * fastExpiry: opt-in per-user durable timer for sub-second absence-leave on
+   *   latency-critical buckets (Approach A graft). The cron remains the
+   *   authoritative backstop. Default false.
+   */
+  timeBased?: boolean;
+  reconcileEvery?: DurationObject;
+  reconcileJoins?: boolean;
+  fastExpiry?: boolean;
+
+  /**
+   * PostHog person-property sync (Section 12). Off by default. When set, on
+   * join/leave the engine $set/$unset a boolean person property keyed by
+   * `postHogPropertyKey` (default `hogsend_bucket_<id>`).
+   */
+  syncToPostHog?: boolean;
+  postHogPropertyKey?: string;
+}

package/src/types/index.ts

@@ -1,3 +1,4 @@
+export * from "./bucket.js";
 export * from "./conditions.js";
 export * from "./journey.js";
 export * from "./journey-context.js";

package/src/types/journey-context.ts

@@ -1,4 +1,5 @@
 import type { DurationObject } from "../duration.js";
+import type { TimeZone } from "../schedule/tz.js";
 
 export interface SleepOptions {
   duration: DurationObject;
@@ -10,6 +11,51 @@ export interface SleepResult {
   resumedAt: string;
 }
 
+export interface SleepUntilOptions {
+  label?: string;
+}
+
+export type Weekday =
+  | "mon"
+  | "tue"
+  | "wed"
+  | "thu"
+  | "fri"
+  | "sat"
+  | "sun"
+  | "monday"
+  | "tuesday"
+  | "wednesday"
+  | "thursday"
+  | "friday"
+  | "saturday"
+  | "sunday";
+
+/** How to treat a resolved instant that is already in the past. */
+export type IfPast = "next" | "now";
+
+export interface TimeOfDayBuilder {
+  /** Resolve to an absolute instant at `time` ("HH:mm") in the bound tz. */
+  at(time: string): Date;
+}
+
+export interface WhenBuilder {
+  /** Upcoming named weekday; chain `.at("HH:mm")`. */
+  next(weekday: Weekday): TimeOfDayBuilder;
+  /** Next occurrence of `time` local (today if future, else tomorrow). */
+  nextLocal(time: string): Date;
+  /** Tomorrow in the bound tz; chain `.at("HH:mm")`. */
+  tomorrow(): TimeOfDayBuilder;
+  /** `duration` from now, snapped to `.at("HH:mm")` on that day. */
+  in(duration: DurationObject): TimeOfDayBuilder;
+  /** Override the resolved user tz for this chain only. Returns a new builder. */
+  tz(timezone: TimeZone): WhenBuilder;
+  /** Override the default send window for this chain. Returns a new builder. */
+  window(start: string, end: string): WhenBuilder;
+  /** How to treat an already-past resolved time. Default "next". */
+  ifPast(strategy: IfPast): WhenBuilder;
+}
+
 export interface TriggerOptions {
   event: string;
   userId: string;
@@ -52,6 +98,13 @@ export interface EmailHistoryResult {
 
 export interface JourneyContext {
   sleep(opts: SleepOptions): Promise<SleepResult>;
+
+  /** Durable sleep until an absolute instant (`Date` or ISO string). */
+  sleepUntil(at: Date | string, opts?: SleepUntilOptions): Promise<SleepResult>;
+
+  /** Timezone-bound fluent scheduler. Always terminates in a `Date`. */
+  when: WhenBuilder;
+
   checkpoint(label: string): Promise<void>;
   trigger(opts: TriggerOptions): Promise<void>;
   identify(properties: Record<string, unknown>): void;