letopis 0.13.0 → 0.18.0

package/dist/write.js

@@ -1,22 +1,54 @@
 /**
- * Запись: операции .set(data) / .delete(opts) / .anonymize(fields) — ЗВЕНЬЯ цепочки;
- * терминал (rows/first/ids/count/run/versions/агрегации) исполняет весь план
- * ОДНОЙ транзакцией (runPlan) — любой отказ (валидация/ACL) откатывает всё.
+ * Запись: операции .create(data) / .update(data) / .delete(opts) / .anonymize(fields) —
+ * ЗВЕНЬЯ цепочки; терминал (rows/first/ids/count/run/versions/агрегации) исполняет весь
+ * план ОДНОЙ транзакцией (runPlan) — любой отказ (валидация/ACL) откатывает всё.
  *
  * Связи задаются dot-цепочкой: шаги до операции (контекст) резолвятся в ровно одну
  * сущность каждый и дают:
- *   - containment-фильтр целей при UPDATE/DELETE (links ⊇ {Класс: id}),
- *   - links создаваемой строки при INSERT.
+ *   - containment-фильтр целей при update/delete (links ⊇ {Класс: id}),
+ *   - links создаваемой строки при create.
  *
- *   await db.Организация(org).Сотрудник().set({ name: 'Вася' }).rows()   // INSERT + links {Org}
- *   await db.Клиент(c).Запись({ status: 'created' }).set({ status: 'confirmed' }).rows()
- *   await db.Клиент({ vip: true }).set({ bonus: 500 })       // сегмент 1: UPDATE всех vip
- *           .Запись().delete({ confirm: true }).rows()       // сегмент 2: снести записи каждого
+ *   await db.Организация(org).Сотрудник().create({ name: 'Вася' }).rows()  // INSERT + links {Org}
+ *   await db.Клиент(c).Запись({ status: 'created' }).update({ status: 'confirmed' }).rows()
+ *   await db.Клиент({ vip: true }).update({ bonus: 500 })     // сегмент 1: версия каждого vip
+ *           .Запись().delete({ confirm: true }).rows()        // сегмент 2: снести записи каждого
  * Продолжение после операции идёт ОТ ЕЁ РЕЗУЛЬТАТА (fan-out по записанным строкам).
  */
+//
+// FILE: lib/src/write.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Write-side движок: валидация, резолв концов/слотов, вычисление id (v5/v7), вставка новых версий, каскадное удаление, анонимизация, исполнение планов и батчей в транзакции.
+//   SCOPE: ValidationError, runPlan, executeBatch, createOp/updateOp/delOp/anonymizeOp, toRow/readRows/deepMerge, BatchPlan.
+//   DEPENDS: M-UUID, M-TYPES, M-SQL, M-ACL
+//   LINKS: M-WRITE, V-M-WRITE
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   ValidationError - ошибка валидации с полями issues
+//   toRow/readRows/deepMerge - нормализация строки, чтение, deep-merge патча
+//   createOp/updateOp/anonymizeOp/delOp - операции записи (create/update/anonymize/delete)
+//   runPlan - исполнить план (сегменты op + читающий хвост) одной транзакцией
+//   executeBatch - исполнить очередь планов (fast-path multi-insert для чистых INSERT)
+//   BatchPlan/PlanMode - модель плана батча и режимы чтения
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { randomUUID } from 'node:crypto';
+import { uuidv5, uuidv7 } from './uuid.js';
 import { buildRead, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, isTransient, retryDelay, RETRIES, } from './sql.js';
 import { aclDenied } from './acl.js';
+// START_CONTRACT: ValidationError
+//   PURPOSE: Ошибка валидации класса, несущая список проблемных полей (issues).
+//   INPUTS: { cls: string; issues: {field, message?}[] }
+//   OUTPUTS: { Error - message с перечнем «поле — сообщение» }
+//   SIDE_EFFECTS: none
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: ValidationError
 export class ValidationError extends Error {
     issues;
     constructor(cls, issues) {
@@ -58,6 +90,14 @@ export function deepMerge(base, patch) {
     }
     return out;
 }
+// START_CONTRACT: validate
+//   PURPOSE: Проверить данные по fastest-validator (строго, + id) и концы LINK; вернуть очищенные данные.
+//   INPUTS: { cls: ClassDef; id: string; data: object; links: object }
+//   OUTPUTS: { object - валидные данные (без id) }
+//   SIDE_EFFECTS: none
+//   ERRORS: class is abstract; ValidationError; link requires end; stray link(s)
+//   LINKS: M-WRITE, V-M-WRITE, M-SCHEMA
+// END_CONTRACT: validate
 /** Валидация данных по fastest-validator (строгая, + id) и концов LINK. */
 function validate(cls, id, data, links) {
     if (cls.abstract)
@@ -67,23 +107,50 @@ function validate(cls, id, data, links) {
     if (res !== true)
         throw new ValidationError(cls.id, res);
     delete merged.id;
+    // START_BLOCK_VALIDATE_LINK_ENDS
     if (cls.category === 'LINK') {
-        let polymorphic = 0;
         const present = new Set(Object.keys(links));
-        for (const end of cls.links) {
-            if (end === 'Entity')
-                polymorphic++;
-            else if (present.has(end))
-                present.delete(end);
-            else
-                throw new Error(`letopis: link "${cls.id}" requires end "${end}"`);
+        if (cls.strictEnds) {
+            // схема v2: жадный матчинг по порядку объявления концов; союз занимает один ключ;
+            // обязательный конец без ключа и ключ вне концов — ошибки
+            for (const end of cls.links) {
+                const hit = end.classes.find((c) => present.has(c));
+                if (hit)
+                    present.delete(hit);
+                else if (!end.optional)
+                    throw new Error(`letopis: link "${cls.id}" requires end "${end.classes.join('|')}"`);
+            }
+            if (present.size) {
+                throw new Error(`letopis: link "${cls.id}" has stray link(s) ${[...present].map((k) => `"${k}"`).join(', ')} — not an end in Schema.links`);
+            }
         }
-        if (present.size < polymorphic) {
-            throw new Error(`letopis: link "${cls.id}" requires ${polymorphic} polymorphic end(s) (any class), got ${present.size}`);
+        else {
+            // legacy-схема (строковые концы): 'Entity' — полиморф-счётчик, лишние связи молчат
+            let polymorphic = 0;
+            for (const end of cls.links) {
+                const name = end.classes[0];
+                if (name === 'Entity')
+                    polymorphic++;
+                else if (present.has(name))
+                    present.delete(name);
+                else
+                    throw new Error(`letopis: link "${cls.id}" requires end "${name}"`);
+            }
+            if (present.size < polymorphic) {
+                throw new Error(`letopis: link "${cls.id}" requires ${polymorphic} polymorphic end(s) (any class), got ${present.size}`);
+            }
         }
     }
+    // END_BLOCK_VALIDATE_LINK_ENDS
     return merged;
 }
+// START_CONTRACT: insertOne
+//   PURPOSE: INSERT одной строки-версии с ретраем гонок (23505 коллизия updated, 40P01/40001 transient) вне транзакции.
+//   INPUTS: { ctx: Ctx; a: InsertArgs }
+//   OUTPUTS: { Promise<Row> - вставленная строка }
+//   SIDE_EFFECTS: INSERT в Entity через runQuery
+//   LINKS: M-WRITE, V-M-WRITE, M-SQL, M-DDL
+// END_CONTRACT: insertOne
 /** INSERT одной строки с ретраем гонок: 23505 (коллизия updated) и transient (40P01/40001). */
 async function insertOne(ctx, a) {
     // jsonb-параметры — JS-объектами (postgres.js сериализует сам)
@@ -91,6 +158,7 @@ async function insertOne(ctx, a) {
         ctx.partition, a.id, a.cls.id, a.data, a.links, a.tags,
         a.account, a.owner, a.prevUpdated, a.deleted,
     ];
+    // START_BLOCK_INSERT_ONE_RETRY
     for (let attempt = 1;; attempt++) {
         try {
             const res = await runQuery(ctx, insertSql(ctx.pgSchema), params, 'insert', [a.cls.id]);
@@ -109,6 +177,7 @@ async function insertOne(ctx, a) {
             throw e;
         }
     }
+    // END_BLOCK_INSERT_ONE_RETRY
 }
 /**
  * enforceAcl: право операции на класс цели. Предикат победившего правила:
@@ -117,6 +186,14 @@ async function insertOne(ctx, a) {
  *    (явный чужой модификатор на цепочке → ошибка).
  * Мутирует step (объект создаётся цепочкой на вызов — локально безопасно).
  */
+// START_CONTRACT: aclWrite
+//   PURPOSE: enforceAcl-проверка права записи/удаления на класс цели; предикат правила пришпиливает owner/account и фильтрует цели.
+//   INPUTS: { ctx: Ctx; step: Step; op: 'WRITE'|'DELETE' }
+//   OUTPUTS: { void - мутирует step (aclFilter/ownerFilter/accountFilter) }
+//   SIDE_EFFECTS: мутирует step
+//   ERRORS: acl denies WRITE/DELETE; acl pins writes to owner/account
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL
+// END_CONTRACT: aclWrite
 function aclWrite(ctx, step, op) {
     if (!ctx.aclDecide)
         return;
@@ -137,11 +214,6 @@ function aclWrite(ctx, step, op) {
         step[key] = v;
     }
 }
-/**
- * Различие форм фильтра в записи:
- *   Класс()   — БЕЗ аргумента  → INSERT новой сущности;
- *   Класс({}) — пустой объект  → «все найденные» (UPDATE в границах контекста).
- */
 const noFilter = (f) => f === undefined;
 /** Entity.account NOT NULL: модификатор → connect() → System-аккаунт; иначе ошибка. */
 function resolveAccount(ctx, step) {
@@ -165,93 +237,229 @@ function tagsValue(step) {
         return t;
     throw new Error('letopis: .tags() before set() accepts string | string[]');
 }
+/** Конец target, принимающий класс cls (legacy: 'Entity'-конец берёт любой HUB). */
+function endFor(target, cls) {
+    return target.links.find((e) => e.classes.includes(cls.id) || (!target.strictEnds && e.classes.includes('Entity') && cls.category === 'HUB'));
+}
 /**
- * Контекст-шаги (все, кроме последнего) → {КлассId: id}.
- * id-фильтр берётся как есть (без запроса); иной фильтр обязан дать ровно одну сущность.
+ * Связи создаваемой сущности из ПУТИ: каждый реальный шаг-предок, чей класс — конец
+ * target, обязан дать ровно одну сущность (id-фильтр — как есть; иначе чтение путём
+ * от начала до него: контекст честно учитывается).
  */
-async function resolveContext(ctx, steps) {
+// START_CONTRACT: resolvePathEnds
+//   PURPOSE: Связи создаваемой сущности из пути: каждый шаг-предок, чей класс — конец target, должен дать ровно одну сущность.
+//   INPUTS: { ctx: Ctx; steps: Step[] }
+//   OUTPUTS: { Promise<Record<string,string>> - класс конца → id }
+//   SIDE_EFFECTS: чтения контекста (readRows)
+//   ERRORS: context step must resolve to exactly one entity
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: resolvePathEnds
+async function resolvePathEnds(ctx, steps) {
+    const target = steps[steps.length - 1].cls;
     const links = {};
-    for (const step of steps) {
+    for (let k = 0; k < steps.length - 1; k++) {
+        const step = steps[k];
+        if (step.pivotKey !== undefined || step.op)
+            continue;
+        if (!endFor(target, step.cls))
+            continue;
         let id;
         if (typeof step.filter === 'string') {
             id = step.filter;
         }
-        else if (!noFilter(step.filter) || step.tagsFilter !== undefined || step.accountFilter || step.ownerFilter) {
-            const rows = await readRows(ctx, [step], { limit: 2 });
+        else {
+            const rows = await readRows(ctx, steps.slice(0, k + 1), { limit: 2 });
             if (rows.length !== 1) {
                 throw new Error(`letopis: context step "${step.name}" must resolve to exactly one entity (got ${rows.length})`);
             }
             id = rows[0].id;
         }
-        else {
-            throw new Error(`letopis: context step "${step.name}" needs an id or a unique filter`);
-        }
         links[step.cls.id] = id;
     }
     return links;
 }
-/** Шаг поиска целей: фильтр последнего шага + containment контекст-связей. */
-function targetStep(target, contextLinks, explicitId) {
-    return {
-        ...target,
-        filter: explicitId ?? target.filter,
-        linksFilter: Object.keys(contextLinks).length ? contextLinks : undefined,
-    };
+/** Резолв слот-значений: строки как есть; вложенные планы — в той же транзакции, ровно одна сущность. */
+// START_CONTRACT: resolveSlots
+//   PURPOSE: Резолв слот-значений (.Класс.set/.unset): строки как есть, вложенные планы — та же транзакция и ровно одна сущность; союз-конец снимается целиком.
+//   INPUTS: { ctx: Ctx; target: ClassDef; extra: Step['extraLinks'] }
+//   OUTPUTS: { Promise<{ vals: Record<string,string>; drops: Set<string> }> }
+//   SIDE_EFFECTS: может исполнять вложенные планы/чтения
+//   ERRORS: slot value plan must resolve to exactly one entity; resolved to class "<x>"
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: resolveSlots
+async function resolveSlots(ctx, target, extra) {
+    const vals = {};
+    const drops = new Set();
+    for (const [clsId, v] of Object.entries(extra ?? {})) {
+        // союз-замещение: слот занимает КОНЕЦ целиком — соседние классы союза снимаются
+        const end = endFor(target, ctx.registry.resolve(clsId));
+        for (const c of end?.classes ?? [clsId])
+            drops.add(c);
+        if (v === null)
+            continue; // .delete() — только снятие
+        let id;
+        if (typeof v === 'string') {
+            id = v;
+        }
+        else {
+            const rows = v.plan.some((s) => s.op)
+                ? (await runPlan(ctx, v.plan, v.mods ?? {}, 'rows'))
+                : await readRows(ctx, v.plan, { ...(v.mods ?? {}), limit: 2 });
+            if (rows.length !== 1) {
+                throw new Error(`letopis: slot "${clsId}" value plan must resolve to exactly one entity (got ${rows.length})`);
+            }
+            if (rows[0].class !== clsId) {
+                throw new Error(`letopis: slot "${clsId}" value plan resolved to class "${rows[0].class}"`);
+            }
+            id = rows[0].id;
+        }
+        vals[clsId] = id;
+    }
+    return { vals, drops };
+}
+/** id новой сущности по IdGen класса (v5 считается отдельно — нужны концы/данные). */
+const genId = (cls) => (cls.idGen.version === 7 ? uuidv7() : randomUUID());
+/**
+ * default поля из правила Schema.attributes: объект-правило `{default: …}` или
+ * DSL-строка `'string|default:базовая'`. Нужен v5Id: id считается ДО валидации (та
+ * подставляет defaults позже), поэтому необязательное from-поле берёт дефолт здесь.
+ */
+function defaultOf(rule) {
+    if (rule && typeof rule === 'object' && !Array.isArray(rule) && 'default' in rule) {
+        return rule.default;
+    }
+    if (typeof rule === 'string') {
+        const seg = rule.split('|').map((s) => s.trim()).find((s) => s.startsWith('default:'));
+        if (seg)
+            return seg.slice('default:'.length);
+    }
+    return undefined;
+}
+/**
+ * Детерминированный id (uuid v5): имя = «схема:партиция:класс:значения from».
+ * from-источник — конец Schema.links (класс или полное имя союза 'Service|Complex';
+ * значение — id присутствующего класса конца) или скалярное поле data (если не задано —
+ * его default из Schema.attributes: id стабилен и без явного ввода необязательного поля).
+ */
+// START_CONTRACT: v5Id
+//   PURPOSE: Детерминированный id (uuid v5) из «схема:партиция:класс:значения from» (концы Schema.links или скалярные поля/дефолты).
+//   INPUTS: { ctx: Ctx; cls: ClassDef; links: object; data: object }
+//   OUTPUTS: { string - uuid v5 }
+//   SIDE_EFFECTS: none
+//   ERRORS: needs end "<...>"; needs scalar data field "<f>"
+//   LINKS: M-WRITE, V-M-WRITE, M-UUID
+// END_CONTRACT: v5Id
+function v5Id(ctx, cls, links, data) {
+    const parts = [];
+    for (const f of cls.idGen.from) {
+        const end = cls.links.find((e) => e.classes.includes(f) || e.classes.join('|') === f);
+        if (end) {
+            const hit = end.classes.find((c) => c in links);
+            if (!hit) {
+                throw new Error(`letopis: id (uuid v5) of "${cls.id}" needs end "${end.classes.join('|')}" — set it in the path or with a slot`);
+            }
+            parts.push(links[hit]);
+        }
+        else {
+            const v = data[f] === undefined ? defaultOf(cls.attributes[f]) : data[f];
+            if (v === undefined || v === null || typeof v === 'object') {
+                throw new Error(`letopis: id (uuid v5) of "${cls.id}" needs scalar data field "${f}"`);
+            }
+            parts.push(String(v));
+        }
+    }
+    return uuidv5(`${ctx.pgSchema}:${ctx.partition}:${cls.id}:${parts.join(':')}`);
+}
+/** Новая версия каждой строки: deep-merge данных + слоты концов (союз-конец замещается целиком). */
+async function versionRows(ctx, target, found, data, slots) {
+    const cls = target.cls;
+    const out = [];
+    for (const row of found) {
+        const mergedData = deepMerge(row.data, data); // только указанные листья
+        const mergedLinks = { ...row.links };
+        for (const c of slots.drops)
+            delete mergedLinks[c];
+        Object.assign(mergedLinks, slots.vals);
+        const full = validate(cls, row.id, mergedData, mergedLinks);
+        out.push(await insertOne(ctx, {
+            id: row.id, cls, data: full, links: mergedLinks,
+            tags: tagsValue(target) ?? row.tags, account: row.account, owner: row.owner,
+            prevUpdated: row.updated, deleted: null,
+        }));
+    }
+    return out;
 }
 /**
- * .set(data):
- *  - пустой фильтр последнего шага и нет data.id → INSERT (links = контекст);
- *  - id (фильтр-строка или data.id) → UPSERT: есть → новая версия (deep-merge), нет → создать;
- *  - фильтр-объект → новая версия каждого найденного (в границах контекста); пусто → [].
+ * .create(data) — «чтобы сущность существовала»:
+ *  - id не задан → INSERT (id по IdGen класса; links = концы из пути + слоты);
+ *  - id известен (Класс(id) / data.id / вычислен v5): есть → новая версия (deep-merge),
+ *    нет → INSERT с этим id (идемпотентный create, REST-PUT семантика);
+ *  - фильтр-объект / pivot — ошибка: create не ищет, это update().
  */
-export async function setOp(ctx, steps, mods, data) {
+// START_CONTRACT: createOp
+//   PURPOSE: .create(data) — INSERT новой сущности либо новая версия при известном/вычисленном id (идемпотентный create); поиск — это update().
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; data: object }
+//   OUTPUTS: { Promise<Row[]> }
+//   SIDE_EFFECTS: INSERT в Entity (в транзакции runPlan)
+//   ERRORS: create() on a pivot; takes no filter; got two ids; computes id (remove explicit); acl denies WRITE
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL
+// END_CONTRACT: createOp
+export async function createOp(ctx, steps, mods, data) {
+    // START_BLOCK_CREATE_RESOLVE
     const target = steps[steps.length - 1];
     const cls = target.cls;
     aclWrite(ctx, target, 'WRITE');
-    // контекст-шаги: и фильтр целей, и значения; .link() — ТОЛЬКО значения (фильтр не трогает)
-    const contextLinks = await resolveContext(ctx, steps.slice(0, -1));
-    const writeLinks = { ...contextLinks, ...(target.extraLinks ?? {}) };
-    const dataId = typeof data.id === 'string' ? data.id : undefined;
+    if (target.pivotKey !== undefined) {
+        throw new Error(`letopis: create() on a pivot step — pivot returns to an existing node, use update()`);
+    }
     const filterId = typeof target.filter === 'string' ? target.filter : undefined;
-    const explicitId = filterId ?? dataId;
-    const insertMode = noFilter(target.filter); // Класс() без аргумента
-    const found = insertMode && !explicitId
-        ? []
-        : await readRows(ctx, [targetStep(target, contextLinks, explicitId)], mods);
-    if (found.length) {
-        const out = [];
-        for (const row of found) {
-            const mergedData = deepMerge(row.data, data); // только указанные листья
-            const mergedLinks = { ...row.links, ...writeLinks }; // контекст + .link()
-            const full = validate(cls, row.id, mergedData, mergedLinks);
-            out.push(await insertOne(ctx, {
-                id: row.id, cls, data: full, links: mergedLinks,
-                tags: tagsValue(target) ?? row.tags, account: row.account, owner: row.owner,
-                prevUpdated: row.updated, deleted: null,
-            }));
+    if (!noFilter(target.filter) && filterId === undefined) {
+        throw new Error(`letopis: create() takes no filter — ${cls.alias}(id).create(…) fixes the id, searching is update()`);
+    }
+    // слоты (.Класс.set/.unset): значения/снятия концов; союз-конец замещается целиком
+    const slots = await resolveSlots(ctx, cls, target.extraLinks);
+    const dataId = typeof data.id === 'string' ? data.id : undefined;
+    if (filterId && dataId && filterId !== dataId) {
+        throw new Error(`letopis: create() got two ids — step "${filterId}" vs data.id "${dataId}"`);
+    }
+    let explicitId = filterId ?? dataId;
+    // связи создаваемого: концы из пути + слоты (слоты выигрывают, unset снимает)
+    const pathEnds = await resolvePathEnds(ctx, steps);
+    const writeLinks = { ...pathEnds };
+    for (const c of slots.drops)
+        delete writeLinks[c];
+    Object.assign(writeLinks, slots.vals);
+    if (cls.idGen.version === 5) {
+        if (explicitId) {
+            throw new Error(`letopis: class "${cls.id}" computes id (uuid v5 from ${cls.idGen.from.join(', ')}) — remove the explicit id`);
         }
-        return out;
+        explicitId = v5Id(ctx, cls, writeLinks, data);
     }
-    // не найдено: INSERT только при явном id или Класс() без аргумента
-    if (!explicitId && !insertMode)
-        return [];
-    // enforceAcl-предикат + явный id: «не нашёл среди доступных» НЕ значит «можно создать» —
-    // существующая, но недоступная сущность иначе перехватывалась бы новой версией с чужим owner.
-    // Проверка существования — БЕЗ предиката и БЕЗ пришпиленных им колонок.
-    if (explicitId && target.aclFilter) {
-        const bare = { ...ctx, aclDecide: undefined };
-        const probe = {
-            ...targetStep(target, contextLinks, explicitId),
-            aclFilter: undefined,
-            ownerFilter: undefined,
-            accountFilter: undefined,
-            linksFilter: undefined,
-        };
-        const taken = await readRows(bare, [probe], {});
-        if (taken.length)
-            return [];
+    if (explicitId !== undefined) {
+        // id известен и существует (в границах пути) → новая версия
+        const pathSteps = [...steps.slice(0, -1), { ...target, filter: explicitId }];
+        const found = await readRows(ctx, pathSteps, mods);
+        if (found.length)
+            return versionRows(ctx, target, found, data, slots);
+        // enforceAcl-предикат: «не нашёл среди доступных» НЕ значит «можно создать» —
+        // существующая, но недоступная сущность иначе перехватывалась бы новой версией
+        // с чужим owner. Проверка существования — БЕЗ предиката и пришпиленных колонок.
+        if (target.aclFilter) {
+            const bare = { ...ctx, aclDecide: undefined };
+            const probe = {
+                ...target,
+                filter: explicitId,
+                aclFilter: undefined,
+                ownerFilter: undefined,
+                accountFilter: undefined,
+                linksFilter: undefined,
+            };
+            const taken = await readRows(bare, [probe], {});
+            if (taken.length)
+                return [];
+        }
     }
-    const id = explicitId ?? randomUUID();
+    const id = explicitId ?? genId(cls);
     const account = resolveAccount(ctx, target);
     const owner = target.ownerFilter ?? ctx.owner ?? account;
     const full = validate(cls, id, data, writeLinks);
@@ -261,6 +469,31 @@ export async function setOp(ctx, steps, mods, data) {
             tags: tagsValue(target) ?? [], account, owner, prevUpdated: null, deleted: null,
         }),
     ];
+    // END_BLOCK_CREATE_RESOLVE
+}
+/**
+ * .update(data?) — новая версия КАЖДОГО найденного путём (deep-merge листьев);
+ * цели: Класс() ≡ Класс({}) — все в границах контекста, id/фильтр/pivot — как в чтении.
+ * Не найдено → [] — update НИКОГДА не создаёт.
+ */
+// START_CONTRACT: updateOp
+//   PURPOSE: .update(data?) — новая версия каждого найденного путём (deep-merge листьев); никогда не создаёт.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; data: object }
+//   OUTPUTS: { Promise<Row[]> }
+//   SIDE_EFFECTS: INSERT новых версий
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: updateOp
+export async function updateOp(ctx, steps, mods, data) {
+    const target = steps[steps.length - 1];
+    aclWrite(ctx, target, 'WRITE');
+    const slots = await resolveSlots(ctx, target.cls, target.extraLinks);
+    // data.id — цель, только если у шага нет своего фильтра
+    const dataId = typeof data.id === 'string' ? data.id : undefined;
+    const pathSteps = noFilter(target.filter) && dataId !== undefined
+        ? [...steps.slice(0, -1), { ...target, filter: dataId }]
+        : steps;
+    const found = await readRows(ctx, pathSteps, mods); // честный путь: переходы, pivot
+    return versionRows(ctx, target, found, data, slots);
 }
 /**
  * .anonymize(fields): GDPR-затирание — новая версия с '[erased]' в указанных string-полях
@@ -275,8 +508,7 @@ export async function anonymizeOp(ctx, steps, mods, fields) {
             throw new Error(`letopis: anonymize() erases string fields only; "${f}" is ${cls.fieldTypes.get(f)?.kind ?? 'unknown'}`);
         }
     }
-    const contextLinks = await resolveContext(ctx, steps.slice(0, -1));
-    const found = await readRows(ctx, [targetStep(target, contextLinks)], mods);
+    const found = await readRows(ctx, steps, mods); // цели — честный путь
     const out = [];
     for (const row of found) {
         const patch = Object.fromEntries(fields.filter((f) => f in row.data).map((f) => [f, '[erased]']));
@@ -295,6 +527,7 @@ export async function anonymizeOp(ctx, steps, mods, fields) {
 async function inTransaction(ctx, fn) {
     if (ctx.inTx)
         return fn(ctx);
+    // START_BLOCK_IN_TRANSACTION_RETRY
     for (let attempt = 1;; attempt++) {
         try {
             return (await ctx.sql.begin(async (tsql) => fn({ ...ctx, sql: tsql, inTx: true })));
@@ -307,6 +540,7 @@ async function inTransaction(ctx, fn) {
             throw e;
         }
     }
+    // END_BLOCK_IN_TRANSACTION_RETRY
 }
 /**
  * .delete({confirm}): цели = фильтр последнего шага + контекст-связи.
@@ -314,14 +548,22 @@ async function inTransaction(ctx, fn) {
  * каскад + advisory-lock); возвращает ВСЁ удалённое (цели + каскад) с $deleted: true.
  * Без confirm — ПРЕВЬЮ: то же замыкание (цели + каскад), но БД не трогается.
  */
+// START_CONTRACT: delOp
+//   PURPOSE: .delete({confirm}) — серверное удаление (tombstone + рекурсивный каскад) при confirm, иначе превью замыкания; DELETE-право на каждый класс каскада.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; confirm: boolean }
+//   OUTPUTS: { Promise<Row[]> - удалённые (цели+каскад) с $deleted, либо превью }
+//   SIDE_EFFECTS: DELETE в Entity (триггер entity_delete) при confirm
+//   ERRORS: acl denies DELETE (в каскаде)
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL, M-DDL
+// END_CONTRACT: delOp
 export async function delOp(ctx, steps, mods, confirm) {
     const target = steps[steps.length - 1];
     aclWrite(ctx, target, 'DELETE');
-    const contextLinks = await resolveContext(ctx, steps.slice(0, -1));
-    const targets = await readRows(ctx, [targetStep(target, contextLinks)], mods);
+    const targets = await readRows(ctx, steps, mods); // цели — честный путь
     if (!targets.length)
         return [];
     const params = [ctx.partition, target.cls.id, ...targets.map((r) => r.id)];
+    // START_BLOCK_DELETE_CASCADE
     return inTransaction(ctx, async (c) => {
         const closure = await runQuery(c, closureSql(c.pgSchema, targets.length), params, 'delete', [target.cls.id]);
         if (!confirm)
@@ -337,6 +579,7 @@ export async function delOp(ctx, steps, mods, confirm) {
         await runQuery(c, deleteSql(c.pgSchema, targets.length), params, 'delete', [target.cls.id]);
         return closure.map((r) => ({ ...toRow(r), $deleted: true }));
     });
+    // END_BLOCK_DELETE_CASCADE
 }
 /** Разрезать план: сегменты (…шаги + op-шаг) и читающий хвост после последней операции. */
 function splitPlan(steps) {
@@ -353,8 +596,10 @@ function splitPlan(steps) {
 }
 function opCall(c, steps, op) {
     switch (op.kind) {
-        case 'set':
-            return setOp(c, steps, op.mods, op.data ?? {});
+        case 'create':
+            return createOp(c, steps, op.mods, op.data ?? {});
+        case 'update':
+            return updateOp(c, steps, op.mods, op.data ?? {});
         case 'anonymize':
             return anonymizeOp(c, steps, op.mods, op.fields ?? []);
         case 'delete':
@@ -378,9 +623,17 @@ const RawRowFmt = {
  * строки результата (контекст = строка); self-шаг (op сразу после op) пишет в те же строки.
  * После delete продолжение идёт от строк КЛАССА ЦЕЛИ (замыкание каскада шире).
  */
+// START_CONTRACT: runPlan
+//   PURPOSE: Исполнить план целиком (сегменты операций + читающий хвост) одной транзакцией; продолжение = fan-out по строкам результата.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; mode: PlanMode }
+//   OUTPUTS: { Promise<unknown> - результат в запрошенном режиме }
+//   SIDE_EFFECTS: записи + чтения в одной транзакции
+//   LINKS: M-WRITE, V-M-WRITE, M-SQL
+// END_CONTRACT: runPlan
 export async function runPlan(ctx, steps, mods, mode) {
     const { segments, tail } = splitPlan(steps);
     return inTransaction(ctx, async (c) => {
+        // START_BLOCK_RUNPLAN_SEGMENTS
         let last = []; // полный результат последней операции (для терминала)
         let start = []; // строки для продолжения (класс цели)
         for (let i = 0; i < segments.length; i++) {
@@ -400,6 +653,7 @@ export async function runPlan(ctx, steps, mods, mode) {
             }
             start = seg.op.kind === 'delete' ? last.filter((r) => r.class === targetCls.id) : last;
         }
+        // END_BLOCK_RUNPLAN_SEGMENTS
         const opStep = segments[segments.length - 1].steps.at(-1);
         const keyName = opStep.aliasKey ?? opStep.name;
         // хвост-чтение от результата последней операции (в той же транзакции)
@@ -473,10 +727,18 @@ async function readByMode(c, steps, mods, mode) {
     }
 }
 const isPureInsertPlan = (p) => p.steps.length === 1 &&
-    p.steps[0].op?.kind === 'set' &&
+    p.steps[0].op?.kind === 'create' &&
     noFilter(p.steps[0].filter) &&
     typeof p.steps[0].op.data?.id !== 'string' &&
-    !Object.keys(p.steps[0].extraLinks ?? {}).length;
+    !Object.keys(p.steps[0].extraLinks ?? {}).length &&
+    p.steps[0].cls.idGen.version !== 5;
+// START_CONTRACT: executeBatch
+//   PURPOSE: Исполнить очередь планов одной транзакцией; подряд идущие чистые INSERT одного класса склеиваются в multi-VALUES.
+//   INPUTS: { ctx: Ctx; queue: BatchPlan[] }
+//   OUTPUTS: { Promise<Row[][]> - результат по каждому плану }
+//   SIDE_EFFECTS: INSERT (multi/по-плану) в транзакции
+//   LINKS: M-WRITE, V-M-WRITE, M-SQL
+// END_CONTRACT: executeBatch
 export async function executeBatch(ctx, queue) {
     if (!queue.length)
         return [];
@@ -484,6 +746,7 @@ export async function executeBatch(ctx, queue) {
         const results = new Array(queue.length);
         let i = 0;
         while (i < queue.length) {
+            // START_BLOCK_BATCH_FASTPATH
             if (isPureInsertPlan(queue[i])) {
                 const cls = queue[i].steps[0].cls;
                 let j = i;
@@ -493,8 +756,8 @@ export async function executeBatch(ctx, queue) {
                 const params = [];
                 for (const g of group) {
                     const s = { ...g.steps[0] };
-                    aclWrite(c, s, 'WRITE'); // склейка multi-VALUES идёт мимо setOp — право+пришпиливание на каждый
-                    const id = randomUUID();
+                    aclWrite(c, s, 'WRITE'); // склейка multi-VALUES идёт мимо createOp — право+пришпиливание на каждый
+                    const id = genId(cls);
                     const full = validate(cls, id, s.op?.data ?? {}, {});
                     const account = resolveAccount(c, s);
                     params.push(c.partition, id, cls.id, full, {}, tagsValue(s) ?? [], account, s.ownerFilter ?? c.owner ?? account);
@@ -505,6 +768,7 @@ export async function executeBatch(ctx, queue) {
                 i = j;
                 continue;
             }
+            // END_BLOCK_BATCH_FASTPATH
             results[i] = (await runPlan(c, queue[i].steps, {}, 'rows'));
             i++;
         }