@magic-marker/nurt 0.1.0

package/dist/index.js

@@ -0,0 +1,996 @@
+// src/errors.ts
+var CycleDetectedError = class extends Error {
+  constructor(cycle) {
+    super(`Cycle detected in flow graph: ${cycle.join(" \u2192 ")}`);
+    this.name = "CycleDetectedError";
+  }
+};
+var DuplicateStepError = class extends Error {
+  constructor(name) {
+    super(`Step "${name}" is already registered`);
+    this.name = "DuplicateStepError";
+  }
+};
+var UnknownParentError = class extends Error {
+  constructor(stepName, parentName) {
+    super(`Step "${stepName}" depends on unknown parent "${parentName}"`);
+    this.name = "UnknownParentError";
+  }
+};
+var UnsealedGroupError = class extends Error {
+  constructor(groupName) {
+    super(`Group "${groupName}" was never sealed`);
+    this.name = "UnsealedGroupError";
+  }
+};
+var UnfilledSlotError = class extends Error {
+  constructor(slotPath) {
+    super(`Slot "${slotPath}" was not provided an implementation`);
+    this.name = "UnfilledSlotError";
+  }
+};
+var StepExecutionError = class extends Error {
+  stepName;
+  cause;
+  constructor(stepName, cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    super(`Step "${stepName}" failed: ${message}`);
+    this.name = "StepExecutionError";
+    this.stepName = stepName;
+    this.cause = cause;
+  }
+};
+
+// src/graph.ts
+function validateAcyclic(nodes) {
+  const inDegree = /* @__PURE__ */ new Map();
+  const children = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (!inDegree.has(node.name)) {
+      inDegree.set(node.name, 0);
+    }
+    if (!children.has(node.name)) {
+      children.set(node.name, []);
+    }
+    for (const parent of node.parentNames) {
+      if (!children.has(parent)) {
+        children.set(parent, []);
+      }
+      children.get(parent).push(node.name);
+      inDegree.set(node.name, (inDegree.get(node.name) ?? 0) + 1);
+    }
+  }
+  const queue = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(name);
+    }
+  }
+  let visited = 0;
+  while (queue.length > 0) {
+    const current = queue.shift();
+    visited++;
+    for (const child of children.get(current) ?? []) {
+      const newDegree = inDegree.get(child) - 1;
+      inDegree.set(child, newDegree);
+      if (newDegree === 0) {
+        queue.push(child);
+      }
+    }
+  }
+  if (visited < nodes.length) {
+    const remaining = nodes.filter((n) => (inDegree.get(n.name) ?? 0) > 0).map((n) => n.name);
+    throw new CycleDetectedError(remaining);
+  }
+}
+function topologicalSort(nodes) {
+  const inDegree = /* @__PURE__ */ new Map();
+  const children = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (!inDegree.has(node.name)) {
+      inDegree.set(node.name, 0);
+    }
+    if (!children.has(node.name)) {
+      children.set(node.name, []);
+    }
+    for (const parent of node.parentNames) {
+      if (!children.has(parent)) {
+        children.set(parent, []);
+      }
+      children.get(parent).push(node.name);
+      inDegree.set(node.name, (inDegree.get(node.name) ?? 0) + 1);
+    }
+  }
+  const queue = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(name);
+    }
+  }
+  const sorted = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    sorted.push(current);
+    for (const child of children.get(current) ?? []) {
+      const newDegree = inDegree.get(child) - 1;
+      inDegree.set(child, newDegree);
+      if (newDegree === 0) {
+        queue.push(child);
+      }
+    }
+  }
+  return sorted;
+}
+function getReadySteps(steps, statuses) {
+  const ready = [];
+  for (const step of steps) {
+    const status = statuses.get(step.name);
+    if (status !== "pending") continue;
+    const allParentsDone = step.parentNames.every((parent) => {
+      const parentStatus = statuses.get(parent);
+      return parentStatus === "success";
+    });
+    if (allParentsDone) {
+      ready.push(step.name);
+    }
+  }
+  return ready;
+}
+function getSkippableSteps(steps, statuses) {
+  const skippable = [];
+  for (const step of steps) {
+    const status = statuses.get(step.name);
+    if (status !== "pending") continue;
+    if (step.allowFailures) continue;
+    const hasFailedParent = step.parentNames.some((parent) => {
+      const parentStatus = statuses.get(parent);
+      return parentStatus === "error" || parentStatus === "skipped";
+    });
+    if (hasFailedParent) {
+      skippable.push(step.name);
+    }
+  }
+  return skippable;
+}
+function getReadyWithFailures(steps, statuses) {
+  const ready = [];
+  for (const step of steps) {
+    const status = statuses.get(step.name);
+    if (status !== "pending") continue;
+    if (!step.allowFailures) continue;
+    const allParentsSettled = step.parentNames.every((parent) => {
+      const parentStatus = statuses.get(parent);
+      return parentStatus === "success" || parentStatus === "error" || parentStatus === "skipped";
+    });
+    if (allParentsSettled) {
+      ready.push(step.name);
+    }
+  }
+  return ready;
+}
+
+// src/types.ts
+var GROUP_REF_BRAND = /* @__PURE__ */ Symbol("GroupRef");
+function group(name) {
+  return { [GROUP_REF_BRAND]: true, groupName: name };
+}
+function isGroupRef(value) {
+  return typeof value === "object" && value !== null && GROUP_REF_BRAND in value;
+}
+function isSubgraphMember(member) {
+  return "flow" in member;
+}
+function isExecutable(value) {
+  return typeof value === "object" && value !== null && "execute" in value && typeof value.execute === "function";
+}
+function invokeHandler(handler, input, ctx) {
+  if (isExecutable(handler)) {
+    return handler.execute(input, ctx);
+  }
+  return handler(
+    input,
+    ctx
+  );
+}
+
+// src/snapshot.ts
+function createSnapshot(input) {
+  const steps = input.flow.steps.map((def) => {
+    const record = input.stepRecords.get(def.name);
+    return {
+      allowFailures: def.allowFailures,
+      completedAt: record?.completedAt,
+      durationMs: record?.durationMs,
+      error: record?.error,
+      name: def.name,
+      output: record?.output,
+      parentNames: [...def.parentNames],
+      startedAt: record?.startedAt,
+      status: record?.status ?? "pending",
+      terminal: def.terminal
+    };
+  });
+  const groups = input.flow.groups.map((groupDef) => {
+    const runtime = input.groupRuntimes.get(groupDef.name);
+    return {
+      dependsOn: [...groupDef.dependsOn],
+      members: runtime?.members.map(serializeGroupMember) ?? [],
+      name: groupDef.name,
+      sealed: runtime?.sealed ?? false
+    };
+  });
+  return {
+    flow: {
+      groups,
+      name: input.flow.name,
+      steps
+    },
+    run: {
+      completedAt: input.run.completedAt,
+      runId: input.run.runId,
+      startedAt: input.run.startedAt,
+      status: input.run.status
+    }
+  };
+}
+function serializeGroupMember(member) {
+  const isSubgraph = isSubgraphMember(member.member);
+  const durationMs = member.startedAt && member.completedAt ? member.completedAt - member.startedAt : void 0;
+  const result = {
+    completedAt: member.completedAt,
+    durationMs,
+    error: member.error,
+    name: member.name,
+    output: member.output,
+    startedAt: member.startedAt,
+    status: member.status,
+    type: isSubgraph ? "subgraph" : "single"
+  };
+  if (isSubgraph) {
+    const sub = member.member;
+    if (sub.externalDeps) {
+      result.externalDeps = { ...sub.externalDeps };
+    }
+    if (member.childRun) {
+      result.subgraph = member.childRun.snapshot();
+    }
+  }
+  return result;
+}
+
+// src/group.ts
+function createGroupRuntime(name, dependsOn) {
+  return {
+    dependsOn,
+    members: [],
+    name,
+    sealed: false
+  };
+}
+function addGroupMembers(group2, members, seal) {
+  for (const member of members) {
+    group2.members.push({
+      member,
+      name: member.name,
+      status: "pending"
+    });
+  }
+  if (seal) {
+    group2.sealed = true;
+  }
+}
+function isGroupComplete(group2) {
+  if (!group2.sealed) return false;
+  return group2.members.every(
+    (m) => m.status === "success" || m.status === "error"
+  );
+}
+function collectGroupOutputs(group2) {
+  return group2.members.map((m) => {
+    if (m.status === "success") {
+      return { status: "success", value: m.output };
+    }
+    return {
+      error: m.error ?? "Unknown error",
+      status: "error"
+    };
+  });
+}
+function collectSuccessOutputs(group2) {
+  return group2.members.filter((m) => m.status === "success").map((m) => m.output);
+}
+async function executeGroupMember(memberRuntime, parentInput, ctx, parentStepOutputs, onStateChange) {
+  memberRuntime.status = "running";
+  memberRuntime.startedAt = Date.now();
+  onStateChange?.();
+  try {
+    if (isSubgraphMember(memberRuntime.member)) {
+      const subgraph = memberRuntime.member;
+      let injectedSteps;
+      if (subgraph.externalDeps && parentStepOutputs) {
+        const deps = Object.entries(subgraph.externalDeps);
+        while (!ctx.signal.aborted && deps.some(([, parentName]) => !parentStepOutputs.has(parentName))) {
+          await new Promise((r) => setTimeout(r, 10));
+        }
+        injectedSteps = /* @__PURE__ */ new Map();
+        for (const [childStepName, parentStepName] of deps) {
+          injectedSteps.set(
+            childStepName,
+            parentStepOutputs.get(parentStepName)
+          );
+        }
+      }
+      const childHooks = onStateChange ? {
+        onStepComplete: onStateChange,
+        onStepError: onStateChange,
+        onStepStart: onStateChange
+      } : void 0;
+      const childRun = subgraph.flow.run({
+        hooks: childHooks,
+        injectedSteps
+      });
+      memberRuntime.childRun = childRun;
+      const onAbort = () => childRun.abort();
+      ctx.signal.addEventListener("abort", onAbort);
+      const result = await childRun.result;
+      ctx.signal.removeEventListener("abort", onAbort);
+      if (result.status === "error") {
+        const errorStep = result.steps.find((s) => s.status === "error");
+        throw new Error(errorStep?.error ?? "Subgraph failed");
+      }
+      const terminalStep = result.steps.find(
+        (s) => s.status === "success" && subgraph.flow.steps.some(
+          (d) => d.name === s.name && d.terminal
+        )
+      );
+      memberRuntime.output = terminalStep?.output ?? result.steps.findLast((s) => s.status === "success")?.output;
+    } else {
+      const single = memberRuntime.member;
+      memberRuntime.output = await invokeHandler(
+        single.execute,
+        parentInput,
+        ctx
+      );
+    }
+    memberRuntime.status = "success";
+    memberRuntime.completedAt = Date.now();
+    onStateChange?.();
+  } catch (error) {
+    memberRuntime.status = "error";
+    memberRuntime.completedAt = Date.now();
+    onStateChange?.();
+    memberRuntime.error = error instanceof Error ? error.message : String(error);
+    throw error;
+  }
+}
+
+// src/history.ts
+var History = class {
+  store = /* @__PURE__ */ new Map();
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  get(key) {
+    return this.store.get(key);
+  }
+  has(key) {
+    return this.store.has(key);
+  }
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+
+// src/flow-run.ts
+var generateRunId = () => crypto.randomUUID().slice(0, 8);
+var FlowRun = class {
+  runId;
+  flow;
+  hooks;
+  failFast;
+  abortController;
+  history;
+  stepDefs;
+  stepRecords;
+  stepOutputs;
+  groupRuntimes;
+  providedSlots;
+  providedData;
+  status = "idle";
+  startedAt = 0;
+  resolveResult;
+  result;
+  loopRunning = false;
+  pendingGroupStarts = [];
+  dynamicStepsAdded = false;
+  constructor(flow2, options) {
+    this.runId = generateRunId();
+    this.flow = flow2;
+    this.hooks = options?.hooks ?? {};
+    this.failFast = options?.failFast ?? false;
+    this.abortController = new AbortController();
+    this.history = new History();
+    this.stepDefs = /* @__PURE__ */ new Map();
+    this.stepRecords = /* @__PURE__ */ new Map();
+    this.stepOutputs = /* @__PURE__ */ new Map();
+    this.groupRuntimes = /* @__PURE__ */ new Map();
+    this.providedSlots = /* @__PURE__ */ new Map();
+    this.providedData = /* @__PURE__ */ new Map();
+    for (const step of flow2.steps) {
+      this.stepDefs.set(step.name, step);
+      this.stepRecords.set(step.name, {
+        name: step.name,
+        parentNames: step.parentNames,
+        status: "pending"
+      });
+    }
+    for (const group2 of flow2.groups) {
+      this.groupRuntimes.set(
+        group2.name,
+        createGroupRuntime(group2.name, group2.dependsOn)
+      );
+    }
+    if (options?.injectedSteps) {
+      for (const [name, output] of options.injectedSteps) {
+        if (!this.stepDefs.has(name)) {
+          this.stepDefs.set(name, {
+            allowFailures: false,
+            handler: async () => output,
+            name,
+            parentNames: [],
+            terminal: false
+          });
+        }
+        this.stepRecords.set(name, {
+          completedAt: Date.now(),
+          durationMs: 0,
+          name,
+          output,
+          parentNames: [],
+          startedAt: Date.now(),
+          status: "success"
+        });
+        this.stepOutputs.set(name, output);
+      }
+    }
+    this.result = new Promise((resolve) => {
+      this.resolveResult = resolve;
+    });
+    this.startExecution();
+  }
+  /**
+   * Read-only snapshot of current step records.
+   */
+  get steps() {
+    return Array.from(this.stepRecords.values());
+  }
+  /**
+   * JSON-serializable snapshot of the current flow + run state.
+   */
+  snapshot() {
+    return createSnapshot({
+      flow: this.flow,
+      groupRuntimes: this.groupRuntimes,
+      run: {
+        completedAt: void 0,
+        runId: this.runId,
+        startedAt: this.startedAt,
+        status: this.status
+      },
+      stepRecords: this.stepRecords
+    });
+  }
+  /**
+   * Abort the run — signals all in-progress steps.
+   */
+  abort() {
+    this.abortController.abort();
+  }
+  /**
+   * Add a step dynamically during execution.
+   */
+  addStep(def) {
+    this.stepDefs.set(def.name, def);
+    const record = {
+      name: def.name,
+      parentNames: def.parentNames,
+      status: "pending"
+    };
+    this.stepRecords.set(def.name, record);
+    this.fireHook("onStepAdded", record);
+    this.dynamicStepsAdded = true;
+    if (!this.loopRunning && this.status === "running") {
+      this.executionLoop();
+    }
+  }
+  /**
+   * Spawn members into a group and auto-seal it.
+   */
+  spawnGroup(groupName, members) {
+    const grp = this.groupRuntimes.get(groupName);
+    if (!grp) {
+      throw new Error(`Unknown group "${groupName}"`);
+    }
+    addGroupMembers(grp, members, true);
+    this.startOrDeferGroup(grp);
+  }
+  /**
+   * Add a single member to a group (without sealing).
+   */
+  addGroupMember(groupName, member) {
+    const grp = this.groupRuntimes.get(groupName);
+    if (!grp) {
+      throw new Error(`Unknown group "${groupName}"`);
+    }
+    addGroupMembers(grp, [member], false);
+    this.startOrDeferGroup(grp);
+  }
+  /**
+   * Seal a group — no more members can be added.
+   */
+  sealGroup(groupName) {
+    const group2 = this.groupRuntimes.get(groupName);
+    if (!group2) {
+      throw new Error(`Unknown group "${groupName}"`);
+    }
+    group2.sealed = true;
+    this.checkGroupCompletion(group2);
+  }
+  /**
+   * Provide a step implementation (slot fill) or external data.
+   */
+  provide(path, value) {
+    if (typeof value === "function" || isExecutableValue(value)) {
+      this.providedSlots.set(path, value);
+    } else {
+      this.providedData.set(path, value);
+    }
+  }
+  // --- Private helpers ---
+  createContext() {
+    const runHandle = {
+      addGroupMember: (groupName, member) => this.addGroupMember(groupName, member),
+      provide: (path, value) => this.provide(path, value),
+      sealGroup: (groupName) => this.sealGroup(groupName),
+      spawnGroup: (groupName, members) => this.spawnGroup(groupName, members)
+    };
+    return {
+      history: this.history,
+      provided() {
+        return void 0;
+      },
+      run: runHandle,
+      runId: this.runId,
+      signal: this.abortController.signal
+    };
+  }
+  // --- Private execution logic ---
+  async startExecution() {
+    this.status = "running";
+    this.startedAt = Date.now();
+    await this.executionLoop();
+  }
+  async executionLoop() {
+    if (this.loopRunning) return;
+    this.loopRunning = true;
+    try {
+      while (!this.abortController.signal.aborted) {
+        this.dynamicStepsAdded = false;
+        this.markSkippableSteps();
+        const allDefs = Array.from(this.stepDefs.values());
+        const statuses = this.getStatusMap();
+        const readyNormal = getReadySteps(allDefs, statuses);
+        const readyWithFailures = getReadyWithFailures(allDefs, statuses);
+        const ready = [.../* @__PURE__ */ new Set([...readyNormal, ...readyWithFailures])];
+        if (ready.length === 0) {
+          const hasRunning = Array.from(this.stepRecords.values()).some(
+            (r) => r.status === "running"
+          );
+          const hasPendingGroups = Array.from(this.groupRuntimes.values()).some(
+            (g) => !isGroupComplete(g) && g.members.length > 0
+          );
+          if (!hasRunning && !hasPendingGroups && !this.dynamicStepsAdded) {
+            break;
+          }
+          if (!this.dynamicStepsAdded) {
+            await new Promise((resolve) => setTimeout(resolve, 1));
+            continue;
+          }
+          continue;
+        }
+        await new Promise((resolveWave) => {
+          let pending = ready.length;
+          for (const name of ready) {
+            this.executeStep(name).finally(() => {
+              pending--;
+              if (this.failFast && this.hasAnyError()) {
+                this.abortController.abort();
+              }
+              this.scheduleReadySteps();
+              if (pending === 0) resolveWave();
+            });
+          }
+        });
+      }
+    } finally {
+      this.loopRunning = false;
+    }
+    this.completeRun();
+  }
+  /**
+   * Check for and launch any newly ready steps without waiting for the full wave.
+   * Called after each individual step completion.
+   */
+  scheduleReadySteps() {
+    this.markSkippableSteps();
+    this.flushPendingGroups();
+    const allDefs = Array.from(this.stepDefs.values());
+    const statuses = this.getStatusMap();
+    const readyNormal = getReadySteps(allDefs, statuses);
+    const readyWithFailures = getReadyWithFailures(allDefs, statuses);
+    const ready = [.../* @__PURE__ */ new Set([...readyNormal, ...readyWithFailures])];
+    for (const name of ready) {
+      this.executeStep(name).finally(() => {
+        this.scheduleReadySteps();
+      });
+    }
+  }
+  async executeStep(name) {
+    const def = this.stepDefs.get(name);
+    const record = this.stepRecords.get(name);
+    record.status = "running";
+    record.startedAt = Date.now();
+    this.fireHook("onStepStart", record);
+    try {
+      const input = this.buildInput(def);
+      const ctx = this.createContext();
+      const output = await invokeHandler(def.handler, input, ctx);
+      record.status = "success";
+      record.completedAt = Date.now();
+      record.durationMs = record.completedAt - record.startedAt;
+      record.output = output;
+      this.stepOutputs.set(name, output);
+      this.fireHook("onStepComplete", record);
+      this.flushPendingGroups();
+    } catch (error) {
+      record.status = "error";
+      record.completedAt = Date.now();
+      record.durationMs = record.completedAt - record.startedAt;
+      record.error = error instanceof Error ? error.message : String(error);
+      this.fireHook("onStepError", record);
+    }
+  }
+  buildInput(def) {
+    const input = {};
+    for (const parentName of def.parentNames) {
+      const groupRuntime = this.groupRuntimes.get(parentName);
+      if (groupRuntime) {
+        input[parentName] = def.allowFailures ? collectGroupOutputs(groupRuntime) : collectSuccessOutputs(groupRuntime);
+        continue;
+      }
+      if (def.allowFailures) {
+        const parentRecord = this.stepRecords.get(parentName);
+        if (parentRecord?.status === "success") {
+          input[parentName] = {
+            status: "success",
+            value: this.stepOutputs.get(parentName)
+          };
+        } else if (parentRecord?.status === "error") {
+          input[parentName] = {
+            error: parentRecord.error ?? "Unknown error",
+            status: "error"
+          };
+        } else {
+          input[parentName] = {
+            status: "skipped"
+          };
+        }
+      } else {
+        input[parentName] = this.stepOutputs.get(parentName);
+      }
+    }
+    if (def.transform) {
+      return def.transform(input);
+    }
+    return input;
+  }
+  markSkippableSteps() {
+    const allDefs = Array.from(this.stepDefs.values());
+    const statuses = this.getStatusMap();
+    let changed = true;
+    while (changed) {
+      changed = false;
+      const skippable = getSkippableSteps(allDefs, statuses);
+      for (const name of skippable) {
+        const record = this.stepRecords.get(name);
+        record.status = "skipped";
+        statuses.set(name, "skipped");
+        changed = true;
+      }
+    }
+  }
+  getStatusMap() {
+    const map = /* @__PURE__ */ new Map();
+    for (const [name, record] of this.stepRecords) {
+      map.set(name, record.status);
+    }
+    for (const [name, group2] of this.groupRuntimes) {
+      if (isGroupComplete(group2)) {
+        const allSuccess = group2.members.every((m) => m.status === "success");
+        map.set(name, allSuccess ? "success" : "error");
+      } else if (group2.members.some((m) => m.status === "running")) {
+        map.set(name, "running");
+      } else if (group2.members.length > 0) {
+        map.set(name, "running");
+      } else {
+        map.set(name, "pending");
+      }
+    }
+    return map;
+  }
+  hasAnyError() {
+    for (const record of this.stepRecords.values()) {
+      if (record.status === "error") return true;
+    }
+    return false;
+  }
+  areGroupDependenciesMet(group2) {
+    for (const dep of group2.dependsOn) {
+      const record = this.stepRecords.get(dep);
+      if (!record || record.status !== "success") return false;
+    }
+    return true;
+  }
+  startOrDeferGroup(grp) {
+    if (this.areGroupDependenciesMet(grp)) {
+      this.startGroupMembers(grp);
+    } else {
+      if (!this.pendingGroupStarts.includes(grp)) {
+        this.pendingGroupStarts.push(grp);
+      }
+    }
+  }
+  flushPendingGroups() {
+    const toFlush = [...this.pendingGroupStarts];
+    this.pendingGroupStarts.length = 0;
+    for (const grp of toFlush) {
+      if (this.areGroupDependenciesMet(grp)) {
+        this.startGroupMembers(grp);
+      } else {
+        this.pendingGroupStarts.push(grp);
+      }
+    }
+  }
+  startGroupMembers(group2) {
+    if (!this.areGroupDependenciesMet(group2)) return;
+    const parentInput = {};
+    for (const dep of group2.dependsOn) {
+      parentInput[dep] = this.stepOutputs.get(dep);
+    }
+    const ctx = this.createContext();
+    for (const member of group2.members) {
+      if (member.status !== "pending") continue;
+      executeGroupMember(
+        member,
+        parentInput,
+        ctx,
+        this.stepOutputs,
+        () => this.fireHook("onChange", void 0)
+      ).then(() => {
+        this.checkGroupCompletion(group2);
+      }).catch(() => {
+        this.checkGroupCompletion(group2);
+      });
+    }
+  }
+  checkGroupCompletion(group2) {
+    if (isGroupComplete(group2)) {
+      this.dynamicStepsAdded = true;
+      this.fireHook("onChange", void 0);
+    }
+  }
+  completeRun() {
+    const terminalSteps = Array.from(this.stepDefs.values()).filter(
+      (d) => d.terminal
+    );
+    const stepsToCheck = terminalSteps.length > 0 ? terminalSteps.map((d) => this.stepRecords.get(d.name)) : Array.from(this.stepRecords.values());
+    const hasError = stepsToCheck.some((r) => r.status === "error");
+    this.status = hasError ? "error" : "success";
+    const result = {
+      completedAt: Date.now(),
+      history: this.history.snapshot(),
+      runId: this.runId,
+      startedAt: this.startedAt,
+      status: this.status,
+      steps: Array.from(this.stepRecords.values())
+    };
+    this.fireHook("onRunComplete", result);
+    this.resolveResult(result);
+  }
+  fireHook(hookName, arg) {
+    try {
+      const hook = this.hooks[hookName];
+      if (hook) {
+        hook(arg);
+      }
+      if (hookName !== "onChange" && this.hooks.onChange) {
+        this.hooks.onChange();
+      }
+    } catch {
+    }
+  }
+};
+function isExecutableValue(value) {
+  return typeof value === "object" && value !== null && "execute" in value && typeof value.execute === "function";
+}
+
+// src/flow.ts
+var Flow = class {
+  name;
+  steps;
+  groups;
+  constructor(name, steps, groups) {
+    const groupNodes = groups.map((g) => ({
+      name: g.name,
+      parentNames: g.dependsOn
+    }));
+    validateAcyclic([...steps, ...groupNodes]);
+    this.name = name;
+    this.steps = Object.freeze([...steps]);
+    this.groups = Object.freeze([...groups]);
+  }
+  /**
+   * Creates a new FlowRun instance.
+   * Multiple runs can execute concurrently from the same Flow.
+   */
+  run(options) {
+    return new FlowRun(this, options);
+  }
+};
+
+// src/flow-builder.ts
+var FlowBuilder = class _FlowBuilder {
+  flowName;
+  steps;
+  groups;
+  knownNames;
+  constructor(flowName, steps = [], groups = [], knownNames) {
+    this.flowName = flowName;
+    this.steps = steps;
+    this.groups = groups;
+    this.knownNames = knownNames ?? new Set(steps.map((s) => s.name));
+  }
+  // Implementation
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  step(name, parentsOrHandler, handlerOrOptions) {
+    if (this.knownNames.has(name)) {
+      throw new DuplicateStepError(name);
+    }
+    let parentNames = [];
+    let handler;
+    let allowFailures = false;
+    let terminal = false;
+    let transform;
+    if (Array.isArray(parentsOrHandler)) {
+      parentNames = parentsOrHandler.map((p) => {
+        if (isGroupRef(p)) return p.groupName;
+        return p;
+      });
+      if (typeof handlerOrOptions === "object" && handlerOrOptions !== null && "execute" in handlerOrOptions) {
+        const opts = handlerOrOptions;
+        handler = opts.execute;
+        allowFailures = opts.allowFailures ?? false;
+        terminal = opts.terminal ?? false;
+        transform = opts.transform;
+      } else {
+        handler = handlerOrOptions;
+      }
+    } else {
+      handler = parentsOrHandler;
+    }
+    for (const parent of parentNames) {
+      if (!this.knownNames.has(parent)) {
+        throw new UnknownParentError(name, parent);
+      }
+    }
+    const newSteps = [
+      ...this.steps,
+      {
+        allowFailures,
+        handler,
+        name,
+        parentNames,
+        terminal,
+        transform
+      }
+    ];
+    const newKnown = new Set(this.knownNames);
+    newKnown.add(name);
+    return new _FlowBuilder(this.flowName, newSteps, [...this.groups], newKnown);
+  }
+  /**
+   * Declare a typed group for dynamic fan-in.
+   * .group<TOut>("reviews", { dependsOn: ["arbiter"] })
+   */
+  group(name, options = {}) {
+    if (this.knownNames.has(name)) {
+      throw new DuplicateStepError(name);
+    }
+    const dependsOn = options.dependsOn ?? [];
+    for (const dep of dependsOn) {
+      if (!this.knownNames.has(dep)) {
+        throw new UnknownParentError(name, dep);
+      }
+    }
+    const newGroups = [...this.groups, { dependsOn, name }];
+    const newKnown = new Set(this.knownNames);
+    newKnown.add(name);
+    return new _FlowBuilder(
+      this.flowName,
+      [...this.steps],
+      newGroups,
+      newKnown
+    );
+  }
+  /**
+   * Validates the DAG and returns an immutable Flow.
+   */
+  build() {
+    return new Flow(this.flowName, this.steps, this.groups);
+  }
+};
+function flow(name) {
+  return new FlowBuilder(name);
+}
+
+// src/pipeline.ts
+function pipeline(name, steps) {
+  if (steps.length === 0) {
+    throw new Error(`Pipeline "${name}" must have at least one step`);
+  }
+  let builder = flow(`${name}`);
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const handler = step.execute ?? (async (input) => input);
+    const isLast = i === steps.length - 1;
+    if (i === 0) {
+      builder = isLast ? builder.step(step.name, {
+        execute: handler,
+        terminal: true
+      }) : builder.step(step.name, handler);
+    } else {
+      const parents = [steps[i - 1].name];
+      builder = isLast ? builder.step(step.name, parents, {
+        execute: handler,
+        terminal: true
+      }) : builder.step(step.name, parents, handler);
+    }
+  }
+  return { flow: builder.build(), name };
+}
+export {
+  CycleDetectedError,
+  DuplicateStepError,
+  Flow,
+  FlowBuilder,
+  FlowRun,
+  History,
+  StepExecutionError,
+  UnfilledSlotError,
+  UnknownParentError,
+  UnsealedGroupError,
+  createSnapshot,
+  flow,
+  getReadySteps,
+  getReadyWithFailures,
+  getSkippableSteps,
+  group,
+  invokeHandler,
+  isExecutable,
+  isGroupRef,
+  isSubgraphMember,
+  pipeline,
+  topologicalSort,
+  validateAcyclic
+};
+//# sourceMappingURL=index.js.map