@lde/search-typesense 0.21.3 → 0.23.0

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;IAYjC,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAmGjE,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;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"}

package/dist/blue-green-rebuild.js

@@ -59,7 +59,8 @@ export class BlueGreenRebuild {
         assertSweepableProvenanceField(searchType, { requireFacetable: false });
         this.sourceField = provenanceField(searchType);
         this.resolved = resolveRebuildOptions(searchType, options);
-        this.collectionName = this.resolved.definitionOptions.name;
+        this.collectionName =
+            this.resolved.definitionOptions.collectionNameFor(searchType);
     }
     async openRun(context) {
         const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
@@ -69,12 +70,25 @@ export class BlueGreenRebuild {
             // Create the fresh (blue) collection up front, so a failure surfaces
             // before any dataset is processed. startedAt orders the versioned names;
             // concurrent same-name runs are excluded by the lock.
-            const collection = `${name}_${Date.parse(context.startedAt)}`;
+            //
+            // The SAME versioning applies to every peer this type joins to, so an
+            // emitted reference field names the peer’s FRESH collection rather than
+            // its live one – Typesense resolves an alias to a concrete collection at
+            // create time and keeps the concrete name, so referencing the alias would
+            // pin the new build to the collection the peer is about to supersede. No
+            // coordinator is needed: every writer in the run gets the same
+            // `RunContext`, so `startedAt` – and therefore every derived name – is
+            // identical across them.
+            const version = Date.parse(context.startedAt);
+            const versioned = (searchType) => `${definitionOptions.collectionNameFor(searchType)}_${version}`;
+            const collection = versioned(this.searchType);
             const previous = await this.aliasTarget(name);
-            const definition = buildCollectionDefinition(this.searchType, definitionOptions);
+            const definition = buildCollectionDefinition(this.searchType, {
+                ...definitionOptions,
+                collectionNameFor: versioned,
+            });
             await this.client.collections().create({
                 ...definition,
-                name: collection,
                 // 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.
@@ -134,6 +148,15 @@ export class BlueGreenRebuild {
                         .catch(() => undefined);
                     await releaseLock(this.client, name);
                 },
+                abandon: async () => {
+                    // Everything `abort` does EXCEPT the drop. Asked for when a peer
+                    // whose documents reference this collection by concrete name has
+                    // already gone live: dropping it would break that live collection’s
+                    // joins, so the collection is kept for a later run to supersede.
+                    // Releasing the lock is the whole point – without it the index stays
+                    // locked for its full TTL and the next run cannot rebuild it.
+                    await releaseLock(this.client, name);
+                },
             };
         });
     }

package/dist/collection-definition.d.ts

@@ -2,17 +2,30 @@ import type { CollectionCreateSchema } from 'typesense';
 import { type SearchSchema, type SearchType } from '@lde/search';
 /** Deployment-specific options the generic field model does not carry. */
 export interface CollectionDefinitionOptions {
-    /** The Typesense collection (or alias) name. Omit to derive it from the
-     *  type’s `name` ({@link deriveCollectionName}); supply one to override that
-     *  (an env prefix, a multi-tenant name, an existing collection). */
-    readonly name?: string;
     /**
-     * The Search Schema the type belongs to – required only when the type
-     * surfaces an inline reference, whose nested fields are declared from the
-     * {@link ReferenceType} the schema resolves. A type without one needs no
-     * schema, so a caller that declares no nesting passes none; a type that does
-     * fails here rather than building a collection that silently omits the
-     * nesting.
+     * How a search type is named in Typesense – for **this** type and, where it
+     * declares a {@link ReferenceField.joinable} reference, for the peer type
+     * that reference points at. Omit to derive every name from the type’s own
+     * `name` ({@link deriveCollectionName}); supply one to override that (an env
+     * prefix, a multi-tenant name, an existing collection).
+     *
+     * A function of the type rather than a bare name, because an emitted
+     * reference field must name the peer’s **concrete** collection: a
+     * blue/green writer therefore hands in a function that appends the run’s
+     * version to every name in the component, so a fresh build references its
+     * peer’s fresh collection rather than the live one. No coordinator is
+     * needed – every writer in a run receives the same `RunContext`, so they
+     * derive identical names.
+     */
+    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) 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.
      */
     readonly schema?: SearchSchema;
     /** Snowball stemming locale for non-localized searchable fields (e.g. `en`).
@@ -37,9 +50,15 @@ export interface CollectionDefinitionOptions {
  * stems in `defaultLocale` when one is set, and is left unstemmed (folded
  * only) otherwise.
  *
- * The collection `name` is optional: omitted, it is derived from the type’s own
- * `name` ({@link deriveCollectionName}), so a caller that has no naming opinion
- * states none.
+ * Collection naming is optional: omitted, every name – this type’s and the peer
+ * types its joins point at – is derived from the type’s own `name`
+ * ({@link deriveCollectionName}), so a caller that has no naming opinion states
+ * none.
+ *
+ * A {@link ReferenceField.joinable} reference is emitted as a Typesense
+ * **reference field** pointing at its target collection’s `id`, so a query can
+ * filter this type by a condition on the referent
+ * ({@link referenceDeclaration}).
  *
  * Memory lever: Typesense holds the index in RAM (with a raw copy of each
  * document on disk), so RAM tracks the *indexed* surface – roughly 2–3× the

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

package/dist/collection-definition.js

@@ -1,4 +1,4 @@
-import { displayFieldPattern, isInlineReference, isInternalField, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
+import { displayFieldPattern, ID_FIELD, isInlineReference, isInternalField, joinGraph, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
 import { deriveCollectionName } from './collection-name.js';
 /**
  * Build a Typesense collection definition from the unified {@link SearchType}, so
@@ -12,9 +12,15 @@ import { deriveCollectionName } from './collection-name.js';
  * stems in `defaultLocale` when one is set, and is left unstemmed (folded
  * only) otherwise.
  *
- * The collection `name` is optional: omitted, it is derived from the type’s own
- * `name` ({@link deriveCollectionName}), so a caller that has no naming opinion
- * states none.
+ * Collection naming is optional: omitted, every name – this type’s and the peer
+ * types its joins point at – is derived from the type’s own `name`
+ * ({@link deriveCollectionName}), so a caller that has no naming opinion states
+ * none.
+ *
+ * A {@link ReferenceField.joinable} reference is emitted as a Typesense
+ * **reference field** pointing at its target collection’s `id`, so a query can
+ * filter this type by a condition on the referent
+ * ({@link referenceDeclaration}).
  *
  * Memory lever: Typesense holds the index in RAM (with a raw copy of each
  * document on disk), so RAM tracks the *indexed* surface – roughly 2–3× the
@@ -39,10 +45,10 @@ import { deriveCollectionName } from './collection-name.js';
  * display labels.
  */
 export function buildCollectionDefinition(searchType, options = {}) {
-    const { defaultLocale } = options;
+    const { defaultLocale, collectionNameFor = deriveCollectionName } = options;
     const collection = {
-        name: options.name ?? deriveCollectionName(searchType),
-        fields: searchType.fields.flatMap((field) => typesenseFields(searchType, field, defaultLocale, options.defaultSortingField, options.schema)),
+        name: collectionNameFor(searchType),
+        fields: searchType.fields.flatMap((field) => typesenseFields(searchType, field, defaultLocale, options.defaultSortingField, options.schema, collectionNameFor)),
     };
     // Typesense rejects an `object`/`object[]` field unless nesting is enabled,
     // so the flag is a consequence of the declaration – never a knob.
@@ -73,8 +79,54 @@ function nestedTypeOf(searchType, field, schema) {
     }
     return nested;
 }
+/**
+ * The Typesense reference declaration a {@link ReferenceField.joinable} field
+ * carries, or `undefined` for every other field. All three keys are forced,
+ * none is a knob:
+ *
+ * - **`reference` always targets `.id`.** A reference match hitting more than
+ *   one document is a 400, and `id` is the only field the schema guarantees
+ *   unique.
+ * - **`async_reference: true`.** Without it, a document whose referent is not
+ *   indexed yet is rejected with a 400 – and the batch import runs
+ *   `throwOnFail: false`, so those would be silently dropped documents.
+ *   Documents stream per dataset ([ADR 13](../../../docs/decisions/0013-project-inside-the-batch-per-root-type.md)),
+ *   so out-of-order arrival is normal rather than exceptional; the engine
+ *   back-fills the reference when the referent lands.
+ * - **`cascade_delete: false`.** It defaults to `true`, so a sweep removing a
+ *   departed source’s referent documents would delete other sources’ referring
+ *   documents with them. Disabling it requires `async_reference`, so the two
+ *   travel together.
+ *
+ * Throws when the type declares a joinable reference the caller gave no schema
+ * to resolve the target of – the collection would otherwise come into existence
+ * without its reference and 400 on every join query.
+ */
+function referenceDeclaration(searchType, field, schema, collectionNameFor) {
+    if (field.kind !== 'reference' || field.joinable !== true) {
+        return undefined;
+    }
+    if (schema === undefined) {
+        throw new Error(`Building the collection for “${searchType.name}” needs the search schema its joinable reference “${field.name}” resolves against; pass it as the collection-definition option “schema”.`);
+    }
+    const target = joinGraph(schema).resolve(searchType, [field.name]);
+    if (target === undefined) {
+        // A schema WAS given and the edge still does not resolve. The rules that
+        // would reject the declaration itself all ran when the schema was built, so
+        // what is left is identity: `joinGraph` resolves from the exact declaration
+        // object the schema holds, and this is a lookalike – a re-declared type, or
+        // one belonging to another schema. Saying “pass the schema” here would send
+        // a caller to do the thing they already did.
+        throw new Error(`Building the collection for “${searchType.name}” cannot resolve its joinable reference “${field.name}”: the given search schema does not declare this exact type. Pass the declaration the schema was built from, not a copy of it.`);
+    }
+    return {
+        reference: `${collectionNameFor(target)}.${ID_FIELD}`,
+        async_reference: true,
+        cascade_delete: false,
+    };
+}
 /** The physical Typesense fields one declaration produces. */
-function typesenseFields(searchType, field, defaultLocale, defaultSortingField, schema) {
+function typesenseFields(searchType, field, defaultLocale, defaultSortingField, schema, collectionNameFor) {
     // An internal field (no role) is projected as a reading device for the
     // derives and pruned before the writer, so the collection stores nothing for
     // it: not stored, not indexed, no RAM. Same predicate the projection prunes
@@ -137,6 +189,7 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
             // A `required` field is non-optional; so is the `default_sorting_field`,
             // which Typesense requires to be present. Everything else may be absent.
             optional: field.required !== true && field.name !== defaultSortingField,
+            ...referenceDeclaration(searchType, field, schema, collectionNameFor),
         },
     ];
     // `names.search` is non-empty exactly when the field projects a folded

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

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

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

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

package/dist/in-place-rebuild.js

@@ -38,7 +38,10 @@ const DEFAULT_MAX_SWEEPABLE_SOURCES = 10_000;
  * `openRun` takes the single-flight cross-pod lock (throwing
  * `RebuildAlreadyRunning` when another rebuild holds it) and creates
  * the collection on demand from the {@link SearchType} plus the two
- * bookkeeping fields.
+ * bookkeeping fields. A collection that already exists is used as it is, with
+ * one exception: it must carry every reference field the declaration asks for,
+ * or the run fails with the drop-and-rebuild that fixes it
+ * ({@link assertReferencesPresent}).
  *
  * Document ids must be unique per (source, entity) – the caller keys them –
  * or documents from different sources overwrite each other.
@@ -72,7 +75,8 @@ export class InPlaceRebuild {
         const { maxSweepableSources = DEFAULT_MAX_SWEEPABLE_SOURCES, ...rebuildOptions } = options;
         this.maxSweepableSources = maxSweepableSources;
         this.resolved = resolveRebuildOptions(searchType, rebuildOptions);
-        this.collectionName = this.resolved.definitionOptions.name;
+        this.collectionName =
+            this.resolved.definitionOptions.collectionNameFor(searchType);
     }
     async openRun(context) {
         const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
@@ -85,8 +89,9 @@ export class InPlaceRebuild {
             // field of its own; when it does, that declared field already carries the
             // IRI (and its own `facet: true`), and a second column would be the same
             // value twice, free to drift.
-            await ensureCollectionExists(this.client, name, () => {
-                const definition = buildCollectionDefinition(this.searchType, definitionOptions);
+            const definition = buildCollectionDefinition(this.searchType, definitionOptions);
+            const declaredFields = definition.fields ?? [];
+            const created = await ensureCollectionExists(this.client, name, () => {
                 const bookkeeping = [
                     ...(sourceField === SOURCE_FIELD
                         ? [{ name: SOURCE_FIELD, type: 'string', facet: true }]
@@ -95,9 +100,14 @@ export class InPlaceRebuild {
                 ];
                 return {
                     ...definition,
-                    fields: [...(definition.fields ?? []), ...bookkeeping],
+                    fields: [...declaredFields, ...bookkeeping],
                 };
             });
+            // A collection this run did NOT create may predate a `joinable` being
+            // declared, and a reference cannot be added to it here.
+            if (!created) {
+                await assertReferencesPresent(this.client, name, declaredFields);
+            }
             const importer = new BatchImporter(this.client, name, batchSize);
             return {
                 // Stamping the provenance field – rather than trusting the projection
@@ -175,3 +185,37 @@ export class InPlaceRebuild {
         return counts.map((count) => count.value);
     }
 }
+/**
+ * Fail loudly when an EXISTING collection does not carry every reference field
+ * the declaration asks for, naming the drop-and-rebuild that fixes it. Never
+ * alters: an In-place rebuild creates a collection on demand and otherwise
+ * leaves its shape alone, and a reference field is the one difference that is
+ * not self-correcting.
+ *
+ * Without this a deployment that added `joinable` to an existing schema would
+ * index and commit perfectly happily, and then 400 on every join query – the
+ * collection has the *values*, it just has no reference to join through.
+ * Failing here keeps the invariant a component-scoped rebuild rests on: a
+ * component’s collections come into existence WITH their references, and never
+ * acquire them later.
+ *
+ * Deliberately scoped to reference fields only. Every other schema difference
+ * is self-correcting (a new plain field simply starts being written) or
+ * harmless, and general drift detection is a feature of its own.
+ */
+async function assertReferencesPresent(client, name, fields) {
+    const declared = fields.filter((field) => field.reference !== undefined);
+    if (declared.length === 0) {
+        return;
+    }
+    const existing = new Map((await client.collections(name).retrieve()).fields.map((field) => [
+        field.name,
+        field.reference,
+    ]));
+    const missing = declared.filter((field) => existing.get(field.name) !== field.reference);
+    if (missing.length > 0) {
+        throw new Error(`Typesense collection “${name}” exists without the reference field(s) ${missing
+            .map((field) => `“${field.name}” → “${field.reference}”`)
+            .join(', ')} its search type declares. A reference cannot be added to a live collection here: drop “${name}” (and the collections that join to it) and let the next run rebuild them.`);
+    }
+}

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { buildCollectionDefinition } from './collection-definition.js';
 export type { CollectionDefinitionOptions } from './collection-definition.js';
 export { deriveCollectionName } from './collection-name.js';
 export { buildSearchParams } from './query-compiler.js';
-export type { BuildSearchParamsOptions } from './query-compiler.js';
+export type { BuildSearchParamsOptions, JoinTarget } from './query-compiler.js';
 export { createTypesenseSearchEngine, parseSearchResponse } from './search.js';
 export type { TypesenseSearchEngine, TypesenseSearchEngineOptions, TypesenseSearchResponse, } from './search.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EACV,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EACV,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/lock.d.ts

@@ -35,8 +35,13 @@ export declare function releaseLock(client: Client, name: string): Promise<void>
 /**
  * Create a collection on demand: retrieve it, and only on a 404 create it
  * from the lazily built `schema`, tolerating a concurrent creator (409).
+ *
+ * Returns whether the collection was **brought into existence** by this call –
+ * which is what tells a caller that everything the definition declares is
+ * actually in the collection. An existing one may predate a declaration
+ * change, and some of those differences an engine cannot correct in place.
  */
-export declare function ensureCollectionExists(client: Client, name: string, schema: () => CollectionCreateSchema): Promise<void>;
+export declare function ensureCollectionExists(client: Client, name: string, schema: () => CollectionCreateSchema): Promise<boolean>;
 /** The HTTP status a Typesense client error carries, if any. */
 export declare function httpStatus(error: unknown): number | undefined;
 //# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAIhE,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAElD;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,IAAI,EAAE,MAAM;CAIzB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,GAAG,EACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GACxB,OAAO,CAAC,GAAG,CAAC,CAUd;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAED,yEAAyE;AACzE,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ7E;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,sBAAsB,GACnC,OAAO,CAAC,IAAI,CAAC,CAgBf;AA+BD,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE7D"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAIhE,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAElD;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,IAAI,EAAE,MAAM;CAIzB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,GAAG,EACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GACxB,OAAO,CAAC,GAAG,CAAC,CAUd;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAED,yEAAyE;AACzE,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ7E;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,sBAAsB,GACnC,OAAO,CAAC,OAAO,CAAC,CAmBlB;AA+BD,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE7D"}

package/dist/lock.js

@@ -83,11 +83,16 @@ export async function releaseLock(client, name) {
 /**
  * Create a collection on demand: retrieve it, and only on a 404 create it
  * from the lazily built `schema`, tolerating a concurrent creator (409).
+ *
+ * Returns whether the collection was **brought into existence** by this call –
+ * which is what tells a caller that everything the definition declares is
+ * actually in the collection. An existing one may predate a declaration
+ * change, and some of those differences an engine cannot correct in place.
  */
 export async function ensureCollectionExists(client, name, schema) {
     try {
         await client.collections(name).retrieve();
-        return;
+        return false;
     }
     catch (error) {
         if (httpStatus(error) !== 404) {
@@ -96,11 +101,14 @@ export async function ensureCollectionExists(client, name, schema) {
     }
     try {
         await client.collections().create(schema());
+        return true;
     }
     catch (error) {
         if (httpStatus(error) !== 409) {
             throw error;
         }
+        // A concurrent caller won the race; the collection exists, but not by us.
+        return false;
     }
 }
 /** Take over the lock if its holder has not refreshed it within `ttlMs`. */
@@ -113,7 +121,7 @@ async function reclaimIfStale(client, name, ttlMs) {
             .retrieve());
     }
     catch (error) {
-        // Released between our create and this read — leave it for the next try.
+        // Released between our create and this read – leave it for the next try.
         if (httpStatus(error) === 404) {
             return false;
         }

package/dist/query-compiler.d.ts

@@ -1,11 +1,35 @@
 import type { SearchParams } from 'typesense/lib/Typesense/Documents.js';
-import { type Filter, type SearchQuery, type SearchType } from '@lde/search';
+import { type Filter, type RootType, type SearchQuery, type SearchType } from '@lde/search';
+/** One hop of a join path, resolved: the Root Type it reaches and the
+ *  Typesense collection that type is stored in. */
+export interface JoinTarget {
+    readonly searchType: RootType;
+    readonly collection: string;
+}
 /**
  * Options for {@link buildSearchParams} – the query half of the engine
  * adapter. {@link TypesenseSearchEngineOptions} extends this, so each knob is
  * declared once and the engine forwards its options wholesale.
  */
 export interface BuildSearchParamsOptions {
+    /**
+     * Resolves a criterion’s {@link CriterionBase.on} join path to the collection
+     * it constrains – the one thing the engine-neutral {@link JoinGraph}
+     * deliberately does not answer, because collection naming is engine- and
+     * deployment-specific.
+     *
+     * Called once per **prefix** of a path, so a two-hop
+     * `['dataset', 'publisher']` yields the collection of each hop and compiles
+     * to the nested `$datasets($publishers(…))`. The declaration comes back with
+     * it, because the leaf term is compiled against the *target* type’s field
+     * (its kind, its facet flag), not the searched one.
+     *
+     * Left unset – or returning `undefined` for a path – a joined criterion
+     * compiles to nothing and drops out of its clause. Through the engine it can
+     * never get that far: `assertValidQuery` rejects an unresolvable path up
+     * front.
+     */
+    readonly joinTargetFor?: (from: SearchType, path: readonly string[]) => JoinTarget | undefined;
     /**
      * Cap on the number of buckets returned per facet (`max_facet_values`). Left
      * unset, Typesense defaults to 10 – too few for high-cardinality facets
@@ -31,6 +55,11 @@ export interface BuildSearchParamsOptions {
  * so the mapping is asserted directly in unit tests. Field names come from
  * {@link physicalFields}, the same convention the projection and the collection
  * schema use, so a query can never reference a field the index does not carry.
+ *
+ * A criterion carrying a {@link CriterionBase.on} join path compiles to a
+ * nested `$collection(…)` clause – one per hop – which is why the compiler
+ * takes {@link BuildSearchParamsOptions.joinTargetFor}: the join graph names
+ * the type, the deployment names the collection.
  */
 export declare function buildSearchParams(query: SearchQuery, searchType: SearchType, options?: BuildSearchParamsOptions): SearchParams<object>;
 /**

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

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

package/dist/query-compiler.js

@@ -6,13 +6,18 @@ import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSecon
  * so the mapping is asserted directly in unit tests. Field names come from
  * {@link physicalFields}, the same convention the projection and the collection
  * schema use, so a query can never reference a field the index does not carry.
+ *
+ * A criterion carrying a {@link CriterionBase.on} join path compiles to a
+ * nested `$collection(…)` clause – one per hop – which is why the compiler
+ * takes {@link BuildSearchParamsOptions.joinTargetFor}: the join graph names
+ * the type, the deployment names the collection.
  */
 export function buildSearchParams(query, searchType, options = {}) {
     const folded = query.text !== undefined && query.text.length > 0
         ? fold(query.text)
         : undefined;
     const { names, weights } = queryFields(searchType, query.locale);
-    const filterBy = compileFilterBy(query.where, searchType, options.onIgnoredFilter);
+    const filterBy = compileFilterBy(query.where, searchType, options);
     const sortBy = query.orderBy
         .map((sort) => compileSort(sort, searchType, query.locale))
         .join(',');
@@ -97,12 +102,12 @@ function queryFields(searchType, locale) {
 }
 /** AND-join the compiled `where` clauses; a clause that compiles to nothing is
  *  skipped and reported to `onIgnoredFilter`. */
-function compileFilterBy(where, searchType, onIgnoredFilter) {
+function compileFilterBy(where, searchType, options) {
     return where
         .map((filter) => {
-        const clause = compileFilter(filter, searchType);
+        const clause = compileFilter(filter, searchType, options);
         if (clause === undefined) {
-            onIgnoredFilter?.(filter);
+            options.onIgnoredFilter?.(filter);
         }
         return clause;
     })
@@ -132,10 +137,10 @@ function compileFilterBy(where, searchType, onIgnoredFilter) {
  * A clause left with no terms either way is skipped and reported to
  * `onIgnoredFilter`.
  */
-function compileFilter(filter, searchType) {
+function compileFilter(filter, searchType, options) {
     const terms = [];
     for (const criterion of filter.or) {
-        const outcome = compileCriterion(criterion, searchType);
+        const outcome = compileCriterion(criterion, searchType, options);
         if (outcome === VACUOUS) {
             return undefined;
         }
@@ -158,7 +163,40 @@ const UNUSABLE = Symbol('unusable');
  * and cannot be recovered from a bare `undefined`, so it is returned rather than
  * re-derived by a second pass over the same rules.
  */
-function compileCriterion(criterion, searchType) {
+function compileCriterion(criterion, searchType, options) {
+    const on = criterion.on ?? [];
+    if (on.length === 0) {
+        return compileLeaf(criterion, searchType);
+    }
+    // A joined criterion constrains a document in ANOTHER collection, so the leaf
+    // is compiled against the type that path reaches and then wrapped, one
+    // `$collection(…)` per hop, outermost hop first:
+    // `['dataset', 'publisher']` → `$datasets($publishers(id:=…))`.
+    const collections = [];
+    let target = searchType;
+    for (let hop = 1; hop <= on.length; hop++) {
+        const resolved = options.joinTargetFor?.(searchType, on.slice(0, hop));
+        if (resolved === undefined) {
+            // An unresolvable path is a criterion that cannot be compiled at all –
+            // false, so it drops out and its siblings still stand. Through the
+            // engine, `assertValidQuery` has already rejected it.
+            return UNUSABLE;
+        }
+        collections.push(resolved.collection);
+        target = resolved.searchType;
+    }
+    const leaf = compileLeaf(criterion, target);
+    // A vacuous leaf states no constraint on the referent, so the join as a whole
+    // states none either – the reading, and so the outcome, passes straight
+    // through the hops.
+    if (leaf === VACUOUS || leaf === UNUSABLE) {
+        return leaf;
+    }
+    return collections.reduceRight((inner, collection) => `$${collection}(${inner})`, leaf);
+}
+/** The criterion’s own term, against the type it actually constrains – the
+ *  searched type, or the one its join path reaches. */
+function compileLeaf(criterion, searchType) {
     // `id` is the Typesense document key, not a declared field. Exact `:=`
     // membership, like a non-facet field ({@link compileMembership}), so an IRI
     // cannot partial-match on a shared path segment. (`fetchLabels` resolves

package/dist/rebuild-support.d.ts

@@ -16,25 +16,27 @@ export interface RebuildOptions extends CollectionDefinitionOptions {
 export interface ResolvedRebuildOptions {
     readonly batchSize: number;
     readonly lockTtlMs: number;
-    /** The collection-definition options with the `name` resolved – the one place
-     *  the resolved name lives, so the collection a writer talks to and the
-     *  definition it creates cannot say different things. */
+    /** 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
+     *  collections its references name cannot say different things. */
     readonly definitionOptions: CollectionDefinitionOptions & {
-        readonly name: string;
+        readonly collectionNameFor: (searchType: SearchType) => string;
     };
 }
 /**
  * Apply the shared defaults, once, so neither writer restates them – including
- * the collection name, derived from the type ({@link deriveCollectionName})
+ * the collection naming, derived from each type ({@link deriveCollectionName})
  * when the deployment supplies none.
  *
  * Writers resolve at construction rather than per run, so an underivable name
  * throws when the writer is built, not on the first rebuild. The collection
  * definition is built here and discarded for the same reason: every way a
  * declaration can fail to describe a collection – an unresolvable surfaced
- * inline reference, whose nesting needs the schema – then fails at construction
- * rather than inside the first run, after a lock is held and a whole extraction
- * has been paid for.
+ * inline reference, whose nesting needs the schema, or a joinable reference
+ * whose target it resolves the same way – then fails at construction rather
+ * than inside the first run, after a lock is held and a whole extraction has
+ * been paid for.
  */
 export declare function resolveRebuildOptions(searchType: SearchType, options: RebuildOptions): ResolvedRebuildOptions;
 /**

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

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

package/dist/rebuild-support.js

@@ -1,20 +1,21 @@
-import { datasetField, isInternalField } from '@lde/search/adapter';
+import { datasetField, isInternalField, joinGraph, referenceFields, } from '@lde/search/adapter';
 import { buildCollectionDefinition, } from './collection-definition.js';
 import { deriveCollectionName } from './collection-name.js';
 import { DEFAULT_LOCK_TTL_MS } from './lock.js';
 import { DEFAULT_BATCH_SIZE } from './import.js';
 /**
  * Apply the shared defaults, once, so neither writer restates them – including
- * the collection name, derived from the type ({@link deriveCollectionName})
+ * the collection naming, derived from each type ({@link deriveCollectionName})
  * when the deployment supplies none.
  *
  * Writers resolve at construction rather than per run, so an underivable name
  * throws when the writer is built, not on the first rebuild. The collection
  * definition is built here and discarded for the same reason: every way a
  * declaration can fail to describe a collection – an unresolvable surfaced
- * inline reference, whose nesting needs the schema – then fails at construction
- * rather than inside the first run, after a lock is held and a whole extraction
- * has been paid for.
+ * inline reference, whose nesting needs the schema, or a joinable reference
+ * whose target it resolves the same way – then fails at construction rather
+ * than inside the first run, after a lock is held and a whole extraction has
+ * been paid for.
  */
 export function resolveRebuildOptions(searchType, options) {
     const { batchSize = DEFAULT_BATCH_SIZE, lockTtlMs = DEFAULT_LOCK_TTL_MS, ...definitionOptions } = options;
@@ -23,12 +24,41 @@ export function resolveRebuildOptions(searchType, options) {
         lockTtlMs,
         definitionOptions: {
             ...definitionOptions,
-            name: definitionOptions.name ?? deriveCollectionName(searchType),
+            collectionNameFor: definitionOptions.collectionNameFor ?? deriveCollectionName,
         },
     };
+    assertDistinctJoinTargetNames(searchType, resolved.definitionOptions);
     buildCollectionDefinition(searchType, resolved.definitionOptions);
     return resolved;
 }
+/**
+ * Reject a `collectionNameFor` that gives a join target the same name as the
+ * type doing the joining.
+ *
+ * The trap is the obvious migration from the `name` option this replaced:
+ * `name: 'staging_works'` reads as `collectionNameFor: () => 'staging_works'`,
+ * a constant function – which now also names every peer, so the emitted
+ * reference points the collection at ITSELF. Nothing downstream complains:
+ * Typesense accepts the self-reference and every join through it then answers
+ * nothing.
+ *
+ * Only the (type, target) pairs this type actually joins to are checked, so a
+ * deployment deliberately sharing one collection between unrelated types – the
+ * several-label-sources-in-one-`labels` case – stays allowed.
+ */
+function assertDistinctJoinTargetNames(searchType, options) {
+    const { schema, collectionNameFor } = options;
+    if (schema === undefined) {
+        return;
+    }
+    const own = collectionNameFor(searchType);
+    for (const field of referenceFields(searchType)) {
+        const target = joinGraph(schema).resolve(searchType, [field.name]);
+        if (target !== undefined && collectionNameFor(target) === own) {
+            throw new Error(`The collection naming for “${searchType.name}” gives its join target “${target.name}” the same collection “${own}”, so the reference on “${field.name}” would point the collection at itself and every join through it would answer nothing. A constant “collectionNameFor” does this – derive the name from the type it is given (e.g. \`(type) => \`prefix_\${deriveCollectionName(type)}\`\`).`);
+        }
+    }
+}
 /**
  * Reject a {@link SearchType} that declares any of the bookkeeping field names
  * a writer stamps, so a domain field can never collide with `source` /

package/dist/search.d.ts

@@ -6,7 +6,7 @@ import { type BuildSearchParamsOptions } from './query-compiler.js';
  *  wholesale into each search. Reference labels resolve per field from the
  *  collection of the SearchType its `labelSource` names – a label source is
  *  just another type, so it is named the same way. */
-export interface TypesenseSearchEngineOptions<TypeName extends string = string> extends BuildSearchParamsOptions {
+export interface TypesenseSearchEngineOptions<TypeName extends string = string> extends Omit<BuildSearchParamsOptions, 'joinTargetFor'> {
     /**
      * Overrides the collection (or alias) a search type reads, keyed by the
      * type’s `name`. Every type not named here reads the collection derived from

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/search.js

@@ -1,4 +1,4 @@
-import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, labelFieldOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
 /**
@@ -39,6 +39,25 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
         searchType.class,
         collection,
     ]));
+    // The schema's join graph, built once (it is cached per schema anyway), plus
+    // the collection half the graph deliberately leaves to the adapter. Together
+    // they are what lets a `where` criterion carry an `on` path: validation
+    // resolves the path to a type, the compiler turns each hop into
+    // `$collection(…)`.
+    const joins = joinGraph(schema);
+    const searchParamsOptions = {
+        ...options,
+        joinTargetFor: (from, path) => {
+            // Both lookups always hit: `assertValidQuery` runs first and rejects
+            // every path this could not resolve, and each type resolved a collection
+            // above.
+            const target = joins.resolve(from, path);
+            return {
+                searchType: target,
+                collection: collections.get(target.class),
+            };
+        },
+    };
     // Resolve every reference field's label source ONCE at construction. The
     // schema already guarantees the named type exists and serves labels
     // (`searchSchema`/`labelFieldOf`), and every type resolved a collection
@@ -175,14 +194,14 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // invalid query (unknown field, wrong operator, unknown facet) are both
             // rejected up front, for EVERY caller.
             assertTypeInSchema(schema, searchType);
-            assertValidQuery(query, searchType);
+            assertValidQuery(query, searchType, 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, options);
+            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
@@ -197,7 +216,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
         async searchFacets(searchType, queries) {
             assertTypeInSchema(schema, searchType);
             for (const query of queries) {
-                assertValidQuery(query, searchType);
+                assertValidQuery(query, searchType, joins);
             }
             if (queries.length === 0) {
                 return [];
@@ -222,7 +241,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             const { results } = (await client.multiSearch.perform({
                 searches: dispatched.map(({ query }) => ({
                     collection,
-                    ...buildSearchParams({ ...query, orderBy: [], limit: 0, offset: 0 }, searchType, options),
+                    ...buildSearchParams({ ...query, orderBy: [], limit: 0, offset: 0 }, searchType, searchParamsOptions),
                 })),
             }));
             // One label lookup serves every successful facet result in the batch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.21.3",
+  "version": "0.23.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.18.3",
+    "@lde/search": "^0.20.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"
@@ -35,6 +35,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "^0.7.9",
-    "@lde/pipeline": "^0.35.6"
+    "@lde/pipeline": "^0.36.0"
   }
 }