letopis 0.20.3 → 1.0.0

package/dist/model.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Подпуть `letopis/model` (план, §2.3, §2.10, §2.11, §2.12, §2.13, этап 2, п. 1–2): описание классов
+ * на Zod 4 и их JSON Schema для строки класса `Class`.
+ *
+ * ```ts
+ * const Org = hub('Org', { fields: z.object({ name: z.string() }), key: ['name'] })
+ * const Master = hub('Master', { ends: { Org }, fields: z.object({ name: z.string() }), key: ['Org', 'name'] })
+ * const booking = link('booking', { ends: { Staff: one(Master), Customer: one(Customer).optional() }, onDelete: { Customer: 'unset' } })
+ * ```
+ * Короткая форма `hub('Master', { name: z.string() }, { key: ['name'] })` — поля сразу вторым аргументом.
+ * Поля, концы и ключ наследуются по правилу 0.21 «потомок заменяет поле целиком» (`extends`).
+ */
+import { z } from 'zod';
+import { type JsonSchema } from './jsonschema.js';
+export type OnDelete = 'restrict' | 'cascade' | 'unset';
+/** Свободные метаданные класса (§2.13). Приложение типизирует их, расширяя интерфейс. */
+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> {
+    readonly targets: readonly Target[];
+    readonly many: Many;
+    readonly required: Required;
+    readonly min?: number;
+    readonly max?: number;
+    readonly onDeleteRule?: OnDelete;
+    readonly metaData?: Record<string, unknown>;
+    constructor(targets: readonly Target[], opts: {
+        many: Many;
+        required: Required;
+        min?: number;
+        max?: number;
+        onDelete?: OnDelete;
+        meta?: Record<string, unknown>;
+    });
+    private with;
+    /** Необязательный конец. */
+    optional(): End<Many, false>;
+    /** Правило при удалении цели: restrict (по умолчанию), cascade, unset. */
+    onDelete(rule: OnDelete): End<Many, Required>;
+    /** Метаданные конца (§2.13). */
+    meta(meta: Record<string, unknown>): End<Many, Required>;
+    /** Имена классов целей. */
+    classNames(): string[];
+}
+/** Одиночный конец; несколько классов — союз: `one(Service, Product)`. По умолчанию обязательный. */
+export declare function one(...targets: Target[]): End<false, true>;
+/** Множественный конец: список целей в одном конце (§4 предложения). */
+export declare function many(target: Target | readonly Target[], opts?: {
+    min?: number;
+    max?: number;
+    onDelete?: OnDelete;
+}): End<true, boolean>;
+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;
+type LinksOf<E extends EndsInput> = {
+    [K in keyof E as EndOf<E[K]> extends End<boolean, true> ? K : never]: LinkValue<E[K]>;
+} & {
+    [K in keyof E as EndOf<E[K]> extends End<boolean, true> ? never : K]?: LinkValue<E[K]>;
+};
+/** Описание класса — вторым аргументом hub()/link(). */
+export interface ClassDef<S extends z.ZodRawShape = z.ZodRawShape, E extends EndsInput = EndsInput, P extends AnyModel | undefined = undefined> {
+    alias?: string;
+    extends?: P;
+    abstract?: boolean;
+    ends?: E;
+    fields?: z.ZodObject<S> | S;
+    key?: readonly string[];
+    onDelete?: Partial<Record<keyof E & string, OnDelete>>;
+    history?: boolean | HistoryPolicy;
+    ownerDefault?: 'tenant' | 'actor';
+    cache?: {
+        ttl?: number;
+    };
+    meta?: ClassMeta;
+}
+/** Описание класса в строке `Class` (метасхема `class_metaschema()` в lib/sql/40-class.sql). */
+export interface ClassDescription {
+    name: string;
+    kind: 'hub' | 'link';
+    parent?: string;
+    abstract?: boolean;
+    alias?: string;
+    fields: {
+        properties: Record<string, JsonSchema>;
+        required?: string[];
+    };
+    ends?: Record<string, {
+        class: string | string[];
+        many?: boolean;
+        required?: boolean;
+        min?: number;
+        max?: number;
+        onDelete?: OnDelete;
+        meta?: Record<string, unknown>;
+    }>;
+    key?: string[];
+    history?: boolean | HistoryPolicy;
+    ownerDefault?: 'tenant' | 'actor';
+    cache?: {
+        ttl?: number;
+    };
+    meta?: ClassMeta;
+}
+/** Правило refine, которое не попадёт в базу: проверяется только в библиотеке. */
+export interface LostRule {
+    path: string;
+    kind: string;
+}
+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> {
+    readonly name: N;
+    readonly kind: 'hub' | 'link';
+    readonly alias?: A;
+    readonly parent?: AnyModel;
+    readonly abstract: boolean;
+    /** Собственные поля класса (без предков). */
+    readonly ownShape: z.ZodRawShape;
+    /** Собственные концы класса (без предков). */
+    readonly ownEnds: Readonly<Record<string, End>>;
+    readonly def: ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>;
+    /** Поля с учётом предков: Zod-схема данных строки (для ранних ошибок в библиотеке). */
+    readonly schema: z.ZodObject<z.ZodRawShape>;
+    /** Концы с учётом предков. */
+    readonly ends: Readonly<Record<string, End>>;
+    /** Ключ с учётом предков ([] — класс без ключа). */
+    readonly key: readonly string[];
+    /** Описание для строки Class: только собственное, предков база развернёт сама. */
+    describe(): ClassDescription;
+    /** Правила refine, которых нет в JSON Schema и в базе. */
+    lostRules(): LostRule[];
+    /** Только для вывода типов. */
+    readonly __types?: {
+        data: D;
+        links: L;
+    };
+}
+export type AnyModel = Model<string, any, any, any>;
+/** Тип данных строки класса: `Infer<typeof Master>`. */
+export type Infer<M> = M extends Model<string, infer D, unknown> ? D : never;
+/** Тип концов строки класса. */
+export type InferLinks<M> = M extends Model<string, unknown, infer L> ? L : never;
+type ShapeOf<F> = F extends z.ZodObject<infer S> ? S : F extends z.ZodRawShape ? F : Record<never, never>;
+type AliasOf<D> = D extends {
+    alias: infer A extends string;
+} ? A : string;
+/** Хаб — объект (мастер, услуга). */
+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 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 { normalizeSchema, translatePattern, type JsonSchema } from './jsonschema.js';

package/dist/model.js

@@ -0,0 +1,224 @@
+/**
+ * Подпуть `letopis/model` (план, §2.3, §2.10, §2.11, §2.12, §2.13, этап 2, п. 1–2): описание классов
+ * на Zod 4 и их JSON Schema для строки класса `Class`.
+ *
+ * ```ts
+ * const Org = hub('Org', { fields: z.object({ name: z.string() }), key: ['name'] })
+ * const Master = hub('Master', { ends: { Org }, fields: z.object({ name: z.string() }), key: ['Org', 'name'] })
+ * const booking = link('booking', { ends: { Staff: one(Master), Customer: one(Customer).optional() }, onDelete: { Customer: 'unset' } })
+ * ```
+ * Короткая форма `hub('Master', { name: z.string() }, { key: ['name'] })` — поля сразу вторым аргументом.
+ * Поля, концы и ключ наследуются по правилу 0.21 «потомок заменяет поле целиком» (`extends`).
+ */
+import { z } from 'zod';
+import { LetopisError } from './errors.js';
+import { normalizeSchema } from './jsonschema.js';
+/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. */
+export class End {
+    targets;
+    many;
+    required;
+    min;
+    max;
+    onDeleteRule;
+    metaData;
+    constructor(targets, opts) {
+        if (!targets.length)
+            throw new LetopisError('invalid_class', 'у конца должен быть хотя бы один класс цели');
+        this.targets = targets;
+        this.many = opts.many;
+        this.required = opts.required;
+        this.min = opts.min;
+        this.max = opts.max;
+        this.onDeleteRule = opts.onDelete;
+        this.metaData = opts.meta;
+    }
+    with(patch) {
+        return new End(this.targets, {
+            many: (patch.many ?? this.many),
+            required: (patch.required ?? this.required),
+            min: this.min,
+            max: this.max,
+            onDelete: patch.onDelete ?? this.onDeleteRule,
+            meta: patch.meta ?? this.metaData,
+        });
+    }
+    /** Необязательный конец. */
+    optional() { return this.with({ required: false }); }
+    /** Правило при удалении цели: restrict (по умолчанию), cascade, unset. */
+    onDelete(rule) { return this.with({ onDelete: rule }); }
+    /** Метаданные конца (§2.13). */
+    meta(meta) { return this.with({ meta }); }
+    /** Имена классов целей. */
+    classNames() {
+        return this.targets.map((t) => (typeof t === 'string' ? t : t.name));
+    }
+}
+/** Одиночный конец; несколько классов — союз: `one(Service, Product)`. По умолчанию обязательный. */
+export function one(...targets) {
+    return new End(targets, { many: false, required: true });
+}
+/** Множественный конец: список целей в одном конце (§4 предложения). */
+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}$/;
+function isZod(v) {
+    return typeof v === 'object' && v !== null && '_zod' in v;
+}
+/** Пути правил refine/superRefine в схеме Zod — их нет в JSON Schema. */
+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' });
+    }
+    if (def.type === 'object')
+        for (const [k, v] of Object.entries(def.shape))
+            collectLost(v, `${path}.${k}`, out);
+    else if (def.type === 'array')
+        collectLost(def.element, `${path}[]`, out);
+    else if (def.type === 'record')
+        collectLost(def.valueType, `${path}.*`, out);
+    else if (def.type === 'union')
+        def.options.forEach((o, i) => collectLost(o, `${path}|${i}`, out));
+    else if (def.type === 'pipe')
+        out.push({ path, kind: 'transform' });
+    if (def.innerType)
+        collectLost(def.innerType, path, out);
+}
+function makeModel(kind, name, defArg, optsArg) {
+    if (!NAME.test(name))
+        throw new LetopisError('invalid_class', `имя класса ${name} недопустимо`);
+    // короткая форма: hub(name, { поле: z…, … }, { key, meta, … })
+    let def;
+    const isShape = defArg && typeof defArg === 'object' && Object.values(defArg).length > 0 && Object.values(defArg).every(isZod);
+    if (optsArg !== undefined || isShape) {
+        def = { ...optsArg, fields: (defArg ?? {}) };
+    }
+    else {
+        def = (defArg ?? {});
+    }
+    const fields = def.fields;
+    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} начинается с $ — так загрузчик помечает служебные ключи`);
+    }
+    const ownEnds = {};
+    for (const [role, v] of Object.entries(def.ends ?? {})) {
+        if (!NAME.test(role))
+            throw new LetopisError('invalid_class', `${name}: имя конца ${role} недопустимо`);
+        let end = v instanceof End ? v : one(v);
+        const rule = def.onDelete?.[role];
+        if (rule)
+            end = end.onDelete(rule);
+        ownEnds[role] = end;
+    }
+    const parent = def.extends;
+    const shape = { ...(parent?.schema.shape ?? {}), ...ownShape };
+    const ends = { ...(parent?.ends ?? {}), ...ownEnds };
+    const key = def.key ?? parent?.key ?? [];
+    for (const k of key) {
+        const f = shape[k];
+        if (f) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let zd = f._zod.def;
+            // умолчание допустимо (база подставит его до проверки), необязательность — нет
+            if (zd.type === 'default')
+                zd = zd.innerType._zod.def;
+            if (zd.type !== 'string')
+                throw new LetopisError('invalid_class', `${name}: поле ключа ${k} должно быть обязательной строкой`);
+        }
+        else if (ends[k]) {
+            if (ends[k].many || !ends[k].required)
+                throw new LetopisError('invalid_class', `${name}: конец ключа ${k} должен быть обязательным и одиночным`);
+        }
+        else {
+            throw new LetopisError('invalid_class', `${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}`);
+        }
+    }
+    // строгий верхний уровень — как в базе (resolved.schema: additionalProperties false)
+    const schema = z.strictObject(shape);
+    const model = {
+        name,
+        kind,
+        alias: def.alias,
+        parent,
+        abstract: def.abstract ?? false,
+        ownShape,
+        ownEnds,
+        def,
+        schema,
+        ends,
+        key,
+        describe() {
+            const js = normalizeSchema(z.toJSONSchema(z.object(ownShape), { io: 'input' }), { where: name, topLevel: true });
+            // поля ключа обязательны и с умолчанием: база подставляет умолчания до проверки (§2.3)
+            const required = new Set(Array.isArray(js.required) ? js.required : []);
+            for (const k of key)
+                if (k in ownShape)
+                    required.add(k);
+            const desc = {
+                name,
+                kind,
+                fields: {
+                    properties: (js.properties ?? {}),
+                    ...(required.size ? { required: [...required] } : {}),
+                },
+            };
+            if (parent)
+                desc.parent = parent.name;
+            if (def.abstract)
+                desc.abstract = true;
+            if (def.alias)
+                desc.alias = def.alias;
+            if (Object.keys(ownEnds).length) {
+                desc.ends = Object.fromEntries(Object.entries(ownEnds).map(([role, e]) => {
+                    const cls = e.classNames();
+                    return [role, {
+                            class: cls.length === 1 ? cls[0] : cls,
+                            ...(e.many ? { many: true } : {}),
+                            ...(e.required ? { required: true } : {}),
+                            ...(e.min !== undefined ? { min: e.min } : {}),
+                            ...(e.max !== undefined ? { max: e.max } : {}),
+                            ...(e.onDeleteRule ? { onDelete: e.onDeleteRule } : {}),
+                            ...(e.metaData ? { meta: e.metaData } : {}),
+                        }];
+                }));
+            }
+            if (def.key)
+                desc.key = [...def.key];
+            if (def.history !== undefined)
+                desc.history = def.history;
+            if (def.ownerDefault)
+                desc.ownerDefault = def.ownerDefault;
+            if (def.cache)
+                desc.cache = def.cache;
+            if (def.meta)
+                desc.meta = def.meta;
+            return desc;
+        },
+        lostRules() {
+            const out = [];
+            for (const [k, v] of Object.entries(ownShape))
+                collectLost(v, `${name}.${k}`, out);
+            return out;
+        },
+    };
+    return model;
+}
+export function hub(name, def, opts) {
+    return makeModel('hub', name, def, opts);
+}
+export function link(name, def, opts) {
+    return makeModel('link', name, def, opts);
+}
+export { normalizeSchema, translatePattern } from './jsonschema.js';

package/dist/ops.d.ts

@@ -1,6 +1,7 @@
 /**
- * Операторы фильтров. Symbol-tagged объекты — не пересекаются с данными.
- * Касты по типам полей делает sql.ts на основе Schema.attributes.
+ * Операторы фильтров (план, этап 3, п. 5) — 18 фабрик 0.21 (`lib/src/ops.ts` тега v0.21.0) без
+ * изменений смысла. Узел помечен символом Symbol.for('letopis.op'): из JSON его не получить,
+ * а вторая копия пакета в том же процессе его узнаёт. Приведение по типу листа делает sql.ts.
  */
 import { type Op, type Scalar } from './types.js';
 export declare const isOp: (v: unknown) => v is Op;
@@ -32,11 +33,11 @@ export declare const has: (v: Scalar) => Op;
 export declare const hasAny: (vs: Scalar[]) => Op;
 /** массив-поле содержит все */
 export declare const hasAll: (vs: Scalar[]) => Op;
-/** поле присутствует (true) / отсутствует (false) в data */
+/** поле присутствует (true) или отсутствует (false) */
 export declare const exists: (yes?: boolean) => Op;
-/** поле NULL или отсутствует */
+/** поле null или отсутствует */
 export declare const isNull: () => Op;
-/** НЕ-условие по полю: not(ilike('%тест%')); скаляр → «не равно» */
+/** НЕ-условие по полю: not(ilike('%тест%')); скаляр — «не равно» */
 export declare const not: (v: Scalar | Op) => Op;
-/** ИЛИ на уровне фильтра шага: db.Запись(or({status:'created'}, {status:'confirmed'})) */
+/** ИЛИ на уровне фильтра шага: t.booking(or({ notes: 'a' }, { notes: 'b' })) */
 export declare const or: (...filters: Record<string, unknown>[]) => Op;

package/dist/ops.js

@@ -1,45 +1,8 @@
 /**
- * Операторы фильтров. Symbol-tagged объекты — не пересекаются с данными.
- * Касты по типам полей делает sql.ts на основе Schema.attributes.
+ * Операторы фильтров (план, этап 3, п. 5) — 18 фабрик 0.21 (`lib/src/ops.ts` тега v0.21.0) без
+ * изменений смысла. Узел помечен символом Symbol.for('letopis.op'): из JSON его не получить,
+ * а вторая копия пакета в том же процессе его узнаёт. Приведение по типу листа делает sql.ts.
  */
-//
-// FILE: lib/src/ops.ts
-// VERSION: 1.0.0
-// START_MODULE_CONTRACT
-//   PURPOSE: Билдеры операторов фильтра, создающие узлы Op для DSL фильтров.
-//   SCOPE: type guard isOp + конструкторы операторов сравнения / списков / строк / массивов / наличия / логики (ne…or) поверх локальной фабрики op().
-//   DEPENDS: M-TYPES
-//   LINKS: M-OPS, V-M-OPS
-//   ROLE: RUNTIME
-//   MAP_MODE: EXPORTS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   op - (локальный) фабрика узла Op: { [OP]: name, args }.
-//   isOp - type guard: значение является узлом Op (содержит символ OP).
-//   ne - ≠ (IS DISTINCT FROM).
-//   gt - >.
-//   gte - ≥.
-//   lt - <.
-//   lte - ≤.
-//   between - a ≤ x ≤ b.
-//   inList - значение из списка (IN).
-//   like - LIKE (шаблон с % и _).
-//   ilike - ILIKE (без регистра).
-//   starts - начинается с (LIKE s%).
-//   ends - заканчивается на (LIKE %s).
-//   has - массив-поле содержит значение.
-//   hasAny - массив-поле содержит хотя бы одно из.
-//   hasAll - массив-поле содержит все.
-//   exists - поле присутствует (true) / отсутствует (false) в data.
-//   isNull - поле NULL или отсутствует.
-//   not - НЕ-условие по полю (скаляр → «не равно»).
-//   or - ИЛИ на уровне фильтра шага.
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
-// END_CHANGE_SUMMARY
 import { OP } from './types.js';
 const op = (name, ...args) => ({ [OP]: name, args });
 export const isOp = (v) => typeof v === 'object' && v !== null && OP in v;
@@ -71,18 +34,11 @@ export const has = (v) => op('has', v);
 export const hasAny = (vs) => op('hasAny', vs);
 /** массив-поле содержит все */
 export const hasAll = (vs) => op('hasAll', vs);
-/** поле присутствует (true) / отсутствует (false) в data */
+/** поле присутствует (true) или отсутствует (false) */
 export const exists = (yes = true) => op('exists', yes);
-/** поле NULL или отсутствует */
+/** поле null или отсутствует */
 export const isNull = () => op('isNull');
-/** НЕ-условие по полю: not(ilike('%тест%')); скаляр → «не равно» */
+/** НЕ-условие по полю: not(ilike('%тест%')); скаляр — «не равно» */
 export const not = (v) => op('not', v);
-// START_CONTRACT: or
-//   PURPOSE: Логическое ИЛИ на уровне фильтра шага — объединяет несколько фильтров-объектов в один узел Op.
-//   INPUTS: { filters: Record<string, unknown>[] - варьируемое число фильтров-объектов (каждый — свой набор условий) }
-//   OUTPUTS: { Op - узел { [OP]: 'or', args: [filters] } }
-//   SIDE_EFFECTS: none (чистая фабрика через op())
-//   LINKS: M-OPS, V-M-OPS
-// END_CONTRACT: or
-/** ИЛИ на уровне фильтра шага: db.Запись(or({status:'created'}, {status:'confirmed'})) */
+/** ИЛИ на уровне фильтра шага: t.booking(or({ notes: 'a' }, { notes: 'b' })) */
 export const or = (...filters) => op('or', filters);

package/dist/pglite.d.ts

@@ -0,0 +1,22 @@
+/**
+ * База для разработки без установленного 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;
+    /** Порт сокета (по умолчанию — свободный). */
+    port?: number;
+}
+export interface PgliteServer {
+    /** Строка подключения postgres.js к сокету PGlite (пользователь и база postgres). */
+    dsn: string;
+    close(): Promise<void>;
+}
+/** Запустить PGlite с pgcrypto и сокетом для postgres.js. */
+export declare function startPglite(opts?: PgliteOptions): Promise<PgliteServer>;

package/dist/pglite.js

@@ -0,0 +1,45 @@
+/**
+ * База для разработки без установленного 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 }) загружает их по требованию.
+ */
+/** Запустить PGlite с pgcrypto и сокетом для postgres.js. */
+export async function startPglite(opts = {}) {
+    const load = async (name) => {
+        try {
+            return await import(name);
+        }
+        catch {
+            throw new Error(`letopis.up: для pglite нужен пакет ${name} — npm i -D @electric-sql/pglite @electric-sql/pglite-socket`);
+        }
+    };
+    const { PGlite } = await load('@electric-sql/pglite');
+    const { pgcrypto } = await load('@electric-sql/pglite/contrib/pgcrypto');
+    const { PGLiteSocketServer } = await load('@electric-sql/pglite-socket');
+    const db = await PGlite.create(opts.dataDir, { extensions: { pgcrypto } });
+    const port = opts.port ?? (await freePort());
+    const server = new PGLiteSocketServer({ db, port, host: '127.0.0.1' });
+    await server.start();
+    return {
+        dsn: `postgres://postgres:postgres@127.0.0.1:${port}/postgres`,
+        async close() {
+            await server.stop();
+            await db.close();
+        },
+    };
+}
+async function freePort() {
+    const net = await import('node:net');
+    return new Promise((resolve, reject) => {
+        const s = net.createServer();
+        s.once('error', reject);
+        s.listen(0, '127.0.0.1', () => {
+            const p = s.address().port;
+            s.close(() => resolve(p));
+        });
+    });
+}

package/dist/registry.d.ts

@@ -0,0 +1,57 @@
+import type { JsonSchema } from './jsonschema.js';
+import { type Validator } from './validate.js';
+export interface EndInfo {
+    class: string | string[];
+    many?: boolean;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    onDelete?: 'restrict' | 'cascade' | 'unset';
+    meta?: Record<string, unknown>;
+}
+/** Тип листа данных для фильтров, сортировки и агрегатов (замена fieldTypeOf 0.21). */
+export type LeafType = 'text' | 'numeric' | 'boolean' | 'timestamptz' | 'date' | 'uuid' | 'jsonb';
+export interface ClassInfo {
+    name: string;
+    tenant: string;
+    rev: number;
+    kind: 'hub' | 'link';
+    alias?: string;
+    abstract: boolean;
+    /** Сам класс, затем предки до корня. */
+    ancestors: string[];
+    schema: JsonSchema;
+    ends: Record<string, EndInfo>;
+    key: string[];
+    history: unknown;
+    ownerDefault: 'tenant' | 'actor';
+    cache?: {
+        ttl?: number;
+    };
+    meta: Record<string, unknown>;
+    /** Валидатор на TypeScript (компилируется при первом обращении). */
+    validator(): Validator;
+}
+interface ClassRow {
+    tenant: string;
+    rev: number;
+    data: {
+        alias?: string;
+        resolved: Record<string, unknown>;
+    };
+}
+export declare class Registry {
+    private byName;
+    private byAlias;
+    /** Заменить содержимое строками Class (собственные классы арендатора и системные). */
+    load(rows: readonly ClassRow[]): void;
+    has(name: string): boolean;
+    find(name: string): ClassInfo | undefined;
+    resolve(name: string): ClassInfo;
+    all(): ClassInfo[];
+    /** Класс и все его потомки (семейство). */
+    family(name: string): ClassInfo[];
+    /** Тип листа по пути полей класса: по JSON Schema (type и format). */
+    leafType(cls: string, path: readonly string[]): LeafType;
+}
+export {};