@graphrefly/graphrefly 0.25.0 → 0.27.0

package/dist/index.cjs

@@ -101,15 +101,20 @@ __export(index_exports, {
   ResettableTimer: () => ResettableTimer,
   SIZEOF_OVERHEAD: () => OVERHEAD,
   SIZEOF_SYMBOL: () => SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION: () => SNAPSHOT_VERSION,
+  SNAPSHOT_WIRE_VERSION: () => SNAPSHOT_WIRE_VERSION,
   START: () => START,
   START_MSG: () => START_MSG,
+  SurfaceError: () => SurfaceError,
   TEARDOWN: () => TEARDOWN,
   TEARDOWN_MSG: () => TEARDOWN_MSG,
   TEARDOWN_ONLY_BATCH: () => TEARDOWN_ONLY_BATCH,
   TimeoutError: () => TimeoutError,
   accessHintForGuard: () => accessHintForGuard,
+  accountability: () => audit_exports,
   advanceVersion: () => advanceVersion,
   ai: () => ai_exports,
+  asSurfaceError: () => asSurfaceError,
   audit: () => audit,
   autoTrackNode: () => autoTrackNode,
   batch: () => batch,
@@ -133,6 +138,7 @@ __export(index_exports, {
   cqrs: () => cqrs_exports,
   createDagCborCodec: () => createDagCborCodec,
   createDagCborZstdCodec: () => createDagCborZstdCodec,
+  createGraph: () => createGraph,
   createTransport: () => createTransport,
   createVersioning: () => createVersioning,
   createWatermarkController: () => createWatermarkController,
@@ -144,11 +150,13 @@ __export(index_exports, {
   defaultConfig: () => defaultConfig,
   defaultHash: () => defaultHash,
   delay: () => delay,
+  deleteSnapshot: () => deleteSnapshot,
   demoShell: () => demo_shell_exports,
   derived: () => derived,
   deserializeError: () => deserializeError,
   dictStorage: () => dictStorage,
   diffForWAL: () => diffForWAL,
+  diffSnapshots: () => diffSnapshots,
   distill: () => distill,
   distinctUntilChanged: () => distinctUntilChanged,
   domainTemplates: () => domain_templates_exports,
@@ -160,6 +168,7 @@ __export(index_exports, {
   encodeEnvelope: () => encodeEnvelope,
   escapeRegexChar: () => escapeRegexChar,
   exhaustMap: () => exhaustMap,
+  explainPath: () => explainPath,
   exponential: () => exponential,
   externalBundle: () => externalBundle,
   externalProducer: () => externalProducer,
@@ -215,6 +224,7 @@ __export(index_exports, {
   graph: () => graph_exports,
   graphProfile: () => graphProfile,
   graphspec: () => graphspec_exports,
+  guarded: () => guarded_execution_exports,
   harness: () => harness_exports,
   indexedDbStorage: () => indexedDbStorage,
   interval: () => interval,
@@ -224,7 +234,9 @@ __export(index_exports, {
   keepalive: () => keepalive,
   last: () => last,
   layout: () => reactive_layout_exports,
+  lens: () => lens_exports,
   linear: () => linear,
+  listSnapshots: () => listSnapshots,
   lru: () => lru,
   map: () => map2,
   matchesAnyPattern: () => matchesAnyPattern,
@@ -274,11 +286,15 @@ __export(index_exports, {
   replay: () => replay,
   replayWAL: () => replayWAL,
   rescue: () => rescue,
+  resilientPipeline: () => resilient_pipeline_exports,
   resolveBackoffPreset: () => resolveBackoffPreset,
   resolveDescribeFields: () => resolveDescribeFields,
+  restoreSnapshot: () => restoreSnapshot,
   retry: () => retry,
   retrySource: () => retrySource,
+  runReduction: () => runReduction,
   sample: () => sample,
+  saveSnapshot: () => saveSnapshot,
   scan: () => scan,
   serializeError: () => serializeError,
   share: () => share,
@@ -290,6 +306,7 @@ __export(index_exports, {
   solid: () => solid_exports,
   sqliteStorage: () => sqliteStorage,
   state: () => state,
+  surface: () => surface_exports,
   svelte: () => svelte_exports,
   switchMap: () => switchMap,
   take: () => take,
@@ -327,6 +344,7 @@ __export(index_exports, {
   version: () => version,
   vue: () => vue_exports,
   wallClockNs: () => wallClockNs,
+  watchTopologyTree: () => watchTopologyTree,
   window: () => window,
   windowCount: () => windowCount,
   windowTime: () => windowTime,
@@ -1338,6 +1356,12 @@ var NodeImpl = class _NodeImpl {
   _autoError;
   _pausable;
   _guard;
+  /**
+   * @internal Additional guards stacked at runtime via {@link NodeImpl._pushGuard}
+   * (e.g. by `policyEnforcer({ mode: "enforce" })`, roadmap §9.2). Effective
+   * write/signal/observe checks AND the original `_guard` with every entry here.
+   */
+  _extraGuards;
   _hashFn;
   _versioning;
   /**
@@ -1511,18 +1535,61 @@ var NodeImpl = class _NodeImpl {
       if (this._inspectorHooks?.size === 0) this._inspectorHooks = void 0;
     };
   }
+  /**
+   * @internal Push an additional guard onto this node. Effective enforcement
+   * is the AND of `_guard` and every guard pushed via this hook — any one
+   * rejecting throws {@link GuardDenied}. Returns a disposer that removes
+   * the pushed guard. Multiple guards may be stacked simultaneously.
+   *
+   * Used by `policyEnforcer({ mode: "enforce" })` (roadmap §9.2) to overlay
+   * runtime constraint enforcement onto an existing graph without rebuilding
+   * its nodes. Pre-1.0 internal API; not part of the public surface.
+   *
+   * **Identity semantics:** guards are tracked in a `Set`, so pushing the
+   * same `NodeGuard` reference twice is a single registration. Wrap each
+   * push in a unique closure if independent stacking is needed.
+   *
+   * **Iteration order:** insertion-ordered (`Set` semantics). Determinism
+   * follows from single-threaded JS execution; nested re-entry from inside
+   * a guard body (push/pop while iterating) is undefined-but-survivable.
+   */
+  _pushGuard(guard) {
+    if (this._extraGuards == null) this._extraGuards = /* @__PURE__ */ new Set();
+    this._extraGuards.add(guard);
+    return () => {
+      this._extraGuards?.delete(guard);
+      if (this._extraGuards?.size === 0) this._extraGuards = void 0;
+    };
+  }
   allowsObserve(actor) {
-    if (this._guard == null) return true;
-    return this._guard(normalizeActor(actor), "observe");
+    if (this._guard == null && this._extraGuards == null) return true;
+    const a = normalizeActor(actor);
+    if (this._guard != null && !this._guard(a, "observe")) return false;
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(a, "observe")) return false;
+      }
+    }
+    return true;
   }
   // --- Guard helper ---
   _checkGuard(options) {
-    if (options?.internal || this._guard == null) return;
+    if (options?.internal) return;
+    const hasGuard = this._guard != null || this._extraGuards != null;
+    const hasActor = options?.actor != null;
+    if (!hasGuard && !hasActor) return;
     const actor = normalizeActor(options?.actor);
     const action2 = options?.delivery === "signal" ? "signal" : "write";
-    if (!this._guard(actor, action2)) {
+    if (this._guard != null && !this._guard(actor, action2)) {
       throw new GuardDenied({ actor, action: action2, nodeName: this.name });
     }
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(actor, action2)) {
+          throw new GuardDenied({ actor, action: action2, nodeName: this.name });
+        }
+      }
+    }
     this._lastMutation = { actor, timestamp_ns: wallClockNs() };
   }
   // --- Public transport ---
@@ -3046,10 +3113,6 @@ function SagaHandler(cqrsName, sagaName, eventNames) {
   };
 }
 
-// src/extra/sources.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-
 // src/extra/cron.ts
 function parseField(field, min, max) {
   const result = /* @__PURE__ */ new Set();
@@ -3287,99 +3350,6 @@ function fromEvent(target, type, opts) {
     return () => target.removeEventListener(type, handler, options);
   }, sourceOpts(rest));
 }
-function fromFSWatch(paths, opts) {
-  const list = Array.isArray(paths) ? paths : [paths];
-  if (list.length === 0) {
-    throw new RangeError("fromFSWatch expects at least one path");
-  }
-  const { recursive = true, debounce: debounce2 = 100, include, exclude, ...rest } = opts ?? {};
-  const includePatterns = include?.map(globToRegExp) ?? [];
-  const excludePatterns = (exclude ?? ["**/node_modules/**", "**/.git/**", "**/dist/**"]).map(
-    globToRegExp
-  );
-  return producer((a) => {
-    const pending = /* @__PURE__ */ new Map();
-    const watchers = [];
-    let stopped = false;
-    let terminalEmitted = false;
-    let generation = 0;
-    const closeWatchers = () => {
-      for (const watcher of watchers.splice(0)) watcher.close();
-    };
-    const emitError = (err) => {
-      if (terminalEmitted) return;
-      terminalEmitted = true;
-      stopped = true;
-      if (timer !== void 0) clearTimeout(timer);
-      timer = void 0;
-      pending.clear();
-      closeWatchers();
-      a.down([[ERROR, err]]);
-    };
-    let timer;
-    const flush = (token) => {
-      timer = void 0;
-      if (stopped || terminalEmitted) return;
-      if (pending.size === 0) return;
-      const batchMessages = [];
-      for (const evt of pending.values()) batchMessages.push([DATA, evt]);
-      pending.clear();
-      if (stopped || terminalEmitted || token !== generation) return;
-      a.down(batchMessages);
-    };
-    try {
-      for (const basePath of list) {
-        const watcher = (0, import_node_fs.watch)(
-          basePath,
-          { recursive },
-          (eventType, fileName) => {
-            if (stopped || terminalEmitted) return;
-            if (fileName == null) return;
-            const rel = String(fileName).replaceAll("\\", "/");
-            const abs = (0, import_node_path.resolve)(basePath, String(fileName));
-            const normalized = abs.replaceAll("\\", "/");
-            const root = (0, import_node_path.resolve)(basePath).replaceAll("\\", "/");
-            const relForMatch = rel.startsWith("./") ? rel.slice(2) : rel;
-            const included = includePatterns.length === 0 || matchesAnyPattern(normalized, includePatterns) || matchesAnyPattern(relForMatch, includePatterns);
-            if (!included) return;
-            const excluded = matchesAnyPattern(normalized, excludePatterns) || matchesAnyPattern(relForMatch, excludePatterns);
-            if (excluded) return;
-            let kind = "change";
-            if (eventType === "rename") {
-              try {
-                kind = (0, import_node_fs.existsSync)(normalized) ? "create" : "delete";
-              } catch {
-                kind = "rename";
-              }
-            }
-            pending.set(normalized, {
-              type: kind,
-              path: normalized,
-              root,
-              relative_path: relForMatch,
-              timestamp_ns: wallClockNs()
-            });
-            if (timer !== void 0) clearTimeout(timer);
-            const token = generation;
-            timer = setTimeout(() => flush(token), debounce2);
-          }
-        );
-        watcher.on("error", (err) => emitError(err));
-        watchers.push(watcher);
-      }
-    } catch (err) {
-      emitError(err);
-    }
-    return () => {
-      stopped = true;
-      generation += 1;
-      if (timer !== void 0) clearTimeout(timer);
-      timer = void 0;
-      closeWatchers();
-      pending.clear();
-    };
-  }, sourceOpts(rest));
-}
 function fromIter(iterable, opts) {
   return producer((a) => {
     let cancelled = false;
@@ -4594,6 +4564,200 @@ var RingBuffer = class {
   }
 };
 
+// src/graph/explain.ts
+function explainPath(described, from, to, opts = {}) {
+  const fromExists = from in described.nodes;
+  const toExists = to in described.nodes;
+  if (!fromExists) return makeFailure(from, to, "no-such-from");
+  if (!toExists) return makeFailure(from, to, "no-such-to");
+  const maxDepth = opts.maxDepth;
+  if (maxDepth != null && (!Number.isInteger(maxDepth) || maxDepth < 0)) {
+    throw new Error(`explainPath: maxDepth must be an integer >= 0`);
+  }
+  if (from === to) {
+    if (opts.findCycle === true) {
+      const cycle = findShortestCycle(described, from, opts);
+      if (cycle != null) return cycle;
+    }
+    const step = buildStep(from, described.nodes[from], 0, opts);
+    return makeSuccess(from, to, [step]);
+  }
+  if (maxDepth === 0) return makeFailure(from, to, "no-path");
+  const result = bfsShortestPath(described, from, to, maxDepth);
+  if (!result.found) {
+    return makeFailure(from, to, result.truncated ? "max-depth-exceeded" : "no-path");
+  }
+  return makeSuccess(from, to, materializeSteps(described, result.pathOrder, opts));
+}
+function bfsShortestPath(described, from, to, maxDepth) {
+  const pred = /* @__PURE__ */ new Map();
+  const queue = [{ path: to, depth: 0 }];
+  const visited = /* @__PURE__ */ new Set([to]);
+  let head = 0;
+  let truncated = false;
+  while (head < queue.length) {
+    const cur = queue[head++];
+    if (cur.path === from) break;
+    if (maxDepth != null && cur.depth >= maxDepth) {
+      const node3 = described.nodes[cur.path];
+      if (node3?.deps && node3.deps.length > 0) truncated = true;
+      continue;
+    }
+    const node2 = described.nodes[cur.path];
+    if (node2 == null) continue;
+    const deps = node2.deps ?? [];
+    const slots = /* @__PURE__ */ new Map();
+    for (let i = 0; i < deps.length; i++) {
+      const dep = deps[i];
+      if (!dep) continue;
+      let arr = slots.get(dep);
+      if (arr == null) {
+        arr = [];
+        slots.set(dep, arr);
+      }
+      arr.push(i);
+    }
+    for (const [dep, indices] of slots) {
+      if (visited.has(dep)) continue;
+      visited.add(dep);
+      pred.set(dep, { from: cur.path, depIndices: indices });
+      queue.push({ path: dep, depth: cur.depth + 1 });
+    }
+  }
+  if (!pred.has(from)) {
+    return { found: false, pathOrder: [], truncated };
+  }
+  const pathOrder = [{ path: from }];
+  let cursor = from;
+  while (cursor !== to) {
+    const p = pred.get(cursor);
+    if (p == null) return { found: false, pathOrder: [], truncated: false };
+    pathOrder[pathOrder.length - 1].depIndices = p.depIndices;
+    pathOrder.push({ path: p.from });
+    cursor = p.from;
+  }
+  return { found: true, pathOrder, truncated: false };
+}
+function findShortestCycle(described, start, opts) {
+  const startNode = described.nodes[start];
+  if (startNode == null) return null;
+  const startDeps = startNode.deps ?? [];
+  const selfSlots = [];
+  for (let i = 0; i < startDeps.length; i++) if (startDeps[i] === start) selfSlots.push(i);
+  if (selfSlots.length > 0) {
+    const step0 = buildStep(start, startNode, 0, opts);
+    step0.dep_index = selfSlots[0];
+    const step1 = buildStep(start, startNode, 1, opts);
+    return makeSuccess(start, start, [step0, step1]);
+  }
+  let best = null;
+  for (let i = 0; i < startDeps.length; i++) {
+    const dep = startDeps[i];
+    if (!dep || dep === start) continue;
+    const sub = bfsShortestPath(described, dep, start, opts.maxDepth);
+    if (!sub.found) continue;
+    if (best == null || sub.pathOrder.length < best.pathOrder.length) {
+      best = sub;
+      best = {
+        found: true,
+        pathOrder: [{ path: start, depIndices: [i] }, ...sub.pathOrder],
+        truncated: false
+      };
+    }
+  }
+  if (best == null) return null;
+  return makeSuccess(start, start, materializeSteps(described, best.pathOrder, opts));
+}
+function materializeSteps(described, pathOrder, opts) {
+  return pathOrder.map((entry, i) => {
+    const node2 = described.nodes[entry.path];
+    const step = buildStep(entry.path, node2, i, opts);
+    if (entry.depIndices != null && entry.depIndices.length > 0) {
+      step.dep_index = entry.depIndices[0];
+      if (entry.depIndices.length > 1) step.dep_indices = [...entry.depIndices];
+    }
+    return step;
+  });
+}
+function buildStep(path, node2, hop, opts) {
+  const step = {
+    path,
+    type: node2.type,
+    hop
+  };
+  if (node2.status !== void 0) step.status = node2.status;
+  if ("value" in node2) step.value = node2.value;
+  if (node2.v != null) step.v = node2.v;
+  const annotation = opts.annotations?.get(path) ?? node2.reason;
+  if (annotation != null) step.reason = annotation;
+  const lastMutation = opts.lastMutations?.get(path) ?? node2.lastMutation;
+  if (lastMutation != null) step.lastMutation = lastMutation;
+  return step;
+}
+function makeSuccess(from, to, steps) {
+  return finalize(from, to, true, "ok", steps);
+}
+function makeFailure(from, to, reason) {
+  return finalize(from, to, false, reason, []);
+}
+function finalize(from, to, found, reason, steps) {
+  const text = renderChain(from, to, found, reason, steps);
+  return {
+    from,
+    to,
+    found,
+    reason,
+    steps,
+    text,
+    toJSON() {
+      return { from, to, found, reason, steps };
+    }
+  };
+}
+function renderChain(from, to, found, reason, steps) {
+  if (!found) {
+    switch (reason) {
+      case "no-such-from":
+        return `explainPath: no node named "${from}"`;
+      case "no-such-to":
+        return `explainPath: no node named "${to}"`;
+      case "max-depth-exceeded":
+        return `explainPath: no path from "${from}" to "${to}" within maxDepth`;
+      default:
+        return `explainPath: no path from "${from}" to "${to}"`;
+    }
+  }
+  const lines = [`Causal path: ${from} \u2192 ${to} (${steps.length} step(s))`];
+  for (const step of steps) {
+    const arrow = step.hop === 0 ? "\xB7" : "\u2193";
+    const head = `  ${arrow} ${step.path} (${step.type}${step.status ? `/${step.status}` : ""})`;
+    lines.push(head);
+    if ("value" in step) {
+      lines.push(`      value: ${formatValue(step.value)}`);
+    }
+    if (step.reason != null) {
+      lines.push(`      reason: ${step.reason}`);
+    }
+    if (step.lastMutation != null) {
+      const a = step.lastMutation.actor;
+      lines.push(`      actor: ${a.type}${a.id ? `:${a.id}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatValue(v) {
+  if (v === void 0) return "<sentinel>";
+  if (v === null) return "null";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+  try {
+    const s = JSON.stringify(v);
+    return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+  } catch {
+    return String(v);
+  }
+}
+
 // src/extra/utils/sizeof.ts
 var OVERHEAD = {
   object: 56,
@@ -5227,6 +5391,20 @@ var Graph = class _Graph {
   _parent = void 0;
   _storageDisposers = /* @__PURE__ */ new Set();
   _disposers = /* @__PURE__ */ new Set();
+  /**
+   * @internal Lazy `TopologyEvent` producer. Created on first `.topology`
+   * access. Zero cost until something subscribes — producer fn only runs when
+   * the first sink attaches, registering one handler into
+   * {@link Graph._topologyEmitters}.
+   */
+  _topology;
+  /**
+   * @internal Active emit handlers for the topology producer. Each entry is
+   * the closure registered by the producer fn on activation; cleared on
+   * deactivation. `_emitTopology` broadcasts through every entry (there is at
+   * most one per activation cycle of the producer).
+   */
+  _topologyEmitters = /* @__PURE__ */ new Set();
   /**
    * @param name - Non-empty graph id (must not contain `::` and must not
    *   equal the reserved meta segment `__meta__`).
@@ -5266,6 +5444,55 @@ var Graph = class _Graph {
     return out;
   }
   // ——————————————————————————————————————————————————————————————
+  //  Topology companion (structural-change event stream)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Reactive stream of structural changes to this graph's own registry
+   * (add / mount / remove). Value mutations live on `observe()`; this
+   * companion only fires when the topology shape changes.
+   *
+   * Lazy: the underlying node is created on first access and activates when
+   * something subscribes. No emission replay — late subscribers do not
+   * receive historical events and should snapshot via {@link Graph.describe}
+   * before listening for incremental changes. Events that fire while the
+   * producer has zero subscribers are dropped (no retention).
+   *
+   * Own-graph only: a parent's `topology` does NOT emit for structural
+   * changes inside a mounted child. Transitive consumers subscribe to each
+   * child's topology separately (recurse through `topology`'s own "added"
+   * events with `nodeKind: "mount"` to discover new children).
+   *
+   * See {@link TopologyEvent} for payload shape.
+   *
+   * @category observability
+   */
+  get topology() {
+    if (this._topology == null) {
+      this._topology = producer(
+        (actions) => {
+          const handler = (event) => {
+            actions.emit(event);
+          };
+          this._topologyEmitters.add(handler);
+          return () => {
+            this._topologyEmitters.delete(handler);
+          };
+        },
+        { name: `${this.name}_topology` }
+      );
+    }
+    return this._topology;
+  }
+  /**
+   * @internal Fire a {@link TopologyEvent} to every active subscriber of
+   * `this.topology`. No-op when the topology node has never been accessed or
+   * currently has no sinks — zero cost for graphs nobody observes.
+   */
+  _emitTopology(event) {
+    if (this._topology == null || this._topologyEmitters.size === 0) return;
+    for (const h of this._topologyEmitters) h(event);
+  }
+  // ——————————————————————————————————————————————————————————————
   //  Node registry
   // ——————————————————————————————————————————————————————————————
   /**
@@ -5295,6 +5522,7 @@ var Graph = class _Graph {
     }
     this._nodes.set(name, node2);
     this._nodeToName.set(node2, name);
+    this._emitTopology({ kind: "added", name, nodeKind: "node" });
     return node2;
   }
   /**
@@ -5335,22 +5563,23 @@ var Graph = class _Graph {
     assertRegisterableName(name, this.name, "remove");
     const child = this._mounts.get(name);
     if (child) {
-      const audit2 = { kind: "mount", nodes: [], mounts: [] };
+      const audit3 = { kind: "mount", nodes: [], mounts: [] };
       const targets = [];
       child._collectObserveTargets("", targets);
       for (const [p, n] of targets) {
         if (!p.includes(`${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}`)) {
-          audit2.nodes.push(p);
+          audit3.nodes.push(p);
         }
         void n;
       }
-      audit2.nodes.sort();
-      audit2.mounts.push(name);
-      audit2.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
+      audit3.nodes.sort();
+      audit3.mounts.push(name);
+      audit3.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
       this._mounts.delete(name);
       child._parent = void 0;
       teardownMountedGraph(child);
-      return audit2;
+      this._emitTopology({ kind: "removed", name, nodeKind: "mount", audit: audit3 });
+      return audit3;
     }
     const node2 = this._nodes.get(name);
     if (!node2) {
@@ -5359,7 +5588,9 @@ var Graph = class _Graph {
     this._nodes.delete(name);
     this._nodeToName.delete(node2);
     node2.down([[TEARDOWN]], { internal: true });
-    return { kind: "node", nodes: [name], mounts: [] };
+    const audit2 = { kind: "node", nodes: [name], mounts: [] };
+    this._emitTopology({ kind: "removed", name, nodeKind: "node", audit: audit2 });
+    return audit2;
   }
   /**
    * Bulk remove — invokes {@link Graph.remove} for every local name matching
@@ -5588,6 +5819,7 @@ var Graph = class _Graph {
     }
     this._mounts.set(name, child);
     child._parent = this;
+    this._emitTopology({ kind: "added", name, nodeKind: "mount" });
     return child;
   }
   /**
@@ -5878,6 +6110,33 @@ var Graph = class _Graph {
     }
     return reachable(this.describe(), from, direction, opts);
   }
+  /**
+   * Causal walkback: shortest dep-chain from `from` to `to`, enriched with
+   * each node's value, status, last-mutation actor, and reasoning annotation
+   * from {@link Graph.trace}. Wraps {@link explainPath} (roadmap §9.2).
+   *
+   * @param from - Upstream node (the cause).
+   * @param to - Downstream node (the effect).
+   * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+   *   and `from === to`, returns the shortest cycle through other nodes
+   *   (useful for diagnosing feedback loops, COMPOSITION-GUIDE §7).
+   *   Annotations and lastMutations are collected automatically from the
+   *   live graph.
+   */
+  explain(from, to, opts) {
+    const described = this.describe({ detail: "full" });
+    const annotations = new Map(this._annotations);
+    const lastMutations = /* @__PURE__ */ new Map();
+    for (const [path, n] of Object.entries(described.nodes)) {
+      if (n.lastMutation != null) lastMutations.set(path, n.lastMutation);
+    }
+    return explainPath(described, from, to, {
+      ...opts?.maxDepth != null ? { maxDepth: opts.maxDepth } : {},
+      ...opts?.findCycle === true ? { findCycle: true } : {},
+      annotations,
+      lastMutations
+    });
+  }
   /**
    * @internal Collect all qualified paths in this graph tree matching a
    * glob pattern. Used by scoped autoCheckpoint subscription.
@@ -6556,7 +6815,7 @@ var Graph = class _Graph {
         return;
       }
       const nextSeq = s.seq + 1;
-      const timestamp_ns = monotonicNs();
+      const timestamp_ns = wallClockNs();
       const isFirst = s.lastSnapshot == null;
       const shouldCompact = isFirst || nextSeq % s.compactEvery === 0;
       const record = shouldCompact ? {
@@ -7330,18 +7589,67 @@ __export(graph_exports, {
   JsonCodec: () => JsonCodec,
   SIZEOF_OVERHEAD: () => OVERHEAD,
   SIZEOF_SYMBOL: () => SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION: () => SNAPSHOT_VERSION,
   createDagCborCodec: () => createDagCborCodec,
   createDagCborZstdCodec: () => createDagCborZstdCodec,
   decodeEnvelope: () => decodeEnvelope,
   diffForWAL: () => diffForWAL,
   encodeEnvelope: () => encodeEnvelope,
+  explainPath: () => explainPath,
   graphProfile: () => graphProfile,
   reachable: () => reachable,
   registerBuiltinCodecs: () => registerBuiltinCodecs,
   replayWAL: () => replayWAL,
-  sizeof: () => sizeof
+  sizeof: () => sizeof,
+  watchTopologyTree: () => watchTopologyTree
 });
 
+// src/graph/topology-tree.ts
+function watchTopologyTree(graph, cb) {
+  const subs = /* @__PURE__ */ new Map();
+  const wire = (g, prefix) => {
+    if (subs.has(g)) return;
+    const placeholder = { off: () => {
+    }, prefix };
+    subs.set(g, placeholder);
+    const off = g.topology.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] !== DATA) continue;
+        const event = m[1];
+        cb(event, g, prefix);
+        if (event.kind === "added" && event.nodeKind === "mount") {
+          const child = g._mounts.get(event.name);
+          if (child instanceof Graph) {
+            const childPrefix = `${prefix}${event.name}::`;
+            wire(child, childPrefix);
+          }
+        } else if (event.kind === "removed" && event.nodeKind === "mount") {
+          const removedPrefix = `${prefix}${event.name}::`;
+          for (const [trackedGraph, trackedEntry] of Array.from(subs.entries())) {
+            if (trackedGraph === graph) continue;
+            if (trackedEntry.prefix.startsWith(removedPrefix)) {
+              trackedEntry.off();
+              subs.delete(trackedGraph);
+            }
+          }
+        }
+      }
+    });
+    placeholder.off = off;
+    for (const [mountName, child] of g._mounts) {
+      if (child instanceof Graph) {
+        const childPrefix = `${prefix}${mountName}::`;
+        wire(child, childPrefix);
+      }
+    }
+  };
+  wire(graph, "");
+  return () => {
+    for (const entry of subs.values()) entry.off();
+    subs.clear();
+  };
+}
+
 // src/patterns/_internal.ts
 function emitToMeta(metaNode, value) {
   if (metaNode == null) return;
@@ -14210,71 +14518,212 @@ function reactiveList(initial, options = {}) {
   };
 }
 
-// src/extra/storage.ts
-var import_node_crypto = require("crypto");
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
-var import_node_sqlite = require("sqlite");
-function sortJsonValue2(value) {
-  if (value === null || typeof value !== "object") return value;
-  if (Array.isArray(value)) return value.map(sortJsonValue2);
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  const out = {};
-  for (const k of keys) out[k] = sortJsonValue2(obj[k]);
-  return out;
-}
-function stableJsonString(data) {
-  return JSON.stringify(sortJsonValue2(data), void 0, 0);
-}
-function memoryStorage() {
-  const data = /* @__PURE__ */ new Map();
-  return {
-    save(key, record) {
-      data.set(key, JSON.parse(JSON.stringify(record)));
-    },
-    load(key) {
-      const v = data.get(key);
-      return v === void 0 ? null : JSON.parse(JSON.stringify(v));
-    },
-    clear(key) {
-      data.delete(key);
-    }
-  };
-}
-function dictStorage(storage) {
-  return {
-    save(key, record) {
-      storage[key] = JSON.parse(JSON.stringify(record));
-    },
-    load(key) {
-      const raw = storage[key];
-      return raw === void 0 ? null : JSON.parse(JSON.stringify(raw));
-    },
-    clear(key) {
-      delete storage[key];
-    }
-  };
+// src/extra/sources-fs.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function sourceOpts4(opts) {
+  return { describeKind: "producer", ...opts };
 }
-function fileStorage(dir) {
-  const pathFor = (key) => {
-    const safe = key.replace(
-      /[^a-zA-Z0-9_-]/g,
-      (c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`
-    );
-    return (0, import_node_path2.join)(dir, `${safe}.json`);
-  };
-  return {
-    save(key, record) {
-      (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
-      const filePath = pathFor(key);
-      const payload = `${stableJsonString(record)}
-`;
-      const base = (0, import_node_path2.basename)(filePath);
-      const d = (0, import_node_path2.dirname)(filePath);
-      const tmp = (0, import_node_path2.join)(d, `.${base}.${(0, import_node_crypto.randomBytes)(8).toString("hex")}.tmp`);
-      try {
-        (0, import_node_fs2.writeFileSync)(tmp, payload, "utf8");
+function fromFSWatch(paths, opts) {
+  const list = Array.isArray(paths) ? paths : [paths];
+  if (list.length === 0) {
+    throw new RangeError("fromFSWatch expects at least one path");
+  }
+  const { recursive = true, debounce: debounce2 = 100, include, exclude, ...rest } = opts ?? {};
+  const includePatterns = include?.map(globToRegExp) ?? [];
+  const excludePatterns = (exclude ?? ["**/node_modules/**", "**/.git/**", "**/dist/**"]).map(
+    globToRegExp
+  );
+  return producer((a) => {
+    const pending = /* @__PURE__ */ new Map();
+    const watchers = [];
+    let stopped = false;
+    let terminalEmitted = false;
+    let generation = 0;
+    const closeWatchers = () => {
+      for (const watcher of watchers.splice(0)) watcher.close();
+    };
+    const emitError = (err) => {
+      if (terminalEmitted) return;
+      terminalEmitted = true;
+      stopped = true;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      pending.clear();
+      closeWatchers();
+      a.down([[ERROR, err]]);
+    };
+    let timer;
+    const flush = (token) => {
+      timer = void 0;
+      if (stopped || terminalEmitted) return;
+      if (pending.size === 0) return;
+      const batchMessages = [];
+      for (const evt of pending.values()) batchMessages.push([DATA, evt]);
+      pending.clear();
+      if (stopped || terminalEmitted || token !== generation) return;
+      a.down(batchMessages);
+    };
+    try {
+      for (const basePath of list) {
+        const watcher = (0, import_node_fs.watch)(
+          basePath,
+          { recursive },
+          (eventType, fileName) => {
+            if (stopped || terminalEmitted) return;
+            if (fileName == null) return;
+            const rel = String(fileName).replaceAll("\\", "/");
+            const abs = (0, import_node_path.resolve)(basePath, String(fileName));
+            const normalized = abs.replaceAll("\\", "/");
+            const root = (0, import_node_path.resolve)(basePath).replaceAll("\\", "/");
+            const relForMatch = rel.startsWith("./") ? rel.slice(2) : rel;
+            const included = includePatterns.length === 0 || matchesAnyPattern(normalized, includePatterns) || matchesAnyPattern(relForMatch, includePatterns);
+            if (!included) return;
+            const excluded = matchesAnyPattern(normalized, excludePatterns) || matchesAnyPattern(relForMatch, excludePatterns);
+            if (excluded) return;
+            let kind = "change";
+            if (eventType === "rename") {
+              try {
+                kind = (0, import_node_fs.existsSync)(normalized) ? "create" : "delete";
+              } catch {
+                kind = "rename";
+              }
+            }
+            pending.set(normalized, {
+              type: kind,
+              path: normalized,
+              root,
+              relative_path: relForMatch,
+              timestamp_ns: wallClockNs()
+            });
+            if (timer !== void 0) clearTimeout(timer);
+            const token = generation;
+            timer = setTimeout(() => flush(token), debounce2);
+          }
+        );
+        watcher.on("error", (err) => emitError(err));
+        watchers.push(watcher);
+      }
+    } catch (err) {
+      emitError(err);
+    }
+    return () => {
+      stopped = true;
+      generation += 1;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      closeWatchers();
+      pending.clear();
+    };
+  }, sourceOpts4(rest));
+}
+
+// src/extra/storage.ts
+var import_node_crypto = require("node:crypto");
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+var import_node_sqlite = require("node:sqlite");
+function sortJsonValue2(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(sortJsonValue2);
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const out = {};
+  for (const k of keys) out[k] = sortJsonValue2(obj[k]);
+  return out;
+}
+function stableJsonString(data) {
+  return JSON.stringify(sortJsonValue2(data), void 0, 0);
+}
+function memoryStorage() {
+  const data = /* @__PURE__ */ new Map();
+  return {
+    save(key, record) {
+      data.set(key, JSON.parse(JSON.stringify(record)));
+    },
+    load(key) {
+      const v = data.get(key);
+      return v === void 0 ? null : JSON.parse(JSON.stringify(v));
+    },
+    clear(key) {
+      data.delete(key);
+    },
+    list() {
+      return [...data.keys()].sort();
+    }
+  };
+}
+function dictStorage(storage) {
+  return {
+    save(key, record) {
+      storage[key] = JSON.parse(JSON.stringify(record));
+    },
+    load(key) {
+      const raw = storage[key];
+      return raw === void 0 ? null : JSON.parse(JSON.stringify(raw));
+    },
+    clear(key) {
+      delete storage[key];
+    },
+    list() {
+      return Object.keys(storage).sort();
+    }
+  };
+}
+function fileStorage(dir) {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const pathFor = (key) => {
+    let out = "";
+    for (const ch of key) {
+      if (ch.length === 1 && /[a-zA-Z0-9_-]/.test(ch)) {
+        out += ch;
+        continue;
+      }
+      for (const byte of encoder.encode(ch)) {
+        out += `%${byte.toString(16).padStart(2, "0")}`;
+      }
+    }
+    return (0, import_node_path2.join)(dir, `${out}.json`);
+  };
+  const keyFromFilename = (filename) => {
+    if (!filename.endsWith(".json")) return null;
+    const stem = filename.slice(0, -".json".length);
+    const bytes = [];
+    const encodeAscii = (s) => {
+      for (let i2 = 0; i2 < s.length; i2++) bytes.push(s.charCodeAt(i2));
+    };
+    let i = 0;
+    while (i < stem.length) {
+      const ch = stem[i];
+      if (ch === "%" && i + 2 < stem.length) {
+        const hex = stem.slice(i + 1, i + 3);
+        if (/^[0-9a-f]{2}$/i.test(hex)) {
+          bytes.push(Number.parseInt(hex, 16));
+          i += 3;
+          continue;
+        }
+      }
+      encodeAscii(ch);
+      i += 1;
+    }
+    try {
+      return decoder.decode(new Uint8Array(bytes));
+    } catch {
+      return null;
+    }
+  };
+  return {
+    save(key, record) {
+      (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+      const filePath = pathFor(key);
+      const payload = `${stableJsonString(record)}
+`;
+      const base = (0, import_node_path2.basename)(filePath);
+      const d = (0, import_node_path2.dirname)(filePath);
+      const tmp = (0, import_node_path2.join)(d, `.${base}.${(0, import_node_crypto.randomBytes)(8).toString("hex")}.tmp`);
+      try {
+        (0, import_node_fs2.writeFileSync)(tmp, payload, "utf8");
         (0, import_node_fs2.renameSync)(tmp, filePath);
       } catch (e) {
         try {
@@ -14299,6 +14748,21 @@ function fileStorage(dir) {
       } catch (e) {
         if (e.code !== "ENOENT") throw e;
       }
+    },
+    list() {
+      try {
+        const entries = (0, import_node_fs2.readdirSync)(dir);
+        const keys = [];
+        for (const entry of entries) {
+          if (entry.startsWith(".")) continue;
+          const k = keyFromFilename(entry);
+          if (k !== null) keys.push(k);
+        }
+        return keys.sort();
+      } catch (e) {
+        if (e.code === "ENOENT") return [];
+        throw e;
+      }
     }
   };
 }
@@ -14321,6 +14785,10 @@ function sqliteStorage(path) {
     clear(key) {
       db.prepare(`DELETE FROM graphrefly_checkpoint WHERE k = ?`).run(key);
     },
+    list() {
+      const rows = db.prepare(`SELECT k FROM graphrefly_checkpoint ORDER BY k`).all();
+      return rows.map((r) => r.k);
+    },
     close() {
       try {
         db.close();
@@ -14970,17 +15438,32 @@ function workerSelf(target, opts) {
 // src/patterns/index.ts
 var patterns_exports = {};
 __export(patterns_exports, {
+  SNAPSHOT_WIRE_VERSION: () => SNAPSHOT_WIRE_VERSION,
+  SurfaceError: () => SurfaceError,
+  accountability: () => audit_exports,
   ai: () => ai_exports,
+  asSurfaceError: () => asSurfaceError,
   cqrs: () => cqrs_exports,
+  createGraph: () => createGraph,
+  deleteSnapshot: () => deleteSnapshot,
   demoShell: () => demo_shell_exports,
+  diffSnapshots: () => diffSnapshots,
   domainTemplates: () => domain_templates_exports,
   graphspec: () => graphspec_exports,
+  guarded: () => guarded_execution_exports,
   harness: () => harness_exports,
   layout: () => reactive_layout_exports,
+  lens: () => lens_exports,
+  listSnapshots: () => listSnapshots,
   memory: () => memory_exports,
   messaging: () => messaging_exports,
   orchestration: () => orchestration_exports,
-  reduction: () => reduction_exports
+  reduction: () => reduction_exports,
+  resilientPipeline: () => resilient_pipeline_exports,
+  restoreSnapshot: () => restoreSnapshot,
+  runReduction: () => runReduction,
+  saveSnapshot: () => saveSnapshot,
+  surface: () => surface_exports
 });
 
 // src/patterns/ai.ts
@@ -18018,6 +18501,420 @@ async function suggestStrategy(graph, problem, adapter, opts) {
   };
 }
 
+// src/patterns/audit.ts
+var audit_exports = {};
+__export(audit_exports, {
+  AuditTrailGraph: () => AuditTrailGraph,
+  PolicyEnforcerGraph: () => PolicyEnforcerGraph,
+  auditTrail: () => auditTrail,
+  complianceSnapshot: () => complianceSnapshot,
+  policyEnforcer: () => policyEnforcer,
+  reactiveExplainPath: () => reactiveExplainPath
+});
+function auditMeta(kind, extra) {
+  return domainMeta("audit", kind, extra);
+}
+var DEFAULT_INCLUDE_TYPES = /* @__PURE__ */ new Set([
+  "data",
+  "error",
+  "complete",
+  "teardown"
+]);
+var AuditTrailGraph = class extends Graph {
+  entries;
+  count;
+  _log;
+  _target;
+  constructor(target, opts) {
+    super(opts.name ?? `${target.name}_audit`, opts.graph);
+    this._target = target;
+    this._log = reactiveLog([], {
+      name: "entries",
+      ...opts.maxSize != null ? { maxSize: opts.maxSize } : {}
+    });
+    this.entries = this._log.entries;
+    this.add("entries", this.entries);
+    this.count = derived(
+      [this.entries],
+      ([snapshot]) => snapshot.length,
+      { name: "count", describeKind: "derived", meta: auditMeta("count") }
+    );
+    this.add("count", this.count);
+    this.addDisposer(keepalive(this.count));
+    const includeTypes = opts.includeTypes != null ? new Set(opts.includeTypes) : DEFAULT_INCLUDE_TYPES;
+    const filter2 = opts.filter;
+    let seq = 0;
+    const handle = target.observe({ timeline: true, structured: true });
+    const offEvent = handle.onEvent((event) => {
+      if (event.type === "derived") return;
+      const type = event.type;
+      if (!includeTypes.has(type)) return;
+      const path = event.path ?? "";
+      const entry = {
+        seq: seq++,
+        timestamp_ns: event.timestamp_ns ?? monotonicNs(),
+        wall_clock_ns: wallClockNs(),
+        path,
+        type
+      };
+      const node2 = path ? safeNode(target, path) : void 0;
+      const lastMutation = node2?.lastMutation;
+      if (lastMutation != null) entry.actor = lastMutation.actor;
+      if (type === "data") entry.value = event.data;
+      if (type === "error") entry.error = event.data;
+      const reason = path ? safeAnnotation(target, path) : void 0;
+      if (reason != null) entry.reason = reason;
+      if (filter2 != null && !filter2(entry)) return;
+      this._log.append(entry);
+    });
+    this.addDisposer(() => {
+      offEvent();
+      handle.dispose();
+    });
+    this.addDisposer(() => this._log.disposeAllViews());
+  }
+  /** All entries currently in the ring (snapshot). */
+  all() {
+    return this.entries.cache ?? [];
+  }
+  /** Entries matching `path`. Order preserved. */
+  byNode(path) {
+    return this.all().filter((e) => e.path === path);
+  }
+  /** Entries whose `actor.id` matches. Use `byActorType` for type filtering. */
+  byActor(actorId) {
+    return this.all().filter((e) => e.actor?.id === actorId);
+  }
+  /** Entries whose `actor.type` matches (e.g. `"llm"`, `"human"`). */
+  byActorType(type) {
+    return this.all().filter((e) => e.actor?.type === type);
+  }
+  /**
+   * Entries with `timestamp_ns` in `[start_ns, end_ns)` (end exclusive).
+   * Omit `end_ns` to query open-ended.
+   */
+  byTimeRange(start_ns, end_ns) {
+    return this.all().filter((e) => {
+      if (e.timestamp_ns < start_ns) return false;
+      if (end_ns != null && e.timestamp_ns >= end_ns) return false;
+      return true;
+    });
+  }
+  /** Reference to the audited graph (escape hatch for tooling). */
+  get target() {
+    return this._target;
+  }
+};
+function auditTrail(target, opts = {}) {
+  return new AuditTrailGraph(target, opts);
+}
+var PolicyEnforcerGraph = class extends Graph {
+  policies;
+  violations;
+  violationCount;
+  _target;
+  _mode;
+  _currentGuard;
+  constructor(target, policies, opts) {
+    super(opts.name ?? `${target.name}_policy`, opts.graph);
+    this._target = target;
+    this._mode = opts.mode ?? "audit";
+    const policiesNode = isNode3(policies) ? policies : state(policies, { name: "policies" });
+    this.policies = policiesNode;
+    this.add("policies", this.policies);
+    this.violations = new TopicGraph("violations", {
+      retainedLimit: opts.violationsLimit ?? 1e3
+    });
+    this.mount("violations", this.violations);
+    this.violationCount = derived(
+      [this.violations.events],
+      ([snapshot]) => snapshot.length,
+      {
+        name: "violationCount",
+        describeKind: "derived",
+        meta: auditMeta("policy_violation_count")
+      }
+    );
+    this.add("violationCount", this.violationCount);
+    this.addDisposer(keepalive(this.violationCount));
+    const initialRules = policiesNode.cache ?? [];
+    let latestRules = initialRules;
+    this._currentGuard = policyFromRules(latestRules);
+    const offPolicies = policiesNode.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA) {
+          latestRules = m[1] ?? [];
+          this._currentGuard = policyFromRules(latestRules);
+        }
+      }
+    });
+    this.addDisposer(offPolicies);
+    const paths = opts.paths != null ? [...opts.paths] : collectPaths(target);
+    if (this._mode === "enforce") {
+      const restorers = /* @__PURE__ */ new Map();
+      const wrapAndPush = (path) => {
+        if (restorers.has(path)) return;
+        const node2 = safeNode(target, path);
+        if (!(node2 instanceof NodeImpl)) return;
+        const pathGuard = (actor, action2) => {
+          const ok = this._currentGuard(actor, action2);
+          if (!ok) {
+            this._publishViolation(actor, action2, path, "blocked");
+          }
+          return ok;
+        };
+        restorers.set(path, node2._pushGuard(pathGuard));
+      };
+      for (const path of paths) wrapAndPush(path);
+      if (opts.paths == null) {
+        const offTopology = watchTopologyTree(target, (event, emitter, prefix) => {
+          if (event.kind === "added") {
+            if (event.nodeKind === "node") {
+              wrapAndPush(`${prefix}${event.name}`);
+            } else {
+              const child = emitter._mounts.get(event.name);
+              if (!(child instanceof Graph)) return;
+              const mountPrefix = `${prefix}${event.name}::`;
+              const localPaths = collectPaths(child);
+              for (const localPath of localPaths) {
+                wrapAndPush(
+                  localPath === "" ? `${prefix}${event.name}` : `${mountPrefix}${localPath}`
+                );
+              }
+            }
+          } else if (event.kind === "removed") {
+            if (event.nodeKind === "node") {
+              const qp = `${prefix}${event.name}`;
+              const r = restorers.get(qp);
+              if (r != null) {
+                r();
+                restorers.delete(qp);
+              }
+            } else {
+              const mountQp = `${prefix}${event.name}`;
+              const mountPrefix = `${mountQp}::`;
+              for (const [p, r] of restorers) {
+                if (p === mountQp || p.startsWith(mountPrefix)) {
+                  r();
+                  restorers.delete(p);
+                }
+              }
+            }
+          }
+        });
+        this.addDisposer(offTopology);
+      } else {
+        const offCleanup = target.topology.subscribe((msgs) => {
+          for (const m of msgs) {
+            if (m[0] !== DATA) continue;
+            const event = m[1];
+            if (event.kind !== "removed" || event.nodeKind !== "node") continue;
+            const r = restorers.get(event.name);
+            if (r != null) {
+              r();
+              restorers.delete(event.name);
+            }
+          }
+        });
+        this.addDisposer(offCleanup);
+      }
+      this.addDisposer(() => {
+        for (const r of restorers.values()) r();
+        restorers.clear();
+      });
+    } else {
+      const handle = target.observe({ timeline: true, structured: true });
+      const off = handle.onEvent((event) => {
+        if (event.type !== "data" && event.type !== "error") return;
+        const path = event.path ?? "";
+        if (!path) return;
+        if (opts.paths != null && !opts.paths.includes(path)) return;
+        const node2 = safeNode(target, path);
+        const lastMutation = node2?.lastMutation;
+        if (lastMutation == null) return;
+        const action2 = "write";
+        if (this._currentGuard(lastMutation.actor, action2)) return;
+        this._publishViolation(lastMutation.actor, action2, path, "observed");
+      });
+      this.addDisposer(() => {
+        off();
+        handle.dispose();
+      });
+    }
+  }
+  _publishViolation(actor, action2, path, result) {
+    this.violations.publish({
+      timestamp_ns: monotonicNs(),
+      wall_clock_ns: wallClockNs(),
+      path,
+      actor,
+      action: action2,
+      mode: this._mode,
+      result
+    });
+  }
+  /** Snapshot of recorded violations. */
+  all() {
+    return this.violations.retained();
+  }
+  get mode() {
+    return this._mode;
+  }
+  get target() {
+    return this._target;
+  }
+};
+function policyEnforcer(target, policies, opts = {}) {
+  return new PolicyEnforcerGraph(target, policies, opts);
+}
+function reactiveExplainPath(target, from, to, opts) {
+  let v = 0;
+  const version2 = state(v, { name: "explain_version" });
+  const handle = target.observe({ timeline: true, structured: true });
+  const off = handle.onEvent((event) => {
+    const t = event.type;
+    if (t !== "data" && t !== "error" && t !== "complete" && t !== "teardown") return;
+    v += 1;
+    version2.emit(v);
+  });
+  const explainOpts = {
+    ...opts?.maxDepth != null ? { maxDepth: opts.maxDepth } : {},
+    ...opts?.findCycle === true ? { findCycle: true } : {}
+  };
+  const node2 = derived([version2], () => target.explain(from, to, explainOpts), {
+    name: opts?.name ?? "explain",
+    describeKind: "derived",
+    equals: (a, b) => a.found === b.found && a.reason === b.reason && a.steps.length === b.steps.length && causalStepsEqual(a.steps, b.steps),
+    meta: auditMeta("explain_path", { from, to })
+  });
+  const stopKeepalive = keepalive(node2);
+  return {
+    node: node2,
+    dispose() {
+      off();
+      handle.dispose();
+      stopKeepalive();
+    }
+  };
+}
+function causalStepsEqual(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x.path !== y.path) return false;
+    if (x.type !== y.type) return false;
+    if (x.status !== y.status) return false;
+    if (x.hop !== y.hop) return false;
+    if (x.dep_index !== y.dep_index) return false;
+    if (x.reason !== y.reason) return false;
+    if (x.value !== y.value) return false;
+    if (x.lastMutation !== y.lastMutation) return false;
+    const xv = x.v;
+    const yv = y.v;
+    if (xv !== yv) {
+      if (xv == null || yv == null) return false;
+      if (xv.id !== yv.id || xv.version !== yv.version) return false;
+    }
+  }
+  return true;
+}
+function complianceSnapshot(target, opts = {}) {
+  const result = {
+    format_version: 1,
+    timestamp_ns: monotonicNs(),
+    wall_clock_ns: wallClockNs(),
+    graph: target.snapshot()
+  };
+  if (opts.actor != null) result.actor = opts.actor;
+  if (opts.audit != null) {
+    const entries = [...opts.audit.all()];
+    result.audit = { count: entries.length, entries };
+  }
+  if (opts.policies != null) {
+    const rules = opts.policies.policies.cache ?? [];
+    result.policies = {
+      mode: opts.policies.mode,
+      rules,
+      violations: [...opts.policies.all()]
+    };
+  }
+  const fingerprint = computeFingerprint(result);
+  return { ...result, fingerprint };
+}
+function isNode3(x) {
+  return typeof x === "object" && x !== null && "subscribe" in x;
+}
+function safeNode(target, path) {
+  try {
+    return target.node(path);
+  } catch {
+    return void 0;
+  }
+}
+function safeAnnotation(target, path) {
+  try {
+    return target.annotation(path);
+  } catch {
+    return void 0;
+  }
+}
+function collectPaths(target) {
+  const described = target.describe({ detail: "minimal" });
+  return Object.keys(described.nodes);
+}
+function computeFingerprint(value) {
+  return defaultHash(JSON.stringify(canonicalize(value)));
+}
+function canonicalize(value) {
+  const stack = /* @__PURE__ */ new Set();
+  const walk = (v) => {
+    if (v === void 0) return { __undefined: true };
+    if (v === null) return null;
+    const t = typeof v;
+    if (t === "bigint") return { __bigint: v.toString() };
+    if (t !== "object") return v;
+    const obj = v;
+    if (stack.has(obj)) return { __circular: true };
+    stack.add(obj);
+    try {
+      if (Array.isArray(obj)) {
+        return obj.map(walk);
+      }
+      if (obj instanceof Date) {
+        return { __date: obj.toISOString() };
+      }
+      if (obj instanceof RegExp) {
+        return { __regexp: { source: obj.source, flags: obj.flags } };
+      }
+      if (obj instanceof Map) {
+        const entries = [...obj.entries()].map(([k, mv]) => [
+          walk(k),
+          walk(mv)
+        ]);
+        return { __map: entries };
+      }
+      if (obj instanceof Set) {
+        const items = [...obj].map(walk);
+        return { __set: items };
+      }
+      if (ArrayBuffer.isView(obj)) {
+        const ta = obj;
+        const arr = new Array(ta.length);
+        for (let i = 0; i < ta.length; i++) arr[i] = ta[i] ?? 0;
+        return { __typed_array: { ctor: obj.constructor.name, data: arr } };
+      }
+      const out = {};
+      for (const k of Object.keys(obj).sort()) {
+        out[k] = walk(obj[k]);
+      }
+      return out;
+    } finally {
+      stack.delete(obj);
+    }
+  };
+  return walk(value);
+}
+
 // src/patterns/demo-shell.ts
 var demo_shell_exports = {};
 __export(demo_shell_exports, {
@@ -20998,6 +21895,65 @@ ${validation.errors.join("\n")}`);
   return parsed;
 }
 
+// src/patterns/guarded-execution.ts
+var guarded_execution_exports = {};
+__export(guarded_execution_exports, {
+  GuardedExecutionGraph: () => GuardedExecutionGraph,
+  guardedExecution: () => guardedExecution
+});
+var GuardedExecutionGraph = class extends Graph {
+  enforcer;
+  violations;
+  _target;
+  _defaultActor;
+  constructor(target, opts) {
+    super(opts.name ?? `${target.name}_guarded`, opts.graph);
+    this._target = target;
+    this._defaultActor = opts.actor;
+    const enforcerOpts = {
+      mode: opts.mode ?? "enforce",
+      name: "enforcer"
+    };
+    if (opts.violationsLimit != null) enforcerOpts.violationsLimit = opts.violationsLimit;
+    this.enforcer = policyEnforcer(target, opts.policies, enforcerOpts);
+    this.violations = this.enforcer.violations;
+    this.mount("enforcer", this.enforcer);
+  }
+  /**
+   * Describe the **target** graph scoped to the configured actor. Returns
+   * only nodes the actor is permitted to see (via the target's node guards
+   * filtering `describe()` via `actor`).
+   *
+   * Pass `{actor}` in opts to override the configured actor for this call.
+   * Pass any standard {@link GraphDescribeOptions} fields (`detail`,
+   * `fields`, `filter`) — they apply to the target's describe.
+   *
+   * **Mode interaction:**
+   * - In `mode: "enforce"` (default), the enforcer stacks a policy-derived
+   *   guard on every target node. `scopedDescribe({actor})` then filters by
+   *   the AND of per-node guards AND the stacked policy guard.
+   * - In `mode: "audit"`, NO guards are stacked — `scopedDescribe` filters
+   *   purely by the target's pre-existing per-node guards. If a target has
+   *   no node-level guards, the policy rules you pass have no effect on
+   *   visibility (they only populate the `violations` topic on writes).
+   */
+  scopedDescribe(opts) {
+    const actor = opts?.actor ?? this._defaultActor;
+    const describeOpts = {
+      ...opts,
+      ...actor != null ? { actor } : {}
+    };
+    return this._target.describe(describeOpts);
+  }
+  /** The wrapped graph (escape hatch for tooling). */
+  get target() {
+    return this._target;
+  }
+};
+function guardedExecution(target, opts) {
+  return new GuardedExecutionGraph(target, opts);
+}
+
 // src/patterns/harness/index.ts
 var harness_exports = {};
 __export(harness_exports, {
@@ -21679,6 +22635,257 @@ function truncate(s, max) {
   return s.length > max ? `${s.slice(0, max - 1)}\u2026` : s;
 }
 
+// src/patterns/lens.ts
+var lens_exports = {};
+__export(lens_exports, {
+  LensGraph: () => LensGraph,
+  graphLens: () => graphLens,
+  watchTopologyTree: () => watchTopologyTree
+});
+function lensMeta(kind) {
+  return domainMeta("lens", kind);
+}
+function computeTopologyStats(described) {
+  const paths = Object.keys(described.nodes);
+  const depsByPath = /* @__PURE__ */ new Map();
+  const dependents = /* @__PURE__ */ new Map();
+  for (const path of paths) {
+    const deps = described.nodes[path]?.deps ?? [];
+    depsByPath.set(path, deps);
+    for (const dep of deps) {
+      if (!dependents.has(dep)) dependents.set(dep, /* @__PURE__ */ new Set());
+      dependents.get(dep).add(path);
+    }
+  }
+  const sources = [];
+  const sinks = [];
+  for (const path of paths) {
+    if ((depsByPath.get(path) ?? []).length === 0) sources.push(path);
+    if (!dependents.has(path)) sinks.push(path);
+  }
+  sources.sort();
+  sinks.sort();
+  const edgeCount = described.edges.length;
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const p of paths) color.set(p, WHITE);
+  let hasCycles = false;
+  const longestFrom = /* @__PURE__ */ new Map();
+  const dfs = (path) => {
+    const c = color.get(path) ?? WHITE;
+    if (c === GRAY) {
+      hasCycles = true;
+      return 0;
+    }
+    if (c === BLACK) return longestFrom.get(path) ?? 0;
+    color.set(path, GRAY);
+    let best = 0;
+    const kids = dependents.get(path);
+    if (kids != null) {
+      for (const k of kids) {
+        const childLongest = dfs(k);
+        if (childLongest + 1 > best) best = childLongest + 1;
+      }
+    }
+    color.set(path, BLACK);
+    longestFrom.set(path, best);
+    return best;
+  };
+  let depth = 0;
+  for (const src of sources) {
+    const d = dfs(src);
+    if (d > depth) depth = d;
+  }
+  for (const p of paths) {
+    if (color.get(p) === WHITE) dfs(p);
+  }
+  return {
+    nodeCount: paths.length,
+    edgeCount,
+    subgraphCount: described.subgraphs.length,
+    sources,
+    sinks,
+    depth,
+    hasCycles
+  };
+}
+function computeHealthReport(described) {
+  const problems = [];
+  for (const [path, desc] of Object.entries(described.nodes)) {
+    if (desc.status !== "errored") continue;
+    const entry = { path, status: "errored" };
+    const upstream = reachable(described, path, "upstream", {});
+    for (const p of upstream) {
+      if (p === path) continue;
+      if (described.nodes[p]?.status === "errored") {
+        entry.upstreamCause = p;
+        break;
+      }
+    }
+    problems.push(entry);
+  }
+  problems.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return { ok: problems.length === 0, problems };
+}
+function topologyStatsEqual(a, b) {
+  return a.nodeCount === b.nodeCount && a.edgeCount === b.edgeCount && a.subgraphCount === b.subgraphCount && a.depth === b.depth && a.hasCycles === b.hasCycles && stringArrayEqual(a.sources, b.sources) && stringArrayEqual(a.sinks, b.sinks);
+}
+function healthReportEqual(a, b) {
+  if (a.ok !== b.ok) return false;
+  if (a.problems.length !== b.problems.length) return false;
+  for (let i = 0; i < a.problems.length; i++) {
+    const x = a.problems[i];
+    const y = b.problems[i];
+    if (x.path !== y.path) return false;
+    if (x.status !== y.status) return false;
+    if (x.upstreamCause !== y.upstreamCause) return false;
+  }
+  return true;
+}
+function stringArrayEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+var LensGraph = class extends Graph {
+  /**
+   * Aggregate structural stats — `nodeCount`, `edgeCount`, `sources`,
+   * `sinks`, `depth`, `hasCycles`, `subgraphCount`. Recomputes on every
+   * structural change via {@link watchTopologyTree} (transitive).
+   *
+   * Named `stats` (not `topology`) because `Graph.topology` already names
+   * the raw `TopologyEvent` stream on every graph including `LensGraph`;
+   * giving the lens its own `topology` accessor with an incompatible
+   * `Node<TopologyStats>` type would break Liskov substitutability.
+   */
+  stats;
+  health;
+  /**
+   * Per-path flow tracker — a live {@link ReactiveMapBundle} keyed by
+   * qualified path. Use `.get(path)` / `.has(path)` / `.size` for O(1)
+   * sync queries; subscribe to `.entries` for a reactive snapshot of the
+   * whole map. Lazy — the snapshot is materialized only while `.entries`
+   * has subscribers.
+   *
+   * Shape intentionally differs from `stats` / `health` (which are plain
+   * `Node<Report>`) because `flow` is a keyed collection, not a single
+   * aggregate value. The map shape exposes cheaper queries than any
+   * snapshot-based design.
+   */
+  flow;
+  _target;
+  constructor(target, opts = {}) {
+    super(opts.name ?? `${target.name}_lens`, opts.graph);
+    this._target = target;
+    let statsVersion = 0;
+    let healthVersion = 0;
+    const statsTick = state(0, { name: "stats_tick" });
+    const healthTick = state(0, { name: "health_tick" });
+    this.add("stats_tick", statsTick);
+    this.add("health_tick", healthTick);
+    const mapOpts = { name: "flow" };
+    if (opts.maxFlowPaths != null) mapOpts.maxSize = opts.maxFlowPaths;
+    this.flow = reactiveMap(mapOpts);
+    this.add("flow", this.flow.entries);
+    const pathFilter = opts.pathFilter;
+    const offTopology = watchTopologyTree(target, (event, _emitter, prefix) => {
+      statsVersion += 1;
+      statsTick.emit(statsVersion);
+      healthVersion += 1;
+      healthTick.emit(healthVersion);
+      if (event.kind === "removed") {
+        if (event.nodeKind === "node") {
+          const qp = `${prefix}${event.name}`;
+          this.flow.delete(qp);
+        } else {
+          const mountPrefix = `${prefix}${event.name}::`;
+          const keysToDelete = [];
+          for (const relativePath of event.audit.nodes) {
+            const qualified = relativePath === "" ? `${prefix}${event.name}` : `${mountPrefix}${relativePath}`;
+            keysToDelete.push(qualified);
+          }
+          if (keysToDelete.length > 0) this.flow.deleteMany(keysToDelete);
+        }
+      }
+    });
+    this.addDisposer(offTopology);
+    const observeHandle = target.observe({ timeline: true, structured: true });
+    const offObserve = observeHandle.onEvent((event) => {
+      const t = event.type;
+      if (t === "error" || t === "complete" || t === "data" || t === "teardown") {
+        healthVersion += 1;
+        healthTick.emit(healthVersion);
+      }
+      if (t === "data") {
+        const path = event.path ?? "";
+        if (!path) return;
+        if (pathFilter != null && !pathFilter(path)) return;
+        const existing = this.flow.get(path);
+        const count = existing != null ? existing.count + 1 : 1;
+        this.flow.set(path, { path, count, lastUpdate_ns: monotonicNs() });
+      }
+    });
+    this.addDisposer(() => {
+      offObserve();
+      observeHandle.dispose();
+    });
+    this.stats = derived(
+      [statsTick],
+      () => computeTopologyStats(target.describe({ detail: "minimal" })),
+      {
+        name: "stats",
+        describeKind: "derived",
+        equals: topologyStatsEqual,
+        meta: lensMeta("stats")
+      }
+    );
+    this.add("stats", this.stats);
+    this.addDisposer(keepalive(this.stats));
+    this.health = derived(
+      [healthTick],
+      () => computeHealthReport(target.describe({ detail: "standard" })),
+      {
+        name: "health",
+        describeKind: "derived",
+        equals: healthReportEqual,
+        meta: lensMeta("health")
+      }
+    );
+    this.add("health", this.health);
+    this.addDisposer(keepalive(this.health));
+  }
+  /**
+   * Live causal chain from `from` to `to`. Recomputes whenever the target
+   * mutates. Disposed automatically when the lens is destroyed.
+   *
+   * **Lifetime note:** every call to `why()` registers a lens-owned disposer
+   * that runs on `lens.destroy()`. The returned `dispose` function releases
+   * the internal subscription but does NOT remove the lens-owned disposer —
+   * so heavy calling (e.g. per render frame) accumulates no-op disposers
+   * until lens teardown. Cache the returned handle for long-lived queries.
+   *
+   * @param from - Qualified path of the upstream endpoint.
+   * @param to - Qualified path of the downstream endpoint.
+   * @param opts - See {@link reactiveExplainPath}.
+   */
+  why(from, to, opts) {
+    const handle = reactiveExplainPath(this._target, from, to, opts);
+    this.addDisposer(handle.dispose);
+    return handle;
+  }
+  /** Reference to the lensed graph. */
+  get target() {
+    return this._target;
+  }
+};
+function graphLens(target, opts) {
+  return new LensGraph(target, opts);
+}
+
 // src/patterns/reactive-layout/index.ts
 var reactive_layout_exports = {};
 __export(reactive_layout_exports, {
@@ -21899,7 +23106,7 @@ var CanvasMeasureAdapter = class {
       this.currentFont = font;
     }
     let width = ctx.measureText(text).width;
-    if (this.emojiCorrection !== 1 && /\p{Emoji_Presentation}/u.test(text)) {
+    if (this.emojiCorrection !== 1 && new RegExp("\\p{Emoji_Presentation}", "u").test(text)) {
       width *= this.emojiCorrection;
     }
     return { width };
@@ -22349,6 +23556,385 @@ function reactiveFlowLayout(opts) {
   };
 }
 
+// src/patterns/resilient-pipeline.ts
+var resilient_pipeline_exports = {};
+__export(resilient_pipeline_exports, {
+  NS_PER_MS: () => NS_PER_MS,
+  NS_PER_SEC: () => NS_PER_SEC,
+  resilientPipeline: () => resilientPipeline
+});
+function resilientPipeline(source, opts = {}) {
+  let current = source;
+  if (opts.rateLimit != null) {
+    current = rateLimiter(current, opts.rateLimit);
+  }
+  if (opts.budget != null && opts.budget.length > 0) {
+    current = budgetGate(current, opts.budget);
+  }
+  let breakerState;
+  if (opts.breaker != null) {
+    const breaker = circuitBreaker(opts.breaker);
+    const onOpen = opts.breakerOnOpen ?? "skip";
+    const wrapped = withBreaker(breaker, { onOpen })(current);
+    current = wrapped.node;
+    breakerState = wrapped.breakerState;
+  }
+  if (opts.timeoutMs != null) {
+    if (opts.timeoutMs <= 0) throw new RangeError("timeoutMs must be > 0");
+    if (opts.timeoutMs > 9e6) {
+      throw new RangeError(
+        "timeoutMs must be <= 9_000_000 (\u22482.5h) to stay within safe ns arithmetic"
+      );
+    }
+    current = timeout(current, opts.timeoutMs * NS_PER_MS);
+  }
+  if (opts.retry != null) {
+    current = retry(current, opts.retry);
+  }
+  if (opts.fallback !== void 0) {
+    current = fallback(current, opts.fallback);
+  }
+  const withStatusBundle = withStatus(current, { initialStatus: opts.initialStatus ?? "pending" });
+  return {
+    node: withStatusBundle.node,
+    status: withStatusBundle.status,
+    error: withStatusBundle.error,
+    breakerState
+  };
+}
+
+// src/patterns/surface/index.ts
+var surface_exports = {};
+__export(surface_exports, {
+  SNAPSHOT_WIRE_VERSION: () => SNAPSHOT_WIRE_VERSION,
+  SurfaceError: () => SurfaceError,
+  asSurfaceError: () => asSurfaceError,
+  createGraph: () => createGraph,
+  deleteSnapshot: () => deleteSnapshot,
+  diffSnapshots: () => diffSnapshots,
+  listSnapshots: () => listSnapshots,
+  restoreSnapshot: () => restoreSnapshot,
+  runReduction: () => runReduction,
+  saveSnapshot: () => saveSnapshot
+});
+
+// src/patterns/surface/errors.ts
+var SurfaceError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "SurfaceError";
+    this.code = code;
+    if (details !== void 0) this.details = details;
+  }
+  /**
+   * JSON-safe payload for wire serialization. Defensively validates
+   * `details` — if it can't be round-tripped through `JSON.stringify`
+   * (cyclic refs, `BigInt`, `Error` instance not pre-toJSON'd), the
+   * payload falls back to `{code, message}` only rather than crashing
+   * the MCP/CLI wrapper when it serializes this error onto the wire.
+   */
+  toJSON() {
+    const out = { code: this.code, message: this.message };
+    if (this.details !== void 0) {
+      const safe = safeDetails(this.details);
+      if (safe !== void 0) out.details = safe;
+    }
+    return out;
+  }
+};
+function safeDetails(details) {
+  try {
+    return JSON.parse(JSON.stringify(details));
+  } catch {
+    return void 0;
+  }
+}
+function asSurfaceError(err, fallbackCode = "internal-error") {
+  if (err instanceof SurfaceError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new SurfaceError(fallbackCode, message);
+}
+
+// src/patterns/surface/create.ts
+function createGraph(spec, opts) {
+  const structural = validateSpec(spec);
+  if (!structural.valid) {
+    throw new SurfaceError(
+      "invalid-spec",
+      `GraphSpec validation failed:
+${structural.errors.join("\n")}`,
+      { errors: structural.errors }
+    );
+  }
+  const catalog = opts?.catalog ?? {};
+  const catalogValidation = validateSpecAgainstCatalog(spec, catalog);
+  if (!catalogValidation.valid) {
+    throw new SurfaceError(
+      "catalog-error",
+      `Catalog validation failed:
+${catalogValidation.errors.join("\n")}`,
+      { errors: catalogValidation.errors }
+    );
+  }
+  try {
+    return compileSpec(spec, opts);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SurfaceError("catalog-error", message);
+  }
+}
+
+// src/patterns/surface/reduce.ts
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+async function runReduction(spec, input, opts) {
+  const inputPath = opts?.inputPath ?? "input";
+  const outputPath = opts?.outputPath ?? "output";
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const graph = createGraph(spec, { catalog: opts?.catalog });
+  let outputNode;
+  try {
+    outputNode = graph.resolve(outputPath);
+  } catch {
+    graph.destroy();
+    throw new SurfaceError(
+      "node-not-found",
+      `reduce: output path "${outputPath}" is not registered`,
+      { path: outputPath }
+    );
+  }
+  try {
+    graph.resolve(inputPath);
+  } catch {
+    graph.destroy();
+    throw new SurfaceError(
+      "node-not-found",
+      `reduce: input path "${inputPath}" is not registered`,
+      { path: inputPath }
+    );
+  }
+  try {
+    return await new Promise((resolve, reject) => {
+      let primed = false;
+      let settled = false;
+      let timer;
+      let unsub;
+      let shouldUnsub = false;
+      const finish = (action2) => {
+        if (settled) return;
+        settled = true;
+        if (timer !== void 0) clearTimeout(timer);
+        if (unsub !== void 0) {
+          unsub();
+          unsub = void 0;
+        } else {
+          shouldUnsub = true;
+        }
+        action2();
+      };
+      unsub = outputNode.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (settled) return;
+          if (!primed) continue;
+          if (m[0] === DATA) {
+            finish(() => resolve(m[1]));
+            return;
+          }
+          if (m[0] === RESOLVED) {
+            const cached2 = outputNode.cache;
+            finish(() => resolve(cached2));
+            return;
+          }
+          if (m[0] === ERROR) {
+            const payload = m[1];
+            const message = payload instanceof Error ? payload.message : String(payload);
+            const cause = payload instanceof Error ? payload : void 0;
+            finish(
+              () => reject(
+                new SurfaceError(
+                  "internal-error",
+                  `reduce: output emitted ERROR: ${message}`,
+                  cause != null ? { cause } : void 0
+                )
+              )
+            );
+            return;
+          }
+          if (m[0] === COMPLETE) {
+            finish(
+              () => reject(
+                new SurfaceError(
+                  "internal-error",
+                  `reduce: output COMPLETEd without a post-push DATA`
+                )
+              )
+            );
+            return;
+          }
+        }
+      });
+      if (shouldUnsub) {
+        unsub?.();
+        unsub = void 0;
+      }
+      primed = true;
+      try {
+        graph.set(inputPath, input);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const cause = err instanceof Error ? err : void 0;
+        finish(
+          () => reject(
+            new SurfaceError(
+              "internal-error",
+              `reduce: failed to set input on "${inputPath}": ${message}`,
+              cause != null ? { path: inputPath, cause } : { path: inputPath }
+            )
+          )
+        );
+        return;
+      }
+      if (!settled && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        timer = setTimeout(() => {
+          finish(
+            () => reject(
+              new SurfaceError(
+                "reduce-timeout",
+                `reduce: no output emitted within ${timeoutMs}ms`,
+                { timeoutMs, outputPath }
+              )
+            )
+          );
+        }, timeoutMs);
+        timer.unref?.();
+      }
+    });
+  } finally {
+    graph.destroy();
+  }
+}
+
+// src/patterns/surface/snapshot.ts
+var SNAPSHOT_WIRE_VERSION = SNAPSHOT_VERSION;
+function unwrapCheckpoint(raw, snapshotId) {
+  if (raw == null || typeof raw !== "object") {
+    throw new SurfaceError("snapshot-not-found", `snapshot "${snapshotId}" not found in tier`, {
+      snapshotId
+    });
+  }
+  const record = raw;
+  if ("mode" in record) {
+    if (record.mode === "full" && "snapshot" in record) {
+      return record.snapshot;
+    }
+    if (record.mode === "diff") {
+      throw new SurfaceError(
+        "restore-failed",
+        `snapshot "${snapshotId}" is a diff record; restore the baseline and replay WAL instead`,
+        { snapshotId, mode: "diff" }
+      );
+    }
+    throw new SurfaceError(
+      "restore-failed",
+      `snapshot "${snapshotId}" has unknown mode "${String(record.mode)}"`,
+      { snapshotId, mode: String(record.mode) }
+    );
+  }
+  if ("nodes" in record && "edges" in record && "subgraphs" in record && "name" in record) {
+    return record;
+  }
+  throw new SurfaceError(
+    "restore-failed",
+    `snapshot "${snapshotId}" payload is not a GraphCheckpointRecord or GraphPersistSnapshot`,
+    { snapshotId }
+  );
+}
+async function saveSnapshot(graph, snapshotId, tier) {
+  let snapshot;
+  try {
+    snapshot = graph.snapshot();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SurfaceError(
+      "snapshot-failed",
+      `snapshot "${snapshotId}" serialization failed: ${message}`,
+      { snapshotId }
+    );
+  }
+  const record = {
+    mode: "full",
+    seq: 0,
+    timestamp_ns: wallClockNs(),
+    format_version: SNAPSHOT_WIRE_VERSION,
+    snapshot
+  };
+  try {
+    await tier.save(snapshotId, record);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SurfaceError("snapshot-failed", `snapshot "${snapshotId}" save failed: ${message}`, {
+      snapshotId
+    });
+  }
+  return { snapshotId, timestamp_ns: record.timestamp_ns };
+}
+async function restoreSnapshot(snapshotId, tier, opts) {
+  const raw = await tier.load(snapshotId);
+  const snapshot = unwrapCheckpoint(raw, snapshotId);
+  try {
+    return Graph.fromSnapshot(
+      snapshot,
+      opts?.factories ? { factories: opts.factories } : void 0
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SurfaceError(
+      "restore-failed",
+      `snapshot "${snapshotId}" restore failed: ${message}`,
+      {
+        snapshotId
+      }
+    );
+  }
+}
+async function diffSnapshots(snapshotIdA, snapshotIdB, tier) {
+  const [rawA, rawB] = await Promise.all([tier.load(snapshotIdA), tier.load(snapshotIdB)]);
+  const snapshotA = unwrapCheckpoint(rawA, snapshotIdA);
+  const snapshotB = unwrapCheckpoint(rawB, snapshotIdB);
+  return Graph.diff(snapshotA, snapshotB);
+}
+async function listSnapshots(tier) {
+  if (typeof tier.list !== "function") {
+    throw new SurfaceError(
+      "tier-no-list",
+      "StorageTier does not implement list(); wrap the tier with an enumerator or use a different backend"
+    );
+  }
+  return tier.list();
+}
+async function deleteSnapshot(snapshotId, tier) {
+  if (typeof tier.clear !== "function") {
+    throw new SurfaceError(
+      "snapshot-failed",
+      `StorageTier is append-only (no clear()); cannot delete "${snapshotId}"`,
+      { snapshotId }
+    );
+  }
+  try {
+    await tier.clear(snapshotId);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SurfaceError(
+      "snapshot-failed",
+      `snapshot "${snapshotId}" delete failed: ${message}`,
+      {
+        snapshotId
+      }
+    );
+  }
+}
+
 // src/index.ts
 var version = "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
@@ -22389,15 +23975,20 @@ var version = "0.0.0";
   ResettableTimer,
   SIZEOF_OVERHEAD,
   SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION,
+  SNAPSHOT_WIRE_VERSION,
   START,
   START_MSG,
+  SurfaceError,
   TEARDOWN,
   TEARDOWN_MSG,
   TEARDOWN_ONLY_BATCH,
   TimeoutError,
   accessHintForGuard,
+  accountability,
   advanceVersion,
   ai,
+  asSurfaceError,
   audit,
   autoTrackNode,
   batch,
@@ -22421,6 +24012,7 @@ var version = "0.0.0";
   cqrs,
   createDagCborCodec,
   createDagCborZstdCodec,
+  createGraph,
   createTransport,
   createVersioning,
   createWatermarkController,
@@ -22432,11 +24024,13 @@ var version = "0.0.0";
   defaultConfig,
   defaultHash,
   delay,
+  deleteSnapshot,
   demoShell,
   derived,
   deserializeError,
   dictStorage,
   diffForWAL,
+  diffSnapshots,
   distill,
   distinctUntilChanged,
   domainTemplates,
@@ -22448,6 +24042,7 @@ var version = "0.0.0";
   encodeEnvelope,
   escapeRegexChar,
   exhaustMap,
+  explainPath,
   exponential,
   externalBundle,
   externalProducer,
@@ -22503,6 +24098,7 @@ var version = "0.0.0";
   graph,
   graphProfile,
   graphspec,
+  guarded,
   harness,
   indexedDbStorage,
   interval,
@@ -22512,7 +24108,9 @@ var version = "0.0.0";
   keepalive,
   last,
   layout,
+  lens,
   linear,
+  listSnapshots,
   lru,
   map,
   matchesAnyPattern,
@@ -22562,11 +24160,15 @@ var version = "0.0.0";
   replay,
   replayWAL,
   rescue,
+  resilientPipeline,
   resolveBackoffPreset,
   resolveDescribeFields,
+  restoreSnapshot,
   retry,
   retrySource,
+  runReduction,
   sample,
+  saveSnapshot,
   scan,
   serializeError,
   share,
@@ -22578,6 +24180,7 @@ var version = "0.0.0";
   solid,
   sqliteStorage,
   state,
+  surface,
   svelte,
   switchMap,
   take,
@@ -22615,6 +24218,7 @@ var version = "0.0.0";
   version,
   vue,
   wallClockNs,
+  watchTopologyTree,
   window,
   windowCount,
   windowTime,