@nshiab/simple-data-analysis-core 2.0.9 → 2.1.0

package/esm/helpers/buildApproximateMutualReachabilityMst.d.ts

@@ -0,0 +1,45 @@
+import { type DuckDBConnection } from "@duckdb/node-api";
+/**
+ * Build an explicitly approximate mutual-reachability MST. HNSW supplies a
+ * high-recall k-neighbor candidate graph; disconnected components are repaired
+ * with deterministic all-member projection sweeps. Neither step guarantees the
+ * complete graph's MST.
+ */
+export default function buildApproximateMutualReachabilityMst(connection: DuckDBConnection, input: {
+    count: number;
+    dimensions: number;
+    minSamples: number;
+}, options: {
+    metric: "euclidean" | "cosine";
+}, names: {
+    rows: string;
+    neighbors: string;
+    search: string;
+    hnsw: string;
+    candidates: string;
+    coreDistances: string;
+    edges: string;
+    components: string;
+    representatives: string;
+    componentPairs: string;
+    bridgeCandidates: string;
+    mst: string;
+}): Promise<{
+    candidateComponents: number;
+    neighborCount: number;
+}>;
+/** Internal connectivity-repair seam used by focused approximation tests. */
+export declare function repairApproximateConnectivity(connection: DuckDBConnection, input: {
+    count: number;
+}, options: {
+    metric: "euclidean" | "cosine";
+}, names: {
+    rows: string;
+    coreDistances: string;
+    edges: string;
+    components: string;
+    representatives: string;
+    componentPairs: string;
+    bridgeCandidates: string;
+}): Promise<number>;
+//# sourceMappingURL=buildApproximateMutualReachabilityMst.d.ts.map

package/esm/helpers/buildApproximateMutualReachabilityMst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildApproximateMutualReachabilityMst.d.ts","sourceRoot":"","sources":["../../src/helpers/buildApproximateMutualReachabilityMst.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,gBAAgB,EAAW,MAAM,kBAAkB,CAAC;AAQ1E;;;;;GAKG;AACH,wBAA8B,qCAAqC,CACjE,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAChE,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAA;CAAE,EAC3C,KAAK,EAAE;IACL,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;CACb,GACA,OAAO,CAAC;IAAE,mBAAmB,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAsFjE;AAED,6EAA6E;AAC7E,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EACxB,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAA;CAAE,EAC3C,KAAK,EAAE;IACL,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,MAAM,CAAC,CAsHjB"}

package/esm/helpers/buildApproximateMutualReachabilityMst.js

@@ -0,0 +1,212 @@
+import { DOUBLE, INTEGER } from "@duckdb/node-api";
+import appendColumnBatches from "./appendColumnBatches.js";
+import buildSparseMutualReachabilityMst from "./buildSparseMutualReachabilityMst.js";
+import buildVectorNeighbors from "./buildVectorNeighbors.js";
+import inspectGraphConnectivity from "./inspectGraphConnectivity.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+import vectorDistanceExpression from "./vectorDistanceExpression.js";
+/**
+ * Build an explicitly approximate mutual-reachability MST. HNSW supplies a
+ * high-recall k-neighbor candidate graph; disconnected components are repaired
+ * with deterministic all-member projection sweeps. Neither step guarantees the
+ * complete graph's MST.
+ */
+export default async function buildApproximateMutualReachabilityMst(connection, input, options, names) {
+    const q = quoteIdentifier;
+    const quoted = Object.fromEntries(Object.entries(names).map(([key, value]) => [key, q(value)]));
+    const neighborCount = Math.min(input.count - 1, Math.max(input.minSamples, 64));
+    await buildVectorNeighbors(connection, {
+        count: input.count,
+        dimensions: input.dimensions,
+        neighborCount,
+    }, {
+        metric: options.metric,
+        search: "hnsw",
+        includeSelf: false,
+        hnsw: {
+            efConstruction: 256,
+            efSearch: Math.max(512, neighborCount * 2),
+            connectivity: 32,
+            candidateCount: Math.min(input.count, neighborCount * 2 + 1),
+            singleThreaded: true,
+            cosineAsL2: true,
+        },
+    }, {
+        rows: quoted.rows,
+        neighbors: quoted.neighbors,
+        search: quoted.search,
+        hnsw: quoted.hnsw,
+        candidates: quoted.candidates,
+    });
+    await connection.run(`CREATE OR REPLACE TEMP TABLE ${quoted.coreDistances} AS
+    SELECT source AS vertex,distance
+    FROM ${quoted.neighbors} WHERE rank=${input.minSamples - 1};
+    CREATE OR REPLACE TEMP TABLE ${quoted.edges} AS
+    SELECT least(n.source,n.target)::INTEGER AS source,
+      greatest(n.source,n.target)::INTEGER AS target,
+      min(greatest(cs.distance,ct.distance,n.distance))::DOUBLE AS distance
+    FROM ${quoted.neighbors} n
+    JOIN ${quoted.coreDistances} cs ON cs.vertex=n.source
+    JOIN ${quoted.coreDistances} ct ON ct.vertex=n.target
+    GROUP BY least(n.source,n.target),greatest(n.source,n.target)`);
+    await connection.run(`DROP TABLE IF EXISTS ${quoted.neighbors};
+    DROP TABLE IF EXISTS ${quoted.candidates};
+    DROP TABLE IF EXISTS ${quoted.search}`);
+    const componentCount = await repairApproximateConnectivity(connection, { count: input.count }, options, {
+        rows: names.rows,
+        coreDistances: names.coreDistances,
+        edges: names.edges,
+        components: names.components,
+        representatives: names.representatives,
+        componentPairs: names.componentPairs,
+        bridgeCandidates: names.bridgeCandidates,
+    });
+    const mst = await buildSparseMutualReachabilityMst(connection, quoted.edges, input.count);
+    await connection.run(`CREATE OR REPLACE TEMP TABLE ${quoted.mst}
+      (source INTEGER,target INTEGER,distance DOUBLE)`);
+    await appendColumnBatches(connection, names.mst, [INTEGER, INTEGER, DOUBLE], mst.length, (column, start, end) => mst.slice(start, end).map((edge) => column === 0 ? edge.source : column === 1 ? edge.target : edge.distance));
+    return { candidateComponents: componentCount, neighborCount };
+}
+/** Internal connectivity-repair seam used by focused approximation tests. */
+export async function repairApproximateConnectivity(connection, input, options, names) {
+    const q = quoteIdentifier;
+    const quoted = Object.fromEntries(Object.entries(names).map(([key, value]) => [key, q(value)]));
+    const componentOf = await readComponents(connection, quoted.edges, input.count);
+    let maximumComponent = -1;
+    for (const component of componentOf) {
+        if (component > maximumComponent)
+            maximumComponent = component;
+    }
+    const componentCount = maximumComponent + 1;
+    if (componentCount > 1) {
+        await createComponentRows(connection, names.components, componentOf);
+        // Each sweep examines every point, rather than a fixed representative
+        // sample. Consecutive component runs in the projected order provide a
+        // connected backbone, while multiple directions offer alternative edges.
+        // We also connect each member of a run to the nearest projected endpoint
+        // in both adjacent runs. All weights are recomputed in the actual metric.
+        const dimensions = Number((await connection.runAndReadAll(`SELECT len(vec) FROM ${quoted.rows} LIMIT 1`)).getRowsJS()[0][0]);
+        await connection.run(`CREATE OR REPLACE TEMP TABLE ${quoted.bridgeCandidates}
+      (source INTEGER,target INTEGER,distance DOUBLE)`);
+        const rawDistance = vectorDistanceExpression("a.vec", "b.vec", options.metric);
+        const projectionCount = Math.min(dimensions, 8) + (dimensions > 1 ? 16 : 0);
+        for (let projection = 0; projection < projectionCount; projection++) {
+            // Coordinate directions handle axis-aligned and one-dimensional data;
+            // fixed pseudo-random directions cover rotated component boundaries.
+            // Coefficients do not depend on table names, execution order, or RNG state.
+            const coefficients = Array.from({ length: dimensions }, (_, dimension) => {
+                if (projection < Math.min(dimensions, 8)) {
+                    return dimension === projection ? 1 : 0;
+                }
+                let hash = Math.imul(projection + 1, 0x9e3779b1) ^
+                    Math.imul(dimension + 1, 0x85ebca6b);
+                hash = Math.imul(hash ^ (hash >>> 16), 0x7feb352d);
+                hash = Math.imul(hash ^ (hash >>> 15), 0x846ca68b);
+                return ((hash ^ (hash >>> 16)) >>> 0) / 0x100000000 * 2 - 1;
+            });
+            // Scaling each coordinate by the same global factor prevents overflow
+            // in the projection without changing its ordering. Unit directions are
+            // the appropriate search geometry for cosine.
+            const vector = options.metric === "cosine"
+                ? `list_transform(r.vec,x -> x/sqrt(array_inner_product(r.vec,r.vec)))::DOUBLE[${dimensions}]`
+                : `list_transform(r.vec,x -> x/scale.maximum)::DOUBLE[${dimensions}]`;
+            await connection.run(`CREATE OR REPLACE TEMP TABLE ${quoted.representatives} AS
+        WITH projected AS (
+          SELECT r.vertex,c.component,
+            array_inner_product(${vector},[${coefficients.join(",")}]::DOUBLE[${dimensions}]) AS position
+          FROM ${quoted.rows} r JOIN ${quoted.components} c USING(vertex)
+          CROSS JOIN (SELECT greatest(1,max(list_max(list_transform(vec,x -> abs(x))))) AS maximum FROM ${quoted.rows}) scale
+        ), ordered AS (
+          SELECT *,lag(component) OVER w AS previous_component,
+            lead(component) OVER w AS next_component,
+            lag(vertex) OVER w AS previous_vertex,
+            lead(vertex) OVER w AS next_vertex
+          FROM projected WINDOW w AS (ORDER BY position,vertex)
+        )
+        SELECT vertex,
+          last_value(CASE WHEN component != previous_component THEN previous_vertex END IGNORE NULLS)
+            OVER (ORDER BY position,vertex ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS left_vertex,
+          first_value(CASE WHEN component != next_component THEN next_vertex END IGNORE NULLS)
+            OVER (ORDER BY position,vertex ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING) AS right_vertex
+        FROM ordered;
+        INSERT INTO ${quoted.bridgeCandidates}
+        SELECT least(a.vertex,b.vertex)::INTEGER,greatest(a.vertex,b.vertex)::INTEGER,
+          greatest(ca.distance,cb.distance,${rawDistance})::DOUBLE
+        FROM (SELECT vertex,unnest([left_vertex,right_vertex]) AS target FROM ${quoted.representatives}) p
+        JOIN ${quoted.rows} a ON a.vertex=p.vertex
+        JOIN ${quoted.rows} b ON b.vertex=p.target
+        JOIN ${quoted.coreDistances} ca ON ca.vertex=a.vertex
+        JOIN ${quoted.coreDistances} cb ON cb.vertex=b.vertex`);
+        }
+        const invalidBridgeDistances = Number((await connection.runAndReadAll(`SELECT count(*) FROM ${quoted.bridgeCandidates}
+       WHERE distance IS NULL OR NOT isfinite(distance)`)).getRowsJS()[0][0]);
+        if (invalidBridgeDistances > 0) {
+            throw new Error(`Approximate HDBSCAN connectivity repair produced ${invalidBridgeDistances} non-finite candidate distances. Rescale the input features.`);
+        }
+        await connection.run(`INSERT INTO ${quoted.edges}
+      SELECT source,target,min(distance) AS distance
+      FROM ${quoted.bridgeCandidates} GROUP BY source,target`);
+    }
+    const connectivity = await inspectGraphConnectivity(connection, quoted.edges, input.count);
+    if (connectivity.componentCount !== 1) {
+        throw new Error(`Approximate HDBSCAN connectivity repair left ${connectivity.componentCount} graph components.`);
+    }
+    return componentCount;
+}
+async function readComponents(connection, edges, count) {
+    const parent = new Int32Array(count);
+    const size = new Int32Array(count).fill(1);
+    for (let vertex = 0; vertex < count; vertex++)
+        parent[vertex] = vertex;
+    const find = (start) => {
+        let root = start;
+        while (parent[root] !== root)
+            root = parent[root];
+        let current = start;
+        while (parent[current] !== current) {
+            const next = parent[current];
+            parent[current] = root;
+            current = next;
+        }
+        return root;
+    };
+    const union = (left, right) => {
+        let a = find(left), b = find(right);
+        if (a === b)
+            return;
+        if (size[a] < size[b])
+            [a, b] = [b, a];
+        parent[b] = a;
+        size[a] += size[b];
+    };
+    const result = await connection.stream(`SELECT source,target FROM ${edges}`);
+    while (true) {
+        const chunk = await result.fetchChunk();
+        if (!chunk || chunk.rowCount === 0)
+            break;
+        const sources = chunk.getColumnVector(0);
+        const targets = chunk.getColumnVector(1);
+        for (let row = 0; row < chunk.rowCount; row++) {
+            union(Number(sources.getItem(row)), Number(targets.getItem(row)));
+        }
+    }
+    const minimum = new Map();
+    for (let vertex = 0; vertex < count; vertex++) {
+        const root = find(vertex);
+        minimum.set(root, Math.min(minimum.get(root) ?? vertex, vertex));
+    }
+    const ids = [...minimum]
+        .sort((a, b) => a[1] - b[1])
+        .map(([root], component) => [root, component]);
+    const componentByRoot = new Map(ids);
+    const componentOf = new Int32Array(count);
+    for (let vertex = 0; vertex < count; vertex++) {
+        componentOf[vertex] = componentByRoot.get(find(vertex));
+    }
+    return componentOf;
+}
+async function createComponentRows(connection, name, componentOf) {
+    await connection.run(`CREATE OR REPLACE TEMP TABLE ${quoteIdentifier(name)}
+      (vertex INTEGER,component INTEGER)`);
+    await appendColumnBatches(connection, name, [INTEGER, INTEGER], componentOf.length, (column, start, end) => Array.from({ length: end - start }, (_, offset) => column === 0 ? start + offset : componentOf[start + offset]));
+}

package/esm/helpers/buildChronologicalGraphComponentsSql.d.ts

@@ -0,0 +1,14 @@
+import type { PreparedGraphTemporalSql } from "./prepareGraphTemporalSql.js";
+import type { PreparedGraphSql } from "./prepareGraphTraversal.js";
+/** Builds all-pairs chronological reachability and maximal-clique membership SQL. */
+export default function buildChronologicalGraphComponentsSql(prepared: PreparedGraphSql, temporal: PreparedGraphTemporalSql): string;
+export type MaximalGraphCliqueRelations = {
+    adjacency: string;
+    initial: string;
+    maximal: string;
+    numbered: string;
+    search: string;
+};
+/** Builds pivoted Bron–Kerbosch CTEs over typed node and mutual-edge relations. */
+export declare function buildMaximalGraphCliquesSql(nodes: string, mutual: string, relations: MaximalGraphCliqueRelations): string;
+//# sourceMappingURL=buildChronologicalGraphComponentsSql.d.ts.map

package/esm/helpers/buildChronologicalGraphComponentsSql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildChronologicalGraphComponentsSql.d.ts","sourceRoot":"","sources":["../../src/helpers/buildChronologicalGraphComponentsSql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,qFAAqF;AACrF,MAAM,CAAC,OAAO,UAAU,oCAAoC,CAC1D,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,wBAAwB,GACjC,MAAM,CA+ER;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,2BAA2B,GACrC,MAAM,CA2FR"}

package/esm/helpers/buildChronologicalGraphComponentsSql.js

@@ -0,0 +1,167 @@
+import buildGraphTemporalReachabilitySql from "./buildGraphTemporalReachabilitySql.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+/** Builds all-pairs chronological reachability and maximal-clique membership SQL. */
+export default function buildChronologicalGraphComponentsSql(prepared, temporal) {
+    const q = quoteIdentifier;
+    // Temporal mutual reachability is not transitive: groups are maximal cliques
+    // that may overlap. Returning every group has exponential worst-case output.
+    const reachability = buildGraphTemporalReachabilitySql(prepared, (edges) => `SELECT ${q("__from")} AS ${q("start")},
+          ${q("__from_key")} AS ${q("__key")}
+        FROM ${edges}
+        UNION
+        SELECT ${q("__to")}, ${q("__to_key")} FROM ${edges}`, "outgoing", temporal);
+    const relations = prepared.relationNames([
+        "graph_component_nodes",
+        "graph_component_reachability",
+        "graph_mutual_neighbors",
+        "graph_mutual_adjacency",
+        "graph_clique_initial",
+        "graph_clique_search",
+        "graph_maximal_cliques",
+        "graph_numbered_cliques",
+    ]);
+    const nodes = relations.graph_component_nodes;
+    const reached = relations.graph_component_reachability;
+    const mutual = relations.graph_mutual_neighbors;
+    const adjacency = relations.graph_mutual_adjacency;
+    const initial = relations.graph_clique_initial;
+    const search = relations.graph_clique_search;
+    const maximal = relations.graph_maximal_cliques;
+    const numbered = relations.graph_numbered_cliques;
+    const edges = reachability.edgesRelation;
+    const reachable = reachability.reachableRelation;
+    return `${reachability.withClause}, ${nodes} AS MATERIALIZED (
+      SELECT ${q("node")}, ${q("__key")}
+      FROM (
+        SELECT ${q("__from")} AS ${q("node")},
+          ${q("__from_key")} AS ${q("__key")}
+        FROM ${edges}
+        UNION
+        SELECT ${q("__to")}, ${q("__to_key")} FROM ${edges}
+      ) AS ${q("valid_nodes")}
+    ), ${reached} AS MATERIALIZED (
+      SELECT ${q("__start_key")}, ${q("__node_key")}
+      FROM ${reachable}
+      UNION
+      SELECT ${q("__key")}, ${q("__key")} FROM ${nodes}
+    ), ${mutual} AS MATERIALIZED (
+      SELECT ${q("forward")}.${q("__start_key")} AS ${q("__key")},
+        ${q("forward")}.${q("__node_key")} AS ${q("__neighbor_key")}
+      FROM ${reached} AS ${q("forward")}
+      INNER JOIN ${reached} AS ${q("reverse")}
+        ON ${q("forward")}.${q("__start_key")} =
+          ${q("reverse")}.${q("__node_key")}
+        AND ${q("forward")}.${q("__node_key")} =
+          ${q("reverse")}.${q("__start_key")}
+      WHERE ${q("forward")}.${q("__start_key")} !=
+        ${q("forward")}.${q("__node_key")}
+    ), ${buildMaximalGraphCliquesSql(nodes, mutual, {
+        adjacency,
+        initial,
+        maximal,
+        numbered,
+        search,
+    })}
+    SELECT ${q("numbered")}.${q("componentId")},
+      ${q("nodes")}.${q("node")}
+    FROM ${numbered} AS ${q("numbered")}
+    CROSS JOIN unnest(${q("numbered")}.${q("__members")}) WITH ORDINALITY
+      AS ${q("member")}(${q("__key")}, ${q("__order")})
+    INNER JOIN ${nodes} AS ${q("nodes")}
+      ON ${q("member")}.${q("__key")} = ${q("nodes")}.${q("__key")}
+    ORDER BY ${q("numbered")}.${q("componentId")},
+      ${q("member")}.${q("__order")}`;
+}
+/** Builds pivoted Bron–Kerbosch CTEs over typed node and mutual-edge relations. */
+export function buildMaximalGraphCliquesSql(nodes, mutual, relations) {
+    const q = quoteIdentifier;
+    const { adjacency, initial, maximal, numbered, search } = relations;
+    // Sibling candidates are P minus the pivot's neighbors. For branch v, move
+    // only earlier siblings (candidate < v and outside N(pivot)) from P to X;
+    // earlier P vertices inside N(pivot) must remain prospective.
+    return `${adjacency} AS MATERIALIZED (
+      SELECT ${q("nodes")}.${q("__key")},
+        COALESCE(
+          list(${q("mutual")}.${q("__neighbor_key")}
+            ORDER BY ${q("mutual")}.${q("__neighbor_key")})
+            FILTER (WHERE ${q("mutual")}.${q("__neighbor_key")} IS NOT NULL),
+          list_slice(list_value(${q("nodes")}.${q("__key")}), 1, 0)
+        ) AS ${q("__neighbors")}
+      FROM ${nodes} AS ${q("nodes")}
+      LEFT JOIN ${mutual} AS ${q("mutual")}
+        ON ${q("nodes")}.${q("__key")} = ${q("mutual")}.${q("__key")}
+      GROUP BY ${q("nodes")}.${q("__key")}
+    ), ${initial} AS MATERIALIZED (
+      SELECT list_slice(${q("__keys")}, 1, 0) AS ${q("__r")},
+        ${q("__keys")} AS ${q("__p")},
+        list_slice(${q("__keys")}, 1, 0) AS ${q("__x")}
+      FROM (
+        SELECT list(${q("__key")} ORDER BY ${q("__key")}) AS ${q("__keys")}
+        FROM ${nodes}
+      ) AS ${q("all_nodes")}
+      WHERE ${q("__keys")} IS NOT NULL
+    ), ${search}(${q("__r")}, ${q("__p")}, ${q("__x")}) AS (
+      SELECT ${q("__r")}, ${q("__p")}, ${q("__x")} FROM ${initial}
+      UNION ALL
+      SELECT list_append(${q("state")}.${q("__r")},
+          ${q("branch")}.${q("__key")}),
+        list_filter(${q("state")}.${q("__p")}, ${q("candidate")} ->
+          list_contains(${q("branch_neighbors")}.${q("__neighbors")},
+            ${q("candidate")})
+          AND (
+            ${q("candidate")} >= ${q("branch")}.${q("__key")}
+            OR list_contains(${q("pivot")}.${q("__neighbors")},
+              ${q("candidate")})
+          )),
+        list_filter(
+          list_concat(${q("state")}.${q("__x")},
+            ${q("state")}.${q("__p")}),
+          ${q("candidate")} ->
+            list_contains(${q("branch_neighbors")}.${q("__neighbors")},
+              ${q("candidate")})
+            AND (
+              list_contains(${q("state")}.${q("__x")}, ${q("candidate")})
+              OR (
+                ${q("candidate")} < ${q("branch")}.${q("__key")}
+                AND NOT list_contains(${q("pivot")}.${q("__neighbors")},
+                  ${q("candidate")})
+              )
+            )
+        )
+      FROM ${search} AS ${q("state")}
+      CROSS JOIN LATERAL (
+        SELECT ${q("candidate_adjacency")}.${q("__key")},
+          ${q("candidate_adjacency")}.${q("__neighbors")}
+        FROM unnest(list_concat(${q("state")}.${q("__p")},
+          ${q("state")}.${q("__x")})) AS ${q("candidate_key")}(${q("__key")})
+        INNER JOIN ${adjacency} AS ${q("candidate_adjacency")}
+          ON ${q("candidate_key")}.${q("__key")} =
+            ${q("candidate_adjacency")}.${q("__key")}
+        ORDER BY list_unique(list_intersect(
+            ${q("state")}.${q("__p")},
+            ${q("candidate_adjacency")}.${q("__neighbors")}
+          )) DESC,
+          ${q("candidate_adjacency")}.${q("__key")}
+        LIMIT 1
+      ) AS ${q("pivot")}
+      CROSS JOIN LATERAL (
+        SELECT ${q("candidate")}.${q("__key")}
+        FROM unnest(${q("state")}.${q("__p")})
+          AS ${q("candidate")}(${q("__key")})
+        WHERE NOT list_contains(${q("pivot")}.${q("__neighbors")},
+          ${q("candidate")}.${q("__key")})
+      ) AS ${q("branch")}
+      INNER JOIN ${adjacency} AS ${q("branch_neighbors")}
+        ON ${q("branch")}.${q("__key")} =
+          ${q("branch_neighbors")}.${q("__key")}
+    ), ${maximal} AS MATERIALIZED (
+      SELECT list_sort(${q("__r")}) AS ${q("__members")}
+      FROM ${search}
+      WHERE len(${q("__p")}) = 0 AND len(${q("__x")}) = 0
+    ), ${numbered} AS MATERIALIZED (
+      SELECT ${q("__members")},
+        CAST(row_number() OVER (ORDER BY ${q("__members")}) - 1 AS BIGINT)
+          AS ${q("componentId")}
+      FROM ${maximal}
+    )`;
+}

package/esm/helpers/buildExactMutualReachabilityMst.d.ts

@@ -0,0 +1,28 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+/** Private, already-quoted relation names owned and cleaned up by the caller. */
+export type MutualReachabilityTables = {
+    rows: string;
+    coreDistances: string;
+    frontier: string;
+    mst: string;
+};
+/**
+ * Build an exact HDBSCAN mutual-reachability MST with bounded materialization.
+ *
+ * The prepared rows relation must contain contiguous INTEGER `vertex` ids and
+ * fixed-size DOUBLE `vec` values. `minSamples` excludes the point itself. Core
+ * distance calculation uses bounded top-k aggregates and retains one scalar per
+ * point. Prim's algorithm retains one frontier edge per unvisited point. This
+ * costs O(n²d) distance work, O(n) stored algorithm state, and O(n) sequential
+ * DuckDB statements; it is intended as the exact correctness baseline.
+ * Cosine preparation may rescale the private vec column, preserving direction.
+ * All supplied scratch names are already quoted, distinct, and caller-owned;
+ * the caller must drop them in finally on both success and failure.
+ */
+export default function buildExactMutualReachabilityMst(connection: DuckDBConnection, input: {
+    count: number;
+    minSamples: number;
+}, options: {
+    metric: "euclidean" | "cosine";
+}, names: MutualReachabilityTables): Promise<void>;
+//# sourceMappingURL=buildExactMutualReachabilityMst.d.ts.map

package/esm/helpers/buildExactMutualReachabilityMst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildExactMutualReachabilityMst.d.ts","sourceRoot":"","sources":["../../src/helpers/buildExactMutualReachabilityMst.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD,iFAAiF;AACjF,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAA8B,+BAA+B,CAC3D,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAA;CAAE,EAC3C,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Gf"}

package/esm/helpers/buildExactMutualReachabilityMst.js

@@ -0,0 +1,97 @@
+import readScalarNumber from "./readScalarNumber.js";
+import vectorDistanceExpression from "./vectorDistanceExpression.js";
+import stabilizeCosineVectors from "./stabilizeCosineVectors.js";
+import validateVectorRowIds from "./validateVectorRowIds.js";
+/**
+ * Build an exact HDBSCAN mutual-reachability MST with bounded materialization.
+ *
+ * The prepared rows relation must contain contiguous INTEGER `vertex` ids and
+ * fixed-size DOUBLE `vec` values. `minSamples` excludes the point itself. Core
+ * distance calculation uses bounded top-k aggregates and retains one scalar per
+ * point. Prim's algorithm retains one frontier edge per unvisited point. This
+ * costs O(n²d) distance work, O(n) stored algorithm state, and O(n) sequential
+ * DuckDB statements; it is intended as the exact correctness baseline.
+ * Cosine preparation may rescale the private vec column, preserving direction.
+ * All supplied scratch names are already quoted, distinct, and caller-owned;
+ * the caller must drop them in finally on both success and failure.
+ */
+export default async function buildExactMutualReachabilityMst(connection, input, options, names) {
+    const { count, minSamples } = input;
+    if (count < 2 || !Number.isSafeInteger(count)) {
+        throw new Error("Exact mutual-reachability MST requires at least two rows.");
+    }
+    if (!Number.isSafeInteger(minSamples) || minSamples < 1 || minSamples >= count) {
+        throw new Error(`minSamples must be a safe integer between 1 and ${count - 1}.`);
+    }
+    await validateVectorRowIds(connection, names.rows, count);
+    if (options.metric === "cosine") {
+        await stabilizeCosineVectors(connection, names.rows);
+    }
+    const distance = vectorDistanceExpression("a.vec", "b.vec", options.metric);
+    await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.coreDistances}
+    (vertex INTEGER PRIMARY KEY,distance DOUBLE)`);
+    for (let offset = 0; offset < count; offset += 32) {
+        await connection.run(`INSERT INTO ${names.coreDistances}
+      SELECT source,max(item.distance)::DOUBLE AS distance FROM (
+        SELECT a.vertex AS source,
+          CASE WHEN bool_and(isfinite(${distance})) THEN
+          min_by(struct_pack(target := b.vertex,distance := ${distance}),
+            struct_pack(distance := ${distance},target := b.vertex),
+            ${minSamples}) ELSE error('Distance computation returned a non-finite value.') END AS closest
+        FROM ${names.rows} a CROSS JOIN ${names.rows} b
+        WHERE a.vertex >= ${offset} AND a.vertex < ${offset + 32}
+          AND a.vertex != b.vertex GROUP BY a.vertex
+      ),UNNEST(closest) AS t(item) GROUP BY source`);
+    }
+    if (await readScalarNumber(connection, `SELECT count(*) FROM ${names.coreDistances}
+        WHERE NOT isfinite(distance)`) ||
+        await readScalarNumber(connection, `SELECT count(*) FROM ${names.coreDistances}`) !== count) {
+        throw new Error("Exact core-distance computation returned missing or non-finite values.");
+    }
+    const root = await readScalarNumber(connection, `SELECT min(vertex) FROM ${names.rows}`);
+    await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.frontier} AS
+    SELECT b.vertex,${root}::INTEGER AS parent,
+      greatest(ca.distance,cb.distance,${distance})::DOUBLE AS distance
+    FROM ${names.rows} a CROSS JOIN ${names.rows} b
+    JOIN ${names.coreDistances} ca ON ca.vertex=a.vertex
+    JOIN ${names.coreDistances} cb ON cb.vertex=b.vertex
+    WHERE a.vertex=${root} AND b.vertex!=${root};
+    CREATE OR REPLACE TEMP TABLE ${names.mst}
+      (source INTEGER,target INTEGER,distance DOUBLE)`);
+    for (let edge = 0; edge < count - 1; edge++) {
+        const chosen = (await connection.runAndReadAll(`SELECT vertex,parent,distance FROM ${names.frontier}
+       ORDER BY distance,least(parent,vertex),greatest(parent,vertex),parent,vertex
+       LIMIT 1`)).getRowsJS()[0];
+        if (chosen === undefined) {
+            throw new Error("Exact mutual-reachability graph became disconnected.");
+        }
+        const vertex = Number(chosen[0]);
+        const parent = Number(chosen[1]);
+        const edgeDistance = Number(chosen[2]);
+        if (!Number.isFinite(edgeDistance)) {
+            throw new Error("Exact mutual-reachability MST returned a non-finite distance.");
+        }
+        await connection.run(`INSERT INTO ${names.mst} VALUES
+      (${Math.min(vertex, parent)},${Math.max(vertex, parent)},${edgeDistance})`);
+        if (edge === count - 2)
+            break;
+        const candidateDistance = vectorDistanceExpression("added.vec", "target.vec", options.metric);
+        await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.frontier} AS
+      WITH candidates AS (
+        SELECT f.*,greatest(ca.distance,cb.distance,${candidateDistance})::DOUBLE
+          AS candidate_distance
+        FROM ${names.frontier} f
+        JOIN ${names.rows} target ON target.vertex=f.vertex
+        CROSS JOIN ${names.rows} added
+        JOIN ${names.coreDistances} ca ON ca.vertex=added.vertex
+        JOIN ${names.coreDistances} cb ON cb.vertex=target.vertex
+        WHERE added.vertex=${vertex} AND f.vertex!=${vertex}
+      )
+      SELECT vertex,
+        CASE WHEN candidate_distance<distance OR
+          (candidate_distance=distance AND ${vertex}<parent)
+          THEN ${vertex} ELSE parent END::INTEGER AS parent,
+        least(distance,candidate_distance)::DOUBLE AS distance
+      FROM candidates`);
+    }
+}

package/esm/helpers/buildGraphTemporalCostStateSql.d.ts

@@ -0,0 +1,12 @@
+import type { PreparedGraphTemporalSql } from "./prepareGraphTemporalSql.js";
+import type { GraphDirection, PreparedGraphSql } from "./prepareGraphTraversal.js";
+export type GraphTemporalCostStateSql = {
+    costRelation: string;
+    edgesRelation: string;
+    settingsRelation: string;
+    startsRelation: string;
+    withClause: string;
+};
+/** Builds keyed best-cost chronological states from an arbitrary start relation. */
+export default function buildGraphTemporalCostStateSql(prepared: PreparedGraphSql, startsSelect: string | ((validEdgesRelation: string) => string), direction: Exclude<GraphDirection, "both">, temporal: PreparedGraphTemporalSql, distanceType: string, edgeWeight: string, eventSelections?: string[]): GraphTemporalCostStateSql;
+//# sourceMappingURL=buildGraphTemporalCostStateSql.d.ts.map

package/esm/helpers/buildGraphTemporalCostStateSql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildGraphTemporalCostStateSql.d.ts","sourceRoot":"","sources":["../../src/helpers/buildGraphTemporalCostStateSql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AAGpC,MAAM,MAAM,yBAAyB,GAAG;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,OAAO,UAAU,8BAA8B,CACpD,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,kBAAkB,EAAE,MAAM,KAAK,MAAM,CAAC,EAC/D,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,EAC1C,QAAQ,EAAE,wBAAwB,EAClC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,eAAe,GAAE,MAAM,EAAO,GAC7B,yBAAyB,CAuF3B"}