Convenciones de la Base de Código

Este apéndice resume el diseño y las convenciones utilizadas en la base de código de Asset Core para lectores y colaboradores externos.

Visión general

Asset Core sigue patrones consistentes en todos los crates para estructura, nomenclatura y documentación. Comprender estas convenciones ayuda a navegar el código y mantener la consistencia al contribuir.

Explicación detallada

Diseño del Repositorio

asset-core/
├── core/                 # Runtime engine (L1/L2/L3)
├── daemon-write/         # HTTP write daemon
├── daemon-read/          # HTTP read daemon
├── acctl/                # CLI tool
├── telemetry/            # Shared metrics crate
├── api-contract/         # OpenAPI spec generation
├── assetcore-adapters/   # Protocol adapters
├── system-tests/         # E2E test harness
├── sdk-python/           # Python SDK
└── Docs/                 # Architecture documentation

Estructura de la Caja

Cada caja sigue este patrón:

crate/
├── Cargo.toml
├── README.md            # Crate overview
├── AGENTS.md            # Rules for LLM agents
└── src/
    ├── lib.rs           # Public API
    ├── mod.rs files     # Module organization
    └── tests/           # Unit tests

Arquitectura de Capas (L1/L2/L3)

El núcleo de la crate impone una estricta separación de capas:

Guía adicional:

Capa	Ubicación	Responsabilidad
L1	core/src/storage/	Estructuras de datos en bruto
L2	core/src/operations/	Lógica de negocio, eventos
L3	core/src/runtime/	Transacciones, deshacer

Reglas:

• L2 puede llamar a L1, no viceversa
• L3 puede llamar a L2, no viceversa
• No se permiten importaciones entre capas excepto hacia abajo

Convenciones de Nomenclatura

Archivos: snake_case

ingress_orchestrator.rs
commit_log_driver.rs

Tipos: PascalCase

struct ValidatedCommit { ... }
enum ContainerKind { ... }

Funciones: snake_case

fn prepare_commit(&mut self) -> Result<...>

Constantes: SCREAMING_SNAKE_CASE

const MAX_BATCH_SIZE: usize = 1000;

Encabezados de Documentación

Cada archivo fuente incluye un encabezado:

// =============================================================================
// Module: ingress/orchestrator
// Description: Coordinates request sequencing and commit pipeline
// Purpose: Provide backpressure-aware ingestion
// Dependencies: worker, append, state
// =============================================================================

Esto ayuda a los agentes LLM a entender el contexto sin leer implementaciones completas.

Manejo de Errores

Errores utilizan enums tipados con contexto:

#[derive(Debug, thiserror::Error)]
pub enum CommitError {
    #[error("Container {0} not found")]
    ContainerNotFound(ContainerId),

    #[error("Insufficient balance: requested {requested}, available {available}")]
    InsufficientBalance {
        requested: u64,
        available: u64,
    },
}

Los errores se mapean a códigos de estado HTTP a través de la capa API.

Nomenclatura de Métricas

Las métricas siguen un patrón consistente:

assetcore_{daemon}_{subsystem}_{metric}_{unit}

Ejemplos:

Guía adicional:

Tono: formal Registro: técnico

Contexto:

• dominio: infraestructura blockchain
• audiencia: desarrolladores e investigadores
• propósito: documentación técnica

Restricciones:

• Usar lenguaje neutral en cuanto al género
• Preservar nombres de marcas
• Mantener precisión técnica

Preservar sin traducción:

• code_blocks
• inline_code
• links
• glossary_terms
• mathematical_notation

Guía de glosario:

Preservar estos términos exactamente: Asset Core, Asset‑Core, CSP, API, Docker, ECS, daemon, L1, L2, L3, OpenGraph, GitHub, Astro, TypeScript, JavaScript, ℤ, ℤ², ℤ³, ℝ², ℝ³, 0D, 1D, 2D, 3D.

• assetcore_write_ingress_queue_depth
• assetcore_read_snapshot_publish_duration_seconds
• assetcore_write_commit_log_lag

Patrones de Pruebas

Pruebas unitarias: En línea en archivos fuente

#[cfg(test)]
mod tests {
    use super::*;
    // ...
}

Pruebas de integración: Bajo el directorio tests/

Pruebas del sistema: En el crate system-tests

Archivos AGENTS.md

Cada caja tiene un AGENTS.md con reglas para agentes de generación de código:

• Invariantes a preservar
• Patrones a seguir
• Archivos a consultar antes de los cambios
• Errores comunes

Lea el AGENTS.md relevante antes de modificar cualquier crate.

Notas de implementación

No Inseguro en Rutas Críticas

El rendimiento proviene de la disposición de datos, no de código inseguro:

• Estructura-de-Arreglos (SoA) para eficiencia de caché
• IDs densos en lugar de hashing
• Buffers preasignados

Sin Cadenas en Rutas Críticas

Los identificadores son enteros:

type ContainerId = u64;
type ClassId = u64;
type InstanceId = u64;

Las cadenas son solo para nombres y configuraciones visibles para el usuario.

Requisitos de Determinismo

Las operaciones deben ser deterministas:

• No hay tiempo del sistema durante la reproducción
• No valores aleatorios
• No hay dependencias externas durante el commit

Los eventos llevan un estado posterior, por lo que la reproducción es idempotente.

Cuándo leer esto

Lea este apéndice cuando:

• Incorporación al código fuente
• Contribuyendo cambios
• Comprensión de los nombres métricos
• Navegando en áreas desconocidas

Para el uso de la API, la documentación de referencia es más relevante.

Ver también

• Escribir Arquitectura de Ruta - Detalles del Pipeline
• Modelo de Ejecución - Visión arquitectónica