@avytheone/efmesh 0.1.0-beta.2 → 0.2.0

package/src/plan/planner.ts

@@ -8,7 +8,9 @@ import { EngineAdapter } from "../engine/adapter.ts"
 import { StateStore } from "../state/store.ts"
 import type { StateError } from "../state/store.ts"
 import { categorizeAstChange } from "./categorize.ts"
-import { FINGERPRINT_VERSION, fingerprintGraph } from "./fingerprint.ts"
+import type { ChangeExplanation } from "./explain.ts"
+import { dropsColumns, explainCategorized } from "./explain.ts"
+import { FINGERPRINT_VERSION, fingerprintGraph, modelFingerprint } from "./fingerprint.ts"
 import { validateEnvName } from "./naming.ts"
 
 export class InvalidEnvironmentError extends Data.TaggedError("InvalidEnvironmentError")<{
@@ -21,6 +23,16 @@ export class ForwardOnlyError extends Data.TaggedError("ForwardOnlyError")<{
   readonly reason: string
 }> {}
 
+/**
+ * Override категоризации не принимается (#5): модели нет в проекте или
+ * AST-дифф очевидно противоречит заявленному вердикту (удалённые колонки
+ * не бывают non-breaking — потомки читают их по именам).
+ */
+export class ReclassifyError extends Data.TaggedError("ReclassifyError")<{
+  readonly model: string
+  readonly reason: string
+}> {}
+
 /**
  * Снапшот посчитан другой версией алгоритма fingerprint (SPEC §4):
  * отпечатки разных версий несравнимы — план честно останавливается,
@@ -65,6 +77,14 @@ export interface PlanAction {
   /** Канонический AST тела (null у external) — сохраняется в снапшот. */
   readonly canonicalAst: string | null
   readonly change: ChangeCategory
+  /** Вердикт планировщика до override оператора (#5); журналируется. */
+  readonly reclassifiedFrom?: ChangeCategory
+  /**
+   * Почему категория такая (#4): разошедшиеся узлы канонического AST и
+   * причина словами. Есть у всех изменённых моделей, кроме added/removed —
+   * там сравнивать не с чем. Пути diverged — отладочная подсказка, не контракт.
+   */
+  readonly explain?: ChangeExplanation
   /**
    * Нужна ли сборка физики. false для unchanged/removed, external и для
    * снапшотов, уже собранных другим окружением, — тогда промоушен это
@@ -98,8 +118,30 @@ export interface PlanOptions {
    * «задним числом» не бывает по построению.
    */
   readonly forwardOnly?: ReadonlyArray<string>
+  /**
+   * Override категоризации (#5, SPEC §5.2): оператор, глядя на `--explain`,
+   * заявляет вердикт вместо планировщика. Управляет судьбой ПОТОМКОВ
+   * (non-breaking-родитель разрешает им реюз физики); саму модель от
+   * пересборки освобождает не он, а forwardOnly. Гвардрейл: очевидное
+   * противоречие AST (удалённые колонки → non-breaking) — ошибка.
+   * Применяется только к вердиктам breaking/non-breaking; на unchanged/
+   * added/removed/indirect молча не влияет.
+   */
+  readonly reclassify?: Readonly<Record<string, "breaking" | "non-breaking">>
 }
 
+/**
+ * Виды, чью физику стоит наследовать при indirect-реюзе (#5): материализуемые
+ * таблицы. view/embedded материализации не имеют, seed пересобирается из
+ * файла дёшево и родителей не имеет.
+ */
+const REUSABLE_KINDS: ReadonlySet<string> = new Set([
+  "full",
+  "incrementalByTimeRange",
+  "incrementalByUniqueKey",
+  "scdType2",
+])
+
 export const planChanges = (
   env: string,
   graph: ModelGraph,
@@ -108,6 +150,7 @@ export const planChanges = (
   Plan,
   | InvalidEnvironmentError
   | ForwardOnlyError
+  | ReclassifyError
   | FingerprintVersionError
   | StateError
   | EngineError
@@ -132,18 +175,33 @@ export const planChanges = (
         })
       }
     }
-    const versions = yield* fingerprintGraph(graph)
+    const reclassify = options?.reclassify ?? {}
+    for (const flagged of Object.keys(reclassify)) {
+      if (!graph.models.has(flagged)) {
+        return yield* new ReclassifyError({ model: flagged, reason: "модели нет в проекте" })
+      }
+    }
+    // кэш канонизации (#8) — стор под рукой; его сбои глотаются:
+    // промах кэша — это просто честный пересчёт, а не ошибка плана
+    const versions = yield* fingerprintGraph(graph, {
+      get: (key) => store.getCanon(key).pipe(Effect.orElseSucceed(() => undefined)),
+      put: (key, canonical) => store.putCanon(key, canonical).pipe(Effect.ignore),
+    })
     const current = new Map(
       (yield* store.getEnvironment(env)).map((row) => [row.name, row.fingerprint]),
     )
 
     const actions: Array<PlanAction> = []
     const changeOf = new Map<string, ChangeCategory>()
+    // кто в этом плане наследует физику старой версии (indirect-реюз, #5)
+    const reusedPhysics = new Set<string>()
     for (const name of graph.order) {
       const model = graph.models.get(name)!
       const { fingerprint, ast } = versions.get(name)!
       const known = current.get(name)
       let change: ChangeCategory
+      let explain: ChangeExplanation | undefined
+      let reclassifiedFrom: ChangeCategory | undefined
       let reusedFrom: string | undefined
       let physicalFingerprint = fingerprint
       if (known === undefined) change = "added"
@@ -160,14 +218,83 @@ export const planChanges = (
           })
         }
         const oldAst = previous?.canonicalAst ?? ""
-        if (oldAst === "" || ast === null) change = "breaking"
-        else if (oldAst === ast) change = "indirect" // версия сдвинута родителем/метаданными
-        else change = categorizeAstChange(oldAst, ast)
+        const changedParents = [...model.deps].filter((dep) => {
+          const parent = changeOf.get(dep)
+          return parent !== undefined && parent !== "unchanged"
+        })
+        if (oldAst === "" || ast === null) {
+          change = "breaking"
+          explain = {
+            diverged: [],
+            reason:
+              ast === null
+                ? "у модели нет SQL-тела (external/seed) — версию сдвинули источник/файл, схема или родители; сравнивать AST не с чем"
+                : "у прошлого снапшота не сохранён канонический AST — сравнивать не с чем, консервативно breaking",
+          }
+        } else if (oldAst === ast) {
+          change = "indirect" // версия сдвинута родителем/метаданными
+          explain =
+            changedParents.length > 0
+              ? {
+                  diverged: [],
+                  reason: `собственный AST не менялся — версию сдвинул каскад от родителей: ${changedParents.join(", ")}`,
+                  cascadeFrom: changedParents,
+                }
+              : {
+                  diverged: [],
+                  reason:
+                    "собственный AST не менялся — разошлись метаданные (kind/grain/columns/target)",
+                }
+        } else {
+          change = categorizeAstChange(oldAst, ast)
+          explain = explainCategorized(oldAst, ast, change)
+        }
+        // override оператора (#5): вердикт заявлен флагом поверх --explain;
+        // планировщик проверяет только очевидное противоречие AST
+        const override = reclassify[name]
+        if (
+          override !== undefined &&
+          (change === "breaking" || change === "non-breaking") &&
+          change !== override
+        ) {
+          if (override === "non-breaking" && (oldAst === "" || ast === null)) {
+            return yield* new ReclassifyError({
+              model: name,
+              reason:
+                "канонического AST нет — проверить вердикт нечем, override не принимается",
+            })
+          }
+          if (override === "non-breaking" && ast !== null && dropsColumns(oldAst, ast)) {
+            return yield* new ReclassifyError({
+              model: name,
+              reason:
+                "в новом SELECT колонок меньше — потомки читают удалённые колонки по именам, non-breaking противоречит AST",
+            })
+          }
+          reclassifiedFrom = change
+          explain = {
+            diverged: explain?.diverged ?? [],
+            reason: `override оператора: ${change} → ${override}; вердикт планировщика: ${explain?.reason ?? "—"}`,
+          }
+          change = override
+        }
+        // «версию сдвинули ТОЛЬКО родители»: отпечаток со старыми подписями
+        // родителей обязан дать known — иначе вместе с родителями разошлись
+        // и метаданные (kind/grain/columns/target), наследовать физику нельзя
+        const parentsOnly =
+          change === "indirect" &&
+          previous !== undefined &&
+          [...model.deps].every((dep) => current.has(dep)) &&
+          (yield* modelFingerprint(
+            model,
+            ast,
+            [...model.deps].sort().map((dep) => `${dep}=${current.get(dep)!}`),
+          )) === known
         // forward-only: явный флаг пользователя — либо каскад: собственный AST
         // не менялся, а все изменившиеся родители сами forward-only (реюз
         // физики родителя означает, что и потомку нечего переигрывать)
         const cascaded =
-          change === "indirect" &&
+          parentsOnly &&
           model.kind._tag === "incrementalByTimeRange" &&
           [...model.deps].every((dep) => {
             const parent = changeOf.get(dep)
@@ -177,6 +304,46 @@ export const planChanges = (
           change = "forward-only"
           reusedFrom = known
           physicalFingerprint = previous.physicalFp
+          explain = forwardOnly.has(name)
+            ? {
+                diverged: explain?.diverged ?? [],
+                reason: `forward-only по флагу: физика и done-интервалы наследуются от @${known.slice(0, 8)}, история не переигрывается`,
+              }
+            : {
+                diverged: [],
+                reason:
+                  "собственный AST не менялся, все изменившиеся родители forward-only — физика реюзается каскадом",
+                cascadeFrom: changedParents,
+              }
+        }
+        // indirect-реюз (#5, класс sqlmesh «indirect non-breaking»): своё тело
+        // не менялось, версию сдвинули только родители, и каждый изменившийся
+        // родитель гарантирует те же данные в старых колонках (non-breaking —
+        // строго суффикс; forward-only и реюз — буквально та же физика) —
+        // потомку нечего переигрывать: физика и учёт наследуются, scdType2
+        // не теряет накопленную историю строк
+        if (
+          change === "indirect" &&
+          parentsOnly &&
+          REUSABLE_KINDS.has(model.kind._tag) &&
+          changedParents.length > 0 &&
+          changedParents.every((dep) => {
+            const parent = changeOf.get(dep)!
+            return (
+              parent === "non-breaking" ||
+              parent === "forward-only" ||
+              (parent === "indirect" && reusedPhysics.has(dep))
+            )
+          })
+        ) {
+          reusedFrom = known
+          physicalFingerprint = previous!.physicalFp
+          reusedPhysics.add(name)
+          explain = {
+            diverged: [],
+            reason: `изменившиеся родители не трогают существующие данные (non-breaking/forward-only) — физика и учёт наследуются от @${known.slice(0, 8)}, пересборки нет`,
+            cascadeFrom: changedParents,
+          }
         }
       }
       changeOf.set(name, change)
@@ -220,6 +387,8 @@ export const planChanges = (
         ...(reusedFrom !== undefined ? { reusedFrom } : {}),
         canonicalAst: ast,
         change,
+        ...(reclassifiedFrom !== undefined ? { reclassifiedFrom } : {}),
+        ...(explain !== undefined ? { explain } : {}),
         build: !alreadyBuilt,
         backfill,
         // каждый apply сверяет запрос с физикой: upsert / SCD-версионирование

package/src/plan/run.ts

@@ -1,8 +1,8 @@
-import { Data, Effect, Schedule } from "effect"
+import { Clock, Data, Effect, Schedule } from "effect"
 import { buildGraph } from "../core/graph.ts"
 import type { AnyModel } from "../core/model.ts"
 import { EngineAdapter } from "../engine/adapter.ts"
-import { StateStore } from "../state/store.ts"
+import { StateStore, type RunRecord } from "../state/store.ts"
 import { applyPlan, type AppliedPlan, type ApplyError, type ApplyOptions } from "./executor.ts"
 import { envLockName, withStateLock, type LockHeldError, type LockOptions } from "./lock.ts"
 import { planChanges, type PlanOptions } from "./planner.ts"
@@ -25,22 +25,60 @@ export type RunError = ApplyError | LockHeldError | RunBlockedByChangesError
 
 export interface RunOptions extends PlanOptions, ApplyOptions, LockOptions {}
 
+/** Исход тика для журнала: ошибка → категория + деталь. */
+const classify = (error: RunError): Pick<RunRecord, "outcome" | "detail"> => {
+  switch (error._tag) {
+    case "RunBlockedByChangesError":
+      return { outcome: "awaiting-human", detail: error.changes.join("; ") }
+    case "LockHeldError":
+      return { outcome: "lock-held", detail: error.name }
+    default:
+      return { outcome: "error", detail: error._tag }
+  }
+}
+
 export const run = (
   env: string,
   models: Iterable<AnyModel>,
   options?: RunOptions,
 ): Effect.Effect<AppliedPlan, RunError, EngineAdapter | StateStore> =>
   Effect.gen(function* () {
-    const graph = yield* buildGraph(models)
-    const plan = yield* planChanges(env, graph, options)
-    const structural = plan.actions
-      .filter((a) => a.change !== "unchanged")
-      .map((a) => `${a.name}: ${a.change}`)
-    if (structural.length > 0) {
-      return yield* new RunBlockedByChangesError({ env, changes: structural })
-    }
-    return yield* applyPlan(plan, graph, options)
-  }).pipe(withStateLock(envLockName(env), options?.lockTtlMs))
+    const store = yield* StateStore
+    const startedAt = new Date(yield* Clock.currentTimeMillis).toISOString()
+    // журнал тиков (SPEC §7, #2): исход пишется ВСЕГДА, включая неуспех —
+    // упавший в три часа ночи cron-тик дебажится задним числом; сбой самой
+    // записи не маскирует настоящий исход (лог + ignore)
+    const journal = (entry: Pick<RunRecord, "outcome" | "detail">) =>
+      Clock.currentTimeMillis.pipe(
+        Effect.flatMap((now) =>
+          store.recordRun({
+            env,
+            startedAt,
+            finishedAt: new Date(now).toISOString(),
+            ...entry,
+          }),
+        ),
+        Effect.catchCause((cause) => Effect.logWarning("журнал тиков недоступен", cause)),
+      )
+
+    return yield* Effect.gen(function* () {
+      const graph = yield* buildGraph(models)
+      const plan = yield* planChanges(env, graph, options)
+      const structural = plan.actions
+        .filter((a) => a.change !== "unchanged")
+        .map((a) => `${a.name}: ${a.change}`)
+      if (structural.length > 0) {
+        return yield* new RunBlockedByChangesError({ env, changes: structural })
+      }
+      return yield* applyPlan(plan, graph, options)
+    }).pipe(
+      withStateLock(envLockName(env), options?.lockTtlMs),
+      Effect.tap((applied) =>
+        journal({ outcome: "ok", detail: JSON.stringify(applied.built) }),
+      ),
+      Effect.tapError((error) => journal(classify(error))),
+    )
+  })
 
 /**
  * Долгоживущий планировщик для встраивания в Effect-приложение (SPEC §7):

package/src/plan/schedule.ts

@@ -0,0 +1,212 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+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. Один заголовок = одна запись, повторная регистрация
+ * перезаписывает на месте (идемпотентно).
+ *
+ * Честные оговорки (документированы в README/SPEC): cron не догоняет
+ * пропущенные запуски (systemd Persistent=true строже — есть
+ * --print-systemd), OS-уровень живёт в ЛОКАЛЬНОЙ таймзоне (TZ=UTC поверх),
+ * на Linux нужен живой cron-демон — семейство Arch без cronie не имеет
+ * его вовсе. Наложение тиков безопасно по построению: run держит env-лок,
+ * а «ждёт человека» = exit 2, не сбой.
+ */
+
+export class ScheduleError extends Data.TaggedError("ScheduleError")<{
+  readonly reason: string
+}> {}
+
+/** Всё, что нужно воркеру, — абсолютными путями (crontab не знает cwd). */
+export interface ScheduleTarget {
+  /** Директория проекта (где лежит конфиг) — cwd тика. */
+  readonly project: string
+  /** Абсолютный путь конфига. */
+  readonly config: string
+  readonly env: string
+}
+
+/** Заголовок Bun.cron: только [A-Za-z0-9_-]; включает проект и окружение. */
+export const scheduleTitle = (target: Pick<ScheduleTarget, "project" | "env">): string =>
+  `efmesh-${basename(target.project)}-${target.env}`.replaceAll(/[^A-Za-z0-9_-]/g, "-")
+
+/** Куда генерируется воркер: рядом с конфигом, в служебной .efmesh/. */
+export const workerPath = (target: ScheduleTarget): string =>
+  join(target.project, ".efmesh", `schedule-${target.env}.ts`)
+
+/** Бинарь CLI этого же пакета — воркер зовёт его, не гадая по npm-именам. */
+const binPath = (): string => fileURLToPath(new URL("../bin.ts", import.meta.url))
+
+/**
+ * Исходник воркера для Bun.cron: OS-шедулер исполняет scheduled(), тот
+ * гоняет обычный `efmesh run` — та же семантика exit-кодов (2 = «ждёт
+ * человека») и тот же журнал тиков в сторе (`efmesh status`).
+ */
+export const workerSource = (target: ScheduleTarget): string => `// сгенерировано \`efmesh schedule\` — не редактируйте: перерегистрация перезапишет
+export default {
+  async scheduled() {
+    const proc = Bun.spawn(
+      [${JSON.stringify(process.execPath)}, ${JSON.stringify(binPath())}, "run", ${JSON.stringify(target.env)}, "--config", ${JSON.stringify(target.config)}],
+      { cwd: ${JSON.stringify(target.project)}, stdout: "inherit", stderr: "inherit" },
+    )
+    process.exitCode = await proc.exited
+  },
+}
+`
+
+/** Никнеймы cron → OnCalendar systemd; произвольные выражения не переводятся. */
+export const cronToOnCalendar = (cron: string): string | undefined =>
+  (
+    {
+      "@hourly": "hourly",
+      "@daily": "daily",
+      "@midnight": "daily",
+      "@weekly": "weekly",
+      "@monthly": "monthly",
+      "@yearly": "yearly",
+      "@annually": "yearly",
+    } as Record<string, string>
+  )[cron.trim()]
+
+/**
+ * systemd-фоллбэк (--print-systemd): у cron нет догона пропущенных запусков
+ * и на Arch-семействе нет демона — user-таймер с Persistent=true честнее.
+ */
+export const systemdUnits = (
+  target: ScheduleTarget,
+  cron: string,
+): { readonly service: string; readonly timer: string; readonly name: string } => {
+  const name = scheduleTitle(target)
+  const calendar = cronToOnCalendar(cron)
+  return {
+    name,
+    service: `[Unit]
+Description=efmesh run ${target.env} (${basename(target.project)})
+
+[Service]
+Type=oneshot
+WorkingDirectory=${target.project}
+ExecStart=${process.execPath} ${binPath()} run ${target.env} --config ${target.config}
+# exit 2 = «ждёт человека» (нужен apply) — намеренно failure юнита: видно в алертах
+`,
+    timer: `[Unit]
+Description=efmesh run ${target.env} — таймер
+
+[Timer]
+OnCalendar=${calendar ?? `hourly  # TODO: переведите «${cron}» в OnCalendar вручную`}
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`,
+  }
+}
+
+/** Валидация выражения тем же парсером, который будет его исполнять. */
+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}»` }),
+    })
+    if (next === null) {
+      return yield* new ScheduleError({
+        reason: `cron-выражение «${cron}» никогда не сработает`,
+      })
+    }
+  })
+
+/** Linux без crontab-бинаря (Arch-семейство) — честная ошибка с рецептом. */
+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",
+    })
+  })
+
+export const registerSchedule = (
+  target: ScheduleTarget,
+  cron: string,
+): Effect.Effect<{ readonly title: string; readonly worker: string }, ScheduleError> =>
+  Effect.gen(function* () {
+    yield* validateCron(cron)
+    yield* requireCrontab()
+    if (!existsSync(target.config)) {
+      return yield* new ScheduleError({ reason: `конфига нет: ${target.config}` })
+    }
+    const worker = workerPath(target)
+    yield* Effect.try({
+      try: () => {
+        mkdirSync(dirname(worker), { recursive: true })
+        writeFileSync(worker, workerSource(target))
+      },
+      catch: (cause) =>
+        new ScheduleError({ reason: `воркер не записался: ${String(cause)}` }),
+    })
+    const title = scheduleTitle(target)
+    yield* Effect.tryPromise({
+      try: () => Bun.cron(worker, cron, title),
+      catch: (cause) =>
+        new ScheduleError({ reason: `Bun.cron не зарегистрировал: ${String(cause)}` }),
+    })
+    return { title, worker }
+  })
+
+export const removeSchedule = (
+  target: ScheduleTarget,
+): Effect.Effect<{ readonly title: string }, ScheduleError> =>
+  Effect.gen(function* () {
+    const title = scheduleTitle(target)
+    yield* Effect.tryPromise({
+      try: () => Bun.cron.remove(title),
+      catch: (cause) => new ScheduleError({ reason: `Bun.cron.remove: ${String(cause)}` }),
+    })
+    // воркер больше никем не исполняется — прибираем молча
+    yield* Effect.sync(() => rmSync(workerPath(target), { force: true }))
+    return { title }
+  })
+
+/**
+ * Список efmesh-регистраций — по платформенным следам Bun.cron: маркеры
+ * `# bun-cron: <title>` в crontab (Linux) / plist'ы launchd (macOS).
+ */
+export const listSchedules = (): Effect.Effect<ReadonlyArray<string>, ScheduleError> =>
+  Effect.gen(function* () {
+    if (process.platform === "linux") {
+      if (Bun.which("crontab") === null) return []
+      const out = yield* Effect.tryPromise({
+        try: async () => {
+          const proc = Bun.spawn(["crontab", "-l"], { stdout: "pipe", stderr: "ignore" })
+          const text = await proc.stdout.text()
+          await proc.exited // пустой crontab выходит с 1 — это не ошибка
+          return text
+        },
+        catch: (cause) => new ScheduleError({ reason: `crontab -l: ${String(cause)}` }),
+      })
+      return out
+        .split("\n")
+        .filter((line) => line.includes("bun-cron") && line.includes("efmesh-"))
+    }
+    if (process.platform === "darwin") {
+      const out = yield* Effect.tryPromise({
+        try: async () => {
+          const proc = Bun.spawn(["launchctl", "list"], { stdout: "pipe", stderr: "ignore" })
+          const text = await proc.stdout.text()
+          await proc.exited
+          return text
+        },
+        catch: (cause) => new ScheduleError({ reason: `launchctl list: ${String(cause)}` }),
+      })
+      return out.split("\n").filter((line) => line.includes("bun.cron.efmesh-"))
+    }
+    return yield* new ScheduleError({
+      reason: `список на ${process.platform} смотрите средствами ОС (Task Scheduler: schtasks /query)`,
+    })
+  })

package/src/plan/status.ts

@@ -0,0 +1,95 @@
+import { Clock, Effect } from "effect"
+import { buildGraph, type GraphError } from "../core/graph.ts"
+import { enumerateIntervals, fromIso, missingIntervals, toIso } from "../core/interval.ts"
+import type { AnyModel } from "../core/model.ts"
+import { STATE_VERSION, StateStore } from "../state/store.ts"
+import type { PlanRecord, RunRecord, StateError } from "../state/store.ts"
+
+/**
+ * `efmesh status <env>` (issue #1): одна команда на вопрос «что вообще
+ * происходит» — для оператора ночного cron и для автора, забывшего
+ * команды. Только чтение: стор открыт → версия схемы уже совпала.
+ */
+
+export interface ModelLag {
+  readonly model: string
+  /** Конец последнего done-интервала (ISO); null — ещё ничего не посчитано. */
+  readonly doneUpTo: string | null
+  /** Сколько интервалов не хватает до «сейчас». 0 — догнано. */
+  readonly missing: number
+  /** Интервалы, помеченные failed, — застрявший бэкфилл виден сразу. */
+  readonly failed: number
+}
+
+export interface StatusReport {
+  readonly env: string
+  readonly storeVersion: number
+  /** Строк в окружении; 0 — окружение не существует (ни разу не применялось). */
+  readonly models: number
+  /** Последний промоушен (ISO); null — окружения нет. */
+  readonly promotedAt: string | null
+  readonly lastPlan: PlanRecord | null
+  /** Последние тики run, свежие первыми. */
+  readonly ticks: ReadonlyArray<RunRecord>
+  /** Отставание incremental-моделей окружения. */
+  readonly lag: ReadonlyArray<ModelLag>
+}
+
+export interface StatusOptions {
+  /** «Сейчас» для расчёта отставания; по умолчанию — Clock. Инъекция для тестов. */
+  readonly now?: number
+  /** Сколько последних тиков показать; по умолчанию 5. */
+  readonly ticks?: number
+}
+
+export const environmentStatus = (
+  env: string,
+  models: Iterable<AnyModel>,
+  options?: StatusOptions,
+): Effect.Effect<StatusReport, GraphError | StateError, StateStore> =>
+  Effect.gen(function* () {
+    const store = yield* StateStore
+    const graph = yield* buildGraph(models)
+    const now = options?.now ?? (yield* Clock.currentTimeMillis)
+
+    const rows = yield* store.getEnvironment(env)
+    const promotedAt =
+      rows.length === 0
+        ? null
+        : rows.map((row) => row.promotedAt).reduce((a, b) => (a > b ? a : b))
+
+    const plans = yield* store.listPlans(env)
+    const lastPlan = plans.at(-1) ?? null
+    const ticks = yield* store.listRuns(env, options?.ticks ?? 5)
+
+    // отставание — по УКАЗАТЕЛЯМ окружения (что реально отдаётся
+    // потребителям), а не по локальным fingerprint'ам проекта
+    const lag: Array<ModelLag> = []
+    for (const row of rows) {
+      const model = graph.models.get(row.name)
+      if (model === undefined || model.kind._tag !== "incrementalByTimeRange") continue
+      const kind = model.kind
+      const records = yield* store.listIntervals(row.fingerprint)
+      const done = records
+        .filter((record) => record.status === "done")
+        .map((record) => ({ start: fromIso(record.startTs), end: fromIso(record.endTs) }))
+      const wanted = enumerateIntervals(kind.interval, fromIso(kind.start), now)
+      const missing = missingIntervals(wanted, done)
+      lag.push({
+        model: row.name,
+        doneUpTo: done.length === 0 ? null : toIso(Math.max(...done.map((i) => i.end))),
+        missing: missing.length,
+        failed: records.filter((record) => record.status === "failed").length,
+      })
+    }
+
+    return {
+      env,
+      storeVersion: STATE_VERSION,
+      models: rows.length,
+      promotedAt,
+      lastPlan,
+      ticks,
+      lag,
+    }
+  })