@byline/search-postgres 3.15.0

package/dist/build-index-row.test.node.js

@@ -0,0 +1,122 @@
+/**
+ * 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 { buildIndexRow, weightClass } from './build-index-row.js';
+import { createRegconfigResolver } from './locale-regconfig.js';
+function doc(overrides = {}) {
+    return {
+        collectionPath: 'publications',
+        documentId: 'doc-1',
+        locale: 'en',
+        status: 'published',
+        zones: ['site'],
+        title: 'Forest Restoration',
+        path: 'forest-restoration',
+        updatedAt: '2026-06-01T00:00:00.000Z',
+        fields: [],
+        ...overrides,
+    };
+}
+describe('weightClass', () => {
+    it('uses the role default when no boost is set', () => {
+        expect(weightClass(undefined, 'B')).toBe('B');
+        expect(weightClass(undefined, 'C')).toBe('C');
+    });
+    it('maps boost magnitude to a weight class', () => {
+        expect(weightClass(2, 'B')).toBe('A');
+        expect(weightClass(1, 'C')).toBe('B');
+        expect(weightClass(0.5, 'B')).toBe('C');
+        expect(weightClass(0.1, 'B')).toBe('D');
+    });
+});
+describe('buildIndexRow', () => {
+    it('does not auto-index the title (display-only; body controls searchability)', () => {
+        const row = buildIndexRow(doc());
+        expect(row.weighted.A).toBe('');
+        expect(row.weighted.B).toBe('');
+        expect(row.body).toBe('');
+        // title still rides the row for display.
+        expect(row.title).toBe('Forest Restoration');
+    });
+    it('makes the title searchable when listed in body (boosted to A)', () => {
+        const row = buildIndexRow(doc({
+            fields: [
+                { name: 'title', type: 'text', role: 'body', value: 'Forest Restoration', boost: 2 },
+            ],
+        }));
+        expect(row.weighted.A).toBe('Forest Restoration');
+    });
+    it('places body fields in B by default and respects boost', () => {
+        const row = buildIndexRow(doc({
+            fields: [
+                { name: 'summary', type: 'text', role: 'body', value: 'A short summary.' },
+                { name: 'abstract', type: 'text', role: 'body', value: 'Detailed abstract.', boost: 2 },
+            ],
+        }));
+        expect(row.weighted.B).toBe('A short summary.');
+        expect(row.weighted.A).toContain('Detailed abstract.');
+    });
+    it('projects facet ids into facets and folds terms into searchable text (class C)', () => {
+        const row = buildIndexRow(doc({
+            fields: [
+                {
+                    name: 'topics',
+                    type: 'facet',
+                    role: 'facet',
+                    value: [
+                        { id: 1, term: 'Ecology' },
+                        { id: 2, term: 'Biodiversity' },
+                    ],
+                },
+            ],
+        }));
+        expect(row.facets).toEqual({
+            topics: [
+                { id: 1, term: 'Ecology' },
+                { id: 2, term: 'Biodiversity' },
+            ],
+        });
+        expect(row.weighted.C).toBe('Ecology\nBiodiversity');
+    });
+    it('projects filters and keeps them out of the search text', () => {
+        const row = buildIndexRow(doc({
+            fields: [
+                { name: 'citationCount', type: 'integer', role: 'filter', value: 42 },
+                { name: 'publishedYear', type: 'integer', role: 'filter', value: 2026 },
+            ],
+        }));
+        expect(row.filters).toEqual({ citationCount: 42, publishedYear: 2026 });
+        expect(row.body).toBe('');
+    });
+    it('concatenates all weighted text into body for snippets', () => {
+        const row = buildIndexRow(doc({
+            fields: [
+                { name: 'summary', type: 'text', role: 'body', value: 'Body text.' },
+                { name: 'topics', type: 'facet', role: 'facet', value: [{ id: 1, term: 'Ecology' }] },
+            ],
+        }));
+        expect(row.body).toBe('Body text.\nEcology');
+    });
+});
+describe('createRegconfigResolver', () => {
+    const resolve = createRegconfigResolver();
+    it('maps known locales (and their base) to a Postgres regconfig', () => {
+        expect(resolve('en')).toBe('english');
+        expect(resolve('fr')).toBe('french');
+        expect(resolve('fr-CA')).toBe('french');
+    });
+    it('falls back to simple for unknown locales / undefined', () => {
+        expect(resolve('th')).toBe('simple');
+        expect(resolve(undefined)).toBe('simple');
+    });
+    it('honours overrides and a custom fallback', () => {
+        const custom = createRegconfigResolver({ th: 'thai' }, 'english');
+        expect(custom('th')).toBe('thai');
+        expect(custom('xx')).toBe('english');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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
+ */
+/**
+ * `@byline/search-postgres` — the built-in Postgres full-text `SearchProvider`.
+ *
+ * Reuses the host's existing Postgres connection (no new infrastructure) and
+ * owns its own schema (a weighted `tsvector` index table; see `migrate`).
+ * Register it on `ServerConfig.search`:
+ *
+ * ```ts
+ * import { pgAdapter } from '@byline/db-postgres'
+ * import { postgresSearch } from '@byline/search-postgres'
+ *
+ * const db = pgAdapter({ connectionString, collections, defaultContentLocale })
+ *
+ * defineServerConfig({
+ *   db,
+ *   // Dev convenience: ensure the search schema at boot. In production,
+ *   // prefer running `migrate(db.pool)` (or the SQL files) deliberately.
+ *   search: postgresSearch({ pool: db.pool, autoMigrate: true }),
+ * })
+ * ```
+ */
+import type { SearchProvider } from '@byline/core';
+import type { Pool } from 'pg';
+export { buildIndexRow, type IndexRow, type WeightClass, weightClass } from './build-index-row.js';
+export { createRegconfigResolver, DEFAULT_FALLBACK_REGCONFIG, type RegconfigResolver, } from './locale-regconfig.js';
+export { type MigrateOptions, type MigrateResult, migrate } from './migrate.js';
+export { PostgresSearchProvider } from './postgres-search-provider.js';
+export interface PostgresSearchOptions {
+    /**
+     * The host's existing pg connection pool — typically `db.pool` from
+     * `pgAdapter`. Reused so the search index lives in the same database with
+     * no second connection.
+     */
+    pool: Pool;
+    /**
+     * When `true`, ensure the search schema by running pending migrations at
+     * construction (idempotent). Defaults to `false` — prefer running
+     * `migrate(pool)` (or the SQL files) deliberately in production, per the
+     * package README. Convenient for development.
+     */
+    autoMigrate?: boolean;
+    /**
+     * Override or extend the locale → Postgres `regconfig` (text-search
+     * language) map. Merged over the built-in defaults.
+     */
+    localeRegconfig?: Record<string, string>;
+    /**
+     * Fallback `regconfig` for locales not in the map. Defaults to `'simple'`
+     * (no stemming / stop-words — unstemmed but correct).
+     */
+    fallbackRegconfig?: string;
+    /**
+     * Locale used to choose the query text-search config when a `search()`
+     * call omits `locale`. Set this to the host's default content locale so a
+     * locale-less query matches default-locale documents (otherwise it falls
+     * back to `simple` and won't match locale-stemmed vectors).
+     */
+    defaultLocale?: string;
+    /** Optional sink for migration progress lines (e.g. the host logger). */
+    log?: (message: string) => void;
+}
+/**
+ * Construct the Postgres full-text search provider. Mirrors the established
+ * adapter-factory shape (`postgresSearch({ pool })`).
+ *
+ * Note: `autoMigrate` runs asynchronously and is not awaited here (the
+ * factory is synchronous to match the seam). For deterministic startup —
+ * especially the first deploy, before any read — call and await
+ * `migrate(pool)` explicitly during boot instead.
+ */
+export declare function postgresSearch(options: PostgresSearchOptions): SearchProvider;

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * 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 { createRegconfigResolver } from './locale-regconfig.js';
+import { migrate } from './migrate.js';
+import { PostgresSearchProvider } from './postgres-search-provider.js';
+export { buildIndexRow, weightClass } from './build-index-row.js';
+export { createRegconfigResolver, DEFAULT_FALLBACK_REGCONFIG, } from './locale-regconfig.js';
+export { migrate } from './migrate.js';
+export { PostgresSearchProvider } from './postgres-search-provider.js';
+/**
+ * Construct the Postgres full-text search provider. Mirrors the established
+ * adapter-factory shape (`postgresSearch({ pool })`).
+ *
+ * Note: `autoMigrate` runs asynchronously and is not awaited here (the
+ * factory is synchronous to match the seam). For deterministic startup —
+ * especially the first deploy, before any read — call and await
+ * `migrate(pool)` explicitly during boot instead.
+ */
+export function postgresSearch(options) {
+    const regconfig = createRegconfigResolver(options.localeRegconfig, options.fallbackRegconfig);
+    if (options.autoMigrate === true) {
+        void migrate(options.pool, { log: options.log }).catch((error) => {
+            const message = `[search-postgres] autoMigrate failed: ${error.message}`;
+            if (options.log)
+                options.log(message);
+            else
+                console.error(message);
+        });
+    }
+    return new PostgresSearchProvider(options.pool, regconfig, options.defaultLocale);
+}

package/dist/locale-regconfig.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare const DEFAULT_FALLBACK_REGCONFIG = "simple";
+export type RegconfigResolver = (locale: string | undefined) => string;
+/**
+ * Build a locale → regconfig resolver. `overrides` are merged over the
+ * built-in map; `fallback` is used for any locale (or locale base) not found.
+ */
+export declare function createRegconfigResolver(overrides?: Record<string, string>, fallback?: string): RegconfigResolver;

package/dist/locale-regconfig.js

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+/**
+ * Maps a content locale to a Postgres text-search configuration
+ * (`regconfig`) — the language used by `to_tsvector` / `websearch_to_tsquery`
+ * for stemming and stop-words. The set here is the configs shipped with a
+ * stock Postgres install; anything unmapped falls back to `'simple'` (no
+ * stemming, no stop-words — correct, just unstemmed).
+ *
+ * A host can override or extend the map via the `localeRegconfig` factory
+ * option, e.g. to wire a custom dictionary or a language Postgres doesn't
+ * ship (Thai, etc.).
+ */
+const DEFAULT_REGCONFIG = {
+    ar: 'arabic',
+    da: 'danish',
+    de: 'german',
+    el: 'greek',
+    en: 'english',
+    es: 'spanish',
+    fi: 'finnish',
+    fr: 'french',
+    hu: 'hungarian',
+    id: 'indonesian',
+    it: 'italian',
+    lt: 'lithuanian',
+    ne: 'nepali',
+    nl: 'dutch',
+    no: 'norwegian',
+    pt: 'portuguese',
+    ro: 'romanian',
+    ru: 'russian',
+    sv: 'swedish',
+    ta: 'tamil',
+    tr: 'turkish',
+};
+export const DEFAULT_FALLBACK_REGCONFIG = 'simple';
+/**
+ * Build a locale → regconfig resolver. `overrides` are merged over the
+ * built-in map; `fallback` is used for any locale (or locale base) not found.
+ */
+export function createRegconfigResolver(overrides = {}, fallback = DEFAULT_FALLBACK_REGCONFIG) {
+    const map = { ...DEFAULT_REGCONFIG, ...overrides };
+    return (locale) => {
+        if (!locale)
+            return fallback;
+        if (map[locale] != null)
+            return map[locale];
+        const base = locale.split('-')[0]?.toLowerCase();
+        return (base != null ? map[base] : undefined) ?? fallback;
+    };
+}

package/dist/migrate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { Pool } from 'pg';
+export interface MigrateOptions {
+    /** Optional sink for progress lines (e.g. the host logger). */
+    log?: (message: string) => void;
+}
+export interface MigrateResult {
+    /** Versions applied during this run (empty when already up to date). */
+    applied: number[];
+}
+/**
+ * Apply any pending search-index migrations. Safe to call repeatedly (and at
+ * boot via `autoMigrate`) — already-applied versions are skipped.
+ */
+export declare function migrate(pool: Pool, options?: MigrateOptions): Promise<MigrateResult>;

package/dist/migrate.js

@@ -0,0 +1,71 @@
+/**
+ * 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
+ */
+/**
+ * Migration runner — the driver owns its schema. Applies the numbered SQL
+ * files in `../migrations` that haven't run yet, recording each in its own
+ * `byline_search_migrations` bookkeeping table (separate from the host's
+ * migration stream). Idempotent and transactional per file.
+ *
+ * The numbered `.sql` files are the source of truth: ops can apply them by
+ * hand (`psql -f migrations/0001_init.sql`) in locked-down environments, or
+ * call `migrate(pool)` / enable `autoMigrate` for convenience.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const MIGRATIONS_DIR = fileURLToPath(new URL('../migrations', import.meta.url));
+/**
+ * Apply any pending search-index migrations. Safe to call repeatedly (and at
+ * boot via `autoMigrate`) — already-applied versions are skipped.
+ */
+export async function migrate(pool, options = {}) {
+    const log = options.log ?? (() => { });
+    await pool.query(`
+    CREATE TABLE IF NOT EXISTS byline_search_migrations (
+      version    integer     PRIMARY KEY,
+      applied_at timestamptz NOT NULL DEFAULT now()
+    )
+  `);
+    const appliedRows = await pool.query('SELECT version FROM byline_search_migrations');
+    const done = new Set(appliedRows.rows.map((r) => Number(r.version)));
+    const pending = loadMigrations().filter((m) => !done.has(m.version));
+    const applied = [];
+    for (const migration of pending) {
+        const client = await pool.connect();
+        try {
+            await client.query('BEGIN');
+            await client.query(migration.sql);
+            await client.query('INSERT INTO byline_search_migrations (version) VALUES ($1)', [
+                migration.version,
+            ]);
+            await client.query('COMMIT');
+            applied.push(migration.version);
+            log(`[search-postgres] applied migration ${migration.name}`);
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw new Error(`[search-postgres] migration ${migration.name} failed: ${error.message}`, { cause: error });
+        }
+        finally {
+            client.release();
+        }
+    }
+    return { applied };
+}
+/** Read + parse the numbered `.sql` files, sorted by version ascending. */
+function loadMigrations() {
+    return readdirSync(MIGRATIONS_DIR)
+        .filter((f) => f.endsWith('.sql'))
+        .map((name) => {
+        const version = Number.parseInt(name.split('_')[0] ?? '', 10);
+        if (!Number.isInteger(version)) {
+            throw new Error(`[search-postgres] migration file '${name}' has no leading version number`);
+        }
+        return { version, name, sql: readFileSync(`${MIGRATIONS_DIR}/${name}`, 'utf8') };
+    })
+        .sort((a, b) => a.version - b.version);
+}

package/dist/postgres-search-provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { SearchCapabilities, SearchDocument, SearchProvider, SearchQuery, SearchResults } from '@byline/core';
+import type { Pool } from 'pg';
+import type { RegconfigResolver } from './locale-regconfig.js';
+/**
+ * The built-in Postgres full-text `SearchProvider`. Stores one weighted
+ * `tsvector` row per `(collection_path, document_id, locale)` and ranks with
+ * `websearch_to_tsquery` + `ts_rank`. Owns its schema (see `migrate`).
+ */
+export declare class PostgresSearchProvider implements SearchProvider {
+    private readonly pool;
+    private readonly regconfig;
+    /**
+     * Locale used to pick the query `regconfig` when a search omits `locale`.
+     * Without it, a locale-less query falls back to `simple` (unstemmed) and
+     * silently fails to match locale-stemmed vectors. Set to the host's
+     * default content locale.
+     */
+    private readonly defaultLocale?;
+    readonly capabilities: SearchCapabilities;
+    constructor(pool: Pool, regconfig: RegconfigResolver, 
+    /**
+     * Locale used to pick the query `regconfig` when a search omits `locale`.
+     * Without it, a locale-less query falls back to `simple` (unstemmed) and
+     * silently fails to match locale-stemmed vectors. Set to the host's
+     * default content locale.
+     */
+    defaultLocale?: string | undefined);
+    upsert(doc: SearchDocument): Promise<void>;
+    remove(ref: {
+        collectionPath: string;
+        documentId: string;
+        locale?: string;
+    }): Promise<void>;
+    reindex(opts?: {
+        collectionPath?: string;
+    }): Promise<void>;
+    search(query: SearchQuery): Promise<SearchResults>;
+}

package/dist/postgres-search-provider.js

@@ -0,0 +1,156 @@
+/**
+ * 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 { buildIndexRow } from './build-index-row.js';
+const CAPABILITIES = {
+    // tsvector + ts_rank floor: no IDF, no fuzzy, no vectors. Facet aggregation
+    // (the data is indexed) and structured `where` filtering are follow-ups.
+    facets: false,
+    typoTolerance: false,
+    semantic: false,
+    bm25: false,
+    weighting: true,
+    highlights: true,
+};
+/**
+ * The built-in Postgres full-text `SearchProvider`. Stores one weighted
+ * `tsvector` row per `(collection_path, document_id, locale)` and ranks with
+ * `websearch_to_tsquery` + `ts_rank`. Owns its schema (see `migrate`).
+ */
+export class PostgresSearchProvider {
+    pool;
+    regconfig;
+    defaultLocale;
+    capabilities = CAPABILITIES;
+    constructor(pool, regconfig, 
+    /**
+     * Locale used to pick the query `regconfig` when a search omits `locale`.
+     * Without it, a locale-less query falls back to `simple` (unstemmed) and
+     * silently fails to match locale-stemmed vectors. Set to the host's
+     * default content locale.
+     */
+    defaultLocale) {
+        this.pool = pool;
+        this.regconfig = regconfig;
+        this.defaultLocale = defaultLocale;
+    }
+    async upsert(doc) {
+        const row = buildIndexRow(doc);
+        const cfg = this.regconfig(row.locale);
+        await this.pool.query(`INSERT INTO byline_search_documents
+         (collection_path, document_id, locale, status, zones, title, path, body,
+          search_vector, facets, filters, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8,
+          setweight(to_tsvector($9::regconfig, $10), 'A') ||
+          setweight(to_tsvector($9::regconfig, $11), 'B') ||
+          setweight(to_tsvector($9::regconfig, $12), 'C') ||
+          setweight(to_tsvector($9::regconfig, $13), 'D'),
+          $14::jsonb, $15::jsonb, $16)
+       ON CONFLICT (collection_path, document_id, locale) DO UPDATE SET
+          status = EXCLUDED.status,
+          zones = EXCLUDED.zones,
+          title = EXCLUDED.title,
+          path = EXCLUDED.path,
+          body = EXCLUDED.body,
+          search_vector = EXCLUDED.search_vector,
+          facets = EXCLUDED.facets,
+          filters = EXCLUDED.filters,
+          updated_at = EXCLUDED.updated_at`, [
+            row.collectionPath,
+            row.documentId,
+            row.locale,
+            row.status,
+            row.zones,
+            row.title,
+            row.path,
+            row.body,
+            cfg,
+            row.weighted.A,
+            row.weighted.B,
+            row.weighted.C,
+            row.weighted.D,
+            JSON.stringify(row.facets),
+            JSON.stringify(row.filters),
+            row.updatedAt,
+        ]);
+    }
+    async remove(ref) {
+        if (ref.locale != null) {
+            await this.pool.query(`DELETE FROM byline_search_documents
+         WHERE collection_path = $1 AND document_id = $2 AND locale = $3`, [ref.collectionPath, ref.documentId, ref.locale]);
+        }
+        else {
+            await this.pool.query(`DELETE FROM byline_search_documents
+         WHERE collection_path = $1 AND document_id = $2`, [ref.collectionPath, ref.documentId]);
+        }
+    }
+    async reindex(opts = {}) {
+        // Clear the slice so a rebuild drops orphans (rows for deleted documents);
+        // the caller (client.reindex) then re-upserts the live published set.
+        if (opts.collectionPath != null) {
+            await this.pool.query('DELETE FROM byline_search_documents WHERE collection_path = $1', [
+                opts.collectionPath,
+            ]);
+        }
+        else {
+            await this.pool.query('TRUNCATE byline_search_documents');
+        }
+    }
+    async search(query) {
+        const cfg = this.regconfig(query.locale ?? this.defaultLocale);
+        const limit = query.limit ?? 20;
+        const offset = query.offset ?? 0;
+        // $1 = regconfig, $2 = query string; further binds appended below.
+        const params = [cfg, query.query];
+        const where = ['d.search_vector @@ q.query'];
+        if (query.collectionPath != null) {
+            params.push(query.collectionPath);
+            where.push(`d.collection_path = $${params.length}`);
+        }
+        if (query.zone != null) {
+            params.push([query.zone]);
+            where.push(`d.zones @> $${params.length}`);
+        }
+        if (query.locale != null) {
+            params.push(query.locale);
+            where.push(`d.locale = $${params.length}`);
+        }
+        // Default to published-only; 'any' is the admin escape hatch.
+        if (query.status !== 'any') {
+            params.push('published');
+            where.push(`d.status = $${params.length}`);
+        }
+        const whereSql = where.join(' AND ');
+        const cte = `WITH q AS (SELECT websearch_to_tsquery($1::regconfig, $2) AS query)`;
+        const countResult = await this.pool.query(`${cte}
+       SELECT count(*)::text AS total
+       FROM byline_search_documents d, q
+       WHERE ${whereSql}`, params);
+        const total = Number(countResult.rows[0]?.total ?? 0);
+        const limitParam = params.length + 1;
+        const offsetParam = params.length + 2;
+        const hitResult = await this.pool.query(`${cte}
+       SELECT d.collection_path, d.document_id, d.locale, d.title, d.path,
+              ts_rank(d.search_vector, q.query) AS score,
+              ts_headline($1::regconfig, d.body, q.query,
+                'StartSel=<mark>, StopSel=</mark>, MaxFragments=2, MaxWords=24, MinWords=8') AS highlight
+       FROM byline_search_documents d, q
+       WHERE ${whereSql}
+       ORDER BY score DESC, d.updated_at DESC
+       LIMIT $${limitParam} OFFSET $${offsetParam}`, [...params, limit, offset]);
+        const hits = hitResult.rows.map((r) => ({
+            collectionPath: r.collection_path,
+            documentId: r.document_id,
+            locale: r.locale,
+            title: r.title,
+            path: r.path,
+            score: Number(r.score),
+            highlights: r.highlight ? { body: [r.highlight] } : undefined,
+        }));
+        return { hits, total };
+    }
+}

package/migrations/0001_init.sql

@@ -0,0 +1,42 @@
+-- @byline/search-postgres — 0001_init
+--
+-- The full-text search index, owned entirely by this driver. One row per
+-- (collection_path, document_id, locale). The `search_vector` is a weighted
+-- tsvector assembled from the type-enriched SearchDocument at upsert time
+-- (title => A, body fields => A–D by boost, facet terms => C). Facet ids and
+-- filterable scalars are kept as jsonb for aggregation / filtering.
+--
+-- Idempotent (IF NOT EXISTS throughout) so re-applying is safe. The driver's
+-- migration runner records applied versions in byline_search_migrations.
+
+CREATE TABLE IF NOT EXISTS byline_search_documents (
+  collection_path text        NOT NULL,
+  document_id     text        NOT NULL,
+  locale          text        NOT NULL,
+  status          text        NOT NULL,
+  zones           text[]      NOT NULL DEFAULT '{}',
+  title           text        NOT NULL DEFAULT '',
+  path            text,
+  body            text        NOT NULL DEFAULT '',
+  search_vector   tsvector,
+  facets          jsonb       NOT NULL DEFAULT '{}'::jsonb,
+  filters         jsonb       NOT NULL DEFAULT '{}'::jsonb,
+  updated_at      timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (collection_path, document_id, locale)
+);
+
+-- Ranked full-text search.
+CREATE INDEX IF NOT EXISTS byline_search_documents_vector_idx
+  ON byline_search_documents USING gin (search_vector);
+
+-- Zone scoping (`zones @> ARRAY[$zone]`).
+CREATE INDEX IF NOT EXISTS byline_search_documents_zones_idx
+  ON byline_search_documents USING gin (zones);
+
+-- Facet aggregation / filtering over the jsonb projection.
+CREATE INDEX IF NOT EXISTS byline_search_documents_facets_idx
+  ON byline_search_documents USING gin (facets jsonb_path_ops);
+
+-- Single-collection scoping + status filtering.
+CREATE INDEX IF NOT EXISTS byline_search_documents_collection_idx
+  ON byline_search_documents (collection_path, status);