@syncular/typegen 0.6.0 → 0.8.0

package/package.json

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

package/src/cli.ts

@@ -131,15 +131,13 @@ function runGeneratePrint(args: GenerateArgs, name: string): void {
           console.log(
             `--   ${input.name}: optional group (${input.members.map((member) => `${member.name}: ${member.type}${member.nullable ? ' | null' : ''}`).join(', ')})`,
           );
-        } else if (input.kind === 'switch') {
-          console.log(`--   ${input.name}: switch (default false)`);
         } else if (input.kind === 'sort') {
           console.log(
             `--   ${input.name}: sort [${input.profiles.map((profile) => profile.name).join(', ')}] (default ${input.defaultProfile})`,
           );
         } else {
           console.log(
-            `--   ${input.name}: page 1..${input.maxSize} (default ${input.defaultSize})`,
+            `--   ${input.name}: limit 1..${input.maxSize} (default ${input.defaultSize})`,
           );
         }
       }

package/src/emit-queries-dart.ts

@@ -103,7 +103,7 @@ function syqlDartType(type: IrColumnType, nullable: boolean): string {
 function syqlControlActive(query: AnalyzedQuery, name: string): string {
   const input = syqlInput(query, name);
   const access = camelCase(input.langName);
-  if (input.kind === 'switch') return access;
+  if (input.kind === 'value' && input.default === false) return access;
   if (input.kind === 'value' && input.nullable) return `${access}.isPresent`;
   if (input.kind === 'value' || input.kind === 'group') {
     return `${access} != null`;
@@ -119,7 +119,7 @@ function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
   }
   const input = syqlInput(query, bind.input);
   const access = camelCase(input.langName);
-  if (bind.kind === 'page') return `effective${typeName(access)}`;
+  if (bind.kind === 'limit') return `effective${typeName(access)}`;
   if (bind.kind === 'group-member') {
     if (input.kind !== 'group') throw new Error('group bind/input mismatch');
     const member = input.members.find(
@@ -134,6 +134,7 @@ function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
     return `${access} == null ? null : ${value}`;
   }
   if (input.kind !== 'value') throw new Error('value bind/input mismatch');
+  if (input.default === false) return paramValue(input.type, access);
   if (input.required) {
     return input.nullable
       ? optionalParamValue(input.type, access)
@@ -189,6 +190,7 @@ function emitSyqlDartRunner(query: AnalyzedQuery): string[] {
     if (input.kind === 'value') {
       const type = syqlDartType(input.type, input.nullable);
       if (input.required) args.push(`required ${type} ${name}`);
+      else if (input.default === false) args.push(`bool ${name} = false`);
       else if (input.nullable) {
         args.push(
           `SyqlQueryPresence<${type}> ${name} = const SyqlQueryPresence.absent()`,
@@ -196,8 +198,6 @@ function emitSyqlDartRunner(query: AnalyzedQuery): string[] {
       } else args.push(`${type}? ${name}`);
     } else if (input.kind === 'group') {
       args.push(`${typeName(query.name)}${typeName(input.langName)}? ${name}`);
-    } else if (input.kind === 'switch') {
-      args.push(`bool ${name} = false`);
     } else if (input.kind === 'sort') {
       const defaultCase =
         input.profiles.find((profile) => profile.name === input.defaultProfile)
@@ -212,13 +212,13 @@ function emitSyqlDartRunner(query: AnalyzedQuery): string[] {
   lines.push(
     `List<${Row}> syncular${Pascal}Query(SyncularClient client${argsClause}) {`,
   );
-  const page = metadata.inputs.find((input) => input.kind === 'page');
-  if (page?.kind === 'page') {
+  const page = metadata.inputs.find((input) => input.kind === 'limit');
+  if (page?.kind === 'limit') {
     const name = camelCase(page.langName);
     lines.push(
       `  final effective${typeName(name)} = ${name} ?? ${page.defaultSize};`,
       `  if (effective${typeName(name)} < 1 || effective${typeName(name)} > ${page.maxSize}) {`,
-      `    throw SyqlQueryInputException('SYQL_RUNTIME_INVALID_PAGE', ${quote(`${query.name}: invalid page size`)});`,
+      `    throw SyqlQueryInputException('SYQL_RUNTIME_INVALID_LIMIT', ${quote(`${query.name}: invalid limit`)});`,
       '  }',
     );
   }

package/src/emit-queries-kotlin.ts

@@ -107,7 +107,7 @@ function syqlKotlinType(type: IrColumnType, nullable: boolean): string {
 function syqlControlActive(query: AnalyzedQuery, name: string): string {
   const input = syqlInput(query, name);
   const access = camelCase(input.langName);
-  if (input.kind === 'switch') return access;
+  if (input.kind === 'value' && input.default === false) return access;
   if (input.kind === 'value' && input.nullable) {
     return `${access} is SyncularQueryPresence.Present`;
   }
@@ -130,7 +130,7 @@ function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
   }
   const input = syqlInput(query, bind.input);
   const access = camelCase(input.langName);
-  if (bind.kind === 'page')
+  if (bind.kind === 'limit')
     return `JsonValue.of(effective${typeName(access)}.toDouble())`;
   if (bind.kind === 'group-member') {
     if (input.kind !== 'group') throw new Error('group bind/input mismatch');
@@ -146,6 +146,7 @@ function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
     return `${access}?.let { value -> ${present} } ?: JsonValue.Null`;
   }
   if (input.kind !== 'value') throw new Error('value bind/input mismatch');
+  if (input.default === false) return paramValue(input.type, access);
   if (input.required) {
     return input.nullable
       ? optionalParamValue(input.type, access)
@@ -201,6 +202,7 @@ function emitSyqlKotlinRunner(query: AnalyzedQuery): string[] {
     if (input.kind === 'value') {
       const type = syqlKotlinType(input.type, input.nullable);
       if (input.required) args.push(`${name}: ${type}`);
+      else if (input.default === false) args.push(`${name}: Boolean = false`);
       else if (input.nullable) {
         args.push(
           `${name}: SyncularQueryPresence<${type}> = SyncularQueryPresence.Absent`,
@@ -210,8 +212,6 @@ function emitSyqlKotlinRunner(query: AnalyzedQuery): string[] {
       args.push(
         `${name}: ${typeName(query.name)}${typeName(input.langName)}? = null`,
       );
-    } else if (input.kind === 'switch') {
-      args.push(`${name}: Boolean = false`);
     } else if (input.kind === 'sort') {
       const defaultCase =
         input.profiles.find((profile) => profile.name === input.defaultProfile)
@@ -223,13 +223,13 @@ function emitSyqlKotlinRunner(query: AnalyzedQuery): string[] {
     }
   }
   lines.push(`        fun ${query.name}(${args.join(', ')}): List<${Row}> {`);
-  const page = metadata.inputs.find((input) => input.kind === 'page');
-  if (page?.kind === 'page') {
+  const page = metadata.inputs.find((input) => input.kind === 'limit');
+  if (page?.kind === 'limit') {
     const name = camelCase(page.langName);
     lines.push(
       `            val effective${typeName(name)} = ${name} ?: ${page.defaultSize}L`,
       `            if (effective${typeName(name)} < 1L || effective${typeName(name)} > ${page.maxSize}L) {`,
-      `                throw SyncularQueryInputException("SYQL_RUNTIME_INVALID_PAGE", ${quote(`${query.name}: invalid page size`)})`,
+      `                throw SyncularQueryInputException("SYQL_RUNTIME_INVALID_LIMIT", ${quote(`${query.name}: invalid limit`)})`,
       '            }',
     );
   }

package/src/emit-queries-swift.ts

@@ -115,7 +115,7 @@ function syqlSwiftType(type: IrColumnType, nullable: boolean): string {
 function syqlControlActive(query: AnalyzedQuery, name: string): string {
   const input = syqlInput(query, name);
   const access = camelCase(input.langName);
-  if (input.kind === 'switch') return access;
+  if (input.kind === 'value' && input.default === false) return access;
   if (input.kind === 'value' && input.nullable) {
     return `{ if case .present = ${access} { return true }; return false }()`;
   }
@@ -138,7 +138,7 @@ function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
   }
   const input = syqlInput(query, bind.input);
   const access = camelCase(input.langName);
-  if (bind.kind === 'page')
+  if (bind.kind === 'limit')
     return `.number(Double(effective${typeName(access)}))`;
   if (bind.kind === 'group-member') {
     if (input.kind !== 'group') throw new Error('group bind/input mismatch');
@@ -154,6 +154,7 @@ function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
     return `${access}.map { value in ${present} } ?? .null`;
   }
   if (input.kind !== 'value') throw new Error('value bind/input mismatch');
+  if (input.default === false) return paramValue(input.type, access);
   if (input.required) {
     return input.nullable
       ? optionalParamValue(input.type, access)
@@ -216,6 +217,7 @@ function emitSyqlSwiftRunner(query: AnalyzedQuery): string[] {
     if (input.kind === 'value') {
       const type = syqlSwiftType(input.type, input.nullable);
       if (input.required) args.push(`${name}: ${type}`);
+      else if (input.default === false) args.push(`${name}: Bool = false`);
       else if (input.nullable)
         args.push(`${name}: SyncularQueryPresence<${type}> = .absent`);
       else args.push(`${name}: ${type}? = nil`);
@@ -223,8 +225,6 @@ function emitSyqlSwiftRunner(query: AnalyzedQuery): string[] {
       args.push(
         `${name}: ${typeName(query.name)}${typeName(input.langName)}? = nil`,
       );
-    } else if (input.kind === 'switch') {
-      args.push(`${name}: Bool = false`);
     } else if (input.kind === 'sort') {
       const defaultCase =
         input.profiles.find((profile) => profile.name === input.defaultProfile)
@@ -239,13 +239,13 @@ function emitSyqlSwiftRunner(query: AnalyzedQuery): string[] {
   lines.push(
     `    public static func ${query.name}(${args.join(', ')}) throws -> [${Row}] {`,
   );
-  const page = metadata.inputs.find((input) => input.kind === 'page');
-  if (page?.kind === 'page') {
+  const page = metadata.inputs.find((input) => input.kind === 'limit');
+  if (page?.kind === 'limit') {
     const name = camelCase(page.langName);
     lines.push(
       `        let effective${typeName(name)} = ${name} ?? ${page.defaultSize}`,
       `        guard effective${typeName(name)} >= 1 && effective${typeName(name)} <= ${page.maxSize} else {`,
-      `            throw SyncularQueryInputError(code: "SYQL_RUNTIME_INVALID_PAGE", message: ${quote(`${query.name}: invalid page size`)})`,
+      `            throw SyncularQueryInputError(code: "SYQL_RUNTIME_INVALID_LIMIT", message: ${quote(`${query.name}: invalid limit`)})`,
       '        }',
     );
   }

package/src/emit-queries.ts

@@ -67,7 +67,8 @@ function reactiveParam(query: AnalyzedQuery, name: string): string {
     );
     if (input?.kind !== 'value')
       throw new Error(`unknown reactive input ${name}`);
-    return `String(params.${propertyKey(input.langName)})`;
+    const access = `params.${propertyKey(input.langName)}`;
+    return `String(${input.default === false ? `${access} ?? false` : access})`;
   }
   const param = query.params.find((candidate) => candidate.name === name);
   if (param === undefined) throw new Error(`unknown reactive param ${name}`);
@@ -117,7 +118,8 @@ function syqlControlActive(
 ): string {
   const input = syqlInput(query, control);
   const access = `${params}.${propertyKey(input.langName)}`;
-  if (input.kind === 'switch') return `${access} === true`;
+  if (input.kind === 'value' && input.default === false)
+    return `${access} === true`;
   if (input.kind === 'value' || input.kind === 'group') {
     return `${access} !== undefined`;
   }
@@ -136,8 +138,8 @@ function syqlBindExpr(
   }
   const input = syqlInput(query, bind.input);
   const access = `${params}.${propertyKey(input.langName)}`;
-  if (bind.kind === 'page') {
-    if (input.kind !== 'page') throw new Error('page bind/input mismatch');
+  if (bind.kind === 'limit') {
+    if (input.kind !== 'limit') throw new Error('limit bind/input mismatch');
     return `${access} ?? ${input.defaultSize}`;
   }
   if (bind.kind === 'group-member') {
@@ -150,6 +152,7 @@ function syqlBindExpr(
     return `${access}?.${propertyKey(member.langName)} ?? null`;
   }
   if (input.kind !== 'value') throw new Error('value bind/input mismatch');
+  if (input.default === false) return `${access} ?? false`;
   if (input.required) return access;
   return input.nullable ? `${access}?.value ?? null` : `${access} ?? null`;
 }
@@ -197,17 +200,13 @@ function emitSyqlValidation(query: AnalyzedQuery, Params: string): string[] {
         );
       }
       lines.push('  }');
-    } else if (input.kind === 'switch') {
-      lines.push(
-        `  if (${access} !== undefined && typeof ${access} !== 'boolean') throw new SyqlInputError('SYQL_RUNTIME_INVALID_INPUT', ${quote(`${query.name}: invalid switch ${input.name}`)});`,
-      );
     } else if (input.kind === 'sort') {
       lines.push(
         `  if (${access} !== undefined && ![${input.profiles.map((profile) => quote(profile.langName)).join(', ')}].includes(${access})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_SORT', ${quote(`${query.name}: invalid sort profile`)});`,
       );
     } else {
       lines.push(
-        `  if (${access} !== undefined && (!Number.isSafeInteger(${access}) || ${access} < 1 || ${access} > ${input.maxSize})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_PAGE', ${quote(`${query.name}: page size must be an integer from 1 through ${input.maxSize}`)});`,
+        `  if (${access} !== undefined && (!Number.isSafeInteger(${access}) || ${access} < 1 || ${access} > ${input.maxSize})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_LIMIT', ${quote(`${query.name}: limit must be an integer from 1 through ${input.maxSize}`)});`,
       );
     }
   }
@@ -267,8 +266,6 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
         lines.push(
           `  ${key}?: ${pascalCase(query.name)}${pascalCase(input.langName)};`,
         );
-      } else if (input.kind === 'switch') {
-        lines.push(`  ${key}?: boolean;`);
       } else if (input.kind === 'sort') {
         lines.push(
           `  ${key}?: ${input.profiles.map((profile) => quote(profile.langName)).join(' | ')};`,
@@ -580,7 +577,7 @@ export function emitQueriesModule(
         "  | 'SYQL_RUNTIME_INVALID_INPUT'",
         "  | 'SYQL_RUNTIME_INVALID_GROUP'",
         "  | 'SYQL_RUNTIME_INVALID_SORT'",
-        "  | 'SYQL_RUNTIME_INVALID_PAGE';",
+        "  | 'SYQL_RUNTIME_INVALID_LIMIT';",
         '',
         'export class SyqlInputError extends Error {',
         "  readonly name = 'SyqlInputError';",

package/src/fmt.ts

@@ -53,7 +53,7 @@ function templates(file: SyqlSyntaxFile): readonly SyqlTemplate[] {
   return file.declarations.flatMap((declaration) => {
     if (declaration.kind === 'predicate') return [declaration.body];
     return [
-      declaration.sql.body,
+      declaration.statement,
       ...(declaration.sort?.profiles.map((profile) => profile.order) ?? []),
     ];
   });
@@ -268,6 +268,8 @@ function formatTokens(parsed: SyqlSyntaxFile): string {
   let justClosedImportList = false;
   let seenTopLevel = false;
   let pendingBetween = 0;
+  let inlineParameterRecord = false;
+  let justClosedInlineParameterRecord = false;
 
   let declarationParameters: DeclarationParameters | undefined;
   let awaitsDeclarationParameters = false;
@@ -279,15 +281,26 @@ function formatTokens(parsed: SyqlSyntaxFile): string {
     const topLevelDeclaration =
       braceDepth === 0 &&
       token.kind === 'identifier' &&
-      (lower === 'import' || lower === 'predicate' || lower === 'query');
+      (lower === 'import' ||
+        lower === 'predicate' ||
+        lower === 'query' ||
+        lower === 'sync') &&
+      !(lower === 'query' && previous?.text === 'sync');
     if (topLevelDeclaration) {
       if (seenTopLevel) writer.blankline();
       seenTopLevel = true;
       previous = undefined;
       awaitsDeclarationParameters = lower === 'predicate' || lower === 'query';
+    } else if (
+      braceDepth === 0 &&
+      lower === 'query' &&
+      previous?.text === 'sync'
+    ) {
+      awaitsDeclarationParameters = true;
     } else if (
       previous?.text === '}' &&
       !justClosedImportList &&
+      !justClosedInlineParameterRecord &&
       token.text !== ';' &&
       token.text !== ','
     ) {
@@ -326,6 +339,12 @@ function formatTokens(parsed: SyqlSyntaxFile): string {
       if (previous?.kind === 'identifier' && previous.text === 'import') {
         writer.write('{', true);
         importList = true;
+      } else if (
+        declarationParameters !== undefined &&
+        previous?.text === ':'
+      ) {
+        writer.write('{', true);
+        inlineParameterRecord = true;
       } else {
         writer.openBlock();
         braceDepth += 1;
@@ -334,7 +353,11 @@ function formatTokens(parsed: SyqlSyntaxFile): string {
       continue;
     }
     if (token.text === '}') {
-      if (importList && braceDepth === 0) {
+      if (inlineParameterRecord) {
+        writer.write('}', true);
+        inlineParameterRecord = false;
+        justClosedInlineParameterRecord = true;
+      } else if (importList && braceDepth === 0) {
         writer.write('}', true);
         importList = false;
         justClosedImportList = true;
@@ -345,6 +368,7 @@ function formatTokens(parsed: SyqlSyntaxFile): string {
       previous = token;
       continue;
     }
+    justClosedInlineParameterRecord = false;
     justClosedImportList = false;
 
     if (token.text === '(') {
@@ -365,7 +389,11 @@ function formatTokens(parsed: SyqlSyntaxFile): string {
       continue;
     }
 
-    if (token.text === ',' && declarationParameters?.depth === parenDepth) {
+    if (
+      token.text === ',' &&
+      declarationParameters?.depth === parenDepth &&
+      !inlineParameterRecord
+    ) {
       const next = tokens[index + 1];
       if (!(declarationParameters.multiline === false && next?.text === ')')) {
         writer.write(',', false);

package/src/lsp.ts

@@ -148,19 +148,19 @@ function spanRange(text: string, span: SyqlSourceSpan): Range {
 function typeText(type: SyqlValueType | undefined): string {
   return type === undefined
     ? 'inferred'
-    : `${type.base}${type.nullable ? ' | null' : ''}`;
+    : `${type.base === 'boolean' ? 'bool' : type.base}${type.nullable ? ' | null' : ''}`;
 }
 
 function parameterHover(parameter: SyqlQueryParameter): string {
-  if (parameter.kind === 'switch') {
-    return `switch \`${parameter.name}\` — false/absent or true`;
+  if (parameter.kind === 'range') {
+    return `${parameter.optional ? 'optional' : 'required'} inclusive range \`${parameter.name}: range<${typeText(parameter.type)}>\``;
   }
   if (parameter.kind === 'group') {
     return `optional group \`${parameter.name}\`\n\n${parameter.members
       .map((member) => `- \`${member.name}: ${typeText(member.type)}\``)
       .join('\n')}`;
   }
-  return `${parameter.optional ? 'optional' : 'required'} input \`${parameter.name}: ${typeText(parameter.type)}\``;
+  return `${parameter.optional ? 'optional' : parameter.default === false ? 'default-false' : 'required'} input \`${parameter.name}: ${typeText(parameter.type)}\``;
 }
 
 export class SyqlLanguageServer {
@@ -432,22 +432,10 @@ export class SyqlLanguageServer {
     const request = this.#request(params);
     if (request === null) return null;
     const { found, view, offset } = request;
-    if (found.word === '@scope' || found.word === '@cover') {
-      return {
-        contents: {
-          kind: 'markdown',
-          value:
-            found.word === '@scope'
-              ? '`@scope` constructs exact reactive dependency keys and the same SQL predicate.'
-              : '`@cover` constructs exact dependencies plus checked window coverage.',
-        },
-      };
-    }
-    if (found.word.startsWith('@')) {
-      const predicate = view.semantic.predicateScopes
-        .get(view.file)
-        ?.get(found.word.slice(1));
-      if (predicate === undefined) return null;
+    const predicate = view.semantic.predicateScopes
+      .get(view.file)
+      ?.get(found.word);
+    if (predicate !== undefined) {
       return {
         contents: {
           kind: 'markdown',
@@ -488,11 +476,11 @@ export class SyqlLanguageServer {
           },
         };
       }
-      if (query.page?.control === found.word) {
+      if (query.limit?.control === found.word) {
         return {
           contents: {
             kind: 'markdown',
-            value: `page control \`${found.word}\`: default ${query.page.defaultSize}, maximum ${query.page.maxSize}`,
+            value: `limit control \`${found.word}\`: default ${query.limit.defaultSize}, maximum ${query.limit.maxSize}`,
           },
         };
       }
@@ -529,10 +517,10 @@ export class SyqlLanguageServer {
 
   #definition(params: unknown): unknown {
     const request = this.#request(params);
-    if (request === null || !request.found.word.startsWith('@')) return null;
+    if (request === null) return null;
     const predicate = request.view.semantic.predicateScopes
       .get(request.view.file)
-      ?.get(request.found.word.slice(1));
+      ?.get(request.found.word);
     if (predicate === undefined) return null;
     const text =
       this.#openText(predicate.module.file) ?? predicate.module.source;
@@ -544,17 +532,17 @@ export class SyqlLanguageServer {
 
   #references(params: unknown): unknown {
     const request = this.#request(params);
-    if (request === null || !request.found.word.startsWith('@')) return [];
+    if (request === null) return [];
     const target = request.view.semantic.predicateScopes
       .get(request.view.file)
-      ?.get(request.found.word.slice(1));
+      ?.get(request.found.word);
     if (target === undefined) return [];
     const locations: unknown[] = [];
     for (const module of request.view.semantic.graph.modules) {
       const scope = request.view.semantic.predicateScopes.get(module.file);
       for (const token of module.tokens) {
-        if (token.kind !== 'at-identifier') continue;
-        const resolved = scope?.get(token.text.slice(1));
+        if (token.kind !== 'identifier') continue;
+        const resolved = scope?.get(token.text);
         if (resolved?.id !== target.id) continue;
         locations.push({
           uri: pathToFileURL(module.file).href,

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;
 
@@ -161,9 +164,8 @@ export interface QueryNamingOptions {
 
 const DEFAULT_NAMING: QueryNamingOptions = { naming: 'camel', targets: ['ts'] };
 
-/** Revision-1 SYQL public inputs. These are deliberately separate from SQL
- * binds: groups and switches are public values without corresponding SQLite
- * parameters, while compiler-generated parameters are never public. */
+/** 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';
@@ -172,6 +174,7 @@ export type QuerySyqlPublicInput =
       readonly type: QueryParamType;
       readonly nullable: boolean;
       readonly required: boolean;
+      readonly default?: false;
     }
   | {
       readonly kind: 'group';
@@ -184,12 +187,6 @@ export type QuerySyqlPublicInput =
         readonly nullable: boolean;
       }[];
     }
-  | {
-      readonly kind: 'switch';
-      readonly name: string;
-      readonly langName: string;
-      readonly default: false;
-    }
   | {
       readonly kind: 'sort';
       readonly name: string;
@@ -201,7 +198,7 @@ export type QuerySyqlPublicInput =
       }[];
     }
   | {
-      readonly kind: 'page';
+      readonly kind: 'limit';
       readonly name: string;
       readonly langName: string;
       readonly defaultSize: number;
@@ -231,7 +228,7 @@ export type QuerySyqlPlanBind =
       readonly controls: readonly string[];
     }
   | {
-      readonly kind: 'page';
+      readonly kind: 'limit';
       readonly name: string;
       readonly type: 'integer';
       readonly input: string;
@@ -250,7 +247,7 @@ export interface QuerySyqlStatement {
 /** The target-neutral physical plan every emitter must implement exactly. */
 export interface QuerySyqlExecutionPlan {
   readonly backend: Exclude<QueryBackend, 'auto'>;
-  /** One bit per optional scalar/group/switch, in declaration order. */
+  /** One bit per conditional activation control, in declaration order. */
   readonly activationControls: readonly string[];
   readonly conditions: readonly {
     readonly controls: readonly string[];
@@ -819,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`
@@ -1168,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.
@@ -1291,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.)