@coopenomics/extension-kit 2026.9.22 → 2026.9.24-3

package/dist/index.d.cts

@@ -5,6 +5,7 @@ import { Reflector } from '@nestjs/core';
 import { Observable } from 'rxjs';
 import { ZodObject } from 'zod';
 import { Cooperative } from 'cooptypes';
+import { MigrationInterface, ObjectLiteral, Repository } from 'typeorm';
 
 /**
  * Пути внутри объекта, по которым пайщик признаётся «своим» для поля.
@@ -747,6 +748,15 @@ interface IRegistryExtension {
      * расширения, которое своих таблиц не держит, — нормальное состояние.
      */
     entities?: ReadonlyArray<new (...args: any[]) => any>;
+    /**
+     * Миграции таблиц расширения — классы миграций TypeORM.
+     *
+     * Схему базы меняют только миграции: добавил или поменял колонку в сущности
+     * из `entities` — положи рядом миграцию (`pnpm schema:generate`). Порядок
+     * задаёт метка времени в имени класса, общая лента с миграциями ядра.
+     * Не путать с `migrations` ниже — те переводят конфиг расширения.
+     */
+    databaseMigrations?: ReadonlyArray<new () => MigrationInterface>;
     /**
      * Миграции схемы конфига расширения — в порядке применения.
      *
@@ -935,6 +945,46 @@ declare function extensionEntities(): ReadonlyArray<ExtensionEntityClass>;
 /** Сбросить состав. Только для тестов, которые поднимают граф модулей заново. */
 declare function resetExtensionEntities(): void;
 
+/**
+ * Миграции таблиц установленных расширений — то, что контроллер отдаёт TypeORM
+ * вместе с миграциями ядра.
+ *
+ * Схему базы меняют только миграции: `synchronize` выключен, потому что он молча
+ * удаляет колонки, которых нет в сущности, и превращает переименование в потерю
+ * данных. Таблицы расширения описывает оно само — списком `databaseMigrations`
+ * в записи реестра, — и файлы миграций лежат в его каталоге: расширение,
+ * вынесенное из монолита, уносит историю своих таблиц с собой.
+ *
+ * Порядок применения задаёт метка времени в имени класса (так TypeORM сортирует
+ * миграции), поэтому миграции ядра и расширений идут одной лентой.
+ *
+ * Список задаётся один раз, до инициализации подключения, — как и состав
+ * сущностей (`registerExtensionEntities`).
+ */
+type ExtensionDatabaseMigrationClass = new () => MigrationInterface;
+/** Объявить миграции таблиц установленных расширений. Вызывает composition root. */
+declare function registerExtensionDatabaseMigrations(list: ReadonlyArray<ExtensionDatabaseMigrationClass>): void;
+/**
+ * Прочитать миграции таблиц расширений.
+ *
+ * До объявления возвращает пустой список: подключение к базе поднимается и в
+ * контурах без единого расширения.
+ */
+declare function extensionDatabaseMigrations(): ReadonlyArray<ExtensionDatabaseMigrationClass>;
+/** Сбросить список. Только для тестов, которые поднимают граф модулей заново. */
+declare function resetExtensionDatabaseMigrations(): void;
+
+/**
+ * Допустимое поле сортировки: имя из латиницы, цифр и подчёркивания и, по
+ * желанию, направление через двоеточие (`created_at:desc` — так сортирует
+ * реестр пайщиков, репозиторий пользователей разбирает пару сам). Поле уходит
+ * в `ORDER BY` строкой, и любой другой символ открывал бы подстановку SQL.
+ * Какая именно колонка разрешена, решает репозиторий по своему списку или
+ * метаданным сущности (`resolveSortColumn`); здесь отсекается всё, что именем
+ * колонки быть не может. Пустая строка — «без сортировки»: её отдаёт таблица
+ * со снятой сортировкой, и репозитории берут порядок по умолчанию.
+ */
+declare const SORT_FIELD_PATTERN: RegExp;
 /**
  * Входные параметры для пагинации и сортировки
  */
@@ -1060,14 +1110,6 @@ interface PlatformBlockchainSettings {
     rootSymbol: string;
     /** Точность системного токена — знаков после запятой. */
     rootPrecision: number;
-    /**
-     * Пауза перед чтением таблиц цепи сразу после успешной мутации, мс.
-     *
-     * На узле-последователе строка появляется в состоянии с задержкой
-     * относительно ответа RPC, и величина этой задержки зависит от узла контура,
-     * а не от расширения.
-     */
-    postTransactChainReadDelayMs: number;
     /**
      * Идентификатор цепи контура. Входит в подписываемую транзакцию, поэтому
      * подпись, собранная для одной цепи, в другой недействительна — расширение
@@ -1274,6 +1316,16 @@ declare class DomainToBlockchainUtils {
     static getEmptyHash(): string;
 }
 
+/** sha256 текста в UTF-8; пустой текст остаётся пустой строкой. */
+declare function chainTextDigest(text: string | null | undefined): string;
+/** Значение из цепи — хеш текста, а не сам текст. */
+declare function isChainTextDigest(value: string | null | undefined): value is string;
+/**
+ * Значение поля из цепи для записи в базу: хеш текст в базе не заменяет.
+ * Строки, записанные до выноса текстов, несут сам текст и копируются как раньше.
+ */
+declare function resolveChainText(chainValue: string, current: string | null | undefined): string;
+
 /**
  * Утилиты для работы с ассетами в формате "AMOUNT SYMBOL" (например, "100.0000 RUB")
  */
@@ -1444,11 +1496,27 @@ declare class DateUtils {
     static formatDurationHumanizeRu(minutes: number): string;
 }
 
+/** Источник событий: подписка и отписка (EventEmitter2, EventEmitter). */
+interface EventSource {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off(event: string, listener: (...args: any[]) => void): unknown;
+}
+interface EventWait<T> {
+    /** Событие, прошедшее отбор, либо `null` по пределу или отмене. */
+    promise: Promise<T | null>;
+    /** Снять ожидание досрочно (факт уже виден без события). */
+    cancel(): void;
+}
 /**
- * Пауза перед чтением таблиц блокчейна сразу после успешной мутации (push_transaction).
- * На узле-последователе строка может появиться в chain state с задержкой относительно ответа RPC.
+ * Дождаться события, а не опрашивать базу. Для случаев, когда ответ зависит
+ * от чужого факта — робот совета решил, обратный вызов перевёл сагу: свой
+ * блок транзакция дожидается сама, а чужое действие приходит событием.
+ *
+ * Порядок у вызывающего: сначала `waitForEvent`, потом одно чтение текущего
+ * состояния — если факт уже случился, `cancel()` и ответ сразу; так событие
+ * между чтением и подпиской не теряется. Подписка снимается при любом исходе.
  */
-declare function waitAfterTransactBeforeChainTableRead(): Promise<void>;
+declare function waitForEvent<T>(source: EventSource, event: string, match: (payload: T) => boolean, timeoutMs: number): EventWait<T>;
 
 /**
  * Форма ответа, из которой берётся номер блока. Описана здесь, а не взята из
@@ -1528,7 +1596,7 @@ declare class CurrencyValidationUtil {
     /**
      * Форматирует сумму с правильным символом валюты
      * @param value Числовое значение
-     * @param precision Количество знаков после запятой (по умолчанию из конфига)
+     * @param precision Количество знаков после запятой (по умолчанию из настроек платформы)
      * @returns string - отформатированная сумма
      */
     static formatAmount(value: number, precision?: number): string;
@@ -1549,6 +1617,20 @@ declare class CurrencyValidationUtil {
  */
 declare function sanitizeUserText<T extends string | null | undefined>(value: T): T;
 
+/**
+ * Имя поля сортировки приходит от клиента и подставляется в `ORDER BY` строкой:
+ * TypeORM вставляет его в SQL как есть, без параметров и экранирования. Поэтому
+ * произвольную строку туда пускать нельзя. Разрешённый набор берём из
+ * метаданных сущности: колонка, которой нет в таблице, молча заменяется на
+ * умолчание — список не должен падать из-за устаревшей ссылки в клиенте.
+ *
+ * @param repository — репозиторий сущности, по чьим колонкам сортируем.
+ * @param sortBy — имя поля от клиента.
+ * @param fallback — колонка по умолчанию.
+ * @returns Имя существующей колонки сущности.
+ */
+declare function resolveSortColumn<T extends ObjectLiteral>(repository: Repository<T>, sortBy: string | undefined, fallback: string): string;
+
 /**
  * Ошибка API с кодом состояния HTTP.
  *
@@ -1565,6 +1647,21 @@ declare class HttpApiError extends HttpException {
     constructor(statusCode: HttpStatus, message: string, isOperational?: boolean, stack?: string, subcode?: any);
 }
 
+/**
+ * Разбор отказа контракта. Контракт пишет причину как `КОД: текст`
+ * (`GATEWAY_OUTCOME_NOT_FOUND: Объект возврата не существует…`); старые
+ * отказы — одним текстом, без кода.
+ */
+declare function parseChainAssert(message: string): {
+    code?: string;
+    text: string;
+};
+/**
+ * Код отказа контракта — из DomainError, в который отказ уже превращён,
+ * или из сырой ошибки цепи. Отказ без кода — undefined. Сравнивать отказы
+ * контракта — по этому коду, а не по тексту: текст переводится и правится.
+ */
+declare function chainErrorCode(error: unknown): string | undefined;
 /**
  * Пробросить отказ цепи человеку.
  *
@@ -1572,8 +1669,69 @@ declare class HttpApiError extends HttpException {
  * message: ...`; пайщику нужна причина, а не обёртка виртуальной машины.
  * Живёт в каркасе, потому что в цепь ходит не одно расширение: вторая копия
  * этой чистки разошлась бы с первой на первом же новом формате ошибки.
+ *
+ * Отказ с кодом (`КОД: текст`) уходит с этим кодом, текст — из словаря,
+ * а без записи в словаре — текст контракта. Отказ без кода — `CHAIN_ASSERT`,
+ * прочий сбой цепи — `CHAIN_ERROR`, текст — параметром `message`.
  */
 declare function rethrowChainError(error: unknown): never;
 
-export { ActiveUserStatusGuard, AmountFormatterUtils, AssetUtils, AuthRoles, BaseExtensionModule, BucketRegistry, CandidateFilterInputDTO, CandidateOutputDTO, CandidateStatus, CurrencyValidationUtil, CurrentUser, DEFAULT_DOCUMENT_VERSION, DateUtils, DocumentAggregateDTO, DomainToBlockchainUtils, EMPTY_HASH, EXTENSION_APP_TERMINATE_EVENT, EXTENSION_REPOSITORY, EXTENSION_SECRET_SET, EXTENSION_SECRET_UNSET, ExpenseProposalStatementGenerateDocumentInputDTO, ExpenseProposalStatementSignedDocumentInputDTO, ExpenseProposalStatementSignedMetaDocumentInputDTO, ExtensionAvailability, ExtensionConfigSuppliedBy, ExtensionDomainEntity, GenerateDocumentInputDTO, GenerateDocumentOptionsInputDTO, GenerateMetaDocumentInputDTO, GeneratedDocumentDTO, GqlJwtAuthGuard, HttpApiError, HttpJwtAuthGuard, IPNProvider, InjectBucket, LOG_EXTENSION_REPOSITORY, LangType, LogExtensionDomainEntity, MetaDocumentInputDTO, ONBOARDING_EXPIRY_DAYS, ONBOARDING_EXPIRY_MS, OptionalCurrentUser, OptionalGqlJwtAuthGuard, PaginationInputDTO, PaginationResult, PaginationUtils, PaymentProvider, PollingProvider, QuantityUtils, ROLES_ANY_STATUS_KEY, ROLES_DENY_SELF_KEY, RolesGuard, SignatureInfoDTO, SignatureInfoInputDTO, SignedDigitalDocumentDTO, SignedDigitalDocumentInputDTO, TransactionDTO, UseBucket, bucketProvidersFor, bucketTokenFor, buildPaginationResult, checkPaymentAmount, checkPaymentSymbol, computeOnboardingExpiresAt, configureExtensionAuth, configurePlatformSettings, createPaginationResult, extensionEntities, generateHashFromString, generateRandomHash, generateUniqueHash, getAmountPlusFee, getAppliedBlockNum, hasServerSecret, isExtensionAvailable, mergeSecretConfig, paginationInputToOffset, platformSettings, providerSuppliedPaths, redactSecretConfig, registerExtensionEntities, resetExtensionEntities, rethrowChainError, sanitizeUserText, verifySignedDocumentAgainstStoredDraft, waitAfterTransactBeforeChainTableRead };
-export type { AuthRolesOptions, BucketSource, BucketSpec, DeserializedDescriptionOfExtension, ExcludeCommonProps, ExtensionAppTerminatePayload, ExtensionAuthOptions, ExtensionConfigFieldPolicy, ExtensionConfigPolicy, ExtensionDomainInterface, ExtensionDomainRepository, ExtensionEntityClass, ExtensionSchemaMigrationAfterContext, GeneratedDocumentDomainInterface, GeneratedDocumentDraft, IDesktopConfig, IExtensionSchemaMigration, IRegistryExtension, IResolvedRegistryExtension, LoadGeneratedDocumentByDocHash, LogExtensionDomainInterface, LogExtensionDomainRepository, LogExtensionFilter, LogExtensionPaginationOptions, LogExtensionPaginationResult, PaymentDetails, PlatformBlockchainSettings, PlatformSettings, RegisteredBucket, RequireFields, SignedDocumentMetaCompareMode, SignedDocumentMetaVerification, SignedDocumentToVerify, TransactResultWithResponse };
+type DomainErrorParams = Record<string, string | number | boolean | null | undefined>;
+interface Branded {
+    code: string;
+    params: DomainErrorParams;
+}
+/**
+ * Текст отказа на языке текущего запроса. Кода нет в словаре, но есть
+ * исходный текст (`params.message` — так приходит отказ контракта с кодом,
+ * ещё не заведённым в словарь) — показывается он, а не ключ.
+ */
+declare function domainErrorMessage(code: string, params?: DomainErrorParams): string;
+/**
+ * Отказ, который видит пайщик: код + параметры, текст — из словаря.
+ *
+ * Код — `SCREAMING_SNAKE` с префиксом области (`CAPITAL_ISSUE_NOT_FOUND`),
+ * сообщение — по ключу `errors.<КОД>` в словаре ядра или расширения.
+ * `message` переводится при создании на язык текущего запроса (для журнала и
+ * старого кода, читающего `error.message`); ответ клиенту фильтр ошибок
+ * переводит заново на язык запроса и кладёт код в `extensions.code`,
+ * параметры — в `extensions.params`.
+ *
+ * Бросать через фабрики по смыслу отказа:
+ *   throw DomainError.notFound('FREE_DECISION_DOCUMENT_NOT_FOUND');
+ *   throw DomainError.badRequest('WALLET_AMOUNT_TOO_SMALL', { min: '100,00 RUB' });
+ */
+declare class DomainError extends HttpException implements Branded {
+    code: string;
+    params: DomainErrorParams;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(code: string, params?: DomainErrorParams, status?: HttpStatus);
+    /** Ключ сообщения в словаре. */
+    get messageKey(): string;
+    static badRequest(code: string, params?: DomainErrorParams): DomainError;
+    static unauthorized(code: string, params?: DomainErrorParams): DomainError;
+    static forbidden(code: string, params?: DomainErrorParams): DomainError;
+    static notFound(code: string, params?: DomainErrorParams): DomainError;
+    static conflict(code: string, params?: DomainErrorParams): DomainError;
+    static unprocessable(code: string, params?: DomainErrorParams): DomainError;
+    static tooManyRequests(code: string, params?: DomainErrorParams): DomainError;
+    static internal(code: string, params?: DomainErrorParams): DomainError;
+    static badGateway(code: string, params?: DomainErrorParams): DomainError;
+    static serviceUnavailable(code: string, params?: DomainErrorParams): DomainError;
+}
+/**
+ * Сообщение для class-validator по ключу словаря. Переводится в момент
+ * проверки — на язык запроса, а не при загрузке модуля:
+ *
+ *   @IsNotEmpty({ message: validationMessage('validation.required') })
+ *
+ * В параметры сообщения попадают `property` (имя поля) и `value`.
+ */
+declare function validationMessage(key: string, params?: DomainErrorParams): (args: {
+    property: string;
+    value?: unknown;
+    constraints?: unknown[];
+}) => string;
+
+export { ActiveUserStatusGuard, AmountFormatterUtils, AssetUtils, AuthRoles, BaseExtensionModule, BucketRegistry, CandidateFilterInputDTO, CandidateOutputDTO, CandidateStatus, CurrencyValidationUtil, CurrentUser, DEFAULT_DOCUMENT_VERSION, DateUtils, DocumentAggregateDTO, DomainError, DomainToBlockchainUtils, EMPTY_HASH, EXTENSION_APP_TERMINATE_EVENT, EXTENSION_REPOSITORY, EXTENSION_SECRET_SET, EXTENSION_SECRET_UNSET, ExpenseProposalStatementGenerateDocumentInputDTO, ExpenseProposalStatementSignedDocumentInputDTO, ExpenseProposalStatementSignedMetaDocumentInputDTO, ExtensionAvailability, ExtensionConfigSuppliedBy, ExtensionDomainEntity, GenerateDocumentInputDTO, GenerateDocumentOptionsInputDTO, GenerateMetaDocumentInputDTO, GeneratedDocumentDTO, GqlJwtAuthGuard, HttpApiError, HttpJwtAuthGuard, IPNProvider, InjectBucket, LOG_EXTENSION_REPOSITORY, LangType, LogExtensionDomainEntity, MetaDocumentInputDTO, ONBOARDING_EXPIRY_DAYS, ONBOARDING_EXPIRY_MS, OptionalCurrentUser, OptionalGqlJwtAuthGuard, PaginationInputDTO, PaginationResult, PaginationUtils, PaymentProvider, PollingProvider, QuantityUtils, ROLES_ANY_STATUS_KEY, ROLES_DENY_SELF_KEY, RolesGuard, SORT_FIELD_PATTERN, SignatureInfoDTO, SignatureInfoInputDTO, SignedDigitalDocumentDTO, SignedDigitalDocumentInputDTO, TransactionDTO, UseBucket, bucketProvidersFor, bucketTokenFor, buildPaginationResult, chainErrorCode, chainTextDigest, checkPaymentAmount, checkPaymentSymbol, computeOnboardingExpiresAt, configureExtensionAuth, configurePlatformSettings, createPaginationResult, domainErrorMessage, extensionDatabaseMigrations, extensionEntities, generateHashFromString, generateRandomHash, generateUniqueHash, getAmountPlusFee, getAppliedBlockNum, hasServerSecret, isChainTextDigest, isExtensionAvailable, mergeSecretConfig, paginationInputToOffset, parseChainAssert, platformSettings, providerSuppliedPaths, redactSecretConfig, registerExtensionDatabaseMigrations, registerExtensionEntities, resetExtensionDatabaseMigrations, resetExtensionEntities, resolveChainText, resolveSortColumn, rethrowChainError, sanitizeUserText, validationMessage, verifySignedDocumentAgainstStoredDraft, waitForEvent };
+export type { AuthRolesOptions, BucketSource, BucketSpec, DeserializedDescriptionOfExtension, DomainErrorParams, EventSource, EventWait, ExcludeCommonProps, ExtensionAppTerminatePayload, ExtensionAuthOptions, ExtensionConfigFieldPolicy, ExtensionConfigPolicy, ExtensionDatabaseMigrationClass, ExtensionDomainInterface, ExtensionDomainRepository, ExtensionEntityClass, ExtensionSchemaMigrationAfterContext, GeneratedDocumentDomainInterface, GeneratedDocumentDraft, IDesktopConfig, IExtensionSchemaMigration, IRegistryExtension, IResolvedRegistryExtension, LoadGeneratedDocumentByDocHash, LogExtensionDomainInterface, LogExtensionDomainRepository, LogExtensionFilter, LogExtensionPaginationOptions, LogExtensionPaginationResult, PaymentDetails, PlatformBlockchainSettings, PlatformSettings, RegisteredBucket, RequireFields, SignedDocumentMetaCompareMode, SignedDocumentMetaVerification, SignedDocumentToVerify, TransactResultWithResponse };

package/dist/index.d.mts

@@ -5,6 +5,7 @@ import { Reflector } from '@nestjs/core';
 import { Observable } from 'rxjs';
 import { ZodObject } from 'zod';
 import { Cooperative } from 'cooptypes';
+import { MigrationInterface, ObjectLiteral, Repository } from 'typeorm';
 
 /**
  * Пути внутри объекта, по которым пайщик признаётся «своим» для поля.
@@ -747,6 +748,15 @@ interface IRegistryExtension {
      * расширения, которое своих таблиц не держит, — нормальное состояние.
      */
     entities?: ReadonlyArray<new (...args: any[]) => any>;
+    /**
+     * Миграции таблиц расширения — классы миграций TypeORM.
+     *
+     * Схему базы меняют только миграции: добавил или поменял колонку в сущности
+     * из `entities` — положи рядом миграцию (`pnpm schema:generate`). Порядок
+     * задаёт метка времени в имени класса, общая лента с миграциями ядра.
+     * Не путать с `migrations` ниже — те переводят конфиг расширения.
+     */
+    databaseMigrations?: ReadonlyArray<new () => MigrationInterface>;
     /**
      * Миграции схемы конфига расширения — в порядке применения.
      *
@@ -935,6 +945,46 @@ declare function extensionEntities(): ReadonlyArray<ExtensionEntityClass>;
 /** Сбросить состав. Только для тестов, которые поднимают граф модулей заново. */
 declare function resetExtensionEntities(): void;
 
+/**
+ * Миграции таблиц установленных расширений — то, что контроллер отдаёт TypeORM
+ * вместе с миграциями ядра.
+ *
+ * Схему базы меняют только миграции: `synchronize` выключен, потому что он молча
+ * удаляет колонки, которых нет в сущности, и превращает переименование в потерю
+ * данных. Таблицы расширения описывает оно само — списком `databaseMigrations`
+ * в записи реестра, — и файлы миграций лежат в его каталоге: расширение,
+ * вынесенное из монолита, уносит историю своих таблиц с собой.
+ *
+ * Порядок применения задаёт метка времени в имени класса (так TypeORM сортирует
+ * миграции), поэтому миграции ядра и расширений идут одной лентой.
+ *
+ * Список задаётся один раз, до инициализации подключения, — как и состав
+ * сущностей (`registerExtensionEntities`).
+ */
+type ExtensionDatabaseMigrationClass = new () => MigrationInterface;
+/** Объявить миграции таблиц установленных расширений. Вызывает composition root. */
+declare function registerExtensionDatabaseMigrations(list: ReadonlyArray<ExtensionDatabaseMigrationClass>): void;
+/**
+ * Прочитать миграции таблиц расширений.
+ *
+ * До объявления возвращает пустой список: подключение к базе поднимается и в
+ * контурах без единого расширения.
+ */
+declare function extensionDatabaseMigrations(): ReadonlyArray<ExtensionDatabaseMigrationClass>;
+/** Сбросить список. Только для тестов, которые поднимают граф модулей заново. */
+declare function resetExtensionDatabaseMigrations(): void;
+
+/**
+ * Допустимое поле сортировки: имя из латиницы, цифр и подчёркивания и, по
+ * желанию, направление через двоеточие (`created_at:desc` — так сортирует
+ * реестр пайщиков, репозиторий пользователей разбирает пару сам). Поле уходит
+ * в `ORDER BY` строкой, и любой другой символ открывал бы подстановку SQL.
+ * Какая именно колонка разрешена, решает репозиторий по своему списку или
+ * метаданным сущности (`resolveSortColumn`); здесь отсекается всё, что именем
+ * колонки быть не может. Пустая строка — «без сортировки»: её отдаёт таблица
+ * со снятой сортировкой, и репозитории берут порядок по умолчанию.
+ */
+declare const SORT_FIELD_PATTERN: RegExp;
 /**
  * Входные параметры для пагинации и сортировки
  */
@@ -1060,14 +1110,6 @@ interface PlatformBlockchainSettings {
     rootSymbol: string;
     /** Точность системного токена — знаков после запятой. */
     rootPrecision: number;
-    /**
-     * Пауза перед чтением таблиц цепи сразу после успешной мутации, мс.
-     *
-     * На узле-последователе строка появляется в состоянии с задержкой
-     * относительно ответа RPC, и величина этой задержки зависит от узла контура,
-     * а не от расширения.
-     */
-    postTransactChainReadDelayMs: number;
     /**
      * Идентификатор цепи контура. Входит в подписываемую транзакцию, поэтому
      * подпись, собранная для одной цепи, в другой недействительна — расширение
@@ -1274,6 +1316,16 @@ declare class DomainToBlockchainUtils {
     static getEmptyHash(): string;
 }
 
+/** sha256 текста в UTF-8; пустой текст остаётся пустой строкой. */
+declare function chainTextDigest(text: string | null | undefined): string;
+/** Значение из цепи — хеш текста, а не сам текст. */
+declare function isChainTextDigest(value: string | null | undefined): value is string;
+/**
+ * Значение поля из цепи для записи в базу: хеш текст в базе не заменяет.
+ * Строки, записанные до выноса текстов, несут сам текст и копируются как раньше.
+ */
+declare function resolveChainText(chainValue: string, current: string | null | undefined): string;
+
 /**
  * Утилиты для работы с ассетами в формате "AMOUNT SYMBOL" (например, "100.0000 RUB")
  */
@@ -1444,11 +1496,27 @@ declare class DateUtils {
     static formatDurationHumanizeRu(minutes: number): string;
 }
 
+/** Источник событий: подписка и отписка (EventEmitter2, EventEmitter). */
+interface EventSource {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off(event: string, listener: (...args: any[]) => void): unknown;
+}
+interface EventWait<T> {
+    /** Событие, прошедшее отбор, либо `null` по пределу или отмене. */
+    promise: Promise<T | null>;
+    /** Снять ожидание досрочно (факт уже виден без события). */
+    cancel(): void;
+}
 /**
- * Пауза перед чтением таблиц блокчейна сразу после успешной мутации (push_transaction).
- * На узле-последователе строка может появиться в chain state с задержкой относительно ответа RPC.
+ * Дождаться события, а не опрашивать базу. Для случаев, когда ответ зависит
+ * от чужого факта — робот совета решил, обратный вызов перевёл сагу: свой
+ * блок транзакция дожидается сама, а чужое действие приходит событием.
+ *
+ * Порядок у вызывающего: сначала `waitForEvent`, потом одно чтение текущего
+ * состояния — если факт уже случился, `cancel()` и ответ сразу; так событие
+ * между чтением и подпиской не теряется. Подписка снимается при любом исходе.
  */
-declare function waitAfterTransactBeforeChainTableRead(): Promise<void>;
+declare function waitForEvent<T>(source: EventSource, event: string, match: (payload: T) => boolean, timeoutMs: number): EventWait<T>;
 
 /**
  * Форма ответа, из которой берётся номер блока. Описана здесь, а не взята из
@@ -1528,7 +1596,7 @@ declare class CurrencyValidationUtil {
     /**
      * Форматирует сумму с правильным символом валюты
      * @param value Числовое значение
-     * @param precision Количество знаков после запятой (по умолчанию из конфига)
+     * @param precision Количество знаков после запятой (по умолчанию из настроек платформы)
      * @returns string - отформатированная сумма
      */
     static formatAmount(value: number, precision?: number): string;
@@ -1549,6 +1617,20 @@ declare class CurrencyValidationUtil {
  */
 declare function sanitizeUserText<T extends string | null | undefined>(value: T): T;
 
+/**
+ * Имя поля сортировки приходит от клиента и подставляется в `ORDER BY` строкой:
+ * TypeORM вставляет его в SQL как есть, без параметров и экранирования. Поэтому
+ * произвольную строку туда пускать нельзя. Разрешённый набор берём из
+ * метаданных сущности: колонка, которой нет в таблице, молча заменяется на
+ * умолчание — список не должен падать из-за устаревшей ссылки в клиенте.
+ *
+ * @param repository — репозиторий сущности, по чьим колонкам сортируем.
+ * @param sortBy — имя поля от клиента.
+ * @param fallback — колонка по умолчанию.
+ * @returns Имя существующей колонки сущности.
+ */
+declare function resolveSortColumn<T extends ObjectLiteral>(repository: Repository<T>, sortBy: string | undefined, fallback: string): string;
+
 /**
  * Ошибка API с кодом состояния HTTP.
  *
@@ -1565,6 +1647,21 @@ declare class HttpApiError extends HttpException {
     constructor(statusCode: HttpStatus, message: string, isOperational?: boolean, stack?: string, subcode?: any);
 }
 
+/**
+ * Разбор отказа контракта. Контракт пишет причину как `КОД: текст`
+ * (`GATEWAY_OUTCOME_NOT_FOUND: Объект возврата не существует…`); старые
+ * отказы — одним текстом, без кода.
+ */
+declare function parseChainAssert(message: string): {
+    code?: string;
+    text: string;
+};
+/**
+ * Код отказа контракта — из DomainError, в который отказ уже превращён,
+ * или из сырой ошибки цепи. Отказ без кода — undefined. Сравнивать отказы
+ * контракта — по этому коду, а не по тексту: текст переводится и правится.
+ */
+declare function chainErrorCode(error: unknown): string | undefined;
 /**
  * Пробросить отказ цепи человеку.
  *
@@ -1572,8 +1669,69 @@ declare class HttpApiError extends HttpException {
  * message: ...`; пайщику нужна причина, а не обёртка виртуальной машины.
  * Живёт в каркасе, потому что в цепь ходит не одно расширение: вторая копия
  * этой чистки разошлась бы с первой на первом же новом формате ошибки.
+ *
+ * Отказ с кодом (`КОД: текст`) уходит с этим кодом, текст — из словаря,
+ * а без записи в словаре — текст контракта. Отказ без кода — `CHAIN_ASSERT`,
+ * прочий сбой цепи — `CHAIN_ERROR`, текст — параметром `message`.
  */
 declare function rethrowChainError(error: unknown): never;
 
-export { ActiveUserStatusGuard, AmountFormatterUtils, AssetUtils, AuthRoles, BaseExtensionModule, BucketRegistry, CandidateFilterInputDTO, CandidateOutputDTO, CandidateStatus, CurrencyValidationUtil, CurrentUser, DEFAULT_DOCUMENT_VERSION, DateUtils, DocumentAggregateDTO, DomainToBlockchainUtils, EMPTY_HASH, EXTENSION_APP_TERMINATE_EVENT, EXTENSION_REPOSITORY, EXTENSION_SECRET_SET, EXTENSION_SECRET_UNSET, ExpenseProposalStatementGenerateDocumentInputDTO, ExpenseProposalStatementSignedDocumentInputDTO, ExpenseProposalStatementSignedMetaDocumentInputDTO, ExtensionAvailability, ExtensionConfigSuppliedBy, ExtensionDomainEntity, GenerateDocumentInputDTO, GenerateDocumentOptionsInputDTO, GenerateMetaDocumentInputDTO, GeneratedDocumentDTO, GqlJwtAuthGuard, HttpApiError, HttpJwtAuthGuard, IPNProvider, InjectBucket, LOG_EXTENSION_REPOSITORY, LangType, LogExtensionDomainEntity, MetaDocumentInputDTO, ONBOARDING_EXPIRY_DAYS, ONBOARDING_EXPIRY_MS, OptionalCurrentUser, OptionalGqlJwtAuthGuard, PaginationInputDTO, PaginationResult, PaginationUtils, PaymentProvider, PollingProvider, QuantityUtils, ROLES_ANY_STATUS_KEY, ROLES_DENY_SELF_KEY, RolesGuard, SignatureInfoDTO, SignatureInfoInputDTO, SignedDigitalDocumentDTO, SignedDigitalDocumentInputDTO, TransactionDTO, UseBucket, bucketProvidersFor, bucketTokenFor, buildPaginationResult, checkPaymentAmount, checkPaymentSymbol, computeOnboardingExpiresAt, configureExtensionAuth, configurePlatformSettings, createPaginationResult, extensionEntities, generateHashFromString, generateRandomHash, generateUniqueHash, getAmountPlusFee, getAppliedBlockNum, hasServerSecret, isExtensionAvailable, mergeSecretConfig, paginationInputToOffset, platformSettings, providerSuppliedPaths, redactSecretConfig, registerExtensionEntities, resetExtensionEntities, rethrowChainError, sanitizeUserText, verifySignedDocumentAgainstStoredDraft, waitAfterTransactBeforeChainTableRead };
-export type { AuthRolesOptions, BucketSource, BucketSpec, DeserializedDescriptionOfExtension, ExcludeCommonProps, ExtensionAppTerminatePayload, ExtensionAuthOptions, ExtensionConfigFieldPolicy, ExtensionConfigPolicy, ExtensionDomainInterface, ExtensionDomainRepository, ExtensionEntityClass, ExtensionSchemaMigrationAfterContext, GeneratedDocumentDomainInterface, GeneratedDocumentDraft, IDesktopConfig, IExtensionSchemaMigration, IRegistryExtension, IResolvedRegistryExtension, LoadGeneratedDocumentByDocHash, LogExtensionDomainInterface, LogExtensionDomainRepository, LogExtensionFilter, LogExtensionPaginationOptions, LogExtensionPaginationResult, PaymentDetails, PlatformBlockchainSettings, PlatformSettings, RegisteredBucket, RequireFields, SignedDocumentMetaCompareMode, SignedDocumentMetaVerification, SignedDocumentToVerify, TransactResultWithResponse };
+type DomainErrorParams = Record<string, string | number | boolean | null | undefined>;
+interface Branded {
+    code: string;
+    params: DomainErrorParams;
+}
+/**
+ * Текст отказа на языке текущего запроса. Кода нет в словаре, но есть
+ * исходный текст (`params.message` — так приходит отказ контракта с кодом,
+ * ещё не заведённым в словарь) — показывается он, а не ключ.
+ */
+declare function domainErrorMessage(code: string, params?: DomainErrorParams): string;
+/**
+ * Отказ, который видит пайщик: код + параметры, текст — из словаря.
+ *
+ * Код — `SCREAMING_SNAKE` с префиксом области (`CAPITAL_ISSUE_NOT_FOUND`),
+ * сообщение — по ключу `errors.<КОД>` в словаре ядра или расширения.
+ * `message` переводится при создании на язык текущего запроса (для журнала и
+ * старого кода, читающего `error.message`); ответ клиенту фильтр ошибок
+ * переводит заново на язык запроса и кладёт код в `extensions.code`,
+ * параметры — в `extensions.params`.
+ *
+ * Бросать через фабрики по смыслу отказа:
+ *   throw DomainError.notFound('FREE_DECISION_DOCUMENT_NOT_FOUND');
+ *   throw DomainError.badRequest('WALLET_AMOUNT_TOO_SMALL', { min: '100,00 RUB' });
+ */
+declare class DomainError extends HttpException implements Branded {
+    code: string;
+    params: DomainErrorParams;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(code: string, params?: DomainErrorParams, status?: HttpStatus);
+    /** Ключ сообщения в словаре. */
+    get messageKey(): string;
+    static badRequest(code: string, params?: DomainErrorParams): DomainError;
+    static unauthorized(code: string, params?: DomainErrorParams): DomainError;
+    static forbidden(code: string, params?: DomainErrorParams): DomainError;
+    static notFound(code: string, params?: DomainErrorParams): DomainError;
+    static conflict(code: string, params?: DomainErrorParams): DomainError;
+    static unprocessable(code: string, params?: DomainErrorParams): DomainError;
+    static tooManyRequests(code: string, params?: DomainErrorParams): DomainError;
+    static internal(code: string, params?: DomainErrorParams): DomainError;
+    static badGateway(code: string, params?: DomainErrorParams): DomainError;
+    static serviceUnavailable(code: string, params?: DomainErrorParams): DomainError;
+}
+/**
+ * Сообщение для class-validator по ключу словаря. Переводится в момент
+ * проверки — на язык запроса, а не при загрузке модуля:
+ *
+ *   @IsNotEmpty({ message: validationMessage('validation.required') })
+ *
+ * В параметры сообщения попадают `property` (имя поля) и `value`.
+ */
+declare function validationMessage(key: string, params?: DomainErrorParams): (args: {
+    property: string;
+    value?: unknown;
+    constraints?: unknown[];
+}) => string;
+
+export { ActiveUserStatusGuard, AmountFormatterUtils, AssetUtils, AuthRoles, BaseExtensionModule, BucketRegistry, CandidateFilterInputDTO, CandidateOutputDTO, CandidateStatus, CurrencyValidationUtil, CurrentUser, DEFAULT_DOCUMENT_VERSION, DateUtils, DocumentAggregateDTO, DomainError, DomainToBlockchainUtils, EMPTY_HASH, EXTENSION_APP_TERMINATE_EVENT, EXTENSION_REPOSITORY, EXTENSION_SECRET_SET, EXTENSION_SECRET_UNSET, ExpenseProposalStatementGenerateDocumentInputDTO, ExpenseProposalStatementSignedDocumentInputDTO, ExpenseProposalStatementSignedMetaDocumentInputDTO, ExtensionAvailability, ExtensionConfigSuppliedBy, ExtensionDomainEntity, GenerateDocumentInputDTO, GenerateDocumentOptionsInputDTO, GenerateMetaDocumentInputDTO, GeneratedDocumentDTO, GqlJwtAuthGuard, HttpApiError, HttpJwtAuthGuard, IPNProvider, InjectBucket, LOG_EXTENSION_REPOSITORY, LangType, LogExtensionDomainEntity, MetaDocumentInputDTO, ONBOARDING_EXPIRY_DAYS, ONBOARDING_EXPIRY_MS, OptionalCurrentUser, OptionalGqlJwtAuthGuard, PaginationInputDTO, PaginationResult, PaginationUtils, PaymentProvider, PollingProvider, QuantityUtils, ROLES_ANY_STATUS_KEY, ROLES_DENY_SELF_KEY, RolesGuard, SORT_FIELD_PATTERN, SignatureInfoDTO, SignatureInfoInputDTO, SignedDigitalDocumentDTO, SignedDigitalDocumentInputDTO, TransactionDTO, UseBucket, bucketProvidersFor, bucketTokenFor, buildPaginationResult, chainErrorCode, chainTextDigest, checkPaymentAmount, checkPaymentSymbol, computeOnboardingExpiresAt, configureExtensionAuth, configurePlatformSettings, createPaginationResult, domainErrorMessage, extensionDatabaseMigrations, extensionEntities, generateHashFromString, generateRandomHash, generateUniqueHash, getAmountPlusFee, getAppliedBlockNum, hasServerSecret, isChainTextDigest, isExtensionAvailable, mergeSecretConfig, paginationInputToOffset, parseChainAssert, platformSettings, providerSuppliedPaths, redactSecretConfig, registerExtensionDatabaseMigrations, registerExtensionEntities, resetExtensionDatabaseMigrations, resetExtensionEntities, resolveChainText, resolveSortColumn, rethrowChainError, sanitizeUserText, validationMessage, verifySignedDocumentAgainstStoredDraft, waitForEvent };
+export type { AuthRolesOptions, BucketSource, BucketSpec, DeserializedDescriptionOfExtension, DomainErrorParams, EventSource, EventWait, ExcludeCommonProps, ExtensionAppTerminatePayload, ExtensionAuthOptions, ExtensionConfigFieldPolicy, ExtensionConfigPolicy, ExtensionDatabaseMigrationClass, ExtensionDomainInterface, ExtensionDomainRepository, ExtensionEntityClass, ExtensionSchemaMigrationAfterContext, GeneratedDocumentDomainInterface, GeneratedDocumentDraft, IDesktopConfig, IExtensionSchemaMigration, IRegistryExtension, IResolvedRegistryExtension, LoadGeneratedDocumentByDocHash, LogExtensionDomainInterface, LogExtensionDomainRepository, LogExtensionFilter, LogExtensionPaginationOptions, LogExtensionPaginationResult, PaymentDetails, PlatformBlockchainSettings, PlatformSettings, RegisteredBucket, RequireFields, SignedDocumentMetaCompareMode, SignedDocumentMetaVerification, SignedDocumentToVerify, TransactResultWithResponse };