ajuste no contas

docs/FIX_CHECKPOINT_NAMESPACE_TRANSACTION_CONFIRMATION_20260901.md

@@ -0,0 +1,16 @@
+# Fix: isolamento do checkpoint LangGraph e snapshot do gateway
+
+## Problema
+O gateway gravava `checkpoints.put(agent_session_id, {state: result, ...})` após `workflow.ainvoke()`.
+O LangGraph saver usa o mesmo repositório e a mesma chave `thread_id == agent_session_id`.
+Assim, o snapshot simplificado do gateway sobrescrevia o checkpoint nativo do LangGraph, removendo canais transacionais como `active_transaction`, `pending_tool_call`, `confirmation_snapshot` e `confirmation_required`.
+
+## Correção
+O snapshot do gateway passou a usar o namespace `gateway:<session_id>`.
+O checkpoint LangGraph continua usando `<session_id>` sem interferência.
+O endpoint `/sessions/{session_id}/checkpoint` consulta o snapshot `gateway:<session_id>` para preservar o contrato de debug existente.
+
+## Invariante
+- checkpoint LangGraph: chave `<session_id>`
+- snapshot/debug do gateway: chave `gateway:<session_id>`
+- nenhuma gravação externa pode sobrescrever o checkpoint nativo do LangGraph.