@lde/search 0.23.2 → 0.24.0

package/dist/adapter.d.ts

@@ -6,11 +6,11 @@
  * 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, referenceFields, referenceTypeNamed, rootTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, labelSourceNameOf, 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, 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 type { PhysicalFields } from './schema.js';
 export { physicalNameTokens } from './physical-name.js';
 export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
 export type { JoinGraph } from './join-graph.js';
-export { filterOperatorFor, filterOperator, filterOn, isUnsatisfiable, validateQuery, assertValidQuery, pageForOffset, } from './query.js';
-export type { FilterOperator, QueryIssue } from './query.js';
+export { filterOperatorFor, filterOperator, filterOn, isWelded, isUnsatisfiable, validateQuery, assertValidQuery, resolvePath, pageForOffset, } from './query.js';
+export type { FilterOperator, QueryIssue, ResolvedPath, PathFailure, } from './query.js';
 //# sourceMappingURL=adapter.d.ts.map

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,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,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,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,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,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,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, referenceFields, referenceTypeNamed, rootTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, labelSourceNameOf, 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, 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 { physicalNameTokens } from './physical-name.js';
 export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
-export { filterOperatorFor, filterOperator, filterOn, isUnsatisfiable, validateQuery, assertValidQuery, pageForOffset, } from './query.js';
+export { filterOperatorFor, filterOperator, filterOn, isWelded, isUnsatisfiable, validateQuery, assertValidQuery, resolvePath, pageForOffset, } from './query.js';

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { FieldKind, SearchField, SearchFieldBase, TextField, KeywordField,
 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, Sort, } 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 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,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,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"}

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;AAEzC,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAiBL,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;AAmHD;;;;;;;;;;;;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;AAEzC,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;AAsHD;;;;;;;;;;;;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,6 +1,6 @@
 import { fold } from '@lde/text-normalization';
 import { buildSubjectIndex, frameSubjects, } from './frame-by-type.js';
-import { assertTypeInSchema, displayFieldName, documentKeyOf, fieldNamed, inheritedFacetKeys, inlineFramingDepth, irAlias, isAbsoluteIri, isInternalField, isInlineReference, isoToUnixSeconds, labelSourceNameOf, physicalFields, referenceTypeNamed, rootTypeNamed, } from './schema.js';
+import { assertTypeInSchema, displayFieldName, documentKeyOf, fieldNamed, inheritedFacetKeys, inlineFramingDepth, irAlias, isAbsoluteIri, isInternalField, isInlineReference, isoToUnixSeconds, labelSourceNameOf, localLookupTypeOf, physicalFields, referenceTypeNamed, rootTypeNamed, } from './schema.js';
 /** The context a projection runs with when its caller supplied none. */
 const NO_PROJECTION_CONTEXT = {};
 /**
@@ -32,10 +32,16 @@ export function projectDocument(node, searchType, schema, context = NO_PROJECTIO
  * only after all projection – so every derive that might read an internal
  * field, at any depth, has already run – which makes this single post-order
  * pass safe. A no-role inline reference is itself internal, so it is deleted
- * whole here; a surfaced (`output`) inline reference survives, but its own
- * internal helper fields are pruned from the nested document. That keeps the
- * *a field without a role reaches neither the engine nor the API* invariant
- * true at every depth of the reference graph, not just at the root.
+ * whole here; one that carries a Role survives, but its own internal helper
+ * fields are pruned from the nested document. That keeps the *a field without a
+ * role reaches neither the engine nor the API* invariant true at every depth of
+ * the reference graph, not just at the root.
+ *
+ * Both kinds of nesting are walked, because both store projected nodes: an
+ * inline reference’s Reference Type, and the Root Type a
+ * {@link ReferenceStrategy.local local} lookup projects its endpoint through.
+ * The second matters more than it looks – a Root Type’s reading-device fields
+ * exist for its OWN derives, and nothing in a referring document wants them.
  */
 function pruneInternalFields(document, searchType, schema) {
     for (const field of searchType.fields) {
@@ -43,22 +49,18 @@ function pruneInternalFields(document, searchType, schema) {
             delete document[field.name];
             continue;
         }
-        // A surfaced inline reference nests its referent(s) as projected node(s);
-        // prune those too, by their reference type.
         if (schema === undefined || field.kind !== 'reference') {
             continue;
         }
-        const ref = field.ref;
-        if (ref?.strategy !== 'inline') {
-            continue;
-        }
-        const referenceType = referenceTypeNamed(schema, ref.typeName);
+        const nestedType = field.ref?.strategy === 'inline'
+            ? referenceTypeNamed(schema, field.ref.typeName)
+            : localLookupTypeOf(field, schema);
         const nested = document[field.name];
-        if (referenceType === undefined || nested === undefined) {
+        if (nestedType === undefined || nested === undefined) {
             continue;
         }
         for (const referent of Array.isArray(nested) ? nested : [nested]) {
-            pruneInternalFields(referent, referenceType, schema);
+            pruneInternalFields(referent, nestedType, schema);
         }
     }
 }
@@ -203,6 +205,22 @@ function applyField(document, node, field, searchType, schema, context) {
         }
         return;
     }
+    // A `local` lookup stores nested documents too, shaped by the TARGET’s own
+    // declaration rather than by a reference type – so an unidentified referent
+    // 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);
+            // 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,
+            // exactly as an inline reference's identity companion does.
+            applyLocalIdentity(document, endpoints, field, schema);
+            return;
+        }
+    }
     switch (field.kind) {
         case 'text':
             return applyText(document, langValuesOf(node, alias), field);
@@ -430,9 +448,103 @@ function applyInlineReference(document, node, alias, field, schema, context) {
     if (referenceType === undefined) {
         return;
     }
-    const referents = valuesOf(node, alias)
+    const referents = applyNestedReferents(document, valuesOf(node, alias), field, referenceType, schema, context);
+    applyIdentityCompanion(document, referents, field, schema);
+}
+/**
+ * Write the {@link ReferenceStrategy.identity identity companion} of an inline
+ * reference: the ids its entries reference, flattened out of the nested
+ * documents just projected, under the flat physical name an engine filters and
+ * facets ({@link physicalFields}).
+ *
+ * Harvested from the entries rather than read from a second path, so what the
+ * companion holds is exactly what the entries hold – including the re-keying
+ * the nested reference already applied, which a separately-read path would have
+ * to repeat and could get wrong.
+ *
+ * The identity field stores either bare ids or, when it is a
+ * {@link ReferenceStrategy.local local} lookup, nested documents carrying an
+ * `id`. Both are read here, because which one a deployment declares is about
+ * how much of the referent it wants to display – not about what identifies it.
+ */
+function applyIdentityCompanion(document, referents, field, schema) {
+    const names = physicalFields(field, schema);
+    if (names.identity === undefined) {
+        return;
+    }
+    const identity = field.ref.identity;
+    // Only the entries the document actually STORES: a single-valued reference
+    // 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)));
+    if (ids.length === 0) {
+        return;
+    }
+    setArray(document, names.identity, ids);
+    // 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) {
+        setArray(document, names.facet, ids.filter(policy.only));
+    }
+}
+/**
+ * Write the identity companion of a {@link ReferenceStrategy.local local}
+ * lookup: the ids of the endpoints just stored, under the flat physical name an
+ * engine filters on ({@link physicalFields}).
+ *
+ * Nothing to do where the field is not `filterable`: without that Role there is
+ * no companion, and the endpoint is display weight like every other nesting.
+ */
+function applyLocalIdentity(document, endpoints, field, schema) {
+    const names = physicalFields(field, schema);
+    if (names.identity === undefined) {
+        return;
+    }
+    // Only the endpoints the field actually STORES: a single-valued reference
+    // keeps the first and drops the rest, and a companion holding an id from a
+    // dropped one would match a filter whose hit shows a different endpoint.
+    const stored = field.array === true ? endpoints : endpoints.slice(0, 1);
+    const ids = dedupe(stored
+        .map((endpoint) => endpoint.id)
+        .filter((id) => typeof id === 'string'));
+    if (ids.length > 0) {
+        setArray(document, names.identity, ids);
+    }
+}
+/** The id a value under an identity field carries: the value itself when the
+ *  field stores bare ids, its `id` when it stores nested documents. */
+function identityValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    const id = isObject(value) ? value.id : undefined;
+    return typeof id === 'string' ? id : undefined;
+}
+/**
+ * Project raw framed values as nested document(s) of `nestedType` and attach
+ * them under the field’s name – the shared body of an inline reference and a
+ * {@link ReferenceStrategy.local local} lookup, which differ only in which type
+ * shapes the referent: a declared Reference Type for the one, the lookup’s own
+ * target Root Type for the other. Sharing it is what makes the two reconstruct
+ * through one path, so a consumer cannot tell a nested referent from a resolved
+ * one.
+ *
+ * Projecting through a Root Type also gives a `local` referent its `id` for
+ * free, re-keyed through that type’s {@link RootType.key} exactly as a
+ * 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) {
+    const referents = values
         .filter(isObject)
-        .map((referent) => projectFields(referent, referenceType, schema, context))
+        .map((referent) => projectFields(referent, nestedType, schema, context))
         // 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.
@@ -440,9 +552,10 @@ function applyInlineReference(document, node, alias, field, schema, context) {
         // single-valued reference, let it win the slot over a real referent.
         .filter((referent) => Object.keys(referent).length > 0);
     if (referents.length === 0) {
-        return;
+        return referents;
     }
     document[field.name] = field.array === true ? referents : referents[0];
+    return referents;
 }
 function langValuesOf(node, key) {
     return valuesOf(node, key)

package/dist/query.d.ts

@@ -95,7 +95,33 @@ export type Criterion = (CriterionBase & {
     };
 }) | (CriterionBase & {
     readonly is: boolean;
+}) | (CriterionBase & {
+    readonly entry: readonly Criterion[];
 });
+/**
+ * The conditions a criterion welds to **one entry** of the nested reference its
+ * {@link CriterionBase.field} names – *this endpoint in this role*, rather than
+ * this endpoint somewhere and that role somewhere.
+ *
+ * Welding is the whole reason an edge is worth indexing. Stated as two ordinary
+ * criteria, `role = etser` and `creator = rembrandt` are satisfied by
+ * *different* entries of the same document, which silently answers a wider
+ * question – the parallel-array defect nesting exists to remove.
+ *
+ * It stays an **atom**, so `where` remains the flat conjunction of disjunctions
+ * of [ADR 18](../../docs/decisions/0018-filter-across-several-fields-with-one-clause.md):
+ * the conjunction lives *inside* one criterion rather than nesting clause
+ * structure, and skip-own-filter still scans one level and finds one field.
+ *
+ * Each welded condition names a field of the reference type and carries no
+ * `on` of its own: they are all conditions on the same entry, which is what
+ * welding means.
+ */
+export type WeldedCriterion = CriterionBase & {
+    readonly entry: readonly Criterion[];
+};
+/** Whether a criterion welds conditions to one entry ({@link WeldedCriterion}). */
+export declare function isWelded(criterion: Criterion): criterion is WeldedCriterion;
 /**
  * One `where` clause: a disjunction, matching a document that satisfies **any**
  * of its criteria. An ordinary single-field filter is the one-criterion case,
@@ -169,13 +195,32 @@ export interface QueryIssue {
      *  the bound of an `unparseable-bound`. Absent on every other reason. */
     readonly value?: string;
     readonly reason: 'unknown-field' | 'not-filterable' | 'operator-mismatch' | 'not-facetable'
-    /** The criterion’s `on` path is longer than {@link MAX_JOIN_DEPTH}. */
+    /** The criterion’s `on` path crosses more than {@link MAX_JOIN_DEPTH}
+     *  *joins*. Nested hops cost no round trip and do not count. */
      | 'join-too-deep'
-    /** The `on` path does not resolve: a name that is not a field, a reference
+    /** A join hop does not resolve: a name that is not a field, a reference
      *  that is not `joinable`, or no join graph to resolve it against. */
      | 'unknown-join'
+    /**
+     * A hop *inside* an inline reference’s entries does not walk into a nested
+     * reference – an unknown name, or a field that is not one. Reported apart
+     * from `unknown-join` so “this field is not joinable” and “this field is
+     * not nested” are not one message.
+     *
+     * Joining out of a nesting lands here too, deliberately: a join addresses
+     * another collection and there is none to address from inside an array
+     * element, so from in here a joinable name is as unwalkable as an unknown
+     * one. A join may contain a nesting; never the reverse.
+     */
+     | 'unknown-nesting'
     /** A projected reference is not a `lookup`, so nothing resolves it. */
      | 'not-resolvable'
+    /**
+     * A criterion welds conditions to one entry of a field that has no entries
+     * – it is not an inline reference. Welding means *one entry satisfies all
+     * of these*, so there has to be something to weld them to.
+     */
+     | 'not-weldable'
     /**
      * A `date` range bound the storage codec ({@link isoToUnixSeconds}) cannot
      * read, so there is no stored value to compare against – reported per
@@ -188,6 +233,43 @@ export interface QueryIssue {
      */
      | 'unparseable-bound';
 }
+/**
+ * A resolved {@link CriterionBase.on} path: which type the leaf field belongs
+ * to, and how the criterion reaches it.
+ *
+ * The two hop kinds are genuinely different operations, so they are separated
+ * here once rather than re-derived by every adapter. A **join** hop crosses
+ * into another collection and costs a round trip; a **nested** hop stays inside
+ * the same document and costs nothing, walking into an inline reference’s
+ * entries.
+ */
+export interface ResolvedPath {
+    /** The type the criterion’s leaf field is declared by. */
+    readonly leafType: SearchType;
+    /** The joinable references to cross, in order. Counts against
+     *  {@link MAX_JOIN_DEPTH}; a nested hop deliberately does not. */
+    readonly joinPath: readonly string[];
+    /** The inline references to walk into, in order, after the joins. */
+    readonly nestedPath: readonly string[];
+}
+/** Why an {@link CriterionBase.on} path did not resolve. */
+export type PathFailure = 'join-too-deep' | 'unknown-join' | 'unknown-nesting';
+/**
+ * Resolve an {@link CriterionBase.on} path against the schema, classifying each
+ * hop by what the declaration says it is: a {@link ReferenceField.joinable}
+ * reference is a join, an inline reference is a nesting.
+ *
+ * **Nested hops must come last.** A join is a clause about another collection
+ * and a nesting is a clause about a field of this document, so a join can
+ * contain a nesting (`$people(…)` around `edge.role`) but a nesting cannot
+ * contain a join – there is no collection to address from inside an array
+ * element. Once inside a nesting, therefore, a joinable name is as unwalkable
+ * as an unknown one and both report `unknown-nesting`.
+ *
+ * Only join hops count against {@link MAX_JOIN_DEPTH}: the cap exists to bound
+ * round trips, and a nesting hop costs none.
+ */
+export declare function resolvePath(searchType: SearchType, path: readonly string[], schema: SearchSchema, joins?: JoinGraph): ResolvedPath | PathFailure;
 /**
  * Structurally validate a query against its search type: **every criterion of
  * every `where` clause** names a declared, `filterable` field whose kind accepts

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":"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"}

package/dist/query.js

@@ -1,5 +1,9 @@
-import { fieldNamed, filterOperatorFor, ID_FIELD, isoToUnixSeconds, } from './schema.js';
+import { fieldNamed, filterOperatorFor, ID_FIELD, isoToUnixSeconds, nestedReferenceType, } 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) {
+    return 'entry' in criterion;
+}
 // The kind→operator table lives with the field model in schema.ts (one source
 // for the query IR, the surfaces, the adapters AND declaration validation);
 // re-exported here so the query-IR module stays the natural import site.
@@ -50,6 +54,96 @@ export function isUnsatisfiable(query) {
             criterion.in.length === 0);
     });
 }
+/**
+ * The checks every leaf criterion answers to, wherever it sits: the field is
+ * declared and `filterable` on the type it constrains, its operator matches
+ * that field's kind, and a `date` range's bounds are readable.
+ *
+ * Shared by an ordinary criterion and by each condition welded to an entry, so
+ * a welded condition is held to exactly the same rules – there is no second,
+ * weaker validator for the inside of an edge. `field` is the path to report
+ * under, which differs between the two.
+ */
+function collectLeafIssues(criterion, constrained, field, issues) {
+    const declared = fieldNamed(constrained, criterion.field);
+    if (declared === undefined) {
+        issues.push({ part: 'where', field, reason: 'unknown-field' });
+        return;
+    }
+    if (declared.filterable !== true) {
+        issues.push({ part: 'where', field, reason: 'not-filterable' });
+        return;
+    }
+    if (filterOperatorFor(declared.kind) !== filterOperator(criterion)) {
+        issues.push({ part: 'where', field, reason: 'operator-mismatch' });
+        return;
+    }
+    if (declared.kind === 'date' && 'range' in criterion) {
+        // A `date` bound is ISO 8601 at the edge and Unix seconds in storage, so a
+        // bound the codec cannot read has nothing to compare against. Both bounds
+        // are checked, so a caller who wrote two bad ones is told about both
+        // instead of fixing one to be told about the other.
+        for (const bound of [criterion.range.min, criterion.range.max]) {
+            if (typeof bound === 'string' && isoToUnixSeconds(bound) === undefined) {
+                issues.push({
+                    part: 'where',
+                    field,
+                    value: bound,
+                    reason: 'unparseable-bound',
+                });
+            }
+        }
+    }
+}
+/**
+ * Resolve an {@link CriterionBase.on} path against the schema, classifying each
+ * hop by what the declaration says it is: a {@link ReferenceField.joinable}
+ * reference is a join, an inline reference is a nesting.
+ *
+ * **Nested hops must come last.** A join is a clause about another collection
+ * and a nesting is a clause about a field of this document, so a join can
+ * contain a nesting (`$people(…)` around `edge.role`) but a nesting cannot
+ * contain a join – there is no collection to address from inside an array
+ * element. Once inside a nesting, therefore, a joinable name is as unwalkable
+ * as an unknown one and both report `unknown-nesting`.
+ *
+ * Only join hops count against {@link MAX_JOIN_DEPTH}: the cap exists to bound
+ * round trips, and a nesting hop costs none.
+ */
+export function resolvePath(searchType, path, schema, joins) {
+    const joinPath = [];
+    const nestedPath = [];
+    let current = searchType;
+    for (const name of path) {
+        const field = fieldNamed(current, name);
+        const nested = field === undefined ? undefined : nestedReferenceType(schema, field);
+        if (nested !== undefined) {
+            nestedPath.push(name);
+            current = nested;
+            continue;
+        }
+        if (nestedPath.length > 0) {
+            // Already inside a document, where the only hop that means anything is
+            // another nesting. A join addresses a collection and there is none to
+            // address from inside an array element, so a joinable name here is as
+            // unwalkable as an unknown one – one reason covers both.
+            return 'unknown-nesting';
+        }
+        // Checked as the budget is spent, not after the walk: a path over the cap
+        // is too deep whether or not its last hop would have resolved, and saying
+        // so is more use than reporting the hop that happened to fail first.
+        if (joinPath.length === MAX_JOIN_DEPTH) {
+            return 'join-too-deep';
+        }
+        const target = joins?.resolve(current, [name]);
+        if (target === undefined) {
+            return 'unknown-join';
+        }
+        joinPath.push(name);
+        current = target;
+    }
+    return { leafType: current, joinPath, nestedPath };
+}
 /** The `field` a joined issue is reported under: the path and the leaf name
  *  together, so a message says which hop and which field, not just which
  *  field. `dataset.publisher.id` reads the way the criterion was written. */
@@ -107,23 +201,29 @@ export function validateQuery(query, searchType, schema, joins) {
             // supplied none cannot serve a joined criterion at all.
             const on = criterion.on ?? [];
             let constrained = searchType;
+            let nested = false;
             if (on.length > 0) {
-                if (on.length > MAX_JOIN_DEPTH) {
-                    issues.push({ part: 'where', field, reason: 'join-too-deep' });
+                const resolved = resolvePath(searchType, on, schema, joins);
+                if (typeof resolved === 'string') {
+                    issues.push({ part: 'where', field, reason: resolved });
                     continue;
                 }
-                const target = joins?.resolve(searchType, on);
-                if (target === undefined) {
-                    issues.push({ part: 'where', field, reason: 'unknown-join' });
-                    continue;
-                }
-                constrained = target;
+                constrained = resolved.leafType;
+                nested = resolved.nestedPath.length > 0;
             }
             // `id` is filterable on every type without being declared by any: it is
             // the document’s IRI, so the lookup exists wherever documents do.
             // Membership only – an IRI has no range and no truth value.
             if (name === ID_FIELD) {
-                if (filterOperator(criterion) !== 'in') {
+                // …but only where documents do. An entry inside a nested reference is
+                // read, not addressed: it has no document key, and the `id` a `local`
+                // lookup stores is the ENDPOINT’s, which the identity companion is
+                // what filters on. Accepting it here would compile to the ROOT
+                // document’s `id` and silently answer a different question.
+                if (nested) {
+                    issues.push({ part: 'where', field, reason: 'unknown-nesting' });
+                }
+                else if (filterOperator(criterion) !== 'in') {
                     issues.push({
                         part: 'where',
                         field,
@@ -133,36 +233,23 @@ export function validateQuery(query, searchType, schema, joins) {
                 continue;
             }
             const declared = fieldNamed(constrained, name);
-            if (declared === undefined) {
-                issues.push({ part: 'where', field, reason: 'unknown-field' });
-            }
-            else if (declared.filterable !== true) {
-                issues.push({ part: 'where', field, reason: 'not-filterable' });
-            }
-            else if (filterOperatorFor(declared.kind) !== filterOperator(criterion)) {
-                issues.push({
-                    part: 'where',
-                    field,
-                    reason: 'operator-mismatch',
-                });
-            }
-            else if (declared.kind === 'date' && 'range' in criterion) {
-                // A `date` bound is ISO 8601 at the edge and Unix seconds in storage,
-                // so a bound the codec cannot read has nothing to compare against.
-                // Both bounds are checked, so a caller who wrote two bad ones is told
-                // about both instead of fixing one to be told about the other.
-                for (const bound of [criterion.range.min, criterion.range.max]) {
-                    if (typeof bound === 'string' &&
-                        isoToUnixSeconds(bound) === undefined) {
-                        issues.push({
-                            part: 'where',
-                            field,
-                            value: bound,
-                            reason: 'unparseable-bound',
-                        });
-                    }
+            // A welded criterion names the NESTED REFERENCE and constrains fields of
+            // the type it nests, so each condition is checked one level in – against
+            // that reference type, and reported under the path a consumer wrote.
+            if (isWelded(criterion)) {
+                const entryType = declared === undefined
+                    ? undefined
+                    : nestedReferenceType(schema, declared);
+                if (entryType === undefined) {
+                    issues.push({ part: 'where', field, reason: 'not-weldable' });
+                    continue;
+                }
+                for (const welded of criterion.entry) {
+                    collectLeafIssues(welded, entryType, [...on, name, welded.field].join('.'), issues);
                 }
+                continue;
             }
+            collectLeafIssues(criterion, constrained, field, issues);
         }
     }
     for (const name of query.facets) {
@@ -188,12 +275,19 @@ export function validateQuery(query, searchType, schema, joins) {
     return issues;
 }
 /**
- * Walk a projection level by level: each key names a `lookup` reference on the
- * type that level belongs to, each `fields` entry an `output` field of the
- * target it resolves against, and each nested `resolve` repeats against that
- * target. A level whose reference is unresolvable stops there – its subtree
- * belongs to a target that does not exist, so reporting it too would bury the
- * one mistake under its consequences.
+ * Walk a projection level by level. A level is one of two things, and the
+ * difference is what it costs rather than how it is written:
+ *
+ * - a **lookup** level names a `lookup` reference, resolves against that
+ *   target’s collection, and costs one batched round trip;
+ * - a **nested** level names an inline reference and descends into its entries,
+ *   costing nothing – the entries are already in the hit. Its `fields` name
+ *   nothing to fetch, because the entries carry what they carry; only the
+ *   levels *below* it can ask for anything.
+ *
+ * A level whose reference is unresolvable stops there: its subtree belongs to a
+ * target that does not exist, so reporting it too would bury the one mistake
+ * under its consequences.
  */
 function collectProjectionIssues(projection, searchType, schema, issues) {
     for (const [name, level] of Object.entries(projection ?? {})) {
@@ -202,6 +296,13 @@ function collectProjectionIssues(projection, searchType, schema, issues) {
             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) {
+            collectProjectionIssues(level.resolve, nested, schema, issues);
+            continue;
+        }
         if (field.kind !== 'reference' || field.ref?.strategy !== 'lookup') {
             issues.push({ part: 'resolve', field: name, reason: 'not-resolvable' });
             continue;