@coopenomics/extension-kit 2026.8.18-2

package/dist/sync/index.cjs

@@ -0,0 +1,1071 @@
+'use strict';
+
+const typeorm = require('typeorm');
+const crypto = require('crypto');
+const graphql = require('@nestjs/graphql');
+const common = require('@nestjs/common');
+const typeorm$1 = require('@nestjs/typeorm');
+
+var __defProp$a = Object.defineProperty;
+var __getOwnPropDesc$a = Object.getOwnPropertyDescriptor;
+var __decorateClass$a = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$a(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$a(target, key, result);
+  return result;
+};
+class BaseTypeormEntity {
+  /**
+   * Получить имя таблицы для сущности
+   * ДОЛЖЕН БЫТЬ ПЕРЕОПРЕДЕЛЕН в каждом наследнике!
+   */
+  static getTableName() {
+    throw new Error("getTableName() must be implemented in subclass");
+  }
+}
+__decorateClass$a([
+  typeorm.PrimaryGeneratedColumn("uuid")
+], BaseTypeormEntity.prototype, "_id", 2);
+__decorateClass$a([
+  typeorm.Column({ type: "integer", default: 0 })
+], BaseTypeormEntity.prototype, "block_num", 2);
+__decorateClass$a([
+  typeorm.Column({ type: "boolean", default: false })
+], BaseTypeormEntity.prototype, "present", 2);
+__decorateClass$a([
+  typeorm.Column({ type: "varchar" })
+], BaseTypeormEntity.prototype, "status", 2);
+__decorateClass$a([
+  typeorm.CreateDateColumn({ type: "timestamp" })
+], BaseTypeormEntity.prototype, "_created_at", 2);
+__decorateClass$a([
+  typeorm.UpdateDateColumn({ type: "timestamp" })
+], BaseTypeormEntity.prototype, "_updated_at", 2);
+
+class BaseDomainEntity {
+  // Дата последнего обновления в базе данных
+  /**
+   * Конструктор базового класса
+   *
+   * @param databaseData - данные из базы данных
+   * @param defaultStatus - статус по умолчанию, если не указан
+   */
+  constructor(databaseData, defaultStatus) {
+    this._id = databaseData._id === "" ? crypto.randomUUID().toString() : databaseData._id;
+    this.block_num = databaseData.block_num ?? 0;
+    this.present = databaseData.present;
+    this.status = databaseData.status ?? defaultStatus;
+    this._created_at = databaseData._created_at ? new Date(databaseData._created_at) : /* @__PURE__ */ new Date();
+    this._updated_at = databaseData._updated_at ? new Date(databaseData._updated_at) : /* @__PURE__ */ new Date();
+  }
+  /**
+   * Обновление базовых данных сущности
+   */
+  updateBase(data) {
+    if (data.block_num !== void 0)
+      this.block_num = data.block_num;
+    if (data.present !== void 0)
+      this.present = data.present;
+    if (data.status !== void 0)
+      this.status = data.status;
+    if (data._created_at !== void 0)
+      this._created_at = data._created_at;
+    if (data._updated_at !== void 0)
+      this._updated_at = data._updated_at;
+  }
+}
+
+var __defProp$9 = Object.defineProperty;
+var __getOwnPropDesc$9 = Object.getOwnPropertyDescriptor;
+var __decorateClass$9 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$9(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$9(target, key, result);
+  return result;
+};
+exports.BaseOutputDTO = class BaseOutputDTO {
+};
+__decorateClass$9([
+  graphql.Field(() => String, {
+    description: "\u0412\u043D\u0443\u0442\u0440\u0435\u043D\u043D\u0438\u0439 ID \u0431\u0430\u0437\u044B \u0434\u0430\u043D\u043D\u044B\u0445"
+  })
+], exports.BaseOutputDTO.prototype, "_id", 2);
+__decorateClass$9([
+  graphql.Field(() => Boolean, {
+    description: "\u0424\u043B\u0430\u0433 \u043F\u0440\u0438\u0441\u0443\u0442\u0441\u0442\u0432\u0438\u044F \u0437\u0430\u043F\u0438\u0441\u0438 \u0432 \u0431\u043B\u043E\u043A\u0447\u0435\u0439\u043D\u0435"
+  })
+], exports.BaseOutputDTO.prototype, "present", 2);
+__decorateClass$9([
+  graphql.Field(() => Number, {
+    nullable: true,
+    description: "\u041D\u043E\u043C\u0435\u0440 \u0431\u043B\u043E\u043A\u0430 \u043A\u0440\u0430\u0439\u043D\u0435\u0439 \u0441\u0438\u043D\u0445\u0440\u043E\u043D\u0438\u0437\u0430\u0446\u0438\u0438 \u0441 \u0431\u043B\u043E\u043A\u0447\u0435\u0439\u043D\u043E\u043C"
+  })
+], exports.BaseOutputDTO.prototype, "block_num", 2);
+__decorateClass$9([
+  graphql.Field(() => Date, {
+    description: "\u0414\u0430\u0442\u0430 \u0441\u043E\u0437\u0434\u0430\u043D\u0438\u044F \u0437\u0430\u043F\u0438\u0441\u0438"
+  })
+], exports.BaseOutputDTO.prototype, "_created_at", 2);
+__decorateClass$9([
+  graphql.Field(() => Date, {
+    description: "\u0414\u0430\u0442\u0430 \u043F\u043E\u0441\u043B\u0435\u0434\u043D\u0435\u0433\u043E \u043E\u0431\u043D\u043E\u0432\u043B\u0435\u043D\u0438\u044F \u0437\u0430\u043F\u0438\u0441\u0438"
+  })
+], exports.BaseOutputDTO.prototype, "_updated_at", 2);
+exports.BaseOutputDTO = __decorateClass$9([
+  graphql.ObjectType("BaseEntity", {
+    description: "\u0411\u0430\u0437\u043E\u0432\u044B\u0435 \u043F\u043E\u043B\u044F \u0441\u0443\u0449\u043D\u043E\u0441\u0442\u0438"
+  })
+], exports.BaseOutputDTO);
+
+class AbstractBlockchainDeltaMapper {
+  /**
+   * Получение всех возможных паттернов событий для подписки
+   * Возвращает массив паттернов типа "delta::contract::table"
+   */
+  getAllEventPatterns() {
+    const patterns = [];
+    const supportedContracts = this.getSupportedContractNames();
+    const supportedTables = this.getSupportedTableNames();
+    for (const contractName of supportedContracts) {
+      for (const tableName of supportedTables) {
+        patterns.push(`delta::${contractName}::${tableName}`);
+      }
+    }
+    return patterns;
+  }
+}
+
+const FORK_AWARE_MARKER = Symbol.for("mono.controller.shared.sync.ForkAware");
+function isForkAware(candidate) {
+  if (candidate == null)
+    return false;
+  const obj = candidate;
+  return obj[FORK_AWARE_MARKER] === true && typeof obj.handleFork === "function";
+}
+
+class UnsupportedContractVersionError extends Error {
+  constructor(entityName, context) {
+    super(
+      `Unsupported contract version while mapping delta for ${entityName}: ${JSON.stringify(context)}`
+    );
+    this.entityName = entityName;
+    this.context = context;
+    this.name = "UnsupportedContractVersionError";
+  }
+}
+
+const DEFAULTS = {
+  unsupportedVersionStrict: false
+};
+let policy = DEFAULTS;
+function configureSyncPolicy(next) {
+  policy = { ...DEFAULTS, ...next };
+}
+function syncPolicy() {
+  return policy;
+}
+
+var __defProp$8 = Object.defineProperty;
+var __getOwnPropDesc$8 = Object.getOwnPropertyDescriptor;
+var __decorateClass$8 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$8(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$8(target, key, result);
+  return result;
+};
+var _a;
+exports.AbstractEntitySyncService = class AbstractEntitySyncService {
+  constructor(repository, mapper, logger) {
+    this.repository = repository;
+    this.mapper = mapper;
+    this.logger = logger;
+    /**
+     * Symbol-маркер для ForkRegistryService (Story 4.1). Все 20+ наследников
+     * автоматически попадают в реестр через bootstrap-сканирование Discovery —
+     * без правок их onModuleInit.
+     */
+    this[_a] = true;
+    this.logger.setContext(`${this.constructor.name}`);
+  }
+  static {
+    _a = FORK_AWARE_MARKER;
+  }
+  /**
+   * Обработка дельты блокчейна
+   */
+  async processDelta(delta) {
+    try {
+      this.logger.debug(`Processing ${this.entityName} delta for table ${delta.table} with key ${delta.primary_key}`);
+      const syncValue = this.mapper.extractSyncValue(delta);
+      const syncKey = this.mapper.extractSyncKey();
+      const blockchainData = this.mapper.mapDeltaToBlockchainData(delta);
+      if (!blockchainData) {
+        const ctx = {
+          contract: delta.contract ?? delta.code,
+          table: delta.table,
+          primary_key: delta.primary_key,
+          block_num: Number(delta.block_num)
+        };
+        this.logger.error(
+          `UNSUPPORTED_CONTRACT_VERSION: mapDeltaToBlockchainData returned null for ${this.entityName} ${syncValue}`,
+          { entity: this.entityName, syncValue, ...ctx }
+        );
+        if (syncPolicy().unsupportedVersionStrict) {
+          throw new UnsupportedContractVersionError(this.entityName, ctx);
+        }
+        return null;
+      }
+      const blockNum = Number(delta.block_num);
+      const present = delta.present !== false;
+      return await this.handleSyncDelta(syncKey, syncValue, blockchainData, blockNum, present);
+    } catch (error) {
+      if (error instanceof UnsupportedContractVersionError)
+        throw error;
+      this.logger.error(`Error processing ${this.entityName} delta: ${error.message}`, error.stack);
+      return null;
+    }
+  }
+  /**
+   * Обработка создания/обновления сущности
+   */
+  async handleSyncDelta(syncKey, syncValue, blockchainData, blockNum, present = true) {
+    const existingEntity = await this.repository.findBySyncKey(syncKey, syncValue);
+    if (existingEntity) {
+      const currentBlockNum = existingEntity.getBlockNum();
+      if (currentBlockNum && blockNum < currentBlockNum) {
+        this.logger.debug(
+          `Skipping outdated update for ${this.entityName} ${syncValue}: block ${blockNum} <= ${currentBlockNum}`
+        );
+        return {
+          created: false,
+          updated: false,
+          blockchainId: syncValue,
+          blockNum: currentBlockNum
+        };
+      }
+      existingEntity.updateFromBlockchain(blockchainData, blockNum, present);
+      await this.repository.update(existingEntity);
+      this.logger.debug(`\u041E\u0431\u043D\u043E\u0432\u043B\u0435\u043D ${this.entityName} ${syncValue} \u0432 \u0431\u043B\u043E\u043A\u0435 ${blockNum}`);
+      return {
+        created: false,
+        updated: true,
+        blockchainId: syncValue,
+        blockNum
+      };
+    } else {
+      await this.repository.createIfNotExists(blockchainData, blockNum, present);
+      this.logger.debug(`\u0421\u043E\u0437\u0434\u0430\u043D ${this.entityName} ${syncValue} \u0432 \u0431\u043B\u043E\u043A\u0435 ${blockNum}`);
+      return {
+        created: true,
+        updated: false,
+        blockchainId: syncValue,
+        blockNum
+      };
+    }
+  }
+  /**
+   * Обработка удаления сущности
+   */
+  async handleEntityDeletion(syncValue, blockNum) {
+    this.logger.debug(`Entity ${this.entityName} ${syncValue} was deleted at block ${blockNum}`);
+    return {
+      created: false,
+      updated: false,
+      blockchainId: syncValue,
+      blockNum
+    };
+  }
+  /**
+   * Обработка форка — архивирование снесённых сущностей + восстановление из 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 для бэк-совместимости.
+   */
+  async handleFork(forkBlockNum, forkEventId) {
+    this.logger.log(`Handling fork for ${this.entityName} at block ${forkBlockNum} (eventId=${forkEventId ?? "n/a"})`);
+    let archivedLive = 0;
+    if (this.repository.archiveInvalidatedSince) {
+      archivedLive = await this.repository.archiveInvalidatedSince(forkBlockNum, forkEventId);
+      this.logger.log(
+        `\u0410\u0440\u0445\u0438\u0432\u0438\u0440\u043E\u0432\u0430\u043D\u043E ${archivedLive} live-\u0440\u044F\u0434\u043E\u0432 ${this.entityName} \u043D\u0430 \u0444\u043E\u0440\u043A\u0435 ${forkBlockNum}`
+      );
+    } else {
+      const affected = await this.repository.findByBlockNumGreaterThan(forkBlockNum);
+      await this.repository.deleteByBlockNumGreaterThan(forkBlockNum);
+      archivedLive = affected.length;
+      this.logger.warn(
+        `${this.entityName}: archiveInvalidatedSince \u043D\u0435 \u0440\u0435\u0430\u043B\u0438\u0437\u043E\u0432\u0430\u043D \u2014 fallback \u043D\u0430 hard-delete (${archivedLive} \u0440\u044F\u0434\u043E\u0432)`
+      );
+    }
+    if (this.repository.restoreFromVersions) {
+      await this.repository.restoreFromVersions(forkBlockNum);
+      this.logger.log(`Restored ${this.entityName} entities from versions after fork at block ${forkBlockNum}`);
+    }
+    if (this.repository.archiveInvalidatedVersionsSince) {
+      const archivedVersions = await this.repository.archiveInvalidatedVersionsSince(forkBlockNum, forkEventId);
+      this.logger.log(
+        `\u0410\u0440\u0445\u0438\u0432\u0438\u0440\u043E\u0432\u0430\u043D\u043E ${archivedVersions} \u0432\u0435\u0440\u0441\u0438\u0439 ${this.entityName} \u043D\u0430 \u0444\u043E\u0440\u043A\u0435 ${forkBlockNum}`
+      );
+    }
+    await this.afterForkProcessing(forkBlockNum, []);
+  }
+  /**
+   * Дополнительные действия после обработки форка
+   * Может быть переопределен в наследниках
+   */
+  async afterForkProcessing(_forkBlockNum, _affectedEntities) {
+  }
+  /**
+   * Получение всех возможных имен событий для подписки
+   */
+  getAllEventPatterns() {
+    return this.mapper.getAllEventPatterns();
+  }
+  /**
+   * Получение всех поддерживаемых таблиц и контрактов для логирования
+   */
+  getSupportedVersions() {
+    return {
+      contracts: this.mapper.getSupportedContractNames(),
+      tables: this.mapper.getSupportedTableNames()
+    };
+  }
+  /**
+   * Получение имени события для подписки на форки
+   */
+  getForkEventPattern() {
+    return "fork::*";
+  }
+};
+exports.AbstractEntitySyncService = __decorateClass$8([
+  common.Injectable()
+], exports.AbstractEntitySyncService);
+
+var __defProp$7 = Object.defineProperty;
+var __getOwnPropDesc$7 = Object.getOwnPropertyDescriptor;
+var __decorateClass$7 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$7(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$7(target, key, result);
+  return result;
+};
+exports.EntityVersionTypeormEntity = class EntityVersionTypeormEntity {
+};
+__decorateClass$7([
+  typeorm.PrimaryGeneratedColumn("uuid")
+], exports.EntityVersionTypeormEntity.prototype, "id", 2);
+__decorateClass$7([
+  typeorm.Column({ type: "varchar", length: 100 })
+], exports.EntityVersionTypeormEntity.prototype, "entity_table", 2);
+__decorateClass$7([
+  typeorm.Column({ type: "varchar", length: 36 })
+], exports.EntityVersionTypeormEntity.prototype, "entity_id", 2);
+__decorateClass$7([
+  typeorm.Column({ type: "jsonb" })
+], exports.EntityVersionTypeormEntity.prototype, "previous_data", 2);
+__decorateClass$7([
+  typeorm.Column({ type: "integer", nullable: true })
+], exports.EntityVersionTypeormEntity.prototype, "block_num", 2);
+__decorateClass$7([
+  typeorm.Column({ type: "varchar", length: 50 })
+], exports.EntityVersionTypeormEntity.prototype, "change_type", 2);
+__decorateClass$7([
+  typeorm.Column({ type: "jsonb", nullable: true })
+], exports.EntityVersionTypeormEntity.prototype, "metadata", 2);
+__decorateClass$7([
+  typeorm.CreateDateColumn({ type: "timestamp" })
+], exports.EntityVersionTypeormEntity.prototype, "created_at", 2);
+exports.EntityVersionTypeormEntity = __decorateClass$7([
+  typeorm.Entity("entity_versions"),
+  typeorm.Index("idx_entity_versions_entity_table_id", ["entity_table", "entity_id"]),
+  typeorm.Index("idx_entity_versions_block_num", ["block_num"])
+], exports.EntityVersionTypeormEntity);
+
+var __defProp$6 = Object.defineProperty;
+var __getOwnPropDesc$6 = Object.getOwnPropertyDescriptor;
+var __decorateClass$6 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$6(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$6(target, key, result);
+  return result;
+};
+var __decorateParam$3 = (index, decorator) => (target, key) => decorator(target, key, index);
+exports.EntityVersionRepository = class EntityVersionRepository {
+  constructor(repository) {
+    this.repository = repository;
+  }
+  /**
+   * Соединение, на котором работает репозиторий.
+   *
+   * Нужно тем, кому требуется транзакция на несколько таблиц. Инжектить
+   * `DataSource` через `@InjectDataSource()` в пакете нельзя: pnpm вшивает в
+   * путь хэш peer-зависимостей, у пакета и контроллера оказываются разные
+   * экземпляры `@nestjs/typeorm`, и токен не совпадает — Nest не находит
+   * провайдера. Токен `@InjectRepository` такой беды не знает: он считается от
+   * класса сущности, а она в пакете одна.
+   */
+  get dataSource() {
+    return this.repository.manager.connection;
+  }
+  /**
+   * Сохранить предыдущую версию сущности
+   */
+  async saveVersion(entityTable, entityId, previousData, blockNum, changeType, metadata) {
+    const version = this.repository.create({
+      entity_table: entityTable,
+      entity_id: entityId,
+      previous_data: previousData,
+      block_num: blockNum,
+      change_type: changeType,
+      metadata
+    });
+    return await this.repository.save(version);
+  }
+  /**
+   * Получить последнюю версию сущности до указанного блока
+   */
+  async getLastVersionBeforeBlock(entityTable, entityId, blockNum) {
+    return await this.repository.createQueryBuilder("version").where("version.entity_table = :entityTable", { entityTable }).andWhere("version.entity_id = :entityId", { entityId }).andWhere("version.block_num <= :blockNum", { blockNum }).orderBy("version.block_num", "DESC").addOrderBy("version.created_at", "DESC").getOne();
+  }
+  /**
+   * Удалить все версии после указанного блока (локальные изменения остаются)
+   */
+  async deleteVersionsAfterBlock(blockNum) {
+    const result = await this.repository.createQueryBuilder().delete().from(exports.EntityVersionTypeormEntity).where("block_num > :blockNum AND block_num IS NOT NULL", { blockNum }).execute();
+    return result.affected || 0;
+  }
+  /**
+   * Получить все версии для сущностей, которые нужно восстановить
+   */
+  async getVersionsForRecovery(entityTable, maxBlockNum) {
+    return await this.repository.createQueryBuilder("version").where("version.entity_table = :entityTable", { entityTable }).andWhere("(version.block_num <= :maxBlockNum OR version.block_num IS NULL)", { maxBlockNum }).orderBy("version.entity_table", "ASC").addOrderBy("version.entity_id", "ASC").addOrderBy("version.block_num", "DESC").addOrderBy("version.created_at", "DESC").getMany();
+  }
+  /**
+   * Очистить версии для указанной сущности
+   */
+  async clearVersionsForEntity(entityTable, entityId) {
+    const result = await this.repository.createQueryBuilder().delete().from(exports.EntityVersionTypeormEntity).where("entity_table = :entityTable", { entityTable }).andWhere("entity_id = :entityId", { entityId }).execute();
+    return result.affected || 0;
+  }
+};
+exports.EntityVersionRepository = __decorateClass$6([
+  common.Injectable(),
+  __decorateParam$3(0, typeorm$1.InjectRepository(exports.EntityVersionTypeormEntity))
+], exports.EntityVersionRepository);
+
+var __defProp$5 = Object.defineProperty;
+var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
+var __decorateClass$5 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$5(target, key, result);
+  return result;
+};
+exports.InvalidatedEntityTypeormEntity = class InvalidatedEntityTypeormEntity {
+};
+__decorateClass$5([
+  typeorm.PrimaryGeneratedColumn("uuid")
+], exports.InvalidatedEntityTypeormEntity.prototype, "id", 2);
+__decorateClass$5([
+  typeorm.Column({ type: "varchar", length: 100 })
+], exports.InvalidatedEntityTypeormEntity.prototype, "entity_table", 2);
+__decorateClass$5([
+  typeorm.Column({ type: "varchar", length: 64 })
+], exports.InvalidatedEntityTypeormEntity.prototype, "entity_id", 2);
+__decorateClass$5([
+  typeorm.Column({ type: "jsonb" })
+], exports.InvalidatedEntityTypeormEntity.prototype, "data", 2);
+__decorateClass$5([
+  typeorm.Column({ type: "integer" })
+], exports.InvalidatedEntityTypeormEntity.prototype, "invalidated_by_block", 2);
+__decorateClass$5([
+  typeorm.Column({ type: "varchar", length: 128, nullable: true })
+], exports.InvalidatedEntityTypeormEntity.prototype, "fork_event_id", 2);
+__decorateClass$5([
+  typeorm.CreateDateColumn({ type: "timestamp" })
+], exports.InvalidatedEntityTypeormEntity.prototype, "created_at", 2);
+exports.InvalidatedEntityTypeormEntity = __decorateClass$5([
+  typeorm.Entity("invalidated_entities"),
+  typeorm.Index("idx_invalidated_entities_block", ["invalidated_by_block"]),
+  typeorm.Index("idx_invalidated_entities_fork_event", ["fork_event_id"]),
+  typeorm.Index("idx_invalidated_entities_table_id", ["entity_table", "entity_id"])
+], exports.InvalidatedEntityTypeormEntity);
+
+var __defProp$4 = Object.defineProperty;
+var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
+var __decorateClass$4 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$4(target, key, result);
+  return result;
+};
+var __decorateParam$2 = (index, decorator) => (target, key) => decorator(target, key, index);
+exports.InvalidatedEntityRepository = class InvalidatedEntityRepository {
+  constructor(repository) {
+    this.repository = repository;
+  }
+  async bulkInsert(records) {
+    if (records.length === 0)
+      return 0;
+    const entities = records.map((r) => this.repository.create(r));
+    const saved = await this.repository.save(entities);
+    return saved.length;
+  }
+  /**
+   * Retention: удалить архив старше указанного блока. Делается отдельной транзакцией,
+   * не транзакционно с архивированием — это фоновая очистка.
+   */
+  async deleteOlderThan(minInvalidatedByBlock) {
+    const result = await this.repository.createQueryBuilder().delete().where("invalidated_by_block < :minInvalidatedByBlock", { minInvalidatedByBlock }).execute();
+    return result.affected ?? 0;
+  }
+  /**
+   * Forensic-read для AC «список из invalidated_entities, сгруппированный по fork_event_id».
+   * UI/CLI обёртка — Epic 9 (out of scope 4.4); сам repository-метод доступен из backend-кода.
+   */
+  async findGroupedByForkEventId(opts) {
+    const qb = this.repository.createQueryBuilder("inv").orderBy("inv.fork_event_id", "ASC").addOrderBy("inv.created_at", "DESC");
+    if (opts.blockNum != null) {
+      qb.where("inv.invalidated_by_block = :blockNum", { blockNum: opts.blockNum });
+    }
+    if (opts.limit != null) {
+      qb.limit(opts.limit);
+    }
+    const rows = await qb.getMany();
+    const grouped = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const key = row.fork_event_id ?? null;
+      const bucket = grouped.get(key) ?? [];
+      bucket.push(row);
+      grouped.set(key, bucket);
+    }
+    return grouped;
+  }
+};
+exports.InvalidatedEntityRepository = __decorateClass$4([
+  common.Injectable(),
+  __decorateParam$2(0, typeorm$1.InjectRepository(exports.InvalidatedEntityTypeormEntity))
+], exports.InvalidatedEntityRepository);
+
+var __defProp$3 = Object.defineProperty;
+var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
+var __decorateClass$3 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$3(target, key, result);
+  return result;
+};
+exports.InvalidatedEntityVersionTypeormEntity = class InvalidatedEntityVersionTypeormEntity {
+};
+__decorateClass$3([
+  typeorm.PrimaryGeneratedColumn("uuid")
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "id", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "varchar", length: 100 })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "entity_table", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "varchar", length: 64 })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "entity_id", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "jsonb" })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "previous_data", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "integer", nullable: true })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "original_block_num", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "integer" })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "invalidated_by_block", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "varchar", length: 128, nullable: true })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "fork_event_id", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "varchar", length: 50 })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "change_type", 2);
+__decorateClass$3([
+  typeorm.Column({ type: "jsonb", nullable: true })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "metadata", 2);
+__decorateClass$3([
+  typeorm.CreateDateColumn({ type: "timestamp" })
+], exports.InvalidatedEntityVersionTypeormEntity.prototype, "created_at", 2);
+exports.InvalidatedEntityVersionTypeormEntity = __decorateClass$3([
+  typeorm.Entity("invalidated_entity_versions"),
+  typeorm.Index("idx_invalidated_versions_block", ["invalidated_by_block"]),
+  typeorm.Index("idx_invalidated_versions_fork_event", ["fork_event_id"]),
+  typeorm.Index("idx_invalidated_versions_table_id", ["entity_table", "entity_id"])
+], exports.InvalidatedEntityVersionTypeormEntity);
+
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$2(target, key, result);
+  return result;
+};
+var __decorateParam$1 = (index, decorator) => (target, key) => decorator(target, key, index);
+exports.InvalidatedEntityVersionRepository = class InvalidatedEntityVersionRepository {
+  constructor(repository) {
+    this.repository = repository;
+  }
+  async bulkInsert(records) {
+    if (records.length === 0)
+      return 0;
+    const entities = records.map((r) => this.repository.create(r));
+    const saved = await this.repository.save(entities);
+    return saved.length;
+  }
+  async deleteOlderThan(minInvalidatedByBlock) {
+    const result = await this.repository.createQueryBuilder().delete().where("invalidated_by_block < :minInvalidatedByBlock", { minInvalidatedByBlock }).execute();
+    return result.affected ?? 0;
+  }
+};
+exports.InvalidatedEntityVersionRepository = __decorateClass$2([
+  common.Injectable(),
+  __decorateParam$1(0, typeorm$1.InjectRepository(exports.InvalidatedEntityVersionTypeormEntity))
+], exports.InvalidatedEntityVersionRepository);
+
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp$1(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+exports.EntityVersioningService = class EntityVersioningService {
+  // Токены зависимостей указаны явно, а не выведены из типов: пакет собирается
+  // unbuild/esbuild, а esbuild не умеет `emitDecoratorMetadata`. Без `@Inject`
+  // Nest не нашёл бы `design:paramtypes` и упал бы на инстанцировании сервиса.
+  constructor(entityVersionRepository, invalidatedEntityRepository, invalidatedEntityVersionRepository) {
+    this.entityVersionRepository = entityVersionRepository;
+    this.invalidatedEntityRepository = invalidatedEntityRepository;
+    this.invalidatedEntityVersionRepository = invalidatedEntityVersionRepository;
+  }
+  /**
+   * Соединение берём у репозитория, а не инъекцией `@InjectDataSource()`:
+   * у пакета и контроллера разные экземпляры `@nestjs/typeorm`, и токен
+   * источника данных не совпал бы — Nest не нашёл бы провайдера.
+   */
+  get dataSource() {
+    return this.entityVersionRepository.dataSource;
+  }
+  /**
+   * Сохранить версию сущности перед её изменением
+   */
+  async saveVersionBeforeUpdate(repository, entityTable, updatedEntity, blockNum, changeType, metadata) {
+    const existingEntity = await repository.findOne({
+      where: { _id: updatedEntity._id }
+    });
+    if (!existingEntity) {
+      return;
+    }
+    await this.entityVersionRepository.saveVersion(
+      entityTable,
+      existingEntity._id,
+      { ...existingEntity },
+      // Глубокая копия предыдущих данных
+      blockNum,
+      changeType,
+      metadata
+    );
+  }
+  /**
+   * Восстановить версии сущностей после форка
+   */
+  async restoreVersionsAfterFork(repository, entityTable, forkBlockNum) {
+    const versionsToRestore = await this.entityVersionRepository.getVersionsForRecovery(entityTable, forkBlockNum);
+    const latestVersions = /* @__PURE__ */ new Map();
+    for (const version of versionsToRestore) {
+      const existingVersion = latestVersions.get(version.entity_id);
+      if (!existingVersion) {
+        latestVersions.set(version.entity_id, version);
+        continue;
+      }
+      const shouldReplace = this.shouldReplaceVersion(existingVersion, version);
+      if (shouldReplace) {
+        latestVersions.set(version.entity_id, version);
+      }
+    }
+    for (const [entityId, version] of latestVersions) {
+      const existingEntity = await repository.findOne({
+        where: { _id: entityId }
+      });
+      if (existingEntity) {
+        Object.assign(existingEntity, version.previous_data);
+        await repository.save(existingEntity);
+      } else {
+        const restoredEntity = repository.create(version.previous_data);
+        await repository.save(restoredEntity);
+      }
+    }
+  }
+  /**
+   * Определить, должна ли новая версия заменить существующую
+   */
+  shouldReplaceVersion(existingVersion, newVersion) {
+    const existingBlockNum = existingVersion.block_num;
+    const newBlockNum = newVersion.block_num;
+    if (existingBlockNum === null && newBlockNum === null) {
+      return newVersion.created_at > existingVersion.created_at;
+    }
+    if (newBlockNum === null && existingBlockNum !== null) {
+      return true;
+    }
+    if (existingBlockNum === null && newBlockNum !== null) {
+      return false;
+    }
+    if (existingBlockNum !== null && newBlockNum !== null) {
+      return newBlockNum > existingBlockNum;
+    }
+    return newVersion.created_at > existingVersion.created_at;
+  }
+  /**
+   * Очистить версии после успешного восстановления
+   */
+  async clearVersionsAfterBlock(blockNum) {
+    return await this.entityVersionRepository.deleteVersionsAfterBlock(blockNum);
+  }
+  /**
+   * Story 4.4: атомарно перенести live-ряды WHERE block_num > forkBlockNum в архив
+   * `invalidated_entities` и удалить их из исходной таблицы. Возвращает количество
+   * перенесённых рядов. Транзакция через DataSource — INSERT и DELETE либо оба
+   * успешны, либо оба откатываются.
+   *
+   * Заменяет прежнюю пару findByBlockNumGreaterThan + deleteByBlockNumGreaterThan
+   * в hot-path handleFork (sequence сейчас: archive → restoreFromVersions →
+   * archiveVersions).
+   */
+  async archiveAndDeleteLiveAfterFork(repository, entityTable, forkBlockNum, forkEventId) {
+    return this.dataSource.transaction(async (manager) => {
+      const txRepo = manager.getRepository(repository.target);
+      const txInvalidated = manager.getRepository(exports.InvalidatedEntityTypeormEntity);
+      const rows = await txRepo.createQueryBuilder("e").where("e.block_num > :forkBlockNum", { forkBlockNum }).getMany();
+      if (rows.length === 0)
+        return 0;
+      const archiveRecords = rows.map(
+        (row) => txInvalidated.create({
+          entity_table: entityTable,
+          entity_id: row._id,
+          data: { ...row },
+          invalidated_by_block: forkBlockNum,
+          fork_event_id: forkEventId ?? null
+        })
+      );
+      await txInvalidated.save(archiveRecords);
+      await txRepo.createQueryBuilder().delete().where("block_num > :forkBlockNum", { forkBlockNum }).execute();
+      return rows.length;
+    });
+  }
+  /**
+   * Story 4.4: атомарно перенести entity_versions WHERE entity_table=... AND block_num > forkBlockNum
+   * в архив `invalidated_entity_versions` и удалить их из entity_versions.
+   * Возвращает количество перенесённых рядов.
+   *
+   * Запускается ПОСЛЕ restoreFromVersions — иначе restore не сможет прочитать
+   * ещё-живые версии.
+   */
+  async archiveAndDeleteVersionsAfterFork(entityTable, forkBlockNum, forkEventId) {
+    return this.dataSource.transaction(async (manager) => {
+      const txVersions = manager.getRepository(exports.EntityVersionTypeormEntity);
+      const txArchive = manager.getRepository(exports.InvalidatedEntityVersionTypeormEntity);
+      const versions = await txVersions.createQueryBuilder("v").where("v.entity_table = :entityTable", { entityTable }).andWhere("v.block_num > :forkBlockNum", { forkBlockNum }).getMany();
+      if (versions.length === 0)
+        return 0;
+      const archiveRecords = versions.map(
+        (v) => txArchive.create({
+          entity_table: v.entity_table,
+          entity_id: v.entity_id,
+          previous_data: v.previous_data,
+          original_block_num: v.block_num ?? null,
+          invalidated_by_block: forkBlockNum,
+          fork_event_id: forkEventId ?? null,
+          change_type: v.change_type,
+          metadata: v.metadata ?? null
+        })
+      );
+      await txArchive.save(archiveRecords);
+      const ids = versions.map((v) => v.id);
+      await txVersions.createQueryBuilder().delete().from(exports.EntityVersionTypeormEntity).whereInIds(ids).execute();
+      return versions.length;
+    });
+  }
+};
+exports.EntityVersioningService = __decorateClass$1([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(exports.EntityVersionRepository)),
+  __decorateParam(1, common.Inject(exports.InvalidatedEntityRepository)),
+  __decorateParam(2, common.Inject(exports.InvalidatedEntityVersionRepository))
+], exports.EntityVersioningService);
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+exports.BaseBlockchainRepository = class BaseBlockchainRepository {
+  constructor(repository, entityVersioningService) {
+    this.repository = repository;
+    this.entityVersioningService = entityVersioningService;
+  }
+  /**
+   * Получить имя таблицы сущности
+   */
+  getEntityTableName() {
+    const entityClass = this.repository.target;
+    if (typeof entityClass.getTableName === "function") {
+      return entityClass.getTableName();
+    }
+    return this.repository.metadata.tableName;
+  }
+  /**
+   * Найти сущность по кастомному ключу синхронизации
+   */
+  async findBySyncKey(syncKey, syncValue) {
+    const whereCondition = { [syncKey]: syncValue.toLowerCase() };
+    const entity = await this.repository.findOne({
+      where: whereCondition
+    });
+    return entity ? this.getMapper().toDomain(entity) : null;
+  }
+  /**
+   * Найти сущности с номером блока больше указанного
+   */
+  async findByBlockNumGreaterThan(blockNum) {
+    const entities = await this.repository.createQueryBuilder("entity").where("entity.block_num > :blockNum", { blockNum }).getMany();
+    return entities.map((entity) => this.getMapper().toDomain(entity));
+  }
+  /**
+   * Создать сущность если не существует
+   * Используется для синхронизации данных из блокчейна
+   */
+  async createIfNotExists(blockchainData, blockNum, present = true) {
+    const syncKey = this.getSyncKey();
+    const syncValue = this.extractSyncValueFromBlockchainData(blockchainData, syncKey);
+    const existing = await this.findBySyncKey(syncKey, syncValue);
+    if (existing) {
+      const existingBlockNum = existing.getBlockNum();
+      if (existingBlockNum != null && Number(blockNum) < Number(existingBlockNum)) {
+        return existing;
+      }
+      existing.updateFromBlockchain(blockchainData, blockNum, present);
+      return await this.save(existing);
+    } else {
+      const now = /* @__PURE__ */ new Date();
+      const minimalDatabaseData = {
+        _id: "",
+        block_num: blockNum,
+        present,
+        _created_at: now,
+        _updated_at: now,
+        [syncKey]: syncValue.toLowerCase()
+        // ключ синхронизации
+      };
+      const newEntity = this.createDomainEntity(minimalDatabaseData, blockchainData);
+      return await this.save(newEntity);
+    }
+  }
+  /**
+   * Удалить сущности с номером блока больше указанного (для обработки форков)
+   */
+  async deleteByBlockNumGreaterThan(blockNum) {
+    await this.repository.createQueryBuilder().delete().where("block_num > :blockNum", { blockNum }).execute();
+  }
+  /**
+   * Восстановить сущности из версий после форка
+   */
+  async restoreFromVersions(forkBlockNum) {
+    await this.entityVersioningService.restoreVersionsAfterFork(this.repository, this.getEntityTableName(), forkBlockNum);
+  }
+  /**
+   * Story 4.4: архивировать live-ряды WHERE block_num > forkBlockNum в invalidated_entities
+   * и удалить из исходной таблицы (атомарно). Возвращает count. Заменяет в hot-path
+   * handleFork прежнюю пару findByBlockNumGreaterThan + deleteByBlockNumGreaterThan.
+   */
+  async archiveInvalidatedSince(forkBlockNum, forkEventId) {
+    return this.entityVersioningService.archiveAndDeleteLiveAfterFork(
+      this.repository,
+      this.getEntityTableName(),
+      forkBlockNum,
+      forkEventId
+    );
+  }
+  /**
+   * Story 4.4: архивировать entity_versions WHERE entity_table=... AND block_num > forkBlockNum
+   * в invalidated_entity_versions и удалить из entity_versions (атомарно). Возвращает count.
+   * Должен вызываться ПОСЛЕ restoreFromVersions — иначе restore не сможет прочитать ещё-живые версии.
+   */
+  async archiveInvalidatedVersionsSince(forkBlockNum, forkEventId) {
+    return this.entityVersioningService.archiveAndDeleteVersionsAfterFork(
+      this.getEntityTableName(),
+      forkBlockNum,
+      forkEventId
+    );
+  }
+  /**
+   * Обновить сущность
+   */
+  async update(entity) {
+    const typeormEntity = this.getMapper().toEntity(entity);
+    await this.entityVersioningService.saveVersionBeforeUpdate(
+      this.repository,
+      this.getEntityTableName(),
+      typeormEntity,
+      typeormEntity.block_num || null,
+      "update"
+    );
+    const savedEntity = await this.repository.save(typeormEntity);
+    return this.getMapper().toDomain(savedEntity);
+  }
+  /**
+   * Создание и валидация сущности без сохранения в базу данных
+   */
+  async create(entity) {
+    const typeormEntity = this.getMapper().toEntity(entity);
+    return this.repository.create(typeormEntity);
+  }
+  /**
+   * Сохранение созданной сущности в базу данных
+   */
+  async saveCreated(entity) {
+    const savedEntity = await this.repository.save(entity);
+    return this.getMapper().toDomain(savedEntity);
+  }
+  /**
+   * Сохранить сущность
+   */
+  async save(entity) {
+    const typeormEntity = this.getMapper().toEntity(entity);
+    if (typeormEntity._id) {
+      await this.entityVersioningService.saveVersionBeforeUpdate(
+        this.repository,
+        this.getEntityTableName(),
+        typeormEntity,
+        typeormEntity.block_num || null,
+        "save"
+      );
+    }
+    const savedEntity = await this.repository.save(typeormEntity);
+    return this.getMapper().toDomain(savedEntity);
+  }
+  /**
+   * Найти все сущности
+   */
+  async findAll() {
+    const entities = await this.repository.find();
+    return entities.map((entity) => this.getMapper().toDomain(entity));
+  }
+  /**
+   * Найти сущность по внутреннему ID базы данных
+   */
+  async findById(_id) {
+    const entity = await this.repository.findOne({
+      where: { _id }
+    });
+    return entity ? this.getMapper().toDomain(entity) : null;
+  }
+  /**
+   * Удалить сущность по внутреннему ID базы данных
+   */
+  async delete(_id) {
+    await this.repository.delete(_id);
+  }
+  /**
+   * Извлечь значение ключа синхронизации из блокчейн данных
+   */
+  extractSyncValueFromBlockchainData(blockchainData, syncKey) {
+    const value = blockchainData[syncKey];
+    if (value === null || value === void 0) {
+      throw new Error(`Sync key '${syncKey}' not found in blockchain data`);
+    }
+    return value.toString().toLowerCase();
+  }
+};
+exports.BaseBlockchainRepository = __decorateClass([
+  common.Injectable()
+], exports.BaseBlockchainRepository);
+
+function auditUnknownStatus(entityName, receivedStatus, logger, allowedStatuses) {
+  if (receivedStatus === void 0 || receivedStatus === null || receivedStatus === "") {
+    return;
+  }
+  const expected = allowedStatuses && allowedStatuses.length > 0 ? `[${allowedStatuses.join(", ")}]` : "\u043D\u0435 \u0443\u043A\u0430\u0437\u0430\u043D\u043E";
+  logger.error(
+    `UNKNOWN_ENTITY_STATUS ${entityName}: \u043F\u043E\u043B\u0443\u0447\u0435\u043D '${String(receivedStatus)}', \u043E\u0436\u0438\u0434\u0430\u044E\u0442\u0441\u044F ${expected}`,
+    { entityName, receivedStatus, allowedStatuses }
+  );
+}
+
+const consoleAuditLogger = {
+  error(message, ...meta) {
+    console.error(message, ...meta);
+  }
+};
+let currentAuditLogger = consoleAuditLogger;
+function configureAuditLogger(logger) {
+  currentAuditLogger = logger;
+}
+function auditLogger() {
+  return currentAuditLogger;
+}
+
+exports.AbstractBlockchainDeltaMapper = AbstractBlockchainDeltaMapper;
+exports.BaseDomainEntity = BaseDomainEntity;
+exports.BaseTypeormEntity = BaseTypeormEntity;
+exports.FORK_AWARE_MARKER = FORK_AWARE_MARKER;
+exports.UnsupportedContractVersionError = UnsupportedContractVersionError;
+exports.auditLogger = auditLogger;
+exports.auditUnknownStatus = auditUnknownStatus;
+exports.configureAuditLogger = configureAuditLogger;
+exports.configureSyncPolicy = configureSyncPolicy;
+exports.isForkAware = isForkAware;
+exports.syncPolicy = syncPolicy;