@lde/search-typesense 0.27.4 → 0.28.0

package/dist/collection-definition.d.ts

@@ -19,11 +19,11 @@ export interface CollectionDefinitionOptions {
      */
     readonly collectionNameFor?: (searchType: SearchType) => string;
     /**
-     * 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), 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;
+     * The Search Schema the type belongs to – required when the type carries an
+     * inline reference (whose nested fields are declared from the reference type
+     * the schema resolves), or 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.
      *
@@ -82,13 +82,18 @@ export interface CollectionDefinitionOptions {
  * entirely: they exist only as a projection-time reading device for the
  * derives, so the collection stores nothing for them.
  *
- * A surfaced (`output`) inline reference is stored as a **nested object** –
- * `object` or `object[]` – with one nested Physical Field per output field of
- * its {@link ReferenceType} ({@link nestedFieldName}), which turns on
- * `enable_nested_fields` for the collection. Nested fields carry `output` only
- * (enforced by `searchSchema`), so they are declared `index: false`: each
- * referent’s values stay grouped on disk and cost no RAM, exactly like the
- * display labels.
+ * An inline reference is stored as a **nested object** – `object` or
+ * `object[]` – with one nested Physical Field per field of the type it nests
+ * ({@link nestedFieldName}), which turns on `enable_nested_fields` for the
+ * collection. A nested field is `index: false` unless it declares a query Role,
+ * so a display-only nesting stays disk weight and costs no RAM, exactly like
+ * the display labels; one that opts into `filterable` or `searchable` is
+ * indexed, and its parent object with it (see {@link nestedFields}).
+ *
+ * An inline reference declaring `filterable` or `facetable` also emits its
+ * {@link ReferenceStrategy.identity identity companion} – a flat id field the
+ * engine can filter and facet, which a nested object is not
+ * ({@link identityCompanionFields}).
  */
 export declare function buildCollectionDefinition(searchType: SearchType, options?: CollectionDefinitionOptions): CollectionCreateSchema;
 //# sourceMappingURL=collection-definition.d.ts.map

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;;;;;;;;;;;;;;;;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"}
+{"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,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAcrB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CA2BxB"}

package/dist/collection-definition.js

@@ -1,4 +1,4 @@
-import { displayFieldPattern, ID_FIELD, isInlineReference, isInternalField, joinGraph, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
+import { displayFieldPattern, ID_FIELD, isInlineReference, isInternalField, joinGraph, localLookupTypeOf, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
 import { deriveCollectionName } from './collection-name.js';
 /**
  * Build a Typesense collection definition from the unified {@link SearchType}, so
@@ -36,13 +36,18 @@ import { deriveCollectionName } from './collection-name.js';
  * entirely: they exist only as a projection-time reading device for the
  * derives, so the collection stores nothing for them.
  *
- * A surfaced (`output`) inline reference is stored as a **nested object** –
- * `object` or `object[]` – with one nested Physical Field per output field of
- * its {@link ReferenceType} ({@link nestedFieldName}), which turns on
- * `enable_nested_fields` for the collection. Nested fields carry `output` only
- * (enforced by `searchSchema`), so they are declared `index: false`: each
- * referent’s values stay grouped on disk and cost no RAM, exactly like the
- * display labels.
+ * An inline reference is stored as a **nested object** – `object` or
+ * `object[]` – with one nested Physical Field per field of the type it nests
+ * ({@link nestedFieldName}), which turns on `enable_nested_fields` for the
+ * collection. A nested field is `index: false` unless it declares a query Role,
+ * so a display-only nesting stays disk weight and costs no RAM, exactly like
+ * the display labels; one that opts into `filterable` or `searchable` is
+ * indexed, and its parent object with it (see {@link nestedFields}).
+ *
+ * An inline reference declaring `filterable` or `facetable` also emits its
+ * {@link ReferenceStrategy.identity identity companion} – a flat id field the
+ * engine can filter and facet, which a nested object is not
+ * ({@link identityCompanionFields}).
  */
 export function buildCollectionDefinition(searchType, options = {}) {
     const { defaultLocale, collectionNameFor = deriveCollectionName } = options;
@@ -64,16 +69,19 @@ export function buildCollectionDefinition(searchType, options = {}) {
     return collection;
 }
 /**
- * The {@link ReferenceType} a field nests, or `undefined` when it nests
- * nothing. Throws when the type surfaces an inline reference the caller gave no
- * schema to resolve: the collection would silently store the reference as a
- * string the projection never writes, so every document would fail to import.
+ * The type a field nests, or `undefined` when it nests nothing. Throws when the
+ * type carries an inline reference the caller gave no schema to resolve: the
+ * collection would silently store the reference as a string the projection
+ * never writes, so every document would fail to import.
  */
 function nestedTypeOf(searchType, field, schema) {
-    const nested = schema === undefined ? undefined : nestedReferenceType(schema, field);
-    // Reached only for a field carrying a Role, so an inline reference here is a
-    // surfaced one: `searchSchema` allows an inline reference no Role but
-    // `output`.
+    const nested = schema === undefined
+        ? undefined
+        : (nestedReferenceType(schema, field) ??
+            localLookupTypeOf(field, schema));
+    // Reached only for a field carrying a Role, so an inline reference here
+    // stores entries: a Role-less one is an internal reading device, pruned
+    // before the writer.
     if (nested === undefined && isInlineReference(field)) {
         throw new Error(`Building the collection for “${searchType.name}” needs the search schema its surfaced inline reference “${field.name}” resolves against; pass it as the collection-definition option “schema”.`);
     }
@@ -136,7 +144,10 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
     }
     const nested = nestedTypeOf(searchType, field, schema);
     if (nested !== undefined) {
-        return nestedFields(field.name, field, nested, schema);
+        return [
+            ...nestedFields(field.name, field, nested, schema, defaultLocale),
+            ...identityCompanionFields(field, schema),
+        ];
     }
     const names = physicalFields(field, schema);
     if (field.kind === 'text') {
@@ -223,53 +234,217 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
     return fields;
 }
 /**
- * The nested object one surfaced inline reference stores, plus one nested
- * Physical Field per output field of its {@link ReferenceType} – recursing for
- * a reference type that itself surfaces an inline reference, to the depth the
- * schema declares (`searchSchema` rejects inline cycles, so the recursion
- * terminates).
+ * The nested object one inline reference stores, plus one nested Physical Field
+ * per field of the type it nests – recursing for a nested field that itself
+ * nests (another inline reference, or a
+ * {@link ReferenceStrategy.local local} lookup, which stores its endpoint
+ * shaped by the target’s own declaration). `searchSchema` rejects inline
+ * cycles, so the recursion terminates.
  *
- * Everything nested is `index: false`: a nested field carries `output` only, so
- * it is stored with its referent and read back with it, never searched, faceted
- * or sorted on. That keeps the RAM lever intact – a nested document is display
- * weight, like the per-language labels – and lets the declared child types be
- * exactly what the projection writes without an indexing contract to satisfy.
- * Declaring the children rather than only the object is what makes the nesting
- * legible in the collection, and what keeps an {@link isInternalField Internal
- * Field} inside a Reference Type visibly contributing nothing.
+ * **A nested field is indexed exactly when it declares a query Role.** One that
+ * declares only `output` keeps `index: false`: stored with its referent, read
+ * back with it, costing disk rather than RAM – the same lever the per-language
+ * display labels use. `filterable` or `searchable` turns indexing on for that
+ * one field, and nothing else.
+ *
+ * **The parent object must be indexed whenever any descendant is.** Typesense
+ * silently ignores an indexed child under an `index: false` parent: no error,
+ * no match, every query answering empty. So the parent’s flag is computed from
+ * the children rather than declared, and this is the one place that invariant
+ * can be got wrong.
  */
-function nestedFields(prefix, reference, referenceType, schema) {
+function nestedFields(prefix, reference, nestedType, schema, defaultLocale, withinArray = false, onPath = new Set()) {
     const array = reference.array === true;
-    const fields = [
-        {
-            name: prefix,
-            type: array ? 'object[]' : 'object',
+    // A type already on this path is not descended into again. `searchSchema`
+    // rejects INLINE cycles, but a {@link ReferenceStrategy.local local} lookup
+    // may reach a Root Type that reaches back – `Work → Person → Work` is a
+    // reasonable schema and nothing forbids it – and without this the builder
+    // recurses until the stack gives out. Stopping here matches where the FRAME
+    // stops ({@link inlineFramingDepth}), so the collection declares exactly the
+    // depth the projection can fill.
+    const walked = new Set(onPath).add(nestedType.name);
+    // Typesense flattens a nested object, so a value under a multi-valued
+    // ancestor arrives as an array however single-valued the declaration is.
+    // That only matters for an INDEXED field, whose declared type is checked
+    // against what is stored; an unindexed one is stored as-is.
+    const flattensToArray = withinArray || array;
+    const children = [];
+    // A `local` lookup nests its endpoint’s own document, which carries the `id`
+    // that identifies it. The target type does not declare `id` – no type
+    // declares its own key – so it is added here or it would be the one stored
+    // value the collection never mentions.
+    if (nestedType.class !== undefined) {
+        children.push({
+            name: nestedFieldName(prefix, 'id'),
+            type: flattensToArray ? 'string[]' : 'string',
             index: false,
-            optional: reference.required !== true,
-        },
-    ];
-    for (const field of referenceType.fields) {
+            optional: true,
+        });
+    }
+    for (const field of nestedType.fields) {
         if (isInternalField(field)) {
             continue;
         }
-        const nested = nestedReferenceType(schema, field);
-        if (nested !== undefined) {
-            fields.push(...nestedFields(nestedFieldName(prefix, field.name), field, nested, schema));
+        const deeper = nestedTypeOfNestedField(field, schema);
+        if (deeper !== undefined && walked.has(deeper.name)) {
+            // The cycle stops here, and so does the frame – nothing will ever be
+            // stored under this field, so nothing is declared for it. Falling
+            // through would declare it as a LEAF, whose scalar type is not what a
+            // nested object would be stored as.
             continue;
         }
-        // A nested text field stores its display values exactly as a root one does
-        // – one `${name}_<lang>` per present language, matched by one pattern
-        // field – only under the referent’s prefix. It has no search or sort
-        // companions: those are Roles a nested field cannot declare.
-        const pattern = field.kind === 'text' ? displayFieldPattern(field) : undefined;
+        if (deeper !== undefined) {
+            children.push(...nestedFields(nestedFieldName(prefix, field.name), field, deeper, schema, defaultLocale, flattensToArray, walked), 
+            // A nested field that stores an object cannot be filtered as itself,
+            // and its own id is a level deeper than a condition can be welded to –
+            // an engine welds conditions on an entry's LEAF fields only. Its
+            // identity companion is that leaf, so it sits beside the object rather
+            // than inside it.
+            ...nestedIdentityFields(prefix, field, schema));
+            continue;
+        }
+        children.push(...nestedLeafFields(prefix, field, defaultLocale, flattensToArray));
+    }
+    return [
+        {
+            name: prefix,
+            // Flattening applies to an object exactly as it does to a value: a
+            // single-valued nesting inside a multi-valued one arrives as a list of
+            // objects, so it is only declared `object` where nothing above it is an
+            // `object[]`.
+            type: flattensToArray ? 'object[]' : 'object',
+            // Never hard-coded: see the parent-object rule above.
+            index: children.some((child) => child.index !== false),
+            optional: reference.required !== true,
+        },
+        ...children,
+    ];
+}
+/**
+ * The **identity companion** of an inline reference: the flat field holding the
+ * ids its entries reference, which the engine filters and facets in place of
+ * the nested object it cannot. Empty for an inline reference declaring no
+ * `identity` – a display-only nesting keeps costing no RAM.
+ *
+ * A second, narrowed field joins it where the target declares a facet policy,
+ * exactly as it does for a top-level facetable reference: the facet then reads
+ * the admitted subset, so an excluded id is never seen by the engine rather
+ * than merely unlabelled.
+ */
+function identityCompanionFields(field, schema) {
+    const names = physicalFields(field, schema);
+    if (names.identity === undefined) {
+        return [];
+    }
+    const fields = [
+        {
+            name: names.identity,
+            type: 'string[]',
+            facet: names.facet === names.identity,
+            optional: true,
+        },
+    ];
+    if (names.facet !== undefined && names.facet !== names.identity) {
+        fields.push({
+            name: names.facet,
+            type: 'string[]',
+            facet: true,
+            optional: true,
+        });
+    }
+    return fields;
+}
+/** The identity companion of a nested field that stores an object: a flat leaf
+ *  beside it, holding the ids a filter welds on. Empty for a nested field that
+ *  declares no query Role, which needs none. */
+function nestedIdentityFields(prefix, field, schema) {
+    const names = physicalFields(field, schema);
+    if (names.identity === undefined) {
+        return [];
+    }
+    return [
+        {
+            name: nestedFieldName(prefix, names.identity),
+            // Always a list, whatever the enclosing reference's arity: the projection
+            // writes it with `setArray`, and an indexed field's declared type is
+            // checked against what is stored – a `string` here rejects every
+            // document carrying such an edge, at import.
+            type: 'string[]',
+            index: true,
+            optional: true,
+        },
+    ];
+}
+/** The type a *nested* field itself nests: another inline reference’s type, or
+ *  the Root Type a {@link ReferenceStrategy.local local} lookup projects its
+ *  endpoint through. */
+function nestedTypeOfNestedField(field, schema) {
+    return nestedReferenceType(schema, field) ?? localLookupTypeOf(field, schema);
+}
+/**
+ * The Physical Fields one non-nesting nested field contributes: exactly what
+ * the projection writes under the referent’s prefix, so the collection and the
+ * document cannot disagree.
+ *
+ * A nested `text` field stores its display values as a root one does – one
+ * `${name}_<lang>` per present language, matched by a single pattern field,
+ * never indexed – plus a folded search companion per locale when it is
+ * `searchable`. Anything undeclared here would still arrive in the document,
+ * and Typesense indexes what it is not told to leave alone, so the fanout is
+ * enumerated rather than left to inference.
+ */
+function nestedLeafFields(prefix, field, defaultLocale, flattensToArray) {
+    const names = physicalFields(field);
+    const searchString = flattensToArray ? 'string[]' : 'string';
+    const fields = [];
+    if (field.kind === 'text') {
+        const pattern = displayFieldPattern(field);
+        if (pattern !== undefined) {
+            // Display values are never indexed, whatever Roles the field declares:
+            // search hits the folded companions below, so the display copies stay on
+            // disk with every language they carry.
+            fields.push({
+                name: nestedFieldName(prefix, pattern),
+                type: 'string',
+                index: false,
+                optional: true,
+            });
+        }
+        fields.push(...names.search.map((name, index) => {
+            const locale = field.locales[index] === 'und' ? defaultLocale : field.locales[index];
+            return {
+                name: nestedFieldName(prefix, name),
+                type: searchString,
+                optional: true,
+                ...(locale !== undefined && { stem: true, locale }),
+            };
+        }));
+        return fields;
+    }
+    // A nested field can be `filterable` or `searchable`, never `facetable` or
+    // `sortable` (`searchSchema`), so `filterable` is what indexes the value
+    // itself – its search companion below indexes on its own account.
+    const indexed = field.filterable === true;
+    const valueType = typesenseValueType(field);
+    // Two ways a list arrives: the field declares one, or an ancestor's
+    // `object[]` flattens it into one. `typesenseValueType` honours `array` only
+    // for the string-shaped kinds, so a multi-valued nested `integer` would
+    // otherwise be declared scalar and rejected at import.
+    const storesAList = flattensToArray || field.array === true;
+    fields.push({
+        name: nestedFieldName(prefix, field.name),
+        type: indexed && storesAList ? arrayValueType(valueType) : valueType,
+        index: indexed,
+        // Always optional: `required` is a promise about the *referent* (this value
+        // is on every referent), while Typesense’s flag is about the document.
+        // Under a multi-valued reference those are different claims, and only the
+        // referent-level one is the declaration’s.
+        optional: true,
+    });
+    for (const name of names.search) {
         fields.push({
-            name: nestedFieldName(prefix, pattern ?? field.name),
-            type: field.kind === 'text' ? 'string' : typesenseValueType(field),
-            index: false,
-            // Always optional: `required` is a promise about the *referent* (this
-            // value is on every referent), while Typesense’s flag is about the
-            // document. Under a multi-valued reference those are different claims,
-            // and only the referent-level one is the declaration’s.
+            name: nestedFieldName(prefix, name),
+            type: searchString,
             optional: true,
         });
     }
@@ -277,6 +452,30 @@ function nestedFields(prefix, reference, referenceType, schema) {
 }
 /** The Typesense field type for a non-localized field, from its `kind`. 64-bit
  *  integers (and dates, stored as Unix seconds) so large counts never overflow. */
+/**
+ * The array form of a value type, for a nested field that an ancestor’s
+ * `object[]` flattens into a list. Only an **indexed** field needs it: Typesense
+ * checks a declared type against what is stored, and a value under a
+ * multi-valued ancestor arrives as an array however single-valued its own
+ * declaration is. Enumerated rather than string-appended so an invalid
+ * combination cannot be built.
+ */
+function arrayValueType(type) {
+    switch (type) {
+        case 'string':
+            return 'string[]';
+        case 'int64':
+            return 'int64[]';
+        case 'float':
+            return 'float[]';
+        case 'bool':
+            return 'bool[]';
+        // Already a list: a multi-valued declaration under a multi-valued ancestor
+        // flattens no further.
+        case 'string[]':
+            return 'string[]';
+    }
+}
 function typesenseValueType(field) {
     switch (field.kind) {
         case 'integer':

package/dist/lookup.d.ts

@@ -1,22 +1,31 @@
 import type { Client } from 'typesense';
 import { type ReferenceProjection, type RootType, type SearchSchema, type SearchType } from '@lde/search';
 /**
- * One resolved level of a {@link ReferenceProjection}: the referents fetched
- * for it, keyed by IRI and still in the engine’s flat physical shape, plus the
- * levels resolved *from* them.
+ * One resolved level of a {@link ReferenceProjection}. A level is one of two
+ * things, discriminated by `via`, because the two cost different things:
+ *
+ * - **`lookup`** – referents fetched from the target’s own collection, keyed by
+ *   id and still in the engine’s flat physical shape. One batched round trip.
+ * - **`nested`** – an inline reference descended into. Its entries are already
+ *   in the hit, so nothing is fetched and there is no target; the level exists
+ *   only to carry the levels resolved *below* it.
  *
  * Kept flat rather than reconstructed here so one reconstruction path serves
  * hits and referents alike – the surface never learns that a nested document
  * arrived by a second round-trip rather than from the hit itself.
  */
-export interface ResolvedReferents {
-    /** The Root Type these referents are declared by – reconstruction reads them
-     *  through the target’s own declaration, never the referrer’s. */
+export type ResolvedReferents = {
+    readonly via: 'lookup';
+    /** The Root Type these referents are declared by – reconstruction reads
+     *  them through the target’s own declaration, never the referrer’s. */
     readonly target: RootType;
     readonly documents: ReadonlyMap<string, Record<string, unknown>>;
     /** Keyed by the reference field’s name on the type this level carries. */
     readonly children: ReadonlyMap<string, ResolvedReferents>;
-}
+} | {
+    readonly via: 'nested';
+    readonly children: ReadonlyMap<string, ResolvedReferents>;
+};
 /**
  * Resolve a projection against the documents that name its referents: one
  * batched `multi_search` **per level**, never per document, because the IRIs of

package/dist/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AASrB;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;sEACkE;IAClE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D;AAKD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAkEjD"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAUrB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB;2EACuE;IACvE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D,GACD;IACE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D,CAAC;AAKN;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAwFjD"}

package/dist/lookup.js

@@ -1,4 +1,4 @@
-import { displayFieldName, fieldNamed, labelFieldOf, rootTypeNamed, } from '@lde/search/adapter';
+import { displayFieldName, fieldNamed, labelFieldOf, nestedReferenceType, rootTypeNamed, } from '@lde/search/adapter';
 import { escapeFilterValue } from './query-compiler.js';
 /** Typesense caps a filter list; the same batch size the label lookup uses. */
 const BATCH_SIZE = 200;
@@ -21,9 +21,24 @@ export async function resolveProjection(client, projection, searchType, schema,
     // stated bound – one round-trip per level – one per field instead.
     const levels = await Promise.all(Object.entries(projection).map(async ([name, level]) => {
         const field = fieldNamed(searchType, name);
-        if (field === undefined ||
-            field.kind !== 'reference' ||
-            field.ref?.strategy !== 'lookup') {
+        if (field === undefined) {
+            return undefined;
+        }
+        // An inline level costs no round trip: its entries are already in the
+        // parents. Flatten them out and hand them down, so the level BELOW reads
+        // its ids off the entries rather than off the document – which is the
+        // whole of what makes a lookup inside a qualified edge resolvable.
+        const nested = nestedReferenceType(schema, field);
+        if (nested !== undefined) {
+            return [
+                name,
+                {
+                    via: 'nested',
+                    children: await resolveProjection(client, level.resolve, nested, schema, collections, entriesOf(parents, name), onError),
+                },
+            ];
+        }
+        if (field.kind !== 'reference' || field.ref?.strategy !== 'lookup') {
             // `assertValidQuery` rejects this for every caller; skipping keeps a
             // hand-built query from throwing here rather than at the port’s guard.
             return undefined;
@@ -44,6 +59,7 @@ export async function resolveProjection(client, projection, searchType, schema,
         return [
             name,
             {
+                via: 'lookup',
                 target,
                 documents,
                 // The level below reads the IRIs off the documents this one just
@@ -59,14 +75,40 @@ export async function resolveProjection(client, projection, searchType, schema,
     }
     return resolved;
 }
-/** Every distinct IRI a page of documents carries under one reference field. */
+/**
+ * The nested entries a page of documents carries under one inline reference,
+ * flattened into one list – the “documents” the level below resolves against.
+ *
+ * Flattening rather than grouping is what keeps the round-trip count per
+ * *level* rather than per document: every entry on the page contributes its ids
+ * to one batch, and reconstruction re-associates them afterwards by id.
+ */
+function entriesOf(documents, field) {
+    return documents.flatMap((document) => {
+        const raw = document[field];
+        return (Array.isArray(raw) ? raw : [raw]).filter((entry) => typeof entry === 'object' && entry !== null);
+    });
+}
+/**
+ * Every distinct id a page of documents carries under one reference field.
+ *
+ * A reference stores its ids one of two ways, and which one is about how much
+ * of the referent the deployment wants stored, not about identity: a plain
+ * reference stores the id itself, while a
+ * {@link ReferenceStrategy.local local} lookup stores the endpoint’s own
+ * document, whose `id` is the same value. Both are read, so a level resolves
+ * the same either way.
+ */
 function distinctIris(documents, field) {
     const iris = new Set();
     for (const document of documents) {
         const raw = document[field];
         for (const value of Array.isArray(raw) ? raw : [raw]) {
-            if (typeof value === 'string' && value !== '') {
-                iris.add(value);
+            const id = typeof value === 'object' && value !== null
+                ? value.id
+                : value;
+            if (typeof id === 'string' && id !== '') {
+                iris.add(id);
             }
         }
     }

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,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"}
+{"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,EAIhB,MAAM,aAAa,CAAC;AAmBrB;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,CAkCtB;AAwfD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/query-compiler.js

@@ -1,5 +1,5 @@
 import { fold } from '@lde/text-normalization';
-import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isRangeFacet, pageForOffset, physicalFields, searchableFields, } from '@lde/search/adapter';
+import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isInternalField, isRangeFacet, isWelded, joinGraph, localLookupTypeOf, pageForOffset, physicalFields, nestedReferenceType, resolvePath, searchableFields, } from '@lde/search/adapter';
 /**
  * Compile the engine-neutral {@link SearchQuery} into Typesense search
  * parameters – the query half of the engine adapter. Pure (no client, no env),
@@ -16,7 +16,7 @@ export function buildSearchParams(query, searchType, options = {}) {
     const folded = query.text !== undefined && query.text.length > 0
         ? fold(query.text)
         : undefined;
-    const { names, weights } = queryFields(searchType, query.locale);
+    const { names, weights } = queryFields(searchType, query.locale, options.schema);
     const filterBy = compileFilterBy(query.where, searchType, options);
     const sortBy = query.orderBy
         .map((sort) => compileSort(sort, searchType, query.locale))
@@ -78,16 +78,41 @@ function compileRangeFacet(name, ranges) {
  * 1), so a match in the user’s language ranks higher while cross-language matches
  * still surface.
  */
-function queryFields(searchType, locale) {
+function queryFields(searchType, locale, schema) {
     const names = [];
     const weights = [];
+    collectSearchable(searchType, locale, schema, '', new Set(), names, weights);
+    return { names, weights };
+}
+/**
+ * Collect the searchable physical fields of a type and of everything it nests,
+ * each under the path an engine addresses it by.
+ *
+ * Nested fields are walked because a nested field may declare `searchable`
+ * (ADR 24) – and a companion that is indexed but absent from `query_by` is the
+ * worst of both: it costs the RAM of an indexed field and matches nothing, in
+ * silence. So the walk here is what makes that Role mean anything.
+ *
+ * `onPath` guards the walk, and is scoped to the PATH rather than to the walk
+ * as a whole: two fields may nest one type – `creator` and `contributor` over
+ * the same edge – and each reaches it under its own prefix, so each must
+ * contribute its own companions. A set shared across the walk would let the
+ * first field claim the type and leave the second's companions indexed but
+ * unqueried. What it does guard is a type reached from ITSELF, which a
+ * {@link ReferenceStrategy.local local} lookup can do.
+ */
+function collectSearchable(searchType, locale, schema, prefix, onPath, names, weights) {
+    if (onPath.has(searchType.name)) {
+        return;
+    }
+    const walked = new Set(onPath).add(searchType.name);
     for (const field of searchableFields(searchType)) {
         const search = physicalFields(field).search;
         const baseWeight = field.searchable.weight;
         if (field.kind === 'text') {
             const locales = field.locales;
             search.forEach((name, index) => {
-                names.push(name);
+                names.push(qualify(prefix, name));
                 // The active locale keeps full weight; `und` is language-neutral, so
                 // it is never demoted (an untagged-only field would otherwise always
                 // rank below its declared weight).
@@ -98,12 +123,26 @@ function queryFields(searchType, locale) {
         }
         else {
             for (const name of search) {
-                names.push(name);
+                names.push(qualify(prefix, name));
                 weights.push(baseWeight);
             }
         }
     }
-    return { names, weights };
+    if (schema === undefined) {
+        return;
+    }
+    for (const field of searchType.fields) {
+        // An internal field is pruned before the writer and declared in no
+        // collection, so its target's companions exist nowhere – asking `query_by`
+        // for one makes the ENGINE reject every search on the collection.
+        if (isInternalField(field)) {
+            continue;
+        }
+        const nested = nestedReferenceType(schema, field) ?? localLookupTypeOf(field, schema);
+        if (nested !== undefined) {
+            collectSearchable(nested, locale, schema, qualify(prefix, field.name), walked, names, weights);
+        }
+    }
 }
 /** AND-join the compiled `where` clauses. A clause that states no constraint is
  *  skipped; one that can match nothing compiles to {@link MATCHES_NOTHING}
@@ -201,16 +240,31 @@ const UNUSABLE = Symbol('unusable');
 function compileCriterion(criterion, searchType, options) {
     const on = criterion.on ?? [];
     if (on.length === 0) {
-        return compileLeaf(criterion, searchType, options.schema);
+        return isWelded(criterion)
+            ? compileWelded(criterion, searchType, options.schema, '')
+            : compileLeaf(criterion, searchType, options.schema);
     }
+    // The path carries two kinds of hop, and they compile differently: a JOIN
+    // crosses into another collection and wraps the leaf in `$collection(…)`; a
+    // NESTING stays in this document and qualifies the leaf’s field name. The
+    // schema is what tells them apart, so without one every hop is read as a
+    // join – exactly the behaviour before nesting existed.
+    const resolvedPath = options.schema === undefined
+        ? undefined
+        : resolvePath(searchType, on, options.schema, joinGraph(options.schema));
+    if (typeof resolvedPath === 'string') {
+        return UNUSABLE;
+    }
+    const joinHops = resolvedPath?.joinPath ?? on;
+    const nestedHops = resolvedPath?.nestedPath ?? [];
     // A joined criterion constrains a document in ANOTHER collection, so the leaf
     // is compiled against the type that path reaches and then wrapped, one
     // `$collection(…)` per hop, outermost hop first:
     // `['dataset', 'publisher']` → `$datasets($publishers(id:=…))`.
     const collections = [];
     let target = searchType;
-    for (let hop = 1; hop <= on.length; hop++) {
-        const resolved = options.joinTargetFor?.(searchType, on.slice(0, hop));
+    for (let hop = 1; hop <= joinHops.length; hop++) {
+        const resolved = options.joinTargetFor?.(searchType, joinHops.slice(0, hop));
         if (resolved === undefined) {
             // An unresolvable path is a criterion that cannot be compiled at all –
             // false, so it drops out and its siblings still stand. Through the
@@ -220,7 +274,11 @@ function compileCriterion(criterion, searchType, options) {
         collections.push(resolved.collection);
         target = resolved.searchType;
     }
-    const leaf = compileLeaf(criterion, target, options.schema);
+    const leafType = resolvedPath?.leafType ?? target;
+    const prefix = nestedHops.join('.');
+    const leaf = isWelded(criterion)
+        ? compileWelded(criterion, leafType, options.schema, prefix)
+        : compileLeaf(criterion, leafType, options.schema, prefix);
     // 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.
@@ -229,9 +287,16 @@ function compileCriterion(criterion, searchType, options) {
     }
     return collections.reduceRight((inner, collection) => `$${collection}(${inner})`, leaf);
 }
-/** 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, schema) {
+/**
+ * The criterion’s own term, against the type it actually constrains – the
+ * searched type, the one its join path reaches, or the reference type its
+ * nesting path walks into.
+ *
+ * `prefix` is that nesting path, dotted: an engine addresses a stored nested
+ * document by qualifying the field name, so `role` inside `creator` becomes
+ * `creator.role`. Empty for every unnested criterion.
+ */
+function compileLeaf(criterion, searchType, schema, prefix = '') {
     // `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
@@ -239,7 +304,12 @@ function compileLeaf(criterion, searchType, schema) {
     // clause.) An empty identity membership enumerates NO document, so it is
     // unusable rather than vacuous – the one place the two readings diverge.
     if (criterion.field === ID_FIELD) {
-        return 'in' in criterion && criterion.in.length > 0
+        // `id` names the DOCUMENT key, which exists only at the top level: inside a
+        // nested reference there is no document to key. Compiling it under a prefix
+        // would filter the root collection's `id` instead – a different question,
+        // silently answered. `assertValidQuery` rejects it first; this is the guard
+        // for a hand-built query.
+        return prefix === '' && 'in' in criterion && criterion.in.length > 0
             ? `${ID_FIELD}:=[${criterion.in.map(escapeFilterValue).join(',')}]`
             : UNUSABLE;
     }
@@ -254,13 +324,57 @@ function compileLeaf(criterion, searchType, schema) {
     }
     if ('in' in criterion) {
         return criterion.in.length > 0
-            ? compileMembership(field, criterion.in, schema)
+            ? compileMembership(field, criterion.in, schema, prefix)
             : VACUOUS;
     }
     if ('range' in criterion) {
-        return compileRange(field, criterion.range) ?? VACUOUS;
+        return compileRange(field, criterion.range, prefix) ?? VACUOUS;
+    }
+    // Every other shape returned above; a welded criterion never reaches here
+    // (compileWelded handles it before the leaf compiler is called).
+    return `${qualify(prefix, field.name)}:=${criterion.is}`;
+}
+/** A field name under its nesting path, if any – the one place the dotted
+ *  addressing an engine uses for a stored nested document is spelled. */
+function qualify(prefix, name) {
+    return prefix === '' ? name : `${prefix}.${name}`;
+}
+/**
+ * A **welded** criterion: `path.{a && b}`, matching a document with ONE entry
+ * that satisfies every condition – as against `path.a && path.b`, which two
+ * different entries can satisfy between them.
+ *
+ * Each condition is compiled against the reference type with an EMPTY prefix,
+ * so what goes inside the braces is always a leaf name. That is a correctness
+ * requirement, not tidiness: Typesense 30.2 **hangs** on a dotted path inside a
+ * group (`creator.{creator.name:=…}` never returns – no error, no result), so
+ * the compiler must be structurally incapable of emitting one. A field whose
+ * value is itself nested is reached through its identity companion, which is a
+ * leaf ({@link physicalFields}).
+ *
+ * A condition that states no constraint drops out, and the weld is whatever
+ * remains; a weld left with nothing is vacuous like any other empty clause.
+ */
+function compileWelded(criterion, searchType, schema, prefix) {
+    const entryType = schema &&
+        nestedReferenceType(schema, fieldNamed(searchType, criterion.field) ?? {});
+    if (entryType === undefined) {
+        return UNUSABLE;
+    }
+    const conditions = [];
+    for (const condition of criterion.entry) {
+        const compiled = compileLeaf(condition, entryType, schema);
+        if (compiled === UNUSABLE) {
+            return UNUSABLE;
+        }
+        if (compiled !== VACUOUS) {
+            conditions.push(compiled);
+        }
+    }
+    if (conditions.length === 0) {
+        return VACUOUS;
     }
-    return `${field.name}:=${criterion.is}`;
+    return `${qualify(prefix, criterion.field)}.{${conditions.join(' && ')}}`;
 }
 /**
  * A membership clause. A non-facet (tokenized) field uses the exact `:=`
@@ -272,11 +386,15 @@ function compileLeaf(criterion, searchType, schema) {
  * filter on such a field is exactly what the policy promises stays whole, so
  * it must compile exact, not tokenized.
  */
-function compileMembership(field, values, schema) {
+function compileMembership(field, values, schema, prefix = '') {
     const list = `[${values.map(escapeFilterValue).join(',')}]`;
-    return physicalFields(field, schema).facet === field.name
-        ? `${field.name}:${list}`
-        : `${field.name}:=${list}`;
+    const names = physicalFields(field, schema);
+    // An inline reference stores a nested object, which an engine cannot filter.
+    // Its identity companion is the flat id field standing in for it – so the
+    // logical name a consumer writes and the physical name the engine reads
+    // differ here, and only here.
+    const name = qualify(prefix, names.identity ?? field.name);
+    return names.facet === name ? `${name}:${list}` : `${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
@@ -285,8 +403,8 @@ function compileMembership(field, values, schema) {
  *  from the conjunction widens it, so the same reading cannot be right in both
  *  positions. `validateQuery` rejects an unreadable bound outright instead,
  *  which is the only answer that neither widens nor narrows. */
-function compileRange(field, range) {
-    const name = field.name;
+function compileRange(field, range, prefix = '') {
+    const name = qualify(prefix, field.name);
     // A bound a caller sent as `null` – a GraphQL variable left unfilled, which
     // the surface passes through – is a bound NOT SET, not a bound of `null`.
     // Read literally it reaches the engine as `datePosted:[null..…]`, which

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"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, facetableFields, 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, labelTargetNameOf, localLookupTypeOf, 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';
@@ -68,9 +68,12 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
     const labelSources = new Map([...schema.values()].map((searchType) => [
         searchType.class,
         new Map(referenceFields(searchType)
-            .filter((field) => labelSourceNameOf(field) !== undefined)
+            // An INLINE reference names its label target one level in, through
+            // its identity companion: the companion holds that field's ids, so
+            // that field's target is what can label them.
+            .filter((field) => labelTargetNameOf(field, schema) !== undefined)
             .map((field) => {
-            const source = typesByName.get(labelSourceNameOf(field));
+            const source = typesByName.get(labelTargetNameOf(field, schema));
             const labelField = labelFieldOf(source);
             return [
                 field.name,
@@ -114,7 +117,18 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
         return [
             searchType.class,
             referenceFields(searchType)
-                .filter((field) => field.output === true && sources?.has(field.name))
+                .filter((field) => field.output === true &&
+                sources?.has(field.name) === true &&
+                // A field storing NESTED DOCUMENTS is excluded, and must be: this
+                // list drives the per-hit label lookup, which reads each stored
+                // value as an id. An inline reference and a `local` lookup store
+                // objects, so every entry would contribute the string
+                // `"[object Object]"` to the batched `id:[…]` filter. Neither
+                // needs entry labels anyway – the referent's own fields are in
+                // the entry – and their FACET buckets are labelled by a separate
+                // path that reads the companion.
+                nestedReferenceType(schema, field) === undefined &&
+                localLookupTypeOf(field, schema) === undefined)
                 .map((field) => ({
                 name: field.name,
                 source: sources.get(field.name),
@@ -538,7 +552,7 @@ export function parseSearchResponse(response, searchType, labels, schema, refere
     // reference facet stays id-only even when a cached full-collection map holds
     // its IRIs.
     const referenceFacets = new Set(referenceFields(searchType)
-        .filter((field) => labelSourceNameOf(field) !== undefined)
+        .filter((field) => labelTargetNameOf(field, schema) !== undefined)
         .map((field) => field.name));
     const facets = {};
     for (const facet of response.facet_counts ?? []) {
@@ -587,15 +601,25 @@ function logicalValue(flat, field, labels, schema, referents) {
             // reconstructs as a nested Search Document rather than as an IRI plus a
             // label. Nesting is rebuilt HERE, below every surface, so a second
             // surface inherits it instead of reimplementing it (ADR 11).
+            const resolved = referents?.get(field.name);
             const nested = nestedReferenceType(schema, field);
             if (nested !== undefined) {
-                return nestedValue(flat[field.name], field, nested, labels, schema);
+                // A nested level resolves nothing itself; what it carries are the
+                // levels below it, which the entries are reconstructed against.
+                return nestedValue(flat[field.name], field, nested, labels, schema, resolved?.children);
+            }
+            // Checked BEFORE the plain lookup below, because a `local` lookup
+            // resolves through the same kind of level while storing a different
+            // shape: its stored value is the endpoint's own document, not an id, so
+            // reading it as one would stringify the object into a bogus `id`.
+            const localType = localLookupTypeOf(field, schema);
+            if (localType !== undefined) {
+                return localLookupValue(flat[field.name], field, localType, resolved, labels, schema);
             }
             // A resolved lookup carries the referent's own fields, fetched from the
             // target's collection. It reconstructs through the SAME path a hit does,
             // so a consumer cannot tell a projected referent from an inline one.
-            const resolved = referents?.get(field.name);
-            if (resolved !== undefined) {
+            if (resolved !== undefined && resolved.via === 'lookup') {
                 return lookupValue(flat[field.name], field, resolved, labels, schema);
             }
             // A surfaced inline reference stores nested documents, not IRIs, so a
@@ -655,10 +679,10 @@ function localizedValue(flat, field) {
  * a nested document is read, not addressed. A nested reference type may itself
  * surface an inline reference, which recurses through {@link reconstructDocument}.
  */
-function nestedValue(raw, field, referenceType, labels, schema) {
+function nestedValue(raw, field, referenceType, labels, schema, children) {
     const referents = (Array.isArray(raw) ? raw : [raw]).filter((referent) => typeof referent === 'object' && referent !== null);
     const documents = referents.map((referent) => {
-        const document = reconstructDocument(referent, referenceType, labels, schema);
+        const document = reconstructDocument(referent, referenceType, labels, schema, children);
         return typeof referent.id === 'string'
             ? { id: referent.id, ...document }
             : document;
@@ -668,6 +692,34 @@ function nestedValue(raw, field, referenceType, labels, schema) {
     }
     return field.array === true ? documents : documents[0];
 }
+/**
+ * Rebuild a {@link ReferenceStrategy.local local} lookup: the endpoint’s own
+ * document as this document stated it, with the **resolved** document overlaid
+ * where the lookup found one.
+ *
+ * Both sides are the target type’s flat physical shape, so the merge is a plain
+ * override and the authoritative value wins field by field. Three cases fall
+ * out of one expression, which is the point of storing local fields
+ * unconditionally:
+ *
+ * - identified and indexed → the target’s own record, over what was stated here;
+ * - identified but not indexed → what was stated here, plus the `id`, rather
+ *   than a bare IRI;
+ * - not identified → what was stated here, with no `id` at all.
+ */
+function localLookupValue(raw, field, target, resolved, labels, schema) {
+    const fetched = resolved?.via === 'lookup' ? resolved.documents : new Map();
+    const merged = (Array.isArray(raw) ? raw : [raw])
+        .filter((entry) => typeof entry === 'object' && entry !== null)
+        .map((entry) => {
+        const id = typeof entry.id === 'string' ? entry.id : undefined;
+        const authoritative = id === undefined ? undefined : fetched.get(id);
+        return authoritative === undefined
+            ? entry
+            : { ...entry, ...authoritative };
+    });
+    return nestedValue(merged, field, target, labels, schema, resolved?.children);
+}
 /**
  * Rebuild a resolved `lookup` reference: each stored IRI becomes the referent’s
  * own document, read through the **target’s** declaration and carrying whatever

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.27.4",
+  "version": "0.28.0",
   "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,17 +25,17 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.23.2",
+    "@lde/search": "^0.24.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"
   },
   "devDependencies": {
-    "n3": "^2.1.2",
+    "n3": "^2.4.0",
     "testcontainers": "^12.1.0"
   },
   "peerDependencies": {
     "@lde/dataset": "^0.7.9",
-    "@lde/pipeline": "^0.36.3"
+    "@lde/pipeline": "^0.36.4"
   }
 }