@query-graph/core 1.1.4 → 1.1.6

package/README.md

@@ -3,47 +3,44 @@
 Типизированное описание графов запросов, нативное планирование и компиляция SQL
 для Node.js.
 
-`query-graph` позволяет один раз описать доступные данные и связи без SQL, а для
-каждой операции выбрать поля, параметры, сортировку и пагинацию. Rust проверяет
-definition, строит минимальный план связей и компилирует его в SQL Server или
-Oracle SQL.
+Граф описывает доступные данные, связи, ограничения и форму результата без
+синтаксиса конкретной СУБД. Rust валидирует definition, выбирает минимальный
+набор связей и компилирует operation в SQL Server или Oracle SQL.
 
-Пакет намеренно **не подключается к базе данных и не выполняет SQL**. Он
-возвращает SQL, bindings и metadata результата; способ исполнения остаётся у
-приложения.
+Пакет не подключается к базе данных и не выполняет запросы. На выходе он
+возвращает SQL, bindings и metadata, необходимые executor приложения.
 
-Основные возможности:
+## Возможности
 
-- строгий TypeScript DSL для sources, parameters, relations и projections;
-- runtime-валидация definition и operation в Rust;
-- выбор только необходимых JOIN по запрошенным projection paths;
-- один definition для SQL Server и Oracle;
-- scalar/list parameters без подстановки значений в SQL;
-- `exists`, детерминированные to-one relations, summary-графы и batch relations;
-- тип результата через `ResultOf`.
+- объектный TypeScript DSL с выводом параметров, projection paths и результата;
+- строгая runtime-валидация definition, mapping и operation в Rust;
+- выбор 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.
 
 Требуется Node.js 20 или новее.
 
-## Быстрый старт
-
-### Установка
+## Установка
 
 ```bash
 npm install @query-graph/core
 ```
 
-Основной объектный DSL уже входит в пакет и доступен через
-`@query-graph/core/dsl`.
+Используйте два entrypoint:
 
-### 1. Опишите доступные данные
+- <code>@query-graph/core/dsl</code> для описания графа и TypeScript типов;
+- <code>@query-graph/core</code> для регистрации и нативной компиляции.
 
-Definition использует логические имена. Здесь нет имён таблиц, SQL-алиасов или
-синтаксиса конкретной СУБД.
+## Быстрый старт
 
 ```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',
@@ -51,7 +48,7 @@ const users = source('users', {
   email: 'string',
 })
 
-const organisationId = requiredParameter('organisationId', 'int64')
+const organisationId = requiredParam('organisationId', 'int64')
 
 const usersDefinition = defineGraph({
   name: 'users',
@@ -60,7 +57,7 @@ const usersDefinition = defineGraph({
   parameters: [organisationId],
   constraints: [
     constraint({
-      predicate: eq(users.field('organisationId'), param(organisationId)),
+      predicate: eq(users.field('organisationId'), organisationId),
     }),
   ],
   projection: [
@@ -68,14 +65,7 @@ const usersDefinition = defineGraph({
     project({ path: 'email', expression: users.field('email'), default: true }),
   ],
 })
-```
-
-### 2. Добавьте реляционное отображение
 
-Mapping связывает логический source с физической таблицей. Его можно заменить,
-не меняя definition.
-
-```ts
 const usersGraph = registerDefinition(usersDefinition).withRelationalMapping({
   sources: {
     users: {
@@ -86,972 +76,192 @@ const usersGraph = registerDefinition(usersDefinition).withRelationalMapping({
     },
   },
 })
-```
 
-Mapping переиспользуемых частей можно держать рядом с ними и объединять при
-регистрации итогового графа:
-
-```ts
-const usersGraph = registerDefinition(usersDefinition).withRelationalMappings([usersMapping, profileMapping])
+const statement = usersGraph.compileSqlServer({ parameters: { organisationId: 42 } }, { version: '2022' })
+type UserRow = ResultOf<typeof usersDefinition>
 ```
 
-Фрагменты могут дополнять `columns` одного source, если указывают одинаковую
-таблицу. Повтор одинакового отображения безопасен. Разные таблицы для одного
-source или разные физические колонки для одного логического поля возвращают
-структурированную ошибку фазы `mapping`. После объединения mapping всё равно
-должен полностью покрывать sources итогового definition.
+<code>statement</code> содержит:
 
-`registerDefinition` валидирует и индексирует definition в Rust. Обычно граф
-регистрируется один раз при запуске приложения и затем переиспользуется.
+| Поле                   | Назначение                                                                        |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| <code>sql</code>       | параметризованный SQL с placeholders <code>p0</code>, <code>p1</code> и так далее |
+| <code>bindings</code>  | связь placeholder с operation parameter и типом                                   |
+| <code>columns</code>   | связь SQL alias <code>cN</code> с логическим projection path                      |
+| <code>objects</code>   | presence metadata для nullable вложенных объектов                                 |
+| <code>relations</code> | связи, выбранные planner для этой operation                                       |
 
-### 3. Скомпилируйте операцию
+Executor берет значения из <code>parameters</code> переданной operation по
+<code>bindings</code>, вызывает DB driver и восстанавливает объект по
+<code>columns</code> и <code>objects</code>. Разбирать SQL не нужно.
 
-Operation содержит только изменяемую часть запроса. TypeScript проверяет имена
-полей и параметров относительно конкретного definition.
+Тот же mapped graph можно скомпилировать в Oracle:
 
 ```ts
-const operation = {
-  select: ['id', 'email'],
-  parameters: {
-    organisationId: 42,
-  },
-} as const satisfies QueryOperation<typeof usersDefinition>
-
-const statement = usersGraph.compileSqlServer(operation)
-
-console.log(statement.sql)
-console.table(statement.bindings)
-console.table(statement.columns)
-
-type UserRow = ResultOf<typeof usersDefinition, typeof operation>
-// { id: number | string; email: string }
+const oracleStatement = usersGraph.compileOracle({ parameters: { organisationId: 42 } }, { version: '19c' })
 ```
 
-Для SQL Server получится параметризованный запрос:
+## Зачем нужен planner
 
-```sql
-SELECT
-  [t0].[id] AS [c0],
-  [t0].[email] AS [c1]
-FROM [dbo].[users] AS [t0]
-WHERE
-  ([t0].[organisation_id] = @p0)
-```
-
-В `statement.bindings` placeholder `p0` будет связан с параметром
-`organisationId` типа `int64`.
-
-Тот же graph можно передать другому compiler:
-
-```ts
-const oracleStatement = usersGraph.compileOracle(operation, { version: '19c' })
-```
-
-### 4. Выполните SQL своим драйвером
-
-Результат компиляции не содержит соединение с базой данных:
-
-| Поле statement | Назначение                                                                     |
-| -------------- | ------------------------------------------------------------------------------ |
-| `sql`          | SQL с именованными placeholders `p0`, `p1` и так далее                         |
-| `bindings`     | связь placeholder с параметром operation, его типом и индексом элемента списка |
-| `columns`      | связь физической колонки `cN` с projection path и scalar type                  |
-| `objects`      | presence-маркеры для nullable вложенных объектов                               |
-| `relations`    | связи, фактически выбранные planner для этой операции                          |
-
-Executor приложения берёт значения из `operation.parameters` согласно
-`statement.bindings`, передаёт их DB driver и восстанавливает логические поля по
-`statement.columns`. Разбирать SQL для этого не требуется.
-
-## Как выбрать возможность
-
-| Задача                                                   | API или раздел                                              |
-| -------------------------------------------------------- | ----------------------------------------------------------- |
-| Выбрать связанные поля `0..1` или `1`                    | [`relation` и `firstBy`](#to-one-selection)                 |
-| Отфильтровать root по наличию связанных строк            | [`exists`](#existential-constraints)                        |
-| Переиспользовать часть definition                        | [GraphModule](#композиция-через-graphmodule)                |
-| Передать массив в `IN (...)`                             | [Параметры-списки](#параметры-списки)                       |
-| Выбирать сортировку во время выполнения                  | [Именованные сортировки](#именованные-сортировки)           |
-| Получить агрегированный результат                        | [Summary-графы](#summary-графы)                             |
-| Отличить отсутствующий объект от объекта с `NULL`-полями | [Presence объектной проекции](#presence-объектной-проекции) |
-| Загрузить коллекцию после пагинации root                 | [Batch-связи](#batch-связи-и-двухфазное-выполнение)         |
-| Обработать структурированную ошибку                      | [Диагностика](#диагностика)                                 |
-
-## Модель использования
-
-| Понятие                | Когда создаётся                     | За что отвечает                                         |
-| ---------------------- | ----------------------------------- | ------------------------------------------------------- |
-| `GraphDefinition`      | при объявлении графа                | логические sources, relations, constraints и projection |
-| `QueryGraph`           | один раз после `registerDefinition` | проверенный и проиндексированный нативный граф          |
-| `RelationalMapping`    | при конфигурации приложения         | физические таблицы и переименования колонок             |
-| `QueryOperation`       | для конкретного запроса             | выбранные поля, параметры, ordering и pagination        |
-| `CompiledSqlStatement` | при компиляции operation            | SQL и metadata, необходимые executor приложения         |
-| `GraphModule`          | при композиции definition           | переиспользуемый фрагмент без собственного root         |
-
-Обычный жизненный цикл выглядит так:
+В реальном графе преимущество проявляется, когда одна definition обслуживает
+разные формы результата:
 
 ```text
-defineGraph -> registerDefinition -> withRelationalMapping(s)
-                                      |
-QueryOperation -----------------------+-> compileSqlServer / compileOracle
-                                              |
-                                              +-> executor приложения -> DB driver
-```
-
-## Архитектура пакета
-
-Cargo workspace разделён на два слоя. `query-graph-core` не зависит от Node.js
-или N-API и содержит definition, type system, planner, relational mapping и SQL
-compilers. Корневой crate `query_graph` является тонким N-API adapter: он
-десериализует wire-объекты, вызывает core и переводит результат и diagnostics в
-JavaScript.
-
-Зависимость направлена только от adapter к core. Исполнение SQL в оба слоя не входит.
-
-## Определение графа
-
-Определение графа не зависит от диалекта SQL и содержит:
-
-- логические источники и поля;
-- типизированные параметры;
-- именованные связи;
-- семантические ограничения;
-- выходную проекцию;
-- именованные варианты сортировки.
+orders
+|-- customer
+|   `-- organisation
+|-- latestPayment [firstBy]
+`-- items [batch many]
 
-`registerDefinition` один раз передает определение в Rust. Rust валидирует все
-ссылки, создает переиспользуемые индексы и возвращает нативный дескриптор
-`QueryGraph`.
-
-```ts
-import { registerDefinition } from '@query-graph/core'
-import {
-  asc,
-  constraint,
-  desc,
-  defineGraph,
-  defineGraphModule,
-  eq,
-  exists,
-  firstBy,
-  inParameter,
-  isNotNull,
-  nullable,
-  ordering,
-  param,
-  project,
-  relation,
-  requiredListParameter,
-  requiredParameter,
-  source,
-} from '@query-graph/core/dsl'
-
-const users = source('users', {
-  id: 'int64',
-  email: 'string',
-})
-
-const profiles = source('profiles', {
-  id: 'int64',
-  userId: 'int64',
-  displayName: nullable('string'),
-})
-
-const userId = requiredParameter('userId', 'int64')
-const profileRelation = relation({
-  name: 'profile',
-  from: users,
-  to: profiles,
-  on: eq(users.field('id'), profiles.field('userId')),
-  cardinality: 'one',
-  required: true,
-  selection: firstBy(asc(profiles.field('id'))),
-})
-
-const userProfileModule = defineGraphModule({
-  name: 'userProfile',
-  sources: [users, profiles],
-  parameters: [userId],
-  relations: [profileRelation],
-  constraints: [
-    constraint({
-      predicate: eq(users.field('id'), param(userId)),
-    }),
-    constraint({
-      predicate: exists(profiles, isNotNull(profiles.field('displayName'))),
-    }),
-  ],
-  projection: [
-    project({
-      path: 'id',
-      expression: users.field('id'),
-      default: true,
-    }),
-    project({
-      path: 'profile.displayName',
-      expression: profiles.field('displayName'),
-    }),
-  ],
-  orderings: [
-    ordering({
-      name: 'idAsc',
-      by: [asc(users.field('id'))],
-      default: true,
-    }),
-  ],
-})
-
-const definition = defineGraph({
-  name: 'userProfile',
-  root: users,
-  modules: [userProfileModule],
-})
-
-const graph = registerDefinition(definition)
+constraints: organisationId, exists(activePromotion)
 ```
 
-### Композиция через GraphModule
-
-`GraphModule` группирует переиспользуемую часть определения: источники,
-параметры, связи, ограничения, проекцию и сортировку. У модуля нет собственного
-корневого источника, и его нельзя зарегистрировать или скомпилировать отдельно.
-
-`defineGraph` объединяет вложенные модули и локальные элементы в один плоский
-`GraphDefinition`. Повторно подключенный объект дедуплицируется по identity. Для
-именованных элементов разные определения с одним ключом приводят к ошибке
-композиции.
-
-Constraints не имеют имени: повторно использованный constraint добавляется один
-раз, а разные constraint-объекты сохраняются и объединяются через `AND`. Сведения
-о модулях не передаются в Rust и не входят в wire-формат.
-
-Вспомогательные функции API описания графа формируют версионируемое и
-сериализуемое промежуточное представление `GraphDefinition`. Дискриминаторы
-выражений, например `kind: 'eq'`, существуют только в сгенерированном
-представлении. В прикладном коде графа их писать не требуется. TypeScript
-проверяет ссылки на поля источников.
-
-Relation path проекции указывать не требуется. При регистрации definition Rust
-находит самый глубокий source, использованный expression, и один раз сохраняет
-путь от root до этого source. Expression может обращаться к root и любым sources
-на одной ветке. Обращение к двум независимым веткам отклоняется как неоднозначная
-проекция. Planner использует уже вычисленные пути и не повторяет inference при
-каждой компиляции operation.
-
-### Варианты DSL
-
-Canonical `GraphDefinition` не зависит от authoring DSL. Основной authoring API
-доступен через `@query-graph/core/dsl` и использует объектные конфигурации. Позиционный
-`@query-graph/core/definition` сохранён как адаптер совместимости для существующего кода;
-новые графы на него ориентировать не следует.
-
-Отдельный пакет `@query-graph/dsl-object` является тонким фасадом над тем же API.
-Он полезен, когда DSL нужен как отдельная зависимость:
-
-```bash
-npm install @query-graph/core @query-graph/dsl-object
-```
+<code>ordersDefinition</code> содержит показанные на схеме relations и
+projection. Его небанальные части выглядят так:
 
 ```ts
-import { registerDefinition } from '@query-graph/core'
-import { asc, defineGraph, eq, firstBy, project, relation, source } from '@query-graph/dsl-object'
-
-const users = source('users', { id: 'int64' })
-const profiles = source('profiles', {
-  id: 'int64',
-  userId: 'int64',
-  displayName: 'string',
+const latestPayment = relation({
+  name: 'latestPayment',
+  from: orders,
+  to: payments,
+  on: eq(orders.field('id'), payments.field('orderId')),
+  selection: firstBy(desc(payments.field('createdAt'))),
 })
 
-const definition = defineGraph({
-  name: 'users',
-  root: users,
-  sources: [users, profiles],
-  relations: [
-    relation({
-      name: 'profile',
-      from: users,
-      to: profiles,
-      on: eq(users.field('id'), profiles.field('userId')),
-      cardinality: 'one',
-      selection: firstBy(asc(profiles.field('id'))),
-    }),
-  ],
-  projection: [
-    project({ path: 'id', expression: users.field('id'), default: true }),
-    project({ path: 'profile.displayName', expression: profiles.field('displayName') }),
-  ],
-})
-
-const graph = registerDefinition(definition)
-```
-
-Фасад не содержит второй реализации и напрямую переэкспортирует
-`@query-graph/core/dsl`. Расширение позиционного compatibility API не меняет поверхность
-объектного DSL.
-
-Оба входа формируют один и тот же versioned wire-контракт. Сторонний DSL также может
-создавать `GraphDefinitionInput`; Rust проверяет его при `registerDefinition`.
-
-### Existential constraints
-
-`exists(source, predicate?)` задаёт семантический квантор. В graph constraint
-Rust по умолчанию использует уникальный relation path от root до указанного source,
-поэтому описывать SQL-подзапрос или correlation columns не требуется.
-
-```ts
-constraint({
-  predicate: exists(memberships, eq(memberships.field('teamId'), param(teamId))),
-})
-```
-
-Predicate может обращаться к root и sources на выведенном пути. Ссылки на
-соседнюю ветку отклоняются при регистрации definition. Помимо constraints,
-явно коррелированный `exists` разрешён в `relation.on`; в projections, ordering
-и selection он отклоняется. Отрицание выражается обычным `not(exists(...))`.
-
-Planner воспринимает existential branch как semijoin. Sources этой ветки не
-добавляются во внешние JOIN и `statement.relations`, поэтому relation с
-cardinality `many` не размножает корневые строки и не мешает их пагинации.
-Oracle и SQL Server compiler строят коррелированный `EXISTS` из одной и той же
-семантики definition.
-
-По умолчанию `exists` коррелируется от root. Для semijoin относительно уже
-выбранного внешнего source можно явно указать точку корреляции:
-
-```ts
-constraint({
-  predicate: exists(permissions, permissionPredicate, { from: memberships }),
-})
-```
-
-`from` должен быть строгим предком целевого source на relation path. Planner
-оставляет путь до `from` во внешнем запросе, а оставшийся путь компилирует как
-коррелированный semijoin.
-
-В `relation.on` точка корреляции обязательна. Это позволяет сначала ограничить
-множество кандидатов связи, а затем применить `firstBy`:
-
-```ts
-relation({
-  name: 'profile',
-  from: users,
-  to: profiles,
-  on: and(
-    eq(users.field('id'), profiles.field('userId')),
-    exists(profileFlags, eq(profileFlags.field('enabled'), true), { from: profiles }),
-  ),
-  selection: firstBy(asc(profiles.field('id'))),
-})
-```
-
-Такой `exists` становится semijoin внутри relation predicate. Его branch не
-материализуется во внешние JOIN и не меняет cardinality результата.
-
-### Параметры-списки
-
-Параметр имеет явную форму `scalar` или `list`. Один параметр не меняет форму
-между операциями, поэтому в прикладном коде не требуется поддерживать
-`number | number[]`.
-
-```ts
-const users = source('users', {
-  id: 'int64',
-})
-
-const memberships = source('memberships', {
-  id: 'int64',
-  userId: 'int64',
-  teamId: 'int64',
-})
-
-const teamIds = requiredListParameter('teamIds', 'int64')
-
-const definition = defineGraph({
-  name: 'usersByTeams',
-  root: users,
-  sources: [users, memberships],
-  parameters: [teamIds],
-  relations: [
-    relation({
-      name: 'memberships',
-      from: users,
-      to: memberships,
-      on: eq(users.field('id'), memberships.field('userId')),
-      cardinality: 'many',
-    }),
-  ],
-  constraints: [
-    constraint({
-      predicate: exists(memberships, inParameter(memberships.field('teamId'), teamIds)),
-    }),
-  ],
-  projection: [project({ path: 'id', expression: users.field('id'), default: true })],
-})
-```
-
-Operation передает обычный массив:
-
-```ts
-const statement = relationalGraph.compileSqlServer({
-  parameters: { teamIds: [12, 18, 24] },
-})
-```
-
-Compiler разворачивает его в `IN (@p0, @p1, @p2)`. Каждый элемент получает
-binding `{ parameter: 'teamIds', index, scalarType: 'int64' }`, по которому
-adapter исполнения берет значение из исходного массива. Rust проверяет каждый
-элемент отдельно и возвращает путь ошибки наподобие
-`parameters.teamIds[2]`.
-
-Отсутствующий optional list отключает constraint с `when`. Переданный пустой
-список остается присутствующим параметром и компилируется в ложный предикат
-`1 = 0`; недопустимый SQL `IN ()` не создается.
-
-### Именованные сортировки
-
-Definition объявляет допустимые способы упорядочивания, а operation выбирает один из них по имени:
-
-```ts
-const definition = defineGraph({
-  // ...
-  orderings: [
-    ordering({ name: 'createdDesc', by: [desc(items.field('dateCreate'))], default: true }),
-    ordering({ name: 'nameAsc', by: [asc(items.field('name'))] }),
-  ],
+const hasActivePromotion = constraint({
+  predicate: exists(promotions, eq(promotions.field('active'), true)),
 })
 
-relationalGraph.compileOracle({
-  ordering: 'nameAsc',
-  parameters,
-})
-```
-
-Поле `default: true` можно указать только у одного варианта. Если operation не передает
-`ordering`, planner использует default-вариант; без него SQL строится без `ORDER BY`.
-TypeScript выводит union имен из definition и подключенных graph modules. Rust проверяет имя
-повторно и планирует только связи и параметры выбранной сортировки.
-
-### To-one selection
-
-`cardinality: 'one'` описывает контракт связи. Если физический источник может
-содержать несколько кандидатов, `firstBy` задает семантическое правило выбора
-одной строки:
-
-```ts
-const profile = relation({
-  name: 'profile',
-  from: users,
-  to: profiles,
-  on: eq(users.field('id'), profiles.field('userId')),
-  selection: firstBy(asc(profiles.field('id'))),
-})
-```
-
-Поля сортировки могут обращаться только к target source. Список сортировки
-обязателен; последнее поле следует выбирать уникальным, чтобы результат был
-детерминированным. `required: false` означает `0..1`, а `required: true` -
-ровно одну связанную строку.
-
-SQL Server renderer использует `OUTER/CROSS APPLY` и `TOP (1)`, Oracle 12c+
-использует `OUTER/CROSS APPLY` и `FETCH FIRST 1 ROW ONLY`. Эти детали не входят
-в definition. Для Oracle 11g `firstBy` возвращает
-`unsupportedDialectFeature`.
-
-### Summary-графы
-
-`defineSummaryGraph` описывает результат через dimensions и measures, не через
-SQL-конструкции `GROUP BY` и `HAVING`:
-
-```ts
-const teams = source('teams', {
-  id: 'int64',
-  workspaceId: 'int64',
-})
-
-const memberships = source('memberships', {
-  id: 'int64',
-  userId: 'int64',
-  teamId: 'int64',
-})
-
-const workspaceId = requiredParameter('workspaceId', 'int64')
-const minimumMembers = requiredParameter('minimumMembers', 'int64')
-
-const teamId = dimension({
-  path: 'teamId',
-  expression: teams.field('id'),
-  default: true,
-})
-
-const memberCount = measure({
-  path: 'memberCount',
-  expression: countDistinct(memberships.field('userId')),
-  default: 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 definition = defineSummaryGraph({
-  name: 'teamSummary',
-  root: teams,
-  sources: [teams, memberships],
-  parameters: [workspaceId, minimumMembers],
-  relations: [
-    relation({
-      name: 'members',
-      from: teams,
-      to: memberships,
-      on: eq(teams.field('id'), memberships.field('teamId')),
-      cardinality: 'many',
-    }),
-  ],
-  constraints: [
-    constraint({
-      predicate: eq(teams.field('workspaceId'), param(workspaceId)),
-    }),
-    constraint({
-      predicate: gte(memberCount, param(minimumMembers)),
-    }),
-  ],
-  dimensions: [teamId],
-  measures: [memberCount],
-  orderings: [
-    ordering({
-      name: 'memberCountDesc',
-      by: [desc(memberCount)],
-      default: true,
-    }),
-  ],
-})
-```
-
-Planner включает все объявленные dimensions в идентичность результата и
-компилирует их в `GROUP BY`, даже если operation не возвращает часть из них.
-Constraint без агрегата фильтрует исходное множество через `WHERE`. Constraint
-с агрегатом фильтрует уже построенные группы через `HAVING`. Поэтому автор графа
-не выбирает SQL-фазу вручную и не может случайно поместить агрегат в `WHERE`.
-
-Поддерживаются `count()`, `count(expression)`, `countDistinct`, `sum`,
-`average`, `minimum` и `maximum`. Measure можно передавать в сравнения и
-сортировку как expression; DSL разворачивает ссылку в сериализуемое
-семантическое выражение до передачи definition в Rust.
-
-Rust отклоняет агрегаты в обычных graph projections, relation predicates и
-dimensions, а также вложенные агрегаты и поля вне объявленных dimensions.
-`count` и `countDistinct` возвращают non-null `int64`; остальные меры nullable,
-поскольку пустое множество или множество из `NULL` не имеет значения агрегата.
-Для сохранения контракта `int64` SQL Server compiler использует `COUNT_BIG`, а
-Oracle compiler - `COUNT`. Dimension должен иметь семантику равенства, поэтому
-`json` не может задавать идентичность группы.
-
-Глобальный `DISTINCT` намеренно не выводится из структуры связей. Для количества
-уникальных значений используется `countDistinct`, а summary только из dimensions
-задает уникальные комбинации через группировку. Произвольный SQL subquery также
-не входит в DSL: `exists`, `firstBy` и агрегаты остаются семантическими
-операциями, для которых форму подзапроса при необходимости выбирает compiler.
-
-Summary-план с несколькими независимыми relations `many` отклоняется: обычные
-JOIN создали бы декартово размножение веток и могли исказить measures. Ограничение
-соседней ветки следует выражать через `exists`. Независимые меры нескольких
-коллекций потребуют отдельной aggregate-subquery strategy в planner; compiler не
-маскирует эту ситуацию через `DISTINCT`.
-
-Полученное определение не содержит SQL, имен таблиц, значений конкретного
-драйвера, объектов построителя или исполняемых функций обратного вызова
-JavaScript. DSL не выполняет планирование запросов: Rust остается единственным
-источником правил валидации и компиляции.
-
-## Система типов
-
-При `registerDefinition` Rust выводит тип каждого expression из описаний полей,
-параметров и литералов. Проверка выполняется один раз после структурной
-валидации и до построения переиспользуемого `QueryGraph`.
-
-Система типов проверяет:
-
-- совместимость операндов сравнений;
-- строковые аргументы `like`, `lower`, `upper` и `concat`;
-- общий тип аргументов `coalesce`;
-- boolean-тип условий relations и constraints;
-- допустимость сортировки выражений;
-- конкретный scalar type и nullability каждого поля проекции;
-- типы аргументов агрегатов и их результирующую nullability;
-- соответствие неагрегированных выражений объявленным dimensions.
-
-Поддерживаемые семантические функции задаются DSL-функциями `lower`, `upper`,
-`coalesce` и `concat`. Произвольное имя функции не является частью публичного
-DSL: сначала функция должна получить общую семантику типов и реализацию для
-каждого SQL dialect.
-
-TypeScript проверяет имена источников, полей и семантических функций во время
-написания definition. Rust остается авторитетной проверкой scalar-типов после
-композиции модулей; Node.js не обходит граф и не дублирует правила вывода типов.
-
-`defineGraph` также сохраняет типы параметров и projection paths, включая
-содержимое вложенных `GraphModule`. `registerDefinition` переносит эти сведения
-на native handle, поэтому операция проверяется непосредственно в месте вызова:
-
-```ts
-const relationalGraph = registerDefinition(definition).withRelationalMapping(mapping)
-
-relationalGraph.compileSqlServer({
-  select: ['id', 'profile.displayName'],
-  parameters: {
-    userId: 42,
-  },
+const items = batchRelation({
+  name: 'items',
+  from: 'id',
+  query: batchQuery({
+    graph: orderItemsGraph,
+    key: { path: 'orderId', parameter: orderIds },
+  }),
+  cardinality: 'many',
 })
-```
-
-TypeScript отклоняет неизвестный projection path или параметр, отсутствие
-required-параметра, scalar вместо списка и значение неподходящего scalar type.
-Optional-параметры можно не передавать, если они не требуются выбранным планом;
-обычно они включают constraint через `when`. Для `int64` допустимы безопасный
-JavaScript number и десятичная строка, а list-параметр получает массив того же
-типа. Эти проверки существуют только в декларациях TypeScript; сериализация
-definition, N-API вызов, runtime-валидация Rust и SQL compilation не меняются.
-
-### Тип результата проекции
-
-DSL сохраняет scalar type и nullability каждого projection expression в compile-time metadata.
-`ResultOf` строит из этих сведений вложенный тип результата по projection paths:
-
-```ts
-import type { QueryOperation, ResultOf } from '@query-graph/core/dsl'
-
-const operation = {
-  select: ['id', 'profile.displayName'],
-  parameters: { userId: 42 },
-} as const satisfies QueryOperation<typeof definition>
-
-type UserRow = ResultOf<typeof definition, typeof operation>
-// {
-//   id: number | string
-//   profile: { displayName: string | null }
-// }
-```
-
-Если второй аргумент не передан, в результат входят только поля с `default: true`.
-`ResultOf` также принимает тип, возвращенный `registerDefinition`, или mapped graph:
-
-```ts
-type DefaultUserRow = ResultOf<typeof graph>
-// { id: number | string }
-```
-
-Nullability учитывает nullable-поле и всю цепочку optional relations до его source.
-Required relation после optional relation не делает значение обязательным. Семантика
-выражений тоже сохраняется: например, `coalesce(nullableField, 'fallback')` выводится
-как non-null `string`.
-
-Типы значений по умолчанию нейтральны к DB driver: `int64` и `decimal` представлены
-как `number | string`, а `date`, `dateTime` и `binary` - как `string`. Адаптер
-исполнения может передать третьим аргументом собственную полную scalar map:
-
-```ts
-import type { DefaultScalarOutputTypeMap, ResultOf } from '@query-graph/core/dsl'
 
-type DriverScalars = Omit<DefaultScalarOutputTypeMap, 'int64' | 'dateTime'> & {
-  int64: bigint
-  dateTime: Date
-}
-
-type DriverUserRow = ResultOf<typeof definition, typeof operation, DriverScalars>
+const mappedOrders = registerDefinition(ordersDefinition).withRelationalMapping(orderMapping)
+const ordersGraph = composeGraph({ root: mappedOrders, relations: [items] })
 ```
 
-Для точного учета явного `select` operation должна сохранять literal tuple через
-`as const` или `satisfies`. Это только TypeScript API: wire definition, N-API и
-Rust planner не получают дополнительного runtime state.
-
-`ResultOf` описывает логическую форму одной строки, восстановленную из путей
-проекции. Он не выполняет запрос и не превращает relation `many` в массив.
-Группировка строк, дедупликация и гидратация коллекций остаются ответственностью
-потребителя модуля.
-
-## Диагностика
+Обычные source и projection declarations здесь свернуты в именованные
+константы. <code>customerObject</code> и <code>latestPaymentObject</code> созданы
+через <code>projectObject</code>, поэтому отсутствующая to-one строка становится
+<code>null</code>.
 
-Ошибки N-API имеют имя `QueryGraphError` и сохраняют обычный `message` и stack.
-Для программной обработки доступны:
-
-- `code` — категория ошибки на границе пакета;
-- `phase` — `definition`, `mapping`, `operation` или `sql`;
-- `issues` — массив `{ code, location, message }`.
+Одна и та же definition теперь обслуживает дешевый список:
 
 ```ts
-import type { QueryGraphError } from '@query-graph/core/definition'
-
-try {
-  relationalGraph.compileSqlServer(operation)
-} catch (cause) {
-  const error = cause as QueryGraphError
-
-  if (error.name === 'QueryGraphError') {
-    console.table(error.issues)
-  }
-}
-```
-
-Wire errors, semantic validation и SQL compilation имеют разные верхнеуровневые
-`code`. Коды отдельных `issues` стабильны и не требуют разбора текста `message`.
-
-## Presence объектной проекции
-
-Nullable-поля не позволяют определить, отсутствует ли вложенный объект: существующий
-объект может корректно содержать только `NULL`. Для такой границы definition явно
-задаёт выражение присутствия через `projectObject`:
-
-```ts
-const definition = defineGraph({
-  name: 'users',
-  root: users,
-  sources: [users, profiles],
-  relations: [
-    relation({
-      name: 'profile',
-      from: users,
-      to: profiles,
-      on: eq(users.field('id'), profiles.field('userId')),
-    }),
-  ],
-  objects: [
-    projectObject({
-      path: 'profile',
-      presence: profiles.field('id'),
-    }),
-  ],
-  projection: [
-    project({
-      path: 'profile.displayName',
-      expression: profiles.field('displayName'),
-    }),
-  ],
+const listPlan = ordersGraph.compileSqlServerPlan({
+  select: ['id'],
+  parameters: { organisationId: 42 },
 })
-```
-
-`presence` должно возвращать не-`NULL`, когда объект существует, и `NULL`, когда
-его нет. Обычно для этого используется обязательный идентификатор source за
-optional relation. Маркер не является доступным для выбора полем проекции.
-
-Если operation выбирает хотя бы одно поле под `profile`, planner включает
-presence-выражение в план. SQL compiler добавляет скрытую колонку, например `o0`,
-и возвращает отдельные metadata:
 
-```ts
-statement.objects
-// [{ path: 'profile', presenceColumn: 'o0' }]
+listPlan.root.relations // []
+listPlan.batches // []
 ```
 
-`statement.columns` по-прежнему содержит только публичные поля `c0`, `c1` и так
-далее. Исполнитель сначала восстанавливает результат по `statement.columns`, а
-затем устанавливает объект по `path` в `null`, если соответствующая исходная
-колонка `presenceColumn` равна `NULL`. Для вложенных объектов metadata упорядочены
-от самого глубокого path к внешнему.
-
-Таким образом, исполнитель не угадывает отсутствие объекта по правилу «все поля
-равны `NULL`». `ResultOf` также учитывает declaration и выводит
-`profile: { ... } | null`. Пакет только компилирует SQL и metadata; выполнение
-запроса и materialization остаются у потребителя.
-
-## SQL Server
-
-Реляционное отображение связывает логические источники с физическими таблицами.
-По умолчанию логические имена полей используются как имена колонок. В `columns`
-указываются только переопределения.
+И подробное представление:
 
 ```ts
-const relationalGraph = graph.withRelationalMapping({
-  sources: {
-    users: {
-      table: {
-        schema: 'dbo',
-        name: 'users',
-      },
-    },
-    profiles: {
-      table: {
-        schema: 'dbo',
-        name: 'user_profiles',
-      },
-      columns: {
-        userId: 'user_id',
-        displayName: 'display_name',
-      },
-    },
-  },
+const detailsPlan = ordersGraph.compileSqlServerPlan({
+  select: ['id', 'customer.name', 'latestPayment.amount', 'items.name'],
+  parameters: { organisationId: 42 },
 })
-```
-
-`withRelationalMappings([...])` является формой композиции того же mapping и
-возвращает такой же типизированный `RelationalQueryGraph`.
-
-Операция передается в Rust одним вызовом. Компилятор выбирает необходимые пути
-связей, формирует синтаксис SQL Server и возвращает описания параметров.
-
-```ts
-const operation = {
-  select: ['id', 'profile.displayName'],
-  parameters: {
-    userId: 42,
-  },
-  offset: 0,
-  limit: 25,
-}
-
-const statement = relationalGraph.compileSqlServer(operation)
-
-console.log(statement.sql)
-console.table(statement.bindings)
-console.table(statement.columns)
-console.table(statement.relations)
-```
 
-`statement.bindings` связывает сгенерированные имена, например `p0`, с
-логическими параметрами, например `userId`, и содержит их scalar type.
-Потребитель берет значения из `operation.parameters` и передает их
-своему драйверу базы данных.
+detailsPlan.root.relations.map(({ name }) => name)
+// ['customer', 'latestPayment']
 
-Wire-контракт значений параметров:
-
-| Scalar type | Значение в `operation.parameters`                              |
-| ----------- | -------------------------------------------------------------- |
-| `boolean`   | `boolean`                                                      |
-| `int32`     | целое JavaScript number в диапазоне `int32`                    |
-| `int64`     | безопасное целое JavaScript number или десятичная строка `i64` |
-| `float64`   | JSON number                                                    |
-| `decimal`   | JSON number или десятичная строка без экспоненты               |
-| `string`    | string                                                         |
-| `date`      | непрозрачная для compiler строка                               |
-| `dateTime`  | непрозрачная для compiler строка                               |
-| `binary`    | непрозрачная для compiler строка                               |
-| `json`      | любое JSON-совместимое значение                                |
-
-Optional parameter означает отсутствие ключа, а не `null`. Формат строк
-`date`, `dateTime` и `binary`, а также преобразование scalar type в тип конкретного
-DB driver определяет adapter исполнения. SQL compiler не копирует значения в
-`statement`: binding metadata ссылается на исходный ключ параметра.
-
-Целевую версию можно указать отдельно от operation:
-
-```ts
-const statement = relationalGraph.compileSqlServer(operation, { version: '2019' })
+detailsPlan.batches.map(({ name }) => name)
+// ['items']
 ```
 
-По умолчанию используется SQL Server 2012. SQL Server 2008 поддерживается для
-запросов без `OFFSET/FETCH`; несовместимая pagination отклоняется до исполнения.
-
-Компилятор намеренно не использует логические имена графа как SQL-алиасы.
-Источники получают короткие физические алиасы `t0`, `t1`, а выходные колонки -
-`c0`, `c1`. Поэтому длинные имена источников и пути проекции не зависят от
-ограничений конкретной СУБД на длину идентификаторов.
-
-`statement.columns` сопоставляет физические имена колонок с логическими путями
-проекции, содержит их `scalarType`, `nullable` и цепочки relations.
-`statement.relations` описывает выбранный планировщиком путь связей, включая
-направление, cardinality и фактическую обязательность JOIN. Эти metadata позволяют
-потребителю сопоставить плоские SQL-колонки с логическими путями, не разбирая SQL.
-Группировка строк и гидратация коллекций не входят в контракт пакета и остаются
-ответственностью потребителя.
-
-## Oracle
-
-Oracle использует тот же planner и operation. Отличается только финальный
-dialect renderer:
+Planner не добавляет невыбранную <code>customerOrganisation</code>,
+<code>exists(activePromotion)</code> остается semijoin без размножения root-строк,
+а <code>items</code> загружается одним batch-запросом для всех найденных orders.
 
-```ts
-const statement = relationalGraph.compileOracle(operation)
-const oracle19cStatement = relationalGraph.compileOracle(operation, { version: '19c' })
+## Модель
 
-console.log(statement.sql)
-console.table(statement.bindings)
+```text
+defineGraph
+    |
+    v
+registerDefinition        Rust validation + reusable analysis
+    |
+    v
+withRelationalMapping     logical sources -> physical tables
+    |
+    +---- QueryOperation
+    |          |
+    v          v
+compileSqlServer / compileOracle
+    |
+    v
+CompiledSqlStatement      SQL + bindings + result metadata
+    |
+    v
+application executor      DB connection remains outside query-graph
 ```
 
-Компилятор генерирует именованные параметры `:p0`, Oracle-кавычки идентификаторов,
-нативный порядок `NULLS FIRST`/`NULLS LAST`, конкатенацию через `||` и пагинацию
-`OFFSET`/`FETCH`, доступную начиная с Oracle 12c. `catalog` в `TableName` относится
-к SQL Server и отклоняется Oracle-компилятором; имя схемы поддерживается.
-
-По умолчанию выбирается Oracle 12c. Oracle 11g поддерживается для запросов без
-pagination; `OFFSET/FETCH` для него отклоняется как неподдерживаемая capability.
-
-Оба компилятора поддерживают выбор полей проекции, scalar/list параметры,
-ограничения определения,
-условные ограничения, сортировку по умолчанию, соединения
-`INNER JOIN`/`LEFT JOIN`, summary dimensions/measures и пагинацию
-`OFFSET`/`FETCH`. Общий SQL pipeline выбирает пути связей, фазы `WHERE`/`HAVING`
-и обходит expression AST, а dialect renderer отвечает только за синтаксис
-конкретной СУБД.
-
-Для обычного record-графа пагинация отклоняется, если план проходит через
-relation с cardinality `many`: JOIN в таком случае меняет количество корневых
-строк. Summary-граф может пагинировать результат после группировки, поэтому
-relation `many` для него допустим. Для пагинации вложенных record-коллекций
-по-прежнему понадобится отдельный split-query plan.
+| Понятие                           | Ответственность                                                    |
+| --------------------------------- | ------------------------------------------------------------------ |
+| <code>GraphDefinition</code>      | sources, parameters, relations, constraints, projection и ordering |
+| <code>GraphModule</code>          | переиспользуемая часть definition без собственного root            |
+| <code>QueryGraph</code>           | проверенный и проиндексированный нативный граф                     |
+| <code>RelationalMapping</code>    | таблицы, схемы и физические имена колонок                          |
+| <code>QueryOperation</code>       | select, parameters, ordering и pagination одного запроса           |
+| <code>CompiledSqlStatement</code> | SQL и контракт результата для executor                             |
 
-Фильтры времени выполнения и пользовательские отображения семантических функций
-намеренно оставлены для последующих этапов.
+## Куда дальше
 
-Полный пример графа, отображения, операции, сгенерированного SQL и замера
-производительности компиляции находится в `benchmark/bench.ts`.
+- [Authoring DSL](docs/authoring.md): sources, expressions, relations,
+  constraints, projections, ordering и summary.
+- [Composition](docs/composition.md): GraphModule, batchQuery, batchRelation и
+  двухфазное выполнение.
+- [Type system](docs/type-system.md): scalar types, nullability,
+  <code>QueryOperation</code> и <code>ResultOf</code>.
+- [SQL compilation](docs/sql.md): relational mapping, dialect versions,
+  bindings и контракт executor.
+- [Diagnostics](docs/diagnostics.md): фазы ошибок, коды и границы runtime
+  validation.
 
-## Batch-связи и двухфазное выполнение
+## Entry Points
 
-Поля из отдельного запроса подключаются без изменения обычного relational-графа:
+Канонический API:
 
 ```ts
-const childrenQuery = batchQuery({
-  graph: childrenGraph,
-  key: {
-    path: 'parentId',
-    parameter: parentIds,
-  },
-})
-
-const children = batchRelation({
-  name: 'children',
-  from: 'id',
-  query: childrenQuery,
-  cardinality: 'many',
-})
-
-const graph = composeGraph({ root: rootGraph, relations: [children] })
-const plan = graph.compileOraclePlan({
-  select: ['id', 'children.id'],
-  parameters: {},
-  limit: 20,
-})
+import { registerDefinition } from '@query-graph/core'
+import { defineGraph, relation, project } from '@query-graph/core/dsl'
 ```
 
-`batchQuery` принадлежит child-модулю и один раз закрепляет его graph,
-projection path ключа и list-параметр. Поэтому разные root-графы могут
-переиспользовать query, не повторяя внутренний контракт child-запроса.
+<code>@query-graph/core/definition</code> сохраняет позиционные фабрики только
+для обратной совместимости с ранним API 1.x.
+<code>@query-graph/dsl-object</code> остается тонким deprecated facade над
+<code>@query-graph/core/dsl</code>. Новому коду эти entrypoint не нужны.
 
-`composeGraph` оставляет в JavaScript только декларативный фасад. Проверка
-совместимости ключей и параметров, разделение operation на root и batch-шаги и
-компиляция SQL выполняются в Rust. `compileOraclePlan` или
-`compileSqlServerPlan` сразу компилирует только `plan.root`; child SQL создаётся
-при вызове `compileBatch`. Plan сохраняет выбранные dialect и version, поэтому
-отложенный statement компилируется с теми же настройками, что и root.
+Batch-фабрики временно доступны из package root, но новый код должен импортировать
+их из <code>@query-graph/core/dsl</code>.
 
-Для подготовки child bindings каждый шаг в `plan.batches` также содержит имя
-ключевого параметра `keyParameter` и снимок статических `parameters`. Executor
-объединяет их с `{ [batch.keyParameter]: keys }` и сопоставляет полученные значения
-с возвращёнными `statement.bindings`.
+## Архитектура
 
-Executor потребителя выполняет `plan.root`, собирает уникальные ненулевые
-значения `parentKey` из `plan.batches`, вызывает
-`plan.compileBatch('children', parentIds)`, выполняет child statement и
-связывает строки по `childKey`. `cardinality: 'one'` означает объект или `null`,
-а `many` — массив. Query-graph не подключается к БД, не дедуплицирует ключи, не
-выполняет statements и не гидратирует результат; при пустом наборе ключей
-executor должен пропустить child-запрос.
-
-Ordering, offset и limit корневой operation применяются только к `plan.root`.
-Batch-связь может задать собственный `ordering`, но child pagination не
-добавляется. Batch-поля выбираются только явно (`children.id`); без prefixed
-path соответствующего шага в `plan.batches` нет. Флаги injection в metadata
-показывают executor, какие ключи были добавлены исключительно для связывания и
-не должны попасть в публичный результат.
-
----
-
-### Rule 34
+<code>query-graph-core</code> не зависит от Node.js. В нем находятся wire model,
+analysis, type checker, planner, relational mapping и SQL compilers. Корневой
+Rust crate содержит только N-API adapter и перевод diagnostics/metadata в
+JavaScript.
 
-> Every sufficiently generic abstraction eventually gets an implementation.
+SQL execution намеренно остается у потребителя. Это позволяет использовать
+любой pool, transaction model, tracing и политику retry, не связывая planner с
+конкретным DB driver.