@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/chunk-CGHORL6G.js

@@ -0,0 +1,579 @@
+import {
+  DEFERRED_TOPIC,
+  PROMPTS_TOPIC,
+  RESPONSES_TOPIC,
+  subscription
+} from "./chunk-Q3EYOCZB.js";
+import {
+  domainMeta
+} from "./chunk-FMPF42Q4.js";
+import {
+  createAuditLog,
+  mutate
+} from "./chunk-BXGZFGZ4.js";
+
+// src/utils/orchestration/human-input.ts
+import { COMPLETE, DATA, node, wallClockNs } from "@graphrefly/pure-ts/core";
+import { fromAny } from "@graphrefly/pure-ts/extra";
+function humanInput(opts) {
+  const { hub, prompt, schema, idGenerator } = opts;
+  const promptNode = fromAny(prompt);
+  const promptsTopic = hub.topic(PROMPTS_TOPIC);
+  const responsesTopic = hub.topic(RESPONSES_TOPIC);
+  const nextId = idGenerator ?? defaultIdGenerator();
+  return node(
+    (_data, a) => {
+      let activeCorrelationId;
+      let respUnsub;
+      const promptUnsub = promptNode.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (m[0] === COMPLETE) {
+            respUnsub?.();
+            respUnsub = void 0;
+            a.down([[COMPLETE]]);
+            return;
+          }
+          if (m[0] !== DATA) continue;
+          const promptStr = m[1];
+          respUnsub?.();
+          respUnsub = void 0;
+          const correlationId = nextId();
+          activeCorrelationId = correlationId;
+          const responseCursorAtSubscribe = responsesTopic.events.cache?.length ?? 0;
+          const envelope = {
+            id: correlationId,
+            correlationId,
+            payload: { prompt: promptStr },
+            ...schema != null && { schema }
+          };
+          promptsTopic.publish(envelope);
+          respUnsub = responsesTopic.events.subscribe((rspMsgs) => {
+            for (const rm of rspMsgs) {
+              if (rm[0] !== DATA) continue;
+              const arr = rm[1];
+              for (let i = responseCursorAtSubscribe; i < arr.length; i++) {
+                const env = arr[i];
+                if (env.correlationId === activeCorrelationId) {
+                  a.emit(env.payload);
+                  respUnsub?.();
+                  respUnsub = void 0;
+                  return;
+                }
+              }
+            }
+          });
+        }
+      });
+      return () => {
+        promptUnsub();
+        respUnsub?.();
+      };
+    },
+    {
+      describeKind: "derived",
+      name: "humanInput",
+      // Each new prompt may produce a structurally-equal response (e.g.
+      // from a deterministic UI mock) — disable framework dedup so
+      // repeat emissions propagate. Same precedent as `agent.out`.
+      equals: () => false
+    }
+  );
+}
+function defaultIdGenerator() {
+  let n = 0;
+  const base = wallClockNs().toString(36);
+  return () => {
+    n += 1;
+    return `humanInput-${base}-${n.toString(36)}`;
+  };
+}
+
+// src/utils/orchestration/pipeline-graph.ts
+import {
+  batch,
+  COMPLETE as COMPLETE2,
+  DATA as DATA2,
+  ERROR,
+  factoryTag,
+  node as node2,
+  placeholderArgs,
+  RESOLVED,
+  wallClockNs as wallClockNs2
+} from "@graphrefly/pure-ts/core";
+import { Graph } from "@graphrefly/pure-ts/graph";
+function meta(kind, extra) {
+  return domainMeta("orchestration", kind, extra);
+}
+var decisionKeyOf = (d) => d.action;
+var PipelineGraph = class extends Graph {
+  // -- task -----------------------------------------------------------------
+  /**
+   * Register a workflow task (`node` + auto-add). String deps resolve via
+   * `this.resolve(path)`; Node deps via {@link Graph.nameOf} O(1) lookup.
+   *
+   * `run` receives `(data: readonly unknown[], ctx)` — the snapshot of latest
+   * values per dep (same shape as the old `DerivedFn` sugar).
+   */
+  task(name, run, opts = {}) {
+    const deps = (opts.deps ?? []).map((d) => this._resolveStep(d));
+    const step = node2(
+      deps,
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        const result = run(data, ctx);
+        if (result !== void 0 && result !== null) actions.emit(result);
+      },
+      {
+        name,
+        describeKind: "derived",
+        meta: meta("task", opts.meta)
+      }
+    );
+    this.add(step, { name });
+    return step;
+  }
+  // -- classify (n-way; replaces binary `branch`) --------------------------
+  classify(name, source, tagger, opts = {}) {
+    const src = this._resolveStep(source);
+    const step = node2(
+      [src],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        const value = data[0];
+        try {
+          actions.emit({ tag: tagger(value), value });
+        } catch (error) {
+          actions.emit({ tag: "error", value, error });
+        }
+      },
+      {
+        name,
+        describeKind: "derived",
+        meta: meta("classify", opts.meta)
+      }
+    );
+    this.add(step, { name });
+    return step;
+  }
+  // -- combine (keyed-record fan-in; replaces positional `join`) -----------
+  combine(name, deps, opts = {}) {
+    const keys = Object.keys(deps);
+    const nodes = keys.map((k) => this._resolveStep(deps[k]));
+    const step = node2(
+      nodes,
+      (batchData, actions, ctx) => {
+        const values = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        const out = {};
+        for (let i = 0; i < keys.length; i++) {
+          out[keys[i]] = values[i];
+        }
+        actions.emit(out);
+      },
+      {
+        name,
+        describeKind: "derived",
+        meta: meta("combine", opts.meta)
+      }
+    );
+    this.add(step, { name });
+    return step;
+  }
+  // -- approvalGate ---------------------------------------------------------
+  approvalGate(name, source, opts = {}) {
+    const maxPending = opts.maxPending ?? 1e3;
+    if (maxPending < 1 && maxPending !== Number.POSITIVE_INFINITY) {
+      throw new RangeError("approvalGate: maxPending must be >= 1");
+    }
+    const startOpen = opts.startOpen ?? false;
+    let src;
+    if (typeof source === "string") {
+      src = this._resolveStep(source);
+    } else if (this.nameOf(source) !== void 0) {
+      src = source;
+    } else {
+      const proxy = node2(
+        [source],
+        (batchData, actions) => {
+          const batch0 = batchData[0];
+          if (batch0 == null || batch0.length === 0) return;
+          for (const v of batch0) actions.emit(v);
+        },
+        {
+          describeKind: "derived",
+          meta: factoryTag("proxy")
+        }
+      );
+      this.add(proxy, { name: `${name}/source` });
+      src = proxy;
+    }
+    const internal = new Graph(`${name}-state`);
+    const pendingNode = internal.state("pending", [], {
+      equals: () => false
+    });
+    const isOpenNode = internal.state("isOpen", startOpen);
+    const countNode = internal.derived("count", ["pending"], (batchData, ctx) => {
+      const data = batchData.map(
+        (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+      );
+      return [data[0].length];
+    });
+    const droppedCountNode = internal.state("droppedCount", 0);
+    const decisions = createAuditLog({
+      name: "decisions",
+      retainedLimit: 1024,
+      graph: internal
+    });
+    this.mount(`${name}-state`, internal);
+    let queue = [];
+    let torn = false;
+    let latched = false;
+    let latestIsOpen = startOpen;
+    const isOpenUnsub = isOpenNode.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA2) latestIsOpen = m[1];
+      }
+    });
+    this.addDisposer(isOpenUnsub);
+    function syncPending() {
+      pendingNode.emit([...queue]);
+    }
+    function recordDecision(action, items, unflushed) {
+      decisions.append({
+        action,
+        t_ns: wallClockNs2(),
+        ...items !== void 0 ? { items, count: items.length } : {},
+        ...unflushed !== void 0 ? { unflushed } : {},
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      });
+    }
+    function enqueue(value) {
+      queue.push(value);
+      if (queue.length > maxPending) {
+        const dropped = queue.shift();
+        droppedCountNode.emit(droppedCountNode.cache + 1);
+        recordDecision("drop", [dropped]);
+      }
+      syncPending();
+    }
+    function dequeue(n) {
+      const items = queue.splice(0, n);
+      syncPending();
+      return items;
+    }
+    const output = node2(
+      [src],
+      (batchData, actions, ctx) => {
+        const terminal = ctx.terminalDeps[0];
+        if (terminal !== void 0) {
+          torn = true;
+          const unflushed = queue.length;
+          queue = [];
+          syncPending();
+          recordDecision("teardown", void 0, unflushed);
+          actions.down(terminal === true ? [[COMPLETE2]] : [[ERROR, terminal]]);
+          return;
+        }
+        const batch0 = batchData[0];
+        if (batch0 == null || batch0.length === 0) {
+          actions.down([[RESOLVED]]);
+          return;
+        }
+        for (const v of batch0) {
+          if (latestIsOpen) {
+            actions.emit(v);
+          } else {
+            enqueue(v);
+            actions.down([[RESOLVED]]);
+          }
+        }
+      },
+      {
+        name,
+        describeKind: "derived",
+        meta: meta("approval_gate", opts.meta)
+      }
+    );
+    this.add(output, { name });
+    if (opts.approver != null) {
+      const initialApproved = Boolean(opts.approver.cache);
+      if (initialApproved) {
+        isOpenNode.emit(true);
+        latestIsOpen = true;
+        if (opts.onceOnly) latched = true;
+      }
+      const approverSub = opts.approver.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (m[0] !== DATA2) continue;
+          const truthy = Boolean(m[1]);
+          if (truthy && !latestIsOpen) {
+            if (opts.onceOnly) {
+              if (latched) continue;
+              latched = true;
+            }
+            batch(() => {
+              isOpenNode.emit(true);
+              const items = dequeue(queue.length);
+              recordDecision("open", items);
+              for (const item of items) {
+                if (torn) break;
+                output.emit(item);
+              }
+            });
+          } else if (!truthy && latestIsOpen) {
+            if (opts.onceOnly && latched) continue;
+            batch(() => {
+              isOpenNode.emit(false);
+              recordDecision("close");
+            });
+          }
+        }
+      });
+      this.addDisposer(approverSub);
+    }
+    const guardTorn = (method) => {
+      if (torn) throw new Error(`approvalGate: ${method}() called after the gate was torn down`);
+    };
+    const approveImpl = (count = 1) => {
+      guardTorn("approve");
+      const items = dequeue(count);
+      for (const item of items) {
+        if (torn) break;
+        output.emit(item);
+      }
+    };
+    const rejectImpl = (count = 1) => {
+      guardTorn("reject");
+      dequeue(count);
+    };
+    const modifyImpl = (fn, count = 1) => {
+      guardTorn("modify");
+      const snapshot = [...queue];
+      const items = dequeue(count);
+      for (let i = 0; i < items.length; i++) {
+        if (torn) break;
+        output.emit(fn(items[i], i, snapshot));
+      }
+    };
+    const openImpl = () => {
+      guardTorn("open");
+      isOpenNode.emit(true);
+      const items = dequeue(queue.length);
+      for (const item of items) {
+        if (torn) break;
+        output.emit(item);
+      }
+    };
+    const closeImpl = () => {
+      guardTorn("close");
+      if (opts.onceOnly && latched) return;
+      isOpenNode.emit(false);
+    };
+    const approve = mutate(approveImpl, {
+      frame: "transactional",
+      log: decisions,
+      freeze: false,
+      onSuccessRecord: (args, _r, m) => ({
+        action: "approve",
+        count: args[0] ?? 1,
+        t_ns: m.t_ns,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      }),
+      onFailureRecord: (_a, _e, m) => ({
+        action: "drop",
+        t_ns: m.t_ns,
+        errorType: m.errorType,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      })
+    });
+    const reject = mutate(rejectImpl, {
+      frame: "transactional",
+      log: decisions,
+      freeze: false,
+      onSuccessRecord: (args, _r, m) => ({
+        action: "reject",
+        count: args[0] ?? 1,
+        t_ns: m.t_ns,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      }),
+      onFailureRecord: (_a, _e, m) => ({
+        action: "drop",
+        t_ns: m.t_ns,
+        errorType: m.errorType,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      })
+    });
+    const modify = mutate(modifyImpl, {
+      frame: "transactional",
+      log: decisions,
+      freeze: false,
+      onSuccessRecord: (args, _r, m) => ({
+        action: "modify",
+        count: args[1] ?? 1,
+        t_ns: m.t_ns,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      }),
+      onFailureRecord: (_a, _e, m) => ({
+        action: "drop",
+        t_ns: m.t_ns,
+        errorType: m.errorType,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      })
+    });
+    const open = mutate(openImpl, {
+      frame: "transactional",
+      log: decisions,
+      freeze: false,
+      onSuccessRecord: (_a, _r, m) => ({
+        action: "open",
+        t_ns: m.t_ns,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      }),
+      onFailureRecord: (_a, _e, m) => ({
+        action: "drop",
+        t_ns: m.t_ns,
+        errorType: m.errorType,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      })
+    });
+    const close = mutate(closeImpl, {
+      frame: "transactional",
+      log: decisions,
+      freeze: false,
+      onSuccessRecord: (_a, _r, m) => ({
+        action: "close",
+        t_ns: m.t_ns,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      }),
+      onFailureRecord: (_a, _e, m) => ({
+        action: "drop",
+        t_ns: m.t_ns,
+        errorType: m.errorType,
+        ...opts.handlerVersion != null ? { handlerVersion: opts.handlerVersion } : {}
+      })
+    });
+    this.addDisposer(countNode.subscribe(() => void 0));
+    const controller = {
+      output,
+      pending: pendingNode,
+      count: countNode,
+      isOpen: isOpenNode,
+      droppedCount: droppedCountNode,
+      decisions,
+      audit: decisions,
+      approve,
+      reject,
+      modify,
+      open,
+      close
+    };
+    return controller;
+  }
+  // -- approval (thin alias over approvalGate({ approver, maxPending: 1 })) -
+  /**
+   * Reactive approval step: passes items through when `approver` is truthy;
+   * holds at most one pending item (maxPending: 1) when falsy. A thin alias
+   * over `approvalGate({ approver, maxPending: 1 })` — use `approvalGate()`
+   * directly for finer control (maxPending, onceOnly, manual approve/reject).
+   */
+  approval(name, source, approver, opts = {}) {
+    return this.approvalGate(name, source, { ...opts, approver, maxPending: 1 });
+  }
+  // -- catch (renamed onFailure; dep-channel intercept) -------------------
+  catch(name, source, recover, opts = {}) {
+    const src = this._resolveStep(source);
+    const mode = opts.on ?? "errored";
+    const step = node2(
+      [src],
+      (batchData, actions, ctx) => {
+        const terminal = ctx.terminalDeps[0];
+        if (terminal !== void 0) {
+          const cause = terminal === true ? { kind: "completed" } : { kind: "errored", error: terminal };
+          if (mode === "terminal" || mode === cause.kind) {
+            actions.emit(recover(cause, actions));
+            return;
+          }
+          actions.down(cause.kind === "completed" ? [[COMPLETE2]] : [[ERROR, cause.error]]);
+          return;
+        }
+        const batch0 = batchData[0];
+        if (batch0 == null || batch0.length === 0) {
+          actions.down([[RESOLVED]]);
+          return;
+        }
+        for (const v of batch0) actions.emit(v);
+      },
+      {
+        name,
+        describeKind: "derived",
+        completeWhenDepsComplete: opts.completeWhenDepsComplete ?? !(mode === "completed" || mode === "terminal"),
+        errorWhenDepsError: !(mode === "errored" || mode === "terminal"),
+        meta: meta("catch", opts.meta)
+      }
+    );
+    this.add(step, { name });
+    return step;
+  }
+  // -- internals ----------------------------------------------------------
+  _resolveStep(dep) {
+    if (typeof dep === "string") return this.resolve(dep);
+    const existing = this.nameOf(dep);
+    if (existing === void 0) {
+      throw new Error(
+        `PipelineGraph "${this.name}": Node dep is not registered. Pass a string path or call graph.add(node) first.`
+      );
+    }
+    return dep;
+  }
+};
+function pipelineGraph(name, opts) {
+  const g = new PipelineGraph(name, opts);
+  const { factory: _f, factoryArgs: _fa, ...tagArgs } = opts ?? {};
+  g.tagFactory("pipelineGraph", placeholderArgs(tagArgs));
+  return g;
+}
+
+// src/utils/orchestration/tracker.ts
+function tracker(opts) {
+  const { hub, topicName, name, from } = opts;
+  const effectiveTopicName = topicName ?? DEFERRED_TOPIC;
+  const effectiveName = name ?? "tracker";
+  const topicGraph = hub.topic(effectiveTopicName);
+  const sub = subscription(effectiveName, topicGraph, {
+    ...from != null && { from }
+  });
+  const total = sub.derived(
+    "tracker-total",
+    [topicGraph.events],
+    (data, ctx) => {
+      const b0 = data[0];
+      const arr = b0 != null && b0.length > 0 ? b0.at(-1) : ctx.prevData[0] ?? [];
+      return [arr.length];
+    },
+    { keepAlive: true }
+  );
+  return {
+    topic: topicGraph,
+    subscription: sub,
+    pending: sub.available,
+    cursor: sub.cursor,
+    total,
+    add: (item) => topicGraph.publish(item),
+    ack: (n) => sub.ack(n ?? 1),
+    pullAndAck: (limit) => sub.pullAndAck(limit)
+  };
+}
+
+export {
+  humanInput,
+  decisionKeyOf,
+  PipelineGraph,
+  pipelineGraph,
+  tracker
+};
+//# sourceMappingURL=chunk-CGHORL6G.js.map