letopis 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Letopis (летопись): versioned entity store on PostgreSQL 18 — integrity, history, tenants and access control enforced by the database itself, dot-notation chains on top",
   "keywords": [
     "postgres",
@@ -35,6 +35,10 @@
     "./model": {
       "types": "./dist/model.d.ts",
       "import": "./dist/model.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
     }
   },
   "engines": {
@@ -72,7 +76,8 @@
   "peerDependencies": {
     "zod": "^4",
     "@electric-sql/pglite": "^0.5.8",
-    "@electric-sql/pglite-socket": "^0.2.11"
+    "@electric-sql/pglite-socket": "^0.2.11",
+    "@modelcontextprotocol/server": "^2.4.0"
   },
   "peerDependenciesMeta": {
     "zod": {
@@ -83,13 +88,19 @@
     },
     "@electric-sql/pglite-socket": {
       "optional": true
+    },
+    "@modelcontextprotocol/server": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@electric-sql/pglite-socket": "^0.2.11",
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@modelcontextprotocol/server": "^2.4.0",
     "@types/node": "^22.20.5",
     "letopis-0": "npm:letopis@0.21.0",
+    "letopis-1": "npm:letopis@1.0.1",
     "tsx": "^4.23.15",
     "typescript": "~5.9.3",
     "zod": "4.6.5"

package/sql/10-core.sql

@@ -86,9 +86,16 @@ create table if not exists @SCHEMA@.log (
   prev_hash  bytea,
   hash       bytea generated always as (@SCHEMA@.version_hash(prev_hash,
                @SCHEMA@.snapshot(id, rev, class, tenant, owner, links, data, tags, at, author, agent, op, reason, moved))) stored,
+  -- пути изменения против предыдущей версии (план 1.1, ревизия 6): производные, в снимок и хэш не входят;
+  -- null — не посчитано (создание, загрузчик, импорт), blame досчитывает сравнением
+  changed    jsonb,
   constraint log_id_rev unique (id, rev)
 );
-create index if not exists log_class_at on @SCHEMA@.log (class, at);
+-- срез журнала по классу (asOf, withDeleted) — по арендатору (доработки после точки Б): цена запроса не растёт с
+-- журналом других арендаторов с тем же именем класса. Прежний log_class_at (class, at) снимается при накате; на
+-- большой установке новый индекс можно построить заранее — create index concurrently log_class_tenant_at …
+create index if not exists log_class_tenant_at on @SCHEMA@.log (class, tenant, at);
+drop index if exists @SCHEMA@.log_class_at;
 create index if not exists log_tx_seq on @SCHEMA@.log (tx, seq);
 -- versions({ follow: true }): переход по связи старого и нового id при reclass и rekey (этап 6)
 create index if not exists log_moved on @SCHEMA@.log (moved) where moved is not null;
@@ -125,7 +132,11 @@ revoke all on @SCHEMA@.entity, @SCHEMA@.log, @SCHEMA@.secret from public, @APP@;
 grant select, delete on @SCHEMA@.entity to @APP@;
 grant insert (id, tenant, class, links, data, tags, owner) on @SCHEMA@.entity to @APP@;
 grant update (class, links, data, tags) on @SCHEMA@.entity to @APP@;
-grant select on @SCHEMA@.log to @APP@;
+-- журнал — без колонки changed (ревью №1 точки А плана 1.1): её пути описывают разницу с предыдущей версией, а та
+-- читателю может быть не видна (условие ACL скрыло её и пропустило следующую); blame получает пути через
+-- version_paths, которая проверяет видимость обеих версий (75-history.sql)
+grant select (seq, tx, id, rev, class, cv, tenant, owner, links, data, tags, at, author, agent, op, reason, moved, prev_hash, hash)
+  on @SCHEMA@.log to @APP@;
 alter table @SCHEMA@.entity enable row level security;
 alter table @SCHEMA@.log enable row level security;
 alter table @SCHEMA@.secret enable row level security;

package/sql/15-errors.sql

@@ -25,7 +25,10 @@ as $$
     ('LT017', 'delete_restricted',      'letopis: delete_restricted: удалению мешают ссылающиеся строки'),
     ('LT018', 'not_deleted',            'letopis: not_deleted: объект не удалён — restore и purge только для удалённых'),
     ('LT019', 'reset_disabled',         'letopis: reset_disabled: reset выключен в этой установке'),
-    ('LT020', 'confirm_mismatch',       'letopis: confirm_mismatch: подтверждение не совпадает с именем схемы')
+    ('LT020', 'confirm_mismatch',       'letopis: confirm_mismatch: подтверждение не совпадает с именем схемы'),
+    ('LT021', 'derived_class',          'letopis: derived_class: строки производного класса пишет только его проектор'),
+    ('LT022', 'aggregate_field',        'letopis: aggregate_field: агрегатное поле считает база'),
+    ('LT023', 'projector_pending',      'letopis: projector_pending: проектор источника ещё не прочёл удаление')
 $$;
 
 create or replace function @SCHEMA@.lt_raise(p_code text, p_name text, p_msg text, p_detail jsonb default null)

package/sql/40-class.sql

@@ -12,7 +12,12 @@
 --   key       [<поле или роль>…] — из них вычисляется id (§2.3); [] — класс без ключа
 --   history   true | false | политика хранения (§2.11)
 --   ownerDefault 'tenant' | 'actor';  cache { ttl };  meta {…} до 64 КБ
---   resolved  развёрнутое описание с учётом предков — пишет триггер, присланное значение перезаписывается
+--   derivedBy имя проектора (план 1.1, §2.4): строки класса пишет только он; наследуется, потомок не меняет
+--   aggregate { <поле>: { sum: <поле источника> | count: true, of: <класс-источник>, via: <роль>, where?: JSON Schema } }
+--             агрегаты в базе (план 1.1, §2.4): поле держит триггер по живым строкам источника; наследуется,
+--             потомок заменяет целиком
+--   resolved  развёрнутое описание с учётом предков — пишет триггер, присланное значение перезаписывается; у
+--             источника агрегатов в нём ещё метка aggregatedBy — какие цели считают его строки (88-derived.sql)
 -- Скомпилированная проверка данных класса лежит в колонке validator строки Class.
 
 create or replace function @SCHEMA@.class_metaschema() returns jsonb
@@ -69,6 +74,23 @@ return $json${
     "ownerDefault": {"type": "string", "enum": ["tenant", "actor"]},
     "cache": {"type": "object"},
     "meta": {"type": "object"},
+    "derivedBy": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_.:-]{0,63}$"},
+    "aggregate": {
+      "type": "object",
+      "propertyNames": {"type": "string", "pattern": "^[^$]"},
+      "additionalProperties": {
+        "type": "object",
+        "required": ["of", "via"],
+        "additionalProperties": false,
+        "properties": {
+          "sum": {"type": "string", "pattern": "^[^$]"},
+          "count": {"type": "boolean", "enum": [true]},
+          "of": {"type": "string", "pattern": "^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$"},
+          "via": {"type": "string", "pattern": "^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$"},
+          "where": {"type": "object"}
+        }
+      }
+    },
     "resolved": {"type": "object"}
   }
 }$json$::jsonb;
@@ -114,6 +136,8 @@ declare
   hist jsonb;
   od text;
   cache jsonb;
+  der text;
+  agg jsonb;
   comp jsonb := '{}';
   i int;
   v jsonb;
@@ -143,6 +167,16 @@ begin
     if v ? 'history' then hist := v->'history'; end if;
     if v ? 'ownerDefault' then od := v->>'ownerDefault'; end if;
     if v ? 'cache' then cache := v->'cache'; end if;
+    -- производный класс (план 1.1, §2.4): проектор задаёт предок, потомок его не меняет
+    if v ? 'derivedBy' then
+      if der is not null and der <> v->>'derivedBy' then
+        perform @SCHEMA@.lt_raise('LT010', 'invalid_class',
+          format('derivedBy класса %s (%s) не совпадает с предком (%s)', v->>'name', v->>'derivedBy', der));
+      end if;
+      der := v->>'derivedBy';
+    end if;
+    -- агрегаты (план 1.1, §2.4): потомок заменяет описание предка целиком, {} — снимает унаследованное
+    if v ? 'aggregate' then agg := v->'aggregate'; end if;
     for m in select * from jsonb_each(coalesce(v->'meta', '{}')) loop
       if m.value = 'null'::jsonb then meta := meta - m.key; else meta := meta || jsonb_build_object(m.key, m.value); end if;
     end loop;
@@ -158,7 +192,9 @@ begin
     'history', coalesce(hist, 'true'),
     'ownerDefault', coalesce(od, 'tenant'),
     'cache', cache,
-    'meta', meta);
+    -- ключи только у производных и у целей агрегатов: у описаний до 1.2 их нет, и сравнение «было — стало» их не задевает
+    'meta', meta) || case when der is not null then jsonb_build_object('derivedBy', der) else '{}'::jsonb end
+                  || case when agg is not null and agg <> '{}'::jsonb then jsonb_build_object('aggregate', agg) else '{}'::jsonb end;
 end $$;
 
 -- Проверка описания класса: метасхема, правила ключа (§2.3), правило unset (§2.10), размер meta.
@@ -243,6 +279,25 @@ begin
       perform @SCHEMA@.lt_raise('LT010', 'invalid_class', format('history: неизвестный часовой пояс %s', res->'history'->>'tz'));
     end if;
   end if;
+  -- производный класс (план 1.1, §2.4): системным не бывает; его строки проектор удаляет и строит заново,
+  -- поэтому они не мешают удалять строки, на которые ссылаются (onDelete только cascade или unset)
+  if res ? 'derivedBy' then
+    if coalesce((data->>'system')::boolean, false) then
+      perform @SCHEMA@.lt_raise('LT010', 'invalid_class', 'системный класс не бывает производным');
+    end if;
+    for e in select key, value from jsonb_each(res->'ends') loop
+      if coalesce(e.value->>'onDelete', 'restrict') not in ('cascade', 'unset') then
+        perform @SCHEMA@.lt_raise('LT010', 'invalid_class',
+          format('конец %s производного класса — onDelete cascade или unset: производная строка не мешает удалять цель', e.key));
+      end if;
+    end loop;
+  end if;
+  -- агрегаты (план 1.1, §2.4; 88-derived.sql): цель — поля, источники, цикл, условия where; источник — метка
+  -- aggregatedBy и та же сверка против агрегатов, которые считают его строки (источник часто описывают после цели)
+  if res ? 'aggregate' then
+    res := @SCHEMA@.agg_prepare(res, data, p_tenant);
+  end if;
+  res := @SCHEMA@.agg_source(res, p_tenant);
   select * into c from @SCHEMA@.compile_validator(res->'schema');
   data := data || jsonb_build_object('resolved', res || jsonb_build_object('rules', c.rules, 'vars', c.vars));
   validator := c.validator;