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>

tests/unit/brainy/graph-subgraph.test.ts

@@ -98,4 +98,35 @@ describe('brain.graph.subgraph() (graph engine #25)', () => {
     // depth 0 = just the seeds, no expansion.
     expect(new Set(view.nodes.map((n) => n.id))).toEqual(new Set([a, c]))
   })
+
+  // ---- Query→expand fusion (graph #61): seed from a query / find() result ----
+
+  it('query→expand: subgraph(query) seeds from the matches and expands their neighborhood', async () => {
+    // The only Project is d; 1-hop expansion brings in a (a → d ReportsTo).
+    const view = await brain.graph.subgraph({ type: NounType.Project }, { depth: 1 })
+    const ids = new Set(view.nodes.map((n) => n.id))
+    expect(ids.has(d)).toBe(true) // the query match (seed)
+    expect(ids.has(a)).toBe(true) // expanded neighbor
+    expect(view.edges.some((r) => r.from === a && r.to === d)).toBe(true)
+  })
+
+  it('query→expand: depth 0 returns just the matches, no expansion', async () => {
+    const view = await brain.graph.subgraph({ type: NounType.Project }, { depth: 0 })
+    expect(new Set(view.nodes.map((n) => n.id))).toEqual(new Set([d]))
+  })
+
+  it('accepts a find() result array as the seed set', async () => {
+    const matches = await brain.find({ type: NounType.Project }) // → [d]
+    expect(matches.length).toBeGreaterThan(0)
+    const view = await brain.graph.subgraph(matches, { depth: 1 })
+    const ids = new Set(view.nodes.map((n) => n.id))
+    expect(ids.has(d)).toBe(true)
+    expect(ids.has(a)).toBe(true)
+  })
+
+  it('query→expand returns empty when the query matches nothing', async () => {
+    const view = await brain.graph.subgraph({ type: NounType.Event }, { depth: 1 })
+    expect(view.nodes).toEqual([])
+    expect(view.edges).toEqual([])
+  })
 })