[breadboard] Make MutableGraph the actual store of nodes, kits, gra…

…phs, modules, edges

- **Start passing `AffectedNodes` instead of `NodeIdentifier`.**
- **Make only one `MutableGraph` instance per BGL.**
- **Move `GraphDescriptor` instance to `MutableGraph`.**
- **Make NodeCache less lazy.**
- **Introduce `GraphDescriptorHandle` and `DescriberManager`.**
- **Move all describer machinery out of `InspectableGraph`.**
- **Unify `MutableGraph` initialization.**
- **Remove `InspectableGraph.#url`.**
- **Use `GraphDescriptorHandle` in `InspectableGraph` constructor.**
- **Introduce `GraphQueries` and start using it.**
- **Remove `InspectableGraph` dependency from `NodeCache`.**
- **Introduce `InspectableKitCache`.**
- **Move `InspectableGraphOptions` to `MutableGraph`.**
- **Teach `Node` to use `MutableGraph` instead of `InspectableGraph`.**
- **Add `InspectableGraphCache`.**
- **Start using `InspectableGraphCache` in earnest.**
- **Use graphs cache everywhere.**
- **Introduce `MutableGraphImpl` and invert its relationship to
`InspectableGraph`.**
- **Fewer deps on `Graph`.**
- **Rename `populate` to `rebuild` for all caches.**
- **Switch to factory pattern in `EdgeCache`.**
- **Split `EdgeCache` and `NodeCache` out into separate files.**
- **docs(changeset): Make `MutableGraph` the actual store of nodes,
kits, graphs, modules, edges.**

Progress on #3836

.changeset/beige-ears-lick.md

@@ -0,0 +1,6 @@
+---
+"@breadboard-ai/visual-editor": minor
+"@google-labs/breadboard": minor
+---
+
+Make `MutableGraph` the actual store of nodes, kits, graphs, modules, edges.

packages/breadboard/src/editor/events.ts

@@ -6,6 +6,7 @@
 
 import { GraphDescriptor, NodeIdentifier } from "../types.js";
 import {
+  AffectedNode,
   ChangeEventType,
   ErrorRejection,
   GraphChangeEvent,
@@ -24,7 +25,7 @@ export class ChangeEvent extends Event implements GraphChangeEvent {
     public version: number,
     public visualOnly: boolean,
     public changeType: ChangeEventType,
-    public affectedNodes: NodeIdentifier[],
+    public affectedNodes: AffectedNode[],
     public affectedModules: NodeIdentifier[]
   ) {
     super(ChangeEvent.eventName, {

packages/breadboard/src/editor/graph.ts

@@ -4,7 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { inspectableGraph } from "../inspector/graph.js";
 import { InspectableGraphWithStore } from "../inspector/types.js";
 import { GraphDescriptor, GraphIdentifier, NodeIdentifier } from "../types.js";
 import {
@@ -21,6 +20,7 @@ import {
   EditTransform,
   EditTransformResult,
   EditOperationConductor,
+  AffectedNode,
 } from "./types.js";
 import { ChangeEvent, ChangeRejectEvent } from "./events.js";
 import { AddEdge } from "./operations/add-edge.js";
@@ -43,6 +43,7 @@ import {
 } from "../run/run-imperative-graph.js";
 import { AddGraph } from "./operations/add-graph.js";
 import { RemoveGraph } from "./operations/remove-graph.js";
+import { inspectableGraph } from "../inspector/mutable-graph.js";
 
 const validImperativeEdits: EditSpec["type"][] = [
   "addmodule",
@@ -107,7 +108,7 @@ export class Graph implements EditableGraph {
 
   #updateGraph(
     visualOnly: boolean,
-    affectedNodes: NodeIdentifier[],
+    affectedNodes: AffectedNode[],
     affectedModules: ModuleIdentifier[]
   ) {
     this.#version++;
@@ -233,7 +234,7 @@ export class Graph implements EditableGraph {
     // Presume that all edits will be visual only.
     let visualOnly = true;
     // Collect affected nodes
-    const affectedNodes: NodeIdentifier[][] = [];
+    const affectedNodes: AffectedNode[][] = [];
     // Collect affected modules
     const affectedModules: NodeIdentifier[][] = [];
     let context: EditOperationContext;

packages/breadboard/src/editor/operations/add-edge.ts

@@ -18,11 +18,13 @@ import {
   unfixUpStarEdge,
 } from "../../inspector/edge.js";
 import { toSubgraphContext } from "../subgraph-context.js";
+import { GraphIdentifier } from "@breadboard-ai/types";
 
 export class AddEdge implements EditOperation {
   async can(
     edge: EditableEdgeSpec,
-    inspector: InspectableGraph
+    inspector: InspectableGraph,
+    graphId: GraphIdentifier
   ): Promise<SingleEditResult> {
     edge = unfixUpStarEdge(edge);
     if (inspector.hasEdge(edge)) {
@@ -84,7 +86,10 @@ export class AddEdge implements EditOperation {
     }
     return {
       success: true,
-      affectedNodes: [edge.from, edge.to],
+      affectedNodes: [
+        { id: edge.from, graphId },
+        { id: edge.to, graphId },
+      ],
       affectedModules: [],
       affectedGraphs: [],
     };
@@ -107,7 +112,7 @@ export class AddEdge implements EditOperation {
       return subgraphContext;
     }
     const { graph, inspector, store } = subgraphContext.result;
-    const can = await this.can(edge, inspector);
+    const can = await this.can(edge, inspector, graphId);
     if (!can.success) {
       return can;
     }
@@ -119,7 +124,10 @@ export class AddEdge implements EditOperation {
     graph.edges.push(edge);
     return {
       success: true,
-      affectedNodes: [edge.from, edge.to],
+      affectedNodes: [
+        { id: edge.from, graphId },
+        { id: edge.to, graphId },
+      ],
       affectedModules: [],
       affectedGraphs: [],
     };

packages/breadboard/src/editor/operations/add-node.ts

@@ -68,7 +68,7 @@ export class AddNode implements EditOperation {
     store.nodeStore.add(node, graphId);
     return {
       success: true,
-      affectedNodes: [node.id],
+      affectedNodes: [{ id: node.id, graphId }],
       affectedModules: [],
       affectedGraphs: [],
     };

packages/breadboard/src/editor/operations/change-configuration.ts

@@ -73,7 +73,7 @@ export class ChangeConfiguration implements EditOperation {
     }
     return {
       success: true,
-      affectedNodes: [id],
+      affectedNodes: [{ id, graphId }],
       affectedModules: [],
       affectedGraphs: [],
     };

packages/breadboard/src/editor/operations/change-edge.ts

@@ -17,12 +17,14 @@ import { AddEdge } from "./add-edge.js";
 import { edgesEqual, findEdgeIndex } from "../edge.js";
 import { fixUpStarEdge } from "../../inspector/edge.js";
 import { toSubgraphContext } from "../subgraph-context.js";
+import { GraphIdentifier } from "@breadboard-ai/types";
 
 export class ChangeEdge implements EditOperation {
   async can(
     from: EditableEdgeSpec,
     to: EditableEdgeSpec,
-    inspector: InspectableGraph
+    inspector: InspectableGraph,
+    graphId: GraphIdentifier
   ): Promise<SingleEditResult> {
     if (edgesEqual(from, to)) {
       return {
@@ -33,10 +35,10 @@ export class ChangeEdge implements EditOperation {
       };
     }
     const canRemoveOp = new RemoveEdge();
-    const canRemove = await canRemoveOp.can(from, inspector);
+    const canRemove = await canRemoveOp.can(from, inspector, graphId);
     if (!canRemove.success) return canRemove;
     const canAddOp = new AddEdge();
-    const canAdd = await canAddOp.can(to, inspector);
+    const canAdd = await canAddOp.can(to, inspector, graphId);
     if (!canAdd.success) return canAdd;
     return {
       success: true,
@@ -63,7 +65,7 @@ export class ChangeEdge implements EditOperation {
     }
 
     const { graph, inspector } = subgraphContext.result;
-    const can = await this.can(from, to, inspector);
+    const can = await this.can(from, to, inspector, graphId);
     if (!can.success) {
       return can;
     }
@@ -89,7 +91,10 @@ export class ChangeEdge implements EditOperation {
     }
     return {
       success: true,
-      affectedNodes: [edge.from, edge.to],
+      affectedNodes: [
+        { id: edge.from, graphId },
+        { id: edge.to, graphId },
+      ],
       affectedModules: [],
       affectedGraphs: [],
     };

packages/breadboard/src/editor/operations/change-metadata.ts

@@ -78,7 +78,7 @@ export class ChangeMetadata implements EditOperation {
         ...metadata,
       };
     }
-    const affectedNodes = visualOnly ? [] : [id];
+    const affectedNodes = visualOnly ? [] : [{ id, graphId }];
     return {
       success: true,
       visualOnly,

packages/breadboard/src/editor/operations/remove-edge.ts

@@ -15,11 +15,13 @@ import { InspectableGraph } from "../../inspector/types.js";
 import { fixUpStarEdge } from "../../inspector/edge.js";
 import { findEdgeIndex } from "../edge.js";
 import { toSubgraphContext } from "../subgraph-context.js";
+import { GraphIdentifier } from "@breadboard-ai/types";
 
 export class RemoveEdge implements EditOperation {
   async can(
     spec: EditableEdgeSpec,
-    inspector: InspectableGraph
+    inspector: InspectableGraph,
+    graphId: GraphIdentifier
   ): Promise<SingleEditResult> {
     if (!inspector.hasEdge(spec)) {
       return {
@@ -29,7 +31,10 @@ export class RemoveEdge implements EditOperation {
     }
     return {
       success: true,
-      affectedNodes: [spec.from, spec.to],
+      affectedNodes: [
+        { id: spec.from, graphId },
+        { id: spec.to, graphId },
+      ],
       affectedModules: [],
       affectedGraphs: [],
     };
@@ -51,7 +56,7 @@ export class RemoveEdge implements EditOperation {
       return subgraphContext;
     }
     const { graph, inspector, store } = subgraphContext.result;
-    const can = await this.can(edge, inspector);
+    const can = await this.can(edge, inspector, graphId);
     if (!can.success) {
       return can;
     }
@@ -62,7 +67,10 @@ export class RemoveEdge implements EditOperation {
     store.edgeStore.remove(foundEdge, graphId);
     return {
       success: true,
-      affectedNodes: [edge.from, edge.to],
+      affectedNodes: [
+        { id: edge.from, graphId },
+        { id: edge.to, graphId },
+      ],
       affectedModules: [],
       affectedGraphs: [],
     };

packages/breadboard/src/editor/operations/remove-node.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { NodeIdentifier } from "@breadboard-ai/types";
+import { GraphIdentifier, NodeIdentifier } from "@breadboard-ai/types";
 import {
   EditOperation,
   EditOperationContext,
@@ -17,7 +17,8 @@ import { toSubgraphContext } from "../subgraph-context.js";
 export class RemoveNode implements EditOperation {
   async can(
     id: NodeIdentifier,
-    inspector: InspectableGraph
+    inspector: InspectableGraph,
+    graphId: GraphIdentifier
   ): Promise<SingleEditResult> {
     const exists = !!inspector.nodeById(id);
     if (!exists) {
@@ -28,7 +29,7 @@ export class RemoveNode implements EditOperation {
     }
     return {
       success: true,
-      affectedNodes: [id],
+      affectedNodes: [{ id, graphId }],
       affectedModules: [],
       affectedGraphs: [],
     };
@@ -49,7 +50,7 @@ export class RemoveNode implements EditOperation {
       return subgraphContext;
     }
     const { graph, inspector, store } = subgraphContext.result;
-    const can = await this.can(id, inspector);
+    const can = await this.can(id, inspector, graphId);
     if (!can.success) {
       return can;
     }
@@ -67,7 +68,7 @@ export class RemoveNode implements EditOperation {
     store.nodeStore.remove(id, graphId);
     return {
       success: true,
-      affectedNodes: [id],
+      affectedNodes: [{ id, graphId }],
       affectedModules: [],
       affectedGraphs: [],
     };

packages/breadboard/src/editor/types.ts

@@ -31,7 +31,7 @@ export type GraphChangeEvent = Event & {
   version: number;
   visualOnly: boolean;
   changeType: ChangeEventType;
-  affectedNodes: NodeIdentifier[];
+  affectedNodes: AffectedNode[];
 };
 
 export type ErrorRejection = {
@@ -283,7 +283,7 @@ export type SingleEditResult =
     }
   | {
       success: true;
-      affectedNodes: NodeIdentifier[];
+      affectedNodes: AffectedNode[];
       affectedModules: ModuleIdentifier[];
       affectedGraphs: GraphIdentifier[];
       /**
@@ -298,6 +298,11 @@ export type SingleEditResult =
       visualOnly?: boolean;
     };
 
+export type AffectedNode = {
+  id: NodeIdentifier;
+  graphId: GraphIdentifier;
+};
+
 export type EditResultLogEntry = {
   edit: EditSpec["type"];
   result: SingleEditResult;