[pournasserian]

Closes #2559

What

The first slice of F-SRC (#2430): the search interface from ADR-0010 with its two in-database implementations, indexing in the write's transaction, text search with type and state filters, and the agent's search tool (SRC-01, MCP-01).

• Core (FluentCMS.Core.Search):
  • [ExtensionPoint] ISearchIndex: IndexAsync(SearchDocument) inside the write's unit of work, and MatchAsync(terms, skip, limit), which returns entry ids with a rank, best first in a stable order, so a caller pages through them.
  • SearchText.From(fields): every string and number of an entry's fields, a fact's value and source included, as lowercase words, cut at 100,000 characters. A string that is a GUID, such as a reference or media id, is left out.
  • SearchTerms.From(query) splits a query into the same words.
  • ISearch.SearchAsync(SearchQuery) takes text, optional content types, states, published-only and a limit (20 by default, 100 at most). It returns hits with the type, state, versions, rank and via.
• Infrastructure:
  • PostgreSQL: a SearchDocuments table with a stored tsvector under the simple configuration and a GIN index.
  • SQLite: an FTS5 table with unicode61 that keeps diacritics.
  • Both tables are outside the EF model and created by their migration, which also indexes every entry that already exists.
  • EntryDirectory indexes on create and update, inside the write's unit of work.
  • EntrySearch joins the matches with the entry rows. Deleted entries drop out, restored ones come back and published-only works, all without touching the index. It then follows each match to the entries whose latest version references it.
  • A hit's state is the one the entry tools show: in_review is read from the change sets holding the entry, as EntryDirectory reads it, and the states filter uses the same state.
• Scopes: only types the caller may read (IAgentPermissions.ReadableTypesAsync) are searched, and only readable matches lead to referencing entries. A types filter naming a type that does not exist returns content_type_not_found, and one outside the scope agent_scope_denied, as list_entries does, so neither is mistaken for no matches.
• Tool: search_entries (query, types, states, published_only, limit), read-only, with a row in McpCoverageTests. The result has a next line naming the call that reads a hit, or what to change when nothing matched. An empty types or states list is refused with search_filter_empty.
• F-EXT: AddFluentCmsExtension takes a lifetime, so a database-backed extension can be scoped.
• CONTRIBUTING.md: how search indexes and what an external engine implements.

Why

SRC-01 asks for full-text and structured search for agents and the desk, and ADR-0010 puts it in the application database behind an extension point. The epic's S2 case is an agent searching for "4411" and finding the Product entity and the page that references it.

Choices worth a look:

• Words, not raw text: both indexes get the same lowercase words. The two tokenizers would otherwise split "19.99" and "A-4411" differently, and the same query has to find the same entries on both providers.
• Prefix match on every term: "441" finds "A-4411", and every term must match.
• Entry rows decide everything but the text, so publish, delete and restore need no index change, and the index stays an interface an external engine can implement.
• Referencing entries are found through the reference index. Only a page's latest version counts, and the page shows the match it came through.
• Matches are read a page at a time, 1,000 by default, until enough pass the scope, deletions and filters, the index has no more, or 10,000 are read, every entry at M1's scale. Better-ranked matches of a type the agent may not read cannot crowd out its own. A search that stops at the ceiling returns complete: false, and the tool's next says so. Search__PageSize and Search__MaxMatches set both. Only the columns a hit needs are read.
• Indexed text is cut at 100,000 characters, well inside PostgreSQL's 1 MB limit on a tsvector, so a very long entry is still stored.
• Known limits:
  • On SQLite the index update deletes by an unindexed column, a scan of the FTS table, which is fine at M1's 10,000 entries.
  • On a PostgreSQL database with a C locale, the migration's backfill splits non-ASCII letters, so entries that existed before it need a save to be found by such words (Index existing entries for search without depending on the database locale #2589). New writes are not affected.
  • Combining marks split words, fact dates are indexed, and very long words differ between providers (Search words: keep combining marks, leave fact dates out, and treat long words alike on both providers #2597).
• Not in this PR: filters on field values and references (next slice), the desk search box and pickers (desk lane), and semantic ranking.

Tests

Unit: text flattening (strings and numbers, facts, arrays, diacritics kept, GUIDs left out, the length cap) and query splitting.

Integration, each on SQLite and PostgreSQL:

• "4411" finds the product entity and the page via it. "441" finds the same, two words narrow to entries with both, a type filter keeps the page, and published-only is empty until the product is published.
• An entry rolled back with its unit of work is not found. Once its write commits it is found by its words, after an update by its new words only, not while deleted, and again after a restore. An update that rolls back leaves the old words found and the new ones not.
• With a page of 20 and a ceiling of 60, a page-only search finds a page ranked behind 45 notes. Behind 65 notes it returns no hits and complete: false. An unfiltered search stops after its first page.
• A product's id is not found as a word, before and after the backfill.
• Entries that existed before the index are found after migrating down past it and up again, which exercises the backfill SQL and Down.
• An entry in a submitted set is a hit in in_review, a published entity in published, and the states filter keeps each by that state.
• An empty query, too many words, an empty filter and an out-of-range limit are refused with their codes.
• Over HTTP, an agent scoped to pages finds the page and not the product with the same words, the same hits ISearch returns for it. States narrow the result, and an empty query, an unknown state and an empty filter are tool errors.
• An agent scoped to pages does not find a page through the product it references, while a person finds both.
• A types filter with an unknown type and one outside the scope returns both errors.
• With a limit of 1, an agent scoped to pages finds its page past 15 better-ranked products. With the old budget of ten matches per hit this test fails on both providers.

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