@hogsend/core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "drizzle-orm": "^0.45.2",
     "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.1.0"
+    "@hogsend/db": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/index.ts

@@ -11,7 +11,12 @@ export {
   hours,
   minutes,
 } from "./duration.js";
-export { JourneyRegistry } from "./registry/index.js";
+export {
+  BucketRegistry,
+  collectEventNames,
+  collectPropertyNames,
+  JourneyRegistry,
+} from "./registry/index.js";
 export * from "./schedule/index.js";
-export { journeyMetaSchema } from "./schemas/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/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";