@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/chunk-Z65DVDEQ.js

@@ -0,0 +1,146 @@
+// src/base/composition/backpressure.ts
+import { PAUSE, RESUME } from "@graphrefly/pure-ts/core";
+var nextLockId = 0;
+function createWatermarkController(sendUp, opts) {
+  if (opts.highWaterMark < 1) throw new RangeError("highWaterMark must be >= 1");
+  if (opts.lowWaterMark < 0) throw new RangeError("lowWaterMark must be >= 0");
+  if (opts.lowWaterMark >= opts.highWaterMark)
+    throw new RangeError("lowWaterMark must be < highWaterMark");
+  const lockId = /* @__PURE__ */ Symbol(`bp-${++nextLockId}`);
+  let pending = 0;
+  let paused = false;
+  return {
+    onEnqueue() {
+      pending += 1;
+      if (!paused && pending >= opts.highWaterMark) {
+        paused = true;
+        sendUp([[PAUSE, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    onDequeue() {
+      if (pending > 0) pending -= 1;
+      if (paused && pending <= opts.lowWaterMark) {
+        paused = false;
+        sendUp([[RESUME, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    get pending() {
+      return pending;
+    },
+    get paused() {
+      return paused;
+    },
+    dispose() {
+      if (paused) {
+        paused = false;
+        sendUp([[RESUME, lockId]]);
+      }
+    }
+  };
+}
+
+// src/base/composition/observable.ts
+import { COMPLETE, DATA, ERROR } from "@graphrefly/pure-ts/core";
+var OBSERVABLE_KEY = typeof Symbol === "function" && Symbol.observable || "@@observable";
+function normalizeObserver(observer) {
+  return typeof observer === "function" ? { next: observer } : observer;
+}
+function makeInterop(onSubscribe) {
+  const obs = {
+    subscribe(rawObserver) {
+      const observer = normalizeObserver(rawObserver);
+      let closed = false;
+      let teardown;
+      let teardownPending = false;
+      const runTeardown = () => {
+        if (teardown) teardown();
+        else teardownPending = true;
+      };
+      const guarded = {
+        get closed() {
+          return closed;
+        },
+        next(value) {
+          if (!closed) observer.next?.(value);
+        },
+        error(err) {
+          if (closed) return;
+          closed = true;
+          try {
+            observer.error?.(err);
+          } finally {
+            runTeardown();
+          }
+        },
+        complete() {
+          if (closed) return;
+          closed = true;
+          try {
+            observer.complete?.();
+          } finally {
+            runTeardown();
+          }
+        }
+      };
+      teardown = onSubscribe(guarded);
+      if (teardownPending) teardown();
+      return {
+        unsubscribe() {
+          if (closed) return;
+          closed = true;
+          teardown?.();
+        }
+      };
+    }
+  };
+  obs[OBSERVABLE_KEY] = function() {
+    return this;
+  };
+  return obs;
+}
+function toObservable(node, options) {
+  if (options?.raw) {
+    return makeInterop((observer) => {
+      return node.subscribe((msgs) => {
+        if (observer.closed) return;
+        observer.next?.(msgs);
+        for (const m of msgs) {
+          if (m[0] === ERROR) {
+            observer.error?.(m[1]);
+            return;
+          }
+          if (m[0] === COMPLETE) {
+            observer.complete?.();
+            return;
+          }
+        }
+      });
+    });
+  }
+  return makeInterop((observer) => {
+    return node.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (observer.closed) return;
+        if (m[0] === DATA) {
+          observer.next?.(m[1]);
+        } else if (m[0] === ERROR) {
+          observer.error?.(m[1]);
+          return;
+        } else if (m[0] === COMPLETE) {
+          observer.complete?.();
+          return;
+        }
+      }
+    });
+  });
+}
+
+export {
+  createWatermarkController,
+  toObservable
+};
+//# sourceMappingURL=chunk-Z65DVDEQ.js.map

package/dist/chunk-Z65DVDEQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base/composition/backpressure.ts","../src/base/composition/observable.ts"],"sourcesContent":["/**\n * Watermark-based backpressure controller — reactive PAUSE/RESUME flow control.\n *\n * Purely synchronous, event-driven. No timers, no polling, no Promises.\n * Each controller instance uses a unique lockId so multiple controllers\n * on the same upstream node do not collide.\n *\n * @module\n */\n\nimport { type Messages, PAUSE, RESUME } from \"@graphrefly/pure-ts/core\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type WatermarkOptions = {\n\t/** Pending count at which PAUSE is sent upstream. */\n\thighWaterMark: number;\n\t/** Pending count at which RESUME is sent upstream (after being paused). */\n\tlowWaterMark: number;\n};\n\nexport type WatermarkController = {\n\t/** Call when a DATA message is buffered/enqueued. Returns `true` if PAUSE was just sent. */\n\tonEnqueue(): boolean;\n\t/** Call when a buffered item is consumed. Returns `true` if RESUME was just sent. */\n\tonDequeue(): boolean;\n\t/** Current un-consumed item count. */\n\treadonly pending: number;\n\t/** Whether upstream is currently paused by this controller. */\n\treadonly paused: boolean;\n\t/** Dispose: if paused, sends RESUME to unblock upstream. */\n\tdispose(): void;\n};\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\nlet nextLockId = 0;\n\n/**\n * Creates a watermark-based backpressure controller.\n *\n * @param sendUp - Callback that delivers messages upstream (typically `handle.up`).\n * @param opts - High/low watermark thresholds (item counts).\n * @returns A {@link WatermarkController}.\n *\n * @example\n * ```ts\n * const handle = graph.observe(\"fast-source\");\n * const wm = createWatermarkController(\n *   (msgs) => handle.up(msgs),\n *   { highWaterMark: 64, lowWaterMark: 16 },\n * );\n *\n * // In sink callback:\n * handle.subscribe((msgs) => {\n *   for (const msg of msgs) {\n *     if (msg[0] === DATA) {\n *       buffer.push(msg[1]);\n *       wm.onEnqueue();\n *     }\n *   }\n * });\n *\n * // When consumer drains:\n * const item = buffer.shift();\n * wm.onDequeue();\n * ```\n *\n * @category extra\n */\nexport function createWatermarkController(\n\tsendUp: (messages: Messages) => void,\n\topts: WatermarkOptions,\n): WatermarkController {\n\tif (opts.highWaterMark < 1) throw new RangeError(\"highWaterMark must be >= 1\");\n\tif (opts.lowWaterMark < 0) throw new RangeError(\"lowWaterMark must be >= 0\");\n\tif (opts.lowWaterMark >= opts.highWaterMark)\n\t\tthrow new RangeError(\"lowWaterMark must be < highWaterMark\");\n\tconst lockId = Symbol(`bp-${++nextLockId}`);\n\tlet pending = 0;\n\tlet paused = false;\n\n\treturn {\n\t\tonEnqueue(): boolean {\n\t\t\tpending += 1;\n\t\t\tif (!paused && pending >= opts.highWaterMark) {\n\t\t\t\tpaused = true;\n\t\t\t\tsendUp([[PAUSE, lockId]]);\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\treturn false;\n\t\t},\n\t\tonDequeue(): boolean {\n\t\t\tif (pending > 0) pending -= 1;\n\t\t\tif (paused && pending <= opts.lowWaterMark) {\n\t\t\t\tpaused = false;\n\t\t\t\tsendUp([[RESUME, lockId]]);\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\treturn false;\n\t\t},\n\t\tget pending() {\n\t\t\treturn pending;\n\t\t},\n\t\tget paused() {\n\t\t\treturn paused;\n\t\t},\n\t\tdispose() {\n\t\t\tif (paused) {\n\t\t\t\tpaused = false;\n\t\t\t\tsendUp([[RESUME, lockId]]);\n\t\t\t}\n\t\t},\n\t};\n}\n","// ---------------------------------------------------------------------------\n// Observable bridge — reactive interop between GraphReFly nodes and the TC39\n// Observable contract (the well-known `Symbol.observable` / \"@@observable\"\n// method). **Zero runtime dependency on rxjs**: the returned value is a\n// spec-interop observable that rxjs `from()`, Angular, the NestJS compat\n// layer, and any `Symbol.observable` consumer can adopt. Consumers wanting\n// rxjs operators do `from(toObservable(node))`.\n//\n// Usage:\n//   import { toObservable } from '@graphrefly/graphrefly/base';\n//   import { from } from 'rxjs';\n//   const values$ = from(toObservable(myNode));               // Observable<T>\n//   const msgs$   = from(toObservable(myNode, { raw: true })); // Observable<Messages>\n// ---------------------------------------------------------------------------\n\nimport type { Node } from \"@graphrefly/pure-ts/core\";\nimport { COMPLETE, DATA, ERROR, type Messages } from \"@graphrefly/pure-ts/core\";\n\n/** Observer passed to {@link InteropObservable.subscribe}. */\nexport interface InteropObserver<T> {\n\tnext?(value: T): void;\n\terror?(err: unknown): void;\n\tcomplete?(): void;\n\t/** rxjs `Subscriber` sets this; we short-circuit delivery when closed. */\n\tclosed?: boolean;\n}\n\n/** Teardown handle returned by {@link InteropObservable.subscribe}. */\nexport interface InteropSubscription {\n\tunsubscribe(): void;\n}\n\n/**\n * Minimal TC39 Observable. rxjs `from()` (and any `Symbol.observable`\n * consumer) adopts it at runtime via the well-known interop method attached\n * by {@link toObservable}. Pass the result through `from(...)` to get a\n * pipeable rxjs `Observable`.\n */\nexport interface InteropObservable<T> {\n\tsubscribe(observer: InteropObserver<T> | ((value: T) => void)): InteropSubscription;\n}\n\n/** Options for {@link toObservable}. */\nexport type ToObservableOptions = {\n\t/**\n\t * When `true`, emit raw `Messages` batches instead of extracted `DATA`\n\t * values. Terminal batches are still emitted as the final `next()` before\n\t * the error/complete signal.\n\t */\n\traw?: boolean;\n};\n\n// Well-known Observable interop key. Mirrors the rxjs / `symbol-observable`\n// resolution (the global `Symbol.observable` when the runtime or a polyfill\n// provides it, otherwise the `\"@@observable\"` string) so rxjs `from()` adopts\n// our object regardless of polyfill state.\nconst OBSERVABLE_KEY: PropertyKey =\n\t(typeof Symbol === \"function\" && (Symbol as unknown as { observable?: symbol }).observable) ||\n\t\"@@observable\";\n\nfunction normalizeObserver<T>(\n\tobserver: InteropObserver<T> | ((value: T) => void),\n): InteropObserver<T> {\n\treturn typeof observer === \"function\" ? { next: observer } : observer;\n}\n\nfunction makeInterop<T>(\n\tonSubscribe: (observer: InteropObserver<T>) => () => void,\n): InteropObservable<T> {\n\tconst obs: InteropObservable<T> = {\n\t\tsubscribe(rawObserver): InteropSubscription {\n\t\t\tconst observer = normalizeObserver(rawObserver);\n\t\t\tlet closed = false;\n\t\t\tlet teardown: (() => void) | undefined;\n\t\t\tlet teardownPending = false;\n\t\t\tconst runTeardown = (): void => {\n\t\t\t\tif (teardown) teardown();\n\t\t\t\telse teardownPending = true; // sync push-on-subscribe terminal\n\t\t\t};\n\t\t\t// Guarded observer: latch `closed` and auto-unsubscribe the node on\n\t\t\t// terminal. The prior rxjs-backed impl got this from rxjs's\n\t\t\t// `Subscriber` (closed flag + teardown-on-terminal); a plain TC39\n\t\t\t// consumer has no such machinery, so without this a post-terminal\n\t\t\t// node wave would re-fire next/error/complete and the node\n\t\t\t// subscription would leak until a manual unsubscribe(). `closed` is\n\t\t\t// also read by toObservable's per-message loop to short-circuit.\n\t\t\tconst guarded: InteropObserver<T> = {\n\t\t\t\tget closed() {\n\t\t\t\t\treturn closed;\n\t\t\t\t},\n\t\t\t\tnext(value) {\n\t\t\t\t\tif (!closed) observer.next?.(value);\n\t\t\t\t},\n\t\t\t\terror(err) {\n\t\t\t\t\tif (closed) return;\n\t\t\t\t\tclosed = true;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tobserver.error?.(err);\n\t\t\t\t\t} finally {\n\t\t\t\t\t\trunTeardown();\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tcomplete() {\n\t\t\t\t\tif (closed) return;\n\t\t\t\t\tclosed = true;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tobserver.complete?.();\n\t\t\t\t\t} finally {\n\t\t\t\t\t\trunTeardown();\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t};\n\t\t\tteardown = onSubscribe(guarded);\n\t\t\tif (teardownPending) teardown(); // terminal fired before assignment\n\t\t\treturn {\n\t\t\t\tunsubscribe() {\n\t\t\t\t\tif (closed) return;\n\t\t\t\t\tclosed = true;\n\t\t\t\t\tteardown?.();\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t};\n\t// TC39 interop: `x[Symbol.observable]()` returns the observable itself.\n\t(obs as unknown as Record<PropertyKey, unknown>)[OBSERVABLE_KEY] = function (\n\t\tthis: InteropObservable<T>,\n\t) {\n\t\treturn this;\n\t};\n\treturn obs;\n}\n\n/**\n * Bridge a `Node<T>` to a TC39 interop observable (no rxjs dependency).\n *\n * Default mode emits the node's value on each `DATA` message. Maps `ERROR` to\n * `observer.error()` and `COMPLETE` to `observer.complete()`.\n * Protocol-internal signals (DIRTY, RESOLVED, PAUSE, etc.) are skipped.\n *\n * With `{ raw: true }`, emits full `[[Type, Data?], ...]` message batches.\n * The stream terminates on ERROR or COMPLETE (the terminal batch is still\n * emitted as the final `next()` before the error/complete signal).\n *\n * The returned value is a spec-interop observable, **not** a concrete rxjs\n * `Observable`. Wrap with `from(toObservable(node))` for rxjs operators, or\n * use the NestJS compat layer's `toObservable` which returns a real rxjs\n * `Observable`. For graph-level observation, use\n * `toObservable(graph.resolve(path))` or subscribe to `graph.observe()`.\n *\n * Unsubscribing unsubscribes the node.\n */\nexport function toObservable<T>(\n\tnode: Node<T>,\n\toptions?: ToObservableOptions & { raw?: false },\n): InteropObservable<T>;\nexport function toObservable<T>(\n\tnode: Node<T>,\n\toptions: ToObservableOptions & { raw: true },\n): InteropObservable<Messages>;\nexport function toObservable<T>(\n\tnode: Node<T>,\n\toptions?: ToObservableOptions,\n): InteropObservable<T | Messages> {\n\tif (options?.raw) {\n\t\treturn makeInterop<Messages>((observer) => {\n\t\t\treturn node.subscribe((msgs) => {\n\t\t\t\tif (observer.closed) return;\n\t\t\t\tobserver.next?.(msgs);\n\t\t\t\tfor (const m of msgs) {\n\t\t\t\t\tif (m[0] === ERROR) {\n\t\t\t\t\t\tobserver.error?.(m[1]);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tif (m[0] === COMPLETE) {\n\t\t\t\t\t\tobserver.complete?.();\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t});\n\t}\n\n\treturn makeInterop<T>((observer) => {\n\t\treturn node.subscribe((msgs) => {\n\t\t\tfor (const m of msgs) {\n\t\t\t\tif (observer.closed) return;\n\t\t\t\tif (m[0] === DATA) {\n\t\t\t\t\tobserver.next?.(m[1] as T);\n\t\t\t\t} else if (m[0] === ERROR) {\n\t\t\t\t\tobserver.error?.(m[1]);\n\t\t\t\t\treturn;\n\t\t\t\t} else if (m[0] === COMPLETE) {\n\t\t\t\t\tobserver.complete?.();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t});\n\t});\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-Z6EGP5D7.js

@@ -0,0 +1,92 @@
+import {
+  graphLens
+} from "./chunk-4XCHZRUJ.js";
+import {
+  auditTrail,
+  complianceSnapshot
+} from "./chunk-FW23JYNQ.js";
+
+// src/presets/inspect/composite.ts
+import { placeholderArgs } from "@graphrefly/pure-ts/core";
+import { Graph } from "@graphrefly/pure-ts/graph";
+var LensSubgraph = class extends 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 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", placeholderArgs(opts));
+  return g;
+}
+
+export {
+  InspectGraph,
+  inspect
+};
+//# sourceMappingURL=chunk-Z6EGP5D7.js.map

package/dist/chunk-Z6EGP5D7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/presets/inspect/composite.ts"],"sourcesContent":["/**\n * `inspect()` preset — Tier 9.1 γ-form γ-II + Q5-6 medium scope.\n *\n * Composes graph observability into a single mounted facade:\n *   - `lens` (mounted as a `LensSubgraph` child) — exposes `topology` /\n *     `health` / `flow` Nodes via `inspect.lens.*`.\n *   - `audit` (mounted `AuditTrailGraph`) — every mutation on the wrapped\n *     target captured as an audit entry.\n *   - `explainTarget(from, to, opts?)` — facade over\n *     `target.describe({ explain: {...} })`; supports both static and\n *     reactive forms.\n *   - `complianceSnapshot()` — one-shot tamper-evident snapshot pairing the\n *     target's persisted state with the audit log.\n *\n * **Path-namespace boundary.** `inspect.describe()` shows InspectGraph's\n * OWN topology (the lens + audit subgraphs and any caller-added siblings) —\n * NOT the wrapped target's topology. Use `inspect.target.describe()` to\n * walk the target. `inspect.node(\"counter\")` resolves under the inspect\n * graph, NOT the target.\n *\n * **Why a Graph subclass.** Per Tier 9.1 γ-II lock: closure-bundled returns\n * (`{lens, audit, explain, ...}` of independently-constructed primitives)\n * hide topology — `describe()` from the wrapper can't walk into the\n * audit/lens pieces. Mounting them under a real `InspectGraph` keeps every\n * contained primitive visible in describe / explain across the boundary,\n * which is the point of the inspect preset.\n *\n * **Why the lens lives in a child `LensSubgraph` mount.** `Graph.destroy()`\n * signals TEARDOWN through `this._nodes` after disposers drain. If the\n * lens nodes were `add()`ed directly to InspectGraph's path table, they\n * would receive TEARDOWN at parent destroy — invalidating any externally\n * held `view.lens.topology.subscribe(...)` reference. Mounting via a child\n * subgraph contains the cascade: inspect's TEARDOWN visits the lens\n * subgraph's nodes through `mount → child._destroyClearOnly`, which clears\n * structure but does NOT broadcast TEARDOWN. The `lens.dispose()` disposer\n * still tears down the underlying observe handle as designed (D1 fix per\n * /qa lock).\n *\n * **Why `inspect()` mounts `graphLens` rather than rebuilding `health` / `flow`.**\n * Per Q3 yellow lock: rebuilding would duplicate the `topology → health`\n * and `dataFlow → flow` deriveds, doubling subscription cost and risking\n * semantic drift. Mounting graphLens once lets `inspect.lens` and the\n * standalone `graphLens(target)` factory share a single source of truth.\n *\n * @module\n */\n\nimport type { Actor, Node } from \"@graphrefly/pure-ts/core\";\nimport { placeholderArgs } from \"@graphrefly/pure-ts/core\";\nimport { type CausalChain, Graph } from \"@graphrefly/pure-ts/graph\";\nimport {\n\ttype AuditTrailGraph,\n\ttype AuditTrailOptions,\n\tauditTrail,\n\ttype ComplianceSnapshotResult,\n\tcomplianceSnapshot,\n\ttype PolicyGateGraph,\n} from \"../../utils/inspect/audit.js\";\nimport { type GraphLensView, graphLens } from \"../../utils/inspect/lens.js\";\n\n/** Options for {@link inspect}. */\nexport interface InspectOptions {\n\t/** Default actor recorded on `complianceSnapshot()` calls. */\n\tactor?: Actor;\n\t/**\n\t * Forwarded to the mounted {@link auditTrail} so callers can configure\n\t * retention / inclusion policy. Pre-allocated to keep `inspect()`\n\t * callable with no opts.\n\t */\n\taudit?: AuditTrailOptions;\n\t/** Optional name override for the `InspectGraph` itself. */\n\tname?: string;\n}\n\n/**\n * Thin Graph-subclass shell that owns the `graphLens(target)` Nodes so\n * inspect's TEARDOWN cascade reaches them via `_destroyClearOnly` (which\n * clears structure WITHOUT broadcasting TEARDOWN) instead of via\n * `signal([[TEARDOWN]])` (which DOES broadcast and would invalidate any\n * externally held lens-node subscription).\n *\n * @internal\n */\nclass LensSubgraph extends Graph {\n\treadonly view: GraphLensView;\n\n\tconstructor(target: Graph) {\n\t\tsuper(\"lens\");\n\t\tthis.view = graphLens(target);\n\t\tthis.add(this.view.topology, { name: \"topology\" });\n\t\tthis.add(this.view.health, { name: \"health\" });\n\t\tthis.add(this.view.flow, { name: \"flow\" });\n\t}\n}\n\n/**\n * Graph subclass returned by {@link inspect}. Mounts a `graphLens` view (as\n * a child `LensSubgraph`), an `auditTrail` (as a child subgraph), and\n * exposes `explainTarget()` + `complianceSnapshot()` facades over the\n * wrapped target.\n *\n * Mounted children (visible in `describe()`):\n *   - `lens::topology` / `lens::health` / `lens::flow` — `graphLens(target)` Nodes.\n *   - `audit::*` — the mounted {@link AuditTrailGraph}.\n *\n * @category observability\n */\nexport class InspectGraph extends Graph {\n\treadonly target: Graph;\n\t/**\n\t * Underlying lens view — reach individual Nodes via\n\t * `inspect.lens.topology` / `inspect.lens.health` / `inspect.lens.flow`.\n\t *\n\t * Direct `inspect.topology` / `inspect.health` / `inspect.flow`\n\t * accessors are NOT shipped because `Graph.topology` is already an\n\t * accessor on the base class with a different shape (`Node<TopologyEvent>`\n\t * — the mount/unmount stream of THIS graph, not the wrapped target's\n\t * describe snapshot). Going through `.lens.*` keeps the two concepts\n\t * cleanly separated.\n\t */\n\treadonly lens: GraphLensView;\n\t/** Mounted audit trail subgraph. */\n\treadonly audit: AuditTrailGraph;\n\n\tprivate readonly _defaultActor?: Actor;\n\tprivate readonly _lensSubgraph: LensSubgraph;\n\n\tconstructor(target: Graph, opts: InspectOptions = {}) {\n\t\tsuper(opts.name ?? `inspect(${target.name})`);\n\t\tthis.target = target;\n\t\tthis._defaultActor = opts.actor;\n\n\t\t// D1 (qa lock): lens lives inside a child mount so `inspect.destroy()`'s\n\t\t// TEARDOWN signal cascade reaches the lens nodes via\n\t\t// `_destroyClearOnly` (no broadcast) rather than via `_signalDeliver`\n\t\t// over `inspect._nodes` (which WOULD broadcast). External holders of\n\t\t// `view.lens.topology.subscribe(...)` see only the `lens.dispose()`\n\t\t// teardown of the underlying observe handle, not a stray TEARDOWN\n\t\t// from inspect's path table.\n\t\tthis._lensSubgraph = new LensSubgraph(target);\n\t\tthis.lens = this._lensSubgraph.view;\n\t\tthis.mount(\"lens\", this._lensSubgraph);\n\n\t\tthis.audit = auditTrail(target, opts.audit ?? {});\n\t\tthis.mount(\"audit\", this.audit);\n\n\t\t// Tear down the lens's underlying observe subscription on destroy.\n\t\t// The mounted subgraphs themselves tear down via mount lifecycle.\n\t\tthis.addDisposer(() => this.lens.dispose());\n\t}\n\n\t/**\n\t * Causal-chain facade over `target.describe({ explain: {...} })`. Supports\n\t * both static (one-shot {@link CausalChain}) and reactive\n\t * (`{ reactive: true }`) forms.\n\t *\n\t * Named `explainTarget` (not folded into a `describe` mode on this class)\n\t * because `inspect.describe(...)` walks `InspectGraph`'s OWN topology\n\t * (lens + audit subgraphs) rather than the wrapped target's. Use\n\t * `inspect.explainTarget(...)` for chains across the wrapped graph;\n\t * `inspect.describe({ explain: {...} })` for chains across the lens /\n\t * audit composition.\n\t */\n\texplainTarget(\n\t\tfrom: string | Node<string>,\n\t\tto: string | Node<string>,\n\t\topts?: {\n\t\t\tmaxDepth?: number | Node<number>;\n\t\t\tfindCycle?: boolean | Node<boolean>;\n\t\t},\n\t): CausalChain;\n\texplainTarget(\n\t\tfrom: string | Node<string>,\n\t\tto: string | Node<string>,\n\t\topts: {\n\t\t\treactive: true;\n\t\t\tmaxDepth?: number | Node<number>;\n\t\t\tfindCycle?: boolean | Node<boolean>;\n\t\t\tname?: string;\n\t\t},\n\t): { node: Node<CausalChain>; dispose: () => void };\n\texplainTarget(\n\t\tfrom: string | Node<string>,\n\t\tto: string | Node<string>,\n\t\topts?: {\n\t\t\treactive?: boolean;\n\t\t\tmaxDepth?: number | Node<number>;\n\t\t\tfindCycle?: boolean | Node<boolean>;\n\t\t\tname?: string;\n\t\t},\n\t): CausalChain | { node: Node<CausalChain>; dispose: () => void } {\n\t\t// Cast through the discriminated overload — TypeScript can't pick a\n\t\t// signature on `target.describe({explain})` because `opts` has the\n\t\t// union shape (reactive: boolean | undefined).\n\t\tconst explainArg: {\n\t\t\tfrom: string | Node<string>;\n\t\t\tto: string | Node<string>;\n\t\t\tmaxDepth?: number | Node<number>;\n\t\t\tfindCycle?: boolean | Node<boolean>;\n\t\t} = { from, to };\n\t\tif (opts?.maxDepth !== undefined) explainArg.maxDepth = opts.maxDepth;\n\t\tif (opts?.findCycle !== undefined) explainArg.findCycle = opts.findCycle;\n\t\tconst describeOpts: Record<string, unknown> = { explain: explainArg };\n\t\tif (opts?.reactive === true) describeOpts.reactive = true;\n\t\tif (opts?.name !== undefined) describeOpts.name = opts.name;\n\t\treturn (\n\t\t\tthis.target.describe as unknown as (\n\t\t\t\to: typeof describeOpts,\n\t\t\t) => CausalChain | { node: Node<CausalChain>; dispose: () => void }\n\t\t)(describeOpts);\n\t}\n\n\t/**\n\t * One-shot tamper-evident snapshot pairing the target's persisted state\n\t * with the audit log + (optional) policy-gate violations.\n\t *\n\t * Uses the inspect's mounted `audit` by default; pair with a separate\n\t * `policyGate` (mounted elsewhere) by passing `policies` explicitly.\n\t *\n\t * **Cryptographic strength caveat (echoed from {@link complianceSnapshot}):**\n\t * the returned `fingerprint` is a truncated SHA-256 (16 hex chars / ~64\n\t * bits) optimized for compact archival. Sufficient for casual integrity\n\t * checks and content-addressed dedup; for adversarial tamper-evidence,\n\t * pair with a full SHA-256 over the canonical JSON externally.\n\t */\n\tcomplianceSnapshot(opts?: {\n\t\tactor?: Actor;\n\t\tpolicies?: PolicyGateGraph;\n\t}): ComplianceSnapshotResult {\n\t\tconst actor = opts?.actor ?? this._defaultActor;\n\t\treturn complianceSnapshot(this.target, {\n\t\t\taudit: this.audit,\n\t\t\t...(actor != null ? { actor } : {}),\n\t\t\t...(opts?.policies != null ? { policies: opts.policies } : {}),\n\t\t});\n\t}\n}\n\n/**\n * Build an {@link InspectGraph} that mounts `graphLens` + `auditTrail` over\n * the wrapped target and exposes `explainTarget()` + `complianceSnapshot()`\n * facades.\n *\n * @example\n * ```ts\n * import { inspect } from \"@graphrefly/graphrefly/patterns/inspect\";\n *\n * const target = buildMyApp();\n * const view = inspect(target, { actor: { id: \"ops-bot\", role: \"monitor\" } });\n *\n * // Live observability\n * view.lens.health.subscribe((msgs) => console.log(\"health:\", msgs));\n * view.lens.flow.subscribe((msgs) => console.log(\"flow:\", msgs));\n *\n * // Causal explainability across the wrapped target\n * const chain = view.explainTarget(\"input\", \"output\");\n *\n * // Tamper-evident snapshot for archival\n * const snapshot = view.complianceSnapshot();\n * ```\n *\n * @category observability\n */\nexport function inspect(target: Graph, opts: InspectOptions = {}): InspectGraph {\n\tconst g = new InspectGraph(target, opts);\n\t// A1 (qa lock): self-tag so `inspect.describe().factory === \"inspect\"`,\n\t// matching the policyGate / pipelineGraph / harnessLoop precedent.\n\tg.tagFactory(\"inspect\", placeholderArgs(opts as unknown as Record<string, unknown>));\n\treturn g;\n}\n"],"mappings":";;;;;;;;;AAgDA,SAAS,uBAAuB;AAChC,SAA2B,aAAa;AAkCxC,IAAM,eAAN,cAA2B,MAAM;AAAA,EACvB;AAAA,EAET,YAAY,QAAe;AAC1B,UAAM,MAAM;AACZ,SAAK,OAAO,UAAU,MAAM;AAC5B,SAAK,IAAI,KAAK,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACjD,SAAK,IAAI,KAAK,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7C,SAAK,IAAI,KAAK,KAAK,MAAM,EAAE,MAAM,OAAO,CAAC;AAAA,EAC1C;AACD;AAcO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA;AAAA;AAAA,EAEA;AAAA,EAEQ;AAAA,EACA;AAAA,EAEjB,YAAY,QAAe,OAAuB,CAAC,GAAG;AACrD,UAAM,KAAK,QAAQ,WAAW,OAAO,IAAI,GAAG;AAC5C,SAAK,SAAS;AACd,SAAK,gBAAgB,KAAK;AAS1B,SAAK,gBAAgB,IAAI,aAAa,MAAM;AAC5C,SAAK,OAAO,KAAK,cAAc;AAC/B,SAAK,MAAM,QAAQ,KAAK,aAAa;AAErC,SAAK,QAAQ,WAAW,QAAQ,KAAK,SAAS,CAAC,CAAC;AAChD,SAAK,MAAM,SAAS,KAAK,KAAK;AAI9B,SAAK,YAAY,MAAM,KAAK,KAAK,QAAQ,CAAC;AAAA,EAC3C;AAAA,EAgCA,cACC,MACA,IACA,MAMiE;AAIjE,UAAM,aAKF,EAAE,MAAM,GAAG;AACf,QAAI,MAAM,aAAa,OAAW,YAAW,WAAW,KAAK;AAC7D,QAAI,MAAM,cAAc,OAAW,YAAW,YAAY,KAAK;AAC/D,UAAM,eAAwC,EAAE,SAAS,WAAW;AACpE,QAAI,MAAM,aAAa,KAAM,cAAa,WAAW;AACrD,QAAI,MAAM,SAAS,OAAW,cAAa,OAAO,KAAK;AACvD,WACC,KAAK,OAAO,SAGX,YAAY;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,mBAAmB,MAGU;AAC5B,UAAM,QAAQ,MAAM,SAAS,KAAK;AAClC,WAAO,mBAAmB,KAAK,QAAQ;AAAA,MACtC,OAAO,KAAK;AAAA,MACZ,GAAI,SAAS,OAAO,EAAE,MAAM,IAAI,CAAC;AAAA,MACjC,GAAI,MAAM,YAAY,OAAO,EAAE,UAAU,KAAK,SAAS,IAAI,CAAC;AAAA,IAC7D,CAAC;AAAA,EACF;AACD;AA2BO,SAAS,QAAQ,QAAe,OAAuB,CAAC,GAAiB;AAC/E,QAAM,IAAI,IAAI,aAAa,QAAQ,IAAI;AAGvC,IAAE,WAAW,WAAW,gBAAgB,IAA0C,CAAC;AACnF,SAAO;AACR;","names":[]}