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
インストール
検証済み bundle がないか、互換性チェックに失敗しています。先にリポジトリの説明を読んでください。 README 全文を読む ↗
ドキュメント
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.mjs | 0755 : | рука: node …/bin/vyvoz-pamyati.mjs … (в package.json объявлен как bin vyvoz-pamyati) |
src/index.js | …/dsh-pamyat-vyvoz/src/index.js | 0644 : | точка входа пакета (main, exports "."): vyvezti, otchyot, vvezti, otchyot_vvoza, схема и договор с ядром |
src/vyvoz.js | …/src/vyvoz.js | 0644 : | вывоз: чтение базы, фильтр, заголовок, атомарная запись файла |
src/vvoz.js | …/src/vvoz.js | 0644 : | ввоз: проверка файла, фильтр, вставка одной транзакцией |
src/yadro.js | …/src/yadro.js | 0644 : | поиск фильтра ядра и проверка договора с ним |
src/shema.js | …/src/shema.js | 0644 : | версия схемы файла, переносимые поля POLYA, непереносимое с причинами NE_VYVOZITSYA, сумма содержимого |
src/zhurnal.js | …/src/zhurnal.js | 0644 : | строка-след в таблицу 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 | без верхней границы | записи не позже |
| — | krik | console.error | куда печатать громкие сообщения (потеря следа в журнале и т. п.) |
--help, --pomoshch, без доводов | — | — | справка, код 2 |
Отбор по полю, которого в базе нет, — отказ VYVOZ_OTBOR_NET_POLYA, а не молчаливый пропуск условия.
Ввоз: vvezti({...})
| поле | умолчание | смысл |
|---|---|---|
baza | — (обязателен) | существующая база-получатель; отсутствует — VYVOZ_BAZA_NE_SUSHHESTVUET, файл не создаётся |
fajl | — (обязателен) | файл вывоза |
yadro | та же цепочка | путь к фильтру ядра |
krik | console.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).