feat(search)!: resolve a reference across several targets

[ddeboer]

Fix #717

A lookup’s target (and an idOnly’s labelSource) may now name several Root Types, in order of precedence, so a field whose referent may be a Person or an Organization labels every value, types every value truthfully, and serves each kind’s own fields.

What changes

Declaration (@lde/search)

• target: string | readonly string[], labelSource likewise; one plural reading (labelSourceNamesOf, labelTargetNamesOf, localLookupTargetsOf, referencedTargetsOf) replaces the single-target helpers, and inheritedFacetPolicies replaces inheritedFacetKeys.
• searchSchema rejects an empty target list, a target named twice, joinable on several targets, and two targets declaring one field differently (kind, arity, Roles, or a reference’s strategy/referent). _target becomes a reserved field name.
• Framing depth is the furthest any target reaches.

Index time (@lde/search, @lde/search-pipeline)

• The extraction reads a multi-target referent’s rdf:type and emits every target’s expansion or key hop, each its own UNION branch inside one OPTIONAL, so multi-valued types and keys don’t multiply rows.
• The projection matches it against each target’s class, in declaration order, and treats the referent as a document of that target: re-keyed through its key, admitted to a facet by its policy. A stored (local) referent records the match under _target, so an unidentified referent is still served as the kind it was stated to be. Single-target lookups store exactly what they stored before.

Query time (@lde/search-typesense)

• Labels and projected lookups fetch from every target collection in the same round-trip; an IRI two collections hold belongs to the first declared. Each resolved nested document is marked with its target under a symbol key (NESTED_DOCUMENT_TYPE), never as a field.
• The collection declares the union of the targets’ fields plus the discriminator.

Surface (@lde/search-api-graphql)

• One interface per target set, PersonOrOrganizationReference, implemented by each ‹Target›Reference and carrying id plus every field the targets declare alike (nullable); __typename resolves per referent, and an inline fragment reaches per-type fields.
• A referent no collection holds – dangling, or its lookup failed – is served as PersonOrOrganizationUnresolvedReference with only its id, rather than claimed for the first target.
• The field’s filter is PersonOrOrganizationFilter { in: [IRI!] }; coarse discovery still finds it.

Not in scope

A join predicate on a polymorphic reference (“works whose creator died before 1900”) stays out of reach – an engine reference names one collection – and is tracked in #845.

Records

ADR 28 amends ADR 21, which had rejected both a target list and an output-side interface on convenience grounds; a __typename that is false for half the values is not a convenience problem. The search, search-api-graphql, search-typesense and search-pipeline reference pages describe the mechanism.

BREAKING for schema-level readers only: the renamed helpers above. A declaration naming one target is unchanged in storage and in emitted GraphQL.