@nitra/cursor 1.29.4 → 1.30.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 Усі помітні зміни цього модуля документуються тут.
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
+# [1.30.0] - 2026-05-29
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 2.1 → 3.0) — viewer-story повністю переписано під **Zed + marksman LSP без site-generator-а**. MkDocs Material і pymdownx-розширення (`!!! note`, `??? engineer`, `=== "tab"`, кастомні audience-CSS) прибрані як рекомендація: їх не рендерить вбудований MD-preview Zed, що ламає принцип «відкрив файл = бачу фінальний вигляд». Collapsible-блоки для змішаної аудиторії — через нативний HTML5 `<details>` / `<summary>`, що рендериться скрізь (Zed preview, GitHub, будь-який майбутній збирач) без розширень парсера. Введено **portable-only subset**: CommonMark + GFM + Mermaid у fenced code + KaTeX + `<details>`; заборонені VitePress containers (`::: tip`), MDX/Astro-компоненти, Hugo shortcodes, AsciiDoc-вкраплення, RST-директиви. Конвенція маркера у `<summary>`: перше слово — аудиторія з фіксованого словника (`Engineer:`/`Ops:`/`Security:`/`Manager:`) → детермінований regex для валідатора. Валідатор отримав чотири нові перевірки: жоден `Engineer:`/`Ops:`/`Security:` блок у manager-only проекціях; кожен `<details>` має оточуючі порожні рядки (інакше `<summary>` рендериться як plain HTML); у `docs/` немає заборонених framework-specific конструкцій; inter-doc посилання працюють для marksman LSP (відносні шляхи або wiki-links). Промпт-скелет LLM-проекцій оновлено — генератор видає `<details>`, не `???`, і дотримується списку заборонених синтаксисів. Subset **forward-compatible**: будь-який збирач (MkDocs, VitePress, Antora) підключається пізніше без переписування контенту. Дзеркало `.cursor/rules/n-ci4.mdc` синхронізується наступним прогоном `npx @nitra/cursor`.
+
+## [1.29.5] - 2026-05-29
+
+### Added
+
+- **`rules/js-bun-db/js-bun-db.mdc`** (`version` 1.11 → 1.12) і дзеркало `.cursor/rules/n-js-bun-db.mdc` — нова секція **`## sql.array(arr, type) для передачі масивів`**: обов'язкове використання `pgWrite.array(arr, type)` / `pgRead.array(arr, type)` замість прямої підстановки JS-масиву `${arr}` або cast-синтаксису `${arr}::type[]` у Bun SQL template literal. Другий аргумент типу обов'язковий — без нього Bun не може вивести pg-тип. Секція містить таблицю заборонених/дозволених патернів, таблицю відповідності JS↔PostgreSQL типів і повний приклад UNNEST + MERGE. Рядок `| Масив значень у \`unnest(...)\` | \`sql.array(arr, type)\` — обов'язково з типом |` додано до таблиці рішень.
+- **`rules/bun/bun.mdc`** (`version` 2.0 → 2.1) і дзеркало `.cursor/rules/n-bun.mdc` — `@playwright/test` додано до **root-only** винятків у `devDependencies` кореневого `package.json` (поряд із Vitest/Stryker peer/tools для `n-cursor coverage`).
+- **`rules/bun/policy/package_json/package_json.rego`** — `"@playwright/test"` додано до набору `allowed_root_test_deps`; дозволяє споживачам тримати пакет у root `devDependencies` без порушення bun-policy.
+- **`rules/bun/policy/package_json/package_json_test.rego`** — новий тест `test_allow_playwright_test`: перевіряє, що `@playwright/test` у root `devDependencies` не генерує deny.
 
 ## [1.29.4] - 2026-05-29
 
@@ -40,7 +54,6 @@
 
 - **`rules/ci4/ci4.mdc`** (`version` 2.0 → 2.1) — додано секцію **«Зв'язок із `.cursor/rules`»**: архітектурна документація у `docs/` не дублює зміст `.cursor/rules/*.mdc` (операційні правила лінту, тестів, CHANGELOG, версіонування), а посилається на потрібне правило через його ім'я у бектиках (наприклад, `див. **`changelog`**`). Дублікати розходяться з оригіналом і ламають automatic-перевірки `npx @nitra/cursor fix`/`check`; правки робляться в одному місці — у самому `.mdc`.
 
-
 ## [1.28.8] - 2026-05-28
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.29.4",
+  "version": "1.30.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/bun/bun.mdc

@@ -2,7 +2,7 @@
 description: Bun як єдиний package manager у монорепо
 globs: "**/package.json,**/bunfig.toml,**/bun.lock,**/bun.lockb"
 alwaysApply: false
-version: '2.0'
+version: '2.1'
 ---
 
 Проект використовує тільки Bun для керування залежностями та запуску скриптів.
@@ -42,7 +42,7 @@ Lockfile у репозиторії: `bun.lock`.
 - Якщо залежність потрібна лише одному пакету, додавати її в директорії цього пакета.
 - У CI та локально запускати скрипти через `bun run`.
 
-В кореневому `package.json` не повинно бути `dependencies`, а в `devDependencies` — тільки модулі `@nitra/*`. **Виняток (root-only)** — Vitest/Stryker peer/tools для `n-cursor coverage`: `vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`. Тримати їх **у корені** доводиться у будь-якому монорепо-споживачі, бо правило `test` enabled завжди (`test/auto.md` = `завжди`), а класти ці пакети у workspace-и не можна: published пакети (`npm-module.mdc`) не мають мати `devDependencies`, а інші workspace-и однаково запускають coverage оркестратор з кореня. Якщо в package.json є поля `packageManager`, то прибрати їх, також прибрати всі директорії та файли для yarn.
+В кореневому `package.json` не повинно бути `dependencies`, а в `devDependencies` — тільки модулі `@nitra/*`. **Виняток (root-only)** — Vitest/Stryker peer/tools для `n-cursor coverage`: `vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`; а також `@playwright/test` для e2e-тестів. Тримати їх **у корені** доводиться у будь-якому монорепо-споживачі, бо правило `test` enabled завжди (`test/auto.md` = `завжди`), а класти ці пакети у workspace-и не можна: published пакети (`npm-module.mdc`) не мають мати `devDependencies`, а інші workspace-и однаково запускають coverage оркестратор з кореня. Якщо в package.json є поля `packageManager`, то прибрати їх, також прибрати всі директорії та файли для yarn.
 
 - Заборонені top-level поля у root `package.json` (з причинами): [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
 

package/rules/bun/policy/package_json/package_json.rego

@@ -68,7 +68,7 @@ deny contains msg if {
 
 # ── helpers ────────────────────────────────────────────────────────────────
 
-allowed_root_test_deps := {"vitest", "@vitest/coverage-v8", "@stryker-mutator/vitest-runner"}
+allowed_root_test_deps := {"vitest", "@vitest/coverage-v8", "@stryker-mutator/vitest-runner", "@playwright/test"}
 
 allowed_root_dev_dependency(name) if {
 	startswith(name, "@nitra/")

package/rules/ci4/ci4.mdc

@@ -1,7 +1,7 @@
 ---
-description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; MkDocs Material як viewer з collapsible engineer-блоками для змішаної аудиторії
+description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; Zed + marksman LSP як viewer без site-generator-а, portable subset (CommonMark + GFM + Mermaid + KaTeX), collapsible engineer-блоки через нативний `<details>`
 alwaysApply: true
-version: '2.1'
+version: '3.0'
 ---
 
 Архітектурна документація проєкту живе у Markdown поряд із кодом. Це не довідник «для людей із порталу архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops).
@@ -47,7 +47,7 @@ RAG витягує **фрагменти**, не цілі документи. Т
 
 Доповнюємо **під domain**:
 
-- **DDD Context Maps** — коли є >1 bounded context (типово для multi-agent: agents, orchestration, memory, tooling). Одна Mermaid-діаграма в `explanation/architecture.md`, ховається під `??? engineer`.
+- **DDD Context Maps** — коли є >1 bounded context (типово для multi-agent: agents, orchestration, memory, tooling). Одна Mermaid-діаграма в `explanation/architecture.md`, ховається під `<details><summary><strong>Engineer:</strong> Context Map</summary>`.
 - **EventModeling** — для event-driven систем (агентські pipeline, CQRS, Event Sourcing). Структура: trigger → command → event → read model. Читається менеджером як наратив, інженером — як креслення.
 - **Business Capability Map** — верхньорівневий manager-overview. Autogen через семантичну класифікацію accepted ADR за тематикою.
 - **Wardley Map** — стратегічний артефакт для board/інвесторів. Manual, не autogen. Квартальне оновлення. Живе в `explanation/strategy.md`.
@@ -108,7 +108,7 @@ docs/
 
 ## Гібрид manual + autogen
 
-Реальні проєкти мають legacy docs, написані до появи ADR. Розв'язок — **зони** через HTML-коментарі (виживають у Markdown, не рендеряться у MkDocs):
+Реальні проєкти мають legacy docs, написані до появи ADR. Розв'язок — **зони** через HTML-коментарі (виживають у Markdown, не рендеряться у жодному MD viewer — ні в Zed built-in preview, ні на GitHub, ні в будь-якому майбутньому site-generator-і):
 
 ```markdown
 # User Service
@@ -191,61 +191,68 @@ User Service відповідає за автентифікацію та про
 - **Incremental**: LLM отримує поточний doc + новий ADR (або `## Update`) — видає diff. Дешевше, але дрейф накопичується.
 - **Компроміс**: incremental + періодичний full rebuild (раз на місяць або після N нових ADR).
 
-## MkDocs Material: collapsible engineer-блоки
+## Viewer/editor: Zed + marksman LSP
 
-Менеджер читає прозу зверху, інженер клікає `??? engineer` і провалюється глибше. Один документ — дві аудиторії без дублювання.
+Окремого site-generator-а **немає** — каталог `docs/` сам є інтерфейсом читання. Інженер відкриває `.md`-файл у Zed і одразу бачить рендер через built-in preview (`cmd+shift+m`). Між сторінками рухається через **`marksman`** LSP: `cmd+click` по `[link](file.md)` і `[[wiki-link]]`, автокомпліт заголовків, find-references, refactor-перейменування заголовків з оновленням посилань у всьому `docs/`.
 
-`mkdocs.yml`:
+`~/.config/zed/settings.json`:
 
-```yaml
-theme:
-  name: material
-  features:
-    - content.code.copy
-    - navigation.tabs
+```json
+{
+  "languages": {
+    "Markdown": {
+      "language_servers": ["marksman"],
+      "soft_wrap": "editor_width"
+    }
+  }
+}
+```
 
-markdown_extensions:
-  - admonition
-  - pymdownx.details
-  - pymdownx.superfences
-  - pymdownx.tabbed: { alternate_style: true }
-  - attr_list
+**Portable-only синтаксис.** Усе, що пишемо в `docs/`, обмежене **CommonMark + GFM + Mermaid у fenced code (` ```mermaid `) + KaTeX (`$...$`) + нативний HTML5 `<details>`**. Заборонено:
 
-extra_css:
-  - stylesheets/audience.css
-```
+- pymdownx admonitions (`!!! note`, `??? engineer`, `=== "tab"`)
+- VitePress containers (`::: tip`, `::: details`)
+- MDX/Astro-компоненти (`<MyComponent />`)
+- Hugo shortcodes (`{{< youtube id >}}`)
+- AsciiDoc-вкраплення, RST-директиви
+
+Усе вище не рендериться у Zed built-in preview і ламає головний принцип: **«відкрив файл = побачив фінальний вигляд»**. Обмеження **forward-compatible**: portable subset рендериться у GitHub, MkDocs, VitePress, Antora — підключення збирача в майбутньому не потребує переписування контенту.
 
-Синтаксис у документах:
+## Collapsible-блоки для змішаної аудиторії
+
+Менеджер читає прозу зверху, інженер розгортає деталі. Реалізація — нативний HTML5 `<details>` / `<summary>`, що рендериться **скрізь**: Zed preview, GitHub, будь-який майбутній збирач. Жодних розширень парсера не треба.
 
 ```markdown
 User Service автентифікує користувачів і керує профілями.
 Підтримуємо OIDC-логін та email/password.
 
-??? engineer "Технічна реалізація автентифікації"
-    OIDC-сервер на Fastify з PKCE flow [oidc-pkce-flow].
-    Refresh-токени з rotation, TTL 30 днів, Redis storage.
+<details>
+<summary><strong>Engineer:</strong> Технічна реалізація автентифікації</summary>
+
+OIDC-сервер на Fastify з PKCE flow [oidc-pkce-flow].
+Refresh-токени з rotation, TTL 30 днів, Redis storage.
+
+</details>
 
 Профілі зберігаються в основній БД, кешуються в Redis на 5 хв.
 
-??? ops "Деталі кешу та інвалідації"
-    Cache key: `user:profile:{userId}:v2`.
-    Інвалідація — NATS подія `user.profile.updated` [user-profile-events].
+<details>
+<summary><strong>Ops:</strong> Деталі кешу та інвалідації</summary>
+
+Cache key: `user:profile:{userId}:v2`.
+Інвалідація — NATS подія `user.profile.updated` [user-profile-events].
+
+</details>
 ```
 
-`???` = згорнуто за замовчуванням, `???+` = розгорнуто.
+**Конвенція маркера у `<summary>`:** перше слово — аудиторія з фіксованого словника (`Engineer:`, `Ops:`, `Security:`, `Manager:`), далі — описова назва. Це дає валідатору детермінований regex для перевірок типу «жоден `Engineer:`-блок не з'являється в manager-only проекціях».
 
-Кастомні audience-styles у `docs/stylesheets/audience.css`:
+**Технічні нюанси `<details>`:**
 
-```css
-.md-typeset details.engineer > summary {
-  background-color: rgba(84, 110, 122, 0.1);
-  border-color: #546e7a;
-}
-.md-typeset details.ops > summary {
-  background-color: rgba(255, 152, 0, 0.1);
-  border-color: #ff9800;
-}
-```
+- порожній рядок до `<details>` і після `<summary>` обов'язковий — інакше Markdown-парсер не активує блочний рендер усередині
+- за замовчуванням блок згорнутий; `<details open>` — розгорнутий
+- візуальна типізація аудиторій робиться **через текст `<summary>`**, не через CSS — у Zed preview кастомні стилі недоступні
+- `<details>` ≠ HTML-обгортка з правила «жодних `<div>`/`<span>`»: це **семантичний** HTML5-елемент, а не презентаційний; його token-cost мізерний
 
 ## Промпт для LLM-проекцій
 
@@ -259,21 +266,35 @@ User Service автентифікує користувачів і керує п
    як пов'язано з іншими частинами продукту. Без технологій, версій, коду.
 
 2. Технічні деталі — тільки всередині блоків:
-   ??? engineer "Описова назва блоку"
-       Код, конфіги, версії, посилання на ADR.
+   <details>
+   <summary><strong>Engineer:</strong> Описова назва блоку</summary>
+
+   Код, конфіги, версії, посилання на ADR.
+
+   </details>
 
 3. Operational деталі:
-   ??? ops "Що моніторити та як реагувати"
+   <details>
+   <summary><strong>Ops:</strong> Що моніторити та як реагувати</summary>
+
+   Метрики, алерти, runbook-кроки.
+
+   </details>
 
 Правила:
-- Якщо прибрати всі ??? блоки, текст лишається зв'язним менеджерським документом.
-- Кожен факт з ADR маркуй [<slug>] всередині engineer-блоку — slug це ім'я clean ADR
+- Якщо прибрати всі <details>-блоки, текст лишається зв'язним менеджерським документом.
+- Перше слово у <summary> — аудиторія з фіксованого словника
+  (Engineer:/Ops:/Security:/Manager:), далі — описова назва
+  (наприклад «<strong>Engineer:</strong> Чому Percona, а не MariaDB»).
+- Порожній рядок до і після вмісту <details> обов'язковий.
+- Кожен факт з ADR маркуй [<slug>] всередині <details>-блоку — slug це ім'я clean ADR
   без розширення (наприклад `[ланцюжок-запуску-abie]`).
-- Назви блоків — описові («Чому Percona, а не MariaDB»).
 - НЕ виходь за межі <!-- AUTOGEN:start --> ... <!-- AUTOGEN:end -->.
 - ADR без рядка `**Status:** Accepted` ігноруй.
 - Якщо в ADR є `## Update YYYY-MM-DD` секції — враховуй найсвіжіший стан рішення,
   старі формулювання вважай застарілими.
+- Заборонені framework-specific synaxes: !!! note, ??? engineer, ::: tip,
+  MDX-компоненти, Hugo shortcodes — тільки CommonMark + GFM + Mermaid + <details>.
 ```
 
 ## Типові поломки LLM і захист
@@ -293,7 +314,10 @@ User Service автентифікує користувачів і керує п
 - Усі `[<slug>]` посилання вказують на існуючі файли `docs/adr/<slug>.md` із рядком `**Status:** Accepted`
 - Усі `AUTOGEN:start` мають парний `AUTOGEN:end` з тим самим `id`
 - Hash у `manifest.json` відповідає фактичному контенту зон
-- Жоден `??? engineer` блок не з'являється в manager-only проекціях
+- Жоден `<details>`-блок з `<summary>` що починається на `Engineer:` / `Ops:` / `Security:` не з'являється в manager-only проекціях
+- Кожен `<details>` має оточуючі порожні рядки (інакше `<summary>`-вміст рендериться як plain HTML, не collapsible)
+- У `docs/` немає заборонених framework-specific конструкцій: `!!! note`, `??? `, `::: tip`, `::: details`, MDX-теги `<[A-Z][a-zA-Z]*`, Hugo shortcodes `{{< `
+- Усі inter-doc посилання працюють для `marksman` LSP (відносні шляхи `[text](./other.md)` або `[[wiki-link]]`, не absolute URLs усередині `docs/`)
 - Якщо в зоні згадано компонент — він є в `docs/glossary.md`
 - ADR без `**Status:** Accepted` не потрапили у проекцію
 
@@ -317,7 +341,7 @@ ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-про
 
 ## Зв'язок із документацією
 
-Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». MkDocs Material рендерить це з collapsible-блоками, тому менеджер бачить прозу, інженер провалюється в деталі.
+Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». Нативний `<details>`-блок дає collapsible-вигляд у будь-якому MD-viewer (Zed built-in preview, GitHub web UI, потенційний майбутній site-generator) без залежності від конкретного фреймворку — менеджер бачить прозу, інженер розгортає деталі.
 
 ## Зв'язок із `.cursor/rules`
 
@@ -330,8 +354,11 @@ ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-про
 - **Claude Code** як runner — slash-команда `/regen-docs` або post-commit hook на зміни `docs/adr/**`
 - **capture-decisions.sh** + **normalize-decisions.sh** — Stop-hooks створення ADR (керує правило `adr`)
 - **gray-matter** на Bun — лише для парсингу draft frontmatter; clean ADR парситься regexp по `**Status:**` / `**Date:**`
-- **MkDocs + Material** як viewer
-- **Mermaid** для C4-діаграм, EventModeling, Context Maps у проекціях
+- **Zed** як viewer/editor — built-in MD preview (`cmd+shift+m`) рендерить кожен файл без site-generator-а; `<details>` для collapsible-блоків
+- **marksman** LSP як шар навігації — `cmd+click` по `[text](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування заголовків
+- **Mermaid** для C4-діаграм, EventModeling, Context Maps — рендериться у Zed preview напряму з ` ```mermaid ` fenced code, без розширень
+- **KaTeX** (опційно) — інлайн-математика `$...$` для метрик/формул; рендериться у Zed preview
+- Site-generator (MkDocs Material / VitePress / Antora) — **не використовується**; portable subset гарантує, що його можна підключити пізніше без переписування контенту
 
 ## Query mode як бонус
 

package/rules/js-bun-db/js-bun-db.mdc

@@ -2,7 +2,7 @@
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 globs: "**/package.json,**/src/conn/**"
 alwaysApply: false
-version: '1.11'
+version: '1.12'
 ---
 
 ## Підтримувані версії баз даних
@@ -276,6 +276,7 @@ const rows = await sql.unsafe(query, values)
 | Динамічний `WHERE` (полів багато) | whitelist + ручні `$N` + `sql.unsafe(text, vals)`    |
 | Сирий migration / DDL             | `sql.unsafe(text)` з `// allow-unsafe: <причина>`    |
 | User input як value               | **тільки** Bun parameters / `$N` bind                |
+| Масив значень у `unnest(...)`     | `sql.array(arr, type)` — обов'язково з типом         |
 
 Головне правило:
 
@@ -384,6 +385,73 @@ await sql.begin(async tx => {
 })
 ```
 
+## `sql.array(arr, type)` для передачі масивів
+
+Коли JS-масив передається як параметр у Bun SQL template literal всередині `unnest(...)` або іншого контексту, де PostgreSQL очікує типізований масив (`int4[]`, `uuid[]` тощо), — обов'язково використовувати `sql.array(arr, type)` (або `pgWrite.array` / `pgRead.array` — вони є екземплярами `SQL`). Другий аргумент (тип елементів) — обов'язковий.
+
+### Заборонені патерни
+
+```javascript
+// ❌ пряма підстановка масиву — Bun серіалізує як рядок, не як pg-масив
+${ids}
+
+// ❌ cast-синтаксис без .array() — працює в деяких версіях, але не гарантований
+${ids}::int8[]
+
+// ❌ відсутній тип — Bun не може вивести тип pg, можливий mismatch
+sql.array(ids)
+```
+
+### Дозволені патерни
+
+```javascript
+// ✅ pgWrite.array з явним типом
+${pgWrite.array(ids, 'int8')}
+${pgWrite.array(uuids, 'uuid')}
+${pgWrite.array(flags, 'bool')}
+${pgWrite.array(amounts, 'numeric')}
+${pgWrite.array(names, 'text')}
+${pgWrite.array(dates, 'date')}
+${pgWrite.array(timestamps, 'timestamptz')}
+
+// ✅ pgRead.array — те саме правило
+${pgRead.array(ids, 'int4')}
+```
+
+### Таблиця типів
+
+| JS-тип        | PostgreSQL тип | Аргумент        |
+| ------------- | -------------- | --------------- |
+| number (int)  | int4           | `'int4'`        |
+| bigint / id   | int8           | `'int8'`        |
+| UUID string   | uuid           | `'uuid'`        |
+| boolean       | bool           | `'bool'`        |
+| decimal/float | numeric        | `'numeric'`     |
+| string        | text           | `'text'`        |
+| date string   | date           | `'date'`        |
+| ISO datetime  | timestamptz    | `'timestamptz'` |
+
+### Повний приклад (UNNEST + MERGE)
+
+```javascript
+await pgWrite`
+  MERGE INTO "order".product p
+  USING (
+    SELECT * FROM unnest(
+      ${pgWrite.array(rows.map(r => r.order_id), 'uuid')},
+      ${pgWrite.array(rows.map(r => r.product_id), 'int4')},
+      ${pgWrite.array(rows.map(r => r.qty), 'numeric')},
+      ${pgWrite.array(rows.map(r => r.is_refund), 'bool')}
+    ) AS s(order_id, product_id, qty, is_refund)
+  ) AS s ON p.order_id = s.order_id AND p.product_id = s.product_id
+  WHEN MATCHED THEN
+    UPDATE SET qty = s.qty
+  WHEN NOT MATCHED THEN
+    INSERT (order_id, product_id, qty, is_refund)
+    VALUES (s.order_id, s.product_id, s.qty, s.is_refund)
+`
+```
+
 ## Коментар під час виправлення SQL injection
 
 Коли виправляєш місце з потенційним **SQL injection** (наприклад, заміна конкатенації/`.join(',')` на `sql(ids)` або перехід з `sql.unsafe(...)` на tagged template), **додай поруч короткий коментар** з описом причини.