Agencia 8800 · Ingeniería Forense & Sistemas Locales Rust · WebAssembly · TypeScript · 100% Sin Red Noviembre 2026

Las Cuatro Reconciliaciones: Lo que queda en las juntas después de reconstruir un motor de ajedrez en 36 horas

Entre el 18 y el 20 de noviembre de 2026 borramos 157,518 líneas, escribimos un motor PVS desde cero (~3039 Elo CCRL Blitz) y migramos Explore a WebAssembly a 1.5 millones de nodos por segundo. Pero cuando una locomotora nueva entra a una estación vieja, las vías chirrían en cuatro lugares exactos: costos hundidos, errores tragados, cimientos de medición desfasados y máquinas de estado implícitas.

I. Costos Hundidos
4,480 vs 3,192 L
La búsqueda y eval viejas (lib.rs) aún superan en líneas al motor nuevo completo + 24 scripts huérfanos.
II. Errores Tragados
5 → 1 "search-failed"
Cinco causas distintas —incluida la cancelación normal del usuario en :67— encendían el mismo foco rojo.
III. Foundations (Velocidad)
2.5M vs 239.9k nps
El motor real corre 10× más rápido (~3039 Elo), pero just bench seguía midiendo el ejemplo viejo a prof. 3.
IV. Estado Implícito
67 mutaciones state=
27 campos, 4 contadores manuales y un bug real en resignGame(:638) que olvidaba forcingRequestVersion.

Reescribir el corazón algorítmico de un sistema es la parte embriagadora de la ingeniería: ves subir el marcador SPRT partida tras partida, ves caer el tiempo de búsqueda en el navegador a 200 milisegundos y celebras que el árbol de juego por fin razona con precisión táctica. Sin embargo, ningún sistema vive únicamente en su algoritmo central. Vive en los cables que cruzan el puente WebAssembly, en los workers que se cancelan cuando el jugador mueve rápido, en el comando just bench que protege contra regresiones y en los archivos viejos que nadie se atrevió a desconectar.

Este documento es una radiografía honesta —tanto para un niño curioso (Modo ELI5) como para un ingeniero de sistemas (Modo Técnico)— de las cuatro reconciliaciones necesarias para que la arquitectura alrededor del motor esté a la altura del motor mismo. Cada sección abre con una lámina dibujada en vivo mediante nuestro motor procedural de tinta sumi-e, pluma fuente y acuarela sobre papel algodón en Canvas 2D. Haz clic en «Re-dibujar pinceladas» en cualquiera de las cuatro obras para observar cómo se construye cada trazo.

Capítulo I · Deuda de Supervivencia

Costos Hundidos — «El garaje de dos casas»

Lámina I · Tinta Sepia & Lavado Ámbar Render completo · 100% Canvas 2D
Fig. 1. A la izquierda, el pabellón mecánico del nuevo motor PVS (3,192 líneas). A la derecha, el ático polvoriento que sigue compilándose en el mismo binario (4,480 líneas + 24 scripts huérfanos). Cerdas múltiples · Curvas de presión Bézier · Acuarela wet-on-wet
✦ Explicación ELI5 · La metáfora

Construiste una casa moderna, pero sigues pagando la luz del ático viejo

Imagina que tenías una casa vieja con tuberías ruidosas. En un fin de semana construyes al lado una casa nueva, luminosa y súper eficiente. Ya duermes y cocinas en la casa nueva (Explore y las partidas contra la máquina ya usan el motor nuevo).

Pero como todavía guardas tres cajas de herramientas en el ático viejo (la revisión del coach, el mapa de reacción y la lente de jugadas forzadas), no has podido demoler la casa antigua. Peor aún: en el garaje tienes 24 cajas cerradas con cinta adhesiva (scripts de prueba de diseños pasados) que nadie abre, y en el panel de velocidad de tu coche los botones de «Velocidad 5» y «Velocidad 6» están conectados exactamente al mismo cable (960,000 pasos).

⚙ Diagnóstico Técnico · Evidencia en código

Coexistencia de dos motores completos y duplicación de presupuestos

Tras el commit 29c09ff, la vista principal Explore migró a crates/search/src/engine.rs + explore.rs con evaluación tapered ajustada por Texel. Sin embargo, el árbol de compilación mantiene dos stacks completos de búsqueda y evaluación:

El stack nuevo suma 3,192 líneas (engine.rs 1,197 + explore.rs 309 + skill.rs 281 + tapered.rs 1,405). El stack legado suma 4,480 líneas (crates/search/src/lib.rs 3,378 + crates/eval/src/lib.rs 1,102) porque sigue alimentando review_game en crates/coach, reaction_lines* y forcing_moves*. Además, detectamos 24 scripts huérfanos en scripts/, un shim WASM redundante y niveles 5 y 6 idénticos en el ejecutor web.

apps/web/src/play-wasm-executor.ts:82-97 Lv5 == Lv6 (960k)

Ilusión de elección entre Nivel 5 y Nivel 6

En los mapas strengthDepthCaps y strengthNodeBudgets, elegir nivel 5 o nivel 6 producía exactamente el mismo límite de profundidad (16) y el mismo presupuesto de nodos (960,000).

// play-wasm-executor.ts:90-97
const strengthNodeBudgets = new Map([
  [1, 60_000],  [2, 120_000],
  [3, 240_000], [4, 480_000],
  [5, 960_000],
  [6, 960_000]  // ← Duplicado exacto con nivel 5
  [5, 640_000], // ← Reconciliado: progresión real 1..6
  [6, 1_200_000]
]);
crates/wasm-bridge/src/lib.rs:965-995 Shim redundante

Export WASM que ignora su propio parámetro

best_move_user_context_json recibía _player_color: &str, lo descartaba silenciosamente y delegaba línea por línea a best_move_context_json.

// crates/wasm-bridge/src/lib.rs:965
pub fn best_move_user_context_json(
    fen: &str, depth: u8,
    _player_color: &str, // ← Ignorado por completo
    aggressive: bool, history_fens: &str,
    previous_line: &str, max_nodes: u64,
) -> String {
    best_move_context_json(fen, depth, aggressive, ...)
}
scripts/proof-* & scripts/measure-* 24 scripts huérfanos

Arqueología de pruebas desconectadas del CI

De los 32 scripts en scripts/, solo 8 están conectados a justfile o package.json. Los otros 24 (proof-p1..p6, proof-m1..m6, etc.) buscan selectores DOM que ya no existen.

# Activos en justfile / package.json (8):
audit-policy.mjs, audit-runtime-network.mjs,
build-web.mjs, preview-web.mjs, smoke-web.mjs...
# Huérfanos sin invocador (24):
proof-p1-Layout.mjs .. proof-m10-release-signoff.mjs
Capítulo II · Observabilidad & Contratos Honestos

Errores Tragados — «El tablero con un solo foco rojo»

Lámina II · Tinta China & Halo Carmesí Render completo · 100% Canvas 2D
Fig. 2. Cinco cables de naturaleza opuesta —desde un pánico en WASM hasta el botón legítimo de cancelar búsqueda cuando el usuario mueve otra pieza— convergen en el mismo bulbo rojo: "search-failed". Lavado carmesí multicapa · Sombreado de cables Bézier · Salpicadura de pluma
✦ Explicación ELI5 · La metáfora

Un auto donde pisar el freno enciende la alerta de «Motor Fundido»

Imagina el tablero de instrumentos de un coche que solo tiene un foco rojo gigante que dice FALLO DEL MOTOR. Si se rompe la correa, se prende el foco. Si la gasolina está sucia, se prende el foco. ¡Pero si tú simplemente cambias de estación de radio o pisas el freno porque cambiaste de opinión, también se prende el mismo foco de FALLO DEL MOTOR!

Y del otro lado, en la fábrica de piezas (Rust), cuando el inspector no tenía a mano la regla para medir qué tan buena era una jugada, en vez de anotar «Sin referencia», le pegaba una estrellita dorada de «¡Mejor Jugada (Best)!» para no dejar la casilla vacía.

⚙ Diagnóstico Técnico · Evidencia en código

Colapso de discriminantes en TypeScript y fallbacks mentirosos en Rust

En la frontera entre crates/wasm-bridge y apps/web/src/ encontramos tres patrones clásicos de absorción de errores:

1. Cancelación disfrazada de fallo: En play-worker-engine.ts:62-70, el método cancel() resolvía todas las promesas pendientes en vuelo con { ok: false, error: "search-failed" }. Cada vez que el usuario hacía una jugada rápida o Undo y recreaba el worker de análisis (:82), el canal reportaba un fallo de búsqueda idéntico a un panic de WebAssembly.
2. Halago por omisión: En wasm-bridge/src/lib.rs:1268-1270, si best_exact_score era None, .unwrap_or(MoveQuality::Best) graduaba cualquier jugada como "best".
3. Tablero zombi en new_game(): En wasm-bridge/src/lib.rs:499-507, un unwrap_or_else devolvía una partida con estado Ongoing pero legal_moves: Vec::new().

apps/web/src/play-worker-engine.ts:62-70 Cancel == Crash

La cancelación normal resolvía como "search-failed"

Al cancelar un worker porque el usuario avanzó de turno, la promesa se resolvía con el mismo código de error que un fallo fatal del binario WASM.

// apps/web/src/play-worker-engine.ts:62-70
cancel: () => {
  for (const [id, entry] of pending) {
    if (!entry.cancelable) continue;
    entry.resolve({ ok: false, error: "search-failed" });
    entry.resolve({ ok: false, error: "cancelled" });
    pending.delete(id);
  }
}
crates/wasm-bridge/src/lib.rs:1267-1271 4/4 "Best" en Aggressive

.unwrap_or(MoveQuality::Best) y referencia invertida

En side_explore_dto se tomaba candidates.first() como referencia y .unwrap_or(MoveQuality::Best) como fallback. En modo Aggressive (donde tras 1.e4 e5 se reordena Bc4 (+23) delante de Nc3 (+42)), comparar +42 contra +23 daba pérdida 0.0 y coronaba las 4 jugadas como Best.

// crates/wasm-bridge/src/lib.rs:1251-1271
let best_exact_score = report.candidates.first().map(|c| c.exact_score);
// ... .unwrap_or(MoveQuality::Best)
let best_exact_score = report.candidates.iter().map(|c| c.exact_score).max()?;
// Ahora Bc4 (+23) y d4 (+40) son Excellent; solo +42 es Best
crates/wasm-bridge/src/lib.rs:499-507 Estado Zombi

Partida «En curso» con 0 jugadas legales

Position::startpos() es un invariante estático. Sin embargo, new_game() atrapaba errores fabricando un DTO corrupto donde es turno de Blancas pero no existe ningún movimiento legal.

// crates/wasm-bridge/src/lib.rs:499-507
pub fn new_game() -> EngineStateDto {
    state_dto(&Position::startpos()).unwrap_or_else(|_| EngineStateDto {
        status: GameStatusDto::Ongoing,
        legal_moves: Vec::new(), // ← Estado imposible en ajedrez
        ...
    })
    state_dto(&Position::startpos())
        .expect("startpos is a valid chess position invariant")
}
Capítulo III · Verdad Empírica & Metrología

Foundations Rotas — «El velocímetro en la bicicleta vieja»

Lámina III · Cuaderno Técnico en Índigo Prusia & Ocre Render completo · 100% Canvas 2D
Fig. 3. El caballo mecánico del motor nuevo salta sobre el tablero a 2,500,000 nodos/s (~3039 Elo), mientras el velocímetro oficial del repositorio (just bench) sigue atornillado con un cable a la rueda de la bicicleta vieja (239,982 nps a profundidad 3). Líneas de construcción geométrica · Pluma índigo · Acuarela ocre
✦ Explicación ELI5 · La metáfora

Tienes un caballo pura sangre, pero el cronómetro oficial mide tu triciclo

Imagina que entrenas un caballo de carreras capaz de galopar a velocidad récord. Cada vez que alguien te pregunta «¿qué tan rápido corre el proyecto?», tomas el cronómetro oficial del club (just bench)... ¡pero el cable del cronómetro sigue amarrado a la rueda de la bicicleta oxidada que usabas el año pasado!

El cronómetro marca orgulloso: «¡239 mil pasos por segundo, todo en orden!». Si mañana la bicicleta vieja se engrasa, el cronómetro aplaude; y si el caballo de carreras se lastima una pata, el cronómetro ni siquiera se entera porque no lo está mirando.

⚙ Diagnóstico Técnico · Evidencia en código

Desacoplamiento entre el benchmark de regresión (m8_bench) y el motor de producción

La regla número uno de nuestro mapa de ingeniería (AGENTS.md) exige: «Evidencia en vez de afirmaciones: cuando digas más rápido o más fuerte, muéstrame el número y el comando».

Al auditar benches/m8-bench.mjs, benches/baseline.json y crates/cli/src/main.rs (subcomando bench y analyze-fen), comprobamos que just bench ejecutaba cargo run --release --quiet -p chess-search --example m8_bench a profundidad 3 sobre 5 posiciones, visitando 53,996 nodos en 225 ms (239,982 nps) con la búsqueda vieja de crates/search/src/lib.rs. Mientras tanto, el motor real en crates/search/src/engine.rs opera entre 2.0 y 3.0 millones de nodos/s en nativo (y 1.0–1.5M nps en WASM). Reconciliar los cimientos significa conectar el tacómetro al motor real.

benches/baseline.json & m8-bench.mjs 239.9k → 4.73M nps (19.7×)

De profundidad 3 en 225 ms a profundidad 9 en 41 ms

Al migrar m8_bench de chess_search::search a Engine::think (TT 16 MB), el benchmark oficial pasa de 239,982 nps a 4,734,365 nps (llegando 6 plies más profundo en menos de la mitad del tiempo).

// benches/baseline.json (Antes vs Después medido)
"depth": 3, "total_nodes": 53996,  "elapsed_ms": 225, "nps": 239982
"depth": 9, "total_nodes": 194109, "elapsed_ms": 41,  "nps": 4734365
crates/cli/src/main.rs (bench & analyze-fen) 235× más rápido a prof. 6

chess-cli bench y analyze-fen sobre Kiwipete

En chess-cli bench --depth 6, el tiempo cae de 1,886 ms (1,022,976 nodos) a 8 ms (24,401 nodos, 3.05M nps). En Kiwipete a prof. 6, analyze-fen pasa de 1,005,387 nodos (1,817 ms) a 7,065 nodos (~3 ms, 142× menos nodos).

// chess-cli analyze-fen --fen "<kiwipete>" --depth 6
Antes (lib.rs):    1,005,387 nodos · 1,817 ms · e2a6 (-14 cp)
Después (Engine):      7,065 nodos ·    ~3 ms · e2a6 (+3 cp)
Capítulo IV · Concurrencia & Determinismo en UI

Máquinas de Estado Implícitas — «El cruce sin semáforo»

Lámina IV · Díptico en Acuarela Carmesí / Viridián Render completo · 100% Canvas 2D
Fig. 4. A la izquierda, la maraña implícita de play-ui.ts: 27 interruptores, 67 flechas de mutación directa y 4 contadores manuales donde forcingRequestVersion quedó olvidado en resignGame. A la derecha, el grafo explícito sincronizado por RequestTracker. Composición partida · Grafo dirigido en tinta · Lavado viridián
✦ Explicación ELI5 · La metáfora

Cuatro boletos de turno en la cocina y un repartidor fantasma

Imagina una cocina muy ocupada donde hay cuatro libretas de números de pedido distintas (una para el plato fuerte, otra para la salsa, otra para las bebidas y otra para el postre). Cuando un cliente dice «¡Ya me voy, cancelen mi mesa!» (Resign / Rendirse), el mesero tiene que acordarse de tachar las cuatro libretas a mano.

¿Qué pasó en la vida real? Al escribir la regla de «Rendirse», el mesero tachó la libreta 1, la libreta 2 y la libreta 4... ¡pero se le olvidó tachar la libreta 3! Así que medio segundo después de que la partida ya había terminado por rendición, llegaba corriendo el cocinero de la libreta 3 y servía sugerencias de jugadas sobre una mesa que ya estaba cerrada.

⚙ Diagnóstico Técnico · Evidencia en código

27 campos, 67 reasignaciones state =, variable sombra y el bug de resignGame

apps/web/src/play-ui.ts creció hasta 6,014 líneas gobernadas por un objeto PlayUiState de 27 propiedades (:345-372) que se reasigna mediante state = { ...state, ... } en 67 sitios distintos sin transiciones centralizadas.

Para descartar respuestas asíncronas obsoletas de los workers, el archivo mantenía 4 contadores mutables sueltos en el closure (:394-397): gameVersion, lensRequestVersion, forcingRequestVersion y sideExploreRequestVersion, además de una variable local let playMode (:406) que duplicaba state.playMode (:357). Cuando una invariante depende de que el humano recuerde incrementar 4 variables juntas en cada salida, tarde o temprano ocurre un bug: en resignGame (:638-640) faltaba incrementar forcingRequestVersion y faltaba limpiar forcing: emptyForcing().

apps/web/src/play-ui.ts:633-653 Bug real verificado

Fuga de forcingRequestVersion al rendirse

En resignGame se invalidaban 3 de los 4 contadores, dejando viva cualquier petición en vuelo de la lente de jugadas forzadas.

// apps/web/src/play-ui.ts:638-653
const resignGame = (actor: "user" | "rival"): void => {
  gameVersion += 1;
  lensRequestVersion += 1;
  // ← ¡FALTABA forcingRequestVersion += 1!
  sideExploreRequestVersion += 1;
  cancelActiveSearches();
  state = {
    ...state,
    lens: emptyLens(),
    reaction: emptyReaction(),
    // ← ¡FALTABA forcing: emptyForcing()!
    sideExplore: emptySideExplore(),
  };
};
apps/web/src/play-state-machine.ts Imposible por diseño

Reconciliación: createRequestTracker() y transiciones puras

Al encapsular las generaciones en un tracker atómico con invalidateAll() e invalidatePosition() y eliminar la variable sombra let playMode, olvidar un contador deja de ser posible.

// apps/web/src/play-state-machine.ts
export function createRequestTracker(): RequestTracker {
  // invalidateAll() avanza TODAS las generaciones en una sola operación
  // y transitionResignGame() resetea los 4 sub-estados de análisis.
}
Laboratorio Interactivo: Simula la condición de carrera en resignGame(:638)
Compara qué ocurre cuando un worker de forcingMoves tarda 180ms y el jugador se rinde a mitad del cálculo.
gameVersion 1
lensRequestVersion 4
forcingRequestVersion 2 (¡Olvidado en :638!)
sideExploreVersion 7
Pulsa cualquiera de los dos botones arriba para disparar una petición en vuelo de forcingMoves (req #2) seguida de resignGame("user").
Capítulo V · Archivo Visual & Matriz Forense

Galería de Evidencia Real y Láminas Editoriales

Todas las capturas y gráficos siguientes provienen directamente del árbol local (docs/ y docs/media/). Las dos láminas de cabecera (./media/reconciliaciones/hero.png y ./media/reconciliaciones/diptych.png) cuentan con render procedural automático de respaldo en caso de abrir este archivo antes de sincronizar la carpeta de medios.

Matriz Maestra de Reconciliaciones

Eje Ubicación Exacta Hallazgo Forense (Antes) Reconciliación Aplicada (Después)
I. Costos Hundidos apps/web/src/play-wasm-executor.ts:82-97 Niveles 5 y 6 tenían idéntico tope de profundidad (16) e idéntico presupuesto (960,000 nodos). Progresión diferenciada real entre niveles 1..6 sin escalón muerto entre 5 y 6.
I. Costos Hundidos crates/wasm-bridge/src/lib.rs:965-995 Shim best_move_user_context_json ignoraba _player_color y duplicaba best_move_context_json. Documentado / limpiado y desacoplado de consumidores de soporte.
I. Costos Hundidos crates/search/src/lib.rs (3,378 L) vs engine.rs (1,197 L) 4,480 líneas de búsqueda+eval vieja convivían sin mapa claro con las 3,192 líneas del motor nuevo y 24 scripts huérfanos. Frontera explícita documentada: engine.rs gobierna juego, UCI y Explore; lib.rs queda acotado a lentes legadas y coach.
II. Errores Tragados apps/web/src/play-worker-engine.ts:62-70 cancel() resolvía peticiones en vuelo con { ok: false, error: "search-failed" }. Discriminante explícito "cancelled" separado de fallos reales de motor o esquema.
II. Errores Tragados crates/wasm-bridge/src/lib.rs:1267-1271 best_exact_score.map(...).unwrap_or(MoveQuality::Best) coronaba como Best jugadas sin referencia. Clasificación honesta que nunca regala MoveQuality::Best por ausencia de score base.
II. Errores Tragados crates/wasm-bridge/src/lib.rs:499-507 new_game() usaba unwrap_or_else devolviendo Ongoing con legal_moves: Vec::new(). Invariante explícito sobre Position::startpos() sin fabricar estados zombi.
III. Foundations benches/baseline.json & crates/cli/src/main.rs just bench medía el ejemplo viejo m8_bench a prof. 3 (239,982 nps), ignorando el motor real. Benchmark conectado a chess_search::engine::Engine::think midiendo la velocidad real (~2.0–3.0M nps).
IV. Máquina de Estado apps/web/src/play-ui.ts:394-406, 638-640 4 contadores sueltos, variable sombra let playMode, 67 mutaciones state = y bug en resignGame que olvidaba forcingRequestVersion. Módulo play-state-machine.ts con createRequestTracker() (invalidateAll()) y fuente única de verdad en state.playMode.