ENDPOINTS_CABLES_TALLER_SISTEMAS_PRODUCCION

# Endpoints / Cables — Atelier → Sistemas → Producción

**Proyecto de ingeniería** · `::::atelier::universalis::::` + `::::artemisa::::universalis::::`  
**Fecha:** 2026-07-09  
**Operador:** alfonso@terrauniversalis.com  
**Lema:** `facta non ficta`  
**Estado:** propuesta arquitectónica — lista para lane Claude Design + implementación Codex/Grok  
**Registro Alexandria:** extiende ALEX-002 (Atelier Universalis)

---

## 0. Qué resuelve este documento

Define el **mecanismo de cables** que conecta tres capas de diseño sin romper producción:

1. **Atelier (global)** — endpoints de sistema de diseño que sujetan **todos** los sistemas al mismo look; un cambio de tema aquí propaga a todo el ecosistema.
2. **Diseño individual por sistema** — cada superficie (Bastion, membresías Terrauniversalis, apps de dominio) tiene su lane propia pero **nunca** desconectada del cable Atelier.
3. **Transversal Artemisa / Alexandria / Cartografía** — fase de diseño coordinada donde los sistemas viven antes de promoverse; Nepohua entra como capa ciudadana en el proceso Alexandria.

La transición **taller → preproducción → producción** debe ser **sutil**: en preproducción ya existen endpoints de producción en formación; en producción **permanecen** los endpoints de diseño **y** los de producción, con **retroalimentación** bidireccional.

---

## 1. Principios no negociables

| # | Regla |
|---|---|
| P1 | **Nunca se corta el cable de diseño** al promover a producción. Producción = diseño + runtime, no diseño reemplazado. |
| P2 | **Un repo, un portal, un gateway** (`unicornd :8800`). Cables internos vía proxy; `endpoints-config.js` es fuente de verdad de runtime. |
| P3 | **Cambio de look global** solo por Atelier DS endpoints — no por parches locales en cada HTML. |
| P4 | **facta non ficta** — fase `verified` solo con evidencia (health, SHA, Nexus, manifest). |
| P5 | **Retroalimentación obligatoria** — drift visual en producción dispara `alexandria:design-review` en Nexus. |

---

## 2. Mapa de facetas (no secuencial — concurrente)

```mermaid
graph TB
  subgraph ATELIER["Fase 0 · Atelier Global · DS Endpoints"]
    DS_TOKENS["ds-tokens / tokens.css"]
    DS_BUNDLE["_ds_bundle.js"]
    DS_THEME["theme-registry.json"]
    DS_API["/atelier-api · registro de cables"]
  end

  subgraph INDIVIDUAL["Fase 1 · Diseño individual por sistema"]
    BASTION["Bastion / dist/official/*"]
    ALEX_D["alexandria-design/"]
    SIST_D["sistemas-design/"]
    CART_D["cartografia · claude-design"]
    MEMB["membresías TU · Analaury · Calexico · …"]
  end

  subgraph TRANSVERSAL["Fase 2 · Transversal · diseño coordinado"]
    ART["::::artemisa::::universalis::::"]
    ALEX["Alexandria · Living Library"]
    NEP["Nepohua · capa ciudadana"]
    CART["Cartografía Universalis"]
    NEX["Nexus · bus de handoff"]
  end

  subgraph RUNTIME["Fase 3 · Producción + preproducción"]
    DIST["dist/official/<sistema>/"]
    PROXY["unicornd proxies :8812–:8822"]
    EP_CFG["assets/endpoints-config.js"]
  end

  DS_TOKENS --> INDIVIDUAL
  DS_BUNDLE --> INDIVIDUAL
  DS_THEME --> INDIVIDUAL
  DS_API --> INDIVIDUAL

  INDIVIDUAL --> TRANSVERSAL
  ART --> ALEX
  ALEX --> NEP
  ALEX --> CART
  TRANSVERSAL --> NEX

  INDIVIDUAL --> RUNTIME
  TRANSVERSAL --> RUNTIME
  ATELIER --> RUNTIME

  DIST -.->|retroalimentación design-review| ATELIER
  EP_CFG -.->|drift detectado| DS_API
```

**Lectura:** Artemisa Systems (Grok/Codex) y Atelier (Claude Design/Code) corren **en paralelo**, no en fila. Alexandria y Cartografía son el **tablero transversal** donde se ve qué sistema está en qué fase de cable.

---

## 3. Taxonomía de endpoints y cables

### 3.1 Tipos de endpoint

| Tipo | ID canónico | Qué expone | Dónde vive | Persiste en prod |
|---|---|---|---|---|
| **DS-GLOBAL** | `atelier://ds/{token\|theme\|bundle}` | tokens, temas, tipografía, motion | `static/official/.../assets/ds-tokens/`, `_ds_bundle.js` | **Sí — permanente** |
| **DS-LANE** | `atelier://lane/{sistema}` | handoff Claude, workspace diseño | `static/official/{sistema}-design/` | **Sí — permanente** |
| **DS-SURFACE** | `atelier://surface/{sistema}` | HTML/CSS/JS de diseño activo | `{sistema}-design/` o `cartografia-claude-design.html` | **Sí — permanente** |
| **PRE-PROD** | `bastion://pre/{sistema}` | build candidato, mirrors, SHA | `dist/official/{sistema}/` + `*_control.*` | Migra a PROD |
| **PROD-RUNTIME** | `bastion://prod/{sistema}` | URL servida `:8800/{sistema}/` | `dist/official/{sistema}/` | **Sí** |
| **PROD-API** | `bastion://api/{slug}` | bridge interno | `tools/*_bridge.py` → proxy en gateway | **Sí** |
| **CABLE** | `cable://{origen}/{destino}` | enlace declarado entre dos endpoints | `config/atelier/endpoints-registry.v1.json` | **Sí — registro** |

### 3.2 El cable (definición de ingeniería)

Un **cable** no es un archivo suelto: es un registro verificable con:

```yaml
cable_id: cable-alexandria-ds-to-prod
from: atelier://lane/alexandria
to: bastion://prod/alexandria
phase: production          # workshop | preproduction | production
kind: design-to-runtime    # ds-global | design-to-runtime | api-bind | feedback
bindings:
  - source: ../assets/ds-tokens/tokens.css
    target: dist/official/alexandria/  # relativo a dist root
  - source: alexandria-layout.css
    target: dist/official/alexandria/
feedback:
  nexus_tag: alexandria:design-review
  health_check: atelier_ds_compliance
  on_drift: open_blocker
immutable_after_promote: [from]   # el endpoint de diseño NO se borra
```

---

## 4. Flujo de fases — taller → preproducción → producción

```mermaid
stateDiagram-v2
  [*] --> TALLER: nuevo sistema / nueva superficie

  TALLER --> PREPROD: handoff Atelier + cable DS-LANE
  note right of TALLER
    Workspace: *-design/
    Claude Design construye aquí
    Cable DS-GLOBAL ya conectado
  end note

  PREPROD --> PREPROD: endpoints PROD en formación
  note right of PREPROD
    dist/official/{sistema}/ recibe mirrors
    PROD-API stubs o bridges reales
    Dual mirror SHA como Catrina
  end note

  PREPROD --> PRODUCCION: certificar + operador aprueba
  note right of PRODUCCION
    DS-LANE + DS-SURFACE permanecen
    PROD-RUNTIME activo en :8800
    Retroalimentación Nexus activa
  end note

  PRODUCCION --> PREPROD: redesign mayor
  PRODUCCION --> TALLER: dinamitar molde (Artemisa)
```

### 4.1 Qué ocurre en cada fase

| Fase | Endpoints activos | Responsable | Evidencia |
|---|---|---|---|
| **Taller** | DS-GLOBAL + DS-LANE + DS-SURFACE | claude-design | `*-design/CLAUDE_DESIGN_HANDOFF.md` |
| **Preproducción** | Todo lo anterior + PRE-PROD + PROD-API (stubs→reales) | claude-design + codex | dual mirror, health parcial |
| **Producción** | **Todos** + PROD-RUNTIME estable | codex/grok + atelier review | `alexandria_health`, Nexus, ALEX record |

---

## 5. Registro canónico de cables

**Archivo:** `config/atelier/endpoints-registry.v1.json`  
**API futura:** `/atelier-api/api/atelier/registry` (propuesta — puerto interno sugerido `:8823`)

Cada **sistema** en el registro tiene:

```json
{
  "system_id": "alexandria",
  "namespace": "::::alexandria::::",
  "phase": "production",
  "membership_tu": null,
  "endpoints": {
    "ds_global": ["atelier://ds/tokens", "atelier://ds/bundle"],
    "ds_lane": "atelier://lane/alexandria",
    "ds_surface": "static/official/alexandria-design/",
    "pre_prod": "static/official/primera netrega oficial v2/dist/official/alexandria/",
    "prod_runtime": "http://127.0.0.1:8800/alexandria/",
    "prod_api": "/alexandria-api"
  },
  "cables": ["cable-alexandria-ds-to-prod"],
  "feedback": { "nexus_tag": "alexandria:design-review", "last_review": null }
}
```

### 5.1 Sistemas inventariados (hecho verificado 2026-07-09)

| system_id | Fase | DS-LANE | PROD-RUNTIME | Notas |
|---|---|---|---|---|
| `alexandria` | production | `alexandria-design/` ● | `/alexandria/` | patrón referencia |
| `cartografia` | production | claude-design en cartografia/ ● | `/cartografia/` | proyecto Claude.ai origen |
| `sistemas` | preproduction | `sistemas-design/` ● | `/sistemas/` | 23 consolas |
| `mayantraktor-live` | preproduction | `mayantraktor-design/` ● | `/mayantraktor-live/` | canon ART-025 |
| `nexus` | workshop | pendiente | `/nexus/` | sin lane Atelier aún |
| `bastion` | production | implícito vía DS global | `/` + múltiples | shell gateway |
| `analaury` | **pendiente** | sin ruta en repo | — | membresía TU — operador |
| `calexico` | **pendiente** | sin ruta en repo | — | membresía TU — operador |

### 5.2 Capa transversal

| Pieza | Rol en el cable | Rutas canónicas |
|---|---|---|
| **Artemisa** | metodología + certificación | `docs/archivum/ARTEMISA_UNIVERSALIS.md`, `.alexandria/artemisa-consolidation.yml` |
| **Alexandria** | nervio vivo, gradiente confianza, depósitos ALEX | `.alexandria/contract.yml`, `architecture/ALEXANDRIA.md` |
| **Nepohua** | capa ciudadana en el proceso (no consola MIDI) | `docs/archivum/terrauniversalis-ancestral/` |
| **Cartografía** | mapa visual de sistemas + fase de cable | `dist/official/cartografia/` |

---

## 6. Cambio de look global (el poder de Atelier)

```text
Operador / Claude Design cambia theme-registry.json
  → Atelier valida tokens contra SKILL.md DS
  → POST Nexus tag atelier:theme-change
  → Todos los sistemas con cable DS-GLOBAL recargan tokens.css + _ds_bundle.js
  → alexandria_health check atelier_ds_compliance
  → Si drift: alexandria:blocker por superficie
```

**Implementación mínima (ingeniería):**

1. `config/atelier/theme-registry.v1.json` — temas nombrados (`obsidian`, `catrina`, `ndi`, …).
2. Cada HTML de producción incluye **solo** la cadena canónica (ya documentada en `BASTION_DESIGN_BINDINGS.md`).
3. `tools/atelier_promote_theme.py` — aplica tema a registro + postea Nexus (propuesta).
4. Cartografía muestra **qué sistemas** están en qué tema (visual — trabajo Claude Design).

---

## 7. Retroalimentación producción → diseño

```mermaid
sequenceDiagram
  participant PROD as dist/official/{sistema}
  participant GW as unicornd :8800
  participant HEALTH as alexandria_health
  participant NEX as Nexus :8812
  participant ATELIER as Atelier / claude-design
  participant CART as Cartografía

  PROD->>GW: sirve HTML con tokens
  HEALTH->>PROD: scan DS compliance
  alt drift detectado
    HEALTH->>NEX: alexandria:blocker + superficie
    NEX->>ATELIER: alexandria:design-review
    ATELIER->>PROD: patch en *-design/ (no directo en prod sin sync)
  else ok
    HEALTH->>CART: actualiza fase verde
  end
```

**Regla:** los parches visuales entran por `*-design/` o DS global; la promoción a `dist/official/` es un **cable explicito** (script o handoff), nunca edición accidental en producción.

---

## 8. Integración con infraestructura existente

| Pieza existente | Cómo se conecta al cable |
|---|---|
| `assets/endpoints-config.js` | Añadir sección `designCables[]` apuntando a DS-GLOBAL y `/atelier-api` |
| `tools/unicornd_gateway.py` | Nuevo proxy `/atelier-api` → `:8823` (propuesto) |
| `tools/alexandria_health.py` | Check `atelier_ds_compliance` por superficie |
| `tools/alexandria_team_sync.py` | Tags `atelier:theme-change`, `alexandria:design-review` |
| `tools/tunnel/8800-config.ps1` | URLs tunnel para Claude Design cloud |
| Patrón Catrina dual mirror | Modelo para PRE-PROD → PROD con SHA |

---

## 9. Entregables de ingeniería (PR plan)

### Ola 1 — Registro y documentación (sin romper prod)
- [ ] `config/atelier/endpoints-registry.v1.json` — poblar 14 superficies `dist/official/`
- [ ] `config/atelier/theme-registry.v1.json` — tema `obsidian` baseline
- [ ] Este documento + handoff Claude Design

### Ola 2 — Atelier API mínima
- [ ] `tools/atelier_registry_bridge.py` + `start-atelier-bridge.ps1`
- [ ] Proxy en `unicornd_gateway.py`: `/atelier-api`
- [ ] `GET /api/atelier/registry`, `GET /api/atelier/cables/{system_id}`

### Ola 3 — Health + Nexus
- [ ] Check DS compliance en `alexandria_health.py`
- [ ] Cartografía: capa visual de fases de cable (Claude Design)

### Ola 4 — Membresías TU
- [ ] Lanes `analaury-design/`, `calexico-design/` cuando operador defina rutas
- [ ] Entrada en registry con `membership_tu: true`

---

## 10. Prompt listo para Claude Design

Ver handoff operativo:

`static/official/atelier-design/CLAUDE_DESIGN_HANDOFF.md`

**Tu primera entrega visual:** panel **Atelier Control** + actualización **Cartografía** con:
- grafo de cables por sistema
- fase (taller / preprod / prod)
- estado DS (compliant / drift / sin lane)
- acción: “cambiar look global” → selección de tema

---

## 11. Pendientes honestos

| Item | Estado |
|---|---|
| Analaury / Calexico rutas en repo | `REFERENCIA_SIN_RUTA` — membresías declaradas por operador |
| `/atelier-api` bridge | propuesto — no implementado |
| 10 superficies sin lane Atelier | circus, nexus, grp, midi, … — ver `architecture/SYSTEM_MAP.md` §4 |
| Diff `contract.yml` design_workspaces | propuesto en `.alexandria/proposals/atelier-universalis.md` — no aplicado |

---

::::facta::non::ficta::::