@avytheone/efmesh 0.1.0-beta.2 → 0.2.1

package/src/plan/explain.ts

@@ -0,0 +1,114 @@
+/**
+ * Categorization explanation (#4, SPEC §5.2): `plan --explain` shows WHICH
+ * nodes of the canonical AST diverged and why the category is what it is.
+ * Paths follow the engine's canon tree (json_serialize_sql on DuckDB,
+ * libpg_query on Postgres) — this is a debugging hint, not a contract:
+ * the shape of the paths moves with the canon and is not a semver event.
+ * The category itself is computed by categorize.ts; here — only its rationale.
+ */
+
+import { topSelect } from "./categorize.ts"
+
+export interface ChangeExplanation {
+  /** Paths of diverged canonical-AST nodes (no more than MAX_DIVERGED). */
+  readonly diverged: ReadonlyArray<string>
+  /** Why the category is what it is. */
+  readonly reason: string
+  /** Changed direct parents — the source of the indirect/forward-only cascade. */
+  readonly cascadeFrom?: ReadonlyArray<string>
+}
+
+/** Beyond this, pointwise paths stop helping — better to open render/diff. */
+const MAX_DIVERGED = 8
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const at = (path: string, segment: string): string =>
+  path === "" ? segment : `${path}.${segment}`
+
+const walk = (before: unknown, after: unknown, path: string, out: Array<string>): void => {
+  if (out.length >= MAX_DIVERGED) return
+  if (JSON.stringify(before) === JSON.stringify(after)) return
+  if (Array.isArray(before) && Array.isArray(after)) {
+    const shared = Math.min(before.length, after.length)
+    for (let i = 0; i < shared; i++) walk(before[i], after[i], `${path}[${i}]`, out)
+    for (let i = shared; i < after.length && out.length < MAX_DIVERGED; i++) {
+      out.push(`${path}[${i}] (added)`)
+    }
+    for (let i = shared; i < before.length && out.length < MAX_DIVERGED; i++) {
+      out.push(`${path}[${i}] (removed)`)
+    }
+    return
+  }
+  if (isRecord(before) && isRecord(after)) {
+    // node replaced by an expression of another type — pointwise paths inside are meaningless
+    if (before["type"] !== after["type"]) {
+      out.push(path === "" ? "(root)" : path)
+      return
+    }
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()
+    for (const key of keys) walk(before[key], after[key], at(path, key), out)
+    return
+  }
+  out.push(path === "" ? "(root)" : path)
+}
+
+/** The statement's boilerplate wrapper in the path is uninteresting — trim to the query body. */
+const trimStatement = (path: string): string =>
+  path.replace(/^statements\[0\]\.node\.?/, "").replace(/^stmts\[0\]\.stmt\.?/, "") ||
+  "(root)"
+
+/** Divergence paths of two canonical ASTs (JSON strings); garbage input — empty. */
+export const divergedPaths = (oldAst: string, newAst: string): ReadonlyArray<string> => {
+  try {
+    const out: Array<string> = []
+    walk(JSON.parse(oldAst), JSON.parse(newAst), "", out)
+    return out.map(trimStatement)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Override guardrail (#5): the new top SELECT has fewer columns — they were
+ * removed, descendants read them by name, so «non-breaking» plainly contradicts
+ * the AST. An unparseable canon does not count as a contradiction: the decision
+ * is the operator's, the override is explicit and journaled.
+ */
+export const dropsColumns = (oldAst: string, newAst: string): boolean => {
+  const before = topSelect(oldAst)
+  const after = topSelect(newAst)
+  if (before === null || after === null) return false
+  return after.list.length < before.list.length
+}
+
+/**
+ * Justifies the categorizeAstChange verdict by the same rules that produced
+ * it (SPEC §5.2): non-breaking — only a suffix of the top SELECT.
+ */
+export const explainCategorized = (
+  oldAst: string,
+  newAst: string,
+  change: "breaking" | "non-breaking",
+): ChangeExplanation => {
+  const diverged = divergedPaths(oldAst, newAst)
+  if (change === "non-breaking") {
+    return {
+      diverged,
+      reason:
+        "columns were appended to the end of the top SELECT, the rest of the tree is untouched — consumers read by name, no rebuild needed",
+    }
+  }
+  const before = topSelect(oldAst)
+  const after = topSelect(newAst)
+  const reason =
+    before === null || after === null
+      ? "canonical AST of an unexpected shape — conservatively breaking"
+      : before.rest !== after.rest
+        ? "the tree diverged outside the SELECT list (FROM/WHERE/JOIN/GROUP BY/modifiers)"
+        : after.list.length < before.list.length
+          ? "columns were removed from SELECT — descendants insert by position, physics must be rebuilt"
+          : "the SELECT list changed not only at its tail — editing or reordering columns breaks descendants' positions"
+  return { diverged, reason }
+}

package/src/plan/fingerprint.ts

@@ -9,24 +9,26 @@ import type { EngineError, SqlParseError } from "../engine/adapter.ts"
 import { EngineAdapter } from "../engine/adapter.ts"
 
 /**
- * Fingerprint снапшота (SPEC §4): хэш канонизированного AST (родной парсер
- * движка, переформатирование запроса fingerprint не меняет), метаданных,
- * влияющих на данные, и fingerprint'ов прямых зависимостей (транзитивность).
+ * Snapshot fingerprint (SPEC §4): hash of the canonicalized AST (engine's
+ * native parser — reformatting a query does not change the fingerprint),
+ * of the metadata that affects data, and of the fingerprints of direct
+ * dependencies (transitivity).
  *
- * `batchSize`, `lookback`, `start` и `description` в fingerprint не входят:
- * они меняют исполнение или объём истории, но не форму данных — недостающие
- * интервалы учёт увидит сам.
+ * `batchSize`, `lookback`, `start` and `description` do not enter the
+ * fingerprint: they change execution or the amount of history, not the shape
+ * of the data — the interval ledger will notice missing intervals on its own.
  */
 
 /**
- * Версия алгоритма fingerprint — КОНТРАКТ (SPEC §4). Fingerprint зависит от
- * канонизации движка (json_serialize_sql DuckDB / libpg_query) и состава
- * payload ниже: любое их изменение молча пере-фингерпринтит все модели
- * пользователя и вынуждает полный ребилд склада. Поэтому: (1) канонизация
- * заморожена golden-тестами (test/fingerprint-golden.test.ts) — красный
- * тест при апгрейде DuckDB/libpg_query означает дрейф канона; (2) осознанная
- * смена алгоритма = инкремент этой константы + история миграции, снапшоты
- * другой версии план не сравнивает, а честно останавливается.
+ * Fingerprint algorithm version — a CONTRACT (SPEC §4). The fingerprint
+ * depends on the engine canonicalization (DuckDB json_serialize_sql /
+ * libpg_query) and on the composition of the payload below: any change to
+ * them silently re-fingerprints all of a user's models and forces a full
+ * rebuild of the warehouse. Therefore: (1) canonicalization is frozen by
+ * golden tests (test/fingerprint-golden.test.ts) — a red test on a
+ * DuckDB/libpg_query upgrade means canon drift; (2) a deliberate change of
+ * algorithm = increment of this constant + a migration history; the plan does
+ * not compare snapshots of a different version, it honestly stops instead.
  */
 export const FINGERPRINT_VERSION = 1
 
@@ -36,14 +38,16 @@ const sha256 = (input: string): string => {
   return hasher.digest("hex")
 }
 
-/** Canonical-рендер: ссылки — логические имена, границы — плейсхолдеры $start/$end. */
+/** Canonical render: refs are logical names, bounds are $start/$end placeholders. */
 export const canonicalSql = (graph: ModelGraph, name: string): string => {
   const model = graph.models.get(name)
-  if (model === undefined) throw new Error(`модели ${name} нет в графе`)
+  // invariant: callers pass a name already known to the graph (the facade
+  // guards user input with UnknownModelError before reaching here)
+  if (model === undefined) throw new Error(`invariant violated: model «${name}» is not in the graph`)
   return render(model.fragment, { resolveRef: (ref) => ref })
 }
 
-/** Часть kind, влияющая на данные. Для seed — хэш содержимого файла: правка данных = новая версия. */
+/** Part of kind that affects data. For seed — hash of the file contents: editing the data = a new version. */
 const kindPayload = (
   model: { readonly name: { readonly full: string } },
   kind: ModelKind,
@@ -85,13 +89,61 @@ const kindPayload = (
 
 export interface ModelVersion {
   readonly fingerprint: string
-  /** Канонический AST тела; null у external. Хранится в снапшоте для категоризации (§5.2). */
+  /** Canonical AST of the body; null for external. Stored in the snapshot for categorization (§5.2). */
   readonly ast: string | null
 }
 
-/** Fingerprint всех моделей графа; транзитивность — через хэши родителей. */
+/**
+ * Canonicalization cache (#8): a repeated plan consists almost entirely of
+ * json_serialize_sql round-trips over unchanged models. The cache is not
+ * data: get/put must be infallible (a miss/failure = recompute).
+ */
+export interface CanonCache {
+  readonly get: (key: string) => Effect.Effect<string | undefined>
+  readonly put: (key: string, canonical: string) => Effect.Effect<void>
+}
+
+/** Cache key: algorithm version + dialect + source — a canon upgrade is not masked. */
+export const canonCacheKey = (dialect: string, source: string): string =>
+  sha256(`${FINGERPRINT_VERSION}:${dialect}:${source}`)
+
+/** The model in the scope the fingerprint needs: kind, data-shape metadata, target. */
+type FingerprintableModel = Parameters<typeof columnNames>[0] & {
+  readonly name: { readonly full: string }
+  readonly kind: ModelKind
+  readonly grain: ReadonlyArray<string> | undefined
+  readonly target: string | undefined
+}
+
+/**
+ * Fingerprint of a single model from a ready AST and parent signatures
+ * (`name=fingerprint`, sorted). The planner needs it to check the
+ * "version shifted by parents ONLY" case (#5): a recompute with the old
+ * signatures must yield the old fingerprint — otherwise the metadata diverged
+ * too, and the physics cannot be reused.
+ */
+export const modelFingerprint = (
+  model: FingerprintableModel,
+  ast: string | null,
+  parents: ReadonlyArray<string>,
+): Effect.Effect<string, SeedReadError> =>
+  Effect.gen(function* () {
+    const payload = JSON.stringify({
+      ast,
+      kind: yield* kindPayload(model, model.kind),
+      grain: model.grain,
+      columns: columnNames(model),
+      // a change of materialization target = new physics, consumers re-read it
+      target: model.target,
+      parents,
+    })
+    return sha256(payload)
+  })
+
+/** Fingerprint of all models in the graph; transitivity via parent hashes. */
 export const fingerprintGraph = (
   graph: ModelGraph,
+  cache?: CanonCache,
 ): Effect.Effect<
   ReadonlyMap<string, ModelVersion>,
   EngineError | SqlParseError | SeedReadError,
@@ -99,27 +151,28 @@ export const fingerprintGraph = (
 > =>
   Effect.gen(function* () {
     const engine = yield* EngineAdapter
+    const canonicalize = (source: string): Effect.Effect<string, EngineError | SqlParseError> =>
+      Effect.gen(function* () {
+        if (cache === undefined) return yield* engine.canonicalize(source)
+        const key = canonCacheKey(engine.dialect, source)
+        const hit = yield* cache.get(key)
+        if (hit !== undefined) return hit
+        const canon = yield* engine.canonicalize(source)
+        yield* cache.put(key, canon)
+        return canon
+      })
     const versions = new Map<string, ModelVersion>()
     for (const name of graph.order) {
       const model = graph.models.get(name)!
-      // у external и seed нет SQL — версия определяется источником/файлом и схемой
+      // external and seed have no SQL — the version is determined by source/file and schema
       const ast =
         model.kind._tag === "external" || model.kind._tag === "seed"
           ? null
-          : yield* engine.canonicalize(canonicalSql(graph, name))
+          : yield* canonicalize(canonicalSql(graph, name))
       const parents = [...model.deps]
         .sort()
         .map((dep) => `${dep}=${versions.get(dep)!.fingerprint}`)
-      const payload = JSON.stringify({
-        ast,
-        kind: yield* kindPayload(model, model.kind),
-        grain: model.grain,
-        columns: columnNames(model),
-        // смена цели материализации = новая физика, потребители перечитают её
-        target: model.target,
-        parents,
-      })
-      versions.set(name, { fingerprint: sha256(payload), ast })
+      versions.set(name, { fingerprint: yield* modelFingerprint(model, ast, parents), ast })
     }
     return versions
   })

package/src/plan/graph-html.ts

@@ -1,9 +1,9 @@
 import type { ModelGraph } from "../core/graph.ts"
 
 /**
- * `efmesh graph --html` (SPEC §11): самодостаточная страница с DAG моделей —
- * SVG без внешних зависимостей, слои по длиннейшему пути от корней,
- * рёбра — кривые Безье, подсветка соседей по наведению.
+ * `efmesh graph --html` (SPEC §11): a self-contained page with the model DAG —
+ * SVG with no external dependencies, layers by the longest path from the
+ * roots, edges are Bézier curves, neighbors highlighted on hover.
  */
 
 const KIND_COLOR: Record<string, string> = {
@@ -27,7 +27,7 @@ const ROW_GAP = 26
 const PAD = 32
 
 export const renderGraphHtml = (graph: ModelGraph): string => {
-  // слой = длиннейший путь от корней: родители всегда левее потомков
+  // layer = longest path from the roots: parents are always left of descendants
   const depth = new Map<string, number>()
   for (const name of graph.order) {
     const model = graph.models.get(name)!
@@ -99,10 +99,10 @@ export const renderGraphHtml = (graph: ModelGraph): string => {
     .join("")
 
   return `<!doctype html>
-<html lang="ru">
+<html lang="en">
 <head>
 <meta charset="utf-8">
-<title>efmesh — DAG моделей</title>
+<title>efmesh — model DAG</title>
 <style>
   :root { color-scheme: light dark; }
   body { font: 14px/1.4 system-ui, sans-serif; margin: 0; padding: 16px;
@@ -124,7 +124,7 @@ export const renderGraphHtml = (graph: ModelGraph): string => {
 </style>
 </head>
 <body>
-<h1>efmesh — DAG моделей</h1>
+<h1>efmesh — model DAG</h1>
 <div class="legend">${legend}</div>
 <svg id="dag" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
 ${edges.join("\n")}

package/src/plan/janitor.ts

@@ -9,32 +9,32 @@ import { janitorLockName, withStateLock, type LockHeldError, type LockOptions }
 import { ducklakeAttachSql, ducklakeRef, parquetPrefix, physicalRef } from "./naming.ts"
 
 /**
- * Уборка осиротевшей физики (SPEC §5.4): снапшоты, на которые не ссылается
- * ни одно окружение и которые осиротели раньше, чем ttl назад, сносятся —
- * таблица/view движка, parquet-префикс озера, запись снапшота и учёт
- * интервалов.
+ * Cleanup of orphaned physical storage (SPEC §5.4): snapshots referenced by
+ * no environment and orphaned longer than ttl ago are removed — the engine
+ * table/view, the lake parquet prefix, the snapshot record and the interval
+ * bookkeeping.
  *
- * ttl отсчитывается от orphaned_at — отметки, которую промоушен ставит
- * при потере последней ссылки и снимает при возврате (откат на старую
- * версию обнуляет счётчик). Для записей без отметки (ни разу не
- * промоутились — например, apply упал до промоушена) — от created_at.
- * ttl по умолчанию 7 дней — достаточно, чтобы мгновенно откатиться
- * переключением view.
+ * ttl is measured from orphaned_at — the mark a promotion sets when the last
+ * reference is lost and clears on return (rolling back to an old version
+ * resets the counter). For records without the mark (never promoted — e.g.
+ * an apply that crashed before promotion) — from created_at.
+ * ttl defaults to 7 days — enough to roll back instantly by switching the
+ * view.
  */
 
 export interface JanitorOptions extends LockOptions {
   readonly ttlDays?: number
   readonly lakePath?: string
-  /** DuckLake-каталог (SPEC §14.5) — чтобы снести и таблицы-на-fingerprint в нём. */
+  /** DuckLake catalog (SPEC §14.5) — to also drop the fingerprint tables inside it. */
   readonly ducklake?: { readonly catalog: string; readonly dataPath?: string }
-  /** «Сейчас» — инъекция для тестов. */
+  /** «Now» — injected for tests. */
   readonly now?: number
 }
 
 export interface JanitorReport {
-  /** Снесённые снапшоты в виде `имя@fp8`. */
+  /** Removed snapshots as `name@fp8`. */
   readonly removed: ReadonlyArray<string>
-  /** Осиротевшие, но моложе ttl — остаются до следующего раза. */
+  /** Orphaned but younger than ttl — kept until next time. */
   readonly kept: ReadonlyArray<string>
 }
 
@@ -53,8 +53,9 @@ export const janitor = (
     const now = options?.now ?? (yield* Clock.currentTimeMillis)
     const ttlMs = (options?.ttlDays ?? 7) * DAY_MS
 
-    // снапшот не хранит цель материализации — при настроенном каталоге
-    // таблица сносится и там, и в _efmesh (DROP IF EXISTS терпим к пустоте)
+    // a snapshot does not store its materialization target — with a catalog
+    // configured, the table is dropped both there and in _efmesh (DROP IF EXISTS
+    // tolerates absence)
     const ducklake = options?.ducklake
     if (ducklake !== undefined && engine.dialect === "duckdb") {
       yield* engine.execute(ducklakeAttachSql(ducklake))
@@ -70,10 +71,11 @@ export const janitor = (
       !referenced.has(snapshot.fingerprint) &&
       (snapshot.orphanedAt ?? snapshot.createdAt) <= deadline
 
-    // фаза 1 — транзакционный claim записей: снос состоится, только если
-    // снапшот ВСЁ ЕЩЁ не referenced и сирота (проверки атомарны с удалением);
-    // параллельный apply, воскресивший версию (upsert снимает orphaned_at),
-    // claim проиграет — и её физика не тронется (гонка F6)
+    // phase 1 — transactional claim of records: removal happens only if the
+    // snapshot is STILL not referenced and an orphan (the checks are atomic
+    // with the delete); against a parallel apply that resurrected the version
+    // (upsert clears orphaned_at) the claim loses — and its physical storage
+    // is left untouched (F6 race)
     const claimed: Array<(typeof snapshots)[number]> = []
     for (const snapshot of snapshots) {
       if (referenced.has(snapshot.fingerprint)) continue
@@ -95,9 +97,9 @@ export const janitor = (
       removed.push(label)
     }
 
-    // фаза 2 — снос физики по СВЕЖЕМУ состоянию стора: физика делится между
-    // версиями (forward-only) и сносится, только если после claim'ов её не
-    // использует ни один выживший снапшот
+    // phase 2 — drop physical storage by the FRESH store state: storage is
+    // shared between versions (forward-only) and dropped only if, after the
+    // claims, no surviving snapshot uses it
     const survivors = yield* store.listSnapshots()
     const physicalInUse = new Set(survivors.map((snapshot) => snapshot.physicalFp))
     const dropped = new Set<string>()
@@ -106,6 +108,9 @@ export const janitor = (
       dropped.add(snapshot.physicalFp)
       const name = parseModelName(snapshot.name)
       const target = physicalRef(name, snapshot.physicalFp)
+      yield* Effect.logDebug("dropping orphaned physics").pipe(
+        Effect.annotateLogs({ model: snapshot.name, physical: snapshot.physicalFp.slice(0, 8) }),
+      )
       yield* engine.execute(
         snapshot.kind === "view"
           ? `DROP VIEW IF EXISTS ${target}`
@@ -124,7 +129,7 @@ export const janitor = (
 
     return { removed, kept }
   }).pipe(
-    // два janitor'а из разных процессов не должны наперегонки сносить одно и
-    // то же; от гонки janitor↔apply защищает ttl (окно на мгновенный откат)
+    // two janitors from different processes must not race to remove the same
+    // thing; the janitor↔apply race is guarded by ttl (the window for an instant rollback)
     withStateLock(janitorLockName, options?.lockTtlMs),
   )

package/src/plan/lineage.ts

@@ -6,28 +6,32 @@ import { EngineAdapter } from "../engine/adapter.ts"
 import { canonicalSql } from "./fingerprint.ts"
 
 /**
- * Колоночный lineage (SPEC §9.4): цепочка от колонки модели до сырьевых
- * колонок external/seed-моделей. Точность best-effort — выражение колонки
- * берётся из канонического AST (родной парсер движка), ссылки на колонки
- * сопоставляются схемам родителей по имени, квалификаторы и алиасы CTE
- * не разворачиваются. Граф моделей при этом точен всегда: зависимости
- * известны из `ctx.ref`, не из парсинга текста.
+ * Column-level lineage (SPEC §9.4): the chain from a model's column down to
+ * the raw columns of external/seed models. Precision is best-effort — a
+ * column's expression is taken from the canonical AST (the engine's native
+ * parser), column references are matched to parents' schemas by name,
+ * qualifiers and CTE aliases are not resolved. The model graph itself is
+ * always exact: dependencies are known from `ctx.ref`, not from text parsing.
  */
 
 export class LineageError extends Data.TaggedError("LineageError")<{
   readonly model: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `lineage «${this.model}»: ${this.reason}`
+  }
+}
 
 export interface LineageNode {
   readonly model: string
   readonly column: string
-  /** Вид модели — external/seed являются листьями (сырьё). */
+  /** Model kind — external/seed are leaves (raw sources). */
   readonly kind: string
   readonly sources: ReadonlyArray<LineageNode>
 }
 
-/** Все COLUMN_REF в поддереве выражения — имена колонок без квалификаторов. */
+/** All COLUMN_REFs in the expression subtree — column names without qualifiers. */
 const collectColumnRefs = (node: unknown, out: Set<string>): void => {
   if (Array.isArray(node)) {
     for (const item of node) collectColumnRefs(item, out)
@@ -49,9 +53,9 @@ const selectItems = (ast: unknown): ReadonlyArray<Record<string, unknown>> => {
 }
 
 /**
- * Колонки, от которых зависит `column` в select_list: выражение с алиасом
- * или одноимённый COLUMN_REF; `SELECT *` — сквозной проброс имени.
- * undefined — выражение колонки не найдено (движковый сахар) — best-effort.
+ * The columns `column` depends on in select_list: an aliased expression or a
+ * same-named COLUMN_REF; `SELECT *` — a pass-through of the name.
+ * undefined — the column's expression was not found (engine sugar) — best-effort.
  */
 const sourceColumnsOf = (ast: unknown, column: string): ReadonlySet<string> | undefined => {
   const items = selectItems(ast)
@@ -83,12 +87,12 @@ export const lineage = (
     const engine = yield* EngineAdapter
     const root = graph.models.get(modelName)
     if (root === undefined) {
-      return yield* new LineageError({ model: modelName, reason: "модели нет в проекте" })
+      return yield* new LineageError({ model: modelName, reason: "model is not in the project" })
     }
     if (!(column in root.schema.fields)) {
       return yield* new LineageError({
         model: modelName,
-        reason: `колонки «${column}» нет в схеме`,
+        reason: `column «${column}» is not in the schema`,
       })
     }
 
@@ -115,7 +119,7 @@ export const lineage = (
           kind: model.kind._tag,
           sources: [],
         }
-        // сырьё: дальше цепочка упирается во внешний мир
+        // raw source: beyond here the chain hits the outside world
         if (model.kind._tag === "external" || model.kind._tag === "seed" || model.deps.size === 0) {
           return leaf
         }
@@ -134,7 +138,7 @@ export const lineage = (
     return yield* trace(root, column)
   })
 
-/** Плоская печать lineage-дерева для CLI. */
+/** Flat printout of the lineage tree for the CLI. */
 export const formatLineage = (node: LineageNode, indent = ""): ReadonlyArray<string> => {
   const marker =
     node.kind === "external" || node.kind === "seed" ? `  [${node.kind}]` : ""

package/src/plan/lock.ts

@@ -2,26 +2,30 @@ import { Data, Effect } from "effect"
 import { StateStore, type StateError } from "../state/store.ts"
 
 /**
- * Межпроцессная блокировка через state store (SPEC §7, §14.6): мутации
- * окружения — apply и run — идут под ОДНИМ локом `env:<имя>`, поэтому
- * параллельные apply+apply и apply+run из разных процессов отсекаются.
- * Протухший лок упавшего процесса перехватывается по ttl (учтена гонка
- * в ту же миллисекунду: expires_at <= now).
+ * Cross-process lock via the state store (SPEC §7, §14.6): environment
+ * mutations — apply and run — go under ONE lock `env:<name>`, so parallel
+ * apply+apply and apply+run from different processes are cut off. A stale
+ * lock of a crashed process is reclaimed by ttl (the same-millisecond race is
+ * accounted for: expires_at <= now).
  */
 
 export class LockHeldError extends Data.TaggedError("LockHeldError")<{
   readonly name: string
-}> {}
+}> {
+  override get message(): string {
+    return `lock «${this.name}» is held by another apply/run process`
+  }
+}
 
 export interface LockOptions {
-  /** Сколько лок живёт без освобождения (упавший процесс); по умолчанию 1 час. */
+  /** How long the lock lives without being released (crashed process); by default 1 hour. */
   readonly lockTtlMs?: number
 }
 
-/** Имя лока, под которым мутируется окружение (общий для apply и run). */
+/** Name of the lock under which an environment is mutated (shared by apply and run). */
 export const envLockName = (env: string): string => `env:${env}`
 
-/** Лок janitor — глобальный: уборка физики не привязана к окружению. */
+/** The janitor lock is global: physical-storage cleanup is not tied to an environment. */
 export const janitorLockName = "janitor"
 
 export const withStateLock =
@@ -33,5 +37,18 @@ export const withStateLock =
       const store = yield* StateStore
       const acquired = yield* store.acquireLock(name, ttlMs ?? 3_600_000)
       if (!acquired) return yield* new LockHeldError({ name })
-      return yield* effect.pipe(Effect.ensuring(store.releaseLock(name).pipe(Effect.ignore)))
+      // lock lifecycle is an internal detail — DEBUG only, keyed by lock name (#14)
+      yield* Effect.logDebug("lock acquired").pipe(Effect.annotateLogs("lock", name))
+      return yield* effect.pipe(
+        Effect.ensuring(
+          store
+            .releaseLock(name)
+            .pipe(
+              Effect.andThen(
+                Effect.logDebug("lock released").pipe(Effect.annotateLogs("lock", name)),
+              ),
+              Effect.ignore,
+            ),
+        ),
+      )
     })

package/src/plan/metrics.ts

@@ -1,14 +1,14 @@
 import { Metric } from "effect"
 
-/** Наблюдаемость из коробки (SPEC §10): счётчики конвейера. */
+/** Observability out of the box (SPEC §10): pipeline counters. */
 export const intervalsDone = Metric.counter("efmesh_intervals_done_total", {
-  description: "Сколько интервалов досчитано и помечено done",
+  description: "how many intervals were computed and marked done",
 })
 
 export const auditFailuresTotal = Metric.counter("efmesh_audit_failures_total", {
-  description: "Сколько blocking-аудитов провалилось",
+  description: "how many blocking audits failed",
 })
 
 export const snapshotsBuilt = Metric.counter("efmesh_snapshots_built_total", {
-  description: "Сколько снапшотов собрано (физика или бэкфилл)",
+  description: "how many snapshots were built (physics or backfill)",
 })