fn_registry/modules/data_table/MIGRATION.md

data_table MIGRATION guide

Referencia para apps que migran a v1.0.0 estable del modulo data_table. La version de modulo (module.md) es semver independiente del entrypoint (data_table.md). Este documento cubre el salto al hito de estabilidad 1.0.0, no versiones intermedias.

---

v2.x → estabilidad 1.0.0 (pendiente gate 0133)

What changed (internals — no API change)

Las optimizaciones planificadas en issue 0133 son transparentes para el caller. La API publica (data_table.h) no cambia.

Cambio interno	Impacto en caller
Columnar snapshot interno (agente B)	Ninguno. TableInput.cells sigue siendo row-major caller-owned.
String interning de celdas en snapshot	Ninguno. Misma interfaz de lectura. Strings siguen viviendo en el caller.
Lazy visible_rows (filter + sort diferidos)	Ninguno. render() sigue siendo una sola llamada por frame.
Display cache per-cell	Ninguno. La cache es opaca al caller.
OpenMP en compute (agente A bench gate)	Ninguno. Threading interno, thread-safety invariante: llamar solo desde el main thread de ImGui.

What you must do

Nada, si usas la API publica.

• data_table::render(id, tables, st, events_out, show_chrome) — firma identica.
• TableInput, State, TableEvent, ColumnSpec, ColorRule — sin cambios de layout.
• Back-compat overload render(id, tables, st, show_chrome) — sigue compilando.

Casos especificos:

Situacion	Accion
Guardabas punteros a TableInput.cells entre frames	Sigue valido. El caller es dueno de cells; el modulo no lo mueve ni libera.
Usabas data_table_internal.h directamente	Rebuild obligatorio. El header es privado del modulo — si lo incluias, estabas fuera del contrato. No se garantiza estabilidad de UiState ni de los helpers internos.
Enlazan fn_table_viz (target antiguo)	Reemplazar por fn_module_data_table. El target fn_table_viz fue deprecado en v1.4.0 (2026-05-16).

Behavior contracts preserved

Estos contratos estan FROZEN en v1.0.0 y no pueden romperse sin major version bump:

• Bit-identical rendering: misma entrada → misma salida visual (excepto antialiasing de ImGui).
• TableEvent.row indexa TableInput: los indices de fila en eventos (ButtonClick, RowDoubleClick, RowRightClick) referencian la tabla de entrada original, no el snapshot interno ni la vista filtrada.
• stats_last_cells pointer-identity sentinel: el campo State::stats_last_cells se usa internamente para detectar cambio de datos. Si el caller pasa el mismo puntero cells en frames consecutivos, el modulo reutiliza la cache de stats. Cambiar el puntero (aunque el contenido sea igual) invalida la cache — comportamiento documentado y frozen.
• events_out solo hace push_back: render() nunca llama clear() ni resize() sobre el vector del caller. El caller limpia antes de cada frame si no quiere acumulacion.
• show_chrome = true por defecto: el overload de back-compat sin show_chrome pasa true.
• State es caller-managed: el modulo no alloca ni libera el State. El caller lo destruye cuando quiere.

New (optional, v1.0.0+)

(placeholder — se documentaran aqui las features opt-in que lleguen post-gate)

---

Backwards compatibility policy

La API publica de data_table::render, TableInput, State, TableEvent, ColumnSpec y ColorRule esta FROZEN en v1.0.0.

• Breaking changes (cambiar firma, quitar campo, cambiar semántica de parametro existente) requieren major version bump y un periodo de coexistencia con el path anterior.
• Additive changes (nuevo campo en struct con default sensato, nuevo overload, nuevo CellRenderer enum value) son minor — consumidores existentes no necesitan cambios.
• Bugfixes y optimizaciones internas son patch — sin cambio de contrato.

Apps consumidoras que solo usen #include "data_table/data_table.h" y #include "core/data_table_types.h" no necesitan cambios en minor y patch bumps.

---

Porting desde el playground (pre-registry)

Si tu app usaba el playground original (cpp/apps/primitives_gallery/playground/tables/data_table.h):

1. Cambiar include path:

   // Antes
   #include "tables/data_table.h"
   #include "tables/data_table_types.h"
   
   // Despues
   #include "data_table/data_table.h"
   #include "core/data_table_types.h"
   

2. Cambiar target CMake:

   # Antes
   target_link_libraries(mi_app PRIVATE fn_table_viz)
   
   # Despues
   target_link_libraries(mi_app PRIVATE fn_module_data_table)
   

3. app.md: declarar uses_modules: [data_table_cpp] en lugar de listar funciones miembro individualmente.

4. Namespace identico: data_table::render, data_table::State, data_table::TableInput — sin cambios.

5. data_table_logic.h eliminado: los helpers internos del playground (row_to_tsv, drill, view_mode, etc.) eran privados. En el modulo son static en data_table.cpp. Si los necesitabas externamente, estan fuera del contrato — contactar para evaluar si deben promoverse al registry.

---

Release checklist (gate 0133 — NO ejecutar hasta A+B listos)

Pasos exactos para ejecutar cuando agentes A y B completen su trabajo:

1. Bench gate: data_table_bench --rows 10000000 debe reportar fps_p1 >= 60. El agente A construye el bench; esta metrica es el prerequisito de estabilidad.

2. fn doctor clean: fn doctor cpp-apps debe pasar sin nuevos CANDIDATE (tablas inline sin migrar en apps consumidoras). Indica que todos los consumidores usan el modulo correctamente.

3. Build 11 consumidores: compilar los 11 apps que linkean fn_module_data_table sin errores ni warnings nuevos. Verificar con:

   cd cpp/build && cmake --build . --target \
     registry_dashboard kanban dag_engine_ui services_monitor \
     graph_explorer chart_demo 2>&1 | grep -E "error:|warning:"
   

   (ajustar lista de targets segun fn doctor cpp-apps output)

4. Version bump:

   /version modules/data_table minor "estable 1.0.0 + columnar + 10M rows"
   

   Esto bumpa el campo version: en module.md (actualmente 2.1.0) a 3.0.0 (major bump porque el modulo alcanza estabilidad contractual) o al numero que corresponda segun la politica semver del proyecto en ese momento.

   Nota: data_table.md tiene version 1.5.0 (entrypoint). module.md tiene 2.1.0 (modulo). El bump de "estabilidad 1.0.0" es un hito de politica — el numero exacto lo decide el operador segun cual de los dos .md es la fuente de verdad para el semver del modulo.

5. Tag stable: en module.md frontmatter, anadir tags: [stable] al array existente [tables, viz, ui, imgui, tql, cpp].

6. Capability growth log: descomentar la entrada preparada en data_table.md (ver seccion al final del archivo), rellenando la fecha real YYYY-MM-DD.

7. Push + tag git:

   git add modules/data_table/module.md modules/data_table/data_table.md
   git commit -m "feat(data_table): stable 1.0.0 — columnar + 10M rows gate passed"
   git tag data_table/v1.0.0
   git push && git push --tags
   

---

Inconsistencias detectadas en doc actual

Las siguientes inconsistencias fueron detectadas durante la preparacion de este documento. No bloquean el gate pero conviene resolver antes del bump:

1. Version drift entre los dos .md: data_table.md tiene version: 1.5.0 y module.md tiene version: 2.1.0. Son versionados independientemente pero no esta documentado explicitamente cual es la "version publica" del modulo. Recomendacion: clarificar en module.md que su version es la del modulo como unidad y data_table.md es la del entrypoint como funcion del registry.

2. error_type: "error_go_core" en data_table.md: la funcion es C++ pura (no retorna error de Go). El campo error_type del frontmatter parece heredado del template Go. No afecta el comportamiento pero es semanticamente incorrecto para un entrypoint C++.

3. tests array en data_table.md apunta a cpp/tests/test_column_specs.cpp pero la documentacion dice "No hay tests unitarios directos". Los tests listados son del harness de compilacion (cpp/tests/), no del entrypoint en si. Aclarar en ## Notas que el test_file_path referencia tests de compilacion/link, no tests de render.

4. llm_anthropic_cpp_core en module.md uses_functions pero data_table.md no lo lista (stub interno). Alinear: si el stub es interno al modulo, deberia estar en members, no en uses_functions.