@modernrelay/orbit-core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2995 @@
+import { G as GraphSnapshot, A as AcceptedGraph, R as ResolvedGroup, a as GraphDiagnostic, b as GraphNode, c as AcceptedEdge, N as NodeId, M as MetaEdge, S as SceneFold, d as GroupSpec, e as GroupBySpec, f as SceneGroups, g as RenderScene, h as SceneLinkRef, i as ScenePointRef, j as Accessor, k as RevisionAwareService, l as RequestContext, m as SearchResult, V as ViewportState, n as SelectionState, o as SubgraphSpec, J as JsonValue, E as EngineFactory, p as ExpansionService, P as PathService, q as GraphTheme, r as GraphStoreState, L as LabelPlacement, s as GraphHostUpdate, B as BeginIngestOptions, I as IngestSession, t as GraphEventName, u as GraphEventMap, v as GraphListenerControl, w as EdgeId, x as ResolvedCluster, y as PathOptions, z as PathResult, C as SearchActivation, D as CrossfilterSession, T as TimelinePlayback, F as Scale, H as MetricName, K as Revisions, O as AccessibilityConfig, Q as ThemeInput, U as LabelConfig, W as IngestBatch, X as RevisionDimension, Y as FilterSpec, Z as FilterExpr, _ as DimensionSpec, $ as BrushState, a0 as DimensionSummary, a1 as DomainPolicy, a2 as EngineBufferChannel, a3 as GraphEngine, a4 as EngineCommit, a5 as EngineCapabilities, a6 as MetricColumn } from './index-BPjuELfY.js';
+export { a7 as AppendReceipt, a8 as CategoryBin, a9 as ClusterSpec, aa as DIAGNOSTIC_SAMPLE_CAP, ab as DiagnosticCode, ac as DiagnosticSeverity, ad as DimensionKind, ae as ErrorPhase, af as ExpansionBatch, ag as ExpansionResponse, ah as FilterMode, ai as FilterValue, aj as GraphEdge, ak as GraphError, al as GraphOperationError, am as HistogramBin, an as IngestCommitReceipt, ao as IngestSessionState, ap as InstanceStatus, aq as LayoutKind, ar as NodeEventPayload, as as OrbitOperationError, at as ResourceAdmissionReport, au as SearchUnavailableReason, av as SimulationConfig, aw as graphErrorToError, ax as isFatalGraphError, ay as resourceLimitFatal } from './index-BPjuELfY.js';
+export { C as ClusterDerivation, D as DEFAULT_CLUSTER_CENTER_RADIUS, a as DEFAULT_LAYOUT_SEED, c as clusterCentroids, d as deriveClusters, g as generateClusterCenters, r as resolveClusterCenters } from './clusters-ExqnvobT.js';
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * §5.1 snapshot validation — deterministic malformed-input resolution.
+ *
+ * Pure function: same input → structurally identical output; never throws on
+ * malformed input. Diagnostics are batched — at most one GraphDiagnostic per
+ * code per pass, with a total count and at most DIAGNOSTIC_SAMPLE_CAP samples
+ * (O(categories) work/allocation, never O(bad rows)).
+ */
+
+declare function validateSnapshot<N = Record<string, unknown>, E = Record<string, unknown>>(snapshot: GraphSnapshot<N, E>): AcceptedGraph<N, E>;
+
+/**
+ * §16.3 stage-3 containment rewrite (S12-T01) — pure derivation, no engine,
+ * no DOM.
+ *
+ * ## The representative forest
+ *
+ * ONE structure drives both group collapse and node fold. Every entity — a
+ * physical node id, or a synthetic group scene key — has AT MOST ONE
+ * representative parent, and:
+ *
+ * > An entity is drawn iff no ancestor is collapsed. Each edge endpoint
+ * > reroutes to its OUTERMOST COLLAPSED ancestor; edges whose endpoints
+ * > rewrite to the same key are dropped; the rest merge per directed pair
+ * > into one meta-edge carrying the underlying count. A SYNTHETIC
+ * > representative materializes only while collapsed; a REAL one is always
+ * > drawn.
+ *
+ * `collapsed` is a property of the REPRESENTATIVE, not of the node — which
+ * is exactly why a folded anchor stays visible while its children hide, and
+ * why nesting needs no special case (a fold inside a collapsed group hides
+ * with it, and its members' edges route to the group).
+ *
+ * Contract summary (spec §16.3/§7.6 stage 3, invariants E5):
+ * - Groups are HIERARCHICAL but singly-parented: a member id may name another
+ *   group (nesting), but no entity has two parents. `validateGroupSpecs`
+ *   rejects a violating array with ONE batched §5.1 'config-error' diagnostic
+ *   BEFORE any scene rewrite — a rejected array changes nothing.
+ * - `rewriteGroups` runs over the HARD-SCOPED model (§7.6 stage 2 output):
+ *   collapsed representatives replace their in-scope descendants with one row
+ *   (a synthetic super-node, or the fold anchor's existing physical row);
+ *   descendant edges re-route into meta-edge rows carrying the underlying-edge
+ *   count (the badge datum). The post-rewrite graph feeds the EXISTING §7.2
+ *   structural diff, so collapse/expand is a diff, never a reload.
+ * - Group ids occupy a distinct PUBLIC namespace (§7.4): synthetic rows carry
+ *   INTERNAL scene keys (NUL-prefixed — outside the documented caller id
+ *   contract) that never escape public payloads. A group id equal to a node
+ *   id coexists without collision. A FOLD anchor is a real node, so its
+ *   entity key IS its node id and it needs no synthetic slot at all.
+ * - Synthetic rows are never cast to N/E: they carry only `id`, and consumers
+ *   identify them by slot position — synthetics are always a CONTIGUOUS
+ *   SUFFIX of the node/edge lists (physical prefix ordering is preserved), so
+ *   `slot >= physicalCount` is the discrimination rule.
+ */
+
+/** Internal scene key of a collapsed group's super-node row. NEVER public. */
+declare function groupSceneKey(groupId: string): string;
+/** Internal scene key of a meta-edge row (directed rewritten endpoint pair). */
+declare function metaEdgeSceneKey(sourceKey: string, targetKey: string): string;
+/** §16.3 PUBLIC meta-edge id: the collision-safe ordered endpoint tuple
+ * `JSON.stringify(['meta-edge', source.kind, source.id, target.kind,
+ * target.id])` — shared with the parallel-edge grouping toggle (R-16.3-24). */
+declare function metaEdgePublicId(sourceKind: 'node' | 'group', sourceId: string, targetKind: 'node' | 'group', targetId: string): string;
+/**
+ * Entity key: a physical node id, or a synthetic group scene key. A fold
+ * anchor IS its node id — that is the whole point of a real representative.
+ */
+type EntityKey = string;
+interface RepForest {
+    /** entity → its representative parent (at most one, by construction). */
+    readonly parent: ReadonlyMap<EntityKey, EntityKey>;
+    /** Representatives whose CHILDREN are hidden — never themselves. */
+    readonly collapsed: ReadonlySet<EntityKey>;
+    /** Synthetic representatives: scene key → the group it stands for. */
+    readonly groupOf: ReadonlyMap<EntityKey, ResolvedGroup>;
+    /** Fold anchors in declaration order (deterministic scene output). */
+    readonly anchors: readonly NodeId[];
+    /** Groups in array order (deterministic super-node suffix order). */
+    readonly groups: readonly ResolvedGroup[];
+}
+/** Physical default size when no nodeSize accessor is configured but the
+ * scene needs a full buffer for the synthetic suffix. */
+declare const PHYSICAL_DEFAULT_POINT_SIZE = 4;
+/** Physical default width when no linkWidth accessor is configured. */
+declare const PHYSICAL_DEFAULT_LINK_WIDTH = 1;
+declare const SUPER_NODE_MAX_SIZE = 36;
+declare const META_EDGE_MAX_WIDTH = 8;
+/** Aggregate super-node size: sublinear in member count, bounded. */
+declare function superNodeSizeFor(memberCount: number): number;
+/** Aggregate meta-edge width: sublinear in underlying-edge count, bounded. */
+declare function metaEdgeWidthFor(count: number): number;
+interface GroupValidationResult {
+    /** Null when the array is valid; otherwise ONE batched 'config-error'. */
+    diagnostic: GraphDiagnostic | null;
+}
+/**
+ * Validates a manual `groups` array against the FULL accepted model (members
+ * may live outside the current hard scope). Violations, all collected into
+ * one diagnostic (§5.1 delivery contract — never one event per bad row):
+ * - duplicate group id in the array;
+ * - self-membership (a group naming its own id — rejected even when a node
+ *   with that id exists: the ambiguity itself is the error);
+ * - duplicate membership (the same node twice in one group);
+ * - overlapping membership (the same node in two groups);
+ * - CYCLIC nesting (groups that contain each other, directly or through a
+ *   chain — the containment forest must stay acyclic);
+ * - unknown members (ids absent from the accepted model AND not naming
+ *   another group; with no accepted model every non-group member is unknown).
+ *
+ * NESTING IS LEGAL: a member id naming another group id nests that group.
+ * Containment is a forest, not a partition — but it stays SINGLY PARENTED,
+ * so overlap remains an error.
+ */
+declare function validateGroupSpecs(specs: readonly GroupSpec[], nodeIndex: ReadonlyMap<NodeId, number> | null): GroupValidationResult;
+/**
+ * Resolves a VALIDATED manual groups array against the accepted model.
+ * Tolerant by design: members that later departed the model drop out of the
+ * resolved membership (model drift is data, not a config error — mirrors
+ * selection pruning). Spec order and member order are preserved.
+ */
+declare function resolveManualGroups(specs: readonly GroupSpec[], nodeIndex: ReadonlyMap<NodeId, number>): ResolvedGroup[];
+/** Canonical structural equality for the groups HOST LANE (GroupSpec is a
+ * plain descriptor like Scale — equal literals never re-rewrite, §6.1). */
+declare function sameGroupSpecArrays(a: readonly GroupSpec[] | null, b: readonly GroupSpec[] | null): boolean;
+/**
+ * R-16.3-14 collision-safe derived-group id codec: `JSON.stringify(['group',
+ * key])`. Injective over keys (JSON string encoding), never equal to the raw
+ * key itself (every output starts with `["group",`), and round-trippable via
+ * JSON.parse. Labels stay separate — the derived group's `label` is the raw
+ * key. Group ids remain a distinct public namespace (§7.4), so a NODE id that
+ * happens to equal a derived id still coexists without collision.
+ */
+declare function groupByDerivedId(key: string): string;
+/** Canonical identity for the groupBy HOST LANE: `by` compares by function
+ * reference (a new inline lambda re-derives), semanticZoom structurally. */
+declare function sameGroupBySpec<N>(a: GroupBySpec<N> | null, b: GroupBySpec<N> | null): boolean;
+/**
+ * D4 boundary validation for a groupBy spec: `by` must be a function and
+ * `semanticZoom.expandAbove` must be STRICTLY greater than `collapseBelow`
+ * (the §16.3 hysteresis contract T05 builds on). Returns ONE batched
+ * 'config-error' diagnostic (the rejected spec never lands — the previous
+ * groupBy configuration stays active) or null when valid.
+ */
+declare function validateGroupBySpec<N>(spec: GroupBySpec<N>): GraphDiagnostic | null;
+interface GroupByDerivation {
+    /** One derived group per distinct key, first-encounter order over the
+     * model's node list. `collapsed` comes from the caller's residue lookup. */
+    groups: readonly ResolvedGroup[];
+    /** Derived PUBLIC id → derived key (the setGroupCollapsed reverse map —
+     * the residue is keyed by KEY, never by id, R-16.3-16). */
+    keyById: ReadonlyMap<string, string>;
+    /** ONE aggregated 'accessor-error' warning when `by` threw (the affected
+     * nodes derive as ungrouped — never silent loss, I3), else null. */
+    diagnostic: GraphDiagnostic | null;
+}
+/**
+ * §16.3 groupBy derivation: one GroupSpec-shaped ResolvedGroup per distinct
+ * string key returned by `by` (first-encounter order, matching §11
+ * categorical-domain conventions); `null` — and any non-string value — means
+ * ungrouped. Derived ids use {@link groupByDerivedId}; `label` is the raw
+ * key; `derived: true` marks membership read-only. `collapsed` defaults to
+ * whatever `isCollapsedKey` reports — with an empty residue everything is
+ * expanded, so adding groupBy alone changes no rendering (R-16.3-13).
+ */
+declare function deriveGroupsByKey<N>(nodes: readonly GraphNode<N>[], by: (node: GraphNode<N>) => string | null, isCollapsedKey: (key: string) => boolean): GroupByDerivation;
+interface SuperNodeRecord {
+    /** Internal scene key of the super-node row (never public). */
+    sceneKey: string;
+    group: ResolvedGroup;
+    /** TRANSITIVE descendants present in the REWRITTEN model's input
+     * (hard-scoped set) — the stage-5 mask and aggregate size read this, not
+     * the full declared membership. Transitive and direct coincide unless
+     * something is nested underneath. */
+    presentMemberIds: readonly NodeId[];
+}
+interface MetaEdgeRecord {
+    /** Internal scene key of the meta-edge row (never public). */
+    sceneKey: string;
+    /** Public record (§7.4 payload surface): endpoints are PUBLIC ids — a
+     * group id or a node id — and `count` is the badge datum. */
+    metaEdge: MetaEdge;
+    /** Indices of the rerouted edges in the PRE-rewrite model's edge list —
+     * the stage-5 "any underlying edge passes" rule evaluates these. */
+    underlying: readonly number[];
+}
+interface GroupRewrite<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** The post-rewrite scene model — what feeds the §7.2 structural diff. */
+    graph: AcceptedGraph<N, E>;
+    /** Physical rows (same objects as the input model's, members removed). */
+    physicalNodes: readonly GraphNode<N>[];
+    physicalEdges: readonly AcceptedEdge<E>[];
+    /** Scene slots >= these counts are synthetic (contiguous-suffix rule). */
+    physicalNodeCount: number;
+    physicalEdgeCount: number;
+    /** Aligned to point slots physicalNodeCount..count-1, in groups order. */
+    superNodes: readonly SuperNodeRecord[];
+    /** Aligned to link slots physicalEdgeCount..linkCount-1, first-encounter
+     * order over the input edge scan. */
+    metaEdges: readonly MetaEdgeRecord[];
+    /** Drawn fold anchors and the descendant count each currently hides. These
+     * are PHYSICAL rows — they occupy no synthetic slot. */
+    folds: readonly SceneFold[];
+    /** hidden node id → the entity key of the row standing for it (a super-node
+     * scene key, or a fold anchor's node id). */
+    hiddenOwner: ReadonlyMap<NodeId, EntityKey>;
+}
+/**
+ * Rewrites the collapsed representatives of `forest` over the hard-scoped
+ * model (§7.6 stage 3). Returns null when nothing collapsed intersects the
+ * model — an uncollapsed group exists only in store.groups and never
+ * rewrites the scene.
+ *
+ * Deterministic: physical rows keep model order; super-nodes append in
+ * groups-array order; meta-edges append in first-encounter order. Edges whose
+ * endpoints land on the SAME representative drop — that covers both a
+ * same-group internal edge and an anchor's edge to its own folded member,
+ * which would otherwise emit a self-loop. Dropped edges are internal state,
+ * cached by construction: they re-derive from the unchanged accepted model on
+ * expand. Synthetic rows carry no positions; the reconciler's departed cache
+ * restores a re-collapsed super-node (stable scene key) and returning members
+ * exactly like any other leave-and-return (§7.3).
+ */
+declare function rewriteGroups<N, E>(model: AcceptedGraph<N, E>, forest: RepForest): GroupRewrite<N, E> | null;
+/**
+ * Collapses same-DIRECTED-endpoint-pair physical edges into ONE meta-edge
+ * per pair, composing with an existing group rewrite (or synthesizing a
+ * groups-empty rewrite when none is active). Returns `base` unchanged when
+ * no pair has multiplicity > 1 — the toggle is then a scene no-op.
+ *
+ * Meta-edge identity reuses the T01 codecs: public id
+ * `metaEdgePublicId('node', source, 'node', target)` (the R-16.3-24 tuple),
+ * internal scene key `metaEdgeSceneKey(source, target)`. `count` (the badge
+ * datum) is the collapsed multiplicity and drives the T01 aggregate width
+ * channel; `underlying` indexes the PRE-rewrite model's edge list so the
+ * stage-5 "any underlying edge passes" mask rule applies unchanged.
+ */
+declare function collapseParallelEdges<N, E>(model: AcceptedGraph<N, E>, base: GroupRewrite<N, E> | null): GroupRewrite<N, E> | null;
+/** The RenderScene.groups descriptor for a rewrite. */
+declare function sceneGroupsOf(rewrite: GroupRewrite<unknown, unknown>): SceneGroups;
+/** Discriminated point ref: physical node id or the ResolvedGroup — never an
+ * internal scene key. Null when out of range. */
+declare function scenePointRefAt(scene: RenderScene, index: number): ScenePointRef | null;
+/** Discriminated link ref: physical edge id or the MetaEdge record. */
+declare function sceneLinkRefAt(scene: RenderScene, linkIndex: number): SceneLinkRef | null;
+
+/**
+ * §7 reconciler — id↔index model, structural diff, position cache.
+ *
+ * v0.1 implements the 'rebuild' index policy only (§7.3): every reconcile
+ * rebuilds the flat buffers from scratch in accepted-base order, preserving
+ * positions by id via the live/departed caches. Pure data-structure work: no
+ * DOM, no engine import.
+ */
+
+interface ReconcileResult {
+    scene: RenderScene;
+    /**
+     * True when the node id sequence OR the edge endpoint/id sequence differs
+     * from the previous reconcile. The first reconcile is always structural.
+     */
+    structuralChange: boolean;
+    /**
+     * True when the resolved position buffer differs from the previous live
+     * position mirror. NaN pairs compare equal so attr-only updates on
+     * unseeded nodes do not spuriously dirty the engine structure.
+     */
+    positionChange: boolean;
+    /** Nodes whose position was restored from the live or departed cache. */
+    reusedPositions: number;
+}
+declare class Reconciler {
+    private datasetKey;
+    private hasScene;
+    private prevIdByIndex;
+    private prevIndexById;
+    private prevEdgeIdByIndex;
+    private prevLinks;
+    /**
+     * Declared node.x/y as of the previous reconcile, for nodes that declared
+     * them. Lets Priority 1 distinguish a CHANGED declaration (caller intent —
+     * wins over any cache) from an unchanged one (defers to live drift). Fresh
+     * per pass, so departed ids drop and a re-add treats its declaration as new.
+     */
+    private prevDeclared;
+    /**
+     * CPU position mirror for the CURRENT scene, indexed by slot (§7.1 posBuf).
+     * Owned copy — never aliases a published scene's positions array, so
+     * noteEnginePositions never mutates an already-published RenderScene.
+     */
+    private livePositions;
+    /**
+     * Ids removed from the scene → last known finite position (§7.1/§7.3
+     * leave-and-return guarantee). Map insertion order doubles as LRU order;
+     * invariant: never overlaps the current scene's id set.
+     */
+    private readonly departed;
+    reconcile<N, E>(accepted: AcceptedGraph<N, E>): ReconcileResult;
+    /**
+     * Copy engine-read positions into the live cache for the CURRENT scene's
+     * slots (§7.1 per-event readback — simulation end, pre-structural-swap).
+     * Extra trailing floats are ignored; a short buffer updates a prefix.
+     */
+    noteEnginePositions(positions: Float32Array): void;
+    private resetDatasetState;
+}
+
+/**
+ * §8 projection (v0.1 subset): styling accessors → engine-ready typed buffers.
+ *
+ * Pure and DOM-free. Color parsing covers the CSS subset orbit documents
+ * (hex, rgb()/rgba(), hsl()/hsla(), small named map); anything else is a
+ * caller error surfaced as a batched 'accessor-error' diagnostic, never a
+ * throw and never a NaN in a GPU buffer (§8 numeric hygiene).
+ */
+
+type RGBA = [number, number, number, number];
+/**
+ * Pure, DOM-free CSS color parse → RGBA floats in [0,1], or null when the
+ * string is not a recognized color. Successful parses are memoized (cache
+ * capped at 4096 entries; cleared wholesale on overflow). The returned tuple
+ * is shared across calls — treat it as immutable.
+ */
+declare function parseColor(css: string): RGBA | null;
+declare function projectColors<T>(items: readonly T[], accessor: Accessor<T, string>, fallback?: [number, number, number, number]): {
+    buffer: Float32Array;
+    diagnostics: GraphDiagnostic[];
+};
+declare function projectSizes<T>(items: readonly T[], accessor: Accessor<T, number>, fallbackSize?: number): {
+    buffer: Float32Array;
+    diagnostics: GraphDiagnostic[];
+};
+
+/**
+ * §16.5 search — the SearchService contract plus the built-in LOCAL indexed
+ * service (S11-T06).
+ *
+ * The default service is client-side and field-scoped: it indexes the node id
+ * ALWAYS plus `attrs[field]` (String()-coerced) for each field the host
+ * declared via `searchIndex` — it never guesses privileged attr names, so a
+ * missing declaration leaves the service id-only. Matching is a
+ * case-insensitive SUBSTRING scan over ONE precomputed lowercase haystack per
+ * node (id + indexed field values joined with unit separators) — NOT a
+ * per-keystroke re-tokenization: the index builds once per model revision
+ * (lazily, on the first search that sees the new revision) and every query
+ * against that revision reuses it.
+ *
+ * Scoring: exact-id match {@link SEARCH_SCORE_EXACT_ID}, id-prefix
+ * {@link SEARCH_SCORE_ID_PREFIX}, field/id substring
+ * {@link SEARCH_SCORE_SUBSTRING} (+{@link SEARCH_SCORE_TOKEN_START_BONUS}
+ * when the match starts a token). Results sort score-desc then accepted-base
+ * order; `label` is the first matching indexed field's ORIGINAL value (the id
+ * when only the id matched).
+ *
+ * `ctx.signal` is honored between scan chunks (an awaited microtask every
+ * {@link SEARCH_SCAN_CHUNK} nodes) — abort is an optimization; the instance's
+ * admission gate is the correctness gate (§9.2). Nothing here touches the
+ * engine, the store, or the DOM.
+ */
+
+/** §16.5 search resolver: custom services plug in server-side search
+ * (Omnigraph B.7); the instance owns RequestContext creation, revision-keyed
+ * caching, supersede cancellation, and stale-result rejection at admission. */
+interface SearchService<N = Record<string, unknown>> extends RevisionAwareService {
+    search(q: string, options: {
+        limit: number;
+    }, ctx: RequestContext): Promise<readonly SearchResult<N>[]>;
+}
+/** Accepted-base view the local service indexes (thunked for lazy wiring —
+ * the instance re-reads it on every call, so the service can be constructed
+ * before any data arrives). */
+interface LocalSearchBase<N = Record<string, unknown>> {
+    /** Accepted-model nodes in accepted-base order (the tie-break order). */
+    nodes: readonly GraphNode<N>[];
+    /** §16.5 declared attr fields; undefined = id-only search (the service
+     * never guesses attr names). */
+    searchIndex: readonly string[] | undefined;
+}
+/** The built-in service plus its test seam: how many times the index was
+ * (re)built — pins "one build per model revision, not one per keystroke". */
+interface LocalSearchService<N = Record<string, unknown>> extends SearchService<N> {
+    readonly buildCount: number;
+}
+declare const SEARCH_SCORE_EXACT_ID = 3;
+declare const SEARCH_SCORE_ID_PREFIX = 2;
+declare const SEARCH_SCORE_SUBSTRING = 1;
+declare const SEARCH_SCORE_TOKEN_START_BONUS = 0.25;
+/** Nodes scanned between cooperative yields (awaited microtask + signal check). */
+declare const SEARCH_SCAN_CHUNK = 4096;
+/**
+ * Creates the §16.5 default indexed search service over the accepted model.
+ * Declares `revisionDependencies: ['source', 'model']` — the index keys on
+ * `ctx.modelRevision` (plus the declared field list), so it builds at most
+ * once per model revision and a stale-model result is discarded by the
+ * instance's admission gate. `getBase` is a thunk re-read on every call so
+ * the instance can wire the service before data arrives.
+ */
+declare function createLocalSearchService<N = Record<string, unknown>>(getBase: () => LocalSearchBase<N>): LocalSearchService<N>;
+
+/**
+ * §8 image-atlas pipeline (S10-T09) — pure core side.
+ *
+ * Turns per-point image refs (stable strings from the synchronous `nodeImage`
+ * accessor) into engine-ready atlas resources: resolved ImageBitmaps with
+ * slot assignments plus an index-aligned per-point slot buffer. The engine
+ * only ever sees the output shape (`EngineCommit.resources`); everything
+ * async — resolve, fetch, decode, retry, abort — stays here.
+ *
+ * Invariants (spec §8):
+ *  - Loads are deduplicated by ref: one in-flight resolve per unique ref.
+ *  - Slots are allocated per unique ref from a free-list capped at
+ *    `maxEntries`; over-cap refs stay placeholder and are diagnosed once per
+ *    generation.
+ *  - Results are admission-checked against the current request state before
+ *    atlas admission; the abort signal is an optimization, admission is the
+ *    gate (a resolver that ignores its signal cannot poison a newer
+ *    generation).
+ *  - Transient resolver/fetch failures retry up to `maxRetries`; decode
+ *    failures are final.
+ *  - Failures are cadence-batched: ONE `image-resolve-failed` diagnostic per
+ *    flush with a count and sampled refs, each ref counted once per
+ *    generation. Failures never poison the engine commit.
+ *  - A resolver-returned string is a final URL/data URI fetched + decoded
+ *    exactly once — never recursively passed back to the resolver.
+ */
+
+/**
+ * Owns authenticated fetch / caching / redirect handling for one ref
+ * (spec §8, Appendix B.6). Returning a Blob hands the bytes straight to
+ * decode; returning a string names a FINAL URL or data URI that the pipeline
+ * fetches + decodes once (it is never re-resolved).
+ */
+type ImageResolver = (ref: string, signal: AbortSignal) => Promise<Blob | string>;
+/** Minimal structural slice of `fetch` the pipeline needs (Node-test injectable). */
+type FetchLike = (url: string, init: {
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    blob(): Promise<Blob>;
+}>;
+/** Blob → ImageBitmap. Injectable so Node tests never touch createImageBitmap. */
+type ImageDecode = (blob: Blob) => Promise<ImageBitmap>;
+/** One coalesced flush of atlas work — mirrors `EngineCommit.resources` (§13). */
+interface ImageAtlasBatch {
+    /** Newly resolved bitmaps with their slot assignments. */
+    upserts: readonly {
+        slot: number;
+        bitmap: ImageBitmap;
+    }[];
+    /** Slots freed by eviction that the engine previously received. */
+    removeSlots: readonly number[];
+    /** Per-point atlas slot indices, aligned to the last requestRefs call
+     * (-1 = placeholder shape). */
+    pointImageIndex: Float32Array;
+    /** At most one batched `image-resolve-failed` diagnostic per flush. */
+    diagnostics: readonly GraphDiagnostic[];
+}
+interface ImageAtlasPipelineOptions {
+    /** Ref → bytes. Default: plain `fetch(ref)` → blob for public URLs. */
+    resolver?: ImageResolver;
+    /** Concurrent resolve bound. Default 4. */
+    maxConcurrent?: number;
+    /** Transient-failure retries per ref lifecycle (decode failures are final).
+     * Default 2 (three attempts total). */
+    maxRetries?: number;
+    /** Atlas slot capacity; refs beyond it stay placeholder. Default 512. */
+    maxEntries?: number;
+    /** Blob → ImageBitmap. Default `createImageBitmap`. */
+    decode?: ImageDecode;
+    /** Fetch used by the default resolver AND for resolver-returned strings. */
+    fetchImpl?: FetchLike;
+    /** Batch scheduler: called with a flush thunk when work is pending; each
+     * scheduled thunk must run at most once. Default: queueMicrotask. */
+    schedule?: (flush: () => void) => void;
+}
+declare const ATLAS_MAX_CONCURRENT_DEFAULT = 4;
+declare const ATLAS_MAX_RETRIES_DEFAULT = 2;
+declare const ATLAS_MAX_ENTRIES_DEFAULT = 512;
+declare class ImageAtlasPipeline {
+    private readonly resolver;
+    private readonly maxConcurrent;
+    private readonly maxRetries;
+    private readonly maxEntries;
+    private readonly decode;
+    private readonly fetchImpl;
+    private readonly schedule;
+    /** ref → live entry. Identity of the mapped entry is the admission gate. */
+    private readonly entries;
+    private readonly freeSlots;
+    private nextSlot;
+    private readonly queue;
+    private active;
+    /** Slots the engine has received via a flushed upsert. */
+    private readonly deliveredSlots;
+    private readonly pendingUpserts;
+    private readonly pendingRemoveSlots;
+    /** Failed refs awaiting the next flush's single batched diagnostic. */
+    private pendingFailureRefs;
+    /** ref → generation it was last counted in (once-per-generation gate). */
+    private readonly countedFailures;
+    private lastRefs;
+    private generation;
+    private flushScheduled;
+    private disposed;
+    /** D5/F11-06: evicted-entry bitmaps awaiting close — closed AFTER the
+     * flush that carries their removeSlots, so the instance's recovery-replay
+     * map (pruned synchronously in the batch callback) can never re-send a
+     * closed bitmap. */
+    private pendingCloseBitmaps;
+    private readonly batchCallbacks;
+    constructor(options?: ImageAtlasPipelineOptions);
+    /** Subscribe to coalesced flushes. Returns an unsubscribe thunk. */
+    onBatch(cb: (batch: ImageAtlasBatch) => void): () => void;
+    /**
+     * Declare the full index-aligned per-point ref list for `generation`.
+     * Refs that drop out are evicted (slot freed → removeSlots); new unique
+     * refs are resolved once each; calls with a stale (lower) generation are
+     * discarded.
+     */
+    requestRefs(refs: readonly (string | null)[], generation: number): void;
+    /** Abort all in-flight work and drop all state. Terminal. */
+    dispose(): void;
+    private allocSlot;
+    private evict;
+    /** Admission gate: entry must still be the live entry for its ref. */
+    private isCurrent;
+    private pump;
+    /** One attempt: resolve → (fetch if string) → decode. Never throws. */
+    private runAttempt;
+    private fetchBlob;
+    private finalFailure;
+    /** Queue a ref for the next flush's single diagnostic, once per generation. */
+    private recordFailure;
+    private scheduleFlush;
+    private flush;
+    /** -1 (placeholder) until the ref's bitmap is delivered or in this batch. */
+    private buildPointIndex;
+    /**
+     * I2 (roster-atomic resource mappings, F11-03): the SYNCHRONOUS point→slot
+     * mapping for the last requested roster — a slot appears only when its ref
+     * is resolved AND the engine has already received the bitmap (delivered);
+     * pending, failed, evicted, and reused-but-undelivered refs are the −1
+     * placeholder. The instance pairs every STRUCTURAL commit with this index
+     * in the same commit, so the engine never renders a new roster against the
+     * previous roster's (wrong-length, stale-slot) mapping; the scheduled
+     * async flush then only ever PROMOTES placeholders to resolved slots.
+     */
+    currentPointIndex(): Float32Array | null;
+}
+
+/**
+ * §16.14 view state (S15 view-state lane) — pure module: the serialized
+ * schema, the canonical-JSON encoder, the structural validator, and the
+ * version gate. No engine, no DOM, no store access; the instance wires
+ * `getViewState`/`setViewState` on top.
+ *
+ * ## Compatibility contract
+ *
+ * Deep-links outlive library versions, so everything in this file is a
+ * COMMITMENT, not an internal:
+ *  - The v1 wire shape below never changes incompatibly; breaking shape
+ *    changes bump `v` and ship an in-code migration from every prior version
+ *    in the same release (the registry seam is here from day one).
+ *  - Additive fields never bump `v` — an equal-`v` payload with unknown
+ *    fields applies cleanly with the unknowns ignored.
+ *  - A payload with `v` HIGHER than this library knows, or failing structural
+ *    validation (hand-edited URL, truncated paste), is rejected whole: a
+ *    half-restored view misrepresents what the sender saw (§16.14).
+ *
+ * ## v1 shape notes
+ *
+ *  - `folds` extends the spec's v1 schema (amendment logged with this slice):
+ *    §16.3 node folds are exploration state over stable public ids — a
+ *    deep-link that silently dropped them would misrepresent the sender's
+ *    view, the exact failure this feature exists to prevent. Session-local
+ *    expansion records, by contrast, are NEVER serialized (R-16.3-08).
+ *  - Brushes are TAGGED on the wire (`kind`) even though the runtime
+ *    BrushState is untagged: the tag comes from `DimensionSpec.kind` at
+ *    serialize time and lets restore validate shape-vs-dimension without
+ *    consulting the live spec first. Categorical stores EXCLUSIONS, so
+ *    categories that appear after the view was saved stay visible.
+ *  - `layout` is the normalized OBJECT form (`{ kind }`) even though the
+ *    runtime today carries only the bare kind string — the object is what
+ *    makes a future static seed or a layouts package additive.
+ */
+
+/** Tagged wire form of a crossfilter brush (§16.6 → §16.14). */
+type ViewBrushState = {
+    kind: 'numeric' | 'temporal';
+    range: readonly [number, number];
+} | {
+    kind: 'categorical';
+    excluded: readonly string[];
+};
+/** Normalized layout descriptor — object form reserves room for a static
+ * seed / structured layouts without a `v` bump. */
+interface ViewLayoutSpec {
+    kind: 'force' | 'fixed';
+}
+/** §11 Scale subset that is data by construction (no functions). */
+type SerializableScale = {
+    kind: 'sequential' | 'diverging';
+    metric: string;
+    range: readonly string[] | readonly number[];
+    domain?: readonly number[];
+    mid?: number;
+} | {
+    kind: 'categorical';
+    /** Field-descriptor form only — a function `by` is omitted upstream. */
+    by: string;
+    palette?: readonly string[] | readonly number[];
+    domain?: readonly string[];
+};
+interface ViewStyling {
+    nodeColor?: SerializableScale;
+    nodeSize?: SerializableScale;
+    showLinks?: boolean;
+    edgeArrows?: boolean;
+    /** Named themes only; a custom GraphTheme object is omitted upstream. */
+    theme?: 'light' | 'dark';
+}
+interface GraphViewState {
+    v: 1;
+    camera: ViewportState | null;
+    selection: SelectionState;
+    hiddenNodeIds: readonly NodeId[];
+    /** §9.2 isolation; null = full scope. */
+    subgraph: SubgraphSpec | null;
+    /** Manual groups verbatim, or — under `groupBy` — `{key, collapsed}` pairs
+     * only (membership recomputes from current data on restore, R-16.3-16). */
+    groups: readonly GroupSpec[] | ReadonlyArray<{
+        key: string;
+        collapsed: boolean;
+    }>;
+    pinnedNodeIds: readonly NodeId[];
+    /** §16.3 node folds: anchor → declared members (v1 extension, see header). */
+    folds?: ReadonlyArray<readonly [NodeId, readonly NodeId[]]>;
+    layout: ViewLayoutSpec;
+    /** Declaration order; a key absent here has no brush. */
+    crossfilter: ReadonlyArray<{
+        key: string;
+        state: ViewBrushState;
+    }>;
+    /** Opt-in frozen layout (quantized, visible set); tuple form keeps opaque
+     * ids safe. Restores as a fixed-equivalent regardless of engine
+     * nondeterminism. */
+    positions?: ReadonlyArray<readonly [string, number, number]>;
+    styling?: ViewStyling;
+    /** Host-owned durable source coordinate — stored verbatim, NEVER
+     * interpreted; compared canonically on restore (§16.14). */
+    dataRef?: JsonValue;
+}
+declare const VIEW_STATE_VERSION: 1;
+/**
+ * Canonical encoding of a JSON value: object keys recursively sorted, arrays
+ * order-preserving, JSON semantics for scalars (so `undefined` members are
+ * dropped exactly as JSON.stringify drops them). Two values compare equal iff
+ * their canonical strings are identical.
+ */
+declare function canonicalJson(value: JsonValue | undefined): string | undefined;
+/** Canonical equality for dataRef values (§16.14): key order never matters.
+ * A non-JSON value (cycles included) is never equal to anything — the §5
+ * "compared, never interpreted" rule extended to malformed input. */
+declare function sameDataRef(a: JsonValue | undefined, b: JsonValue | undefined): boolean;
+type ViewStateVerdict = {
+    ok: true;
+    state: GraphViewState;
+} | {
+    ok: false;
+    code: 'invalid-view-state' | 'unsupported-version';
+    problems: readonly string[];
+};
+/**
+ * Full structural validation + version gate. Order per §16.14: version first
+ * (higher-than-known and non-numeric reject as `unsupported-version` /
+ * `invalid-view-state` BEFORE field checks), then per-field structure. Lower
+ * versions run the migration registry, then re-validate at the current shape.
+ */
+declare function validateViewState(raw: unknown): ViewStateVerdict;
+type SetViewStateResult = {
+    status: 'applied';
+}
+/** dataRef differed: `viewStateMismatch` fired INSTEAD of applying.
+ * Re-call with `ignoreMismatch: true` to opt in. */
+ | {
+    status: 'mismatch';
+} | {
+    status: 'rejected';
+    code: 'invalid-view-state' | 'unsupported-version'
+    /** The state touches a §6.4 controlled slice or carries styling the
+     * host must reflect, and no aggregate restore callback exists. */
+     | 'missing-restore-callback'
+    /** Another restore/history transaction is awaiting acknowledgement. */
+     | 'restore-pending'
+    /** The host never reflected the intent within the window. */
+     | 'restore-timeout'
+    /** The host reflected DIFFERENT values than the intent asked for. */
+     | 'restore-diverged';
+    problems: readonly string[];
+};
+
+/**
+ * §6 GraphInstance — the public headless core instance (v0.3 subset).
+ *
+ * One `applyHostUpdate` call is the atomic host boundary: it validates,
+ * reconciles, re-projects only dirty channels, and publishes EXACTLY ONE store
+ * `set()` and AT MOST ONE engine commit, so a simultaneous data + style +
+ * controlled-state change can never tear across frames (§6).
+ *
+ * Vanilla zustand only — no React, no DOM access at module scope (§18).
+ */
+
+/** §8 dark base theme (the default when no base is named). */
+declare const GRAPH_THEME_DARK: GraphTheme;
+/** §8 light base theme. */
+declare const GRAPH_THEME_LIGHT: GraphTheme;
+/**
+ * Resolve a ThemeInput to a full GraphTheme (§8): pick the named base
+ * (default dark), then merge every defined token over it. A full GraphTheme
+ * input resolves to exactly its own tokens; `undefined` resolves to the dark
+ * base; the v0.1 `{background}` compat shorthand merges as a partial.
+ */
+declare function resolveTheme(input?: ThemeInput): GraphTheme;
+/** One categorical legend row (§11): declared-domain rows first (including
+ * currently-empty categories), then extra seen values sorted. */
+interface ScaleInfoRow {
+    value: string;
+    /** TOTAL occurrences over the accepted model (v0.8 tier: not mask-aware). */
+    count: number;
+    /** Palette slot from `categoricalIndex` (-1 = empty palette). */
+    colorIndex: number;
+}
+/** `getScaleInfo` payload: the active Scale descriptor plus its resolved
+ * numeric domain (sequential/diverging) or legend rows (categorical). */
+interface ScaleChannelInfo<N = Record<string, unknown>> {
+    scale: Scale<string, N> | Scale<number, N>;
+    /** Resolved numeric domain; omitted while unresolvable (no data/metric). */
+    domain?: readonly [number, number];
+    /** Categorical rows; omitted for sequential/diverging scales. */
+    rows?: readonly ScaleInfoRow[];
+}
+/** §9.2 revision-aware service seam (expansion since v0.5, search since S11). */
+interface GraphServices<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /**
+     * Ego-expansion resolver for `expandNode` / `SubgraphSpec.hops`. Default:
+     * the built-in LOCAL service — it walks the core's §7.1 adjacency over the
+     * accepted model, INCLUDING currently out-of-scope nodes (zero config,
+     * zero network; the core still never fetches).
+     */
+    expansion?: ExpansionService<N, E>;
+    /**
+     * §16.2 path resolver for `findPath`. Default: the built-in LOCAL
+     * unweighted BFS over the loaded VISIBLE edge list, respecting
+     * PathOptions.direction. Revision-aware: a result arriving after a
+     * dataset replacement is discarded at admission (S12-T08).
+     */
+    path?: PathService;
+    /**
+     * §16.5 search resolver for `instance.search`. Default: the built-in LOCAL
+     * indexed service over the accepted model plus the host's declared
+     * `searchIndex` fields (id-only when never declared — it never guesses
+     * attr names; zero config, zero network). Custom services plug in
+     * server-side search (Omnigraph B.7) with the same instance-side
+     * correctness: RequestContext, revision-keyed caching, supersede
+     * cancellation, stale rejection at admission.
+     */
+    search?: SearchService<N>;
+}
+interface CreateGraphInstanceOptions<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** Called once per mount; a re-attach constructs a fresh engine (§6). */
+    engine: EngineFactory;
+    /** Fit the camera once when the first data-bearing commit reaches a fresh engine. Default true. */
+    fitViewOnFirstData?: boolean;
+    /** §9.2 revision-aware services (expansion + §16.5 search). */
+    services?: GraphServices<N, E>;
+    /**
+     * §16.5 node attr fields the DEFAULT search service indexes (ids always;
+     * absent = id-only — the service never guesses attr names). CONSTRUCTION-
+     * ONLY per the spec's host construction options (D7): read once here;
+     * changing it requires a keyed remount / replacement instance. A runtime
+     * `applyHostUpdate` attempt is ignored with a one-shot warning.
+     */
+    searchIndex?: readonly string[];
+    /**
+     * §16.14 undo/redo (S9-T20). Default true. `false` makes the history
+     * surface inert (record/undo/redo no-ops, depths stay 0); an object sets
+     * the stack bound (default {@link HISTORY_LIMIT_DEFAULT} entries).
+     */
+    history?: boolean | {
+        limit?: number;
+    };
+    /**
+     * §8 image-atlas resolver seam (S10): owns authenticated fetch/caching for
+     * one `nodeImage` ref. Default: plain `fetch(ref)` for public URLs.
+     * Injectable for tests and authenticated hosts.
+     */
+    imageResolver?: ImageResolver;
+}
+/**
+ * `expandNode` outcome (§9.2/§16.3):
+ *  - `{ added }` — the admitted result merged; `added` counts the nodes it
+ *    made newly visible in the current scope.
+ *  - `{ noop: true }` — every returned neighbor was already visible in the
+ *    current scope (T17); no session was opened, nothing changed.
+ *  - `{ coalesced: true }` — reserved. v0.5 same-id coalescing hands the
+ *    SECOND caller the IDENTICAL in-flight promise, so both callers observe
+ *    the primary call's `{added}`/`{noop}` result instead of this marker.
+ */
+type ExpandNodeResult = {
+    added: number;
+} | {
+    coalesced: true;
+} | {
+    noop: true;
+};
+/**
+ * §9.2 expansion bookkeeping: one committed expansion overlay. Data-merging
+ * batches carry the request id (overlayId + batch ids) and provenance into
+ * ingestion so abort, rollback, and removeOverlay remove the exact
+ * contribution they own.
+ */
+interface ExpansionOverlayRecord {
+    overlayId: string;
+    requestId: string;
+    /** Node ids this expansion revealed into the visible scope. */
+    revealedIds: readonly NodeId[];
+    /** Service-supplied provenance (single-response or stream header). */
+    provenance?: unknown;
+}
+/**
+ * §14 overlay label lane subscriptions. Two channels with distinct cadences:
+ *  - `subscribeCandidates` fires ONLY when the candidate SET (ids/text/forced)
+ *    changes — the throttled re-rank. React re-renders label content here.
+ *  - `subscribePositions` fires on scheduler ticks (host `onFrame`) with fresh
+ *    x/y for the SAME set — imperative transform writes, NO React re-render.
+ * Both replay the current state synchronously on subscribe. The emitted array
+ * and its placement objects are REUSED across position ticks — copy if you
+ * need a snapshot.
+ */
+interface LabelSubscriptions {
+    subscribeCandidates(cb: (list: readonly LabelPlacement[]) => void): () => void;
+    subscribePositions(cb: (list: readonly LabelPlacement[]) => void): () => void;
+}
+interface GraphInstance<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** Vanilla zustand store — the single observable state surface (§6.3). */
+    readonly store: StoreApi<GraphStoreState>;
+    /** §14 DOM label lane (overlay scheduler output). */
+    readonly labels: LabelSubscriptions;
+    /** Atomic host transaction: one store publication, at most one engine commit (§6). */
+    applyHostUpdate(update: GraphHostUpdate<N, E>): void;
+    /**
+     * §7.5 revisioned ingestion: begin a bounded, cancellable session against an
+     * explicit `datasetKey` and `baseModelRevision` (compare-and-set; mismatch
+     * throws 'stale-revision'). Overlay sessions must name the CURRENT
+     * datasetKey; replace sessions may establish a new one and are always
+     * atomic.
+     *
+     * T16 rule: while a declarative data source is actively driving (a snapshot
+     * was applied through `applyHostUpdate` and has not been superseded by a
+     * committed replace session), `purpose:'replace'` is rejected at begin with
+     * a TypeError — two writers may not race for the base. Overlay ingestion
+     * stays allowed alongside a declarative base.
+     *
+     * Every session admission/publication is serialized through the
+     * instance-local acceptance queue; arrival there is the global admission
+     * order (§7.5).
+     */
+    beginIngest(opts: BeginIngestOptions): IngestSession<N, E>;
+    /**
+     * §7.5: atomically remove exactly one committed overlay — re-runs collision
+     * and endpoint resolution, promotes formerly shadowed rows from surviving
+     * overlays, advances model/render revisions, and releases the overlayId for
+     * deliberate reuse. Unknown ids are an idempotent `{ removed: false }`.
+     */
+    removeOverlay(overlayId: string): {
+        removed: boolean;
+    };
+    /** Committed overlay ids for the current dataset (§7.5). */
+    getOverlayIds(): readonly string[];
+    attach(container: HTMLElement): Promise<void>;
+    detach(): void;
+    destroy(): void;
+    /**
+     * §15 typed events: listeners run SYNCHRONOUSLY in registration order; the
+     * control's preventDefault() cancels ONLY the built-in follow-up (click
+     * selection, drag pin), never other listeners.
+     */
+    on<K extends GraphEventName>(name: K, cb: (payload: GraphEventMap<N, E>[K], control: GraphListenerControl) => void): () => void;
+    fitView(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setViewport(v: Partial<ViewportState>): void;
+    /**
+     * §16 focus neighborhood (T10): keep the v0.1 camera behavior
+     * (setFocusedIndex + zoomToIndex) and RETURN the 1-hop neighbor ids
+     * (engine adjacency when available, else the core CSR adjacency).
+     *
+     * Documented compromise: the engine exposes ONE highlight channel until S10
+     * styling lands, so the neighbor ring is pushed through setSelectedIndices
+     * ONLY when that cannot lie about real selection state — selection empty
+     * and uncontrolled. The ring is a visual, never a store write; the next
+     * selection push overwrites it. Opt out via `highlightNeighbors: false`.
+     * `hops` is reserved at 1 until multi-hop lands.
+     */
+    focusNode(id: NodeId, opts?: {
+        highlightNeighbors?: boolean;
+        hops?: 1;
+    }): readonly NodeId[];
+    /**
+     * §14/§15 typed context-menu channel, opened from a DOM presenter. Label
+     * divs are `pointerEvents: 'auto'` by design (click-to-focus), so a
+     * right-click on one never reaches the engine canvas — without this seam
+     * the nodes prominent enough to carry labels are exactly the ones whose
+     * right-click falls through to the browser's native menu. Emits the SAME
+     * 'contextMenu' event the canvas gesture produces; `screen` is
+     * container-relative CSS px (the §15 payload contract). Unknown ids are a
+     * silent no-op (a stale label racing a model swap is data, not an error).
+     */
+    requestNodeContextMenu(id: NodeId, screen: readonly [number, number]): void;
+    setSelection(ids: readonly NodeId[] | SelectionState): void;
+    selectNodes(ids: readonly NodeId[]): void;
+    selectEdges(ids: readonly EdgeId[]): void;
+    /** §16.2 group namespace (S12-T02): validate against the CURRENT resolved
+     * groups (unknown ids dropped, duplicates collapse) and store in
+     * groups-array order — the group analog of accepted-base ordering. Never
+     * touches the node/edge namespaces; the group namespace is always
+     * instance-owned (§6.4 controlled selection covers nodes only). */
+    selectGroups(ids: readonly string[]): void;
+    /** Expand to the 1-hop neighborhood of `id` (or of the current selection). */
+    selectNeighbors(id?: NodeId): void;
+    selectAll(): void;
+    invertSelection(): void;
+    clearSelection(): void;
+    /**
+     * §16.2 lasso (S6-T05): resolve the SCREEN-coordinate polygon to node ids
+     * via `engine.pointsInPolygon`, drop hidden ids, then replace (default) or
+     * union (`additive`) the node selection through the same §6.4 ownership
+     * path as every other mutator (controlled → intent only). Returns the
+     * resolved lasso ids (accepted-base order) regardless of ownership; empty
+     * when the engine is not ready or lacks `pointsInPolygon`.
+     */
+    selectWithinPolygon(screenPolygon: readonly [number, number][], opts?: {
+        additive?: boolean;
+    }): readonly NodeId[];
+    /** Pure fallback-route query: the accepted edge within pick tolerance of a
+     * SCREEN point. Null on the native route, while picking is disarmed (sim
+     * hot), or when nothing is in range. */
+    pickEdgeAt(screen: readonly [number, number]): AcceptedEdge<E> | null;
+    /** Fallback-route hover sample: writes `hover.edgeId` and emits 'edgeHover'
+     * on transitions (identical payloads to the native route). No-op (null) on
+     * the native route. */
+    sampleEdgeHover(screen: readonly [number, number]): AcceptedEdge<E> | null;
+    /** Fallback-route click resolution: emits 'edgeClick' when a link is within
+     * tolerance. No-op (null) on the native route. */
+    sampleEdgeClick(screen: readonly [number, number]): AcceptedEdge<E> | null;
+    hideNodes(ids: readonly NodeId[]): void;
+    showNodes(ids: readonly NodeId[]): void;
+    showAll(): void;
+    pinNode(id: NodeId, xy?: readonly [number, number]): void;
+    unpinNode(id: NodeId): void;
+    clearPins(): void;
+    /** §16.3 PERSISTENT pins (S12-T09): pin ids AT THEIR CURRENT POSITION via
+     * engine.setPinnedIndices — no position payload in v0.10. Independent of
+     * transient drag pinning (`pins`): the engine receives the UNION of both
+     * slices, so releasing a drag pin leaves a persistent pin held. §6.4
+     * ownership mirrors groups: once the host supplies `pinnedNodeIds` (null
+     * included) the ops fire the 'pinnedChange' intent instead of writing.
+     * Unknown ids drop; departed ids prune through the ownership path on
+     * model changes (R-16.3-25). */
+    pinNodes(ids: readonly NodeId[]): void;
+    /** Release persistent pins (see {@link pinNodes}); unpinned ids no-op. */
+    unpinNodes(ids: readonly NodeId[]): void;
+    /** Add one group definition (same §16.3 acyclic/singly-parented validation as the
+     * `groups` prop — a violating spec is ONE 'config-error' and a no-op). */
+    groupNodes(spec: GroupSpec): void;
+    /** Remove one group definition; its id prunes from SelectionState.groupIds
+     * through the ownership path. Unknown ids no-op (dev-mode warning). */
+    ungroup(groupId: string): void;
+    /** Collapse/expand one group as a §7.2 structural diff. Works on manual
+     * groups AND groupBy-derived groups (the residue toggle). Same-value
+     * calls are exact no-ops (zero publishes, zero commits). */
+    setGroupCollapsed(groupId: string, collapsed: boolean): void;
+    /**
+     * Folds `id`'s neighbourhood into `id`. Members default to the anchor's
+     * neighbours in the CURRENT render model that no representative has
+     * claimed yet — first fold wins, so folding two adjacent hubs never fights
+     * over a shared neighbour and never needs a leaf-only restriction. Pass
+     * `memberIds` to fold an explicit set instead (unknown ids and ids already
+     * claimed elsewhere drop; an id that is an ANCESTOR of the anchor is
+     * rejected, since that would close a containment cycle).
+     *
+     * One publish and at most one structural commit (E1). A no-member fold is
+     * an exact no-op. Records a §16.14 'folds' history step.
+     */
+    foldNode(id: NodeId, opts?: {
+        memberIds?: readonly NodeId[];
+    }): void;
+    /** Unfolds `id`, returning its members to the scene as a §7.2 structural
+     * diff. Unknown or unfolded ids are exact no-ops. */
+    unfoldNode(id: NodeId): void;
+    /** The members `id` currently stands for, or null when it is not folded.
+     * Membership is the DECLARED set — members that have since left the model
+     * are reported but simply do not draw. */
+    getFold(id: NodeId): {
+        memberIds: readonly NodeId[];
+    } | null;
+    /** Current stage-4 clusters over the physical scene: ordered keys, member
+     * ids, the force center labels anchor to while hot, and the settled
+     * centroid (null until a §7.1 readback or a fixed-layout commit). Empty
+     * when no `clusters` spec is active. Clusters synthesize nothing — the
+     * scene is byte-identical with and without a spec (R-16.3-17/19). */
+    getClusters(): readonly ResolvedCluster[];
+    /** R-16.3-18: resolve a cluster (by key) to its MEMBER node ids and write
+     * them into SelectionState.nodeIds through the standard §6.4 ownership
+     * path — clusters have no id namespace of their own in selection.
+     * `additive` unions with the current node selection. Unknown keys no-op. */
+    selectCluster(key: string, opts?: {
+        additive?: boolean;
+    }): void;
+    /**
+     * §9.2 isolate: hard-scope the graph to the CURRENT node selection —
+     * `subgraph: { seedIds: selection.nodeIds }` through the SAME path as the
+     * host-update prop. No-op when nothing is selected. Ownership note (v0.5):
+     * `subgraph` is UNCONTROLLED-ONLY — always instance-owned; the prop and
+     * this method write the same state, last writer wins.
+     */
+    isolateSelection(): void;
+    /** §9.2: clear the hard scope (`subgraph: null`) — the full accepted model
+     * returns with cached positions (§9.4-style identity for kept ids). */
+    resetIsolation(): void;
+    /**
+     * §9.2/§16.3 ego-expansion of `id` (default 1 hop) through the configured
+     * ExpansionService. The result is gated by admission (declared revision
+     * dependencies + dataset lineage + seed existence — abort is only an
+     * optimization) and merges through ONE awaited atomic overlay
+     * IngestSession carrying the request id; a discard/rejection leaves the
+     * graph untouched ('service-aborted' info / 'service-error' error
+     * diagnostic; the promise rejects, the 'error' event never fires). Within
+     * one valid scope revision a second same-id call while one is in flight
+     * returns the IDENTICAL promise (one service call serves both); distinct
+     * ids run concurrently. Under an active hard scope, revealed neighbors
+     * join the resolved scope (accretion) in the same commit.
+     */
+    expandNode(id: NodeId, opts?: {
+        hops?: number;
+    }): Promise<ExpandNodeResult>;
+    /**
+     * Undoes `id`'s own expansions — the navigation Back button, NOT a
+     * containment operation. Aborts `id`'s pending expansion AND explicitly
+     * removes the overlays its past expansions committed (plus their scope
+     * accretion). Committed overlay DATA otherwise persists per §7.5 until
+     * removeOverlay / a replacing snapshot; this IS that explicit removal for
+     * expansion overlays.
+     *
+     * On a node that was never expanded from, this does nothing — there is no
+     * record to pop. To hide a node's neighbourhood behind it on a freshly
+     * loaded graph, that is {@link foldNode}: one word for containment, a
+     * different word for navigation history.
+     */
+    retractExpansion(id: NodeId): void;
+    /** §9.2 expansion bookkeeping for `id`: committed overlay records with
+     * request id, provenance, and the ids each expansion revealed. */
+    getExpansionOverlays(id: NodeId): readonly ExpansionOverlayRecord[];
+    /**
+     * Run the configured SearchService (default: the built-in local indexed
+     * service). The instance creates the `RequestContext`, caches results by
+     * `serviceCacheKey` over EXACTLY the service's declared revision
+     * dimensions ({@link SEARCH_CACHE_LIMIT}-entry LRU; a second call with an
+     * equal key while one is in flight coalesces onto the same service call),
+     * cancels superseded work (a NEWER query aborts the older in-flight call —
+     * the older promise rejects `OrbitOperationError {code:'aborted'}`), and
+     * rejects stale results at admission (declared revision drift or dataset
+     * lineage change → the same typed 'aborted' rejection with a distinct
+     * staleness message; the store is untouched). A successful search
+     * publishes `store.search = {query, results}` — `node` populated for
+     * in-model ids — in ONE store publication. Search NEVER changes
+     * scope/filter semantics and never fetches graph data (§16.5).
+     */
+    search(query: string, opts?: {
+        limit?: number;
+    }): Promise<readonly SearchResult<N>[]>;
+    /** Clear `store.search` to null (e.g. the <GraphSearch> input emptied). */
+    clearSearch(): void;
+    /** §16.2 path query + atomic emphasis (S12-T08): resolves via the path
+     * service (local BFS default); null = unreachable (a RESULT). Emphasis is
+     * session-local — released by clearPath, any selection mutation, undo/
+     * redo, or a scene rebuild; never a history step; never serialized. */
+    findPath(sourceId: NodeId, targetId: NodeId, options?: PathOptions): Promise<PathResult | null>;
+    clearPath(): void;
+    getActivePath(): PathResult | null;
+    /**
+     * §16.5 result contract (T07): a result id in the current rendered scene
+     * AND §9.1 mask-visible is focused (`focusNode`) → `{status:'focused'}`.
+     * Otherwise classification ONLY — 'not-loaded' (absent from the accepted
+     * model), 'out-of-scope' (in the model but outside the hard scope),
+     * 'filtered' (in the scene but mask-hidden). Never mutates scope or
+     * filters — the host reacts explicitly (§16.5).
+     */
+    activateSearchResult(result: SearchResult<N>): SearchActivation;
+    pauseSimulation(): void;
+    resumeSimulation(): void;
+    isSimulationRunning(): boolean;
+    /** §16.1 screenshot: delegates to the engine; null when unsupported/not ready. */
+    captureScreenshot(): Promise<Blob | null>;
+    /**
+     * §15.1 binding-detected reduced-motion media preference. The EFFECTIVE
+     * value is `accessibility.reducedMotion ?? v` — when reduced, camera
+     * durations (fitView/setViewport/focusNode) coerce to 0.
+     */
+    setReducedMotion(v: boolean | undefined): void;
+    /**
+     * The crossfilter session facade, or null until the `crossfilter` prop has
+     * configured dimensions over an accepted base. Delegates to the
+     * typed-column engine; `setBrush` routes visibility deltas into the §9.1
+     * soft mask (buffers-only commit, zero relayout) and resolves after the
+     * publish. Brush slot deltas are BASE indices; under a hard scope
+     * out-of-scope rows have no scene slot and simply do not mask anything.
+     */
+    getCrossfilterSession(): CrossfilterSession | null;
+    /**
+     * Play a brush window across a numeric/temporal dimension's domain through
+     * the crossfilter mask fast path (zero relayout). One playing dimension at
+     * a time — a second play supersedes; a USER `setBrush` on the playing key
+     * pauses playback. The whole play session coalesces into ONE history entry.
+     */
+    playTimeline(key: string, playback?: Partial<TimelinePlayback>): void;
+    pauseTimeline(): void;
+    /** Undo the most recent uncontrolled mutation entry (selection / hidden /
+     * pins / scope / brushes). Returns false when there is nothing to undo. */
+    undo(): boolean;
+    /** Re-apply the most recently undone entry. False when nothing to redo. */
+    redo(): boolean;
+    /**
+     * Serialize the exploration state (§16.14): camera, selection, hidden ids,
+     * isolation, groups (manual specs verbatim; under `groupBy` only collapsed
+     * `{key, collapsed}` pairs — membership recomputes on restore), pins,
+     * folds, layout, crossfilter brushes in declaration order, the Scale-valued
+     * styling subset, and the host's `dataRef` verbatim. The predicate `filter`
+     * and §16.3 expansion records are never serialized. The sync form carries
+     * no positions: reproduction is best-effort via the layout descriptor.
+     */
+    getViewState(opts?: {
+        includePositions?: false;
+    }): GraphViewState;
+    /**
+     * Async form: additionally embeds quantized coordinates for the VISIBLE
+     * (post-mask) set, read once from the engine (per-event readback, ADR-001).
+     * Restores as a frozen fixed-equivalent — pixel-faithful regardless of
+     * engine nondeterminism. Past `maxPositions` (default 100 000) the call
+     * rejects `export-materialization-too-large`; persist the layout through
+     * the export lane and reference it from `dataRef` instead of inlining.
+     */
+    getViewState(opts: {
+        includePositions: true;
+        maxPositions?: number;
+    }): Promise<GraphViewState>;
+    /**
+     * Atomically restore a serialized view (§16.14). NEVER partially applies:
+     * structural validation and the version gate run first (reject whole with
+     * one 'invalid-view-state' diagnostic); then the dataRef canonical
+     * comparison — a mismatch fires the 'viewStateMismatch' event INSTEAD of
+     * applying, and restoration proceeds only on an `ignoreMismatch` re-call.
+     * The apply is ONE history transaction through the same command appliers
+     * undo/redo uses, so a restore is itself undoable. Embedded positions
+     * apply as a frozen fixed-equivalent (one replay-style commit, then the
+     * simulation pauses — a later explicit layout change or reheat unfreezes).
+     * A state touching a §6.4 controlled slice (or styling, once a restore
+     * callback exists) resolves 'missing-restore-callback' until the aggregate
+     * protocol is registered.
+     */
+    setViewState(raw: unknown, opts?: {
+        ignoreMismatch?: boolean;
+        isDataRefEqual?: (stored: JsonValue | undefined, current: JsonValue | undefined) => boolean;
+    }): Promise<SetViewStateResult>;
+    /**
+     * Picture exports. 'png' delegates to {@link captureScreenshot} (typed
+     * rejection when the engine lacks the capability). 'svg' renders the
+     * VISIBLE (post-mask) set through the engine-free exporter: one per-event
+     * position readback, colors/sizes from the same projectors the commits
+     * use, labels from the current candidate set, in space coordinates with a
+     * padded viewBox. Above `maxSvgElements` (default 50 000) it rejects
+     * `export-too-large` — pass `fallback: 'raster-hybrid'` to instead receive
+     * a PNG base layer with a vector label overlay.
+     */
+    exportImage(format: 'png'): Promise<Blob>;
+    exportImage(format: 'svg', opts?: {
+        maxSvgElements?: number;
+        fallback?: 'raster-hybrid';
+    }): Promise<string>;
+    /**
+     * Bounded object export of the pinned model: 'visible' (default) is the
+     * mask-visible roster with both-endpoint-visible edges; 'accepted' the
+     * full model. Rejects `export-materialization-too-large` past `limit`
+     * (default 100 000 rows) BEFORE allocating — the stream is the remedy.
+     */
+    exportData(scope?: 'visible' | 'accepted', opts?: {
+        limit?: number;
+    }): Promise<{
+        nodes: readonly GraphNode<N>[];
+        edges: readonly AcceptedEdge<E>[];
+    }>;
+    /** Memory-bounded JSONL: one `{"kind":"node"|"edge","value":…}` line per
+     * entity over ONE pinned revision — a mid-stream commit never mixes
+     * epochs. Closing the generator releases the pin. */
+    exportDataStream(scope?: 'visible' | 'accepted'): AsyncGenerator<string, void, undefined>;
+    /** Bounded id → [x, y] map from one position readback (§7.1 per-event). */
+    exportLayout(opts?: {
+        limit?: number;
+    }): Promise<ReadonlyMap<NodeId, readonly [number, number]>>;
+    /** Memory-bounded `{"id","x","y"}` JSONL over one pinned readback. */
+    exportLayoutStream(): AsyncGenerator<string, void, undefined>;
+    /**
+     * §11 legend surface: the active Scale on a styling channel plus its
+     * resolved domain (sequential/diverging — resolved through the SAME frozen
+     * DomainStore coordinate the projection uses) or categorical legend rows
+     * (declared-domain order first including empty categories, then extra seen
+     * values sorted; counts are v0.8-tier TOTALS over the accepted model, not
+     * mask-aware). Null when the channel is not scale-valued.
+     */
+    getScaleInfo(channel: 'nodeColor' | 'nodeSize'): ScaleChannelInfo<N> | null;
+    /**
+     * §12 metric read for one node id via the core id→index map (never a
+     * public million-entry Map). Null for unknown ids/metrics and §8-null
+     * values; lazily computes the degree family on first use.
+     */
+    getMetricValue(metric: MetricName, id: NodeId): number | null;
+    getRevisions(): Revisions;
+    getDiagnostics(): readonly GraphDiagnostic[];
+    getNode(id: NodeId): GraphNode<N> | undefined;
+    /** Accepted edge by id — the symmetric partner of {@link getNode}, and the
+     * way a hover/selection consumer resolves `store.hover.edgeId` or
+     * `selection.edgeIds` to real records. Undefined for unknown ids. */
+    getEdge(id: EdgeId): AcceptedEdge<E> | undefined;
+    /** Scene ids that are §9.1 mask-visible (scope ∧ mask), scene order. */
+    getVisibleNodeIds(): readonly NodeId[];
+    /** Scene roster: scope applied, mask NOT applied — the §15.1 navigator's
+     * entry list, which must still LIST masked/hidden nodes and expose their
+     * state in text rather than dropping them. */
+    getSceneNodeIds(): readonly NodeId[];
+    /** §15.1 accessibility config stash (navigator/live-region consumers). */
+    getAccessibility(): AccessibilityConfig<N> | undefined;
+}
+/** §16.14: consecutive same-dimension brush moves within this window merge
+ * into one history entry (scrub/drag coalescing). */
+declare const BRUSH_HISTORY_COALESCE_MS = 500;
+/** §16.6 timeline defaults (S9-T10). */
+declare const TIMELINE_TICK_MS_DEFAULT = 100;
+declare const TIMELINE_STEP_DEFAULT = 0.01;
+/** §16.5 search defaults (S11-T06). */
+declare const SEARCH_LIMIT_DEFAULT = 20;
+declare const SEARCH_CACHE_LIMIT = 32;
+declare function createGraphInstance<N = Record<string, unknown>, E = Record<string, unknown>>(opts: CreateGraphInstanceOptions<N, E>): GraphInstance<N, E>;
+
+/**
+ * §14 DOM label lane — pure candidate selection (S7-T01/T16).
+ *
+ * `selectLabelCandidates` is a pure, deterministic ranking function: no engine,
+ * no DOM, no store. The instance-side overlay scheduler calls it on THROTTLED
+ * re-rank triggers only (viewport idle, model change, config change, settle) —
+ * NEVER per frame. Positions are the reconciler's CPU cache (space coords);
+ * per-frame work elsewhere is a pure O(k) projection of the winners.
+ *
+ * Selection rules (§14):
+ *  - Zoom-LOD: below `minZoom` the lane is empty EXCEPT `showFor` ids, which
+ *    bypass the zoom gate but stay viewport-culled.
+ *  - `showFor` claims capacity FIRST in accepted-base order. When the
+ *    in-viewport `showFor` set alone exceeds capacity k, accepted-base order
+ *    wins deterministically and `overloadCount` reports the omissions (one
+ *    `label-overload` diagnostic upstream — no winner churn).
+ *  - Remaining capacity fills with viewport-visible nodes ranked by
+ *    `getWeight` (else degree), ties broken by accepted-base order.
+ *  - Visibility comes from the engine's `pointsInRect` when available, else a
+ *    CPU cull of cached positions through the viewport transform. Nodes with
+ *    unknown (NaN) cached positions are unplaceable on the CPU path.
+ */
+
+/** A capacity winner before per-frame projection assigns screen coordinates. */
+type LabelCandidate = Omit<LabelPlacement, 'x' | 'y'>;
+/** §14 default ranked-candidate cap. */
+declare const LABEL_MAX_VISIBLE_DEFAULT = 64;
+/** §14 policy maximum for `maxVisible`. */
+declare const LABEL_MAX_VISIBLE_CAP = 1024;
+interface LabelCandidateViewport {
+    zoom: number;
+    /** Visible screen rect `[x0, y0, x1, y1]` (CSS px). Omit = size unknown → no viewport cull. */
+    screenRect?: readonly [number, number, number, number];
+    /** space → screen projection for the CPU cull path (null = not projectable). */
+    spaceToScreen?: (p: readonly [number, number]) => readonly [number, number] | null;
+}
+interface SelectLabelCandidatesArgs<N = Record<string, unknown>> {
+    scene: RenderScene;
+    /**
+     * Accepted nodes in accepted-base order. Under the 'rebuild' index policy
+     * (§7.3) scene index i IS accepted-base position i, so `nodes[i]` is the
+     * node behind `scene.idByIndex[i]`.
+     */
+    nodes: readonly GraphNode<N>[];
+    /** Space positions from the CPU cache (2*count floats; NaN pair = unknown). */
+    positions: Float32Array;
+    viewport: LabelCandidateViewport;
+    config: LabelConfig<N>;
+    /** Degree of scene index i — the default ranking weight. */
+    degreeOf?: (index: number) => number;
+    /**
+     * Engine-accelerated visibility: point indices inside a screen rect. A null
+     * return (engine not ready) falls back to the CPU cull.
+     */
+    pointsInRect?: (rect: readonly [number, number, number, number]) => number[] | null;
+}
+interface LabelCandidateResult {
+    /** Capacity-ordered winners: forced (accepted-base order) then ranked fills. */
+    placements: readonly LabelCandidate[];
+    /** In-viewport `showFor` ids omitted because they alone exceed capacity. */
+    overloadCount: number;
+}
+declare function selectLabelCandidates<N = Record<string, unknown>>(args: SelectLabelCandidatesArgs<N>): LabelCandidateResult;
+
+/**
+ * §7.1/§13 CSR adjacency over columnar link buffers.
+ *
+ * Pure, engine-free helpers shared by local expansion (§9.2), incident-edge
+ * dirtying (§9.1), and the engine-facing `neighborIndices` interaction helper
+ * (§13). Build is O(L) via two counting passes over the flat
+ * `[src0, tgt0, src1, tgt1, …]` link buffer — no comparison sort and no
+ * per-link allocation (the only allocations are the CSR arrays plus one
+ * point-sized cursor array).
+ *
+ * The adjacency is UNDIRECTED: every link contributes one neighbor entry per
+ * endpoint slot, so parallel links repeat, and a self-loop (a, a) lists `a`
+ * twice under point a — once per endpoint slot.
+ */
+interface Adjacency {
+    /**
+     * Length `pointCount + 1`; the neighbors of point `i` live at
+     * `neighbors[offsets[i] … offsets[i + 1])`.
+     */
+    readonly offsets: Uint32Array;
+    /** Length `links.length` (two entries per link — one per direction). */
+    readonly neighbors: Uint32Array;
+}
+/**
+ * Builds a CSR adjacency from a flat `[src, tgt]` pair buffer.
+ *
+ * @param links flat `[src0, tgt0, src1, tgt1, …]` point-index pairs
+ * @param pointCount number of points; every endpoint must be `< pointCount`
+ */
+declare function buildAdjacency(links: Uint32Array, pointCount: number): Adjacency;
+/**
+ * Zero-copy neighbor list of one point: a `subarray` VIEW into
+ * `adj.neighbors` — do not mutate, and do not hold across a rebuild.
+ */
+declare function neighborsOf(adj: Adjacency, index: number): Uint32Array;
+
+/**
+ * §13/§15 CPU link-pick fallback: a uniform grid over ALL links in SPACE
+ * coordinates (cell ≈ median link length), used when the engine lacks native
+ * `linkAt` (`capabilities.linkPicking === false`). Backs
+ * `onEdgeClick`/`onEdgeHover` via the §7.4 index→edge mapping.
+ *
+ * Coordinate contract: everything here is SPACE coordinates. Callers invert
+ * the affine `Viewport` (space = (screen − center)/zoom + [x, y]) and pass a
+ * space-unit tolerance (`tolerancePx / zoom`).
+ *
+ * Invalidation contract (normative — wave 2 enforces arming):
+ * - The grid indexes a POSITION SNAPSHOT (the §7.1 `posBuf` CPU mirror as of
+ *   the build call). It NEVER observes live simulation positions: while the
+ *   simulation is hot (alpha above threshold) or an animated `setLayout()`
+ *   transition runs, picking is DISARMED by the caller; on settle one
+ *   per-event `getPositions` refreshes the mirror and the grid is rebuilt.
+ * - Rebuild ONLY on structural change (link buffer changed) or position
+ *   sync. The grid is invariant under camera moves and visibility-mask
+ *   changes: the §9.1 mask is applied per candidate at QUERY time via the
+ *   optional `visible` callback (pure pass-through until S9 wires the real
+ *   mask through it).
+ *
+ * Build uses two counting-sort passes into CSR grid arrays (`cellOffsets`,
+ * `cellLinkIds`). Each segment is inserted with a supercover grid traversal,
+ * so a link contributes O(cols + rows) cells in the worst case instead of
+ * every cell in its O(cols * rows) axis-aligned bounding box. There is no
+ * comparison sort or per-link allocation beyond the CSR arrays (plus
+ * O(cells) cursor and O(links) query stamps). Links with a non-finite endpoint
+ * (NaN-tombstoned points, §13) are excluded and can never be returned. A hard
+ * CSR-entry cap deterministically degrades pathological builds to exact O(L)
+ * query scans with no cell-link payload.
+ */
+/** §9.1 visibility mask applied per candidate at query time. */
+type LinkVisibilityMask = (linkIndex: number) => boolean;
+/**
+ * Read-only view of the built grid (diagnostics/tests). The typed arrays are
+ * the LIVE internal buffers — never mutate them.
+ */
+interface LinkPickGridSnapshot {
+    /** `scan` means the CSR cap tripped and queries use an exact full scan. */
+    readonly mode: 'grid' | 'scan';
+    readonly cellSize: number;
+    readonly cols: number;
+    readonly rows: number;
+    readonly minX: number;
+    readonly minY: number;
+    /** CSR: length `cols * rows + 1`; `[0, 0]` in `scan` mode. */
+    readonly cellOffsets: Uint32Array;
+    /** CSR segment-supercover pairs; empty in `scan` mode. */
+    readonly cellLinkIds: Uint32Array;
+}
+/**
+ * Exact point→segment squared distance (shared with the query path so the
+ * grid and any external oracle agree bit-for-bit).
+ */
+declare function pointSegmentDistanceSquared(px: number, py: number, ax: number, ay: number, bx: number, by: number): number;
+declare class LinkPickIndex {
+    private grid;
+    /** Per-link visited stamps: dedupe across cells within one query. */
+    private stamps;
+    private queryStamp;
+    get isBuilt(): boolean;
+    /** Read-only grid/scan index view for diagnostics/tests; null before build. */
+    gridSnapshot(): LinkPickGridSnapshot | null;
+    /**
+     * Drops the grid: `nearestLink` reports null until the next build. Wave 2
+     * calls this on structural change / sim-hot disarm.
+     */
+    invalidate(): void;
+    /**
+     * One-shot output-sensitive build over a position snapshot: O(L + I), where
+     * I is the emitted segment-cell pairs up to `MAX_CELL_LINK_ENTRIES`; above
+     * that cap it commits exact-scan mode. Drains the chunked generator with an
+     * infinite budget so both entry points share one code path (chunked and
+     * one-shot builds are bit-identical).
+     */
+    build(positions: Float32Array, links: Uint32Array): void;
+    /**
+     * Incremental build: yields whenever `now() − sliceStart ≥ budgetMs` so a
+     * scheduler can spread the work across idle frames (§17 long-task budget).
+     * Pure generator — no rAF/timers here; the caller owns scheduling.
+     *
+     * The previous grid stays armed and queryable until the new one commits on
+     * generator completion; abandoning the iterator leaves the old grid
+     * intact. At most one build should be in flight per index — the wave-2
+     * scheduler serializes rebuilds.
+     */
+    buildChunked(positions: Float32Array, links: Uint32Array, budgetMs: number, now: () => number): IterableIterator<void>;
+    /**
+     * Nearest link within `tolerance` (space units) of the space point
+     * `(x, y)`, or null. Scans the candidate cells covering the tolerance
+     * disc's bounding box (typically the 3×3 neighborhood; more when the
+     * tolerance exceeds the cell size), applies the optional §9.1 visibility
+     * mask per candidate, then runs the exact point→segment distance test.
+     * Nearest wins; exact-distance ties break toward the LOWER link index.
+     * Returns null while unbuilt/invalidated (picking disarmed).
+     */
+    nearestLink(x: number, y: number, tolerance: number, visible?: LinkVisibilityMask): number | null;
+}
+
+/**
+ * §13/§15 edge-picking facade (S6-T07).
+ *
+ * The core commits to ONE route per mount session, read from
+ * `engine.capabilities.linkPicking` at engine-ready time — never method
+ * sniffing, and never re-evaluated (a capability record mutated after ready
+ * changes nothing):
+ *
+ *  - 'native':   the adapter delivers `onLinkClick`/`onLinkHover` host events
+ *                itself; the facade is inert (arm/disarm/queries no-op and
+ *                `pickLinkAt` returns null) and the instance maps link indices
+ *                to typed edges straight off the host events.
+ *  - 'fallback': the instance samples the pointer on the shared §15 throttle
+ *                cadence and resolves hits through a `LinkPickIndex` uniform
+ *                grid that is armed ONLY while the simulation is settled.
+ *
+ * Arming protocol (fallback route; §13):
+ *  - `arm(positions, links)` runs on simulation settle (fed by one per-event
+ *    `getPositions` readback) and on structural commits that do NOT restart
+ *    the simulation (fixed layout). The grid builds CHUNKED via
+ *    `LinkPickIndex.buildChunked` under a per-slice time budget so large link
+ *    sets never block (§17); small builds complete synchronously in the first
+ *    slice. While an initial build is in flight queries return null; a
+ *    position-sync REBUILD keeps answering from the previous grid until the
+ *    new one commits.
+ *  - `disarm()` runs on any commit that restarts the simulation: targets are
+ *    moving and the position mirror is stale, so queries return null until
+ *    the next settle re-arms.
+ *  - Rebuilds happen ONLY on structural change or position sync — the grid is
+ *    invariant under camera moves and mask changes (the §9.1 visibility mask
+ *    is applied per candidate at query time; pass-through stub until S9).
+ *
+ * Tolerance (§13): a query converts screen px to space units via
+ * `screenToSpace` of two points `EDGE_PICK_TOLERANCE_PX` apart, then uses
+ * `max(4px, half the median link width)` scaled by that factor.
+ */
+
+type EdgePickRoute = 'native' | 'fallback';
+/** Screen-space pick tolerance floor, and the probe distance used to measure
+ * the screen→space scale (§13). */
+declare const EDGE_PICK_TOLERANCE_PX = 4;
+/**
+ * Median link width in px from a projected linkWidth buffer (deterministic
+ * stride sample, cap 1024). Returns 0 for null/empty/non-finite input — the
+ * 4px floor then wins in the tolerance formula.
+ */
+declare function medianLinkWidthPx(widths: Float32Array | null): number;
+interface EdgePickingFacadeOptions {
+    /** Fixed for the facade's lifetime; read from capabilities at ready. */
+    route: EdgePickRoute;
+    /** Affine screen→space conversion; null = conversion unavailable. */
+    screenToSpace: (p: readonly [number, number]) => readonly [number, number] | null;
+    /** Median link width in px for the tolerance floor; default () => 0. */
+    medianLinkWidthPx?: () => number;
+    /** §9.1 visibility mask pass-through stub (mutable via the setter). */
+    linkVisible?: LinkVisibilityMask;
+    /** Chunked-build slice budget in ms. */
+    buildBudgetMs?: number;
+    /** Scheduler for build continuation slices (test seam). */
+    schedule?: (continueBuild: () => void) => void;
+    /** Clock for the build budget (test seam). */
+    now?: () => number;
+}
+declare class EdgePickingFacade {
+    /** The route this mount session committed to at ready. */
+    readonly route: EdgePickRoute;
+    private readonly screenToSpace;
+    private readonly medianWidthPx;
+    private readonly budgetMs;
+    private readonly schedule;
+    private readonly now;
+    private readonly index;
+    private mask;
+    /** Bumped by disarm/arm/destroy; abandons any in-flight chunked build. */
+    private generation;
+    constructor(opts: EdgePickingFacadeOptions);
+    /** True when the fallback grid is built and answering queries. */
+    get armed(): boolean;
+    /**
+     * (Re-)arm from a settled position snapshot. `positions`/`links` must be
+     * stable snapshots — the grid references them until the next rebuild.
+     * No-op on the native route.
+     */
+    arm(positions: Float32Array, links: Uint32Array): void;
+    /** Simulation went hot: drop the grid; queries null until the next settle. */
+    disarm(): void;
+    /** §9.1 mask pass-through stub: applied per candidate at query time. */
+    setLinkVisibilityMask(mask: LinkVisibilityMask | null): void;
+    /**
+     * Nearest link index within tolerance of a SCREEN point, or null when: on
+     * the native route, disarmed (sim hot / not yet settled), no conversion,
+     * or nothing in range.
+     */
+    pickLinkAt(screen: readonly [number, number]): number | null;
+    /** Abandon any in-flight build and drop the grid (session teardown). */
+    destroy(): void;
+}
+
+/**
+ * Collision-safe identity helpers for synthesized edges.
+ *
+ * Simple ids retain the documented `source→target#k` shape. The three
+ * framing characters are backslash-escaped inside endpoint components, making
+ * the concatenation injective for arbitrary JavaScript strings (including
+ * strings that themselves contain backslashes, arrows, hashes, or NULs).
+ */
+
+type EdgePairCounters = Map<NodeId, Map<NodeId, number>>;
+
+/**
+ * §7.5 revisioned ingestion — pure session/overlay bookkeeping plus the
+ * instance-local acceptance queue (S8-T01..T07).
+ *
+ * Everything here is data-structure work: no store, no engine, no DOM. The
+ * GraphInstance wires these helpers into its publication path (instance.ts).
+ *
+ * Ordering model: every admission takes a monotonically increasing ticket from
+ * the instance's AcceptanceQueue. Overlay rows are stamped with their
+ * admission ticket, and the merge folds base + overlays strictly in ticket
+ * order — arrival at the queue IS the global admission order (§7.5).
+ */
+
+/** Byte backpressure budget default: 8 MiB of admitted-but-unflushed payload. */
+declare const INGEST_MAX_PENDING_BYTES_DEFAULT = 8388608;
+/** Progressive-overlay coalesced flush latency cap default (ms). */
+declare const INGEST_MAX_FLUSH_LATENCY_MS_DEFAULT = 50;
+/** A single batch larger than `factor × maxPendingBytes` rejects outright. */
+declare const INGEST_OVERFLOW_FACTOR = 4;
+declare class AcceptanceQueue {
+    private ticket;
+    /** Depth guard: admissions made from inside a job run nested — arrival
+     * order still equals call order under synchronous execution. */
+    private depth;
+    /** Total admissions so far (the global admission-order clock). */
+    get admissions(): number;
+    /** True while a job admitted by this queue is executing. */
+    get active(): boolean;
+    /** Take the next admission-order ticket without running a job (row stamps). */
+    nextTicket(): number;
+    /**
+     * Admit a job at the tail of the global order and execute it synchronously.
+     * Exceptions propagate to the admitter (v0.5 synchronous execution).
+     */
+    admit<T>(job: () => T): T;
+}
+/** `batch.bytes` when declared, else a rough JSON estimate of the payload. */
+declare function estimateBatchBytes(batch: IngestBatch<unknown, unknown>): number;
+interface RowTally {
+    count: number;
+    samples: string[];
+}
+/** Per-session staging tallies; surfaced as diagnostics ONLY at commit (§7.5). */
+interface StagingTallies {
+    invalidNodes: RowTally;
+    duplicateNodes: RowTally;
+    invalidEdges: RowTally;
+    duplicateEdges: RowTally;
+}
+declare function newStagingTallies(): StagingTallies;
+interface StampedNode<N> {
+    /** Global admission-order ticket (queue arrival). */
+    readonly order: number;
+    readonly node: GraphNode<N>;
+}
+interface StampedEdge<E> {
+    readonly order: number;
+    readonly edge: AcceptedEdge<E>;
+}
+interface SessionContribution<N = Record<string, unknown>, E = Record<string, unknown>> {
+    readonly overlayId: string;
+    /** Session-deduped admitted node rows in admission order. */
+    readonly nodes: StampedNode<N>[];
+    /** Session-deduped admitted edge records (ids resolved) in admission order. */
+    readonly edges: StampedEdge<E>[];
+    readonly nodeIds: Set<NodeId>;
+    readonly edgeIds: Set<string>;
+    /** Exact ordered endpoint tuple → next synthesized-parallel-edge k (§5). */
+    readonly pairCounters: EdgePairCounters;
+    /** Public prefix lengths: rows before these counts have been published
+     * (progressive flush / commit); appends only grow the arrays, so a prefix
+     * is sufficient. Atomic sessions stay at 0 until commit (§7.5). */
+    publicNodeCount: number;
+    publicEdgeCount: number;
+}
+declare function newContribution<N, E>(overlayId: string): SessionContribution<N, E>;
+interface StageResult {
+    admittedNodes: number;
+    admittedEdges: number;
+}
+/**
+ * Validate and stage one batch's rows into a session contribution.
+ *
+ * §5.1-equivalent row validation WITHOUT endpoint checks — edges may arrive
+ * before nodes (§7.5): they occupy their eventual edge records here; endpoint
+ * resolution happens at merge. Within a session, duplicate ids are
+ * first-wins-dropped (tallied for commit diagnostics); cross-session
+ * collisions are the merge's shadowing concern, not staging's.
+ */
+declare function stageBatch<N, E>(contribution: SessionContribution<N, E>, batch: IngestBatch<N, E>, tallies: StagingTallies, nextOrder: () => number): StageResult;
+/** The accepted base (declarative snapshot or committed replace session). */
+interface MergeBase<N = Record<string, unknown>, E = Record<string, unknown>> {
+    datasetKey: string;
+    sourceRevision: number | string;
+    nodes: readonly GraphNode<N>[];
+    /** id → position in `nodes`. */
+    nodeIndex: ReadonlyMap<NodeId, number>;
+    /** Endpoint-resolved base edges. */
+    edges: readonly AcceptedEdge<E>[];
+    /** Replace-session bases retain edge records whose endpoints were missing
+     * at commit; a later overlay node can still resolve them (§7.5). */
+    pendingEdges: readonly StampedEdge<E>[];
+    diagnostics: readonly GraphDiagnostic[];
+}
+/** Sentinel owner key for base pending edges in `pendingBySource`. */
+declare const BASE_PENDING_KEY = "";
+interface MergeResult<N = Record<string, unknown>, E = Record<string, unknown>> {
+    accepted: AcceptedGraph<N, E>;
+    /** Overlay node rows shadowed by an earlier admission (base included). */
+    shadowedCount: number;
+    shadowedSamples: readonly string[];
+    /** Later same-id edge records dropped (first admission wins). */
+    duplicateEdgeCount: number;
+    duplicateEdgeSamples: readonly string[];
+    /** overlayId (or BASE_PENDING_KEY) → edges still awaiting an endpoint. The
+     * pending-endpoint index: these occupy edge records but never enter the
+     * engine link buffer (§7.5). */
+    pendingBySource: ReadonlyMap<string, number>;
+    pendingEdgeCount: number;
+}
+declare function baseFromAccepted<N, E>(accepted: AcceptedGraph<N, E>): MergeBase<N, E>;
+/**
+ * Build a MergeBase from a replace session's staged contribution. Edges whose
+ * endpoints exist in the session's own node set resolve immediately; the rest
+ * stay pending (they may resolve through later overlays).
+ */
+declare function baseFromContribution<N, E>(datasetKey: string, sourceRevision: number | string, contribution: SessionContribution<N, E>, diagnostics: readonly GraphDiagnostic[]): MergeBase<N, E>;
+/**
+ * Merge the accepted base with every overlay contribution's PUBLIC rows.
+ *
+ * - Node collisions: earliest admission (ticket order; base first) wins.
+ *   Later rows stay retained-but-shadowed in their contribution and are
+ *   tallied for the single count-aggregated 'overlay-node-shadowed' info
+ *   diagnostic (§7.5).
+ * - Edge ids: first admission wins; later same-id records are dropped
+ *   (tallied). An edge whose endpoints are not all present in the merged
+ *   node set is pending — it occupies its record and the pending-endpoint
+ *   accounting but is excluded from `accepted.edges` (and therefore from the
+ *   engine link buffer). Endpoints arriving later resolve it on the next
+ *   merge (same or different batch/overlay).
+ *
+ * Deterministic: output depends only on the base and the stamped rows.
+ */
+declare function mergeModel<N, E>(base: MergeBase<N, E>, overlays: readonly SessionContribution<N, E>[]): MergeResult<N, E>;
+/** Recomputed per merge: ONE count-aggregated shadow info + edge-dedupe note. */
+declare function mergeDiagnostics(merge: MergeResult<unknown, unknown>): GraphDiagnostic[];
+/**
+ * Commit-time diagnostics for one session: staging tallies plus the dangling
+ * (still-pending-endpoint) count — emitted ONLY at session commit (§7.5).
+ */
+declare function sessionCommitDiagnostics(tallies: StagingTallies, danglingCount: number, danglingSamples?: readonly string[]): GraphDiagnostic[];
+
+/**
+ * §9.2 hard subgraph scope — pure resolution over the accepted base.
+ *
+ * `resolveScope` turns a `SubgraphSpec` into the exact node/edge subset the
+ * reconciler should be fed: seeds validated against the accepted base
+ * (unknown ids dropped, duplicates collapsed), optional `hops` expansion via
+ * BFS over the §7.1 CSR adjacency of the ACCEPTED BASE (not the scene — the
+ * default expansion service walks this same index, §9.2), and edges cascaded
+ * through `cascadeEdges`, the single §9 edge-survival primitive (an edge
+ * survives iff BOTH endpoints survive) that S9's soft masks reuse.
+ *
+ * Everything here is synchronous and engine-free. The async
+ * `ExpansionService` seam (./services) exists for `expandNode`; `hops`
+ * resolution inside a host update takes this local path directly.
+ */
+
+/**
+ * THE edge-cascade primitive (§9): an edge survives iff BOTH of its
+ * endpoints survive. O(E); the only allocation is the output array, which
+ * holds references to the input edge objects (never copies).
+ *
+ * Exported for reuse by §9.1 soft masks (S9) and any other subset producer.
+ */
+declare function cascadeEdges<E>(edges: readonly AcceptedEdge<E>[], survives: (id: NodeId) => boolean): AcceptedEdge<E>[];
+/**
+ * Builds the §7.1 CSR adjacency of an accepted base: endpoints are positions
+ * in `accepted.nodes` (accepted-base order). Every accepted edge has resolved
+ * endpoints by contract (§5.1 drops dangling edges), so this cannot throw on
+ * a well-formed `AcceptedGraph`.
+ */
+declare function buildAcceptedAdjacency(accepted: AcceptedGraph<unknown, unknown>): Adjacency;
+/** Output of `resolveScope`: the exact subset to feed the reconciler (§9.2). */
+interface ResolvedScope<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** Surviving node ids (seeds + hop expansion), membership-query form. */
+    nodeIds: ReadonlySet<NodeId>;
+    /** Surviving nodes in accepted-base order (same objects, never copies). */
+    nodes: readonly GraphNode<N>[];
+    /** Edges whose BOTH endpoints survive, in accepted-base order. */
+    edges: readonly AcceptedEdge<E>[];
+}
+/**
+ * Resolves a hard-scope spec against the accepted base (§9.2).
+ *
+ * - `spec.seedIds` are validated against `accepted.nodeIndex`: ids unknown to
+ *   the accepted base are dropped, duplicates collapse to one seed.
+ * - `spec.hops` (default 0; negative/non-finite values clamp to 0, fractions
+ *   floor) expands the survivor set by BFS over the accepted-base adjacency.
+ *   This is the synchronous local path — the §9.2 default `ExpansionService`
+ *   walks the same index for `expandNode`.
+ * - `adjacency` may be a caller-cached `buildAcceptedAdjacency(accepted)`
+ *   result; pass `null` to have one built on demand (only when `hops > 0`
+ *   and there are surviving seeds — hop-0 resolution never builds it).
+ * - Output preserves accepted-base order for both nodes and edges; edges are
+ *   cascaded through {@link cascadeEdges}.
+ */
+declare function resolveScope<N, E>(accepted: AcceptedGraph<N, E>, spec: SubgraphSpec, adjacency: Adjacency | null): ResolvedScope<N, E>;
+
+/**
+ * §9.2 revision-aware services — pure sequencing/admission/caching helpers
+ * plus the built-in local expansion service.
+ *
+ * The correctness gate is `admitServiceResult`: a result is admitted only if
+ * every revision dimension the service DECLARED is unchanged since the call
+ * was issued; undeclared dimensions never invalidate (so e.g. the local
+ * expansion service, declaring only 'source', survives unrelated model/scope
+ * advances from other overlay publications). Abort is an optimization —
+ * admission is the gate.
+ *
+ * Cache keys include service identity, canonical-JSON request parameters,
+ * `datasetKey`, and EXACTLY the declared revision dimensions' current values.
+ *
+ * Nothing here touches the engine, the store, or the DOM; the instance wires
+ * these primitives to its acceptance queue.
+ */
+
+/** Current value of each §9.2 revision dimension (a Revisions subset). */
+interface RevisionSnapshot {
+    source: number | string | null;
+    model: number;
+    scope: number;
+}
+/** Monotonic instance-process-unique request id (deterministic prefix for tests). */
+declare function nextRequestId(prefix?: string): string;
+interface CreateRequestContextArgs {
+    datasetKey: string;
+    /** Revision values current at issue time (snapshotted into the context). */
+    revisions: RevisionSnapshot;
+    /** Explicit id (e.g. for coalescing bookkeeping); generated when omitted. */
+    requestId?: string;
+    /** Chain an upstream signal (e.g. instance teardown) into this request. */
+    parentSignal?: AbortSignal;
+}
+/** A `RequestContext` plus its owning abort handle. */
+interface RequestContextHandle {
+    readonly context: RequestContext;
+    readonly controller: AbortController;
+    abort(reason?: unknown): void;
+}
+/**
+ * Builds the `RequestContext` a service call receives (§9.2): dataset,
+ * the three revision dimensions at issue time, a request id, and a
+ * cancellation signal owned by the returned controller.
+ */
+declare function createRequestContext(args: CreateRequestContextArgs): RequestContextHandle;
+interface AdmitServiceResultArgs {
+    /** The service's `revisionDependencies` (§9.2). */
+    declared: readonly RevisionDimension[];
+    /** Revision values when the request was issued. */
+    at: RevisionSnapshot;
+    /** Revision values at admission time. */
+    now: RevisionSnapshot;
+}
+/**
+ * §9.2 stale-result rule: admit a service result iff EVERY declared revision
+ * dimension is unchanged between issue and admission. Undeclared dimensions
+ * never invalidate. Declaring nothing means the result is admissible under
+ * any drift; declaring all three restores strict point-in-model semantics.
+ */
+declare function admitServiceResult(args: AdmitServiceResultArgs): boolean;
+interface ServiceCacheKeyArgs {
+    serviceId: string;
+    /** Request parameters (JSON-shaped); key order is canonicalized away. */
+    params: unknown;
+    datasetKey: string;
+    /** The service's declared revision dependencies (§9.2). */
+    declared: readonly RevisionDimension[];
+    /** Current revision values; only declared dimensions enter the key. */
+    revisions: RevisionSnapshot;
+}
+/**
+ * §9.2 cache-key rule: service identity + canonical-JSON params +
+ * `datasetKey` + EXACTLY the declared revision dimensions' current values.
+ * Declaration-list order and params key order do not affect the key;
+ * undeclared revision drift never changes it.
+ */
+declare function serviceCacheKey(args: ServiceCacheKeyArgs): string;
+/** Accepted-base view the local service walks (thunked for lazy wiring). */
+interface LocalExpansionBase<N = Record<string, unknown>, E = Record<string, unknown>> {
+    accepted: AcceptedGraph<N, E>;
+    /** The §7.1 CSR adjacency of `accepted` (see buildAcceptedAdjacency). */
+    adjacency: Adjacency;
+}
+/**
+ * The built-in §9.2 expansion service: walks the core's accepted-base
+ * adjacency — INCLUDING currently out-of-scope nodes (it reads the base, not
+ * the scene) — with zero config and zero network. Declares
+ * `revisionDependencies: ['source']`, so unrelated model/scope advances
+ * (e.g. other overlay publications) never invalidate its results.
+ *
+ * `getBase` is a thunk so the instance can wire the service before data
+ * arrives; it is re-read on every call. The returned promise is async but
+ * effectively synchronous (resolves without I/O). `ctx.signal` is honored:
+ * an aborted call rejects with `OrbitOperationError { code: 'aborted' }`
+ * instead of returning a result (abort is still only an optimization — the
+ * admission gate is authoritative).
+ *
+ * The response is the CLOSED N-hop neighborhood (seeds included, plus every
+ * edge between returned nodes); per §9.2 the overlay merger dedupes rows
+ * that already exist, so returning already-known seeds is correct.
+ */
+declare function createLocalExpansionService<N = Record<string, unknown>, E = Record<string, unknown>>(getBase: () => LocalExpansionBase<N, E>): ExpansionService<N, E>;
+type RegisterExpansionResult = {
+    kind: 'new';
+}
+/** A same-id expansion is already in flight; its result serves both. */
+ | {
+    kind: 'coalesced';
+    onto: string;
+};
+/**
+ * Pure in-flight-expansion ledger (§9.2): within one valid scope revision a
+ * second `expandNode(id)` while one is in flight coalesces into the pending
+ * call; expansions of DISTINCT ids run (and complete) concurrently and
+ * independently. `retractExpansion(id)` uses `abort(id)` to drop that id's
+ * pending expansion. Holds no timers, promises, or engine state — the
+ * instance owns the actual requests.
+ */
+declare class PendingExpansions {
+    private readonly inFlight;
+    /**
+     * Registers an expansion of `id` under `requestId`. Returns
+     * `{ kind: 'coalesced', onto }` when a same-id expansion is already in
+     * flight (the caller must NOT issue a new request; `onto` is the request
+     * id whose result serves both), else records the id and returns
+     * `{ kind: 'new' }`.
+     */
+    register(id: NodeId, requestId: string): RegisterExpansionResult;
+    /**
+     * Marks `id`'s expansion complete. When `requestId` is given, clears only
+     * if it still owns the slot (a stale completion after abort + re-expand
+     * must not clear the newer request). Returns whether the slot was cleared.
+     */
+    resolve(id: NodeId, requestId?: string): boolean;
+    /**
+     * Drops `id`'s pending expansion (retractExpansion path). Returns the aborted
+     * request id so the caller can cancel its controller, or null when nothing
+     * was in flight.
+     */
+    abort(id: NodeId): string | null;
+    /** Request id currently serving `id`, if any. */
+    requestIdFor(id: NodeId): string | undefined;
+    has(id: NodeId): boolean;
+    get size(): number;
+    /** Snapshot of pending ids (store's `pendingExpansions` shape). */
+    ids(): ReadonlySet<NodeId>;
+}
+
+/**
+ * §16.14 history command-stack kernel (S9-T20; pulled forward from M7).
+ *
+ * v0.7 implements the KERNEL only: value-diff commands, transactions,
+ * coalescing, and a bounded stack. The kernel never touches stores — it is a
+ * pure application seam: `undo()`/`redo()` return the command list to apply
+ * (already inverted, in application order) and move the cursor; the instance
+ * (wired in S15) applies commands to its slices and publishes.
+ * Ownership-mode acknowledgement walks and view-state integration are S15.
+ *
+ * Commands are `{ slice, before, after }` value diffs — never closures — so
+ * they are serializable and invert by swapping. The kernel freezes and stores
+ * exactly what it is given (no structuredClone): callers pass plain values /
+ * arrays and must not mutate them afterward. A DEV-only serializability walk
+ * (no functions, no Map/Set — callers convert) runs behind the `debug` flag.
+ */
+/** One history-worthy mutation: a serializable value diff over a named slice. */
+interface HistoryCommand {
+    readonly slice: string;
+    readonly before: unknown;
+    readonly after: unknown;
+}
+/** Depth snapshot published to subscribers (mirrors GraphStoreState.history). */
+interface HistoryDepths {
+    readonly undoDepth: number;
+    readonly redoDepth: number;
+}
+interface HistoryKernelOptions {
+    /** Stack bound; oldest entry evicted past it (§16.14; default 50). */
+    limit?: number;
+    /** `false` = the `history: false` prop: everything is a no-op, depths stay 0. */
+    enabled?: boolean;
+    /** DEV-only: walk recorded payloads and throw on non-serializable values. */
+    debug?: boolean;
+}
+declare const HISTORY_LIMIT_DEFAULT = 50;
+/**
+ * Bounded undo/redo command stack. Store-agnostic: see module doc for the
+ * application seam. All methods are synchronous; there is no async state.
+ */
+declare class HistoryKernel {
+    private readonly limit;
+    private readonly enabled;
+    private readonly debug;
+    private readonly undoStack;
+    private readonly redoStack;
+    /** Nested begin() joins the outer transaction (depth-counted). */
+    private txDepth;
+    private txCommands;
+    private txLabel;
+    private txCoalesce;
+    /**
+     * Coalescing chain anchor: the tag of the most recently PUSHED entry, valid
+     * only while that entry is still the top of the undo stack with nothing in
+     * between — any undo/redo/clear or non-coalesced push breaks the chain.
+     */
+    private lastCoalesce;
+    private readonly listeners;
+    private lastDepths;
+    constructor(options?: HistoryKernelOptions);
+    /** Open a transaction; nested calls join the outer one (depth-counted). */
+    begin(label?: string): void;
+    /**
+     * Open a coalescing transaction: consecutive transactions with the same
+     * `key` within `windowMs` MERGE into the prior stack entry (original before
+     * kept, after replaced per slice) — camera drags, timeline play sessions.
+     * Nested inside an open transaction it joins the outer one unchanged.
+     * `now` is injectable for tests; each merge refreshes the window anchor.
+     */
+    beginCoalesced(key: string, windowMs: number, now?: () => number): void;
+    /**
+     * Record one value-diff command. Inside a transaction it appends to the
+     * pending entry; outside it wraps itself in an implicit single-command
+     * transaction. The kernel freezes and stores what it is given.
+     */
+    record(slice: string, before: unknown, after: unknown): void;
+    /** Close a transaction; the outermost end() pushes one stack entry. */
+    end(): void;
+    /**
+     * Move the cursor back one entry and return its commands, already inverted
+     * (before/after swapped) and in application order (reverse of recorded).
+     * Returns null at the bottom of the stack. Does not touch any store.
+     */
+    undo(): readonly HistoryCommand[] | null;
+    /**
+     * Move the cursor forward one entry and return its commands in original
+     * application order. Returns null when there is nothing to redo.
+     */
+    redo(): readonly HistoryCommand[] | null;
+    peekUndoDepth(): number;
+    peekRedoDepth(): number;
+    /** Empty both stacks and any pending transaction (datasetKey swaps). */
+    clear(): void;
+    /** Subscribe to depth CHANGES (not every call). Returns an unsubscriber. */
+    subscribe(cb: (depths: HistoryDepths) => void): () => void;
+    /**
+     * Push one entry: any new entry clears the redo branch; a coalesce-tagged
+     * entry within the window of a still-anchored same-key predecessor merges
+     * into it instead (original before kept, after replaced per slice); pushing
+     * past the limit evicts the oldest entry.
+     */
+    private pushEntry;
+    private notify;
+}
+
+/**
+ * §9.1 soft filtering (S9-T01) — pure, engine-free expr evaluation,
+ * validation, compilation, and canonical keying. The instance feeds compiled
+ * filters into the SoftMask kernel (./mask); nothing here touches the store.
+ *
+ * Semantics (orbit-spec.md §9.1):
+ * - `field` addresses `attrs[field]`; the literal field 'id' addresses the
+ *   entity id (it wins even when `attrs.id` exists).
+ * - The serializable expr path NEVER throws: junk shapes and §8-hygiene
+ *   failures (non-numeric / non-finite values under 'range') simply fail the
+ *   item. `validateFilterExpr` is the reporting channel — the instance turns
+ *   its findings into validation errors at applyHostUpdate.
+ * - eq/neq/in compare numbers with Object.is semantics EXCEPT that NaN is
+ *   never equal to anything (so ±0 are distinct and NaN ≠ NaN); everything
+ *   else compares with plain ===. No coercion, ever ('5' never equals 5).
+ * - Function predicates are black boxes: throws are caught and aggregated
+ *   into ONE {count, samples} result the caller converts to a single
+ *   'filter-error' diagnostic (§5.1 batching — O(categories), never O(bad
+ *   rows)). A throwing predicate FAILS OPEN: the item stays visible, so a
+ *   buggy predicate can never blank the graph.
+ * - Structural specs compare by canonical key (`canonicalFilterKey`) so
+ *   identity churn with equal structure never re-evaluates; function
+ *   predicates key by reference identity via a WeakMap-issued token.
+ */
+
+/**
+ * Resolves a filter `field` against an entity: 'id' addresses the entity id;
+ * any other field addresses `attrs[field]` (undefined when attrs are absent).
+ */
+declare function resolveFilterField(item: GraphNode<unknown> | AcceptedEdge<unknown>, field: string): unknown;
+/**
+ * Evaluates one expr for one item via a field resolver. NEVER throws:
+ * malformed shapes and §8-hygiene failures fail the item (return false);
+ * a malformed operand under 'not' also fails (junk never passes by double
+ * negation). `range` requires a finite number value; missing bounds are
+ * unbounded; includeMin/includeMax default true. `is-null` matches null OR
+ * undefined (absent attr).
+ */
+declare function evaluateFilterExpr(expr: FilterExpr, resolve: (field: string) => unknown): boolean;
+/**
+ * Structural checker for serializable exprs: unknown ops and malformed
+ * shapes are reported as `$`-rooted path strings ([] = valid). The instance
+ * converts findings into validation errors at applyHostUpdate (§9.1) —
+ * evaluation itself never throws on the same junk, it just fails the item.
+ */
+declare function validateFilterExpr(expr: FilterExpr): string[];
+/** ONE aggregated throw tally per compiled filter → one 'filter-error'
+ * diagnostic (count + capped samples), never O(bad rows) diagnostics. */
+interface FilterErrorAggregate {
+    count: number;
+    /** At most DIAGNOSTIC_SAMPLE_CAP offending entity ids. */
+    samples: string[];
+}
+interface CompiledFilter<T> {
+    /** True = item passes (stays fully visible); false = item fails the mask. */
+    test(item: T): boolean;
+    /** Live tally of predicate throws (function specs only; the expr path
+     * never throws). The caller converts a nonzero count to a 'filter-error'
+     * diagnostic after the evaluation pass. */
+    readonly errors: FilterErrorAggregate;
+}
+/** Compiles the node lane of a FilterSpec (absent selector = pass-all). */
+declare function compileNodeFilter<N = Record<string, unknown>, E = Record<string, unknown>>(spec: FilterSpec<N, E>): CompiledFilter<GraphNode<N>>;
+/** Compiles the edge lane of a FilterSpec (absent selector = pass-all). */
+declare function compileEdgeFilter<N = Record<string, unknown>, E = Record<string, unknown>>(spec: FilterSpec<N, E>): CompiledFilter<AcceptedEdge<E>>;
+/**
+ * Canonical structural key for a FilterSpec or FilterExpr: object keys are
+ * sorted, arrays preserve order, undefined-valued keys are omitted, and
+ * function predicates map to a unique reference-identity token. Two inputs
+ * with equal keys are §9.1-equivalent — the instance skips re-evaluation
+ * when the key of an incoming filter matches the active one (identity churn
+ * with equal structure never re-evaluates; swapping a function reference
+ * always does).
+ */
+declare function canonicalFilterKey(specOrExpr: unknown): string;
+
+/**
+ * §9.1 soft-mask kernel (S9-T02/T03) — failure COUNTERS, never Sets and
+ * never per-source bit positions (so there is no 32-dimension cap).
+ *
+ * The mask owns four Uint16 counter lanes: hideFailures and dimFailures for
+ * nodes AND edges. Every acquired {@link MaskSource} contributes +1 to a
+ * lane counter for each slot it currently fails and -1 when that slot
+ * re-enters. A slot is visible iff hideFailures === 0 and dimmed iff visible
+ * AND dimFailures > 0 (spec §9.1 mask mechanics).
+ *
+ * Delta discipline: each source keeps its previous failing membership as
+ * per-source Uint8 flag columns plus a dense slot list, so replacing a
+ * membership touches counters ONLY for slots whose membership actually
+ * changed (O(1) detection per presented slot). Counter transitions across
+ * zero append the slot to reusable dirty lists; {@link SoftMask.drainDirty}
+ * compares against the state at the previous drain, so a fail-then-restore
+ * inside one drain period nets to no emission.
+ *
+ * {@link SoftMask.applyNodeCascadeToEdges} implements §9's SINGLE edge-
+ * survival rule over the mask lane: an edge hide-fails iff EITHER endpoint
+ * hide-fails (equivalently: survives iff BOTH endpoints survive —
+ * scope.ts `cascadeEdges` is the hard-scope variant of the same rule). It is
+ * fed through one dedicated internal cascade source from the node hide lane:
+ * O(E) recompute per call, but only edges whose state changed produce
+ * counter deltas.
+ *
+ * Overflow guard: increments clamp at 0xFFFF and latch a one-time
+ * {@link SoftMask.overflowed} flag the caller reports (an implementation may
+ * widen to Uint32 without changing semantics, §9.1). Debug builds assert
+ * balanced increments/decrements whenever a clear()/release() leaves zero
+ * held memberships.
+ */
+/** Default muted alpha for dimmed entities (§9.1 'dim' mode). */
+declare const DIM_ALPHA_DEFAULT = 0.15;
+/**
+ * A handle contributing failure memberships to the mask. Setting a lane
+ * REPLACES that lane's previous membership for this source (the kernel
+ * applies only the delta). `null` = empty membership for that lane; an
+ * omitted `dimIdx` leaves the dim lane untouched.
+ */
+interface MaskSource {
+    readonly name: string;
+    setNodeFailures(hideIdx: Iterable<number> | null, dimIdx?: Iterable<number> | null): void;
+    setEdgeFailures(hideIdx: Iterable<number> | null, dimIdx?: Iterable<number> | null): void;
+    /** Empties all four lane memberships (the source stays usable). */
+    clear(): void;
+    /** clear() + permanently retires the handle (further set/clear throws;
+     * release() itself is idempotent). */
+    release(): void;
+}
+/**
+ * One drain payload. The four index arrays are REUSED across drains — copy
+ * before the next drainDirty() call if you need to keep them.
+ */
+interface MaskDrain {
+    /** Node slots whose hide-visibility (hideFailures 0 ↔ nonzero) flipped
+     * since the previous drain. */
+    nodes: readonly number[];
+    /** Edge slots whose hide-visibility flipped since the previous drain. */
+    edges: readonly number[];
+    /** Node slots whose dim state (dimFailures 0 ↔ nonzero) flipped — the
+     * alpha lane. Consumers recompute alpha over `nodes ∪ nodesAlpha` (a hide
+     * flip also changes the effective alpha; a slot may appear in both). */
+    nodesAlpha: readonly number[];
+    /** Edge slots whose dim state flipped. */
+    edgesAlpha: readonly number[];
+    nodeVisibleCount: number;
+    edgeVisibleCount: number;
+}
+declare class SoftMask {
+    private nodeCap;
+    private edgeCap;
+    private readonly nodeHideLane;
+    private readonly nodeDimLane;
+    private readonly edgeHideLane;
+    private readonly edgeDimLane;
+    private readonly sources;
+    /** Dedicated internal source implementing the §9 node→edge cascade. */
+    private cascadeSource;
+    private overflowedFlag;
+    /** Total memberships currently held across all sources and lanes. */
+    private totalHeld;
+    constructor(nodeCapacity: number, edgeCapacity: number);
+    get nodeCapacity(): number;
+    get edgeCapacity(): number;
+    /** One-time latch: some counter hit 0xFFFF and an increment was dropped.
+     * Counts may drift afterwards; the caller reports it (§9.1 overflow guard). */
+    get overflowed(): boolean;
+    get nodeHideFailures(): Uint16Array;
+    get nodeDimFailures(): Uint16Array;
+    get edgeHideFailures(): Uint16Array;
+    get edgeDimFailures(): Uint16Array;
+    /**
+     * Grows capacities for structure changes (existing slot state is
+     * preserved; new slots start fully visible). Capacities never shrink —
+     * a smaller value is a no-op for that dimension.
+     */
+    grow(nodeCapacity: number, edgeCapacity: number): void;
+    /** Registers a new failure source. No cap on source count (§9.1). */
+    acquire(name: string): MaskSource;
+    /**
+     * §9 edge cascade over the mask lane: recomputes, from the CURRENT node
+     * hide lane, the set of edges with at least one hidden endpoint, and feeds
+     * it to the dedicated internal cascade source (edge hide lane only).
+     * `links` is the flat `[src0, tgt0, src1, tgt1, …]` node-slot pair buffer
+     * (§7.1 CSR input shape); edge slot i has endpoints at links[2i]/[2i+1].
+     * O(E) scan per call — typically once per drain — but only edges whose
+     * cascade state changed produce counter deltas (and thus dirty entries).
+     * Edges beyond `links.length / 2` are treated as having no hidden
+     * endpoint (their previous cascade contribution, if any, is removed).
+     */
+    applyNodeCascadeToEdges(links: Uint32Array): void;
+    /**
+     * Drains the zero-crossing dirty lists accumulated since the previous
+     * drain. Only NET flips are emitted (state compared against the previous
+     * drain). The returned index arrays are reused by the next drain.
+     */
+    drainDirty(): MaskDrain;
+    visibleNodeCount(): number;
+    visibleEdgeCount(): number;
+    /** Visible iff hideFailures === 0 (out-of-range slots read not-visible). */
+    isNodeVisible(index: number): boolean;
+    isEdgeVisible(index: number): boolean;
+    /** Dimmed iff visible AND dimFailures > 0 (§9.1). */
+    isNodeDimmed(index: number): boolean;
+    isEdgeDimmed(index: number): boolean;
+    /** 1 (fully visible) | dimAlpha (dimmed) | 0 (hidden). */
+    nodeAlpha(index: number, dimAlpha?: number): number;
+    edgeAlpha(index: number, dimAlpha?: number): number;
+    /**
+     * Replaces one source-lane membership with `incoming` (null = empty),
+     * applying counter deltas ONLY for slots whose membership changed.
+     * Incoming slots are validated up front so a RangeError never leaves the
+     * membership partially applied; duplicates within `incoming` count once.
+     */
+    private applyMembership;
+    private increment;
+    private decrement;
+    /** Records the first zero-crossing of a slot per drain period, remembering
+     * whether the counter was zero at the previous drain. */
+    private markDirty;
+    private drainLane;
+    private clearSource;
+    /** Debug balanced-increment assert: whenever no source holds any
+     * membership, every counter must read zero (skipped once overflowed —
+     * clamped increments legitimately drift the books). */
+    private assertBalancedIfIdle;
+}
+
+/**
+ * §16.6 crossfilter — typed-column engine (v0.7 node-dimension subset).
+ *
+ * `TypedColumnCrossfilter` is the columnar backend the instance wraps into the
+ * public `CrossfilterSession`. Design (crossfilter.js lineage):
+ *
+ * - **Parse once.** `build()` extracts every dimension exactly once into typed
+ *   columns (numeric/temporal → `Float64Array` epoch-ms/values, categorical →
+ *   dictionary codes). §8 hygiene: non-finite numerics, unparseable temporals,
+ *   and non-string/non-finite categorical values are excluded from the
+ *   dimension (tracked per dimension in `excludedRows`; the slot is marked
+ *   invalid). Temporal parsing: numbers are epoch ms verbatim; strings go
+ *   through `Date.parse` (ES2022 parses `'YYYY-MM-DD'` as UTC midnight);
+ *   `Date` instances use `getTime()`.
+ * - **O(Δ) brushes.** Each range dimension keeps a one-time argsorted
+ *   permutation. A brush move performs two binary searches and walks ONLY the
+ *   symmetric difference between the old and new in-range windows; categorical
+ *   brushes walk only the per-code slot lists whose excluded flag changed. The
+ *   brush path never re-sorts. A per-slot, per-dimension pass flag plus a
+ *   global per-slot failure counter make a row selection-visible iff it fails
+ *   zero dimensions. Hygiene-excluded rows fail any non-null brush on that
+ *   dimension (they cannot be in range / in a category) and pass a null brush.
+ * - **Deltas out.** `setBrush` returns the slots whose overall visibility
+ *   flipped (`hidden`/`shown`) for the instance's mask source.
+ * - **Lazy dual layer.** `summarize()` returns immutable summaries whose
+ *   `filtered` layer counts rows passing every OTHER dimension's brush plus an
+ *   external node-mask predicate (`setExternalMask`). v0.7 recomputes a dirty
+ *   dimension's filtered layer lazily per `summarize()` call — O(rows) per
+ *   dirty summarize, documented and acceptable at this tier (§17 fixtures own
+ *   the perf claims; the O(Δ) guarantee covers the brush/visibility path).
+ * - **Revisions & notify.** `selectionRevision` starts at 0 and advances
+ *   exactly once per observable `setBrush` (a brush state change is observable
+ *   via `getBrush` even when no row flips). v0.7 is synchronous, so
+ *   latest-call-wins degenerates to "every call applies immediately in call
+ *   order". Subscribers fire once per observable change after state is
+ *   consistent; synchronous re-entrancy (a subscriber mutating the engine) is
+ *   coalesced into one trailing notification pass. Model updates
+ *   (`appendRows`/`replaceAll`) keep the current `selectionRevision` (§16.6)
+ *   but do notify. External-mask changes notify (summaries changed) without
+ *   advancing the selection revision.
+ * - **Incremental append.** `appendRows` extends columns/codes in place and
+ *   merges the pre-sorted old permutation with the sorted new block
+ *   (permutation merge — never a full re-argsort); bins extend incrementally
+ *   unless the domain grew (then a re-bin, still sort-free). Brushes persist
+ *   by key and are re-applied to the NEW slots only; the returned delta covers
+ *   only new slots (`shown` = new passing, `hidden` = new failing).
+ *   `replaceAll` rebuilds columns but preserves brushes by dimension key,
+ *   re-applying them as one combined delta against an all-visible baseline of
+ *   the new roster (`shown` is always empty). `replaceAll` clears the external
+ *   mask (slot indices changed meaning); `appendRows` keeps it and treats new
+ *   slots as passing until the instance re-supplies it.
+ */
+
+/** Default histogram bin count for numeric/temporal dimensions (§16.6). */
+declare const DEFAULT_BIN_COUNT = 24;
+/** Slots whose overall selection-visibility flipped in one operation. */
+interface BrushDelta {
+    /** Slots that flipped visible → hidden. */
+    hidden: number[];
+    /** Slots that flipped hidden → visible. */
+    shown: number[];
+}
+/** Test instrumentation counters (see crossfilter.test.ts O(Δ) evidence). */
+interface CrossfilterStats {
+    /** Slots touched by brush delta walks (the O(Δ) loop). */
+    slotsWalked: number;
+    /** Full-column argsorts (build/replaceAll only — never append or brush). */
+    fullSorts: number;
+    /** Permutation merges performed by appendRows. */
+    permutationMerges: number;
+}
+declare class TypedColumnCrossfilter<N = Record<string, unknown>> {
+    /** Test instrumentation; see CrossfilterStats. Reset with resetStats(). */
+    readonly stats: CrossfilterStats;
+    private dims;
+    private byKey;
+    private specs;
+    private n;
+    /** Per-slot count of dimensions the slot currently fails. */
+    private failCount;
+    private externalMask;
+    private revision;
+    private readonly subscribers;
+    private built;
+    private disposed;
+    private notifying;
+    private renotify;
+    /** Monotonic from 0; advances exactly once per observable setBrush change. */
+    get selectionRevision(): number;
+    resetStats(): void;
+    /**
+     * (Re)initialize columns from scratch. Clears all brushes and the external
+     * mask (use replaceAll to rebuild while preserving brushes by key). Does not
+     * notify and does not touch selectionRevision.
+     */
+    build(nodes: readonly GraphNode<N>[], specs: readonly DimensionSpec<N>[]): void;
+    rowCount(): number;
+    getBrush(key: string): BrushState;
+    isSlotVisible(slot: number): boolean;
+    /** Fresh array of selection-visible slots, ascending. */
+    visibleSlots(): number[];
+    /**
+     * Apply a brush (latest-call-wins: v0.7 is synchronous, so each call applies
+     * immediately in call order). Returns the slots whose overall
+     * selection-visibility flipped. A no-op (deep-equal brush) returns empty
+     * deltas without advancing selectionRevision or notifying.
+     */
+    setBrush(key: string, brush: BrushState): BrushDelta;
+    /**
+     * External node-mask predicate for the joint "filtered" second layer (the
+     * instance wires the §9.1 filter-prop node mask in). Affects summaries only,
+     * never selection visibility. Length must equal rowCount(). Notifies on
+     * observable change; does NOT advance selectionRevision.
+     */
+    setExternalMask(passSlots: Uint8Array | null): void;
+    /**
+     * Immutable summary. The filtered layer is recomputed lazily when dirty —
+     * O(rows) per dirty summarize (v0.7 tier; see module doc). Returned objects
+     * are frozen and never mutated by later operations.
+     */
+    summarize(key: string): DimensionSummary;
+    /**
+     * Incrementally extend columns with new rows (S9-T09 subset): no full
+     * rebuild, no full re-argsort — the pre-sorted old permutation merges with
+     * the sorted new block. Brushes stay by key and are applied to the NEW slots
+     * only; the returned delta covers only new slots. Keeps selectionRevision;
+     * notifies when rows were appended.
+     */
+    appendRows(newNodes: readonly GraphNode<N>[]): BrushDelta;
+    /**
+     * Full rebuild from a new roster, PRESERVING brushes by dimension key and
+     * re-applying them as one combined delta against an all-visible baseline of
+     * the new roster (shown is always empty). Clears the external mask. Keeps
+     * selectionRevision; notifies once.
+     */
+    replaceAll(nodes: readonly GraphNode<N>[]): BrushDelta;
+    /** Fires once per observable selection/summary change, state consistent. */
+    subscribe(cb: () => void): () => void;
+    /** Idempotent; every other method throws afterwards. */
+    dispose(): void;
+    private ensureLive;
+    private ensureBuilt;
+    private dim;
+    private buildDims;
+    private buildRangeDim;
+    private buildCatDim;
+    /** Recompute domain, bin edges, per-slot bin index, and totals. Sort-free. */
+    private rebinRange;
+    private binIndex;
+    private flip;
+    private walkSorted;
+    private walkList;
+    private applyRangeTransition;
+    private applyCatTransition;
+    private appendRange;
+    private appendCat;
+    private recomputeFiltered;
+    /** One callback pass per observable change; synchronous re-entrancy coalesces. */
+    private notify;
+}
+
+/**
+ * §11 scales & domains (S10-T01/T07) — canonical scale keying, default
+ * palettes, sRGB color interpolation, domain-state machinery, and stable
+ * categorical assignment. Pure and engine-free; the instance/projection
+ * layers consume these primitives when a styling channel carries a `Scale`.
+ *
+ * Semantics (orbit-spec.md §8/§11):
+ * - Scales are plain descriptors compared by CANONICAL STRUCTURAL VALUE —
+ *   equal inline literals produce equal keys and never reproject. A function
+ *   `by` keys by reference identity (WeakMap token), never by source text.
+ * - Domains default to the whole dataset revision and stay FROZEN across
+ *   masking/brushing/isolation ('dataset' scope): the same metric value never
+ *   changes visual meaning because a user brushed. 'hard-scope'/'visible' are
+ *   explicit opt-ins that recompute when the caller's scope generation bumps;
+ *   streaming 'expand' permits monotonic domain growth on recompute.
+ * - Explicit numeric domains always win verbatim (never computed, cached, or
+ *   unioned).
+ * - Categorical values declared in `domain` take their declared position;
+ *   out-of-domain values take a stable fnv-1a hash slot — NEVER first-seen
+ *   order, so arrival order can never recolor a category.
+ * - §8 numeric hygiene: null/non-finite metric values resolve to `null`
+ *   (caller falls back to the default style) and are excluded from domains.
+ */
+
+type SequentialScale<T, N = Record<string, unknown>> = Extract<Scale<T, N>, {
+    kind: 'sequential';
+}>;
+type CategoricalScale<T, N = Record<string, unknown>> = Extract<Scale<T, N>, {
+    kind: 'categorical';
+}>;
+type DivergingScale<T, N = Record<string, unknown>> = Extract<Scale<T, N>, {
+    kind: 'diverging';
+}>;
+/**
+ * Canonical structural key for a Scale descriptor: object keys sorted, array
+ * order preserved, undefined-valued keys omitted, and a function `by` mapped
+ * to a unique reference-identity token (same WeakMap approach — and canonical
+ * grammar — as `canonicalFilterKey`). Two scales with equal keys are
+ * §11-equivalent: equal inline literals MUST and DO produce equal keys, so
+ * identity churn never reprojects; swapping a function reference always does.
+ */
+declare function canonicalScaleKey<T, N>(scale: Scale<T, N>): string;
+/** 12 brand-neutral categorical hues distinguishable on light AND dark. */
+declare const CATEGORICAL_PALETTE: readonly string[];
+/** Default sequential ramp endpoints (low → high). */
+declare const SEQUENTIAL_RANGE_DEFAULT: readonly [string, string];
+/** Default diverging stops (low → mid → high). */
+declare const DIVERGING_RANGE_DEFAULT: readonly [string, string, string];
+/**
+ * Interpolates between two CSS color strings in sRGB (component-wise,
+ * including alpha) and returns an `rgba(r, g, b, a)` string. `t` is clamped
+ * to [0,1] (non-finite t → 0). Unparseable endpoints fall back to the
+ * projection lane's neutral gray — never a throw, never NaN output.
+ */
+declare function interpolateColor(a: string, b: string, t: number): string;
+/**
+ * Sequential color: maps `value` across `domain` onto the two-stop ramp.
+ * Returns null (caller renders the default style, §8 hygiene) when the value
+ * is null/non-finite or the domain is null.
+ */
+declare function sequentialColor<N = Record<string, unknown>>(scale: SequentialScale<string, N>, value: number | null, domain: readonly [number, number] | null): string | null;
+/**
+ * Diverging color: `mid` maps to the middle stop exactly; each half
+ * interpolates independently ([domain[0]..mid] over range[0..1],
+ * [mid..domain[1]] over range[1..2]). A degenerate half collapses to the
+ * middle stop. Null/non-finite value or null domain → null.
+ */
+declare function divergingColor<N = Record<string, unknown>>(scale: DivergingScale<string, N>, value: number | null, domain: readonly [number, number] | null): string | null;
+/**
+ * Sequential size: linear map of `value` across `domain` onto [lo,hi],
+ * clamped at the range endpoints. Degenerate domains yield the range
+ * midpoint; null/non-finite values and null domains yield null (default
+ * style — NaN is never handed to a size buffer, §8).
+ */
+declare function sequentialSize(range: readonly [number, number], value: number | null, domain: readonly [number, number] | null): number | null;
+/**
+ * [min,max] over the finite numbers in `values` (§8 hygiene: null and
+ * non-finite entries are excluded), or null when nothing qualifies. A single
+ * qualifying value yields a degenerate [v,v] domain.
+ */
+declare function computeNumericDomain(values: Iterable<number | null>): [number, number] | null;
+interface ResolveDomainArgs {
+    /** Cache key — `canonicalScaleKey(scale)` (the metric name is part of the
+     * descriptor, so the key already discriminates by metric). Opaque here. */
+    key: string;
+    /** Explicit caller domain — returned VERBATIM; never computed, cached, or
+     * expand-unioned (§11: explicit always wins). */
+    explicit?: readonly [number, number] | undefined;
+    /** Defaults: scope 'dataset', streaming 'freeze-per-revision'. */
+    policy?: DomainPolicy | undefined;
+    /** The dataset revision the caller is resolving against. */
+    datasetRevision: number | string;
+    /** Caller-owned generation counter for 'hard-scope'/'visible' scopes
+     * (bump = recompute). IGNORED under 'dataset' scope — masking/brushing
+     * must never change what a color means. */
+    scopeGeneration?: number | undefined;
+    /** Source lineage this resolve belongs to (F11-02: datasetKey + source
+     * revision). `streaming: 'expand'` unions only WITHIN one lineage — a
+     * source replacement starts fresh instead of unioning dead extrema.
+     * Callers that omit it keep the legacy always-union behavior. */
+    lineage?: string | undefined;
+    /** Domain producer (typically wraps computeNumericDomain over the metric
+     * column). Called at most once per freeze coordinate. */
+    compute: () => readonly [number, number] | null;
+}
+/**
+ * Per-instance domain freezer keyed by canonical scale key (§11).
+ *
+ * FREEZE-PER-REVISION: under scope 'dataset' the domain is computed ONCE per
+ * {key, datasetRevision} — repeat resolves return the frozen value without
+ * calling `compute`, no matter how the underlying data was masked or brushed
+ * in between. 'hard-scope'/'visible' additionally recompute when the caller's
+ * scopeGeneration bumps. Streaming 'expand' turns every recompute into a
+ * monotonic union with the previous domain (the domain only ever grows);
+ * 'freeze-per-revision' replaces it. Explicit domains bypass the store.
+ */
+declare class DomainStore {
+    private readonly entries;
+    resolveDomain(args: ResolveDomainArgs): readonly [number, number] | null;
+    /**
+     * Dataset replace: `revision` is the revision now current — every entry
+     * frozen for any OTHER revision is dropped (including expand-union lineage,
+     * so a replaced dataset never unions against dead data). Entries already
+     * at `revision` survive.
+     */
+    invalidateDataset(revision: number | string): void;
+    /** Full reset (dataset identity change / instance teardown). */
+    clear(): void;
+}
+/**
+ * Palette slot for a categorical value: values declared in `domain` take
+ * their declared position (mod palette length — fixed order → stable colors);
+ * out-of-domain values take fnv-1a(value) mod palette length — stable across
+ * sessions and arrival orders, NEVER first-seen order. Returns -1 for an
+ * empty palette.
+ */
+declare function categoricalIndex(domain: readonly string[] | undefined, palette: readonly unknown[], value: string): number;
+/**
+ * Stable legend row order: declared `domain` values FIRST in declared order
+ * (including currently-empty categories), then extra seen values sorted
+ * lexicographically. Duplicates (within `seen` or already declared) collapse.
+ */
+declare function categoricalRows(domain: readonly string[] | undefined, seen: Iterable<string>): string[];
+
+/**
+ * DEF2 capability-policy module (spec §13; plan S1-T08/S4-T05).
+ *
+ * §13 (normative): for capabilities where the core owns a fallback path, the
+ * core selects native-vs-fallback ONCE at mount from the engine's declared
+ * `capabilities` record — never by sniffing method presence — and unsupported
+ * *requested* props degrade loudly (a §5.1 diagnostic), never as silent no-ops.
+ *
+ * This module is the single place those decisions are made:
+ *  - {@link resolveEnginePolicy} turns the capability record + the host's
+ *    requested features into one frozen {@link EnginePolicy} at mount.
+ *  - {@link assertCapabilityMethodParity} is the mount-time dev-mode record
+ *    vs. method-surface assertion, restricted to honestly checkable pairs.
+ *  - {@link normalizeCommitForCapabilities} strips commit payload an engine
+ *    declared it cannot honor, so incapable adapters never see it.
+ */
+
+/** One loud degradation: a feature the host requested that the mounted engine
+ * does not declare. Feeds the §5.1 dev diagnostic at mount. */
+interface EnginePolicyDegradation {
+    readonly feature: string;
+    readonly reason: string;
+}
+/** Host-requested capability-gated features, gathered from mount-time props
+ * (`edgeArrows` prop → edgeArrows; image-bearing nodeStyle/atlas → images). */
+interface RequestedEngineFeatures {
+    edgeArrows?: boolean;
+    images?: boolean;
+    /** §16.3 stage-4: a `clusters` spec is active this session. */
+    clusters?: boolean;
+}
+/**
+ * The frozen mount-time native-vs-fallback record (§13). Evaluated exactly
+ * once per mount from `EngineCapabilities` and never revisited — capability
+ * records are static declarations fixed at engine construction, so the policy
+ * must not drift even if a caller mutates the input record afterwards.
+ */
+interface EnginePolicy {
+    /** §16.12 arrowheads: engine-drawn, or the prop is inert (+ dev warning). */
+    readonly edgeArrows: 'native' | 'inert';
+    /** §8 image sprites: atlas-backed, or the placeholder glyph with refs
+     * retained for a future compatible engine. */
+    readonly images: 'native' | 'placeholder';
+    /** §13 link hover/click: engine events, or the core's CPU grid fallback. */
+    readonly linkPicking: 'native' | 'cpu-fallback';
+    /** §16.3 stage-4 cluster force: engine-applied, or inert (membership,
+     * labels, and centroids are core-owned and unaffected). */
+    readonly clusterForce: 'native' | 'inert';
+    /** Channels eligible for ranged (partial) uploads; empty = full replaces. */
+    readonly rangedChannels: ReadonlySet<EngineBufferChannel>;
+    /** Exactly one entry per REQUESTED-but-unsupported feature; requested and
+     * supported — or simply never requested — contributes nothing. */
+    readonly degradations: readonly EnginePolicyDegradation[];
+}
+/**
+ * Resolve the mount-time engine policy from the declared capability record.
+ *
+ * Decisions come from `capabilities` ONLY — method sniffing is forbidden by
+ * §13. The result is deep-frozen and holds a defensive copy of
+ * `rangeUpdates`, so mutating the input record afterwards changes nothing.
+ * A degradation entry exists only for features the host actually requested
+ * that the engine does not declare; unrequested gaps stay silent.
+ */
+declare function resolveEnginePolicy(capabilities: EngineCapabilities, requested: RequestedEngineFeatures): EnginePolicy;
+/**
+ * Mount-time dev-mode assertion: does the declared capability record agree
+ * with the engine's method surface? Returns a list of human-readable
+ * mismatches (empty = consistent).
+ *
+ * Why so few checks? §13's illustrative parity assertion
+ * (`capabilities.linkPicking === (typeof engine.linkAt === 'function')`)
+ * presumes the spec's full method surface; the v0.1 adapter contract
+ * deliberately narrows it, leaving most capabilities with NO honestly
+ * checkable method pair. Those defer to the §19 conformance suite, which
+ * validates declared records against observed behavior:
+ *
+ *  - `linkPicking`: native picking arrives through mount-time host events
+ *    (`onLinkClick`/`onLinkHover`), not a probeable `linkAt` method — there
+ *    is nothing on the engine object to compare the record against.
+ *  - `edgeArrows` / `pointImages` / `rangeUpdates`: honored inside
+ *    `commit()` payload handling (`config.linkArrows`, `resources`, ranged
+ *    uploads) with no distinguishing method; only behavior can validate them.
+ *  - `simulation`: `start()`/`pause()` are mandatory on every engine (static
+ *    engines no-op them), so method presence carries no signal either way.
+ *  - `pointsInPolygon`-family (`pointsInRect`, `captureScreenshot`,
+ *    `neighborIndices`, `screenToSpace`/`spaceToScreen`, `setPinnedIndices`,
+ *    `zoomToIndex`): optional-by-contract with no declaring capability bit —
+ *    absence is legitimate, so no check is fabricated for them.
+ *
+ * The one honest pair on this surface: `trackedPositions` declares position
+ * readback works, so `getPositions` must actually be present.
+ */
+declare function assertCapabilityMethodParity(engine: GraphEngine): string[];
+/**
+ * Strip commit payload the engine's capability record says it cannot honor:
+ *  - `resources` (image atlas + per-point image index) unless `pointImages`;
+ *  - `config.linkArrows` unless `edgeArrows`;
+ *  - `config.cluster` unless `clusterForce` (§16.3 stage 4 — the core keeps
+ *    membership, labels, and centroids; only the FORCE is engine-side).
+ * A `config` left empty by the strip is dropped entirely.
+ *
+ * IDENTITY-PRESERVING: when nothing needs stripping the SAME commit object
+ * reference is returned, so downstream dirty/equality checks stay cheap. The
+ * input commit is never mutated. `dropped` names each stripped payload path.
+ */
+declare function normalizeCommitForCapabilities(commit: EngineCommit, capabilities: EngineCapabilities): {
+    commit: EngineCommit;
+    dropped: readonly string[];
+};
+
+/**
+ * §8 shared numeric hygiene (R-19-10) — THE single coercion layer for every
+ * numeric consumer in orbit-core.
+ *
+ * Wherever a caller-supplied value feeds a numeric sink — size/width
+ * projection buffers (§8), scale domains (§11), metric columns (§12),
+ * crossfilter bins (§16.6), table lanes — the value is REQUIRED to route
+ * through `coerceNumeric` / `coerceNumericInto`. Non-numeric and non-finite
+ * inputs (including the string sentinels `"NaN"` / `"Infinity"` /
+ * `"-Infinity"` that JSON transports smuggle through, §5) coerce to `null`:
+ * the row falls back to the default style and is excluded from domain
+ * computation. NaN NEVER escapes this module — not as a return value and not
+ * into a GPU buffer.
+ *
+ * Coercion rules:
+ * - numbers pass iff `Number.isFinite` (NaN / ±Infinity → null);
+ * - strings are trimmed; empty → null; the case-insensitive sentinels
+ *   'NaN' / 'Infinity' / '-Infinity' / '+Infinity' → null; anything else
+ *   parses via `Number(...)` and passes iff finite (so '1e3' → 1000 but
+ *   '12px' → null — `Number`, not `parseFloat`, so no partial prefixes);
+ * - booleans, objects, arrays, functions, symbols, bigints, null, and
+ *   undefined → null (no `valueOf`/`toString` coercion side channels).
+ *
+ * FOLLOW-UP (do not fix here): `crossfilter.ts` predates this module and
+ * carries its own inline finite checks; migrating it to route through
+ * `coerceNumeric` is a tracked S10 follow-up so the sentinel-string rules
+ * stay defined in exactly one place.
+ */
+declare function coerceNumeric(value: unknown): number | null;
+/**
+ * Buffer-writer variant for hot projection loops: coerces `value` and writes
+ * it at `target[index]`, falling back to `fallback` when coercion yields
+ * null. Returns true iff the caller's value was admitted (false = fallback
+ * was written).
+ *
+ * The fallback itself is hygiene-checked (a non-finite fallback writes 0) so
+ * NaN cannot reach the buffer through EITHER argument. Allocation-free.
+ */
+declare function coerceNumericInto(target: Float32Array, index: number, value: unknown, fallback: number): boolean;
+
+/**
+ * §12 metrics (v0.8 subset): lazy degree-family primitives over the
+ * maintained topology plus revision-gated admission of async metric columns.
+ *
+ * - The degree family (degree / inDegree / outDegree) is computed LAZILY on
+ *   first request per model revision, in ONE combined O(n + L) pass, and
+ *   cached as Float64Arrays until the model revision changes.
+ * - SELF-LOOP SEMANTICS: a self-loop (a, a) contributes exactly 1 to each of
+ *   degree, inDegree, and outDegree of `a`. The CSR adjacency lists a
+ *   self-loop twice under its point (once per endpoint slot, see
+ *   adjacency.ts), so degree = CSR row length MINUS the point's self-loop
+ *   count; in/out come from a directed pass over the flat link pairs.
+ * - Async columns join once against the accepted model (§12): 'index' align
+ *   is positional over accepted-base order; 'ids' align joins by id with
+ *   unknown ids counted+sampled, duplicate ids counted (last occurrence
+ *   wins), and absent rows null. Every value routes through `coerceNumeric`
+ *   (§8 hygiene, R-19-10). A column computed for a stale model revision is
+ *   DISCARDED with a diagnostic — admission is the correctness gate, abort
+ *   is only an optimization (§9.2).
+ * - Storage encodes null as NaN inside Float64Arrays; `getMetricValue`
+ *   converts back at the boundary so NaN never escapes to callers.
+ * - Admitted columns SHADOW the built-in degree family under the same name
+ *   (a precomputed/server 'degree' column wins; §12 precomputed path).
+ */
+
+/** Topology snapshot the degree family is computed from (§12). */
+interface MetricModelInput<N = Record<string, unknown>> {
+    /** Accepted nodes in accepted-base order (index i ↔ point i). */
+    nodes: readonly GraphNode<N>[];
+    /** CSR adjacency over `links` (self-loops listed twice; adjacency.ts). */
+    adjacency: Adjacency;
+    /** Flat `[src0, tgt0, src1, tgt1, …]` directed point-index pairs. */
+    links: Uint32Array;
+    datasetRevision: number | string;
+    modelRevision: number;
+}
+interface AdmitColumnsOptions {
+    /** Accepted id → accepted-base index (the core map — no public copy). */
+    nodeIndex: ReadonlyMap<NodeId, number>;
+    /** Accepted node count ('index' align must match exactly). */
+    count: number;
+    /** The model revision current when the update carrying the columns was
+     * ISSUED (the admission gate compares each column's own
+     * `forModelRevision` stamp against this — I1). */
+    modelRevision: number;
+}
+interface AdmitColumnsResult {
+    /** Metric names admitted by this call, in input order. */
+    admitted: readonly string[];
+    diagnostics: readonly GraphDiagnostic[];
+}
+declare class MetricStore<N = Record<string, unknown>> {
+    private model;
+    private degreeCache;
+    /** Admitted async columns by metric name; NaN encodes null. */
+    private readonly columns;
+    private degreePasses;
+    /** Number of combined degree-family compute passes (test observability). */
+    get degreeComputePasses(): number;
+    /**
+     * Installs the topology the degree family derives from. A changed
+     * {datasetRevision, modelRevision} coordinate invalidates the lazy degree
+     * cache AND drops every admitted column (their accepted-base alignment is
+     * meaningless against a different model); re-setting the identical
+     * coordinate keeps both.
+     */
+    setModel(model: MetricModelInput<N>): void;
+    /**
+     * Joins async metric columns against the accepted model (§12).
+     * Revision-gated PER COLUMN (I1): a column whose issue-time
+     * `forModelRevision` stamp differs from `opts.modelRevision` is discarded
+     * (info diagnostic — a normal async race outcome, §9.2). A missing or
+     * mismatched stamp is never defaulted to the current revision — that
+     * would make the gate self-satisfying.
+     * Structural rejections ('index' length mismatch, missing/mismatched ids)
+     * emit ONE warning diagnostic per column; a joined column emits at most
+     * one unknown-ids and one duplicate-ids diagnostic, each carrying a total
+     * count and at most DIAGNOSTIC_SAMPLE_CAP sample ids.
+     */
+    admitColumns(columns: readonly MetricColumn[], opts: AdmitColumnsOptions): AdmitColumnsResult;
+    /**
+     * Allocation-free hot path: one map lookup + one typed-array read.
+     * NaN-encoded nulls convert back to `null` at this boundary; unknown
+     * metrics and out-of-range indices are `null`, never NaN.
+     */
+    getMetricValue(metric: MetricName, index: number): number | null;
+    /**
+     * Raw column in accepted-base order, or null when unavailable. NaN encodes
+     * null (§12) — consumers exclude NaN slots from domains. Do NOT mutate:
+     * this is the live cache, not a copy.
+     */
+    metricValues(metric: MetricName): Float64Array | null;
+    /** True when the metric would resolve; never triggers a compute pass. */
+    hasMetric(name: MetricName): boolean;
+    private resolve;
+    /** One combined O(n + L) pass computes all three family members. */
+    private ensureDegrees;
+}
+
+/**
+ * §16.8 minimap / overview — CPU fallback lane (S11-T09/T10).
+ *
+ * v0.9 trim: no engine exposes `capabilities.overviewPass` yet (cosmos has no
+ * second draw pass — M0 matrix), so this controller IS the minimap thumbnail
+ * path: an O(n) CPU rasterization of the §7.1 position mirror into a small
+ * RGBA dot field. It is a pure controller — no DOM, no canvas — the React
+ * component blits the returned `Uint8ClampedArray` into an `ImageData`/canvas
+ * and draws the viewport rectangle on top (O(1) from `getViewport()`, fully
+ * decoupled from thumbnail refresh cadence).
+ *
+ * Refresh cadence (spec §16.8): ≤ 2 Hz while the simulation is hot (positions
+ * change continuously on the GPU, so the epoch is ignored), ≤ 1 Hz after a
+ * change while idle, and ZERO work while idle with an unchanged positions
+ * epoch — `shouldRefresh` is the single throttle gate and latches its clock /
+ * epoch only when it answers true (a `true` must be followed by one
+ * `rasterize()`).
+ *
+ * Orientation: minimap pixel y grows DOWNWARD while world (space) y grows
+ * upward — the same flip cosmos applies in its space→screen scale (dist
+ * `scalePointY.domain([S, 0])`), so the thumbnail visually matches the main
+ * canvas. `worldToMinimap`/`minimapToWorld` are exact inverses over the last
+ * rasterized bounds.
+ */
+/** Position mirror handed to the controller: interleaved x,y space coords. */
+interface OverviewScene {
+    /** Interleaved `[x0, y0, x1, y1, …]`; may be longer than `count` pairs. */
+    positions: Float32Array;
+    /** Number of points (pairs) to read from `positions`. */
+    count: number;
+}
+interface OverviewControllerOptions {
+    /** Latest scene snapshot, or null when nothing is loaded yet. */
+    getScene: () => OverviewScene | null;
+    /**
+     * Soft-filter visibility mask. Hidden points still rasterize (and still
+     * contribute to bounds — the thumbnail must not re-frame when a filter
+     * toggles) but at a dimmed alpha.
+     */
+    getVisible?: (index: number) => boolean;
+    /** Square thumbnail edge in pixels. Default {@link OVERVIEW_SIZE_DEFAULT}. */
+    size?: number;
+}
+/** World-space extent of the last rasterization (finite positions only). */
+interface OverviewBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+interface OverviewRaster {
+    /** RGBA, `size * size * 4` bytes — blit via `new ImageData(bitmap, size)`. */
+    bitmap: Uint8ClampedArray;
+    bounds: OverviewBounds;
+}
+/** Spec §16.8: the CPU fallback rasterizes into a 256² target. */
+declare const OVERVIEW_SIZE_DEFAULT = 256;
+/** Hot-simulation refresh floor: ≤ 2 Hz. */
+declare const OVERVIEW_HOT_INTERVAL_MS = 500;
+/** Idle-after-change refresh floor: ≤ 1 Hz. */
+declare const OVERVIEW_IDLE_INTERVAL_MS = 1000;
+declare class OverviewController {
+    private readonly getScene;
+    private readonly getVisible;
+    readonly size: number;
+    /** Transform of the LAST rasterization; null until rasterize() succeeds. */
+    private frame;
+    private lastRefreshMs;
+    private lastEpoch;
+    constructor(options: OverviewControllerOptions);
+    /**
+     * The single throttle gate (see module header). Latches `nowMs`/`epoch`
+     * when it returns true, so each `true` accounts for exactly one refresh:
+     *
+     * - hot (`simulationRunning`): time-gated only (≤ 2 Hz) — the epoch is
+     *   ignored because positions change continuously without epoch advances;
+     * - idle: refresh only when the epoch ADVANCED since the last refresh,
+     *   time-gated at ≤ 1 Hz;
+     * - idle + unchanged epoch: always false — zero work, forever.
+     */
+    shouldRefresh(nowMs: number, simulationRunning: boolean, epoch: number): boolean;
+    /**
+     * Rasterizes the current scene into a fresh `size²` RGBA dot field: 1 px
+     * white dots whose alpha ACCUMULATES on overlap (heatmap-ish density),
+     * dimmed for mask-hidden points; NaN pairs (§7.3 tombstones) are skipped.
+     * World bounds map into the thumbnail with a 5 % edge padding at a UNIFORM
+     * scale (aspect preserved, centered on the short axis) and a downward pixel
+     * y (see module header). Returns null when there is no scene or no point.
+     */
+    rasterize(): OverviewRaster | null;
+    /**
+     * World (space) → minimap pixel coords over the LAST rasterized frame
+     * (fractional; callers round for pixel work). Null before any rasterize.
+     */
+    worldToMinimap(x: number, y: number): [number, number] | null;
+    /** Exact inverse of {@link worldToMinimap}. Null before any rasterize. */
+    minimapToWorld(px: number, py: number): [number, number] | null;
+}
+
+/**
+ * §16.14 SVG export (S15 export lane) — the M7 pure module.
+ *
+ * ENGINE-INDEPENDENT BY CONSTRUCTION, not by discipline: positions and
+ * projected styles come IN as a plain descriptor, vector markup goes OUT as a
+ * string. No engine, no instance, no DOM — the post-v1 server snapshot path
+ * (spec §13, R-13-53) reuses this verbatim under plain Node, and the test
+ * suite runs it exactly that way. Keeping it engine-free is an M7
+ * requirement, which is why it is a standalone module rather than instance
+ * code that might one day be extracted.
+ *
+ * Output discipline (§16.14):
+ *  - One element per node/edge/label, assembled OFF-DOM by chunked
+ *    array-join — O(elements), never a live DOM node per element.
+ *  - Every label and attribute string is XML-escaped (§14's untrusted-content
+ *    rule in its XML form): a hostile label renders as literal text in every
+ *    downstream vector tool, never as markup.
+ *  - Bounded: above `maxElements` (default 50 000 — the practical ceiling for
+ *    downstream vector editors) rendering THROWS before assembling anything;
+ *    the instance wraps that into the typed `export-too-large` rejection, and
+ *    the raster-hybrid form (a PNG base layer plus a small vector overlay) is
+ *    the sanctioned way past it.
+ */
+interface SvgSceneNode {
+    x: number;
+    y: number;
+    /** Radius in output px (the caller halves its size-buffer diameter). */
+    r: number;
+    /** Any CSS color string (the caller projects RGBA buffers to rgba()). */
+    color: string;
+}
+interface SvgSceneEdge {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color: string;
+    width: number;
+}
+interface SvgSceneLabel {
+    x: number;
+    y: number;
+    /** UNTRUSTED text — escaped here, never pre-escaped by callers (double
+     * escaping is a rendering bug, missing escaping is an injection). */
+    text: string;
+    color: string;
+    /** Font size in px. Default 11. */
+    size?: number;
+}
+interface SvgScene {
+    width: number;
+    height: number;
+    background: string;
+    nodes: readonly SvgSceneNode[];
+    edges: readonly SvgSceneEdge[];
+    labels?: readonly SvgSceneLabel[];
+    /**
+     * Raster-hybrid base layer: a data URI (typically the engine screenshot).
+     * When present, `nodes` and `edges` are expected to be EMPTY — the raster
+     * carries them — and only labels/overlay chrome emit as vectors.
+     */
+    rasterBase?: {
+        href: string;
+    };
+}
+interface RenderSvgOptions {
+    /** Element budget across nodes+edges+labels. Default 50 000. */
+    maxElements?: number;
+}
+declare const SVG_MAX_ELEMENTS_DEFAULT = 50000;
+/** Thrown (not returned) on budget overflow — a pure module has no
+ * diagnostics lane; the instance converts this into `export-too-large`. */
+declare class SvgBudgetError extends Error {
+    readonly elementCount: number;
+    readonly limit: number;
+    constructor(elementCount: number, limit: number);
+}
+declare function escapeXml(text: string): string;
+/**
+ * Render a scene to an SVG document string. Pure: same input, same output,
+ * byte for byte. Throws {@link SvgBudgetError} when the element budget is
+ * exceeded — BEFORE assembling any markup.
+ */
+declare function renderSvg(scene: SvgScene, opts?: RenderSvgOptions): string;
+
+export { ATLAS_MAX_CONCURRENT_DEFAULT, ATLAS_MAX_ENTRIES_DEFAULT, ATLAS_MAX_RETRIES_DEFAULT, AcceptanceQueue, AcceptedEdge, AcceptedGraph, AccessibilityConfig, Accessor, type Adjacency, type AdmitColumnsOptions, type AdmitColumnsResult, type AdmitServiceResultArgs, BASE_PENDING_KEY, BRUSH_HISTORY_COALESCE_MS, BeginIngestOptions, type BrushDelta, BrushState, CATEGORICAL_PALETTE, type CategoricalScale, type CompiledFilter, type CreateGraphInstanceOptions, type CreateRequestContextArgs, CrossfilterSession, type CrossfilterStats, DEFAULT_BIN_COUNT, DIM_ALPHA_DEFAULT, DIVERGING_RANGE_DEFAULT, DimensionSpec, DimensionSummary, type DivergingScale, DomainPolicy, DomainStore, EDGE_PICK_TOLERANCE_PX, EdgeId, type EdgePickRoute, EdgePickingFacade, type EdgePickingFacadeOptions, type EnginePolicy, type EnginePolicyDegradation, type ExpandNodeResult, type ExpansionOverlayRecord, ExpansionService, type FetchLike, type FilterErrorAggregate, FilterExpr, FilterSpec, GRAPH_THEME_DARK, GRAPH_THEME_LIGHT, GraphDiagnostic, GraphEventMap, GraphEventName, GraphHostUpdate, type GraphInstance, GraphListenerControl, GraphNode, type GraphServices, GraphSnapshot, GraphStoreState, GraphTheme, type GraphViewState, type GroupByDerivation, GroupBySpec, type GroupRewrite, GroupSpec, type GroupValidationResult, HISTORY_LIMIT_DEFAULT, type HistoryCommand, type HistoryDepths, HistoryKernel, type HistoryKernelOptions, INGEST_MAX_FLUSH_LATENCY_MS_DEFAULT, INGEST_MAX_PENDING_BYTES_DEFAULT, INGEST_OVERFLOW_FACTOR, type ImageAtlasBatch, ImageAtlasPipeline, type ImageAtlasPipelineOptions, type ImageDecode, type ImageResolver, IngestBatch, IngestSession, JsonValue, LABEL_MAX_VISIBLE_CAP, LABEL_MAX_VISIBLE_DEFAULT, type LabelCandidate, type LabelCandidateResult, type LabelCandidateViewport, LabelConfig, LabelPlacement, type LabelSubscriptions, type LinkPickGridSnapshot, LinkPickIndex, type LinkVisibilityMask, type LocalExpansionBase, type LocalSearchBase, type LocalSearchService, META_EDGE_MAX_WIDTH, type MaskDrain, type MaskSource, type MergeBase, type MergeResult, MetaEdge, type MetaEdgeRecord, MetricColumn, type MetricModelInput, MetricName, MetricStore, NodeId, OVERVIEW_HOT_INTERVAL_MS, OVERVIEW_IDLE_INTERVAL_MS, OVERVIEW_SIZE_DEFAULT, type OverviewBounds, OverviewController, type OverviewControllerOptions, type OverviewRaster, type OverviewScene, PHYSICAL_DEFAULT_LINK_WIDTH, PHYSICAL_DEFAULT_POINT_SIZE, PathOptions, PathResult, PathService, PendingExpansions, type ReconcileResult, Reconciler, type RegisterExpansionResult, RenderScene, type RenderSvgOptions, RequestContext, type RequestContextHandle, type RequestedEngineFeatures, type ResolveDomainArgs, ResolvedCluster, ResolvedGroup, type ResolvedScope, RevisionAwareService, RevisionDimension, type RevisionSnapshot, Revisions, type RowTally, SEARCH_CACHE_LIMIT, SEARCH_LIMIT_DEFAULT, SEARCH_SCAN_CHUNK, SEARCH_SCORE_EXACT_ID, SEARCH_SCORE_ID_PREFIX, SEARCH_SCORE_SUBSTRING, SEARCH_SCORE_TOKEN_START_BONUS, SEQUENTIAL_RANGE_DEFAULT, SUPER_NODE_MAX_SIZE, SVG_MAX_ELEMENTS_DEFAULT, Scale, type ScaleChannelInfo, type ScaleInfoRow, SceneGroups, SceneLinkRef, ScenePointRef, SearchActivation, SearchResult, type SearchService, type SelectLabelCandidatesArgs, SelectionState, type SequentialScale, type SerializableScale, type ServiceCacheKeyArgs, type SessionContribution, type SetViewStateResult, SoftMask, type StageResult, type StagingTallies, type StampedEdge, type StampedNode, SubgraphSpec, type SuperNodeRecord, SvgBudgetError, type SvgScene, type SvgSceneEdge, type SvgSceneLabel, type SvgSceneNode, TIMELINE_STEP_DEFAULT, TIMELINE_TICK_MS_DEFAULT, ThemeInput, TimelinePlayback, TypedColumnCrossfilter, VIEW_STATE_VERSION, type ViewBrushState, type ViewLayoutSpec, type ViewStateVerdict, type ViewStyling, ViewportState, admitServiceResult, assertCapabilityMethodParity, baseFromAccepted, baseFromContribution, buildAcceptedAdjacency, buildAdjacency, canonicalFilterKey, canonicalJson, canonicalScaleKey, cascadeEdges, categoricalIndex, categoricalRows, coerceNumeric, coerceNumericInto, collapseParallelEdges, compileEdgeFilter, compileNodeFilter, computeNumericDomain, createGraphInstance, createLocalExpansionService, createLocalSearchService, createRequestContext, deriveGroupsByKey, divergingColor, escapeXml, estimateBatchBytes, evaluateFilterExpr, groupByDerivedId, groupSceneKey, interpolateColor, medianLinkWidthPx, mergeDiagnostics, mergeModel, metaEdgePublicId, metaEdgeSceneKey, metaEdgeWidthFor, neighborsOf, newContribution, newStagingTallies, nextRequestId, normalizeCommitForCapabilities, parseColor, pointSegmentDistanceSquared, projectColors, projectSizes, renderSvg, resolveEnginePolicy, resolveFilterField, resolveManualGroups, resolveScope, resolveTheme, rewriteGroups, sameDataRef, sameGroupBySpec, sameGroupSpecArrays, sceneGroupsOf, sceneLinkRefAt, scenePointRefAt, selectLabelCandidates, sequentialColor, sequentialSize, serviceCacheKey, sessionCommitDiagnostics, stageBatch, superNodeSizeFor, validateFilterExpr, validateGroupBySpec, validateGroupSpecs, validateSnapshot, validateViewState };