letopis 1.4.2 → 2.0.0

package/sql/95-seed.system.sql

@@ -21,8 +21,6 @@ begin
   if p_class = 'Class' then
     select c.data, c.validator into d, vld from @SCHEMA@.class_prepare(d, p_tenant) c;
   end if;
-  -- журнал раньше строки: агрегатные поля новой цели триггер после вставки досчитывает в ту же версию — и в entity,
-  -- и в уже записанную версию журнала (план 1.1, §2.4)
   insert into @SCHEMA@.log (id, rev, class, tenant, owner, links, data, tags, at, author, op)
   values (p_id, 1, p_class, p_tenant, p_tenant, coalesce(p_links, '{}'), d, '{}', now_ts, '@SYSTEM@', 'create');
   insert into @SCHEMA@.entity (id, rev, class, tenant, owner, links, data, at, created_at, author, op, validator)
@@ -30,10 +28,6 @@ begin
   if p_class in ('rule', 'Resource', 'member', 'Account', 'Class') then
     perform @SCHEMA@.acl_bump();
   end if;
-  -- новая цель агрегатов: метки её источников — заново
-  if p_class = 'Class' and d->'resolved' ? 'aggregate' then
-    perform @SCHEMA@.agg_mark(p_tenant, @SCHEMA@.agg_of(d->'resolved'));
-  end if;
   return p_id;
 end $$;
 alter function @SCHEMA@.sys_create(uuid, text, uuid, jsonb, jsonb) owner to @OWNER@;
@@ -58,10 +52,10 @@ alter function @SCHEMA@.sys_resource(uuid, text, text, jsonb) owner to @OWNER@;
 alter function @SCHEMA@.sys_rule(uuid, uuid, uuid, text, int, jsonb) owner to @OWNER@;
 revoke all on function @SCHEMA@.sys_resource(uuid, text, text, jsonb), @SCHEMA@.sys_rule(uuid, uuid, uuid, text, int, jsonb) from public;
 
--- Системный сид целиком (установка и reset({ all }), этап 6): ключ подписи и счётчик прав, System,
+-- Системный сид целиком (установка, этап 6): ключ подписи и счётчик прав, System,
 -- системные классы, общие группы и системные права (этап 5, п. 8). Роль admin — роль членства в
 -- System: системные администраторы работают в арендаторе System. Права auth.* — сервису
--- (имперсонация, выпуск сессий, креды), letopis.* (verify, reset, maintain) — только системному
+-- (имперсонация, выпуск сессий, креды), letopis.* (maintain) — только системному
 -- администратору. Повторный вызов ничего не меняет.
 create or replace function @SCHEMA@.seed_system() returns void
 language plpgsql volatile
@@ -78,16 +72,15 @@ declare
   o_signals uuid;
   op text;
 begin
-  -- аккаунт System — раньше строки ключа: служебные строки secret (KEY, LOCK, PROJECTOR) принадлежат ему, а внешний
+  -- аккаунт System — раньше строки ключа: служебные строки secret (KEY, LOCK) принадлежат ему, а внешний
   -- ключ secret.account (ревизия 7) требует строку аккаунта в entity. Счётчик прав sys_create повышает, только когда
-  -- строка ключа уже есть, — на свежей установке и после reset({ all }) ей неоткуда взяться, и начальный v — 0
+  -- строка ключа уже есть, — на свежей установке ей неоткуда взяться, и начальный v — 0
   perform @SCHEMA@.sys_create('@SYSTEM@'::uuid, 'Account', '@SYSTEM@'::uuid, '{}',
     '{"name": "System", "categories": ["System"], "enabled": true}');
 
   -- Ключ подписи пропуска прав и счётчик изменений прав (50-acl.sql: acl_token, acl_bump); от ключа же
   -- выводится ключ сигналов. Режим сигналов (up({ signals })) хранится в meta этой строки: установщик
-  -- читает его перед накатом, поэтому повторный up() без опции режим не меняет, а reset({ all }) кладёт
-  -- его заново из константы установки.
+  -- читает его перед накатом, поэтому повторный up() без опции режим не меняет.
   insert into @SCHEMA@.secret as k (id, account, kind, material, meta)
   values ('@SYSTEM@'::uuid, '@SYSTEM@'::uuid, 'KEY', @PGCRYPTO@.gen_random_bytes(32), '{"v": 0, "signals": "@SIGNALS@"}')
   on conflict (id) do update set meta = k.meta || '{"signals": "@SIGNALS@"}'
@@ -148,8 +141,8 @@ begin
   foreach op in array array['READ', 'WRITE', 'DELETE'] loop
     perform @SCHEMA@.sys_rule(sys, g_admin, @SCHEMA@.sys_resource(sys, 'all:' || op, op, null), 'allow', 100);
   end loop;
-  -- строки-замки (60-write.sql: lock_row) семейств всех классов, в том числе классов арендаторов, заведённых до 1.2, и
-  -- обслуживания — заранее: первое обращение под нагрузкой их не вставляет
+  -- строки-замки (60-write.sql: lock_row) семейств всех классов — системных, из сидов (sys_create их не заводит) и
+  -- арендаторов — и обслуживания — заранее: первое обращение под нагрузкой их не вставляет
   perform @SCHEMA@.family_rows(c.tenant, c.data) from @SCHEMA@.entity c where c.class = 'Class';
   perform @SCHEMA@.lock_row('@SCHEMA_NAME@:maintain');
 end $$;

package/sql/99-revision.sql

@@ -1,4 +1,5 @@
 -- letopis 1.0 — штамп ревизии движка (план, §2.2, этап 1, п. 11): последний оператор наката.
 -- Номер совпадает с DDL_REVISION в lib/src/types.ts (проверяет check-docs). С 1.4 в штампе ещё версия пакета и хэш
 -- файлов ядра (engine, sql): connect() предупреждает, если функции схемы ставила другая версия движка той же ревизии.
-comment on schema @SCHEMA@ is 'letopis ddl_revision=7 engine=@ENGINE_VERSION@ sql=@ENGINE_SQL@';
+-- Ревизия 8 — первая у 2.0 (план 2.0, редакция 2): схему ниже неё (letopis 1.x) up() и connect() отклоняют.
+comment on schema @SCHEMA@ is 'letopis ddl_revision=8 engine=@ENGINE_VERSION@ sql=@ENGINE_SQL@';

package/sql/README.md

@@ -1,7 +1,7 @@
-# SQL ядра letopis 1.0
+# SQL ядра letopis 2.0
 
 Файлы накатываются установщиком (`lib/src/up.ts`, функция `install`) по возрастанию номера; каждый можно применить повторно.
-Спецификация — `reports/PLAN-LETOPIS-1.0.md`, §2 и этап 1.
+Спецификация — `reports/PLAN-LETOPIS-1.0.md` (§2 и этап 1) и `reports/PLAN-LETOPIS-2.0.md`.
 
 ## Подстановки при накате
 
@@ -10,27 +10,39 @@
 | `@SCHEMA@` | имя схемы в кавычках, например `"v2.salon"` |
 | `@SCHEMA_NAME@` | имя схемы как строковый литерал без кавычек идентификатора, например `v2.salon` |
 | `@OWNER@` | роль-владелец, по умолчанию `letopis_owner` |
+| `@OWNER_NAME@` | имя роли-владельца строковым литералом без кавычек идентификатора, например `letopis_owner` (условия триггеров, `pg_has_role`) |
 | `@APP@` | роль приложения, по умолчанию `letopis_app` |
 | `@PGCRYPTO@` | схема, где установлен pgcrypto (`pg_extension.extnamespace`) |
-| `@SYSTEM@` | id системного арендатора System: `2eba6d0a-1edd-4bb6-a85a-a703dab49035` (как в 0.21) |
-| `@ALLOW_RESET@` | `true` или `false` — константа установки |
-| `@HISTORY_DEFAULT@` | политика хранения по умолчанию `up({ history })` литералом JSON или `'null'` — константа установки |
-| `@RESERVED_NAMES@` | методы цепочки — `RESERVED_CLASS_NAMES` из `lib/src/types.ts`, литералами через запятую |
-| `@SIGNALS@` | режим сигналов `class`, `tenant`, `opaque` или `none` (план 1.1, §2.2): опция `up({ signals })`, иначе сохранённый в `meta.signals` строки ключа `secret`, иначе `class` — константа установки |
+| `@SYSTEM@` | id системного арендатора System: `2eba6d0a-1edd-4bb6-a85a-a703dab49035` |
+| `@RESERVED_NAMES@` | методы цепочки, корня `db` и батча — `RESERVED_CLASS_NAMES` из `lib/src/types.ts`, литералами через запятую |
+| `@MESSAGES@` | каталог сообщений базы — разделы `sql-*` каталога `lib/src/messages` (план 2.0, этап 3, п. 3): литерал JSON «ключ → `{ name, ru }`» для `message_catalog()` в `15-errors.sql` |
+| `@SIGNALS@` | режим сигналов `class`, `tenant`, `opaque` или `none`: опция `up({ signals })`, иначе сохранённый в `meta.signals` строки ключа `secret`, иначе `class` — константа установки |
 | `@ENGINE_VERSION@` | версия пакета (`lib/package.json`) — штамп движка в комментарии схемы (`99-revision.sql`) |
-| `@ENGINE_SQL@` | 16 знаков sha256 исходного текста файлов `NN-*.sql` до подстановок (переводы строк — LF): `connect()` сверяет его с файлами своего пакета |
+| `@ENGINE_SQL@` | 16 знаков sha256 исходного текста файлов `NN-*.sql` до подстановок (переводы строк — LF) и разделов `sql-*` каталога сообщений: `connect()` сверяет его с файлами своего пакета |
 
-## Колонки снимка версии
+## Колонки версии
 
-Одинаковы в `entity` и `log` (§2.2): `id`, `rev`, `class`, `tenant`, `owner`, `links`, `data`, `tags`, `at` (время версии),
-`author`, `agent`, `op`, `reason`, `moved`. Хэш — генерируемая колонка: `sha256(prev_hash || snapshot(...))`, где
-`snapshot()` — неизменяемая функция, время входит числом микросекунд.
+Одинаковы в `entity` и `log` (§2.2): `id`, `rev`, `class`, `cv`, `tenant`, `owner`, `links`, `data`, `tags`, `at` (время
+версии), `author`, `agent`, `op`, `reason`. У `entity` ещё `ends` (генерируемая: все цели концов),
+`created_at` и `validator` (у строк `Class`), у `log` — `seq` и `tx` (курсор подписки).
 
 ## Коды ошибок
 
 Собственный класс SQLSTATE `LT`; текст — `letopis: <имя>: <сообщение>`, детали — JSON в `DETAIL`.
 Источник истины — функция `error_catalog()` в `15-errors.sql`.
 
+Тексты — по ключам каталога сообщений (план 2.0, этап 3, п. 3): `lt_fail(ключ, параметры jsonb, detail jsonb)` берёт имя
+ошибки и русский шаблон из `message_catalog()` (`{имя}` — параметр, подставляет `lt_text()`), а в `DETAIL` кладёт поля
+`detail` и ещё `key`, `params` — библиотека переносит их в `err.key` и `err.params`; текст тот же, что видит сырой SQL.
+`LetopisError.detail`: без `detail` — `{}`; с `p_detail => 'null'` в `DETAIL` — признак `nodetail`, и у ошибки `detail` нет.
+Свой SQLSTATE — `lt_raise(код, ключ, параметры, detail)`. Функции, которые исполняет приложение (`inc`, `links_patch`),
+бросают `raise` сами: текст — `lt_text(ключ, параметры)`, она и `message_catalog()` выданы приложению; `DETAIL` без своих
+полей — с `'nodetail', true`. Все места бросают ошибки по ключам: перегрузки `lt_fail(имя, текст, detail)` и
+`lt_raise(код, имя, текст, detail)` — сам механизм, вне `15-errors.sql` их не зовут (`lt_raise` с текстом — единственный
+`raise`). Внутренняя ошибка — `lt_raise('XX000', ключ, …)` с кодом `internal`; строки отказа ужесточения и нарушения данных несут `key` и `params`, а
+текст `problem` и `message` собирает `lt_text`. Литеральный текст в `raise` и в `problem` ловит `check:docs`
+(`literals`).
+
 | Код | Имя | Когда |
 |---|---|---|
 | LT001 | `no_session` | нет действующей сессии |
@@ -41,22 +53,18 @@
 | LT006 | `acl_denied` | отказ по правилам доступа |
 | LT007 | `id_mismatch` | id не равен v5 от ключа; в деталях `expected` |
 | LT008 | `id_from_db` | id класса без ключа выдаёт база |
-| LT009 | `immutable_key` | ключевое поле, id, арендатор, владелец менять нельзя |
+| LT009 | `immutable_key` | ключевое поле, класс, id, арендатор, владелец менять нельзя |
 | LT010 | `invalid_class` | описание класса отклонено, класс не найден или абстрактный |
-| LT011 | `use_reclass` | класс с ключом меняется функцией `reclass()` |
-| LT012 | `reclass_denied` | роли ссылающихся строк не принимают новый класс; в деталях `rows`, `others` |
 | LT013 | `tightening_conflict` | ужесточению мешают строки; в деталях `rows`, `others` |
-| LT014 | `isolation_level` | удаление и смена класса — только в `read committed` |
+| LT014 | `isolation_level` | удаление — только в `read committed` |
 | LT015 | `recreated_in_statement` | id удалён и создан заново одним оператором |
-| LT016 | `cursor_expired` | курсор подписки старше яруса `all` (этап 6) |
 | LT017 | `delete_restricted` | удалению мешают ссылающиеся строки (`onDelete: restrict`); в деталях `rows`, `others` |
-| LT018 | `not_deleted` | `restore` и `purge` — только для удалённых объектов (этап 6) |
-| LT019 | `reset_disabled` | флаг `allowReset` установки выключен: `reset` и `maintain(now)` недоступны (этап 6) |
-| LT020 | `confirm_mismatch` | подтверждение сброса не совпадает с именем схемы (этап 6) |
-| LT021 | `derived_class` | строки производного класса (`derivedBy`) пишет и удаляет только его проектор; на них не ссылаются концы (план 1.1, §2.4) |
-| LT022 | `aggregate_field` | агрегатное поле (`aggregate`) считает база: приложение и сырой SQL его не передают и не меняют (план 1.1, §2.4) |
-| LT023 | `projector_pending` | `purge` удалённого объекта, чьё надгробие ещё не прочёл проектор его класса (ревью безопасности №3, №5), или `trim_history`, чью первую оставшуюся версию он ещё не прочёл (хвост ревью №3) |
+| LT018 | `not_deleted` | `restore` — только для удалённых объектов |
 
 ## Порядок файлов
 
-`10-core` → `15-errors` → `20-context` → `30-validate` → `40-class` → `50-acl` → `60-write` → `70-read` → `75-history` → `80-auth` → `88-derived` → `90-time` → `95-seed.system` → `99-revision`. Миграции между ревизиями — `migrate/NNNN-*.sql` (номер — ревизия, к которой ведёт), их применяет `up({ upgrade: true })` до повторного наката.
+`10-core` → `15-errors` → `20-context` → `30-validate` → `40-class` → `50-acl` → `60-write` → `70-read` → `80-auth` → `90-time` → `95-seed.system` → `99-revision`. Миграции между ревизиями — `migrate/NNNN-*.sql` (номер — ревизия, к которой ведёт; правило — `migrate/README.md`), их применяет `up({ upgrade: true })` до повторного наката. У 2.0 (ревизия 8) миграций нет.
+
+Файлы описывают только нынешнюю ревизию: `drop … if exists` в них — лишь там, где без него не пройдёт повторный накат
+той же ревизии (политики RLS в `50-acl.sql`: у `create policy` нет `or replace`). Смена сигнатуры функции в пределах
+ревизии — `drop function if exists` прежней в том же файле, иначе повторный накат оставит лишнюю перегрузку.

package/sql/migrate/README.md

@@ -0,0 +1,14 @@
+# Миграции схемы letopis 2.x
+
+`up({ upgrade: true })` применяет файлы этого каталога к схеме отставшей ревизии 2.x: в транзакции наката, под
+блокировкой схемы и от роли владельца, до повторного наката файлов ядра (`lib/src/up.ts`: `install`, `migrationFiles`).
+
+- Имя — `NNNN-описание.sql`: четыре цифры — номер ревизии, к которой ведёт миграция, затем дефис и строчные латинские
+  буквы, цифры, точки и дефисы (`^\d{4}-[a-z0-9.-]+\.sql$`). Файлы с другим именем, как этот, установщик пропускает.
+- Номер миграции — новая ревизия движка: тот же номер — `DDL_REVISION` в `lib/src/types.ts` и `ddl_revision` в
+  `lib/sql/99-revision.sql` (их сверяет `npm run check:docs`).
+- Применяются миграции с номером выше ревизии схемы и не выше `DDL_REVISION`, по возрастанию номера. Подстановки — как
+  у файлов ядра (`@SCHEMA@`, `@OWNER@` и другие — таблица в `lib/sql/README.md`).
+- В миграцию идёт только то, чего не догонит повторный накат: колонка или ограничение существующей таблицы, перенос
+  данных. Функции, индексы, триггеры и политики ставят файлы ядра.
+- У 2.0 (ревизия 8) миграций нет.