@avytheone/efmesh 0.1.0-beta.2 → 0.2.1

package/CHANGELOG.md

@@ -1,102 +1,181 @@
 # Changelog
 
-Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
-версионирование — [SemVer](https://semver.org/lang/ru/).
-Внутренняя история разработки велась фазами F0–F6 (SPEC.md §13);
-первая версия собирает их целиком.
-
-## [Unreleased]
+Format — [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+versioning — [SemVer](https://semver.org/).
+Internal development history was tracked in phases F0–F6 (SPEC.md §13);
+the first version gathers them in full.
+
+## [0.2.1] — 2026-07-16
+
+Theme: hygiene for the first stranger — the whole surface is English,
+failures explain themselves, execution is visible.
+
+- Detailed execution log (#14). `apply` and `run` now narrate their work
+  through Effect's logging system: per-model build start/finish with duration,
+  backfill batch progress (`batch n of m` with interval bounds), warn-audits
+  and promotion. Levels — **info** for lifecycle (visible by default), **warn**
+  for warn-audits/retries, **debug** for the rendered SQL and lock internals;
+  the existing `--log-level` flag sets the minimum. Every line carries
+  structured fields (`model`, `env`, `interval`) as annotations. Logs go to
+  **stderr** (stdout and `--json` stay byte-clean); a TTY gets pretty colored
+  output, a pipe/journal gets one-line logfmt with no ANSI. Embedders provide
+  their own `Logger` layer to redirect sinks and levels. Exit codes unchanged.
+- Human-readable, precise errors everywhere (#13). Every tagged error now
+  derives its `message` from its typed fields, so the culprit (model, env,
+  file, interval) and the underlying engine/system text are always present —
+  an empty `EngineError:` is constructively impossible. `EngineError` carries
+  the failing model and the engine's own message; a failing `apply` names the
+  model, quotes DuckDB/Postgres verbatim, and shows the SQL context. The CLI
+  now renders one failure screen (cause first, an actionable hint where one
+  exists) and prints the Effect fiber trace only under `--log-level debug`.
+  Exit codes (0/1/2) and `--json` shapes are unchanged. New exported error
+  `UnknownModelError` (render/lineage against a name not in the project).
+- The entire user-facing surface is English: CLI output and help, error
+  messages, `--json` string values (key names and exit codes unchanged),
+  the `init` scaffold, the hospital example data (#11). Source comments
+  and test names too (#12).
+- **Breaking:** the `apply` confirmation prompt accepts only `y`/`yes`
+  (case-insensitive); the Cyrillic tokens are no longer recognized.
+- `efmesh init` scaffold now teaches the core lifecycle: a seed feeding
+  an incremental-by-time-range model with a blocking audit and a full
+  rollup on top, runnable immediately after `init` (#11).
+
+## [0.2.0] — 2026-07-16
+
+Theme: "operator and team" — efmesh in the hands of a non-author: the
+operator of the nightly cron and a team with CI.
+
+- `efmesh status <env>` — what is going on in one command: the last applied
+  plan, interval lag per incremental model, failed intervals, recent run
+  ticks (#1).
+- Run tick journal in the state store (`runs`, schema v4 — `efmesh migrate`
+  with a store backup): every tick records its outcome, including
+  unsuccessful ones (#2).
+- `--json` on `plan`, `audit` and `status`: a stable machine-readable shape
+  for CI and bots; exit codes unchanged (#3).
+- Canonicalization cache in the state store (schema v5): a no-op plan on
+  2000 models drops from ~0.6 s to ~50 ms; the cache key includes the
+  dialect and `FINGERPRINT_VERSION`, so canon drift can never be masked (#8).
+- Integration test: stale lock reclaim under a real `kill -9` (#7).
+- `plan --explain`: for every change — which canonical-AST nodes diverged
+  and why the category followed (cascade sources for `indirect`, inherited
+  physics for `forward-only`); also shipped in `--json` as `explain`
+  (`PlanAction.explain` in the library API). AST paths are a debugging
+  hint, not a contract (#4).
+- Indirect physics reuse — the sqlmesh "indirect non-breaking" class: a
+  descendant whose own AST did not change and whose changed parents are all
+  non-breaking/forward-only inherits the previous version's physical table
+  and interval accounting instead of a full rebuild (scdType2 keeps its row
+  history). Safety is proven, not assumed: the fingerprint recomputed with
+  the parents' old fingerprints must reproduce the old version, so
+  simultaneous metadata drift disables reuse (#5).
+- `--reclassify model=breaking|non-breaking` on `plan`/`apply`: the
+  operator's verdict as a flag on top of `--explain` (no interactive
+  dialog — works in CI), journaled with `applied_by`
+  (`PlanAction.reclassifiedFrom`); governs descendants' physics reuse.
+  Guard rail: dropped columns declared non-breaking are refused (#5).
+- `diff --data` — compare the DATA of two environments: full row counts,
+  key overlap (grain or the kind's key), per-column mismatch rates among
+  matched keys, schema drift between sides. `--sample P` compares a
+  deterministic share of keys (md5 buckets aligned across both sides — no
+  false only-in rows); `--json` for CI (`dataDiffEnvironments` in the
+  library API) (#6).
+- `efmesh schedule <env>` — register the `run` tick in the OS scheduler via
+  `Bun.cron` (crontab/launchd/Task Scheduler; `engines.bun >= 1.3.11`).
+  Idempotent by title; `--remove`, `--list`; on cron-less Linux
+  (Arch family) it detects the missing daemon and `--print-systemd` emits
+  user units with `Persistent=true` instead (#10).
 
 ## [0.1.0-beta.2] — 2026-07-16
 
-- Релизный конвейер: публикация в npmjs.org из GitHub Actions по тегу
-  `v*` через Trusted Publishing (OIDC, без токенов) с provenance.
-  Содержимое пакета не менялось — релиз проверяет сам конвейер.
+- Release pipeline: publishing to npmjs.org from GitHub Actions on a `v*`
+  tag via Trusted Publishing (OIDC, no tokens) with provenance.
+  The package contents did not change — the release verifies the pipeline itself.
 
 ## [0.1.0-beta.1] — 2026-07-16
 
-Первая публичная бета. Всё ниже — новое.
-
-### Модели и план (F0–F1)
-
-- `defineModel`/`defineExternal`: модели — TypeScript-модули, ссылки —
-  импорты, форма данных — Effect Schema; DAG строится из значений.
-- Fingerprint по каноническому AST (`json_serialize_sql` DuckDB):
-  переформатирование SQL не триггерит пересборку.
-- Снапшоты версий, виртуальные окружения (view поверх физики),
-  план как diff, промоушен без пересчёта.
-- `kind.incrementalByTimeRange`: интервальный учёт в state store, бэкфилл
-  батчами DELETE+INSERT в транзакции, resume с места остановки, `lookback`.
-- Контракт схемы перед сборкой (`DESCRIBE` против объявленной Schema).
-- `target: "parquet"`: озеро локально или на S3 (httpfs), интервал = партиция.
-
-### Качество и эксплуатация (F2)
-
-- Аудиты `notNull`/`unique`/`accepted`, blocking/warn.
-- `testModel` (`efmesh/testing`): юнит-тесты моделей на фикстурах
-  в in-memory DuckDB.
-- Категоризация изменений breaking / non-breaking / indirect по AST.
-- `efmesh run`: идемпотентный тик планировщика с межпроцессным локом;
-  `Runner.daemon` для встраивания.
+First public beta. Everything below is new.
+
+### Models and plans (F0–F1)
+
+- `defineModel`/`defineExternal`: models are TypeScript modules, references
+  are imports, data shape is Effect Schema; the DAG is built from values.
+- Fingerprint over the canonical AST (`json_serialize_sql` in DuckDB):
+  reformatting SQL does not trigger a rebuild.
+- Version snapshots, virtual environments (views over physical storage),
+  a plan as a diff, promotion without recomputation.
+- `kind.incrementalByTimeRange`: interval ledger in the state store, backfill
+  in DELETE+INSERT batches within a transaction, resume from where it stopped, `lookback`.
+- A schema contract before a build (`DESCRIBE` against the declared Schema).
+- `target: "parquet"`: a lake locally or on S3 (httpfs), interval = partition.
+
+### Quality and operations (F2)
+
+- `notNull`/`unique`/`accepted` audits, blocking/warn.
+- `testModel` (`efmesh/testing`): unit tests for models on fixtures
+  in in-memory DuckDB.
+- Change categorization breaking / non-breaking / indirect by AST.
+- `efmesh run`: an idempotent scheduler tick with a cross-process lock;
+  `Runner.daemon` for embedding.
 - `efmesh janitor`, `efmesh diff`, `defineSeed`,
-  `kind.incrementalByUniqueKey` (upsert), экспорт витрин в ATTACH-базы,
-  метрики и спаны.
-
-### Широта (F3)
-
-- Postgres: движок на `Bun.SQL` (пул, параллельные батчи бэкфилла),
-  canonicalize через libpg_query, state store в схеме `efmesh_state`.
-- `--forward-only`: правка без переигрывания истории — новая версия
-  наследует физику и done-интервалы, новые колонки через `ALTER`.
-- `kind.scdType2` (история строк), `kind.embedded` (подзапрос без
-  материализации), `defineSqlModel` (сырые `.sql` с `@ref`/`@start`/`@end`).
-- Колоночный `efmesh lineage`, `efmesh graph --html`.
-
-### Эксплуатационная зрелость (F4)
-
-- Межмодельная DAG-конкурентность apply (`--jobs`): модель стартует
-  по готовности родителей; на DuckDB честно 1 (одно соединение).
-- `target: "ducklake"`: физика в DuckLake-каталоге, снапшоты и time travel
-  каталога — бонус.
-- Автономный `efmesh audit <env>` по view-слою окружения.
-- `efmesh init` (скаффолд), версия схемы state store + `efmesh migrate`.
-- Подтверждение плана в TTY (`--yes` пропускает, не-TTY едет без вопроса).
-
-### Бета-гейт (F5)
-
-- Межпроцессный лок на `apply` — общий env-лок с `run`: параллельные
-  мутации окружения из разных процессов взаимно исключаются
-  (`LockHeldError`); у janitor свой глобальный лок.
-- Discovery моделей по glob: `discovery: "models/**/*.ts"` в конфиге.
-- Ретраи батча бэкфилла: `--retries N`, `Schedule.exponential`;
-  аудиты не ретраятся.
-- `applied_by` в журнале планов (версия схемы стора 2).
-- Лицензия MIT.
-
-### Бета-гейт, часть 2 (F6)
-
-- effect — peerDependency с точным пином беты; еженедельный CI против
-  свежей беты (ранний сигнал дрейфа v4).
-- Fingerprint как контракт: `FINGERPRINT_VERSION` в снапшотах (схема
-  стора 3), golden-тесты замораживают канонизацию DuckDB и libpg_query;
-  снапшот чужой версии — громкая `FingerprintVersionError`.
-- Гонка janitor↔apply закрыта транзакционно: claim сироты атомарен
-  с проверками, воскрешение снимает сиротство, промоушен проверяет
-  живость снапшотов — view не переключается на снесённую физику.
-- Parquet-партиции пишутся атомарно (temp + rename); `migrate` снимает
-  копию SQLite-стора перед апгрейдом схемы.
-- **Ломающее:** `apply` в не-TTY с изменениями требует `--yes`;
-  exit-код `2` = «ждёт человека» (отказ подтверждения,
+  `kind.incrementalByUniqueKey` (upsert), export of marts to ATTACH databases,
+  metrics and spans.
+
+### Breadth (F3)
+
+- Postgres: an engine on `Bun.SQL` (pool, parallel backfill batches),
+  canonicalize via libpg_query, state store in the `efmesh_state` schema.
+- `--forward-only`: a change without replaying history — the new version
+  inherits physical storage and done-intervals, new columns via `ALTER`.
+- `kind.scdType2` (row history), `kind.embedded` (subquery without
+  materialization), `defineSqlModel` (raw `.sql` with `@ref`/`@start`/`@end`).
+- Column-level `efmesh lineage`, `efmesh graph --html`.
+
+### Operational maturity (F4)
+
+- Cross-model DAG concurrency for apply (`--jobs`): a model starts
+  as soon as its parents are ready; on DuckDB it is honestly 1 (a single connection).
+- `target: "ducklake"`: physical storage in a DuckLake catalog, catalog
+  snapshots and time travel come as a bonus.
+- Standalone `efmesh audit <env>` over an environment's view layer.
+- `efmesh init` (scaffold), state-store schema version + `efmesh migrate`.
+- Plan confirmation in a TTY (`--yes` skips it, a non-TTY proceeds without asking).
+
+### Beta gate (F5)
+
+- Cross-process lock on `apply` — a shared env lock with `run`: parallel
+  mutations of an environment from different processes are mutually exclusive
+  (`LockHeldError`); the janitor has its own global lock.
+- Model discovery by glob: `discovery: "models/**/*.ts"` in the config.
+- Backfill batch retries: `--retries N`, `Schedule.exponential`;
+  audits are not retried.
+- `applied_by` in the plans journal (store schema version 2).
+- MIT license.
+
+### Beta gate, part 2 (F6)
+
+- effect is a peerDependency with an exact beta pin; a weekly CI job against
+  a fresh beta (an early signal of v4 drift).
+- Fingerprint as a contract: `FINGERPRINT_VERSION` in snapshots (store
+  schema 3), golden tests freeze DuckDB and libpg_query canonicalization;
+  a snapshot of a foreign version is a loud `FingerprintVersionError`.
+- The janitor↔apply race is closed transactionally: claiming an orphan is
+  atomic with the checks, resurrection clears the orphan status, promotion
+  checks snapshot liveness — a view never switches to removed physical storage.
+- Parquet partitions are written atomically (temp + rename); `migrate` takes
+  a copy of the SQLite store before upgrading the schema.
+- **Breaking:** `apply` in a non-TTY with changes requires `--yes`;
+  exit code `2` = "awaiting a human" (confirmation refused,
   `RunBlockedByChangesError`).
-- Публичное API сужено до осознанного whitelist (`index.ts`).
-- README на английском (русское зеркало — README.ru.md), секция
-  «для кого это (и для кого нет)».
-
-### Известные ограничения
-
-- Effect v4 — beta-зависимость; API efmesh держится стабильного
-  подмножества.
-- Одиночный бинарник `bun build --compile` собирается, но standalone-Bun
-  не резолвит импорт `"efmesh"` из рантайм-конфига — дистрибуция пакетом.
-- Nullability не входит в контракт схемы (DuckDB `DESCRIBE` её не отдаёт) —
-  выражается аудитом `notNull`.
+- The public API is narrowed to a deliberate whitelist (`index.ts`).
+- README in English (the Russian mirror is README.ru.md), a
+  "who this is for (and who it isn't)" section.
+
+### Known limitations
+
+- Effect v4 is a beta dependency; the efmesh API sticks to a stable
+  subset.
+- A single `bun build --compile` binary builds, but standalone Bun
+  cannot resolve the `"efmesh"` import from a runtime config — distribution is via the package.
+- Nullability is not part of the schema contract (DuckDB `DESCRIBE` does not report it) —
+  it is expressed with the `notNull` audit.

package/README.md

@@ -2,12 +2,14 @@
 
 > Data transformation in the spirit of [sqlmesh](https://sqlmesh.com) — on TypeScript, [Bun](https://bun.sh) and [Effect](https://effect.website).
 
-[![ci](https://github.com/avytheone/efmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/avytheone/efmesh/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-orange) ![version](https://img.shields.io/badge/version-0.1.0--beta.1-blue) ![license](https://img.shields.io/badge/license-MIT-green) ![runtime](https://img.shields.io/badge/runtime-bun-black) ![effect](https://img.shields.io/badge/effect-v4-5C4EE5)
+[![ci](https://github.com/avytheone/efmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/avytheone/efmesh/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-orange) ![npm](https://img.shields.io/npm/v/%40avytheone%2Fefmesh) ![license](https://img.shields.io/badge/license-MIT-green) ![runtime](https://img.shields.io/badge/runtime-bun-black) ![effect](https://img.shields.io/badge/effect-v4-5C4EE5)
 
 *Русская версия: [README.ru.md](./README.ru.md).*
 
 Models are plain TypeScript modules: SQL bodies, imports as dependencies, Effect Schema as the data shape. efmesh fingerprints every model by its canonical AST, keeps versions as snapshots, computes a plan as the diff between your project and an environment, and applies exactly that plan: physical tables are rebuilt only where something actually changed, while environments (dev/prod/…) are virtual views over shared physical storage — promoting to prod costs zero recomputation.
 
+<p align="center"><img src="docs/demo.svg" alt="efmesh demo: a ref typo is a compile error; a plan rebuilds exactly the changed branch; promotion is a view swap" width="840"></p>
+
 ```ts
 import { Schema } from "effect"
 import { defineModel, kind } from "@avytheone/efmesh"
@@ -46,9 +48,15 @@ export const moves = defineModel(
 
 A typo in a `ref` is a compile error, not an empty run; renaming a parent's column breaks the child's build before any SQL reaches the database.
 
+## Why this exists: small data lakes
+
+Most analytics in the world is not a cloud warehouse — it is DuckDB-class data: gigabytes to a terabyte on one machine. Product analytics of a startup, the marts of one department, on-prem and edge deployments, a pipeline living inside a SaaS app. dbt and sqlmesh were born in the cloud-DWH world and carry that weight with them (Python, adapters, infrastructure). efmesh is the sqlmesh approach that is `bun add` and go — and the lake is a folder of parquet files.
+
+Honestly placed: the **core** is the same class of system as sqlmesh — snapshots, AST fingerprints, plans as diffs, virtual environments. The **breadth** is not: no cloud engines, no multi-dialect, no web UI, no ecosystem of packages — and no ambition to catch up on all of it. Compared to dbt-core the trade is reversed: dbt has an industry around it, but no state-based plans, no virtual environments, no fingerprint versioning — every team reinvents "how not to rebuild everything". Our four honest advantages: **types as the DAG contract** (a typo breaks the build, not the nightly run), **library before CLI** (embed `Efmesh.apply(...)` in your app), **one language for the whole stack** (models, app, tests), and a **codebase you can read in an evening** (~5.5k lines).
+
 ## Who this is for (and who it isn't)
 
-**For you**, if you are a TypeScript team on Bun, want a typed dbt/sqlmesh-style workflow on top of DuckDB or Postgres, and are fine living on a beta (efmesh is 0.1.x; Effect v4 is beta, pinned exactly as a peer dependency).
+**For you**, if you are a TypeScript team on Bun, want a typed dbt/sqlmesh-style workflow on top of DuckDB or Postgres, and are fine living on a beta (efmesh is 0.2.x; Effect v4 is beta, pinned exactly as a peer dependency).
 
 **Not for you**, if you need: a Node runtime (Bun-only for now), multi-dialect or cloud DWHs (Snowflake/BigQuery are out of scope), 1.0-grade stability, or the Python ecosystem — take sqlmesh instead, honestly.
 
@@ -58,7 +66,7 @@ A typo in a `ref` is a compile error, not an empty run; renaming a parent's colu
 
 **Materialization targets.** Native engine tables, `parquet` (a lake, local or s3://, interval = partition, views over `read_parquet`), `ducklake` (table-per-fingerprint in a [DuckLake](https://ducklake.select) catalog — catalog snapshots and time travel come as a bonus).
 
-**Plans and versions.** Fingerprints over canonical ASTs (reformatting SQL never triggers a rebuild — frozen by golden tests), change categorization breaking / non-breaking / indirect / forward-only, `--forward-only` applies a change without replaying history (the new version inherits physical storage and done-intervals; new columns via `ALTER`), plan confirmation in a TTY, an applied-plans journal with `applied_by`.
+**Plans and versions.** Fingerprints over canonical ASTs (reformatting SQL never triggers a rebuild — frozen by golden tests), change categorization breaking / non-breaking / indirect / forward-only with `plan --explain` reasoning and a `--reclassify` operator override, indirect physics reuse (descendants of a non-breaking change are not rebuilt — scdType2 keeps its history), `--forward-only` applies a change without replaying history (the new version inherits physical storage and done-intervals; new columns via `ALTER`), plan confirmation in a TTY, an applied-plans journal with `applied_by`.
 
 **Data quality.** A schema contract before every build (`DESCRIBE` of the query against the declared Schema), `notNull` / `unique` / `accepted` audits (blocking fails the apply, `warn` logs), a standalone `efmesh audit` over an environment's view layer, and `testModel` — unit tests for models on fixtures in in-memory DuckDB.
 
@@ -69,7 +77,7 @@ A typo in a `ref` is a compile error, not an empty run; renaming a parent's colu
 ## Quickstart
 
 ```sh
-bun add -d @avytheone/efmesh@beta
+bun add -d @avytheone/efmesh
 bunx efmesh init my-warehouse && cd my-warehouse
 bunx efmesh plan dev    # what would be done
 bunx efmesh apply dev   # physical tables, backfill, view layer
@@ -102,7 +110,7 @@ models (TS modules)  ──►  DAG + fingerprints over canonical ASTs
 - **Virtual layer** — views `<env>__<schema>.<table>` (prod is just `<schema>.<table>`) pointing at physical storage. An environment is a set of pointers; promotion and rollback are view swaps.
 - **The interval ledger** is the single source of truth about what has been computed: an interrupted backfill resumes where it stopped; recomputing an interval is a transactional DELETE+INSERT of the range — no duplicates.
 
-Full architecture, invariants and decisions: [SPEC.md](./SPEC.md) (in Russian).
+Full architecture, invariants and decisions: [SPEC.md](./SPEC.md).
 
 ## Data quality
 
@@ -157,18 +165,84 @@ export default defineConfig({
 | `efmesh plan <env>` | diff the project against an environment + missing intervals; changes nothing |
 | `efmesh apply <env>` | plan → confirmation (TTY) → physical tables, backfill, view layer |
 | `efmesh run <env>` | scheduler tick: new intervals only, under the lock; for cron |
+| `efmesh status <env>` | what is going on: last plan, interval lag, recent run ticks |
 | `efmesh audit <env>` | audit the environment's view layer — catches after-the-fact degradation |
-| `efmesh diff <envA> <envB>` | how two environments differ |
+| `efmesh diff <envA> <envB>` | how two environments differ; `--data` compares the actual data |
 | `efmesh render <model> [--env]` | the final SQL of a model |
 | `efmesh lineage <model[.col]>` | column lineage down to the raw sources |
 | `efmesh graph [--html]` | the model DAG as text or a page |
 | `efmesh janitor [--ttl 7]` | remove orphaned physical storage older than ttl |
 | `efmesh migrate` | bring the state-store schema up to the current version |
+| `efmesh schedule <env>` | register `run <env>` in the OS scheduler via `Bun.cron` |
 
 `apply`/`run` flags: `--jobs N` — DAG concurrency (always 1 on DuckDB — single connection), `--retries N` — retries for transient batch failures (exponential backoff), `--yes`/`-y` — skip confirmation, `--forward-only <model>,…` — reuse physical storage and history.
 
+`plan`/`apply` take `--reclassify <model>=breaking|non-breaking[,…]` — the
+operator's verdict on top of `--explain`, journaled with `applied_by`. A
+non-breaking parent lets unchanged descendants reuse their previous physical
+tables instead of rebuilding (scdType2 keeps its row history); an override
+that plainly contradicts the AST (dropped columns) is refused.
+
+`plan`, `audit` and `status` take `--json` — a stable machine-readable shape
+(a contract under semver) for CI and bots; exit codes are unchanged, stdout
+stays pure JSON.
+
+`plan --explain` adds the reasoning to every change: which canonical-AST
+nodes diverged (`where_clause`, `select_list[2] (added)`, …) and why the
+category followed — including cascade sources for `indirect`. The same
+data ships in `--json` as `explain`; the AST paths are a debugging hint,
+not part of the contract.
+
+`diff <envA> <envB> --data` compares the actual data of two environments:
+row counts, key overlap (grain or the kind's key), per-column mismatch
+rates among matched keys, schema drift between sides. `--sample P` (1–99)
+compares a deterministic share of keys — md5 buckets aligned across both
+sides, so sampling never fabricates only-in rows. `--model a,b` narrows,
+`--json` for CI.
+
+`schedule <env> [--cron '@hourly']` registers the `run` tick in the OS
+scheduler (crontab / launchd / Task Scheduler) via `Bun.cron` — idempotent
+by title, `--remove` unregisters, `--list` shows what's there. Honest
+caveats: OS cron runs in the local timezone and does not catch up on missed
+runs, and Arch-family Linux ships no cron daemon at all — `--print-systemd`
+emits user-unit files instead (`Persistent=true` catches up). Overlapping
+ticks are safe by construction: `run` takes the env lock and exits `2` when
+changes await a human.
+
 Exit codes: `0` — success, `1` — error, `2` — "awaiting a human": the plan needs confirmation in a non-TTY (add `--yes`), or `run` hit unapplied changes. In a non-TTY, `apply` with changes and no `--yes` refuses — efmesh will not silently roll out a plan nobody has seen.
 
+## Logging
+
+`apply` and `run` narrate what they do. Logs go to **stderr** — stdout stays
+reserved for the plan screen, summaries and `--json`, which stays byte-clean.
+Levels, set by the built-in `--log-level` flag (minimum level, default `info`):
+
+- **info** — lifecycle a human watches: per-model build start/finish with
+  duration, backfill batch progress (`batch 3 of 7` with the interval bounds),
+  promotion.
+- **warn** — warn-audits (violations that do not block) and retries.
+- **debug** — the rendered SQL about to run, lock acquire/release, and other
+  internals. `--log-level debug` also prints the full fiber trace on a failure.
+
+Each line carries structured fields as annotations (`model`, `env`, `interval`,
+…). At a TTY the output is pretty and colored; piped to a file or the systemd
+journal it is one-line [logfmt](https://brandur.org/logfmt) with no ANSI, so a
+log reader (or an AI agent post-morteming a 3am tick) can group by field.
+
+Embedding efmesh as a library? Logging is Effect's `Effect.log*` — provide your
+own `Logger` layer (sink, format, minimum level) and the CLI's choices do not
+apply. Row counts are not logged: efmesh never runs an extra query just to count.
+
+## Performance
+
+The framework overhead is negligible for any realistic project (in-memory DuckDB, `bun bench/plan-bench.ts N`):
+
+| models | cold plan | apply (all physical) | no-op plan | promote to prod |
+|---|---|---|---|---|
+| 100 | 54 ms | 158 ms | 3 ms | 51 ms |
+| 500 | 228 ms | 759 ms | 11 ms | 197 ms |
+| 2000 | 0.9 s | 2.9 s | 50 ms | 1.3 s |
+
 ## Postgres
 
 ```ts
@@ -186,10 +260,10 @@ Next up: categorization override in the plan dialog, non-time-based intervals. K
 
 ## Documentation
 
-- [SPEC.md](./SPEC.md) — the architecture spec: decisions, invariants, open questions (in Russian);
-- [CHANGELOG.md](./CHANGELOG.md) — release history (in Russian);
+- [SPEC.md](./SPEC.md) — the architecture spec: decisions, invariants, open questions;
+- [CHANGELOG.md](./CHANGELOG.md) — release history;
 - [examples/hospital](./examples/hospital/) — a live example with every model kind;
-- [CONTRIBUTING.md](./CONTRIBUTING.md) — build, test and PR guide (in Russian; PRs and issues in English are welcome).
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — build, test and PR guide.
 
 ## License
 

package/README.ru.md

@@ -4,10 +4,12 @@
 
 *Русское зеркало; основной README — [английский](./README.md).*
 
-[![ci](https://github.com/avytheone/efmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/avytheone/efmesh/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-orange) ![version](https://img.shields.io/badge/version-0.1.0--beta.1-blue) ![license](https://img.shields.io/badge/license-MIT-green) ![runtime](https://img.shields.io/badge/runtime-bun-black) ![effect](https://img.shields.io/badge/effect-v4-5C4EE5)
+[![ci](https://github.com/avytheone/efmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/avytheone/efmesh/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-orange) ![npm](https://img.shields.io/npm/v/%40avytheone%2Fefmesh) ![license](https://img.shields.io/badge/license-MIT-green) ![runtime](https://img.shields.io/badge/runtime-bun-black) ![effect](https://img.shields.io/badge/effect-v4-5C4EE5)
 
 Модели — обычные TypeScript-модули: тело на SQL, ссылки между моделями — импорты, форма данных — Effect Schema. efmesh считает fingerprint каждой модели по каноническому AST, хранит версии снапшотами, строит план как diff «проект против окружения» и применяет ровно его: физика пересчитывается только там, где что-то реально изменилось, а окружения (dev/prod/…) — виртуальные view поверх общей физики, промоушен в prod не стоит ни одного пересчёта.
 
+<p align="center"><img src="docs/demo.svg" alt="efmesh demo: a ref typo is a compile error; a plan rebuilds exactly the changed branch; promotion is a view swap" width="840"></p>
+
 ```ts
 import { Schema } from "effect"
 import { defineModel, kind } from "@avytheone/efmesh"
@@ -46,11 +48,17 @@ export const moves = defineModel(
 
 Опечатка в `ref` у нас — ошибка компиляции, а не пустой прогон; переименованная колонка родителя ломает сборку потомка до того, как SQL уедет в базу.
 
+## Зачем это существует: маленькие озёра данных
+
+Большинство аналитики в мире — не облачный warehouse, а данные DuckDB-класса: от гигабайт до терабайта на одной машине. Продуктовая аналитика стартапа, витрины одного отдела, on-prem и edge, pipeline внутри SaaS-приложения. dbt и sqlmesh родом из мира облачных DWH и тащат этот вес с собой (Python, адаптеры, инфраструктура). efmesh — это sqlmesh-подход, который `bun add` и поехал, а озеро — это папка parquet-файлов.
+
+Честная позиция: **ядро** — тот же класс систем, что sqlmesh (снапшоты, AST-fingerprint, план как diff, виртуальные окружения), но **широты** нет: ни облачных движков, ни мульти-диалекта, ни веб-UI, ни экосистемы пакетов — и нет амбиции всё это догонять. С dbt-core размен обратный: у dbt индустрия вокруг, но нет state-based планов, виртуальных окружений и версионирования по fingerprint — каждая команда сама изобретает «как не пересчитывать всё». Наши четыре честных преимущества: **типы как контракт DAG** (опечатка ломает сборку, а не ночной прогон), **библиотека прежде CLI** (`Efmesh.apply(...)` встраивается в приложение), **один язык на весь стек** (модели, приложение, тесты) и **кодовая база, читаемая за вечер** (~5.5k строк).
+
 ## Для кого это (и для кого нет)
 
 **Для вас**, если вы TypeScript-команда на Bun, хотите типизированный
 dbt/sqlmesh-подход поверх DuckDB или Postgres и готовы жить на бете
-(efmesh — 0.1.x, Effect v4 — beta, версия effect пинована peer-зависимостью).
+(efmesh — 0.2.x, Effect v4 — beta, версия effect пинована peer-зависимостью).
 
 **Не для вас**, если нужны: Node-рантайм (пока только Bun), мульти-диалект
 или облачные DWH (Snowflake/BigQuery — вне scope), стабильность уровня 1.0
@@ -62,7 +70,7 @@ dbt/sqlmesh-подход поверх DuckDB или Postgres и готовы ж
 
 **Цели материализации.** Нативная таблица движка, `parquet` (озеро: локально или s3://, интервал = партиция, view поверх `read_parquet`), `ducklake` (таблица-на-fingerprint в [DuckLake](https://ducklake.select)-каталоге — снапшоты и time travel каталога бонусом).
 
-**План и версии.** Fingerprint по каноническому AST (переформатирование SQL не триггерит пересборку), категоризация изменений breaking / non-breaking / indirect / forward-only, `--forward-only` — правка без переигрывания истории (новая версия наследует физику и done-интервалы, новые колонки — `ALTER`), подтверждение плана в TTY, журнал применений с `applied_by`.
+**План и версии.** Fingerprint по каноническому AST (переформатирование SQL не триггерит пересборку), категоризация изменений breaking / non-breaking / indirect / forward-only с обоснованием `plan --explain` и оператором-override `--reclassify`, indirect-реюз физики (потомки non-breaking-правки не пересобираются — scdType2 не теряет историю), `--forward-only` — правка без переигрывания истории (новая версия наследует физику и done-интервалы, новые колонки — `ALTER`), подтверждение плана в TTY, журнал применений с `applied_by`.
 
 **Качество.** Контракт схемы перед сборкой (`DESCRIBE` запроса против объявленной Schema), аудиты `notNull` / `unique` / `accepted` (blocking роняет apply, `warn` — логирует), автономный `efmesh audit` по view-слою окружения, `testModel` — юнит-тесты моделей на фикстурах в in-memory DuckDB.
 
@@ -73,7 +81,7 @@ dbt/sqlmesh-подход поверх DuckDB или Postgres и готовы ж
 ## Быстрый старт
 
 ```sh
-bun add -d @avytheone/efmesh@beta
+bun add -d @avytheone/efmesh
 bunx efmesh init my-warehouse && cd my-warehouse
 bunx efmesh plan dev    # что будет сделано
 bunx efmesh apply dev   # физика, бэкфилл, view-слой
@@ -161,21 +169,88 @@ export default defineConfig({
 | `efmesh plan <env>` | diff проекта против окружения + недостающие интервалы, ничего не меняет |
 | `efmesh apply <env>` | план → подтверждение (TTY) → физика, бэкфилл, view-слой |
 | `efmesh run <env>` | тик планировщика: только новые интервалы, под локом; для cron |
+| `efmesh status <env>` | что происходит: последний план, отставание интервалов, тики run |
 | `efmesh audit <env>` | аудиты view-слоя окружения — ловит деградацию задним числом |
-| `efmesh diff <envA> <envB>` | чем окружения отличаются |
+| `efmesh diff <envA> <envB>` | чем окружения отличаются; `--data` сравнивает сами данные |
 | `efmesh render <model> [--env]` | итоговый SQL модели |
 | `efmesh lineage <model[.col]>` | колоночный lineage до сырья |
 | `efmesh graph [--html]` | DAG моделей текстом или страницей |
 | `efmesh janitor [--ttl 7]` | снести осиротевшую физику старше ttl |
 | `efmesh migrate` | догнать схему state store до текущей версии |
+| `efmesh schedule <env>` | зарегистрировать `run <env>` в OS-шедулере через `Bun.cron` |
 
 Флаги `apply`/`run`: `--jobs N` — DAG-конкурентность (на DuckDB всегда 1 — одно соединение), `--retries N` — ретраи транзиентных сбоев батча (экспоненциальная пауза), `--yes`/`-y` — без подтверждения, `--forward-only <model>,…` — реюз физики и истории.
 
+`plan`/`apply` принимают `--reclassify <model>=breaking|non-breaking[,…]` —
+вердикт оператора поверх `--explain`, журналируется с `applied_by`.
+Non-breaking-родитель разрешает нетронутым потомкам реюзать физику вместо
+пересборки (scdType2 не теряет историю строк); override, очевидно
+противоречащий AST (удалённые колонки), не принимается.
+
+`plan`, `audit` и `status` принимают `--json` — стабильная машиночитаемая
+форма (контракт в рамках semver) для CI и ботов; exit-коды не меняются,
+stdout — чистый JSON.
+
+`plan --explain` добавляет к каждому изменению обоснование: какие узлы
+канонического AST разошлись (`where_clause`, `select_list[2] (добавлен)`, …)
+и почему категория именно такая — включая источники каскада у `indirect`.
+Те же данные попадают в `--json` полем `explain`; пути по AST — отладочная
+подсказка, не часть контракта.
+
+`diff <envA> <envB> --data` сравнивает сами данные двух окружений: счётчики
+строк, пересечение по ключу (grain или ключ вида), доли расхождений по
+колонкам среди сопоставленных ключей, дрейф схемы между сторонами.
+`--sample P` (1–99) сравнивает детерминированную долю ключей — md5-бакеты
+выровнены между сторонами, выборка не рождает ложных only-in. `--model a,b`
+сужает, `--json` для CI.
+
+`schedule <env> [--cron '@hourly']` регистрирует тик `run` в OS-шедулере
+(crontab / launchd / Task Scheduler) через `Bun.cron` — идемпотентно по
+заголовку, `--remove` снимает, `--list` показывает записи. Честные
+оговорки: OS-cron живёт в локальной таймзоне и не догоняет пропущенные
+запуски, а Arch-семейство Linux вовсе не ставит cron-демона —
+`--print-systemd` печатает user-юниты (`Persistent=true` догоняет).
+Наложение тиков безопасно по построению: `run` берёт env-лок и выходит
+с кодом `2`, когда изменения ждут человека.
+
 Exit-коды: `0` — успех, `1` — ошибка, `2` — «ждёт человека»: план требует
 подтверждения в не-TTY (нужен `--yes`) или `run` упёрся в неприменённые
 изменения. В не-TTY `apply` с изменениями БЕЗ `--yes` не применяется —
 молча катить план, который никто не видел, efmesh отказывается.
 
+## Логирование
+
+`apply` и `run` рассказывают, что делают. Логи идут в **stderr** — stdout
+остаётся под план, сводки и `--json`, который остаётся байт-чистым JSON.
+Уровни задаёт встроенный флаг `--log-level` (минимальный уровень, по
+умолчанию `info`):
+
+- **info** — жизненный цикл, за которым следит человек: старт/финиш сборки
+  каждой модели с длительностью, прогресс бэкфила (`batch 3 of 7` с границами
+  интервала), промоушен.
+- **warn** — warn-аудиты (нарушения, которые не блокируют) и ретраи.
+- **debug** — рендер SQL перед выполнением, взятие/освобождение лока и прочие
+  внутренности. `--log-level debug` также печатает полный fiber-trace при сбое.
+
+В каждой строке структурные поля-аннотации (`model`, `env`, `interval`, …). В
+TTY вывод красивый и цветной; в файл или systemd journal — однострочный
+[logfmt](https://brandur.org/logfmt) без ANSI, чтобы читатель логов (или
+ИИ-агент, разбирающий трёхчасовой ночной тик) группировал по полям.
+
+Встраиваете efmesh как библиотеку? Логирование — это `Effect.log*`: дайте свой
+`Logger`-слой (приёмник, формат, минимальный уровень), и выбор CLI не действует.
+Число строк не логируется: efmesh не делает лишний запрос ради подсчёта.
+
+## Перфоманс
+
+Оверхед фреймворка пренебрежим для любого реалистичного проекта (in-memory DuckDB, `bun bench/plan-bench.ts N`):
+
+| моделей | plan холодный | apply (вся физика) | plan пустой | промоушен prod |
+|---|---|---|---|---|
+| 100 | 54 мс | 158 мс | 3 мс | 51 мс |
+| 500 | 228 мс | 759 мс | 11 мс | 197 мс |
+| 2000 | 0.9 с | 2.9 с | 50 мс | 1.3 с |
+
 ## Postgres
 
 ```ts