@syncular/typegen 0.15.1 → 0.15.3

package/README.md

@@ -473,7 +473,10 @@ 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.
+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

@@ -762,7 +762,10 @@ class Validator {
             }
             candidates.push({ ref, scopes: inferred });
         }
-        const dependencies = [...new Set(refs.map((ref) => ref.table))]
+        const ftsOwners = new Map(this.#ir.tables.flatMap((table) => table.ftsIndexes.map((index) => [index.name, table.name])));
+        const dependencies = [
+            ...new Set(refs.map((ref) => ftsOwners.get(ref.table) ?? ref.table)),
+        ]
             .sort()
             .map((table) => {
             const instances = candidates.filter((item) => item.ref.table === table);
@@ -907,9 +910,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.1",
+  "version": "0.15.3",
   "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.1",
-    "@syncular/server": "0.15.1"
+    "@syncular/core": "0.15.3",
+    "@syncular/server": "0.15.3"
   }
 }

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

@@ -1149,7 +1149,14 @@ class Validator {
       candidates.push({ ref, scopes: inferred });
     }
 
-    const dependencies = [...new Set(refs.map((ref) => ref.table))]
+    const ftsOwners = new Map(
+      this.#ir.tables.flatMap((table) =>
+        table.ftsIndexes.map((index) => [index.name, table.name] as const),
+      ),
+    );
+    const dependencies = [
+      ...new Set(refs.map((ref) => ftsOwners.get(ref.table) ?? ref.table)),
+    ]
       .sort()
       .map((table) => {
         const instances = candidates.filter((item) => item.ref.table === table);
@@ -1364,11 +1371,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;