Metadata-Version: 2.4
Name: govoplan-search
Version: 0.1.18
Summary: Permission-aware global and contextual search for GovOPlaN.
Author: GovOPlaN
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: govoplan-core>=0.1.18
Dynamic: license-file

# govoplan-search

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

Permission-aware global and contextual search for GovOPlaN. Search is the first
command in the titlebar action group. Clicking its icon, pressing `F3`, or
pressing `Ctrl`/`Cmd`+`K` opens the same full query field and result overlay.

The titlebar command, result overlay, filters, and Search administration route
announce stable help contexts. Pressing `F1` while one of those controls is
focused opens its Search documentation, with the current page retained as a
fallback.

The route, overlay, state, accessibility, and consequence mapping is recorded in
[`docs/INTERFACE_PATTERN_MIGRATION.md`](docs/INTERFACE_PATTERN_MIGRATION.md).

The module works with its built-in database index and no external search
service. PostgreSQL uses native full-text search; SQLite provides a bounded
development fallback. Other modules may:

- register a live search provider in their module manifest
- write authorized documents through the `search.index_writer` capability
- announce context-sensitive WebUI search scopes through `search.contexts`

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. A source may additionally implement the event-source extension to
translate committed platform events into `SearchIndexChange` records. The
platform event worker queues those records idempotently and applies them to the
derived index; Search never imports a source module or invents its ACL. Direct
capability callers may still use `search.index_writer.enqueue_change()` when
they already own a suitable transactional boundary.

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 use **Administration > Search index** or the
equivalent `/api/v1/search/admin/*` endpoints to inspect source coverage,
reconcile disabled modules, process queued changes, and start or continue
bounded provider rebuilds. Quarantined changes and provider errors stay
visible. Rows requiring a source authorization recheck are omitted when their
provider is unavailable, stale, or fails to return an explicit allow decision.

Files, Campaign, Calendar, Mail, IDM, and Postbox provide native source
adapters. Mail indexes only its bounded read-only cache, and Postbox never
indexes ciphertext or key material. All six recheck current source-owned
authorization when results are returned.
