@graphrefly/graphrefly 0.26.0 → 0.28.0

package/dist/index-sm373fsH.d.ts

@@ -0,0 +1,192 @@
+import { a as Node } from './node-Cc1TniY8.js';
+import { a as GraphOptions, G as Graph } from './graph-BZGRXwOm.js';
+
+/**
+ * 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-tbf2gKHd.d.cts

@@ -0,0 +1,139 @@
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { G as Graph } from './graph-D48Qw9Cg.cjs';
+
+/**
+ * Memory patterns (roadmap §4.3).
+ *
+ * Domain-layer helpers composed from GraphRefly primitives. `vectorIndex` uses
+ * an exact-search backend by default; an HNSW adapter can be injected as an
+ * optional dependency.
+ */
+
+type CollectionPolicy = "fifo" | "lru";
+type VectorBackend = "flat" | "hnsw";
+type LightCollectionEntry<T> = {
+    readonly id: string;
+    readonly value: T;
+    readonly createdAtNs: number;
+    readonly lastAccessNs: number;
+};
+type LightCollectionOptions = {
+    name?: string;
+    maxSize?: number;
+    policy?: CollectionPolicy;
+};
+type LightCollectionBundle<T> = {
+    readonly entries: Node<ReadonlyMap<string, LightCollectionEntry<T>>>;
+    upsert: (id: string, value: T) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    get: (id: string) => T | undefined;
+    has: (id: string) => boolean;
+};
+type CollectionEntry<T> = LightCollectionEntry<T> & {
+    readonly baseScore: number;
+};
+type RankedCollectionEntry<T> = CollectionEntry<T> & {
+    readonly score: number;
+};
+type CollectionOptions<T> = {
+    maxSize?: number;
+    policy?: CollectionPolicy;
+    /**
+     * Produces a base score at insert/update time.
+     */
+    score?: (value: T) => number;
+    /**
+     * Exponential decay rate per second. 0 disables decay.
+     */
+    decayRate?: number;
+    /**
+     * Minimum score floor after decay.
+     */
+    minScore?: number;
+};
+type CollectionGraph<T> = Graph & {
+    upsert: (id: string, value: T, opts?: {
+        score?: number;
+    }) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    getItem: (id: string) => CollectionEntry<T> | undefined;
+};
+type VectorRecord<TMeta> = {
+    readonly id: string;
+    readonly vector: readonly number[];
+    readonly meta?: TMeta;
+};
+type VectorSearchResult<TMeta> = {
+    readonly id: string;
+    readonly score: number;
+    readonly meta?: TMeta;
+};
+type HnswAdapter<TMeta> = {
+    upsert: (id: string, vector: readonly number[], meta?: TMeta) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    search: (query: readonly number[], k: number) => ReadonlyArray<VectorSearchResult<TMeta>>;
+};
+type VectorIndexOptions<TMeta> = {
+    backend?: VectorBackend;
+    dimension?: number;
+    /**
+     * Optional dependency seam for HNSW.
+     */
+    hnswFactory?: () => HnswAdapter<TMeta>;
+};
+type VectorIndexBundle<TMeta> = {
+    readonly backend: VectorBackend;
+    readonly entries: Node<ReadonlyMap<string, VectorRecord<TMeta>>>;
+    upsert: (id: string, vector: readonly number[], meta?: TMeta) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    search: (query: readonly number[], k?: number) => ReadonlyArray<VectorSearchResult<TMeta>>;
+};
+type KnowledgeEdge<TRelation extends string = string> = {
+    readonly from: string;
+    readonly to: string;
+    readonly relation: TRelation;
+    readonly weight: number;
+};
+type KnowledgeGraphGraph<TEntity, TRelation extends string = string> = Graph & {
+    upsertEntity: (id: string, value: TEntity) => void;
+    removeEntity: (id: string) => void;
+    link: (from: string, to: string, relation: TRelation, weight?: number) => void;
+    unlink: (from: string, to: string, relation?: TRelation) => void;
+    related: (id: string, relation?: TRelation) => ReadonlyArray<KnowledgeEdge<TRelation>>;
+};
+declare function decay(baseScore: number, ageSeconds: number, ratePerSecond: number, minScore?: number): number;
+declare function lightCollection<T>(opts?: LightCollectionOptions): LightCollectionBundle<T>;
+declare function collection<T>(name: string, opts?: CollectionOptions<T>): CollectionGraph<T>;
+declare function vectorIndex<TMeta>(opts?: VectorIndexOptions<TMeta>): VectorIndexBundle<TMeta>;
+declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string): KnowledgeGraphGraph<TEntity, TRelation>;
+
+type index_CollectionEntry<T> = CollectionEntry<T>;
+type index_CollectionGraph<T> = CollectionGraph<T>;
+type index_CollectionOptions<T> = CollectionOptions<T>;
+type index_CollectionPolicy = CollectionPolicy;
+type index_HnswAdapter<TMeta> = HnswAdapter<TMeta>;
+type index_KnowledgeEdge<TRelation extends string = string> = KnowledgeEdge<TRelation>;
+type index_KnowledgeGraphGraph<TEntity, TRelation extends string = string> = KnowledgeGraphGraph<TEntity, TRelation>;
+type index_LightCollectionBundle<T> = LightCollectionBundle<T>;
+type index_LightCollectionEntry<T> = LightCollectionEntry<T>;
+type index_LightCollectionOptions = LightCollectionOptions;
+type index_RankedCollectionEntry<T> = RankedCollectionEntry<T>;
+type index_VectorBackend = VectorBackend;
+type index_VectorIndexBundle<TMeta> = VectorIndexBundle<TMeta>;
+type index_VectorIndexOptions<TMeta> = VectorIndexOptions<TMeta>;
+type index_VectorRecord<TMeta> = VectorRecord<TMeta>;
+type index_VectorSearchResult<TMeta> = VectorSearchResult<TMeta>;
+declare const index_collection: typeof collection;
+declare const index_decay: typeof decay;
+declare const index_knowledgeGraph: typeof knowledgeGraph;
+declare const index_lightCollection: typeof lightCollection;
+declare const index_vectorIndex: typeof vectorIndex;
+declare namespace index {
+  export { type index_CollectionEntry as CollectionEntry, type index_CollectionGraph as CollectionGraph, type index_CollectionOptions as CollectionOptions, type index_CollectionPolicy as CollectionPolicy, type index_HnswAdapter as HnswAdapter, type index_KnowledgeEdge as KnowledgeEdge, type index_KnowledgeGraphGraph as KnowledgeGraphGraph, type index_LightCollectionBundle as LightCollectionBundle, type index_LightCollectionEntry as LightCollectionEntry, type index_LightCollectionOptions as LightCollectionOptions, type index_RankedCollectionEntry as RankedCollectionEntry, type index_VectorBackend as VectorBackend, type index_VectorIndexBundle as VectorIndexBundle, type index_VectorIndexOptions as VectorIndexOptions, type index_VectorRecord as VectorRecord, type index_VectorSearchResult as VectorSearchResult, index_collection as collection, index_decay as decay, index_knowledgeGraph as knowledgeGraph, index_lightCollection as lightCollection, index_vectorIndex as vectorIndex };
+}
+
+export { type CollectionEntry as C, type HnswAdapter as H, type KnowledgeGraphGraph as K, type LightCollectionBundle as L, type RankedCollectionEntry as R, type VectorIndexBundle as V, type VectorSearchResult as a, type CollectionGraph as b, type CollectionOptions as c, type CollectionPolicy as d, type KnowledgeEdge as e, type LightCollectionEntry as f, type LightCollectionOptions as g, type VectorBackend as h, index as i, type VectorIndexOptions as j, type VectorRecord as k, collection as l, decay as m, knowledgeGraph as n, lightCollection as o, vectorIndex as v };

package/dist/{demo-shell-26p5fVxn.d.cts → index-u15meRxL.d.cts}

@@ -1,5 +1,5 @@
-import { G as Graph } from './graph-6tZ5jEzr.cjs';
-import { M as MeasurementAdapter } from './reactive-layout-BaOQefHu.cjs';
+import { G as Graph } from './graph-D48Qw9Cg.cjs';
+import { M as MeasurementAdapter } from './reactive-layout-CpYb5qLP.cjs';
 
 /**
  * Three-pane demo shell (roadmap §7.2).
@@ -86,17 +86,17 @@ type DemoShellHandle = {
  */
 declare function demoShell(opts?: DemoShellOptions): DemoShellHandle;
 
-type demoShell$1_DemoShellHandle = DemoShellHandle;
-type demoShell$1_DemoShellOptions = DemoShellOptions;
-type demoShell$1_FullscreenPane = FullscreenPane;
-type demoShell$1_GraphLabelSize = GraphLabelSize;
-type demoShell$1_HighlightCallbacks = HighlightCallbacks;
-type demoShell$1_HoverPaneType = HoverPaneType;
-type demoShell$1_HoverTarget = HoverTarget;
-type demoShell$1_NodeRegistry = NodeRegistry;
-declare const demoShell$1_demoShell: typeof demoShell;
-declare namespace demoShell$1 {
-  export { type demoShell$1_DemoShellHandle as DemoShellHandle, type demoShell$1_DemoShellOptions as DemoShellOptions, type demoShell$1_FullscreenPane as FullscreenPane, type demoShell$1_GraphLabelSize as GraphLabelSize, type demoShell$1_HighlightCallbacks as HighlightCallbacks, type demoShell$1_HoverPaneType as HoverPaneType, type demoShell$1_HoverTarget as HoverTarget, type demoShell$1_NodeRegistry as NodeRegistry, demoShell$1_demoShell as demoShell };
+type index_DemoShellHandle = DemoShellHandle;
+type index_DemoShellOptions = DemoShellOptions;
+type index_FullscreenPane = FullscreenPane;
+type index_GraphLabelSize = GraphLabelSize;
+type index_HighlightCallbacks = HighlightCallbacks;
+type index_HoverPaneType = HoverPaneType;
+type index_HoverTarget = HoverTarget;
+type index_NodeRegistry = NodeRegistry;
+declare const index_demoShell: typeof demoShell;
+declare namespace index {
+  export { type index_DemoShellHandle as DemoShellHandle, type index_DemoShellOptions as DemoShellOptions, type index_FullscreenPane as FullscreenPane, type index_GraphLabelSize as GraphLabelSize, type index_HighlightCallbacks as HighlightCallbacks, type index_HoverPaneType as HoverPaneType, type index_HoverTarget as HoverTarget, type index_NodeRegistry as NodeRegistry, index_demoShell as demoShell };
 }
 
-export { type DemoShellHandle as D, type FullscreenPane as F, type GraphLabelSize as G, type HighlightCallbacks as H, type NodeRegistry as N, type DemoShellOptions as a, type HoverPaneType as b, type HoverTarget as c, demoShell$1 as d, demoShell as e };
+export { type DemoShellHandle as D, type FullscreenPane as F, type GraphLabelSize as G, type HighlightCallbacks as H, type NodeRegistry as N, type DemoShellOptions as a, type HoverPaneType as b, type HoverTarget as c, demoShell as d, index as i };

package/dist/{index-eJ6T_qGM.d.ts → index-umtoWT8K.d.ts}

@@ -1,5 +1,6 @@
-import { l as GraphReFlyConfig } from './node-C_IBuvX2.js';
-import { c as GraphPersistSnapshot, m as GraphCheckpointRecord, G as Graph, T as TopologyEvent, C as CausalChain, j as CausalStep, D as DescribeFilter, E as ExplainPathOptions, k as GRAPH_META_SEGMENT, l as GraphActorOptions, b as GraphAttachStorageOptions, d as GraphDescribeOptions, e as GraphDescribeOutput, n as GraphDiagramDirection, o as GraphDiagramOptions, p as GraphDiffChange, i as GraphDiffResult, q as GraphFactoryContext, h as GraphNodeFactory, r as GraphObserveAll, s as GraphObserveOne, a as GraphOptions, g as GraphProfileOptions, f as GraphProfileResult, t as GraphVersionChange, u as GraphWALDiff, N as NodeProfile, O as ObserveDetail, v as ObserveEvent, w as ObserveOptions, x as ObserveResult, y as ObserveTheme, z as ObserveThemeName, R as ReachableDirection, A as ReachableOptions, S as SNAPSHOT_VERSION, B as TraceEntry, F as diffForWAL, H as explainPath, I as graphProfile, J as reachable } from './graph-DQ69XU0g.js';
+import { o as GraphReFlyConfig } from './node-Cc1TniY8.js';
+import { d as GraphPersistSnapshot, i as GraphCheckpointRecord, G as Graph, C as CausalChain, e as CausalStep, D as DescribeFilter, E as ExplainPathOptions, f as GRAPH_META_SEGMENT, g as GraphActorOptions, h as GraphAttachStorageOptions, b as GraphDescribeOptions, c as GraphDescribeOutput, j as GraphDiagramDirection, k as GraphDiagramOptions, l as GraphDiffChange, m as GraphDiffResult, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, r as GraphProfileOptions, s as GraphProfileResult, t as GraphVersionChange, u as GraphWALDiff, N as NodeProfile, O as ObserveDetail, v as ObserveEvent, w as ObserveOptions, x as ObserveResult, y as ObserveTheme, z as ObserveThemeName, R as ReachableDirection, A as ReachableOptions, S as SNAPSHOT_VERSION, T as TopologyEvent, B as TraceEntry, F as diffForWAL, H as explainPath, I as graphProfile, J as mermaidLiveUrl, K as reachable } from './graph-BZGRXwOm.js';
+import { w as watchTopologyTree } from './topology-tree-CYHOwQZ_.js';
 
 /**
  * Approximate in-memory size estimation for arbitrary JS values.
@@ -255,26 +256,146 @@ declare function registerBuiltinCodecs(config: GraphReFlyConfig): void;
 declare function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot;
 
 /**
- * Subscribe to structural changes across `graph` and every transitively
- * mounted subgraph. `cb` fires on every {@link TopologyEvent} from any
- * graph in the tree. Newly-mounted subgraphs are auto-wired when their
- * parent emits `{kind: "added", nodeKind: "mount"}`; newly-unmounted
- * subgraphs' subscriptions are disposed via the parent's
- * `{kind: "removed", nodeKind: "mount"}` event plus the returned
- * `GraphRemoveAudit`.
+ * Graph observability validation — smoke-exercise helper (D4).
  *
- * The callback receives a third argument `prefix`: the `::`-delimited
- * path from the root watched graph to the emitter, ending with `"::"`
- * (empty string when the event comes from the root itself). Compute
- * a qualified path for an added/removed entry as `prefix + event.name`.
+ * One library-level utility that walks every observability surface the library
+ * ships — `describe()`, `explain(from, to)`, `observe(path)` — and reports
+ * failures as a structured result. Non-throwing by default; composable into
+ * example dry-run paths, CI smoke tests, and MCP reduce-path validators.
  *
- * @param graph - Root graph to watch.
- * @param cb - Receives `(event, emitterGraph, prefix)`.
- * @returns Dispose function — tears down every active subscription.
+ * **Motivation.** Dry-run equivalence (CLAUDE.md) requires every observability
+ * call the real run exercises to also run under dry-run. Previously each
+ * example reimplemented the walk (inbox-reducer caught a `describe()`
+ * dangling-pointer bug only after adding an ad-hoc `graph.explain` check).
+ * This utility centralizes the smoke-exercise so regressions in
+ * `describe` / `explain` / `observe` surface BEFORE any wire spend.
  *
- * @category observability
+ * **Non-goals.** Not a deep correctness check. `describe()` structural
+ * invariants (dangling deps, duplicate paths) are what this catches; actual
+ * data assertions belong in application tests.
+ *
+ * @module
+ */
+
+/** Describe render formats exercised by {@link validateGraphObservability}. */
+type ObservabilityDescribeFormat = "json" | "pretty" | "mermaid" | "mermaid-url" | "d2";
+/** One observability check performed by {@link validateGraphObservability}. */
+type ObservabilityCheck = 
+/** `describe()` was exercised and its structural invariants (nodes ⊇ deps) held. */
+{
+    kind: "describe";
+    ok: true;
+    nodeCount: number;
+    edgeCount: number;
+} | {
+    kind: "describe";
+    ok: false;
+    reason: string;
+    danglingDeps?: readonly string[];
+}
+/** `describe({ format })` render was exercised and produced non-empty output. */
+ | {
+    kind: "describe-format";
+    ok: true;
+    format: ObservabilityDescribeFormat;
+    length: number;
+} | {
+    kind: "describe-format";
+    ok: false;
+    format: ObservabilityDescribeFormat;
+    reason: string;
+}
+/** `observe(path)` succeeded / failed. `path` is the requested path. */
+ | {
+    kind: "observe";
+    ok: true;
+    path: string;
+} | {
+    kind: "observe";
+    ok: false;
+    path: string;
+    reason: string;
+}
+/** `explain(from, to)` succeeded / failed. `found` is the chain's found flag. */
+ | {
+    kind: "explain";
+    ok: true;
+    from: string;
+    to: string;
+    found: boolean;
+    steps: number;
+} | {
+    kind: "explain";
+    ok: false;
+    from: string;
+    to: string;
+    reason: string;
+};
+/** Structured result returned by {@link validateGraphObservability}. */
+interface ValidateObservabilityResult {
+    /** `true` iff every performed check passed (`ok: true`). */
+    readonly ok: boolean;
+    /** All checks performed, in the order they ran. */
+    readonly checks: readonly ObservabilityCheck[];
+    /** Convenience — checks with `ok: false`. */
+    readonly failures: readonly ObservabilityCheck[];
+    /** Single-line summary (e.g. for `process.stderr`). */
+    summary(): string;
+}
+/** Options for {@link validateGraphObservability}. */
+interface ValidateObservabilityOptions {
+    /**
+     * Paths to exercise via `graph.observe(path)`. Each path is resolved against
+     * the same path grammar `graph.observe` / `graph.resolve` use. Non-existent
+     * paths are reported as observe failures.
+     */
+    readonly paths?: readonly string[];
+    /**
+     * `(from, to)` pairs to exercise via `graph.explain(from, to)`. Each pair
+     * records `found` and `steps`; a pair where `found === false` does NOT
+     * fail the overall result — pass `requireFound: true` to tighten that.
+     */
+    readonly pairs?: ReadonlyArray<readonly [from: string, to: string]>;
+    /**
+     * When `true`, `explain` pairs that return `found: false` count as failures.
+     * Default `true` — the common case is "assert this chain exists."
+     */
+    readonly requireFound?: boolean;
+    /**
+     * When `true`, skip the `describe()` structural check (nodes ⊇ deps).
+     * Default `false`. Turn off only when your graph intentionally keeps
+     * untracked deps (rare — COMPOSITION-GUIDE §24 argues against it).
+     */
+    readonly skipDescribe?: boolean;
+    /**
+     * Describe formats to exercise via `graph.describe({ format })`. Each
+     * format renders the graph once and checks that the result is a non-empty
+     * string. Useful in dry-run blocks so regressions in the render paths
+     * (mermaid, pretty, json, d2, mermaid-url) surface before any wire spend.
+     */
+    readonly formats?: readonly ObservabilityDescribeFormat[];
+}
+/**
+ * Exercise every observability surface on `graph` and report failures.
+ *
+ * Does NOT throw — returns a structured result so callers (dry-run blocks,
+ * CLI smoke tests, MCP reduce-path validators) can exit non-zero with a
+ * diagnostic instead of letting the process crash mid-inspection.
+ *
+ * @example
+ * ```ts
+ * const result = validateGraphObservability(graph, {
+ *   paths: ["input", "output"],
+ *   pairs: [["input", "output"]],
+ * });
+ * if (!result.ok) {
+ *   console.error(result.summary());
+ *   for (const f of result.failures) console.error(f);
+ *   process.exit(3);
+ * }
+ * ```
  */
-declare function watchTopologyTree(graph: Graph, cb: (event: TopologyEvent, emitter: Graph, prefix: string) => void): () => void;
+declare function validateGraphObservability(graph: Graph, opts?: ValidateObservabilityOptions): ValidateObservabilityResult;
 
 /**
  * Graph container: registry, wiring, introspection (Phase 1).
@@ -312,6 +433,8 @@ declare const index_GraphWALDiff: typeof GraphWALDiff;
 declare const index_JsonCodec: typeof JsonCodec;
 type index_LazyGraphCodec = LazyGraphCodec;
 declare const index_NodeProfile: typeof NodeProfile;
+type index_ObservabilityCheck = ObservabilityCheck;
+type index_ObservabilityDescribeFormat = ObservabilityDescribeFormat;
 declare const index_ObserveDetail: typeof ObserveDetail;
 declare const index_ObserveEvent: typeof ObserveEvent;
 declare const index_ObserveOptions: typeof ObserveOptions;
@@ -324,6 +447,8 @@ declare const index_SIZEOF_SYMBOL: typeof SIZEOF_SYMBOL;
 declare const index_SNAPSHOT_VERSION: typeof SNAPSHOT_VERSION;
 declare const index_TopologyEvent: typeof TopologyEvent;
 declare const index_TraceEntry: typeof TraceEntry;
+type index_ValidateObservabilityOptions = ValidateObservabilityOptions;
+type index_ValidateObservabilityResult = ValidateObservabilityResult;
 type index_WALEntry = WALEntry;
 declare const index_createDagCborCodec: typeof createDagCborCodec;
 declare const index_createDagCborZstdCodec: typeof createDagCborZstdCodec;
@@ -332,13 +457,15 @@ declare const index_diffForWAL: typeof diffForWAL;
 declare const index_encodeEnvelope: typeof encodeEnvelope;
 declare const index_explainPath: typeof explainPath;
 declare const index_graphProfile: typeof graphProfile;
+declare const index_mermaidLiveUrl: typeof mermaidLiveUrl;
 declare const index_reachable: typeof reachable;
 declare const index_registerBuiltinCodecs: typeof registerBuiltinCodecs;
 declare const index_replayWAL: typeof replayWAL;
 declare const index_sizeof: typeof sizeof;
+declare const index_validateGraphObservability: typeof validateGraphObservability;
 declare const index_watchTopologyTree: typeof watchTopologyTree;
 declare namespace index {
-  export { index_CausalChain as CausalChain, index_CausalStep as CausalStep, index_DescribeFilter as DescribeFilter, index_ENVELOPE_VERSION as ENVELOPE_VERSION, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_ExplainPathOptions as ExplainPathOptions, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAttachStorageOptions as GraphAttachStorageOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOptions as GraphDescribeOptions, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiagramOptions as GraphDiagramOptions, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphProfileOptions as GraphProfileOptions, index_GraphProfileResult as GraphProfileResult, index_GraphVersionChange as GraphVersionChange, index_GraphWALDiff as GraphWALDiff, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_NodeProfile as NodeProfile, index_ObserveDetail as ObserveDetail, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ObserveTheme as ObserveTheme, index_ObserveThemeName as ObserveThemeName, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, OVERHEAD as SIZEOF_OVERHEAD, index_SIZEOF_SYMBOL as SIZEOF_SYMBOL, index_SNAPSHOT_VERSION as SNAPSHOT_VERSION, index_TopologyEvent as TopologyEvent, index_TraceEntry as TraceEntry, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_decodeEnvelope as decodeEnvelope, index_diffForWAL as diffForWAL, index_encodeEnvelope as encodeEnvelope, index_explainPath as explainPath, index_graphProfile as graphProfile, index_reachable as reachable, index_registerBuiltinCodecs as registerBuiltinCodecs, index_replayWAL as replayWAL, index_sizeof as sizeof, index_watchTopologyTree as watchTopologyTree };
+  export { index_CausalChain as CausalChain, index_CausalStep as CausalStep, index_DescribeFilter as DescribeFilter, index_ENVELOPE_VERSION as ENVELOPE_VERSION, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_ExplainPathOptions as ExplainPathOptions, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAttachStorageOptions as GraphAttachStorageOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOptions as GraphDescribeOptions, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiagramOptions as GraphDiagramOptions, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphProfileOptions as GraphProfileOptions, index_GraphProfileResult as GraphProfileResult, index_GraphVersionChange as GraphVersionChange, index_GraphWALDiff as GraphWALDiff, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_NodeProfile as NodeProfile, type index_ObservabilityCheck as ObservabilityCheck, type index_ObservabilityDescribeFormat as ObservabilityDescribeFormat, index_ObserveDetail as ObserveDetail, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ObserveTheme as ObserveTheme, index_ObserveThemeName as ObserveThemeName, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, OVERHEAD as SIZEOF_OVERHEAD, index_SIZEOF_SYMBOL as SIZEOF_SYMBOL, index_SNAPSHOT_VERSION as SNAPSHOT_VERSION, index_TopologyEvent as TopologyEvent, index_TraceEntry as TraceEntry, type index_ValidateObservabilityOptions as ValidateObservabilityOptions, type index_ValidateObservabilityResult as ValidateObservabilityResult, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_decodeEnvelope as decodeEnvelope, index_diffForWAL as diffForWAL, index_encodeEnvelope as encodeEnvelope, index_explainPath as explainPath, index_graphProfile as graphProfile, index_mermaidLiveUrl as mermaidLiveUrl, index_reachable as reachable, index_registerBuiltinCodecs as registerBuiltinCodecs, index_replayWAL as replayWAL, index_sizeof as sizeof, index_validateGraphObservability as validateGraphObservability, index_watchTopologyTree as watchTopologyTree };
 }
 
-export { ENVELOPE_VERSION as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, OVERHEAD as O, SIZEOF_SYMBOL as S, type WALEntry as W, type EvictedSubgraphInfo as a, type EvictionPolicy as b, createDagCborCodec as c, createDagCborZstdCodec as d, decodeEnvelope as e, encodeEnvelope as f, replayWAL as g, index as i, registerBuiltinCodecs as r, sizeof as s, watchTopologyTree as w };
+export { ENVELOPE_VERSION as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, type ObservabilityCheck as O, SIZEOF_SYMBOL as S, type ValidateObservabilityOptions as V, type WALEntry as W, type EvictedSubgraphInfo as a, type EvictionPolicy as b, type ObservabilityDescribeFormat as c, OVERHEAD as d, type ValidateObservabilityResult as e, createDagCborCodec as f, createDagCborZstdCodec as g, decodeEnvelope as h, encodeEnvelope as i, index as j, replayWAL as k, registerBuiltinCodecs as r, sizeof as s, validateGraphObservability as v };