letopis 1.4.2 → 3.0.0

package/dist/model.d.ts

@@ -17,18 +17,20 @@ export type OnDelete = 'restrict' | 'cascade' | 'unset';
 export interface ClassMeta {
     [key: string]: unknown;
 }
-/** Политика хранения истории (§2.11). */
-export interface HistoryPolicy {
-    all: string;
-    daily?: string;
-    weekly?: string;
-    monthly?: string;
-    yearly?: string;
-    tz?: string;
-}
 type Target = AnyModel | string;
-/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. */
-export declare class End<Many extends boolean = boolean, Required extends boolean = boolean> {
+/** Имя класса цели: у модели — её имя, у строки — сама строка. */
+type TargetName<T> = T extends string ? T : T extends {
+    readonly name: infer N extends string;
+} ? N : string;
+/**
+ * Обязателен ли множественный конец по `min` (для типов): `min` больше нуля — да, нет `min` или ноль — нет, число,
+ * известное только во время выполнения, — неизвестно (`boolean`).
+ */
+type MinRequired<O> = O extends {
+    min: infer N;
+} ? (N extends 0 | undefined ? false : number extends N ? boolean : true) : false;
+/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. `T` — имена классов целей (только для типов). */
+export declare class End<Many extends boolean = boolean, Required extends boolean = boolean, T extends string = string> {
     readonly targets: readonly Target[];
     readonly many: Many;
     readonly required: Required;
@@ -36,6 +38,8 @@ export declare class End<Many extends boolean = boolean, Required extends boolea
     readonly max?: number;
     readonly onDeleteRule?: OnDelete;
     readonly metaData?: Record<string, unknown>;
+    /** Только для вывода типов: имена классов целей — строгие переходы и слоты цепочек (план 2.0, этап 4, п. 1). */
+    readonly __targets?: T;
     constructor(targets: readonly Target[], opts: {
         many: Many;
         required: Required;
@@ -46,22 +50,25 @@ export declare class End<Many extends boolean = boolean, Required extends boolea
     });
     private with;
     /** Необязательный конец. */
-    optional(): End<Many, false>;
+    optional(): End<Many, false, T>;
     /** Правило при удалении цели: restrict (по умолчанию), cascade, unset. */
-    onDelete(rule: OnDelete): End<Many, Required>;
+    onDelete(rule: OnDelete): End<Many, Required, T>;
     /** Метаданные конца (§2.13). */
-    meta(meta: Record<string, unknown>): End<Many, Required>;
+    meta(meta: Record<string, unknown>): End<Many, Required, T>;
     /** Имена классов целей. */
     classNames(): string[];
 }
 /** Одиночный конец; несколько классов — союз: `one(Service, Product)`. По умолчанию обязательный. */
-export declare function one(...targets: Target[]): End<false, true>;
-/** Множественный конец: список целей в одном конце (§4 предложения). */
-export declare function many(target: Target | readonly Target[], opts?: {
+export declare function one<const T extends readonly Target[]>(...targets: T): End<false, true, TargetName<T[number]>>;
+/**
+ * Множественный конец: список целей в одном конце (§4 предложения). Обязателен при `min` больше нуля — `unset()` у него
+ * в цепочке типизированного подключения нет.
+ */
+export declare function many<const T extends Target | readonly Target[], const O extends {
     min?: number;
     max?: number;
     onDelete?: OnDelete;
-}): End<true, boolean>;
+} = Record<never, never>>(target: T, opts?: O): End<true, MinRequired<O>, TargetName<T extends readonly (infer X)[] ? X : T>>;
 type EndsInput = Record<string, End | AnyModel>;
 type EndOf<E> = E extends End<infer M, infer R> ? End<M, R> : End<false, true>;
 type LinkValue<E> = EndOf<E> extends End<true, boolean> ? string[] : string;
@@ -79,39 +86,14 @@ export interface ClassDef<S extends z.ZodRawShape = z.ZodRawShape, E extends End
     fields?: z.ZodObject<S> | S;
     key?: readonly string[];
     onDelete?: Partial<Record<keyof E & string, OnDelete>>;
-    history?: boolean | HistoryPolicy;
+    /** Вести ли журнал версий (по умолчанию да). */
+    history?: boolean;
     ownerDefault?: 'tenant' | 'actor';
     cache?: {
         ttl?: number;
     };
     meta?: ClassMeta;
-    /** Производный класс (план 1.1, §2.4): строки пишет только проектор с этим именем; наследуется. */
-    derivedBy?: string;
-    /**
-     * Агрегаты в базе (план 1.1, §2.4): поле — сумма поля (`sum`) или число (`count: true`) живых строк класса `of` того
-     * же арендатора, чей одиночный конец `via` ведёт на строку; `where` — JSON Schema над данными строки-источника.
-     * Поле считает база, приложение его не пишет. Наследуется, потомок заменяет целиком.
-     */
-    aggregate?: Record<string, AggregateDef>;
 }
-/** Описание одного агрегатного поля: `sum` или `count: true`; `of` — класс-источник (имя или модель). */
-export type AggregateDef = {
-    sum: string;
-    count?: never;
-    of: string | {
-        readonly name: string;
-    };
-    via: string;
-    where?: JsonSchema;
-} | {
-    count: true;
-    sum?: never;
-    of: string | {
-        readonly name: string;
-    };
-    via: string;
-    where?: JsonSchema;
-};
 /** Описание класса в строке `Class` (метасхема `class_metaschema()` в lib/sql/40-class.sql). */
 export interface ClassDescription {
     name: string;
@@ -133,20 +115,12 @@ export interface ClassDescription {
         meta?: Record<string, unknown>;
     }>;
     key?: string[];
-    history?: boolean | HistoryPolicy;
+    history?: boolean;
     ownerDefault?: 'tenant' | 'actor';
     cache?: {
         ttl?: number;
     };
     meta?: ClassMeta;
-    derivedBy?: string;
-    aggregate?: Record<string, {
-        sum?: string;
-        count?: true;
-        of: string;
-        via: string;
-        where?: JsonSchema;
-    }>;
 }
 /** Правило refine, которое не попадёт в базу: проверяется только в библиотеке. */
 export interface LostRule {
@@ -155,7 +129,36 @@ export interface LostRule {
 }
 type DataOf<P, S extends z.ZodRawShape> = P extends Model<string, infer PD, unknown> ? Omit<PD, keyof z.output<z.ZodObject<S>>> & z.output<z.ZodObject<S>> : z.output<z.ZodObject<S>>;
 type AllLinks<P, E extends EndsInput> = P extends Model<string, unknown, infer PL> ? Omit<PL, keyof E> & LinksOf<E> : LinksOf<E>;
-export interface Model<N extends string = string, D = unknown, L = unknown, A extends string = string> {
+/**
+ * Концы класса для строгих типов цепочек (план 2.0, этап 4, п. 1): роль → классы целей, множественный ли, обязательный
+ * ли; с концами предков (потомок заменяет конец целиком). Тот же вид выдаёт `letopis types` (generateTypes, sync.ts).
+ */
+type EndSpecOf<V> = V extends End<infer Mn, infer R, infer T> ? {
+    targets: T;
+    many: Mn;
+    required: R;
+} : V extends {
+    readonly name: infer N extends string;
+} ? {
+    targets: N;
+    many: false;
+    required: true;
+} : never;
+type EndsSpecOf<E> = {
+    [K in keyof E]: EndSpecOf<E[K]>;
+};
+type AllEnds<P, E extends EndsInput> = P extends Model<string, unknown, unknown, string, infer PE, string> ? Omit<PE, keyof E> & EndsSpecOf<E> : EndsSpecOf<E>;
+/** Имя класса и его предков — как `ancestors` реестра (семейства и переходы строгих типов). */
+type Lineage<N extends string, P> = N | (P extends Model<infer PN, unknown, unknown, string, unknown, infer PP> ? PN | PP : never);
+/** Концы описания класса: `ends` или пусто. */
+type EndsIn<D> = D extends {
+    ends?: infer E extends EndsInput;
+} ? E : Record<never, never>;
+/**
+ * Модель класса. `N` — имя, `D` — данные строки, `L` — концы строки, `A` — алиас, `E` — концы класса (роль → классы
+ * целей, множественный ли, обязательный ли), `P` — имя класса и его предков: всё это — для строгих типов цепочек.
+ */
+export interface Model<N extends string = string, D = unknown, L = unknown, A extends string = string, E = unknown, P extends string = N> {
     readonly name: N;
     readonly kind: 'hub' | 'link';
     readonly alias?: A;
@@ -180,9 +183,11 @@ export interface Model<N extends string = string, D = unknown, L = unknown, A ex
     readonly __types?: {
         data: D;
         links: L;
+        ends: E;
+        ancestors: P;
     };
 }
-export type AnyModel = Model<string, any, any, any>;
+export type AnyModel = Model<string, any, any, any, any, any>;
 /** Тип данных строки класса: `Infer<typeof Master>`. */
 export type Infer<M> = M extends Model<string, infer D, unknown> ? D : never;
 /** Тип концов строки класса. */
@@ -191,13 +196,25 @@ type ShapeOf<F> = F extends z.ZodObject<infer S> ? S : F extends z.ZodRawShape ?
 type AliasOf<D> = D extends {
     alias: infer A extends string;
 } ? A : string;
+/** Предок из описания класса (`extends`); нет — unknown. */
+type ExtendsOf<D> = D extends {
+    extends?: infer P;
+} ? P : unknown;
+/** Описание класса без полей — третьим аргументом короткой формы. */
+type ClassOpts = Omit<ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>, 'fields'>;
+/** Тип модели по имени, описанию и собственным полям: данные и концы — с предками. */
+type ModelOf<N extends string, D, S extends z.ZodRawShape> = Model<N, DataOf<ExtendsOf<D>, S>, AllLinks<ExtendsOf<D>, EndsIn<D>>, AliasOf<D>, AllEnds<ExtendsOf<D>, EndsIn<D>>, Lineage<N, ExtendsOf<D>>>;
 /**
  * Описывает класс объектов (хаб): поля, ключ, концы и свойства класса. Класс-связь объектов со своими данными
  * описывает `link()`.
  */
-export declare function hub<N extends string, S extends z.ZodRawShape>(name: N, shape: S, opts: Omit<ClassDef, 'fields'>): Model<N, z.output<z.ZodObject<S>>, Record<never, never>>;
-export declare function hub<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): Model<N, DataOf<D['extends'], ShapeOf<D['fields']>>, AllLinks<D['extends'], D['ends'] extends EndsInput ? D['ends'] : Record<never, never>>, AliasOf<D>>;
+export declare function hub<N extends string, S extends z.ZodRawShape, const O extends ClassOpts>(name: N, shape: S, opts: O): ModelOf<N, O, S>;
+export declare function hub<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): ModelOf<N, D, ShapeOf<D['fields']>>;
+/** Короткая форма без опций: hub('Имя', { поле: z… }) — поля класса (полная форма { fields: z.object(…) } — выше). */
+export declare function hub<N extends string, S extends z.ZodRawShape>(name: N, shape: S): ModelOf<N, {}, S>;
 /** Связь — отношение между объектами со своими данными (бронь, навык). */
-export declare function link<N extends string, S extends z.ZodRawShape>(name: N, shape: S, opts: Omit<ClassDef, 'fields'>): Model<N, z.output<z.ZodObject<S>>, Record<never, never>>;
-export declare function link<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): Model<N, DataOf<D['extends'], ShapeOf<D['fields']>>, AllLinks<D['extends'], D['ends'] extends EndsInput ? D['ends'] : Record<never, never>>, AliasOf<D>>;
+export declare function link<N extends string, S extends z.ZodRawShape, const O extends ClassOpts>(name: N, shape: S, opts: O): ModelOf<N, O, S>;
+export declare function link<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): ModelOf<N, D, ShapeOf<D['fields']>>;
+/** Короткая форма без опций: link('Имя', { поле: z… }) — поля класса (полная форма { fields: z.object(…) } — выше). */
+export declare function link<N extends string, S extends z.ZodRawShape>(name: N, shape: S): ModelOf<N, {}, S>;
 export { normalizeSchema, translatePattern, type JsonSchema } from './jsonschema.js';

package/dist/model.js

@@ -11,9 +11,10 @@
  * Поля, концы и ключ наследуются по правилу 0.21 «потомок заменяет поле целиком» (`extends`).
  */
 import { z } from 'zod';
-import { LetopisError } from './errors.js';
+import { lerr } from './errors.js';
 import { normalizeSchema } from './jsonschema.js';
-/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. */
+import { RESERVED_CLASS_NAMES } from './types.js';
+/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. `T` — имена классов целей (только для типов). */
 export class End {
     targets;
     many;
@@ -24,7 +25,7 @@ export class End {
     metaData;
     constructor(targets, opts) {
         if (!targets.length)
-            throw new LetopisError('invalid_class', 'у конца должен быть хотя бы один класс цели');
+            throw lerr('model.end_no_targets');
         this.targets = targets;
         this.many = opts.many;
         this.required = opts.required;
@@ -58,25 +59,31 @@ export class End {
 export function one(...targets) {
     return new End(targets, { many: false, required: true });
 }
-/** Множественный конец: список целей в одном конце (§4 предложения). */
+/**
+ * Множественный конец: список целей в одном конце (§4 предложения). Обязателен при `min` больше нуля — `unset()` у него
+ * в цепочке типизированного подключения нет.
+ */
 export function many(target, opts = {}) {
     const targets = Array.isArray(target) ? target : [target];
     return new End(targets, { many: true, required: (opts.min ?? 0) > 0, min: opts.min, max: opts.max, onDelete: opts.onDelete });
 }
 const NAME = /^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$/;
 /** Ключи полной формы описания класса (ClassDef). */
-const DEF_KEYS = new Set(['alias', 'extends', 'abstract', 'ends', 'fields', 'key', 'onDelete', 'history', 'ownerDefault', 'cache', 'meta', 'derivedBy', 'aggregate']);
+const DEF_KEYS = new Set(['alias', 'extends', 'abstract', 'ends', 'fields', 'key', 'onDelete', 'history', 'ownerDefault', 'cache', 'meta']);
 function isZod(v) {
     return typeof v === 'object' && v !== null && '_zod' in v;
 }
-/** Пути правил refine/superRefine в схеме Zod — их нет в JSON Schema. */
+/**
+ * Пути правил Zod, которых нет в JSON Schema: refine/superRefine (`refine`) и преобразования — `overwrite` (`.trim()`,
+ * `.toLowerCase()`, `.toUpperCase()`, `.normalize()` …) и `transform` (`.transform()`, `z.preprocess()`, `.pipe()`).
+ * Преобразования база и валидатор letopis не исполняют: их syncModels отклоняет (план 2.1, A11).
+ */
 function collectLost(schema, path, out) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const def = schema._zod.def;
-    for (const c of def.checks ?? []) {
-        if (c?._zod?.def?.check === 'custom')
-            out.push({ path, kind: 'refine' });
-    }
+    collectChecks(schema, path, out);
+    if (def.type === 'transform')
+        out.push({ path, kind: 'transform' });
     if (def.type === 'object')
         for (const [k, v] of Object.entries(def.shape))
             collectLost(v, `${path}.${k}`, out);
@@ -91,9 +98,24 @@ function collectLost(schema, path, out) {
     if (def.innerType)
         collectLost(def.innerType, path, out);
 }
+/** Проверки самой схемы (без вложенных): refine/superRefine/check — `refine`, `overwrite` — преобразование. */
+function collectChecks(schema, path, out) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    for (const c of schema._zod.def.checks ?? []) {
+        const check = c?._zod?.def?.check;
+        if (check === 'custom')
+            out.push({ path, kind: 'refine' });
+        else if (check === 'overwrite')
+            out.push({ path, kind: 'overwrite' });
+    }
+}
 function makeModel(kind, name, defArg, optsArg) {
     if (!NAME.test(name))
-        throw new LetopisError('invalid_class', `имя класса ${name} недопустимо`);
+        throw lerr('model.class_name_invalid', { name });
+    // имя метода цепочки или корня db: шаг с таким именем до хаба не дойдёт (план 2.0, этап 4, п. 2; 7.10 №3); связь с
+    // таким именем отклоняет база
+    if (kind === 'hub' && RESERVED_CLASS_NAMES.includes(name))
+        throw lerr('model.hub_name_reserved', { name });
     // короткая форма: hub(name, { поле: z…, … }, { key, meta, … })
     let def;
     // { fields: z.object(…) } без других ключей описания — полная форма, а не класс с единственным полем fields (план 2.0,
@@ -111,12 +133,12 @@ function makeModel(kind, name, defArg, optsArg) {
     const ownShape = !fields ? {} : fields instanceof z.ZodObject ? fields.shape : fields;
     for (const k of Object.keys(ownShape)) {
         if (k.startsWith('$'))
-            throw new LetopisError('invalid_class', `${name}: имя поля ${k} начинается с $ — так загрузчик помечает служебные ключи`);
+            throw lerr('model.field_name_dollar', { cls: name, field: k });
     }
     const ownEnds = {};
     for (const [role, v] of Object.entries(def.ends ?? {})) {
         if (!NAME.test(role))
-            throw new LetopisError('invalid_class', `${name}: имя конца ${role} недопустимо`);
+            throw lerr('model.end_name_invalid', { cls: name, role });
         let end = v instanceof End ? v : one(v);
         const rule = def.onDelete?.[role];
         if (rule)
@@ -136,28 +158,21 @@ function makeModel(kind, name, defArg, optsArg) {
             if (zd.type === 'default')
                 zd = zd.innerType._zod.def;
             if (zd.type !== 'string')
-                throw new LetopisError('invalid_class', `${name}: поле ключа ${k} должно быть обязательной строкой`);
+                throw lerr('model.key_field_type', { cls: name, field: k });
         }
         else if (ends[k]) {
             if (ends[k].many || !ends[k].required)
-                throw new LetopisError('invalid_class', `${name}: конец ключа ${k} должен быть обязательным и одиночным`);
+                throw lerr('model.key_end_type', { cls: name, end: k });
         }
         else {
-            throw new LetopisError('invalid_class', `${name}: ключ ссылается на неизвестное поле или конец ${k}`);
+            throw lerr('model.key_unknown_name', { cls: name, name: k });
         }
     }
     for (const [role, e] of Object.entries(ends)) {
         if (e.onDeleteRule === 'unset' && (e.required || (e.min ?? 0) > 0)) {
-            throw new LetopisError('invalid_class', `${name}: onDelete unset недопустим для обязательного конца ${role}`);
+            throw lerr('model.unset_required_end', { cls: name, end: role });
         }
     }
-    // агрегаты (план 1.1, §2.4): остальное — роль, поле суммы, цикл — сверяет база по описаниям источников
-    for (const [field, a] of Object.entries(def.aggregate ?? {})) {
-        if (!(field in shape))
-            throw new LetopisError('invalid_class', `${name}: агрегатного поля ${field} нет среди полей класса`);
-        if ((a.sum === undefined) === (a.count === undefined))
-            throw new LetopisError('invalid_class', `${name}: агрегат ${field} — ровно одно из sum и count: true`);
-    }
     // строгий верхний уровень — как в базе (resolved.schema: additionalProperties false)
     const schema = z.strictObject(shape);
     const model = {
@@ -217,20 +232,14 @@ function makeModel(kind, name, defArg, optsArg) {
                 desc.cache = def.cache;
             if (def.meta)
                 desc.meta = def.meta;
-            if (def.derivedBy)
-                desc.derivedBy = def.derivedBy;
-            if (def.aggregate) {
-                desc.aggregate = Object.fromEntries(Object.entries(def.aggregate).map(([field, a]) => [field, {
-                        ...(a.sum !== undefined ? { sum: a.sum } : { count: true }),
-                        of: typeof a.of === 'string' ? a.of : a.of.name,
-                        via: a.via,
-                        ...(a.where ? { where: a.where } : {}),
-                    }]));
-            }
             return desc;
         },
         lostRules() {
             const out = [];
+            // проверки z.object(…).refine/superRefine/check — на уровне объекта (между полями): в описание класса идёт
+            // только shape, поэтому они тоже потеряны — путь — имя класса
+            if (fields instanceof z.ZodObject)
+                collectChecks(fields, name, out);
             for (const [k, v] of Object.entries(ownShape))
                 collectLost(v, `${name}.${k}`, out);
             return out;

package/dist/ops.d.ts

@@ -81,3 +81,38 @@ export declare const not: (v: Scalar | Op) => Op;
  * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и».
  */
 export declare const or: (...filters: Record<string, unknown>[]) => Op;
+/**
+ * Значение ключа в JSON-фильтре MCP: `value` — скаляр, `list` — массив скаляров, `range` — массив из двух скаляров,
+ * `text` — строка, `flag` — true или false, `true` — только true, `negation` — оператор или скаляр, `filters` — массив
+ * фильтров вместо всего фильтра шага (`$or`). По нему mcp.ts проверяет значение, а таблицы показывают форму.
+ */
+export type OpArg = 'value' | 'list' | 'range' | 'text' | 'flag' | 'true' | 'negation' | 'filters';
+/** Оператор фильтра в реестре. */
+export interface OperatorSpec {
+    /** Имя фабрики в TypeScript: `import { gt } from 'letopis'`. */
+    readonly ts: string;
+    /** Сама фабрика. */
+    readonly make: (...args: never[]) => Op;
+    /** Ключ в JSON-фильтре MCP (`letopis_query`): `{ "price": { "$gt": 1000 } }`. */
+    readonly mcp: string;
+    /** Значение ключа MCP. */
+    readonly arg: OpArg;
+    /** Смысл для таблиц: README, шпаргалка, глава «Чтение» и справочник сайта. */
+    readonly ru: string;
+}
+/** Все 18 операторов в порядке таблиц. */
+export declare const OPERATORS: readonly OperatorSpec[];
+/** Вызов фабрики в таблицах: `between(a, b)`. */
+export declare function opCall(o: OperatorSpec): string;
+/** Ключ MCP со значением в таблицах: `{ "$between": [a, b] }`. */
+export declare function opJson(o: OperatorSpec): string;
+/** Ключ MCP с формой значения для описания letopis_query: `$between [a, b]`; у value, text и negation — только ключ. */
+export declare function opHint(o: OperatorSpec): string;
+/**
+ * Таблица операторов в Markdown — README, шпаргалка и справочник сайта: TypeScript, MCP, смысл; `mcp: false` — без
+ * колонки MCP (глава «Чтение» сайта: там цепочки на TypeScript). Вертикальная черта в ячейке экранируется, иначе она
+ * разрезала бы строку таблицы.
+ */
+export declare function operatorTable({ mcp }?: {
+    mcp?: boolean;
+}): string;

package/dist/ops.js

@@ -82,3 +82,104 @@ export const not = (v) => op('not', v);
  * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и».
  */
 export const or = (...filters) => op('or', filters);
+/** Все 18 операторов в порядке таблиц. */
+export const OPERATORS = [
+    {
+        ts: 'ne', make: ne, mcp: '$ne', arg: 'value',
+        ru: 'Не равно. Подходят и строки без поля или с `null`; `ne(null)` — строки, где у поля есть значение',
+    },
+    {
+        ts: 'gt', make: gt, mcp: '$gt', arg: 'value',
+        ru: 'Больше. Сравнение — по типу поля из описания класса (числа — как числа, даты — как даты), поле без описания — как текст; строки без поля не подходят',
+    },
+    {
+        ts: 'gte', make: gte, mcp: '$gte', arg: 'value',
+        ru: 'Больше или равно; сравнение — как у `gt`',
+    },
+    {
+        ts: 'lt', make: lt, mcp: '$lt', arg: 'value',
+        ru: 'Меньше; сравнение — как у `gt`',
+    },
+    {
+        ts: 'lte', make: lte, mcp: '$lte', arg: 'value',
+        ru: 'Меньше или равно; сравнение — как у `gt`',
+    },
+    {
+        ts: 'between', make: between, mcp: '$between', arg: 'range',
+        ru: 'От `a` до `b` включительно; сравнение — как у `gt`. Если `a` больше `b`, не подходит ничего',
+    },
+    {
+        ts: 'inList', make: inList, mcp: '$in', arg: 'list',
+        ru: 'Одно из значений списка. Пустой список не находит ничего; `null` в списке не находит строк без значения — для них `isNull`',
+    },
+    {
+        ts: 'like', make: like, mcp: '$like', arg: 'text',
+        ru: 'Текст по шаблону с учётом регистра: `%` — любые символы, в том числе ни одного, `_` — ровно один; буквальные `%` и `_` — с обратной косой чертой',
+    },
+    {
+        ts: 'ilike', make: ilike, mcp: '$ilike', arg: 'text',
+        ru: 'Как `like`, но без учёта регистра',
+    },
+    {
+        ts: 'starts', make: starts, mcp: '$starts', arg: 'text',
+        ru: 'Текст начинается с `s`, с учётом регистра. Это `like(s + \'%\')`: `%` и `_` внутри `s` не экранируются и работают как в шаблоне',
+    },
+    {
+        ts: 'ends', make: ends, mcp: '$ends', arg: 'text',
+        ru: 'Текст заканчивается на `s`, с учётом регистра. Это `like(\'%\' + s)`: `%` и `_` внутри `s` не экранируются и работают как в шаблоне',
+    },
+    {
+        ts: 'has', make: has, mcp: '$has', arg: 'value',
+        ru: 'Поле-массив содержит элемент `v`. Тип важен: `has(5)` найдёт число 5, но не строку `\'5\'`',
+    },
+    {
+        ts: 'hasAny', make: hasAny, mcp: '$hasAny', arg: 'list',
+        ru: 'Поле-массив содержит хотя бы один элемент списка. Находит только строковые элементы; пустой список не находит ничего',
+    },
+    {
+        ts: 'hasAll', make: hasAll, mcp: '$hasAll', arg: 'list',
+        ru: 'Поле-массив содержит все элементы списка, в любом порядке. Тип важен, как у `has`; пустой список подходит любой строке, даже без поля',
+    },
+    {
+        ts: 'exists', make: exists, mcp: '$exists', arg: 'flag',
+        ru: 'Поле есть в данных (`true`, по умолчанию) или его нет (`false`); значение не важно — поле с `null` тоже есть',
+    },
+    {
+        ts: 'isNull', make: isNull, mcp: '$isNull', arg: 'true',
+        ru: 'В поле `null` или поля нет совсем; отличить одно от другого помогает `exists`',
+    },
+    {
+        ts: 'not', make: not, mcp: '$not', arg: 'negation',
+        ru: 'Отрицание: `x` — оператор (`not(gte(1000))` — меньше 1000 или поля нет) или простое значение — тогда это «не равно», как `ne`',
+    },
+    {
+        ts: 'or', make: or, mcp: '$or', arg: 'filters',
+        ru: 'Хотя бы один из фильтров. Ставится вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и»',
+    },
+];
+/** Вызов фабрики в таблицах: `between(a, b)`. */
+export function opCall(o) {
+    const args = { value: 'v', list: '[v, …]', range: 'a, b', text: 's', flag: 'b = true', true: '', negation: 'x', filters: 'f1, f2, …' };
+    return `${o.ts}(${args[o.arg]})`;
+}
+/** Ключ MCP со значением в таблицах: `{ "$between": [a, b] }`. */
+export function opJson(o) {
+    const vals = { value: 'v', list: '[v, …]', range: '[a, b]', text: '"s"', flag: 'b', true: 'true', negation: 'x', filters: '[f1, f2, …]' };
+    return `{ "${o.mcp}": ${vals[o.arg]} }`;
+}
+/** Ключ MCP с формой значения для описания letopis_query: `$between [a, b]`; у value, text и negation — только ключ. */
+export function opHint(o) {
+    const vals = { list: '[..]', range: '[a, b]', flag: 'true|false', true: 'true', filters: '[filter, …]' };
+    return vals[o.arg] ? `${o.mcp} ${vals[o.arg]}` : o.mcp;
+}
+/**
+ * Таблица операторов в Markdown — README, шпаргалка и справочник сайта: TypeScript, MCP, смысл; `mcp: false` — без
+ * колонки MCP (глава «Чтение» сайта: там цепочки на TypeScript). Вертикальная черта в ячейке экранируется, иначе она
+ * разрезала бы строку таблицы.
+ */
+export function operatorTable({ mcp = true } = {}) {
+    const cell = (s) => s.replaceAll('|', '\\|');
+    const head = mcp ? '| TypeScript | MCP | Смысл |' : '| TypeScript | Смысл |';
+    const rows = OPERATORS.map((o) => `| ${[`\`${opCall(o)}\``, ...(mcp ? [`\`${opJson(o)}\``] : []), o.ru].map(cell).join(' | ')} |`);
+    return [head, mcp ? '|---|---|---|' : '|---|---|', ...rows].join('\n');
+}

package/dist/pglite.d.ts

@@ -1,12 +1,3 @@
-/**
- * База для разработки без установленного PostgreSQL (решение 6 точки А): PGlite (PostgreSQL 18 в
- * WebAssembly) с pgcrypto, доступный postgres.js через pglite-socket. Одно соединение: годится для
- * разработки и быстрых тестов логики, но не для гонок и не вместо postgres:18 в CI; LISTEN из
- * второго соединения нет — connect({ listen: false, max: 1 }).
- *
- * Пакеты @electric-sql/pglite и @electric-sql/pglite-socket — необязательные peer-зависимости:
- * основная точка входа их не импортирует, up({ pglite }) загружает их по требованию.
- */
 export interface PgliteOptions {
     /** Каталог данных (по умолчанию — в памяти, данные теряются при остановке). */
     dataDir?: string;

package/dist/pglite.js

@@ -7,6 +7,7 @@
  * Пакеты @electric-sql/pglite и @electric-sql/pglite-socket — необязательные peer-зависимости:
  * основная точка входа их не импортирует, up({ pglite }) загружает их по требованию.
  */
+import { lmsg } from './errors.js';
 /** Запустить PGlite с pgcrypto и сокетом для postgres.js. */
 export async function startPglite(opts = {}) {
     const load = async (name) => {
@@ -14,7 +15,8 @@ export async function startPglite(opts = {}) {
             return await import(name);
         }
         catch {
-            throw new Error(`letopis.up: для pglite нужен пакет ${name} — npm i -D @electric-sql/pglite @electric-sql/pglite-socket`);
+            // обычный Error, как у up(): подходящего кода нет
+            throw new Error(`letopis.up: ${lmsg('boot.pglite_package', { name })}`);
         }
     };
     const { PGlite } = await load('@electric-sql/pglite');

package/dist/registry.d.ts

@@ -9,18 +9,7 @@ export interface EndInfo {
     onDelete?: 'restrict' | 'cascade' | 'unset';
     meta?: Record<string, unknown>;
 }
-/**
- * Агрегат в базе (план 1.1, §2.4): поле — сумма поля sum или число (count) живых строк класса of с потомками того же
- * арендатора, чей одиночный конец via ведёт на строку; where — JSON Schema над данными строки-источника.
- */
-export interface AggregateInfo {
-    sum?: string;
-    count?: true;
-    of: string;
-    via: string;
-    where?: JsonSchema;
-}
-/** Тип листа данных для фильтров, сортировки и агрегатов (замена fieldTypeOf 0.21). */
+/** Тип листа данных для фильтров, сортировки и агрегатов. */
 export type LeafType = 'text' | 'numeric' | 'boolean' | 'timestamptz' | 'date' | 'uuid' | 'jsonb';
 export interface ClassInfo {
     name: string;
@@ -34,16 +23,13 @@ export interface ClassInfo {
     schema: JsonSchema;
     ends: Record<string, EndInfo>;
     key: string[];
-    history: unknown;
+    /** Ведёт ли класс журнал версий (`history: false` — нет). */
+    history: boolean;
     ownerDefault: 'tenant' | 'actor';
     cache?: {
         ttl?: number;
     };
     meta: Record<string, unknown>;
-    /** Производный класс: строки пишет только проектор с этим именем (план 1.1, §2.4). */
-    derivedBy?: string;
-    /** Агрегатные поля: их считает база, приложение не пишет (план 1.1, §2.4). */
-    aggregate?: Record<string, AggregateInfo>;
     /** Валидатор на TypeScript (компилируется при первом обращении). */
     validator(): Validator;
 }
@@ -55,8 +41,6 @@ interface ClassRow {
         resolved: Record<string, unknown>;
     };
 }
-/** Агрегатные поля класса: их считает база (план 1.1, §2.4). */
-export declare const aggregateFields: (cls: Pick<ClassInfo, "aggregate">) => string[];
 export declare class Registry {
     private byName;
     private byAlias;