surfaces/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md

Phase 01.1: Matrix restart reconciliation and dev reset workflow - Context

Gathered: 2026-04-03 Status: Ready for planning

## Phase Boundary

Сделать Matrix-адаптер пригодным для повторяемой локальной разработки и ручного QA без ручного “ритуала” удаления БД, выхода из всех комнат и пересоздания пользователя.

В scope этой фазы:

• безопасный restart flow для Matrix-бота после потери локального state
• reconciliation локального store с уже существующими Matrix rooms / Space
• отдельный dev reset workflow для controlled clean-room QA
• диагностируемое поведение при несогласованности local state и server-side Matrix state

Вне scope:

• реальный Lambda SDK
• новые пользовательские Matrix features
• E2EE
• production-grade multi-user migration framework

## Implementation Decisions

Matrix state lifecycle

• D-01: Локальный SQLite store больше не должен считаться единственной точкой истины для Matrix runtime в dev workflow.
• D-02: При старте бот должен пытаться восстановить минимально необходимое локальное состояние из уже существующих Matrix rooms / Space, а не требовать full reset.
• D-03: Reconciliation должен восстанавливать как минимум matrix_user:*, matrix_room:* и missing chat:{user}:{chat_id} записи, если серверные комнаты уже существуют.
• D-04: Reconciliation не должен создавать новые Space/rooms, если задача — именно восстановление локального state после рестарта.

Dev restart behavior

• D-05: Обычный restart бота должен быть основным путём для разработки; удаление lambda_matrix.db и matrix_store не должно быть обязательным для проверки workflow.
• D-06: Если local state неполон, бот должен либо восстановить его, либо логировать понятную причину, а не падать на командах вроде !rename.
• D-07: Несогласованность между room_meta и ChatManager должна обнаруживаться и устраняться автоматически на startup или при первом обращении.

Dev reset workflow

• D-08: Нужен отдельный dev-only reset tool/script для controlled QA, вместо ручного набора shell-команд.
• D-09: Reset workflow должен как минимум поддерживать local-only reset: удаление lambda_matrix.db и matrix_store с понятной инструкцией, что делать с server-side Matrix rooms.
• D-10: Если full server-side cleanup не автоматизируется в этой фазе, tool должен явно печатать, какие ручные шаги обязательны в Matrix client.

The agent's Discretion

• Точное место вызова reconciliation в startup flow
• Внутренняя структура helper-модуля (bootstrap.py, reconcile.py или аналог)
• Формат dev reset script и уровень автоматизации server-side cleanup
• Детали debug-logging и dry-run режима, если они помогают без раздувания scope

## Specific Ideas

• Главный критерий: после обычного restart бот не должен ломаться только потому, что local DB была сброшена или частично потеряна.
• Reset workflow должен быть явным и repeatable, а не завязанным на память разработчика.
• Нужно различать две ситуации:
  • broken because code is wrong
  • broken because local dev state was deliberately reset and requires reconciliation

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Matrix phase artifacts

• .planning/phases/01-matrix-qa-polish/01-CONTEXT.md — locked Matrix decisions from Phase 1
• .planning/phases/01-matrix-qa-polish/01-VERIFICATION.md — what Phase 1 already validated and what manual QA still expects
• .planning/phases/01-matrix-qa-polish/01-HUMAN-UAT.md — remaining real-client Matrix checks

Current Matrix runtime

• adapter/matrix/bot.py — startup flow, sync loop, runtime wiring, DB/store env vars
• adapter/matrix/store.py — persisted Matrix metadata and pending confirmation keys
• adapter/matrix/room_router.py — room_id to chat_id resolution and current unregistered fallback
• adapter/matrix/handlers/auth.py — invite bootstrap that creates Space and first chat room
• core/chat.py — ChatManager persistence contract that currently breaks when local state is missing

Supporting docs

• docs/matrix-prototype.md — intended Matrix UX and architecture direction
• README.md — current run instructions and existing manual QA/reset habits

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• adapter/matrix/store.py already persists room/user metadata and is the obvious place to anchor reconciliation inputs.
• adapter/matrix/room_router.py already detects unknown rooms via unregistered:{room_id} fallback; this is a useful reconciliation trigger point.
• core/chat.py already has get_or_create, rename, archive, list_active; missing chat records can be rebuilt through this API instead of inventing a parallel format.

Established Patterns

• Matrix runtime uses SQLiteStore for adapter-local metadata and matrix-nio room callbacks for transport events.
• Phase 1 already moved Matrix to Space+rooms and command-only confirmations, so this phase must preserve that model rather than reverting to DM-first simplifications.

Integration Points

• Startup path in adapter/matrix/bot.py:main() is the natural place to run reconciliation before sync_forever.
• Invite/bootstrap path in adapter/matrix/handlers/auth.py is the existing source of truth for what metadata a healthy first room should have.
• ChatManager records and matrix_room:* metadata must stay consistent enough that commands like !rename, !archive, and !chats work after restart.

</code_context>

## Deferred Ideas

• Full production-grade migration of historical Matrix state across schema versions
• Automatic server-side deletion/leave for all Matrix rooms and Space during reset, if it requires broader admin semantics
• Any Phase 2 SDK integration work

---

Phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow Context gathered: 2026-04-03