letopis 3.0.0 → 3.0.1

package/dist/write.js

@@ -6,7 +6,7 @@
  *   await db.Org(org).Staff().create({ name: 'Вася', phone: '+7' }).rows()      // концы из пути: { Org }
  *   await db.Customer(c).booking({ notes: 'x' }).update({ notes: 'y' }).rows()
  *   await db.Wallet(w).update({ balance: inc(-300) }).first()                     // приращение в базе
- *   await db.Staff(s).booking().create({ … }).Customer.set(c).Item.set(svc).rows() // слоты концов
+ *   await db.Staff(s).booking().create({ … }).Customer.set(c).Item.set(svc).rows() // шаги ролей
  *
  * Библиотека пишет обычными операторами SQL — теми же, что выполнил бы человек в консоли:
  * insert, update … set data = merge(data, $patch), insert … on conflict do update, delete; всё
@@ -36,6 +36,18 @@ 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;
+const HIDDEN_ACTIONS = ['delete', 'unset', 'restrict'];
+const HIDDEN_PREFIX = 'hidden:';
+/**
+ * Действие строки-сводки предпросмотра удаления (3.0.1): `$hidden` или хвост id `hidden:<действие>`; не сводка — null.
+ * Сводку узнаёт и по одному id: expect, собранный из ответа как `{ id, rev }`, её не теряет.
+ */
+function hiddenOf(x) {
+    if (x.$action !== 'hidden' && !(typeof x.id === 'string' && x.id.startsWith(HIDDEN_PREFIX)))
+        return null;
+    const a = x.$hidden ?? (typeof x.id === 'string' ? x.id.slice(HIDDEN_PREFIX.length) : undefined);
+    return HIDDEN_ACTIONS.includes(a) ? a : null;
+}
 /**
  * Данные create() и upsert() без ключей со значением undefined — как у патча update() (splitPatch): ключ undefined JSON
  * не передаёт, а валидатор на TypeScript принимал его за поле не того типа (план 2.1, A12). Вложенные объекты — тоже;
@@ -52,10 +64,21 @@ export function dropUndefined(data) {
     }
     return out;
 }
-/** expect — список строк { id, rev } (и $action у превью удаления): иначе invalid_query до записи. */
+/**
+ * expect — список строк { id, rev } (и $action у предпросмотра удаления): иначе invalid_query до записи. Строка-сводка
+ * скрытых строк предпросмотра удаления (`$action: 'hidden'`, id `hidden:<действие>`, 3.0.1) — без rev, `$count` (если
+ * задан) — целое ≥ 1.
+ */
 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);
+    const ok = Array.isArray(expect) && expect.every((x) => {
+        if (x === null || typeof x !== 'object' || typeof x.id !== 'string')
+            return false;
+        const e = x;
+        if (verb === 'delete' && (e.$action === 'hidden' || e.id.startsWith(HIDDEN_PREFIX))) {
+            return hiddenOf(e) !== null && (e.$count === undefined || (Number.isInteger(e.$count) && e.$count >= 1));
+        }
+        return Number.isInteger(e.rev) && e.rev >= 1;
+    });
     if (!ok)
         throw lerr('write.bad_expect', { verb });
 }
@@ -666,29 +689,74 @@ async function updateOp(w, steps, opStep) {
     }
     return inTargetOrder(ids, res.map((r) => toRow(r.row)));
 }
-/** Превью удаления целей: то же замыкание, что у триггера удаления (ref_action), база не меняется. */
+/** Строка-сводка скрытых правами строк предпросмотра (3.0.1): ни класса, ни id, ни данных — только действие и число. */
+const hiddenRow = (action, count) => ({
+    id: `${HIDDEN_PREFIX}${action}`, class: '', rev: 0, tenant: '', owner: '', links: {}, data: {}, tags: [], at: '', author: '',
+    op: 'hidden', $action: 'hidden', $hidden: action, $count: count,
+});
+/**
+ * Предпросмотр удаления целей: то же замыкание, что у триггера удаления (ref_action), база не меняется. Видимые строки —
+ * как есть, скрытые правами — в конце сводками: delete_preview отдаёт их строками с id null, action
+ * 'hidden:<действие>' и числом в depth; здесь — по строке на действие delete, unset, restrict, только непустые.
+ */
 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) => {
+        + `left join ${S}.entity e on e.id = p.id where p.id is null or e.id is not null `
+        + `order by p.id is null, p.depth nulls last, p.action, e.id`, [ids]);
+    const out = [];
+    const hidden = new Map();
+    for (const r of res) {
+        if (r.action.startsWith(HIDDEN_PREFIX)) {
+            hidden.set(r.action.slice(HIDDEN_PREFIX.length), r.depth ?? 0);
+            continue;
+        }
         const row = toRow(r.row);
         row.$action = r.action;
         if (r.depth !== null)
             row.$depth = r.depth;
-        return row;
-    });
+        out.push(row);
+    }
+    for (const a of HIDDEN_ACTIONS) {
+        const n = hidden.get(a) ?? 0;
+        if (n > 0)
+            out.push(hiddenRow(a, n));
+    }
+    return out;
 }
-/** Превью совпадает с показанным: те же строки по id, с теми же rev и $action (порядок не важен). */
+/**
+ * Превью совпадает с показанным: те же видимые строки по id, с теми же rev и $action (порядок не важен), и те же
+ * сводки скрытых строк (3.0.1) по действию и числу; у сводки без $count сверяется только её наличие.
+ */
 function samePreview(now, expect) {
     if (now.length !== expect.length)
         return false;
-    const want = new Map(expect.map((x) => [x.id.toLowerCase(), x]));
+    const want = new Map();
+    for (const x of expect) {
+        const h = hiddenOf(x);
+        want.set(h ? `${HIDDEN_PREFIX}${h}` : x.id.toLowerCase(), x);
+    }
+    if (want.size !== expect.length)
+        return false;
     return now.every((r) => {
+        if (r.$action === 'hidden') {
+            const x = want.get(r.id);
+            return x !== undefined && (x.$count === undefined || x.$count === r.$count);
+        }
         const x = want.get(r.id.toLowerCase());
-        return x !== undefined && x.rev === r.rev && (x.$action === undefined || x.$action === r.$action);
+        return x !== undefined && hiddenOf(x) === null && x.rev === r.rev && (x.$action === undefined || x.$action === r.$action);
     });
 }
+/**
+ * Сверенный с expect предпросмотр, а в нём мешающие строки (restrict) — видимые или скрытые правами (3.0.1): отказ
+ * delete_restricted до удаления; detail — как у отказа триггера: видимые { id, class } и число остальных.
+ */
+function checkRestrict(now) {
+    const rows = now.filter((r) => r.$action === 'restrict').map((r) => ({ id: r.id, class: r.class }));
+    const others = now.filter((r) => r.$action === 'hidden' && r.$hidden === 'restrict').reduce((n, r) => n + (r.$count ?? 0), 0);
+    if (rows.length || others)
+        throw lerr('write.delete_restricted', { visible: rows.length, others }, { detail: { rows, others } });
+}
 async function deleteOp(w, steps, opStep) {
     const op = opStep.op;
     const S = quoteId(w.schema);
@@ -710,6 +778,7 @@ async function deleteOp(w, steps, opStep) {
         }
         if (!samePreview(now, op.expect))
             throw lerr('write.preview_changed', undefined, { detail: { preview: now } });
+        checkRestrict(now);
     }
     if (!ids.length)
         return [];

package/llms.txt

@@ -16,7 +16,7 @@
 
 Главное для кода на letopis:
 
-- Установка: `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`.
+- Установка: `npm pkg set type=module && npm i letopis@3 zod postgres@3 && npm i -D tsx` (код приложения — ESM; `@3` — мажорная линия этой документации, без версии npm поставит последний выпуск; `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`).
@@ -32,6 +32,7 @@
 - Логирование: `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`; удаление подтверждает человек, удаляется ровно показанное превью.
+- Системный администратор — член System с ролью `admin`, отдельный аккаунт: через сервис не входит (`verifyPassword`, `sessionFor`, `svc.as()` — `acl_denied`), входит ключом API и `auth.switch(System)`; `purgeAccount` стирает только собственного арендатора аккаунта — стираемые персональные данные держите в классе с `history: false` (README, «Аккаунты, арендаторы и членство», «Удалить аккаунт»).
 - Лицензия — PolyForm Noncommercial 1.0.0 (SPDX `PolyForm-Noncommercial-1.0.0`): исходный код доступен, некоммерческое использование бесплатно, коммерческое — только по отдельной лицензии владельца (запрос — issue на https://github.com/alepri51/letopis/issues).
 
 ## Документы

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Letopis (летопись): хранилище версионированных сущностей на PostgreSQL 18 — целостность, история, арендаторы и права проверяет сама база, поверх — цепочки через точку. ИИ-агенту — AGENT-CHEATSHEET.md и llms.txt в пакете; исходный код доступен (PolyForm Noncommercial 1.0.0)",
   "keywords": [
     "postgres",

package/sql/60-write.sql

@@ -1378,12 +1378,15 @@ begin
   return null;
 end $$;
 
--- Превью удаления (этап 4, п. 6): что удалит delete этих строк — те же уровни и то же правило
+-- Предпросмотр удаления (этап 4, п. 6): что удалит delete этих строк — те же уровни и то же правило
 -- ref_action(), что у триггера, но без изменений. Строки: action delete (цели — depth 0, каскад —
 -- уровень), unset (конец будет снят) и restrict (мешает удалению). Функция владельца ищет по
 -- индексу ends без RLS (§3 «Индексы под RLS»), поэтому и цели, и выдачу пропускает через
 -- row_visible() — то же условие, что у политики чтения (как find_*): невидимых строк не раскрывает
--- ни id, ни классом. О невидимых мешающих строках скажет само удаление (visible_detail: число).
+-- ни id, ни классом. Невидимые строки замыкания (3.0.1) — в конце сводкой, по строке на действие (delete,
+-- unset, restrict; только непустые): id и class — null, action — 'hidden:<действие>', depth — их число. Вид
+-- результата прежний: тело ставит create or replace повторным накатом той же ревизии, а клиент, который
+-- соединяет выдачу с entity по id, сводок не видит.
 create or replace function @SCHEMA@.delete_preview(p_ids uuid[]) returns table(id uuid, class text, action text, depth int)
 language plpgsql stable security definer
 set search_path = pg_catalog, @SCHEMA@, pg_temp
@@ -1432,10 +1435,19 @@ begin
     from (select x.id, @SCHEMA@.ref_action((@SCHEMA@.class_row(x.class, x.tenant)).data->'resolved'->'ends', x.links, all_ids) as a
           from @SCHEMA@.entity x where x.ends && all_ids and not (x.id = any (all_ids))) r);
   return query
-    select (o->>0)::uuid, e.class, o->>1, (o->>2)::int
-    from jsonb_array_elements(out_rows) o
-    join @SCHEMA@.entity e on e.id = (o->>0)::uuid
-    where @SCHEMA@.row_visible(e.tenant, e.class, e.id, e.owner, e.tags, e.data, e.links, c_tenant, c_account, c_plan);
+    with o as (
+      select (j.v->>0)::uuid as id, e.class, j.v->>1 as action, (j.v->>2)::int as depth, j.ord,
+             @SCHEMA@.row_visible(e.tenant, e.class, e.id, e.owner, e.tags, e.data, e.links, c_tenant, c_account, c_plan) as vis
+      from jsonb_array_elements(out_rows) with ordinality j(v, ord)
+      join @SCHEMA@.entity e on e.id = (j.v->>0)::uuid
+    )
+    select x.id, x.class, x.action, x.depth
+    from (select o.id, o.class, o.action, o.depth, 0 as part, o.ord as k from o where o.vis
+          union all
+          select null::uuid, null::text, 'hidden:' || o.action, count(*)::int, 1,
+                 array_position(array['delete', 'unset', 'restrict'], o.action)::bigint
+          from o where not o.vis group by o.action) x
+    order by x.part, x.k;
 end $$;
 
 create or replace trigger entity_bi before insert on @SCHEMA@.entity