@avytheone/efmesh 0.2.0 → 0.2.1

package/src/efmesh.ts

@@ -22,17 +22,18 @@ import {
   type PlanOptions,
 } from "./plan/planner.ts"
 import type { SeedReadError } from "./core/errors.ts"
+import { UnknownModelError } from "./core/errors.ts"
 import type { GraphError } from "./core/graph.ts"
 import type { StateError } from "./state/store.ts"
 import { StateStore } from "./state/store.ts"
 import { externalSourceRef, viewRef } from "./plan/naming.ts"
 
 /**
- * Фасад efmesh (SPEC §10): обычные Effect'ы, встраиваемые в любое
- * приложение; CLI — тонкая обёртка над ними.
+ * The efmesh facade (SPEC §10): plain Effects embeddable in any
+ * application; the CLI is a thin wrapper over them.
  */
 export const Efmesh = {
-  /** Посчитать план для окружения, ничего не меняя. Движок нужен для канонизации SQL. */
+  /** Compute a plan for an environment without changing anything. The engine is needed to canonicalize SQL. */
   plan: (
     env: string,
     models: Iterable<AnyModel>,
@@ -52,9 +53,10 @@ export const Efmesh = {
   > => buildGraph(models).pipe(Effect.flatMap((graph) => planChanges(env, graph, options))),
 
   /**
-   * План + применение: физика, бэкфилл интервалов, view-слой, состояние.
-   * Идёт под межпроцессным локом `env:<имя>` (SPEC §14.6) — тем же, что у
-   * run: параллельные мутации окружения из разных процессов отсекаются.
+   * Plan + apply: physics, interval backfill, view layer, state.
+   * Runs under the cross-process lock `env:<name>` (SPEC §14.6) — the same
+   * one `run` uses: concurrent environment mutations from different
+   * processes are cut off.
    */
   apply: (
     env: string,
@@ -67,21 +69,30 @@ export const Efmesh = {
       return yield* applyPlan(plan, graph, options)
     }).pipe(withStateLock(envLockName(env), options?.lockTtlMs)),
 
-  /** Canonical-рендер SQL модели (ссылки — логические имена) для отладки. */
-  render: (models: Iterable<AnyModel>, name: string): Effect.Effect<string, GraphError> =>
-    buildGraph(models).pipe(Effect.map((graph) => canonicalSql(graph, name))),
+  /** Canonical SQL render of a model (refs are logical names), for debugging. */
+  render: (
+    models: Iterable<AnyModel>,
+    name: string,
+  ): Effect.Effect<string, GraphError | UnknownModelError> =>
+    buildGraph(models).pipe(
+      Effect.flatMap((graph) =>
+        graph.models.has(name)
+          ? Effect.succeed(canonicalSql(graph, name))
+          : new UnknownModelError({ model: name }),
+      ),
+    ),
 
-  /** Рендер SQL модели против view-слоя окружения — «как выполнит движок». */
+  /** SQL render of a model against an environment's view layer — "as the engine would run it". */
   renderFor: (
     models: Iterable<AnyModel>,
     name: string,
     env: string,
-  ): Effect.Effect<string, GraphError> =>
+  ): Effect.Effect<string, GraphError | UnknownModelError> =>
     buildGraph(models).pipe(
-      Effect.map((graph) => {
+      Effect.flatMap((graph) => {
         const model = graph.models.get(name)
-        if (model === undefined) throw new Error(`модели ${name} нет в проекте`)
-        // view-слоя у external и embedded нет: источник как есть / подзапрос
+        if (model === undefined) return new UnknownModelError({ model: name })
+        // external and embedded have no view layer: source as-is / subquery
         const resolve = (ref: string): string => {
           const source = graph.models.get(ref)!
           if (source.kind._tag === "external") return externalSourceRef(source.kind.source)
@@ -90,7 +101,7 @@ export const Efmesh = {
           }
           return viewRef(env, source.name)
         }
-        return render(model.fragment, { resolveRef: resolve })
+        return Effect.succeed(render(model.fragment, { resolveRef: resolve }))
       }),
     ),
 } as const

package/src/engine/adapter.ts

@@ -1,13 +1,30 @@
 import { Context, Data, Effect } from "effect"
+import { causeText, sqlSnippet } from "../error-text.ts"
 
+/**
+ * The engine rejected a statement (SPEC §9.1). `cause` is the engine's own
+ * error (DuckDB/Postgres) — never swallowed; `sql` is the statement that
+ * failed; `model` names the culprit when the failure happened while building a
+ * specific model (attached by the executor). The `message` is derived from all
+ * three so an operator or agent sees what the engine said and where, not an
+ * empty `EngineError:` (#13).
+ */
 export class EngineError extends Data.TaggedError("EngineError")<{
   readonly sql: string
   readonly cause: unknown
-}> {}
+  /** The model being built when the engine failed, when known. */
+  readonly model?: string
+}> {
+  override get message(): string {
+    const where = this.model !== undefined ? `[model ${this.model}] ` : ""
+    return `${where}${causeText(this.cause)} — while running SQL: ${sqlSnippet(this.sql)}`
+  }
+}
 
-/** Движок не смог распарсить SQL модели (SPEC §9.2). */
+/** The engine could not parse the model's SQL (SPEC §9.2). */
 export class SqlParseError extends Data.TaggedError("SqlParseError")<{
   readonly sql: string
+  /** The engine parser's own message; also this error's rendered `message`. */
   readonly message: string
 }> {}
 
@@ -17,9 +34,9 @@ export interface EngineColumn {
 }
 
 /**
- * Адаптер движка (SPEC §9.1). Минимальная поверхность: DDL-помощники
- * живут отдельно (executor) и ходят через execute — адаптеру незачем
- * знать про физический/виртуальный слой.
+ * Engine adapter (SPEC §9.1). A minimal surface: DDL helpers live separately
+ * (executor) and go through execute — the adapter has no need to know about
+ * the physical/virtual layer.
  */
 export type Dialect = "duckdb" | "postgres"
 
@@ -30,19 +47,19 @@ export interface Engine {
   ) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, EngineError>
   readonly execute: (sql: string) => Effect.Effect<void, EngineError>
   /**
-   * Набор стейтментов одной транзакцией движка, откат при любой ошибке.
-   * Примитив адаптера, а не BEGIN/COMMIT через execute: на пуле соединений
-   * (Postgres) отдельные вызовы разъехались бы по разным соединениям.
+   * A set of statements in one engine transaction, rolled back on any error.
+   * An adapter primitive rather than BEGIN/COMMIT via execute: on a connection
+   * pool (Postgres) separate calls would scatter across different connections.
    */
   readonly transaction: (
     statements: ReadonlyArray<string>,
   ) => Effect.Effect<void, EngineError>
-  /** Имена и типы колонок запроса без его выполнения (контракт схемы, SPEC §3.2). */
+  /** Names and types of a query's columns without executing it (schema contract, SPEC §3.2). */
   readonly describe: (sql: string) => Effect.Effect<ReadonlyArray<EngineColumn>, EngineError>
   /**
-   * Канонический вид SELECT-запроса для fingerprint (SPEC §4, §9.2):
-   * парсинг родным парсером движка, нормализация, детерминированная
-   * сериализация. Переформатирование текста не меняет результат.
+   * The canonical form of a SELECT query for the fingerprint (SPEC §4, §9.2):
+   * parsing by the engine's native parser, normalization, deterministic
+   * serialization. Reformatting the text does not change the result.
    */
   readonly canonicalize: (sql: string) => Effect.Effect<string, EngineError | SqlParseError>
 }

package/src/engine/duckdb.ts

@@ -4,9 +4,9 @@ import type { Engine, EngineColumn } from "./adapter.ts"
 import { EngineAdapter, EngineError, SqlParseError } from "./adapter.ts"
 
 /**
- * AST от json_serialize_sql содержит позиции токенов (query_location) —
- * единственное, чем отличаются одинаковые по смыслу, но по-разному
- * отформатированные запросы. Вычищаем — остаётся формат-инвариантное ядро.
+ * The AST from json_serialize_sql contains token positions (query_location) —
+ * the only thing that differs between semantically identical but differently
+ * formatted queries. We strip it — leaving a format-invariant core.
  */
 const stripLocations = (value: unknown): unknown => {
   if (Array.isArray(value)) return value.map(stripLocations)
@@ -22,7 +22,7 @@ const stripLocations = (value: unknown): unknown => {
 }
 
 export interface DuckDBEngineOptions {
-  /** Путь к файлу базы; по умолчанию in-memory. */
+  /** Path to the database file; by default in-memory. */
   readonly path?: string
 }
 
@@ -65,8 +65,8 @@ export const DuckDBEngineLive = (
           ),
         )
 
-      // одно соединение: параллельные транзакции сериализуются семафором,
-      // чтобы фибры не перемежали чужие BEGIN/COMMIT
+      // single connection: parallel transactions are serialized by a semaphore
+      // so fibers do not interleave each other's BEGIN/COMMIT
       const transactionLock = yield* Semaphore.make(1)
 
       const service: Engine = {
@@ -101,7 +101,7 @@ export const DuckDBEngineLive = (
                 readonly error: boolean
                 readonly error_message?: string
               }
-              // ошибка парсинга приходит содержимым JSON, не исключением
+              // a parse error arrives as JSON content, not as an exception
               if (ast.error) {
                 return new SqlParseError({
                   sql: sqlText,

package/src/engine/postgres.ts

@@ -5,17 +5,17 @@ import type { Engine, EngineColumn } from "./adapter.ts"
 import { EngineAdapter, EngineError, SqlParseError } from "./adapter.ts"
 
 /**
- * Postgres-адаптер (SPEC §9.1, F3) поверх встроенного клиента Bun (`Bun.SQL`):
- * пул соединений из коробки — транзакция закрепляется за одним соединением
- * через sql.begin, остальные запросы свободно распределяются по пулу,
- * что и даёт честный параллелизм бэкфилла (SPEC §5.3).
+ * Postgres adapter (SPEC §9.1, F3) over Bun's built-in client (`Bun.SQL`):
+ * a connection pool out of the box — a transaction is pinned to a single
+ * connection via sql.begin, the rest of the queries are distributed freely
+ * across the pool, which is what gives honest backfill parallelism (SPEC §5.3).
  *
- * Канонизация — libpg_query (WASM-сборка парсера самого Postgres, SPEC §9.2):
- * дерево разбора с вычищенными позициями токенов формат-инвариантно,
- * как и json_serialize_sql у DuckDB.
+ * Canonicalization — libpg_query (a WASM build of Postgres's own parser, SPEC
+ * §9.2): the parse tree with token positions stripped is format-invariant,
+ * just like DuckDB's json_serialize_sql.
  */
 
-/** Позиции токенов (location) — единственная формат-зависимость дерева libpg_query. */
+/** Token positions (location) — the only format-dependency of the libpg_query tree. */
 const stripLocations = (value: unknown): unknown => {
   if (Array.isArray(value)) return value.map(stripLocations)
   if (value !== null && typeof value === "object") {
@@ -30,15 +30,15 @@ const stripLocations = (value: unknown): unknown => {
 }
 
 /**
- * Канонизация Postgres-SQL — чистая (libpg_query, сервер не нужен);
- * вынесена из Layer, чтобы golden-тесты могли заморозить канон
- * независимо от пула (SPEC §4: канонизация = контракт fingerprint).
+ * Postgres-SQL canonicalization is pure (libpg_query, no server needed);
+ * lifted out of the Layer so golden tests can freeze the canon independently
+ * of the pool (SPEC §4: canonicalization = the fingerprint contract).
  */
 export const canonicalizePostgresSql = (
   sqlText: string,
 ): Effect.Effect<string, SqlParseError> => {
-  // $start/$end канонического рендера — не синтаксис Postgres;
-  // детерминированная замена на $1/$2 сохраняет стабильность fingerprint
+  // $start/$end of the canonical render are not Postgres syntax;
+  // a deterministic replacement with $1/$2 keeps the fingerprint stable
   const parameterized = sqlText.replace(/\$start\b/g, "$1").replace(/\$end\b/g, "$2")
   return Effect.tryPromise({
     try: () => parse(parameterized),
@@ -51,9 +51,9 @@ export const canonicalizePostgresSql = (
 }
 
 export interface PostgresEngineOptions {
-  /** postgres://… или unix-сокет через ?host=/путь. */
+  /** postgres://… or a unix socket via ?host=/path. */
   readonly url: string
-  /** Размер пула соединений; по умолчанию 8. */
+  /** Connection pool size; by default 8. */
   readonly max?: number
 }
 
@@ -89,8 +89,8 @@ export const PostgresEngineLive = (
               }),
             catch: (cause) => new EngineError({ sql: statements.join(";\n"), cause }),
           }).pipe(Effect.asVoid),
-        // DESCRIBE у Postgres нет: временный view на одном соединении
-        // (sql.begin) даёт имена и типы из каталога без выполнения запроса
+        // Postgres has no DESCRIBE: a temporary view on a single connection
+        // (sql.begin) gives names and types from the catalog without running the query
         describe: (sqlText) =>
           Effect.tryPromise({
             try: () =>

package/src/error-text.ts

@@ -0,0 +1,35 @@
+/**
+ * Message-building helpers shared by tagged errors (#13). Every error's
+ * `message` is DERIVED from its typed fields — no information lives only in a
+ * formatted string, and a vacuous message is constructively impossible: the
+ * culprit and the underlying cause are always carried in fields and rendered
+ * here. Kept out of the public API on purpose (internal plumbing).
+ */
+
+/**
+ * Human text of an unknown caught value — the engine/syscall/parser's own
+ * message. This is the thing the code cannot invent: it must be surfaced from
+ * whatever the underlying layer threw, never swallowed.
+ */
+export const causeText = (cause: unknown): string => {
+  if (cause instanceof Error) {
+    return cause.message !== "" ? cause.message : cause.name
+  }
+  if (typeof cause === "string") return cause
+  if (cause === undefined) return "unknown cause"
+  if (typeof cause === "object" && cause !== null && "message" in cause) {
+    const message = (cause as { readonly message: unknown }).message
+    if (typeof message === "string" && message !== "") return message
+  }
+  return String(cause)
+}
+
+/**
+ * One-line SQL context for an error message: whitespace collapsed, truncated
+ * with an ellipsis. The full statement stays in the error's `sql` field for
+ * programmatic consumers; this is only the human-readable tail.
+ */
+export const sqlSnippet = (sql: string, max = 200): string => {
+  const collapsed = sql.replace(/\s+/g, " ").trim()
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1)}…` : collapsed
+}

package/src/index.ts

@@ -1,11 +1,11 @@
 /**
- * Публичное API efmesh (F6): осознанный whitelist вместо `export *` —
- * всё, что экспортировано здесь, становится semver-обязательством пакета.
- * Внутренности (naming, lock-хелперы, executor, planner, fingerprint-кухня)
- * намеренно не экспортируются; юнит-тесты моделей — `efmesh/testing`.
+ * Public API of efmesh (F6): a deliberate whitelist instead of `export *` —
+ * everything exported here becomes a semver commitment of the package.
+ * Internals (naming, lock helpers, executor, planner, fingerprint plumbing)
+ * are deliberately not exported; unit-testing models lives in `efmesh/testing`.
  */
 
-// — определение проекта: модели, виды, аудиты, конфиг —
+// — project definition: models, kinds, audits, config —
 export {
   defineExternal,
   defineModel,
@@ -30,7 +30,7 @@ export { audit, type Audit, type AuditCtx } from "./core/audit.ts"
 export { defineConfig, type EfmeshConfig } from "./config.ts"
 export { discoverModels, DiscoveryConflictError, DiscoveryError } from "./discovery.ts"
 
-// — фасад и операции: обычные Effect'ы для встраивания (SPEC §10) —
+// — facade and operations: plain Effects for embedding (SPEC §10) —
 export { Efmesh } from "./efmesh.ts"
 export { run, daemon, Runner, RunBlockedByChangesError, type RunError, type RunOptions } from "./plan/run.ts"
 export { janitor, type JanitorOptions, type JanitorReport } from "./plan/janitor.ts"
@@ -68,7 +68,7 @@ export {
   type ScheduleTarget,
 } from "./plan/schedule.ts"
 
-// — план и применение: типы результата и опций —
+// — plan and apply: result and options types —
 export type {
   ChangeCategory,
   Plan,
@@ -94,17 +94,18 @@ export { SchemaMismatchError } from "./plan/contract.ts"
 export { LockHeldError, type LockOptions } from "./plan/lock.ts"
 export { FINGERPRINT_VERSION } from "./plan/fingerprint.ts"
 
-// — граф: составные ошибки загрузки проекта —
+// — graph: compound project-loading errors —
 export {
   DagCycleError,
   DuplicateModelError,
   ModelDefinitionError,
   SeedReadError,
   UnknownDependencyError,
+  UnknownModelError,
 } from "./core/errors.ts"
 export type { GraphError } from "./core/graph.ts"
 
-// — движки: слои и сервис (кастомные обёртки — например, для тестов) —
+// — engines: layers and service (custom wrappers — e.g. for tests) —
 export {
   EngineAdapter,
   EngineError,
@@ -120,7 +121,7 @@ export {
   type PostgresEngineOptions,
 } from "./engine/postgres.ts"
 
-// — state store: слои, миграции, записи —
+// — state store: layers, migrations, records —
 export {
   StateStore,
   StateError,
@@ -140,5 +141,5 @@ export {
   type PostgresStateOptions,
 } from "./state/postgres.ts"
 
-// — интервалы: границы для options.now и разбор отчётов —
+// — intervals: bounds for options.now and report parsing —
 export { fromIso, toIso, type Interval, type IntervalUnit } from "./core/interval.ts"

package/src/init.ts

@@ -3,57 +3,129 @@ import * as NodePath from "node:path"
 import { Data, Effect } from "effect"
 
 /**
- * `efmesh init` (SPEC §12): скаффолд минимального проекта — конфиг,
- * пара моделей (seed + витрина с аудитом) и данные к ним. Ничего не
- * перезаписывает: существующий efmesh.config.ts — честная ошибка.
+ * `efmesh init` (SPEC §12): scaffold a minimal, runnable project — config, a
+ * seed, an incremental model with a backfill and a blocking audit, and a full
+ * rollup on top. `efmesh plan dev && efmesh apply dev` works immediately, with
+ * no data-generation step: the seed carries its own timestamped rows.
+ *
+ * The example is written to *teach* the plan/apply lifecycle to a first
+ * reader (often an evaluating agent): a seed whose content is versioned, an
+ * incrementalByTimeRange model that backfills day by day, and an audit that
+ * gates each interval. Overwrites nothing: an existing file is an honest error.
  */
 
 export class InitError extends Data.TaggedError("InitError")<{
   readonly path: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `${this.path}: ${this.reason}`
+  }
+}
 
 const MODELS_TS = `import { Schema } from "effect"
 import { audit, defineModel, defineSeed, kind } from "@avytheone/efmesh"
 
-// seed: справочник из файла; содержимое входит в fingerprint —
-// правка CSV = новая версия и пересборка
-export const departments = defineSeed({
-  name: "ref.departments",
-  file: "seeds/departments.csv",
-  schema: Schema.Struct({ dept: Schema.String, floor: Schema.Number }),
+// A seed is reference data loaded from a file. Its *content* feeds the
+// fingerprint, so editing events.csv mints a new version and forces a rebuild
+// of everything downstream — that is the guarantee the fingerprint buys you.
+export const events = defineSeed({
+  name: "raw.events",
+  file: "seeds/events.csv",
+  schema: Schema.Struct({
+    event_at: Schema.DateTimeUtc,
+    region: Schema.String,
+    amount: Schema.Number,
+  }),
+  description: "Raw revenue events, one row per transaction",
 })
 
-// витрина: full-модель с контрактом схемы и blocking-аудитом
-export const floors = defineModel(
+// An incrementalByTimeRange model owns an interval ledger: apply backfills one
+// day at a time from \`start\`, DELETE+INSERT per interval, and records which
+// days are done. Re-running only fills the gaps — that is backfill. \`lookback: 1\`
+// re-reads the most recent done day so late-arriving events still land.
+//
+// \`timeColumn\` names the OUTPUT column intervals are sliced by (here \`day\`); the
+// body filters its source with ctx.start/ctx.end, the half-open bounds
+// [start, end) of the interval being built. The blocking audit runs against
+// each freshly loaded interval and, on a violation, fails apply for that day.
+export const dailyRevenue = defineModel(
   {
-    name: "mart.floors",
+    name: "mart.daily_revenue",
+    kind: kind.incrementalByTimeRange({
+      timeColumn: "day",
+      start: "2026-01-01T00:00:00Z",
+      interval: "day",
+      lookback: 1,
+    }),
+    schema: Schema.Struct({
+      day: Schema.DateTimeUtc,
+      region: Schema.String,
+      revenue: Schema.Number,
+    }),
+    grain: ["day", "region"],
+    description: "Revenue per region per day, backfilled interval by interval",
+    audits: [audit.notNull("revenue")],
+  },
+  (ctx) => ctx.sql\`
+    SELECT
+      date_trunc('day', event_at) AS day,
+      region,
+      sum(amount)::BIGINT AS revenue
+    FROM \${ctx.ref(events)}
+    WHERE event_at >= \${ctx.start} AND event_at < \${ctx.end}
+    GROUP BY day, region
+  \`,
+)
+
+// A full model rebuilds in one shot from the whole physical table of its
+// parent. It depends on the incremental above via ctx.ref, so it sits
+// downstream in the DAG and rebuilds when that parent's fingerprint changes.
+export const regionRevenue = defineModel(
+  {
+    name: "mart.region_revenue",
     kind: kind.full(),
-    schema: Schema.Struct({ floor: Schema.Number, depts: Schema.Number }),
-    audits: [audit.notNull("floor")],
+    schema: Schema.Struct({
+      region: Schema.String,
+      revenue: Schema.Number,
+      days: Schema.Number,
+    }),
+    description: "Lifetime revenue and active days per region",
   },
   (ctx) => ctx.sql\`
-    SELECT floor, count(*)::INT AS depts
-    FROM \${ctx.ref(departments)}
-    GROUP BY floor
+    SELECT region, sum(revenue)::BIGINT AS revenue, count(*)::BIGINT AS days
+    FROM \${ctx.ref(dailyRevenue)}
+    GROUP BY region
+    ORDER BY revenue DESC
   \`,
 )
 `
 
 const CONFIG_TS = `import { defineConfig } from "@avytheone/efmesh"
-import { departments, floors } from "./models.ts"
+import { dailyRevenue, events, regionRevenue } from "./models.ts"
 
+// The project config is typed TypeScript, not YAML. The CLI imports it and
+// assembles the engine and state layers. Defaults target a local DuckDB file
+// (efmesh.duckdb) and a SQLite state store (efmesh.state.sqlite) next to it.
 export default defineConfig({
-  models: [departments, floors],
-  // engine: { url: "postgres://…" },  // вместо DuckDB-файла
-  // lake: { path: "lake" },           // для target: "parquet"
+  models: [events, dailyRevenue, regionRevenue],
+  // engine: { url: "postgres://…" },   // Postgres instead of the DuckDB file
+  // lake: { path: "lake" },            // enables target: "parquet" on a model
 })
 `
 
-const SEED_CSV = `dept,floor
-ОРИТ,3
-терапия,2
-хирургия,3
+// Timestamps in plain \`YYYY-MM-DD HH:MM:SS\` so DuckDB's read_csv autodetects a
+// TIMESTAMP column; two regions across three days give the backfill several
+// non-empty intervals to fill.
+const SEED_CSV = `event_at,region,amount
+2026-01-01 08:30:00,north,100
+2026-01-01 14:00:00,north,150
+2026-01-01 16:45:00,south,90
+2026-01-02 09:10:00,north,120
+2026-01-02 11:20:00,south,200
+2026-01-02 18:00:00,south,60
+2026-01-03 07:50:00,north,80
+2026-01-03 13:30:00,south,140
 `
 
 export const scaffold = (dir: string): Effect.Effect<ReadonlyArray<string>, InitError> =>
@@ -62,13 +134,13 @@ export const scaffold = (dir: string): Effect.Effect<ReadonlyArray<string>, Init
     const files: ReadonlyArray<readonly [string, string]> = [
       ["efmesh.config.ts", CONFIG_TS],
       ["models.ts", MODELS_TS],
-      ["seeds/departments.csv", SEED_CSV],
+      ["seeds/events.csv", SEED_CSV],
     ]
     for (const [relative] of files) {
       if (existsSync(NodePath.join(root, relative))) {
         return yield* new InitError({
           path: NodePath.join(root, relative),
-          reason: "файл уже существует — init ничего не перезаписывает",
+          reason: "file already exists — init overwrites nothing",
         })
       }
     }

package/src/plan/audit-run.ts

@@ -8,13 +8,13 @@ import type { EngineError } from "../engine/adapter.ts"
 import { externalSourceRef, viewRef } from "./naming.ts"
 
 /**
- * Автономный прогон аудитов (SPEC §8, F4): проверяет то, что окружение
- * отдаёт потребителям СЕЙЧАС — view-слой целиком, не свежезагруженный
- * интервал, как в apply. Ловит деградацию задним числом: поздние данные
- * через lookback, руками поправленную физику, дрейф external-источников.
+ * Standalone audit run (SPEC §8, F4): checks what the environment serves to
+ * consumers RIGHT NOW — the whole view-layer, not the freshly loaded interval
+ * as in apply. Catches degradation after the fact: late data via lookback,
+ * physical storage edited by hand, drift of external sources.
  *
- * Ничего не меняет и не помечает; отчёт целиком — упавший blocking-аудит
- * не прячет следующие за ним.
+ * Changes and marks nothing; the report is complete — a failed blocking audit
+ * does not hide the ones that follow it.
  */
 
 export interface AuditRunResult {
@@ -26,21 +26,29 @@ export interface AuditRunResult {
 
 export interface AuditRunReport {
   readonly results: ReadonlyArray<AuditRunResult>
-  /** Суммарные нарушения blocking-аудитов — не ноль ⇒ окружению нельзя верить. */
+  /** Total blocking-audit violations — nonzero ⇒ the environment cannot be trusted. */
   readonly blockingViolations: number
 }
 
-/** Запрошенной модели нет в проекте (или у неё нет аудитов — нечего гонять). */
+/** The requested model is not in the project (or has no audits — nothing to run). */
 export class AuditTargetError extends Data.TaggedError("AuditTargetError")<{
   readonly model: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `audit target «${this.model}»: ${this.reason}`
+  }
+}
 
-/** Итог для CLI: blocking-аудиты окружения нарушены. */
+/** Result for the CLI: the environment's blocking audits are violated. */
 export class EnvironmentAuditError extends Data.TaggedError("EnvironmentAuditError")<{
   readonly env: string
   readonly blockingViolations: number
-}> {}
+}> {
+  override get message(): string {
+    return `environment «${this.env}»: ${this.blockingViolations} blocking audit violation(s)`
+  }
+}
 
 const selfFor = (graph: ModelGraph, env: string, model: AnyModel): string => {
   const resolve = (ref: string): string => {
@@ -51,7 +59,7 @@ const selfFor = (graph: ModelGraph, env: string, model: AnyModel): string => {
     }
     return viewRef(env, source.name)
   }
-  // embedded не материализуется — аудируется подзапрос против view окружения
+  // embedded is not materialized — the subquery is audited against the environment's view
   if (model.kind._tag === "embedded") {
     return `(${render(model.fragment, { resolveRef: resolve })})`
   }
@@ -68,7 +76,7 @@ export const auditEnvironment = (
     const graph = yield* buildGraph(models)
     for (const name of only ?? []) {
       if (!graph.models.has(name)) {
-        return yield* new AuditTargetError({ model: name, reason: "модели нет в проекте" })
+        return yield* new AuditTargetError({ model: name, reason: "model is not in the project" })
       }
     }
     const wanted = only === undefined ? undefined : new Set(only)