Дневные чанки сессий — .tesserae/session_chunks.db

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end --> Оконные запросы по сессиям — tesserae summary, tesserae decisions и activity-действия планировщика ask — раньше заново парсили каждый попадающий в окно транскрипт Claude Code / Codex при каждом вызове. Хранилище дневных чанков сохраняет каждый нормализованный ход один раз, разложенным по меткам дней KST, так что полностью покрытый прошедший день отдаётся из SQLite вместо сырого пересканирования. Замер на реальном корпусе из многих тысяч сессий показывает, что оконные сводки становятся ~в 20 раз быстрее.

Хранилище — один файл SQLite, .tesserae/session_chunks.db (WAL, короткоживущее соединение на операцию): таблица turns с индексом по дню, таблица day_coverage, фиксирующая, какие пары (day, harness) полны, и таблица meta с версией схемы.

Кто его пишет

1. Живой путь — тейлер движка. Пока работает tesserae engine, тейлер сессий дописывает ходы в хранилище по мере их чтения, на каждый опрос, и апсертит покрытие для затронутых дней (source: "tailer"). Путь записи — только-добавление, идемпотентен относительно повторно доставленных ходов и никогда не бросает исключение в цикл демона. Здесь сознательно нет писателя на хуке SessionEnd — фоновые писатели SessionEnd накапливаются (зафиксированный сценарий отказа).
2. Backfill. Две точки входа обходят существующие транскрипты и заполняют историю (source: "backfill"):
3. tesserae refresh запускает backfill автоматически как часть своего шага импорта сессий, так что первый refresh после обновления наполняет хранилище без дополнительных действий.
4. tesserae sessions chunk-backfill [--since YYYY-MM-DD] запускает его явно; --since ограничивает глубину обхода (по умолчанию: вся история).

Backfill берёт неблокирующий flock на .tesserae/session_chunks.lock с семантикой «пропустить, если занято» — конкурирующий backfill (или движок, уже удерживающий блокировку) заставляет второго вызывающего чисто пропустить, а не встать в очередь. Апсерты backfill ключуются по (session_path, ts, role, hash(text)), поэтому строки тейлера и строки backfill никогда не дублируют друг друга. Однодневное перекрытие на инкрементальных backfill «лечит» ходы, приземлившиеся после того, как покрытие дня было впервые заявлено.

Кто его читает

Быстрый путь живёт в единственной точке сканирования (activity_summary.iter_project_transcripts / scan_messages), поэтому всё ниже по течению наследует его прозрачно:

• tesserae summary (включая встроенный сбор decisions)
• tesserae decisions
• tesserae ask — действия планировщика activity_summary / decisions
• MCP activity_summary и query_decisions
• представление живых сессий

Правило покрытия: сегодняшний день всегда сканируется в сыром виде

Окно отдаётся из чанков, только когда выполняется всё следующее:

1. это ровно один день, выровненный по KST;
2. этот день строго раньше сегодняшнего — сегодняшний день ещё пишется, поэтому он всегда идёт через сырое сканирование транскриптов;
3. строка day_coverage существует для каждого запрошенного harness в этот день.

Всё остальное для этого окна откатывается к сырому сканированию.

Гарантия отката к сырому сканированию

Хранилище чанков — ускоритель, но никогда не источник истины:

• Любая ошибка БД, отсутствующий/повреждённый файл или несовпадение schema_version дают из чанк-пути ничего — сырое сканирование транскриптов у вызывающего идёт ровно как раньше. Несовпадение схемы сбрасывает и пересоздаёт хранилище пустым; покрытие исчезает вместе с ним, поэтому откат остаётся корректным.
• Дни без покрытия (например, движок не работал и backfill не выполнялся) молча идут по медленному пути. Корректно, но ускорение пропадает — tesserae doctor сообщает о пропусках покрытия в недавнем окне и указывает на tesserae sessions chunk-backfill (см. doctor.md).
• Инвариант паритета: для полностью покрытого дня отданные из чанков ходы равны тому, что дало бы сырое сканирование (те же timestamp, role, name, text, ключ сессии и harness).

Эксплуатационные заметки

• Держите tesserae engine запущенным — и прошедшие дни остаются покрытыми вживую; иначе периодический tesserae refresh (или явный chunk-backfill) закрывает пропуски.
• Хранилище существует на проект, живёт под .tesserae/ и его всегда можно безопасно удалить — следующий backfill пересоздаст его, а читатели тем временем откатываются к сырым сканированиям.