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

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

<domain>
## 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

</domain>

<decisions>
## 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

</decisions>

<specifics>
## Specific Ideas

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

</specifics>

<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>
## 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

</deferred>

---

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