@graphrefly/graphrefly 0.47.1 → 0.48.0

package/dist/presets/index.cjs

@@ -341,11 +341,13 @@ function withTimeout(source, opts, extraOpts) {
       if (latestOpts != null) {
         attachSource();
       }
-      return () => {
-        stopped = true;
-        timer.cancel();
-        if (srcUnsub) srcUnsub();
-        if (optsUnsub) optsUnsub();
+      return {
+        onDeactivation: () => {
+          stopped = true;
+          timer.cancel();
+          if (srcUnsub) srcUnsub();
+          if (optsUnsub) optsUnsub();
+        }
       };
     },
     {
@@ -475,9 +477,11 @@ function _oneShotLlmCall(adapter, messages, config) {
         invokeResult = adapter.invoke(messages, { ...config.invokeOpts, signal: ac.signal });
       } catch (err) {
         emitOnce(config.onFailure("throw", err));
-        return () => {
-          unlinkParent();
-          ac.abort();
+        return {
+          onDeactivation: () => {
+            unlinkParent();
+            ac.abort();
+          }
         };
       }
       const callNode = (0, import_extra.fromAny)(invokeResult, { signal: ac.signal });
@@ -506,11 +510,13 @@ function _oneShotLlmCall(adapter, messages, config) {
         unsub();
         unsub = null;
       }
-      return () => {
-        unlinkParent();
-        ac.abort();
-        unsub?.();
-        unsub = null;
+      return {
+        onDeactivation: () => {
+          unlinkParent();
+          ac.abort();
+          unsub?.();
+          unsub = null;
+        }
       };
     },
     { describeKind: "producer" }
@@ -553,6 +559,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)) {
@@ -1586,9 +1612,11 @@ function _retrySource(source, opts, emitState) {
       const merged = makeMergedOptsMirror(opts);
       const getCfg = () => resolveRetryConfig(merged.current());
       const inner = _runRetryStateMachine(getCfg, () => source, a, emitState);
-      return () => {
-        inner();
-        merged.unsub();
+      return {
+        onDeactivation: () => {
+          inner();
+          merged.unsub();
+        }
       };
     },
     {
@@ -1612,9 +1640,11 @@ function _retryFactory(factory, opts, emitState) {
       const merged = makeMergedOptsMirror(opts);
       const getCfg = () => resolveRetryConfig(merged.current());
       const inner = _runRetryStateMachine(getCfg, factory, a, emitState);
-      return () => {
-        inner();
-        merged.unsub();
+      return {
+        onDeactivation: () => {
+          inner();
+          merged.unsub();
+        }
       };
     },
     {
@@ -1768,16 +1798,20 @@ var ToolRegistryGraph = class extends import_graph4.Graph {
           inner = handlerResultToNode(raw, ac.signal);
         } catch (err) {
           actions.down([[import_core10.ERROR, err]]);
-          return () => {
-            ac.abort();
+          return {
+            onDeactivation: () => {
+              ac.abort();
+            }
           };
         }
         const unsub = inner.subscribe((batch15) => {
           actions.down(batch15);
         });
-        return () => {
-          ac.abort();
-          unsub();
+        return {
+          onDeactivation: () => {
+            ac.abort();
+            unsub();
+          }
         };
       },
       {
@@ -2013,6 +2047,11 @@ var AgentLoopGraph = class extends import_graph5.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" }
@@ -2034,6 +2073,45 @@ var AgentLoopGraph = class extends import_graph5.Graph {
       },
       { describeKind: "effect" }
     );
+    const effFullDeny = gatedToolCallsNode !== toolCallsRaw ? (0, import_core11.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_core11.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_core11.DATA) latestStatus = m[1];
@@ -2053,6 +2131,7 @@ var AgentLoopGraph = class extends import_graph5.Graph {
     );
     const kaResponse = (0, import_extra7.keepalive)(effResponse);
     const kaResults = (0, import_extra7.keepalive)(effResults);
+    const kaFullDeny = effFullDeny ? (0, import_extra7.keepalive)(effFullDeny) : null;
     const kaAbort = (0, import_extra7.keepalive)(effAbort);
     this._terminalResult = (0, import_core11.node)(
       [statusNode, lastResponseState],
@@ -2105,6 +2184,7 @@ var AgentLoopGraph = class extends import_graph5.Graph {
     this.addDisposer(statusSub);
     this.addDisposer(kaResponse);
     this.addDisposer(kaResults);
+    if (kaFullDeny) this.addDisposer(kaFullDeny);
     this.addDisposer(kaAbort);
     this._disposeRunWiring = () => {
     };
@@ -3979,8 +4059,10 @@ function promptNode(adapter, deps, prompt, opts) {
           } catch (err) {
             done = true;
             actions.down([[import_core17.ERROR, err]]);
-            return () => {
-              abortDispose?.();
+            return {
+              onDeactivation: () => {
+                abortDispose?.();
+              }
             };
           }
           const callNode = (0, import_extra14.fromAny)(invokeResult);
@@ -4038,11 +4120,13 @@ function promptNode(adapter, deps, prompt, opts) {
               }
             }
           });
-          return () => {
-            cancelled = true;
-            sub();
-            abortDispose?.();
-            abortDispose = void 0;
+          return {
+            onDeactivation: () => {
+              cancelled = true;
+              sub();
+              abortDispose?.();
+              abortDispose = void 0;
+            }
           };
         },
         {
@@ -4609,9 +4693,11 @@ function heterogeneousDebate(parent, opts) {
             if (!cancelled) actions.down([[import_core21.ERROR, err]]);
           }
         })();
-        return () => {
-          cancelled = true;
-          ac.abort();
+        return {
+          onDeactivation: () => {
+            cancelled = true;
+            ac.abort();
+          }
         };
       },
       { describeKind: "producer", name: `${name}.round-work` }
@@ -4748,7 +4834,7 @@ function actorPool(parent, opts = {}) {
   const name = opts.name ?? `actorPool-${++_actorPoolSeq}`;
   const graph = new import_graph12.Graph(name);
   parent.mount(name, graph);
-  const depthCap = opts.depthCap ?? Number.POSITIVE_INFINITY;
+  const depthCap = opts.depthCap ?? 8;
   let autoActor = 0;
   const liveHandles = /* @__PURE__ */ new Set();
   const contextPool = taggedContextPool(graph, {
@@ -4852,6 +4938,16 @@ var import_core23 = require("@graphrefly/pure-ts/core");
 var import_extra20 = 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
@@ -4902,8 +4998,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
     });
     this.add(strategyNode, { name: "strategy" });
     const lastFeedbackState = (0, import_core23.node)([], {
-      name: "lastFeedback",
-      initial: null
+      name: "lastFeedback"
     });
     this.add(lastFeedbackState, { name: "lastFeedback" });
     const prevCandidatesState = (0, import_core23.node)([], {
@@ -4922,7 +5017,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
       // append-style; reactive consumers want every push
     });
     this.add(historyState, { name: "history" });
-    const bestState = (0, import_core23.node)([], { name: "best", initial: null });
+    const bestState = (0, import_core23.node)([], { name: "best" });
     this.add(bestState, { name: "best" });
     const scoreState = (0, import_core23.node)([], { name: "score", initial: Number.NEGATIVE_INFINITY });
     this.add(scoreState, { name: "score" });
@@ -4946,7 +5041,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) => {
@@ -4967,7 +5062,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_core23.node)(
           [],
           (_data, actions) => {
@@ -4983,8 +5078,10 @@ var RefineLoopGraph = class extends import_graph13.Graph {
                     if (!cancelled) actions.down([[import_core23.ERROR, err]]);
                   }
                 );
-                return () => {
-                  cancelled = true;
+                return {
+                  onDeactivation: () => {
+                    cancelled = true;
+                  }
                 };
               }
               actions.emit({ iter, items: result });
@@ -5357,7 +5454,7 @@ var RefineLoopGraph = class extends import_graph13.Graph {
           decision = "paused";
         }
         (0, import_core23.batch)(() => {
-          bestState.emit(best);
+          if (best !== null) bestState.emit(best);
           scoreState.emit(fb.score);
           historyState.emit(nextHistory);
           budgetState.emit(nextBudget);
@@ -5597,7 +5694,7 @@ function errorCritique(opts) {
 function defaultToOutput(result) {
   const { best, score, status } = result;
   const scoreStr = Number.isFinite(score) ? score.toFixed(3) : String(score);
-  const artifact = best ?? void 0;
+  const artifact = best;
   if (status === "converged") {
     return {
       outcome: "success",
@@ -5850,7 +5947,7 @@ function withStatus(src, options) {
           } else a.down([m]);
         }
       });
-      return unsub;
+      return { onDeactivation: unsub };
     },
     {
       ...operatorOpts(),
@@ -6075,7 +6172,7 @@ function withBreaker(breaker, options) {
           }
         });
         syncState();
-        return unsub;
+        return { onDeactivation: unsub };
       },
       {
         ...operatorOpts(),
@@ -6217,8 +6314,10 @@ function budgetGate(source, constraints, opts) {
           })
         );
       }
-      return () => {
-        for (const u of unsubs) u();
+      return {
+        onDeactivation: () => {
+          for (const u of unsubs) u();
+        }
       };
     },
     {
@@ -6348,9 +6447,11 @@ function fallback(source, fb, options) {
           } else a.down([m]);
         }
       });
-      return () => {
-        sourceUnsub?.();
-        fallbackUnsub?.();
+      return {
+        onDeactivation: () => {
+          sourceUnsub?.();
+          fallbackUnsub?.();
+        }
       };
     },
     {
@@ -6415,31 +6516,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_core30.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);
@@ -6562,11 +6672,13 @@ function rateLimiter(source, opts) {
           } else a.down([m]);
         }
       });
-      return () => {
-        terminated = true;
-        timer.cancel();
-        unsub();
-        optMirror.unsub();
+      return {
+        onDeactivation: () => {
+          terminated = true;
+          timer.cancel();
+          unsub();
+          optMirror.unsub();
+        }
       };
     },
     {
@@ -6808,6 +6920,10 @@ var PipelineGraph = class extends import_graph15.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)
       }
     );
@@ -7025,6 +7141,11 @@ var PipelineGraph = class extends import_graph15.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)
       }
     );
@@ -7227,7 +7348,10 @@ var JobQueueGraph = class extends import_graph17.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
@@ -7268,7 +7392,7 @@ var JobQueueGraph = class extends import_graph17.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) => {
@@ -7321,7 +7445,7 @@ var JobQueueGraph = class extends import_graph17.Graph {
       }
     );
     this._nackImpl = mutate(
-      (id, job, requeue) => {
+      (id, job, requeue, _error) => {
         if (requeue) {
           this._jobs.set(id, { ...job, state: "queued" });
           this._pending.append(id);
@@ -7334,12 +7458,16 @@ var JobQueueGraph = class extends import_graph17.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 } : {}
         })
       }
     );
@@ -7411,10 +7539,20 @@ var JobQueueGraph = class extends import_graph17.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;
   }
   /**
@@ -7580,10 +7718,10 @@ var JobFlowGraph = class extends import_graph17.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;
               }
@@ -7634,7 +7772,7 @@ var JobFlowGraph = class extends import_graph17.Graph {
                   } else if (m[0] === import_core33.ERROR) {
                     settled = true;
                     cleanupSub();
-                    current.nack(job.id, { requeue: false });
+                    current.nack(job.id, { requeue: false, error: m[1] });
                     return;
                   }
                 }
@@ -7890,7 +8028,18 @@ var HarnessGraph = class extends import_graph18.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;
@@ -9190,7 +9339,11 @@ function healthReportEqual(a, b) {
   }
   return true;
 }
-function graphLens(target) {
+function graphLens(target, opts = {}) {
+  const mutLogOpt = opts.mutations;
+  const mutationsEnabled = mutLogOpt != null;
+  const pendingFlowChanges = [];
+  let disposed = false;
   const topologyHandle = target.describe({
     reactive: true,
     detail: "standard",
@@ -9233,17 +9386,26 @@ function graphLens(target) {
           const path = event.path;
           if (path == null || path === "") continue;
           const prior = flowMap.get(path);
+          const count = (prior?.count ?? 0) + 1;
           flowMap.set(path, {
             path,
-            count: (prior?.count ?? 0) + 1,
+            count,
             lastUpdate_ns: c.flushedAt_ns
           });
+          if (mutationsEnabled && !disposed) {
+            pendingFlowChanges.push({ kind: "tick", path, count });
+          }
         }
       }
       if (desc != null && flowMap.size > 0) {
         const valid = new Set(Object.keys(desc.nodes));
         for (const k of [...flowMap.keys()]) {
-          if (!valid.has(k)) flowMap.delete(k);
+          if (!valid.has(k)) {
+            flowMap.delete(k);
+            if (mutationsEnabled && !disposed) {
+              pendingFlowChanges.push({ kind: "evict", path: k });
+            }
+          }
         }
       }
       actions.emit(new Map(flowMap));
@@ -9254,15 +9416,50 @@ function graphLens(target) {
       meta: domainMeta("lens", "flow")
     }
   );
+  let flowMutations;
+  let stopFlowMutKeep;
+  if (mutLogOpt != null) {
+    const log = (0, import_extra30.reactiveLog)(void 0, {
+      name: mutLogOpt === true ? "graphLens.flowMutations" : mutLogOpt.name ?? "graphLens.flowMutations",
+      maxSize: mutLogOpt === true ? void 0 : mutLogOpt.maxSize
+    });
+    flowMutations = log;
+    let mutVersion = 0;
+    const flowMutationsDrain = (0, import_core39.node)(
+      [flow],
+      (_batchData, _actions, _ctx) => {
+        if (pendingFlowChanges.length === 0) return;
+        const drained = pendingFlowChanges.splice(0);
+        for (const change of drained) {
+          log.append({
+            structure: "lensFlow",
+            version: ++mutVersion,
+            t_ns: (0, import_core39.wallClockNs)(),
+            lifecycle: "data",
+            change
+          });
+        }
+      },
+      {
+        name: "graphLens.flowMutationsDrain",
+        describeKind: "effect",
+        meta: domainMeta("lens", "flowMutations")
+      }
+    );
+    stopFlowMutKeep = (0, import_extra30.keepalive)(flowMutationsDrain);
+  }
   const stopFlowKeep = (0, import_extra30.keepalive)(flow);
-  let disposed = false;
   return {
     topology,
     health,
     flow,
+    ...flowMutations ? { flowMutations } : {},
     dispose() {
       if (disposed) return;
       disposed = true;
+      stopFlowMutKeep?.();
+      flowMutations?.dispose();
+      pendingFlowChanges.length = 0;
       stopFlowKeep();
       stopHealthKeep();
       topologyHandle.dispose();
@@ -9481,11 +9678,12 @@ var GuardedExecutionGraph = class extends import_graph26.Graph {
     this.addDisposer((0, import_extra31.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"
     });
@@ -9531,11 +9729,11 @@ var GuardedExecutionGraph = class extends import_graph26.Graph {
     const actorNode = actorOverride == null ? this._actorNode : isNode4(actorOverride) ? actorOverride : (0, import_core41.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 ?? {}
     });
@@ -9636,7 +9834,6 @@ var ResilientPipelineGraph = class extends import_graph27.Graph {
       } else {
         const rateOpts = {
           ...opts.rateLimit,
-          maxBuffer: opts.rateLimit.maxBuffer ?? Infinity,
           meta: domainMeta("resilient", "rate-limit")
         };
         const bundle = rateLimiter(current, rateOpts);