feat(query): public identifier()/unsafe, backtick escaping, docs and tests

  - API: add sql.identifier() and sql.unsafe() to QueryClient and re-export from @ydbjs/query.
  - Security: identifier() now escapes backticks inside names (`` ` → ````) to prevent injection via identifiers.
  - Docs:
      - README.md: link to Russian README, section on identifiers and unsafe fragments, note that options apply only to single execute calls, add missing StatsMode imports in examples.
      - Add README.ru.md with comprehensive guide and examples.
      - SECURITY.md: examples migrated to sql/query(driver), add allow-list/validation patterns for dynamic identifiers.
      - package.json: update homepage to package page.
  - Tests: cover backtick escaping in identifier(), verify public re-exports of identifier/unsafe, minor formatting fixes.

  No breaking changes.

Signed-off-by: Vladislav Polyakov <[email protected]>

Author: polRk

packages/query/README.md

@@ -1,5 +1,7 @@
 # @ydbjs/query
 
+Read this in Russian: [README.ru.md](README.ru.md)
+
 The `@ydbjs/query` package provides a high-level, type-safe client for executing YQL queries and managing transactions in YDB. It features a tagged template API, automatic parameter binding, transaction helpers, and deep integration with the YDB type system.
 
 ## Features
@@ -89,6 +91,7 @@ await sql.begin({ isolation: 'snapshotReadOnly', idempotent: true }, async (tx)
 ### Advanced: Multiple Result Sets, Streaming, and Events
 
 ```ts
+import { StatsMode } from '@ydbjs/api/query'
 // Multiple result sets
 type Result = [[{ id: number }], [{ count: number }]]
 const [rows, [{ count }]] = await sql<Result>`SELECT id FROM users; SELECT COUNT(*) as count FROM users;`
@@ -116,13 +119,16 @@ try {
 ### Query Options and Chaining
 
 ```ts
+import { StatsMode } from '@ydbjs/api/query'
 await sql`SELECT * FROM users`
   .isolation('onlineReadOnly', { allowInconsistentReads: true })
   .idempotent(true)
   .timeout(5000)
   .withStats(StatsMode.FULL)
 ```
 
+Note: isolation(), idempotent(), timeout(), and withStats() apply to single execute calls only; they are ignored inside transactions (sql.begin/sql.transaction).
+
 ### Value Conversion and Type Safety
 
 All parameter values are converted using `@ydbjs/value`. See its documentation for details on supported types and conversion rules. You can pass native JS types, or use explicit YDB value classes for full control.
@@ -137,11 +143,34 @@ await sql`SELECT * FROM users WHERE meta = ${fromJs({ foo: 'bar' })}`
 You can enable and access query execution statistics:
 
 ```ts
+import { StatsMode } from '@ydbjs/api/query'
 const q = sql`SELECT * FROM users`.withStats(StatsMode.FULL)
 await q
 console.log(q.stats())
 ```
 
+## Identifiers and Unsafe Fragments
+
+- Use identifiers for dynamic table/column names:
+
+```ts
+// As a method on the client
+await sql`SELECT * FROM ${sql.identifier('users')}`
+
+// Or import from the package if needed
+import { identifier } from '@ydbjs/query'
+await sql`SELECT * FROM ${identifier('users')}`
+```
+
+- Use unsafe only for trusted SQL fragments (never with user input):
+
+```ts
+import { unsafe } from '@ydbjs/query'
+await sql`SELECT * FROM users ${unsafe('ORDER BY created_at DESC')}`
+```
+
+Security note: identifier() only quotes the name and escapes backticks. Do not pass untrusted input without validation/allow‑listing.
+
 ## Development
 
 ### Building the Package

packages/query/README.ru.md

@@ -0,0 +1,215 @@
+# @ydbjs/query
+
+Читать на английском: [README.md](README.md)
+
+`@ydbjs/query` — высокоуровневый, типобезопасный клиент для выполнения YQL‑запросов и управления транзакциями в YDB. Поддерживает теговый шаблонный синтаксис, автоматическое связывание параметров, хелперы транзакций и глубокую интеграцию с типовой системой YDB.
+
+## Возможности
+
+- Теговый шаблонный синтаксис для YQL
+- Типобезопасное связывание параметров (включая сложные/вложенные типы)
+- Транзакции с настройками изоляции и идемпотентности
+- Несколько результирующих наборов и стриминг
+- Статистика выполнения и диагностика
+- Полные типы TypeScript
+
+## Установка
+
+```sh
+npm install @ydbjs/core@alpha @ydbjs/query@alpha
+```
+
+## Как это работает
+
+- **Query‑клиент**: создайте клиент `query(driver)`. Он возвращает теговую функцию для YQL и хелперы транзакций.
+- **Сессии и транзакции**: управление жизненным циклом выполняется автоматически. Можно запускать одиночные запросы или объединять несколько запросов в транзакцию через `begin`/`transaction`.
+- **Параметры**: параметры передаются через интерполяцию (`${}`) в шаблоне. Поддерживаются нативные типы JS, классы значений YDB и массивы/объекты. Для именованных параметров используйте `.parameter()`/`.param()`.
+- **Безопасность типов**: все значения конвертируются с помощью `@ydbjs/value`. Сложные и вложенные типы обрабатываются автоматически.
+- **Результаты**: YDB может возвращать несколько наборов результатов за один запрос.
+- **Статистика**: используйте `.withStats()` или `.stats()` для доступа к статистике выполнения.
+
+## Использование
+
+### Быстрый старт
+
+```ts
+import { Driver } from '@ydbjs/core'
+import { query } from '@ydbjs/query'
+
+const driver = new Driver('grpc://localhost:2136/local')
+await driver.ready()
+
+const sql = query(driver)
+const resultSets = await sql`SELECT 1 + 1 AS sum`
+console.log(resultSets) // [ [ { sum: 2 } ] ]
+```
+
+### Параметризованные запросы
+
+```ts
+const userId = 42n
+const userName = 'Alice'
+await sql`
+  SELECT * FROM users
+  WHERE id = ${userId} AND name = ${userName}
+`
+```
+
+#### Именованные параметры и кастомные типы
+
+```ts
+import { Uint64 } from '@ydbjs/value/primitive'
+const id = new Uint64(123n)
+await sql`SELECT * FROM users WHERE id = $id`.parameter('id', id)
+```
+
+#### Массивы, структуры и табличные параметры
+
+```ts
+const users = [
+  { id: 1, name: 'Alice' },
+  { id: 2, name: 'Bob' },
+]
+await sql`INSERT INTO users SELECT * FROM AS_TABLE(${users})`
+```
+
+### Транзакции
+
+```ts
+// Serializable read-write (по умолчанию)
+const result = await sql.begin(async (tx) => {
+  await tx`UPDATE users SET active = false WHERE last_login < CurrentUtcTimestamp() - Interval('P1Y')`
+  return await tx`SELECT * FROM users WHERE active = false`
+})
+
+// С изоляцией и идемпотентностью
+await sql.begin({ isolation: 'snapshotReadOnly', idempotent: true }, async (tx) => {
+  return await tx`SELECT COUNT(*) FROM users`
+})
+```
+
+### Продвинутое: несколько наборов результатов, стриминг и события
+
+```ts
+import { StatsMode } from '@ydbjs/api/query'
+// Несколько наборов результатов
+type Result = [[{ id: number }], [{ count: number }]]
+const [rows, [{ count }]] = await sql<Result>`SELECT id FROM users; SELECT COUNT(*) as count FROM users;`
+
+// Подписка на статистику и ретраи
+const q = sql`SELECT * FROM users`.withStats(StatsMode.FULL)
+q.on('stats', (stats) => console.log('Query stats:', stats))
+q.on('retry', (ctx) => console.log('Retrying:', ctx))
+await q
+```
+
+### Обработка ошибок
+
+```ts
+import { YDBError } from '@ydbjs/error'
+try {
+  await sql`SELECT * FROM non_existent_table`
+} catch (e) {
+  if (e instanceof YDBError) {
+    console.error('YDB Error:', e.message)
+  }
+}
+```
+
+### Опции запроса и чейнинг
+
+```ts
+import { StatsMode } from '@ydbjs/api/query'
+await sql`SELECT * FROM users`
+  .isolation('onlineReadOnly', { allowInconsistentReads: true })
+  .idempotent(true)
+  .timeout(5000)
+  .withStats(StatsMode.FULL)
+```
+
+Внимание: эти опции действуют только для одиночных запросов (один вызов execute). Внутри транзакций (sql.begin/sql.transaction) они игнорируются.
+
+### Конвертация значений и безопасность типов
+
+Все значения конвертируются с помощью `@ydbjs/value`. См. документацию `@ydbjs/value` по типам и правилам конвертации. Можно передавать нативные типы JS или использовать классы YDB для полного контроля.
+
+```ts
+import { fromJs } from '@ydbjs/value'
+await sql`SELECT * FROM users WHERE meta = ${fromJs({ foo: 'bar' })}`
+```
+
+## Статистика запросов
+
+```ts
+import { StatsMode } from '@ydbjs/api/query'
+const q = sql`SELECT * FROM users`.withStats(StatsMode.FULL)
+await q
+console.log(q.stats())
+```
+
+## Идентификаторы и небезопасные фрагменты
+
+- Динамические имена таблиц/колонок — используйте идентификаторы:
+
+```ts
+// Метод клиента
+await sql`SELECT * FROM ${sql.identifier('users')}`
+
+// Или импорт из пакета
+import { identifier } from '@ydbjs/query'
+await sql`SELECT * FROM ${identifier('users')}`
+```
+
+- Небезопасные фрагменты — только для доверенных сценариев (не с данными пользователя):
+
+```ts
+import { unsafe } from '@ydbjs/query'
+await sql`SELECT * FROM users ${unsafe('ORDER BY created_at DESC')}`
+```
+
+Заметка по безопасности: identifier() лишь экранирует обратные кавычки и оборачивает имя в обратные кавычки. Не передавайте туда непроверенный ввод — используйте валидацию/allow‑list.
+
+## Разработка
+
+### Сборка
+
+```sh
+npm run build
+```
+
+### Тесты
+
+```sh
+npm test
+```
+
+## Настройки для AI ассистентов
+
+Этот пакет содержит примеры конфигураций для AI‑ассистентов в каталоге `ai-instructions/`, чтобы генерировать безопасный YQL‑код.
+
+Быстрый старт:
+
+```bash
+# Для Cursor AI
+cp node_modules/@ydbjs/query/ai-instructions/.cursorrules.example .cursorrules
+
+# Для GitHub Copilot
+cp node_modules/@ydbjs/query/ai-instructions/.copilot-instructions.example.md .copilot-instructions.md
+
+# Для прочих ассистентов
+cp node_modules/@ydbjs/query/ai-instructions/.instructions.example.md .instructions.md
+# ИЛИ
+cp node_modules/@ydbjs/query/ai-instructions/.ai-instructions.example.md .ai-instructions.md
+```
+
+См. `SECURITY.md` для полного руководства по безопасности.
+
+## Лицензия
+
+Проект распространяется по лицензии [Apache 2.0](../../LICENSE).
+
+## Ссылки
+
+- Документация YDB: https://ydb.tech
+- Репозиторий: https://github.com/ydb-platform/ydb-js-sdk
+- Issues: https://github.com/ydb-platform/ydb-js-sdk/issues