@lde/search-typesense 0.17.0 → 0.18.0

package/dist/collection-definition.d.ts

@@ -1,11 +1,20 @@
 import type { CollectionCreateSchema } from 'typesense';
-import { type SearchType } from '@lde/search';
+import { type SearchSchema, type SearchType } from '@lde/search';
 /** Deployment-specific options the generic field model does not carry. */
 export interface CollectionDefinitionOptions {
     /** The Typesense collection (or alias) name. Omit to derive it from the
      *  type’s `name` ({@link deriveCollectionName}); supply one to override that
      *  (an env prefix, a multi-tenant name, an existing collection). */
     readonly name?: string;
+    /**
+     * The Search Schema the type belongs to – required only when the type
+     * surfaces an inline reference, whose nested fields are declared from the
+     * {@link ReferenceType} the schema resolves. A type without one needs no
+     * schema, so a caller that declares no nesting passes none; a type that does
+     * fails here rather than building a collection that silently omits the
+     * nesting.
+     */
+    readonly schema?: SearchSchema;
     /** Snowball stemming locale for non-localized searchable fields (e.g. `en`).
      *  Unset, those fields are not stemmed – folding still applies – so no
      *  language is ever assumed. Localized text search fields always stem in
@@ -45,6 +54,14 @@ export interface CollectionDefinitionOptions {
  * {@link isInternalField Internal fields} (those declaring no role) are omitted
  * 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.
  */
 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,EAAoB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAQhE,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;wEAEoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CAexB"}
+{"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;AAWrB,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;wEAEoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CA0BxB"}

package/dist/collection-definition.js

@@ -1,4 +1,4 @@
-import { displayFieldPattern, isInternalField, physicalFields, } from '@lde/search/adapter';
+import { displayFieldPattern, isInlineReference, isInternalField, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
 import { deriveCollectionName } from './collection-name.js';
 /**
  * Build a Typesense collection definition from the unified {@link SearchType}, so
@@ -29,13 +29,26 @@ import { deriveCollectionName } from './collection-name.js';
  * {@link isInternalField Internal fields} (those declaring no role) are omitted
  * 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.
  */
 export function buildCollectionDefinition(searchType, options = {}) {
     const { defaultLocale } = options;
     const collection = {
         name: options.name ?? deriveCollectionName(searchType),
-        fields: searchType.fields.flatMap((field) => typesenseFields(field, defaultLocale, options.defaultSortingField)),
+        fields: searchType.fields.flatMap((field) => typesenseFields(searchType, field, defaultLocale, options.defaultSortingField, options.schema)),
     };
+    // Typesense rejects an `object`/`object[]` field unless nesting is enabled,
+    // so the flag is a consequence of the declaration – never a knob.
+    if (collection.fields?.some((field) => field.type.startsWith('object'))) {
+        collection.enable_nested_fields = true;
+    }
     if (options.defaultSortingField !== undefined) {
         collection.default_sorting_field = options.defaultSortingField;
     }
@@ -44,8 +57,24 @@ 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.
+ */
+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`.
+    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”.`);
+    }
+    return nested;
+}
 /** The physical Typesense fields one declaration produces. */
-function typesenseFields(field, defaultLocale, defaultSortingField) {
+function typesenseFields(searchType, field, defaultLocale, defaultSortingField, schema) {
     // An internal field (no role) is projected as a reading device for the
     // derives and pruned before the writer, so the collection stores nothing for
     // it: not stored, not indexed, no RAM. Same predicate the projection prunes
@@ -53,6 +82,10 @@ function typesenseFields(field, defaultLocale, defaultSortingField) {
     if (isInternalField(field)) {
         return [];
     }
+    const nested = nestedTypeOf(searchType, field, schema);
+    if (nested !== undefined) {
+        return nestedFields(field.name, field, nested, schema);
+    }
     const names = physicalFields(field);
     if (field.kind === 'text') {
         const locales = field.locales;
@@ -121,6 +154,59 @@ function typesenseFields(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).
+ *
+ * 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.
+ */
+function nestedFields(prefix, reference, referenceType, schema) {
+    const array = reference.array === true;
+    const fields = [
+        {
+            name: prefix,
+            type: array ? 'object[]' : 'object',
+            index: false,
+            optional: reference.required !== true,
+        },
+    ];
+    for (const field of referenceType.fields) {
+        if (isInternalField(field)) {
+            continue;
+        }
+        const nested = nestedReferenceType(schema, field);
+        if (nested !== undefined) {
+            fields.push(...nestedFields(nestedFieldName(prefix, field.name), field, nested, schema));
+            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;
+        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.
+            optional: true,
+        });
+    }
+    return fields;
+}
 /** 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. */
 function typesenseValueType(field) {

package/dist/rebuild-support.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from 'typesense';
 import type { SearchType } from '@lde/search';
-import type { CollectionDefinitionOptions } from './collection-definition.js';
+import { type CollectionDefinitionOptions } from './collection-definition.js';
 /**
  * The tuning knobs both rebuild writers share, on top of the collection-definition
  * options. Each writer may add its own (In-place adds `maxSweepableSources`).
@@ -29,7 +29,12 @@ export interface ResolvedRebuildOptions {
  * when the deployment supplies none.
  *
  * Writers resolve at construction rather than per run, so an underivable name
- * throws when the writer is built, not on the first rebuild.
+ * throws when the writer is built, not on the first rebuild. The collection
+ * definition is built here and discarded for the same reason: every way a
+ * declaration can fail to describe a collection – an unresolvable surfaced
+ * inline reference, whose nesting needs the schema – then fails at construction
+ * rather than inside the first run, after a lock is held and a whole extraction
+ * has been paid for.
  */
 export declare function resolveRebuildOptions(searchType: SearchType, options: RebuildOptions): ResolvedRebuildOptions;
 /**

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;AAC9C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAK9E;;;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;;6DAEyD;IACzD,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAcxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;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,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,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;;6DAEyD;IACzD,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAgBxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;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,3 +1,4 @@
+import { buildCollectionDefinition, } from './collection-definition.js';
 import { deriveCollectionName } from './collection-name.js';
 import { DEFAULT_LOCK_TTL_MS } from './lock.js';
 import { DEFAULT_BATCH_SIZE } from './import.js';
@@ -7,11 +8,16 @@ import { DEFAULT_BATCH_SIZE } from './import.js';
  * when the deployment supplies none.
  *
  * Writers resolve at construction rather than per run, so an underivable name
- * throws when the writer is built, not on the first rebuild.
+ * throws when the writer is built, not on the first rebuild. The collection
+ * definition is built here and discarded for the same reason: every way a
+ * declaration can fail to describe a collection – an unresolvable surfaced
+ * inline reference, whose nesting needs the schema – then fails at construction
+ * rather than inside the first run, after a lock is held and a whole extraction
+ * has been paid for.
  */
 export function resolveRebuildOptions(searchType, options) {
     const { batchSize = DEFAULT_BATCH_SIZE, lockTtlMs = DEFAULT_LOCK_TTL_MS, ...definitionOptions } = options;
-    return {
+    const resolved = {
         batchSize,
         lockTtlMs,
         definitionOptions: {
@@ -19,6 +25,8 @@ export function resolveRebuildOptions(searchType, options) {
             name: definitionOptions.name ?? deriveCollectionName(searchType),
         },
     };
+    buildCollectionDefinition(searchType, resolved.definitionOptions);
+    return resolved;
 }
 /**
  * Reject a {@link SearchType} that declares any of the bookkeeping field names

package/dist/search.d.ts

@@ -118,8 +118,14 @@ export interface TypesenseSearchResponse {
  * Reconstruct a Typesense response into the engine-neutral {@link SearchResult}:
  * the flat, fanned-out document is turned back into a logical one (per-locale
  * display fields → a language map, reference IRIs → labelled references via the
- * label-source lookup, scalars passed through). `labels` maps a reference IRI
- * to its resolved label; an IRI absent from it yields an id-only reference.
+ * label-source lookup, nested objects → nested Search Documents, scalars passed
+ * through). `labels` maps a reference IRI to its resolved label; an IRI absent
+ * from it yields an id-only reference. `schema` resolves the Reference Type a
+ * surfaced inline reference nests – required, not optional: reconstruction is a
+ * function of the whole schema exactly as the engine is, and a caller that
+ * omitted it would silently serve nothing for every nested field. A schema that
+ * does not declare a field’s reference type reconstructs nothing for it rather
+ * than the wrong shape, the same call the projection makes.
  */
-export declare function parseSearchResponse(response: TypesenseSearchResponse, searchType: SearchType, labels: ReadonlyMap<string, LocalizedValue>): SearchResult;
+export declare function parseSearchResponse(response: TypesenseSearchResponse, searchType: SearchType, labels: ReadonlyMap<string, LocalizedValue>, schema: SearchSchema): SearchResult;
 //# sourceMappingURL=search.d.ts.map

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, fieldNamed, isRangeFacet, isUnsatisfiable, labelFieldOf, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, labelFieldOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
 /**
@@ -192,7 +192,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // the URL.
             const response = await performSingleSearch(client, collections.get(searchType.class), params);
             const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
-            return parseSearchResponse(response, searchType, labels);
+            return parseSearchResponse(response, searchType, labels, schema);
         },
         async searchFacets(searchType, queries) {
             assertTypeInSchema(schema, searchType);
@@ -243,7 +243,8 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
                             error: new Error(`Typesense facet search for “${queries[index].facets.join('”, “')}” failed${result?.code !== undefined ? ` (${result.code})` : ''}: ${result?.error ?? 'no result entry'}`),
                         }
                         : {
-                            facets: parseSearchResponse(result, searchType, labels).facets,
+                            facets: parseSearchResponse(result, searchType, labels, schema)
+                                .facets,
                         };
             });
             return outcomes;
@@ -453,13 +454,19 @@ function mergeLabels(maps) {
  * Reconstruct a Typesense response into the engine-neutral {@link SearchResult}:
  * the flat, fanned-out document is turned back into a logical one (per-locale
  * display fields → a language map, reference IRIs → labelled references via the
- * label-source lookup, scalars passed through). `labels` maps a reference IRI
- * to its resolved label; an IRI absent from it yields an id-only reference.
+ * label-source lookup, nested objects → nested Search Documents, scalars passed
+ * through). `labels` maps a reference IRI to its resolved label; an IRI absent
+ * from it yields an id-only reference. `schema` resolves the Reference Type a
+ * surfaced inline reference nests – required, not optional: reconstruction is a
+ * function of the whole schema exactly as the engine is, and a caller that
+ * omitted it would silently serve nothing for every nested field. A schema that
+ * does not declare a field’s reference type reconstructs nothing for it rather
+ * than the wrong shape, the same call the projection makes.
  */
-export function parseSearchResponse(response, searchType, labels) {
+export function parseSearchResponse(response, searchType, labels, schema) {
     const hits = (response.hits ?? []).map((hit) => ({
         id: String(hit.document.id),
-        document: reconstructDocument(hit.document, searchType, labels),
+        document: reconstructDocument(hit.document, searchType, labels, schema),
     }));
     // Reference facets are IRI-keyed; their buckets carry a resolved data label.
     // Plain facets (tokens, free strings) carry no label – the consumer owns display.
@@ -493,22 +500,40 @@ export function parseSearchResponse(response, searchType, labels) {
     return { hits, total: response.found, facets };
 }
 /** Rebuild one logical document from a flat Typesense document. */
-function reconstructDocument(flat, searchType, labels) {
+function reconstructDocument(flat, searchType, labels, schema) {
     const document = {};
     for (const field of outputFields(searchType)) {
-        const value = logicalValue(flat, field, labels);
+        const value = logicalValue(flat, field, labels, schema);
         if (value !== undefined) {
             document[field.name] = value;
         }
     }
     return document;
 }
-function logicalValue(flat, field, labels) {
+function logicalValue(flat, field, labels, schema) {
     switch (field.kind) {
         case 'text':
             return localizedValue(flat, field);
-        case 'reference':
-            return referenceValue(flat, field, labels);
+        case 'reference': {
+            // A surfaced inline reference carries its referent’s own fields, so it
+            // 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 nested = nestedReferenceType(schema, field);
+            if (nested !== undefined) {
+                return nestedValue(flat[field.name], field, nested, labels, schema);
+            }
+            // A surfaced inline reference stores nested documents, not IRIs, so a
+            // schema that does not declare its reference type (a type parsed against
+            // a foreign schema) reconstructs nothing rather than the wrong shape –
+            // the same call the projection makes. Only output fields are
+            // reconstructed, and `searchSchema` allows an inline reference no Role
+            // but `output`, so every inline reference reaching this point is a
+            // surfaced one.
+            return isInlineReference(field)
+                ? undefined
+                : referenceValue(flat, field, labels);
+        }
         case 'keyword': {
             const value = flat[field.name];
             return Array.isArray(value) || typeof value === 'string'
@@ -546,6 +571,28 @@ function localizedValue(flat, field) {
     }
     return Object.keys(map).length > 0 ? map : undefined;
 }
+/**
+ * Rebuild a surfaced inline reference from the nested object(s) the engine
+ * stored: one {@link NestedDocument} per referent, each carrying its Reference
+ * Type’s own output fields – so a multi-valued reference keeps every referent’s
+ * values grouped rather than smeared across parallel arrays. `id` is carried
+ * only when the referent had one; a blank-node referent nests without it, since
+ * 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) {
+    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);
+        return typeof referent.id === 'string'
+            ? { id: referent.id, ...document }
+            : document;
+    });
+    if (documents.length === 0) {
+        return undefined;
+    }
+    return field.array === true ? documents : documents[0];
+}
 /** Map stored reference IRIs to labelled references; id-only when no label. */
 function referenceValue(flat, field, labels) {
     const raw = flat[field.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.17.0",
+  "version": "0.18.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,7 +25,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.14.0",
+    "@lde/search": "^0.15.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"