@byline/search-postgres 4.8.0 → 4.9.0

package/README.md

@@ -1,19 +1,21 @@
 # @byline/search-postgres
 
-The built-in Postgres full-text `SearchProvider` for Byline CMS. Implements the
-`SearchProvider` seam from `@byline/core` over a weighted `tsvector` index —
-ranked search with **zero new infrastructure**, reusing your existing Postgres
-connection.
+The built-in PostgreSQL full-text `SearchProvider` for Byline CMS. It combines
+the portable multilingual analyzer from `@byline/search-analysis` with a
+weighted, GIN-indexed `tsvector`, providing ranked search with **zero new
+infrastructure** and reusing the existing PostgreSQL connection.
 
 It consumes the type-enriched `SearchDocument` that core assembles
 (`buildSearchDocument`) and stores one weighted row per
-`(collection_path, document_id, locale)`: `title` → weight class `A`, `body`
-fields → `A`–`D` by their declared `boost`, facet **terms** → `C` (folded into
-the searchable vector), with facet **ids** and filterable scalars kept as
-`jsonb` for aggregation / filtering.
+`(collection_path, document_id, locale)`: body fields → `A`–`D` by their
+declared `boost`, facet **terms** → `C` (folded into the searchable vector),
+with facet **ids** and filterable scalars kept as `jsonb` for future
+aggregation and filtering. A collection's title remains display-only unless
+its identity field is also declared in `search.body`.
 
-See [`docs/05-reading-and-delivery/07-search.md`](../../docs/05-reading-and-delivery/07-search.md)
-for the full subsystem design.
+See
+[`docs/06-search/06-postgres-and-mysql.md`](../../docs/06-search/06-postgres-and-mysql.md)
+for the built-in provider comparison and operational reference.
 
 ## Install
 
@@ -54,6 +56,25 @@ migration stream — it ships its own numbered SQL files in
 `byline_search_migrations` table. There are three ways to apply them; pick per
 environment.
 
+### Portable-analysis cutover
+
+The portable-analysis release replaces the original native PostgreSQL search
+schema directly. There is no in-place compatibility migration: search data is
+a disposable projection of published documents. Before deploying this version
+over an older `@byline/search-postgres` installation, drop only the three
+driver-owned tables, reapply `0001_init.sql`, and rebuild each searchable
+collection:
+
+```sql
+DROP TABLE IF EXISTS byline_search_index_metadata;
+DROP TABLE IF EXISTS byline_search_documents;
+DROP TABLE IF EXISTS byline_search_migrations;
+```
+
+This does not remove CMS documents. After applying the new schema, run the
+normal `client.reindex()` workflow so the portable index is reconstructed from
+published versions.
+
 ### 1. Run the SQL by hand (locked-down / managed Postgres)
 
 The numbered files are the source of truth and are DBA-reviewable:
@@ -88,29 +109,36 @@ option 2 so startup is deterministic and DDL permissions are explicit.
 ```ts
 provider.capabilities
 // { facets: false, typoTolerance: false, semantic: false,
-//   bm25: false, weighting: true, highlights: true }
+//   bm25: false, weighting: true, highlights: true,
+//   fullText: {
+//     nativeAnalysis: false, portableAnalysis: true,
+//     allTerms: true, anyTerms: true,
+//     minimumShouldMatch: true, phrase: true
+//   } }
 ```
 
-The `tsvector` + `ts_rank` floor: per-field **weighting** and **highlighting**
-(`ts_headline`) are supported today. Facet *data* is indexed, but facet
-*aggregation* queries, structured `where` filtering, fuzzy matching (`pg_trgm`),
-BM25 ranking, and semantic/vector retrieval are follow-ups — surfaced honestly
-through the capability flags so consumers light up only what's available.
+The `tsvector` + `ts_rank` floor supports per-field **weighting** and all shared
+full-text matching policies. Ranked rows are highlighted from stored original
+body text through the shared portable token offsets, so snippets preserve the
+source spelling while matching normalized and expanded terms. Facet *data* is
+indexed, but facet *aggregation* queries, structured `where` filtering, fuzzy
+matching, BM25 ranking, and semantic/vector retrieval are follow-ups. The
+capability flags let consumers enable only supported behavior.
 
 ## Language / locale
 
-Search is per-locale. Each document's text is indexed with the Postgres
-`regconfig` mapped from its content locale (`en` → `english`, `fr` → `french`,
-…), falling back to `simple` (unstemmed) for unmapped locales. Pass `locale`
-to `search()` so the query uses the matching `regconfig` (a locale-less query
-falls back to `simple` and won't match locale-stemmed vectors) — or set
-`defaultLocale` so locale-less queries use your default content locale:
+Search is stored per locale. The portable analyzer applies Unicode
+normalization, ICU word segmentation, identifier preservation, optional
+language expanders, and Han bigrams before the adapter writes parser-safe
+physical terms to PostgreSQL. `defaultLocale` supplies the analyzer fallback
+when content or a query does not declare a usable locale:
 
 ```ts
-postgresSearch({
-  pool: db.pool,
-  defaultLocale: 'en',             // regconfig for searches that omit `locale`
-  localeRegconfig: { th: 'thai' }, // a custom dictionary you've installed
-  fallbackRegconfig: 'simple',
-})
+postgresSearch({ pool: db.pool, defaultLocale: 'en' })
 ```
+
+For language-specific stemming or lemmatization, construct a portable analyzer
+with versioned expanders and pass it as `analyzer`. The provider persists its
+fingerprint per collection. If that fingerprint changes, clear and rebuild the
+affected collection before it accepts new writes or searches; this prevents
+mixed token pipelines from producing incomplete results.

package/dist/build-index-row.d.ts

@@ -39,8 +39,9 @@ export interface IndexRow {
 export declare function weightClass(boost: number | undefined, defaultClass: WeightClass): WeightClass;
 /**
  * Transform a `SearchDocument` into the flat `IndexRow` the provider writes.
- * Pure — no SQL, no DB. The title always weights `A`; body text weights by
- * boost (default `B`); facet terms weight by boost (default `C`) and their
- * ids are projected into `facets`; filters are projected as-is.
+ * Pure — no SQL, no DB. `title` is display-only and never weighted (see the
+ * note below); body text weights by boost (default `B`); facet terms weight by
+ * boost (default `C`) and their ids are projected into `facets`; filters are
+ * projected as-is.
  */
 export declare function buildIndexRow(doc: SearchDocument): IndexRow;

package/dist/build-index-row.js

@@ -22,9 +22,10 @@ export function weightClass(boost, defaultClass) {
 }
 /**
  * Transform a `SearchDocument` into the flat `IndexRow` the provider writes.
- * Pure — no SQL, no DB. The title always weights `A`; body text weights by
- * boost (default `B`); facet terms weight by boost (default `C`) and their
- * ids are projected into `facets`; filters are projected as-is.
+ * Pure — no SQL, no DB. `title` is display-only and never weighted (see the
+ * note below); body text weights by boost (default `B`); facet terms weight by
+ * boost (default `C`) and their ids are projected into `facets`; filters are
+ * projected as-is.
  */
 export function buildIndexRow(doc) {
     const weighted = { A: [], B: [], C: [], D: [] };

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

@@ -7,7 +7,6 @@
  */
 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',
@@ -103,20 +102,3 @@ describe('buildIndexRow', () => {
         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/errors.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 class SearchAnalyzerMismatchError extends Error {
+    readonly collectionPath: string;
+    readonly expectedFingerprint: string;
+    readonly actualFingerprint: string | null;
+    readonly code = "SEARCH_INDEX_REINDEX_REQUIRED";
+    constructor(collectionPath: string, expectedFingerprint: string, actualFingerprint: string | null);
+}

package/dist/errors.js

@@ -0,0 +1,22 @@
+/**
+ * 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 class SearchAnalyzerMismatchError extends Error {
+    collectionPath;
+    expectedFingerprint;
+    actualFingerprint;
+    code = 'SEARCH_INDEX_REINDEX_REQUIRED';
+    constructor(collectionPath, expectedFingerprint, actualFingerprint) {
+        const actual = actualFingerprint ?? 'an unversioned analyzer';
+        super(`Search index for collection "${collectionPath}" uses "${actual}"; ` +
+            `expected analyzer "${expectedFingerprint}". Rebuild this collection's search index.`);
+        this.collectionPath = collectionPath;
+        this.expectedFingerprint = expectedFingerprint;
+        this.actualFingerprint = actualFingerprint;
+        this.name = 'SearchAnalyzerMismatchError';
+    }
+}

package/dist/index.d.ts

@@ -27,9 +27,10 @@
  * ```
  */
 import type { SearchProvider } from '@byline/core';
+import { type PortableSearchAnalyzer } from '@byline/search-analysis';
 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 { SearchAnalyzerMismatchError } from './errors.js';
 export { type MigrateOptions, type MigrateResult, migrate } from './migrate.js';
 export { PostgresSearchProvider } from './postgres-search-provider.js';
 export interface PostgresSearchOptions {
@@ -47,22 +48,18 @@ export interface PostgresSearchOptions {
      */
     autoMigrate?: boolean;
     /**
-     * Override or extend the locale → Postgres `regconfig` (text-search
-     * language) map. Merged over the built-in defaults.
+     * Locale used when neither indexed content nor a query supplies one.
+     * Defaults to `en`.
      */
-    localeRegconfig?: Record<string, string>;
-    /**
-     * Fallback `regconfig` for locales not in the map. Defaults to `'simple'`
-     * (no stemming / stop-words — unstemmed but correct).
-     */
-    fallbackRegconfig?: string;
+    defaultLocale?: 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).
+     * Custom portable analyzer, typically carrying versioned language
+     * expanders. Defaults to `createPortableSearchAnalyzer({ defaultLocale })`.
+     *
+     * Changing the analyzer fingerprint requires rebuilding the affected
+     * collections before they can be searched or indexed.
      */
-    defaultLocale?: string;
+    analyzer?: PortableSearchAnalyzer;
     /** Optional sink for migration progress lines (e.g. the host logger). */
     log?: (message: string) => void;
 }

package/dist/index.js

@@ -5,11 +5,11 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { createRegconfigResolver } from './locale-regconfig.js';
+import { createPortableSearchAnalyzer } from '@byline/search-analysis';
 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 { SearchAnalyzerMismatchError } from './errors.js';
 export { migrate } from './migrate.js';
 export { PostgresSearchProvider } from './postgres-search-provider.js';
 /**
@@ -22,7 +22,7 @@ export { PostgresSearchProvider } from './postgres-search-provider.js';
  * `migrate(pool)` explicitly during boot instead.
  */
 export function postgresSearch(options) {
-    const regconfig = createRegconfigResolver(options.localeRegconfig, options.fallbackRegconfig);
+    const analyzer = options.analyzer ?? createPortableSearchAnalyzer({ defaultLocale: options.defaultLocale });
     if (options.autoMigrate === true) {
         void migrate(options.pool, { log: options.log }).catch((error) => {
             const message = `[search-postgres] autoMigrate failed: ${error.message}`;
@@ -32,5 +32,5 @@ export function postgresSearch(options) {
                 console.error(message);
         });
     }
-    return new PostgresSearchProvider(options.pool, regconfig, options.defaultLocale);
+    return new PostgresSearchProvider(options.pool, analyzer);
 }

package/dist/migrations-data.js

@@ -11,11 +11,11 @@ export const MIGRATIONS = [
         name: '0001_init.sql',
         sql: `-- @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.
+-- The disposable full-text search index, owned entirely by this driver. One
+-- row per (collection_path, document_id, locale). \`search_vector\` stores
+-- parser-safe physical tokens produced by @byline/search-analysis and
+-- \`analyzer_fingerprint\` identifies the exact portable analysis pipeline.
+-- Search indexes created with an older schema must be dropped and rebuilt.
 --
 -- Idempotent (IF NOT EXISTS throughout) so re-applying is safe. The driver's
 -- migration runner records applied versions in byline_search_migrations.
@@ -29,7 +29,8 @@ CREATE TABLE IF NOT EXISTS byline_search_documents (
   title           text        NOT NULL DEFAULT '',
   path            text,
   body            text        NOT NULL DEFAULT '',
-  search_vector   tsvector,
+  search_vector   tsvector    NOT NULL,
+  analyzer_fingerprint text   NOT NULL,
   facets          jsonb       NOT NULL DEFAULT '{}'::jsonb,
   filters         jsonb       NOT NULL DEFAULT '{}'::jsonb,
   updated_at      timestamptz NOT NULL DEFAULT now(),
@@ -51,6 +52,16 @@ CREATE INDEX IF NOT EXISTS byline_search_documents_facets_idx
 -- Single-collection scoping + status filtering.
 CREATE INDEX IF NOT EXISTS byline_search_documents_collection_idx
   ON byline_search_documents (collection_path, status);
+
+-- One locked row per collection prevents concurrent processes with different
+-- analyzer fingerprints from mixing incompatible projections. Collection
+-- zones let fingerprint guards retain zone scope without scanning documents.
+CREATE TABLE IF NOT EXISTS byline_search_index_metadata (
+  collection_path      text        PRIMARY KEY,
+  analyzer_fingerprint text        NOT NULL,
+  zones                text[]      NOT NULL DEFAULT '{}',
+  updated_at           timestamptz NOT NULL DEFAULT now()
+);
 `,
     },
 ];

package/dist/portable-index-vector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 PortableSearchAnalyzer } from '@byline/search-analysis';
+import type { IndexRow } from './build-index-row.js';
+export interface PortableIndexVector {
+    /** PostgreSQL text representation accepted by `$n::tsvector`. */
+    value: string;
+    analyzerFingerprint: string;
+}
+/**
+ * Build a weighted tsvector literal from portable logical terms. Expansions
+ * share their source position, derived variants lose one weight class, and
+ * Han grams always use the lowest class.
+ */
+export declare function buildPortableIndexVector(row: Pick<IndexRow, 'locale' | 'weighted'>, analyzer: PortableSearchAnalyzer): PortableIndexVector;

package/dist/portable-index-vector.js

@@ -0,0 +1,108 @@
+/**
+ * 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 { encodeSqlToken, } from '@byline/search-analysis';
+const WEIGHT_CLASSES = ['A', 'B', 'C', 'D'];
+const MAX_TSVECTOR_POSITION = 16_383;
+/**
+ * Build a weighted tsvector literal from portable logical terms. Expansions
+ * share their source position, derived variants lose one weight class, and
+ * Han grams always use the lowest class.
+ */
+export function buildPortableIndexVector(row, analyzer) {
+    const lexemes = new Map();
+    let positionBase = 0;
+    for (const weight of WEIGHT_CLASSES) {
+        const analyzed = analyzer.analyzeText({ text: row.weighted[weight], locale: row.locale });
+        const sourcePositionCount = Math.max(-1, ...analyzed.exactTokens.map(positionOf), ...analyzed.identifierTokens.map(positionOf)) + 1;
+        const gramPositions = positionGrams(analyzed.gramTokens, positionBase + sourcePositionCount + 1);
+        for (const token of analyzed.tokens) {
+            const physical = encodeSqlToken(token);
+            const position = gramPositions.get(token) ?? positionBase + token.position + 1;
+            const effectiveWeight = tokenWeight(token, weight);
+            addLexeme(lexemes, physical, position, effectiveWeight);
+        }
+        // Keep a one-position boundary between weight buckets so phrases cannot
+        // bridge independently configured fields solely because they were joined.
+        positionBase = Math.max(positionBase + sourcePositionCount, ...gramPositions.values()) + 1;
+    }
+    return {
+        value: renderTsvector(lexemes),
+        analyzerFingerprint: analyzer.fingerprint,
+    };
+}
+function positionOf(token) {
+    return token.position;
+}
+function positionGrams(grams, firstPosition) {
+    const positioned = new Map();
+    const ordered = grams.toSorted((left, right) => left.normalizedStart - right.normalizedStart || left.normalizedEnd - right.normalizedEnd);
+    let position = firstPosition;
+    let previous;
+    for (const gram of ordered) {
+        // Overlapping bigrams in one Han run occupy consecutive positions.
+        // Leave a gap between distinct runs so a phrase cannot bridge intervening
+        // non-Han content.
+        if (previous != null && gram.normalizedStart >= previous.normalizedEnd)
+            position += 1;
+        positioned.set(gram, position);
+        position += 1;
+        previous = gram;
+    }
+    return positioned;
+}
+function tokenWeight(token, sourceWeight) {
+    if (token.kind === 'gram')
+        return 'D';
+    if (token.kind === 'exact' || token.kind === 'identifier')
+        return sourceWeight;
+    return lowerWeight(sourceWeight);
+}
+function lowerWeight(weight) {
+    switch (weight) {
+        case 'A':
+            return 'B';
+        case 'B':
+            return 'C';
+        case 'C':
+        case 'D':
+            return 'D';
+    }
+}
+function addLexeme(lexemes, lexeme, position, weight) {
+    let entry = lexemes.get(lexeme);
+    if (entry == null) {
+        entry = { positions: new Map(), beyondPositionLimit: false };
+        lexemes.set(lexeme, entry);
+    }
+    if (position > MAX_TSVECTOR_POSITION) {
+        entry.beyondPositionLimit = true;
+        return;
+    }
+    const current = entry.positions.get(position);
+    if (current == null || weightRank(weight) > weightRank(current)) {
+        entry.positions.set(position, weight);
+    }
+}
+function weightRank(weight) {
+    return WEIGHT_CLASSES.length - WEIGHT_CLASSES.indexOf(weight);
+}
+function renderTsvector(lexemes) {
+    return [...lexemes.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([lexeme, entry]) => {
+        const positions = [...entry.positions.entries()]
+            .sort(([left], [right]) => left - right)
+            .map(([position, weight]) => `${position}${weight}`);
+        // A bare lexeme still participates in matching when all of its
+        // occurrences exceed PostgreSQL's positional ceiling.
+        if (positions.length === 0 && entry.beyondPositionLimit)
+            return `'${lexeme}'`;
+        return positions.length > 0 ? `'${lexeme}':${positions.join(',')}` : `'${lexeme}'`;
+    })
+        .join(' ');
+}

package/dist/portable-index-vector.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/portable-index-vector.test.node.js

@@ -0,0 +1,61 @@
+/**
+ * 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 { createPortableSearchAnalyzer, encodeSqlToken, } from '@byline/search-analysis';
+import { describe, expect, it } from 'vitest';
+import { buildPortableIndexVector } from './portable-index-vector.js';
+const englishExpander = {
+    fingerprint: 'english-test1',
+    supports: (locale) => locale.startsWith('en'),
+    expand: (token) => (token.value === 'running' ? [{ kind: 'stem', value: 'run' }] : []),
+};
+function row(overrides = {}) {
+    return {
+        collectionPath: 'publications',
+        documentId: 'doc-1',
+        locale: 'en',
+        status: 'published',
+        zones: ['site'],
+        title: 'Running database',
+        path: 'running-database',
+        body: 'Running 数据库',
+        weighted: { A: 'Running 数据库', B: '', C: '', D: '' },
+        facets: {},
+        filters: {},
+        updatedAt: '2026-07-26T00:00:00.000Z',
+        ...overrides,
+    };
+}
+describe('buildPortableIndexVector', () => {
+    it('keeps exact and derived terms at one position with lower derived weight', () => {
+        const analyzer = createPortableSearchAnalyzer({ expanders: [englishExpander] });
+        const vector = buildPortableIndexVector(row(), analyzer);
+        const exact = encodeSqlToken({ kind: 'exact', value: 'running' });
+        const stem = encodeSqlToken({ kind: 'stem', value: 'run' });
+        expect(vector.value).toContain(`'${exact}':1A`);
+        expect(vector.value).toContain(`'${stem}':1B`);
+        expect(vector.analyzerFingerprint).toBe(analyzer.fingerprint);
+    });
+    it('always assigns Han grams to weight D', () => {
+        const analyzer = createPortableSearchAnalyzer();
+        const vector = buildPortableIndexVector(row(), analyzer);
+        expect(vector.value).toContain(`'${encodeSqlToken({ kind: 'gram', value: '数据' })}':4D`);
+        expect(vector.value).toContain(`'${encodeSqlToken({ kind: 'gram', value: '据库' })}':5D`);
+    });
+    it('separates weight buckets positionally', () => {
+        const analyzer = createPortableSearchAnalyzer();
+        const input = row({
+            body: 'alpha\nbeta',
+            weighted: { A: 'alpha', B: 'beta', C: '', D: '' },
+        });
+        const vector = buildPortableIndexVector(input, analyzer);
+        const alpha = encodeSqlToken({ kind: 'exact', value: 'alpha' });
+        const beta = encodeSqlToken({ kind: 'exact', value: 'beta' });
+        expect(vector.value).toContain(`'${alpha}':1A`);
+        expect(vector.value).toContain(`'${beta}':3B`);
+    });
+});

package/dist/portable-query.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 PortableQueryPlan } from '@byline/search-analysis';
+export interface PortablePostgresQuery {
+    /** Complete matching/ranking tsquery source for `to_tsquery('simple', …)`. */
+    tsquery: string;
+    /** One query per source concept, used to enforce minimum-should-match. */
+    conceptTsqueries: string[];
+    minimumShouldMatch?: number;
+}
+/** Translate a backend-neutral plan into parser-safe PostgreSQL tsquery text. */
+export declare function buildPortablePostgresQuery(plan: PortableQueryPlan): PortablePostgresQuery;

package/dist/portable-query.js

@@ -0,0 +1,110 @@
+/**
+ * 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 { encodeSqlToken, } from '@byline/search-analysis';
+/** Translate a backend-neutral plan into parser-safe PostgreSQL tsquery text. */
+export function buildPortablePostgresQuery(plan) {
+    const conceptTsqueries = plan.concepts.map(conceptExpression);
+    if (conceptTsqueries.some((expression) => expression.length === 0)) {
+        throw new TypeError('Portable query plan contains a concept with no searchable terms');
+    }
+    if (conceptTsqueries.length === 0) {
+        return { tsquery: '', conceptTsqueries: [] };
+    }
+    const operator = plan.matching.operator === 'all' ? '&' : '|';
+    const groupedConcepts = groupCrossConceptGrams(plan, conceptTsqueries, operator);
+    const clauses = [joinExpressions(groupedConcepts, operator)];
+    for (const phrase of plan.phrases) {
+        const expressions = phrase.conceptIndexes.map((index) => conceptTsqueries[index] ?? '');
+        if (expressions.some((expression) => expression.length === 0)) {
+            throw new RangeError('Portable query phrase references an unknown concept');
+        }
+        clauses.push(joinExpressions(expressions, '<->'));
+    }
+    return {
+        tsquery: joinExpressions(clauses, '&'),
+        conceptTsqueries,
+        ...(plan.matching.minimumShouldMatch != null
+            ? { minimumShouldMatch: plan.matching.minimumShouldMatch }
+            : {}),
+    };
+}
+function conceptExpression(concept) {
+    const alternatives = uniqueTerms([
+        ...concept.exactTokens,
+        ...concept.stemTokens,
+        ...concept.lemmaTokens,
+        ...concept.normalizedTokens,
+        ...concept.identifierTokens,
+    ]);
+    const grams = orderedTerms(concept.gramTokens);
+    if (grams.length > 0)
+        alternatives.push(joinExpressions(grams, '<->'));
+    return joinExpressions(alternatives, '|');
+}
+function groupCrossConceptGrams(plan, concepts, operator) {
+    const replacements = new Map();
+    for (const sequence of plan.gramSequences) {
+        if (sequence.length === 0)
+            continue;
+        const start = Math.min(...sequence.map((token) => token.normalizedStart));
+        const end = Math.max(...sequence.map((token) => token.normalizedEnd));
+        const indexes = plan.concepts
+            .filter((concept) => conceptOverlaps(concept, start, end))
+            .map((concept) => concept.index);
+        if (indexes.length < 2)
+            continue;
+        const first = indexes[0];
+        const last = indexes.at(-1);
+        if (first == null || last == null || last - first + 1 !== indexes.length)
+            continue;
+        const original = joinExpressions(indexes.map((index) => concepts[index] ?? ''), operator);
+        const gramPhrase = joinExpressions(orderedTerms(sequence), '<->');
+        if (original.length === 0 || gramPhrase.length === 0)
+            continue;
+        replacements.set(first, {
+            expression: joinExpressions([original, gramPhrase], '|'),
+            through: last,
+        });
+    }
+    const grouped = [];
+    for (let index = 0; index < concepts.length; index++) {
+        const replacement = replacements.get(index);
+        if (replacement != null) {
+            grouped.push(replacement.expression);
+            index = replacement.through;
+            continue;
+        }
+        if ([...replacements.entries()].some(([start, entry]) => index > start && index <= entry.through)) {
+            continue;
+        }
+        const concept = concepts[index];
+        if (concept != null)
+            grouped.push(concept);
+    }
+    return grouped;
+}
+function conceptOverlaps(concept, start, end) {
+    const source = [...concept.exactTokens, ...concept.identifierTokens];
+    return source.some((token) => token.normalizedStart < end && token.normalizedEnd > start);
+}
+function uniqueTerms(tokens) {
+    return [...new Set(tokens.map((token) => encodeSqlToken(token)))];
+}
+function orderedTerms(tokens) {
+    return tokens
+        .toSorted((left, right) => left.normalizedStart - right.normalizedStart || left.normalizedEnd - right.normalizedEnd)
+        .map((token) => encodeSqlToken(token));
+}
+function joinExpressions(expressions, operator) {
+    const nonEmpty = expressions.filter((expression) => expression.length > 0);
+    if (nonEmpty.length === 0)
+        return '';
+    if (nonEmpty.length === 1)
+        return nonEmpty[0] ?? '';
+    return `(${nonEmpty.map((expression) => `(${expression})`).join(` ${operator} `)})`;
+}

package/dist/portable-query.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/portable-query.test.node.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { createPortableSearchAnalyzer, encodeSqlToken, } from '@byline/search-analysis';
+import { describe, expect, it } from 'vitest';
+import { buildPortablePostgresQuery } from './portable-query.js';
+const expander = {
+    fingerprint: 'english-test1',
+    supports: (locale) => locale.startsWith('en'),
+    expand: (token) => (token.value === 'running' ? [{ kind: 'stem', value: 'run' }] : []),
+};
+describe('buildPortablePostgresQuery', () => {
+    it('keeps recall variants grouped inside all-concept matching', () => {
+        const analyzer = createPortableSearchAnalyzer({ expanders: [expander] });
+        const translated = buildPortablePostgresQuery(analyzer.analyzeQuery({ query: 'running restoration', locale: 'en' }));
+        const exact = encodeSqlToken({ kind: 'exact', value: 'running' });
+        const stem = encodeSqlToken({ kind: 'stem', value: 'run' });
+        const restoration = encodeSqlToken({ kind: 'exact', value: 'restoration' });
+        expect(translated.conceptTsqueries).toHaveLength(2);
+        expect(translated.conceptTsqueries[0]).toContain(exact);
+        expect(translated.conceptTsqueries[0]).toContain(stem);
+        expect(translated.tsquery).toContain(' | ');
+        expect(translated.tsquery).toContain(' & ');
+        expect(translated.tsquery).toContain(restoration);
+    });
+    it('preserves phrase order and minimum-should-match inputs', () => {
+        const analyzer = createPortableSearchAnalyzer();
+        const translated = buildPortablePostgresQuery(analyzer.analyzeQuery({
+            query: '"forest restoration" database',
+            locale: 'en',
+            matching: { operator: 'any', minimumShouldMatch: 2 },
+        }));
+        expect(translated.conceptTsqueries).toHaveLength(3);
+        expect(translated.minimumShouldMatch).toBe(2);
+        expect(translated.tsquery).toContain(' | ');
+        expect(translated.tsquery).toContain(' <-> ');
+        expect(translated.tsquery).toMatch(/^[a-z0-9()|&<>\-\s]+$/);
+    });
+    it('returns an empty translation for punctuation-only input', () => {
+        const analyzer = createPortableSearchAnalyzer();
+        const translated = buildPortablePostgresQuery(analyzer.analyzeQuery({ query: '---' }));
+        expect(translated).toEqual({ tsquery: '', conceptTsqueries: [] });
+    });
+});

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

@@ -6,32 +6,17 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { SearchCapabilities, SearchDocument, SearchProvider, SearchQuery, SearchResults } from '@byline/core';
+import { type PortableSearchAnalyzer } from '@byline/search-analysis';
 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`).
+ * The built-in PostgreSQL `SearchProvider`. Stores portable logical terms in
+ * one weighted tsvector per `(collection_path, document_id, locale)`.
  */
 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?;
+    private readonly analyzer;
     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);
+    constructor(pool: Pool, analyzer: PortableSearchAnalyzer);
     upsert(doc: SearchDocument): Promise<void>;
     remove(ref: {
         collectionPath: string;
@@ -42,4 +27,5 @@ export declare class PostgresSearchProvider implements SearchProvider {
         collectionPath?: string;
     }): Promise<void>;
     search(query: SearchQuery): Promise<SearchResults>;
+    private assertAnalyzerFingerprint;
 }

package/dist/postgres-search-provider.js

@@ -5,78 +5,72 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { highlightPortableText } from '@byline/search-analysis';
 import { buildIndexRow } from './build-index-row.js';
+import { SearchAnalyzerMismatchError } from './errors.js';
+import { buildPortableIndexVector } from './portable-index-vector.js';
+import { buildPortablePostgresQuery } from './portable-query.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.
+    // Portable tsvector + ts_rank floor: no IDF, fuzzy matching, vectors,
+    // aggregation, or structured `where` filtering yet.
     facets: false,
     typoTolerance: false,
     semantic: false,
     bm25: false,
     weighting: true,
     highlights: true,
+    fullText: {
+        nativeAnalysis: false,
+        portableAnalysis: true,
+        allTerms: true,
+        anyTerms: true,
+        minimumShouldMatch: true,
+        phrase: 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`).
+ * The built-in PostgreSQL `SearchProvider`. Stores portable logical terms in
+ * one weighted tsvector per `(collection_path, document_id, locale)`.
  */
 export class PostgresSearchProvider {
     pool;
-    regconfig;
-    defaultLocale;
+    analyzer;
     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) {
+    constructor(pool, analyzer) {
         this.pool = pool;
-        this.regconfig = regconfig;
-        this.defaultLocale = defaultLocale;
+        this.analyzer = analyzer;
     }
     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,
-        ]);
+        const vector = buildPortableIndexVector(row, this.analyzer);
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            await client.query(`INSERT INTO byline_search_index_metadata
+           (collection_path, analyzer_fingerprint, zones, updated_at)
+         VALUES ($1, $2, $3, now())
+         ON CONFLICT (collection_path) DO UPDATE
+           SET zones = ARRAY(
+             SELECT DISTINCT unnest(byline_search_index_metadata.zones || EXCLUDED.zones)
+           )`, [row.collectionPath, vector.analyzerFingerprint, row.zones]);
+            const metadata = await client.query(`SELECT analyzer_fingerprint
+         FROM byline_search_index_metadata
+         WHERE collection_path = $1
+         FOR UPDATE`, [row.collectionPath]);
+            const actualFingerprint = metadata.rows[0]?.analyzer_fingerprint ?? null;
+            if (actualFingerprint !== vector.analyzerFingerprint) {
+                throw new SearchAnalyzerMismatchError(row.collectionPath, vector.analyzerFingerprint, actualFingerprint);
+            }
+            await client.query(UPSERT_SQL, upsertParams(row, vector.value, vector.analyzerFingerprint));
+            await client.query('COMMIT');
+        }
+        catch (error) {
+            await rollback(client);
+            throw error;
+        }
+        finally {
+            client.release();
+        }
     }
     async remove(ref) {
         if (ref.locale != null) {
@@ -89,68 +83,171 @@ export class PostgresSearchProvider {
         }
     }
     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,
-            ]);
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            if (opts.collectionPath != null) {
+                await client.query('DELETE FROM byline_search_index_metadata WHERE collection_path = $1', [
+                    opts.collectionPath,
+                ]);
+                await client.query('DELETE FROM byline_search_documents WHERE collection_path = $1', [
+                    opts.collectionPath,
+                ]);
+            }
+            else {
+                await client.query('TRUNCATE byline_search_documents');
+                await client.query('TRUNCATE byline_search_index_metadata');
+            }
+            await client.query('COMMIT');
         }
-        else {
-            await this.pool.query('TRUNCATE byline_search_documents');
+        catch (error) {
+            await rollback(client);
+            throw error;
+        }
+        finally {
+            client.release();
         }
     }
     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 plan = this.analyzer.analyzeQuery({
+            query: query.query,
+            locale: query.locale,
+            matching: query.matching,
+        });
+        const translated = buildPortablePostgresQuery(plan);
+        if (translated.tsquery.length === 0)
+            return { hits: [], total: 0 };
+        await this.assertAnalyzerFingerprint(query);
+        const params = [translated.tsquery];
         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}`);
+        if (translated.minimumShouldMatch != null) {
+            params.push(translated.conceptTsqueries);
+            const conceptsParam = params.length;
+            params.push(translated.minimumShouldMatch);
+            const minimumParam = params.length;
+            where.push(`(SELECT count(*)
+          FROM unnest($${conceptsParam}::text[]) AS concept(query_text)
+          WHERE d.search_vector @@ to_tsquery('simple', concept.query_text))
+         >= $${minimumParam}`);
         }
+        appendScopeFilters(query, params, where, true);
+        const cte = `WITH q AS (SELECT to_tsquery('simple', $1) AS query)`;
         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 limit = query.limit ?? 20;
+        const offset = query.offset ?? 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
+       SELECT d.collection_path, d.document_id, d.locale, d.title, d.path, d.body,
+              ts_rank(d.search_vector, q.query) AS score
        FROM byline_search_documents d, q
        WHERE ${whereSql}
-       ORDER BY score DESC, d.updated_at DESC
+       ORDER BY score DESC, d.updated_at DESC,
+                d.collection_path, d.document_id, d.locale
        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,
-        }));
+        const hits = hitResult.rows.map((row) => {
+            const highlight = highlightPortableText({
+                text: row.body,
+                plan,
+                analyzer: this.analyzer,
+            });
+            return {
+                collectionPath: row.collection_path,
+                documentId: row.document_id,
+                locale: row.locale,
+                title: row.title,
+                path: row.path,
+                score: Number(row.score),
+                ...(highlight == null ? {} : { highlights: { body: [highlight] } }),
+            };
+        });
         return { hits, total };
     }
+    async assertAnalyzerFingerprint(query) {
+        const params = [this.analyzer.fingerprint];
+        const where = ['m.analyzer_fingerprint IS DISTINCT FROM $1'];
+        appendMetadataScopeFilters(query, params, where);
+        const incompatible = await this.pool.query(`SELECT m.collection_path, m.analyzer_fingerprint
+       FROM byline_search_index_metadata m
+       WHERE ${where.join(' AND ')}
+       LIMIT 1`, params);
+        const row = incompatible.rows[0];
+        if (row != null) {
+            throw new SearchAnalyzerMismatchError(row.collection_path, this.analyzer.fingerprint, row.analyzer_fingerprint);
+        }
+    }
+}
+function appendMetadataScopeFilters(query, params, where) {
+    if (query.collectionPath != null) {
+        params.push(query.collectionPath);
+        where.push(`m.collection_path = $${params.length}`);
+    }
+    if (query.zone != null) {
+        params.push([query.zone]);
+        where.push(`m.zones @> $${params.length}`);
+    }
+}
+function appendScopeFilters(query, params, where, includeStatus) {
+    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}`);
+    }
+    if (includeStatus && query.status !== 'any') {
+        params.push('published');
+        where.push(`d.status = $${params.length}`);
+    }
+}
+function upsertParams(row, vector, analyzerFingerprint) {
+    return [
+        row.collectionPath,
+        row.documentId,
+        row.locale,
+        row.status,
+        row.zones,
+        row.title,
+        row.path,
+        row.body,
+        vector,
+        analyzerFingerprint,
+        JSON.stringify(row.facets),
+        JSON.stringify(row.filters),
+        row.updatedAt,
+    ];
+}
+async function rollback(client) {
+    try {
+        await client.query('ROLLBACK');
+    }
+    catch {
+        // Preserve the original operation error.
+    }
 }
+const UPSERT_SQL = `INSERT INTO byline_search_documents
+  (collection_path, document_id, locale, status, zones, title, path, body,
+   search_vector, analyzer_fingerprint, facets, filters, updated_at)
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::tsvector, $10,
+   $11::jsonb, $12::jsonb, $13)
+ 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,
+   analyzer_fingerprint = EXCLUDED.analyzer_fingerprint,
+   facets = EXCLUDED.facets,
+   filters = EXCLUDED.filters,
+   updated_at = EXCLUDED.updated_at`;

package/migrations/0001_init.sql

@@ -1,10 +1,10 @@
 -- @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.
+-- The disposable full-text search index, owned entirely by this driver. One
+-- row per (collection_path, document_id, locale). `search_vector` stores
+-- parser-safe physical tokens produced by @byline/search-analysis and
+-- `analyzer_fingerprint` identifies the exact portable analysis pipeline.
+-- Search indexes created with an older schema must be dropped and rebuilt.
 --
 -- Idempotent (IF NOT EXISTS throughout) so re-applying is safe. The driver's
 -- migration runner records applied versions in byline_search_migrations.
@@ -18,7 +18,8 @@ CREATE TABLE IF NOT EXISTS byline_search_documents (
   title           text        NOT NULL DEFAULT '',
   path            text,
   body            text        NOT NULL DEFAULT '',
-  search_vector   tsvector,
+  search_vector   tsvector    NOT NULL,
+  analyzer_fingerprint text   NOT NULL,
   facets          jsonb       NOT NULL DEFAULT '{}'::jsonb,
   filters         jsonb       NOT NULL DEFAULT '{}'::jsonb,
   updated_at      timestamptz NOT NULL DEFAULT now(),
@@ -40,3 +41,13 @@ CREATE INDEX IF NOT EXISTS byline_search_documents_facets_idx
 -- Single-collection scoping + status filtering.
 CREATE INDEX IF NOT EXISTS byline_search_documents_collection_idx
   ON byline_search_documents (collection_path, status);
+
+-- One locked row per collection prevents concurrent processes with different
+-- analyzer fingerprints from mixing incompatible projections. Collection
+-- zones let fingerprint guards retain zone scope without scanning documents.
+CREATE TABLE IF NOT EXISTS byline_search_index_metadata (
+  collection_path      text        PRIMARY KEY,
+  analyzer_fingerprint text        NOT NULL,
+  zones                text[]      NOT NULL DEFAULT '{}',
+  updated_at           timestamptz NOT NULL DEFAULT now()
+);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/search-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -41,7 +41,8 @@
     "migrations"
   ],
   "dependencies": {
-    "@byline/core": "4.8.0"
+    "@byline/core": "4.9.0",
+    "@byline/search-analysis": "4.9.0"
   },
   "peerDependencies": {
     "pg": "^8.21.0"
@@ -52,12 +53,14 @@
     "@types/pg": "^8.20.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
+    "dotenv": "^17.4.2",
     "npm-run-all": "^4.1.5",
     "pg": "^8.22.0",
     "tsc-alias": "^1.9.1",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "@byline/search-conformance": "0.0.2"
   },
   "publishConfig": {
     "access": "public"
@@ -68,6 +71,7 @@
     "clean": "node scripts/clean.js node_modules dist build .turbo",
     "lint": "biome check --write --unsafe --diagnostic-level=error",
     "test": "vitest run --mode=node",
+    "test:integration": "vitest run --mode=integration",
     "test:watch": "vitest --mode=node",
     "typecheck": "tsc --noEmit"
   }