@lde/search-typesense 0.27.2 → 0.27.4

package/dist/collection-definition.d.ts

@@ -21,11 +21,19 @@ export interface CollectionDefinitionOptions {
     /**
      * The Search Schema the type belongs to – required when the type surfaces an
      * inline reference (whose nested fields are declared from the
-     * {@link ReferenceType} the schema resolves) or declares a joinable
+     * {@link ReferenceType} the schema resolves), declares a joinable
      * reference (whose target collection the schema’s {@link joinGraph}
      * resolves). A type doing neither needs no schema, so a caller passes none;
      * a type that does fails here rather than building a collection that
      * silently omits the nesting or the reference.
+     *
+     * Also what resolves the facet policy a facetable reference inherits from
+     * the type it names ({@link physicalFields}): without the schema the field
+     * itself is declared the facet and no `${name}_facet` companion is, the same
+     * reading the projection makes without one. Whether a policy applies cannot
+     * be told without the schema, so this is not guarded: a deployment that
+     * declares one and builds its collections schema-less meets the engine’s own
+     * error on the first facet query, not a silently narrowed-to-nothing facet.
      */
     readonly schema?: SearchSchema;
     /** Snowball stemming locale for non-localized searchable fields (e.g. `en`).

package/dist/collection-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection-definition.d.ts","sourceRoot":"","sources":["../src/collection-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAarB,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;IAChE;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;4BAGwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CA2BxB"}
+{"version":3,"file":"collection-definition.d.ts","sourceRoot":"","sources":["../src/collection-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAarB,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;IAChE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;4BAGwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CA2BxB"}

package/dist/collection-definition.js

@@ -138,7 +138,7 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
     if (nested !== undefined) {
         return nestedFields(field.name, field, nested, schema);
     }
-    const names = physicalFields(field);
+    const names = physicalFields(field, schema);
     if (field.kind === 'text') {
         const locales = field.locales;
         const displayPattern = displayFieldPattern(field);
@@ -184,7 +184,10 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
         {
             name: field.name,
             type: valueType,
-            facet: field.facetable ?? false,
+            // A reference inheriting a facet policy facets its companion below, and
+            // the field itself stays a plain stored value – which is also what keeps
+            // a membership filter on it exact (`compileMembership`).
+            facet: names.facet === field.name,
             sort: field.sortable ?? false,
             // A `required` field is non-optional; so is the `default_sorting_field`,
             // which Typesense requires to be present. Everything else may be absent.
@@ -205,6 +208,18 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
             }),
         });
     }
+    // The `${name}_facet` companion of a reference inheriting a facet policy:
+    // the admitted subset of the field’s values, and the only one of the two
+    // the engine facets. Optional, because a document none of whose values the
+    // policy admits carries no companion at all.
+    if (names.facet !== undefined && names.facet !== field.name) {
+        fields.push({
+            name: names.facet,
+            type: valueType,
+            facet: true,
+            optional: true,
+        });
+    }
     return fields;
 }
 /**

package/dist/in-place-rebuild.d.ts

@@ -35,9 +35,10 @@ export interface InPlaceRebuildOptions extends RebuildOptions {
  * `RebuildAlreadyRunning` when another rebuild holds it) and creates
  * the collection on demand from the {@link SearchType} plus the two
  * bookkeeping fields. A collection that already exists is used as it is, with
- * one exception: it must carry every reference field the declaration asks for,
- * or the run fails with the drop-and-rebuild that fixes it
- * ({@link assertReferencesPresent}).
+ * one exception: it must carry every reference field the declaration asks for
+ * and every facet companion its facets read, or the run fails with the
+ * drop-and-rebuild that fixes it
+ * ({@link assertReferencesAndFacetCompanionsPresent}).
  *
  * Document ids must be unique per (source, entity) – the caller keys them –
  * or documents from different sources overwrite each other.

package/dist/in-place-rebuild.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-place-rebuild.d.ts","sourceRoot":"","sources":["../src/in-place-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAavB,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAa9B;gCACgC;AAChC,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D;sEACkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,cAAc,CACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAiB1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAjB7B;;;;;OAKG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD;;;6CAGyC;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,qBAA0B;IAe/B,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAuHjE;;;;;;OAMG;YACW,cAAc;CAsB7B"}
+{"version":3,"file":"in-place-rebuild.d.ts","sourceRoot":"","sources":["../src/in-place-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAavB,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAa9B;gCACgC;AAChC,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D;sEACkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,cAAc,CACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAiB1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAjB7B;;;;;OAKG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD;;;6CAGyC;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,qBAA0B;IAkB/B,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IA6HjE;;;;;;OAMG;YACW,cAAc;CAsB7B"}

package/dist/in-place-rebuild.js

@@ -1,3 +1,4 @@
+import { facetableFields, physicalFields } from '@lde/search/adapter';
 import { buildCollectionDefinition } from './collection-definition.js';
 import { BatchImporter } from './import.js';
 import { ensureCollectionExists, openLockedRun, releaseLock } from './lock.js';
@@ -39,9 +40,10 @@ const DEFAULT_MAX_SWEEPABLE_SOURCES = 10_000;
  * `RebuildAlreadyRunning` when another rebuild holds it) and creates
  * the collection on demand from the {@link SearchType} plus the two
  * bookkeeping fields. A collection that already exists is used as it is, with
- * one exception: it must carry every reference field the declaration asks for,
- * or the run fails with the drop-and-rebuild that fixes it
- * ({@link assertReferencesPresent}).
+ * one exception: it must carry every reference field the declaration asks for
+ * and every facet companion its facets read, or the run fails with the
+ * drop-and-rebuild that fixes it
+ * ({@link assertReferencesAndFacetCompanionsPresent}).
  *
  * Document ids must be unique per (source, entity) – the caller keys them –
  * or documents from different sources overwrite each other.
@@ -70,7 +72,10 @@ export class InPlaceRebuild {
         this.client = client;
         this.searchType = searchType;
         assertNoReservedFields(searchType, [SOURCE_FIELD, LAST_SEEN_FIELD]);
-        assertSweepableProvenanceField(searchType, { requireFacetable: true });
+        assertSweepableProvenanceField(searchType, {
+            requireFacetable: true,
+            schema: options.schema,
+        });
         this.sourceField = provenanceField(searchType);
         const { maxSweepableSources = DEFAULT_MAX_SWEEPABLE_SOURCES, ...rebuildOptions } = options;
         this.maxSweepableSources = maxSweepableSources;
@@ -104,9 +109,10 @@ export class InPlaceRebuild {
                 };
             });
             // A collection this run did NOT create may predate a `joinable` being
-            // declared, and a reference cannot be added to it here.
+            // declared, or a facet policy on a type this one references – and
+            // neither a reference nor a facet companion can be added to it here.
             if (!created) {
-                await assertReferencesPresent(this.client, name, declaredFields);
+                await assertReferencesAndFacetCompanionsPresent(this.client, name, declaredFields, facetCompanionsOf(this.searchType, definitionOptions.schema));
             }
             const importer = new BatchImporter(this.client, name, batchSize);
             return {
@@ -199,23 +205,48 @@ export class InPlaceRebuild {
  * component’s collections come into existence WITH their references, and never
  * acquire them later.
  *
- * Deliberately scoped to reference fields only. Every other schema difference
- * is self-correcting (a new plain field simply starts being written) or
+ * The facet companion of a reference inheriting a facet policy
+ * (`RootType.facetKeys` on the type it names) is the other field a live
+ * collection cannot acquire: the documents carry `${name}_facet`, the
+ * collection does not declare it, and every facet on the field fails with
+ * *could not find a facet field* – on every type referencing the policy’s
+ * type, until someone drops the collection by hand. Rotating a pipeline
+ * version reprocesses datasets; it does not recreate collections. So it is
+ * checked here too, with the same instruction.
+ *
+ * Deliberately scoped to those two. Every other schema difference is
+ * self-correcting (a new plain field simply starts being written) or
  * harmless, and general drift detection is a feature of its own.
  */
-async function assertReferencesPresent(client, name, fields) {
-    const declared = fields.filter((field) => field.reference !== undefined);
-    if (declared.length === 0) {
+async function assertReferencesAndFacetCompanionsPresent(client, name, fields, facetCompanions) {
+    const references = fields.filter((field) => field.reference !== undefined);
+    if (references.length === 0 && facetCompanions.length === 0) {
         return;
     }
     const existing = new Map((await client.collections(name).retrieve()).fields.map((field) => [
         field.name,
-        field.reference,
+        field,
     ]));
-    const missing = declared.filter((field) => existing.get(field.name) !== field.reference);
-    if (missing.length > 0) {
-        throw new Error(`Typesense collection “${name}” exists without the reference field(s) ${missing
+    const missingReferences = references.filter((field) => existing.get(field.name)?.reference !== field.reference);
+    if (missingReferences.length > 0) {
+        throw new Error(`Typesense collection “${name}” exists without the reference field(s) ${missingReferences
             .map((field) => `“${field.name}” → “${field.reference}”`)
             .join(', ')} its search type declares. A reference cannot be added to a live collection here: drop “${name}” (and the collections that join to it) and let the next run rebuild them.`);
     }
+    const missingCompanions = facetCompanions.filter((companion) => existing.get(companion)?.facet !== true);
+    if (missingCompanions.length > 0) {
+        throw new Error(`Typesense collection “${name}” exists without the facet field(s) ${missingCompanions
+            .map((companion) => `“${companion}”`)
+            .join(', ')} its search type facets on – the companion of a reference to a type that declares a facet policy (“facetKeys”). A facet field cannot be added to a live collection here: drop “${name}” (and the collections that join to it) and let the next run rebuild them.`);
+    }
+}
+/** The `${name}_facet` companions a type’s facets read instead of the fields
+ *  themselves – one per facetable reference inheriting a facet policy
+ *  ({@link physicalFields}). */
+function facetCompanionsOf(searchType, schema) {
+    return facetableFields(searchType).flatMap((field) => {
+        // A facetable field always has a facet field.
+        const facet = physicalFields(field, schema).facet;
+        return facet === field.name ? [] : [facet];
+    });
 }

package/dist/query-compiler.d.ts

@@ -1,5 +1,5 @@
 import type { SearchParams } from 'typesense/lib/Typesense/Documents.js';
-import { type Filter, type RootType, type SearchQuery, type SearchType } from '@lde/search';
+import { type Filter, type RootType, type SearchQuery, type SearchSchema, type SearchType } from '@lde/search';
 /** One hop of a join path, resolved: the Root Type it reaches and the
  *  Typesense collection that type is stored in. */
 export interface JoinTarget {
@@ -38,6 +38,16 @@ export interface BuildSearchParamsOptions {
      * range count is still safe.
      */
     readonly maxFacetValues?: number;
+    /**
+     * The Search Schema the searched type belongs to – what resolves the facet
+     * policy a reference inherits from the type it names
+     * (`physicalFields(field, schema).facet`): the `${name}_facet` companion a
+     * facet on such a field reads, and the membership operator a filter on it
+     * compiles to. Left unset, a facet reads the field itself – which, against a
+     * collection built with the schema, is a field the engine does not facet.
+     * Through the engine it is always set.
+     */
+    readonly schema?: SearchSchema;
     /**
      * Called for each `where` clause that does not compile as the caller wrote
      * it – either because it states no constraint (an empty `in` list, a `range`

package/dist/query-compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-compiler.d.ts","sourceRoot":"","sources":["../src/query-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,QAAQ,EAEb,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAarB;mDACmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,UAAU,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAAC,MAAM,CAAC,CA8BtB;AA+UD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"query-compiler.d.ts","sourceRoot":"","sources":["../src/query-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,QAAQ,EAEb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAarB;mDACmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,UAAU,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAAC,MAAM,CAAC,CA8BtB;AA6VD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/query-compiler.js

@@ -35,7 +35,7 @@ export function buildSearchParams(query, searchType, options = {}) {
         params.sort_by = sortBy;
     }
     if (query.facets.length > 0) {
-        params.facet_by = compileFacetBy(query.facets, searchType);
+        params.facet_by = compileFacetBy(query.facets, searchType, options.schema);
         if (options.maxFacetValues !== undefined) {
             params.max_facet_values = options.maxFacetValues;
         }
@@ -45,17 +45,22 @@ export function buildSearchParams(query, searchType, options = {}) {
 /**
  * The `facet_by` clause. A facet on a numeric field that declares
  * {@link SearchField.facetRanges} faceted into those fixed half-open `[min, max)`
- * bins (a histogram); every other facet is a plain per-value facet on its field
- * name. Typesense range syntax is already start-inclusive/end-exclusive, so the
+ * bins (a histogram); every other facet is a plain per-value facet on the
+ * field the declaration facets ({@link physicalFields} – the field itself, or
+ * the `${name}_facet` companion of a reference inheriting a facet policy).
+ * Typesense range syntax is already start-inclusive/end-exclusive, so the
  * declared bounds pass straight through with no boundary fix-up.
  */
-function compileFacetBy(facets, searchType) {
+function compileFacetBy(facets, searchType, schema) {
     return facets
         .map((name) => {
         const field = fieldNamed(searchType, name);
-        return field !== undefined && isRangeFacet(field)
+        if (field === undefined) {
+            return name;
+        }
+        return isRangeFacet(field)
             ? compileRangeFacet(field.name, field.facetRanges)
-            : name;
+            : (physicalFields(field, schema).facet ?? name);
     })
         .join(',');
 }
@@ -196,7 +201,7 @@ const UNUSABLE = Symbol('unusable');
 function compileCriterion(criterion, searchType, options) {
     const on = criterion.on ?? [];
     if (on.length === 0) {
-        return compileLeaf(criterion, searchType);
+        return compileLeaf(criterion, searchType, options.schema);
     }
     // A joined criterion constrains a document in ANOTHER collection, so the leaf
     // is compiled against the type that path reaches and then wrapped, one
@@ -215,7 +220,7 @@ function compileCriterion(criterion, searchType, options) {
         collections.push(resolved.collection);
         target = resolved.searchType;
     }
-    const leaf = compileLeaf(criterion, target);
+    const leaf = compileLeaf(criterion, target, options.schema);
     // A vacuous leaf states no constraint on the referent, so the join as a whole
     // states none either – the reading, and so the outcome, passes straight
     // through the hops.
@@ -226,7 +231,7 @@ function compileCriterion(criterion, searchType, options) {
 }
 /** The criterion’s own term, against the type it actually constrains – the
  *  searched type, or the one its join path reaches. */
-function compileLeaf(criterion, searchType) {
+function compileLeaf(criterion, searchType, schema) {
     // `id` is the Typesense document key, not a declared field. Exact `:=`
     // membership, like a non-facet field ({@link compileMembership}), so an IRI
     // cannot partial-match on a shared path segment. (`fetchLabels` resolves
@@ -249,7 +254,7 @@ function compileLeaf(criterion, searchType) {
     }
     if ('in' in criterion) {
         return criterion.in.length > 0
-            ? compileMembership(field, criterion.in)
+            ? compileMembership(field, criterion.in, schema)
             : VACUOUS;
     }
     if ('range' in criterion) {
@@ -260,12 +265,18 @@ function compileLeaf(criterion, searchType) {
 /**
  * A membership clause. A non-facet (tokenized) field uses the exact `:=`
  * operator so an IRI cannot partial-match on a shared path segment.
+ *
+ * *Non-facet* is the **engine’s** facet status, not the declaration’s: a
+ * reference inheriting a facet policy is `facetable` in the schema while the
+ * engine facets its companion and stores the field itself plain – and a
+ * filter on such a field is exactly what the policy promises stays whole, so
+ * it must compile exact, not tokenized.
  */
-function compileMembership(field, values) {
+function compileMembership(field, values, schema) {
     const list = `[${values.map(escapeFilterValue).join(',')}]`;
-    return field.facetable !== true
-        ? `${field.name}:=${list}`
-        : `${field.name}:${list}`;
+    return physicalFields(field, schema).facet === field.name
+        ? `${field.name}:${list}`
+        : `${field.name}:=${list}`;
 }
 /** An inclusive Typesense range clause, or `undefined` when neither bound is
  *  usable. Which of the two readings that is – the caller set no bounds, or the

package/dist/rebuild-support.d.ts

@@ -1,5 +1,5 @@
 import type { Client } from 'typesense';
-import type { SearchType } from '@lde/search';
+import type { SearchSchema, SearchType } from '@lde/search';
 import { type CollectionDefinitionOptions } from './collection-definition.js';
 /**
  * The tuning knobs both rebuild writers share, on top of the collection-definition
@@ -60,13 +60,19 @@ export declare function assertNoReservedFields(searchType: SearchType, reserved:
  *   selection, which carries raw dataset IRIs, so a transformed value would
  *   match nothing and the sweep would silently stop deleting;
  * - **`facetable`** where the writer enumerates the indexed sources by faceting
- *   it (the In-place writer does; Blue/green only ever filters by a known IRI).
+ *   it (the In-place writer does; Blue/green only ever filters by a known IRI)
+ *   – and faceted **on its own name**: a reference inheriting a facet policy
+ *   from the type it names facets a companion holding only the admitted keys
+ *   (`physicalFields(field, schema).facet`), so enumerating the sources
+ *   through it would miss every dataset the policy excludes. `schema` is what
+ *   resolves that; without one no policy is visible, as nowhere else.
  *
  * Thrown at writer construction, so a declaration that cannot be swept fails
  * before a run touches the index rather than at the sweep, after the writes.
  */
 export declare function assertSweepableProvenanceField(searchType: SearchType, options: {
     readonly requireFacetable: boolean;
+    readonly schema?: SearchSchema;
 }): void;
 /** Stamp each document with fixed bookkeeping fields as it streams past. */
 export declare function stampDocuments<TDocument>(documents: AsyncIterable<TDocument>, stamp: Readonly<Record<string, string>>): AsyncIterable<TDocument & Record<string, string>>;

package/dist/rebuild-support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rebuild-support.d.ts","sourceRoot":"","sources":["../src/rebuild-support.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAKpC;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,2BAA2B;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;0FAC0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;uEAGmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;KAChE,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAkBxB;AAsCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;IAAE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAC9C,IAAI,CA0BN;AAED,4EAA4E;AAC5E,wBAAuB,cAAc,CAAC,SAAS,EAC7C,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,EACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtC,aAAa,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAInD;AAED,mEAAmE;AACnE,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAKf"}
+{"version":3,"file":"rebuild-support.d.ts","sourceRoot":"","sources":["../src/rebuild-support.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQ5D,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAKpC;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,2BAA2B;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;0FAC0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;uEAGmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;KAChE,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAkBxB;AAsCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;IACP,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC,GACA,IAAI,CAiCN;AAED,4EAA4E;AAC5E,wBAAuB,cAAc,CAAC,SAAS,EAC7C,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,EACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtC,aAAa,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAInD;AAED,mEAAmE;AACnE,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/rebuild-support.js

@@ -1,4 +1,4 @@
-import { datasetField, isInternalField, joinGraph, referenceFields, } from '@lde/search/adapter';
+import { datasetField, isInternalField, joinGraph, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildCollectionDefinition, } from './collection-definition.js';
 import { deriveCollectionName } from './collection-name.js';
 import { DEFAULT_LOCK_TTL_MS } from './lock.js';
@@ -87,7 +87,12 @@ export function assertNoReservedFields(searchType, reserved) {
  *   selection, which carries raw dataset IRIs, so a transformed value would
  *   match nothing and the sweep would silently stop deleting;
  * - **`facetable`** where the writer enumerates the indexed sources by faceting
- *   it (the In-place writer does; Blue/green only ever filters by a known IRI).
+ *   it (the In-place writer does; Blue/green only ever filters by a known IRI)
+ *   – and faceted **on its own name**: a reference inheriting a facet policy
+ *   from the type it names facets a companion holding only the admitted keys
+ *   (`physicalFields(field, schema).facet`), so enumerating the sources
+ *   through it would miss every dataset the policy excludes. `schema` is what
+ *   resolves that; without one no policy is visible, as nowhere else.
  *
  * Thrown at writer construction, so a declaration that cannot be swept fails
  * before a run touches the index rather than at the sweep, after the writes.
@@ -107,6 +112,10 @@ export function assertSweepableProvenanceField(searchType, options) {
     if (options.requireFacetable && field.facetable !== true) {
         problems.push('it is not facetable, and the membership sweep enumerates the indexed datasets by faceting it');
     }
+    else if (options.requireFacetable &&
+        physicalFields(field, options.schema).facet !== field.name) {
+        problems.push('it inherits a facet policy from the type it names, so the engine facets only the datasets the policy admits, and the membership sweep enumerates the indexed datasets by faceting it');
+    }
     if (problems.length > 0) {
         throw new Error(`SearchType “${searchType.name}” declares “${field.name}” over the indexed dataset, which this writer keeps its provenance bookkeeping on, but ${problems.join('; and ')}.`);
     }

package/dist/search.d.ts

@@ -108,6 +108,9 @@ export interface TypesenseSearchResponse {
         readonly document: Record<string, unknown>;
     }[];
     readonly facet_counts?: readonly {
+        /** The field faceted – by the time a response reaches
+         *  {@link parseSearchResponse}, the **declared** field name: the engine
+         *  maps a facet companion’s name back at the response boundary. */
         readonly field_name: string;
         readonly counts: readonly {
             readonly value: string;

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAGL,KAAK,cAAc,EAOnB,KAAK,UAAU,EAGf,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAiBrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAExE;;;;sDAIsD;AACtD,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAIhC,SAAQ,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACnE;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CACpC,KAAK,SAAS,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE,CAC3D,SAAQ,YAAY,CAAC,KAAK,CAAC;IAC3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EAEzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,GAAE,4BAA4B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAM,GAChE,qBAAqB,CAAC,KAAK,CAAC,CAuW9B;AAyCD,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AA0HD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAgDtC;AA6BD,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS;QAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS;YACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,EAAE,CAAC;KACL,EAAE,CAAC;CACL;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EAC3C,MAAM,EAAE,YAAY,EACpB,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,YAAY,CAgDd"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/search.js

@@ -1,4 +1,4 @@
-import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNameOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNameOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
 import { resolveProjection } from './lookup.js';
@@ -48,6 +48,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
     const joins = joinGraph(schema);
     const searchParamsOptions = {
         ...options,
+        schema,
         joinTargetFor: (from, path) => {
             // Both lookups always hit: `assertValidQuery` runs first and rejects
             // every path this could not resolve, and each type resolved a collection
@@ -81,6 +82,22 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             ];
         })),
     ]));
+    // Typesense reports a facet under the field it faceted, which for a reference
+    // inheriting a facet policy is the `${name}_facet` companion, not the
+    // declared field. Resolved back to the declared name per type ONCE, from the
+    // same `physicalFields` that named it, and applied to every response at the
+    // boundary – before `labelLookupGroups` (which finds a facet’s label source
+    // by declared name) and `parseSearchResponse` (which files its counts under
+    // it). Either consumer meeting the engine name would silently lose the
+    // facet’s labels, or its counts, or both.
+    const declaredFacetNames = new Map([...schema.values()].map((searchType) => [
+        searchType.class,
+        new Map(facetableFields(searchType).map((field) => [
+            // A facetable field always has a facet field.
+            physicalFields(field, schema).facet,
+            field.name,
+        ])),
+    ]));
     // The distinct source collections per type, for the cached path – fixed at
     // construction, so no per-search dedup dance.
     const distinctLabelSources = new Map([...labelSources].map(([type, sources]) => [
@@ -210,7 +227,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // would overflow Typesense's 4000-char query-string limit. POST puts it
             // in the body, so the filter is bounded by the caller's request, not by
             // the URL.
-            const response = await performSingleSearch(client, collections.get(searchType.class), params);
+            const response = withDeclaredFacetNames(await performSingleSearch(client, collections.get(searchType.class), params), declaredFacetNames.get(searchType.class));
             const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
             // What the caller asked to resolve, level by level. Independent of the
             // label lookup above: that one serves facet buckets and unprojected
@@ -243,12 +260,16 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // compiles as facet-only regardless of what it carries: no hits
             // (per_page 0) and no ordering – nothing is transferred or sorted that
             // this method cannot return.
-            const { results } = (await client.multiSearch.perform({
+            const { results: rawResults } = (await client.multiSearch.perform({
                 searches: dispatched.map(({ query }) => ({
                     collection,
                     ...buildSearchParams({ ...query, orderBy: [], limit: 0, offset: 0 }, searchType, searchParamsOptions),
                 })),
             }));
+            const declaredNames = declaredFacetNames.get(searchType.class);
+            const results = rawResults.map((result) => 'error' in result
+                ? result
+                : withDeclaredFacetNames(result, declaredNames));
             // One label lookup serves every successful facet result in the batch.
             const responses = results.filter((result) => !('error' in result));
             const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups(responses, labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
@@ -384,6 +405,25 @@ function labelLookupGroups(responses, sources, outputSources) {
         iris: [...iris],
     }));
 }
+/**
+ * The response with each facet filed under the declared field name its engine
+ * facet field stands for – the one place an engine facet name is translated,
+ * so that nothing downstream of it meets one.
+ */
+function withDeclaredFacetNames(response, declaredNames) {
+    if (response.facet_counts === undefined) {
+        return response;
+    }
+    return {
+        ...response,
+        facet_counts: response.facet_counts.map((facet) => ({
+            ...facet,
+            // Every facet the engine reports was asked for by a declared, facetable
+            // field (`assertValidQuery`), and the map holds each of those.
+            field_name: declaredNames.get(facet.field_name),
+        })),
+    };
+}
 /**
  * Dispatch one search as a single-entry `multi_search` (POST). `multi_search`
  * reports a failed entry inline instead of rejecting the call, so the entry is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "description": "Typesense implementation of the @lde/search SearchEngine port: collection-schema builder, query compiler, label-resolving result reconstruction, and blue/green index lifecycle. Engine-specific (Typesense) but domain-agnostic.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -25,16 +25,17 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.23.1",
+    "@lde/search": "^0.23.2",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"
   },
   "devDependencies": {
+    "n3": "^2.1.2",
     "testcontainers": "^12.1.0"
   },
   "peerDependencies": {
     "@lde/dataset": "^0.7.9",
-    "@lde/pipeline": "^0.36.1"
+    "@lde/pipeline": "^0.36.3"
   }
 }