@graphrefly/graphrefly 0.26.0 → 0.28.0

package/dist/index-rX8HBM5h.d.cts

@@ -0,0 +1,321 @@
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { G as Graph } from './graph-D48Qw9Cg.cjs';
+import { L as LLMAdapter } from './types-O3GzJY2U.cjs';
+
+/**
+ * LLM graph composition (roadmap §8.3).
+ *
+ * Declarative GraphSpec schema + compiler/decompiler for graph topology.
+ * The LLM designs graphs as JSON; compileSpec instantiates them; decompileGraph
+ * extracts them back. Templates support reusable subgraph patterns. Feedback
+ * edges express bounded cycles via §8.1 feedback().
+ *
+ * @module
+ */
+
+/** A single node declaration in a GraphSpec. */
+type GraphSpecNode = {
+    /** Node kind: state, producer, derived, effect, operator. */
+    type: "state" | "producer" | "derived" | "effect" | "operator";
+    /** Dependency node names (for derived/effect/operator). */
+    deps?: string[];
+    /** Named function from the catalog (for derived/effect/operator/producer). */
+    fn?: string;
+    /** Named source from the catalog (for producer). */
+    source?: string;
+    /** Freeform config passed to the catalog fn/source factory. */
+    config?: Record<string, unknown>;
+    /** Initial value (for state nodes). */
+    initial?: unknown;
+    /** Human/LLM-readable metadata. */
+    meta?: Record<string, unknown>;
+};
+/** Template instantiation node — expanded at compile time. */
+type GraphSpecTemplateRef = {
+    type: "template";
+    /** Name of the template to instantiate. */
+    template: string;
+    /** Parameter bindings: template param name → node name. */
+    bind: Record<string, string>;
+};
+/** A reusable subgraph pattern with parameter substitution. */
+type GraphSpecTemplate = {
+    /** Parameter names (prefixed with $ in node refs). */
+    params: string[];
+    /** Node declarations within the template. */
+    nodes: Record<string, GraphSpecNode>;
+    /** Which node's output is the template's output. */
+    output: string;
+};
+/** A feedback edge: bounded cycle from condition to reentry. */
+type GraphSpecFeedbackEdge = {
+    /** Node whose DATA triggers the feedback. */
+    from: string;
+    /** State node that receives the feedback value. */
+    to: string;
+    /** Max iterations before stopping (default: 10). */
+    maxIterations?: number;
+};
+/** Declarative graph topology for LLM composition (§8.3). */
+type GraphSpec = {
+    /** Graph name. */
+    name: string;
+    /** Node declarations (keyed by node name). */
+    nodes: Record<string, GraphSpecNode | GraphSpecTemplateRef>;
+    /** Reusable subgraph templates. */
+    templates?: Record<string, GraphSpecTemplate>;
+    /** Feedback edges (bounded cycles). */
+    feedback?: GraphSpecFeedbackEdge[];
+};
+/**
+ * Factory for creating a derived/effect/operator node from catalog.
+ * Receives resolved dep nodes and the config from the spec.
+ */
+type FnFactory = (deps: Node<unknown>[], config: Record<string, unknown>) => Node<unknown>;
+/**
+ * Factory for creating a producer node from catalog.
+ * Receives the config from the spec.
+ */
+type SourceFactory = (config: Record<string, unknown>) => Node<unknown>;
+/** Simple config field descriptor for LLM prompt generation and validation. */
+type ConfigFieldSchema = {
+    /** Human-readable type: "string", "number", "boolean", "string[]", etc. */
+    type: string;
+    /** Whether this field is required (default: true). */
+    required?: boolean;
+    /** Allowed values (enum constraint). */
+    enum?: readonly (string | number | boolean)[];
+    /** Human-readable description for LLM context. */
+    description?: string;
+    /** Default value if omitted. */
+    default?: unknown;
+};
+/**
+ * Rich catalog entry: bundles a runtime factory with LLM-facing metadata.
+ *
+ * The metadata is used to:
+ * 1. Auto-generate prompt text for {@link llmCompose} (replaces manual `catalogDescription`)
+ * 2. Validate LLM output in {@link validateSpec} (catch wrong fn names, invalid config)
+ * 3. Provide actionable error messages for {@link llmRefine} feedback loops
+ *
+ * Developers register ONE object; the library handles prompt generation and validation.
+ */
+type CatalogFnEntry = {
+    /** Runtime factory. */
+    factory: FnFactory;
+    /** One-line description for LLM prompt (what it does, not how). */
+    description: string;
+    /** Config field schemas. Keys are config field names. */
+    configSchema?: Record<string, ConfigFieldSchema>;
+    /** Example config objects (shown in prompt for complex fns). */
+    examples?: Record<string, unknown>[];
+    /** Category tags for grouping in prompt (e.g., "resilience", "reduction", "ai"). */
+    tags?: string[];
+};
+/** Rich catalog entry for producer sources. */
+type CatalogSourceEntry = {
+    /** Runtime factory. */
+    factory: SourceFactory;
+    /** One-line description for LLM prompt. */
+    description: string;
+    /** Config field schemas. */
+    configSchema?: Record<string, ConfigFieldSchema>;
+    /** Example config objects. */
+    examples?: Record<string, unknown>[];
+    /** Category tags. */
+    tags?: string[];
+};
+/**
+ * Fn/source lookup table passed to compileSpec and llmCompose.
+ *
+ * Accepts both bare factories (backward-compatible) and rich {@link CatalogFnEntry}
+ * / {@link CatalogSourceEntry} objects. When rich entries are provided, the library
+ * auto-generates LLM prompts and validates LLM output against the catalog.
+ */
+type GraphSpecCatalog = {
+    fns?: Record<string, FnFactory | CatalogFnEntry>;
+    sources?: Record<string, SourceFactory | CatalogSourceEntry>;
+};
+/** Type guard: is this a rich catalog fn entry (vs bare factory)? */
+declare function isRichFnEntry(entry: FnFactory | CatalogFnEntry): entry is CatalogFnEntry;
+/** Type guard: is this a rich catalog source entry (vs bare factory)? */
+declare function isRichSourceEntry(entry: SourceFactory | CatalogSourceEntry): entry is CatalogSourceEntry;
+/** Extract the runtime factory from a catalog entry (rich or bare). */
+declare function extractFnFactory(entry: FnFactory | CatalogFnEntry): FnFactory;
+/** Extract the runtime factory from a catalog source entry (rich or bare). */
+declare function extractSourceFactory(entry: SourceFactory | CatalogSourceEntry): SourceFactory;
+/**
+ * Auto-generate catalog prompt text from rich catalog entries.
+ *
+ * Groups fns by tag, formats each as `- name: description. Config: { ... }`.
+ * Falls back to listing names only for bare factories.
+ */
+declare function generateCatalogPrompt(catalog: GraphSpecCatalog): string;
+/**
+ * Validate a GraphSpec against a catalog.
+ *
+ * Checks that fn/source names reference actual catalog entries, and validates
+ * config fields against configSchema when rich entries are available.
+ * Returns additional errors beyond structural {@link validateSpec} checks.
+ */
+declare function validateSpecAgainstCatalog(spec: GraphSpec, catalog: GraphSpecCatalog): GraphSpecValidation;
+/** Validation result from {@link validateSpec}. */
+type GraphSpecValidation = {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validate a GraphSpec JSON object.
+ *
+ * Checks structural validity: required fields, node types, dep references,
+ * template references, feedback edge targets, self-cycles, and bind completeness.
+ */
+declare function validateSpec(spec: unknown): GraphSpecValidation;
+/** Options for {@link compileSpec}. */
+type CompileSpecOptions = {
+    /** Fn/source catalog for resolving named factories. */
+    catalog?: GraphSpecCatalog;
+};
+/**
+ * Instantiate a Graph from a GraphSpec.
+ *
+ * Handles template expansion (mounted subgraphs), feedback wiring via §8.1
+ * feedback(), node factory lookup from the catalog, and topology validation.
+ *
+ * @param spec - Declarative graph topology.
+ * @param opts - Catalog and compile options.
+ * @returns A running Graph.
+ * @throws On validation failure, missing catalog entries, or unresolvable deps.
+ *
+ * @category patterns
+ */
+declare function compileSpec(spec: GraphSpec, opts?: CompileSpecOptions): Graph;
+/**
+ * Extract a GraphSpec from a running graph.
+ *
+ * Uses `describe({ detail: "standard" })` as a starting point, then enriches:
+ * - Feedback edges recovered from counter node meta (`feedbackFrom`/`feedbackTo`)
+ * - Template refs recovered from output node meta (`_templateName`/`_templateBind`)
+ * - Structural fingerprinting as fallback for 2+ identical mounted subgraphs
+ *
+ * @param graph - Running graph to decompile.
+ * @returns A GraphSpec representation.
+ *
+ * @category patterns
+ */
+declare function decompileGraph(graph: Graph): GraphSpec;
+/** A single change in a spec diff. */
+type SpecDiffEntry = {
+    type: "added" | "removed" | "changed";
+    path: string;
+    detail?: string;
+};
+/** Structural diff between two GraphSpecs. */
+type SpecDiffResult = {
+    entries: SpecDiffEntry[];
+    summary: string;
+};
+/**
+ * Compute a structural diff between two GraphSpecs.
+ *
+ * Template-aware: reports "changed template definition" vs "changed
+ * instantiation bindings." No runtime needed — pure JSON comparison.
+ *
+ * @param specA - The "before" spec.
+ * @param specB - The "after" spec.
+ * @returns Diff entries and a human-readable summary.
+ *
+ * @category patterns
+ */
+declare function specDiff(specA: GraphSpec, specB: GraphSpec): SpecDiffResult;
+/** Options for {@link llmCompose}. */
+type LLMComposeOptions = {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Extra instructions appended to the system prompt. */
+    systemPromptExtra?: string;
+    /**
+     * Available fn/source catalog names for the LLM to reference.
+     * When omitted and `catalog` contains rich {@link CatalogFnEntry} entries,
+     * the prompt is auto-generated via {@link generateCatalogPrompt}.
+     */
+    catalogDescription?: string;
+    /**
+     * Catalog for auto-prompt generation and catalog-aware validation.
+     * When rich entries are provided, the catalog prompt is auto-generated
+     * and LLM output is validated against fn/source names and config schemas.
+     */
+    catalog?: GraphSpecCatalog;
+    /**
+     * Max auto-refine attempts when the LLM output fails catalog validation.
+     * Each attempt feeds the validation errors back to the LLM via llmRefine.
+     * Default: 0 (no auto-refine). Set to 2-3 for production use.
+     */
+    maxAutoRefine?: number;
+};
+/**
+ * Ask an LLM to compose a GraphSpec from a natural-language problem description.
+ *
+ * The LLM generates a GraphSpec (with templates + feedback), validated before
+ * returning. The spec is for human review before compilation via compileSpec().
+ *
+ * @param problem - Natural language problem description.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options and catalog description.
+ * @returns A validated GraphSpec.
+ * @throws On invalid LLM output or validation failure.
+ *
+ * @category patterns
+ */
+declare function llmCompose(problem: string, adapter: LLMAdapter, opts?: LLMComposeOptions): Promise<GraphSpec>;
+/** Options for {@link llmRefine}. */
+type LLMRefineOptions = LLMComposeOptions;
+/**
+ * Ask an LLM to modify an existing GraphSpec based on feedback or changed requirements.
+ *
+ * @param currentSpec - The current GraphSpec to modify.
+ * @param feedback - Natural language feedback or changed requirements.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options.
+ * @returns A new GraphSpec incorporating the feedback.
+ * @throws On invalid LLM output or validation failure.
+ *
+ * @category patterns
+ */
+declare function llmRefine(currentSpec: GraphSpec, feedback: string, adapter: LLMAdapter, opts?: LLMRefineOptions): Promise<GraphSpec>;
+
+type index_CatalogFnEntry = CatalogFnEntry;
+type index_CatalogSourceEntry = CatalogSourceEntry;
+type index_CompileSpecOptions = CompileSpecOptions;
+type index_ConfigFieldSchema = ConfigFieldSchema;
+type index_FnFactory = FnFactory;
+type index_GraphSpec = GraphSpec;
+type index_GraphSpecCatalog = GraphSpecCatalog;
+type index_GraphSpecFeedbackEdge = GraphSpecFeedbackEdge;
+type index_GraphSpecNode = GraphSpecNode;
+type index_GraphSpecTemplate = GraphSpecTemplate;
+type index_GraphSpecTemplateRef = GraphSpecTemplateRef;
+type index_GraphSpecValidation = GraphSpecValidation;
+type index_LLMComposeOptions = LLMComposeOptions;
+type index_LLMRefineOptions = LLMRefineOptions;
+type index_SourceFactory = SourceFactory;
+type index_SpecDiffEntry = SpecDiffEntry;
+type index_SpecDiffResult = SpecDiffResult;
+declare const index_compileSpec: typeof compileSpec;
+declare const index_decompileGraph: typeof decompileGraph;
+declare const index_extractFnFactory: typeof extractFnFactory;
+declare const index_extractSourceFactory: typeof extractSourceFactory;
+declare const index_generateCatalogPrompt: typeof generateCatalogPrompt;
+declare const index_isRichFnEntry: typeof isRichFnEntry;
+declare const index_isRichSourceEntry: typeof isRichSourceEntry;
+declare const index_llmCompose: typeof llmCompose;
+declare const index_llmRefine: typeof llmRefine;
+declare const index_specDiff: typeof specDiff;
+declare const index_validateSpec: typeof validateSpec;
+declare const index_validateSpecAgainstCatalog: typeof validateSpecAgainstCatalog;
+declare namespace index {
+  export { type index_CatalogFnEntry as CatalogFnEntry, type index_CatalogSourceEntry as CatalogSourceEntry, type index_CompileSpecOptions as CompileSpecOptions, type index_ConfigFieldSchema as ConfigFieldSchema, type index_FnFactory as FnFactory, type index_GraphSpec as GraphSpec, type index_GraphSpecCatalog as GraphSpecCatalog, type index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, type index_GraphSpecNode as GraphSpecNode, type index_GraphSpecTemplate as GraphSpecTemplate, type index_GraphSpecTemplateRef as GraphSpecTemplateRef, type index_GraphSpecValidation as GraphSpecValidation, type index_LLMComposeOptions as LLMComposeOptions, type index_LLMRefineOptions as LLMRefineOptions, type index_SourceFactory as SourceFactory, type index_SpecDiffEntry as SpecDiffEntry, type index_SpecDiffResult as SpecDiffResult, index_compileSpec as compileSpec, index_decompileGraph as decompileGraph, index_extractFnFactory as extractFnFactory, index_extractSourceFactory as extractSourceFactory, index_generateCatalogPrompt as generateCatalogPrompt, index_isRichFnEntry as isRichFnEntry, index_isRichSourceEntry as isRichSourceEntry, index_llmCompose as llmCompose, index_llmRefine as llmRefine, index_specDiff as specDiff, index_validateSpec as validateSpec, index_validateSpecAgainstCatalog as validateSpecAgainstCatalog };
+}
+
+export { type CatalogFnEntry as C, type FnFactory as F, type GraphSpec as G, type LLMComposeOptions as L, type SourceFactory as S, type CatalogSourceEntry as a, type ConfigFieldSchema as b, type GraphSpecCatalog as c, type GraphSpecFeedbackEdge as d, type GraphSpecNode as e, type GraphSpecTemplate as f, type GraphSpecTemplateRef as g, type GraphSpecValidation as h, index as i, type CompileSpecOptions as j, type LLMRefineOptions as k, type SpecDiffEntry as l, type SpecDiffResult as m, compileSpec as n, decompileGraph as o, extractFnFactory as p, extractSourceFactory as q, generateCatalogPrompt as r, isRichFnEntry as s, isRichSourceEntry as t, llmCompose as u, llmRefine as v, specDiff as w, validateSpec as x, validateSpecAgainstCatalog as y };

package/dist/{index-CUwyr1Kk.d.cts → index-rnwQly8X.d.cts}

@@ -1,5 +1,6 @@
-import { l as GraphReFlyConfig } from './node-C_IBuvX2.cjs';
-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-6tZ5jEzr.cjs';
+import { o as GraphReFlyConfig } from './node-Cc1TniY8.cjs';
+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-D48Qw9Cg.cjs';
+import { w as watchTopologyTree } from './topology-tree-DROUdq5B.cjs';
 
 /**
  * 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 };