@avytheone/efmesh 0.1.0-beta.2 → 0.2.1

package/src/plan/run.ts

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

package/src/plan/schedule.ts

@@ -0,0 +1,217 @@
+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): 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).
+ *
+ * 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
+  }
+}
+
+/** Everything the worker needs, as absolute paths (crontab has no cwd). */
+export interface ScheduleTarget {
+  /** 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 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, "-")
+
+/** 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 binary of this same package — the worker calls it without guessing npm names. */
+const binPath = (): string => fileURLToPath(new URL("../bin.ts", import.meta.url))
+
+/**
+ * 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 => `// generated by \`efmesh schedule\` — do not edit: re-registration overwrites it
+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 nicknames → systemd OnCalendar; arbitrary expressions are not translated. */
+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 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,
+  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 = "awaiting a human" (apply needed) — deliberately a unit failure: visible in alerts
+`,
+    timer: `[Unit]
+Description=efmesh run ${target.env} — timer
+
+[Timer]
+OnCalendar=${calendar ?? `hourly  # TODO: translate "${cron}" into OnCalendar by hand`}
+Persistent=true
+
+[Install]
+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: `cannot parse cron expression "${cron}"` }),
+    })
+    if (next === null) {
+      return yield* new ScheduleError({
+        reason: `cron expression "${cron}" will never fire`,
+      })
+    }
+  })
+
+/** 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:
+        "this machine has no crontab (the Arch family ships no cron daemon): " +
+        "install cronie OR use a systemd timer — 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: `config not found: ${target.config}` })
+    }
+    const worker = workerPath(target)
+    yield* Effect.try({
+      try: () => {
+        mkdirSync(dirname(worker), { recursive: true })
+        writeFileSync(worker, workerSource(target))
+      },
+      catch: (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 did not register: ${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)}` }),
+    })
+    // the worker is no longer executed by anyone — clean it up silently
+    yield* Effect.sync(() => rmSync(workerPath(target), { force: true }))
+    return { title }
+  })
+
+/**
+ * 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* () {
+    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 // an empty crontab exits with 1 — that is not an error
+          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: `list on ${process.platform} via the OS tools (Task Scheduler: schtasks /query)`,
+    })
+  })

package/src/plan/status.ts

@@ -0,0 +1,96 @@
+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): 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
+  /** End of the last done interval (ISO); null — nothing computed yet. */
+  readonly doneUpTo: string | null
+  /** How many intervals are missing up to «now». 0 — caught up. */
+  readonly missing: number
+  /** Intervals marked failed — a stuck backfill is visible at once. */
+  readonly failed: number
+}
+
+export interface StatusReport {
+  readonly env: string
+  readonly storeVersion: number
+  /** Rows in the environment; 0 — the environment does not exist (never applied). */
+  readonly models: number
+  /** Last promotion (ISO); null — no environment. */
+  readonly promotedAt: string | null
+  readonly lastPlan: PlanRecord | null
+  /** Latest run ticks, freshest first. */
+  readonly ticks: ReadonlyArray<RunRecord>
+  /** Lag of the environment's incremental models. */
+  readonly lag: ReadonlyArray<ModelLag>
+}
+
+export interface StatusOptions {
+  /** «Now» for computing lag; by default — Clock. Injected for tests. */
+  readonly now?: number
+  /** How many latest ticks to show; by default 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)
+
+    // 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)
+      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,
+    }
+  })

package/src/state/postgres.ts

@@ -5,17 +5,18 @@ import type {
   IntervalRecord,
   MigrationReport,
   PlanRecord,
+  RunRecord,
   SnapshotRecord,
   StateStoreShape,
 } from "./store.ts"
 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 = `
@@ -54,6 +55,18 @@ CREATE TABLE IF NOT EXISTS efmesh_state.intervals (
   updated_at  TEXT NOT NULL,
   PRIMARY KEY (snapshot_fp, start_ts)
 );
+CREATE TABLE IF NOT EXISTS efmesh_state.runs (
+  id          INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  env         TEXT NOT NULL,
+  started_at  TEXT NOT NULL,
+  finished_at TEXT NOT NULL,
+  outcome     TEXT NOT NULL,
+  detail      TEXT NOT NULL DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS efmesh_state.canon_cache (
+  key       TEXT PRIMARY KEY,
+  canonical TEXT NOT NULL
+);
 CREATE TABLE IF NOT EXISTS efmesh_state.locks (
   name        TEXT PRIMARY KEY,
   acquired_at TEXT NOT NULL,
@@ -62,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
 }
 
@@ -75,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(
@@ -84,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(`
@@ -101,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> =>
@@ -140,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 }),
@@ -177,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)
@@ -271,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(
@@ -281,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`,
                       )
                     }
                   }
@@ -293,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
@@ -331,6 +344,42 @@ export const PostgresStateLive = (
             )) as ReadonlyArray<PlanRecord>
           }),
 
+        getCanon: (key) =>
+          attempt("getCanon", async () => {
+            const rows = (await sql.unsafe(
+              `SELECT canonical FROM efmesh_state.canon_cache WHERE key = $1`,
+              [key],
+            )) as ReadonlyArray<{ canonical: string }>
+            return rows[0]?.canonical
+          }),
+
+        putCanon: (key, canonical) =>
+          attempt("putCanon", async () => {
+            await sql.unsafe(
+              `INSERT INTO efmesh_state.canon_cache (key, canonical) VALUES ($1, $2)
+               ON CONFLICT (key) DO NOTHING`,
+              [key, canonical],
+            )
+          }),
+
+        recordRun: (record) =>
+          attempt("recordRun", async () => {
+            await sql.unsafe(
+              `INSERT INTO efmesh_state.runs (env, started_at, finished_at, outcome, detail)
+               VALUES ($1, $2, $3, $4, $5)`,
+              [record.env, record.startedAt, record.finishedAt, record.outcome, record.detail],
+            )
+          }),
+
+        listRuns: (env, limit) =>
+          attempt("listRuns", async () => {
+            return (await sql.unsafe(
+              `SELECT id, env, started_at AS "startedAt", finished_at AS "finishedAt", outcome, detail
+               FROM efmesh_state.runs WHERE env = $1 ORDER BY id DESC LIMIT $2`,
+              [env, limit],
+            )) as ReadonlyArray<RunRecord>
+          }),
+
         acquireLock: (name, ttlMs) =>
           Clock.currentTimeMillis.pipe(
             Effect.flatMap((nowMs) =>
@@ -338,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],