@graphrefly/graphrefly 0.41.0 → 0.43.0

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

@@ -1,5 +1,5 @@
-import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-BYInONRr.cjs';
-import { D as DescribeNodeOutput, a as DescribeDetail, b as DescribeField } from './meta-Ct9nqQS5.cjs';
+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 { StorageHandle } from './extra/storage-core.cjs';
 import { SnapshotStorageTier } from './extra/storage-tiers.cjs';
 
@@ -1665,4 +1665,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): ReachableResult;
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-export { type ObserveTheme as A, type ObserveThemeName as B, type CausalChain as C, type DescribeFilter as D, type ExplainPathOptions as E, type ObserveTier as F, Graph as G, type ReachableOptions as H, type TraceEntry as I, diffForWAL as J, explainPath as K, graphProfile as L, type Meta as M, type NodeProfile as N, type ObserveChangeset as O, reachable as P, topologyDiff as Q, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, type GraphOptions as a, type GraphDescribeOutput as b, type GraphPersistSnapshot as c, type GraphDescribeOptions as d, type CausalStep as e, type DescribeChangeset as f, type DescribeEvent as g, GRAPH_META_SEGMENT as h, type GraphActorOptions as i, type GraphAttachStorageOptions as j, type GraphCheckpointRecord as k, type GraphDiagramDirection as l, type GraphDiffChange as m, type GraphDiffResult as n, type GraphFactoryContext as o, type GraphNodeFactory as p, type GraphObserveAll as q, type GraphObserveOne as r, type GraphProfileOptions as s, type GraphProfileResult as t, type GraphVersionChange as u, type GraphWALDiff as v, type ObserveDetail as w, type ObserveEvent as x, type ObserveOptions as y, type ObserveResult as z };
+export { type ObserveTheme as A, type ObserveThemeName as B, type CausalChain as C, type DescribeChangeset as D, type ExplainPathOptions as E, type ObserveTier as F, Graph as G, type ReachableOptions as H, type TraceEntry as I, diffForWAL as J, explainPath as K, graphProfile as L, type Meta as M, type NodeProfile as N, type ObserveChangeset as O, reachable as P, topologyDiff as Q, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, type GraphOptions as a, type GraphDescribeOutput as b, type CausalStep as c, type DescribeEvent as d, type DescribeFilter as e, GRAPH_META_SEGMENT as f, type GraphActorOptions as g, type GraphAttachStorageOptions as h, type GraphCheckpointRecord as i, type GraphDescribeOptions as j, type GraphDiagramDirection as k, type GraphDiffChange as l, type GraphDiffResult as m, type GraphFactoryContext as n, type GraphNodeFactory as o, type GraphObserveAll as p, type GraphObserveOne as q, type GraphPersistSnapshot as r, type GraphProfileOptions as s, type GraphProfileResult as t, type GraphVersionChange as u, type GraphWALDiff as v, type ObserveDetail as w, type ObserveEvent as x, type ObserveOptions as y, type ObserveResult as z };

package/dist/{index-DgJc8Zgc.d.cts → index-0rKFCVFp.d.cts}

@@ -1,6 +1,6 @@
-import { o as GraphReFlyConfig } from './node-BYInONRr.cjs';
-import { c as GraphPersistSnapshot, k as GraphCheckpointRecord, G as Graph, C as CausalChain, e as CausalStep, D as DescribeFilter, E as ExplainPathOptions, h as GRAPH_META_SEGMENT, i as GraphActorOptions, j as GraphAttachStorageOptions, d as GraphDescribeOptions, b as GraphDescribeOutput, l as GraphDiagramDirection, m as GraphDiffChange, n as GraphDiffResult, o as GraphFactoryContext, p as GraphNodeFactory, q as GraphObserveAll, r as GraphObserveOne, a as GraphOptions, s as GraphProfileOptions, t as GraphProfileResult, u as GraphVersionChange, v as GraphWALDiff, N as NodeProfile, O as ObserveChangeset, w as ObserveDetail, x as ObserveEvent, y as ObserveOptions, z as ObserveResult, A as ObserveTheme, B as ObserveThemeName, F as ObserveTier, R as ReachableDirection, H as ReachableOptions, S as SNAPSHOT_VERSION, T as TopologyEvent, I as TraceEntry, J as diffForWAL, K as explainPath, L as graphProfile, P as reachable } from './graph-E6likq7w.cjs';
-import { w as watchTopologyTree } from './topology-tree-3LBKFsUo.cjs';
+import { n as GraphReFlyConfig } from './node-ClS5yC-B.cjs';
+import { r as GraphPersistSnapshot, i as GraphCheckpointRecord, G as Graph, C as CausalChain, c as CausalStep, e as DescribeFilter, E as ExplainPathOptions, f as GRAPH_META_SEGMENT, g as GraphActorOptions, h as GraphAttachStorageOptions, j as GraphDescribeOptions, b as GraphDescribeOutput, k as GraphDiagramDirection, l as GraphDiffChange, m as GraphDiffResult, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, s as GraphProfileOptions, t as GraphProfileResult, u as GraphVersionChange, v as GraphWALDiff, N as NodeProfile, O as ObserveChangeset, w as ObserveDetail, x as ObserveEvent, y as ObserveOptions, z as ObserveResult, A as ObserveTheme, B as ObserveThemeName, F as ObserveTier, R as ReachableDirection, H as ReachableOptions, S as SNAPSHOT_VERSION, T as TopologyEvent, I as TraceEntry, J as diffForWAL, K as explainPath, L as graphProfile, P as reachable } from './graph-C4SHb3Ly.cjs';
+import { w as watchTopologyTree } from './topology-tree-BSdfSwMi.cjs';
 
 /**
  * Approximate in-memory size estimation for arbitrary JS values.
@@ -255,6 +255,88 @@ declare function registerBuiltinCodecs(config: GraphReFlyConfig): void;
  */
 declare function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot;
 
+/**
+ * Topology check: detect "island" nodes with no in-edges AND no out-edges.
+ *
+ * Companion to {@link validateGraphObservability} for user validation. Catches
+ * the kind of disconnected-node smell flagged in the pagerduty-demo audit
+ * ("decisions/log not linked to any other nodes", "tokens only by itself") —
+ * the visible symptom of imperative writes or closure-held state that bypassed
+ * the reactive edge graph.
+ *
+ * **What counts as an island.** A node is an island when:
+ *   - it has zero declared deps (zero **in-edges**), AND
+ *   - no other node in the graph declares it as a dep (zero **out-edges**).
+ *
+ * Source nodes (producers / state nodes that act as roots) typically have zero
+ * in-edges but ≥1 out-edge — those are NOT islands. Sink nodes (effects that
+ * terminate a chain) have ≥1 in-edge but zero out-edges — also NOT islands.
+ * Only nodes that satisfy BOTH conditions are reported.
+ *
+ * **Sub-graph paths.** When the graph mounts subgraphs, the check walks the
+ * full path-qualified node table from `graph.describe({ detail: "minimal" })`
+ * — both top-level and mounted children participate.
+ *
+ * **False-positive caveat (D7 /qa lock).** A `state(0, { name: "metric" })`
+ * whose only consumer is an external (non-graph) subscriber — e.g. a React /
+ * Vue / CLI subscription that calls `.subscribe(...)` directly — looks like
+ * an island from `describe()`'s perspective: zero declared in-edges, and no
+ * other node lists it as a dep. The check WILL flag it. Treat
+ * `validateNoIslands` as a smell-detector, not a definitive correctness gate;
+ * complement with `graph.observe(...)` instrumentation when external
+ * consumers are part of the design. If you have known external-consumer
+ * roots, filter them from `result.orphans` before deciding what to act on.
+ *
+ * **Synthetic `__internal__/` paths (EH-9).** Compound factories sometimes
+ * surface unnamed helper nodes under the `__internal__/` namespace
+ * (auto-generated when a producer / derived is added without a `name` and
+ * the registrar falls back to a synthetic prefix). These never represent
+ * user-authored topology and should not surface as actionable orphans;
+ * `validateNoIslands` filters them out before reporting. If a real factory
+ * regression accidentally leaks a user-meaningful node under this prefix,
+ * the fix is to give the node a real name — not to remove the filter.
+ *
+ * **Non-throwing by default.** Returns a structured result so callers
+ * (dry-run blocks, CI smoke tests) can exit non-zero with a diagnostic
+ * instead of crashing.
+ *
+ * @module
+ */
+
+/** A reported island node, surfacing both path and node kind for triage. */
+interface IslandReport {
+    /** Path-qualified node name (mounted children included). */
+    readonly path: string;
+    /** `describe()` node `type` — `"state"` / `"derived"` / `"effect"` etc. Helps distinguish "forgot to wire" from "compositional bug". */
+    readonly kind: string;
+}
+/** Result returned by {@link validateNoIslands}. */
+interface ValidateNoIslandsResult {
+    /** `true` when the graph has zero island nodes. */
+    readonly ok: boolean;
+    /**
+     * Path-qualified names + kinds of nodes that are both zero-in and
+     * zero-out. Sorted ASCII-asc by `path` for deterministic output.
+     */
+    readonly orphans: readonly IslandReport[];
+    /** Single-line summary suitable for `process.stderr`. */
+    summary(): string;
+}
+/**
+ * Walk the graph's describe output and report island nodes (zero in + zero out edges).
+ *
+ * @example
+ * ```ts
+ * const result = validateNoIslands(graph);
+ * if (!result.ok) {
+ *   console.error(result.summary());
+ *   for (const o of result.orphans) console.error(`  - ${o.path} (${o.kind})`);
+ *   process.exit(3);
+ * }
+ * ```
+ */
+declare function validateNoIslands(graph: Graph): ValidateNoIslandsResult;
+
 /**
  * Graph observability validation — smoke-exercise helper (D4).
  *
@@ -430,6 +512,7 @@ declare const index_GraphProfileOptions: typeof GraphProfileOptions;
 declare const index_GraphProfileResult: typeof GraphProfileResult;
 declare const index_GraphVersionChange: typeof GraphVersionChange;
 declare const index_GraphWALDiff: typeof GraphWALDiff;
+type index_IslandReport = IslandReport;
 declare const index_JsonCodec: typeof JsonCodec;
 type index_LazyGraphCodec = LazyGraphCodec;
 declare const index_NodeProfile: typeof NodeProfile;
@@ -449,6 +532,7 @@ declare const index_SIZEOF_SYMBOL: typeof SIZEOF_SYMBOL;
 declare const index_SNAPSHOT_VERSION: typeof SNAPSHOT_VERSION;
 declare const index_TopologyEvent: typeof TopologyEvent;
 declare const index_TraceEntry: typeof TraceEntry;
+type index_ValidateNoIslandsResult = ValidateNoIslandsResult;
 type index_ValidateObservabilityOptions = ValidateObservabilityOptions;
 type index_ValidateObservabilityResult = ValidateObservabilityResult;
 type index_WALEntry = WALEntry;
@@ -464,9 +548,10 @@ declare const index_registerBuiltinCodecs: typeof registerBuiltinCodecs;
 declare const index_replayWAL: typeof replayWAL;
 declare const index_sizeof: typeof sizeof;
 declare const index_validateGraphObservability: typeof validateGraphObservability;
+declare const index_validateNoIslands: typeof validateNoIslands;
 declare const index_watchTopologyTree: typeof watchTopologyTree;
 declare namespace index {
-  export { index_CausalChain as CausalChain, index_CausalStep as CausalStep, index_DescribeFilter as DescribeFilter, index_ENVELOPE_VERSION as ENVELOPE_VERSION, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_ExplainPathOptions as ExplainPathOptions, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAttachStorageOptions as GraphAttachStorageOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOptions as GraphDescribeOptions, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphProfileOptions as GraphProfileOptions, index_GraphProfileResult as GraphProfileResult, index_GraphVersionChange as GraphVersionChange, index_GraphWALDiff as GraphWALDiff, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_NodeProfile as NodeProfile, type index_ObservabilityCheck as ObservabilityCheck, type index_ObservabilityDescribeFormat as ObservabilityDescribeFormat, index_ObserveChangeset as ObserveChangeset, index_ObserveDetail as ObserveDetail, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ObserveTheme as ObserveTheme, index_ObserveThemeName as ObserveThemeName, index_ObserveTier as ObserveTier, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, OVERHEAD as SIZEOF_OVERHEAD, index_SIZEOF_SYMBOL as SIZEOF_SYMBOL, index_SNAPSHOT_VERSION as SNAPSHOT_VERSION, index_TopologyEvent as TopologyEvent, index_TraceEntry as TraceEntry, type index_ValidateObservabilityOptions as ValidateObservabilityOptions, type index_ValidateObservabilityResult as ValidateObservabilityResult, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_decodeEnvelope as decodeEnvelope, index_diffForWAL as diffForWAL, index_encodeEnvelope as encodeEnvelope, index_explainPath as explainPath, index_graphProfile as graphProfile, index_reachable as reachable, index_registerBuiltinCodecs as registerBuiltinCodecs, index_replayWAL as replayWAL, index_sizeof as sizeof, index_validateGraphObservability as validateGraphObservability, index_watchTopologyTree as watchTopologyTree };
+  export { index_CausalChain as CausalChain, index_CausalStep as CausalStep, index_DescribeFilter as DescribeFilter, index_ENVELOPE_VERSION as ENVELOPE_VERSION, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_ExplainPathOptions as ExplainPathOptions, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAttachStorageOptions as GraphAttachStorageOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOptions as GraphDescribeOptions, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphProfileOptions as GraphProfileOptions, index_GraphProfileResult as GraphProfileResult, index_GraphVersionChange as GraphVersionChange, index_GraphWALDiff as GraphWALDiff, type index_IslandReport as IslandReport, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_NodeProfile as NodeProfile, type index_ObservabilityCheck as ObservabilityCheck, type index_ObservabilityDescribeFormat as ObservabilityDescribeFormat, index_ObserveChangeset as ObserveChangeset, index_ObserveDetail as ObserveDetail, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ObserveTheme as ObserveTheme, index_ObserveThemeName as ObserveThemeName, index_ObserveTier as ObserveTier, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, OVERHEAD as SIZEOF_OVERHEAD, index_SIZEOF_SYMBOL as SIZEOF_SYMBOL, index_SNAPSHOT_VERSION as SNAPSHOT_VERSION, index_TopologyEvent as TopologyEvent, index_TraceEntry as TraceEntry, type index_ValidateNoIslandsResult as ValidateNoIslandsResult, type index_ValidateObservabilityOptions as ValidateObservabilityOptions, type index_ValidateObservabilityResult as ValidateObservabilityResult, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_decodeEnvelope as decodeEnvelope, index_diffForWAL as diffForWAL, index_encodeEnvelope as encodeEnvelope, index_explainPath as explainPath, index_graphProfile as graphProfile, index_reachable as reachable, index_registerBuiltinCodecs as registerBuiltinCodecs, index_replayWAL as replayWAL, index_sizeof as sizeof, index_validateGraphObservability as validateGraphObservability, index_validateNoIslands as validateNoIslands, index_watchTopologyTree as watchTopologyTree };
 }
 
-export { ENVELOPE_VERSION as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, type ObservabilityCheck as O, SIZEOF_SYMBOL as S, type ValidateObservabilityOptions as V, type WALEntry as W, type EvictedSubgraphInfo as a, type EvictionPolicy as b, type ObservabilityDescribeFormat as c, OVERHEAD as d, type ValidateObservabilityResult as e, createDagCborCodec as f, createDagCborZstdCodec as g, decodeEnvelope as h, encodeEnvelope as i, index as j, replayWAL as k, registerBuiltinCodecs as r, sizeof as s, validateGraphObservability as v };
+export { ENVELOPE_VERSION as E, type GraphCodec as G, type IslandReport as I, JsonCodec as J, type LazyGraphCodec as L, type ObservabilityCheck as O, SIZEOF_SYMBOL as S, type ValidateNoIslandsResult as V, type WALEntry as W, type EvictedSubgraphInfo as a, type EvictionPolicy as b, type ObservabilityDescribeFormat as c, OVERHEAD as d, type ValidateObservabilityOptions as e, type ValidateObservabilityResult as f, createDagCborCodec as g, createDagCborZstdCodec as h, decodeEnvelope as i, encodeEnvelope as j, index as k, replayWAL as l, validateNoIslands as m, registerBuiltinCodecs as r, sizeof as s, validateGraphObservability as v };

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

@@ -1,4 +1,4 @@
-import { N as Node } from './node-BYInONRr.js';
+import { N as Node } from './node-ClS5yC-B.js';
 
 /**
  * Backoff strategies for {@link retry} (roadmap §3.1). Delays are in **nanoseconds**.
@@ -648,4 +648,4 @@ declare function timeout<T>(source: Node<T>, timeoutNs: number, options?: {
     meta?: Record<string, unknown>;
 }): Node<T>;
 
-export { type BackoffPreset as B, type CircuitState as C, type ExponentialBackoffOptions as E, type FallbackInput as F, type JitterMode as J, NS_PER_MS as N, type RateLimiterState as R, type StatusValue as S, TimeoutError as T, type WithBreakerBundle as W, type RateLimiterOptions as a, type CircuitBreakerOptions as b, type RetryOptions as c, NS_PER_SEC as d, type BackoffStrategy as e, type CircuitBreaker as f, CircuitOpenError as g, RateLimiterOverflowError as h, type RateLimiterOverflowPolicy as i, type TokenBucket as j, type WithStatusBundle as k, circuitBreaker as l, constant as m, decorrelatedJitter as n, exponential as o, fallback as p, fibonacci as q, linear as r, rateLimiter as s, resolveBackoffPreset as t, retry as u, timeout as v, tokenBucket as w, withBreaker as x, withMaxAttempts as y, withStatus as z };
+export { type BackoffPreset as B, type CircuitBreaker as C, type ExponentialBackoffOptions as E, type FallbackInput as F, type JitterMode as J, NS_PER_MS as N, type RateLimiterOptions as R, type StatusValue as S, TimeoutError as T, type WithBreakerBundle as W, type BackoffStrategy as a, type CircuitBreakerOptions as b, CircuitOpenError as c, type CircuitState as d, NS_PER_SEC as e, RateLimiterOverflowError as f, type RateLimiterOverflowPolicy as g, type RetryOptions as h, type TokenBucket as i, type WithStatusBundle as j, circuitBreaker as k, constant as l, decorrelatedJitter as m, exponential as n, fallback as o, fibonacci as p, linear as q, rateLimiter as r, resolveBackoffPreset as s, retry as t, timeout as u, tokenBucket as v, withBreaker as w, withMaxAttempts as x, withStatus as y };