@avytheone/efmesh 0.1.0-beta.1

package/src/plan/naming.ts

@@ -0,0 +1,91 @@
+import type { ExternalSource, ModelName } from "../core/model.ts"
+
+/**
+ * Раскладка объектов в движке (SPEC §2):
+ * - физика: схема `_efmesh`, таблица `<схема>__<таблица>__<fp8>`;
+ * - виртуалка: prod живёт в родных схемах моделей (`med.stays`),
+ *   остальные окружения — в префиксованных (`dev__med.stays`).
+ *
+ * Схема именно `_efmesh`, не `efmesh`: DuckDB называет каталог по имени
+ * файла базы, и для `efmesh.duckdb` ссылка `efmesh.x` становится
+ * неоднозначной (каталог или схема) — Binder Error.
+ */
+
+export const PROD_ENV = "prod"
+
+const ENV_NAME = /^[a-z][a-z0-9_]*$/
+
+export const validateEnvName = (env: string): boolean => ENV_NAME.test(env)
+
+export const fp8 = (fingerprint: string): string => fingerprint.slice(0, 8)
+
+export const physicalSchema = "_efmesh"
+
+export const physicalTable = (name: ModelName, fingerprint: string): string =>
+  `${name.schema}__${name.table}__${fp8(fingerprint)}`
+
+export const physicalRef = (name: ModelName, fingerprint: string): string =>
+  `"${physicalSchema}"."${physicalTable(name, fingerprint)}"`
+
+export const envSchema = (env: string, modelSchema: string): string =>
+  env === PROD_ENV ? modelSchema : `${env}__${modelSchema}`
+
+/**
+ * Раскладка parquet-озера (SPEC §3.3): `<lake>/<схема>/<таблица>/fp=<fp8>/…`,
+ * у incremental внутри — партиции `interval=<ключ>/data.parquet`.
+ * Интервал = партиция: пересчёт — перезапись файлов партиции, источник
+ * правды — учёт интервалов, поэтому неатомарность перезаписи не страшна.
+ */
+export const parquetPrefix = (lakePath: string, name: ModelName, fingerprint: string): string =>
+  `${lakePath.replace(/\/+$/, "")}/${name.schema}/${name.table}/fp=${fp8(fingerprint)}`
+
+/**
+ * union_by_name: партиции одного префикса могут отличаться схемой после
+ * forward-only-эволюции (новые колонки появляются только в новых файлах —
+ * история читается с NULL).
+ */
+export const parquetRef = (lakePath: string, name: ModelName, fingerprint: string): string =>
+  `read_parquet('${parquetPrefix(lakePath, name, fingerprint).replaceAll(`'`, `''`)}/**/*.parquet', union_by_name=true)`
+
+/**
+ * DuckLake-цель (SPEC §14.5): каталог подключается под фиксированным
+ * алиасом, физика — таблица-на-fingerprint в нём (то же имя, что у
+ * нативной физики, только каталог другой). Версионность остаётся нашей;
+ * снапшоты/time travel DuckLake — бонус. Потребители вне efmesh должны
+ * сами сделать ATTACH — view окружений ссылаются на каталог по алиасу.
+ */
+export const ducklakeAlias = "_efmesh_ducklake"
+
+export const ducklakeRef = (name: ModelName, fingerprint: string): string =>
+  `"${ducklakeAlias}"."${physicalTable(name, fingerprint)}"`
+
+export const ducklakeAttachSql = (config: {
+  readonly catalog: string
+  readonly dataPath?: string
+}): string =>
+  `ATTACH IF NOT EXISTS 'ducklake:sqlite:${config.catalog.replaceAll(`'`, `''`)}' AS "${ducklakeAlias}"${
+    config.dataPath !== undefined
+      ? ` (DATA_PATH '${config.dataPath.replaceAll(`'`, `''`)}')`
+      : ""
+  }`
+
+/** Ключ партиции интервала — безопасен для файловых систем (без двоеточий). */
+export const intervalKey = (unit: "day" | "hour", startMs: number): string => {
+  const iso = new Date(startMs).toISOString()
+  return unit === "day" ? iso.slice(0, 10) : `${iso.slice(0, 10)}T${iso.slice(11, 13)}`
+}
+
+const READERS = { parquet: "read_parquet", csv: "read_csv", json: "read_json" } as const
+
+/**
+ * Во что рендерится ссылка на external-модель (SPEC §9.3): имя таблицы
+ * (движка или ATTACH-базы) как есть, файлы/URL — через read_*.
+ * external не материализуется, потребители читают источник напрямую.
+ */
+export const externalSourceRef = (source: ExternalSource): string =>
+  source._tag === "table"
+    ? source.table
+    : `${READERS[source.format]}('${source.path.replaceAll(`'`, `''`)}')`
+
+export const viewRef = (env: string, name: ModelName): string =>
+  `"${envSchema(env, name.schema)}"."${name.table}"`

package/src/plan/planner.ts

@@ -0,0 +1,252 @@
+import { Clock, Data, Effect } from "effect"
+import type { SeedReadError } from "../core/errors.ts"
+import type { ModelGraph } from "../core/graph.ts"
+import type { Interval } from "../core/interval.ts"
+import { enumerateIntervals, fromIso, mergeIntervals, missingIntervals } from "../core/interval.ts"
+import type { EngineError, SqlParseError } from "../engine/adapter.ts"
+import { EngineAdapter } from "../engine/adapter.ts"
+import { StateStore } from "../state/store.ts"
+import type { StateError } from "../state/store.ts"
+import { categorizeAstChange } from "./categorize.ts"
+import { FINGERPRINT_VERSION, fingerprintGraph } from "./fingerprint.ts"
+import { validateEnvName } from "./naming.ts"
+
+export class InvalidEnvironmentError extends Data.TaggedError("InvalidEnvironmentError")<{
+  readonly env: string
+}> {}
+
+/** Модель нельзя применить forward-only (SPEC §5.2). */
+export class ForwardOnlyError extends Data.TaggedError("ForwardOnlyError")<{
+  readonly model: string
+  readonly reason: string
+}> {}
+
+/**
+ * Снапшот посчитан другой версией алгоритма fingerprint (SPEC §4):
+ * отпечатки разных версий несравнимы — план честно останавливается,
+ * а не показывает «всё breaking». Лечится миграцией той версии efmesh,
+ * которая сменила алгоритм.
+ */
+export class FingerprintVersionError extends Data.TaggedError("FingerprintVersionError")<{
+  readonly model: string
+  readonly found: number
+  readonly wanted: number
+}> {}
+
+export type ChangeCategory =
+  /** Модели не было в окружении. */
+  | "added"
+  /** Смысловая правка запроса или метаданных: модель и потомки пересобираются. */
+  | "breaking"
+  /** Добавлены колонки в конец SELECT, остальное дерево нетронуто (SPEC §5.2). */
+  | "non-breaking"
+  /** Собственный AST не менялся — версия сдвинулась каскадом от родителя. */
+  | "indirect"
+  /**
+   * Физика и done-интервалы старой версии переиспользуются, история не
+   * переигрывается — новая логика действует с момента применения (SPEC §5.2).
+   * Явный флаг пользователя или каскад от forward-only-родителей.
+   */
+  | "forward-only"
+  /** Была в окружении, из проекта исчезла — view будет снесён при промоушене. */
+  | "removed"
+  | "unchanged"
+
+export interface PlanAction {
+  readonly name: string
+  readonly fingerprint: string
+  /**
+   * Fingerprint, чьей физикой пользуется снапшот: обычно собственный,
+   * при forward-only — унаследованный от предыдущей версии.
+   */
+  readonly physicalFingerprint: string
+  /** Откуда наследуются физика и done-интервалы (fingerprint старой версии) при forward-only. */
+  readonly reusedFrom?: string
+  /** Канонический AST тела (null у external) — сохраняется в снапшот. */
+  readonly canonicalAst: string | null
+  readonly change: ChangeCategory
+  /**
+   * Нужна ли сборка физики. false для unchanged/removed, external и для
+   * снапшотов, уже собранных другим окружением, — тогда промоушен это
+   * только view-swap.
+   */
+  readonly build: boolean
+  /**
+   * Диапазоны к пересчёту у incrementalByTimeRange (слитые из недостающих
+   * интервалов + lookback); у остальных видов пуст. Дыры бывают и у
+   * unchanged-модели — время идёт, появляются новые интервалы.
+   */
+  readonly backfill: ReadonlyArray<Interval>
+  /** true у incrementalByUniqueKey: каждый apply перегоняет запрос (upsert по ключу). */
+  readonly refresh: boolean
+}
+
+export interface Plan {
+  readonly env: string
+  /** В топологическом порядке; removed — в конце. */
+  readonly actions: ReadonlyArray<PlanAction>
+  readonly hasChanges: boolean
+}
+
+export interface PlanOptions {
+  /** «Сейчас» для расчёта интервалов; по умолчанию — Clock. Инъекция для тестов. */
+  readonly now?: number
+  /**
+   * Модели, чьи изменения применить forward-only (SPEC §5.2): новая версия
+   * наследует физическую таблицу и done-интервалы старой, история не
+   * переигрывается. Только incrementalByTimeRange — у остальных видов
+   * «задним числом» не бывает по построению.
+   */
+  readonly forwardOnly?: ReadonlyArray<string>
+}
+
+export const planChanges = (
+  env: string,
+  graph: ModelGraph,
+  options?: PlanOptions,
+): Effect.Effect<
+  Plan,
+  | InvalidEnvironmentError
+  | ForwardOnlyError
+  | FingerprintVersionError
+  | StateError
+  | EngineError
+  | SqlParseError
+  | SeedReadError,
+  StateStore | EngineAdapter
+> =>
+  Effect.gen(function* () {
+    if (!validateEnvName(env)) return yield* new InvalidEnvironmentError({ env })
+    const store = yield* StateStore
+    const now = options?.now ?? (yield* Clock.currentTimeMillis)
+    const forwardOnly = new Set(options?.forwardOnly ?? [])
+    for (const flagged of forwardOnly) {
+      const model = graph.models.get(flagged)
+      if (model === undefined) {
+        return yield* new ForwardOnlyError({ model: flagged, reason: "модели нет в проекте" })
+      }
+      if (model.kind._tag !== "incrementalByTimeRange") {
+        return yield* new ForwardOnlyError({
+          model: flagged,
+          reason: `forward-only переиспользует физику и учёт интервалов — применим только к incrementalByTimeRange, вид модели — ${model.kind._tag}`,
+        })
+      }
+    }
+    const versions = yield* fingerprintGraph(graph)
+    const current = new Map(
+      (yield* store.getEnvironment(env)).map((row) => [row.name, row.fingerprint]),
+    )
+
+    const actions: Array<PlanAction> = []
+    const changeOf = new Map<string, ChangeCategory>()
+    for (const name of graph.order) {
+      const model = graph.models.get(name)!
+      const { fingerprint, ast } = versions.get(name)!
+      const known = current.get(name)
+      let change: ChangeCategory
+      let reusedFrom: string | undefined
+      let physicalFingerprint = fingerprint
+      if (known === undefined) change = "added"
+      else if (known === fingerprint) change = "unchanged"
+      else {
+        // категоризация по AST против последнего известного снапшота (SPEC §5.2);
+        // старых записей без AST и external — консервативно breaking
+        const previous = yield* store.getSnapshot(name, known)
+        if (previous !== undefined && previous.fingerprintVersion !== FINGERPRINT_VERSION) {
+          return yield* new FingerprintVersionError({
+            model: name,
+            found: previous.fingerprintVersion,
+            wanted: FINGERPRINT_VERSION,
+          })
+        }
+        const oldAst = previous?.canonicalAst ?? ""
+        if (oldAst === "" || ast === null) change = "breaking"
+        else if (oldAst === ast) change = "indirect" // версия сдвинута родителем/метаданными
+        else change = categorizeAstChange(oldAst, ast)
+        // forward-only: явный флаг пользователя — либо каскад: собственный AST
+        // не менялся, а все изменившиеся родители сами forward-only (реюз
+        // физики родителя означает, что и потомку нечего переигрывать)
+        const cascaded =
+          change === "indirect" &&
+          model.kind._tag === "incrementalByTimeRange" &&
+          [...model.deps].every((dep) => {
+            const parent = changeOf.get(dep)
+            return parent === undefined || parent === "unchanged" || parent === "forward-only"
+          })
+        if (previous !== undefined && (forwardOnly.has(name) || cascaded)) {
+          change = "forward-only"
+          reusedFrom = known
+          physicalFingerprint = previous.physicalFp
+        }
+      }
+      changeOf.set(name, change)
+      // external не материализуется — версия участвует в diff, физики нет
+      const existing = yield* store.getSnapshot(name, fingerprint)
+      if (existing !== undefined) physicalFingerprint = existing.physicalFp
+      const alreadyBuilt =
+        model.kind._tag === "external" || change === "unchanged" || existing !== undefined
+
+      let backfill: ReadonlyArray<Interval> = []
+      if (model.kind._tag === "incrementalByTimeRange") {
+        const kind = model.kind
+        const wanted = enumerateIntervals(kind.interval, fromIso(kind.start), now)
+        // покрытие привязано к fingerprint: новая версия = пустой учёт = полный
+        // бэкфилл; forward-only наследует done-интервалы старой версии —
+        // пересчитывается только то, чего не было
+        const inherited =
+          reusedFrom === undefined ? [] : yield* store.listIntervals(reusedFrom)
+        const doneByStart = new Map<number, Interval>()
+        for (const record of [...(yield* store.listIntervals(fingerprint)), ...inherited]) {
+          if (record.status !== "done") continue
+          doneByStart.set(fromIso(record.startTs), {
+            start: fromIso(record.startTs),
+            end: fromIso(record.endTs),
+          })
+        }
+        const done = [...doneByStart.values()]
+        const missing = [...missingIntervals(wanted, done)]
+        if (kind.lookback > 0) {
+          // поздно приезжающие данные: последние done-интервалы перечитываются
+          const tail = done.sort((a, b) => a.start - b.start).slice(-kind.lookback)
+          missing.push(...tail)
+        }
+        backfill = mergeIntervals(missing.sort((a, b) => a.start - b.start))
+      }
+
+      actions.push({
+        name,
+        fingerprint,
+        physicalFingerprint,
+        ...(reusedFrom !== undefined ? { reusedFrom } : {}),
+        canonicalAst: ast,
+        change,
+        build: !alreadyBuilt,
+        backfill,
+        // каждый apply сверяет запрос с физикой: upsert / SCD-версионирование
+        refresh:
+          model.kind._tag === "incrementalByUniqueKey" || model.kind._tag === "scdType2",
+      })
+    }
+    for (const [name, fingerprint] of current) {
+      if (!graph.models.has(name)) {
+        actions.push({
+          name,
+          fingerprint,
+          physicalFingerprint: fingerprint,
+          canonicalAst: null,
+          change: "removed",
+          build: false,
+          backfill: [],
+          refresh: false,
+        })
+      }
+    }
+
+    return {
+      env,
+      actions,
+      hasChanges: actions.some(
+        (a) => a.change !== "unchanged" || a.backfill.length > 0 || a.refresh,
+      ),
+    }
+  }).pipe(Effect.withSpan("efmesh.plan", { attributes: { env } }))

package/src/plan/run.ts

@@ -0,0 +1,70 @@
+import { 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 { 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 не вклинится
+ * в чужое применение и наоборот.
+ */
+
+export class RunBlockedByChangesError extends Data.TaggedError("RunBlockedByChangesError")<{
+  readonly env: string
+  readonly changes: ReadonlyArray<string>
+}> {}
+
+export type RunError = ApplyError | LockHeldError | RunBlockedByChangesError
+
+export interface RunOptions extends PlanOptions, ApplyOptions, LockOptions {}
+
+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))
+
+/**
+ * Долгоживущий планировщик для встраивания в Effect-приложение (SPEC §7):
+ * тики по Schedule, ошибка тика логируется и не роняет демона
+ * (кроме занятого лока — это штатно, лог потише).
+ */
+export const daemon = (
+  env: string,
+  models: Iterable<AnyModel>,
+  schedule: Schedule.Schedule<unknown>,
+  options?: RunOptions,
+): Effect.Effect<never, never, EngineAdapter | StateStore> =>
+  run(env, models, options).pipe(
+    Effect.tap((applied) =>
+      applied.built.length > 0
+        ? Effect.logInfo(`run ${env}: обработано ${applied.built.join(", ")}`)
+        : Effect.void,
+    ),
+    Effect.catchTag("LockHeldError", () =>
+      Effect.logDebug(`run ${env}: лок занят другим процессом, пропуск тика`),
+    ),
+    Effect.catchCause((cause) => Effect.logError(`run ${env}: тик упал`, cause)),
+    Effect.schedule(schedule),
+    Effect.andThen(Effect.never),
+  )
+
+export const Runner = { run, daemon } as const