Introducción General

Este resumen te proporciona la narrativa y el modelo mental mínimo necesario para comenzar con confianza. Define cómo es el “primer éxito” y muestra cómo los componentes centrales ofrecen determinismo y repetición.

Para quién es esto

Cualquiera que sea nuevo en Asset Core y quiera entender los componentes mínimos requeridos para ejecutar el sistema y enviar una primera transacción. Si está evaluando si el modelo se ajusta a su dominio, esta es la forma más rápida de orientarse antes de profundizar en los detalles.

Lo que aprenderás

Esta sección se centra en el conjunto más pequeño de conceptos que necesitas para obtener un flujo correcto de extremo a extremo. Verás los límites del sistema, el papel del registro de confirmaciones y cómo confirmar que las escrituras son visibles para las lecturas de manera determinista.

• Los componentes principales (daemon de escritura, daemon de lectura, registro de confirmaciones, catálogo de espacios de nombres y clientes con tokens de autenticación) y de qué es responsable cada uno
• Cómo fluye la información desde un commit hacia las proyecciones de lectura y por qué ese flujo se mantiene determinista
• Cómo se ve el “éxito” en una primera interacción y cómo reconocerlo en las respuestas

Cuándo usar esto

Lee esto antes de intentar ejecutar Asset Core localmente o integrarlo en tu aplicación. Si deseas conocer el modelo detrás de las garantías, comienza con Runtime Model y Transactions and Operations. Si quieres ejemplos de cómo los dominios se mapean de manera clara en el sistema, lee Scenario Foundations. Si estás listo para construir, continúa con First Commit and Read o el Python SDK path. Los operadores y constructores de agentes pueden saltar directamente a Operations o Agents Overview.

Estructura de alto nivel

Asset Core utiliza una arquitectura de separación de escritura/lectura con event sourcing como la fuente de verdad. Esta separación es fundamental: el daemon de escritura optimiza para la corrección y el determinismo, mientras que el daemon de lectura optimiza para el rendimiento de las consultas y la visibilidad de la frescura. Juntos, forman un sistema interdependiente donde el registro de confirmaciones es el puente entre las escrituras y las lecturas.

┌──────────────┐        ┌──────────────┐
│ Write Daemon │        │ Read Daemon  │
└──────┬───────┘        └──────▲───────┘
       │                       │
       │ Events                │ Tail + Apply
       ▼                       │
   ┌───────────────────────────┴──┐
   │      Commit Log (Events)     │
   │   (sealed batches, ordered)  │
   └──────────────────────────────┘

Escribir daemon

El daemon de escritura acepta solicitudes HTTP POST a /v1/write/namespaces/{namespace_id}/commit. Es el único componente que muta el estado, por lo que cada commit se serializa y el sistema se mantiene determinista bajo concurrencia.

Este diseño de un solo escritor es un compromiso deliberado: no se puede escalar el rendimiento de escritura horizontalmente dentro de un mismo espacio de nombres, pero se obtiene un determinismo absoluto (ver Modelo de Ejecución). El rendimiento de escritura se escala mediante el sharding a través de espacios de nombres; cada espacio de nombres es un mundo independiente de un solo escritor.

El demonio de escritura:

• Valida las transacciones entrantes (verifica la estructura de la operación, las precondiciones)
• Ejecuta operaciones contra el tiempo de ejecución (aplica lógica de negocio a través de las capas L2/L3)
• Agrupa eventos en lotes (agrupa eventos con números de secuencia)
• Persiste lotes en el backend del registro de confirmaciones antes de la confirmación (la durabilidad depende de la elección del backend)

Lo que ganas: cada commit ve una vista consistente del mundo, las operaciones se ejecutan en un orden total, la depuración se convierte en un análisis forense en lugar de una conjetura probabilística. Lo que cedes: el rendimiento de escritura está limitado por la capacidad de un solo nodo (pero la fragmentación a través de espacios de nombres recupera la escalabilidad horizontal).

Leer daemon

El daemon de lectura atiende consultas HTTP GET. Materializa proyecciones del registro de confirmaciones para que las lecturas sean rápidas, consistentes y explicables. Las proyecciones son datos derivados; si se pierden, se pueden reconstruir a partir del registro de confirmaciones (ver Freshness and Replay).

El daemon de lectura opera de manera asíncrona respecto a las escrituras: sigue el registro de confirmaciones a su propio ritmo, aplicando eventos a medida que llegan. Esto significa que las lecturas son eventualmente consistentes, no inmediatamente consistentes. El retraso entre las confirmaciones y las consultas se mide y se expone, lo cual es crítico para la depuración.

El daemon de lectura:

• Realiza un seguimiento del registro de commits para nuevos lotes (sondea eventos desde el último punto de control)
• Aplica eventos a través de la reproducción determinista (utiliza configuraciones L1, ver Modelo de Ejecución)
• Publica instantáneas de cero-copia (intercambio atómico, sin actualizaciones parciales visibles)
• Informa sobre los metadatos de frescura (retraso entre eventos comprometidos y estado de consulta)

Las consultas devuelven proyecciones en un momento específico con información de frescura (world_seq, retraso en los commits y milisegundos), para que puedas razonar sobre la obsolescencia de manera explícita. Los clientes pueden bloquear lecturas hasta que sean lo suficientemente frescas pasando x-assetcore-min-world-seq.

Lo que ganas: rendimiento de consulta independiente de la carga de escritura, estado de lectura desechable (reconstruir desde el registro), visibilidad en la obsolescencia (sin retraso oculto). Lo que cedes: las lecturas no son instantáneamente frescas; siempre hay algún retraso (típicamente en milisegundos).

Registro de Commits

El registro de confirmaciones es la tienda de eventos autorizada. Es la única fuente de datos utilizada para la reproducción y auditoría. La durabilidad depende del backend que elijas: los backends en memoria son rápidos y desechables, mientras que los backends respaldados por archivos o segmentados persisten a través de reinicios. Este diseño (ver Modelo de Ejecución) mantiene a AssetCore operativamente simple: siempre puedes reconstruir el estado de la consulta a partir del registro, y la durabilidad es una elección de implementación explícita.

El registro de commits es:

• Solo agregar: Los eventos se añaden al final, nunca se modifican ni se eliminan
• Inmutable: Una vez escrito, los lotes no pueden ser cambiados ni reordenados
• Secuenciado: Cada lote tiene un número de secuencia monótono (orden total)
• Duradero (opcional): Cuando se respalda con almacenamiento de archivos o segmentado, los lotes se persisten antes de la confirmación

Ambos daemons interactúan con el mismo registro de confirmaciones, asegurando consistencia entre las escrituras y lecturas. El daemon de escritura agrega eventos; el daemon de lectura los sigue y los aplica. Esta separación es lo que permite escalar la escritura/lectura de manera independiente: el daemon de escritura no bloquea el rendimiento de lectura, y el daemon de lectura puede retrasarse sin afectar el rendimiento de escritura.

Lo que ganas: depuración forense (repetición hasta cualquier punto), auditabilidad (demostrar lo que sucedió y cuándo), y análisis que nunca se desvían (todos consumen la misma fuente). Lo que cedes: el almacenamiento de registros crece con el tiempo (aunque las estrategias de archivo mitigan esto), y la recuperación completa de fallos depende de utilizar un backend duradero.

Cliente

Cualquier cliente HTTP puede interactuar con Asset Core. Los SDK son capas delgadas sobre el mismo contrato HTTP, por lo que siempre tienes una ruta de respaldo cuando necesitas depurar a nivel de protocolo.

Clientes:

• Enviar transacciones al daemon de escritura (POST /v1/write/namespaces/{id}/commit)
• Consultar el estado desde el daemon de lectura (GET /v1/read/namespaces/{id}/query)
• Utilice claves de idempotencia para reintentos seguros (previene compromisos duplicados por reintentos de red)

El SDK de Python proporciona ayudantes tipados y envolturas ergonómicas, pero el HTTP en bruto funciona para cualquier lenguaje. Esto significa que nunca estás atado a un SDK específico; cuando necesitas solucionar problemas a nivel de protocolo, puedes usar curl o cualquier cliente HTTP.

El Objetivo

Comenzar significa:

1. Ejecutar ambos demonios localmente con tokens de autenticación y un catálogo de espacios de nombres para que puedas observar el comportamiento de escritura y lectura
2. Provisionar un espacio de nombres y enviar un commit que crea un contenedor y añade saldo, demostrando escrituras de extremo a extremo
3. Leer de nuevo el estado para confirmar que el commit se aplicó y que el modelo de lectura está actualizado

Esto valida que su entorno está funcionando y le proporciona una base para experimentos e integraciones más complejas.

Próximos pasos

• Primer Commit y Lectura - Guía paso a paso con ejemplos de HTTP, luego profundice en la API HTTP y Transacciones
• Uso del SDK de Python - Mismo flujo de trabajo con ayudantes de Python tipados para una iteración más rápida
• Escenario continuo del brazo robótico - Recorrido completo del mundo real con detalles de registros y reproducción determinista