@graphrefly/graphrefly 0.34.0 → 0.36.0

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

@@ -1,6 +1,7 @@
-import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-8qx0kgYt.js';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-CtDjj7cU.js';
-import { StorageTier, StorageHandle } from './extra/storage-core.js';
+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 { StorageHandle } from './extra/storage-core.js';
+import { SnapshotStorageTier } from './extra/storage-tiers.js';
 
 /**
  * Causal walkback over a {@link Graph.describe} snapshot (roadmap §9.2).
@@ -356,8 +357,8 @@ type GraphFactoryContext = {
 };
 type GraphNodeFactory = (name: string, context: GraphFactoryContext) => Node;
 /**
- * Checkpoint record shape passed to `StorageTier.save`. Written by
- * {@link Graph.attachStorage} per-tier according to each tier's
+ * Checkpoint record shape passed to `SnapshotStorageTier.save`. Written by
+ * {@link Graph.attachSnapshotStorage} per-tier according to each tier's
  * `compactEvery` cadence.
  *
  * `mode: "full"` → full snapshot. Baseline anchor emitted on the first save
@@ -372,6 +373,7 @@ type GraphNodeFactory = (name: string, context: GraphFactoryContext) => Node;
  * cross-version WAL replay).
  */
 type GraphCheckpointRecord = {
+    name: string;
     seq: number;
     timestamp_ns: number;
     format_version: number;
@@ -382,7 +384,7 @@ type GraphCheckpointRecord = {
     mode: "diff";
     diff: GraphWALDiff;
 });
-/** Options for {@link Graph.attachStorage}. */
+/** Options for {@link Graph.attachSnapshotStorage}. */
 type GraphAttachStorageOptions = {
     /**
      * Before the first save, attempt to restore from the first tier whose
@@ -392,7 +394,7 @@ type GraphAttachStorageOptions = {
     autoRestore?: boolean;
     /**
      * Limit the subscription surface (scoped observe). By default
-     * `attachStorage` observes every node in the graph tree; on large graphs
+     * `attachSnapshotStorage` observes every node in the graph tree; on large graphs
      * that's thousands of subscriptions just for tier-gating. Pass a path
      * list (or a single glob) to observe only those nodes.
      */
@@ -400,7 +402,7 @@ type GraphAttachStorageOptions = {
     /** Pre-save path-level filter — skip records triggered by paths that fail this predicate. */
     filter?: (name: string, described: DescribeNodeOutput) => boolean;
     /** Surfaced on tier save errors and autoRestore failures. */
-    onError?: (error: unknown, tier: StorageTier) => void;
+    onError?: (error: unknown, tier: SnapshotStorageTier<GraphCheckpointRecord>) => void;
 };
 /**
  * Event emitted by {@link Graph.topology} on every structural change to the
@@ -439,7 +441,7 @@ type GraphDiagramOptions = {
 /**
  * Snapshot format version (§3.8). Exported so the surface layer's
  * `saveSnapshot` writes the same `format_version` as
- * `Graph.attachStorage` — one source of truth prevents silent wire
+ * `Graph.attachSnapshotStorage` — one source of truth prevents silent wire
  * drift between auto-checkpoint and one-shot persistence paths.
  */
 declare const SNAPSHOT_VERSION = 1;
@@ -782,6 +784,14 @@ declare class Graph {
      * @param node - Node instance to own.
      * @param opts - `{ name?, annotation? }`.
      */
+    /**
+     * O(1) reverse lookup — returns the name the given Node was registered
+     * under via {@link Graph.add}, or `undefined` if it isn't registered here.
+     *
+     * Audit 2 (2026-04-24): replaces the orchestration's `findRegisteredNodePath`
+     * O(nodes²) describe-scan with direct `WeakMap<Node, string>` lookup.
+     */
+    nameOf(node: Node): string | undefined;
     add<T extends Node>(node: T, opts?: {
         name?: string;
         annotation?: string;
@@ -903,6 +913,8 @@ declare class Graph {
      * @returns The mounted `child`, for chaining.
      */
     mount<G extends Graph>(name: string, child: G): G;
+    mount(name: string): Graph;
+    mount(name: string, builder: (sub: Graph) => void): Graph;
     /**
      * Look up a node by qualified path (§3.5). Segments are separated by `::`.
      *
@@ -1206,7 +1218,7 @@ declare class Graph {
     toJSON(): GraphPersistSnapshot;
     /**
      * Unified persistence surface (§3.8). Cascades snapshot records through
-     * one or more {@link StorageTier}s, each with its own `debounceMs` /
+     * one or more {@link SnapshotStorageTier}s, each with its own `debounceMs` /
      * `compactEvery` cadence and independent diff baseline.
      *
      * Subscription gates on {@link messageTier} ≥ 3 (DATA/RESOLVED/terminal),
@@ -1220,7 +1232,7 @@ declare class Graph {
      * share a single snapshot computation per observe event; debounced tiers
      * compute their own snapshot when their timer fires.
      */
-    attachStorage(tiers: readonly StorageTier[], options?: GraphAttachStorageOptions): StorageHandle;
+    attachSnapshotStorage(tiers: readonly SnapshotStorageTier<GraphCheckpointRecord>[], options?: GraphAttachStorageOptions): StorageHandle;
     /**
      * Try tiers in order (hottest first); apply the first record that hits
      * via {@link Graph.restore}. Returns `true` if any tier produced a
@@ -1237,7 +1249,7 @@ declare class Graph {
      * the bad tier, some pre-existing). A subsequent successful tier's
      * `restore()` overwrites the overlapping slices.
      *
-     * Internal helper shared by {@link Graph.attachStorage}'s `autoRestore`
+     * Internal helper shared by {@link Graph.attachSnapshotStorage}'s `autoRestore`
      * option and the static {@link Graph.fromStorage} factory.
      */
     private _cascadeRestore;
@@ -1253,14 +1265,14 @@ declare class Graph {
      * @throws If no tier holds a restorable record matching `name` *and* no
      *   `factories` override is provided for dynamic nodes.
      */
-    static fromStorage(name: string, tiers: readonly StorageTier[], opts?: GraphOptions & {
+    static fromStorage(name: string, tiers: readonly SnapshotStorageTier<GraphCheckpointRecord>[], opts?: GraphOptions & {
         factories?: Record<string, GraphNodeFactory>;
         /**
          * Called when a tier throws during `load()` or when
          * {@link Graph.fromSnapshot} rejects a tier's record. The cascade
          * falls through to the next colder tier regardless.
          */
-        onError?: (err: unknown, tier: StorageTier) => void;
+        onError?: (err: unknown, tier: SnapshotStorageTier<GraphCheckpointRecord>) => void;
     }): Promise<Graph>;
     private _annotations;
     private readonly _traceRing;
@@ -1350,7 +1362,7 @@ type GraphDiffResult = {
  * slice for each added path so {@link replayWAL} can reconstruct nodes added
  * between full anchors (topology mutations inside a `compactEvery` window).
  *
- * `Graph.diff()` returns the audit shape (no payload); `attachStorage` writes
+ * `Graph.diff()` returns the audit shape (no payload); `attachSnapshotStorage` writes
  * this WAL shape. The two shapes stay structurally compatible — `GraphWALDiff`
  * is a superset.
  */
@@ -1445,4 +1457,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 GraphDescribeOptions as b, type GraphDescribeOutput as c, type GraphPersistSnapshot 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 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 };

package/dist/{graph-DaoydJ_u.d.cts → graph-kTltt95s.d.cts}

@@ -1,6 +1,7 @@
-import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-8qx0kgYt.cjs';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-BdjSt8ky.cjs';
-import { StorageTier, StorageHandle } from './extra/storage-core.cjs';
+import { A as Actor, p as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-fSc-hCv8.cjs';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-BGO6C7K9.cjs';
+import { StorageHandle } from './extra/storage-core.cjs';
+import { SnapshotStorageTier } from './extra/storage-tiers.cjs';
 
 /**
  * Causal walkback over a {@link Graph.describe} snapshot (roadmap §9.2).
@@ -356,8 +357,8 @@ type GraphFactoryContext = {
 };
 type GraphNodeFactory = (name: string, context: GraphFactoryContext) => Node;
 /**
- * Checkpoint record shape passed to `StorageTier.save`. Written by
- * {@link Graph.attachStorage} per-tier according to each tier's
+ * Checkpoint record shape passed to `SnapshotStorageTier.save`. Written by
+ * {@link Graph.attachSnapshotStorage} per-tier according to each tier's
  * `compactEvery` cadence.
  *
  * `mode: "full"` → full snapshot. Baseline anchor emitted on the first save
@@ -372,6 +373,7 @@ type GraphNodeFactory = (name: string, context: GraphFactoryContext) => Node;
  * cross-version WAL replay).
  */
 type GraphCheckpointRecord = {
+    name: string;
     seq: number;
     timestamp_ns: number;
     format_version: number;
@@ -382,7 +384,7 @@ type GraphCheckpointRecord = {
     mode: "diff";
     diff: GraphWALDiff;
 });
-/** Options for {@link Graph.attachStorage}. */
+/** Options for {@link Graph.attachSnapshotStorage}. */
 type GraphAttachStorageOptions = {
     /**
      * Before the first save, attempt to restore from the first tier whose
@@ -392,7 +394,7 @@ type GraphAttachStorageOptions = {
     autoRestore?: boolean;
     /**
      * Limit the subscription surface (scoped observe). By default
-     * `attachStorage` observes every node in the graph tree; on large graphs
+     * `attachSnapshotStorage` observes every node in the graph tree; on large graphs
      * that's thousands of subscriptions just for tier-gating. Pass a path
      * list (or a single glob) to observe only those nodes.
      */
@@ -400,7 +402,7 @@ type GraphAttachStorageOptions = {
     /** Pre-save path-level filter — skip records triggered by paths that fail this predicate. */
     filter?: (name: string, described: DescribeNodeOutput) => boolean;
     /** Surfaced on tier save errors and autoRestore failures. */
-    onError?: (error: unknown, tier: StorageTier) => void;
+    onError?: (error: unknown, tier: SnapshotStorageTier<GraphCheckpointRecord>) => void;
 };
 /**
  * Event emitted by {@link Graph.topology} on every structural change to the
@@ -439,7 +441,7 @@ type GraphDiagramOptions = {
 /**
  * Snapshot format version (§3.8). Exported so the surface layer's
  * `saveSnapshot` writes the same `format_version` as
- * `Graph.attachStorage` — one source of truth prevents silent wire
+ * `Graph.attachSnapshotStorage` — one source of truth prevents silent wire
  * drift between auto-checkpoint and one-shot persistence paths.
  */
 declare const SNAPSHOT_VERSION = 1;
@@ -782,6 +784,14 @@ declare class Graph {
      * @param node - Node instance to own.
      * @param opts - `{ name?, annotation? }`.
      */
+    /**
+     * O(1) reverse lookup — returns the name the given Node was registered
+     * under via {@link Graph.add}, or `undefined` if it isn't registered here.
+     *
+     * Audit 2 (2026-04-24): replaces the orchestration's `findRegisteredNodePath`
+     * O(nodes²) describe-scan with direct `WeakMap<Node, string>` lookup.
+     */
+    nameOf(node: Node): string | undefined;
     add<T extends Node>(node: T, opts?: {
         name?: string;
         annotation?: string;
@@ -903,6 +913,8 @@ declare class Graph {
      * @returns The mounted `child`, for chaining.
      */
     mount<G extends Graph>(name: string, child: G): G;
+    mount(name: string): Graph;
+    mount(name: string, builder: (sub: Graph) => void): Graph;
     /**
      * Look up a node by qualified path (§3.5). Segments are separated by `::`.
      *
@@ -1206,7 +1218,7 @@ declare class Graph {
     toJSON(): GraphPersistSnapshot;
     /**
      * Unified persistence surface (§3.8). Cascades snapshot records through
-     * one or more {@link StorageTier}s, each with its own `debounceMs` /
+     * one or more {@link SnapshotStorageTier}s, each with its own `debounceMs` /
      * `compactEvery` cadence and independent diff baseline.
      *
      * Subscription gates on {@link messageTier} ≥ 3 (DATA/RESOLVED/terminal),
@@ -1220,7 +1232,7 @@ declare class Graph {
      * share a single snapshot computation per observe event; debounced tiers
      * compute their own snapshot when their timer fires.
      */
-    attachStorage(tiers: readonly StorageTier[], options?: GraphAttachStorageOptions): StorageHandle;
+    attachSnapshotStorage(tiers: readonly SnapshotStorageTier<GraphCheckpointRecord>[], options?: GraphAttachStorageOptions): StorageHandle;
     /**
      * Try tiers in order (hottest first); apply the first record that hits
      * via {@link Graph.restore}. Returns `true` if any tier produced a
@@ -1237,7 +1249,7 @@ declare class Graph {
      * the bad tier, some pre-existing). A subsequent successful tier's
      * `restore()` overwrites the overlapping slices.
      *
-     * Internal helper shared by {@link Graph.attachStorage}'s `autoRestore`
+     * Internal helper shared by {@link Graph.attachSnapshotStorage}'s `autoRestore`
      * option and the static {@link Graph.fromStorage} factory.
      */
     private _cascadeRestore;
@@ -1253,14 +1265,14 @@ declare class Graph {
      * @throws If no tier holds a restorable record matching `name` *and* no
      *   `factories` override is provided for dynamic nodes.
      */
-    static fromStorage(name: string, tiers: readonly StorageTier[], opts?: GraphOptions & {
+    static fromStorage(name: string, tiers: readonly SnapshotStorageTier<GraphCheckpointRecord>[], opts?: GraphOptions & {
         factories?: Record<string, GraphNodeFactory>;
         /**
          * Called when a tier throws during `load()` or when
          * {@link Graph.fromSnapshot} rejects a tier's record. The cascade
          * falls through to the next colder tier regardless.
          */
-        onError?: (err: unknown, tier: StorageTier) => void;
+        onError?: (err: unknown, tier: SnapshotStorageTier<GraphCheckpointRecord>) => void;
     }): Promise<Graph>;
     private _annotations;
     private readonly _traceRing;
@@ -1350,7 +1362,7 @@ type GraphDiffResult = {
  * slice for each added path so {@link replayWAL} can reconstruct nodes added
  * between full anchors (topology mutations inside a `compactEvery` window).
  *
- * `Graph.diff()` returns the audit shape (no payload); `attachStorage` writes
+ * `Graph.diff()` returns the audit shape (no payload); `attachSnapshotStorage` writes
  * this WAL shape. The two shapes stay structurally compatible — `GraphWALDiff`
  * is a superset.
  */
@@ -1445,4 +1457,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 GraphDescribeOptions as b, type GraphDescribeOutput as c, type GraphPersistSnapshot 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 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 };

package/dist/imperative-audit-ahAE65a9.d.cts

@@ -0,0 +1,28 @@
+/**
+ * Imperative-controller-with-audit helper layer (Audit 2 — locked 2026-04-24).
+ *
+ * Five Phase-4 primitives share the same shape: imperative mutation methods +
+ * closure state + reactive audit log + freeze-at-entry + rollback-on-throw.
+ * This module factors out the common machinery so each primitive becomes
+ * declarative wiring over typed audit records:
+ *  - `gate`, `pipeline.gate`            (Wave A.2 Unit 8)
+ *  - `JobQueueGraph`                    (Wave B.3 Unit 15)
+ *  - `CqrsGraph.dispatch`               (Wave C.2 Unit 20)
+ *  - `CqrsGraph.saga`                   (Wave C.3 Unit 22)
+ *  - `processManager` (Wave 7)          [out of scope this commit]
+ *
+ * @internal — exposed for primitive impls only; not re-exported through any
+ * patterns/<x>/index.ts barrel.
+ */
+
+/** Shared base shape for every audit record. Per-primitive types extend this. */
+interface BaseAuditRecord {
+    readonly t_ns: number;
+    readonly seq?: number;
+    readonly handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+
+export type { BaseAuditRecord as B };

package/dist/imperative-audit-ahAE65a9.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Imperative-controller-with-audit helper layer (Audit 2 — locked 2026-04-24).
+ *
+ * Five Phase-4 primitives share the same shape: imperative mutation methods +
+ * closure state + reactive audit log + freeze-at-entry + rollback-on-throw.
+ * This module factors out the common machinery so each primitive becomes
+ * declarative wiring over typed audit records:
+ *  - `gate`, `pipeline.gate`            (Wave A.2 Unit 8)
+ *  - `JobQueueGraph`                    (Wave B.3 Unit 15)
+ *  - `CqrsGraph.dispatch`               (Wave C.2 Unit 20)
+ *  - `CqrsGraph.saga`                   (Wave C.3 Unit 22)
+ *  - `processManager` (Wave 7)          [out of scope this commit]
+ *
+ * @internal — exposed for primitive impls only; not re-exported through any
+ * patterns/<x>/index.ts barrel.
+ */
+
+/** Shared base shape for every audit record. Per-primitive types extend this. */
+interface BaseAuditRecord {
+    readonly t_ns: number;
+    readonly seq?: number;
+    readonly handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+
+export type { BaseAuditRecord as B };