@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/presets/inspect/index.cjs

@@ -0,0 +1,1087 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/presets/inspect/index.ts
+var inspect_exports = {};
+__export(inspect_exports, {
+  GuardedExecutionGraph: () => GuardedExecutionGraph,
+  InspectGraph: () => InspectGraph,
+  guardedExecution: () => guardedExecution,
+  inspect: () => inspect
+});
+module.exports = __toCommonJS(inspect_exports);
+
+// src/presets/inspect/composite.ts
+var import_core5 = require("@graphrefly/pure-ts/core");
+var import_graph6 = require("@graphrefly/pure-ts/graph");
+
+// src/utils/inspect/audit.ts
+var import_core3 = require("@graphrefly/pure-ts/core");
+var import_extra3 = require("@graphrefly/pure-ts/extra");
+var import_graph3 = require("@graphrefly/pure-ts/graph");
+
+// src/base/meta/domain-meta.ts
+function domainMeta(domain, kind, extra) {
+  return {
+    [domain]: true,
+    [`${domain}_type`]: kind,
+    ...extra ?? {}
+  };
+}
+
+// src/utils/messaging/index.ts
+var import_core2 = require("@graphrefly/pure-ts/core");
+var import_extra2 = require("@graphrefly/pure-ts/extra");
+var import_graph2 = require("@graphrefly/pure-ts/graph");
+
+// src/base/mutation/index.ts
+var import_core = require("@graphrefly/pure-ts/core");
+var import_extra = require("@graphrefly/pure-ts/extra");
+var import_graph = require("@graphrefly/pure-ts/graph");
+var DEFAULT_AUDIT_GUARD = (0, import_core.policy)((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const k of Object.keys(value)) {
+    deepFreeze(value[k]);
+  }
+  return Object.freeze(value);
+}
+function mutate(act, opts) {
+  const { up, down } = typeof act === "function" ? { up: act, down: void 0 } : act;
+  const freeze = opts.freeze ?? true;
+  if (opts.frame === "inline") {
+    return function wrapped(...args) {
+      const sealed = freeze ? args.map(deepFreeze) : args;
+      const t_ns = (0, import_core.wallClockNs)();
+      const seq = opts.seq ? bumpCursor(opts.seq) : void 0;
+      try {
+        const result = up(...sealed);
+        if (opts.log && opts.onSuccessRecord) {
+          appendAudit(
+            opts.log,
+            opts.onSuccessRecord,
+            sealed,
+            result,
+            { t_ns, seq },
+            opts.handlerVersion
+          );
+        }
+        return result;
+      } catch (err) {
+        if (opts.log && opts.onFailureRecord) {
+          const errorType = err instanceof Error ? err.name : typeof err;
+          appendAudit(
+            opts.log,
+            opts.onFailureRecord,
+            sealed,
+            err,
+            { t_ns, seq, errorType },
+            opts.handlerVersion
+          );
+        }
+        throw err;
+      }
+    };
+  }
+  return function wrapped(...args) {
+    const sealed = freeze ? args.map(deepFreeze) : args;
+    const t_ns = (0, import_core.wallClockNs)();
+    let result;
+    let captured;
+    let captureSet = false;
+    let seq;
+    try {
+      (0, import_core.batch)(() => {
+        if (opts.seq) seq = bumpCursor(opts.seq);
+        try {
+          result = up(...sealed);
+          if (opts.log && opts.onSuccessRecord) {
+            appendAudit(
+              opts.log,
+              opts.onSuccessRecord,
+              sealed,
+              result,
+              { t_ns, seq },
+              opts.handlerVersion
+            );
+          }
+        } catch (err) {
+          captured = err;
+          captureSet = true;
+          throw err;
+        }
+      });
+    } catch (outerErr) {
+      if (captureSet && down) {
+        try {
+          down(...sealed);
+        } catch (downErr) {
+          console.error(
+            `mutate: down hook threw \u2014 original action error preserved (${captured instanceof Error ? captured.name : typeof captured}). Down error:`,
+            downErr
+          );
+        }
+      }
+      if (captureSet && opts.log && opts.onFailureRecord) {
+        const errorType = captured instanceof Error ? captured.name : typeof captured;
+        appendAudit(
+          opts.log,
+          opts.onFailureRecord,
+          sealed,
+          captured,
+          { t_ns, seq, errorType },
+          opts.handlerVersion
+        );
+      }
+      throw captureSet ? captured : outerErr;
+    }
+    return result;
+  };
+}
+var _bumpCursorWarned = /* @__PURE__ */ new WeakSet();
+function bumpCursor(seq) {
+  const raw = seq.cache;
+  const valid = typeof raw === "number" && Number.isFinite(raw);
+  if (!valid && raw !== void 0 && !_bumpCursorWarned.has(seq)) {
+    _bumpCursorWarned.add(seq);
+    console.warn(
+      `bumpCursor: cursor cache held a non-numeric value (${String(raw)}); resetting to 0. Causes include: a snapshot codec round-tripping the cursor as a string / null / NaN, OR a malformed initial seed (e.g. state<number>(NaN)). Audit consumers may see colliding seq values after this point.`
+    );
+  }
+  const cur = valid ? raw : 0;
+  const next = cur + 1;
+  seq.down([[import_core.DIRTY], [import_core.DATA, next]]);
+  return next;
+}
+function appendAudit(audit, builder, args, value, meta, handlerVersion) {
+  const record = builder(args, value, meta);
+  if (record === void 0) return;
+  const stamped = handlerVersion != null ? { ...record, handlerVersion } : record;
+  audit.append(stamped);
+}
+
+// src/utils/messaging/index.ts
+function messagingMeta(kind, extra) {
+  return domainMeta("messaging", kind, extra);
+}
+var DEFAULT_TOPIC_RETAINED_LIMIT = 1024;
+var TopicGraph = class extends import_graph2.Graph {
+  _log;
+  _publishImpl;
+  events;
+  /**
+   * Most recently published value. Stays in the protocol SENTINEL state
+   * (`cache === undefined`, no DATA emitted) until the first publish, then
+   * tracks the latest entry. Spec §5.12 reserves `undefined` as the
+   * "never sent DATA" sentinel — and `TopicGraph.publish(undefined)` is
+   * rejected — so `cache === undefined` unambiguously signals "empty topic"
+   * even when `T` itself includes `null` (i.e., `topic<number | null>`).
+   *
+   * **Within a reactive fn:** detect the empty-topic case via
+   * `ctx.prevData[i] === undefined` for the dep slot holding `topic.latest`,
+   * or check `latest.cache === undefined` outside reactive code. No
+   * separate `hasLatest` companion needed — the SENTINEL is the answer.
+   */
+  latest;
+  constructor(name, opts = {}) {
+    super(name, opts.graph);
+    this._log = (0, import_extra2.reactiveLog)([], {
+      name: "events",
+      maxSize: opts.retainedLimit ?? DEFAULT_TOPIC_RETAINED_LIMIT
+    });
+    this.events = this._log.entries;
+    this.add(this.events, { name: "events" });
+    this.latest = this.derived(
+      "latest",
+      ["events"],
+      (batchData, ctx) => {
+        const data = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+        );
+        const entries = data[0];
+        return entries.length === 0 ? [] : [entries[entries.length - 1]];
+      },
+      { meta: messagingMeta("topic_latest") }
+    );
+    this.addDisposer((0, import_extra2.keepalive)(this.latest));
+    this.addDisposer(() => {
+      this.events.down([[import_core2.COMPLETE]]);
+    });
+    this.addDisposer(() => this._log.disposeAllViews());
+    this._publishImpl = mutate(
+      (value) => {
+        this._log.append(value);
+      },
+      { frame: "inline", freeze: false }
+    );
+  }
+  publish(value) {
+    if (value === void 0) {
+      throw new TypeError(
+        `TopicGraph "${this.name}": publish(undefined) is not allowed (spec \xA75.12 SENTINEL).`
+      );
+    }
+    this._publishImpl(value);
+  }
+  /**
+   * Wire one or more append-log storage tiers (Audit 4). Each tier receives
+   * appended events per wave; rollback honors the wave-as-transaction model.
+   *
+   * Named `attachEventStorage` (not `attachStorage`) to avoid colliding with
+   * the inherited {@link Graph.attachSnapshotStorage} which takes the
+   * paired `AttachSnapshotTierPair[]` shape (Phase 14.6) — distinct
+   * concerns, distinct surfaces.
+   *
+   * @returns Disposer.
+   */
+  attachEventStorage(tiers) {
+    return this._log.attachStorage(tiers);
+  }
+  retained() {
+    return this.events.cache;
+  }
+  /** Internal log bundle — used by TopicBridgeGraph for `attach`. */
+  get _logBundle() {
+    return this._log;
+  }
+};
+
+// src/utils/inspect/audit.ts
+function auditMeta(kind, extra) {
+  return domainMeta("audit", kind, extra);
+}
+var DEFAULT_INCLUDE_TYPES = /* @__PURE__ */ new Set([
+  "data",
+  "error",
+  "complete",
+  "teardown"
+]);
+var AuditTrailGraph = class extends import_graph3.Graph {
+  entries;
+  count;
+  /**
+   * Effective set of event types this trail records (EH-18). Reflects
+   * either the caller-supplied `opts.includeTypes` or the default set
+   * (`["data", "error", "complete", "teardown"]`). Captured at construction
+   * — each instance owns its own clone, so a default-using trail can never
+   * leak mutations into the module-level default set.
+   *
+   * **Mutation contract.** Type-system read-only via `ReadonlySet`. Runtime
+   * mutation through an unsafe cast (`(audit.includeTypes as Set<...>)
+   * .add(...)`) is unsupported — it would desync the field from the
+   * recording closure, which captured the original `Set` reference at
+   * construction. The runtime does NOT enforce immutability beyond the
+   * type contract; consumers must respect it.
+   *
+   * Use this to validate that a `complianceSnapshot.fingerprint` was
+   * computed against the same recording surface — fingerprints are stable
+   * only when the recording set is identical across snapshots.
+   */
+  includeTypes;
+  _log;
+  _target;
+  constructor(target, opts) {
+    super(opts.name ?? `${target.name}_audit`, opts.graph);
+    this._target = target;
+    this._log = (0, import_extra3.reactiveLog)([], {
+      name: "entries",
+      ...opts.maxSize != null ? { maxSize: opts.maxSize } : {}
+    });
+    this.entries = this._log.entries;
+    this.add(this.entries, { name: "entries" });
+    this.count = this.derived(
+      "count",
+      ["entries"],
+      (batchData, ctx) => {
+        const data = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+        );
+        return [data[0].length];
+      },
+      { meta: auditMeta("count") }
+    );
+    this.addDisposer((0, import_extra3.keepalive)(this.count));
+    const includeTypes = opts.includeTypes != null ? new Set(opts.includeTypes) : new Set(DEFAULT_INCLUDE_TYPES);
+    this.includeTypes = includeTypes;
+    const filter = 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 ?? (0, import_core3.monotonicNs)(),
+        wall_clock_ns: (0, import_core3.wallClockNs)(),
+        path,
+        type
+      };
+      const node6 = path ? safeNode(target, path) : void 0;
+      const lastMutation = node6?.lastMutation;
+      if (lastMutation != null) entry.actor = lastMutation.actor;
+      if (type === "data") entry.value = event.data;
+      if (type === "error") entry.error = event.data;
+      const annotation = path ? safeAnnotation(target, path) : void 0;
+      if (annotation != null) entry.annotation = annotation;
+      if (filter != null && !filter(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 PolicyGateGraph = class extends import_graph3.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 = isNode(policies) ? policies : (0, import_core3.node)([], { name: "policies", initial: policies });
+    this.policies = policiesNode;
+    this.add(this.policies, { name: "policies" });
+    this.violations = new TopicGraph("violations", {
+      retainedLimit: opts.violationsLimit ?? 1e3
+    });
+    this.mount("violations", this.violations);
+    this.violationCount = this.derived(
+      "violationCount",
+      ["violations::events"],
+      (batchData, ctx) => {
+        const data = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+        );
+        return [data[0].length];
+      },
+      {
+        meta: auditMeta("policy_violation_count")
+      }
+    );
+    this.addDisposer((0, import_extra3.keepalive)(this.violationCount));
+    const initialRules = policiesNode.cache ?? [];
+    let latestRules = initialRules;
+    this._currentGuard = (0, import_core3.policyFromRules)(latestRules);
+    const offPolicies = policiesNode.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === import_core3.DATA) {
+          latestRules = m[1] ?? [];
+          this._currentGuard = (0, import_core3.policyFromRules)(latestRules);
+        }
+      }
+    });
+    this.addDisposer(offPolicies);
+    const pathsOpt = opts.paths;
+    const pathsNode = isNode(pathsOpt) ? pathsOpt : void 0;
+    const pathsExplicit = pathsOpt != null;
+    const initialPaths = pathsNode != null ? pathsNode.cache ?? [] : pathsExplicit ? [...pathsOpt] : void 0;
+    let latestPaths = initialPaths;
+    const paths = latestPaths ?? collectPaths(target);
+    if (this._mode !== "enforce" && pathsNode != null) {
+      const offAuditPaths = pathsNode.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (m[0] !== import_core3.DATA) continue;
+          latestPaths = m[1] ?? [];
+        }
+      });
+      this.addDisposer(offAuditPaths);
+    }
+    if (this._mode === "enforce") {
+      const restorers = /* @__PURE__ */ new Map();
+      const wrapAndPush = (path) => {
+        if (restorers.has(path)) return;
+        const node6 = safeNode(target, path);
+        if (!(node6 instanceof import_core3.NodeImpl)) return;
+        const pathGuard = (actor, action) => {
+          const ok = this._currentGuard(actor, action);
+          if (!ok) {
+            this._publishViolation(actor, action, path, "blocked");
+          }
+          return ok;
+        };
+        restorers.set(path, node6._pushGuard(pathGuard));
+      };
+      for (const path of paths) wrapAndPush(path);
+      if (pathsNode != null) {
+        const offReactivePaths = pathsNode.subscribe((msgs) => {
+          for (const m of msgs) {
+            if (m[0] !== import_core3.DATA) continue;
+            const next = m[1] ?? [];
+            const nextSet = new Set(next);
+            const prevSet = new Set(latestPaths ?? []);
+            (0, import_core3.batch)(() => {
+              for (const p of prevSet) {
+                if (nextSet.has(p)) continue;
+                const r = restorers.get(p);
+                if (r != null) {
+                  r();
+                  restorers.delete(p);
+                }
+              }
+              for (const p of nextSet) {
+                if (prevSet.has(p)) continue;
+                wrapAndPush(p);
+              }
+              latestPaths = next;
+            });
+          }
+        });
+        this.addDisposer(offReactivePaths);
+      }
+      if (!pathsExplicit) {
+        const offTopology = (0, import_graph3.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 import_graph3.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] !== import_core3.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 (latestPaths != null && !latestPaths.includes(path)) return;
+        const actor = event.actor ?? safeNode(target, path)?.lastMutation?.actor;
+        if (actor == null) return;
+        const action = "write";
+        if (this._currentGuard(actor, action)) return;
+        this._publishViolation(actor, action, path, "observed");
+      });
+      this.addDisposer(() => {
+        off();
+        handle.dispose();
+      });
+    }
+  }
+  _publishViolation(actor, action, path, result) {
+    this.violations.publish({
+      timestamp_ns: (0, import_core3.monotonicNs)(),
+      wall_clock_ns: (0, import_core3.wallClockNs)(),
+      path,
+      actor,
+      action,
+      mode: this._mode,
+      result
+    });
+  }
+  /** Snapshot of recorded violations. */
+  all() {
+    return this.violations.retained();
+  }
+  get mode() {
+    return this._mode;
+  }
+  get target() {
+    return this._target;
+  }
+};
+function policyGate(target, policies, opts = {}) {
+  const g = new PolicyGateGraph(target, policies, opts);
+  g.tagFactory("policyGate", (0, import_core3.placeholderArgs)(opts));
+  return g;
+}
+function complianceSnapshot(target, opts = {}) {
+  const result = {
+    format_version: 1,
+    timestamp_ns: (0, import_core3.monotonicNs)(),
+    wall_clock_ns: (0, import_core3.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 isNode(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 (0, import_core3.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/utils/inspect/lens.ts
+var import_core4 = require("@graphrefly/pure-ts/core");
+var import_extra4 = require("@graphrefly/pure-ts/extra");
+var import_graph4 = require("@graphrefly/pure-ts/graph");
+var import_graph5 = require("@graphrefly/pure-ts/graph");
+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 = (0, import_graph4.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 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 graphLens(target) {
+  const topologyHandle = target.describe({
+    reactive: true,
+    detail: "standard",
+    reactiveName: "graphLens.topology"
+  });
+  const topology = topologyHandle.node;
+  const health = (0, import_core4.node)(
+    [topology],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+      );
+      actions.emit(computeHealthReport(data[0]));
+    },
+    {
+      name: "graphLens.health",
+      describeKind: "derived",
+      equals: healthReportEqual,
+      meta: domainMeta("lens", "health")
+    }
+  );
+  const stopHealthKeep = (0, import_extra4.keepalive)(health);
+  const flowMap = /* @__PURE__ */ new Map();
+  let lastAppliedFlush_ns = -1;
+  const dataFlow = target.observe({ reactive: true, tiers: ["data"] });
+  const flow = (0, import_core4.node)(
+    [dataFlow, topology],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+      );
+      const changeset = data[0];
+      const described = data[1];
+      const c = changeset;
+      const desc = described;
+      if (c != null && c.flushedAt_ns > lastAppliedFlush_ns) {
+        lastAppliedFlush_ns = c.flushedAt_ns;
+        for (const event of c.events) {
+          if (event.type !== "data") continue;
+          const path = event.path;
+          if (path == null || path === "") continue;
+          const prior = flowMap.get(path);
+          flowMap.set(path, {
+            path,
+            count: (prior?.count ?? 0) + 1,
+            lastUpdate_ns: c.flushedAt_ns
+          });
+        }
+      }
+      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);
+        }
+      }
+      actions.emit(new Map(flowMap));
+    },
+    {
+      name: "graphLens.flow",
+      describeKind: "derived",
+      meta: domainMeta("lens", "flow")
+    }
+  );
+  const stopFlowKeep = (0, import_extra4.keepalive)(flow);
+  let disposed = false;
+  return {
+    topology,
+    health,
+    flow,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stopFlowKeep();
+      stopHealthKeep();
+      topologyHandle.dispose();
+    }
+  };
+}
+
+// src/presets/inspect/composite.ts
+var LensSubgraph = class extends import_graph6.Graph {
+  view;
+  constructor(target) {
+    super("lens");
+    this.view = graphLens(target);
+    this.add(this.view.topology, { name: "topology" });
+    this.add(this.view.health, { name: "health" });
+    this.add(this.view.flow, { name: "flow" });
+  }
+};
+var InspectGraph = class extends import_graph6.Graph {
+  target;
+  /**
+   * Underlying lens view — reach individual Nodes via
+   * `inspect.lens.topology` / `inspect.lens.health` / `inspect.lens.flow`.
+   *
+   * Direct `inspect.topology` / `inspect.health` / `inspect.flow`
+   * accessors are NOT shipped because `Graph.topology` is already an
+   * accessor on the base class with a different shape (`Node<TopologyEvent>`
+   * — the mount/unmount stream of THIS graph, not the wrapped target's
+   * describe snapshot). Going through `.lens.*` keeps the two concepts
+   * cleanly separated.
+   */
+  lens;
+  /** Mounted audit trail subgraph. */
+  audit;
+  _defaultActor;
+  _lensSubgraph;
+  constructor(target, opts = {}) {
+    super(opts.name ?? `inspect(${target.name})`);
+    this.target = target;
+    this._defaultActor = opts.actor;
+    this._lensSubgraph = new LensSubgraph(target);
+    this.lens = this._lensSubgraph.view;
+    this.mount("lens", this._lensSubgraph);
+    this.audit = auditTrail(target, opts.audit ?? {});
+    this.mount("audit", this.audit);
+    this.addDisposer(() => this.lens.dispose());
+  }
+  explainTarget(from, to, opts) {
+    const explainArg = { from, to };
+    if (opts?.maxDepth !== void 0) explainArg.maxDepth = opts.maxDepth;
+    if (opts?.findCycle !== void 0) explainArg.findCycle = opts.findCycle;
+    const describeOpts = { explain: explainArg };
+    if (opts?.reactive === true) describeOpts.reactive = true;
+    if (opts?.name !== void 0) describeOpts.name = opts.name;
+    return this.target.describe(describeOpts);
+  }
+  /**
+   * One-shot tamper-evident snapshot pairing the target's persisted state
+   * with the audit log + (optional) policy-gate violations.
+   *
+   * Uses the inspect's mounted `audit` by default; pair with a separate
+   * `policyGate` (mounted elsewhere) by passing `policies` explicitly.
+   *
+   * **Cryptographic strength caveat (echoed from {@link complianceSnapshot}):**
+   * the returned `fingerprint` is a truncated SHA-256 (16 hex chars / ~64
+   * bits) optimized for compact archival. Sufficient for casual integrity
+   * checks and content-addressed dedup; for adversarial tamper-evidence,
+   * pair with a full SHA-256 over the canonical JSON externally.
+   */
+  complianceSnapshot(opts) {
+    const actor = opts?.actor ?? this._defaultActor;
+    return complianceSnapshot(this.target, {
+      audit: this.audit,
+      ...actor != null ? { actor } : {},
+      ...opts?.policies != null ? { policies: opts.policies } : {}
+    });
+  }
+};
+function inspect(target, opts = {}) {
+  const g = new InspectGraph(target, opts);
+  g.tagFactory("inspect", (0, import_core5.placeholderArgs)(opts));
+  return g;
+}
+
+// src/presets/inspect/guarded-execution.ts
+var import_core6 = require("@graphrefly/pure-ts/core");
+var import_extra5 = require("@graphrefly/pure-ts/extra");
+var import_graph7 = require("@graphrefly/pure-ts/graph");
+function isNode2(x) {
+  return typeof x === "object" && x !== null && "subscribe" in x && "down" in x;
+}
+function guardedMeta(kind) {
+  return domainMeta("guarded", kind);
+}
+var GuardedExecutionGraph = class extends import_graph7.Graph {
+  enforcer;
+  violations;
+  lints;
+  scope;
+  /**
+   * Canonical reactive describe scoped to the wrapper's configured `actor`.
+   * Subscribes ONCE at construction; lifecycle owned by the wrapper (disposed
+   * on `wrapper.destroy()`). Use this property for the common case
+   * (long-lived consumer wanting "describe scoped to my actor"); use
+   * {@link scopedDescribeNode} only when a per-call actor override or
+   * different `detail`/`fields` is required.
+   *
+   * Re-derives on every settle of the target graph: structural changes,
+   * status transitions (errors flip nodes into `"errored"`), and actor
+   * emissions (when a `Node<Actor>` is bound, including the SENTINEL bridge
+   * applied internally — see qa G1B).
+   */
+  scopedDescribe;
+  _target;
+  _actorNode;
+  _mode;
+  _firedLintKinds = /* @__PURE__ */ new Set();
+  constructor(target, opts) {
+    super(opts.name ?? `${target.name}_guarded`, opts.graph);
+    this._target = target;
+    this._mode = opts.mode ?? "enforce";
+    const policiesOpt = opts.policies;
+    const policiesIsNode = isNode2(policiesOpt);
+    if (!policiesIsNode && this._mode === "enforce" && policiesOpt.length === 0) {
+      throw new RangeError(
+        'guardedExecution: empty `policies` in `mode: "enforce"` denies every action. Pass at least `{ effect: "allow", action: "*" }` and layer deny rules on top.'
+      );
+    }
+    this.lints = new TopicGraph("lints", {
+      retainedLimit: opts.lintsLimit ?? 64
+    });
+    this.mount("lints", this.lints);
+    const actorOpt = opts.actor;
+    if (actorOpt == null) {
+      this._actorNode = (0, import_core6.node)([], { name: "actor", initial: null });
+    } else if (isNode2(actorOpt)) {
+      this._actorNode = (0, import_core6.node)(
+        [actorOpt],
+        (batchData, actions, ctx) => {
+          const data = batchData.map(
+            (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+          );
+          actions.emit(data[0] ?? null);
+        },
+        { describeKind: "derived", name: "actor", initial: null }
+      );
+    } else {
+      this._actorNode = (0, import_core6.node)([], { name: "actor", initial: actorOpt });
+    }
+    const enforcerOpts = {
+      mode: this._mode,
+      name: "enforcer"
+    };
+    if (opts.violationsLimit != null) enforcerOpts.violationsLimit = opts.violationsLimit;
+    this.enforcer = policyGate(target, opts.policies, enforcerOpts);
+    this.violations = this.enforcer.violations;
+    this.mount("enforcer", this.enforcer);
+    if (policiesIsNode && this._mode === "enforce") {
+      const policiesNode = policiesOpt;
+      const cached = policiesNode.cache;
+      if (cached != null && cached.length === 0) {
+        this._fireLint(
+          "empty-policies",
+          '`policies` Node cached an empty array in `mode: "enforce"` \u2014 every action will be denied. Add at least one allow rule.'
+        );
+      }
+      const offEmpty = policiesNode.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (m[0] !== import_core6.DATA) continue;
+          const v = m[1];
+          if (v == null || v.length === 0) {
+            this._fireLint(
+              "empty-policies",
+              '`policies` Node emitted an empty array in `mode: "enforce"` \u2014 every action will be denied. Add at least one allow rule.'
+            );
+          }
+        }
+      });
+      this.addDisposer(offEmpty);
+    }
+    if (this._mode === "audit") {
+      const described = target.describe({ detail: "full" });
+      const anyGuard = Object.values(described.nodes).some((n) => n.guard != null);
+      if (!anyGuard) {
+        this._fireLint(
+          "audit-no-effect",
+          '`mode: "audit"` + target has no per-node guards \u2014 `scopedDescribeNode` filters by per-node guards only, so policy rules will not affect describe() visibility. Policies still populate the `violations` topic on writes.'
+        );
+      }
+    }
+    if (actorOpt == null) {
+      this._fireLint(
+        "no-actor",
+        "no actor configured \u2014 `wrapper.scopedDescribe` and `scopedDescribeNode()` will return an unscoped describe (full visibility) unless a per-call actor is supplied."
+      );
+    }
+    this.scope = (0, import_core6.node)(
+      [this._actorNode, this.enforcer.policies],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch4, i) => batch4 != null && batch4.length > 0 ? batch4.at(-1) : ctx.prevData[i]
+        );
+        actions.emit({
+          actor: data[0] ?? null,
+          mode: this._mode,
+          policiesCount: data[1].length
+        });
+      },
+      {
+        name: "scope",
+        describeKind: "derived",
+        meta: guardedMeta("scope")
+      }
+    );
+    this.add(this.scope, { name: "scope" });
+    this.addDisposer((0, import_extra5.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".
+      actor: this._actorNode,
+      reactiveName: "scopedDescribe"
+    });
+    this.scopedDescribe = scopedHandle.node;
+    this.add(this.scopedDescribe, { name: "scopedDescribe" });
+    this.addDisposer(scopedHandle.dispose);
+  }
+  _fireLint(kind, message) {
+    if (this._firedLintKinds.has(kind)) return;
+    this._firedLintKinds.add(kind);
+    this.lints.publish({ kind, message, timestamp_ns: (0, import_core6.monotonicNs)() });
+  }
+  /**
+   * **Per-call escape hatch.** Prefer {@link scopedDescribe} (the mounted
+   * property) for the common case of "describe scoped to my actor." Use
+   * this method ONLY when you need a per-call actor override or different
+   * `detail`/`fields`/`filter`.
+   *
+   * Returns a live `Node<GraphDescribeOutput>` scoped to the supplied (or
+   * configured) actor, plus an explicit `dispose` for caller-controlled
+   * lifecycle. Re-derives on every settle of the target graph: structural
+   * changes, status transitions, and actor emissions (when a `Node<Actor>`
+   * is bound).
+   *
+   * **Lifecycle (qa G1A — EC1 fix).** Each call instantiates a fresh
+   * `target.describe({reactive: true})` handle (with its own version state,
+   * observe handle, transitive topology subscriptions, derived + keepalive).
+   * The caller MUST invoke the returned `dispose()` when finished to release
+   * these resources. Disposers ARE also tracked on the wrapper graph so
+   * `wrapper.destroy()` cleans up any handles the caller forgot — but a
+   * long-lived wrapper with heavy per-call usage will leak until destroy
+   * unless `dispose()` is called explicitly.
+   *
+   * @param actorOverride - Optional per-call override. Static {@link Actor}
+   *   or `Node<Actor>`. Omit to use the wrapper-configured default.
+   * @param opts - Standard {@link GraphDescribeOptions} fields (`detail`,
+   *   `fields`, `filter`). `actor` / `reactive` / `reactiveName` are
+   *   controlled by the wrapper.
+   * @returns `{node, dispose}` — `node` is the live describe Node; `dispose`
+   *   tears down the underlying reactive describe subscription idempotently.
+   */
+  scopedDescribeNode(actorOverride, opts) {
+    const actorNode = actorOverride == null ? this._actorNode : isNode2(actorOverride) ? actorOverride : (0, import_core6.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."
+      actor: actorNode,
+      ...opts ?? {}
+    });
+    this.addDisposer(handle.dispose);
+    return { node: handle.node, dispose: handle.dispose };
+  }
+  /** The wrapped graph (escape hatch for tooling). */
+  get target() {
+    return this._target;
+  }
+};
+function guardedExecution(target, opts) {
+  return new GuardedExecutionGraph(target, opts);
+}
+//# sourceMappingURL=index.cjs.map