@celom/prose 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,634 @@
+class k extends Error {
+  constructor(e, t, r, o) {
+    super(e), this.flowName = t, this.stepName = r, this.timeoutMs = o, this.name = "TimeoutError";
+  }
+}
+class b extends Error {
+  issues;
+  constructor(e, t) {
+    super(e), this.name = "ValidationError", typeof t == "string" ? this.issues = [{ field: t, message: e }] : Array.isArray(t) ? this.issues = t : this.issues = [{ field: "unknown", message: e }];
+  }
+  /**
+   * Create a validation error for a single field
+   */
+  static single(e, t, r) {
+    return new b(t, [{ field: e, message: t, value: r }]);
+  }
+  /**
+   * Create a validation error for multiple fields
+   */
+  static multiple(e) {
+    const t = `Validation failed: ${e.map((r) => r.field).join(", ")}`;
+    return new b(t, e);
+  }
+  /**
+   * Convert to JSON for serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      issues: this.issues
+    };
+  }
+  /**
+   * Get a single field error (for backward compatibility)
+   */
+  get field() {
+    return this.issues[0]?.field;
+  }
+}
+class d extends Error {
+  constructor(e, t, r, o) {
+    super(e), this.flowName = t, this.stepName = r, this.originalError = o, this.name = "FlowExecutionError";
+  }
+}
+function $(u) {
+  if (u.aborted)
+    throw u.reason instanceof Error ? u.reason : new Error("Flow execution was aborted");
+}
+function F(u, e) {
+  return e.aborted ? Promise.reject(
+    e.reason instanceof Error ? e.reason : new Error("Aborted")
+  ) : new Promise((t, r) => {
+    function o() {
+      r(e.reason instanceof Error ? e.reason : new Error("Aborted"));
+    }
+    e.addEventListener("abort", o, { once: !0 }), u.then(
+      (n) => {
+        e.removeEventListener("abort", o), t(n);
+      },
+      (n) => {
+        e.removeEventListener("abort", o), r(n);
+      }
+    );
+  });
+}
+function N(u, e) {
+  return new Promise((t, r) => {
+    if (e.aborted) {
+      r(e.reason instanceof Error ? e.reason : new Error("Aborted"));
+      return;
+    }
+    const o = setTimeout(() => {
+      e.removeEventListener("abort", n), t();
+    }, u);
+    function n() {
+      clearTimeout(o), r(e.reason instanceof Error ? e.reason : new Error("Aborted"));
+    }
+    e.addEventListener("abort", n, { once: !0 });
+  });
+}
+class T {
+  /**
+   * Execute a complete flow from configuration
+   * @returns FlowExecutionResult containing the result value and whether flow was short-circuited
+   */
+  async execute(e, t, r, o) {
+    const n = Date.now(), i = {
+      flowName: e.name,
+      startedAt: new Date(n),
+      correlationId: o?.correlationId
+    }, s = o?.observer, a = new AbortController(), h = o?.signal ? AbortSignal.any([o.signal, a.signal]) : a.signal;
+    let p;
+    o?.timeout && (p = setTimeout(
+      () => a.abort(
+        new k(
+          `Flow execution timeout after ${o.timeout}ms`,
+          e.name,
+          void 0,
+          o.timeout
+        )
+      ),
+      o.timeout
+    ));
+    let l = {
+      input: Object.freeze(t),
+      state: {},
+      deps: r,
+      meta: i,
+      signal: h
+    };
+    s?.onFlowStart?.(e.name, t);
+    try {
+      for (const c of e.steps) {
+        if ($(h), l.meta.currentStep = c.name, c.condition && !c.condition(l)) {
+          s?.onStepSkipped?.(c.name, l);
+          continue;
+        }
+        if (c.type === "break") {
+          const g = c, E = Date.now();
+          if (s?.onStepStart?.(c.name, l), g.breakCondition(l)) {
+            const y = g.breakReturnValue ? g.breakReturnValue(l) : l.state, M = Date.now() - E, x = Date.now() - n;
+            return s?.onStepComplete?.(c.name, y, M, l), s?.onFlowBreak?.(
+              e.name,
+              c.name,
+              y,
+              x
+            ), { value: y, didBreak: !0 };
+          }
+          const A = Date.now() - E;
+          s?.onStepComplete?.(
+            c.name,
+            { __breakConditionMet: !1 },
+            A,
+            l
+          );
+          continue;
+        }
+        const w = await this.executeStep(c, l, r, o, h);
+        w && typeof w == "object" && c.type !== "event" && (l = {
+          ...l,
+          state: { ...l.state, ...w }
+        });
+      }
+      const m = Date.now() - n;
+      return s?.onFlowComplete?.(e.name, l.state, m), { value: l.state, didBreak: !1 };
+    } catch (m) {
+      const c = Date.now() - n;
+      if (s?.onFlowError?.(e.name, m, c), o?.throwOnError === !1)
+        return { value: l.state, didBreak: !1 };
+      throw m;
+    } finally {
+      p !== void 0 && clearTimeout(p), a.abort();
+    }
+  }
+  /**
+   * Execute a single step with retry logic
+   */
+  async executeStep(e, t, r, o, n) {
+    const i = e.retryOptions;
+    return i ? this.executeWithRetry(e, t, r, i, o, n) : this.executeSingleStep(e, t, r, o, n);
+  }
+  /**
+   * Execute a step with retry logic
+   */
+  async executeWithRetry(e, t, r, o, n, i) {
+    const s = n?.observer;
+    let a, h = o.delayMs;
+    for (let p = 1; p <= o.maxAttempts; p++) {
+      $(i);
+      try {
+        return await this.executeSingleStep(e, t, r, n, i);
+      } catch (l) {
+        if (a = l instanceof Error ? l : new Error(String(l)), o.shouldRetry && !o.shouldRetry(a) || a instanceof b || p === o.maxAttempts)
+          throw a;
+        s?.onStepRetry?.(
+          e.name,
+          p,
+          o.maxAttempts,
+          a
+        ), await N(h, i), o.backoffMultiplier && (h = Math.min(
+          h * o.backoffMultiplier,
+          o.maxDelayMs || Number.MAX_SAFE_INTEGER
+        ));
+      }
+    }
+    throw a;
+  }
+  /**
+   * Execute a single step without retry
+   */
+  async executeSingleStep(e, t, r, o, n) {
+    const i = o?.observer, s = Date.now(), a = e.retryOptions?.stepTimeout ?? o?.stepTimeout;
+    i?.onStepStart?.(e.name, t);
+    let h, p, l = t;
+    if (a) {
+      h = new AbortController();
+      const m = AbortSignal.any([n, h.signal]);
+      l = { ...t, signal: m }, p = setTimeout(
+        () => h.abort(
+          new k(
+            `Step '${e.name}' timed out after ${a}ms`,
+            t.meta.flowName,
+            e.name,
+            a
+          )
+        ),
+        a
+      );
+    }
+    try {
+      const c = await F((async () => {
+        switch (e.type) {
+          case "validate": {
+            await e.handler(l);
+            return;
+          }
+          case "step":
+            return await e.handler(l);
+          case "transaction":
+            return await this.executeTransaction(e, l, r, o);
+          case "event":
+            return await this.executeEvent(e, l, o);
+          default:
+            throw new d(
+              "Unknown step type",
+              t.meta.flowName
+            );
+        }
+      })(), l.signal), w = Date.now() - s;
+      return i?.onStepComplete?.(e.name, c, w, t), c;
+    } catch (m) {
+      const c = Date.now() - s;
+      throw i?.onStepError?.(e.name, m, c, t), m;
+    } finally {
+      p !== void 0 && clearTimeout(p);
+    }
+  }
+  /**
+   * Execute a transaction step
+   */
+  async executeTransaction(e, t, r, o) {
+    const n = r.db;
+    if (!n) {
+      const i = o?.errorHandling?.throwOnMissingDatabase ?? !0, s = "No database found in dependencies for transaction";
+      if (i)
+        throw new d(s, t.meta.flowName, e.name);
+      console.warn(`[Workflow:${t.meta.flowName}] ${s}`);
+      return;
+    }
+    return await n.transaction(async (i) => await e.handler(t, i));
+  }
+  /**
+   * Execute an event publishing step
+   */
+  async executeEvent(e, t, r) {
+    const o = t.deps.eventPublisher;
+    if (!o) {
+      const s = r?.errorHandling?.throwOnMissingEventPublisher ?? !0, a = "No event publisher found in dependencies";
+      if (s)
+        throw new d(a, t.meta.flowName, e.name);
+      console.warn(`[Workflow:${t.meta.flowName}] ${a}`);
+      return;
+    }
+    if (typeof o.publish != "function")
+      throw new d(
+        "Event publisher must have publish() method",
+        t.meta.flowName,
+        e.name
+      );
+    const n = await e.handler(t);
+    if (!n)
+      return;
+    const i = Array.isArray(n) ? n : [n];
+    for (const s of i)
+      s && s.eventType && await this.publishEvent(o, s, e.channel, t);
+  }
+  /**
+   * Publish a single event to a specific channel
+   */
+  async publishEvent(e, t, r, o) {
+    const n = {
+      ...t,
+      correlationId: o.meta.correlationId
+    };
+    await e.publish(r, n);
+  }
+}
+function S(u) {
+  if (u === null || typeof u != "object") return !1;
+  const e = Object.getPrototypeOf(u);
+  return e === Object.prototype || e === null;
+}
+function v(...u) {
+  const e = {};
+  for (const t of u)
+    if (S(t))
+      for (const r in t) {
+        if (!Object.prototype.hasOwnProperty.call(t, r)) continue;
+        const o = e[r], n = t[r];
+        Array.isArray(n) ? Array.isArray(o) ? e[r] = [...o, ...n] : e[r] = [...n] : S(n) ? S(o) ? e[r] = v(o, n) : e[r] = v({}, n) : e[r] = n;
+      }
+  return e;
+}
+function D(u) {
+  return new f(u);
+}
+class f {
+  // Requires "any" for proper output inference
+  constructor(e, t = null, r = 0, o) {
+    this.name = e, this.steps = t, this.length = r, o && (this.outputMapper = o);
+  }
+  steps;
+  length;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputMapper;
+  // Convert linked list of steps to an array for easier processing
+  toArray() {
+    const e = new Array(this.length);
+    let t = this.steps;
+    for (let r = this.length - 1; r >= 0; r--)
+      e[r] = t.head, t = t.tail;
+    return e;
+  }
+  /**
+   * Add a validation step
+   */
+  validate(e, t) {
+    return new f(
+      this.name,
+      { head: { name: e, type: "validate", handler: t }, tail: this.steps },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add a regular step that can return state to merge
+   */
+  step(e, t, r) {
+    return new f(
+      this.name,
+      { head: { name: e, type: "step", handler: t, retryOptions: r }, tail: this.steps },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add a conditional step that only executes if condition is met
+   */
+  stepIf(e, t, r, o) {
+    return new f(
+      this.name,
+      { head: { name: e, type: "step", handler: r, condition: t, retryOptions: o }, tail: this.steps },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add a transaction step for database operations
+   */
+  transaction(e, t) {
+    return new f(
+      this.name,
+      {
+        // Safe assertion: at runtime the executor passes the actual ORM tx object,
+        // which matches the inferred type. The step definition uses `unknown` for
+        // storage but contravariance prevents direct assignment.
+        head: { name: e, type: "transaction", handler: t },
+        tail: this.steps
+      },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add an event publishing step with explicit channel
+   */
+  event(e, t, r = "publishEvent") {
+    return new f(
+      this.name,
+      { head: { name: r, type: "event", channel: e, handler: t }, tail: this.steps },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add multiple events to publish to the same channel
+   */
+  events(e, t, r = "publishEvents") {
+    const o = async (n) => {
+      const i = [];
+      for (const s of t) {
+        const a = await s(n);
+        a && (Array.isArray(a) ? i.push(...a) : i.push(a));
+      }
+      return i.length > 0 ? i : void 0;
+    };
+    return new f(
+      this.name,
+      { head: { name: r, type: "event", channel: e, handler: o }, tail: this.steps },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  breakIf(e, t) {
+    const r = `break_${this.length}`;
+    return new f(
+      this.name,
+      { head: { name: r, type: "break", breakCondition: e, breakReturnValue: t }, tail: this.steps },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add a retry configuration to the last step
+   */
+  withRetry(e) {
+    return this.steps === null ? this : new f(
+      this.name,
+      { head: { ...this.steps.head, retryOptions: e }, tail: this.steps.tail },
+      this.length,
+      this.outputMapper
+    );
+  }
+  /**
+   * Add a parallel execution step that runs multiple handlers concurrently
+   * and merges their results into the flow state.
+   *
+   * @example
+   * .parallel('fetchAll', 'shallow',
+   *   (ctx) => ({ users: fetchUsers(ctx.input.orgId) }),
+   *   (ctx) => ({ posts: fetchPosts(ctx.input.orgId) }),
+   * )
+   */
+  parallel(e, t, ...r) {
+    const o = async (n) => {
+      const i = await Promise.all(
+        r.map((s) => s(n))
+      );
+      if (t === "error-on-conflict") {
+        const s = /* @__PURE__ */ new Set();
+        for (const a of i)
+          if (a && typeof a == "object")
+            for (const h in a) {
+              if (s.has(h))
+                throw new Error(
+                  `[Workflow:${e}] Key conflict detected in parallel merge: '${h}'`
+                );
+              s.add(h);
+            }
+        return Object.assign({}, ...i);
+      }
+      return t === "deep" ? v(
+        {},
+        ...i
+      ) : Object.assign({}, ...i);
+    };
+    return new f(
+      this.name,
+      {
+        head: { name: e, type: "step", handler: o },
+        tail: this.steps
+      },
+      this.length + 1,
+      this.outputMapper
+    );
+  }
+  /**
+   * Apply a builder-to-builder transformation, enabling reusable sub-flows.
+   *
+   * @example
+   * function withAuth(builder) {
+   *   return builder
+   *     .step('validateToken', ...)
+   *     .step('loadUser', ...);
+   * }
+   *
+   * createFlow('order')
+   *   .pipe(withAuth)
+   *   .step('createOrder', ...)
+   *   .build();
+   */
+  pipe(e) {
+    return e(this);
+  }
+  /**
+   * Transform the accumulated state into the final output
+   */
+  map(e) {
+    return new f(
+      this.name,
+      this.steps,
+      this.length,
+      e
+    );
+  }
+  /**
+   * Build the flow definition
+   */
+  build() {
+    const e = this.toArray(), t = /* @__PURE__ */ new Set(), r = [];
+    for (const s of e)
+      t.has(s.name) && r.push(s.name), t.add(s.name);
+    if (r.length > 0)
+      throw new Error(
+        `Flow '${this.name}' has duplicate step names: ${r.join(", ")}. Each step must have a unique name for proper debugging and observability.`
+      );
+    const o = new T(), n = {
+      name: this.name,
+      steps: e
+    }, i = this.outputMapper;
+    return {
+      name: n.name,
+      steps: n.steps,
+      execute: async (s, a, h) => {
+        const p = await o.execute(n, s, a, h);
+        return p.didBreak ? p.value : i ? i(s, p.value) : p.value;
+      }
+    };
+  }
+}
+class C {
+  constructor(e) {
+    this.logger = e;
+  }
+  onFlowStart(e, t) {
+    this.logger?.debug?.(
+      `[Workflow] Flow ${e} started. Input: ${t}`
+    );
+  }
+  onFlowComplete(e, t, r) {
+    this.logger?.debug?.(
+      `[Workflow] Flow ${e} completed. Output: ${t} - (${r}ms)`
+    );
+  }
+  onFlowError(e, t, r) {
+    this.logger?.error?.(
+      `[Workflow] Flow failed: ${e} (${r}ms)`,
+      t
+    );
+  }
+  onStepStart(e) {
+    this.logger?.debug?.(`[Workflow] Step started: ${e}`);
+  }
+  onStepComplete(e, t, r) {
+    this.logger?.debug?.(
+      `[Workflow] Step completed: ${e} (${r}ms)`
+    );
+  }
+  onStepError(e, t, r) {
+    this.logger?.error?.(
+      `[Workflow] Step failed: ${e} (${r}ms)`,
+      t
+    );
+  }
+  onStepRetry(e, t, r, o) {
+    this.logger?.warn?.(
+      `[Workflow] Step retry: ${e} (attempt ${t}/${r}) - ${o.message}`
+    );
+  }
+  onStepSkipped(e) {
+    this.logger?.debug?.(`[Workflow] Step skipped: ${e}`);
+  }
+  onFlowBreak(e, t, r, o) {
+    this.logger?.debug?.(
+      `[Workflow] Flow ${e} short-circuited at '${t}' (${o}ms)`
+    );
+  }
+}
+class O {
+  // All methods intentionally left empty
+}
+class W {
+  logger;
+  constructor(e) {
+    this.logger = e.child({ component: "workflow" });
+  }
+  onFlowStart(e, t) {
+    this.logger.info({ flow: e }, "Flow started");
+  }
+  onFlowComplete(e, t, r) {
+    this.logger.info(
+      { flow: e, durationMs: r },
+      "Flow completed"
+    );
+  }
+  onFlowError(e, t, r) {
+    this.logger.error(
+      { flow: e, durationMs: r, err: t },
+      "Flow failed"
+    );
+  }
+  onStepStart(e, t) {
+    this.logger.debug({ step: e }, "Step started");
+  }
+  onStepComplete(e, t, r, o) {
+    const n = {
+      step: e,
+      durationMs: r
+    };
+    t && typeof t == "object" && (n.resultKeys = Object.keys(t)), this.logger.info(n, "Step completed");
+  }
+  onStepError(e, t, r, o) {
+    this.logger.error(
+      { step: e, durationMs: r, err: t },
+      "Step failed"
+    );
+  }
+  onStepRetry(e, t, r, o) {
+    this.logger.warn(
+      { step: e, attempt: t, maxAttempts: r, err: o },
+      "Step retrying"
+    );
+  }
+  onStepSkipped(e, t) {
+    this.logger.debug({ step: e }, "Step skipped");
+  }
+  onFlowBreak(e, t, r, o) {
+    this.logger.info(
+      { flow: e, breakStep: t, durationMs: o },
+      "Flow short-circuited"
+    );
+  }
+}
+export {
+  C as DefaultObserver,
+  f as FlowBuilder,
+  d as FlowExecutionError,
+  O as NoOpObserver,
+  W as PinoFlowObserver,
+  k as TimeoutError,
+  b as ValidationError,
+  D as createFlow
+};

package/dist/lib/flow-builder.d.ts

@@ -0,0 +1,120 @@
+import { FlowContext, FlowDefinition, StepDefinition, StepCondition, RetryOptions, FlowState, BaseFlowDependencies, FlowEvent, MergeStrategy } from './types.js';
+type StepNode<T> = {
+    readonly head: T;
+    readonly tail: StepNode<T> | null;
+};
+/**
+ * Infer the transaction client type from the deps' db.transaction signature.
+ * Falls back to `unknown` when TDeps is `never` or db is absent/untyped.
+ */
+type InferTransactionClient<TDeps> = [TDeps] extends [never] ? unknown : TDeps extends {
+    db: {
+        transaction(fn: (tx: infer Tx) => any): any;
+    };
+} ? Tx : unknown;
+/**
+ * Converts a union type to an intersection type.
+ * Used to merge return types from parallel/sequence handlers.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Create a new flow with the given name
+ */
+export declare function createFlow<TInput, TDeps extends BaseFlowDependencies = never>(name: string): FlowBuilder<TInput, TDeps, Record<string, never>, never, never>;
+/**
+ * FlowBuilder provides a fluent API for creating declarative workflows
+ */
+export declare class FlowBuilder<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState, TMapperOutput = never, TBreakOutputs = never> {
+    private name;
+    private steps;
+    private length;
+    private outputMapper?;
+    constructor(name: string, steps?: StepNode<StepDefinition<TInput, TDeps, TState>> | null, length?: number, mapper?: (input: TInput, state: TState) => TMapperOutput);
+    private toArray;
+    /**
+     * Add a validation step
+     */
+    validate(name: string, handler: (ctx: FlowContext<TInput, TDeps, TState>) => void | Promise<void>): FlowBuilder<TInput, TDeps, TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add a regular step that can return state to merge
+     */
+    step<TResult extends object>(name: string, handler: (ctx: FlowContext<TInput, TDeps, TState>) => TResult | void | undefined | Promise<TResult | void | undefined>, retryOptions?: RetryOptions): FlowBuilder<TInput, TDeps, TResult & TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add a conditional step that only executes if condition is met
+     */
+    stepIf<TResult extends object>(name: string, condition: StepCondition<TInput, TDeps, TState>, handler: (ctx: FlowContext<TInput, TDeps, TState>) => TResult | void | undefined | Promise<TResult | void | undefined>, retryOptions?: RetryOptions): FlowBuilder<TInput, TDeps, TResult & TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add a transaction step for database operations
+     */
+    transaction<TResult extends object>(name: string, handler: (ctx: FlowContext<TInput, TDeps, TState>, tx: InferTransactionClient<TDeps>) => TResult | Promise<TResult>): FlowBuilder<TInput, TDeps, TResult & TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add an event publishing step with explicit channel
+     */
+    event(channel: string, builder: (ctx: FlowContext<TInput, TDeps, TState>) => FlowEvent | FlowEvent[] | void | Promise<FlowEvent | FlowEvent[] | void>, name?: string): FlowBuilder<TInput, TDeps, TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add multiple events to publish to the same channel
+     */
+    events(channel: string, builders: Array<(ctx: FlowContext<TInput, TDeps, TState>) => FlowEvent | FlowEvent[] | void | Promise<FlowEvent | FlowEvent[] | void>>, name?: string): FlowBuilder<TInput, TDeps, TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add a break condition that short-circuits the flow if met.
+     * When the condition returns true, the flow stops and returns the value
+     * from the returnValue function (or the accumulated state if not provided).
+     *
+     * @param condition - Function that returns true to break the flow
+     * @param returnValue - Optional function to compute the return value when breaking
+     * @returns New FlowBuilder with break step added
+     *
+     * @example
+     * .step('validateToken', validateVerificationTokenStep)
+     * .breakIf(
+     *   (ctx) => ctx.state.alreadyVerified,
+     *   (ctx) => ({ success: true, alreadyVerified: true })
+     * )
+     * .step('getAccount', getAccountStep)  // Only runs if not already verified
+     */
+    breakIf(condition: (ctx: FlowContext<TInput, TDeps, TState>) => boolean): FlowBuilder<TInput, TDeps, TState, TMapperOutput, TBreakOutputs | TState>;
+    breakIf<TBreakOutput>(condition: (ctx: FlowContext<TInput, TDeps, TState>) => boolean, returnValue: (ctx: FlowContext<TInput, TDeps, TState>) => TBreakOutput): FlowBuilder<TInput, TDeps, TState, TMapperOutput, TBreakOutputs | TBreakOutput>;
+    /**
+     * Add a retry configuration to the last step
+     */
+    withRetry(options: RetryOptions): FlowBuilder<TInput, TDeps, TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Add a parallel execution step that runs multiple handlers concurrently
+     * and merges their results into the flow state.
+     *
+     * @example
+     * .parallel('fetchAll', 'shallow',
+     *   (ctx) => ({ users: fetchUsers(ctx.input.orgId) }),
+     *   (ctx) => ({ posts: fetchPosts(ctx.input.orgId) }),
+     * )
+     */
+    parallel<TResults extends object[]>(name: string, strategy: MergeStrategy, ...handlers: {
+        [K in keyof TResults]: (ctx: FlowContext<TInput, TDeps, TState>) => TResults[K] | Promise<TResults[K]>;
+    }): FlowBuilder<TInput, TDeps, UnionToIntersection<TResults[number]> & TState, TMapperOutput, TBreakOutputs>;
+    /**
+     * Apply a builder-to-builder transformation, enabling reusable sub-flows.
+     *
+     * @example
+     * function withAuth(builder) {
+     *   return builder
+     *     .step('validateToken', ...)
+     *     .step('loadUser', ...);
+     * }
+     *
+     * createFlow('order')
+     *   .pipe(withAuth)
+     *   .step('createOrder', ...)
+     *   .build();
+     */
+    pipe<R>(fn: (builder: this) => R): R;
+    /**
+     * Transform the accumulated state into the final output
+     */
+    map<TNewOutput>(mapper: (input: TInput, state: TState) => TNewOutput): FlowBuilder<TInput, TDeps, TState, TNewOutput, TBreakOutputs>;
+    /**
+     * Build the flow definition
+     */
+    build(): FlowDefinition<TInput, TDeps, TState, TMapperOutput, TBreakOutputs>;
+}
+export {};
+//# sourceMappingURL=flow-builder.d.ts.map

package/dist/lib/flow-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-builder.d.ts","sourceRoot":"","sources":["../../src/lib/flow-builder.ts"],"names":[],"mappings":"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"}

package/dist/lib/flow-executor.d.ts

@@ -0,0 +1,33 @@
+import { FlowConfig, FlowExecutionOptions, FlowState, BaseFlowDependencies, FlowExecutionResult } from './types.js';
+export declare class FlowExecutor<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState = Record<string, unknown>> {
+    /**
+     * Execute a complete flow from configuration
+     * @returns FlowExecutionResult containing the result value and whether flow was short-circuited
+     */
+    execute(config: FlowConfig<TInput, TDeps, TState>, input: TInput, deps: TDeps, options?: FlowExecutionOptions<TInput, TDeps, TState>): Promise<FlowExecutionResult<TState>>;
+    /**
+     * Execute a single step with retry logic
+     */
+    private executeStep;
+    /**
+     * Execute a step with retry logic
+     */
+    private executeWithRetry;
+    /**
+     * Execute a single step without retry
+     */
+    private executeSingleStep;
+    /**
+     * Execute a transaction step
+     */
+    private executeTransaction;
+    /**
+     * Execute an event publishing step
+     */
+    private executeEvent;
+    /**
+     * Publish a single event to a specific channel
+     */
+    private publishEvent;
+}
+//# sourceMappingURL=flow-executor.d.ts.map

package/dist/lib/flow-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-executor.d.ts","sourceRoot":"","sources":["../../src/lib/flow-executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAEV,UAAU,EACV,oBAAoB,EAIpB,SAAS,EACT,oBAAoB,EAGpB,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAuEpB,qBAAa,YAAY,CACvB,MAAM,EACN,KAAK,SAAS,oBAAoB,EAClC,MAAM,SAAS,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElD;;;OAGG;IACG,OAAO,CACX,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,EACzC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE,oBAAoB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,GACpD,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IA4IvC;;OAEG;YACW,WAAW;IAgBzB;;OAEG;YACW,gBAAgB;IA4D9B;;OAEG;YACW,iBAAiB;IA+F/B;;OAEG;YACW,kBAAkB;IA4BhC;;OAEG;YACW,YAAY;IA+C1B;;OAEG;YACW,YAAY;CAc3B"}

package/dist/lib/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @celom/prose - Declarative workflow DSL for orchestrating complex business operations
+ */
+export * from './types.js';
+export { ValidationError, FlowExecutionError, TimeoutError } from './types.js';
+export { createFlow, FlowBuilder, } from './flow-builder.js';
+export type { FlowObserver } from './observer.js';
+export { DefaultObserver, NoOpObserver } from './observer.js';
+export { PinoFlowObserver, type PinoLike } from './pino-observer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/E,OAAO,EACL,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/lib/observer.d.ts

@@ -0,0 +1,71 @@
+import { BaseFlowDependencies, FlowContext, FlowState } from './types.js';
+/**
+ * Observer interface for monitoring flow execution
+ * All methods are optional - implement only what you need
+ */
+export interface FlowObserver<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> {
+    /**
+     * Called when a flow starts execution
+     */
+    onFlowStart?: (flowName: string, input: TInput) => void;
+    /**
+     * Called when a flow completes successfully
+     */
+    onFlowComplete?: (flowName: string, output: TState, totalDuration: number) => void;
+    /**
+     * Called when a flow fails with an error
+     */
+    onFlowError?: (flowName: string, error: Error, totalDuration: number) => void;
+    /**
+     * Called when a step starts execution
+     */
+    onStepStart?: (stepName: string, context: FlowContext<TInput, TDeps, TState>) => void;
+    /**
+     * Called when a step completes successfully
+     */
+    onStepComplete?: (stepName: string, result: unknown, duration: number, context: FlowContext<TInput, TDeps, TState>) => void;
+    /**
+     * Called when a step fails with an error
+     */
+    onStepError?: (stepName: string, error: Error, duration: number, context: FlowContext<TInput, TDeps, TState>) => void;
+    /**
+     * Called when a step is retried
+     */
+    onStepRetry?: (stepName: string, attempt: number, maxAttempts: number, error: Error) => void;
+    /**
+     * Called when a step is skipped due to condition
+     */
+    onStepSkipped?: (stepName: string, context: FlowContext<TInput, TDeps, TState>) => void;
+    /**
+     * Called when a flow is short-circuited via breakIf
+     */
+    onFlowBreak?: (flowName: string, breakStepName: string, returnValue: unknown, totalDuration: number) => void;
+}
+/**
+ * Default observer implementation that logs to console
+ * Useful for development and debugging
+ */
+export declare class DefaultObserver<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> implements FlowObserver<TInput, TDeps, TState> {
+    private logger?;
+    constructor(logger?: {
+        debug?: (msg: string) => void;
+        error?: (msg: string, error: Error) => void;
+        warn?: (msg: string) => void;
+    } | undefined);
+    onFlowStart(flowName: string, input: TInput): void;
+    onFlowComplete(flowName: string, output: TState, totalDuration: number): void;
+    onFlowError(flowName: string, error: Error, totalDuration: number): void;
+    onStepStart(stepName: string): void;
+    onStepComplete(stepName: string, result: unknown, duration: number): void;
+    onStepError(stepName: string, error: Error, duration: number): void;
+    onStepRetry(stepName: string, attempt: number, maxAttempts: number, error: Error): void;
+    onStepSkipped(stepName: string): void;
+    onFlowBreak(flowName: string, breakStepName: string, returnValue: unknown, totalDuration: number): void;
+}
+/**
+ * No-op observer that does nothing
+ * Useful for testing or when observability is not needed
+ */
+export declare class NoOpObserver<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> implements FlowObserver<TInput, TDeps, TState> {
+}
+//# sourceMappingURL=observer.d.ts.map

package/dist/lib/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/lib/observer.ts"],"names":[],"mappings":"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"}

package/dist/lib/pino-observer.d.ts

@@ -0,0 +1,27 @@
+import { BaseFlowDependencies, FlowState } from './types.js';
+import { FlowObserver } from './observer.js';
+/**
+ * Minimal pino-compatible logger interface.
+ * Avoids a direct pino dependency — satisfied by fastify.log.
+ */
+export interface PinoLike {
+    info: (obj: Record<string, unknown>, msg: string) => void;
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+    error: (obj: Record<string, unknown>, msg: string) => void;
+    child: (bindings: Record<string, unknown>) => PinoLike;
+}
+export declare class PinoFlowObserver<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> implements FlowObserver<TInput, TDeps, TState> {
+    private logger;
+    constructor(logger: PinoLike);
+    onFlowStart(flowName: string, _input: TInput): void;
+    onFlowComplete(flowName: string, _output: TState, totalDuration: number): void;
+    onFlowError(flowName: string, error: Error, totalDuration: number): void;
+    onStepStart(stepName: string, _context: unknown): void;
+    onStepComplete(stepName: string, result: unknown, duration: number, _context: unknown): void;
+    onStepError(stepName: string, error: Error, duration: number, _context: unknown): void;
+    onStepRetry(stepName: string, attempt: number, maxAttempts: number, error: Error): void;
+    onStepSkipped(stepName: string, _context: unknown): void;
+    onFlowBreak(flowName: string, breakStepName: string, _returnValue: unknown, totalDuration: number): void;
+}
+//# sourceMappingURL=pino-observer.d.ts.map

package/dist/lib/pino-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pino-observer.d.ts","sourceRoot":"","sources":["../../src/lib/pino-observer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,QAAQ,CAAC;CACxD;AAED,qBAAa,gBAAgB,CAC3B,MAAM,EACN,KAAK,SAAS,oBAAoB,EAClC,MAAM,SAAS,SAAS,CACxB,YAAW,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;IAE9C,OAAO,CAAC,MAAM,CAAW;gBAEb,MAAM,EAAE,QAAQ;IAI5B,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAInD,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,IAAI;IAOP,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAOxE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAItD,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,GAChB,IAAI;IAcP,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,GAChB,IAAI;IAOP,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,KAAK,GACX,IAAI;IAOP,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxD,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,MAAM,GACpB,IAAI;CAMR"}

package/dist/lib/types.d.ts

@@ -0,0 +1,269 @@
+import { FlowObserver } from './observer.js';
+/**
+ * A database client capable of running transactions.
+ *
+ * Any ORM / driver that exposes a `transaction()` method satisfies this
+ * (e.g. Drizzle, Knex, Prisma).
+ */
+export interface DatabaseClient {
+    transaction<T>(fn: (tx: TransactionClient) => Promise<T>): Promise<T>;
+}
+/**
+ * The transaction client passed into transaction step handlers.
+ *
+ * Intentionally opaque so consumers can narrow it to their ORM's
+ * transaction type via the generic parameter on `.transaction()`.
+ */
+export type TransactionClient = unknown;
+/**
+ * A flow event that can be published.
+ *
+ * Only `eventType` is required by the framework; everything else is
+ * pass-through data attached by the application.
+ */
+export interface FlowEvent {
+    eventType: string;
+    [key: string]: unknown;
+}
+/**
+ * An event publisher capable of publishing events to named channels.
+ */
+export interface FlowEventPublisher {
+    publish(channel: string, event: FlowEvent): Promise<void> | void;
+}
+export type BaseFlowDependencies = {
+    db?: DatabaseClient;
+    eventPublisher?: FlowEventPublisher;
+};
+export type FlowState = Record<string, unknown>;
+/**
+ * Flow metadata tracked during execution
+ */
+export interface FlowMeta {
+    flowName: string;
+    startedAt: Date;
+    currentStep?: string;
+    correlationId?: string;
+}
+/**
+ * Context passed to each step in the flow
+ */
+export interface FlowContext<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> {
+    readonly input: Readonly<TInput>;
+    state: TState;
+    deps: TDeps;
+    meta: FlowMeta;
+    /** AbortSignal for cooperative cancellation. Aborted on timeout or external signal. */
+    signal: AbortSignal;
+}
+/**
+ * Result of a step execution
+ */
+export type StepResult<T> = T | void | undefined;
+/**
+ * Condition checker for conditional steps
+ */
+export type StepCondition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> = (ctx: FlowContext<TInput, TDeps, TState>) => boolean;
+/**
+ * Error handling configuration for flow execution
+ */
+export interface ErrorHandlingConfig {
+    /** Throw error if event publisher is missing (default: true) */
+    throwOnMissingEventPublisher?: boolean;
+    /** Throw error if database is missing for transaction (default: true) */
+    throwOnMissingDatabase?: boolean;
+}
+/**
+ * Options for flow execution
+ */
+export interface FlowExecutionOptions<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> {
+    correlationId?: string;
+    throwOnError?: boolean;
+    /** Timeout in milliseconds for the entire flow */
+    timeout?: number;
+    /** Timeout in milliseconds for individual steps */
+    stepTimeout?: number;
+    /** External AbortSignal for caller-driven cancellation */
+    signal?: AbortSignal;
+    observer?: FlowObserver<TInput, TDeps, TState>;
+    errorHandling?: ErrorHandlingConfig;
+}
+/**
+ * Base properties shared by all step types
+ */
+interface BaseStepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> {
+    name: string;
+    condition?: StepCondition<TInput, TDeps, TState>;
+    retryOptions?: RetryOptions;
+}
+/**
+ * Validation step - validates input or state without returning data
+ */
+export interface ValidationStepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> extends BaseStepDefinition<TInput, TDeps, TState> {
+    type: 'validate';
+    handler: (ctx: FlowContext<TInput, TDeps, TState>) => void | Promise<void>;
+}
+/**
+ * Executor step - performs work and returns state to merge
+ */
+export interface ExecutorStepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> extends BaseStepDefinition<TInput, TDeps, TState> {
+    type: 'step';
+    handler: (ctx: FlowContext<TInput, TDeps, TState>) => StepResult<unknown> | Promise<StepResult<unknown>>;
+}
+/**
+ * Transaction step - performs work within a database transaction
+ */
+export interface TransactionStepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> extends BaseStepDefinition<TInput, TDeps, TState> {
+    type: 'transaction';
+    handler: (ctx: FlowContext<TInput, TDeps, TState>, tx: TransactionClient) => unknown | Promise<unknown>;
+}
+/**
+ * Event step - publishes events to a specific channel
+ */
+export interface EventStepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> extends BaseStepDefinition<TInput, TDeps, TState> {
+    type: 'event';
+    channel: string;
+    handler: (ctx: FlowContext<TInput, TDeps, TState>) => FlowEvent | FlowEvent[] | void | Promise<FlowEvent | FlowEvent[] | void>;
+}
+/**
+ * Break condition checker for short-circuit flow termination
+ */
+export type BreakCondition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> = (ctx: FlowContext<TInput, TDeps, TState>) => boolean;
+/**
+ * Break return value generator
+ */
+export type BreakReturnValue<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState, TBreakOutput> = (ctx: FlowContext<TInput, TDeps, TState>) => TBreakOutput;
+/**
+ * Break step - short-circuits the flow if condition is met
+ *
+ * @example
+ * .step('validateToken', validateVerificationTokenStep)
+ * .breakIf(
+ *   (ctx) => ctx.state.alreadyVerified,
+ *   (ctx) => ({ success: true, alreadyVerified: true })
+ * )
+ */
+export interface BreakStepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> extends BaseStepDefinition<TInput, TDeps, TState> {
+    type: 'break';
+    breakCondition: BreakCondition<TInput, TDeps, TState>;
+    breakReturnValue?: BreakReturnValue<TInput, TDeps, TState, unknown>;
+}
+/**
+ * Discriminated union of all step types
+ */
+export type StepDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> = ValidationStepDefinition<TInput, TDeps, TState> | ExecutorStepDefinition<TInput, TDeps, TState> | TransactionStepDefinition<TInput, TDeps, TState> | EventStepDefinition<TInput, TDeps, TState> | BreakStepDefinition<TInput, TDeps, TState>;
+/**
+ * Merge strategy for parallel execution
+ * - 'shallow': Default - later results override earlier ones (silent overwrites)
+ * - 'error-on-conflict': Throw error if keys conflict between results
+ * - 'deep': Perform deep merge of nested objects
+ */
+export type MergeStrategy = 'shallow' | 'error-on-conflict' | 'deep';
+/**
+ * Retry configuration for a step
+ */
+export interface RetryOptions {
+    maxAttempts: number;
+    delayMs: number;
+    backoffMultiplier?: number;
+    maxDelayMs?: number;
+    shouldRetry?: (error: Error) => boolean;
+    /** Timeout in milliseconds for this specific step (overrides flow-level stepTimeout) */
+    stepTimeout?: number;
+}
+/**
+ * Timeout configuration for flow or step execution
+ */
+export interface TimeoutOptions {
+    /** Timeout in milliseconds for the entire flow */
+    timeout?: number;
+    /** Timeout in milliseconds for individual steps (overrides flow timeout for steps) */
+    stepTimeout?: number;
+}
+/**
+ * Error thrown when a step or flow times out
+ */
+export declare class TimeoutError extends Error {
+    flowName: string;
+    stepName?: string | undefined;
+    timeoutMs?: number | undefined;
+    constructor(message: string, flowName: string, stepName?: string | undefined, timeoutMs?: number | undefined);
+}
+/**
+ * Internal result from flow executor indicating whether flow completed normally or short-circuited
+ */
+export interface FlowExecutionResult<TState> {
+    /** The result value (either accumulated state or break return value) */
+    value: TState;
+    /** Whether the flow was short-circuited via breakIf */
+    didBreak: boolean;
+}
+/**
+ * Flow configuration - just the definition without execution
+ */
+export interface FlowConfig<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState> {
+    name: string;
+    steps: StepDefinition<TInput, TDeps, TState>[];
+}
+/**
+ * Helper type to infer the correct output type
+ * Uses tuple wrapping to properly handle the never type
+ */
+export type InferFlowOutput<TState, TMapperOutput> = [TMapperOutput] extends [
+    never
+] ? TState : TMapperOutput;
+/**
+ * Flow definition containing all steps and execution method
+ */
+export interface FlowDefinition<TInput, TDeps extends BaseFlowDependencies, TState extends FlowState, TMapperOutput = never, TBreakOutputs = never> {
+    name: string;
+    steps: StepDefinition<TInput, TDeps, TState>[];
+    execute: (input: TInput, deps: TDeps, options?: FlowExecutionOptions<TInput, TDeps, TState>) => Promise<InferFlowOutput<TState, TMapperOutput> | TBreakOutputs>;
+}
+/**
+ * Validation issue details
+ */
+export interface ValidationIssue {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+/**
+ * Error thrown during validation
+ * Supports both single field errors and multiple validation issues
+ */
+export declare class ValidationError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(message: string, issues?: ValidationIssue[] | string);
+    /**
+     * Create a validation error for a single field
+     */
+    static single(field: string, message: string, value?: unknown): ValidationError;
+    /**
+     * Create a validation error for multiple fields
+     */
+    static multiple(issues: ValidationIssue[]): ValidationError;
+    /**
+     * Convert to JSON for serialization
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        issues: ValidationIssue[];
+    };
+    /**
+     * Get a single field error (for backward compatibility)
+     */
+    get field(): string | undefined;
+}
+/**
+ * Error thrown during flow execution
+ */
+export declare class FlowExecutionError extends Error {
+    flowName: string;
+    stepName?: string | undefined;
+    originalError?: Error | undefined;
+    constructor(message: string, flowName: string, stepName?: string | undefined, originalError?: Error | undefined);
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deep merge utility for combining objects recursively.
+ * - Plain objects are merged recursively
+ * - Arrays are concatenated (not overwritten)
+ * - Non-plain objects (Date, Map, Set, etc.) are treated as primitives
+ */
+export declare function deepMerge(...objects: Array<Record<string, unknown> | null | undefined>): Record<string, unknown>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/lib/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/lib/utils.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,GAAG,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC5D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkCzB"}

package/dist/puppet.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Type inference smoke test for FlowBuilder's cons-list internals.
+ * This file is NOT meant to be executed — only type-checked.
+ *
+ * Run: npx tsc --noEmit --project packages/prose/tsconfig.lib.json
+ */
+export {};
+//# sourceMappingURL=puppet.d.ts.map

package/dist/puppet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"puppet.d.ts","sourceRoot":"","sources":["../src/puppet.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@celom/prose",
-  "version": "0.1.3",
+  "version": "0.2.0",
+  "license": "MIT",
   "author": "Carlos Mimoso",
   "description": "Declarative workflow DSL for orchestrating complex business operations in Javascript/Typescript.",
   "keywords": [