fix(postgres): index bare reference ID searches

[Gordex2014]

Closes #1414.

PostgreSQL bare-ID reference searches previously combined an equality with a leading-wildcard suffix match. Accurate totals therefore scanned the full reference-parameter slice and timed out on the Synthea QA corpus.

This change:

• adds schema v41 with a partial expression index for the final segment of stored references;
• changes only plain bare-ID searches to one equality against that expression;
• preserves exact Type/id, absolute URL, :Type, modifier, and contained-reference behavior;
• makes index creation and the schema marker atomic;
• allows clustered instances to wait for the migration without inheriting the query statement timeout;
• bounds the optional post-migration analyze so it cannot hold startup indefinitely.

Validation:

• 231 PostgreSQL unit tests passed;
• 269 PostgreSQL integration tests passed;
• PostgreSQL-only HFS compilation and formatting passed;
• custom and generic plans use idx_search_reference_target_id with the target value in Index Cond and no suffix filter;
• full-corpus bare-ID search returned HTTP 200 in 0.374 seconds with the expected total of 165 and the same five ordered resources as Patient/id.

Deployment note: schema v41 uses transactional, non-concurrent CREATE INDEX. It permits reads but blocks writes to search_index while building. Build time and disk use scale with reference rows; the QA corpus produced an approximately 3.3 GB index. Reference writes subsequently maintain one additional btree entry.

Visual explanation

See the query-path, migration, and verification summary.

Temporary review evidence expires 2026-09-26T19:59:38.754Z.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[codecov]

Codecov Report

❌ Patch coverage is 99.06977% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ence/src/backends/postgres/search/query_builder.rs	96.47%	3 Missing ⚠️
crates/persistence/src/backends/postgres/schema.rs	99.71%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!