@graphrefly/graphrefly 0.40.0 → 0.42.0

package/dist/index-CPNSy-U0.d.cts

@@ -0,0 +1,760 @@
+import { A as Actor, N as Node, W as PolicyRuleData, o as GuardAction } from './node-ClS5yC-B.cjs';
+import { G as Graph, a as GraphOptions, r as GraphPersistSnapshot, b as GraphDescribeOutput, j as GraphDescribeOptions, C as CausalChain, e as DescribeFilter } from './graph-C4SHb3Ly.cjs';
+import { T as TopicGraph } from './index-BTQtTb_H.cjs';
+import { w as watchTopologyTree } from './topology-tree-BSdfSwMi.cjs';
+
+/**
+ * Audit, policy enforcement, and compliance export (roadmap §9.2).
+ *
+ * Three composed factories that wrap any {@link Graph} with the harness
+ * accountability layer:
+ *
+ * - {@link auditTrail} — reactive mutation log with by-node/by-actor/by-time
+ *   queries.
+ * - {@link policyGate} — reactive ABAC gate (Tier 2.3 rename of
+ *   `policyEnforcer`); in `"audit"` mode records would-be denials, in
+ *   `"enforce"` mode pushes guards onto target nodes so subsequent writes
+ *   throw {@link GuardDenied}.
+ * - {@link complianceSnapshot} — point-in-time export of graph state +
+ *   audit trail + policies for regulatory archival.
+ *
+ * @module
+ */
+
+/** A single recorded mutation/event in an {@link AuditTrailGraph}. */
+interface AuditEntry {
+    seq: number;
+    timestamp_ns: number;
+    wall_clock_ns: number;
+    path: string;
+    type: "data" | "dirty" | "resolved" | "invalidate" | "pause" | "resume" | "complete" | "error" | "teardown";
+    actor?: Actor;
+    value?: unknown;
+    error?: unknown;
+    annotation?: string;
+}
+/** Options for {@link auditTrail}. */
+interface AuditTrailOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /** Ring-buffer cap for the underlying `reactiveLog`. Default: unbounded. */
+    maxSize?: number;
+    /**
+     * Which event types to record. Default: `["data", "error", "complete",
+     * "teardown"]` — the user-meaningful set. Opt in to mid-wave protocol
+     * events (`"dirty"`, `"resolved"`, `"invalidate"`, `"pause"`, `"resume"`)
+     * by listing them explicitly. Note: those tier-1/tier-2 events do not
+     * carry an `actor` (no `lastMutation` populated) — record them only for
+     * protocol-level diagnostics.
+     */
+    includeTypes?: readonly AuditEntry["type"][];
+    /** Per-event filter; return false to skip. */
+    filter?: (entry: AuditEntry) => boolean;
+}
+/**
+ * Mounted audit log — `entries` exposes the reactive `AuditEntry[]`; query
+ * helpers are sync convenience wrappers over the cached snapshot.
+ */
+declare class AuditTrailGraph extends Graph {
+    readonly entries: Node<readonly AuditEntry[]>;
+    readonly count: Node<number>;
+    private readonly _log;
+    private readonly _target;
+    constructor(target: Graph, opts: AuditTrailOptions);
+    /** All entries currently in the ring (snapshot). */
+    all(): readonly AuditEntry[];
+    /** Entries matching `path`. Order preserved. */
+    byNode(path: string): readonly AuditEntry[];
+    /** Entries whose `actor.id` matches. Use `byActorType` for type filtering. */
+    byActor(actorId: string): readonly AuditEntry[];
+    /** Entries whose `actor.type` matches (e.g. `"llm"`, `"human"`). */
+    byActorType(type: string): readonly AuditEntry[];
+    /**
+     * Entries with `timestamp_ns` in `[start_ns, end_ns)` (end exclusive).
+     * Omit `end_ns` to query open-ended.
+     */
+    byTimeRange(start_ns: number, end_ns?: number): readonly AuditEntry[];
+    /** Reference to the audited graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wraps any {@link Graph} with a reactive audit trail recording every event
+ * matching `includeTypes` (default: data + error + complete + teardown).
+ *
+ * Each entry carries `seq`, `timestamp_ns` (monotonic), `wall_clock_ns`,
+ * `path`, `type`, and — when available — `actor`, `value`, `error`, and the
+ * `graph.trace()` reasoning annotation for the path.
+ *
+ * The returned graph mounts an `entries` node + `count` derived. Query
+ * helpers (`byNode`, `byActor`, `byTimeRange`) operate on the cached
+ * snapshot synchronously.
+ */
+declare function auditTrail(target: Graph, opts?: AuditTrailOptions): AuditTrailGraph;
+/** A single policy denial recorded by {@link PolicyGateGraph}. */
+interface PolicyViolation {
+    timestamp_ns: number;
+    wall_clock_ns: number;
+    path: string;
+    actor: Actor;
+    action: GuardAction;
+    mode: "audit" | "enforce";
+    /** `"observed"` (audit mode after-the-fact) or `"blocked"` (enforce mode pre-write). */
+    result: "observed" | "blocked";
+}
+/** Options for {@link policyGate}. */
+interface PolicyGateOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /**
+     * `"audit"` (default) — observe events and record would-be denials;
+     * does not block writes. Audit mode requires `lastMutation` attribution
+     * on the audited node — anonymous/internal writes (no `actor` passed,
+     * unguarded node) are skipped silently because the policy cannot be
+     * evaluated without an actor.
+     *
+     * `"enforce"` — push guards onto target nodes so disallowed writes
+     * throw {@link GuardDenied}. Reverted on dispose.
+     */
+    mode?: "audit" | "enforce";
+    /**
+     * Restrict enforcement to specific node paths (qualified). When omitted,
+     * applies to every node visible in `target.describe()` at construction
+     * time (subgraphs are walked transitively) AND subscribes to the full
+     * topology tree via {@link watchTopologyTree}, so nodes added to
+     * `target` OR any transitively-mounted subgraph after construction are
+     * guarded automatically (enforce mode only).
+     *
+     * Accepts a static `readonly string[]` or a reactive
+     * `Node<readonly string[]>` (Tier 3.4 — F.9 reactive primitive carve-out).
+     * When a `Node` is passed, the enforcer rebinds the guarded path set on
+     * every emission: paths added to the new set get wrapped, paths removed
+     * from the new set get released, and the audit-mode allow-list filter
+     * uses the latest cached value. Static-array callers retain the current
+     * "caller owns the path set" semantics.
+     *
+     * **Cost:** unrestricted mode runs `describe({detail:"minimal"})` once
+     * at construction (O(N) over the graph tree) plus one topology
+     * subscription per graph instance in the mount tree. Restricted mode
+     * (static or reactive) skips both and disables `watchTopologyTree`
+     * dynamic coverage — for reactive callers, the path-set Node is the
+     * single source of truth for which paths are guarded.
+     */
+    paths?: readonly string[] | Node<readonly string[]>;
+    /**
+     * Ring-buffer cap for the violations topic. Default: 1000. Static
+     * number only — reactive form is deferred pending TopicGraph reactive
+     * `retainedLimit` support (see Tier 10.8 design follow-up in
+     * `docs/optimizations.md`).
+     */
+    violationsLimit?: number;
+}
+/**
+ * Reactive ABAC enforcement layer. Policies are reactive — pass a
+ * `Node<readonly PolicyRuleData[]>` to allow LLMs (or any reactive source)
+ * to update them at runtime; the enforcer rebinds its internal
+ * {@link NodeGuard} on every push.
+ */
+declare class PolicyGateGraph extends Graph {
+    readonly policies: Node<readonly PolicyRuleData[]>;
+    readonly violations: TopicGraph<PolicyViolation>;
+    readonly violationCount: Node<number>;
+    private readonly _target;
+    private readonly _mode;
+    private _currentGuard;
+    constructor(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts: PolicyGateOptions);
+    private _publishViolation;
+    /** Snapshot of recorded violations. */
+    all(): readonly PolicyViolation[];
+    get mode(): "audit" | "enforce";
+    get target(): Graph;
+}
+/**
+ * Wraps a {@link Graph} with reactive policy enforcement. Pass either a
+ * static rule list or a {@link Node} of rules (LLM-updatable). Records
+ * `PolicyViolation` entries to `violations` topic; in `"enforce"` mode also
+ * pushes guards onto target nodes so disallowed writes throw.
+ *
+ * Self-tags via `g.tagFactory("policyGate", placeholderArgs(opts))` so
+ * `graph.describe()` surfaces `factory: "policyGate"` provenance (Phase 2.5
+ * DT5 ride-along, locked with the Tier 2.3 rename).
+ */
+declare function policyGate(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts?: PolicyGateOptions): PolicyGateGraph;
+/** Options for {@link complianceSnapshot}. */
+interface ComplianceSnapshotOptions {
+    audit?: AuditTrailGraph;
+    policies?: PolicyGateGraph;
+    /** Actor recorded as the snapshot taker. */
+    actor?: Actor;
+}
+/** Output of {@link complianceSnapshot}. JSON-serializable. */
+interface ComplianceSnapshotResult {
+    format_version: 1;
+    timestamp_ns: number;
+    wall_clock_ns: number;
+    actor?: Actor;
+    graph: GraphPersistSnapshot;
+    audit?: {
+        count: number;
+        entries: AuditEntry[];
+    };
+    policies?: {
+        mode: "audit" | "enforce";
+        rules: readonly PolicyRuleData[];
+        violations: readonly PolicyViolation[];
+    };
+    /**
+     * Truncated SHA-256 hex (16 chars / ~64 bits) over a canonical encoding
+     * of every field above (excluding `fingerprint` itself). Deterministic
+     * across runs given identical inputs. Suitable for casual tamper-evidence
+     * and content-addressed dedup; for full cryptographic strength, hash the
+     * canonical JSON externally with Web Crypto / Node `crypto`.
+     */
+    fingerprint: string;
+}
+/**
+ * One-shot point-in-time export of a {@link Graph}'s state plus optional
+ * audit + policy bundles. Returns a JSON-serializable object with a
+ * deterministic truncated-SHA-256 {@link ComplianceSnapshotResult.fingerprint}
+ * over the canonical payload for tamper-evidence in regulatory archival.
+ *
+ * **Cryptographic strength:** the fingerprint is truncated to 64 bits for
+ * compact archival. Collision-resistant for casual integrity checks but NOT
+ * sufficient for adversarial tamper-evidence — pair with a full SHA-256
+ * (or stronger) over the canonical JSON when regulatory requirements demand
+ * collision resistance.
+ */
+declare function complianceSnapshot(target: Graph, opts?: ComplianceSnapshotOptions): ComplianceSnapshotResult;
+
+/**
+ * Composable safety layer (roadmap §9.0b — Tier 5.1 Wave-B rebuild).
+ *
+ * {@link guardedExecution} wraps any {@link Graph} with:
+ *
+ * - {@link policyGate} — reactive ABAC (Tier 2.3 rename of `policyEnforcer`),
+ *   policies stored as a `Node` so LLMs / humans can update them at runtime.
+ *   Full transitive dynamic coverage via `watchTopologyTree`.
+ * - Reactive {@link GuardedExecutionGraph.scopedDescribeNode} — a thin
+ *   delegate over `target.describe({ reactive: true, actor })` that re-derives
+ *   on every settle (topology change, error transition, actor swap).
+ * - The enforcer's `violations` topic is republished as `violations` on
+ *   the wrapper, composable with {@link graphLens}'s `health`.
+ * - The wrapper-level `lints` topic surfaces non-policy diagnostic warnings
+ *   (`empty-policies` / `audit-no-effect` / `no-actor`) so misconfigurations
+ *   are caught reactively rather than via thrown errors at scattered call sites.
+ * - The `scope` derived publishes the current configuration tuple
+ *   (`{actor, mode, policiesCount}`) for dashboards.
+ *
+ * V1 scope: policies + actor + reactive scoped describe + lints + scope.
+ * Budget-as-option is NOT in V1 — it requires a cost-tracking design that
+ * hasn't landed yet. Callers who need a budget limit today append a
+ * budget-aware {@link PolicyRuleData} to the policies list (check current
+ * cost and `deny` when exhausted).
+ *
+ * @module
+ */
+
+/** Diagnostic warning published on {@link GuardedExecutionGraph.lints}. */
+interface GuardedExecutionLint {
+    /**
+     * - `"empty-policies"` — `policies` Node emitted an empty array in
+     *   `mode: "enforce"`. Static empty arrays throw at construction; this
+     *   covers the reactive case.
+     * - `"audit-no-effect"` — `mode: "audit"` plus the target has no per-node
+     *   guards, so `scopedDescribeNode` filters by per-node guards only and
+     *   policies will never gate visibility (they still populate `violations`
+     *   on writes).
+     * - `"no-actor"` — neither a wrapper-configured nor per-call actor was
+     *   supplied. `scopedDescribeNode` falls back to "describe everything"
+     *   for the corresponding subscription.
+     */
+    kind: "empty-policies" | "audit-no-effect" | "no-actor";
+    message: string;
+    timestamp_ns: number;
+}
+/** Configuration tuple published on {@link GuardedExecutionGraph.scope}. */
+interface GuardedScope {
+    /** The wrapper-configured default actor, or `null` when none configured. */
+    actor: Actor | null;
+    mode: "audit" | "enforce";
+    /** Current policy count (reactive — re-emits on `policies` Node updates). */
+    policiesCount: number;
+}
+/** Options for {@link guardedExecution}. */
+interface GuardedExecutionOptions {
+    /**
+     * Policies enforced against every guarded write. Static list or a live
+     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
+     *
+     * **Empty-policies handling:**
+     * - Static empty array + `mode: "enforce"` throws `RangeError` at
+     *   construction (deny-by-default is almost certainly a misconfiguration).
+     * - Node-supplied empty array + `mode: "enforce"` emits a one-time
+     *   `"empty-policies"` lint on first such emission (the wrapper can't
+     *   throw mid-run — surface the warning reactively).
+     * - `mode: "audit"` tolerates empty policies (no guards stacked; policies
+     *   only feed the `violations` channel on writes).
+     */
+    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
+    /**
+     * Default actor used when the caller invokes
+     * {@link GuardedExecutionGraph.scopedDescribeNode} without an override.
+     * Accepts a static {@link Actor} or a `Node<Actor>` — when a Node is
+     * supplied, the reactive describe re-derives on every actor emission so
+     * harnesses binding a per-turn actor get a single live describe Node
+     * instead of re-creating one per turn.
+     *
+     * Omit to scope per-call only. A `"no-actor"` lint fires once per instance
+     * if neither a configured nor per-call actor is ever supplied (the
+     * resulting describe is unscoped — full visibility).
+     */
+    actor?: Actor | Node<Actor>;
+    /**
+     * `"enforce"` (default) — push guards onto target nodes so disallowed
+     * writes throw {@link GuardDenied}.
+     * `"audit"` — record would-be denials to the `violations` topic without
+     * blocking writes.
+     */
+    mode?: "audit" | "enforce";
+    /** Ring-buffer cap for the `violations` topic. Default 1000 (inherited from policyGate). */
+    violationsLimit?: number;
+    /** Ring-buffer cap for the `lints` topic. Default 64 — each lint kind fires at most once per instance. */
+    lintsLimit?: number;
+    /** Wrapper graph name. Default `${target.name}_guarded`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Wrapper over a target {@link Graph} providing reactive ABAC + reactive
+ * scoped describe + diagnostic lints. Mounts a {@link PolicyGateGraph} under
+ * `enforcer`, a {@link TopicGraph} of {@link GuardedExecutionLint} under
+ * `lints`, and a `scope` derived publishing `{actor, mode, policiesCount}`.
+ *
+ * @category patterns
+ */
+declare class GuardedExecutionGraph extends Graph {
+    readonly enforcer: PolicyGateGraph;
+    readonly violations: TopicGraph<PolicyViolation>;
+    readonly lints: TopicGraph<GuardedExecutionLint>;
+    readonly scope: Node<GuardedScope>;
+    /**
+     * 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).
+     */
+    readonly scopedDescribe: Node<GraphDescribeOutput>;
+    private readonly _target;
+    private readonly _actorNode;
+    private readonly _mode;
+    private readonly _firedLintKinds;
+    constructor(target: Graph, opts: GuardedExecutionOptions);
+    private _fireLint;
+    /**
+     * **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?: Actor | Node<Actor>, opts?: Omit<GraphDescribeOptions, "actor" | "reactive" | "reactiveName">): {
+        node: Node<GraphDescribeOutput>;
+        dispose: () => void;
+    };
+    /** The wrapped graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wrap a {@link Graph} with {@link policyGate} plus a reactive scoped describe
+ * lens. Returns a {@link GuardedExecutionGraph} that can be mounted, diffed,
+ * or composed with {@link graphLens}.
+ *
+ * @param target - The graph to guard.
+ * @param opts - See {@link GuardedExecutionOptions}.
+ *
+ * @example
+ * ```ts
+ * const guarded = guardedExecution(app, {
+ *   actor: state<Actor>({ type: "human", id: "alice" }), // reactive — re-derive on swap
+ *   policies: [
+ *     { effect: "allow", action: "read", actorType: "human" },
+ *     { effect: "deny", action: "write", pathPattern: "system::*" },
+ *   ],
+ *   mode: "enforce",
+ * });
+ *
+ * // Canonical: subscribe to the mounted reactive describe (no per-call leak).
+ * guarded.scopedDescribe.subscribe((msgs) => { /* live describe per actor / topology change *\/ });
+ * // Per-call escape hatch (different actor / detail) — caller manages dispose.
+ * const detailed = guarded.scopedDescribeNode(undefined, { detail: "standard" });
+ * try { detailed.node.subscribe(/* … *\/); } finally { detailed.dispose(); }
+ * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
+ * guarded.lints.events.subscribe(msgs => console.warn("lints:", msgs));
+ * guarded.scope.subscribe(msgs => console.log("scope:", msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
+
+/**
+ * Reactive graph observability preset (Tier 5.3 reshape — Session A.4 lock).
+ *
+ * `graphLens(target)` is a thin compositor (~30 LOC of glue) over two
+ * already-shipped reactive primitives:
+ *
+ * - `target.describe({ reactive: true })` — live topology snapshot.
+ * - `target.observe({ reactive: true, tiers: ["data"] })` — coalesced data
+ *   changesets per outermost batch flush.
+ *
+ * It returns three Nodes plus a dispose function:
+ *
+ * - `topology: Node<GraphDescribeOutput>` — the live describe snapshot,
+ *   re-emitting on every settle of the target tree (structural change,
+ *   error/complete/teardown transition).
+ * - `health: Node<HealthReport>` — `{ok, problems[]}` aggregated from the
+ *   live describe; `ok=false` when any node enters `"errored"` status,
+ *   with `upstreamCause` walked backward through deps.
+ * - `flow: Node<ReadonlyMap<string, FlowEntry>>` — per-path DATA counters
+ *   accumulating as `target.observe({reactive: true, tiers: ["data"]})`
+ *   delivers changesets. The map is reconciled against `topology` on each
+ *   topology change so removed nodes drop their entries.
+ *
+ * Pre-Tier-5.3 shipped a `LensGraph` class with `stats` / `health` / `flow`
+ * (as a `ReactiveMapBundle`) / `why(from, to)` / `flowEntryNode(...)`. The
+ * surface collapsed because every concern was already a one-liner over
+ * `describe({reactive:true})` + `observe({reactive:true, tiers})` once those
+ * landed in Tier 1.5.1 / 1.5.2 — the class added no protocol-level concept,
+ * just glue. Callers who need topology stats compose a derived over
+ * `topology` directly; callers who need a causal chain call
+ * `target.explain(from, to, { reactive: true })`.
+ *
+ * The transitive topology-subscription helper {@link watchTopologyTree} is
+ * re-exported here for downstream factories that need full-tree dynamic
+ * coverage without taking a dep on `graph/`.
+ *
+ * @module
+ */
+
+/** A single health problem entry. */
+interface HealthProblem {
+    path: string;
+    /** V1 only reports `"errored"`. Future versions may add `"completed"`, `"disconnected"`. */
+    status: "errored";
+    /** First errored upstream ancestor along the dep chain, when one exists and is distinct from `path`. */
+    upstreamCause?: string;
+}
+/** Aggregate health snapshot. `ok=true` iff `problems.length === 0`. */
+interface HealthReport {
+    ok: boolean;
+    problems: readonly HealthProblem[];
+}
+/** Per-path flow entry stored in the {@link GraphLensView.flow} map. */
+interface FlowEntry {
+    path: string;
+    /** Cumulative DATA emissions observed since the lens activated. */
+    count: number;
+    /** Monotonic ns at the most recent DATA emission for this path, or `null` if none yet. */
+    lastUpdate_ns: number | null;
+}
+/** Output of {@link graphLens}. */
+interface GraphLensView {
+    /** Live describe snapshot. Re-emits on structural change AND status transitions. */
+    topology: Node<GraphDescribeOutput>;
+    /** Live `{ok, problems[]}`. Aggregated from `topology`; equality-deduped. */
+    health: Node<HealthReport>;
+    /** Per-path DATA counter map. Re-emits per outermost batch flush. */
+    flow: Node<ReadonlyMap<string, FlowEntry>>;
+    /**
+     * Tear down the underlying `describe({reactive:true})` subscription.
+     * The `flow` node activates lazily; subscribing-then-unsubscribing reclaims
+     * its observe stream automatically. Call `dispose()` once when finished.
+     */
+    dispose(): void;
+}
+/** Build a `HealthReport` from a fresh `GraphDescribeOutput`. */
+declare function computeHealthReport(described: GraphDescribeOutput): HealthReport;
+/** Structural equality for {@link HealthReport} — used as the `health` derived's `equals`. */
+declare function healthReportEqual(a: HealthReport, b: HealthReport): boolean;
+/**
+ * Reactive observability preset over a target {@link Graph}.
+ *
+ * @param target - The graph to observe.
+ *
+ * @example
+ * ```ts
+ * const g = new Graph("app");
+ * g.add(state(0, { name: "counter" }), { name: "counter" });
+ *
+ * const lens = graphLens(g);
+ * lens.topology.subscribe((msgs) => console.log("topology:", msgs));
+ * lens.health.subscribe((msgs) => console.log("health:", msgs));
+ * lens.flow.subscribe((msgs) => {
+ *   for (const [type, payload] of msgs) {
+ *     if (type === DATA) console.log("flow map size:", (payload as ReadonlyMap<string, FlowEntry>).size);
+ *   }
+ * });
+ *
+ * // Causal chains: use the underlying primitive directly — `graphLens` no
+ * // longer wraps it, since `graph.explain({ reactive: true })` already
+ * // provides everything the old `lens.why()` did.
+ * const why = g.explain("counter", "consumer", { reactive: true });
+ *
+ * // Tear down when done.
+ * lens.dispose();
+ * ```
+ *
+ * @category observability
+ */
+declare function graphLens(target: Graph): GraphLensView;
+
+/**
+ * `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.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.explain(...)`. Supports both static
+     * (one-shot {@link CausalChain}) and reactive (`{ reactive: true }`)
+     * forms — overload signatures mirror {@link Graph.explain}.
+     *
+     * Named `explainTarget` (not `explain`) to avoid shadowing the
+     * inherited {@link Graph.explain} method, which walks `InspectGraph`'s
+     * OWN topology (lens + audit subgraphs) rather than the wrapped
+     * target's. Use `inspect.explainTarget(...)` for chains across the
+     * wrapped graph; `inspect.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;
+
+/**
+ * Inspect — graph observability primitives + presets (Tier 9.1 γ-form γ-ii merge).
+ *
+ * Merges the former `patterns/audit/`, `patterns/lens/`, and
+ * `patterns/guarded-execution/` folders into a single domain. Sub-files
+ * preserve the legacy folder boundaries for clarity, then export through this
+ * barrel.
+ *
+ * Building blocks (this barrel + sub-files):
+ *  - `auditTrail` / `policyGate` / `complianceSnapshot` / `explainPath` —
+ *    audit + policy + causal explainability primitives.
+ *  - `graphLens` / `computeHealthReport` / `healthReportEqual` /
+ *    `watchTopologyTree` — topology-driven health and flow views.
+ *  - `guardedExecution` / `GuardedExecutionGraph` — actor-scoped wrapper
+ *    that enforces / audits guards on a target graph.
+ *
+ * Presets (`./presets/inspect.ts`):
+ *  - `inspect()` — `lens + auditTrail + explain (facade) + complianceSnapshot()`
+ *    composition (Tier 9.1 γ-form Q5-6 medium scope). Mounts `graphLens`
+ *    internally rather than rebuilding `health` / `flow`.
+ *
+ * @module
+ */
+
+type index_AuditEntry = AuditEntry;
+type index_AuditTrailGraph = AuditTrailGraph;
+declare const index_AuditTrailGraph: typeof AuditTrailGraph;
+type index_AuditTrailOptions = AuditTrailOptions;
+type index_ComplianceSnapshotOptions = ComplianceSnapshotOptions;
+type index_ComplianceSnapshotResult = ComplianceSnapshotResult;
+declare const index_DescribeFilter: typeof DescribeFilter;
+type index_FlowEntry = FlowEntry;
+type index_GraphLensView = GraphLensView;
+type index_GuardedExecutionGraph = GuardedExecutionGraph;
+declare const index_GuardedExecutionGraph: typeof GuardedExecutionGraph;
+type index_GuardedExecutionLint = GuardedExecutionLint;
+type index_GuardedExecutionOptions = GuardedExecutionOptions;
+type index_GuardedScope = GuardedScope;
+type index_HealthProblem = HealthProblem;
+type index_HealthReport = HealthReport;
+type index_InspectGraph = InspectGraph;
+declare const index_InspectGraph: typeof InspectGraph;
+type index_InspectOptions = InspectOptions;
+type index_PolicyGateGraph = PolicyGateGraph;
+declare const index_PolicyGateGraph: typeof PolicyGateGraph;
+type index_PolicyGateOptions = PolicyGateOptions;
+type index_PolicyViolation = PolicyViolation;
+declare const index_auditTrail: typeof auditTrail;
+declare const index_complianceSnapshot: typeof complianceSnapshot;
+declare const index_computeHealthReport: typeof computeHealthReport;
+declare const index_graphLens: typeof graphLens;
+declare const index_guardedExecution: typeof guardedExecution;
+declare const index_healthReportEqual: typeof healthReportEqual;
+declare const index_inspect: typeof inspect;
+declare const index_policyGate: typeof policyGate;
+declare const index_watchTopologyTree: typeof watchTopologyTree;
+declare namespace index {
+  export { type index_AuditEntry as AuditEntry, index_AuditTrailGraph as AuditTrailGraph, type index_AuditTrailOptions as AuditTrailOptions, type index_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type index_ComplianceSnapshotResult as ComplianceSnapshotResult, index_DescribeFilter as DescribeFilter, type index_FlowEntry as FlowEntry, type index_GraphLensView as GraphLensView, index_GuardedExecutionGraph as GuardedExecutionGraph, type index_GuardedExecutionLint as GuardedExecutionLint, type index_GuardedExecutionOptions as GuardedExecutionOptions, type index_GuardedScope as GuardedScope, type index_HealthProblem as HealthProblem, type index_HealthReport as HealthReport, index_InspectGraph as InspectGraph, type index_InspectOptions as InspectOptions, index_PolicyGateGraph as PolicyGateGraph, type index_PolicyGateOptions as PolicyGateOptions, type index_PolicyViolation as PolicyViolation, index_auditTrail as auditTrail, index_complianceSnapshot as complianceSnapshot, index_computeHealthReport as computeHealthReport, index_graphLens as graphLens, index_guardedExecution as guardedExecution, index_healthReportEqual as healthReportEqual, index_inspect as inspect, index_policyGate as policyGate, index_watchTopologyTree as watchTopologyTree };
+}
+
+export { type AuditEntry as A, type ComplianceSnapshotOptions as C, type FlowEntry as F, type GraphLensView as G, type HealthProblem as H, InspectGraph as I, PolicyGateGraph as P, AuditTrailGraph as a, type AuditTrailOptions as b, type ComplianceSnapshotResult as c, GuardedExecutionGraph as d, type GuardedExecutionLint as e, type GuardedExecutionOptions as f, type GuardedScope as g, type HealthReport as h, index as i, type InspectOptions as j, type PolicyGateOptions as k, type PolicyViolation as l, auditTrail as m, complianceSnapshot as n, computeHealthReport as o, graphLens as p, guardedExecution as q, healthReportEqual as r, inspect as s, policyGate as t };