@graphrefly/graphrefly 0.17.0 → 0.19.0

package/dist/graph/index.d.cts

@@ -1,3 +1,3 @@
-export { D as DeltaCheckpoint, E as EvictedSubgraphInfo, b as EvictionPolicy, c as GraphCodec, a as GraphProfileOptions, G as GraphProfileResult, J as JsonCodec, L as LazyGraphCodec, N as NodeProfile, W as WALEntry, d as createDagCborCodec, e as createDagCborZstdCodec, g as graphProfile, n as negotiateCodec, r as replayWAL, s as sizeof } from '../index-4OIX-q0C.cjs';
-export { A as AutoCheckpointAdapter, D as DescribeFilter, d as GRAPH_META_SEGMENT, G as Graph, e as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, f as GraphCheckpointRecord, g as GraphDescribeOptions, h as GraphDescribeOutput, i as GraphDiagramDirection, j as GraphDiagramOptions, k as GraphDiffChange, l as GraphDiffResult, m as GraphDumpOptions, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, r as GraphPersistSnapshot, s as GraphSpyHandle, t as GraphSpyOptions, u as GraphSpyTheme, v as GraphSpyThemeName, O as ObserveDetail, w as ObserveEvent, x as ObserveOptions, y as ObserveResult, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, B as reachable } from '../graph-fCsaaVIa.cjs';
-import '../meta-BV4pj9ML.cjs';
+export { D as DeltaCheckpoint, E as EvictedSubgraphInfo, a as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, W as WALEntry, c as createDagCborCodec, b as createDagCborZstdCodec, n as negotiateCodec, r as replayWAL, s as sizeof } from '../index-UudxGnzc.cjs';
+export { A as AutoCheckpointAdapter, D as DescribeFilter, f as GRAPH_META_SEGMENT, G as Graph, g as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, h as GraphCheckpointRecord, i as GraphDescribeOptions, j as GraphDescribeOutput, k as GraphDiagramDirection, l as GraphDiagramOptions, m as GraphDiffChange, n as GraphDiffResult, o as GraphDumpOptions, p as GraphFactoryContext, q as GraphNodeFactory, r as GraphObserveAll, s as GraphObserveOne, a as GraphOptions, t as GraphPersistSnapshot, e as GraphProfileOptions, d as GraphProfileResult, N as NodeProfile, O as ObserveDetail, u as ObserveEvent, v as ObserveOptions, w as ObserveResult, x as ObserveTheme, y as ObserveThemeName, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, B as graphProfile, C as reachable } from '../graph-KsTe57nI.cjs';
+import '../meta-BnG7XAaE.cjs';

package/dist/graph/index.d.ts

@@ -1,3 +1,3 @@
-export { D as DeltaCheckpoint, E as EvictedSubgraphInfo, b as EvictionPolicy, c as GraphCodec, a as GraphProfileOptions, G as GraphProfileResult, J as JsonCodec, L as LazyGraphCodec, N as NodeProfile, W as WALEntry, d as createDagCborCodec, e as createDagCborZstdCodec, g as graphProfile, n as negotiateCodec, r as replayWAL, s as sizeof } from '../index-D7y9Q8W4.js';
-export { A as AutoCheckpointAdapter, D as DescribeFilter, d as GRAPH_META_SEGMENT, G as Graph, e as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, f as GraphCheckpointRecord, g as GraphDescribeOptions, h as GraphDescribeOutput, i as GraphDiagramDirection, j as GraphDiagramOptions, k as GraphDiffChange, l as GraphDiffResult, m as GraphDumpOptions, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, r as GraphPersistSnapshot, s as GraphSpyHandle, t as GraphSpyOptions, u as GraphSpyTheme, v as GraphSpyThemeName, O as ObserveDetail, w as ObserveEvent, x as ObserveOptions, y as ObserveResult, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, B as reachable } from '../graph-Dc-P9BVm.js';
-import '../meta-BV4pj9ML.js';
+export { D as DeltaCheckpoint, E as EvictedSubgraphInfo, a as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, W as WALEntry, c as createDagCborCodec, b as createDagCborZstdCodec, n as negotiateCodec, r as replayWAL, s as sizeof } from '../index-B2SvPEbc.js';
+export { A as AutoCheckpointAdapter, D as DescribeFilter, f as GRAPH_META_SEGMENT, G as Graph, g as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, h as GraphCheckpointRecord, i as GraphDescribeOptions, j as GraphDescribeOutput, k as GraphDiagramDirection, l as GraphDiagramOptions, m as GraphDiffChange, n as GraphDiffResult, o as GraphDumpOptions, p as GraphFactoryContext, q as GraphNodeFactory, r as GraphObserveAll, s as GraphObserveOne, a as GraphOptions, t as GraphPersistSnapshot, e as GraphProfileOptions, d as GraphProfileResult, N as NodeProfile, O as ObserveDetail, u as ObserveEvent, v as ObserveOptions, w as ObserveResult, x as ObserveTheme, y as ObserveThemeName, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, B as graphProfile, C as reachable } from '../graph-mILUUqW8.js';
+import '../meta-BnG7XAaE.js';

package/dist/graph/index.js

@@ -2,18 +2,18 @@ import {
   JsonCodec,
   createDagCborCodec,
   createDagCborZstdCodec,
-  graphProfile,
   negotiateCodec,
-  replayWAL,
-  sizeof
-} from "../chunk-EBNKJULL.js";
+  replayWAL
+} from "../chunk-YLR5JUJZ.js";
 import {
   GRAPH_META_SEGMENT,
   Graph,
-  reachable
-} from "../chunk-IHJHBADD.js";
-import "../chunk-F2ULI3Q3.js";
-import "../chunk-BV3TPSBK.js";
+  graphProfile,
+  reachable,
+  sizeof
+} from "../chunk-JC2SN46B.js";
+import "../chunk-XUOY3YKN.js";
+import "../chunk-YXR3WW3Q.js";
 export {
   GRAPH_META_SEGMENT,
   Graph,

package/dist/{graph-fCsaaVIa.d.cts → graph-KsTe57nI.d.cts}

@@ -1,4 +1,67 @@
-import { j as DescribeNodeOutput, h as DescribeDetail, i as DescribeField, N as Node, y as VersioningLevel, A as Actor, m as Messages, p as NodeSink } from './meta-BV4pj9ML.cjs';
+import { i as DescribeNodeOutput, g as DescribeDetail, h as DescribeField, N as Node, y as VersioningLevel, A as Actor, l as Messages, o as NodeSink } from './meta-BnG7XAaE.cjs';
+
+/**
+ * Graph profiling and inspection utilities.
+ *
+ * Provides per-node memory estimation, connectivity stats, and hotspot
+ * detection. Non-invasive — reads from `describe()` and node internals
+ * without modifying state.
+ *
+ * @module
+ */
+
+/** Per-node profile entry. */
+interface NodeProfile {
+    /** Qualified path within the graph. */
+    path: string;
+    /** Node type (state, derived, producer, effect). */
+    type: string;
+    /** Node status (disconnected, dirty, settled, errored, completed). */
+    status: string;
+    /** Approximate retained bytes for the node's cached value. */
+    valueSizeBytes: number;
+    /** Number of downstream subscribers (sinks). */
+    subscriberCount: number;
+    /** Number of upstream dependencies. */
+    depCount: number;
+    /** True if this is an effect node with no external subscribers (potential leak). */
+    isOrphanEffect: boolean;
+}
+/** Aggregate graph profile. */
+interface GraphProfileResult {
+    /** Total node count. */
+    nodeCount: number;
+    /** Total edge count. */
+    edgeCount: number;
+    /** Subgraph count. */
+    subgraphCount: number;
+    /** All node profiles. */
+    nodes: NodeProfile[];
+    /** Total approximate value memory across all nodes. */
+    totalValueSizeBytes: number;
+    /** Nodes sorted by valueSizeBytes descending (top N). */
+    hotspots: NodeProfile[];
+    /** Effect nodes with no external subscribers (potential leaks). */
+    orphanEffects: NodeProfile[];
+}
+/** Options for {@link graphProfile}. */
+interface GraphProfileOptions {
+    /** Limit hotspot list (default 10). */
+    topN?: number;
+    /** Include subgraph nodes recursively (default true). */
+    recursive?: boolean;
+}
+/**
+ * Profile a graph's memory and connectivity characteristics.
+ *
+ * Uses `describe({ detail: "standard" })` for node metadata and direct
+ * `NodeImpl` access for subscriber counts and cached values.
+ *
+ * @param graph - The graph to profile.
+ * @param opts - Optional configuration.
+ * @returns Aggregate profile with per-node details and hotspots.
+ */
+declare function graphProfile(graph: Graph, opts?: GraphProfileOptions): GraphProfileResult;
 
 /**
  * Reserved segment for meta companion paths: `nodeName::__meta__::metaKey` (GRAPHREFLY-SPEC §3.6).
@@ -165,6 +228,19 @@ type ObserveOptions = {
      * `"minimal"` filters to DATA-only events.
      */
     detail?: ObserveDetail;
+    /**
+     * When set, auto-enables structured mode and attaches a logger.
+     * `"pretty"` renders colored one-line output; `"json"` emits one JSON object per event.
+     */
+    format?: "pretty" | "json";
+    /** Sink for rendered lines (`console.log` by default). Only used when `format` is set. */
+    logger?: (line: string, event: ObserveEvent) => void;
+    /** Keep only these event types in formatted output. Only used when `format` is set. */
+    includeTypes?: ObserveEvent["type"][];
+    /** Exclude these event types from formatted output. Only used when `format` is set. */
+    excludeTypes?: ObserveEvent["type"][];
+    /** Built-in color preset (`ansi` default) or explicit color tokens. Only used when `format` is set. */
+    theme?: ObserveThemeName | ObserveTheme;
 };
 /** Accumulated observation result (structured mode). */
 type ObserveResult<T = unknown> = {
@@ -176,10 +252,12 @@ type ObserveResult<T = unknown> = {
     readonly resolvedCount: number;
     /** All events in order. */
     readonly events: ObserveEvent[];
-    /** True if COMPLETE received without prior ERROR. */
-    readonly completedCleanly: boolean;
-    /** True if ERROR received. */
-    readonly errored: boolean;
+    /** True if any observed node sent COMPLETE without prior ERROR on that node. */
+    readonly anyCompletedCleanly: boolean;
+    /** True if any observed node sent ERROR. */
+    readonly anyErrored: boolean;
+    /** True if at least one COMPLETE received and no ERROR from any observed node. */
+    readonly completedWithoutErrors: boolean;
     /** Stop observing. */
     dispose(): void;
     /**
@@ -195,6 +273,8 @@ type ObserveEvent = {
     data?: unknown;
     timestamp_ns?: number;
     in_batch?: boolean;
+    /** Monotonically increasing counter per subscribe-callback invocation. All events in one delivery share the same id. */
+    batch_id?: number;
     trigger_dep_index?: number;
     trigger_dep_name?: string;
     /**
@@ -208,30 +288,10 @@ type ObserveEvent = {
     };
     dep_values?: unknown[];
 };
-/** Built-in color presets for {@link Graph.spy}. */
-type GraphSpyThemeName = "none" | "ansi";
-/** ANSI/style overrides for {@link Graph.spy} event rendering. */
-type GraphSpyTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", string>>;
-/** Options for {@link Graph.spy}. */
-type GraphSpyOptions = ObserveOptions & {
-    /** Observe one path; omit for graph-wide mode. */
-    path?: string;
-    /** Keep only these event types in spy output. */
-    includeTypes?: ObserveEvent["type"][];
-    /** Exclude these event types from spy output. */
-    excludeTypes?: ObserveEvent["type"][];
-    /** Built-in color preset (`ansi` default) or explicit color tokens. */
-    theme?: GraphSpyThemeName | GraphSpyTheme;
-    /** One-line `pretty` output (default) or JSON-per-event. */
-    format?: "pretty" | "json";
-    /** Optional sink for rendered lines (`console.log` by default). */
-    logger?: (line: string, event: ObserveEvent) => void;
-};
-/** Handle returned by {@link Graph.spy}. */
-type GraphSpyHandle = {
-    readonly result: ObserveResult;
-    dispose(): void;
-};
+/** Built-in color preset names for observe `format` rendering. */
+type ObserveThemeName = "none" | "ansi";
+/** ANSI/style overrides for observe `format` event rendering. */
+type ObserveTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", string>>;
 /** Options for {@link Graph.dumpGraph}. */
 type GraphDumpOptions = {
     actor?: Actor;
@@ -432,6 +492,14 @@ declare class Graph {
     describe(options?: GraphDescribeOptions): GraphDescribeOutput;
     private _collectSubgraphs;
     private _collectAllEdges;
+    /**
+     * Snapshot-based resource profile: per-node stats, orphan effect detection,
+     * memory hotspots. Zero runtime overhead — walks nodes on demand.
+     *
+     * @param opts - Optional `topN` for hotspot limit (default 10).
+     * @returns Aggregate profile with per-node details, hotspots, and orphan effects.
+     */
+    resourceProfile(opts?: GraphProfileOptions): GraphProfileResult;
     private _qualifyEdgeEndpoint;
     private _collectObserveTargets;
     private _appendMetaObserveTargets;
@@ -453,6 +521,9 @@ declare class Graph {
         causal?: true;
         derived?: true;
     }): ObserveResult;
+    observe(path: string, options: ObserveOptions & {
+        format: "pretty" | "json";
+    }): ObserveResult;
     observe(path: string, options?: ObserveOptions): GraphObserveOne;
     observe(options: ObserveOptions & {
         structured?: true;
@@ -460,19 +531,26 @@ declare class Graph {
         causal?: true;
         derived?: true;
     }): ObserveResult;
+    observe(options: ObserveOptions & {
+        format: "pretty" | "json";
+    }): ObserveResult;
     observe(options?: ObserveOptions): GraphObserveAll;
     private _createObserveResult;
     private _createObserveResultForAll;
     /**
-     * Convenience live debugger over {@link Graph.observe}. Logs protocol events as they flow.
-     *
-     * Supports one-node (`path`) and graph-wide modes, event filtering, and JSON/pretty rendering.
-     * Color themes are built in (`ansi` / `none`) to avoid external dependencies.
-     *
-     * @param options - Spy configuration.
-     * @returns Disposable handle plus a structured observation accumulator.
+     * Fallback ObserveResult for single-node when inspector is disabled but `format` is requested.
+     * Subscribes to raw messages and accumulates events with timeline info.
+     */
+    private _createFallbackObserveResult;
+    /**
+     * Fallback ObserveResult for graph-wide when inspector is disabled but `format` is requested.
      */
-    spy(options?: GraphSpyOptions): GraphSpyHandle;
+    private _createFallbackObserveResultForAll;
+    /**
+     * Attaches a format logger to an ObserveResult, rendering events as they arrive.
+     * Wraps the result's dispose to flush pending events.
+     */
+    private _attachFormatLogger;
     /**
      * CLI/debug-friendly graph dump built on {@link Graph.describe}.
      *
@@ -552,8 +630,9 @@ declare class Graph {
     /**
      * Debounced persistence wired to graph-wide observe stream (spec §3.8 auto-checkpoint).
      *
-     * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 2 messages
-     * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1 control waves.
+     * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 3 messages
+     * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1/2 control
+     * waves (`START`/`DIRTY`/`INVALIDATE`/`PAUSE`/`RESUME`).
      */
     autoCheckpoint(adapter: AutoCheckpointAdapter, options?: GraphAutoCheckpointOptions): GraphAutoCheckpointHandle;
     /**
@@ -576,7 +655,7 @@ declare class Graph {
     toD2(options?: GraphDiagramOptions): string;
     /**
      * When `false`, structured observation options (`causal`, `timeline`),
-     * `annotate()`, and `traceLog()` are no-ops. Raw `observe()` always works.
+     * and `trace()` writes are no-ops. Raw `observe()` always works.
      *
      * Default: `true` outside production (`process.env.NODE_ENV !== "production"`).
      */
@@ -584,20 +663,17 @@ declare class Graph {
     private _annotations;
     private _traceRing;
     /**
-     * Attaches a reasoning annotation to a node — captures *why* an AI agent set a value.
+     * Unified reasoning trace: write annotations or read the ring buffer.
      *
+     * Write: `graph.trace("path", "reason")` — attaches a reasoning annotation
+     * to a node, capturing *why* an AI agent set a value.
      * No-op when {@link Graph.inspectorEnabled} is `false`.
      *
-     * @param path - Qualified node path.
-     * @param reason - Free-text note stored in the trace ring buffer.
-     */
-    annotate(path: string, reason: string): void;
-    /**
-     * Returns a chronological log of all reasoning annotations (ring buffer).
-     *
-     * @returns `[]` when {@link Graph.inspectorEnabled} is `false`.
+     * Read: `graph.trace()` — returns a chronological log of all annotations.
+     * Returns `[]` when {@link Graph.inspectorEnabled} is `false`.
      */
-    traceLog(): readonly TraceEntry[];
+    trace(path: string, reason: string): void;
+    trace(): readonly TraceEntry[];
     /**
      * Computes structural + value diff between two {@link Graph.describe} snapshots.
      *
@@ -671,4 +747,4 @@ type ReachableOptions = {
  */
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-export { type AutoCheckpointAdapter as A, reachable as B, type DescribeFilter as D, Graph as G, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAutoCheckpointHandle as b, type GraphAutoCheckpointOptions as c, GRAPH_META_SEGMENT as d, type GraphActorOptions as e, type GraphCheckpointRecord as f, type GraphDescribeOptions as g, type GraphDescribeOutput as h, type GraphDiagramDirection as i, type GraphDiagramOptions as j, type GraphDiffChange as k, type GraphDiffResult as l, type GraphDumpOptions as m, type GraphFactoryContext as n, type GraphNodeFactory as o, type GraphObserveAll as p, type GraphObserveOne as q, type GraphPersistSnapshot as r, type GraphSpyHandle as s, type GraphSpyOptions as t, type GraphSpyTheme as u, type GraphSpyThemeName as v, type ObserveEvent as w, type ObserveOptions as x, type ObserveResult as y, type ReachableOptions as z };
+export { type AutoCheckpointAdapter as A, graphProfile as B, reachable as C, type DescribeFilter as D, Graph as G, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAutoCheckpointHandle as b, type GraphAutoCheckpointOptions as c, type GraphProfileResult as d, type GraphProfileOptions as e, GRAPH_META_SEGMENT as f, type GraphActorOptions as g, type GraphCheckpointRecord as h, type GraphDescribeOptions as i, type GraphDescribeOutput as j, type GraphDiagramDirection as k, type GraphDiagramOptions as l, type GraphDiffChange as m, type GraphDiffResult as n, type GraphDumpOptions as o, type GraphFactoryContext as p, type GraphNodeFactory as q, type GraphObserveAll as r, type GraphObserveOne as s, type GraphPersistSnapshot as t, type ObserveEvent as u, type ObserveOptions as v, type ObserveResult as w, type ObserveTheme as x, type ObserveThemeName as y, type ReachableOptions as z };

package/dist/{graph-Dc-P9BVm.d.ts → graph-mILUUqW8.d.ts}

@@ -1,4 +1,67 @@
-import { j as DescribeNodeOutput, h as DescribeDetail, i as DescribeField, N as Node, y as VersioningLevel, A as Actor, m as Messages, p as NodeSink } from './meta-BV4pj9ML.js';
+import { i as DescribeNodeOutput, g as DescribeDetail, h as DescribeField, N as Node, y as VersioningLevel, A as Actor, l as Messages, o as NodeSink } from './meta-BnG7XAaE.js';
+
+/**
+ * Graph profiling and inspection utilities.
+ *
+ * Provides per-node memory estimation, connectivity stats, and hotspot
+ * detection. Non-invasive — reads from `describe()` and node internals
+ * without modifying state.
+ *
+ * @module
+ */
+
+/** Per-node profile entry. */
+interface NodeProfile {
+    /** Qualified path within the graph. */
+    path: string;
+    /** Node type (state, derived, producer, effect). */
+    type: string;
+    /** Node status (disconnected, dirty, settled, errored, completed). */
+    status: string;
+    /** Approximate retained bytes for the node's cached value. */
+    valueSizeBytes: number;
+    /** Number of downstream subscribers (sinks). */
+    subscriberCount: number;
+    /** Number of upstream dependencies. */
+    depCount: number;
+    /** True if this is an effect node with no external subscribers (potential leak). */
+    isOrphanEffect: boolean;
+}
+/** Aggregate graph profile. */
+interface GraphProfileResult {
+    /** Total node count. */
+    nodeCount: number;
+    /** Total edge count. */
+    edgeCount: number;
+    /** Subgraph count. */
+    subgraphCount: number;
+    /** All node profiles. */
+    nodes: NodeProfile[];
+    /** Total approximate value memory across all nodes. */
+    totalValueSizeBytes: number;
+    /** Nodes sorted by valueSizeBytes descending (top N). */
+    hotspots: NodeProfile[];
+    /** Effect nodes with no external subscribers (potential leaks). */
+    orphanEffects: NodeProfile[];
+}
+/** Options for {@link graphProfile}. */
+interface GraphProfileOptions {
+    /** Limit hotspot list (default 10). */
+    topN?: number;
+    /** Include subgraph nodes recursively (default true). */
+    recursive?: boolean;
+}
+/**
+ * Profile a graph's memory and connectivity characteristics.
+ *
+ * Uses `describe({ detail: "standard" })` for node metadata and direct
+ * `NodeImpl` access for subscriber counts and cached values.
+ *
+ * @param graph - The graph to profile.
+ * @param opts - Optional configuration.
+ * @returns Aggregate profile with per-node details and hotspots.
+ */
+declare function graphProfile(graph: Graph, opts?: GraphProfileOptions): GraphProfileResult;
 
 /**
  * Reserved segment for meta companion paths: `nodeName::__meta__::metaKey` (GRAPHREFLY-SPEC §3.6).
@@ -165,6 +228,19 @@ type ObserveOptions = {
      * `"minimal"` filters to DATA-only events.
      */
     detail?: ObserveDetail;
+    /**
+     * When set, auto-enables structured mode and attaches a logger.
+     * `"pretty"` renders colored one-line output; `"json"` emits one JSON object per event.
+     */
+    format?: "pretty" | "json";
+    /** Sink for rendered lines (`console.log` by default). Only used when `format` is set. */
+    logger?: (line: string, event: ObserveEvent) => void;
+    /** Keep only these event types in formatted output. Only used when `format` is set. */
+    includeTypes?: ObserveEvent["type"][];
+    /** Exclude these event types from formatted output. Only used when `format` is set. */
+    excludeTypes?: ObserveEvent["type"][];
+    /** Built-in color preset (`ansi` default) or explicit color tokens. Only used when `format` is set. */
+    theme?: ObserveThemeName | ObserveTheme;
 };
 /** Accumulated observation result (structured mode). */
 type ObserveResult<T = unknown> = {
@@ -176,10 +252,12 @@ type ObserveResult<T = unknown> = {
     readonly resolvedCount: number;
     /** All events in order. */
     readonly events: ObserveEvent[];
-    /** True if COMPLETE received without prior ERROR. */
-    readonly completedCleanly: boolean;
-    /** True if ERROR received. */
-    readonly errored: boolean;
+    /** True if any observed node sent COMPLETE without prior ERROR on that node. */
+    readonly anyCompletedCleanly: boolean;
+    /** True if any observed node sent ERROR. */
+    readonly anyErrored: boolean;
+    /** True if at least one COMPLETE received and no ERROR from any observed node. */
+    readonly completedWithoutErrors: boolean;
     /** Stop observing. */
     dispose(): void;
     /**
@@ -195,6 +273,8 @@ type ObserveEvent = {
     data?: unknown;
     timestamp_ns?: number;
     in_batch?: boolean;
+    /** Monotonically increasing counter per subscribe-callback invocation. All events in one delivery share the same id. */
+    batch_id?: number;
     trigger_dep_index?: number;
     trigger_dep_name?: string;
     /**
@@ -208,30 +288,10 @@ type ObserveEvent = {
     };
     dep_values?: unknown[];
 };
-/** Built-in color presets for {@link Graph.spy}. */
-type GraphSpyThemeName = "none" | "ansi";
-/** ANSI/style overrides for {@link Graph.spy} event rendering. */
-type GraphSpyTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", string>>;
-/** Options for {@link Graph.spy}. */
-type GraphSpyOptions = ObserveOptions & {
-    /** Observe one path; omit for graph-wide mode. */
-    path?: string;
-    /** Keep only these event types in spy output. */
-    includeTypes?: ObserveEvent["type"][];
-    /** Exclude these event types from spy output. */
-    excludeTypes?: ObserveEvent["type"][];
-    /** Built-in color preset (`ansi` default) or explicit color tokens. */
-    theme?: GraphSpyThemeName | GraphSpyTheme;
-    /** One-line `pretty` output (default) or JSON-per-event. */
-    format?: "pretty" | "json";
-    /** Optional sink for rendered lines (`console.log` by default). */
-    logger?: (line: string, event: ObserveEvent) => void;
-};
-/** Handle returned by {@link Graph.spy}. */
-type GraphSpyHandle = {
-    readonly result: ObserveResult;
-    dispose(): void;
-};
+/** Built-in color preset names for observe `format` rendering. */
+type ObserveThemeName = "none" | "ansi";
+/** ANSI/style overrides for observe `format` event rendering. */
+type ObserveTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", string>>;
 /** Options for {@link Graph.dumpGraph}. */
 type GraphDumpOptions = {
     actor?: Actor;
@@ -432,6 +492,14 @@ declare class Graph {
     describe(options?: GraphDescribeOptions): GraphDescribeOutput;
     private _collectSubgraphs;
     private _collectAllEdges;
+    /**
+     * Snapshot-based resource profile: per-node stats, orphan effect detection,
+     * memory hotspots. Zero runtime overhead — walks nodes on demand.
+     *
+     * @param opts - Optional `topN` for hotspot limit (default 10).
+     * @returns Aggregate profile with per-node details, hotspots, and orphan effects.
+     */
+    resourceProfile(opts?: GraphProfileOptions): GraphProfileResult;
     private _qualifyEdgeEndpoint;
     private _collectObserveTargets;
     private _appendMetaObserveTargets;
@@ -453,6 +521,9 @@ declare class Graph {
         causal?: true;
         derived?: true;
     }): ObserveResult;
+    observe(path: string, options: ObserveOptions & {
+        format: "pretty" | "json";
+    }): ObserveResult;
     observe(path: string, options?: ObserveOptions): GraphObserveOne;
     observe(options: ObserveOptions & {
         structured?: true;
@@ -460,19 +531,26 @@ declare class Graph {
         causal?: true;
         derived?: true;
     }): ObserveResult;
+    observe(options: ObserveOptions & {
+        format: "pretty" | "json";
+    }): ObserveResult;
     observe(options?: ObserveOptions): GraphObserveAll;
     private _createObserveResult;
     private _createObserveResultForAll;
     /**
-     * Convenience live debugger over {@link Graph.observe}. Logs protocol events as they flow.
-     *
-     * Supports one-node (`path`) and graph-wide modes, event filtering, and JSON/pretty rendering.
-     * Color themes are built in (`ansi` / `none`) to avoid external dependencies.
-     *
-     * @param options - Spy configuration.
-     * @returns Disposable handle plus a structured observation accumulator.
+     * Fallback ObserveResult for single-node when inspector is disabled but `format` is requested.
+     * Subscribes to raw messages and accumulates events with timeline info.
+     */
+    private _createFallbackObserveResult;
+    /**
+     * Fallback ObserveResult for graph-wide when inspector is disabled but `format` is requested.
      */
-    spy(options?: GraphSpyOptions): GraphSpyHandle;
+    private _createFallbackObserveResultForAll;
+    /**
+     * Attaches a format logger to an ObserveResult, rendering events as they arrive.
+     * Wraps the result's dispose to flush pending events.
+     */
+    private _attachFormatLogger;
     /**
      * CLI/debug-friendly graph dump built on {@link Graph.describe}.
      *
@@ -552,8 +630,9 @@ declare class Graph {
     /**
      * Debounced persistence wired to graph-wide observe stream (spec §3.8 auto-checkpoint).
      *
-     * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 2 messages
-     * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1 control waves.
+     * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 3 messages
+     * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1/2 control
+     * waves (`START`/`DIRTY`/`INVALIDATE`/`PAUSE`/`RESUME`).
      */
     autoCheckpoint(adapter: AutoCheckpointAdapter, options?: GraphAutoCheckpointOptions): GraphAutoCheckpointHandle;
     /**
@@ -576,7 +655,7 @@ declare class Graph {
     toD2(options?: GraphDiagramOptions): string;
     /**
      * When `false`, structured observation options (`causal`, `timeline`),
-     * `annotate()`, and `traceLog()` are no-ops. Raw `observe()` always works.
+     * and `trace()` writes are no-ops. Raw `observe()` always works.
      *
      * Default: `true` outside production (`process.env.NODE_ENV !== "production"`).
      */
@@ -584,20 +663,17 @@ declare class Graph {
     private _annotations;
     private _traceRing;
     /**
-     * Attaches a reasoning annotation to a node — captures *why* an AI agent set a value.
+     * Unified reasoning trace: write annotations or read the ring buffer.
      *
+     * Write: `graph.trace("path", "reason")` — attaches a reasoning annotation
+     * to a node, capturing *why* an AI agent set a value.
      * No-op when {@link Graph.inspectorEnabled} is `false`.
      *
-     * @param path - Qualified node path.
-     * @param reason - Free-text note stored in the trace ring buffer.
-     */
-    annotate(path: string, reason: string): void;
-    /**
-     * Returns a chronological log of all reasoning annotations (ring buffer).
-     *
-     * @returns `[]` when {@link Graph.inspectorEnabled} is `false`.
+     * Read: `graph.trace()` — returns a chronological log of all annotations.
+     * Returns `[]` when {@link Graph.inspectorEnabled} is `false`.
      */
-    traceLog(): readonly TraceEntry[];
+    trace(path: string, reason: string): void;
+    trace(): readonly TraceEntry[];
     /**
      * Computes structural + value diff between two {@link Graph.describe} snapshots.
      *
@@ -671,4 +747,4 @@ type ReachableOptions = {
  */
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-export { type AutoCheckpointAdapter as A, reachable as B, type DescribeFilter as D, Graph as G, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAutoCheckpointHandle as b, type GraphAutoCheckpointOptions as c, GRAPH_META_SEGMENT as d, type GraphActorOptions as e, type GraphCheckpointRecord as f, type GraphDescribeOptions as g, type GraphDescribeOutput as h, type GraphDiagramDirection as i, type GraphDiagramOptions as j, type GraphDiffChange as k, type GraphDiffResult as l, type GraphDumpOptions as m, type GraphFactoryContext as n, type GraphNodeFactory as o, type GraphObserveAll as p, type GraphObserveOne as q, type GraphPersistSnapshot as r, type GraphSpyHandle as s, type GraphSpyOptions as t, type GraphSpyTheme as u, type GraphSpyThemeName as v, type ObserveEvent as w, type ObserveOptions as x, type ObserveResult as y, type ReachableOptions as z };
+export { type AutoCheckpointAdapter as A, graphProfile as B, reachable as C, type DescribeFilter as D, Graph as G, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAutoCheckpointHandle as b, type GraphAutoCheckpointOptions as c, type GraphProfileResult as d, type GraphProfileOptions as e, GRAPH_META_SEGMENT as f, type GraphActorOptions as g, type GraphCheckpointRecord as h, type GraphDescribeOptions as i, type GraphDescribeOutput as j, type GraphDiagramDirection as k, type GraphDiagramOptions as l, type GraphDiffChange as m, type GraphDiffResult as n, type GraphDumpOptions as o, type GraphFactoryContext as p, type GraphNodeFactory as q, type GraphObserveAll as r, type GraphObserveOne as s, type GraphPersistSnapshot as t, type ObserveEvent as u, type ObserveOptions as v, type ObserveResult as w, type ObserveTheme as x, type ObserveThemeName as y, type ReachableOptions as z };

package/dist/{index-DhXznWyH.d.ts → index-8a605sg9.d.ts}

@@ -1,5 +1,5 @@
-import { N as Node } from './meta-BV4pj9ML.js';
-import { G as Graph } from './graph-Dc-P9BVm.js';
+import { N as Node } from './meta-BnG7XAaE.js';
+import { G as Graph } from './graph-mILUUqW8.js';
 
 /** Pluggable measurement backend. */
 interface MeasurementAdapter {