letopis 0.13.0 → 0.16.0

package/dist/chain.d.ts

@@ -4,8 +4,9 @@
  *
  * Выборка настраивается модификаторами: .limit(n) .offset(n) .sort(field, dir?)
  * Колонки — модификаторами: .tags(…) .account(…) .owner(…); ключ путей — .alias(…).
- * Запись: .set(data) / .delete({confirm}) / .anonymize(fields) — ЗВЕНЬЯ (возвращают
- * цепочку, продолжение — от результата); исполняет ТЕРМИНАЛ, весь план одной транзакцией.
+ * Запись: .create(data) / .update(data) / .delete({confirm}) / .anonymize(fields) — ЗВЕНЬЯ
+ * (возвращают цепочку, продолжение — от результата); исполняет ТЕРМИНАЛ, весь план
+ * одной транзакцией.
  */
 import type { Row, Path, Filter } from './types.js';
 import { type Ctx } from './sql.js';
@@ -49,31 +50,37 @@ export interface ChainCore {
     anonymize(fields: string[]): Chain;
     /** Переименовать ключ ТЕКУЩЕГО шага в выводе путей. */
     alias(name: string): Chain;
-    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В set() — значение тегов. */
+    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В записи — значение тегов. */
     tags(v: string | string[] | object): Chain;
-    /** Колонка account (uuid или Row/Account). В set()-insert — значение. */
+    /** Колонка account (uuid или Row/Account). В create() — значение. */
     account(v: string | {
         id: string;
     }): Chain;
-    /** Колонка owner (uuid или Row/Account). В set()-insert — значение. */
+    /** Колонка owner (uuid или Row/Account). В create() — значение. */
     owner(v: string | {
         id: string;
     }): Chain;
     /**
-     * Значение связи для записи БЕЗ участия в фильтре целей (в отличие от контекст-шага):
-     *   tr.Запись(b).позиция({}).link('Сотрудник', новый).set({}).rows()  // перевесить исполнителя
+     * Вставить узел в путь: x — ленивая цепочка-паттерн (стык проверяется правилами
+     * переходов) либо Row (шаг его класса по id). ТА ЖЕ переменная-цепочка повторно
+     * в одном пути — возврат к её узлу (ветвление); разные переменные — разные узлы.
      */
-    link(className: string, target: string | {
-        id: string;
-    }): Chain;
+    entity(x: Chain | Row): Chain;
     /**
-     * Записать в шаг, к которому приклеен точкой (ЗВЕНО — вернёт цепочку, исполняет терминал):
-     *   await db.Организация(org).Сотрудник().set({ name: 'Вася' }).rows()
-     * Связи — контекст-шагами до set(). Пустой фильтр без data.id → INSERT;
-     * id (фильтр или data.id) → UPSERT; фильтр-объект → версия каждого найденного.
+     * Создать сущность (ЗВЕНО — вернёт цепочку, исполняет терминал):
+     *   await db.Организация(org).Сотрудник().create({ name: 'Вася' }).rows()
+     * Связи — контекст-шагами до create() + слотами .Класс.set(…) после. id — по Schema
+     * (attributes.id: v4 | v7 | v5-вычисляемый); известный id (Класс(id) / data.id / v5)
+     * уже существует → новая версия (идемпотентно). Фильтр-объект — ошибка: это update().
+     */
+    create(data?: Record<string, unknown>): Chain;
+    /**
+     * Новая версия КАЖДОГО найденного путём (deep-merge листьев data):
+     *   await db.Запись(з).позиция({ qty: 1 }).update({ qty: 2 }).rows()
+     * Класс() ≡ Класс({}) — все в границах контекста. Не найдено → [] (НИКОГДА не создаёт).
      * Продолжение цепочки — от записанных строк (fan-out при множестве).
      */
-    set(data?: Record<string, unknown>): Chain;
+    update(data?: Record<string, unknown>): Chain;
     /**
      * Удаление-звено. { confirm: true } — серверный tombstone + каскад (продолжение — от
      * затомбстоуненных, $deleted: true); БЕЗ confirm — превью: терминал вернёт кандидатов
@@ -83,8 +90,25 @@ export interface ChainCore {
         confirm?: boolean;
     }): Chain;
 }
+/**
+ * Свойство-класс на цепочке:
+ *   ВЫЗОВ  `Класс(фильтр?)` — шаг-навигация; повтор LINK-класса в пути = возврат
+ *          к его узлу (pivot: ветвление к другому концу, дофильтровка AND);
+ *   СЛОТ   `Класс` без скобок — конец links записываемой версии:
+ *     .set(target) — установить конец (id | Row | вложенная цепочка: та же транзакция,
+ *                    ровно одна сущность класса конца); союз-конец замещается целиком;
+ *     .unset()     — снять optional-конец.
+ * Слот валиден только для конца из Schema.links владельца и ТОЛЬКО после операции
+ * записи: …create(…).Класс.set(x) / …update(…).Класс.unset() — та же версия строки.
+ */
+export type StepProp = ((filter?: Filter) => Chain) & {
+    set(target: string | {
+        id: string;
+    } | Chain): Chain;
+    unset(): Chain;
+};
 export type Chain = ChainCore & {
-    [className: string]: (filter?: Filter) => Chain;
+    [className: string]: StepProp;
 };
 export interface DbCore {
     /** Открыть транзакцию: tr — тот же API + commit/rollback/lock. */
@@ -114,6 +138,8 @@ export interface DbCore {
     auth: AuthApi;
     /** ACL по Resource/Rule: check(эндпоинт) / checkData(класс, READ|WRITE|DELETE) / reload. */
     acl: AclApi;
+    /** Начать путь с готового узла/паттерна: db.entity(pos).… (pos — ленивая цепочка или Row). */
+    entity(x: Chain | Row): Chain;
 }
 export type EntityDb = DbCore & {
     [className: string]: (filter?: Filter) => Chain;
@@ -147,5 +173,7 @@ export type Batch = {
 interface RootState {
     batches: Map<string, BatchPlan[]>;
 }
+/** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
+export declare const PLAN: unique symbol;
 export declare function makeDb(ctx: Ctx, root?: RootState): EntityDb;
 export {};

package/dist/chain.js

@@ -1,4 +1,4 @@
-import { buildRead, runQuery, leafType } from './sql.js';
+import { buildRead, runQuery, leafType, resolveHop, nextNodeKey, } from './sql.js';
 import { runPlan, executeBatch, toRow } from './write.js';
 import { beginTx, lock } from './tx.js';
 import { makeTables } from './tables.js';
@@ -16,6 +16,44 @@ function normalizeFilter(f) {
     return f;
 }
 const clsOf = (steps) => steps.map((s) => s.cls.id);
+/** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
+export const PLAN = Symbol('letopis.plan');
+const peekPlan = (x) => x !== null && typeof x === 'object' ? x[PLAN] : undefined;
+/** Конец схемы владельца, принимающий класс слота (legacy: 'Entity'-конец берёт любой HUB). */
+function findEnd(owner, slot) {
+    return owner.links.find((e) => e.classes.includes(slot.id) || (!owner.strictEnds && e.classes.includes('Entity') && slot.category === 'HUB'));
+}
+/** Значение слота: id-строка | Row | цепочка (одношаговый адрес сворачивается в id). */
+function slotValue(slotCls, v) {
+    if (typeof v === 'string')
+        return v;
+    const plan = peekPlan(v);
+    if (plan) {
+        const [head] = plan.steps;
+        if (plan.steps.length === 1 && !head.op && typeof head.filter === 'string') {
+            if (head.cls.id !== slotCls.id) {
+                throw new Error(`letopis: slot "${slotCls.id}" got a chain of class "${head.cls.id}"`);
+            }
+            return head.filter; // просто адрес db.Класс(id) — без вложенного исполнения
+        }
+        return { plan: plan.steps, mods: plan.mods };
+    }
+    if (v !== null && typeof v === 'object' && typeof v.id === 'string') {
+        return v.id; // Row / Account
+    }
+    throw new Error(`letopis: slot "${slotCls.id}" accepts an id, a Row or a chain`);
+}
+/** Узел для pivot: последний реальный шаг класса cls в ТЕКУЩЕМ читающем сегменте (до op). */
+function pivotNodeOf(steps, cls) {
+    for (let i = steps.length - 1; i >= 0; i--) {
+        const s = steps[i];
+        if (s.op)
+            return undefined; // операция закрывает паттерн — узлы до неё недоступны
+        if (s.pivotKey === undefined && s.cls.id === cls.id)
+            return s;
+    }
+    return undefined;
+}
 async function runPaths(ctx, steps, mods) {
     const q = buildRead(ctx, steps, mods, 'paths');
     const res = await runQuery(ctx, q.text, q.params, 'paths', clsOf(steps));
@@ -35,7 +73,67 @@ async function runRows(ctx, steps, mods) {
         return d != null ? { ...row, $depth: d } : row;
     });
 }
-function makeChain(ctx, steps, mods, batch) {
+const NO_NODES = new Map();
+/**
+ * Свойство-класс (вызов = шаг/pivot; без скобок = слот). ownerSteps undefined — корень
+ * (db/batch): слот без владельца — ошибка.
+ */
+function classProp(ctx, name, cls, ownerSteps, mods, batch, nodes, applySlot) {
+    const step = (filter) => {
+        const prev = ownerSteps?.[ownerSteps.length - 1];
+        // повтор LINK-класса в текущем паттерне — возврат к узлу (pivot)
+        const node = prev && cls.category === 'LINK' ? pivotNodeOf(ownerSteps, cls) : undefined;
+        if (node) {
+            const pivot = { name, cls, filter: normalizeFilter(filter), pivotKey: node.nodeKey };
+            return makeChain(ctx, [...ownerSteps, pivot], mods, batch, nodes);
+        }
+        if (prev && !prev.op)
+            resolveHop(prev.cls, cls); // ранняя проверка пути (после op — продолжение от результата)
+        const next = { name, cls, filter: normalizeFilter(filter), nodeKey: nextNodeKey() };
+        return makeChain(ctx, [...(ownerSteps ?? []), next], ownerSteps ? mods : {}, batch, nodes);
+    };
+    const slotGuard = () => {
+        if (!ownerSteps?.length || !applySlot) {
+            throw new Error(`letopis: slot "${name}" needs an owner step — start with a class call: db.Класс(…).${name}.set(…)`);
+        }
+        const owner = ownerSteps[ownerSteps.length - 1];
+        if (!findEnd(owner.cls, cls)) {
+            throw new Error(`letopis: "${cls.id}" is not a link end of "${owner.cls.id}" (Schema.links: ${owner.cls.links.map((e) => e.classes.join('|')).join(', ') || '—'})`);
+        }
+        return owner.cls;
+    };
+    return new Proxy(step, {
+        apply: (t, _self, args) => t(...args),
+        get(t, p, r) {
+            if (p === 'set') {
+                return (v) => {
+                    slotGuard();
+                    return applySlot(cls, slotValue(cls, v));
+                };
+            }
+            if (p === 'unset') {
+                return () => {
+                    const ownerCls = slotGuard();
+                    const end = findEnd(ownerCls, cls);
+                    if (ownerCls.strictEnds && !end.optional) {
+                        throw new Error(`letopis: link end "${cls.id}" of "${ownerCls.id}" is required — cannot unset`);
+                    }
+                    return applySlot(cls, null);
+                };
+            }
+            if (p === 'delete') {
+                return () => {
+                    throw new Error(`letopis: slot .delete() renamed to .unset() (0.16.0) — .${name}.unset() removes the link end`);
+                };
+            }
+            if (typeof p === 'symbol' || p === 'then' || p in Function.prototype || p === 'name' || p === 'length' || p === 'prototype') {
+                return Reflect.get(t, p, r);
+            }
+            throw new Error(`letopis: "${name}" without call is a link slot (set/unset); for navigation call ${name}(…)`);
+        },
+    });
+}
+function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
     const hasOps = steps.some((s) => s.op);
     const withLast = (patch) => {
         const last = steps[steps.length - 1];
@@ -44,24 +142,83 @@ function makeChain(ctx, steps, mods, batch) {
         }
         const next = steps.slice();
         next[next.length - 1] = { ...last, ...patch };
-        return makeChain(ctx, next, mods, batch);
+        return makeChain(ctx, next, mods, batch, nodes);
+    };
+    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batch, nodes);
+    /** Обновить план в батче (регистрируется на первой операции, дальше мутируется). */
+    const syncBatch = (next) => {
+        if (!batch)
+            return;
+        if (batch.entry)
+            batch.entry.steps = next;
+        else {
+            batch.entry = { steps: next };
+            batch.queue.push(batch.entry);
+        }
     };
-    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batch);
     /** Операция-звено: op на последний шаг (op уже есть → self-шаг «те же сущности»); mods сбрасываются. */
     const withOp = (op) => {
         const last = steps[steps.length - 1];
         const next = last.op
-            ? [...steps, { name: last.name, cls: last.cls, self: true, op }]
+            ? [...steps, { name: last.name, cls: last.cls, self: true, op, nodeKey: nextNodeKey() }]
             : [...steps.slice(0, -1), { ...last, op }];
-        if (batch) {
-            if (batch.entry)
-                batch.entry.steps = next;
-            else {
-                batch.entry = { steps: next };
-                batch.queue.push(batch.entry);
+        syncBatch(next);
+        return makeChain(ctx, next, {}, batch, nodes);
+    };
+    /**
+     * Слот связи: значение конца ЗАПИСЫВАЕМОЙ версии последнего шага — только после
+     * операции записи (…create(…).Класс.set(x) / …update(…).Класс.unset()): та же версия.
+     */
+    const applySlot = (slotCls, value) => {
+        const last = steps[steps.length - 1];
+        if (!last.op) {
+            throw new Error(`letopis: link slot "${slotCls.alias}" needs a write — add .create(…)/.update(…) before .${slotCls.alias}.${value === null ? 'unset()' : 'set(…)'}`);
+        }
+        if (last.op.kind !== 'create' && last.op.kind !== 'update') {
+            throw new Error(`letopis: link slot after ${last.op.kind}() — slots apply to create()/update()`);
+        }
+        if (last.extraLinks && slotCls.id in last.extraLinks) {
+            throw new Error(`letopis: duplicate link slot "${slotCls.id}" in one write`);
+        }
+        const patched = {
+            ...last,
+            extraLinks: { ...(last.extraLinks ?? {}), [slotCls.id]: value },
+        };
+        const next = [...steps.slice(0, -1), patched];
+        syncBatch(next);
+        return makeChain(ctx, next, mods, batch, nodes);
+    };
+    /** entity(x): вклейка узла/паттерна; та же переменная повторно — возврат к её узлу. */
+    const entityStep = (x) => {
+        const plan = peekPlan(x);
+        if (plan) {
+            const known = nodes.get(x);
+            if (known !== undefined) {
+                const lastX = plan.steps[plan.steps.length - 1];
+                const pivot = { name: lastX.name, cls: lastX.cls, pivotKey: known };
+                return makeChain(ctx, [...steps, pivot], mods, batch, nodes);
             }
+            if (plan.steps.some((s) => s.op)) {
+                throw new Error('letopis: entity() takes a read pattern — a chain with operations cannot be embedded');
+            }
+            const prev = steps[steps.length - 1];
+            if (prev && !prev.op)
+                resolveHop(prev.cls, plan.steps[0].cls); // стык по правилам пути
+            const nodeKey = plan.steps[plan.steps.length - 1].nodeKey;
+            const nextNodes = new Map(nodes);
+            nextNodes.set(x, nodeKey);
+            return makeChain(ctx, [...steps, ...plan.steps], mods, batch, nextNodes);
+        }
+        if (x !== null && typeof x === 'object' && typeof x.id === 'string' && typeof x.class === 'string') {
+            const row = x;
+            const cls = ctx.registry.resolve(row.class);
+            const prev = steps[steps.length - 1];
+            if (prev && !prev.op)
+                resolveHop(prev.cls, cls);
+            const next = { name: cls.alias, cls, filter: row.id, nodeKey: nextNodeKey() };
+            return makeChain(ctx, [...steps, next], mods, batch, nodes);
         }
-        return makeChain(ctx, next, {}, batch);
+        throw new Error('letopis: entity() accepts a lazy chain or a Row');
     };
     /** Терминал: план (есть операции) — runPlan одной транзакцией; иначе прямое чтение. */
     const guardBatch = () => {
@@ -71,9 +228,13 @@ function makeChain(ctx, steps, mods, batch) {
     };
     const handler = {
         get(_t, prop) {
+            if (prop === PLAN)
+                return { steps, mods };
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             switch (prop) {
+                case 'entity':
+                    return entityStep;
                 case 'run':
                     return () => {
                         guardBatch();
@@ -173,8 +334,23 @@ function makeChain(ctx, steps, mods, batch) {
                             return raw.deleted ? { ...row, $deleted: true } : row;
                         });
                     };
+                case 'create':
+                    return (data = {}) => {
+                        const last = steps[steps.length - 1];
+                        if (last && !last.op) { // после op create пишет результат — фильтр там подставит план
+                            if (last.pivotKey !== undefined) {
+                                throw new Error('letopis: create() on a pivot step — pivot returns to an existing node, use update()');
+                            }
+                            if (last.filter !== undefined && typeof last.filter !== 'string') {
+                                throw new Error(`letopis: create() takes no filter — ${last.name}(id).create(…) fixes the id, searching is update()`);
+                            }
+                        }
+                        return withOp({ kind: 'create', data, mods });
+                    };
+                case 'update':
+                    return (data = {}) => withOp({ kind: 'update', data, mods });
                 case 'set':
-                    return (data = {}) => withOp({ kind: 'set', data, mods });
+                    throw new Error('letopis: set() split into create()/update() (0.16.0) — create() inserts, update() versions what the path finds');
                 case 'delete':
                     return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, mods });
                 case 'anonymize':
@@ -188,17 +364,10 @@ function makeChain(ctx, steps, mods, batch) {
                 case 'owner':
                     return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
                 case 'link':
-                    return (clsName, target) => {
-                        const linkCls = ctx.registry.resolve(clsName);
-                        const last = steps[steps.length - 1];
-                        return withLast({
-                            extraLinks: { ...(last.extraLinks ?? {}), [linkCls.id]: typeof target === 'object' ? target.id : target },
-                        });
-                    };
+                    throw new Error('letopis: .link() removed (0.15.0) — use the link slot: .Класс.set(target)');
             }
             if (ctx.registry.has(prop)) {
-                const cls = ctx.registry.resolve(prop);
-                return (filter) => makeChain(ctx, [...steps, { name: prop, cls, filter: normalizeFilter(filter) }], mods, batch);
+                return classProp(ctx, prop, ctx.registry.resolve(prop), steps, mods, batch, nodes, applySlot);
             }
             ctx.registry.resolve(prop); // неизвестный класс — понятная ошибка со списком
             return undefined;
@@ -225,8 +394,7 @@ function makeBatch(ctx, queue) {
                     return () => queue.length;
             }
             if (ctx.registry.has(prop)) {
-                const cls = ctx.registry.resolve(prop);
-                return (filter) => makeChain(ctx, [{ name: String(prop), cls, filter: normalizeFilter(filter) }], {}, { queue });
+                return classProp(ctx, String(prop), ctx.registry.resolve(prop), undefined, {}, { queue }, NO_NODES);
             }
             ctx.registry.resolve(prop);
             return undefined;
@@ -335,9 +503,12 @@ export function makeDb(ctx, root) {
                 case 'sql':
                     return ctx.sql;
             }
+            if (prop === 'entity') {
+                // старт пути с готового паттерна/строки: db.entity(pos).…
+                return (x) => makeChain(ctx, [], {}, undefined, NO_NODES).entity(x);
+            }
             if (ctx.registry.has(prop)) {
-                const cls = ctx.registry.resolve(prop);
-                return (filter) => makeChain(ctx, [{ name: String(prop), cls, filter: normalizeFilter(filter) }], {});
+                return classProp(ctx, String(prop), ctx.registry.resolve(prop), undefined, {}, undefined, NO_NODES);
             }
             ctx.registry.resolve(prop);
             return undefined;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export declare function connect(opts: ConnectOpts): Promise<EntityDb>;
 export declare function cursorOf(row: import('./types.js').Row, field?: string): import('./types.js').Cursor;
 export { up } from './up.js';
 export type { UpOpts } from './up.js';
+export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
 export type { Row, Path, Filter, ChainMods, Cursor, ConnectOpts, QueryEvent, Account, Credential, Resource, Rule, AclOp, AclDecision, } from './types.js';
 export type { EntityDb, EntityTx, Chain, Batch, WatchEvent, WatchOpts } from './chain.js';

package/dist/index.js

@@ -57,6 +57,8 @@ export function cursorOf(row, field = 'updated') {
 }
 // одна точка входа: контейнер + готовность + схема + connect
 export { up } from './up.js';
+// генерация id (attributes.id): формула v5 открыта — id считается ДО создания
+export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
 // операторы фильтров
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
 export { totpCode } from './auth.js';

package/dist/schema.js

@@ -2,6 +2,8 @@
  * Загрузка таблицы Schema → реестр классов:
  *  - резолв имени по id и alias;
  *  - цепочка ancestors (walk по ancestor, если в БД не заполнена);
+ *  - attributes НАСЛЕДУЮТСЯ по цепочке (потомок поверх предка; поле = замена правила
+ *    целиком) — включая правило id (генерация v4/v5/v7); links НЕ наследуются;
  *  - скомпилированный fastest-validator per class;
  *  - карта типов полей (для SQL-кастов фильтров).
  */
@@ -88,6 +90,58 @@ export function fieldTypeOf(attr) {
     }
     return { kind: 'any' };
 }
+/**
+ * Элемент Schema.links: объект-конец v2 (jsonb) либо legacy-строка 'Org'
+ * (включая JSON-текст в text[] у старых схем). Возвращает [конец, isV2].
+ */
+function parseEnd(cls, raw) {
+    let o;
+    if (typeof raw === 'string') {
+        if (!raw.trimStart().startsWith('{'))
+            return [{ classes: [raw] }, false];
+        try {
+            o = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`letopis: class "${cls}" has malformed link end (bad JSON): ${raw}`);
+        }
+    }
+    else {
+        o = raw;
+    }
+    const classes = o.classes ?? (o.class ? [o.class] : []);
+    if (!classes.length || classes.some((c) => typeof c !== 'string' || !c)) {
+        throw new Error(`letopis: class "${cls}" has link end without classes: ${JSON.stringify(raw)}`);
+    }
+    return [{ classes, optional: o.optional === true, cardinality: o.cardinality }, true];
+}
+/**
+ * attributes.id: правило валидации + (объектом) спецификация генерации.
+ * generate/from — ключи letopis, вырезаются из правила перед компиляцией валидатора.
+ */
+function parseIdGen(cls, attributes) {
+    const raw = attributes.id;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { idGen: { version: 4 }, attrs: attributes };
+    }
+    const { generate, from, ...rule } = raw;
+    const attrs = { ...attributes, id: rule };
+    if (generate === undefined)
+        return { idGen: { version: 4 }, attrs };
+    if (generate !== 4 && generate !== 5 && generate !== 7) {
+        throw new Error(`letopis: class "${cls}" — attributes.id.generate must be 4 | 5 | 7, got ${JSON.stringify(generate)}`);
+    }
+    if (generate === 5) {
+        if (!Array.isArray(from) || !from.length || from.some((f) => typeof f !== 'string' || !f)) {
+            throw new Error(`letopis: class "${cls}" — id generate:5 needs "from": non-empty string[] (link ends / data fields)`);
+        }
+        return { idGen: { version: 5, from: from }, attrs };
+    }
+    if (from !== undefined) {
+        throw new Error(`letopis: class "${cls}" — attributes.id.from is for generate:5 only`);
+    }
+    return { idGen: { version: generate }, attrs };
+}
 function buildDef(row, byId) {
     // цепочка наследования: из БД или walk по ancestor
     let ancestors = row.ancestors ?? [];
@@ -101,18 +155,54 @@ function buildDef(row, byId) {
             cur = byId.get(cur)?.ancestor ?? null;
         }
     }
+    // attributes НАСЛЕДУЮТСЯ по цепочке ancestor: потомок ПОВЕРХ предка, переопределение
+    // поля — замена правила ЦЕЛИКОМ (не слияние объекта-правила). links не наследуются.
+    const merged = {};
+    for (let i = ancestors.length - 1; i >= 0; i--) {
+        Object.assign(merged, byId.get(ancestors[i])?.attributes ?? {});
+    }
+    // attributes.id: спецификация генерации (generate/from) отделяется от правила валидации
+    const { idGen, attrs } = parseIdGen(row.id, merged);
     // fastest-validator: валидируем {id, ...data}; СТРОГО — лишние поля запрещены
-    const compiled = v.compile({ ...row.attributes, $$strict: true });
+    const compiled = v.compile({ ...attrs, $$strict: true });
     const check = (data) => {
         const res = compiled(data);
         return res === true ? true : res;
     };
     const fieldTypes = new Map();
-    for (const [field, attr] of Object.entries(row.attributes)) {
+    for (const [field, attr] of Object.entries(attrs)) {
         if (field.startsWith('$$'))
             continue;
         fieldTypes.set(field, fieldTypeOf(attr));
     }
+    let strictEnds = false;
+    // jsonb-массив; text[] у legacy-схем даёт string[]; jsonb-строка "[…]" (двойная
+    // сериализация внешних писателей) — распарсить
+    let rawLinks = row.links ?? [];
+    if (typeof rawLinks === 'string')
+        rawLinks = JSON.parse(rawLinks);
+    const ends = rawLinks.map((raw) => {
+        const [end, v2] = parseEnd(row.id, raw);
+        if (v2)
+            strictEnds = true;
+        return end;
+    });
+    // id v5: каждый источник from — обязательный конец links (класс или полное имя союза
+    // 'Service|Complex') ЛИБО поле data
+    if (idGen.version === 5) {
+        for (const f of idGen.from) {
+            const end = ends.find((e) => e.classes.includes(f) || e.classes.join('|') === f);
+            if (end) {
+                if (end.optional) {
+                    throw new Error(`letopis: class "${row.id}" — id (uuid v5) can't depend on optional end "${f}"`);
+                }
+                continue;
+            }
+            if (f !== 'id' && f in attrs)
+                continue;
+            throw new Error(`letopis: class "${row.id}" — id "from" source "${f}" is neither a link end nor a data field`);
+        }
+    }
     return {
         id: row.id,
         alias: row.alias,
@@ -120,8 +210,10 @@ function buildDef(row, byId) {
         ancestor: row.ancestor,
         ancestors,
         descendants: row.descendants ?? [], // считает триггер schema_lineage
-        attributes: row.attributes,
-        links: row.links ?? [],
+        attributes: merged,
+        links: ends,
+        strictEnds,
+        idGen,
         meta: row.meta ?? {},
         abstract: row.meta?.abstract === true || row.meta?.abstract === 'true',
         order: row.order,

package/dist/sql.d.ts

@@ -55,11 +55,25 @@ export declare const retryDelay: (attempt: number) => Promise<void>;
  * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
  */
 export declare function runQuery<T>(ctx: Ctx, text: string, params: unknown[], mode: QueryEvent['mode'], classes: string[]): Promise<T[]>;
+/** Значение слота связи: id | вложенный план | null (снять конец). */
+export type SlotValue = string | {
+    plan: Step[];
+    mods?: ChainMods;
+} | null;
+/** Уникальная метка узла пути (для pivot-возвратов; переживает нарезку плана). */
+export declare const nextNodeKey: () => number;
 export interface Step {
     /** Имя, как вызвано в цепочке (алиас или id). */
     name: string;
     cls: ClassDef;
     filter?: Filter;
+    /** Метка узла (есть у каждого реального шага). */
+    nodeKey?: number;
+    /**
+     * Pivot: шаг-ВОЗВРАТ к уже введённому узлу (повтор LINK-класса / entity(та же переменная)).
+     * Не создаёт узел; его фильтры дофильтровывают узел (AND); следующий шаг ветвится от узла.
+     */
+    pivotKey?: number;
     /** .alias(name) — ключ шага в путях. */
     aliasKey?: string;
     /** .tags(…) — фильтр по колонке tags: строка | string[] (все) | has/hasAny/hasAll. */
@@ -70,13 +84,17 @@ export interface Step {
     ownerFilter?: string;
     /** Внутреннее (write-цепочки): containment по links — контекст-связи. */
     linksFilter?: Record<string, string>;
-    /** .link(Класс, target) — значение связи при записи БЕЗ участия в фильтре целей. */
-    extraLinks?: Record<string, string>;
+    /**
+     * Слоты связей (`.Класс.set(target)` / `.Класс.unset()`): значения концов записываемой
+     * версии БЕЗ участия в фильтре целей. string — id; {plan} — вложенная цепочка (та же
+     * транзакция, ровно одна сущность класса конца); null — снять optional-конец.
+     */
+    extraLinks?: Record<string, SlotValue>;
     /** Внутреннее (enforceAcl): предикат WRITE/DELETE-правила — цели ищутся только среди своих. */
     aclFilter?: Record<string, unknown>;
     /** .deep(max): рекурсивный self-обход (дети любой глубины), только reverse того же класса. */
     deepMax?: number;
-    /** Операция записи на шаге (.set/.delete/.anonymize) — исполняется терминалом плана. */
+    /** Операция записи на шаге (.create/.update/.delete/.anonymize) — исполняется терминалом плана. */
     op?: import('./types.js').PlanOp;
     /** Внутреннее: шаг «те же сущности» (операция сразу после операции) — цель = строки старта. */
     self?: boolean;
@@ -85,6 +103,8 @@ export declare const entityTable: (pgSchema: string) => string;
 /** Тип листа data-пути по Schema: спуск через record (значение) и object (props). */
 export declare function leafType(cls: ClassDef, path: string[]): FieldType | undefined;
 type HopMode = 'forward' | 'reverse';
+/** Класс target входит в какой-нибудь конец def (союзы учитываются). */
+export declare function linksTo(def: ClassDef, target: string): boolean;
 /** Правило обхода между шагами (по реестру Schema). */
 export declare function resolveHop(prev: ClassDef, next: ClassDef): HopMode;
 export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg';