letopis 1.4.0 → 1.4.2

package/dist/admin.d.ts

@@ -17,22 +17,28 @@ export interface VerifyIssue {
 export interface VerifyResult {
     ok: boolean;
     issues: VerifyIssue[];
-    /** Хэш всех голов цепочек — храните вне базы: подмену последних версий выдаст его расхождение. */
+    /** Один хэш текущих версий всех объектов — храните его вне базы: подмену самых свежих версий выдаст его расхождение. */
     anchor: string;
 }
 export interface MaintainOptions {
-    /** Момент «сейчас» для прореживания — только в установке с allowReset (тесты). */
+    /** Момент «сейчас» для прореживания — только в установке с `allowReset` (тесты). */
     now?: string | Date;
-    /** Пачек прореживания за вызов (по умолчанию 100); каждая — своя транзакция. */
+    /** Сколько пачек прореживания журнала самое большее сделать за один вызов; каждая пачка — своя транзакция. */
     batches?: number;
-    /** Версий в пачке (по умолчанию 10 000). */
+    /** Сколько версий самое большее удалить в одной пачке прореживания. */
     limit?: number;
 }
+/** Внутренняя опция maintain(): остановка запуска по расписанию — текущая пачка доделывается, следующая не начинается. */
+export declare const MAINTAIN_STOP: unique symbol;
 export interface MaintainReport {
     /** Другой процесс уже обслуживает установку (держит строку-замок обслуживания): этот вызов ничего не делал. */
     skipped: boolean;
-    /** Удалено истёкших и погашенных сессий и одноразовых кодов. */
+    /** Удалено сессий: истёкших и погашенных (выход, отзыв, смена пароля, отключение или удаление аккаунта). */
     sessions: number;
+    /**
+     * Удалено одноразовых кодов (вид `OTP` и свои виды `OTP_<ИМЯ>` из `issueOtp({ kind })`): истёкших, использованных,
+     * заменённых новым и исчерпавших попытки.
+     */
     codes: number;
     /** Прорежено версий журнала. */
     thinned: number;
@@ -46,7 +52,7 @@ export interface ResetOptions {
     level: 'sessions' | 'tenant' | 'all';
     /** Подтверждение — имя схемы установки. */
     confirm: string;
-    /** level: 'tenant' — арендатор (по умолчанию — арендатор сессии). */
+    /** Какого арендатора сбросить при `level: 'tenant'` — его id; на других уровнях не учитывается. */
     tenant?: string;
 }
 export interface ResetResult {
@@ -55,10 +61,10 @@ export interface ResetResult {
     tenant?: string;
     rows?: number;
     versions?: number;
-    /** level: 'all' — новый ключ сервиса: прежние сессии и ключи больше не действуют. */
+    /** `level: 'all'` — новый ключ сервиса: прежние сессии и ключи больше не действуют. */
     serviceKey?: string;
 }
-/** Машинное описание модели (db.describe()). */
+/** Машинное описание модели (`db.describe()`). */
 export interface ModelDescription {
     schema: string;
     tenant: string | null;
@@ -117,13 +123,23 @@ export declare function verify(a: AdminCtx, opts?: {
  * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
  * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
  */
-export declare function maintain(a: AdminCtx, opts?: MaintainOptions): Promise<MaintainReport>;
+export declare function maintain(a: AdminCtx, opts?: MaintainOptions & {
+    [MAINTAIN_STOP]?: () => boolean;
+}): Promise<MaintainReport>;
 /** Предупреждение о заполненной очереди сигналов (§2.12): больше половины — зависший слушатель. */
 export declare function queueWarning(queue: number): string | null;
-/** Интервал расписания: число мс или '30s', '15m', '1h', '1d'. */
-export declare function parseInterval(v: string | number): number;
-/** Запуск maintain() по расписанию (connect({ maintain: '1h' })): ошибки — предупреждением. */
-export declare function scheduleMaintain(run: () => Promise<unknown>, every: string | number): () => void;
+/**
+ * Интервал расписания: число мс или строка '500ms', '30s', '15m', '1h', '1d' — конечный, от 1 мс до 2³¹−1 мс (около 24
+ * суток); иначе invalid_data. Ноль, отрицательное, NaN и слишком длинный интервал таймер Node.js превращает в 1 мс —
+ * обслуживание шло бы без перерыва.
+ */
+export declare function parseInterval(v: unknown): number;
+/**
+ * Запуск maintain() по расписанию (connect({ maintain: '1h' }); ms — уже проверенный интервал): ошибки — предупреждением,
+ * следующий запуск не начинается, пока идёт прежний. Возвращает остановку: она снимает таймер, просит идущий запуск не
+ * начинать новых пачек и ждёт его конца — close() закрывает пул после неё, а не посреди пачки.
+ */
+export declare function scheduleMaintain(run: (stopped: () => boolean) => Promise<unknown>, ms: number): () => Promise<void>;
 /**
  * Сброс (этап 6, п. 6). Предохранители — в базе: флаг allowReset установки, право letopis.reset,
  * подтверждение именем схемы. tenant — пачками (длинная операция не держит горизонт подписок).
@@ -153,6 +169,6 @@ export declare function rebuildAggregates(env: {
 }, cls: string): Promise<number>;
 /** Машинное описание модели арендатора вместе с метаданными классов (этап 6, п. 12). */
 export declare function describe(a: AdminCtx): ModelDescription;
-/** Описание модели текстом для языковых моделей (llms.txt). */
+/** Описание модели текстом для языковых моделей. */
 export declare function describeText(d: ModelDescription): string;
 export {};

package/dist/admin.js

@@ -1,6 +1,8 @@
 import { LetopisError, fromDbError } from './errors.js';
 import { runTx } from './tx.js';
 import { CHAIN_METHODS, DB_METHODS } from './types.js';
+/** Внутренняя опция maintain(): остановка запуска по расписанию — текущая пачка доделывается, следующая не начинается. */
+export const MAINTAIN_STOP = Symbol('letopis.maintain.stop');
 const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
 const one = async (a, text, params = []) => a.exec.run(async (q) => (await q.unsafe(text, params))[0]);
 export async function verify(a, opts = {}) {
@@ -24,8 +26,20 @@ export async function maintain(a, opts = {}) {
     const report = { skipped: false, sessions: 0, codes: 0, thinned: 0, batches: 0, more: false, queue: 0 };
     const max = opts.batches ?? 100;
     for (let i = 0; i < max; i++) {
-        // блокировку берёт сама maintain() базы — строку-замок, которую посторонняя роль не займёт; занята — null
-        const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select ${a.S}.maintain($1::text::timestamptz, $2::int) as r`, [now, opts.limit ?? 10_000]));
+        // запуск по расписанию остановлен (close()): следующая пачка не начинается, отчёт — с more: true
+        if (i > 0 && opts[MAINTAIN_STOP]?.())
+            break;
+        // блокировку берёт сама maintain() базы — строку-замок, которую посторонняя роль не займёт; занята — null.
+        // Истёкшие сессии и коды — только в первой пачке (план 2.0, 7.3 №4); схема, функции которой ещё не обновил up()
+        // (нет третьего аргумента, 42883), — прежний вызов: он чистит в каждой пачке
+        const call = (cleanup) => runTx(a.txc, (q) => q.unsafe(cleanup === null
+            ? `select ${a.S}.maintain($1::text::timestamptz, $2::int) as r`
+            : `select ${a.S}.maintain($1::text::timestamptz, $2::int, $3::boolean) as r`, (cleanup === null ? [now, opts.limit ?? 10_000] : [now, opts.limit ?? 10_000, cleanup])));
+        const [{ r }] = await call(i === 0).catch((e) => {
+            if (e.code === '42883')
+                return call(null);
+            throw e;
+        });
         if (r === null) {
             if (i === 0)
                 return { ...report, skipped: true };
@@ -50,28 +64,49 @@ export async function maintain(a, opts = {}) {
 export function queueWarning(queue) {
     return queue > 0.5 ? `letopis: очередь сигналов PostgreSQL заполнена на ${(queue * 100).toFixed(0)} % — проверьте зависших слушателей` : null;
 }
-/** Интервал расписания: число мс или '30s', '15m', '1h', '1d'. */
+/** Самый длинный интервал таймера Node.js — 2³¹−1 мс (около 24,8 суток): дольше таймер не ждёт и срабатывает сразу. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Интервал расписания: число мс или строка '500ms', '30s', '15m', '1h', '1d' — конечный, от 1 мс до 2³¹−1 мс (около 24
+ * суток); иначе invalid_data. Ноль, отрицательное, NaN и слишком длинный интервал таймер Node.js превращает в 1 мс —
+ * обслуживание шло бы без перерыва.
+ */
 export function parseInterval(v) {
+    let ms = Number.NaN;
     if (typeof v === 'number')
-        return v;
-    const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(v.trim());
-    if (!m)
-        throw new LetopisError('invalid_data', `интервал ${v}: число мс или '30s', '15m', '1h', '1d'`);
-    const n = Number(m[1]);
-    return n * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+        ms = v;
+    else if (typeof v === 'string') {
+        const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(v.trim());
+        if (m)
+            ms = Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+    }
+    if (!Number.isFinite(ms) || ms < 1 || ms > MAX_TIMER_MS) {
+        const shown = typeof v === 'string' ? `'${v}'` : typeof v === 'number' || typeof v === 'boolean' || v == null ? String(v) : typeof v;
+        throw new LetopisError('invalid_data', `интервал ${shown}: число мс или строка '30s', '15m', '1h', '1d' — от 1 мс до 2³¹−1 мс (около 24 суток)`);
+    }
+    return ms;
 }
-/** Запуск maintain() по расписанию (connect({ maintain: '1h' })): ошибки — предупреждением. */
-export function scheduleMaintain(run, every) {
-    const ms = parseInterval(every);
-    let busy = false;
+/**
+ * Запуск maintain() по расписанию (connect({ maintain: '1h' }); ms — уже проверенный интервал): ошибки — предупреждением,
+ * следующий запуск не начинается, пока идёт прежний. Возвращает остановку: она снимает таймер, просит идущий запуск не
+ * начинать новых пачек и ждёт его конца — close() закрывает пул после неё, а не посреди пачки.
+ */
+export function scheduleMaintain(run, ms) {
+    let stopped = false;
+    let current = null;
     const timer = setInterval(() => {
-        if (busy)
+        if (current || stopped)
             return;
-        busy = true;
-        run().catch((e) => console.warn(`letopis: maintain по расписанию: ${e.message}`)).finally(() => (busy = false));
+        current = run(() => stopped)
+            .then(() => { }, (e) => console.warn(`letopis: maintain по расписанию: ${e.message}`))
+            .finally(() => (current = null));
     }, ms);
     timer.unref?.();
-    return () => clearInterval(timer);
+    return async () => {
+        stopped = true;
+        clearInterval(timer);
+        await current;
+    };
 }
 /**
  * Сброс (этап 6, п. 6). Предохранители — в базе: флаг allowReset установки, право letopis.reset,
@@ -163,7 +198,7 @@ export function describe(a) {
     })).sort((x, y) => Number(x.system) - Number(y.system) || x.name.localeCompare(y.name));
     return { schema: a.schema, tenant: a.tenant(), classes, methods: { chain: CHAIN_METHODS, db: DB_METHODS } };
 }
-/** Описание модели текстом для языковых моделей (llms.txt). */
+/** Описание модели текстом для языковых моделей. */
 export function describeText(d) {
     const out = [`# letopis: модель схемы ${d.schema}`, '',
         'Цепочка: db.Класс(фильтр).Связь().Класс().rows(); запись — create, update, upsert, delete; история — versions(), asOf(), withDeleted().', ''];

package/dist/auth.d.ts

@@ -15,6 +15,24 @@ export interface LoginResult {
     account: string;
     token: string;
 }
+/** Сведения о сессии по её токену (`db.auth.session()`). Время — строкой ISO 8601. */
+export interface SessionInfo {
+    /** Аккаунт сессии. */
+    account: string;
+    /** Рабочий арендатор сессии: выбранный `auth.switch()` или собственный арендатор аккаунта. */
+    tenant: string;
+    /** Членство в рабочем арендаторе цело и арендатор включён; в собственном арендаторе — всегда true. */
+    member: boolean;
+    /** Когда сессия истечёт, если ею не пользоваться (подключение продлевает её само). */
+    expiresAt: string;
+    /** Время входа. */
+    loginAt: string;
+    /**
+     * Способы входа: вид креда, по которому вошли (`PASSWORD`, `APIKEY`, `KEYSECRET`, `OTP`, `TELEGRAM` и т. п.), `SERVICE` —
+     * сессию выпустил сервис (`sessionFor()`), `TOTP` — пройден второй фактор. У сессии от `createTenant()` список пуст.
+     */
+    methods: string[];
+}
 /** Кред без секретного материала. */
 export interface Credential {
     id: string;
@@ -28,7 +46,7 @@ export interface Credential {
     expires_at: string | null;
 }
 export interface AuthApi {
-    /** Пароль (и любой «логин/пароль»: kind — PASSWORD, EMAIL, …): создать или заменить. Смена гасит остальные сессии аккаунта. */
+    /** Пароль (и любой «логин/пароль»: `kind` — `PASSWORD`, `EMAIL`, …): создать или заменить. Смена гасит остальные сессии аккаунта. */
     setPassword(a: {
         account: AccountRef;
         identifier: string;
@@ -38,9 +56,9 @@ export interface AuthApi {
         keepCurrent?: boolean;
     }): Promise<string>;
     /**
-     * Вход по паролю — для сервиса с правом auth.password и auth.session. Неудача — null. С `totp` после
-     * верного пароля база проверяет код TOTP аккаунта (право auth.totp; счётчик неудач и блокировка — общие
-     * с verifyTotp): верный — сессия со способами [kind, 'TOTP'], неверный или повторный — null.
+     * Вход по паролю — для сервиса с правом `auth.password` и `auth.session`. Неудача — `null`. С `totp` после
+     * верного пароля база проверяет код TOTP аккаунта (право `auth.totp`; счётчик неудач и блокировка — общие
+     * с `verifyTotp()`): верный — сессия со способами `[kind, 'TOTP']`, неверный или повторный — `null`.
      */
     verifyPassword(a: {
         identifier: string;
@@ -70,7 +88,10 @@ export interface AuthApi {
         id: string;
     }>;
     verifyKeySecret(key: string, secret: string): Promise<LoginResult | null>;
-    /** TOTP: секрет в base32 и ссылка otpauth:// для QR; фактор включает первая успешная проверка. */
+    /**
+     * Подключает второй фактор TOTP: выдаёт секрет (base32) и адрес `otpauth://` для QR-кода в приложении-аутентификаторе.
+     * Фактор включится после первой верной проверки кода — `verifyTotp()` или входа с `totp`.
+     */
     enrollTotp(a: {
         account: AccountRef;
         issuer?: string;
@@ -85,7 +106,7 @@ export interface AuthApi {
         window?: number;
     }): Promise<boolean>;
     totpEnabled(account: AccountRef): Promise<boolean>;
-    /** Одноразовый код для доставки сервисом (право auth.otp). */
+    /** Одноразовый код для доставки сервисом (право `auth.otp`). */
     issueOtp(a: {
         account: AccountRef;
         identifier: string;
@@ -96,13 +117,19 @@ export interface AuthApi {
     }): Promise<{
         code: string;
     }>;
-    /** Вход по одноразовому коду: успех и перебор (лимит задал выпуск, 1–10, по умолчанию 5) сжигают код. */
+    /**
+     * Вход по одноразовому коду: верный код открывает новую сессию. Код сгорает после верного ввода и после исчерпания
+     * неверных попыток — их число задаёт `issueOtp({ maxAttempts })`.
+     */
     verifyOtp(a: {
         identifier: string;
         code: string;
         kind?: string;
     }): Promise<LoginResult | null>;
-    /** Внешняя identity (TELEGRAM, GOOGLE, SSO): токен проверяет сервис, здесь — связка. */
+    /**
+     * Привязывает к аккаунту внешнюю учётную запись — например, для входа через Telegram, Google или SSO. Входят по привязке
+     * через `lookup()`; токен внешнего сервиса ваш сервис проверяет сам.
+     */
     link(a: {
         account: AccountRef;
         kind: string;
@@ -110,7 +137,11 @@ export interface AuthApi {
         meta?: Record<string, unknown>;
         confirmed?: boolean;
     }): Promise<string>;
-    /** Вход по identity — для сервиса с правами auth.identity и auth.session; `totp` — как у verifyPassword. */
+    /**
+     * Вход через привязанную внешнюю учётную запись: находит аккаунт по виду и id у внешнего сервиса и открывает ему новую
+     * сессию. Вызывает сервис с правами `auth.identity` и `auth.session`, когда уже сам проверил токен внешнего сервиса;
+     * `totp` — как у `verifyPassword()`.
+     */
     lookup(a: {
         kind: string;
         identifier: string;
@@ -118,36 +149,48 @@ export interface AuthApi {
         ttl?: number;
         totp?: string;
     }): Promise<LoginResult | null>;
-    /** Креды аккаунта без секретов. */
+    /** Способы входа (креды) аккаунта — без хэшей и секретов. */
     credentials(account: AccountRef): Promise<Credential[]>;
     /**
      * Удалить кред. Ключ API и пара ключ + секрет гасят только свои сессии, прочие креды — остальные сессии
-     * аккаунта; текущая гаснет, если keepCurrent: false. Свои ключи сервис отзывает сам; последний
-     * действующий ключ сервиса не отзывается (acl_denied).
+     * аккаунта; текущая гаснет, если `keepCurrent: false`. Свои ключи сервис отзывает сам; последний
+     * действующий ключ сервиса не отзывается (`acl_denied`).
      */
     revokeCredential(id: string, opts?: {
         keepCurrent?: boolean;
     }): Promise<boolean>;
-    /** Признаки креда confirmed и enabled (право auth.credential). */
+    /** Признаки креда `confirmed` и `enabled` (право `auth.credential`). */
     setFlags(id: string, flags: {
         confirmed?: boolean;
         enabled?: boolean;
     }): Promise<boolean>;
-    /** Короткая сессия пользователя для другого процесса (право auth.session). */
+    /** Сессия пользователя для другого процесса (право `auth.session`); срок — `ttl` в секундах, по умолчанию 7 суток. */
     sessionFor(account: AccountRef, opts?: {
         ttl?: number;
     }): Promise<string>;
+    /**
+     * Сведения о сессии по её токену — для сервиса, который держит токен пользователя (например, в cookie): чья это
+     * сессия, в каком арендаторе она работает, цело ли там членство, когда истечёт, когда и как был вход. Подключение
+     * по этому токену не открывается, срок сессии не продлевается. Вызывает сервис или системный администратор
+     * (право `auth.session`).
+     * @param token Токен сессии пользователя — тот, что выдали вход или `sessionFor()`.
+     * @returns Сведения о сессии или `null`: токен неверный, сессия погашена или истекла, аккаунт отключён — причина
+     * не различается.
+     * @throws LetopisError `acl_denied` — у вызывающего нет права `auth.session` (например, это обычный пользователь);
+     * `no_session` — у подключения нет действующей сессии.
+     */
+    session(token: string): Promise<SessionInfo | null>;
     /** Продлить текущую сессию; новый срок — от сейчас. */
     refresh(opts?: {
         ttl?: number;
     }): Promise<string>;
     /** Выход: погасить текущую сессию. */
     revoke(): Promise<boolean>;
-    /** Выход везде: все сессии аккаунта (чужого — с правом auth.session). */
+    /** Выход везде: все сессии аккаунта (чужого — с правом `auth.session`). */
     revokeAll(account?: AccountRef): Promise<number>;
     /** Переключить арендатора сессии: собственный или по членству. */
     switch(tenant: string): Promise<void>;
-    /** Арендаторы, доступные аккаунту сессии: собственный (owner) и по членству. */
+    /** Арендаторы, доступные аккаунту сессии: собственный (`owner`) и по членству. */
     tenants(): Promise<{
         tenant: string;
         roles: string[];
@@ -155,7 +198,8 @@ export interface AuthApi {
     /**
      * Удалить аккаунт (этап 6; accounts.purge 0.21): системный администратор или владелец его
      * арендатора; себя и последнего владельца арендатора — нельзя. Данные арендатора стираются,
-     * владение строками в чужих арендаторах переходит им, сессии гаснут, креды удаляются.
+     * владение строками в чужих арендаторах переходит им, сессии гаснут, креды удаляются. Владелец стирает
+     * и арендатора, в котором работает: его сессия возвращается в личный арендатор.
      */
     purgeAccount(account: AccountRef): Promise<{
         account: string;

package/dist/auth.js

@@ -27,7 +27,12 @@ export async function verifyHash(password, stored) {
     if (algo !== 'scrypt' || !hashB64)
         return false;
     const want = Buffer.from(hashB64, 'base64');
-    const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, { N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem });
+    // N, r, p — из строки хэша (подходят и хэши, импортированные из других систем), память — не больше 64 МБ: хэш,
+    // которому нужно больше, или с недопустимыми параметрами scrypt Node.js отвергает — это понятная ошибка, а не «неверный
+    // пароль» (false). Текст Node.js в сообщение не идёт: он зависит от сборки OpenSSL
+    const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, { N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem }).catch(() => {
+        throw new LetopisError('invalid_data', `хэш пароля: параметры scrypt N=${N}, r=${r}, p=${p} недопустимы или требуют больше 64 МБ памяти`);
+    });
     return got.length === want.length && timingSafeEqual(got, want);
 }
 /** Холостая проверка: «идентификатора нет» отвечает не быстрее, чем «пароль неверен». */
@@ -178,6 +183,11 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
         async sessionFor(account, opts) {
             return (await login(accId(account), opts?.ttl, ['SERVICE'])).token;
         },
+        async session(token) {
+            const r = (await one(`select ${S}.auth_session_info($1) as r`, [token])).r;
+            // jsonb хранит ключи в своём порядке — объект собирается в порядке описания SessionInfo
+            return r && { account: r.account, tenant: r.tenant, member: r.member, expiresAt: r.expiresAt, loginAt: r.loginAt, methods: r.methods };
+        },
         async refresh(opts) {
             return (await one(`select ${S}.auth_refresh(coalesce($1::interval, interval '7 days')) as e`, [ttlOf(opts?.ttl)])).e;
         },
@@ -198,7 +208,11 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
             return rows.map((r) => ({ tenant: r.tenant, roles: r.roles }));
         },
         async purgeAccount(account) {
-            return (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
+            const r = (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
+            // стёрт арендатор, в котором работала сессия корня: база вернула её в личный арендатор — перечитать
+            if (canSwitch)
+                await onSwitch();
+            return r;
         },
     };
 }

package/dist/cache.d.ts

@@ -4,7 +4,11 @@ export declare const ACL_CLASSES: ReadonlySet<string>;
 export interface CacheOptions {
     /** Срок ответа по умолчанию, секунды (60). */
     ttl?: number;
-    /** Работать без слушателя сигналов — только по сроку (пул в режиме транзакций, §2.12). */
+    /**
+     * Включает кэш, даже когда подключение не слушает сигналы базы: `connect({ listen: false })` (например, за PgBouncer в
+     * режиме транзакций) или установка с `up({ signals: 'none' })`; без опции кэш тогда выключен. Такой ответ живёт до
+     * конца срока: записи других процессов его не сбрасывают, записи этого подключения — сбрасывают (§2.12).
+     */
     ttlOnly?: boolean;
     /** Не больше ответов в памяти (10 000): старые вытесняются. */
     max?: number;

package/dist/cache.js

@@ -85,7 +85,8 @@ export class ResultCache {
             return undefined;
         }
         this.st.hits++;
-        return e.value;
+        // копия: правка выданного ответа не портит запись кэша (план 2.0, 7.2 №5)
+        return structuredClone(e.value);
     }
     /** Положить ответ, если с момента снимка не было сигналов о его классах и сессии. */
     set(key, value, classes, session, tok, ttlMs, sessionExpires) {
@@ -100,7 +101,7 @@ export class ResultCache {
         }
         if (this.map.size >= this.max)
             this.map.delete(this.map.keys().next().value);
-        this.map.set(key, { value, classes: [...classes], session, tenant: tok.tenant, expires: Date.now() + ttlMs, sessionExpires });
+        this.map.set(key, { value: structuredClone(value), classes: [...classes], session, tenant: tok.tenant, expires: Date.now() + ttlMs, sessionExpires });
         this.st.stores++;
         return true;
     }