@graphty/graphty-element 2.5.2 → 2.6.1

package/dist/src/algorithms/input/ScopedInput.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @file The one input accessor a run reads its graph through (design/sets/sets-design.md section
+ * 10.1), and the binding that tells it which scope the run is over.
+ *
+ * Derivation is SCOPE FIRST: the declared snapshot, then `inducedSubgraph(node bitmap)`, then
+ * `filterEdges(edge bitmap)` only when the scope's edges are not all the edges its nodes induce,
+ * then `toUndirected` when asked, then `simplified` by the asked merge policy. The scope is applied
+ * in declared space before undirecting because `toUndirected` collapses a reciprocal pair into one
+ * edge that keeps the lower index's row: undirecting first would hand a thresholded run the weight
+ * of a hidden edge. The input is never built by inducing on edge endpoints, so a scope with
+ * isolated nodes keeps them.
+ *
+ * WHOLE-GRAPH SHORTCUT: a scope covering every node and every edge -- or no scope at all -- takes
+ * exactly the route the element took before scopes existed: the snapshot unchanged, the store's
+ * per-snapshot undirected cache for the undirected view, and the merge of parallel edges.
+ *
+ * WHO GETS A SCOPED INPUT is decided per algorithm class: only a class declaring
+ * `static scopeInput = "subgraph"` is handed its run's scope. Every other class reads the whole
+ * graph through the same accessor, because an algorithm that enumerates its nodes from the data
+ * manager would otherwise compute over a scoped topology while listing every node.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import { type DerivedGraph, type EdgeMask, type GraphSnapshot, type NodeMask } from "@graphty/graph-format";
+import type { AlgorithmDescriptor, EdgeId, EdgeReading, NodeId } from "../../catalog/types";
+import type { Resolution } from "../../session/sets/resolve";
+import { type DerivedInput, DerivedInputs, type InputOrientation } from "./derivedInputs";
+/** Counts the input tests read: `derivations` is one per graph-format derivation, each a CSR pass. */
+export declare const scopedInputCounters: {
+    derivations: number;
+};
+/** How a run wants its input built. OPEN: may gain members. */
+export interface ScopedInputOptions {
+    /**
+     * How parallel edges merge in `subgraph()`. OPEN UNION. Default "sum", the element's reading
+     * of a repeated edge as more connection; shortest paths want "min".
+     */
+    readonly simplify?: "sum" | "min" | "max" | "none";
+}
+/** What a scoped run computes over (design 10.2). OPEN: may gain members. */
+export interface ScopedInput {
+    /** The full graph, declared orientation. */
+    readonly graph: GraphSnapshot;
+    /** The scope's nodes; valid in both orientations (undirecting keeps node rows). */
+    readonly nodes: NodeMask;
+    /** The scope's edges over the declared `graph` only, whatever orientation was asked. */
+    readonly edges: EdgeMask;
+    /** True when the scope is the whole graph; `subgraph()` then returns `graph` (or its undirected view). */
+    readonly whole: boolean;
+    /** How many nodes the scope holds: the set bits of `nodes`. */
+    readonly nodeCount: number;
+    /** How many edges the scope holds: the set bits of `edges`. */
+    readonly edgeCount: number;
+    /** The derived compact snapshot in the asked orientation. Lazy, cached, shared. */
+    subgraph(): GraphSnapshot;
+}
+/**
+ * The element's own input, which also carries the maps back to the declared graph.
+ * @internal
+ */
+export interface ElementScopedInput extends ScopedInput {
+    /**
+     * The derived snapshot with its maps.
+     * @returns The input.
+     */
+    derived(): DerivedInput;
+}
+/** The two data-manager members the accessor reads. */
+interface SnapshotSource {
+    getSnapshot(): GraphSnapshot;
+    undirected(snapshot: GraphSnapshot): DerivedGraph;
+}
+/** A scope resolved against the snapshot it covers. */
+export interface ResolvedInputScope {
+    readonly resolution: Resolution;
+    readonly graph: GraphSnapshot;
+    /** How the scope reads its edges, when the resolver knows; the run's caveat is worded from it. */
+    readonly reading?: EdgeReading;
+}
+/** What one run hands its algorithm: the scope, the cache it derives into, and its holder identity. */
+export interface RunInput {
+    readonly inputs: DerivedInputs;
+    /** The run, as the cache's holder. */
+    readonly holder: object;
+    /**
+     * The run's scope over the current snapshot, or null for the whole graph.
+     * @returns The scope.
+     */
+    scope(): ResolvedInputScope | null;
+}
+/** Which classes declare that they compute over their run's scope. OPEN UNION; "mask" is later. */
+export type ScopeInputDeclaration = NonNullable<AlgorithmDescriptor["scopeInput"]>;
+/**
+ * Whether an algorithm's class declares `static scopeInput = "subgraph"`.
+ * @param algorithm - The instance.
+ * @returns True when it computes over its scope.
+ */
+export declare function declaresScopedInput(algorithm: object): boolean;
+/**
+ * The run input an algorithm reads through, when its class declares a scoped input.
+ * @param algorithm - The instance.
+ * @returns The binding, or undefined for the whole graph.
+ */
+export declare function runInputOf(algorithm: object): RunInput | undefined;
+/**
+ * The scope of the run an algorithm is publishing for, whatever its class declares: what mask-back
+ * masks against.
+ * @param algorithm - The instance.
+ * @returns The scope over the current snapshot, or null outside a run or for the whole graph.
+ */
+export declare function runScopeOf(algorithm: object): ResolvedInputScope | null;
+/**
+ * The orientation an algorithm-graph mode reads.
+ * @param mode - `"directed"` or `"undirected"`.
+ * @returns The orientation.
+ */
+export declare function orientationOf(mode: "directed" | "undirected"): InputOrientation;
+/**
+ * The input one algorithm reads, in one orientation.
+ * @param data - The data manager.
+ * @param orientation - The orientation.
+ * @param options - The merge policy.
+ * @param run - The run's binding, when the algorithm declares a scoped input and runs as a run.
+ * @returns The input.
+ * @throws An Error when the run's scope was resolved against another snapshot than the current one.
+ */
+export declare function createScopedInput(data: SnapshotSource, orientation: InputOrientation, options?: ScopedInputOptions, run?: RunInput): ElementScopedInput;
+/**
+ * The nodes an input covers, in declared row order: the order of the compact snapshot's rows, and
+ * the order an adapter lists what it publishes in.
+ * @param input - The input.
+ * @returns The node ids.
+ */
+export declare function scopeNodeIds(input: ScopedInput): NodeId[];
+/** One declared edge an input covers: its session id, its row in the declared graph, and its ends. */
+interface ScopeEdge {
+    readonly id: EdgeId;
+    /** The row in `ScopedInput.graph`, which is what an edge remap is indexed by. */
+    readonly row: number;
+    /** The source node, in the declared orientation. */
+    readonly source: NodeId;
+    /** The target node, in the declared orientation. */
+    readonly target: NodeId;
+}
+/**
+ * The declared edges an input covers, in row order.
+ * @param input - The input.
+ * @returns The edges.
+ * @throws An Error when the graph carries no edge id column, which every store declares.
+ */
+export declare function scopeEdges(input: ScopedInput): ScopeEdge[];
+/** What owns a graph's derived inputs: the graph, and the accelerator its release goes to. */
+interface InputOwner {
+    readonly acceleration: {
+        readonly accelerator: Readonly<Record<string, unknown>> | null;
+    };
+}
+/**
+ * A graph's derived inputs, built on first use. Released snapshots go to the attached
+ * accelerator's `release`, when it has one.
+ * @param owner - The graph.
+ * @returns Its cache.
+ */
+export declare function derivedInputsOf(owner: InputOwner): DerivedInputs;
+/**
+ * A graph's derived inputs, if any were ever built. For the freeze and dispose hooks.
+ * @param owner - The graph.
+ * @returns Its cache, or undefined.
+ */
+export declare function peekDerivedInputs(owner: object): DerivedInputs | undefined;
+/**
+ * Run one algorithm's work with its run's scope bound: a class declaring a scoped input reads the
+ * scope through `Algorithm.input`, and every input it derives is held until the work settles --
+ * published or aborted -- and only then may be released.
+ * @param algorithm - The instance.
+ * @param owner - The graph it runs on.
+ * @param scope - The run's scope over the current snapshot, or null for the whole graph.
+ * @param signal - Aborts a wait for room.
+ * @param work - The work.
+ * @returns What the work returned.
+ */
+export declare function withRunInput<T>(algorithm: object, owner: InputOwner & {
+    getDataManager(): SnapshotSource;
+}, scope: () => ResolvedInputScope | null, signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T>;
+export {};

package/dist/src/algorithms/input/derivedInputs.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @file The derived-input cache (design/sets/sets-design.md sections 10.3 and 10.4): the compact
+ * snapshots a scoped run computes over, kept so a repeated scoped run hands an accelerator the
+ * SAME snapshot object and hits its upload cache instead of uploading the graph again.
+ *
+ * An entry is keyed by (store, snapshot serial, resolution signature, orientation,
+ * simplification). The resolution signature is a hash of the node and edge bitmaps, and a hit is
+ * confirmed word for word against the bitmaps the entry was derived for, so two scopes spelled
+ * differently that cover the same elements share one input, and a hash collision can never hand a
+ * run somebody else's graph.
+ *
+ * ENTRIES ARE REFERENCE-COUNTED. A run holds every entry it derived or looked up from the moment
+ * it asks until its result is published or it is aborted. GPU memory is not garbage collected and
+ * an accelerator's `release` destroys device buffers at once, so an entry is only ever MARKED
+ * while held -- by byte pressure, a freeze or dispose -- and the release runs when the last holder
+ * lets go. Nothing runs on memory that has gone, the guarantee `Graph.ts` gives a layout.
+ *
+ * BYTES are the typed arrays reachable from the live entries, each counted once however many
+ * entries reach it: the derived snapshots with their columns, id maps and whatever views an
+ * algorithm built on them since, the composed maps, and the bitmaps a hit is checked against. The
+ * bound is max(256 MB, 1.5 x the full snapshot's bytes), so one ordinary scoped run always fits.
+ * Held entries count against it and are never evicted; a run that cannot fit waits for a DIFFERENT
+ * run to let go, or is refused `E_TOO_LARGE` when no other run holds anything. A run never waits
+ * on itself: once it holds an input, whatever else it derives is admitted over the bound.
+ *
+ * Device bytes are the accelerator's to count; they are not in this bound.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { GraphSnapshot, U32 } from "@graphty/graph-format";
+/** How a run wants its input's parallel edges merged. OPEN UNION (design 10.2). */
+export type SimplifyPolicy = "sum" | "min" | "max" | "none";
+/** Which orientation a run reads. */
+export type InputOrientation = "declared" | "undirected";
+/** Counts the cache tests read. */
+export declare const derivedInputCounters: {
+    hits: number;
+    misses: number;
+    released: number;
+};
+/** One derived input: the snapshot a run computes over and the maps back to the declared graph. */
+export interface DerivedInput {
+    /** The compact snapshot, in the asked orientation and simplified by the asked policy. */
+    readonly snapshot: GraphSnapshot;
+    /** Declared edge index -> edge index in {@link snapshot}, INVALID_INDEX when dropped; null when unchanged. */
+    readonly edgeRemap: U32 | null;
+    /** Node index in {@link snapshot} -> declared node index; null when unchanged. */
+    readonly nodeOrigin: U32 | null;
+}
+/** The membership an input is derived for: a resolution's bitmaps, over one snapshot of one store. */
+export interface InputMembership {
+    readonly nodes: U32;
+    readonly edges: U32;
+    readonly serial: number;
+    readonly store: object | null;
+}
+/** A read-only view of one entry, for the accounting test. */
+interface DerivedInputEntry extends DerivedInput {
+    readonly key: string;
+    readonly held: boolean;
+    readonly marked: boolean;
+    /** The bitmaps the entry was derived for. */
+    readonly nodes: U32;
+    readonly edges: U32;
+}
+/** One session graph's derived inputs. */
+export declare class DerivedInputs {
+    private readonly options;
+    /** Entries, least recently used first. */
+    private readonly entries;
+    /** Entries kept only until their holders let go: marked, and no longer reachable by key. */
+    private readonly draining;
+    /** Bytes each waiting-or-running run reserved before deriving. */
+    private readonly reservations;
+    /** Runs waiting for another run to let go. */
+    private waiters;
+    /** The full snapshot's bytes, as last seen. */
+    private fullBytes;
+    private disposed;
+    /**
+     * An empty cache.
+     * @param options - The release hook and, for tests, the byte bound.
+     * @param options.release - Frees an accelerator's device buffers for a snapshot nothing uses.
+     * @param options.limit - A fixed byte bound instead of max(256 MB, 1.5 x the full snapshot).
+     */
+    constructor(options?: {
+        readonly release?: (snapshot: GraphSnapshot) => void;
+        readonly limit?: number;
+    });
+    /**
+     * The byte bound now.
+     * @returns The bound.
+     */
+    get bound(): number;
+    /**
+     * The bytes the live entries hold, draining ones included.
+     * @returns The byte count.
+     */
+    get bytes(): number;
+    /**
+     * Every live entry, draining ones included, least recently used first. For the accounting test.
+     * @returns The entries.
+     */
+    list(): DerivedInputEntry[];
+    /**
+     * A cached input, held for a run on a hit.
+     * @param holder - The run.
+     * @param membership - What it is derived for.
+     * @param orientation - The orientation.
+     * @param simplify - The merge policy.
+     * @returns The input, or undefined on a miss.
+     */
+    get(holder: object, membership: InputMembership, orientation: InputOrientation, simplify: SimplifyPolicy): DerivedInput | undefined;
+    /**
+     * Cache an input a run derived, held for it, then evict unheld entries past the bound.
+     * @param holder - The run.
+     * @param membership - What it was derived for.
+     * @param orientation - The orientation.
+     * @param simplify - The merge policy.
+     * @param input - The derived input.
+     * @param full - The full snapshot it was derived from, whose bytes set the bound.
+     * @returns The input.
+     */
+    put(holder: object, membership: InputMembership, orientation: InputOrientation, simplify: SimplifyPolicy, input: DerivedInput, full: GraphSnapshot): DerivedInput;
+    /**
+     * Reserve room for a run's derivation before it starts. Evicts unheld entries to make room;
+     * waits while a DIFFERENT run holds or reserves what would free it; refuses `E_TOO_LARGE`
+     * when nothing else holds anything and it still does not fit. A run that already holds an
+     * input is admitted at once: it never waits on itself.
+     * @param holder - The run.
+     * @param estimate - The bytes its derivation is expected to take.
+     * @param full - The full snapshot, whose bytes set the bound.
+     * @param signal - Aborts the wait.
+     * @returns Resolves once the run may derive.
+     */
+    reserve(holder: object, estimate: number, full: GraphSnapshot, signal?: AbortSignal): Promise<void>;
+    /**
+     * A run published or aborted: it lets go of every input it held and its reservation. A marked
+     * input with no holder left is released; waiting runs try again.
+     * @param holder - The run.
+     */
+    releaseHolder(holder: object): void;
+    /** The graph froze: every entry is over a snapshot that has gone. */
+    freeze(): void;
+    /** The graph is being torn down: release what nothing holds, mark the rest, cache nothing more. */
+    dispose(): void;
+    /**
+     * Mark every entry over another snapshot or store than this membership's.
+     * @param membership - The membership now being asked for.
+     */
+    private sync;
+    /**
+     * Evict unheld entries, least recently used first, until the bytes fit.
+     * @param budget - The bytes to fit in; the bound by default.
+     */
+    private shrink;
+    /**
+     * Take an entry out of the cache: released at once when unheld, else marked and drained.
+     * @param entry - It.
+     */
+    private evictEntry;
+    /**
+     * Release an entry's snapshot, unless another live entry still reaches the same one.
+     * @param entry - It.
+     */
+    private free;
+    /**
+     * Every live entry: cached and draining.
+     * @yields Each entry.
+     */
+    private live;
+    /**
+     * Whether a run holds anything.
+     * @param holder - The run.
+     * @returns True when it does.
+     */
+    private holds;
+    /**
+     * Whether a run other than this one holds an input or a reservation.
+     * @param holder - The run asking.
+     * @returns True when another does.
+     */
+    private othersHold;
+    /**
+     * The bytes other runs reserved and have not yet derived.
+     * @param holder - The run asking, left out.
+     * @returns The byte count.
+     */
+    private pending;
+    /**
+     * Resolves the next time a run lets go or the graph freezes.
+     * @param signal - Rejects the wait when aborted.
+     * @returns The wait.
+     */
+    private nextRelease;
+    /** Let every waiting run try again. */
+    private wake;
+}
+export {};

package/dist/src/algorithms/input/maskBack.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Central mask-back of a scoped run's published values, the caveat that says what the run
+ * computed on, and the check of node options against the scope (design/sets/sets-design.md
+ * section 10.1).
+ *
+ * MASK-BACK IS CENTRAL so that it holds whatever path computed a value: an algorithm that fills a
+ * default for every element it did not index (Dijkstra's `Infinity` and `onPath: false`), an edge
+ * remap that writes every declared edge of a merged group, and an algorithm that computed on the
+ * whole graph because it does not declare a scoped input. Every node value outside the scope's
+ * node bitmap and every edge value outside its edge bitmap is dropped before the result is built,
+ * so it reads missing and is left out of every ranking, histogram and summary.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { OptionDescriptor } from "../../catalog/types";
+import type { RunResultInit } from "../../session/results/RunResult";
+import { type ResolvedInputScope } from "./ScopedInput";
+/** The note a run carries when its algorithm computed on the whole graph and was masked back. */
+export declare const WHOLE_GRAPH_CAVEAT = "Computed on the whole graph; values kept for the scope only.";
+/**
+ * A result's inputs with every value outside the run's scope dropped and the scope caveat added.
+ * A run over the whole graph, or no run at all, passes unchanged.
+ * @param algorithm - The algorithm instance publishing the result.
+ * @param init - What it would build the result from.
+ * @returns What to build the result from.
+ */
+export declare function maskBack(algorithm: object, init: RunResultInit): RunResultInit;
+/**
+ * Refuse a node option that names a node of the graph outside the run's scope, before any work
+ * starts. An id the graph does not hold at all is left to the algorithm, which says so in its own
+ * words.
+ * @param options - The algorithm's declared options.
+ * @param params - The values the run starts with.
+ * @param scope - The run's scope, or null for the whole graph.
+ * @throws A `GraphtyError` with `E_OPTION_RANGE` and `details.reason: "outside-scope"`.
+ */
+export declare function checkNodeOptions(options: readonly OptionDescriptor[], params: Readonly<Record<string, unknown>>, scope: ResolvedInputScope | null): void;

package/dist/src/algorithms/metrics/MetricAlgorithm.d.ts

@@ -17,7 +17,7 @@
 import type { FieldDescriptor, NodeId } from "../../catalog/types";
 import { type RunResult } from "../../session/results";
 import { Algorithm } from "../Algorithm";
-import type { AlgorithmRunContext } from "../results/types";
+import type { RunControls } from "../results/types";
 import type { MetricMeasurement, MetricRunContext } from "./types";
 /**
  * A metric: an algorithm that measures one number for every node.
@@ -53,7 +53,7 @@ export declare abstract class MetricAlgorithm<TOptions extends Record<string, un
      * @returns The result, or undefined when there was nothing to measure.
      * @throws Whatever the context's signal throws once the run has been cancelled.
      */
-    publishResult(context: AlgorithmRunContext, runId: string): Promise<RunResult | undefined>;
+    publishResult(context: RunControls, runId: string): Promise<RunResult | undefined>;
     /**
      * Measure the graph, publish the result, and project the 1.10 view from it.
      * @param context - Where progress goes, where cancellation arrives, and which run id to
@@ -71,7 +71,7 @@ export declare abstract class MetricAlgorithm<TOptions extends Record<string, un
     /**
      * Measure every node.
      * @param context - Where progress goes and where cancellation arrives.
-     * @param nodeIds - The nodes to measure, in the graph's own order.
+     * @param nodeIds - The nodes to measure, in the input's row order.
      * @returns One value per node, how they were scaled, and what qualifies them.
      */
     protected abstract measure(context: MetricRunContext, nodeIds: readonly NodeId[]): Promise<MetricMeasurement>;

package/dist/src/algorithms/results/DeclaredAlgorithm.d.ts

@@ -9,7 +9,7 @@
 import type { AlgorithmDescriptor, FieldDescriptor, RunId } from "../../catalog/types";
 import { type RunResult } from "../../session/results";
 import { Algorithm } from "../Algorithm";
-import { type AlgorithmOutput, type AlgorithmRunContext } from "./types";
+import { type AlgorithmOutput, type AlgorithmRunContext, type RunControls } from "./types";
 /**
  * An algorithm whose result is a value it returns.
  * @template TOptions - The options type this algorithm resolves from its schema.
@@ -92,7 +92,7 @@ export declare abstract class DeclaredAlgorithm<TOptions extends Record<string,
      * @returns The result, or undefined when there was nothing to compute.
      * @throws Whatever the context's signal throws once the run has been cancelled.
      */
-    publishResult(context: AlgorithmRunContext, runId: RunId, fields?: readonly FieldDescriptor[]): Promise<RunResult | undefined>;
+    publishResult(context: RunControls, runId: RunId, fields?: readonly FieldDescriptor[]): Promise<RunResult | undefined>;
     /**
      * Compute this algorithm's result, publish it under a run id, and project the 1.x view of it.
      *
@@ -100,6 +100,7 @@ export declare abstract class DeclaredAlgorithm<TOptions extends Record<string,
      * because the catalogue states what a reader sees a field called and cannot be imported here
      * without a cycle -- it reads these classes to publish their options.
      * @param context - What the element gave the run: a signal, a progress channel and a yield.
+     *   The graph the run computes over is bound here, as the context's `input`.
      * @param runId - The id the result is published under, which is the `<runId>` in
      *   `results.<runId>`.
      * @param declared - The catalogue's descriptors for this algorithm's fields, when the caller
@@ -108,5 +109,5 @@ export declare abstract class DeclaredAlgorithm<TOptions extends Record<string,
      * @throws Whatever the context's signal throws once the run has been cancelled, which is a
      *   `DOMException` named `AbortError`.
      */
-    computeRun(context: AlgorithmRunContext, runId: RunId, declared?: readonly FieldDescriptor[]): Promise<RunResult | undefined>;
+    computeRun(context: RunControls, runId: RunId, declared?: readonly FieldDescriptor[]): Promise<RunResult | undefined>;
 }

package/dist/src/algorithms/results/types.d.ts

@@ -18,6 +18,7 @@
 import type { EdgeId, FieldDescriptor, ResultShape } from "../../catalog/types";
 import type { ResultElementValues } from "../../session/results";
 import type { Caveats, RunDirection, RunProgressReport } from "../../session/runs";
+import type { ScopedInput, ScopedInputOptions } from "../input/ScopedInput";
 /**
  * One field a run actually published.
  *
@@ -81,12 +82,33 @@ export declare function declaredCaveats(init: CaveatsInit): Caveats;
 /**
  * What the element gives an algorithm while it runs.
  *
- * The three members are the whole of it: a signal that says stop, a way to say how far along the
- * work is, and a way to hand the frame back so a long computation does not lock the screen. An
- * algorithm that reports nothing and never yields is indistinguishable, to a reader watching a
- * large graph, from one that has hung.
+ * Four members: a signal that says stop, a way to say how far along the work is, a way to hand
+ * the frame back so a long computation does not lock the screen, and the graph the run computes
+ * over. An algorithm that reports nothing and never yields is indistinguishable, to a reader
+ * watching a large graph, from one that has hung.
  */
-export interface AlgorithmRunContext {
+export interface AlgorithmRunContext extends RunControls {
+    /**
+     * The graph this run computes over, in one orientation.
+     *
+     * A class declaring `static scopeInput = "subgraph"` is handed its run's scope: `subgraph()`
+     * is the compact snapshot of the scope's nodes and edges, and `nodes`/`edges` are its masks
+     * over the full `graph`. Every other class is handed the whole graph, and the element keeps
+     * only the scope's values of what it publishes, with the caveat "Computed on the whole graph;
+     * values kept for the scope only." Publish by element id either way; row numbers of a
+     * subgraph are not the graph's.
+     * @param orientation - `"declared"`, the graph as loaded, or `"undirected"`, with a
+     *   reciprocal pair collapsed into one edge.
+     * @param options - How parallel edges merge in `subgraph()`: `"sum"` by default.
+     * @returns The input.
+     */
+    input(orientation: "declared" | "undirected", options?: ScopedInputOptions): ScopedInput;
+}
+/**
+ * The half of a run context that does not depend on which algorithm runs: what a run hands
+ * `publishResult`, which binds `input` to the algorithm it is publishing for.
+ */
+export interface RunControls {
     /** Aborted when the run is cancelled. Throw from it; never swallow it. */
     readonly signal: AbortSignal;
     /**
@@ -144,5 +166,5 @@ export declare function detachedRunContext(): AlgorithmRunContext;
  * @param step - What to do with one element.
  * @returns A promise that settles when every element has been walked.
  */
-export declare function forEachChunked<T>(context: AlgorithmRunContext, phase: string, items: readonly T[], step: (item: T, index: number) => void): Promise<void>;
+export declare function forEachChunked<T>(context: RunControls, phase: string, items: readonly T[], step: (item: T, index: number) => void): Promise<void>;
 export {};

package/dist/src/algorithms/utils/communityUtils.d.ts

@@ -1,23 +1,6 @@
 /**
  * @file Shared utilities for community detection algorithms
  */
-import type { GraphLike } from "./graphUtils";
-/**
- * Options for community utilities
- */
-interface CommunityOptions {
-    /** Weight attribute name on edges (default: "value") */
-    weightAttribute?: string;
-}
-/**
- * Options for degree calculation
- */
-interface DegreeOptions {
-    /** Whether to treat the graph as directed (default: false for undirected) */
-    directed?: boolean;
-    /** For directed graphs, count "in", "out", or "both" edges (default: "both") */
-    countType?: "in" | "out" | "both";
-}
 /**
  * Convert a community assignment map to an array of arrays.
  *
@@ -33,36 +16,6 @@ interface DegreeOptions {
  * ```
  */
 export declare function extractCommunities(communities: Map<number | string, number>): (number | string)[][];
-/**
- * Get the total weight of all edges in the graph.
- * @param graph - The graphty-element Graph instance
- * @param options - Configuration options
- * @returns Total edge weight
- * @example
- * ```typescript
- * const totalWeight = getTotalEdgeWeight(graph);
- * ```
- */
-export declare function getTotalEdgeWeight(graph: GraphLike, options?: CommunityOptions): number;
-/**
- * Get the degree of a specific node.
- *
- * In undirected mode (default), counts all edges incident to the node.
- * In directed mode, can count incoming, outgoing, or both edges.
- * @param graph - The graphty-element Graph instance
- * @param nodeId - The ID of the node
- * @param options - Configuration options
- * @returns The degree of the node
- * @example
- * ```typescript
- * // Undirected degree
- * const degree = getNodeDegree(graph, "A");
- *
- * // Directed out-degree
- * const outDegree = getNodeDegree(graph, "A", { directed: true, countType: "out" });
- * ```
- */
-export declare function getNodeDegree(graph: GraphLike, nodeId: number | string, options?: DegreeOptions): number;
 /**
  * Count the number of unique communities in a community assignment map.
  * @param communities - Map of node ID to community ID
@@ -75,4 +28,3 @@ export declare function getNodeDegree(graph: GraphLike, nodeId: number | string,
  * ```
  */
 export declare function countUniqueCommunities(communities: Map<number | string, number>): number;
-export {};