@graphty/graphty-element 2.5.2 → 2.6.0

package/dist/src/session/runs/RunsApi.d.ts

@@ -18,10 +18,12 @@
  * structural view of `OperationQueueManager` narrow enough that the session never imports the
  * renderer's manager to talk to it.
  */
-import { type AlgorithmDescriptor, type LayerId, type RunId, type Scope } from "../../catalog/types";
+import { type AlgorithmDescriptor, type LayerId, type RunId, type Scope, type ScopeInput, type SetId } from "../../catalog/types";
+import type { HeldCaptures } from "../sets/captures";
 import type { AutoApplyPolicy } from "../styles/autoApply";
 import { type RunExecutor, type RunQueueContext } from "./Run";
-import { type Caveats, type EngineVersions, type ResolvedScope, type RunChange, type RunsApi } from "./types";
+import { type LiveKeyword } from "./runId";
+import { type Caveats, type EngineVersions, type ResolvedScope, type RunChange, type RunsApi, type RunScopeFacts } from "./types";
 /**
  * The element's operation queue, as a run needs it.
  *
@@ -104,12 +106,40 @@ export interface RunsApiOptions {
      * @returns What it resolves to now.
      */
     readonly resolveScope: (spec: Scope) => ResolvedScope;
+    /**
+     * What a run records about the set a scope names: its revision and its edge reading. Absent
+     * records neither.
+     * @param spec - The scope.
+     * @returns The facts.
+     */
+    readonly scopeFacts?: (spec: Scope) => RunScopeFacts;
+    /**
+     * The name of a kept set, for a run label.
+     * @param id - The set.
+     * @returns The name, or undefined when no set has the id.
+     */
+    readonly setName?: (id: SetId) => string | undefined;
     /** The thing that actually runs an algorithm. */
     readonly execute: RunExecutor;
     /** Which versions are producing the numbers. */
     readonly engine: EngineVersions;
     /** What a call that names no scope gets. Defaults to the visible graph. */
     readonly defaultScope?: Scope;
+    /**
+     * A write door's check of the scope a call names: session edge ids to stable members, set ids
+     * checked as issued. Absent, the scope is taken as given.
+     * @param spec - The scope as given.
+     * @returns The scope to record.
+     */
+    readonly admitScope?: (spec: ScopeInput) => Scope;
+    /**
+     * The definition a live scope keyword stands for now, which a derived run id hashes in its
+     * place: the visibility filter and window for `"visible"`, the selected nodes for
+     * `"selection"`. Absent, the keyword itself is hashed.
+     * @param keyword - The keyword.
+     * @returns Plain data that changes exactly when the keyword's definition does.
+     */
+    readonly liveScope?: (keyword: LiveKeyword) => unknown;
     /** The caveats a run starts from, before the work refines them. */
     readonly defaultCaveats?: Caveats;
     /** The style layers that read runs, once there are any. */
@@ -133,6 +163,18 @@ export interface RunsApiOptions {
      * @param change - The run's record, and which moment it reached.
      */
     readonly onChange?: (change: RunChange) => void;
+    /** Called once per execution token minted, which is what advances the session input tick. */
+    readonly onExecution?: () => void;
+    /** Called when a run is removed, and with it its result (design/sets 11). */
+    readonly onRemoved?: (id: RunId) => void;
+    /**
+     * Capture what live references hold of a run's result before a re-run replaces it
+     * (design/sets 5.2). Absent: nothing is captured.
+     * @param run - The run about to re-execute in place, its result still in place.
+     * @param prior - The captures it keeps now.
+     * @returns The captures it keeps from now on.
+     */
+    readonly captureHeld?: (run: RunId, prior: HeldCaptures) => HeldCaptures;
 }
 /** The runs API, plus the two things a session needs and a consumer never calls. */
 export interface SessionRunsApi extends RunsApi {
@@ -147,9 +189,23 @@ export interface SessionRunsApi extends RunsApi {
      * @returns True when the element derived the id.
      */
     isDerivedId(id: RunId): boolean;
+    /**
+     * What a run keeps of earlier executions' items that live references hold (design/sets 5.2).
+     * @param id - The run id.
+     * @returns The captures; empty for a run this session does not hold.
+     */
+    heldOf(id: RunId): HeldCaptures;
     /** Cancel everything still running and forget every run this session held. */
     dispose(): void;
 }
+/**
+ * Build one session's execution-token minter: a nonce drawn once, then a counter shared by every
+ * run the session holds, never a per-run count. `startedAt` was rejected as an identity because
+ * two executions in one millisecond compare equal.
+ * @param onMint - called after every mint
+ * @returns the minter; each call returns `<nonce>.<counter>`, opaque to every reader
+ */
+export declare function createExecutionMinter(onMint?: () => void): () => string;
 /**
  * Build the runs API over an existing operation queue.
  * @param options - The queue, the catalogue, the scope resolver and the thing that does the work.

package/dist/src/session/runs/runId.d.ts

@@ -1,11 +1,19 @@
 /**
  * @file Run identity: what makes two calls the same run, and what makes them different ones.
  *
- * A run id is not a slot number. It is either author-assigned through `as:` or derived from what
- * the run IS -- the algorithm key, the parameters once canonicalised, and the scope that was
- * asked for. An id minted from an execution counter would mean a saved style layer, recipe or
- * template resolves to a different run depending on the order things happened to execute, and
- * changing that afterwards is a behavioural break in everything already persisted.
+ * A run id is not a slot number. It is either author-assigned through `as:` or derived from the
+ * RESULT the run answers -- the algorithm key, whether it is exact or sampled, and the scope it
+ * reads with the live keywords frozen. An id minted from an execution counter would mean a saved
+ * style layer, recipe or template resolves to a different run depending on the order things
+ * happened to execute, and changing that afterwards is a behavioural break in everything already
+ * persisted.
+ *
+ * The derived id is the RESULT's id ({@link ResultId}): parameters and the seed are not part of
+ * it, so tuning a resolution or a damping factor re-runs the same result and every layer bound to
+ * it repaints, instead of growing a second result and a second layer. The keywords `"visible"` and
+ * `"selection"` are replaced by the definition in force before hashing -- the visibility filter
+ * and time window, the selected nodes -- so the same unscoped call under a different filter is a
+ * different result, never a re-execution of the first one over a different graph.
  *
  * Two rules do the work here:
  *
@@ -19,7 +27,7 @@
  *
  * Nothing here reaches Babylon.js, Lit or the DOM: it is string arithmetic over plain data.
  */
-import type { AlgorithmKey, EdgeId, NodeId, OptionDescriptor, RunId, Scope } from "../../catalog/types";
+import type { AlgorithmKey, EdgeId, NodeId, OptionDescriptor, ResultId, RunId, Scope } from "../../catalog/types";
 /**
  * A short, stable digest of a string, made of characters a run id may carry.
  *
@@ -103,6 +111,47 @@ export declare function canonicalIdentity(identity: RunIdentity): string;
  * @returns The id, which always matches the run-id pattern.
  */
 export declare function deriveRunId(identity: RunIdentity): RunId;
+/** The live scope keywords, whose members change without the scope's spelling changing. */
+export type LiveKeyword = "visible" | "selection";
+/**
+ * A scope with every live keyword replaced by the definition in force, for hashing only: the
+ * scope itself, and the `of` of every `member` leaf inside an inline definition.
+ * @param scope - The scope a run was asked for.
+ * @param live - The definition each live keyword stands for now.
+ * @returns The frozen scope, plain data.
+ */
+export declare function freezeScope(scope: Scope, live: (keyword: LiveKeyword) => unknown): unknown;
+/**
+ * The selected nodes as a frozen scope names them: sorted, so the same selection made in another
+ * order is the same result.
+ * @param nodes - The selected node ids.
+ * @returns The ids, sorted.
+ */
+export declare function frozenSelection(nodes: Iterable<NodeId>): NodeId[];
+/** What names a result: everything that makes two calls one result, and nothing a re-run may tune. */
+export interface ResultIdentity {
+    /** Which algorithm ran. */
+    readonly algorithm: AlgorithmKey;
+    /** The scope, frozen by {@link freezeScope}. */
+    readonly scope: unknown;
+    /** The sample size that was asked for, or null: a sampled result is never an exact one. */
+    readonly sample: number | null;
+    /** Whether approximation was refused, or null when the caller did not say. */
+    readonly exact: boolean | null;
+}
+/**
+ * The id a result gets when its author did not name it: derived from what the result IS, never
+ * from its parameters, its seed or when it ran.
+ * @param identity - What the result is.
+ * @returns The id, which always matches the run-id pattern.
+ */
+export declare function deriveResultId(identity: ResultIdentity): ResultId;
+/**
+ * The canonical text of a result identity, which is what two runs under one id are compared by.
+ * @param identity - The identity.
+ * @returns Its canonical text.
+ */
+export declare function canonicalResultIdentity(identity: ResultIdentity): string;
 /**
  * Check an author-assigned id against the pattern every run id keeps.
  *

package/dist/src/session/runs/types.d.ts

@@ -15,7 +15,7 @@
  * lands, rather than being stubbed with a placeholder type: `command`, the journalled command a
  * run was started from, which arrives with the command union.
  */
-import type { AlgorithmKey, EdgeId, FieldDescriptor, LayerId, NodeId, ResultShape, RunId, Scope } from "../../catalog/types";
+import type { AlgorithmKey, EdgeId, EdgeReading, FieldDescriptor, LayerId, NodeId, ResultShape, RunId, Scope, ScopeInput, SetId } from "../../catalog/types";
 import type { GraphtyError } from "../../errors/GraphtyError";
 import type { ResultSummary, RunResult } from "../results/types";
 import type { StyleSuggestion } from "../styles/derive";
@@ -190,15 +190,19 @@ export interface Caveats {
  * meantime.
  */
 export interface ResolvedScope {
-    /** The nodes in scope. */
+    /** The nodes in scope. Lazy: built on the first read, then the same set on every read. */
     readonly nodes: ReadonlySet<NodeId>;
-    /** The edges in scope. */
+    /** The edges in scope. Lazy: built on the first read, then the same set on every read. */
     readonly edges: ReadonlySet<EdgeId>;
     /** How many nodes are in scope. */
     readonly nodeCount: number;
     /** How many edges are in scope. */
     readonly edgeCount: number;
-    /** Equal digests mean equal scopes, which is how staleness is derived rather than tracked. */
+    /**
+     * Equal digests mean equal scopes, which is how staleness is derived rather than tracked.
+     * Versioned: `d1:` and 16 hex digits, comparable only within one session and store. Computed
+     * on first read.
+     */
     readonly digest: string;
     /** What was asked for, before it was resolved. */
     readonly spec: Scope;
@@ -215,7 +219,21 @@ export interface RunScopeRecord {
     readonly edges: number;
     /** The digest the staleness comparison reads. */
     readonly digest: string;
+    /**
+     * The kept set a `{ set }` scope named, and its revision when the run resolved it, so a reader
+     * can tell whether the set has been redefined since. Absent for every other scope.
+     */
+    readonly set?: {
+        /** The kept set's id. */
+        readonly id: SetId;
+        /** The set's revision when the run resolved it. */
+        readonly revision: string;
+    };
+    /** Which edges came with the scope's nodes. OPEN UNION, as {@link EdgeReading}. */
+    readonly reading?: EdgeReading;
 }
+/** What a run records about the set its scope named, beside the resolution. */
+export type RunScopeFacts = Pick<RunScopeRecord, "set" | "reading">;
 /** Which versions of which packages produced a result. */
 export interface EngineVersions {
     /** The graphty-element version. */
@@ -271,8 +289,11 @@ export interface RunOptions {
  * saved document that referenced one would resolve differently against a different session.
  */
 export interface StartOptions extends RunOptions {
-    /** What the run may look at. Defaults to the visible graph. */
-    readonly scope?: Scope;
+    /**
+     * What the run may look at. Defaults to the visible graph. An inline `{ define }` may name
+     * edges by session edge id; the run records their stable form.
+     */
+    readonly scope?: ScopeInput;
     /** The seed for a randomised or sampled method, so a run can be reproduced. */
     readonly seed?: number;
     /**
@@ -319,8 +340,8 @@ export interface RunSpec {
     readonly algorithm: AlgorithmKey;
     /** Its parameters. */
     readonly params?: Readonly<Record<string, unknown>>;
-    /** What it may look at. */
-    readonly scope?: Scope;
+    /** What it may look at, as {@link StartOptions.scope}. */
+    readonly scope?: ScopeInput;
     /** The seed for a randomised or sampled method. */
     readonly seed?: number;
     /** The id to give the run. */
@@ -546,10 +567,17 @@ export interface RunRemoval {
 export interface RunsApi {
     /**
      * Start one algorithm.
+     *
+     * The scope is resolved when the call is made, and again when the work starts: a set it names
+     * that is redefined while the run waits in the queue is run over as redefined, and the run
+     * records the revision it used (`record.scope.set.revision`).
      * @param algorithm - Which algorithm to run.
      * @param params - Its parameters.
      * @param options - The scope, the seed, the id and the rest.
      * @returns The run, which is awaitable and watchable straight away.
+     * @throws `E_SCOPE_EMPTY` when a scope other than `"graph"` or `"visible"` holds no nodes (a
+     * run that finds it empty only when its work starts fails with the same code);
+     * `E_BAD_COMMAND` for a malformed scope or a set id never issued.
      */
     start(algorithm: AlgorithmKey, params?: Readonly<Record<string, unknown>>, options?: StartOptions): Run;
     /**

package/dist/src/session/scope/ElementMask.d.ts

@@ -77,6 +77,8 @@ export declare class ElementMask<TId> {
     private members;
     /** Bumped whenever a mutation actually changed the membership. */
     private revision;
+    /** Told of every version bump. */
+    private readonly onVersion;
     /** The last id array handed out, or null before the first materialisation. */
     private cachedIds;
     /** The revision `cachedIds` was materialised at. */
@@ -90,9 +92,13 @@ export declare class ElementMask<TId> {
      *     builds a fresh object per call costs a re-materialisation per read. It never costs
      *     correctness -- the contents are compared before a new array is handed out.
      * @param capacity - Rows to reserve before the first growth; a non-negative integer.
+     * @param onVersion - Called on every version bump; a session mask passes its input tick's
+     *     advance here, so the tick moves whenever the mask does (design/sets 6.2).
      * @throws A `RangeError` when `capacity` is not a non-negative integer.
      */
-    constructor(readSpace: () => MaskIdSpace<TId>, capacity?: number);
+    constructor(readSpace: () => MaskIdSpace<TId>, capacity?: number, onVersion?: () => void);
+    /** Move the version on, and tell whoever asked to be told. */
+    private bump;
     /**
      * Rows the backing array can hold without reallocating.
      * @returns The current capacity in rows.
@@ -229,6 +235,13 @@ export declare class ElementMask<TId> {
      * @returns A fresh `Uint8Array` of length {@link ElementMask.count}.
      */
     bytes(): U8;
+    /**
+     * The membership as a packed bitmap in graph-format's mask layout (ceil(length / 32) words,
+     * LSB-first): one pass of byte reads. A row at or past the live count is not a member.
+     * @param length - How many indices the bitmap covers, normally the snapshot's element count.
+     * @returns A fresh bitmap.
+     */
+    pack(length: number): U32;
     /**
      * The ids in the set, materialised lazily and handed back frozen.
      *

package/dist/src/session/scope/ScopeApi.d.ts

@@ -24,21 +24,18 @@
  * Nothing here reaches Babylon.js, Lit or the DOM.
  */
 import { type GraphSnapshot } from "@graphty/graph-format";
-import type { EdgeId, NodeId, Query, Scope, ScopeId } from "../../catalog/types";
+import type { EdgeId, EdgeMember, EdgeReading, NodeId, Path, Query, ResultItem, RunId, Scope, ScopeId, ScopeInput } from "../../catalog/types";
+import type { AttributeRevisions, InputTick } from "../attributes";
 import type { ResolvedScope } from "../runs/types";
-import { ElementMask, type MaskIdSpace } from "./ElementMask";
+import { SetsCache } from "../sets/cache";
+import { type Capture } from "../sets/captures";
+import { type ComponentLabels, type Resolution, type ResolveContext } from "../sets/resolve";
+import type { SetsApi } from "../sets/types";
+import type { FilterSources, FilterValueSource, ScopeLeaf } from "../visibility/filter";
+import type { ElementMask, MaskIdSpace } from "./ElementMask";
+export type { ComponentLabels } from "../sets/resolve";
 /** How many edges {@link ScopeApi.count} looks at when it is allowed to answer approximately. */
 export declare const DEFAULT_SCOPE_SAMPLE = 10000;
-/**
- * The digest a resolved scope carries: equal digests mean the same elements.
- *
- * Two 32-bit lanes rather than one, because a single 32-bit digest starts colliding at a few
- * tens of thousands of distinct scopes, and a collision here reports a stale run as fresh.
- * @param nodes - The node ids in the scope, in any order.
- * @param edges - The edge ids in the scope, in any order.
- * @returns The digest: sixteen lower-case hexadecimal characters.
- */
-export declare function membershipDigest(nodes: readonly NodeId[], edges: readonly EdgeId[]): string;
 /**
  * One snapshot's node identity space, for a mask over its nodes.
  * @param snapshot - The snapshot to read.
@@ -83,13 +80,6 @@ export interface ScopeSelectionSource {
      */
     nodes(): ElementMask<NodeId>;
 }
-/** Which connected component each node belongs to. */
-export interface ComponentLabels {
-    /** One component number per dense node index. */
-    readonly labels: ArrayLike<number>;
-    /** How many components there are, so the labels are `[0, count)`. */
-    readonly count: number;
-}
 /**
  * Where the resolver reads everything it does not compute itself.
  *
@@ -104,6 +94,8 @@ export interface ScopeSources {
      * @returns The current snapshot.
      */
     snapshot(): GraphSnapshot;
+    /** The store instance every resolution is tagged with. Absent tags them with null. */
+    readonly store?: object;
     /** What is visible. Absent means nothing hides anything, so `visible` is the whole graph. */
     readonly visibility?: ScopeVisibilitySource;
     /** What is selected. Absent refuses the `selection` scope. */
@@ -122,6 +114,57 @@ export interface ScopeSources {
      * @returns The matching node ids; ones the graph no longer holds are ignored.
      */
     readonly match?: (where: Query) => Iterable<NodeId>;
+    /**
+     * The paths a predicate's compiled expression reads. With {@link revisions} and
+     * {@link executionOf}, what lets a `{ where }` answer be cached: absent, it is resolved on
+     * every read.
+     * @param where - The predicate.
+     * @returns The paths.
+     */
+    readonly pathsOf?: (where: Query) => readonly Path[];
+    /** The node attribute revisions a predicate's cached answer is keyed on. */
+    readonly revisions?: AttributeRevisions;
+    /** The edge attribute revisions a rule's `edges` leaf is keyed on. */
+    readonly edgeRevisions?: AttributeRevisions;
+    /**
+     * The execution token of a run's current result, which a predicate over its results is keyed
+     * on.
+     * @param run - The run.
+     * @returns The token, or undefined when the run has no result.
+     */
+    readonly executionOf?: (run: RunId) => string | undefined;
+    /** The session input tick; saving or removing a scope advances it. */
+    readonly tick?: InputTick;
+    /** The resolution cache. A private one when absent. */
+    readonly cache?: SetsCache;
+    /** The kept sets `{ set }` and a rule's `member` leaf may name, beside the saved scopes. */
+    readonly sets?: SetsApi;
+    /** The edges a predicate matches. Absent refuses a rule's `edges` leaf. */
+    readonly matchEdges?: (where: Query) => Iterable<EdgeId>;
+    /** Attribute values. Absent refuses a rule's `range` and `categories` leaves. */
+    readonly values?: FilterValueSource;
+    /** A run's current result. Absent refuses a rule's `item` leaf and a `threshold` over `results.*`. */
+    readonly result?: FilterSources["result"];
+    /**
+     * What a held item's re-run captured (design/sets 5.2). Absent: nothing was captured.
+     * @param item - The item, with its execution.
+     * @returns The capture, or undefined.
+     */
+    readonly captured?: (item: ResultItem) => Capture | undefined;
+    /**
+     * A session edge's stable identity, so an inline `{ define }` may name edges by session id.
+     * Absent refuses a session edge id inside `{ define }`.
+     * @param id - The session edge id.
+     * @returns The member, or undefined when the graph holds no such edge.
+     */
+    readonly edgeMember?: (id: EdgeId) => EdgeMember | undefined;
+    /**
+     * Which halves carry a value path, so an `induced` rule over an edge field resolves to nothing
+     * as its status says. Absent: such a leaf is not known to speak edges.
+     * @param path - The path.
+     * @returns `"node"`, `"edge"`, or both.
+     */
+    readonly fieldKinds?: (path: Path) => readonly string[];
 }
 /** One scope somebody saved under a name. */
 export interface SavedScope {
@@ -148,6 +191,10 @@ export interface ScopeCount {
     readonly exact: boolean;
     /** How many edges were looked at, when the answer was estimated from a sample. */
     readonly sampled?: number;
+    /** For a kept fixed or path set: the node ids it names that the graph does not hold. */
+    readonly missingNodes?: number;
+    /** For a kept fixed or path set: the edge members (a path's steps) no edge of the graph matches. */
+    readonly missingEdges?: number;
 }
 /** What {@link ScopeApi.count} accepts. */
 export interface ScopeCountOptions {
@@ -163,29 +210,36 @@ export interface ScopeApi {
      * @param spec - What to resolve.
      * @returns The resolved scope.
      */
-    resolve(spec: Scope): Promise<ResolvedScope>;
+    resolve(spec: ScopeInput): Promise<ResolvedScope>;
     /**
      * How many elements a specification covers, without materialising them.
      * @param spec - What to count.
      * @param options - Whether an estimate is acceptable, and how big a sample to take.
      * @returns The counts, saying whether the edge count was exact.
      */
-    count(spec: Scope, options?: ScopeCountOptions): Promise<ScopeCount>;
+    count(spec: ScopeInput, options?: ScopeCountOptions): Promise<ScopeCount>;
     /**
      * Keep a specification under a name, so `{ set: id }` can name it later.
-     * @param name - The name, unique within the session.
+     *
+     * It is kept as a set, created from `user`: `{ where }` as a rule, `{ nodes }` as a fixed
+     * set, `{ define }` as its definition, `"graph"`, `"largest-component"` and `{ set }` as a
+     * rule naming them. `"selection"` and `"visible"` are kept as their current members.
+     * @deprecated Use {@link SetsApi.create | session.sets.create}, which takes a definition.
+     * @param name - The name, unique among kept sets.
      * @param spec - The specification to keep.
-     * @returns The minted id.
+     * @returns The minted id, never one issued before.
      */
     save(name: string, spec: Scope): ScopeId;
     /**
-     * Every saved scope, with whether it still refers to anything.
-     * @returns The saved scopes, in the order they were saved.
+     * Every kept set, as the specification it holds and whether it still refers to anything.
+     * @deprecated Use {@link SetsApi.list | session.sets.list}, which returns the definitions.
+     * @returns The kept sets, in the order they were created.
      */
     list(): readonly SavedScope[];
     /**
-     * Forget a saved scope. Anything that named it becomes unbound rather than silently empty.
-     * @param id - The id to forget.
+     * Remove a kept set. Anything that named it becomes unbound rather than silently empty.
+     * @deprecated Use {@link SetsApi.remove | session.sets.remove}.
+     * @param id - The id to remove.
      */
     remove(id: ScopeId): void;
 }
@@ -197,20 +251,95 @@ export interface ScopeApi {
  * the synchronous answer, and everything under here is synchronous anyway.
  */
 export interface ScopeResolver extends ScopeApi {
+    /**
+     * A write position's scope in canonical form: session edge ids inside `{ define }` replaced by
+     * their stable members, the definition validated.
+     * @param spec - The scope as given.
+     * @returns The canonical scope.
+     * @throws `E_BAD_COMMAND` when it is not a scope.
+     */
+    canonical(spec: ScopeInput): Scope;
+    /**
+     * What a write door stores, before it validates it: session edge ids inside any nested inline
+     * definition replaced by their stable members, and every `{ set }` it names checked as issued
+     * in this session (a removed set's id is accepted and reads as detached).
+     * @param value - A scope, a rule tree or a set definition, as given.
+     * @returns The value, stable; the same object when it held no session edge id.
+     * @throws `E_BAD_COMMAND` for a session edge id the graph lacks, or a set id never issued.
+     */
+    admit<T>(value: T): T;
     /**
      * The elements a specification covers, answered without a promise.
      * @param spec - What to resolve.
      * @returns The resolved scope.
      */
     resolveNow(spec: Scope): ResolvedScope;
+    /**
+     * The node ids a specification covers, read from its node bitmap: no id `Set` is built.
+     * @param spec - What to resolve.
+     * @returns The ids, in dense index order.
+     */
+    nodeIdsOf(spec: Scope): readonly NodeId[];
+    /**
+     * What a rule's `member` leaf speaks, for a pass: never throws, and a reference that cannot be
+     * resolved (a cycle, a missing set) speaks nothing.
+     * @param spec - The referenced set.
+     * @returns The leaf.
+     */
+    leafOf(spec: Scope): ScopeLeaf;
+    /**
+     * A specification's bitmaps, through the resolution cache, with the snapshot they cover.
+     * @param spec - What to resolve.
+     * @returns The resolution and its snapshot.
+     */
+    resolutionOf(spec: Scope): {
+        readonly resolution: Resolution;
+        readonly graph: GraphSnapshot;
+    };
+    /**
+     * How a specification reads, following a `{ set }` to its definition.
+     * @param spec - The specification.
+     * @returns The reading.
+     */
+    readingOf(spec: Scope): EdgeReading;
+    /** The kept sets `save`, `list` and `remove` delegate to. */
+    readonly sets: SetsApi;
+    /**
+     * What a resolution reads now, for an internal reader that resolves through the cache itself.
+     * @returns The context over the current snapshot.
+     */
+    contextNow(): ResolveContext;
 }
+/** A resolution and the snapshot it covers. */
+interface Membership {
+    readonly resolution: Resolution;
+    readonly graph: GraphSnapshot;
+}
+/** What stands behind a resolved scope: its bitmaps, and how to resolve the same spec again now. */
+interface ScopeBehind extends Membership {
+    /** How the scope reads its edges. */
+    readonly reading: EdgeReading;
+    /**
+     * The same specification resolved against the graph as it stands now.
+     * @returns The resolution and its snapshot.
+     */
+    now(): Membership;
+}
+/**
+ * The bitmaps behind a resolved scope, and the snapshot they cover. Internal: a run hands its
+ * algorithm these rather than the id sets.
+ * @param scope - A resolved scope.
+ * @returns What stands behind it, or undefined for a scope no resolver dressed.
+ */
+export declare function resolutionBehind(scope: ResolvedScope): ScopeBehind | undefined;
 /**
  * Build the scope resolver one session uses.
  *
- * Membership is walked once per specification and cached against the inputs it was walked from
- * -- the snapshot, the visibility and selection masks, and the saved list -- because the reader
- * that asks most often is the staleness check on a finished run, and that is read by every
- * progress event. Nothing is cached across a change to any of those.
+ * Each specification is resolved through the session's resolution cache
+ * (`session/sets/cache.ts`), keyed by its input signature: exactly the inputs it reads -- the
+ * snapshot, a mask version, a saved scope's record, the attribute revisions and run results a
+ * predicate reads. The reader that asks most often is the staleness check on a finished run, and
+ * the digest is memoised on the resolution, so a staleness read over unchanged inputs sums nothing.
  * @param sources - Where to read the graph and the capabilities a narrowing scope needs.
  * @returns The resolver.
  */

package/dist/src/session/scope/index.d.ts

@@ -11,4 +11,4 @@
  * Nothing in this module's import graph reaches Babylon.js, Lit or the DOM.
  */
 export { DEFAULT_MASK_CAPACITY, ElementMask, type MaskIdSpace } from "./ElementMask";
-export { type ComponentLabels, createScopeApi, DEFAULT_SCOPE_SAMPLE, edgeSpaceOf, membershipDigest, nodeSpaceOf, type SavedScope, type ScopeApi, type ScopeCount, type ScopeCountOptions, type ScopeResolver, type ScopeSelectionSource, type ScopeSources, type ScopeVisibilitySource, } from "./ScopeApi";
+export { type ComponentLabels, createScopeApi, DEFAULT_SCOPE_SAMPLE, edgeSpaceOf, nodeSpaceOf, type SavedScope, type ScopeApi, type ScopeCount, type ScopeCountOptions, type ScopeResolver, type ScopeSelectionSource, type ScopeSources, type ScopeVisibilitySource, } from "./ScopeApi";

package/dist/src/session/selection/SelectionApi.d.ts

@@ -40,10 +40,10 @@ import { type SessionRecordSource } from "../types";
 import { type SelectionMatch, type SelectionSearchHit, type SelectionTarget, type SelectionTextMode } from "./targets";
 /** The most elements one selection holds before it is truncated, when nothing says otherwise. */
 export declare const DEFAULT_SELECTION_CAP = 5000;
-/** What a mutation does with the elements a target named. */
-export type SetOp = "replace" | "add" | "remove" | "toggle" | "intersect";
+/** What a selection change does with the elements a target named. */
+export type SelectionOp = "replace" | "add" | "remove" | "toggle" | "intersect";
 /** Every set operation, for a caller that wants to check one before passing it on. */
-export declare const SET_OPS: readonly SetOp[];
+export declare const SET_OPS: readonly SelectionOp[];
 /**
  * Who asked for a selection change.
  *
@@ -181,20 +181,23 @@ export interface SelectionApi {
      *     does.
      * @returns What changed.
      */
-    apply(target: SelectionTarget, op?: SetOp): Promise<SelectionDelta>;
+    apply(target: SelectionTarget, op?: SelectionOp): Promise<SelectionDelta>;
     /**
      * Empty the selection.
      * @returns What changed.
      */
     clear(): SelectionDelta;
     /**
-     * Keep this selection under a name, so it can be named as a scope later.
+     * Keep this selection under a name, as a kept set created from the selection, so it can be
+     * named as `{ set: id }` later.
      *
-     * The saved scope holds the selected NODES: a scope's edges are induced from its nodes, so a
-     * selected edge whose endpoints are not selected is not an edge any work over that scope
-     * could follow.
+     * The kept set holds the selected nodes and the selected edges. With nodes selected it reads
+     * `induced`: every edge between its nodes comes with it, and the selected edges are kept
+     * beside them. With edges alone it reads `listed`: those edges and their endpoints.
+     * @deprecated Use {@link SetsApi.createFrom | session.sets.createFrom("selection")}, which keeps
+     * the same members and also takes a reading; this verb keeps working.
      * @param name - The name to save it under.
-     * @returns The minted scope id.
+     * @returns The minted set id.
      */
     promote(name: string): ScopeId;
     /**
@@ -220,7 +223,7 @@ export interface SelectionOwner extends SelectionApi {
      * @param cause - Who asked; the API itself when absent.
      * @returns What changed.
      */
-    applyNow(target: SelectionTarget, op?: SetOp, cause?: SelectionCause): SelectionDelta;
+    applyNow(target: SelectionTarget, op?: SelectionOp, cause?: SelectionCause): SelectionDelta;
     /**
      * The node mask itself, for the scope resolver's `selection` source.
      * @returns The live mask, which the caller must not mutate.
@@ -294,6 +297,8 @@ export interface SelectionSources {
      * @param delta - What joined, what left, what the selection holds now, and who asked.
      */
     readonly onChange?: (delta: SelectionDelta) => void;
+    /** Called on every version bump of either mask, which is what advances the session input tick. */
+    readonly onMaskVersion?: () => void;
 }
 /**
  * Build the selection one session owns.

package/dist/src/session/selection/index.d.ts

@@ -13,5 +13,5 @@
  *
  * Nothing in this module's import graph reaches Babylon.js, Lit or the DOM.
  */
-export { createSelectionApi, DEFAULT_SELECTION_CAP, type SelectionApi, type SelectionAttributeStatistics, type SelectionCause, type SelectionDelta, type SelectionOwner, type SelectionSources, type SelectionStatistics, SET_OPS, type SetOp, } from "./SelectionApi";
+export { createSelectionApi, DEFAULT_SELECTION_CAP, type SelectionApi, type SelectionAttributeStatistics, type SelectionCause, type SelectionDelta, type SelectionOp, type SelectionOwner, type SelectionSources, type SelectionStatistics, SET_OPS, } from "./SelectionApi";
 export { type ElementIdTarget, type NeighborhoodTarget, resolveTarget, type SelectionDirection, type SelectionMatch, type SelectionSearchHit, type SelectionTarget, type SelectionTextMode, type TargetContext, type TargetMembers, } from "./targets";