@syncular/typegen 0.6.0 → 0.8.0

package/README.md

@@ -330,8 +330,8 @@ Two frontends feed one QueryIR pipeline. **`.sql`** is plain SQL plus
 `:params`, the compatibility floor documented below. **`.syql`** is the
 revision-1 structured frontend: authoritative typed inputs, explicit
 `when(...)` conjuncts, atomic optional groups, imported hygienic predicates,
-constructive `@scope`/`@cover` facts, complete sort profiles, bounded pages,
-and proven identity. Its complete normative definition is
+inferred scope dependencies, explicit sync coverage, complete sort profiles,
+bounded limits, and inferred identity. Its complete normative definition is
 [`../../docs/SYQL.md`](../../docs/SYQL.md); the rationale and implementation
 record are [`../../docs/rfcs/0004-syql-language.md`](../../docs/rfcs/0004-syql-language.md).
 
@@ -345,43 +345,32 @@ definitions, references, symbols, and formatting. Casing follows the manifest
 ```syql
 import { matchesTitle } from "./predicates.syql";
 
-query listTodos(
+sync query listTodos(
   listId,
   status?: string | null,
-  range?(start: integer, end: integer),
+  range?,
   q?: string,
-  unassigned?: switch,
+  unassigned: bool = false,
 ) {
-  sql {
-    select id, title, status, created_at
-    from todos
-    where @cover(todos.list_id = :listId)
-      and when(status) {
-        status is :status
-      }
-      and when(range) {
-        created_at between :start and :end
-      }
-      and when(unassigned) {
-        assignee_id is null
-      }
-      and when(q) {
-        @matchesTitle(:q)
-      }
+  select id, title, status, created_at
+  from todos
+  where todos.list_id = :listId
+    and when(status) status is :status
+    and when(range) created_at between :range
+    and when(unassigned) assignee_id is null
+    and when(q) matchesTitle(:q)
+  order by sortBy default newest {
+    newest: created_at desc, id desc;
+    oldest: created_at asc, id asc;
   }
-  sort sortBy default newest {
-    newest { created_at desc, id desc }
-    oldest { created_at asc, id asc }
-  }
-  page pageSize default 50 max 200;
-  identity by id;
+  limit pageSize default 50 max 200;
 }
 ```
 
 Optional nullable scalars use a generated presence wrapper so absent,
 present-null, and present-value remain distinct. A group is one optional host
-object whose members are all required. A switch defaults false. Sort is a
-generated enum/union of complete checked profiles; page is validated as a
+object whose members are all required. A `bool = false` flag activates on
+true. Sort is a generated enum/union of complete checked profiles; limit is validated as a
 positive bounded integer before execution. `integer` inputs are exact signed
 64-bit values in the SYQL API (`bigint` in TypeScript, `Int64`/`Long`/`int` on
 native targets).
@@ -459,6 +448,27 @@ boundary):
 | **plain column ref** (`title`, `t.title`, `title AS x`) | resolved to the IR column (decltype confirms) — exact IR type, incl. `json`/`blob_ref`/`crdt` | the IR column's `NOT NULL` | **exact** |
 | **computed expression** (`count(*)`, `done + 1`, `:p AS l`) | decltype is null → documented fallback: aggregate/arithmetic → number, else string | always nullable (an expression's nullability is not knowable from decltype) | **fallback** |
 
+Every local synced table also has the protocol-owned `_sync_version` column.
+Named queries may project it with an explicit public alias when an application
+needs the observed server version for optimistic concurrency:
+
+```syql
+query getTodo(listId, todoId) {
+  select id, title, _sync_version as server_version
+  from todos
+  where todos.list_id = :listId and todos.id = :todoId;
+}
+```
+
+The generated `serverVersion` field is an exact, non-null `integer`. The
+physical name is intentionally not a public result name: project it with an
+alias such as `server_version`. `_sync_version` is query-only, is excluded from
+schema and mutation types, and is not added by `select *`; this prevents client
+code from writing engine-owned concurrency state. Pass a positive observed
+value as a mutation `baseVersion`. Locally-created or still-unacknowledged rows
+can carry a non-positive sentinel and should omit the base version until the
+server assigns one.
+
 `bun:sqlite` exposes `columnNames`, `declaredTypes` (once executed once — we
 run the statement against the empty DB), and `paramsCount`. It does **not**
 expose column origin (table/column), param **names**, or `NOT NULL` flags — so
@@ -502,24 +512,19 @@ identifier and keeping those that name an IR table. This captures subquery /
 prepare() still guarantees the SQL itself is correct.
 
 Inference is deliberately conservative around `OR`, joins, grouping, and
-computed identity. A `.syql` query constructs exact reactive facts in the same
-node that restricts the SQL:
+computed identity. Ordinary scope predicates construct exact reactive facts;
+`sync query` additionally requests checked coverage:
 
 ```syql
-query compareLists(left, right) {
-  sql {
-    select id, title from tasks
-    where @cover(tasks.project_id in (:left, :right))
-  }
-  identity by id;
+sync query compareLists(left, right) {
+  select id, title from tasks
+  where tasks.project_id in (:left, :right);
 }
 ```
 
-`@scope` emits a real predicate plus exact dependency keys. `@cover` emits the
-same dependency facts plus proven window coverage and must bind every declared
-scope of that table instance. Only required, exactly typed binds are allowed.
-`identity by ...` is accepted only when the projected fields are proven unique;
-it is not an unchecked assertion. Without constructive proof the compiler
+Coverage must resolve one table instance and bind every declared scope. Only
+required, non-null, exactly typed binds are allowed. Result identity is inferred
+from schema keys and the projection. Without constructive proof the compiler
 falls back to table-wide dependency, no coverage, and/or unkeyed reconciliation.
 
 **Emitted shape, per language** (one query, five outputs — abbreviated):

package/dist/cli.js

@@ -121,14 +121,11 @@ function runGeneratePrint(args, name) {
                 else if (input.kind === 'group') {
                     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})`);
+                    console.log(`--   ${input.name}: limit 1..${input.maxSize} (default ${input.defaultSize})`);
                 }
             }
         }

package/dist/emit-queries-dart.js

@@ -77,7 +77,7 @@ function syqlDartType(type, nullable) {
 function syqlControlActive(query, name) {
     const input = syqlInput(query, name);
     const access = camelCase(input.langName);
-    if (input.kind === 'switch')
+    if (input.kind === 'value' && input.default === false)
         return access;
     if (input.kind === 'value' && input.nullable)
         return `${access}.isPresent`;
@@ -94,7 +94,7 @@ function syqlBindExpr(query, bind) {
     }
     const input = syqlInput(query, bind.input);
     const access = camelCase(input.langName);
-    if (bind.kind === 'page')
+    if (bind.kind === 'limit')
         return `effective${typeName(access)}`;
     if (bind.kind === 'group-member') {
         if (input.kind !== 'group')
@@ -110,6 +110,8 @@ function syqlBindExpr(query, bind) {
     }
     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)
@@ -157,6 +159,8 @@ function emitSyqlDartRunner(query) {
             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()`);
             }
@@ -166,9 +170,6 @@ function emitSyqlDartRunner(query) {
         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)
                 ?.langName ?? input.defaultProfile;
@@ -181,10 +182,10 @@ function emitSyqlDartRunner(query) {
     }
     const argsClause = args.length > 0 ? `, {${args.join(', ')}}` : '';
     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`)});`, '  }');
+        lines.push(`  final effective${typeName(name)} = ${name} ?? ${page.defaultSize};`, `  if (effective${typeName(name)} < 1 || effective${typeName(name)} > ${page.maxSize}) {`, `    throw SyqlQueryInputException('SYQL_RUNTIME_INVALID_LIMIT', ${quote(`${query.name}: invalid limit`)});`, '  }');
     }
     if (metadata.plan.backend === 'variants') {
         lines.push('  var activationMask = 0;');

package/dist/emit-queries-kotlin.js

@@ -78,7 +78,7 @@ function syqlKotlinType(type, nullable) {
 function syqlControlActive(query, name) {
     const input = syqlInput(query, name);
     const access = camelCase(input.langName);
-    if (input.kind === 'switch')
+    if (input.kind === 'value' && input.default === false)
         return access;
     if (input.kind === 'value' && input.nullable) {
         return `${access} is SyncularQueryPresence.Present`;
@@ -100,7 +100,7 @@ function syqlBindExpr(query, bind) {
     }
     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')
@@ -116,6 +116,8 @@ function syqlBindExpr(query, bind) {
     }
     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)
@@ -163,6 +165,8 @@ function emitSyqlKotlinRunner(query) {
             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`);
             }
@@ -172,9 +176,6 @@ function emitSyqlKotlinRunner(query) {
         else if (input.kind === 'group') {
             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)
                 ?.langName ?? input.defaultProfile;
@@ -186,10 +187,10 @@ function emitSyqlKotlinRunner(query) {
         }
     }
     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`)})`, '            }');
+        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_LIMIT", ${quote(`${query.name}: invalid limit`)})`, '            }');
     }
     if (metadata.plan.backend === 'variants') {
         lines.push('            var activationMask = 0');

package/dist/emit-queries-swift.js

@@ -85,7 +85,7 @@ function syqlSwiftType(type, nullable) {
 function syqlControlActive(query, name) {
     const input = syqlInput(query, name);
     const access = camelCase(input.langName);
-    if (input.kind === 'switch')
+    if (input.kind === 'value' && input.default === false)
         return access;
     if (input.kind === 'value' && input.nullable) {
         return `{ if case .present = ${access} { return true }; return false }()`;
@@ -107,7 +107,7 @@ function syqlBindExpr(query, bind) {
     }
     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')
@@ -123,6 +123,8 @@ function syqlBindExpr(query, bind) {
     }
     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)
@@ -178,6 +180,8 @@ function emitSyqlSwiftRunner(query) {
             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
@@ -186,9 +190,6 @@ function emitSyqlSwiftRunner(query) {
         else if (input.kind === 'group') {
             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)
                 ?.langName ?? input.defaultProfile;
@@ -199,10 +200,10 @@ function emitSyqlSwiftRunner(query) {
         }
     }
     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`)})`, '        }');
+        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_LIMIT", message: ${quote(`${query.name}: invalid limit`)})`, '        }');
     }
     if (metadata.plan.backend === 'variants') {
         lines.push('        var activationMask = 0');

package/dist/emit-queries.js

@@ -32,7 +32,8 @@ function reactiveParam(query, name) {
         const input = query.syql.inputs.find((candidate) => candidate.kind === 'value' && candidate.name === name);
         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)
@@ -72,7 +73,7 @@ function syqlTsTypeCheck(expression, type, nullable) {
 function syqlControlActive(query, control, params) {
     const input = syqlInput(query, control);
     const access = `${params}.${propertyKey(input.langName)}`;
-    if (input.kind === 'switch')
+    if (input.kind === 'value' && input.default === false)
         return `${access} === true`;
     if (input.kind === 'value' || input.kind === 'group') {
         return `${access} !== undefined`;
@@ -87,9 +88,9 @@ function syqlBindExpr(query, bind, params) {
     }
     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') {
@@ -102,6 +103,8 @@ function syqlBindExpr(query, bind, params) {
     }
     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`;
@@ -132,14 +135,11 @@ function emitSyqlValidation(query, Params) {
             }
             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}`)});`);
+            lines.push(`  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}`)});`);
         }
     }
     lines.push('  return params;', '}');
@@ -183,9 +183,6 @@ function emitSyqlQuery(query, hash) {
             else if (input.kind === 'group') {
                 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(' | ')};`);
             }
@@ -382,7 +379,7 @@ export function emitQueriesModule(queries, hash, irVersion) {
             "  | '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/dist/fmt.js

@@ -42,7 +42,7 @@ function templates(file) {
         if (declaration.kind === 'predicate')
             return [declaration.body];
         return [
-            declaration.sql.body,
+            declaration.statement,
             ...(declaration.sort?.profiles.map((profile) => profile.order) ?? []),
         ];
     });
@@ -218,6 +218,8 @@ function formatTokens(parsed) {
     let justClosedImportList = false;
     let seenTopLevel = false;
     let pendingBetween = 0;
+    let inlineParameterRecord = false;
+    let justClosedInlineParameterRecord = false;
     let declarationParameters;
     let awaitsDeclarationParameters = false;
     for (let index = 0; index < tokens.length; index += 1) {
@@ -226,7 +228,11 @@ function formatTokens(parsed) {
         const template = inTemplate(ranges, token);
         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();
@@ -234,8 +240,14 @@ function formatTokens(parsed) {
             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 !== ',') {
             writer.newline();
@@ -271,6 +283,11 @@ function formatTokens(parsed) {
                 writer.write('{', true);
                 importList = true;
             }
+            else if (declarationParameters !== undefined &&
+                previous?.text === ':') {
+                writer.write('{', true);
+                inlineParameterRecord = true;
+            }
             else {
                 writer.openBlock();
                 braceDepth += 1;
@@ -279,7 +296,12 @@ function formatTokens(parsed) {
             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;
@@ -291,6 +313,7 @@ function formatTokens(parsed) {
             previous = token;
             continue;
         }
+        justClosedInlineParameterRecord = false;
         justClosedImportList = false;
         if (token.text === '(') {
             parenDepth += 1;
@@ -308,7 +331,9 @@ function formatTokens(parsed) {
             previous = token;
             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/dist/lsp.js

@@ -78,18 +78,18 @@ function spanRange(text, span) {
 function typeText(type) {
     return type === undefined
         ? 'inferred'
-        : `${type.base}${type.nullable ? ' | null' : ''}`;
+        : `${type.base === 'boolean' ? 'bool' : type.base}${type.nullable ? ' | null' : ''}`;
 }
 function parameterHover(parameter) {
-    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 {
     #documents = new Map();
@@ -333,22 +333,10 @@ export class SyqlLanguageServer {
         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',
@@ -382,11 +370,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}`,
                     },
                 };
             }
@@ -418,11 +406,11 @@ export class SyqlLanguageServer {
     }
     #definition(params) {
         const request = this.#request(params);
-        if (request === null || !request.found.word.startsWith('@'))
+        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;
@@ -433,20 +421,20 @@ export class SyqlLanguageServer {
     }
     #references(params) {
         const request = this.#request(params);
-        if (request === null || !request.found.word.startsWith('@'))
+        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 = [];
         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')
+                if (token.kind !== 'identifier')
                     continue;
-                const resolved = scope?.get(token.text.slice(1));
+                const resolved = scope?.get(token.text);
                 if (resolved?.id !== target.id)
                     continue;
                 locations.push({

package/dist/query.d.ts

@@ -67,9 +67,8 @@ export interface QueryNamingOptions {
      * not participate in public target-language keyword/private-name checks. */
     readonly internalParams?: readonly string[];
 }
-/** 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';
     readonly name: string;
@@ -77,6 +76,7 @@ export type QuerySyqlPublicInput = {
     readonly type: QueryParamType;
     readonly nullable: boolean;
     readonly required: boolean;
+    readonly default?: false;
 } | {
     readonly kind: 'group';
     readonly name: string;
@@ -87,11 +87,6 @@ export type QuerySyqlPublicInput = {
         readonly type: QueryParamType;
         readonly nullable: boolean;
     }[];
-} | {
-    readonly kind: 'switch';
-    readonly name: string;
-    readonly langName: string;
-    readonly default: false;
 } | {
     readonly kind: 'sort';
     readonly name: string;
@@ -102,7 +97,7 @@ export type QuerySyqlPublicInput = {
         readonly langName: string;
     }[];
 } | {
-    readonly kind: 'page';
+    readonly kind: 'limit';
     readonly name: string;
     readonly langName: string;
     readonly defaultSize: number;
@@ -127,7 +122,7 @@ export type QuerySyqlPlanBind = {
     readonly condition: number;
     readonly controls: readonly string[];
 } | {
-    readonly kind: 'page';
+    readonly kind: 'limit';
     readonly name: string;
     readonly type: 'integer';
     readonly input: string;
@@ -144,7 +139,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[];