@nicia-ai/typegraph 0.18.0 → 0.20.0

package/dist/index.js

@@ -3451,6 +3451,116 @@ function decodeByValueType(value, valueType) {
     }
   }
 }
+function buildReachableCte(options) {
+  const trackPath = options.cyclePolicy === "prevent" || options.includePath;
+  const edgeKindFilter = compileKindFilter(
+    sql.raw("e.kind"),
+    options.edgeKinds
+  );
+  const currentTimestamp = options.dialect.currentTimestamp();
+  const nodeTemporalFilter = compileTemporalFilter({
+    mode: options.temporalMode,
+    asOf: options.asOf,
+    tableAlias: "n",
+    currentTimestamp
+  });
+  const edgeTemporalFilter = compileTemporalFilter({
+    mode: options.temporalMode,
+    asOf: options.asOf,
+    tableAlias: "e",
+    currentTimestamp
+  });
+  const initialPath = trackPath ? options.dialect.initializePath(sql.raw("n.id")) : void 0;
+  const pathExtension = trackPath ? options.dialect.extendPath(sql.raw("r.path"), sql.raw("n.id")) : void 0;
+  const cycleCheck = options.cyclePolicy === "prevent" ? options.dialect.cycleCheck(sql.raw("n.id"), sql.raw("r.path")) : void 0;
+  const baseColumns = [sql`n.id`, sql`n.kind`, sql`0 AS depth`];
+  if (initialPath !== void 0) {
+    baseColumns.push(sql`${initialPath} AS path`);
+  }
+  const baseCase = sql`SELECT ${sql.join(baseColumns, sql`, `)} FROM ${options.schema.nodesTable} n WHERE n.graph_id = ${options.graphId} AND n.id = ${options.sourceId} AND ${nodeTemporalFilter}`;
+  const recursiveColumns = [
+    sql`n.id`,
+    sql`n.kind`,
+    sql`r.depth + 1 AS depth`
+  ];
+  if (pathExtension !== void 0) {
+    recursiveColumns.push(sql`${pathExtension} AS path`);
+  }
+  const recursiveWhere = [
+    sql`e.graph_id = ${options.graphId}`,
+    edgeKindFilter,
+    edgeTemporalFilter,
+    nodeTemporalFilter,
+    sql`r.depth < ${options.maxHops}`
+  ];
+  if (cycleCheck !== void 0) recursiveWhere.push(cycleCheck);
+  const forceWorktableOuterJoinOrder = options.dialect.capabilities.forceRecursiveWorktableOuterJoinOrder;
+  const recursiveCase = compileRecursiveBranch({
+    recursiveColumns,
+    whereClauses: recursiveWhere,
+    direction: options.direction,
+    forceWorktableOuterJoinOrder,
+    schema: options.schema
+  });
+  return sql`WITH RECURSIVE reachable AS (${baseCase} UNION ALL ${recursiveCase})`;
+}
+function compileRecursiveBranch(options) {
+  const selectClause = sql`SELECT ${sql.join([...options.recursiveColumns], sql`, `)}`;
+  switch (options.direction) {
+    case "out": {
+      return buildDirectionalBranch({
+        selectClause,
+        whereClauses: options.whereClauses,
+        joinField: "from_id",
+        targetField: "to_id",
+        targetKindField: "to_kind",
+        forceWorktableOuterJoinOrder: options.forceWorktableOuterJoinOrder,
+        schema: options.schema
+      });
+    }
+    case "in": {
+      return buildDirectionalBranch({
+        selectClause,
+        whereClauses: options.whereClauses,
+        joinField: "to_id",
+        targetField: "from_id",
+        targetKindField: "from_kind",
+        forceWorktableOuterJoinOrder: options.forceWorktableOuterJoinOrder,
+        schema: options.schema
+      });
+    }
+    case "both": {
+      return buildBidirectionalBranch({
+        selectClause,
+        whereClauses: options.whereClauses,
+        forceWorktableOuterJoinOrder: options.forceWorktableOuterJoinOrder,
+        schema: options.schema
+      });
+    }
+  }
+}
+function buildDirectionalBranch(options) {
+  const nodeJoin = sql`JOIN ${options.schema.nodesTable} n ON n.graph_id = e.graph_id AND n.id = e.${sql.raw(options.targetField)} AND n.kind = e.${sql.raw(options.targetKindField)}`;
+  if (options.forceWorktableOuterJoinOrder) {
+    const allWhere = [
+      ...options.whereClauses,
+      sql`e.${sql.raw(options.joinField)} = r.id`
+    ];
+    return sql`${options.selectClause} FROM reachable r CROSS JOIN ${options.schema.edgesTable} e ${nodeJoin} WHERE ${sql.join(allWhere, sql` AND `)}`;
+  }
+  return sql`${options.selectClause} FROM reachable r JOIN ${options.schema.edgesTable} e ON e.${sql.raw(options.joinField)} = r.id ${nodeJoin} WHERE ${sql.join([...options.whereClauses], sql` AND `)}`;
+}
+function buildBidirectionalBranch(options) {
+  const nodeJoin = sql`JOIN ${options.schema.nodesTable} n ON n.graph_id = e.graph_id AND ((e.to_id = r.id AND n.id = e.from_id AND n.kind = e.from_kind) OR (e.from_id = r.id AND n.id = e.to_id AND n.kind = e.to_kind))`;
+  if (options.forceWorktableOuterJoinOrder) {
+    const allWhere = [
+      ...options.whereClauses,
+      sql`(e.from_id = r.id OR e.to_id = r.id)`
+    ];
+    return sql`${options.selectClause} FROM reachable r CROSS JOIN ${options.schema.edgesTable} e ${nodeJoin} WHERE ${sql.join(allWhere, sql` AND `)}`;
+  }
+  return sql`${options.selectClause} FROM reachable r JOIN ${options.schema.edgesTable} e ON (e.from_id = r.id OR e.to_id = r.id) ${nodeJoin} WHERE ${sql.join([...options.whereClauses], sql` AND `)}`;
+}
 
 // src/store/row-mappers.ts
 function nullToUndefined2(value) {
@@ -3528,9 +3638,6 @@ function defineSubgraphProject(_graph) {
 }
 async function executeSubgraph(params) {
   const { options } = params;
-  if (options.edges.length === 0) {
-    return { nodes: [], edges: [] };
-  }
   const maxDepth = Math.min(
     options.maxDepth ?? DEFAULT_SUBGRAPH_MAX_DEPTH,
     MAX_EXPLICIT_RECURSIVE_DEPTH
@@ -3544,6 +3651,8 @@ async function executeSubgraph(params) {
     excludeRoot: options.excludeRoot ?? false,
     direction: options.direction ?? "out",
     cyclePolicy: options.cyclePolicy ?? "prevent",
+    temporalMode: options.temporalMode ?? params.graph.defaults.temporalMode,
+    asOf: options.asOf,
     dialect: params.dialect,
     schema: params.schema ?? DEFAULT_SQL_SCHEMA,
     backend: params.backend
@@ -3561,21 +3670,47 @@ async function executeSubgraph(params) {
     (kind, field2) => schemaIntrospector.getEdgeFieldTypeInfo(kind, field2),
     "edge"
   );
-  const reachableCte = buildReachableCte(ctx);
+  const reachableCte = buildReachableCte({
+    graphId: ctx.graphId,
+    sourceId: ctx.rootId,
+    edgeKinds: ctx.edgeKinds,
+    maxHops: ctx.maxDepth,
+    direction: ctx.direction,
+    cyclePolicy: ctx.cyclePolicy,
+    includePath: false,
+    temporalMode: ctx.temporalMode,
+    ...ctx.asOf !== void 0 && { asOf: ctx.asOf },
+    dialect: ctx.dialect,
+    schema: ctx.schema
+  });
   const includedIdsCte = buildIncludedIdsCte(ctx);
   const [nodeRows, edgeRows] = await Promise.all([
     fetchSubgraphNodes(ctx, reachableCte, includedIdsCte, nodeProjectionPlan),
     fetchSubgraphEdges(ctx, reachableCte, includedIdsCte, edgeProjectionPlan)
   ]);
-  const nodes = nodeRows.map(
-    (row) => mapSubgraphNodeRow(row, nodeProjectionPlan)
-  );
-  const edges = edgeRows.map(
-    (row) => mapSubgraphEdgeRow(row, edgeProjectionPlan)
-  );
+  const nodesMap = /* @__PURE__ */ new Map();
+  for (const row of nodeRows) {
+    const node = mapSubgraphNodeRow(row, nodeProjectionPlan);
+    nodesMap.set(node.id, node);
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  const reverseAdjacency = /* @__PURE__ */ new Map();
+  for (const row of edgeRows) {
+    const edge = mapSubgraphEdgeRow(row, edgeProjectionPlan);
+    insertAdjacencyEntry(adjacency, edge.fromId, edge.kind, edge);
+    insertAdjacencyEntry(
+      reverseAdjacency,
+      edge.toId,
+      edge.kind,
+      edge
+    );
+  }
+  const root = nodesMap.get(ctx.rootId);
   return {
-    nodes,
-    edges
+    root,
+    nodes: nodesMap,
+    adjacency,
+    reverseAdjacency
   };
 }
 var introspectorCache = /* @__PURE__ */ new WeakMap();
@@ -3645,79 +3780,6 @@ function getIncludedNodeKinds(graph, includeKinds) {
 function dedupeStrings(values) {
   return [...new Set(values)];
 }
-function buildReachableCte(ctx) {
-  const shouldTrackPath = ctx.cyclePolicy === "prevent";
-  const edgeKindFilter = compileKindFilter(sql.raw("e.kind"), ctx.edgeKinds);
-  const initialPath = shouldTrackPath ? ctx.dialect.initializePath(sql.raw("n.id")) : void 0;
-  const pathExtension = shouldTrackPath ? ctx.dialect.extendPath(sql.raw("r.path"), sql.raw("n.id")) : void 0;
-  const cycleCheck = shouldTrackPath ? ctx.dialect.cycleCheck(sql.raw("n.id"), sql.raw("r.path")) : void 0;
-  const baseColumns = [sql`n.id`, sql`n.kind`, sql`0 AS depth`];
-  if (initialPath !== void 0) {
-    baseColumns.push(sql`${initialPath} AS path`);
-  }
-  const baseCase = sql`SELECT ${sql.join(baseColumns, sql`, `)} FROM ${ctx.schema.nodesTable} n WHERE n.graph_id = ${ctx.graphId} AND n.id = ${ctx.rootId} AND n.deleted_at IS NULL`;
-  const recursiveColumns = [
-    sql`n.id`,
-    sql`n.kind`,
-    sql`r.depth + 1 AS depth`
-  ];
-  if (pathExtension !== void 0) {
-    recursiveColumns.push(sql`${pathExtension} AS path`);
-  }
-  const recursiveWhereClauses = [
-    sql`e.graph_id = ${ctx.graphId}`,
-    edgeKindFilter,
-    sql`e.deleted_at IS NULL`,
-    sql`n.deleted_at IS NULL`,
-    sql`r.depth < ${ctx.maxDepth}`
-  ];
-  if (cycleCheck !== void 0) {
-    recursiveWhereClauses.push(cycleCheck);
-  }
-  const forceWorktableOuterJoinOrder = ctx.dialect.capabilities.forceRecursiveWorktableOuterJoinOrder;
-  const recursiveCase = ctx.direction === "both" ? compileBidirectionalBranch({
-    recursiveColumns,
-    whereClauses: recursiveWhereClauses,
-    forceWorktableOuterJoinOrder,
-    schema: ctx.schema
-  }) : compileRecursiveBranch({
-    recursiveColumns,
-    whereClauses: recursiveWhereClauses,
-    joinField: "from_id",
-    targetField: "to_id",
-    targetKindField: "to_kind",
-    forceWorktableOuterJoinOrder,
-    schema: ctx.schema
-  });
-  return sql`WITH RECURSIVE reachable AS (${baseCase} UNION ALL ${recursiveCase})`;
-}
-function compileRecursiveBranch(params) {
-  const columns = [...params.recursiveColumns];
-  const selectClause = sql`SELECT ${sql.join(columns, sql`, `)}`;
-  const nodeJoin = sql`JOIN ${params.schema.nodesTable} n ON n.graph_id = e.graph_id AND n.id = e.${sql.raw(params.targetField)} AND n.kind = e.${sql.raw(params.targetKindField)}`;
-  if (params.forceWorktableOuterJoinOrder) {
-    const allWhere = [
-      ...params.whereClauses,
-      sql`e.${sql.raw(params.joinField)} = r.id`
-    ];
-    return sql`${selectClause} FROM reachable r CROSS JOIN ${params.schema.edgesTable} e ${nodeJoin} WHERE ${sql.join(allWhere, sql` AND `)}`;
-  }
-  const where = [...params.whereClauses];
-  return sql`${selectClause} FROM reachable r JOIN ${params.schema.edgesTable} e ON e.${sql.raw(params.joinField)} = r.id ${nodeJoin} WHERE ${sql.join(where, sql` AND `)}`;
-}
-function compileBidirectionalBranch(params) {
-  const columns = [...params.recursiveColumns];
-  const selectClause = sql`SELECT ${sql.join(columns, sql`, `)}`;
-  const nodeJoin = sql`JOIN ${params.schema.nodesTable} n ON n.graph_id = e.graph_id AND ((e.to_id = r.id AND n.id = e.from_id AND n.kind = e.from_kind) OR (e.from_id = r.id AND n.id = e.to_id AND n.kind = e.to_kind))`;
-  if (params.forceWorktableOuterJoinOrder) {
-    const allWhere = [
-      ...params.whereClauses,
-      sql`(e.from_id = r.id OR e.to_id = r.id)`
-    ];
-    return sql`${selectClause} FROM reachable r CROSS JOIN ${params.schema.edgesTable} e ${nodeJoin} WHERE ${sql.join(allWhere, sql` AND `)}`;
-  }
-  return sql`${selectClause} FROM reachable r JOIN ${params.schema.edgesTable} e ON (e.from_id = r.id OR e.to_id = r.id) ${nodeJoin} WHERE ${sql.join([...params.whereClauses], sql` AND `)}`;
-}
 function buildIncludedIdsCte(ctx) {
   const filters = [];
   if (ctx.includeKinds !== void 0 && ctx.includeKinds.length > 0) {
@@ -3749,6 +3811,12 @@ async function fetchSubgraphNodes(ctx, reachableCte, includedIdsCte, projectionP
 }
 async function fetchSubgraphEdges(ctx, reachableCte, includedIdsCte, projectionPlan) {
   const edgeKindFilter = compileKindFilter(sql.raw("e.kind"), ctx.edgeKinds);
+  const edgeTemporalFilter = compileTemporalFilter({
+    mode: ctx.temporalMode,
+    asOf: ctx.asOf,
+    tableAlias: "e",
+    currentTimestamp: ctx.dialect.currentTimestamp()
+  });
   const columns = [
     sql`e.id`,
     sql`e.kind`,
@@ -3766,7 +3834,7 @@ async function fetchSubgraphEdges(ctx, reachableCte, includedIdsCte, projectionP
     ]),
     ...buildProjectedPropertyColumns("e", projectionPlan, ctx.dialect)
   ];
-  const query = sql`${reachableCte}${includedIdsCte} SELECT ${sql.join(columns, sql`, `)} FROM ${ctx.schema.edgesTable} e WHERE e.graph_id = ${ctx.graphId} AND ${edgeKindFilter} AND e.deleted_at IS NULL AND e.from_id IN (SELECT id FROM included_ids) AND e.to_id IN (SELECT id FROM included_ids)`;
+  const query = sql`${reachableCte}${includedIdsCte} SELECT ${sql.join(columns, sql`, `)} FROM ${ctx.schema.edgesTable} e WHERE e.graph_id = ${ctx.graphId} AND ${edgeKindFilter} AND ${edgeTemporalFilter} AND e.from_id IN (SELECT id FROM included_ids) AND e.to_id IN (SELECT id FROM included_ids)`;
   return ctx.backend.execute(query);
 }
 function buildMetadataColumns(alias, plan, columns) {
@@ -3815,6 +3883,19 @@ function buildProjectedPropertyColumns(alias, plan, dialect) {
   }
   return columns;
 }
+function insertAdjacencyEntry(index, nodeId, edgeKind, edge) {
+  let kindMap = index.get(nodeId);
+  if (kindMap === void 0) {
+    kindMap = /* @__PURE__ */ new Map();
+    index.set(nodeId, kindMap);
+  }
+  const edges = kindMap.get(edgeKind);
+  if (edges === void 0) {
+    kindMap.set(edgeKind, [edge]);
+  } else {
+    edges.push(edge);
+  }
+}
 function applyProjectedFields(target, row, kindPlan) {
   for (const fieldPlan of kindPlan.propertyFields) {
     target[fieldPlan.field] = decodeSelectedValue(
@@ -8898,6 +8979,246 @@ function extractEdgeTypes(graph) {
   return result;
 }
 
+// src/store/algorithms/context.ts
+var DEFAULT_ALGORITHM_MAX_HOPS = 10;
+var DEFAULT_NEIGHBOR_DEPTH = 1;
+function resolveTemporalOptions(ctx, options) {
+  return {
+    temporalMode: options.temporalMode ?? ctx.defaultTemporalMode,
+    ...options.asOf !== void 0 && { asOf: options.asOf }
+  };
+}
+function resolveTemporalFilter(ctx, options, tableAlias) {
+  const resolved = resolveTemporalOptions(ctx, options);
+  const filterOptions = {
+    mode: resolved.temporalMode,
+    asOf: resolved.asOf,
+    tableAlias,
+    currentTimestamp: ctx.dialect.currentTimestamp()
+  };
+  return compileTemporalFilter(filterOptions);
+}
+function resolveMaxHops(rawMaxHops, fallback, optionName) {
+  const value = rawMaxHops ?? fallback;
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new ConfigurationError(
+      `Graph algorithm ${optionName} must be a finite integer, got ${String(value)}.`,
+      { option: optionName, value }
+    );
+  }
+  if (value < 1) {
+    throw new ConfigurationError(
+      `Graph algorithm ${optionName} must be at least 1, got ${value}.`,
+      { option: optionName, value }
+    );
+  }
+  if (value > MAX_EXPLICIT_RECURSIVE_DEPTH) {
+    throw new ConfigurationError(
+      `Graph algorithm ${optionName} (${value}) exceeds the maximum of ${MAX_EXPLICIT_RECURSIVE_DEPTH}.`,
+      { option: optionName, value, limit: MAX_EXPLICIT_RECURSIVE_DEPTH }
+    );
+  }
+  return value;
+}
+function assertEdgeKinds(edges) {
+  if (edges.length === 0) {
+    throw new ConfigurationError(
+      `Graph algorithms require at least one edge kind in 'edges'.`,
+      { edges }
+    );
+  }
+}
+
+// src/store/algorithms/degree.ts
+async function executeDegree(ctx, nodeId, options = {}) {
+  const direction = options.direction ?? "both";
+  const whereClauses = [
+    sql`graph_id = ${ctx.graphId}`,
+    resolveTemporalFilter(ctx, options),
+    compileDirectionFilter(direction, nodeId)
+  ];
+  if (options.edges !== void 0) {
+    whereClauses.push(compileKindFilter(sql.raw("kind"), options.edges));
+  }
+  const countExpr = direction === "both" ? sql`COUNT(DISTINCT id)` : sql`COUNT(*)`;
+  const query = sql`SELECT ${countExpr} AS count FROM ${ctx.schema.edgesTable} WHERE ${sql.join(whereClauses, sql` AND `)}`;
+  const rows = await ctx.backend.execute(query);
+  return Number(rows[0]?.count ?? 0);
+}
+function compileDirectionFilter(direction, nodeId) {
+  switch (direction) {
+    case "out": {
+      return sql`from_id = ${nodeId}`;
+    }
+    case "in": {
+      return sql`to_id = ${nodeId}`;
+    }
+    case "both": {
+      return sql`(from_id = ${nodeId} OR to_id = ${nodeId})`;
+    }
+  }
+}
+async function executeReachable(ctx, sourceId, options) {
+  assertEdgeKinds(options.edges);
+  const maxHops = resolveMaxHops(
+    options.maxHops,
+    DEFAULT_ALGORITHM_MAX_HOPS,
+    "maxHops"
+  );
+  const cte = buildReachableCte({
+    graphId: ctx.graphId,
+    sourceId,
+    edgeKinds: options.edges,
+    maxHops,
+    direction: options.direction ?? "out",
+    cyclePolicy: options.cyclePolicy ?? "prevent",
+    includePath: false,
+    ...resolveTemporalOptions(ctx, options),
+    dialect: ctx.dialect,
+    schema: ctx.schema
+  });
+  const sourceFilter = options.excludeSource === true ? sql` WHERE id != ${sourceId}` : sql``;
+  const query = sql`${cte} SELECT id, kind, MIN(depth) AS depth FROM reachable${sourceFilter} GROUP BY id, kind ORDER BY depth ASC, id ASC`;
+  const rows = await ctx.backend.execute(query);
+  return rows.map((row) => ({
+    id: row.id,
+    kind: row.kind,
+    depth: Number(row.depth)
+  }));
+}
+async function executeCanReach(ctx, sourceId, targetId, options) {
+  assertEdgeKinds(options.edges);
+  const maxHops = resolveMaxHops(
+    options.maxHops,
+    DEFAULT_ALGORITHM_MAX_HOPS,
+    "maxHops"
+  );
+  const cte = buildReachableCte({
+    graphId: ctx.graphId,
+    sourceId,
+    edgeKinds: options.edges,
+    maxHops,
+    direction: options.direction ?? "out",
+    cyclePolicy: options.cyclePolicy ?? "prevent",
+    includePath: false,
+    ...resolveTemporalOptions(ctx, options),
+    dialect: ctx.dialect,
+    schema: ctx.schema
+  });
+  const query = sql`${cte} SELECT 1 AS hit FROM reachable WHERE id = ${targetId} LIMIT 1`;
+  const rows = await ctx.backend.execute(query);
+  return rows.length > 0;
+}
+async function executeNeighbors(ctx, sourceId, options) {
+  const depth = resolveMaxHops(options.depth, DEFAULT_NEIGHBOR_DEPTH, "depth");
+  return executeReachable(ctx, sourceId, {
+    edges: options.edges,
+    maxHops: depth,
+    direction: options.direction ?? "out",
+    cyclePolicy: options.cyclePolicy ?? "prevent",
+    ...options.temporalMode !== void 0 && {
+      temporalMode: options.temporalMode
+    },
+    ...options.asOf !== void 0 && { asOf: options.asOf },
+    excludeSource: true
+  });
+}
+async function executeShortestPath(ctx, sourceId, targetId, options) {
+  assertEdgeKinds(options.edges);
+  const maxHops = resolveMaxHops(
+    options.maxHops,
+    DEFAULT_ALGORITHM_MAX_HOPS,
+    "maxHops"
+  );
+  if (sourceId === targetId) {
+    const source = await fetchNodeKind(ctx, sourceId, options);
+    if (source === void 0) return void 0;
+    return { nodes: [source], depth: 0 };
+  }
+  const cte = buildReachableCte({
+    graphId: ctx.graphId,
+    sourceId,
+    edgeKinds: options.edges,
+    maxHops,
+    direction: options.direction ?? "out",
+    cyclePolicy: options.cyclePolicy ?? "prevent",
+    includePath: true,
+    ...resolveTemporalOptions(ctx, options),
+    dialect: ctx.dialect,
+    schema: ctx.schema
+  });
+  const pathContainsCheck = sql`NOT (${ctx.dialect.cycleCheck(sql.raw("r.id"), sql.raw("h.path"))})`;
+  const query = sql`${cte}, hit AS (SELECT id, kind, depth, path FROM reachable WHERE id = ${targetId} ORDER BY depth ASC LIMIT 1) SELECT h.id AS hit_id, h.kind AS hit_kind, h.depth AS hit_depth, h.path AS hit_path, r.id AS node_id, r.kind AS node_kind FROM hit h LEFT JOIN reachable r ON ${pathContainsCheck}`;
+  const rows = await ctx.backend.execute(query);
+  const first = rows[0];
+  if (first === void 0) return void 0;
+  const pathIds = normalizePath(first.hit_path);
+  const kindById = buildKindIndex(rows);
+  const pathNodes = pathIds.map((id) => ({
+    id,
+    kind: kindById.get(id) ?? ""
+  }));
+  return { nodes: pathNodes, depth: Number(first.hit_depth) };
+}
+function buildKindIndex(rows) {
+  const map = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (row.node_id !== void 0 && row.node_kind !== void 0) {
+      map.set(row.node_id, row.node_kind);
+    }
+  }
+  return map;
+}
+async function fetchNodeKind(ctx, nodeId, options) {
+  const temporalFilter = resolveTemporalFilter(ctx, options);
+  const query = sql`SELECT id, kind FROM ${ctx.schema.nodesTable} WHERE graph_id = ${ctx.graphId} AND id = ${nodeId} AND ${temporalFilter} LIMIT 1`;
+  const rows = await ctx.backend.execute(query);
+  const row = rows[0];
+  if (row === void 0) return void 0;
+  return { id: row.id, kind: row.kind };
+}
+
+// src/store/algorithms/index.ts
+function resolveNodeId(value) {
+  return typeof value === "string" ? value : value.id;
+}
+function createGraphAlgorithms(params) {
+  const ctx = {
+    graphId: params.graphId,
+    backend: params.backend,
+    dialect: getDialect(params.backend.dialect),
+    schema: params.schema ?? (params.backend.tableNames ? createSqlSchema(params.backend.tableNames) : createSqlSchema()),
+    defaultTemporalMode: params.defaultTemporalMode
+  };
+  return {
+    shortestPath(from, to, options) {
+      return executeShortestPath(
+        ctx,
+        resolveNodeId(from),
+        resolveNodeId(to),
+        options
+      );
+    },
+    reachable(from, options) {
+      return executeReachable(ctx, resolveNodeId(from), options);
+    },
+    canReach(from, to, options) {
+      return executeCanReach(
+        ctx,
+        resolveNodeId(from),
+        resolveNodeId(to),
+        options
+      );
+    },
+    neighbors(node, options) {
+      return executeNeighbors(ctx, resolveNodeId(node), options);
+    },
+    degree(node, options) {
+      return executeDegree(ctx, resolveNodeId(node), options ?? {});
+    }
+  };
+}
+
 // src/store/collections/edge-collection.ts
 function narrowEdge(edge) {
   return edge;
@@ -11665,6 +11986,7 @@ var Store = class {
   #defaultTraversalExpansion;
   #nodeCollections;
   #edgeCollections;
+  #algorithms;
   constructor(graph, backend, options) {
     this.#graph = graph;
     this.#backend = backend;
@@ -11746,6 +12068,38 @@ var Store = class {
     }
     return this.#edgeCollections;
   }
+  // === Graph Algorithms ===
+  /**
+   * Tier 1 graph algorithms: shortest path, reachability, neighborhoods, and
+   * degree centrality.
+   *
+   * Each call compiles to a single recursive-CTE query against the backend.
+   * The facade is built lazily on first access and cached for the lifetime
+   * of the store.
+   *
+   * @example
+   * ```typescript
+   * const path = await store.algorithms.shortestPath(alice, bob, {
+   *   edges: ["knows"],
+   * });
+   *
+   * const friends = await store.algorithms.neighbors(alice, {
+   *   edges: ["knows"],
+   *   depth: 2,
+   * });
+   * ```
+   */
+  get algorithms() {
+    if (this.#algorithms === void 0) {
+      this.#algorithms = createGraphAlgorithms({
+        graphId: this.graphId,
+        backend: this.#backend,
+        schema: this.#schema,
+        defaultTemporalMode: this.#graph.defaults.temporalMode
+      });
+    }
+    return this.#algorithms;
+  }
   // === Dynamic Collection Access ===
   /**
    * Returns the node collection for the given kind, or undefined if the kind
@@ -11926,22 +12280,26 @@ var Store = class {
    * Extracts a typed subgraph by traversing from a root node.
    *
    * Performs a BFS traversal from `rootId` following the specified edge kinds,
-   * then returns all reachable nodes and the edges connecting them.
+   * returning an indexed result with adjacency maps for immediate traversal.
    *
    * @example
    * ```typescript
-   * const result = await store.subgraph(run.id, {
+   * const sg = await store.subgraph(run.id, {
    *   edges: ["has_task", "runs_agent", "uses_skill"],
    *   maxDepth: 4,
-   *   includeKinds: ["Run", "Task", "Agent", "Skill"],
    * });
    *
-   * for (const node of result.nodes) {
-   *   switch (node.kind) {
-   *     case "Task": console.log(node.name); break;
-   *     case "Agent": console.log(node.model); break;
-   *   }
-   * }
+   * // Root node (the traversal starting point)
+   * console.log(sg.root?.kind);
+   *
+   * // Lookup by ID
+   * const task = sg.nodes.get(taskId);
+   *
+   * // Forward adjacency: edges of a kind from a node
+   * const taskEdges = sg.adjacency.get(run.id)?.get("has_task") ?? [];
+   *
+   * // Reverse adjacency: edges of a kind pointing to a node
+   * const parentEdges = sg.reverseAdjacency.get(taskId)?.get("has_task") ?? [];
    * ```
    */
   async subgraph(rootId, options) {
@@ -12020,6 +12378,7 @@ var Store = class {
     await (this.#backend.capabilities.transactions ? this.#backend.transaction(async (tx) => doClear(tx)) : doClear(this.#backend));
     this.#nodeCollections = void 0;
     this.#edgeCollections = void 0;
+    this.#algorithms = void 0;
   }
   // === Lifecycle ===
   /**