01
Access first
Best practice begins before the query
Record the customer purpose, acting account, entitled product, approved filters, and legal or provider authorization before running any search. DewEngine's search.perform target is decision-gated and has no implementation. A team must not substitute page crawling, private-request replay, access-control bypass, or reverse engineering when an authorized contract is absent. The feature should remain disabled or accept another lawful source.
- Fail closed when product entitlement is unknown
- Keep search useful through customer-supplied inputs when possible
02
Query record
Persist what the user actually asked
A result makes sense only beside its query context. Store normalized filters, customer-visible query label, account namespace, request time, result scope, and a hash or version of the search definition. Avoid storing secrets or unnecessary personal text. If the user edits a filter, create a new run rather than rewriting the provenance of earlier candidates.
- Give every search run a stable internal identifier
- Show which filters produced each reviewed candidate
03
Pagination
Represent incomplete pages honestly
Search results may be paginated, reordered, limited, or interrupted. Persist progress before requesting another page, deduplicate by provider-scoped resource identity, and expose partial coverage. Never assume page size, total count, or cursor stability without conformance evidence for the exact access path. A failed next page does not turn already observed items into a complete ranked result set.
- Scope cursors to workspace, account, and query version
- Resume from durable progress without duplicating candidates
04
Result meaning
Do not preserve rank as objective truth
A provider's ordering can be account-dependent and time-bound. It should not become an unexplained fit score in a CRM or ATS. Preserve observed order for traceability, then apply explicit customer rules separately. For example, a recruiter may review results against a requisition, but the integration must not infer protected traits or make an automated hiring decision from position.
- Label provider order separately from customer prioritization
- Require a human decision before attaching ambiguous identities
05
Retention
Keep candidates only as long as the purpose requires
A research queue, accepted CRM record, rejected candidate, and raw search observation can have different retention periods. Store the minimum fields needed for review, make correction possible, and propagate deletion through projections, caches, exports, and diagnostic stores. Do not build a permanent shadow index of professional people merely because search results were once visible to an account.
- Expire unreviewed candidates on a documented schedule
- Audit secondary exports and enrichment jobs
06
Test plan
Qualify ambiguity and failure, not just happy-path results
Conformance must cover empty queries, unsupported filters, duplicate pages, reordered items, revoked sessions, lost entitlement, throttling, partial runs, concurrent refresh, wrong-person matching, tenant substitution, correction, and deletion. The legal and provider gate, conservative query budgets, account health, and kill switch must pass before production. These practices describe a possible authorized integration, not current DewEngine access.
- Compare result identity across repeated approved runs
- Verify interruption never becomes a false complete state