@graphrefly/graphrefly 0.36.0 → 0.38.0

package/dist/{graph-Cv-8x0ZI.d.ts → graph-BjW1taJl.d.ts}

@@ -1,8 +1,97 @@
 import { A as Actor, p as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-fSc-hCv8.js';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-CC6EPdpK.js';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-BYqlATmg.js';
 import { StorageHandle } from './extra/storage-core.js';
 import { SnapshotStorageTier } from './extra/storage-tiers.js';
 
+/**
+ * Pure structural diff over `GraphDescribeOutput` snapshots.
+ *
+ * Produces a {@link DescribeChangeset} of {@link DescribeEvent}s describing the
+ * topology delta from `prev` → `next`. Used by `Graph.describe({ reactive:
+ * "diff" })` internally and re-exported here for static-snapshot diffing
+ * (e.g. computing the topology delta between two persisted snapshots without
+ * spinning up a live graph).
+ *
+ * Topology-only — no value/state events. The data layer lives in
+ * `Graph.observe`. Per Tier 1.5.1 (locked Session A.1), `DescribeEvent` and
+ * {@link ObserveEvent} have disjoint type sets so a consumer can route both
+ * streams without ambiguity.
+ *
+ * `flushedAt_ns` is taken from `core/clock.ts`'s `monotonicNs()` so callers can
+ * order changesets across the same process without wall-clock skew.
+ *
+ * @module
+ */
+
+/**
+ * Meta dictionary attached to a node, as surfaced by
+ * {@link DescribeNodeOutput.meta}. Aliased here so {@link DescribeEvent}'s
+ * `node-meta-changed` variant has a stable, narrow type.
+ */
+type Meta = Record<string, unknown>;
+/**
+ * One topology delta between two `describe()` snapshots. Disjoint from
+ * `ObserveEvent` (the data-layer envelope).
+ */
+type DescribeEvent = {
+    type: "node-added";
+    path: string;
+    node: DescribeNodeOutput;
+} | {
+    type: "node-removed";
+    path: string;
+} | {
+    type: "node-meta-changed";
+    path: string;
+    prevMeta: Meta;
+    nextMeta: Meta;
+} | {
+    type: "edge-added";
+    from: string;
+    to: string;
+} | {
+    type: "edge-removed";
+    from: string;
+    to: string;
+} | {
+    type: "subgraph-mounted";
+    path: string;
+} | {
+    type: "subgraph-unmounted";
+    path: string;
+};
+/**
+ * Coalesced batch of {@link DescribeEvent}s emitted as a single DATA wave by
+ * `Graph.describe({ reactive: "diff" })` per outermost batch flush.
+ *
+ * `flushedAt_ns` is monotonic (from `core/clock.ts`); compare against another
+ * changeset's `flushedAt_ns` to order them. `events` is empty only when
+ * `topologyDiff` is called with two structurally identical snapshots; reactive
+ * variants suppress empty changesets so consumers don't see no-op DATA waves.
+ */
+type DescribeChangeset = {
+    events: ReadonlyArray<DescribeEvent>;
+    flushedAt_ns: number;
+};
+/**
+ * Pure topology delta from `prev` → `next`. No I/O, no node references — purely
+ * over the JSON shape `Graph.describe()` returns.
+ *
+ * Event ordering within a changeset:
+ *   1. `subgraph-mounted` (added subgraphs first — their nodes follow)
+ *   2. `node-added`
+ *   3. `node-meta-changed`
+ *   4. `edge-added`
+ *   5. `edge-removed`
+ *   6. `node-removed`
+ *   7. `subgraph-unmounted` (last — node removals already reported)
+ *
+ * Each group is emitted in code-point sort order on the path / `${from}->${to}`
+ * key so the changeset is deterministic across runs (useful for snapshot
+ * tests and golden-output assertions).
+ */
+declare function topologyDiff(prev: GraphDescribeOutput, next: GraphDescribeOutput): DescribeChangeset;
+
 /**
  * Causal walkback over a {@link Graph.describe} snapshot (roadmap §9.2).
  *
@@ -222,6 +311,25 @@ interface GraphOptions {
      * time — not mutable afterward (ring buffers can't resize cleanly).
      */
     traceCapacity?: number;
+    /**
+     * Tier 1.5.3 Phase 2.5 (Session A.1 lock + Phase 2.5 design DG1=B, 2026-04-27).
+     * Top-level factory identifier for Graph-returning factories (`agentMemory`,
+     * `harnessLoop`, `pipelineGraph`, etc.). When set, `describe()` surfaces
+     * `factory` + `factoryArgs` at the top of `GraphDescribeOutput` so consumers
+     * can identify provenance, and `compileSpec` can delegate reconstruction to
+     * `catalog.graphFactories[factory]` with `factoryArgs`. Prefer the
+     * post-construction `Graph.prototype.tagFactory(name, args?)` mutator inside
+     * the factory body over passing here directly.
+     */
+    factory?: string;
+    /**
+     * JSON-serializable subset of the construction args. For non-JSON fields
+     * (LLMAdapter, callbacks, embedders), prefer the {@link placeholderArgs}
+     * helper which substitutes descriptive `"<Node>"` / `"<function>"` strings
+     * (DG2 = ii). Catalog `graphFactories` recipients receive this back during
+     * `compileSpec` to recreate the graph with the user-supplied runtime ctx.
+     */
+    factoryArgs?: unknown;
     [key: string]: unknown;
 }
 /** Filter for {@link Graph.describe} — object-style partial match or predicate. */
@@ -247,7 +355,32 @@ type GraphActorOptions = {
 };
 /** Options for {@link Graph.describe} (Phase 3.3b progressive disclosure). */
 type GraphDescribeOptions = {
-    actor?: Actor;
+    /**
+     * Scope `describe()` to what `actor` is allowed to observe. Accepts a
+     * static {@link Actor} (resolved at call time) or a `Node<Actor>` — when a
+     * Node is passed and `reactive: true` is set, the reactive describe handle
+     * subscribes to the actor node and re-derives whenever the actor changes,
+     * so harnesses that bind a reactive actor (e.g. per-turn `currentActor`
+     * state) get a single live describe Node instead of re-calling
+     * `describe({ actor })` per turn.
+     *
+     * **Cache-undefined semantics:** when a `Node<Actor>` is supplied whose
+     * `cache` is `undefined` (e.g. a `producer` that has not yet emitted),
+     * describe is treated identically to `actor: undefined` — i.e. **no
+     * scoping** (full visibility). This matches every other Node-cache read in
+     * the codebase, but means a not-yet-active actor node degrades to "describe
+     * everything." Activate the actor node (subscribe + emit, or seed via
+     * `state(initial)`) before calling `describe` if you rely on guard
+     * scoping. In `reactive: true` mode the describe re-derives once the
+     * actor node populates.
+     *
+     * **Terminal-type handling:** if the supplied `Node<Actor>` emits
+     * `COMPLETE`, `ERROR`, or `TEARDOWN`, the reactive describe releases the
+     * actor subscription and re-derives one last time against the final
+     * `actor.cache` value. Subsequent describe outputs reflect that frozen
+     * cache until `handle.dispose()` runs.
+     */
+    actor?: Actor | Node<Actor>;
     /**
      * Node filter. Filters operate on whatever fields the chosen `detail` level
      * provides. For `metaHas` and `status` filters, use `detail: "standard"` or
@@ -307,14 +440,18 @@ type GraphDescribeOptions = {
      */
     asciiCharset?: "unicode" | "ascii";
     /**
-     * Reactive describe (D2): when `true`, return `{ node, dispose }` where `node`
-     * emits a fresh `GraphDescribeOutput` (or format string, if `format` is set)
-     * every time the graph state settles. Same coalescing as
-     * {@link Graph.explain} with `{ reactive: true }` — one recompute per
-     * outermost drain via the batch-flush hook, so large batched mutations
-     * don't amplify describe work per event.
-     */
-    reactive?: boolean;
+     * Reactive describe (D2):
+     * - `true` — return `{ node, dispose }` where `node` emits a fresh
+     *   `GraphDescribeOutput` (or format string, if `format` is set) every time
+     *   the graph state settles. Same coalescing as {@link Graph.explain} with
+     *   `{ reactive: true }`.
+     * - `"diff"` — return `{ node, dispose }` where `node` emits a
+     *   {@link DescribeChangeset} per topology change. Empty changesets are
+     *   suppressed; the initial cache is a synthetic full-add diff so a fresh
+     *   subscriber sees the current topology as adds via push-on-subscribe.
+     *   (Tier 1.5.1 — Session A.1 lock).
+     */
+    reactive?: boolean | "diff";
     /** Reactive-only: name for the backing derived node (default `"describe"`). */
     reactiveName?: string;
 };
@@ -332,6 +469,16 @@ type GraphDescribeOutput = {
         to: string;
     }>;
     subgraphs: string[];
+    /**
+     * Top-level factory identifier (Tier 1.5.3 Phase 2.5 — DG1=B). Present when
+     * the graph was constructed by a Graph-returning factory that called
+     * `Graph.prototype.tagFactory(name, args?)` (or set `GraphOptions.factory`).
+     * Used by `compileSpec` for catalog-based reconstruction via
+     * `catalog.graphFactories[factory]`.
+     */
+    factory?: string;
+    /** JSON-serializable construction args paired with `factory`. */
+    factoryArgs?: unknown;
     /**
      * Re-read the live graph with higher detail (Phase 3.3b).
      * Returns a new `GraphDescribeOutput`; the original remains a snapshot.
@@ -494,6 +641,26 @@ type GraphObserveAll = {
  * - `"full"` — standard + timeline + causal + derived.
  */
 type ObserveDetail = "minimal" | "standard" | "full";
+/**
+ * Tier name for {@link ObserveEvent} filtering. Aligns with spec §1.2 message
+ * tier semantics — each `ObserveTier` corresponds to one or more protocol
+ * message types. Used by {@link ObserveOptions.tiers} to scope observation to
+ * a subset of event categories (e.g. `tiers: ["error", "complete", "teardown"]`
+ * for failure-only health monitoring).
+ */
+type ObserveTier = ObserveEvent["type"];
+/**
+ * Coalesced batch of {@link ObserveEvent}s emitted as one DATA wave per
+ * outermost batch flush by `Graph.observe({ reactive: true })`.
+ *
+ * Disjoint from `DescribeChangeset` (the topology-layer envelope). Each event
+ * carries its own `path` so consumers route per-path without unwrapping the
+ * envelope first. `flushedAt_ns` is monotonic via `core/clock.ts`.
+ */
+type ObserveChangeset = {
+    events: ReadonlyArray<ObserveEvent>;
+    flushedAt_ns: number;
+};
 /** Options for structured observation modes on {@link Graph.observe}. */
 type ObserveOptions = {
     actor?: Actor;
@@ -511,6 +678,27 @@ type ObserveOptions = {
      * `"minimal"` filters to DATA-only events.
      */
     detail?: ObserveDetail;
+    /**
+     * Filter observed events to these tiers only. When omitted, all event types
+     * are delivered. Applies to both the structured callback and the reactive
+     * variants (`observe({ reactive: true })`).
+     *
+     * Example: `tiers: ["error", "complete", "teardown"]` for failure-only
+     * health monitoring; `tiers: ["data"]` for value-flow tracking.
+     */
+    tiers?: readonly ObserveTier[];
+    /**
+     * Return a `Node<ObserveChangeset>` that emits one DATA wave per outermost
+     * batch flush, with all observed events for that flush coalesced into a
+     * single changeset. Auto-enables structured mode (the reactive variant
+     * delivers {@link ObserveEvent}s, not raw messages).
+     *
+     * Coalescing matches `describe({ reactive: true })`'s `registerBatchFlushHook`
+     * mechanism — N events in one batch → one changeset DATA wave at flush.
+     */
+    reactive?: boolean;
+    /** Optional name for the reactive changeset node when `reactive: true`. */
+    reactiveName?: string;
     /**
      * When set, auto-enables structured mode and attaches a logger.
      * - `"pretty"` — colored one-line output per event.
@@ -730,7 +918,24 @@ declare class Graph {
      *   equal the reserved meta segment `__meta__`).
      * @param opts - See {@link GraphOptions}. Stored frozen on the instance.
      */
+    /** Tier 1.5.3 Phase 2.5 — top-level factory tag for Graph-returning factories. */
+    private _factory?;
+    private _factoryArgs?;
     constructor(name: string, opts?: GraphOptions);
+    /**
+     * Tag this graph with its constructing factory's identifier and args.
+     * Used by Graph-returning factories (`agentMemory`, `harnessLoop`,
+     * `pipelineGraph`, etc.) so `describe()` exposes provenance and
+     * `compileSpec` can delegate reconstruction to
+     * `catalog.graphFactories[factory]`. Tier 1.5.3 Phase 2.5 (DG1=B).
+     *
+     * `factoryArgs` should be JSON-serializable. For non-JSON fields
+     * (LLMAdapter, callbacks, etc.), use {@link placeholderArgs} to
+     * substitute descriptive strings (DG2=ii).
+     *
+     * Returns `this` for fluent chaining inside factory bodies.
+     */
+    tagFactory(factory: string, factoryArgs?: unknown): this;
     /**
      * Walk ancestors up through `_parent`. Returns the chain starting at this
      * instance, ending at the root (a graph with no parent). O(depth).
@@ -990,6 +1195,9 @@ declare class Graph {
         reactive: true;
         format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
     }): ReactiveDescribeHandle<string>;
+    describe(options: GraphDescribeOptions & {
+        reactive: "diff";
+    }): ReactiveDescribeHandle<DescribeChangeset>;
     describe(options: GraphDescribeOptions & {
         reactive: true;
     }): ReactiveDescribeHandle<GraphDescribeOutput>;
@@ -1051,6 +1259,14 @@ declare class Graph {
     };
     private _explainStatic;
     private _describeReactive;
+    /**
+     * Reactive topology-diff variant of `describe()`. Wraps `_describeReactive`'s
+     * snapshot stream and emits a `DescribeChangeset` per change, suppressing
+     * empty changesets. The initial cache is a synthetic full-add diff so a
+     * fresh subscriber sees the current topology as a single `node-added` /
+     * `edge-added` / `subgraph-mounted` payload via push-on-subscribe.
+     */
+    private _describeReactiveDiff;
     private _explainReactive;
     /**
      * @internal Collect all qualified paths in this graph tree matching a
@@ -1077,10 +1293,26 @@ declare class Graph {
      * `ObserveResult` is also an `AsyncIterable<ObserveEvent>` — use
      * `for await (const ev of result)` for pull-based consumption.
      */
+    observe(path: string, options: ObserveOptions & {
+        reactive: true;
+    }): Node<ObserveChangeset>;
+    observe(options: ObserveOptions & {
+        reactive: true;
+    }): Node<ObserveChangeset>;
     observe(path: string, options?: ObserveOptions & StructuredTriggers): ObserveResult;
     observe(path: string, options?: ObserveOptions): GraphObserveOne;
     observe(options: ObserveOptions & StructuredTriggers): ObserveResult;
     observe(options?: ObserveOptions): GraphObserveAll;
+    /**
+     * Reactive observe variant — wraps the structured observer and emits one
+     * `ObserveChangeset` DATA per outermost batch flush, with all observed
+     * events for that flush coalesced into a single envelope. Tier filter
+     * (`options.tiers`) drops out-of-scope events before accumulation.
+     *
+     * Cleanup is producer-bound: the structured observer is torn down when the
+     * last consumer of the returned node unsubscribes.
+     */
+    private _observeReactive;
     /** Dispatch helper — builds a unified observer + its expand closure. */
     private _buildStructuredObserver;
     /**
@@ -1457,4 +1689,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): ReachableResult;
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-export { type ReachableOptions as A, type TraceEntry as B, type CausalChain as C, type DescribeFilter as D, type ExplainPathOptions as E, diffForWAL as F, Graph as G, explainPath as H, graphProfile as I, mermaidLiveUrl as J, reachable as K, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, type GraphOptions as a, type GraphPersistSnapshot as b, type GraphDescribeOptions as c, type GraphDescribeOutput as d, type CausalStep as e, GRAPH_META_SEGMENT as f, type GraphActorOptions as g, type GraphAttachStorageOptions as h, type GraphCheckpointRecord as i, type GraphDiagramDirection as j, type GraphDiagramOptions 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 GraphProfileOptions as r, type GraphProfileResult as s, type GraphVersionChange as t, type GraphWALDiff as u, type ObserveEvent as v, type ObserveOptions as w, type ObserveResult as x, type ObserveTheme as y, type ObserveThemeName as z };
+export { type ObserveTheme as A, type ObserveThemeName as B, type CausalChain as C, type DescribeFilter as D, type ExplainPathOptions as E, type ReachableOptions as F, Graph as G, type TraceEntry as H, diffForWAL as I, explainPath as J, graphProfile as K, mermaidLiveUrl as L, type Meta as M, type NodeProfile as N, type ObserveDetail 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 GraphPersistSnapshot as b, type GraphDescribeOptions as c, type GraphDescribeOutput 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 GraphDiagramOptions as m, type GraphDiffChange as n, type GraphDiffResult as o, type GraphFactoryContext as p, type GraphNodeFactory as q, type GraphObserveAll as r, type GraphObserveOne as s, type GraphProfileOptions as t, type GraphProfileResult as u, type GraphVersionChange as v, type GraphWALDiff as w, type ObserveEvent as x, type ObserveOptions as y, type ObserveResult as z };