@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/managers/DataManager.d.ts

@@ -1,33 +1,42 @@
-import { type DerivedGraph, type DuplicatePolicy, type GraphSnapshot } from "@graphty/graph-format";
+import { type DerivedGraph, type GraphSnapshot } from "@graphty/graph-format";
 import type { EdgeId } from "../catalog/types";
 import type { AdHocData } from "../config";
+import { WRITABLE_LANE } from "../data/lane";
 import type { ElementPositions } from "../data/positions";
-import { type ImportReport } from "../data/report";
-import { Edge, EdgeMap } from "../Edge";
-import type { LayoutEngine } from "../layout/LayoutEngine";
+import type { ImportReport } from "../data/report";
+import { Edge } from "../Edge";
+import { type LayoutEngine } from "../layout/LayoutEngine";
 import { MeshCache } from "../meshes/MeshCache";
 import { Node, NodeIdType } from "../Node";
-import type { DirectionProvenance } from "../session/types";
+import type { LaneStore } from "../session/GraphSession";
+import type { Dispatcher, UndoableContext } from "../session/project/Dispatcher";
+import { type AddEdgesOptions } from "../session/project/ingest";
+import type { GraphSlice } from "../session/project/state";
+import type { DirectionProvenance, HistoryCause, ReadonlyElementPositions } from "../session/types";
 import type { Styles } from "../Styles";
 import type { EventManager } from "./EventManager";
 import type { GraphContext } from "./GraphContext";
 import type { Manager } from "./interfaces";
-/** What a caller may say about one `addEdges` call that the configuration does not already say. */
-export interface AddEdgesOptions {
-    /** The JMESPath expression naming the source endpoint, overriding the configured one. */
-    readonly source?: string;
-    /** The JMESPath expression naming the target endpoint, overriding the configured one. */
-    readonly target?: string;
-    /**
-     * What to do with a record naming an ordered pair the graph already holds, overriding
-     * `data.knownFields.repeatedEdges` for this call alone.
-     *
-     * The expand-a-node path passes `"first"`, because "fetch the neighbourhood of this node" is a
-     * request that legitimately re-supplies edges the graph already has, and the element knows
-     * that about its own call site.
-     */
-    readonly repeated?: DuplicatePolicy;
-}
+export type { AddEdgesOptions } from "../session/project/ingest";
+/**
+ * A data manager as its own session reads it: every store member, with the writable lane under
+ * `positions`, which the session's dispatcher writes when it places, pins or restores nodes. No
+ * entry point exports it; the manager's own `positions` is read-only.
+ * @param manager - The data manager.
+ * @returns The store the session is handed.
+ */
+export declare function laneStoreOf(manager: DataManager): LaneStore;
+/**
+ * A standalone renderer test's reach into a data manager's collections: registering a render
+ * object it built by hand, as ingest would have. No entry point exports it; the collections are
+ * read-only to everything else, and nodes and edges arrive through the data doors.
+ */
+export declare const dataManagerInternals: {
+    /** Register a node under its id. */
+    adoptNode(manager: DataManager, node: Node): void;
+    /** Register an edge under its id, its endpoint pair and, when it has one, its row. */
+    adoptEdge(manager: DataManager, edge: Edge): void;
+};
 /**
  * Manages all data operations for nodes and edges
  * Handles CRUD operations, caching, and data source loading
@@ -58,26 +67,38 @@ export interface AddEdgesOptions {
 export declare class DataManager implements Manager {
     private eventManager;
     private styles;
-    nodes: Map<string | number, Node>;
+    private readonly nodeMap;
+    private readonly edgeMap;
+    private readonly edgeRows;
+    /**
+     * Every node the graph holds, keyed by id. Read-only: nodes arrive and leave through the data
+     * doors, which are undoable steps.
+     * @returns The nodes.
+     */
+    get nodes(): ReadonlyMap<string | number, Node>;
+    /** {@link DataManager.nodes}: the node map with no writer. */
+    private readonly nodeView;
     /**
      * Every edge the graph holds, keyed by `Edge.id`.
      *
      * The key type is `string` and not `string | number`, because `Edge.id` is the element's own
      * edge counter printed as a string and nothing else. While the key was widened, `getEdge(0)`
      * compiled, answered `undefined` for the edge whose id is `"0"`, and said nothing about it.
+     * @returns The edges.
      */
-    edges: Map<string, Edge>;
+    get edges(): ReadonlyMap<string, Edge>;
+    /** {@link DataManager.edges}: the edge map with no writer. */
+    private readonly edgeView;
     /** Goes up on every edge added or removed, so a cache over the edge set knows it is stale. */
     edgeVersion: number;
     nodeCache: Map<NodeIdType, Node>;
-    edgeCache: EdgeMap;
     /**
      * Render objects by their store edge index, so a freeze report's `edgeRemap` -- and a removal,
      * which hands back the incident edge indices and nothing else -- can find them in O(1). Sparse:
      * an index with no render object yet, or whose edge was removed, reads `undefined`.
+     * @returns The edges by row, read-only.
      */
-    readonly edgesByIndex: (Edge | undefined)[];
-    private logger;
+    get edgesByIndex(): readonly (Edge | undefined)[];
     /** The one graph-format builder and its cached snapshot; replaced only by `clear()`/`dispose()`. */
     private store;
     /**
@@ -91,7 +112,19 @@ export declare class DataManager implements Manager {
      * and a Clear never rewinds it.
      */
     private readonly inputs;
-    graphResults?: AdHocData;
+    /**
+     * Graph-level results a plugin algorithm without a descriptor wrote, kept as the `graphResults`
+     * value of the graph. Read-only, except to a plugin while `algo.legacy` runs it: what it writes
+     * then is part of that command's step.
+     * @returns The value, or undefined when none was written.
+     */
+    get graphResults(): AdHocData | undefined;
+    /**
+     * Write graph-level results; only a plugin can, while `algo.legacy` runs it.
+     * @param value - The results.
+     * @throws A `GraphtyError` with `E_UNSUPPORTED` outside a plugin run.
+     */
+    set graphResults(value: AdHocData | undefined);
     meshCache: MeshCache;
     private graphContext;
     private shouldStartLayout;
@@ -106,29 +139,34 @@ export declare class DataManager implements Manager {
      * encoding of two ids is ambiguous for some pair of them.
      */
     private pendingByPair;
+    /** Turns records and data sources into the graph; this manager draws what it produces. */
+    private readonly ingest;
     /**
-     * The store edge index each record identifier has already produced, when
-     * `knownFields.edgeIdPath` names one. Empty when it does not, which is the default.
-     */
-    private edgesByRecordId;
-    /** What the last load did, for `session.data.lastImport()`. Null until something has loaded. */
-    private importReport;
-    /**
-     * The endpoint expressions the load in progress resolved, so a chunked load probes ONCE.
-     *
-     * A file that spells one chunk's edges `source`/`target` and the next chunk's `from`/`to` is a
-     * broken file, and letting each chunk decide for itself makes the answer both unreportable and
-     * dependent on how the file happened to be split.
+     * The graph primitives every write goes through. A data manager on its own has nothing to
+     * record into; the graph's session hands it its own in {@link DataManager.bindSession}.
      */
-    private loadEndpoints;
-    /** The tally the load in progress is counting into, or null outside a load. */
-    private loadTally;
+    private graph;
+    /** The session's dispatcher, once bound: the data doors dispatch through it. */
+    private dispatcher;
+    /** The edges the last removal took out, for the doors that answer with them. */
+    private removedEdges;
+    /** Why rows are arriving: set while a dispatched command writes, for the `data-added` event. */
+    private cause;
     /**
      * Bumped by every REPLACING load as it is asked for, and by `supersedeLoads`. A load that
      * sees it move has been overtaken, and stops with `E_SUPERSEDED` rather than touching the
      * graph: see `addDataFromSource`.
      */
     private replaceGeneration;
+    /** The loads dispatched and not yet settled, so a newer replacing load can withdraw them. */
+    private readonly inFlight;
+    /**
+     * The id each load's events carry, by its source's configuration: the dispatcher hands the
+     * command on as a frozen copy, and `data.import` keeps only the configuration by reference.
+     */
+    private readonly loadIds;
+    /** The id of the import running now, for the events it emits. */
+    private loadId;
     /**
      * Creates an instance of DataManager
      * @param eventManager - Event manager for emitting data events
@@ -146,6 +184,11 @@ export declare class DataManager implements Manager {
      * @returns the snapshot
      */
     getSnapshot(): GraphSnapshot;
+    /**
+     * Whether the next {@link getSnapshot} would freeze a new snapshot.
+     * @returns True when the store is not settled.
+     */
+    get snapshotStale(): boolean;
     /**
      * The undirected view of a snapshot, built once per snapshot and cached.
      * @param snapshot - a snapshot this manager produced
@@ -160,9 +203,28 @@ export declare class DataManager implements Manager {
      * in one place and nothing is lost when the graph is frozen again. A row that no layout has
      * placed reads as NaN, never as the origin: zero is a real coordinate and "not placed yet" is
      * not.
+     *
+     * Read-only here: a write would move nodes with no step. The element's own engines reach the
+     * writable lane through `writableLane`; a consumer places nodes through
+     * `session.positions.set`.
+     * @returns the coordinates, read-only
+     */
+    get positions(): ReadonlyElementPositions;
+    /** The coordinates, read-only; reads whichever lane the store holds now. */
+    private readonly readonlyLane;
+    /**
+     * The writable lane, for the element's own engines and nodes. See `writableLane`.
      * @returns the live position array
      */
-    get positions(): ElementPositions;
+    get [WRITABLE_LANE](): ElementPositions;
+    /**
+     * Whether a load from a data source is still streaming records in.
+     *
+     * A static layout reads it to tell a chunk of a load, after which the whole graph is arranged
+     * again, from a reader's add to a finished graph, after which existing nodes stay put.
+     * @returns true between a load's first chunk and its end
+     */
+    get isLoading(): boolean;
     /**
      * How many nodes the DATA arrived carrying a coordinate for.
      *
@@ -185,6 +247,87 @@ export declare class DataManager implements Manager {
      * @returns the report, or null when nothing has been loaded into this graph
      */
     get lastImport(): ImportReport | null;
+    /**
+     * Write through the session from here on: the data doors dispatch `data.apply` and
+     * `data.import`, and the session carries both out through this manager's ingest, over this
+     * manager's store.
+     * @param dispatcher - The session's dispatcher.
+     * @param hooks - What the graph does around a write.
+     * @param hooks.rowsAdded - Called by each command that adds rows, after it wrote them, with how
+     *     that command starts work as its deferred members.
+     * @param hooks.loading - Called with true when an import starts reading and false when it stops.
+     * @param hooks.removing - Called with the nodes and edges a removal names, before it writes.
+     */
+    bindSession(dispatcher: Dispatcher, hooks: {
+        rowsAdded(after: UndoableContext["after"] | undefined): void;
+        loading(active: boolean): void;
+        removing(nodes: readonly NodeIdType[], edges: readonly EdgeId[]): void;
+    }): void;
+    /**
+     * Carry out one mutation through ingest, drawing what it adds as it goes.
+     * @param mutation - The mutation.
+     * @param writer - The command's writer.
+     */
+    private applyMutation;
+    /**
+     * The id a node is held under, for an id that may be spelled as the other type (see
+     * {@link DataManager.getNode}); an edge id is taken as it is.
+     * @param target - Node or edge.
+     * @param id - The id as given.
+     * @returns The id the graph holds it under, or the one given when it holds none.
+     */
+    private resolveId;
+    /**
+     * Strict state: the drawn maps keyed exactly like the `graph` slice. An edge the slice holds
+     * may instead be waiting for an endpoint that has not arrived.
+     * @param slice - The slice the last pass derived.
+     * @returns One sentence per problem; empty when there is none.
+     */
+    sliceProblems(slice: GraphSlice): string[];
+    /**
+     * Bring the render objects in line with the `graph` slice: what the derivation lane's `graph`
+     * hook runs, forward and on undo, redo and rollback alike. A node or edge the slice holds and
+     * nothing draws is built; one drawn that the slice no longer holds is torn down; one whose
+     * record changed is handed the new record. Forward adds were drawn as they were ingested, so
+     * for them this finds nothing to build.
+     * @param slice - The slice to draw.
+     * @param dirty - The slice's keys changed since the last pass.
+     * @param cause - What moved the state, for the events.
+     * @returns How many rows were built and torn down.
+     */
+    reconcile(slice: GraphSlice, dirty: ReadonlySet<string>, cause: HistoryCause): {
+        added: number;
+        removed: number;
+    };
+    /**
+     * Tear down nodes' render objects and every render edge attached to one of them, leaving the
+     * store alone: the store already reflects the state being drawn.
+     * @param ids - The nodes.
+     * @param slice - The slice being drawn, which may still hold an edge of a node going.
+     * @returns The ids of the edges torn down with them and not left waiting.
+     */
+    private dropRenderNodes;
+    /**
+     * Tear down what draws rows a forward removal took out of the store: the edges first, since an
+     * edge reads its endpoints' meshes while it goes, then the nodes. One `elements-removed`.
+     * @param nodes - The node ids removed.
+     * @param edges - The edge ids removed, including every edge attached to a removed node.
+     */
+    private dropRendered;
+    /** Tear down every render object: the graph was emptied. */
+    private dropEverythingRendered;
+    /**
+     * Take one node's render object out of every structure that holds it and free it. Its edges
+     * must already be gone.
+     * @param node - The node.
+     */
+    private disposeRenderNode;
+    /**
+     * What ingest needs from the render half: which edges exist (built or pending), and what to
+     * do with each record once the store holds it.
+     * @returns the host, reading this manager's fields lazily
+     */
+    private ingestHost;
     /**
      * Build the store, wiring its three freeze callbacks back into this manager.
      *
@@ -291,27 +434,27 @@ export declare class DataManager implements Manager {
      */
     addNode(node: AdHocData, idPath?: string): void;
     /**
-     * The id `addNodes` reads off a node record.
-     * @param node - the record
+     * Replace every node with these, as one step: a node the records name again keeps its row and
+     * its edges, and one they no longer name goes, with its edges. A set past the render ceiling
+     * is refused with `E_TOO_LARGE` and the step rolls back, so the graph keeps the nodes it had.
+     * @param nodes - the nodes the graph should hold afterwards
      * @param idPath - JMESPath expression to extract the id; the configured node id path when unset
-     * @returns the node's id
-     */
-    nodeIdOf(node: Record<string | number, unknown>, idPath?: string): NodeIdType;
-    /**
-     * Refuse a replacing node set the renderer cannot hold, before the replace removes anything.
-     *
-     * The node half of what {@link setEdges} decides first: the new set is counted against an
-     * emptied graph, so a refused replace keeps the nodes the graph had.
-     * @param count - how many distinct nodes the graph would hold afterwards
-     * @throws A `GraphtyError` with `E_TOO_LARGE` when `count` is past the ceiling
      */
-    refuseNodeSetAboveCeiling(count: number): void;
+    setNodes(nodes: Record<string | number, unknown>[], idPath?: string): void;
     /**
      * Adds multiple nodes to the graph
      * @param nodes - Array of node data objects
      * @param idPath - JMESPath expression to extract node ID from data
      */
     addNodes(nodes: Record<string | number, unknown>[], idPath?: string): void;
+    /**
+     * Build the render object for a node the store has just taken.
+     * @param nodeId - the node id
+     * @param node - the raw record
+     * @param index - the row the store gave it; INVALID_INDEX for an id graph-format will not
+     *     take, and the node renders anyway. See the class comment.
+     */
+    private buildNode;
     /**
      * Build the render objects for pending edges whose nodes now exist.
      *
@@ -320,7 +463,7 @@ export declare class DataManager implements Manager {
      */
     private processPendingEdges;
     /**
-     * Record a freshly built render edge in all three of the places that index it.
+     * Record a freshly built render edge in both of the places that index it.
      * @param edge - the new render object
      * @param edgeIndex - the index the builder gave this edge. Never INVALID_INDEX: an edge whose
      *     endpoint ids graph-format will not store is rejected before it reaches here
@@ -346,7 +489,7 @@ export declare class DataManager implements Manager {
      */
     getNode(nodeId: NodeIdType): Node | undefined;
     /**
-     * Remove a node AND every edge attached to it.
+     * Remove a node AND every edge attached to it, as one undoable step.
      *
      * The cascade is what the name says, and it used to be missing: the store side already
      * tombstoned the incident edges, but their render objects survived with their meshes, their
@@ -362,11 +505,11 @@ export declare class DataManager implements Manager {
      */
     removeNodeAndIncidentEdges(nodeId: NodeIdType): readonly EdgeId[] | null;
     /**
-     * Take a node out of the store and tear down every edge that was attached to it.
-     * @param node - the node being removed
-     * @returns the ids of the edges that went with it
+     * Carry out one mutation: through the session's dispatcher once bound, so it is a step, or
+     * straight through the primitives on a data manager with no session.
+     * @param mutation - The mutation.
      */
-    private detachNodeFromStore;
+    private write;
     /**
      * Take one render edge out of every structure that holds it, and free its meshes.
      *
@@ -406,40 +549,17 @@ export declare class DataManager implements Manager {
      */
     addEdges(edges: Record<string | number, unknown>[], options?: AddEdgesOptions): void;
     /**
-     * The endpoint expressions this batch is read with, resolved once per load rather than once
-     * per batch when a load is in progress.
-     * @param edges - the batch's records
-     * @param options - the caller's overrides, if any
-     * @returns the expressions
+     * Build the render object for an edge the store has just taken, or defer it until both
+     * endpoints have one.
+     * @param stored - the edge, its resolved endpoints and the row and counter the store gave it
      */
-    private endpointsFor;
-    /**
-     * The edge a record repeats, or null when it repeats none.
-     * @param sourceId - the source endpoint id
-     * @param targetId - the target endpoint id
-     * @param recordId - the value of `knownFields.edgeIdPath`, when one is configured
-     * @returns the existing edge, or null
-     */
-    private knownEdgeFor;
+    private buildEdge;
     /**
      * The edge occupying one store row, whether or not its render object has been built.
      * @param edgeIndex - the row
      * @returns the existing edge, or null when the row is not one this manager holds
      */
     private existingAt;
-    /**
-     * Apply the repeat policy to one record that names an edge the graph already holds.
-     * @param known - the edge already present
-     * @param record - the repeating record
-     * @param weight - the repeating record's resolved weight
-     * @param policy - what to do about it
-     * @param sourceId - the source endpoint id, for the error message
-     * @param targetId - the target endpoint id, for the error message
-     * @param tally - the load's counters
-     * @returns true when the repeat has been dealt with and must not become an edge of its own
-     * @throws A `GraphtyError` with `E_DUPLICATE_EDGE` under the `"error"` policy.
-     */
-    private mergeRepeat;
     /**
      * Gets an edge by its ID
      * @param edgeId - Edge identifier
@@ -451,6 +571,11 @@ export declare class DataManager implements Manager {
      *
      * Plural because "the edge between a and b" stopped being a single thing the moment parallel
      * edges became representable.
+     *
+     * Answered by the store: the builder's incidence lists name the live edges between the two
+     * rows, and `edgesByIndex` turns each into its render object. An edge whose render object is
+     * still pending is left out, and so, in an undirected graph, is an edge recorded the other way
+     * round -- the pair is ORDERED, the same question for either direction.
      * @param srcNodeId - Source node identifier
      * @param dstNodeId - Destination node identifier
      * @returns the edges, oldest first; empty when there are none
@@ -470,22 +595,6 @@ export declare class DataManager implements Manager {
      *     whatever `addEdges` throws.
      */
     setEdges(edges: Record<string | number, unknown>[], options?: AddEdgesOptions): void;
-    /**
-     * How many edges a batch would add, by the same tests the ingest loop applies.
-     *
-     * A record whose endpoint ids graph-format will not store adds nothing (the loop rejects it).
-     * Under the `keep` policy every other record is an edge. Under a folding policy a record that
-     * repeats an edge the graph holds, or a record earlier in the same batch, folds into it and
-     * adds nothing; a repeat is named the way `knownEdgeFor` names it, by record id when one is
-     * configured and stored, else by the ordered endpoint pair.
-     * @param edges - the batch
-     * @param endpoints - the batch's endpoint expressions
-     * @param policy - the repeat policy the batch is under
-     * @param replacing - true when every held edge is about to be removed, so none of them can be
-     *     repeated
-     * @returns the number of edges the batch would add
-     */
-    private edgesAdded;
     /**
      * Removes an edge from the graph
      * @param edgeId - Edge identifier to remove
@@ -493,47 +602,10 @@ export declare class DataManager implements Manager {
      */
     removeEdge(edgeId: string): boolean;
     /**
-     * Adopt the direction a file declared, and say out loud when the element could not.
-     *
-     * The element reports the direction its DATA declares, so that a file which says it is
-     * undirected is not counted, measured or offered algorithms as though it were a digraph. What
-     * it must never do is overrule the consumer: `data.directed` set to a boolean settles the
-     * question and locks the builder, and this reports that rather than fighting it.
-     * @param type - the data source type, for the log line
-     * @param declaration - what the file said, or null when it said nothing
-     * @returns true once the question is settled and need not be asked again this import; false
-     *     while the source has still declared nothing
-     */
-    private applyDeclaredDirection;
-    /**
-     * Reserve a load's place in line, at the moment the caller asked for it.
-     *
-     * A caller that reads a file or sniffs a URL before it loads calls this FIRST, so a load that
-     * was asked for later still wins however long the earlier one spends reading. A replacing load
-     * supersedes every load reserved before it.
-     * @param replace - Whether the load will replace the graph
-     * @returns The generation to hand to `addDataFromSource` and `throwIfSuperseded`
-     */
-    beginLoad(replace: boolean): number;
-    /**
-     * Abandon every load in flight: each rejects with `E_SUPERSEDED` and adds nothing more.
-     * The element's `clearData` calls this, so a load finishing after the graph was closed does
-     * not bring its data back.
-     */
-    supersedeLoads(): void;
-    /**
-     * Throw `E_SUPERSEDED` when a load reserved at `generation` has been overtaken.
-     * @param generation - What `beginLoad` returned for the load
-     * @param type - The load's format, for the message
-     */
-    throwIfSuperseded(generation: number, type: string): void;
-    /**
-     * Loads data from a registered data source
-     *
-     * A REPLACING load reads the whole source into memory before it touches the store, and only
-     * once the source has finished without an error does it clear the graph and add what it read.
-     * A malformed or empty file therefore leaves the graph it would have replaced exactly as it
-     * was. An additive load streams each chunk straight in, as it always has.
+     * Loads data from a registered data source, as one step: a `data.import` on its turn in the
+     * queue. A REPLACING load empties the graph in the same step, and a load that fails rolls the
+     * whole step back, so a malformed or empty file leaves the graph it would have replaced
+     * exactly as it was.
      *
      * A load that reads no node records and no edge records at all fails with `E_EMPTY_LOAD`
      * rather than completing with zero counts. A file of edges alone is not empty: its endpoints
@@ -550,54 +622,49 @@ export declare class DataManager implements Manager {
      * @param load.replace - Swap the graph for what the source holds, once it has all parsed
      * @param load.generation - The place `beginLoad` reserved for this load when the caller's call
      *     was made; left unset, the load takes its place now
+     * @param load.coalesce - The key imports coalesce under while the first waits its turn
+     * @param load.setup - Declared at construction: it becomes the baseline
      */
     addDataFromSource(type: string, opts?: object, load?: {
         loadId?: number;
         replace?: boolean;
         generation?: number;
+        coalesce?: string;
+        setup?: boolean;
     }): Promise<void>;
     /**
-     * Freeze one load's counters into the report a consumer reads, and keep it for `lastImport`.
-     * @param format - the data source that read the file
-     * @param tally - what the load counted
-     * @returns the report
+     * Dispatch an import as one load: it carries its id into every event it emits, and it is
+     * withdrawn with `E_SUPERSEDED` once a replacing load asked for after it, or `clearData`,
+     * moves the generation on.
+     * @param command - The import.
+     * @param generation - What `beginLoad` returned when the load was asked for.
+     * @param loadId - The id its events carry.
      */
-    private sealLoad;
+    private runLoad;
     /**
-     * What the graph HOLDS right now, as the report and the session's own counts both mean it.
+     * Reserve a load's place in line, at the moment the caller asked for it.
      *
-     * Read off the builder rather than off this manager's render maps, and that is the whole
-     * point: an edge endpoint the file never declared as a node is created by the builder, so it
-     * is in the graph and in `session.status.counts.nodes` while having no render `Node` and so no
-     * entry in `nodes`. Counting the render objects made the report say two nodes for a load the
-     * session reported three for -- one load, two numbers, disagreeing, which is the defect this
-     * report exists to end rather than to repeat one level down.
-     * @returns the node and edge counts the graph holds
+     * A caller that reads a file or sniffs a URL before it loads calls this FIRST, so a load that
+     * was asked for later still wins however long the earlier one spends reading. A replacing load
+     * supersedes every load reserved before it.
+     * @param replace - Whether the load will replace the graph
+     * @returns The generation to hand to `addDataFromSource` and `throwIfSuperseded`
      */
-    private heldCounts;
+    beginLoad(replace: boolean): number;
     /**
-     * Refuse to grow past what the renderer can draw, instead of freezing the tab.
-     *
-     * WHY A REFUSAL AND NOT A DEGRADED DRAW. The design says that above the render ceiling the
-     * element draws a smaller render set, and above `edgesDrawn` it hides edges until the view
-     * narrows. Neither exists yet. What exists is a renderer that, past these counts, exhausts
-     * the renderer process and produces no further frame -- measured for issue #405 at 18,000
-     * nodes / 180,000 edges on an RTX 4070 SUPER, where the renderer process reached 4.7 GB and
-     * died while 17,000 / 170,000 loaded in 17 s. Until the degraded draw lands, the honest
-     * behaviour at the ceiling is a coded error the consumer can show, so `DEFAULT_LIMITS` is
-     * the number the element enforces rather than a number it merely publishes.
-     *
-     * `E_TOO_LARGE` is the code because the ceiling is a hard limit of this renderer, and the
-     * caller's remedy is the one that code names: load a subset.
-     * @param of - what is being counted
-     * @param held - how many the graph holds already
-     * @param adding - how many this call would add
-     * @param limit - the most the renderer can draw
-     * @throws A `GraphtyError` with `E_TOO_LARGE` when `held + adding` is past the limit
+     * Abandon every load in flight: each rejects with `E_SUPERSEDED`, its step rolled back, and
+     * adds nothing. The element's `clearData` calls this, so a load finishing after the graph was
+     * closed does not bring its data back.
      */
-    private refuseAboveCeiling;
+    supersedeLoads(): void;
     /**
-     * Clear all data
+     * Throw `E_SUPERSEDED` when a load reserved at `generation` has been overtaken.
+     * @param generation - What `beginLoad` returned for the load
+     * @param type - The load's format, for the message
+     */
+    throwIfSuperseded(generation: number, type: string): void;
+    /**
+     * Remove every node, edge, record and graph-level value, as one undoable step.
      */
     clear(): void;
     /**
@@ -605,9 +672,19 @@ export declare class DataManager implements Manager {
      * Called when layout has settled
      */
     startLabelAnimations(): void;
+    /**
+     * The node and edge counts the graph store holds: what `statistics()` and the stats panel
+     * report, including a pending edge and an endpoint no record declared as a node.
+     * @returns the node and edge counts
+     */
+    heldCounts(): {
+        nodes: number;
+        edges: number;
+    };
     /**
      * Get statistics about the data
-     * @returns Object containing node count, edge count, and cached mesh count
+     * @returns the node and edge counts the graph holds -- the same numbers `statistics()` and the
+     *     stats panel give -- and the cached mesh count
      */
     getStats(): {
         nodeCount: number;

package/dist/src/managers/EventManager.d.ts

@@ -4,6 +4,7 @@ import type { EdgeId, NodeId } from "../catalog/types";
 import type { ImportReport } from "../data/report";
 import type { DataLoadingErrorEvent, EdgeEvent, EventCallbackType, EventType, GraphErrorEvent, GraphEvent, NodeEvent, SelectionChangedEvent } from "../events";
 import type { Graph } from "../Graph";
+import type { HistoryCause } from "../session/types";
 import type { GraphContext } from "./GraphContext";
 import type { Manager } from "./interfaces";
 /**
@@ -72,16 +73,18 @@ export declare class EventManager implements Manager {
      * Emits the removal event naming every node and edge one removal call took away.
      * @param nodes - the nodes that were removed
      * @param edges - every edge that was attached to one of them
+     * @param cause - what removed them, when it came through the history
      */
-    emitElementsRemoved(nodes: NodeId[], edges: EdgeId[]): void;
+    emitElementsRemoved(nodes: NodeId[], edges: EdgeId[], cause?: HistoryCause): void;
     /**
      * Emits a data added event when nodes or edges are added
      * @param dataType - Type of data added (nodes or edges)
      * @param count - Number of items added
      * @param shouldStartLayout - Whether layout should be started
      * @param shouldZoomToFit - Whether to zoom to fit the data
+     * @param cause - what added them, when it came through the history
      */
-    emitDataAdded(dataType: "nodes" | "edges", count: number, shouldStartLayout: boolean, shouldZoomToFit: boolean): void;
+    emitDataAdded(dataType: "nodes" | "edges", count: number, shouldStartLayout: boolean, shouldZoomToFit: boolean, cause?: HistoryCause): void;
     /**
      * Emit `snapshot-replaced` (graph-format design 14.4 rule 11).
      *