iia-arg/dsh-plugins--packages-dsh-pamyat-vyvoz ↗★ 2

dsh-pamyat-vyvoz

Вывоз и ввоз памяти агента: перенос смысла между базами, а не копия файла · Agent memory export and import: moving meaning between databases, not copying a file

Package
dsh-pamyat-vyvoz
Compatibility
Unverified
Version
3.1.4
License
MIT
Last updated
Oct 22, 2026

Install

This plugin has no verified bundle, or compatibility checks failed. Read the repository notes first. Read the full README ↗

dsh-pamyat-vyvoz — вывоз и ввоз памяти агента: перенос смысла между базами, а не копия файла

Версия · Version: 3.1.4

Назначение

Копия базы памяти возвращает машину в прежнее состояние. Вывоз отвечает на другой вопрос: как перенести знание туда, где схема другая, номера записей свои и наших правил доверия нет. Копию нельзя влить в живую базу, а вывоз — можно. Пакет читает таблицу zapisi базы памяти SQLite и пропускает каждую запись через фильтр секретов ядра dsh-pamyat-core. Результат — файл JSONL: строка-заголовок и по строке на запись, без местных id. Ввоз берёт такой файл, проверяет его целиком и вставляет записи в другую базу одной транзакцией.

Вывоз обязан фильтровать: фильтр ядра стоит на входе, и всё, что легло в базу до его появления, никем не проверено. Своих правил у пакета нет — решает ядро. Отвечает оно одним из трёх режимов:

  • zapiraet — запись задерживается;
  • pomechaet — запись уезжает с пометкой pometka_filtra;
  • neizvesten — на вывозе останавливается весь вывоз (код 1, файла нет), на ввозе отклоняется запись.

Пакет — не плагин и не работает по расписанию. Его зовёт человек, рукой: перенос памяти имеет последствия на другой машине и не должен случаться, пока никто не смотрит. Вывоз доступен скриптом vyvoz-pamyati и функцией vyvezti(), ввоз — только функцией vvezti(). Читает результат тот, кто ввозит файл. Кроме того, каждая операция оставляет строку в таблице zhurnal той базы, которую она трогала. Живых потребителей в бою нет (запись dsh-pamyat-vyvoz реестра: «ЗОВУТ РУКОЙ, В БОЮ НЕ ЖИВЁТ»).

Что ставится и куда

В бой ничего не ставится. Запись dsh-pamyat-vyvoz в /etc/agent-registry/plugins.yaml (раздел plugins) указывает на дерево выпусков: инструмент живёт там, боевой установки нет по замыслу. Поля derevo.files у записи нет.

файл в пакетепуть на машинережим, владелецкто исполняет / читает
bin/vyvoz-pamyati.mjs/opt//workspace/dsh-plugins/packages/dsh-pamyat-vyvoz/bin/vyvoz-pamyati.mjs0755 :рука: node …/bin/vyvoz-pamyati.mjs … (в package.json объявлен как bin vyvoz-pamyati)
src/index.js…/dsh-pamyat-vyvoz/src/index.js0644 :точка входа пакета (main, exports "."): vyvezti, otchyot, vvezti, otchyot_vvoza, схема и договор с ядром
src/vyvoz.js…/src/vyvoz.js0644 :вывоз: чтение базы, фильтр, заголовок, атомарная запись файла
src/vvoz.js…/src/vvoz.js0644 :ввоз: проверка файла, фильтр, вставка одной транзакцией
src/yadro.js…/src/yadro.js0644 :поиск фильтра ядра и проверка договора с ним
src/shema.js…/src/shema.js0644 :версия схемы файла, переносимые поля POLYA, непереносимое с причинами NE_VYVOZITSYA, сумма содержимого
src/zhurnal.js…/src/zhurnal.js0644 :строка-след в таблицу zhurnal базы

Не исполняются: test/ (стенды), docs/, README.md, README.en.md, CHANGELOG.md. Подробности о внутреннем устройстве — в docs/ARCHITECTURE.md, docs/SETTINGS.md, docs/GUARDS.md и docs/TROUBLESHOOTING.md. Текущая версия — package.json и CHANGELOG.md.

Что нужно на машине:

  • Node.js 22.13.0+ в ветке 22, либо 23.4.0+: нужен node:sqlite и readOnly. На Node 22 возможен ExperimentalWarning в stderr — сам по себе он не означает отказ; судить по коду выхода. Текущий прогон — Node 24.19.0. Минимум соответствует официальной истории SQLite API; ранние 22.5–22.12 требуют экспериментального флага и не входят в этот договор.
  • ядро dsh-pamyat-core с файлом src/filtr-vhoda.js (нижняя граница версии — peerDependencies в package.json). В дереве оно лежит соседним каталогом ../dsh-pamyat-core и находится само.

Что операции пишут:

  • вывоз — файл, названный --fajl (права 0600; сначала пишется временный файл .chastichnyj- , потом переименовывается), и строку в zhurnal базы-источника;
  • ввоз — записи в zapisi базы-получателя и строку в её zhurnal.

Установка

Можно звать пакет из проверенного дерева выпусков: рядом должны лежать dsh-pamyat-vyvoz и dsh-pamyat-core. Для отдельной установки подготовь локальные архивы этой головы; ожидаемое ядро среза — 3.1.1. В npm доступна редакция 3.1.3 (замер 15.10.2026, npm view dsh-pamyat-vyvoz version). По решению владельца от 14.10.2026 изменения после публикации ведутся локально и в npm не выкладываются. Для описанной локальной проверки используйте архивы выбранной головы.

# CORE_SOURCE / VYVOZ_SOURCE — каталоги исходников пакетов
# ARTIFACTS — существующий каталог для архивов
(cd "$CORE_SOURCE" && npm pack --ignore-scripts --pack-destination "$ARTIFACTS")
(cd "$VYVOZ_SOURCE" && npm pack --ignore-scripts --pack-destination "$ARTIFACTS")
# В отдельном каталоге автономного CLI, без обращения к реестру:
npm install --offline --ignore-scripts --legacy-peer-deps \
  /absolute/path/dsh-pamyat-core-3.1.4.tgz \
  /absolute/path/dsh-pamyat-vyvoz-3.1.4.tgz
./node_modules/.bin/vyvoz-pamyati --help

Сверь SHA архивов, версии обоих package.json и наличие bin/vyvoz-pamyati.mjs/src/filtr-vhoda.js. Справка возвращает 2, это не ошибка установки. --legacy-peer-deps здесь нужен для автономного фильтра/CLI; для монтирования самого ядра в DSH его платформенные peers ставят по инструкции ядра. Вывоз не монтируется в ход агента. npx без уже установленного bin не использовать: он может пойти в registry за другим пакетом.

Правка идёт так (поле update записи реестра): правка в рабочем каталоге дерева → ворота → выпуск. В ход агента пакет не монтируется. Юнитов и таймеров нет.

Вызов вывоза — от учётки, которой читается база (для строки журнала нужна ещё и запись):

# проба: что уехало бы; файл не создаётся, строка журнала пишется
node /opt//workspace/dsh-plugins/packages/dsh-pamyat-vyvoz/bin/vyvoz-pamyati.mjs \
     --baza /opt//pamyat/pamyat.db --otkuda 

# вывоз в файл
node /opt//workspace/dsh-plugins/packages/dsh-pamyat-vyvoz/bin/vyvoz-pamyati.mjs \
     --baza /opt//pamyat/pamyat.db --otkuda  --fajl /путь/vyvoz.jsonl

Ввоз — только из программы:

import { vvezti, otchyot_vvoza } from '/opt//workspace/dsh-plugins/packages/dsh-pamyat-vyvoz/src/index.js';
const it = await vvezti({ baza: '/путь/к/базе-получателю.db', fajl: '/путь/vyvoz.jsonl' });
console.log(otchyot_vvoza(it));

Настройка

Переменных окружения пакет не читает. Вся настройка — ключами скрипта и полями объекта, передаваемого в функцию. Неизвестное поле объекта — отказ VYVOZ_NEIZVESTNYJ_KLYUCH. Неизвестный ключ скрипта отказывает с кодом 2 до чтения данных.

Вывоз: vyvoz-pamyati / vyvezti({...})

ключ скриптаполе vyveztiумолчаниесмысл
--baza baza— (обязателен)база-источник; записи читаются только на чтение, строка журнала пишется отдельным соединением на запись
--otkuda otkuda— (обязателен, умолчания нет)имя источника в заголовке файла; пусто или одни пробелы — отказ VYVOZ_NET_OTKUDA
--fajl fajlнеткуда писать; без него — проба: отчёт есть, файла нет. Одноимённый файл заменяется без спроса
--yadro yadroцепочка: по имени пакета dsh-pamyat-core/src/filtr-vhoda.js → соседний каталог ../dsh-pamyat-core → свой node_modulesпуть к фильтру ядра; явный путь отменяет цепочку
--agent otbor.agentвсетолько записи этого агента
--klass otbor.klassвсетолько этот класс
--s otbor.sбез нижней границызаписи не раньше; мс epoch или дата, понятная Date.parse (в API — только мс)
--po otbor.poбез верхней границызаписи не позже
—krikconsole.errorкуда печатать громкие сообщения (потеря следа в журнале и т. п.)
--help, --pomoshch, без доводов——справка, код 2

Отбор по полю, которого в базе нет, — отказ VYVOZ_OTBOR_NET_POLYA, а не молчаливый пропуск условия.

Ввоз: vvezti({...})

полеумолчаниесмысл
baza— (обязателен)существующая база-получатель; отсутствует — VYVOZ_BAZA_NE_SUSHHESTVUET, файл не создаётся
fajl— (обязателен)файл вывоза
yadroта же цепочкапуть к фильтру ядра
krikconsole.errorкуда печатать громкие сообщения

Состав файла (зашит в src/shema.js):

  • версия схемы — VERSIYA_SHEMY;
  • переносимые поля — POLYA;
  • что не переносится и почему — NE_VYVOZITSYA: id, журнал, очередь доставки, настройки схемы, счётчики выдач, отметка сверки.

pometka_filtra — известная транспортная пометка в JSONL, не сохраняется в БД при ввозе. Приёмник заново фильтрует каждое поле POLYA своим ядром; пометка не меняет решение фильтра и не объявляется неизвестным полем. Исходный JSONL функция не удаляет; сохрани его, если нужна эта пометка.

Проверка

Новый выпуск добавляет stend-audit-boundaries.mjs (31 проба CLI/API) и stend-audit-docs.mjs (8 проб документации). Старый stend-vyvoza.mjs сохраняет свои 60 проб; npm test запускает все три входа.

Стенд: в каталоге пакета npm test, то есть node test/vse-stendy.mjs. Обходчик берёт с диска все test/stend-*.mjs и называет .mjs, лежащие рядом не по образцу. Исходный стенд stend-vyvoza.mjs сохраняет 60 проб:

  • договор с ядром и его порчи;
  • запирающие и незнакомые классы;
  • отчёт без содержимого;
  • чужие id и чужая схема;
  • атомарность и тождество;
  • ограничения;
  • круг «вывоз → ввоз» с посимвольной сверкой.

Ядро нужно соседним каталогом ../dsh-pamyat-core. Базы и файлы стенд создаёт во временном каталоге (TMPDIR) и убирает на любом выходе. Коды обходчика:

  • 0 — все стенды зелёные;
  • 1 — хоть один разошёлся;
  • 2 — слепота: стенд вернул код вне 0/1, убит сигналом, или стендов нет.

Прогон 09.10 на коде метки dsh-pamyat-vyvoz-v1.1.19 (= master): «итог: 60 из 60», код 0.

Из записи dsh-pamyat-vyvoz реестра:

  • installed_check: node -p "require('/opt//workspace/dsh-plugins/packages/dsh-pamyat-vyvoz/package.json').version";
  • healthcheck: cd /opt//workspace/dsh-plugins/packages/dsh-pamyat-vyvoz && npm test;
  • fingerprint_check: состав npm pack --dry-run без .bak, sha256 каждого файла, свёртка в 16 знаков; должна совпасть с fingerprint записи.

Коды скрипта vyvoz-pamyati:

  • 0 — вывоз состоялся (или проба);
  • 1 — отказ по предмету: VYVOZ_NEZNAKOMYJ_KLASS, VYVOZ_OTBOR_NET_POLYA;
  • 2 — слепота: всё остальное. Сюда входят нет ядра или договор не выполнен (VYVOZ_DOGOVOR_YADRA), база не открылась, доводы не поняты, VYVOZ_NET_OTKUDA, VYVOZ_NEIZVESTNYJ_KLYUCH, ошибка записи файла, справка.

Отказы ввоза (исключение с полем code) все случаются до первой записи в базу, база не тронута:

  • VYVOZ_PUSTOJ_FAJL, VYVOZ_NET_ZAGOLOVKA, VYVOZ_NE_NASH_FAJL;
  • VYVOZ_CHUZHAYA_SHEMA, VYVOZ_ZAGOLOVOK_BEZ_OTKUDA;
  • VYVOZ_BITAYA_STROKA, VYVOZ_CHUZHIE_ID, VYVOZ_SUMMA_NE_SOSHLAS;
  • VYVOZ_DOGOVOR_YADRA, VYVOZ_NEIZVESTNYJ_KLYUCH.

Ошибка базы во время вставки откатывает транзакцию целиком.

Ограничения

  • Не проверено живым переносом между двумя машинами (поле nepolno записи реестра). Круг «вывоз → ввоз» мерили на копии живой базы одного узла и на стенде.
  • «Задержано 0» значит «фильтр не нашёл запирающего», а не «секретов нет». Фильтр ядра знает свой перечень форм и пропустит незнакомую, в том числе закодированную внутри поля. Поле-BLOB проверяется ещё и как текст UTF-8. На запись решение принимается по одной находке ядра в каждом поле.
  • Договор с ядром проверяет форму ответов фильтра, а не его правоту. Что найденное ядро — той редакции, которую ждали, не проверяется: печатается только звено цепочки, откуда оно взято. Код ядра исполняется при импорте, до всех проверок.
  • Новый класс в ядре, о котором вывоз не знает, останавливает весь вывоз до правки пакета. Это цена выбора: утечка необратима, остановка — нет.
  • Не заменяет ночную копию базы. Не сливает знания и не разрешает противоречий: две записи об одном предмете останутся двумя. О правдивости записи не судит.
  • Не переносит файл на другую машину и не решает, где его хранить.
  • Проба (без --fajl) всё равно пишет строку в журнал базы-источника с исходом tolko-otchyot. Строка журнала пишется отдельным соединением на запись: нет прав на запись или нет таблицы zhurnal — след не появится, о чём будет сказано, а операция при этом состоится.
  • Запись файла атомарна (временный файл рядом и переименование), но без fsync: при сбое питания файл может оказаться пустым или старым.
  • Сумма содержимого — первые 32 шестнадцатеричных знака sha256 (128 бит), хотя приставка sha256: называет её полной. Ввоз сверяет сумму, только если она есть в заголовке. У файла старого вывоза без суммы обрыв на границе строки не виден, и об этом говорит итог ввоза.
  • Ввоз присваивает свои номера. Тождество записи — «агент + источник + время создания»; если в базе нет поля agent — «источник + время». Смысловые дубли с другим тождеством не ловятся.
  • Поля, которых нет в схеме базы-получателя, и поля вне договора POLYA при ввозе теряются. Они называются поимённо в итоге и в предупреждении. В БД эти значения не размещены; восстановить их можно из сохранённого исходного JSONL, который функция ввоза не удаляет.
  • Запись класса ogranichenie ложится с bez_podtverzhdeniya=1. Если такого поля в базе нет, ограничения ввозятся без пометки, и это попадает в итог отдельной строкой.
  • На базе без таблицы zapisi вывоз отказывает ошибкой SQL, а не отдельным понятным сообщением.
  • Неизвестное имя CLI — отказ с кодом 2 до вывоза; опечатка не означает «вывезти всё».

Лицензия и авторы

Лицензия MIT (package.json). Авторы — команда Iia-arg. Исходники семейства: (каталог packages/dsh-pamyat-vyvoz).