feat: implement durable permission-aware search

README.md

@@ -16,3 +16,23 @@ development fallback. Other modules may:
 
 An optional OpenSearch adapter is a later provider, not a hard dependency.
 Source modules remain responsible for defining visibility and authorization.
+
+## Index lifecycle
+
+Source modules register a versioned `search_sources` provider. A provider
+declares its resource types and index version, returns bounded resumable
+backfill pages, and batch-rechecks current authorization for sensitive
+resources. Incremental writes use `SearchIndexChange` and
+`search.index_writer.enqueue_change()` so change IDs are durable and
+idempotent in the same database transaction as the caller.
+
+The built-in backend exposes opaque cursor pagination and does not return
+pre-authorization totals. PostgreSQL uses full-text search and will add
+trigram indexes when `pg_trgm` is already installed; SQLite remains a bounded
+development fallback.
+
+Tenant search administrators can inspect `/api/v1/search/admin/diagnostics`,
+reconcile disabled modules, process queued changes, and start or continue
+resumable provider rebuilds. Rows requiring a source authorization recheck
+are omitted when their provider is unavailable, stale, or fails to return an
+explicit allow decision.