@nagi-js/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1285 @@
+// src/internal.ts
+var DEF = "__def";
+function attachDef(meta, def) {
+  return { kind: meta.kind, id: meta.id, [DEF]: def };
+}
+function getDef(step) {
+  const def = step[DEF];
+  if (def === void 0) {
+    throw new Error(
+      `Step "${step.id}" has no internal definition. Construct steps via the builder.`
+    );
+  }
+  return def;
+}
+function resolveNeeds(def, loadOutput) {
+  const result = {};
+  for (const [localKey, upstream] of Object.entries(def.needs)) {
+    if (upstream && typeof upstream === "object" && "id" in upstream && typeof upstream.id === "string") {
+      result[localKey] = loadOutput(upstream.id);
+    }
+  }
+  return result;
+}
+function readSelectedArm(matchId, runState) {
+  for (const fact of runState.facts) {
+    if (fact.kind === "match.arm-selected" && fact.stepId === matchId) {
+      return fact.arm;
+    }
+  }
+  return null;
+}
+function selectArm(def, args) {
+  if (def.mode === "discriminator") {
+    const key = def.on(args);
+    if (def.arms[key] === void 0) {
+      const available = Object.keys(def.arms).join(", ");
+      throw new Error(
+        `match: discriminator returned "${key}" which has no arm (available: ${available || "<none>"})`
+      );
+    }
+    return key;
+  }
+  for (const arm of def.arms) {
+    if (arm.otherwise) return arm.id;
+    if (arm.when?.(args)) return arm.id;
+  }
+  throw new Error(
+    `match: no guard arm matched and no { otherwise: true } fallback was provided`
+  );
+}
+
+// src/builder.ts
+function isDiscriminator(config) {
+  return "cases" in config && "on" in config;
+}
+function makeBuilder() {
+  function task(config) {
+    const def = {
+      kind: "task",
+      needs: config.needs ?? {},
+      ...config.retry !== void 0 ? { retry: config.retry } : {},
+      ...config.timeout !== void 0 ? { timeout: config.timeout } : {},
+      ...config.when !== void 0 ? {
+        when: config.when
+      } : {},
+      run: config.run
+    };
+    return attachDef({ kind: "task", id: "" }, def);
+  }
+  function signal(config) {
+    const def = {
+      kind: "signal",
+      needs: config.needs ?? {},
+      schema: config.schema,
+      ...config.timeout !== void 0 ? { timeout: config.timeout } : {},
+      ...config.when !== void 0 ? {
+        when: config.when
+      } : {}
+    };
+    return attachDef({ kind: "signal", id: "" }, def);
+  }
+  function match(config) {
+    const needs = "needs" in config && config.needs ? config.needs : {};
+    if (isDiscriminator(config)) {
+      const arms2 = {};
+      for (const [caseKey, build] of Object.entries(config.cases)) {
+        const nested = build(
+          makeBuilder()
+        );
+        arms2[caseKey] = { id: caseKey, stepIds: [], _nested: nested };
+      }
+      const def2 = {
+        kind: "match",
+        mode: "discriminator",
+        needs,
+        on: config.on,
+        arms: arms2
+      };
+      return attachDef({ kind: "match", id: "" }, def2);
+    }
+    const guardConfig = config;
+    const arms = [];
+    for (let i = 0; i < guardConfig.arms.length; i++) {
+      const arm = guardConfig.arms[i];
+      const nested = arm.build(makeBuilder());
+      const armId = arm.otherwise ? "otherwise" : `arm${i}`;
+      arms.push({
+        id: armId,
+        ...arm.when !== void 0 ? {
+          when: arm.when
+        } : {},
+        ...arm.otherwise ? { otherwise: true } : {},
+        stepIds: [],
+        _nested: nested
+      });
+    }
+    const def = {
+      kind: "match",
+      mode: "guard",
+      needs,
+      arms
+    };
+    return attachDef({ kind: "match", id: "" }, def);
+  }
+  return { task, signal, match };
+}
+function flow(config) {
+  const builder = makeBuilder();
+  const built = config.build(builder);
+  const idByIdentity = /* @__PURE__ */ new Map();
+  collectIds(built, "", idByIdentity);
+  const finalSteps = {};
+  walkAndRewrite({
+    flowId: config.id,
+    map: built,
+    prefix: "",
+    parentMatch: void 0,
+    idByIdentity,
+    out: finalSteps
+  });
+  return {
+    id: config.id,
+    input: config.input,
+    steps: finalSteps,
+    ...config.output !== void 0 ? { output: config.output } : {}
+  };
+}
+function collectIds(map, prefix, idByIdentity) {
+  for (const [key, step] of Object.entries(map)) {
+    const id = prefix ? `${prefix}.${key}` : key;
+    idByIdentity.set(step, id);
+    const def = step.__def;
+    if (def?.kind === "match") {
+      const arms = def.mode === "discriminator" ? Object.values(def.arms) : def.arms;
+      for (const arm of arms) {
+        if (arm._nested)
+          collectIds(arm._nested, `${id}.${arm.id}`, idByIdentity);
+      }
+    }
+  }
+}
+function walkAndRewrite(args) {
+  const { flowId, map, prefix, parentMatch, idByIdentity, out } = args;
+  for (const [key, step] of Object.entries(map)) {
+    const id = prefix ? `${prefix}.${key}` : key;
+    const def = step.__def;
+    if (def === void 0) {
+      throw new Error(
+        `Flow "${flowId}": step "${id}" has no internal def. Did you return a value not produced by the builder?`
+      );
+    }
+    if (step.id !== "") {
+      throw new Error(
+        `Flow "${flowId}": step "${id}" was produced by a different flow() call (its id is already "${step.id}"). Each flow's build must use only the builder passed to it; steps cannot be shared between flows.`
+      );
+    }
+    const rewrittenNeeds = {};
+    for (const [localKey, upstream] of Object.entries(def.needs)) {
+      const upstreamId = idByIdentity.get(upstream);
+      if (upstreamId === void 0) {
+        const fromOtherFlow = upstream.id !== "";
+        throw new Error(
+          fromOtherFlow ? `Flow "${flowId}": step "${id}" needs an upstream step from a different flow() call (upstream id "${upstream.id}"). Steps cannot be shared between flows.` : `Flow "${flowId}": step "${id}" references an upstream step that was not returned from build(). Add it to the returned object.`
+        );
+      }
+      rewrittenNeeds[localKey] = { ...upstream, id: upstreamId };
+    }
+    if (def.kind === "match") {
+      const armList = def.mode === "discriminator" ? Object.values(def.arms) : def.arms;
+      const finalizedArms = [];
+      for (const arm of armList) {
+        const armPrefix = `${id}.${arm.id}`;
+        const nestedStepIds = [];
+        if (arm._nested) {
+          for (const nestedKey of Object.keys(arm._nested)) {
+            nestedStepIds.push(`${armPrefix}.${nestedKey}`);
+          }
+          walkAndRewrite({
+            flowId,
+            map: arm._nested,
+            prefix: armPrefix,
+            parentMatch: { matchId: id, armId: arm.id },
+            idByIdentity,
+            out
+          });
+        }
+        finalizedArms.push({
+          id: arm.id,
+          ...arm.when !== void 0 ? { when: arm.when } : {},
+          ...arm.otherwise ? { otherwise: true } : {},
+          stepIds: nestedStepIds
+        });
+      }
+      const finalizedDef2 = def.mode === "discriminator" ? {
+        kind: "match",
+        mode: "discriminator",
+        needs: rewrittenNeeds,
+        on: def.on,
+        arms: Object.fromEntries(finalizedArms.map((a) => [a.id, a])),
+        ...parentMatch ? { parentMatch } : {}
+      } : {
+        kind: "match",
+        mode: "guard",
+        needs: rewrittenNeeds,
+        arms: finalizedArms,
+        ...parentMatch ? { parentMatch } : {}
+      };
+      out[id] = attachDef({ kind: "match", id }, finalizedDef2);
+      continue;
+    }
+    const baseRewritten = { ...def, needs: rewrittenNeeds };
+    const finalizedDef = parentMatch ? { ...baseRewritten, parentMatch } : baseRewritten;
+    out[id] = attachDef({ kind: finalizedDef.kind, id }, finalizedDef);
+  }
+}
+
+// src/memory.ts
+var DEFAULT_STORE_LEASE_MS = 6e4;
+var InMemoryStore = class {
+  facts = /* @__PURE__ */ new Map();
+  outputs = /* @__PURE__ */ new Map();
+  onces = /* @__PURE__ */ new Map();
+  leases = /* @__PURE__ */ new Map();
+  leaseMs;
+  constructor(opts = {}) {
+    this.leaseMs = opts.leaseMs ?? DEFAULT_STORE_LEASE_MS;
+  }
+  async appendFact(runId, fact) {
+    const list = this.facts.get(runId) ?? [];
+    list.push(fact);
+    this.facts.set(runId, list);
+  }
+  async tryStartRun(runId, fact) {
+    if (this.facts.has(runId)) {
+      return { started: false };
+    }
+    this.facts.set(runId, [fact]);
+    return { started: true };
+  }
+  async loadRunState(runId) {
+    return projectRunState(runId, this.facts.get(runId) ?? []);
+  }
+  async claimStep(runId, stepId, attempt) {
+    const key = `${runId}::${stepId}::${attempt}`;
+    const now = Date.now();
+    const existing = this.leases.get(key);
+    if (existing && existing.expiresAt > now) {
+      return null;
+    }
+    const token = `lease-${crypto.randomUUID()}`;
+    this.leases.set(key, { token, expiresAt: now + this.leaseMs });
+    return token;
+  }
+  async completeStep(runId, stepId, output, fact) {
+    this.outputs.set(`${runId}::${stepId}`, output);
+    await this.appendFact(runId, fact);
+  }
+  async failStep(runId, _stepId, _error, fact) {
+    await this.appendFact(runId, fact);
+  }
+  async getStepOutput(runId, stepId) {
+    return this.outputs.get(`${runId}::${stepId}`) ?? null;
+  }
+  async recordOnce(runId, stepId, scope, value) {
+    this.onces.set(`${runId}::${stepId}::${scope}`, value);
+  }
+  async getOnce(runId, stepId, scope) {
+    return this.onces.get(`${runId}::${stepId}::${scope}`) ?? null;
+  }
+  async runStep(runId, stepId, _attempt, body) {
+    const result = await body(void 0);
+    if (result.fact.kind === "step.completed") {
+      await this.completeStep(runId, stepId, result.output, result.fact);
+    } else {
+      await this.failStep(runId, stepId, result.fact.error, result.fact);
+    }
+    return result.output;
+  }
+};
+function projectRunState(runId, facts) {
+  let flowId = "";
+  let status = "pending";
+  const steps = {};
+  for (const fact of facts) {
+    switch (fact.kind) {
+      case "flow.started":
+        flowId = fact.flowId;
+        status = "running";
+        break;
+      case "flow.completed":
+        status = "completed";
+        break;
+      case "flow.failed":
+        status = "failed";
+        break;
+      case "step.started":
+        steps[fact.stepId] = {
+          stepId: fact.stepId,
+          status: "running",
+          attempts: fact.attempt
+        };
+        break;
+      case "step.completed":
+        steps[fact.stepId] = {
+          stepId: fact.stepId,
+          status: "completed",
+          attempts: fact.attempt,
+          output: fact.output
+        };
+        break;
+      case "step.failed":
+        steps[fact.stepId] = {
+          stepId: fact.stepId,
+          status: "failed",
+          attempts: fact.attempt,
+          error: fact.error
+        };
+        break;
+      case "step.skipped":
+        steps[fact.stepId] = {
+          stepId: fact.stepId,
+          status: "skipped",
+          attempts: 0
+        };
+        break;
+    }
+  }
+  return { runId, flowId, status, steps, facts };
+}
+var DEFAULT_QUEUE_LEASE_MS = 6e4;
+var InMemoryQueue = class {
+  pending = [];
+  leased = /* @__PURE__ */ new Map();
+  leaseMs;
+  constructor(opts = {}) {
+    this.leaseMs = opts.leaseMs ?? DEFAULT_QUEUE_LEASE_MS;
+  }
+  async enqueue(runId, stepId, opts) {
+    const now = Date.now();
+    const item = {
+      receipt: crypto.randomUUID(),
+      runId,
+      stepId,
+      payload: opts?.payload ?? null,
+      attempt: opts?.attempt ?? 1,
+      enqueuedAt: now,
+      visibleAt: now + (opts?.delayMs ?? 0)
+    };
+    this.pending.push(item);
+  }
+  async dequeue(opts) {
+    const now = Date.now();
+    const claimed = [];
+    for (let i = 0; i < this.pending.length && claimed.length < opts.count; i++) {
+      const item = this.pending[i];
+      if (item === void 0) continue;
+      if (item.visibleAt > now) continue;
+      const next = { ...item, visibleAt: now + this.leaseMs };
+      this.pending.splice(i, 1);
+      i--;
+      this.leased.set(item.receipt, next);
+      claimed.push(item);
+    }
+    return claimed;
+  }
+  async ack(receipt) {
+    this.leased.delete(receipt);
+  }
+  async nack(receipt, opts) {
+    const item = this.leased.get(receipt);
+    if (!item) return;
+    this.leased.delete(receipt);
+    const requeued = {
+      ...item,
+      visibleAt: Date.now() + (opts?.delayMs ?? 0)
+    };
+    this.pending.push(requeued);
+  }
+  async extend(receipt, leaseMs) {
+    const item = this.leased.get(receipt);
+    if (!item) return;
+    this.leased.set(receipt, { ...item, visibleAt: Date.now() + leaseMs });
+  }
+};
+var InMemoryClock = class {
+  timers = /* @__PURE__ */ new Map();
+  trigger;
+  constructor(opts = {}) {
+    this.trigger = opts.trigger;
+  }
+  now() {
+    return /* @__PURE__ */ new Date();
+  }
+  async sleep(ms, signal) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new Error("aborted");
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason ?? new Error("aborted"));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  async schedule(at, runId, stepId) {
+    const key = `${runId}::${stepId}`;
+    const existing = this.timers.get(key);
+    if (existing !== void 0) clearTimeout(existing);
+    const delay = Math.max(0, at.getTime() - Date.now());
+    const handle = setTimeout(() => {
+      this.timers.delete(key);
+      this.trigger?.fire(runId);
+    }, delay);
+    this.timers.set(key, handle);
+  }
+  /** Clear any pending scheduled timers. Call from test teardown. */
+  dispose() {
+    for (const t of this.timers.values()) clearTimeout(t);
+    this.timers.clear();
+  }
+};
+var InMemoryTrigger = class {
+  handlers = [];
+  subscribe(handler) {
+    this.handlers.push(handler);
+    return () => {
+      this.handlers = this.handlers.filter((h) => h !== handler);
+    };
+  }
+  /**
+   * Test-only: synchronously dispatch a wake-up to all subscribers.
+   * Real triggers fire from a Store change (NOTIFY/LISTEN, polling, etc.).
+   */
+  fire(runId) {
+    for (const h of this.handlers) h(runId);
+  }
+};
+
+// src/idempotency.ts
+function makeIdempotencyKey(runId, stepId) {
+  return (scope) => `nagi:${runId}:${stepId}:${scope}`;
+}
+function makeOnce(args) {
+  const { runId, stepId, store } = args;
+  return async function once(scope, fn) {
+    const cached = await store.getOnce(runId, stepId, scope);
+    if (cached !== null) return cached;
+    const value = await fn();
+    await store.recordOnce(runId, stepId, scope, value);
+    return value;
+  };
+}
+
+// src/scheduler.ts
+function nextRunnable(args) {
+  const { flow: flow2, runState, input } = args;
+  const runnable = [];
+  const skip = [];
+  for (const [stepId, step] of Object.entries(flow2.steps)) {
+    const state = runState.steps[stepId];
+    if (state !== void 0 && state.status !== "pending") continue;
+    const def = getDef(step);
+    const parentGate = checkParentMatch(def, runState);
+    if (parentGate === "blocked") continue;
+    if (parentGate === "transitive-skip") {
+      skip.push({ stepId, reason: "transitive" });
+      continue;
+    }
+    const upstreamCheck = checkUpstream(def, runState);
+    if (upstreamCheck === "blocked") continue;
+    if (upstreamCheck === "transitive-skip") {
+      skip.push({ stepId, reason: "transitive" });
+      continue;
+    }
+    const when = def.kind === "match" ? void 0 : def.when;
+    if (when) {
+      const needs = resolveNeeds(
+        def,
+        (id) => runState.steps[id]?.output ?? null
+      );
+      const shouldRun = when({ input, needs });
+      if (!shouldRun) {
+        skip.push({ stepId, reason: "when-false" });
+        continue;
+      }
+    }
+    runnable.push(stepId);
+  }
+  return { runnable, skip };
+}
+function checkUpstream(def, runState) {
+  for (const upstream of Object.values(def.needs)) {
+    if (!upstream || typeof upstream !== "object" || !("id" in upstream) || typeof upstream.id !== "string") {
+      continue;
+    }
+    const upstreamState = runState.steps[upstream.id];
+    if (upstreamState === void 0) return "blocked";
+    if (upstreamState.status === "completed") continue;
+    if (upstreamState.status === "skipped" || upstreamState.status === "failed") {
+      return "transitive-skip";
+    }
+    return "blocked";
+  }
+  return "ready";
+}
+function checkParentMatch(def, runState) {
+  if (!def.parentMatch) return "ready";
+  const { matchId, armId } = def.parentMatch;
+  const parentState = runState.steps[matchId];
+  if (parentState?.status === "failed" || parentState?.status === "skipped") {
+    return "transitive-skip";
+  }
+  const selected = readSelectedArm(matchId, runState);
+  if (selected === null) return "blocked";
+  return selected === armId ? "ready" : "transitive-skip";
+}
+function aggregateMatch(matchId, flow2, runState) {
+  const step = flow2.steps[matchId];
+  if (!step) return { kind: "pending" };
+  const def = getDef(step);
+  if (def.kind !== "match") return { kind: "pending" };
+  const selected = readSelectedArm(matchId, runState);
+  if (selected === null) return { kind: "pending" };
+  const arm = def.mode === "discriminator" ? def.arms[selected] : def.arms.find((a) => a.id === selected);
+  if (!arm) return { kind: "pending" };
+  const output = {};
+  let allTerminal = true;
+  const stripPrefix = `${matchId}.${arm.id}.`;
+  for (const stepId of arm.stepIds) {
+    const state = runState.steps[stepId];
+    if (state === void 0 || state.status === "pending" || state.status === "running") {
+      allTerminal = false;
+      continue;
+    }
+    if (state.status === "failed") {
+      return { kind: "fail-fast", failedStepId: stepId };
+    }
+    const localKey = stepId.startsWith(stripPrefix) ? stepId.slice(stripPrefix.length) : stepId;
+    output[localKey] = state.status === "completed" ? state.output ?? null : null;
+  }
+  if (!allTerminal) return { kind: "pending" };
+  return { kind: "complete", output };
+}
+function flowTermination(flow2, runState) {
+  let done = true;
+  let failed = false;
+  for (const stepId of Object.keys(flow2.steps)) {
+    const state = runState.steps[stepId];
+    if (state === void 0 || state.status === "pending" || state.status === "running") {
+      done = false;
+      break;
+    }
+    if (state.status === "failed") failed = true;
+  }
+  return { done, failed };
+}
+function extractInput(runState) {
+  for (const fact of runState.facts) {
+    if (fact.kind === "flow.started") return fact.input;
+  }
+  throw new Error(
+    "No flow.started fact in run \u2014 was the run initialized via wf.start?"
+  );
+}
+
+// src/dispatch.ts
+var DEFAULT_RETRY = {
+  maxAttempts: 3,
+  backoff: "exponential",
+  initialDelayMs: 1e3,
+  maxDelayMs: 6e4
+};
+async function dispatchMessage(deps, message) {
+  const { store, queue, clock } = deps;
+  const { runId, stepId, attempt } = message;
+  const flow2 = await deps.flowFor(runId);
+  const step = flow2.steps[stepId];
+  if (!step) {
+    deps.logger?.warn(
+      `dispatch: step "${stepId}" not in flow "${flow2.id}"; ack and skip`
+    );
+    await queue.ack(message.receipt);
+    return;
+  }
+  const def = getDef(step);
+  const preState = await store.loadRunState(runId);
+  const preStep = preState.steps[stepId];
+  if (preStep && (preStep.status === "completed" || preStep.status === "failed" || preStep.status === "skipped")) {
+    await queue.ack(message.receipt);
+    return;
+  }
+  const claim = await store.claimStep(runId, stepId, attempt);
+  if (claim === null) {
+    await queue.ack(message.receipt);
+    return;
+  }
+  await store.appendFact(runId, {
+    kind: "step.started",
+    runId,
+    stepId,
+    attempt,
+    at: clock.now()
+  });
+  const startEventInput = def.kind === "task" ? extractInput(await store.loadRunState(runId)) : null;
+  await deps.hooks?.onStepStart?.({
+    runId,
+    flowId: flow2.id,
+    stepId,
+    attempt,
+    kind: def.kind,
+    input: startEventInput,
+    at: clock.now()
+  });
+  const startedAt = Date.now();
+  try {
+    if (def.kind === "task") {
+      const output = await executeTask({
+        deps,
+        message,
+        def,
+        runId,
+        stepId,
+        attempt
+      });
+      await deps.hooks?.onStepComplete?.({
+        runId,
+        flowId: flow2.id,
+        stepId,
+        attempt,
+        kind: "task",
+        output,
+        durationMs: Date.now() - startedAt,
+        at: clock.now()
+      });
+      await advance(deps, runId);
+    } else if (def.kind === "signal") {
+      await queue.ack(message.receipt);
+      return;
+    } else if (def.kind === "match") {
+      await executeMatch({ deps, message, def, runId, stepId, attempt });
+      await advance(deps, runId);
+    }
+  } catch (err) {
+    await handleStepError({
+      deps,
+      flow: flow2,
+      message,
+      def,
+      runId,
+      stepId,
+      attempt,
+      err
+    });
+  }
+}
+async function executeTask(args) {
+  const { deps, message, def, runId, stepId, attempt } = args;
+  if (def.kind !== "task") {
+    throw new Error(`executeTask called with non-task def (kind: ${def.kind})`);
+  }
+  const { store, queue, clock } = deps;
+  const runState = await store.loadRunState(runId);
+  const input = extractInput(runState);
+  const needs = resolveNeeds(def, (id) => runState.steps[id]?.output ?? null);
+  const output = await store.runStep(
+    runId,
+    stepId,
+    attempt,
+    async (tx) => {
+      const ctx = makeStepCtx({
+        runId,
+        stepId,
+        attempt,
+        input,
+        store,
+        clock,
+        tx,
+        ...deps.logger !== void 0 ? { logger: deps.logger } : {}
+      });
+      const out = await def.run({ input, needs, ctx });
+      const fact = {
+        kind: "step.completed",
+        runId,
+        stepId,
+        attempt,
+        output: out,
+        at: clock.now()
+      };
+      return { output: out, fact };
+    }
+  );
+  await queue.ack(message.receipt);
+  return output;
+}
+async function executeMatch(args) {
+  const { deps, message, def, runId, stepId } = args;
+  const { store, queue, clock } = deps;
+  const runState = await store.loadRunState(runId);
+  const input = extractInput(runState);
+  const needs = resolveNeeds(def, (id) => runState.steps[id]?.output ?? null);
+  const armId = selectArm(def, { input, needs });
+  await store.appendFact(runId, {
+    kind: "match.arm-selected",
+    runId,
+    stepId,
+    arm: armId,
+    at: clock.now()
+  });
+  await queue.ack(message.receipt);
+}
+async function handleStepError(args) {
+  const { deps, flow: flow2, message, def, runId, stepId, attempt, err } = args;
+  const { store, queue, clock } = deps;
+  const error = serializeError(err);
+  const policy = def.kind === "task" && def.retry ? def.retry : deps.defaultRetry ?? DEFAULT_RETRY;
+  const shouldRetry = attempt < policy.maxAttempts && retryAllows(policy, err);
+  if (shouldRetry) {
+    const delayMs = computeBackoff(policy, attempt);
+    await store.appendFact(runId, {
+      kind: "step.retried",
+      runId,
+      stepId,
+      attempt,
+      nextAttemptAt: new Date(Date.now() + delayMs),
+      at: clock.now()
+    });
+    await deps.hooks?.onStepRetry?.({
+      runId,
+      flowId: flow2.id,
+      stepId,
+      attempt,
+      kind: def.kind,
+      error,
+      nextAttemptAt: new Date(Date.now() + delayMs),
+      at: clock.now()
+    });
+    await queue.enqueue(runId, stepId, { attempt: attempt + 1, delayMs });
+    await queue.ack(message.receipt);
+    return;
+  }
+  const fact = {
+    kind: "step.failed",
+    runId,
+    stepId,
+    attempt,
+    error,
+    at: clock.now()
+  };
+  await store.failStep(runId, stepId, error, fact);
+  await deps.hooks?.onStepError?.({
+    runId,
+    flowId: flow2.id,
+    stepId,
+    attempt,
+    kind: def.kind,
+    error,
+    at: clock.now()
+  });
+  await queue.ack(message.receipt);
+  await advance(deps, runId);
+}
+var MAX_ADVANCE_ITERS = 1024;
+async function advance(deps, runId) {
+  const { store, queue, clock } = deps;
+  const flow2 = await deps.flowFor(runId);
+  for (let iter = 0; iter < MAX_ADVANCE_ITERS; iter++) {
+    const runState = await store.loadRunState(runId);
+    const promoted = await promoteMatches({ deps, flow: flow2, runState });
+    if (promoted) continue;
+    const termination = flowTermination(flow2, runState);
+    if (termination.done) {
+      const last2 = runState.facts[runState.facts.length - 1];
+      const flowAlreadyTerminal = last2 !== void 0 && (last2.kind === "flow.completed" || last2.kind === "flow.failed");
+      if (!flowAlreadyTerminal) {
+        if (termination.failed) {
+          const failedStep = Object.values(runState.steps).find(
+            (s) => s.status === "failed"
+          );
+          await store.appendFact(runId, {
+            kind: "flow.failed",
+            runId,
+            error: failedStep?.error ?? {
+              name: "Error",
+              message: "step failed"
+            },
+            at: clock.now()
+          });
+          await deps.hooks?.onFlowError?.({
+            runId,
+            flowId: flow2.id,
+            error: failedStep?.error ?? {
+              name: "Error",
+              message: "step failed"
+            },
+            at: clock.now()
+          });
+        } else {
+          let flowOutput = null;
+          if (flow2.output !== void 0) {
+            const stepOutputs = {};
+            for (const [sid, sstate] of Object.entries(runState.steps)) {
+              if (sstate.output !== void 0) stepOutputs[sid] = sstate.output;
+            }
+            flowOutput = flow2.output(stepOutputs);
+          }
+          await store.appendFact(runId, {
+            kind: "flow.completed",
+            runId,
+            output: flowOutput,
+            at: clock.now()
+          });
+          await deps.hooks?.onFlowComplete?.({
+            runId,
+            flowId: flow2.id,
+            output: flowOutput,
+            at: clock.now()
+          });
+        }
+      }
+      return;
+    }
+    const input = extractInput(runState);
+    const decision = nextRunnable({ flow: flow2, runState, input });
+    if (decision.skip.length === 0 && decision.runnable.length === 0) return;
+    for (const { stepId, reason } of decision.skip) {
+      await store.appendFact(runId, {
+        kind: "step.skipped",
+        runId,
+        stepId,
+        reason,
+        at: clock.now()
+      });
+    }
+    for (const stepId of decision.runnable) {
+      await queue.enqueue(runId, stepId);
+    }
+    if (decision.runnable.length > 0) {
+      return;
+    }
+  }
+  const cycleError = {
+    name: "NagiCycleError",
+    message: `advance exceeded ${MAX_ADVANCE_ITERS} iterations \u2014 likely a cycle or infinite skip loop in flow "${flow2.id}"`
+  };
+  const last = (await store.loadRunState(runId)).facts.slice(-1)[0];
+  const alreadyTerminal = last !== void 0 && (last.kind === "flow.completed" || last.kind === "flow.failed");
+  if (!alreadyTerminal) {
+    await store.appendFact(runId, {
+      kind: "flow.failed",
+      runId,
+      error: cycleError,
+      at: clock.now()
+    });
+    await deps.hooks?.onFlowError?.({
+      runId,
+      flowId: flow2.id,
+      error: cycleError,
+      at: clock.now()
+    });
+  }
+}
+async function promoteMatches(args) {
+  const { deps, flow: flow2, runState } = args;
+  const { store, clock } = deps;
+  let promoted = false;
+  for (const [matchId, step] of Object.entries(flow2.steps)) {
+    const def = getDef(step);
+    if (def.kind !== "match") continue;
+    const state = runState.steps[matchId];
+    if (state?.status !== "running") continue;
+    const agg = aggregateMatch(matchId, flow2, runState);
+    if (agg.kind === "pending") continue;
+    const attempt = state.attempts > 0 ? state.attempts : 1;
+    if (agg.kind === "fail-fast") {
+      const failedNested = runState.steps[agg.failedStepId];
+      const error = failedNested?.error ?? {
+        name: "Error",
+        message: `match "${matchId}": chosen-arm step "${agg.failedStepId}" failed`
+      };
+      const fact2 = {
+        kind: "step.failed",
+        runId: runState.runId,
+        stepId: matchId,
+        attempt,
+        error,
+        at: clock.now()
+      };
+      await store.failStep(runState.runId, matchId, error, fact2);
+      await deps.hooks?.onStepError?.({
+        runId: runState.runId,
+        flowId: flow2.id,
+        stepId: matchId,
+        attempt,
+        kind: "match",
+        error,
+        at: clock.now()
+      });
+      promoted = true;
+      continue;
+    }
+    const fact = {
+      kind: "step.completed",
+      runId: runState.runId,
+      stepId: matchId,
+      attempt,
+      output: agg.output,
+      at: clock.now()
+    };
+    await store.completeStep(runState.runId, matchId, agg.output, fact);
+    await deps.hooks?.onStepComplete?.({
+      runId: runState.runId,
+      flowId: flow2.id,
+      stepId: matchId,
+      attempt,
+      kind: "match",
+      output: agg.output,
+      durationMs: 0,
+      at: clock.now()
+    });
+    promoted = true;
+  }
+  return promoted;
+}
+function makeStepCtx(args) {
+  const { runId, stepId, attempt, input, store, clock, tx } = args;
+  const ac = new AbortController();
+  return {
+    input,
+    runId,
+    stepId,
+    attempt,
+    signal: ac.signal,
+    now: () => clock.now(),
+    // `tx` is supplied by `Store.runStep` — for adapters with no real
+    // transaction (in-memory) it is `undefined as Tx`, and handlers that
+    // touch `ctx.tx` will throw on the first call. Adapters that need
+    // typed transactional clients (e.g. `@nagi-js/postgres`) augment
+    // `Register.tx` and pass a real Kysely transaction here.
+    tx,
+    logger: args.logger ?? consoleLogger(),
+    once: makeOnce({ runId, stepId, store }),
+    idempotencyKey: makeIdempotencyKey(runId, stepId)
+  };
+}
+function consoleLogger() {
+  return {
+    debug: (m, a) => console.debug(m, a),
+    info: (m, a) => console.info(m, a),
+    warn: (m, a) => console.warn(m, a),
+    error: (m, a) => console.error(m, a)
+  };
+}
+function computeBackoff(policy, attempt) {
+  const initial = policy.initialDelayMs ?? 1e3;
+  const max = policy.maxDelayMs ?? 6e4;
+  switch (policy.backoff) {
+    case "exponential":
+      return Math.min(initial * 2 ** Math.max(0, attempt - 1), max);
+    case "linear":
+      return Math.min(initial * Math.max(1, attempt), max);
+    case "fixed":
+      return Math.min(initial, max);
+  }
+}
+function retryAllows(policy, err) {
+  if (!policy.retryOn) return true;
+  return policy.retryOn(err);
+}
+function serializeError(err) {
+  if (err instanceof Error) {
+    return {
+      name: err.name,
+      message: err.message,
+      ...err.stack !== void 0 ? { stack: err.stack } : {}
+    };
+  }
+  return { name: "Error", message: String(err) };
+}
+
+// src/worker.ts
+var DEFAULT_CONCURRENCY = 4;
+var DEFAULT_POLL_INTERVAL_MS = 1e3;
+function makeWorker(deps, config) {
+  return new WorkerImpl(deps, config);
+}
+var WorkerImpl = class {
+  constructor(deps, config) {
+    this.deps = deps;
+    this.concurrency = Math.max(1, config?.concurrency ?? DEFAULT_CONCURRENCY);
+    this.pollIntervalMs = config?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.signal = config?.signal;
+  }
+  deps;
+  inFlight = 0;
+  concurrency;
+  pollIntervalMs;
+  signal;
+  async run() {
+    while (!this.aborted()) {
+      const slots = this.concurrency - this.inFlight;
+      if (slots <= 0) {
+        await this.sleep(50);
+        continue;
+      }
+      const messages = await this.dequeue(slots);
+      if (messages.length === 0) {
+        await this.sleep(this.pollIntervalMs);
+        continue;
+      }
+      for (const msg of messages) this.fire(msg);
+    }
+    await this.drain();
+  }
+  async runOnce(opts) {
+    const limit = Math.max(1, opts?.maxSteps ?? this.concurrency);
+    let processed = 0;
+    while (processed < limit && !this.aborted()) {
+      const remaining = limit - processed;
+      const messages = await this.dequeue(
+        Math.min(remaining, this.concurrency)
+      );
+      if (messages.length === 0) break;
+      await Promise.all(messages.map((m) => this.dispatchSafely(m)));
+      processed += messages.length;
+    }
+    return { processed };
+  }
+  async runUntilEmpty(opts) {
+    const deadline = opts?.deadline;
+    let processed = 0;
+    while (!this.aborted()) {
+      if (deadline !== void 0 && Date.now() >= deadline) break;
+      const messages = await this.dequeue(this.concurrency);
+      if (messages.length === 0) break;
+      await Promise.all(messages.map((m) => this.dispatchSafely(m)));
+      processed += messages.length;
+    }
+    return { processed };
+  }
+  async dequeue(count) {
+    return this.deps.queue.dequeue({ count: Math.max(1, count) });
+  }
+  fire(msg) {
+    this.inFlight++;
+    void this.dispatchSafely(msg).finally(() => {
+      this.inFlight = Math.max(0, this.inFlight - 1);
+    });
+  }
+  async dispatchSafely(msg) {
+    try {
+      await dispatchMessage(this.deps, msg);
+    } catch (err) {
+      this.deps.logger?.error("worker.dispatch threw uncaught", {
+        error: String(err)
+      });
+      try {
+        await this.deps.queue.nack(msg.receipt);
+      } catch {
+      }
+    }
+  }
+  async drain() {
+    while (this.inFlight > 0) {
+      await this.deps.clock.sleep(50);
+    }
+  }
+  aborted() {
+    return this.signal?.aborted === true;
+  }
+  async sleep(ms) {
+    try {
+      await this.deps.clock.sleep(ms, this.signal);
+    } catch {
+    }
+  }
+};
+
+// src/runtime.ts
+var NagiValidationError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(issues.map((i) => i.message).join("; "));
+    this.name = "NagiValidationError";
+    this.issues = issues;
+  }
+};
+var NagiRuntimeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NagiRuntimeError";
+  }
+};
+function nagi(config) {
+  const clock = config.clock ?? new InMemoryClock();
+  const flowsById = /* @__PURE__ */ new Map();
+  for (const f of config.flows) {
+    if (flowsById.has(f.id)) {
+      throw new NagiRuntimeError(
+        `Duplicate flow id "${f.id}" passed to nagi()`
+      );
+    }
+    flowsById.set(f.id, f);
+  }
+  async function flowFor(runId) {
+    const runState = await config.store.loadRunState(runId);
+    const flow2 = flowsById.get(runState.flowId);
+    if (!flow2) {
+      throw new NagiRuntimeError(
+        `Run ${runId} references flow "${runState.flowId}" which is not registered with nagi().`
+      );
+    }
+    return flow2;
+  }
+  const dispatchDeps = {
+    flowFor,
+    store: config.store,
+    queue: config.queue,
+    clock,
+    ...config.hooks !== void 0 ? { hooks: config.hooks } : {},
+    ...config.logger !== void 0 ? { logger: config.logger } : {},
+    ...config.defaultRetry !== void 0 ? { defaultRetry: config.defaultRetry } : {}
+  };
+  return {
+    async start(flow2, input, opts) {
+      if (!flowsById.has(flow2.id)) {
+        throw new NagiRuntimeError(
+          `Flow "${flow2.id}" not registered with nagi(). Pass it to flows[].`
+        );
+      }
+      let runId;
+      if (opts?.runId !== void 0) {
+        if (typeof opts.runId !== "string" || opts.runId.length === 0) {
+          throw new NagiValidationError([
+            {
+              message: "opts.runId must be a non-empty string",
+              path: ["runId"]
+            }
+          ]);
+        }
+        runId = opts.runId;
+      } else {
+        runId = mintRunId();
+      }
+      const validated = await validate(flow2.input, input);
+      const startedAt = clock.now();
+      const fact = {
+        kind: "flow.started",
+        runId,
+        flowId: flow2.id,
+        input: validated,
+        at: startedAt
+      };
+      const { started } = await config.store.tryStartRun(runId, fact);
+      if (!started) {
+        return runId;
+      }
+      await config.hooks?.onFlowStart?.({
+        runId,
+        flowId: flow2.id,
+        input: validated,
+        at: startedAt
+      });
+      await advance(dispatchDeps, runId);
+      return runId;
+    },
+    async signal(runId, stepName, payload) {
+      const runState = await config.store.loadRunState(runId);
+      const flow2 = flowsById.get(runState.flowId);
+      if (!flow2) {
+        throw new NagiRuntimeError(
+          `Run ${runId} references flow "${runState.flowId}" which is not registered with nagi().`
+        );
+      }
+      const step = flow2.steps[stepName];
+      if (!step) {
+        throw new NagiRuntimeError(
+          `Flow "${flow2.id}" has no step named "${stepName}".`
+        );
+      }
+      const def = getDef(step);
+      if (def.kind !== "signal") {
+        throw new NagiRuntimeError(
+          `Step "${stepName}" is a ${def.kind}, not a signal.`
+        );
+      }
+      const stepState = runState.steps[stepName];
+      if (stepState?.status !== "running") {
+        throw new NagiRuntimeError(
+          `Step "${stepName}" is not waiting for signal (status: ${stepState?.status ?? "pending"}).`
+        );
+      }
+      const validated = await validate(def.schema, payload);
+      const attempt = stepState.attempts > 0 ? stepState.attempts : 1;
+      await config.store.appendFact(runId, {
+        kind: "signal.received",
+        runId,
+        stepId: stepName,
+        payload: validated,
+        at: clock.now()
+      });
+      const completedFact = {
+        kind: "step.completed",
+        runId,
+        stepId: stepName,
+        attempt,
+        output: validated,
+        at: clock.now()
+      };
+      await config.store.completeStep(
+        runId,
+        stepName,
+        validated,
+        completedFact
+      );
+      await config.hooks?.onSignalReceived?.({
+        runId,
+        flowId: flow2.id,
+        stepId: stepName,
+        attempt,
+        kind: "signal",
+        payload: validated,
+        at: clock.now()
+      });
+      await advance(dispatchDeps, runId);
+    },
+    worker(workerConfig) {
+      if (config.flows.length === 0) {
+        throw new NagiRuntimeError(
+          "nagi(): no flows registered \u2014 cannot create a worker."
+        );
+      }
+      return makeWorker({ ...dispatchDeps, clock }, workerConfig);
+    },
+    async replay(runId, opts = { mode: "continue" }) {
+      const runState = await config.store.loadRunState(runId);
+      const flow2 = flowsById.get(runState.flowId);
+      if (!flow2) {
+        throw new NagiRuntimeError(
+          `Run ${runId} references flow "${runState.flowId}" which is not registered with nagi().`
+        );
+      }
+      if (opts.mode === "inspect") return;
+      await advance(dispatchDeps, runId);
+    }
+  };
+}
+function mintRunId() {
+  return `run-${crypto.randomUUID()}`;
+}
+async function validate(schema, value) {
+  const result = await schema["~standard"].validate(value);
+  if ("issues" in result && result.issues !== void 0) {
+    throw new NagiValidationError(result.issues);
+  }
+  return result.value;
+}
+
+export { InMemoryClock, InMemoryQueue, InMemoryStore, InMemoryTrigger, NagiRuntimeError, NagiValidationError, flow, nagi, projectRunState };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map