Codex report

[FiveTechSoft]

  1 +# Informe de mejoras — FiveTechSoft/peng-mimo
  2 +
  3 +## Ficha de revisión
  4 +
  5 +- Repositorio analizado: <https://github.com/FiveTechSoft/peng-mimo>
  6 +- Rama: `peng`
  7 +- Commit revisado: [`1482e26fb9f19ef676575368228c54a918941a18`](https://github.com/FiveTechSoft/peng-mimo/commit/1482e26fb9f19ef676575368228c54a918941a18)
  8 +- Fecha: 11 de julio de 2026
  9 +- Alcance: motor C, carga y conversión de modelos, tests, CLI, API, web, documentación, distribución, seguridad práctica y rendimiento.
 10 +- Naturaleza: revisión técnica puntual; no es auditoría formal ni certificación de seguridad.
 11 +- Cambios en el repositorio analizado: ninguno.
 12 +
 13 +## Resumen ejecutivo
 14 +
 15 +`peng-mimo` demuestra una idea valiosa: ejecutar MiMo-V2.5 311B en hardware de consumo mediante streaming de expertos desde NVMe. El trabajo forense sobre arquitectura, layout QKV, tokenizer, cuantización y límites de I/O es fuerte. El moto
     r `mimo` compila y los tests C básicos pasan.
 16 +
 17 +El proyecto todavía debe presentarse como experimental. Bloqueos principales antes de recomendarlo ampliamente:
 18 +
 19 +1. Endurecer carga de modelos no confiables y corregir desbordamiento confirmado en plantilla de chat.
 20 +2. Convertir validación token-exact en gate reproducible de CI para `mimo`.
 21 +3. Hacer que build, setup, API y web ejecuten Peng/MiMo, no GLM/Colibri.
 22 +4. Hacer atómica y versionada conversión de 152 GB.
 23 +5. Unificar comandos, variables, defaults y documentación.
 24 +
 25 +## Severidad
 26 +
 27 +- **P0 — bloqueante:** riesgo de corrupción de memoria, pérdida de integridad del artefacto o flujo principal incorrecto.
 28 +- **P1 — alta:** afecta fiabilidad, reproducibilidad, RAM, seguridad de despliegue o experiencia principal.
 29 +- **P2 — media:** mejora calidad, mantenimiento, documentación o compatibilidad.
 30 +- **P3 — baja/condicional:** optimizar solo con evidencia o durante cambios cercanos.
 31 +
 32 +## Fortalezas que conviene conservar
 33 +
 34 +- Motor CPU pequeño, directo y sin framework de runtime pesado.
 35 +- Método oracle-first y comparación token-exact.
 36 +- Documentación técnica honesta sobre NVMe, RAM, caché y límites físicos.
 37 +- Modelo convertido ya publicado; evita conversión inicial de 316 GB.
 38 +- Validaciones de dimensiones del config MiMo.
 39 +- Cola FIFO acotada, límites de cuerpo HTTP y CORS local restrictivo por defecto.
 40 +- Hash de nombres de tensores y lectura `pread_full()` para tensores de más de 2 GB.
 41 +- Tests existentes para primitivas C, converter, scheduler/API y SSE.
 42 +- `package-lock.json`, TypeScript estricto y plantilla de benchmarks reproducibles.
 43 +
 44 +---
 45 +
 46 +## Hallazgos detallados
 47 +
 48 +### F-01 — P0 — Loader de modelos no valida completamente archivos no confiables
 49 +
 50 +**Evidencia**
 51 +
 52 +- [`st_init()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/st.h#L121-L147) confía en tamaño de header, JSON, shapes, offsets y multiplicaciones sin contrastarlos con tamaño real del archivo.
 53 +- [`st_read_f32()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/st.h#L197-L218) copia `t->nbytes` a buffer cuya capacidad no recibe.
 54 +- [`qt_from_disk()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L716-L733) reserva según geometría esperada, pero lee metadatos del shard sin exigir igualdad de tamaño y dtype.
 55 +- `json.h` acepta JSON parcial, no devuelve errores estructurados y trunca strings en buffer temporal de 64 KiB.
 56 +- Tokens procedentes de tokenizer/ref deberían validarse contra `vocab_size` antes de indexar embeddings.
 57 +
 58 +**Impacto**
 59 +
 60 +Shard, config o tokenizer corrupto/manipulado puede causar OOM, overflow aritmético, lectura fuera de archivo, escritura fuera de buffer o crash. Superficie real: usuario descarga un contenedor externo de aproximadamente 152 GB.
 61 +
 62 +**Mejora**
 63 +
 64 +- Limitar tamaño de header.
 65 +- Validar `hlen <= file_size - 8`.
 66 +- Validar JSON completo, tipos, shapes, offsets ordenados, ausencia de duplicados y aritmética overflow-safe.
 67 +- Exigir `nbytes == numel * dtype_size`.
 68 +- Pasar capacidad esperada a `st_read_f32`, `st_read_raw` y slices.
 69 +- Rechazar IDs fuera de vocabulario.
 70 +- Añadir corpus malformado y fuzz básico bajo ASan/UBSan.
 71 +
 72 +**Criterio de aceptación**
 73 +
 74 +Alterar header, shape, dtype, offset, `.qs` o token ID produce error limpio; cero crash/overflow bajo sanitizers; modelo válido conserva tokens.
 75 +
 76 +### F-02 — P0 — Desbordamiento confirmado en builder de plantilla de chat
 77 +
 78 +**Evidencia**
 79 +
 80 +- [`mimo_turn_render()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L1870-L1879) acumula retorno de `snprintf()`. Si hay truncado, retorno refleja longitud necesaria y `bl` puede superar
      `cap`.
 81 +- Caller tokeniza usando `bl` como longitud real en [`run_serve()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L2027-L2035).
 82 +- `TEMPLATE_DUMP` hace `fwrite(..., bl)` sobre buffer fijo de 64 KiB en [`main()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L2354-L2364).
 83 +- Entrada llega por `getline()` sin límite previo.
 84 +
 85 +**Verificación**
 86 +
 87 +Compilación con AddressSanitizer + mensaje de 70.000 caracteres reprodujo `heap-buffer-overflow`, lectura 4.600 bytes después del buffer de 65.536 bytes; proceso terminó con código 134.
 88 +
 89 +**Mejora**
 90 +
 91 +Builder dinámico: calcular tamaño, reservar una vez y comprobar cada escritura. Alternativa mínima: retorno `-ENOSPC`, límite explícito de prompt y rechazo antes de tokenizar.
 92 +
 93 +**Criterio de aceptación**
 94 +
 95 +Tests `cap-1`, `cap`, `cap+1`, usuario largo y `SYSTEM` largo; ASan limpio; error controlado en entrada excesiva.
 96 +
 97 +### F-03 — P0 — Exactitud central contradictoria y sin gate reproducible
 98 +
 99 +**Evidencia**
100 +
101 +- [`README.md`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/README.md#L123-L135) publica 32/32 teacher-forcing y 20/20 greedy.
102 +- [`findings.md`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/findings.md#L344-L364) registra 31/32 y 18/20 incluso con int8 después de MTP/v2.
103 +- Un commit posterior afirma de nuevo gates verdes, pero HEAD no permite reproducirlos desde clon limpio.
104 +- [`check`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/Makefile#L91-L95) compila `glm`, no `mimo`.
105 +- Oracle, tokenizer y binarios necesarios están ignorados por Git.
106 +
107 +**Impacto**
108 +
109 +No puede determinarse de forma independiente si HEAD mantiene promesa token-exact. Una regresión central puede aparecer verde.
110 +
111 +**Mejora**
112 +
113 +- Bisectar o cerrar explícitamente divergencia documentada.
114 +- Crear `check_mimo_exact` con oracle full-feature: SWA, sink, value scale, MTP y eviction.
115 +- Separar perfil `exact` de perfil `fast`.
116 +- Gate de identidad para PILOT on/off y DRAFT cuando se prometa lossless.
117 +
118 +**Criterio de aceptación**
119 +
120 +F32/int8 = 32/32 TF y 20/20 greedy; CI falla con una sola divergencia; resultados README corresponden al SHA actual.
121 +
122 +### F-04 — P0 — Superficie pública Peng sigue ejecutando GLM/Colibri
123 +
124 +**Evidencia**
125 +
126 +- API renderiza plantilla GLM `[gMASK]<sop>` en [`render_chat()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/openai_server.py#L154-L178).
127 +- API usa por defecto binario `glm` y modelo `glm-5.2-colibri` en [`serve()` y CLI](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/openai_server.py#L537-L583).
128 +- [`c/coli`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/coli#L1-L27) es CLI GLM.
129 +- [`c/setup.sh`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/setup.sh#L23-L45) compila GLM y describe modelo de 372 GB.
130 +- [`Makefile`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/Makefile) y target `all` construyen GLM.
131 +- Web conserva modelo GLM y branding Colibri en [`App.tsx`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/web/src/App.tsx#L29-L48).
132 +- Planner usa campos MLA/GLM, no geometría KV híbrida MiMo.
133 +
134 +**Impacto**
135 +
136 +`--engine mimo` con API envía prompt GLM inválido. Build, setup, planner y UI no representan producto anunciado.
137 +
138 +**Mejora KISS**
139 +
140 +Hacer Peng MiMo-only en superficie soportada. Mover/marcar legado upstream. Solo crear perfiles multi-modelo si existe necesidad real.
141 +
142 +**Criterio de aceptación**
143 +
144 +Clon limpio: `make`, setup, API y web usan `mimo`; plantilla mono/multiturno coincide con tokenizer oficial; ningún flujo Peng usa tokens GLM.
145 +
146 +### F-05 — P0 — Conversión reanudable puede aceptar salida truncada
147 +
148 +**Evidencia**
149 +
150 +- Converter omite shard si `outp` existe y escribe `save_file()` directamente al destino en [`convert_fp8_to_int4.py`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/tools/convert_fp8_to_int4.py#L6
     35-L648).
151 +- Log técnico del propio repo reconoce que corte durante guardado deja shard truncado que resume puede saltar.
152 +
153 +**Impacto**
154 +
155 +Conversión de horas puede terminar con contenedor incompleto aceptado como válido.
156 +
157 +**Mejora**
158 +
159 +Escribir `.tmp`, cerrar/sincronizar, validar safetensors y `os.replace()`. Mantener manifest de shards completos, inventario de tensores y checksums.
160 +
161 +**Criterio de aceptación**
162 +
163 +Matar proceso durante escritura y relanzar regenera shard automáticamente; manifest final valida inventario completo.
164 +
165 +### F-06 — P1 — Revisiones externas mutables pueden mezclarse durante conversión
166 +
167 +**Evidencia**
168 +
169 +- README descarga ramas mutables sin `--revision`.
170 +- Converter usa URLs `/resolve/main` para index y metadatos en [`convert_fp8_to_int4.py`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/tools/convert_fp8_to_int4.py#L565-L589).
171 +- Conversión dura horas; upstream puede cambiar entre descarga de config, index y shards.
172 +- Revisiones observadas en auditoría: base `63651580ca774f8504f676040460aed3e1244ac1`; contenedor `445e9ac47466080a15e33aa4b850f0fee6587c42`.
173 +
174 +**Mejora**
175 +
176 +Resolver SHA al inicio, persistirlo y usarlo para todas las peticiones. Añadir `--revision`. Registrar source SHA, converter SHA y hashes en manifest.
177 +
178 +**Criterio de aceptación**
179 +
180 +Una conversión nunca mezcla revisiones; misma revisión produce mismo inventario y metadatos.
181 +
182 +### F-07 — P1 — `make check` no es limpio, reproducible ni centrado en MiMo
183 +
184 +**Evidencia**
185 +
186 +- [`CONTRIBUTING.md`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/CONTRIBUTING.md#L5-L17) promete tests de librería estándar.
187 +- Tests importan `transformers`, `numpy`, `torch` y `safetensors`; no existe manifest Python.
188 +- `test_mimo_template.py` puede omitirse porque `check` no construye `mimo`.
189 +- Ejecución auditada: tests C 3/3 verdes; discovery Python falló por `ModuleNotFoundError: transformers`. Fallos de socket adicionales fueron limitación del sandbox, no se atribuyen al repo.
190 +- GitHub tiene cero workflows.
191 +
192 +**Mejora**
193 +
194 +- `check-core`: build `mimo`, C, Python realmente stdlib.
195 +- `check-full`: dependencias fijadas, tokenizer, template, converter y oracle.
196 +- CI Linux gcc/clang, web, ASan/UBSan; job oracle separado/cacheado.
197 +
198 +**Criterio de aceptación**
199 +
200 +Clon limpio pasa core sin deps externas; full pasa tras instalación documentada; skips son deliberados y visibles.
201 +
202 +### F-08 — P1 — Cancelar en web no cancela generación activa
203 +
204 +**Evidencia**
205 +
206 +- Web aborta `fetch` en [`App.tsx`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/web/src/App.tsx#L81-L102).
207 +- API solo deja de escribir al cliente; [`Engine.generate()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/openai_server.py#L249-L280) sigue leyendo hasta `END`.
208 +- Scheduler queda ocupado. A 0,3 tok/s, 512 tokens pueden ocupar unos 28 minutos después de pulsar Stop.
209 +
210 +**Mejora MVP**
211 +
212 +Al desconectar, terminar y reiniciar proceso; carga publicada ronda 20 s. Fase posterior: cancelación cooperativa a límite de token preservando estado coherente.
213 +
214 +**Criterio de aceptación**
215 +
216 +Abort libera scheduler rápidamente y siguiente petición progresa; test desconecta a mitad y verifica que no se consumen todos los tokens.
217 +
218 +### F-09 — P1 — Health y proceso hijo no reflejan estado real
219 +
220 +**Evidencia**
221 +
222 +- [`/health`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/openai_server.py#L368-L381) devuelve `ok` con métricas de scheduler sin comprobar `process.poll()`.
223 +- Motor muerto se descubre al generar; no hay restart/backoff acotado.
224 +- `chat_peng.py` descarta stderr, ocultando causa de fallo de carga.
225 +
226 +**Mejora**
227 +
228 +Separar liveness/readiness, 503 si motor no listo, conservar stderr reciente y restart único/acotado.
229 +
230 +**Criterio de aceptación**
231 +
232 +Matar child cambia readiness; petición recibe 503 claro o motor reinicia una vez sin bucle.
233 +
234 +### F-10 — P1 — API puede exponerse sin autenticación fuerte por defecto
235 +
236 +**Evidencia**
237 +
238 +- [`serve()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/openai_server.py#L537-L552) permite bind no local sin clave y solo advierte.
239 +- Transporte es HTTP plano; `http.server` no es servidor público endurecido.
240 +- Web persiste API key en `localStorage` en [`App.tsx`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/web/src/App.tsx#L45-L48).
241 +
242 +**Mejora**
243 +
244 +- Rechazar host no loopback sin clave salvo `--allow-insecure` explícito.
245 +- Recomendar reverse proxy TLS y timeouts de socket.
246 +- Secretos por entorno/archivo, no argumento visible en `ps`.
247 +- Key solo en memoria por defecto; recordar de forma explícita como máximo en `sessionStorage`; CSP en build publicado.
248 +
249 +**Criterio de aceptación**
250 +
251 +Bind externo sin protección falla; auth/CORS tienen prueba; recarga normal no conserva secreto.
252 +
253 +### F-11 — P1 — KV de capas SWA reserva contexto completo
254 +
255 +**Evidencia**
256 +
257 +- [`kv_alloc()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L1462-L1472) reserva `max_t` para todas las capas.
258 +- Atención indexa KV por posición absoluta en [`attention()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L1175-L1193).
259 +- MiMo tiene 39 capas SWA con ventana 128; diseño reconoce ring como optimización diferida.
260 +
261 +**Impacto calculado**
262 +
263 +CTX=4096: capas SWA reservan aproximadamente 1,636 GB frente a 0,051 GB con ring; ahorro aproximado 1,58 GB, algo más con MTP. CTX=32k: ahorro cercano a 13 GB.
264 +
265 +**Mejora**
266 +
267 +Ring `physical = logical % window` solo para SWA/MTP. Full attention permanece lineal; RoPE conserva posición lógica.
268 +
269 +**Criterio de aceptación**
270 +
271 +Dos o más wraps mantienen identidad con implementación lineal; RSS baja alrededor de 1,5 GB a CTX=4096.
272 +
273 +### F-12 — P1 — Variables de runtime y conceptos de sampling se contradicen
274 +
275 +**Evidencia**
276 +
277 +- `NOPACK`, `DROP`, `LOOKA`, `PILOT` y algunos modos usan mera presencia; `PILOT=0` activa en [`mimo.c`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L2366-L2391).
278 +- README documenta `NUC`; código lee `NUCLEUS`.
279 +- `TOPP` poda expertos; OpenAI `top_p` y `NUCLEUS` muestrean vocabulario. Nombre induce errores.
280 +- Wrapper usa `TOPP=0.6`, README cita `TOPP=0.7`; C directo usa 0.
281 +
282 +**Mejora**
283 +
284 +Helpers tipados `env_bool/int/float`, rangos y dump de configuración efectiva. Renombrar a `EXPERT_TOP_P` y `TOKEN_TOP_P`, manteniendo aliases con warning. Perfiles explícitos `exact` y `fast`.
285 +
286 +**Criterio de aceptación**
287 +
288 +Tests para ausente/0/1/inválido; `PILOT=0` queda off; docs y runtime coinciden 1:1.
289 +
290 +### F-13 — P1 — Quickstart y comandos de chat no son copiables
291 +
292 +**Evidencia**
293 +
294 +- Quickstart hace `cd peng-mimo/c`, luego indica `python3 c/chat_peng.py`; desde ese cwd busca `c/c/chat_peng.py`.
295 +- README documenta `/more` y `/exit`; wrapper implementa `/mas` y `/salir`.
296 +- `chat_peng.py` comprueba `len(stat) >= 4` y después accede `stat[4]`.
297 +- stderr del motor se descarta.
298 +
299 +**Mejora**
300 +
301 +Un solo quickstart desde raíz; aliases ingleses y españoles; validar status con cinco campos; mostrar error de carga.
302 +
303 +**Criterio de aceptación**
304 +
305 +Todos comandos copiados desde README funcionan; `/more`, `/exit`, `/mas`, `/salir` tienen conducta definida; protocolo malformado no causa excepción secundaria.
306 +
307 +### F-14 — P1 — Resource planner calcula geometría GLM para modelo MiMo
308 +
309 +**Evidencia**
310 +
311 +`resource_plan.py` usa campos `kv_lora_rank`, `qk_rope_head_dim` y `qk_nope_head_dim`; MiMo usa GQA híbrido full/SWA. Runtime C calcula geometría distinta.
312 +
313 +**Impacto**
314 +
315 +Plan puede subestimar KV, elevar cap y provocar OOM o expectativas falsas.
316 +
317 +**Mejora**
318 +
319 +Detectar `model_type`, fórmula MiMo probada contra estimación C, o retirar planner del flujo Peng hasta soportarlo.
320 +
321 +**Criterio de aceptación**
322 +
323 +Fixtures GLM/MiMo coinciden con runtime dentro de margen definido; arquitectura desconocida falla explícitamente.
324 +
325 +### F-15 — P1 — Target CUDA MiMo no enlaza backend
326 +
327 +**Evidencia**
328 +
329 +- `CUDA=1` define `CUDA_OBJ=backend_cuda.o`.
330 +- Target `glm` depende y enlaza objeto; target [`mimo`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/Makefile#L50-L56) no.
331 +- `mimo.c` sí llama funciones CUDA bajo `COLI_CUDA`.
332 +
333 +**Mejora**
334 +
335 +Enlazar `$(CUDA_OBJ)` y añadir dependencia de header, o retirar/ocultar claim MiMo CUDA hasta validarlo.
336 +
337 +**Criterio de aceptación**
338 +
339 +Linux CUDA `make mimo CUDA=1` enlaza y fixture pasa; CPU queda idéntico.
340 +
341 +### F-16 — P1 — Sin contrato de release, formato ni licencia inequívoca
342 +
343 +**Evidencia**
344 +
345 +- Cero tags/releases; rama `peng` sin workflows.
346 +- Contenedor externo ya distribuye 16 shards, pero benchmark local habla de 17.
347 +- No hay `format_version`/manifest reconocido por motor.
348 +- Config convertido conserva marcadores FP8/custom code que pueden confundir loaders estándar.
349 +- Motor/repo declara Apache-2.0, modelo base MiMo MIT y contenedor convertido Apache-2.0. README dice vagamente “their own license”. No se concluye incompatibilidad legal; falta claridad.
350 +
351 +**Mejora**
352 +
353 +Release experimental `v0.1.0`; manifest con esquema, commits, revisión base, cuantización, tamaños, shards/checksums y compatibilidad. Separar licencia de motor, pesos base y artefacto, preservando avisos MIT.
354 +
355 +**Criterio de aceptación**
356 +
357 +Tag inmutable; loader rechaza formato incompatible; README y model card cuentan misma historia; 16/17 shards y GB/GiB quedan explicados.
358 +
359 +### F-17 — P1 — Dependencias de desarrollo no están fijadas
360 +
361 +**Evidencia**
362 +
363 +- No existe `requirements-dev.txt`, `pyproject.toml` o constraints.
364 +- README usa `pip install -U`.
365 +- Hallazgo interno indica que reference code solo funciona con Transformers 5.0–5.1.
366 +- `package.json` no declara `engines`.
367 +
368 +**Mejora**
369 +
370 +Constraints mínimos: Transformers 5.1.0 para oracle, grupos separados converter/tests, Node LTS declarado mediante `engines` y `.nvmrc`.
371 +
372 +**Criterio de aceptación**
373 +
374 +Entornos limpios reproducen core/full/web con versiones documentadas.
375 +
376 +### F-18 — P1 — Estado documental, alcance y estrategia upstream son contradictorios
377 +
378 +**Evidencia**
379 +
380 +- README marca Phase 6 completa y luego mantiene “Pending for Phase 6” sobre plantilla ya implementada.
381 +- Diseño inicial deja MTP fuera; README actual lo declara integrado.
382 +- Plan histórico conserva casillas sin completar y rutas `C:\colibri`/`~/colibri`.
383 +- `docs/` contiene upstream README, plan y spec, pero no índice, troubleshooting ni desarrollo Peng.
384 +- Issue #1 pregunta por continuidad MiMo y estrategia upstream; README no lo resuelve claramente.
385 +- Respuesta pública menciona shared expert aunque README/código indican que MiMo no tiene shared expert, y llama “speculative decoding” a PILOT/LOOKA, que son prefetch; MTP es speculative decoding.
386 +
387 +**Mejora**
388 +
389 +Una fuente de estado vivo: `Current status`, `Known limitations`, `Next milestones`. Marcar plan/spec como históricos. Bloque “Project status and upstream strategy”. Corregir aclaraciones públicas.
390 +
391 +**Criterio de aceptación**
392 +
393 +Cero contradicciones README/findings; documentos históricos muestran fecha/commit; soporte y estrategia quedan explícitos.
394 +
395 +### F-19 — P2 — Calidad int4 y benchmarks no validan todavía experiencia real
396 +
397 +**Evidencia**
398 +
399 +- Token-exact del oracle valida implementación, no degradación de calidad del modelo real cuantizado.
400 +- Claim “frontier quality” se apoya en smoke test simple.
401 +- Resultados de rendimiento no siempre incluyen SHA, revisión del contenedor, repeticiones y mediana; defaults citados ya cambiaron.
402 +
403 +**Mejora MVP**
404 +
405 +Suite de 20–50 prompts EN/ES: hechos, código, Unicode, multiturno, contexto >128, formatos y negativa segura. Publicar comando, SHA, modelo, cold/warm, repeticiones y mediana.
406 +
407 +**Criterio de aceptación**
408 +
409 +Cada release publica resultado reproducible y regresiones conocidas. No afirmar calidad global sin datos.
410 +
411 +### F-20 — P2 — Frontend: parser, accesibilidad y feedback incompletos
412 +
413 +**Evidencia**
414 +
415 +- `JSON.parse` de SSE sin tolerancia; frame final sin separador puede quedar sin consumir.
416 +- Solo dos tests SSE; faltan UTF-8 partido, `[DONE]`, error, abort y EOF.
417 +- Probe sin timeout; cola/uso/latencia enviados por API se ignoran.
418 +- Textarea sin label accesible, toggle sin `aria-pressed`, errores/estado sin live regions, foco visible incompleto y sin `prefers-reduced-motion`.
419 +- Varios textos pequeños tienen contraste calculado inferior a 4,5:1.
420 +
421 +**Mejora**
422 +
423 +Contrato API/web sin modelo grande; parser robusto; timeout; métricas básicas; labels/ARIA/foco/contraste AA/reduced motion.
424 +
425 +**Criterio de aceptación**
426 +
427 +Tests cubren límites SSE y abort; navegación completa con teclado; axe sin incidencias serious/critical.
428 +
429 +### F-21 — P2/P3 — Fiabilidad I/O, memoria y mantenimiento incremental
430 +
431 +**Evidencia**
432 +
433 +- `pread_full()` existe, pero [`expert_load()`](https://github.com/FiveTechSoft/peng-mimo/blob/1482e26fb9f19ef676575368228c54a918941a18/c/mimo.c#L979-L1005) usa `pread()` único para weights/scales; short read o EINTR termina proceso.
434 +- Parser JSON deja árbol/nodos/keys temporalmente fugados; `st.h` lo reconoce.
435 +- `mimo.c` y `glm.c` rondan 2.500 líneas y comparten gran parte de quant, sampling, I/O, caché y protocolo.
436 +- Attention/MoE hacen múltiples alloc/free por capa. Optimización solo debe hacerse si profiling atribuye coste real.
437 +- Makefile suprime `-Wmisleading-indentation` y no fija estándar C.
438 +- `make check` deja `c/tests/test_tier` sin ignorar.
439 +- Topics GitHub y homepage están vacíos; sin receta operativa Peng/systemd.
440 +
441 +**Mejora**
442 +
443 +- Helper único `pread_exact` con EINTR y contexto.
444 +- Destructor JSON.
445 +- Extraer solo primitivas byte-idénticas cuando se toquen por segunda vez; no crear framework.
446 +- Workspace reusable únicamente si profiling muestra >5%.
447 +- `-std=gnu11/gnu17`, sanitizer target y formateo incremental.
448 +- Build artifacts fuera del árbol o ignorados.
449 +- Ejemplo systemd simple, loopback por defecto, env 0600 y reverse proxy opcional.
450 +
451 +**Criterio de aceptación**
452 +
453 +Fault injection de short reads; LSan limpio; corrección común se cambia una vez; optimización medida >=5%; `make check && git status --porcelain` limpio.
454 +
455 +---
456 +
457 +## Verificación ejecutada
458 +
459 +- `git ls-remote`: rama por defecto `peng`, commit auditado disponible.
460 +- `make -C c mimo`: compila correctamente sin warnings en host auditado.
461 +- Tests C `json`, `safetensors primitive`, `tier`: 3/3 pasan.
462 +- `make check`: no termina en clon limpio por dependencia `transformers` no declarada; fallos de bind HTTP observados pertenecen al sandbox.
463 +- AddressSanitizer: desbordamiento de plantilla reproducido con 70.000 caracteres.
464 +- Web, según revisión paralela: `npm test` y `npm run build` pasan; `npm audit` devuelve 0 vulnerabilidades conocidas.
465 +- GitHub: 0 workflows, 0 tags, 0 releases.
466 +
467 +## Límites de la revisión
468 +
469 +- No se descargó ni ejecutó el contenedor completo de 152 GB.
470 +- No se regeneró oracle full-feature por faltar entorno/dependencias fijadas.
471 +- No se probó CUDA por falta de host CUDA.
472 +- No se realizó pentest remoto ni fuzzing exhaustivo.
473 +- Cifras de RAM del ring SWA son cálculo sobre geometría documentada, no medición de RSS en modelo real.

└ roadmap.md (+218 -0)
1 +# Roadmap propuesto — FiveTechSoft/peng-mimo
2 +
3 +## Estado
4 +
5 +- [x] Revisión de repositorio, código, tests, docs, API, web y distribución.
6 +- [x] Hallazgos consolidados en findings.md.
7 +- [ ] Implementación en FiveTechSoft/peng-mimo: no iniciada; requiere autorización y checkout persistente del repositorio objetivo.
8 +
9 +Este roadmap prioriza motor Peng/MiMo funcional y verificable. No incluye multimodal, nuevas arquitecturas ni automatización innecesaria.
10 +
11 +## Principios
12 +
13 +1. Seguridad e integridad antes de optimización.
14 +2. Un solo flujo Peng soportado.
15 +3. Gate pequeño antes del modelo de 152 GB.
16 +4. Perfiles exact y fast separados.
17 +5. Cambios incrementales, medidos y reversibles.
18 +
19 +## Orden de ejecución
20 +
21 +### Fase 0 — Bloqueantes de seguridad e integridad
22 +
23 +Objetivo: modelo externo y entradas largas no pueden corromper memoria; conversión no acepta artefactos parciales.
24 +
25 +- [ ] R0.1 — Endurecer loader safetensors/JSON (F-01)
26 + - Validar header, offsets, shapes, dtype, tamaños, duplicados y overflow.
27 + - Pasar capacidad a APIs de lectura.
28 + - Validar token IDs.
29 + - Añadir fixtures corruptos y ASan/UBSan.
30 +- [ ] R0.2 — Corregir builder de plantilla (F-02)
31 + - Builder dinámico o error ENOSPC comprobado.
32 + - Límite de prompt explícito.
33 + - Tests en límites y SYSTEM largo.
34 +- [ ] R0.3 — Escritura atómica del converter (F-05)
35 + - .tmp + validación + os.replace().
36 + - Manifest de shards completados.
37 + - Test kill/restart.
38 +- [ ] R0.4 — Fijar revisión durante conversión (F-06)
39 + - Resolver SHA al inicio.
40 + - --revision aplicado a index, metadata y shards.
41 + - Persistir provenance.
42 +
43 +Gate de salida
44 +
45 +- ASan/UBSan verdes.
46 +- Corpus malformado falla limpiamente.
47 +- Conversión interrumpida se repara sola.
48 +- Modelo válido conserva resultados previos.
49 +
50 +### Fase 1 — Hacer Peng verificable desde clon limpio
51 +
52 +Objetivo: un comando demuestra que motor MiMo actual compila y mantiene exactitud.
53 +
54 +- [ ] R1.1 — Resolver estado token-exact (F-03)
55 + - Reproducir/bisectar 31/32 y 18/20 documentado.
56 + - Actualizar resultado canónico sin ocultar divergencias.
57 +- [ ] R1.2 — Crear check-core y check-full (F-07, F-17)
58 + - Core sin paquetes Python externos.
59 + - Full con constraints fijados, Transformers 5.1.0 y assets versionados.
60 +- [ ] R1.3 — Añadir fixture/oracle MiMo pequeño (F-03, F-07)
61 + - Tokenizer, plantilla, converter, SWA boundary, eviction, TF y greedy.
62 + - Identidad PILOT y DRAFT donde se promete lossless.
63 +- [ ] R1.4 — CI mínima (F-07)
64 + - Linux gcc/clang: mimo, C, Python core.
65 + - Integration/oracle cacheado.
66 + - Web test/build.
67 + - Sanitizers.
68 +- [ ] R1.5 — Limpiar árbol tras tests (F-21)
69 + - Build artifacts fuera del source o correctamente ignorados.
70 +
71 +Gate de salida
72 +
73 +- make check-core verde en clon limpio.
74 +- make check-full verde con instalación documentada.
75 +- CI falla ante una divergencia de token.
76 +- git status --porcelain vacío después de checks.
77 +
78 +### Fase 2 — Un solo producto Peng/MiMo
79 +
80 +Objetivo: ningún comando público ejecuta GLM por accidente.
81 +
82 +- [ ] R2.1 — Decidir superficie (F-04)
83 + - Recomendado: Peng MiMo-only.
84 + - Mover o marcar claramente coli, GLM, scripts y web heredados.
85 +- [ ] R2.2 — Defaults de build/setup (F-04, F-13)
86 + - Root make construye mimo.
87 + - setup.sh y quickstart Peng.
88 +- [ ] R2.3 — Unificar wrapper y comandos (F-09, F-12, F-13)
89 + - Aliases /more//mas, /exit//salir.
90 + - Mostrar stderr y validar protocolo.
91 + - Runtime options tipadas.
92 +- [ ] R2.4 — Renombrar knobs ambiguos (F-12)
93 + - EXPERT_TOP_P y TOKEN_TOP_P.
94 + - Aliases temporales con warning.
95 + - Perfiles exact y fast.
96 +- [ ] R2.5 — Corregir planner MiMo o retirarlo del flujo (F-14)
97 +- [ ] R2.6 — Corregir enlace CUDA o retirar claim (F-15)
98 +
99 +Gate de salida
100 +
101 +- Quickstart copiado funciona desde raíz.
102 +- Búsqueda de defaults GLM solo devuelve código marcado como legado.
103 +- Config efectiva se imprime y coincide con documentación.
104 +- Planner no subestima KV MiMo.
105 +
106 +### Fase 3 — API/web Peng fiable
107 +
108 +Objetivo: exponer API solo si usa plantilla MiMo correcta y puede detener trabajo.
109 +
110 +- [ ] R3.1 — Plantilla API MiMo (F-04)
111 + - Compartir una sola implementación o golden oficial.
112 + - Tests mono/multiturno/thinking/system.
113 +- [ ] R3.2 — Cancelación real (F-08)
114 + - MVP: reinicio controlado del child.
115 + - Después: cancelación cooperativa a límite de token.
116 +- [ ] R3.3 — Liveness/readiness (F-09)
117 + - 503 con motor muerto/no listo.
118 + - Restart acotado y logs de child.
119 +- [ ] R3.4 — Seguridad de exposición (F-10)
120 + - Fail-closed fuera de loopback.
121 + - Timeouts, guía TLS, key fuera de localStorage.
122 +- [ ] R3.5 — Contrato web/API (F-20)
123 + - SSE UTF-8/chunks/EOF/error/abort.
124 + - Cola, uso y latencia visibles.
125 +- [ ] R3.6 — Accesibilidad básica (F-20)
126 + - Labels, ARIA live, foco, contraste AA y reduced motion.
127 +
128 +Gate de salida
129 +
130 +- /v1/models devuelve Peng/MiMo.
131 +- Prompt API coincide con template oficial.
132 +- Stop libera scheduler.
133 +- Bind externo inseguro falla.
134 +- Axe sin incidencias serious/critical.
135 +
136 +### Fase 4 — Recuperar RAM de SWA
137 +
138 +Objetivo: liberar memoria útil para caché de expertos.
139 +
140 +- [ ] R4.1 — Ring KV SWA/MTP (F-11)
141 + - Índice físico módulo ventana.
142 + - Posición lógica preservada para RoPE.
143 + - Full attention lineal.
144 +- [ ] R4.2 — Gates de wrap
145 + - Dos o más vueltas completas.
146 + - Comparación contra implementación lineal.
147 +- [ ] R4.3 — Medición real
148 + - RSS CTX 4096 y 32k.
149 + - Cap, hit-rate y tok/s cold/warm.
150 +
151 +Gate de salida
152 +
153 +- Identidad de salida.
154 +- Ahorro esperado cercano a 1,5 GB en CTX 4096.
155 +- Sin regresión de rendimiento medible.
156 +
157 +### Fase 5 — Release experimental reproducible
158 +
159 +Objetivo: relacionar código, modelo y claims mediante artefactos inmutables.
160 +
161 +- [ ] R5.1 — Manifest de formato (F-16)
162 + - peng_format_version.
163 + - SHA de motor/converter/base/container.
164 + - Bits, shapes, shard count, hashes y compatibilidad.
165 +- [ ] R5.2 — Licencias y NOTICE (F-16)
166 + - Motor Apache-2.0.
167 + - Pesos base MIT y revisión.
168 + - Artefacto convertido y atribuciones.
169 +- [ ] R5.3 — Tag v0.1.0-experimental (F-16)
170 +- [ ] R5.4 — Docs de estado vivo (F-18)
171 + - Estado, limitaciones, milestones y estrategia upstream.
172 + - Plan/spec históricos marcados.
173 +- [ ] R5.5 — Quickstart y troubleshooting (F-13, F-18)
174 + - WSL/ext4, espacio, RAM, descarga, checksum, errores comunes.
175 +
176 +Gate de salida
177 +
178 +- Tag y modelo inmutables.
179 +- Loader valida versión.
180 +- README/model card/licencias coinciden.
181 +- Benchmark identifica exactamente código y pesos.
182 +
183 +### Fase 6 — Calidad, operación y mejoras medidas
184 +
185 +Objetivo: probar valor real antes de ampliar arquitectura.
186 +
187 +- [ ] R6.1 — Suite pequeña de calidad (F-19)
188 + - 20–50 prompts EN/ES, multiturno, Unicode, contexto largo y formato.
189 +- [ ] R6.2 — Benchmark trazable (F-19)
190 + - SHA, modelo, comando, cold/warm, repeticiones y mediana.
191 +- [ ] R6.3 — Servicio operativo simple (F-21)
192 + - Ejemplo systemd, env 0600, loopback y reverse proxy opcional.
193 +- [ ] R6.4 — pread_exact y limpieza JSON (F-21)
194 +- [ ] R6.5 — Extraer primitivas compartidas solo al tocarlas (F-21)
195 + - Quant, sampling, runtime options o I/O; attention sigue específica.
196 +- [ ] R6.6 — Optimizar allocations solo con profiling (F-21)
197 + - Umbral: >5% de tiempo/fragmentación y mejora >=5%.
198 +
199 +## Fuera de alcance por ahora
200 +
201 +- Multimodal.
202 +- Soporte de más modelos.
203 +- Contexto nativo de un millón de tokens.
204 +- Orquestación distribuida/enterprise.
205 +- Dockerización de pesos de 152 GB.
206 +- Refactor completo del motor antes de estabilizar gates.
207 +
208 +## Secuencia mínima recomendada
209 +
210 +1. R0.1 loader seguro.
211 +2. R0.2 overflow de plantilla.
212 +3. R0.3–R0.4 converter atómico y fijado.
213 +4. R1.1–R1.4 exactitud reproducible + CI.
214 +5. R2.1–R2.4 superficie Peng única.
215 +6. R3 API/web solo después.
216 +7. R4 ring SWA.
217 +8. R5 release experimental.
218 +9. R6 calidad y optimización medida.