@syncular/typegen 0.15.0 → 0.15.2

package/README.md

@@ -470,8 +470,13 @@ 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` remain SQLite expressions and therefore use the
-normal computed-expression fidelity rules.
+`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. A bounded FTS join must project
+the FTS table's `_syncular_source_id` as well as every joined table's primary
+key and end its total order in those identity fields. Typegen then proves the
+composite row key instead of weakening bounded-query stability rules.
 
 **Typing fidelity** (what `bun:sqlite` actually exposes, and its honest
 boundary):

package/dist/query.js

@@ -86,6 +86,8 @@ const DECLTYPE_MAP = {
 };
 /** Local client protocol column; query-only and never part of schema IR. */
 const SYNC_VERSION_COLUMN = '_sync_version';
+/** Stable private identity shared by every declared local FTS5 projection. */
+const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
 const DEFAULT_NAMING = { naming: 'camel', targets: ['ts'] };
 // -- path → name --------------------------------------------------------------
 /** A single kebab-case path segment (folder) or filename stem. */
@@ -513,6 +515,14 @@ function splitSelectList(sql) {
     return items;
 }
 const PLAIN_REF_RE = new RegExp(`^(?:(${IDENT})\\.)?(${IDENT})$`);
+function declaredFtsProjection(ir, tableName) {
+    return ir.tables.some((table) => table.ftsIndexes.some((index) => index.name === tableName));
+}
+const FTS_SOURCE_ID_IR_COLUMN = {
+    name: FTS_SOURCE_ID_COLUMN,
+    type: 'string',
+    nullable: false,
+};
 /** Resolve a SELECT item's expression to an IR column, if it is a plain ref. */
 function resolveSource(item, refs, ir) {
     const m = PLAIN_REF_RE.exec(item.expr);
@@ -527,7 +537,13 @@ function resolveSource(item, refs, ir) {
             return null;
         const table = byName.get(ref.table);
         const col = table?.columns.find((c) => c.name === columnName);
-        return col === undefined ? null : { table: ref.table, column: col };
+        if (col !== undefined)
+            return { table: ref.table, column: col };
+        if (columnName === FTS_SOURCE_ID_COLUMN &&
+            declaredFtsProjection(ir, ref.table)) {
+            return { table: ref.table, column: FTS_SOURCE_ID_IR_COLUMN };
+        }
+        return null;
     }
     // Unqualified: search every FROM/JOIN table (SQLite already resolved
     // ambiguity; a single-table query is the common case).
@@ -536,6 +552,10 @@ function resolveSource(item, refs, ir) {
         const col = table?.columns.find((c) => c.name === columnName);
         if (col !== undefined)
             return { table: ref.table, column: col };
+        if (columnName === FTS_SOURCE_ID_COLUMN &&
+            declaredFtsProjection(ir, ref.table)) {
+            return { table: ref.table, column: FTS_SOURCE_ID_IR_COLUMN };
+        }
     }
     return null;
 }
@@ -836,7 +856,7 @@ export function synthesizeDdl(ir) {
         }
         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}');`);
+            lines.push(`CREATE VIRTUAL TABLE ${index.name} USING fts5(${FTS_SOURCE_ID_COLUMN} UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`);
         }
     }
     return lines.join('\n');

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) {
@@ -892,9 +907,13 @@ class Validator {
         const inferred = [];
         for (const ref of refs) {
             const table = this.#ir.tables.find((item) => item.name === ref.table);
-            const column = analysis.columns.find((candidate) => table !== undefined &&
-                candidate.origin?.table === table.name &&
-                candidate.origin.column === table.primaryKey &&
+            const primaryKey = table?.primaryKey ??
+                (this.#ir.tables.some((item) => item.ftsIndexes.some((index) => index.name === ref.table))
+                    ? '_syncular_source_id'
+                    : undefined);
+            const column = analysis.columns.find((candidate) => primaryKey !== undefined &&
+                candidate.origin?.table === ref.table &&
+                candidate.origin.column === primaryKey &&
                 !candidate.nullable);
             if (column === undefined)
                 return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "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.15.0",
-    "@syncular/server": "0.15.0"
+    "@syncular/core": "0.15.2",
+    "@syncular/server": "0.15.2"
   }
 }

package/src/query.ts

@@ -89,6 +89,8 @@ const DECLTYPE_MAP: Readonly<Record<string, IrColumnType>> = {
 
 /** Local client protocol column; query-only and never part of schema IR. */
 const SYNC_VERSION_COLUMN = '_sync_version';
+/** Stable private identity shared by every declared local FTS5 projection. */
+const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
 
 /** A param type is one of the §2.4 types (the columns params compare to). */
 export type QueryParamType = IrColumnType;
@@ -793,6 +795,18 @@ interface ResolvedSource {
   readonly column: IrTable['columns'][number];
 }
 
+function declaredFtsProjection(ir: IrDocument, tableName: string): boolean {
+  return ir.tables.some((table) =>
+    table.ftsIndexes.some((index) => index.name === tableName),
+  );
+}
+
+const FTS_SOURCE_ID_IR_COLUMN: IrTable['columns'][number] = {
+  name: FTS_SOURCE_ID_COLUMN,
+  type: 'string',
+  nullable: false,
+};
+
 /** Resolve a SELECT item's expression to an IR column, if it is a plain ref. */
 function resolveSource(
   item: SelectItem,
@@ -809,7 +823,14 @@ function resolveSource(
     if (ref === undefined) return null;
     const table = byName.get(ref.table);
     const col = table?.columns.find((c) => c.name === columnName);
-    return col === undefined ? null : { table: ref.table, column: col };
+    if (col !== undefined) return { table: ref.table, column: col };
+    if (
+      columnName === FTS_SOURCE_ID_COLUMN &&
+      declaredFtsProjection(ir, ref.table)
+    ) {
+      return { table: ref.table, column: FTS_SOURCE_ID_IR_COLUMN };
+    }
+    return null;
   }
   // Unqualified: search every FROM/JOIN table (SQLite already resolved
   // ambiguity; a single-table query is the common case).
@@ -817,6 +838,12 @@ function resolveSource(
     const table = byName.get(ref.table);
     const col = table?.columns.find((c) => c.name === columnName);
     if (col !== undefined) return { table: ref.table, column: col };
+    if (
+      columnName === FTS_SOURCE_ID_COLUMN &&
+      declaredFtsProjection(ir, ref.table)
+    ) {
+      return { table: ref.table, column: FTS_SOURCE_ID_IR_COLUMN };
+    }
   }
   return null;
 }
@@ -1211,7 +1238,7 @@ export function synthesizeDdl(ir: IrDocument): string {
     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}');`,
+        `CREATE VIRTUAL TABLE ${index.name} USING fts5(${FTS_SOURCE_ID_COLUMN} UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`,
       );
     }
   }

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`,
         );
       }
 
@@ -1335,11 +1364,18 @@ class Validator {
     const inferred: string[] = [];
     for (const ref of refs) {
       const table = this.#ir.tables.find((item) => item.name === ref.table);
+      const primaryKey =
+        table?.primaryKey ??
+        (this.#ir.tables.some((item) =>
+          item.ftsIndexes.some((index) => index.name === ref.table),
+        )
+          ? '_syncular_source_id'
+          : undefined);
       const column = analysis.columns.find(
         (candidate) =>
-          table !== undefined &&
-          candidate.origin?.table === table.name &&
-          candidate.origin.column === table.primaryKey &&
+          primaryKey !== undefined &&
+          candidate.origin?.table === ref.table &&
+          candidate.origin.column === primaryKey &&
           !candidate.nullable,
       );
       if (column === undefined) return undefined;