feat(8.0): brain.graph.subgraph(query) query→expand fusion (#61)

The subgraph seed selector now accepts not just entity id(s) but a find() result
or a FindParams query — brain.graph.subgraph({ where: { team: 'platform' } },
{ depth: 1 }) runs the query and expands the neighborhood of every match in one
call. Existing id-seeded calls are unchanged.

The win is the native query→expand path: for a metadata-only query, the matched
universe is forwarded to traverse() as an OpaqueIdSet (a roaring Buffer) with NO
id materialization in TypeScript — the find() result never leaves the engine's
representation (the O(1)-crossing the cor 3.0 contract is built around). The
pure-JS path (or any query carrying vector/text/proximity criteria) materializes
the matched ids via find() and seeds the traversal from them, capped at a bounded
default when the caller pins no limit.

- New public `SubgraphSelector<T>` union (id | id[] | Result[] | FindParams).
- find()'s metadata filter-builder extracted to a shared `buildMetadataFilter`
  (reused by the opaque universe producer); behavior unchanged.
- graphSubgraphNative generalized to accept `bigint[] | OpaqueIdSet` seeds.

Tested: JS query→expand + Result[] selector + empty-match in graph-subgraph, and
the native opaque pass-through (Buffer reaches traverse unmaterialized) vs the
find()-materialized bigint[] seeds via the mock provider in graph-native-routing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/types/brainy.types.ts

@@ -913,6 +913,17 @@ export interface GraphPathResult {
   cost: number
 }
 
+/**
+ * What {@link GraphApi.subgraph} expands from — "the things to grow a neighborhood
+ * around". One of:
+ * - an entity id, or an array of them (the explicit id set),
+ * - a {@link Result} array (a `find()` result — its entities become the seeds), or
+ * - a {@link FindParams} query (the query→expand fusion: run the query, expand from
+ *   every match). With the native engine a metadata-only query's matched universe is
+ *   forwarded to the traversal as an opaque set with no id materialization.
+ */
+export type SubgraphSelector<T = any> = string | string[] | Result<T>[] | FindParams<T>
+
 /**
  * The `brain.graph` namespace — graph-shaped reads over the knowledge graph.
  * Routes to a native {@link import('../plugin.js').GraphAccelerationProvider}
@@ -921,17 +932,23 @@ export interface GraphPathResult {
  */
 export interface GraphApi<T = any> {
   /**
-   * @description Extract the subgraph reachable from one or more seed entities —
-   *   the bounded multi-hop neighborhood, as nodes + edges. The one-call answer to
-   *   "show me everything around this node, N hops out".
-   * @param seeds - A seed entity id, or an array of them.
+   * @description Extract the subgraph reachable from a seed selector — the bounded
+   *   multi-hop neighborhood, as nodes + edges. The one-call answer to "show me
+   *   everything around this, N hops out". The seed can be entity id(s), a `find()`
+   *   result, or a {@link FindParams} query (query→expand: run the query, then expand
+   *   from every match — with the native engine the matched universe never leaves
+   *   the engine's representation).
+   * @param selector - Seed id(s), a `find()` result, or a query. See {@link SubgraphSelector}.
    * @param options - Depth, direction, edge/visibility filters, and caps.
    * @returns The hydrated {@link GraphView}.
    * @example
    * const view = await brain.graph.subgraph(personId, { depth: 2 })
    * // view.nodes = the 2-hop neighborhood; view.edges = the relations among them
+   * @example
+   * // Query→expand: the neighborhood of everything matching a filter.
+   * const cluster = await brain.graph.subgraph({ where: { team: 'platform' } }, { depth: 1 })
    */
-  subgraph(seeds: string | string[], options?: SubgraphOptions): Promise<GraphView<T>>
+  subgraph(selector: SubgraphSelector<T>, options?: SubgraphOptions): Promise<GraphView<T>>
 
   /**
    * @description Stream the WHOLE graph in one O(N+E) pass as a sequence of