@graphrefly/graphrefly 0.27.0 → 0.28.0

package/dist/index-BxJ86YZZ.d.cts

@@ -0,0 +1,105 @@
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { S as StatusValue, C as CircuitState, R as RateLimiterOptions, a as CircuitBreakerOptions, b as RetryOptions, F as FallbackInput, N as NS_PER_MS, c as NS_PER_SEC } from './resilience-Ba5-b4WD.cjs';
+import { B as BudgetConstraint } from './index-rHJSKsU8.cjs';
+
+/**
+ * Resilience composition with correct nesting order (roadmap §9.0b).
+ *
+ * {@link resilientPipeline} composes the resilience primitives from
+ * `extra/resilience.ts` in the order discovered during the §9.1 eval runs:
+ *
+ * ```text
+ *   rateLimit → budget → breaker → timeout → retry → fallback → status
+ * ```
+ *
+ * Note on retry/timeout ordering: `timeout` is applied BEFORE `retry` so each
+ * retry attempt resubscribes to a fresh deadline (per-attempt semantics). If
+ * `timeout` wrapped `retry`, a single deadline would apply to the entire
+ * retry chain — not what callers expect.
+ *
+ * Every step is optional — omit the option and that layer is skipped. The
+ * returned bundle exposes the final `Node<T>` plus the status/error/breaker
+ * companions so callers can wire them into dashboards, alerts, or
+ * {@link graphLens}.
+ *
+ * Subsumes the pre-1.0 `resilientFetch` template — that template becomes a
+ * preconfigured instance of this factory for the HTTP fetch case.
+ *
+ * @module
+ */
+
+/** Options for {@link resilientPipeline}. Every field is optional — omit to skip that layer. */
+interface ResilientPipelineOptions<T> {
+    /** Admission control — at most `maxEvents` DATA per `windowNs`. See {@link rateLimiter}. */
+    rateLimit?: RateLimiterOptions;
+    /** Cost/constraint gate. See {@link budgetGate}. */
+    budget?: ReadonlyArray<BudgetConstraint>;
+    /** Circuit breaker — fail-fast when the downstream resource is unhealthy. See {@link circuitBreaker}. */
+    breaker?: CircuitBreakerOptions;
+    /**
+     * Behavior when the breaker is open:
+     * - `"skip"` — emit RESOLVED (default, lets downstream drop the beat)
+     * - `"error"` — emit a `CircuitOpenError` so `retry`/`fallback` can react
+     *
+     * Only used when `breaker` is provided.
+     */
+    breakerOnOpen?: "skip" | "error";
+    /** Retry policy on terminal ERROR. See {@link retry}. */
+    retry?: RetryOptions;
+    /**
+     * Per-attempt deadline in milliseconds. Converted to ns internally. Omit to skip the timeout wrap.
+     *
+     * Specified in ms (not ns) because callers consistently think in millisecond deadlines;
+     * retry/breaker/ratelimit options take ns to match their primitives exactly.
+     */
+    timeoutMs?: number;
+    /** Final fallback value emitted on terminal ERROR after retry exhausts. See {@link fallback}. */
+    fallback?: FallbackInput<T>;
+    /** Initial status reported by the status node. Default `"pending"`. */
+    initialStatus?: StatusValue;
+}
+/** Output bundle of {@link resilientPipeline}. */
+interface ResilientPipelineBundle<T> {
+    /** The final resilient node. Subscribe to this for DATA emissions. */
+    node: Node<T>;
+    /** Live status: `"pending" | "active" | "completed" | "errored"`. */
+    status: Node<StatusValue>;
+    /** Last error payload, or `null` when not errored. */
+    error: Node<unknown | null>;
+    /** Breaker state when `opts.breaker` was provided; `undefined` otherwise. */
+    breakerState: Node<CircuitState> | undefined;
+}
+/**
+ * Compose a resilient pipeline around `source` in the canonical nesting
+ * order — `rateLimit → budget → breaker → timeout → retry → fallback → status`.
+ * Omit any option to skip that layer.
+ *
+ * @param source - Upstream node to wrap.
+ * @param opts - See {@link ResilientPipelineOptions}. All fields optional.
+ *
+ * @example
+ * ```ts
+ * const safeFetch = resilientPipeline(fetchNode, {
+ *   rateLimit: { maxEvents: 10, windowNs: NS_PER_SEC },
+ *   breaker: { failureThreshold: 5 },
+ *   retry: { count: 3, backoff: "exponential" },
+ *   timeoutMs: 10_000,
+ *   fallback: null,
+ * });
+ * safeFetch.status.subscribe(msgs => console.log(msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function resilientPipeline<T>(source: Node<T>, opts?: ResilientPipelineOptions<T>): ResilientPipelineBundle<T>;
+
+declare const index_NS_PER_MS: typeof NS_PER_MS;
+declare const index_NS_PER_SEC: typeof NS_PER_SEC;
+type index_ResilientPipelineBundle<T> = ResilientPipelineBundle<T>;
+type index_ResilientPipelineOptions<T> = ResilientPipelineOptions<T>;
+declare const index_resilientPipeline: typeof resilientPipeline;
+declare namespace index {
+  export { index_NS_PER_MS as NS_PER_MS, index_NS_PER_SEC as NS_PER_SEC, type index_ResilientPipelineBundle as ResilientPipelineBundle, type index_ResilientPipelineOptions as ResilientPipelineOptions, index_resilientPipeline as resilientPipeline };
+}
+
+export { type ResilientPipelineBundle as R, type ResilientPipelineOptions as a, index as i, resilientPipeline as r };

package/dist/{audit-DRlSzBu9.d.ts → index-C73n7lo-.d.cts}

@@ -1,6 +1,6 @@
-import { A as Actor, N as Node, P as PolicyRuleData, k as GuardAction } from './node-BmerH3kS.js';
-import { a as Graph, G as GraphOptions, s as GraphPersistSnapshot, C as CausalChain } from './graph-CCwGKLCm.js';
-import { T as TopicGraph } from './messaging-XDoYablx.js';
+import { A as Actor, a as Node, P as PolicyRuleData, G as GuardAction } from './node-Cc1TniY8.cjs';
+import { G as Graph, a as GraphOptions, d as GraphPersistSnapshot, C as CausalChain } from './graph-D48Qw9Cg.cjs';
+import { T as TopicGraph } from './index-DyxjtScX.cjs';
 
 /**
  * Audit, policy enforcement, and compliance export (roadmap §9.2).
@@ -29,7 +29,7 @@ interface AuditEntry {
     actor?: Actor;
     value?: unknown;
     error?: unknown;
-    reason?: string;
+    annotation?: string;
 }
 /** Options for {@link auditTrail}. */
 interface AuditTrailOptions {
@@ -170,6 +170,12 @@ declare function policyEnforcer(target: Graph, policies: readonly PolicyRuleData
  * `data`, `error`, `complete`, and `teardown` bump the version (matching the
  * audit defaults).
  */
+/**
+ * @deprecated Use `graph.explain(from, to, { reactive: true, ... })` directly.
+ *   This free-function wrapper now dispatches to the consolidated
+ *   {@link Graph.explain} overload for mental-model consistency with
+ *   `describe` / `observe`. Will be removed pre-1.0.
+ */
 declare function reactiveExplainPath(target: Graph, from: string, to: string, opts?: {
     maxDepth?: number;
     name?: string;
@@ -224,22 +230,22 @@ interface ComplianceSnapshotResult {
  */
 declare function complianceSnapshot(target: Graph, opts?: ComplianceSnapshotOptions): ComplianceSnapshotResult;
 
-type audit_AuditEntry = AuditEntry;
-type audit_AuditTrailGraph = AuditTrailGraph;
-declare const audit_AuditTrailGraph: typeof AuditTrailGraph;
-type audit_AuditTrailOptions = AuditTrailOptions;
-type audit_ComplianceSnapshotOptions = ComplianceSnapshotOptions;
-type audit_ComplianceSnapshotResult = ComplianceSnapshotResult;
-type audit_PolicyEnforcerGraph = PolicyEnforcerGraph;
-declare const audit_PolicyEnforcerGraph: typeof PolicyEnforcerGraph;
-type audit_PolicyEnforcerOptions = PolicyEnforcerOptions;
-type audit_PolicyViolation = PolicyViolation;
-declare const audit_auditTrail: typeof auditTrail;
-declare const audit_complianceSnapshot: typeof complianceSnapshot;
-declare const audit_policyEnforcer: typeof policyEnforcer;
-declare const audit_reactiveExplainPath: typeof reactiveExplainPath;
-declare namespace audit {
-  export { type audit_AuditEntry as AuditEntry, audit_AuditTrailGraph as AuditTrailGraph, type audit_AuditTrailOptions as AuditTrailOptions, type audit_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type audit_ComplianceSnapshotResult as ComplianceSnapshotResult, audit_PolicyEnforcerGraph as PolicyEnforcerGraph, type audit_PolicyEnforcerOptions as PolicyEnforcerOptions, type audit_PolicyViolation as PolicyViolation, audit_auditTrail as auditTrail, audit_complianceSnapshot as complianceSnapshot, audit_policyEnforcer as policyEnforcer, audit_reactiveExplainPath as reactiveExplainPath };
+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;
+type index_PolicyEnforcerGraph = PolicyEnforcerGraph;
+declare const index_PolicyEnforcerGraph: typeof PolicyEnforcerGraph;
+type index_PolicyEnforcerOptions = PolicyEnforcerOptions;
+type index_PolicyViolation = PolicyViolation;
+declare const index_auditTrail: typeof auditTrail;
+declare const index_complianceSnapshot: typeof complianceSnapshot;
+declare const index_policyEnforcer: typeof policyEnforcer;
+declare const index_reactiveExplainPath: typeof reactiveExplainPath;
+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_PolicyEnforcerGraph as PolicyEnforcerGraph, type index_PolicyEnforcerOptions as PolicyEnforcerOptions, type index_PolicyViolation as PolicyViolation, index_auditTrail as auditTrail, index_complianceSnapshot as complianceSnapshot, index_policyEnforcer as policyEnforcer, index_reactiveExplainPath as reactiveExplainPath };
 }
 
-export { type AuditEntry as A, type ComplianceSnapshotOptions as C, PolicyEnforcerGraph as P, type PolicyViolation as a, audit as b, AuditTrailGraph as c, type AuditTrailOptions as d, type ComplianceSnapshotResult as e, type PolicyEnforcerOptions as f, auditTrail as g, complianceSnapshot as h, policyEnforcer as p, reactiveExplainPath as r };
+export { type AuditEntry as A, type ComplianceSnapshotOptions as C, PolicyEnforcerGraph as P, type PolicyViolation as a, AuditTrailGraph as b, type AuditTrailOptions as c, type ComplianceSnapshotResult as d, type PolicyEnforcerOptions as e, auditTrail as f, complianceSnapshot as g, index as i, policyEnforcer as p, reactiveExplainPath as r };

package/dist/index-CEXXwWVH.d.cts

@@ -0,0 +1,192 @@
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { a as GraphOptions, G as Graph } from './graph-D48Qw9Cg.cjs';
+
+/**
+ * CQRS patterns (roadmap §4.5).
+ *
+ * Composition layer over reactiveLog (3.2), pipeline/sagas (4.1), event bus (4.2),
+ * projections (4.3). Guards (1.5) enforce command/query boundary.
+ *
+ * - `cqrs(name, opts?)` → `CqrsGraph` — top-level factory
+ * - `CqrsGraph.command(name, handler)` — write-only node; guard rejects `observe`
+ * - `CqrsGraph.event(name)` — backed by `reactiveLog`; append-only
+ * - `CqrsGraph.projection(name, events, reducer, initial)` — read-only derived; guard rejects `write`
+ * - `CqrsGraph.saga(name, events, handler)` — event-driven side effects
+ */
+
+/**
+ * Immutable envelope for events emitted by command handlers.
+ *
+ * `seq` is a per-graph monotonic counter that provides stable ordering when
+ * multiple events share the same `timestampNs` (same wall-clock tick).
+ */
+type CqrsEvent<T = unknown> = {
+    type: string;
+    payload: T;
+    /** Wall-clock nanoseconds (via `wallClockNs()`). */
+    timestampNs: number;
+    /** Monotonic sequence within this CqrsGraph instance. */
+    seq: number;
+    /** V0 identity of the event log node at append time (§6.0b). */
+    v0?: {
+        id: string;
+        version: number;
+    };
+};
+/**
+ * Opaque replay cursor returned by `loadEvents`. Pass it back to
+ * `loadEvents` to resume from the last position.
+ */
+type EventStoreCursor = {
+    readonly __brand?: "EventStoreCursor";
+    [key: string]: unknown;
+};
+/**
+ * Result of `loadEvents` — events plus an opaque cursor for resumption.
+ */
+type LoadEventsResult = {
+    events: CqrsEvent[];
+    cursor: EventStoreCursor | undefined;
+};
+/**
+ * Pluggable persistence for CQRS events.
+ *
+ * **`persist`:** Must be synchronous. Called from the dispatch path inside
+ * `batch()`. Adapters that need async I/O should buffer internally and
+ * expose a `flush()` method for explicit drain.
+ */
+interface EventStoreAdapter {
+    persist(event: CqrsEvent): void;
+    /**
+     * Load persisted events. When `cursor` is provided, returns only events
+     * after that position. The returned `cursor` should be passed to the next
+     * `loadEvents` call for incremental replay.
+     */
+    loadEvents(eventType: string, cursor?: EventStoreCursor): LoadEventsResult | Promise<LoadEventsResult>;
+    /** Optional explicit flush for adapters with async I/O. */
+    flush?(): Promise<void>;
+}
+declare class MemoryEventStore implements EventStoreAdapter {
+    private readonly _store;
+    persist(event: CqrsEvent): void;
+    loadEvents(eventType: string, cursor?: EventStoreCursor): LoadEventsResult;
+    clear(): void;
+}
+type CommandActions = {
+    /** Append an event to a named event log (bypasses event guard). */
+    emit: (eventName: string, payload: unknown) => void;
+};
+/**
+ * Command handler receives the dispatch payload and actions to emit events.
+ *
+ * **Purity:** Handlers should not mutate the payload. Event emission via
+ * `actions.emit()` is the only sanctioned side effect.
+ */
+type CommandHandler<T = unknown> = (payload: T, actions: CommandActions) => void;
+/**
+ * Projection reducer folds events into a read model.
+ *
+ * **Purity contract:** Reducers MUST be pure — return a new state value
+ * without mutating `state` or any event. The `state` parameter is the
+ * original `initial` value on every invocation (full event-sourcing replay),
+ * so mutation would corrupt future recomputations.
+ */
+type ProjectionReducer<TState = unknown, TEvent = unknown> = (state: TState, events: readonly CqrsEvent<TEvent>[]) => TState;
+type SagaHandler<T = unknown> = (event: CqrsEvent<T>) => void;
+type CqrsOptions = {
+    graph?: GraphOptions;
+};
+declare class CqrsGraph extends Graph {
+    private readonly _eventLogs;
+    private readonly _commandHandlers;
+    private readonly _projections;
+    private readonly _sagas;
+    private readonly _keepaliveDisposers;
+    private _eventStore;
+    private _seq;
+    constructor(name: string, opts?: CqrsOptions);
+    destroy(): void;
+    /**
+     * Register a named event stream backed by `reactiveLog`.
+     * Guard denies external `write` — only commands append internally.
+     */
+    event(name: string): Node<readonly CqrsEvent[]>;
+    /** Internal: append to an event log, auto-registering if needed. */
+    private _appendEvent;
+    /**
+     * Register a command with its handler. Guard denies `observe` (write-only).
+     * Use `dispatch(name, payload)` to execute.
+     *
+     * The command node carries dynamic `meta.error` — a reactive companion
+     * that holds the last handler error (or `null` on success).
+     */
+    command<T = unknown>(name: string, handler: CommandHandler<T>): Node<T>;
+    /**
+     * Execute a registered command. Wraps the entire dispatch in `batch()` so
+     * the command node DATA and all emitted events settle atomically.
+     *
+     * If the handler throws, `meta.error` on the command node is set to the
+     * error and the exception is re-thrown.
+     */
+    dispatch<T = unknown>(commandName: string, payload: T): void;
+    /**
+     * Register a read-only projection derived from event streams.
+     * Guard denies `write` — value is computed from events only.
+     *
+     * **Purity contract:** The `reducer` must be a pure function — it receives
+     * the original `initial` on every invocation (full event-sourcing replay).
+     * Never mutate `initial`; always return a new value.
+     */
+    projection<TState>(name: string, eventNames: readonly string[], reducer: ProjectionReducer<TState>, initial: TState): Node<TState>;
+    /**
+     * Register an event-driven side effect. Runs handler for each **new** event
+     * from the specified streams (tracks last-processed entry count per stream).
+     *
+     * The saga node carries dynamic `meta.error` — a reactive companion that
+     * holds the last handler error (or `null` on success). Handler errors do
+     * not propagate out of the saga run (the event cursor still advances so
+     * the same entry is not delivered twice).
+     */
+    saga<T = unknown>(name: string, eventNames: readonly string[], handler: SagaHandler<T>): Node<unknown>;
+    useEventStore(adapter: EventStoreAdapter): void;
+    /**
+     * Replay persisted events through a reducer to rebuild a read model.
+     * Requires an event store adapter wired via `useEventStore()`.
+     */
+    rebuildProjection<TState>(eventNames: readonly string[], reducer: ProjectionReducer<TState>, initial: TState): Promise<TState>;
+}
+/**
+ * Create a CQRS graph container.
+ *
+ * @example
+ * ```ts
+ * const app = cqrs("orders");
+ * app.event("orderPlaced");
+ * app.command("placeOrder", (payload, { emit }) => {
+ *   emit("orderPlaced", { orderId: payload.id, amount: payload.amount });
+ * });
+ * app.projection("orderCount", ["orderPlaced"], (_s, events) => events.length, 0);
+ * app.dispatch("placeOrder", { id: "1", amount: 100 });
+ * ```
+ */
+declare function cqrs(name: string, opts?: CqrsOptions): CqrsGraph;
+
+type index_CommandActions = CommandActions;
+type index_CommandHandler<T = unknown> = CommandHandler<T>;
+type index_CqrsEvent<T = unknown> = CqrsEvent<T>;
+type index_CqrsGraph = CqrsGraph;
+declare const index_CqrsGraph: typeof CqrsGraph;
+type index_CqrsOptions = CqrsOptions;
+type index_EventStoreAdapter = EventStoreAdapter;
+type index_EventStoreCursor = EventStoreCursor;
+type index_LoadEventsResult = LoadEventsResult;
+type index_MemoryEventStore = MemoryEventStore;
+declare const index_MemoryEventStore: typeof MemoryEventStore;
+type index_ProjectionReducer<TState = unknown, TEvent = unknown> = ProjectionReducer<TState, TEvent>;
+type index_SagaHandler<T = unknown> = SagaHandler<T>;
+declare const index_cqrs: typeof cqrs;
+declare namespace index {
+  export { type index_CommandActions as CommandActions, type index_CommandHandler as CommandHandler, type index_CqrsEvent as CqrsEvent, index_CqrsGraph as CqrsGraph, type index_CqrsOptions as CqrsOptions, type index_EventStoreAdapter as EventStoreAdapter, type index_EventStoreCursor as EventStoreCursor, type index_LoadEventsResult as LoadEventsResult, index_MemoryEventStore as MemoryEventStore, type index_ProjectionReducer as ProjectionReducer, type index_SagaHandler as SagaHandler, index_cqrs as cqrs };
+}
+
+export { type CqrsOptions as C, type EventStoreAdapter as E, type LoadEventsResult as L, MemoryEventStore as M, type ProjectionReducer as P, type SagaHandler as S, CqrsGraph as a, type CommandActions as b, type CommandHandler as c, type CqrsEvent as d, type EventStoreCursor as e, cqrs as f, index as i };

package/dist/index-CHEswufn.d.cts

@@ -0,0 +1,163 @@
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { R as ReactiveMapBundle } from './reactive-map-DUeRmb9d.cjs';
+import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-D48Qw9Cg.cjs';
+import { w as watchTopologyTree } from './topology-tree-DROUdq5B.cjs';
+
+/** Aggregate topology stats emitted by {@link LensGraph.stats}. */
+interface TopologyStats {
+    /** Total primary nodes across this graph and all transitively mounted subgraphs. */
+    nodeCount: number;
+    /** Total directed edges (derived from deps; no duplicates). */
+    edgeCount: number;
+    /** Count of mounted subgraphs (transitive). */
+    subgraphCount: number;
+    /** Qualified paths with no upstream deps (source nodes). Sorted. */
+    sources: readonly string[];
+    /** Qualified paths with no downstream consumers in-graph (sink nodes). Sorted. */
+    sinks: readonly string[];
+    /** Longest path from any source to any sink (in edges). `0` for empty graphs. */
+    depth: number;
+    /** `true` if the dep DAG contains a cycle (feedback edge). */
+    hasCycles: boolean;
+}
+/** 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[];
+}
+/** One per-path flow entry stored in {@link LensGraph.flow}. */
+interface FlowEntry {
+    path: string;
+    /** Cumulative DATA emissions observed since the lens activated. */
+    count: number;
+    /** `monotonicNs()` at the most recent DATA emission, or `null` if none yet. */
+    lastUpdate_ns: number | null;
+}
+/** Options for {@link graphLens}. */
+interface GraphLensOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /**
+     * Limit which node paths `flow` tracks. When omitted, every path in
+     * `target.describe()` is observed. Recommended for graphs with hundreds
+     * of nodes since each tracked path adds one observe-event dispatch per
+     * DATA emission.
+     */
+    pathFilter?: (path: string) => boolean;
+    /**
+     * LRU cap on the {@link LensGraph.flow} map. When set, the flow tracker
+     * evicts least-recently-used paths (by insertion / set order) once the
+     * entry count exceeds this bound. Omit for unbounded (not recommended
+     * for long-running graphs with churning paths). Passed through to the
+     * underlying {@link reactiveMap}'s `maxSize`.
+     */
+    maxFlowPaths?: number;
+}
+/**
+ * Reactive observability surface for a target {@link Graph}.
+ * See {@link graphLens}.
+ *
+ * @category observability
+ */
+declare class LensGraph extends Graph {
+    /**
+     * Aggregate structural stats — `nodeCount`, `edgeCount`, `sources`,
+     * `sinks`, `depth`, `hasCycles`, `subgraphCount`. Recomputes on every
+     * structural change via {@link watchTopologyTree} (transitive).
+     *
+     * Named `stats` (not `topology`) because `Graph.topology` already names
+     * the raw `TopologyEvent` stream on every graph including `LensGraph`;
+     * giving the lens its own `topology` accessor with an incompatible
+     * `Node<TopologyStats>` type would break Liskov substitutability.
+     */
+    readonly stats: Node<TopologyStats>;
+    readonly health: Node<HealthReport>;
+    /**
+     * Per-path flow tracker — a live {@link ReactiveMapBundle} keyed by
+     * qualified path. Use `.get(path)` / `.has(path)` / `.size` for O(1)
+     * sync queries; subscribe to `.entries` for a reactive snapshot of the
+     * whole map. Lazy — the snapshot is materialized only while `.entries`
+     * has subscribers.
+     *
+     * Shape intentionally differs from `stats` / `health` (which are plain
+     * `Node<Report>`) because `flow` is a keyed collection, not a single
+     * aggregate value. The map shape exposes cheaper queries than any
+     * snapshot-based design.
+     */
+    readonly flow: ReactiveMapBundle<string, FlowEntry>;
+    private readonly _target;
+    constructor(target: Graph, opts?: GraphLensOptions);
+    /**
+     * Live causal chain from `from` to `to`. Recomputes whenever the target
+     * mutates. Disposed automatically when the lens is destroyed.
+     *
+     * **Lifetime note:** every call to `why()` registers a lens-owned disposer
+     * that runs on `lens.destroy()`. The returned `dispose` function releases
+     * the internal subscription but does NOT remove the lens-owned disposer —
+     * so heavy calling (e.g. per render frame) accumulates no-op disposers
+     * until lens teardown. Cache the returned handle for long-lived queries.
+     *
+     * @param from - Qualified path of the upstream endpoint.
+     * @param to - Qualified path of the downstream endpoint.
+     * @param opts - See {@link reactiveExplainPath}.
+     */
+    why(from: string, to: string, opts?: {
+        maxDepth?: number;
+        name?: string;
+        findCycle?: boolean;
+    }): {
+        node: Node<CausalChain>;
+        dispose: () => void;
+    };
+    /** Reference to the lensed graph. */
+    get target(): Graph;
+}
+/**
+ * Create a reactive observability lens over a {@link Graph}. Returns a
+ * {@link LensGraph} with three reactive surfaces (`stats`, `health`, `flow`)
+ * plus the `why(from, to)` method.
+ *
+ * The returned graph is detached. Mount it via `target.mount("lens", lens)`
+ * if you want it to appear in the target's `describe()`, or keep it standalone.
+ *
+ * @param target - The graph to observe.
+ * @param opts - See {@link GraphLensOptions}.
+ *
+ * @example
+ * ```ts
+ * const g = new Graph("app");
+ * g.add(state(0, { name: "counter" }));
+ * const lens = graphLens(g);
+ * lens.stats.subscribe((msgs) => console.log(msgs[0]?.[1])); // TopologyStats
+ * // Flow queries — O(1) without subscribing to snapshots:
+ * lens.flow.get("counter");        // FlowEntry | undefined
+ * lens.flow.size;                  // number
+ * lens.flow.entries.subscribe(...); // reactive snapshot, lazy-materialized
+ * ```
+ *
+ * @category observability
+ */
+declare function graphLens(target: Graph, opts?: GraphLensOptions): LensGraph;
+
+type index_FlowEntry = FlowEntry;
+type index_GraphLensOptions = GraphLensOptions;
+type index_HealthProblem = HealthProblem;
+type index_HealthReport = HealthReport;
+type index_LensGraph = LensGraph;
+declare const index_LensGraph: typeof LensGraph;
+type index_TopologyStats = TopologyStats;
+declare const index_graphLens: typeof graphLens;
+declare const index_watchTopologyTree: typeof watchTopologyTree;
+declare namespace index {
+  export { type index_FlowEntry as FlowEntry, type index_GraphLensOptions as GraphLensOptions, type index_HealthProblem as HealthProblem, type index_HealthReport as HealthReport, index_LensGraph as LensGraph, type index_TopologyStats as TopologyStats, index_graphLens as graphLens, index_watchTopologyTree as watchTopologyTree };
+}
+
+export { type FlowEntry as F, type GraphLensOptions as G, type HealthProblem as H, LensGraph as L, type TopologyStats as T, type HealthReport as a, graphLens as g, index as i };

package/dist/{index-C0svESO4.d.ts → index-CMn8S8Hw.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-BmerH3kS.js';
+import { a as Node } from './node-Cc1TniY8.js';
 
 /**
  * A Nanostores-compatible atom.

package/dist/{index-ByQxazQJ.d.cts → index-CRO83MmV.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-BmerH3kS.cjs';
+import { a as Node } from './node-Cc1TniY8.cjs';
 
 /**
  * Options for creating an atom.

package/dist/{index-BuEoe-Qu.d.ts → index-CloUk1kY.d.ts}

@@ -1,12 +1,12 @@
-import { i as index$2 } from './index-3lsddbbS.js';
-import { i as index$3 } from './index-C0svESO4.js';
-import { i as index$4 } from './index-BPVt8kqc.js';
-import { i as index$5 } from './index-Dzk2hrlR.js';
-import { N as Node } from './node-BmerH3kS.js';
-import { i as index$6 } from './index-VdHQMPy1.js';
-import { i as index$7 } from './index-CxFrXH4m.js';
-import { i as index$8 } from './index-wEn0eFe8.js';
-import { i as index$9 } from './index-B9B7_HEY.js';
+import { i as index$2 } from './index-Bqachn9_.js';
+import { i as index$3 } from './index-CMn8S8Hw.js';
+import { i as index$4 } from './index-m-yHof5p.js';
+import { i as index$5 } from './index-BVHOrDwO.js';
+import { a as Node } from './node-Cc1TniY8.js';
+import { i as index$6 } from './index-B1AmmSlb.js';
+import { i as index$7 } from './index-BWJV63ti.js';
+import { i as index$8 } from './index-BwM9BEkt.js';
+import { i as index$9 } from './index-DiOXyAwt.js';
 
 /**
  * Options for creating signals.