@lde/search 0.19.0 → 0.21.0

package/dist/adapter.d.ts

@@ -9,6 +9,8 @@
 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,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,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

@@ -8,4 +8,5 @@
  */
 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.js

@@ -121,7 +121,16 @@ function applyField(document, node, field, searchType, schema, context) {
         return applyProjectionValue(document, field, field.from, context);
     }
     if (field.derive !== undefined) {
-        const value = field.derive(document, context);
+        const derived = field.derive(document, context);
+        // A derived `reference` is held to the same rule as a read one: what it
+        // stores is a selection key, and the surface types it `IRI`. ADR 19 sends
+        // an IRI-valued `keyword` derive here by converting it to `reference`, so
+        // this is the busiest way a non-IRI could otherwise reach the index. A
+        // value that survives nothing leaves the field absent, exactly as a derive
+        // returning `undefined` does.
+        const value = field.kind === 'reference' && derived !== undefined
+            ? derivedIris(derived)
+            : derived;
         if (value !== undefined) {
             document[field.name] = value;
         }
@@ -236,7 +245,14 @@ function foldedSearchValue(values) {
  * document – a value the API cannot serialize.
  */
 function applyFacet(document, raw, field) {
-    const values = dedupe(field.transform ? raw.map(field.transform) : raw);
+    // A `reference` stores identity, so what it stores must be an IRI whatever
+    // route the value arrived by. {@link iriString} guards the graph path, but a
+    // `transform` runs after it and a `from` projection value never passes it at
+    // all – so both are checked here, at the one point they share. Without this
+    // the surface would promise `IRI` over a value the projection let through.
+    const referenced = field.kind === 'reference';
+    const transformed = field.transform ? raw.map(field.transform) : raw;
+    const values = dedupe(referenced ? transformed.filter(isAbsoluteIri) : transformed);
     const folded = dedupe(values.map((value) => fold(value)));
     const searchField = physicalFields(field).search[0];
     if (field.array === true) {
@@ -384,6 +400,17 @@ function iriString(value) {
     const iri = isObject(value) ? value['@id'] : value;
     return typeof iri === 'string' && isAbsoluteIri(iri) ? iri : undefined;
 }
+/** What a `derive` on a `reference` field is allowed to have produced: the
+ *  absolute IRIs among its return value, keeping the shape the declaration
+ *  promises (a list stays a list, a single value stays single) so `array` still
+ *  decides the stored shape. A lone non-IRI becomes `undefined`, i.e. absent –
+ *  the same outcome the graph path gives it. */
+function derivedIris(value) {
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === 'string' && isAbsoluteIri(entry));
+    }
+    return typeof value === 'string' && isAbsoluteIri(value) ? value : 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,6 +189,28 @@ export interface ReferenceField extends SearchFieldBase, Searchable {
      * resolution.
      */
     readonly labelSource?: string;
+    /**
+     * 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
@@ -377,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
@@ -461,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' | 'missing-ref-type-name' | '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
@@ -503,7 +526,16 @@ export declare const OR_KEY = "or";
  * - a `text` field’s declared locales are BCP-47-shaped (no `_`, which is the
  *   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;
+ *   need the reference type name), and – unless its strategy is `idOnly`, which
+ *   emits no type of its own – that `ref` declares a `typeName`; `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
@@ -609,11 +641,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

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;
 }
 /**
@@ -384,7 +392,16 @@ const LOCALE_PATTERN = /^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$/;
  * - a `text` field’s declared locales are BCP-47-shaped (no `_`, which is the
  *   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;
+ *   need the reference type name), and – unless its strategy is `idOnly`, which
+ *   emits no type of its own – that `ref` declares a `typeName`; `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 +461,38 @@ export function validateSearchType(searchType) {
             if (field.output === true && field.ref === undefined) {
                 issue('missing-ref');
             }
+            // `typeName` is optional only for `idOnly`, which emits no type and so
+            // needs no name to emit one under. Every other surfaced strategy is
+            // served AS a named type, and without a name an API surface has nothing
+            // to emit – the GraphQL one silently prints `undefined` as the field’s
+            // type, publishing a contract that is not a schema.
+            if (field.output === true &&
+                field.ref !== undefined &&
+                field.ref.strategy !== 'idOnly' &&
+                field.ref.typeName === undefined) {
+                issue('missing-ref-type-name');
+            }
+            // 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 +668,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 +692,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.19.0",
+  "version": "0.21.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",