@lde/search-api-graphql 0.21.1 → 0.23.0

package/dist/build-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../src/build-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAmBrB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAGvB,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACjE;AAED;2EAC2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC;yCACqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;uBACmB;IACnB,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,KACnB,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC;;kEAE8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;gDAE4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAqGD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CA4pBf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}
+{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../src/build-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAqBrB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAGvB,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACjE;AAED;2EAC2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC;yCACqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;uBACmB;IACnB,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,KACnB,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC;;kEAE8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;gDAE4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AA4GD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAsxBf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}

package/dist/build-schema.js

@@ -1,5 +1,5 @@
 import { GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString, printSchema, } from 'graphql';
-import { AND_KEY, DEFAULT_LABEL_FIELD, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, isAbsoluteIri, OR_KEY, isRangeFacet, labelFieldNameOf, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+import { AND_KEY, DEFAULT_LABEL_FIELD, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, isAbsoluteIri, OR_KEY, isRangeFacet, joinGraph, labelFieldNameOf, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
 import { defaultLanguageOrder, toLanguageStrings, } from './language.js';
 import { createFacetLoader } from './facet-batch.js';
 const nonNullListOf = (type) => new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(type)));
@@ -15,21 +15,28 @@ const scalarOutput = (scalar, field) => field.required === true ? new GraphQLNon
  * distinguishable. Consequence for consumers: a variable must be declared
  * `[IRI!]`, not `[String!]`, because GraphQL checks variable usage nominally.
  *
- * **Input coercion validates; output serialization does not.** Rejecting a bare
- * token on the way in is what turns `where: { material: { in: ["boerenbont"] } }`
- * from a silent empty result into an error saying why – the same job
- * `argsToQuery` already does for an out-of-range `perPage`.
+ * **It validates in both directions.** Rejecting a bare token on the way in is
+ * what turns `where: { material: { in: ["boerenbont"] } }` from a silent empty
+ * result into an error saying why – the same job `argsToQuery` already does for
+ * an out-of-range `perPage`. Outbound matters for the same reason: a type
+ * enforced in one direction only is not one a consumer can rely on, and the
+ * coarse discovery strategy reads `IRI` as the promise that a value is a
+ * selection key.
  *
- * It validates on the way **out** too, and deliberately: a type that is enforced
- * in one direction only is not a type a consumer can rely on, and the coarse
- * discovery strategy reads `IRI` as the promise that a value is a selection key.
- * Serving a non-IRI under it would make the promise false exactly where a
- * consumer acts on it. The projection applies the same rule at the source, so
- * the only way to reach this error is an index written before it existed – which
- * a reindex fixes, and which failing names instead of hiding.
+ * **Where a bad value is dropped rather than raised.** Raising is right where
+ * the value IS the document’s identity (`id`, a reference’s `id`): such a
+ * document cannot be selected, so serving it would hand back something
+ * unusable. It is wrong for a facet bucket – `value: IRI!` sits inside a chain
+ * of non-nulls up to the root field, so raising there nulls the WHOLE response
+ * and discards `items`, which is precisely what facet-batch.ts’s degradation
+ * contract forbids a supplementary sidebar count from doing. The facet
+ * resolvers therefore filter unselectable buckets out instead.
  *
  * What counts as an IRI is {@link isAbsoluteIri} – shared with the projection,
- * so the surface cannot promise something the index contradicts.
+ * which applies it on every route a reference value can take (graph path,
+ * `derive`, `from`, `transform`), so the surface cannot promise something the
+ * index contradicts and the outbound error is reachable only from an index
+ * written before that rule existed.
  */
 const iriScalar = new GraphQLScalarType({
     name: 'IRI',
@@ -133,7 +140,7 @@ export function buildGraphQLSchema(schema, options = {}) {
     // that selects it, with no `String`-to-`IRI` boundary in between – the
     // contract BooleanBucket already keeps for `is`.
     const iriBucket = new GraphQLObjectType({
-        name: 'IriBucket',
+        name: 'IRIBucket',
         fields: valueBucketFields(iriScalar),
     });
     // A numeric range-facet bin: half-open `[min, max)` bounds (max null on an
@@ -254,7 +261,28 @@ export function buildGraphQLSchema(schema, options = {}) {
     // collide: searchSchema resolves its typeName to a declared Reference Type
     // and rejects duplicate names schema-wide.
     const referenceTypes = new Map();
-    const takenTypeNames = new Set(rootTypeNames);
+    // Seeded with the shared types every schema carries, not just the root type
+    // names: a declaration is free to name a type `IRI` or `ValueBucket`, and
+    // without this it would pass both collision checks and fail at
+    // `new GraphQLSchema` with graphql-js’s “Schema must contain uniquely named
+    // types” – naming neither the declaration nor the field, which is the opaque
+    // failure these checks exist to replace.
+    const takenTypeNames = new Set([
+        ...rootTypeNames,
+        iriScalar.name,
+        keywordFilter.name,
+        iriFilter.name,
+        languageString.name,
+        valueBucket.name,
+        iriBucket.name,
+        rangeBucket.name,
+        booleanBucket.name,
+        paginationType.name,
+        sortDirection.name,
+        intRange.name,
+        floatRange.name,
+        dateRange.name,
+    ]);
     /** The label key each id-plus-label reference type was registered with; no
      *  entry for a surfaced inline one, which carries fields instead of a label. */
     const labelKeys = new Map();
@@ -268,6 +296,12 @@ export function buildGraphQLSchema(schema, options = {}) {
             ? DEFAULT_LABEL_FIELD
             : labelFieldNameOf(rootTypesByName.get(field.labelSource));
     }
+    // The declared joins, and the input types they make shareable. Each map is
+    // keyed by the SearchType `name`, so a type reached as a join target and the
+    // same type queried in its own right meet exactly one `‹Name›Where`.
+    const joins = joinGraph(schema);
+    const whereInputs = new Map();
+    const referenceFilters = new Map();
     /**
      * Register the GraphQL type one reference field is served as, once per
      * referenced shape. A **surfaced inline** reference is served as the nested
@@ -421,10 +455,22 @@ export function buildGraphQLSchema(schema, options = {}) {
                 };
         }
     }
+    function whereFieldType(field, owner) {
+        // A joinable reference is filterable in two ways at once – by the ids it
+        // holds, and by a condition on the referent – so it earns a richer input
+        // than the plain membership every other reference gets. Making the
+        // difference visible in the schema is the point: a consumer sees which
+        // references can be filtered through, instead of discovering it from a
+        // runtime error.
+        const target = joins.resolve(owner, [field.name]);
+        return target !== undefined
+            ? referenceFilterFor(target)
+            : plainWhereFieldType(field);
+    }
     /** The filter input one field accepts, fixed by what the field keys on: a
      *  `reference` keys on identity (its target’s filter, or `IRIFilter` when it
      *  names no target), a `keyword` on literals. */
-    function whereFieldType(field) {
+    function plainWhereFieldType(field) {
         switch (filterOperatorFor(field.kind)) {
             case 'in':
                 if (field.kind !== 'reference') {
@@ -443,58 +489,88 @@ export function buildGraphQLSchema(schema, options = {}) {
                 return GraphQLBoolean;
         }
     }
-    /** The root query field for one {@link RootType}, with its derived types. */
-    function rootField(searchType, typeOptions) {
-        const typeName = searchType.name;
-        const outputType = new GraphQLObjectType({
-            name: typeName,
-            fields: () => {
-                const fields = {
-                    id: { type: new GraphQLNonNull(iriScalar) },
-                };
-                for (const field of outputFields(searchType)) {
-                    fields[field.name] = outputFieldConfig(field);
-                }
-                return fields;
-            },
+    /**
+     * The filter input a joinable reference to `target` takes, created once per
+     * target type and shared by EVERY field pointing at it – `publisher` and
+     * `creator` both resolving to `Organization` take the same
+     * `OrganizationReferenceFilter`, because what it can express is a property of
+     * the referenced type, not of the referring field.
+     *
+     * `@oneOf`, so a criterion stays an atom: filter by the ids the field holds,
+     * **or** by a condition on the referent, never both in one term.
+     */
+    function referenceFilterFor(target) {
+        const existing = referenceFilters.get(target.name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = new GraphQLInputObjectType({
+            name: `${target.name}ReferenceFilter`,
+            description: `A condition on a joinable reference to ${target.name}: the ids it holds, or a condition on the referenced ${target.name} itself.`,
+            isOneOf: true,
+            // A thunk: the target’s own `where` may point back through further
+            // joinable references (the join graph is acyclic, so this terminates).
+            fields: () => ({
+                // `IRI`, exactly as `‹Target›Filter` types it: this arm asks the same
+                // question that filter asks – which of the target’s ids the field
+                // holds – so it must accept the same variable a consumer declares
+                // `[IRI!]` for. Typing it `String` here would make the join arm the
+                // one place identity is not `IRI`-keyed.
+                in: { type: new GraphQLList(new GraphQLNonNull(iriScalar)) },
+                where: { type: whereInputFor(target) },
+            }),
         });
-        // Every type is filterable on `id`, so the input always has at least one
-        // field and always exists – no type is unaddressable by IRI, whatever it
-        // declares.
-        const filterable = filterableFields(searchType);
-        /**
-         * One key per filterable field (plus the undeclared `id`), each typed by its
-         * OWN kind – so the operator a key accepts is fixed by the field it names,
-         * and a range on a keyword field cannot be written at all. This is the
-         * single vocabulary every level of `where` is built from: the same keys
-         * appear on the clause and on a criterion, so a field is never named a
-         * second way.
-         */
-        const fieldKeys = () => {
-            const fields = {
-                // Typed self-referentially – `TermWhere.id: TermFilter` – so a consumer
-                // can resolve “the collection I am browsing” to “the filter type that
-                // accepts its IRIs”, which is what makes the refined discovery strategy
-                // work without hardcoding a single domain name.
-                [ID_FIELD]: { type: targetFilter(typeName) },
-            };
-            for (const field of filterable) {
-                fields[field.name] = {
-                    type: whereFieldType(field),
-                    description: field.description,
-                };
-            }
-            return fields;
+        referenceFilters.set(target.name, created);
+        return created;
+    }
+    /**
+     * One key per filterable field (plus the undeclared `id`), each typed by its
+     * OWN kind – so the operator a key accepts is fixed by the field it names,
+     * and a range on a keyword field cannot be written at all. This is the
+     * single vocabulary every level of `where` is built from: the same keys
+     * appear on the clause and on a criterion, so a field is never named a
+     * second way.
+     */
+    function fieldKeys(searchType) {
+        const fields = {
+            // Typed self-referentially – `TermWhere.id: TermFilter` – so a consumer
+            // can resolve “the collection I am browsing” to “the filter type that
+            // accepts its IRIs”, which is what makes the refined discovery strategy
+            // work without hardcoding a single domain name.
+            [ID_FIELD]: { type: targetFilter(searchType.name) },
         };
+        for (const field of filterableFields(searchType)) {
+            fields[field.name] = {
+                type: whereFieldType(field, searchType),
+                description: field.description,
+            };
+        }
+        return fields;
+    }
+    /**
+     * The `where` input of one root type, created once and shared: it is both the
+     * argument of that type’s own query field and – through a
+     * {@link referenceFilterFor} – the shape a *joined* condition on it takes
+     * from another type. One input either way, so the vocabulary a consumer
+     * learns for `datasets(where: …)` is the same one they write inside
+     * `creativeWorks(where: { dataset: { where: … } })`.
+     */
+    function whereInputFor(searchType) {
+        const existing = whereInputs.get(searchType.name);
+        if (existing !== undefined) {
+            return existing;
+        }
         // A criterion is an ATOM: exactly one field, enforced by `@oneOf`. That is
         // what keeps `where` a flat conjunction of disjunctions – a criterion that
         // could carry two keys would be a conjunction nested inside an `or`, and
         // skip-own-filter (ADR 5) has no answer for a clause buried inside another.
+        // Created here rather than on its own, because it exists for exactly one
+        // `where` and shares its memoization.
         const criterionInput = new GraphQLInputObjectType({
-            name: `${typeName}Criterion`,
+            name: `${searchType.name}Criterion`,
             description: 'A condition on exactly one field. Used inside `or`, where the criteria are alternatives.',
             isOneOf: true,
-            fields: fieldKeys,
+            fields: () => fieldKeys(searchType),
         });
         const orKey = {
             type: new GraphQLList(new GraphQLNonNull(criterionInput)),
@@ -506,18 +582,41 @@ export function buildGraphQLSchema(schema, options = {}) {
         // `or` holds only `@oneOf` criteria. So `where` stays a flat conjunction of
         // disjunctions at any nesting depth, and a reader meets one input type
         // instead of two near-identical ones.
-        const whereInput = new GraphQLInputObjectType({
-            name: `${typeName}Where`,
+        const created = new GraphQLInputObjectType({
+            name: `${searchType.name}Where`,
             description: 'Sibling keys are combined with AND. Use `or` for a disjunction, and `and` when a query needs more than one of them.',
             fields: () => ({
-                ...fieldKeys(),
+                ...fieldKeys(searchType),
                 [OR_KEY]: orKey,
                 [AND_KEY]: {
-                    type: new GraphQLList(new GraphQLNonNull(whereInput)),
+                    type: new GraphQLList(new GraphQLNonNull(created)),
                     description: 'Further groups of conditions, all of which apply. The way to carry a second `or` disjunction alongside the first.',
                 },
             }),
         });
+        whereInputs.set(searchType.name, created);
+        return created;
+    }
+    /** The root query field for one {@link RootType}, with its derived types. */
+    function rootField(searchType, typeOptions) {
+        const typeName = searchType.name;
+        const outputType = new GraphQLObjectType({
+            name: typeName,
+            fields: () => {
+                const fields = {
+                    id: { type: new GraphQLNonNull(iriScalar) },
+                };
+                for (const field of outputFields(searchType)) {
+                    fields[field.name] = outputFieldConfig(field);
+                }
+                return fields;
+            },
+        });
+        // Every type is filterable on `id`, so the input always has at least one
+        // field and always exists – no type is unaddressable by IRI, whatever it
+        // declares. It may already have been created as a joined type’s filter
+        // shape; `whereInputFor` hands back the same instance either way.
+        const whereInput = whereInputFor(searchType);
         const sortValues = {
             RELEVANCE: { value: 'relevance' },
         };
@@ -540,7 +639,7 @@ export function buildGraphQLSchema(schema, options = {}) {
         });
         // Keyed facets object: one field per facetable field, typed by its kind
         // (range fields → [RangeBucket!], boolean fields → [BooleanBucket!],
-        // reference fields → [IriBucket!], else [ValueBucket!]). Only the selected
+        // reference fields → [IRIBucket!], else [ValueBucket!]). Only the selected
         // fields are resolved (GraphQL prunes the rest), so the selection IS the
         // request; how they are computed – skip-own-filter, batched into one
         // engine dispatch – lives in facet-batch.ts.
@@ -593,7 +692,7 @@ export function buildGraphQLSchema(schema, options = {}) {
                 },
             },
             resolve: async (_source, args, context) => {
-                const built = argsToQuery(args, context, searchType, maxPerPage);
+                const built = argsToQuery(args, context, searchType, maxPerPage, joins);
                 const finalQuery = typeOptions?.queryDefaults
                     ? typeOptions.queryDefaults(built, context)
                     : built;
@@ -634,12 +733,28 @@ export function buildGraphQLSchema(schema, options = {}) {
             fields: () => {
                 const fields = {};
                 for (const field of facetable) {
+                    const bucketType = bucketTypeFor(field);
                     fields[field.name] = {
-                        type: nonNullListOf(bucketTypeFor(field)),
+                        type: nonNullListOf(bucketType),
                         // The skip-own-filter query building, the batching into one
                         // engine dispatch and the degrade-to-[] error handling all live
                         // in the loader (facet-batch.ts).
-                        resolve: (source) => source.loadFacet(field.name),
+                        resolve: async (source) => {
+                            const buckets = await source.loadFacet(field.name);
+                            if (bucketType !== iriBucket) {
+                                return buckets;
+                            }
+                            // A bucket keyed on something that is not an IRI is not a
+                            // selection key – it cannot be sent back as the filter that
+                            // selects it – so it is dropped rather than served under `IRI`.
+                            // Dropping, not throwing: `value: IRI!` sits inside a chain of
+                            // non-nulls up to the root field, so a raising coercion here
+                            // would null the WHOLE response and take `items` with it, which
+                            // is exactly what facet-batch.ts’s degradation contract forbids
+                            // a supplementary sidebar count from doing.
+                            return buckets.filter((bucket) => typeof bucket.value === 'string' &&
+                                isAbsoluteIri(bucket.value));
+                        },
                     };
                 }
                 return fields;
@@ -673,7 +788,7 @@ export function printGraphQLSchema(schema, options = {}) {
 /** Pure args → {@link SearchQuery} mapping. Rejects out-of-bounds paging
  *  (`page < 1`, `perPage` outside `1..maxPerPage`) with a clear error – a
  *  negative offset or an unbounded page size must not reach the engine. */
-function argsToQuery(args, context, searchType, maxPerPage) {
+function argsToQuery(args, context, searchType, maxPerPage, joins) {
     const perPage = args.perPage ?? 20;
     const page = args.page ?? 1;
     if (page < 1) {
@@ -685,7 +800,7 @@ function argsToQuery(args, context, searchType, maxPerPage) {
     }
     return {
         text: args.query,
-        where: whereToFilters(args.where, searchType),
+        where: whereToFilters(args.where, searchType, joins),
         orderBy: args.orderBy
             ? [{ field: args.orderBy.field, direction: args.orderBy.direction }]
             : [],
@@ -696,18 +811,37 @@ function argsToQuery(args, context, searchType, maxPerPage) {
         locale: context.acceptLanguage[0] ?? 'und',
     };
 }
-function whereToFilters(where, searchType) {
+/**
+ * Compile one `Where` input into the flat conjunction of disjunctions the IR
+ * holds, at `on` hops out from the searched type (`[]` at the top level).
+ *
+ * A **joined** key carrying `where` recurses with the path extended by that
+ * key, and its clauses join this list – exactly how `and` already flattens. The
+ * result is still flat: the nesting lives in each criterion’s `on` path, never
+ * in the clause structure, so skip-own-filter (ADR 5) still scans one level.
+ */
+function whereToFilters(where, searchType, joins, on = []) {
     // `== null` deliberately: an explicit `where: null` is as absent as an omitted
     // one, and reading keys off it would throw.
     if (where == null) {
         return [];
     }
-    const filters = criteriaOf(where, searchType).map(filterOn);
+    const filters = [];
     // Sibling field keys AND, so each becomes a one-criterion filter of its own,
     // while `or` becomes a SINGLE filter carrying every alternative. That is the
     // whole AND/OR mapping: which bucket a criterion lands in, never a combinator
     // inferred from how deeply it is nested.
-    const alternatives = (where[OR_KEY] ?? []).flatMap((criterion) => criteriaOf(criterion, searchType));
+    for (const entry of keyEntriesOf(where, searchType, joins)) {
+        if ('nested' in entry) {
+            filters.push(...whereToFilters(entry.nested, entry.target, joins, [
+                ...on,
+                entry.name,
+            ]));
+            continue;
+        }
+        filters.push(filterOn(withPath(entry.criterion, on)));
+    }
+    const alternatives = (where[OR_KEY] ?? []).flatMap((criterion) => criteriaOf(criterion, searchType, joins, on));
     if (alternatives.length > 0) {
         filters.push({ or: alternatives });
     }
@@ -716,47 +850,105 @@ function whereToFilters(where, searchType) {
     // result flat: nested conjunctions collapse into this one list, and an `and`
     // can never sit inside an `or` (which holds only criteria).
     for (const nested of where[AND_KEY] ?? []) {
-        filters.push(...whereToFilters(nested, searchType));
+        filters.push(...whereToFilters(nested, searchType, joins, on));
     }
     return filters;
 }
+/** A criterion with its join path attached, or unchanged at the top level –
+ *  so an ordinary query’s IR is byte-for-byte what it was. */
+function withPath(criterion, on) {
+    return on.length === 0 ? criterion : { ...criterion, on };
+}
 /**
- * The criteria a keyed object carries, in declaration order. A `Criterion` is
- * `@oneOf`, so it yields exactly one; a `Where`/`Clause` yields one per field
- * key it sets. `id` is read first: no type declares it, so the field loop below
- * never sees it.
+ * The criteria a keyed object carries, in declaration order, `on` hops out. A
+ * `Criterion` is `@oneOf`, so it yields exactly one; a `Where` yields one per
+ * field key it sets.
+ *
+ * A joined key carrying `where` is compiled through {@link whereToFilters} and
+ * must come back as exactly ONE one-criterion clause. Anything else – two field
+ * keys, an `or`, an `and` – is a conjunction, and a conjunction cannot sit
+ * inside the `or` this feeds (ADR 18’s flat IR has nowhere to put it), so it is
+ * rejected with the rewrite that expresses it instead.
  */
-function criteriaOf(keyed, searchType) {
+function criteriaOf(keyed, searchType, joins, on = []) {
     const criteria = [];
+    for (const entry of keyEntriesOf(keyed, searchType, joins)) {
+        if (!('nested' in entry)) {
+            criteria.push(withPath(entry.criterion, on));
+            continue;
+        }
+        const path = [...on, entry.name];
+        const nested = whereToFilters(entry.nested, entry.target, joins, path);
+        const [only] = nested;
+        // An `or` alternative must be exactly one criterion. Empty and
+        // more-than-one are opposite mistakes, so they are named separately rather
+        // than sharing a message that fits only one of them.
+        if (only === undefined) {
+            throw new Error(`The joined condition on “${entry.name}” states no criterion, so it constrains nothing – and an “or” alternative that constrains nothing would make the whole disjunction match everything. Give it a condition, or leave the alternative out.`);
+        }
+        if (nested.length !== 1 || only.or.length !== 1) {
+            throw new Error(`The joined condition on “${entry.name}” states more than one criterion, so it is a conjunction – which cannot sit inside an “or”. Write one “or” alternative per criterion, or move the conjunction into “and”.`);
+        }
+        criteria.push(only.or[0]);
+    }
+    return criteria;
+}
+/**
+ * The field keys a keyed input sets, in declaration order. `id` is read first:
+ * no type declares it, so the field loop never sees it.
+ *
+ * A joinable reference takes a `‹Target›ReferenceFilter` rather than a plain
+ * `StringFilter`, and its two `@oneOf` arms mean different things: `in` filters
+ * by the ids the field itself holds – no join, the same membership every other
+ * reference gets – while `where` states a condition on the referent and yields
+ * a nested entry the caller walks into.
+ */
+function keyEntriesOf(keyed, searchType, joins) {
+    const entries = [];
     const id = keyed[ID_FIELD];
     if (id !== undefined && id !== null) {
-        criteria.push({ field: ID_FIELD, in: id.in ?? [] });
+        entries.push({ criterion: { field: ID_FIELD, in: id.in ?? [] } });
     }
     for (const field of filterableFields(searchType)) {
         const value = keyed[field.name];
         if (value === undefined || value === null) {
             continue;
         }
+        const target = joins.resolve(searchType, [field.name]);
+        if (target !== undefined) {
+            const nested = value
+                .where;
+            if (nested !== undefined && nested !== null) {
+                entries.push({ name: field.name, nested, target });
+                continue;
+            }
+        }
         switch (filterOperatorFor(field.kind)) {
             case 'in':
-                criteria.push({
-                    field: field.name,
-                    in: value.in ?? [],
+                entries.push({
+                    criterion: {
+                        field: field.name,
+                        in: value.in ?? [],
+                    },
                 });
                 break;
             case 'range': {
                 const range = value;
-                criteria.push({
-                    field: field.name,
-                    range: { min: range.min, max: range.max },
+                entries.push({
+                    criterion: {
+                        field: field.name,
+                        range: { min: range.min, max: range.max },
+                    },
                 });
                 break;
             }
             default:
-                criteria.push({ field: field.name, is: value });
+                entries.push({
+                    criterion: { field: field.name, is: value },
+                });
         }
     }
-    return criteria;
+    return entries;
 }
 function rangeInput(name, bound) {
     return new GraphQLInputObjectType({

package/dist/facet-batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facet-batch.d.ts","sourceRoot":"","sources":["../src/facet-batch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EAEX,QAAQ,EACR,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACrD,WAAW,CAoCb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,WAAW,EAAE,CAoBf"}
+{"version":3,"file":"facet-batch.d.ts","sourceRoot":"","sources":["../src/facet-batch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,WAAW,EAEX,QAAQ,EACR,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACrD,WAAW,CAoCb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,WAAW,EAAE,CAoBf"}

package/dist/facet-batch.js

@@ -115,7 +115,21 @@ function ownedField(filter) {
     if (first === undefined) {
         return undefined;
     }
-    return rest.every((criterion) => criterion.field === first.field)
-        ? first.field
-        : undefined;
+    const key = axisOf(first);
+    return rest.every((criterion) => axisOf(criterion) === key) ? key : undefined;
+}
+/**
+ * The axis one criterion constrains: its field, qualified by the join path it
+ * reaches that field through. Two criteria are the same axis only when both
+ * agree – `dataset.publisher` and a local `publisher` are different questions,
+ * so a selection on one is no selection on the other.
+ *
+ * Facets are not yet offered on joined fields, so a joined clause’s key can
+ * never equal a requested facet name and such a clause simply never drops. That
+ * falls out of the key rather than being a rule of its own, and stays right if
+ * joined facets land later.
+ */
+function axisOf(criterion) {
+    const on = criterion.on ?? [];
+    return on.length === 0 ? criterion.field : [...on, criterion.field].join('.');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "Engine- and domain-agnostic GraphQL surface for @lde/search: builds an executable GraphQLSchema from a whole SearchSchema at runtime (no codegen) – one root query field per SearchType – served by generic resolvers over any SearchEngine – and serves it as a framework-agnostic fetch handler with a self-contained playground, SDL endpoint, CORS and depth/cost limits. You supply the schema and per-type typeNames; it names neither your domain nor your engine.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -37,7 +37,7 @@
     "@escape.tech/graphql-armor-cost-limit": "^2.4.3",
     "@escape.tech/graphql-armor-max-depth": "^2.4.2",
     "@graphql-yoga/render-graphiql": "^5.21.2",
-    "@lde/search": "^0.19.0",
+    "@lde/search": "^0.21.0",
     "commander": "^15.0.0",
     "dataloader": "^2.2.3",
     "graphql": "^16.9.0",