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.
Un documento en stdout
Legible para una persona y confiable para software
QZX imprime un mensaje humano breve de forma predeterminada. 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. 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.
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 y códigos de error son compatibles. Eliminar un campo obligatorio, cambiar el significado o tipo de success o message, o permitir varios documentos en stdout 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.