@query-graph/core 1.1.5 → 1.1.7

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2020 N-API for Rust
+Copyright (c) 2026 Viktor Marichev
+Copyright (c) 2020 N-API for Rust contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,6 +17,7 @@
 - выбор JOIN только для реально запрошенных полей и условий;
 - scalar и list parameters без подстановки значений в SQL;
 - <code>exists</code>, <code>firstBy</code>, nullable projection objects и именованные ordering;
+- вычисляемые проекции с переносимыми строковыми и числовыми функциями;
 - summary-графы с dimensions, measures, <code>GROUP BY</code> и <code>HAVING</code>;
 - batch relations для загрузки коллекций после пагинации root;
 - один семантический definition для SQL Server и Oracle.
@@ -38,8 +39,8 @@ npm install @query-graph/core
 
 ```ts
 import { registerDefinition } from '@query-graph/core'
-import { constraint, defineGraph, eq, param, project, requiredParameter, source } from '@query-graph/core/dsl'
-import type { QueryOperation, ResultOf } from '@query-graph/core/dsl'
+import { constraint, defineGraph, eq, project, requiredParam, source } from '@query-graph/core/dsl'
+import type { ResultOf } from '@query-graph/core/dsl'
 
 const users = source('users', {
   id: 'int64',
@@ -47,7 +48,7 @@ const users = source('users', {
   email: 'string',
 })
 
-const organisationId = requiredParameter('organisationId', 'int64')
+const organisationId = requiredParam('organisationId', 'int64')
 
 const usersDefinition = defineGraph({
   name: 'users',
@@ -56,7 +57,7 @@ const usersDefinition = defineGraph({
   parameters: [organisationId],
   constraints: [
     constraint({
-      predicate: eq(users.field('organisationId'), param(organisationId)),
+      predicate: eq(users.field('organisationId'), organisationId),
     }),
   ],
   projection: [
@@ -76,13 +77,8 @@ const usersGraph = registerDefinition(usersDefinition).withRelationalMapping({
   },
 })
 
-const operation = {
-  select: ['id', 'email'],
-  parameters: { organisationId: 42 },
-} as const satisfies QueryOperation<typeof usersDefinition>
-
-const statement = usersGraph.compileSqlServer(operation, { version: '2022' })
-type UserRow = ResultOf<typeof usersDefinition, typeof operation>
+const statement = usersGraph.compileSqlServer({ parameters: { organisationId: 42 } }, { version: '2022' })
+type UserRow = ResultOf<typeof usersDefinition>
 ```
 
 <code>statement</code> содержит:
@@ -95,16 +91,108 @@ type UserRow = ResultOf<typeof usersDefinition, typeof operation>
 | <code>objects</code>   | presence metadata для nullable вложенных объектов                                 |
 | <code>relations</code> | связи, выбранные planner для этой operation                                       |
 
-Executor берет значения из <code>operation.parameters</code> по
+Executor берет значения из <code>parameters</code> переданной operation по
 <code>bindings</code>, вызывает DB driver и восстанавливает объект по
 <code>columns</code> и <code>objects</code>. Разбирать SQL не нужно.
 
 Тот же mapped graph можно скомпилировать в Oracle:
 
 ```ts
-const oracleStatement = usersGraph.compileOracle(operation, { version: '19c' })
+const oracleStatement = usersGraph.compileOracle({ parameters: { organisationId: 42 } }, { version: '19c' })
+```
+
+## Зачем нужен planner
+
+В реальном графе преимущество проявляется, когда одна definition обслуживает
+разные формы результата:
+
+```text
+orders
+|-- customer
+|   `-- organisation
+|-- latestPayment [firstBy]
+`-- items [batch many]
+
+constraints: organisationId, exists(activePromotion)
+```
+
+<code>ordersDefinition</code> содержит показанные на схеме relations и
+projection. Его небанальные части выглядят так:
+
+```ts
+const latestPayment = relation({
+  name: 'latestPayment',
+  from: orders,
+  to: payments,
+  on: eq(orders.field('id'), payments.field('orderId')),
+  selection: firstBy(desc(payments.field('createdAt'))),
+})
+
+const hasActivePromotion = constraint({
+  predicate: exists(promotions, eq(promotions.field('active'), true)),
+})
+
+const ordersDefinition = defineGraph({
+  name: 'orders',
+  root: orders,
+  sources: [orders, customers, organisations, payments, promotions],
+  parameters: [organisationId],
+  relations: [customer, customerOrganisation, latestPayment, activePromotion],
+  constraints: [byOrganisation, hasActivePromotion],
+  objects: [customerObject, latestPaymentObject],
+  projection: [orderId, customerName, customerOrganisationName, latestPaymentAmount],
+})
+
+const items = batchRelation({
+  name: 'items',
+  from: 'id',
+  query: batchQuery({
+    graph: orderItemsGraph,
+    key: { path: 'orderId', parameter: orderIds },
+  }),
+  cardinality: 'many',
+})
+
+const mappedOrders = registerDefinition(ordersDefinition).withRelationalMapping(orderMapping)
+const ordersGraph = composeGraph({ root: mappedOrders, relations: [items] })
+```
+
+Обычные source и projection declarations здесь свернуты в именованные
+константы. <code>customerObject</code> и <code>latestPaymentObject</code> созданы
+через <code>projectObject</code>, поэтому отсутствующая to-one строка становится
+<code>null</code>.
+
+Одна и та же definition теперь обслуживает дешевый список:
+
+```ts
+const listPlan = ordersGraph.compileSqlServerPlan({
+  select: ['id'],
+  parameters: { organisationId: 42 },
+})
+
+listPlan.root.relations // []
+listPlan.batches // []
+```
+
+И подробное представление:
+
+```ts
+const detailsPlan = ordersGraph.compileSqlServerPlan({
+  select: ['id', 'customer.name', 'latestPayment.amount', 'items.name'],
+  parameters: { organisationId: 42 },
+})
+
+detailsPlan.root.relations.map(({ name }) => name)
+// ['customer', 'latestPayment']
+
+detailsPlan.batches.map(({ name }) => name)
+// ['items']
 ```
 
+Planner не добавляет невыбранную <code>customerOrganisation</code>,
+<code>exists(activePromotion)</code> остается semijoin без размножения root-строк,
+а <code>items</code> загружается одним batch-запросом для всех найденных orders.
+
 ## Модель
 
 ```text
@@ -160,9 +248,9 @@ import { defineGraph, relation, project } from '@query-graph/core/dsl'
 ```
 
 <code>@query-graph/core/definition</code> сохраняет позиционные фабрики только
-для совместимости линии 1.2.x. <code>@query-graph/dsl-object</code> остается
-тонким deprecated facade над <code>@query-graph/core/dsl</code>. Новому коду эти
-entrypoint не нужны.
+для обратной совместимости с ранним API 1.x.
+<code>@query-graph/dsl-object</code> остается тонким deprecated facade над
+<code>@query-graph/core/dsl</code>. Новому коду эти entrypoint не нужны.
 
 Batch-фабрики временно доступны из package root, но новый код должен импортировать
 их из <code>@query-graph/core/dsl</code>.
@@ -177,7 +265,3 @@ JavaScript.
 SQL execution намеренно остается у потребителя. Это позволяет использовать
 любой pool, transaction model, tracing и политику retry, не связывая planner с
 конкретным DB driver.
-
-### Rule 34
-
-Every sufficiently generic abstraction eventually gets an implementation.

package/definition.d.ts

@@ -30,7 +30,7 @@ import type {
 } from './dsl.js'
 
 /** @deprecated Import authoring primitives from `@query-graph/core/dsl`. */
-export const GRAPH_DEFINITION_VERSION: 10
+export const GRAPH_DEFINITION_VERSION: 12
 
 /** @deprecated Use `source.field(name)` from `@query-graph/core/dsl`. */
 export function field<

package/definition.js

@@ -65,13 +65,22 @@ exports.hidden = objectDsl.hidden
 exports.source = objectDsl.source
 exports.field = field
 exports.requiredParameter = objectDsl.requiredParameter
+exports.requiredParam = objectDsl.requiredParam
 exports.optionalParameter = objectDsl.optionalParameter
+exports.optionalParam = objectDsl.optionalParam
 exports.param = objectDsl.param
 exports.literal = objectDsl.literal
 exports.integer = objectDsl.integer
 exports.decimal = objectDsl.decimal
 exports.requiredListParameter = objectDsl.requiredListParameter
+exports.requiredListParam = objectDsl.requiredListParam
 exports.optionalListParameter = objectDsl.optionalListParameter
+exports.optionalListParam = objectDsl.optionalListParam
+exports.requiredGroupsParameter = objectDsl.requiredGroupsParameter
+exports.requiredGroupsParam = objectDsl.requiredGroupsParam
+exports.optionalGroupsParameter = objectDsl.optionalGroupsParameter
+exports.optionalGroupsParam = objectDsl.optionalGroupsParam
+exports.allGroups = objectDsl.allGroups
 exports.eq = objectDsl.eq
 exports.neq = objectDsl.neq
 exports.lt = objectDsl.lt
@@ -86,11 +95,15 @@ exports.not = objectDsl.not
 exports.isNull = objectDsl.isNull
 exports.isNotNull = objectDsl.isNotNull
 exports.inParameter = objectDsl.inParameter
+exports.inParam = objectDsl.inParam
 exports.exists = objectDsl.exists
 exports.lower = objectDsl.lower
 exports.upper = objectDsl.upper
 exports.coalesce = objectDsl.coalesce
 exports.concat = objectDsl.concat
+exports.divide = objectDsl.divide
+exports.truncate = objectDsl.truncate
+exports.modulo = objectDsl.modulo
 exports.count = objectDsl.count
 exports.countDistinct = objectDsl.countDistinct
 exports.sum = objectDsl.sum

package/docs/authoring.md

@@ -1,7 +1,7 @@
 # Authoring DSL
 
 Authoring API находится в <code>@query-graph/core/dsl</code>. Он создает
-семантический definition версии 10, который не содержит таблиц, SQL aliases или
+семантический definition версии 12, который не содержит таблиц, SQL aliases или
 синтаксиса диалекта.
 
 ## Sources и поля
@@ -22,26 +22,124 @@ const users = source('users', {
 ## Параметры
 
 ```ts
-const id = requiredParameter('id', 'int64')
-const status = optionalParameter('status', 'string')
-const ids = requiredListParameter('ids', 'int64')
+const id = requiredParam('id', 'int64')
+const status = optionalParam('status', 'string')
+const ids = requiredListParam('ids', 'int64')
+const optionalIds = optionalListParam('optionalIds', 'int64')
 ```
 
-Scalar parameter используется через <code>param</code>, list parameter через
-<code>inParameter</code>. Optional parameter не активирует constraint с
+Scalar parameter передается в expression напрямую, list parameter используется
+через <code>inParam</code>. Явная форма <code>param(id)</code> поддерживается
+для совместимости. Полные имена <code>requiredParameter</code>,
+<code>optionalParameter</code>, <code>requiredListParameter</code>,
+<code>optionalListParameter</code> и <code>inParameter</code> остаются алиасами
+тех же factories. Optional parameter не активирует constraint с
 <code>when</code>, пока значение отсутствует.
 
+### Группированные параметры
+
+Grouped list parameter описывает массив групп <code>{ key, values }</code>.
+Каждая группа содержит один ключ и список значений:
+
+```ts
+import { allGroups, and, constraint, eq, inParam, optionalGroupsParam, source } from '@query-graph/core/dsl'
+
+const attributes = source('attributes', { name: 'string', valueId: 'int64' })
+const filters = optionalGroupsParam('filters', { key: 'string', value: 'int64' })
+const attributeFilter = constraint({
+  predicate: allGroups(filters, ({ key, values }) =>
+    and(eq(attributes.field('name'), key), inParam(attributes.field('valueId'), values)),
+  ),
+})
+
+// Operation parameters:
+const parameters = {
+  filters: [
+    { key: 'color', values: [1, 2] },
+    { key: 'size', values: [3] },
+  ],
+}
+```
+
+Добавьте <code>filters</code> в <code>parameters</code> definition, а
+<code>attributeFilter</code> в <code>constraints</code>. Если разные группы
+должны совпасть с разными связанными строками, поместите <code>exists</code>
+внутрь callback и объявите соответствующую relation.
+
+<code>requiredGroupsParam</code> требует присутствия массива в operation.
+Полные имена <code>optionalGroupsParameter</code> и
+<code>requiredGroupsParameter</code> являются алиасами тех же factories.
+Неизвестные поля конфигурации, scalar types и некорректные аргументы factories
+отклоняются сразу при authoring.
+
+Callback <code>allGroups</code> вызывается ровно один раз при построении AST,
+а не для каждой runtime-группы. <code>key</code> является типизированным scalar
+expression, <code>values</code> является отдельной scoped list reference только
+для <code>inParam</code>/<code>inParameter</code>. Ни grouped parameter, ни
+<code>values</code> нельзя передать в <code>param</code> или использовать как
+обычное scalar expression. <code>values</code> также нельзя объявить root parameter.
+
+Каждый binder получает UUID scope через <code>node:crypto.randomUUID()</code>,
+независимо от загрузки отдельных экземпляров или копий DSL. Вложенный callback
+может захватить <code>key</code> и <code>values</code> внешнего callback;
+одноименные параметры не смешивают их scopes. Ссылки за пределами своего binder,
+в том числе захваченные из соседнего callback, отклоняются Rust при регистрации.
+Scope является внутренним идентификатором, его конкретное значение не гарантируется.
+
+Семантика компиляции:
+
+- отсутствующий optional parameter и пустой массив групп дают <code>true</code>;
+- неактивное тело не требует optional scalar parameters или JOIN, используемых
+  только внутри него;
+- predicates всех групп объединяются через <code>AND</code>;
+- повторяющиеся ключи остаются независимыми группами, их values не объединяются;
+- пустой <code>values</code> дает <code>false</code> в <code>inParam</code>;
+- nullable predicate сохраняет обычную трехзначную SQL-семантику.
+
+Rust разрешает <code>allGroups</code> только в constraint predicates, включая
+вложенные boolean expressions и <code>exists</code>. Projection, ordering,
+relation predicates и aggregate bodies не поддерживают binder.
+
+Wire definition сохраняет тип элементов в <code>scalarType</code> и добавляет
+<code>shape: 'groupedList'</code> и <code>keyType</code>. AST использует
+<code>{ kind: 'allGroups', parameter, scope, predicate }</code>,
+<code>{ kind: 'groupKey', scope }</code> и
+<code>{ kind: 'inGroupValues', expression, scope }</code>.
+
 ## Expressions
 
 DSL предоставляет сравнения, boolean groups, null tests, semantic functions,
 агрегаты и literals:
 
 ```ts
-const predicate = and(eq(users.field('organisationId'), param(organisationId)), isNull(users.field('dateDelete')))
+const predicate = and(eq(users.field('organisationId'), organisationId), isNull(users.field('dateDelete')))
+```
+
+Semantic functions позволяют оставить вычисляемые поля частью графа, не
+привязывая definition к синтаксису Oracle или SQL Server:
+
+```ts
+const durationProjection = [
+  project({
+    path: 'hoursDuration',
+    expression: truncate(divide(services.field('durationMinutes'), 60)),
+  }),
+  project({
+    path: 'minutesDuration',
+    expression: modulo(services.field('durationMinutes'), 60),
+  }),
+]
 ```
 
-Типы operands проверяются TypeScript во время authoring и повторно Rust при
-регистрации.
+<code>divide</code> возвращает decimal для точных числовых типов и float64,
+если хотя бы один operand имеет тип float64. <code>truncate</code> отбрасывает
+дробную часть по направлению к нулю и сохраняет scalar type. <code>modulo</code>
+принимает int32, int64 и decimal; float64 отклоняется, чтобы definition одинаково
+работал в поддерживаемых диалектах. Nullability распространяется от operands к
+результату.
+
+TypeScript выводит тип и nullability результата во время authoring. Rust при
+регистрации повторно проверяет arity и совместимость типов operands.
 
 ## Relations
 
@@ -72,7 +170,7 @@ const profileRelation = relation({
 ```ts
 constraint({
   when: organisationId,
-  predicate: eq(users.field('organisationId'), param(organisationId)),
+  predicate: eq(users.field('organisationId'), organisationId),
 })
 
 constraint({

package/docs/composition.md

@@ -19,7 +19,7 @@ Many-связь в одном SQL может размножить root-стро
 Child-модуль один раз закрепляет контракт ключа:
 
 ```ts
-const itemIds = requiredListParameter('itemIds', 'int64')
+const itemIds = requiredListParam('itemIds', 'int64')
 
 const childrenQuery = batchQuery({
   graph: childrenGraph,

package/docs/diagnostics.md

@@ -45,8 +45,32 @@ Rust выполняет semantic validation:
 Такое разделение дает ранние ошибки опечаток, не дублируя planner rules в
 JavaScript.
 
+Циклические зависимости relation predicates через <code>exists</code> отклоняются
+при регистрации definition: <code>invalidExistsContext</code> указывает на
+<code>relations[i].on</code>, замыкающий цикл. Параметры, необходимые вложенным
+<code>exists</code>, проверяются в фазе <code>operation</code>; отсутствующий
+параметр получает <code>missingParameter</code> с location
+<code>parameters.&lt;name&gt;</code>.
+
+Статические параметры batch relation проверяются при <code>composeGraph</code>:
+ошибки относятся к фазе <code>composition</code>, в том числе для имен параметров
+с квадратными скобками. Параметр batch key исключается из этой проверки по точному
+имени; значения ключей проверяются позже, при <code>compileBatch</code>, в фазе
+<code>operation</code>.
+
 ## Совместимость diagnostics
 
-Wire schema остается версии 10. В совместимых выпусках сохраняются diagnostic
+Wire schema версии 12 добавляет grouped-параметры и scoped-шаблоны `allGroups`.
+Сохранённые raw definitions предыдущей версии требуют обновления; обычные
+DSL-фабрики формируют актуальную версию автоматически. JS DSL и native binding
+должны быть из одного выпуска пакета.
+
+Невалидные данные группы получают `invalidParameterType` с точным путём,
+например `parameters.characteristics[0].values[1]`. Ссылка вне своего шаблона
+получает `unknownGroupScope`; повторное объявление активного scope получает
+`shadowedGroupScope`. `allGroups` вне constraint predicate получает
+`invalidAllGroupsContext`. Эти проверки выполняются и для raw wire definitions.
+
+Для прежних ошибок сохраняются diagnostic
 codes и locations. Message предназначен человеку и не должен использоваться как
 machine-readable contract.

package/docs/sql.md

@@ -33,6 +33,41 @@ const oracle = graph.compileOracle(operation, { version: '19c' })
 Version capabilities проверяются до возврата SQL. Например, pagination и
 <code>firstBy</code> могут требовать более новую версию диалекта.
 
+Semantic functions рендерятся с одинаковым поведением через разные конструкции
+диалектов:
+
+| DSL                              | Oracle                        | SQL Server                        |
+| -------------------------------- | ----------------------------- | --------------------------------- |
+| <code>divide(left, right)</code> | <code>left / right</code>     | дробное <code>left / right</code> |
+| <code>truncate(value)</code>     | <code>TRUNC(value)</code>     | <code>ROUND(value, 0, 1)</code>   |
+| <code>modulo(left, right)</code> | <code>MOD(left, right)</code> | <code>left % right</code>         |
+
+SQL Server compiler принудительно переводит <code>divide</code> в дробную
+арифметику, чтобы два integer operands не дали integer division.
+
+В SQL Server 2012 и новее <code>concat</code> с одним аргументом компилируется
+с дополнительной пустой строкой <code>''</code>. Списки длиннее 254 аргументов
+разделяются на вложенные вызовы с сохранением порядка. Промежуточные группы
+используют <code>nvarchar(max)</code>, чтобы избежать обрезания строк при
+объединении. <code>NULL</code> обрабатывается как пустая строка согласно
+[семантике CONCAT в SQL Server](https://learn.microsoft.com/en-us/sql/t-sql/functions/concat-transact-sql).
+
+## Boolean expressions
+
+Компилятор различает значения и условия. Boolean-поле в <code>WHERE</code>,
+<code>ON</code> или логическом выражении превращается в сравнение с <code>1</code>.
+Условие в <code>SELECT</code>, <code>GROUP BY</code> или аргументе функции
+превращается в <code>CASE</code>: <code>TRUE</code> дает <code>1</code>,
+<code>FALSE</code> — <code>0</code>, <code>UNKNOWN</code> — <code>NULL</code>.
+Boolean metadata и TypeScript-типы сохраняются; преобразование значений драйвера
+остается ответственностью executor.
+
+В Oracle 23ai условия сохраняют нативный SQL-тип <code>BOOLEAN</code> в контексте
+значения. В контексте условия скалярные значения оборачиваются в
+<code>TO_BOOLEAN</code>, который принимает как числовое, так и boolean-представление.
+Прямые проекции полей и существующие сравнения с boolean literals сохраняют
+прежний SQL.
+
 ## Bindings
 
 Compiler никогда не вставляет operation values в SQL. Каждый binding содержит:
@@ -40,11 +75,64 @@ Compiler никогда не вставляет operation values в SQL. Каж
 - SQL placeholder name;
 - имя parameter;
 - scalar type;
-- index элемента для list parameter.
+- index элемента для list parameter;
+- path до вложенного значения для grouped parameter.
 
 Повторное использование parameter переиспользует binding. Пустой list
 компилируется в ложное условие без placeholders.
 
+Для scalar отсутствуют и `index`, и `path`. Для обычного list сохраняется
+`index`. Для grouped list используется только `path`, например:
+
+```ts
+;[
+  { name: 'p0', parameter: 'characteristics', scalarType: 'int64', path: [0, 'key'] },
+  { name: 'p1', parameter: 'characteristics', scalarType: 'int64', path: [0, 'values', 1] },
+]
+```
+
+Executor извлекает значение из `operation.parameters[binding.parameter]`,
+последовательно проходя по сегментам `path`. `index` и `path` взаимно исключаются;
+отсутствующий сегмент должен приводить к ошибке, а не к подстановке `null`.
+Тип binding соответствует конкретному ключу или элементу values, а не контейнеру.
+Повторное обращение к тому же параметру и пути переиспользует placeholder.
+Потребитель должен обновить resolver bindings до начала использования grouped-параметров.
+
+`allGroups` разворачивает шаблон в условия, соединённые `AND`, только при
+компиляции операции. Для отсутствующего optional-параметра и пустого списка
+групп результат равен `TRUE`; зависимости тела шаблона не включаются в план.
+Каждый `exists` остаётся коррелированным подзапросом по описанному пути relations,
+включая `firstBy`. Definition не изменяется, но SQL зависит от количества групп
+и значений. Это один SQL-запрос, а не отдельное выполнение на каждую группу.
+
+На один statement допускается до 10 000 разворачиваний тела `allGroups`
+суммарно по всем шаблонам, включая вложенные. Превышение возвращает
+`groupExpansionLimitExceeded`: вложенность может увеличить SQL многократно,
+даже когда все bindings переиспользуются. Лимит применяется отдельно к каждой
+компиляции и не ограничивает каталог доступных групп в приложении.
+
+Также ограничено суммарное число элементов параметров-массивов, развёрнутых
+внутри этих шаблонов: до 100 000 на statement. Повторное использование
+одинаковых placeholders считается повторно, поскольку увеличивает SQL.
+Ограничение охватывает и `values` группы, и обычный list parameter внутри
+`allGroups`; превышение даёт `groupValueExpansionLimitExceeded`.
+
+SQL Server compiler отклоняет statement с более чем 2100 уникальными bindings
+с диагностикой `tooManyParameters`. Считаются все scalar, list и grouped bindings
+вместе; разбиение `IN` не уменьшает их количество. Для больших выборок нужна
+другая стратегия передачи данных, которой текущий grouped DSL не подменяет
+явную ошибку. Ограничение согласовано с
+[бюджетом параметров SQL Server](https://learn.microsoft.com/sql/sql-server/maximum-capacity-specifications-for-sql-server).
+
+В Oracle большие <code>inParam</code> (включая values группы) и <code>inList</code> разбиваются на
+группы <code>IN</code>, объединённые <code>OR</code> в общих скобках внутри
+одного SQL. Размер группы — до 1000 выражений в 11g–21c и до 65535 в 23ai
+согласно [лимитам Oracle](https://python-oracledb.readthedocs.io/en/v2.5.1/user_guide/bind.html#binding-a-large-number-of-items-in-an-in-list).
+<code>not</code> применяется ко всей группе и сохраняет SQL-семантику
+<code>NULL</code>. Порядок элементов и индексы bindings сохраняются, включая
+дубликаты. Пустой литеральный <code>inList</code> по-прежнему отклоняется при
+валидации definition.
+
 ## Result metadata
 
 SQL columns получают технические aliases <code>c0</code>,

package/docs/type-system.md

@@ -16,6 +16,10 @@ TypeScript помогает автору до регистрации, Rust ос
 <code>int64</code> принимает number только в безопасном диапазоне JavaScript.
 Decimal string проверяется как конечная десятичная запись.
 
+<code>integer(value)</code> поддерживает весь диапазон от
+<code>Number.MIN_SAFE_INTEGER</code> до <code>Number.MAX_SAFE_INTEGER</code>,
+включая значения за пределами 32 бит.
+
 ## QueryOperation
 
 Definition передает свои параметры, projection paths и ordering names в
@@ -34,6 +38,49 @@ const operation = {
 Required parameters обязательны, optional параметры могут отсутствовать,
 list parameters принимают readonly arrays.
 
+Grouped list parameters выводятся как:
+
+```ts
+readonly {
+  key: ScalarParameterValue<KeyType>
+  values: readonly ScalarParameterValue<ValueType>[]
+}[]
+```
+
+Например, <code>requiredGroupsParam('filters', { key: 'string', value: 'int64' })</code>
+требует <code>parameters.filters</code> типа
+<code>readonly { key: string; values: readonly (number | string)[] }[]</code>.
+Optional grouped parameter может отсутствовать, но не заменяться на <code>null</code>.
+Оба массива принимают readonly tuples, в том числе из <code>as const</code>.
+
+Контейнер групп, отдельная группа и контейнер <code>values</code> не могут быть
+<code>null</code>. Ключ и элементы списка следуют обычному scalar contract:
+<code>null</code> запрещен для всех типов, кроме <code>json</code>. JSON сохраняет
+существующую семантику JSON values, включая <code>null</code> и вложенные структуры.
+Rust проверяет наличие <code>key</code>/<code>values</code>, неизвестные поля
+группы и scalar types, включая ограничения числовых значений.
+
+Grouped parameters сохраняют эти типы при композиции GraphModule и могут быть
+статическими параметрами дочернего <code>batchRelation</code>. Ключ
+<code>batchQuery</code> по-прежнему требует обычный list parameter, не grouped list.
+
+В callback <code>allGroups</code> ключ имеет scalar type <code>KeyType</code>,
+а <code>GroupValuesRef&lt;ValueType&gt;</code> принимается только как второй аргумент
+<code>inParameter</code>/<code>inParam</code>. TypeScript исключает эту reference
+из scalar expressions и root parameters; Rust проверяет lexical scope и
+совместимость типов сравнения и membership.
+
+Для grouped bindings <code>path</code> указывает на значение внутри operation
+parameter: <code>[groupIndex, 'key']</code> или
+<code>[groupIndex, 'values', valueIndex]</code>. Scalar bindings остаются без
+<code>index</code>/<code>path</code>, обычные list bindings сохраняют
+<code>index</code>. Поля <code>index</code> и <code>path</code> взаимоисключающие.
+Это же правило действует для результатов <code>compileBatch</code>.
+
+В Node API <code>offset</code> и <code>limit</code> принимают безопасные целые
+JavaScript, включая значения больше <code>2 \*\* 32 - 1</code>.
+<code>offset</code> должен быть неотрицательным, <code>limit</code> — положительным.
+
 ## Nullability
 
 Nullability выражения складывается из:
@@ -46,6 +93,20 @@ Nullability выражения складывается из:
 Required relation под optional ancestor остается nullable. Это свойство
 вычисляется из topology один раз при регистрации.
 
+В <code>fieldType</code> флаг <code>nullable</code> типа <code>boolean</code>
+означает, что поле может быть NULL. Литеральные <code>true</code> и
+<code>false</code> позволяют вывести точную nullability.
+
+Сравнения <code>eq</code>/<code>neq</code> с гарантированным <code>null</code>
+(включая <code>literal(null)</code>) дают non-null результат. Тип операнда
+<code>string | null</code> сам по себе не гарантирует сравнение именно с NULL:
+nullable поле при сравнении со строкой может дать NULL.
+
+<code>allGroups</code> возвращает boolean с nullability predicate шаблона.
+Пустой набор групп дает <code>true</code>, но при наличии групп nullable
+сравнение внутри callback может дать SQL UNKNOWN. Если callback возвращает
+<code>exists</code>, результат остается non-null boolean.
+
 ## ResultOf
 
 ```ts
@@ -77,7 +138,8 @@ compilation не меняются.
 Rust проверяет:
 
 - ссылки на sources, fields и parameters;
-- scalar/list shape параметров;
+- scalar/list/groupedList shape параметров и key type grouped parameters;
+- lexical scopes ключей и списков групп, допустимость binder в constraint context;
 - совместимость сравнений и функций;
 - boolean тип predicates;
 - orderable и groupable expressions;