docs(0133): MIGRATION.md + growth log placeholder + drift fix
- modules/data_table/MIGRATION.md: porting guide + release checklist 1.0.0-stable
- data_table.md: growth log entry commented for post-gate bump
- data_table.md: fix error_type Go remnant ("error_go_core" -> "") in C++ module
- cpp/CMakeLists.txt: SQLite3 optional dep for data_table_bench (cross-windows)
- agent_cleanup_worktree.go: !windows build tag (uses unix-only syscalls)
- dev/issues/0133-cpp-data-table-10m-rows.md: issue tracking
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,148 @@
|
||||
# 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`.
|
||||
@@ -43,7 +43,7 @@ uses_types:
|
||||
- ColorRule_cpp_core
|
||||
returns: []
|
||||
returns_optional: false
|
||||
error_type: "error_go_core"
|
||||
error_type: ""
|
||||
imports:
|
||||
- imgui.h
|
||||
- app_base.h
|
||||
@@ -261,6 +261,10 @@ No hay tests unitarios directos: `render()` requiere ImGui + ImPlot context acti
|
||||
|
||||
## Capability growth log
|
||||
|
||||
<!-- ANADIR CUANDO PASE EL GATE 0133:
|
||||
v1.0.0-stable (YYYY-MM-DD) — finalize: columnar snapshot + string interning + lazy filter/sort + display cache + OpenMP compute. Bench 10M rows >=60fps. API publica frozen: render(), TableInput, State, TableEvent, ColumnSpec, ColorRule no admiten breaking changes sin major bump. Ver MIGRATION.md para contratos exactos.
|
||||
-->
|
||||
|
||||
v1.1.0 (2026-05-15) — declarative CellRenderer (Badge/Progress/Duration/Icon) via TableInput.column_specs sidecar. Back-compat preservado: apps existentes sin column_specs siguen funcionando sin cambios.
|
||||
|
||||
v1.2.0 (2026-05-15) — Button renderer + event sink (ButtonClick/RowDoubleClick/RowRightClick) + tooltip per cell + column_specs persisted in TQL (aux_column_specs roundtrip). Back-compat preserved: events_out=nullptr by default; existing render() callers unchanged.
|
||||
|
||||
Reference in New Issue
Block a user