ADR 0050 — El repositorio guarda su estado

Estado: aceptado · Fecha: 2026-10-24

Contexto

Desde M32 el proyecto analizado vive en el repositorio, no en la app: el escritorio escribe .codarch/snapshot.cc.json y .codarch/report.json, y al arrancar restaura de ahí. Eso dejó tres sitios con papeles distintos, pero solo uno estaba escrito:

• .codarch.yml, en la raíz: alcance, reglas, addons y perfil de dominio. Es configuración y se versiona.
• .codarch/: snapshot, reporte y mapa. Es estado derivado y no se versiona.
• .codarch-history/: la línea del tiempo. Se versiona a propósito, porque es lo que un equipo comparte (ADR 0024).

El repaso dejó cuatro huecos:

1. El escritorio añadía .codarch/ al .gitignore del repo, pero el CLI (codarch analyze) no: analizar desde la terminal dejaba el estado como ficheros sin seguimiento.
2. El escritorio lo añadía en cada guardado, así que quitar la línea del .gitignore no servía de nada: volvía en el siguiente análisis.
3. Analizar una subcarpeta (repo/src) crea su propio .codarch/ y no había regla escrita sobre si debía heredar el del repo.
4. codarch serve --watch reanaliza en memoria, pero el escritorio no vigila nada: su mapa se queda viejo hasta que se vuelve a analizar a mano.

Lo único que la app guarda fuera del repo es lo de la máquina: la última raíz analizada y las preferencias de vista.

Decisión

1. Tres sitios, tres papeles

• .codarch.yml (raíz, versionado): la configuración declarativa. Viaja con el repo y la lee también el CI.
• .codarch/ (ignorado): el estado derivado del análisis. Se puede borrar sin miedo; se reconstruye. Incluye el snapshot, el reporte, el mapa, el libro de cadenas (.codarch/chains.json), que se deriva del historial, y las preferencias de vista del repo (preferences.json, ADR 0053).
• .codarch-history/ (versionado): la línea del tiempo. No se mete dentro de .codarch/ porque entonces dejaría de compartirse.

2. Quien crea el estado lo ignora en git

El CLI y el escritorio añaden .codarch/ al .gitignore del repositorio solo cuando el directorio nace, sin tocar el resto del fichero y sin repetir la entrada si ya está (.codarch/ o .codarch valen igual). Si el usuario quita la línea para versionar el estado, no vuelve.

Un --out distinto de .codarch/ no toca el .gitignore. serve analiza en memoria y no escribe el estado del análisis; si calcula el libro de cadenas, lo cachea en .codarch/chains.json (que es derivado) y deja .codarch/ ignorado al crearlo.

3. El estado se ancla en la carpeta analizada

Analizar repo/src escribe repo/src/.codarch/, aunque repo/.codarch/ ya exista. Un snapshot de src/ no es el del repo y no puede pisarlo. La app enseña qué raíz está viendo.

Buscar el .codarch/ más cercano hacia arriba queda descartado por ahora: es más limpio, pero convierte un análisis parcial en una escritura sobre el estado del repo entero. Si molesta la duplicación, se resuelve con una acción explícita («analizar el repo desde su raíz»), no en silencio. Las rutas del sistema se rechazan antes de analizar (ADR 0052).

La dirección contraria sí se abre: un análisis puede leer el estado de los .codarch/ que tiene por debajo, sin escribir en ellos, para no reparsear lo que ya está parseado (ADR 0089). Lo prohibido sigue siendo mirar hacia arriba.

4. Global, lo mínimo

En la máquina quedan solo la última raíz y las preferencias de vista; el proyecto, su configuración y su estado viven en el repo. Abrir otro repositorio no hereda nada del anterior.

5. A tiempo real

Una sola vigilancia compartida (watchRepository, con chokidar) para el CLI y el escritorio: la misma lista de exclusiones, el mismo agrupado de ráfagas y el mismo respeto a los renombrados de los editores. No se vigila .git, node_modules, .codarch/ (para no realimentarse) ni las carpetas de salida.

El escritorio empieza a vigilar al analizar o restaurar un repo, reanaliza al guardar y solo reescribe .codarch/ si el checksum cambió; el mapa recibe el snapshot nuevo. La cabecera dice live mientras vigila. Al abrir un repo que ya tiene estado, enseña lo guardado al instante y reanaliza detrás: los cambios hechos sin la app se ven antes de ponerse en live.

Consecuencias

• Analizar desde el CLI o desde el escritorio deja el repo limpio en git sin que el usuario toque nada.
• El estado se puede borrar y regenerar; no es una copia de seguridad.
• Analizar subcarpetas no rompe el estado del repo, pero puede duplicarlo; el mapa dice qué raíz se está viendo.
• Vigilar consume CPU y disco: el retardo, el respeto a .gitignore y el nivel de detalle lo acotan.
• El historial sigue siendo lo único que un equipo comparte por git; el resto es de cada máquina.

Alternativas descartadas

• Reutilizar el .codarch/ del ancestro: más limpio, pero un análisis de src/ sobrescribiría el snapshot del repo. Se puede ofrecer como acción explícita más adelante.
• Meter el historial en .codarch/: se perdería justo lo que se quiere compartir.
• Guardar el estado en el directorio de instalación: un proyecto por máquina y la web no lo vería; es lo que arregló M32.
• Ignorar en cada análisis: impediría versionar el estado si alguien lo quiere.
• Escribir .codarch/ desde serve: sirve para mirar; escribir convertiría un servidor de solo lectura en otro dueño del estado.

Hoja de ruta

M34 — El estado vive en el repositorio

Estado: cerrada.

• El escritorio escribe .codarch/ en el repo y lo ignora al crearlo (M32).
• El CLI analyze ignora .codarch/ cuando lo crea; --out no toca el .gitignore.
• La cabecera dice si el repo se vigila: live, live en pausa o sin vigilancia.
• Al abrir un repo con .codarch/, enseñar lo guardado al instante y refrescar en segundo plano.
• Una vigilancia compartida (watchRepository, chokidar) para serve y el escritorio.
• El libro de cadenas y el historial viven en el repo; un fichero suelto no mezcla estados.
• Probar la regla de anclaje con subcarpetas y decir en la app qué raíz se está viendo: la banda enseña la fuente del snapshot y el título de la ventana, la carpeta; el anclaje tiene su test diferencial en el ADR 0089.
• Reutilizar el parseo de los alcances anidados, leyendo siempre hacia abajo (ADR 0089).
• La vigilancia se pausa desde los ajustes (live / live en pausa), también en el escritorio.

El registro de lo hecho vive en el feed de la guía.