@avytheone/efmesh 0.1.0-beta.1

package/src/plan/fingerprint.ts

@@ -0,0 +1,125 @@
+import { readFileSync } from "node:fs"
+import { Effect } from "effect"
+import { SeedReadError } from "../core/errors.ts"
+import type { ModelGraph } from "../core/graph.ts"
+import type { ModelKind } from "../core/model.ts"
+import { columnNames } from "../core/model.ts"
+import { render } from "../core/sql.ts"
+import type { EngineError, SqlParseError } from "../engine/adapter.ts"
+import { EngineAdapter } from "../engine/adapter.ts"
+
+/**
+ * Fingerprint снапшота (SPEC §4): хэш канонизированного AST (родной парсер
+ * движка, переформатирование запроса fingerprint не меняет), метаданных,
+ * влияющих на данные, и fingerprint'ов прямых зависимостей (транзитивность).
+ *
+ * `batchSize`, `lookback`, `start` и `description` в fingerprint не входят:
+ * они меняют исполнение или объём истории, но не форму данных — недостающие
+ * интервалы учёт увидит сам.
+ */
+
+/**
+ * Версия алгоритма fingerprint — КОНТРАКТ (SPEC §4). Fingerprint зависит от
+ * канонизации движка (json_serialize_sql DuckDB / libpg_query) и состава
+ * payload ниже: любое их изменение молча пере-фингерпринтит все модели
+ * пользователя и вынуждает полный ребилд склада. Поэтому: (1) канонизация
+ * заморожена golden-тестами (test/fingerprint-golden.test.ts) — красный
+ * тест при апгрейде DuckDB/libpg_query означает дрейф канона; (2) осознанная
+ * смена алгоритма = инкремент этой константы + история миграции, снапшоты
+ * другой версии план не сравнивает, а честно останавливается.
+ */
+export const FINGERPRINT_VERSION = 1
+
+const sha256 = (input: string): string => {
+  const hasher = new Bun.CryptoHasher("sha256")
+  hasher.update(input)
+  return hasher.digest("hex")
+}
+
+/** Canonical-рендер: ссылки — логические имена, границы — плейсхолдеры $start/$end. */
+export const canonicalSql = (graph: ModelGraph, name: string): string => {
+  const model = graph.models.get(name)
+  if (model === undefined) throw new Error(`модели ${name} нет в графе`)
+  return render(model.fragment, { resolveRef: (ref) => ref })
+}
+
+/** Часть kind, влияющая на данные. Для seed — хэш содержимого файла: правка данных = новая версия. */
+const kindPayload = (
+  model: { readonly name: { readonly full: string } },
+  kind: ModelKind,
+): Effect.Effect<unknown, SeedReadError> => {
+  switch (kind._tag) {
+    case "full":
+    case "view":
+    case "embedded":
+      return Effect.succeed({ _tag: kind._tag })
+    case "incrementalByTimeRange":
+      return Effect.succeed({
+        _tag: kind._tag,
+        timeColumn: kind.timeColumn,
+        interval: kind.interval,
+      })
+    case "incrementalByUniqueKey":
+      return Effect.succeed({ _tag: kind._tag, key: kind.key })
+    case "scdType2":
+      return Effect.succeed({
+        _tag: kind._tag,
+        key: kind.key,
+        validFrom: kind.validFrom,
+        validTo: kind.validTo,
+      })
+    case "external":
+      return Effect.succeed({ _tag: kind._tag, source: kind.source })
+    case "seed":
+      return Effect.try({
+        try: () => ({
+          _tag: kind._tag,
+          file: kind.file,
+          contentHash: sha256(readFileSync(kind.file, "utf8")),
+        }),
+        catch: (cause) =>
+          new SeedReadError({ model: model.name.full, file: kind.file, cause }),
+      })
+  }
+}
+
+export interface ModelVersion {
+  readonly fingerprint: string
+  /** Канонический AST тела; null у external. Хранится в снапшоте для категоризации (§5.2). */
+  readonly ast: string | null
+}
+
+/** Fingerprint всех моделей графа; транзитивность — через хэши родителей. */
+export const fingerprintGraph = (
+  graph: ModelGraph,
+): Effect.Effect<
+  ReadonlyMap<string, ModelVersion>,
+  EngineError | SqlParseError | SeedReadError,
+  EngineAdapter
+> =>
+  Effect.gen(function* () {
+    const engine = yield* EngineAdapter
+    const versions = new Map<string, ModelVersion>()
+    for (const name of graph.order) {
+      const model = graph.models.get(name)!
+      // у external и seed нет SQL — версия определяется источником/файлом и схемой
+      const ast =
+        model.kind._tag === "external" || model.kind._tag === "seed"
+          ? null
+          : yield* engine.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 })
+    }
+    return versions
+  })

package/src/plan/graph-html.ts

@@ -0,0 +1,157 @@
+import type { ModelGraph } from "../core/graph.ts"
+
+/**
+ * `efmesh graph --html` (SPEC §11): самодостаточная страница с DAG моделей —
+ * SVG без внешних зависимостей, слои по длиннейшему пути от корней,
+ * рёбра — кривые Безье, подсветка соседей по наведению.
+ */
+
+const KIND_COLOR: Record<string, string> = {
+  external: "#8899aa",
+  seed: "#b08968",
+  view: "#5fa8d3",
+  embedded: "#9d8cd6",
+  full: "#4f772d",
+  incrementalByTimeRange: "#e07a5f",
+  incrementalByUniqueKey: "#d4a373",
+  scdType2: "#c05299",
+}
+
+const escapeHtml = (text: string): string =>
+  text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll(`"`, "&quot;")
+
+const NODE_W = 210
+const NODE_H = 46
+const COL_GAP = 90
+const ROW_GAP = 26
+const PAD = 32
+
+export const renderGraphHtml = (graph: ModelGraph): string => {
+  // слой = длиннейший путь от корней: родители всегда левее потомков
+  const depth = new Map<string, number>()
+  for (const name of graph.order) {
+    const model = graph.models.get(name)!
+    let level = 0
+    for (const dep of model.deps) level = Math.max(level, (depth.get(dep) ?? 0) + 1)
+    depth.set(name, level)
+  }
+  const columns = new Map<number, Array<string>>()
+  for (const name of graph.order) {
+    const level = depth.get(name)!
+    const column = columns.get(level) ?? []
+    column.push(name)
+    columns.set(level, column)
+  }
+
+  const position = new Map<string, { x: number; y: number }>()
+  for (const [level, names] of columns) {
+    names.forEach((name, index) => {
+      position.set(name, {
+        x: PAD + level * (NODE_W + COL_GAP),
+        y: PAD + index * (NODE_H + ROW_GAP),
+      })
+    })
+  }
+  const width = PAD * 2 + columns.size * (NODE_W + COL_GAP) - COL_GAP
+  const height =
+    PAD * 2 +
+    Math.max(...[...columns.values()].map((names) => names.length)) * (NODE_H + ROW_GAP) -
+    ROW_GAP
+
+  const edges: Array<string> = []
+  for (const name of graph.order) {
+    const model = graph.models.get(name)!
+    const to = position.get(name)!
+    for (const dep of model.deps) {
+      const from = position.get(dep)!
+      const x1 = from.x + NODE_W
+      const y1 = from.y + NODE_H / 2
+      const x2 = to.x
+      const y2 = to.y + NODE_H / 2
+      const bend = (x2 - x1) / 2
+      edges.push(
+        `<path class="edge" data-from="${escapeHtml(dep)}" data-to="${escapeHtml(name)}" d="M ${x1} ${y1} C ${x1 + bend} ${y1}, ${x2 - bend} ${y2}, ${x2} ${y2}"/>`,
+      )
+    }
+  }
+
+  const nodes = graph.order.map((name) => {
+    const model = graph.models.get(name)!
+    const { x, y } = position.get(name)!
+    const color = KIND_COLOR[model.kind._tag] ?? "#666"
+    const title =
+      model.description !== undefined ? `${name} — ${model.description}` : name
+    return `<g class="node" data-name="${escapeHtml(name)}" transform="translate(${x}, ${y})">
+      <title>${escapeHtml(title)}</title>
+      <rect width="${NODE_W}" height="${NODE_H}" rx="8"/>
+      <rect width="4" height="${NODE_H}" rx="2" fill="${color}"/>
+      <text x="14" y="19" class="name">${escapeHtml(name)}</text>
+      <text x="14" y="36" class="kind" fill="${color}">${escapeHtml(model.kind._tag)}</text>
+    </g>`
+  })
+
+  const legend = Object.entries(KIND_COLOR)
+    .filter(([tag]) => [...graph.models.values()].some((model) => model.kind._tag === tag))
+    .map(
+      ([tag, color]) =>
+        `<span class="badge"><i style="background:${color}"></i>${escapeHtml(tag)}</span>`,
+    )
+    .join("")
+
+  return `<!doctype html>
+<html lang="ru">
+<head>
+<meta charset="utf-8">
+<title>efmesh — DAG моделей</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.4 system-ui, sans-serif; margin: 0; padding: 16px;
+         background: light-dark(#fafafa, #16181d); color: light-dark(#222, #ddd); }
+  h1 { font-size: 16px; margin: 0 0 4px; }
+  .legend { margin-bottom: 12px; }
+  .badge { display: inline-flex; align-items: center; gap: 5px; margin-right: 14px;
+           font-size: 12px; opacity: .85; }
+  .badge i { width: 10px; height: 10px; border-radius: 3px; display: inline-block; }
+  svg { max-width: 100%; height: auto; }
+  .node rect:first-of-type { fill: light-dark(#fff, #23262e);
+    stroke: light-dark(#d5d5d5, #3a3f4a); }
+  .node .name { font-weight: 600; font-size: 13px; fill: light-dark(#222, #eee); }
+  .node .kind { font-size: 11px; }
+  .edge { fill: none; stroke: light-dark(#b9c0c9, #4a5160); stroke-width: 1.5; }
+  .node, .edge { transition: opacity .12s ease; }
+  svg.focused .node:not(.lit), svg.focused .edge:not(.lit) { opacity: .18; }
+  .edge.lit { stroke: light-dark(#e07a5f, #e6a08c); stroke-width: 2; }
+</style>
+</head>
+<body>
+<h1>efmesh — 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")}
+${nodes.join("\n")}
+</svg>
+<script>
+  const svg = document.getElementById("dag")
+  const edges = [...svg.querySelectorAll(".edge")]
+  for (const node of svg.querySelectorAll(".node")) {
+    node.addEventListener("mouseenter", () => {
+      const name = node.dataset.name
+      svg.classList.add("focused")
+      node.classList.add("lit")
+      for (const edge of edges) {
+        if (edge.dataset.from !== name && edge.dataset.to !== name) continue
+        edge.classList.add("lit")
+        const other = edge.dataset.from === name ? edge.dataset.to : edge.dataset.from
+        svg.querySelector('.node[data-name="' + CSS.escape(other) + '"]')?.classList.add("lit")
+      }
+    })
+    node.addEventListener("mouseleave", () => {
+      svg.classList.remove("focused")
+      for (const lit of svg.querySelectorAll(".lit")) lit.classList.remove("lit")
+    })
+  }
+</script>
+</body>
+</html>
+`
+}

package/src/plan/janitor.ts

@@ -0,0 +1,130 @@
+import { rmSync } from "node:fs"
+import { Clock, Effect } from "effect"
+import { parseModelName } from "../core/model.ts"
+import { EngineAdapter } from "../engine/adapter.ts"
+import type { EngineError } from "../engine/adapter.ts"
+import { StateStore } from "../state/store.ts"
+import type { StateError } from "../state/store.ts"
+import { janitorLockName, withStateLock, type LockHeldError, type LockOptions } from "./lock.ts"
+import { ducklakeAttachSql, ducklakeRef, parquetPrefix, physicalRef } from "./naming.ts"
+
+/**
+ * Уборка осиротевшей физики (SPEC §5.4): снапшоты, на которые не ссылается
+ * ни одно окружение и которые осиротели раньше, чем ttl назад, сносятся —
+ * таблица/view движка, parquet-префикс озера, запись снапшота и учёт
+ * интервалов.
+ *
+ * ttl отсчитывается от orphaned_at — отметки, которую промоушен ставит
+ * при потере последней ссылки и снимает при возврате (откат на старую
+ * версию обнуляет счётчик). Для записей без отметки (ни разу не
+ * промоутились — например, apply упал до промоушена) — от created_at.
+ * ttl по умолчанию 7 дней — достаточно, чтобы мгновенно откатиться
+ * переключением view.
+ */
+
+export interface JanitorOptions extends LockOptions {
+  readonly ttlDays?: number
+  readonly lakePath?: string
+  /** DuckLake-каталог (SPEC §14.5) — чтобы снести и таблицы-на-fingerprint в нём. */
+  readonly ducklake?: { readonly catalog: string; readonly dataPath?: string }
+  /** «Сейчас» — инъекция для тестов. */
+  readonly now?: number
+}
+
+export interface JanitorReport {
+  /** Снесённые снапшоты в виде `имя@fp8`. */
+  readonly removed: ReadonlyArray<string>
+  /** Осиротевшие, но моложе ttl — остаются до следующего раза. */
+  readonly kept: ReadonlyArray<string>
+}
+
+const DAY_MS = 86_400_000
+
+export const janitor = (
+  options?: JanitorOptions,
+): Effect.Effect<
+  JanitorReport,
+  EngineError | StateError | LockHeldError,
+  EngineAdapter | StateStore
+> =>
+  Effect.gen(function* () {
+    const engine = yield* EngineAdapter
+    const store = yield* StateStore
+    const now = options?.now ?? (yield* Clock.currentTimeMillis)
+    const ttlMs = (options?.ttlDays ?? 7) * DAY_MS
+
+    // снапшот не хранит цель материализации — при настроенном каталоге
+    // таблица сносится и там, и в _efmesh (DROP IF EXISTS терпим к пустоте)
+    const ducklake = options?.ducklake
+    if (ducklake !== undefined && engine.dialect === "duckdb") {
+      yield* engine.execute(ducklakeAttachSql(ducklake))
+    }
+
+    const referenced = yield* store.listReferencedFingerprints()
+    const removed: Array<string> = []
+    const kept: Array<string> = []
+
+    const snapshots = yield* store.listSnapshots()
+    const deadline = new Date(now - ttlMs).toISOString()
+    const isDoomed = (snapshot: (typeof snapshots)[number]): boolean =>
+      !referenced.has(snapshot.fingerprint) &&
+      (snapshot.orphanedAt ?? snapshot.createdAt) <= deadline
+
+    // фаза 1 — транзакционный claim записей: снос состоится, только если
+    // снапшот ВСЁ ЕЩЁ не referenced и сирота (проверки атомарны с удалением);
+    // параллельный apply, воскресивший версию (upsert снимает orphaned_at),
+    // claim проиграет — и её физика не тронется (гонка F6)
+    const claimed: Array<(typeof snapshots)[number]> = []
+    for (const snapshot of snapshots) {
+      if (referenced.has(snapshot.fingerprint)) continue
+      const label = `${snapshot.name}@${snapshot.fingerprint.slice(0, 8)}`
+      if (!isDoomed(snapshot)) {
+        kept.push(label)
+        continue
+      }
+      const won = yield* store.deleteSnapshotIfDoomed(
+        snapshot.name,
+        snapshot.fingerprint,
+        deadline,
+      )
+      if (!won) {
+        kept.push(label)
+        continue
+      }
+      claimed.push(snapshot)
+      removed.push(label)
+    }
+
+    // фаза 2 — снос физики по СВЕЖЕМУ состоянию стора: физика делится между
+    // версиями (forward-only) и сносится, только если после claim'ов её не
+    // использует ни один выживший снапшот
+    const survivors = yield* store.listSnapshots()
+    const physicalInUse = new Set(survivors.map((snapshot) => snapshot.physicalFp))
+    const dropped = new Set<string>()
+    for (const snapshot of claimed) {
+      if (physicalInUse.has(snapshot.physicalFp) || dropped.has(snapshot.physicalFp)) continue
+      dropped.add(snapshot.physicalFp)
+      const name = parseModelName(snapshot.name)
+      const target = physicalRef(name, snapshot.physicalFp)
+      yield* engine.execute(
+        snapshot.kind === "view"
+          ? `DROP VIEW IF EXISTS ${target}`
+          : `DROP TABLE IF EXISTS ${target}`,
+      )
+      if (ducklake !== undefined && engine.dialect === "duckdb" && snapshot.kind !== "view") {
+        yield* engine.execute(
+          `DROP TABLE IF EXISTS ${ducklakeRef(name, snapshot.physicalFp)}`,
+        )
+      }
+      if (options?.lakePath !== undefined && !options.lakePath.startsWith("s3://")) {
+        const prefix = parquetPrefix(options.lakePath, name, snapshot.physicalFp)
+        yield* Effect.sync(() => rmSync(prefix, { recursive: true, force: true }))
+      }
+    }
+
+    return { removed, kept }
+  }).pipe(
+    // два janitor'а из разных процессов не должны наперегонки сносить одно и
+    // то же; от гонки janitor↔apply защищает ttl (окно на мгновенный откат)
+    withStateLock(janitorLockName, options?.lockTtlMs),
+  )

package/src/plan/lineage.ts

@@ -0,0 +1,143 @@
+import { Data, Effect } from "effect"
+import type { ModelGraph } from "../core/graph.ts"
+import type { AnyModel } from "../core/model.ts"
+import type { EngineError, SqlParseError } from "../engine/adapter.ts"
+import { EngineAdapter } from "../engine/adapter.ts"
+import { canonicalSql } from "./fingerprint.ts"
+
+/**
+ * Колоночный lineage (SPEC §9.4): цепочка от колонки модели до сырьевых
+ * колонок external/seed-моделей. Точность best-effort — выражение колонки
+ * берётся из канонического AST (родной парсер движка), ссылки на колонки
+ * сопоставляются схемам родителей по имени, квалификаторы и алиасы CTE
+ * не разворачиваются. Граф моделей при этом точен всегда: зависимости
+ * известны из `ctx.ref`, не из парсинга текста.
+ */
+
+export class LineageError extends Data.TaggedError("LineageError")<{
+  readonly model: string
+  readonly reason: string
+}> {}
+
+export interface LineageNode {
+  readonly model: string
+  readonly column: string
+  /** Вид модели — external/seed являются листьями (сырьё). */
+  readonly kind: string
+  readonly sources: ReadonlyArray<LineageNode>
+}
+
+/** Все COLUMN_REF в поддереве выражения — имена колонок без квалификаторов. */
+const collectColumnRefs = (node: unknown, out: Set<string>): void => {
+  if (Array.isArray(node)) {
+    for (const item of node) collectColumnRefs(item, out)
+    return
+  }
+  if (node === null || typeof node !== "object") return
+  const record = node as Record<string, unknown>
+  if (record.class === "COLUMN_REF" && Array.isArray(record.column_names)) {
+    const names = record.column_names as ReadonlyArray<string>
+    if (names.length > 0) out.add(names[names.length - 1]!)
+  }
+  for (const value of Object.values(record)) collectColumnRefs(value, out)
+}
+
+const selectItems = (ast: unknown): ReadonlyArray<Record<string, unknown>> => {
+  const statements = (ast as { statements?: ReadonlyArray<{ node?: unknown }> }).statements
+  const node = statements?.[0]?.node as { select_list?: ReadonlyArray<unknown> } | undefined
+  return (node?.select_list ?? []) as ReadonlyArray<Record<string, unknown>>
+}
+
+/**
+ * Колонки, от которых зависит `column` в select_list: выражение с алиасом
+ * или одноимённый COLUMN_REF; `SELECT *` — сквозной проброс имени.
+ * undefined — выражение колонки не найдено (движковый сахар) — best-effort.
+ */
+const sourceColumnsOf = (ast: unknown, column: string): ReadonlySet<string> | undefined => {
+  const items = selectItems(ast)
+  const named =
+    items.find((item) => item.alias === column) ??
+    items.find((item) => {
+      if (item.alias !== "" && item.alias !== undefined) return false
+      if (item.class !== "COLUMN_REF" || !Array.isArray(item.column_names)) return false
+      const names = item.column_names as ReadonlyArray<string>
+      return names[names.length - 1] === column
+    })
+  if (named !== undefined) {
+    const out = new Set<string>()
+    collectColumnRefs(named, out)
+    return out
+  }
+  if (items.some((item) => item.class === "STAR" || item.type === "STAR")) {
+    return new Set([column])
+  }
+  return undefined
+}
+
+export const lineage = (
+  graph: ModelGraph,
+  modelName: string,
+  column: string,
+): Effect.Effect<LineageNode, LineageError | EngineError | SqlParseError, EngineAdapter> =>
+  Effect.gen(function* () {
+    const engine = yield* EngineAdapter
+    const root = graph.models.get(modelName)
+    if (root === undefined) {
+      return yield* new LineageError({ model: modelName, reason: "модели нет в проекте" })
+    }
+    if (!(column in root.schema.fields)) {
+      return yield* new LineageError({
+        model: modelName,
+        reason: `колонки «${column}» нет в схеме`,
+      })
+    }
+
+    const asts = new Map<string, unknown>()
+    const astOf = (model: AnyModel): Effect.Effect<unknown, EngineError | SqlParseError> =>
+      Effect.gen(function* () {
+        const cached = asts.get(model.name.full)
+        if (cached !== undefined) return cached
+        const ast = JSON.parse(
+          yield* engine.canonicalize(canonicalSql(graph, model.name.full)),
+        ) as unknown
+        asts.set(model.name.full, ast)
+        return ast
+      })
+
+    const trace = (
+      model: AnyModel,
+      wanted: string,
+    ): Effect.Effect<LineageNode, EngineError | SqlParseError> =>
+      Effect.gen(function* () {
+        const leaf: LineageNode = {
+          model: model.name.full,
+          column: wanted,
+          kind: model.kind._tag,
+          sources: [],
+        }
+        // сырьё: дальше цепочка упирается во внешний мир
+        if (model.kind._tag === "external" || model.kind._tag === "seed" || model.deps.size === 0) {
+          return leaf
+        }
+        const columns = sourceColumnsOf(yield* astOf(model), wanted)
+        if (columns === undefined) return leaf
+        const sources: Array<LineageNode> = []
+        for (const source of columns) {
+          for (const parent of model.refs.values()) {
+            if (!(source in parent.schema.fields)) continue
+            sources.push(yield* trace(parent, source))
+          }
+        }
+        return { ...leaf, sources }
+      })
+
+    return yield* trace(root, column)
+  })
+
+/** Плоская печать lineage-дерева для CLI. */
+export const formatLineage = (node: LineageNode, indent = ""): ReadonlyArray<string> => {
+  const marker =
+    node.kind === "external" || node.kind === "seed" ? `  [${node.kind}]` : ""
+  const line = `${indent}${node.model}.${node.column}${marker}`
+  return [line, ...node.sources.flatMap((source) => formatLineage(source, `${indent}  `))]
+}

package/src/plan/lock.ts

@@ -0,0 +1,37 @@
+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).
+ */
+
+export class LockHeldError extends Data.TaggedError("LockHeldError")<{
+  readonly name: string
+}> {}
+
+export interface LockOptions {
+  /** Сколько лок живёт без освобождения (упавший процесс); по умолчанию 1 час. */
+  readonly lockTtlMs?: number
+}
+
+/** Имя лока, под которым мутируется окружение (общий для apply и run). */
+export const envLockName = (env: string): string => `env:${env}`
+
+/** Лок janitor — глобальный: уборка физики не привязана к окружению. */
+export const janitorLockName = "janitor"
+
+export const withStateLock =
+  (name: string, ttlMs?: number) =>
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E | LockHeldError | StateError, R | StateStore> =>
+    Effect.gen(function* () {
+      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)))
+    })

package/src/plan/metrics.ts

@@ -0,0 +1,14 @@
+import { Metric } from "effect"
+
+/** Наблюдаемость из коробки (SPEC §10): счётчики конвейера. */
+export const intervalsDone = Metric.counter("efmesh_intervals_done_total", {
+  description: "Сколько интервалов досчитано и помечено done",
+})
+
+export const auditFailuresTotal = Metric.counter("efmesh_audit_failures_total", {
+  description: "Сколько blocking-аудитов провалилось",
+})
+
+export const snapshotsBuilt = Metric.counter("efmesh_snapshots_built_total", {
+  description: "Сколько снапшотов собрано (физика или бэкфилл)",
+})