@avytheone/efmesh 0.1.0-beta.1

package/src/core/audit.ts

@@ -0,0 +1,88 @@
+import { Data, type Schema } from "effect"
+import type { SelfValue, SqlFragment, SqlLiteral } from "./sql.ts"
+import { quoteIdent, sql } from "./sql.ts"
+
+/** Blocking-аудит нашёл нарушения: снапшот/интервал не считается годным. */
+export class AuditFailure extends Data.TaggedError("AuditFailure")<{
+  readonly model: string
+  readonly audit: string
+  readonly violations: number
+}> {}
+
+/**
+ * Аудит (SPEC §8) — SQL-предикат над результатом модели: запрос возвращает
+ * НАРУШАЮЩИЕ строки, непустой результат = провал. `ctx.self` рендерится
+ * в физику снапшота (у incremental — в подзапрос обработанного интервала,
+ * аудит проверяет то, что только что загрузили, а не всю историю).
+ *
+ * blocking-аудит (по умолчанию) роняет apply: интервал помечается failed,
+ * view не промоутится. warn — лог + конвейер едет дальше.
+ */
+export interface Audit {
+  readonly name: string
+  readonly blocking: boolean
+  /** Запрос нарушений; содержит узел Self. */
+  readonly fragment: SqlFragment
+}
+
+export interface AuditCtx {
+  readonly sql: typeof sql
+  readonly self: SelfValue
+}
+
+const SELF: SelfValue = { _tag: "SelfValue" }
+
+/** Билдеры типизированы колонками модели через параметр Fields. */
+export const audit = {
+  notNull: <Fields extends Schema.Struct.Fields>(
+    column: Extract<keyof Fields, string>,
+  ): Audit => ({
+    name: `not_null(${column})`,
+    blocking: true,
+    fragment: sql`SELECT * FROM ${SELF} WHERE ${idents(column)} IS NULL`,
+  }),
+
+  unique: <Fields extends Schema.Struct.Fields>(
+    ...columns: ReadonlyArray<Extract<keyof Fields, string>>
+  ): Audit => ({
+    name: `unique(${columns.join(", ")})`,
+    blocking: true,
+    fragment: sql`
+      SELECT ${idents(...columns)}, count(*) AS duplicates
+      FROM ${SELF}
+      GROUP BY ${idents(...columns)}
+      HAVING count(*) > 1`,
+  }),
+
+  accepted: <Fields extends Schema.Struct.Fields>(
+    column: Extract<keyof Fields, string>,
+    values: ReadonlyArray<SqlLiteral>,
+  ): Audit => ({
+    name: `accepted(${column})`,
+    blocking: true,
+    fragment: sql`
+      SELECT * FROM ${SELF}
+      WHERE ${idents(column)} IS NOT NULL
+        AND ${idents(column)} NOT IN (${valuesList(values)})`,
+  }),
+
+  custom: (name: string, body: (ctx: AuditCtx) => SqlFragment): Audit => ({
+    name,
+    blocking: true,
+    fragment: body({ sql, self: SELF }),
+  }),
+
+  /** Понизить аудит до предупреждения: лог вместо провала. */
+  warn: (base: Audit): Audit => ({ ...base, blocking: false }),
+} as const
+
+const idents = (...names: ReadonlyArray<string>): SqlFragment => ({
+  _tag: "SqlFragment",
+  nodes: [{ _tag: "Text", text: names.map(quoteIdent).join(", ") }],
+})
+
+const valuesList = (values: ReadonlyArray<SqlLiteral>): SqlFragment =>
+  values.reduce<SqlFragment>(
+    (acc, value, index) => (index === 0 ? sql`${value}` : sql`${acc}, ${value}`),
+    { _tag: "SqlFragment", nodes: [] },
+  )

package/src/core/errors.ts

@@ -0,0 +1,27 @@
+import { Data } from "effect"
+
+/** Некорректная конфигурация модели: битое имя, self-ref и т.п. Бросается на этапе загрузки модуля. */
+export class ModelDefinitionError extends Data.TaggedError("ModelDefinitionError")<{
+  readonly model: string
+  readonly reason: string
+}> {}
+
+export class DuplicateModelError extends Data.TaggedError("DuplicateModelError")<{
+  readonly name: string
+}> {}
+
+export class UnknownDependencyError extends Data.TaggedError("UnknownDependencyError")<{
+  readonly model: string
+  readonly dependency: string
+}> {}
+
+export class DagCycleError extends Data.TaggedError("DagCycleError")<{
+  readonly cycle: ReadonlyArray<string>
+}> {}
+
+/** Файл seed-модели не читается — fingerprint и сборка невозможны. */
+export class SeedReadError extends Data.TaggedError("SeedReadError")<{
+  readonly model: string
+  readonly file: string
+  readonly cause: unknown
+}> {}

package/src/core/graph.ts

@@ -0,0 +1,76 @@
+import { Effect } from "effect"
+import { DagCycleError, DuplicateModelError, UnknownDependencyError } from "./errors.ts"
+import type { AnyModel } from "./model.ts"
+
+export interface ModelGraph {
+  readonly models: ReadonlyMap<string, AnyModel>
+  /** Топологический порядок: родители раньше детей. */
+  readonly order: ReadonlyArray<string>
+  /** Прямые потомки: кто ссылается на данную модель. */
+  readonly dependents: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+export type GraphError = DuplicateModelError | UnknownDependencyError | DagCycleError
+
+/** Собирает DAG из набора моделей: дубликаты, неизвестные зависимости, циклы — типизированные ошибки. */
+export const buildGraph = (
+  input: Iterable<AnyModel>,
+): Effect.Effect<ModelGraph, GraphError> =>
+  Effect.gen(function* () {
+    const models = new Map<string, AnyModel>()
+    for (const model of input) {
+      if (models.has(model.name.full)) {
+        return yield* new DuplicateModelError({ name: model.name.full })
+      }
+      models.set(model.name.full, model)
+    }
+
+    const dependents = new Map<string, Set<string>>()
+    for (const name of models.keys()) dependents.set(name, new Set())
+    for (const model of models.values()) {
+      for (const dep of model.deps) {
+        if (!models.has(dep)) {
+          return yield* new UnknownDependencyError({ model: model.name.full, dependency: dep })
+        }
+        dependents.get(dep)!.add(model.name.full)
+      }
+    }
+
+    // Кан: считаем входящие степени (число зависимостей), снимаем нулевые.
+    const inDegree = new Map<string, number>()
+    for (const [name, model] of models) inDegree.set(name, model.deps.size)
+    // сортировка очереди — чтобы порядок был детерминированным между запусками
+    const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([n]) => n).sort()
+    const order: Array<string> = []
+    while (queue.length > 0) {
+      const name = queue.shift()!
+      order.push(name)
+      for (const child of [...dependents.get(name)!].sort()) {
+        const left = inDegree.get(child)! - 1
+        inDegree.set(child, left)
+        if (left === 0) queue.push(child)
+      }
+    }
+
+    if (order.length !== models.size) {
+      const cycle = [...models.keys()].filter((n) => !order.includes(n))
+      return yield* new DagCycleError({ cycle })
+    }
+
+    return { models, order, dependents }
+  })
+
+/** Все транзитивные потомки модели (для breaking-каскада в плане). */
+export const transitiveDependents = (graph: ModelGraph, name: string): ReadonlySet<string> => {
+  const out = new Set<string>()
+  const stack = [name]
+  while (stack.length > 0) {
+    for (const child of graph.dependents.get(stack.pop()!) ?? []) {
+      if (!out.has(child)) {
+        out.add(child)
+        stack.push(child)
+      }
+    }
+  }
+  return out
+}

package/src/core/interval.ts

@@ -0,0 +1,119 @@
+/**
+ * Интервальная арифметика (SPEC §2, §5.3): полуинтервалы `[start, end)`
+ * времени UTC, выровненные по зерну модели. Учёт заполненных интервалов —
+ * основа инкрементальности и бэкфилла; здесь только чистая математика,
+ * состояние живёт в state store.
+ *
+ * Внутреннее представление — epoch millis: зёрна day/hour в UTC не зависят
+ * от календаря, деление с округлением вниз даёт выравнивание.
+ */
+
+export type IntervalUnit = "day" | "hour"
+
+export interface Interval {
+  readonly start: number
+  readonly end: number
+}
+
+export const unitMillis: Record<IntervalUnit, number> = {
+  day: 86_400_000,
+  hour: 3_600_000,
+}
+
+export const floorTo = (unit: IntervalUnit, ms: number): number => {
+  const step = unitMillis[unit]
+  return Math.floor(ms / step) * step
+}
+
+/**
+ * Все завершённые интервалы зерна от `startMs` до `nowMs`:
+ * начало выравнивается вниз, последний интервал — тот, что уже закончился
+ * (`end <= floor(now)` — недописанное «сегодня» не считается).
+ */
+export const enumerateIntervals = (
+  unit: IntervalUnit,
+  startMs: number,
+  nowMs: number,
+): ReadonlyArray<Interval> => {
+  const step = unitMillis[unit]
+  const from = floorTo(unit, startMs)
+  const to = floorTo(unit, nowMs)
+  const intervals: Array<Interval> = []
+  for (let start = from; start + step <= to; start += step) {
+    intervals.push({ start, end: start + step })
+  }
+  return intervals
+}
+
+/** `wanted` минус `covered` (сравнение по `start`; интервалы одного зерна). */
+export const missingIntervals = (
+  wanted: ReadonlyArray<Interval>,
+  covered: ReadonlyArray<Interval>,
+): ReadonlyArray<Interval> => {
+  const done = new Set(covered.map((i) => i.start))
+  return wanted.filter((i) => !done.has(i.start))
+}
+
+/** Смежные интервалы сливаются в непрерывные диапазоны (вход — отсортированный). */
+export const mergeIntervals = (
+  intervals: ReadonlyArray<Interval>,
+): ReadonlyArray<Interval> => {
+  const merged: Array<Interval> = []
+  for (const interval of intervals) {
+    const last = merged[merged.length - 1]
+    if (last !== undefined && last.end === interval.start) {
+      merged[merged.length - 1] = { start: last.start, end: interval.end }
+    } else {
+      merged.push({ ...interval })
+    }
+  }
+  return merged
+}
+
+/**
+ * Режет диапазон на батчи не длиннее `batchSize` интервалов зерна.
+ * Батч — единица исполнения (один DELETE+INSERT), интервал — единица учёта.
+ */
+export const splitIntoBatches = (
+  range: Interval,
+  unit: IntervalUnit,
+  batchSize: number,
+): ReadonlyArray<Interval> => {
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    throw new RangeError(`batchSize должен быть целым ≥ 1, получен ${batchSize}`)
+  }
+  const step = unitMillis[unit] * batchSize
+  const batches: Array<Interval> = []
+  for (let start = range.start; start < range.end; start += step) {
+    batches.push({ start, end: Math.min(start + step, range.end) })
+  }
+  return batches
+}
+
+/** Интервалы зерна внутри диапазона (для поинтервальной отметки done после батча). */
+export const intervalsWithin = (
+  range: Interval,
+  unit: IntervalUnit,
+): ReadonlyArray<Interval> => {
+  const step = unitMillis[unit]
+  const intervals: Array<Interval> = []
+  for (let start = range.start; start < range.end; start += step) {
+    intervals.push({ start, end: Math.min(start + step, range.end) })
+  }
+  return intervals
+}
+
+/** ISO-8601 UTC — формат хранения границ в state store (сортируется лексикографически). */
+export const toIso = (ms: number): string => new Date(ms).toISOString()
+
+export const fromIso = (iso: string): number => {
+  const ms = Date.parse(iso)
+  if (Number.isNaN(ms)) throw new RangeError(`не ISO-время: ${iso}`)
+  return ms
+}
+
+/** Литерал для подстановки границы интервала в SQL DuckDB. */
+export const sqlTimestamp = (ms: number): string => {
+  const iso = new Date(ms).toISOString()
+  return `TIMESTAMP '${iso.slice(0, 10)} ${iso.slice(11, 19)}'`
+}