Solución de problemas

Algo en AWR no se comporta como esperas. Esta guía trabaja de los síntomas a las soluciones: primero las comprobaciones de salud, luego los problemas de base de datos y luego los cambios interrumpidos en tus archivos fuente. Cada sección da el comando exacto a ejecutar y cómo leer la salida. Para los comandos del día a día, consulta Flujo de trabajo diario y Referencia de la CLI.

Paso uno: ejecuta una comprobación de salud

AWR incluye un comando de diagnóstico incorporado llamado Doctor, en dos niveles:

awr --json doctor --database-only
awr --json doctor

--database-only comprueba la base de datos SQLite en sí: integridad, claves foráneas, versión del esquema, identidades de migración y objetos de esquema propiedad de AWR.
El doctor completo además inspecciona tus archivos fuente seleccionados y las vinculaciones entre los registros del runtime y los archivos en disco.

Doctor abre la base de datos en solo lectura. No migra el esquema, no reindexa fuentes, no aplica mutaciones pendientes, no expira reservas ni elimina archivos huérfanos: así que siempre es seguro ejecutarlo, incluso en un proyecto dañado.

Leer los hallazgos de Doctor

Doctor informa de los problemas como hallazgos explícitos en lugar de adivinar:

schema_issues — tablas, columnas, índices o disparadores propiedad de AWR ausentes o modificados, comprobados contra las migraciones incluidas. Los objetos extra pueden coexistir; Doctor no reparará definiciones ni imprimirá su SQL.
foreign_key_check_error — una referencia malformada impidió que SQLite siquiera ejecutara su comprobación de claves foráneas. Si ves este campo, la base de datos no está sana, y un cero de violaciones informado significa «no pudimos contarlas», no «todo está bien».
Sesiones activas — solo informativo; un registro antiguo no prueba que el proceso esté muerto.
Dependencias ausentes, aristas colgantes, fuentes no disponibles, guardados interrumpidos y artefactos dañados o no registrados se informan cada uno como hallazgos. Las páginas ilegibles o una base de datos ajena (no AWR) producen errores explícitos, no un estado engañoso.

Síntoma: «AWR rechazó mi archivo fuente»

Cuando un archivo fuente YAML tiene un error de sintaxis o un campo de tipo incorrecto, AWR falla con el código de error InvalidInput y detalles estructurados:

{
  "location": {
    "locator": "file:///project/work.yaml",
    "pointer": "/work_items/0/title",
    "line": 3,
    "column": 10
  },
  "rule": "ledger.string",
  "repair": "Use a quoted string or a YAML block scalar (|) for multiline text."
}

Cómo leerlo: pointer nombra el campo ofensor usando el vocabulario de tu propio archivo fuente (incluidos los nombres de campo en chino configurados); line y column empiezan en uno. Los errores de sintaxis puros pueden tener solo coordenadas del analizador, y algunas búsquedas (como los alias de YAML) conservan el puntero con coordenadas nulas: eso no rechaza un archivo por lo demás válido. rule nombra la expectativa fallida; repair describe la estructura esperada. Nunca edita el archivo ni devuelve el valor rechazado.

Un caso común: escribiste title: [Draft, Review], que YAML analiza como una lista, pero el campo requiere una cadena. Si la coma era literal:

title: "Draft, Review"

Para descripciones multilínea usa un escalar de bloque YAML (|); el texto en chino válido y las rutas con espacios están totalmente soportados.

Síntoma: «Mis cambios no aparecen en las consultas»

Editaste un archivo fuente pero AWR sigue mostrando hechos antiguos. Ejecuta una reindexación:

awr source reindex

Luego comprueba ambas partes del informe: el éxito de la operación y la completitud de la proyección. Un escaneo puede tener éxito mientras la proyección sigue incompleta, porque el escaneo observa las fuentes sin importar sus hechos modificados. El mismo informe llega como JSON con --json y por MCP awr_source_reindex. Compara la salida desde instantáneas iniciales equivalentes; la reindexación en sí actualiza el estado de la fuente.

Si la evidencia de un elemento de trabajo parece incorrecta, work show (o MCP awr_work_get) informa evidence_groups junto a la lista plana evidence. Cada grupo tiene un localizador exacto; una referencia de fuente y un informe verificado en la misma ruta permanecen distintos, y la agrupación nunca transfiere la verificación entre registros.

Síntoma: «La base de datos está corrupta o perdida»

Tus archivos fuente son la autoridad para los hechos del proyecto, pero la base de datos SQLite (.awr/state.db) también contiene estado que esos archivos no contienen: sesiones, reservas, puntos de control, eventos del runtime, registros de artefactos e intentos de mutación. La reindexación actualiza las proyecciones desde las fuentes, pero no puede reconstruir ese historial del runtime — y tampoco puede hacerlo inicializar una base de datos nueva desde las mismas fuentes.

Hacer copias de seguridad correctamente

Para una instantánea recuperable, conserva todo esto junto, y pausa los escritores del proyecto mientras lo reúnes (la API de backup de SQLite da una imagen coherente de la base de datos, pero no captura los archivos circundantes):

Una copia de seguridad coherente de .awr/state.db hecha con la API de backup de SQLite o herramientas equivalentes: copiar el archivo mientras hay escritores activos puede perder registros confirmados que aún están en el registro de escritura anticipada (write-ahead log).
Los archivos fuente correspondientes, la revisión de Git, .awr/project.toml, la configuración de raíz autorizada y cualquier fuente externa explícitamente autorizada.
Los archivos de artefactos gestionados, los artefactos locales registrados fuera del directorio gestionado y los diarios e instantáneas de recuperación de .awr/mutations referenciados por operaciones pendientes.

Restaurar

Detén el proyecto.
Restaura en la raíz canónica registrada; conserva el estado desplazado en lugar de borrarlo.
Ejecuta awr --json doctor --database-only y luego awr --json doctor completo.

Una restauración puede recuperar un registro de artefacto mientras su archivo sigue ausente: restaura el archivo o deja el hallazgo sin resolver. awr source reindex no es ni una restauración del runtime ni una herramienta de reubicación de la base de datos.

Doctor puede realizar reparaciones con nombre, pero solo con la revisión actual del proyecto, un objeto seleccionado y una razón; las reparaciones preservan las fuentes y el estado del runtime no relacionado. Si la integridad de la base de datos está rota, las reparaciones de runtime sugeridas están deshabilitadas: no hay reconstrucción automática.

Síntoma: «Una mutación se interrumpió a media escritura»

AWR aplica las propuestas aprobadas a tus archivos fuente con guardas de durabilidad: instantáneas inmutables de antes/después se guardan antes de que el intento se registre, y el éxito requiere los bytes de fuente previstos, una proyección reconstruida y el evento final de aplicación. Si un proceso muere a media escritura, el intento queda abierto y recuperable.

Si recibes MutationIncomplete con write_outcome: pending_recovery, inspecciona primero:

awr --json doctor
awr --json proposal show PROPOSAL_ID

Lee el project_revision actual de la salida y luego reanuda la propuesta:

awr --json proposal recover PROPOSAL_ID \
  --actor reviewer \
  --reason "Resume the interrupted report review" \
  --expected-revision CURRENT_REVISION

Lo que hace la recuperación depende de hasta dónde llegó el intento:

Estado tras la interrupción	Qué hace la recuperación
Existen instantáneas, no hay diario de aplicación	La fuente no ha cambiado; un `proposal apply` nuevo puede comenzar.
Existe el diario, la fuente aún coincide con «antes»	Revalida propiedad, configuración, fuente y revisión, y luego instala los bytes de «después» registrados.
La fuente ya coincide con «después», proyección incompleta	Reconstruye la proyección sin reescribir el archivo.
Proyección confirmada, evento final ausente	Valida la proyección y confirma el evento final: sin segunda escritura del archivo.
Evento final confirmado, respuesta perdida	Devuelve el recibo duradero; repetir la recuperación falla con `InvalidTransition`, sin evento duplicado.
La fuente o las instantáneas discrepan del plan registrado	Preserva la fuente, informa del conflicto y retiene la finalización.

Un reintento correcto informa recovered, nombra el intento original y vincula su resolved_event_id al evento final.

Dos cosas que no hacer:

No edites las instantáneas para forzar un resultado. Si la fuente actual no coincide con ninguna instantánea, resuelve el conflicto de la fuente y prepara una propuesta nueva.
No asumas que un reintento escribió el archivo. source_write_performed describe solo la invocación actual: es por eso que la recuperación revalida primero.

Concurrencia: los escritores de AWR se coordinan mediante un bloqueo del SO por fuente y comprobaciones transaccionales de expected_revision. Las fuentes separadas progresan de forma independiente, pero una revisión de proyecto intermedia puede requerir un reintento de recuperación explícito. Los editores externos no se unen al bloqueo; las comprobaciones de huellas detectan sus cambios.

Cuándo parar y pedir ayuda

Para y escala en lugar de improvisar cuando:

Doctor informa de integridad de base de datos rota (foreign_key_check_error, páginas ilegibles): las reparaciones de runtime están deshabilitadas, sin reconstrucción automática.
Una recuperación de mutación informa de un conflicto fuente/instantánea: la ruta soportada es una propuesta nueva, no editar a mano instantáneas o diarios.
Tu escenario implica pérdida de energía de la máquina, escritores distribuidos u otros sistemas operativos: las garantías de recuperación cubren la interrupción de procesos locales; más allá de eso no está establecido.

Antes de pedir ayuda o abrir un issue, captura el estado mientras está fresco:

awr --json doctor --database-only
awr --json doctor
awr --json proposal show PROPOSAL_ID   # if a mutation is involved

Conserva intactos la base de datos desplazada, los diarios de .awr/mutations y los archivos fuente relevantes: hacen que un informe sea accionable y son tu red de seguridad si la corrección sale mal.