@avytheone/efmesh 0.2.0 → 0.2.1

package/src/plan/schedule.ts

@@ -4,49 +4,53 @@ import { fileURLToPath } from "node:url"
 import { Data, Effect } from "effect"
 
 /**
- * `efmesh schedule` (#10): регистрация тика `run` в OS-шедулере через
- * Bun.cron (>=1.3.11): crontab на Linux, launchd на macOS, Task Scheduler
- * на Windows. Один заголовок = одна запись, повторная регистрация
- * перезаписывает на месте (идемпотентно).
+ * `efmesh schedule` (#10): registers a `run` tick in the OS scheduler via
+ * Bun.cron (>=1.3.11): crontab on Linux, launchd on macOS, Task Scheduler
+ * on Windows. One title = one entry; re-registration overwrites in place
+ * (idempotent).
  *
- * Честные оговорки (документированы в README/SPEC): cron не догоняет
- * пропущенные запуски (systemd Persistent=true строже — есть
- * --print-systemd), OS-уровень живёт в ЛОКАЛЬНОЙ таймзоне (TZ=UTC поверх),
- * на Linux нужен живой cron-демон — семейство Arch без cronie не имеет
- * его вовсе. Наложение тиков безопасно по построению: run держит env-лок,
- * а «ждёт человека» = exit 2, не сбой.
+ * Honest caveats (documented in README/SPEC): cron does not catch up on
+ * missed runs (systemd Persistent=true is stricter — hence --print-systemd),
+ * the OS level lives in the LOCAL timezone (TZ=UTC on top), on Linux a live
+ * cron daemon is required — the Arch family without cronie has none at all.
+ * Overlapping ticks are safe by construction: run holds the env lock, and
+ * "awaiting a human" = exit 2, not a failure.
  */
 
 export class ScheduleError extends Data.TaggedError("ScheduleError")<{
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return this.reason
+  }
+}
 
-/** Всё, что нужно воркеру, — абсолютными путями (crontab не знает cwd). */
+/** Everything the worker needs, as absolute paths (crontab has no cwd). */
 export interface ScheduleTarget {
-  /** Директория проекта (где лежит конфиг) — cwd тика. */
+  /** Project directory (where the config lives) — the tick's cwd. */
   readonly project: string
-  /** Абсолютный путь конфига. */
+  /** Absolute path of the config. */
   readonly config: string
   readonly env: string
 }
 
-/** Заголовок Bun.cron: только [A-Za-z0-9_-]; включает проект и окружение. */
+/** Bun.cron title: only [A-Za-z0-9_-]; includes the project and environment. */
 export const scheduleTitle = (target: Pick<ScheduleTarget, "project" | "env">): string =>
   `efmesh-${basename(target.project)}-${target.env}`.replaceAll(/[^A-Za-z0-9_-]/g, "-")
 
-/** Куда генерируется воркер: рядом с конфигом, в служебной .efmesh/. */
+/** Where the worker is generated: next to the config, in the internal .efmesh/. */
 export const workerPath = (target: ScheduleTarget): string =>
   join(target.project, ".efmesh", `schedule-${target.env}.ts`)
 
-/** Бинарь CLI этого же пакета — воркер зовёт его, не гадая по npm-именам. */
+/** CLI binary of this same package — the worker calls it without guessing npm names. */
 const binPath = (): string => fileURLToPath(new URL("../bin.ts", import.meta.url))
 
 /**
- * Исходник воркера для Bun.cron: OS-шедулер исполняет scheduled(), тот
- * гоняет обычный `efmesh run` — та же семантика exit-кодов (2 = «ждёт
- * человека») и тот же журнал тиков в сторе (`efmesh status`).
+ * Worker source for Bun.cron: the OS scheduler runs scheduled(), which runs
+ * an ordinary `efmesh run` — the same exit-code semantics (2 = "awaiting a
+ * human") and the same tick journal in the store (`efmesh status`).
  */
-export const workerSource = (target: ScheduleTarget): string => `// сгенерировано \`efmesh schedule\` — не редактируйте: перерегистрация перезапишет
+export const workerSource = (target: ScheduleTarget): string => `// generated by \`efmesh schedule\` — do not edit: re-registration overwrites it
 export default {
   async scheduled() {
     const proc = Bun.spawn(
@@ -58,7 +62,7 @@ export default {
 }
 `
 
-/** Никнеймы cron → OnCalendar systemd; произвольные выражения не переводятся. */
+/** cron nicknames → systemd OnCalendar; arbitrary expressions are not translated. */
 export const cronToOnCalendar = (cron: string): string | undefined =>
   (
     {
@@ -73,8 +77,9 @@ export const cronToOnCalendar = (cron: string): string | undefined =>
   )[cron.trim()]
 
 /**
- * systemd-фоллбэк (--print-systemd): у cron нет догона пропущенных запусков
- * и на Arch-семействе нет демона — user-таймер с Persistent=true честнее.
+ * systemd fallback (--print-systemd): cron has no catch-up for missed runs
+ * and the Arch family has no daemon — a user timer with Persistent=true is
+ * more honest.
  */
 export const systemdUnits = (
   target: ScheduleTarget,
@@ -91,13 +96,13 @@ Description=efmesh run ${target.env} (${basename(target.project)})
 Type=oneshot
 WorkingDirectory=${target.project}
 ExecStart=${process.execPath} ${binPath()} run ${target.env} --config ${target.config}
-# exit 2 = «ждёт человека» (нужен apply) — намеренно failure юнита: видно в алертах
+# exit 2 = "awaiting a human" (apply needed) — deliberately a unit failure: visible in alerts
 `,
     timer: `[Unit]
-Description=efmesh run ${target.env} — таймер
+Description=efmesh run ${target.env} — timer
 
 [Timer]
-OnCalendar=${calendar ?? `hourly  # TODO: переведите «${cron}» в OnCalendar вручную`}
+OnCalendar=${calendar ?? `hourly  # TODO: translate "${cron}" into OnCalendar by hand`}
 Persistent=true
 
 [Install]
@@ -106,28 +111,28 @@ WantedBy=timers.target
   }
 }
 
-/** Валидация выражения тем же парсером, который будет его исполнять. */
+/** Validate the expression with the same parser that will execute it. */
 export const validateCron = (cron: string): Effect.Effect<void, ScheduleError> =>
   Effect.gen(function* () {
     const next = yield* Effect.try({
       try: () => Bun.cron.parse(cron),
-      catch: () => new ScheduleError({ reason: `не разбирается cron-выражение «${cron}»` }),
+      catch: () => new ScheduleError({ reason: `cannot parse cron expression "${cron}"` }),
     })
     if (next === null) {
       return yield* new ScheduleError({
-        reason: `cron-выражение «${cron}» никогда не сработает`,
+        reason: `cron expression "${cron}" will never fire`,
       })
     }
   })
 
-/** Linux без crontab-бинаря (Arch-семейство) — честная ошибка с рецептом. */
+/** Linux without a crontab binary (Arch family) — an honest error with a recipe. */
 const requireCrontab = (): Effect.Effect<void, ScheduleError> =>
   Effect.gen(function* () {
     if (process.platform !== "linux" || Bun.which("crontab") !== null) return
     return yield* new ScheduleError({
       reason:
-        "на этой машине нет crontab (Arch-семейство не ставит cron-демона): " +
-        "установите cronie ЛИБО используйте systemd-таймер — efmesh schedule <env> --print-systemd",
+        "this machine has no crontab (the Arch family ships no cron daemon): " +
+        "install cronie OR use a systemd timer — efmesh schedule <env> --print-systemd",
     })
   })
 
@@ -139,7 +144,7 @@ export const registerSchedule = (
     yield* validateCron(cron)
     yield* requireCrontab()
     if (!existsSync(target.config)) {
-      return yield* new ScheduleError({ reason: `конфига нет: ${target.config}` })
+      return yield* new ScheduleError({ reason: `config not found: ${target.config}` })
     }
     const worker = workerPath(target)
     yield* Effect.try({
@@ -148,13 +153,13 @@ export const registerSchedule = (
         writeFileSync(worker, workerSource(target))
       },
       catch: (cause) =>
-        new ScheduleError({ reason: `воркер не записался: ${String(cause)}` }),
+        new ScheduleError({ reason: `worker was not written: ${String(cause)}` }),
     })
     const title = scheduleTitle(target)
     yield* Effect.tryPromise({
       try: () => Bun.cron(worker, cron, title),
       catch: (cause) =>
-        new ScheduleError({ reason: `Bun.cron не зарегистрировал: ${String(cause)}` }),
+        new ScheduleError({ reason: `Bun.cron did not register: ${String(cause)}` }),
     })
     return { title, worker }
   })
@@ -168,14 +173,14 @@ export const removeSchedule = (
       try: () => Bun.cron.remove(title),
       catch: (cause) => new ScheduleError({ reason: `Bun.cron.remove: ${String(cause)}` }),
     })
-    // воркер больше никем не исполняется — прибираем молча
+    // the worker is no longer executed by anyone — clean it up silently
     yield* Effect.sync(() => rmSync(workerPath(target), { force: true }))
     return { title }
   })
 
 /**
- * Список efmesh-регистраций — по платформенным следам Bun.cron: маркеры
- * `# bun-cron: <title>` в crontab (Linux) / plist'ы launchd (macOS).
+ * List of efmesh registrations — by Bun.cron's platform traces: `# bun-cron:
+ * <title>` markers in crontab (Linux) / launchd plists (macOS).
  */
 export const listSchedules = (): Effect.Effect<ReadonlyArray<string>, ScheduleError> =>
   Effect.gen(function* () {
@@ -185,7 +190,7 @@ export const listSchedules = (): Effect.Effect<ReadonlyArray<string>, ScheduleEr
         try: async () => {
           const proc = Bun.spawn(["crontab", "-l"], { stdout: "pipe", stderr: "ignore" })
           const text = await proc.stdout.text()
-          await proc.exited // пустой crontab выходит с 1 — это не ошибка
+          await proc.exited // an empty crontab exits with 1 — that is not an error
           return text
         },
         catch: (cause) => new ScheduleError({ reason: `crontab -l: ${String(cause)}` }),
@@ -207,6 +212,6 @@ export const listSchedules = (): Effect.Effect<ReadonlyArray<string>, ScheduleEr
       return out.split("\n").filter((line) => line.includes("bun.cron.efmesh-"))
     }
     return yield* new ScheduleError({
-      reason: `список на ${process.platform} смотрите средствами ОС (Task Scheduler: schtasks /query)`,
+      reason: `list on ${process.platform} via the OS tools (Task Scheduler: schtasks /query)`,
     })
   })

package/src/plan/status.ts

@@ -6,39 +6,40 @@ import { STATE_VERSION, StateStore } from "../state/store.ts"
 import type { PlanRecord, RunRecord, StateError } from "../state/store.ts"
 
 /**
- * `efmesh status <env>` (issue #1): одна команда на вопрос «что вообще
- * происходит» — для оператора ночного cron и для автора, забывшего
- * команды. Только чтение: стор открыт → версия схемы уже совпала.
+ * `efmesh status <env>` (issue #1): one command for the question «what is
+ * even going on» — for the nightly-cron operator and for the author who
+ * forgot the commands. Read-only: if the store opened → its schema version
+ * already matched.
  */
 
 export interface ModelLag {
   readonly model: string
-  /** Конец последнего done-интервала (ISO); null — ещё ничего не посчитано. */
+  /** End of the last done interval (ISO); null — nothing computed yet. */
   readonly doneUpTo: string | null
-  /** Сколько интервалов не хватает до «сейчас». 0 — догнано. */
+  /** How many intervals are missing up to «now». 0 — caught up. */
   readonly missing: number
-  /** Интервалы, помеченные failed, — застрявший бэкфилл виден сразу. */
+  /** Intervals marked failed — a stuck backfill is visible at once. */
   readonly failed: number
 }
 
 export interface StatusReport {
   readonly env: string
   readonly storeVersion: number
-  /** Строк в окружении; 0 — окружение не существует (ни разу не применялось). */
+  /** Rows in the environment; 0 — the environment does not exist (never applied). */
   readonly models: number
-  /** Последний промоушен (ISO); null — окружения нет. */
+  /** Last promotion (ISO); null — no environment. */
   readonly promotedAt: string | null
   readonly lastPlan: PlanRecord | null
-  /** Последние тики run, свежие первыми. */
+  /** Latest run ticks, freshest first. */
   readonly ticks: ReadonlyArray<RunRecord>
-  /** Отставание incremental-моделей окружения. */
+  /** Lag of the environment's incremental models. */
   readonly lag: ReadonlyArray<ModelLag>
 }
 
 export interface StatusOptions {
-  /** «Сейчас» для расчёта отставания; по умолчанию — Clock. Инъекция для тестов. */
+  /** «Now» for computing lag; by default — Clock. Injected for tests. */
   readonly now?: number
-  /** Сколько последних тиков показать; по умолчанию 5. */
+  /** How many latest ticks to show; by default 5. */
   readonly ticks?: number
 }
 
@@ -62,8 +63,8 @@ export const environmentStatus = (
     const lastPlan = plans.at(-1) ?? null
     const ticks = yield* store.listRuns(env, options?.ticks ?? 5)
 
-    // отставание — по УКАЗАТЕЛЯМ окружения (что реально отдаётся
-    // потребителям), а не по локальным fingerprint'ам проекта
+    // lag — by the environment's POINTERS (what is actually served to
+    // consumers), not by the project's local fingerprints
     const lag: Array<ModelLag> = []
     for (const row of rows) {
       const model = graph.models.get(row.name)

package/src/state/postgres.ts

@@ -12,11 +12,11 @@ import type {
 import { STATE_VERSION, StateError, StateSchemaError, StateStore } from "./store.ts"
 
 /**
- * State store в Postgres (SPEC §6, F3) — для командной/прод-работы:
- * состояние переживает конкурентные запуски из разных процессов и машин.
- * Схема `efmesh_state`, семантика один в один с bun:sqlite-реализацией;
- * временные метки — ISO UTC текстом (лексикографически сортируемы),
- * как и в SQLite: содержимое стора переносимо между бэкендами.
+ * State store on Postgres (SPEC §6, F3) — for team/production work: state
+ * survives concurrent runs from different processes and machines.
+ * Schema `efmesh_state`, semantics identical to the bun:sqlite implementation;
+ * timestamps are ISO UTC text (lexicographically sortable), same as in
+ * SQLite: the store's contents are portable between backends.
  */
 
 const SCHEMA = `
@@ -75,9 +75,9 @@ CREATE TABLE IF NOT EXISTS efmesh_state.locks (
 `
 
 export interface PostgresStateOptions {
-  /** postgres://… или unix-сокет через ?host=/путь. */
+  /** postgres://… or a unix socket via ?host=/path. */
   readonly url: string
-  /** Размер пула; состоянию хватает пары соединений. */
+  /** Pool size; a couple of connections are enough for state. */
   readonly max?: number
 }
 
@@ -88,7 +88,7 @@ const regclass = async (pool: SQL, table: string): Promise<boolean> => {
   return rows[0]?.r != null
 }
 
-/** 0 — стор без таблицы meta (создан до появления версионирования, F0–F3). */
+/** 0 — a store with no meta table (created before versioning existed, F0–F3). */
 const readVersion = async (pool: SQL): Promise<number> => {
   if (!(await regclass(pool, "meta"))) return 0
   const rows = (await pool.unsafe(
@@ -97,7 +97,7 @@ const readVersion = async (pool: SQL): Promise<number> => {
   return rows[0]?.version ?? 0
 }
 
-/** Догоняет схему до STATE_VERSION (см. sqlite-реализацию — семантика та же). */
+/** Catches the schema up to STATE_VERSION (see the sqlite implementation — same semantics). */
 const applyMigrations = async (pool: SQL): Promise<void> => {
   await pool.unsafe(SCHEMA)
   await pool.unsafe(`
@@ -114,7 +114,7 @@ const applyMigrations = async (pool: SQL): Promise<void> => {
   })
 }
 
-/** `efmesh migrate`: явное обновление схемы существующего стора. */
+/** `efmesh migrate`: an explicit schema upgrade of an existing store. */
 export const migratePostgresState = (
   options: PostgresStateOptions,
 ): Effect.Effect<MigrationReport, StateError> =>
@@ -153,8 +153,8 @@ export const PostgresStateLive = (
         }),
         (pool) => Effect.promise(() => pool.end()).pipe(Effect.ignore),
       )
-      // свежий стор бутстрапится на текущую версию; существующий со схемой
-      // старше требует явного `efmesh migrate` (SPEC §6)
+      // a fresh store bootstraps at the current version; an existing store
+      // with an older schema requires an explicit `efmesh migrate` (SPEC §6)
       const fresh = yield* Effect.tryPromise({
         try: async () => !(await regclass(sql, "snapshots")),
         catch: (cause) => new StateError({ operation: "open", cause }),
@@ -190,7 +190,7 @@ export const PostgresStateLive = (
             Effect.flatMap((now) =>
               attempt("upsertSnapshot", async () => {
                 await sql.unsafe(
-                  // воскрешение снимает сиротство и освежает created_at — как в sqlite (гонка F6)
+                  // reviving clears orphan status and refreshes created_at — same as sqlite (race, F6)
                   `INSERT INTO efmesh_state.snapshots
                      (name, fingerprint, rendered_sql, canonical_ast, physical_fp, kind, fingerprint_version, created_at)
                    VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
@@ -284,8 +284,8 @@ export const PostgresStateLive = (
             Effect.flatMap((now) =>
               attempt("promote", () =>
                 sql.begin(async (tx) => {
-                  // живость снапшотов — в той же транзакции (гонка F6):
-                  // janitor унёс версию → громкая ошибка, view не трогается
+                  // snapshot liveness — in the same transaction (race, F6):
+                  // janitor removed the version → loud error, the view is left alone
                   for (const entry of entries) {
                     if (entry.requireSnapshot !== true) continue
                     const alive = (await tx.unsafe(
@@ -294,7 +294,7 @@ export const PostgresStateLive = (
                     )) as ReadonlyArray<unknown>
                     if (alive.length === 0) {
                       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`,
                       )
                     }
                   }
@@ -306,7 +306,7 @@ export const PostgresStateLive = (
                       [env, entry.name, entry.fingerprint, now],
                     )
                   }
-                  // учёт сиротства — как в sqlite-реализации (SPEC §5.4)
+                  // orphan bookkeeping — same as the sqlite implementation (SPEC §5.4)
                   await tx.unsafe(
                     `UPDATE efmesh_state.snapshots SET orphaned_at = $1
                      WHERE orphaned_at IS NULL
@@ -387,8 +387,8 @@ export const PostgresStateLive = (
                 sql.begin(async (tx) => {
                   const now = new Date(nowMs).toISOString()
                   const expires = new Date(nowMs + ttlMs).toISOString()
-                  // протухший лок упавшего процесса перехватывается;
-                  // <= — лок, истёкший в момент T, свободен с T
+                  // a stale lock from a crashed process is reclaimed;
+                  // <= — a lock that expires at instant T is free as of T
                   await tx.unsafe(
                     `DELETE FROM efmesh_state.locks WHERE name = $1 AND expires_at <= $2`,
                     [name, now],

package/src/state/sqlite.ts

@@ -67,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
 }
 
@@ -78,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
@@ -86,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)
@@ -104,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)`)
@@ -113,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,
@@ -157,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 }),
@@ -187,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)
@@ -294,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`,
                       )
                     }
                   }
@@ -315,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
@@ -396,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(