---
read_when:
    - Вы реализуете clawdbot-d63.2 / clawdbot-04b
    - Вы изменяете архивацию сеансов SQLite при их хранении, сбросе, удалении или удалении агента
    - Необходимо отличать семейства артефактов эпохи SQLite от устаревших сопутствующих файлов JSONL
summary: План пути 3 по архивированию всех артефактов расшифровок SQLite, относящихся к сеансу
title: Семейство артефактов сеанса SQLite для пути 3
x-i18n:
    generated_at: "2026-07-13T18:18:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    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`,
  именуются на основе реальных путей `sessionFile` к JSONL. Значения `sessionFile` SQLite являются
  маркерами `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,
  для общей сессии до 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` для этого рабочего дерева Codex должны выполняться
в Crabbox/Testbox.
