Especificación abierta · Versión 1
QZX Result Contract v1
Un envoltorio JSON pequeño y extensible que permite a agentes de IA, automatizaciones y personas determinar si un comando tuvo éxito, comprender el resultado y conservar evidencia específica sin adivinar columnas ni analizar prosa.
Creado y mantenido por Alejandro Sánchez como una especificación abierta de QZX.
success ni message.Núcleo estable
Dos campos en los que todo consumidor puede confiar
success· booleanotrueúnicamente cuando la operación solicitada terminó correctamente.message· texto no vacío- Un resumen humano completo, no una etiqueta que obligue a realizar otra consulta.
Evidencia extensible
Cada tipo de comando conserva los hechos que necesita
Una búsqueda de archivos, una consulta DNS, una inspección de disco y una operación de procesos no deberían fingir que comparten los mismos campos de dominio. Los productores pueden añadir datos tipados, details, warnings y meta. Los consumidores deben ignorar los campos que no comprendan.
Núcleo independiente del transporte
Legible para una persona y confiable para software
El contrato central es independiente de CLI, MCP, HTTP o una biblioteca. QZX añade su propio perfil JSON para CLI: con --json, escribe un documento contractual completo en stdout y envía el progreso o la salida incidental de herramientas nativas a stderr.
- Los fallos incluyen
erroro unerror_codeestable; los resultados exitosos no contienen ninguno de esos campos de fallo. - Los campos opcionales definidos conservan su tipo declarado cuando aparecen; los campos no disponibles se omiten en vez de usar
null. meta.schema_versionidentifica el envoltorio común cuando existe metadata.- Los campos adicionales desconocidos siguen siendo válidos, permitiendo evolución aditiva.
- La compatibilidad contractual no implica autorización, sandbox ni soporte universal de plataformas.
{
"success": true,
"message": "Current local date and time returned in ISO 8601 format.",
"output": "2026-08-07T21:45:00-05:00",
"meta": {
"command": "getCurrentDateTime",
"duration_ms": 2.4,
"schema_version": 1
}
}Adopción sin dependencia
Otras herramientas pueden implementar la forma del resultado sin adoptar los comandos QZX
El contrato separa transporte y vocabulario de operaciones. Una CLI local, servidor MCP, herramienta de build o wrapper interno puede emitir un resultado compatible con QZX y conservar sus propios nombres y campos de dominio.
1 · Producir
Emitir el núcleo
Devuelve success explícito, un message útil y evidencia verdadera del dominio.
2 · Validar
Usar el esquema
Valida JSON guardado o canalizado con el esquema descargable o el validador QZX sin dependencias.
3 · Informar
Publicar evidencia
Comparte límites, resultados de conformidad y desviaciones, sin afirmar certificaciones inexistentes.
Kit de conformidad · Evidencia lista para CI
Convierte un éxito y un fallo en una evidencia revisable
QZX incluye un validador de evidencia sin dependencias y una Composite Action reutilizable para GitHub. El validador comprueba que el archivo de éxito realmente declare success: true, que el de fallo declare success: false, aplica el perfil central o MCP elegido y genera una evidencia JSON determinista con los SHA-256 de los archivos exactos evaluados.
La Action ejecuta la misma prueba en el repositorio adoptante, hace fallar CI cuando no hay conformidad, restringe las rutas de evidencia y del informe a GITHUB_WORKSPACE y escribe un resumen PASS/FAIL. El propio CI de QZX ejercita los perfiles central y MCP con CPython 3.13.
Cada receipt se autoidentifica con el schema público QZX Result Contract Conformance Receipt v1. Cualquier implementación de JSON Schema 2020-12 puede validar así la estructura del informe sin ejecutar QZX. Una receipt válida según el schema puede registrar success: false; la validez estructural y la conformidad de la implementación son deliberadamente afirmaciones separadas.
Usar el validador de QZX es opcional: el contrato puede implementarse con cualquier validador independiente de JSON Schema o del perfil. Para evidencia pública durable, fija la Action al SHA exacto del commit QZX que probaste.
Un comando de evidencia
python scripts/validate_result_contract_evidence.py \
--profile mcp-2025-11-25 \
--success evidence/success.json \
--failure evidence/failure.json \
--tool-definition evidence/tool-definition.json \
--report evidence/qzx-conformance.json- Entradas
- Éxito y fallo completados reales; definición de la herramienta MCP cuando aplique ese perfil.
- Evidencia
- Perfil, hallazgos del validador,
output_schema_modede MCP, roles semánticos y SHA-256 de la evidencia exacta. - Límite de la afirmación
- Evidencia de conformidad solamente: no certifica seguridad, corrección del dominio ni aval de QZX.
Interoperabilidad MCP · 2025-06-18 → 2026-07-28
Adopta el contrato de resultados sin reemplazar — ni actualizar — MCP
MCP admite outputSchema, structuredContent e isError para herramientas desde la especificación 2025-06-18. Por eso QZX ofrece perfiles específicos para 2025-06-18, 2025-11-25 y 2026-07-28, en vez de obligar a un productor compatible a actualizar toda su pila MCP sólo para probar un contrato de resultados.
Una herramienta conserva su nombre, entradas, permisos, transporte y campos de dominio. QZX registra si la relación de su outputSchema es una referencia canónica, el schema exacto inline, una composición allOf o la forma más débil y portable entre SDKs structural_core. La receipt expone esa diferencia en vez de ocultarla detrás de un simple indicador verde.
Un cliente que entiende MCP ya dispone de isError. QZX mantiene success dentro del resultado estructurado por otra razón: el resultado sigue describiendo por sí mismo su desenlace cuando se registra, cachea, encola, almacena, prueba o reutiliza fuera de su wrapper MCP original. Dentro de MCP no hay dos fuentes de verdad: el estado efectivo de error MCP en un resultado completado debe ser igual a !success. MCP interpreta un isError ausente como false, por lo que un éxito puede omitir el campo y un fallo debe seguir emitiendo isError: true.
MCP 2026-07-28 exige además resultType: "complete" para un resultado completado. Los perfiles de 2025 deliberadamente no inventan ese campo.
Mapeo determinista
outputSchema- Schema canónico de QZX cuando el SDK lo permite; de lo contrario, un núcleo estructural restringido cuya relación más débil queda registrada en la receipt.
structuredContent- El objeto completo de resultado QZX, validado contra Result Contract v1.
isError- En resultados completos, el estado efectivo debe ser igual a
!success; el campo sólo puede omitirse cuando ese valor efectivo seafalse. resultType- Obligatorio como
completeen el perfil 2026-07-28; no es requisito en los perfiles de 2025. - Errores de protocolo MCP / JSON-RPC
- Siguen siendo errores del protocolo; no se fabrica un resultado QZX completado.
Validar sin otra dependencia
El repositorio fuente incluye un validador que lee un archivo o stdin:
qzx getCurrentDateTime --output-format iso --json \
| python scripts/validate_result_contract.py -
python scripts/validate_result_contract.py result.json --jsonEl runtime de QZX valida su propio envoltorio final antes de imprimirlo. Un productor interno inválido se reemplaza por un fallo conforme invalid_result_contract.
La versión 1 evoluciona de forma aditiva
Los nuevos campos opcionales, códigos de error y perfiles de transporte son compatibles cuando conservan la semántica central. Eliminar un campo obligatorio, cambiar el significado o tipo de success o message, o cambiar la raíz para que deje de ser un objeto JSON por resultado completado exige una nueva versión contractual.
“Compatible con QZX Result Contract v1” describe una forma de resultado. No implica aval, paridad de comandos, ejecución segura ni permiso para presentar otro producto como QZX.
Revisión pública y pilotos empresariales
Ayuda a comprobar si este contrato merece una adopción más amplia
Alejandro recibe implementaciones independientes, revisiones de interoperabilidad, pilotos reales con agentes y trabajo público de conformidad patrocinado. El apoyo económico puede financiar pruebas y documentación, pero nunca control privado del contrato abierto ni resultados favorables garantizados.