@syncular/typegen 0.5.1 → 0.7.0

package/src/manifest.ts

@@ -128,9 +128,7 @@ export interface Manifest {
    * generated row types/params (queries lower with `AS` aliases); "preserve"
    * keeps SQL-truth names everywhere. */
   readonly naming: NamingMode;
-  /** §7 `.syql` backend: "neutralize" (default), "variants" (enumerate
-   * whenever eligible), or "auto" (enumerate at ≤ 2 optional groups). The
-   * per-query `variants` knob always forces enumeration. */
+  /** §7 `.syql` backend: "auto" (default), "neutralize", or "variants". */
   readonly queryBackend: ManifestQueryBackend;
   readonly output: ManifestOutput;
   readonly schemaVersions: readonly ManifestSchemaVersion[];
@@ -389,7 +387,7 @@ export function parseManifest(raw: unknown): Manifest {
     }
     naming = obj.naming;
   }
-  let queryBackend: ManifestQueryBackend = 'neutralize';
+  let queryBackend: ManifestQueryBackend = 'auto';
   if (obj.queryBackend !== undefined) {
     if (
       obj.queryBackend !== 'neutralize' &&

package/src/query-ir.ts

@@ -14,7 +14,7 @@ import type { AnalyzedQuery } from './query';
 /** Serialize analyzed queries as the deterministic QueryIR JSON document. */
 export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
   const doc = {
-    queryIrVersion: 2,
+    queryIrVersion: 3,
     queries: queries.map((query) => ({
       name: query.name,
       file: query.file,
@@ -25,11 +25,6 @@ export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
         name: param.name,
         langName: param.langName,
         type: param.type,
-        // §4 metadata — emitted only when set, so `.sql`-tier IR bytes are
-        // unchanged from before the DSL existed.
-        ...(param.optional === true ? { optional: true } : {}),
-        ...(param.group !== undefined ? { group: param.group } : {}),
-        ...(param.flag === true ? { flag: true } : {}),
       })),
       columns: query.columns.map((column) => ({
         name: column.name,
@@ -62,43 +57,58 @@ export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
           ? { rowKey: query.reactive.rowKey }
           : {}),
       },
-      // §6 knob metadata — emitted only when declared.
-      ...(query.orderBy !== undefined
-        ? {
-            orderBy: {
-              allowed: query.orderBy.allowed.map((c) => ({
-                name: c.name,
-                langName: c.langName,
-              })),
-              defaultColumn: query.orderBy.defaultColumn,
-              defaultDir: query.orderBy.defaultDir,
+      ...(query.syql === undefined
+        ? {}
+        : {
+            syql: {
+              revision: query.syql.revision,
+              inputs: query.syql.inputs.map((input) => {
+                if (input.kind === 'value') return { ...input };
+                if (input.kind === 'group') {
+                  return {
+                    kind: input.kind,
+                    name: input.name,
+                    langName: input.langName,
+                    members: input.members.map((member) => ({ ...member })),
+                  };
+                }
+                if (input.kind === 'sort') {
+                  return {
+                    kind: input.kind,
+                    name: input.name,
+                    langName: input.langName,
+                    defaultProfile: input.defaultProfile,
+                    profiles: input.profiles.map((profile) => ({ ...profile })),
+                  };
+                }
+                return { ...input };
+              }),
+              plan: {
+                backend: query.syql.plan.backend,
+                activationControls: query.syql.plan.activationControls,
+                conditions: query.syql.plan.conditions.map((condition) => ({
+                  controls: condition.controls,
+                  ...(condition.bind === undefined
+                    ? {}
+                    : { bind: condition.bind }),
+                })),
+                statements: query.syql.plan.statements.map((statement) => ({
+                  ...(statement.sortProfile === undefined
+                    ? {}
+                    : { sortProfile: statement.sortProfile }),
+                  ...(statement.activationMask === undefined
+                    ? {}
+                    : { activationMask: statement.activationMask }),
+                  sql: statement.sql,
+                  positionalSql: statement.positionalSql,
+                  binds: statement.binds.map((bind) => ({ ...bind })),
+                })),
+              },
+              ...(query.syql.identity === undefined
+                ? {}
+                : { identity: query.syql.identity }),
             },
-          }
-        : {}),
-      ...(query.limit !== undefined ? { limit: query.limit } : {}),
-      ...(query.positionalSqlBase !== undefined
-        ? { positionalSqlBase: query.positionalSqlBase }
-        : {}),
-      // §7 variant backend — emitted only when the query opts in.
-      ...(query.variantGroups !== undefined
-        ? {
-            variantGroups: query.variantGroups.map((g) => ({
-              key: g.key,
-              params: g.params,
-              flag: g.flag,
-            })),
-          }
-        : {}),
-      ...(query.variants !== undefined
-        ? {
-            variants: query.variants.map((v) => ({
-              when: v.when,
-              sql: v.sql,
-              positionalSql: v.positionalSql,
-              params: v.params,
-            })),
-          }
-        : {}),
+          }),
     })),
   };
   return `${JSON.stringify(doc, null, 2)}\n`;

package/src/query.ts

@@ -87,6 +87,9 @@ const DECLTYPE_MAP: Readonly<Record<string, IrColumnType>> = {
   CRDT: 'crdt',
 };
 
+/** Local client protocol column; query-only and never part of schema IR. */
+const SYNC_VERSION_COLUMN = '_sync_version';
+
 /** A param type is one of the §2.4 types (the columns params compare to). */
 export type QueryParamType = IrColumnType;
 
@@ -98,30 +101,6 @@ export interface QueryParam {
   readonly type: QueryParamType;
   /** How the type was resolved — for the docs/tests, not emitted. */
   readonly source: 'inferred' | 'comment';
-  /** §4 (DESIGN-queries.md): an optional param — its auto-guarded conjunct
-   * applies only when it is provided. Always false for the `.sql` tier. */
-  readonly optional?: boolean;
-  /** §4: the `from+to` pairing — params sharing a group apply together. */
-  readonly group?: string;
-  /** §3: a `: flag` boolean guard param (never in a predicate as written;
-   * the lowering binds it). Implies optional. */
-  readonly flag?: boolean;
-}
-
-/** §6 orderBy knob: a generate-time allowlist (identifiers cannot bind). */
-export interface QueryOrderBy {
-  /** Allowed columns: authored SQL name + the language-facing key the
-   * generated signature accepts. Each is SQLite-checked at generate time. */
-  readonly allowed: readonly { name: string; langName: string }[];
-  /** Default column (authored SQL name). */
-  readonly defaultColumn: string;
-  readonly defaultDir: 'asc' | 'desc';
-}
-
-/** §6 limit knob: a bound value with a codegen clamp + default. */
-export interface QueryLimit {
-  readonly max?: number;
-  readonly default?: number;
 }
 
 export interface QueryColumn {
@@ -166,7 +145,7 @@ export interface QueryReactiveMetadata {
   readonly rowKey?: readonly string[];
 }
 
-/** §7/§8 backend selection: neutralization (default), always-variants, or
+/** §7/§8 backend selection: neutralization, always-variants, or
  * the small-N heuristic (`auto`: enumerate at ≤ 2 optional groups). */
 export type QueryBackend = 'neutralize' | 'variants' | 'auto';
 
@@ -176,13 +155,115 @@ export interface QueryNamingOptions {
   /** Emitter targets this run generates — keyword hazards are only real on
    * targets that exist. */
   readonly targets: readonly NamingTarget[];
-  /** `.syql` conditional-lowering backend (default `neutralize`); the
-   * per-query `variants` knob always forces enumeration. */
+  /** `.syql` conditional-lowering policy (default `auto`). */
   readonly backend?: QueryBackend;
+  /** Compiler-reserved physical binds. They retain their exact names and do
+   * not participate in public target-language keyword/private-name checks. */
+  readonly internalParams?: readonly string[];
 }
 
 const DEFAULT_NAMING: QueryNamingOptions = { naming: 'camel', targets: ['ts'] };
 
+/** SYQL public inputs. These are deliberately separate from SQL binds: groups
+ * and compiler-generated parameters have distinct public/runtime shapes. */
+export type QuerySyqlPublicInput =
+  | {
+      readonly kind: 'value';
+      readonly name: string;
+      readonly langName: string;
+      readonly type: QueryParamType;
+      readonly nullable: boolean;
+      readonly required: boolean;
+      readonly default?: false;
+    }
+  | {
+      readonly kind: 'group';
+      readonly name: string;
+      readonly langName: string;
+      readonly members: readonly {
+        readonly name: string;
+        readonly langName: string;
+        readonly type: QueryParamType;
+        readonly nullable: boolean;
+      }[];
+    }
+  | {
+      readonly kind: 'sort';
+      readonly name: string;
+      readonly langName: string;
+      readonly defaultProfile: string;
+      readonly profiles: readonly {
+        readonly name: string;
+        readonly langName: string;
+      }[];
+    }
+  | {
+      readonly kind: 'limit';
+      readonly name: string;
+      readonly langName: string;
+      readonly defaultSize: number;
+      readonly maxSize: number;
+    };
+
+/** One distinct SQLite bind in a physical revision-1 statement. */
+export type QuerySyqlPlanBind =
+  | {
+      readonly kind: 'value';
+      readonly name: string;
+      readonly type: QueryParamType;
+      readonly input: string;
+    }
+  | {
+      readonly kind: 'group-member';
+      readonly name: string;
+      readonly type: QueryParamType;
+      readonly input: string;
+      readonly member: string;
+    }
+  | {
+      readonly kind: 'condition-active';
+      readonly name: string;
+      readonly type: 'boolean';
+      readonly condition: number;
+      readonly controls: readonly string[];
+    }
+  | {
+      readonly kind: 'limit';
+      readonly name: string;
+      readonly type: 'integer';
+      readonly input: string;
+    };
+
+/** One SQLite-checked statement selected by sort profile and, for the
+ * enumerated backend, the activation bitmask. */
+export interface QuerySyqlStatement {
+  readonly sortProfile?: string;
+  readonly activationMask?: number;
+  readonly sql: string;
+  readonly positionalSql: string;
+  readonly binds: readonly QuerySyqlPlanBind[];
+}
+
+/** The target-neutral physical plan every emitter must implement exactly. */
+export interface QuerySyqlExecutionPlan {
+  readonly backend: Exclude<QueryBackend, 'auto'>;
+  /** One bit per conditional activation control, in declaration order. */
+  readonly activationControls: readonly string[];
+  readonly conditions: readonly {
+    readonly controls: readonly string[];
+    /** Present only for neutralized plans. */
+    readonly bind?: string;
+  }[];
+  readonly statements: readonly QuerySyqlStatement[];
+}
+
+export interface QuerySyqlMetadata {
+  readonly revision: 1;
+  readonly inputs: readonly QuerySyqlPublicInput[];
+  readonly plan: QuerySyqlExecutionPlan;
+  readonly identity?: readonly string[];
+}
+
 export interface AnalyzedQuery {
   /** camelCase function name (path-derived, or a `-- name:` override). */
   readonly name: string;
@@ -204,41 +285,9 @@ export interface AnalyzedQuery {
   /** IR tables this query reads (the useRawSql `{tables}` set), sorted. */
   readonly tables: readonly string[];
   readonly reactive: QueryReactiveMetadata;
-  /** §6 orderBy knob (`.syql` tier). When present, `sql`/`positionalSql`
-   * carry the DEFAULT order-by tail and `positionalSqlBase` is the static
-   * prefix emitters compose the selected column onto. */
-  readonly orderBy?: QueryOrderBy;
-  /** §6 limit knob (`.syql` tier): the trailing `LIMIT ?` bind's clamp. */
-  readonly limit?: QueryLimit;
-  /** positional SQL WITHOUT the dynamic ORDER BY/LIMIT tail; present only
-   * when `orderBy` is (emitters build `base + ORDER BY <baked> + limit
-   * tail`). */
-  readonly positionalSqlBase?: string;
-  /** The positional limit tail (e.g. ` limit min(coalesce(?, 50), 100)` —
-   * the default+clamp live IN the SQL, so runtimes bind `limit ?? null`).
-   * Present only when BOTH knobs are declared (composers need it verbatim). */
-  readonly positionalLimitTail?: string;
-  /** §7 variant-enumeration backend (opt-in `variants` knob): one checked
-   * statement per combination of provided optional groups. Semantically
-   * identical to the neutralization `sql` by construction; the TS emitter
-   * dispatches on provided-ness for perfect index use. `when` lists the
-   * provided group keys; `params` are the DISTINCT param names this variant
-   * binds, positional order. */
-  readonly variants?: readonly {
-    readonly when: readonly string[];
-    readonly sql: string;
-    readonly positionalSql: string;
-    readonly params: readonly string[];
-  }[];
-  /** The optional-group keys, in dispatch-bit order (bit i of the variant
-   * index = group i provided). Present iff `variants` is. */
-  readonly variantGroups?: readonly {
-    readonly key: string;
-    /** Params whose provision defines the group (all must be non-null; a
-     * flag group is "on" when its single param is TRUE). */
-    readonly params: readonly string[];
-    readonly flag: boolean;
-  }[];
+  /** Revision-1 frontend/public-input and physical execution contract. When
+   * present, emitters use this instead of treating `params` as the API. */
+  readonly syql?: QuerySyqlMetadata;
 }
 
 // -- path → name --------------------------------------------------------------
@@ -502,7 +551,7 @@ function parseCommentParams(file: string, raw: string): CommentParam[] {
 
 /** Strip `--` and block comments so identifier scans don't hit commented SQL,
  * and string literals so `':x'` inside a string isn't read as a param. */
-function stripCommentsAndStrings(sql: string): string {
+export function stripCommentsAndStrings(sql: string): string {
   let out = '';
   let i = 0;
   while (i < sql.length) {
@@ -638,7 +687,7 @@ export function toPositionalSql(sql: string): string {
 
 // -- FROM/JOIN table resolution ----------------------------------------------
 
-interface TableRef {
+export interface TableRef {
   readonly table: string;
   /** Alias (or the table name when un-aliased). */
   readonly alias: string;
@@ -668,7 +717,7 @@ const RESERVED_ALIAS = new Set([
   'having',
 ]);
 
-function scanTableRefs(sql: string, ir: IrDocument): TableRef[] {
+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 refs: TableRef[] = [];
@@ -767,6 +816,20 @@ function resolveSource(
   return null;
 }
 
+/** Resolve the one supported query-only protocol column. SQLite still proves
+ * qualifier/ambiguity against the synthesized local tables. */
+function isSyncVersionSource(
+  item: SelectItem,
+  refs: readonly TableRef[],
+): boolean {
+  const match = PLAIN_REF_RE.exec(item.expr);
+  if (match === null || match[2] !== SYNC_VERSION_COLUMN) return false;
+  const qualifier = match[1];
+  return qualifier === undefined
+    ? refs.length === 1
+    : refs.some((ref) => ref.alias === qualifier);
+}
+
 // -- param type inference -----------------------------------------------------
 //
 // Infer a param's type from `col <op> :name` or `col IN (:name, …)` where `col`
@@ -855,6 +918,78 @@ function inferParamType(
   return null;
 }
 
+/**
+ * Return every revision-1 column/LIKE type constraint for one bind. Unlike
+ * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
+ * so conflicting checked uses cannot be silently accepted.
+ */
+export function inferParamTypeEvidence(
+  paramName: string,
+  sql: string,
+  refs: readonly TableRef[],
+  ir: IrDocument,
+): readonly IrColumnType[] {
+  const cleaned = stripCommentsAndStrings(sql);
+  const byName = new Map(
+    ir.tables.map((table) => [table.name, table] as const),
+  );
+  const evidence: IrColumnType[] = [];
+  const add = (qualifier: string | undefined, column: string): void => {
+    if (qualifier !== undefined) {
+      const ref = refs.find((candidate) => candidate.alias === qualifier);
+      const table = ref === undefined ? undefined : byName.get(ref.table);
+      const type = table?.columns.find((item) => item.name === column)?.type;
+      if (type !== undefined) evidence.push(type);
+      return;
+    }
+    const matches = refs.flatMap((ref) => {
+      const table = byName.get(ref.table);
+      const type = table?.columns.find((item) => item.name === column)?.type;
+      return type === undefined ? [] : [type];
+    });
+    if (matches.length === 1) evidence.push(matches[0] as IrColumnType);
+  };
+
+  const comparison = new RegExp(
+    `(?:(${IDENT})\\.)?(${IDENT})\\s*(?:=|==|!=|<>|<=|>=|<|>|\\bLIKE\\b|\\bIS\\b)\\s*:${paramName}\\b`,
+    'gi',
+  );
+  for (const match of cleaned.matchAll(comparison)) {
+    add(match[1], match[2] as string);
+  }
+  const reversed = new RegExp(
+    `:${paramName}\\b\\s*(?:=|==|!=|<>|<=|>=|<|>)\\s*(?:(${IDENT})\\.)?(${IDENT})`,
+    'gi',
+  );
+  for (const match of cleaned.matchAll(reversed)) {
+    add(match[1], match[2] as string);
+  }
+  const inList = new RegExp(
+    `(?:(${IDENT})\\.)?(${IDENT})\\s+IN\\s*\\(([^)]*:${paramName}\\b[^)]*)\\)`,
+    'gi',
+  );
+  for (const match of cleaned.matchAll(inList)) {
+    add(match[1], match[2] as string);
+  }
+  const betweenLeft = new RegExp(
+    `(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`,
+    'gi',
+  );
+  for (const match of cleaned.matchAll(betweenLeft)) {
+    add(match[1], match[2] as string);
+  }
+  const betweenRight = new RegExp(
+    `(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`,
+    'gi',
+  );
+  for (const match of cleaned.matchAll(betweenRight)) {
+    add(match[1], match[2] as string);
+  }
+  const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'gi');
+  if (like.test(cleaned)) evidence.push('string');
+  return evidence;
+}
+
 // -- fallback column typing (computed expressions) ----------------------------
 
 const AGG_RE = /\b(count|sum|total|avg|min|max)\s*\(/i;
@@ -941,11 +1076,7 @@ function inferReactiveMetadata(
           if (!requiredAt(match.index)) continue;
           const name = match[1] ?? match[2];
           const param = name === undefined ? undefined : byParam.get(name);
-          if (
-            param !== undefined &&
-            param.optional !== true &&
-            param.flag !== true
-          ) {
+          if (param !== undefined) {
             found.push(param.name);
           }
         }
@@ -956,11 +1087,7 @@ function inferReactiveMetadata(
             /:([A-Za-z_][A-Za-z0-9_]*)/g,
           )) {
             const param = byParam.get(paramMatch[1] as string);
-            if (
-              param !== undefined &&
-              param.optional !== true &&
-              param.flag !== true
-            ) {
+            if (param !== undefined) {
               found.push(param.name);
             }
           }
@@ -1052,6 +1179,10 @@ export function synthesizeDdl(ir: IrDocument): string {
       const pk = c.name === table.primaryKey ? ' PRIMARY KEY' : '';
       return `  ${c.name} ${SQL_TYPE[c.type]}${pk}${notNull}`;
     });
+    // The materialized local client table always carries this hidden protocol
+    // token. It is absent from IR mutation types but may be explicitly aliased
+    // by a named read query for optimistic concurrency.
+    cols.push(`  ${SYNC_VERSION_COLUMN} INTEGER NOT NULL DEFAULT -1`);
     lines.push(`CREATE TABLE ${table.name} (\n${cols.join(',\n')}\n);`);
     // Create the declared indexes too — harmless for prepare()/decltype, and
     // keeps the type-check DB's shape honest with what the client materializes.
@@ -1175,6 +1306,21 @@ export function analyzeStatement(
     const source = item !== undefined ? resolveSource(item, refs, ir) : null;
     const sqlName = sqlNames[index] ?? colName;
     const langName = langNames[index] ?? colName;
+    if (item !== undefined && isSyncVersionSource(item, refs)) {
+      if (sqlName === SYNC_VERSION_COLUMN) {
+        throw new TypegenError(
+          file,
+          `${SYNC_VERSION_COLUMN} is stripped from app-facing query rows unless explicitly aliased (for example \`${SYNC_VERSION_COLUMN} AS server_version\`)`,
+        );
+      }
+      return {
+        name: sqlName,
+        langName,
+        type: 'integer',
+        nullable: false,
+        fidelity: 'exact',
+      };
+    }
     if (source !== null) {
       // Exact: IR column type + IR nullability. (decltype agrees; we prefer
       // the IR type so blob_ref/crdt/json semantic types survive.)
@@ -1214,16 +1360,20 @@ export function analyzeStatement(
       `internal: scanned ${paramNames.length} params (${paramNames.join(', ')}) but SQLite reports ${described.paramsCount}`,
     );
   }
-  const paramLangNames = buildNamingMap(
-    paramNames,
+  const internalParams = new Set(naming.internalParams ?? []);
+  const publicParamLangNames = buildNamingMap(
+    paramNames.filter((name) => !internalParams.has(name)),
     naming.naming,
     file,
     'params',
     naming.targets,
   );
+  const langNameByParam = new Map(
+    publicParamLangNames.map((mapping) => [mapping.sqlName, mapping.langName]),
+  );
   const commentByName = new Map(commentParams.map((p) => [p.name, p.type]));
-  const params: QueryParam[] = paramNames.map((paramName, index) => {
-    const langName = paramLangNames[index]?.langName ?? paramName;
+  const params: QueryParam[] = paramNames.map((paramName) => {
+    const langName = langNameByParam.get(paramName) ?? paramName;
     const commented = commentByName.get(paramName);
     if (commented !== undefined) {
       return { name: paramName, langName, type: commented, source: 'comment' };