@coopenomics/extension-kit 2026.8.18-2

package/dist/sync/index.d.mts

@@ -0,0 +1,735 @@
+import { Repository, DataSource } from 'typeorm';
+
+/**
+ * Дельта таблицы блокчейна — то, что прилетает из SHiP-парсера на каждое
+ * изменение строки в state контракта.
+ *
+ * Каркас синхронизации обязан знать эту форму: с неё начинается вся цепочка
+ * `delta -> mapper -> сущность -> репозиторий`. Ядро контроллера объявляло тот
+ * же тип в `~/types/common` и теперь реэкспортирует его отсюда, чтобы описание
+ * оставалось одно.
+ */
+interface IDelta {
+    chain_id: string;
+    block_num: number;
+    block_id: string;
+    /** ISO-8601 время блока (UTC) из SHiP-трейса. parser2 отдаёт, parser1 не отдавал. */
+    block_time?: string;
+    present: boolean;
+    code: string;
+    scope: string;
+    table: string;
+    primary_key: string;
+    value?: any;
+}
+
+/**
+ * Минимальный контракт логгера, которым пользуется каркас синхронизации.
+ *
+ * Зачем отдельный тип, а не порт из `@coopenomics/innercoop`: пакеты каркаса и
+ * контрактов ортогональны и не зависят друг от друга (INV-007). Связывать их
+ * ради пяти методов нельзя, а дублировать порт — значит завести второе имя
+ * для одной сущности.
+ *
+ * Поэтому здесь объявлена именно та часть, которую вызывает каркас, и опора
+ * идёт на структурную типизацию: `WinstonLoggerService` ядра подходит под этот
+ * контракт как есть, поэтому наследники передают его в `super()` без правок,
+ * и `ILoggerPort` из innercoop подойдёт так же, когда появится.
+ */
+interface ISyncLogger {
+    /** Пометить, от чьего имени идут записи (обычно имя класса-наследника). */
+    setContext(context: string): void;
+    log(message: any, ...optionalParams: any[]): void;
+    debug(message: any, ...optionalParams: any[]): void;
+    warn(message: any, ...optionalParams: any[]): void;
+    error(message: any, ...optionalParams: any[]): void;
+}
+
+/**
+ * Базовый интерфейс данных из базы данных для всех синхронизируемых сущностей
+ */
+interface IBaseDatabaseData {
+    /** Внутренний ID базы данных */
+    _id: string;
+    /** Номер блока последнего обновления */
+    block_num?: number;
+    /** Существует ли запись в блокчейне */
+    present: boolean;
+    /** Статус сущности */
+    status?: string;
+    /** Дата создания в базе данных */
+    _created_at?: Date;
+    /** Дата последнего обновления в базе данных */
+    _updated_at?: Date;
+}
+
+/**
+ * Интерфейс для данных с привязкой к блоку
+ */
+interface IBlockchainSyncData {
+    /** Номер блока в котором произошло изменение */
+    block_num: number;
+}
+/**
+ * Интерфейс для сущностей, которые могут быть синхронизированы с блокчейном
+ */
+interface IBlockchainSynchronizable {
+    /** Номер блока последнего обновления */
+    getBlockNum(): number | undefined;
+    /** Ключ для поиска сущности в блокчейне */
+    getPrimaryKey(): string;
+    /** Ключ для синхронизации сущности в блокчейне и базе данных */
+    getSyncKey(): string;
+    /** Обновление данных из блокчейна */
+    updateFromBlockchain(blockchainData: any, blockNum: number, present?: boolean): void;
+}
+/**
+ * Интерфейс для маппинга дельт блокчейна в доменные данные
+ */
+interface IBlockchainDeltaMapper<TBlockchainData = any, _TDomainEntity = any> {
+    /** Маппинг данных дельты в блокчейн-данные */
+    mapDeltaToBlockchainData(delta: IDelta): TBlockchainData | null;
+    /** Получение идентификатора сущности из дельты */
+    extractSyncValue(delta: IDelta): string;
+    /** Получение ключа для синхронизации сущности в блокчейне и базе данных */
+    extractSyncKey(): string;
+    /** Получение всех возможных паттернов событий  */
+    getAllEventPatterns(): string[];
+    /** Получение всех поддерживаемых имен таблиц */
+    getSupportedTableNames(): string[];
+    /** Получение всех поддерживаемых имен контрактов */
+    getSupportedContractNames(): string[];
+}
+/**
+ * Интерфейс для репозиториев с поддержкой синхронизации блокчейна
+ */
+interface IBlockchainSyncRepository<TEntity extends IBlockchainSynchronizable> {
+    /** Найти сущность по кастомному ключу синхронизации */
+    findBySyncKey(syncKey: string, syncValue: string): Promise<TEntity | null>;
+    /** Найти сущности с номером блока больше указанного */
+    findByBlockNumGreaterThan(blockNum: number): Promise<TEntity[]>;
+    /** Создание и валидация сущности без сохранения в базу данных */
+    create(entity: TEntity): Promise<any>;
+    /** Сохранение созданной сущности в базу данных */
+    saveCreated(entity: any): Promise<TEntity>;
+    /** Сохранить сущность */
+    save(entity: TEntity): Promise<TEntity>;
+    /** Обновить сущность */
+    update(entity: TEntity): Promise<TEntity>;
+    /** Создать сущность если не существует */
+    createIfNotExists(blockchainData: any, blockNum: number, present?: boolean): Promise<TEntity>;
+    /** Удалить сущности с номером блока больше указанного (для обработки форков) */
+    deleteByBlockNumGreaterThan(blockNum: number): Promise<void>;
+    /** Восстановить сущности из версий после форка */
+    restoreFromVersions?(forkBlockNum: number): Promise<void>;
+    /**
+     * Story 4.4: атомарно перенести live-сущности WHERE block_num > forkBlockNum в архив
+     * (invalidated_entities) и удалить из исходной таблицы. Возвращает count.
+     */
+    archiveInvalidatedSince?(forkBlockNum: number, forkEventId?: string | null): Promise<number>;
+    /**
+     * Story 4.4: атомарно перенести версии этой entity_table WHERE block_num > forkBlockNum
+     * в архив (invalidated_entity_versions) и удалить из entity_versions. Возвращает count.
+     */
+    archiveInvalidatedVersionsSince?(forkBlockNum: number, forkEventId?: string | null): Promise<number>;
+}
+/**
+ * Результат синхронизации сущности
+ */
+interface ISyncResult {
+    /** Была ли сущность создана */
+    created: boolean;
+    /** Была ли сущность обновлена */
+    updated: boolean;
+    /** Идентификатор сущности */
+    blockchainId: string;
+    /** Номер блока */
+    blockNum: number;
+}
+
+declare class BaseTypeormEntity {
+    _id: string;
+    block_num: number;
+    present: boolean;
+    status: string;
+    _created_at: Date;
+    _updated_at: Date;
+    /**
+     * Получить имя таблицы для сущности
+     * ДОЛЖЕН БЫТЬ ПЕРЕОПРЕДЕЛЕН в каждом наследнике!
+     */
+    static getTableName(): string;
+}
+
+/**
+ * Базовый класс для доменных сущностей
+ *
+ * Предоставляет общую логику для всех доменных сущностей:
+ * - Генерация _id при необходимости
+ * - Установка базовых полей из IBaseDatabaseData
+ */
+declare abstract class BaseDomainEntity<T extends IBaseDatabaseData> {
+    _id: string;
+    block_num?: number;
+    present: boolean;
+    status?: string;
+    _created_at: Date;
+    _updated_at: Date;
+    /**
+     * Конструктор базового класса
+     *
+     * @param databaseData - данные из базы данных
+     * @param defaultStatus - статус по умолчанию, если не указан
+     */
+    constructor(databaseData: T, defaultStatus?: string);
+    /**
+     * Обновление базовых данных сущности
+     */
+    updateBase(data: Partial<T>): void;
+}
+
+/**
+ * Базовый GraphQL Output DTO для сущностей
+ */
+declare class BaseOutputDTO {
+    _id: string;
+    present: boolean;
+    block_num?: number;
+    _created_at: Date;
+    _updated_at: Date;
+}
+
+/**
+ * Абстрактный базовый класс для всех блокчейн дельта-мапперов
+ * Предоставляет общую реализацию getAllEventPatterns()
+ */
+declare abstract class AbstractBlockchainDeltaMapper<TBlockchainData = any, TDomainEntity = any> implements IBlockchainDeltaMapper<TBlockchainData, TDomainEntity> {
+    /**
+     * Получение всех возможных паттернов событий для подписки
+     * Возвращает массив паттернов типа "delta::contract::table"
+     */
+    getAllEventPatterns(): string[];
+    abstract getSupportedContractNames(): string[];
+    abstract getSupportedTableNames(): string[];
+    abstract mapDeltaToBlockchainData(delta: IDelta): TBlockchainData | null;
+    abstract extractSyncValue(delta: IDelta): string;
+    abstract extractSyncKey(): string;
+}
+
+/**
+ * Контракт syncer'а, который умеет откатывать свои сущности при форке (ADR-005, Story 4.1).
+ *
+ * Реализуется один раз — в AbstractEntitySyncService, поэтому каждый наследник (capital,
+ * agreements, wallet и пр.) получает поведение автоматически через `implements` родителя.
+ *
+ * ForkRegistryService собирает реализующих через DiscoveryService по symbol-маркеру
+ * FORK_AWARE_MARKER на onApplicationBootstrap — без правок onModuleInit у наследников,
+ * без instanceof-зависимости (Symbol на прототипе работает кросс-extension).
+ *
+ * ForkRegistryService обходит зарегистрированных syncer'ов **последовательно** (for-of await)
+ * для каждой `handleFork(blockNum)`: re-throw любой ошибки останавливает дальнейший обход
+ * и не даёт parser2 ACK'нуть форк-событие (повторная доставка пересыграет цепочку).
+ */
+interface IForkAwareSyncer {
+    /**
+     * Откатить сущности этого syncer'а до состояния на блок forkBlockNum включительно.
+     * При ошибке — обязан re-throw (silent catch ломает контракт sequential apply).
+     *
+     * Story 4.4: `forkEventId` (optional) — локально-вычисленный controller-формат
+     * event_id (см. computeForkEventId), пробрасывается syncer'ом в архив инвалидированных
+     * сущностей (invalidated_entities.fork_event_id) для группировки по форкам. Старые
+     * вызовы без второго параметра остаются валидными — поле в архиве записывается NULL.
+     */
+    handleFork(forkBlockNum: number, forkEventId?: string | null): Promise<void>;
+    /**
+     * Опциональный приоритет для FK-зависимостей внутри одного контракта (меньше = раньше).
+     * Если не задан — порядок берётся из обхода DiscoveryService (отражает DI-граф Nest).
+     */
+    readonly forkRollbackPriority?: number;
+}
+/**
+ * Marker symbol для отделения форк-aware syncer'ов от прочих провайдеров при сканировании
+ * DiscoveryService. Класс-родитель AbstractEntitySyncService выставляет marker = true на
+ * своих экземплярах, поэтому все 20+ наследников автоматически попадают в обход без
+ * правок их onModuleInit.
+ */
+declare const FORK_AWARE_MARKER: unique symbol;
+/**
+ * Type guard для проверки, что произвольный провайдер реализует IForkAwareSyncer.
+ * Проверяет наличие symbol-маркера на инстансе и метода handleFork — duck typing
+ * с защитой от ложных срабатываний.
+ */
+declare function isForkAware(candidate: unknown): candidate is IForkAwareSyncer;
+
+/**
+ * Абстрактный сервис для синхронизации сущностей с блокчейном
+ *
+ * Предоставляет базовую логику для:
+ * - Обработки дельт блокчейна
+ * - Создания/обновления сущностей
+ * - Обработки форков (Story 4.1: реализует IForkAwareSyncer — ForkRegistryService
+ *   собирает наследников через DiscoveryService по symbol-маркеру и обходит
+ *   sequential при форке)
+ */
+declare abstract class AbstractEntitySyncService<TEntity extends IBlockchainSynchronizable, TBlockchainData = any> implements IForkAwareSyncer {
+    protected readonly repository: IBlockchainSyncRepository<TEntity>;
+    protected readonly mapper: IBlockchainDeltaMapper<TBlockchainData>;
+    protected readonly logger: ISyncLogger;
+    protected abstract readonly entityName: string;
+    /**
+     * Symbol-маркер для ForkRegistryService (Story 4.1). Все 20+ наследников
+     * автоматически попадают в реестр через bootstrap-сканирование Discovery —
+     * без правок их onModuleInit.
+     */
+    readonly [FORK_AWARE_MARKER] = true;
+    constructor(repository: IBlockchainSyncRepository<TEntity>, mapper: IBlockchainDeltaMapper<TBlockchainData>, logger: ISyncLogger);
+    /**
+     * Обработка дельты блокчейна
+     */
+    processDelta(delta: IDelta): Promise<ISyncResult | null>;
+    /**
+     * Обработка создания/обновления сущности
+     */
+    handleSyncDelta(syncKey: string, syncValue: string, blockchainData: TBlockchainData, blockNum: number, present?: boolean): Promise<ISyncResult>;
+    /**
+     * Обработка удаления сущности
+     */
+    private handleEntityDeletion;
+    /**
+     * Обработка форка — архивирование снесённых сущностей + восстановление из versions
+     * + архивирование инвалидированных версий.
+     *
+     * Story 4.1: ошибки больше НЕ глотаются — обязательный re-throw для контракта
+     * sequential ForkRegistry.runAll (INV-T03). Если rollback упадёт — parser2 не
+     * ACK'нет fork-event, повторная доставка пересыграет цепочку. Уже отработавшие
+     * syncer'ы в цепи будут no-op (versions уже подняты), сбойный — попробует ещё раз.
+     *
+     * Story 4.4: hard-delete заменён на «архив + delete» атомарно. Порядок:
+     *   1) archiveInvalidatedSince — live-ряды WHERE block_num > N переезжают в
+     *      invalidated_entities, оригинал удаляется (одна транзакция).
+     *   2) restoreFromVersions — поднять previous_data из ещё-живых entity_versions.
+     *   3) archiveInvalidatedVersionsSince — entity_versions WHERE entity_table=... AND
+     *      block_num > N переезжают в invalidated_entity_versions, оригинал удаляется.
+     *      Запускается ПОСЛЕ restore, иначе restore не сможет прочитать живые версии.
+     * Если репо не реализует archive методы (off-chain) — graceful no-op + fallback
+     * на старую findByBlockNumGreaterThan/deleteByBlockNumGreaterThan для бэк-совместимости.
+     */
+    handleFork(forkBlockNum: number, forkEventId?: string | null): Promise<void>;
+    /**
+     * Дополнительные действия после обработки форка
+     * Может быть переопределен в наследниках
+     */
+    protected afterForkProcessing(_forkBlockNum: number, _affectedEntities: TEntity[]): Promise<void>;
+    /**
+     * Получение всех возможных имен событий для подписки
+     */
+    getAllEventPatterns(): string[];
+    /**
+     * Получение всех поддерживаемых таблиц и контрактов для логирования
+     */
+    getSupportedVersions(): {
+        contracts: string[];
+        tables: string[];
+    };
+    /**
+     * Получение имени события для подписки на форки
+     */
+    getForkEventPattern(): string;
+}
+
+/**
+ * Единая таблица для хранения версий всех сущностей системы.
+ * Используется для восстановления состояния при форках блокчейна.
+ */
+declare class EntityVersionTypeormEntity {
+    id: string;
+    /**
+     * Название таблицы сущности (например, 'chairman_approvals')
+     */
+    entity_table: string;
+    /**
+     * ID сущности в её таблице (_id для TypeORM сущностей)
+     */
+    entity_id: string;
+    /**
+     * Полные данные предыдущей версии сущности в JSON формате
+     */
+    previous_data: Record<string, any>;
+    /**
+     * Номер блока, на котором произошло изменение
+     */
+    block_num?: number | null;
+    /**
+     * Тип изменения (blockchain_sync, local_change и т.д.)
+     */
+    change_type: string;
+    /**
+     * Дополнительные метаданные изменения
+     */
+    metadata?: Record<string, any>;
+    created_at: Date;
+}
+
+/**
+ * Репозиторий для работы с версиями сущностей.
+ * Используется для восстановления состояния при форках.
+ */
+declare class EntityVersionRepository {
+    private readonly repository;
+    constructor(repository: Repository<EntityVersionTypeormEntity>);
+    /**
+     * Соединение, на котором работает репозиторий.
+     *
+     * Нужно тем, кому требуется транзакция на несколько таблиц. Инжектить
+     * `DataSource` через `@InjectDataSource()` в пакете нельзя: pnpm вшивает в
+     * путь хэш peer-зависимостей, у пакета и контроллера оказываются разные
+     * экземпляры `@nestjs/typeorm`, и токен не совпадает — Nest не находит
+     * провайдера. Токен `@InjectRepository` такой беды не знает: он считается от
+     * класса сущности, а она в пакете одна.
+     */
+    get dataSource(): DataSource;
+    /**
+     * Сохранить предыдущую версию сущности
+     */
+    saveVersion(entityTable: string, entityId: string, previousData: Record<string, any>, blockNum: number | null, changeType: string, metadata?: Record<string, any>): Promise<EntityVersionTypeormEntity>;
+    /**
+     * Получить последнюю версию сущности до указанного блока
+     */
+    getLastVersionBeforeBlock(entityTable: string, entityId: string, blockNum: number): Promise<EntityVersionTypeormEntity | null>;
+    /**
+     * Удалить все версии после указанного блока (локальные изменения остаются)
+     */
+    deleteVersionsAfterBlock(blockNum: number): Promise<number>;
+    /**
+     * Получить все версии для сущностей, которые нужно восстановить
+     */
+    getVersionsForRecovery(entityTable: string, maxBlockNum: number): Promise<EntityVersionTypeormEntity[]>;
+    /**
+     * Очистить версии для указанной сущности
+     */
+    clearVersionsForEntity(entityTable: string, entityId: string): Promise<number>;
+}
+
+/**
+ * Архив сущностей, снесённых форком. Каждый ряд = одна live-запись, которая была
+ * в зеркале блокчейна на момент форка (block_num > forkBlockNum). Story 4.4.
+ *
+ * `invalidated_by_block` = block_num форка (т.е. forked_from_block из ForkEvent).
+ * `fork_event_id` группирует все снесённые одним форком ряды (опционально — старые форки до Story 4.4 без id).
+ *
+ * Retention: BlockchainArchiveRetentionService раз в час удаляет WHERE invalidated_by_block < LIB - 1000.
+ */
+declare class InvalidatedEntityTypeormEntity {
+    id: string;
+    entity_table: string;
+    entity_id: string;
+    data: Record<string, any>;
+    invalidated_by_block: number;
+    fork_event_id?: string | null;
+    created_at: Date;
+}
+
+interface InvalidatedEntityRecord {
+    entity_table: string;
+    entity_id: string;
+    data: Record<string, any>;
+    invalidated_by_block: number;
+    fork_event_id?: string | null;
+}
+/**
+ * Репозиторий архива снесённых форком live-сущностей (Story 4.4).
+ */
+declare class InvalidatedEntityRepository {
+    private readonly repository;
+    constructor(repository: Repository<InvalidatedEntityTypeormEntity>);
+    bulkInsert(records: InvalidatedEntityRecord[]): Promise<number>;
+    /**
+     * Retention: удалить архив старше указанного блока. Делается отдельной транзакцией,
+     * не транзакционно с архивированием — это фоновая очистка.
+     */
+    deleteOlderThan(minInvalidatedByBlock: number): Promise<number>;
+    /**
+     * Forensic-read для AC «список из invalidated_entities, сгруппированный по fork_event_id».
+     * UI/CLI обёртка — Epic 9 (out of scope 4.4); сам repository-метод доступен из backend-кода.
+     */
+    findGroupedByForkEventId(opts: {
+        blockNum?: number;
+        limit?: number;
+    }): Promise<Map<string | null, InvalidatedEntityTypeormEntity[]>>;
+}
+
+/**
+ * Архив версий-снимков, потерявших инвалидирующий блок при форке. Story 4.4.
+ *
+ * Каждый ряд entity_versions хранит previous_data + block_num (блок, в котором данное
+ * previous_data перестало быть актуальным). При форке на N все entity_versions
+ * WHERE block_num > N теряют свой инвалидирующий блок (он на снесённой ветке) и
+ * становятся «осиротевшими». Если не убрать — при повторном форке restoreFromVersions
+ * подберёт их и поднимет не ту ветку.
+ *
+ * `original_block_num` = блок-инвалидатор из исходного entity_versions ряда (может быть null
+ * для локальных pre-blockchain изменений). `invalidated_by_block` = блок форка.
+ */
+declare class InvalidatedEntityVersionTypeormEntity {
+    id: string;
+    entity_table: string;
+    entity_id: string;
+    previous_data: Record<string, any>;
+    original_block_num?: number | null;
+    invalidated_by_block: number;
+    fork_event_id?: string | null;
+    change_type: string;
+    metadata?: Record<string, any> | null;
+    created_at: Date;
+}
+
+interface InvalidatedEntityVersionRecord {
+    entity_table: string;
+    entity_id: string;
+    previous_data: Record<string, any>;
+    original_block_num?: number | null;
+    invalidated_by_block: number;
+    fork_event_id?: string | null;
+    change_type: string;
+    metadata?: Record<string, any> | null;
+}
+/**
+ * Репозиторий архива снесённых форком версий-снимков entity_versions (Story 4.4).
+ */
+declare class InvalidatedEntityVersionRepository {
+    private readonly repository;
+    constructor(repository: Repository<InvalidatedEntityVersionTypeormEntity>);
+    bulkInsert(records: InvalidatedEntityVersionRecord[]): Promise<number>;
+    deleteOlderThan(minInvalidatedByBlock: number): Promise<number>;
+}
+
+/**
+ * Сервис для версионирования сущностей.
+ * Автоматически сохраняет предыдущие версии при изменениях и восстанавливает их при форках.
+ *
+ * Story 4.4: расширен двумя архивными методами — archiveAndDeleteLiveAfterFork /
+ * archiveAndDeleteVersionsAfterFork. Используются из AbstractEntitySyncService.handleFork
+ * через делегацию BaseBlockchainRepository (см. base-blockchain.repository.ts).
+ */
+declare class EntityVersioningService {
+    private readonly entityVersionRepository;
+    private readonly invalidatedEntityRepository;
+    private readonly invalidatedEntityVersionRepository;
+    constructor(entityVersionRepository: EntityVersionRepository, invalidatedEntityRepository: InvalidatedEntityRepository, invalidatedEntityVersionRepository: InvalidatedEntityVersionRepository);
+    /**
+     * Соединение берём у репозитория, а не инъекцией `@InjectDataSource()`:
+     * у пакета и контроллера разные экземпляры `@nestjs/typeorm`, и токен
+     * источника данных не совпал бы — Nest не нашёл бы провайдера.
+     */
+    private get dataSource();
+    /**
+     * Сохранить версию сущности перед её изменением
+     */
+    saveVersionBeforeUpdate<TEntity extends IBaseDatabaseData>(repository: Repository<TEntity>, entityTable: string, updatedEntity: Partial<TEntity>, blockNum: number | null, changeType: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Восстановить версии сущностей после форка
+     */
+    restoreVersionsAfterFork<TEntity extends IBaseDatabaseData>(repository: Repository<TEntity>, entityTable: string, forkBlockNum: number): Promise<void>;
+    /**
+     * Определить, должна ли новая версия заменить существующую
+     */
+    private shouldReplaceVersion;
+    /**
+     * Очистить версии после успешного восстановления
+     */
+    clearVersionsAfterBlock(blockNum: number): Promise<number>;
+    /**
+     * Story 4.4: атомарно перенести live-ряды WHERE block_num > forkBlockNum в архив
+     * `invalidated_entities` и удалить их из исходной таблицы. Возвращает количество
+     * перенесённых рядов. Транзакция через DataSource — INSERT и DELETE либо оба
+     * успешны, либо оба откатываются.
+     *
+     * Заменяет прежнюю пару findByBlockNumGreaterThan + deleteByBlockNumGreaterThan
+     * в hot-path handleFork (sequence сейчас: archive → restoreFromVersions →
+     * archiveVersions).
+     */
+    archiveAndDeleteLiveAfterFork<TEntity extends IBaseDatabaseData>(repository: Repository<TEntity>, entityTable: string, forkBlockNum: number, forkEventId?: string | null): Promise<number>;
+    /**
+     * Story 4.4: атомарно перенести entity_versions WHERE entity_table=... AND block_num > forkBlockNum
+     * в архив `invalidated_entity_versions` и удалить их из entity_versions.
+     * Возвращает количество перенесённых рядов.
+     *
+     * Запускается ПОСЛЕ restoreFromVersions — иначе restore не сможет прочитать
+     * ещё-живые версии.
+     */
+    archiveAndDeleteVersionsAfterFork(entityTable: string, forkBlockNum: number, forkEventId?: string | null): Promise<number>;
+}
+
+/**
+ * Базовый абстрактный класс для репозиториев блокчейн-сущностей
+ *
+ * Предоставляет общую реализацию методов:
+ * - Синхронизации с блокчейном: findByBlockchainId, findByBlockNumGreaterThan, createIfNotExists, deleteByBlockNumGreaterThan
+ * - CRUD операций: findAll, findById, save, update, delete
+ */
+declare abstract class BaseBlockchainRepository<TDomainEntity extends IBlockchainSynchronizable, TTypeormEntity extends IBaseDatabaseData> implements IBlockchainSyncRepository<TDomainEntity> {
+    protected readonly repository: Repository<TTypeormEntity>;
+    protected readonly entityVersioningService: EntityVersioningService;
+    protected constructor(repository: Repository<TTypeormEntity>, entityVersioningService: EntityVersioningService);
+    /**
+     * Маппер для преобразования между доменной и TypeORM сущностями
+     * Должен содержать методы:
+     * - toDomain(typeormEntity: TTypeormEntity): TDomainEntity
+     * - toEntity(domainEntity: TDomainEntity): Partial<TTypeormEntity>
+     */
+    protected abstract getMapper(): {
+        toDomain: (typeormEntity: TTypeormEntity) => TDomainEntity;
+        toEntity: (domainEntity: TDomainEntity) => Partial<TTypeormEntity>;
+    };
+    /**
+     * Получить имя таблицы сущности
+     */
+    protected getEntityTableName(): string;
+    /**
+     * Найти сущность по кастомному ключу синхронизации
+     */
+    findBySyncKey(syncKey: string, syncValue: string): Promise<TDomainEntity | null>;
+    /**
+     * Найти сущности с номером блока больше указанного
+     */
+    findByBlockNumGreaterThan(blockNum: number): Promise<TDomainEntity[]>;
+    /**
+     * Создать сущность если не существует
+     * Используется для синхронизации данных из блокчейна
+     */
+    createIfNotExists(blockchainData: any, blockNum: number, present?: boolean): Promise<TDomainEntity>;
+    /**
+     * Удалить сущности с номером блока больше указанного (для обработки форков)
+     */
+    deleteByBlockNumGreaterThan(blockNum: number): Promise<void>;
+    /**
+     * Восстановить сущности из версий после форка
+     */
+    restoreFromVersions(forkBlockNum: number): Promise<void>;
+    /**
+     * Story 4.4: архивировать live-ряды WHERE block_num > forkBlockNum в invalidated_entities
+     * и удалить из исходной таблицы (атомарно). Возвращает count. Заменяет в hot-path
+     * handleFork прежнюю пару findByBlockNumGreaterThan + deleteByBlockNumGreaterThan.
+     */
+    archiveInvalidatedSince(forkBlockNum: number, forkEventId?: string | null): Promise<number>;
+    /**
+     * Story 4.4: архивировать entity_versions WHERE entity_table=... AND block_num > forkBlockNum
+     * в invalidated_entity_versions и удалить из entity_versions (атомарно). Возвращает count.
+     * Должен вызываться ПОСЛЕ restoreFromVersions — иначе restore не сможет прочитать ещё-живые версии.
+     */
+    archiveInvalidatedVersionsSince(forkBlockNum: number, forkEventId?: string | null): Promise<number>;
+    /**
+     * Обновить сущность
+     */
+    update(entity: TDomainEntity): Promise<TDomainEntity>;
+    /**
+     * Создание и валидация сущности без сохранения в базу данных
+     */
+    create(entity: TDomainEntity): Promise<any>;
+    /**
+     * Сохранение созданной сущности в базу данных
+     */
+    saveCreated(entity: any): Promise<TDomainEntity>;
+    /**
+     * Сохранить сущность
+     */
+    save(entity: TDomainEntity): Promise<TDomainEntity>;
+    /**
+     * Найти все сущности
+     */
+    findAll(): Promise<TDomainEntity[]>;
+    /**
+     * Найти сущность по внутреннему ID базы данных
+     */
+    findById(_id: string): Promise<TDomainEntity | null>;
+    /**
+     * Удалить сущность по внутреннему ID базы данных
+     */
+    delete(_id: string): Promise<void>;
+    /**
+     * Создать доменную сущность
+     * Должен быть реализован в наследниках для создания конкретного типа сущности
+     */
+    protected abstract createDomainEntity(databaseData: any, blockchainData: any): TDomainEntity;
+    /**
+     * Получить ключ синхронизации для данной сущности
+     * Должен быть реализован в наследниках для возврата правильного ключа
+     */
+    protected abstract getSyncKey(): string;
+    /**
+     * Извлечь значение ключа синхронизации из блокчейн данных
+     */
+    protected extractSyncValueFromBlockchainData(blockchainData: any, syncKey: string): string;
+}
+
+/**
+ * Story 6.5 (Epic 6): сигнализирует, что mapper не смог разобрать дельту блокчейна
+ * (mapDeltaToBlockchainData вернул null). Бросается из `AbstractEntitySyncService.processDelta`
+ * в strict-mode (`config.blockchain.unsupported_version_strict=true`).
+ *
+ * В non-strict режиме (default) ошибка не бросается — пишется только `logger.error` для
+ * аудита; парсер ACK'нет fork-event-like (поведение совместимое с текущим).
+ */
+declare class UnsupportedContractVersionError extends Error {
+    readonly entityName: string;
+    readonly context: {
+        contract?: string;
+        table?: string;
+        primary_key?: string | number;
+        block_num?: number;
+    };
+    constructor(entityName: string, context: {
+        contract?: string;
+        table?: string;
+        primary_key?: string | number;
+        block_num?: number;
+    });
+}
+
+/**
+ * Story 6.5 (Epic 6): helper для эталонной точки `mapStatusToDomain`.
+ * При попадании на default-ветку (unknown статус из цепи) пишет `logger.error`
+ * с контекстом (entity, статус, ожидаемые статусы) — это audit-trail для schema drift.
+ *
+ * Возврата нет — caller сам решает, какой UNDEFINED-fallback использовать.
+ */
+interface AuditLoggerLike {
+    error(message: string, ...meta: any[]): void;
+}
+declare function auditUnknownStatus(entityName: string, receivedStatus: unknown, logger: AuditLoggerLike, allowedStatuses?: ReadonlyArray<string>): void;
+
+/**
+ * Политика каркаса синхронизации.
+ *
+ * Отделена от настроек контура (`platformSettings`) намеренно: те описывают
+ * кооператив — имя, адреса, зону, — а здесь режим обработки дельт, свойство
+ * стенда, а не кооператива.
+ *
+ * Задаёт её composition root контроллера при старте, рядом с остальными
+ * предусловиями. Расширение, собранное отдельно, получит значения по умолчанию
+ * — они совпадают с поведением контроллера без переменных окружения.
+ */
+interface SyncPolicy {
+    /**
+     * Что делать с дельтой неизвестной версии контракта.
+     *
+     * `false` (по умолчанию) — записать предупреждение и пропустить: расхождение
+     * схемы не должно останавливать синхронизацию рабочего кооператива.
+     * `true` — бросить `UnsupportedContractVersionError`, парсер не подтвердит
+     * дельту и она уйдёт в dead-letter. Так включают на стенде, когда нужно
+     * убедиться, что расхождения схемы нет вовсе.
+     */
+    unsupportedVersionStrict: boolean;
+}
+/** Вызывается composition root'ом при старте. Повторный вызов перезаписывает. */
+declare function configureSyncPolicy(next: Partial<SyncPolicy>): void;
+/** Текущая политика; без настройки — значения по умолчанию. */
+declare function syncPolicy(): SyncPolicy;
+
+/** Задать журнал аудита. Вызывается из composition root при старте. */
+declare function configureAuditLogger(logger: AuditLoggerLike): void;
+/** Журнал аудита, которым пользуются каркас и расширения. */
+declare function auditLogger(): AuditLoggerLike;
+
+export { AbstractBlockchainDeltaMapper, AbstractEntitySyncService, BaseBlockchainRepository, BaseDomainEntity, BaseOutputDTO, BaseTypeormEntity, EntityVersionRepository, EntityVersionTypeormEntity, EntityVersioningService, FORK_AWARE_MARKER, InvalidatedEntityRepository, InvalidatedEntityTypeormEntity, InvalidatedEntityVersionRepository, InvalidatedEntityVersionTypeormEntity, UnsupportedContractVersionError, auditLogger, auditUnknownStatus, configureAuditLogger, configureSyncPolicy, isForkAware, syncPolicy };
+export type { AuditLoggerLike, IBaseDatabaseData, IBlockchainDeltaMapper, IBlockchainSyncData, IBlockchainSyncRepository, IBlockchainSynchronizable, IDelta, IForkAwareSyncer, ISyncLogger, ISyncResult, InvalidatedEntityRecord, InvalidatedEntityVersionRecord, SyncPolicy };