@lde/search 0.28.1 → 0.30.0

package/dist/adapter.d.ts

@@ -6,7 +6,7 @@
  * deployment author declaring a schema and running searches needs none of
  * this; the main entry point carries that (small) authoring surface.
  */
-export { assertTypeInSchema, physicalFields, irAlias, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, isInlineReference, nestedReferenceType, nestedFieldName, localLookupTypeOf, identityFieldOf, identityFieldName, referenceFields, referenceTypeNamed, rootTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, labelSourceNameOf, labelTargetNameOf, documentKeyOf, DEFAULT_LABEL_FIELD, isRangeFacet, isAbsoluteIri, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, irAlias, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, isInlineReference, nestedReferenceType, nestedFieldName, localLookupTargetsOf, referencedTargetsOf, storedTargetOf, TARGET_FIELD, identityFieldOf, identityFieldName, referenceFields, referenceTypeNamed, rootTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, labelSourceNamesOf, labelTargetNamesOf, documentKeyOf, DEFAULT_LABEL_FIELD, isRangeFacet, isBinnedRangeFacet, isAbsoluteIri, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export type { PhysicalFields } from './schema.js';
 export { physicalNameTokens } from './physical-name.js';
 export { matchLanguage } from './language.js';

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/adapter.js

@@ -6,7 +6,7 @@
  * deployment author declaring a schema and running searches needs none of
  * this; the main entry point carries that (small) authoring surface.
  */
-export { assertTypeInSchema, physicalFields, irAlias, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, isInlineReference, nestedReferenceType, nestedFieldName, localLookupTypeOf, identityFieldOf, identityFieldName, referenceFields, referenceTypeNamed, rootTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, labelSourceNameOf, labelTargetNameOf, documentKeyOf, DEFAULT_LABEL_FIELD, isRangeFacet, isAbsoluteIri, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, irAlias, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, isInlineReference, nestedReferenceType, nestedFieldName, localLookupTargetsOf, referencedTargetsOf, storedTargetOf, TARGET_FIELD, identityFieldOf, identityFieldName, referenceFields, referenceTypeNamed, rootTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, labelSourceNamesOf, labelTargetNamesOf, documentKeyOf, DEFAULT_LABEL_FIELD, isRangeFacet, isBinnedRangeFacet, isAbsoluteIri, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export { physicalNameTokens } from './physical-name.js';
 export { matchLanguage } from './language.js';
 export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';

package/dist/engine.d.ts

@@ -41,7 +41,7 @@ export interface SearchEngine<Types extends readonly SearchType[] = readonly Sea
      * Typesense `multi_search`), returning one {@link FacetsOutcome} per query,
      * positionally aligned with `queries`. This is what keeps a faceted
      * listing – one skip-own-filter query variant per filtered facet – from
-     * fanning out into per-facet engine calls. Only facet buckets come back: an
+     * fanning out into per-facet engine calls. Only facets come back: an
      * engine answers every query in the batch facet-only (as if `limit: 0` and
      * without ordering, whatever the query carries), so hits are never
      * transferred. Reference-facet buckets carry resolved labels exactly as in
@@ -56,7 +56,7 @@ export interface SearchEngine<Types extends readonly SearchType[] = readonly Sea
 }
 /**
  * One query’s outcome in a {@link SearchEngine.searchFacets} batch – its
- * facet buckets, or the error that failed it. The `allSettled`-style shape
+ * facets, or the error that failed it. The `allSettled`-style shape
  * keeps one failed query (e.g. one failed `multi_search` entry) from
  * discarding its siblings’ results: a caller degrades exactly the facets of
  * the failed query. Discriminate with `'error' in outcome`.
@@ -73,10 +73,36 @@ export interface SearchResult<FacetField extends string = string, OutputField ex
     readonly facets: FacetMap<FacetField>;
 }
 /**
- * Facet buckets keyed by facet field name. `Partial` because a result carries
- * buckets only for the fields the query asked for, not every facetable field.
+ * Facets keyed by facet field name. `Partial` because a result carries a facet
+ * only for the fields the query asked for, not every facetable field.
  */
-export type FacetMap<FacetField extends string = string> = Readonly<Partial<Record<FacetField, readonly FacetBucket[]>>>;
+export type FacetMap<FacetField extends string = string> = Readonly<Partial<Record<FacetField, Facet>>>;
+/**
+ * One facet over the documents a query matches: its buckets and, for a
+ * numeric (`integer`/`number`/`date`) field, the extent of the values those
+ * documents hold – the bounds a range slider needs.
+ *
+ * A facet buckets per distinct value, or – a numeric field declaring
+ * `facetRanges` – into those bins. Only a numeric facet has an extent.
+ */
+export interface Facet {
+    readonly buckets: readonly FacetBucket[];
+    /**
+     * The lowest and highest value among the matching documents, for a numeric
+     * facet. Absent on any other facet, and when no matching document holds a
+     * value.
+     */
+    readonly extent?: FacetExtent;
+}
+/**
+ * The lowest and highest value a range facet’s documents hold, stored terms
+ * like every other value at this seam: a `date` in Unix seconds, which a
+ * surface serves as ISO 8601 the way it serves the field itself.
+ */
+export interface FacetExtent {
+    readonly min: number;
+    readonly max: number;
+}
 /**
  * The facet-field-name union of a search type – the keys a {@link SearchResult}’s
  * `facets` can hold. Narrow for a declaration captured as a literal (via
@@ -133,7 +159,22 @@ export type SearchValue = string | number | boolean | readonly string[] | Locali
  */
 export interface NestedDocument {
     readonly [field: string]: SearchValue | undefined;
+    /**
+     * The `name` of the Root Type this document is read through, where the
+     * field that carries it is a `lookup` naming **several** targets – the
+     * declaration it was resolved or stored against. Such a lookup serves
+     * referents of any of its targets under one field, and this is what tells a
+     * surface which one each referent is, so it can type the value per referent
+     * instead of claiming one kind for all of them. Absent where there is
+     * nothing to tell apart: a single-target lookup, or an inline reference’s
+     * entry. Keyed by a symbol so it can never collide with a declared field
+     * name.
+     */
+    readonly [NESTED_DOCUMENT_TYPE]?: string;
 }
+/** The key under which a {@link NestedDocument} carries the `name` of the
+ *  Root Type it is read through. */
+export declare const NESTED_DOCUMENT_TYPE: unique symbol;
 /**
  * A JSON-LD-style language map (`@container: @language`, `@set` arrays); the key
  * `und` carries untagged (`@none`) values. The surface flattens it to a

package/dist/engine.d.ts.map

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

package/dist/engine.js

@@ -1 +1,3 @@
-export {};
+/** The key under which a {@link NestedDocument} carries the `name` of the
+ *  Root Type it is read through. */
+export const NESTED_DOCUMENT_TYPE = Symbol('lde.search.nestedDocumentType');

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
 export type { JoinGraph } from './join-graph.js';
 export { filterOn } from './query.js';
 export type { SearchQuery, ReferenceProjection, Filter, Criterion, CriterionBase, WeldedCriterion, Sort, } from './query.js';
-export type { SearchEngine, SearchResult, SearchHit, ResultDocument, SearchValue, LocalizedValue, Reference, NestedDocument, FacetBucket, FacetMap, FacetsOutcome, FacetFieldsOf, OutputFieldsOf, } from './engine.js';
+export { NESTED_DOCUMENT_TYPE } from './engine.js';
+export type { SearchEngine, SearchResult, SearchHit, ResultDocument, SearchValue, LocalizedValue, Reference, NestedDocument, Facet, FacetBucket, FacetExtent, FacetMap, FacetsOutcome, FacetFieldsOf, OutputFieldsOf, } from './engine.js';
 export type { FramedNode } from './frame-by-type.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":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAKtB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,OAAO,EACP,MAAM,EAMN,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOjD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,MAAM,EACN,SAAS,EACT,aAAa,EACb,eAAe,EACf,IAAI,GACL,MAAM,YAAY,CAAC;AAIpB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,SAAS,EACT,cAAc,EACd,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAKtB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,OAAO,EACP,MAAM,EAMN,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOjD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,MAAM,EACN,SAAS,EACT,aAAa,EACb,eAAe,EACf,IAAI,GACL,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -27,3 +27,6 @@ export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
 // policy (`queryDefaults`) appends to `where`, so it belongs on the authoring
 // surface and not only on the adapter one.
 export { filterOn } from './query.js';
+// Engine port + the logical result document returned across it. An engine is
+// bound to the whole SearchSchema at construction by its adapter factory.
+export { NESTED_DOCUMENT_TYPE } from './engine.js';

package/dist/join-graph.js

@@ -1,4 +1,4 @@
-import { labelSourceNameOf, referenceFields, } from './schema.js';
+import { labelSourceNamesOf, referenceFields, } from './schema.js';
 /**
  * The deepest `on` path a query may state: `dataset → publisher → country` is
  * three hops. Fixed rather than configurable, and enforced in the query IR
@@ -103,7 +103,9 @@ function declaredEdges(searchType, byName) {
         // field, which a Reference Type cannot carry (a nested field is `output`
         // only). So a joinable edge always has a collection at the far end without
         // a rule of its own.
-        const target = byName.get(labelSourceNameOf(field));
+        // One target, never several: `validateSearchType` refuses `joinable` on a
+        // reference naming more than one.
+        const target = byName.get(labelSourceNamesOf(field)[0]);
         const claimed = claimedBy.get(target.name);
         if (claimed !== undefined) {
             throw new Error(`Search type “${searchType.name}” declares two joinable references to “${target.name}” (“${claimed}” and “${field.name}”); an engine addresses a join by collection, not by field, so only one reference per target can be joinable. Drop “joinable” from one of them – it keeps its labels, facets and id filtering.`);

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAkBL,KAAK,eAAe,EAEpB,KAAK,QAAQ,EAEb,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO,CAChD,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAC1C;IACC,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,YAAY,EACrB,OAAO,GAAE,iBAAyC,GACjD,cAAc,CAgBhB;AAwKD;;;;;;;;;;;;GAYG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,EACpB,OAAO,GAAE,iBAAyC,GACjD,aAAa,CAAC,cAAc,CAAC,CAc/B"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAoBL,KAAK,eAAe,EAIpB,KAAK,QAAQ,EAEb,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO,CAChD,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAC1C;IACC,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,YAAY,EACrB,OAAO,GAAE,iBAAyC,GACjD,cAAc,CAgBhB;AAmLD;;;;;;;;;;;;GAYG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,EACpB,OAAO,GAAE,iBAAyC,GACjD,aAAa,CAAC,cAAc,CAAC,CAc/B"}

package/dist/project.js

@@ -1,7 +1,7 @@
 import { fold } from '@lde/text-normalization';
 import { matchLanguage } from './language.js';
 import { buildSubjectIndex, frameSubjects, } from './frame-by-type.js';
-import { assertTypeInSchema, displayFieldName, documentKeyOf, fieldNamed, inheritedFacetKeys, inlineFramingDepth, irAlias, isAbsoluteIri, isInternalField, isInlineReference, isoToUnixSeconds, labelSourceNameOf, localLookupTypeOf, physicalFields, referenceTypeNamed, rootTypeNamed, } from './schema.js';
+import { assertTypeInSchema, displayFieldName, documentKeyOf, fieldNamed, identityFieldOf, inheritedFacetPolicies, inlineFramingDepth, irAlias, isAbsoluteIri, isInternalField, isInlineReference, isoToUnixSeconds, localLookupTargetsOf, physicalFields, referencedTargetsOf, referenceTypeNamed, storedTargetOf, TARGET_FIELD, } from './schema.js';
 /** The context a projection runs with when its caller supplied none. */
 const NO_PROJECTION_CONTEXT = {};
 /**
@@ -65,19 +65,21 @@ function pruneInternalFields(document, searchType, schema) {
         if (schema === undefined || field.kind !== 'reference') {
             continue;
         }
-        const nestedType = field.ref?.strategy === 'inline'
-            ? referenceTypeNamed(schema, field.ref.typeName)
-            : localLookupTypeOf(field, schema);
+        const nestedTypes = field.ref?.strategy === 'inline'
+            ? [referenceTypeNamed(schema, field.ref.typeName)].filter((type) => type !== undefined)
+            : localLookupTargetsOf(field, schema);
         const nested = document[field.name];
-        if (nestedType === undefined || nested === undefined) {
+        if (nestedTypes.length === 0 || nested === undefined) {
             continue;
         }
         for (const referent of Array.isArray(nested) ? nested : [nested]) {
-            pruneInternalFields(referent, nestedType, schema);
+            pruneInternalFields(referent, nestedTypes.length === 1
+                ? nestedTypes[0]
+                : storedTargetOf(referent, nestedTypes), schema);
         }
         // Two entries that differed only in their node IRI are one entry now that
         // it is gone – two edge nodes stating the same fact.
-        if (nestedType.class === undefined && Array.isArray(nested)) {
+        if (nestedTypes[0].class === undefined && Array.isArray(nested)) {
             document[field.name] = dedupeBy(nested, (referent) => JSON.stringify(referent));
         }
     }
@@ -254,9 +256,9 @@ function applyField(document, node, field, searchType, schema, context, nested)
     // is an entry like any other, minus its `id`. Same reason as above for
     // needing a schema: without one there is no target to project through.
     if (field.kind === 'reference' && schema !== undefined) {
-        const localType = localLookupTypeOf(field, schema);
-        if (localType !== undefined) {
-            const endpoints = applyNestedReferents(document, valuesOf(node, alias), field, localType, schema, context);
+        const localTargets = localLookupTargetsOf(field, schema);
+        if (localTargets.length > 0) {
+            const endpoints = applyNestedReferents(document, valuesOf(node, alias), field, localTargets, schema, context);
             // A `local` lookup stores an object, so its own id is a level deeper than
             // a filter can reach – an engine welds conditions on an entry's LEAF
             // fields only. `filterable` therefore fans out the id beside the object,
@@ -270,8 +272,12 @@ function applyField(document, node, field, searchType, schema, context, nested)
             return applyText(document, langValuesOf(node, alias), field);
         case 'keyword':
             return applyFacet(document, literalsOf(node, alias), field, schema);
-        case 'reference':
-            return applyFacet(document, referenceValues(node, alias, field, schema), field, schema);
+        case 'reference': {
+            const targetsById = new Map();
+            const values = referenceValues(node, alias, field, schema, targetsById);
+            rememberTargets(document, targetsById);
+            return applyFacet(document, values, field, schema, targetsById);
+        }
         case 'integer':
             return setNumber(document, field.name, toInteger(firstLiteralOf(node, alias)));
         case 'number':
@@ -316,27 +322,87 @@ function applyField(document, node, field, searchType, schema, context, nested)
  * referent’s node IRIs therefore sees a key instead, which is why the two are
  * worth declaring together only deliberately.
  */
-function referenceValues(node, alias, field, schema) {
-    const targetName = labelSourceNameOf(field);
-    if (schema === undefined || targetName === undefined) {
-        return irisOf(node, alias);
-    }
+function referenceValues(node, alias, field, schema, targetsById) {
     // Guaranteed declared: `searchSchema` validates that every named target
     // resolves, and the projection only ever runs against a type of its schema.
-    const target = rootTypeNamed(schema, targetName);
-    if (target.key === undefined) {
+    const targets = referencedTargetsOf(field, schema);
+    if (targets.length === 0) {
         return irisOf(node, alias);
     }
-    const keyFieldName = target.key.field;
     return valuesOf(node, alias)
         .map((value) => {
         const iri = iriString(value);
-        return iri === undefined
-            ? undefined
-            : documentKeyOf(target, iri, isObject(value) ? keyCandidatesOf(value, target, keyFieldName) : []);
+        if (iri === undefined) {
+            return undefined;
+        }
+        // Each referent is re-keyed through the target IT belongs to – the one
+        // its `rdf:type` matches – so a person keyed on an authority IRI and an
+        // organization keyed on nothing store, under one field, the ids their
+        // own collections file them under.
+        const target = targetOfReferent(value, targets);
+        const keyed = target.key === undefined
+            ? iri
+            : documentKeyOf(target, iri, isObject(value)
+                ? keyCandidatesOf(value, target, target.key.field)
+                : []);
+        // Remembered only where there was a choice: a single-target reference
+        // stays byte-identical to what it was, symbol keys included. Keyed by
+        // what the field STORES – the value after its own `transform`, which
+        // `applyFacet` applies before it reads this map.
+        if (keyed !== undefined && targets.length > 1) {
+            targetsById.set(field.transform === undefined ? keyed : field.transform(keyed), target);
+        }
+        return keyed;
     })
         .filter((value) => value !== undefined);
 }
+/**
+ * The Root Type a framed referent belongs to, among the targets its reference
+ * names: the first whose `class` is among the referent’s `rdf:type`s, which
+ * the extraction emits and framing carries as `@type`; else the first target
+ * declared. One target needs no evidence at all. This is the one reading of
+ * *which of several targets is this*, so re-keying, the facet policy and the
+ * stored discriminator ({@link TARGET_FIELD}) cannot disagree.
+ */
+function targetOfReferent(value, targets) {
+    if (targets.length === 1 || !isObject(value)) {
+        return targets[0];
+    }
+    const raw = value['@type'];
+    const classes = new Set((Array.isArray(raw) ? raw : [raw]).filter((type) => typeof type === 'string'));
+    return targets.find((target) => classes.has(target.class)) ?? targets[0];
+}
+/**
+ * The targets the reference values of a projected node were resolved through,
+ * by id – kept beside the node under a symbol, so it never reaches the
+ * writer, for the one reader that needs it after projection: the identity
+ * companion of an inline reference, which admits an entry’s id to a facet by
+ * the policy of the target that id belongs to. Only a reference naming
+ * several targets has anything to remember.
+ */
+const REFERENT_TARGETS = Symbol('referentTargets');
+function rememberTargets(document, targetsById) {
+    if (targetsById.size === 0) {
+        return;
+    }
+    const node = document;
+    const remembered = (node[REFERENT_TARGETS] ??= new Map());
+    for (const [id, target] of targetsById) {
+        remembered.set(id, target);
+    }
+}
+/**
+ * Whether an id deserves a facet bucket, by the {@link FacetKeys facet policy}
+ * of the target it belongs to: admitted where that target declares none, and
+ * by its `only` where it does. `targetName` is the target the id was resolved
+ * or stored against; an id whose target is unknown falls back to the first
+ * declared, the same precedence every other reading of several targets uses.
+ */
+function admitsFacet(policies, targets, targetName, id) {
+    // Policies are inherited from targets, so where any exists a target does.
+    const policy = policies.get(targetName ?? targets[0].name);
+    return policy === undefined || policy.only(id);
+}
 /**
  * Project a text field. **Display** (when `output`) preserves *every* language
  * present – one label per language, or every label of it for an `array` field
@@ -450,7 +516,7 @@ function foldedSearchValue(values) {
  * already-read raw values).
  *
  * A reference inheriting a {@link FacetKeys facet policy} from the type it
- * names ({@link inheritedFacetKeys}) also writes the `${name}_facet` companion
+ * names ({@link inheritedFacetPolicies}) also writes the `${name}_facet` companion
  * the engine facets instead of the field: the subset of **what the field
  * stores** that the policy admits. So it is written after the field’s own
  * `transform` and the IRI filter, from the same `values` – for a keyed target
@@ -469,7 +535,7 @@ function foldedSearchValue(values) {
  * engine rejects, or – where it does not type-check, as inside a nested
  * document – a value the API cannot serialize.
  */
-function applyFacet(document, raw, field, schema) {
+function applyFacet(document, raw, field, schema, targetsById) {
     // A `reference` stores identity, so what it stores must be an IRI whatever
     // route the value arrived by. {@link iriString} guards the graph path, but a
     // `transform` runs after it and a `from` projection value never passes it at
@@ -481,21 +547,25 @@ function applyFacet(document, raw, field, schema) {
     const folded = dedupe(values.map((value) => fold(value)));
     const names = physicalFields(field, schema);
     const searchField = names.search[0];
-    const policy = inheritedFacetKeys(field, schema);
+    const policies = inheritedFacetPolicies(field, schema);
+    const inherited = policies.size > 0;
     // `names.facet` is the companion exactly when a policy is inherited –
-    // physicalFields reads the same `inheritedFacetKeys`.
+    // physicalFields reads the same `inheritedFacetPolicies`.
     const facetField = names.facet;
     // The companion is a subset of what the field STORES – for a single-valued
     // field its first value, not the first admitted of all of them, or the facet
     // would count a value no filter on the field can reproduce.
     const stored = field.array === true ? values : values.slice(0, 1);
-    const admitted = policy === undefined ? [] : stored.filter(policy.only);
+    const targets = referencedTargetsOf(field, schema);
+    const admitted = !inherited
+        ? []
+        : stored.filter((id) => admitsFacet(policies, targets, targetsById?.get(id)?.name, id));
     if (field.array === true) {
         setArray(document, field.name, stored);
         if (field.searchable) {
             setArray(document, searchField, folded);
         }
-        if (policy !== undefined) {
+        if (inherited) {
             setArray(document, facetField, admitted);
         }
         return;
@@ -504,7 +574,7 @@ function applyFacet(document, raw, field, schema) {
     if (field.searchable) {
         setString(document, searchField, folded[0]);
     }
-    if (policy !== undefined) {
+    if (inherited) {
         setString(document, facetField, admitted[0]);
     }
 }
@@ -555,7 +625,7 @@ function applyInlineReference(document, node, alias, field, schema, context, nes
     if (referenceType === undefined) {
         return;
     }
-    const referents = applyNestedReferents(document, valuesOf(node, alias), field, referenceType, schema, context);
+    const referents = applyNestedReferents(document, valuesOf(node, alias), field, [referenceType], schema, context);
     applyIdentityCompanion(document, referents, field, schema, nested);
 }
 /**
@@ -584,11 +654,24 @@ function applyIdentityCompanion(document, referents, field, schema, nested) {
     // keeps the first referent and drops the rest, and a companion holding an id
     // from a dropped one would match a filter whose hit shows no such entry.
     const stored = field.array === true ? referents : referents.slice(0, 1);
-    const ids = dedupe(stored.flatMap((referent) => (Array.isArray(referent[identity])
-        ? referent[identity]
-        : [referent[identity]])
-        .map(identityValue)
-        .filter((id) => id !== undefined)));
+    // Each id with the target it was resolved through, for the facet policy
+    // below: a stored endpoint says so itself ({@link TARGET_FIELD}), a bare id
+    // was remembered when the entry was projected ({@link rememberTargets}).
+    const targetById = new Map();
+    for (const referent of stored) {
+        const remembered = referent[REFERENT_TARGETS];
+        const raw = referent[identity];
+        for (const value of Array.isArray(raw) ? raw : [raw]) {
+            const id = identityValue(value);
+            if (id === undefined || targetById.has(id)) {
+                continue;
+            }
+            targetById.set(id, isObject(value) && typeof value[TARGET_FIELD] === 'string'
+                ? value[TARGET_FIELD]
+                : remembered?.get(id)?.name);
+        }
+    }
+    const ids = [...targetById.keys()];
     if (ids.length === 0) {
         return;
     }
@@ -596,9 +679,10 @@ function applyIdentityCompanion(document, referents, field, schema, nested) {
     // Same rule as every other facetable reference: where the target declares a
     // facet policy, the facet reads a narrowed companion of its own, so an
     // excluded id is never seen by the engine rather than merely unlabelled.
-    const policy = inheritedFacetKeys(field, schema);
-    if (policy !== undefined) {
-        setIdentity(document, names.facet, ids.filter(policy.only), field, nested);
+    const policies = inheritedFacetPolicies(field, schema);
+    if (policies.size > 0) {
+        const targets = referencedTargetsOf(identityFieldOf(field, schema), schema);
+        setIdentity(document, names.facet, ids.filter((id) => admitsFacet(policies, targets, targetById.get(id), id)), field, nested);
     }
 }
 /**
@@ -676,14 +760,27 @@ function identityValue(value) {
  * top-level document of that type would be – so the stored id is the one the
  * target’s collection files it under, and the lookup can find it.
  */
-function applyNestedReferents(document, values, field, nestedType, schema, context) {
+function applyNestedReferents(document, values, field, nestedTypes, schema, context) {
     // One node may stand for several entries: a weldable leaf is single-valued,
     // so an edge the graph gave several roles or several endpoints fans out into
     // one entry per combination BEFORE it is projected (ADR 26).
     const referents = values
         .filter(isObject)
-        .flatMap((value) => tuplesOf(value, nestedType, field))
-        .map((tuple) => projectFields(tuple, nestedType, schema, context, true))
+        .flatMap((value) => {
+        // A lookup naming several targets projects each referent through the
+        // one it belongs to, and stores which – so an engine adapter can read
+        // an entry no collection answers for through the right declaration.
+        const nestedType = nestedTypes.length === 1
+            ? nestedTypes[0]
+            : targetOfReferent(value, nestedTypes);
+        return tuplesOf(value, nestedType, field).map((tuple) => {
+            const projected = projectFields(tuple, nestedType, schema, context, true);
+            if (nestedTypes.length > 1 && Object.keys(projected).length > 0) {
+                projected[TARGET_FIELD] = nestedType.name;
+            }
+            return projected;
+        });
+    })
         // Fields, not identity, are what makes something a referent: a literal
         // value object under the alias (dirty source data), or a node this
         // reference type reads nothing from, projects nothing and is no referent.

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAClC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;gEAC4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,MAAM,CACJ,MAAM,EACN;IACE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC,CACF,CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GACjB,CAAC,aAAa,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACpD,CAAC,aAAa,GAAG;IACf,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAChC,CAAC;CACH,CAAC,GACF,CAAC,aAAa,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC,GAC1C,CAAC,aAAa,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC,CAAC;AAEF,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,IAAI,eAAe,CAE3E;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,EAAE,EAAE,SAAS,SAAS,EAAE,CAAC;CACnC;AAED,+BAA+B;AAC/B,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CACpC;AAKD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,cAAc,CAEnE;AAED;wDACwD;AACxD,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAW3D;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;6EACyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EACX,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,eAAe;IACjB;oEACgE;OAC9D,eAAe;IACjB;0EACsE;OACpE,cAAc;IAChB;;;;;;;;;;OAUG;OACD,iBAAiB;IACnB,uEAAuE;OACrE,gBAAgB;IAClB;;;;OAIG;OACD,cAAc;IAChB;;;;;;;;;OASG;OACD,mBAAmB,CAAC;CACzB;AAiDD;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B;sEACkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,SAAS,GAChB,YAAY,GAAG,WAAW,CAkC5B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,SAAS,GAChB,SAAS,UAAU,EAAE,CA+FvB;AAqFD;yEACyE;AACzE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,SAAS,GAChB,IAAI,CAaN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/query.js

@@ -1,4 +1,4 @@
-import { fieldNamed, filterOperatorFor, ID_FIELD, isoToUnixSeconds, nestedReferenceType, } from './schema.js';
+import { fieldNamed, filterOperatorFor, ID_FIELD, isoToUnixSeconds, nestedReferenceType, referencedTargetsOf, } from './schema.js';
 import { MAX_JOIN_DEPTH } from './join-graph.js';
 /** Whether a criterion welds conditions to one entry ({@link WeldedCriterion}). */
 export function isWelded(criterion) {
@@ -261,7 +261,7 @@ export function validateQuery(query, searchType, schema, joins) {
             issues.push({ part: 'facets', field: name, reason: 'not-facetable' });
         }
     }
-    collectProjectionIssues(query.resolve, searchType, schema, issues);
+    collectProjectionIssues(query.resolve, [searchType], schema, issues);
     for (const sort of query.orderBy) {
         if (sort.field !== 'relevance' &&
             fieldNamed(searchType, sort.field) === undefined) {
@@ -289,35 +289,52 @@ export function validateQuery(query, searchType, schema, joins) {
  * target that does not exist, so reporting it too would bury the one mistake
  * under its consequences.
  */
-function collectProjectionIssues(projection, searchType, schema, issues) {
+function collectProjectionIssues(projection, searchTypes, schema, issues) {
     for (const [name, level] of Object.entries(projection ?? {})) {
-        const field = fieldNamed(searchType, name);
-        if (field === undefined) {
+        // A level is read against every type it may be reached through: a lookup
+        // naming several targets resolves a referent of any of them, so the level
+        // below is valid wherever ANY of those targets serves it – a field one
+        // target declares and another does not is exactly what a polymorphic
+        // selection asks for.
+        const fields = searchTypes
+            .map((searchType) => fieldNamed(searchType, name))
+            .filter((field) => field !== undefined);
+        if (fields.length === 0) {
             issues.push({ part: 'resolve', field: name, reason: 'unknown-field' });
             continue;
         }
         // Descending into an inline reference is free, so a nested level is valid
         // wherever the entries exist – what it is *for* is the lookup below it.
-        const nested = nestedReferenceType(schema, field);
-        if (nested !== undefined) {
+        // `searchSchema` holds the targets of one lookup to one declaration per
+        // name, so a name is nested or a lookup, never both; each is still read
+        // on its own here rather than one deciding for the other.
+        const nested = [];
+        for (const field of fields) {
+            const referenceType = nestedReferenceType(schema, field);
+            if (referenceType !== undefined) {
+                nested.push(referenceType);
+            }
+        }
+        if (nested.length > 0) {
             collectProjectionIssues(level.resolve, nested, schema, issues);
-            continue;
         }
-        if (field.kind !== 'reference' || field.ref?.strategy !== 'lookup') {
-            issues.push({ part: 'resolve', field: name, reason: 'not-resolvable' });
+        const lookups = fields.filter((field) => field.kind === 'reference' && field.ref?.strategy === 'lookup');
+        if (lookups.length === 0) {
+            if (nested.length === 0) {
+                issues.push({ part: 'resolve', field: name, reason: 'not-resolvable' });
+            }
             continue;
         }
-        const targetName = field.ref.target;
-        const target = [...schema.values()].find((rootType) => rootType.name === targetName);
-        if (target === undefined) {
+        const targets = lookups.flatMap((field) => referencedTargetsOf(field, schema));
+        if (targets.length === 0) {
             // searchSchema rejects a lookup whose target it cannot resolve, so this
             // is a query built against a different schema than the engine serves.
             issues.push({ part: 'resolve', field: name, reason: 'not-resolvable' });
             continue;
         }
         for (const wanted of level.fields ?? []) {
-            const targetField = fieldNamed(target, wanted);
-            if (targetField === undefined || targetField.output !== true) {
+            const served = targets.some((target) => fieldNamed(target, wanted)?.output === true);
+            if (!served) {
                 issues.push({
                     part: 'resolve',
                     field: `${name}.${wanted}`,
@@ -325,7 +342,7 @@ function collectProjectionIssues(projection, searchType, schema, issues) {
                 });
             }
         }
-        collectProjectionIssues(level.resolve, target, schema, issues);
+        collectProjectionIssues(level.resolve, targets, schema, issues);
     }
 }
 /** Throw on the first structurally invalid query part ({@link validateQuery}),