@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/utils/orchestration/index.cjs

@@ -0,0 +1,876 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/orchestration/index.ts
+var orchestration_exports = {};
+__export(orchestration_exports, {
+  PipelineGraph: () => PipelineGraph,
+  decisionKeyOf: () => decisionKeyOf,
+  humanInput: () => humanInput,
+  pipelineGraph: () => pipelineGraph,
+  tracker: () => tracker
+});
+module.exports = __toCommonJS(orchestration_exports);
+
+// src/utils/orchestration/human-input.ts
+var import_core3 = require("@graphrefly/pure-ts/core");
+var import_extra3 = require("@graphrefly/pure-ts/extra");
+
+// src/utils/messaging/message.ts
+var PROMPTS_TOPIC = "prompts";
+var RESPONSES_TOPIC = "responses";
+var DEFERRED_TOPIC = "deferred";
+
+// src/utils/messaging/index.ts
+var import_core2 = require("@graphrefly/pure-ts/core");
+var import_extra2 = require("@graphrefly/pure-ts/extra");
+var import_graph2 = require("@graphrefly/pure-ts/graph");
+
+// src/base/meta/domain-meta.ts
+function domainMeta(domain, kind, extra) {
+  return {
+    [domain]: true,
+    [`${domain}_type`]: kind,
+    ...extra ?? {}
+  };
+}
+
+// src/base/mutation/index.ts
+var import_core = require("@graphrefly/pure-ts/core");
+var import_extra = require("@graphrefly/pure-ts/extra");
+var import_graph = require("@graphrefly/pure-ts/graph");
+var DEFAULT_AUDIT_GUARD = (0, import_core.policy)((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+function createAuditLog(opts) {
+  const log = (0, import_extra.reactiveLog)([], {
+    name: opts.name,
+    maxSize: opts.retainedLimit ?? 1024,
+    guard: opts.guard ?? DEFAULT_AUDIT_GUARD,
+    ...opts.versioning != null ? { versioning: opts.versioning } : {}
+  });
+  log.withLatest();
+  if (opts.graph) {
+    opts.graph.add(log.entries, { name: opts.name });
+  }
+  return log;
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const k of Object.keys(value)) {
+    deepFreeze(value[k]);
+  }
+  return Object.freeze(value);
+}
+function mutate(act, opts) {
+  const { up, down } = typeof act === "function" ? { up: act, down: void 0 } : act;
+  const freeze = opts.freeze ?? true;
+  if (opts.frame === "inline") {
+    return function wrapped(...args) {
+      const sealed = freeze ? args.map(deepFreeze) : args;
+      const t_ns = (0, import_core.wallClockNs)();
+      const seq = opts.seq ? bumpCursor(opts.seq) : void 0;
+      try {
+        const result = up(...sealed);
+        if (opts.log && opts.onSuccessRecord) {
+          appendAudit(
+            opts.log,
+            opts.onSuccessRecord,
+            sealed,
+            result,
+            { t_ns, seq },
+            opts.handlerVersion
+          );
+        }
+        return result;
+      } catch (err) {
+        if (opts.log && opts.onFailureRecord) {
+          const errorType = err instanceof Error ? err.name : typeof err;
+          appendAudit(
+            opts.log,
+            opts.onFailureRecord,
+            sealed,
+            err,
+            { t_ns, seq, errorType },
+            opts.handlerVersion
+          );
+        }
+        throw err;
+      }
+    };
+  }
+  return function wrapped(...args) {
+    const sealed = freeze ? args.map(deepFreeze) : args;
+    const t_ns = (0, import_core.wallClockNs)();
+    let result;
+    let captured;
+    let captureSet = false;
+    let seq;
+    try {
+      (0, import_core.batch)(() => {
+        if (opts.seq) seq = bumpCursor(opts.seq);
+        try {
+          result = up(...sealed);
+          if (opts.log && opts.onSuccessRecord) {
+            appendAudit(
+              opts.log,
+              opts.onSuccessRecord,
+              sealed,
+              result,
+              { t_ns, seq },
+              opts.handlerVersion
+            );
+          }
+        } catch (err) {
+          captured = err;
+          captureSet = true;
+          throw err;
+        }
+      });
+    } catch (outerErr) {
+      if (captureSet && down) {
+        try {
+          down(...sealed);
+        } catch (downErr) {
+          console.error(
+            `mutate: down hook threw \u2014 original action error preserved (${captured instanceof Error ? captured.name : typeof captured}). Down error:`,
+            downErr
+          );
+        }
+      }
+      if (captureSet && opts.log && opts.onFailureRecord) {
+        const errorType = captured instanceof Error ? captured.name : typeof captured;
+        appendAudit(
+          opts.log,
+          opts.onFailureRecord,
+          sealed,
+          captured,
+          { t_ns, seq, errorType },
+          opts.handlerVersion
+        );
+      }
+      throw captureSet ? captured : outerErr;
+    }
+    return result;
+  };
+}
+var _bumpCursorWarned = /* @__PURE__ */ new WeakSet();
+function bumpCursor(seq) {
+  const raw = seq.cache;
+  const valid = typeof raw === "number" && Number.isFinite(raw);
+  if (!valid && raw !== void 0 && !_bumpCursorWarned.has(seq)) {
+    _bumpCursorWarned.add(seq);
+    console.warn(
+      `bumpCursor: cursor cache held a non-numeric value (${String(raw)}); resetting to 0. Causes include: a snapshot codec round-tripping the cursor as a string / null / NaN, OR a malformed initial seed (e.g. state<number>(NaN)). Audit consumers may see colliding seq values after this point.`
+    );
+  }
+  const cur = valid ? raw : 0;
+  const next = cur + 1;
+  seq.down([[import_core.DIRTY], [import_core.DATA, next]]);
+  return next;
+}
+function appendAudit(audit, builder, args, value, meta2, handlerVersion) {
+  const record = builder(args, value, meta2);
+  if (record === void 0) return;
+  const stamped = handlerVersion != null ? { ...record, handlerVersion } : record;
+  audit.append(stamped);
+}
+
+// src/utils/messaging/index.ts
+function requireNonNegativeInt(value, label) {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return value;
+}
+function messagingMeta(kind, extra) {
+  return domainMeta("messaging", kind, extra);
+}
+var SubscriptionGraph = class extends import_graph2.Graph {
+  cursor;
+  available;
+  /**
+   * Reference to the upstream topic graph. Intentionally NOT mounted
+   * under this subscription: a subscription is a VIEW over an
+   * externally-owned topic. Double-mounting (e.g. hub-owned topic +
+   * sub-mount here) would make either-side teardown leave the other
+   * holding a dead reference. Node-level `derived([topicEvents], …)`
+   * still wires the data dependency across graph boundaries. D1(e).
+   */
+  topic;
+  _disposed = false;
+  _ackImpl;
+  _pullAndAckImpl;
+  constructor(name, topicGraph, opts = {}) {
+    super(name, opts.graph);
+    this.topic = topicGraph;
+    let initialCursor;
+    if (opts.from !== void 0) {
+      if (opts.from === "retained") {
+        initialCursor = 0;
+      } else if (opts.from === "now") {
+        initialCursor = topicGraph.events.cache.length;
+      } else {
+        initialCursor = requireNonNegativeInt(opts.from, "subscription from");
+      }
+    } else {
+      initialCursor = requireNonNegativeInt(opts.cursor ?? 0, "subscription cursor");
+    }
+    this.cursor = this.state("cursor", initialCursor, {
+      meta: messagingMeta("subscription_cursor")
+    });
+    this.available = topicGraph._logBundle.view({ kind: "fromCursor", cursor: this.cursor });
+    this.add(this.available, { name: "available" });
+    this.addDisposer((0, import_extra2.keepalive)(this.available));
+    if (opts.advanceOn !== void 0) {
+      const advanceOn = opts.advanceOn;
+      let advanceInitialized = false;
+      const advancePump = (0, import_core2.node)(
+        [advanceOn],
+        () => {
+          if (!advanceInitialized) {
+            advanceInitialized = true;
+            return;
+          }
+          if (this._disposed) return;
+          const avail = this.available.cache;
+          if (avail.length === 0) return;
+          const next = this.cursor.cache + avail.length;
+          this.cursor.emit(next);
+        },
+        {
+          name: "advancePump",
+          describeKind: "effect",
+          meta: messagingMeta("subscription_advance_pump")
+        }
+      );
+      this.add(advancePump, { name: "advancePump" });
+      this.addDisposer((0, import_extra2.keepalive)(advancePump));
+    }
+    this._ackImpl = mutate(
+      (count) => {
+        const available = this.available.cache;
+        const requested = count === void 0 ? available.length : requireNonNegativeInt(count, "subscription ack count");
+        const step = Math.min(requested, available.length);
+        if (step <= 0) return this.cursor.cache;
+        const next = this.cursor.cache + step;
+        this.cursor.emit(next);
+        return next;
+      },
+      { frame: "inline", freeze: false }
+    );
+    this._pullAndAckImpl = mutate(
+      (limit) => {
+        const available = this.available.cache;
+        const max = limit === void 0 ? available.length : requireNonNegativeInt(limit, "subscription pullAndAck limit");
+        const items = available.slice(0, max);
+        if (items.length === 0) return { items, cursor: this.cursor.cache };
+        const next = this.cursor.cache + items.length;
+        this.cursor.emit(next);
+        return { items, cursor: next };
+      },
+      { frame: "inline", freeze: false }
+    );
+  }
+  ack(count) {
+    if (this._disposed) return this.cursor.cache;
+    return this._ackImpl(count);
+  }
+  pull(limit) {
+    if (this._disposed) return [];
+    const available = this.available.cache;
+    const max = limit === void 0 ? available.length : requireNonNegativeInt(limit, "subscription pull limit");
+    return available.slice(0, max);
+  }
+  /**
+   * Atomic pull-and-acknowledge. Returns `{ items, cursor }` where `cursor`
+   * is the new cursor position after advancing. Under single-threaded JS the
+   * snapshot and advance are atomic; PY callers use a per-subscription Lock.
+   *
+   * Replaces `pull(limit, { ack: true })`.
+   */
+  pullAndAck(limit) {
+    if (this._disposed) return { items: [], cursor: this.cursor.cache };
+    return this._pullAndAckImpl(limit);
+  }
+  /**
+   * Release internal subscriptions and mark the subscription torn-down.
+   * Subsequent `pull`, `pullAndAck`, `ack` return empty / current cursor.
+   * Emits COMPLETE on `cursor` so derived consumers (e.g. `available`) see
+   * the termination signal. Also drains `addDisposer` callbacks (including
+   * the `keepalive(advancePump)` subscription) so no keepalive leak occurs.
+   */
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = true;
+    this.cursor.down([[import_core2.COMPLETE]]);
+    this.destroy();
+  }
+};
+function subscription(name, topicGraph, opts) {
+  return new SubscriptionGraph(name, topicGraph, opts);
+}
+
+// src/utils/orchestration/human-input.ts
+function humanInput(opts) {
+  const { hub, prompt, schema, idGenerator } = opts;
+  const promptNode = (0, import_extra3.fromAny)(prompt);
+  const promptsTopic = hub.topic(PROMPTS_TOPIC);
+  const responsesTopic = hub.topic(RESPONSES_TOPIC);
+  const nextId = idGenerator ?? defaultIdGenerator();
+  return (0, import_core3.node)(
+    (_data, a) => {
+      let activeCorrelationId;
+      let respUnsub;
+      const promptUnsub = promptNode.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (m[0] === import_core3.COMPLETE) {
+            respUnsub?.();
+            respUnsub = void 0;
+            a.down([[import_core3.COMPLETE]]);
+            return;
+          }
+          if (m[0] !== import_core3.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] !== import_core3.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 = (0, import_core3.wallClockNs)().toString(36);
+  return () => {
+    n += 1;
+    return `humanInput-${base}-${n.toString(36)}`;
+  };
+}
+
+// src/utils/orchestration/pipeline-graph.ts
+var import_core4 = require("@graphrefly/pure-ts/core");
+var import_graph3 = require("@graphrefly/pure-ts/graph");
+function meta(kind, extra) {
+  return domainMeta("orchestration", kind, extra);
+}
+var decisionKeyOf = (d) => d.action;
+var PipelineGraph = class extends import_graph3.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 = (0, import_core4.node)(
+      deps,
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.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 = (0, import_core4.node)(
+      [src],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.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 = (0, import_core4.node)(
+      nodes,
+      (batchData, actions, ctx) => {
+        const values = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.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 = (0, import_core4.node)(
+        [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: (0, import_core4.factoryTag)("proxy")
+        }
+      );
+      this.add(proxy, { name: `${name}/source` });
+      src = proxy;
+    }
+    const internal = new import_graph3.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(
+        (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.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] === import_core4.DATA) latestIsOpen = m[1];
+      }
+    });
+    this.addDisposer(isOpenUnsub);
+    function syncPending() {
+      pendingNode.emit([...queue]);
+    }
+    function recordDecision(action, items, unflushed) {
+      decisions.append({
+        action,
+        t_ns: (0, import_core4.wallClockNs)(),
+        ...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 = (0, import_core4.node)(
+      [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 ? [[import_core4.COMPLETE]] : [[import_core4.ERROR, terminal]]);
+          return;
+        }
+        const batch0 = batchData[0];
+        if (batch0 == null || batch0.length === 0) {
+          actions.down([[import_core4.RESOLVED]]);
+          return;
+        }
+        for (const v of batch0) {
+          if (latestIsOpen) {
+            actions.emit(v);
+          } else {
+            enqueue(v);
+            actions.down([[import_core4.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] !== import_core4.DATA) continue;
+          const truthy = Boolean(m[1]);
+          if (truthy && !latestIsOpen) {
+            if (opts.onceOnly) {
+              if (latched) continue;
+              latched = true;
+            }
+            (0, import_core4.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;
+            (0, import_core4.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 = (0, import_core4.node)(
+      [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" ? [[import_core4.COMPLETE]] : [[import_core4.ERROR, cause.error]]);
+          return;
+        }
+        const batch0 = batchData[0];
+        if (batch0 == null || batch0.length === 0) {
+          actions.down([[import_core4.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", (0, import_core4.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)
+  };
+}
+//# sourceMappingURL=index.cjs.map