inkcheck

QA mecánico para historias de ink. Comprobaciones de compilación, exploración sistemática acotada de ramas, rutas de reproducción de errores en tiempo de ejecución y detección de contenido muerto, como CLI independiente para escritores y equipos, con integraciones opcionales de CI y MCP.

Los agentes empiezan aquí → SKILL.md — cuándo invocar esto, ejemplos trabajados, MUST/MUST NOT. Contrato de familia: FAMILY.md.

inkcheck es una herramienta de QA, no una herramienta de escritura. No genera, reescribe ni envía ni una palabra de prosa. Existe para que la historia que tú escribiste pueda comprobarse mecánicamente: compilarla con el compilador oficial de ink, explorar rutas de elección dentro de límites explícitos y reproducir fallos antes de que un jugador los encuentre.

¿Usa IA?

No. inkcheck en sí mismo no usa IA, aprendizaje automático, LLM ni modelos generativos para probar historias. No se entrena con tu código fuente, no infiere cambios de prosa, no reescribe texto de la historia ni envía contenido de la historia a un servicio de IA.

Está diseñado para que humanos, sistemas de CI y agentes de codificación de IA opcionales puedan ejecutar las mismas comprobaciones mecánicas de QA. La comprobación real es código determinista: el compilador oficial de ink, el runtime de ink, la exploración acotada de ramas e informes estructurados.

Related MCP server: RenForge MCP

Pruébalo en dos minutos

Con Node.js 18 o superior:

npx -y inkcheck path/to/main.ink

¿Quieres ver el informe de rutas de fallo antes de probar tu propia historia? Ejecuta la demostración sintética de dos minutos.

Promesa del producto

Inkcheck es QA mecánico acotado para historias de ink. No demuestra que cada ruta funcione en una historia grande. Explora de forma determinista los estados de historia alcanzables dentro de límites explícitos, informa rutas de reproducción exactas para los problemas que encuentra y muestra dónde — y por qué — la cobertura fue parcial, para que los autores puedan usarlo como seguro de regresión barato y repetible.

Inkcheck no demostrará que una historia interactiva grande no tiene errores. La explosión combinatoria es real: bucles, variables, aleatoriedad y código del juego anfitrión pueden crear más estados posibles de los que cualquier herramienta pueda visitar exhaustivamente.

La promesa es más estrecha y más útil: hacer que el QA mecánico de historias sea barato, repetible y accionable. Inkcheck recorre estados de elección reales alcanzables dentro de límites explícitos, te dice cuándo la ejecución fue parcial y convierte los fallos en rutas de reproducción que puedes volver a ejecutar después de una corrección. Si hoy encuentra una ruta rota, esa misma comprobación configurada debería poder buscar esa ruta de nuevo mañana.

Este es un proyecto de QA de código abierto porque ese límite importa. Si un informe exagera, pasa por alto un patrón obvio, necesita una mejor estrategia de recorrido o falla en una forma de historia que puedas compartir de forma segura, por favor trae un fixture o un issue. La hoja de ruta trata de hacer que la cobertura parcial sea más transparente y más valiosa, no de fingir que la cobertura parcial se convierte en prueba.

Dirección del producto y autoevaluación

Se planea que el valor futuro de inkcheck provenga de un híbrido reproducible: sondas amplias con semilla, inspección local sistemática, búsqueda de diversidad acotada y especialistas conscientes de Ink para compuertas, bucles, aserciones y elegibilidad de storylets. Los especialistas deben permanecer acotados y ganar más trabajo mediante evidencia nueva de cartera porque también pueden convertirse en trampas de presupuesto.

El mismo trato se aplica al hardware. La CLI local y las comprobaciones de cartera MCP de un solo disparo usan por defecto un piloto en vivo determinista de 1.024 estados que mantiene secuenciales los trabajos pequeños, con límite de profundidad y saturados de frontera autoral, y activa trabajadores acotados solo para una frontera sostenida abierta. Cada estado del piloto cuenta bajo el techo global original; la búsqueda no se reinicia para tomar la decisión. La evaluación emparejada retuvo evidencia exacta y mejoró una ejecución de The Intercept de 5M estados y profundidad 100 en un 25,6%, mientras que los trabajos restringidos y alojados conservan techos secuenciales explícitos. Consulta la evaluación de concurrencia.

Estas son puntuaciones separadas, no un promedio. Una puntuación alta de confianza no puede compensar un error de tiempo de ejecución perdido. La tarjeta de puntuación detallada de verdades de producto e ingeniería define cada objetivo 10/10, la evidencia actual, las restricciones de ingeniería y el protocolo de reevaluación utilizado en cada épica o lanzamiento. La primera evaluación completa de promoción de política v2 mantiene la asignación dinámica experimental en lugar de convertir evidencia mixta en una afirmación de lanzamiento.

Alcance de Inkcheck 0.6

Inkcheck 0.6 incluye la base de QA en cualquier momento sin afirmar una política de búsqueda dinámica universalmente mejor. La cartera acotada establecida sigue siendo el valor predeterminado de búsqueda. La concurrencia consciente de la carga de trabajo puede adelantar los resultados cuando un piloto en vivo muestra suficiente trabajo sostenido; las campañas duraderas pueden regresar, reanudarse e inspeccionar ventanas de resultados vinculadas al código fuente; los humanos y los agentes pueden elegir posturas de tiempo/recurso con nombre; y cada decisión automática sigue siendo atribuible. La expansión de cola larga, la rotación y la detención permanecen solo en modo sombra porque la compuerta de promoción de tres familias no estableció valor orientado al autor de manera suficientemente amplia como para activarlas.

Este es un contrato de lanzamiento completado, no una afirmación de que el problema de investigación más amplio esté resuelto. El tamaño dinámico de la primera ventana, los checkpoints compactos grandes, el costo atribuido al proveedor, la evaluación de agentes más amplia y los exploradores especialistas acotados siguen siendo trabajo de hoja de ruta rastreado por separado. Un lanzamiento futuro puede reemplazar la cartera fija solo después de que la evidencia comprobada supere las mismas compuertas de retención crítica, reproducción, recursos y honestidad.

Inkcheck 0.7: Reglas que importan

Inkcheck 0.7 hace que los invariantes declarados por el autor sean de primera clase en el verificador alojado, así como en la configuración local, CI y MCP. Un escritor puede agregar una regla numérica opcional como gold >= 0 en el flujo web; se muestra en lenguaje sencillo y configuración tipada generada antes de la ejecución, se comprueba durante el QA acotado ordinario y se informa con un testigo de reproducción exacto si se viola. El flujo web detecta variables de Ink declaradas para ayudar a la selección, pero el servidor sigue siendo la autoridad: las variables desconocidas, los tipos no válidos y la gramática no admitida fallan antes de la exploración; la configuración temporal de reglas se elimina con la subida. Los agentes pueden redactar propuestas de reglas tipadas pero no pueden autorizarlas silenciosamente. La versión 0.7.2 también agrega pines de evidencia de QA privados: un testigo aprobado de runtime, aserción u objetivo puede volver a comprobarse después de una edición sin otra búsqueda, mientras que una ejecución acotada nueva sigue siendo necesaria para una verificación amplia.

Un especialista separado dirigido por aserciones sigue siendo opt-in y experimental. No recibe presupuesto predeterminado, no cambia la tarjeta de puntuación ni afirma mejor cobertura hasta que pase su compuerta de evidencia preregistrada. El contrato de Reglas que importan define ambos límites.

Políticas de campaña de agentes

Los agentes MCP pueden iniciar una campaña duradera con un modo de alto nivel quick, balanced, deep, overnight o campaign en lugar de inventar pesos de explorador. balanced es el valor predeterminado para agentes nuevos; fixed preserva los controles heredados explícitos. Las anulaciones acotadas pueden cambiar la postura de estado/ventana/tiempo/memoria/disco/plazo, recursos escasos/equilibrados/abundantes, valor preferido (broad_qa, runtime_assertions, outcomes o approved_goals), trabajo protegido de cola larga y detención por ceilings frente a knee. Las ventanas base exactas permanecen libres de aserciones y objetivos y son reanudables. Las asignaciones protegidas de cola larga ahora lanzan hijos de cartera deterministas iniciados desde la raíz con una semilla de búsqueda alternativa y un límite más profundo, preservando el checkpoint base exacto. Una campaña runtime_assertions puede agregar ventanas de aserciones validadas con add_assertions; una campaña approved_goals puede agregar un objetivo validado con add_goal. Cada hijo usa una concesión explícita, guarda un informe de evidencia separado y recibe crédito solo por evidencia nueva de campaña: crítica, de intención, de nudo de autor o terminal.

La primera evaluación de hijo de campaña dirigido por historia autoral encontró una pista creíble de revisión de variable obsoleta y una hipótesis de aserción rechazada en The Intercept. Su objetivo escalonado falló, ambos hijos de alto presupuesto se detuvieron por memoria antes de 5M, y una base compartida de 500K excedió el límite de checkpoint duradero. Eso es valor de aserción prometedor más una advertencia clara: las reglas creadas por agentes necesitan validación humana, los especialistas necesitan economía de sonda a expansión, y se requieren checkpoints compactos antes de que las campañas grandes se vuelvan rutinarias.

La evaluación independiente de cola larga emparejada comparó luego una frontera compartida creciente con particiones de cartera protegidas iniciadas desde la raíz. En una campaña de Intercept de 5M, el brazo compartido se detuvo por memoria en 786.559 estados totales; nueve hijos independientes completaron los 5M con un pico de heap más bajo y acreditaron 3.558 variantes terminales nuevas de campaña frente a 407. No encontraron ningún problema crítico nuevo, nudo de autor ni final visible. Esto es evidencia de diversidad eficiente en recursos y rendimientos decrecientes medibles, no una afirmación universal de valor de QA.

La compuerta de promoción 0.6 de tres familias posterior no promovió la detención o expansión dinámica. Dog Ink Adventure y Heresy II alcanzaron un techo de recursos antes de que su base de 500K produjera un checkpoint reanudable, por lo que ninguna política de cola larga pudo actuar. En The Intercept, las particiones independientes alcanzaron 4,66M de estados con un pico de heap de 1,40 GiB mientras que la frontera creciente se detuvo en 787K estados y 3,70 GiB; el redescubrimiento terminal subió del 34% al 94%, sin ningún problema crítico nuevo, nudo de autor ni resultado visible. Inkcheck mantiene estas recomendaciones solo en modo sombra y trata el tamaño dinámico de la primera ventana como el requisito de producto más fuerte a continuación.

Cada ventana de resultados devuelve un ID de política estable, la razón de asignación, el rendimiento preferido medido, evidencia de rendimiento/recursos, un rango empírico etiquetado con incertidumbre para otra ventana, cualquier restricción vinculante y el ID de informe utilizado para inspeccionar curvas o hallazgos completos. La inspección compacta también nombra el propósito, la partición y el rendimiento marginal de la última ventana. Un knee requiere tres ventanas consecutivas sin rendimiento preferido y no puede consumir sondas protegidas. Sigue siendo una observación acotada sobre las trayectorias realmente ejecutadas, no una afirmación de que la historia está cubierta o de que no existen descubrimientos posteriores. Consulta el contrato de política de campaña y la guía de ventanas de resultados MCP.

Después de que los hijos independientes se ejecutan, la decisión compacta también incluye una recomendación de cola larga solo-sombra versionada: expandir la misma familia, rotar a otra partición o detenerse después del piso protegido. Usa el valor nuevo de campaña bajo la preferencia seleccionada, informa el rendimiento reciente por estado y segundo, requiere sondas secas progresivamente más numerosas para posturas escasas/equilibradas/abundantes, y expone el redescubrimiento compacto de valor seleccionado más las brechas de descubrimiento locales al informe factuales. Los registros antiguos marcan esas señales como no disponibles. El redescubrimiento es superposición de identidad con informes de campaña anteriores, no trabajo bruto de estados duplicados; las brechas que se amplían son observaciones, no prueba de meseta. liveEffect: false significa que esta evidencia aún no puede cambiar la asignación.

Los humanos pueden usar la misma política duradera sin aprender sus controles: inkcheck campaign story.ink ejecuta la intención equilibrada, mientras que --mode quick, deep u overnight elige una postura de resultado y tiempo. Devuelve ventanas de resultados inmutables vinculadas a la fuente a medida que avanza el trabajo, conserva el último informe parcial en una fecha límite o cancelación entre ventanas, y mantiene los techos técnicos de estado/tiempo/memoria/disco disponibles como anulaciones de expertos. Las ventanas de resultados separan el trabajo invertido, el rendimiento accionable, la incertidumbre del pronóstico y si la búsqueda puede continuar. Un intervalo de descubrimiento silencioso o una rodilla observada nunca se describe como cobertura completa.

Inicio rápido

Con Node.js 18 o más reciente:

npx -y inkcheck path/to/main.ink

No se requiere instalación global. La primera ejecución descarga el compilador oficial de ink fijado, verifica su hash SHA-256 y procesa la historia localmente.

Configuración del proyecto

Confirma un inkcheck.yml cuando un proyecto deba usar el mismo punto de entrada y ajustes de CI acotados para cada sesión humana o de agente:

schemaVersion: 1
entrypoint: story.ink
ci:
  maxDepth: 100
  maxStates: 1000000
  goalMaxStates: 250000
  seed: 1
  storySeed: 1
  search: portfolio
  concurrency: auto
  strict: true
assertions:
  - id: gold_nonnegative
    description: Gold never goes negative
    when: always
    condition:
      left: { variable: gold }
      operator: ">="
      right: { literal: 0 }
goals:
  - id: depleted_gold
    description: Seek paths where the player runs out of gold
    condition:
      left: { variable: gold }
      operator: "<="
      right: { literal: 0 }

Ejecuta inkcheck validate-config para comprobarlo. Desde ese directorio, inkcheck usa el punto de entrada y los valores predeterminados configurados; las banderas explícitas de CLI aún ganan. Las claves desconocidas fallan la validación, por lo que el comportamiento externo no compatible y los campos de política de edición no pueden aparecer implementados. El contrato publicado es config schema v1.

Las aserciones son datos tipados, nunca JavaScript ni expresiones arbitrarias de Ink. Los operandos son variables o literales escalares; las comparaciones usan ==, !=, <, <=, > o >=, y las condiciones pueden componerse con all, any y not. Las reglas se ejecutan siempre, en estados terminales o al entrar en un nudo nombrado. Las variables/nudos desconocidos y las comparaciones inválidas entre tipos fallan antes de que la exploración gaste su presupuesto de estados. Una violación siempre falla el CI e incluye los valores observados más un testigo de reproducción indexado exacto. Una ejecución limpia acotada significa solo “no se observó violación”; solo una ejecución exhaustiva informa la regla como verificada exhaustivamente.

Los objetivos usan la misma gramática de condiciones no ejecutable, pero guían la exploración en lugar de fallar el CI. La exploración general siempre recibe el presupuesto completo de maxStates. Establece goalMaxStates en la configuración o --goal-states en la CLI para añadir una porción explícita determinista de proximidad al objetivo; su valor predeterminado es cero y el presupuesto combinado no puede exceder 100,000,000 estados. Los objetivos aún se observan durante la exploración ordinaria cuando no se solicita una porción adicional. Un objetivo alcanzado incluye índices de elección exactos; un fallo dice not_reached_within_limits a menos que la exploración exhaustiva realmente demuestre que es inalcanzable. Los informes exponen los presupuestos base, de objetivo y totales por separado para que la dirección no pueda desplazar silenciosamente los hallazgos generales de control de calidad. Consulta la evidencia comparativa en search experiments.

Para una dependencia compuesta tardía, reemplaza condition con dos o más stages ordenados. Cada etapa usa la misma gramática tipada. Inkcheck busca el primer hito acumulativo no cumplido, por lo que una etapa posterior solo se alcanza en un camino cuyo estado también satisface cada etapa anterior. Un requisito previo no cumplido deja las etapas posteriores como blocked_by_stage; no las llama inalcanzables. Este primer contrato por etapas usa un presupuesto de objetivo adicional compartido y se reinicia determinísticamente desde la raíz de la historia en lugar de serializar puntos de control en tiempo de ejecución.

Para un proyecto nuevo que contenga un archivo .ink, inkcheck init crea esta configuración. Los proyectos de múltiples archivos deben nombrar la raíz con --entrypoint. inkcheck agent-kit --format codex añade la configuración cuando sea necesario, un ejemplo de GitHub Actions fijado, reglas de ignorar artefactos .inkcheck/ e instrucciones de agente compactas con versión coincidente. Ambos comandos son idempotentes y preverifican cada destino; rechazan toda la operación en lugar de sobrescribir o modificar parcialmente archivos existentes creados por el autor. El artefacto npm también incluye el canónico skills/inkcheck/SKILL.md, referencias progresivas de Ink/flujo de trabajo y diez ejercicios dorados ejecutables. inkcheck capabilities --json anuncia esto como features.bundledAgentSkill y sigue siendo la autoridad para el contrato de esquema instalado.

--save-report almacena atómicamente un informe versionado en .inkcheck/reports/ y devuelve su ID estable derivado del contenido y el punto de entrada. Una sesión posterior puede usar inkcheck artifacts list --json y inkcheck artifacts show <report-id> --json; al reabrir se informa si la evidencia guardada es current, stale o path_changed con respecto al punto de entrada actual. Los informes pueden contener texto de la historia, variables y testigos exactos, por lo que el kit de agente los ignora por defecto. Consulta local report artifacts para el contrato de confianza, privacidad y compatibilidad.

Las ejecuciones largas compartidas de base también pueden persistir su frontera viva exacta localmente. Comienza con --search=shared --no-min-repro --save-checkpoint y luego continúa más tarde con inkcheck resume <checkpoint-id> --max-states N; N es la concesión total más grande, no trabajo oculto adicional. inkcheck checkpoints list/show informa metadatos acotados, tamaño comprimido duradero, codificación de almacenamiento y frescura de la fuente. Los nuevos archivos de punto de control son artefactos gzip transmitidos; los JSON antiguos de esquema v1 simple siguen siendo legibles. Los puntos de control son privados, atómicos, vinculados a la fuente/configuración, ignorados por defecto y con límite de retención; pueden contener texto creado por el autor y estado de ejecución. Consulta local resumable checkpoints. Los pases compartidos también exponen un registro de observabilidad de recursos/rendimiento acotado que mantiene la contabilidad lógica determinista separada de las observaciones vivas de heap/RSS. Los agentes MCP pueden usar la misma base exacta a través de ventanas de resultados start_search / inspect_search / continue_search / cancel_search duraderas. También pueden usar add_goal para una sonda dirigida aditiva explícita que comienza desde la raíz de la historia y deja esa frontera base exacta intacta. Portfolio, variables compartidas, aserciones, reanudación de frontera dirigida y trabajos alojados aún no usan este contrato de puntos de control.

Verificador alojado

El repositorio ahora incluye una interfaz web autoalojada para escritores que no quieren usar una terminal. El modo alojado sube temporalmente el código fuente .ink autorizado, ofrece intenciones Quick (resultado anterior de 250K estados) y Balanced (resultado más profundo de 1M estados), crea un trabajo privado de corta duración, transmite señales de trabajo real, rendimiento e incertidumbre, y elimina el directorio temporal del trabajo después de completarse, cancelarse o fallar. Los chequeos alojados completados devuelven una identidad de ventana de resultados vinculada a la fuente e IDs de hallazgos estables. No hace públicos los informes ni retiene el texto de la historia en los registros de la aplicación. Las métricas de uso opcionales de primera parte mantienen recuentos agregados diarios más una estimación aproximada de navegadores únicos diarios que preserva la privacidad: no se retienen IPs, agentes de usuario, tokens de navegador ni perfiles de visitantes.

La CLI local sigue siendo la opción de privacidad primero porque no se produce ninguna subida de historia. Consulta Hosted checker deployment para el modelo de amenazas, el despliegue con Docker, los límites operativos y un presupuesto actual de menos de 50 $/mes.

Lo que detecta

• Errores y advertencias de compilación — desvíos rotos, variables no resueltas, cabos sueltos, con números de archivo y línea (vía inklecate, el compilador oficial)

• Errores de ejecución con una ruta de reproducción — la secuencia exacta de elecciones que desencadena una división por cero, una llamada externa incorrecta o fuera de contenido, p. ej. repro: [Enter in darkness → Descend to the cellar]

• Posibles ciclos de elección forzada sin terminación — una advertencia de revisión conservadora cuando la única elección disponible vuelve al mismo estado de control con las mismas variables visibles para el autor; las salidas opcionales, el comportamiento aleatorio, los contadores de turnos, los contadores de visitas y las llamadas EXTERNAL se excluyen intencionalmente

• Contenido no visitado, clasificado — nudos que ninguna ruta explorada visita dentro de los límites configurados, cada uno clasificado con un escaneo de desvíos entrantes: “no hay puntos de desvío creados aquí — posible huérfano” versus “tiene desvíos entrantes — probablemente más allá de los límites de esta ejecución”

• Estados terminales distintos — con un rastro de elecciones que alcanza cada uno; las variables finales diferentes se retienen como resultados distintos

vs. las alternativas

El compilador te dice que la historia es válida. Hacer clic te dice que los caminos que resultaste clic funcionan. Ink-Tester muestrea repetidamente recorridos aleatorios e informa la frecuencia a nivel de línea; inkcheck en cambio recorre los estados de elección sistemáticamente y devuelve rutas de fallo cortas. La diferencia clave es la repetibilidad: después de arreglar una ruta informada, la misma ejecución configurada puede comprobar esa ruta de nuevo. Los enfoques son complementarios, especialmente para historias con aleatoriedad o integraciones de motor.

Ejemplo

$ inkcheck examples/manor.ink
✓ compiled — 92 words, 7 knots, 6 choices
✓ explored 18050 states within limits (depth 100, 10000000 states, seed 1) — exhaustive (every reachable state visited) — 5 distinct terminal state(s)
    terminal via [Enter in darkness → Search the study → Leave with your loot]: "You slip out the servant door, heavier by half a purse."
    ...
✗ 1 runtime error(s):
    obj is null or undefined (at cellar.3)
      repro: [Enter in darkness → Descend to the cellar] (found by dfs:last)
⚠ 1 knot(s) never visited on any explored path — unreached is not necessarily unreachable:
    treasure_vault (manor.ink line 35) — no authored divert points here — possible orphan

Cuando una ejecución se corta, el informe nombra el límite que realmente la acotó — por ejemplo ⚠ coverage is partial, not a proof — paths were cut at 30 choices deep; raise --max-depth to follow longer trails. La profundidad y el presupuesto de estados son ejes separados: en ejecuciones locales de The Intercept, aumentar --max-depth de 30 a 100 alcanzó más contenido tardío de la historia con un presupuesto de 1,000,000 de estados que un presupuesto 10× mayor a profundidad 30.

El código de salida es distinto de cero en errores de compilación o ejecución. Añade --strict para fallar también en advertencias, nudos no visitados, truncamiento o stubs externos, de modo que la cobertura parcial no pueda pasar el CI silenciosamente.

Una historia no tiene que ser larga para exceder el presupuesto predeterminado. El The Intercept publicado por Inkle se considera un archivo fuente relativamente pequeño por la comunidad, sin embargo Inkcheck aún lo informa como parcial en 5,000,000 de estados: la ramificación más las variables persistentes crea un grafo de estados alcanzables mucho más grande de lo que sugiere el recuento visible de elecciones. El agotamiento es una prueba observada, no una expectativa inferida del tamaño de la fuente. Una historia de valores finitos puede ser agotable en principio pero impracticable de enumerar; el estado de turnos, aleatorio o de variables no acotadas puede hacer que el grafo semántico sea no acotado. Una ejecución acotada se detiene en lo que ocurra primero — estado, profundidad, tiempo o memoria — y dice cuál. El verificador alojado limita los trabajos compartidos a 1,000,000 de estados; los trabajos más grandes (hasta el techo de 100M de la CLI) pertenecen localmente. Consulta Rendimiento y memoria para obtener orientación sobre el dimensionamiento.

Dentro de una sola ejecución, inkcheck reparte su presupuesto de estados entre pasadas de búsqueda complementarias en lugar de apostarlo todo a un único orden de recorrido. La cartera CLI actual explora rebanadas DFS de última-opción-primero, primera-opción-primero y de dentro-hacia-fuera, añade una rebanada de muestreo aleatorio con semilla que varía los prefijos de opciones tempranas que las pasadas deterministas tienden a repetir, añade un haz de diversidad con tope de frontera que avanza nivel a nivel como BFS manteniendo un estado por linaje de firma de variable, y reserva una pequeña rebanada de anchura-primero para acortar las rutas de reproducción. La rebanada aleatoria usa una semilla predeterminada fija y el haz no necesita semilla en absoluto, así que las ejecuciones siguen siendo reproducibles en CI; cada final y error de ejecución notificado nombra la pasada (y la semilla) que lo encontró. Esto a menudo encuentra más finales y nudos alcanzables con el mismo límite de --max-states, pero sigue siendo QA acotado: un informe truncado es evidencia útil, no una prueba exhaustiva.

--search=shared opta por una alternativa experimental: las vistas profundas, de novedad-primero y con semilla se alimentan de una única frontera deduplicada y cada estado alcanzable se expande como máximo una vez. Esto puede gastar un presupuesto ajustado de forma más eficiente cuando varias estrategias redescubrirían el mismo estado. La telemetría JSON separa los checkpoints JSON/variables pendientes y activos, la ascendencia de testigos retenida, los índices de deduplicación y semánticos, las referencias de frontera y los hallazgos; también informa de la ascendencia liberada y las compactaciones de vistas obsoletas. Son estimaciones estructurales/payload contabilizadas deterministas, no el uso exacto del heap de V8. Aún no es el valor predeterminado: algunas estructuras de opciones tempranas pueden seguir favoreciendo las pasadas independientes aleatorias y de haz de la cartera.

Los consumidores de biblioteca que evalúan trabajos compartidos de larga duración pueden usar exploreSharedResumable(...). Cuando queda presupuesto, devuelve un checkpoint JSON versionado y vinculado a la fuente que contiene la frontera compartida base viva exacta; una llamada posterior eleva la concesión total (por ejemplo, de 100k a 1m) y continúa sin reproducir los primeros 100k. La equivalencia de ejecución dividida se prueba por regresión contra una ejecución ininterrumpida. Es una base de motor, aún no una función de persistencia CLI: los checkpoints pueden contener texto autoral, variables, estado de ejecución y rutas de testigos, y el esquema v1 excluye deliberadamente aserciones, objetivos y modos compartidos con conocimiento de variables/objetivos. Véase esquema de checkpoint compartido v1.

--search=shared-variable es un experimento más acotado que otorga el 12,5 % de las selecciones de frontera compartida a estados alcanzados mediante instantáneas o transiciones de variables poco comunes. El impulso está acotado y las vistas profunda, de novedad y con semilla siguen activas. Puede ayudar a grafos de storylet impulsados mecánicamente, pero no es uniformemente mejor; la tabla comparativa incluida recoge tanto ganancias como regresiones.

La cartera adaptativa sigue siendo el valor predeterminado de propósito general. Los modos experimentales no cambian sus pesos ni su comportamiento. La política de estrategia de búsqueda de inkcheck define la amplitud de referencia y las puertas de regresión necesarias antes de cualquier cambio futuro del valor predeterminado.

Búsqueda acotada frente a muestreo aleatorio

Inkcheck no es una promesa de visitar todos los estados posibles en una historia no trivial. Las ramas, los bucles, las variables, el comportamiento aleatorio y las integraciones con juegos anfitriones pueden hacer que la cobertura exhaustiva sea físicamente impracticable. Su ventaja práctica sobre el muestreo aleatorio es la reproducibilidad: dado el mismo relato y los mismos límites, inkcheck recorre el grafo de opciones sistemáticamente, devuelve rutas de opciones exactas para los fallos, informa de pistas de nudos no visitados y dice explícitamente cuándo la ejecución fue parcial.

El muestreo aleatorio sigue siendo útil, especialmente para historias con aleatoriedad o espacios de estados enormes. Trate los enfoques como complementarios: el juego aleatorio puede tropezar con caminos sorprendentes, mientras que inkcheck ofrece evidencia determinista apta para CI dentro de un presupuesto declarado.

En una prueba local de The Intercept con un límite de profundidad de 30, los presupuestos más altos encontraron más estados terminales pero no demostraron una cobertura completa. Los tiempos provienen de una única máquina de desarrollo local y deben leerse como evidencia de escala, no como un punto de referencia universal:

Esa es la interpretación prevista: cada ejecución prueba estados reales alcanzables y puede sacar a la luz rutas rotas reales, pero un informe truncado es evidencia sobre lo que se visitó, no una prueba de que todo era alcanzable o correcto.

Rendimiento y memoria

El presupuesto predeterminado es de 10.000.000 de estados y el techo es de 100.000.000, así que merece la pena saber cuánto cuesta una ejecución grande. Dos recursos acotan una ejecución: tiempo y memoria. Las historias pequeñas o agotables no tocan ninguno de los dos: la cartera sale antes de tiempo en cuanto una pasada sistemática demuestra que el espacio alcanzable está completo, así que inkcheck small.ink termina en el puñado de estados que tenga independientemente del valor predeterminado. Las cifras siguientes solo importan para historias grandes y no exhaustivas.

El tiempo escala aproximadamente de forma lineal con los estados explorados. En una máquina de desarrollo, The Intercept tardó unos 200 segundos por millón de estados (véase la tabla anterior), así que una ejecución de 10M de estados son decenas de minutos y una de 100M son horas. No hay límite de tiempo de pared en la CLI local, así que para CI o uso interactivo, fije --max-states a la cobertura que realmente necesite en lugar de confiar en el valor predeterminado — o ejecute el valor predeterminado con --progress (activado por defecto en una terminal interactiva) para poder observar e interrumpir.

La memoria es una suma de términos con distinto crecimiento, y es la razón por la que el techo es alto en lugar de peligroso:

Dos reglas prácticas de esa tabla:

• Presupueste el heap, no solo los estados. Como estimación del peor caso (sin deduplicación de estados), prevea aproximadamente 2 GB de heap por cada 10M de estados distintos. Las historias con bucles se deduplican mucho y usan mucho menos; una historia con poca deduplicación se acerca al peor caso. Así que el peor caso de una ejecución de 10M de estados (~2 GB) se sitúa cerca del límite de heap predeterminado de Node: una historia con muchos bucles se mantiene muy por debajo, pero una grande con poca deduplicación puede alcanzar el guardián de memoria antes de terminar incluso con el presupuesto predeterminado. Una ejecución de 100M de estados supera un heap predeterminado normal y se detendrá en el guardián a menos que eleve --max-old-space-size. En cualquier caso se detiene limpiamente con un informe parcial — el guardián es lo que hace seguro apuntar al techo alto, no una promesa de que la ejecución se completará.

• El guardián de memoria es el verdadero limitador, no el techo. Una ejecución se detiene limpiamente al 85 % del heap de V8 (o su --max-memory) y devuelve un informe parcial con truncatedBy.memory en lugar de fallar. Así que establecer --max-states 100000000 no es temerario — en una máquina normal, el guardián, no el techo, decide dónde se detiene. Para ir más lejos, dé a Node más heap: NODE_OPTIONS=--max-old-space-size=8192 inkcheck big.ink --max-states 100000000.

• Los límites de seguridad no son decisiones de eficiencia. Los topes de estado, tiempo y memoria responden a «¿hasta dónde puede llegar este trabajo?». No afirman que usar toda la máquina sea valioso ni que una meseta aparente esté completa. La ruta de investigación 0.6 mide los hallazgos nuevos de la cartera a lo largo del tiempo, el rendimiento, las brechas de recuperación, el RSS máximo y los bytes de frontera retenidos para que las futuras políticas rápida/equilibrada/profunda puedan elegir ventanas de resultados útiles mientras reservan sondas de cola larga. Los límites fijos siguen disponibles para CI y auditoría.

Palancas, en orden de impacto, cuando una historia es demasiado grande para terminar: eleve --max-old-space-size (más margen), pase --no-min-repro (elimina la frontera BFS superlineal), baje --max-states (acota tanto tiempo como memoria), o divida la historia y compruebe las partes por separado. En el modo compartido experimental, establezca --max-frontier-memory o --max-frontier-states cuando la propia cola de checkpoints pendientes necesite un límite más estricto, y eleve ese envoltorio solo cuando su informe muestre que sigue llegando evidencia útil. El veredicto nextRun nombra el límite vinculante después de cada ejecución para que sepa qué palanca se aplica.

La evaluación medida de ejecución profunda segura para recursos registra cómo se comportan los guardianes en trabajos autorales con techo de 5M, incluida la evidencia de marcas de agua altas de estados pendientes y bytes serializados de la frontera compartida.

Servidor MCP

Herramientas para agentes de IA que trabajan en historias de ink:

Añade a Claude Code:

claude mcp add inkcheck -- npx -y inkcheck mcp

o a cualquier configuración de cliente MCP:

{
  "mcpServers": {
    "inkcheck": { "command": "npx", "args": ["-y", "inkcheck", "mcp"] }
  }
}

El perfil MCP predeterminado expone cinco herramientas: inkcheck_capabilities, inspect_story, compile_story, start_search e inkcheck_workflow. Esto mantiene pequeño el contexto de arranque de agentes nuevos; capabilities enumera las operaciones lógicas y los campos de solicitud del enrutador. Establece INKCHECK_MCP_PROFILE=full solo para clientes que requieran cada operación como una herramienta nombrada separada.

El bucle de agente compacto es inkcheck_capabilities -> inspect_story -> compile_story -> start_search -> enrutar operaciones de hallazgo/reproducción/regresión a través de inkcheck_workflow -> corregir -> compilar y verificar. Las sesiones de ventana de resultados son la ruta de agente predeterminada porque son duraderas, acotadas, paginadas y vinculadas al origen. Las operaciones lógicas start_campaign / continue_campaign añaden una política agregada y gasto/procedencia medidos alrededor de la misma frontera compartida exacta; las operaciones ordinarias start_search / continue_search conservan el control explícito de concesión acumulativa. Las llamadas son síncronas, por lo que la cancelación es fiable en los límites duraderos devueltos, no como adelantamiento a mitad de ventana. inspect_search sigue siendo mínimamente privado; add_goal puede gastar un presupuesto dirigido informado por separado sin debilitar la búsqueda base exacta, y replay_witness es el límite explícito que devuelve una transcripción actual, rastro de elecciones y estado de variables. Para fallos en tiempo de ejecución, violaciones de aserciones y testigos de objetivos aprobados, ejecuta pin_regression antes de editar y check_regression después para reproducir un testigo privado exacto sin otra ejecución de búsqueda. Un pin no es una verificación amplia; ejecuta una nueva búsqueda acotada después de ediciones significativas. Consulta Pines de evidencia de QA, la habilidad incluida y Sesiones de ventana de resultados MCP.

Cuando un autor o agente propone reglas de historia, inkcheck_workflow puede ejecutar review_contract primero. La revisión valida aserciones y objetivos tipados contra la historia compilada, inventaría contratos existentes, requiere aprobación del autor y recomienda QA amplio con presupuesto dirigido cero por defecto. Es de solo lectura: no puede editar configuración, gastar presupuesto de búsqueda ni promover silenciosamente una sonda de objetivo. Consulta Contratos de QA dirigidos por agente.

CLI

inkcheck capabilities [--json]
inkcheck inspect <story.ink> [--json]
inkcheck <story.ink> [--max-depth N] [--max-states N] [--seed N] [--story-seed N] [--search=portfolio|shared|shared-variable] [--concurrency auto|N] [--max-frontier-states N] [--max-frontier-memory MB] [--auto] [--profile] [--next] [--no-min-repro] [--strict] [--save-report] [--save-checkpoint] [--progress=auto|human|ndjson|off] [--human|--json|--json-stream|--markdown]
inkcheck artifacts list [--json]
inkcheck artifacts show <report-id> [--json]
inkcheck artifacts findings <report-id> [--limit N] [--cursor C] [--json]
inkcheck artifacts finding <report-id> <finding-id> [--json]
inkcheck artifacts replay <report-id> <finding-id> [--json]
inkcheck artifacts delete <report-id> [--apply] [--json]
inkcheck artifacts prune --keep N [--apply] [--json]
inkcheck checkpoints list [--json]
inkcheck checkpoints show <checkpoint-id> [--json]
inkcheck resume <checkpoint-id> --max-states N [--json]
inkcheck mcp    # start the MCP server on stdio

inkcheck capabilities --json permite a los agentes comprobar versiones de esquema, límites, modos de búsqueda y funciones explícitamente compatibles o no disponibles antes de confiar en ellas. inkcheck inspect story.ink --json realiza descubrimiento determinista solo de origen sin compilar ni explorar: sigue los includes locales del proyecto y devuelve un mapa acotado de la forma de la historia, semántica, externos, knots/funciones, declaraciones/lecturas/escrituras de variables y puertas de condición estáticas con sitios de asignación factuales. Una sesión MCP duradera puede convertir una puerta compatible seleccionada explícitamente en una ejecución de objetivo probe_gate acotada separada; esa sonda iniciada en la raíz preserva la frontera base exacta e informa un testigo o un fallo acotado. La inspección de puertas y los sitios de asignación son pistas de requisitos previos, nunca prueba de alcanzabilidad ni un cambio en la asignación de búsqueda predeterminada. Consulta el contrato de inspección de puertas compuestas y el contrato de descubrimiento de agentes.

El protocolo de evaluación de sondas de puertas compara la búsqueda compartida ordinaria con la sonda explícita del mismo presupuesto en un candado de combinación de elección temprana y una celda opcional de 5M de The Intercept. Es evidencia de si vale la pena un direccionamiento adicional de requisitos previos, no una afirmación de cobertura o promoción.

Las comprobaciones JSON usan el esquema de informe versionado. Los hallazgos tienen IDs estables y tipos normalizados; los testigos de finalización y error en tiempo de ejecución llevan tanto texto de elección humano como índices de elección basados en cero, de modo que las etiquetas duplicadas sigan siendo exactamente reproducibles a través de playtest_story. El sobre registra la versión de Inkcheck, la huella de la historia compilada, la configuración efectiva, el límite de vinculación y un shadowDecision solo de observación, conservando las secciones establecidas compile, stats, explore y nextRun.

--concurrency auto es el valor predeterminado de cartera local. Establece un techo de cuatro carriles, no cuatro trabajadores incondicionales: una pasada DFS de adentro hacia afuera se ejecuta durante como máximo 1.024 estados, luego el clasificador versionado permanece secuencial cuando la historia se agota, la profundidad se vincula, los knots creados ya están saturados, el hardware tiene un solo núcleo o la memoria no puede financiar trabajadores de forma segura. Una frontera sostenida abierta mantiene esa pasada activa en el padre mientras las pasadas no tocadas comienzan en trabajadores persistentes. --concurrency 1 es una exclusión secuencial estricta; los valores explícitos 2-16 preservan un techo fijo de trabajadores sin clasificación de carga de trabajo. La búsqueda compartida y las ejecuciones de objetivos aditivos permanecen automáticamente secuenciales a menos que se haya solicitado explícitamente un valor fijo incompatible.

Los informes exponen concurrencyMode, el techo resuelto, la política/decisión/motivo de activación, el trabajo piloto, los trabajadores efectivos, el plan de heap agregado y las evaluaciones duplicadas (cero para la política de producción). El fallo de un trabajador conserva la evidencia completada más reciente e informa truncatedBy.worker; nunca se hace pasar por una parada de presupuesto de estados. Las implementaciones alojadas pasan su propio techo explícito por trabajo, con un valor predeterminado de uno en el contenedor de producción, y la cancelación real de hijos limpia las subidas temporales. El RSS máximo puede ser mayor porque la sobrecarga de V8/tiempo de ejecución no es heap; el clasificador estima la forma de la carga de trabajo, no la integridad de la cobertura.

MCP usa salida de máquina compacta por defecto: la inspección está limitada a 16 KiB y la compilación, estadísticas, exploración de un solo disparo y respuestas de ventana de resultados a 32 KiB. La omisión de salida se informa por separado del truncamiento de búsqueda acotada. Los informes completos con contenido de historia siguen disponibles solo a través de llamadas explícitas de detalle o profundización.

Los informes guardados admiten profundización acotada en hallazgos sin cargar el informe completo. artifacts findings devuelve como máximo 20 resúmenes mínimamente privados por defecto (máximo 100) y un cursor vinculado al informe; los resúmenes omiten prosa de historia, variables, texto de elección y rutas de testigos. artifacts finding obtiene un hallazgo estable completo. artifacts replay recompila el punto de entrada guardado y sigue las elecciones indexadas de ese hallazgo con su semilla de historia guardada, pero solo mientras la frescura del artefacto sea current; el origen obsoleto o movido falla de forma segura.

El almacenamiento de informes es privado y acotado: un informe puede usar como máximo 256 MiB y todos los informes de un proyecto pueden usar como máximo 1 GiB. Un guardado que supere cualquiera de los techos falla sin eliminar evidencia antigua. artifacts delete y artifacts prune --keep N muestran una vista previa por defecto y mutan solo con --apply; prune conserva los N informes más recientes para cada punto de entrada y elimina como máximo 100 por invocación. Este ciclo de vida explícito evita que un ID de informe estable desaparezca simplemente porque otra ejecución terminó.

Los mantenedores pueden comparar recomendaciones de sombra entre ejecuciones de presupuesto independientes con el evaluador de políticas de sombra dirigido por manifiesto. El benchmark de promoción de búsqueda separado ejecuta matrices de línea base/candidato emparejadas en un corpus de 20 familias verificado más un nivel de proyectos creados con consentimiento seguro fijado, informa observaciones de recursos y pérdidas de la peor familia/proyecto, y nunca declara un ganador. La primera evaluación de proyectos creados encontró paridad donde las celdas se completaron y límites de recursos significativos de forma de proyecto, no una ventaja de la política v2. Ninguna herramienta llama oráculo a una ejecución acotada más grande ni cambia la política predeterminada.

--max-depth acepta 1–1.000 y --max-states acepta 1–100.000.000, con un presupuesto predeterminado de 10.000.000. Estos techos estrictos evitan que entradas de automatización malformadas deshabiliten accidentalmente los límites de exploración. El valor predeterminado es deliberadamente ambicioso porque tres cosas hacen que un presupuesto grande sea seguro en lugar de imprudente: una historia totalmente explorable sale temprano en el momento en que una pasada sistemática demuestra que es exhaustiva (por lo que las historias pequeñas aún terminan en un puñado de estados), el guardián de memoria se detiene limpiamente antes de un fallo de falta de memoria, y el informe de progreso te permite observar e interrumpir una ejecución larga. Una historia grande y no exhaustiva por lo tanto usará ese presupuesto — consulta Rendimiento y memoria antes de ejecutar una en CI, y fija un --max-states más pequeño allí si un tiempo de ejecución acotado importa más que la profundidad de cobertura.

--max-states es un presupuesto total para la ejecución, no una promesa de que una sola caminata DFS gastará todos los estados. Por defecto, la CLI divide la mayor parte de ese presupuesto entre tres vistas DFS complementarias del árbol de elecciones más una porción de muestreo aleatorio con semilla, y mantiene una pequeña porción de búsqueda en anchura para rutas más cortas de fallo y finalización. Usa --no-min-repro para gastar esa porción de reproducción en la cartera DFS cuando el acortamiento en anchura sea menos importante que una búsqueda más amplia.

--seed (predeterminado 1) controla solo la porción de búsqueda de muestreo aleatorio de Inkcheck. --story-seed (predeterminado 1) establece independientemente el estado RNG inicial de Ink para el comportamiento de RANDOM() y barajado. Mantén ambos fijos para CI reproducible y reproducción exacta de testigos; cambia --seed para muestrear diferentes caminatas de elección, o cambia deliberadamente --story-seed para ejercitar otra secuencia válida de aleatoriedad de historia. Los comandos SEED_RANDOM(...) creados aún tienen efecto y pueden anular la semilla de historia inicial. Inkcheck registra ambas semillas y lleva storySeed en las instrucciones de reproducción, pero una ejecución no enumera cada semilla de historia posible. El campo foundBy de cada hallazgo en la salida --json nombra la pasada que lo descubrió, p. ej. dfs:last o random:seed=1.

--search=shared selecciona el motor experimental de múltiples frentes con estado compartido; --search=portfolio es el valor predeterminado sin cambios. El modo compartido sigue siendo determinista para una semilla fija y aún respeta los controles de profundidad, estado, memoria, tiempo, progreso y acortamiento de reproducción.

--save-checkpoint es deliberadamente más estrecho que la búsqueda compartida ordinaria: requiere --search=shared --no-min-repro y sin aserciones, objetivos, --auto, --next ni artefacto de informe en el mismo comando. Cuando queda trabajo activo, la salida JSON incluye un ID de checkpoint vinculado al origen. inkcheck resume <id> --max-states N requiere que el origen y los vínculos de búsqueda coincidan y que N supere la concesión total previa del checkpoint; guarda automáticamente la siguiente generación. Las búsquedas completadas y detenidas por recursos devuelven su informe sin inventar un checkpoint reanudable.

--search=shared-variable añade una pequeña frontera de rareza de variables a la búsqueda compartida. Prioriza valores de variables poco comunes observados y cambia mecánicamente; no usa IA, no entiende el significado de la historia ni infiere qué valores son deseables.

--max-frontier-states y --max-frontier-memory son envoltorios de seguridad opcionales de búsqueda compartida para los puntos de control pendientes retenidos. Ninguno tiene un valor predeterminado: Inkcheck no impone un límite de frontera universal bajo. Si un envoltorio explícito se activa, la ejecución conserva sus hallazgos, informa truncatedBy.frontier y no etiqueta erróneamente la parada como agotamiento del presupuesto de estados. Los mismos controles están disponibles como entradas ci.maxFrontierStates / ci.maxFrontierMb y MCP explore_story.

--max-memory <mb> limita cuánta memoria heap puede usar toda la ejecución antes de detenerse limpiamente. Un aborto por falta de memoria del heap de V8 no se puede capturar después del hecho, por lo que inkcheck vigila la memoria durante la exploración y — antes de que se produzca un bloqueo — se detiene, conserva todo lo encontrado hasta el momento e informa truncatedBy.memory con un informe parcial en lugar de perder la ejecución. Los límites explícitos retienen hasta el 25% (como máximo 1 GiB) para la construcción y el vaciado del resultado final; el flujo acotado informa tanto el envoltorio completo como la marca de agua de búsqueda inferior. El límite predeterminado es el 85% del límite del heap de V8 (que respeta cualquier NODE_OPTIONS=--max-old-space-size que establezcas), por lo que las ejecuciones grandes en hardware modesto se degradan con elegancia en lugar de morir; pasa un valor explícito para ajustarlo o aflojarlo. En una parada por memoria, el veredicto de nextRun es investigate (aumenta --max-old-space-size, reduce --max-states o divide la historia) — nunca broaden, ya que más presupuesto solo chocaría contra la pared antes.

--max-time <s> es la contraparte de tiempo de pared total: el plazo comienza antes de la compilación y el escaneo de fuentes, y la ejecución retiene el 10% de la concesión (con un mínimo de 250 ms y un máximo de 60 segundos) para fusionar los hallazgos retenidos y vaciar su resultado. La exploración se detiene con truncatedBy.time en lugar de agotar el presupuesto de estados. No hay límite de tiempo predeterminado en la CLI local. Está pensado para CI o cualquier contexto que necesite un tiempo de ejecución acotado pero que aún quiera los hallazgos hasta el momento — la misma idea de parcialidad elegante que el guardián de memoria, aplicada al tiempo. El verificador web alojado lo establece automáticamente, justo por debajo de su tiempo de espera máximo, por lo que una historia lenta devuelve un informe parcial en lugar de ser eliminada.

--profile imprime un perfil de forma estático y económico de la historia — variables y dónde se asignan, densidad de opciones, la ruta de desvío más larga — además del límite de profundidad y los pesos de pasada que inkcheck elegiría para esa forma, sin ejecutar ninguna exploración. --auto aplica esas sugerencias: eleva --max-depth cuando las rutas de desvío estáticas superan el valor predeterminado (nunca lo reduce, y tus banderas explícitas siempre ganan) y entrega los pesos de pasada del perfil a la cartera. En una historia cuya ruta principal tiene 40 opciones de profundidad, la configuración predeterminada no encuentra nada mientras que --auto llega al final y demuestra que la historia es exhaustiva en ~111 estados.

Las terminales interactivas muestran una línea de progreso en vivo concisa por defecto: fase real, estados explorados contra el presupuesto de trabajo configurado, descubrimientos y tiempo transcurrido. --progress=human fuerza instantáneas legibles para los registros de CI; --progress=ndjson escribe eventos versionados para agentes y analizadores; --progress=off silencia el progreso. Ninguno de estos porcentajes afirma cobertura de la historia. El informe final de stdout sigue siendo autoritativo, y el progreso nunca incluye prosa de la historia, opciones, variables o fragmentos de código fuente.

Cada informe también lleva un veredicto nextRun — un pequeño vocabulario cerrado (stop, deepen, broaden, reseed, investigate) calculado de forma determinista a partir del propio informe, con banderas concretas, una justificación que cita los campos que utilizó y la ganancia esperada respaldada por evidencia. --next actúa sobre él: después de la verificación, inkcheck aplica la escalada recomendada y vuelve a ejecutar, hasta tres veces, deteniéndose en un veredicto stop/investigate, en los techos de bandera, o cuando una ejecución escalada no encuentra nada nuevo (punto fijo). El rastro por ejecución aparece en la salida --json como runs; la narración de saltos va a stderr para que la salida de máquina permanezca limpia. Las recomendaciones nunca superan los techos duros documentados — cuando ningún aumento de bandera tiene evidencia detrás, el veredicto se degrada a investigate y señala los nudos que vale la pena revisar.

GitHub Actions:

- uses: actions/setup-node@v4
  with: { node-version: 22 }
- name: Check the story and publish a readable summary
  shell: bash
  run: |
    set -o pipefail
    npx -y inkcheck story/main.ink --strict --markdown --max-states 500000 | tee -a "$GITHUB_STEP_SUMMARY"

El ejemplo fija --max-states 500000 para que el trabajo tenga un tiempo de ejecución predecible; el presupuesto predeterminado es 10,000,000, que una historia grande y no exhaustiva realmente gastaría (ver Rendimiento y memoria). Fija un presupuesto en CI siempre que un tiempo de pared acotado importe más que la cobertura máxima.

--strict falla no solo por advertencias y nudos no visitados, sino también cuando la exploración se trunca o una función EXTERNAL tuvo que ser simulada. Esto evita que una verificación parcial luzca una insignia verde de “completa”.

Consulta la guía de QA de InkJam para una configuración amigable para escritores y ayuda para interpretar el informe.

¿Encontraste un resultado engañoso? Usa los formularios de incidencias públicas para informar un resultado incorrecto o omitido, ofrecer un fixture mínimo con licencia o solicitar una verificación de clínica de QA opcional. Nunca adjuntes material de historia privado, bajo embargo o restringido por jam a una incidencia pública.

Para humanos, CI y agentes

inkcheck puede ser manejado por un humano en una terminal, un trabajo de CI o un agente de codificación de IA opcional. La herramienta en sí misma aún no usa IA; los agentes son solo otro llamador de la CLI o del servidor MCP.

• Interfaz legible por máquina: tool.json en la raíz del repositorio describe las banderas de CLI, las herramientas MCP, los códigos de salida y las formas de salida de --json / --json-stream en un solo archivo.

• --json emite el informe completo como un único objeto JSON ({ compile, stats, explore }) en stdout — analiza eso en lugar de extraer la salida bonita. explore.passes mantiene una discoveryCurve local de pasada acotada (“lo que este explorador encontró”) más una portfolioMarginalCurve solo de cartera (“lo que este explorador añadió primero”), separando terminales exactos, resultados visibles, errores de ejecución, aserciones, metas/etapas, nudos y novedad comparable. Los resúmenes preservan los primeros/últimos estados de descubrimiento y los hechos de brecha seca a pesar de la compactación. Los informes de cartera también incluyen una curva de toda la ejecución en orden real de ejecución intercalada; el tiempo de pared permanece observacional en los eventos de progreso. explore.schedule muestra cómo las rondas adaptativas gastaron el presupuesto. El shadowDecision versionado muestra lo que la futura política de cualquier momento recomendaría y por qué, incluyendo pisos protegidos por pasada e incertidumbre. Es solo observacional (applied: false): nunca cambia la búsqueda actual ni afirma que la cobertura acotada sea prueba.

• --json-stream emite testigos numéricos de hallazgos reproducibles como NDJSON cuando se retienen, luego un resumen terminal acotado en lugar de materializar el informe enriquecido completo o una cadena JSON del tamaño de un informe. Actualmente requiere --concurrency 1, admite una sola ejecución de exploración (sin --next ni --profile) y no se puede combinar con --save-report. Un modo de etiqueta numérica reservada admite la puntuación neutral de oráculo de InkBench sin exponer variables de oráculo a la búsqueda ni transmitir cada final ordinario. Usa el flujo para evaluaciones largas de procesos externos donde la evidencia parcial debe sobrevivir un límite de envoltorio duro. Consulta el contrato de flujo de evidencia acotado.

• --progress=ndjson emite eventos versionados de ciclo de vida y progreso de trabajo en stderr para un agente o analizador de registros de CI. statesExplored / stateBudget es uso de presupuesto, no cobertura de historia; el informe final de stdout sigue siendo autoritativo. Consulta el contrato de progreso NDJSON.

• --human emite una lista priorizada de correcciones agrupada por errores, advertencias y notas, con ubicaciones de archivo/línea cuando estén disponibles, rutas de opciones para fallos de ejecución y un siguiente paso para cada hallazgo.

• --markdown emite un informe compatible con el Resumen de Pasos de GitHub para humanos que revisan CI.

• Códigos de salida deterministas: 0 limpio · 1 errores de compilación/ejecución (o, bajo --strict, advertencias, nudos no visitados, truncamiento o stubs externos) · 2 error de uso. Ramifica según el código de salida; no hagas grep del texto.

• MCP: claude mcp add inkcheck -- npx -y inkcheck mcp expone el perfil compacto de agente de cinco herramientas. Usa INKCHECK_MCP_PROFILE=full para el catálogo de compatibilidad.

• El bucle: edita .ink -> compile_story -> start_search -> enruta la siguiente acción de evidencia a través de inkcheck_workflow -> corrige -> compila y verifica. inkcheck es una verificación mecánica repetible para un grafo de historia que generaste o editaste; úsalo para verificar tu propio trabajo antes de devolverlo.

• El bucle de cobertura: explore_story (y la CLI --json) devuelve nextRun — cambia según su recommendation (stop / deepen / broaden / reseed / investigate) y vuelve a ejecutar con nextRun.flags hasta que stop: true. O deja que la CLI lo maneje: inkcheck story.ink --next.

llms.txt en la raíz del repositorio es un resumen compacto y amigable para modelos de todo lo anterior.

Cómo funciona

• Compilación usa inklecate, el compilador canónico — encontrado vía $INKLECATE_PATH, luego PATH, y luego descargado automáticamente desde la versión oficial fijada de ink 1.2.1 en ~/.cache/inkcheck en la primera ejecución. Los archivos descargados se verifican contra hashes SHA-256 fijados antes de la extracción. Las historias se compilan con -c para que todas las visitas a nudos se cuenten.

• Exploración ejecuta la historia compilada en inkjs (el puerto oficial del runtime JS), reutilizando instancias de historias agrupadas para que el JSON compilado se analice una vez por pasada y los estados se rebobinen vía LoadJson. Inkcheck inicializa la aleatoriedad de la historia desde --story-seed (por defecto 1), y luego preserva el estado del RNG de Ink en cada rama guardada; el SEED_RANDOM(...) del autor sigue siendo autoritativo cuando se ejecuta. Los estados se deduplican por hash de contenido. Se siguen los INCLUDEs.

• La CLI usa una búsqueda de portafolio acotada y adaptativa. Pasadas complementarias — última-opción-primero, primera-opción-primero, y DFS de dentro-afuera, un haz con prioridad de diversidad, y caminatas aleatorias con semilla — se ejecutan intercaladas en diez rondas deterministas. Los pesos iniciales (aproximadamente 20/20/26/15/20%, o la sugerencia de un perfil de forma bajo --auto) se reasignan cada ronda hacia pasadas cuyos hallazgos siguen creciendo, con un piso fraccional previsto del 8% por pasada activa. La reproducción de políticas solo para investigación convierte esa intención en servicio entero acumulativo auditable y normaliza la recencia a las ventanas de ejecución observadas de cada pasada en lugar de un contador global de estados. Requiere tres ventanas antes de estimar el rendimiento, expira las señales después de una o dos ventanas medidas sin renovación, y permite superposiciones de asignación experimentales solo para evidencia renovada de runtime/aserción o progreso explícito de objetivos; la cobertura amplia permanece con el planificador establecido. El planificador de producción permanece sin cambios hasta que pase el corpus completo de promoción. Las pasadas son complementarias: los ordenamientos DFS agotan sistemáticamente los subárboles, el haz distribuye el presupuesto entre linajes de estados variables dentro de un límite duro de frontera, y las caminatas aleatorias vuelven a lanzar cada punto de elección para que las combinaciones de opciones tempranas se muestreen en lugar de repetirse. Los hallazgos se fusionan en un informe, cada uno etiquetado con la pasada que lo encontró, y el cronograma ejecutado aparece en la salida --json.

• --concurrency auto consciente de la carga de trabajo es el valor por defecto del portafolio local. Su piloto de DFS de dentro-afuera en vivo de 1,024 estados se convierte en el prefijo de la primera ronda adaptativa normal, y luego continúa secuencialmente o se superpone con pasadas no tocadas en trabajadores persistentes acotados. Si el tiempo o la memoria se agotan durante ese piloto — o la fecha límite llega antes de que cualquier trabajador se inicialice — el piloto válido se devuelve como un informe parcial truncado explícitamente por recursos, nunca mal etiquetado como agotamiento del presupuesto de estados. La compuerta de 80 celdas 100K retuvo hallazgos exactos, prueba y cronogramas adaptativos con solo dos activaciones de frontera abierta; las compuertas de 5M The Intercept profundidad-30/profundidad-100 retuvieron evidencia exacta, rechazaron el trabajo acotado por profundidad, y mejoraron el trabajo sostenido de 657.7s a 489.0s. Cada estado permanece dentro de un techo y las evaluaciones piloto duplicadas son cero. El 1 explícito preserva la ejecución secuencial; los techos explícitos de 2-16 preservan concurrencia fija. Ver la evaluación de concurrencia.

• El --search=shared experimental mantiene una identidad de estado global y expone el trabajo pendiente a través de vistas de frontera profunda, de novedad y con semilla. Un estado elegido por cualquier vista se expande una vez; el JSON de checkpoint expandido se libera inmediatamente, los enlaces padre compactos sobreviven solo mientras un descendiente pendiente necesite la ruta exacta de reproducción, y los IDs de vista obsoletos se compactan periódicamente. Los informes exponen contabilidad de componentes y envolturas de checkpoint explícitas opcionales. La rareza de estado-variable y de transición-variable se registra como telemetría de evaluación.

• El --search=shared-variable experimental reemplaza una de cada ocho selecciones de frontera compartida con una vista de rareza de variable. Su puntuación combina la frecuencia observada de la instantánea de variable destino y el cambio más raro en ese borde; no puede consumir más que su porción fija, por lo que la novedad del grafo, la profundidad y la exploración con semilla permanecen representadas.

• En el momento en que cualquier pasada sistemática visita cada estado alcanzable sin alcanzar un límite, todo el portafolio se detiene: cada estado adicional sería redundante. Una historia pequeña completamente explorable con el presupuesto por defecto de 10,000,000 estados aún termina en el puñado de estados que realmente tiene — el gran valor por defecto no cuesta nada cuando una historia es agotable.

• La pasada de haz responde "¿qué debería optimizar un haz?" de manera concreta: los supervivientes se seleccionan en rotación entre grupos de firmas de variables (diversidad primero), clasificados dentro de cada grupo por novedad — nudos recién visitados, luego nuevas firmas de variables, luego nuevos conjuntos de opciones ofrecidas. Es determinista sin semilla, e informa la ejecución como truncada siempre que haya tenido que podar un estado alcanzable, por lo que un haz nunca reclama silenciosamente cobertura completa.

• A menos que se omita con --no-min-repro, la CLI reserva aproximadamente el 10% del presupuesto solicitado de --max-states para una porción de reducción de reproducción en anchura primero. BFS alcanza hallazgos compartidos por senderos de elección más cortos cuando es posible y puede contribuir con hallazgos superficiales adicionales.

• Los límites (--max-depth, --max-states) mantienen bajo control la combinatoria del peor caso; el informe dice explícitamente cuándo fue truncado.

Límites de cobertura

• La exploración está acotada. Un informe truncado es evidencia sobre estados visitados, no prueba sobre toda la historia.

• Los informes indican los límites bajo los que se ejecutaron (profundidad, presupuesto de estados, semilla de búsqueda y semilla de historia) y, cuando se truncan, qué límite realmente cortó la cobertura (truncatedBy en --json, incluyendo memory) con consejos específicos sobre qué bandera elevar.

• Una ejecución grande que agotaría la memoria se detiene limpiamente y devuelve un informe parcial (truncatedBy.memory) en lugar de fallar — la huella de memoria está dominada por el conjunto hash de deduplicación (~lineal en estados distintos) y, en historias profundas con pocos bucles, la frontera de reproducción en anchura primero, por lo que --no-min-repro y un --max-states más ajustado son las palancas cuando una historia es demasiado grande para terminar.

• Las historias pequeñas a menudo obtienen la garantía opuesta: cuando una pasada sistemática visita cada estado alcanzable sin alcanzar un límite, el informe lo dice (exhaustive), y el agotamiento del presupuesto de la porción de muestreo ya no cuenta como truncamiento.

• Las funciones EXTERNAL se sustituyen con cero porque el juego anfitrión no está disponible. El informe nombra cada stub; el modo estricto falla en lugar de reclamar cobertura completa.

• El comportamiento aleatorio es repetible para la semilla de historia informada, pero una ejecución no enumera cada posible semilla de historia. Varíe deliberadamente --story-seed y mantenga las pruebas de juego humanas en el bucle cuando la frecuencia de resultados importe.

• Un nudo no visitado puede estar intencionalmente inactivo, ser entrado por el motor, o ser inalcanzable. El triaje de desvíos entrantes separa los huérfanos probables del contenido probablemente limitado por límites, pero es una indicación de revisión, no una instrucción automática de eliminación.

Hoja de ruta

La hoja de ruta se rige por la tarjeta de puntuación de verdades de producto e ingeniería. Cada épica debería mejorar el valor medido sin debilitar la honestidad de cobertura acotada, la retención de evidencia crítica, la reproducción determinista o los techos de recursos.

• Transparencia de cobertura: informes más claros para truncamiento, límites de profundidad, finales visitados, espacio de búsqueda omitido y qué se exploró o no.

• Calidad de informes: mejores ubicaciones de origen, rutas de reproducción más cortas, identidades de problemas estables y agrupación más clara de errores de runtime, nudos no visitados y límites de cobertura.

• Aserciones de historia definidas por el autor: reglas de proyecto deterministas como "el oro nunca va negativo", "la salud nunca excede el máximo" o "las variables requeridas se establecen antes de los finales".

• Búsqueda de variables dirigida por objetivos: permitir que autores y agentes busquen estados aprobados mientras se preserva un presupuesto protegido de búsqueda general y un lenguaje exacto de cobertura acotada.

• Asistente de objetivos de IA alojado opcional: una interfaz humana de primera clase, explícitamente habilitada, que ayuda a autores no técnicos a proponer objetivos de variables y aserciones para aprobación, y luego delega toda la ejecución y verificación al motor determinista no-IA de Inkcheck. Los controles de proveedor, consentimiento, compartición de fuentes, retención, costo y desactivación deben ser explícitos; las reglas generadas nunca se confían o aplican silenciosamente.

• Persistencia de reproducción: recordar rutas de fallo conocidas y asegurar que las ejecuciones futuras sigan verificándolas incluso cuando las estrategias de recorrido mejoren.

• Checkpoints de campaña compactos: retener y reanudar fronteras útiles de historias grandes sin que los artefactos de checkpoint dominen la memoria o el disco, y degradar a un informe parcial inmutable antes de los límites de serialización.

• Accesorios de compatibilidad públicos: ejemplos consentidos y casos límite sintéticos para pruebas de regresión, comparaciones de rendimiento y construcción de confianza.

• Preparación para agentes: el benchmark de preparación para agentes ejecutable fija un protocolo sin pistas ocultas, accesorio determinista de runtime/aserción, objetivos de arranque/herramienta/referencia/seguridad/prueba, puntuador de máquina y atribución separada de herramienta/habilidad/modelo/entorno. Dos ejecuciones observacionales que pasen de implementaciones de agentes distintas siguen siendo la puerta de liberación (#67).

• Arnés de promoción de búsqueda: una tarjeta de puntuación amplia y predeclarada entre familias estructurales, presupuestos, profundidades y semillas antes de que cualquier estrategia experimental pueda cambiar el valor por defecto.

• Búsqueda especialista acotada: detectar formas mecánicas y despachar pequeñas sondas expertas para compuertas compuestas, bucles/contadores, elegibilidad de storylet, límites de aserción y diversidad de frontera conductual (#107-#112). Los especialistas ganan expansión a través de valor nuevo de portafolio y retienen trabajo general/de cola larga protegido.

• Controles de rendimiento para historias grandes: preajustes de verificación rápida, estándar y profunda con compensaciones más claras de tiempo/cobertura.

• Verificaciones de lint estructurales: verificaciones opcionales para etiquetas faltantes, esquemas de etiquetas inconsistentes o convenciones de metadatos específicas del proyecto.

Licencia

MIT