@graphrefly/graphrefly 0.43.0 → 0.44.0

package/dist/{graph-C4SHb3Ly.d.cts → graph-CWvEUQAq.d.cts}

@@ -1,5 +1,5 @@
-import { A as Actor, n as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-ClS5yC-B.cjs';
-import { D as DescribeNodeOutput, a as DescribeDetail, b as DescribeField } from './meta-vE8bxW1E.cjs';
+import { A as Actor, l as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-kK3CvTrR.cjs';
+import { D as DescribeNodeOutput, a as DerivedFn, E as EffectFn, c as DescribeDetail, d as DescribeField } from './sugar-DQjFmVqb.cjs';
 import { StorageHandle } from './extra/storage-core.cjs';
 import { SnapshotStorageTier } from './extra/storage-tiers.cjs';
 
@@ -334,6 +334,73 @@ interface GraphOptions {
     factoryArgs?: unknown;
     [key: string]: unknown;
 }
+/**
+ * Options for {@link Graph.derived}. Forwarded to the underlying
+ * {@link derived} primitive plus graph-level extras.
+ *
+ * - `keepAlive: true` — installs an internal subscription so the node
+ *   stays activated and `.cache` stays current for **external consumers**
+ *   (UI render, debug snapshot, audit log) with no real subscriber. The
+ *   subscription self-prunes on the node's terminal (`COMPLETE` / `ERROR`
+ *   / `TEARDOWN`) and is also drained by {@link Graph.destroy}, so
+ *   repeated `graph.remove(name)` cycles do not accumulate stale
+ *   disposers.
+ *
+ *   **Do not read `node.cache` from inside another reactive fn** (spec
+ *   §5.12) — declare the node as a real dep instead. `keepAlive` is a
+ *   convenience for *external* read patterns, not a shortcut around the
+ *   message protocol.
+ * - `signal` — when aborted, removes this node from the graph via
+ *   {@link Graph.remove}, which sends `[[TEARDOWN]]` and drains cleanup
+ *   hooks. Already-aborted signals trigger removal synchronously.
+ * - `equals`, `initial`, `meta` — pass-through to {@link NodeOptions}.
+ * - `annotation` — forwarded to {@link Graph.add} (see `graph.trace`).
+ */
+interface GraphDerivedOptions<T> {
+    equals?: (a: T, b: T) => boolean;
+    initial?: T | null;
+    keepAlive?: boolean;
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    annotation?: string;
+}
+/**
+ * Options for {@link Graph.effect}.
+ *
+ * - `signal` — when aborted, removes this node from the graph via
+ *   {@link Graph.remove} (fires the effect's `deactivate` cleanup).
+ * - `meta` / `annotation` — same forwarding shape as
+ *   {@link GraphDerivedOptions}.
+ */
+interface GraphEffectOptions {
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    annotation?: string;
+}
+/**
+ * Options for {@link Graph.produce}.
+ *
+ * - `signal` — forwarded to the underlying {@link fromAny} for in-flight
+ *   cancellation of `Promise` / `AsyncIterable` sources, AND triggers
+ *   {@link Graph.remove} when aborted so the graph topology reflects the
+ *   cancellation.
+ * - `equals` / `meta` / `annotation` — same forwarding shape as
+ *   {@link GraphDerivedOptions}.
+ */
+interface GraphProduceOptions<T> {
+    equals?: (a: T, b: T) => boolean;
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    annotation?: string;
+}
+/**
+ * Source shapes accepted by {@link Graph.produce}. Excludes `Node<T>` —
+ * Node→Node passthrough is rejected at the boundary because `fromAny`
+ * passes Nodes through verbatim, which would silently drop `meta`/`equals`
+ * options and bypass the `add()` registration's name semantics. For
+ * Node→Node, use {@link Graph.derived} with `keepAlive: true` instead.
+ */
+type GraphProduceInput<T> = PromiseLike<T> | AsyncIterable<T> | Iterable<T> | T;
 /** Filter for {@link Graph.describe} — object-style partial match or predicate. */
 type DescribeFilter = Partial<Pick<DescribeNodeOutput, "type" | "status">> | {
     type?: DescribeNodeOutput["type"];
@@ -1035,6 +1102,115 @@ declare class Graph {
      * TEARDOWN and unregisters the node).
      */
     complete(name: string, options?: GraphActorOptions): void;
+    /**
+     * Internal: register a self-pruning keepalive subscription. The sink
+     * watches for terminal messages (`COMPLETE`/`ERROR`/`TEARDOWN`) on `n`
+     * and removes the disposer from `_disposers` when one arrives, so
+     * repeated `graph.remove(name)` cycles do not accumulate stale
+     * disposers (qa B3).
+     */
+    private _registerSelfPruningKeepalive;
+    /**
+     * Internal: wire an `AbortSignal` so its abort triggers
+     * `graph.remove(name)`. Already-aborted signals trigger removal
+     * synchronously. The abort listener is itself registered as a graph
+     * disposer so it gets cleaned up if `destroy()` runs first (qa B4).
+     */
+    private _wireSignalToRemove;
+    /**
+     * Path-based reactive derivation. Resolves each entry in `depPaths` via
+     * {@link Graph.resolve}, builds a {@link derived} node, registers it via
+     * {@link Graph.add}, and returns the registered Node.
+     *
+     * **First-run gate inherited.** fn does not fire until every dep has
+     * delivered at least one real DATA — same gate as `derived()` (spec §2.7,
+     * `partial: false`). A SENTINEL dep holds activation; `null` is a real
+     * DATA value and releases the gate. **Empty `depPaths` is a vacuous
+     * gate** — fn fires once synchronously on first activation. Use this
+     * for one-shot constants only; for async sources prefer
+     * {@link Graph.produce}.
+     *
+     * **`keepAlive: true`** — installs an internal subscription so the node
+     * stays activated and `.cache` stays current for **external consumers**
+     * (UI render, debug snapshot, audit log). The subscription self-prunes
+     * on the node's terminal and is also drained by {@link Graph.destroy}.
+     *
+     * **Do not read `node.cache` from inside another reactive fn** — that
+     * is a §5.12 boundary violation regardless of `keepAlive`. Declare the
+     * node as a real dep instead so the edge appears in `describe()` and
+     * the message protocol carries the value.
+     *
+     * **`signal`** — when aborted, removes this node from the graph.
+     *
+     * @param name - Local registration name (must be unique on this graph).
+     * @param depPaths - `::`-qualified paths resolved at construction time.
+     * @param fn - Pure compute receiving sugar-unwrapped scalar dep values.
+     * @param opts - {@link GraphDerivedOptions}.
+     * @returns The registered `Node<T>`.
+     */
+    derived<T>(name: string, depPaths: readonly string[], fn: DerivedFn<T>, opts?: GraphDerivedOptions<T>): Node<T>;
+    /**
+     * Path-based managed side effect. Resolves each entry in `depPaths`,
+     * builds an {@link effect} node, registers it, and returns the
+     * registered Node. fn does not auto-emit — call `actions.emit(v)` /
+     * `actions.down(msgs)` explicitly to produce downstream messages.
+     *
+     * **Cleanup.** Return a cleanup function (`() => void`) or granular
+     * hooks (`{ beforeRun?, deactivate?, invalidate? }`) — fired on the
+     * matching transition by the underlying primitive (see
+     * {@link NodeFnCleanup}). Graph teardown propagates `[[TEARDOWN]]`
+     * which triggers `deactivate`.
+     *
+     * **`signal`** — when aborted, removes this node from the graph (fires
+     * the effect's `deactivate` cleanup).
+     *
+     * @param name - Local registration name (must be unique on this graph).
+     * @param depPaths - `::`-qualified paths resolved at construction time.
+     * @param fn - Side-effect receiving sugar-unwrapped scalar dep values.
+     * @param opts - {@link GraphEffectOptions}.
+     * @returns The registered `Node<unknown>`.
+     */
+    effect(name: string, depPaths: readonly string[], fn: EffectFn, opts?: GraphEffectOptions): Node<unknown>;
+    /**
+     * Wraps an external/async source as a named graph node via
+     * {@link fromAny}. Accepts {@link GraphProduceInput} shapes:
+     * `Promise`, `AsyncIterable`, `Iterable`, or scalar.
+     *
+     * **Node sources are rejected.** For `Node → Node`, use
+     * {@link Graph.derived} with `keepAlive: true` — `fromAny` would
+     * passthrough a Node verbatim and silently drop `meta`/`equals`
+     * options. The type signature excludes `Node<T>`; a runtime guard
+     * catches casts.
+     *
+     * **`undefined` is rejected.** `undefined` is the global SENTINEL;
+     * emitting it as DATA would corrupt downstream first-run gates.
+     * `null` (a valid DATA value) is accepted.
+     *
+     * **`signal`** — forwarded to {@link fromAny} for in-flight cancel of
+     * Promise/AsyncIterable sources, AND triggers {@link Graph.remove}
+     * when aborted so the topology reflects the cancellation.
+     *
+     * @param name - Local registration name (must be unique on this graph).
+     * @param source - Any {@link GraphProduceInput} shape.
+     * @param opts - {@link GraphProduceOptions}.
+     * @returns The registered `Node<T>`.
+     */
+    produce<T>(name: string, source: GraphProduceInput<T>, opts?: GraphProduceOptions<T>): Node<T>;
+    /**
+     * Atomic multi-mutation. Same semantics as core {@link batch}: DATA and
+     * RESOLVED emissions inside `fn` defer, DIRTY propagates immediately, and
+     * downstream consumers see one coalesced wave (spec §1.3 invariant 7).
+     * Exposed on `Graph` for discoverability and import hygiene — pattern
+     * authors can reach for `graph.batch(...)` without importing `batch` from
+     * the core entry. Shares one global frame with the core import; nesting
+     * either way is supported.
+     *
+     * **Caveat:** if `fn` throws, deferred DATA is discarded but DIRTY
+     * messages already propagated synchronously, leaving downstream nodes
+     * in `dirty` status with stale `.cache`. Catch and emit compensating
+     * INVALIDATE/RESET if you need to recover.
+     */
+    batch(fn: () => void): void;
     /**
      * Returns the full edge list for this graph tree, derived on demand from
      * each registered node's `_deps` (no stored registry). Local-only
@@ -1221,6 +1397,13 @@ declare class Graph {
      *   When `reactive: true`, also accepts `name?`.
      */
     explain(from: string | Node<string>, to: string | Node<string>, opts?: {
+        /**
+         * DF13 (2026-04-29) — narrow the static overload to forbid
+         * `reactive: true`. A caller passing `{ reactive: true, ... }`
+         * is steered into the reactive overload instead of falling
+         * through to the implementation signature's union return.
+         */
+        reactive?: false;
         maxDepth?: number | Node<number>;
         findCycle?: boolean | Node<boolean>;
     }): CausalChain;
@@ -1333,7 +1516,17 @@ declare class Graph {
      * stays `true` even if the instance is later reused via {@link add}.
      */
     get destroyed(): boolean;
-    /** Clear structure after parent already signaled TEARDOWN through this subtree. */
+    /**
+     * Clear structure after parent already signaled TEARDOWN through this subtree.
+     *
+     * Drains both `_disposers` and `_storageDisposers` to mirror the full
+     * {@link destroy} path — child mounts that registered disposers via
+     * {@link addDisposer} (audit trails, log dispose hooks, off-event
+     * callbacks, attached storage) would otherwise leak when destruction
+     * reaches the subtree via the parent's TEARDOWN cascade rather than a
+     * direct `destroy()` call (EH-2). Disposers run BEFORE structure clear
+     * so cleanups can still resolve node paths if needed.
+     */
     private _destroyClearOnly;
     /**
      * Serializes structure and current values to JSON-shaped data (§3.8). Same

package/dist/{graph-7VguS7a4.d.ts → graph-D9LFnda9.d.ts}

@@ -1,5 +1,5 @@
-import { A as Actor, n as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-ClS5yC-B.js';
-import { D as DescribeNodeOutput, a as DescribeDetail, b as DescribeField } from './meta-BgVAsg9j.js';
+import { A as Actor, l as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-kK3CvTrR.js';
+import { D as DescribeNodeOutput, a as DerivedFn, E as EffectFn, c as DescribeDetail, d as DescribeField } from './sugar-fhLIE7TT.js';
 import { StorageHandle } from './extra/storage-core.js';
 import { SnapshotStorageTier } from './extra/storage-tiers.js';
 
@@ -334,6 +334,73 @@ interface GraphOptions {
     factoryArgs?: unknown;
     [key: string]: unknown;
 }
+/**
+ * Options for {@link Graph.derived}. Forwarded to the underlying
+ * {@link derived} primitive plus graph-level extras.
+ *
+ * - `keepAlive: true` — installs an internal subscription so the node
+ *   stays activated and `.cache` stays current for **external consumers**
+ *   (UI render, debug snapshot, audit log) with no real subscriber. The
+ *   subscription self-prunes on the node's terminal (`COMPLETE` / `ERROR`
+ *   / `TEARDOWN`) and is also drained by {@link Graph.destroy}, so
+ *   repeated `graph.remove(name)` cycles do not accumulate stale
+ *   disposers.
+ *
+ *   **Do not read `node.cache` from inside another reactive fn** (spec
+ *   §5.12) — declare the node as a real dep instead. `keepAlive` is a
+ *   convenience for *external* read patterns, not a shortcut around the
+ *   message protocol.
+ * - `signal` — when aborted, removes this node from the graph via
+ *   {@link Graph.remove}, which sends `[[TEARDOWN]]` and drains cleanup
+ *   hooks. Already-aborted signals trigger removal synchronously.
+ * - `equals`, `initial`, `meta` — pass-through to {@link NodeOptions}.
+ * - `annotation` — forwarded to {@link Graph.add} (see `graph.trace`).
+ */
+interface GraphDerivedOptions<T> {
+    equals?: (a: T, b: T) => boolean;
+    initial?: T | null;
+    keepAlive?: boolean;
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    annotation?: string;
+}
+/**
+ * Options for {@link Graph.effect}.
+ *
+ * - `signal` — when aborted, removes this node from the graph via
+ *   {@link Graph.remove} (fires the effect's `deactivate` cleanup).
+ * - `meta` / `annotation` — same forwarding shape as
+ *   {@link GraphDerivedOptions}.
+ */
+interface GraphEffectOptions {
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    annotation?: string;
+}
+/**
+ * Options for {@link Graph.produce}.
+ *
+ * - `signal` — forwarded to the underlying {@link fromAny} for in-flight
+ *   cancellation of `Promise` / `AsyncIterable` sources, AND triggers
+ *   {@link Graph.remove} when aborted so the graph topology reflects the
+ *   cancellation.
+ * - `equals` / `meta` / `annotation` — same forwarding shape as
+ *   {@link GraphDerivedOptions}.
+ */
+interface GraphProduceOptions<T> {
+    equals?: (a: T, b: T) => boolean;
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    annotation?: string;
+}
+/**
+ * Source shapes accepted by {@link Graph.produce}. Excludes `Node<T>` —
+ * Node→Node passthrough is rejected at the boundary because `fromAny`
+ * passes Nodes through verbatim, which would silently drop `meta`/`equals`
+ * options and bypass the `add()` registration's name semantics. For
+ * Node→Node, use {@link Graph.derived} with `keepAlive: true` instead.
+ */
+type GraphProduceInput<T> = PromiseLike<T> | AsyncIterable<T> | Iterable<T> | T;
 /** Filter for {@link Graph.describe} — object-style partial match or predicate. */
 type DescribeFilter = Partial<Pick<DescribeNodeOutput, "type" | "status">> | {
     type?: DescribeNodeOutput["type"];
@@ -1035,6 +1102,115 @@ declare class Graph {
      * TEARDOWN and unregisters the node).
      */
     complete(name: string, options?: GraphActorOptions): void;
+    /**
+     * Internal: register a self-pruning keepalive subscription. The sink
+     * watches for terminal messages (`COMPLETE`/`ERROR`/`TEARDOWN`) on `n`
+     * and removes the disposer from `_disposers` when one arrives, so
+     * repeated `graph.remove(name)` cycles do not accumulate stale
+     * disposers (qa B3).
+     */
+    private _registerSelfPruningKeepalive;
+    /**
+     * Internal: wire an `AbortSignal` so its abort triggers
+     * `graph.remove(name)`. Already-aborted signals trigger removal
+     * synchronously. The abort listener is itself registered as a graph
+     * disposer so it gets cleaned up if `destroy()` runs first (qa B4).
+     */
+    private _wireSignalToRemove;
+    /**
+     * Path-based reactive derivation. Resolves each entry in `depPaths` via
+     * {@link Graph.resolve}, builds a {@link derived} node, registers it via
+     * {@link Graph.add}, and returns the registered Node.
+     *
+     * **First-run gate inherited.** fn does not fire until every dep has
+     * delivered at least one real DATA — same gate as `derived()` (spec §2.7,
+     * `partial: false`). A SENTINEL dep holds activation; `null` is a real
+     * DATA value and releases the gate. **Empty `depPaths` is a vacuous
+     * gate** — fn fires once synchronously on first activation. Use this
+     * for one-shot constants only; for async sources prefer
+     * {@link Graph.produce}.
+     *
+     * **`keepAlive: true`** — installs an internal subscription so the node
+     * stays activated and `.cache` stays current for **external consumers**
+     * (UI render, debug snapshot, audit log). The subscription self-prunes
+     * on the node's terminal and is also drained by {@link Graph.destroy}.
+     *
+     * **Do not read `node.cache` from inside another reactive fn** — that
+     * is a §5.12 boundary violation regardless of `keepAlive`. Declare the
+     * node as a real dep instead so the edge appears in `describe()` and
+     * the message protocol carries the value.
+     *
+     * **`signal`** — when aborted, removes this node from the graph.
+     *
+     * @param name - Local registration name (must be unique on this graph).
+     * @param depPaths - `::`-qualified paths resolved at construction time.
+     * @param fn - Pure compute receiving sugar-unwrapped scalar dep values.
+     * @param opts - {@link GraphDerivedOptions}.
+     * @returns The registered `Node<T>`.
+     */
+    derived<T>(name: string, depPaths: readonly string[], fn: DerivedFn<T>, opts?: GraphDerivedOptions<T>): Node<T>;
+    /**
+     * Path-based managed side effect. Resolves each entry in `depPaths`,
+     * builds an {@link effect} node, registers it, and returns the
+     * registered Node. fn does not auto-emit — call `actions.emit(v)` /
+     * `actions.down(msgs)` explicitly to produce downstream messages.
+     *
+     * **Cleanup.** Return a cleanup function (`() => void`) or granular
+     * hooks (`{ beforeRun?, deactivate?, invalidate? }`) — fired on the
+     * matching transition by the underlying primitive (see
+     * {@link NodeFnCleanup}). Graph teardown propagates `[[TEARDOWN]]`
+     * which triggers `deactivate`.
+     *
+     * **`signal`** — when aborted, removes this node from the graph (fires
+     * the effect's `deactivate` cleanup).
+     *
+     * @param name - Local registration name (must be unique on this graph).
+     * @param depPaths - `::`-qualified paths resolved at construction time.
+     * @param fn - Side-effect receiving sugar-unwrapped scalar dep values.
+     * @param opts - {@link GraphEffectOptions}.
+     * @returns The registered `Node<unknown>`.
+     */
+    effect(name: string, depPaths: readonly string[], fn: EffectFn, opts?: GraphEffectOptions): Node<unknown>;
+    /**
+     * Wraps an external/async source as a named graph node via
+     * {@link fromAny}. Accepts {@link GraphProduceInput} shapes:
+     * `Promise`, `AsyncIterable`, `Iterable`, or scalar.
+     *
+     * **Node sources are rejected.** For `Node → Node`, use
+     * {@link Graph.derived} with `keepAlive: true` — `fromAny` would
+     * passthrough a Node verbatim and silently drop `meta`/`equals`
+     * options. The type signature excludes `Node<T>`; a runtime guard
+     * catches casts.
+     *
+     * **`undefined` is rejected.** `undefined` is the global SENTINEL;
+     * emitting it as DATA would corrupt downstream first-run gates.
+     * `null` (a valid DATA value) is accepted.
+     *
+     * **`signal`** — forwarded to {@link fromAny} for in-flight cancel of
+     * Promise/AsyncIterable sources, AND triggers {@link Graph.remove}
+     * when aborted so the topology reflects the cancellation.
+     *
+     * @param name - Local registration name (must be unique on this graph).
+     * @param source - Any {@link GraphProduceInput} shape.
+     * @param opts - {@link GraphProduceOptions}.
+     * @returns The registered `Node<T>`.
+     */
+    produce<T>(name: string, source: GraphProduceInput<T>, opts?: GraphProduceOptions<T>): Node<T>;
+    /**
+     * Atomic multi-mutation. Same semantics as core {@link batch}: DATA and
+     * RESOLVED emissions inside `fn` defer, DIRTY propagates immediately, and
+     * downstream consumers see one coalesced wave (spec §1.3 invariant 7).
+     * Exposed on `Graph` for discoverability and import hygiene — pattern
+     * authors can reach for `graph.batch(...)` without importing `batch` from
+     * the core entry. Shares one global frame with the core import; nesting
+     * either way is supported.
+     *
+     * **Caveat:** if `fn` throws, deferred DATA is discarded but DIRTY
+     * messages already propagated synchronously, leaving downstream nodes
+     * in `dirty` status with stale `.cache`. Catch and emit compensating
+     * INVALIDATE/RESET if you need to recover.
+     */
+    batch(fn: () => void): void;
     /**
      * Returns the full edge list for this graph tree, derived on demand from
      * each registered node's `_deps` (no stored registry). Local-only
@@ -1221,6 +1397,13 @@ declare class Graph {
      *   When `reactive: true`, also accepts `name?`.
      */
     explain(from: string | Node<string>, to: string | Node<string>, opts?: {
+        /**
+         * DF13 (2026-04-29) — narrow the static overload to forbid
+         * `reactive: true`. A caller passing `{ reactive: true, ... }`
+         * is steered into the reactive overload instead of falling
+         * through to the implementation signature's union return.
+         */
+        reactive?: false;
         maxDepth?: number | Node<number>;
         findCycle?: boolean | Node<boolean>;
     }): CausalChain;
@@ -1333,7 +1516,17 @@ declare class Graph {
      * stays `true` even if the instance is later reused via {@link add}.
      */
     get destroyed(): boolean;
-    /** Clear structure after parent already signaled TEARDOWN through this subtree. */
+    /**
+     * Clear structure after parent already signaled TEARDOWN through this subtree.
+     *
+     * Drains both `_disposers` and `_storageDisposers` to mirror the full
+     * {@link destroy} path — child mounts that registered disposers via
+     * {@link addDisposer} (audit trails, log dispose hooks, off-event
+     * callbacks, attached storage) would otherwise leak when destruction
+     * reaches the subtree via the parent's TEARDOWN cascade rather than a
+     * direct `destroy()` call (EH-2). Disposers run BEFORE structure clear
+     * so cleanups can still resolve node paths if needed.
+     */
     private _destroyClearOnly;
     /**
      * Serializes structure and current values to JSON-shaped data (§3.8). Same

package/dist/{index-O7fucFrU.d.cts → index-5k1T6jl0.d.cts}

@@ -1,12 +1,12 @@
-import { i as index$2 } from './index-ChOyVLKm.cjs';
-import { i as index$3 } from './index-C9kSENB4.cjs';
-import { i as index$4 } from './index-BAOD98JD.cjs';
-import { i as index$5 } from './index-z96luz5O.cjs';
-import { N as Node } from './node-ClS5yC-B.cjs';
-import { i as index$6 } from './index-BVpm6noz.cjs';
-import { i as index$7 } from './index-hHcaFlJX.cjs';
-import { i as index$8 } from './index-BJX94aud.cjs';
-import { i as index$9 } from './index-f5IivDUX.cjs';
+import { i as index$2 } from './index-BrPrLl4e.cjs';
+import { i as index$3 } from './index-BQSKmbuG.cjs';
+import { i as index$4 } from './index-Climxqsu.cjs';
+import { i as index$5 } from './index-C5stwKcw.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
+import { i as index$6 } from './index-hcDJ8PSI.cjs';
+import { i as index$7 } from './index-_6ODbuOu.cjs';
+import { i as index$8 } from './index-CK29LV56.cjs';
+import { i as index$9 } from './index-ZVQhLa2i.cjs';
 
 /**
  * Options for creating signals.

package/dist/{index-DyR7eU5S.d.cts → index-9770hRuQ.d.cts}

@@ -1,7 +1,7 @@
-import { A as Actor, N as Node, W as PolicyRuleData, o as GuardAction } from './node-ClS5yC-B.cjs';
-import { G as Graph, a as GraphOptions, r as GraphPersistSnapshot, b as GraphDescribeOutput, j as GraphDescribeOptions, C as CausalChain, e as DescribeFilter } from './graph-C4SHb3Ly.cjs';
-import { T as TopicGraph } from './index-BTQtTb_H.cjs';
-import { w as watchTopologyTree } from './topology-tree-BSdfSwMi.cjs';
+import { A as Actor, N as Node, W as PolicyRuleData, m as GuardAction } from './node-kK3CvTrR.cjs';
+import { G as Graph, a as GraphOptions, r as GraphPersistSnapshot, b as GraphDescribeOutput, j as GraphDescribeOptions, C as CausalChain, e as DescribeFilter } from './graph-CWvEUQAq.cjs';
+import { T as TopicGraph } from './index-C5ri2Axc.cjs';
+import { w as watchTopologyTree } from './topology-tree-Bcz27hpF.cjs';
 
 /**
  * Audit, policy enforcement, and compliance export (roadmap §9.2).

package/dist/{index-COD1kVoS.d.cts → index-B-_tFaqV.d.cts}

@@ -1,8 +1,8 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
-import { B as BaseAuditRecord } from './index-C9pjcz3l.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-B00laMSQ.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
+import { B as BaseAuditRecord } from './index-D0aciIex.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
 import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
-import { a as GraphOptions, G as Graph } from './graph-C4SHb3Ly.cjs';
+import { a as GraphOptions, G as Graph } from './graph-CWvEUQAq.cjs';
 
 /**
  * CQRS patterns (roadmap §4.5).

package/dist/{index-CLon-IWF.d.cts → index-B17QddL1.d.cts}

@@ -1,7 +1,7 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
-import { B as BaseAuditRecord } from './index-C9pjcz3l.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-B00laMSQ.cjs';
-import { G as Graph } from './graph-C4SHb3Ly.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
+import { B as BaseAuditRecord } from './index-D0aciIex.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
+import { G as Graph } from './graph-CWvEUQAq.cjs';
 
 /**
  * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under

package/dist/{index-B-i4_g3k.d.ts → index-B1F8Enjf.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-ClS5yC-B.js';
+import { N as Node } from './node-kK3CvTrR.js';
 
 /**
  * Backoff strategies for {@link retry} (roadmap §3.1). Delays are in **nanoseconds**.
@@ -227,8 +227,8 @@ type RetryFactoryOptions<T> = RetryOptions & {
  *
  * @category extra
  */
-declare function retry<T>(input: Node<T>, opts?: RetryOptions): Node<T>;
-declare function retry<T>(input: () => Node<T>, opts?: RetryFactoryOptions<T>): Node<T>;
+declare function retry<T>(input: Node<T>, opts?: NodeOrValue<RetryOptions>): Node<T>;
+declare function retry<T>(input: () => Node<T>, opts?: NodeOrValue<RetryFactoryOptions<T>>): Node<T>;
 type CircuitState = "closed" | "open" | "half-open";
 /**
  * Thrown when {@link withBreaker} is configured with `onOpen: "error"` and the breaker rejects work.
@@ -275,6 +275,13 @@ interface CircuitBreaker {
     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.
@@ -282,12 +289,24 @@ interface CircuitBreaker {
  * 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.
+ * @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";
@@ -300,7 +319,7 @@ interface CircuitBreaker {
  *
  * @category extra
  */
-declare function circuitBreaker(options?: CircuitBreakerOptions): CircuitBreaker;
+declare function circuitBreaker(options?: NodeOrValue<CircuitBreakerOptions>): CircuitBreaker;
 type WithBreakerBundle<T> = {
     node: Node<T>;
     breakerState: Node<CircuitState>;
@@ -525,7 +544,7 @@ type RateLimiterBundle<T> = {
  *
  * @category extra
  */
-declare function rateLimiter<T>(source: Node<T>, opts: RateLimiterOptions): RateLimiterBundle<T>;
+declare function rateLimiter<T>(source: Node<T>, opts: NodeOrValue<RateLimiterOptions>): RateLimiterBundle<T>;
 type StatusValue = "pending" | "running" | "completed" | "errored";
 type WithStatusBundle<T> = {
     node: Node<T>;
@@ -557,6 +576,17 @@ type WithStatusBundle<T> = {
  * appear as edges in `describe()` if no consumer subscribes to them (per
  * COMPOSITION-GUIDE §1, push-on-subscribe semantics).
  *
+ * **Per-subscribe lifecycle (DF8, 2026-04-29 doc lock).** When the wrapped
+ * source is `resubscribable: true` and multiple consumers attach in
+ * sequence, each new subscription cycle re-runs the producer fn AND
+ * re-emits the initial `pending` + `null` companion DATAs. Downstream
+ * subscribers to the `status` / `error` companions see thrash:
+ * `pending → running → completed → pending → running …`. This is the
+ * intended fresh-cycle semantic (each subscription cycle reports its own
+ * lifecycle); consumers that need a "stable" status across cycles should
+ * derive a snapshot via a separate `state()` mirror rather than depending
+ * on the per-cycle reset.
+ *
  * @example
  * ```ts
  * import { withStatus, state } from "@graphrefly/graphrefly-ts";
@@ -583,6 +613,20 @@ declare class TimeoutError extends Error {
     name: string;
     constructor(ns: number);
 }
+/**
+ * Either a literal value or a reactive Node carrying it. Mirrors
+ * {@link FallbackInput}'s precedent for "options that may be reactive."
+ *
+ * Used by {@link timeout} / {@link retry} / {@link rateLimiter} /
+ * {@link circuitBreaker} / {@link budgetGate} to accept reactive option
+ * configurations (Tier 6.5 3.2, 2026-04-29). Each primitive subscribes
+ * to the option Node via {@link resolveReactiveOption} and rebinds
+ * internal state per its locked swap-semantic rule (see each primitive's
+ * JSDoc for the rule).
+ *
+ * @category extra
+ */
+type NodeOrValue<T> = T | Node<T>;
 /** Inputs accepted by {@link fallback}. */
 type FallbackInput<T> = T | Node<T> | PromiseLike<T> | AsyncIterable<T>;
 /**
@@ -626,7 +670,9 @@ declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>, options?: {
  * the timer. Terminal messages (`COMPLETE`/`ERROR`) cancel the timer.
  *
  * @param source - Upstream node.
- * @param timeoutNs - Deadline in **nanoseconds** (must be > 0). Internally converted to milliseconds for `setTimeout` scheduling.
+ * @param timeoutNs - Deadline in **nanoseconds** (must be > 0), or a
+ *   `Node<number>` carrying the deadline reactively (Tier 6.5 3.2.1).
+ *   Internally converted to milliseconds for `setTimeout` scheduling.
  * @returns Node that errors on timeout.
  *
  * @throws {RangeError} when `timeoutNs <= 0`.
@@ -634,6 +680,13 @@ declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>, options?: {
  * @remarks
  * **Scheduling:** internally uses {@link ResettableTimer} (raw `setTimeout`) per spec §5.10's resilience-operator carve-out. The deadline is `timeoutNs / NS_PER_MS` ms; sub-millisecond `timeoutNs` values get the same minimum-1ms host-scheduler granularity that `setTimeout` provides.
  *
+ * **Reactive `timeoutNs` (locked semantics, Tier 6.5 3.2.1, 2026-04-29).**
+ * When `timeoutNs` is a `Node<number>`, each timer-(re)start reads the
+ * latest value. An option swap mid-flight applies to the **next** timer
+ * window (no in-flight reset) — the active timer keeps its original
+ * deadline; the next DATA-driven `startTimer()` call reads the new
+ * value. Static-form callers see no behavior change.
+ *
  * @example
  * ```ts
  * import { timeout, never, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
@@ -644,7 +697,7 @@ declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>, options?: {
  *
  * @category extra
  */
-declare function timeout<T>(source: Node<T>, timeoutNs: number, options?: {
+declare function timeout<T>(source: Node<T>, timeoutNs: NodeOrValue<number>, options?: {
     meta?: Record<string, unknown>;
 }): Node<T>;