# Arsenal Nexora V2 · Fase 4 — DbVersion 3 extendido y catálogo Warehouse

## Objetivo

Habilitar de forma comprobada los índices de ítem `256–511` en Warehouse DbVersion 3 sin alterar la transacción de compra, y corregir la fuente de verdad usada para el tamaño físico de los ítems.

## Evidencia del formato

Las muestras obtenidas desde el Warehouse Editor del mismo entorno confirman el layout de 16 bytes:

- `0:350`, durabilidad 90, serial 35713 → `5E005A00008B8180000000FFFFFFFFFF`
- `13:270`, durabilidad 255, serial 35712 → `0E00FF00008B808000D000FFFFFFFFFF`
- `0:350`, durabilidad 255, serial 35719 → `5E00FF00008B8780000000FFFFFFFFFF`
- `13:270`, durabilidad 255, serial 35720 → `0E00FF00008B888000D000FFFFFFFFFF`

La regla confirmada es:

- byte 0 = `Index & 0xFF`;
- byte 7, bit `0x80` = bit `0x100` del Index;
- byte 7, bits `0x3F` = Excellent;
- byte 7, bit `0x40` = tercer bit de la opción adicional;
- byte 9, nibble alto = Section/Type.

Por tanto DbVersion 3 codifica de forma directa `Index 0–511`. El catálogo entregado por Nexora llega como máximo a 510, así que sus 1.839 entradas quedan dentro del rango comprobado.

## Cambios de encoder y decoder

- `encodeItem()` conserva el byte bajo del Index en byte 0 y escribe el bit alto en `byte7 & 0x80`.
- La lectura del Warehouse reconstruye el Index antes de resolver dimensiones, evitando confundir `0:350` con `0:94` o `13:270` con `13:14`.
- `NexoraItemDecoder` usa la misma regla para el equipamiento público.
- Los assets del perfil admiten índices hasta 511.
- El formulario y la validación backend admiten `item_index 0–511`.

## Migración SQL

La columna ya era `smallint`; el bloqueo estaba en `CK_NIS_index`. `Instalar / validar tablas` migra instalaciones existentes de `0–255` a `0–511` y las instalaciones nuevas nacen directamente con el nuevo constraint.

Después de aplicar el parche entra en cada reino y ejecuta:

`AdminCP → Arsenal Nexora → Configuración → Instalar / validar tablas`

El diagnóstico `Índices extendidos 0–511` debe quedar en verde.

## Catálogo técnico reconciliado

`Items.xml` del Warehouse Editor y `Item.txt` contienen los mismos 1.839 códigos, pero se detectaron 95 discrepancias de dimensiones. Para la ocupación del Warehouse, Arsenal 1.3.0 usa `Items.xml` (atributos `X/Y`) como fuente primaria y conserva `Item.txt` como contraste.

Ejemplo detectado:

- `0:10 Light Saber`: Warehouse Editor `2×4`; Item.txt `1×4`.

El AdminCP muestra la discrepancia y el backend exige la huella definida por el Warehouse Editor. La inferencia por imagen continúa siendo un fallback y nunca sobreescribe silenciosamente el catálogo técnico.

El catálogo normalizado también conserva `Excellent`, `Level380` y `Socket` de `Items.xml` para futuras mejoras del editor.

## Regeneración

Recomendado:

```bash
php includes/plugins/itemshop/tools_build_item_catalog.php /ruta/Items.xml /ruta/Item.txt
```

El modo antiguo con solo Item.txt sigue disponible, pero pierde la validación cruzada de X/Y y capacidades.

## Validación ejecutada

Se verificó localmente que el encoder produce exactamente los cuatro HEX capturados del Warehouse Editor. También se probaron los bordes `255`, `256` y `511`, la decodificación pública de `0:350`, el reconocimiento de un ítem extendido ya presente en el baúl y el catálogo completo de 1.839 ítems.

La función transaccional `purchase()` no cambia en esta fase; cambia únicamente la codificación del ítem que se inserta y la lectura segura del índice existente.
