feat(typed): generic, type-safe client and query builder

[mlwelles]

What this adds

A generic typed layer over modusgraph.Client that binds a Go type to the
otherwise any-typed client, giving you compile-time-typed CRUD and a fluent
query builder with no per-entity code generation. It is the handwritten
substrate modusgraph-gen's generated clients compose over, and it stands on
its own wherever you want types over modusgraph.

The whole diff lives under typed/. It builds and tests green against the
current client with no changes to the root package.

The problem it solves

modusgraph.Client is value-oriented: its methods take and return any, and a
query is assembled by hand from dgman primitives and decoded into a slice you
declare at the call site. Every call site repeats the same shape — declare the
destination, build the query, decode, re-assert the type. The typed layer lifts
that shape into the type system once.

Before — untyped client

// "First person named Alice" — the type is repeated on every line,
// and the single-result case is hand-rolled.
var out []Person
q := client.Query(ctx, &Person{}).
    Filter("eq(name, $1)", "Alice").
    First(1)
if err := q.Nodes(&out); err != nil {
    return nil, err
}
var person *Person
if len(out) > 0 {
    person = &out[0]
}

After — typed client

people := typed.NewClient[Person](client) // declare the type once

person, err := people.Query(ctx).
    Filter("eq(name, $1)", "Alice").
    First() // returns *Person; nil when nothing matched

The same lift applies across the API: Nodes() returns []Person,
IterNodes() yields *Person, Get returns *Person.

Query builder

Query[T] is fluent: builder methods chain, terminals (Nodes, First,
NodesAndCount, IterNodes) execute and decode typed results.

• Filters accumulate and AND together, each fragment parenthesized so a
  fragment containing OR keeps its precedence.
• OrGroup ORs several sub-scopes into one parenthesized group:

  // age >= 18 AND (name == "Alice" OR name == "Bob")
  people.Query(ctx).
      Filter("ge(age, $1)", 18).
      OrGroup(
          typed.NewDetachedQuery[Person]().Filter(`eq(name, "Alice")`),
          typed.NewDetachedQuery[Person]().Filter(`eq(name, "Bob")`),
      ).Nodes()

• WhereEdge constrains T by a scalar of a neighbour reached over an edge
  (a root filter cannot express this); resolved by a pre-pass and intersected
  with any root you set.
• IterNodes streams arbitrarily large result sets a page at a time over a
  single read-only snapshot.
• MultiQuery batches N same-type blocks into one round-trip.

On reusing dgman vs. reinventing it

The Or/OrGroup support builds on dgman, it does not reimplement it.
dgman exposes a single string-based Query.Filter(filter string, params ...any)
with $N positional markers and no AND/OR combinators and no root-intersection
helpers. So any builder offering Where/Or composition must assemble the
filter string itself and hand it to dgman's Filter. This layer does exactly
that and no more:

• the actual filtering, parameter binding, and injection-safe $N substitution
  stay in dgman (Query.Filter, parseQueryWithParams);
• shiftPlaceholders only renumbers $N to match dgman's own convention
  when independently-written fragments are concatenated — it does not re-parse
  or re-escape values;
• the layer adds only what dgman lacks: fragment composition (AND/OR grouping
  with correct precedence) and the type binding.

Review round — changes since first push

Addresses the automated review (cubic). Highlights:

• Filter precedence (P1): combineAnd now parenthesizes each fragment, so
  a raw OR fragment no longer binds incorrectly when ANDed.
• WhereEdge roots (P1): the pre-pass no longer discards a caller-set
  UID/RootFunc; it intersects via a uid() @filter instead.
• MultiQuery reuse (P1): Add rejects the same *Query[T] under two names
  (Execute names the underlying query in place).
• NodesAndCount tracing: now opens a span like the other terminals.
• Tests: added a precedence regression, a WhereEdge+root intersection
  test, and a duplicate-Query guard; the filter-sequencing test now asserts
  the exact expression; the laziness check is delta-based.

Documentation

• Package doc.go with the before/after narrative and the design rationale.
• Runnable, compile-checked examples for the client, query builder, OrGroup,
  WhereEdge, IterNodes, and MultiQuery.
• A verified-output example for the filter builder.

[cubic-dev-ai]

5 issues found across 16 files

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[matthewmcneely]

Six subpackage files are missing the SPDX header that every other file in the repo carries: filter/filter.go, filter/fulltext.go, filter/filter_test.go, filter/fulltext_test.go, search/merge.go, search/merge_test.go.

[matthewmcneely]

@mlwelles Also, can you update the README with the major feature additions of this PR?

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>