@syncular/typegen 0.14.0 → 0.15.1

package/README.md

@@ -185,6 +185,7 @@ duplicate ordinals are errors). The parser accepts exactly:
 - `ALTER TABLE name ADD [COLUMN] column-def`
 - `CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table ( col [, col…] )`
 - `DROP TABLE [IF EXISTS] name`
+- `CREATE VIRTUAL TABLE [IF NOT EXISTS] name USING fts5( text-col [, text-col…], content = table [, tokenize = 'allowlisted tokenizer'] )`
 - column-def: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL] [DEFAULT literal]`
 - `--` line comments and `/* … */` block comments
 
@@ -226,6 +227,22 @@ reference relational server drops the retired current-row table and its live
 scope index. Append-only commit history follows the configured retention
 policy—`DROP TABLE` is schema retirement, not a compliance erasure API.
 
+**Local FTS5 projections** (`CREATE VIRTUAL TABLE … USING fts5`). The authored
+`content = table` option declares which already-created synced table owns the
+projection; it is not passed through as SQLite external-content mode. Typegen
+attaches `{ name, columns, tokenize }` to that table's `ftsIndexes` array and
+emits it in TypeScript, Swift, Kotlin, and Dart schema values. The TypeScript
+and Rust clients create a contentful FTS table with a private stable source-ID
+column and deterministic maintenance triggers. FTS is local-only: it is not a
+wire/server table, cannot be subscribed or mutated, and maps back to its owner
+for named-query invalidation. Columns must precede options, be distinct
+non-encrypted strings, and number 1–32. `content` is required. Supported
+tokenizers are `unicode61` (default), its `remove_diacritics 0|1|2` variants,
+`porter unicode61`, and `trigram`. Other modules/options/tokenizers, encrypted
+columns, or schema-object name collisions fail generation. There is no
+automatic `LIKE` fallback when FTS5 is unavailable; local schema creation
+fails loudly.
+
 **Hard errors** (each names the construct and source file): any other
 statement (`CREATE TRIGGER/VIEW`, `DROP INDEX`, DML, `ALTER … RENAME`, …); unknown
 or parameterized types (`VARCHAR(36)`); quoted identifiers
@@ -234,7 +251,9 @@ or parameterized types (`VARCHAR(36)`); quoted identifiers
 (`REFERENCES`, `CHECK`, `COLLATE`, …); `DEFAULT (expression)`; composite
 or missing primary keys; `PRIMARY KEY` on `ADD COLUMN`; duplicate
 tables/columns; ASC/DESC, expression, or partial (`WHERE`) index columns; a
-duplicate or unknown-column index; trailing clauses (`STRICT`).
+duplicate or unknown-column index; unsupported virtual-table modules or FTS5
+options; an FTS projection without an owner or with invalid/encrypted columns;
+trailing clauses (`STRICT`).
 
 **`DEFAULT` literals are accepted and ignored**: typegen extracts the
 schema *shape*; executing migrations (where defaults matter) is the
@@ -447,6 +466,15 @@ a bad table/column reference or a syntax error throws with SQLite's own
 message. The prepared statement then yields the result column names +
 `declaredTypes` (SQLite's `sqlite3_column_decltype`).
 
+For FTS-backed named queries the synthesized type-check database creates the
+same declared columns plus `_syncular_source_id UNINDEXED`. `MATCH :query`
+infers a string parameter, and the FTS table reference is folded into its
+owning synced table for dependency and scope-coverage metadata. `bm25`,
+`highlight`, and `snippet` are accepted deterministic FTS5 auxiliary
+functions only when the query references a schema-declared FTS projection;
+they use the normal computed-expression fidelity rules. Arbitrary extension
+functions remain outside the portable profile.
+
 **Typing fidelity** (what `bun:sqlite` actually exposes, and its honest
 boundary):
 

package/dist/emit-dart.js

@@ -64,6 +64,14 @@ function emitSchemaValue(ir, indent) {
             lines.push(`${i}        {'pattern': ${quote(scope.pattern)}, 'column': ${quote(scope.column)}},`);
         }
         lines.push(`${i}      ],`);
+        if (table.ftsIndexes.length > 0) {
+            lines.push(`${i}      'ftsIndexes': [`);
+            for (const index of table.ftsIndexes) {
+                const columns = index.columns.map((column) => quote(column)).join(', ');
+                lines.push(`${i}        {'name': ${quote(index.name)}, 'columns': [${columns}], 'tokenize': ${quote(index.tokenize)}},`);
+            }
+            lines.push(`${i}      ],`);
+        }
         lines.push(`${i}    },`);
     }
     lines.push(`${i}  ],`);

package/dist/emit-kotlin.js

@@ -64,6 +64,16 @@ function emitSchemaValue(ir, indent) {
             lines.push(`${i}        JsonValue.obj("pattern" to JsonValue.of(${quote(scope.pattern)}), "column" to JsonValue.of(${quote(scope.column)})),`);
         }
         lines.push(`${i}      )),`);
+        if (table.ftsIndexes.length > 0) {
+            lines.push(`${i}      "ftsIndexes" to JsonValue.arr(listOf(`);
+            for (const index of table.ftsIndexes) {
+                const columns = index.columns
+                    .map((column) => `JsonValue.of(${quote(column)})`)
+                    .join(', ');
+                lines.push(`${i}        JsonValue.obj("name" to JsonValue.of(${quote(index.name)}), "columns" to JsonValue.arr(listOf(${columns})), "tokenize" to JsonValue.of(${quote(index.tokenize)})),`);
+            }
+            lines.push(`${i}      )),`);
+        }
         lines.push(`${i}    ),`);
     }
     lines.push(`${i}  )),`);

package/dist/emit-swift.js

@@ -68,6 +68,16 @@ function emitSchemaValue(ir, indent) {
             lines.push(`${i}        .object(["pattern": .string(${quote(scope.pattern)}), "column": .string(${quote(scope.column)})]),`);
         }
         lines.push(`${i}      ]),`);
+        if (table.ftsIndexes.length > 0) {
+            lines.push(`${i}      "ftsIndexes": .array([`);
+            for (const index of table.ftsIndexes) {
+                const columns = index.columns
+                    .map((column) => `.string(${quote(column)})`)
+                    .join(', ');
+                lines.push(`${i}        .object(["name": .string(${quote(index.name)}), "columns": .array([${columns}]), "tokenize": .string(${quote(index.tokenize)})]),`);
+            }
+            lines.push(`${i}      ]),`);
+        }
         lines.push(`${i}    ]),`);
     }
     lines.push(`${i}  ]),`);

package/dist/emit.js

@@ -77,6 +77,14 @@ function emitSchema(ir) {
             }
             lines.push('      ],');
         }
+        if (table.ftsIndexes.length > 0) {
+            lines.push('      ftsIndexes: [');
+            for (const index of table.ftsIndexes) {
+                const cols = index.columns.map((column) => quote(column)).join(', ');
+                lines.push(`        { name: ${quote(index.name)}, columns: [${cols}], tokenize: ${quote(index.tokenize)} },`);
+            }
+            lines.push('      ],');
+        }
         lines.push('    },');
     }
     lines.push('  ],');

package/dist/generate.js

@@ -50,6 +50,14 @@ function buildTable(manifestTable, parsed) {
         }
     }
     const columns = applyEncryption(parsed, scopes, manifestTable.encryptedColumns);
+    for (const ftsIndex of parsed.ftsIndexes) {
+        for (const columnName of ftsIndex.columns) {
+            const column = columns.find((candidate) => candidate.name === columnName);
+            if (column?.encrypted === true) {
+                throw new TypegenError(MANIFEST_FILENAME, `table ${parsed.name}: FTS index ${JSON.stringify(ftsIndex.name)} cannot index encrypted column ${JSON.stringify(columnName)}`);
+            }
+        }
+    }
     return {
         name: parsed.name,
         primaryKey: parsed.primaryKey,
@@ -58,6 +66,7 @@ function buildTable(manifestTable, parsed) {
         // Indexes flow through from the migration parser (already validated:
         // columns exist, names unique per schema) in declaration order.
         indexes: parsed.indexes,
+        ftsIndexes: parsed.ftsIndexes,
         extensions: canonicalizeExtensions(manifestTable.extensions),
     };
 }
@@ -256,10 +265,16 @@ export function makeQueryDb(ir) {
             try {
                 const columnNames = stmt.columnNames;
                 // Execute once against the empty DB to populate decltype; result is [].
-                stmt.all();
-                const declaredTypes = stmt.declaredTypes;
                 const paramsCount = stmt
                     .paramsCount;
+                // An unbound FTS5 MATCH parameter is treated as the empty query and
+                // fails parsing. A numeric probe is valid for MATCH and LIMIT alike,
+                // while the empty database still guarantees no result rows.
+                const probe = /\bMATCH\b/i.test(sql)
+                    ? Array.from({ length: paramsCount }, () => 1)
+                    : [];
+                stmt.all(...probe);
+                const declaredTypes = stmt.declaredTypes;
                 return { columnNames, declaredTypes, paramsCount };
             }
             finally {

package/dist/ir.d.ts

@@ -37,6 +37,14 @@ export interface IrIndex {
     readonly columns: readonly string[];
     readonly unique: boolean;
 }
+/** One client-local contentful FTS5 projection. It is owned by the
+ * synced table in whose `ftsIndexes` array it appears and never enters the
+ * row codec, server schema, scopes, or mutation surface. */
+export interface IrFtsIndex {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly tokenize: string;
+}
 export interface IrTable {
     readonly name: string;
     readonly primaryKey: string;
@@ -46,6 +54,8 @@ export interface IrTable {
     /** Local secondary indexes (§migration subset), in declaration order.
      * Additive under irVersion 1: absent/empty for tables that declare none. */
     readonly indexes: readonly IrIndex[];
+    /** Client-local FTS5 projections, in migration declaration order. */
+    readonly ftsIndexes: readonly IrFtsIndex[];
     /** Reserved per-table hook slot (WP-49); empty object for now. */
     readonly extensions: Readonly<Record<string, unknown>>;
 }

package/dist/ir.js

@@ -74,6 +74,15 @@ export function serializeIr(ir) {
                     })),
                 }
                 : {}),
+            ...(table.ftsIndexes.length > 0
+                ? {
+                    ftsIndexes: table.ftsIndexes.map((index) => ({
+                        name: index.name,
+                        columns: index.columns,
+                        tokenize: index.tokenize,
+                    })),
+                }
+                : {}),
             extensions: canonicalizeExtensions(table.extensions),
         })),
         subscriptions: ir.subscriptions.map((sub) => ({

package/dist/query.js

@@ -439,7 +439,6 @@ export function toPositionalSql(sql) {
 const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
 // `FROM tbl [AS] a`, `JOIN tbl [AS] a`. We only need the referenced base
 // tables that exist in the IR; SQLite has already proven every reference.
-const TABLE_REF_RE = new RegExp(`\\b(?:FROM|JOIN)\\s+(${IDENT})(?:\\s+(?:AS\\s+)?(${IDENT}))?`, 'gi');
 const RESERVED_ALIAS = new Set([
     'on',
     'where',
@@ -455,9 +454,14 @@ const RESERVED_ALIAS = new Set([
     'limit',
     'having',
 ]);
+const RESERVED_ALIAS_PATTERN = [...RESERVED_ALIAS].join('|');
+const TABLE_REF_RE = new RegExp(`\\b(?:FROM|JOIN)\\s+(${IDENT})(?:\\s+(?:AS\\s+)?((?!(?:${RESERVED_ALIAS_PATTERN})\\b)${IDENT}))?`, 'gi');
 export function scanTableRefs(sql, ir) {
     const cleaned = stripCommentsAndStrings(sql);
-    const known = new Map(ir.tables.map((t) => [t.name, t]));
+    const known = new Set(ir.tables.flatMap((table) => [
+        table.name,
+        ...table.ftsIndexes.map((index) => index.name),
+    ]));
     const refs = [];
     for (const m of cleaned.matchAll(TABLE_REF_RE)) {
         const table = m[1];
@@ -614,6 +618,9 @@ function inferParamType(paramName, sql, refs, ir) {
     const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'i');
     if (like.test(cleaned))
         return 'string';
+    const match = new RegExp(`\\bMATCH\\b\\s*:${paramName}\\b`, 'i');
+    if (match.test(cleaned))
+        return 'string';
     return null;
 }
 /**
@@ -665,6 +672,9 @@ export function inferParamTypeEvidence(paramName, sql, refs, ir) {
     const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'gi');
     if (like.test(cleaned))
         evidence.push('string');
+    const match = new RegExp(`\\bMATCH\\b\\s*:${paramName}\\b`, 'gi');
+    if (match.test(cleaned))
+        evidence.push('string');
     return evidence;
 }
 // -- fallback column typing (computed expressions) ----------------------------
@@ -711,7 +721,10 @@ function inferReactiveMetadata(sql, refs, ir, params, columns) {
     const byParam = new Map(params.map((param) => [param.name, param]));
     const dependencies = [];
     const coverage = [];
-    for (const tableName of [...new Set(refs.map((ref) => ref.table))].sort()) {
+    const ftsOwner = new Map(ir.tables.flatMap((table) => table.ftsIndexes.map((index) => [index.name, table.name])));
+    for (const tableName of [
+        ...new Set(refs.map((ref) => ftsOwner.get(ref.table) ?? ref.table)),
+    ].sort()) {
         const table = ir.tables.find((candidate) => candidate.name === tableName);
         const tableRefs = refs.filter((ref) => ref.table === tableName);
         const scopes = [];
@@ -821,6 +834,10 @@ export function synthesizeDdl(ir) {
             const unique = index.unique ? 'UNIQUE ' : '';
             lines.push(`CREATE ${unique}INDEX ${index.name} ON ${table.name} (${index.columns.join(', ')});`);
         }
+        for (const index of table.ftsIndexes) {
+            const tokenize = index.tokenize.replaceAll("'", "''");
+            lines.push(`CREATE VIRTUAL TABLE ${index.name} USING fts5(_syncular_source_id UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`);
+        }
     }
     return lines.join('\n');
 }
@@ -864,7 +881,8 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
     };
     let described = analyze(sourceSql);
     const refs = scanTableRefs(sourceSql, ir);
-    const tableSet = new Set(refs.map((r) => r.table));
+    const ftsOwner = new Map(ir.tables.flatMap((table) => table.ftsIndexes.map((index) => [index.name, table.name])));
+    const tableSet = new Set(refs.map((ref) => ftsOwner.get(ref.table) ?? ref.table));
     const tables = [...tableSet].sort();
     if (tables.length === 0) {
         throw new TypegenError(file, 'query reads no synced table — every named query must read at least one IR table (for exact invalidation)');

package/dist/sql.d.ts

@@ -1,10 +1,12 @@
-import type { IrColumn, IrIndex } from './ir.js';
+import type { IrColumn, IrFtsIndex, IrIndex } from './ir.js';
 export interface ParsedTable {
     readonly name: string;
     primaryKey: string;
     readonly columns: IrColumn[];
     /** Local secondary indexes, in declaration order (CREATE INDEX subset). */
     readonly indexes: IrIndex[];
+    /** Client-local contentful FTS5 projections. */
+    readonly ftsIndexes: IrFtsIndex[];
 }
 /**
  * Apply one migration file's SQL to the accumulated table map. Columns

package/dist/sql.js

@@ -8,6 +8,8 @@
  * - `ALTER TABLE name ADD [COLUMN] coldef`
  * - `CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table (col [, col…])`
  * - `DROP TABLE [IF EXISTS] name`
+ * - `CREATE VIRTUAL TABLE name USING fts5(cols…, content=table,
+ *   [tokenize='allowlisted tokenizer'])` (RFC 0005 local projection)
  * - column defs: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL]
  *   [DEFAULT literal]`
  * - `--` and C-style comments
@@ -115,7 +117,7 @@ function tokenizeStatements(sql, source) {
             current.push({ kind: 'number', text: sql.slice(i, end) });
             i = end;
         }
-        else if (ch === '(' || ch === ')' || ch === ',') {
+        else if (ch === '(' || ch === ')' || ch === ',' || ch === '=') {
             current.push({ kind: 'punct', text: ch });
             i += 1;
         }
@@ -248,6 +250,10 @@ function parseColumnDef(cursor, allowPrimaryKey) {
  * `CREATE UNIQUE INDEX`. Anything else is a hard error naming the construct.
  */
 function parseCreate(cursor, tables, droppedTables, source) {
+    if (cursor.eatWord('VIRTUAL')) {
+        parseCreateVirtualTable(cursor, tables);
+        return;
+    }
     if (cursor.eatWord('TABLE')) {
         parseCreateTable(cursor, tables, droppedTables, source);
         return;
@@ -262,7 +268,109 @@ function parseCreate(cursor, tables, droppedTables, source) {
         return;
     }
     const token = cursor.peek();
-    cursor.fail(`unsupported CREATE statement (only CREATE TABLE and CREATE [UNIQUE] INDEX), found ${JSON.stringify(token?.text ?? '')}`);
+    cursor.fail(`unsupported CREATE statement (only CREATE TABLE, CREATE [UNIQUE] INDEX, and CREATE VIRTUAL TABLE … USING fts5), found ${JSON.stringify(token?.text ?? '')}`);
+}
+const ALLOWED_FTS_TOKENIZERS = new Set([
+    'unicode61',
+    'unicode61 remove_diacritics 0',
+    'unicode61 remove_diacritics 1',
+    'unicode61 remove_diacritics 2',
+    'porter unicode61',
+    'trigram',
+]);
+/** Parse the deliberately narrow migration-subset v2 FTS5 form documented in
+ * RFC 0005. The virtual table is attached to its owning synced
+ * table and is not itself a synced table. */
+function parseCreateVirtualTable(cursor, tables) {
+    cursor.expectWord('TABLE', 'after CREATE VIRTUAL');
+    if (cursor.eatWord('IF')) {
+        cursor.expectWord('NOT', 'after IF');
+        cursor.expectWord('EXISTS', 'after IF NOT');
+    }
+    const name = cursor.identifier('an FTS virtual-table name');
+    if (tables.has(name)) {
+        cursor.fail(`FTS virtual table ${name} conflicts with a synced table`);
+    }
+    for (const table of tables.values()) {
+        if (table.indexes.some((index) => index.name === name) ||
+            table.ftsIndexes.some((index) => index.name === name)) {
+            cursor.fail(`FTS virtual table ${name} is created twice or conflicts with an index`);
+        }
+    }
+    cursor.expectWord('USING', `after CREATE VIRTUAL TABLE ${name}`);
+    cursor.expectWord('FTS5', `as the module for ${name}`);
+    cursor.expectPunct('(', `after USING fts5 for ${name}`);
+    const columns = [];
+    let content;
+    let tokenize = 'unicode61';
+    let tokenizeDeclared = false;
+    let sawOption = false;
+    for (;;) {
+        const field = cursor.identifier(`an FTS5 column or option for ${name}`);
+        if (cursor.peek()?.text === '=') {
+            sawOption = true;
+            cursor.next();
+            const value = cursor.next();
+            if (value.kind !== 'word' && value.kind !== 'string') {
+                cursor.fail(`FTS virtual table ${name}: ${field} needs a literal value`);
+            }
+            if (field.toUpperCase() === 'CONTENT') {
+                if (content !== undefined) {
+                    cursor.fail(`FTS virtual table ${name}: content is declared twice`);
+                }
+                content = value.text;
+            }
+            else if (field.toUpperCase() === 'TOKENIZE') {
+                if (tokenizeDeclared) {
+                    cursor.fail(`FTS virtual table ${name}: tokenize is declared twice`);
+                }
+                if (!ALLOWED_FTS_TOKENIZERS.has(value.text)) {
+                    cursor.fail(`FTS virtual table ${name}: tokenizer ${JSON.stringify(value.text)} is not allowlisted`);
+                }
+                tokenize = value.text;
+                tokenizeDeclared = true;
+            }
+            else {
+                cursor.fail(`FTS virtual table ${name}: unsupported FTS5 option ${JSON.stringify(field)}`);
+            }
+        }
+        else {
+            if (sawOption) {
+                cursor.fail(`FTS virtual table ${name}: indexed columns must precede FTS5 options`);
+            }
+            if (columns.includes(field)) {
+                cursor.fail(`FTS virtual table ${name}: column ${JSON.stringify(field)} appears twice`);
+            }
+            columns.push(field);
+        }
+        const separator = cursor.next();
+        if (separator.kind === 'punct' && separator.text === ',')
+            continue;
+        if (separator.kind === 'punct' && separator.text === ')')
+            break;
+        cursor.fail(`FTS virtual table ${name}: expected "," or ")", found ${JSON.stringify(separator.text)}`);
+    }
+    cursor.expectEnd();
+    if (content === undefined) {
+        cursor.fail(`FTS virtual table ${name}: content = synced_table is required`);
+    }
+    const table = tables.get(content);
+    if (table === undefined) {
+        cursor.fail(`FTS virtual table ${name}: content table ${JSON.stringify(content)} does not exist at this point`);
+    }
+    if (columns.length === 0 || columns.length > 32) {
+        cursor.fail(`FTS virtual table ${name}: between 1 and 32 columns are required`);
+    }
+    for (const columnName of columns) {
+        const column = table.columns.find((candidate) => candidate.name === columnName);
+        if (column === undefined) {
+            cursor.fail(`FTS virtual table ${name}: column ${JSON.stringify(columnName)} does not exist on table ${content}`);
+        }
+        if (column.type !== 'string') {
+            cursor.fail(`FTS virtual table ${name}: column ${JSON.stringify(columnName)} must have TEXT/string type`);
+        }
+    }
+    table.ftsIndexes.push({ name, columns, tokenize });
 }
 function parseCreateTable(cursor, tables, droppedTables, source) {
     if (cursor.eatWord('IF')) {
@@ -276,6 +384,12 @@ function parseCreateTable(cursor, tables, droppedTables, source) {
     if (tables.has(name)) {
         cursor.fail(`table ${name} is created twice`);
     }
+    for (const table of tables.values()) {
+        if (table.indexes.some((index) => index.name === name) ||
+            table.ftsIndexes.some((index) => index.name === name)) {
+            cursor.fail(`table ${name} conflicts with an index or FTS virtual table`);
+        }
+    }
     cursor.expectPunct('(', `after CREATE TABLE ${name}`);
     const columns = [];
     const primaryKeys = [];
@@ -335,7 +449,13 @@ function parseCreateTable(cursor, tables, droppedTables, source) {
         throw new TypegenError(source, `table ${name}: primary key ${JSON.stringify(primaryKey)} is not a column`);
     }
     const finalColumns = columns.map((c) => c.name === primaryKey ? { ...c, nullable: false } : c);
-    tables.set(name, { name, primaryKey, columns: finalColumns, indexes: [] });
+    tables.set(name, {
+        name,
+        primaryKey,
+        columns: finalColumns,
+        indexes: [],
+        ftsIndexes: [],
+    });
 }
 /**
  * `CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table (col [, col…])`.
@@ -352,9 +472,13 @@ function parseCreateIndex(cursor, tables, unique) {
         cursor.expectWord('EXISTS', 'after IF NOT');
     }
     const name = cursor.identifier('an index name');
+    if (tables.has(name)) {
+        cursor.fail(`index ${name} conflicts with a synced table`);
+    }
     for (const table of tables.values()) {
-        if (table.indexes.some((i) => i.name === name)) {
-            cursor.fail(`index ${name} is created twice`);
+        if (table.indexes.some((i) => i.name === name) ||
+            table.ftsIndexes.some((i) => i.name === name)) {
+            cursor.fail(`index ${name} is created twice or conflicts with an FTS virtual table`);
         }
     }
     cursor.expectWord('ON', `after CREATE INDEX ${name}`);
@@ -459,7 +583,7 @@ export function applyMigrationSql(tables, sql, source, droppedTables = new Set()
             parseDropTable(cursor, tables, droppedTables);
         }
         else {
-            throw new TypegenError(source, `unsupported SQL statement starting with ${JSON.stringify(head.text)} (only CREATE TABLE, CREATE [UNIQUE] INDEX, ALTER TABLE … ADD COLUMN, and DROP TABLE)`);
+            throw new TypegenError(source, `unsupported SQL statement starting with ${JSON.stringify(head.text)} (only CREATE TABLE, CREATE [UNIQUE] INDEX, CREATE VIRTUAL TABLE … USING fts5, ALTER TABLE … ADD COLUMN, and DROP TABLE)`);
         }
     }
 }

package/dist/syql-validator.js

@@ -121,6 +121,16 @@ const SQLITE_346_PORTABLE_FUNCTIONS = new Set([
     'jsonb_replace',
     'jsonb_set',
 ]);
+/**
+ * Deterministic FTS5 auxiliary functions available only when the query reads
+ * a schema-declared FTS projection. FTS5 is an explicit Syncular client
+ * requirement in that case, not an arbitrary host extension.
+ */
+const SQLITE_FTS5_AUXILIARY_FUNCTIONS = new Set([
+    'bm25',
+    'highlight',
+    'snippet',
+]);
 const SQL_PAREN_KEYWORDS = new Set([
     'and',
     'as',
@@ -248,8 +258,8 @@ class Validator {
         const activeStructure = this.#inspect(activeSql, location);
         this.#validateStatementShape(activeSql, activeStructure, logical.declaration, location);
         this.#validateDeterminism(activeSql, logical.declaration.statement.span);
-        this.#validatePortableProfile(activeSql, logical.declaration.statement.span);
         const refs = scanTableRefs(activeSql, this.#ir);
+        this.#validatePortableProfile(activeSql, logical.declaration.statement.span, refs);
         const bindSymbols = this.#bindSymbols(logical.declaration);
         const bindTypes = this.#resolveBindTypes(logical, activeSql, refs, bindSymbols);
         const sort = this.#validateSort(logical.declaration, activeStructure, location);
@@ -512,8 +522,11 @@ class Validator {
             }
         }
     }
-    #validatePortableProfile(sql, span) {
+    #validatePortableProfile(sql, span, refs) {
         const tokens = significant(lexSyqlSqlSource(span.file, sql));
+        const declaredFtsTables = new Set(this.#ir.tables.flatMap((table) => table.ftsIndexes.map((index) => index.name)));
+        const queryRefs = refs ?? scanTableRefs(sql, this.#ir);
+        const readsDeclaredFts = queryRefs.some((ref) => declaredFtsTables.has(ref.table));
         for (let index = 0; index < tokens.length; index += 1) {
             const token = tokens[index];
             const lower = tokenLower(token);
@@ -537,8 +550,10 @@ class Validator {
                 tokens[closeIndex + 2]?.text === '(') {
                 continue;
             }
-            if (!SQLITE_346_PORTABLE_FUNCTIONS.has(lower ?? '')) {
-                this.#fail('SYQL6002_INVALID_SQL', token.span, `${token.text}() is not a core built-in in the portable SQLite 3.46.0 profile`);
+            const allowedFtsAuxiliary = readsDeclaredFts && SQLITE_FTS5_AUXILIARY_FUNCTIONS.has(lower ?? '');
+            if (!SQLITE_346_PORTABLE_FUNCTIONS.has(lower ?? '') &&
+                !allowedFtsAuxiliary) {
+                this.#fail('SYQL6002_INVALID_SQL', token.span, `${token.text}() is not a core built-in in the portable SQLite 3.46.0 profile or an auxiliary function of a referenced schema-declared FTS5 projection`);
             }
             const argumentCount = functionArgumentCount(tokens, index + 1);
             if (lower === 'iif' && argumentCount !== 3) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,7 +48,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/core": "0.14.0",
-    "@syncular/server": "0.14.0"
+    "@syncular/core": "0.15.1",
+    "@syncular/server": "0.15.1"
   }
 }

package/src/emit-dart.ts

@@ -91,6 +91,16 @@ function emitSchemaValue(ir: IrDocument, indent: string): string[] {
       );
     }
     lines.push(`${i}      ],`);
+    if (table.ftsIndexes.length > 0) {
+      lines.push(`${i}      'ftsIndexes': [`);
+      for (const index of table.ftsIndexes) {
+        const columns = index.columns.map((column) => quote(column)).join(', ');
+        lines.push(
+          `${i}        {'name': ${quote(index.name)}, 'columns': [${columns}], 'tokenize': ${quote(index.tokenize)}},`,
+        );
+      }
+      lines.push(`${i}      ],`);
+    }
     lines.push(`${i}    },`);
   }
   lines.push(`${i}  ],`);

package/src/emit-kotlin.ts

@@ -92,6 +92,18 @@ function emitSchemaValue(ir: IrDocument, indent: string): string[] {
       );
     }
     lines.push(`${i}      )),`);
+    if (table.ftsIndexes.length > 0) {
+      lines.push(`${i}      "ftsIndexes" to JsonValue.arr(listOf(`);
+      for (const index of table.ftsIndexes) {
+        const columns = index.columns
+          .map((column) => `JsonValue.of(${quote(column)})`)
+          .join(', ');
+        lines.push(
+          `${i}        JsonValue.obj("name" to JsonValue.of(${quote(index.name)}), "columns" to JsonValue.arr(listOf(${columns})), "tokenize" to JsonValue.of(${quote(index.tokenize)})),`,
+        );
+      }
+      lines.push(`${i}      )),`);
+    }
     lines.push(`${i}    ),`);
   }
   lines.push(`${i}  )),`);

package/src/emit-swift.ts

@@ -96,6 +96,18 @@ function emitSchemaValue(ir: IrDocument, indent: string): string[] {
       );
     }
     lines.push(`${i}      ]),`);
+    if (table.ftsIndexes.length > 0) {
+      lines.push(`${i}      "ftsIndexes": .array([`);
+      for (const index of table.ftsIndexes) {
+        const columns = index.columns
+          .map((column) => `.string(${quote(column)})`)
+          .join(', ');
+        lines.push(
+          `${i}        .object(["name": .string(${quote(index.name)}), "columns": .array([${columns}]), "tokenize": .string(${quote(index.tokenize)})]),`,
+        );
+      }
+      lines.push(`${i}      ]),`);
+    }
     lines.push(`${i}    ]),`);
   }
   lines.push(`${i}  ]),`);

package/src/emit.ts

@@ -108,6 +108,16 @@ function emitSchema(ir: IrDocument): string {
       }
       lines.push('      ],');
     }
+    if (table.ftsIndexes.length > 0) {
+      lines.push('      ftsIndexes: [');
+      for (const index of table.ftsIndexes) {
+        const cols = index.columns.map((column) => quote(column)).join(', ');
+        lines.push(
+          `        { name: ${quote(index.name)}, columns: [${cols}], tokenize: ${quote(index.tokenize)} },`,
+        );
+      }
+      lines.push('      ],');
+    }
     lines.push('    },');
   }
   lines.push('  ],');

package/src/generate.ts

@@ -113,6 +113,17 @@ function buildTable(
     scopes,
     manifestTable.encryptedColumns,
   );
+  for (const ftsIndex of parsed.ftsIndexes) {
+    for (const columnName of ftsIndex.columns) {
+      const column = columns.find((candidate) => candidate.name === columnName);
+      if (column?.encrypted === true) {
+        throw new TypegenError(
+          MANIFEST_FILENAME,
+          `table ${parsed.name}: FTS index ${JSON.stringify(ftsIndex.name)} cannot index encrypted column ${JSON.stringify(columnName)}`,
+        );
+      }
+    }
+  }
   return {
     name: parsed.name,
     primaryKey: parsed.primaryKey,
@@ -121,6 +132,7 @@ function buildTable(
     // Indexes flow through from the migration parser (already validated:
     // columns exist, names unique per schema) in declaration order.
     indexes: parsed.indexes,
+    ftsIndexes: parsed.ftsIndexes,
     extensions: canonicalizeExtensions(manifestTable.extensions) as Record<
       string,
       unknown
@@ -410,12 +422,22 @@ export function makeQueryDb(ir: IrDocument): {
       try {
         const columnNames = stmt.columnNames;
         // Execute once against the empty DB to populate decltype; result is [].
-        (stmt as unknown as { all: () => unknown[] }).all();
+        const paramsCount = (stmt as unknown as { paramsCount: number })
+          .paramsCount;
+        // An unbound FTS5 MATCH parameter is treated as the empty query and
+        // fails parsing. A numeric probe is valid for MATCH and LIMIT alike,
+        // while the empty database still guarantees no result rows.
+        const probe = /\bMATCH\b/i.test(sql)
+          ? Array.from({ length: paramsCount }, () => 1)
+          : [];
+        (
+          stmt as unknown as {
+            all: (...params: readonly number[]) => unknown[];
+          }
+        ).all(...probe);
         const declaredTypes = (
           stmt as unknown as { declaredTypes: (string | null)[] }
         ).declaredTypes;
-        const paramsCount = (stmt as unknown as { paramsCount: number })
-          .paramsCount;
         return { columnNames, declaredTypes, paramsCount };
       } finally {
         stmt.finalize();

package/src/ir.ts

@@ -64,6 +64,15 @@ export interface IrIndex {
   readonly unique: boolean;
 }
 
+/** One client-local contentful FTS5 projection. It is owned by the
+ * synced table in whose `ftsIndexes` array it appears and never enters the
+ * row codec, server schema, scopes, or mutation surface. */
+export interface IrFtsIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly tokenize: string;
+}
+
 export interface IrTable {
   readonly name: string;
   readonly primaryKey: string;
@@ -73,6 +82,8 @@ export interface IrTable {
   /** Local secondary indexes (§migration subset), in declaration order.
    * Additive under irVersion 1: absent/empty for tables that declare none. */
   readonly indexes: readonly IrIndex[];
+  /** Client-local FTS5 projections, in migration declaration order. */
+  readonly ftsIndexes: readonly IrFtsIndex[];
   /** Reserved per-table hook slot (WP-49); empty object for now. */
   readonly extensions: Readonly<Record<string, unknown>>;
 }
@@ -176,6 +187,15 @@ export function serializeIr(ir: IrDocument): string {
             })),
           }
         : {}),
+      ...(table.ftsIndexes.length > 0
+        ? {
+            ftsIndexes: table.ftsIndexes.map((index) => ({
+              name: index.name,
+              columns: index.columns,
+              tokenize: index.tokenize,
+            })),
+          }
+        : {}),
       extensions: canonicalizeExtensions(table.extensions),
     })),
     subscriptions: ir.subscriptions.map((sub) => ({

package/src/query.ts

@@ -696,11 +696,6 @@ export interface TableRef {
 const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
 // `FROM tbl [AS] a`, `JOIN tbl [AS] a`. We only need the referenced base
 // tables that exist in the IR; SQLite has already proven every reference.
-const TABLE_REF_RE = new RegExp(
-  `\\b(?:FROM|JOIN)\\s+(${IDENT})(?:\\s+(?:AS\\s+)?(${IDENT}))?`,
-  'gi',
-);
-
 const RESERVED_ALIAS = new Set([
   'on',
   'where',
@@ -716,10 +711,20 @@ const RESERVED_ALIAS = new Set([
   'limit',
   'having',
 ]);
+const RESERVED_ALIAS_PATTERN = [...RESERVED_ALIAS].join('|');
+const TABLE_REF_RE = new RegExp(
+  `\\b(?:FROM|JOIN)\\s+(${IDENT})(?:\\s+(?:AS\\s+)?((?!(?:${RESERVED_ALIAS_PATTERN})\\b)${IDENT}))?`,
+  'gi',
+);
 
 export function scanTableRefs(sql: string, ir: IrDocument): TableRef[] {
   const cleaned = stripCommentsAndStrings(sql);
-  const known = new Map(ir.tables.map((t) => [t.name, t] as const));
+  const known = new Set(
+    ir.tables.flatMap((table) => [
+      table.name,
+      ...table.ftsIndexes.map((index) => index.name),
+    ]),
+  );
   const refs: TableRef[] = [];
   for (const m of cleaned.matchAll(TABLE_REF_RE)) {
     const table = m[1] as string;
@@ -915,6 +920,8 @@ function inferParamType(
   // shape).
   const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'i');
   if (like.test(cleaned)) return 'string';
+  const match = new RegExp(`\\bMATCH\\b\\s*:${paramName}\\b`, 'i');
+  if (match.test(cleaned)) return 'string';
   return null;
 }
 
@@ -987,6 +994,8 @@ export function inferParamTypeEvidence(
   }
   const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'gi');
   if (like.test(cleaned)) evidence.push('string');
+  const match = new RegExp(`\\bMATCH\\b\\s*:${paramName}\\b`, 'gi');
+  if (match.test(cleaned)) evidence.push('string');
   return evidence;
 }
 
@@ -1054,8 +1063,15 @@ function inferReactiveMetadata(
     scopes: QueryScopeBinding[];
   }> = [];
   const coverage: QueryCoverageBinding[] = [];
+  const ftsOwner = new Map(
+    ir.tables.flatMap((table) =>
+      table.ftsIndexes.map((index) => [index.name, table.name] as const),
+    ),
+  );
 
-  for (const tableName of [...new Set(refs.map((ref) => ref.table))].sort()) {
+  for (const tableName of [
+    ...new Set(refs.map((ref) => ftsOwner.get(ref.table) ?? ref.table)),
+  ].sort()) {
     const table = ir.tables.find((candidate) => candidate.name === tableName);
     const tableRefs = refs.filter((ref) => ref.table === tableName);
     const scopes: QueryScopeBinding[] = [];
@@ -1192,6 +1208,12 @@ export function synthesizeDdl(ir: IrDocument): string {
         `CREATE ${unique}INDEX ${index.name} ON ${table.name} (${index.columns.join(', ')});`,
       );
     }
+    for (const index of table.ftsIndexes) {
+      const tokenize = index.tokenize.replaceAll("'", "''");
+      lines.push(
+        `CREATE VIRTUAL TABLE ${index.name} USING fts5(_syncular_source_id UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`,
+      );
+    }
   }
   return lines.join('\n');
 }
@@ -1252,7 +1274,14 @@ export function analyzeStatement(
   let described = analyze(sourceSql);
 
   const refs = scanTableRefs(sourceSql, ir);
-  const tableSet = new Set(refs.map((r) => r.table));
+  const ftsOwner = new Map(
+    ir.tables.flatMap((table) =>
+      table.ftsIndexes.map((index) => [index.name, table.name] as const),
+    ),
+  );
+  const tableSet = new Set(
+    refs.map((ref) => ftsOwner.get(ref.table) ?? ref.table),
+  );
   const tables = [...tableSet].sort();
   if (tables.length === 0) {
     throw new TypegenError(

package/src/sql.ts

@@ -8,6 +8,8 @@
  * - `ALTER TABLE name ADD [COLUMN] coldef`
  * - `CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table (col [, col…])`
  * - `DROP TABLE [IF EXISTS] name`
+ * - `CREATE VIRTUAL TABLE name USING fts5(cols…, content=table,
+ *   [tokenize='allowlisted tokenizer'])` (RFC 0005 local projection)
  * - column defs: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL]
  *   [DEFAULT literal]`
  * - `--` and C-style comments
@@ -18,7 +20,7 @@
  * indexes — is a hard error naming the unsupported construct.
  */
 import { TypegenError } from './errors';
-import type { IrColumn, IrColumnType, IrIndex } from './ir';
+import type { IrColumn, IrColumnType, IrFtsIndex, IrIndex } from './ir';
 
 /** SQL type keyword → the §2.4 column types. Case-insensitive. */
 const TYPE_MAP: Readonly<Record<string, IrColumnType>> = {
@@ -56,6 +58,8 @@ export interface ParsedTable {
   readonly columns: IrColumn[];
   /** Local secondary indexes, in declaration order (CREATE INDEX subset). */
   readonly indexes: IrIndex[];
+  /** Client-local contentful FTS5 projections. */
+  readonly ftsIndexes: IrFtsIndex[];
 }
 
 interface Token {
@@ -122,7 +126,7 @@ function tokenizeStatements(sql: string, source: string): Token[][] {
       while (end < sql.length && /[0-9.]/.test(sql[end] as string)) end += 1;
       current.push({ kind: 'number', text: sql.slice(i, end) });
       i = end;
-    } else if (ch === '(' || ch === ')' || ch === ',') {
+    } else if (ch === '(' || ch === ')' || ch === ',' || ch === '=') {
       current.push({ kind: 'punct', text: ch });
       i += 1;
     } else {
@@ -294,6 +298,10 @@ function parseCreate(
   droppedTables: ReadonlySet<string>,
   source: string,
 ): void {
+  if (cursor.eatWord('VIRTUAL')) {
+    parseCreateVirtualTable(cursor, tables);
+    return;
+  }
   if (cursor.eatWord('TABLE')) {
     parseCreateTable(cursor, tables, droppedTables, source);
     return;
@@ -309,10 +317,140 @@ function parseCreate(
   }
   const token = cursor.peek();
   cursor.fail(
-    `unsupported CREATE statement (only CREATE TABLE and CREATE [UNIQUE] INDEX), found ${JSON.stringify(token?.text ?? '')}`,
+    `unsupported CREATE statement (only CREATE TABLE, CREATE [UNIQUE] INDEX, and CREATE VIRTUAL TABLE … USING fts5), found ${JSON.stringify(token?.text ?? '')}`,
   );
 }
 
+const ALLOWED_FTS_TOKENIZERS = new Set([
+  'unicode61',
+  'unicode61 remove_diacritics 0',
+  'unicode61 remove_diacritics 1',
+  'unicode61 remove_diacritics 2',
+  'porter unicode61',
+  'trigram',
+]);
+
+/** Parse the deliberately narrow migration-subset v2 FTS5 form documented in
+ * RFC 0005. The virtual table is attached to its owning synced
+ * table and is not itself a synced table. */
+function parseCreateVirtualTable(
+  cursor: Cursor,
+  tables: Map<string, ParsedTable>,
+): void {
+  cursor.expectWord('TABLE', 'after CREATE VIRTUAL');
+  if (cursor.eatWord('IF')) {
+    cursor.expectWord('NOT', 'after IF');
+    cursor.expectWord('EXISTS', 'after IF NOT');
+  }
+  const name = cursor.identifier('an FTS virtual-table name');
+  if (tables.has(name)) {
+    cursor.fail(`FTS virtual table ${name} conflicts with a synced table`);
+  }
+  for (const table of tables.values()) {
+    if (
+      table.indexes.some((index) => index.name === name) ||
+      table.ftsIndexes.some((index) => index.name === name)
+    ) {
+      cursor.fail(
+        `FTS virtual table ${name} is created twice or conflicts with an index`,
+      );
+    }
+  }
+  cursor.expectWord('USING', `after CREATE VIRTUAL TABLE ${name}`);
+  cursor.expectWord('FTS5', `as the module for ${name}`);
+  cursor.expectPunct('(', `after USING fts5 for ${name}`);
+  const columns: string[] = [];
+  let content: string | undefined;
+  let tokenize = 'unicode61';
+  let tokenizeDeclared = false;
+  let sawOption = false;
+  for (;;) {
+    const field = cursor.identifier(`an FTS5 column or option for ${name}`);
+    if (cursor.peek()?.text === '=') {
+      sawOption = true;
+      cursor.next();
+      const value = cursor.next();
+      if (value.kind !== 'word' && value.kind !== 'string') {
+        cursor.fail(
+          `FTS virtual table ${name}: ${field} needs a literal value`,
+        );
+      }
+      if (field.toUpperCase() === 'CONTENT') {
+        if (content !== undefined) {
+          cursor.fail(`FTS virtual table ${name}: content is declared twice`);
+        }
+        content = value.text;
+      } else if (field.toUpperCase() === 'TOKENIZE') {
+        if (tokenizeDeclared) {
+          cursor.fail(`FTS virtual table ${name}: tokenize is declared twice`);
+        }
+        if (!ALLOWED_FTS_TOKENIZERS.has(value.text)) {
+          cursor.fail(
+            `FTS virtual table ${name}: tokenizer ${JSON.stringify(value.text)} is not allowlisted`,
+          );
+        }
+        tokenize = value.text;
+        tokenizeDeclared = true;
+      } else {
+        cursor.fail(
+          `FTS virtual table ${name}: unsupported FTS5 option ${JSON.stringify(field)}`,
+        );
+      }
+    } else {
+      if (sawOption) {
+        cursor.fail(
+          `FTS virtual table ${name}: indexed columns must precede FTS5 options`,
+        );
+      }
+      if (columns.includes(field)) {
+        cursor.fail(
+          `FTS virtual table ${name}: column ${JSON.stringify(field)} appears twice`,
+        );
+      }
+      columns.push(field);
+    }
+    const separator = cursor.next();
+    if (separator.kind === 'punct' && separator.text === ',') continue;
+    if (separator.kind === 'punct' && separator.text === ')') break;
+    cursor.fail(
+      `FTS virtual table ${name}: expected "," or ")", found ${JSON.stringify(separator.text)}`,
+    );
+  }
+  cursor.expectEnd();
+  if (content === undefined) {
+    cursor.fail(
+      `FTS virtual table ${name}: content = synced_table is required`,
+    );
+  }
+  const table = tables.get(content);
+  if (table === undefined) {
+    cursor.fail(
+      `FTS virtual table ${name}: content table ${JSON.stringify(content)} does not exist at this point`,
+    );
+  }
+  if (columns.length === 0 || columns.length > 32) {
+    cursor.fail(
+      `FTS virtual table ${name}: between 1 and 32 columns are required`,
+    );
+  }
+  for (const columnName of columns) {
+    const column = table.columns.find(
+      (candidate) => candidate.name === columnName,
+    );
+    if (column === undefined) {
+      cursor.fail(
+        `FTS virtual table ${name}: column ${JSON.stringify(columnName)} does not exist on table ${content}`,
+      );
+    }
+    if (column.type !== 'string') {
+      cursor.fail(
+        `FTS virtual table ${name}: column ${JSON.stringify(columnName)} must have TEXT/string type`,
+      );
+    }
+  }
+  table.ftsIndexes.push({ name, columns, tokenize });
+}
+
 function parseCreateTable(
   cursor: Cursor,
   tables: Map<string, ParsedTable>,
@@ -332,6 +470,14 @@ function parseCreateTable(
   if (tables.has(name)) {
     cursor.fail(`table ${name} is created twice`);
   }
+  for (const table of tables.values()) {
+    if (
+      table.indexes.some((index) => index.name === name) ||
+      table.ftsIndexes.some((index) => index.name === name)
+    ) {
+      cursor.fail(`table ${name} conflicts with an index or FTS virtual table`);
+    }
+  }
   cursor.expectPunct('(', `after CREATE TABLE ${name}`);
   const columns: IrColumn[] = [];
   const primaryKeys: string[] = [];
@@ -401,7 +547,13 @@ function parseCreateTable(
   const finalColumns = columns.map((c) =>
     c.name === primaryKey ? { ...c, nullable: false } : c,
   );
-  tables.set(name, { name, primaryKey, columns: finalColumns, indexes: [] });
+  tables.set(name, {
+    name,
+    primaryKey,
+    columns: finalColumns,
+    indexes: [],
+    ftsIndexes: [],
+  });
 }
 
 /**
@@ -423,9 +575,17 @@ function parseCreateIndex(
     cursor.expectWord('EXISTS', 'after IF NOT');
   }
   const name = cursor.identifier('an index name');
+  if (tables.has(name)) {
+    cursor.fail(`index ${name} conflicts with a synced table`);
+  }
   for (const table of tables.values()) {
-    if (table.indexes.some((i) => i.name === name)) {
-      cursor.fail(`index ${name} is created twice`);
+    if (
+      table.indexes.some((i) => i.name === name) ||
+      table.ftsIndexes.some((i) => i.name === name)
+    ) {
+      cursor.fail(
+        `index ${name} is created twice or conflicts with an FTS virtual table`,
+      );
     }
   }
   cursor.expectWord('ON', `after CREATE INDEX ${name}`);
@@ -559,7 +719,7 @@ export function applyMigrationSql(
     } else {
       throw new TypegenError(
         source,
-        `unsupported SQL statement starting with ${JSON.stringify(head.text)} (only CREATE TABLE, CREATE [UNIQUE] INDEX, ALTER TABLE … ADD COLUMN, and DROP TABLE)`,
+        `unsupported SQL statement starting with ${JSON.stringify(head.text)} (only CREATE TABLE, CREATE [UNIQUE] INDEX, CREATE VIRTUAL TABLE … USING fts5, ALTER TABLE … ADD COLUMN, and DROP TABLE)`,
       );
     }
   }

package/src/syql-validator.ts

@@ -221,6 +221,16 @@ const SQLITE_346_PORTABLE_FUNCTIONS = new Set([
   'jsonb_replace',
   'jsonb_set',
 ]);
+/**
+ * Deterministic FTS5 auxiliary functions available only when the query reads
+ * a schema-declared FTS projection. FTS5 is an explicit Syncular client
+ * requirement in that case, not an arbitrary host extension.
+ */
+const SQLITE_FTS5_AUXILIARY_FUNCTIONS = new Set([
+  'bm25',
+  'highlight',
+  'snippet',
+]);
 const SQL_PAREN_KEYWORDS = new Set([
   'and',
   'as',
@@ -376,12 +386,13 @@ class Validator {
       location,
     );
     this.#validateDeterminism(activeSql, logical.declaration.statement.span);
+    const refs = scanTableRefs(activeSql, this.#ir);
     this.#validatePortableProfile(
       activeSql,
       logical.declaration.statement.span,
+      refs,
     );
 
-    const refs = scanTableRefs(activeSql, this.#ir);
     const bindSymbols = this.#bindSymbols(logical.declaration);
     const bindTypes = this.#resolveBindTypes(
       logical,
@@ -792,8 +803,21 @@ class Validator {
     }
   }
 
-  #validatePortableProfile(sql: string, span: SyqlSourceSpan): void {
+  #validatePortableProfile(
+    sql: string,
+    span: SyqlSourceSpan,
+    refs?: readonly TableRef[],
+  ): void {
     const tokens = significant(lexSyqlSqlSource(span.file, sql));
+    const declaredFtsTables = new Set(
+      this.#ir.tables.flatMap((table) =>
+        table.ftsIndexes.map((index) => index.name),
+      ),
+    );
+    const queryRefs = refs ?? scanTableRefs(sql, this.#ir);
+    const readsDeclaredFts = queryRefs.some((ref) =>
+      declaredFtsTables.has(ref.table),
+    );
     for (let index = 0; index < tokens.length; index += 1) {
       const token = tokens[index] as SyqlToken;
       const lower = tokenLower(token);
@@ -828,11 +852,16 @@ class Validator {
       ) {
         continue;
       }
-      if (!SQLITE_346_PORTABLE_FUNCTIONS.has(lower ?? '')) {
+      const allowedFtsAuxiliary =
+        readsDeclaredFts && SQLITE_FTS5_AUXILIARY_FUNCTIONS.has(lower ?? '');
+      if (
+        !SQLITE_346_PORTABLE_FUNCTIONS.has(lower ?? '') &&
+        !allowedFtsAuxiliary
+      ) {
         this.#fail(
           'SYQL6002_INVALID_SQL',
           token.span,
-          `${token.text}() is not a core built-in in the portable SQLite 3.46.0 profile`,
+          `${token.text}() is not a core built-in in the portable SQLite 3.46.0 profile or an auxiliary function of a referenced schema-declared FTS5 projection`,
         );
       }