@byline/core 3.14.0 → 3.15.0

package/dist/auth/register-collection-abilities.test.node.js

@@ -42,6 +42,7 @@ describe('registerCollectionAbilities', () => {
             'collections.pages.delete',
             'collections.pages.publish',
             'collections.pages.changeStatus',
+            'collections.pages.reindex',
         ]);
     });
     it('places every ability under the same `collections.<path>` group', () => {
@@ -49,7 +50,7 @@ describe('registerCollectionAbilities', () => {
         registerCollectionAbilities(registry, pageCollection());
         const buckets = registry.byGroup();
         expect(buckets.size).toBe(1);
-        expect(buckets.get('collections.pages')?.length).toBe(6);
+        expect(buckets.get('collections.pages')?.length).toBe(7);
     });
     it('derives labels from the collection singular/plural labels', () => {
         const registry = new AbilityRegistry();
@@ -60,6 +61,7 @@ describe('registerCollectionAbilities', () => {
         expect(registry.get('collections.pages.delete')?.label).toBe('Delete Page');
         expect(registry.get('collections.pages.publish')?.label).toBe('Publish Pages');
         expect(registry.get('collections.pages.changeStatus')?.label).toBe('Change status of Pages');
+        expect(registry.get('collections.pages.reindex')?.label).toBe('Reindex Pages search');
     });
     it('tags every ability with source: "collection"', () => {
         const registry = new AbilityRegistry();
@@ -68,7 +70,7 @@ describe('registerCollectionAbilities', () => {
             expect(descriptor.source).toBe('collection');
         }
     });
-    it('registers the same six-ability shape regardless of workflow complexity', () => {
+    it('registers the same seven-ability shape regardless of workflow complexity', () => {
         const registry = new AbilityRegistry();
         registerCollectionAbilities(registry, newsCollection());
         expect(registry.list().map((d) => d.key)).toEqual([
@@ -78,14 +80,15 @@ describe('registerCollectionAbilities', () => {
             'collections.news.delete',
             'collections.news.publish',
             'collections.news.changeStatus',
+            'collections.news.reindex',
         ]);
     });
-    it('is idempotent — calling twice leaves the registry with the same six entries', () => {
+    it('is idempotent — calling twice leaves the registry with the same seven entries', () => {
         const registry = new AbilityRegistry();
         const collection = pageCollection();
         registerCollectionAbilities(registry, collection);
         registerCollectionAbilities(registry, collection);
-        expect(registry.size).toBe(6);
+        expect(registry.size).toBe(7);
     });
     it('keeps multiple collections isolated in distinct groups', () => {
         const registry = new AbilityRegistry();
@@ -93,9 +96,9 @@ describe('registerCollectionAbilities', () => {
         registerCollectionAbilities(registry, newsCollection());
         const buckets = registry.byGroup();
         expect(buckets.size).toBe(2);
-        expect(buckets.get('collections.pages')?.length).toBe(6);
-        expect(buckets.get('collections.news')?.length).toBe(6);
-        expect(registry.size).toBe(12);
+        expect(buckets.get('collections.pages')?.length).toBe(7);
+        expect(buckets.get('collections.news')?.length).toBe(7);
+        expect(registry.size).toBe(14);
     });
 });
 describe('COLLECTION_ABILITY_VERBS / collectionAbilityKey', () => {
@@ -107,6 +110,7 @@ describe('COLLECTION_ABILITY_VERBS / collectionAbilityKey', () => {
             'delete',
             'publish',
             'changeStatus',
+            'reindex',
         ]);
     });
     it('collectionAbilityKey composes a flat dotted key', () => {

package/dist/config/config.d.ts

@@ -1,4 +1,4 @@
-import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ServerConfig } from '../@types/index.js';
+import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ColumnDefinition, ServerConfig } from '../@types/index.js';
 /**
  * Resolve a collection definition by `path`. Returns `null` either when
  * no config has been registered (e.g. unit tests, isolated tooling) or
@@ -12,6 +12,17 @@ import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ServerC
  */
 export declare const getCollectionDefinition: (path: string) => CollectionDefinition | null;
 export declare const getCollectionAdminConfig: (slug: string) => CollectionAdminConfig | null;
+/**
+ * Resolve a collection's item-row/tile columns — the per-collection projection
+ * + presentation contract used by the relation picker, relation/`hasMany`
+ * tiles, and (planned) search-result rows.
+ *
+ * Prefers the canonical {@link CollectionAdminConfig.itemView}, falling back to
+ * the deprecated `picker` alias. Always read item-view columns through this
+ * helper rather than touching `config.picker` directly, so the alias keeps
+ * working until it is removed.
+ */
+export declare const resolveItemViewColumns: (config: CollectionAdminConfig | null | undefined) => ColumnDefinition[] | undefined;
 export declare function defineClientConfig(config: ClientConfig): void;
 export declare function defineServerConfig(config: ServerConfig): void;
 export declare function getClientConfig(): ClientConfig;

package/dist/config/config.js

@@ -54,6 +54,17 @@ export const getCollectionAdminConfig = (slug) => {
         return null;
     return clientConfig.admin?.find((admin) => admin.slug === slug) ?? null;
 };
+/**
+ * Resolve a collection's item-row/tile columns — the per-collection projection
+ * + presentation contract used by the relation picker, relation/`hasMany`
+ * tiles, and (planned) search-result rows.
+ *
+ * Prefers the canonical {@link CollectionAdminConfig.itemView}, falling back to
+ * the deprecated `picker` alias. Always read item-view columns through this
+ * helper rather than touching `config.picker` directly, so the alias keeps
+ * working until it is removed.
+ */
+export const resolveItemViewColumns = (config) => config?.itemView ?? config?.picker;
 export function defineClientConfig(config) {
     validateCollections(config.collections);
     validateAdminConfigs(config.admin, config.collections);

package/dist/config/resolve-item-view-columns.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/config/resolve-item-view-columns.test.node.js

@@ -0,0 +1,30 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { resolveItemViewColumns } from './config.js';
+const itemViewCols = [{ fieldName: 'title', label: 'Title' }];
+const pickerCols = [{ fieldName: 'name', label: 'Name' }];
+const cfg = (over) => ({ slug: 'x', ...over });
+describe('resolveItemViewColumns', () => {
+    it('returns itemView when present', () => {
+        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols }))).toBe(itemViewCols);
+    });
+    it('falls back to the deprecated picker alias', () => {
+        expect(resolveItemViewColumns(cfg({ picker: pickerCols }))).toBe(pickerCols);
+    });
+    it('prefers itemView over picker when both are present', () => {
+        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols, picker: pickerCols }))).toBe(itemViewCols);
+    });
+    it('returns undefined when neither is set', () => {
+        expect(resolveItemViewColumns(cfg({}))).toBeUndefined();
+    });
+    it('tolerates null / undefined config', () => {
+        expect(resolveItemViewColumns(null)).toBeUndefined();
+        expect(resolveItemViewColumns(undefined)).toBeUndefined();
+    });
+});

package/dist/core.js

@@ -14,6 +14,7 @@ import { ensureCollections } from './services/collection-bootstrap.js';
 import { discoverCounterGroups } from './services/discover-counter-groups.js';
 import { validateTranslations } from './services/i18n-validator.js';
 import { validateRichTextFieldFlags } from './services/richtext-populate.js';
+import { validateSearchConfig } from './services/validate-search-config.js';
 /**
  * Initialize Byline CMS core services via the typed registry.
  *
@@ -46,6 +47,12 @@ export const initBylineCore = async (config, pinoLogger) => {
         populate: config.fields?.richText?.populate != null,
         embed: config.fields?.richText?.embed != null,
     });
+    // Validate search configuration: a collection that opts into search must
+    // have a SearchProvider registered, otherwise indexing / client.search()
+    // would silently no-op. Fail-fast at boot, same posture as richText above.
+    validateSearchConfig(composed.collections, {
+        provider: config.search != null,
+    });
     // Validate the admin i18n translation registry against the configured
     // interface locale set. Throws on structural errors (missing bundle for
     // a declared locale, defaultLocale outside the permitted set, …); soft

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
-export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';

package/dist/index.js

@@ -16,7 +16,7 @@
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
-export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';

package/dist/services/build-search-document.d.ts

@@ -0,0 +1,46 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { CollectionDefinition, RichTextToTextFn, SearchDocument } from '../@types/index.js';
+/** A locale-resolved document fed to the assembler — one locale's view. */
+export interface SearchSourceDocument {
+    /** Stable document id (shared across versions and locales). */
+    documentId: string;
+    /** Content locale this view represents. */
+    locale: string;
+    /** Lifecycle status of the indexed version. */
+    status: string;
+    /** URL path, or null when the collection has none. */
+    path?: string | null;
+    /**
+     * Locale-resolved, camelCase field data (the `ClientDocument.fields`
+     * shape). Relation fields named in `search.facets` must be populated.
+     */
+    fields: Record<string, any>;
+    /** Timestamp of the indexed version. */
+    updatedAt?: Date | string;
+}
+export interface BuildSearchDocumentOptions {
+    /**
+     * Rich-text plain-text extractor (`ServerConfig.fields.richText.toText`).
+     * Required for `richText` fields named in `search.body`; without it those
+     * fields are skipped.
+     */
+    richTextToText?: RichTextToTextFn;
+    /**
+     * Resolve a target collection definition by path — used to find a facet
+     * target's identity field (the term) and `counter` field (the id).
+     */
+    resolveTargetDefinition?: (collectionPath: string) => CollectionDefinition | null;
+    /** Content locale, for defensive locale-envelope resolution. */
+    locale?: string;
+}
+/**
+ * Assemble one type-enriched `SearchDocument` from a locale-resolved
+ * document and its collection's role-based `search` config.
+ */
+export declare function buildSearchDocument(doc: SearchSourceDocument, definition: CollectionDefinition, options?: BuildSearchDocumentOptions): SearchDocument;

package/dist/services/build-search-document.js

@@ -0,0 +1,220 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * `buildSearchDocument` — the document-grain assembler for the
+ * `SearchProvider` seam. Walks a collection's role-based `search` config
+ * against one locale-resolved document and emits a single, type-enriched
+ * `SearchDocument` for a driver to index. See
+ * `docs/05-reading-and-delivery/07-search.md`.
+ *
+ * Role-based and explicit: only the fields named in `search.{body,facets,
+ * filters}` are projected — nothing is auto-pulled, so unindexed content
+ * never leaks into the index. Core derives each field's `SearchFieldType`
+ * from the schema (the "type enrichment") so a driver can map it onto its
+ * own index without re-inspecting the collection definition.
+ *
+ * Pure and synchronous, like `documentToMarkdown`: the rich-text plain-text
+ * extractor is the editor-agnostic `toText` seam passed via options, and
+ * relation targets are resolved through a caller-supplied definition
+ * resolver — no globals, no DB reads. The caller is responsible for handing
+ * in a document whose `facets` relation fields are already populated (depth
+ * 1) with the target's identity + counter fields.
+ *
+ * v1 scope: `search.{body,facets,filters}` name **top-level** fields. Deep
+ * paths into blocks / arrays are a follow-up.
+ */
+import { resolveIdentityField } from './populate.js';
+/**
+ * Assemble one type-enriched `SearchDocument` from a locale-resolved
+ * document and its collection's role-based `search` config.
+ */
+export function buildSearchDocument(doc, definition, options = {}) {
+    const locale = options.locale ?? doc.locale;
+    const search = definition.search ?? {};
+    const fieldsData = doc.fields ?? {};
+    const title = stringValue(resolveLocalized(fieldsData[resolveIdentityField(definition) ?? ''], locale)) ?? '';
+    const zones = search.zones != null && search.zones.length > 0 ? search.zones : [definition.path];
+    const fields = [];
+    // --- body: searchable text -------------------------------------------------
+    for (const decl of search.body ?? []) {
+        const name = declName(decl);
+        const field = definition.fields.find((f) => f.name === name);
+        if (field == null)
+            continue;
+        let value;
+        if (field.type === 'richText') {
+            value = options.richTextToText
+                ? nonEmpty(options.richTextToText({
+                    value: resolveLocalized(fieldsData[name], locale),
+                    fieldPath: name,
+                    collectionPath: definition.path,
+                }))
+                : null;
+        }
+        else {
+            value = stringValue(resolveLocalized(fieldsData[name], locale));
+        }
+        if (value != null) {
+            fields.push(withBoost({ name, type: 'text', role: 'body', value }, decl));
+        }
+    }
+    // --- facets: controlled-vocabulary references ------------------------------
+    for (const decl of search.facets ?? []) {
+        const name = declName(decl);
+        const field = definition.fields.find((f) => f.name === name);
+        if (field == null || field.type !== 'relation')
+            continue;
+        const targetPath = field.targetCollection;
+        const targetDef = targetPath ? (options.resolveTargetDefinition?.(targetPath) ?? null) : null;
+        const termField = targetDef ? resolveIdentityField(targetDef) : undefined;
+        const idField = targetDef?.fields.find((f) => f.type === 'counter')?.name;
+        const facetValues = toEnvelopeArray(fieldsData[name])
+            .map((env) => extractFacetValue(env, termField, idField, locale))
+            .filter((v) => v != null);
+        if (facetValues.length > 0) {
+            fields.push(withBoost({ name, type: 'facet', role: 'facet', value: facetValues }, decl));
+        }
+    }
+    // --- filters: scalar projections for filtering / sorting -------------------
+    for (const name of search.filters ?? []) {
+        const field = definition.fields.find((f) => f.name === name);
+        if (field == null)
+            continue;
+        const type = filterType(field.type);
+        const value = coerceFilterValue(resolveLocalized(fieldsData[name], locale), type);
+        if (value != null) {
+            fields.push({ name, type, role: 'filter', value });
+        }
+    }
+    return {
+        collectionPath: definition.path,
+        documentId: doc.documentId,
+        locale,
+        status: doc.status,
+        zones,
+        title,
+        path: doc.path ?? null,
+        fields,
+        updatedAt: dateValue(doc.updatedAt) ?? new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function declName(decl) {
+    return typeof decl === 'string' ? decl : decl.field;
+}
+function withBoost(field, decl) {
+    const boost = typeof decl === 'string' ? undefined : decl.boost;
+    return boost != null ? { ...field, boost } : field;
+}
+/** A populated single relation or array of relations → array of envelopes. */
+function toEnvelopeArray(value) {
+    if (Array.isArray(value))
+        return value.filter((v) => v != null);
+    if (value != null && typeof value === 'object')
+        return [value];
+    return [];
+}
+function extractFacetValue(envelope, termField, idField, locale) {
+    const target = asRecord(envelope.document);
+    const targetFields = asRecord(target.fields);
+    const term = termField ? stringValue(resolveLocalized(targetFields[termField], locale)) : null;
+    if (term == null)
+        return null;
+    // Prefer the target's stable counter id (the aggregator's reporting key);
+    // fall back to its document id when the vocabulary has no counter field.
+    const rawId = idField != null ? targetFields[idField] : undefined;
+    const id = typeof rawId === 'number' || typeof rawId === 'string'
+        ? rawId
+        : (stringValue(target.documentId ?? target.id) ?? term);
+    return { id, term };
+}
+/** Map a collection field type to the filter-side `SearchFieldType`. */
+function filterType(fieldType) {
+    switch (fieldType) {
+        case 'integer':
+        case 'counter':
+            return 'integer';
+        case 'float':
+        case 'decimal':
+            return 'float';
+        case 'boolean':
+        case 'checkbox':
+            return 'boolean';
+        case 'date':
+        case 'time':
+        case 'datetime':
+            return 'datetime';
+        default:
+            return 'keyword';
+    }
+}
+function coerceFilterValue(value, type) {
+    if (value == null)
+        return null;
+    switch (type) {
+        case 'integer':
+        case 'float': {
+            const n = typeof value === 'number' ? value : Number(value);
+            return Number.isFinite(n) ? n : null;
+        }
+        case 'boolean':
+            return typeof value === 'boolean' ? value : null;
+        case 'datetime':
+            return dateValue(value);
+        default:
+            return stringValue(value);
+    }
+}
+/**
+ * Locale-scoped reads deliver flat values; `locale: 'all'` reads deliver
+ * `{ en: …, fr: … }` envelopes. Pick the requested locale (or the first
+ * available) when an envelope sneaks through.
+ */
+function resolveLocalized(value, locale) {
+    if (value != null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        !(value instanceof Date)) {
+        const record = value;
+        const keys = Object.keys(record);
+        const localeLike = keys.length > 0 && keys.every((k) => /^[a-z]{2}(-[A-Za-z]{2,4})?$/.test(k));
+        if (localeLike) {
+            if (locale && locale in record)
+                return record[locale];
+            return record[keys[0]];
+        }
+    }
+    return value;
+}
+function asRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function nonEmpty(value) {
+    return value != null && value.trim().length > 0 ? value : null;
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value.trim().length > 0 ? value : null;
+    if (typeof value === 'number')
+        return String(value);
+    return null;
+}
+function dateValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'string') {
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime()))
+            return date.toISOString();
+    }
+    return null;
+}

package/dist/services/build-search-document.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/services/build-search-document.test.node.js

@@ -0,0 +1,164 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Contract tests for the document-grain search assembler. Verifies the
+ * role-based projection (body / facets / filters / zones), the schema-derived
+ * type enrichment, per-field boost, and that nothing outside the config is
+ * pulled (no leakage of unindexed content).
+ */
+import { describe, expect, it } from 'vitest';
+import { buildSearchDocument } from './build-search-document.js';
+// A controlled-vocabulary facet collection: a `counter` id + a `name` term.
+const topics = {
+    path: 'topics',
+    labels: { singular: 'Topic', plural: 'Topics' },
+    useAsTitle: 'name',
+    fields: [
+        { name: 'name', label: 'Name', type: 'text', localized: true },
+        { name: 'facetId', label: 'Facet Id', type: 'counter', group: 'publication-facets' },
+    ],
+};
+const publications = {
+    path: 'publications',
+    labels: { singular: 'Publication', plural: 'Publications' },
+    useAsTitle: 'title',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text', localized: true },
+        { name: 'abstract', label: 'Abstract', type: 'richText', localized: true },
+        { name: 'editorialNotes', label: 'Editorial Notes', type: 'textArea' },
+        { name: 'publicationDate', label: 'Date', type: 'datetime' },
+        { name: 'citationCount', label: 'Citations', type: 'integer' },
+        {
+            name: 'topics',
+            label: 'Topics',
+            type: 'relation',
+            targetCollection: 'topics',
+        },
+    ],
+    search: {
+        body: ['title', { field: 'abstract', boost: 2 }],
+        facets: ['topics'],
+        filters: ['publicationDate', 'citationCount'],
+        zones: ['site', 'publications'],
+    },
+};
+const resolveTargetDefinition = (path) => (path === 'topics' ? topics : null);
+// Stub `toText` seam — returns a string property so we don't depend on Lexical.
+const richTextToText = ({ value }) => typeof value === 'object' && value != null ? String(value.text ?? '') : '';
+function source() {
+    return {
+        documentId: 'doc-1',
+        locale: 'en',
+        status: 'published',
+        path: 'forest-restoration',
+        updatedAt: '2026-06-01T00:00:00.000Z',
+        fields: {
+            title: 'Forest Restoration',
+            abstract: { text: 'Methods for restoring degraded forest.' },
+            editorialNotes: 'Internal: chase the author for figures.',
+            publicationDate: '2026-05-01T00:00:00.000Z',
+            citationCount: 42,
+            topics: [
+                {
+                    _resolved: true,
+                    document: { documentId: 't-1', fields: { name: 'Ecology', facetId: 1 } },
+                },
+                {
+                    _resolved: true,
+                    document: { documentId: 't-2', fields: { name: 'Biodiversity', facetId: 2 } },
+                },
+            ],
+        },
+    };
+}
+function fieldByName(fields, name) {
+    return fields.find((f) => f.name === name);
+}
+describe('buildSearchDocument', () => {
+    const doc = buildSearchDocument(source(), publications, {
+        richTextToText,
+        resolveTargetDefinition,
+    });
+    it('sets identity, status, locale, path, and updatedAt', () => {
+        expect(doc.collectionPath).toBe('publications');
+        expect(doc.documentId).toBe('doc-1');
+        expect(doc.locale).toBe('en');
+        expect(doc.status).toBe('published');
+        expect(doc.title).toBe('Forest Restoration');
+        expect(doc.path).toBe('forest-restoration');
+        expect(doc.updatedAt).toBe('2026-06-01T00:00:00.000Z');
+    });
+    it('resolves zones from config', () => {
+        expect(doc.zones).toEqual(['site', 'publications']);
+    });
+    it('projects body text fields as type:text role:body', () => {
+        const title = fieldByName(doc.fields, 'title');
+        expect(title).toMatchObject({
+            name: 'title',
+            type: 'text',
+            role: 'body',
+            value: 'Forest Restoration',
+        });
+    });
+    it('extracts richText body via the toText seam and carries boost', () => {
+        const abstract = fieldByName(doc.fields, 'abstract');
+        expect(abstract).toMatchObject({
+            name: 'abstract',
+            type: 'text',
+            role: 'body',
+            value: 'Methods for restoring degraded forest.',
+            boost: 2,
+        });
+    });
+    it('resolves facets to {id, term} from target counter + useAsTitle', () => {
+        const topicsField = fieldByName(doc.fields, 'topics');
+        expect(topicsField).toMatchObject({ name: 'topics', type: 'facet', role: 'facet' });
+        expect(topicsField?.value).toEqual([
+            { id: 1, term: 'Ecology' },
+            { id: 2, term: 'Biodiversity' },
+        ]);
+    });
+    it('projects filters with schema-derived types', () => {
+        expect(fieldByName(doc.fields, 'publicationDate')).toMatchObject({
+            type: 'datetime',
+            role: 'filter',
+            value: '2026-05-01T00:00:00.000Z',
+        });
+        expect(fieldByName(doc.fields, 'citationCount')).toMatchObject({
+            type: 'integer',
+            role: 'filter',
+            value: 42,
+        });
+    });
+    it('does not pull fields outside the search config (no leakage)', () => {
+        expect(fieldByName(doc.fields, 'editorialNotes')).toBeUndefined();
+    });
+    it('defaults zones to the collection path when unset', () => {
+        const noZones = { ...publications, search: { body: ['title'] } };
+        const out = buildSearchDocument(source(), noZones);
+        expect(out.zones).toEqual(['publications']);
+    });
+    it('skips richText body fields when no toText seam is registered', () => {
+        const out = buildSearchDocument(source(), publications, { resolveTargetDefinition });
+        expect(fieldByName(out.fields, 'abstract')).toBeUndefined();
+        // Plain text body field still projects.
+        expect(fieldByName(out.fields, 'title')).toBeDefined();
+    });
+    it('resolves localized values to the requested locale', () => {
+        const localized = {
+            ...source(),
+            fields: { ...source().fields, title: { en: 'Forest Restoration', fr: 'Restauration' } },
+        };
+        const out = buildSearchDocument(localized, publications, {
+            richTextToText,
+            resolveTargetDefinition,
+            locale: 'fr',
+        });
+        expect(out.title).toBe('Restauration');
+    });
+});

package/dist/services/index.d.ts

@@ -1,6 +1,7 @@
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { type AssignCounterValuesInput, assignCounterValues } from './assign-counter-values.js';
+export { type BuildSearchDocumentOptions, buildSearchDocument, type SearchSourceDocument, } from './build-search-document.js';
 export { type CollectionRecord, type EnsureCollectionsInput, ensureCollections, } from './collection-bootstrap.js';
 export { type DiscoverCounterGroupsInput, discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';
@@ -8,8 +9,9 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { type InterfaceI18nConfig, type TranslationDriftWarning, type ValidateTranslationsResult, validateTranslations, } from './i18n-validator.js';
-export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, type UnresolvedRelationValue, } from './populate.js';
+export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, resolveIdentityField, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
 export { collectRichTextLeaves, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextAdapterPresence, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { type SearchProviderPresence, validateSearchConfig, } from './validate-search-config.js';
 export { type FieldLeaf, walkFieldTree } from './walk-field-tree.js';