feat(search)!: per-reference label sources

[ddeboer]

Slice 4 of #534, stacked on #561: per-reference label sources, replacing the single global sidecar labels collection. Design captured in ADR 7.

Schema (@lde/search)

ReferenceField.labelSource names the SearchType whose collection resolves the reference’s labels. The named type must declare an output, searchable text field called label – something to reconstruct a label from, and something to type ahead against (the future facet-by-name entry point). searchSchema validates this schema-wide, so a dangling or unsuitable source fails at startup. A reference without a labelSource stays id-only: its IRIs never travel in a lookup.

Resolving open decision 1 of #534 as decided: the global labels collection is dropped, not kept as a typeless fallback – a typed entity collection and a ‘labels collection’ are the same kind of thing (one entry in collections).

Engine (@lde/search-typesense)

• Each reference field resolves from its own source’s collection; all sources’ id-lists are bundled into the single multi_search the engine already used (per-source batches of 200).
• Labels reconstruct from the source type’s label declaration (per-locale display fields), with a bare untagged label value as the und fallback – so existing sidecar-shaped documents keep working during migration.
• The opt-in in-memory cache (labelCacheTtlMs) now caches per source collection, single-flight per collection.
• Reference facet buckets are labelled from the facet field’s own source, exactly as hit references are.

Covered by the issue’s resolver spec: labels resolve batched per source, fields without a source are pruned from lookups, dangling references degrade to id-only; plus the migrated container-backed integration suite, where the label collection is now built from the same SearchType declaration via buildCollectionSchema.

Also

Degeneralizes UI-specific “sidebar” wording in ADR 5, the READMEs and JSDoc to “a faceted listing” – the sidebar is a consumer (Dataset Register) notion, not LDE’s.

Breaking changes

TypesenseSearchEngineOptions.labelsCollection is removed. Migration: declare each label source as a SearchType, add its collection to options.collections, set labelSource on each reference field, and rebuild label collections via buildCollectionSchema so the physical label fields exist. fetchLabels now takes label-lookup groups instead of (collection, iris).

Part of #534 (slice 4; the facet-by-name two-step itself follows separately with #533’s value-query IR).