@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/base/worker/index.d.cts

@@ -0,0 +1,207 @@
+import { Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * WorkerTransport — normalized message channel for all worker types.
+ *
+ * Abstracts Worker, SharedWorker, ServiceWorker, BroadcastChannel, and
+ * MessagePort behind a uniform post/listen/terminate interface.
+ */
+/** Normalized bidirectional message channel. */
+interface WorkerTransport {
+    /** Send data to the other side. Optional transferables for zero-copy. */
+    post(data: unknown, transfer?: Transferable[]): void;
+    /** Listen for incoming messages. Returns unsubscribe function. */
+    listen(handler: (data: unknown) => void): () => void;
+    /** Terminate the connection (if supported by the underlying transport). */
+    terminate?(): void;
+}
+/**
+ * Auto-detect transport type and create a normalized WorkerTransport.
+ *
+ * Supports:
+ * - `Worker` — direct postMessage/onmessage
+ * - `SharedWorker` — port-based postMessage/onmessage
+ * - `ServiceWorker` — postMessage via controller, listen via navigator.serviceWorker
+ * - `BroadcastChannel` — postMessage/onmessage (no Transferable support)
+ * - `MessagePort` — direct postMessage/onmessage (worker-side SharedWorker port)
+ */
+declare function createTransport(target: unknown): WorkerTransport;
+
+/**
+ * workerBridge — main-thread reactive node bridge to a worker.
+ *
+ * Creates proxy nodes for imported worker nodes, subscribes to exposed
+ * nodes and sends values across the wire. Uses derived() + effect() for
+ * natural batch coalescing via two-phase push + bitmask resolution.
+ *
+ * Wire filtering: graph-local signals ({@link isLocalOnly}) stay local;
+ * DATA values go through the coalescing path; RESOLVED, COMPLETE, ERROR,
+ * TEARDOWN, and unknown {@link Symbol.for} types go through the signal
+ * subscription.
+ *
+ * Handshake:
+ *   1. Main creates bridge, starts listening
+ *   2. Worker sends { t: 'r', stores: { name: initialValue, ... } }
+ *   3. Main creates proxy nodes, marks meta.status "connected"
+ *   4. Main sends { t: 'i', stores: { name: currentValue, ... } }
+ *   5. Bidirectional value flow begins
+ */
+
+interface WorkerBridgeOptions<TExpose extends Record<string, Node<any>>, TImport extends readonly string[]> {
+    /** Nodes to send to the worker. */
+    expose?: TExpose;
+    /** Node names the worker will provide. */
+    import?: TImport;
+    /** Per-node transferable extractors for zero-copy ArrayBuffer passing. */
+    transfer?: Partial<Record<keyof TExpose, (value: any) => Transferable[]>>;
+    /** Debug name. */
+    name?: string;
+    /**
+     * Handshake timeout in milliseconds. If the worker doesn't send READY
+     * within this window, `meta.status` transitions to `"closed"` and
+     * `meta.error` is set. Default: no timeout.
+     */
+    timeoutMs?: number;
+}
+/** Proxy nodes created from imported worker node names. */
+type ImportedNodes<T extends readonly string[]> = {
+    readonly [K in T[number]]: Node<any>;
+};
+type WorkerBridge<_TExpose extends Record<string, Node<any>>, TImport extends readonly string[]> = ImportedNodes<TImport> & {
+    /** Connection status meta node. */
+    meta: {
+        status: Node<"connecting" | "connected" | "closed">;
+        error: Node<Error | null>;
+    };
+    /** Destroy the bridge: sends TEARDOWN, disconnects, terminates worker. */
+    destroy(): void;
+};
+declare function workerBridge<TExpose extends Record<string, Node<any>>, TImport extends readonly string[]>(target: unknown | WorkerTransport, opts: WorkerBridgeOptions<TExpose, TImport>): WorkerBridge<TExpose, TImport>;
+
+/**
+ * Wire protocol for worker bridge communication.
+ *
+ * Graph-local signals ({@link isLocalOnly}) stay local to each side's
+ * reactive graph. DATA values cross via coalescing; RESOLVED/COMPLETE/TEARDOWN
+ * as signals; ERROR as serialized payloads.
+ *
+ * Lifecycle signals serialize as string names since Symbols can't survive
+ * structured clone. Unknown {@link Symbol.for} symbols are round-tripped
+ * via their registered key.
+ */
+/** Value update — one node changed. */
+interface ValueMessage {
+    t: "v";
+    /** Node name. */
+    s: string;
+    /** Serialized value. */
+    d: unknown;
+}
+/** Lifecycle signal — serialized symbol name. */
+interface SignalMessage {
+    t: "s";
+    /** Node name, or `"*"` for bridge-wide. */
+    s: string;
+    /** Signal name string (e.g. "TEARDOWN"). */
+    sig: string;
+    /** Optional payload for custom symbols (spec §1.3.6 forward unchanged). */
+    d?: unknown;
+}
+/** Ready — worker declares its exported nodes with initial values. */
+interface ReadyMessage {
+    t: "r";
+    stores: Record<string, unknown>;
+}
+/** Init — main sends initial values of its exposed nodes. */
+interface InitMessage {
+    t: "i";
+    stores: Record<string, unknown>;
+}
+/** Batch value update — multiple nodes changed in one reactive cycle. */
+interface BatchMessage {
+    t: "b";
+    u: Record<string, unknown>;
+    /** V0 versions per node for delta sync — peer skips if version <= lastSeen (§6.0b). */
+    v?: Record<string, number>;
+}
+/** Error payload — serialized since Error objects don't survive structured clone. */
+interface ErrorMessage {
+    t: "e";
+    /** Node name. */
+    s: string;
+    /** Serialized error. */
+    err: {
+        message: string;
+        name: string;
+        stack?: string;
+    };
+}
+type BridgeMessage = ValueMessage | SignalMessage | ReadyMessage | InitMessage | BatchMessage | ErrorMessage;
+/**
+ * Serialize a message type symbol to a string for structured clone transfer.
+ *
+ * Known GraphReFly symbols map to their canonical names. Unknown symbols
+ * registered via {@link Symbol.for} use their registered key. Unregistered
+ * symbols return `"UNKNOWN"`.
+ */
+declare function signalToName(s: symbol): string;
+/**
+ * Deserialize a string back to a message type symbol.
+ *
+ * Known GraphReFly names map to their canonical symbols. Other non-empty
+ * strings are reconstructed via {@link Symbol.for} (round-trip safe for
+ * custom message types). Returns `undefined` for `"UNKNOWN"`.
+ */
+declare function nameToSignal(name: string): symbol | undefined;
+/** Serialize an error for structured clone transfer. */
+declare function serializeError(err: unknown): {
+    message: string;
+    name: string;
+    stack?: string;
+};
+/** Deserialize an error payload back to an Error object. */
+declare function deserializeError(payload: {
+    message: string;
+    name: string;
+    stack?: string;
+}): Error;
+
+/**
+ * workerSelf — worker-side reactive node bridge.
+ *
+ * Mirror of workerBridge() for the worker side. Creates proxy nodes for
+ * imports from main thread, exposes local nodes via the same wire protocol.
+ * Uses derived() + effect() for batch coalescing.
+ *
+ * Wire filtering: graph-local signals ({@link isLocalOnly}) stay local;
+ * DATA values go through the coalescing path; RESOLVED, COMPLETE, ERROR,
+ * TEARDOWN, and unknown {@link Symbol.for} types go through the signal
+ * subscription.
+ *
+ * Handshake (worker perspective):
+ *   1. workerSelf() called — creates proxy nodes for imports
+ *   2. Runs expose factory with proxy nodes -> gets nodes to expose
+ *   3. Sends { t: 'r', stores: { name: initialValue, ... } } to main
+ *   4. Receives { t: 'i', stores: { name: value, ... } } from main
+ *   5. Updates proxy nodes -> triggers local effects
+ */
+
+interface WorkerSelfOptions<TImport extends readonly string[]> {
+    /** Node names that the main thread will provide. */
+    import?: TImport;
+    /** Factory that receives imported proxy nodes and returns nodes to expose. */
+    expose: (imported: WorkerImported<TImport>) => Record<string, Node<any>>;
+    /** Per-node transferable extractors for zero-copy ArrayBuffer passing. */
+    transfer?: Record<string, (value: any) => Transferable[]>;
+}
+/** Proxy nodes available inside the worker from main-thread exposed nodes. */
+type WorkerImported<T extends readonly string[]> = {
+    readonly [K in T[number]]: Node<any>;
+};
+interface WorkerSelfHandle {
+    /** Dispose all subscriptions and stop the bridge. */
+    destroy(): void;
+}
+declare function workerSelf<TImport extends readonly string[]>(target: unknown | WorkerTransport, opts: WorkerSelfOptions<TImport>): WorkerSelfHandle;
+
+export { type BatchMessage, type BridgeMessage, type ErrorMessage, type InitMessage, type ReadyMessage, type SignalMessage, type ValueMessage, type WorkerBridge, type WorkerBridgeOptions, type WorkerSelfHandle, type WorkerSelfOptions, type WorkerTransport, createTransport, deserializeError, nameToSignal, serializeError, signalToName, workerBridge, workerSelf };

package/dist/base/worker/index.d.ts

@@ -0,0 +1,207 @@
+import { Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * WorkerTransport — normalized message channel for all worker types.
+ *
+ * Abstracts Worker, SharedWorker, ServiceWorker, BroadcastChannel, and
+ * MessagePort behind a uniform post/listen/terminate interface.
+ */
+/** Normalized bidirectional message channel. */
+interface WorkerTransport {
+    /** Send data to the other side. Optional transferables for zero-copy. */
+    post(data: unknown, transfer?: Transferable[]): void;
+    /** Listen for incoming messages. Returns unsubscribe function. */
+    listen(handler: (data: unknown) => void): () => void;
+    /** Terminate the connection (if supported by the underlying transport). */
+    terminate?(): void;
+}
+/**
+ * Auto-detect transport type and create a normalized WorkerTransport.
+ *
+ * Supports:
+ * - `Worker` — direct postMessage/onmessage
+ * - `SharedWorker` — port-based postMessage/onmessage
+ * - `ServiceWorker` — postMessage via controller, listen via navigator.serviceWorker
+ * - `BroadcastChannel` — postMessage/onmessage (no Transferable support)
+ * - `MessagePort` — direct postMessage/onmessage (worker-side SharedWorker port)
+ */
+declare function createTransport(target: unknown): WorkerTransport;
+
+/**
+ * workerBridge — main-thread reactive node bridge to a worker.
+ *
+ * Creates proxy nodes for imported worker nodes, subscribes to exposed
+ * nodes and sends values across the wire. Uses derived() + effect() for
+ * natural batch coalescing via two-phase push + bitmask resolution.
+ *
+ * Wire filtering: graph-local signals ({@link isLocalOnly}) stay local;
+ * DATA values go through the coalescing path; RESOLVED, COMPLETE, ERROR,
+ * TEARDOWN, and unknown {@link Symbol.for} types go through the signal
+ * subscription.
+ *
+ * Handshake:
+ *   1. Main creates bridge, starts listening
+ *   2. Worker sends { t: 'r', stores: { name: initialValue, ... } }
+ *   3. Main creates proxy nodes, marks meta.status "connected"
+ *   4. Main sends { t: 'i', stores: { name: currentValue, ... } }
+ *   5. Bidirectional value flow begins
+ */
+
+interface WorkerBridgeOptions<TExpose extends Record<string, Node<any>>, TImport extends readonly string[]> {
+    /** Nodes to send to the worker. */
+    expose?: TExpose;
+    /** Node names the worker will provide. */
+    import?: TImport;
+    /** Per-node transferable extractors for zero-copy ArrayBuffer passing. */
+    transfer?: Partial<Record<keyof TExpose, (value: any) => Transferable[]>>;
+    /** Debug name. */
+    name?: string;
+    /**
+     * Handshake timeout in milliseconds. If the worker doesn't send READY
+     * within this window, `meta.status` transitions to `"closed"` and
+     * `meta.error` is set. Default: no timeout.
+     */
+    timeoutMs?: number;
+}
+/** Proxy nodes created from imported worker node names. */
+type ImportedNodes<T extends readonly string[]> = {
+    readonly [K in T[number]]: Node<any>;
+};
+type WorkerBridge<_TExpose extends Record<string, Node<any>>, TImport extends readonly string[]> = ImportedNodes<TImport> & {
+    /** Connection status meta node. */
+    meta: {
+        status: Node<"connecting" | "connected" | "closed">;
+        error: Node<Error | null>;
+    };
+    /** Destroy the bridge: sends TEARDOWN, disconnects, terminates worker. */
+    destroy(): void;
+};
+declare function workerBridge<TExpose extends Record<string, Node<any>>, TImport extends readonly string[]>(target: unknown | WorkerTransport, opts: WorkerBridgeOptions<TExpose, TImport>): WorkerBridge<TExpose, TImport>;
+
+/**
+ * Wire protocol for worker bridge communication.
+ *
+ * Graph-local signals ({@link isLocalOnly}) stay local to each side's
+ * reactive graph. DATA values cross via coalescing; RESOLVED/COMPLETE/TEARDOWN
+ * as signals; ERROR as serialized payloads.
+ *
+ * Lifecycle signals serialize as string names since Symbols can't survive
+ * structured clone. Unknown {@link Symbol.for} symbols are round-tripped
+ * via their registered key.
+ */
+/** Value update — one node changed. */
+interface ValueMessage {
+    t: "v";
+    /** Node name. */
+    s: string;
+    /** Serialized value. */
+    d: unknown;
+}
+/** Lifecycle signal — serialized symbol name. */
+interface SignalMessage {
+    t: "s";
+    /** Node name, or `"*"` for bridge-wide. */
+    s: string;
+    /** Signal name string (e.g. "TEARDOWN"). */
+    sig: string;
+    /** Optional payload for custom symbols (spec §1.3.6 forward unchanged). */
+    d?: unknown;
+}
+/** Ready — worker declares its exported nodes with initial values. */
+interface ReadyMessage {
+    t: "r";
+    stores: Record<string, unknown>;
+}
+/** Init — main sends initial values of its exposed nodes. */
+interface InitMessage {
+    t: "i";
+    stores: Record<string, unknown>;
+}
+/** Batch value update — multiple nodes changed in one reactive cycle. */
+interface BatchMessage {
+    t: "b";
+    u: Record<string, unknown>;
+    /** V0 versions per node for delta sync — peer skips if version <= lastSeen (§6.0b). */
+    v?: Record<string, number>;
+}
+/** Error payload — serialized since Error objects don't survive structured clone. */
+interface ErrorMessage {
+    t: "e";
+    /** Node name. */
+    s: string;
+    /** Serialized error. */
+    err: {
+        message: string;
+        name: string;
+        stack?: string;
+    };
+}
+type BridgeMessage = ValueMessage | SignalMessage | ReadyMessage | InitMessage | BatchMessage | ErrorMessage;
+/**
+ * Serialize a message type symbol to a string for structured clone transfer.
+ *
+ * Known GraphReFly symbols map to their canonical names. Unknown symbols
+ * registered via {@link Symbol.for} use their registered key. Unregistered
+ * symbols return `"UNKNOWN"`.
+ */
+declare function signalToName(s: symbol): string;
+/**
+ * Deserialize a string back to a message type symbol.
+ *
+ * Known GraphReFly names map to their canonical symbols. Other non-empty
+ * strings are reconstructed via {@link Symbol.for} (round-trip safe for
+ * custom message types). Returns `undefined` for `"UNKNOWN"`.
+ */
+declare function nameToSignal(name: string): symbol | undefined;
+/** Serialize an error for structured clone transfer. */
+declare function serializeError(err: unknown): {
+    message: string;
+    name: string;
+    stack?: string;
+};
+/** Deserialize an error payload back to an Error object. */
+declare function deserializeError(payload: {
+    message: string;
+    name: string;
+    stack?: string;
+}): Error;
+
+/**
+ * workerSelf — worker-side reactive node bridge.
+ *
+ * Mirror of workerBridge() for the worker side. Creates proxy nodes for
+ * imports from main thread, exposes local nodes via the same wire protocol.
+ * Uses derived() + effect() for batch coalescing.
+ *
+ * Wire filtering: graph-local signals ({@link isLocalOnly}) stay local;
+ * DATA values go through the coalescing path; RESOLVED, COMPLETE, ERROR,
+ * TEARDOWN, and unknown {@link Symbol.for} types go through the signal
+ * subscription.
+ *
+ * Handshake (worker perspective):
+ *   1. workerSelf() called — creates proxy nodes for imports
+ *   2. Runs expose factory with proxy nodes -> gets nodes to expose
+ *   3. Sends { t: 'r', stores: { name: initialValue, ... } } to main
+ *   4. Receives { t: 'i', stores: { name: value, ... } } from main
+ *   5. Updates proxy nodes -> triggers local effects
+ */
+
+interface WorkerSelfOptions<TImport extends readonly string[]> {
+    /** Node names that the main thread will provide. */
+    import?: TImport;
+    /** Factory that receives imported proxy nodes and returns nodes to expose. */
+    expose: (imported: WorkerImported<TImport>) => Record<string, Node<any>>;
+    /** Per-node transferable extractors for zero-copy ArrayBuffer passing. */
+    transfer?: Record<string, (value: any) => Transferable[]>;
+}
+/** Proxy nodes available inside the worker from main-thread exposed nodes. */
+type WorkerImported<T extends readonly string[]> = {
+    readonly [K in T[number]]: Node<any>;
+};
+interface WorkerSelfHandle {
+    /** Dispose all subscriptions and stop the bridge. */
+    destroy(): void;
+}
+declare function workerSelf<TImport extends readonly string[]>(target: unknown | WorkerTransport, opts: WorkerSelfOptions<TImport>): WorkerSelfHandle;
+
+export { type BatchMessage, type BridgeMessage, type ErrorMessage, type InitMessage, type ReadyMessage, type SignalMessage, type ValueMessage, type WorkerBridge, type WorkerBridgeOptions, type WorkerSelfHandle, type WorkerSelfOptions, type WorkerTransport, createTransport, deserializeError, nameToSignal, serializeError, signalToName, workerBridge, workerSelf };

package/dist/base/worker/index.js

@@ -0,0 +1,20 @@
+import {
+  createTransport,
+  deserializeError,
+  nameToSignal,
+  serializeError,
+  signalToName,
+  workerBridge,
+  workerSelf
+} from "../../chunk-NDUD3IMO.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  createTransport,
+  deserializeError,
+  nameToSignal,
+  serializeError,
+  signalToName,
+  workerBridge,
+  workerSelf
+};
+//# sourceMappingURL=index.js.map

package/dist/base/worker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/breaker-C9skL3d8.d.ts

@@ -0,0 +1,175 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.js';
+import { B as BackoffStrategy } from './backoff-Bnb9OoPh.js';
+
+/**
+ * Central gate-state vocabulary for resilience primitives.
+ *
+ * **DS-13.5.B follow-on (locked 2026-05-01).** Two-state base enum
+ * (`"open" | "closed"`) used as the literal vocabulary inside
+ * gate-shaped `<Primitive>State` companions on `budgetGate`. Other
+ * primitives extend this base with primitive-specific values:
+ *
+ * - `rateLimiter` → `GateState | "throttled"`.
+ * - `circuitBreaker` → `GateState | "half-open"`.
+ *
+ * Keeping the base as a separate exported type lets callers narrow
+ * generic gate-state consumers without coupling to any one primitive's
+ * extension axis.
+ *
+ * @category extra/resilience
+ */
+type GateState = "open" | "closed";
+
+/**
+ * Circuit breaker — open/half-open/closed state machine + companion bundle.
+ *
+ * - {@link circuitBreaker} returns a synchronous breaker handle (counters,
+ *   state machine, optional reactive-options subscription).
+ * - {@link withBreaker} wraps a `Node<T>` and surfaces a reactive
+ *   `Node<CircuitState>` companion (`bundle.breakerState`) for telemetry.
+ */
+
+type CircuitState = "closed" | "open" | "half-open";
+/**
+ * Lifecycle-shaped state companion emitted by {@link withBreaker}
+ * (DS-13.5.B, locked 2026-05-01). Pre-1.0 break vs the prior
+ * `Node<CircuitState>` (string-only) shape.
+ *
+ * `status` extends {@link GateState} with `"half-open"`. The numeric
+ * fields surface the breaker's full internal state for telemetry and
+ * `describe()` traversal.
+ *
+ * @category extra/resilience
+ */
+interface BreakerState {
+    readonly status: GateState | "half-open";
+    readonly failureCount: number;
+    readonly openCycle: number;
+    readonly lastOpenedAtNs: number;
+    readonly halfOpenAttempts: number;
+    readonly lastCooldownNs: number;
+}
+/**
+ * Thrown when {@link withBreaker} is configured with `onOpen: "error"` and the breaker rejects work.
+ *
+ * @category extra
+ */
+declare class CircuitOpenError extends Error {
+    name: string;
+    constructor();
+}
+interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening. Default: 5. */
+    failureThreshold?: number;
+    /** Base cooldown in nanoseconds before transitioning to half-open. Default: 30s. */
+    cooldownNs?: number;
+    /** Backoff strategy for cooldown escalation across consecutive open cycles. Overrides `cooldownNs` when provided. */
+    cooldown?: BackoffStrategy;
+    /** Max trial requests allowed in half-open state. Default: 1. */
+    halfOpenMax?: number;
+    /**
+     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
+     * (monotonically non-decreasing; suitable for elapsed-time arithmetic — never
+     * use `Date.now()` because wall-clock skew can flip elapsed math negative).
+     * Default: `monotonicNs` from `core/clock`. Override for deterministic tests.
+     */
+    now?: () => number;
+}
+interface CircuitBreaker {
+    /** Whether a request should be allowed through. Triggers open→half-open transition when cooldown expires. */
+    canExecute(): boolean;
+    /** Record a successful execution. Resets to closed. */
+    recordSuccess(): void;
+    /** Record a failed execution. May transition to open. */
+    recordFailure(error?: unknown): void;
+    /**
+     * Current circuit state (read-only, does not trigger transitions).
+     *
+     * **Telemetry:** wrap with {@link withBreaker} to surface this as a reactive
+     * `Node<CircuitState>` companion (`bundle.breakerState`) — every state
+     * transition (`closed`/`open`/`half-open`) emits to subscribers.
+     */
+    readonly state: CircuitState;
+    /** Number of consecutive failures in the current closed period. */
+    readonly failureCount: number;
+    /** Manually reset to closed state, clearing all counters. */
+    reset(): void;
+    /**
+     * Release the reactive-options subscription (Tier 6.5 3.2.4, 2026-04-29).
+     * No-op when constructed with static options. Call when retiring a
+     * breaker whose options came from a `Node<CircuitBreakerOptions>` to
+     * avoid leaking the option-Node subscription.
+     */
+    dispose(): void;
+}
+/**
+ * Factory for a synchronous circuit breaker with `closed`, `open`, and `half-open` states.
+ *
+ * Supports escalating cooldown via an optional {@link BackoffStrategy} — each consecutive
+ * open→half-open→open cycle increments the backoff attempt.
+ *
+ * @param options - Threshold, cooldown, half-open limit, and optional clock
+ *   override; OR a `Node<CircuitBreakerOptions>` carrying the same shape
+ *   reactively (Tier 6.5 3.2.4).
+ * @returns {@link CircuitBreaker} instance.
+ *
+ * @remarks
+ * **Timing:** Uses `monotonicNs()` by default (nanoseconds). Override `now` for tests.
+ *
+ * **Reactive options (locked semantics, Tier 6.5 3.2.4, 2026-04-29).**
+ * When `options` is a `Node<CircuitBreakerOptions>`, the breaker
+ * subscribes at construction and re-reads `failureThreshold` /
+ * `cooldownNs` / `cooldown` / `halfOpenMax` / `now` on each DATA. **An
+ * option swap RESETS the breaker to `"closed"`** with all counters
+ * cleared — operators tuning a runaway breaker get a clean baseline.
+ * If retaining failure history across re-tunings matters, derive a new
+ * breaker per-tuning instead. Call `breaker.dispose()` when retiring to
+ * release the option-Node subscription.
+ *
+ * @example
+ * ```ts
+ * import { circuitBreaker, exponential, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
+ *
+ * const b = circuitBreaker({
+ *   failureThreshold: 3,
+ *   cooldown: exponential({ baseNs: 1 * NS_PER_SEC }),
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function circuitBreaker(options?: NodeOrValue<CircuitBreakerOptions>): CircuitBreaker;
+type WithBreakerBundle<T> = {
+    node: Node<T>;
+    breakerState: Node<BreakerState>;
+};
+/**
+ * Returns a unary wrapper that gates upstream `DATA` through a {@link CircuitBreaker}.
+ *
+ * @param breaker - Shared breaker instance (typically one per resource).
+ * @param options - `onOpen: "skip"` emits `RESOLVED` when open; `"error"` emits {@link CircuitOpenError}.
+ * @returns Function mapping `Node<T>` to `{ node, breakerState }` companion nodes.
+ *
+ * @remarks
+ * **Success path:** `COMPLETE` calls {@link CircuitBreaker.recordSuccess}. **Failure path:** upstream `ERROR` calls {@link CircuitBreaker.recordFailure} and is forwarded.
+ *
+ * **State telemetry:** `breakerState: Node<CircuitState>` is a reactive companion that mirrors `breaker.state` — every transition (`closed`/`open`/`half-open`) emits a `DATA`. Also accessible via `node.meta.breakerState` for `describe()` traversal.
+ *
+ * @example
+ * ```ts
+ * import { state, withBreaker, circuitBreaker } from "@graphrefly/graphrefly-ts";
+ *
+ * const b = circuitBreaker({ failureThreshold: 2 });
+ * const s = state(1);
+ * const { node, breakerState } = withBreaker(b)(s);
+ * ```
+ *
+ * @category extra
+ */
+declare function withBreaker<T>(breaker: CircuitBreaker, options?: {
+    onOpen?: "skip" | "error";
+    meta?: Record<string, unknown>;
+}): (source: Node<T>) => WithBreakerBundle<T>;
+
+export { type BreakerState as B, type CircuitBreaker as C, type GateState as G, type WithBreakerBundle as W, type CircuitBreakerOptions as a, CircuitOpenError as b, type CircuitState as c, circuitBreaker as d, withBreaker as w };