@lde/search-typesense 0.27.4 → 0.29.0

package/dist/blue-green-rebuild.d.ts

@@ -19,11 +19,14 @@ export type BlueGreenRebuildOptions = RebuildOptions;
  *   creates the versioned collection (`${name}_<timestamp>`) with the schema
  *   derived from the {@link SearchType}.
  * - `write` streams documents into the fresh collection, batched across write
- *   calls, each stamped with its `source` (the dataset IRI).
+ *   calls, each recording the dataset it came from ({@link openDocuments}).
  * - `flush` on a **failed** dataset, and `reset` (the pipeline’s dump-fallback
- *   discard), roll that dataset’s documents back out of the not-yet-live
- *   collection by `source`, so a swap never ships a half-processed dataset;
- *   a successful flush leaves the streamed documents in place.
+ *   discard), roll that dataset back out of the not-yet-live collection, so a
+ *   swap never ships a half-processed dataset; a successful flush leaves the
+ *   streamed documents in place. On a canonically keyed collection the
+ *   rollback drops the failed dataset’s *membership*, so a document another
+ *   dataset also contributed stays – with a reference from that dataset that
+ *   still resolves.
  * - `commit` imports the remainder, atomically repoints the `name` alias to
  *   the new collection, drops the collection it superseded, and releases the
  *   lock. Until commit, the live alias never points at a partial build.
@@ -50,10 +53,6 @@ export declare class BlueGreenRebuild<TDocument extends {
      */
     readonly collectionName: string;
     private readonly resolved;
-    /** The column this collection carries its documents’ dataset IRI in: the
-     *  type’s declared dataset field, or the private `source` when it declares
-     *  none. Both the stamp and the per-dataset rollback filter read it. */
-    private readonly sourceField;
     constructor(client: Client, searchType: SearchType, options?: BlueGreenRebuildOptions);
     openRun(context: RunContext): Promise<RunWriter<TDocument>>;
     /** The collection an alias currently points at, or `undefined` if unset. */

package/dist/blue-green-rebuild.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blue-green-rebuild.d.ts","sourceRoot":"","sources":["../src/blue-green-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAUvB,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B;;yDAEyD;AACzD,MAAM,MAAM,uBAAuB,GAAG,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAgB,CAC3B,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;;;;;;;OAOG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD;;4EAEwE;IACxE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,uBAA4B;IAajC,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAwHjE,4EAA4E;YAC9D,WAAW;CAW1B"}
+{"version":3,"file":"blue-green-rebuild.d.ts","sourceRoot":"","sources":["../src/blue-green-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AASvB,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B;;yDAEyD;AACzD,MAAM,MAAM,uBAAuB,GAAG,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,gBAAgB,CAC3B,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAa1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAb7B;;;;;;;OAOG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAG/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,uBAA4B;IAUjC,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAsGjE,4EAA4E;YAC9D,WAAW;CAW1B"}

package/dist/blue-green-rebuild.js

@@ -1,8 +1,7 @@
 import { buildCollectionDefinition } from './collection-definition.js';
-import { BatchImporter } from './import.js';
 import { httpStatus, openLockedRun, releaseLock } from './lock.js';
-import { SOURCE_FIELD, provenanceField, sourceDocumentsFilter, } from './sweep.js';
-import { assertNoReservedFields, assertSweepableProvenanceField, deleteByFilter, resolveRebuildOptions, stampDocuments, } from './rebuild-support.js';
+import { assertWritableType, openDocuments, withBookkeeping, } from './documents.js';
+import { resolveRebuildOptions, } from './rebuild-support.js';
 /**
  * Blue/green Rebuild (build a fresh index alongside the live one, then swap to
  * it atomically) as a transactional `Writer`: each run builds the search
@@ -16,11 +15,14 @@ import { assertNoReservedFields, assertSweepableProvenanceField, deleteByFilter,
  *   creates the versioned collection (`${name}_<timestamp>`) with the schema
  *   derived from the {@link SearchType}.
  * - `write` streams documents into the fresh collection, batched across write
- *   calls, each stamped with its `source` (the dataset IRI).
+ *   calls, each recording the dataset it came from ({@link openDocuments}).
  * - `flush` on a **failed** dataset, and `reset` (the pipeline’s dump-fallback
- *   discard), roll that dataset’s documents back out of the not-yet-live
- *   collection by `source`, so a swap never ships a half-processed dataset;
- *   a successful flush leaves the streamed documents in place.
+ *   discard), roll that dataset back out of the not-yet-live collection, so a
+ *   swap never ships a half-processed dataset; a successful flush leaves the
+ *   streamed documents in place. On a canonically keyed collection the
+ *   rollback drops the failed dataset’s *membership*, so a document another
+ *   dataset also contributed stays – with a reference from that dataset that
+ *   still resolves.
  * - `commit` imports the remainder, atomically repoints the `name` alias to
  *   the new collection, drops the collection it superseded, and releases the
  *   lock. Until commit, the live alias never points at a partial build.
@@ -45,19 +47,12 @@ export class BlueGreenRebuild {
      */
     collectionName;
     resolved;
-    /** The column this collection carries its documents’ dataset IRI in: the
-     *  type’s declared dataset field, or the private `source` when it declares
-     *  none. Both the stamp and the per-dataset rollback filter read it. */
-    sourceField;
     constructor(client, searchType, options = {}) {
         this.client = client;
         this.searchType = searchType;
-        // `source` is stamped on every document for per-dataset rollback.
-        assertNoReservedFields(searchType, [SOURCE_FIELD]);
-        // Rollback filters by a known dataset IRI rather than enumerating the
-        // indexed ones, so a declared field need not be facetable here.
-        assertSweepableProvenanceField(searchType, { requireFacetable: false });
-        this.sourceField = provenanceField(searchType);
+        // Rollback drops a known dataset rather than enumerating the indexed ones,
+        // so a declared dataset field need not be facetable here.
+        assertWritableType(searchType, { requireFacetable: false });
         this.resolved = resolveRebuildOptions(searchType, options);
         this.collectionName =
             this.resolved.definitionOptions.collectionNameFor(searchType);
@@ -65,7 +60,6 @@ export class BlueGreenRebuild {
     async openRun(context) {
         const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
         const name = this.collectionName;
-        const sourceField = this.sourceField;
         return openLockedRun(this.client, name, lockTtlMs, async () => {
             // Create the fresh (blue) collection up front, so a failure surfaces
             // before any dataset is processed. startedAt orders the versioned names;
@@ -87,30 +81,22 @@ export class BlueGreenRebuild {
                 ...definitionOptions,
                 collectionNameFor: versioned,
             });
-            await this.client.collections().create({
-                ...definition,
-                // The private `source` only when the type declares no dataset field of
-                // its own; a declared one is already in the definition and carries the
-                // same IRI.
-                fields: [
-                    ...(definition.fields ?? []),
-                    ...(sourceField === SOURCE_FIELD
-                        ? [{ name: SOURCE_FIELD, type: 'string' }]
-                        : []),
-                ],
+            await this.client
+                .collections()
+                .create(withBookkeeping(definition, this.searchType));
+            const documents = openDocuments(this.client, collection, {
+                searchType: this.searchType,
+                runId: context.runId,
+                startedAt: context.startedAt,
+                batchSize,
             });
-            const importer = new BatchImporter(this.client, collection, batchSize);
-            // Drop a dataset’s streamed documents back out of the not-yet-live
-            // collection (a failed dataset, or a reset before the dump re-run). Any
-            // still buffered must land first, so the delete filter sees them.
-            const rollback = async (dataset) => {
-                await importer.flush();
-                await deleteByFilter(this.client, collection, sourceDocumentsFilter(sourceField, dataset.iri.toString()));
-            };
+            // Roll a dataset back out of the not-yet-live collection (a failed
+            // dataset, or a reset before the dump re-run). On a keyed collection
+            // that drops its membership rather than the documents themselves, so a
+            // dataset that succeeded keeps the ones it also contributed.
+            const rollback = async (dataset) => documents.dropAll(dataset);
             return {
-                write: async (dataset, documents) => importer.add(stampDocuments(documents, {
-                    [sourceField]: dataset.iri.toString(),
-                })),
+                write: async (dataset, items) => documents.add(dataset, items),
                 flush: async (dataset, outcome) => {
                     // A successful dataset keeps its streamed documents (they go live at
                     // the swap); a failed one is rolled back so the swap never ships it.
@@ -120,7 +106,7 @@ export class BlueGreenRebuild {
                 },
                 reset: async (dataset) => rollback(dataset),
                 commit: async () => {
-                    await importer.flush();
+                    await documents.flush();
                     // The alias swap is the commit point: once it lands the new
                     // collection is live. Everything after it is best-effort cleanup that
                     // must NOT fail the commit – a post-swap rejection would otherwise

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':