letopis 0.21.0 → 1.0.0

package/llms.txt

@@ -0,0 +1,26 @@
+# letopis
+
+> Versioned entity store for Node.js on PostgreSQL 18. Every change is a version in a journal (history, reads as of a date, cursor subscriptions). Integrity, tenant isolation and access rules are enforced by the database itself (triggers and row-level security), so they hold for raw SQL too. Data is read and written with chains like `db.Shop(shop).Product().rows()`.
+
+Key facts for writing code with letopis 1.0:
+
+- ESM package, Node 22+, PostgreSQL 18+ with pgcrypto, database encoding UTF8. Runtime dependency: `postgres`. Zod 4 is an optional peer dependency needed only by `letopis/model`.
+- Install a schema with `up({ dsn, schema })` from an admin role; the schema is named `v2.<name>`. The application connects with a LOGIN role that is a member of `letopis_app`: `connect({ dsn, schema: 'v2.<name>', token | apiKey })`. A role that bypasses RLS is refused (`bypass_rls`) unless `allowBypassRls: true`.
+- Classes are hubs (objects) and links (relations with ends), described with `hub()`/`link()` from `letopis/model` and written to the database with `syncModels()` or `letopis sync`. A class with a key gets a deterministic UUID v5 id (`db.idOf`); uniqueness is the key.
+- Verbs return a chain; a terminal (`rows`, `first`, `ids`, `count`, …) executes the whole plan in one transaction. `create` only creates (a taken key is `exists`), `update` merges and never creates, `upsert` replaces the whole object (keyed classes only), `delete()` is a preview and `delete({ confirm: true })` deletes.
+- Money and counters: `update({ balance: inc(n) })` adds inside the statement; `update(patch, { rev })` fails with `conflict` if the row changed; `forUpdate()` locks rows inside `db.begin()`.
+- Access rules are always on and deny by default; `up({ tenant })` or `createTenant()` creates a tenant with the rule "authenticated users may do everything" and its first user.
+- Errors carry a lowercase `err.code`: `exists`, `conflict`, `invalid_data` (`err.issues`), `target_not_found`, `acl_denied`, `no_session`, `removed` (0.21 API with its replacement), …
+
+## Docs
+
+- [Agent cheatsheet](AGENT-CHEATSHEET.en.md): one page for an AI agent writing code with letopis — working cycle and pitfalls
+- [Guide](README.en.md): task-based guide, API reference, errors, limitations
+- [Шпаргалка для агента](AGENT-CHEATSHEET.md): the cheatsheet in Russian (original)
+- [Руководство](README.md): the guide in Russian (original)
+
+## Optional
+
+- [Migration from 0.21](MIGRATION.md): data import with `letopis import` and the API replacement table (Russian)
+- [Changelog](CHANGELOG.md): decisions by version, BREAKING changes of 1.0 (Russian)
+- Model of a concrete installation for an agent: `letopis describe --format text --out llms.txt` or `describeText(db.describe())` — classes, keys, fields and ends of that schema

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "letopis",
-  "version": "0.21.0",
-  "description": "Letopis (летопись): append-only versioned entity store on TimescaleDB with dot-notation chains — every change is a new row, history is first-class (asOf, versions, watch, cascade tombstones)",
+  "version": "1.0.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": [
-    "timescaledb",
     "postgres",
-    "append-only",
-    "immutable",
+    "postgresql",
+    "row-level-security",
     "versioning",
     "audit",
     "temporal",
     "asof",
-    "event-sourcing",
-    "booking",
     "graph",
-    "jsonb"
+    "jsonb",
+    "multi-tenant",
+    "acl",
+    "uuidv5"
   ],
   "license": "MIT",
   "repository": {
@@ -31,37 +31,67 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./model": {
+      "types": "./dist/model.d.ts",
+      "import": "./dist/model.js"
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
+  },
+  "bin": {
+    "letopis": "dist/cli.js"
   },
   "files": [
     "dist",
-    "scripts",
     "sql",
-    "docker",
     "README.md",
+    "README.en.md",
+    "AGENT-CHEATSHEET.md",
+    "AGENT-CHEATSHEET.en.md",
+    "llms.txt",
     "CHANGELOG.md",
+    "MIGRATION.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "tsx --test --test-concurrency=1 --test-force-exit test/*.test.ts",
     "check:docs": "node scripts/check-docs.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "seed:booking": "tsx scripts/gen-seed-booking.mjs",
+    "test:import-salon": "tsx bench/import-salon.mjs",
     "api:contract": "node scripts/gen-api-contract.mjs",
-    "bench": "tsx bench/history.bench.mjs",
     "prepublishOnly": "npm run typecheck && npm run check:docs && npm run build"
   },
   "dependencies": {
-    "fastest-validator": "^1.19.0",
-    "postgres": "^3.4.5"
+    "postgres": "^3.4.9"
+  },
+  "peerDependencies": {
+    "zod": "^4",
+    "@electric-sql/pglite": "^0.5.8",
+    "@electric-sql/pglite-socket": "^0.2.11"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    },
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@electric-sql/pglite-socket": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
-    "ioredis": "^5.11.1",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "@electric-sql/pglite": "^0.5.8",
+    "@electric-sql/pglite-socket": "^0.2.11",
+    "@types/node": "^22.20.5",
+    "letopis-0": "npm:letopis@0.21.0",
+    "tsx": "^4.23.15",
+    "typescript": "~5.9.3",
+    "zod": "4.6.5"
   }
 }

package/sql/10-core.sql

@@ -0,0 +1,136 @@
+-- letopis 1.0 — хранение и права (план, §2.2, этап 1, п. 1).
+-- Ровно три таблицы: entity (текущее состояние), log (журнал версий), secret (креды и сессии).
+-- Повторный накат ничего не меняет: всё создаётся с проверкой существования.
+
+-- Схему создаёт установщик (create schema … authorization владелец): у владельца нет права CREATE в базе.
+revoke all on schema @SCHEMA@ from public;
+grant usage on schema @SCHEMA@ to @APP@;
+
+-- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}.
+create or replace function @SCHEMA@.link_ids(links jsonb) returns uuid[]
+language sql immutable parallel safe
+return (
+  -- lax $.*[*]: значения концов, массивы разворачиваются, одиночная строка остаётся собой
+  select coalesce(array_agg(distinct (v #>> '{}')::uuid order by (v #>> '{}')::uuid), '{}'::uuid[])
+  from jsonb_path_query(coalesce(links, '{}'::jsonb), 'lax $.*[*]') as v
+);
+
+-- Снимок версии для хэша (§2.2). Не зависит от настроек сеанса: время — числом микросекунд,
+-- остальное — через текстовый вид jsonb, который от настроек не зависит.
+create or replace function @SCHEMA@.snapshot(
+  id uuid, rev int, class text, tenant uuid, owner uuid, links jsonb, data jsonb, tags text[],
+  at timestamptz, author uuid, agent text, op text, reason text, moved uuid
+) returns bytea
+language sql immutable parallel safe
+return convert_to(
+  jsonb_build_array(
+    id, rev, class, tenant, owner, links, data, to_jsonb(tags),
+    (extract(epoch from at) * 1000000)::bigint, author, agent, op, reason, moved
+  )::text,
+  'UTF8'
+);
+
+create or replace function @SCHEMA@.version_hash(prev_hash bytea, snap bytea) returns bytea
+language sql immutable parallel safe
+return sha256(coalesce(prev_hash, ''::bytea) || snap);
+
+create table if not exists @SCHEMA@.entity (
+  id         uuid primary key,
+  rev        int not null,
+  class      text not null,
+  cv         int not null default 0,
+  tenant     uuid not null,
+  owner      uuid not null,
+  links      jsonb not null default '{}'::jsonb,
+  ends       uuid[] generated always as (@SCHEMA@.link_ids(links)) stored,
+  data       jsonb not null default '{}'::jsonb,
+  tags       text[] not null default '{}',
+  at         timestamptz not null,
+  created_at timestamptz not null,
+  author     uuid not null,
+  agent      text,
+  op         text not null,
+  reason     text,
+  moved      uuid,
+  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,
+  validator  jsonpath
+);
+create index if not exists entity_class_tenant on @SCHEMA@.entity (class, tenant);
+create index if not exists entity_ends on @SCHEMA@.entity using gin (ends) with (fastupdate = off);
+create index if not exists entity_data on @SCHEMA@.entity using gin (data jsonb_path_ops);
+-- описание класса по имени (class_row): без вычисления v5 на каждый поиск
+create index if not exists entity_class_name on @SCHEMA@.entity ((data->>'name'), tenant) where class = 'Class';
+-- строки с владельцем-пользователем: переход владения арендатору при выходе из членства (этап 5)
+create index if not exists entity_owner on @SCHEMA@.entity (owner, tenant) where owner <> tenant;
+
+create table if not exists @SCHEMA@.log (
+  seq        bigint generated always as identity,
+  tx         xid8 not null default pg_current_xact_id(),
+  id         uuid not null,
+  rev        int not null,
+  class      text not null,
+  cv         int not null default 0,
+  tenant     uuid not null,
+  owner      uuid not null,
+  links      jsonb,
+  data       jsonb,
+  tags       text[],
+  at         timestamptz not null,
+  author     uuid not null,
+  agent      text,
+  op         text not null,
+  reason     text,
+  moved      uuid,
+  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,
+  constraint log_id_rev unique (id, rev)
+);
+create index if not exists log_class_at on @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;
+-- срез asOf и withDeleted по переходу и deep (ревизия 5): версии, ссылавшиеся на id, — как entity_ends у
+-- текущего состояния; без него поиск в журнале перебирал все версии класса (бенч этапа 7)
+create index if not exists log_ends on @SCHEMA@.log using gin (@SCHEMA@.link_ids(links));
+-- журнал часто прореживается (§2.11): чаще чистим
+alter table @SCHEMA@.log set (autovacuum_vacuum_scale_factor = 0.02, autovacuum_analyze_scale_factor = 0.02);
+
+create table if not exists @SCHEMA@.secret (
+  id          uuid primary key default gen_random_uuid(),
+  account     uuid not null,
+  kind        text not null,       -- PASSWORD, APIKEY, KEYSECRET, OTP, TOTP, IDENTITY, SESSION
+  ident       text,                -- email, телефон, префикс ключа, внешний id
+  material    bytea,               -- хэш пароля, ключа, кода или токена; секрет TOTP
+  meta        jsonb not null default '{}'::jsonb,
+  expires_at  timestamptz,
+  created_at  timestamptz not null default clock_timestamp(),
+  deleted_at  timestamptz
+);
+create unique index if not exists secret_kind_ident on @SCHEMA@.secret (kind, casefold(ident) collate pg_unicode_fast)
+  where deleted_at is null and ident is not null;
+create index if not exists secret_material on @SCHEMA@.secret (material) where kind = 'SESSION' and deleted_at is null;
+
+alter table @SCHEMA@.entity owner to @OWNER@;
+alter table @SCHEMA@.log owner to @OWNER@;
+alter table @SCHEMA@.secret owner to @OWNER@;
+alter function @SCHEMA@.link_ids(jsonb) owner to @OWNER@;
+alter function @SCHEMA@.snapshot(uuid, int, text, uuid, uuid, jsonb, jsonb, text[], timestamptz, uuid, text, text, text, uuid) owner to @OWNER@;
+alter function @SCHEMA@.version_hash(bytea, bytea) owner to @OWNER@;
+
+-- Права приложения (§2.7, этап 1, п. 1): только пользовательские колонки.
+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@;
+alter table @SCHEMA@.entity enable row level security;
+alter table @SCHEMA@.log enable row level security;
+alter table @SCHEMA@.secret enable row level security;
+revoke all on all functions in schema @SCHEMA@ from public;
+-- генерируемые колонки ends и hash вычисляются с правами пишущей роли: функции чистые, без побочных эффектов
+grant execute on function @SCHEMA@.link_ids(jsonb),
+  @SCHEMA@.snapshot(uuid, int, text, uuid, uuid, jsonb, jsonb, text[], timestamptz, uuid, text, text, text, uuid),
+  @SCHEMA@.version_hash(bytea, bytea) to @APP@;

package/sql/15-errors.sql

@@ -0,0 +1,60 @@
+-- letopis 1.0 — каталог ошибок базы (план, §7.1, этап 1, п. 7).
+-- У ошибок letopis собственный класс кодов SQLSTATE «LT»; текст — «letopis: <имя>: <сообщение>»,
+-- детали — JSON в поле DETAIL. Текст «цель не найдена» одинаков для несуществующей и чужой цели.
+
+create or replace function @SCHEMA@.error_catalog() returns table (code text, name text, message text)
+language sql immutable parallel safe
+as $$
+  values
+    ('LT001', 'no_session',             'letopis: no_session: нет действующей сессии'),
+    ('LT002', 'target_not_found',       'letopis: target_not_found: цель не найдена'),
+    ('LT003', 'invalid_data',           'letopis: invalid_data: данные не проходят описание класса'),
+    ('LT004', 'undeclared_end',         'letopis: undeclared_end: конец не объявлен в классе'),
+    ('LT005', 'tenant_denied',          'letopis: tenant_denied: чужой арендатор'),
+    ('LT006', 'acl_denied',             'letopis: acl_denied: отказ по правилам доступа'),
+    ('LT007', 'id_mismatch',            'letopis: id_mismatch: id не равен v5 от ключа'),
+    ('LT008', 'id_from_db',             'letopis: id_from_db: id класса без ключа выдаёт база'),
+    ('LT009', 'immutable_key',          'letopis: immutable_key: ключевое поле менять нельзя'),
+    ('LT010', 'invalid_class',          'letopis: invalid_class: описание класса отклонено'),
+    ('LT011', 'use_reclass',            'letopis: use_reclass: класс с ключом меняется функцией reclass()'),
+    ('LT012', 'reclass_denied',         'letopis: reclass_denied: смена класса отклонена'),
+    ('LT013', 'tightening_conflict',    'letopis: tightening_conflict: ужесточению описания мешают строки'),
+    ('LT014', 'isolation_level',        'letopis: isolation_level: операция разрешена только в read committed'),
+    ('LT015', 'recreated_in_statement', 'letopis: recreated_in_statement: id удалён и создан заново одним оператором'),
+    ('LT016', 'cursor_expired',         'letopis: cursor_expired: курсор подписки старше яруса all'),
+    ('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: подтверждение не совпадает с именем схемы')
+$$;
+
+create or replace function @SCHEMA@.lt_raise(p_code text, p_name text, p_msg text, p_detail jsonb default null)
+returns void
+language plpgsql
+as $$
+begin
+  raise exception using errcode = p_code, message = 'letopis: ' || p_name || ': ' || p_msg,
+    detail = coalesce(p_detail, '{}'::jsonb)::text;
+end $$;
+
+-- Ошибка по имени из каталога.
+create or replace function @SCHEMA@.lt_fail(p_name text, p_msg text, p_detail jsonb default null)
+returns void
+language plpgsql
+as $$
+declare
+  c text;
+begin
+  select e.code into c from @SCHEMA@.error_catalog() e where e.name = p_name;
+  perform @SCHEMA@.lt_raise(coalesce(c, 'LT000'), p_name, p_msg, p_detail);
+end $$;
+
+do $$
+declare f text;
+begin
+  foreach f in array array['error_catalog()', 'lt_raise(text, text, text, jsonb)', 'lt_fail(text, text, jsonb)'] loop
+    execute format('alter function @SCHEMA@.%s owner to @OWNER@', f);
+    execute format('revoke all on function @SCHEMA@.%s from public', f);
+  end loop;
+end $$;
+grant execute on function @SCHEMA@.error_catalog() to @APP@;

package/sql/20-context.sql

@@ -0,0 +1,153 @@
+-- letopis 1.0 — сессии и контекст запроса (план, §2.9, этап 1, п. 3, этап 5, п. 2–4).
+-- Каждая операция библиотеки — транзакция, первые операторы которой выставляют letopis.token,
+-- при имперсонации letopis.account и при выборе арендатора letopis.tenant через set_config(…, true).
+-- Без настоящего токена настройки ничего не дают: сессия ищется по sha256 токена, а
+-- letopis.account действует только для сессии с правом auth.impersonate (правила System).
+
+-- Контекст запроса: актор (аккаунт, от имени которого идёт работа), рабочий арендатор, автор и агент
+-- версии, категории актора и его роли в арендаторе, сессия и сервис (при имперсонации).
+-- Только читает. Нет токена или сессии — пустой контекст; запрещённая имперсонация и арендатор без
+-- членства — ошибка: молча работать в другом арендаторе или от другого имени нельзя.
+create or replace function @SCHEMA@.ctx(out account uuid, out tenant uuid, out author uuid, out agent text,
+  out categories text[], out roles text[], out session uuid, out service uuid)
+language plpgsql stable security definer
+set search_path = pg_catalog, @SCHEMA@, pg_temp
+as $$
+#variable_conflict use_variable
+declare
+  tok text := nullif(current_setting('letopis.token', true), '');
+  imp text := nullif(current_setting('letopis.account', true), '');
+  want text := nullif(current_setting('letopis.tenant', true), '');
+  s record;
+  a record;
+  t record;
+  m record;
+  scats text[];
+  sroles text[];
+  stenant uuid;
+begin
+  if tok is null then
+    return;
+  end if;
+  select x.id, x.account, x.meta into s
+  from @SCHEMA@.secret x
+  where x.kind = 'SESSION' and x.deleted_at is null
+    and x.material = sha256(convert_to(tok, 'UTF8'))
+    and (x.expires_at is null or x.expires_at > clock_timestamp());
+  if s.id is null then
+    return;
+  end if;
+  select e.id, e.data into a from @SCHEMA@.entity e
+  where e.id = s.account and e.class = 'Account' and e.tenant = '@SYSTEM@'::uuid and coalesce((e.data->>'enabled')::boolean, true);
+  if a.id is null then
+    return;
+  end if;
+  session := s.id;
+  account := s.account;
+  tenant := coalesce((s.meta->>'tenant')::uuid, s.account);
+  if imp is not null and imp is distinct from s.account::text then
+    -- имперсонация (этап 5, п. 3): право сервиса — по правилам System, в его собственном арендаторе
+    if not pg_input_is_valid(imp, 'uuid') then
+      perform @SCHEMA@.lt_fail('acl_denied', 'letopis.account — не id аккаунта');
+    end if;
+    scats := array(select jsonb_array_elements_text(coalesce(a.data->'categories', '[]'::jsonb)));
+    stenant := tenant;
+    sroles := case when stenant = s.account then array['owner'] else array(
+      select jsonb_array_elements_text(coalesce(x.data->'roles', '[]'::jsonb)) from @SCHEMA@.entity x
+      where x.id = @SCHEMA@.v5_id(stenant, 'member', array[s.account::text, stenant::text]) and x.class = 'member') end;
+    if not coalesce((@SCHEMA@.acl_api_for(stenant, scats, sroles, 'auth.impersonate', true)->>'allow')::boolean, false) then
+      perform @SCHEMA@.lt_fail('acl_denied', 'нет права auth.impersonate');
+    end if;
+    select e.id, e.data into a from @SCHEMA@.entity e where e.id = imp::uuid and e.class = 'Account' and e.tenant = '@SYSTEM@'::uuid;
+    -- от имени System, сервисов, системных администраторов и отключённых аккаунтов действовать нельзя
+    if a.id is null or not coalesce((a.data->>'enabled')::boolean, true) or a.id = '@SYSTEM@'::uuid
+       or coalesce(a.data->'categories' ?| array['System', 'Service'], false)
+       or exists (select 1 from @SCHEMA@.entity x
+                  where x.id = @SCHEMA@.v5_id('@SYSTEM@'::uuid, 'member', array[a.id::text, '@SYSTEM@']) and x.class = 'member') then
+      perform @SCHEMA@.lt_fail('acl_denied', 'действовать от имени этого аккаунта нельзя');
+    end if;
+    service := s.account;
+    agent := s.account::text;
+    account := a.id;
+    tenant := a.id;
+  end if;
+  if want is not null then
+    if not pg_input_is_valid(want, 'uuid') then
+      perform @SCHEMA@.lt_fail('tenant_denied', 'letopis.tenant — не id арендатора');
+    end if;
+    tenant := want::uuid;
+  end if;
+  if tenant = account then
+    roles := array['owner'];
+  else
+    -- работа в чужом арендаторе — по членству; членство проверяется при каждом вызове
+    select x.data into m from @SCHEMA@.entity x
+    where x.id = @SCHEMA@.v5_id(tenant, 'member', array[account::text, tenant::text]) and x.class = 'member' and x.tenant = tenant;
+    select e.id into t from @SCHEMA@.entity e
+    where e.id = tenant and e.class = 'Account' and e.tenant = '@SYSTEM@'::uuid and coalesce((e.data->>'enabled')::boolean, true);
+    if m is null or t.id is null then
+      perform @SCHEMA@.lt_fail('tenant_denied', 'нет членства в арендаторе');
+    end if;
+    roles := array(select jsonb_array_elements_text(coalesce(m.data->'roles', '[]'::jsonb)));
+  end if;
+  categories := array(select jsonb_array_elements_text(coalesce(a.data->'categories', '[]'::jsonb)));
+  author := account;
+end $$;
+
+create or replace function @SCHEMA@.ctx_tenant() returns uuid
+language sql stable
+return (select c.tenant from @SCHEMA@.ctx() c);
+
+create or replace function @SCHEMA@.ctx_account() returns uuid
+language sql stable
+return (select c.account from @SCHEMA@.ctx() c);
+
+-- Новая сессия: 256 случайных бит, в базе — только sha256 токена. В meta — время и способы входа
+-- (без них не проверить «недавний вход»), рабочий арендатор после auth.switch, выпустивший сервис.
+create or replace function @SCHEMA@.new_session(p_account uuid, p_ttl interval, p_meta jsonb) returns text
+language plpgsql volatile security definer
+set search_path = pg_catalog, @SCHEMA@, pg_temp
+as $$
+declare
+  tok text := encode(@PGCRYPTO@.gen_random_bytes(32), 'hex');
+begin
+  insert into @SCHEMA@.secret (account, kind, material, meta, expires_at)
+  values (p_account, 'SESSION', sha256(convert_to(tok, 'UTF8')),
+          coalesce(p_meta, '{}'::jsonb) || jsonb_build_object('login_at', clock_timestamp(), 'ttl', coalesce(p_ttl, interval '7 days')::text),
+          clock_timestamp() + coalesce(p_ttl, interval '7 days'));
+  return tok;
+end $$;
+
+-- Вход по API-ключу (APIKEY): префикс ищется в ident, ключ сверяется по sha256. Сессия помнит ключ
+-- (meta.cred): отзыв ключа гасит только его сессии.
+create or replace function @SCHEMA@.login_apikey(p_key text) returns text
+language plpgsql volatile security definer
+set search_path = pg_catalog, @SCHEMA@, pg_temp
+as $$
+declare
+  k record;
+begin
+  select s.id, s.account into k
+  from @SCHEMA@.secret s
+  join @SCHEMA@.entity a on a.id = s.account and a.class = 'Account' and a.tenant = '@SYSTEM@'::uuid
+  where s.kind = 'APIKEY' and s.deleted_at is null
+    and casefold(s.ident) collate pg_unicode_fast = casefold(left(p_key, 12)) collate pg_unicode_fast
+    and s.material = sha256(convert_to(p_key, 'UTF8'))
+    and (s.expires_at is null or s.expires_at > clock_timestamp())
+    and coalesce((s.meta->>'enabled')::boolean, true)
+    and coalesce((a.data->>'enabled')::boolean, true);
+  if k.account is null then
+    raise exception using errcode = 'LT001', message = 'letopis: no_session: неверный ключ';
+  end if;
+  return @SCHEMA@.new_session(k.account, interval '7 days', jsonb_build_object('methods', jsonb_build_array('APIKEY'), 'cred', k.id));
+end $$;
+
+alter function @SCHEMA@.ctx() owner to @OWNER@;
+alter function @SCHEMA@.ctx_tenant() owner to @OWNER@;
+alter function @SCHEMA@.ctx_account() owner to @OWNER@;
+alter function @SCHEMA@.new_session(uuid, interval, jsonb) owner to @OWNER@;
+alter function @SCHEMA@.login_apikey(text) owner to @OWNER@;
+revoke all on function @SCHEMA@.ctx(), @SCHEMA@.ctx_tenant(), @SCHEMA@.ctx_account(),
+  @SCHEMA@.new_session(uuid, interval, jsonb), @SCHEMA@.login_apikey(text) from public;
+grant execute on function @SCHEMA@.ctx(), @SCHEMA@.ctx_tenant(), @SCHEMA@.ctx_account(),
+  @SCHEMA@.login_apikey(text) to @APP@;