@lde/search 0.18.3 → 0.20.0

package/dist/adapter.d.ts

@@ -6,9 +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, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, DEFAULT_LABEL_FIELD, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, irAlias, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, isInlineReference, nestedReferenceType, nestedFieldName, referenceFields, referenceTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, 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';
 //# 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,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,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,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,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,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"}

package/dist/adapter.js

@@ -6,6 +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, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, DEFAULT_LABEL_FIELD, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, irAlias, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, isInlineReference, nestedReferenceType, nestedFieldName, referenceFields, referenceTypeNamed, inlineFramingDepth, fieldNamed, datasetField, ID_FIELD, AND_KEY, OR_KEY, labelFieldOf, labelFieldNameOf, 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';

package/dist/index.d.ts

@@ -2,8 +2,10 @@ export { projectRoots } from './project.js';
 export type { ProjectedNode, ProjectionContext, SearchDocument, } from './project.js';
 export { defineSearchType, searchSchema, validateSearchType, assertValidSearchType, ID_FIELD, AND_KEY, OR_KEY, } from './schema.js';
 export type { FieldKind, SearchField, SearchFieldBase, TextField, KeywordField, ReferenceField, NumericField, BooleanField, SearchType, SearchTypeBase, RootType, ReferenceType, RootTypeOf, SearchTypeIssue, SearchSchema, FacetRange, ProjectionValue, } from './schema.js';
+export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
+export type { JoinGraph } from './join-graph.js';
 export { filterOn } from './query.js';
-export type { SearchQuery, Filter, Criterion, Sort } from './query.js';
+export type { SearchQuery, Filter, Criterion, CriterionBase, 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,GACP,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC;AAOrB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIvE,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,GACP,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,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,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"}

package/dist/index.js

@@ -11,6 +11,10 @@ export { projectRoots } from './project.js';
 // schema, query semantics and the GraphQL surface – a discriminated union by
 // `kind`, validated again at runtime when the schema is built.
 export { defineSearchType, searchSchema, validateSearchType, assertValidSearchType, ID_FIELD, AND_KEY, OR_KEY, } from './schema.js';
+// The declared join edges between root types: which types a query can filter
+// across, and which collections must be rebuilt together. Built eagerly by
+// `searchSchema`, so declaring a schema is what validates the joins.
+export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
 // Engine- and protocol-neutral query IR (what a `queryDefaults` policy or an
 // in-process caller writes).
 // `filterOn` builds the ordinary one-criterion clause – the shape a consumer

package/dist/join-graph.d.ts

@@ -0,0 +1,63 @@
+import { type RootType, type SearchSchema, type SearchType } 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
+ * ({@link validateQuery}) rather than in an adapter, so a later REST surface
+ * inherits the same ceiling. Typesense imposes no limit of its own, and the
+ * GraphQL max-depth guard counts selection sets rather than input nesting, so
+ * without this a `where` could nest a join arbitrarily deep and each hop is an
+ * extra collection scan.
+ */
+export declare const MAX_JOIN_DEPTH = 3;
+/**
+ * The declared join edges of a {@link SearchSchema}: which Root Types are
+ * reachable from which through {@link ReferenceField.joinable} references, and
+ * which of them must be rebuilt together.
+ *
+ * Two members, because a consumer needs exactly two answers. A **query**
+ * compiler asks *what does this path of field names reach* ({@link
+ * JoinGraph.resolve}); a **writer** asks *which collections come into existence
+ * together* ({@link JoinGraph.components}). Everything else – deriving the
+ * edges from `joinable` + `labelSource`, the one-edge-per-target rule, cycle
+ * rejection, the depth cap, and the asymmetry between undirected membership and
+ * directed creation order – is hidden here, so no consumer restates it.
+ *
+ * `resolve` returns a {@link RootType}, never a collection name: how a type is
+ * named in an engine is engine- and deployment-specific and stays in the
+ * adapter.
+ */
+export interface JoinGraph {
+    /**
+     * The **join components**: groups of Root Types that reference one another,
+     * directly or transitively, and therefore share a rebuild
+     * ([ADR 19](../../docs/decisions/0019-filter-across-collections-through-declared-joins.md)).
+     * Every Root Type appears in exactly one; a type with no joinable edge is a
+     * singleton and keeps per-collection isolation exactly as before.
+     *
+     * Membership is the **undirected** connected component – a referrer and its
+     * referent must rebuild together whichever way the edge points – while the
+     * order **within** a component is the **directed** topological sort,
+     * referenced first. That asymmetry is load-bearing: an engine cannot create a
+     * collection whose reference names a collection that does not exist yet, so
+     * the referent’s collection must be opened first.
+     */
+    readonly components: readonly (readonly RootType[])[];
+    /**
+     * The Root Type a path of joinable field names reaches from `from`, or
+     * `undefined` when the path does not resolve – an unknown field name, a
+     * reference that is not `joinable`, or a path deeper than
+     * {@link MAX_JOIN_DEPTH}. An empty path resolves to `from` itself only when
+     * `from` is a Root Type; a Reference Type has no collection to join to.
+     */
+    resolve(from: SearchType, path: readonly string[]): RootType | undefined;
+}
+/**
+ * The join graph of a {@link SearchSchema}, built once per schema and cached:
+ * {@link searchSchema} builds it eagerly, so a schema whose joins do not hold
+ * up – two joinable fields at one target, a cycle – fails at startup rather
+ * than on the first query or the first rebuild.
+ *
+ * Calling it again for the same schema returns the same graph.
+ */
+export declare function joinGraph(schema: SearchSchema): JoinGraph;
+//# sourceMappingURL=join-graph.d.ts.map

package/dist/join-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-graph.d.ts","sourceRoot":"","sources":["../src/join-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,SAAS,QAAQ,EAAE,CAAC,EAAE,CAAC;IACtD;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC1E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAQzD"}

package/dist/join-graph.js

@@ -0,0 +1,192 @@
+import { 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
+ * ({@link validateQuery}) rather than in an adapter, so a later REST surface
+ * inherits the same ceiling. Typesense imposes no limit of its own, and the
+ * GraphQL max-depth guard counts selection sets rather than input nesting, so
+ * without this a `where` could nest a join arbitrarily deep and each hop is an
+ * extra collection scan.
+ */
+export const MAX_JOIN_DEPTH = 3;
+/**
+ * The join graph of a {@link SearchSchema}, built once per schema and cached:
+ * {@link searchSchema} builds it eagerly, so a schema whose joins do not hold
+ * up – two joinable fields at one target, a cycle – fails at startup rather
+ * than on the first query or the first rebuild.
+ *
+ * Calling it again for the same schema returns the same graph.
+ */
+export function joinGraph(schema) {
+    const cached = graphsBySchema.get(schema);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const built = buildJoinGraph(schema);
+    graphsBySchema.set(schema, built);
+    return built;
+}
+/** One graph per schema, held beside it rather than on it, so a
+ *  {@link SearchSchema} stays a plain branded `Map`. */
+const graphsBySchema = new WeakMap();
+/** The edges leaving one Root Type, keyed by field name. Total by
+ *  construction: the index is built with an entry for EVERY Root Type, an empty
+ *  map where a type declares none, so no caller needs a fallback it can never
+ *  take. */
+function edgesOf(edges, searchType) {
+    return edges.get(searchType.class);
+}
+/** The edges leaving one Root Type, in declaration order. */
+function edgesFrom(edges, searchType) {
+    return edgesOf(edges, searchType).values();
+}
+/**
+ * Derive, validate and index the edges. Throws – rather than reporting issues –
+ * because it is called from {@link searchSchema}, whose contract is that an
+ * invalid declaration fails at startup.
+ */
+function buildJoinGraph(schema) {
+    const rootTypes = [...schema.values()];
+    const byName = new Map(rootTypes.map((type) => [type.name, type]));
+    const edges = new Map();
+    for (const searchType of rootTypes) {
+        edges.set(searchType.class, declaredEdges(searchType, byName));
+    }
+    assertAcyclic(rootTypes, edges);
+    return {
+        components: componentsOf(rootTypes, edges),
+        resolve(from, path) {
+            if (path.length > MAX_JOIN_DEPTH) {
+                return undefined;
+            }
+            // A Reference Type is never indexed, so it has no collection to join
+            // from; only a member of this schema’s class map can start a path.
+            const start = from.class === undefined ? undefined : schema.get(from.class);
+            if (start === undefined || start !== from) {
+                return undefined;
+            }
+            let current = start;
+            for (const name of path) {
+                const edge = edgesOf(edges, current).get(name);
+                if (edge === undefined) {
+                    return undefined;
+                }
+                current = edge.target;
+            }
+            return current;
+        },
+    };
+}
+/**
+ * The joinable edges one Root Type declares, keyed by field name.
+ *
+ * Enforces the **one edge per (type, target)** rule here rather than in a
+ * consumer: a Typesense join addresses the referent by *collection*, not by
+ * field, so a second reference to the same collection is accepted, indexed and
+ * then unreachable – the engine resolves every join through the first field
+ * that matched and silently ignores the rest
+ * ({@link https://github.com/typesense/typesense/issues/3021}). `publisher` and
+ * `creator` both resolving to `Organization` is the ordinary case, so it must
+ * be a declaration error naming both fields rather than a surprise at query
+ * time.
+ */
+function declaredEdges(searchType, byName) {
+    const edges = new Map();
+    const claimedBy = new Map();
+    for (const field of referenceFields(searchType)) {
+        if (field.joinable !== true) {
+            continue;
+        }
+        // Both lookups always hit: `validateSearchType` rejects `joinable` without
+        // a `labelSource`, and a label source is always an indexed Root Type – it
+        // must declare a `searchable` `label` 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(field.labelSource);
+        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.`);
+        }
+        claimedBy.set(target.name, field.name);
+        edges.set(field.name, { field, target });
+    }
+    return edges;
+}
+/**
+ * Reject a cycle in the **directed** join graph. A cycle would make the
+ * topological creation order below undefinable – there is no collection to
+ * create first – and, with the component as the unit of rebuild, no order in
+ * which a component’s collections could come into existence at all.
+ */
+function assertAcyclic(rootTypes, edges) {
+    const done = new Set();
+    const visit = (searchType, onPath) => {
+        if (onPath.some((ancestor) => ancestor.class === searchType.class)) {
+            const cycle = [...onPath, searchType]
+                .map((type) => `“${type.name}”`)
+                .join(' → ');
+            throw new Error(`Join cycle ${cycle}; the joinable references between search types must be acyclic, so a component’s collections have an order to be created in.`);
+        }
+        if (done.has(searchType.class)) {
+            return;
+        }
+        const extended = [...onPath, searchType];
+        for (const edge of edgesFrom(edges, searchType)) {
+            visit(edge.target, extended);
+        }
+        done.add(searchType.class);
+    };
+    for (const searchType of rootTypes) {
+        visit(searchType, []);
+    }
+}
+/**
+ * Partition the Root Types into join components, each topologically ordered.
+ *
+ * Membership is the undirected connected component (union-find over the
+ * edges); the order within one is a depth-first topological sort over the
+ * directed edges, so a type is emitted only after everything it references.
+ * Components come out in declaration order of their first member, so a schema’s
+ * rebuild order is stable across runs.
+ */
+function componentsOf(rootTypes, edges) {
+    const parent = new Map(rootTypes.map((type) => [type.class, type.class]));
+    const find = (iri) => {
+        let root = iri;
+        while (parent.get(root) !== root) {
+            root = parent.get(root);
+        }
+        return root;
+    };
+    for (const searchType of rootTypes) {
+        for (const edge of edgesFrom(edges, searchType)) {
+            parent.set(find(searchType.class), find(edge.target.class));
+        }
+    }
+    const members = new Map();
+    for (const searchType of rootTypes) {
+        const root = find(searchType.class);
+        members.set(root, [...(members.get(root) ?? []), searchType]);
+    }
+    return [...members.values()].map((component) => topologicallyOrdered(component, edges));
+}
+/** One component’s members, everything a type references before the type
+ *  itself. Terminates because {@link assertAcyclic} ran first. */
+function topologicallyOrdered(component, edges) {
+    const ordered = [];
+    const emitted = new Set();
+    const visit = (searchType) => {
+        if (emitted.has(searchType.class)) {
+            return;
+        }
+        emitted.add(searchType.class);
+        for (const edge of edgesFrom(edges, searchType)) {
+            visit(edge.target);
+        }
+        ordered.push(searchType);
+    };
+    for (const searchType of component) {
+        visit(searchType);
+    }
+    return ordered;
+}

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,EAWL,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;AAyED;;;;;;;;;;;;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,CAW/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,EAYL,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;AA2ED;;;;;;;;;;;;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,CAW/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, inlineFramingDepth, irAlias, isInternalField, isInlineReference, isoToUnixSeconds, physicalFields, referenceTypeNamed, } from './schema.js';
+import { assertTypeInSchema, displayFieldName, inlineFramingDepth, irAlias, isAbsoluteIri, isInternalField, isInlineReference, isoToUnixSeconds, physicalFields, referenceTypeNamed, } from './schema.js';
 /** The context a projection runs with when its caller supplied none. */
 const NO_PROJECTION_CONTEXT = {};
 /**
@@ -19,7 +19,7 @@ const NO_PROJECTION_CONTEXT = {};
  */
 export function projectDocument(node, searchType, schema, context = NO_PROJECTION_CONTEXT) {
     if (documentKey(node) === undefined) {
-        throw new Error(`Cannot project a “${searchType.name}” node without an @id (a blank node label is not one): every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
+        throw new Error(`Cannot project a “${searchType.name}” node whose @id is not an absolute IRI (got ${JSON.stringify(node['@id']) ?? 'none'}; a blank node label or a relative reference is not one): every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
     }
     // The guard above is what makes this a SearchDocument: projectFields sets `id`
     // for exactly the nodes documentKey resolves.
@@ -76,15 +76,17 @@ function projectFields(node, searchType, schema, context) {
     return document;
 }
 /**
- * The document key a framed node carries, if any. A blank node label (`_:b0`) is
- * not one: framing mints it per call, so it recurs across documents and can
- * change when unrelated triples do. A node bearing one is therefore projected as
- * if framing had pruned its `@id` – which it does whenever the label occurs only
- * once in the framing results.
+ * The document key a framed node carries, if any – an {@link isAbsoluteIri
+ * absolute IRI}, the same rule {@link iriString} applies to a referent, so a
+ * root and a reference cannot disagree about what counts as identity. A blank
+ * node label (`_:b0`) is not one: framing mints it per call, so it recurs across
+ * documents and can change when unrelated triples do. A node bearing one is
+ * therefore projected as if framing had pruned its `@id` – which it does
+ * whenever the label occurs only once in the framing results.
  */
 function documentKey(node) {
     const id = node['@id'];
-    return typeof id === 'string' && !id.startsWith('_:') ? id : undefined;
+    return typeof id === 'string' && isAbsoluteIri(id) ? id : undefined;
 }
 /**
  * Project a single type over a known set of `roots` – the per-type, roots-given
@@ -362,14 +364,25 @@ function literalString(value) {
     }
     return undefined;
 }
+/**
+ * The IRI a reference value carries, or `undefined` when it carries none. A
+ * value may arrive as a bare string – `schema:sameAs`, `contentUrl`,
+ * `thumbnailUrl` and `landingPage` all range on `schema:URL`, which a source may
+ * emit as a literal rather than a node – or as a node object.
+ *
+ * **A referent with no IRI yields nothing**, the same rule {@link documentKey}
+ * applies to a root and for the same reason: what a `labelOnly`/`idOnly`
+ * reference stores is a selection key, and a blank node label is not one.
+ * Framing mints it per call, so it recurs across documents and changes when
+ * unrelated triples do – indexing it would key a facet bucket on a value that
+ * neither groups what is equal nor separates what is not. An **inline**
+ * reference is untouched by this: it carries the referent’s fields rather than
+ * its identity ({@link applyInlineReference}), so a blank-node referent nests
+ * exactly as before.
+ */
 function iriString(value) {
-    if (typeof value === 'string') {
-        return value;
-    }
-    if (isObject(value) && typeof value['@id'] === 'string') {
-        return value['@id'];
-    }
-    return undefined;
+    const iri = isObject(value) ? value['@id'] : value;
+    return typeof iri === 'string' && isAbsoluteIri(iri) ? iri : undefined;
 }
 function toInteger(literal) {
     return literal === undefined ? undefined : Math.trunc(Number(literal));

package/dist/query.d.ts

@@ -1,4 +1,5 @@
 import { type SearchType } from './schema.js';
+import { type JoinGraph } from './join-graph.js';
 /**
  * The engine- and protocol-neutral query IR. Every API surface compiles its
  * input into this; every engine adapter compiles it into an engine query. One
@@ -20,6 +21,35 @@ export interface SearchQuery {
     /** Selects the per-locale fields to query/sort on (from `Accept-Language`). */
     readonly locale: string;
 }
+/**
+ * What every {@link Criterion} carries, whatever its operator: the field it
+ * constrains, and – for a criterion that constrains a *joined* document rather
+ * than this one – the path of joinable references to walk to reach it.
+ */
+export interface CriterionBase {
+    /** The logical field name, on the type the {@link CriterionBase.on} path
+     *  reaches (or on the searched type when there is none). */
+    readonly field: string;
+    /**
+     * A **join path**: the names of the {@link ReferenceField.joinable}
+     * references to follow, in order, to the type this criterion constrains.
+     * `['dataset', 'publisher']` on a `CreativeWork` criterion means *the
+     * publisher of the dataset this work belongs to*. Omitted (or empty) for the
+     * ordinary case: the criterion constrains the searched type itself.
+     *
+     * A path, deliberately, and not boolean structure – so the criterion stays an
+     * **atom** and `where` stays the flat conjunction of disjunctions
+     * [ADR 18](../../docs/decisions/0018-filter-across-several-fields-with-one-clause.md)
+     * made it. `on` sits on the criterion rather than on the {@link Filter} for
+     * the same reason a criterion carries its own operator: a `Filter`-level
+     * `on` would scope the whole disjunction and make
+     * `“published by X, or titled Y”` inexpressible.
+     *
+     * Capped at {@link MAX_JOIN_DEPTH} hops and resolved by
+     * {@link validateQuery} against the schema’s {@link JoinGraph}.
+     */
+    readonly on?: readonly string[];
+}
 /**
  * One criterion on one field. The operator is fixed by that field’s
  * {@link FieldKind} ({@link filterOperatorFor}): keyword/reference use `in` (OR
@@ -29,21 +59,20 @@ export interface SearchQuery {
  * Criteria are the atoms a {@link Filter} is built from, so each carries its own
  * field AND its own operator: one clause may range over a `reference` and a
  * `keyword` field at once, and each field is constrained the way its kind
- * allows.
+ * allows. Each equally carries its own {@link CriterionBase.on} join path, so
+ * one clause may mix a condition on this document with one on a joined
+ * document.
  */
-export type Criterion = {
-    readonly field: string;
+export type Criterion = (CriterionBase & {
     readonly in: readonly string[];
-} | {
-    readonly field: string;
+}) | (CriterionBase & {
     readonly range: {
         readonly min?: number | string;
         readonly max?: number | string;
     };
-} | {
-    readonly field: string;
+}) | (CriterionBase & {
     readonly is: boolean;
-};
+});
 /**
  * One `where` clause: a disjunction, matching a document that satisfies **any**
  * of its criteria. An ordinary single-field filter is the one-criterion case,
@@ -92,6 +121,10 @@ export declare function filterOn(criterion: Criterion): Filter;
  * is a disjunction that happens to include identity, not an enumeration of
  * wanted documents, so it stays the vacuous no-op every other empty `in` is.
  *
+ * A joined identity clause (`{ on: […], field: 'id', in: [] }`) reads the same
+ * way one hop out: it enumerates the *referents* wanted, and no referent means
+ * no document can match through that edge.
+ *
  * An adapter MUST answer an unsatisfiable query with an empty result rather
  * than dispatching it.
  */
@@ -108,7 +141,12 @@ export declare function isUnsatisfiable(query: SearchQuery): boolean;
 export interface QueryIssue {
     readonly part: 'where' | 'facets' | 'orderBy';
     readonly field: string;
-    readonly reason: 'unknown-field' | 'not-filterable' | 'operator-mismatch' | 'not-facetable';
+    readonly reason: 'unknown-field' | 'not-filterable' | 'operator-mismatch' | 'not-facetable'
+    /** The criterion’s `on` path is longer than {@link MAX_JOIN_DEPTH}. */
+     | 'join-too-deep'
+    /** The `on` path 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';
 }
 /**
  * Structurally validate a query against its search type: **every criterion of
@@ -121,15 +159,24 @@ export interface QueryIssue {
  * checks declaration only, not the `sortable` flag: that flag means *publicly
  * selectable*, and a deployment policy may sort on a private tie-break field.
  *
+ * A criterion carrying an {@link CriterionBase.on} join path is checked against
+ * the type that path reaches instead: the path must be at most
+ * {@link MAX_JOIN_DEPTH} hops (`join-too-deep`) and must resolve through
+ * `joins` (`unknown-join`), and the leaf field must then be filterable on the
+ * *target* type. The cap lives here, in the IR, rather than in an adapter or a
+ * surface, so every surface inherits it. `joins` is optional because a query
+ * with no join path needs none; a joined criterion validated without one is an
+ * `unknown-join`, never a silently unchecked filter.
+ *
  * This is the port’s always-on guard: every {@link SearchEngine} adapter MUST
  * reject a query with issues ({@link assertValidQuery}) instead of passing
  * garbage to its engine, so validation holds for every caller – including
  * `queryDefaults` policies and surfaces weaker than GraphQL.
  */
-export declare function validateQuery(query: SearchQuery, searchType: SearchType): readonly QueryIssue[];
+export declare function validateQuery(query: SearchQuery, searchType: SearchType, joins?: JoinGraph): readonly QueryIssue[];
 /** Throw on the first structurally invalid query part ({@link validateQuery}),
  *  naming every issue. The always-on entry point for engine adapters. */
-export declare function assertValidQuery(query: SearchQuery, searchType: SearchType): void;
+export declare function assertValidQuery(query: SearchQuery, searchType: SearchType, joins?: JoinGraph): void;
 /**
  * The 1-based page an `offset` falls on – the numbered-pagination presentation
  * of the IR, shared by the surfaces and the adapters. `limit: 0` (a facet-only

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB;;;;;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;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1D;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,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,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAW3D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EACb,eAAe,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,eAAe,CAAC;CAC9E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,GACrB,SAAS,UAAU,EAAE,CA0DvB;AAED;yEACyE;AACzE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,GACrB,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/query.js

@@ -1,4 +1,5 @@
 import { fieldNamed, filterOperatorFor, ID_FIELD, } from './schema.js';
+import { MAX_JOIN_DEPTH } from './join-graph.js';
 // 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.
@@ -32,6 +33,10 @@ export function filterOn(criterion) {
  * is a disjunction that happens to include identity, not an enumeration of
  * wanted documents, so it stays the vacuous no-op every other empty `in` is.
  *
+ * A joined identity clause (`{ on: […], field: 'id', in: [] }`) reads the same
+ * way one hop out: it enumerates the *referents* wanted, and no referent means
+ * no document can match through that edge.
+ *
  * An adapter MUST answer an unsatisfiable query with an empty result rather
  * than dispatching it.
  */
@@ -45,6 +50,13 @@ export function isUnsatisfiable(query) {
             criterion.in.length === 0);
     });
 }
+/** 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. */
+function issueField(criterion) {
+    const on = criterion.on ?? [];
+    return on.length === 0 ? criterion.field : [...on, criterion.field].join('.');
+}
 /**
  * Structurally validate a query against its search type: **every criterion of
  * every `where` clause** names a declared, `filterable` field whose kind accepts
@@ -56,12 +68,21 @@ export function isUnsatisfiable(query) {
  * checks declaration only, not the `sortable` flag: that flag means *publicly
  * selectable*, and a deployment policy may sort on a private tie-break field.
  *
+ * A criterion carrying an {@link CriterionBase.on} join path is checked against
+ * the type that path reaches instead: the path must be at most
+ * {@link MAX_JOIN_DEPTH} hops (`join-too-deep`) and must resolve through
+ * `joins` (`unknown-join`), and the leaf field must then be filterable on the
+ * *target* type. The cap lives here, in the IR, rather than in an adapter or a
+ * surface, so every surface inherits it. `joins` is optional because a query
+ * with no join path needs none; a joined criterion validated without one is an
+ * `unknown-join`, never a silently unchecked filter.
+ *
  * This is the port’s always-on guard: every {@link SearchEngine} adapter MUST
  * reject a query with issues ({@link assertValidQuery}) instead of passing
  * garbage to its engine, so validation holds for every caller – including
  * `queryDefaults` policies and surfaces weaker than GraphQL.
  */
-export function validateQuery(query, searchType) {
+export function validateQuery(query, searchType, joins) {
     const issues = [];
     for (const filter of query.where) {
         // Each criterion is checked on its own, so a multi-criterion clause needs
@@ -71,6 +92,25 @@ export function validateQuery(query, searchType) {
         // a `reference` membership with a `date` range without either being wrong.
         for (const criterion of filter.or) {
             const name = criterion.field;
+            const field = issueField(criterion);
+            // A criterion may constrain a JOINED document, and then every rule below
+            // is about the type its `on` path reaches, not about the searched one.
+            // Resolving the path needs the schema’s join graph, so a caller that
+            // supplied none cannot serve a joined criterion at all.
+            const on = criterion.on ?? [];
+            let constrained = searchType;
+            if (on.length > 0) {
+                if (on.length > MAX_JOIN_DEPTH) {
+                    issues.push({ part: 'where', field, reason: 'join-too-deep' });
+                    continue;
+                }
+                const target = joins?.resolve(searchType, on);
+                if (target === undefined) {
+                    issues.push({ part: 'where', field, reason: 'unknown-join' });
+                    continue;
+                }
+                constrained = target;
+            }
             // `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.
@@ -78,23 +118,23 @@ export function validateQuery(query, searchType) {
                 if (filterOperator(criterion) !== 'in') {
                     issues.push({
                         part: 'where',
-                        field: name,
+                        field,
                         reason: 'operator-mismatch',
                     });
                 }
                 continue;
             }
-            const field = fieldNamed(searchType, name);
-            if (field === undefined) {
-                issues.push({ part: 'where', field: name, reason: 'unknown-field' });
+            const declared = fieldNamed(constrained, name);
+            if (declared === undefined) {
+                issues.push({ part: 'where', field, reason: 'unknown-field' });
             }
-            else if (field.filterable !== true) {
-                issues.push({ part: 'where', field: name, reason: 'not-filterable' });
+            else if (declared.filterable !== true) {
+                issues.push({ part: 'where', field, reason: 'not-filterable' });
             }
-            else if (filterOperatorFor(field.kind) !== filterOperator(criterion)) {
+            else if (filterOperatorFor(declared.kind) !== filterOperator(criterion)) {
                 issues.push({
                     part: 'where',
-                    field: name,
+                    field,
                     reason: 'operator-mismatch',
                 });
             }
@@ -123,8 +163,8 @@ export function validateQuery(query, searchType) {
 }
 /** Throw on the first structurally invalid query part ({@link validateQuery}),
  *  naming every issue. The always-on entry point for engine adapters. */
-export function assertValidQuery(query, searchType) {
-    const issues = validateQuery(query, searchType);
+export function assertValidQuery(query, searchType, joins) {
+    const issues = validateQuery(query, searchType, joins);
     if (issues.length > 0) {
         const detail = issues
             .map((issue) => `${issue.part}: “${issue.field}” (${issue.reason})`)

package/dist/schema.d.ts

@@ -189,28 +189,76 @@ export interface ReferenceField extends SearchFieldBase, Searchable {
      * resolution.
      */
     readonly labelSource?: string;
-    /** The referenced entity’s shape and how much of it to carry. Required when
-     *  the field is `output` (the API surfaces need the reference type name);
-     *  optional for a facet- or filter-only reference. */
+    /**
+     * Turn this reference into an **engine-level join**, so a query can filter
+     * this type by a condition on the referent – `“every object published by
+     * institution X”` in one round-trip instead of two. Valid only alongside
+     * {@link ReferenceField.labelSource}, which already asserts that this
+     * field’s values are ids of documents in that type’s collection – exactly
+     * the fact a join needs.
+     *
+     * A capability flag in the vocabulary of `filterable`/`facetable`/`sortable`,
+     * and deliberately not derived from `labelSource`: an engine may refuse to
+     * index a mutual reference, so auto-deriving would make an existing schema
+     * silently lose a field. A `labelSource` added for display therefore costs
+     * nothing it does not cost today; only a `joinable` edge pays the
+     * component-scoped rebuild coupling.
+     *
+     * Never on an `inline` reference: that carries its referent as a nested
+     * object rather than as an id an engine can point a reference field at.
+     *
+     * At most ONE joinable field per (type, label source) – see
+     * {@link joinGraph}.
+     */
+    readonly joinable?: boolean;
+    /**
+     * The referenced entity’s shape and how much of it to carry. Required when
+     * the field is `output` – the strategy is what decides the output shape, so
+     * a surfaced reference must state it; optional for a facet- or filter-only
+     * reference.
+     *
+     * A **discriminated union by `strategy`**, because `typeName` is load-bearing
+     * for two of the three and meaningless for the third: a `labelOnly` reference
+     * needs a name to emit its id-plus-label type under, an `inline` one needs a
+     * name that resolves to a declared {@link ReferenceType}, and an `idOnly` one
+     * carries a bare IRI that may belong to no declared type at all (`sameAs`
+     * points at a vocabulary nobody indexes). Declaring `typeName` on an `idOnly`
+     * reference is still useful where a target *is* nameable – an API surface can
+     * then tell IRIs of that target apart from IRIs at large.
+     */
     readonly ref?: {
         /** Logical API type name of the referenced entity (PascalCase, e.g.
-         *  `Organization`) – names the reference’s type in the API surfaces, the
-         *  way {@link SearchType.name} names a root type; fields sharing it share
-         *  one emitted type. For a `labelOnly`/`idOnly` reference it is a name,
-         *  not a key: it need not correspond to any indexed root type, and it may
-         *  name one (`creator` → `Person`, with the labels resolved from that
-         *  root’s collection via `labelSource`) – an API surface then serves the
-         *  reference under a derived name (GraphQL: `‹Name›Reference`) to keep
-         *  type names unique. An `inline` reference’s typeName instead resolves to
-         *  a declared {@link ReferenceType}, so it can never name a root type. */
+         *  `Organization`) – names the reference’s type in the API surfaces,
+         *  the way {@link SearchType.name} names a root type; fields sharing it
+         *  share one emitted type. For a `labelOnly` reference it is a name,
+         *  not a key: it need not correspond to any indexed root type, and it
+         *  may name one (`creator` → `Person`, with the labels resolved from
+         *  that root’s collection via `labelSource`) – an API surface then
+         *  serves the reference under a derived name (GraphQL:
+         *  `‹Name›Reference`) to keep type names unique. An `inline`
+         *  reference’s typeName instead resolves to a declared
+         *  {@link ReferenceType}, so it can never name a root type. */
         readonly typeName: string;
-        /** How much of the referenced entity the reference carries. `labelOnly`
-         *  (id + display label, resolved from a label source) and `inline` (the
-         *  referent’s own projected fields, carried inline through a declared
-         *  {@link ReferenceType} – see {@link isInlineReference}) are implemented;
-         *  `idOnly` is a forward declaration, so that declarations (and the SHACL
-         *  `search:nestedStrategy` mapping) keep their shape when it lands. */
-        readonly strategy: 'labelOnly' | 'idOnly' | 'inline';
+        /** `labelOnly` carries the id plus a display label resolved from a
+         *  label source; `inline` carries the referent’s own projected fields
+         *  through a declared {@link ReferenceType} (see
+         *  {@link isInlineReference}). */
+        readonly strategy: 'labelOnly' | 'inline';
+    } | {
+        /** Optional here, unlike the other strategies: an `idOnly` reference
+         *  emits no type of its own, so a name is not needed to emit one under.
+         *  Declare it when the referent’s IRIs form a nameable set an API
+         *  surface should distinguish; omit it for IRIs that belong to no such
+         *  set. */
+        readonly typeName?: string;
+        /** The IRI, and nothing else – no label resolution, no nested fields.
+         *  Surfaces as a bare IRI rather than an object, which is what makes it
+         *  the right strategy for a reference whose referent is not an entity
+         *  this deployment describes: a canonical vocabulary URI, a licence, a
+         *  content URL. A {@link ReferenceField.labelSource} is still honoured
+         *  for facet bucket labels – the strategy governs the output shape, not
+         *  whether a bucket can be labelled. */
+        readonly strategy: 'idOnly';
     };
 }
 /**
@@ -351,7 +399,8 @@ export interface SearchSchema<Types extends readonly SearchType[] = readonly Sea
  *
  * Every declaration is validated ({@link assertValidSearchType}) – the
  * declaration-time counterpart of the port’s `assertValidQuery` – and the
- * schema-wide invariants are enforced: no two Root Types may share a `class` IRI
+ * schema-wide invariants are enforced – including the join rules, by building
+ * the {@link joinGraph} eagerly: no two Root Types may share a `class` IRI
  * (they would silently overwrite each other in the map) and no two types may
  * share a `name` (names key the API surfaces, across Root and Reference Types
  * alike). Every inline reference must resolve to a declared Reference Type, and
@@ -435,7 +484,7 @@ export declare function labelFieldOf(searchType: SearchType): TextField | undefi
  */
 export interface SearchTypeIssue {
     readonly field: string;
-    readonly reason: 'duplicate-field-name' | 'invalid-field-name' | 'unknown-kind' | 'invalid-locale' | 'missing-ref' | 'ref-not-allowed' | 'text-requires-locales' | 'locales-not-allowed' | 'facet-ranges-not-allowed' | 'searchable-not-allowed' | 'transform-not-allowed' | 'derive-with-path' | 'from-not-allowed' | 'from-with-path' | 'from-with-derive' | 'from-with-inline-ref' | 'unknown-projection-value' | 'duplicate-projection-value' | 'text-not-filterable' | 'text-not-facetable' | 'reserved-field-name';
+    readonly reason: 'duplicate-field-name' | 'invalid-field-name' | 'unknown-kind' | 'invalid-locale' | 'missing-ref' | 'ref-not-allowed' | 'text-requires-locales' | 'locales-not-allowed' | 'facet-ranges-not-allowed' | 'searchable-not-allowed' | 'transform-not-allowed' | 'derive-with-path' | 'from-not-allowed' | 'from-with-path' | 'from-with-derive' | 'from-with-inline-ref' | 'unknown-projection-value' | 'duplicate-projection-value' | 'text-not-filterable' | 'text-not-facetable' | 'joinable-not-allowed' | 'joinable-without-label-source' | 'joinable-with-inline-ref' | 'reserved-field-name';
 }
 /**
  * The reserved logical name of a document’s IRI – the one field every indexed
@@ -478,6 +527,13 @@ export declare const OR_KEY = "or";
  *   reserved name↔locale separator);
  * - a `reference` field that is `output` declares `ref` (the API surfaces
  *   need the reference type name); `ref` on any other kind is meaningless;
+ * - `joinable` only on a `reference` field, and only alongside a `labelSource`
+ *   – the join addresses the referent’s collection, which is the one the label
+ *   source names, so without it the flag states an edge to nowhere – and never
+ *   on an `inline` reference, which is stored as a nested object rather than as
+ *   an id a reference field can point at. The schema-wide half of the rule (at
+ *   most one joinable field per (type, label source), no cycles) is
+ *   {@link joinGraph}’s;
  * - a `text` field declares at least one locale (`und` = untagged; projection and
  *   result reconstruction have no representation for unlocalized text – use
  *   `keyword` for untagged strings); `locales` on any other kind is
@@ -583,11 +639,20 @@ export declare function sortableFields(searchType: SearchType): readonly SearchF
 export declare function outputFields(searchType: SearchType): readonly SearchField[];
 /**
  * Whether a field declares **no** role – none of `output`, `searchable`,
- * `filterable`, `facetable`, `sortable`. Such a field is an **internal field**:
- * the projection populates it (so a later {@link SearchFieldBase.derive} can
- * read it), then prunes it before the document reaches a writer, and the engine
- * collection definition omits it entirely – not stored, not indexed, no RAM.
- * Absence of a role declares that intent; there is no separate marker flag.
+ * `filterable`, `facetable`, `sortable`, `joinable`. Such a field is an
+ * **internal field**: the projection populates it (so a later
+ * {@link SearchFieldBase.derive} can read it), then prunes it before the
+ * document reaches a writer, and the engine collection definition omits it
+ * entirely – not stored, not indexed, no RAM. Absence of a role declares that
+ * intent; there is no separate marker flag.
+ *
+ * {@link ReferenceField.joinable} counts as a role for exactly the reason the
+ * others do: it is a promise about what the *engine* can do with the field, and
+ * an engine can only join through a value it actually stores. Leaving it out
+ * would let a joinable-but-otherwise-role-less reference declare an edge the
+ * schema resolves, the query validates and the compiler emits – against a
+ * collection that never stored the column, so every such query fails at the
+ * engine.
  *
  * The single predicate the projection and the collection definition share, so
  * they cannot disagree on what is internal. See the Search context’s load-bearing
@@ -638,6 +703,24 @@ export declare function irAlias(searchType: SearchType, field: SearchField): str
 export declare function isRangeFacet(field: SearchField): field is NumericField & {
     readonly facetRanges: readonly FacetRange[];
 };
+/**
+ * Whether a value is an **absolute IRI**: a scheme, then anything with no
+ * whitespace. The single definition the projection (which
+ * drops a reference value failing it) and an API surface (which types such a
+ * value as an IRI, and rejects one that is not) both read, so the two cannot
+ * disagree about what a reference holds – the argument {@link physicalFields}
+ * makes for the physical fanout.
+ *
+ * Deliberately a **scheme check, not an `http(s)` one**. `urn:`, `doi:`, `ark:`,
+ * `tag:`, `mailto:` and a deployment’s own minted scheme (`urn:lde:…`) are
+ * ordinary Linked Data, and rejecting them would make this package refuse
+ * conformant data. What the check does exclude is what a reference must never
+ * hold: a blank node label (`_:b0` – a scheme must start with a letter), a bare
+ * token (`boerenbont`), and a relative reference. Full RFC 3987 parsing would
+ * buy nothing over that while starting to reject real data with a character
+ * someone forgot to percent-encode.
+ */
+export declare function isAbsoluteIri(value: string): boolean;
 /**
  * The engine storage codec for `date` fields: stored as Unix seconds (a
  * sortable, range-filterable int64), ISO 8601 at the API edges. One pair for

package/dist/schema.d.ts.map

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

package/dist/schema.js

@@ -1,3 +1,4 @@
+import { joinGraph } from './join-graph.js';
 const OPERATOR_BY_KIND = {
     text: undefined,
     keyword: 'in',
@@ -49,7 +50,8 @@ function isRootType(searchType) {
  *
  * Every declaration is validated ({@link assertValidSearchType}) – the
  * declaration-time counterpart of the port’s `assertValidQuery` – and the
- * schema-wide invariants are enforced: no two Root Types may share a `class` IRI
+ * schema-wide invariants are enforced – including the join rules, by building
+ * the {@link joinGraph} eagerly: no two Root Types may share a `class` IRI
  * (they would silently overwrite each other in the map) and no two types may
  * share a `name` (names key the API surfaces, across Root and Reference Types
  * alike). Every inline reference must resolve to a declared Reference Type, and
@@ -84,6 +86,12 @@ export function searchSchema(...types) {
         .filter(isRootType)
         .map((searchType) => [searchType.class, searchType]));
     referenceTypesBySchema.set(schema, referenceTypes);
+    // Build the join graph eagerly and discard it: it is cached per schema, and
+    // building it is what enforces the schema-wide join rules (one joinable
+    // reference per target, every target an indexed Root Type, no cycles). A
+    // schema whose joins do not hold up therefore fails HERE, not on the first
+    // query or – worse – halfway through the first rebuild.
+    joinGraph(schema);
     return schema;
 }
 /**
@@ -385,6 +393,13 @@ const LOCALE_PATTERN = /^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$/;
  *   reserved name↔locale separator);
  * - a `reference` field that is `output` declares `ref` (the API surfaces
  *   need the reference type name); `ref` on any other kind is meaningless;
+ * - `joinable` only on a `reference` field, and only alongside a `labelSource`
+ *   – the join addresses the referent’s collection, which is the one the label
+ *   source names, so without it the flag states an edge to nowhere – and never
+ *   on an `inline` reference, which is stored as a nested object rather than as
+ *   an id a reference field can point at. The schema-wide half of the rule (at
+ *   most one joinable field per (type, label source), no cycles) is
+ *   {@link joinGraph}’s;
  * - a `text` field declares at least one locale (`und` = untagged; projection and
  *   result reconstruction have no representation for unlocalized text – use
  *   `keyword` for untagged strings); `locales` on any other kind is
@@ -444,9 +459,27 @@ export function validateSearchType(searchType) {
             if (field.output === true && field.ref === undefined) {
                 issue('missing-ref');
             }
+            // A join addresses the referent’s collection, which is the collection the
+            // label source names: without one the flag states an edge to nowhere.
+            if (field.joinable === true && field.labelSource === undefined) {
+                issue('joinable-without-label-source');
+            }
+            // An inline reference is stored as a NESTED OBJECT, not as an id an
+            // engine can point a reference field at, so the two cannot both hold:
+            // the collection definition would emit the nesting and silently drop the
+            // reference, leaving a schema whose joins validate, compile and then fail
+            // at the engine. Carry the referent inline or join to it, not both.
+            if (field.joinable === true && field.ref?.strategy === 'inline') {
+                issue('joinable-with-inline-ref');
+            }
         }
-        else if (field.ref !== undefined) {
-            issue('ref-not-allowed');
+        else {
+            if (field.ref !== undefined) {
+                issue('ref-not-allowed');
+            }
+            if (field.joinable === true) {
+                issue('joinable-not-allowed');
+            }
         }
         if (field.kind === 'text') {
             if ((field.locales ?? []).length === 0) {
@@ -622,11 +655,20 @@ export function outputFields(searchType) {
 }
 /**
  * Whether a field declares **no** role – none of `output`, `searchable`,
- * `filterable`, `facetable`, `sortable`. Such a field is an **internal field**:
- * the projection populates it (so a later {@link SearchFieldBase.derive} can
- * read it), then prunes it before the document reaches a writer, and the engine
- * collection definition omits it entirely – not stored, not indexed, no RAM.
- * Absence of a role declares that intent; there is no separate marker flag.
+ * `filterable`, `facetable`, `sortable`, `joinable`. Such a field is an
+ * **internal field**: the projection populates it (so a later
+ * {@link SearchFieldBase.derive} can read it), then prunes it before the
+ * document reaches a writer, and the engine collection definition omits it
+ * entirely – not stored, not indexed, no RAM. Absence of a role declares that
+ * intent; there is no separate marker flag.
+ *
+ * {@link ReferenceField.joinable} counts as a role for exactly the reason the
+ * others do: it is a promise about what the *engine* can do with the field, and
+ * an engine can only join through a value it actually stores. Leaving it out
+ * would let a joinable-but-otherwise-role-less reference declare an edge the
+ * schema resolves, the query validates and the compiler emits – against a
+ * collection that never stored the column, so every such query fails at the
+ * engine.
  *
  * The single predicate the projection and the collection definition share, so
  * they cannot disagree on what is internal. See the Search context’s load-bearing
@@ -637,7 +679,8 @@ export function isInternalField(field) {
         field.searchable === undefined &&
         field.filterable !== true &&
         field.facetable !== true &&
-        field.sortable !== true);
+        field.sortable !== true &&
+        (field.kind !== 'reference' || field.joinable !== true));
 }
 /** Fields of kind `reference` (IRI-valued, label-resolved), in declaration order. */
 export function referenceFields(searchType) {
@@ -692,6 +735,30 @@ export function irAlias(searchType, field) {
 export function isRangeFacet(field) {
     return field.facetRanges !== undefined && field.facetRanges.length > 0;
 }
+/**
+ * Whether a value is an **absolute IRI**: a scheme, then anything with no
+ * whitespace. The single definition the projection (which
+ * drops a reference value failing it) and an API surface (which types such a
+ * value as an IRI, and rejects one that is not) both read, so the two cannot
+ * disagree about what a reference holds – the argument {@link physicalFields}
+ * makes for the physical fanout.
+ *
+ * Deliberately a **scheme check, not an `http(s)` one**. `urn:`, `doi:`, `ark:`,
+ * `tag:`, `mailto:` and a deployment’s own minted scheme (`urn:lde:…`) are
+ * ordinary Linked Data, and rejecting them would make this package refuse
+ * conformant data. What the check does exclude is what a reference must never
+ * hold: a blank node label (`_:b0` – a scheme must start with a letter), a bare
+ * token (`boerenbont`), and a relative reference. Full RFC 3987 parsing would
+ * buy nothing over that while starting to reject real data with a character
+ * someone forgot to percent-encode.
+ */
+export function isAbsoluteIri(value) {
+    return ABSOLUTE_IRI.test(value);
+}
+/** Scheme (RFC 3986 `ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )`), then any
+ *  run of non-whitespace. Non-ASCII is deliberately allowed: an IRI is not
+ *  restricted to ASCII. */
+const ABSOLUTE_IRI = /^[A-Za-z][A-Za-z0-9+.-]*:\S*$/;
 /**
  * The engine storage codec for `date` fields: stored as Unix seconds (a
  * sortable, range-filterable int64), ISO 8601 at the API edges. One pair for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.18.3",
+  "version": "0.20.0",
   "description": "Engine- and domain-agnostic core for RDF-backed search: a unified declarative field model (SearchField/SearchType/SearchSchema), a neutral query IR, the SearchEngine port with logical result types, and a streaming CONSTRUCT-to-document projection. Bakes in no engine, protocol, or domain.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",