--- id: WF-PFM-QRY-015 title: Index CRM record changes into Quick Search trigger: CRM submits a batch of at most one hundred record-change events to the search indexer. product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f inference: [] implements: - CAP-PFM-QRY-017 moves: - STATE-PFM-QRY-013 crosses: - SVC-PFM-QRY-quick-search idempotency: >- Distinct records are projected under newly claimed versions. Provider ordering rejects older writes, while duplicate events can cause newer claims and repeated projection reads. concurrency: >- Five indexer invocations are reserved; CRM owns delivery buffering and retries when the indexing function is throttled or fails. hops: - 'n': 1 actor_or_service: CRM change-event consumer action: Receive the CRM batch and return a result for each event. anchor: 'services-platform:modules/quick-search/aws/logic/quick-search-indexer.lambda.ts' seam: event on_failure: The submitting service retries missing or failed results under its change-delivery policy. left_inconsistent: Search remains behind committed CRM changes until indexing or repair succeeds. observer: CRM's change-event delivery records; the indexer's alarms provenance: observed source: 'services-platform:modules/quick-search/services/indexing/handle-change-events.ts' - 'n': 2 actor_or_service: Indexer action: >- Skip scopes that are absent, unready for indexing or deleting, and ignore changes proven unrelated to configured projection fields. anchor: 'services-platform:modules/quick-search/services/indexing/handle-change-events.ts' seam: sync on_failure: Skipped events are acknowledged rather than treated as indexing failure. left_inconsistent: No document update is attempted for those skipped scopes. observer: indexer log counts provenance: observed source: 'services-platform:modules/quick-search/services/indexing/handle-change-events.ts' - 'n': 3 actor_or_service: Indexer action: >- Claim versions before reading projections and write each record’s target-generation document or deletion state through the query layer. anchor: 'services-platform:modules/quick-search/services/indexing/index-records.ts' seam: sync on_failure: Provider failures report affected workspace events as failed. left_inconsistent: >- Claimed versions can precede provider contents until retry or reconciliation repairs the write. observer: per-event results provenance: observed source: 'services-platform:modules/quick-search/services/indexing/index-records.ts' - 'n': 4 actor_or_service: Indexer action: >- Refresh contacts affected by organization changes, using a related rebuild when the fanout exceeds two hundred. anchor: 'services-platform:modules/quick-search/services/rebuild/request-rebuild.ts' seam: state_machine on_failure: A failed job start leaves a pending rebuild for recovery. left_inconsistent: Related display values can remain stale until that work succeeds. observer: the rebuild job list provenance: observed source: 'services-platform:modules/quick-search/services/indexing/handle-change-events.ts' branches: [] waits: [] evidence: - >- services-platform at ad3f6a6: modules/quick-search/services/indexing/*.ts; aws/logic/quick-search-indexer.lambda.ts; services/rebuild/request-rebuild.ts; docs/proposals/quick-search.md §9 controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Index CRM record changes into Quick Search ## What It Does CRM submits a batch of at most one hundred record-change events to the search indexer. ## The Flow ```mermaid sequenceDiagram participant C as Request or schedule participant H0 as CRM change-event consumer participant H1 as Indexer participant H2 as Indexer participant H3 as Indexer C-)H0: Receive the CRM batch and return a result for each event H0->>H1: Skip scopes that are absent, unready for indexing or deleting, and ignore changes proven unrelated t H1->>H2: Claim versions before reading projections and write each record’s target-generation document or dele H2-)H3: Refresh contacts affected by organization changes, using a related rebuild when the fanout exceeds t ``` Receive the CRM batch and return a result for each event. Skip scopes that are absent, unready for indexing or deleting, and ignore changes proven unrelated to configured projection fields. Claim versions before reading projections and write each record’s target-generation document or deletion state through the query layer. Refresh contacts affected by organization changes, using a related rebuild when the fanout exceeds two hundred. ## When Something Fails The submitting service retries missing or failed results under its change-delivery policy. Search remains behind committed CRM changes until indexing or repair succeeds. Skipped events are acknowledged rather than treated as indexing failure. No document update is attempted for those skipped scopes. Provider failures report affected workspace events as failed. Claimed versions can precede provider contents until retry or reconciliation repairs the write. A failed job start leaves a pending rebuild for recovery. Related display values can remain stale until that work succeeds. ## Idempotency and Concurrency Distinct records are projected under newly claimed versions. Provider ordering rejects older writes, while duplicate events can cause newer claims and repeated projection reads. Five indexer invocations are reserved; CRM owns delivery buffering and retries when the indexing function is throttled or fails.