fn_registry/dev/issues/0107e-version-pinning-codegen.md

id, title, status, type, domain, scope, priority, depends, blocks, related, created, updated, tags

id	title	status	type	domain	scope	priority	depends	blocks	related	created	updated	tags
0107e	uses_modules con min_version + codegen fail-loud	pendiente	feature	meta cpp-stack tooling	registry	media	0107a		0107	2026-05-17	2026-05-17	modules versioning codegen fail-loud

0107e — Version pinning + codegen fail-loud

Parte del issue principal 0107.

Objetivo

Permitir que app.md declare version minima del modulo y que el codegen falle ruidosamente si:

1. Modulo declarado en uses_modules tiene version < min_version.
2. Python3 no disponible y uses_modules no vacio.
3. Codegen produce count = 0 cuando uses_modules declara N>0 modulos.

Schema extendido app.md::uses_modules

# Forma corta (back-compat, sin pinning):
uses_modules: [data_table_cpp]

# Forma larga (con pinning):
uses_modules:
  - name: data_table_cpp
    min_version: "1.4"        # SemVer minor — acepta 1.4.x, 1.5.x, ..., NO 2.0.0
  - name: chat_ia_cpp
    min_version: "0.1"

# Mixed permitido:
uses_modules:
  - data_table_cpp           # sin pin
  - name: framework_cpp      # con pin
    min_version: "1.1"

Reglas:

• min_version formato MAJOR.MINOR (no patch — patch siempre bug fix compatible).
• Comparacion: module.md::version >= min_version AND module.md::version.major == min_version.major. Esto previene saltos de major silenciosos.

Tareas

• 5.1 python/functions/infra/codegen_app_modules.py: parser acepta string corto Y dict largo.
• 5.2 Codegen lee module.md::version y compara contra min_version declarado en uses_modules. Si falla → exit 3 con mensaje claro.
• 5.3 cpp/CMakeLists.txt::add_imgui_app: si codegen exit != 0 AND != 2 → message(FATAL_ERROR ...) (no WARNING como hoy).
• 5.4 Si Python3 NO encontrado AND app.md tiene uses_modules no vacio → message(FATAL_ERROR "Python3 required to parse uses_modules; install python3.").
• 5.5 Si codegen devuelve count=0 cuando uses_modules declara N>0 → message(FATAL_ERROR ...) con apunta a la app.md.
• 5.6 Indexer registry/parser.go: parsea ambas formas y persiste en apps.uses_modules_json con shape canonico [{name, min_version}] (min_version null si no declarado).
• 5.7 Test: app sintetica con dict largo + modulo sintetico con version 1.3 y min_version 1.4 → cmake configure falla con mensaje esperado.
• 5.8 Migrar 7 apps consumidoras de data_table a usar dict largo con min_version: "1.4" (o lo que sea v actual cuando 0107e cierre).

Mensajes de error esperados

CMake Error at cpp/CMakeLists.txt:289 (message):
  codegen_app_modules failed for services_monitor: module 'data_table_cpp'
  version 1.3.0 does not satisfy min_version 1.4 declared in
  apps/services_monitor/app.md::uses_modules.

  Either bump module version (via /version) or relax pin in app.md.

CMake Error at cpp/CMakeLists.txt:289 (message):
  codegen_app_modules: app 'dag_engine_ui' declares uses_modules: [data_table_cpp]
  but generated module manifest has count=0.

  Likely cause: Python parser failed silently. Re-run with verbose:
    python3 python/functions/infra/codegen_app_modules.py \
      --app-md apps/dag_engine_ui/app.md \
      --modules-root modules/ \
      --app-name dag_engine_ui \
      --out /tmp/test.cpp

Riesgos

• Apps existentes sin pinning rompen?: NO. La forma corta sigue valida y trata min_version como null = sin chequeo. Solo apps que opten explicitamente reciben gate.
• Build se vuelve ruidoso si modulo no se actualizo: deliberado. Es el sentido del fail-loud.