@graphrefly/graphrefly 0.45.0 → 0.46.0

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":[]}