# Arquitectura general MayanTraktor

Documento maestro del módulo `mayantraktor-live`.

Estado: `ARQUITECTURA_CONSOLIDADA_PENDIENTE_VALIDACION_HARDWARE_COMPLETA`.

Este documento explica cómo encajan todos los componentes. No sustituye el canon ART-025, los mappings fuente ni las tablas técnicas: los organiza y establece cuál documento gobierna cada decisión.

## 1. Autoridad documental

Orden de autoridad:

1. ART-025, `reglamento_mayan_traktor_mapeado_espejo.md`.
2. Captura MIDI cruda confirmada desde hardware.
3. Mapping fuente preservado con `source_mapping_id` y hash.
4. `mayantraktor-mapping.json`, contrato normalizado.
5. Este documento maestro.
6. Planes, tablas, auditorías y checklists subordinados.

Si dos documentos discrepan, no se adivina. Se conserva el hardware, se marca el conflicto y se resuelve con captura física.

## 2. Principio rector

MayanTraktor es una consola distribuida:

```text
MK2 izquierda        Traktor X1 / 00         MK2 derecha
base y detalle       coordinación central    espejo y detalle

       M32: teclado y knobs transversales
       Hercules: mezclador y transporte compacto
       Bastion: catálogo, estado, seguridad y salida
```

Regla ART-025:

- El hardware Native es intocable como identidad física.
- El espejo Mayan es lectura lógica y visual.
- Página, color, función y aplicación son capas.
- Ningún pad o botón cambia físicamente de identidad.
- La salida final se habilita únicamente después de identificar, validar y probar el mensaje.

## 3. Flujo general

```text
control físico
-> endpoint MIDI
-> captura cruda
-> identidad técnica
-> filtro y cuarentena
-> resolución de modificador/capa
-> mirror lógico
-> mapping fuente preservado
-> acción de aplicación
-> guardia de seguridad
-> salida y verificación
```

Un evento no debe saltarse ninguna etapa para llegar a una salida operativa.

## 4. Capas obligatorias de un control

| Capa | Contenido |
| --- | --- |
| Física | Equipo, lado, página, posición y nombre Native |
| MIDI técnica | Endpoint, tipo, canal, data, valores y resolución |
| Routing | Directo, USB, Bome, red, virtual port o aplicación |
| Mirror | Fuente lógica, destino espejo y transformación |
| Familia | Dominio 01-04 |
| Profundidad | `BASE`, `ADVANCED` o modificador explícito |
| Aplicación | djay, Traktor, Maschine, Windows, OBS, NDI, Bastion, etc. |
| Función | Acción concreta solicitada |
| Seguridad | Confirmación, límites, fallback y cuarentena |
| Provenance | Archivo fuente, hash, fecha y captura |
| Verificación | `pending`, `captured`, `tested`, `locked` o `quarantined` |

Llave técnica:

`physical_device_id + endpoint + message_type + channel + data`

## 5. Superficies y responsabilidades

| Superficie | Endpoint/ruta | Responsabilidad |
| --- | --- | --- |
| MK2 izquierda | `midiuniversalis`, canal humano 14 | Base, Deck 1/3, pads, FX, stems, browser y acciones profundas |
| MK2 derecha | Endpoint Maschine/MSI independiente | Espejo, Deck 2/4, pads, FX, stems, browser y acciones profundas |
| Traktor Kontrol X1 | Endpoint propio | Nodo `00`, familia, profundidad, coordinación y retorno seguro |
| Komplete Kontrol M32 | `midiuniversalis`, canal humano 15 propuesto | Teclas y knobs transversales, cuatro páginas |
| Hercules DJControl Mix | `DJCONTROL MIX` | Mezcla, volúmenes, EQ por capas, jogs y transporte |
| Bastion | Gateway oficial existente | Catálogo, listener, estado, filtros, seguridad y despacho |

Compartir un número MIDI entre endpoints distintos no es conflicto. Compartir una identidad completa dentro del mismo controlador sí lo es.

## 6. Familias y páginas

| Familia | Color | Dominio | MK2 izquierda BASE | MK2 derecha BASE | MK2 izquierda ADV | MK2 derecha ADV | M32 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `01` | Verde | Audio, MIDI, ASIO y mezcla | A | D | E | H | 1 |
| `02` | Azul | Video, NDI y streaming | C | B | G | F | 2 |
| `03` | Dorado | Producción, djay, Traktor y grabación | B | C | F | G | 3 |
| `04` | Magenta | Windows, voz, RPA, Bastion e IA | D | A | H | E | 4 |

Los colores son metadata de Bastion. No ordenan cambiar los LEDs físicos Native.

`SHIFT` añade una capa lógica secundaria y se representa con indicador blanco. Error y cuarentena usan rojo y naranja en Bastion.

## 7. Espejo MK2

La MK2 derecha conserva su numeración Native y recibe una lectura mirror horizontal:

```text
L13 <-> R16    L14 <-> R15
L09 <-> R12    L10 <-> R11
L05 <-> R08    L06 <-> R07
L01 <-> R04    L02 <-> R03
```

Ejemplo correcto:

```text
native_physical_id = right_pad_16
mayan_mirror_source = left_pad_13
```

Nunca registrar que el pad físico 16 “se convirtió” en pad 13.

## 8. Identidad MIDI por controlador

### Maschine MK2

- Ocho páginas A-H.
- Dieciséis pads por página.
- Cada MK2 utiliza notas `0-127` una sola vez entre todas sus páginas.
- Knobs, botones y transportes también deben tener identidades completas únicas.
- Los perfiles generados reportan cero duplicados.

### M32

- Cuatro páginas de teclas y knobs.
- Se configura mediante Komplete Kontrol MIDI Assignment Editor.
- Comparte ruta con MK2 izquierda, pero debe quedar separada por canal y tipo.
- La configuración física y carga siguen pendientes.

### Traktor X1

- Conserva endpoint y mensajes nativos.
- El botón verde central está reservado como candidato `00_universalis`.
- Su identidad MIDI exacta sigue pendiente de captura.

### Hercules

- El mapping djay contiene 110 bindings y 110 identidades completas únicas.
- Los números repetidos entre lados están separados por canal.
- Esto prueba el archivo de aplicación, no todavía la emisión cruda.
- Los pares iPad `CCn + CC(n+32)` permanecen bloqueados hasta la prueba A/B.

## 9. Mezcla, transporte y browser

### Hercules: mezclador y transporte

- Seis knobs: master, monitor y controles de deck; buses finales pendientes de aprobación.
- Sliders: volúmenes, crossfader y tempo según captura.
- Jogs: resolución `NORMAL` y `FINE` como capas lógicas pendientes de modificador real.
- PLAY/CUE/SYNC: transporte inmediato y seguro.
- HIGH/MID/BASS: capas condicionadas; nunca mappings simultáneos sobre el mismo CC.

### MK2: browser y biblioteca

Ambas MK2 conservan:

| Control | MIDI Native |
| --- | --- |
| Browse | CC87 |
| Enter | CC100 |
| Dial | CC101 |
| StepL | CC105 |
| StepR | CC106 |
| Restart | CC104 |
| Play | CC108 |
| Rec | CC109 |

La MK2 izquierda carga Deck 1/3 y la derecha Deck 2/4 según familia. El destino de deck es función lógica, no cambio del CC Native.

## 10. Topología de routing

- USB es la conexión preferida para controladores durante el live.
- Bome y MIDI de red son capas de routing, no fuentes de identidad física.
- `midiuniversalis` y `midiuniversalis main` deben conservarse como rutas diferenciadas.
- Ninguna ruta puede transmitir eventos no clasificados hacia sintetizadores o salidas audibles.
- Los endpoints de Bastion solo pueden provenir de `assets/endpoints-config.js`.
- Todo módulo web permanece detrás del gateway oficial `:8800`; no se crea servidor ni puerto adicional.

## 11. Audio del live

- Windows y djay Pro: Behringer UMC404HD OUT 1-2.
- Fallback físico desde hub HP G5 hacia canales 1-2.
- Machines/M32: ruta física hacia Behringer canal 3 según configuración del operador.
- iPad/live input: entrada cableada, no Bluetooth.
- Sonos: Line-In cableado para evitar latencia.
- MSI Realtek no se modifica durante preparación de live.

Toda automatización de volumen necesita:

1. rango seguro;
2. salida identificada;
3. prueba audible;
4. fallback manual;
5. recuperación sin reiniciar toda la consola.

## 12. Seguridad y cuarentena

- Nunca matar procesos directamente desde un botón.
- Nunca cambiar salida de audio sin fallback.
- Nunca borrar un mapping sin exportación y hash.
- Nunca aprender CC secundarios de iPad hasta aislar origen.
- `AD 00 47` y `AD 00 48` permanecen en cuarentena.
- Ningún evento desconocido puede alcanzar Microsoft GS Wavetable Synth ni otra salida audible.
- Una capa o color no autoriza ejecución por sí mismo.

## 13. Estados operativos

| Estado | Significado |
| --- | --- |
| `PENDING_CAPTURE` | Existe intención, falta MIDI físico |
| `CAPTURED` | Mensaje crudo asociado al control |
| `SOURCE_CONFIRMED` | Existe mapping fuente preservado |
| `TESTED` | Acción probada en plataforma concreta |
| `LOCKED` | Binding confirmado y protegido |
| `QUARANTINED` | Evento bloqueado por ruido o riesgo |
| `PARTIAL` | Solo parte de una transacción respondió |
| `NO_PROBADO_HARDWARE_FISICO` | No existe prueba física suficiente |

No usar `LOCKED` para una propuesta o inferencia.

## 14. Fuente de verdad por tema

| Tema | Documento |
| --- | --- |
| Canon mirror | ART-025 |
| Contrato completo | `mayantraktor-mapping.json` |
| Tabla humana | `mapping-table.md` |
| Identidad y familias | `mayantraktor-console-identity-proposal.md` |
| MK2 A-H | `controller-editor-8-pages-remap.md` |
| M32 | `komplete-kontrol-m32-4-pages-remap.md` |
| Hercules | `hercules-djcontrol-mix-mapping-plan.md` |
| Auditoría Hercules | `hercules-source-audit.json` |
| Transporte/browser | `transport-mixer-browser-architecture.md` |
| Colores | `generated-controller-profiles/bastion-layer-colors.json` |
| Prueba del live | `live-checklist.md` |
| Defectos | `defects-log-template.md` |
| Fuentes reales | `source-mappings/mayan.mappings/` |

## 15. Secuencia de puesta en marcha

1. Exportar y respaldar mappings actuales.
2. Cargar y verificar perfiles MK2 en cada máquina.
3. Configurar M32 en su equipo.
4. Capturar el botón verde X1 y selectores de familia.
5. Capturar Hercules directa y después con routing activo.
6. Resolver CC secundarios del iPad.
7. Filtrar eventos en cuarentena.
8. Probar browser MK2 por separado.
9. Probar mezcla y transporte Hercules.
10. Probar mirror y decks 1-4.
11. Probar audio y fallback.
12. Ejecutar checklist completo.
13. Cambiar de demo a operativo únicamente después de evidencia real.

## 16. Estado actual

Confirmado:

- Repo, módulo y ruta canónica.
- Mappings fuente importados.
- Roles generales de las superficies.
- Identidades MK2 generadas sin duplicados.
- Mapping Hercules de aplicación sin duplicados completos.
- Colores semánticos y arquitectura de browser/transporte.

Confirmado por operador:

- Perfil A-H cargado en Controller Editor de ambas MK2.

Pendiente:

- Prueba MIDI de páginas A/C en MK2 izquierda.
- Prueba MIDI de páginas D/B en MK2 derecha.
- Configuración física M32.
- Captura exacta del `00` X1.
- Captura cruda completa Hercules.
- Pruebas A/B de iPad.
- Prueba integral de audio y live.

Resultado requerido:

`ONE_CONSOLE_ONE_GEOGRAPHY_SYNCHRONIZED_FAMILIES_ZERO_DUPLICATES`

Marca de prueba global:

`NO_PROBADO_HARDWARE_FISICO_COMPLETO`