Convencions de la Base de Codi

Aquest annex resumeix el disseny i les convencions utilitzades en la base de codi d’Asset Core per a lectors i contribuïdors externs.

Visió general

Asset Core segueix patrons consistents a través de totes les caixes per a l’estructura, la nomenclatura i la documentació. Entendre aquestes convencions ajuda a navegar pel codi i mantenir la consistència quan es contribueix.

Explicació detallada

Disposició del repositori

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 caixa

Cada caixa segueix aquest patró:

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 Capes (L1/L2/L3)

El nucli del crate imposa una separació estricta de capes:

Capa	Ubicació	Responsabilitat
L1	`core/src/storage/`	Estructures de dades en brut
L2	`core/src/operations/`	Lògica empresarial, esdeveniments
L3	`core/src/runtime/`	Transaccions, desfer

Regles:

L2 pot trucar a L1, no a l’inrevés
L3 pot cridar a L2, no a l’inrevés
No hi ha imports entre capes excepte cap avall

Convencions de Nomenclatura

Fitxers: snake_case

ingress_orchestrator.rs
commit_log_driver.rs

Tipus: PascalCase

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

Funcions: snake_case

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

Constants: SCREAMING_SNAKE_CASE

const MAX_BATCH_SIZE: usize = 1000;

Encapçalaments de Documentació

Cada fitxer font inclou un encapçalament:

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

Això ajuda els agents LLM a entendre el context sense llegir implementacions completes.

Gestió d’Errors

Errors utilitzen enums tipats amb context:

Orientació addicional:

Tono: formal Registre: tècnic

Context:

domini: infraestructura blockchain
audiència: desenvolupadors i investigadors
propòsit: documentació tècnica

Restriccions:

Utilitzar un llenguatge neutre en termes de gènere
Preservar noms de marca
Mantenir l’exactitud tècnica

Preservar sense traducció:

code_blocks
inline_code
links
glossary_terms
mathematical_notation

Orientació del glossari:

Preservar aquests termes exactament: Asset Core, Asset‑Core, CSP, API, Docker, ECS, daemon, L1, L2, L3, OpenGraph, GitHub, Astro, TypeScript, JavaScript, ℤ, ℤ², ℤ³, ℝ², ℝ³, 0D, 1D, 2D, 3D.

Requisits de sortida: - Llengua objectiu: català (codi de llengua: ca, NO francès canadenc). Utilitzeu aquesta llengua de manera coherent durant tota la resposta. - Retorneu només el text traduït; NO el poseu en code fences, JSON, marcadors YAML o comentaris. - NUNCA emeti ``` o qualsevol altre límit de frontera en la vostra sortida; si no esteu segurs, torneu INVALID. - Preserveu l’estructura Markdown, code fences, codi amb backticks, URLs i termes del glossari exactament. - Si no podeu complir, respongueu amb la cadena exacta INVALID. - Si el text és parells clau/valor YAML, emeti’ls tal com són sense afegir marcadors --- o fences.

Guies de format: - La sortida ha de ser text traduït en brut sense envoltar en code fences o metadades. - No afegiu wrappers JSON/YAML ni marcadors ---. - No emeti ``` o qualsevol altre límit de frontera en la sortida. - Retorneu només el text traduït.

#[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,
    },
}

Els errors es mapegen als codis d’estat HTTP a través de la capa API.

Nomenclatura de mètriques

Les mètriques segueixen un patró consistent:

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

Exemples:

Orientació addicional:

Tonalitat: formal Registre: tècnic

Context:

domini: infraestructura de blockchain
audiència: desenvolupadors i investigadors
propòsit: documentació tècnica

Restriccions:

Utilitzar un llenguatge neutral en termes de gènere
Preservar noms de marca
Mantenir l’exactitud tècnica

Preservar sense traducció:

code_blocks
inline_code
links
glossary_terms
mathematical_notation

Orientació del glossari:

assetcore_write_ingress_queue_depth
assetcore_read_snapshot_publish_duration_seconds
assetcore_write_commit_log_lag

Proves de Patrons

Proves unitàries: Inline en fitxers font

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

Proves d’integració: sota el directori tests/

Proves del sistema: En el crate system-tests

AGENTS.md Fitxers

Cada caixa té un AGENTS.md amb regles per a agents de generació de codi:

Invariants a preservar
Patrons a seguir
Fitxers a consultar abans de fer canvis
Errors comuns

Llegeix el AGENTS.md rellevant abans de modificar qualsevol crate.

Notes d’implementació

No Unsafe in Hot Paths

El rendiment prové de la disposició de dades, no de codi insegur:

Estructura-d’Arrays (SoA) per a l’eficiència de la memòria cau
IDs dens en comptes de hashing
Buffers preassignats

Sense cadenes en camins calents

Els identificadors són enters:

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

Les cadenes són només per a noms i configuracions visibles per a l’usuari.

Requisits de Determinisme

Les operacions han de ser deterministes:

No hi ha temps del sistema durant la reproducció
No valors aleatoris
No hi ha dependències externes durant el commit

Els esdeveniments porten estat posterior, de manera que la reproducció és idempotent.

Quan llegir això

Llegeix aquest annex quan:

Integració al codi font
Contribuint canvis
Comprensió dels noms mètrics
Navegant per àrees desconegudes

Per a l’ús de l’API, la documentació de referència és més rellevant.

Veure també

Escriure Arquitectura de Camí - Detalls del Pipeline
Model d’execució - Visió arquitectònica