@lde/search 0.1.1 → 0.2.0

package/dist/project.d.ts

@@ -1,98 +1,26 @@
 import type { Quad } from '@rdfjs/types';
 import { type FramedNode } from './frame-by-type.js';
+import { type SearchSchema, type SearchType } from './schema.js';
 /** A flat search document. `id` is the engine document key. */
 export type SearchDocument = {
     id: string;
 } & Record<string, unknown>;
-/**
- * How one framed-IR property projects into search fields. The vocabulary mirrors
- * SHACL so a generator can later emit it from shapes + search annotations:
- * `path` is `sh:path`, and the kind is derivable from `sh:datatype`/`sh:nodeKind`
- * /`sh:maxCount` plus the search annotations.
- */
-export type FieldKind = LangTextKind | FacetKind | NumberKind | DateKind;
-/**
- * Language-tagged text, projected per locale. `locales` is the single source of
- * truth for which languages this field emits; `display`, `search` and `sort` are
- * three independent opt-in families that each fan out over it:
- * - `display` → `${name}_${locale}` display label, accents preserved;
- * - `search` → `${name}_search_${locale}` folded match field (one per locale so
- *   the engine can tokenize/stem each language and the query can rank the user’s
- *   locale higher);
- * - `sort` → `${name}_sort_${locale}` folded sort key (one per locale so a
- *   locale-switching UI sorts on the active language).
- *
- * All three default off — a field emits exactly the families it opts into (e.g.
- * `search` alone is a search-only field, shown via a separate label). Only listed
- * locales are projected: a value whose language tag is not in `locales` (and is
- * not mapped in by `untaggedLanguage`) is not indexed at all.
- */
-export interface LangTextKind {
-    readonly type: 'langText';
-    /** The languages to project; drives whichever of the families are enabled. */
-    readonly locales: readonly string[];
-    /** Emit the per-locale display labels `${name}_${locale}` (accents preserved). */
-    readonly display?: boolean;
-    /** Emit a folded `${name}_search_${locale}` per locale (matchable). */
-    readonly search?: boolean;
-    /** Emit a folded `${name}_sort_${locale}` per locale (sortable). */
-    readonly sort?: boolean;
-}
-/** A faceted multi-value field, optionally also folded for search. */
-export interface FacetKind {
-    readonly type: 'facet';
-    /** Read IRI references (`@id`) rather than literal values. */
-    readonly iri?: boolean;
-    /** Also emit a folded `${name}_search` array. */
-    readonly search?: boolean;
-    /** Transform each value before faceting (e.g. strip a media-type prefix). */
-    readonly transform?: (value: string) => string;
-}
-/** A numeric scalar. */
-export interface NumberKind {
-    readonly type: 'number';
-}
-/** An ISO date-time, parsed into Unix seconds. */
-export interface DateKind {
-    readonly type: 'date';
-}
-/**
- * One field of a projection: an output `name`, the framed-IR predicate `path` to
- * read (the SHACL `sh:path`), and the kind-specific config discriminated by
- * `type`.
- */
-export type FieldSpec = {
-    /** Output field base name; per-kind suffixes are appended. */
-    readonly name: string;
-    /** Framed-IR predicate IRI to read (the SHACL `sh:path`). */
-    readonly path: string;
-} & FieldKind;
-/** A computed field that is not a direct projection of a single path
- *  (e.g. a status rank, or a group derived from a code table). */
-export type Derivation = (document: SearchDocument, node: FramedNode) => void;
-/**
- * One root type’s complete projection — the runtime form of a single SHACL
- * NodeShape: `type` is its `sh:targetClass` (and the framed node’s `@type`),
- * `fields` are its property shapes, and `derivations` are its `sh:rule`-shaped
- * computed fields. A generator emits one of these per NodeShape.
- */
-export interface Projection {
-    readonly type: string;
-    readonly fields: readonly FieldSpec[];
-    readonly derivations?: readonly Derivation[];
-}
 /**
  * Project one framed JSON-LD node into a flat search document: apply each field
- * spec, then run the derivations (which may read fields the specs already set).
+ * of the type in declaration order. A field with a `derive` function computes
+ * its value from the node and the document as populated so far (so a derived
+ * field may read fields declared before it). The physical field names a field
+ * fans out to come from {@link physicalFields}, the single source shared with
+ * the engine collection schema and the query compiler.
  */
-export declare function projectDocument(node: FramedNode, projection: Projection): SearchDocument;
+export declare function projectDocument(node: FramedNode, searchType: SearchType): SearchDocument;
 /**
- * Frame `quads` for every projection’s root type and project each node with its
- * type’s projection — the multi-shape pipeline. Streams one document at a time
- * so memory stays flat. The IR maps to a projection by type, so adding a shape
- * is adding a `Projection` (no engine change).
+ * Frame `quads` for every root type in the schema and project each node with its
+ * type’s declaration — the multi-shape pipeline. Streams one document at a time
+ * so memory stays flat. The IR maps to a declaration by type, so adding a shape
+ * is adding a `SearchType` to the schema (no engine change).
  */
-export declare function projectGraph(quads: readonly Quad[], projections: readonly Projection[]): AsyncIterable<SearchDocument>;
+export declare function projectGraph(quads: readonly Quad[], schema: SearchSchema): AsyncIterable<SearchDocument>;
 export declare function literalsOf(node: FramedNode, path: string): string[];
 export declare function firstLiteralOf(node: FramedNode, path: string): string | undefined;
 export declare function irisOf(node: FramedNode, path: string): string[];

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAElE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAChD;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GAAG,SAAS,CAAC;AAEd;kEACkE;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAehB;AAED;;;;;GAKG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC,aAAa,CAAC,cAAc,CAAC,CAS/B;AA+FD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAInE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAYhB;AAED;;;;;GAKG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,EAAE,YAAY,GACnB,aAAa,CAAC,cAAc,CAAC,CAM/B;AAsID,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAInE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}

package/dist/project.js

@@ -1,81 +1,122 @@
 import { fold } from '@lde/text-normalization';
 import { frameByType } from './frame-by-type.js';
+import { isoToUnixSeconds, physicalFields, } from './schema.js';
 /**
  * Project one framed JSON-LD node into a flat search document: apply each field
- * spec, then run the derivations (which may read fields the specs already set).
+ * of the type in declaration order. A field with a `derive` function computes
+ * its value from the node and the document as populated so far (so a derived
+ * field may read fields declared before it). The physical field names a field
+ * fans out to come from {@link physicalFields}, the single source shared with
+ * the engine collection schema and the query compiler.
  */
-export function projectDocument(node, projection) {
+export function projectDocument(node, searchType) {
     const id = node['@id'];
     if (typeof id !== 'string') {
-        throw new Error(`Cannot project a ${projection.type} node without an @id: every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
+        throw new Error(`Cannot project a ${searchType.type} node without an @id: every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
     }
     const document = { id };
-    for (const field of projection.fields) {
+    for (const field of searchType.fields) {
         applyField(document, node, field);
     }
-    for (const derive of projection.derivations ?? []) {
-        derive(document, node);
-    }
     return document;
 }
 /**
- * Frame `quads` for every projection’s root type and project each node with its
- * type’s projection — the multi-shape pipeline. Streams one document at a time
- * so memory stays flat. The IR maps to a projection by type, so adding a shape
- * is adding a `Projection` (no engine change).
+ * Frame `quads` for every root type in the schema and project each node with its
+ * type’s declaration — the multi-shape pipeline. Streams one document at a time
+ * so memory stays flat. The IR maps to a declaration by type, so adding a shape
+ * is adding a `SearchType` to the schema (no engine change).
  */
-export async function* projectGraph(quads, projections) {
-    const byType = new Map(projections.map((projection) => [projection.type, projection]));
-    for (const projection of byType.values()) {
-        for await (const node of frameByType(quads, projection.type)) {
-            yield projectDocument(node, projection);
+export async function* projectGraph(quads, schema) {
+    for (const searchType of schema.values()) {
+        for await (const node of frameByType(quads, searchType.type)) {
+            yield projectDocument(node, searchType);
         }
     }
 }
 function applyField(document, node, field) {
-    switch (field.type) {
-        case 'langText':
-            return applyLangText(document, langValuesOf(node, field.path), field);
-        case 'facet':
-            return applyFacet(document, node, field);
+    if (field.derive !== undefined) {
+        const value = field.derive(node, document);
+        if (value !== undefined) {
+            document[field.name] = value;
+        }
+        return;
+    }
+    const path = field.path;
+    if (path === undefined) {
+        // Neither path nor derive: populated outside the projection, if at all.
+        return;
+    }
+    switch (field.kind) {
+        case 'text':
+            return applyText(document, langValuesOf(node, path), field);
+        case 'keyword':
+            return applyFacet(document, literalsOf(node, path), field);
+        case 'reference':
+            return applyFacet(document, irisOf(node, path), field);
+        case 'integer':
+            return setNumber(document, field.name, toInteger(firstLiteralOf(node, path)));
         case 'number':
-            return setNumber(document, field.name, toInteger(firstLiteralOf(node, field.path)));
-        case 'date':
-            return setNumber(document, field.name, isoToUnix(firstLiteralOf(node, field.path)));
+            return setNumber(document, field.name, toNumber(firstLiteralOf(node, path)));
+        case 'date': {
+            const literal = firstLiteralOf(node, path);
+            return setNumber(document, field.name, literal === undefined ? undefined : isoToUnixSeconds(literal));
+        }
+        case 'boolean': {
+            // The xsd:boolean lexical space: true/false/1/0.
+            const literal = firstLiteralOf(node, path);
+            if (literal !== undefined) {
+                document[field.name] = literal === 'true' || literal === '1';
+            }
+            return;
+        }
     }
 }
-function applyLangText(document, values, { name, locales, display, search, sort }) {
-    if (locales.length === 0) {
-        throw new Error(`langText field “${name}” must declare at least one locale; nothing would be projected otherwise.`);
-    }
-    for (const locale of locales) {
+/**
+ * Project a text field per locale (untagged literals land in the `und`
+ * locale). Display shows one label (accents preserved) when the field is
+ * `output`; sort keys off that same primary value (folded) when `sortable`;
+ * search folds every value of the locale when `searchable`, so all are
+ * matchable. Absent locales emit nothing.
+ */
+function applyText(document, values, field) {
+    // Empty `locales` is rejected at declaration time (`validateSearchType`);
+    // here it simply projects nothing.
+    const locales = field.locales;
+    const names = physicalFields(field);
+    locales.forEach((locale, index) => {
         const localeValues = values
             .filter((value) => value.lang === locale)
             .map((value) => value.value);
         if (localeValues.length === 0) {
-            continue;
+            return;
         }
-        // Display shows one label (accents preserved); sort keys off that same
-        // primary value (folded); search folds every value of the locale so all
-        // are matchable. Absent locales emit nothing (the field stays optional).
         const [primary] = localeValues;
-        if (display) {
-            setString(document, `${name}_${locale}`, primary);
+        if (field.output) {
+            setString(document, names.display[index], primary);
         }
-        if (search) {
-            setString(document, `${name}_search_${locale}`, fold(localeValues.join(' ')).trim());
+        if (field.searchable) {
+            setString(document, names.search[index], foldedSearchValue(localeValues));
         }
-        if (sort) {
-            setString(document, `${name}_sort_${locale}`, fold(primary));
+        if (field.sortable) {
+            setString(document, names.sort[index], fold(primary));
         }
-    }
+    });
+}
+/** The projection’s definition of a folded free-text search value. */
+function foldedSearchValue(values) {
+    return fold(values.join(' ')).trim();
 }
-function applyFacet(document, node, { name, path, iri, search, transform }) {
-    const raw = iri ? irisOf(node, path) : literalsOf(node, path);
-    const values = dedupe(transform ? raw.map(transform) : raw);
-    setArray(document, name, values);
-    if (search) {
-        setArray(document, `${name}_search`, dedupe(values.map((value) => fold(value))));
+/**
+ * Project a faceted multi-value field: dedupe (after the optional transform),
+ * write the value field, and — when `searchable` — a folded `${name}_search`
+ * array. `keyword` reads literals; `reference` reads IRIs (the caller passes the
+ * already-read raw values).
+ */
+function applyFacet(document, raw, field) {
+    const values = dedupe(field.transform ? raw.map(field.transform) : raw);
+    setArray(document, field.name, values);
+    if (field.searchable) {
+        setArray(document, physicalFields(field).search[0], dedupe(values.map((value) => fold(value))));
     }
 }
 function langValuesOf(node, path) {
@@ -108,9 +149,10 @@ function toLangValue(value) {
     if (literal === undefined) {
         return undefined;
     }
+    // Untagged literals (JSON-LD @none) land in the reserved `und` locale.
     const lang = isObject(value) && typeof value['@language'] === 'string'
         ? value['@language']
-        : '';
+        : 'und';
     return { value: literal, lang };
 }
 function literalString(value) {
@@ -140,12 +182,8 @@ function iriString(value) {
 function toInteger(literal) {
     return literal === undefined ? undefined : Math.trunc(Number(literal));
 }
-function isoToUnix(iso) {
-    if (iso === undefined) {
-        return undefined;
-    }
-    const millis = new Date(iso).getTime();
-    return Number.isNaN(millis) ? undefined : Math.trunc(millis / 1000);
+function toNumber(literal) {
+    return literal === undefined ? undefined : Number(literal);
 }
 function setNumber(document, field, value) {
     if (value !== undefined && !Number.isNaN(value)) {

package/dist/query.d.ts

@@ -0,0 +1,87 @@
+import { type SearchType } from './schema.js';
+/**
+ * The engine- and protocol-neutral query IR. Every API surface compiles its
+ * input into this; every engine adapter compiles it into an engine query. One
+ * shared representation in the middle keeps the GraphQL surface, a later REST
+ * surface and the adapter from drifting.
+ */
+export interface SearchQuery {
+    /** Free-text query; `undefined`/`''` means browse (no text ranking). */
+    readonly text?: string;
+    /** AND across fields. */
+    readonly where: readonly Filter[];
+    /** Primary public sort plus any server tie-breaks, in precedence order. */
+    readonly orderBy: readonly Sort[];
+    /** Numbered pagination. */
+    readonly limit: number;
+    readonly offset: number;
+    /** Logical field names to return facet buckets for. */
+    readonly facets: readonly string[];
+    /** Selects the per-locale fields to query/sort on (from `Accept-Language`). */
+    readonly locale: string;
+}
+/**
+ * One `where` clause. The operator is fixed by the target field’s {@link FieldKind}
+ * ({@link filterOperatorFor}): keyword/reference use `in` (OR within the field),
+ * the numeric/date kinds use an inclusive `range`, boolean uses `is`. Bounds are
+ * inclusive only — no `gt`/`gte`/`lt`/`lte`.
+ */
+export type Filter = {
+    readonly field: string;
+    readonly in: readonly string[];
+} | {
+    readonly field: string;
+    readonly range: {
+        readonly min?: number | string;
+        readonly max?: number | string;
+    };
+} | {
+    readonly field: string;
+    readonly is: boolean;
+};
+/** A single sort dimension. */
+export interface Sort {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+export { filterOperatorFor } from './schema.js';
+export type { FilterOperator } from './schema.js';
+import type { FilterOperator } from './schema.js';
+/** The operator a {@link Filter} value carries, from its discriminating key. */
+export declare function filterOperator(filter: Filter): FilterOperator;
+/**
+ * One structural problem {@link validateQuery} found: the query references a
+ * field the search type does not declare, or uses it in a role it does not
+ * opt into. Vacuous-but-valid clauses (an empty `in` list, a `range` with no
+ * bound) are NOT issues — a compiler skips those as no-ops.
+ */
+export interface QueryIssue {
+    readonly part: 'where' | 'facets' | 'orderBy';
+    readonly field: string;
+    readonly reason: 'unknown-field' | 'not-filterable' | 'operator-mismatch' | 'not-facetable';
+}
+/**
+ * Structurally validate a query against its search type: every `where` clause
+ * targets a declared, `filterable` field with the operator its kind accepts
+ * ({@link filterOperatorFor}); every requested facet is a declared, `facetable`
+ * field; every sort is `relevance` or a declared field. Sorting deliberately
+ * checks declaration only, not the `sortable` flag: that flag means *publicly
+ * selectable*, and a deployment policy may sort on a private tie-break field.
+ *
+ * This is the port’s always-on guard: every {@link SearchEngine} adapter MUST
+ * reject a query with issues ({@link assertValidQuery}) instead of passing
+ * garbage to its engine, so validation holds for every caller — including
+ * `queryDefaults` policies and surfaces weaker than GraphQL.
+ */
+export declare function validateQuery(query: SearchQuery, searchType: SearchType): readonly QueryIssue[];
+/** Throw on the first structurally invalid query part ({@link validateQuery}),
+ *  naming every issue. The always-on entry point for engine adapters. */
+export declare function assertValidQuery(query: SearchQuery, searchType: SearchType): void;
+/**
+ * The 1-based page an `offset` falls on — the numbered-pagination presentation
+ * of the IR, shared by the surfaces and the adapters. `limit: 0` (a facet-only
+ * query) fetches no hits and has no meaningful page, so it pins to 1 rather
+ * than dividing by zero.
+ */
+export declare function pageForOffset(offset: number, limit: number): number;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAClC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1D;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAChC,CAAC;CACH,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD,+BAA+B;AAC/B,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CACpC;AAKD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAE7D;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EACX,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,eAAe,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,GACrB,SAAS,UAAU,EAAE,CA6CvB;AAED;yEACyE;AACzE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,GACrB,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/query.js

@@ -0,0 +1,89 @@
+import { fieldNamed, filterOperatorFor } from './schema.js';
+// The kind→operator table lives with the field model in schema.ts (one source
+// for the query IR, the surfaces, the adapters AND declaration validation);
+// re-exported here so the query-IR module stays the natural import site.
+export { filterOperatorFor } from './schema.js';
+/** The operator a {@link Filter} value carries, from its discriminating key. */
+export function filterOperator(filter) {
+    return 'in' in filter ? 'in' : 'range' in filter ? 'range' : 'is';
+}
+/**
+ * Structurally validate a query against its search type: every `where` clause
+ * targets a declared, `filterable` field with the operator its kind accepts
+ * ({@link filterOperatorFor}); every requested facet is a declared, `facetable`
+ * field; every sort is `relevance` or a declared field. Sorting deliberately
+ * checks declaration only, not the `sortable` flag: that flag means *publicly
+ * selectable*, and a deployment policy may sort on a private tie-break field.
+ *
+ * This is the port’s always-on guard: every {@link SearchEngine} adapter MUST
+ * reject a query with issues ({@link assertValidQuery}) instead of passing
+ * garbage to its engine, so validation holds for every caller — including
+ * `queryDefaults` policies and surfaces weaker than GraphQL.
+ */
+export function validateQuery(query, searchType) {
+    const issues = [];
+    for (const filter of query.where) {
+        const field = fieldNamed(searchType, filter.field);
+        if (field === undefined) {
+            issues.push({
+                part: 'where',
+                field: filter.field,
+                reason: 'unknown-field',
+            });
+        }
+        else if (field.filterable !== true) {
+            issues.push({
+                part: 'where',
+                field: filter.field,
+                reason: 'not-filterable',
+            });
+        }
+        else if (filterOperatorFor(field.kind) !== filterOperator(filter)) {
+            issues.push({
+                part: 'where',
+                field: filter.field,
+                reason: 'operator-mismatch',
+            });
+        }
+    }
+    for (const name of query.facets) {
+        const field = fieldNamed(searchType, name);
+        if (field === undefined) {
+            issues.push({ part: 'facets', field: name, reason: 'unknown-field' });
+        }
+        else if (field.facetable !== true) {
+            issues.push({ part: 'facets', field: name, reason: 'not-facetable' });
+        }
+    }
+    for (const sort of query.orderBy) {
+        if (sort.field !== 'relevance' &&
+            fieldNamed(searchType, sort.field) === undefined) {
+            issues.push({
+                part: 'orderBy',
+                field: sort.field,
+                reason: 'unknown-field',
+            });
+        }
+    }
+    return issues;
+}
+/** Throw on the first structurally invalid query part ({@link validateQuery}),
+ *  naming every issue. The always-on entry point for engine adapters. */
+export function assertValidQuery(query, searchType) {
+    const issues = validateQuery(query, searchType);
+    if (issues.length > 0) {
+        const detail = issues
+            .map((issue) => `${issue.part}: “${issue.field}” (${issue.reason})`)
+            .join(', ');
+        throw new Error(`Invalid search query for “${searchType.name}”: ${detail}.`);
+    }
+}
+/**
+ * The 1-based page an `offset` falls on — the numbered-pagination presentation
+ * of the IR, shared by the surfaces and the adapters. `limit: 0` (a facet-only
+ * query) fetches no hits and has no meaningful page, so it pins to 1 rather
+ * than dividing by zero.
+ */
+export function pageForOffset(offset, limit) {
+    return limit > 0 ? Math.floor(offset / limit) + 1 : 1;
+}