@avytheone/efmesh 0.2.0 → 0.2.1

package/src/core/model.ts

@@ -6,57 +6,57 @@ import { ModelDefinitionError } from "./errors.ts"
 import type { BoundValue, IdentsValue, RefValue, SqlFragment } from "./sql.ts"
 import { collectRefs, parseSqlText, sql, usesBounds } from "./sql.ts"
 
-/** Вид материализации (SPEC §3.1). */
+/** Materialization kind (SPEC §3.1). */
 export type ModelKind =
   | { readonly _tag: "full" }
   | { readonly _tag: "view" }
   | {
-      /** Подставляется в потребителей как подзапрос, без материализации (SPEC §3.1). */
+      /** Inlined into consumers as a subquery, without materialization (SPEC §3.1). */
       readonly _tag: "embedded"
     }
   | {
       readonly _tag: "incrementalByTimeRange"
-      /** Колонка времени, по которой режутся и перечитываются интервалы. */
+      /** Time column that intervals are sliced and reread by. */
       readonly timeColumn: string
-      /** С какого момента бэкфиллить (ISO UTC). */
+      /** Point in time to backfill from (ISO UTC). */
       readonly start: string
-      /** Зерно интервала. */
+      /** Interval grain. */
       readonly interval: IntervalUnit
-      /** Сколько интервалов зерна исполняется одним DELETE+INSERT. */
+      /** How many grain intervals a single DELETE+INSERT executes. */
       readonly batchSize: number
-      /** Сколько последних done-интервалов пересчитывать заново (поздние данные). */
+      /** How many of the most recent done intervals to recompute (late-arriving data). */
       readonly lookback: number
     }
   | { readonly _tag: "external"; readonly source: ExternalSource }
   | {
       readonly _tag: "seed"
-      /** CSV/JSON-файл с данными; содержимое входит в fingerprint. */
+      /** CSV/JSON file with the data; its contents feed into the fingerprint. */
       readonly file: string
       readonly format: "csv" | "json"
     }
   | {
       readonly _tag: "incrementalByUniqueKey"
-      /** Логический ключ upsert'а; каждый apply перегоняет запрос и заменяет строки по ключу. */
+      /** Logical upsert key; every apply reruns the query and replaces rows by key. */
       readonly key: ReadonlyArray<string>
     }
   | {
       /**
-       * Медленно меняющееся измерение, тип 2 (SPEC §3.1): история версий
-       * строк. Каждый apply сверяет запрос с открытыми строками: изменившиеся
-       * и исчезнувшие закрываются (validTo = сейчас), новые версии
-       * вставляются открытыми (validTo IS NULL).
+       * Slowly changing dimension, type 2 (SPEC §3.1): row version history.
+       * Every apply compares the query against the currently open rows: rows
+       * that changed or disappeared are closed (validTo = now), new versions
+       * are inserted open (validTo IS NULL).
        */
       readonly _tag: "scdType2"
       readonly key: ReadonlyArray<string>
-      /** Колонки версионирования — ведёт efmesh: в схеме объявлены, в запросе отсутствуют. */
+      /** Versioning columns — managed by efmesh: declared in the schema, absent from the query. */
       readonly validFrom: string
       readonly validTo: string
     }
 
 /**
- * Определение внешнего источника (SPEC §9.3): таблица движка/ATTACH-базы
- * или файлы по пути/URL (`read_parquet`/`read_csv`/`read_json`, включая
- * HTTPS — REST-JSON ложится сюда же).
+ * External source definition (SPEC §9.3): an engine table/ATTACH database,
+ * or files by path/URL (`read_parquet`/`read_csv`/`read_json`, including
+ * HTTPS — REST-JSON lands here too).
  */
 export type ExternalSource =
   | { readonly _tag: "table"; readonly table: string }
@@ -110,7 +110,7 @@ export const external = {
   }),
 } as const
 
-/** Имя модели: `<схема>.<таблица>`. */
+/** Model name: `<schema>.<table>`. */
 const MODEL_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/
 
 export interface ModelName {
@@ -123,7 +123,7 @@ export const parseModelName = (raw: string): ModelName => {
   if (!MODEL_NAME.test(raw)) {
     throw new ModelDefinitionError({
       model: raw,
-      reason: "имя модели должно быть вида <схема>.<таблица> (латиница, цифры, _)",
+      reason: "model name must be of the form <schema>.<table> (latin letters, digits, _)",
     })
   }
   const [schema, table] = raw.split(".") as [string, string]
@@ -131,10 +131,11 @@ export const parseModelName = (raw: string): ModelName => {
 }
 
 /**
- * Куда складывать физический слой (SPEC §3.3): нативная таблица движка,
- * parquet-файлы озера (интервал = партиция, view поверх read_parquet) или
- * DuckLake-каталог (SPEC §14.5: таблица-на-fingerprint в ATTACH-каталоге —
- * снапшоты и time travel самого DuckLake в довесок, версионность наша).
+ * Where to put the physical layer (SPEC §3.3): a native engine table,
+ * lake parquet files (interval = partition, a view over read_parquet), or
+ * a DuckLake catalog (SPEC §14.5: a table-per-fingerprint in an ATTACH
+ * catalog — DuckLake's own snapshots and time travel come along for free,
+ * but versioning stays ours).
  */
 export type MaterializationTarget = "table" | "parquet" | "ducklake"
 
@@ -143,20 +144,20 @@ export interface ModelConfig<Fields extends Schema.Struct.Fields> {
   readonly kind: ModelKind
   readonly schema: Schema.Struct<Fields>
   readonly description?: string
-  /** Логический первичный ключ; пока метаданные (аудит unique — F2). */
+  /** Logical primary key; metadata only for now (unique audit — F2). */
   readonly grain?: ReadonlyArray<Extract<keyof Fields, string>>
-  /** Цель материализации; по умолчанию — таблица движка. */
+  /** Materialization target; defaults to a native engine table. */
   readonly target?: MaterializationTarget
-  /** Аудиты качества (SPEC §8); в fingerprint не входят. */
+  /** Quality audits (SPEC §8); excluded from the fingerprint. */
   readonly audits?: ReadonlyArray<Audit>
   /**
-   * Экспорт наружу (SPEC §9.3): после аудитов и промоушена готовый
-   * результат уезжает в ATTACH-базу (`attach` — алиас из конфига).
+   * Export outward (SPEC §9.3): after audits and promotion, the finished
+   * result is shipped to an ATTACH database (`attach` — an alias from config).
    */
   readonly export?: { readonly attach: string; readonly table: string }
 }
 
-/** Контекст рендера тела модели. Тело обязано быть чистым: всё изменчивое приходит отсюда. */
+/** Rendering context for a model body. The body must be pure: all mutable state flows in from here. */
 export interface ModelCtx {
   readonly sql: typeof sql
   readonly ref: (model: AnyModel) => RefValue
@@ -165,9 +166,9 @@ export interface ModelCtx {
     ...names: ReadonlyArray<Extract<keyof Fields, string>>
   ) => IdentsValue
   /**
-   * Границы обрабатываемого интервала `[start, end)` — только для
-   * incrementalByTimeRange. При исполнении подставляются литералами,
-   * в canonical-текст попадают плейсхолдерами (SPEC §3).
+   * Bounds of the interval being processed `[start, end)` — only for
+   * incrementalByTimeRange. Substituted with literals at execution time;
+   * rendered as placeholders in the canonical text (SPEC §3).
    */
   readonly start: BoundValue
   readonly end: BoundValue
@@ -182,11 +183,11 @@ export interface Model<Fields extends Schema.Struct.Fields = Schema.Struct.Field
   readonly grain: ReadonlyArray<string>
   readonly target: MaterializationTarget
   readonly audits: ReadonlyArray<Audit>
-  /** Тело, отрендеренное в фрагмент один раз при определении. */
+  /** Body, rendered into a fragment once at definition time. */
   readonly fragment: SqlFragment
-  /** Имена моделей, на которые тело ссылается через `ctx.ref`. */
+  /** Names of the models the body references via `ctx.ref`. */
   readonly deps: ReadonlySet<string>
-  /** Сами модели-источники по имени — схемы для валидации фикстур в testModel. */
+  /** The source models themselves, by name — schemas for fixture validation in testModel. */
   readonly refs: ReadonlyMap<string, AnyModel>
   readonly export?: { readonly attach: string; readonly table: string }
 }
@@ -197,7 +198,7 @@ export type AnyModel = Model<any>
 export const columnNames = (model: AnyModel): ReadonlyArray<string> =>
   Object.keys(model.schema.fields)
 
-/** Общие проверки конфигурации вида модели — для defineModel и defineSqlModel. */
+/** Shared model-kind config checks — for defineModel and defineSqlModel. */
 const validateKindConfig = <Fields extends Schema.Struct.Fields>(
   name: ModelName,
   config: ModelConfig<Fields>,
@@ -205,13 +206,13 @@ const validateKindConfig = <Fields extends Schema.Struct.Fields>(
   if (config.kind._tag === "external") {
     throw new ModelDefinitionError({
       model: name.full,
-      reason: "external-модель не имеет тела — используй defineExternal",
+      reason: "an external model has no body — use defineExternal",
     })
   }
   if (config.kind._tag === "seed") {
     throw new ModelDefinitionError({
       model: name.full,
-      reason: "seed-модель не имеет тела — используй defineSeed",
+      reason: "a seed model has no body — use defineSeed",
     })
   }
   if (config.kind._tag === "incrementalByUniqueKey" || config.kind._tag === "scdType2") {
@@ -219,12 +220,12 @@ const validateKindConfig = <Fields extends Schema.Struct.Fields>(
       if (!(keyColumn in config.schema.fields)) {
         throw new ModelDefinitionError({
           model: name.full,
-          reason: `ключевой колонки «${keyColumn}» нет в схеме модели`,
+          reason: `key column «${keyColumn}» is not in the model schema`,
         })
       }
     }
     if (config.kind.key.length === 0) {
-      throw new ModelDefinitionError({ model: name.full, reason: "key не может быть пустым" })
+      throw new ModelDefinitionError({ model: name.full, reason: "key cannot be empty" })
     }
   }
   if (config.kind._tag === "scdType2") {
@@ -232,27 +233,27 @@ const validateKindConfig = <Fields extends Schema.Struct.Fields>(
     if (validFrom === validTo) {
       throw new ModelDefinitionError({
         model: name.full,
-        reason: "validFrom и validTo не могут совпадать",
+        reason: "validFrom and validTo cannot be the same",
       })
     }
     for (const column of [validFrom, validTo]) {
       if (!(column in config.schema.fields)) {
         throw new ModelDefinitionError({
           model: name.full,
-          reason: `колонки версионирования «${column}» нет в схеме модели — потребители должны её видеть`,
+          reason: `versioning column «${column}» is not in the model schema — consumers must see it`,
         })
       }
       if (config.kind.key.includes(column)) {
         throw new ModelDefinitionError({
           model: name.full,
-          reason: `колонка версионирования «${column}» не может входить в key`,
+          reason: `versioning column «${column}» cannot be part of key`,
         })
       }
     }
     if (config.target === "parquet") {
       throw new ModelDefinitionError({
         model: name.full,
-        reason: "scdType2 закрывает строки на месте — parquet-цель неприменима",
+        reason: "scdType2 closes rows in place — a parquet target is not applicable",
       })
     }
   }
@@ -263,32 +264,32 @@ const validateKindConfig = <Fields extends Schema.Struct.Fields>(
   ) {
     throw new ModelDefinitionError({
       model: name.full,
-      reason: `${config.kind._tag} не материализуется — цель «${config.target}» к нему неприменима`,
+      reason: `${config.kind._tag} is not materialized — target «${config.target}» is not applicable to it`,
     })
   }
   if (config.kind._tag === "incrementalByUniqueKey" && config.target === "parquet") {
     throw new ModelDefinitionError({
       model: name.full,
-      reason: "upsert по ключу в parquet-файлы невозможен — используй target: \"table\"",
+      reason: "key upsert into parquet files is impossible — use target: \"table\"",
     })
   }
   if (config.kind._tag === "incrementalByTimeRange") {
     if (!(config.kind.timeColumn in config.schema.fields)) {
       throw new ModelDefinitionError({
         model: name.full,
-        reason: `timeColumn «${config.kind.timeColumn}» нет в схеме модели`,
+        reason: `timeColumn «${config.kind.timeColumn}» is not in the model schema`,
       })
     }
     if (Number.isNaN(Date.parse(config.kind.start))) {
       throw new ModelDefinitionError({
         model: name.full,
-        reason: `start «${config.kind.start}» — не ISO-время`,
+        reason: `start «${config.kind.start}» is not an ISO time`,
       })
     }
   }
 }
 
-/** Финальная сборка модели из фрагмента — общие инварианты тела. */
+/** Final assembly of a model from a fragment — shared body invariants. */
 const assembleModel = <Fields extends Schema.Struct.Fields>(
   name: ModelName,
   config: ModelConfig<Fields>,
@@ -298,12 +299,12 @@ const assembleModel = <Fields extends Schema.Struct.Fields>(
   if (usesBounds(fragment) && config.kind._tag !== "incrementalByTimeRange") {
     throw new ModelDefinitionError({
       model: name.full,
-      reason: `ctx.start/ctx.end доступны только incrementalByTimeRange, вид модели — ${config.kind._tag}`,
+      reason: `ctx.start/ctx.end are available only in incrementalByTimeRange, model kind is ${config.kind._tag}`,
     })
   }
   const deps = collectRefs(fragment)
   if (deps.has(name.full)) {
-    throw new ModelDefinitionError({ model: name.full, reason: "модель ссылается сама на себя" })
+    throw new ModelDefinitionError({ model: name.full, reason: "model references itself" })
   }
   return {
     _tag: "Model",
@@ -322,9 +323,9 @@ const assembleModel = <Fields extends Schema.Struct.Fields>(
 }
 
 /**
- * Определяет модель. Вызывается на верхнем уровне модуля; тело выполняется
- * ровно один раз — сразу, поэтому ссылки (`ctx.ref`) известны статически
- * и DAG строится без парсинга SQL.
+ * Defines a model. Called at module top level; the body runs exactly once,
+ * immediately, so references (`ctx.ref`) are known statically and the DAG
+ * is built without parsing SQL.
  */
 export const defineModel = <const Fields extends Schema.Struct.Fields>(
   config: ModelConfig<Fields>,
@@ -343,10 +344,10 @@ export const defineModel = <const Fields extends Schema.Struct.Fields>(
       const known = new Set(Object.keys(model.schema.fields))
       for (const column of names) {
         if (!known.has(column)) {
-          // недостижимо при честной типизации; защита от `as any`
+          // unreachable under honest typing; guards against `as any`
           throw new ModelDefinitionError({
             model: config.name,
-            reason: `колонки «${column}» нет в схеме модели ${model.name.full}`,
+            reason: `column «${column}» is not in the schema of model ${model.name.full}`,
           })
         }
       }
@@ -360,20 +361,20 @@ export const defineModel = <const Fields extends Schema.Struct.Fields>(
 
 export interface SqlModelConfig<Fields extends Schema.Struct.Fields>
   extends ModelConfig<Fields> {
-  /** Путь к .sql-файлу тела: `@ref(схема.таблица)`, `@start`, `@end`. */
+  /** Path to the .sql body file: `@ref(schema.table)`, `@start`, `@end`. */
   readonly file: string
   /**
-   * Модели, на которые SQL-текст ссылается через `@ref` — значениями,
-   * чтобы DAG и testModel работали как у обычных моделей.
+   * Models the SQL text references via `@ref` — passed by value, so the
+   * DAG and testModel work the same way as for ordinary models.
    */
   readonly refs?: ReadonlyArray<AnyModel>
 }
 
 /**
- * Модель из сырого .sql-файла (SPEC §14.1) — для миграции существующих
- * dbt/sqlmesh-проектов. Типизация ссылок теряется (это честная цена):
- * каждая `@ref` в тексте обязана быть объявлена в `refs`, лишние
- * объявления — ошибка.
+ * Model from a raw .sql file (SPEC §14.1) — for migrating existing
+ * dbt/sqlmesh projects. Reference typing is lost (an honest price to pay):
+ * every `@ref` in the text must be declared in `refs`, and extra
+ * declarations are an error.
  */
 export const defineSqlModel = <const Fields extends Schema.Struct.Fields>(
   config: SqlModelConfig<Fields>,
@@ -386,7 +387,7 @@ export const defineSqlModel = <const Fields extends Schema.Struct.Fields>(
   } catch (cause) {
     throw new ModelDefinitionError({
       model: name.full,
-      reason: `не удалось прочитать ${config.file}: ${String(cause)}`,
+      reason: `could not read ${config.file}: ${String(cause)}`,
     })
   }
   const fragment = parseSqlText(text)
@@ -396,7 +397,7 @@ export const defineSqlModel = <const Fields extends Schema.Struct.Fields>(
     if (!declared.has(ref)) {
       throw new ModelDefinitionError({
         model: name.full,
-        reason: `@ref(${ref}) в ${config.file} не объявлен в refs`,
+        reason: `@ref(${ref}) in ${config.file} is not declared in refs`,
       })
     }
   }
@@ -404,7 +405,7 @@ export const defineSqlModel = <const Fields extends Schema.Struct.Fields>(
     if (!used.has(declaredName)) {
       throw new ModelDefinitionError({
         model: name.full,
-        reason: `модель ${declaredName} объявлена в refs, но @ref в ${config.file} её не использует`,
+        reason: `model ${declaredName} is declared in refs but @ref in ${config.file} does not use it`,
       })
     }
   }
@@ -419,10 +420,10 @@ export interface ExternalConfig<Fields extends Schema.Struct.Fields> {
 }
 
 /**
- * Внешний источник (SPEC §3.1, §9.3): не материализуется, но участвует
- * в DAG и lineage, схема объявляется. В fingerprint входит только
- * *определение* источника — содержимое меняется между запусками, и это
- * нормально для сырья.
+ * External source (SPEC §3.1, §9.3): not materialized, but participates
+ * in the DAG and lineage, and declares a schema. Only the source's
+ * *definition* feeds into the fingerprint — the contents change between
+ * runs, which is normal for raw data.
  */
 export const defineExternal = <const Fields extends Schema.Struct.Fields>(
   config: ExternalConfig<Fields>,
@@ -433,7 +434,7 @@ export const defineExternal = <const Fields extends Schema.Struct.Fields>(
   schema: config.schema,
   description: config.description,
   grain: [],
-  target: "table", // не материализуется — поле не используется
+  target: "table", // not materialized — field is unused
   audits: [],
   fragment: { _tag: "SqlFragment", nodes: [] },
   deps: new Set(),
@@ -442,7 +443,7 @@ export const defineExternal = <const Fields extends Schema.Struct.Fields>(
 
 export interface SeedConfig<Fields extends Schema.Struct.Fields> {
   readonly name: string
-  /** Путь к CSV/JSON-файлу; формат — по расширению или явно. */
+  /** Path to the CSV/JSON file; format inferred from the extension or given explicitly. */
   readonly file: string
   readonly format?: "csv" | "json"
   readonly schema: Schema.Struct<Fields>
@@ -451,9 +452,9 @@ export interface SeedConfig<Fields extends Schema.Struct.Fields> {
 }
 
 /**
- * Seed (SPEC §3.1): справочник из файла. В отличие от external, содержимое
- * файла входит в fingerprint — правка данных = новая версия и пересборка;
- * форма проверяется контрактом схемы при сборке.
+ * Seed (SPEC §3.1): a reference table from a file. Unlike external, the
+ * file's contents feed into the fingerprint — editing the data means a new
+ * version and a rebuild; shape is checked by the schema contract at build time.
  */
 export const defineSeed = <const Fields extends Schema.Struct.Fields>(
   config: SeedConfig<Fields>,

package/src/core/sql.ts

@@ -1,9 +1,9 @@
 /**
- * SQL-фрагменты: дерево из текста, ссылок на модели и идентификаторов.
+ * SQL fragments: a tree of text, model references, and identifiers.
  *
- * Тело модели рендерится в фрагмент один раз при определении; в текст SQL
- * фрагмент превращается позже — резолвером ссылок (canonical-рендер для
- * fingerprint, физический — для исполнения).
+ * A model body is rendered into a fragment once at definition time; the
+ * fragment turns into SQL text later — by the reference resolver
+ * (canonical rendering for the fingerprint, physical for execution).
  */
 
 export interface SqlFragment {
@@ -18,30 +18,30 @@ export type SqlNode =
   | { readonly _tag: "Bound"; readonly which: "start" | "end" }
   | { readonly _tag: "Self" }
 
-/** Ссылка на модель, полученная из `ctx.ref(model)`. */
+/** A model reference, obtained from `ctx.ref(model)`. */
 export interface RefValue {
   readonly _tag: "RefValue"
   readonly modelName: string
 }
 
-/** Список колонок, полученный из `ctx.cols(model, ...)`. */
+/** A list of columns, obtained from `ctx.cols(model, ...)`. */
 export interface IdentsValue {
   readonly _tag: "IdentsValue"
   readonly names: ReadonlyArray<string>
 }
 
-/** Граница обрабатываемого интервала — `ctx.start` / `ctx.end` (SPEC §3). */
+/** Bound of the interval being processed — `ctx.start` / `ctx.end` (SPEC §3). */
 export interface BoundValue {
   readonly _tag: "BoundValue"
   readonly which: "start" | "end"
 }
 
-/** Результат самой модели в запросе аудита — `ctx.self` (SPEC §8). */
+/** The model's own result in an audit query — `ctx.self` (SPEC §8). */
 export interface SelfValue {
   readonly _tag: "SelfValue"
 }
 
-/** Скалярные значения инлайнятся как SQL-литералы (детерминированно). */
+/** Scalar values are inlined as SQL literals (deterministically). */
 export type SqlLiteral = string | number | boolean | bigint | null
 
 export type Interpolation =
@@ -124,16 +124,16 @@ export const sql = (
 }
 
 export interface RenderOptions {
-  /** Во что превращается ссылка на модель (physical-таблица, view окружения, логическое имя…). */
+  /** What a model reference turns into (a physical table, an environment view, a logical name…). */
   readonly resolveRef: (modelName: string) => string
   /**
-   * Границы обрабатываемого интервала — готовые SQL-выражения
-   * (`TIMESTAMP '…'` при исполнении). Без них `ctx.start`/`ctx.end`
-   * рендерятся плейсхолдерами `$start`/`$end` — так канонический текст
-   * не зависит от конкретных дат и fingerprint стабилен (SPEC §3, §4).
+   * Bounds of the interval being processed — ready-made SQL expressions
+   * (`TIMESTAMP '…'` at execution time). Without them, `ctx.start`/`ctx.end`
+   * render as `$start`/`$end` placeholders — so the canonical text doesn't
+   * depend on specific dates and the fingerprint stays stable (SPEC §3, §4).
    */
   readonly interval?: { readonly start: string; readonly end: string }
-  /** Во что рендерится `ctx.self` в запросе аудита (физика или подзапрос интервала). */
+  /** What `ctx.self` renders to in an audit query (physical table or interval subquery). */
   readonly self?: string
 }
 
@@ -154,7 +154,7 @@ export const render = (fragment: SqlFragment, options: RenderOptions): string =>
         out += options.interval === undefined ? `$${node.which}` : options.interval[node.which]
         break
       case "Self":
-        if (options.self === undefined) throw new Error("рендер ctx.self без options.self")
+        if (options.self === undefined) throw new Error("rendering ctx.self without options.self")
         out += options.self
         break
     }
@@ -163,10 +163,10 @@ export const render = (fragment: SqlFragment, options: RenderOptions): string =>
 }
 
 /**
- * Парсер сырого SQL-текста (SPEC §14.1): `@ref(схема.таблица)` — ссылка
- * на модель, `@start`/`@end` — границы интервала. Всё остальное — текст
- * как есть. Для миграции существующих dbt/sqlmesh-проектов: типизация
- * ссылок теряется, зависимости объявляются рядом (defineSqlModel.refs).
+ * Parser for raw SQL text (SPEC §14.1): `@ref(schema.table)` is a model
+ * reference, `@start`/`@end` are interval bounds. Everything else is text
+ * as-is. For migrating existing dbt/sqlmesh projects: reference typing is
+ * lost, dependencies are declared alongside it (defineSqlModel.refs).
  */
 export const parseSqlText = (text: string): SqlFragment => {
   const nodes: Array<SqlNode> = []
@@ -195,6 +195,6 @@ export const collectRefs = (fragment: SqlFragment): ReadonlySet<string> => {
   return refs
 }
 
-/** Использует ли фрагмент границы интервала (валидация вида модели). */
+/** Whether the fragment uses interval bounds (model-kind validation). */
 export const usesBounds = (fragment: SqlFragment): boolean =>
   fragment.nodes.some((node) => node._tag === "Bound")

package/src/discovery.ts

@@ -3,23 +3,31 @@ import { Data, Effect } from "effect"
 import type { AnyModel } from "./core/model.ts"
 
 /**
- * Discovery моделей по glob (SPEC §12): файлы по маскам из конфига
- * импортируются, все экспорты-модели (defineModel/defineExternal/defineSeed/
- * defineSqlModel — у всех _tag: "Model") собираются в проект. Порядок —
- * детерминированный (сортировка путей), два разных определения с одним
- * именем — ошибка загрузки; один и тот же объект, реэкспортированный из
- * нескольких файлов, считается один раз.
+ * Model discovery by glob (SPEC §12): files matching the config's masks are
+ * imported, and every model export (defineModel/defineExternal/defineSeed/
+ * defineSqlModel — all tagged _tag: "Model") joins the project. Order is
+ * deterministic (paths are sorted); two distinct definitions sharing a name
+ * are a load error; the same object re-exported from several files counts
+ * once.
  */
 
 export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
   readonly path: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `model discovery at ${this.path}: ${this.reason}`
+  }
+}
 
 export class DiscoveryConflictError extends Data.TaggedError("DiscoveryConflictError")<{
   readonly name: string
   readonly files: ReadonlyArray<string>
-}> {}
+}> {
+  override get message(): string {
+    return `model «${this.name}» is defined in more than one place: ${this.files.join(", ")}`
+  }
+}
 
 const isModel = (value: unknown): value is AnyModel =>
   typeof value === "object" &&