---
read_when:
    - Ви реалізуєте clawdbot-d63.2 / clawdbot-04b
    - Ви змінюєте механізми зберігання, скидання, видалення сеансів SQLite або їх архівування під час видалення агента
    - Потрібно відрізняти сімейства артефактів епохи SQLite від застарілих супровідних файлів JSONL
summary: План шляху 3 для архівування всіх артефактів транскриптів SQLite, що належать до сеансу
title: 'Шлях 3: сімейство артефактів сеансу SQLite'
x-i18n:
    generated_at: "2026-07-16T18:13:21Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: adb2c31293ab63cb80449d037600d78fbb228e91f380d1ccaf15fb00728a9057
    source_path: plan/path3-sqlite-session-artifact-family.md
    workflow: 16
---

# Сімейство артефактів сеансів SQLite для шляху 3

Ця примітка визначає межі `clawdbot-d63.2`, тоді як `clawdbot-d63.1` відповідає за пов’язаний
допоміжний засіб архівування під час скидання/видалення в `src/config/sessions/session-accessor.sqlite.ts`.
Під час цього проходу файл реалізації містив незбережені зміни, тому цей артефакт фіксує
точний контракт і точки внесення змін, не створюючи конфлікту з паралельним виконавцем.

## Авторитетне сімейство

Після переходу на SQLite активні стенограми сеансів зберігаються в рядках SQLite. Сімейство
архіву сеансу:

- Рядки `transcript_events`, `transcript_event_identities` і `sessions`
  для поточного `sessionId` запису.
- Той самий набір рядків стенограми SQLite для кожного `sessionId`, на який
  посилається `entry.compactionCheckpoints[*].preCompaction.sessionId`.
- Той самий набір рядків стенограми SQLite для кожного `sessionId`, на який
  посилається `entry.compactionCheckpoints[*].postCompaction.sessionId`.
- Той самий набір рядків стенограми SQLite для кожного `sessionId` у
  `entry.usageFamilySessionIds`.

Архівуйте лише рядки, на які більше не посилається жоден із решти
рядків `session_entries` або метадані Compaction чи сімейства використання
будь-якого запису, що залишився. Це зберігає стан розгалуження/відновлення контрольної точки
та агрегування використання, доки не зникне останнє активне посилання.

## Артефакти поза сімейством після переходу

Згенеровані варіанти файлів стенограм тем і бічні файли траєкторій не є активним
станом середовища виконання SQLite. Це застарілі файлові артефакти:

- Варіанти тем, як-от `<sessionId>-topic-<thread>.jsonl`, існують лише для
  файлового формату стенограм. SQLite використовує канонічний ідентифікатор сеансу разом із
  метаданими доставки `session_routes`/запису замість окремих файлів JSONL для кожної теми.
- Бічні файли траєкторій, як-от `.trajectory.jsonl` і `.trajectory-path.json`,
  отримують назви зі справжніх шляхів JSONL `sessionFile`. Значення SQLite `sessionFile` є
  маркерами `sqlite:<agentId>:<sessionId>:<storePath>` і не позначають бічні
  файли.
- Засоби читання архівного рівня мають і надалі читати застарілі архівовані файли JSONL, але
  утримання середовища виконання не має сканувати каталоги активних сеансів або повторно відкривати файли
  стенограм JSONL для сеансів SQLite.

Імпорт Doctor залишається власником міграції застарілих основних файлів JSONL і
суміжних із ними бічних файлів траєкторій. Утримання SQLite у середовищі виконання не має додавати
другий імпортер або резервний файловий шлях.

## Точки внесення змін

Розширте допоміжний засіб архівування SQLite, доданий у `clawdbot-d63.1`, замість
додавання паралельного шляху.

1. Додайте локальний збирач поруч із `deleteSqliteSessionStateIfUnreferenced`:
   - `collectSqliteSessionArtifactFamily(entry: SessionEntry): Set<string>`
   - Включіть `entry.sessionId`, ідентифікатори сеансів до/після контрольної точки та
     `usageFamilySessionIds`.
   - Відфільтруйте порожні рядки та детерміновано усуньте дублікати.

2. Додайте збирач посилань для сховища після видалення:
   - `readReferencedSqliteSessionArtifactFamilyIds(database): Set<string>`
   - Переберіть поточні `session_entries`, проаналізуйте кожен `entry_json` і зберіть
     ті самі ідентифікатори сімейства з кожного запису, що залишився.

3. Змініть виклики скидання/видалення/обслуговування, які зараз архівують один
   видалений `sessionId`, щоб вони передавали повне сімейство видаленого запису.

4. Для кожного ідентифікатора сімейства архівуйте рядки стенограми SQLite із зазначеною викликачем
   причиною (`reset` або `deleted`), а потім видаляйте рядок `sessions` лише тоді, коли
   ідентифікатор сімейства відсутній у наборі посилань після видалення.

5. Залиште видалення подій стенограми централізованим через наявний шлях
   очищення рядків сеансу SQLite. Не додавайте читання активних JSONL.

## Цільові тести

Додайте тести лише для SQLite до `src/config/sessions/session-accessor.conformance.test.ts`
або до пов’язаного тесту життєвого циклу після фіксації змін у `clawdbot-d63.1`:

- Видалення запису зі стенограмою до Compaction архівує як поточний
  сеанс, так і сеанс до Compaction, а потім видаляє обидва набори рядків SQLite.
- Видалення одного з двох записів, які спільно використовують сеанс до Compaction, не архівує
  нічого для спільного попереднього сеансу, доки не буде видалено останній запис,
  що на нього посилається.
- Видалення запису з `usageFamilySessionIds` архівує рядки стенограми SQLite
  попередника, якщо жоден інший запис не посилається на це сімейство використання.
- Ключ сеансу у формі теми з маркером SQLite не спричиняє читання будь-якого згенерованого
  JSONL теми або пошуку бічного файла.

Для цільової перевірки слід використати:

```bash
node scripts/run-vitest.mjs src/config/sessions/session-accessor.conformance.test.ts
```

Якщо фінальні тести розміщено в `store.session-lifecycle-mutation.test.ts`, запустіть цей
файл явно за допомогою тієї самої обгортки. Широкі перевірки `pnpm` мають виконуватися на
Crabbox/Testbox для цього робочого дерева Codex.
