@avytheone/efmesh 0.2.0 → 0.2.1

package/src/plan/naming.ts

@@ -1,14 +1,14 @@
 import type { ExternalSource, ModelName } from "../core/model.ts"
 
 /**
- * Раскладка объектов в движке (SPEC §2):
- * - физика: схема `_efmesh`, таблица `<схема>__<таблица>__<fp8>`;
- * - виртуалка: prod живёт в родных схемах моделей (`med.stays`),
- *   остальные окружения — в префиксованных (`dev__med.stays`).
+ * Object layout in the engine (SPEC §2):
+ * - physical: schema `_efmesh`, table `<schema>__<table>__<fp8>`;
+ * - virtual: prod lives in the models' native schemas (`med.stays`),
+ *   other environments — in prefixed ones (`dev__med.stays`).
  *
- * Схема именно `_efmesh`, не `efmesh`: DuckDB называет каталог по имени
- * файла базы, и для `efmesh.duckdb` ссылка `efmesh.x` становится
- * неоднозначной (каталог или схема) — Binder Error.
+ * The schema is `_efmesh`, not `efmesh`, precisely because: DuckDB names the
+ * catalog after the database file name, and for `efmesh.duckdb` the reference
+ * `efmesh.x` becomes ambiguous (catalog or schema) — a Binder Error.
  */
 
 export const PROD_ENV = "prod"
@@ -31,28 +31,28 @@ export const envSchema = (env: string, modelSchema: string): string =>
   env === PROD_ENV ? modelSchema : `${env}__${modelSchema}`
 
 /**
- * Раскладка parquet-озера (SPEC §3.3): `<lake>/<схема>/<таблица>/fp=<fp8>/…`,
- * у incremental внутри — партиции `interval=<ключ>/data.parquet`.
- * Интервал = партиция: пересчёт — перезапись файлов партиции, источник
- * правды — учёт интервалов, поэтому неатомарность перезаписи не страшна.
+ * Parquet-lake layout (SPEC §3.3): `<lake>/<schema>/<table>/fp=<fp8>/…`,
+ * for incremental inside — partitions `interval=<key>/data.parquet`.
+ * Interval = partition: a recompute rewrites the partition's files, the
+ * source of truth is the interval bookkeeping, so a non-atomic rewrite is harmless.
  */
 export const parquetPrefix = (lakePath: string, name: ModelName, fingerprint: string): string =>
   `${lakePath.replace(/\/+$/, "")}/${name.schema}/${name.table}/fp=${fp8(fingerprint)}`
 
 /**
- * union_by_name: партиции одного префикса могут отличаться схемой после
- * forward-only-эволюции (новые колонки появляются только в новых файлах —
- * история читается с NULL).
+ * union_by_name: partitions of one prefix may differ in schema after
+ * forward-only evolution (new columns appear only in new files — history is
+ * read with NULL).
  */
 export const parquetRef = (lakePath: string, name: ModelName, fingerprint: string): string =>
   `read_parquet('${parquetPrefix(lakePath, name, fingerprint).replaceAll(`'`, `''`)}/**/*.parquet', union_by_name=true)`
 
 /**
- * DuckLake-цель (SPEC §14.5): каталог подключается под фиксированным
- * алиасом, физика — таблица-на-fingerprint в нём (то же имя, что у
- * нативной физики, только каталог другой). Версионность остаётся нашей;
- * снапшоты/time travel DuckLake — бонус. Потребители вне efmesh должны
- * сами сделать ATTACH — view окружений ссылаются на каталог по алиасу.
+ * DuckLake target (SPEC §14.5): the catalog is attached under a fixed alias,
+ * the physical storage is a fingerprint table in it (the same name as native
+ * physical storage, only a different catalog). Versioning stays ours;
+ * DuckLake snapshots/time travel are a bonus. Consumers outside efmesh must
+ * ATTACH it themselves — the environments' views reference the catalog by alias.
  */
 export const ducklakeAlias = "_efmesh_ducklake"
 
@@ -69,7 +69,7 @@ export const ducklakeAttachSql = (config: {
       : ""
   }`
 
-/** Ключ партиции интервала — безопасен для файловых систем (без двоеточий). */
+/** Interval partition key — filesystem-safe (no colons). */
 export const intervalKey = (unit: "day" | "hour", startMs: number): string => {
   const iso = new Date(startMs).toISOString()
   return unit === "day" ? iso.slice(0, 10) : `${iso.slice(0, 10)}T${iso.slice(11, 13)}`
@@ -78,9 +78,9 @@ export const intervalKey = (unit: "day" | "hour", startMs: number): string => {
 const READERS = { parquet: "read_parquet", csv: "read_csv", json: "read_json" } as const
 
 /**
- * Во что рендерится ссылка на external-модель (SPEC §9.3): имя таблицы
- * (движка или ATTACH-базы) как есть, файлы/URL — через read_*.
- * external не материализуется, потребители читают источник напрямую.
+ * What a reference to an external model renders to (SPEC §9.3): the table name
+ * (of the engine or an ATTACH database) as is, files/URLs — via read_*.
+ * external is not materialized, consumers read the source directly.
  */
 export const externalSourceRef = (source: ExternalSource): string =>
   source._tag === "table"

package/src/plan/planner.ts

@@ -15,52 +15,68 @@ import { validateEnvName } from "./naming.ts"
 
 export class InvalidEnvironmentError extends Data.TaggedError("InvalidEnvironmentError")<{
   readonly env: string
-}> {}
+}> {
+  override get message(): string {
+    return `invalid environment name «${this.env}» — use latin letters, digits and _`
+  }
+}
 
-/** Модель нельзя применить forward-only (SPEC §5.2). */
+/** The model cannot be applied forward-only (SPEC §5.2). */
 export class ForwardOnlyError extends Data.TaggedError("ForwardOnlyError")<{
   readonly model: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `model «${this.model}» cannot be applied forward-only: ${this.reason}`
+  }
+}
 
 /**
- * Override категоризации не принимается (#5): модели нет в проекте или
- * AST-дифф очевидно противоречит заявленному вердикту (удалённые колонки
- * не бывают non-breaking — потомки читают их по именам).
+ * A categorization override is rejected (#5): the model is not in the project
+ * or the AST diff obviously contradicts the claimed verdict (removed columns
+ * are never non-breaking — descendants read them by name).
  */
 export class ReclassifyError extends Data.TaggedError("ReclassifyError")<{
   readonly model: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `reclassify «${this.model}»: ${this.reason}`
+  }
+}
 
 /**
- * Снапшот посчитан другой версией алгоритма fingerprint (SPEC §4):
- * отпечатки разных версий несравнимы — план честно останавливается,
- * а не показывает «всё breaking». Лечится миграцией той версии efmesh,
- * которая сменила алгоритм.
+ * The snapshot was computed by a different version of the fingerprint
+ * algorithm (SPEC §4): fingerprints of different versions are incomparable —
+ * the plan honestly stops instead of showing "everything breaking". Cured by
+ * migrating to the version of efmesh that changed the algorithm.
  */
 export class FingerprintVersionError extends Data.TaggedError("FingerprintVersionError")<{
   readonly model: string
   readonly found: number
   readonly wanted: number
-}> {}
+}> {
+  override get message(): string {
+    return `model «${this.model}» was fingerprinted by algorithm v${this.found}, but this efmesh expects v${this.wanted}`
+  }
+}
 
 export type ChangeCategory =
-  /** Модели не было в окружении. */
+  /** The model was not in the environment. */
   | "added"
-  /** Смысловая правка запроса или метаданных: модель и потомки пересобираются. */
+  /** A meaningful edit of the query or metadata: the model and its descendants rebuild. */
   | "breaking"
-  /** Добавлены колонки в конец SELECT, остальное дерево нетронуто (SPEC §5.2). */
+  /** Columns appended to the end of the SELECT, the rest of the tree untouched (SPEC §5.2). */
   | "non-breaking"
-  /** Собственный AST не менялся — версия сдвинулась каскадом от родителя. */
+  /** The own AST did not change — the version shifted by cascade from a parent. */
   | "indirect"
   /**
-   * Физика и done-интервалы старой версии переиспользуются, история не
-   * переигрывается — новая логика действует с момента применения (SPEC §5.2).
-   * Явный флаг пользователя или каскад от forward-only-родителей.
+   * The physics and done-intervals of the old version are reused, history is
+   * not replayed — the new logic takes effect from the moment of application
+   * (SPEC §5.2). An explicit user flag or a cascade from forward-only parents.
    */
   | "forward-only"
-  /** Была в окружении, из проекта исчезла — view будет снесён при промоушене. */
+  /** Was in the environment, vanished from the project — the view is dropped at promotion. */
   | "removed"
   | "unchanged"
 
@@ -68,72 +84,73 @@ export interface PlanAction {
   readonly name: string
   readonly fingerprint: string
   /**
-   * Fingerprint, чьей физикой пользуется снапшот: обычно собственный,
-   * при forward-only — унаследованный от предыдущей версии.
+   * The fingerprint whose physics the snapshot uses: usually its own, and
+   * under forward-only — inherited from the previous version.
    */
   readonly physicalFingerprint: string
-  /** Откуда наследуются физика и done-интервалы (fingerprint старой версии) при forward-only. */
+  /** Where the physics and done-intervals are inherited from (fingerprint of the old version) under forward-only. */
   readonly reusedFrom?: string
-  /** Канонический AST тела (null у external) — сохраняется в снапшот. */
+  /** Canonical AST of the body (null for external) — saved into the snapshot. */
   readonly canonicalAst: string | null
   readonly change: ChangeCategory
-  /** Вердикт планировщика до override оператора (#5); журналируется. */
+  /** The planner's verdict before the operator override (#5); journaled. */
   readonly reclassifiedFrom?: ChangeCategory
   /**
-   * Почему категория такая (#4): разошедшиеся узлы канонического AST и
-   * причина словами. Есть у всех изменённых моделей, кроме added/removed —
-   * там сравнивать не с чем. Пути diverged — отладочная подсказка, не контракт.
+   * Why the category is what it is (#4): the diverged nodes of the canonical
+   * AST and the reason in words. Present on all changed models except
+   * added/removed — there is nothing to compare there. The diverged paths are
+   * a debugging hint, not a contract.
    */
   readonly explain?: ChangeExplanation
   /**
-   * Нужна ли сборка физики. false для unchanged/removed, external и для
-   * снапшотов, уже собранных другим окружением, — тогда промоушен это
-   * только view-swap.
+   * Whether physics needs building. false for unchanged/removed, external and
+   * for snapshots already built by another environment — then promotion is
+   * only a view-swap.
    */
   readonly build: boolean
   /**
-   * Диапазоны к пересчёту у incrementalByTimeRange (слитые из недостающих
-   * интервалов + lookback); у остальных видов пуст. Дыры бывают и у
-   * unchanged-модели — время идёт, появляются новые интервалы.
+   * Ranges to recompute for incrementalByTimeRange (merged from missing
+   * intervals + lookback); empty for other kinds. Gaps happen even for an
+   * unchanged model — time passes, new intervals appear.
    */
   readonly backfill: ReadonlyArray<Interval>
-  /** true у incrementalByUniqueKey: каждый apply перегоняет запрос (upsert по ключу). */
+  /** true for incrementalByUniqueKey: every apply re-runs the query (upsert by key). */
   readonly refresh: boolean
 }
 
 export interface Plan {
   readonly env: string
-  /** В топологическом порядке; removed — в конце. */
+  /** In topological order; removed comes last. */
   readonly actions: ReadonlyArray<PlanAction>
   readonly hasChanges: boolean
 }
 
 export interface PlanOptions {
-  /** «Сейчас» для расчёта интервалов; по умолчанию — Clock. Инъекция для тестов. */
+  /** "Now" for computing intervals; defaults to Clock. Injection point for tests. */
   readonly now?: number
   /**
-   * Модели, чьи изменения применить forward-only (SPEC §5.2): новая версия
-   * наследует физическую таблицу и done-интервалы старой, история не
-   * переигрывается. Только incrementalByTimeRange — у остальных видов
-   * «задним числом» не бывает по построению.
+   * Models whose changes to apply forward-only (SPEC §5.2): the new version
+   * inherits the physical table and done-intervals of the old one, history is
+   * not replayed. Only incrementalByTimeRange — other kinds have no
+   * "retroactive" notion by construction.
    */
   readonly forwardOnly?: ReadonlyArray<string>
   /**
-   * Override категоризации (#5, SPEC §5.2): оператор, глядя на `--explain`,
-   * заявляет вердикт вместо планировщика. Управляет судьбой ПОТОМКОВ
-   * (non-breaking-родитель разрешает им реюз физики); саму модель от
-   * пересборки освобождает не он, а forwardOnly. Гвардрейл: очевидное
-   * противоречие AST (удалённые колонки → non-breaking) — ошибка.
-   * Применяется только к вердиктам breaking/non-breaking; на unchanged/
-   * added/removed/indirect молча не влияет.
+   * Categorization override (#5, SPEC §5.2): the operator, looking at
+   * `--explain`, states the verdict instead of the planner. It governs the
+   * fate of DESCENDANTS (a non-breaking parent lets them reuse the physics);
+   * the model itself is freed from rebuilding not by this but by forwardOnly.
+   * Guardrail: an obvious AST contradiction (removed columns → non-breaking)
+   * is an error. Applies only to breaking/non-breaking verdicts; on unchanged/
+   * added/removed/indirect it silently has no effect.
    */
   readonly reclassify?: Readonly<Record<string, "breaking" | "non-breaking">>
 }
 
 /**
- * Виды, чью физику стоит наследовать при indirect-реюзе (#5): материализуемые
- * таблицы. view/embedded материализации не имеют, seed пересобирается из
- * файла дёшево и родителей не имеет.
+ * Kinds whose physics is worth inheriting on indirect reuse (#5):
+ * materialized tables. view/embedded have no materialization; seed rebuilds
+ * cheaply from a file and has no parents.
  */
 const REUSABLE_KINDS: ReadonlySet<string> = new Set([
   "full",
@@ -166,23 +183,23 @@ export const planChanges = (
     for (const flagged of forwardOnly) {
       const model = graph.models.get(flagged)
       if (model === undefined) {
-        return yield* new ForwardOnlyError({ model: flagged, reason: "модели нет в проекте" })
+        return yield* new ForwardOnlyError({ model: flagged, reason: "model is not in the project" })
       }
       if (model.kind._tag !== "incrementalByTimeRange") {
         return yield* new ForwardOnlyError({
           model: flagged,
-          reason: `forward-only переиспользует физику и учёт интервалов — применим только к incrementalByTimeRange, вид модели — ${model.kind._tag}`,
+          reason: `forward-only reuses physics and interval accounting — applicable only to incrementalByTimeRange, model kind is ${model.kind._tag}`,
         })
       }
     }
     const reclassify = options?.reclassify ?? {}
     for (const flagged of Object.keys(reclassify)) {
       if (!graph.models.has(flagged)) {
-        return yield* new ReclassifyError({ model: flagged, reason: "модели нет в проекте" })
+        return yield* new ReclassifyError({ model: flagged, reason: "model is not in the project" })
       }
     }
-    // кэш канонизации (#8) — стор под рукой; его сбои глотаются:
-    // промах кэша — это просто честный пересчёт, а не ошибка плана
+    // canonicalization cache (#8) — the store is at hand; its failures are
+    // swallowed: a cache miss is just an honest recompute, not a plan error
     const versions = yield* fingerprintGraph(graph, {
       get: (key) => store.getCanon(key).pipe(Effect.orElseSucceed(() => undefined)),
       put: (key, canonical) => store.putCanon(key, canonical).pipe(Effect.ignore),
@@ -193,7 +210,7 @@ export const planChanges = (
 
     const actions: Array<PlanAction> = []
     const changeOf = new Map<string, ChangeCategory>()
-    // кто в этом плане наследует физику старой версии (indirect-реюз, #5)
+    // who in this plan inherits the physics of the old version (indirect reuse, #5)
     const reusedPhysics = new Set<string>()
     for (const name of graph.order) {
       const model = graph.models.get(name)!
@@ -207,8 +224,8 @@ export const planChanges = (
       if (known === undefined) change = "added"
       else if (known === fingerprint) change = "unchanged"
       else {
-        // категоризация по AST против последнего известного снапшота (SPEC §5.2);
-        // старых записей без AST и external — консервативно breaking
+        // categorization by AST against the last known snapshot (SPEC §5.2);
+        // old records without an AST and external — conservatively breaking
         const previous = yield* store.getSnapshot(name, known)
         if (previous !== undefined && previous.fingerprintVersion !== FINGERPRINT_VERSION) {
           return yield* new FingerprintVersionError({
@@ -228,29 +245,29 @@ export const planChanges = (
             diverged: [],
             reason:
               ast === null
-                ? "у модели нет SQL-тела (external/seed) — версию сдвинули источник/файл, схема или родители; сравнивать AST не с чем"
-                : "у прошлого снапшота не сохранён канонический AST — сравнивать не с чем, консервативно breaking",
+                ? "model has no SQL body (external/seed) — the version was shifted by source/file, schema or parents; there is no AST to compare against"
+                : "the previous snapshot did not store a canonical AST — nothing to compare against, conservatively breaking",
           }
         } else if (oldAst === ast) {
-          change = "indirect" // версия сдвинута родителем/метаданными
+          change = "indirect" // version shifted by a parent/metadata
           explain =
             changedParents.length > 0
               ? {
                   diverged: [],
-                  reason: `собственный AST не менялся — версию сдвинул каскад от родителей: ${changedParents.join(", ")}`,
+                  reason: `own AST did not change — the version was shifted by a cascade from parents: ${changedParents.join(", ")}`,
                   cascadeFrom: changedParents,
                 }
               : {
                   diverged: [],
                   reason:
-                    "собственный AST не менялся — разошлись метаданные (kind/grain/columns/target)",
+                    "own AST did not change — metadata diverged (kind/grain/columns/target)",
                 }
         } else {
           change = categorizeAstChange(oldAst, ast)
           explain = explainCategorized(oldAst, ast, change)
         }
-        // override оператора (#5): вердикт заявлен флагом поверх --explain;
-        // планировщик проверяет только очевидное противоречие AST
+        // operator override (#5): the verdict is stated by a flag on top of
+        // --explain; the planner checks only an obvious AST contradiction
         const override = reclassify[name]
         if (
           override !== undefined &&
@@ -261,26 +278,26 @@ export const planChanges = (
             return yield* new ReclassifyError({
               model: name,
               reason:
-                "канонического AST нет — проверить вердикт нечем, override не принимается",
+                "no canonical AST — nothing to check the verdict against, override is not accepted",
             })
           }
           if (override === "non-breaking" && ast !== null && dropsColumns(oldAst, ast)) {
             return yield* new ReclassifyError({
               model: name,
               reason:
-                "в новом SELECT колонок меньше — потомки читают удалённые колонки по именам, non-breaking противоречит AST",
+                "the new SELECT has fewer columns — descendants read the removed columns by name, non-breaking contradicts the AST",
             })
           }
           reclassifiedFrom = change
           explain = {
             diverged: explain?.diverged ?? [],
-            reason: `override оператора: ${change} → ${override}; вердикт планировщика: ${explain?.reason ?? "—"}`,
+            reason: `operator override: ${change} → ${override}; planner verdict: ${explain?.reason ?? "—"}`,
           }
           change = override
         }
-        // «версию сдвинули ТОЛЬКО родители»: отпечаток со старыми подписями
-        // родителей обязан дать known — иначе вместе с родителями разошлись
-        // и метаданные (kind/grain/columns/target), наследовать физику нельзя
+        // "version shifted by parents ONLY": a fingerprint with the old parent
+        // signatures must yield known — otherwise the metadata diverged along
+        // with the parents (kind/grain/columns/target) and physics cannot be inherited
         const parentsOnly =
           change === "indirect" &&
           previous !== undefined &&
@@ -290,9 +307,9 @@ export const planChanges = (
             ast,
             [...model.deps].sort().map((dep) => `${dep}=${current.get(dep)!}`),
           )) === known
-        // forward-only: явный флаг пользователя — либо каскад: собственный AST
-        // не менялся, а все изменившиеся родители сами forward-only (реюз
-        // физики родителя означает, что и потомку нечего переигрывать)
+        // forward-only: an explicit user flag — or a cascade: the own AST did
+        // not change and all changed parents are themselves forward-only (reuse
+        // of a parent's physics means the descendant has nothing to replay either)
         const cascaded =
           parentsOnly &&
           model.kind._tag === "incrementalByTimeRange" &&
@@ -307,21 +324,21 @@ export const planChanges = (
           explain = forwardOnly.has(name)
             ? {
                 diverged: explain?.diverged ?? [],
-                reason: `forward-only по флагу: физика и done-интервалы наследуются от @${known.slice(0, 8)}, история не переигрывается`,
+                reason: `forward-only by flag: physics and done intervals are inherited from @${known.slice(0, 8)}, history is not replayed`,
               }
             : {
                 diverged: [],
                 reason:
-                  "собственный AST не менялся, все изменившиеся родители forward-only — физика реюзается каскадом",
+                  "own AST did not change, all changed parents are forward-only — physics is reused by cascade",
                 cascadeFrom: changedParents,
               }
         }
-        // indirect-реюз (#5, класс sqlmesh «indirect non-breaking»): своё тело
-        // не менялось, версию сдвинули только родители, и каждый изменившийся
-        // родитель гарантирует те же данные в старых колонках (non-breaking —
-        // строго суффикс; forward-only и реюз — буквально та же физика) —
-        // потомку нечего переигрывать: физика и учёт наследуются, scdType2
-        // не теряет накопленную историю строк
+        // indirect reuse (#5, sqlmesh's "indirect non-breaking" class): the own
+        // body did not change, the version was shifted only by parents, and each
+        // changed parent guarantees the same data in the old columns (non-breaking
+        // — strictly a suffix; forward-only and reuse — literally the same
+        // physics) — the descendant has nothing to replay: physics and ledger are
+        // inherited, scdType2 does not lose its accumulated row history
         if (
           change === "indirect" &&
           parentsOnly &&
@@ -341,13 +358,13 @@ export const planChanges = (
           reusedPhysics.add(name)
           explain = {
             diverged: [],
-            reason: `изменившиеся родители не трогают существующие данные (non-breaking/forward-only) — физика и учёт наследуются от @${known.slice(0, 8)}, пересборки нет`,
+            reason: `changed parents do not touch existing data (non-breaking/forward-only) — physics and accounting are inherited from @${known.slice(0, 8)}, no rebuild`,
             cascadeFrom: changedParents,
           }
         }
       }
       changeOf.set(name, change)
-      // external не материализуется — версия участвует в diff, физики нет
+      // external is not materialized — the version participates in the diff, there is no physics
       const existing = yield* store.getSnapshot(name, fingerprint)
       if (existing !== undefined) physicalFingerprint = existing.physicalFp
       const alreadyBuilt =
@@ -357,9 +374,9 @@ export const planChanges = (
       if (model.kind._tag === "incrementalByTimeRange") {
         const kind = model.kind
         const wanted = enumerateIntervals(kind.interval, fromIso(kind.start), now)
-        // покрытие привязано к fingerprint: новая версия = пустой учёт = полный
-        // бэкфилл; forward-only наследует done-интервалы старой версии —
-        // пересчитывается только то, чего не было
+        // coverage is keyed to the fingerprint: a new version = empty ledger =
+        // full backfill; forward-only inherits the done-intervals of the old
+        // version — only what was missing is recomputed
         const inherited =
           reusedFrom === undefined ? [] : yield* store.listIntervals(reusedFrom)
         const doneByStart = new Map<number, Interval>()
@@ -373,7 +390,7 @@ export const planChanges = (
         const done = [...doneByStart.values()]
         const missing = [...missingIntervals(wanted, done)]
         if (kind.lookback > 0) {
-          // поздно приезжающие данные: последние done-интервалы перечитываются
+          // late-arriving data: the last done-intervals are re-read
           const tail = done.sort((a, b) => a.start - b.start).slice(-kind.lookback)
           missing.push(...tail)
         }
@@ -391,7 +408,7 @@ export const planChanges = (
         ...(explain !== undefined ? { explain } : {}),
         build: !alreadyBuilt,
         backfill,
-        // каждый apply сверяет запрос с физикой: upsert / SCD-версионирование
+        // every apply reconciles the query with the physics: upsert / SCD versioning
         refresh:
           model.kind._tag === "incrementalByUniqueKey" || model.kind._tag === "scdType2",
       })

package/src/plan/run.ts

@@ -8,24 +8,28 @@ import { envLockName, withStateLock, type LockHeldError, type LockOptions } from
 import { planChanges, type PlanOptions } from "./planner.ts"
 
 /**
- * `run` — тик планировщика (SPEC §7): догоняет интервалы и upsert'ы
- * СУЩЕСТВУЮЩИХ версий, никогда не применяет изменения моделей — это
- * работа plan/apply с человеком у руля. Идемпотентен и безопасен для
- * cron/systemd: параллельный запуск отсекается блокировкой в state store —
- * той же `env:<имя>`, что у apply (SPEC §14.6), поэтому run не вклинится
- * в чужое применение и наоборот.
+ * `run` — a scheduler tick (SPEC §7): catches up intervals and upserts of
+ * EXISTING versions, never applies model changes — that is the job of
+ * plan/apply with a human at the helm. Idempotent and safe for cron/systemd:
+ * a parallel run is cut off by a lock in the state store — the same
+ * `env:<name>` as apply's (SPEC §14.6), so run will not wedge into someone
+ * else's apply and vice versa.
  */
 
 export class RunBlockedByChangesError extends Data.TaggedError("RunBlockedByChangesError")<{
   readonly env: string
   readonly changes: ReadonlyArray<string>
-}> {}
+}> {
+  override get message(): string {
+    return `environment «${this.env}» has unapplied structural changes: ${this.changes.join(", ")} — run \`efmesh apply ${this.env}\``
+  }
+}
 
 export type RunError = ApplyError | LockHeldError | RunBlockedByChangesError
 
 export interface RunOptions extends PlanOptions, ApplyOptions, LockOptions {}
 
-/** Исход тика для журнала: ошибка → категория + деталь. */
+/** Tick outcome for the journal: error → category + detail. */
 const classify = (error: RunError): Pick<RunRecord, "outcome" | "detail"> => {
   switch (error._tag) {
     case "RunBlockedByChangesError":
@@ -45,9 +49,10 @@ export const run = (
   Effect.gen(function* () {
     const store = yield* StateStore
     const startedAt = new Date(yield* Clock.currentTimeMillis).toISOString()
-    // журнал тиков (SPEC §7, #2): исход пишется ВСЕГДА, включая неуспех —
-    // упавший в три часа ночи cron-тик дебажится задним числом; сбой самой
-    // записи не маскирует настоящий исход (лог + ignore)
+    // tick journal (SPEC §7, #2): the outcome is written ALWAYS, including
+    // failure — a cron tick that fell over at three in the morning is debugged
+    // after the fact; a failure of the write itself does not mask the real
+    // outcome (log + ignore)
     const journal = (entry: Pick<RunRecord, "outcome" | "detail">) =>
       Clock.currentTimeMillis.pipe(
         Effect.flatMap((now) =>
@@ -58,7 +63,7 @@ export const run = (
             ...entry,
           }),
         ),
-        Effect.catchCause((cause) => Effect.logWarning("журнал тиков недоступен", cause)),
+        Effect.catchCause((cause) => Effect.logWarning("tick journal is unavailable", cause)),
       )
 
     return yield* Effect.gen(function* () {
@@ -81,9 +86,9 @@ export const run = (
   })
 
 /**
- * Долгоживущий планировщик для встраивания в Effect-приложение (SPEC §7):
- * тики по Schedule, ошибка тика логируется и не роняет демона
- * (кроме занятого лока — это штатно, лог потише).
+ * Long-lived scheduler for embedding in an Effect application (SPEC §7):
+ * ticks on a Schedule; a tick error is logged and does not bring the daemon
+ * down (except a held lock — that is routine, logged more quietly).
  */
 export const daemon = (
   env: string,
@@ -94,13 +99,16 @@ export const daemon = (
   run(env, models, options).pipe(
     Effect.tap((applied) =>
       applied.built.length > 0
-        ? Effect.logInfo(`run ${env}: обработано ${applied.built.join(", ")}`)
-        : Effect.void,
+        ? Effect.logInfo(`tick built ${applied.built.join(", ")}`)
+        : Effect.logInfo("tick: no new intervals"),
     ),
+    // a held lock is routine (another process ticks) — debug, not an alarm
     Effect.catchTag("LockHeldError", () =>
-      Effect.logDebug(`run ${env}: лок занят другим процессом, пропуск тика`),
+      Effect.logDebug("tick skipped: lock held by another process"),
     ),
-    Effect.catchCause((cause) => Effect.logError(`run ${env}: тик упал`, cause)),
+    Effect.catchCause((cause) => Effect.logError("tick failed", cause)),
+    // env is a structured field, not baked into every message (#14)
+    Effect.annotateLogs("env", env),
     Effect.schedule(schedule),
     Effect.andThen(Effect.never),
   )