@avytheone/efmesh 0.1.0-beta.2 → 0.2.1

package/src/cli.ts

@@ -1,6 +1,6 @@
 import { writeFileSync } from "node:fs"
 import * as NodePath from "node:path"
-import { Console, Data, Effect, Layer } from "effect"
+import { Cause, Console, Data, Effect, Layer } from "effect"
 import { Argument, Command, Flag } from "effect/unstable/cli"
 import type { EfmeshConfig } from "./config.ts"
 import { buildGraph } from "./core/graph.ts"
@@ -12,24 +12,41 @@ import { DuckDBEngineLive } from "./engine/duckdb.ts"
 import { PostgresEngineLive } from "./engine/postgres.ts"
 import { PostgresStateLive } from "./state/postgres.ts"
 import { auditEnvironment, EnvironmentAuditError } from "./plan/audit-run.ts"
-import { diffEnvironments } from "./plan/diff.ts"
+import {
+  dataDiffEnvironments,
+  diffEnvironments,
+  type DataDiffReport,
+} from "./plan/diff.ts"
+import { EngineAdapter } from "./engine/adapter.ts"
+import { ducklakeAttachSql } from "./plan/naming.ts"
+import {
+  listSchedules,
+  registerSchedule,
+  removeSchedule,
+  systemdUnits,
+} from "./plan/schedule.ts"
 import { renderGraphHtml } from "./plan/graph-html.ts"
 import { formatLineage, lineage, LineageError } from "./plan/lineage.ts"
+import { environmentStatus } from "./plan/status.ts"
 import { janitor } from "./plan/janitor.ts"
 import { fp8 } from "./plan/naming.ts"
 import { envLockName, withStateLock } from "./plan/lock.ts"
 import { applyPlan } from "./plan/executor.ts"
 import { run } from "./plan/run.ts"
-import { planChanges, type Plan } from "./plan/planner.ts"
+import { planChanges, ReclassifyError, type Plan } from "./plan/planner.ts"
 import { migratePostgresState } from "./state/postgres.ts"
 import { migrateSqliteState, SqliteStateLive } from "./state/sqlite.ts"
 
 export class ConfigLoadError extends Data.TaggedError("ConfigLoadError")<{
   readonly path: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `config ${this.path}: ${this.reason}`
+  }
+}
 
-/** Конфиг с уже собранным списком моделей: явные + найденные discovery. */
+/** Config with an already-assembled model list: explicit ones + discovery finds. */
 type LoadedConfig = EfmeshConfig & { readonly models: ReadonlyArray<AnyModel> }
 
 const loadConfig = (
@@ -44,7 +61,7 @@ const loadConfig = (
           module.default === undefined ||
           (!Array.isArray(module.default.models) && module.default.discovery === undefined)
         ) {
-          throw new Error("конфиг должен экспортировать default с models и/или discovery")
+          throw new Error("config must export a default with models and/or discovery")
         }
         return module.default
       },
@@ -52,10 +69,10 @@ const loadConfig = (
     })
     const explicit = config.models ?? []
     if (config.discovery === undefined) return { ...config, models: explicit }
-    // маски — относительно конфига: проект переносим независимо от cwd
+    // globs are relative to the config: the project is portable regardless of cwd
     const discovered = yield* discoverModels(config.discovery, NodePath.dirname(absolute))
     const seen = new Set(explicit)
-    const names = new Map(explicit.map((model) => [model.name.full, "models в конфиге"]))
+    const names = new Map(explicit.map((model) => [model.name.full, "config models"]))
     const merged = [...explicit]
     for (const model of discovered) {
       if (seen.has(model)) continue
@@ -69,7 +86,7 @@ const loadConfig = (
     return { ...config, models: merged }
   })
 
-/** Слои движка и состояния из конфига — общие для plan/apply. */
+/** Engine and state layers from the config — shared by plan/apply. */
 const configLayers = (config: EfmeshConfig) =>
   Layer.mergeAll(
     config.engine?.url !== undefined
@@ -85,7 +102,7 @@ const configLayers = (config: EfmeshConfig) =>
 
 const configFlag = Flag.string("config").pipe(
   Flag.withDefault("efmesh.config.ts"),
-  Flag.withDescription("Путь к efmesh.config.ts"),
+  Flag.withDescription("path to efmesh.config.ts"),
 )
 
 const CHANGE_MARK: Record<string, string> = {
@@ -101,14 +118,21 @@ const CHANGE_MARK: Record<string, string> = {
 const forwardOnlyFlag = Flag.string("forward-only").pipe(
   Flag.withDefault(""),
   Flag.withDescription(
-    "Модели через запятую: изменения применяются forward-only — физика и история переиспользуются",
+    "comma-separated models: changes apply forward-only — physics and history are reused",
+  ),
+)
+
+const reclassifyFlag = Flag.string("reclassify").pipe(
+  Flag.withDefault(""),
+  Flag.withDescription(
+    'override categorization (#5): "model=breaking|non-breaking[,…]" on top of --explain; journaled with applied_by',
   ),
 )
 
 const jobsFlag = Flag.string("jobs").pipe(
   Flag.withDefault(""),
   Flag.withDescription(
-    "Сколько моделей строить одновременно (DAG-конкурентность; на DuckDB всегда 1)",
+    "how many models to build at once (DAG concurrency; always 1 on DuckDB)",
   ),
 )
 
@@ -120,7 +144,7 @@ const parseJobs = (value: string): number | undefined => {
 const retriesFlag = Flag.string("retries").pipe(
   Flag.withDefault(""),
   Flag.withDescription(
-    "Сколько раз ретраить упавший батч бэкфилла (экспоненциальная пауза; по умолчанию 0)",
+    "how many times to retry a failed backfill batch (exponential backoff; default 0)",
   ),
 )
 
@@ -139,27 +163,56 @@ const parseForwardOnly = (value: string): ReadonlyArray<string> | undefined => {
   return names.length > 0 ? names : undefined
 }
 
+/** `model=breaking|non-breaking[,…]` → record for PlanOptions.reclassify (#5). */
+export const parseReclassify = (
+  value: string,
+): Effect.Effect<Readonly<Record<string, "breaking" | "non-breaking">> | undefined, ReclassifyError> =>
+  Effect.gen(function* () {
+    const entries = value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry !== "")
+    if (entries.length === 0) return undefined
+    const parsed: Record<string, "breaking" | "non-breaking"> = {}
+    for (const entry of entries) {
+      const [model, category, ...extra] = entry.split("=")
+      if (
+        model === undefined ||
+        model === "" ||
+        extra.length > 0 ||
+        (category !== "breaking" && category !== "non-breaking")
+      ) {
+        return yield* new ReclassifyError({
+          model: entry,
+          reason: 'expected "model=breaking" or "model=non-breaking"',
+        })
+      }
+      parsed[model] = category
+    }
+    return parsed
+  })
+
 const yesFlag = Flag.boolean("yes").pipe(
   Flag.withAlias("y"),
-  Flag.withDescription("Применить без подтверждения (не-TTY подтверждения не спрашивает)"),
+  Flag.withDescription("apply without confirmation (non-TTY never asks)"),
 )
 
-/** y/yes/д/да — регистронезависимо; всё остальное (включая пусто) — отказ. */
+/** Accepts y/yes, case-insensitive; anything else (including empty) is a refusal. */
 export const isAffirmative = (answer: string | null): boolean =>
-  ["y", "yes", "д", "да"].includes((answer ?? "").trim().toLowerCase())
+  ["y", "yes"].includes((answer ?? "").trim().toLowerCase())
 
 /**
- * Exit-код «работа ждёт человека» (F6): план требует подтверждения в не-TTY
- * или run упёрся в структурные изменения. Алертинг обязан отличать это
- * штатное состояние от настоящих ошибок (код 1).
+ * The "work awaits a human" exit code (F6): the plan needs confirmation in a
+ * non-TTY, or run hit structural changes. Alerting must distinguish this
+ * normal state from real errors (code 1).
  */
 export const EXIT_AWAITING_HUMAN = 2
 
 /**
- * Судьба показанного плана (SPEC §5.1, ужесточено в F6): без изменений или
- * с --yes — применять; изменения в TTY — спросить человека; изменения в
- * не-TTY (CI, cron, пайп) — ОТКАЗ: молча применять план, который никто не
- * видел, нельзя, нужен явный --yes.
+ * The fate of a shown plan (SPEC §5.1, tightened in F6): no changes or
+ * --yes — apply; changes in a TTY — ask the human; changes in a
+ * non-TTY (CI, cron, pipe) — REFUSE: silently applying a plan nobody
+ * saw is forbidden, an explicit --yes is required.
  */
 export const decideApply = (
   hasChanges: boolean,
@@ -167,24 +220,76 @@ export const decideApply = (
   tty: boolean,
 ): "apply" | "ask" | "refuse" => (!hasChanges || yes ? "apply" : tty ? "ask" : "refuse")
 
+const jsonFlag = Flag.boolean("json").pipe(
+  Flag.withDescription("machine-readable output (stable shape — a contract for CI)"),
+)
+
+const explainFlag = Flag.boolean("explain").pipe(
+  Flag.withDescription(
+    "for each change — which canonical AST nodes diverged and why the category is what it is",
+  ),
+)
+
+/**
+ * JSON shape of the plan (#3) — a CONTRACT for CI and bots: shape changes
+ * are package semver events. Intervals are ISO UTC, not epoch ms.
+ */
+export const planToJson = (plan: Plan): unknown => ({
+  env: plan.env,
+  hasChanges: plan.hasChanges,
+  actions: plan.actions.map((action) => ({
+    name: action.name,
+    change: action.change,
+    // operator override (#5) and physical reuse — additive contract fields
+    ...(action.reclassifiedFrom !== undefined
+      ? { reclassifiedFrom: action.reclassifiedFrom }
+      : {}),
+    ...(action.reusedFrom !== undefined ? { reusedFrom: action.reusedFrom } : {}),
+    fingerprint: action.fingerprint,
+    build: action.build,
+    backfill: action.backfill.map((range) => ({
+      start: new Date(range.start).toISOString(),
+      end: new Date(range.end).toISOString(),
+    })),
+    // category reason (#4); diverged paths are a debug hint, not a contract
+    ...(action.explain !== undefined ? { explain: action.explain } : {}),
+  })),
+})
+
+const printJson = (payload: unknown) => Console.log(JSON.stringify(payload, null, 2))
+
 const formatRange = (range: { readonly start: number; readonly end: number }): string =>
-  `[${new Date(range.start).toISOString().slice(0, 10)} … ${new Date(range.end).toISOString().slice(0, 10)})`
+  `[${new Date(range.start).toISOString().slice(0, 10)}, ${new Date(range.end).toISOString().slice(0, 10)})`
 
-const printPlan = (plan: Plan) =>
+const printPlan = (plan: Plan, explain = false) =>
   Effect.gen(function* () {
-    yield* Console.log(`план для окружения «${plan.env}»:`)
+    yield* Console.log(`plan for environment "${plan.env}":`)
     for (const action of plan.actions) {
       const mark = CHANGE_MARK[action.change] ?? "?"
-      const build = action.build ? "  [сборка]" : ""
+      const overridden =
+        action.reclassifiedFrom !== undefined
+          ? `  [override: was ${action.reclassifiedFrom}]`
+          : ""
+      const reused =
+        action.change === "indirect" && action.reusedFrom !== undefined
+          ? "  [physics reused]"
+          : ""
+      const build = action.build ? "  [build]" : ""
       const backfill =
         action.backfill.length > 0
-          ? `  бэкфилл ${action.backfill.map(formatRange).join(", ")}`
+          ? `  backfill ${action.backfill.map(formatRange).join(", ")}`
           : ""
       yield* Console.log(
-        `  ${mark} ${action.name}  ${action.change} @${fp8(action.fingerprint)}${build}${backfill}`,
+        `  ${mark} ${action.name}  ${action.change} @${fp8(action.fingerprint)}${overridden}${reused}${build}${backfill}`,
       )
+      if (explain && action.explain !== undefined) {
+        yield* Console.log(`      why: ${action.explain.reason}`)
+        if (action.explain.diverged.length > 0) {
+          yield* Console.log(`      diverged: ${action.explain.diverged.join(", ")}`)
+        }
+      }
     }
-    if (!plan.hasChanges) yield* Console.log("  изменений нет")
+    if (!plan.hasChanges) yield* Console.log("  no changes")
   })
 
 const initCommand = Command.make(
@@ -193,24 +298,33 @@ const initCommand = Command.make(
   ({ dir }) =>
     Effect.gen(function* () {
       const created = yield* scaffold(dir)
-      for (const file of created) yield* Console.log(`создан ${file}`)
-      yield* Console.log("дальше: bunx efmesh plan dev && bunx efmesh apply dev")
+      for (const file of created) yield* Console.log(`created ${file}`)
+      yield* Console.log("next: bunx efmesh plan dev && bunx efmesh apply dev")
     }),
-).pipe(Command.withDescription("Скаффолд проекта: конфиг, модели-пример, seed"))
+).pipe(Command.withDescription("scaffold a project: config, example models, seed"))
 
 const planCommand = Command.make(
   "plan",
-  { env: Argument.string("env"), config: configFlag, forwardOnly: forwardOnlyFlag },
-  ({ config, env, forwardOnly }) =>
+  {
+    env: Argument.string("env"),
+    config: configFlag,
+    forwardOnly: forwardOnlyFlag,
+    reclassify: reclassifyFlag,
+    json: jsonFlag,
+    explain: explainFlag,
+  },
+  ({ config, env, explain, forwardOnly, json, reclassify }) =>
     Effect.gen(function* () {
       const loaded = yield* loadConfig(config)
       const names = parseForwardOnly(forwardOnly)
+      const overrides = yield* parseReclassify(reclassify)
       const plan = yield* Efmesh.plan(env, loaded.models, {
         ...(names !== undefined ? { forwardOnly: names } : {}),
+        ...(overrides !== undefined ? { reclassify: overrides } : {}),
       }).pipe(Effect.provide(configLayers(loaded)))
-      yield* printPlan(plan)
+      yield* json ? printJson(planToJson(plan)) : printPlan(plan, explain)
     }),
-).pipe(Command.withDescription("Показать diff проекта против окружения, ничего не меняя"))
+).pipe(Command.withDescription("show the project diff against an environment, changing nothing"))
 
 const applyCommand = Command.make(
   "apply",
@@ -218,30 +332,33 @@ const applyCommand = Command.make(
     env: Argument.string("env"),
     config: configFlag,
     forwardOnly: forwardOnlyFlag,
+    reclassify: reclassifyFlag,
     jobs: jobsFlag,
     retries: retriesFlag,
     yes: yesFlag,
   },
-  ({ config, env, forwardOnly, jobs, retries, yes }) =>
+  ({ config, env, forwardOnly, jobs, reclassify, retries, yes }) =>
     Effect.gen(function* () {
       const loaded = yield* loadConfig(config)
       const names = parseForwardOnly(forwardOnly)
+      const overrides = yield* parseReclassify(reclassify)
       const modelConcurrency = parseJobs(jobs)
       const retry = parseRetries(retries)
-      // план и применение — под одним слоем и одним межпроцессным локом:
-      // применяется ровно тот план, который показан и подтверждён, и никто
-      // (второй apply, cron с run) не вклинится между ними (SPEC §14.6);
-      // цена — лок держится и пока человек думает над подтверждением
+      // plan and apply — under one layer and one cross-process lock:
+      // exactly the plan that was shown and confirmed gets applied, and no one
+      // (a second apply, cron with run) wedges in between them (SPEC §14.6);
+      // the cost — the lock is held even while the human ponders confirmation
       yield* Effect.gen(function* () {
         const graph = yield* buildGraph(loaded.models)
         const plan = yield* planChanges(env, graph, {
           ...(names !== undefined ? { forwardOnly: names } : {}),
+          ...(overrides !== undefined ? { reclassify: overrides } : {}),
         })
         yield* printPlan(plan)
         const decision = decideApply(plan.hasChanges, yes, process.stdin.isTTY === true)
         if (decision === "refuse") {
           yield* Console.error(
-            "план меняет модели, а подтвердить некому (не-TTY): добавьте --yes",
+            "the plan changes models but there is no one to confirm (non-TTY): add --yes",
           )
           yield* Effect.sync(() => {
             process.exitCode = EXIT_AWAITING_HUMAN
@@ -250,9 +367,9 @@ const applyCommand = Command.make(
         }
         if (
           decision === "ask" &&
-          !isAffirmative(globalThis.prompt("применить план? [y/N]"))
+          !isAffirmative(globalThis.prompt("apply the plan? [y/N]"))
         ) {
-          yield* Console.log("применение отменено")
+          yield* Console.log("apply cancelled")
           return
         }
         const applied = yield* applyPlan(plan, graph, {
@@ -264,13 +381,13 @@ const applyCommand = Command.make(
         })
         yield* Console.log(
           applied.built.length > 0
-            ? `собрано: ${applied.built.join(", ")}`
-            : "сборка не потребовалась (только view-swap)",
+            ? `built: ${applied.built.join(", ")}`
+            : "no build needed (view-swap only)",
         )
-        yield* Console.log(`окружение «${applied.plan.env}» промоутнуто`)
+        yield* Console.log(`environment "${applied.plan.env}" promoted`)
       }).pipe(withStateLock(envLockName(env)), Effect.provide(configLayers(loaded)))
     }),
-).pipe(Command.withDescription("Применить план: собрать физику и переключить view"))
+).pipe(Command.withDescription("apply the plan: build physics and swap views"))
 
 const renderCommand = Command.make(
   "render",
@@ -279,7 +396,7 @@ const renderCommand = Command.make(
     config: configFlag,
     env: Flag.string("env").pipe(
       Flag.withDefault(""),
-      Flag.withDescription("Рендер против view-слоя окружения вместо логических имён"),
+      Flag.withDescription("render against an environment's view layer instead of logical names"),
     ),
   },
   ({ config, env, model }) =>
@@ -290,7 +407,7 @@ const renderCommand = Command.make(
         : yield* Efmesh.renderFor(loaded.models, model, env)
       yield* Console.log(sql.trim())
     }),
-).pipe(Command.withDescription("Показать итоговый SQL модели"))
+).pipe(Command.withDescription("show a model's final SQL"))
 
 const runCommand = Command.make(
   "run",
@@ -308,12 +425,12 @@ const runCommand = Command.make(
         ...(retry !== undefined ? { retry } : {}),
       }).pipe(
         Effect.provide(configLayers(loaded)),
-        // структурные изменения — штатное «ждёт человека с apply», не сбой:
-        // алертинг различает по exit-коду 2 (F6)
+        // structural changes are the normal "awaits a human with apply", not a failure:
+        // alerting tells it apart by exit code 2 (F6)
         Effect.catchTag("RunBlockedByChangesError", (blocked) =>
           Effect.gen(function* () {
             yield* Console.error(
-              `run ${blocked.env}: есть неприменённые изменения — нужен apply:\n  ${blocked.changes.join("\n  ")}`,
+              `run "${blocked.env}": unapplied changes present — apply needed:\n  ${blocked.changes.join("\n  ")}`,
             )
             yield* Effect.sync(() => {
               process.exitCode = EXIT_AWAITING_HUMAN
@@ -325,35 +442,198 @@ const runCommand = Command.make(
       if (applied === undefined) return
       yield* Console.log(
         applied.built.length > 0
-          ? `обработано: ${applied.built.join(", ")}`
-          : "новых интервалов нет",
+          ? `processed: ${applied.built.join(", ")}`
+          : "no new intervals",
       )
     }),
 ).pipe(
   Command.withDescription(
-    "Тик планировщика: догнать интервалы существующих версий (изменения — через apply)",
+    "scheduler tick: catch up intervals of existing versions (changes go through apply)",
   ),
 )
 
+const printDataDiff = (report: DataDiffReport) =>
+  Effect.gen(function* () {
+    yield* Console.log(`data "${report.envA}" ↔ "${report.envB}":`)
+    if (report.models.length === 0) {
+      yield* Console.log("  no shared materializable models")
+      return
+    }
+    for (const entry of report.models) {
+      if (entry.key === undefined) {
+        yield* Console.log(
+          `  · ${entry.model}  A=${entry.rowsA} B=${entry.rowsB}  no key (set a grain) — counts only`,
+        )
+      } else {
+        const clean =
+          entry.onlyInA === 0 &&
+          entry.onlyInB === 0 &&
+          (entry.columns?.length ?? 0) === 0 &&
+          entry.rowsA === entry.rowsB
+        const sampled =
+          entry.sampledPercent !== undefined ? `  (sample ${entry.sampledPercent}%)` : ""
+        yield* Console.log(
+          `  ${clean ? "✓" : "≠"} ${entry.model}  A=${entry.rowsA} B=${entry.rowsB}  key (${entry.key.join(", ")}): only in A ${entry.onlyInA}, only in B ${entry.onlyInB}, matched ${entry.matched}${sampled}`,
+        )
+        for (const drift of entry.columns ?? []) {
+          yield* Console.log(
+            `      ${drift.column}: ${drift.mismatches} of ${entry.matched} (${(drift.rate * 100).toFixed(2)}%)`,
+          )
+        }
+      }
+      if (entry.columnsOnlyInA !== undefined) {
+        yield* Console.log(`      columns only in A: ${entry.columnsOnlyInA.join(", ")}`)
+      }
+      if (entry.columnsOnlyInB !== undefined) {
+        yield* Console.log(`      columns only in B: ${entry.columnsOnlyInB.join(", ")}`)
+      }
+    }
+  })
+
 const diffCommand = Command.make(
   "diff",
-  { envA: Argument.string("envA"), envB: Argument.string("envB"), config: configFlag },
-  ({ config, envA, envB }) =>
+  {
+    envA: Argument.string("envA"),
+    envB: Argument.string("envB"),
+    config: configFlag,
+    data: Flag.boolean("data").pipe(
+      Flag.withDescription(
+        "compare view-layer DATA: row counts, key intersection, per-column divergences",
+      ),
+    ),
+    model: Flag.string("model").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("only these models, comma-separated (for --data)"),
+    ),
+    sample: Flag.string("sample").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription(
+        "percent 1–99: compare a deterministic fraction of keys (md5 buckets; for --data)",
+      ),
+    ),
+    json: jsonFlag,
+  },
+  ({ config, data, envA, envB, json, model, sample }) =>
     Effect.gen(function* () {
       const loaded = yield* loadConfig(config)
+      if (data) {
+        const only = parseForwardOnly(model)
+        const percent = sample === "" ? undefined : Number(sample)
+        if (percent !== undefined && !(Number.isFinite(percent) && percent >= 1 && percent <= 99)) {
+          yield* Console.error("--sample expects a percent from 1 to 99")
+          return yield* Effect.sync(() => {
+            process.exitCode = 1
+          })
+        }
+        const report = yield* Effect.gen(function* () {
+          // ducklake marts are visible via ATTACH — the same way apply does it
+          if (loaded.ducklake !== undefined) {
+            const engine = yield* EngineAdapter
+            yield* engine.execute(ducklakeAttachSql(loaded.ducklake))
+          }
+          return yield* dataDiffEnvironments(envA, envB, loaded.models, {
+            ...(only !== undefined ? { models: only } : {}),
+            ...(percent !== undefined ? { samplePercent: percent } : {}),
+          })
+        }).pipe(Effect.provide(configLayers(loaded)))
+        yield* json ? printJson(report) : printDataDiff(report)
+        return
+      }
       const diff = yield* diffEnvironments(envA, envB).pipe(
         Effect.provide(configLayers(loaded)),
       )
-      for (const name of diff.onlyInA) yield* Console.log(`< ${name}  только в ${envA}`)
-      for (const name of diff.onlyInB) yield* Console.log(`> ${name}  только в ${envB}`)
+      if (json) {
+        yield* printJson(diff)
+        return
+      }
+      for (const name of diff.onlyInA) yield* Console.log(`< ${name}  only in ${envA}`)
+      for (const name of diff.onlyInB) yield* Console.log(`> ${name}  only in ${envB}`)
       for (const entry of diff.different) {
         yield* Console.log(`≠ ${entry.name}  ${envA}@${entry.a} vs ${envB}@${entry.b}`)
       }
       if (diff.onlyInA.length + diff.onlyInB.length + diff.different.length === 0) {
-        yield* Console.log("окружения идентичны")
+        yield* Console.log("environments are identical")
       }
     }),
-).pipe(Command.withDescription("Чем окружения отличаются (по state store)"))
+).pipe(
+  Command.withDescription("how environments differ: versions (state store) or --data (row data)"),
+)
+
+const scheduleCommand = Command.make(
+  "schedule",
+  {
+    env: Argument.string("env").pipe(Argument.withDefault("")),
+    config: configFlag,
+    cron: Flag.string("cron").pipe(
+      Flag.withDefault("@hourly"),
+      Flag.withDescription("cron expression or nickname (@hourly, @daily, …)"),
+    ),
+    remove: Flag.boolean("remove").pipe(
+      Flag.withDescription("unregister the environment from the OS scheduler"),
+    ),
+    list: Flag.boolean("list").pipe(
+      Flag.withDescription("list efmesh entries in the OS scheduler"),
+    ),
+    printSystemd: Flag.boolean("print-systemd").pipe(
+      Flag.withDescription(
+        "print systemd user units instead of cron (Persistent=true catches up misses; a lifeline without a cron daemon)",
+      ),
+    ),
+  },
+  ({ config, cron, env, list, printSystemd, remove }) =>
+    Effect.gen(function* () {
+      if (list) {
+        const entries = yield* listSchedules()
+        if (entries.length === 0) yield* Console.log("no efmesh entries in the OS scheduler")
+        for (const entry of entries) yield* Console.log(`  ${entry}`)
+        return
+      }
+      if (env === "") {
+        yield* Console.error("environment required: efmesh schedule <env> [--cron …]")
+        return yield* Effect.sync(() => {
+          process.exitCode = 1
+        })
+      }
+      const configAbs = NodePath.resolve(process.cwd(), config)
+      const target = { project: NodePath.dirname(configAbs), config: configAbs, env }
+      if (printSystemd) {
+        const units = systemdUnits(target, cron)
+        yield* Console.log(`# ~/.config/systemd/user/${units.name}.service`)
+        yield* Console.log(units.service)
+        yield* Console.log(`# ~/.config/systemd/user/${units.name}.timer`)
+        yield* Console.log(units.timer)
+        yield* Console.log(
+          `# enable: systemctl --user daemon-reload && systemctl --user enable --now ${units.name}.timer`,
+        )
+        return
+      }
+      if (remove) {
+        const removed = yield* removeSchedule(target)
+        yield* Console.log(`unregistered: ${removed.title}`)
+        return
+      }
+      const registered = yield* registerSchedule(target, cron)
+      yield* Console.log(`registered: ${registered.title} — "${cron}" (OS scheduler)`)
+      yield* Console.log(`worker: ${registered.worker}`)
+      yield* Console.log(
+        "tick journal: efmesh status " + env + "; NB: cron does not catch up missed runs — a systemd timer is stricter (--print-systemd)",
+      )
+    }).pipe(
+      // reason is the most valuable part (a recipe for the operator): surface it in words, not a stacktrace
+      Effect.catchTag("ScheduleError", (error) =>
+        Effect.gen(function* () {
+          yield* Console.error(`schedule: ${error.reason}`)
+          yield* Effect.sync(() => {
+            process.exitCode = 1
+          })
+        }),
+      ),
+    ),
+).pipe(
+  Command.withDescription(
+    "register run <env> in the OS scheduler (Bun.cron: crontab/launchd/Task Scheduler)",
+  ),
+)
 
 const janitorCommand = Command.make(
   "janitor",
@@ -361,7 +641,7 @@ const janitorCommand = Command.make(
     config: configFlag,
     ttl: Flag.string("ttl").pipe(
       Flag.withDefault("7"),
-      Flag.withDescription("Сколько дней осиротевшая физика живёт до сноса"),
+      Flag.withDescription("how many days orphaned physics lives before removal"),
     ),
   },
   ({ config, ttl }) =>
@@ -374,14 +654,64 @@ const janitorCommand = Command.make(
       }).pipe(Effect.provide(configLayers(loaded)))
       yield* Console.log(
         report.removed.length > 0
-          ? `снесено: ${report.removed.join(", ")}`
-          : "осиротевшей физики старше ttl нет",
+          ? `removed: ${report.removed.join(", ")}`
+          : "no orphaned physics older than ttl",
       )
       if (report.kept.length > 0) {
-        yield* Console.log(`осиротело, но моложе ttl: ${report.kept.join(", ")}`)
+        yield* Console.log(`orphaned but younger than ttl: ${report.kept.join(", ")}`)
       }
     }),
-).pipe(Command.withDescription("Убрать физику, на которую не ссылается ни одно окружение"))
+).pipe(Command.withDescription("remove physics no environment references"))
+
+const statusCommand = Command.make(
+  "status",
+  { env: Argument.string("env"), config: configFlag, json: jsonFlag },
+  ({ config, env, json }) =>
+    Effect.gen(function* () {
+      const loaded = yield* loadConfig(config)
+      const report = yield* environmentStatus(env, loaded.models).pipe(
+        Effect.provide(configLayers(loaded)),
+      )
+      if (json) {
+        yield* printJson(report)
+        return
+      }
+      if (report.models === 0) {
+        yield* Console.log(`environment "${env}" does not exist — the first apply creates it`)
+        return
+      }
+      yield* Console.log(
+        `environment "${env}": models ${report.models}, promoted ${report.promotedAt}, store schema v${report.storeVersion}`,
+      )
+      if (report.lastPlan !== null) {
+        yield* Console.log(
+          `last plan: ${report.lastPlan.appliedAt} (${report.lastPlan.appliedBy || "unknown"})`,
+        )
+      }
+      for (const lag of report.lag) {
+        const state =
+          lag.missing === 0
+            ? `caught up to ${lag.doneUpTo}`
+            : `behind by ${lag.missing} interval(s), caught up to ${lag.doneUpTo ?? "—"}`
+        const failed = lag.failed > 0 ? `  ⚠ failed intervals: ${lag.failed}` : ""
+        yield* Console.log(`  ${lag.missing === 0 ? "✓" : "…"} ${lag.model}  ${state}${failed}`)
+      }
+      if (report.ticks.length === 0) {
+        yield* Console.log("no run ticks yet")
+      } else {
+        yield* Console.log("recent run ticks:")
+        for (const tick of report.ticks) {
+          const mark = tick.outcome === "ok" ? "✓" : tick.outcome === "error" ? "✗" : "…"
+          const ms = Date.parse(tick.finishedAt) - Date.parse(tick.startedAt)
+          yield* Console.log(
+            `  ${mark} ${tick.startedAt}  ${tick.outcome} (${ms} ms)${tick.detail !== "" ? `  ${tick.detail}` : ""}`,
+          )
+        }
+      }
+    }),
+).pipe(
+  Command.withDescription("what is happening in an environment: promotion, lag, run ticks"),
+)
 
 const auditCommand = Command.make(
   "audit",
@@ -390,25 +720,37 @@ const auditCommand = Command.make(
     config: configFlag,
     model: Flag.string("model").pipe(
       Flag.withDefault(""),
-      Flag.withDescription("Только эти модели, через запятую (по умолчанию — все с аудитами)"),
+      Flag.withDescription("only these models, comma-separated (default — all with audits)"),
     ),
+    json: jsonFlag,
   },
-  ({ config, env, model }) =>
+  ({ config, env, model, json }) =>
     Effect.gen(function* () {
       const loaded = yield* loadConfig(config)
       const only = parseForwardOnly(model)
       const report = yield* auditEnvironment(env, loaded.models, only).pipe(
         Effect.provide(configLayers(loaded)),
       )
+      if (json) {
+        // the whole report; the blocking-based exit code is preserved — stdout is pure JSON
+        yield* printJson(report)
+        if (report.blockingViolations > 0) {
+          return yield* new EnvironmentAuditError({
+            env,
+            blockingViolations: report.blockingViolations,
+          })
+        }
+        return
+      }
       if (report.results.length === 0) {
-        yield* Console.log("аудитов нет — нечего проверять")
+        yield* Console.log("no audits — nothing to check")
         return
       }
       for (const result of report.results) {
         const mark = result.violations === 0 ? "✓" : result.blocking ? "✗" : "⚠"
         const tail =
           result.violations > 0
-            ? `  ${result.violations} нарушений${result.blocking ? "" : " (warn)"}`
+            ? `  ${result.violations} violations${result.blocking ? "" : " (warn)"}`
             : ""
         yield* Console.log(`  ${mark} ${result.model}  ${result.audit}${tail}`)
       }
@@ -418,10 +760,10 @@ const auditCommand = Command.make(
           blockingViolations: report.blockingViolations,
         })
       }
-      yield* Console.log(`blocking-аудиты окружения «${env}» чисты`)
+      yield* Console.log(`blocking audits of environment "${env}" are clean`)
     }),
 ).pipe(
-  Command.withDescription("Прогнать аудиты по view-слою окружения, ничего не меняя"),
+  Command.withDescription("run audits over an environment's view layer, changing nothing"),
 )
 
 const migrateCommand = Command.make(
@@ -435,14 +777,14 @@ const migrateCommand = Command.make(
         : migrateSqliteState({ path: loaded.state?.path ?? "efmesh.state.sqlite" }))
       yield* Console.log(
         report.from === report.to
-          ? `state store уже на версии ${report.to}`
-          : `state store: версия ${report.from} → ${report.to}`,
+          ? `state store already at version ${report.to}`
+          : `state store: version ${report.from} → ${report.to}`,
       )
       if (report.backup !== undefined) {
-        yield* Console.log(`копия старого стора: ${report.backup}`)
+        yield* Console.log(`backup of the old store: ${report.backup}`)
       }
     }),
-).pipe(Command.withDescription("Догнать схему state store до текущей версии"))
+).pipe(Command.withDescription("bring the state store schema up to the current version"))
 
 const graphCommand = Command.make(
   "graph",
@@ -450,7 +792,7 @@ const graphCommand = Command.make(
     config: configFlag,
     html: Flag.string("html").pipe(
       Flag.withDefault(""),
-      Flag.withDescription("Записать DAG самодостаточной HTML-страницей по указанному пути"),
+      Flag.withDescription("write the DAG as a self-contained HTML page at the given path"),
     ),
   },
   ({ config, html }) =>
@@ -459,7 +801,7 @@ const graphCommand = Command.make(
       const graph = yield* buildGraph(loaded.models)
       if (html !== "") {
         yield* Effect.sync(() => writeFileSync(html, renderGraphHtml(graph)))
-        yield* Console.log(`DAG записан: ${html}`)
+        yield* Console.log(`DAG written: ${html}`)
         return
       }
       for (const name of graph.order) {
@@ -468,7 +810,7 @@ const graphCommand = Command.make(
         yield* Console.log(`${name} (${model.kind._tag})${deps}`)
       }
     }),
-).pipe(Command.withDescription("DAG моделей в топологическом порядке (или --html файл)"))
+).pipe(Command.withDescription("the model DAG in topological order (or an --html file)"))
 
 const lineageCommand = Command.make(
   "lineage",
@@ -480,14 +822,14 @@ const lineageCommand = Command.make(
       if (segments.length < 2) {
         return yield* new LineageError({
           model: target,
-          reason: "ожидается <схема>.<таблица>[.<колонка>]",
+          reason: "expected <schema>.<table>[.<column>]",
         })
       }
       const modelName = `${segments[0]}.${segments[1]}`
       const graph = yield* buildGraph(loaded.models)
       const model = graph.models.get(modelName)
       if (model === undefined) {
-        return yield* new LineageError({ model: modelName, reason: "модели нет в проекте" })
+        return yield* new LineageError({ model: modelName, reason: "model is not in the project" })
       }
       const columns =
         segments.length >= 3 ? [segments.slice(2).join(".")] : Object.keys(model.schema.fields)
@@ -498,20 +840,98 @@ const lineageCommand = Command.make(
         for (const line of formatLineage(tree)) yield* Console.log(line)
       }
     }),
-).pipe(Command.withDescription("Колоночный lineage до сырьевых колонок (best-effort)"))
+).pipe(Command.withDescription("column lineage down to raw columns (best-effort)"))
+
+/**
+ * Actionable next step for a failure, when one exists — the recipe the
+ * `schedule` command already prints for a missing cron daemon, generalized to
+ * every error that has one obvious cure (#13). No entry ⇒ the message already
+ * says everything; we do not invent filler advice.
+ */
+const FAILURE_HINTS: Readonly<Record<string, (error: Record<string, unknown>) => string>> = {
+  StateSchemaError: () => "run `efmesh migrate` to bring the state store up to date",
+  FingerprintVersionError: () => "run `efmesh migrate` or upgrade efmesh, then re-apply",
+  LockHeldError: (error) =>
+    `wait for the other apply/run to finish, or clear the stale lock «${String(error["name"])}»`,
+  LakeNotConfiguredError: () => "add `lake: { path: … }` to efmesh.config.ts",
+  DucklakeNotConfiguredError: () => "add `ducklake: { catalog: … }` to efmesh.config.ts",
+  AttachNotConfiguredError: (error) =>
+    `add «${String(error["attach"])}» to \`attach\` in efmesh.config.ts`,
+  ConfigLoadError: () =>
+    "check the --config path and that it default-exports defineConfig({ … })",
+  RunBlockedByChangesError: (error) => `run \`efmesh apply ${String(error["env"])}\``,
+}
+
+/** First line of a rendered failure: the tag names the class, the message the culprit + cause. */
+const errorHeadline = (error: unknown): string => {
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    const record = error as Record<string, unknown>
+    const message = record["message"]
+    const detail = typeof message === "string" && message !== "" ? message : "(no detail)"
+    return `${String(record["_tag"])}: ${detail}`
+  }
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message !== "" ? error.message : "(no detail)"}`
+  }
+  return String(error)
+}
+
+/**
+ * The single failure renderer (#13): cause first (the tagged error's derived
+ * message names the culprit), an actionable hint where one exists, and the
+ * Effect fiber trace ONLY under `--log-level debug` — an operator or agent
+ * sees one screen with the real cause, not a stack over an empty message. The
+ * exit code stays a frozen contract (0/1/2): the caller sets it, not this.
+ */
+export const renderFailure = (
+  cause: Cause.Cause<unknown>,
+  options?: { readonly debug?: boolean },
+): string => {
+  const error = Cause.squash(cause)
+  const lines = [errorHeadline(error)]
+  const tag =
+    typeof error === "object" && error !== null && "_tag" in error
+      ? String((error as Record<string, unknown>)["_tag"])
+      : ""
+  const hint = FAILURE_HINTS[tag]?.(error as Record<string, unknown>)
+  if (hint !== undefined) lines.push(`  → ${hint}`)
+  if (options?.debug === true) {
+    lines.push("", "── trace (--log-level debug) ──", Cause.pretty(cause))
+  } else {
+    lines.push("  (re-run with --log-level debug for the full trace)")
+  }
+  return lines.join("\n")
+}
+
+/**
+ * Whether the run asked for the full trace. Reused from the already-parsed
+ * global `--log-level` flag (values trace/debug/all mean "show me everything")
+ * so there is one knob, not a second bespoke verbosity flag.
+ */
+export const wantsTrace = (argv: ReadonlyArray<string>): boolean => {
+  const verbose = new Set(["trace", "debug", "all"])
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index]!
+    if (arg.startsWith("--log-level=")) return verbose.has(arg.slice("--log-level=".length))
+    if (arg === "--log-level") return verbose.has((argv[index + 1] ?? "").toLowerCase())
+  }
+  return false
+}
 
 export const rootCommand = Command.make("efmesh").pipe(
-  Command.withDescription("sqlmesh на bun, typescript и Effect"),
+  Command.withDescription("sqlmesh on bun, typescript and Effect"),
   Command.withSubcommands([
     initCommand,
     planCommand,
     applyCommand,
     runCommand,
+    statusCommand,
     auditCommand,
     renderCommand,
     graphCommand,
     lineageCommand,
     diffCommand,
+    scheduleCommand,
     janitorCommand,
     migrateCommand,
   ]),