Contenidors i Actius

Els contenidors són l’abstracció de emmagatzematge fonamental a Asset Core. Contenen actius amb diferents característiques espacials segons el seu tipus. La idea clau és que el mateix model de transacció s’aplica a tots els tipus de contenidors, de manera que es poden modelar dominis diversos sense canviar la infraestructura.

Problema que resol aquest concepte

La gestió d’actius del món real implica patrons d’emmagatzematge diversos. Un model de dades de talla única o bé s’ajusta massa o bé perd semàntica crítica, especialment en sistemes espacials.

• Quantitats agregades (saldos de comptes, recompte d’inventari)
• Seqüències ordenades (slots d’equip, llistes classificades)
• Disposicions espacials (reixetes d’emmagatzematge, plaques de laboratori)

Un únic model d’emmagatzematge no pot representar eficientment tots aquests patrons. Asset Core resol això proporcionant múltiples tipus de contenidors, cadascun optimitzat per la seva dimensió espacial mentre comparteix una interfície d’operació comuna. Això et proporciona tant fidelitat com consistència.

Idees principals

Classificació Dimensional

La part més difícil de construir sistemes d’estat espacial és gestionar la discrepància dimensional entre els patrons d’emmagatzematge. Els saldos dels comptes són escalar (0D): t’importa la quantitat, no la posició. Els espais d’equip són seqüencials (1D): la posició importa, però només en una línia. Les reixetes d’emmagatzematge són planes (2D): l’adjacència i la col·lisió importen en dues dimensions.

La majoria dels sistemes escullen un model i l’estiren de manera incòmoda. Emmagatzemen tot en una taula relacional i perden la semàntica espacial (sense detecció de col·lisions, sense consultes d’adjacència). Emmagatzemen tot en un gràfic i paguen per una estructura que no necessiten (un saldo no necessita coordenades). Emmagatzemen tot en un magatzem de clau-valor genèric i implementen la lògica espacial en el codi de l’aplicació (reinventant la detecció de col·lisions per a cada domini).

AssetCore adopta un enfocament diferent: proporcionar el contenidor ADEQUAT per a cada necessitat dimensional, però mantenir la interfície d’operació consistent. Els contenidors es classifiquen segons la dimensionalitat del seu espai d’adreces. Cada tipus afegeix semàntica espacial sense canviar l’envolupant de transacció:

Tipus	Dimensió	Espai d’adreces	Casos d’ús exemples
Balanç (balance)	0D	Cap (només agregació)	Saldos, totals
Slots (slots)	1D	Índexs seqüencials	Equipament, llistes ordenades
Reixeta (grid)	2D	Coordenades de reixeta	Plats, magatzems
Línia contínua (continuous_line_1d)	1D	Coordenada de punt fix (x)	Rails, actuadors
Pla continu (continuous_grid_2d)	2D	Coordenades de punt fix (x, y)	Cèl·lules de treball de robot, recollir i col·locar

Aquest tipatge dimensional resol un problema real: evita que tractis accidentalment un saldo escalar com una graella (sense sentit) o que consultis les posicions de les ranures d’un pla continu (error de tipus). El tipus de contenidor codifica el contracte espacial, i les operacions es validen contra ell en el moment de l’execució.

El que guanyeu: les mateixes operacions (AddFungible, MoveInstance, etc.) s’adapten automàticament a la geometria del contenidor. El que renuncieu: la càrrega cognitiva d’aprendre 5 tipus de contenidors en comptes de 1. Creiem que aquest intercanvi us fa més ràpids a llarg termini perquè el vostre model de domini coincideix amb el vostre model mental.

Saldo (0D)

Els contenidors de saldo contenen saldos fungibles. Utilitzeu-los quan només us importi la quantitat i no la ubicació espacial: llibres de comptes, totals de moneda, grups de recursos.

Els saldos són 0-dimensional: no tenen coordenades, no tenen posicions, no tenen empremta espacial. Un saldo és un comptador escalar pur. Això els converteix en l’eina adequada per a preguntes de “quanta quantitat”, no per a preguntes de “on”.

• Identificat per parells (class_id, key)
• Quantitats agregades sense posició espacial (sense coordenades x/y)
• Suport per a operacions d’afegir, eliminar i transferir

Per què és important: Si emmagatzemes moneda en un contenidor Grid, hauries de triar coordenades arbitràries per a cada unitat. Si ho emmagatzemes en Slots, malgastaràs un slot per unitat i arribaràs als límits de capacitat instantàniament. Els saldos et donen agregació escalar il·limitada, que és el que és realment la moneda.

Exemple de cas d’ús: Un inventari de reactius en un laboratori on es fan seguiment de mil·lilitres de nitrogen líquid. No t’importa ON és el nitrogen (està al dipòsit), t’importa QUANT en tens. Això és un saldo.

{
  "op": "AddFungible",
  "args": {
    "class_id": 100,
    "key": 1,
    "quantity": 500,
    "location": {
      "container_id": 1001,
      "kind": "balance"
    }
  }
}

El que guanyeu: agregació sense sobrecàrrega espacial. Un saldo que manté 1.000.000 unitats té el mateix cost que un saldo que manté 1 unitat; és només un comptador. El que renuncieu: consultes espacials. No podeu preguntar “què hi ha a la posició (3,5)” per a un saldo perquè les posicions no existeixen. Si necessiteu semàntica espacial, utilitzeu contenidors Grid o Continuous en el seu lloc.

Slots (1D)

Els contenidors de slot contenen instàncies úniques en posicions seqüencials. Són ideals per a equips, càrregues o llistes ordenades on l’exclusivitat és més important que la geometria.

• Índexs de 1 a N (capacitat configurable)
• Cada slot conté com a màxim una instància
• Suport per a les operacions de col·locació, eliminació i intercanvi

Exemple: Slots d’equipament en un personatge o posicions en una cua de processament.

{
  "op": "PlaceInSlot",
  "args": {
    "container_id": 1001,
    "instance_id": 9001,
    "slot_index": 1
  }
}

Reixeta (2D)

Els contenidors de gra afegeixen geometria espacial. Són l’elecció adequada per a magatzems, plaques de laboratori i qualsevol entorn on l’adjacència i la col·lisió siguin importants.

• Amplada x Alçada de la malla de cel·les
• Els elements ocupen múltiples cel·les segons la forma
• Suport per a la detecció de col·lisions i adjacència

Exemple: Una placa de 96 pous o una graella d’emmagatzematge de magatzem.

Els contenidors de graella poden contenir tant piles fungibles (amb col·locació espacial) com instàncies úniques.

Línia Contínua (1D)

Els contenidors de línia contínua (continuous_line_1d) emmagatzemen instàncies al llarg d’un eix de punt fix únic. Les coordenades de punt fix garanteixen una reproducció determinista sense deriva de punt flotant.

• Les coordenades són enters fixos deterministes (sense decimals)
• Els col·locaments han de romandre dins dels límits mínims/màxims
• Les comprovacions de col·lisió imposen intervals no superposats

Casos d’ús: rails lineals, cintes transportadores amb precisió sub-cel·lular i robòtica d’eix únic.

Pla Continu (2D)

Els contenidors de pla continu (continuous_grid_2d) emmagatzemen instàncies en un espai de treball continu i delimitat. Estan dissenyats per a cèl·lules de treball en robòtica i tasques de planificació contínua.

• Coordenades x/y de punt fix amb arrodoniment determinista
• Comprovacions de col·lisió de rectangles orientats (rotació en mil·graus)
• Col·locacions, moviments i rotacions amb comprovació de límits
• Col·locacions només d’instància (sense piles fungibles)

Casos d’ús: cèl·lules de treball de robot, tasques de recollida i col·locació, i planificació de col·lisions mètriques.

Instances vs. Fungibles

Aquesta distinció reflecteix el món real: la moneda és fungible (el teu bitllet de $20 és intercanviable amb el meu), l’equipament és únic (la teva espasa específica té durabilitat, encanteris i una història). El sistema de tipus imposa això a nivell d’operació.

Actius fungibles són quantitats intercanviables. Són representats per parells de classe i clau i es poden dividir o fusionar lliurement.

• Identificat per classe i clau
• Les operacions especifiquen quantitats
• Es pot dividir i fusionar lliurement

Per què és important: els fungibles es poden dividir i fusionar lliurement, cosa que permet operacions com Distribute (dividir la quantitat entre objectius) i ConsolidateStacks (fusionar en un). Intentar “dividir” una instància és un error de tipus detectat en el moment de la validació.

Instàncies úniques són rastrejades individualment. Són representades per IDs estables i poden ser adjuntades o desadjuntades per formar jerarquies.

• Tenir IDs globalment únics
• No es pot dividir ni fusionar
• Pot formar jerarquies pare-fill mitjançant attach/detach

Les instàncies úniques no es poden dividir ni fusionar—MoveInstance reubica tota l’instància de manera atòmica. L’herència pare-fill per a les instàncies (Attach/Detach) modela un veritable anidament: una motxilla conté una bossa, que conté pocions. L’herència es reflecteix en les consultes, fent que “què hi ha dins d’aquest contenidor de manera recursiva?” sigui una operació de primera classe.

Classes i formes

Classes defineixen tipus d’actius. Són els identificadors canònics tant per a fungibles com per a instàncies, i han de ser registrades abans de l’ús.

• Proporcionar metadades com noms i banderes opcionals
• Servir com a identificadors estables per a balances fungibles o instàncies úniques
• Ha de ser registrat abans d’usar-se

Les classes són de l’àmbit del namespace: un class_id només té significat dins del seu namespace. El mateix ID numèric en un namespace diferent és una classe diferent. Un cop registrat, un ID de classe no es pot reutilitzar per a una definició diferent. Això manté l’identitat estable per a l’auditoria i la reproducció.

Les classes poden portar opcionalment restriccions de comportament que s’apliquen en el moment de la validació de l’operació. Aquestes restriccions són com encodeu els límits del “món real” en regles deterministes:

• Escala de balance (quantització de punt fix per a balances)
• Sòls/teulades de saldo mínim i màxim
• Mida màxima de la pila per a piles fungibles
• Màxims de piles per contenidor per a una classe
• Capacitat de saldo negatiu (permesa explícitament o no)

Les formes defineixen empremtes espacials. Permeten que el temps d’execució imposi regles de col·lisió de manera determinista, cosa que és essencial per a la correcció.

• Amplada i alçada en cel·les de la graella
• Associat a una classe i una clau de variant opcional
• Requerit per a la col·locació del contenidor de la graella

Les variants s’expressen amb stack_key. El pare (class_id, stack_key) defineix la identitat fungible i determina quina forma (si n’hi ha) és necessària per a la col·locació. Això permet modelar variants (mida, nivell, condició) sense multiplicar els IDs de classe.

Recapitulació de compatibilitat:

• Balanç: Quantitats fungibles només (escala de punt fix; sense posicions)
• Slots: Instàncies només (una instància per slot)
• Grau: Piles o instàncies fungibles (formes requerides per a la col·locació de múltiples cel·les)
• Continu 1D/2D: Només instàncies (coordenades de punt fix; formes/abast requerits)

{
  "op": "RegisterClass",
  "args": {
    "request": {
      "class_id": 200,
      "flags": 2,
      "name": "Sample Tube"
    }
  }
}

Com s’integra al sistema

Validació i enviament

El tipus de contenidor forma part del contracte d’operació. Durant la validació L2, el runtime comprova el tipus de contenidor, la registració de classes i els requisits de forma abans de qualsevol mutació. El preflight utilitza les mateixes comprovacions, així que un preflight exitós implica que el compromís passarà si el món no ha canviat.

Exemples de com això es desenvolupa:

• AddFungible sobre el saldo incrementa un saldo escalar.
• AddFungible a la graella requereix registre de forma i comprovacions de col·lisió.
• PlaceInSlot en equilibri és rebutjat (tipus de contenidor incorrecte).

Registre i formes

La classe i la forma de registre viuen en l’espai de noms del registre. Les col·locacions en graella i contínues consulten el registre per a empremtes o abastaments, de manera que la col·locació és determinista i segura per a la reproducció en lloc de ser ad hoc.

Llegir projeccions i superfícies de consulta

Les projeccions de lectura mantenen índexs específics del contenidor (saldos per classe/clau, ocupació de slots, ancoratges de la graella). Les respostes de lectura retornen càrregues tipades per tipus de contenidor, de manera que les consultes de “continguts del contenidor” sempre coincideixen amb la geometria que imposa el contenidor.

Vegeu també

• Transaccions i Operacions - Com funcionen les operacions
• Acció de Referència - Referència completa de l’operació
• Model d’execució - Com s’integren els contenidors en l’arquitectura