@graphty/graphty-element 2.5.1 → 2.6.0

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

@@ -1,9 +1,10 @@
 import type { SimulationType } from "@graphty/layout";
+import type { Scope, ScopeInput } from "../catalog/types";
 import type { GraphLayoutBehavior } from "../config/GraphBehavior";
 import type { Edge } from "../Edge";
 import { LayoutEngine } from "../layout/LayoutEngine";
 import { type SimulationEngineOptions } from "../layout/SimulationLayoutEngine";
-import type { Node } from "../Node";
+import type { Node, NodeIdType } from "../Node";
 import type { Styles } from "../Styles";
 import type { DataManager } from "./DataManager";
 import type { EventManager } from "./EventManager";
@@ -32,6 +33,31 @@ import type { Manager } from "./interfaces";
  * @throws A `ZodError` when an option is outside the range its published schema declares.
  */
 export declare function resolveSimulationOptions(type: SimulationType, options: Record<string, unknown>, behavior: GraphLayoutBehavior): SimulationEngineOptions;
+/**
+ * What a layout manager reads of the session to scope a layout. `Graph` hands its session's in.
+ */
+interface LayoutScopeSource {
+    /**
+     * A write position's scope in canonical form.
+     * @param input - The scope as a consumer gave it.
+     * @returns The canonical scope.
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` when it is not a scope.
+     */
+    canonical(input: ScopeInput): Scope;
+    /**
+     * The ids of the nodes a scope covers now.
+     * @param scope - The scope.
+     * @returns The ids.
+     * @throws A `GraphtyError` when the scope cannot be resolved, such as a removed set.
+     */
+    members(scope: Scope): readonly NodeIdType[];
+    /**
+     * Whether something the scope names was removed, so it can no longer mean what it meant.
+     * @param scope - The scope.
+     * @returns True when it is detached.
+     */
+    detached(scope: Scope): boolean;
+}
 /**
  * Manages layout engines and their lifecycle
  * Coordinates layout updates and transitions
@@ -61,6 +87,20 @@ export declare class LayoutManager implements Manager {
      */
     private engineDimension?;
     private logger;
+    /** Where a scope is canonicalised and resolved, once `Graph` has a session to hand in. */
+    private scopeSource;
+    /**
+     * The scope layouts run over, CARRIED from one `setLayout` to the next: an explicit scope sets
+     * it, `"graph"` clears it, and a call that names none keeps it, so changing one force
+     * parameter never un-scopes the layout. Undefined is the whole graph.
+     */
+    private carriedScope;
+    /**
+     * The members the running layout captured when it started, or null when it holds nothing:
+     * no scope, an engine that is not scoped, or a scope that could not be resolved. Every node
+     * outside it is held, including one that arrives later.
+     */
+    private members;
     /**
      * Gets the running state of the layout
      * @returns True if layout is running, false otherwise
@@ -161,6 +201,8 @@ export declare class LayoutManager implements Manager {
      * Used by operations that are already queued to prevent nested queueing
      * @param layout - A registered engine name, or a catalogue layout id
      * @param opts - Layout-specific options
+     * @param explicitScope - Whether the carried scope was named in this call, which is the only
+     * case in which a scope the engine cannot use, or cannot resolve, is refused
      */
     private _setLayoutInternal;
     /**
@@ -206,9 +248,90 @@ export declare class LayoutManager implements Manager {
      * This goes through the queue when called from Graph
      * @param type - Layout type identifier
      * @param opts - Layout-specific options
+     * @param scope - What the layout runs over. Absent keeps the carried scope, `"graph"` clears
+     * it, and anything else becomes the carried scope for this and later layouts. Internal: a
+     * consumer scopes a layout through `Graph.setLayout`'s `options.scope`.
      * @returns Promise that resolves when layout is set
+     * @throws A `GraphtyError` with `E_UNSUPPORTED` for a scope on an engine that is not scoped,
+     * or `E_BAD_COMMAND` for a scope that is malformed or names a removed set.
+     */
+    setLayout(type: string, opts?: object, scope?: ScopeInput): Promise<void>;
+    /**
+     * Hand the manager the session it resolves scopes through.
+     * @param source - The session's canonicaliser and resolver.
+     * @internal
+     */
+    setScopeSource(source: LayoutScopeSource): void;
+    /**
+     * The scope layouts run over, as the consumer last set it; undefined for the whole graph.
+     * @returns The canonical scope.
+     * @internal
+     */
+    get scope(): Scope | undefined;
+    /**
+     * Change the carried scope without starting a layout. The next layout, and
+     * {@link LayoutManager.rescope}, run over it. It never refuses a scope that cannot be resolved:
+     * a carried scope that means nothing is inactive.
+     * @param scope - The scope; undefined or `"graph"` for the whole graph.
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` when it is not a scope.
+     * @internal
+     */
+    carryScope(scope: ScopeInput | undefined): void;
+    /**
+     * Restart the running layout, with its options, over the carried scope.
+     * @returns A promise that resolves once the layout has restarted; at once when none is set.
+     * @internal
+     */
+    rescope(): Promise<void>;
+    /**
+     * The layout as a user of the sets it names, for "Used by": present only while a layout
+     * is actually holding nodes for its scope.
+     * @returns The user and the scope, or undefined.
+     * @internal
+     */
+    scopeUser(): {
+        readonly user: {
+            readonly kind: "layout";
+            readonly id?: string;
+            readonly label: string;
+        };
+        readonly scope: Scope;
+    } | undefined;
+    /**
+     * Let go of every held node when the scope the running layout captured names something that was
+     * removed, so the layout runs over the whole graph instead. Nothing throws.
+     * @internal
+     */
+    releaseDetachedScope(): void;
+    /**
+     * The source, or the refusal a manager built without a graph gives for a scope.
+     * @returns The source.
+     */
+    private requireScopeSource;
+    /**
+     * Capture the members the next layout runs over, or null when it holds nothing.
+     * @param scoped - Whether the engine about to be built accepts a scope.
+     * @param explicit - Whether the scope came in this call, which is the only case that refuses.
+     * @returns The members.
+     * @throws The resolver's `GraphtyError` for an explicit scope that cannot be resolved.
+     */
+    private captureMembers;
+    /**
+     * The hold mask for the graph as it stands: every row whose node is not a member.
+     * @param members - The captured members.
+     * @returns The mask and the rows it covers.
+     */
+    private holdMaskOf;
+    /**
+     * Tell a freshly built scoped engine where every held node is, and then hold them.
+     *
+     * Placed first for the reason `replayPins` places before it pins: a live simulation's own idea
+     * of where a node is starts wherever its initialisation put it, and d3 fixes a node at that.
+     * @param engine - The engine about to become current.
+     * @param members - The members it lays out.
+     * @param nodes - Every node in the graph.
      */
-    setLayout(type: string, opts?: object): Promise<void>;
+    private applyHold;
     /**
      * Run the configured number of simulation steps, stopping early if the layout arrives.
      *
@@ -348,3 +471,4 @@ export declare class LayoutManager implements Manager {
      */
     updatePositions(nodes: Node[]): Promise<void>;
 }
+export {};

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

@@ -24,6 +24,7 @@ interface PerfCounterSnapshot {
  * Draw calls counter data (includes count in addition to timing)
  */
 interface DrawCallsSnapshot extends PerfCounterSnapshot {
+    /** How many frames the counter has seen. The last frame's draw calls are `current`. */
     count: number;
 }
 /**

package/dist/src/session/GraphSession.d.ts

@@ -10,6 +10,11 @@
  * rather than aspirational: `test/packaging/node-safe-entries.test.ts` resolves the `./session`
  * entry point's import graph and fails if a renderer appears in it.
  */
+import type { RuleTree, Scope } from "../catalog/types";
+import { type InputCounters } from "./attributes";
+import { type ScopeResolver } from "./scope";
+import { SetsNotifier } from "./sets/notify";
+import type { SetsApi, SetUser } from "./sets/types";
 import type { CreateGraphSessionOptions, ElementSession, GraphSession } from "./types";
 /**
  * Build a graph session.
@@ -45,3 +50,46 @@ export declare function createGraphSession(options?: CreateGraphSessionOptions):
  * @returns The session.
  */
 export declare function createElementSession(options?: CreateGraphSessionOptions): ElementSession;
+/** What names a set from outside the session, for `usedBy`. */
+type SetsUsersProvider = () => Iterable<{
+    readonly user: SetUser;
+    readonly scope: Scope | RuleTree;
+}>;
+/**
+ * Add users of sets that live outside the session -- the element's running layout -- to what
+ * `sets.usedBy` reports. Internal.
+ * @param session - a session this module built
+ * @param provider - reads the users now
+ * @throws An Error for a session this module did not build.
+ */
+export declare function addSetsUsers(session: GraphSession, provider: SetsUsersProvider): void;
+/**
+ * A session's change notifier and re-resolution scheduler (design/sets 11). Internal.
+ * @param session - a session this module built
+ * @returns its notifier
+ * @throws An Error for a session this module did not build.
+ */
+export declare function setsNotifierOfSession(session: GraphSession): SetsNotifier;
+/**
+ * A session's scope resolver, with the synchronous doors the published `session.scope` lacks.
+ * Internal.
+ * @param session - a session this module built
+ * @returns its resolver
+ * @throws An Error for a session this module did not build.
+ */
+export declare function scopeResolverOfSession(session: GraphSession): ScopeResolver;
+/**
+ * A session's kept sets. Internal: the tests' spelling of `session.sets`.
+ * @param session - a session
+ * @returns its sets
+ */
+export declare function setsOfSession(session: GraphSession): SetsApi;
+/**
+ * A session's input counters: its input tick and its attribute revisions (design/sets 6.2).
+ * Internal.
+ * @param session - a session this module built
+ * @returns its counters
+ * @throws An Error for a session this module did not build.
+ */
+export declare function inputCountersOfSession(session: GraphSession): InputCounters;
+export {};

package/dist/src/session/attributes.d.ts

@@ -1,14 +1,22 @@
 /**
- * @file What attributes the graph's records carry, described as data.
+ * @file What attributes the graph's records carry, described as data -- and the one function that
+ * writes them.
  *
  * An options form, a filter builder, a colour encoding and a column picker all need the same
  * four facts about every attribute: what it is called, what type its values are, how many
  * records actually carry it, and what a few of its values look like. Each of those is a walk
  * over the graph, so each of them is the element's to do once rather than every consumer's to do
  * separately.
+ *
+ * The second half is the writer. A cache over a rule that reads `data.weight` is keyed on the
+ * revision of `weight` (design/sets/sets-design.md 6.2), and a revision that some write path forgot
+ * to bump is a cache that answers from values nobody holds any more. So every write into a
+ * record's `data` goes through {@link writeAttributes} or {@link replaceAttributes}, and
+ * `test/session/single-attribute-writer.test.ts` fails on any other.
  */
 import type { GraphSnapshot } from "@graphty/graph-format";
 import type { AttributeDescriptor } from "../catalog/types";
+import type { MovedInput } from "./sets/notify";
 import { type SessionRecordSource } from "./types";
 /**
  * Every attribute the graph's records carry.
@@ -22,3 +30,115 @@ import { type SessionRecordSource } from "./types";
  * @returns the descriptors, node attributes first
  */
 export declare function describeAttributes(snapshot: GraphSnapshot, records: SessionRecordSource | null): readonly AttributeDescriptor[];
+/**
+ * One session-wide counter that moves whenever any input a set's resolution can read moves: an
+ * attribute revision, a visibility or selection mask version, an execution token or a freeze.
+ *
+ * A memo keyed on it can never outlive an input it summarises, which is its whole job: a reader
+ * that saw the same tick twice knows nothing it could have read has changed in between.
+ */
+export declare class InputTick {
+    #private;
+    /**
+     * The current tick.
+     * @returns the tick, starting at 0 and only ever growing
+     */
+    get value(): number;
+    /** Move the tick on. Allocation-free, so a freeze can call it inside its commit. */
+    advance(): void;
+    /**
+     * Tell every session over this store that an input moved (design/sets 11). Separate from
+     * {@link InputTick.advance}, which moves on every bump: this is said once per write or freeze,
+     * after it has landed, by the store owner's side -- a freeze once delivered, an attribute
+     * write once per batch.
+     * @param input - what moved
+     */
+    announce(input: MovedInput): void;
+    /**
+     * Hear every announcement.
+     * @param listener - called with each
+     * @returns stops listening
+     */
+    listen(listener: (input: MovedInput) => void): () => void;
+}
+/**
+ * Per-field revisions of one element kind's attributes.
+ *
+ * Keyed by the TOP-LEVEL field, the first segment after `data.`, because that is the granularity a
+ * compiled rule's paths name and the granularity a write touches: editing `label` must not
+ * invalidate a rule over `weight`.
+ */
+export declare class AttributeRevisions {
+    #private;
+    /**
+     * Start every field at revision 0.
+     * @param tick - the session tick every bump advances
+     */
+    constructor(tick: InputTick);
+    /**
+     * The revision of one field.
+     * @param field - the top-level attribute key
+     * @returns how many writes have touched it; 0 for a field nothing has written
+     */
+    of(field: string): number;
+    /**
+     * Record that one write touched these fields. A write that changed no value still counts:
+     * comparing old and new values would cost a deep equality per field for no correctness gain.
+     * @param fields - the top-level keys written
+     */
+    bump(fields: Iterable<string>): void;
+}
+/** The three counters a set's input signature reads, shared by a session and its store's owner. */
+export interface InputCounters {
+    /** The session input tick. */
+    readonly tick: InputTick;
+    /** Node attribute revisions. */
+    readonly nodes: AttributeRevisions;
+    /** Edge attribute revisions. */
+    readonly edges: AttributeRevisions;
+}
+/**
+ * The counters of one store owner, created on first ask.
+ *
+ * Keyed by the object the session is handed as its store: `DataManager` for a rendered graph, which
+ * passes the same counters to every `GraphStore` it builds so a Clear never rewinds them, or the
+ * `GraphStore` itself for a headless session. A side table rather than a member, so the published
+ * `SessionGraphStore` interface gains nothing.
+ * @param owner - the store, or whoever builds stores
+ * @returns its counters
+ */
+export declare function inputCountersOf(owner: object): InputCounters;
+/**
+ * Write fields into a record's attributes and bump each field's revision. With `fields` naming
+ * only some keys of `update`, only those are written.
+ * @param revisions - the revisions of the record's kind
+ * @param data - the record's attribute object (`node.data`, `edge.data`)
+ * @param update - where the values come from
+ * @param fields - the keys to write; every own key of `update` when absent
+ */
+export declare function writeAttributes(revisions: AttributeRevisions, data: Record<string, unknown>, update: Readonly<Record<string, unknown>>, fields?: readonly string[]): void;
+/**
+ * Write a batch of updates, each into the attributes of the record its `id` names, through
+ * {@link writeAttributes}, then announce the fields written once on the input tick, so a live set
+ * re-resolves once per batch rather than once per record (design/sets 11). `id` is the address,
+ * not an attribute, and is not written; an id with no record is skipped.
+ * @param counters - the store owner's counters
+ * @param element - which kind of record
+ * @param updates - the updates
+ * @param dataOf - a record's attribute object by id
+ */
+export declare function writeUpdates(counters: InputCounters, element: "node" | "edge", updates: readonly {
+    readonly id: string | number;
+    readonly [key: string]: unknown;
+}[], dataOf: (id: string | number) => Record<string, unknown> | undefined): void;
+/**
+ * Replace a record's attributes wholesale (the `last` repeated-edge policy) and bump every field
+ * the old or the new record carries, since a field that disappeared changed too.
+ * @param revisions - the revisions of the record's kind
+ * @param owner - the object holding `data`
+ * @param owner.data - its current attributes
+ * @param record - the new attributes, held by reference as the constructor holds the first
+ */
+export declare function replaceAttributes<T extends object>(revisions: AttributeRevisions, owner: {
+    data: T;
+}, record: T): void;

package/dist/src/session/cost/estimate.d.ts

@@ -235,6 +235,11 @@ export interface CostInput {
      * same rule written once.
      */
     readonly sample?: number;
+    /**
+     * Seconds spent deriving a scoped run's compact input before the algorithm starts, added to
+     * the algorithm's own estimate. Absent for a run over the whole graph.
+     */
+    readonly derivationSeconds?: number;
 }
 /**
  * What a run would cost, and how much the answer is worth.
@@ -302,8 +307,23 @@ export type CostGateDecision = {
     /** The error to reject the run with, carrying the facts a consumer switches on. */
     readonly error: GraphtyError;
 };
+/** A scope a refused run could be pointed at, sized by whoever holds it: a kept set, today. */
+export interface ScopeCandidate {
+    /** The scope specification. */
+    readonly scope: Scope;
+    /** What to call it on a button: the set's name. */
+    readonly label: string;
+    /** How many nodes it covers. */
+    readonly nodes: number;
+    /** How many edges it covers. */
+    readonly edges: number;
+    /** Seconds to derive its compact input. */
+    readonly derivationSeconds: number;
+}
 /** What the gate is told beyond the estimate's own inputs. */
 interface CostGateOptions {
+    /** The kept sets to suggest when they fit, read only on a refusal. */
+    readonly keptSets?: () => readonly ScopeCandidate[];
     /** The cap and the memory budget. Defaults to {@link DEFAULT_COST_GATE_LIMITS}. */
     readonly limits?: Readonly<CostGateLimits>;
     /** Refuse to approximate: above the cap this fails rather than sampling. */

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

@@ -13,5 +13,5 @@
  * the frame for 10.4.
  */
 export { calibrateCost, calibrateOnce, CostMeasurementLog, currentCalibration, machineFingerprint, resetCalibration, } from "./calibrate";
-export type { CostConfidence, CostEstimate, CostGateDecision, CostGateLimits, CostInput, CostMeasurement, MachineCalibration, } from "./estimate";
+export type { CostConfidence, CostEstimate, CostGateDecision, CostGateLimits, CostInput, CostMeasurement, MachineCalibration, ScopeCandidate, } from "./estimate";
 export { ASSUMED_ITERATION_BOUND, DEFAULT_COST_GATE_LIMITS, DEFAULT_COST_RATES, DEFAULT_EXACT_COMPUTATION_CAP_SECONDS, estimateCost, gateRun, ITERATION_OPTION_NAME, MAX_COLUMN_LENGTH, MEASUREMENT_EXTRAPOLATION_LIMIT, resultBytes, } from "./estimate";

package/dist/src/session/planning.d.ts

@@ -15,9 +15,9 @@
  *
  * Nothing here reaches Babylon.js, Lit or the DOM.
  */
-import type { AlgorithmDescriptor, AlgorithmKey, FieldDescriptor, RunId, Scope } from "../catalog/types";
+import type { AlgorithmDescriptor, AlgorithmKey, FieldDescriptor, RunId, Scope, SetId } from "../catalog/types";
 import type { GraphtyErrorCode } from "../errors";
-import { type CostEstimate, type CostGateLimits, type CostMeasurement, type MachineCalibration } from "./cost";
+import { type CostEstimate, type CostGateLimits, type CostMeasurement, type MachineCalibration, type ScopeCandidate } from "./cost";
 import type { Caveats, ResolvedScope } from "./runs";
 import type { GraphStatistics } from "./types";
 /**
@@ -175,7 +175,37 @@ export interface PlanningContext {
     readonly calibration?: () => MachineCalibration | undefined;
     /** Reads the most recent timing of each algorithm on this machine. */
     readonly measurements?: () => ReadonlyMap<AlgorithmKey, CostMeasurement> | undefined;
+    /**
+     * The kept sets, in listing order, for the scopes a refused run is pointed at.
+     * @returns Each set's id and name.
+     */
+    readonly keptSets?: () => readonly {
+        readonly id: SetId;
+        readonly name: string;
+    }[];
 }
+/**
+ * The cost of deriving a scope's compact input, in seconds: a + b(N + E) + c(kept edges).
+ *
+ * Not proportional to the scope: `inducedSubgraph` allocates full-length remaps and scans every
+ * edge of the whole graph, then builds the kept edges. Fitted to the design's measured rows
+ * (design/sets 6.5, Barabasi-Albert m = 5): 64 ms at 1M / 5M keeping 10% of the nodes and 273 ms
+ * keeping 50%, which gives about 9 ns per element of the whole graph and 170 ns per kept edge.
+ * ponytail: fixed coefficients from one machine; the timing runners re-fit them, and a calibrated
+ * rate replaces them when a derivation is ever timed on the device.
+ * @param nodes - Nodes in the whole graph.
+ * @param edges - Edges in the whole graph.
+ * @param keptEdges - Edges in the scope.
+ * @returns The seconds.
+ */
+export declare function derivationSeconds(nodes: number, edges: number, keptEdges: number): number;
+/**
+ * The kept sets a refused run could be pointed at, sized over the graph as it stands. A set that
+ * cannot be resolved now (a detached one) or holds no node is left out.
+ * @param context - What planning reads.
+ * @returns The candidates, in listing order.
+ */
+export declare function keptSetScopes(context: PlanningContext): ScopeCandidate[];
 /**
  * What one command would cost, answered synchronously so that a button can be drawn from it.
  * @param context - What planning reads.

package/dist/src/session/query.d.ts

@@ -66,6 +66,13 @@ export interface QueryEngine {
      * @returns The unresolved paths.
      */
     unresolvedPathsOf(where: Query): readonly Path[];
+    /**
+     * Every path an expression reads, as its node compile sees them: what a cached answer over it
+     * is keyed on.
+     * @param where - The expression.
+     * @returns The paths.
+     */
+    pathsOf(where: Query): readonly Path[];
     /**
      * The nodes a text search finds.
      * @param text - What was typed.

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

@@ -16,7 +16,7 @@
  * published from the Node-safe `./session` entry point.
  */
 import type { Path, ResultShape, RunId } from "../../catalog/types";
-import { type ResultRoot, type ResultsApi, type RunResult } from "./types";
+import { type ResultRoot, type ResultsApi, type RunRef, type RunResult } from "./types";
 /**
  * The few candidates closest to a name somebody got wrong.
  *
@@ -50,6 +50,12 @@ export interface ResultsRunEntry {
     readonly shape: ResultShape;
     /** The result, once the run has published one. */
     readonly result?: RunResult;
+    /**
+     * The token of the execution that produced `result`, written with it so whatever restores the
+     * result restores its token (design/sets 5.2). Internal: surfaced later only as the opaque
+     * `ResultItem.run`.
+     */
+    readonly execution?: string;
 }
 /**
  * Where the results API looks runs up.
@@ -70,6 +76,13 @@ export interface ResultsRegistry {
      */
     entries(): readonly ResultsRunEntry[];
 }
+/**
+ * The execution token of a run's current result, read from its result entry.
+ * @param results - A results API this module built.
+ * @param run - The run, its result, or its id.
+ * @returns The token, or undefined when there is no result or none was minted.
+ */
+export declare function resultExecutionOf(results: ResultsApi, run: RunRef): string | undefined;
 /**
  * Build the results API over a registry of runs.
  * @param registry - Where runs are looked up.

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

@@ -26,8 +26,9 @@
 import type { AlgorithmKey, FieldDescriptor, ResultShape, RunId } from "../../catalog/types";
 import { GraphtyError } from "../../errors";
 import type { ResultSummary, RunResult } from "../results/types";
+import type { HeldCaptures } from "../sets/captures";
 import { type StyleSuggestion } from "../styles/derive";
-import { type Caveats, type EngineVersions, type JournalId, type Progress, type ResolvedScope, type Run, type RunPhase, type RunRecord, type RunStatus, type RunStyle, type StaleNote } from "./types";
+import { type Caveats, type EngineVersions, type JournalId, type Progress, type ResolvedScope, type Run, type RunPhase, type RunRecord, type RunScopeFacts, type RunStatus, type RunStyle, type StaleNote } from "./types";
 /**
  * Where a run writes its progress so the element's existing operation events carry it.
  *
@@ -205,6 +206,12 @@ export interface RunSurroundings {
      * @returns The resolved scope.
      */
     resolveScope(): ResolvedScope;
+    /**
+     * What the run records about the set its scope names, read when the scope is resolved.
+     * Optional: a run with nobody to ask records neither.
+     * @returns The facts.
+     */
+    scopeFacts?(): RunScopeFacts;
     /**
      * Hand the run's work to the queue.
      * @param body - The work.
@@ -220,6 +227,21 @@ export interface RunSurroundings {
      * @param phase - Which moment.
      */
     notify?(phase: RunPhase): void;
+    /**
+     * Mint the token that identifies one execution of this run (design/sets 5.2): a session nonce
+     * plus a session-wide counter. Called once when the work starts. Optional for the same reason
+     * as `notify`: a run driven directly by a test has no session to mint from.
+     * @returns The token.
+     */
+    mintExecution?(): string;
+    /**
+     * Capture what live references hold of the result about to be replaced (design/sets 5.2).
+     * Called when a finished run re-executes in place, before its result goes. Optional for the
+     * same reason as `notify`.
+     * @param prior - The captures the run keeps now.
+     * @returns The captures the run keeps from now on.
+     */
+    captureHeld?(prior: HeldCaptures): HeldCaptures;
 }
 /**
  * A started computation.
@@ -231,8 +253,6 @@ export interface RunSurroundings {
 export declare class ManagedRun<T = RunResult> implements Run<T> {
     readonly id: RunId;
     readonly algorithm: AlgorithmKey;
-    readonly params: Readonly<Record<string, unknown>>;
-    readonly seed: number | null;
     readonly shape: ResultShape;
     readonly engine: EngineVersions;
     /**
@@ -243,14 +263,22 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
     readonly style: RunStyle;
     /** The journal has not landed, so every run reports that it wrote no entry. */
     readonly journalId: JournalId | null;
-    private readonly definition;
+    /** What the run is. Replaced only by {@link ManagedRun.retune}, which changes the parameters and seed. */
+    private definition;
     private readonly surroundings;
     private scopeValue;
+    private scopeFactsValue;
     private statusValue;
     private progressValue;
     private caveatsValue;
     private fieldsValue;
     private resultValue;
+    /** The token of the execution now running, minted when its work started. */
+    private executionValue;
+    /** The token of the execution that produced {@link resultValue}, written with it. */
+    private resultExecutionValue;
+    /** What held references keep of earlier executions: run state, written only by a re-run. */
+    private heldValue;
     private summaryValue;
     private errorValue;
     private startedAtValue;
@@ -272,6 +300,16 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @param surroundings - What the run asks of the session holding it.
      */
     constructor(definition: RunDefinition<T>, surroundings: RunSurroundings);
+    /**
+     * The parameters the current execution uses, canonicalised.
+     * @returns The parameters.
+     */
+    get params(): Readonly<Record<string, unknown>>;
+    /**
+     * The seed the current execution uses, or null.
+     * @returns The seed.
+     */
+    get seed(): number | null;
     /**
      * What to call this run, computed by the element rather than by the consumer.
      * @returns The label.
@@ -345,6 +383,18 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @returns The result, or undefined until the run succeeds.
      */
     get result(): T | undefined;
+    /**
+     * The execution token of the current result: undefined until a result exists, and for a run
+     * whose surroundings mint none. Internal: not on the published `Run` interface.
+     * @returns The token.
+     */
+    get resultExecution(): string | undefined;
+    /**
+     * The members of earlier executions' items that live references hold, by execution and item
+     * key. Internal: not on the published `Run` interface.
+     * @returns The captures.
+     */
+    get held(): HeldCaptures;
     /**
      * Why the run failed.
      * @returns The error, or undefined when it did not.
@@ -386,6 +436,17 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @returns This run, restarted.
      */
     rerun(): Run<T>;
+    /**
+     * Run the same result again with other parameters or another seed, keeping its id, so every
+     * style layer and reference bound to the result repaints from the new values. Work still
+     * queued or running is cancelled first: only the latest parameters' answer matters.
+     * @param params - The new parameters, canonicalised.
+     * @param seed - The new seed, or null.
+     * @param caveats - The caveats the new execution starts from.
+     * @returns This run, restarted.
+     * @internal
+     */
+    retune(params: Readonly<Record<string, unknown>>, seed: number | null, caveats: Caveats): Run<T>;
     /**
      * What this run suggests be drawn from it.
      *