@avytheone/efmesh 0.1.0-beta.1

package/SPEC.md

@@ -0,0 +1,641 @@
+# EFMESH — спецификация
+
+**efmesh** — фреймворк трансформации данных в духе sqlmesh, но на TypeScript, Bun и Effect v4.
+Не порт sqlmesh, а перенос его *идей* на другую почву: там, где sqlmesh опирается на Python-макросы
+и Jinja, efmesh опирается на систему типов TypeScript и на Effect как рантайм.
+
+Это архитектурный документ: решения, инварианты и открытые вопросы.
+Знакомство с проектом и справка пользователя — в [README](./README.md),
+история изменений — в [CHANGELOG](./CHANGELOG.md).
+
+Статус: v0.2 — реализация прошла фазы F0–F5 (§13), версия пакета
+0.1.0-beta.1; реализованное помечено в тексте уточнениями «*Реализация Fn*».
+
+---
+
+## 1. Зачем
+
+dbt и sqlmesh решают реальную задачу — версионируемые SQL-трансформации с зависимостями,
+инкрементальностью и дешёвыми dev-окружениями. Но оба живут в Python-экосистеме:
+шаблоны на Jinja, макросы на Python, типов нет, интеграция в TypeScript-бэкенд — через subprocess.
+
+efmesh делает то же самое для команды, которая уже живёт в TypeScript и Effect:
+
+- **Модель — это TypeScript-модуль.** Никакого Jinja. Макрос — обычная функция.
+  Ссылка на другую модель — импорт: переименовал модель — компилятор покажет все места.
+- **Схема модели — это Effect Schema.** Колонки типизированы, ссылки на колонки
+  проверяются на этапе компиляции, а соответствие объявленной схемы фактическому
+  результату запроса — на этапе плана.
+- **Всё — Effect.** Типизированные ошибки, Layer для подмены движков, Stream для бэкфилла,
+  Metric/Tracer из коробки. efmesh можно встроить в существующее Effect-приложение
+  как библиотеку — CLI лишь тонкая обёртка.
+- **Bun.** Мгновенный старт CLI, `bun test` для тестов моделей, `bun build --compile`
+  для единого бинарника.
+- **DuckDB как первый движок.** Не просто «локальная аналитика»: httpfs и ATTACH
+  превращают его в лёгкую федерацию (parquet на S3, чужой Postgres, JSON по HTTPS),
+  а материализация в parquet-файлы даёт озеро без отдельной инфраструктуры (§3.3, §9.3).
+
+### Не-цели
+
+- Тяжёлый ингест (EL): очереди, CDC, ретраи по чужим API — не наша забота.
+  Но лёгкое чтение внешнего мира через федерацию DuckDB (parquet/S3, ATTACH-базы,
+  JSON по HTTPS) — законный источник для `external`-моделей: сырьё не обязано
+  заранее лежать «в базе».
+- Оркестрация общего назначения: не замена Airflow/Temporal. Есть свой планировщик
+  по cron, но он про интервалы моделей, не про произвольные пайплайны.
+- BI и визуализация. Максимум — `efmesh graph --html` для отладки DAG.
+- Транспиляция между диалектами SQL (киллер-фича sqlglot). Честно признаём:
+  повторить sqlglot в TS нереалистично. Диалект — свойство проекта, не модели (§9).
+
+---
+
+## 2. Понятийное ядро
+
+Пять понятий, всё остальное — производные:
+
+| Понятие | Что это |
+|---|---|
+| **Модель** | Именованная трансформация: SQL-запрос + метаданные (вид, cron, схема, аудиты). Материализуется в таблицу или view. |
+| **Снапшот** | Версия модели, идентифицируемая fingerprint'ом — хэшем канонизированного SQL и метаданных. Каждому снапшоту соответствует своя физическая таблица. |
+| **Интервал** | Полуинтервал времени `[start, end)`, для которого данные снапшота посчитаны. Учёт заполненных интервалов — основа инкрементальности и бэкфилла. |
+| **Окружение** | Именованный набор view (`dev`, `prod`, `feature_x`), указывающих на физические таблицы снапшотов. Виртуальное: создание окружения — это создание view, не копирование данных. |
+| **План** | Diff между локальными определениями моделей и состоянием окружения + перечень интервалов к пересчёту. Просмотрел → применил. |
+
+Ключевая механика (взята у sqlmesh без изменений, потому что она правильная):
+
+```
+физический слой:  _efmesh.med__stays__a3f9c1            ← таблица по fingerprint
+                  lake/med/stays/fp=a3f9c1/…/*.parquet  ← или parquet-партиции (§3.3)
+виртуальный слой: dev__med.stays → view → физика a3f9c1
+                  med.stays      → view → физика 88b2e0   (prod = родные схемы)
+```
+
+Не изменил модель — dev и prod смотрят на **одну и ту же** физическую таблицу.
+Изменил — в dev появляется новая физическая таблица, prod не тронут.
+Промоушен в prod — переключение view, без копирования данных и без пересчёта.
+
+---
+
+## 3. Определение модели
+
+Модель — TS-модуль, экспортирующий результат `defineModel`:
+
+```ts
+import { defineModel, kind, audit } from "efmesh"
+import { Schema } from "effect"
+import { moves } from "./moves"
+
+export const stays = defineModel({
+  name: "med.stays",
+  kind: kind.incrementalByTimeRange({ timeColumn: "moved_at" }),
+  cron: "@daily",
+  grain: ["stay_id"],                       // логический первичный ключ
+  schema: Schema.Struct({
+    stay_id:  Schema.String,
+    dept:     Schema.String,
+    moved_at: Schema.DateTimeUtc,
+    duration: Schema.Number,
+  }),
+  audits: [audit.notNull("stay_id"), audit.unique("stay_id")],
+  description: "Пребывания пациента в отделении, склеенные из движений",
+}, (ctx) => ctx.sql`
+  SELECT
+    ${ctx.cols(moves, "move_id", "dept")},
+    moved_at,
+    extract(epoch FROM lead(moved_at) OVER w - moved_at) AS duration
+  FROM ${ctx.ref(moves)}
+  WHERE moved_at >= ${ctx.start} AND moved_at < ${ctx.end}
+  WINDOW w AS (PARTITION BY case_id ORDER BY moved_at)
+`)
+```
+
+Что здесь важно:
+
+- **`ctx.ref(moves)`** — ссылка на модель как на значение, не строку.
+  Рендерится в имя view текущего окружения (или в CTE в тестах).
+  Из этих ссылок efmesh собирает DAG — никакого парсинга имён из текста запроса
+  для построения зависимостей не нужно.
+- **`ctx.cols(moves, ...)`** — колонки проверяются компилятором против `moves.schema`.
+  Опечатка в имени колонки = ошибка типов, а не падение в проде.
+- **`ctx.start` / `ctx.end`** — границы обрабатываемого интервала. Подставляются
+  как *bound parameters* при выполнении, а в текст канонизированного SQL попадают
+  как плейсхолдеры — поэтому fingerprint не зависит от конкретных дат.
+- **Тело — чистая функция.** Рендер должен быть детерминированным: `Date.now()`,
+  `Math.random()`, чтение env внутри тела запрещены (ломают стабильность fingerprint).
+  Всё изменчивое приходит через `ctx`.
+
+### 3.1 Виды моделей (kind)
+
+| Вид | Семантика | Фаза |
+|---|---|---|
+| `full` | Полный пересчёт таблицы при каждом запуске | F0 |
+| `view` | Не материализуется, только view поверх запроса | F0 |
+| `incrementalByTimeRange({ timeColumn, batchSize?, lookback? })` | Пересчёт по интервалам времени; `lookback` — сколько прошлых интервалов пересчитывать заново (поздно приезжающие данные) | F1 |
+| `incrementalByUniqueKey({ key })` | Upsert по ключу | F2 |
+| `seed({ file })` | Данные из CSV/JSON-файла, валидируются через `schema` | F2 |
+| `external` | Внешний источник (сырьё): таблица движка, parquet/CSV/JSON по пути или URL, таблица ATTACH-базы. Не материализуется, но участвует в DAG и lineage, схема объявляется | F1 |
+| `embedded` | Подставляется в потребителей как CTE, без материализации | F3 |
+| `scdType2({ key, validFrom, validTo })` | Медленно меняющиеся измерения | F3 |
+
+### 3.2 Проверка контракта схемы
+
+Объявленная `schema` — не документация, а контракт. Перед сборкой каждого
+снапшота (на apply, когда физика родителей уже существует) efmesh выполняет
+`DESCRIBE <запрос>` (DuckDB отдаёт имена и типы, не выполняя запрос), сравнивает
+фактические типы колонок с объявленными и падает с `SchemaMismatchError`, если
+разошлись. Имена сверяются строго (недостающие и лишние колонки), типы — по
+семействам (`Schema.Number` покрывает и INTEGER, и DOUBLE; `DateTimeUtc` —
+все TIMESTAMP-варианты). Это ловит дрейф типов до бэкфилла, а не после.
+
+### 3.3 Цель материализации
+
+Куда складывать физический слой — свойство модели (по умолчанию берётся из конфига):
+
+- **`target: "table"`** — нативная таблица движка.
+- **`target: "parquet"`** — озеро: снапшот материализуется в parquet-файлы
+  (`<lake>/med/stays/fp=a3f9c1/interval=2026-01-01/*.parquet`), view поверх
+  `read_parquet('…/fp=a3f9c1/**')`. Путь озера — локальная директория или S3 (httpfs).
+- **`target: "ducklake"`** *(F4, §14.5)* — таблица-на-fingerprint в DuckLake-каталоге
+  (`ATTACH 'ducklake:sqlite:<catalog>'` под алиасом `_efmesh_ducklake`,
+  конфиг `ducklake: { catalog, dataPath? }`). Версионность остаётся нашей
+  (fingerprint + учёт интервалов); снапшоты и time travel DuckLake — бонус,
+  не второй владелец истории. DELETE+INSERT, ALTER (forward-only) и
+  транзакции работают в каталоге как есть; janitor чистит и его. DuckDB-only.
+  Потребители вне efmesh обязаны сами сделать ATTACH — view окружений
+  ссылаются на таблицы каталога по алиасу.
+
+Инкрементальность efmesh ложится на parquet-озеро без единой новой концепции:
+**интервал = партиция**. Пересчёт интервала — запись файлов его партиции заново;
+учёт интервалов (§6) и здесь остаётся источником правды, поэтому неатомарность
+перезаписи префикса на S3 не страшна — недописанный интервал просто не помечен
+`done` и будет пересчитан.
+
+---
+
+## 4. Снапшоты и fingerprint
+
+Fingerprint снапшота = хэш от:
+
+1. **канонизированного SQL** — запрос рендерится с плейсхолдерами вместо интервалов,
+   парсится в AST, AST нормализуется (регистр ключевых слов, пробелы, порядок
+   неупорядоченных элементов) и депарсится обратно. Переформатирование запроса
+   не меняет fingerprint;
+2. метаданных, влияющих на данные: `kind`, `grain`, `timeColumn`, `schema`;
+3. fingerprint'ов прямых зависимостей (транзитивность: изменение родителя
+   меняет версию потомка — если изменение breaking, см. §5.2).
+
+`cron`, `description`, `owner`, аудиты в fingerprint **не входят** — их изменение
+это metadata-only change без пересчёта.
+
+Физическая таблица: `_efmesh.<schema>__<name>__<fp8>`, где `fp8` — первые
+8 символов fingerprint. Служебная схема — именно `_efmesh` с подчёркиванием:
+DuckDB называет каталог по имени файла базы, и для `efmesh.duckdb` ссылка
+`efmesh.x` неоднозначна (каталог или схема) — Binder Error.
+
+**Стабильность fingerprint — контракт (F6).** Отпечаток зависит от
+канонизации движка (json_serialize_sql DuckDB / libpg_query) и состава
+payload: их изменение молча пере-фингерпринтит все модели пользователя и
+вынуждает полный ребилд склада. Поэтому: (1) канонизация заморожена
+golden-тестами (`test/fingerprint-golden.test.ts`) — красный тест при
+апгрейде `@duckdb/node-api`/`libpg-query` означает дрейф канона, и это
+повод для решения, а не для обновления хэшей; (2) снапшот несёт
+`fingerprint_version` (версия схемы стора 3); (3) осознанная смена
+алгоритма = инкремент `FINGERPRINT_VERSION` + история миграции — план,
+встретив снапшот другой версии, честно останавливается
+(`FingerprintVersionError`), а не показывает «всё breaking».
+
+---
+
+## 5. План: diff и применение
+
+### 5.1 Что делает `efmesh plan <env>`
+
+1. Загружает все модели проекта (импорт TS-модулей через Bun), строит DAG.
+2. Считает fingerprint каждой модели, сравнивает с состоянием окружения.
+3. Категоризирует изменения (§5.2).
+4. Считает недостающие интервалы: для новых снапшотов — от `start` проекта
+   (или модели) до текущего момента; для существующих — дыры в учёте.
+5. Показывает человеку: какие модели изменились, как категоризировано,
+   сколько интервалов будет пересчитано, текстовый diff SQL.
+6. `efmesh apply` показывает тот же план и применяет его: создаёт физические
+   таблицы, гонит бэкфилл, переключает view. *Реализация F4: в TTY план
+   применяется только после явного «y» (y/yes/д/да; `--yes`/`-y` пропускает
+   вопрос), применяется ровно показанный план без пересчёта; не-TTY (CI,
+   пайпы) едет без вопроса.*
+
+### 5.2 Категории изменений
+
+| Категория | Как определяется | Что пересчитывается |
+|---|---|---|
+| **breaking** | По diff AST: удалили/переименовали колонку, изменили выражение существующей, изменили WHERE/JOIN | Модель + все потомки |
+| **non-breaking** | Добавили колонку, добавили независимый CTE | Только сама модель |
+| **forward-only** | Явный флаг пользователя (`--forward-only <model>,…`) или каскад: собственный AST не менялся, а все изменившиеся родители сами forward-only | Ничего задним числом: новая версия наследует физическую таблицу и done-интервалы старой (`physical_fp` снапшота), новые колонки добавляются `ALTER`-ом (история получает NULL), удаление колонок реюзом не выражается — ошибка. Только `incrementalByTimeRange` — у остальных видов «задним числом» не бывает по построению |
+| **metadata-only** | Изменились поля вне fingerprint | Ничего |
+
+Категоризация автоматическая (сравнение AST-выражений по колонкам), с возможностью
+ручного override в диалоге плана. При сомнении efmesh консервативен: не смог
+доказать non-breaking — значит breaking. *Уточнение F2/F3: non-breaking
+распознаётся как строго суффиксное расширение select_list при нетронутом
+остальном дереве (INSERT потомков позиционный); реюз физики — не автоматика
+non-breaking, а явный forward-only.*
+
+### 5.3 Бэкфилл
+
+- Интервалы к пересчёту группируются в батчи (`batchSize` модели).
+- Исполнение — параллельные батчи в пределах модели (`concurrency`, по
+  умолчанию 4): интервалы не пересекаются, каждый батч — своя транзакция
+  на своём соединении пула. Осмыслено на Postgres (F3); DuckDB держит одно
+  соединение — там бэкфилл последовательный, транзакции сериализуются
+  семафором адаптера.
+- **Межмодельная DAG-конкурентность (F4):** сборка и бэкфилл моделей идут
+  не последовательным топологическим циклом, а по готовности — каждая
+  модель плана получает Deferred-гейт и стартует, как только готовы её
+  родители из этого же плана; независимые ветки строятся параллельно
+  (`modelConcurrency`, по умолчанию 4; CLI `--jobs`). Упавший родитель
+  не открывает гейт — потомки не строятся. На DuckDB конкурентность
+  честно = 1: одно соединение, чужие стейтменты вклинивались бы в
+  BEGIN/COMMIT транзакции.
+- Каждый интервал — транзакция: `DELETE` диапазона + `INSERT` (или `MERGE` для
+  unique-key). Упавший интервал не отравляет соседей; ретраи через `Schedule`
+  с экспоненциальной паузой, после исчерпания — интервал помечается `failed`,
+  план завершается ошибкой с перечнем. *Реализация F5: opt-in —
+  `ApplyOptions.retry {attempts, baseDelayMs}` / CLI `--retries N`;
+  ретраится только транзакционная запись батча (повтор безопасен),
+  аудиты не ретраятся — их провал детерминирован.*
+- Прогресс пишется в state store поинтервально: прерванный бэкфилл продолжается
+  с места остановки, а не с нуля.
+
+### 5.4 Промоушен и janitor
+
+Промоушен окружения — транзакционная замена набора view (`CREATE OR REPLACE VIEW`).
+Физика (таблицы и parquet-префиксы), на которую больше не ссылается ни одно окружение, живёт ещё
+`ttl` (по умолчанию 7 дней — чтобы можно было мгновенно откатиться переключением
+view) и затем убираются командой `efmesh janitor`. ttl отсчитывается от
+`orphaned_at` — отметки, которую промоушен ставит при потере последней ссылки
+и снимает при возврате (откат обнуляет счётчик). Физика, разделяемая
+несколькими версиями (forward-only), сносится только с последним
+использующим её снапшотом.
+
+---
+
+## 6. Состояние
+
+Всё состояние — в state store (по умолчанию — SQLite-файл через `bun:sqlite` рядом
+с проектом; для командной/прод-работы — схема `efmesh_state` в Postgres,
+`state: { url: "postgres://…" }` в конфиге; семантика и раскладка идентичны,
+метки времени — ISO UTC текстом в обоих бэкендах). Сам DuckDB
+на роль state store не годится: он однописательский, а состояние должно переживать
+конкурентные запуски из разных процессов. Таблицы:
+
+```
+snapshots     (name, fingerprint, definition_json, created_at)
+intervals     (snapshot_fp, start_ts, end_ts, status: done|failed, updated_at)
+environments  (env, name, snapshot_fp, promoted_at)
+plans         (id, env, summary_json, applied_at, applied_by)   -- журнал аудита
+meta          (version)                                          -- версия схемы (F4)
+```
+
+`applied_by` (F5, версия схемы 2) — кто применил план: `ApplyOptions.appliedBy`
+или ОС-пользователь; записи доверсионного журнала читаются с пустым автором.
+
+Схема стора версионирована (F4): свежий стор бутстрапится на текущую
+`STATE_VERSION` сам; существующий со схемой старше (включая доверсионные)
+открытие не проходит — `StateSchemaError` с подсказкой. Догоняет явный
+`efmesh migrate` — молча менять чужие данные при открытии нельзя.
+
+Инварианты:
+
+- Учёт интервалов — единственный источник правды о том, что посчитано.
+  Физическая таблица без записей в `intervals` считается пустой.
+- Запись в state store — только через транзакции state store; efmesh никогда
+  не смешивает в одной транзакции данные и состояние, если движок данных
+  и state store — разные базы (двухфазности нет, есть идемпотентность:
+  пересчёт интервала безопасен всегда).
+
+---
+
+## 7. Запуск по расписанию
+
+`efmesh run <env>` — один тик планировщика:
+
+1. Для каждой модели, у которой наступил новый интервал, — посчитать его
+   (плюс `lookback` прошлых). *Уточнение F2: отдельного `cron`-поля нет —
+   роль расписания играет зерно интервала (`interval: "day" | "hour"`);
+   `run` никогда не применяет изменения моделей (это plan/apply с человеком
+   у руля) и отказывается работать при структурных изменениях.*
+2. Порядок и конкурентность — как в бэкфилле (§5.3).
+3. Аудиты — после каждого посчитанного интервала (§8).
+
+`run` идемпотентен и безопасен для cron/systemd-таймера: параллельный запуск
+отсекается блокировкой в state store — таблица `locks` с ttl (протухший лок
+упавшего процесса перехватывается), одинаково в SQLite и Postgres.
+*Уточнение F5 (§14.6 закрыт): лок один на окружение (`env:<имя>`) и общий
+для `run` и `apply` — мутации окружения из разных процессов взаимно
+исключаются; у `janitor` свой глобальный лок.*
+Долгоживущий демон не нужен,
+но для встраивания в Effect-приложение есть `Runner.daemon` — `Effect`, крутящий
+тики по `Schedule.cron` внутри вашего рантайма.
+
+---
+
+## 8. Качество: аудиты и тесты
+
+**Аудит** — SQL-предикат над результатом, выполняется после загрузки интервала.
+Возвращает нарушающие строки; непустой результат = `AuditFailure`.
+
+```ts
+audits: [
+  audit.notNull("stay_id"),
+  audit.unique("stay_id"),
+  audit.accepted("dept", ["ОРИТ", "терапия", "хирургия"]),
+  audit.custom("положительная длительность", (ctx) => ctx.sql`
+    SELECT * FROM ${ctx.self} WHERE duration < 0
+  `),
+]
+```
+
+Аудит бывает `blocking` (по умолчанию: интервал помечается failed, view не
+промоутится) и `warn` (метрика + лог, конвейер едет дальше).
+
+Помимо прогона в apply, есть автономный `efmesh audit <env>` (F4): проверяет
+то, что окружение отдаёт потребителям СЕЙЧАС — view-слой целиком, а не
+свежезагруженный интервал. Ловит деградацию задним числом (поздние данные,
+правку физики мимо efmesh, дрейф external); ничего не меняет и не помечает,
+отчёт целиком, ненулевой exit при blocking-нарушениях.
+
+**Тест** — юнит-тест запроса на фикстурах, живёт в `bun test`:
+
+```ts
+import { testModel } from "efmesh/testing"
+
+testModel(stays, {
+  inputs: { [moves.name]: [
+    { move_id: "1", case_id: "c1", dept: "ОРИТ", moved_at: "2026-01-01T10:00Z" },
+    { move_id: "2", case_id: "c1", dept: "терапия", moved_at: "2026-01-02T10:00Z" },
+  ]},
+  interval: ["2026-01-01", "2026-01-03"],
+  expect: [{ stay_id: "1", dept: "ОРИТ", duration: 86400 }],
+})
+```
+
+Механика: `ctx.ref` в тестовом режиме рендерится в CTE с `VALUES` из фикстур
+(валидированных через Schema модели-источника!), запрос выполняется на
+одноразовом in-memory DuckDB — мгновенно, без docker и внешней инфраструктуры, —
+результат сравнивается с ожидаемым. Фикстуры с невалидными по Schema данными
+не компилируются — тест не может врать о форме входа.
+
+---
+
+## 9. Движки и парсинг SQL
+
+### 9.1 Адаптер движка — Effect-сервис
+
+```ts
+interface Engine {
+  readonly dialect: "duckdb" | "postgres"
+  readonly query: (sql: string) => Effect<Rows, EngineError>
+  readonly execute: (sql: string) => Effect<void, EngineError>
+  /** Набор стейтментов одной транзакцией: на пуле соединений BEGIN/COMMIT
+      отдельными execute разъехались бы по разным соединениям. */
+  readonly transaction: (statements: ReadonlyArray<string>) => Effect<void, EngineError>
+  readonly describe: (sql: string) => Effect<ColumnTypes, EngineError>       // для §3.2
+  readonly canonicalize: (sql: string) => Effect<string, EngineError | SqlParseError> // для §9.2
+}
+```
+
+Подключается через `Layer`. Первый движок — **DuckDB** (поверх `@duckdb/node-api`),
+второй — **Postgres** (F3, поверх встроенного `Bun.SQL` с пулом;
+`describe` — временный view + `pg_attribute` на одном соединении).
+DuckDB-специфика (seed, parquet-цель, external по файлам/URL, export в
+ATTACH) на других движках честно падает `EngineFeatureError` до любых
+действий. DuckDB выбран первым не только за скорость и нулевую
+инфраструктуру: httpfs, ATTACH и parquet делают его одновременно движком,
+федератором и озером (§9.3). State store — отдельный сервис с тем же паттерном.
+
+### 9.2 Парсинг
+
+Для канонизации (§4), diff-категоризации (§5.2) и lineage нужен настоящий парсер —
+и это обязанность адаптера: каждый движок парсит свой диалект сам, самодельного
+«парсера всех SQL» в efmesh нет.
+
+- **DuckDB** отдаёт AST собственным парсером: `json_serialize_sql()` /
+  `json_deserialize_sql()`. Канонизация — round-trip сериализации: стопроцентная
+  точность диалекта, включая его расширения (`read_parquet`, `GROUP BY ALL`,
+  list-типы), ноль сторонних зависимостей. Ограничение: сериализуются только
+  SELECT-стейтменты — а тело модели ровно им и является.
+- **Postgres** (F3, реализовано) — libpg_query в WASM, парсер самого Postgres:
+  дерево разбора с вычищенными `location` формат-инвариантно; плейсхолдеры
+  `$start`/`$end` канонического рендера детерминированно замещаются `$1`/`$2`
+  (bare `$имя` — не синтаксис Postgres).
+
+Транспиляции между диалектами **нет** (не-цель): проект пишется под диалект
+своего движка. Это честное сужение относительно sqlmesh (sqlglot) в обмен
+на точность и простоту.
+
+### 9.3 Федерация: чтение и запись наружу
+
+DuckDB закрывает три сценария, ради которых он и выбран первым движком:
+
+- **Озеро на parquet.** Цель материализации `parquet` (§3.3): физический слой —
+  файлы локально или на S3, view поверх `read_parquet`. Склад без склада.
+- **Чтение чужих систем.** `external`-модели поверх `read_parquet`/`read_csv`/
+  `read_json` — в том числе по HTTPS, так что «дёрнуть REST API, отдающий JSON»
+  ложится сюда же, — и поверх таблиц ATTACH-баз (Postgres, MySQL, SQLite).
+  Про детерминизм: внешний источник меняется между запусками, это нормально
+  (как любое сырьё) — в fingerprint входит только *определение* источника,
+  не его содержимое; свежесть управляется интервалами и cron.
+- **Запись наружу.** Экспорт результата модели в ATTACH-базу — например, готовая
+  витрина уезжает в рабочий Postgres приложения:
+  `export: { attach: "app_pg", table: "public.stays" }`. Экспорт выполняется
+  после аудитов и только для промоутнутого снапшота — наружу не может уехать
+  непроверенное. Фаза F2.
+
+### 9.4 Lineage
+
+Из AST + разрешённых `ctx.ref` строится колоночный lineage (F3, реализовано):
+`efmesh lineage med.stays.duration` → цепочка до сырьевых колонок
+`external`/`seed`-моделей. Точность best-effort: выражение колонки берётся
+из канонического AST, `COLUMN_REF` сопоставляются схемам родителей по имени
+(квалификаторы и алиасы CTE не разворачиваются), `SELECT *` — сквозной
+проброс. Так как зависимости моделей известны из `ref`, а не из парсинга
+имён, граф моделей точен всегда — приблизителен только колоночный уровень.
+
+---
+
+## 10. Effect-архитектура
+
+Слои (снизу вверх):
+
+```
+EngineAdapter (DuckDB | Postgres)        StateStore (SQLite | PG)
+        └──────────────┬──────────────────────┘
+                   Snapshotter  (fingerprint, канонизация)
+                   IntervalLedger (учёт интервалов)
+                        │
+                     Planner   (diff, категоризация, план)
+                     Executor  (бэкфилл: Stream + DAG-конкурентность)
+                     Auditor
+                        │
+                  Efmesh (фасад: plan / apply / run / test)
+                        │
+              CLI (тонкая обёртка)   |   ваш Effect-код (библиотечное встраивание)
+```
+
+Принципы:
+
+- **Типизированные ошибки** на каждом уровне: `ParseError | SchemaMismatchError |
+  PlanConflictError | AuditFailure | IntervalFailure | EngineError`. Никаких
+  `throw` — вся обработка через канал ошибок Effect.
+- **Один владелец жизненного цикла**: ресурсы (пулы соединений, WASM-инстанс
+  парсера) — `Scope`/`Layer`, teardown гарантирован.
+- **Наблюдаемость из коробки**: span на каждую модель/интервал, `Metric` —
+  `efmesh_intervals_done_total`, `efmesh_interval_duration`, `efmesh_audit_failures_total`.
+- **Библиотека прежде CLI.** `Efmesh.plan(env)` — обычный `Effect`, который можно
+  запустить внутри любого приложения, снабдив слоями. CLI собирается на
+  Effect CLI-модуле и компилируется `bun build --compile` в один бинарник.
+  *Уточнение F5: бинарник собирается и работает (`--external` на чужие
+  платформы `@duckdb/node-bindings-*`), но standalone-исполняемые Bun
+  не резолвят bare-импорт `"efmesh"` из рантайм-загружаемого
+  `efmesh.config.ts` даже при живом node_modules — ограничение Bun,
+  не наше. Дистрибуция беты — пакетом (`bun add -d efmesh`), бинарник
+  подождёт апстрима.*
+
+Целевая версия — **Effect v4**: один пакет `effect`, сервисы через
+`ServiceMap`/`Layer`, `Schema` из коробки. Пока v4 в движении, API-поверхность
+efmesh закладывается на стабильное подмножество (Effect/Layer/Schema/Stream/
+Schedule/Metric/Scope), точечные адаптации — при финализации v4.
+
+---
+
+## 11. CLI
+
+```
+efmesh init [dir]               — скаффолд проекта (конфиг, модели-пример, seed)
+efmesh plan <env> [--forward-only <model>,…]
+efmesh apply <env> [--yes] [--jobs N] [--retries N] [--forward-only …]  — план + подтверждение + применение
+efmesh run  <env> [--jobs N] [--retries N]  — тик планировщика
+efmesh audit <env> [--model a,b] — аудиты view-слоя окружения, ничего не меняя
+efmesh render <model> [--env]   — показать итоговый SQL (для отладки)
+efmesh diff <envA> <envB>       — чем окружения отличаются
+efmesh lineage <model[.column]>
+efmesh graph [--html]           — DAG моделей
+efmesh janitor [--ttl 7]        — уборка осиротевших физических таблиц
+efmesh migrate                  — догнать схему state store до текущей версии
+```
+
+Конфиг — `efmesh.config.ts` (не YAML): типизирован, собирает `Layer` движка
+и state store, задаёт окружения, `start` проекта, ttl, конкурентность.
+
+---
+
+## 12. Структура проекта пользователя
+
+```
+my-warehouse/
+  efmesh.config.ts
+  models/
+    sources.ts          — external-модели (сырьё) с их Schema
+    med/
+      moves.ts
+      stays.ts
+  seeds/
+    departments.csv
+  tests/
+    stays.test.ts       — bun test
+```
+
+Discovery моделей — по glob из конфига + проверка, что каждый экспорт
+`defineModel` достижим; дубликаты имён — ошибка загрузки. *Реализовано (F5):
+`discovery: glob | glob[]` в конфиге (маски относительно конфига), все
+экспорты-модели найденных файлов попадают в проект; реэкспорт того же
+объекта — не дубликат, два разных определения с одним именем —
+`DiscoveryConflictError` с обоими файлами; совместимо с явным `models`.*
+
+---
+
+## 13. Фазы
+
+- **F0 — скелет (вертикальный срез).** `defineModel`, `full`/`view`, рендер и
+  `ctx.ref`, DuckDB-адаптер (нативные таблицы), state store на `bun:sqlite`,
+  `plan`/`apply` без категоризации (всё breaking), физический+виртуальный слой,
+  `render`, `graph`.
+  Стоп-условие: две связанные модели проходят plan→apply→изменение→plan→apply,
+  prod не пересчитывается при промоушене.
+- **F1 — инкрементальность и озеро.** `incrementalByTimeRange`, учёт интервалов,
+  бэкфилл со Stream и DAG-конкурентностью, fingerprint по канонизированному AST
+  (`json_serialize_sql`), `external` (таблицы, файлы/URL, ATTACH-чтение),
+  контракт схемы (§3.2), цель материализации `parquet` — локально и на S3 (httpfs),
+  прерывание/продолжение бэкфилла.
+- **F2 — качество и эксплуатация.** Аудиты, `testModel` (in-memory DuckDB),
+  `run` по cron + блокировка + `Runner.daemon`, категоризация
+  breaking/non-breaking по AST, `janitor` (таблицы и parquet-префиксы), `diff`,
+  метрики/спаны, `seed`, `incrementalByUniqueKey`, экспорт в ATTACH-базы (§9.3).
+- **F3 — широта.** Postgres-адаптер (libpg_query, state store в PG,
+  пул → параллельные батчи бэкфилла), lineage по колонкам, `forward-only`
+  (+ orphaned_at для janitor), `scdType2`, `embedded`, `graph --html`,
+  сырые `.sql`-модели (`defineSqlModel`, §14.1 закрыт). *Построено.*
+- **F4 — эксплуатационная зрелость.** Межмодельная DAG-конкурентность
+  apply (Deferred-гейты, `--jobs`, §5.3), `target: "ducklake"` (§14.5
+  закрыт), автономный `efmesh audit` (§8), `efmesh init`, версия схемы
+  state store + `efmesh migrate` (§6), интерактивное подтверждение плана
+  (§5.1). *Построено.*
+- **F5 — бета-гейт.** Межпроцессный лок на `apply` — общий env-лок с `run`
+  (§14.6 закрыт), discovery моделей по glob (§12), ретраи батча бэкфилла
+  со `Schedule.exponential` (§5.3), `applied_by` в журнале планов (версия
+  схемы стора 2), решение по nullability (§14.2 закрыт: контракт — имена
+  и типы, NULL — дело аудита), версия 0.1.0-beta; одиночный бинарник
+  уперся в ограничение Bun (§10) — дистрибуция пакетом. *Построено.*
+  Дальше (кандидаты): override категоризации в диалоге плана (§5.2),
+  интервалы не по времени (§14.3), lock и на janitor↔apply гонку
+  жёстче ttl-смягчения, публикация в registry.
+
+---
+
+## 14. Открытые вопросы
+
+1. **Сырые `.sql`-файлы.** *Закрыт (F3):* `defineSqlModel({ file, refs })` —
+   тело в `.sql` с `@ref(имя)`/`@start`/`@end`, зависимости объявляются
+   значениями в `refs` (каждый `@ref` обязан быть объявлен, лишние — ошибка),
+   поэтому DAG, fingerprint и testModel работают как у обычных моделей.
+   Типизация колонок по-прежнему теряется — честная цена миграции.
+2. **Nullability в контракте.** *Закрыт (F5) решением:* `DESCRIBE <запрос>`
+   в DuckDB даёт имена и типы, но не nullability — контракт проверяет
+   имена и типы (семейства), обещание «не NULL» выражается аудитом
+   `audit.notNull` (blocking по умолчанию). `Schema.NullOr` в модели —
+   документация формы данных, не рантайм-гарантия.
+3. **Интервалы не по времени.** sqlmesh умеет `INCREMENTAL_BY_PARTITION`.
+   Нужно ли обобщать учёт с временных интервалов до произвольных партиций —
+   решить по первому реальному потребителю.
+4. **Мульти-движок в одном проекте.** ATTACH закрывает типовой случай без второго
+   адаптера (читать из PG, экспортировать в PG, считая всё в DuckDB); полноценный
+   мульти-движок — вне scope, но `EngineAdapter`-слой на модель этому не противоречит.
+5. **DuckLake.** *Закрыт (F4):* реализована третья цель материализации
+   `target: "ducklake"` (§3.3) — таблица-на-fingerprint в ATTACH-каталоге,
+   версионность остаётся нашей, снапшоты/time travel DuckLake — бонус.
+   Ровно по выводам пробы 2026-07-15: DuckLake — не замена нашей
+   версионности (второй владелец истории), а дополнительное место
+   физики; DELETE+INSERT, ALTER и транзакции работают в каталоге как есть.
+   SQLite-каталог не добавляет инфраструктуры; мультипроцессность
+   честно потребует Postgres-каталога — отложено до реального потребителя.
+6. **Конкурентность записи DuckDB.** *Закрыт (F5):* блокировка в state
+   store покрывает и apply — `run` и `apply` окружения идут под одним
+   локом `env:<имя>` (протухший перехватывается по ttl), у `janitor` свой
+   глобальный лок; в CLI лок охватывает план→подтверждение→применение.
+   Гонку janitor↔apply (воскрешение осиротевшего снапшота в момент сноса)
+   смягчает ttl осиротевшей физики.
+
+---
+
+## 15. Сравнение (шпаргалка)
+
+| | dbt | sqlmesh | efmesh |
+|---|---|---|---|
+| Язык моделей | SQL + Jinja | SQL + Jinja/Python | SQL внутри TypeScript |
+| Зависимости | `ref('строка')` | парсинг SQL | импорт модуля, проверен компилятором |
+| Типизация колонок | нет | contracts (рантайм) | Effect Schema (компайл-тайм + план) |
+| Версионирование | нет (state-less) | снапшоты + fingerprint | снапшоты + fingerprint |
+| Dev-окружения | копии таблиц | виртуальные (view) | виртуальные (view) |
+| Инкрементальность | самописный `is_incremental()` | интервалы, автоучёт | интервалы, автоучёт |
+| Мульти-диалект | да | да (sqlglot) | нет — диалект движка (DuckDB первым) |
+| Озеро на parquet | адаптеры | адаптеры | родное: target `parquet`, интервал=партиция |
+| Встраивание | subprocess | Python API | Effect-библиотека |