--- read_when: - Ви перевіряєте перемикання сховища SQLite для шляху 3 на запущеному Gateway - Потрібно відрізняти очікувані розбіжності в застарілому JSONL від збоїв під час виконання - Ви створюєте або перевіряєте керований агентом інструментарій наскрізного тестування SQLite у реальному середовищі summary: Проєктування перевірки роботи Gateway наживо для перемикання сесії/транскрипту Path 3 на SQLite title: 'Шлях 3: робочий E2E-стенд SQLite' x-i18n: generated_at: "2026-07-16T18:32:13Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 2749bf47cb4967bc80a5ed37a12f2a553f3b388ed8cd90cfb3217e1b5e8afae9 source_path: reference/path3-live-sqlite-e2e-harness.md workflow: 16 --- Живий E2E-стенд Path 3 для SQLite доводить, що Gateway використовує SQLite як канонічне сховище сеансів і транскриптів, тоді як застарілі файли JSONL залишаються вхідними даними для міграції або архівними матеріалами. Це стенд для перевірки супровідниками, а не звичайний засіб діагностики для користувачів. Після того як Gateway обробив трафік після міграції, паритет із застарілими JSONL більше не є достовірним сигналом стану середовища виконання. У справному мігрованому Gateway кількість рядків транскриптів у SQLite може відрізнятися від кількості записів у застарілих JSONL, оскільки нові ходи мають просувати лише стан SQLite. Тому живий стенд повинен на кожному кроці вимірювати поведінку Gateway, зміни рядків SQLite, незмінність застарілих файлів і стан журналів. ## Формат команди Передбачена жива команда: ```bash node scripts/path3-live-sqlite-e2e.mjs \ --url http://127.0.0.1:18789 \ --agent main \ --session-key agent:main:path3-live-e2e: \ --json ``` Команда підключається до вже запущеного Gateway. Вона не запускає, не зупиняє, не імпортує та не виконує міграцію повторно, якщо згодом явно не буде додано режим міграції. Варіант для CI або ізольованого локального середовища може використовувати `test/helpers/openclaw-test-instance.ts`, але шлях живої перевірки має перевіряти фактичний операторський Gateway і його справжню окрему для кожного агента базу даних SQLite. ## Ізольована перевірка зібраного CLI Засіб перевірки зібраного CLI наповнює ізольоване застаріле сховище сеансів, запускає повторно зібраний Gateway і доводить, що під час запуску активні застарілі сеанси імпортуються до SQLite до початку читання середовищем виконання. Він не повинен запускати `openclaw doctor --fix` до першого запуску Gateway, оскільки це перевіряло б шлях ручної міграції замість шляху оновлення, який користувачі отримують під час першого запуску після перемикання. Після імпорту під час запуску ізольована перевірка може виконати `openclaw doctor --session-sqlite inspect` і `openclaw doctor --session-sqlite validate` як діагностичне підтвердження. Ці команди doctor не є рушієм міграції для перевірки оновлення під час запуску. Окремі сценарії імпорту doctor мають наповнювати застарілі файли транскриптів разом із допоміжними файлами траєкторій і перевіряти, що doctor архівує ці артефакти, тоді як SQLite залишається канонічним сховищем. ## Попередня перевірка Попередня перевірка збирає базовий стан і завершується помилкою до надсилання перевірочного ходу, якщо Gateway непридатний до використання: - `GET /health` і поглиблена перевірка стану Gateway мають повідомляти про запущений і доступний Gateway. - Версії CLI та Gateway мають відповідати гілці, що перевіряється. - Стенд записує позицію журналу для активного файлового журналу Gateway. - Стенд записує кількість рядків у таблицях SQLite для кожного агента: `sessions`, `session_entries`, `transcript_events`, `transcript_event_identities` і `session_routes`. - Стенд записує `mtime`, `size` і відомості про наявність застарілого `sessions.json`, згаданих файлів JSONL і потенційних шляхів JSONL перевірочного сеансу. - `lsof -p ` має показувати дескриптори SQLite DB/WAL/SHM і відсутність активних дескрипторів `.jsonl` або `sessions.json`. `openclaw doctor --session-sqlite validate` у живому режимі має лише інформаційне значення. Після трафіку, обробленого після перемикання, він може повідомляти про очікувану розбіжність із застарілими файлами. Стенд має використовувати вивід doctor для класифікації та інвентаризації міграції, а не як критерій проходження чи непроходження перевірки середовища виконання. ## Сценарій, керований агентом Живий сценарій використовує окремий ключ перевірочного сеансу й за можливості керує Gateway через публічні шляхи RPC. Одного ходу агента має бути достатньо для перевірки звичайного збереження, але повна перевірка має охоплювати стики 3.1b, які раніше вимагали окремих живих перевірок: - Звичайний хід чату: створити або повторно використати перевірочний сеанс, надіслати справжній запит агенту, дочекатися остаточного результату асистента й перевірити `chat.history` або еквівалентну проєкцію Gateway. - Ідентичність транскрипту: перевірити, що той самий маркер наявний в історії Gateway і в рядках транскрипту SQLite, зокрема в рядках зі стабільними ідентичностями подій, якщо вони є. - Засоби доступу до метаданих сеансу: прочитати перевірочний сеанс і вибрані наявні живі сеанси через засоби доступу Gateway/сеансу та порівняти їх із рядками SQLite. - Проєкція зміни сеансу: застосувати оборотну зміну метаданих моделі/сеансу до перевірочного сеансу, а потім перевірити, що спроєктований рядок і відповідь Gateway узгоджуються. - Життєвий цикл контрольної точки Compaction: перелічити, розгалузити й відновити контрольну точку лише для перевірочного сеансу або синтетичного сеансу-фікстури, створеного стендом. - Відновлення після перезапуску: виконати безпечний шлях маркера відновлення для контрольованого перевірочного сеансу або ізольованого тестового екземпляра; у живому режимі цей крок можна виконувати лише тоді, коли цільовий набір сеансів указаний явно, а зміни є оборотними. - Життєвий цикл очищення: видалити або скинути перевірочний сеанс, а потім перевірити рядки життєвого циклу SQLite і стан архівованого транскрипту. Специфічні для транспорту стики, які не можна безпечно перевірити на живому операторському Gateway, як-от вхідний трафік WhatsApp або голосових викликів, мають використовувати перевірки середовища виконання на рівні власника за тим самим контрактом SQLite, а не імітацію зовнішнього транспорту. ## Твердження для кожного кроку На кожному кроці створюються знімки стану до та після, а також записується структурований результат перевірки: - Кількість рядків SQLite збільшується лише там, де очікується. - Рядки траєкторії середовища виконання збільшуються для перевірочних сеансів із маркерами, які записують події середовища виконання. - Рядок перевірочного сеансу має очікувані `session_id`, стан, часові позначки, метадані та рядки маршрутів. - Проєкція історії/сеансу Gateway відповідає завершальній частині транскрипту SQLite. - Файл JSONL перевірочного сеансу не створюється й не змінюється. - Допоміжний файл `.trajectory.jsonl`, `.trajectory-path.json` або похідний від маркера `trajectory/.jsonl` для перевірочного сеансу не створюється. - Наявні застарілі файли JSONL і `sessions.json` залишаються незмінними, якщо крок явно не є операцією автономної міграції або архівування. - Процес Gateway не відкриває дескриптори `.jsonl` або `sessions.json`. - Журнали від попередньої позиції не містять `ERROR`, `FATAL`, `SQLITE_`, `no such column`, повідомлень про недоступність сховища сеансів, помилку відновлення після перезапуску або попередження про узгодження транскриптів, якщо сценарій явно не вносить їх до списку дозволених. Сканування журналів є частиною контракту проходження чи непроходження перевірки. Gateway, який відповідає на перевірки стану, але видає помилки схеми SQLite або повторювані помилки узгодження транскриптів, не вважається справним для Path 3. ## Артефакт підтвердження Стенд має записувати підтвердження в `.artifacts/path3-live-e2e//` і не додавати його до git: - `summary.json`: аргументи команди, версія Gateway, результат, невдале твердження та шляхи до артефактів. - `sqlite-before.json` і `sqlite-after.json`: кількість рядків і вибрані перевірочні рядки. - `legacy-files.json`: наявність застарілих файлів, `mtime`, розмір і відомості про те, чи змінено кожен файл. - `gateway-log-scan.json`: діапазон позицій, відповідні рядки журналу й рішення щодо списку дозволених. - `events.jsonl`: упорядковані спостереження для кожного кроку, придатні для коментарів із підтвердженням у PR. Підтвердження в PR має підсумовувати ці артефакти, а не вставляти повні транскрипти або вміст приватних повідомлень. ## Правила безпеки - Живий режим ніколи не повинен повторно імпортувати застарілі JSONL під час роботи Gateway. - Живий режим не повинен змінювати сеанси, що не є перевірочними, крім явно вибраних оборотних перевірок відновлення. - Будь-який руйнівний або масштабний крок міграції потребує свіжої резервної копії відповідної бази даних SQLite і каталогу застарілих сеансів. - Резервні копії мають обмежуватися відповідною базою даних агента/каталогом сеансу й повторно використовуватися протягом одного запуску перевірки, щоб уникнути необмеженого збільшення використання диска. - Після кроку очищення не повинно залишатися перевірочного сеансу, перевірочного JSONL або зміненого застарілого файлу, якщо викликаць не передає `--keep-artifacts`. ## Успішний результат Успішний живий запуск означає, що Gateway прийняв справжній керований агентом потік сеансу, увесь спостережуваний канонічний стан містився в SQLite, застарілі файли середовища виконання залишалися незмінними, а стан журналів був чистим протягом вимірюваного проміжку. Це не означає, що паритет із застарілими JSONL залишається точним після живого трафіку; щойно SQLite стає канонічним сховищем, розбіжність у живому середовищі є очікуваною.