@graphrefly/ts 0.0.1 → 0.0.3

package/dist/{graph-D-1-SQeC.d.ts → graph-CS0b4V9B.d.ts}

@@ -1,7 +1,7 @@
 import { BatchCtx } from './core/index.js';
-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-BsJvElYZ.js';
+import { q as NodeVersionJson, D as Dispatcher, u as NodeVersioningPolicy, E as EnvironmentDrivers, n as NodeOptions, N as Node, m as NodeFn, C as Ctx, B as Status } from './types-DChxk1vK.js';
 import { S as StrictJsonObject, b as StrictJsonValue } from './codec-BB7p8fJc.js';
-import { G as GraphTopologyEdge, e as GraphTopologySnapshot, b as DescribeOpts, c as DescribeSnapshot } from './describe-BpyJuWkw.js';
+import { G as GraphTopologyEdge, e as GraphTopologySnapshot, b as DescribeOpts, c as DescribeSnapshot } from './describe-cYr_Z5zm.js';
 import { M as Message } from './messages-CAzUPPJM.js';
 
 /**
@@ -143,78 +143,43 @@ interface GraphCheckpoint {
     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;
+/** 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;
+    };
 }
-/** profile() snapshot. Shares the mount-aware `::` path key with describe/observe. */
-interface Profile {
-    totalInvokes: number;
-    nodes: Record<string, NodeProfile>;
+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;
 }
 
 interface GraphRestoreDefinition<S = never, T = unknown> {
@@ -335,19 +300,96 @@ declare function define<S, T>(ref: string, fn: (v: S) => T, opts?: DefineOpts):
  * 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). */
+/**
+ * Transform each upstream DATA value with a synchronous mapping function.
+ *
+ * @param fn - Mapping function, or a named `define()` definition for checkpoint restoration.
+ * @returns An operator that emits `fn(value)` for each upstream value.
+ * @example
+ * ```ts
+ * import { graph, map } from "@graphrefly/ts";
+ *
+ * const g = graph();
+ * const count = g.state(1);
+ * const doubled = g.initNode(map((value: number) => value * 2), [count]);
+ * ```
+ * @remarks **Restorable maps:** Passing a named `define()` registers semantic restore metadata.
+ * @category operators
+ */
 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). */
+/**
+ * Pass through upstream values that satisfy a predicate.
+ *
+ * @param pred - Predicate evaluated for each upstream DATA value.
+ * @returns An operator that emits matching values and stays quiet for non-matches.
+ * @example
+ * ```ts
+ * import { filter, graph } from "@graphrefly/ts";
+ *
+ * const g = graph();
+ * const count = g.state(0);
+ * const even = g.initNode(filter((value: number) => value % 2 === 0), [count]);
+ * ```
+ * @category operators
+ */
 declare function filter<S>(pred: (v: S) => boolean): Operator<S, S>;
-/** scan: stateful accumulator over the upstream (acc seeded once, kept in ctx.state). */
+/**
+ * Accumulate upstream values and emit each intermediate accumulator.
+ *
+ * @param reducer - Reducer called with the previous accumulator and each upstream value.
+ * @param seed - Initial accumulator value.
+ * @returns An operator that emits the accumulator after every input value.
+ * @example
+ * ```ts
+ * import { graph, scan } from "@graphrefly/ts";
+ *
+ * const g = graph();
+ * const values = g.state(1);
+ * const total = g.initNode(scan((sum: number, value: number) => sum + value, 0), [values]);
+ * ```
+ * @category operators
+ */
 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). */
+/**
+ * Emit the first `n` upstream values, then complete.
+ *
+ * @param n - Number of DATA values to pass before completion.
+ * @returns An operator that forwards at most `n` values and then emits COMPLETE.
+ * @example
+ * ```ts
+ * import { graph, take } from "@graphrefly/ts";
+ *
+ * const firstThree = graph().initNode(take<number>(3), [source]);
+ * ```
+ * @category operators
+ */
 declare function take<S>(n: number): Operator<S, S>;
-/** distinctUntilChanged: emit only when the value differs from the previous emit. */
+/**
+ * Suppress consecutive duplicate values.
+ *
+ * @param eq - Equality predicate; defaults to `Object.is`.
+ * @returns An operator that emits only when the next value differs from the previous emitted value.
+ * @example
+ * ```ts
+ * import { distinctUntilChanged, graph } from "@graphrefly/ts";
+ *
+ * const stable = graph().initNode(distinctUntilChanged<number>(), [source]);
+ * ```
+ * @category operators
+ */
 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.
+ *
+ * @returns An operator that forwards DATA from any dependency.
+ * @example
+ * ```ts
+ * import { graph, merge } from "@graphrefly/ts";
+ *
+ * const merged = graph().initNode(merge<number>(), [left, right]);
+ * ```
+ * @category operators
  */
 declare function merge<T>(): Operator<T, T>;
 /**
@@ -356,6 +398,17 @@ declare function merge<T>(): Operator<T, T>;
  * 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).
+ *
+ * @param reducer - Reducer called with the accumulator and each upstream DATA value.
+ * @param seed - Initial accumulator value emitted if the source completes empty.
+ * @returns An operator that emits one accumulated value when the source completes.
+ * @example
+ * ```ts
+ * import { graph, reduce } from "@graphrefly/ts";
+ *
+ * const total = graph().initNode(reduce((sum: number, value: number) => sum + value, 0), [source]);
+ * ```
+ * @category operators
  */
 declare function reduce<S, T>(reducer: (acc: T, v: S) => T, seed: T): Operator<S, T>;
 /**
@@ -469,64 +522,6 @@ interface ValveOpts {
  */
 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;
@@ -552,6 +547,125 @@ interface TopologyGroup {
     initNode<TIn, TOut>(op: Operator<TIn, TOut>, deps: readonly Node<TIn>[], opts?: SugarOpts<TOut>): Node<TOut>;
     release(opts?: TopologyGroupReleaseOptions): void;
 }
+
+/**
+ * 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>;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * import { graph } from "@graphrefly/ts";
+ *
+ * const count = graph().state(0);
+ * count.set(1);
+ * ```
+ * @category graph
+ */
+declare class StateNode<T> extends Node<T> {
+    set(v: T): void;
+}
+/**
+ * Own a single graph-local topology, lifecycle, inspection index, and dispatcher boundary.
+ *
+ * @example
+ * ```ts
+ * import { graph } from "@graphrefly/ts";
+ *
+ * const g = graph({ name: "counter" });
+ * const count = g.state(0, { name: "count" });
+ * const doubled = g.derived([count], ([value]) => value * 2, { name: "doubled" });
+ * ```
+ * @remarks **Graph-local:** Cross-graph dependencies require a wire bridge; direct deps stay inside
+ *   one graph ownership domain.
+ * @category graph
+ */
 declare class Graph {
     readonly name?: string;
     private readonly _dispatcher;
@@ -660,7 +774,22 @@ declare class Graph {
     private _checkpoint;
     private _checkpointNode;
 }
-/** Construct a Graph (default global dispatcher; L4-Q4). */
+/**
+ * Construct a graph with graph-local topology, lifecycle, and inspection ownership.
+ *
+ * @param opts - Optional graph name, dispatcher, versioning policy, environment drivers, and
+ *   profiling switch.
+ * @returns A `Graph` instance whose sugar methods create graph-registered nodes.
+ * @example
+ * ```ts
+ * import { graph } from "@graphrefly/ts";
+ *
+ * const g = graph({ name: "counter" });
+ * const count = g.state(0, { name: "count" });
+ * const doubled = g.derived([count], ([value]) => value * 2);
+ * ```
+ * @category graph
+ */
 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 };

package/dist/{index-72VZC0-E.d.cts → index-DLrNopda.d.cts}

@@ -1,5 +1,5 @@
-import { N as Node, n as NodeOptions, h as HttpResponse, g as HttpRequest, x as ProcessResult, z as SseEvent, A as SseRequest, J as WebSocketEvent, M as WebSocketRequest, X as WebhookEvent, Y as WebhookRegistration, w as ProcessCommand } from './types-CcPIn7sy.cjs';
-import { L as Operator } from './graph-DCEWh4T2.cjs';
+import { N as Node, n as NodeOptions, h as HttpResponse, g as HttpRequest, x as ProcessResult, z as SseEvent, A as SseRequest, J as WebSocketEvent, M as WebSocketRequest, X as WebhookEvent, Y as WebhookRegistration, w as ProcessCommand } from './types-CTN3XoMl.cjs';
+import { L as Operator } from './graph-C1C-wb0L.cjs';
 
 /**
  * Async + sync sources (binding-layer sugar, D43 / D40 / feedback_async_sources_binding_layer).
@@ -44,6 +44,16 @@ interface TimerSourceOpts extends AsyncSourceOpts {
 interface FromCronOptions extends AsyncSourceOpts {
     /** Cron matcher polling interval in milliseconds. Default: 60_000. */
     tickMs?: number;
+    /** IANA timezone used for wall-clock cron matching. Defaults to the host-local timezone. */
+    timezone?: string;
+    /**
+     * DST policy for timezone-aware matching. Current D484 defaults are explicit: nonexistent
+     * wall-clock minutes are skipped, and repeated wall-clock minutes fire at most once.
+     */
+    dst?: {
+        readonly nonexistent?: "skip";
+        readonly repeated?: "once";
+    };
     /**
      * Emitted value shape. `timestamp_ns` is a decimal string so it cannot lose precision as a
      * JavaScript number; use `timestamp_ms` when numeric millisecond precision is enough.
@@ -74,8 +84,12 @@ type PushUnsubscribe = () => void;
 type PushRegister<T> = (deliver: (payload: T) => void) => PushUnsubscribe | undefined;
 /** Parse a standard five-field cron expression. */
 declare function parseCron(expr: string): CronSchedule;
-/** Test whether a local Date matches a parsed cron schedule. */
-declare function matchesCron(schedule: CronSchedule, date: Date): boolean;
+interface CronMatchOptions {
+    /** IANA timezone used for wall-clock projection. Defaults to the host-local timezone. */
+    timezone?: string;
+}
+/** Test whether a Date matches a parsed cron schedule in host-local time or an IANA timezone. */
+declare function matchesCron(schedule: CronSchedule, date: Date, opts?: CronMatchOptions): boolean;
 declare function fromCron(expr: string, opts: FromCronOptions & {
     output: "date";
 }): Operator<never, Date>;
@@ -101,38 +115,165 @@ declare function fromWebhookWithOptions(registration: WebhookRegistration): Oper
  * Timer source: one-shot (first tick then COMPLETE) or periodic (`{period}` → 0, 1, 2, …).
  * sync pool + pausable:false (a timer keeps producing through PAUSE, R-pause-modes). Emits the
  * tick counter from 0; deactivation clears the timers.
+ *
+ * @param ms - Delay before the first tick in milliseconds.
+ * @param opts - Optional period and source options.
+ * @returns A source operator that emits tick counters.
+ * @example
+ * ```ts
+ * import { graph, timer } from "@graphrefly/ts";
+ *
+ * const tick = graph().initNode(timer(100), []);
+ * ```
+ * @category sources
  */
 declare function timer(ms: number, opts?: TimerSourceOpts): Operator<never, number>;
-/** Frozen pure-ts name for {@link timer}; preserves the real factory name in describe(). */
+/**
+ * Create a timer source with the legacy `fromTimer` factory name.
+ *
+ * @param ms - Delay before the first tick in milliseconds.
+ * @param opts - Optional period and source options.
+ * @returns A source operator that emits tick counters.
+ * @example
+ * ```ts
+ * import { fromTimer, graph } from "@graphrefly/ts";
+ *
+ * const tick = graph().initNode(fromTimer(100), []);
+ * ```
+ * @remarks **Factory name:** This preserves the real `fromTimer` factory name in `describe()`.
+ * @category sources
+ */
 declare function fromTimer(ms: number, opts?: TimerSourceOpts): Operator<never, number>;
-/** interval: periodic ticks (0, 1, 2, …), first at `ms`, then every `ms` (RxJS semantics). */
+/**
+ * Emit periodic tick counters.
+ *
+ * @param ms - Delay before the first tick and between later ticks in milliseconds.
+ * @returns A source operator that emits `0`, `1`, `2`, and so on.
+ * @example
+ * ```ts
+ * import { graph, interval } from "@graphrefly/ts";
+ *
+ * const ticks = graph().initNode(interval(1000), []);
+ * ```
+ * @category sources
+ */
 declare function interval(ms: number): Operator<never, number>;
 /**
  * Lift a Promise (or thenable) to a single-value stream: one DATA then COMPLETE, or ERROR on
  * rejection. async pool (default pausable → a paused source buffers its late emit). Optional
  * `signal` aborts to ERROR.
+ *
+ * @param p - Promise or thenable to lift into the graph.
+ * @param opts - Optional abort signal and async source options.
+ * @returns A source operator that emits one DATA value and COMPLETE, or ERROR on rejection/abort.
+ * @example
+ * ```ts
+ * import { fromPromise, graph } from "@graphrefly/ts";
+ *
+ * const user = graph().initNode(fromPromise(fetch("/user").then((res) => res.json())), []);
+ * ```
+ * @category sources
  */
 declare function fromPromise<T>(p: Promise<T> | PromiseLike<T>, opts?: AsyncSourceOpts): Operator<never, T>;
 /**
  * Read an async iterable: each value → DATA; COMPLETE when done; ERROR on failure. async pool.
  * Optional `signal` aborts the pump.
+ *
+ * @param iterable - Async iterable to pump into the graph.
+ * @param opts - Optional abort signal and async source options.
+ * @returns A source operator that emits every iterable value and then COMPLETE.
+ * @example
+ * ```ts
+ * import { fromAsyncIter, graph } from "@graphrefly/ts";
+ *
+ * const stream = graph().initNode(fromAsyncIter(events()), []);
+ * ```
+ * @category sources
  */
 declare function fromAsyncIter<T>(iterable: AsyncIterable<T>, opts?: AsyncSourceOpts): Operator<never, T>;
 /**
  * of: synchronous values — each argument as DATA, then COMPLETE. `of()` is the EMPTY source.
+ *
+ * @param values - Values to emit synchronously on activation.
+ * @returns A source operator that emits each value and then COMPLETE.
+ * @example
+ * ```ts
+ * import { graph, of } from "@graphrefly/ts";
+ *
+ * const values = graph().initNode(of(1, 2, 3), []);
+ * ```
+ * @category sources
  */
 declare function of<T = never>(...values: T[]): Operator<never, T>;
-/** fromIter: a sync iterable — each value → DATA (in order), then COMPLETE, on activation. */
+/**
+ * Emit every value from a synchronous iterable.
+ *
+ * @param iterable - Iterable whose values are emitted in order.
+ * @returns A source operator that emits every iterable value and then COMPLETE.
+ * @example
+ * ```ts
+ * import { fromIter, graph } from "@graphrefly/ts";
+ *
+ * const values = graph().initNode(fromIter([1, 2, 3]), []);
+ * ```
+ * @category sources
+ */
 declare function fromIter<T>(iterable: Iterable<T>): Operator<never, T>;
-/** EMPTY analogue: complete immediately with no DATA. */
+/**
+ * Complete immediately without emitting DATA.
+ *
+ * @returns A source operator that emits COMPLETE on activation.
+ * @example
+ * ```ts
+ * import { empty, graph } from "@graphrefly/ts";
+ *
+ * const done = graph().initNode(empty(), []);
+ * ```
+ * @category sources
+ */
 declare function empty<T = never>(): Operator<never, T>;
-/** NEVER analogue: activate and remain silent until deactivation. */
+/**
+ * Activate and remain silent until deactivation.
+ *
+ * @returns A source operator that never emits DATA or terminal messages by itself.
+ * @example
+ * ```ts
+ * import { graph, never } from "@graphrefly/ts";
+ *
+ * const quiet = graph().initNode(never(), []);
+ * ```
+ * @category sources
+ */
 declare function never<T = never>(): Operator<never, T>;
-/** Error source: terminate with ERROR on activation, coercing invalid host-language payloads. */
+/**
+ * Terminate with ERROR on activation.
+ *
+ * @param err - Host-language error payload to normalize into a protocol ERROR payload.
+ * @returns A source operator that emits ERROR.
+ * @example
+ * ```ts
+ * import { graph, throwError } from "@graphrefly/ts";
+ *
+ * const failed = graph().initNode(throwError(new Error("boom")), []);
+ * ```
+ * @category sources
+ */
 declare function throwError(err: unknown): Operator<never, never>;
 /**
  * Wrap a DOM-style event target. Each event becomes DATA; deactivation removes the listener.
  * External callbacks are source boundaries (D43), so no polling or operator-level async leaks in.
+ *
+ * @param target - Event target implementing `addEventListener` and `removeEventListener`.
+ * @param type - Event type to subscribe to.
+ * @param opts - Optional listener options and source options.
+ * @returns A source operator that emits each event as DATA.
+ * @example
+ * ```ts
+ * import { fromEvent, graph } from "@graphrefly/ts";
+ *
+ * const clicks = graph().initNode(fromEvent<MouseEvent>(button, "click"), []);
+ * ```
+ * @category sources
  */
 declare function fromEvent<T = unknown>(target: EventTargetLike, type: string, opts?: FromEventOptions): Operator<never, T>;
 /**