ADR-0003. Detect schema drift but never auto-rebuild collections

Field	Value
Status	Accepted
Date	2026-03-01
Deciders	@search-team
Supersedes	—

Context

• On bootstrap, TypesenseSearchEngineComponent compares each registered collection config against the live Typesense collection.
• Typesense cannot alter most field definitions in place; applying a changed schema generally means dropping and recreating the collection.
• Recreating a collection deletes all its documents, which would silently wipe the search index on a routine deploy.
• Reindexing from CDC/source after a drop can take a long time and leaves a window of empty/partial results.

Decision

We will create a collection if it is missing, but on divergence we only log an error ("manual migration required") and leave the live collection untouched. Additive field changes are rolled out via the explicit backfill scripts (migrate:references, migrate:denorm); destructive recreations are a deliberate, human-run operation.

Consequences

Pros	Cons
A deploy can never silently wipe the index	Schema changes require a manual step + operator awareness
Operators choose a safe reindex window	Config and live schema can stay diverged until acted on
Backfill scripts handle the common additive case	New destructive changes need a documented runbook step

Alternatives Considered

Option	Pros	Cons	Why rejected
Auto drop + recreate on divergence	Fully automated	Wipes documents on every schema change deploy	Unacceptable data-loss risk
Block bootstrap on divergence	Forces action	Takes the whole host down for a search schema diff	Too blunt; search is non-critical-path
Versioned alias swap (blue/green collections)	Zero-downtime reindex	More moving parts, alias management	Deferred — overkill for current scale

References

• packages/search/src/components/typesense-search-engine.component.ts — ensureCollectionsWithMigration
• packages/search/src/helpers/schema-migration.helper.ts
• Operations