@graphrefly/graphrefly 0.47.2 → 0.48.0

package/dist/solutions/index.cjs

@@ -1333,6 +1333,11 @@ var AgentLoopGraph = class extends import_graph3.Graph {
           chat.append("assistant", response.content, {
             toolCalls: response.toolCalls
           });
+          if (capReached && hasToolCalls) {
+            for (const tc of response.toolCalls) {
+              chat.appendToolResult(tc.id, "[tool call denied: maxTurns reached]");
+            }
+          }
         });
       },
       { describeKind: "effect" }
@@ -1354,6 +1359,45 @@ var AgentLoopGraph = class extends import_graph3.Graph {
       },
       { describeKind: "effect" }
     );
+    const effFullDeny = gatedToolCallsNode !== toolCallsRaw ? (0, import_core9.node)(
+      [toolCallsRaw, gatedToolCallsNode],
+      (batchData) => {
+        if (latestAborted) return;
+        const rawBatch = batchData[0];
+        const gatedBatch = batchData[1];
+        const rawCalls = rawBatch != null && rawBatch.length > 0 ? rawBatch.at(-1) : null;
+        if (rawCalls == null || rawCalls.length === 0) return;
+        const gatedCalls = gatedBatch != null && gatedBatch.length > 0 ? gatedBatch.at(-1) : null;
+        const allowedIds = gatedCalls === null ? null : new Set(gatedCalls.map((c) => c.id));
+        const denied = allowedIds === null ? rawCalls : rawCalls.filter((c) => !allowedIds.has(c.id));
+        if (denied.length === 0) return;
+        const isFullDeny = gatedCalls === null;
+        (0, import_core9.batch)(() => {
+          if (isFullDeny) {
+            statusNode.emit(latestTurn >= maxTurns ? "done" : "thinking");
+          }
+          for (const c of denied)
+            chat.appendToolResult(c.id, "[tool call denied by interceptor]");
+        });
+      },
+      {
+        name: "fullDenyRecovery",
+        describeKind: "effect",
+        meta: aiMeta("agent_full_deny_recovery"),
+        // MUST be explicit: the core `node()` default is
+        // `partial: false` (node.ts `opts.partial ?? false`),
+        // and `gatedToolCallsNode` only ever emits RESOLVED on the
+        // full-deny path (never DATA/terminal). Spec R2.7.0
+        // (DS-2.7.A, 2026-05-19) holds the `partial: false`
+        // first-run gate until every dep has contributed real
+        // DATA, so a `partial: false` effFullDeny would hold the
+        // fn FOREVER. Spec R2.7.2 = `partial: true` disables the
+        // gate; the fn body's `denied`-subtraction guard above
+        // covers the SENTINEL slot per the R2.7.2 author
+        // contract.
+        partial: true
+      }
+    ) : null;
     let latestStatus = statusNode.cache ?? "idle";
     const statusSub = statusNode.subscribe((msgs) => {
       for (const m of msgs) if (m[0] === import_core9.DATA) latestStatus = m[1];
@@ -1373,6 +1417,7 @@ var AgentLoopGraph = class extends import_graph3.Graph {
     );
     const kaResponse = (0, import_extra5.keepalive)(effResponse);
     const kaResults = (0, import_extra5.keepalive)(effResults);
+    const kaFullDeny = effFullDeny ? (0, import_extra5.keepalive)(effFullDeny) : null;
     const kaAbort = (0, import_extra5.keepalive)(effAbort);
     this._terminalResult = (0, import_core9.node)(
       [statusNode, lastResponseState],
@@ -1425,6 +1470,7 @@ var AgentLoopGraph = class extends import_graph3.Graph {
     this.addDisposer(statusSub);
     this.addDisposer(kaResponse);
     this.addDisposer(kaResults);
+    if (kaFullDeny) this.addDisposer(kaFullDeny);
     this.addDisposer(kaAbort);
     this._disposeRunWiring = () => {
     };
@@ -1724,6 +1770,26 @@ function createAuditLog(opts) {
   }
   return log;
 }
+function readonlyAuditLog(log) {
+  return Object.freeze({
+    get entries() {
+      return log.entries;
+    },
+    get size() {
+      return log.size;
+    },
+    get lastValue() {
+      return log.lastValue;
+    },
+    get mutationLog() {
+      return log.mutationLog;
+    },
+    at: log.at.bind(log),
+    withLatest: log.withLatest.bind(log),
+    view: log.view.bind(log),
+    scan: log.scan.bind(log)
+  });
+}
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
   for (const k of Object.keys(value)) {
@@ -4129,31 +4195,40 @@ var RATE_LIMITER_INITIAL_STATE = Object.freeze({
   pendingCount: 0,
   paused: false
 });
+function validateRateLimiterOpts(o) {
+  if (o.maxEvents <= 0) throw new RangeError("maxEvents must be > 0");
+  if (o.windowNs <= 0) throw new RangeError("windowNs must be > 0");
+  if (o.maxBuffer === void 0) {
+    throw new RangeError(
+      "rateLimiter requires explicit maxBuffer (use Infinity to opt in to unbounded)"
+    );
+  }
+  const isUnbounded = o.maxBuffer === Infinity;
+  if (!isUnbounded && (!Number.isInteger(o.maxBuffer) || o.maxBuffer < 1)) {
+    throw new RangeError("maxBuffer must be a positive integer (or Infinity for unbounded)");
+  }
+}
+function resolveInitialReactiveOpts(optsNode) {
+  const cached = optsNode.cache;
+  if (cached === void 0) {
+    throw new RangeError(
+      "rateLimiter: reactive (Node-form) opts must carry a cached value at construction \u2014 seed the opts Node with `initial`. Mode (bounded vs unbounded) and the initial cap are LOCKED from `.cache` at construction and the swap handler rejects mode toggles; an un-seeded Node would silently lock bounded `maxBuffer: 1` (D4)."
+    );
+  }
+  return cached;
+}
 function rateLimiter(source, opts) {
   const isReactive = isNode(opts);
-  if (!isReactive) {
-    const o = opts;
-    if (o.maxEvents <= 0) throw new RangeError("maxEvents must be > 0");
-    if (o.windowNs <= 0) throw new RangeError("windowNs must be > 0");
-    if (o.maxBuffer === void 0) {
-      throw new RangeError(
-        "rateLimiter requires explicit maxBuffer (use Infinity to opt in to unbounded)"
-      );
-    }
-    const isUnbounded0 = o.maxBuffer === Infinity;
-    if (!isUnbounded0 && (!Number.isInteger(o.maxBuffer) || o.maxBuffer < 1)) {
-      throw new RangeError("maxBuffer must be a positive integer (or Infinity for unbounded)");
-    }
-  }
-  const initialOpts = isReactive ? opts.cache : opts;
-  const initialMaxBuffer = initialOpts?.maxBuffer;
+  const initialOpts = isReactive ? resolveInitialReactiveOpts(opts) : opts;
+  validateRateLimiterOpts(initialOpts);
+  const initialMaxBuffer = initialOpts.maxBuffer;
   const isUnbounded = initialMaxBuffer === Infinity;
   const out = (0, import_core22.node)(
     (_data, a) => {
-      let maxEvents = initialOpts?.maxEvents ?? 1;
-      let windowNs = initialOpts?.windowNs ?? NS_PER_SEC;
-      let maxBuffer = initialMaxBuffer ?? 1;
-      let onOverflow = initialOpts?.onOverflow ?? "drop-newest";
+      let maxEvents = initialOpts.maxEvents;
+      let windowNs = initialOpts.windowNs;
+      let maxBuffer = initialMaxBuffer;
+      let onOverflow = initialOpts.onOverflow ?? "drop-newest";
       let refillPerSec = maxEvents * NS_PER_SEC / windowNs;
       let tokenTimeNs = NS_PER_SEC / refillPerSec;
       let bucket = tokenBucket(maxEvents, refillPerSec);
@@ -4982,6 +5057,10 @@ var PipelineGraph = class extends import_graph9.Graph {
       {
         name,
         describeKind: "derived",
+        // Spec §2.7 R2.7.1 (DS-2.7.A). fn must fire on
+        // upstream-COMPLETE/ERROR-only-without-DATA so the
+        // teardown-decision record + downstream terminal forward run.
+        terminalAsRealInput: true,
         meta: meta("approval_gate", opts.meta)
       }
     );
@@ -5199,6 +5278,11 @@ var PipelineGraph = class extends import_graph9.Graph {
         describeKind: "derived",
         completeWhenDepsComplete: opts.completeWhenDepsComplete ?? !(mode === "completed" || mode === "terminal"),
         errorWhenDepsError: !(mode === "errored" || mode === "terminal"),
+        // Spec §2.7 R2.7.1 (DS-2.7.A). `catch` exists to fire on a
+        // source terminal — its whole job is `recover(cause, …)` on a
+        // terminal-only wave. Without this opt-in the gate holds and
+        // the recover branch never runs.
+        terminalAsRealInput: true,
         meta: meta("catch", opts.meta)
       }
     );
@@ -5401,7 +5485,10 @@ var JobQueueGraph = class extends import_graph11.Graph {
   depth;
   /** Audit log of every queue mutation (Audit 2). */
   events;
-  /** Alias for {@link JobQueueGraph.events} — Audit 2 `.audit` duplication. */
+  /**
+   * Read-only view of {@link JobQueueGraph.events} — Audit 2 `.audit`
+   * duplication; M7 (cannot mutate the canonical log via the alias).
+   */
   audit;
   // Tier 8 / COMPOSITION-GUIDE §35: mutate wrappers for the four
   // single-record mutation methods. Assigned in the constructor (NOT via
@@ -5442,7 +5529,7 @@ var JobQueueGraph = class extends import_graph11.Graph {
       retainedLimit: 1024,
       graph: this
     });
-    this.audit = this.events;
+    this.audit = readonlyAuditLog(this.events);
     this._seqCursor = registerCursor(this, "seq", 0);
     this._enqueueImpl = mutate(
       (payload, enqueueOpts) => {
@@ -5495,7 +5582,7 @@ var JobQueueGraph = class extends import_graph11.Graph {
       }
     );
     this._nackImpl = mutate(
-      (id, job, requeue) => {
+      (id, job, requeue, _error) => {
         if (requeue) {
           this._jobs.set(id, { ...job, state: "queued" });
           this._pending.append(id);
@@ -5508,12 +5595,16 @@ var JobQueueGraph = class extends import_graph11.Graph {
         log: this.events,
         seq: this._seqCursor,
         freeze: false,
-        onSuccessRecord: ([id, job], _r, { t_ns, seq }) => ({
+        onSuccessRecord: ([id, job, requeue, error], _r, { t_ns, seq }) => ({
           action: "nack",
           id,
           attempts: job.attempts,
           t_ns,
-          seq: seq ?? 0
+          seq: seq ?? 0,
+          // F-CATCH D-3: surface the failure cause on the no-requeue
+          // (terminal-failure) nack only. A requeue nack is a retry,
+          // not a failure, so it carries no error.
+          ...!requeue && error !== void 0 ? { error } : {}
         })
       }
     );
@@ -5585,10 +5676,20 @@ var JobQueueGraph = class extends import_graph11.Graph {
     this._ackImpl(id, job);
     return true;
   }
+  /**
+   * Negatively-acknowledge an inflight job.
+   *
+   * @param opts.requeue - `true` (default) returns the job to the queue for
+   *   retry; `false` drops it permanently (terminal failure).
+   * @param opts.error - Optional failure cause for a `requeue: false` nack.
+   *   Recorded on the emitted `"nack"` {@link JobEvent} as `error` so the
+   *   reason a job failed is recoverable from the event stream (F-CATCH
+   *   D-3). Ignored when `requeue` is `true` (a retry is not a failure).
+   */
   nack(id, opts = {}) {
     const job = this._jobs.get(id);
     if (!job || job.state !== "inflight") return false;
-    this._nackImpl(id, job, opts.requeue ?? true);
+    this._nackImpl(id, job, opts.requeue ?? true, opts.error);
     return true;
   }
   /**
@@ -5754,10 +5855,10 @@ var JobFlowGraph = class extends import_graph11.Graph {
               let result;
               try {
                 result = workFn(job, { signal: ac.signal });
-              } catch {
+              } catch (err) {
                 inflight.delete(entry);
                 inflightCounter?.emit(inflight.size);
-                current.nack(job.id, { requeue: false });
+                current.nack(job.id, { requeue: false, error: err });
                 processed += 1;
                 continue;
               }
@@ -5808,7 +5909,7 @@ var JobFlowGraph = class extends import_graph11.Graph {
                   } else if (m[0] === import_core26.ERROR) {
                     settled = true;
                     cleanupSub();
-                    current.nack(job.id, { requeue: false });
+                    current.nack(job.id, { requeue: false, error: m[1] });
                     return;
                   }
                 }
@@ -6064,7 +6165,18 @@ var HarnessGraph = class extends import_graph12.Graph {
    * (use {@link unrouted}), and the internal `triage-output` fan-in.
    */
   queueTopics;
-  /** Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`. */
+  /**
+   * Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`.
+   *
+   * **Ownership (EC10/EC15).** Owned by the harness: it is mounted as a
+   * child subgraph (`harness.mount("strategy", strategy)`), so its disposal
+   * cascades from `harness.destroy()` via the mount lifecycle. Do **not**
+   * call `strategy.destroy()` independently — the harness's `triage-input`
+   * node and (when `opts.priority` is set) `buildPriorityScores` hold
+   * cross-graph deps on `strategy.entries`; destroying the strategy out of
+   * band staleness those nodes while the rest of the loop keeps running.
+   * Read/subscribe freely; let the harness own the lifecycle.
+   */
   strategy;
   /** Global retry count across all items (circuit breaker). Reactive — subscribable. */
   totalRetries;
@@ -6526,6 +6638,16 @@ var import_core28 = require("@graphrefly/pure-ts/core");
 var import_extra19 = require("@graphrefly/pure-ts/extra");
 var import_graph13 = require("@graphrefly/pure-ts/graph");
 var RefineLoopGraph = class extends import_graph13.Graph {
+  /**
+   * Best candidate so far. **SENTINEL until the first iteration settles** —
+   * `loop.best.cache` is `undefined` (not `null`) before any iteration
+   * produces a best, and a degenerate empty-candidate iteration leaves the
+   * prior best in place rather than wiping it. Consumers guard with
+   * `=== undefined` (spec §3 SENTINEL), not `== null`. (Anti-pattern sweep
+   * 2026-05-18: dropped the `initial: null` eager-placeholder; `null` is
+   * reserved for the per-iteration {@link Iteration.best} data field where an
+   * empty batch is a valid domain value.)
+   */
   best;
   /**
    * Best score so far. Pseudo-private (`_score`) to avoid colliding with any
@@ -6576,8 +6698,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
     });
     this.add(strategyNode, { name: "strategy" });
     const lastFeedbackState = (0, import_core28.node)([], {
-      name: "lastFeedback",
-      initial: null
+      name: "lastFeedback"
     });
     this.add(lastFeedbackState, { name: "lastFeedback" });
     const prevCandidatesState = (0, import_core28.node)([], {
@@ -6596,7 +6717,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
       // append-style; reactive consumers want every push
     });
     this.add(historyState, { name: "history" });
-    const bestState = (0, import_core28.node)([], { name: "best", initial: null });
+    const bestState = (0, import_core28.node)([], { name: "best" });
     this.add(bestState, { name: "best" });
     const scoreState = (0, import_core28.node)([], { name: "score", initial: Number.NEGATIVE_INFINITY });
     this.add(scoreState, { name: "score" });
@@ -6620,7 +6741,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
     this.decide = hubDecideTopic;
     this._pauseState = pauseState;
     let latestStrategy = initialStrategy;
-    let latestFeedback = null;
+    let latestFeedback;
     let latestPrevCandidates = [];
     this.addDisposer(
       strategyNode.subscribe((msgs) => {
@@ -6641,7 +6762,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
       iterationTrigger,
       (iter) => {
         const strat = latestStrategy;
-        const isSeed = iter === 0 || latestFeedback == null;
+        const isSeed = iter === 0 || latestFeedback === void 0;
         return (0, import_core28.node)(
           [],
           (_data, actions) => {
@@ -7033,7 +7154,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
           decision = "paused";
         }
         (0, import_core28.batch)(() => {
-          bestState.emit(best);
+          if (best !== null) bestState.emit(best);
           scoreState.emit(fb.score);
           historyState.emit(nextHistory);
           budgetState.emit(nextBudget);
@@ -7925,11 +8046,12 @@ var GuardedExecutionGraph = class extends import_graph17.Graph {
     this.addDisposer((0, import_extra24.keepalive)(this.scope));
     const scopedHandle = target.describe({
       reactive: true,
-      // F8 (Tier 5.2): `_actorNode` is `Node<Actor | null>`. The cast is
-      // safe at runtime per the `resolveActorOption` null-tolerance
-      // contract — `null` / `undefined` cache is treated as "no scoping"
-      // (full visibility). See `scopedDescribeNode` for the matching
-      // per-call site and graph.ts § "Cache-undefined semantics".
+      // F8 (resolved 2026-05-18): `GraphDescribeOptions.actor` is now
+      // `Actor | Node<Actor | null>`, so `_actorNode` (a
+      // `Node<Actor | null>`) passes without a cast. A `null`/`undefined`
+      // cache resolves to "no scoping" (full visibility) per
+      // `resolveActorOption`. See graph.ts § "Cache-undefined/null
+      // semantics".
       actor: this._actorNode,
       reactiveName: "scopedDescribe"
     });
@@ -7975,11 +8097,11 @@ var GuardedExecutionGraph = class extends import_graph17.Graph {
     const actorNode = actorOverride == null ? this._actorNode : isNode4(actorOverride) ? actorOverride : (0, import_core32.node)([], { name: "actor_override", initial: actorOverride });
     const handle = this._target.describe({
       reactive: true,
-      // `_actorNode` is `Node<Actor | null>`. The `as Node<Actor>` cast is
-      // safe at runtime: `_describeReactive` resolves the actor via
-      // `resolveActorOption`, which treats `null`/`undefined` cache as
-      // "no scoping" (full visibility). Documented in graph.ts §
-      // "Cache-undefined semantics."
+      // F8 (resolved 2026-05-18): `actor` accepts `Node<Actor | null>`
+      // directly. `actorNode` is `_actorNode` (`Node<Actor | null>`) or
+      // an override (`Node<Actor>`/`Node<Actor | null>`); both assign
+      // without a cast. `_describeReactive` resolves via
+      // `resolveActorOption` (null/undefined cache → no scoping).
       actor: actorNode,
       ...opts ?? {}
     });
@@ -8080,7 +8202,6 @@ var ResilientPipelineGraph = class extends import_graph18.Graph {
       } else {
         const rateOpts = {
           ...opts.rateLimit,
-          maxBuffer: opts.rateLimit.maxBuffer ?? Infinity,
           meta: domainMeta("resilient", "rate-limit")
         };
         const bundle = rateLimiter(current, rateOpts);