[pournasserian]

Closes #2599

What

The second slice of F-SRC (#2430): search filters on field values and references, combined with text, or without text for one type (SRC-01).

• Core (FluentCMS.Core.Search):
  • SearchQuery.Fields: filters on the latest version's field values, all of which must hold. Each is a FieldFilter(field, operator, value), and they need exactly one type in ContentTypes.
  • SearchQuery.References: an entry or entity id. Only entries whose latest version references it are kept.
  • FieldFilters checks the filters against the type's definition before anything is read, and applies them to an entry's fields:
    • Text, rich text and enum fields take equals and contains, which ignores case.
    • Number and date-time fields take equals, less_than, at_most, greater_than and at_least. Numbers are compared as decimals, as the number field type stores them. A date-time value is a point in time in ISO 8601 with an offset, or a YYYY-MM-DD date for a dateOnly field, checked with the same rules the field type uses.
    • Boolean and reference fields take equals.
    • On an entity, the fact's value is compared.
    • A missing or null field holds no filter.
    • Lists, JSON and media are refused as not filterable.
  • New codes: search_filter_needs_one_type, search_field_not_found, search_field_not_filterable, search_operator_not_supported and search_filter_value_invalid. An empty Fields list is search_filter_empty.
• Text is optional when the query names one type and filters it by fields or a reference. The candidates are that type's entries in id order, read a page at a time like text matches, with a rank of 0 and no via hits.
• Infrastructure: EntrySearch applies the field and reference filters to each page's candidates that pass the scope, deletions and state filters. It reads their latest versions in one query per page, and the same rules apply to entries found through a reference.
• Tool: search_entries takes fields, an array of {field, operator, value}, and references, an id. query is optional with one type and either filter. A malformed item or an unknown operator is an argument error naming its position.
• ToolArgumentsReader.OptionalArray.

Why

SRC-01 asks for full-text and structured search. The first slice filtered by type, state and published version. Agents next ask for things like "products under 20" or "the pages that reference this product".

Choices worth a look:

• Field values are filtered in C# on the candidates, not in SQL. ADR-0010 says structured filters are ordinary EF queries, and the reference filter is one. The fields, though, are JSON whose shape depends on the type, and an entity's value sits inside its fact. One evaluator gives the same answer on both providers, and it runs only on candidates that already passed everything else, a page at a time. A search without words reads at most Search__MaxMatches of the type's entries and says when it stopped early. If the maintainer prefers SQL here, it can move behind the same FieldFilters rules.
• Field filters need one type, so each field and its type are known, and a wrong operator or value is refused before anything is read instead of matching nothing.
• Without words there is no rank and no via: every candidate is a match, so a reference has nothing to explain.
• Not in this PR: filters on list items, JSON paths and media metadata, ordering by a field, and the desk search box (desk lane).

Tests

Unit: each field type's operators and value kinds, with their refusals, including dates without an offset or in another form. Each operator on text, decimals beyond a double's precision, date-times with offsets, calendar dates, booleans and references. A missing or null field, all filters having to hold, and an entity's fact value.

Integration, each on SQLite and PostgreSQL:

• "widget" with price less_than 20 on an entity type finds the product at 19.99, and not those at 25 or without the word. With no words, name contains "wid" finds both widgets, with rank 0.
• references finds the page whose latest version references the product, and not one whose earlier version did. Combined with words, it keeps only matches that also reference it.
• Field filters with no type or two types, a reference filter with no words and no type, an empty fields list, an unknown field, contains on a number and values of the wrong kind are refused with their codes.
• Over HTTP, on an entity type, an agent filters by the price fact, finds both products with contains and no query, and finds by reference the page whose latest version references the product, not the one whose earlier version did. An unknown operator and an incomplete item are argument errors.
• Over HTTP, no type or two types, an unknown field, contains on a number and a value of the wrong kind each return their code.

The full suite ran locally against a postgres:17 container as well as SQLite, and markdownlint passes. No new package and no new project reference.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers