feat(search): key a root type on a declared field

[ddeboer]

PR 1 of #763 – the write side. The facet policy (facetKeys: { only }, PR 2)
is not in here.

What changes

A Root Type is keyed on the node’s IRI unless it names a key field to
read the key from. A reference to such a type stores the target’s key.

key: {
  field: '_sameAs',
  pick: (candidates) => candidates.find(isGeoNames) ?? candidates.find(isCovered),
}

Non-breaking and opt-in: a schema declaring no key extracts, projects, indexes
and queries exactly as before. @lde/pipeline, @lde/search-indexer and the API
packages are untouched; the selector is unchanged.

@lde/search

• KeyField / RootType.key. field names a declared field of the type: a
  path-bearing, array reference field that is not inline. Naming a declared
  field is the point – its extraction branch already exists, a reader transform
  that repairs reference values covers the candidates, and the field’s own
  transform is where IRI normalisation lives, so two spellings of one IRI
  become one candidate before anything chooses between them.
• documentKeyOf (exported from /adapter) is the whole rule in one
  function – transform, IRI filter, dedupe, sort, pick – so the projection
  and a deployment’s transform read the same answer. Candidates reach pick
  sorted, so the default (the first) is deterministic whatever order the
  CONSTRUCT returned them in; pick must return one of them or undefined, and
  anything else throws naming the node and the candidates.
• rootTypeNamed resolves the type a declaration points at, replacing the
  by-name map assertResolvableLabelSources kept for itself (and the one in
  @lde/search-typesense’s projection lookup).
• Projection. A root is keyed through documentKeyOf; a reference that
  names a keyed target (a lookup’s target, an idOnly’s labelSource)
  stores the referent’s key. A reference naming no target, a derived one, and a
  projection run without a schema are left alone – that is the same line a join
  draws, and for the same reason.
• Validation rejects a key naming an unknown, non-reference, path-less,
  single-valued or inline field, a non-function pick, and a key on a
  Reference Type (typed never, so it also fails to compile).

Also fixes an error message this refactor would otherwise have made misleading:
a lookup naming a declared Reference Type used to complain about a missing
label field and now says the name is unknown – so it names it for what it is
instead, and says why only a Root Type can serve labels.

@lde/search-pipeline

One OPTIONAL hop per reference into a keyed target, reading the referent’s key
field and emitting it under the target’s IR Alias. Inside that reference’s
own UNION branch, so it multiplies against nothing; OPTIONAL, so an unaligned
referent keeps its row and its own IRI instead of dropping out of the CONSTRUCT.
The root side is unchanged.

Consequences worth reading

• Several nodes with one key are one document. That is what a document key
  means; the writer upserts by id. The projection still emits one document per
  distinct root – folding them is the writer’s upsert.
• A transform that replaces a root’s quads must re-emit the key field – the
  existing rule that a field the document needs must be in the stream, applied to
  one more field. Documented on key and in the indexer reference; left a
  convention rather than a guarantee, since the structural alternative touches
  @lde/pipeline’s runner.
• A transform that supplies key candidates must reach every referring type.
  A transform is attached to one type’s reader, and a reference’s key is read in
  the referring type’s extraction query – so candidates minted on the target
  alone key the target’s own document while every reference to it still stores
  the node IRI. Repairing candidates the graph already carries is unaffected.
• The referring field’s own transform runs on the key, not on the
  referent’s node IRI, since a transform transforms what the field stores.
  Pinned by a test so the ordering is deliberate.
• The key is assigned before any derive runs, so a derive sees the key.
• A cross-dataset node reference does not resolve (the hop runs against the
  referring dataset’s distribution). Recorded in the docs and the ADR.

Documentation

ADR 22 Key a root type on a declared field, a “Document key” section in the
@lde/search reference beside labelField, the key hop in the
@lde/search-pipeline extraction section, and the re-emit rule in
@lde/search-indexer’s “Add a transform”.

Follow-ups (not done here)

Per the issue: #754 is no longer a precondition, #760 stays latent, and the
multi-valued provenance stamp (#697 / #709) is worth un-deferring since this
makes shared documents common. Left for you to decide on the tracker.

Part of #763 – deliberately not Fix, so the issue stays open for PR 2.