@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/session/project/ingest.d.ts

@@ -0,0 +1,364 @@
+/**
+ * @file Ingest: how records become the graph, with no renderer anywhere in reach.
+ *
+ * Id and endpoint extraction, the repeated-edge policy, weight resolution, the direction a file
+ * declares, the import report and the chunked load all live here. What happens to a record once
+ * the graph holds it -- a mesh, a place in the layout engine, an event -- is the host's business,
+ * reached through {@link IngestHost}. `DataManager` is the element's host and keeps only that
+ * render half; a headless session can be another.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM: `test/packaging/node-safe-entries.test.ts`
+ * checks it.
+ */
+import { type DuplicatePolicy } from "@graphty/graph-format";
+import type { EdgeId } from "../../catalog/types";
+import type { ErrorAggregator } from "../../data/ErrorAggregator";
+import type { GraphStore } from "../../data/GraphStore";
+import { type ImportReport } from "../../data/report";
+import type { NodeIdType } from "../../Node";
+import type { Styles } from "../../Styles";
+import { type DataImportCommand, type DataMutation } from "../commands/data";
+import type { GraphWriter } from "./graphOps";
+/**
+ * Whether a value may be used as a graph-format node id.
+ *
+ * graph-format accepts a string or a FINITE number and throws `E_INVALID_ID` for anything else
+ * (`graph-format/src/ids/node-id-map.ts`). The element is looser: a node id is whatever the
+ * configured JMESPath expression returns, which is `null` for a record that does not carry the
+ * key at all, and the element has always let such a record through and rendered it. So the id is
+ * CHECKED here rather than thrown on -- an unusable id leaves the render object exactly as it is
+ * today and keeps it out of the store, which is the one place the id has to be real.
+ * @param id - the extracted id
+ * @returns true when graph-format will accept it
+ */
+export declare function isStorableId(id: unknown): id is string | number;
+/**
+ * Resolve an edge weight: the configured path, then the legacy "value" key, then 1.
+ *
+ * The second probe exists because the conversion this replaced hard-coded a `value` weight key, so
+ * every weighted dataset, fixture and story in this repository carries `value` and nothing carries
+ * `weight`. Reading only the configured path would silently re-read all of them as unweighted.
+ * The probe is removed once nothing ships a `value` key.
+ * @param record - the raw edge record
+ * @param path - `config.data.knownFields.edgeWeightPath`; null means "do not look"
+ * @returns the weight and which probe produced it
+ */
+export declare function resolveEdgeWeight(record: Record<string | number, unknown>, path: string | null): {
+    weight: number;
+    source: "path" | "legacy" | "default";
+};
+/** 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;
+}
+/** An edge the graph already holds, as the host hands it back; the host may carry more. */
+interface KnownEdge {
+    /** The edge's index in the builder. */
+    readonly edgeIndex: number;
+}
+/** One edge record the store has just taken. */
+export interface StoredEdge {
+    /** The raw edge record. */
+    readonly record: Record<string | number, unknown>;
+    /** The source endpoint id, resolved once for the batch. */
+    readonly sourceId: NodeIdType;
+    /** The target endpoint id, resolved once for the batch. */
+    readonly targetId: NodeIdType;
+    /** The edge's index in the builder. */
+    readonly edgeIndex: number;
+    /** The counter the store stamped into this edge's id column. */
+    readonly edgeId: number;
+}
+/**
+ * What ingest needs from whoever draws the graph.
+ *
+ * Every question about an edge the graph already holds comes here because the host is what knows
+ * both halves of it: an edge with a render object and an edge still waiting for its endpoints. A
+ * repeat policy has to be able to reach both -- a `sum` that ignored a waiting edge would lose a
+ * weight, and a `first` that ignored it would create the second edge it exists to prevent.
+ * @template K - the host's own description of an existing edge
+ */
+export interface IngestHost<K extends KnownEdge> {
+    /** The store records are written into; asked each time, because clearing replaces it. */
+    store(): GraphStore;
+    /** The data configuration; asked each time, because the element edits it in place. */
+    dataConfig(): Styles["config"]["data"];
+    /** Whether a node with this id is already held, so a re-supplied node is skipped. */
+    hasNode(id: NodeIdType): boolean;
+    /** How many nodes are held, for the ceiling. */
+    nodeCount(): number;
+    /** Every edge between one ordered pair, oldest first. */
+    edgesBetween(sourceId: NodeIdType, targetId: NodeIdType): readonly K[];
+    /** The edge occupying one store row, or null. */
+    edgeAt(edgeIndex: number): K | null;
+    /** Replace the attributes an existing edge carries (the `last` repeat policy). */
+    replaceEdgeRecord(known: K, record: Record<string | number, unknown>): void;
+    /** A node the store has just taken; `index` is `INVALID_INDEX` for an id it will not hold. */
+    nodeStored(id: NodeIdType, record: Record<string | number, unknown>, index: number): void;
+    /** An edge the store has just taken. */
+    edgeStored(edge: StoredEdge): void;
+    /** Rows have been removed from the store; whatever draws them goes. */
+    rowsRemoved(nodes: readonly NodeIdType[], edges: readonly EdgeId[]): void;
+    /** The graph has been emptied. */
+    cleared(): void;
+    /** A non-empty batch of node records has been ingested. */
+    nodesArrived(count: number): void;
+    /** A non-empty batch of edge records has been ingested. */
+    edgesArrived(count: number): void;
+    /** A chunk of a load has been ingested. */
+    loadProgress(progress: LoadProgress): void;
+    /** A load finished and its source counted errors along the way. */
+    loadErrors(format: string, errors: ErrorAggregator): void;
+    /** A load finished. */
+    loadComplete(format: string, report: ImportReport, progress: LoadProgress, duration: number, errors: number): void;
+    /** A load failed after `progress.chunks` chunks. */
+    loadFailed(format: string, error: Error, progress: LoadProgress): void;
+}
+/** How far a load has got. */
+interface LoadProgress {
+    /** The data source being read. */
+    readonly format: string;
+    /** The file size the caller passed, when it passed one. */
+    readonly fileSize: number | undefined;
+    /** Node RECORDS the source has handed over so far. */
+    readonly nodeRecords: number;
+    /** Edge RECORDS the source has handed over so far. */
+    readonly edgeRecords: number;
+    /** Chunks ingested so far. */
+    readonly chunks: number;
+}
+/**
+ * Turns node and edge records, and whole data sources, into the graph a host holds.
+ *
+ * One per graph. It keeps what outlives a single call: the record identifiers already seen, the
+ * last import report, and -- while a load is in progress -- the load's tally and the endpoint
+ * spelling its first edge chunk settled on.
+ * @template K - the host's own description of an existing edge
+ */
+export declare class Ingest<K extends KnownEdge> {
+    private readonly host;
+    private readonly logger;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    private loadEndpoints;
+    /** The tally the load in progress is counting into, or null outside a load. */
+    private loadTally;
+    /**
+     * Whether a load from a data source is still streaming records in.
+     * @returns true between a load's first chunk and its end
+     */
+    get loading(): boolean;
+    /**
+     * Start with no records seen and no report.
+     * @param host - what draws the graph, and knows which edges it already holds
+     */
+    constructor(host: IngestHost<K>);
+    /** Forget everything about the graph that was: called when the host discards its store. */
+    reset(): void;
+    /**
+     * Carry out one `data.apply` mutation.
+     * @param mutation - The mutation.
+     * @param writer - The command's writer.
+     * @param resolve - The id a row is held under, for an id the caller may have spelled
+     *     differently; the id as given by default.
+     */
+    apply(mutation: DataMutation, writer: GraphWriter, resolve?: (target: "node" | "edge", id: NodeIdType) => NodeIdType): void;
+    /**
+     * Carry out one `data.import`: empty the graph first unless it merges, record where the rows
+     * came from, and load them. A source missing its name or its options is recorded and nothing
+     * is loaded.
+     * @param command - The import.
+     * @param writer - The command's writer.
+     * @param signal - Fires when the import is cancelled; it stops before the next chunk.
+     * @returns Settles once the last chunk is written.
+     */
+    importSource(command: DataImportCommand, writer: GraphWriter, signal?: AbortSignal): Promise<void>;
+    /**
+     * Adds multiple nodes to the graph
+     * @param nodes - Array of node data objects
+     * @param idPath - JMESPath expression to extract node ID from data, or undefined for the
+     *     configured one
+     * @param writer - the graph primitives to write through
+     */
+    addNodes(nodes: readonly Record<string | number, unknown>[], idPath: string | undefined, writer: GraphWriter): void;
+    /**
+     * Add edge records to the graph, resolving their endpoints once for the whole batch.
+     *
+     * THREE THINGS HAPPEN HERE THAT USED TO HAPPEN ELSEWHERE OR NOT AT ALL.
+     *
+     * The endpoint spelling is decided once per batch and reported, rather than read from two
+     * configured paths whose defaults disagreed with every guide the element ships. A batch whose
+     * records answer none of the accepted spellings throws instead of quietly producing a graph
+     * with nodes and no edges.
+     *
+     * A record naming an ordered pair the graph already holds is handed to the repeat policy,
+     * which by default KEEPS it as a second edge. It used to be dropped before the store could
+     * see it, which is why `statistics().repeatedEdgeCount` has always been zero.
+     *
+     * A record whose endpoint ids graph-format will not store is REJECTED and counted, rather than
+     * becoming a render object with no store row -- which is how an edge ended up permanently
+     * visible and unfilterable.
+     * @param edges - Array of edge data objects
+     * @param options - the endpoint expressions and the repeat policy for this call
+     * @param writer - the graph primitives to write through
+     * @throws A `GraphtyError` with `E_EDGE_ENDPOINTS_UNRESOLVED` when no spelling answers, and
+     *     with `E_DUPLICATE_EDGE` under the `"error"` repeat policy.
+     */
+    addEdges(edges: readonly Record<string | number, unknown>[], options: AddEdgesOptions | undefined, writer: GraphWriter): void;
+    /**
+     * Refuse a replacement node set the renderer cannot hold, before the caller removes anything:
+     * the node half of {@link Ingest.refuseReplacement}, counted against an emptied graph.
+     * @param nodes - the nodes the graph should hold afterwards
+     * @param idPath - where a record's id is; the configured node id path when unset
+     * @throws A `GraphtyError` with `E_TOO_LARGE` when the new set is past the ceiling.
+     */
+    refuseNodeReplacement(nodes: readonly Record<string | number, unknown>[], idPath?: string): void;
+    /**
+     * Refuse a replacement edge set the renderer cannot hold, before the caller removes anything.
+     *
+     * Removing first and letting `addEdges` refuse would leave a host that assigned too many edges
+     * with its old edges gone and none of the new ones held, which is neither the graph it had nor
+     * the one it asked for. The new batch is counted against an emptied graph, since the old edges
+     * are what it replaces; a pending edge, whose endpoints have not arrived, survives the replace.
+     * @param edges - the edges the graph should hold afterwards
+     * @param replaced - how many held edges the replacement removes
+     * @param options - the endpoint expressions and the repeat policy for this call
+     * @throws A `GraphtyError` with `E_TOO_LARGE` when the new set is past the ceiling.
+     */
+    refuseReplacement(edges: Record<string | number, unknown>[], replaced: number, 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
+     */
+    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;
+    /**
+     * 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
+     * @param writer - the graph primitives to write through
+     * @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;
+    /**
+     * 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;
+    /**
+     * 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
+     * @param writer - the graph primitives to write through
+     * @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;
+    /**
+     * Loads data from a registered data source
+     * @param type - Data source type identifier
+     * @param opts - Options to pass to the data source
+     * @param writer - the graph primitives to write through
+     * @param signal - Fires when the load is cancelled; it stops at once, even while the source
+     *     is still waiting for its next chunk
+     * @param replacing - Whether the load replaces the graph, so reading only part of the file
+     *     is a failure
+     */
+    addDataFromSource(type: string, opts: object, writer: GraphWriter, signal?: AbortSignal, replacing?: 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
+     * @param writer - the graph primitives to write through
+     * @returns the report
+     */
+    private sealLoad;
+    /**
+     * What the graph HOLDS right now, as the report and the session's own counts both mean it.
+     *
+     * Read off the builder rather than off the host's render objects, 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`. 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
+     */
+    private heldCounts;
+    /**
+     * 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
+     */
+    private refuseAboveCeiling;
+}
+export {};

package/dist/src/session/project/state.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @file Project state: the fixed list of slices that make up a project, and nothing else.
+ *
+ * Everything a project file would save lives in one of the ten slices below, and a change to a
+ * slice is undoable. Anything outside them (camera, hover, selection, a run still computing) is
+ * exempt. See design/undo/undo-design.md section 3.
+ *
+ * The only writer of this state is a `Draft` (`./draft.ts`). The maps are typed read-only here so
+ * that no other module can write them; the draft module holds the mutable handles.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM: the session entry point will reach it.
+ */
+import type { CameraState } from "../../camera/types";
+import type { EdgeId, LayoutId, NodeId, RunId, Scope, SetId } from "../../catalog/types";
+import type { AlgorithmRunCommand } from "../planning";
+import type { RunResult } from "../results/types";
+import type { RunRecord } from "../runs/types";
+import type { HeldCaptures } from "../sets/captures";
+import type { ElementSet } from "../sets/types";
+import type { CompiledLayer } from "../styles/Layer";
+import type { RuleTree, TimeWindow } from "../visibility/filter";
+/** One node or edge record as the graph holds it: the attributes it arrived with. */
+export type GraphRecord = Readonly<Record<string | number, unknown>>;
+/**
+ * The `graph` slice: an op-log. The topology (rows, endpoints, weights and the builder's columns)
+ * lives in the session's `GraphStore`; the slice holds what is keyed by id beside it. Only the
+ * graph primitives (`./graphOps.ts`) write it. See design/undo/undo-design.md section 3.4.
+ */
+export interface GraphSlice {
+    /** Names one exact row order. Never reissued (see {@link Counter}). */
+    readonly token: number;
+    /** Names one dataset's coordinate space. Never reissued. */
+    readonly epoch: number;
+    /** Node records by node id. */
+    readonly nodes: ReadonlyMap<NodeId, GraphRecord>;
+    /** Edge records by the element-assigned edge id. */
+    readonly edges: ReadonlyMap<EdgeId, GraphRecord>;
+    /** Graph-level values by name: the import report, graph-level results. */
+    readonly values: ReadonlyMap<string, unknown>;
+}
+/**
+ * An empty `graph` slice.
+ * @param token - Its graph token.
+ * @param epoch - Its graph epoch.
+ * @returns The slice, frozen; its maps are its own.
+ */
+export declare function emptyGraphSlice(token?: number, epoch?: number): GraphSlice;
+/** The `layout` slice: which layout draws the graph, with what, and in how many dimensions. */
+export interface LayoutChoice {
+    /** The catalogue id. */
+    readonly id: LayoutId;
+    /** The registered engine that draws it; several engines can draw one id. */
+    readonly engine: string;
+    /** The options it was chosen with. */
+    readonly options: Readonly<Record<string, unknown>>;
+    /** The one home of the dimension. */
+    readonly dimension: "2d" | "3d";
+    /**
+     * What the layout runs over, canonical, carried from one choice to the next; absent for the
+     * whole graph. A scope that resolves to nothing leaves the layout over the whole graph.
+     */
+    readonly scope?: Scope;
+}
+/**
+ * The `arrangement` slice: node coordinates at rest, copied out of the positions lane. Immutable
+ * once taken; see `./arrangement.ts`.
+ */
+export interface ArrangementCapture {
+    /** The node ids of the snapshot the coordinates belong to, in row order. */
+    readonly ids: readonly NodeId[];
+    /** The graph token of that snapshot. */
+    readonly token: number;
+    /** The graph epoch the coordinates were taken in. */
+    readonly epoch: number;
+    /** The coordinates, stride 3. */
+    readonly coords: Float32Array;
+}
+/** One finished run, as the `runs` slice keeps it. */
+export interface RunEntry {
+    /** The command that produced it; the dedupe identity is computed from this. */
+    readonly command: AlgorithmRunCommand;
+    /** Its run record. */
+    readonly record: RunRecord;
+    /** Its result, held by reference: a published result is already frozen. */
+    readonly result: RunResult;
+    /**
+     * The token of the execution that produced `result` (design/sets 5.2), minted by a counter no
+     * undo rewinds. Absent for a result published by an executor outside the runs API.
+     */
+    readonly execution?: string;
+    /**
+     * What live references held of earlier executions' items when a re-run replaced them
+     * (design/sets 5.2), so a layer restored by undo paints from them. Absent when none.
+     */
+    readonly held?: HeldCaptures;
+    /** Whether auto-apply has painted it. */
+    readonly painted: boolean;
+    /** Whether its id was derived rather than author-assigned. */
+    readonly derived: boolean;
+    /** Whether the graph changed while it computed. */
+    readonly stale: boolean;
+}
+/** The `visibility` slice. The masks are derived from it, not state. */
+export interface VisibilityState {
+    readonly filter: RuleTree | null;
+    readonly window: TimeWindow | null;
+    readonly showContext: boolean;
+}
+/** The whole project, as readers see it. */
+export interface ProjectState {
+    readonly graph: GraphSlice;
+    /** The pinned node ids. An op-log slice, written by the graph primitives. */
+    readonly pins: ReadonlySet<NodeId>;
+    /** One key per leaf of `ProjectConfig`, by dotted path. */
+    readonly config: ReadonlyMap<string, unknown>;
+    /** Null until a layout is chosen. */
+    readonly layout: LayoutChoice | null;
+    /** The capture the lane was last sealed into or restored from; null until the first. */
+    readonly arrangement: ArrangementCapture | null;
+    readonly runs: ReadonlyMap<RunId, RunEntry>;
+    /** The frozen, compiled layer stack, index 0 the bottom. */
+    readonly styles: readonly CompiledLayer[];
+    readonly visibility: VisibilityState;
+    /** The kept sets, by id: deep-frozen records. */
+    readonly sets: ReadonlyMap<SetId, ElementSet>;
+    /** Saved camera views, by name. */
+    readonly views: ReadonlyMap<string, CameraState>;
+}
+/** A counter that only ever increases, so a value it issued never names two different things. */
+interface Counter {
+    /** @returns A value this counter has never returned before. */
+    next(): number;
+}
+/**
+ * Make a never-reissuing counter.
+ * @returns A counter whose first value is 1.
+ */
+export declare function createCounter(): Counter;
+/**
+ * The state a session starts from: its baseline. History begins after it.
+ * @param init - Slices that start with something other than their empty value.
+ * @returns A fresh state. The slice maps are owned by it; pass copies if you keep yours.
+ */
+export declare function createProjectState(init?: Partial<ProjectState>): ProjectState;
+export {};

package/dist/src/session/project/strict.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @file Strict state: extra checks that project state is only ever changed through the
+ * dispatcher, switched on in the element's own tests and by anyone who wants them.
+ *
+ * The switch is the global `globalThis.__GRAPHTY_STRICT_STATE__ = true`, set before a session is
+ * created. A global rather than an environment variable, because browsers have no `process` and
+ * the published bundle must not touch it. In Node, `GRAPHTY_STRICT_STATE=1` works too; it is
+ * read through `globalThis.process`, so where there is none nothing throws. See
+ * design/undo/undo-design.md section 12.1.
+ */
+import { GraphtyError } from "../../errors/GraphtyError";
+/**
+ * Whether strict state is on. Read once per store, when it is created.
+ * @returns True when the global or, in Node, the environment variable asks for it.
+ */
+export declare function strictStateEnabled(): boolean;
+/**
+ * The error a failed strict check throws: a broken invariant, so a bug in the element.
+ * @param what - What was found, as a sentence fragment.
+ * @returns The error, to throw.
+ */
+export declare function strictViolation(what: string): GraphtyError;
+/**
+ * Strict: an op-log key (a node or edge id, or a whole `graph` or `pins` slice) being acquired by
+ * one open group must not already be held by another, because an op-log cannot hand a key over.
+ * @param key - The key being acquired.
+ * @param holder - The label of the other open group holding it, or null when none does.
+ */
+export declare function checkSoleHolder(key: string, holder: string | null): void;
+/**
+ * Strict: a command dispatched inline through a group-tagged facade touches only keys that are
+ * free or held by its own group (design section 4.5).
+ * @param op - The inline command's op.
+ * @param key - The op-log key another group holds.
+ * @param holder - The label of that group.
+ */
+export declare function checkInlineKey(op: string, key: string, holder: string): void;
+/**
+ * Strict: note a typed array state has just come to keep. Typed arrays cannot be frozen, so its
+ * bytes are summed now, and a later check that finds them changed names what holds it. Nothing
+ * happens when strict state is off, or for an array already noted.
+ * @param array - The array.
+ * @param what - What holds it, as a noun phrase naming the slice.
+ * @param holder - The object whose state keeps it (a store, an arrangement), whose dispatcher
+ *     checks it at each dispatch; absent, every dispatch checks it.
+ */
+export declare function retainArray(array: ArrayBufferView, what: string, holder?: object): void;
+/**
+ * Strict: check the retained arrays still alive: the ones the given holders' state keeps, as each
+ * dispatch does, or every one, as the test setup does after each test.
+ * @param holders - The holders whose arrays to check, beside the shared ones; every array when
+ *     absent.
+ */
+export declare function verifyRetainedArrays(holders?: readonly (object | null)[]): void;
+/**
+ * Strict: the graph store's builder was changed by something other than the graph primitives.
+ * @param count - How many mutations nobody accounted for.
+ * @returns The error, to throw.
+ */
+export declare function builderDrift(count: number): GraphtyError;
+/**
+ * Hand an error the element caught and carried on past -- the render loop's catch, a lane hook
+ * that reports and goes on -- to whoever is watching: the element's own tests install
+ * `globalThis.__GRAPHTY_CAUGHT__` and fail the test it happened in. Nothing is installed in
+ * production, so this does nothing there.
+ * @param error - What was caught.
+ */
+export declare function reportCaught(error: unknown): void;

package/dist/src/session/results/RunResult.d.ts

@@ -85,6 +85,26 @@ export interface RunResultInit {
     /** The plain-language generator, when one is installed. */
     readonly reading?: ResultReadingGenerator;
 }
+/**
+ * Where each element of one half sits: position to id, and id to position. A graph-format node id
+ * map is one, which is what lets a result share the snapshot's instead of building its own.
+ */
+interface ResultIdIndex {
+    /** How many elements it holds. */
+    readonly size: number;
+    /**
+     * The id at a position.
+     * @param position - The position, from 0 to `size - 1`.
+     * @returns The id.
+     */
+    idOf(position: number): NodeId;
+    /**
+     * The position of an id, by SameValueZero.
+     * @param id - The id.
+     * @returns The position, or a number outside `[0, size)` when it holds no such id.
+     */
+    indexOf(id: NodeId): number;
+}
 /**
  * Build the result a run publishes.
  *
@@ -97,4 +117,32 @@ export interface RunResultInit {
  * @returns The result, immutable.
  */
 export declare function createRunResult(init: RunResultInit): RunResult;
+/** One id index a result reads through, as the undo history charges for it. */
+interface RetainedIndex {
+    /** The index object: charged once however many results share it. */
+    readonly index: object;
+    /** The graph token of the snapshot it belongs to, or null when the result owns it. */
+    readonly token: number | null;
+    /** What it costs, estimated. */
+    readonly bytes: number;
+}
+/**
+ * What a result retains: its columns and caches, and the id indexes it reads through. The
+ * indexes are apart because whether one costs anything depends on what else is alive: one shared
+ * with the resident snapshot costs nothing extra (design/undo/undo-design.md section 7).
+ * @param result - The result; one this module did not build retains nothing it can see.
+ * @returns The bytes and the indexes.
+ */
+export declare function retentionOf(result: RunResult): {
+    readonly bytes: number;
+    readonly indexes: readonly RetainedIndex[];
+};
+/**
+ * Let a result read its nodes through a snapshot's id index, dropping its own, when the two hold
+ * the same ids in the same order. Nothing observable changes.
+ * @param result - The result.
+ * @param index - The snapshot's node id index.
+ * @param token - The graph token of that snapshot.
+ */
+export declare function shareNodeIndex(result: RunResult, index: ResultIdIndex, token: number): void;
 export {};

package/dist/src/session/results/statistics.d.ts

@@ -182,6 +182,26 @@ export interface RankableEntry {
  * @returns The ranking, best first. Entries with no finite value are left out.
  */
 export declare function rankEntries(entries: readonly RankableEntry[]): readonly RankingEntry[];
+/**
+ * The order {@link rankEntries} ranks in, as positions: best first, ties in printed-id order,
+ * elements with no finite value left out. Four bytes per ranked element, so a result can keep one
+ * per field instead of an object per element.
+ * @param length - How many positions there are.
+ * @param valueAt - The value at a position.
+ * @param idAt - The id at a position.
+ * @returns The ranked positions, best first.
+ */
+export declare function rankOrder(length: number, valueAt: (position: number) => number, idAt: (position: number) => NodeId): Uint32Array;
+/**
+ * The first entries of a ranking, built from its order. Ties share a rank: the next distinct
+ * value takes the rank its place implies, so ranks run 1, 2, 2, 4.
+ * @param order - The ranked positions, from {@link rankOrder}.
+ * @param count - How many entries to build, at most `order.length`.
+ * @param valueAt - The value at a position.
+ * @param idAt - The id at a position.
+ * @returns The entries, best first, frozen.
+ */
+export declare function rankedPrefix(order: Uint32Array, count: number, valueAt: (position: number) => number, idAt: (position: number) => NodeId): readonly RankingEntry[];
 /**
  * The top `n` of a ranking, cut only between tie groups. See {@link TopRanking} for the policy.
  * @param ranking - The ranking, best first, with tied entries sharing a rank.