feat(search)!: engine- and domain-agnostic query model, Typesense compiler, and GraphQL surface

[ddeboer]

What

Reworks @lde/search and @lde/search-typesense into a unified, engine- and
domain-agnostic search API, and adds @lde/search-api-graphql (the new GraphQL surface).
@lde/search and @lde/search-typesense already existed in the repo; this reworks them
(breaking), it does not introduce them. One declarative search schema drives projection, the
engine collection schema, the query semantics, and the GraphQL surface – so they cannot
drift. The domain type (Dataset, Person, …) and the engine choice (Typesense, …) are the
consumer’s, configured at the seams; the libraries never name a domain.

Terminology

The model has three levels (see the new Terminology section in the @lde/search README):

Term	What it is	SHACL	GraphQL
SearchField	One queryable field: kind, IR path, capability flags	property shape	field
SearchType	One root type’s declaration: type IRI + fields + derivations	NodeShape	object type
SearchSchema	Every SearchType, keyed by type IRI; built with searchSchema(…)	shapes graph	schema

projectGraph consumes a SearchSchema; the engine port and the GraphQL surface operate on
one SearchType at a time.

Review guide

Three tiers by stability; spend review effort accordingly.

1. Stable API Contract (the emitted GraphQL SDL): highest scrutiny. The consumer-facing
surface a Presentation Layer couples to. Its stability is independent of @lde package versions
and is guarded by the printGraphQLSchema SDL snapshot, so this is the one part that must stay
right.

• @lde/search-api-graphql build-schema.ts: output types, where/orderBy/facet inputs,
  named reference types, nullability.

2. @lde library API (0.x, still stabilizing): review the design, not for permanence.
Developer-facing package APIs; pre-1.0 a breaking change is a routine minor bump (our nx
adjustSemverBumpsForZeroMajorVersion), so review for correctness and shape, not as frozen.

• @lde/search engine.ts (SearchEngine port + result types), query.ts (SearchQuery IR /
  filter operators), schema.ts (SearchField/SearchType/SearchSchema model).

3. Internal / swappable: lower scrutiny. Behind the port; changeable without consumer impact
(ADR 0003).

• @lde/search project.ts / frame-by-type.ts; @lde/search-typesense query-compiler.ts /
  collection-schema.ts / search.ts.

The neutral-fixture snapshot tests pin each generator; a snapshot diff flags a generated-shape
change, so start there.

Not in this PR: the consumer (Dataset Register) side, including the hand-written dr:*
CONSTRUCTs, lands in a separate DR PR after these packages publish. Those CONSTRUCTs are
provisional (slated for SHACL-driven replacement) and will be guarded there by a
schema/CONSTRUCT contract test, so none of that review burden is here.

Packages

@lde/search (core) — breaking

• Unifies the field model: one SearchField / SearchType replaces the projection
  FieldSpec/Projection and the discriminated FieldKind.
• Names the whole declaration: SearchSchema is the map of SearchTypes keyed by type IRI,
  built with the new searchSchema() factory; projectGraph(quads, schema) consumes it.
• Adds the neutral query IR (SearchQuery / Filter / Sort) and filter-operator semantics.
• Adds the SearchEngine port and logical result types (SearchResult / SearchHit /
  ResultDocument / Reference / LocalizedValue / FacetBucket).
• Adds physicalFields (the shared physical-fanout convention) and field selectors
  (searchableFields, facetableFields, filterableFields, sortableFields, outputFields).
• Rewrites projectDocument/projectGraph onto the unified model; projection output is
  unchanged — the guardrail test was ported field-for-field.
• BREAKING: FieldSpec, Projection, and the discriminated FieldKind are removed. The
  per-type declaration is SearchType (formerly named SearchSchema).

@lde/search-typesense (engine adapter) — additive

• buildCollectionSchema derives a Typesense collection from the field model (kind→type, the
  physical fanout via physicalFields, per-locale stemming, required / default-sorting-field).
• buildSearchParams compiles SearchQuery into Typesense params — filter_by / sort_by /
  facet_by / query_by with active-locale weighting and exact membership for non-facet
  fields (grouped facets are ordinary denormalized values, not a special clause).
• createTypesenseSearchEngine implements the SearchEngine port end to end: it reconstructs
  logical documents and resolves reference (and reference-facet) labels from the sidecar
  labels collection in a single lookup.
• Covered by unit tests plus a Typesense testcontainer integration test.

@lde/search-api-graphql (GraphQL surface) — new

• buildGraphQLSchema(searchType, { typeName }) builds an executable GraphQLSchema at
  runtime from any SearchType (no codegen, no SDL artifact), served by one generic resolver
  over any SearchEngine.
• Derives output types, where/orderBy/facet inputs, named reference types, and nullability
  (from required / array / kind) from the field model; best-first Accept-Language
  output ordering; a nullable facet label resolved for reference facets only.
• Exports printGraphQLSchema for a consumer-side SDL snapshot guard.

Notes

• ADRs 0003/0004 updated: the unified model and its terminology (SearchType per NodeShape,
  SearchSchema as the type-keyed map), the SearchEngine rename (the interface is the port;
  the Typesense class is the adapter), size → Float (int64 overflow), the typed-surface
  design, and facet labels.
• Root README: the packages table gains the @lde/search-api-graphql row and the architecture
  diagram gains the search family (search, search-typesense, search-api-graphql,
  text-normalization).
• Each generator ships a neutral-fixture snapshot to pin its output across versions.
• Deferred: the idOnly/inline reference strategies, the OutputOf<S> typed-surface
  overlay, and a REST surface.