@graphrefly/ts 0.0.0

package/dist/graph-s23RbbFO.d.cts

@@ -0,0 +1,666 @@
+import { BatchCtx } from './core/index.cjs';
+import { q as NodeVersionJson, B as Status, N as Node, m as NodeFn, D as Dispatcher, u as NodeVersioningPolicy, C as Ctx, n as NodeOptions, E as EnvironmentDrivers } from './types-bNMSWKqF.cjs';
+import { S as StrictJsonObject, b as StrictJsonValue } from './codec-BB7p8fJc.cjs';
+import { G as GraphTopologyEdge, e as GraphTopologySnapshot, b as DescribeOpts, c as DescribeSnapshot } from './describe-Ciu8SUnN.cjs';
+import { M as Message } from './messages-BZqrGGm1.cjs';
+
+/**
+ * GraphBlueprint first slice (D173/D177).
+ *
+ * A blueprint is read-only audit/collaboration evidence over graph.topology(). It is not an
+ * authoring spec, checkpoint, restore input, hash owner, or collaboration ownership artifact.
+ */
+
+declare const GRAPH_BLUEPRINT_VERSION: "graphrefly.blueprint.v1";
+type GraphBlueprintJson = StrictJsonValue;
+type GraphBlueprintProvenance = StrictJsonObject;
+interface NormalizedGraphTopologyNode {
+    readonly id: string;
+    readonly name?: string;
+    readonly factory: string;
+    readonly deps: readonly string[];
+    readonly meta?: Readonly<Record<string, GraphBlueprintJson>>;
+}
+interface NormalizedGraphTopologySnapshot {
+    readonly name?: string;
+    readonly nodes: readonly NormalizedGraphTopologyNode[];
+    readonly edges: readonly GraphTopologyEdge[];
+    readonly subgraphs?: readonly NormalizedGraphTopologySnapshot[];
+}
+type GraphBlueprintDiagnosticCode = "dangling-dep" | "duplicate-node-id" | "island-node";
+interface GraphBlueprintDiagnosticIssue {
+    readonly severity: "warning" | "error";
+    readonly code: GraphBlueprintDiagnosticCode;
+    readonly message: string;
+    readonly nodeId?: string;
+    readonly from?: string;
+    readonly to?: string;
+}
+interface GraphBlueprintDiagnostics {
+    readonly ok: boolean;
+    readonly issues: readonly GraphBlueprintDiagnosticIssue[];
+}
+type GraphBlueprintHashInput = "strictCanonicalTopologyBytes";
+interface GraphBlueprintHash {
+    readonly kind: "topology";
+    readonly algorithm: string;
+    readonly input: GraphBlueprintHashInput;
+    readonly value: string;
+}
+interface GraphBlueprintHashOptions {
+    readonly algorithm: string;
+    readonly hash: (bytes: Uint8Array) => string | Promise<string>;
+}
+interface GraphBlueprint {
+    readonly version: typeof GRAPH_BLUEPRINT_VERSION;
+    readonly topology: NormalizedGraphTopologySnapshot;
+    readonly diagnostics?: GraphBlueprintDiagnostics;
+    readonly provenance?: GraphBlueprintProvenance;
+    readonly hash?: GraphBlueprintHash;
+}
+interface GraphBlueprintOptions {
+    /** Include graph-local structural diagnostics over the normalized topology. */
+    readonly diagnostics?: boolean;
+    /** Caller-supplied provenance only; environment enrichment stays outside Graph core (D177). */
+    readonly provenance?: GraphBlueprintProvenance;
+}
+declare function normalizeTopology(snapshot: GraphTopologySnapshot | NormalizedGraphTopologySnapshot): NormalizedGraphTopologySnapshot;
+declare function canonicalTopologyJson(snapshot: GraphTopologySnapshot | NormalizedGraphTopologySnapshot): string;
+declare function canonicalTopologyBytes(snapshot: GraphTopologySnapshot | NormalizedGraphTopologySnapshot): Uint8Array;
+declare function withBlueprintHash(blueprint: GraphBlueprint, options: GraphBlueprintHashOptions): GraphBlueprint | Promise<GraphBlueprint>;
+declare function withBlueprintProvenance(blueprint: GraphBlueprint, provenance: GraphBlueprintProvenance): GraphBlueprint;
+declare function graphBlueprintDiagnostics(topology: NormalizedGraphTopologySnapshot): GraphBlueprintDiagnostics;
+
+/**
+ * Graph checkpoint public data shape (D83/D86/D90/D116).
+ *
+ * Checkpoint is a graph lifecycle snapshot: strict-JSON-compatible data, no storage I/O,
+ * no observe-log replay, and no restore runtime in this first TS slice.
+ */
+
+declare const GRAPH_CHECKPOINT_VERSION: "graphrefly.checkpoint.v1";
+type GraphCheckpointVersion = typeof GRAPH_CHECKPOINT_VERSION;
+type GraphCheckpointJson = StrictJsonValue;
+type GraphCheckpointValue = {
+    kind: "SENTINEL";
+} | {
+    kind: "DATA";
+    data: GraphCheckpointJson;
+};
+type GraphCheckpointTerminal = {
+    kind: "none";
+} | {
+    kind: "COMPLETE";
+} | {
+    kind: "ERROR";
+    error: GraphCheckpointJson;
+};
+type GraphCheckpointFactory = {
+    kind: "registry-ref";
+    ref: string;
+    config?: GraphCheckpointJson;
+    configVersion?: GraphCheckpointJson;
+} | {
+    kind: "local-only";
+    name: string;
+    reason: string;
+};
+interface GraphCheckpointNode {
+    id: string;
+    name?: string;
+    factory: GraphCheckpointFactory;
+    status: string;
+    deps: string[];
+    value: GraphCheckpointValue;
+    backendState?: GraphCheckpointJson;
+    version?: NodeVersionJson;
+    terminal: GraphCheckpointTerminal;
+    lifecycle: {
+        activated: boolean;
+        hasCalledFnOnce: boolean;
+    };
+    ctxState: {
+        persist: boolean;
+        value: GraphCheckpointValue;
+    };
+    meta?: {
+        [key: string]: GraphCheckpointJson;
+    };
+}
+interface GraphCheckpointEdge {
+    from: string;
+    to: string;
+}
+interface GraphCheckpointMount {
+    at: string;
+    checkpoint: GraphCheckpoint;
+}
+interface GraphCheckpoint {
+    version: GraphCheckpointVersion;
+    name?: string;
+    nodes: GraphCheckpointNode[];
+    edges: GraphCheckpointEdge[];
+    mounts?: GraphCheckpointMount[];
+}
+
+/**
+ * observe / profile inspection shapes (R-observe, R-profile / D39).
+ *
+ * observe = a read-only enveloped EGRESS (not a graph node). profile = an opt-in
+ * accumulated-counter snapshot backed by the dispatcher recorder (counters never live on
+ * the thin node, R-node-thin). Per-language (D24, never in parity).
+ */
+
+/** One item of an observe() stream. The envelope carries node identity + ordering. */
+interface ObserveEvent {
+    /** Mount-aware `::` path of the emitting node (shared key with describe/profile). */
+    path: string;
+    /** The protocol message observed at that node. */
+    msg: Message;
+    /** messageTier(msg[0]). */
+    tier: number;
+    /** Graph-local monotonic sequence (D26) — orders events across nodes. */
+    seq: number;
+}
+/** A read-only egress: subscribe to the live ObserveEvent stream; call the returned fn to stop. */
+interface ObserveStream {
+    subscribe(sink: (e: ObserveEvent) => void): () => void;
+}
+type TopologyEventKind = "node-registered" | "deps-changed" | "node-released" | "mount-changed";
+interface TopologyEvent {
+    /** D145 graph inspection/lifecycle event kind. Not a protocol message. */
+    readonly kind: TopologyEventKind;
+    /** Mount-aware `::` path of the affected registered node. */
+    readonly path: string;
+    /** Current dep ids after the event, matching describe().nodes[].deps. */
+    readonly deps: readonly string[];
+    /** Previous dep ids for deps-changed events. */
+    readonly prevDeps?: readonly string[];
+    /** Factory name for node-registered and node-released events. */
+    readonly factory?: string;
+    /** Graph-local monotonic sequence shared with observe() ordering. */
+    readonly seq: number;
+}
+/** A read-only topology egress stream. It does not activate nodes or emit DATA. */
+interface TopologyStream {
+    subscribe(sink: (e: TopologyEvent) => void): () => void;
+}
+/** Predicate used by filterObserve(). */
+type ObservePredicate = (event: ObserveEvent) => boolean;
+/** Equality used by coalesceObserve() for adjacent observe-event suppression. */
+type ObserveEventEquals = (prev: ObserveEvent, next: ObserveEvent) => boolean;
+/**
+ * Filter a read-only observe egress stream without turning it into a graph node.
+ *
+ * The source stream owns ordering and lifecycle; this helper only decides whether to forward each
+ * ObserveEvent and returns the source unsubscribe unchanged.
+ */
+declare function filterObserve(stream: ObserveStream, predicate: ObservePredicate): ObserveStream;
+/**
+ * Suppress adjacent duplicate ObserveEvents while preserving the source stream order.
+ *
+ * This is egress-side coalescing only: it does not batch, delay, reorder, alter seq values, or add
+ * topology to describe(). Pass a custom equality when the caller wants a narrower or wider
+ * definition of "duplicate".
+ */
+declare function coalesceObserve(stream: ObserveStream, equals?: ObserveEventEquals): ObserveStream;
+/** Per-node profile counters (D39). invokes/duration are dispatcher-backed (R-profile). */
+interface NodeProfile {
+    invokes: number;
+    totalDurationNs: number;
+    lastDurationNs: number;
+    status: Status;
+}
+/** profile() snapshot. Shares the mount-aware `::` path key with describe/observe. */
+interface Profile {
+    totalInvokes: number;
+    nodes: Record<string, NodeProfile>;
+}
+
+interface GraphRestoreDefinition<S = never, T = unknown> {
+    readonly kind: "definition";
+    readonly ref: string;
+    readonly fn: (v: S) => T;
+}
+type GraphRestoreEntry = GraphRestoreDescriptor | GraphRestoreDefinition;
+interface GraphRestoreDescriptorContext<C extends GraphCheckpointJson | undefined = GraphCheckpointJson | undefined> {
+    readonly graph: Graph;
+    readonly id: string;
+    readonly name?: string;
+    readonly deps: readonly Node<unknown>[];
+    readonly config: C;
+    readonly configVersion?: GraphCheckpointJson;
+    readonly checkpoint: GraphCheckpointNode;
+    resolveDefinition<S = unknown, T = unknown>(ref: string): GraphRestoreDefinition<S, T>;
+    registerState<T = unknown>(opts?: SugarOpts<T>): Node<unknown>;
+    registerNode<T = unknown>(factory: string, deps: readonly Node<unknown>[], fn: NodeFn | null, opts?: SugarOpts<T>): Node<unknown>;
+}
+interface GraphRestoreDescriptor<C extends GraphCheckpointJson | undefined = GraphCheckpointJson | undefined> {
+    readonly ref: string;
+    validateConfig?(config: GraphCheckpointJson | undefined, configVersion: GraphCheckpointJson | undefined, checkpoint: GraphCheckpointNode): C;
+    create(ctx: GraphRestoreDescriptorContext<C>): Node<unknown>;
+}
+type GraphRestoreRegistry = ReadonlyMap<string, GraphRestoreEntry> | Readonly<Record<string, GraphRestoreEntry>>;
+interface RestoreGraphOptions {
+    registry: GraphRestoreRegistry;
+    dispatcher?: Dispatcher;
+    versioning?: NodeVersioningPolicy;
+}
+declare const stateRestoreDescriptor: GraphRestoreDescriptor<undefined>;
+type TakeConfig = {
+    n: number;
+};
+type TimerConfig = {
+    ms: number;
+};
+type MapConfig = {
+    fn: string;
+};
+declare const takeRestoreDescriptor: GraphRestoreDescriptor<TakeConfig>;
+declare const mapRestoreDescriptor: GraphRestoreDescriptor<MapConfig>;
+declare const timerRestoreDescriptor: GraphRestoreDescriptor<TimerConfig>;
+declare const defaultRestoreRegistry: Readonly<Record<string, GraphRestoreDescriptor>>;
+declare function restoreGraph(checkpoint: GraphCheckpoint, options: RestoreGraphOptions): Graph;
+
+/**
+ * Operators as free-standing factory definitions (D43 / D6 / D40 Catalog-first).
+ *
+ * Operators are `node` sugar (D6), NOT verbs (D4) and NEVER in parity (D24). Each is a
+ * pure {@link Operator} spec — `{factory, body, opts}` — built on the bare `node` primitive
+ * (NOT the `derived` verb): `body` reads ctx dep slots positionally and emits via
+ * `ctx.down`. Two ways to instantiate:
+ *
+ *   - {@link initNode}(op, deps, opts?) — bare, no Graph; returns a working `Node<T>`.
+ *   - `g.initNode(op, deps, opts?)` — graph-bound; the SAME call, plus inspection registration
+ *     (the real factory name lands in the graph's `_entries`, so describe/observe/profile
+ *     show it — D6/R-describe — while the node stays thin, R-node-thin).
+ *
+ * The D30 throw→ERROR boundary lives once, in the free {@link initNode} (which `g.initNode`
+ * funnels through). The pure-ts `operatorOpts/partialOperatorOpts/gatedOperatorOpts` trio is
+ * NOT ported: its sole job (`describeKind:"derived"`) is dead under D6/D39 (factory = the
+ * REAL operator name); only the `partial`/`terminalAsRealInput` flags survive, carried
+ * per-operator in `op.opts`.
+ *
+ * Config is folded into the factory (`map(fn)`, `scan(reducer, seed)`, `take(n)`, `merge()`),
+ * so fn params are annotated where the source type can't be inferred (RxJS-pipe cost);
+ * dep-type safety is recovered by the typed `g.initNode` overloads.
+ */
+
+/**
+ * A free-standing operator definition (D43). `TIn` = the element type each dep delivers
+ * (the operator reads `depLatest(ctx, i) as TIn`); `TOut` = the emitted value type.
+ * `__in`/`__out` are phantom-only (never assigned) — they let `g.initNode` infer + check the
+ * dep tuple against the operator without an explicit type argument.
+ */
+interface Operator<TIn = unknown, TOut = unknown> {
+    /** Real operator name shown in describe (D6/L1.5) — recorded at `_add` by `g.initNode`. */
+    readonly factory: string;
+    /** The ctx-body: reads ctx dep slots positionally, emits via `ctx.down`. */
+    readonly body: (ctx: Ctx) => void;
+    /** Behavioral node options the operator needs (e.g. `partial:true` for combine-family). */
+    readonly opts?: Partial<NodeOptions<TOut>>;
+    /**
+     * D97/D100 restore metadata derived from a named definition or static built-in config.
+     * This is semantic metadata only; dispatcher handles stay graph-local runtime state.
+     */
+    readonly restore?: {
+        ref: string;
+        config?: GraphCheckpointJson;
+        configVersion?: GraphCheckpointJson;
+    };
+    /** @internal phantom — never set; carries the dep element type for `g.initNode` inference. */
+    readonly __in?: TIn;
+    /** @internal phantom — never set; carries the output value type. */
+    readonly __out?: TOut;
+}
+type MutableRestoreRegistry = Map<string, GraphRestoreEntry> | Record<string, GraphRestoreEntry>;
+type RestoreRegistryEntry = GraphRestoreEntry;
+interface Definition<S = unknown, T = unknown> extends GraphRestoreDefinition<S, T> {
+    readonly ref: string;
+    readonly fn: (v: S) => T;
+}
+interface DefineOpts {
+    registry?: MutableRestoreRegistry;
+}
+declare function restoreRegistry(entries?: readonly GraphRestoreEntry[], base?: GraphRestoreRegistry): Map<string, GraphRestoreEntry>;
+declare function define<S, T>(ref: string, fn: (v: S) => T, opts?: DefineOpts): Definition<S, T>;
+/**
+ * Instantiate an operator as a bare `Node<T>` — NO Graph required (D43 bare-node path).
+ * Wraps `op.body` in the D30 value-throw→ERROR boundary; merges `op.opts` with caller `opts`
+ * (caller wins, so `partial`/`pool`/`dispatcher` overrides take effect). The
+ * dispatcher defaults to the process-global (D26) unless `opts.dispatcher` is passed.
+ *
+ * `g.initNode` is the same call PLUS graph registration; graph inspection
+ * (describe/observe/profile) requires that path — a node built bare here is not registered in
+ * any graph's index.
+ */
+declare function initNode<TIn, TOut>(op: Operator<TIn, TOut>, deps: readonly Node<unknown>[], opts?: NodeOptions<TOut>): Node<TOut>;
+/** map: emit fn(value). A named {@link define} makes the map restorable via the map descriptor (D101). */
+declare function map<S, T>(fn: ((v: S) => T) | Definition<S, T>): Operator<S, T>;
+/** filter: emit value only when pred(value) (else skip the wave). */
+declare function filter<S>(pred: (v: S) => boolean): Operator<S, S>;
+/** scan: stateful accumulator over the upstream (acc seeded once, kept in ctx.state). */
+declare function scan<S, T>(reducer: (acc: T, v: S) => T, seed: T): Operator<S, T>;
+/** take: emit the first n values, then COMPLETE (terminal-is-forever). */
+declare function take<S>(n: number): Operator<S, S>;
+/** distinctUntilChanged: emit only when the value differs from the previous emit. */
+declare function distinctUntilChanged<S>(eq?: (a: S, b: S) => boolean): Operator<S, S>;
+/**
+ * merge: interleave several sources — emit each DATA from whichever dep fired. `partial:true`
+ * (combine-family): fires on any single dep, not gated on all deps settling.
+ */
+declare function merge<T>(): Operator<T, T>;
+/**
+ * reduce: accumulate over the whole source, emit ONE final value on the source's COMPLETE
+ * (RxJS `reduce`). Unlike {@link scan} (which emits every step), reduce stays quiet until the
+ * source terminates. `completeWhenDepsComplete:false + terminalAsRealInput:true`: the fn fires on
+ * the source COMPLETE (reading `terminal===true`) and emits the accumulator + COMPLETE. An empty
+ * source emits the seed (RxJS parity). A source ERROR auto-forwards (errorWhenDepsError default).
+ */
+declare function reduce<S, T>(reducer: (acc: T, v: S) => T, seed: T): Operator<S, T>;
+/**
+ * pairwise: emit `[previous, current]` for each consecutive pair; the very first value produces no
+ * pair (quiet → undirty RESOLVED). Previous value is kept in `ctx.state`.
+ */
+declare function pairwise<S>(): Operator<S, readonly [S, S]>;
+/** skip: drop the first `n` DATA values, then pass the rest through. */
+declare function skip<S>(n: number): Operator<S, S>;
+/**
+ * takeWhile: emit values while `pred` holds; on the first value that fails `pred`, COMPLETE
+ * WITHOUT emitting it (RxJS default, non-inclusive). Terminal-is-forever once it completes.
+ */
+declare function takeWhile<S>(pred: (v: S) => boolean): Operator<S, S>;
+/**
+ * first: emit the first value matching `pred` (or simply the first value), then COMPLETE. EDGE
+ * (RxJS divergence, flagged — same class as last/find/elementAt): if the source COMPLETEs with no
+ * matching value, the substrate auto-cascades a bare COMPLETE (no value); RxJS `first()` throws
+ * EmptyError. Could align to `[[ERROR, EmptyError]]` (expressible) if strict RxJS parity is wanted.
+ */
+declare function first<S>(pred?: (v: S) => boolean): Operator<S, S>;
+/**
+ * last: emit the last value matching `pred` (or the last value) on the source's COMPLETE.
+ * `completeWhenDepsComplete:false + terminalAsRealInput:true`. EDGE (RxJS divergence, flagged):
+ * RxJS `last()` throws EmptyError when no value matched; we COMPLETE without a value (no throw) —
+ * the clean-slate substrate has no "complete-or-throw" terminal and SENTINEL forbids emitting a
+ * placeholder.
+ */
+declare function last<S>(pred?: (v: S) => boolean): Operator<S, S>;
+/**
+ * find: emit the first value matching `pred`, then COMPLETE. EDGE (RxJS divergence, flagged): RxJS
+ * `find` emits `undefined` then COMPLETE when nothing matched — but `undefined` IS the SENTINEL
+ * (R-sentinel), so a not-found source COMPLETE here emits a bare COMPLETE (no value).
+ */
+declare function find<S>(pred: (v: S) => boolean): Operator<S, S>;
+/**
+ * elementAt: emit the value at zero-based `index`, then COMPLETE. EDGE (RxJS divergence, flagged):
+ * RxJS throws ArgumentOutOfRangeError if the source completes before `index`; we COMPLETE without
+ * a value (no throw), consistent with last/find.
+ */
+declare function elementAt<S>(index: number): Operator<S, S>;
+/** Observer object for {@link tap} — lifecycle-aware side effects (RxJS tap observer form). */
+interface TapObserver<T> {
+    data?: (value: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+}
+/**
+ * tap: invoke a side effect on each DATA (function form) or on data/error/complete (observer form);
+ * values pass through unchanged. The observer form reads source terminals
+ * (`completeWhenDepsComplete:false + errorWhenDepsError:false + terminalAsRealInput:true`) so it can
+ * call `error`/`complete` then forward the terminal; the function form lets the substrate
+ * auto-cascade terminals.
+ */
+declare function tap<S>(fnOrObserver: ((v: S) => void) | TapObserver<S>): Operator<S, S>;
+/**
+ * onFirstData (alias `tapFirst`): invoke `fn` exactly once on the first qualifying value (default
+ * `where: v => v != null` — null/undefined pass through without counting as "first"), then pass all
+ * values through unchanged. The one-shot guard is per-node `ctx.state` (NOT a factory closure, so a
+ * second instantiation of the same factory re-arms — R-ctx-state).
+ */
+declare function onFirstData<S>(fn: (v: S) => void, opts?: {
+    where?: (v: S) => boolean;
+}): Operator<S, S>;
+/** tapFirst: alias of {@link onFirstData} (the one-shot companion to {@link tap}). */
+declare const tapFirst: typeof onFirstData;
+/** Options for {@link settle}. */
+interface SettleOpts<S> {
+    /** Consecutive no-change waves before declaring convergence + COMPLETE. */
+    quietWaves: number;
+    /** Optional hard cap on total waves before forced COMPLETE. */
+    maxWaves?: number;
+    /** Optional comparator; a DATA equal to the previous one does NOT reset the quiet counter. */
+    equals?: (a: S, b: S) => boolean;
+}
+/**
+ * settle: forward each DATA unchanged, watch for convergence, COMPLETE once the source has been
+ * quiet for `quietWaves` consecutive waves (or `maxWaves` elapsed). "Wave" = one fn invocation
+ * (a DATA batch OR a bare undirty RESOLVED end-of-wave). No polling (R-no-polling) — the counter
+ * advances only on real upstream waves. `settle`'s own `equals` is a body comparator, NOT the
+ * removed substrate `equals` (D49).
+ */
+declare function settle<S>(opts: SettleOpts<S>): Operator<S, S>;
+/**
+ * rescue (alias `catchError`): replace an upstream ERROR with a recovered value. On source DATA →
+ * forward; on source ERROR → emit `recover(err)` as DATA (if `recover` throws, forward THAT as
+ * ERROR); on source COMPLETE → COMPLETE. After recovery the source is terminal-errored (dead) so no
+ * further values flow — the recovered value is the final cached value (matches the frozen pure-ts
+ * reference; it does NOT auto-COMPLETE, RxJS-`catchError(()=>of(x))` divergence, flagged).
+ */
+declare function rescue<S>(recover: (err: unknown) => S): Operator<S, S>;
+/** catchError: RxJS-named alias of {@link rescue}. */
+declare const catchError: typeof rescue;
+/** Options for {@link valve}. */
+interface ValveOpts {
+    /**
+     * Optional AbortController (or a `() => AbortController | undefined` factory): on the control's
+     * truthy→falsy edge, `valve` calls `controller.abort()` — cancel an in-flight async boundary
+     * (LLM/fetch) the caller threaded `controller.signal` into. An external-resource cleanup (like
+     * `ctx.onDeactivation`), NOT an imperative reactive trigger (R-no-imperative).
+     */
+    abortInFlight?: AbortController | (() => AbortController | undefined);
+}
+/**
+ * valve: forward the source's DATA only while `control` (dep 1) is truthy; when closed, stay quiet
+ * (undirty RESOLVED). `[source, control]` declared deps + `partial:true` (the control wave can fire
+ * before the source ever delivers). `completeWhenDepsComplete:false` — closing the gate (control
+ * terminating) does NOT complete the valve; only the SOURCE's terminal (read via
+ * `terminalAsRealInput`) is forwarded. The `state`-verb control input is a legitimate external
+ * boundary (D4 / D54), not a forbidden imperative trigger.
+ */
+declare function valve<S>(opts?: ValveOpts): Operator<S, S>;
+
+/**
+ * The Graph layer (CSP-2): convenience + inspection entry (D5 / R-graph-role).
+ *
+ * g.* sugar desugars to dispatcher.register + Node and auto-registers into the graph
+ * inspection index (D27: sugar→ctx-fn conversion lives strictly here; the substrate node
+ * only ever sees `(ctx)=>void`). The Graph owns naming, describe, mount, and the D30
+ * value-level throw→ERROR boundary. The bare node()/dispatcher stay inspection-free
+ * (R-node-thin).
+ *
+ * Canonical authority: ~/src/graphrefly — D3/D5/D27/D30/D36/D37/D39, R-graph-role,
+ * R-describe, R-fn-contract, R-edges-derived, R-meta-presentation.
+ */
+
+/** Map a tuple of Nodes to the tuple of their value types (typed value-level fn args). */
+type DepValues<D extends readonly Node<unknown>[]> = {
+    [K in keyof D]: D[K] extends Node<infer V> ? V : never;
+};
+/** Value-level derived fn: receives dep values, returns the next value (undefined = no emit). */
+type DerivedFn<D extends readonly Node<unknown>[], T> = (...values: DepValues<D>) => T | undefined;
+/** Value-level effect fn: receives dep values, optionally returns a deactivation cleanup. */
+type EffectFn<D extends readonly Node<unknown>[]> = (...values: DepValues<D>) => void | (() => void);
+/** Sugar options — node options minus graph-owned dispatcher plus naming/meta. */
+interface SugarOpts<T = unknown> extends Omit<NodeOptions<T>, "dispatcher"> {
+    name?: string;
+    meta?: Record<string, unknown>;
+    /**
+     * D95: explicit restorable factory metadata. Static JSON-compatible config may live here;
+     * reactive options must remain graph deps. Without this, function-backed nodes are local-only.
+     */
+    restore?: {
+        ref: string;
+        config?: unknown;
+        configVersion?: unknown;
+    };
+}
+interface GraphOptions {
+    name?: string;
+    /** Bind to a dispatcher (default = process-global, D26). */
+    dispatcher?: Dispatcher;
+    /** D109 default node runtime versioning policy for graph-owned nodes. Default is nodev0. */
+    versioning?: NodeVersioningPolicy;
+    /** Graph-owned environment drivers for source/adapter boundaries (D130/D131). */
+    environment?: EnvironmentDrivers;
+    /**
+     * Turn on the dispatcher profile recorder (D39 / F-PERF default off). NOTE: this
+     * switches recording on for the WHOLE bound dispatcher (the default is process-global,
+     * D26) — every graph sharing it then pays the recorder cost. For isolated profiling
+     * use a dedicated dispatcher: `graph({ dispatcher: new Dispatcher(), profile: true })`.
+     */
+    profile?: boolean;
+}
+/**
+ * A state node (L4-Q1): a manual source whose `.set(v)` is `node.down([[DATA, v]])` sugar.
+ * Extends the substrate Node so it is usable as a dep AND carries the graph-layer `.set`.
+ */
+declare class StateNode<T> extends Node<T> {
+    set(v: T): void;
+}
+interface TopologyGroupOptions {
+    /** Optional inspection/release reason label for this graph-owned topology group. */
+    name?: string;
+}
+interface TopologyGroupReleaseOptions {
+    /** Optional diagnostic reason. No protocol/control messages are synthesized. */
+    reason?: string;
+}
+/**
+ * Graph-owned D152 release group: a label over ordinary graph-registered nodes.
+ * The graph registry remains the source of truth; helper-local membership is only
+ * a memo for atomic quiescent release.
+ */
+interface TopologyGroup {
+    readonly name?: string;
+    readonly released: boolean;
+    add<T extends Node<unknown>>(node: T): T;
+    node<T = unknown>(deps?: readonly Node<unknown>[], fn?: NodeFn | null, opts?: SugarOpts<T>): Node<T>;
+    state<T>(initial: T, opts?: SugarOpts<T>): StateNode<T>;
+    producer<T = unknown>(fn: NodeFn, opts?: SugarOpts<T>): Node<T>;
+    derived<const D extends readonly Node<unknown>[], T>(deps: D, fn: DerivedFn<D, T>, opts?: SugarOpts<T>): Node<T>;
+    effect<const D extends readonly Node<unknown>[]>(deps: D, fn: EffectFn<D>, opts?: SugarOpts<void>): Node<void>;
+    initNode<TIn, TOut>(op: Operator<TIn, TOut>, deps: readonly Node<TIn>[], opts?: SugarOpts<TOut>): Node<TOut>;
+    release(opts?: TopologyGroupReleaseOptions): void;
+}
+declare class Graph {
+    readonly name?: string;
+    private readonly _dispatcher;
+    private readonly _versioning;
+    private readonly _environment;
+    private readonly _core;
+    private readonly _entries;
+    private readonly _byId;
+    private readonly _retiredIds;
+    private readonly _mounts;
+    private _seq;
+    private _clock;
+    private _topologyObserverSeq;
+    private readonly _topologyObservers;
+    private _topologyDelivering;
+    private readonly _topologyQueue;
+    private _synthSeq;
+    private readonly _synthIds;
+    constructor(opts?: GraphOptions);
+    private _add;
+    private _addWithId;
+    private _assertDepsLocal;
+    private _assertRegisteredNode;
+    private _nodeOpts;
+    private _construct;
+    /** Look up a registered node by its id. */
+    find(id: string): Node<unknown> | undefined;
+    private _releaseNodes;
+    /** ctx-level power surface: a raw `(ctx)=>void` fn (or a passthrough/state when null). */
+    node<T = unknown>(deps?: readonly Node<unknown>[], fn?: NodeFn | null, opts?: SugarOpts<T>): Node<T>;
+    /** A manual source with `.set(v)` (L4-Q1). */
+    state<T>(initial: T, opts?: SugarOpts<T>): StateNode<T>;
+    /** ctx-level depless source; its fn runs on activation (R-rom-ram). */
+    producer<T = unknown>(fn: NodeFn, opts?: SugarOpts<T>): Node<T>;
+    /** value-level pure transform: deps → value (D27 wrapped; D30 throw→ERROR). */
+    derived<const D extends readonly Node<unknown>[], T>(deps: D, fn: DerivedFn<D, T>, opts?: SugarOpts<T>): Node<T>;
+    /** value-level sink: deps → effect; return value (a fn) becomes onDeactivation (D28). */
+    effect<const D extends readonly Node<unknown>[]>(deps: D, fn: EffectFn<D>, opts?: SugarOpts<void>): Node<void>;
+    /** Declarative batch (D12): one wave, success→commit / throw→rollback. */
+    batch<T>(fn: (bctx: BatchCtx) => T): T;
+    /** Embed a child graph addressable under `at` (R-mount; mount has no deps). */
+    mount(child: Graph, opts: {
+        at: string;
+    }): void;
+    /**
+     * Instantiate an operator (or source) factory as a registered graph node. `deps` are
+     * type-checked against the operator's input element type; the output type flows from the
+     * operator. A source is a depless operator — pass `[]`. Caller `opts` (name/meta/behavioral
+     * overrides) win over the operator's baked-in `opts`.
+     */
+    initNode<TIn, TOut>(op: Operator<TIn, TOut>, deps: readonly Node<TIn>[], opts?: SugarOpts<TOut>): Node<TOut>;
+    /**
+     * Graph-owned activation root for internal helper nodes. This is the sanctioned keepalive shape:
+     * a graph, not a helper closure, owns the subscription and returns the release handle.
+     */
+    retain<T>(node: Node<T>, opts?: {
+        reason?: string;
+    }): () => void;
+    /**
+     * D152 graph-owned topology/release group. Members are ordinary registered graph nodes;
+     * release is quiescent-only and removes ids atomically without synthesizing protocol messages.
+     */
+    topologyGroup(opts?: TopologyGroupOptions): TopologyGroup;
+    /** Live point-in-time structure snapshot (R-describe / D39 / D51). `_prefix` carries the mount path. */
+    describe(opts?: DescribeOpts, _prefix?: string): DescribeSnapshot;
+    /**
+     * D173 pure-structure topology snapshot over the same live truth source as describe().
+     * Runtime status/value/version remain on describe(); blueprint metadata is a later envelope.
+     */
+    topology(): GraphTopologySnapshot;
+    /**
+     * D177 synchronous audit/collaboration envelope over the pure topology snapshot.
+     * Hashing and environment provenance enrichment stay in pure helpers outside Graph core.
+     */
+    blueprint(opts?: GraphBlueprintOptions): GraphBlueprint;
+    private _observeTargets;
+    /**
+     * observe(path?) = read-only enveloped EGRESS (R-observe / D39). NOT a graph node — it
+     * taps the target node(s) via subscribe and forwards each Message as an ObserveEvent.
+     * No path = whole graph; an exact id = a single node; otherwise a `::`-prefix subtree.
+     */
+    observe(path?: string): ObserveStream;
+    /**
+     * D145 observeTopology(path?) = read-only graph lifecycle egress over the existing
+     * graph registry. It is not a graph node, does not subscribe to nodes, and emits no DATA.
+     */
+    observeTopology(path?: string): TopologyStream;
+    private _idForTopologyNode;
+    private _topologyDeps;
+    private _emitTopologyNodeRegistered;
+    private _emitTopologyDepsChanged;
+    private _emitTopologyNodeReleased;
+    private _emitTopologyMountChanged;
+    private _ensureMountedTopologyForwarders;
+    private _releaseMountedTopologyForwarders;
+    private _emitMountedTopologyEvent;
+    private _emitTopologyEvent;
+    /**
+     * profile() = accumulated-counter snapshot (R-profile / D39). invokes + duration are
+     * dispatcher-backed (the invoke funnel, F-DISPATCH-ALL) — counters never live on the
+     * thin node (R-node-thin). Requires `graph({ profile: true })` (opt-in, F-PERF).
+     */
+    profile(): Profile;
+    /** Versioned graph lifecycle checkpoint (R-snapshot / D83 / D90). Pure capture, no storage I/O. */
+    checkpoint(): GraphCheckpoint;
+    private _checkpoint;
+    private _checkpointNode;
+}
+/** Construct a Graph (default global dispatcher; L4-Q4). */
+declare function graph(opts?: GraphOptions): Graph;
+
+export { type ValveOpts as $, type GraphRestoreDescriptorContext as A, type GraphRestoreEntry as B, type GraphRestoreRegistry as C, type DefineOpts as D, type EffectFn as E, type NormalizedGraphTopologyNode as F, GRAPH_BLUEPRINT_VERSION as G, type NormalizedGraphTopologySnapshot as H, type ObserveEventEquals as I, type ObservePredicate as J, type ObserveStream as K, type Operator as L, type RestoreRegistryEntry as M, type NodeProfile as N, type ObserveEvent as O, type Profile as P, StateNode as Q, type RestoreGraphOptions as R, type SettleOpts as S, type SugarOpts as T, type TapObserver as U, type TopologyEvent as V, type TopologyEventKind as W, type TopologyGroup as X, type TopologyGroupOptions as Y, type TopologyGroupReleaseOptions as Z, type TopologyStream as _, type Definition as a, canonicalTopologyBytes as a0, canonicalTopologyJson as a1, catchError as a2, coalesceObserve as a3, defaultRestoreRegistry as a4, define as a5, distinctUntilChanged as a6, elementAt as a7, filter as a8, filterObserve as a9, valve as aA, withBlueprintHash as aB, withBlueprintProvenance as aC, find as aa, first as ab, graph as ac, graphBlueprintDiagnostics as ad, initNode as ae, last as af, map as ag, mapRestoreDescriptor as ah, merge as ai, normalizeTopology as aj, onFirstData as ak, pairwise as al, reduce as am, rescue as an, restoreGraph as ao, restoreRegistry as ap, scan as aq, settle as ar, skip as as, stateRestoreDescriptor as at, take as au, takeRestoreDescriptor as av, takeWhile as aw, tap as ax, tapFirst as ay, timerRestoreDescriptor as az, type DerivedFn as b, GRAPH_CHECKPOINT_VERSION as c, Graph as d, type GraphBlueprint as e, type GraphBlueprintDiagnosticCode as f, type GraphBlueprintDiagnosticIssue as g, type GraphBlueprintDiagnostics as h, type GraphBlueprintHash as i, type GraphBlueprintHashInput as j, type GraphBlueprintHashOptions as k, type GraphBlueprintJson as l, type GraphBlueprintOptions as m, type GraphBlueprintProvenance as n, type GraphCheckpoint as o, type GraphCheckpointEdge as p, type GraphCheckpointFactory as q, type GraphCheckpointJson as r, type GraphCheckpointMount as s, type GraphCheckpointNode as t, type GraphCheckpointTerminal as u, type GraphCheckpointValue as v, type GraphCheckpointVersion as w, type GraphOptions as x, type GraphRestoreDefinition as y, type GraphRestoreDescriptor as z };