@avytheone/efmesh 0.1.0-beta.1

package/src/state/sqlite.ts

@@ -0,0 +1,407 @@
+import { Database } from "bun:sqlite"
+import { copyFileSync, existsSync } from "node:fs"
+import { Clock, Effect, Layer } from "effect"
+import type {
+  EnvironmentRecord,
+  IntervalRecord,
+  MigrationReport,
+  PlanRecord,
+  SnapshotRecord,
+  StateStoreShape,
+} from "./store.ts"
+import { STATE_VERSION, StateError, StateSchemaError, StateStore } from "./store.ts"
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS snapshots (
+  name          TEXT NOT NULL,
+  fingerprint   TEXT NOT NULL,
+  rendered_sql  TEXT NOT NULL,
+  canonical_ast TEXT NOT NULL DEFAULT '',
+  physical_fp   TEXT NOT NULL DEFAULT '',
+  kind          TEXT NOT NULL,
+  fingerprint_version INTEGER NOT NULL DEFAULT 1,
+  created_at    TEXT NOT NULL,
+  orphaned_at   TEXT,
+  PRIMARY KEY (name, fingerprint)
+);
+CREATE TABLE IF NOT EXISTS environments (
+  env         TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  promoted_at TEXT NOT NULL,
+  PRIMARY KEY (env, name)
+);
+CREATE TABLE IF NOT EXISTS plans (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  env        TEXT NOT NULL,
+  summary    TEXT NOT NULL,
+  applied_at TEXT NOT NULL,
+  applied_by TEXT NOT NULL DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS intervals (
+  snapshot_fp TEXT NOT NULL,
+  start_ts    TEXT NOT NULL,
+  end_ts      TEXT NOT NULL,
+  status      TEXT NOT NULL,
+  updated_at  TEXT NOT NULL,
+  PRIMARY KEY (snapshot_fp, start_ts)
+);
+CREATE TABLE IF NOT EXISTS locks (
+  name        TEXT PRIMARY KEY,
+  acquired_at TEXT NOT NULL,
+  expires_at  TEXT NOT NULL
+);
+`
+
+export interface SqliteStateOptions {
+  /** Путь к файлу состояния; по умолчанию in-memory (тесты). */
+  readonly path?: string
+}
+
+const isoNow = Clock.currentTimeMillis.pipe(Effect.map((ms) => new Date(ms).toISOString()))
+
+const tableExists = (db: Database, name: string): boolean =>
+  db
+    .query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1`)
+    .get(name) !== null
+
+/** 0 — стор без таблицы meta (создан до появления версионирования, F0–F3). */
+const readVersion = (db: Database): number => {
+  if (!tableExists(db, "meta")) return 0
+  const row = db.query(`SELECT version FROM meta`).get() as { version: number } | null
+  return row?.version ?? 0
+}
+
+/**
+ * Догоняет схему до STATE_VERSION. Версия 1 = базовая раскладка F4,
+ * версия 2 = applied_by в журнале планов (F5); ALTER-ы ниже подхватывают
+ * сторы, созданные до соответствующих колонок (canonical_ast — F2,
+ * orphaned_at/physical_fp — F3, applied_by — F5), — на новом сторе
+ * они no-op через try/catch. Будущие версии — новые записи здесь же.
+ */
+const applyMigrations = (db: Database): void => {
+  db.exec(SCHEMA)
+  for (const alter of [
+    `ALTER TABLE snapshots ADD COLUMN canonical_ast TEXT NOT NULL DEFAULT ''`,
+    `ALTER TABLE snapshots ADD COLUMN orphaned_at TEXT`,
+    `ALTER TABLE snapshots ADD COLUMN physical_fp TEXT NOT NULL DEFAULT ''`,
+    `ALTER TABLE plans ADD COLUMN applied_by TEXT NOT NULL DEFAULT ''`,
+    `ALTER TABLE snapshots ADD COLUMN fingerprint_version INTEGER NOT NULL DEFAULT 1`,
+  ]) {
+    try {
+      db.exec(alter)
+    } catch {
+      // колонка уже есть
+    }
+  }
+  db.exec(`CREATE TABLE IF NOT EXISTS meta (version INTEGER NOT NULL)`)
+  db.exec(`DELETE FROM meta`)
+  db.query(`INSERT INTO meta (version) VALUES (?1)`).run(STATE_VERSION)
+}
+
+/**
+ * `efmesh migrate`: явное обновление схемы существующего стора.
+ * Перед апгрейдом файл копируется в `<path>.backup-v<from>` — откат
+ * на старую версию efmesh иначе односторонний (F6).
+ */
+export const migrateSqliteState = (
+  options?: SqliteStateOptions,
+): Effect.Effect<MigrationReport, StateError> =>
+  Effect.try({
+    try: () => {
+      const path = options?.path ?? ":memory:"
+      const db = new Database(path, { create: true })
+      try {
+        const from = readVersion(db)
+        let backup: string | undefined
+        if (path !== ":memory:" && from !== STATE_VERSION && existsSync(path)) {
+          backup = `${path}.backup-v${from}`
+          copyFileSync(path, backup)
+        }
+        applyMigrations(db)
+        return { from, to: STATE_VERSION, ...(backup !== undefined ? { backup } : {}) }
+      } finally {
+        db.close()
+      }
+    },
+    catch: (cause) => new StateError({ operation: "migrate", cause }),
+  })
+
+export const SqliteStateLive = (
+  options?: SqliteStateOptions,
+): Layer.Layer<StateStore, StateError | StateSchemaError> =>
+  Layer.effect(
+    StateStore,
+    Effect.gen(function* () {
+      const db = yield* Effect.acquireRelease(
+        Effect.try({
+          try: () => {
+            const db = new Database(options?.path ?? ":memory:", { create: true })
+            db.exec("PRAGMA journal_mode = WAL;")
+            return db
+          },
+          catch: (cause) => new StateError({ operation: "open", cause }),
+        }),
+        (db) => Effect.sync(() => db.close()),
+      )
+      // свежий стор бутстрапится на текущую версию; существующий со схемой
+      // старше требует явного `efmesh migrate` — молча менять чужие данные
+      // при открытии нельзя (SPEC §6)
+      const fresh = yield* Effect.try({
+        try: () => !tableExists(db, "snapshots"),
+        catch: (cause) => new StateError({ operation: "open", cause }),
+      })
+      if (fresh) {
+        yield* Effect.try({
+          try: () => applyMigrations(db),
+          catch: (cause) => new StateError({ operation: "migrate", cause }),
+        })
+      } else {
+        const version = yield* Effect.try({
+          try: () => readVersion(db),
+          catch: (cause) => new StateError({ operation: "open", cause }),
+        })
+        if (version !== STATE_VERSION) {
+          return yield* new StateSchemaError({ found: version, wanted: STATE_VERSION })
+        }
+      }
+
+      const attempt = <A>(operation: string, body: () => A) =>
+        Effect.try({ try: body, catch: (cause) => new StateError({ operation, cause }) })
+
+      const service: StateStoreShape = {
+        upsertSnapshot: (snapshot) =>
+          isoNow.pipe(
+            Effect.flatMap((now) =>
+              attempt("upsertSnapshot", () => {
+                // воскрешение версии (повторный apply старого fingerprint)
+                // снимает сиротство И освежает created_at СРАЗУ: между upsert
+                // и промоушеном janitor не сочтёт её обречённой ни по
+                // orphaned_at, ни по старому created_at (гонка F6)
+                db.query(
+                  `INSERT INTO snapshots (name, fingerprint, rendered_sql, canonical_ast, physical_fp, kind, fingerprint_version, created_at)
+                   VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+                   ON CONFLICT (name, fingerprint)
+                   DO UPDATE SET orphaned_at = NULL, created_at = excluded.created_at`,
+                ).run(
+                  snapshot.name,
+                  snapshot.fingerprint,
+                  snapshot.renderedSql,
+                  snapshot.canonicalAst,
+                  snapshot.physicalFp,
+                  snapshot.kind,
+                  snapshot.fingerprintVersion,
+                  now,
+                )
+              }),
+            ),
+          ),
+
+        getSnapshot: (name, fingerprint) =>
+          attempt("getSnapshot", () => {
+            const row = db
+              .query(
+                `SELECT name, fingerprint, rendered_sql AS renderedSql,
+                        canonical_ast AS canonicalAst, kind, created_at AS createdAt,
+                        orphaned_at AS orphanedAt, fingerprint_version AS fingerprintVersion,
+                        CASE WHEN physical_fp = '' THEN fingerprint ELSE physical_fp END AS physicalFp
+                 FROM snapshots WHERE name = ?1 AND fingerprint = ?2`,
+              )
+              .get(name, fingerprint) as SnapshotRecord | null
+            return row ?? undefined
+          }),
+
+        listReferencedFingerprints: () =>
+          attempt("listReferencedFingerprints", () => {
+            const rows = db
+              .query(`SELECT DISTINCT fingerprint FROM environments`)
+              .all() as ReadonlyArray<{ fingerprint: string }>
+            return new Set(rows.map((r) => r.fingerprint))
+          }),
+
+        listSnapshots: () =>
+          attempt("listSnapshots", () => {
+            return db
+              .query(
+                `SELECT name, fingerprint, rendered_sql AS renderedSql,
+                        canonical_ast AS canonicalAst, kind, created_at AS createdAt,
+                        orphaned_at AS orphanedAt, fingerprint_version AS fingerprintVersion,
+                        CASE WHEN physical_fp = '' THEN fingerprint ELSE physical_fp END AS physicalFp
+                 FROM snapshots ORDER BY name, created_at`,
+              )
+              .all() as ReadonlyArray<SnapshotRecord>
+          }),
+
+        deleteSnapshot: (name, fingerprint) =>
+          attempt("deleteSnapshot", () => {
+            const remove = db.transaction(() => {
+              db.query(`DELETE FROM snapshots WHERE name = ?1 AND fingerprint = ?2`).run(
+                name,
+                fingerprint,
+              )
+              db.query(`DELETE FROM intervals WHERE snapshot_fp = ?1`).run(fingerprint)
+            })
+            remove()
+          }),
+
+        deleteSnapshotIfDoomed: (name, fingerprint, deadline) =>
+          attempt("deleteSnapshotIfDoomed", () => {
+            const claim = db.transaction((): boolean => {
+              const referenced =
+                db
+                  .query(`SELECT 1 FROM environments WHERE fingerprint = ?1 LIMIT 1`)
+                  .get(fingerprint) !== null
+              if (referenced) return false
+              const result = db
+                .query(
+                  `DELETE FROM snapshots
+                   WHERE name = ?1 AND fingerprint = ?2
+                     AND COALESCE(orphaned_at, created_at) <= ?3`,
+                )
+                .run(name, fingerprint, deadline)
+              if (result.changes === 0) return false
+              db.query(`DELETE FROM intervals WHERE snapshot_fp = ?1`).run(fingerprint)
+              return true
+            })
+            return claim() as boolean
+          }),
+
+        getEnvironment: (env) =>
+          attempt("getEnvironment", () => {
+            return db
+              .query(
+                `SELECT env, name, fingerprint, promoted_at AS promotedAt
+                 FROM environments WHERE env = ?1 ORDER BY name`,
+              )
+              .all(env) as ReadonlyArray<EnvironmentRecord>
+          }),
+
+        promote: (env, entries) =>
+          isoNow.pipe(
+            Effect.flatMap((now) =>
+              attempt("promote", () => {
+                const replace = db.transaction(() => {
+                  // живость снапшотов — в той же транзакции: если janitor
+                  // успел унести версию, промоушен громко падает, а view
+                  // не переключается на снесённую физику (гонка F6)
+                  const alive = db.query(
+                    `SELECT 1 FROM snapshots WHERE name = ?1 AND fingerprint = ?2`,
+                  )
+                  for (const entry of entries) {
+                    if (entry.requireSnapshot === true && alive.get(entry.name, entry.fingerprint) === null) {
+                      throw new Error(
+                        `промоушен ${env}: снапшот ${entry.name}@${entry.fingerprint.slice(0, 8)} исчез из стора (снесён janitor?) — повторите apply`,
+                      )
+                    }
+                  }
+                  db.query(`DELETE FROM environments WHERE env = ?1`).run(env)
+                  const insert = db.query(
+                    `INSERT INTO environments (env, name, fingerprint, promoted_at)
+                     VALUES (?1, ?2, ?3, ?4)`,
+                  )
+                  for (const entry of entries) {
+                    insert.run(env, entry.name, entry.fingerprint, now)
+                  }
+                  // ссылочность меняется только здесь — тут же и учёт сиротства:
+                  // потерявшие последнюю ссылку получают отметку, вернувшиеся
+                  // (откат на старую версию) — теряют её (SPEC §5.4)
+                  db.query(
+                    `UPDATE snapshots SET orphaned_at = ?1
+                     WHERE orphaned_at IS NULL
+                       AND fingerprint NOT IN (SELECT fingerprint FROM environments)`,
+                  ).run(now)
+                  db.query(
+                    `UPDATE snapshots SET orphaned_at = NULL
+                     WHERE orphaned_at IS NOT NULL
+                       AND fingerprint IN (SELECT fingerprint FROM environments)`,
+                  ).run()
+                })
+                replace()
+              }),
+            ),
+          ),
+
+        recordPlan: (env, summary, appliedBy) =>
+          isoNow.pipe(
+            Effect.flatMap((now) =>
+              attempt("recordPlan", () => {
+                db.query(
+                  `INSERT INTO plans (env, summary, applied_at, applied_by) VALUES (?1, ?2, ?3, ?4)`,
+                ).run(env, summary, now, appliedBy)
+              }),
+            ),
+          ),
+
+        listPlans: (env) =>
+          attempt("listPlans", () => {
+            return db
+              .query(
+                `SELECT id, env, summary, applied_at AS appliedAt, applied_by AS appliedBy
+                 FROM plans WHERE env = ?1 ORDER BY id`,
+              )
+              .all(env) as ReadonlyArray<PlanRecord>
+          }),
+
+        acquireLock: (name, ttlMs) =>
+          Clock.currentTimeMillis.pipe(
+            Effect.flatMap((nowMs) =>
+              attempt("acquireLock", () => {
+                const now = new Date(nowMs).toISOString()
+                const expires = new Date(nowMs + ttlMs).toISOString()
+                const acquire = db.transaction(() => {
+                  // протухший лок упавшего процесса перехватывается;
+                  // <= — лок, истёкший в момент T, свободен с T (ttl=0 в ту же мс)
+                  db.query(`DELETE FROM locks WHERE name = ?1 AND expires_at <= ?2`).run(name, now)
+                  const result = db
+                    .query(
+                      `INSERT INTO locks (name, acquired_at, expires_at)
+                       VALUES (?1, ?2, ?3)
+                       ON CONFLICT (name) DO NOTHING`,
+                    )
+                    .run(name, now, expires)
+                  return result.changes > 0
+                })
+                return acquire()
+              }),
+            ),
+          ),
+
+        releaseLock: (name) =>
+          attempt("releaseLock", () => {
+            db.query(`DELETE FROM locks WHERE name = ?1`).run(name)
+          }),
+
+        markIntervals: (snapshotFp, intervals, status) =>
+          isoNow.pipe(
+            Effect.flatMap((now) =>
+              attempt("markIntervals", () => {
+                const upsert = db.query(
+                  `INSERT INTO intervals (snapshot_fp, start_ts, end_ts, status, updated_at)
+                   VALUES (?1, ?2, ?3, ?4, ?5)
+                   ON CONFLICT (snapshot_fp, start_ts)
+                   DO UPDATE SET end_ts = ?3, status = ?4, updated_at = ?5`,
+                )
+                const all = db.transaction(() => {
+                  for (const interval of intervals) {
+                    upsert.run(snapshotFp, interval.startTs, interval.endTs, status, now)
+                  }
+                })
+                all()
+              }),
+            ),
+          ),
+
+        listIntervals: (snapshotFp) =>
+          attempt("listIntervals", () => {
+            return db
+              .query(
+                `SELECT snapshot_fp AS snapshotFp, start_ts AS startTs, end_ts AS endTs,
+                        status, updated_at AS updatedAt
+                 FROM intervals WHERE snapshot_fp = ?1 ORDER BY start_ts`,
+              )
+              .all(snapshotFp) as ReadonlyArray<IntervalRecord>
+          }),
+      }
+      return service
+    }),
+  )

package/src/state/store.ts

@@ -0,0 +1,161 @@
+import { Context, Data, Effect } from "effect"
+
+export class StateError extends Data.TaggedError("StateError")<{
+  readonly operation: string
+  readonly cause: unknown
+}> {}
+
+/**
+ * Текущая версия схемы state store. Свежий стор бутстрапится сразу
+ * на неё; стор со схемой старше (в т.ч. созданный до появления версии)
+ * открытие не проходит — данные догоняет явный `efmesh migrate`.
+ * 1 — базовая раскладка (F4), 2 — applied_by в журнале планов (F5),
+ * 3 — fingerprint_version в снапшотах (F6).
+ */
+export const STATE_VERSION = 3
+
+/** Схема стора не совпадает с ожидаемой бинарём — нужен `efmesh migrate`. */
+export class StateSchemaError extends Data.TaggedError("StateSchemaError")<{
+  readonly found: number
+  readonly wanted: number
+}> {}
+
+/** Итог миграции для CLI. */
+export interface MigrationReport {
+  readonly from: number
+  readonly to: number
+  /** Куда сложена копия стора перед апгрейдом схемы (SQLite; F6). */
+  readonly backup?: string
+}
+
+/** Версия модели, известная state store (SPEC §6). */
+export interface SnapshotRecord {
+  readonly name: string
+  readonly fingerprint: string
+  /** Canonical-рендер SQL — для diff-показа и отладки. */
+  readonly renderedSql: string
+  /** Канонический AST тела (JSON) — для категоризации изменений (SPEC §5.2). */
+  readonly canonicalAst: string
+  /**
+   * Fingerprint, чьей физической таблицей/префиксом пользуется снапшот.
+   * Обычно равен собственному; при forward-only (SPEC §5.2) — наследуется
+   * от предыдущей версии: физика переиспользуется, история не переигрывается.
+   */
+  readonly physicalFp: string
+  readonly kind: string
+  /**
+   * Версия алгоритма fingerprint, которым посчитан снапшот (SPEC §4).
+   * План сравнивает только одноверсионные отпечатки; иная версия —
+   * громкая остановка, не тихий «всё breaking».
+   */
+  readonly fingerprintVersion: number
+  readonly createdAt: string
+  /**
+   * Когда снапшот перестал быть указан хоть одним окружением (ISO UTC);
+   * null — на него ссылаются. Ставится и снимается при промоушене,
+   * ttl janitor'а отсчитывается отсюда (SPEC §5.4).
+   */
+  readonly orphanedAt: string | null
+}
+
+/** Строка окружения: логическое имя → снапшот, на который указывает view. */
+export interface EnvironmentRecord {
+  readonly env: string
+  readonly name: string
+  readonly fingerprint: string
+  readonly promotedAt: string
+}
+
+export interface PlanRecord {
+  readonly id: number
+  readonly env: string
+  readonly summary: string
+  readonly appliedAt: string
+  /** Кто применил план (ОС-пользователь или ApplyOptions.appliedBy); '' у записей до v2. */
+  readonly appliedBy: string
+}
+
+/**
+ * Учёт заполненных интервалов снапшота (SPEC §6) — единственный источник
+ * правды о том, что посчитано: физическая таблица без записей здесь
+ * считается пустой. Границы — ISO UTC (сортируются лексикографически).
+ */
+export interface IntervalRecord {
+  readonly snapshotFp: string
+  readonly startTs: string
+  readonly endTs: string
+  readonly status: "done" | "failed"
+  readonly updatedAt: string
+}
+
+export interface StateStoreShape {
+  /** Идемпотентно: (name, fingerprint) уникальны, повторная запись — no-op. */
+  readonly upsertSnapshot: (
+    snapshot: Omit<SnapshotRecord, "createdAt" | "orphanedAt">,
+  ) => Effect.Effect<void, StateError>
+  readonly getSnapshot: (
+    name: string,
+    fingerprint: string,
+  ) => Effect.Effect<SnapshotRecord | undefined, StateError>
+  /** Все снапшоты, на которые ссылается хоть одно окружение, — для janitor. */
+  readonly listReferencedFingerprints: () => Effect.Effect<ReadonlySet<string>, StateError>
+  readonly listSnapshots: () => Effect.Effect<ReadonlyArray<SnapshotRecord>, StateError>
+  /** Удаляет запись снапшота и его учёт интервалов (физику убирает janitor). */
+  readonly deleteSnapshot: (name: string, fingerprint: string) => Effect.Effect<void, StateError>
+  /**
+   * Транзакционный «claim» сироты janitor'ом (SPEC §5.4, F6): запись и учёт
+   * интервалов удаляются, только если снапшот ВСЁ ЕЩЁ не referenced ни одним
+   * окружением и осиротел не позже deadline (ISO UTC) — обе проверки в одной
+   * транзакции с удалением, поэтому параллельный apply, воскресивший версию,
+   * не даст её унести. true — снесено, false — состояние изменилось.
+   */
+  readonly deleteSnapshotIfDoomed: (
+    name: string,
+    fingerprint: string,
+    deadline: string,
+  ) => Effect.Effect<boolean, StateError>
+  readonly getEnvironment: (
+    env: string,
+  ) => Effect.Effect<ReadonlyArray<EnvironmentRecord>, StateError>
+  /**
+   * Транзакционно заменяет весь набор окружения. Записи с
+   * `requireSnapshot: true` проверяются на живость снапшота в той же
+   * транзакции: если janitor успел его унести, промоушен громко падает —
+   * view никогда не переключается на снесённую физику.
+   */
+  readonly promote: (
+    env: string,
+    entries: ReadonlyArray<{
+      readonly name: string
+      readonly fingerprint: string
+      readonly requireSnapshot?: boolean
+    }>,
+  ) => Effect.Effect<void, StateError>
+  /** Журнал применённых планов. */
+  readonly recordPlan: (
+    env: string,
+    summary: string,
+    appliedBy: string,
+  ) => Effect.Effect<void, StateError>
+  readonly listPlans: (env: string) => Effect.Effect<ReadonlyArray<PlanRecord>, StateError>
+  /**
+   * Межпроцессная блокировка (SPEC §7): true — получена, false — держит
+   * другой процесс. Протухшие (expires) локи перехватываются — упавший
+   * процесс не оставляет вечный замок.
+   */
+  readonly acquireLock: (name: string, ttlMs: number) => Effect.Effect<boolean, StateError>
+  readonly releaseLock: (name: string) => Effect.Effect<void, StateError>
+  /** Транзакционный upsert интервалов снапшота (повторная отметка — обновление статуса). */
+  readonly markIntervals: (
+    snapshotFp: string,
+    intervals: ReadonlyArray<{ readonly startTs: string; readonly endTs: string }>,
+    status: IntervalRecord["status"],
+  ) => Effect.Effect<void, StateError>
+  readonly listIntervals: (
+    snapshotFp: string,
+  ) => Effect.Effect<ReadonlyArray<IntervalRecord>, StateError>
+}
+
+export class StateStore extends Context.Service<StateStore, StateStoreShape>()(
+  "efmesh/StateStore",
+) {}