@graphrefly/graphrefly 0.42.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-LIpQQE9f.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-BtAsBp8K.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-CPNSy-U0.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).
@@ -58,6 +58,25 @@ interface AuditTrailOptions {
 declare class AuditTrailGraph extends Graph {
     readonly entries: Node<readonly AuditEntry[]>;
     readonly count: Node<number>;
+    /**
+     * Effective set of event types this trail records (EH-18). Reflects
+     * either the caller-supplied `opts.includeTypes` or the default set
+     * (`["data", "error", "complete", "teardown"]`). Captured at construction
+     * — each instance owns its own clone, so a default-using trail can never
+     * leak mutations into the module-level default set.
+     *
+     * **Mutation contract.** Type-system read-only via `ReadonlySet`. Runtime
+     * mutation through an unsafe cast (`(audit.includeTypes as Set<...>)
+     * .add(...)`) is unsupported — it would desync the field from the
+     * recording closure, which captured the original `Set` reference at
+     * construction. The runtime does NOT enforce immutability beyond the
+     * type contract; consumers must respect it.
+     *
+     * Use this to validate that a `complianceSnapshot.fingerprint` was
+     * computed against the same recording surface — fingerprints are stable
+     * only when the recording set is identical across snapshots.
+     */
+    readonly includeTypes: ReadonlySet<AuditEntry["type"]>;
     private readonly _log;
     private readonly _target;
     constructor(target: Graph, opts: AuditTrailOptions);

package/dist/{index-CEMx8n40.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-DBIqYS43.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-2B7u2pVn.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-DBIqYS43.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