@graphrefly/graphrefly 0.43.0 → 0.45.0

package/dist/index-BTQtTb_H.d.cts

@@ -1,301 +0,0 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
-import { G as Graph, a as GraphOptions } from './graph-C4SHb3Ly.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-B00laMSQ.cjs';
-import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
-
-type TopicOptions = {
-    graph?: GraphOptions;
-    /** Bounded retention; default 1024 per cross-cutting policy (Audit 2/4). */
-    retainedLimit?: number;
-};
-declare class TopicGraph<T> extends Graph {
-    private readonly _log;
-    private readonly _publishImpl;
-    readonly events: Node<readonly T[]>;
-    /**
-     * Most recently published value, or `null` when the topic has no entries
-     * yet. Spec §5.12 reserves `undefined` as the protocol-internal "never
-     * sent DATA" sentinel — `null` is the idiomatic "empty / no value" signal
-     * for domain nodes. F7.
-     *
-     * **Caveat when `T` itself includes `null`** (e.g., `topic<number | null>`):
-     * `latest === null` is ambiguous — it could mean "no publish yet" OR "a
-     * `null` value was published". Use {@link hasLatest} to disambiguate, or
-     * observe {@link events} directly and track length yourself.
-     */
-    readonly latest: Node<T | null>;
-    /**
-     * Reactive `true` once the topic has at least one published entry.
-     * Disambiguates "`null` never published" from "`null` was published" when
-     * `T` includes `null`.
-     */
-    readonly hasLatest: Node<boolean>;
-    constructor(name: string, opts?: TopicOptions);
-    publish(value: T): void;
-    /**
-     * Wire one or more append-log storage tiers (Audit 4). Each tier receives
-     * appended events per wave; rollback honors the wave-as-transaction model.
-     *
-     * Named `attachEventStorage` (not `attachStorage`) to avoid colliding with
-     * the inherited {@link Graph.attachSnapshotStorage} which takes the
-     * snapshot-based `StorageTier[]` shape.
-     *
-     * @returns Disposer.
-     */
-    attachEventStorage(tiers: readonly AppendLogStorageTier<T>[]): () => void;
-    retained(): readonly T[];
-    /** Internal log bundle — used by TopicBridgeGraph for `attach`. */
-    get _logBundle(): ReactiveLogBundle<T>;
-}
-type SubscriptionOptions = {
-    graph?: GraphOptions;
-    /**
-     * Starting cursor position.
-     * @deprecated Use `from` instead.
-     */
-    cursor?: number;
-    /**
-     * Starting position for the subscription.
-     * - `"retained"` (default) — cursor starts at 0; consumer sees all retained history.
-     * - `"now"` — cursor starts at current topic length; consumer ignores history.
-     * - `number` — explicit cursor position.
-     */
-    from?: "now" | "retained" | number;
-    /**
-     * When this signal node emits DATA, the subscription auto-advances cursor
-     * to current `available.length`. Useful for "ack everything when X happens"
-     * patterns. The reactive edge `advanceOn → cursor` is visible in `explain()`.
-     */
-    advanceOn?: Node<unknown>;
-};
-/** Result of {@link SubscriptionGraph.pullAndAck}. */
-type PullAndAckResult<T> = {
-    items: readonly T[];
-    cursor: number;
-};
-declare class SubscriptionGraph<T> extends Graph {
-    readonly cursor: Node<number>;
-    readonly available: Node<readonly T[]>;
-    /**
-     * Reference to the upstream topic graph. Intentionally NOT mounted
-     * under this subscription: a subscription is a VIEW over an
-     * externally-owned topic. Double-mounting (e.g. hub-owned topic +
-     * sub-mount here) would make either-side teardown leave the other
-     * holding a dead reference. Node-level `derived([topicEvents], …)`
-     * still wires the data dependency across graph boundaries. D1(e).
-     */
-    readonly topic: TopicGraph<T>;
-    private _disposed;
-    private readonly _ackImpl;
-    private readonly _pullAndAckImpl;
-    constructor(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions);
-    ack(count?: number): number;
-    pull(limit?: number): readonly T[];
-    /**
-     * Atomic pull-and-acknowledge. Returns `{ items, cursor }` where `cursor`
-     * is the new cursor position after advancing. Under single-threaded JS the
-     * snapshot and advance are atomic; PY callers use a per-subscription Lock.
-     *
-     * Replaces `pull(limit, { ack: true })`.
-     */
-    pullAndAck(limit?: number): PullAndAckResult<T>;
-    /**
-     * Release internal subscriptions and mark the subscription torn-down.
-     * Subsequent `pull`, `pullAndAck`, `ack` return empty / current cursor.
-     * Emits COMPLETE on `cursor` so derived consumers (e.g. `available`) see
-     * the termination signal. Also drains `addDisposer` callbacks (including
-     * the `keepalive(advancePump)` subscription) so no keepalive leak occurs.
-     */
-    dispose(): void;
-}
-type TopicBridgeOptions<TIn, TOut> = {
-    graph?: GraphOptions;
-    cursor?: number;
-    maxPerPump?: number;
-    /**
-     * Optional transform/filter applied to each item before republishing.
-     *
-     * **At-most-once with silent drop:** when `map` returns `undefined`, the
-     * input is consumed from the source cursor but NOT republished. Filtered
-     * items are not retained for retry. If you need filter-with-retry
-     * semantics, do the filtering in a downstream subscription on the bridged
-     * output rather than in the `map` function.
-     */
-    map?: (value: TIn) => TOut | undefined;
-};
-declare class TopicBridgeGraph<TIn, TOut = TIn> extends Graph {
-    private readonly _sourceSub;
-    readonly bridgedCount: Node<number>;
-    /**
-     * Emits each mapped batch as DATA — gives downstream observers a reactive
-     * stream of bridged values. Also the link target for `target._log.attach`.
-     */
-    readonly output: Node<readonly TOut[]>;
-    constructor(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>);
-}
-/**
- * Private pure data structure managing a named set of {@link TopicGraph}
- * instances. Extracted from {@link MessagingHubGraph} for separation of
- * concerns (B.2 Unit 14 lock: D — split into TopicRegistry + facade).
- *
- * Reusable if other domain consumers (e.g. cqrs.eventLogs) want a shared
- * topic registry later.
- *
- * @internal
- */
-declare class TopicRegistry {
-    private readonly _map;
-    /** Reactive monotonic version counter. Advances on topic create/remove. */
-    readonly version: Node<number>;
-    constructor(versionNode: Node<number>);
-    get size(): number;
-    has(name: string): boolean;
-    get<T>(name: string): TopicGraph<T> | undefined;
-    set<T>(name: string, t: TopicGraph<T>): void;
-    delete(name: string): boolean;
-    keys(): IterableIterator<string>;
-}
-type MessagingHubOptions = {
-    graph?: GraphOptions;
-    /**
-     * Default `TopicOptions` applied to every topic created via `topic(name)`
-     * without explicit options. Per-call opts override. Default: `{}`
-     * (unbounded retention per topic unless `retainedLimit` is set per call).
-     */
-    defaultTopicOptions?: TopicOptions;
-};
-/**
- * Lazy Pulsar-inspired topic registry. Manages a named set of {@link TopicGraph}
- * instances with retention + cursor semantics. Topics are created on first
- * access; `removeTopic(name)` unmounts and tears down via {@link Graph.remove}.
- *
- * Internally delegates to {@link TopicRegistry} for topic map management
- * (B.2 Unit 14 lock: D facade split).
- *
- * **Relationship to `pubsub()` in `src/extra/pubsub.ts`:** `pubsub` is a
- * lightweight last-value state hub (no retention, no cursors). `MessagingHubGraph`
- * is the full messaging hub — retained message logs, cursor-based subscriptions,
- * and pattern-layer lifecycle management.
- *
- * @category patterns
- */
-declare class MessagingHubGraph extends Graph {
-    private readonly _registry;
-    /** Reactive monotonic version counter — advances on topic create/remove. */
-    readonly version: Node<number>;
-    private readonly _defaultTopicOptions;
-    private readonly _removeTopicImpl;
-    constructor(name: string, opts?: MessagingHubOptions);
-    /** Number of topics currently in the hub. */
-    get size(): number;
-    /** Checks topic existence without creating. */
-    has(name: string): boolean;
-    /** Iterator over topic names. */
-    topicNames(): IterableIterator<string>;
-    /**
-     * Returns the {@link TopicGraph} for `name`, creating lazily on first call.
-     * Subsequent calls with the same name return the same instance (options on
-     * repeat calls are ignored — the topic is already configured).
-     */
-    topic<T = unknown>(name: string, opts?: TopicOptions): TopicGraph<T>;
-    /**
-     * Publishes a value to the topic, lazily creating it on first publish.
-     *
-     * **Late-subscriber caveat:** the topic is created lazily, so subscribers
-     * that attach AFTER a publish only see the retained window (governed by
-     * `retainedLimit` on `TopicOptions` / `defaultTopicOptions`). If
-     * `retainedLimit === 0` is set explicitly, early publishes are
-     * effectively dropped — prefer an unset `retainedLimit` (unbounded
-     * retention) or subscribe before publishing when late-subscribers matter.
-     */
-    publish<T = unknown>(name: string, value: T): void;
-    /**
-     * Bulk publish — issues all publishes inside one outer batch. New topics
-     * are created on demand. No-op if `entries` yields nothing.
-     *
-     * **Iterable consumption (F6):** `entries` is consumed once (single-pass)
-     * INSIDE the batch frame. If the iterator throws mid-way, the batch is
-     * discarded and NO publishes are visible to subscribers (all-or-nothing).
-     * Pass an array or `Set` for multi-shot callers.
-     */
-    publishMany(entries: Iterable<[string, unknown]>): void;
-    /**
-     * Creates a {@link SubscriptionGraph} over a named topic. The topic is
-     * lazily created if missing. Subscription lifecycle is owned by the caller —
-     * the hub does NOT mount the subscription.
-     *
-     * @param subName - Local name for the subscription graph.
-     * @param topicName - Hub topic to subscribe to.
-     * @param opts - `SubscriptionOptions` (initial cursor, etc.).
-     */
-    subscribe<T = unknown>(subName: string, topicName: string, opts?: SubscriptionOptions): SubscriptionGraph<T>;
-    /**
-     * Unmounts and tears down the topic's graph. Returns `true` if the topic
-     * existed. Subscribers receive `TEARDOWN` via {@link Graph.remove}.
-     *
-     * **Closure-state caveat:** the registry mutation (`_registry.delete`) and
-     * version bump happen in a `try/finally`, so registry/version converge to
-     * a consistent state even when {@link Graph.remove} throws. `lightMutation`
-     * does not roll back this mutation on throw — `Map.delete` on closure
-     * state is invisible to any batch frame. The pre-existing try/finally is
-     * load-bearing for that invariant.
-     */
-    removeTopic(name: string): boolean;
-}
-/**
- * Creates a Pulsar-inspired topic graph (append-only retained stream + latest value).
- */
-declare function topic<T>(name: string, opts?: TopicOptions): TopicGraph<T>;
-/**
- * Creates a lazy Pulsar-inspired messaging hub. Topics are created on first access
- * via `hub.topic(name)`; `hub.publish(name, value)` shortcuts through the registry.
- *
- * @example
- * ```ts
- * import { messagingHub } from "@graphrefly/graphrefly/patterns/messaging";
- *
- * const hub = messagingHub("main", { defaultTopicOptions: { retainedLimit: 256 } });
- * hub.publish("orders", { id: 1 });
- * hub.publishMany([["shipments", { id: 1 }], ["orders", { id: 2 }]]);
- * const sub = hub.subscribe("orders-worker", "orders", { cursor: 0 });
- * ```
- */
-declare function messagingHub(name: string, opts?: MessagingHubOptions): MessagingHubGraph;
-/**
- * Creates a cursor-based subscription graph over a topic.
- */
-declare function subscription<T>(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions): SubscriptionGraph<T>;
-/**
- * Creates an autonomous cursor-based topic relay graph.
- *
- * When `opts.map` is provided, items where `map` returns `undefined` are
- * consumed from the source cursor but NOT republished (at-most-once with
- * silent drop). For filter-with-retry semantics, apply the filter in a
- * downstream subscription on the bridge's `output` node instead.
- */
-declare function topicBridge<TIn, TOut = TIn>(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>): TopicBridgeGraph<TIn, TOut>;
-
-type index_MessagingHubGraph = MessagingHubGraph;
-declare const index_MessagingHubGraph: typeof MessagingHubGraph;
-type index_MessagingHubOptions = MessagingHubOptions;
-type index_PullAndAckResult<T> = PullAndAckResult<T>;
-type index_SubscriptionGraph<T> = SubscriptionGraph<T>;
-declare const index_SubscriptionGraph: typeof SubscriptionGraph;
-type index_SubscriptionOptions = SubscriptionOptions;
-type index_TopicBridgeGraph<TIn, TOut = TIn> = TopicBridgeGraph<TIn, TOut>;
-declare const index_TopicBridgeGraph: typeof TopicBridgeGraph;
-type index_TopicBridgeOptions<TIn, TOut> = TopicBridgeOptions<TIn, TOut>;
-type index_TopicGraph<T> = TopicGraph<T>;
-declare const index_TopicGraph: typeof TopicGraph;
-type index_TopicOptions = TopicOptions;
-type index_TopicRegistry = TopicRegistry;
-declare const index_TopicRegistry: typeof TopicRegistry;
-declare const index_messagingHub: typeof messagingHub;
-declare const index_subscription: typeof subscription;
-declare const index_topic: typeof topic;
-declare const index_topicBridge: typeof topicBridge;
-declare namespace index {
-  export { index_MessagingHubGraph as MessagingHubGraph, type index_MessagingHubOptions as MessagingHubOptions, type index_PullAndAckResult as PullAndAckResult, index_SubscriptionGraph as SubscriptionGraph, type index_SubscriptionOptions as SubscriptionOptions, index_TopicBridgeGraph as TopicBridgeGraph, type index_TopicBridgeOptions as TopicBridgeOptions, index_TopicGraph as TopicGraph, type index_TopicOptions as TopicOptions, index_TopicRegistry as TopicRegistry, index_messagingHub as messagingHub, index_subscription as subscription, index_topic as topic, index_topicBridge as topicBridge };
-}
-
-export { MessagingHubGraph as M, type PullAndAckResult as P, SubscriptionGraph as S, TopicGraph as T, type MessagingHubOptions as a, type SubscriptionOptions as b, TopicBridgeGraph as c, type TopicBridgeOptions as d, type TopicOptions as e, TopicRegistry as f, topicBridge as g, index as i, messagingHub as m, subscription as s, topic as t };

package/dist/index-BVpm6noz.d.cts

@@ -1,36 +0,0 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
-
-/** Solid accessor function — returns current value when called. */
-type Accessor<T> = () => T;
-/**
- * Subscribe to a `Node<T>` as a Solid signal. Auto-cleans up with the owning scope.
- * Subscription lifecycle is tied to Solid scope cleanup (not node terminal messages).
- */
-declare function useSubscribe<T>(node: Node<T>): Accessor<T | undefined | null>;
-/**
- * Bind a writable `Node<T>` as a Solid resource tuple `[accessor, setter]`.
- * Setter always forwards `[[DIRTY], [DATA, value]]`, including `value === undefined`.
- * Subscription lifecycle is tied to Solid scope cleanup (not node terminal messages).
- */
-declare function useStore<T>(node: Node<T>): [Accessor<T | undefined | null>, (v: T) => void];
-/** Maps a key to an object of nodes. Used by `useSubscribeRecord`. */
-type NodeFactory<K, R extends Record<string, any>> = (key: K) => {
-    [P in keyof R]: Node<R[P]>;
-};
-/**
- * Subscribe to a dynamic set of keyed node records as a Solid accessor.
- * Re-subscribes all per-key fields whenever `keys` changes.
- * Key re-sync is gated to settled batches (`messageTier >= 3`) to avoid DIRTY-phase churn.
- */
-declare function useSubscribeRecord<K extends string, R extends Record<string, any>>(keysNode: Node<K[]>, factory: NodeFactory<K, R>): Accessor<Record<K, R>>;
-
-type index_Accessor<T> = Accessor<T>;
-type index_NodeFactory<K, R extends Record<string, any>> = NodeFactory<K, R>;
-declare const index_useStore: typeof useStore;
-declare const index_useSubscribe: typeof useSubscribe;
-declare const index_useSubscribeRecord: typeof useSubscribeRecord;
-declare namespace index {
-  export { type index_Accessor as Accessor, type index_NodeFactory as NodeFactory, index_useStore as useStore, index_useSubscribe as useSubscribe, index_useSubscribeRecord as useSubscribeRecord };
-}
-
-export { type Accessor as A, type NodeFactory as N, useSubscribe as a, useSubscribeRecord as b, index as i, useStore as u };

package/dist/index-Bc41FuHp.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-Du7u1lSf.cjs';
-import { G as Graph, o as GraphNodeFactory, m as GraphDiffResult } from './graph-C4SHb3Ly.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 };