@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/presets/inspect/index.d.ts

@@ -0,0 +1,172 @@
+import { Actor, Node } from '@graphrefly/pure-ts/core';
+import { Graph, CausalChain } from '@graphrefly/pure-ts/graph';
+export { DescribeFilter } from '@graphrefly/pure-ts/graph';
+import { a as AuditTrailGraph, b as AuditTrailOptions, P as PolicyGateGraph, c as ComplianceSnapshotResult } from '../../audit-BAXb3VOg.js';
+import { GraphLensView } from '../../utils/inspect/index.js';
+export { G as GuardedExecutionGraph, a as GuardedExecutionLint, b as GuardedExecutionOptions, c as GuardedScope, g as guardedExecution } from '../../guarded-execution-BcdtxeBk.js';
+import '../../utils/messaging/index.js';
+import '@graphrefly/pure-ts/extra';
+import '../../base/mutation/index.js';
+
+/**
+ * `inspect()` preset — Tier 9.1 γ-form γ-II + Q5-6 medium scope.
+ *
+ * Composes graph observability into a single mounted facade:
+ *   - `lens` (mounted as a `LensSubgraph` child) — exposes `topology` /
+ *     `health` / `flow` Nodes via `inspect.lens.*`.
+ *   - `audit` (mounted `AuditTrailGraph`) — every mutation on the wrapped
+ *     target captured as an audit entry.
+ *   - `explainTarget(from, to, opts?)` — facade over
+ *     `target.describe({ explain: {...} })`; supports both static and
+ *     reactive forms.
+ *   - `complianceSnapshot()` — one-shot tamper-evident snapshot pairing the
+ *     target's persisted state with the audit log.
+ *
+ * **Path-namespace boundary.** `inspect.describe()` shows InspectGraph's
+ * OWN topology (the lens + audit subgraphs and any caller-added siblings) —
+ * NOT the wrapped target's topology. Use `inspect.target.describe()` to
+ * walk the target. `inspect.node("counter")` resolves under the inspect
+ * graph, NOT the target.
+ *
+ * **Why a Graph subclass.** Per Tier 9.1 γ-II lock: closure-bundled returns
+ * (`{lens, audit, explain, ...}` of independently-constructed primitives)
+ * hide topology — `describe()` from the wrapper can't walk into the
+ * audit/lens pieces. Mounting them under a real `InspectGraph` keeps every
+ * contained primitive visible in describe / explain across the boundary,
+ * which is the point of the inspect preset.
+ *
+ * **Why the lens lives in a child `LensSubgraph` mount.** `Graph.destroy()`
+ * signals TEARDOWN through `this._nodes` after disposers drain. If the
+ * lens nodes were `add()`ed directly to InspectGraph's path table, they
+ * would receive TEARDOWN at parent destroy — invalidating any externally
+ * held `view.lens.topology.subscribe(...)` reference. Mounting via a child
+ * subgraph contains the cascade: inspect's TEARDOWN visits the lens
+ * subgraph's nodes through `mount → child._destroyClearOnly`, which clears
+ * structure but does NOT broadcast TEARDOWN. The `lens.dispose()` disposer
+ * still tears down the underlying observe handle as designed (D1 fix per
+ * /qa lock).
+ *
+ * **Why `inspect()` mounts `graphLens` rather than rebuilding `health` / `flow`.**
+ * Per Q3 yellow lock: rebuilding would duplicate the `topology → health`
+ * and `dataFlow → flow` deriveds, doubling subscription cost and risking
+ * semantic drift. Mounting graphLens once lets `inspect.lens` and the
+ * standalone `graphLens(target)` factory share a single source of truth.
+ *
+ * @module
+ */
+
+/** Options for {@link inspect}. */
+interface InspectOptions {
+    /** Default actor recorded on `complianceSnapshot()` calls. */
+    actor?: Actor;
+    /**
+     * Forwarded to the mounted {@link auditTrail} so callers can configure
+     * retention / inclusion policy. Pre-allocated to keep `inspect()`
+     * callable with no opts.
+     */
+    audit?: AuditTrailOptions;
+    /** Optional name override for the `InspectGraph` itself. */
+    name?: string;
+}
+/**
+ * Graph subclass returned by {@link inspect}. Mounts a `graphLens` view (as
+ * a child `LensSubgraph`), an `auditTrail` (as a child subgraph), and
+ * exposes `explainTarget()` + `complianceSnapshot()` facades over the
+ * wrapped target.
+ *
+ * Mounted children (visible in `describe()`):
+ *   - `lens::topology` / `lens::health` / `lens::flow` — `graphLens(target)` Nodes.
+ *   - `audit::*` — the mounted {@link AuditTrailGraph}.
+ *
+ * @category observability
+ */
+declare class InspectGraph extends Graph {
+    readonly target: Graph;
+    /**
+     * 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.
+     */
+    readonly lens: GraphLensView;
+    /** Mounted audit trail subgraph. */
+    readonly audit: AuditTrailGraph;
+    private readonly _defaultActor?;
+    private readonly _lensSubgraph;
+    constructor(target: Graph, opts?: InspectOptions);
+    /**
+     * Causal-chain facade over `target.describe({ explain: {...} })`. Supports
+     * both static (one-shot {@link CausalChain}) and reactive
+     * (`{ reactive: true }`) forms.
+     *
+     * Named `explainTarget` (not folded into a `describe` mode on this class)
+     * because `inspect.describe(...)` walks `InspectGraph`'s OWN topology
+     * (lens + audit subgraphs) rather than the wrapped target's. Use
+     * `inspect.explainTarget(...)` for chains across the wrapped graph;
+     * `inspect.describe({ explain: {...} })` for chains across the lens /
+     * audit composition.
+     */
+    explainTarget(from: string | Node<string>, to: string | Node<string>, opts?: {
+        maxDepth?: number | Node<number>;
+        findCycle?: boolean | Node<boolean>;
+    }): CausalChain;
+    explainTarget(from: string | Node<string>, to: string | Node<string>, opts: {
+        reactive: true;
+        maxDepth?: number | Node<number>;
+        findCycle?: boolean | Node<boolean>;
+        name?: string;
+    }): {
+        node: Node<CausalChain>;
+        dispose: () => void;
+    };
+    /**
+     * 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?: {
+        actor?: Actor;
+        policies?: PolicyGateGraph;
+    }): ComplianceSnapshotResult;
+}
+/**
+ * Build an {@link InspectGraph} that mounts `graphLens` + `auditTrail` over
+ * the wrapped target and exposes `explainTarget()` + `complianceSnapshot()`
+ * facades.
+ *
+ * @example
+ * ```ts
+ * import { inspect } from "@graphrefly/graphrefly/patterns/inspect";
+ *
+ * const target = buildMyApp();
+ * const view = inspect(target, { actor: { id: "ops-bot", role: "monitor" } });
+ *
+ * // Live observability
+ * view.lens.health.subscribe((msgs) => console.log("health:", msgs));
+ * view.lens.flow.subscribe((msgs) => console.log("flow:", msgs));
+ *
+ * // Causal explainability across the wrapped target
+ * const chain = view.explainTarget("input", "output");
+ *
+ * // Tamper-evident snapshot for archival
+ * const snapshot = view.complianceSnapshot();
+ * ```
+ *
+ * @category observability
+ */
+declare function inspect(target: Graph, opts?: InspectOptions): InspectGraph;
+
+export { InspectGraph, type InspectOptions, inspect };

package/dist/presets/inspect/index.js

@@ -0,0 +1,21 @@
+import {
+  InspectGraph,
+  inspect
+} from "../../chunk-Z6EGP5D7.js";
+import {
+  GuardedExecutionGraph,
+  guardedExecution
+} from "../../chunk-JGFRAFDL.js";
+import "../../chunk-4XCHZRUJ.js";
+import "../../chunk-FW23JYNQ.js";
+import "../../chunk-Q3EYOCZB.js";
+import "../../chunk-FMPF42Q4.js";
+import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  GuardedExecutionGraph,
+  InspectGraph,
+  guardedExecution,
+  inspect
+};
+//# sourceMappingURL=index.js.map

package/dist/presets/inspect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}