Proyecto: SDK y CLI con compatibilidad verificada

← SE-119 — Taller: empaquetar una capacidad reusable · ↑ Parte 09 · 📚 Índice completo · 🌐 Portal · SE-121 — Problemas, síntomas, necesidades y oportunidades →

Punto profesional y fundamento pedagógico

Punto profesional. La clase existe para entregar SDK y CLI con contrato común y compatibilidad verificada entre versiones.

Por qué aparece aquí. Se sitúa después de Taller: empaquetar una capacidad reusable y antes de la clase siguiente: convierte el conocimiento anterior en una decisión observable que la clase siguiente podrá reutilizar. La continuidad se comprueba en el artefacto, no por compartir vocabulario.

Error conceptual que debe corregir. Duplicar lógica entre interfaces o declarar compatibilidad sin consumidor anterior.

Secuencia de aprendizaje. Antes de leer la solución, el estudiante predice el resultado del caso normal y del error conceptual anterior. Luego explica un caso resuelto paso a paso, construye un contraejemplo que cambie la decisión y, sin consultar el texto, reconstruye el mecanismo y lo aplica a una entrada nueva. La secuencia usa predicción, explicación propia, contraste y recuperación. ICAP distingue participación de construcción de conocimiento; How People Learn II exige conectar conocimiento previo, contexto y transferencia; la práctica de recuperación respalda producir de nuevo la explicación tras una demora; y Education for Life and Work exige devolución que explique la causa del error.

Evidencia de aprendizaje. Matriz de versiones, artefactos, consumidor de regresión, CLI, SDK y changelog. Debe contener predicción previa, observación, explicación causal, contraejemplo, criterio de aceptación y una nota de qué dato haría cambiar la conclusión.

Límite de la conclusión. La matriz cubre versiones y plataformas declaradas, no compatibilidad universal.

Trazabilidad fuente → afirmación

Antes de empezar

Esta clase continúa el producto reutilizable con SDK y CLI de la Parte 09. Recupera la evidencia de la clase anterior, añade una decisión propia de Proyecto: SDK y CLI con compatibilidad verificada y deja un artefacto que la clase siguiente deberá consumir. La pregunta activa es: ¿Qué conjunto mínimo de artefactos y pruebas sostiene un SDK y CLI listos para consumidores reales?

Prerrequisitos

• Haber completado la clase anterior o reconstruir su contrato y evidencia.
• Python 3.11 o posterior, terminal, editor y Git; un segundo runtime es opcional y debe declararse.
• Trabajar con fixtures sintéticos: ninguna observación necesita datos de una persona o sistema real.

Problema auténtico

El producto reutilizable con SDK y CLI debe cerrar la etapa de programación con un release candidato: API, CLI, plugin de ejemplo, build reproducible dentro del alcance y compatibilidad entre versión anterior y nueva.

Objetivos observables

Al terminar podrás explicar los cinco mecanismos de esta clase, predecir su comportamiento antes de ejecutar, construir un caso normal y uno límite, diagnosticar el fallo controlado, comparar una alternativa y entregar evidencia que otra persona pueda reproducir.

Mapa conceptual

flowchart LR
    N1[Contrato multicapa] --> N2[Matriz de compatibilidad] --> N3[Release candidate] --> N4[Supply chain mínima] --> N5[Aceptación desde el consumidor]
    N5 -->|fallo o cambio| N1

El mapa se lee como una cadena de razonamiento, no como fases obligatorias del runtime. La flecha de retorno indica que un fallo o cambio de requisito obliga a revisar el modelo inicial; no autoriza a parchear solo la última salida.

Temas y por qué importan

Conceptos y decisiones

1. Contrato multicapa

El proyecto publica API Python, CLI y protocolo de plugin con versiones y errores alineados. Cada capa tiene consumidores y compatibilidad propias. Un documento enumera superficie pública para impedir que el equipo clasifique cambios después de romper.

2. Matriz de compatibilidad

Se prueba runtime mínimo/máximo, instalación desde wheel/sdist, consumidor anterior con release nuevo y plugin compatible/incompatible. Una matriz verde respalda solo combinaciones ejecutadas; las demás se marcan no verificadas.

3. Release candidate

El RC usa artefactos inmutables, changelog, hashes y guía de migración. Se instala exactamente el artefacto que se pretende publicar. Si cambia un byte tras la prueba, se genera otro prerelease.

4. Supply chain mínima

Dependencias y licencias se inventarían, fuentes se fijan según política y se genera metadata de procedencia/SBOM disponible. Esto no equivale a una cadena de suministro completa, pero hace visibles componentes y decisiones.

5. Aceptación desde el consumidor

Una persona nueva sigue quickstart, ejecuta caso, interpreta error, instala plugin y migra. Tiempo y bloqueos se registran. El cierre incluye problemas conocidos y ruta de rollback, no solo una demo feliz.

Definiciones de trabajo

• contrato multicapa: el proyecto publica api python, cli y protocolo de plugin con versiones y errores alineados.
• matriz de compatibilidad: se prueba runtime mínimo/máximo, instalación desde wheel/sdist, consumidor anterior con release nuevo y plugin compatible/incompatible.
• release candidate: el rc usa artefactos inmutables, changelog, hashes y guía de migración.
• supply chain mínima: dependencias y licencias se inventarían, fuentes se fijan según política y se genera metadata de procedencia/sbom disponible.
• aceptación desde el consumidor: una persona nueva sigue quickstart, ejecuta caso, interpreta error, instala plugin y migra.

Las definiciones son operativas para el producto reutilizable con SDK y CLI. No convierten términos con historia más amplia en sinónimos y deben contrastarse con la documentación primaria enlazada al final.

Ejemplo mínimo

python -m unittest -v
python -m build
python tools/verify_artifacts.py dist/
python tools/compat.py --old 1.4.2 --candidate 1.5.0-rc.1
engineering_sdk self-check --redact

Antes de ejecutar, predice estado, resultado y error. Después registra versión, comando y salida. Si el fragmento es pseudocódigo o pertenece a otro lenguaje, etiquétalo como tal y no afirmes que fue ejecutado.

Ejemplo profesional

En el producto reutilizable con SDK y CLI, un release contiene contrato público, artefactos inmutables, dependencias, procedencia, ejemplos, errores y ruta de migración. La implementación de esta clase debe conservar ese contrato aunque cambie la forma interna. El caso profesional no pregunta únicamente si produce una salida: pregunta quién puede producirla, qué estado observa, cómo falla y qué rastro permite disputar una decisión incorrecta.

Compara el caso normal con autorización falsa, evidencia incompleta, empate y repetición. Un mecanismo es apropiado cuando esas diferencias quedan visibles y localizadas; es peligroso cuando dependen de orden accidental, estado oculto o una convención que el consumidor no puede conocer.

Práctica guiada

1. Copia el contrato de entrada y salida antes de escribir implementación.
2. Predice el caso normal y un límite; identifica la invariante que no puede romperse.
3. Implementa la versión mínima sin I/O dentro del núcleo.
4. Ejecuta el caso y conserva comando, versión y salida bajo evidence/.
5. Introduce el fallo controlado, reduce la reproducción y formula dos hipótesis rivales.
6. Corrige la causa, añade regresión y ejecuta el conjunto completo.
7. Compara con otro paradigma o lenguaje indicando qué semántica se preserva.

Ejercicios

1. Lectura: dibuja una traza de cinco pasos y marca dónde cambia estado o control.
2. Construcción: añade una capacidad pública y prueba el comportamiento desde un proyecto consumidor.
3. Frontera: cubre vacío, empate, no autorizado e inválido con resultados distintos.
4. Contraste: reescribe una pieza con otro modelo y explica una mejora y una pérdida.

Reto verificable

Entrega implementación, fixtures, pruebas y un informe corto. Se aprueba si otra persona ejecuta desde checkout limpio, obtiene los mismos resultados y puede relacionar cada rama o transformación con una regla del dominio. No se aprueba por cantidad de archivos ni por usar la sintaxis característica del paradigma.

Caso conductor

El producto reutilizable con SDK y CLI empaqueta el motor de la biblioteca de estructuras y algoritmos como engineering_sdk, expone choose_next, una CLI y un punto de extensión. Ejecuta instalación limpia, entrada válida, configuración ausente, plugin incompatible y actualización entre dos versiones. Cambia después una sola regla o condición y revisa qué archivos, pruebas y trazas debieron modificarse. Esa superficie de cambio alimenta el proyecto final de la parte.

Preguntas frecuentes

¿Una técnica o herramienta determina toda la arquitectura?

No. Puede organizar un núcleo o una frontera sin dominar el sistema completo. Combinar técnicas es válido si las fronteras preservan identidad, orden, errores y evidencia.

¿Más automatización o menos líneas significan una solución mejor?

No. La brevedad puede quitar duplicación o esconder decisiones. Se evalúan semántica, diagnóstico, costo de cambio y adecuación a la carga.

¿Debo instalar todas las herramientas mencionadas?

No. Instala solo lo necesario para la práctica elegida. Registra versión y comandos; si solo analizas una notación o salida, decláralo como análisis no ejecutado.

Fallo controlado y diagnóstico

Las pruebas usan fuente local mientras el RC omite entry point. Ejecuta toda aceptación desde artefactos en un workspace consumidor vacío y compara hashes antes de publicar.

Registra síntoma, entrada mínima, hipótesis, observación que descarta cada hipótesis, causa, corrección y prueba de regresión. No cambies simultáneamente implementación, fixture y expectativa.

Errores comunes y cómo corregirlos

Entorno y archivos clave

work/SE-120/
├── README.md
├── engineering_sdk/
│   ├── domain.py
│   └── se_120.py
├── fixtures/cases.json
├── tests/test_se_120.py
└── evidence/diagnosis.md

El README declara plataforma, runtimes, comandos, limpieza y límites. Evita dependencias externas cuando la biblioteca estándar permita observar el mecanismo; si agregas una, fija procedencia y versión.

Seguridad, ética y accesibilidad

• la autorización forma parte del dominio y no se infiere por ausencia de rechazo;
• no uses eval, reglas descargadas ni serialización insegura;
• limita colas, recursión, tamaño de entrada y tiempo de evaluación;
• redacta trazas y conserva una explicación textual además de color o animación;
• una recomendación automatizada debe poder revisarse, impugnarse y corregirse;
• respeta licencias de ejemplos y atribuye adaptaciones.

Transferencia

Traslada un fixture al segundo modelo, herramienta, plataforma o lenguaje. Compara representación de ausencia, error, mutabilidad, orden y cancelación. La transferencia está lograda cuando el contrato se conserva y las diferencias están explicadas, no cuando la interfaz se parece.

Evaluación y evidencia

Fuentes

• Semantic Versioning 2.0.0 — Api pública, versiones, prereleases y compatibilidad declarada; autoridad: Semantic Versioning project.
• Python Packaging User Guide: Specifications — Metadata, nombres, versiones, dependencias y artefactos de distribución; autoridad: Python Packaging Authority.
• pylock.toml Specification — Lock files para instalaciones reproducibles y selección por entorno; autoridad: Python Packaging Authority.
• Python Standard Library — Argparse, importlib.metadata, subprocess y apis de automatización; autoridad: Python Software Foundation.
• SPDX Specification 3.0 — Identificadores, sbom y procedencia legible por máquinas; autoridad: Linux Foundation.
• REUSE Specification — Declaración inequívoca y verificable de copyright y licencias por archivo; autoridad: Free Software Foundation Europe.

Cada fuente respalda el mecanismo indicado; ninguna demuestra que la implementación del producto reutilizable con SDK y CLI sea correcta. Esa afirmación depende de fixtures, pruebas, trazas y revisión reproducible.

Límites y siguiente paso

El proyecto acredita un release candidato dentro de su matriz, no disponibilidad, seguridad o soporte productivo. La Parte 10 cambiará el foco desde construir correctamente hacia descubrir qué problema y resultado de producto justifican la siguiente inversión.

Glosario

• contrato multicapa: el proyecto publica api python, cli y protocolo de plugin con versiones y errores alineados.
• matriz de compatibilidad: se prueba runtime mínimo/máximo, instalación desde wheel/sdist, consumidor anterior con release nuevo y plugin compatible/incompatible.
• release candidate: el rc usa artefactos inmutables, changelog, hashes y guía de migración.
• supply chain mínima: dependencias y licencias se inventarían, fuentes se fijan según política y se genera metadata de procedencia/sbom disponible.
• aceptación desde el consumidor: una persona nueva sigue quickstart, ejecuta caso, interpreta error, instala plugin y migra.

← SE-119 — Taller: empaquetar una capacidad reusable · ↑ Parte 09 · 📚 Índice completo · 🌐 Portal · SE-121 — Problemas, síntomas, necesidades y oportunidades →