Ediciones multarchivo atómicas para agentes de programación: la lección de Semaprax

Cuando un agente de programación cambia varios archivos dependientes, no basta con reemplazar cada archivo de forma segura. El proyecto necesita un único límite de publicación. Sin él, un proceso de build, un servidor de lenguaje, un watcher de pruebas u otro agente puede leer parte del programa antiguo y parte del nuevo.

Nos encontramos con este problema al desarrollar Semaprax, nuestro lenguaje de sistemas experimental orientado a agentes. La lección sirve más allá del lenguaje: prepara una generación inmutable completa, verifícala y después cambia un pequeño puntero activo. Este artículo explica el patrón, sus límites y las preguntas que un comprador técnico debería hacer antes de confiar en cualquier promesa de ediciones “atómicas”.

¿Qué es una edición multarchivo atómica?

Una edición multarchivo atómica hace visible a sus lectores definidos un estado antiguo completo o un estado nuevo completo, nunca una mezcla intermedia. La frase queda incompleta hasta que el sistema identifica a esos lectores, los archivos incluidos, el punto de commit y el modelo de fallo.

Imagina un cambio que renombra una función exportada y actualiza su llamada en otro archivo. Si cambia primero la definición, un watcher puede ver la llamada antigua junto a la definición nueva. Si cambia primero la llamada, observa la inconsistencia contraria. Ambos archivos pueden contener texto válido y, aun así, el programa combinado ser inválido durante ese instante.

La lección: publicar generaciones, no una secuencia de escrituras

Semaprax necesitaba una forma acotada de publicar cambios verificados en varios archivos fuente. Su decisión de arquitectura descarta el reemplazo secuencial porque un lector puede observar una generación mixta. El diseño elegido conserva generaciones completas e inmutables y selecciona una mediante un único registro ACTIVE. La decisión de arquitectura de Semaprax fijada a una revisión documenta la solución y las alternativas rechazadas.

.semaprax-workspace/
  ACTIVE
  generations/
    <revision-antigua>/
    <revision-candidata>/

La ruta de escritura tiene cinco fases distintas:

1. Vincular la propuesta a una revisión base. Si el workspace seleccionado cambió, la operación se rechaza.
2. Validar cada archivo afectado. Todas las operaciones se resuelven contra la misma base autenticada.
3. Construir el candidato completo por separado. También incluye los archivos sin cambios para formar una generación íntegra.
4. Verificar el candidato completo. Se comprueban formatos, identidades, límites, digests y las invariantes que el protocolo afirma.
5. Cambiar un único puntero. Tras las comprobaciones finales solo se reemplaza ACTIVE. Un lector cooperante resuelve el puntero y lee una generación inmutable.

¿Por qué no basta con renombrar un archivo de forma atómica?

Escribir un archivo temporal y renombrarlo sobre el destino es un patrón valioso para un solo archivo. Rust documenta std::fs::rename como una operación de renombrado y describe diferencias por plataforma y fallos entre puntos de montaje. La API no ofrece una transacción portable sobre un conjunto arbitrario de rutas. Consulta el contrato de rename de la biblioteca estándar de Rust.

Repetir la operación para cinco archivos crea cinco momentos de publicación. Si un lector actúa entre el segundo y el tercero, el programa sigue expuesto como mezcla. La atomicidad por archivo no se convierte automáticamente en atomicidad de proyecto.

¿Git no hace ya atómicos los cambios multarchivo?

Un commit de Git identifica un árbol completo, pero no convierte cada transición del working tree vivo en una operación atómica para editores, watchers u otros procesos. Publicar el historial del repositorio no es lo mismo que cambiar los archivos que leen herramientas activas.

Git muestra la importancia de definir bien el límite. git update-ref puede verificar un object ID anterior y agrupar cambios de referencias en una transacción. Su documentación también advierte que un lector concurrente puede ver solo parte de varias modificaciones de referencias, aunque cada referencia se actualice de forma atómica. La documentación oficial de Git sobre update-ref es un buen modelo para versiones esperadas y estados transaccionales explícitos.

Usa ramas, worktrees y commits para colaboración, revisión y recuperación. Añade una capa de publicación gestionada solo cuando los consumidores en ejecución deban observar un snapshot coherente durante el cambio.

Por qué las generaciones inmutables son un patrón práctico

Las generaciones inmutables trasladan la mayor parte del riesgo antes del punto de commit. Un candidato puede construirse, inspeccionarse y rechazarse sin modificar el estado seleccionado. La operación final es pequeña porque cambia un puntero, no todos los archivos de carga.

El patrón no es exclusivo de herramientas para agentes. Nix explica las actualizaciones atómicas de forma similar: los paquetes no se sobrescriben y un perfil pasa a una nueva generación, lo que evita una ventana con archivos antiguos y nuevos mezclados. La guía oficial de arquitectura de Nix aporta un ejemplo maduro del patrón.

La parte específica de los agentes es la evidencia. Una respuesta convincente del modelo no debería tener autoridad de commit. El sistema debe conservar la revisión base, las operaciones propuestas, el digest candidato, los resultados de validación y el resultado del cambio de puntero para que otro componente pueda comprobarlo.

Qué implementa realmente Semaprax y qué no

En el commit auditado, Semaprax define una transacción acotada para entre 2 y 16 archivos .spx gestionados. Los escritores toman un bloqueo exclusivo, construyen o autentican una generación candidata completa, ejecutan comprobaciones finales y reemplazan ACTIVE. Los lectores cooperantes toman un bloqueo compartido y resuelven la generación inmutable seleccionada. La especificación fijada de la transacción de workspace define formato, límites, diagnósticos, evidencia y exclusiones.

El límite importa más que el titular. El protocolo no vuelve atómicos los archivos fuente sin gestionar, Git, los editores ni los lectores no cooperantes. No promete comportamiento en sistemas de archivos de red, durabilidad ante pérdida de energía, rollback automático, semántica general del repositorio ni reparación multarchivo arbitraria. Semaprax sigue siendo investigación prealfa y este artículo no convierte evidencia acotada en una afirmación de madurez productiva.

Construir o comprar: ocho preguntas para proveedores

1. ¿Qué lectores están protegidos? Pregunta si la garantía cubre solo la API o también working tree, servidores de lenguaje, builds y procesos externos.
2. ¿Cuál es la revisión base? Toda propuesta necesita una versión esperada y un rechazo claro cuando queda obsoleta.
3. ¿Dónde está el punto de commit? “Usamos archivos temporales” no responde a la pregunta multarchivo.
4. ¿Se valida el candidato completo? Las comprobaciones de sintaxis por archivo no detectan todas las roturas entre archivos.
5. ¿Quién tiene autoridad de escritura? El output del modelo, la evidencia y los tokens de aprobación no deben convertirse en poder de commit reutilizable.
6. ¿Qué sucede antes y después del cambio? El rechazo previo y la ambigüedad posterior necesitan recuperaciones distintas.
7. ¿Qué durabilidad se ha probado? Caída del proceso, del sistema operativo, pérdida de energía y almacenamiento de red son fallos diferentes.
8. ¿La evidencia es reproducible? Pide pruebas hostiles, fixtures fijos, límites y versiones exactas, no solo una demo.

¿Cuándo necesitas esta arquitectura?

Probablemente no necesitas un protocolo de generaciones para un agente que propone un parche, se detiene y espera la revisión humana de un diff normal de Git. Considéralo cuando el trabajo autónomo modifica varios archivos acoplados mientras builds, servicios u otros agentes leen continuamente el workspace y un estado mixto puede activar un despliegue, generación de código, migración o acción irreversible.

Empieza una capa antes si el agente no puede identificar las entidades correctas. Nuestra nota de Semaprax sobre identidad semántica explica los IDs estables y los parches ligados a revisiones. La guía de harnesses para agentes de IA sitúa la publicación dentro del sistema de contexto, políticas, herramientas, verificación y observabilidad.

Preguntas frecuentes

¿Los commits de Git son atómicos?

Un commit identifica un árbol completo. Eso no garantiza que los lectores activos de un directorio cambiante nunca observen estados intermedios.

¿Escribir atómicamente equivale a tener rollback?

No. La publicación atómica define qué se hace visible en el punto de cambio. Rollback, limpieza y recuperación tras un fallo son contratos separados.

¿Las generaciones inmutables evitan conflictos de merge?

No. Controlan la visibilidad para lectores cooperantes. La coordinación de ramas, los conflictos semánticos y la revisión humana siguen aparte.

Nota editorial: OpenAI Codex ayudó con la investigación, la redacción y la traducción. Wavect comprobó las afirmaciones técnicas el 6 de septiembre de 2026 contra el commit 942ed70 de Semaprax y la documentación primaria enlazada. No se infieren afirmaciones de rendimiento ni de madurez productiva a partir del output del modelo.