@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/index-CS0LTlB8.d.cts

@@ -1,385 +0,0 @@
-import { D as DescribeNodeOutput } from './sugar-DQjFmVqb.cjs';
-import { N as Node } from './node-kK3CvTrR.cjs';
-import { G as Graph, b as GraphDescribeOutput } from './graph-CWvEUQAq.cjs';
-import { L as LLMAdapter } from './types-C0_yquda.cjs';
-
-/**
- * LLM graph composition (roadmap §8.3).
- *
- * Declarative GraphSpec schema + compiler/decompiler for graph topology.
- * The LLM designs graphs as JSON; `compileSpec` instantiates them;
- * `decompileSpec` extracts them back. Templates support reusable subgraph
- * patterns. Feedback edges express bounded cycles via §8.1 feedback().
- *
- * **Tier 1.5.3 Phase 3 (2026-04-27):** `GraphSpec` is a structural alias of
- * {@link GraphDescribeOutput} with two LLM-author-friendly extras
- * (`templates?` / `feedback?`). Per-node factory references are encoded in
- * `meta.factory` + `meta.factoryArgs` (no more `fn` / `source` / `config` /
- * `initial` fields). State node initial values live in
- * `meta.factoryArgs.initial` (state self-tags with
- * `factoryTag("state", { initial })`).
- *
- * @module
- */
-
-/**
- * A single node declaration in a GraphSpec — structural alias of
- * {@link DescribeNodeOutput}.
- *
- * Per-node factory provenance lives in `meta.factory` + `meta.factoryArgs`
- * (use {@link factoryTag} to stamp them at construction time). State node
- * initial values come through `meta.factoryArgs.initial` for tagged states,
- * with fallback to `value` (since spec projection retains state values).
- */
-type GraphSpecNode = DescribeNodeOutput;
-/** 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).
- *
- * Tier 1.5.3 Phase 3 (2026-04-27): structural alias of
- * {@link GraphDescribeOutput} extended with optional `templates` /
- * `feedback` fields for LLM-author convenience. Top-level `factory` /
- * `factoryArgs` (Phase 2.5 carry) ride along on every describe output.
- *
- * Round-trip property: `decompileSpec(g) === g.describe({ detail: "spec" })`
- * (modulo the small feedback-edge extraction sugar).
- */
-type GraphSpec = Omit<GraphDescribeOutput, "nodes" | "expand"> & {
-    /** Node declarations (keyed by node name). Either a structural describe entry or a template ref. */
-    nodes: Record<string, GraphSpecNode | GraphSpecTemplateRef>;
-    /** Reusable subgraph templates (LLM-author extra; not present in `describe()` output). */
-    templates?: Record<string, GraphSpecTemplate>;
-    /** Feedback edges (bounded cycles, LLM-author extra). */
-    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[];
-};
-/**
- * Top-level Graph factory — used when a spec was produced from a graph that
- * called `Graph.prototype.tagFactory(name, args)`. The catalog supplies a
- * function that takes the recorded `factoryArgs` (JSON-serializable subset)
- * and returns a fully-wired Graph. Runtime context (LLMAdapter instances,
- * callbacks, embedders) is captured by the closure — the args themselves are
- * a documentation fragment, not a complete construction recipe.
- *
- * Tier 1.5.3 Phase 2.5 (DG1=B, 2026-04-27).
- */
-type GraphFactory = (factoryArgs: unknown) => Graph;
-/**
- * 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.
- *
- * `graphFactories` (Tier 1.5.3 Phase 2.5) handles top-level Graph-returning
- * factories — when `spec.factory` matches a key, `compileSpec` delegates the
- * entire reconstruction to that factory.
- */
-type GraphSpecCatalog = {
-    fns?: Record<string, FnFactory | CatalogFnEntry>;
-    sources?: Record<string, SourceFactory | CatalogSourceEntry>;
-    graphFactories?: Record<string, GraphFactory>;
-};
-/** 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[];
-    /**
-     * Non-fatal advisories. Currently includes feedback edges whose `from`
-     * refers to an `effect` node (effects produce no DATA — the feedback
-     * counter will never advance). Always present (empty array when nothing
-     * is flagged) — symmetry with `errors` so callers can read
-     * `result.warnings.length` without a null check.
-     */
-    warnings: 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.
- *
- * **Effect-node feedback advisory (C24-3).** When a feedback edge's `from`
- * refers to an `effect` node, the validator flags it via `warnings` (not
- * `errors`) — effect nodes produce no DATA emission, so a feedback counter
- * targeting one will never advance. The spec compiles either way; the
- * advisory exists because the misconfiguration is silent at runtime
- * (counter at 0 forever) without it.
- */
-declare function validateSpec(spec: unknown): GraphSpecValidation;
-/** Options for {@link compileSpec}. */
-type CompileSpecOptions = {
-    /** Fn/source catalog for resolving named factories. */
-    catalog?: GraphSpecCatalog;
-    /**
-     * How to handle nodes whose `fn` / `source` is missing from the catalog.
-     * - `"placeholder"` (default): silently substitute identity passthroughs
-     *   (`producer(() => {})` / `derived(deps, vals => vals[0])`). Backward-
-     *   compatible — preserves the historical "soft compile" behavior.
-     * - `"warn"`: substitute placeholders AND log each missing entry via
-     *   `console.warn`, or via the `onWarn` callback if supplied.
-     * - `"error"`: collect every missing entry across the whole spec, then
-     *   throw an `Error` listing them all (no partial graph returned).
-     */
-    onMissing?: "error" | "warn" | "placeholder";
-    /** Custom warning sink. Used only when `onMissing === "warn"`. Defaults to `console.warn`. */
-    onWarn?: (message: string) => void;
-};
-/**
- * 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 {@link GraphSpec} from a running graph.
- *
- * Tier 1.5.3 Phase 3 (2026-04-27): thin projection over
- * `graph.describe({ detail: "spec" })`. The describe-output already carries
- * structural fields (`type`, `deps`, optional `value`) plus per-node
- * `meta.factory` / `meta.factoryArgs` for tagged factories and top-level
- * `factory` / `factoryArgs` for graph-level tags. The only sugar this helper
- * adds is a feedback-edge recovery scan over `meta.feedbackFrom` /
- * `meta.feedbackTo` companion fields stamped by the §8.1 `feedback()`
- * primitive.
- *
- * **Removed in Phase 3:** template fingerprinting / `_templateName` /
- * `_templateBind` recovery. Mounted subgraphs surface as nested `subname::*`
- * paths in `desc.nodes`; if you need the template-instantiation form, build
- * the spec by hand or read the meta companions directly.
- *
- * @param graph - Running graph to decompile.
- * @returns A GraphSpec representation.
- *
- * @category patterns
- */
-declare function decompileSpec(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_GraphFactory = GraphFactory;
-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_decompileSpec: typeof decompileSpec;
-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_GraphFactory as GraphFactory, 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_decompileSpec as decompileSpec, 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 GraphFactory as k, type LLMRefineOptions as l, type SpecDiffEntry as m, type SpecDiffResult as n, compileSpec as o, decompileSpec as p, extractFnFactory as q, extractSourceFactory as r, generateCatalogPrompt as s, isRichFnEntry as t, isRichSourceEntry as u, llmCompose as v, llmRefine as w, specDiff as x, validateSpec as y, validateSpecAgainstCatalog as z };

package/dist/index-CSOmP7xT.d.cts

@@ -1,291 +0,0 @@
-import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-CS0LTlB8.cjs';
-import { G as Graph, o as GraphNodeFactory, m as GraphDiffResult } from './graph-CWvEUQAq.cjs';
-import { KvStorageTier } from './extra/storage-tiers.cjs';
-
-/**
- * Surface: create a graph from a {@link GraphSpec} (§9.3-core).
- *
- * Thin wrapper over {@link compileSpec} that converts the two failure modes
- * ({@link validateSpec} structural errors, and catalog-aware validation
- * errors) into typed {@link SurfaceError} throws. Consumers are MCP/CLI
- * wrappers, not end-user graph code — those should import `compileSpec`
- * directly.
- *
- * @module
- */
-
-/** Options for {@link createGraph}. Same shape as {@link CompileSpecOptions}. */
-type CreateGraphOptions = CompileSpecOptions;
-/**
- * Build a {@link Graph} from a parsed {@link GraphSpec} with surface-layer
- * error typing.
- *
- * @throws {SurfaceError} `invalid-spec` for structural errors;
- *   `catalog-error` when fn/source names or config don't match the catalog.
- */
-declare function createGraph(spec: GraphSpec, opts?: CreateGraphOptions): Graph;
-
-/**
- * Typed errors for the surface layer (§9.3-core).
- *
- * The surface layer is consumed by `@graphrefly/mcp-server` and
- * `@graphrefly/cli`. Both have native error channels (MCP's `isError` flag,
- * CLI's exit codes), so surface functions throw a {@link SurfaceError}
- * carrying a structured code + details payload that wrappers can map to
- * their native shape. No `Result` envelope — keep the callsite idiom
- * `try/catch` and let each wrapper surface the error its own way.
- *
- * @module
- */
-/** Structured error codes emitted by the surface layer. JSON-safe. */
-type SurfaceErrorCode = "invalid-spec" | "graph-not-found" | "graph-exists" | "snapshot-not-found" | "node-not-found" | "reduce-timeout" | "catalog-error" | "restore-failed" | "snapshot-failed" | "tier-no-list" | "compose-not-configured" | "compose-failed" | "internal-error";
-/** JSON-safe shape surfaces should echo back through the wrapper. */
-interface SurfaceErrorPayload {
-    code: SurfaceErrorCode;
-    message: string;
-    /** Optional structured detail; must be JSON-safe. */
-    details?: Readonly<Record<string, unknown>>;
-}
-/**
- * Thrown by surface layer functions on failure. `code` is the stable
- * machine-readable identifier; `details` carries structured context
- * (e.g. `validateSpec` errors, missing path name). Both fields round-trip
- * through `toJSON()` for wrappers that serialize errors over the wire.
- */
-declare class SurfaceError extends Error {
-    readonly code: SurfaceErrorCode;
-    readonly details?: Readonly<Record<string, unknown>>;
-    constructor(code: SurfaceErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
-    /**
-     * JSON-safe payload for wire serialization. Defensively validates
-     * `details` — if it can't be round-tripped through `JSON.stringify`
-     * (cyclic refs, `BigInt`, `Error` instance not pre-toJSON'd), the
-     * payload falls back to `{code, message}` only rather than crashing
-     * the MCP/CLI wrapper when it serializes this error onto the wire.
-     */
-    toJSON(): SurfaceErrorPayload;
-}
-/** Wrap any thrown value as a SurfaceError. Idempotent on existing SurfaceError. */
-declare function asSurfaceError(err: unknown, fallbackCode?: SurfaceErrorCode): SurfaceError;
-
-/**
- * Surface: one-shot `input → pipeline → output` (§9.3-core).
- *
- * `runReduction` compiles a {@link GraphSpec}, pushes an input value to a
- * named state node, awaits the first post-push DATA emission on a named
- * output, then disposes the graph. Stateless per call — no graphId, no
- * registry.
- *
- * Named `runReduction` (not `reduce`) to avoid collision with the
- * reactive {@link reduce} operator in `extra/operators.ts`. The MCP tool
- * name (`graphrefly_reduce`) and CLI subcommand (`graphrefly reduce`) use
- * the short form; the library export carries the verb.
- *
- * The subscribe-before-push ordering is deliberate. `graph.set` propagates
- * synchronously for sync derived/operator chains; for async sources
- * (`fromPromise`, `fromAsyncIter`, LLM adapters) the first post-push DATA
- * arrives on a later tick. Subscribing before the push catches both, and
- * skipping the priming push-on-subscribe emission avoids resolving with the
- * stale pre-push cache (spec §2.2).
- *
- * @module
- */
-
-/** Options for {@link reduce}. */
-interface ReduceOptions {
-    /** Fn/source catalog for {@link createGraph}. */
-    catalog?: GraphSpecCatalog;
-    /** Path of the state node that receives the input. Default `"input"`. */
-    inputPath?: string;
-    /** Path of the node whose first post-push DATA is the result. Default `"output"`. */
-    outputPath?: string;
-    /** Hard deadline in milliseconds. Default `30_000`. */
-    timeoutMs?: number;
-}
-/**
- * Run a spec as a one-shot reduction: `input → graph → output`.
- *
- * Resolves on the first `[DATA, v]` **or** `[RESOLVED]` emitted by
- * `outputPath` after the input push. The RESOLVED path handles spec
- * §1.3.3 equals-substitution (output recomputed to a value equal to its
- * cache, so the graph skips the DATA push) by returning `outputNode.cache`
- * — the caller always gets the settled value, never hangs on idempotent
- * inputs.
- *
- * @throws {SurfaceError} `invalid-spec` / `catalog-error` (propagated from
- *   {@link createGraph}), `node-not-found` when `inputPath`/`outputPath`
- *   can't be resolved, `reduce-timeout` when `timeoutMs` elapses without
- *   a post-push emission, or the ERROR payload from the graph re-thrown
- *   as `internal-error`.
- */
-declare function runReduction(spec: GraphSpec, input: unknown, opts?: ReduceOptions): Promise<unknown>;
-
-/**
- * Surface: snapshot save/restore/diff/list over {@link KvStorageTier} (§9.3-core).
- *
- * One-shot snapshot management for stateless callers (MCP tools, CLI
- * commands) layered on the existing multi-tier auto-checkpoint substrate.
- * A saved snapshot is a `mode: "full"` {@link GraphCheckpointRecord} with
- * `seq: 0` — byte-identical to the baseline anchor
- * {@link Graph.attachSnapshotStorage} writes on its first flush. An
- * auto-checkpointed graph can therefore be restored through this surface,
- * and a surface-saved snapshot can be picked up by `attachSnapshotStorage({
- * autoRestore: true })`.
- *
- * The wire envelope stays at {@link SNAPSHOT_WIRE_VERSION}; no new format.
- *
- * @module
- */
-
-/**
- * Current envelope version. Re-exported from `graph.ts` so the one-shot
- * surface path and `Graph.attachSnapshotStorage` write byte-identical
- * `format_version` fields — no silent wire drift.
- */
-declare const SNAPSHOT_WIRE_VERSION = 1;
-/** Shape returned by {@link saveSnapshot}. */
-interface SaveSnapshotResult {
-    snapshotId: string;
-    timestamp_ns: number;
-}
-/** Options for {@link restoreSnapshot}. */
-interface RestoreSnapshotOptions {
-    /** Passthrough to `Graph.fromSnapshot`. First matching pattern wins. */
-    factories?: Record<string, GraphNodeFactory>;
-}
-/**
- * Write a graph's current state as a one-shot `mode: "full"` record.
- *
- * Uses the same {@link GraphCheckpointRecord} envelope as
- * {@link Graph.attachSnapshotStorage} so the two persistence paths interoperate.
- *
- * @throws {SurfaceError} `snapshot-failed` when the tier's `save` throws.
- */
-declare function saveSnapshot(graph: Graph, snapshotId: string, tier: KvStorageTier): Promise<SaveSnapshotResult>;
-/**
- * Load a snapshot from a tier and materialize it as a new {@link Graph}.
- *
- * Uses {@link Graph.fromSnapshot} to reconstruct topology; pass
- * `factories` when the graph includes non-state nodes that the default
- * hydrator can't rebuild on its own.
- *
- * **Requires a `mode: "full"` record.** Surface-written snapshots from
- * {@link saveSnapshot} always qualify. Records written by
- * {@link Graph.attachSnapshotStorage} with `compactEvery > 1` may be
- * `mode: "diff"` between compacts — those throw `restore-failed` until
- * the tier's next compact flush (or until Phase 8.7 WAL replay lands).
- * If you need interop during development, either call
- * {@link saveSnapshot} explicitly (always full) or configure
- * `attachSnapshotStorage({compactEvery: 1})`.
- *
- * @throws {SurfaceError} `snapshot-not-found` on miss; `restore-failed`
- *   when the payload shape doesn't match, when the record is
- *   `mode: "diff"`, or when `Graph.fromSnapshot` rejects.
- */
-declare function restoreSnapshot(snapshotId: string, tier: KvStorageTier, opts?: RestoreSnapshotOptions): Promise<Graph>;
-/**
- * Load two snapshots and compute a {@link GraphDiffResult} via static
- * {@link Graph.diff}. Returns the audit shape (structural + value diff,
- * no payload); use {@link diffForWAL} directly for WAL-oriented diffs.
- *
- * @throws {SurfaceError} `snapshot-not-found` on either miss.
- */
-declare function diffSnapshots(snapshotIdA: string, snapshotIdB: string, tier: KvStorageTier): Promise<GraphDiffResult>;
-/**
- * Enumerate snapshot ids on a tier.
- *
- * Only keys written by {@link saveSnapshot} are returned. Surface-written
- * records are stored under the `"snapshot:"` key prefix and decoded back to
- * the caller-visible id before being returned — other keys on the same tier
- * (notably `attachSnapshotStorage` baseline/WAL keys written under `graph.name`) are
- * filtered out automatically. This lets a single tier back both the surface
- * and `attachSnapshotStorage` without leaking graph names through `listSnapshots`.
- *
- * @param tier — the storage tier to enumerate.
- * @param opts.includeUnprefixed — when `true`, also return keys that are
- *   NOT under the namespacing prefix. Off by default; set this when reading
- *   pre-namespacing snapshot sets.
- *
- *   **Caveat:** when a tier is shared with {@link Graph.attachSnapshotStorage}, its
- *   auto-checkpoint baseline + WAL keys (written under `graph.name`) are
- *   unprefixed. Calling with `includeUnprefixed: true` returns those keys
- *   alongside surface snapshots — and subsequent `restoreSnapshot` /
- *   `deleteSnapshot` will operate on them via the fallback-lookup path,
- *   potentially overwriting or deleting live auto-checkpoint state. Use
- *   `includeUnprefixed` only against tiers you know are NOT shared with
- *   `attachSnapshotStorage`, or follow up with a predicate filter to separate
- *   ids you own from ones owned by other subsystems.
- *
- * @throws {SurfaceError} `tier-no-list` when the tier does not implement
- *   the optional `list()` method. Check `typeof tier.list === "function"`
- *   before calling if you want to branch on capability.
- */
-declare function listSnapshots(tier: KvStorageTier, opts?: {
-    includeUnprefixed?: boolean;
-}): Promise<readonly string[]>;
-/**
- * Delete a snapshot from a tier.
- *
- * Silent on miss (clear semantics). `tier.clear` is optional — throws
- * `snapshot-failed` when the tier is append-only.
- *
- * @throws {SurfaceError} `snapshot-failed` when `clear` is unsupported
- *   or throws.
- */
-declare function deleteSnapshot(snapshotId: string, tier: KvStorageTier): Promise<void>;
-
-/**
- * Surface layer (§9.3-core) — shared, JSON-safe operations consumed by
- * `@graphrefly/mcp-server` and `@graphrefly/cli`.
- *
- * The surface is a thin projection of existing Graph APIs (`describe`,
- * `observe`, `explain`, `snapshot`, `restore`, static `diff`), plus two
- * genuinely new operations:
- *
- * 1. {@link createGraph} — `compileSpec` wrapped with typed surface errors.
- * 2. {@link reduce} — one-shot `input → pipeline → output`.
- *
- * Snapshot persistence reuses the {@link KvStorageTier} substrate introduced
- * for `Graph.attachSnapshotStorage`, so one-shot snapshots and auto-checkpoints
- * share the {@link GraphCheckpointRecord} envelope. No new wire format.
- *
- * Errors throw as {@link SurfaceError} — wrappers map to their native
- * error channel (MCP `isError`, CLI exit code). No `Result<T, E>` wrapper.
- *
- * @module
- */
-
-declare const index_CatalogFnEntry: typeof CatalogFnEntry;
-declare const index_CatalogSourceEntry: typeof CatalogSourceEntry;
-declare const index_ConfigFieldSchema: typeof ConfigFieldSchema;
-type index_CreateGraphOptions = CreateGraphOptions;
-declare const index_FnFactory: typeof FnFactory;
-declare const index_GraphSpec: typeof GraphSpec;
-declare const index_GraphSpecCatalog: typeof GraphSpecCatalog;
-declare const index_GraphSpecFeedbackEdge: typeof GraphSpecFeedbackEdge;
-declare const index_GraphSpecNode: typeof GraphSpecNode;
-declare const index_GraphSpecTemplate: typeof GraphSpecTemplate;
-declare const index_GraphSpecTemplateRef: typeof GraphSpecTemplateRef;
-declare const index_GraphSpecValidation: typeof GraphSpecValidation;
-type index_ReduceOptions = ReduceOptions;
-type index_RestoreSnapshotOptions = RestoreSnapshotOptions;
-declare const index_SNAPSHOT_WIRE_VERSION: typeof SNAPSHOT_WIRE_VERSION;
-type index_SaveSnapshotResult = SaveSnapshotResult;
-declare const index_SourceFactory: typeof SourceFactory;
-type index_SurfaceError = SurfaceError;
-declare const index_SurfaceError: typeof SurfaceError;
-type index_SurfaceErrorCode = SurfaceErrorCode;
-type index_SurfaceErrorPayload = SurfaceErrorPayload;
-declare const index_asSurfaceError: typeof asSurfaceError;
-declare const index_createGraph: typeof createGraph;
-declare const index_deleteSnapshot: typeof deleteSnapshot;
-declare const index_diffSnapshots: typeof diffSnapshots;
-declare const index_listSnapshots: typeof listSnapshots;
-declare const index_restoreSnapshot: typeof restoreSnapshot;
-declare const index_runReduction: typeof runReduction;
-declare const index_saveSnapshot: typeof saveSnapshot;
-declare namespace index {
-  export { index_CatalogFnEntry as CatalogFnEntry, index_CatalogSourceEntry as CatalogSourceEntry, index_ConfigFieldSchema as ConfigFieldSchema, type index_CreateGraphOptions as CreateGraphOptions, index_FnFactory as FnFactory, index_GraphSpec as GraphSpec, index_GraphSpecCatalog as GraphSpecCatalog, index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, index_GraphSpecNode as GraphSpecNode, index_GraphSpecTemplate as GraphSpecTemplate, index_GraphSpecTemplateRef as GraphSpecTemplateRef, index_GraphSpecValidation as GraphSpecValidation, type index_ReduceOptions as ReduceOptions, type index_RestoreSnapshotOptions as RestoreSnapshotOptions, index_SNAPSHOT_WIRE_VERSION as SNAPSHOT_WIRE_VERSION, type index_SaveSnapshotResult as SaveSnapshotResult, index_SourceFactory as SourceFactory, index_SurfaceError as SurfaceError, type index_SurfaceErrorCode as SurfaceErrorCode, type index_SurfaceErrorPayload as SurfaceErrorPayload, index_asSurfaceError as asSurfaceError, index_createGraph as createGraph, index_deleteSnapshot as deleteSnapshot, index_diffSnapshots as diffSnapshots, index_listSnapshots as listSnapshots, index_restoreSnapshot as restoreSnapshot, index_runReduction as runReduction, index_saveSnapshot as saveSnapshot };
-}
-
-export { type CreateGraphOptions as C, type ReduceOptions as R, SNAPSHOT_WIRE_VERSION as S, type RestoreSnapshotOptions as a, type SaveSnapshotResult as b, SurfaceError as c, type SurfaceErrorCode as d, type SurfaceErrorPayload as e, asSurfaceError as f, createGraph as g, deleteSnapshot as h, diffSnapshots as i, runReduction as j, index as k, listSnapshots as l, restoreSnapshot as r, saveSnapshot as s };