@shware/workflow 0.0.0-stage → 0.1.0

package/dist/dsl/flow.d.mts

@@ -0,0 +1,223 @@
+import { NodeIR } from "../ir.mjs";
+import { ActionRef } from "./action.mjs";
+import { Duration, TimeOfDay, Weekday } from "./base.mjs";
+import { EventRef, MessageArgs, PropInput } from "./refs.mjs";
+import { TemplateRef } from "./template.mjs";
+import { Condition } from "./condition.mjs";
+//#region src/dsl/flow.d.ts
+/**
+ * The flow chain — FlowBuilder is the DSL's step surface (messages, delays,
+ * flow control, data), and its implementation is the compiler front half: each
+ * chained call executes no logic, it just collects one IR node (ids are
+ * assigned later, in workflow.toIR()). Sub-flow callbacks run exactly once at
+ * construction — builder in, builder out — so the output is always a static
+ * tree.
+ *
+ * Every public method also captures its callsite (provenance): the loc lands
+ * in the node's hash-excluded meta and is the anchor for future in-place
+ * editing from the studio.
+ */
+type Scalar = string | number | boolean;
+/** An emitted field: a scalar (or a profile ref to one); a nested field cannot be sent. */
+type EmitValue<T> = [NonNullable<T>] extends [Scalar] ? PropInput<T> : never;
+/** The payload `sendEvent` accepts for an event: its fields, scalar ones only. */
+export type EmitPayload<P> = { [K in keyof P]: EmitValue<P[K]>; };
+/** Payload may be omitted when the event declares no required field. */
+export type EmitArgs<P> = Record<never, never> extends P ? [payload?: EmitPayload<P>] : [payload: EmitPayload<P>];
+/** Per-node push options. */
+export interface PushOptions {
+  /** Which devices get a copy: 'all' (the default) or only the most recently registered. */
+  devices?: 'all' | 'latest';
+}
+/** A reusable flow fragment (what `flow(...)` returns), referenced directly by branch arms. */
+export interface Flow {
+  readonly __flow: true;
+}
+/** Sub-flow: a named fragment, or an inline callback (runs once at construction — builder in, builder out). */
+export type SubFlow = Flow | ((w: FlowBuilder) => FlowBuilder);
+/** A branch arm: the [condition, sub-flow] tuple — an [if, then] ordering convention. */
+export type BranchCase = readonly [condition: Condition, flow: SubFlow];
+/**
+ * A branch argument: either a tuple arm, or a bare sub-flow meaning the default
+ * arm. The bare form may appear once, and must come last (checked at runtime).
+ */
+export type BranchArm = BranchCase | SubFlow;
+export interface FlowBuilder {
+  email<P extends object>(template: TemplateRef<'email', P>, ...props: MessageArgs<P>): this;
+  sms<P extends object>(template: TemplateRef<'sms', P>, ...props: MessageArgs<P>): this;
+  /**
+   * Push to the user's devices — every device the host's directory lists, or
+   * only the most recently registered with `{ devices: 'latest' }`. A user with
+   * no device is skipped (branch on `reachable('push')` to fall back to email).
+   */
+  push<P extends object>(template: TemplateRef<'push', P>, ...args: [...props: MessageArgs<P>, options?: PushOptions]): this;
+  inApp<P extends object>(template: TemplateRef<'in_app', P>, ...props: MessageArgs<P>): this;
+  slack<P extends object>(template: TemplateRef<'slack', P>, ...props: MessageArgs<P>): this;
+  discord<P extends object>(template: TemplateRef<'discord', P>, ...props: MessageArgs<P>): this;
+  survey<P extends object>(template: TemplateRef<'survey', P>, ...props: MessageArgs<P>): this;
+  /** Time Delay; passing { min, max } makes it a Randomized Delay. */
+  delay(duration: Duration): this;
+  delay(range: {
+    min: Duration;
+    max: Duration;
+  }): this;
+  /** Time Window: hold until inside the window (e.g. weekdays 09:00–17:00). tz: 'user' uses the user's timezone. */
+  timeWindow(opts: {
+    days?: readonly Weekday[];
+    between: readonly [TimeOfDay, TimeOfDay];
+    tz?: 'user' | (string & {});
+  }): this;
+  /**
+   * Wait Until: continue on the main line once the condition holds, or take
+   * onTimeout when it expires (default 'continue'). On the engine side this is
+   * "await event racing a timer" — a native primitive of durable runtimes.
+   */
+  waitUntil(condition: Condition, opts: {
+    timeout: Duration;
+    onTimeout?: 'continue' | 'exit' | SubFlow;
+  }): this;
+  /**
+   * Splice a fragment in place: a named `flow(...)` or a callback, expanded
+   * once while the workflow is defined — a composition step before compiling,
+   * not a node (the IR has no trace of it, and ids are assigned over the whole
+   * workflow as if the steps were written inline). Each use gets its own copy,
+   * so one fragment can be used in several places and workflows.
+   *
+   *   const preferPush = (push, email, props) =>
+   *     flow((w) => w.branch([reachable('push'), (b) => b.push(push, props)], (b) => b.email(email, props)));
+   *   workflow({ id: 'onboarding', ... }).use(preferPush(tipPush, tipEmail, { name: u.name }))
+   */
+  use(fragment: SubFlow): this;
+  /**
+   * Conditional branch: ordered first-match (same semantics as Step Functions
+   * Choice / Knock branch). This one primitive covers both the UI's True/False
+   * Branch (two arms) and Multi-Split Branch (N arms). Arms are
+   * [condition, sub-flow] tuples; a bare sub-flow in tail position is the
+   * default arm. With no match and no default, execution simply continues.
+   * Rejoin is structural: after the matching arm finishes, execution resumes
+   * at the node following the branch — to opt out, call .exit() inside the arm.
+   *
+   *   .branch([activeSubscriber, upgradeFlow], firstTimeFlow)   // True/False
+   *   .branch([vip, vipFlow], [trial, trialFlow], defaultFlow)  // Multi-Split
+   *   .branch([not(usedStaging), eduFlow])                      // single arm: no match continues
+   *
+   * The optional first argument `label` becomes the node's name in IR (UI title
+   * / observability handle). It is not a jump target — there is no goto here;
+   * looping is a future re-entry-policy topic (see sendEvent). Arm labels in
+   * the UI are derived from the condition.
+   */
+  branch(...arms: readonly BranchArm[]): this;
+  branch(label: string, ...arms: readonly BranchArm[]): this;
+  /**
+   * Gate: exit unless the condition holds, otherwise continue. A first-class
+   * node rather than sugar over branch — same semantics as Zapier's "only
+   * continue if" / Iterable's Filter tile, and rendered on its own in the UI.
+   * `reason` is the audit-log line — metadata, so rewording it is free
+   * (excluded from contentHash, see hash.ts).
+   */
+  filter(condition: Condition, opts?: {
+    reason?: string;
+  }): this;
+  /**
+   * Random Cohort Branch (A/B): weights must sum to 100 (checked at runtime).
+   * `key` names the experiment: bucketing hashes `userId:key` instead of the
+   * structural node id, so assignments survive node insertion/moves and the
+   * experiment keeps one identity across workflow versions — set it for any
+   * A/B whose results you intend to read.
+   *
+   * Arm names become node id segments and are read back in authoring order, so
+   * they are restricted to letters, digits, '_' and '-', never starting with a
+   * digit (checked at runtime).
+   */
+  cohort(arms: Record<string, {
+    weight: number;
+    flow?: SubFlow;
+  }>, opts?: {
+    key?: string;
+  }): this;
+  /**
+   * Exit: end the whole workflow immediately (the UI's Exit node); `reason`
+   * goes into the audit log and is metadata, so rewording it neither repins
+   * in-flight journeys nor shows up in plan. Inside a branch arm this means
+   * "terminate, do not rejoin" — it stops here instead of falling through,
+   * while an arm without exit rejoins naturally.
+   */
+  exit(reason?: string): this;
+  /**
+   * Emit a typed event (customer.io's Send Event). The event comes from an
+   * e.xxx reference, so payload types flow in the same way trigger.event works.
+   * This is how workflows compose: an event can trigger another workflow, and
+   * the resulting call graph is statically analyzable. Payload values may
+   * reference u.xxx. Only scalar fields can be sent (IR carries literals and
+   * profile refs, not nested JSON): an event whose payload requires a nested
+   * field cannot be emitted from a journey, and the types say so.
+   *
+   * Note on loops: a trailing self-triggering sendEvent will become the
+   * official periodic-flow shape *once a re-entry policy exists* — today the
+   * entry policy is once-per-user, so a self-trigger cannot re-enter and does
+   * not loop.
+   * TODO: the rest of the Data category — outbound webhook / profile update /
+   * journey attributes.
+   */
+  sendEvent<P extends object>(event: EventRef<P>, ...payload: EmitArgs<P>): this;
+  /**
+   * Run a custom action (see dsl/action.ts for the model). The chain records
+   * identity only — name, args, codeHash — never the code: the implementation
+   * ships inside the deployed Worker bundle and is resolved by name from the
+   * runtime registry. Args are typed by the ActionRef and may reference u.xxx,
+   * resolved at run time exactly like message props. Executed inside a durable
+   * step: retried on throw, checkpointed on success.
+   */
+  run<A extends object>(action: ActionRef<A>, ...args: MessageArgs<A>): this;
+}
+/** @internal extended by WorkflowBuilderImpl; not part of the public API */
+export declare class FlowBuilderImpl implements FlowBuilder {
+  /** Nodes as collected; ids are assigned in one pass inside toIR, so '' is a placeholder here. */
+  readonly nodes: NodeIR[];
+  /** Provenance: the callsite (captured in the public method) lands in meta.loc, outside the hash. */
+  private pushNode;
+  private message;
+  email<P extends object>(t: TemplateRef<'email', P>, ...args: MessageArgs<P>): this;
+  sms<P extends object>(t: TemplateRef<'sms', P>, ...args: MessageArgs<P>): this;
+  push<P extends object>(t: TemplateRef<'push', P>, ...args: [...props: MessageArgs<P>, options?: PushOptions]): this;
+  inApp<P extends object>(t: TemplateRef<'in_app', P>, ...args: MessageArgs<P>): this;
+  slack<P extends object>(t: TemplateRef<'slack', P>, ...args: MessageArgs<P>): this;
+  discord<P extends object>(t: TemplateRef<'discord', P>, ...args: MessageArgs<P>): this;
+  survey<P extends object>(t: TemplateRef<'survey', P>, ...args: MessageArgs<P>): this;
+  delay(duration: Duration): this;
+  delay(range: {
+    min: Duration;
+    max: Duration;
+  }): this;
+  timeWindow(opts: {
+    days?: readonly Weekday[];
+    between: readonly [TimeOfDay, TimeOfDay];
+    tz?: 'user' | (string & {});
+  }): this;
+  waitUntil(condition: Condition, opts: {
+    timeout: Duration;
+    onTimeout?: 'continue' | 'exit' | SubFlow;
+  }): this;
+  use(fragment: SubFlow): this;
+  branch(...arms: readonly BranchArm[]): this;
+  branch(label: string, ...arms: readonly BranchArm[]): this;
+  filter(condition: Condition, opts?: {
+    reason?: string;
+  }): this;
+  cohort(arms: Record<string, {
+    weight: number;
+    flow?: SubFlow;
+  }>, opts?: {
+    key?: string;
+  }): this;
+  exit(reason?: string): this;
+  sendEvent<P extends object>(ev: EventRef<P>, ...payload: EmitArgs<P>): this;
+  run<A extends object>(a: ActionRef<A>, ...args: MessageArgs<A>): this;
+}
+/**
+ * A reusable flow fragment: a free function. Once personalization goes through
+ * u.xxx and events through e.xxx, the flow layer carries no schema generics.
+ */
+export declare function flow(build: (w: FlowBuilder) => FlowBuilder): Flow;
+//#endregion
+//# sourceMappingURL=flow.d.mts.map

package/dist/dsl/flow.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.mts","names":[],"sources":["../../src/dsl/flow.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAqBK;;KAGA,UAAU,MAAM,YAAY,aAAa,UAAU,UAAU;;YAGtD,YAAY,QAAQ,WAAW,IAAI,UAAU,EAAE;;YAG/C,SAAS,KACnB,6BAA6B,KAAK,UAAU,YAAY,OAAO,SAAS,YAAY;;iBAGrE;;EAEf;;;iBAIe;WACN;;;YAQC,UAAU,SAAS,GAAG,gBAAgB;;YAGtC,uBAAuB,WAAW,WAAW,MAAM;;;;;YAMnD,YAAY,aAAa;iBAsCpB;EAEf,MAAM,kBAAkB,UAAU,qBAAqB,OAAO,OAAO,YAAY;EACjF,IAAI,kBAAkB,UAAU,mBAAmB,OAAO,OAAO,YAAY;;;;;;EAM7E,KAAK,kBACH,UAAU,oBAAoB,OAC3B,UAAU,OAAO,YAAY,IAAI,UAAU;EAEhD,MAAM,kBAAkB,UAAU,sBAAsB,OAAO,OAAO,YAAY;EAClF,MAAM,kBAAkB,UAAU,qBAAqB,OAAO,OAAO,YAAY;EACjF,QAAQ,kBAAkB,UAAU,uBAAuB,OAAO,OAAO,YAAY;EACrF,OAAO,kBAAkB,UAAU,sBAAsB,OAAO,OAAO,YAAY;;EAInF,MAAM,UAAU;EAChB,MAAM;IAAS,KAAK;IAAU,KAAK;;;EAGnC,WAAW;IACT,gBAAgB;IAChB,mBAAmB,WAAW;IAC9B;;;;;;;EAQF,UACE,WAAW,WACX;IAAQ,SAAS;IAAU,kCAAkC;;;;;;;;;;;;;EAc/D,IAAI,UAAU;;;;;;;;;;;;;;;;;;;EAqBd,UAAU,eAAe;EACzB,OAAO,kBAAkB,eAAe;;;;;;;;EASxC,OAAO,WAAW,WAAW;IAAS;;;;;;;;;;;;;EAatC,OAAO,MAAM;IAAiB;IAAgB,OAAO;MAAY;IAAS;;;;;;;;;EAS1E,KAAK;;;;;;;;;;;;;;;;;EAmBL,UAAU,kBAAkB,OAAO,SAAS,OAAO,SAAS,SAAS;;;;;;;;;EAUrE,IAAI,kBAAkB,QAAQ,UAAU,OAAO,MAAM,YAAY;;;qBAQtD,2BAA2B;;WAE7B,OAAO;;UAGR;UAKA;EAqBR,MAAM,kBAAkB,GAAG,qBAAqB,OAAO,MAAM,YAAY;EAGzE,IAAI,kBAAkB,GAAG,mBAAmB,OAAO,MAAM,YAAY;EAGrE,KAAK,kBACH,GAAG,oBAAoB,OACpB,UAAU,OAAO,YAAY,IAAI,UAAU;EAMhD,MAAM,kBAAkB,GAAG,sBAAsB,OAAO,MAAM,YAAY;EAG1E,MAAM,kBAAkB,GAAG,qBAAqB,OAAO,MAAM,YAAY;EAGzE,QAAQ,kBAAkB,GAAG,uBAAuB,OAAO,MAAM,YAAY;EAG7E,OAAO,kBAAkB,GAAG,sBAAsB,OAAO,MAAM,YAAY;EAI3E,MAAM,UAAU;EAChB,MAAM;IAAS,KAAK;IAAU,KAAK;;EAqBnC,WAAW;IACT,gBAAgB;IAChB,mBAAmB,WAAW;IAC9B;;EAsBF,UACE,WAAW,WACX;IAAQ,SAAS;IAAU,kCAAkC;;EAiB/D,IAAI,UAAU;EAMd,UAAU,eAAe;EACzB,OAAO,kBAAkB,eAAe;EAsCxC,OAAO,WAAW,WAAW;IAAS;;EAYtC,OAAO,MAAM;IAAiB;IAAgB,OAAO;MAAY;IAAS;;EAmD1E,KAAK;EAOL,UAAU,kBAAkB,IAAI,SAAS,OAAO,SAAS,SAAS;EAwBlE,IAAI,kBAAkB,GAAG,UAAU,OAAO,MAAM,YAAY;;;;;;wBAmB9C,KAAK,QAAQ,GAAG,gBAAgB,cAAc"}

package/dist/dsl/flow.mjs

@@ -0,0 +1,226 @@
+import { captureLoc } from "../provenance.mjs";
+import { durationIR, timeOfDayMinutes } from "./base.mjs";
+import { condIR } from "./condition.mjs";
+//#region src/dsl/flow.ts
+/**
+* A cohort arm name has two jobs, and both constrain its spelling:
+* - it is interpolated into the node ids of the arm's flow ('{id}.{name}.{j}'),
+*   and an id is a durable step name — a dot would fake a nesting level and can
+*   collide with a real one, an empty name gives '{id}..{j}';
+* - it is an object key, and JavaScript lists integer-like keys first in
+*   ascending numeric order however the author wrote them. The arms array is
+*   documented (and interpreted) as authoring order, and the bucketing walk
+*   accumulates weights along it, so an arm named '0' added to a live
+*   experiment would prepend itself and re-bucket everyone already in it.
+*/
+const ARM_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function resolveSubFlow(sub) {
+	if (typeof sub === "function") {
+		const builder = new FlowBuilderImpl();
+		if (typeof sub(builder)?.then === "function") throw new TypeError("sub-flow callbacks must be synchronous: they run once, while the workflow is defined");
+		return builder.nodes;
+	}
+	return structuredClone(sub.nodes);
+}
+/** @internal extended by WorkflowBuilderImpl; not part of the public API */
+var FlowBuilderImpl = class {
+	/** Nodes as collected; ids are assigned in one pass inside toIR, so '' is a placeholder here. */
+	nodes = [];
+	/** Provenance: the callsite (captured in the public method) lands in meta.loc, outside the hash. */
+	pushNode(node, loc) {
+		this.nodes.push({
+			...node,
+			...loc !== void 0 ? { meta: { loc } } : {}
+		});
+		return this;
+	}
+	message(channel, tpl, props, loc, devices) {
+		return this.pushNode({
+			id: "",
+			type: "message",
+			channel,
+			template: tpl.key,
+			props: props ?? {},
+			...devices !== void 0 ? { devices } : {}
+		}, loc);
+	}
+	email(t, ...args) {
+		return this.message("email", t, args[0], captureLoc(this.email));
+	}
+	sms(t, ...args) {
+		return this.message("sms", t, args[0], captureLoc(this.sms));
+	}
+	push(t, ...args) {
+		const [props, options] = args;
+		const devices = options?.devices === "latest" ? "latest" : void 0;
+		return this.message("push", t, props, captureLoc(this.push), devices);
+	}
+	inApp(t, ...args) {
+		return this.message("in_app", t, args[0], captureLoc(this.inApp));
+	}
+	slack(t, ...args) {
+		return this.message("slack", t, args[0], captureLoc(this.slack));
+	}
+	discord(t, ...args) {
+		return this.message("discord", t, args[0], captureLoc(this.discord));
+	}
+	survey(t, ...args) {
+		return this.message("survey", t, args[0], captureLoc(this.survey));
+	}
+	delay(d) {
+		const loc = captureLoc(this.delay);
+		if (typeof d === "string") return this.pushNode({
+			id: "",
+			type: "delay",
+			duration: durationIR(d)
+		}, loc);
+		const min = durationIR(d.min);
+		const max = durationIR(d.max);
+		if (max.ms < min.ms) throw new Error(`delay(): 'max' must not be shorter than 'min', got { min: '${d.min}', max: '${d.max}' }`);
+		return this.pushNode({
+			id: "",
+			type: "random_delay",
+			min,
+			max
+		}, loc);
+	}
+	timeWindow(opts) {
+		const loc = captureLoc(this.timeWindow);
+		const start = timeOfDayMinutes(opts.between[0]);
+		if (timeOfDayMinutes(opts.between[1]) <= start) throw new Error(`timeWindow(): 'between' must open before it closes within one day, got [${opts.between[0]}, ${opts.between[1]}] (overnight windows are not supported yet)`);
+		return this.pushNode({
+			id: "",
+			type: "time_window",
+			days: [...opts.days ?? [
+				"mon",
+				"tue",
+				"wed",
+				"thu",
+				"fri",
+				"sat",
+				"sun"
+			]],
+			between: [opts.between[0], opts.between[1]],
+			tz: opts.tz ?? "user"
+		}, loc);
+	}
+	waitUntil(condition, opts) {
+		const loc = captureLoc(this.waitUntil);
+		const onTimeout = opts.onTimeout ?? "continue";
+		return this.pushNode({
+			id: "",
+			type: "wait_until",
+			condition: condIR(condition),
+			timeout: durationIR(opts.timeout),
+			onTimeout: onTimeout === "continue" || onTimeout === "exit" ? onTimeout : resolveSubFlow(onTimeout)
+		}, loc);
+	}
+	use(fragment) {
+		this.nodes.push(...resolveSubFlow(fragment));
+		return this;
+	}
+	branch(...args) {
+		const loc = captureLoc(this.branch);
+		const label = typeof args[0] === "string" ? args[0] : void 0;
+		const arms = label === void 0 ? args : args.slice(1);
+		const cases = [];
+		let otherwise;
+		arms.forEach((arm, i) => {
+			if (Array.isArray(arm)) {
+				if (otherwise !== void 0) throw new Error("branch(): default arm (bare sub-flow) must be the last argument");
+				const [condition, sub] = arm;
+				cases.push({
+					condition: condIR(condition),
+					flow: resolveSubFlow(sub)
+				});
+			} else {
+				if (otherwise !== void 0) throw new Error("branch(): only one default arm (bare sub-flow) is allowed");
+				if (i !== arms.length - 1) throw new Error("branch(): default arm (bare sub-flow) must be the last argument");
+				otherwise = resolveSubFlow(arm);
+			}
+		});
+		return this.pushNode({
+			id: "",
+			type: "branch",
+			...label !== void 0 ? { label } : {},
+			cases,
+			...otherwise !== void 0 ? { otherwise } : {}
+		}, loc);
+	}
+	filter(condition, opts) {
+		return this.pushNode({
+			id: "",
+			type: "filter",
+			condition: condIR(condition),
+			...opts?.reason !== void 0 ? { reason: opts.reason } : {}
+		}, captureLoc(this.filter));
+	}
+	cohort(arms, opts) {
+		const loc = captureLoc(this.cohort);
+		const entries = Object.entries(arms);
+		const total = entries.map(([name, a]) => {
+			if (!ARM_NAME.test(name)) throw new Error(`cohort(): arm name '${name}' must start with a letter or '_' and contain only letters, digits, '_' or '-' — arm names become node id segments, and integer-like names would silently reorder the arms`);
+			const bp = a.weight * 100;
+			if (Math.abs(bp - Math.round(bp)) > 1e-6) throw new Error(`cohort(): arm '${name}' weight ${a.weight} is finer than the 0.01% bucketing grid — use at most two decimal places`);
+			if (bp < 0) throw new Error(`cohort(): arm '${name}' weight ${a.weight} must not be negative`);
+			return Math.round(bp);
+		}).reduce((sum, bp) => sum + bp, 0);
+		if (total !== 1e4) throw new Error(`cohort(): weights must sum to 100, got ${total / 100}`);
+		return this.pushNode({
+			id: "",
+			type: "cohort",
+			...opts?.key !== void 0 ? { key: opts.key } : {},
+			arms: entries.map(([name, a]) => ({
+				name,
+				weight: a.weight,
+				flow: a.flow ? resolveSubFlow(a.flow) : []
+			}))
+		}, loc);
+	}
+	exit(reason) {
+		return this.pushNode({
+			id: "",
+			type: "exit",
+			...reason !== void 0 ? { reason } : {}
+		}, captureLoc(this.exit));
+	}
+	sendEvent(ev, ...payload) {
+		const values = payload[0] ?? {};
+		for (const [field, value] of Object.entries(values)) if (!(typeof value === "object" && value !== null && value.type === "user_property") && ![
+			"string",
+			"number",
+			"boolean"
+		].includes(typeof value)) throw new TypeError(`sendEvent('${ev.name}'): '${field}' is not a scalar or a u.xxx reference — an emitted payload carries scalar fields only`);
+		return this.pushNode({
+			id: "",
+			type: "send_event",
+			event: ev.name,
+			payload: values
+		}, captureLoc(this.sendEvent));
+	}
+	run(a, ...args) {
+		return this.pushNode({
+			id: "",
+			type: "action",
+			action: a.name,
+			args: args[0] ?? {},
+			codeHash: a.codeHash
+		}, captureLoc(this.run));
+	}
+};
+/**
+* A reusable flow fragment: a free function. Once personalization goes through
+* u.xxx and events through e.xxx, the flow layer carries no schema generics.
+*/
+function flow(build) {
+	const builder = new FlowBuilderImpl();
+	build(builder);
+	return {
+		__flow: true,
+		nodes: builder.nodes
+	};
+}
+//#endregion
+export { FlowBuilderImpl, flow };
+
+//# sourceMappingURL=flow.mjs.map

package/dist/dsl/flow.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.mjs","names":[],"sources":["../../src/dsl/flow.ts"],"sourcesContent":["import type { ChannelIR, ConditionIR, NodeIR, PropValueIR, SourceLocIR } from '../ir';\nimport { captureLoc } from '../provenance';\nimport type { ActionRef } from './action';\nimport { type Duration, type TimeOfDay, type Weekday, durationIR, timeOfDayMinutes } from './base';\nimport { type Condition, condIR } from './condition';\nimport type { EventRef, MessageArgs, PropInput } from './refs';\nimport type { Channel, TemplateRef } from './template';\n\n/**\n * The flow chain — FlowBuilder is the DSL's step surface (messages, delays,\n * flow control, data), and its implementation is the compiler front half: each\n * chained call executes no logic, it just collects one IR node (ids are\n * assigned later, in workflow.toIR()). Sub-flow callbacks run exactly once at\n * construction — builder in, builder out — so the output is always a static\n * tree.\n *\n * Every public method also captures its callsite (provenance): the loc lands\n * in the node's hash-excluded meta and is the anchor for future in-place\n * editing from the studio.\n */\n\ntype Scalar = string | number | boolean;\n\n/** An emitted field: a scalar (or a profile ref to one); a nested field cannot be sent. */\ntype EmitValue<T> = [NonNullable<T>] extends [Scalar] ? PropInput<T> : never;\n\n/** The payload `sendEvent` accepts for an event: its fields, scalar ones only. */\nexport type EmitPayload<P> = { [K in keyof P]: EmitValue<P[K]> };\n\n/** Payload may be omitted when the event declares no required field. */\nexport type EmitArgs<P> =\n  Record<never, never> extends P ? [payload?: EmitPayload<P>] : [payload: EmitPayload<P>];\n\n/** Per-node push options. */\nexport interface PushOptions {\n  /** Which devices get a copy: 'all' (the default) or only the most recently registered. */\n  devices?: 'all' | 'latest';\n}\n\n/** A reusable flow fragment (what `flow(...)` returns), referenced directly by branch arms. */\nexport interface Flow {\n  readonly __flow: true;\n}\n\ninterface FlowInternal extends Flow {\n  readonly nodes: NodeIR[];\n}\n\n/** Sub-flow: a named fragment, or an inline callback (runs once at construction — builder in, builder out). */\nexport type SubFlow = Flow | ((w: FlowBuilder) => FlowBuilder);\n\n/** A branch arm: the [condition, sub-flow] tuple — an [if, then] ordering convention. */\nexport type BranchCase = readonly [condition: Condition, flow: SubFlow];\n\n/**\n * A branch argument: either a tuple arm, or a bare sub-flow meaning the default\n * arm. The bare form may appear once, and must come last (checked at runtime).\n */\nexport type BranchArm = BranchCase | SubFlow;\n\n/**\n * A cohort arm name has two jobs, and both constrain its spelling:\n * - it is interpolated into the node ids of the arm's flow ('{id}.{name}.{j}'),\n *   and an id is a durable step name — a dot would fake a nesting level and can\n *   collide with a real one, an empty name gives '{id}..{j}';\n * - it is an object key, and JavaScript lists integer-like keys first in\n *   ascending numeric order however the author wrote them. The arms array is\n *   documented (and interpreted) as authoring order, and the bucketing walk\n *   accumulates weights along it, so an arm named '0' added to a live\n *   experiment would prepend itself and re-bucket everyone already in it.\n */\nconst ARM_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;\n\nfunction resolveSubFlow(sub: SubFlow): NodeIR[] {\n  if (typeof sub === 'function') {\n    const builder = new FlowBuilderImpl();\n    const returned: unknown = sub(builder);\n    // An async callback would add its nodes after construction is over — after ids were assigned\n    if (typeof (returned as { then?: unknown } | undefined)?.then === 'function') {\n      throw new TypeError(\n        'sub-flow callbacks must be synchronous: they run once, while the workflow is defined'\n      );\n    }\n    return builder.nodes;\n  }\n  /*\n   * A named fragment is a value, and the convention is to reuse it — two branch\n   * arms may hold the same one. Handing out its own nodes aliases them into\n   * both places, and assignIds writes ids *in place*: the second prefix\n   * overwrites the first, so the two placements end up as one object under one\n   * id — one durable step name, one message idempotency key, one bucket seed.\n   * A copy per placement is what makes a fragment behave like a value.\n   */\n  return structuredClone((sub as FlowInternal).nodes);\n}\n\nexport interface FlowBuilder {\n  /* ---- Messages: every channel is one message node; separate methods buy channel-level typing ---- */\n  email<P extends object>(template: TemplateRef<'email', P>, ...props: MessageArgs<P>): this;\n  sms<P extends object>(template: TemplateRef<'sms', P>, ...props: MessageArgs<P>): this;\n  /**\n   * Push to the user's devices — every device the host's directory lists, or\n   * only the most recently registered with `{ devices: 'latest' }`. A user with\n   * no device is skipped (branch on `reachable('push')` to fall back to email).\n   */\n  push<P extends object>(\n    template: TemplateRef<'push', P>,\n    ...args: [...props: MessageArgs<P>, options?: PushOptions]\n  ): this;\n  inApp<P extends object>(template: TemplateRef<'in_app', P>, ...props: MessageArgs<P>): this;\n  slack<P extends object>(template: TemplateRef<'slack', P>, ...props: MessageArgs<P>): this;\n  discord<P extends object>(template: TemplateRef<'discord', P>, ...props: MessageArgs<P>): this;\n  survey<P extends object>(template: TemplateRef<'survey', P>, ...props: MessageArgs<P>): this;\n\n  /* --------------------------------- Delays --------------------------------- */\n  /** Time Delay; passing { min, max } makes it a Randomized Delay. */\n  delay(duration: Duration): this;\n  delay(range: { min: Duration; max: Duration }): this;\n\n  /** Time Window: hold until inside the window (e.g. weekdays 09:00–17:00). tz: 'user' uses the user's timezone. */\n  timeWindow(opts: {\n    days?: readonly Weekday[];\n    between: readonly [TimeOfDay, TimeOfDay];\n    tz?: 'user' | (string & {});\n  }): this;\n\n  /**\n   * Wait Until: continue on the main line once the condition holds, or take\n   * onTimeout when it expires (default 'continue'). On the engine side this is\n   * \"await event racing a timer\" — a native primitive of durable runtimes.\n   */\n  waitUntil(\n    condition: Condition,\n    opts: { timeout: Duration; onTimeout?: 'continue' | 'exit' | SubFlow }\n  ): this;\n\n  /**\n   * Splice a fragment in place: a named `flow(...)` or a callback, expanded\n   * once while the workflow is defined — a composition step before compiling,\n   * not a node (the IR has no trace of it, and ids are assigned over the whole\n   * workflow as if the steps were written inline). Each use gets its own copy,\n   * so one fragment can be used in several places and workflows.\n   *\n   *   const preferPush = (push, email, props) =>\n   *     flow((w) => w.branch([reachable('push'), (b) => b.push(push, props)], (b) => b.email(email, props)));\n   *   workflow({ id: 'onboarding', ... }).use(preferPush(tipPush, tipEmail, { name: u.name }))\n   */\n  use(fragment: SubFlow): this;\n\n  /* ------------------------------ Flow Control ------------------------------ */\n  /**\n   * Conditional branch: ordered first-match (same semantics as Step Functions\n   * Choice / Knock branch). This one primitive covers both the UI's True/False\n   * Branch (two arms) and Multi-Split Branch (N arms). Arms are\n   * [condition, sub-flow] tuples; a bare sub-flow in tail position is the\n   * default arm. With no match and no default, execution simply continues.\n   * Rejoin is structural: after the matching arm finishes, execution resumes\n   * at the node following the branch — to opt out, call .exit() inside the arm.\n   *\n   *   .branch([activeSubscriber, upgradeFlow], firstTimeFlow)   // True/False\n   *   .branch([vip, vipFlow], [trial, trialFlow], defaultFlow)  // Multi-Split\n   *   .branch([not(usedStaging), eduFlow])                      // single arm: no match continues\n   *\n   * The optional first argument `label` becomes the node's name in IR (UI title\n   * / observability handle). It is not a jump target — there is no goto here;\n   * looping is a future re-entry-policy topic (see sendEvent). Arm labels in\n   * the UI are derived from the condition.\n   */\n  branch(...arms: readonly BranchArm[]): this;\n  branch(label: string, ...arms: readonly BranchArm[]): this;\n\n  /**\n   * Gate: exit unless the condition holds, otherwise continue. A first-class\n   * node rather than sugar over branch — same semantics as Zapier's \"only\n   * continue if\" / Iterable's Filter tile, and rendered on its own in the UI.\n   * `reason` is the audit-log line — metadata, so rewording it is free\n   * (excluded from contentHash, see hash.ts).\n   */\n  filter(condition: Condition, opts?: { reason?: string }): this;\n\n  /**\n   * Random Cohort Branch (A/B): weights must sum to 100 (checked at runtime).\n   * `key` names the experiment: bucketing hashes `userId:key` instead of the\n   * structural node id, so assignments survive node insertion/moves and the\n   * experiment keeps one identity across workflow versions — set it for any\n   * A/B whose results you intend to read.\n   *\n   * Arm names become node id segments and are read back in authoring order, so\n   * they are restricted to letters, digits, '_' and '-', never starting with a\n   * digit (checked at runtime).\n   */\n  cohort(arms: Record<string, { weight: number; flow?: SubFlow }>, opts?: { key?: string }): this;\n\n  /**\n   * Exit: end the whole workflow immediately (the UI's Exit node); `reason`\n   * goes into the audit log and is metadata, so rewording it neither repins\n   * in-flight journeys nor shows up in plan. Inside a branch arm this means\n   * \"terminate, do not rejoin\" — it stops here instead of falling through,\n   * while an arm without exit rejoins naturally.\n   */\n  exit(reason?: string): this;\n\n  /* ---------------------------------- Data ---------------------------------- */\n  /**\n   * Emit a typed event (customer.io's Send Event). The event comes from an\n   * e.xxx reference, so payload types flow in the same way trigger.event works.\n   * This is how workflows compose: an event can trigger another workflow, and\n   * the resulting call graph is statically analyzable. Payload values may\n   * reference u.xxx. Only scalar fields can be sent (IR carries literals and\n   * profile refs, not nested JSON): an event whose payload requires a nested\n   * field cannot be emitted from a journey, and the types say so.\n   *\n   * Note on loops: a trailing self-triggering sendEvent will become the\n   * official periodic-flow shape *once a re-entry policy exists* — today the\n   * entry policy is once-per-user, so a self-trigger cannot re-enter and does\n   * not loop.\n   * TODO: the rest of the Data category — outbound webhook / profile update /\n   * journey attributes.\n   */\n  sendEvent<P extends object>(event: EventRef<P>, ...payload: EmitArgs<P>): this;\n\n  /**\n   * Run a custom action (see dsl/action.ts for the model). The chain records\n   * identity only — name, args, codeHash — never the code: the implementation\n   * ships inside the deployed Worker bundle and is resolved by name from the\n   * runtime registry. Args are typed by the ActionRef and may reference u.xxx,\n   * resolved at run time exactly like message props. Executed inside a durable\n   * step: retried on throw, checkpointed on success.\n   */\n  run<A extends object>(action: ActionRef<A>, ...args: MessageArgs<A>): this;\n}\n\n/* oxlint-disable typescript/unbound-method --\n * `captureLoc(this.xxx)` passes the method by identity as the stack-trace\n * boundary for Error.captureStackTrace; it is never invoked, so `this`\n * scoping cannot go wrong. */\n/** @internal extended by WorkflowBuilderImpl; not part of the public API */\nexport class FlowBuilderImpl implements FlowBuilder {\n  /** Nodes as collected; ids are assigned in one pass inside toIR, so '' is a placeholder here. */\n  readonly nodes: NodeIR[] = [];\n\n  /** Provenance: the callsite (captured in the public method) lands in meta.loc, outside the hash. */\n  private pushNode(node: NodeIR, loc: SourceLocIR | undefined): this {\n    this.nodes.push({ ...node, ...(loc !== undefined ? { meta: { loc } } : {}) });\n    return this;\n  }\n\n  private message(\n    channel: ChannelIR,\n    tpl: TemplateRef<Channel, object>,\n    props: object | undefined,\n    loc: SourceLocIR | undefined,\n    devices?: 'latest'\n  ): this {\n    return this.pushNode(\n      {\n        id: '',\n        type: 'message',\n        channel,\n        template: tpl.key,\n        props: (props ?? {}) as Record<string, PropValueIR>,\n        // Absent for 'all', so adding the option left every existing push's hash as it was\n        ...(devices !== undefined ? { devices } : {}),\n      },\n      loc\n    );\n  }\n\n  email<P extends object>(t: TemplateRef<'email', P>, ...args: MessageArgs<P>): this {\n    return this.message('email', t, args[0], captureLoc(this.email));\n  }\n  sms<P extends object>(t: TemplateRef<'sms', P>, ...args: MessageArgs<P>): this {\n    return this.message('sms', t, args[0], captureLoc(this.sms));\n  }\n  push<P extends object>(\n    t: TemplateRef<'push', P>,\n    ...args: [...props: MessageArgs<P>, options?: PushOptions]\n  ): this {\n    const [props, options] = args as unknown as [object | undefined, PushOptions | undefined];\n    const devices = options?.devices === 'latest' ? 'latest' : undefined;\n    return this.message('push', t, props, captureLoc(this.push), devices);\n  }\n  inApp<P extends object>(t: TemplateRef<'in_app', P>, ...args: MessageArgs<P>): this {\n    return this.message('in_app', t, args[0], captureLoc(this.inApp));\n  }\n  slack<P extends object>(t: TemplateRef<'slack', P>, ...args: MessageArgs<P>): this {\n    return this.message('slack', t, args[0], captureLoc(this.slack));\n  }\n  discord<P extends object>(t: TemplateRef<'discord', P>, ...args: MessageArgs<P>): this {\n    return this.message('discord', t, args[0], captureLoc(this.discord));\n  }\n  survey<P extends object>(t: TemplateRef<'survey', P>, ...args: MessageArgs<P>): this {\n    return this.message('survey', t, args[0], captureLoc(this.survey));\n  }\n\n  delay(duration: Duration): this;\n  delay(range: { min: Duration; max: Duration }): this;\n  delay(d: Duration | { min: Duration; max: Duration }): this {\n    const loc = captureLoc(this.delay);\n    if (typeof d === 'string') {\n      return this.pushNode({ id: '', type: 'delay', duration: durationIR(d) }, loc);\n    }\n    const min = durationIR(d.min);\n    const max = durationIR(d.max);\n    /*\n     * The interpreter draws `min + random(max - min)` with the span clamped at\n     * zero, so a backwards range does not fail — it quietly collapses into a\n     * fixed `min` sleep. Reject it here, where the author can still see it.\n     */\n    if (max.ms < min.ms) {\n      throw new Error(\n        `delay(): 'max' must not be shorter than 'min', got { min: '${d.min}', max: '${d.max}' }`\n      );\n    }\n    return this.pushNode({ id: '', type: 'random_delay', min, max }, loc);\n  }\n\n  timeWindow(opts: {\n    days?: readonly Weekday[];\n    between: readonly [TimeOfDay, TimeOfDay];\n    tz?: 'user' | (string & {});\n  }): this {\n    const loc = captureLoc(this.timeWindow);\n    const start = timeOfDayMinutes(opts.between[0]);\n    const end = timeOfDayMinutes(opts.between[1]);\n    if (end <= start) {\n      throw new Error(\n        `timeWindow(): 'between' must open before it closes within one day, got [${opts.between[0]}, ${opts.between[1]}] (overnight windows are not supported yet)`\n      );\n    }\n    return this.pushNode(\n      {\n        id: '',\n        type: 'time_window',\n        days: [...(opts.days ?? (['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'] as const))],\n        between: [opts.between[0], opts.between[1]],\n        tz: opts.tz ?? 'user',\n      },\n      loc\n    );\n  }\n\n  waitUntil(\n    condition: Condition,\n    opts: { timeout: Duration; onTimeout?: 'continue' | 'exit' | SubFlow }\n  ): this {\n    const loc = captureLoc(this.waitUntil);\n    const onTimeout = opts.onTimeout ?? 'continue';\n    return this.pushNode(\n      {\n        id: '',\n        type: 'wait_until',\n        condition: condIR(condition),\n        timeout: durationIR(opts.timeout),\n        onTimeout:\n          onTimeout === 'continue' || onTimeout === 'exit' ? onTimeout : resolveSubFlow(onTimeout),\n      },\n      loc\n    );\n  }\n\n  use(fragment: SubFlow): this {\n    // The fragment's nodes carry their own provenance (where the fragment was written)\n    this.nodes.push(...resolveSubFlow(fragment));\n    return this;\n  }\n\n  branch(...arms: readonly BranchArm[]): this;\n  branch(label: string, ...arms: readonly BranchArm[]): this;\n  branch(...args: readonly (string | BranchArm)[]): this {\n    const loc = captureLoc(this.branch);\n    const label = typeof args[0] === 'string' ? args[0] : undefined;\n    const arms = (label === undefined ? args : args.slice(1)) as readonly BranchArm[];\n\n    const cases: { condition: ConditionIR; flow: NodeIR[] }[] = [];\n    let otherwise: NodeIR[] | undefined;\n    arms.forEach((arm, i) => {\n      if (Array.isArray(arm)) {\n        if (otherwise !== undefined) {\n          throw new Error('branch(): default arm (bare sub-flow) must be the last argument');\n        }\n        const [condition, sub] = arm as BranchCase;\n        cases.push({ condition: condIR(condition), flow: resolveSubFlow(sub) });\n      } else {\n        if (otherwise !== undefined) {\n          throw new Error('branch(): only one default arm (bare sub-flow) is allowed');\n        }\n        if (i !== arms.length - 1) {\n          throw new Error('branch(): default arm (bare sub-flow) must be the last argument');\n        }\n        otherwise = resolveSubFlow(arm as SubFlow);\n      }\n    });\n\n    return this.pushNode(\n      {\n        id: '',\n        type: 'branch',\n        ...(label !== undefined ? { label } : {}),\n        cases,\n        ...(otherwise !== undefined ? { otherwise } : {}),\n      },\n      loc\n    );\n  }\n\n  filter(condition: Condition, opts?: { reason?: string }): this {\n    return this.pushNode(\n      {\n        id: '',\n        type: 'filter',\n        condition: condIR(condition),\n        ...(opts?.reason !== undefined ? { reason: opts.reason } : {}),\n      },\n      captureLoc(this.filter)\n    );\n  }\n\n  cohort(arms: Record<string, { weight: number; flow?: SubFlow }>, opts?: { key?: string }): this {\n    const loc = captureLoc(this.cohort);\n    const entries = Object.entries(arms);\n    /*\n     * Weights live on a 0.01% grid: the runtime buckets into 10,000 slots\n     * (basis points), so anything finer would be silently quantized — reject\n     * it here instead. Converting to integer basis points also makes the\n     * sum check exact; no epsilon needed.\n     */\n    const basisPoints = entries.map(([name, a]) => {\n      if (!ARM_NAME.test(name)) {\n        throw new Error(\n          `cohort(): arm name '${name}' must start with a letter or '_' and contain only letters, digits, '_' or '-' — arm names become node id segments, and integer-like names would silently reorder the arms`\n        );\n      }\n      const bp = a.weight * 100;\n      if (Math.abs(bp - Math.round(bp)) > 1e-6) {\n        throw new Error(\n          `cohort(): arm '${name}' weight ${a.weight} is finer than the 0.01% bucketing grid — use at most two decimal places`\n        );\n      }\n      /*\n       * The sum check alone accepts -50 / 150: the runtime walks the arms\n       * accumulating basis points and takes the first whose cumulative total\n       * clears the bucket, so a negative weight hands 100% of users to its\n       * neighbour instead of splitting anything.\n       */\n      if (bp < 0) {\n        throw new Error(`cohort(): arm '${name}' weight ${a.weight} must not be negative`);\n      }\n      return Math.round(bp);\n    });\n    const total = basisPoints.reduce((sum, bp) => sum + bp, 0);\n    if (total !== 10_000) {\n      throw new Error(`cohort(): weights must sum to 100, got ${total / 100}`);\n    }\n    return this.pushNode(\n      {\n        id: '',\n        type: 'cohort',\n        ...(opts?.key !== undefined ? { key: opts.key } : {}),\n        arms: entries.map(([name, a]) => ({\n          name,\n          weight: a.weight,\n          flow: a.flow ? resolveSubFlow(a.flow) : [],\n        })),\n      },\n      loc\n    );\n  }\n\n  exit(reason?: string): this {\n    return this.pushNode(\n      { id: '', type: 'exit', ...(reason !== undefined ? { reason } : {}) },\n      captureLoc(this.exit)\n    );\n  }\n\n  sendEvent<P extends object>(ev: EventRef<P>, ...payload: EmitArgs<P>): this {\n    const values = (payload[0] ?? {}) as Record<string, unknown>;\n    for (const [field, value] of Object.entries(values)) {\n      const ref =\n        typeof value === 'object' &&\n        value !== null &&\n        (value as { type?: unknown }).type === 'user_property';\n      if (!ref && !['string', 'number', 'boolean'].includes(typeof value)) {\n        throw new TypeError(\n          `sendEvent('${ev.name}'): '${field}' is not a scalar or a u.xxx reference — an emitted payload carries scalar fields only`\n        );\n      }\n    }\n    return this.pushNode(\n      {\n        id: '',\n        type: 'send_event',\n        event: ev.name,\n        payload: values as Record<string, PropValueIR>,\n      },\n      captureLoc(this.sendEvent)\n    );\n  }\n\n  run<A extends object>(a: ActionRef<A>, ...args: MessageArgs<A>): this {\n    return this.pushNode(\n      {\n        id: '',\n        type: 'action',\n        action: a.name,\n        args: (args[0] ?? {}) as Record<string, PropValueIR>,\n        codeHash: a.codeHash,\n      },\n      captureLoc(this.run)\n    );\n  }\n}\n/* oxlint-enable typescript/unbound-method */\n\n/**\n * A reusable flow fragment: a free function. Once personalization goes through\n * u.xxx and events through e.xxx, the flow layer carries no schema generics.\n */\nexport function flow(build: (w: FlowBuilder) => FlowBuilder): Flow {\n  const builder = new FlowBuilderImpl();\n  build(builder);\n  const impl: FlowInternal = { __flow: true, nodes: builder.nodes };\n  return impl;\n}\n"],"mappings":"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"}

package/dist/dsl/index.cjs

@@ -0,0 +1,38 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_dsl_action = require("./action.cjs");
+const require_dsl_refs = require("./refs.cjs");
+const require_dsl_template = require("./template.cjs");
+const require_dsl_condition = require("./condition.cjs");
+const require_dsl_flow = require("./flow.cjs");
+const require_dsl_trigger = require("./trigger.cjs");
+const require_dsl_workflow = require("./workflow.cjs");
+const require_dsl_bundle = require("./bundle.cjs");
+exports.action = require_dsl_action.action;
+exports.and = require_dsl_condition.and;
+exports.between = require_dsl_condition.between;
+exports.compileBundle = require_dsl_bundle.compileBundle;
+exports.contains = require_dsl_condition.contains;
+exports.eq = require_dsl_condition.eq;
+exports.event = require_dsl_refs.event;
+exports.exists = require_dsl_condition.exists;
+exports.flow = require_dsl_flow.flow;
+exports.gt = require_dsl_condition.gt;
+exports.gte = require_dsl_condition.gte;
+exports.inArray = require_dsl_condition.inArray;
+exports.lt = require_dsl_condition.lt;
+exports.lte = require_dsl_condition.lte;
+exports.ne = require_dsl_condition.ne;
+exports.not = require_dsl_condition.not;
+exports.notBetween = require_dsl_condition.notBetween;
+exports.notContains = require_dsl_condition.notContains;
+exports.notExists = require_dsl_condition.notExists;
+exports.notInArray = require_dsl_condition.notInArray;
+exports.or = require_dsl_condition.or;
+exports.performed = require_dsl_condition.performed;
+exports.reachable = require_dsl_condition.reachable;
+exports.segment = require_dsl_condition.segment;
+exports.template = require_dsl_template.template;
+exports.templates = require_dsl_template.templates;
+exports.trigger = require_dsl_trigger.trigger;
+exports.user = require_dsl_refs.user;
+exports.workflow = require_dsl_workflow.workflow;

package/dist/dsl/index.d.cts

@@ -0,0 +1,10 @@
+import { ActionContext, ActionHandler, ActionRef, action } from "./action.cjs";
+import { Duration, EventMap, TimeOfDay, UserPropertyBase, Weekday } from "./base.cjs";
+import { EventRef, EventRefs, MessageArgs, PayloadRef, PayloadRefNode, PayloadRefs, PropInput, PropsInput, UserPropertyRef, UserRefs, event, user } from "./refs.cjs";
+import { Channel, EmptyProps, PropsOf, TemplateFactory, TemplateRef, TemplateRefTable, TemplateRefs, TemplateRegistry, template, templates } from "./template.cjs";
+import { Condition, PayloadWhere, PerformedOptions, SegmentDefinition, SegmentRef, and, between, contains, eq, exists, gt, gte, inArray, lt, lte, ne, not, notBetween, notContains, notExists, notInArray, or, performed, reachable, segment } from "./condition.cjs";
+import { BranchArm, BranchCase, EmitArgs, EmitPayload, Flow, FlowBuilder, PushOptions, SubFlow, flow } from "./flow.cjs";
+import { DateTime, EventTriggerOptions, TriggerFactory, TriggerRef, trigger } from "./trigger.cjs";
+import { GoalOptions, WorkflowBuilder, WorkflowDefinition, workflow } from "./workflow.cjs";
+import { compileBundle } from "./bundle.cjs";
+export { type ActionContext, type ActionHandler, type ActionRef, type BranchArm, type BranchCase, type Channel, type Condition, type DateTime, type Duration, type EmitArgs, type EmitPayload, type EmptyProps, type EventMap, type EventRef, type EventRefs, type EventTriggerOptions, type Flow, type FlowBuilder, type GoalOptions, type MessageArgs, type PayloadRef, type PayloadRefNode, type PayloadRefs, type PayloadWhere, type PerformedOptions, type PropInput, type PropsInput, type PropsOf, type PushOptions, type SegmentDefinition, type SegmentRef, type SubFlow, type TemplateFactory, type TemplateRef, type TemplateRefTable, type TemplateRefs, type TemplateRegistry, type TimeOfDay, type TriggerFactory, type TriggerRef, type UserPropertyBase, type UserPropertyRef, type UserRefs, type Weekday, type WorkflowBuilder, type WorkflowDefinition, action, and, between, compileBundle, contains, eq, event, exists, flow, gt, gte, inArray, lt, lte, ne, not, notBetween, notContains, notExists, notInArray, or, performed, reachable, segment, template, templates, trigger, user, workflow };

package/dist/dsl/index.d.mts

@@ -0,0 +1,10 @@
+import { ActionContext, ActionHandler, ActionRef, action } from "./action.mjs";
+import { Duration, EventMap, TimeOfDay, UserPropertyBase, Weekday } from "./base.mjs";
+import { EventRef, EventRefs, MessageArgs, PayloadRef, PayloadRefNode, PayloadRefs, PropInput, PropsInput, UserPropertyRef, UserRefs, event, user } from "./refs.mjs";
+import { Channel, EmptyProps, PropsOf, TemplateFactory, TemplateRef, TemplateRefTable, TemplateRefs, TemplateRegistry, template, templates } from "./template.mjs";
+import { Condition, PayloadWhere, PerformedOptions, SegmentDefinition, SegmentRef, and, between, contains, eq, exists, gt, gte, inArray, lt, lte, ne, not, notBetween, notContains, notExists, notInArray, or, performed, reachable, segment } from "./condition.mjs";
+import { BranchArm, BranchCase, EmitArgs, EmitPayload, Flow, FlowBuilder, PushOptions, SubFlow, flow } from "./flow.mjs";
+import { DateTime, EventTriggerOptions, TriggerFactory, TriggerRef, trigger } from "./trigger.mjs";
+import { GoalOptions, WorkflowBuilder, WorkflowDefinition, workflow } from "./workflow.mjs";
+import { compileBundle } from "./bundle.mjs";
+export { type ActionContext, type ActionHandler, type ActionRef, type BranchArm, type BranchCase, type Channel, type Condition, type DateTime, type Duration, type EmitArgs, type EmitPayload, type EmptyProps, type EventMap, type EventRef, type EventRefs, type EventTriggerOptions, type Flow, type FlowBuilder, type GoalOptions, type MessageArgs, type PayloadRef, type PayloadRefNode, type PayloadRefs, type PayloadWhere, type PerformedOptions, type PropInput, type PropsInput, type PropsOf, type PushOptions, type SegmentDefinition, type SegmentRef, type SubFlow, type TemplateFactory, type TemplateRef, type TemplateRefTable, type TemplateRefs, type TemplateRegistry, type TimeOfDay, type TriggerFactory, type TriggerRef, type UserPropertyBase, type UserPropertyRef, type UserRefs, type Weekday, type WorkflowBuilder, type WorkflowDefinition, action, and, between, compileBundle, contains, eq, event, exists, flow, gt, gte, inArray, lt, lte, ne, not, notBetween, notContains, notExists, notInArray, or, performed, reachable, segment, template, templates, trigger, user, workflow };

package/dist/dsl/index.mjs

@@ -0,0 +1,9 @@
+import { action } from "./action.mjs";
+import { event, user } from "./refs.mjs";
+import { template, templates } from "./template.mjs";
+import { and, between, contains, eq, exists, gt, gte, inArray, lt, lte, ne, not, notBetween, notContains, notExists, notInArray, or, performed, reachable, segment } from "./condition.mjs";
+import { flow } from "./flow.mjs";
+import { trigger } from "./trigger.mjs";
+import { workflow } from "./workflow.mjs";
+import { compileBundle } from "./bundle.mjs";
+export { action, and, between, compileBundle, contains, eq, event, exists, flow, gt, gte, inArray, lt, lte, ne, not, notBetween, notContains, notExists, notInArray, or, performed, reachable, segment, template, templates, trigger, user, workflow };

package/dist/dsl/refs.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/dsl/refs.ts
+/**
+* Build the reference tables: the app calls each once in its schema module and
+* exports the result (implemented with a Proxy — property access *is* the reference).
+*
+*   export const u = user<UserProperty>();
+*   export const e = event<Event>();
+*
+* From then on predicates and personalization are all property access:
+* eq(u.subscription_status, 'active'), performed(e.purchase, { within: '30 days' }),
+* { plan: u.subscription_plan }.
+*
+* Properties are deliberately single-level: the data source is a database
+* table and is naturally flat, so nested paths are out of scope.
+*/
+function user() {
+	return new Proxy({}, { get: (_target, prop) => ({
+		type: "user_property",
+		path: String(prop)
+	}) });
+}
+function event() {
+	return new Proxy({}, { get: (_target, prop) => ({
+		type: "event_ref",
+		name: String(prop)
+	}) });
+}
+/**
+* Where a payload ref keeps its own state. A payload ref doubles as the table
+* of its sub-fields, so every *string* key it answered for itself shadowed an
+* author's field of that name: with a payload field called `path`,
+* `performed(e.page_view, (p) => eq(p.path, '/pricing'))` type-checked, handed
+* `prop()` the ref's own prefix instead of a sub-ref, and compiled to a
+* *profile* predicate on a property named 'path' — a mistake that only
+* surfaced later, as a zod error nowhere near the line that caused it. A symbol
+* key cannot be reached by `p.<field>`, so no field name can collide with it.
+*/
+const PAYLOAD_PATH = Symbol("workflow.payloadPath");
+/**
+* Nested Proxy: every string key extends the dotted path, so an author's field
+* may be named anything — including `path` or `type`. The ref's own path reads
+* off PAYLOAD_PATH, the one key a field name cannot spell.
+* @internal used by performed() and trigger.event() to hand `p` to a where callback
+*/
+function payloadRefs(prefix = "") {
+	return new Proxy({}, { get: (_target, prop) => {
+		if (prop === PAYLOAD_PATH) return prefix;
+		if (typeof prop === "symbol") return void 0;
+		return payloadRefs(prefix === "" ? prop : `${prefix}.${prop}`);
+	} });
+}
+//#endregion
+exports.PAYLOAD_PATH = PAYLOAD_PATH;
+exports.event = event;
+exports.payloadRefs = payloadRefs;
+exports.user = user;
+
+//# sourceMappingURL=refs.cjs.map