feat(12-01): report the search engine's found count and field weights

- optional beachcomber.PageSearcher returns a page of candidate ids plus
  the engine's found count; beachcomber.SearchPage falls back to
  SearchIDs for engines without it, so Engine is unchanged
- Query.QueryByWeights is sent to Typesense as query_by_weights; a
  mismatched weight list or a page above typesense.MaxPerPage (250) is
  refused before any request

modules/beachcomber/searchable.go

@@ -62,6 +62,10 @@ type Query struct {
 	Q string
 	// QueryBy lists the fields Q is matched against.
 	QueryBy []string
+	// QueryByWeights ranks the QueryBy fields, one weight per field in the
+	// same order (Typesense query_by_weights). Empty leaves the engine
+	// default; a length different from QueryBy is an error.
+	QueryByWeights []int
 	// FilterBy is an engine filter expression, for example
 	// "collection_id:=5".
 	FilterBy string
@@ -73,6 +77,35 @@ type Query struct {
 	PerPage int
 }
 
+// SearchResult is one page of candidate ids and the number of documents
+// the engine found for the query. Both are candidates only: callers re-gate
+// the ids, and recount any total they expose, in SQL.
+type SearchResult struct {
+	IDs   []string
+	Found int
+}
+
+// PageSearcher is implemented by an engine that can report how many
+// documents matched besides the page of ids. It is optional so that
+// existing Engine implementations stay valid; use SearchPage to call it.
+type PageSearcher interface {
+	SearchPage(ctx context.Context, index string, q Query) (SearchResult, error)
+}
+
+// SearchPage asks e for one page of q: through PageSearcher when e
+// implements it, otherwise through SearchIDs with Found set to the number
+// of ids returned.
+func SearchPage(ctx context.Context, e Engine, index string, q Query) (SearchResult, error) {
+	if ps, ok := e.(PageSearcher); ok {
+		return ps.SearchPage(ctx, index, q)
+	}
+	ids, err := e.SearchIDs(ctx, index, q)
+	if err != nil {
+		return SearchResult{}, err
+	}
+	return SearchResult{IDs: ids, Found: len(ids)}, nil
+}
+
 // Gate is the application kill-switch consulted before every sync. It
 // reads its setting through db, a clean session on the write's connection
 // (inside a caller's plain transaction, a savepoint of it); any error must