fix(search): match bare-id reference searches on Postgres

[aacruzgon]

Summary

On the Postgres backend, reference search parameters matched only when the query value carried a Type/ prefix — a bare logical id matched nothing and returned an empty Bundle. Observation?patient=<id> is the primary form in the spec and the shape Inferno uses throughout, so essentially every clinical search on Postgres returned zero.

References are indexed as written (search/writer.rs stores Reference.reference verbatim), so the stored value is the literal Patient/<id>. The query compared the raw search value against it with equality only. SQLite, MongoDB and Elasticsearch all branch on whether the value carries a / and fall back to a suffix match; only Postgres did not.

Fixes #490.

Changes

postgres/search/query_builder.rs

• build_reference_condition now branches on whether the version-stripped value contains /, mirroring the SQLite handler. A bare id matches exactly, as a /<id> suffix, or with a trailing /_history/<vid>; a Type/id or absolute URL keeps its previous exact-plus-versioned semantics.
• Added the :Type modifier, which was not handled on Postgres at all — subject:Patient=<id> also returned zero. A bare id is now resolved to Type/id and matched as a type-prefixed reference.
• The plain path binds fully-formed patterns built with the file's existing like_escape plus ESCAPE '\', rather than concatenating the raw value onto a pattern in SQL. This is load-bearing for the new suffix match: unescaped, patient=% would become LIKE '%/%' and match every stored reference. The :contains, :below and :above paths keep their existing behavior.
• That varies the parameter count per value (two for a type-prefixed reference, three for a bare id), so the loop runs a counter instead of offset + i. build_search_query already advances the next parameter's offset by params.len(), and both production callers append fragment.params wholesale, so placeholder numbering for following parameters is unaffected.
• Matching stays version-agnostic and the OR-list still compiles to a single sublink (the semi-join shape that reference_or_list_is_a_single_sublink guards).

Testing

• cargo test -p helios-persistence --features postgres,sqlite,R4 --lib backends::postgres::search::query_builder — 14 passed, including 4 new: bare-id parameter binding, :Type normalization, version stripping, and LIKE-metacharacter escaping.
• cargo test -p helios-persistence --features postgres,sqlite,R4 — full suite, 0 failures.
• New postgres_integration_search_reference_bare_id against a real Postgres via testcontainers, covering bare id, :Type + bare id, a decoy patient, and the wildcard case. The existing postgres_integration_search_reference only ever asserted the Type/id form, which is how the gap survived.
• Regression guard confirmed: with the fix reverted, the new integration test fails with left: [] right: ["obs-1", "obs-2"].

End to end

Postgres 16 in Docker, hfs built as CI builds it (--features R4,sqlite,elasticsearch,postgres,mongodb,s3), Inferno fixtures loaded via crates/hfs/tests/inferno/install.sh — the reproduction from #490:

query	before	after
Observation?_summary=count (control)	246	246
Observation?patient=us-core-client-tests-patient	0	27
Observation?patient=Patient/us-core-client-tests-patient	27	27
Observation?subject=us-core-client-tests-patient	0	27
Observation?subject:Patient=us-core-client-tests-patient	—	27
Condition?patient=us-core-client-tests-patient	0	2
Encounter?patient=us-core-client-tests-patient	0	1
Observation?patient=%	—	0
Observation?patient=nonexistent-id	—	0

Every value now matches the SQLite column.

Inferno

Ran us_core_v800 locally against both backends on the same fixtures:

backend	pass rate
postgres (before, 2026-08-02 nightly)	4.6% (25/544)
postgres (after)	60.2% (328/544)
sqlite (same local run)	59.9% (326/544)

Postgres is now at parity with SQLite. Diffing the two failure sets: 10 shared (all already in the workflow's OMITTED_TESTS for v8.0.0), 0 SQLite-only, 3 Postgres-only.

Notes

• Expect the Postgres Inferno job to go red after this merges. It reported success at 4.6% only because the gate counts fail/error and every clinical group degraded to skip. With those groups now proceeding, the 3 Postgres-only failures become real. That is the gate working, but it will look like a regression in the run history.
• Those 3 failures are all patient_category_date_search_test on vital-signs profiles, and are a separate pre-existing defect — filed as postgres search: dates with a negative UTC offset fail to parse and are silently indexed as Utc::now() — every date search over them is wrong #494. Dates carrying a negative UTC offset fail to parse in the Postgres writer and are silently indexed as Utc::now(). Confirmed independent of this change: it reproduces with no reference parameter at all (Observation?_id=<obs>&date=gt2023-08-02 returns 1 on Postgres, 0 on SQLite), and bare-id and type-prefixed reference forms return identical results.
• No schema or migration change; this is query-side only. Existing indexed data is unaffected.
• Not addressed here: build_contained (_contained=true) still compares references with equality only — same gap on a narrow path. Chained search is identical on both backends (LIKE '%value%') and unaffected.
• Also unchanged: the silent-failure posture from postgres search: reference parameters match only Type/id — a bare id matches nothing, so patient=85 returns zero (Inferno pass rate 4.6%) #490 — an unsatisfiable reference shape still returns a Bundle with total: 0 rather than an OperationOutcome, and Prefer: handling=strict still returns a Bundle. That is the search: _tag, _profile and _security filters are silently dropped — even under Prefer: handling=strict — and the self link claims they were applied #474-class concern and is out of scope here.
• Clippy was not run locally; the workspace has pre-existing failures under clippy 1.96 in files untouched by this change (doc_lazy_continuation in helios-serde-support, collapsible_if in the helios-fhir build script, large_enum_variant in generated crates/fhir/src/r6.rs). Leaving that to CI.

[codecov]

Codecov Report

❌ Patch coverage is 96.58120% 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.58%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!