--- id: DOM-PFM-QRY-005 title: Search Index realises: CON-PFM-QRY-005 product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-QRY-quick-search readable_by: [] lifecycle: STATE-PFM-QRY-013 custom_fields: none identity: >- A search scope pairs a workspace with a registered record type. Documents use the source record’s identity within that scope, while numeric generations coordinate rebuilds. Browser credentials are derived for a request and have no stored record identity. attributes: - name: record type kind: enum required: true computed: false notes: >- The code registry fixes the owning application, dataset, access grant, provider and fallback projection for each type. - name: field list kind: collection required: true computed: false notes: >- The workspace chooses one to thirty distinct eligible fields across three ranking tiers, replacing the owner’s defaults under a configuration version. - name: active and target generation kind: number required: true computed: false notes: >- Active and target generations track ledger progress and configuration versions. They do not isolate provider visibility, and the target cannot precede the active number. - name: settings version kind: number required: true computed: true notes: The ledger records the provider-settings release associated with completed generation work. - name: readiness and diagnostics kind: computed required: false computed: true notes: >- First activation, reconciliation counts, bounded degraded-field diagnostics and truncation counts describe index health. - name: provider and target kind: text required: true computed: false notes: The provider stores documents in the environment’s shared index target. - name: document claims kind: collection required: true computed: true notes: >- Per-record claims increase the indexing version and retain live or deleted state; deleted claims are retained for at least fourteen days. - name: documents kind: collection required: true computed: true notes: >- The provider holds searchable tiers, display values, discovery markers, workspace tags, generation metadata and write versions rather than storing documents in the application database. - name: rebuild jobs kind: collection required: false computed: true notes: >- Durable jobs retain full or related rebuild scope, cause, steps and history for initial, configuration, explicit and repair work. - name: search credential kind: computed required: false computed: true notes: >- The signed key restricts index, workspace, live documents and permitted requested types. The browser renews at eighty percent of its lifetime. relationships: - to: DOM-PFM-QRY-001 cardinality: one-to-one ownership: >- Each record type uses one dataset for vocabulary and projection; the index retains the derived provider representation. cross_service: true invariants: - id: INV-DOM-PFM-QRY-005-01 statement: >- The target generation cannot trail the active ledger value. Activation uses compare-and-set, but provider replacements can affect live search before activation. enforced_at: - database - service provenance: observed source: >- services-platform:modules/quick-search/services/persistence/index-states.ts:activateGeneration; modules/quick-search/services/providers/algolia/filters.ts:accessFilter; modules/quick-search/services/providers/algolia/documents.ts:objectIdOf - id: INV-DOM-PFM-QRY-005-02 statement: A target change and the rebuild request needed to satisfy it commit together. enforced_at: - service provenance: observed source: 'services-platform:modules/quick-search/services/rebuild/request-rebuild.ts:requestRebuild' - id: INV-DOM-PFM-QRY-005-03 statement: >- Only one full rebuild remains open for a workspace and record type; further requests join that work. enforced_at: - database - service provenance: observed source: >- services-platform:modules/quick-search/db/quick-search-rebuild-jobs.table.ts (quick_search_rebuild_jobs_open_full_uidx) - id: INV-DOM-PFM-QRY-005-04 statement: >- Provider document writes use increasing claimed versions to reject older writes and retain deletion precedence. enforced_at: - service provenance: documented source: 'services-platform:docs/proposals/quick-search.md#9.3' - id: INV-DOM-PFM-QRY-005-05 statement: >- Credentials authorize the caller’s workspace and every requested type; requesting any unauthorized type refuses the complete access request. enforced_at: - service provenance: observed source: 'services-platform:modules/quick-search/services/access/issue-access.ts' - id: INV-DOM-PFM-QRY-005-06 statement: >- Field configuration accepts one to thirty unique eligible fields as a whole. An identical replacement creates neither a new version nor a rebuild. enforced_at: - service provenance: observed source: 'services-platform:modules/quick-search/services/configuration/apply-configuration.ts' - id: INV-DOM-PFM-QRY-005-07 statement: >- Deletion-state guards refuse new rebuild requests and make rebuild and change-event processing stop indexing the workspace. enforced_at: - service provenance: observed source: >- services-platform:modules/quick-search/services/rebuild/request-rebuild.ts; services/rebuild/quick-search-rebuild-operations.ts; services/indexing/handle-change-events.ts - id: INV-DOM-PFM-QRY-005-08 statement: >- Reading an unconfigured type returns the default configuration at version zero without persisting a settings row. enforced_at: - service provenance: observed source: 'services-platform:modules/quick-search/services/configuration/provision.ts' physical: - platform.quick_search_configurations - platform.quick_search_index_states - platform.quick_search_documents - platform.quick_search_rebuild_jobs - platform.quick_search_rebuild_job_steps - platform.quick_search_rebuild_job_events - the provider index rhythm2_quick_search (Algolia; no table) evidence: - >- services-platform at ad3f6a6: modules/quick-search/registry/record-types.ts; db/*.table.ts; services/access, configuration, indexing, rebuild, maintenance, persistence and providers; docs/quick-search.md; docs/proposals/quick-search.md (approved 2026-10-09) - 'react-console at baf6dae: lib/quick-search/*.ts; components/console/quick-search/*.tsx' --- # Search Index ## What It Models The search index is a derived lookup view of contacts and organizations. It supports typed discovery while the applications remain responsible for opening and editing the records. ## Identity and Attributes A workspace and record type form the indexing scope. Configurations select fields; claims order writes; generations describe rebuild progress in the database ledger. ## Relationships Dataset metadata supplies searchable vocabulary. Provider documents and browser credentials belong to the search boundary rather than the business-record store. ## Invariants The invariant rows locate write ordering, access restrictions and rebuild coordination. Ledger activation does not provide an atomic switch of visible provider documents. ## How It Is Stored and Shared Quick Search keeps settings, claims and jobs in the database and projections at the provider. CRM events and scheduled repairs update that derived state. ## Open Design Questions The organization gate conflict and mixed-generation rebuild visibility remain unresolved product issues. Existing credentials can retain access until their short lifetime ends.