@nshiab/simple-data-analysis-core 2.1.11 → 2.1.13

package/src/helpers/buildChronologicalGraphComponentsSql.ts

@@ -0,0 +1,193 @@
+import buildGraphTemporalReachabilitySql from "./buildGraphTemporalReachabilitySql.ts";
+import type { PreparedGraphTemporalSql } from "./prepareGraphTemporalSql.ts";
+import type { PreparedGraphSql } from "./prepareGraphTraversal.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+/** Builds all-pairs chronological reachability and maximal-clique membership SQL. */
+export default function buildChronologicalGraphComponentsSql(
+  prepared: PreparedGraphSql,
+  temporal: PreparedGraphTemporalSql,
+): string {
+  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")}`;
+}
+
+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 function buildMaximalGraphCliquesSql(
+  nodes: string,
+  mutual: string,
+  relations: MaximalGraphCliqueRelations,
+): string {
+  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/src/helpers/buildExactMutualReachabilityMst.ts

@@ -0,0 +1,122 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+import readScalarNumber from "./readScalarNumber.ts";
+import vectorDistanceExpression from "./vectorDistanceExpression.ts";
+import stabilizeCosineVectors from "./stabilizeCosineVectors.ts";
+import validateVectorRowIds from "./validateVectorRowIds.ts";
+
+/** 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 async function buildExactMutualReachabilityMst(
+  connection: DuckDBConnection,
+  input: { count: number; minSamples: number },
+  options: { metric: "euclidean" | "cosine" },
+  names: MutualReachabilityTables,
+): Promise<void> {
+  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/src/helpers/buildFuzzyMatchSql.ts

@@ -0,0 +1,30 @@
+export type FuzzyMethod = "ratio" | "partial_ratio" | "token_sort_ratio" | "token_set_ratio";
+
+export default function buildFuzzyMatchSql(
+  leftExpression: string,
+  rightExpression: string,
+  method: FuzzyMethod,
+  threshold: number,
+  options: {
+    decimals?: number;
+    prefilterPrefixLength?: number;
+  } = {},
+): { scoreExpression: string; condition: string } {
+  const fuzzyExpression = `rapidfuzz_${method}(${leftExpression}, ${rightExpression})`;
+  const scoreExpression =
+    options.decimals === undefined
+      ? fuzzyExpression
+      : `ROUND(${fuzzyExpression}, ${options.decimals})`;
+
+  let condition = `${scoreExpression} >= ${threshold}`;
+
+  if (method === "ratio") {
+    const maxDiffMultiplier = (200 - 2 * threshold) / (200 - threshold);
+    condition += ` AND ABS(LENGTH(${leftExpression}) - LENGTH(${rightExpression})) <= ${maxDiffMultiplier} * GREATEST(LENGTH(${leftExpression}), LENGTH(${rightExpression}))`;
+  }
+  if (options.prefilterPrefixLength !== undefined) {
+    condition += ` AND SUBSTR(${leftExpression}, 1, ${options.prefilterPrefixLength}) = SUBSTR(${rightExpression}, 1, ${options.prefilterPrefixLength})`;
+  }
+
+  return { scoreExpression, condition };
+}

package/src/helpers/buildGraphTemporalCostStateSql.ts

@@ -0,0 +1,120 @@
+import type { PreparedGraphTemporalSql } from "./prepareGraphTemporalSql.ts";
+import type { GraphDirection, PreparedGraphSql } from "./prepareGraphTraversal.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+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[] = [],
+  minimize: "weight" | "steps" = "weight",
+): GraphTemporalCostStateSql {
+  const q = quoteIdentifier;
+  const relations = prepared.relationNames([
+    "graph_starts",
+    "graph_temporal_settings",
+    "graph_event_rows",
+    "graph_edges",
+    "graph_cost_states",
+  ]);
+  const startsRelation = relations.graph_starts;
+  const settingsRelation = relations.graph_temporal_settings;
+  const eventRowsRelation = relations.graph_event_rows;
+  const edgesRelation = relations.graph_edges;
+  const costRelation = relations.graph_cost_states;
+  const start = `${q("starts")}.${q("start")}`;
+  const startKey = `${q("starts")}.${q("__key")}`;
+  const reachedStart = `${q("reached")}.${q("start")}`;
+  const reachedStartKey = `${q("reached")}.${q("__start_key")}`;
+  const reachedNodeKey = `${q("reached")}.${q("__node_key")}`;
+  const reachedDistance = `${q("reached")}.${q("distance")}`;
+  const edgeTo = `${q("edges")}.${q("__to")}`;
+  const edgeToKey = `${q("edges")}.${q("__to_key")}`;
+  const edgeFromKey = `${q("edges")}.${q("__from_key")}`;
+  const eventId = `${q("edges")}.${q("__event_id")}`;
+  const eventStart = `${q("edges")}.${q("__event_start")}`;
+  const eventEnd = `${q("edges")}.${q("__event_end")}`;
+  const edgeCost = `${q("edges")}.${q("__weight")}`;
+  const bestDistance = `${q("best")}.${q("distance")}`;
+  const gap = `${q("settings")}.${q("__gap")}`;
+  const candidateSteps = `${q("reached")}.${q("steps")} + 1`;
+  // A steps-only bound must not sum reported weights: discarded routes can
+  // overflow even when every optimal route's reported total is representable.
+  const firstDistance = minimize === "steps" ? "CAST(1 AS BIGINT)" : edgeCost;
+  const candidateDistance =
+    minimize === "steps"
+      ? candidateSteps
+      : `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+  const bestSteps = `${q("best")}.${q("steps")}`;
+  const order = (distance: string, steps: string) =>
+    minimize === "steps" ? `ROW(${steps}, ${distance})` : `ROW(${distance}, ${steps})`;
+  const candidateOrder = order(candidateDistance, candidateSteps);
+  const selectedDistance = `arg_min(${candidateDistance}, ${candidateOrder})`;
+  const selectedSteps = `arg_min(${candidateSteps}, ${candidateOrder})`;
+  const resolvedStartsSelect =
+    typeof startsSelect === "string" ? startsSelect : startsSelect(edgesRelation);
+
+  // Only states for the same start and physical event can dominate each other.
+  // Weight optimization orders by cost then steps; step optimization counts
+  // only connections. Strict improvements terminate even zero-cost cycles.
+  return {
+    costRelation,
+    edgesRelation,
+    settingsRelation,
+    startsRelation,
+    withClause: `WITH RECURSIVE ${settingsRelation} AS MATERIALIZED (
+      SELECT CAST(? AS HUGEINT) AS ${q("__gap")}
+    ), ${eventRowsRelation} AS MATERIALIZED (
+      ${prepared.edges(direction, [
+        `${edgeWeight} AS ${q("__weight")}`,
+        ...eventSelections,
+        ...temporal.eventSelections("edges"),
+      ])}
+    ), ${edgesRelation} AS MATERIALIZED (
+      SELECT *
+      FROM ${eventRowsRelation} AS ${q("events")}
+      WHERE ${temporal.eventValidity("events")}
+    ), ${startsRelation} AS MATERIALIZED (
+      ${resolvedStartsSelect}
+    ), ${costRelation}(
+      ${q("start")}, ${q("node")},
+      ${q("__start_key")}, ${q("__node_key")},
+      ${q("__event_id")}, ${q("__event_start")}, ${q("__event_end")},
+      ${q("distance")}, ${q("steps")}
+    ) USING KEY(${q("__start_key")}, ${q("__event_id")}) AS (
+      SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
+        ${eventId}, ${eventStart}, ${eventEnd}, ${firstDistance}, CAST(1 AS BIGINT)
+      FROM ${startsRelation} AS ${q("starts")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${startKey} = ${edgeFromKey}
+      UNION
+      SELECT ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
+        ${eventId}, ${eventStart}, ${eventEnd},
+        ${selectedDistance} AS ${q("distance")}, ${selectedSteps} AS ${q("steps")}
+      FROM ${costRelation} AS ${q("reached")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${reachedNodeKey} = ${edgeFromKey}
+      CROSS JOIN ${settingsRelation} AS ${q("settings")}
+      LEFT JOIN recurring.${costRelation} AS ${q("best")}
+        ON ${reachedStartKey} = ${q("best")}.${q("__start_key")}
+        AND ${eventId} = ${q("best")}.${q("__event_id")}
+      WHERE ${temporal.transition("reached", "edges", direction, gap)}
+      GROUP BY ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
+        ${eventId}, ${eventStart}, ${eventEnd}, ${bestDistance}, ${bestSteps}
+      HAVING ${bestDistance} IS NULL OR
+        ${order(selectedDistance, selectedSteps)} < ${order(bestDistance, bestSteps)}
+    )`,
+  };
+}

package/src/helpers/buildGraphTemporalReachabilitySql.ts

@@ -0,0 +1,84 @@
+import type { PreparedGraphTemporalSql } from "./prepareGraphTemporalSql.ts";
+import type { GraphDirection, PreparedGraphSql } from "./prepareGraphTraversal.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+export type GraphTemporalReachabilitySql = {
+  edgesRelation: string;
+  reachableRelation: string;
+  withClause: string;
+};
+
+/**
+ * Builds reusable chronological reachability CTEs from a start relation.
+ * A callback may derive all-node starts from the materialized valid edges.
+ */
+export default function buildGraphTemporalReachabilitySql(
+  prepared: PreparedGraphSql,
+  startsSelect: string | ((validEdgesRelation: string) => string),
+  direction: Exclude<GraphDirection, "both">,
+  temporal: PreparedGraphTemporalSql,
+): GraphTemporalReachabilitySql {
+  const q = quoteIdentifier;
+  const relations = prepared.relationNames([
+    "graph_starts",
+    "graph_temporal_settings",
+    "graph_event_rows",
+    "graph_edges",
+    "graph_reachable_states",
+  ]);
+  const startsRelation = relations.graph_starts;
+  const settingsRelation = relations.graph_temporal_settings;
+  const eventRowsRelation = relations.graph_event_rows;
+  const edgesRelation = relations.graph_edges;
+  const reachableRelation = relations.graph_reachable_states;
+  const start = `${q("starts")}.${q("start")}`;
+  const startKey = `${q("starts")}.${q("__key")}`;
+  const reachedStart = `${q("reached")}.${q("start")}`;
+  const reachedStartKey = `${q("reached")}.${q("__start_key")}`;
+  const reachedNodeKey = `${q("reached")}.${q("__node_key")}`;
+  const edgeTo = `${q("edges")}.${q("__to")}`;
+  const edgeToKey = `${q("edges")}.${q("__to_key")}`;
+  const edgeFromKey = `${q("edges")}.${q("__from_key")}`;
+  const eventId = `${q("edges")}.${q("__event_id")}`;
+  const eventStart = `${q("edges")}.${q("__event_start")}`;
+  const eventEnd = `${q("edges")}.${q("__event_end")}`;
+  const gap = `${q("settings")}.${q("__gap")}`;
+  const resolvedStartsSelect =
+    typeof startsSelect === "string" ? startsSelect : startsSelect(edgesRelation);
+
+  // Materialized event IDs stay fixed; UNION bounds states to starts × events,
+  // including equal-time cycles, because the last event determines all next steps.
+  return {
+    edgesRelation,
+    reachableRelation,
+    withClause: `WITH RECURSIVE ${settingsRelation} AS MATERIALIZED (
+      SELECT CAST(? AS HUGEINT) AS ${q("__gap")}
+    ), ${eventRowsRelation} AS MATERIALIZED (
+      ${prepared.edges(direction, temporal.eventSelections("edges"))}
+    ), ${edgesRelation} AS MATERIALIZED (
+      SELECT *
+      FROM ${eventRowsRelation} AS ${q("events")}
+      WHERE ${temporal.eventValidity("events")}
+    ), ${startsRelation} AS MATERIALIZED (
+      ${resolvedStartsSelect}
+    ), ${reachableRelation}(
+      ${q("start")}, ${q("node")},
+      ${q("__start_key")}, ${q("__node_key")},
+      ${q("__event_id")}, ${q("__event_start")}, ${q("__event_end")}
+    ) AS (
+      SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
+        ${eventId}, ${eventStart}, ${eventEnd}
+      FROM ${startsRelation} AS ${q("starts")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${startKey} = ${edgeFromKey}
+      UNION
+      SELECT ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
+        ${eventId}, ${eventStart}, ${eventEnd}
+      FROM ${reachableRelation} AS ${q("reached")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${reachedNodeKey} = ${edgeFromKey}
+      CROSS JOIN ${settingsRelation} AS ${q("settings")}
+      WHERE ${temporal.transition("reached", "edges", direction, gap)}
+    )`,
+  };
+}

package/src/helpers/buildSparseMutualReachabilityMst.ts

@@ -0,0 +1,53 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+
+type WeightedEdge = { source: number; target: number; distance: number };
+
+/** Select a deterministically ordered MST from a connected sparse candidate graph. */
+export default async function buildSparseMutualReachabilityMst(
+  connection: DuckDBConnection,
+  edges: string,
+  count: number,
+): Promise<WeightedEdge[]> {
+  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: number): number => {
+    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 mst: WeightedEdge[] = [];
+  const result = await connection.stream(
+    `SELECT source,target,distance FROM ${edges}
+     ORDER BY distance,source,target`,
+  );
+  while (mst.length < count - 1) {
+    const chunk = await result.fetchChunk();
+    if (!chunk || chunk.rowCount === 0) break;
+    const sources = chunk.getColumnVector(0);
+    const targets = chunk.getColumnVector(1);
+    const distances = chunk.getColumnVector(2);
+    for (let row = 0; row < chunk.rowCount && mst.length < count - 1; row++) {
+      const source = Number(sources.getItem(row));
+      const target = Number(targets.getItem(row));
+      const distance = Number(distances.getItem(row));
+      let left = find(source),
+        right = find(target);
+      if (left === right) continue;
+      if (size[left] < size[right]) [left, right] = [right, left];
+      parent[right] = left;
+      size[left] += size[right];
+      mst.push({ source, target, distance });
+    }
+  }
+  if (mst.length !== count - 1) {
+    throw new Error("Approximate HDBSCAN candidate graph has no spanning tree.");
+  }
+  return mst;
+}