@avytheone/efmesh 0.1.0-beta.2 → 0.2.1

package/src/state/sqlite.ts

@@ -6,6 +6,7 @@ import type {
   IntervalRecord,
   MigrationReport,
   PlanRecord,
+  RunRecord,
   SnapshotRecord,
   StateStoreShape,
 } from "./store.ts"
@@ -46,6 +47,18 @@ CREATE TABLE IF NOT EXISTS intervals (
   updated_at  TEXT NOT NULL,
   PRIMARY KEY (snapshot_fp, start_ts)
 );
+CREATE TABLE IF NOT EXISTS runs (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  env         TEXT NOT NULL,
+  started_at  TEXT NOT NULL,
+  finished_at TEXT NOT NULL,
+  outcome     TEXT NOT NULL,
+  detail      TEXT NOT NULL DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS canon_cache (
+  key       TEXT PRIMARY KEY,
+  canonical TEXT NOT NULL
+);
 CREATE TABLE IF NOT EXISTS locks (
   name        TEXT PRIMARY KEY,
   acquired_at TEXT NOT NULL,
@@ -54,7 +67,7 @@ CREATE TABLE IF NOT EXISTS locks (
 `
 
 export interface SqliteStateOptions {
-  /** Путь к файлу состояния; по умолчанию in-memory (тесты). */
+  /** Path to the state file; defaults to in-memory (tests). */
   readonly path?: string
 }
 
@@ -65,7 +78,7 @@ const tableExists = (db: Database, name: string): boolean =>
     .query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1`)
     .get(name) !== null
 
-/** 0 — стор без таблицы meta (создан до появления версионирования, F0–F3). */
+/** 0 — a store with no meta table (created before versioning existed, F0–F3). */
 const readVersion = (db: Database): number => {
   if (!tableExists(db, "meta")) return 0
   const row = db.query(`SELECT version FROM meta`).get() as { version: number } | null
@@ -73,11 +86,11 @@ const readVersion = (db: Database): number => {
 }
 
 /**
- * Догоняет схему до STATE_VERSION. Версия 1 = базовая раскладка F4,
- * версия 2 = applied_by в журнале планов (F5); ALTER-ы ниже подхватывают
- * сторы, созданные до соответствующих колонок (canonical_ast — F2,
- * orphaned_at/physical_fp — F3, applied_by — F5), — на новом сторе
- * они no-op через try/catch. Будущие версии — новые записи здесь же.
+ * Catches the schema up to STATE_VERSION. Version 1 = base layout F4,
+ * version 2 = applied_by in the plan journal (F5); the ALTERs below pick up
+ * stores created before the corresponding columns existed (canonical_ast —
+ * F2, orphaned_at/physical_fp — F3, applied_by — F5) — on a fresh store
+ * they are a no-op via try/catch. Future versions get new entries right here.
  */
 const applyMigrations = (db: Database): void => {
   db.exec(SCHEMA)
@@ -91,7 +104,7 @@ const applyMigrations = (db: Database): void => {
     try {
       db.exec(alter)
     } catch {
-      // колонка уже есть
+      // column already exists
     }
   }
   db.exec(`CREATE TABLE IF NOT EXISTS meta (version INTEGER NOT NULL)`)
@@ -100,9 +113,9 @@ const applyMigrations = (db: Database): void => {
 }
 
 /**
- * `efmesh migrate`: явное обновление схемы существующего стора.
- * Перед апгрейдом файл копируется в `<path>.backup-v<from>` — откат
- * на старую версию efmesh иначе односторонний (F6).
+ * `efmesh migrate`: an explicit schema upgrade of an existing store.
+ * Before the upgrade, the file is copied to `<path>.backup-v<from>` —
+ * otherwise rolling back to an older efmesh version would be a one-way trip (F6).
  */
 export const migrateSqliteState = (
   options?: SqliteStateOptions,
@@ -144,9 +157,9 @@ export const SqliteStateLive = (
         }),
         (db) => Effect.sync(() => db.close()),
       )
-      // свежий стор бутстрапится на текущую версию; существующий со схемой
-      // старше требует явного `efmesh migrate` — молча менять чужие данные
-      // при открытии нельзя (SPEC §6)
+      // a fresh store bootstraps at the current version; an existing store
+      // with an older schema requires an explicit `efmesh migrate` — silently
+      // rewriting someone else's data on open is not allowed (SPEC §6)
       const fresh = yield* Effect.try({
         try: () => !tableExists(db, "snapshots"),
         catch: (cause) => new StateError({ operation: "open", cause }),
@@ -174,10 +187,10 @@ export const SqliteStateLive = (
           isoNow.pipe(
             Effect.flatMap((now) =>
               attempt("upsertSnapshot", () => {
-                // воскрешение версии (повторный apply старого fingerprint)
-                // снимает сиротство И освежает created_at СРАЗУ: между upsert
-                // и промоушеном janitor не сочтёт её обречённой ни по
-                // orphaned_at, ни по старому created_at (гонка F6)
+                // reviving a version (a repeated apply of an old fingerprint)
+                // clears orphan status AND refreshes created_at IMMEDIATELY: between
+                // the upsert and promotion, the janitor won't judge it doomed by
+                // either orphaned_at or a stale created_at (race, F6)
                 db.query(
                   `INSERT INTO snapshots (name, fingerprint, rendered_sql, canonical_ast, physical_fp, kind, fingerprint_version, created_at)
                    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
@@ -281,16 +294,16 @@ export const SqliteStateLive = (
             Effect.flatMap((now) =>
               attempt("promote", () => {
                 const replace = db.transaction(() => {
-                  // живость снапшотов — в той же транзакции: если janitor
-                  // успел унести версию, промоушен громко падает, а view
-                  // не переключается на снесённую физику (гонка F6)
+                  // snapshot liveness — in the same transaction: if the janitor
+                  // already removed the version, promotion fails loudly, and the
+                  // view never switches to demolished physics (race, F6)
                   const alive = db.query(
                     `SELECT 1 FROM snapshots WHERE name = ?1 AND fingerprint = ?2`,
                   )
                   for (const entry of entries) {
                     if (entry.requireSnapshot === true && alive.get(entry.name, entry.fingerprint) === null) {
                       throw new Error(
-                        `промоушен ${env}: снапшот ${entry.name}@${entry.fingerprint.slice(0, 8)} исчез из стора (снесён janitor?) — повторите apply`,
+                        `promotion "${env}": snapshot ${entry.name}@${entry.fingerprint.slice(0, 8)} vanished from the store (removed by janitor?) — retry apply`,
                       )
                     }
                   }
@@ -302,9 +315,9 @@ export const SqliteStateLive = (
                   for (const entry of entries) {
                     insert.run(env, entry.name, entry.fingerprint, now)
                   }
-                  // ссылочность меняется только здесь — тут же и учёт сиротства:
-                  // потерявшие последнюю ссылку получают отметку, вернувшиеся
-                  // (откат на старую версию) — теряют её (SPEC §5.4)
+                  // referencing changes only here — so orphan bookkeeping happens
+                  // right here too: those losing their last reference get marked,
+                  // those returning (rollback to an old version) lose the mark (SPEC §5.4)
                   db.query(
                     `UPDATE snapshots SET orphaned_at = ?1
                      WHERE orphaned_at IS NULL
@@ -342,6 +355,40 @@ export const SqliteStateLive = (
               .all(env) as ReadonlyArray<PlanRecord>
           }),
 
+        getCanon: (key) =>
+          attempt("getCanon", () => {
+            const row = db
+              .query(`SELECT canonical FROM canon_cache WHERE key = ?1`)
+              .get(key) as { canonical: string } | null
+            return row?.canonical ?? undefined
+          }),
+
+        putCanon: (key, canonical) =>
+          attempt("putCanon", () => {
+            db.query(
+              `INSERT INTO canon_cache (key, canonical) VALUES (?1, ?2)
+               ON CONFLICT (key) DO NOTHING`,
+            ).run(key, canonical)
+          }),
+
+        recordRun: (record) =>
+          attempt("recordRun", () => {
+            db.query(
+              `INSERT INTO runs (env, started_at, finished_at, outcome, detail)
+               VALUES (?1, ?2, ?3, ?4, ?5)`,
+            ).run(record.env, record.startedAt, record.finishedAt, record.outcome, record.detail)
+          }),
+
+        listRuns: (env, limit) =>
+          attempt("listRuns", () => {
+            return db
+              .query(
+                `SELECT id, env, started_at AS startedAt, finished_at AS finishedAt, outcome, detail
+                 FROM runs WHERE env = ?1 ORDER BY id DESC LIMIT ?2`,
+              )
+              .all(env, limit) as ReadonlyArray<RunRecord>
+          }),
+
         acquireLock: (name, ttlMs) =>
           Clock.currentTimeMillis.pipe(
             Effect.flatMap((nowMs) =>
@@ -349,8 +396,8 @@ export const SqliteStateLive = (
                 const now = new Date(nowMs).toISOString()
                 const expires = new Date(nowMs + ttlMs).toISOString()
                 const acquire = db.transaction(() => {
-                  // протухший лок упавшего процесса перехватывается;
-                  // <= — лок, истёкший в момент T, свободен с T (ttl=0 в ту же мс)
+                  // a stale lock from a crashed process is reclaimed;
+                  // <= — a lock that expires at instant T is free as of T (ttl=0 in the same ms)
                   db.query(`DELETE FROM locks WHERE name = ?1 AND expires_at <= ?2`).run(name, now)
                   const result = db
                     .query(

package/src/state/store.ts

@@ -1,64 +1,75 @@
 import { Context, Data, Effect } from "effect"
+import { causeText } from "../error-text.ts"
 
 export class StateError extends Data.TaggedError("StateError")<{
   readonly operation: string
   readonly cause: unknown
-}> {}
+}> {
+  override get message(): string {
+    return `state store: ${this.operation} failed — ${causeText(this.cause)}`
+  }
+}
 
 /**
- * Текущая версия схемы state store. Свежий стор бутстрапится сразу
- * на неё; стор со схемой старше (в т.ч. созданный до появления версии)
- * открытие не проходит — данные догоняет явный `efmesh migrate`.
- * 1 — базовая раскладка (F4), 2 — applied_by в журнале планов (F5),
- * 3 — fingerprint_version в снапшотах (F6).
+ * Current schema version of the state store. A fresh store bootstraps
+ * directly at it; a store with an older schema (including one created
+ * before versioning existed) refuses to open — data catches up via an
+ * explicit `efmesh migrate`.
+ * 1 — base layout (F4), 2 — applied_by in the plan journal (F5),
+ * 3 — fingerprint_version in snapshots (F6), 4 — run tick journal (0.2.0),
+ * 5 — canonicalization cache canon_cache (0.2.0, #8).
  */
-export const STATE_VERSION = 3
+export const STATE_VERSION = 5
 
-/** Схема стора не совпадает с ожидаемой бинарём — нужен `efmesh migrate`. */
+/** Store schema doesn't match the binary's expectation — `efmesh migrate` is needed. */
 export class StateSchemaError extends Data.TaggedError("StateSchemaError")<{
   readonly found: number
   readonly wanted: number
-}> {}
+}> {
+  override get message(): string {
+    return `state store schema is v${this.found}, but this efmesh expects v${this.wanted} — run \`efmesh migrate\``
+  }
+}
 
-/** Итог миграции для CLI. */
+/** Migration outcome for the CLI. */
 export interface MigrationReport {
   readonly from: number
   readonly to: number
-  /** Куда сложена копия стора перед апгрейдом схемы (SQLite; F6). */
+  /** Where the store's copy was stashed before the schema upgrade (SQLite; F6). */
   readonly backup?: string
 }
 
-/** Версия модели, известная state store (SPEC §6). */
+/** A model version known to the state store (SPEC §6). */
 export interface SnapshotRecord {
   readonly name: string
   readonly fingerprint: string
-  /** Canonical-рендер SQL — для diff-показа и отладки. */
+  /** Canonical SQL rendering — for diff display and debugging. */
   readonly renderedSql: string
-  /** Канонический AST тела (JSON) — для категоризации изменений (SPEC §5.2). */
+  /** Canonical AST of the body (JSON) — for categorizing changes (SPEC §5.2). */
   readonly canonicalAst: string
   /**
-   * Fingerprint, чьей физической таблицей/префиксом пользуется снапшот.
-   * Обычно равен собственному; при forward-only (SPEC §5.2) — наследуется
-   * от предыдущей версии: физика переиспользуется, история не переигрывается.
+   * Fingerprint whose physical table/prefix this snapshot uses.
+   * Usually its own; under forward-only (SPEC §5.2) it is inherited
+   * from the previous version: physics is reused, history is not replayed.
    */
   readonly physicalFp: string
   readonly kind: string
   /**
-   * Версия алгоритма fingerprint, которым посчитан снапшот (SPEC §4).
-   * План сравнивает только одноверсионные отпечатки; иная версия —
-   * громкая остановка, не тихий «всё breaking».
+   * Version of the fingerprint algorithm used to compute this snapshot (SPEC §4).
+   * Plan only compares same-version fingerprints; a different version is
+   * a loud stop, not a silent "everything is breaking".
    */
   readonly fingerprintVersion: number
   readonly createdAt: string
   /**
-   * Когда снапшот перестал быть указан хоть одним окружением (ISO UTC);
-   * null — на него ссылаются. Ставится и снимается при промоушене,
-   * ttl janitor'а отсчитывается отсюда (SPEC §5.4).
+   * When the snapshot stopped being pointed to by any environment (ISO UTC);
+   * null means it is still referenced. Set and cleared on promotion,
+   * the janitor's ttl is counted from here (SPEC §5.4).
    */
   readonly orphanedAt: string | null
 }
 
-/** Строка окружения: логическое имя → снапшот, на который указывает view. */
+/** Environment row: logical name → snapshot the view points to. */
 export interface EnvironmentRecord {
   readonly env: string
   readonly name: string
@@ -71,14 +82,30 @@ export interface PlanRecord {
   readonly env: string
   readonly summary: string
   readonly appliedAt: string
-  /** Кто применил план (ОС-пользователь или ApplyOptions.appliedBy); '' у записей до v2. */
+  /** Who applied the plan (OS user or ApplyOptions.appliedBy); '' for records predating v2. */
   readonly appliedBy: string
 }
 
 /**
- * Учёт заполненных интервалов снапшота (SPEC §6) — единственный источник
- * правды о том, что посчитано: физическая таблица без записей здесь
- * считается пустой. Границы — ISO UTC (сортируются лексикографически).
+ * Run tick journal entry (SPEC §7, issue #2): a cron tick that fails at
+ * three in the morning must be debuggable after the fact. outcome:
+ * ok — tick succeeded; awaiting-human — there are unapplied changes (exit 2);
+ * lock-held — the environment is held by another process; error — an actual failure.
+ */
+export interface RunRecord {
+  readonly id: number
+  readonly env: string
+  readonly startedAt: string
+  readonly finishedAt: string
+  readonly outcome: "ok" | "awaiting-human" | "lock-held" | "error"
+  /** ok: JSON array of collected models; awaiting-human: list of changes; error: error tag. */
+  readonly detail: string
+}
+
+/**
+ * Bookkeeping of a snapshot's filled intervals (SPEC §6) — the single source
+ * of truth for what has been computed: a physical table with no records here
+ * is considered empty. Bounds are ISO UTC (sorted lexicographically).
  */
 export interface IntervalRecord {
   readonly snapshotFp: string
@@ -89,7 +116,7 @@ export interface IntervalRecord {
 }
 
 export interface StateStoreShape {
-  /** Идемпотентно: (name, fingerprint) уникальны, повторная запись — no-op. */
+  /** Idempotent: (name, fingerprint) is unique, a repeated write is a no-op. */
   readonly upsertSnapshot: (
     snapshot: Omit<SnapshotRecord, "createdAt" | "orphanedAt">,
   ) => Effect.Effect<void, StateError>
@@ -97,17 +124,18 @@ export interface StateStoreShape {
     name: string,
     fingerprint: string,
   ) => Effect.Effect<SnapshotRecord | undefined, StateError>
-  /** Все снапшоты, на которые ссылается хоть одно окружение, — для janitor. */
+  /** All snapshots referenced by at least one environment — for the janitor. */
   readonly listReferencedFingerprints: () => Effect.Effect<ReadonlySet<string>, StateError>
   readonly listSnapshots: () => Effect.Effect<ReadonlyArray<SnapshotRecord>, StateError>
-  /** Удаляет запись снапшота и его учёт интервалов (физику убирает janitor). */
+  /** Deletes the snapshot record and its interval bookkeeping (the janitor removes the physics). */
   readonly deleteSnapshot: (name: string, fingerprint: string) => Effect.Effect<void, StateError>
   /**
-   * Транзакционный «claim» сироты janitor'ом (SPEC §5.4, F6): запись и учёт
-   * интервалов удаляются, только если снапшот ВСЁ ЕЩЁ не referenced ни одним
-   * окружением и осиротел не позже deadline (ISO UTC) — обе проверки в одной
-   * транзакции с удалением, поэтому параллельный apply, воскресивший версию,
-   * не даст её унести. true — снесено, false — состояние изменилось.
+   * Transactional "claim" of an orphan by the janitor (SPEC §5.4, F6): the
+   * record and its interval bookkeeping are deleted only if the snapshot is
+   * STILL not referenced by any environment and orphaned no later than the
+   * deadline (ISO UTC) — both checks run in the same transaction as the
+   * delete, so a concurrent apply that revived the version can't lose it to
+   * removal. true — removed, false — state changed underneath.
    */
   readonly deleteSnapshotIfDoomed: (
     name: string,
@@ -118,10 +146,10 @@ export interface StateStoreShape {
     env: string,
   ) => Effect.Effect<ReadonlyArray<EnvironmentRecord>, StateError>
   /**
-   * Транзакционно заменяет весь набор окружения. Записи с
-   * `requireSnapshot: true` проверяются на живость снапшота в той же
-   * транзакции: если janitor успел его унести, промоушен громко падает —
-   * view никогда не переключается на снесённую физику.
+   * Transactionally replaces the environment's whole set. Entries with
+   * `requireSnapshot: true` are checked for the snapshot's liveness in the
+   * same transaction: if the janitor already removed it, promotion fails
+   * loudly — the view never switches to demolished physics.
    */
   readonly promote: (
     env: string,
@@ -131,21 +159,36 @@ export interface StateStoreShape {
       readonly requireSnapshot?: boolean
     }>,
   ) => Effect.Effect<void, StateError>
-  /** Журнал применённых планов. */
+  /** Journal of applied plans. */
   readonly recordPlan: (
     env: string,
     summary: string,
     appliedBy: string,
   ) => Effect.Effect<void, StateError>
+  /**
+   * Canonicalization cache (#8): the key already includes the dialect and
+   * FINGERPRINT_VERSION — a change in algorithm or engine can never hand back
+   * a stale canon. The cache is not data: a miss or failure is safe, the
+   * caller must swallow it.
+   */
+  readonly getCanon: (key: string) => Effect.Effect<string | undefined, StateError>
+  readonly putCanon: (key: string, canonical: string) => Effect.Effect<void, StateError>
+  /** Run tick journal (SPEC §7): the outcome of every tick, including unsuccessful ones. */
+  readonly recordRun: (record: Omit<RunRecord, "id">) => Effect.Effect<void, StateError>
+  /** The environment's most recent ticks, newest first. */
+  readonly listRuns: (
+    env: string,
+    limit: number,
+  ) => Effect.Effect<ReadonlyArray<RunRecord>, StateError>
   readonly listPlans: (env: string) => Effect.Effect<ReadonlyArray<PlanRecord>, StateError>
   /**
-   * Межпроцессная блокировка (SPEC §7): true — получена, false — держит
-   * другой процесс. Протухшие (expires) локи перехватываются — упавший
-   * процесс не оставляет вечный замок.
+   * Cross-process lock (SPEC §7): true — acquired, false — held by another
+   * process. Stale (expired) locks are reclaimed — a crashed process
+   * doesn't leave a lock held forever.
    */
   readonly acquireLock: (name: string, ttlMs: number) => Effect.Effect<boolean, StateError>
   readonly releaseLock: (name: string) => Effect.Effect<void, StateError>
-  /** Транзакционный upsert интервалов снапшота (повторная отметка — обновление статуса). */
+  /** Transactional upsert of snapshot intervals (re-marking updates the status). */
   readonly markIntervals: (
     snapshotFp: string,
     intervals: ReadonlyArray<{ readonly startTs: string; readonly endTs: string }>,

package/src/testing/index.ts

@@ -7,22 +7,22 @@ import { DuckDBEngineLive } from "../engine/duckdb.ts"
 import { familyOfAst, type TypeFamily } from "../plan/contract.ts"
 
 /**
- * Юнит-тест модели на фикстурах (SPEC §8): `ctx.ref` рендерится в CTE
- * с VALUES из фикстур, валидированных через Schema модели-источника
- * (модель помнит источники значениями — model.refs), запрос выполняется
- * на одноразовом in-memory DuckDB, результат сравнивается с ожидаемым.
- * Живёт в bun test:
+ * Unit-tests a model against fixtures (SPEC §8): `ctx.ref` is rendered into a
+ * CTE with VALUES from the fixtures, validated against the source model's
+ * Schema (the model remembers its sources by value — model.refs); the query
+ * runs on a throwaway in-memory DuckDB, and the result is compared to the
+ * expectation. Lives in bun test:
  *
  *   test("stays", () => testModel(stays, { inputs: {...}, expect: [...] }))
  */
 
 export interface TestModelSpec {
-  /** Фикстуры по полным именам моделей-источников; нужны для всех deps. */
+  /** Fixtures keyed by source models' full names; required for every dep. */
   readonly inputs?: Readonly<Record<string, ReadonlyArray<Record<string, unknown>>>>
-  /** Границы интервала [start, end) — обязательны для incremental-моделей. */
+  /** Interval bounds [start, end) — required for incremental models. */
   readonly interval?: readonly [string, string]
   readonly expect: ReadonlyArray<Record<string, unknown>>
-  /** Сравнивать порядок строк; по умолчанию порядок не важен. */
+  /** Whether row order matters; unordered by default. */
   readonly strictOrder?: boolean
 }
 
@@ -34,7 +34,7 @@ const DUCK_TYPE: Record<TypeFamily, string> = {
   any: "VARCHAR",
 }
 
-/** Литерал фикстуры по семейству колонки (ISO-строки времени → TIMESTAMP). */
+/** Fixture literal by column family (ISO time strings → TIMESTAMP). */
 const fixtureLiteral = (value: unknown, family: TypeFamily): string => {
   if (value === null || value === undefined) return "NULL"
   if (family === "temporal") return sqlTimestamp(fromIso(String(value)))
@@ -46,14 +46,15 @@ const fixtureLiteral = (value: unknown, family: TypeFamily): string => {
   ) {
     return escapeLiteral(value)
   }
-  throw new Error(`фикстура содержит нерендерируемое значение: ${String(value)}`)
+  throw new Error(`fixture contains a non-renderable value: ${String(value)}`)
 }
 
 /**
- * Фикстура не может врать о форме входа: значения сверяются с семействами
- * типов Schema источника (строки времени — ISO; Schema.DateTimeUtc в v4
- * декодирует готовый DateTime.Utc, не строку, поэтому проверка по семейству,
- * не через decode), лишние ключи — опечатки — отвергаются.
+ * A fixture cannot lie about the shape of its input: values are checked
+ * against the source Schema's type families (time strings are ISO; in v4
+ * Schema.DateTimeUtc decodes to a ready DateTime.Utc, not a string, so the
+ * check is by family rather than via decode), and extra keys — typos — are
+ * rejected.
  */
 const validateFixture = (
   source: AnyModel,
@@ -63,7 +64,7 @@ const validateFixture = (
   const known = new Set(fields.map(([name]) => name))
   for (const key of Object.keys(row)) {
     if (!known.has(key)) {
-      throw new Error(`фикстура ${source.name.full}: лишняя колонка «${key}»`)
+      throw new Error(`fixture ${source.name.full}: extra column «${key}»`)
     }
   }
   for (const [name, field] of fields) {
@@ -82,13 +83,13 @@ const validateFixture = (
               : true
     if (!ok) {
       throw new Error(
-        `фикстура ${source.name.full}: колонка «${name}» ждёт ${family}, получено ${JSON.stringify(value)}`,
+        `fixture ${source.name.full}: column «${name}» expects ${family}, got ${JSON.stringify(value)}`,
       )
     }
   }
 }
 
-/** CTE источника: VALUES из фикстур или пустой SELECT с типами схемы. */
+/** Source CTE: VALUES from fixtures, or an empty SELECT typed by the schema. */
 const fixtureCte = (source: AnyModel, rows: ReadonlyArray<Record<string, unknown>>): string => {
   const fields = Object.entries(source.schema.fields) as ReadonlyArray<
     [string, { readonly ast: unknown }]
@@ -109,7 +110,7 @@ const fixtureCte = (source: AnyModel, rows: ReadonlyArray<Record<string, unknown
   return `SELECT * FROM (VALUES ${tuples.join(", ")}) AS t(${columns})`
 }
 
-/** DuckDB-значения → сравнимые примитивы (bigint → number, объекты времени → строка). */
+/** DuckDB values → comparable primitives (bigint → number, time objects → string). */
 const normalize = (row: Record<string, unknown>): Record<string, unknown> =>
   Object.fromEntries(
     Object.entries(row).map(([key, value]) => {
@@ -130,7 +131,7 @@ const canonical = (
   return strictOrder ? normalized : [...normalized].sort()
 }
 
-/** Прогоняет модель на фикстурах, возвращает строки — для нестандартных проверок. */
+/** Runs the model against fixtures, returning rows — for non-standard checks. */
 export const runModel = async (
   model: AnyModel,
   spec: Pick<TestModelSpec, "inputs" | "interval">,
@@ -138,16 +139,16 @@ export const runModel = async (
   const inputs = spec.inputs ?? {}
   for (const dep of model.deps) {
     if (!(dep in inputs)) {
-      throw new Error(`нет фикстуры для источника ${dep} (deps модели ${model.name.full})`)
+      throw new Error(`no fixture for source ${dep} (deps of model ${model.name.full})`)
     }
   }
   for (const name of Object.keys(inputs)) {
     if (!model.deps.has(name)) {
-      throw new Error(`фикстура «${name}» не является источником модели ${model.name.full}`)
+      throw new Error(`fixture «${name}» is not a source of model ${model.name.full}`)
     }
   }
   if (usesBounds(model.fragment) && spec.interval === undefined) {
-    throw new Error(`модель ${model.name.full} использует ctx.start/ctx.end — укажи interval`)
+    throw new Error(`model ${model.name.full} uses ctx.start/ctx.end — provide interval`)
   }
 
   const ctes = [...model.deps]
@@ -174,7 +175,7 @@ export const runModel = async (
   )
 }
 
-/** Прогоняет модель на фикстурах и сверяет результат с ожиданием. */
+/** Runs the model against fixtures and checks the result against the expectation. */
 export const testModel = async (model: AnyModel, spec: TestModelSpec): Promise<void> => {
   const rows = await runModel(model, spec)
   const got = canonical(rows, spec.strictOrder ?? false)
@@ -182,10 +183,10 @@ export const testModel = async (model: AnyModel, spec: TestModelSpec): Promise<v
   if (got.length !== want.length || got.some((row, index) => row !== want[index])) {
     throw new Error(
       [
-        `результат модели ${model.name.full} не совпал с ожиданием:`,
-        `— получено (${got.length}):`,
+        `result of model ${model.name.full} did not match the expectation:`,
+        `— got (${got.length}):`,
         ...got.map((row) => `    ${row}`),
-        `— ожидалось (${want.length}):`,
+        `— expected (${want.length}):`,
         ...want.map((row) => `    ${row}`),
       ].join("\n"),
     )