WNDL: qué hace exactamente, sus mecánicas y cómo convierte tu web en un sistema orientado a objetivos
11 min de lectura · Arquitectura & Producto
En la mayoría de las plataformas empresariales, el usuario tiene que memorizar dónde está cada pantalla, qué pestaña abrir primero y en qué orden cargar los datos. Si quiere configurar un canal de atención o dar de alta una integración, primero debe crear un asistente, antes una credencial, después una herramienta y recién entonces armar el flujo.
WNDL (Web Navigation & Deterministic Execution Layer) nace en Lumentia para eliminar esa fricción: es al mismo tiempo un copiloto interactivo de interfaz (UI Co-Pilot) y un motor formal de planificación y ejecución orientado a objetivos. En lugar de obligar a la persona a conocer el manual interno del software, le permite expresar qué quiere lograr y deja que el sistema calcule y ejecute el camino exacto.
La unidad fundamental en WNDL deja de ser el clic suelto o la pantalla aislada: es la transición verificable entre el estado actual del sistema (S₀) y el estado objetivo (G).
1. ¿Qué hace exactamente WNDL?
WNDL compila la anatomía completa de una aplicación web en un único artefacto declarativo y firmado criptográficamente: el wndl-manifest.json. A partir de ese único mapa de verdad, habilita cuatro capacidades concretas en tiempo real:
- Guía y Recorrido Interactivo de la UI: En cualquier pantalla donde esté el usuario, el widget puede explicar qué hace cada sección, abrir paneles o modales ocultos mediante clics reales controlados, mostrar para qué sirve cada campo o botón y cerrar los modales al terminar el recorrido.
- Inspección Contextual Instantánea (
Ctrl+Alt+Click): En vistas densas con decenas de controles, el usuario puede hacerCtrl+Alt+Click(oCmd+Alt+Clicken Mac) sobre cualquier botón o input sin disparar su acción real. WNDL intercepta el evento y despliega una tarjeta explicando qué hace ese control, qué modal abre, dentro de qué contenedor vive y qué reglas de seguridad lo gobiernan. - Planificación Multi-Salto de Dependencias (Δ(S₀, G)): Cuando el usuario pide una tarea que requiere pasos previos (por ejemplo, "configurá una herramienta HTTP en mi agente"), WNDL consulta el estado real de la cuenta (S₀), detecta si ya existe una credencial creada y, si falta, encadena automáticamente la creación de la credencial antes de registrar la herramienta.
- Ejecución Híbrida (API + WebMCP + DOM) con Garantía Anti-Duplicados: Para cada paso del plan, WNDL elige el mecanismo más rápido, económico y fiable disponible —llamando directamente a la API REST del backend cuando es posible o rellenando el formulario en pantalla frente al usuario cuando requiere revisión humana— y verifica la postcondición antes de avanzar.
2. Los objetivos de diseño de WNDL
A diferencia de los agentes basados puramente en capturas de pantalla o bucles ReAct que adivinan selectores en cada turno, WNDL fue diseñado bajo cinco objetivos estrictos de ingeniería:
| Objetivo | Qué problema resuelve | Cómo lo garantiza WNDL |
|---|---|---|
| Comprensión determinista del sistema | Los agentes visuales alucinan botones inexistentes o fallan cuando cambia una clase CSS. | Un compilador en 4 estratos extrae esquemas, endpoints OpenAPI, guardias AST de permisos y el árbol de accesibilidad real con Playwright. |
| Resolución de dependencias reales | Rellenar un formulario falla si antes no existen las entidades de las que depende. | Modelado como hipergrafo AND-OR con precondiciones, efectos de adición/borrado (add_effects / del_effects) y referencias simbólicas @ref(op).id. |
| Optimización microeconómica (EEC) | Usar siempre navegador o LLM en cada paso es lento y costoso. | Cálculo del Costo Efectivo Esperado combinando latencia, costo de tokens, hops de UI y confiabilidad bayesiana por ejecutor. |
| Cero operaciones duplicadas | Un timeout de red después de enviar un formulario puede duplicar cobros o registros. | Protocolo de reconciliación con PostGetter e idempotency_key antes de cualquier reintento. |
| Control humano y Least-Privilege | Un asistente nunca debe tener más permisos que el usuario ni ejecutar acciones destructivas solo. | Ejecución autenticada con el user_token del propio usuario y políticas duras never_click / highlight_only. |
3. Las 6 mecánicas internas de WNDL
Mecánica 1 — Compilación Semántica en 4 Estratos (manifest-gen)
WNDL no improvisa el mapa de la aplicación durante la charla con el cliente: lo compila previamente mediante el servicio manifest-gen en cuatro capas complementarias:
- Estrato 1 (Esquema e Índices): Analiza modelos y colecciones para extraer predicados de existencia (
alias.exists,credential.exists,tool.exists,flow.exists) y bloqueos de lectura/escritura (read_locks/write_locks). - Estrato 2 (Endpoints Backend / Tier 1): Analiza el AST del backend y OpenAPI para descubrir rutas
GET(que se convierten en State Getters) y rutas transaccionalesPOST/PUT/PATCH/DELETE(que se registran como ejecutores directos de Tier 1). - Estrato 3 (Guardias de Rol y Estado): Extrae de los controladores las validaciones de rol, permisos de módulo y precondiciones obligatorias.
- Estrato 4 (Superficie UI, Playbooks DOM y Overlays): Recorre las vistas con Playwright e inspección de plantillas para construir el grafo jerárquico
view → modal → form → field/buttoncon predicadosPERTENECE_A,ABRE,CIERRA,NAVEGAyGUARDA, vinculando cada formulario DOM (Tier 3) con su endpoint API equivalente (Tier 1).
Antes de publicarse, el bundle pasa por una Suite de Conformidad (reglas C01–C06) y recibe una huella criptográfica target_fingerprint firmada con HMAC-SHA256 que incluye el hash de OpenAPI y los hashes ARIA de cada vista.
Mecánica 2 — Observación del Estado Inicial (S₀) y Trazabilidad de Vista
Cuando el usuario interactúa con el widget, WNDL sabe exactamente dónde está parado y por dónde pasó:
- Contexto automático de navegación: El widget inyecta
wndl_route(ruta actual),wndl_view(ID del nodo en el grafo),wndl_view_summary(resumen funcional de la pantalla) ywndl_trace(el recorrido histórico de vistas en la sesión). - Getters autenticados con permisos del usuario: Para saber qué entidades ya existen en la cuenta (S₀), WNDL ejecuta State Getters (como
auth_me,aliases,credentials,tools,flowso selectores DOM en vivo) utilizando las credenciales del propio usuario enwindow.LumentiaContext, respetando estrictamente su rol y módulos habilitados.
Mecánica 3 — Planificación Formal sobre el Hipergrafo AND-OR (Δ(S₀, G))
Una vez traducida la intención del usuario a un conjunto de átomos objetivo G, entra en acción el planificador formal (WndlOptimalStatePlanner):
- Poda por diferencial Δ(S₀, G): Si el usuario pide crear un flujo que requiere una herramienta y una credencial, pero la credencial ya existe en S₀, WNDL poda automáticamente esa rama y planifica solo desde la herramienta en adelante.
- Promesas Simbólicas de Skolem (
SymbolicRef): Cuando la Operación B necesita el ID que recién va a producir la Operación A durante el plan, el planificador enlaza el argumento simbólico@ref(op_A).idy el orquestador lo resuelve en tiempo de ejecución apenas culmina A. - Búsqueda Exacta Branch-and-Bound con EEC: Evalúa el sub-hipergrafo usando la heurística admisible hmax, descontando operaciones compartidas y protegiendo contra amenazas causales (
del_effects). - Olas Topológicas Libres de Conflicto: Agrupa los pasos independientes en olas paralelas y aplica las Condiciones de Bernstein (Ri ∩ Wj = ∅, Wi ∩ Rj = ∅, Wi ∩ Wj = ∅) junto con coloreado de grafos Welsh-Powell para garantizar que dos operaciones paralelas jamás colisionen sobre la misma tabla o recurso.
Mecánica 4 — Selección Adaptativa de Sustrato (Tiers 0 a 3) y Superficies de UI
Cada operación del dominio puede declarar múltiples ejecutores. WNDL elige dinámicamente el mejor según el canal y la política organizacional (OrgUtilityPolicy):
- Tier 0 (Determinista Local): Cálculos, validaciones y transformaciones resueltas en memoria sin red.
- Tier 1 (API Backend / SQL): Invocación directa a endpoints transaccionales (ej.
POST /api/v1/agent/tools) con latencia de ~120 ms y costo de tokens cero. Además, permite que canales sin navegador (como WhatsApp, Instagram, Messenger o Email) planifiquen y ejecuten sobre Tier 1 podando automáticamente los Tiers visuales. - Tier 2 (WebMCP en Navegador): Herramientas estructuradas registradas en el sustrato del navegador (
WndlBrowserSubstrate). - Tier 3 (Playbook DOM Guiado): Apertura de modales, llenado paso a paso (
fill,select,check_many) y verificación en el DOM cuando no existe API o se requiere acompañamiento visual.
En el navegador, el gestor de superficies (WndlSurfaceManager) adapta el widget en tres modos sin destruir el estado de la página donde trabaja el usuario: Bubble (burbuja compacta), Docked (panel lateral acoplado que desplaza el layout sin tapar botones) y Workspace (centro de comando con visor de olas y un Stage Iframe aislado con ?wndl_stage=1).
Mecánica 5 — Los 6 Estados de Salida y el Protocolo Anti-Duplicados
El orquestador (WndlMissionOrchestrator) nunca da por exitosa una operación solo porque el clic ocurrió o porque llegó un HTTP 200. Cada paso se clasifica en uno de seis estados formales:
VERIFIED_OK: La operación respondió con éxito y elPostGetterconfirmó que el nuevo estado existe.UNVERIFIABLE_LAG: Respuesta 2xx pero el estado aún no refleja el cambio por consistencia eventual; aplica bounded polling con backoff antes de decidir.VALIDATION_ERROR: Error 400/422; efecto nulo garantizado, no se reintenta con los mismos datos.CLEAN_TRANSIENT/DRIFT_ELEMENT_MISSING: Fallo limpio pre-envío o cambio en el DOM; conmuta automáticamente a un ejecutor alternativo (por ejemplo, de Tier 3 a Tier 1).AMBIGUOUS_OUTCOME: Corte de WebSocket o timeout de lectura después de enviar la petición. Aquí rige la regla de oro de WNDL: prohibido reintentar a ciegas. Primero se ejecuta elPostGetter; si el objeto ya se creó, la misión pasa aRECONCILED_OKsin duplicar nada. Si no existe y la operación tieneidempotency_key, reintenta con la misma clave; si no es idempotente, escala aHUMAN_RECONCILIATION_GATE.PARTIAL_COLLECTION: En operaciones sobre listas (FOREACH), guarda un bitmap de progreso para reanudar exactamente desde el ítem pendiente sin repetir los anteriores.
Mecánica 6 — Seguridad Declarativa y Explorador 3D de Hipergrafos
Toda acción sobre la interfaz respeta las políticas declaradas en el manifest:
policies.never_click: Botones sensibles o destructivos (como Eliminar, Anular, Emitir o Pagar) jamás son presionados automáticamente por el ejecutor.policies.irreversible_final_stepyhighlight_only: En pasos críticos, WNDL completa los datos previos, verifica cada campo y solo resalta el botón final para que la decisión y el clic definitivo sean siempre humanos.
Además, desde la vista /brains/wndl (y la consola /wndl), los equipos pueden auditar su mapa en un Explorador 3D interactivo de doble capa (Three.js), visualizando arriba el hipergrafo de dominio AND-OR y abajo el sustrato de vistas y rutas, simulando consultas y comparando el Costo Efectivo Esperado (EEC) frente a la operación 100 % manual.
4. Cómo activarlo y configurarlo en tu sitio
Desde Configuración → Alias → Publicar en mi Web, tenés control granular sobre cómo opera WNDL en el widget de cada asistente:
- Habilitar WNDL: Activa la carga y sincronización del manifiesto para el alias.
- Navegador (botón «Guía» + recorrido guiado): Muestra a tus usuarios el mapa de la pantalla actual, el tour paso a paso que abre y explica modales, y el atajo
Ctrl+Alt+Click. - Ejecutor en el chat: Permite que el asistente navegue y ejecute playbooks o planes desde la conversación. Podés habilitar el Navegador sin el Ejecutor (o viceversa).
- Getters del Manifest con credenciales del usuario: Elegís qué getters de estado están permitidos (
auth_me, aliases, credentials, tools, flows...o*). El widget los consulta usando la sesión ouser_tokendewindow.LumentiaContextpara planificar siempre dentro de los permisos reales de quien chatea.
¿Querés profundizar en cómo se combina con el resto de la plataforma? Revisá cómo funcionan los Agent Workers, cómo configurar un asistente personalizado por usuario con least-privilege y nuestra arquitectura de observabilidad del widget.