letopis 2.0.0 → 3.0.0

package/dist/write.js

@@ -17,11 +17,11 @@
  * строка видна, но править нельзя — acl_denied; строки уже нет — target_not_found; номер версии
  * разошёлся со { rev } — conflict.
  */
-import { lerr, ValidationError } from './errors.js';
+import { fromDbError, issuesFromDb, lerr, lmsg, LetopisError, ValidationError } from './errors.js';
 import { isOp } from './ops.js';
 import { accepts, buildRead, nextNodeKey, precheckStep, resolveHop, stepClasses, toRow } from './sql.js';
 import { idOf } from './uuid.js';
-import { applyDefaults } from './validate.js';
+import { applyDefaults, leavesToDb } from './validate.js';
 // ---------------------------------------------------------------------------
 // Приращение: маркер, которого не получить из JSON (§2.5)
 // ---------------------------------------------------------------------------
@@ -36,6 +36,29 @@ export function inc(by, opts = {}) {
     return Object.freeze({ [INC]: true, by, ...(opts.start !== undefined ? { start: opts.start } : {}) });
 }
 export const isInc = (v) => typeof v === 'object' && v !== null && v[INC] === true;
+/**
+ * Данные create() и upsert() без ключей со значением undefined — как у патча update() (splitPatch): ключ undefined JSON
+ * не передаёт, а валидатор на TypeScript принимал его за поле не того типа (план 2.1, A12). Вложенные объекты — тоже;
+ * массивы, даты, маркеры и операторы — как есть.
+ */
+export function dropUndefined(data) {
+    if (!isPlain(data))
+        return data;
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (v === undefined)
+            continue;
+        out[k] = isPlain(v) ? dropUndefined(v) : v;
+    }
+    return out;
+}
+/** expect — список строк { id, rev } (и $action у превью удаления): иначе invalid_query до записи. */
+function checkExpect(expect, verb) {
+    const ok = Array.isArray(expect) && expect.every((x) => x !== null && typeof x === 'object' && typeof x.id === 'string'
+        && Number.isInteger(x.rev) && x.rev >= 1);
+    if (!ok)
+        throw lerr('write.bad_expect', { verb });
+}
 /** Причина изменения: строка до 1000 символов без NUL (её не принимает set_config). */
 export function checkReason(v, where) {
     if (typeof v !== 'string' || v.length > 1000 || v.includes('\0')) {
@@ -44,7 +67,9 @@ export function checkReason(v, where) {
     return v;
 }
 const asList = (v) => (Array.isArray(v) ? v : [v]);
-const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date) && !isInc(v) && !isOp(v);
+function isPlain(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date) && !isInc(v) && !isOp(v);
+}
 /** Патч update → остаток для merge и список приращений. Недопустимое — invalid_data до отправки. */
 export function splitPatch(patch) {
     const incs = [];
@@ -97,6 +122,51 @@ export function splitPatch(patch) {
 // ---------------------------------------------------------------------------
 // Проверки до отправки (precheckPlan)
 // ---------------------------------------------------------------------------
+/**
+ * Нарушения, найденные валидатором на TypeScript у класса с правилами только для базы (`pattern`): полный список даст
+ * база (completeIssues). Ключ — сама ошибка.
+ */
+const PENDING = new WeakMap();
+/**
+ * Ключи данных, которые не поля класса, а его концы (связи): имя роли конца или имя класса на конце (у роли с другим
+ * именем). Пары [ключ, роль] — для текста «задайте .Роль.set(id)» (write.link_in_data, 3.0): подсказка в самом тексте
+ * ошибки, а не только в err.hint.
+ */
+function endsAsFields(cls, data, skip) {
+    const props = (cls.schema.properties ?? {});
+    const out = [];
+    for (const k of Object.keys(data)) {
+        if (data[k] === undefined || k in props || k === skip)
+            continue;
+        if (cls.ends[k] !== undefined) {
+            out.push([k, k]);
+            continue;
+        }
+        const role = Object.entries(cls.ends).find(([, e]) => (Array.isArray(e.class) ? e.class : [e.class]).includes(k))?.[0];
+        if (role !== undefined)
+            out.push([k, role]);
+    }
+    return out;
+}
+/** Ключ и параметры ошибки «конец передан полем данных» (write.link_in_data). */
+function linkInData(cls, verb, found) {
+    return { key: 'write.link_in_data', params: { verb, cls: cls.name, keys: found.map(([k]) => k).join(', '), role: found[0][1] } };
+}
+/**
+ * Патч update() с ключом — именем конца класса, которого нет среди полей: база отклонила бы его (лишний ключ верхнего
+ * уровня) — отказ до записи с подсказкой «конец — из пути или .Роль.set()» (план 2.1, A8). data.id цели — не данные.
+ */
+function checkPatchEnds(s, patch) {
+    const cls = s.cls;
+    if (cls.name === 'Class' || cls.abstract || cls.schema.additionalProperties !== false)
+        return;
+    const useDataId = s.filter === undefined && typeof patch.id === 'string';
+    const found = endsAsFields(cls, patch, useDataId ? 'id' : undefined);
+    if (!found.length)
+        return;
+    const issue = { path: [], keyword: 'additionalProperties', message: lmsg('model.issue_additional', { keys: found.map(([k]) => k).join(', ') }) };
+    throw new ValidationError(cls.name, [issue], linkInData(cls, 'update', found));
+}
 /** Данные create/upsert: объект без маркеров; ранняя проверка валидатором на TypeScript. */
 function checkFullData(cls, data, verb) {
     if (!isPlain(data))
@@ -116,9 +186,57 @@ function checkFullData(cls, data, verb) {
     // описания системных классов проверяет только база (метасхема Class, class_admit)
     if (cls.name === 'Class' || cls.abstract)
         return;
-    const issues = cls.validator()(applyDefaults(cls.schema, data));
-    if (issues.length)
-        throw new ValidationError(cls.name, issues);
+    const v = cls.validator();
+    const full = applyDefaults(cls.schema, data);
+    const issues = v(full);
+    if (!issues.length)
+        return;
+    const found = endsAsFields(cls, data);
+    const e = new ValidationError(cls.name, issues, found.length ? linkInData(cls, verb, found) : undefined);
+    if (leavesToDb(v))
+        PENDING.set(e, { cls: cls.name, data: full });
+    throw e;
+}
+/**
+ * Ошибка данных до записи у класса с правилами только для базы (`pattern`): валидатор на TypeScript нашёл не всё — полный
+ * список нарушений даёт база одним запросом (`validate_row`, план 2.1, A8), под точкой сохранения: неудача запроса
+ * (схема прежней ревизии) не ломает db.begin(), остаётся прежняя ошибка. Прочие ошибки — как есть.
+ */
+export async function completeIssues(ctx, e) {
+    const p = e instanceof ValidationError ? PENDING.get(e) : undefined;
+    if (!p)
+        return e;
+    const S = quoteId(ctx.schema);
+    let raw;
+    try {
+        raw = await ctx.exec.run(async (q) => {
+            await q.unsafe('savepoint letopis_issues');
+            try {
+                const [r] = (await q.unsafe(`select ${S}.validate_row($1::text, $2::jsonb) as v`, [p.cls, p.data]));
+                await q.unsafe('release savepoint letopis_issues');
+                return r?.v;
+            }
+            catch {
+                await q.unsafe('rollback to savepoint letopis_issues');
+                return null;
+            }
+        }, { read: true });
+    }
+    catch {
+        return e;
+    }
+    if (!Array.isArray(raw) || !raw.length)
+        return e;
+    const v = e;
+    return Object.assign(new ValidationError(p.cls, issuesFromDb(raw), v.key ? { key: v.key, params: v.params } : undefined), { cause: e });
+}
+/**
+ * Блокировка строк в порядке id (lockedRead, updateOp — for no key update; deleteOp с expect — for update): id, которые
+ * удалось заблокировать.
+ */
+export async function lockIds(q, S, ids, mode = 'no key update') {
+    const rows = (await q.unsafe(`select id from ${S}.entity where id = any ($1::uuid[]) order by id for ${mode}`, [ids], { prepare: true }));
+    return new Set(rows.map((r) => r.id));
 }
 /** Фильтр шага сужает цели: id, список id, оператор, строка ответа, объект хотя бы с одним заданным полем. */
 const narrowingFilter = (f) => f !== undefined && f !== null && (typeof f !== 'object' || Array.isArray(f) || isOp(f) || Object.values(f).some((v) => v !== undefined));
@@ -139,6 +257,13 @@ function narrowed(steps, i) {
     }
     return false;
 }
+/** Шаги сегмента глагола шага i: от шага после прежнего глагола до него самого. */
+function segmentOf(steps, i) {
+    let j = i - 1;
+    while (j >= 0 && !steps[j].op)
+        j--;
+    return steps.slice(j + 1, i + 1);
+}
 /**
  * Всё, что проверяется без базы, — до отправки первого оператора (§2.5). Фильтры шагов и поля sort() и агрегатов
  * (неизвестное поле — invalid_query, план 2.0, этап 3, п. 3) — precheckStep построителя; order и agg — модификатор и
@@ -161,8 +286,9 @@ export function precheckPlan(reg, steps, order, agg) {
         const m = s.opMods ?? {};
         if (m.asOf !== undefined)
             throw lerr('write.as_of_write', { verb });
-        // restore сам ищет удалённые объекты шага
-        if (m.withDeleted && verb !== 'restore')
+        // restore сам ищет удалённые объекты шага; withDeleted() — модификатор шага (план 2.1, A9): у шага глагола или шага
+        // до него в сегменте — отказ, как прежде у модификатора цепочки
+        if (verb !== 'restore' && segmentOf(steps, i).some((x) => x.withDeleted))
             throw lerr('write.with_deleted_write', { verb });
         switch (op.kind) {
             case 'create':
@@ -185,6 +311,7 @@ export function precheckPlan(reg, steps, order, agg) {
                 if (!isPlain(op.data))
                     throw lerr('write.patch_not_object');
                 splitPatch(op.data);
+                checkPatchEnds(s, op.data);
                 if (op.rev !== undefined && (!Number.isInteger(op.rev) || op.rev < 1))
                     throw lerr('write.bad_rev');
                 // строгий режим (план 2.0, этап 4, п. 2; 7.10 №2): правка без сужения целей — отказ до записи, все строки —
@@ -194,11 +321,28 @@ export function precheckPlan(reg, steps, order, agg) {
                 }
                 break;
             case 'delete':
-                // превью (без confirm) ничего не удаляет — его не сужают
+                // превью (без confirm) ничего не удаляет — его не сужают и не сверяют
+                if (op.expect !== undefined) {
+                    if (!op.confirm)
+                        throw lerr('write.expect_without_confirm');
+                    checkExpect(op.expect, verb);
+                }
+                // 3.0: удаление сверяется с превью, которое видел пользователь (expect); без сверки — только осознанно, { all: true }
+                if (op.confirm && op.expect === undefined && !op.all)
+                    throw lerr('write.confirm_without_expect');
                 if (op.confirm && !op.all && !narrowed(steps, i))
-                    throw lerr('write.no_filter', { call: 'delete({ confirm: true })', cls: s.cls.name });
+                    throw lerr('write.no_filter', { call: 'delete({ confirm: true, expect })', cls: s.cls.name });
                 break;
             case 'restore':
+                // partial (второй раунд 2.1, A3) — только с expect: пропуск считается по показанным надгробиям
+                if (op.partial && op.expect === undefined)
+                    throw lerr('write.partial_without_expect');
+                if (op.expect !== undefined)
+                    checkExpect(op.expect, verb);
+                // 3.0: без expect — отказ, и для явных id тоже: restore вернул бы последнее надгробие, а не то, что видел
+                // пользователь (объект могли восстановить, поменять и удалить снова); вернуть всё без сверки — { all: true }
+                else if (!op.all)
+                    throw lerr('write.restore_without_expect');
                 break;
         }
         for (const sl of s.slots ?? []) {
@@ -349,7 +493,8 @@ async function slotIds(w, v) {
             // отдаёт строки чтения (план 2.0, 7.2 №3: раньше — TypeError)
             precheckPlan(w.reg, v.plan);
             const r = await execPlan(w, v.plan, v.mods, 'rows');
-            rows = r.kind === 'rows' ? r.rows : r.res;
+            // чтение хвоста отдаёт строки в обёртке { row } (readIn, режим 'rows') — как в батче, распаковать
+            rows = r.kind === 'rows' ? r.rows : r.res.map((x) => toRow(x.row));
         }
         else {
             rows = await readRows(w, v.plan, v.mods);
@@ -462,6 +607,11 @@ function inTargetOrder(ids, rows) {
     const pos = new Map(ids.map((id, i) => [id, i]));
     return rows.sort((a, b) => (pos.get(a.id) ?? 0) - (pos.get(b.id) ?? 0));
 }
+/** Шаги сужены только по id: фильтр — id или список id, без tags(), owner() и обхода deep(). */
+function idsOnly(steps) {
+    return steps.every((s) => (s.filter === undefined || typeof s.filter === 'string' || (Array.isArray(s.filter) && s.filter.every((x) => typeof x === 'string')))
+        && s.tagsFilter === undefined && s.ownerFilter === undefined);
+}
 /** Цели update и delete: id из пути (limit и sort сужают); data.id — если у шага нет фильтра. */
 async function targetIds(w, steps, opStep, dataId) {
     const path = steps.map(bare);
@@ -478,7 +628,15 @@ async function updateOp(w, steps, opStep) {
     // data.id — цель, только если у шага нет своего фильтра (write.ts:461-466 в 0.21); тогда id не данные
     const useDataId = opStep.filter === undefined && typeof op.data.id === 'string';
     const { id: dataId, ...data } = op.data;
-    const ids = await targetIds(w, steps, opStep, useDataId ? dataId : undefined);
+    let ids = await targetIds(w, steps, opStep, useDataId ? dataId : undefined);
+    // цели сужены не только по id (данные, концы, tags(), owner()): как lockedRead — блокировка целей и то же чтение заново;
+    // правятся только строки, которые и после ожидания блокировки подходят под условия (план 2.1, A4). Без гонки — те же
+    // цели; строка, которую не дала заблокировать RLS, остаётся в целях — её объяснит explainMissing
+    if (ids.length && !idsOnly(steps)) {
+        const locked = await lockIds(w.q, S, ids);
+        const fresh = new Set(await targetIds(w, steps, opStep, useDataId ? dataId : undefined));
+        ids = ids.filter((id) => fresh.has(id) || !locked.has(id));
+    }
     if (op.rev !== undefined) {
         if (ids.length > 1)
             throw lerr('write.rev_many_targets', { step: opStep.name, count: ids.length });
@@ -508,24 +666,53 @@ async function updateOp(w, steps, opStep) {
     }
     return inTargetOrder(ids, res.map((r) => toRow(r.row)));
 }
+/** Превью удаления целей: то же замыкание, что у триггера удаления (ref_action), база не меняется. */
+async function previewOf(w, ids) {
+    const S = quoteId(w.schema);
+    const res = await query(w, `select ${rowJson('e')} as row, p.action, p.depth from ${S}.delete_preview($1::uuid[]) p `
+        + `join ${S}.entity e on e.id = p.id order by p.depth nulls last, p.action, e.id`, [ids]);
+    return res.map((r) => {
+        const row = toRow(r.row);
+        row.$action = r.action;
+        if (r.depth !== null)
+            row.$depth = r.depth;
+        return row;
+    });
+}
+/** Превью совпадает с показанным: те же строки по id, с теми же rev и $action (порядок не важен). */
+function samePreview(now, expect) {
+    if (now.length !== expect.length)
+        return false;
+    const want = new Map(expect.map((x) => [x.id.toLowerCase(), x]));
+    return now.every((r) => {
+        const x = want.get(r.id.toLowerCase());
+        return x !== undefined && x.rev === r.rev && (x.$action === undefined || x.$action === r.$action);
+    });
+}
 async function deleteOp(w, steps, opStep) {
     const op = opStep.op;
     const S = quoteId(w.schema);
     const ids = await targetIds(w, steps, opStep);
+    if (!op.confirm)
+        return ids.length ? previewOf(w, ids) : [];
+    // delete({ confirm: true, expect }): удалить ровно показанное (план 2.1, A2) — превью заново в той же транзакции.
+    // Атомарно (второй раунд 2.1, A1): всё замыкание каскада (строки превью с $action 'delete') блокируется for update в
+    // порядке id, и превью строится ещё раз уже под блокировкой. Вставка связи берёт на своих концах for key share
+    // (60-write.sql, targets_bad): с for update она конфликтует, с for no key update — нет. Вставщик успел первым —
+    // пересчёт видит его строку (preview_changed); мы первые — он получает end_target_missing. Взаимоблокировку при росте
+    // замыкания повторяет runTx (40P01)
+    if (op.expect !== undefined) {
+        let now = ids.length ? await previewOf(w, ids) : [];
+        const closure = now.filter((r) => r.$action === 'delete').map((r) => r.id);
+        if (closure.length) {
+            await lockIds(w.q, S, closure, 'update');
+            now = await previewOf(w, ids);
+        }
+        if (!samePreview(now, op.expect))
+            throw lerr('write.preview_changed', undefined, { detail: { preview: now } });
+    }
     if (!ids.length)
         return [];
-    if (!op.confirm) {
-        // превью: то же замыкание, что у триггера удаления (ref_action), база не меняется
-        const res = await query(w, `select ${rowJson('e')} as row, p.action, p.depth from ${S}.delete_preview($1::uuid[]) p `
-            + `join ${S}.entity e on e.id = p.id order by p.depth nulls last, p.action, e.id`, [ids]);
-        return res.map((r) => {
-            const row = toRow(r.row);
-            row.$action = r.action;
-            if (r.depth !== null)
-                row.$depth = r.depth;
-            return row;
-        });
-    }
     // результат — надгробия этой транзакции после метки: delete … returning не видит каскад триггера
     const [{ mark }] = await query(w, `select coalesce(max(seq), 0)::text as mark from ${S}.log where tx = pg_current_xact_id()`, []);
     const gone = await query(w, `delete from ${S}.entity e where e.id = any ($1::uuid[]) returning ${rowJson('e')} as row`, [ids]);
@@ -548,25 +735,155 @@ async function deleteOp(w, steps, opStep) {
     }
     return out;
 }
-/** Удалённые объекты шага (restore): живые цели без удалённых — not_deleted. */
-async function deletedTargets(w, steps, opStep, verb) {
-    const rows = await readRows(w, steps.map(bare), { ...(opStep.opMods ?? {}), withDeleted: true });
+/** Причины отказа для строк шага restore (живых или надгробий не той версии): одним запросом к журналу. */
+async function refusals(w, rows, want) {
+    if (!rows.length)
+        return [];
+    const S = quoteId(w.schema);
+    const exp = rows.map((r) => want?.get(r.id.toLowerCase()) ?? null);
+    const log = await query(w, `select x.id::text as id, `
+        + `(select l.op from ${S}.log l where l.id = x.id and l.rev > x.exp order by l.rev limit 1) as after, `
+        + `(select l.op from ${S}.log l where l.id = x.id and l.rev > (select max(t.rev) from ${S}.log t where t.id = x.id and t.op = 'delete') `
+        + `order by l.rev limit 1) as after_last from unnest($1::uuid[], $2::int[]) as x(id, exp)`, [rows.map((r) => r.id), exp]);
+    const by = new Map(log.map((r) => [r.id.toLowerCase(), r]));
+    return rows.map((r, i) => {
+        const l = by.get(r.id.toLowerCase());
+        const live = r.$deleted !== true;
+        const last = l?.after_last ?? null;
+        const why = live && last === 'restore' ? 'restored' : live && last === 'create' ? 'reissued' : 'changed';
+        return { id: r.id, rev: r.rev, expected: exp[i], after: l?.after ?? null, deleted: !live, live, why };
+    });
+}
+/**
+ * Отказ restore по смыслу (второй раунд 2.1, A2): есть `changed` — restore_stale (conflict), иначе есть `reissued` —
+ * restore_id_taken, иначе restore_already (оба — not_deleted). detail.ids — цели этого ключа; с expect (и всегда у
+ * restore_stale) detail.stale — все цели, которые не восстановить, с причиной.
+ */
+function restoreRefusal(verb, list, withExpect, cause) {
+    const of = (why) => list.filter((x) => x.why === why).map((x) => x.id);
+    const extra = (detail) => ({ detail, ...(cause !== undefined ? { cause } : {}) });
+    const stale = withExpect ? { stale: list } : {};
+    const changed = of('changed');
+    if (changed.length)
+        return lerr('write.restore_stale', { ids: changed.join(', ') }, extra({ ids: changed, stale: list }));
+    const taken = of('reissued');
+    if (taken.length)
+        return lerr('write.restore_id_taken', { verb, ids: taken.join(', ') }, extra({ ids: taken, ...stale }));
+    const done = of('restored');
+    return lerr('write.restore_already', { verb, ids: done.join(', ') }, extra({ ids: done, ...stale }));
+}
+/** Строка ответа restore({ expect, partial: true }) для цели, которую не восстановить (второй раунд 2.1, A3). */
+const skipRow = (r, why) => ({ ...r, $action: 'skip', $why: why });
+const byIdOrder = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+ * Удалённые объекты шага (restore). Шаг цели читается с надгробиями; у шагов до него withDeleted() — свой (план 2.1, A9).
+ * Без expect: восстанавливаются удалённые цели; если удалённых нет, а живые есть — отказ по смыслу (restoreRefusal: уже
+ * восстановлен, id занят новым объектом) или not_deleted (не удалялся). С expect — только цели из expect, и последняя
+ * версия каждой — то же надгробие; иначе отказ по смыслу и ничего не восстановлено, а с partial — строка-пропуск.
+ */
+async function deletedTargets(w, steps, opStep, verb, expect, partial) {
+    const path = steps.map(bare);
+    path[path.length - 1] = { ...path[path.length - 1], withDeleted: true };
+    const rows = await readRows(w, path, opStep.opMods ?? {});
+    // без явного порядка — по id: restore пишет журнал по очереди целей
+    const ordered = (xs) => (opStep.opMods?.order ? xs : [...xs].sort(byIdOrder));
+    if (expect !== undefined) {
+        const want = new Map(expect.map((x) => [x.id.toLowerCase(), x.rev]));
+        const mine = rows.filter((r) => want.has(r.id.toLowerCase()));
+        const good = (r) => r.$deleted === true && r.rev === want.get(r.id.toLowerCase());
+        const bad = await refusals(w, mine.filter((r) => !good(r)), want);
+        if (bad.length && !partial)
+            throw restoreRefusal(verb, bad, true);
+        const why = new Map(bad.map((x) => [x.id, x.why]));
+        const all = ordered(mine);
+        return { dead: all.filter(good), skip: all.filter((r) => !good(r)).map((r) => skipRow(r, why.get(r.id) ?? 'changed')), order: all.map((r) => r.id) };
+    }
     const dead = rows.filter((r) => r.$deleted);
-    if (!dead.length && rows.length)
+    if (!dead.length && rows.length) {
+        const live = await refusals(w, rows, null);
+        if (live.some((x) => x.why !== 'changed'))
+            throw restoreRefusal(verb, live.filter((x) => x.why !== 'changed'), false);
         throw lerr('write.not_deleted', { verb }, { detail: { ids: rows.map((r) => r.id) } });
-    // без явного порядка — по id: restore пишет журнал по очереди целей
-    return opStep.opMods?.order ? dead : [...dead].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    const all = ordered(dead);
+    return { dead: all, skip: [], order: all.map((r) => r.id) };
+}
+/** Отказ функции базы restore() по смыслу (уже восстановлен, id занят, версия не та) — причина и подробности; иначе null. */
+function dbRefusal(e) {
+    const le = fromDbError(e);
+    if (!(le instanceof LetopisError))
+        return null;
+    const why = le.key === 'sql-time.restore_already' ? 'restored' : le.key === 'sql-time.restore_id_taken' ? 'reissued'
+        : le.key === 'sql-time.restore_stale' ? 'changed' : undefined;
+    if (!why)
+        return null;
+    const d = (le.detail ?? {});
+    const p = le.params ?? {};
+    return {
+        id: String(d.id ?? p.id ?? ''), rev: Number(d.rev ?? p.rev ?? 0), expected: d.expected ?? (typeof p.expected === 'number' ? p.expected : null),
+        after: d.after ?? null, deleted: d.deleted ?? false, live: d.live ?? why !== 'changed', why,
+    };
 }
-/** Восстановление (этап 6, п. 2): последний снимок новой версией; база перепроверяет его по текущему описанию. */
+/**
+ * Восстановление (этап 6, п. 2): последний снимок новой версией; база перепроверяет его по текущему описанию. С expect
+ * база ещё раз сверяет номер последней версии под блокировкой записи журнала (restore(id, rev), план 2.1, A1): гонку
+ * между чтением и восстановлением ловит она, и её отказ — по смыслу, как у проверки до записи (второй раунд 2.1, A2).
+ * partial (A3): цели, которые не восстановить, — строки-пропуски { …строка, $action: 'skip', $why }, остальные
+ * восстанавливаются; каждая цель — под своей точкой сохранения, проигранная гонка тоже становится пропуском.
+ */
 async function restoreOp(w, steps, opStep) {
     const S = quoteId(w.schema);
-    const dead = await deletedTargets(w, steps, opStep, 'restore');
+    const { expect, partial } = opStep.op;
+    const { dead, skip, order } = await deletedTargets(w, steps, opStep, 'restore', expect, partial);
     if (!dead.length)
-        return [];
-    const ids = dead.map((r) => r.id);
-    await query(w, `select ${S}.restore(x) from unnest($1::uuid[]) with ordinality as u(x, i) order by u.i`, [ids]);
-    const res = await query(w, `select ${rowJson('e')} as row from ${S}.entity e where e.id = any ($1::uuid[])`, [ids]);
-    return inTargetOrder(ids, res.map((r) => toRow(r.row)));
+        return inTargetOrder(order, skip);
+    let ids = dead.map((r) => r.id);
+    if (expect === undefined) {
+        // прежний вызов restore(id): работает и со схемой прежней ревизии
+        try {
+            await query(w, `select ${S}.restore(x) from unnest($1::uuid[]) with ordinality as u(x, i) order by u.i`, [ids]);
+        }
+        catch (e) {
+            const r = dbRefusal(e);
+            if (r && r.why !== 'changed')
+                throw restoreRefusal('restore', [r], false, e);
+            throw e;
+        }
+    }
+    else if (!partial) {
+        try {
+            await query(w, `select ${S}.restore(u.x, u.r) from unnest($1::uuid[], $2::int[]) with ordinality as u(x, r, i) order by u.i`, [ids, dead.map((r) => r.rev)]);
+        }
+        catch (e) {
+            const r = dbRefusal(e);
+            if (r)
+                throw restoreRefusal('restore', [r], true, e);
+            throw e;
+        }
+    }
+    else {
+        const lost = new Set();
+        for (const r of dead) {
+            await w.q.unsafe('savepoint letopis_restore');
+            try {
+                await query(w, `select ${S}.restore($1::uuid, $2::int)`, [r.id, r.rev]);
+                await w.q.unsafe('release savepoint letopis_restore');
+            }
+            catch (e) {
+                await w.q.unsafe('rollback to savepoint letopis_restore');
+                const why = dbRefusal(e)?.why;
+                if (!why)
+                    throw e;
+                lost.add(r.id);
+                skip.push(skipRow(r, why));
+            }
+        }
+        ids = ids.filter((id) => !lost.has(id));
+    }
+    const res = ids.length
+        ? await query(w, `select ${rowJson('e')} as row from ${S}.entity e where e.id = any ($1::uuid[])`, [ids])
+        : [];
+    return inTargetOrder(order, [...res.map((r) => toRow(r.row)), ...skip]);
 }
 async function opCall(w, steps, opStep) {
     await useReason(w, reasonFor(w, opStep));
@@ -632,10 +949,11 @@ export async function execPlan(w, steps, mods, mode, agg) {
         else {
             last = await opCall(w, [fromRows(prevOp, start.map((r) => r.id)), ...seg.steps], opStep);
         }
-        // после удаления продолжение — от удалённых строк класса цели (замыкание каскада шире)
+        // после удаления продолжение — от удалённых строк класса цели (замыкание каскада шире); после restore — от
+        // восстановленных, без строк-пропусков partial
         start = kind === 'delete' && opStep.op.confirm
             ? last.filter((r) => stepClasses(w.reg, opStep).includes(r.class))
-            : last;
+            : kind === 'restore' ? last.filter((r) => r.$action !== 'skip') : last;
         prevOp = opStep;
     }
     // причина глагола не переходит на следующие операторы транзакции

package/llms.txt

@@ -1,30 +1,50 @@
 # letopis
 
-> Хранилище версионированных объектов для Node.js на PostgreSQL 18. Каждое изменение — версия в журнале (история, чтение на момент, подписка по курсору). Целостность, изоляцию арендаторов и права доступа проверяет сама база (триггеры и политики RLS), поэтому они действуют и для сырого SQL. Данные читают и пишут цепочками вида `db.Shop(shop).Product().rows()`.
+> ИИ-агенту: код на letopis пишите по [AGENT-CHEATSHEET.md](AGENT-CHEATSHEET.md) — памятка лежит в пакете рядом с этим файлом (`node_modules/letopis/AGENT-CHEATSHEET.md`); прочитайте её целиком: «Правила для любой задачи», рабочий цикл и «Грабли».
+>
+> Хранилище версионированных объектов для Node.js на PostgreSQL 18, версия 3.0. Каждое изменение — версия в журнале (история, чтение на момент, подписка по курсору). Целостность, изоляцию арендаторов и права доступа проверяет сама база (триггеры и политики RLS), поэтому они действуют и для сырого SQL. Данные читают и пишут цепочками вида `db.Team(g).Item().rows()`.
+
+Безопасность по умолчанию (одна строка — одно правило):
+
+- Удаление — только по превью: `delete()` → показать → `delete({ confirm: true, expect: превью })`; `delete({ confirm: true })` без `expect` — `invalid_query` (`write.confirm_without_expect`).
+- Восстановление — только по надгробиям: `restore({ expect: ответ delete() })`; `restore()` без `expect`, и по явному id тоже, — `invalid_query` (`write.restore_without_expect`).
+- Массовое и без сверки — только явно и только в осознанных скриптах: `{ all: true }` у `update`, `delete({ confirm: true, all: true })`, `restore({ all: true })`.
+- Арендатор — только из серверной сессии (`svc.auth.session(token)`), никогда из параметра клиента.
+- Права по умолчанию запрещают; подключение в обход RLS — `bypass_rls`, пока нет `allowBypassRls: true`.
+- `createTenant(admin, …)` — `admin` только пул `postgres()`, иначе `invalid_query` (`api.create_tenant_admin`).
+- Журнал событий маскирует значения полей с паролями, токенами, ключами, секретами и кредами (и полей из `redact`), учётные данные в строке подключения и пароль в тексте SQL; значения параметров SQL, тексты ошибок PostgreSQL и поле `data` строк в подробностях ошибок не пишет. Значения фильтров чтения в `chain` пишутся как есть — персональные поля добавьте в `redact`.
 
 Главное для кода на letopis:
 
-- Пакет ESM, Node 22+, PostgreSQL 18+ с pgcrypto, кодировка базы UTF8. Зависимость времени выполнения — `postgres`. Zod 4 — необязательная peer-зависимость, нужна только `letopis/model`; `@modelcontextprotocol/server` — только `letopis/mcp`.
-- Схему ставит `up({ dsn, schema })` от администраторской роли; имя схемы — `v2.<имя>`; `up({ upgrade: true })` обновляет схему отставшей ревизии (миграции и повторный накат), `up({ schema, fresh: true })` пересоздаёт схему — данные теряются. Приложение подключается ролью LOGIN — членом `letopis_app`: `connect({ dsn, schema: 'v2.<имя>', token | apiKey })`. Роль в обход RLS отклоняется (`bypass_rls`), если не передать `allowBypassRls: true`.
-- Классы — хабы (объекты) и связи (отношения с концами). Их описывают `hub()` и `link()` из `letopis/model` и пишут в базу `syncModels()` или `letopis sync`. У класса с ключом id детерминированный, UUID v5 (`db.idOf`); уникальность — по ключу.
-- Глаголы возвращают цепочку; терминал (`rows`, `first`, `ids`, `count`, …) исполняет весь план одной транзакцией. `create` только создаёт (занятый ключ — `exists`), `update` сливает и никогда не создаёт, `upsert` заменяет объект целиком (только у классов с ключом), `delete()` — превью, `delete({ confirm: true })` удаляет.
-- Строгий режим. `connect({ models })` или `connect<Models>()` с файлом `letopis types` дают строгие типы: шаг — только класс или алиас моделей и системных классов, переходы — по концам, слоты — роли класса, поля фильтров, `or()` и агрегатов — поля класса; имя, известное только во время выполнения, — `loose(db)[имя]()`. Во время выполнения: `update()` и `delete({ confirm: true })` без фильтра, id, `tags()`, `owner()` и `limit()` ни у одного шага — `invalid_query` (все строки — `{ all: true }`); неизвестное поле фильтра, `sort()` или агрегата — `invalid_query` с похожими именами (сверяется первый ключ пути), неизвестный класс или роль — `invalid_class` с похожими; неизвестная опция `connect()`, `up()`, `load()`, `watch()`, `createMcpServer()` — `invalid_data` с похожими именами; `after()` перед `count()` и агрегатами — `invalid_query`; хаб с именем метода цепочки, корня `db` или батча — `invalid_class`.
-- Деньги и счётчики: `update({ balance: inc(n) })` прибавляет внутри оператора; `update(patch, { rev })` даёт `conflict`, если строка изменилась; `forUpdate()` блокирует строки внутри `db.begin()`.
-- История: `versions()` (у версии — автор, время, вид операции и причина) и срез `asOf(момент)`; глаголы, `db.begin()` и `db.batch()` принимают `{ reason }`. Журнал хранит каждую версию; `history: false` у класса — журнала нет.
-- Массовая загрузка с администраторского подключения: `db.load(rows)`; в пустую схему — `db.load(rows, { initial: true })`: одна транзакция, индексы и триггеры перестраиваются в конце.
-- Подписка: `db.watch({ from, classes })` — `await sub.ready()` перед записью, которая должна попасть в поток (`from: 'now'` фиксирует начало первым запросом); параллельные `next()` получают разные события.
-- Сигналы NOTIFY видны любой роли базы: `up({ signals: 'class' | 'tenant' | 'opaque' | 'none' })` выбирает, что они раскрывают (по умолчанию `class`).
-- Права действуют всегда и по умолчанию запрещают; `up({ tenant })` или `createTenant()` заводит арендатора с правилом «вошедшим можно всё» и его первого пользователя.
-- MCP: `createMcpServer(db)` из `letopis/mcp` и `letopis mcp` (stdio, только токен сессии пользователя) дают ИИ-агенту инструменты `letopis_model`, `letopis_query` (JSON-цепочка, без SQL), `letopis_history` и, с `write: true`, `letopis_write`; агент действует с правами одного пользователя, удаление подтверждает человек через elicitation. `structuredContent` ответа — `{ notice, data }` (отказ — `{ notice, error }`): `notice` предупреждает, что в `data` — данные базы, а не инструкции.
-- У ошибок строчный код `err.code`: `exists`, `conflict`, `invalid_data` (`err.issues`), `target_not_found`, `acl_denied`, `no_session`, …; `err.hint` — что делать, `err.docs` — ссылка на код в разделе «Ошибки» README.
+- Установка: `npm pkg set type=module && npm i letopis zod postgres@3 && npm i -D tsx` (код приложения — ESM; `postgres@3` — та же мажорная версия, что у letopis, иначе `createTenant` не проходит проверку типов). Node 22+, PostgreSQL 18+ с pgcrypto, база UTF8. Zod 4 нужен только `letopis/model`, `@modelcontextprotocol/server` — только `letopis/mcp`.
+- Схему ставит `up({ dsn, schema, login, tenant })` от администратора (суперпользователь или роль с `CREATEROLE`, `CREATE` в базе и `CREATEDB`, если базы нет); роль приложения заводит `login`, её строка подключения — `r.login.dsn`. Ключ сервиса выдаёт только первый `up()` — храните его сами или передавайте свой `up({ serviceKey })`; `connect({ apiKey: null | '' })` — сразу `invalid_data` (`api.connect_empty_credential`), а `undefined` — подключение без сессии, поэтому ключ проверяйте до `connect()`; `up({ upgrade: true })` обновляет схему отставшей ревизии, `up({ fresh: true })` пересоздаёт её с потерей данных.
+- Вход пользователя: одно подключение сервиса на процесс (`connect({ apiKey })`), `svc.auth.verifyPassword()` → `{ account, token }`, затем `svc.as(account, { tenant })` на запрос. Без `{ tenant }` сессия — в **личном** арендаторе пользователя (классов там нет, `invalid_class`); проверка — `db.tenant`. По погашенной сессии чтение отдаёт пустые ответы, запись — `no_session`, поэтому `svc.auth.session(token)` — в начале каждого запроса.
+- Классы — хабы (объекты) и связи (отношения с концами): `hub()` и `link()` из `letopis/model`, в базу — `syncModels()` или `letopis sync` (в арендатора сессии). Имя роли конца одно на арендатора; роли `Group`, `Object`, `User`, `Tenant` заняты системными классами `rule` и `member` — конец с таким именем на другой класс — `invalid_class` (`model.end_role_system`).
+- Уникальность и инварианты держит ключ, а не проверка в коде: у класса с ключом id — UUID v5 (`db.idOf`), второй такой `create()` — `exists`, и под гонкой. «Одна открытая запись на объект» — связь с ключом по концу (`key: ['Obj']`); `restore()` бизнес-правил не проверяет, поэтому и при возврате инвариант держит только ключ.
+- Глаголы возвращают цепочку; терминал (`rows`, `first`, `ids`, `count`, …) исполняет весь план одной транзакцией. `create` только создаёт, `update` сливает патч и никогда не создаёт (`undefined` в патче — поле не меняется), `upsert` заменяет данные целиком (поле с `undefined` пропадает; только у классов с ключом).
+- Удаление ровно показанного атомарно: превью сверяется под блокировкой каскада, расхождение — `conflict` (`write.preview_changed`) с новым превью в `err.detail.preview`. Целей нет: непустой `expect` — `conflict` с `err.detail.preview: []` («уже удалено или не найдено»), `expect: []` — пустой ответ.
+- Возврат — по ответу `delete()` (или надгробиям `withDeleted()` по id): `restore({ expect })` — всё или отказ по смыслу (`write.restore_already`, `write.restore_id_taken` — `not_deleted`; `write.restore_stale` — `conflict`); `restore({ expect, partial: true })` — что можно, пропуски — строки `$action: 'skip'` с `$why`. Цель конца — первой, каскад — следующим шагом, оба — в одной `db.begin()` с `commit()`/`rollback()`.
+- Гонка за прочитанное — `forUpdate()` в `db.begin()` (только с `rows`, `first`, `ids`), `update(patch, { rev })` (`conflict`) или ключ; счётчик — `update({ n: inc(k) })`. Фильтр `update()` по данным, концам, `tags()`, `owner()` перепроверяется под блокировкой строки: выведенную параллельной транзакцией из-под фильтра строку он не правит (из двух одновременных правок со `status: 'new'` проходит одна); фильтр только по id — пройдут обе. Форма транзакции — `const tr = await db.begin(); try { …; await tr.commit() } catch (e) { await tr.rollback(); throw e }`; `db.begin(fn)` — `invalid_query`.
+- Строгий режим: `connect({ models })` или `connect<Models>()` дают строгие типы; неизвестное поле, класс или опция — отказ с похожими именами; `update()` без фильтра — `invalid_query` (все строки — `{ all: true }`); id не uuid — `invalid_query` до запроса; фильтр `undefined` — шаг без фильтра и предупреждение.
+- Концы связи — не поля данных: из пути или слотом `.Роль.set(id)`; имя конца в данных — `invalid_data` (`write.link_in_data`).
+- Модификаторы выборки (`sort`, `limit`, `offset`, `after`, `forUpdate`) — последнему шагу; `withDeleted()` — своему шагу. `versions()` — терминал; по пути — только живые, с удалёнными — `withDeleted()` на шаге или явный id.
+- Ответы и ошибки: строка — `{ id, class, rev, links, data, … }`, превью — с `$action`, надгробие — `$deleted: true`; ошибка — `LetopisError` с `err.code`, `err.key`, `err.detail`, `err.hint`, у данных — `ValidationError` с `err.issues: [{ path, keyword, message }]`. Штатные отказы (`exists`, `conflict`, `not_deleted`, `target_not_found`, `tenant_denied`, `acl_denied`, `no_session`, …) — ответ человеку своими фразами по `err.key`/`err.code`; ошибки кода — 500.
+- Логирование: `connect({ log, logLevel, redact })` и `up({ … })` — функция или объект-логгер (`console`, pino), порог `debug|info|warn|error|off` (по умолчанию `info`); без кода — `LETOPIS_LOG=info` (JSON-строки в stderr), CLI — `--log[=уровень]`. События `delete` и `restore` — что удалено и что не вернулось; внутри `db.begin()` событие значит «выполнено в транзакции», фиксацию доказывает `tx.commit` с тем же `tx`. Штатные отказы — событие `error` уровня `warn`, ошибки кода — уровня `error`.
+- Обслуживание — `maintain()` (администраторское подключение, системный администратор или право `letopis.maintain`, иначе `acl_denied`); загрузка — `db.load(rows)` с администраторского подключения; подписка — `db.watch({ from, classes })` и `await sub.ready()` перед записью.
+- MCP: `createMcpServer(await svc.as(пользователь, { tenant }))` из `letopis/mcp` и `letopis mcp` дают ИИ-агенту `letopis_model`, `letopis_query`, `letopis_history` и, с `write: true`, `letopis_write`; удаление подтверждает человек, удаляется ровно показанное превью.
+- Лицензия — PolyForm Noncommercial 1.0.0 (SPDX `PolyForm-Noncommercial-1.0.0`): исходный код доступен, некоммерческое использование бесплатно, коммерческое — только по отдельной лицензии владельца (запрос — issue на https://github.com/alepri51/letopis/issues).
 
 ## Документы
 
-- [Шпаргалка для агента](AGENT-CHEATSHEET.md): одна страница для ИИ-агента, который пишет код на letopis, — рабочий цикл и грабли
+- [Памятка для агента](AGENT-CHEATSHEET.md): общие правила для любой задачи на letopis, рабочий цикл одной программой и грабли
 - [Руководство](README.md): руководство по задачам, справочник API, ограничения
-- [Ошибки](README.md#15-ошибки): все коды — что значит и что делать
+- [Безопасность по умолчанию](README.md#безопасность-по-умолчанию): что отклоняется без сверки и как это сделать осознанно
+- [Логирование](README.md#логирование): опции, уровни, `LETOPIS_LOG`, формат события, маскировка, список событий
+- [Ошибки](README.md#15-ошибки): все коды и ключи — что значит, что делать и что сказать человеку
+- Машинный каталог API и ошибок — `api-contract.json` в пакете (`node_modules/letopis/api-contract.json`)
 
 ## Дополнительно
 
-- [Изменения по версиям](CHANGELOG.md): решения по версиям, несовместимые изменения
+- [Изменения по версиям](CHANGELOG.md): что изменилось при переходе на 3.0 и чем заменить снятое
+- [Лицензия](LICENSE) и [коммерческое использование](LICENSE-COMMERCIAL.md): что можно без разрешения и как получить коммерческую лицензию
 - Модель конкретной установки для агента — инструмент MCP `letopis_model`: классы, ключи, поля, концы и рабочие цепочки этой схемы