@nicia-ai/typegraph 0.9.1 → 0.10.0

package/dist/index.d.cts

@@ -3,8 +3,8 @@ import { N as NodeType, E as EdgeType } from './types-DMzKq0d5.cjs';
 export { A as AnyEdgeType, C as Cardinality, a as Collation, D as DeleteBehavior, b as EdgeId, c as EdgeProps, d as EdgeRegistration, e as EdgeTypeWithEndpoints, f as EndpointExistence, G as GraphDefaults, g as NodeId, h as NodeProps, i as NodeRegistration, S as SqlDialect, T as TemporalMode, U as UniqueConstraint, j as UniquenessScope, k as isEdgeType, l as isEdgeTypeWithEndpoints, m as isNodeType } from './types-DMzKq0d5.cjs';
 import { I as InferenceType, M as MetaEdge, O as OntologyRelation } from './types-GLkwvQvS.cjs';
 export { D as DEFAULT_SQL_SCHEMA, G as GraphBackend, a as MetaEdgeProperties, S as SqlSchema, b as SqlTableNames, T as TransactionBackend, c as createSqlSchema, i as isMetaEdge } from './types-GLkwvQvS.cjs';
-import { A as AliasMap, E as EdgeAliasMap, Q as QueryBuilder, T as TraversalBuilder, C as CreateQueryBuilderOptions } from './store-DgzIgrmn.cjs';
-export { a as AggregateResult, b as ConstraintNames, c as CreateEdgeInput, d as CreateNodeInput, e as Edge, f as EdgeAccessor, g as EdgeCollection, h as EdgeFindByEndpointsOptions, i as EdgeGetOrCreateByEndpointsOptions, j as EdgeGetOrCreateByEndpointsResult, k as EmbeddingSchema, l as EmbeddingValue, m as ExecutableAggregateQuery, n as ExecutableQuery, F as FieldAccessor, G as GetOrCreateAction, H as HookContext, I as IfExistsMode, N as Node, o as NodeAccessor, p as NodeAlias, q as NodeCollection, r as NodeGetOrCreateByConstraintOptions, s as NodeGetOrCreateByConstraintResult, t as NodeRef, O as OperationHookContext, P as PaginateOptions, u as PaginatedResult, v as Predicate, w as PreparedQuery, x as PropsAccessor, y as QueryHookContext, z as QueryOptions, R as RecursiveTraversalOptions, S as SelectContext, B as SelectableEdge, D as SelectableNode, J as Store, K as StoreHooks, L as StoreOptions, M as StreamOptions, U as TransactionContext, V as TypedEdgeCollection, W as UnionableQuery, X as UpdateEdgeInput, Y as UpdateNodeInput, Z as createStore, _ as createStoreWithSchema, $ as embedding, a0 as exists, a1 as fieldRef, a2 as getEmbeddingDimensions, a3 as inSubquery, a4 as isEmbeddingSchema, a5 as isParameterRef, a6 as notExists, a7 as notInSubquery, a8 as param } from './store-DgzIgrmn.cjs';
+import { A as AliasMap, E as EdgeAliasMap, Q as QueryBuilder, T as TraversalBuilder, C as CreateQueryBuilderOptions } from './store-NE18RGqV.cjs';
+export { a as AggregateResult, b as AnyEdge, c as AnyNode, d as ConstraintNames, e as CreateEdgeInput, f as CreateNodeInput, g as Edge, h as EdgeAccessor, i as EdgeCollection, j as EdgeFindByEndpointsOptions, k as EdgeGetOrCreateByEndpointsOptions, l as EdgeGetOrCreateByEndpointsResult, m as EmbeddingSchema, n as EmbeddingValue, o as ExecutableAggregateQuery, p as ExecutableQuery, F as FieldAccessor, G as GetOrCreateAction, H as HookContext, I as IfExistsMode, N as Node, q as NodeAccessor, r as NodeAlias, s as NodeCollection, t as NodeGetOrCreateByConstraintOptions, u as NodeGetOrCreateByConstraintResult, v as NodeRef, O as OperationHookContext, P as PaginateOptions, w as PaginatedResult, x as Predicate, y as PreparedQuery, z as PropsAccessor, B as QueryHookContext, D as QueryOptions, R as RecursiveTraversalOptions, S as SelectContext, J as SelectableEdge, K as SelectableNode, L as Store, M as StoreHooks, U as StoreOptions, V as StreamOptions, W as SubgraphOptions, X as SubgraphResult, Y as SubsetEdge, Z as SubsetNode, _ as TransactionContext, $ as TypedEdgeCollection, a0 as UnionableQuery, a1 as UpdateEdgeInput, a2 as UpdateNodeInput, a3 as createStore, a4 as createStoreWithSchema, a5 as embedding, a6 as exists, a7 as fieldRef, a8 as getEmbeddingDimensions, a9 as inSubquery, aa as isEmbeddingSchema, ab as isParameterRef, ac as notExists, ad as notInSubquery, ae as param } from './store-NE18RGqV.cjs';
 import { G as GraphDef, K as KindRegistry } from './manager-DGSnJa1v.cjs';
 export { A as AllEdgeTypes, a as AllNodeTypes, E as EdgeKinds, b as GetEdgeType, c as GetNodeType, N as NodeKinds, d as defineGraph, g as getEdgeKinds, e as getNodeKinds, i as isGraphDef } from './manager-DGSnJa1v.cjs';
 export { C as CardinalityError, a as CompilerInvariantError, b as ConfigurationError, D as DatabaseOperationError, c as DisjointError, E as EdgeNotFoundError, d as EndpointError, e as EndpointNotFoundError, f as ErrorCategory, K as KindNotFoundError, M as MigrationError, N as NodeConstraintNotFoundError, g as NodeNotFoundError, R as RestrictedDeleteError, S as SchemaMismatchError, T as TypeGraphError, h as TypeGraphErrorOptions, U as UniquenessError, i as UnsupportedPredicateError, V as ValidationError, j as ValidationErrorDetails, k as ValidationIssue, l as VersionConflictError, m as getErrorSuggestion, n as isConstraintError, o as isSystemError, p as isTypeGraphError, q as isUserRecoverable } from './index-QTnQwakS.cjs';

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { N as NodeType, E as EdgeType } from './types-DMzKq0d5.js';
 export { A as AnyEdgeType, C as Cardinality, a as Collation, D as DeleteBehavior, b as EdgeId, c as EdgeProps, d as EdgeRegistration, e as EdgeTypeWithEndpoints, f as EndpointExistence, G as GraphDefaults, g as NodeId, h as NodeProps, i as NodeRegistration, S as SqlDialect, T as TemporalMode, U as UniqueConstraint, j as UniquenessScope, k as isEdgeType, l as isEdgeTypeWithEndpoints, m as isNodeType } from './types-DMzKq0d5.js';
 import { I as InferenceType, M as MetaEdge, O as OntologyRelation } from './types-1YJKodRv.js';
 export { D as DEFAULT_SQL_SCHEMA, G as GraphBackend, a as MetaEdgeProperties, S as SqlSchema, b as SqlTableNames, T as TransactionBackend, c as createSqlSchema, i as isMetaEdge } from './types-1YJKodRv.js';
-import { A as AliasMap, E as EdgeAliasMap, Q as QueryBuilder, T as TraversalBuilder, C as CreateQueryBuilderOptions } from './store-wqOO3GSy.js';
-export { a as AggregateResult, b as ConstraintNames, c as CreateEdgeInput, d as CreateNodeInput, e as Edge, f as EdgeAccessor, g as EdgeCollection, h as EdgeFindByEndpointsOptions, i as EdgeGetOrCreateByEndpointsOptions, j as EdgeGetOrCreateByEndpointsResult, k as EmbeddingSchema, l as EmbeddingValue, m as ExecutableAggregateQuery, n as ExecutableQuery, F as FieldAccessor, G as GetOrCreateAction, H as HookContext, I as IfExistsMode, N as Node, o as NodeAccessor, p as NodeAlias, q as NodeCollection, r as NodeGetOrCreateByConstraintOptions, s as NodeGetOrCreateByConstraintResult, t as NodeRef, O as OperationHookContext, P as PaginateOptions, u as PaginatedResult, v as Predicate, w as PreparedQuery, x as PropsAccessor, y as QueryHookContext, z as QueryOptions, R as RecursiveTraversalOptions, S as SelectContext, B as SelectableEdge, D as SelectableNode, J as Store, K as StoreHooks, L as StoreOptions, M as StreamOptions, U as TransactionContext, V as TypedEdgeCollection, W as UnionableQuery, X as UpdateEdgeInput, Y as UpdateNodeInput, Z as createStore, _ as createStoreWithSchema, $ as embedding, a0 as exists, a1 as fieldRef, a2 as getEmbeddingDimensions, a3 as inSubquery, a4 as isEmbeddingSchema, a5 as isParameterRef, a6 as notExists, a7 as notInSubquery, a8 as param } from './store-wqOO3GSy.js';
+import { A as AliasMap, E as EdgeAliasMap, Q as QueryBuilder, T as TraversalBuilder, C as CreateQueryBuilderOptions } from './store-BcFe9jJe.js';
+export { a as AggregateResult, b as AnyEdge, c as AnyNode, d as ConstraintNames, e as CreateEdgeInput, f as CreateNodeInput, g as Edge, h as EdgeAccessor, i as EdgeCollection, j as EdgeFindByEndpointsOptions, k as EdgeGetOrCreateByEndpointsOptions, l as EdgeGetOrCreateByEndpointsResult, m as EmbeddingSchema, n as EmbeddingValue, o as ExecutableAggregateQuery, p as ExecutableQuery, F as FieldAccessor, G as GetOrCreateAction, H as HookContext, I as IfExistsMode, N as Node, q as NodeAccessor, r as NodeAlias, s as NodeCollection, t as NodeGetOrCreateByConstraintOptions, u as NodeGetOrCreateByConstraintResult, v as NodeRef, O as OperationHookContext, P as PaginateOptions, w as PaginatedResult, x as Predicate, y as PreparedQuery, z as PropsAccessor, B as QueryHookContext, D as QueryOptions, R as RecursiveTraversalOptions, S as SelectContext, J as SelectableEdge, K as SelectableNode, L as Store, M as StoreHooks, U as StoreOptions, V as StreamOptions, W as SubgraphOptions, X as SubgraphResult, Y as SubsetEdge, Z as SubsetNode, _ as TransactionContext, $ as TypedEdgeCollection, a0 as UnionableQuery, a1 as UpdateEdgeInput, a2 as UpdateNodeInput, a3 as createStore, a4 as createStoreWithSchema, a5 as embedding, a6 as exists, a7 as fieldRef, a8 as getEmbeddingDimensions, a9 as inSubquery, aa as isEmbeddingSchema, ab as isParameterRef, ac as notExists, ad as notInSubquery, ae as param } from './store-BcFe9jJe.js';
 import { G as GraphDef, K as KindRegistry } from './manager-BCLhWysp.js';
 export { A as AllEdgeTypes, a as AllNodeTypes, E as EdgeKinds, b as GetEdgeType, c as GetNodeType, N as NodeKinds, d as defineGraph, g as getEdgeKinds, e as getNodeKinds, i as isGraphDef } from './manager-BCLhWysp.js';
 export { C as CardinalityError, a as CompilerInvariantError, b as ConfigurationError, D as DatabaseOperationError, c as DisjointError, E as EdgeNotFoundError, d as EndpointError, e as EndpointNotFoundError, f as ErrorCategory, K as KindNotFoundError, M as MigrationError, N as NodeConstraintNotFoundError, g as NodeNotFoundError, R as RestrictedDeleteError, S as SchemaMismatchError, T as TypeGraphError, h as TypeGraphErrorOptions, U as UniquenessError, i as UnsupportedPredicateError, V as ValidationError, j as ValidationErrorDetails, k as ValidationIssue, l as VersionConflictError, m as getErrorSuggestion, n as isConstraintError, o as isSystemError, p as isTypeGraphError, q as isUserRecoverable } from './index-QTnQwakS.js';

package/dist/index.js

@@ -2524,14 +2524,8 @@ function compileAggregateExprFromSource(expr, dialect) {
   const { field: field2 } = expr;
   const fn = expr.function;
   switch (fn) {
-    case "count": {
-      const cteAlias = `cte_${field2.alias}`;
-      return sql`COUNT(${sql.raw(cteAlias)}.${sql.raw(field2.alias)}_id)`;
-    }
-    case "countDistinct": {
-      const cteAlias = `cte_${field2.alias}`;
-      return sql`COUNT(DISTINCT ${sql.raw(cteAlias)}.${sql.raw(field2.alias)}_id)`;
-    }
+    case "count":
+    case "countDistinct":
     case "sum":
     case "avg":
     case "min":
@@ -2543,6 +2537,9 @@ function compileAggregateExprFromSource(expr, dialect) {
         field2.valueType,
         cteAlias
       );
+      if (fn === "countDistinct") {
+        return sql`COUNT(DISTINCT ${column})`;
+      }
       return sql`${sql.raw(fn.toUpperCase())}(${column})`;
     }
     default: {
@@ -3038,7 +3035,7 @@ function compileRecursiveCte(ast, traversal, graphId, ctx, requiredColumnsByAlia
     recursiveBaseWhereClauses.push(cycleCheck);
   }
   recursiveBaseWhereClauses.push(...edgePredicates, ...targetNodePredicates);
-  function compileRecursiveBranch(branch) {
+  function compileRecursiveBranch2(branch) {
     const recursiveFilterClauses = [
       ...recursiveBaseWhereClauses,
       compileKindFilter2(branch.edgeKinds, "e.kind"),
@@ -3093,7 +3090,7 @@ function compileRecursiveCte(ast, traversal, graphId, ctx, requiredColumnsByAlia
   const directTargetField = direction === "out" ? "to_id" : "from_id";
   const directJoinKindField = direction === "out" ? "from_kind" : "to_kind";
   const directTargetKindField = direction === "out" ? "to_kind" : "from_kind";
-  const directBranch = compileRecursiveBranch({
+  const directBranch = compileRecursiveBranch2({
     joinField: directJoinField,
     targetField: directTargetField,
     joinKindField: directJoinKindField,
@@ -3109,7 +3106,7 @@ function compileRecursiveCte(ast, traversal, graphId, ctx, requiredColumnsByAlia
       (kind) => directEdgeKinds.includes(kind)
     );
     const duplicateGuard = overlappingKinds.length > 0 ? sql`NOT (e.from_id = e.to_id AND ${compileKindFilter2(overlappingKinds, "e.kind")})` : void 0;
-    const inverseBranch = compileRecursiveBranch({
+    const inverseBranch = compileRecursiveBranch2({
       joinField: inverseJoinField,
       targetField: inverseTargetField,
       joinKindField: inverseJoinKindField,
@@ -3652,19 +3649,17 @@ function compilePrefixedSelect(ast, prefix, dialect) {
 function compileFieldValueForSetOp(source, prefix, alias, dialect) {
   if ("__type" in source && source.__type === "aggregate") {
     const { field: field2, function: fn } = source;
-    const cteName = `cte_${prefix}_${field2.alias}`;
     switch (fn) {
-      case "count": {
-        return sql`COUNT(${sql.raw(cteName)}.${sql.raw(field2.alias)}_id)`;
-      }
-      case "countDistinct": {
-        return sql`COUNT(DISTINCT ${sql.raw(cteName)}.${sql.raw(field2.alias)}_id)`;
-      }
+      case "count":
+      case "countDistinct":
       case "sum":
       case "avg":
       case "min":
       case "max": {
         const column = compileFieldColumnForSetOp(field2, prefix, dialect);
+        if (fn === "countDistinct") {
+          return sql`COUNT(DISTINCT ${column})`;
+        }
         return sql`${sql.raw(fn.toUpperCase())}(${column})`;
       }
       default: {
@@ -3878,9 +3873,7 @@ function collectRequiredColumnsByAlias2(ast) {
         markFieldRefAsRequired(requiredColumnsByAlias, source);
       } else {
         addRequiredColumn(requiredColumnsByAlias, source.field.alias, "id");
-        if (source.function !== "count" && source.function !== "countDistinct") {
-          markFieldRefAsRequired(requiredColumnsByAlias, source.field);
-        }
+        markFieldRefAsRequired(requiredColumnsByAlias, source.field);
       }
     }
   }
@@ -11197,6 +11190,142 @@ async function executeNodeBulkGetOrCreateByConstraint(ctx, kind, constraintName,
   }
   return results;
 }
+var DEFAULT_SUBGRAPH_MAX_DEPTH = 10;
+function normalizeProps(value) {
+  return typeof value === "string" ? value : JSON.stringify(value ?? {});
+}
+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_RECURSIVE_DEPTH
+  );
+  const ctx = {
+    graphId: params.graphId,
+    rootId: params.rootId,
+    edgeKinds: options.edges,
+    maxDepth,
+    includeKinds: options.includeKinds,
+    excludeRoot: options.excludeRoot ?? false,
+    direction: options.direction ?? "out",
+    cyclePolicy: options.cyclePolicy ?? "prevent",
+    dialect: params.dialect,
+    schema: params.schema ?? DEFAULT_SQL_SCHEMA,
+    backend: params.backend
+  };
+  const reachableCte = buildReachableCte(ctx);
+  const includedIdsCte = buildIncludedIdsCte(ctx);
+  const [nodeRows, edgeRows] = await Promise.all([
+    fetchSubgraphNodes(ctx, reachableCte, includedIdsCte),
+    fetchSubgraphEdges(ctx, reachableCte, includedIdsCte)
+  ]);
+  const nodes = nodeRows.map(
+    (row) => rowToNode({ ...row, props: normalizeProps(row.props) })
+  );
+  const edges = edgeRows.map(
+    (row) => rowToEdge({ ...row, props: normalizeProps(row.props) })
+  );
+  return {
+    nodes,
+    edges
+  };
+}
+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) {
+    filters.push(compileKindFilter(sql.raw("kind"), ctx.includeKinds));
+  }
+  if (ctx.excludeRoot) {
+    filters.push(sql`id != ${ctx.rootId}`);
+  }
+  const whereClause = filters.length > 0 ? sql` WHERE ${sql.join(filters, sql` AND `)}` : sql``;
+  return sql`, included_ids AS (SELECT DISTINCT id FROM reachable${whereClause})`;
+}
+async function fetchSubgraphNodes(ctx, reachableCte, includedIdsCte) {
+  const query = sql`${reachableCte}${includedIdsCte} SELECT n.kind, n.id, n.props, n.version, n.valid_from, n.valid_to, n.created_at, n.updated_at, n.deleted_at FROM ${ctx.schema.nodesTable} n WHERE n.graph_id = ${ctx.graphId} AND n.id IN (SELECT id FROM included_ids)`;
+  return ctx.backend.execute(query);
+}
+async function fetchSubgraphEdges(ctx, reachableCte, includedIdsCte) {
+  const edgeKindFilter = compileKindFilter(sql.raw("e.kind"), ctx.edgeKinds);
+  const query = sql`${reachableCte}${includedIdsCte} SELECT e.id, e.kind, e.from_kind, e.from_id, e.to_kind, e.to_id, e.props, e.valid_from, e.valid_to, e.created_at, e.updated_at, e.deleted_at 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)`;
+  return ctx.backend.execute(query);
+}
 
 // src/store/store.ts
 var Store = class {
@@ -11400,6 +11529,39 @@ var Store = class {
   query() {
     return this.#createQueryForBackend(this.#backend);
   }
+  // === Subgraph Extraction ===
+  /**
+   * 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.
+   *
+   * @example
+   * ```typescript
+   * const result = 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;
+   *   }
+   * }
+   * ```
+   */
+  async subgraph(rootId, options) {
+    return executeSubgraph({
+      graphId: this.graphId,
+      rootId,
+      backend: this.#backend,
+      dialect: getDialect(this.#backend.dialect),
+      schema: this.#schema,
+      options
+    });
+  }
   // === Transactions ===
   /**
    * Executes a function within a transaction.