@lde/search-typesense 0.36.1 → 0.38.0

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

@@ -20,6 +20,9 @@ export type BlueGreenRebuildOptions = RebuildOptions;
  *   derived from the {@link SearchType}.
  * - `write` streams documents into the fresh collection, batched across write
  *   calls, each recording the dataset it came from ({@link openDocuments}).
+ * - `write` leaves out a document Typesense refuses or that lacks a required
+ *   field; `flush` reports those through {@link RunContext.itemsRejected} and
+ *   fails the dataset when they exceed `maxRejectedShare`.
  * - `flush` on a **failed** dataset, and `reset` (the pipeline’s dump-fallback
  *   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

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;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"}
+{"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,EAGL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B;;yDAEyD;AACzD,MAAM,MAAM,uBAAuB,GAAG,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;IA2HjE,4EAA4E;YAC9D,WAAW;CAW1B"}

package/dist/blue-green-rebuild.js

@@ -1,7 +1,7 @@
 import { buildCollectionDefinition } from './collection-definition.js';
 import { httpStatus, openLockedRun, releaseLock } from './lock.js';
 import { assertWritableType, openDocuments, withBookkeeping, } from './documents.js';
-import { resolveRebuildOptions, } from './rebuild-support.js';
+import { resolveRebuildOptions, settleDataset, } 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,6 +16,9 @@ import { resolveRebuildOptions, } from './rebuild-support.js';
  *   derived from the {@link SearchType}.
  * - `write` streams documents into the fresh collection, batched across write
  *   calls, each recording the dataset it came from ({@link openDocuments}).
+ * - `write` leaves out a document Typesense refuses or that lacks a required
+ *   field; `flush` reports those through {@link RunContext.itemsRejected} and
+ *   fails the dataset when they exceed `maxRejectedShare`.
  * - `flush` on a **failed** dataset, and `reset` (the pipeline’s dump-fallback
  *   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
@@ -58,7 +61,7 @@ export class BlueGreenRebuild {
             this.resolved.definitionOptions.collectionNameFor(searchType);
     }
     async openRun(context) {
-        const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
+        const { batchSize, lockTtlMs, maxRejectedShare, definitionOptions } = this.resolved;
         const name = this.collectionName;
         return openLockedRun(this.client, name, lockTtlMs, async () => {
             // Create the fresh (blue) collection up front, so a failure surfaces
@@ -89,6 +92,7 @@ export class BlueGreenRebuild {
                 runId: context.runId,
                 startedAt: context.startedAt,
                 batchSize,
+                schema: definitionOptions.schema,
             });
             // 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
@@ -99,12 +103,25 @@ export class BlueGreenRebuild {
                 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.
+                    // the swap); a failed one – or one that left too much out – is
+                    // rolled back so the swap never ships it.
+                    try {
+                        await settleDataset(documents, dataset, outcome, context, this.searchType, maxRejectedShare);
+                    }
+                    catch (error) {
+                        await rollback(dataset);
+                        throw error;
+                    }
                     if (outcome !== 'success') {
                         await rollback(dataset);
                     }
                 },
-                reset: async (dataset) => rollback(dataset),
+                reset: async (dataset) => {
+                    // The re-run writes the dataset afresh, so what this attempt left
+                    // out is no longer the dataset’s to answer for.
+                    await documents.settle(dataset);
+                    await rollback(dataset);
+                },
                 commit: async () => {
                     await documents.flush();
                     // The alias swap is the commit point: once it lands the new

package/dist/documents.d.ts

@@ -1,6 +1,7 @@
 import type { Client, CollectionCreateSchema } from 'typesense';
 import type { CollectionFieldSchema } from 'typesense/lib/Typesense/Collection.js';
 import type { Dataset } from '@lde/dataset';
+import type { ItemsRejected } from '@lde/pipeline';
 import type { SearchSchema, SearchType } from '@lde/search';
 /**
  * Default ceiling on the distinct datasets a collection may hold before the
@@ -19,6 +20,9 @@ export interface RunDocumentsOptions {
     readonly startedAt: string;
     /** Documents per Typesense import request. */
     readonly batchSize: number;
+    /** The schema the type belongs to, which a required field of an inline
+     *  reference’s referent is declared in. */
+    readonly schema?: SearchSchema;
     /** Most distinct datasets {@link RunDocuments.dropUnselected} may enumerate
      *  before it throws rather than risk missing one that left. */
     readonly maxSweepableSources?: number;
@@ -36,10 +40,21 @@ export interface RunDocumentsOptions {
 export interface RunDocuments<TDocument extends {
     id: string;
 }> {
-    /** Write a dataset’s documents, batched. */
+    /**
+     * Write a dataset’s documents, batched. A document Typesense refuses, or
+     * that lacks a required field Typesense cannot check
+     * ({@link missingRequiredFields}), is left out and counted against its
+     * dataset rather than failing the write – see {@link settle}.
+     */
     add(dataset: Dataset, documents: AsyncIterable<TDocument>): Promise<void>;
     /** Land whatever is still buffered. */
     flush(): Promise<void>;
+    /**
+     * Land whatever is still buffered and account for the dataset’s documents
+     * since it was last settled: how many it wrote, and which were left out and
+     * why. Starts the dataset’s count afresh.
+     */
+    settle(dataset: Dataset): Promise<DatasetWrites>;
     /**
      * Drop what this dataset had and this run did not rewrite – the sweep after
      * a dataset succeeds. A document another dataset still references survives,
@@ -63,6 +78,9 @@ export interface RunDocuments<TDocument extends {
      */
     dropUnselected(selectedDatasets: Iterable<string>): Promise<void>;
 }
+/** A dataset’s documents in one collection, as {@link RunDocuments.settle}
+ *  counts them. */
+export type DatasetWrites = Omit<ItemsRejected, 'target'>;
 /**
  * Open a run’s documents on a collection.
  *

package/dist/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAY,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAmCtE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;qCACiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;mEAC+D;IAC/D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE;IAC5D,4CAA4C;IAC5C,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,uCAAuC;IACvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,yEAAyE;IACzE,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,cAAc,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAC5D,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CAAC,SAAS,CAAC,CAIzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,sBAAsB,EAClC,UAAU,EAAE,UAAU,GACrB,sBAAsB,CA4BxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;IACP,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC,GACA,IAAI,CAoDN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,qBAAqB,EAAE,EAC1C,UAAU,EAAE,MAAM,GACjB,IAAI,CAWN"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAY,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2CtE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;qCACiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;+CAC2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;mEAC+D;IAC/D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE;IAC5D;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,uCAAuC;IACvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,yEAAyE;IACzE,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,cAAc,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED;mBACmB;AACnB,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAC5D,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CAAC,SAAS,CAAC,CAIzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,sBAAsB,EAClC,UAAU,EAAE,UAAU,GACrB,sBAAsB,CA4BxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;IACP,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC,GACA,IAAI,CAoDN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,qBAAqB,EAAE,EAC1C,UAAU,EAAE,MAAM,GACjB,IAAI,CAWN"}

package/dist/documents.js

@@ -3,7 +3,7 @@
 // and the two regimes a collection can be in – a document belongs to one
 // dataset, or several reference it – so a writer states *what* should go and
 // never *how* it is stored.
-import { datasetField, isInternalField, physicalFields, } from '@lde/search/adapter';
+import { datasetField, isInternalField, missingRequiredFields, physicalFields, } from '@lde/search/adapter';
 import { escapeFilterValue } from './query-compiler.js';
 /** The private field carrying the dataset IRI a document came from, in a
  *  collection whose documents each belong to one dataset. */
@@ -25,6 +25,11 @@ const LOOKUP_BATCH = 200;
 const MAX_SEARCHES_PER_REQUEST = 50;
 /** Stay well under Typesense’s ~4000-char URL query-string limit per delete. */
 const MAX_FILTER_VALUES_LENGTH = 3000;
+/** Distinct rejection reasons kept per dataset; the rest are counted under
+ *  one, so a reason that varies per document cannot grow the tally unbounded. */
+const MAX_REJECTION_REASONS = 10;
+/** Ids kept per rejection reason, as examples to look up. */
+const MAX_REJECTION_EXAMPLES = 3;
 /**
  * Default ceiling on the distinct datasets a collection may hold before the
  * membership sweep refuses to guess. The sweep needs the complete set to spot
@@ -204,13 +209,21 @@ function ownedDocuments(client, collection, options) {
     const { searchType, runId, batchSize } = options;
     const field = provenanceFieldOf(searchType);
     const buffer = new Batch(batchSize);
+    const writes = new WriteTally();
     const run = escapeFilterValue(runId);
     const of = (dataset) => `${field}:=${escapeFilterValue(dataset.iri.toString())}`;
     const land = async () => {
         const batch = buffer.take();
-        if (batch.length > 0) {
-            await importDocuments(client, collection, batch, 'upsert');
+        if (batch.length === 0) {
+            return;
         }
+        const errors = await upsertDocuments(client, collection, batch);
+        errors.forEach((error, index) => {
+            if (error !== undefined) {
+                const document = batch[index];
+                writes.reject(String(document[field]), String(document.id), error);
+            }
+        });
     };
     const drop = async (filter) => {
         await land();
@@ -230,18 +243,25 @@ function ownedDocuments(client, collection, options) {
         // unprojected is sweepable but not full-text findable by dataset: absent,
         // never wrong.
         add: async (dataset, documents) => {
+            const iri = dataset.iri.toString();
             const stamp = {
-                [field]: dataset.iri.toString(),
+                [field]: iri,
                 [LAST_SEEN_FIELD]: runId,
             };
             for await (const document of documents) {
-                buffer.push({ ...document, ...stamp });
-                if (buffer.full()) {
-                    await land();
+                if (writes.admit(iri, document, searchType, options.schema)) {
+                    buffer.push({ ...document, ...stamp });
+                    if (buffer.full()) {
+                        await land();
+                    }
                 }
             }
         },
         flush: land,
+        settle: async (dataset) => {
+            await land();
+            return writes.take(dataset.iri.toString());
+        },
         dropUnwritten: async (dataset) => drop(`${of(dataset)} && ${LAST_SEEN_FIELD}:!=${run}`),
         dropWrittenThisRun: async (dataset) => drop(`${of(dataset)} && ${LAST_SEEN_FIELD}:=${run}`),
         dropAll: async (dataset) => drop(of(dataset)),
@@ -261,7 +281,8 @@ function ownedDocuments(client, collection, options) {
  * referencing.
  */
 function sharedDocuments(client, collection, options) {
-    const { batchSize } = options;
+    const { searchType, batchSize } = options;
+    const writes = new WriteTally();
     const run = Date.parse(options.startedAt);
     const facet = `${REFERENCED_BY_FIELD}.dataset`;
     const buffer = new Batch(batchSize);
@@ -280,6 +301,8 @@ function sharedDocuments(client, collection, options) {
         // Two nodes of one dataset, or two datasets, can key onto one document
         // within a single batch. Later content wins, as a merged document always
         // does – but membership is the union, or the second would erase the first.
+        // `writes` keeps every dataset a write came from, repeats included, so a
+        // refusal counts once per document the datasets wrote – as `admit` did.
         const merged = new Map();
         for (const { document, dataset } of batch) {
             const seen = merged.get(document.id);
@@ -290,18 +313,29 @@ function sharedDocuments(client, collection, options) {
                     : seen.datasets.includes(dataset)
                         ? seen.datasets
                         : [...seen.datasets, dataset],
+                writes: [...(seen?.writes ?? []), dataset],
             });
         }
         const stored = await storedMembership(client, collection, [
             ...merged.keys(),
         ]);
-        await importDocuments(client, collection, [...merged.values()].map(({ document, datasets }) => ({
+        const entries = [...merged.values()];
+        const errors = await upsertDocuments(client, collection, entries.map(({ document, datasets }) => ({
             ...document,
             [REFERENCED_BY_FIELD]: [
                 ...(stored.get(document.id) ?? []).filter((referrer) => !datasets.includes(referrer.dataset)),
                 ...datasets.map((dataset) => ({ dataset, run })),
             ],
-        })), 'upsert');
+        })));
+        // A refused document is refused for every write merged into it.
+        errors.forEach((error, index) => {
+            if (error !== undefined) {
+                const { document, writes: merges } = entries[index];
+                for (const dataset of merges) {
+                    writes.reject(dataset, document.id, error);
+                }
+            }
+        });
     };
     /**
      * Take the datasets out of every document the filter selects, deleting the
@@ -349,7 +383,7 @@ function sharedDocuments(client, collection, options) {
                 throw new Error(`Retracting ${datasets.join(', ')} from “${collection}” selected ${hits.length} document(s) carrying none of them, so the sweep cannot make progress.`);
             }
             if (keeping.length > 0) {
-                await importDocuments(client, collection, keeping, 'update');
+                await updateDocuments(client, collection, keeping);
             }
             for (const chunk of chunked(emptied.map(escapeFilterValue))) {
                 await deleteByFilter(client, collection, `id:=[${chunk.join(',')}]`);
@@ -360,13 +394,19 @@ function sharedDocuments(client, collection, options) {
         add: async (dataset, documents) => {
             const iri = dataset.iri.toString();
             for await (const document of documents) {
-                buffer.push({ document, dataset: iri });
-                if (buffer.full()) {
-                    await land();
+                if (writes.admit(iri, document, searchType, options.schema)) {
+                    buffer.push({ document, dataset: iri });
+                    if (buffer.full()) {
+                        await land();
+                    }
                 }
             }
         },
         flush: land,
+        settle: async (dataset) => {
+            await land();
+            return writes.take(dataset.iri.toString());
+        },
         dropUnwritten: async (dataset) => {
             const iri = dataset.iri.toString();
             await retract(`${REFERENCED_BY_FIELD}.{dataset:=${escapeFilterValue(iri)} && run:<${run}}`, [iri]);
@@ -494,24 +534,106 @@ class Batch {
     }
 }
 /**
- * Import one batch, throwing if any individual document fails – Typesense’s
- * bulk import otherwise reports per-document failures without rejecting, which
- * would turn a rejected write into silently missing data.
+ * Each dataset’s documents since it was last settled: how many it wrote, and
+ * which were left out and why. Bounded per dataset by
+ * {@link MAX_REJECTION_REASONS} and {@link MAX_REJECTION_EXAMPLES}, however
+ * many documents are rejected.
+ */
+class WriteTally {
+    datasets = new Map();
+    /**
+     * Count a document the dataset wrote, answering whether it may be imported:
+     * one lacking a required field is rejected here, before Typesense sees it.
+     */
+    admit(dataset, document, searchType, schema) {
+        this.of(dataset).written += 1;
+        const missing = missingRequiredFields(document, searchType, schema);
+        if (missing.length === 0) {
+            return true;
+        }
+        this.reject(dataset, document.id, `missing required ${missing.length === 1 ? 'field' : 'fields'} ${missing
+            .map((name) => `“${name}”`)
+            .join(', ')}`);
+        return false;
+    }
+    /** Count a document of the dataset as left out, for `reason`. */
+    reject(dataset, id, reason) {
+        const tally = this.of(dataset);
+        tally.rejected += 1;
+        const key = tally.reasons.has(reason) || tally.reasons.size < MAX_REJECTION_REASONS
+            ? reason
+            : 'other reasons';
+        const entry = tally.reasons.get(key) ?? { count: 0, examples: [] };
+        entry.count += 1;
+        if (entry.examples.length < MAX_REJECTION_EXAMPLES) {
+            entry.examples.push(id);
+        }
+        tally.reasons.set(key, entry);
+    }
+    /** The dataset’s count, most frequent reason first, starting it afresh. */
+    take(dataset) {
+        const tally = this.datasets.get(dataset);
+        this.datasets.delete(dataset);
+        const reasons = [...(tally?.reasons ?? [])]
+            .map(([reason, { count, examples }]) => ({ reason, count, examples }))
+            .sort((left, right) => right.count - left.count);
+        return {
+            written: tally?.written ?? 0,
+            rejected: tally?.rejected ?? 0,
+            reasons,
+        };
+    }
+    of(dataset) {
+        let tally = this.datasets.get(dataset);
+        if (tally === undefined) {
+            tally = { written: 0, rejected: 0, reasons: new Map() };
+            this.datasets.set(dataset, tally);
+        }
+        return tally;
+    }
+}
+/**
+ * Upsert one batch, answering each document Typesense refused with its error –
+ * `undefined` for one written – in batch order. Typesense writes the valid
+ * documents of a batch and reports the rest per document without rejecting,
+ * so a caller that ignored the answer would turn a refusal into silently
+ * missing data.
+ *
+ * Only a client error (4xx) refuses the document itself. Any other failure –
+ * the engine out of memory or disk, not ready – says nothing about the data,
+ * so it throws: counted as a rejection, it would let a dataset succeed short
+ * of documents, and an In-place sweep then delete their indexed versions.
  */
-async function importDocuments(client, collection, batch, action) {
-    const results = (await client
+async function upsertDocuments(client, collection, batch) {
+    const results = await importBatch(client, collection, batch, 'upsert');
+    const failed = results.find((result) => !result.success && !(result.code >= 400 && result.code < 500));
+    if (failed !== undefined && !failed.success) {
+        throw new Error(`Typesense upsert into “${collection}” failed: ${failed.error} (HTTP ${failed.code})`);
+    }
+    return results.map((result) => (result.success ? undefined : result.error));
+}
+/**
+ * Update one batch, throwing if any document fails. An update only rewrites
+ * bookkeeping on documents already stored, so a refusal means broken
+ * bookkeeping, not bad source data, and must not be skipped.
+ */
+async function updateDocuments(client, collection, batch) {
+    const results = await importBatch(client, collection, batch, 'update');
+    const failures = results.flatMap((result) => result.success ? [] : [result.error]);
+    if (failures.length > 0) {
+        throw new Error(`Typesense update into “${collection}” failed for ${failures.length}/${results.length} documents: ${failures.join('; ')}`);
+    }
+}
+/** Import one batch, answering Typesense’s result per document in batch
+ *  order. */
+async function importBatch(client, collection, batch, action) {
+    return (await client
         .collections(collection)
         .documents()
         .import(batch, {
         action,
         throwOnFail: false,
     }));
-    const failures = results.filter((result) => !result.success);
-    if (failures.length > 0) {
-        throw new Error(`Typesense ${action} into “${collection}” failed for ${failures.length}/${results.length} documents: ${failures
-            .map((failure) => failure.error)
-            .join('; ')}`);
-    }
 }
 /** A whole-collection search; `q: '*'` needs no field to query by. */
 async function search(client, collection, parameters) {

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

@@ -25,6 +25,10 @@ export interface InPlaceRebuildOptions extends RebuildOptions {
  * document several datasets share, and the document itself only with the last
  * of them:
  *
+ * - a document Typesense refuses or that lacks a required field is left out
+ *   of the write; the dataset’s **flush** reports those through
+ *   {@link RunContext.itemsRejected} and fails the dataset, unswept, when they
+ *   exceed `maxRejectedShare`;
  * - a **successful dataset flush** drops what the dataset had and this run did
  *   not rewrite. A failed dataset is not swept – its output is incomplete, and
  *   the next successful run reconciles;

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

@@ -1 +1 @@
-{"version":3,"file":"in-place-rebuild.d.ts","sourceRoot":"","sources":["../src/in-place-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AASvB,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B;gCACgC;AAChC,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAc,CACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAY1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZ7B;;;;;OAKG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAG/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,qBAA0B;IAe/B,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;CAuElE"}
+{"version":3,"file":"in-place-rebuild.d.ts","sourceRoot":"","sources":["../src/in-place-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AASvB,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B;gCACgC;AAChC,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,cAAc,CACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAY1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZ7B;;;;;OAKG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAG/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,qBAA0B;IAe/B,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;CAqFlE"}

package/dist/in-place-rebuild.js

@@ -2,7 +2,7 @@ import { facetableFields, physicalFields } from '@lde/search/adapter';
 import { buildCollectionDefinition } from './collection-definition.js';
 import { ensureCollectionExists, openLockedRun, releaseLock } from './lock.js';
 import { assertBookkeepingPresent, assertWritableType, openDocuments, withBookkeeping, } from './documents.js';
-import { resolveRebuildOptions, } from './rebuild-support.js';
+import { resolveRebuildOptions, settleDataset, } from './rebuild-support.js';
 /**
  * In-place Rebuild (update the live index directly – upsert changed sources,
  * sweep the rest – rather than swap in a fresh one) as a transactional
@@ -13,6 +13,10 @@ import { resolveRebuildOptions, } from './rebuild-support.js';
  * document several datasets share, and the document itself only with the last
  * of them:
  *
+ * - a document Typesense refuses or that lacks a required field is left out
+ *   of the write; the dataset’s **flush** reports those through
+ *   {@link RunContext.itemsRejected} and fails the dataset, unswept, when they
+ *   exceed `maxRejectedShare`;
  * - a **successful dataset flush** drops what the dataset had and this run did
  *   not rewrite. A failed dataset is not swept – its output is incomplete, and
  *   the next successful run reconciles;
@@ -70,7 +74,7 @@ export class InPlaceRebuild {
             this.resolved.definitionOptions.collectionNameFor(searchType);
     }
     async openRun(context) {
-        const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
+        const { batchSize, lockTtlMs, maxRejectedShare, definitionOptions } = this.resolved;
         const name = this.collectionName;
         return openLockedRun(this.client, name, lockTtlMs, async () => {
             // Create the collection on demand: the SearchType’s schema plus whatever
@@ -92,24 +96,31 @@ export class InPlaceRebuild {
                 runId: context.runId,
                 startedAt: context.startedAt,
                 batchSize,
+                schema: definitionOptions.schema,
                 maxSweepableSources: this.maxSweepableSources,
             });
             return {
                 write: async (dataset, items) => documents.add(dataset, items),
                 flush: async (dataset, outcome) => {
+                    // A dataset that left too much out fails here, unswept like any
+                    // other failed dataset.
+                    await settleDataset(documents, dataset, outcome, context, this.searchType, maxRejectedShare);
                     if (outcome !== 'success') {
                         // A failed dataset’s output is incomplete: sweeping against it
                         // would delete documents the run never got to rewrite. Leave the
-                        // stale ones for the next successful run to reconcile. The buffered
-                        // documents stay buffered; the next flush lands them.
+                        // stale ones for the next successful run to reconcile.
                         return;
                     }
                     await documents.dropUnwritten(dataset);
                 },
                 // Discard only this run’s partial writes for the dataset (the failed
                 // endpoint attempt) so the dump re-run rebuilds it cleanly; the
-                // dataset’s prior-run documents stay for the success sweep.
-                reset: async (dataset) => documents.dropWrittenThisRun(dataset),
+                // dataset’s prior-run documents stay for the success sweep. What the
+                // attempt left out is no longer the dataset’s to answer for.
+                reset: async (dataset) => {
+                    await documents.settle(dataset);
+                    await documents.dropWrittenThisRun(dataset);
+                },
                 commit: async () => {
                     await documents.flush();
                     await documents.dropUnselected(context.selectedSources());

package/dist/rebuild-support.d.ts

@@ -1,5 +1,8 @@
+import type { Dataset } from '@lde/dataset';
+import type { DatasetOutcome, RunContext } from '@lde/pipeline';
 import type { SearchType } from '@lde/search';
 import { type CollectionDefinitionOptions } from './collection-definition.js';
+import type { RunDocuments } from './documents.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`).
@@ -9,12 +12,22 @@ export interface RebuildOptions extends CollectionDefinitionOptions {
     readonly batchSize?: number;
     /** A held lock older than this (ms) is reclaimed (default 10 minutes). */
     readonly lockTtlMs?: number;
+    /**
+     * The largest share of a dataset’s documents, from 0 to 1, this collection
+     * may leave out before the dataset fails (default 0.5). A document is left
+     * out when Typesense refuses it or it lacks a required field, and reported
+     * through {@link RunContext.itemsRejected} either way. A dataset whose every
+     * document was left out always fails, so it cannot go live empty; `0` fails
+     * a dataset on its first rejection.
+     */
+    readonly maxRejectedShare?: number;
 }
 /** The shared options resolved to concrete values plus the residual
  *  collection-definition options a writer passes to {@link buildCollectionDefinition}. */
 export interface ResolvedRebuildOptions {
     readonly batchSize: number;
     readonly lockTtlMs: number;
+    readonly maxRejectedShare: number;
     /** The collection-definition options with `collectionNameFor` resolved to a
      *  total function – the one place the naming convention lives, so the
      *  collection a writer talks to, the definition it creates and the peer
@@ -38,4 +51,19 @@ export interface ResolvedRebuildOptions {
  * been paid for.
  */
 export declare function resolveRebuildOptions(searchType: SearchType, options: RebuildOptions): ResolvedRebuildOptions;
+/**
+ * Finish a dataset’s writes to one collection: land them, report what was
+ * left out ({@link RunContext.itemsRejected}), and fail an otherwise
+ * successful dataset when more was left out than `maxRejectedShare` allows –
+ * or all of it. A dataset that already failed is only reported: its output is
+ * incomplete, so its share says nothing, and failing it twice would blame the
+ * data for what a stage did.
+ *
+ * Both writers settle at the dataset’s flush rather than leave its last
+ * partial batch for the next dataset’s writes to land, so a rejection is
+ * always counted, reported and judged against the dataset it belongs to.
+ */
+export declare function settleDataset(documents: RunDocuments<{
+    id: string;
+}>, dataset: Dataset, outcome: DatasetOutcome, context: RunContext, searchType: SearchType, maxRejectedShare: number): Promise<void>;
 //# sourceMappingURL=rebuild-support.d.ts.map

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,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAOpC;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,2BAA2B;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;0FAC0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;uEAGmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;KAChE,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAkBxB"}
+{"version":3,"file":"rebuild-support.d.ts","sourceRoot":"","sources":["../src/rebuild-support.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAUnD;;;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;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;0FAC0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;uEAGmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;KAChE,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAyBxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,YAAY,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/rebuild-support.js

@@ -4,6 +4,9 @@ import { deriveCollectionName } from './collection-name.js';
 import { DEFAULT_LOCK_TTL_MS } from './lock.js';
 /** Documents imported per Typesense request unless a writer is told otherwise. */
 const DEFAULT_BATCH_SIZE = 1000;
+/** The share of a dataset’s documents a collection may reject before the
+ *  dataset fails, unless a writer is told otherwise. */
+const DEFAULT_MAX_REJECTED_SHARE = 0.5;
 /**
  * Apply the shared defaults, once, so neither writer restates them – including
  * the collection naming, derived from each type ({@link deriveCollectionName})
@@ -19,10 +22,14 @@ const DEFAULT_BATCH_SIZE = 1000;
  * been paid for.
  */
 export function resolveRebuildOptions(searchType, options) {
-    const { batchSize = DEFAULT_BATCH_SIZE, lockTtlMs = DEFAULT_LOCK_TTL_MS, ...definitionOptions } = options;
+    const { batchSize = DEFAULT_BATCH_SIZE, lockTtlMs = DEFAULT_LOCK_TTL_MS, maxRejectedShare = DEFAULT_MAX_REJECTED_SHARE, ...definitionOptions } = options;
+    if (!(maxRejectedShare >= 0 && maxRejectedShare <= 1)) {
+        throw new Error(`maxRejectedShare must be a share from 0 to 1, got ${maxRejectedShare}.`);
+    }
     const resolved = {
         batchSize,
         lockTtlMs,
+        maxRejectedShare,
         definitionOptions: {
             ...definitionOptions,
             collectionNameFor: definitionOptions.collectionNameFor ?? deriveCollectionName,
@@ -32,6 +39,38 @@ export function resolveRebuildOptions(searchType, options) {
     buildCollectionDefinition(searchType, resolved.definitionOptions);
     return resolved;
 }
+/**
+ * Finish a dataset’s writes to one collection: land them, report what was
+ * left out ({@link RunContext.itemsRejected}), and fail an otherwise
+ * successful dataset when more was left out than `maxRejectedShare` allows –
+ * or all of it. A dataset that already failed is only reported: its output is
+ * incomplete, so its share says nothing, and failing it twice would blame the
+ * data for what a stage did.
+ *
+ * Both writers settle at the dataset’s flush rather than leave its last
+ * partial batch for the next dataset’s writes to land, so a rejection is
+ * always counted, reported and judged against the dataset it belongs to.
+ */
+export async function settleDataset(documents, dataset, outcome, context, searchType, maxRejectedShare) {
+    const writes = await documents.settle(dataset);
+    if (writes.rejected === 0) {
+        return;
+    }
+    context.itemsRejected?.(dataset, { target: searchType.name, ...writes });
+    if (outcome !== 'success') {
+        return;
+    }
+    const limit = writes.rejected === writes.written
+        ? 'every one of them'
+        : writes.rejected > writes.written * maxRejectedShare
+            ? `more than the ${Math.round(maxRejectedShare * 1000) / 10}% maxRejectedShare allows`
+            : undefined;
+    if (limit !== undefined) {
+        throw new Error(`“${searchType.name}” left out ${writes.rejected} of ${writes.written} documents of ${dataset.iri.toString()}, ${limit}: ${writes.reasons
+            .map(({ reason, count }) => `${count} × ${reason}`)
+            .join('; ')}`);
+    }
+}
 /**
  * Reject a `collectionNameFor` that gives a join target the same name as the
  * type doing the joining.

package/dist/search.d.ts

@@ -69,8 +69,8 @@ export interface LabelSource {
  * reference field from its own label source’s collection, all sources bundled
  * into one lookup – and reconstructs the engine-neutral
  * {@link SearchResult} ({@link parseSearchResponse}). `searchFacets` answers
- * a whole facet batch (e.g. a faceted listing’s skip-own-filter query variants) as a
- * single `multi_search` round-trip with one shared label lookup; a failed
+ * a whole facet batch (e.g. a faceted listing’s skip-own-filter query variants) in
+ * one `multi_search` round-trip with one shared label lookup; a failed
  * entry is reported in place as a per-query outcome, so it never discards
  * its siblings’ facets. Every engine specific stays here; consumers see only
  * logical documents.

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,5 +1,5 @@
 import { NESTED_DOCUMENT_TYPE, } from '@lde/search';
-import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, fieldNamed, isInlineReference, isBinnedRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNamesOf, labelTargetNamesOf, localLookupTargetsOf, nestedReferenceType, outputFields, physicalFields, referencedTargetsOf, referenceFields, storedTargetOf, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, facetSearches, fieldNamed, filterOn, inheritedFacetPolicies, isInlineReference, isBinnedRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNamesOf, labelTargetNamesOf, localLookupTargetsOf, nestedReferenceType, outputFields, physicalFields, referencedTargetsOf, referenceFields, storedTargetOf, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
 import { resolveProjection, } from './lookup.js';
@@ -13,8 +13,8 @@ import { resolveProjection, } from './lookup.js';
  * reference field from its own label source’s collection, all sources bundled
  * into one lookup – and reconstructs the engine-neutral
  * {@link SearchResult} ({@link parseSearchResponse}). `searchFacets` answers
- * a whole facet batch (e.g. a faceted listing’s skip-own-filter query variants) as a
- * single `multi_search` round-trip with one shared label lookup; a failed
+ * a whole facet batch (e.g. a faceted listing’s skip-own-filter query variants) in
+ * one `multi_search` round-trip with one shared label lookup; a failed
  * entry is reported in place as a per-query outcome, so it never discards
  * its siblings’ facets. Every engine specific stays here; consumers see only
  * logical documents.
@@ -220,6 +220,63 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             return new Map();
         }
     }
+    /**
+     * Answer the searches each caller’s query needs and fold them back into one
+     * response per caller: the hits and total of its first search, the facets
+     * of all. The searches travel together in one `multi_search` round-trip
+     * (split into requests of {@link MULTI_SEARCH_LIMIT}) – a POST, so a long
+     * `filter_by` (a batch `id` lookup, any membership over many IRIs) is
+     * bounded by the caller’s request, not by Typesense’s 4000-char
+     * query-string limit. A search asking for no document is answered empty
+     * without being sent: its only filter would compile away and hand back the
+     * whole collection ({@link isUnsatisfiable}). Each facet then reports the
+     * values its search selected ({@link withSelectedValues}).
+     *
+     * A failed search fails exactly its caller, which gets an `Error` in its
+     * place; only the transport failing rejects.
+     */
+    async function answer(searchType, callers) {
+        const collection = collections.get(searchType.class);
+        const planned = callers.flat();
+        const dispatched = planned.filter(({ query }) => !isUnsatisfiable(query));
+        const results = await performInChunks(client, dispatched.map(({ query }) => ({
+            collection,
+            ...buildSearchParams(query, searchType, searchParamsOptions),
+        })));
+        const transportFailure = results.find((result) => result instanceof Error);
+        if (transportFailure !== undefined) {
+            throw transportFailure;
+        }
+        const declaredNames = declaredFacetNames.get(searchType.class);
+        let entry = 0;
+        const responses = planned.map((search) => {
+            if (isUnsatisfiable(search.query)) {
+                return EMPTY_RESPONSE;
+            }
+            const result = results[entry++];
+            return result === undefined || 'error' in result
+                ? searchError(collection, search, result)
+                : withDeclaredFacetNames(result, declaredNames);
+        });
+        const completed = await withSelectedValues(client, collection, searchType, planned.map((search, index) => ({
+            ...search,
+            response: responses[index],
+        })), searchParamsOptions);
+        let next = 0;
+        return callers.map((searches) => {
+            const own = completed.slice(next, (next += searches.length));
+            const failed = own.find((response) => response instanceof Error);
+            if (failed !== undefined) {
+                return failed;
+            }
+            const answered = own;
+            const [first = EMPTY_RESPONSE] = answered;
+            return {
+                ...first,
+                facet_counts: answered.flatMap((response) => response.facet_counts ?? []),
+            };
+        });
+    }
     const engine = {
         schema,
         collectionNameFor(searchType) {
@@ -232,21 +289,27 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // rejected up front, for EVERY caller.
             assertTypeInSchema(schema, searchType);
             assertValidQuery(query, searchType, schema, joins);
-            // Asks for no document (an empty `id` membership): answer it without a
-            // round-trip rather than dispatching a query whose only filter compiles
-            // away, which would hand back the whole collection.
-            if (isUnsatisfiable(query)) {
-                return { total: 0, hits: [], facets: {} };
-            }
-            const params = buildSearchParams(query, searchType, searchParamsOptions);
             const cachedLabelsPromise = startCachedLabels(searchType);
-            // ONE search, but through `multi_search` (POST) like the facet batch and
-            // the label lookup: `documents().search()` is a GET, so a long
-            // `filter_by` – a batch `id` lookup, or any membership over many IRIs –
-            // would overflow Typesense's 4000-char query-string limit. POST puts it
-            // in the body, so the filter is bounded by the caller's request, not by
-            // the URL.
-            const response = withDeclaredFacetNames(await performSingleSearch(client, collections.get(searchType.class), params), declaredFacetNames.get(searchType.class));
+            // The hits come from the query as asked, carrying the facets that share
+            // its `where`; each own-filtered facet is counted by a search of its own
+            // (`facetSearches`), in the same round-trip.
+            const searches = facetSearches(query);
+            const shared = searches.find((search) => search.own === undefined);
+            const [response] = await answer(searchType, [
+                [
+                    {
+                        query: { ...query, facets: shared?.query.facets ?? [] },
+                        selected: {},
+                        facetOnly: false,
+                    },
+                    ...searches
+                        .filter((search) => search !== shared)
+                        .map(facetOnlySearch),
+                ],
+            ]);
+            if (response instanceof Error) {
+                throw response;
+            }
             const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? [], distinctLabelSources.get(searchType.class) ?? []));
             // What the caller asked to resolve, level by level. Independent of the
             // label lookup above: that one serves facet buckets and unprojected
@@ -262,56 +325,22 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             if (queries.length === 0) {
                 return [];
             }
-            const collection = collections.get(searchType.class);
             const cachedLabelsPromise = startCachedLabels(searchType);
-            // A query asking for no document faces the same inversion as in
-            // `search()`: its only filter would compile away and it would count
-            // facets over the whole collection. Such a query is answered with empty
-            // facets and kept OUT of the batch, so `dispatched` maps each sent search
-            // back to its caller position.
-            const dispatched = queries
-                .map((query, index) => ({ query, index }))
-                .filter(({ query }) => !isUnsatisfiable(query));
-            if (dispatched.length === 0) {
-                return queries.map(() => ({ facets: {} }));
-            }
-            // The whole batch travels as ONE multi_search round-trip. Each query
-            // compiles as facet-only regardless of what it carries: no hits
+            // Every search of every query travels in one multi_search round-trip,
+            // each facet-only regardless of what its query carries: no hits
             // (per_page 0) and no ordering – nothing is transferred or sorted that
             // this method cannot return.
-            const { results: rawResults } = (await client.multiSearch.perform({
-                searches: dispatched.map(({ query }) => ({
-                    collection,
-                    ...buildSearchParams({ ...query, orderBy: [], limit: 0, offset: 0 }, searchType, searchParamsOptions),
-                })),
-            }));
-            const declaredNames = declaredFacetNames.get(searchType.class);
-            const results = rawResults.map((result) => 'error' in result
-                ? result
-                : withDeclaredFacetNames(result, declaredNames));
+            const responses = await answer(searchType, queries.map((query) => facetSearches(query).map(facetOnlySearch)));
             // One label lookup serves every successful facet result in the batch.
-            const responses = results.filter((result) => !('error' in result));
-            const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups(responses, labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? [], distinctLabelSources.get(searchType.class) ?? []));
-            // multi_search reports a failed entry inline instead of rejecting the
-            // call; pass that through as a per-query outcome – naming the facets,
-            // not the position, since the batch order is the caller's internal –
-            // so one failed query never discards its siblings' facets. Every caller
-            // position is answered: a dispatched query by its entry, an
-            // unsatisfiable one by empty facets.
-            const outcomes = queries.map(() => ({ facets: {} }));
-            dispatched.forEach(({ index }, entry) => {
-                const result = results[entry];
-                outcomes[index] =
-                    result === undefined || 'error' in result
-                        ? {
-                            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, schema)
-                                .facets,
-                        };
-            });
-            return outcomes;
+            const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups(responses.filter((response) => !(response instanceof Error)), labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? [], distinctLabelSources.get(searchType.class) ?? []));
+            // A failed query is reported in place, so it never discards its
+            // siblings’ facets.
+            return responses.map((response) => response instanceof Error
+                ? { error: response }
+                : {
+                    facets: parseSearchResponse(response, searchType, labels, schema)
+                        .facets,
+                });
         },
     };
     // The runtime object is string-keyed; the literal-schema typing narrows it.
@@ -449,24 +478,179 @@ function withDeclaredFacetNames(response, declaredNames) {
         })),
     };
 }
+/** A planned facet search as sent: no hits, and with no hits no ordering. */
+function facetOnlySearch(search) {
+    return {
+        query: { ...search.query, orderBy: [], limit: 0, offset: 0 },
+        selected: search.selected,
+        facetOnly: true,
+    };
+}
+/** The error a failed or missing `multi_search` entry stands for, naming a
+ *  facet search by its facets – the batch position is the adapter’s own. */
+function searchError(collection, search, result) {
+    return entryError(search.facetOnly
+        ? `facet search for “${search.query.facets.join('”, “')}”`
+        : `search of “${collection}”`, result);
+}
+/** The error a failed or missing `multi_search` entry stands for. */
+function entryError(subject, result) {
+    return new Error(result === undefined
+        ? `Typesense ${subject} returned no result entry.`
+        : `Typesense ${subject} failed${result.code !== undefined ? ` (${result.code})` : ''}: ${result.error}`);
+}
 /**
- * Dispatch one search as a single-entry `multi_search` (POST). `multi_search`
- * reports a failed entry inline instead of rejecting the call, so the entry is
- * translated back into a throw: `search()` rejects on engine failure, and that
- * contract must not weaken just because the transport moved off GET.
+ * Send searches as `multi_search` requests of at most {@link
+ * MULTI_SEARCH_LIMIT} each, concurrently, and return their entries in order.
+ * A request that rejects rejects the whole call: the transport failed.
  */
-async function performSingleSearch(client, collection, params) {
-    const { results } = (await client.multiSearch.perform({
-        searches: [{ collection, ...params }],
-    }));
-    const [result] = results;
-    if (result === undefined) {
-        throw new Error(`Typesense search of “${collection}” returned no result entry.`);
-    }
-    if ('error' in result) {
-        throw new Error(`Typesense search of “${collection}” failed${result.code !== undefined ? ` (${result.code})` : ''}: ${result.error}`);
+async function performInChunks(client, searches) {
+    const chunks = [];
+    for (let start = 0; start < searches.length; start += MULTI_SEARCH_LIMIT) {
+        chunks.push(searches.slice(start, start + MULTI_SEARCH_LIMIT));
     }
-    return result;
+    const answered = await Promise.all(chunks.map(async (chunk) => {
+        try {
+            return (await client.multiSearch.perform({ searches: [...chunk] })).results;
+        }
+        catch (error) {
+            // The request as a whole failed: so did every search it carried, and
+            // nothing else. The Typesense client rejects with an Error.
+            return chunk.map(() => error);
+        }
+    }));
+    return answered.flat();
+}
+/** A response with nothing in it: the answer to a search that asks for no
+ *  document, which is never dispatched. */
+const EMPTY_RESPONSE = { found: 0, hits: [] };
+/** The bucket cap Typesense applies when `max_facet_values` is unset. */
+const TYPESENSE_DEFAULT_MAX_FACET_VALUES = 10;
+/** The searches Typesense accepts in one `multi_search` request by default
+ *  (`limit_multi_searches`). */
+const MULTI_SEARCH_LIMIT = 50;
+/**
+ * Each response with the values its search selected among the facet buckets,
+ * merged with the engine’s own in descending count order. A response that is
+ * already an `Error` passes through unchanged.
+ *
+ * A value missing from a facet the engine reported in full matches no
+ * document, so it gets count 0 without another search. A value missing from a
+ * facet cut off at the bucket cap, or narrowed by a facet policy, may still
+ * match documents, so it is counted by a search of its own: the search’s
+ * `where` plus that value. One search per value, because a facet search
+ * filtered on several values of a multi-valued field could cut off the very
+ * values it was asked to count. These searches travel together, in as few
+ * `multi_search` requests as Typesense accepts. The common cases (no
+ * selection, a selection with hits, a facet under the cap) cost nothing.
+ *
+ * A failed count fails exactly the response it was for, which becomes an
+ * `Error` in its place.
+ */
+async function withSelectedValues(client, collection, searchType, entries, options) {
+    const cap = options.maxFacetValues ?? TYPESENSE_DEFAULT_MAX_FACET_VALUES;
+    const missing = entries.map(({ query, selected, response }) => response instanceof Error
+        ? []
+        : Object.entries(selected).flatMap(([field, values]) => {
+            const counts = response.facet_counts?.find((facet) => facet.field_name === field)
+                ?.counts ?? [];
+            const present = new Set(counts.map((bucket) => bucket.value));
+            // A facet narrowed by a facet policy never reports a value the
+            // policy excludes, though a filter on the field still matches it:
+            // absent is no proof of 0 there either, so count it. A search that
+            // asks for no document has nothing to count.
+            const uncertain = !isUnsatisfiable(query) &&
+                (counts.length >= cap ||
+                    narrowedByPolicy(searchType, field, options));
+            return values
+                .filter((value) => !present.has(value))
+                .map((value) => ({ field, value, uncertain }));
+        }));
+    const toCount = missing.flatMap((values, entry) => values
+        .filter(({ uncertain }) => uncertain)
+        .map(({ field, value }) => ({ entry, field, value })));
+    const found = new Map();
+    const key = (entry, field, value) => JSON.stringify([entry, field, value]);
+    const results = await performInChunks(client, toCount.map(({ entry, field, value }) => {
+        const { query } = entries[entry];
+        return {
+            collection,
+            ...buildSearchParams({
+                ...query,
+                where: [...query.where, selecting(searchType, field, value)],
+                facets: [],
+                orderBy: [],
+                limit: 0,
+                offset: 0,
+            }, searchType, options),
+        };
+    }));
+    toCount.forEach(({ entry, field, value }, index) => {
+        const result = results[index];
+        found.set(key(entry, field, value), result instanceof Error
+            ? result
+            : result === undefined || 'error' in result
+                ? entryError(`count of facet value “${value}” on “${field}”`, result)
+                : result.found);
+    });
+    return entries.map(({ response }, entry) => {
+        const values = missing[entry];
+        if (response instanceof Error || values.length === 0) {
+            return response;
+        }
+        const added = new Map();
+        for (const { field, value, uncertain } of values) {
+            // Every uncertain value was counted above.
+            const count = uncertain
+                ? found.get(key(entry, field, value))
+                : 0;
+            if (count instanceof Error) {
+                return count;
+            }
+            added.set(field, [...(added.get(field) ?? []), { value, count }]);
+        }
+        const facetCounts = response.facet_counts ?? [];
+        return {
+            ...response,
+            facet_counts: [
+                ...facetCounts.map((facet) => ({
+                    ...facet,
+                    // Merged by count: a value a policy hid can outnumber every bucket.
+                    counts: added.has(facet.field_name)
+                        ? [
+                            ...facet.counts,
+                            ...added.get(facet.field_name),
+                        ].sort(byCount)
+                        : facet.counts,
+                })),
+                // A facet the response does not carry at all: an unanswered search’s.
+                ...[...added]
+                    .filter(([field]) => !facetCounts.some((facet) => facet.field_name === field))
+                    .map(([field, counts]) => ({
+                    field_name: field,
+                    counts: counts.sort(byCount),
+                })),
+            ],
+        };
+    });
+}
+/** The clause that selects one facet value: `is` on a boolean, `in` on
+ *  anything else. */
+function selecting(searchType, field, value) {
+    return filterOn(fieldNamed(searchType, field)?.kind === 'boolean'
+        ? { field, is: value === 'true' }
+        : { field, in: [value] });
+}
+/** Orders buckets by descending count, as the engine orders its own. */
+function byCount(first, second) {
+    return second.count - first.count;
+}
+/** Whether a facet policy narrows the facet on `name` ({@link
+ *  inheritedFacetPolicies}), so its buckets leave out values its field holds. */
+function narrowedByPolicy(searchType, name, options) {
+    const field = fieldNamed(searchType, name);
+    return (field !== undefined &&
+        inheritedFacetPolicies(field, options.schema).size > 0);
 }
 /**
  * Resolve labels from each group’s label-source collection. Labels are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.36.1",
+  "version": "0.38.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.30.0",
+    "@lde/search": "^0.32.0",
     "@lde/text-normalization": "^0.2.0",
     "tslib": "^2.3.0",
     "typesense": "^3.1.1"
@@ -36,6 +36,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "^0.8.0",
-    "@lde/pipeline": "^0.38.1"
+    "@lde/pipeline": "^0.39.0"
   }
 }