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

패키지
dsh-pamyat-vyvoz
호환성
미검증
버전
3.1.4
라이선스
MIT
최근 업데이트
2026. 10. 22.

설치

검증된 bundle이 없거나 호환성 검사에 실패했습니다. 먼저 저장소 설명을 읽어 주세요. 전체 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).