Contenidors i Actius

Els contenidors són l’abstracció de magatzematge fonamental a Asset Core. Contenen actius amb diferents característiques espacials segons el seu tipus.

Problema que resol aquest concepte

La gestió d’actius del món real implica patrons d’emmagatzematge diversos:

• 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 sol 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.

Idees principals

Classificació Dimensional

Els contenidors es classifiquen segons la dimensionalitat del seu espai d’adreces:

Tipus	Dimensió	Espai d’adreces	Cas d’ús
Estàndard	0D	Cap (només agregació)	Saldo, totals
Slots	1D	Índexs seqüencials	Equipament, llistes ordenades
Reixeta	2D	Coordenades de reixa	Plats, magatzems
Línia contínua	1D	Coordenada de punt fix (x)	Rails, actuadors
Pla continu	2D	Coordenades de punt fix (x, y)	Cèl·lules de treball de robots, recollir i col·locar

Cada dimensió afegeix semàntica espacial mentre preserva la mateixa gramàtica d’operació.

Saldo (0D)

Els contenidors estàndard contenen saldos fungibles:

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

Exemple: Un inventari de reactius on només t’importen les quantitats totals.

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

Slots (1D)

Els contenidors de slot mantenen instàncies úniques en posicions seqüencials:

• Índexs de 0 a N-1 (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": 0
  }
}

Reixeta (2D)

Els contenidors de graella afegeixen geometria espacial:

• 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 emmagatzemen instàncies al llarg d’un eix de punt fix únic:

• 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 emmagatzemen instàncies en un espai de treball continu i delimitat:

• 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

Actius fungibles són quantitats intercanviables:

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

Instàncies úniques són rastrejades individualment:

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

Classes i formes

Classes defineix tipus d’actius:

• Especifiqueu si els actius són fungibles o únics
• Proporcionar metadades com noms
• Ha de ser registrat abans d’usar-se

Les formes defineixen empremtes espacials:

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

{
  "op": "RegisterClass",
  "args": {
    "request": {
      "class_id": 200,
      "name": "Sample Tube",
      "fungible": false
    }
  }
}

Com s’integra al sistema

Operació de Despatx

El temps d’execució despacha operacions en funció del tipus de contenidor:

• AddFungible a Estàndard: addició directa de saldo
• AddFungible a la Xarxa: col·locació espacial amb cerca de forma
• AddFungible en Slots: rebutjat (tipus de contenidor incorrecte)

Aquesta distribució es gestiona internament; els clients especifiquen operacions sense conèixer els detalls interns del contenidor.

Generació d’Esdeveniments

Cada tipus de contenidor genera esdeveniments adequats:

• Estàndard: BalanceAdded, BalanceRemoved
• Slots: SlotOccupied, SlotCleared
• Reixeta: GridPlacement, StackQtyChanged

Els esdeveniments porten un estat posterior per a la reproducció determinista.

Manteniment de l’Índex

El temps d’execució manté índexs per a consultes eficients:

• Consultes de saldo per classe i clau
• Ubicacions d’instàncies per ID
• Ocupació de slots per índex

Aquests índexs s’actualitzen atòmicament amb operacions.

Invariants i garanties clau

Cicle de Vida del Contenidor

• Els contenidors s’han de crear abans d’usar-los
• Els contenidors han d’estar buits abans de la seva eliminació
• Els IDs dels contenidors no poden ser reutilitzats

Restriccions de Capacitat

• Els índexs de slot han de ser dins dels límits
• Les ubicacions de la graella han de cabre dins les dimensions
• Les quantitats no poden desbordar u64

Seguretat de Tipus

• Les operacions fungibles rebutgen els contenidors Slots
• Les operacions de slot rebutgen contenidors estàndard
• Les operacions validen el tipus de contenidor abans de l’execució

Veure també

• Transaccions i Operacions - Com funcionen les operacions

5. Operacions per Domini - Referència completa d’operacions

• Model d’execució - Com s’integren els contenidors en l’arquitectura