# Codex Suite · Modular Foundation v1

> Estado: **0.1 backend completado**. Corte: 5 de agosto de 2026.

Esta fase reduce el acoplamiento de `server.js` y del cliente web sin cambiar rutas, payloads, autenticación ni superficies visibles. Cada extracción debe pasar contratos, pruebas completas y arranque aislado antes de continuar.

## Orden de extracción backend

1. **0.1a Frontera de sesión y origen · completado**
   - Propietario: `lib/codex-session-boundary.js`.
   - Responsabilidades: comparación constante del token heredado, sesión en memoria, cookie, expiración deslizante, mismo origen, middleware Codex, compatibilidad del bridge y estado de hardening.
   - Rutas registradas: `POST|GET|DELETE /api/codex/session` y `POST|GET|DELETE /api/bridge/session`.
   - El token, los IDs y el mapa de sesiones permanecen privados al módulo.
2. **0.1b Bootstrap y administración · completado**
   - Propietario: `lib/codex-admin-routes.js`.
   - Ocho rutas: status, comandos, settings, administración segura y diagnóstico.
   - El diagnóstico conserva 23 checks y recibe todas sus capacidades por inyección explícita.
3. **0.1c Workspace y contexto · completado**
   - Propietario: `lib/codex-workspace-routes.js`.
   - Diez rutas: catálogo y búsqueda de archivos, explorer/preview, creación de carpetas, perfil, adjuntos e instrucciones.
   - Una guardia común confina las lecturas al workspace permitido; el catálogo no devuelve rutas absolutas y las cuatro mutaciones conservan control de mismo origen.
   - Integraciones, capacidades y marketplace permanecen deliberadamente en 0.1d para evitar mezclar dominios.
4. **0.1d Modelos y capacidades · completado**
   - Propietario: `lib/codex-capability-routes.js`.
   - Diecinueve rutas: router/evals de modelos, complementos, integraciones, MCP, plugins, marketplaces, seguridad read-only y capacidades del App Server.
   - Las diez mutaciones conservan mismo origen y las confirmaciones exactas; las lecturas con scope comparten una guardia de workspace.
   - Deployment permanece en 0.1f porque publica estado/configuración y no forma parte del catálogo de capacidades.
5. **0.1e Threads, turns y SSE · completado**
   - Propietario: `lib/codex-thread-routes.js`.
   - Diecinueve rutas: listado/creación/reanudación/lectura, runtime, controles de thread, turns, steer/cancel/recover, aprobaciones y SSE.
   - Las catorce mutaciones conservan mismo origen; borrar conserva confirmación exacta y las decisiones de aprobación desconocidas degradan a rechazo.
   - Contratos, checkpoints, preflight, decisiones de archivos, rollback y deploy permanecen en 0.1f como un único dominio de evidencia/publicación.
6. **0.1f Evidence, checkpoints, staging y deploy · completado**
   - Propietario: `lib/codex-evidence-routes.js`.
   - Dieciséis rutas: Evidence Ledger, Workspace Twin, deployment, contratos, checkpoints/revisión, preflight, decisiones por archivo y rollback.
   - Las ocho mutaciones conservan mismo origen; aceptación mantiene gates de preflight/contrato y deploy únicamente de archivos aceptados.
   - Las lecturas de evidencia y Twin siguen marcadas como read-only y las rutas con scope comparten guardia de workspace.
7. **0.1g Composición y error boundary · completado**
   - Propietario: `lib/codex-suite-router.js`.
   - Compone las 75 rutas `/api/codex`, UI, sesiones y los cinco módulos de dominio mediante inyección explícita.
   - Un único error boundary conserva status y payload históricos, pero registra solo método, path sin query, status y código de error.
   - El cierre es idempotente, desuscribe Evidence e intenta cerrar monitor y App Server aunque falle un recurso.

## Contratos congelados en 0.1a

- No se acepta token mediante query string ni body fuera de la ruta de intercambio de sesión.
- La compatibilidad temporal usa exclusivamente `X-Bridge-Token`.
- La cookie continúa siendo `HttpOnly`, `SameSite=Strict`, `Path=/` y `Secure` cuando el transporte es HTTPS.
- Las mutaciones requieren mismo origen, allowlist explícita, contexto `Sec-Fetch-Site` permitido o la cabecera heredada.
- Codex Suite y las aplicaciones del bridge continúan compartiendo la sesión de forma compatible.

## Evidencia 0.1a

- Sintaxis: `node --check` sobre el módulo y `server.js`.
- Pruebas: **71/71** superadas; se añadieron dos pruebas conductuales de sesión.
- Servidor aislado `127.0.0.1:8101`: intercambio de sesión 200, cookie presente, status Codex 200 y status de sesión bridge 200.
- Un origen hostil recibió 403 en una mutación.
- El puerto 8101 quedó detenido.

## Evidencia 0.1b

- Sintaxis: `node --check` sobre el módulo y `server.js`.
- Pruebas: **73/73** superadas; dos nuevas pruebas cubren rutas/middleware y contratos de settings/diagnóstico.
- Servidor aislado `127.0.0.1:8101`: status, comandos, settings y administración devolvieron 200 sin exponer el token del bridge.
- Diagnóstico real: 23 checks, 0 errores; mutación con origen hostil: 403.
- El puerto 8101 quedó detenido.

## Evidencia 0.1c

- Sintaxis: `node --check` sobre `lib/codex-workspace-routes.js` y `server.js`.
- Pruebas: **75/75** superadas en 17 archivos; dos contratos nuevos cubren el registro exacto, middleware, ocultación de rutas y rechazo de workspaces desconocidos.
- Servidor aislado `127.0.0.1:8101`: sesión correcta, 30 workspaces catalogados sin el campo `path`, búsqueda, explorer, preview, perfil e instrucciones operativos.
- Un workspace desconocido recibió 400 y una mutación con origen hostil recibió 403. El smoke test no creó archivos ni modificó el perfil.
- El puerto 8101 quedó detenido y libre tras la prueba.
- Tras reiniciar el bridge principal: `/health`, `/codex-suite`, `/apps` y el login vecino de Lliria Properties respondieron 200; workspace autenticado respondió 200 y las lecturas anónimas de administración/workspace, 401.

## Evidencia 0.1d

- Sintaxis: `node --check` sobre `lib/codex-capability-routes.js` y `server.js`.
- Pruebas: **78/78** superadas en 18 archivos; tres contratos nuevos cubren rutas/middleware, scope, argumentos externos y confirmación de presupuesto.
- Servidor aislado `127.0.0.1:8101`: router con 238 candidatos, cuatro recomendaciones, integraciones, seguridad read-only y capacidades respondieron correctamente.
- Workspace desconocido y confirmación inválida recibieron 400; una mutación con origen hostil recibió 403. No se ejecutaron evals, instalaciones, escrituras ni comprobación Docker remota.
- El puerto 8101 quedó detenido y libre tras la prueba.
- Tras cargar 0.1d en 8095, `/health`, `/codex-suite`, `/apps` y Lliria Properties respondieron 200; router y capacidades autenticados respondieron 200, la capacidad anónima 401 y el token del bridge no apareció en esas respuestas.

## Evidencia 0.1e

- Sintaxis: `node --check` sobre `lib/codex-thread-routes.js` y `server.js`.
- Pruebas: **81/81** superadas en 19 archivos; tres contratos nuevos cubren rutas/middleware, límites, selección de modelo, confirmaciones y ciclo de alta/baja del SSE.
- Las pruebas estructurales antiguas se ajustaron para inspeccionar el módulo propietario en vez de exigir implementación literal dentro de `server.js`; no se redujo su cobertura.
- Servidor aislado `127.0.0.1:8101`: sesión y listado de threads 200, runtime 200, mutación de turn desde origen hostil 403 y SSE 200 con `bridge/streamState` y `resetRequired`.
- El cliente SSE de verificación canceló explícitamente su reader; el servidor aislado y el PID temporal quedaron detenidos y el puerto 8101 libre.
- Tras cargar 0.1e en 8095, health, Codex Suite, `/apps` y Lliria Properties respondieron 200; threads/runtime autenticados y SSE respondieron 200, threads anónimos 401 y el token del bridge no apareció en las respuestas comprobadas.

## Evidencia 0.1f

- Sintaxis: `node --check` sobre `lib/codex-evidence-routes.js` y `server.js`.
- Pruebas: **84/84** superadas en 20 archivos; tres contratos nuevos cubren rutas/middleware, lecturas read-only/scope y decisión individual de checkpoint.
- Las pruebas estructurales de staging, contratos y Twin se ajustaron para inspeccionar el módulo propietario; no se redujeron los gates comprobados.
- Servidor aislado `127.0.0.1:8101`: Evidence, Twin, deployment, contrato y checkpoints respondieron 200; workspace desconocido 400 y mutaciones hostiles de snapshot/decisión 403.
- El token del bridge no apareció en las respuestas comprobadas; no se crearon snapshots, contratos, preflights ni checkpoints y no se ejecutó deploy. El puerto 8101 quedó detenido y libre.
- Tras cargar 0.1f en 8095, health, Codex Suite, `/apps` y Lliria Properties respondieron 200; Evidence, Twin, deployment y checkpoints autenticados respondieron 200, Evidence anónimo 401 y no apareció el token del bridge.

## Evidencia 0.1g

- Sintaxis: `node --check` sobre `lib/codex-suite-router.js`, `server.js` y la prueba de hardening modificada.
- Pruebas específicas: **8/8** superadas para composición/error boundary y hardening. Batería completa: **87/87** superadas en 21 archivos.
- Los contratos comprueban exactamente 75 rutas Codex, un error boundary, conservación de status/payload, logs sin query ni mensaje sensible y cierre idempotente de cada recurso una sola vez.
- Servidor aislado `127.0.0.1:8101`: health, Codex Suite, `/apps`, intercambio de sesión y workspaces autenticados respondieron 200; API anónima 401, origen hostil 403 y un error controlado 400.
- El token no apareció en las respuestas comprobadas y el marcador incluido en la query del error no apareció en los logs. El proceso temporal terminó y 8101 quedó libre.
- Limitación de la prueba de proceso: en Windows, `process.kill(pid, 'SIGTERM')` terminó el proceso y liberó el puerto sin ejecutar el manejador JavaScript observable. El cierre de recursos está demostrado por la prueba automatizada, no por esa señal de proceso.
- Tras reiniciar 8095 mediante `cursor-bridge-manager.ps1`, `/health`, `/codex-suite`, `/apps` y Lliria Properties respondieron 200; el catálogo autenticado devolvió 30 workspaces, la API anónima 401 y una mutación con origen hostil 403. El token no apareció en las respuestas comprobadas.
- Inventario al cierre: 27 módulos `lib/codex-*.js`; `server.js`, 83.851 bytes.

## Regla de finalización

Las fases 0.1–0.4, **1.1–1.4**, **2.1–2.4** quedan completadas; **3.3/3.4** avanzadas a parcial v2. **Lab Fabric + wave16** consume el `.16`. Persistencia versionada, hub Control PWA **v66**. Rutas Codex **141**. Siguiente: **1.5** o **3.1**. 0.5 Git aplazado por decisión.

## Orden de extracción frontend

1. **0.2a Frontend Core · completado**
   - Propietario compartido: `static/codex-suite/modules/core.js`.
   - Extrae configuración predeterminada, estado único, registro DOM, cliente API, traducción técnica y estado de conexión.
   - `app.js` pasa de script clásico a entrypoint ES. La PWA v29 precarga la raíz del grafo modular.
   - La auditoría CDP importa una superficie explícita del módulo sin publicar estado o funciones en `window` durante el uso normal.
2. **0.2b Ajustes, administración y diagnóstico · completado**
   - Propietario: `static/codex-suite/modules/settings.js`.
   - Extrae lectura/aplicación de preferencias, configuración segura de Codex/proveedores, escritura de credencial, borrado confirmado y diagnóstico visual.
   - El módulo registra sus listeners una sola vez mediante una frontera idempotente; `app.js` conserva únicamente importación, bootstrap y composición.
   - La PWA v30 precarga `core.js` y `settings.js`.
3. **0.2c Workspace, explorer e integraciones · completado**
   - Propietarios: `static/codex-suite/modules/workspace.js` y `static/codex-suite/modules/integrations.js`.
   - Workspace concentra catálogo/reset, AGENTS.md, explorer/preview/contexto, memoria y áreas; integraciones concentra análisis, MCP/plugins, complementos, deployment y seguridad read-only.
   - Las dependencias transversales se inyectan explícitamente y cada dominio registra sus listeners una sola vez. `app.js` conserva por ahora la composición y el cambio transversal de workspace para 0.2f.
   - La PWA v31 precarga los cuatro módulos existentes: core, settings, workspace e integraciones.
4. **0.2d Control, modelos y evidencia · completado**
   - Propietario: `static/codex-suite/modules/control.js`.
   - Extrae navegación de Control, router/evaluaciones de modelos, modo automático, presupuesto, certificación, Misiones, Evidence, contratos, Workspace Twin y preflight staging.
   - Las dependencias transversales se inyectan mediante `configureControlModule()` y los listeners se registran una sola vez. La PWA v32 precarga el nuevo módulo.
5. **0.2e Chat, runtime, revisión y eventos · completado**
   - Propietario: `static/codex-suite/modules/chat.js`.
   - Extrae threads, historial, render incremental, SSE/replay, watchdog y recuperación, aprobaciones, checkpoints, revisión individual y masiva, envío, steer y cancelación.
   - Las dependencias de Control se inyectan explícitamente; listeners y temporizador de vigilancia se activan desde una frontera idempotente. La PWA v33 precarga el módulo.
6. **0.2f Composición, bindings y error boundary visual · completado**
   - Propietario: `static/codex-suite/modules/composition.js`; `app.js` queda como entrypoint mínimo.
   - Configura todos los dominios una vez, registra bindings idempotentes y captura errores de arranque, `error` y `unhandledrejection` en un boundary accesible y recuperable.
   - La PWA v34 precarga el grafo completo, incluida la raíz de composición.

## Evidencia 0.2a

- Sintaxis: `node --check` sobre entrypoint, core, service worker y verificador CDP.
- Contratos nuevos: **4/4** para estado único, importación ES, frontera de sesión/secretos, PWA v29 y acceso de auditoría no global en producción.
- Batería completa: **91/91** pruebas superadas en 22 archivos.
- Chromium/CDP contra `127.0.0.1:8101`: escritorio 1440×900 y móvil 390×844 sin overflow horizontal, compositor visible, targets táctiles ≥48 px y todas las superficies auditadas con scroll.
- La auditoría verificó sesión, PWA, deduplicación optimista, aislamiento de threads, fechas, modos Ask/Plan/Autopilot, revisión por archivo, contratos, Twin, staging, explorer, complementos, catálogo MCP y seguridad.
- Diagnóstico visible: 22 correctas, 1 aviso y 0 errores. El aviso no se contabiliza como prueba superada.
- El primer intento de catálogo MCP devolvió 500 porque el servidor temporal se inició sin red; se repitió con red autorizada y la auditoría completa terminó correctamente. No se simularon datos del catálogo.
- Puertos temporales 8101, 9331 y 9332 detenidos y libres tras la verificación.
- Tamaño tras 0.2a: `app.js`, 164.855 bytes; `modules/core.js`, 9.492 bytes. El tamaño total no es el objetivo de esta extracción; el objetivo es separar propiedad sin duplicar estado.

## Evidencia 0.2b

- Sintaxis: `node --check` sobre core, settings, entrypoint, service worker y verificador CDP.
- Contratos específicos: **4/4** para propiedad del dominio, rutas/payloads, frontera de credenciales, listeners idempotentes y PWA v30.
- Batería completa: **95/95** pruebas superadas en 23 archivos.
- Chromium/CDP contra `127.0.0.1:8101`: ajustes y administración cargados, diagnóstico accionado desde la UI con 23 resultados, 22 correctos, 1 aviso y 0 errores.
- Escritorio 1440×900 y móvil 390×844 conservaron cero overflow horizontal, compositor visible, superficies con scroll y controles táctiles ≥48 px.
- No se guardó, cambió ni eliminó ninguna credencial o configuración durante la auditoría. El catálogo MCP se consultó con red real autorizada.
- Puertos temporales 8101, 9331 y 9332 detenidos y libres.
- Tamaño tras 0.2b: `app.js`, 156.261 bytes; `modules/core.js`, 9.492 bytes; `modules/settings.js`, 9.010 bytes.

## Evidencia 0.2c

- Sintaxis: `node --check` sobre workspace, integraciones, entrypoint y verificador CDP.
- Contratos específicos: **5/5** para propiedad única, inyección explícita, listeners idempotentes, confinamiento por workspace, confirmaciones exactas, credencial de deployment write-only y PWA v31.
- Pruebas específicas y de regresión frontend: **35/35**. Batería completa: **100/100** pruebas superadas en 24 archivos.
- El primer intento Chromium/CDP detectó una carrera real al activar el service worker v31: la recarga por `controllerchange` interrumpió un sondeo de `Runtime.evaluate`. El verificador ahora reintenta exclusivamente los errores transitorios de navegación y mantiene visibles los errores reales; la segunda ejecución terminó correctamente.
- Chromium/CDP contra `127.0.0.1:8101`: escritorio 1440×900 y móvil 390×844 sin overflow horizontal, compositor visible, paneles con scroll y controles táctiles ≥48 px.
- Explorer verificado con 34 entradas, drag/contexto, preview y acción de adjuntar; complementos con seis recomendaciones y contraseña write-only; integración MCP con diez secciones en español; seguridad con ocho tarjetas read-only. La auditoría creó dos snapshots Twin redacted de metadatos como parte de su contrato histórico.
- Diagnóstico visible: 22 correctas, 1 aviso y 0 errores en 23 resultados. Capturas especializadas actualizadas bajo `storage/codex-suite-*.png`.
- Puertos temporales 8101, 9331 y 9332 detenidos y libres tras la verificación.
- Tamaño tras 0.2c: `app.js`, 122.314 bytes; `core.js`, 9.492; `settings.js`, 9.010; `workspace.js`, 11.584; `integrations.js`, 24.109 bytes.

## Evidencia 0.2d

- Sintaxis: `node --check` sobre control, entrypoint, service worker y verificador CDP.
- Contratos específicos: **5/5** para propietario único, inyección explícita, listeners idempotentes, scope por workspace, confirmaciones, ausencia de secretos y PWA v32.
- Batería completa: **105/105** pruebas superadas en 25 archivos.
- Chromium/CDP contra `127.0.0.1:8101`: escritorio 1440×900 y móvil 390×844 sin overflow horizontal, con compositor visible, paneles con scroll y targets táctiles ≥48 px.
- Modelos, Misiones, Contratos, Twin y Staging fueron recorridos desde la UI. Se comprobaron tres gates y la acción de criterio de Contratos; Staging mantuvo gates y bloqueo selectivo sin exponer entradas de comandos; Twin mostró snapshots redacted sin contenido de código.
- Diagnóstico visible: 22 correctas, 1 aviso y 0 errores. La auditoría histórica creó dos snapshots Twin adicionales de metadatos redacted; no se registró contenido de archivos.
- Capturas de escritorio, móvil y superficies especializadas actualizadas bajo `storage/codex-suite-*.png`.
- El servidor temporal fue detenido y los puertos 8101, 9331 y 9332 quedaron libres tras la verificación.
- Tamaño tras 0.2d: `app.js`, 82.027 bytes; `control.js`, 43.171 bytes. La reducción corresponde a traslado de propiedad, no a eliminación de capacidades.

## Evidencia 0.2e

- Sintaxis: `node --check` sobre chat, entrypoint y service worker.
- Contratos específicos: **5/5** para propiedad única, dependencias/listeners idempotentes, replay SSE, watchdog/recuperación, checkpoints, aprobaciones, decisiones por archivo y PWA v33.
- Batería completa: **110/110** pruebas superadas en 26 archivos.
- Chromium/CDP contra `127.0.0.1:8101`: escritorio 1440×900 y móvil 390×844 sin overflow horizontal, compositor visible y controles táctiles ≥48 px.
- Se verificaron deduplicación optimista, aislamiento de eventos de otros threads, timestamps, Ask/Plan/Autopilot, revisión con dos archivos y cuatro acciones individuales, tres acciones masivas, contratos y staging selectivo.
- Diagnóstico visible: 22 correctas, 1 aviso y 0 errores. La auditoría creó dos snapshots Twin adicionales de metadatos redacted; no incluyeron contenido de código.
- El servidor temporal fue detenido y los puertos 8101, 9331 y 9332 quedaron libres.
- Tamaño tras 0.2e: `app.js`, 39.876 bytes; `chat.js`, 43.316 bytes. La lógica extraída conserva contratos y reduce el entrypoint sin introducir un framework.

## Evidencia 0.2f

- Sintaxis: `node --check` sobre entrypoint, composición, core, service worker y verificador CDP.
- Contratos específicos: **5/5** para entrypoint mínimo, composición única, bindings idempotentes, boundary accesible/redactado, lifecycle PWA/viewport y PWA v34.
- Batería completa: **115/115** pruebas superadas en 27 archivos.
- La primera auditoría CDP detectó que los cinco IDs del boundary no estaban registrados en `core.js`; el fallo impedía el bootstrap. Se corrigió el registro DOM, se añadió cobertura y se repitieron todas las pruebas antes de auditar de nuevo.
- Chromium/CDP contra `127.0.0.1:8101`: escritorio 1440×900 y móvil 390×844 sin overflow. El boundary fue visible, quedó dentro del viewport, mantuvo `role=alert`, `aria-live=assertive`, acción de recarga, redacción y targets móviles ≥48 px.
- El resto de superficies 0.2a–0.2e siguió operativo; diagnóstico: 22 correctas, 1 aviso y 0 errores. La auditoría creó dos snapshots Twin de metadatos redacted.
- Capturas nuevas: `storage/codex-suite-error-desktop.png` y `storage/codex-suite-error-mobile.png`.
- El servidor temporal fue detenido y los puertos 8101, 9331 y 9332 quedaron libres.
- Tamaño final: `app.js`, 281 bytes; `composition.js`, 41.609 bytes; `style.css`, 56.282 bytes.