# Arquitectura

> Agent NAS tiene cuatro capas y una capa de sincronización opcional: Interface proyecta las capacidades en interfaces existentes, Trust es el único punto de autorización, Memory convierte las notas en conocimiento consultable y Store guarda un árbol con historial. La capa Memory se puede borrar y reconstruir entera, y Store simplemente usa almacenamiento maduro.

## Cuatro capas y sincronización opcional

- **Interface (interfaz)**: Proyecta las capacidades en interfaces que los agentes, las personas y las herramientas ya usan. Las pasarelas no tienen estado y nunca deciden quién puede hacer qué. (Montaje (FUSE, NFS, SMB), Git, Compatible con S3, WebDAV, MCP, API HTTP, CLI, A2A (opcional))
- **Trust (confianza)**: El único punto de autorización. Un motor de políticas determinista sin ningún modelo en la decisión; primero se registra y después se actúa. (Sujetos y ejecuciones, Capability Lease, Motor de políticas, Human Gate, Trust Labels, Credential Broker, Flight Recorder)
- **Memory (memoria)**: Convierte las notas en conocimiento consultable y legible con presupuesto. Todo se puede reconstruir a partir de la capa inferior. (Convenciones de notas, Índices (texto completo, vectorial, grafo), Budgeted Reads, Tareas de mantenimiento, Linaje, Cascade Forget)
- **Store (almacén)**: Un árbol con historial, sobre instantáneas maduras del sistema de archivos, Git o almacenamiento de objetos versionado. No entiende la memoria ni las etiquetas. (Tree, Commit, Agent Branch, Instantáneas del sistema de archivos, Git, Almacenamiento de objetos)
- **Sync (sincronización, opcional)**: Replicación y uso compartido entre nodos. Va al final a propósito: primero hay que dejar bien un solo nodo. (Remotos de Git, Transferencia de instantáneas, Enlaces de concesión, Paquetes de traspaso)

- **La capa Memory es reconstruible.** Borra todos los índices y reconstruye, y las notas de Store siguen siendo totalmente legibles.
- **Las pasarelas no tienen estado.** Todo el estado persistente está en Store y en los registros de Trust; una pasarela puede reiniciarse libremente y escalar en horizontal.
- **Trust es el único punto de autorización.** Eso incluye las tareas en segundo plano del propio NAS (indexación, mantenimiento): también se ejecutan como principals `svc:*` con concesiones.
- **Store no entiende la memoria ni la semántica de las etiquetas.** Solo guarda un árbol con metadatos.
- **Primero se registra, después se actúa.** Una operación con consecuencias debe escribir antes un registro de intención.

## La cintura estrecha: seis sustantivos

Todo el diseño depende de seis sustantivos; las etiquetas, las compuertas, la memoria y los manifiestos de lectura son convenciones construidas encima.

| Sustantivo | Significado | Invariante clave |
| --- | --- | --- |
| Tree | Un árbol de directorios con historial. | Cualquier commit se puede reproducir; hay un hash de contenido o una detección de cambios equivalente. |
| Commit | Un cambio inmutable. | Lleva metadatos de procedencia: `principal`, `on_behalf_of`, `run`, `lease`. |
| Principal | Una entidad que puede autenticarse y rendir cuentas. | El tipo es `human`, `agent`, `service` o `node`; un `agent` pertenece a un rol, no a una ejecución. |
| Run | Una ejecución con principio, fin, propósito y un responsable. | Tiene una concesión raíz; es dueña de una rama. |
| Lease | La autorización de una ejecución. | Tiene caducidad; solo se puede acotar más; es revocable; lleva presupuestos. |
| Record | Un registro de solo anexado. | Encadenado por hashes; primero se registra, después se actúa. |

## La capa Store: contrato y motores opcionales

El contrato de Store lo proporciona un motor o lo emula la pasarela. Una implementación puede combinar motores, por ejemplo Git para el texto e instantáneas para los archivos grandes; el contrato no prescribe el motor, la función hash ni el formato en disco.

1. Commits atómicos.
2. Bifurcaciones baratas: idealmente cercanas a O(1); en el peor caso degradándose a una copia, y entonces las cuotas y un TTL son obligatorios.
3. Instantáneas inmutables.
4. Detección de cambios: un hash de contenido o un equivalente.
5. La diferencia entre dos commits.
6. Exportación completa en un formato estándar: un directorio, el historial de Git y los metadatos `.nas/` en texto plano.

| Motor | Adecuado para | Coste de bifurcar | Nota |
| --- | --- | --- | --- |
| Git (con worktrees) | Texto, memoria, habilidades, bases de código pequeñas | Bajo | Los archivos grandes necesitan LFS o almacenamiento externo; las fusiones binarias son malas. |
| Instantáneas y clones del sistema de archivos (ZFS, btrfs, APFS) | Directorios grandes, archivos mixtos | Cercano a O(1) | Depende del sistema de archivos; copiar entre máquinas necesita send/receive. |
| Almacenamiento de objetos versionado (forks de Tigris, lakeFS, S3 más un manifiesto) | Conjuntos de datos, archivos grandes | Cercano a O(1) | Necesita que la pasarela ofrezca una vista de archivos. |
| Directorio normal más copia | Empezar con Lite | O(n) | Solo para datos pequeños; las cuotas y un TTL son obligatorios. |

> **La vía de recuperación queda fuera del radio de impacto.** Las instantáneas y las copias de seguridad están en manos del principal propietario, y ninguna concesión puede incluir “borrar una instantánea” ni “borrar una copia de seguridad”. Es la lección más directa del incidente de abril de 2026: la vía de recuperación debe quedar fuera del radio de impacto de lo que protege.

- El cifrado en reposo viene de la capa inferior; la clase de retención `sensitive` usa su propio dominio de claves, de modo que se puede destruir eliminando la clave.
- La deduplicación y la destrucción entran en conflicto: la clase `sensitive` no se deduplica entre dominios de claves.

## El recorrido de una ejecución

1. **Solicitar.** El orquestador (o el propietario) solicita una concesión para una ejecución: rutas, acciones, caducidad, propósito. Dentro del **sobre de políticas** se emite de forma automática; fuera de él pasa a una Human Gate.
2. **Empezar.** El NAS crea el `run` y la rama `<role>/<run_id>` y entrega la concesión a la ejecución; el sandbox monta la rama (o hace un `git clone`).
3. **Trabajar.** El agente lee y escribe con herramientas de archivos normales. Las lecturas se acumulan en el **manifiesto de lectura** y la contaminación de la sesión se actualiza con ellas; el acceso fuera de los límites se rechaza y se registra.
4. **Hacer commit.** Los cambios se confirman con un commit de forma automática (con retardo) o explícita, y cada commit lleva metadatos de procedencia.
5. **Proponer.** `propose` crea un **Agent PR**: el diff, la intención, un resumen del manifiesto de lectura, los resultados de las comprobaciones y un resumen de etiquetas.
6. **Decidir.** El motor de políticas decide: si las comprobaciones pasan y el riesgo es bajo, se fusiona de forma automática; si hay datos protegidos, una acción hacia el exterior o una violación de la Rule of Two, pasa a una Human Gate; si está claramente prohibido, se rechaza.
7. **Fusionar y registrar.** La fusión crea un commit con procedencia y escribe un Record.
8. **Cerrar.** La concesión caduca; la rama se recicla tras su TTL; los manifiestos de lectura y los Records se conservan según la política de retención.

**La ruta de lectura:** solicitud, comprobación de la concesión, comprobación de etiquetas (¿permite la contaminación actual de la sesión esta lectura?), recuento del presupuesto, lectura desde Store, anotación en el manifiesto de lectura, y devolución del contenido y de los punteros de evidencia.

> **Primero se registra, después se actúa.** Una operación con consecuencias (fusionar, borrar, compartir, enviar al exterior, cambiar una concesión) debe escribir antes un registro de intención; si no se puede escribir, la operación falla (fail closed). Las lecturas van al manifiesto de lectura, que se vuelca por lotes y no necesita ser síncrono en cada lectura.

## Formas de despliegue

| Forma | Descripción | Adecuado para |
| --- | --- | --- |
| Lite | Una sola máquina y un solo usuario: un proceso de pasarela más almacenamiento local (Git o instantáneas del sistema de archivos); L0 a L1. | Particulares y desarrolladores que lo prueban. |
| Overlay | Deja en paz el NAS o el almacén de objetos existente: una pasarela se coloca delante y gestiona solo un directorio o un bucket; los montajes y la vista S3 pasan por la pasarela. | **El punto de partida más realista:** quien ya tiene un equipo. |
| Team | Varios usuarios y agentes, un servidor o un clúster pequeño; L0 a L3; notificaciones de compuertas y una sala de control. | Equipos pequeños. |
| Cloud | Un servicio alojado multiinquilino con aislamiento fuerte; L0 a L3. | Quien no tiene hardware propio. |

El principio: no se necesita hardware especial y vale cualquier máquina siempre encendida; los aceleradores son opcionales, porque bastan modelos pequeños para los embeddings y los resúmenes, y también se pueden llamar servicios externos.

## Construir una v0 con piezas existentes

| Capacidad | Piezas que puedes usar hoy |
| --- | --- |
| Store y ramas | Git y worktrees; instantáneas de btrfs o ZFS; o Tigris y lakeFS (almacenamiento de objetos). |
| Línea principal protegida | Protección de ramas en Forgejo, Gitea o GitHub; o ramas protegidas de lakeFS. |
| Concesiones | Un servidor de autorización OAuth (por ejemplo Keycloak) con intercambio de tokens, y un servidor de recursos que compruebe el prefijo de la ruta y la acción; o un servicio de firma de unos cientos de líneas. |
| Registros | Una tabla SQLite de solo anexado más un hash diario; trailers de Git en los commits; exportación con OpenTelemetry. |
| Compuertas | Revisión de PR más una notificación push; la CLI `nas gate approve`. |
| Memoria | Markdown bajo `memory/` más SQLite FTS5; un almacén vectorial se añade después. |
| Etiquetas | Marca el directorio de importación como `external`; guarda la contaminación de sesión de cada ejecución en la pasarela. |
| Interfaces | Un montaje NFS, SMB o FUSE; Git sobre SSH o HTTPS; una pasarela S3; un pequeño servidor MCP. |

Lo que dice esta tabla: **L0 y L1 no necesitan ninguna invención nueva.** Lo nuevo es el contrato que los combina y las pruebas que lo verifican; consulta la [especificación](https://agentnas.com/es/spec/).

## Operación

- **Copias de seguridad:** 3-2-1; las instantáneas y las copias de seguridad pertenecen al principal propietario y ninguna concesión puede tocarlas; haz un simulacro de restauración cada trimestre y guarda un registro.
- **Actualizaciones:** las pasarelas no tienen estado y se pueden actualizar de forma gradual; cualquier cambio de formato de Store debe llevar un plan de migración y de reversión; la capa Memory se puede reconstruir entera.
- **Supervisión:** tasas de emisión y denegación de concesiones; longitud de la cola de compuertas y tasa de aprobación (una tasa de aprobación que se mantiene por encima del 95 % indica que las compuertas son demasiado frecuentes y conviene fusionarlas o endurecer la política); número y antigüedad de las ramas; frescura de los índices; verificación de la cadena de registros; cuotas.
- **Capacidad:** las ramas tienen un TTL y cuotas; la papelera tiene un período de retención; los datos derivados tienen un presupuesto.

## La sala de control

La interfaz para las personas puede ser una página web, una CLI o un chatbot. No es esencial: L0 a L1 pueden funcionar por completo con una CLI y una plataforma Git existente.

- **Línea de actividad:** agregada por ejecución: quién hizo qué y qué leyó.
- **Bandeja de compuertas:** acciones pendientes de aprobación, mostradas como Gate Cards.
- **Directorio de roles:** el Home de cada rol, sus concesiones, presupuestos y ejecuciones recientes.
- **Explorador de memoria:** notas y fuentes, la cuarentena de notas sin revisar, propuestas de mantenimiento.
- **Ramas y PR:** ramas sin fusionar y la papelera.
- **Consola de olvido:** solicitudes, vista previa del linaje e informes.

Las personas también pueden mirar directamente por SMB o WebDAV: `/humans/<user>/Agent Activity/` es una vista de actividad de solo lectura hecha de archivos normales.

---

URL canónica: https://agentnas.com/es/architecture/
Actualizado: 2026-11-11 · Borrador de especificación v0.2 · CC BY 4.0