Arxi Decision Gate Asset Core
Docs
Documentació d'Asset Core

Documentació del motor d'estat del món determinista i referències de l'API.

Decision Gate docs

Obtenció d’Informació Inicial

Aquesta visió general et proporciona la narrativa i el model mental mínim necessari per començar amb confiança. Defineix com és el “primer èxit” i mostra com els components bàsics proporcionen determinisme i reproducció.

Qui és per a això

Qualsevol persona nova a Asset Core que vulgui entendre els components mínims necessaris per executar el sistema i enviar una primera transacció. Si esteu avaluant si el model s’adapta al vostre domini, aquesta és la manera més ràpida d’orientar-vos abans de submergir-vos en els detalls.

Què aprendràs

Aquesta secció se centra en el conjunt més petit de conceptes que necessiteu per obtenir un flux correcte de principi a fi. Veureu els límits del sistema, el paper del registre de compromisos i com confirmar que les escriptures són visibles per a les lectures de manera determinista.

  • Els components bàsics (escriptura daemon, lectura daemon, registre de confirmació, catàleg d’espais de noms i clients amb tokens d’autenticació) i de què és responsable cadascun.
  • Com flueix la dada d’un commit a les projeccions de lectura i per què aquest flux es manté determinista
  • Com es veu el “èxit” en una primera interacció i com reconèixer-lo en les respostes

Quan utilitzar això

Llegeix això abans d’intentar executar Asset Core localment o integrar-lo a la teva aplicació. Si vols el model darrere de les garanties, comença amb Runtime Model i Transactions and Operations. Si vols exemples de com els dominis es mapegen netament al sistema, llegeix Scenario Foundations. Si estàs llest per construir, continua amb First Commit and Read o el Python SDK path. Els operadors i constructors d’agents poden saltar directament a Operations o Agents Overview.

Estructura de nivell alt

Asset Core utilitza una arquitectura de separació d’escriptura/lectura amb esdeveniments com a font de veracitat. Aquesta separació és fonamental: el daemon d’escriptura s’optimitza per a la correcció i el determinisme, mentre que el daemon de lectura s’optimitza per al rendiment de les consultes i la visibilitat de la frescor. Junts, formen un sistema interdependent on el registre de confirmació és el pont entre les escriptures i les lectures.

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

Escriure daemon

El daemon d’escriptura accepta sol·licituds HTTP POST a /v1/write/namespaces/{namespace_id}/commit. És el únic component que muta l’estat, així que cada compromís es serialitza i el sistema es manté determinista sota concurrència.

Aquest disseny de sol escriptor és un compromís deliberat: no es pot escalar el rendiment d’escriptura horitzontalment dins d’un mateix espai de noms, però s’obté un determinisme absolut (vegeu Model d’execució). El rendiment d’escriptura s’escalfa mitjançant la fragmentació entre espais de noms—cada espai de noms és un món independent de sol escriptor.

El daemon d’escriptura:

  • Valida les transaccions entrants (comprova l’estructura de l’operació, les precondicions)
  • Executa operacions contra el temps d’execució (aplica la lògica empresarial a través de les capes L2/L3)
  • Agrupa esdeveniments en lots (agrupa esdeveniments amb números de seqüència)
  • Persisteix lots al registre de compromisos abans de l’acusament de rebuda (la durabilitat depèn de l’elecció del backend)

El que guanyes: cada commit veu una visió consistent del món, les operacions s’executen en un ordre total, la depuració es converteix en una anàlisi forense en lloc d’una conjectura probabilística. El que renuncies: el rendiment d’escriptura està limitat per la capacitat d’un únic node (però la fragmentació a través de namespaces recupera l’escalabilitat horitzontal).

Llegir daemon

El daemon de lectura atén les consultes HTTP GET. Materialitza projeccions del registre de compromisos, de manera que les lectures són ràpides, coherents i explicables. Les projeccions són dades derivades; si es perden, es poden reconstruir a partir del registre de compromisos (vegeu Freshness and Replay).

El daemon de lectura opera de manera asíncrona respecte a les escriptures: segueix el registre de compromisos al seu propi ritme, aplicant esdeveniments a mesura que arriben. Això significa que les lectures són eventualment consistents, no immediatament consistents. El retard entre els compromisos i les consultes es mesura i s’exposa, cosa que és crítica per al depurament.

El daemon de lectura:

  • Segueix el registre de commits per a nous lots (polls per esdeveniments des del darrer punt de control)
  • Aplica esdeveniments mitjançant la reproducció determinista (utilitza setters L1, vegeu Model d’execució)
  • Publica instantànies de zero còpia (intercanvi atòmic, sense actualitzacions parcials visibles)
  • Informa sobre la frescor dels metadades (retard entre esdeveniments compromesos i l’estat de la consulta)

Les consultes retornen projeccions puntuals amb informació de frescor (world_seq, retard en els compromisos i mil·lisegons), de manera que podeu raonar sobre l’envelliment de manera explícita. Els clients poden bloquejar les lectures fins que siguin prou fresques passant x-assetcore-min-world-seq.

El que guanyeu: rendiment de consulta independent de la càrrega d’escriptura, estat de lectura descartable (reconstrucció des del registre), visibilitat sobre l’antic (sense retard ocult). El que renuncieu: les lectures no són instantàniament fresques—sempre hi ha algun retard (típicament mil·lisegons).

Commit Log

El registre de commits és l’emmagatzematge d’esdeveniments autoritzat. És la única font de dades utilitzada per a la reproducció i l’auditoria. La durabilitat depèn del backend que escolliu: els backends en memòria són ràpids i descartables, mentre que els backends basats en fitxers o segmentats persisteixen a través de reinicis. Aquest disseny (vegeu Model d’execució) manté AssetCore operativament senzill: sempre podeu reconstruir l’estat de la consulta a partir del registre, i la durabilitat és una elecció de desplegament explícita.

El registre de commits és:

  • Només afegir: Els esdeveniments s’afegeixen al final, mai es modifiquen ni s’eliminen
  • Immutable: Un cop escrits, els lots no es poden canviar ni reordenar
  • Seqüenciat: Cada lot té un número de seqüència monotònic (ordenació total)
  • Durable (opcional): Quan es recolza en emmagatzematge de fitxers o segmentat, els lots es persisteixen abans de l’acusament de rebuda

Ambdós daemons interactuen amb el mateix registre de commits, assegurant la consistència entre escriptures i lectures. El daemon d’escriptura afegeix esdeveniments; el daemon de lectura els segueix i els aplica. Aquesta separació és el que permet escalar l’escriptura i la lectura de manera independent: el daemon d’escriptura no bloqueja el rendiment de lectura, i el daemon de lectura pot retardar-se sense afectar el rendiment d’escriptura.

El que guanyeu: depuració forense (repetició en qualsevol moment), auditable (provar què va passar quan) i analítiques que mai es desvien (tots consumeixen la mateixa font). El que renuncieu: l’emmagatzematge de registres creix amb el temps (encara que les estratègies d’arxiu mitiguen això), i la recuperació completa de fallades depèn de l’ús d’un backend durable.

Client

Qualsevol client HTTP pot interactuar amb Asset Core. Els SDK són capes fines sobre el mateix contracte HTTP, així que sempre teniu un camí de retrocés quan necessiteu depurar a nivell de protocol.

Clients:

  • Enviar transaccions al daemon d’escriptura (POST /v1/write/namespaces/{id}/commit)
  • Consultar l’estat del daemon de lectura (GET /v1/read/namespaces/{id}/query)
  • Utilitzeu claus d’idempotència per a reintents segurs (preveu compromisos duplicats a causa de reintents de xarxa)

El SDK de Python proporciona helpers tipats i wrappers ergonòmics, però l’HTTP brut funciona per a qualsevol llenguatge. Això significa que mai no estàs bloquejat en un SDK específic; quan necessites solucionar problemes a nivell de protocol, pots utilitzar curl o qualsevol client HTTP.

L’Objectiu

Començar significa:

  1. Executar ambdós daemons localment amb tokens d’autenticació i un catàleg d’espais de noms perquè pugueu observar el comportament d’escriptura i lectura
  2. Proporcionar un espai de noms i enviar un compromís que crea un contenidor i afegeix saldo, demostrant escriptures de punta a punta
  3. Llegint de nou l’estat per confirmar que el commit s’ha aplicat i que el model de lectura és actual

Això valida que el teu entorn està funcionant i et proporciona una base per a experiments i integracions més complexes.

Properes passes