@kortexya/nodus 0.1.0

package/types/hypergraph/Simplifier.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Simplifier driver. Orchestrates iterative atomic-operation application
+ * via a max-priority queue keyed on the priority measure (paper Eq. 1).
+ *
+ * Pipeline (paper §5.1, §5.2):
+ *  1. Compute statistics on H_0.
+ *  2. Enumerate every legal candidate op.
+ *  3. Push into priority queue.
+ *  4. Pop top op → apply → record on reversal stack.
+ *  5. Update statistics over operation footprint (lazy betweenness).
+ *  6. Re-evaluate legality + priority of footprint-touching ops.
+ *  7. Stop when terminating criterion met.
+ */
+import { Hypergraph } from './Hypergraph';
+import type { AtomicOperationRecord, HypergraphData, HypergraphId, SimplificationOptions } from './types';
+export interface SimplifierResult {
+    /** Reversal stack: operations in reverse-application order H_0 → H_n. */
+    operations: AtomicOperationRecord[];
+    /** Captured snapshots H_0, H_1, ..., H_n. */
+    scales: HypergraphData[];
+    /** H_0 cardinality of every hyperedge that has ever existed in any
+     *  scale. Used by the optimizer/reverser to size polygons per paper
+     *  §5.3 ("we use the corresponding cardinalities saved from the
+     *  original scale H_0"). For hyperedges that absorbed others via
+     *  merger, this is the sum of the absorbed H_0 cardinalities. */
+    originalCardinality: Map<HypergraphId, number>;
+}
+export declare class Simplifier {
+    readonly H: Hypergraph;
+    constructor(H: Hypergraph);
+    run(opts?: SimplificationOptions): SimplifierResult;
+    /**
+     * WASM-accelerated path. Interns the hypergraph to integer ids, runs the Rust simplifier
+     * to get the operation sequence + originalCardinality, then replays the sequence on `this.H`
+     * via the real op objects — producing byte-identical records + scales to the pure-TS run.
+     * Returns null (caller falls back to the TS path) when the wasm module isn't loaded.
+     */
+    private _runWasm;
+}

package/types/hypergraph/Statistics.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Statistics over a hypergraph used by the simplifier priority measure
+ * (paper §4.2): vertex degree, hyperedge cardinality, betweenness centrality
+ * (Brandes on the König graph), adjacency factor.
+ */
+import type { HypergraphId } from './types';
+import type { Hypergraph } from './Hypergraph';
+export interface Statistics {
+    degree: Map<HypergraphId, number>;
+    cardinality: Map<HypergraphId, number>;
+    betweenness: Map<HypergraphId, number>;
+    /** Adjacency factor Adj_t(v) and Adj_t(e), parameterized by t. */
+    adjacencyFactor: Map<HypergraphId, number>;
+    /** Pair adjacency a'_{uv} = a_{uv}^t for vertex pairs. Lazy-evaluated via getter. */
+    adjacencyPair: (a: HypergraphId, b: HypergraphId) => number;
+    /** Global ranges for normalizing the priority measure (Eq. 1). */
+    ranges: {
+        degree: {
+            min: number;
+            max: number;
+        };
+        cardinality: {
+            min: number;
+            max: number;
+        };
+        adjacency: {
+            min: number;
+            max: number;
+        };
+        betweenness: {
+            min: number;
+            max: number;
+        };
+    };
+}
+/**
+ * Brandes' algorithm for betweenness centrality on an undirected
+ * unweighted graph. Returns an array indexed by node index.
+ *
+ * Brandes 2001, "A Faster Algorithm for Betweenness Centrality".
+ * O(n·m) time, O(n+m) space. Used here on the König graph K(H).
+ */
+export declare function brandesBetweenness(adj: number[][]): Float64Array;
+/**
+ * Compute all statistics for the priority measure.
+ *
+ * @param t Power in adjacency factor; t=0 reduces to neighborhood size,
+ *          t≥1 emphasizes high-multiplicity sharing. Paper recommends t=2.
+ */
+export declare function computeStatistics<V, E>(H: Hypergraph<V, E>, t?: number): Statistics;
+/**
+ * Adjacency factor (paper §4.2.1):
+ *   Adj_t(v) = Σ_{u≠v} a_{uv}^t,    Adj_t(e) = Σ_{f≠e} a_{ef}^t
+ */
+export declare function computeAdjacencyFactor<V, E>(H: Hypergraph<V, E>, t?: number): Map<HypergraphId, number>;

package/types/hypergraph/forbidden/StrangledHyperedge.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Strangled hyperedge (paper Fig. 6 (d)) — dual of strangled vertex.
+ *
+ * Detection runs the strangled-vertex algorithm on the dual hypergraph
+ * H' = ⟨E, V⟩, where each "vertex" of H' is an original hyperedge and
+ * each "hyperedge" of H' is the set of original hyperedges incident to
+ * an original vertex.
+ */
+import { Hypergraph } from '../Hypergraph';
+import type { ForbiddenSubgraph } from '../types';
+export declare function buildDual<V, E>(H: Hypergraph<V, E>): Hypergraph<E, V>;
+export declare function detectStrangledHyperedge(H: Hypergraph): ForbiddenSubgraph[];

package/types/hypergraph/forbidden/StrangledVertex.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Strangled vertex (paper Fig. 6 (c)).
+ *
+ * A vertex v whose neighborhood H_{V_v ∪ {v}} contains a proper subset
+ * of incident hyperedges and adjacent vertices that form a cycle of
+ * length ≥3 around v in the König-graph sense.
+ *
+ * Detection: build the König-style alternating graph induced by v's
+ * 1-hop hyperedges and 1-hop adjacent vertices. Search for any cycle
+ * passing through ≥3 distinct hyperedges (plus their connecting
+ * vertices) that does NOT include v itself. Such a cycle "strangles"
+ * v because v is enclosed by a closed chain of polygons.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { ForbiddenSubgraph } from '../types';
+export declare function detectStrangledVertex(H: Hypergraph): ForbiddenSubgraph[];

package/types/hypergraph/forbidden/ThreeAdjacentCluster2.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 3-adjacent cluster of 2 hyperedges (paper Fig. 6 (a)).
+ *
+ * A pair (e, f) of hyperedges that share at least 3 common vertices.
+ * Such a pair forces self-intersection or non-strict-convexity in any
+ * polygon representation.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { ForbiddenSubgraph } from '../types';
+export declare function detectThreeAdjacentCluster2(H: Hypergraph): ForbiddenSubgraph[];

package/types/hypergraph/forbidden/TwoAdjacentCluster3.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 2-adjacent cluster of 3 hyperedges (paper Fig. 6 (b)).
+ *
+ * Definition (paper §4.2.1): an "n-adjacent cluster of m hyperedges" is
+ * the partial hypergraph induced by a set of hyperedges J ⊆ E that
+ * **all** contain a common set of n ≥ 2 vertices X ⊆ V — that is, the
+ * intersection ∩_{e∈J} V_e ⊇ X with |X| = n.
+ *
+ * For (b), n = 2 and |J| = 3. Detection: enumerate triples of
+ * hyperedges and count their global intersection size.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { ForbiddenSubgraph } from '../types';
+export declare function detectTwoAdjacentCluster3(H: Hypergraph): ForbiddenSubgraph[];

package/types/hypergraph/forbidden/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Forbidden sub-hypergraph detectors. From paper Theorem 2 / Fig. 6:
+ * a Zykov-planar hypergraph H has a convex polygon representation if
+ * and only if it contains none of:
+ *
+ *   (a) 3-adjacent cluster of 2 hyperedges  — pair sharing ≥3 vertices
+ *   (b) 2-adjacent cluster of 3 hyperedges  — triple where each pair shares ≥2
+ *   (c) Strangled vertex                    — cycle of length ≥3 in the
+ *                                             incidence neighborhood of v
+ *   (d) Strangled hyperedge                 — dual of (c)
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { ForbiddenSubgraph, ForbiddenSubgraphKind, HypergraphId } from '../types';
+import { detectThreeAdjacentCluster2 } from './ThreeAdjacentCluster2';
+import { detectTwoAdjacentCluster3 } from './TwoAdjacentCluster3';
+import { detectStrangledVertex } from './StrangledVertex';
+import { detectStrangledHyperedge } from './StrangledHyperedge';
+export declare const ALL_FORBIDDEN_KINDS: ForbiddenSubgraphKind[];
+export declare function detectAllForbidden(H: Hypergraph, kinds?: ForbiddenSubgraphKind[]): ForbiddenSubgraph[];
+/** Returns true if any forbidden sub-hypergraph touches the given footprint. */
+export declare function forbiddenInFootprint(H: Hypergraph, vSet: Set<HypergraphId>, eSet: Set<HypergraphId>, kinds?: ForbiddenSubgraphKind[]): boolean;
+export { detectThreeAdjacentCluster2, detectTwoAdjacentCluster3, detectStrangledVertex, detectStrangledHyperedge, };

package/types/hypergraph/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Public surface of the hypergraph subsystem. Re-exports the data
+ * model, simplifier, optimizer, reverser, renderers, and types.
+ */
+export { Hypergraph } from './Hypergraph';
+export { buildKoenigGraph, isHyperedgeIndex, type KoenigGraph } from './KoenigGraph';
+export { computeStatistics, computeAdjacencyFactor, brandesBetweenness, type Statistics, } from './Statistics';
+export { VertexRemoval, HyperedgeRemoval, VertexMerger, HyperedgeMerger, enumerateCandidates, operationFromRecord, computePriority, type AtomicOperation, } from './operations';
+export { detectAllForbidden, forbiddenInFootprint, ALL_FORBIDDEN_KINDS, detectThreeAdjacentCluster2, detectTwoAdjacentCluster3, detectStrangledVertex, detectStrangledHyperedge, } from './forbidden';
+export { buildDual } from './forbidden/StrangledHyperedge';
+export { Simplifier, type SimplifierResult } from './Simplifier';
+export { evaluateEnergy, type LayoutModel, } from './layout/Energy';
+export { minimizeLBFGS, type LBFGSOptions, type LBFGSResult } from './layout/LBFGS';
+export { minimizeAdam, type AdamOptions } from './layout/Adam';
+export { optimize, buildModel, refreshModelOrdering, type OptimizerInput, type OptimizerResult, } from './layout/Optimizer';
+export { reverse, type ReverserInput, type ReverserResult, } from './layout/Reverser';
+export { createPolygonDraw, applyDefaults, type PolygonRenderState, } from './render/PolygonRenderer';
+export { createSVGDraw } from './render/SVGPolygonRenderer';
+export { hitTest, screenToWorld, type HitResult, type HitTestState } from './render/Interaction';
+export { adaptOsfkbGraph, fetchOsfkbHypergraph, fetchOsfkbLattice, fetchOsfkbLatticeAll, fetchOsfkbDerivation, fetchOsfkbResiduation, fetchOsfkbTermState, fetchOsfkbGlbLub, fetchOsfkbUnifyTerms, fetchOsfkbFunctions, fetchOsfkbBranchDiff, fetchOsfkbOsfqlAsGraph, fetchOsfkbFuzzyUnify, fetchOsfkbGradedPoset, fetchOsfkbGradedPosetAll, fetchOsfkbSortNeighborhood, subscribeOsfkbDerivationStream, type OsfkbVisualizationGraph, type OsfkbVisualizationResponse, type OsfkbAdapterResult, type OsfkbClientOptions, type OsfkbCoreferenceGroup, type AdaptOptions, } from './osfkb/adapter';
+export type { HypergraphData, HypergraphVertex, HypergraphHyperedge, HypergraphId, HypergraphRenderOptions, InteractionEvent, AtomicOperationKind, AtomicOperationRecord, ForbiddenSubgraph, ForbiddenSubgraphKind, SimplificationOptions, LayoutOptions, LayoutWeights, LayoutProgress, QualityMetrics, Vec2, } from './types';

package/types/hypergraph/layout/Adam.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adam optimizer fallback. Selectable when L-BFGS line search fails on
+ * a pathological dataset.
+ */
+import type { LBFGSOptions, ObjectiveFn, LBFGSResult } from './LBFGS';
+export interface AdamOptions extends Pick<LBFGSOptions, 'maxIter' | 'tol' | 'mask' | 'onIter'> {
+    lr?: number;
+    beta1?: number;
+    beta2?: number;
+    eps?: number;
+}
+export declare function minimizeAdam(f: ObjectiveFn, x0: Float64Array, opts?: AdamOptions): LBFGSResult;

package/types/hypergraph/layout/Energy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Energy terms for the polygon-layout objective (paper §5.3, building
+ * on Qu et al. [41]). Five terms:
+ *
+ *  1. Polygon regularity   E_reg
+ *  2. Polygon area         E_area
+ *  3. Polygon separation   E_sep
+ *  4. Regularity intersection (convexity recovery)  E_int
+ *  5. Primal-dual coordination  E_pd
+ *
+ * State vectors:
+ *   x : Float64Array of length 2|V|  (primal vertex positions)
+ *   y : Float64Array of length 2|E|  (dual vertex positions = primal hyperedge centroids)
+ */
+import type { LayoutWeights } from '../types';
+export interface LayoutModel {
+    /** vertex id → flat index 0..|V|-1 */
+    vIndex: Map<string | number, number>;
+    /** hyperedge id → flat index 0..|E|-1 */
+    eIndex: Map<string | number, number>;
+    vCount: number;
+    eCount: number;
+    /** Per-hyperedge: list of vertex flat-indices (sorted CCW around centroid). */
+    hyperedgeVerts: number[][];
+    /** Per-hyperedge: cardinality (equal to hyperedgeVerts[i].length, cached). */
+    cardinality: number[];
+    /** Per-hyperedge: cardinality used for E_area / E_sep in the regularity
+     *  phase. Paper §5.3: "we use the corresponding cardinalities saved
+     *  from the original scale H_0" — for hyperedges that have absorbed
+     *  others via merger, this is the sum of merged H_0 cardinalities;
+     *  for hyperedges intact since H_0, this equals the H_0 cardinality. */
+    originalCardinality: number[];
+    /** Per-hyperedge: target polygon area A*(k). Computed from
+     *  originalCardinality, not the current k. */
+    targetArea: number[];
+    /** Per-vertex: list of hyperedge flat-indices that contain it. */
+    vertexInHyperedges: number[][];
+    /** Buffer distance d_b for separation energy. */
+    bufferDistance: number;
+    /** Which phase the energy evaluator should use for the separation
+     *  d_0 formula. 'separation' uses Eq. 3 (½ sum of current diameters
+     *  + d_b); 'regularity' uses the circumradius of the regular polygon
+     *  with originalCardinality and targetArea. */
+    phase: 'separation' | 'regularity';
+}
+/**
+ * Compute total energy and its gradient w.r.t. (x, y).
+ *
+ * Returns { energy, grad } where grad is a flat Float64Array of length
+ * 2*(|V| + |E|): first 2|V| entries are ∂E/∂x, next 2|E| are ∂E/∂y.
+ */
+export declare function evaluateEnergy(model: LayoutModel, state: Float64Array, weights: LayoutWeights): {
+    energy: number;
+    grad: Float64Array;
+};

package/types/hypergraph/layout/LBFGS.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Limited-memory BFGS solver. m=8 by default. Backtracking Armijo line
+ * search (sufficient for our convex-ish energy basin once separation is
+ * resolved). No external dependencies.
+ *
+ * Used by the hypergraph layout optimizer; the paper specifically cites
+ * primal-dual quasi-Newton methods because the energy Hessian is ill-
+ * conditioned (regularity term curvature ≫ coordination term curvature).
+ */
+export interface LBFGSOptions {
+    m?: number;
+    maxIter?: number;
+    tol?: number;
+    c1?: number;
+    alphaInit?: number;
+    alphaShrink?: number;
+    maxLineSearch?: number;
+    /** Optional mask: if mask[i] is false, gradient and step are zeroed for index i. */
+    mask?: Uint8Array;
+    onIter?: (iter: number, f: number, gnorm: number) => void;
+}
+export type ObjectiveFn = (x: Float64Array) => {
+    energy: number;
+    grad: Float64Array;
+};
+export interface LBFGSResult {
+    x: Float64Array;
+    energy: number;
+    iterations: number;
+    converged: boolean;
+}
+export declare function minimizeLBFGS(f: ObjectiveFn, x0: Float64Array, opts?: LBFGSOptions): LBFGSResult;

package/types/hypergraph/layout/Optimizer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Two-phase polygon-layout optimizer (paper §5.3).
+ *
+ *  Phase 1 (separation): only E_sep + E_pd active. Spreads apart any
+ *  initial overlaps.
+ *  Phase 2 (regularity):  all five terms active with paper weights.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import { type LayoutModel } from './Energy';
+import type { LayoutOptions, HypergraphId } from '../types';
+import { sortPointsCCW } from '../../geometry/index';
+export interface OptimizerInput {
+    H: Hypergraph;
+    /** Optional initial vertex positions; missing vertices placed on a circle. */
+    initialPositions?: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    /** Optional initial dual positions (hyperedge centroids); auto-computed if absent. */
+    initialDualPositions?: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    /** Original H_0 hyperedge cardinalities. Used by E_area / E_sep in the
+     *  regularity phase per paper §5.3 — when a hyperedge in H_n has
+     *  absorbed others via merger, its target area should reflect the
+     *  total of the merged H_0 cardinalities, not the current H_n vertex
+     *  count. Pass `null`/undefined to fall back to current cardinality. */
+    originalCardinality?: Map<HypergraphId, number>;
+    options: LayoutOptions;
+}
+export interface OptimizerResult {
+    vertexPositions: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    dualPositions: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    energy: number;
+    iterations: number;
+    /** Float64Array state for debugging / chaining. */
+    state: Float64Array;
+    model: LayoutModel;
+}
+export declare function optimize(input: OptimizerInput): OptimizerResult;
+/**
+ * Build the per-call layout model: maps ids to flat indices, sorts each
+ * hyperedge's vertex list CCW around its centroid (by initial positions),
+ * and computes target areas.
+ */
+export declare function buildModel(H: Hypergraph, targetA: (k: number) => number, bufferDistance: number, originalCardinality?: Map<HypergraphId, number>): LayoutModel;
+/**
+ * Re-sort each hyperedge's vertex list CCW around its current centroid.
+ * Called inside the objective so the regularity / area terms see a
+ * coherent ordering even as positions move.
+ */
+export declare function refreshModelOrdering(model: LayoutModel, state: Float64Array): void;
+export { sortPointsCCW };

package/types/hypergraph/layout/Reverser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Iterative reversal with locally-frozen optimization (paper §5.3).
+ *
+ * Pop applied operations off the simplifier stack one at a time; for
+ * each:
+ *   1. Apply the inverse to recover the predecessor scale H_i.
+ *   2. Compute the operation footprint F.
+ *   3. Run the regularity-phase L-BFGS over the full state but with a
+ *      mask that freezes any vertex / dual-vertex outside F. This keeps
+ *      per-step cost roughly constant rather than O(|V|+|E|).
+ */
+import { Hypergraph } from '../Hypergraph';
+import type { AtomicOperationRecord, HypergraphId, LayoutOptions } from '../types';
+export interface ReverserInput {
+    /** Current simplest hypergraph H_n (will be mutated in place into H_0). */
+    H: Hypergraph;
+    /** Reversal stack from the simplifier (most-recent op last). */
+    operations: AtomicOperationRecord[];
+    /** Vertex positions at H_n. */
+    vertexPositions: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    dualPositions: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    /** H_0 cardinalities of every hyperedge that ever existed (paper §5.3). */
+    originalCardinality?: Map<HypergraphId, number>;
+    options: LayoutOptions;
+}
+export interface ReverserResult {
+    vertexPositions: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+    dualPositions: Map<HypergraphId, {
+        x: number;
+        y: number;
+    }>;
+}
+export declare function reverse(input: ReverserInput): ReverserResult;

package/types/hypergraph/operations/AtomicOperation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Atomic simplification operations and their inverses (paper §4.1).
+ *
+ * Four primal-dual pairs:
+ *   - Vertex Removal      ↔ Vertex Addition
+ *   - Hyperedge Removal   ↔ Hyperedge Addition
+ *   - Vertex Merger       ↔ Vertex Split
+ *   - Hyperedge Merger    ↔ Hyperedge Split
+ *
+ * Vertex/hyperedge removal correspond under primal-dual swap, as do
+ * the mergers (Fig. 5 of the paper).
+ */
+import type { AtomicOperationKind, AtomicOperationRecord, HypergraphId } from '../types';
+import type { Hypergraph } from '../Hypergraph';
+import type { Statistics } from '../Statistics';
+export interface OperationCandidate {
+    kind: AtomicOperationKind;
+    vertices: HypergraphId[];
+    hyperedges: HypergraphId[];
+}
+export interface AtomicOperation {
+    kind: AtomicOperationKind;
+    /** Returns true if applying this op preserves connectivity and respects merger legality. */
+    isLegal(H: Hypergraph): boolean;
+    /** Apply mutation. Returns a record sufficient to invert. */
+    apply(H: Hypergraph): AtomicOperationRecord;
+    /** Reverse a previously applied operation given its record. */
+    invert(H: Hypergraph, record: AtomicOperationRecord): void;
+    /** Footprint = elements affected (used for local re-optimization on reversal). */
+    footprint(H: Hypergraph): {
+        vertices: HypergraphId[];
+        hyperedges: HypergraphId[];
+    };
+    /** Priority (paper Eq. 1 + max-of-footprint per Eq. 2). */
+    priority(H: Hypergraph, S: Statistics, weights: {
+        alpha: number;
+        beta: number;
+        gamma: number;
+    }): number;
+}
+/**
+ * Compute paper Eq. 1: P(O) = α·d̂_O' + β·ā_O' + γ·b̄_O' where each
+ * primed value is normalized via global min/max ranges of S.
+ *
+ * d̂_O = max(degree, cardinality) over the operation footprint (Eq. 2).
+ * ā_O  = average adjacency factor of the operands (only meaningful for
+ *        merger ops; for removal ops we use the operand's own factor).
+ * b̄_O  = average betweenness of the operands.
+ */
+export declare function computePriority(S: Statistics, weights: {
+    alpha: number;
+    beta: number;
+    gamma: number;
+}, footprintMaxDegOrCard: number, operandsAvgAdj: number, operandsAvgBetween: number): number;

package/types/hypergraph/operations/HyperedgeMerger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Hyperedge Merger: collapses a pair of adjacent hyperedges (e, f) into
+ * a single hyperedge (we keep `e` and absorb `f`). The retained
+ * hyperedge's vertex set becomes V_e ∪ V_f.
+ *
+ * Legality (paper §5.1): legal iff a_{ef} ≥ 2 (the hyperedges share ≥2
+ * vertices) — guarantees the merger doesn't introduce non-adjacent pairs.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { Statistics } from '../Statistics';
+import type { AtomicOperationRecord, HypergraphId } from '../types';
+import { type AtomicOperation } from './AtomicOperation';
+export declare class HyperedgeMerger implements AtomicOperation {
+    readonly retained: HypergraphId;
+    readonly absorbed: HypergraphId;
+    kind: "hyperedgeMerger";
+    constructor(retained: HypergraphId, absorbed: HypergraphId);
+    isLegal(H: Hypergraph): boolean;
+    apply(H: Hypergraph): AtomicOperationRecord;
+    invert(H: Hypergraph, record: AtomicOperationRecord): void;
+    footprint(H: Hypergraph): {
+        vertices: HypergraphId[];
+        hyperedges: HypergraphId[];
+    };
+    priority(H: Hypergraph, S: Statistics, w: {
+        alpha: number;
+        beta: number;
+        gamma: number;
+    }): number;
+}

package/types/hypergraph/operations/HyperedgeRemoval.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hyperedge Removal: deletes a hyperedge e from H. Dual of vertex removal.
+ *
+ * Legality (paper §5.1): every pair of vertices incident to e must remain
+ * adjacent (share at least one other hyperedge). Plus connectivity.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { Statistics } from '../Statistics';
+import type { AtomicOperationRecord, HypergraphId } from '../types';
+import { type AtomicOperation } from './AtomicOperation';
+export declare class HyperedgeRemoval implements AtomicOperation {
+    readonly eid: HypergraphId;
+    kind: "hyperedgeRemoval";
+    constructor(eid: HypergraphId);
+    isLegal(H: Hypergraph): boolean;
+    apply(H: Hypergraph): AtomicOperationRecord;
+    invert(H: Hypergraph, record: AtomicOperationRecord): void;
+    footprint(H: Hypergraph): {
+        vertices: HypergraphId[];
+        hyperedges: HypergraphId[];
+    };
+    priority(H: Hypergraph, S: Statistics, w: {
+        alpha: number;
+        beta: number;
+        gamma: number;
+    }): number;
+}

package/types/hypergraph/operations/VertexMerger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Vertex Merger: collapses a pair of adjacent vertices (u, v) into a
+ * single vertex (we keep `u` and absorb `v`). The retained vertex's
+ * incidence becomes E_u ∪ E_v.
+ *
+ * Legality (paper §5.1): legal iff a_{uv} ≥ 2 (the vertices already share
+ * ≥2 hyperedges) — guarantees the merger doesn't introduce non-adjacent
+ * pairs of remaining elements. Plus connectivity (always preserved by a
+ * merger of adjacent vertices in a connected hypergraph).
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { Statistics } from '../Statistics';
+import type { AtomicOperationRecord, HypergraphId } from '../types';
+import { type AtomicOperation } from './AtomicOperation';
+export declare class VertexMerger implements AtomicOperation {
+    readonly retained: HypergraphId;
+    readonly absorbed: HypergraphId;
+    kind: "vertexMerger";
+    constructor(retained: HypergraphId, absorbed: HypergraphId);
+    isLegal(H: Hypergraph): boolean;
+    apply(H: Hypergraph): AtomicOperationRecord;
+    invert(H: Hypergraph, record: AtomicOperationRecord): void;
+    footprint(H: Hypergraph): {
+        vertices: HypergraphId[];
+        hyperedges: HypergraphId[];
+    };
+    priority(H: Hypergraph, S: Statistics, w: {
+        alpha: number;
+        beta: number;
+        gamma: number;
+    }): number;
+}

package/types/hypergraph/operations/VertexRemoval.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Vertex Removal: deletes a vertex v from H. The vertex is removed from
+ * every incident hyperedge's vertex set. Inverse: re-add v with its
+ * original incidence list.
+ *
+ * Legality (paper §5.1): removal is legal only if no pair of hyperedges
+ * incident to v becomes non-adjacent as a consequence. We also require
+ * connectivity preservation.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { Statistics } from '../Statistics';
+import type { AtomicOperationRecord, HypergraphId } from '../types';
+import { type AtomicOperation } from './AtomicOperation';
+export declare class VertexRemoval implements AtomicOperation {
+    readonly vid: HypergraphId;
+    kind: "vertexRemoval";
+    constructor(vid: HypergraphId);
+    isLegal(H: Hypergraph): boolean;
+    apply(H: Hypergraph): AtomicOperationRecord;
+    invert(H: Hypergraph, record: AtomicOperationRecord): void;
+    footprint(H: Hypergraph): {
+        vertices: HypergraphId[];
+        hyperedges: HypergraphId[];
+    };
+    priority(H: Hypergraph, S: Statistics, w: {
+        alpha: number;
+        beta: number;
+        gamma: number;
+    }): number;
+}

package/types/hypergraph/operations/index.d.ts

@@ -0,0 +1,19 @@
+export { VertexRemoval } from './VertexRemoval';
+export { HyperedgeRemoval } from './HyperedgeRemoval';
+export { VertexMerger } from './VertexMerger';
+export { HyperedgeMerger } from './HyperedgeMerger';
+export { computePriority } from './AtomicOperation';
+export type { AtomicOperation, OperationCandidate } from './AtomicOperation';
+import type { AtomicOperation } from './AtomicOperation';
+import type { AtomicOperationRecord } from '../types';
+import type { Hypergraph } from '../Hypergraph';
+/**
+ * Reconstruct an operation object from a record so the simplifier can
+ * invert ops it didn't synthesize itself (e.g. on JSON-roundtrip).
+ */
+export declare function operationFromRecord(record: AtomicOperationRecord): AtomicOperation;
+/**
+ * Enumerate all candidate operations on the given hypergraph.
+ * Used by the simplifier to seed its priority queue.
+ */
+export declare function enumerateCandidates(H: Hypergraph): AtomicOperation[];