# 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**:
   ```cpp
   // 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**:
   ```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:
   ```bash
   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**:
   ```bash
   /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**:
   ```bash
   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`.