@lde/search 0.1.2 → 0.3.0

package/README.md

@@ -1,170 +1,308 @@
 # @lde/search
 
-Engine-agnostic search projection for RDF-backed pipelines. **`projectGraph`**
-streams the result of a SPARQL `CONSTRUCT` into flat search documents, with no
-engine and no vocabulary baked in. Internally it does two things per subject of
-a root type: frame its one-hop subgraph into a JSON-LD IR node, then project
-that node into a flat document from a **declarative field spec**.
+The core of the LDE search family: packages that together act as a **generator
+for search engines**. You write one declarative `SearchSchema`, and everything
+a running search engine needs is derived from it: the document projection, the
+engine collection schema, the query semantics, and the API surface. All these
+are kept in sync automatically rather than handwritten per deployment.
 
-An engine adapter (e.g. [`@lde/search-typesense`](../search-typesense)) then
-writes those documents to a search backend.
+The core itself is **engine-, API- and domain-agnostic**: it bakes in no search
+engine, no API protocol, and no domain vocabulary. The engine- and API-specific
+halves are adapters that plug into the ports defined here:
 
-```ts
-import { projectGraph, type Projection } from '@lde/search';
+- **engine adapters** implement the `SearchEngine` port:
+  [`@lde/search-typesense`](../search-typesense), with OpenSearch to follow;
+- **API surfaces** drive it, parsing client input into `search(SearchQuery)`:
+  [`@lde/search-api-graphql`](../search-api-graphql), with a REST
+  surface to follow.
 
-const projection: Projection = {
-  /* type + field spec — see below */
-};
+The library never names your domain: the same core drives a `Dataset`,
+`Person`, or `CreativeWork` search.
 
-for await (const document of projectGraph(quads, [projection])) {
-  // one flat search document per matching subject, streamed
-}
+It provides four things:
+
+- **unified field model** — `SearchField` / `SearchType` / `SearchSchema`:
+  one declaration per field that drives all four consumers below, so they
+  cannot drift;
+- **neutral query IR** — `SearchQuery` / `Filter` / `Sort` + filter
+  semantics: every API surface compiles into it, every engine adapter compiles
+  out of it, so the two cannot drift;
+- **engine port** — `SearchEngine` and the logical result types
+  (`SearchResult` / `SearchHit` / `ResultDocument` / `Reference` / …);
+- **streaming projection** — `projectGraph`, RDF `CONSTRUCT` quads → flat
+  search documents.
+
+```
+SearchSchema ─┬─► projection      (projectGraph → flat documents)        [here]
+              ├─► engine adapter  (collection schema + query compiler)   e.g. @lde/search-typesense
+              ├─► query semantics (SearchQuery, filter/sort/facet)       [here]
+              └─► API surface     (GraphQL / REST)                       e.g. @lde/search-api-graphql
 ```
 
-`projectGraph` is fully streaming: subjects are grouped and framed one at a time
-and documents are yielded as they are produced, so beyond a subject index memory
-stays flat at scale (framing the whole graph at once is roughly O(N²)). Duplicate
-triples are collapsed first, because some SPARQL engines (e.g. QLever) do not
-deduplicate `CONSTRUCT` output. The IR carries no `@context`, so a `derivation`
-reading it sees full predicate IRIs with language tags preserved.
+At runtime, everything those consumers do is a **pure transformation between
+data shapes**, each one parameterised by the schema — three chains, meeting at
+the engine:
 
-## Projection
+```
+indexing:  RDF quads ──frame──► FramedNode ──project──► SearchDocument ──import──► engine
+querying:  client input ──parse──► SearchQuery ──compile──► engine query
+results:   engine response ──parse──► SearchResult ──shape──► API output
+```
+
+Validation happens before the first arrow (SHACL over the RDF) and inside the
+last (the engine enforces its collection schema); between them every stage is
+a typed, deterministic function — easy to test, and swappable per deployment.
+
+## Entry points
+
+Exports are stratified by audience:
+
+- **`@lde/search`** — the authoring surface: `defineSearchType`,
+  `searchSchema`, `projectGraph` (+ the IR readers `derive` functions use),
+  validation, and every model/query/result type.
+- **`@lde/search/adapter`** — plumbing for engine adapters and API surfaces:
+  `physicalFields`, the field selectors, `assertValidQuery`, the filter
+  operators and storage codecs.
+- **`@lde/search/testing`** — `describeSearchEngineContract`, the executable
+  port contract every engine adapter runs against a live instance of itself
+  (vitest; optional peer).
+
+## Terminology
+
+The model has three levels, with analogues in SHACL ([one possible source](#why-a-declarative-model))
+and GraphQL (one of the surfaces):
+
+| Term           | What it is                                                                                                      | SHACL          | GraphQL     |
+| -------------- | --------------------------------------------------------------------------------------------------------------- | -------------- | ----------- |
+| `SearchField`  | One queryable field: a `kind`, the IR `path` it projects from, and the capability flags it opts into            | property shape | field       |
+| `SearchType`   | One root type’s complete declaration: its logical API `name`, its `type` IRI and its fields (incl. derived)     | NodeShape      | object type |
+| `SearchSchema` | The whole search declaration: every `SearchType`, keyed by `type` IRI — build one with `searchSchema(...types)` | shapes graph   | schema      |
+
+`projectGraph` and the GraphQL surface consume a `SearchSchema` (projecting
+every type in one pass); the engine port executes one `SearchType` at a time.
+
+### API conventions
 
-The mapping is data, not code. Each field declares the IR `path` to read and a
-`kind`; the conventions (per-locale split, diacritic folding via
-[`@lde/text-normalization`](../text-normalization), facet arrays, numeric
-coercion) are applied for you. Computed fields are `derivations` — hooks that
-read the node and set fields the kinds can't.
+Two conventions hold across the whole family:
+
+- **Parameter order** — a function takes the value it operates on first and
+  the declaration right after it: `projectDocument(node, type)`,
+  `buildSearchParams(query, type)`,
+  `createTypesenseSearchEngine(client, schema, options)`,
+  `engine.search(type, query)`.
+- **Factory verbs** — the verb tells you what kind of thing comes back.
+  `define*` captures a declaration as a literal (`defineSearchType`);
+  `build*` is a pure data-to-data constructor (`buildCollectionSchema`,
+  `buildSearchParams`, `buildGraphQLSchema`); `create*` makes a stateful
+  instance (`createTypesenseSearchEngine`). A bare noun (`searchSchema`)
+  constructs the trivial container it names.
+
+## Field model
+
+The mapping is data, not code. Each field declares its `kind`, the IR `path` to
+read (or a `derive` function for a **derived** field, computed from the framed
+node in declaration order — so it may read fields declared before it), and the
+capabilities it opts into. The physical field names a declaration fans out to
+(per-locale search/sort keys) come from
+`physicalFields`, the single convention projection, the collection schema and the
+query compiler all share.
 
 ```ts
-import { projectGraph, irisOf, type Projection } from '@lde/search';
+import {
+  defineSearchType,
+  projectGraph,
+  irisOf,
+  searchSchema,
+} from '@lde/search';
 
-const projection: Projection = {
+const DATASET = defineSearchType({
+  name: 'Dataset', // logical API name: names the GraphQL type, a REST path, …
   type: 'http://www.w3.org/ns/dcat#Dataset',
   fields: [
-    // → title_nl, title_en, title_search_nl, title_search_en, title_sort_nl, title_sort_en
+    // → title_nl, title_en, title_search_nl/_en, title_sort_nl/_en
     {
       name: 'title',
       path: 'http://purl.org/dc/terms/title',
-      kind: {
-        type: 'langText',
-        locales: ['nl', 'en'],
-        display: true,
-        search: true,
-        sort: true,
-      },
+      kind: 'text',
+      locales: ['nl', 'en'],
+      output: true,
+      searchable: { weight: 5 },
+      sortable: true,
     },
-    // → publisher (IRI facet)
+    // → publisher (IRI facet, resolved to a labelled reference at the surface)
     {
       name: 'publisher',
       path: 'http://purl.org/dc/terms/publisher',
-      kind: { type: 'facet', iri: true },
+      kind: 'reference',
+      facetable: true,
+      output: true,
+      ref: { typeName: 'Organization', strategy: 'labelOnly' },
     },
     // → size (int)
-    { name: 'size', path: 'urn:dr:size', kind: { type: 'number' } },
-  ],
-  derivations: [
-    (document, node) => {
-      document.class_count = irisOf(node, 'urn:dr:class').length;
+    { name: 'size', path: 'urn:dr:size', kind: 'integer', sortable: true },
+    // derived field (no path): computed from the framed node
+    {
+      name: 'classCount',
+      kind: 'integer',
+      sortable: true,
+      derive: (node) => irisOf(node, 'urn:dr:class').length,
     },
   ],
-};
+});
 
-for await (const document of projectGraph(quads, [projection])) {
-  // …
+for await (const document of projectGraph(quads, searchSchema(DATASET))) {
+  // one flat search document per matching subject, streamed
 }
 ```
 
-**Kinds**
+`defineSearchType` captures the declaration as a literal (what
+`as const satisfies SearchType` would do manually, with nothing to remember),
+so typed facet/output keys can be derived from it — see
+[Typed results](#typed-results) and `@lde/search-api-graphql`.
 
-| kind       | emits                                                                                                                                                    |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `langText` | per locale (see below), each opt-in: `_${locale}` display with `display`, `_search_${locale}` folded with `search`, `_sort_${locale}` folded with `sort` |
-| `facet`    | the field as a deduped array; `iri` reads `@id`; `search` adds a folded `_search`; `transform` rewrites values                                           |
-| `number`   | a numeric scalar; `date` parses an ISO date-time to unix seconds                                                                                         |
+**Kinds** (`FieldKind`): `text`, `keyword`, `integer`, `number`, `boolean`,
+`date`, `reference`. The Typesense/engine vocabulary and the GraphQL types are
+_derived_ from the kind by the adapter and the surface — never declared here.
+
+`SearchField` is a **discriminated union by `kind`** (`TextField`,
+`KeywordField`, `ReferenceField`, `NumericField`, `BooleanField`): each kind
+declares exactly the properties it can honour — `locales` on text, `ref` on
+references, `facetRanges` on numerics — so an illegal declaration fails to
+compile. Text is **always multilingual in shape**: `locales` lists the
+language tags to fan out, and the reserved **`und`** locale (JSON-LD `@none`,
+RDF `und`) buckets untagged literals — a monolingual or untagged corpus
+declares `locales: ['und']`, mixed data `['nl', 'und']`. Declaring a real
+language is recommended (it drives per-locale stemming); `und` is folded but
+unstemmed unless `defaultLocale` opts in, is never demoted in search
+weighting, and adding a language later is additive — the API output shape
+never changes. Use `keyword` for exact-match tokens, never for prose.
+
+**Declarations are also validated at runtime** (for declarations built
+outside TypeScript — a SHACL generator, plain JS): `searchSchema()`
+rejects a structurally invalid declaration (duplicate field names, an `output`
+reference without `ref`, `text` without locales, `locales` on a non-text kind,
+`facetRanges` on a non-numeric kind, `searchable`/`transform` on a kind whose
+projection cannot honour it, `filterable`/`facetable` on `text`, two types
+sharing a `type` IRI or `name`) — the declaration-time counterpart of the
+port’s always-on query validation, so a bad schema fails at startup rather
+than per document at index time. `validateSearchType` /
+`assertValidSearchType` are exported for validating a single declaration
+directly.
+
+| kind                 | `where`              | facet | sort             | output                          |
+| -------------------- | -------------------- | ----- | ---------------- | ------------------------------- |
+| `text`               | – (feeds free text)  | –     | yes (per-locale) | best-first language list        |
+| `keyword`            | `in` (membership)    | yes   | –                | string / `string[]`             |
+| `reference`          | `in` (membership)    | yes   | –                | labelled reference (id + label) |
+| `integer` / `number` | `range { min, max }` | yes   | yes              | number                          |
+| `date`               | `range` (inclusive)  | yes   | yes              | ISO 8601 string (surface)       |
+| `boolean`            | `is`                 | yes   | –                | boolean (absent = false)        |
+
+A `reference` carries `labelOnly` today (id + display label); the `idOnly` and
+`inline` strategies are forward declarations. References are object-shaped from
+day one so that `inline` can later **add** fields to a reference type without
+breaking clients.
+
+## Projection
+
+`projectGraph` is fully streaming: subjects are grouped and framed one at a time
+and documents are yielded as produced, so beyond a subject index memory stays
+flat at scale (framing the whole graph at once is roughly O(N²)). Duplicate
+triples are collapsed first, because some SPARQL engines (e.g. QLever) do not
+deduplicate `CONSTRUCT` output. The IR carries no `@context`, so a `derive` function
+reading it sees full predicate IRIs with language tags preserved.
 
 ## Locales
 
-`locales` is the **single** list of languages a `langText` field projects;
-`display`, `search` and `sort` are independent opt-in families that each fan out
+`locales` is the **single** list of locales a `text` field projects (`und` =
+untagged literals);
+`output`, `searchable` and `sortable` are independent opt-ins that each fan out
 over it (so a field emits exactly what it opts into):
 
-- `display` → `title_nl`/`title_en` (accents preserved);
-- `search` → `title_search_nl`/`title_search_en` (folded; one field per locale
-  lets a query `query_by` them and rank the user’s language higher via
-  `query_by_weights`, and lets a language that needs a dedicated tokenizer set
-  its own `locale` in the schema);
-- `sort` → `title_sort_nl`/`title_sort_en` (folded, so a locale-switching UI
+- `output` → `title_nl`/`title_en` (accents preserved);
+- `searchable` → `title_search_nl`/`title_search_en` (folded; one field per locale
+  lets a query `query_by` them and rank the user’s language higher, and lets a
+  language that needs a dedicated tokenizer set its own stemming `locale` in the
+  engine schema);
+- `sortable` → `title_sort_nl`/`title_sort_en` (folded, so a locale-switching UI
   sorts on the active language).
 
-A field with `search` but no `display` is **search-only** — folded and stemmed
-for retrieval but never rendered (e.g. a `publisher` searched here but shown via
-a separate label).
+A field with `searchable` but no `output` is **search-only** — folded and stemmed
+for retrieval but never rendered (e.g. a creator searched here but shown via a
+separate label). **Only listed locales are indexed**; a literal whose language tag is not in
+`locales` is not projected (declare `und` to catch untagged literals). Per-locale fields are
+**omitted, never empty**, when a document lacks that language, so declare them
+optional in the engine schema and sort with `missing_values: last`.
 
 Folding the search fields is what lets diacritic-insensitive matching and
 stemming coexist. A search engine on its **default** locale typically folds case
-and diacritics for you (Typesense v30, verified, even folds ø/æ/ß) — so there the
-folding here is belt-and-suspenders. But enabling a language’s **stemming**
-requires setting that language’s `locale` (e.g. `locale: 'nl'` + `stem: true` so
-`huizen` matches `huis`), and a non-default locale switches the engine to ICU
-tokenization, which **preserves** diacritics. At that point the engine no longer
-folds them, and `fold()` is what keeps matching diacritic-insensitive. Stemming
-is a per-field engine-schema choice (the consumer’s), and being rules-based it
-can mangle proper nouns and place names — e.g. the Dutch stemmer reduces the city
-`Bergen` to `berg`, colliding it with “mountain”.
-
-Recommended split: enable stemming on the **free-text** search fields
-(`*_search_${locale}`, descriptions, keywords) where morphological recall helps
-(`verhaal` ↔ `verhalen`), and keep **place names and other proper-noun facets on
-a separate, unstemmed field** (facets are exact-match anyway). That captures the
-recall without the `Bergen`/`berg` collision in the facet. A `stem_dictionary`
-can pin specific names if you need stemmed free-text without given collisions.
-
-**Only listed locales are indexed.** A literal whose language tag is not in
-`locales` is not projected at all — no display, no search, no sort field — so it
-is invisible to the index. To index a language, add it to `locales`.
-
-Per-locale fields are **omitted, never empty**, when a document lacks that
-language, so declare them `optional: true` in the engine schema. At query time,
-sort with `missing_values: last` to push documents lacking the active locale to
-the end, and `query_by` all the per-locale search fields (weighting the user’s
-locale higher) to keep cross-language recall.
-
-A literal with no `@language` tag matches no locale, so it is not projected. Tag
-your source literals (or pre-process them) for the languages you index.
+and diacritics for you; enabling a language’s **stemming** switches it to ICU
+tokenization, which **preserves** diacritics — at which point `fold()` (from
+[`@lde/text-normalization`](../text-normalization)) is what keeps matching
+diacritic-insensitive. Stemming is rules-based and can mangle proper nouns (the
+Dutch stemmer reduces the city `Bergen` to `berg`), so enable it on free-text
+fields and keep proper-noun facets on a separate, unstemmed field.
 
 ## Querying
 
 The search fields are stored already case- and diacritic-folded, so **the query
-must be folded the same way** with the same `fold()` from
-[`@lde/text-normalization`](../text-normalization) before it reaches the engine.
-Otherwise index and query are normalized differently and matches silently miss
-(the user sees no results, with no error). An engine on its default locale would
-fold a raw query for you, but one set to a stemming locale (which preserves
-diacritics) or a non-folding backend will not — so always fold, and matching
-stays correct on any engine.
+must be folded the same way** with the same `fold()` before it reaches the engine,
+or index and query normalize differently and matches silently miss. This contract
+holds for **any** consumer, including an API built on this package — which is why
+engine adapters and surfaces compile through the shared `SearchQuery` IR and the
+`physicalFields` convention rather than re-deriving field names.
+
+Queries are **always validated**: the port contract requires every engine
+adapter to reject a structurally invalid `SearchQuery` (`assertValidQuery`) —
+unknown or non-`filterable` fields in `where`, an operator not matching the
+field’s kind, non-`facetable` facet requests — no matter which surface or
+policy produced it. A typed surface like GraphQL makes most of these
+unrepresentable; the port enforces them for everyone else (deployment
+`queryDefaults`, in-process callers, weaker-typed surfaces).
+
+## Typed results
+
+An engine is **bound to the whole `SearchSchema` at construction** — like
+every other schema consumer (`projectGraph(quads, schema)`,
+`buildGraphQLSchema(schema)`): the adapter factory takes the deployment’s
+declaration together with each type’s physical location, so a query can never
+meet the wrong index, and deployment-level concerns (the label cache,
+cross-type search, facet batching) have one home. A search names its type per
+call. Because `searchSchema()` captures the declared types as a literal
+tuple, `search()` accepts **only the deployment’s own types** (a foreign type
+is a compile error) and returns facet/document keys typed by the type passed
+— no caller-side generics:
 
 ```ts
-import { fold } from '@lde/text-normalization';
-
-await client
-  .collections(collection)
-  .documents()
-  .search({
-    q: fold(userQuery),
-    query_by: 'title_search_nl,title_search_en',
-    query_by_weights: '2,1', // rank the user’s locale higher
-  });
+const engine = createTypesenseSearchEngine(client, schema, {
+  collections: { Dataset: 'datasets', Person: 'people' }, // omitting one = type error
+});
+
+const result = await engine.search(DATASET, query);
+result.facets.publisher; // typed: only DATASET’s facetable fields are keys
+result.facets.publsher; // compile error (typo)
+result.hits[0].document.title; // typed: only DATASET’s output fields are keys
+await engine.search(OTHER_TYPE, query); // compile error: not in this schema
 ```
 
-This contract holds for **any** consumer, including a search API built on top of
-this package: index-time and query-time folding must use the same `fold()`, or
-non-decomposing terms silently miss.
+`searchFacets(type, queries)` is the port’s **batch entry point**: several
+facet-only queries – e.g. a faceted sidebar’s skip-own-filter variants –
+answered in one engine round-trip (Typesense: a single `multi_search`), one
+outcome per query, positionally aligned – its facet map, or an in-place error,
+so one failed query never discards its siblings’ facets. The same schema
+binding, per-query validation and typed facet keys apply to every query in
+the batch.
+
+This only works when the types were declared with `defineSearchType` (or
+captured `as const satisfies SearchType`) and composed with `searchSchema()`;
+a plain `: SearchSchema` annotation widens gracefully to string keys.
+`FacetFieldsOf`/`OutputFieldsOf` are exported for annotating your own
+signatures, and `engine.schema` exposes the bound declaration for routing.
 
-## Why a spec
+## Why a declarative model
 
-The field spec's vocabulary mirrors SHACL on purpose: `path` is `sh:path`, and
-the kind is derivable from `sh:datatype` / `sh:nodeKind` / `sh:maxCount` plus
-search annotations. So the same projection engine that runs a hand-written spec
-today will run a **SHACL-generated** spec tomorrow — the engine and the IR stay;
-only spec-authoring gets automated. Nothing is thrown away.
+The vocabulary mirrors SHACL on purpose: `path` is `sh:path`, `array` is
+`sh:maxCount`, `required` is `sh:minCount`, `locales` is `sh:languageIn`, `ref`
+is `sh:class`/`sh:node`. So the same core that runs a hand-written `SearchSchema`
+today will run a **SHACL-generated** one tomorrow — the model, the ports and the
+IR stay; only schema-authoring gets automated.

package/dist/adapter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The adapter-author surface of `@lde/search` (import from
+ * `@lde/search/adapter`): the plumbing an engine adapter or API surface needs
+ * to compile queries and reconstruct results — field selectors, the physical
+ * field-name convention, query validation and the storage codecs. A
+ * deployment author declaring a schema and running searches needs none of
+ * this; the main entry point carries that (small) authoring surface.
+ */
+export { assertTypeInSchema, physicalFields, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export type { PhysicalFields } from './schema.js';
+export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';
+export type { FilterOperator, QueryIssue } from './query.js';
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/adapter.js

@@ -0,0 +1,10 @@
+/**
+ * The adapter-author surface of `@lde/search` (import from
+ * `@lde/search/adapter`): the plumbing an engine adapter or API surface needs
+ * to compile queries and reconstruct results — field selectors, the physical
+ * field-name convention, query validation and the storage codecs. A
+ * deployment author declaring a schema and running searches needs none of
+ * this; the main entry point carries that (small) authoring surface.
+ */
+export { assertTypeInSchema, physicalFields, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';

package/dist/engine.d.ts

@@ -0,0 +1,154 @@
+import type { SearchQuery } from './query.js';
+import type { SearchSchema, SearchType } from './schema.js';
+/**
+ * The engine port: the boundary a concrete engine adapter (e.g. the engine
+ * `@lde/search-typesense`’s `createTypesenseSearchEngine` returns) implements.
+ * An engine is **bound to the whole {@link SearchSchema} at construction** —
+ * the adapter factory takes the deployment’s declaration together with the
+ * physical location of every type (its collections map), mirroring the other
+ * schema consumers (`projectGraph(quads, schema)`,
+ * `buildGraphQLSchema(schema)`): everything is a function of the schema. A
+ * query can never meet the wrong index, deployment-level concerns (label
+ * cache, cross-type search, facet batching) have one home, and a search names
+ * its type per call.
+ * The adapter owns every engine specific (companion-field expansion,
+ * full-text field selection and weights, filter compilation, sorting, result
+ * folding, faceting) and returns only logical documents, so a deployment can
+ * swap engines without any consumer noticing. Nothing engine-specific and
+ * nothing RDF-specific leaks past this port.
+ *
+ * Port contract: an adapter ALWAYS rejects a `searchType` that is not in its
+ * bound schema, and ALWAYS validates the incoming query against it
+ * (`assertValidQuery`) — unknown or non-filterable fields, mismatched
+ * operators, unknown facets — rather than passing garbage to its engine.
+ * Validation is not the caller’s job: it must hold for every surface and for
+ * injected deployment policy.
+ *
+ * `Types` is the literal tuple {@link searchSchema} captured: with a
+ * `defineSearchType` declaration, `search()` only accepts the deployment’s
+ * own types (a foreign type is a compile error) and returns facet/document
+ * keys typed by the type passed. A widened `: SearchSchema` degrades
+ * gracefully to string keys ({@link FacetFieldsOf}).
+ */
+export interface SearchEngine<Types extends readonly SearchType[] = readonly SearchType[]> {
+    /** The declaration this engine serves — exposed so a surface can route and
+     *  a caller can enumerate the searchable types. */
+    readonly schema: SearchSchema<Types>;
+    search<T extends Types[number]>(searchType: T, query: SearchQuery): Promise<SearchResult<FacetFieldsOf<T>, OutputFieldsOf<T>>>;
+    /**
+     * The batch entry point: answer several facet-only queries against one type
+     * in a single engine round-trip (where the engine supports one, e.g.
+     * Typesense `multi_search`), returning one {@link FacetsOutcome} per query,
+     * positionally aligned with `queries`. This is what keeps a faceted
+     * sidebar – one skip-own-filter query variant per filtered facet – from
+     * fanning out into per-facet engine calls. Only facet buckets come back: an
+     * engine answers every query in the batch facet-only (as if `limit: 0` and
+     * without ordering, whatever the query carries), so hits are never
+     * transferred. Reference-facet buckets carry resolved labels exactly as in
+     * {@link search}. A failure of one query is reported in place
+     * (`{ error }`) rather than by rejecting, so it never discards its
+     * siblings’ facets; the returned promise rejects only for batch-level
+     * failures (a foreign `searchType`, a structurally invalid query, the
+     * transport itself). The port contract holds for every query in the batch;
+     * an empty `queries` resolves to `[]` without touching the engine.
+     */
+    searchFacets<T extends Types[number]>(searchType: T, queries: readonly SearchQuery[]): Promise<readonly FacetsOutcome<FacetFieldsOf<T>>[]>;
+}
+/**
+ * One query’s outcome in a {@link SearchEngine.searchFacets} batch – its
+ * facet buckets, or the error that failed it. The `allSettled`-style shape
+ * keeps one failed query (e.g. one failed `multi_search` entry) from
+ * discarding its siblings’ results: a caller degrades exactly the facets of
+ * the failed query. Discriminate with `'error' in outcome`.
+ */
+export type FacetsOutcome<FacetField extends string = string> = {
+    readonly facets: FacetMap<FacetField>;
+} | {
+    readonly error: unknown;
+};
+/** What an engine returns: logical hits, a total, and the requested facets. */
+export interface SearchResult<FacetField extends string = string, OutputField extends string = string> {
+    readonly hits: readonly SearchHit<OutputField>[];
+    readonly total: number;
+    readonly facets: FacetMap<FacetField>;
+}
+/**
+ * Facet buckets keyed by facet field name. `Partial` because a result carries
+ * buckets only for the fields the query asked for, not every facetable field.
+ */
+export type FacetMap<FacetField extends string = string> = Readonly<Partial<Record<FacetField, readonly FacetBucket[]>>>;
+/**
+ * The facet-field-name union of a search type — the keys a {@link SearchResult}’s
+ * `facets` can hold. Narrow for a declaration captured as a literal (via
+ * `defineSearchType` or `as const satisfies SearchType`); a plain
+ * `: SearchType` annotation degrades to `string` (its field names are not
+ * statically known).
+ */
+export type FacetFieldsOf<Type extends SearchType> = SearchType extends Type ? string : Extract<Type['fields'][number], {
+    readonly facetable: true;
+}>['name'];
+/**
+ * The output-field-name union of a search type — the keys a {@link ResultDocument}
+ * can hold. Like {@link FacetFieldsOf}, degrades to `string` for a widened
+ * declaration.
+ */
+export type OutputFieldsOf<Type extends SearchType> = SearchType extends Type ? string : Extract<Type['fields'][number], {
+    readonly output: true;
+}>['name'];
+/**
+ * One result row. `id` (the stable document key, an IRI) is kept *out* of
+ * {@link ResultDocument}: it is always present and is the hit’s identity, a
+ * different contract from the optional, typed logical field values — and it maps
+ * straight onto the GraphQL output’s guaranteed `id: String!`. The document
+ * holds only the selectable fields.
+ */
+export interface SearchHit<OutputField extends string = string> {
+    readonly id: string;
+    readonly document: ResultDocument<OutputField>;
+}
+/**
+ * The logical result document at the query seam — engine- and RDF-neutral.
+ * Distinct from the flat, fanned-out projection `SearchDocument` that lives
+ * index-side: this carries logical fields with language maps and references,
+ * ready for a surface to shape. Keyed by output field name; `Partial` because a
+ * document omits absent optional fields. `OutputField` defaults to `string`; a
+ * deployment narrows it via {@link OutputFieldsOf} for typo-safe field access.
+ */
+export type ResultDocument<OutputField extends string = string> = Readonly<Partial<Record<OutputField, SearchValue>>>;
+/** A logical field value. */
+export type SearchValue = string | number | boolean | readonly string[] | LocalizedValue | Reference | readonly Reference[];
+/**
+ * A JSON-LD-style language map (`@container: @language`, `@set` arrays); the key
+ * `und` carries untagged (`@none`) values. The surface flattens it to a
+ * best-first `Accept-Language`-ordered list.
+ */
+export type LocalizedValue = Readonly<Record<string, readonly string[]>>;
+/**
+ * The generic internal carrier for a referenced entity. The GraphQL surface maps
+ * it to a named per-shape type (e.g. `Organization`, `Term`) with `label`
+ * exposed as `name`.
+ */
+export interface Reference {
+    readonly id: string;
+    readonly label?: LocalizedValue;
+}
+/**
+ * One facet bucket: a value and how many documents carry it. `label` is the
+ * engine-resolved canonical **data** label, present only for reference facets
+ * (IRI-keyed); it is absent for facets whose value is a token or free string
+ * whose display the consumer owns (its own i18n, or the value itself).
+ */
+export interface FacetBucket {
+    readonly value: string;
+    readonly count: number;
+    readonly label?: LocalizedValue;
+    /**
+     * For a range-facet bucket: its half-open bounds (`min` inclusive, `max`
+     * exclusive), echoing the declared {@link FacetRange} so the bucket is
+     * self-describing and a consumer never hardcodes the bin formula. Both absent
+     * for a value facet; either absent for an open-ended bin.
+     */
+    readonly min?: number;
+    readonly max?: number;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engine.js

@@ -0,0 +1 @@
+export {};