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

Transaccions i Operacions

Les transaccions són la unitat atòmica de canvi a Asset Core. Cada transacció conté una seqüència d’operacions que s’executen juntes o no s’executen en absolut. Aquest és el contracte bàsic que fa que Asset Core sigui determinista i auditable.

Problema que resol aquest concepte

Els canvis d’estat complexos sovint requereixen múltiples actualitzacions coordinades. Sense atomicitat, els sistemes es desvien perquè els canvis parcials es comprometen i ja no coincideixen amb l’estat previst.

  • Creant un contenidor i omplint-lo
  • Transferència d’actius entre ubicacions
  • Afegint una instància i col·locant-la

Sense transaccions atòmiques, aquests canvis de múltiples passos podrien fallar a mitja execució, deixant el sistema en un estat inconsistent. Asset Core resol això agrupant operacions en transaccions amb semàntica de tot o res.

Asset Core utilitza un vocabulari d’operacions fix perquè defineix la superfície matemàtica mínima per a les transicions d’estat. Cada cridant—humà, servei o agent—utilitza les mateixes operacions; la governança determina quines pot invocar un cridant. El conjunt limitat fa que l’auditoria i les eines siguin manejables sense sacrificar l’expressivitat.

Idees principals

Estructura del Compromís

Una sol·licitud de commit conté una llista d’operacions. L’envoltant és intencionadament uniforme perquè es pugui validar, reproduir i auditar de manera consistent a través de tots els dominis.

{
  "actor_id": "lab-operator-17",
  "operations": [
    { "op": "CreateContainer", "args": { ... } },
    { "op": "AddFungible", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": { "experiment": "phase-1" }
}

Les operacions s’executen en ordre dins de la transacció. Si qualsevol operació falla, tota la confirmació es desfarà.

Operació Sobre.

Cada operació té la mateixa estructura d’envolupant:

{
  "op": "OperationName",
  "args": { ... }
}
  • op: L’identificador de l’operació (per exemple, CreateContainer)
  • args: Arguments específics de l’operació

Aquesta estructura uniforme facilita la composició i el processament d’operacions de manera programàtica.

Les 24 Operacions

Asset Core defineix exactament 24 operacions a través de 5 dominis. Aquest petit vocabulari tancat és el que fa que l’aplicació automatitzada de polítiques i l’auditoria siguin manejables.

DomainOperations
ContainerCreateContainer, RemoveContainer
BalanceAddFungible, RemoveFungible, MoveFungible, TransferFungible, TransferMany, Distribute, MoveMany, MergeStacks, ConsolidateStacks
InstanceAddInstance, MoveInstance, RemoveInstance, BurnInstance, Attach, Detach
SlotPlaceInSlot, RemoveFromSlot, SwapSlots
SchemaRegisterClass, RegisterClassShape, RegisterClassContinuousShape1d, RegisterClassContinuousShape2d

Per què exactament 24? Perquè és el conjunt mínim que cobreix l’espai d’operació per a sistemes d’estat espacial sense perdre expressivitat.

Cada operació s’emmarca en una taxonomia de 4 dimensions: domini (quin tipus d’entitat), acció (quin tipus de canvi), abast (entitat única o múltiple) i reversibilitat (es pot desfer o és destructiva). Aquesta taxonomia no és decorativa: és com es construeix la governança.

Aquest vocabulari tancat també és crític per a la governança. Una API sense límits (SQL arbitrari, scripting d’ús general) significa que els cridadors poden realitzar operacions que no havies anticipat i que no pots auditar. Un conjunt d’operacions fix significa que pots:

  • Llista blanca per domini: “Aquest agent només pot modificar saldos, no instàncies”
  • Blacklist operacions destructives: “Aquest agent pot moure’s però no cremar”
  • Audita exhaustivament: “Mostra’m cada operació que aquest actor ha realitzat”

La restricció és una característica. Quan necessiteu un comportament de nivell superior, combineu operacions: combineu diverses operacions en una sola transacció. Els patrons comuns de múltiples operacions estan documentats a Recipes, però la llista no és exhaustiva. Si el vostre domini té comportament fora del model, mantingueu aquesta lògica a la vostra aplicació i comprometeu els canvis d’estat resultants a través d’operacions.

Aquest conjunt fix proporciona:

  • Auditabilitat: Cada possible canvi d’estat és conegut
  • Seguretat: No hi ha mutacions arbitràries
  • Consistència: Mateixes operacions funcionen a tots els entorns

Sistema de Etiquetes

Les operacions es classifiquen en quatre dimensions. Aquesta taxonomia no és metadades de documentació: és la base per a la governança.

Per què existeix això: Quan atorgueu a un trucador permís per manipular l’estat d’AssetCore, necessiteu un control granular. “Pot modificar qualsevol cosa” és massa ampli. Les llistes d’acceptació llargues són fràgils i difícils de mantenir. El sistema d’etiquetes us proporciona un filtratge semàntic: “pot crear i moure instàncies, però no pot destruir” o “només pot modificar saldos, no contenidors.”

Les quatre dimensions:

Dominis: Quin tipus d’entitat està afectat

  • contenidor, saldo, instància, slot, esquema

Acció: Quin tipus de canvi

  • crear, destruir, moure, enllaçar, consolidar

Abast: Quantes entitats

  • single, multi

Reversibilitat: Es pot desfer?

  • reversible, destructive, neutral

Com això t’ajuda:

  • Permisos de l’agent: Llista blanca per domini + acció. “Aquest agent pot moure instàncies però no les pot eliminar” = domain:instance, action:move, reversibility:reversible.

  • Consultes d’auditoria: “Mostra’m totes les operacions destructives en les últimes 24 hores” = filtra el registre d’esdeveniments per reversibilitat:destructiva.

  • Generació d’eines: El manifest d’operacions (fitxer JSON) inclou etiquetes. Podeu generar definicions d’eines d’agent de manera programàtica: “Creeu una eina per a cada operació reversible d’abast únic.”

Exemple: El catàleg d’eines MCP utilitza aquestes etiquetes per agrupar operacions en superfícies d’eines segures. Els agents obtenen assetcore_move_instance (reversible, d’abast únic) però no assetcore_burn_instance (destructiu) a menys que se’ls concedeixi explícitament.

Idempotència

La idempotency_key opcional permet reintents segurs. En producció, és un control de fiabilitat primari, no una característica de conveniència.

  • La primera sol·licitud amb una clau s’executa normalment
  • Les sol·licituds posteriors amb la mateixa clau retornen la resposta emmagatzemada
  • Prevé la duplicació de commits a causa de reintents de xarxa

Sempre utilitzeu claus d’idempotència per a càrregues de treball en producció.

Com s’integra al sistema

Flux d’Execució

  1. El client envia la sol·licitud de compromís
  2. Escriure daemon que analitza i valida
  3. Les operacions s’executen en seqüència (la validació del tipus de contenidor es realitza aquí; vegeu Containers and Assets)
  4. Els esdeveniments es registren per a cada operació
  5. Els esdeveniments es segellen en un lot
  6. El lot s’afegeix al registre de commits del backend (vegeu Model d’execució)
  7. El client rep una resposta d’èxit

Reversió en cas de fallada

Si alguna operació falla:

  1. L’execució s’atura en l’operació fallida
  2. El registre d’anul·lació s’aplica en ordre invers
  3. L’estat es restaura a la situació anterior a la transacció
  4. El client rep una resposta d’error

No hi ha compromisos parcials visibles per als lectors.

Generació d’Esdeveniments

Cada operació genera esdeveniments que:

  • Descriu el canvi d’estat
  • Portar l’estat posterior per a la reproducció
  • S’agrupen en el lot de transaccions

Els esdeveniments són el registre autoritzat (la durabilitat depèn del backend); les operacions són el format de la sol·licitud.

Invariants i garanties clau

Atomicitat

Totes les operacions d’una transacció tenen èxit o fracassen juntes. Aquesta és la garantia que impedeix la corrupció parcial de l’estat.

Sense atomicitat, una fallada en l’operació 5 de 10 deixa les operacions 1-4 compromeses i 6-10 no executades. El teu estat és ara internament inconsistent: un contenidor creat però mai omplert, una transferència mig executada, una instància moguda però la seva referència pare obsoleta. La depuració requereix reconstruir “el que hauria d’haver passat”, cosa que sovint és impossible. Els usuaris veuen un estat corrupte, les operacions fallen inesperadament i la confiança s’erosiona.

AssetCore aplica l’atomicitat a través d’un registre d’undo (vegeu Model d’execució):

  • No s’observa execució parcial visible (les consultes mai veuen estats intermedis)
  • La reversió restaura l’estat anterior exacte (reprodueix el registre d’anul·lació a l’inrevés)
  • Les respostes d’error utilitzen RFC 9457 Problem Details amb codis estables (t’expliquen QUINA operació ha fallat i per què)

La resposta d’error t’informa quina operació ha fallat i per què, però l’estat es manté net. El que guanyes: confiança que les transaccions fallides no deixen rastre, no cal netejar manualment després de fallades, la consistència interna és una garantia i no un esforç màxim. El que renuncies: no pots “confirmar el que ha tingut èxit i saltar el que ha fallat.” Això no és un error, és el disseny. Si necessites un progrés parcial, divideix la transacció en confirmacions més petites amb punts de control explícits.

Conservació de l’Ordre

Les operacions s’executen en l’ordre en què apareixen a l’array. Això sembla obvi, però té implicacions subtils per a la correcció.

Les operacions posteriors veuen els efectes de les anteriors dins de la mateixa transacció. Així és com podeu CreateContainer en l’operació 1 i AddFungible a aquest contenidor en l’operació 2—l’ID del contenidor del resultat de l’operació 1 és visible immediatament. Sense la preservació de l’ordre, hauríeu de dividir aquestes en transaccions separades amb coordinació manual.

AssetCore garanteix l’execució seqüencial:

  • Les operacions posteriors veuen els efectes de les anteriors (dependències satisfetes en seqüència)
  • Les dependències es satisfan de manera seqüencial (sense execució paral·lela dins d’una transacció)
  • No hi ha reordenació ni optimització que canviï la semàntica (el temps d’execució no reorganitza per rendiment)

Això és crític per al determinisme: si el temps d’execució reorganitza les operacions per rendiment, dues transaccions idèntiques podrien produir seqüències d’esdeveniments diferents depenent de les heurístiques del temps d’execució. La preservació de l’ordre fa que l’execució de transaccions sigui una funció pura de l’array d’entrada. El que guanyes: execució previsible, capacitat per compondre operacions amb dependències, reproducció determinista. El que perds: el temps d’execució no pot paral·lelitzar automàticament operacions independents dins d’una transacció, però la majoria de transaccions són prou petites com perquè això no sigui rellevant.

Determinisme

Donada una estat idèntic i una seqüència d’operacions idèntica, l’execució produeix esdeveniments idèntics en bytes. Això és el que fa possible la reproducció.

El determinisme a nivell de transacció es basa en les garanties de determinisme del temps d’execució (vegeu Model d’execució). Les operacions no han de dependre d’estats externs: no lectures del rellotge del sistema, no generació de nombres aleatoris, no trucades a APIs externes. Tot el que afecta l’execució flueix a través dels arguments de l’operació o de l’estat actual.

AssetCore garanteix una execució determinista:

  • Donades l’estat i les operacions idèntiques (mateix estat del món, mateix array d’operacions)
  • Els esdeveniments seran idèntics en bytes (mateixa seqüència, mateix contingut)
  • Permet la reproducció i verificació (reconstruir l’estat a partir del registre, demostrar què va passar quan)

El que això permet: depuració de viatge en el temps (reproducció en qualsevol moment i inspecció), recuperació de desastres (reconstruir projeccions a partir del registre de confirmacions), auditoria forense (provar què va passar quan). El que renuncies: no pots cridar APIs externes ni utilitzar caràcters temporals d’operacions—tot ha de ser determinista. Si necessites temps de rellotge o dades externes, inclou-ho com a arguments d’operació (capturats en el moment de la confirmació) en lloc de recuperar-ho durant l’execució.

Vocabulari Fixat

Les 24 operacions són el conjunt complet. No es poden definir operacions personalitzades ni ampliar el vocabulari en temps d’execució.

Això sembla una limitació fins que us adoneu que és la base per a l’auditoria i la seguretat de l’agent. Cada possible canvi d’estat s’ajusta a una de les 24 categories semàntiques. Aquest és un espai tractable per a l’aplicació de polítiques. Sense aquesta restricció, un agent d’IA podria construir transicions d’estat arbitràries que mai no heu considerat. Amb aquesta restricció, podeu enumerar cada tipus d’operació possible, adjuntar polítiques a cadascuna i auditar exhaustivament.

AssetCore aplica un vocabulari fix:

  • Les 24 operacions estan completes (sense operacions personalitzades, sense extensió en temps d’execució)
  • Els canvis complexos componen múltiples operacions en una sola transacció (vegeu Recipes per patrons comuns)
  • Aquesta restricció és una característica: fa possible la governança

El que guanyeu: espai d’operació auditable (coneixeu cada tipus de canvi possible), seguretat de l’agent (vocabulari limitat = sense sorpreses), semàntica consistent a través dels entorns (mateixes operacions a tot arreu). El que renuncieu: flexibilitat per definir operacions específiques del domini. Si algun comportament no es mapeja directament, mantingueu aquesta lògica fora del temps d’execució i utilitzeu Asset Core per a les transicions d’estat que sí que ho fan. Aquest és el mateix compromís que utilitzar SQL (llenguatge de consulta fix) enfront de codi arbitrari: la restricció permet eines i garanties.

Vegeu també