data_drain 0.1.19 → 0.2.1

data/docs/execution/archive/v0.2.0.md

@@ -0,0 +1,812 @@
+# Plan de Ejecución — v0.2.0
+
+**Release objetivo:** v0.2.0 — Hardening de seguridad y testing
+**Items del roadmap:** 1, 2, 3, 4 ([ver IMPROVEMENT_PLAN.md](../IMPROVEMENT_PLAN.md#p0--seguridad-y-correctitud-v020))
+**Branch:** `feature/v0.2.0` → mergeado a `main` (commit `e1d121b`)
+**Estado:** ✅ Completado — v0.2.0 release el 2026-04-13
+**Última actualización:** 2026-04-13
+
+---
+
+## Resumen
+
+Este release cierra los gaps P0 de DataDrain: SQL injection en `table_name`, credenciales S3 expuestas, memory leak de conexión DuckDB, y la cobertura de tests insuficiente. Resultado esperado: gema producción-ready para datos sensibles con > 80% line coverage.
+
+**Items del release:**
+
+| Item | Resumen | Estimación |
+|------|---------|-----------|
+| 2 | Validación regex de `table_name`/`primary_key` | 1-2h |
+| 1 | Migrar credenciales S3 a `credential_chain` | 2-4h |
+| 3 | Cleanup conexión DuckDB thread-local (`Record.disconnect!`) | 4-6h |
+| 4 | Cobertura tests P0 (Record, Storage, GlueRunner, Observability, Configuration) | 1-2 días |
+
+**Total estimado:** 2-3 días de trabajo enfocado.
+
+---
+
+## Review de agentes — incorporado
+
+Este plan fue revisado por **opencode/big-pickle** (`v0.2.0.agente-review.md`, 2026-04-13). Los 4 issues + 2 preguntas planteados fueron incorporados:
+
+| Issue / Q | Resolución | Ubicación en este plan |
+|-----------|-----------|----------------------|
+| Issue 1: `aws_region` también necesita escape | `safe_region = escape_sql(region)` antes de heredoc | Fase 3.2 |
+| Issue 2: convención `:integration` tag | Definida con `define_derived_metadata` | Fase 0.4 |
+| Issue 3: aws-sdk-s3 versión | Verificación añadida a Fase 0.1 | Fase 0.1 |
+| Issue 4: orden ParquetFixtures vs spec_helper | Trigger en spec_helper, módulo en support | Fase 5.2 |
+| Q1: caracteres a escapar en DuckDB | Verificación manual en `bin/console` antes de Fase 1 | Fase 0.1 |
+| Q2: callers con `public.table` | `rg` en monorepo Wispro antes de Fase 1 | Fase 0.1 |
+| R1: comentario en spec_helper sobre cleanup | Aplicado a `config.after(:each)` | Fase 0.5 |
+
+---
+
+## Orden de ejecución y dependencias
+
+```
+Fase 0 (setup)
+   │
+   ▼
+Fase 1: Item 2 (validación regex) ──────► sin deps, calienta
+   │
+   ▼
+Fase 2: Setup tests baseline (Configuration, Observability, JsonType, Storage factory)
+   │
+   ├──► Fase 3: Item 1 (S3 secret) + tests Storage::S3
+   │       │
+   │       ▼
+   ├──► Fase 4: Tests Storage::Local + GlueRunner
+   │
+   ▼
+Fase 5: Item 3 (disconnect!) + tests Record
+   │
+   ▼
+Fase 6: Tests Engine + FileIngestor (refuerzo + nuevos casos)
+   │
+   ▼
+Fase 7: Lint + Coverage report + CHANGELOG + version bump + commit final
+```
+
+**Razonamiento del orden:**
+- Item 2 primero: cheap, sin deps, establece patrón de validación + tests.
+- Tests baseline antes de los items grandes: te dan una red para no romper.
+- Item 1 después de tener `storage/s3_spec.rb` esqueleto.
+- Item 3 último porque requiere tests de Record ya escritos para validar idempotencia.
+
+---
+
+## Pre-requisitos (Fase 0)
+
+### 0.1 Verificar entorno
+
+- [ ] `bundle install` corre limpio
+- [ ] `bundle exec rspec` actual pasa (4 tests verdes)
+- [ ] `bundle exec rubocop` actual sin ofensas
+- [ ] DuckDB version en `Gemfile.lock` ≥ 1.4 (para `CREATE SECRET`)
+- [ ] **aws-sdk-s3 ≥ 1.114** (para `Aws::S3::Client.new(stub_responses: true)`):
+  ```bash
+  bundle exec ruby -e "require 'bundler'; puts Bundler.load.specs.find { |s| s.name == 'aws-sdk-s3' }.version"
+  ```
+  Si < 1.114 → bumpear `Gemfile`.
+- [ ] **Q1 resuelta — caracteres a escapar en DuckDB SQL strings.** Probar en `bin/console`:
+  ```ruby
+  conn.query("CREATE OR REPLACE SECRET t (TYPE S3, REGION 'us-east-1''); SELECT 1;--')")
+  # Confirmar si SQL estándar (solo `'` → `''`) es suficiente o si DuckDB tiene reglas extra
+  ```
+  Documentar resultado acá:
+  > Resultado: ___________________
+- [ ] **Q2 resuelta — buscar callers con `public.table` o schema en monorepo Wispro:**
+  ```bash
+  rg "table_name.*[\"']\w+\.\w+" --type ruby
+  rg "DataDrain::Engine.new" -A 5 --type ruby
+  ```
+  Si hay matches con schema explícito → coordinar con Item 2 (relajar regex o forzar split de schema).
+  Documentar:
+  > Callers encontrados con schema: ___________________
+
+### 0.2 Crear branch
+
+- [ ] `git checkout -b feature/v0.2.0`
+
+### 0.3 Agregar SimpleCov
+
+- [ ] Agregar a `Gemfile`:
+  ```ruby
+  group :test do
+    gem "simplecov", require: false
+  end
+  ```
+- [ ] Agregar al inicio de `spec/spec_helper.rb`:
+  ```ruby
+  require "simplecov"
+  SimpleCov.start do
+    add_filter "/spec/"
+    minimum_coverage 80  # falla si baja del 80%
+  end
+  ```
+- [ ] `bundle install`
+- [ ] `bundle exec rspec` y verificar baseline de cobertura actual reportada en `coverage/index.html`
+- [ ] Agregar `coverage/` a `.gitignore` si no está
+- [ ] Commit: `chore: add simplecov for coverage tracking`
+
+### 0.4 Estructura de fixtures
+
+- [ ] Crear `spec/fixtures/`
+- [ ] Crear `spec/fixtures/sample.csv` con 5 filas dummy:
+  ```csv
+  id,timestamp,isp_id,value
+  1,2026-01-01 10:00:00,42,100
+  2,2026-01-02 11:00:00,42,200
+  3,2026-02-01 12:00:00,43,150
+  4,2026-02-15 13:00:00,42,175
+  5,2026-03-01 14:00:00,43,225
+  ```
+- [ ] Decidir si tests integration con Postgres son parte de este release (recomendación: marcar como `:integration` y skip por default en CI; correr a mano)
+- [ ] **Definir convención `:integration` tag** en `spec/spec_helper.rb`:
+  ```ruby
+  RSpec.configure do |config|
+    config.define_derived_metadata(:integration) do |metadata|
+      metadata[:skip] = "Integration test — requiere Postgres real (correr con --tag integration)"
+    end
+  end
+  ```
+  Tests integration se marcan con `it "...", :integration do`. Para correrlos: `bundle exec rspec --tag integration` (requiere remover/sobrescribir el skip; alternativa: usar `metadata[:skip] = !ENV["RUN_INTEGRATION"]` para activar con env var).
+- [ ] Commit: `chore: add test fixtures structure`
+
+### 0.5 Helper de specs
+
+- [ ] Crear `spec/support/` y agregar requires en `spec_helper.rb`:
+  ```ruby
+  Dir[File.expand_path("support/**/*.rb", __dir__)].sort.each { |f| require f }
+  ```
+- [ ] Crear `spec/support/configuration_helper.rb`:
+  ```ruby
+  module ConfigurationHelper
+    def with_config(**overrides)
+      original = DataDrain.configuration
+      DataDrain.configure { |c| overrides.each { |k, v| c.send("#{k}=", v) } }
+      yield
+    ensure
+      DataDrain.instance_variable_set(:@configuration, original)
+      DataDrain::Storage.reset_adapter!
+    end
+  end
+
+  RSpec.configure do |config|
+    config.include ConfigurationHelper
+
+    # Limpia la config global y el adapter cacheado entre tests para evitar leaks
+    # de estado. Tests que escriben archivos al disco deben usar `Dir.mktmpdir` o
+    # un `tmp/test_lake/` descartable; este hook NO los limpia (responsabilidad
+    # del test).
+    config.after(:each) do
+      DataDrain.reset_configuration!
+    end
+  end
+  ```
+- [ ] Commit: `chore: add spec support helpers`
+
+### Checkpoint Fase 0
+
+- [ ] `bundle exec rspec` pasa (4 tests + 0% nuevos)
+- [ ] Coverage report generado
+- [ ] 3 commits limpios en `feature/v0.2.0`
+
+---
+
+## Fase 1 — Item 2: Validación regex (P0)
+
+**Roadmap:** [Item 2](../IMPROVEMENT_PLAN.md#item-2--validación-regex-de-table_name-primary_key-anti-sql-injection)
+
+### 1.1 Implementar validación en Engine
+
+- [ ] Editar `lib/data_drain/engine.rb`:
+  - Agregar constante de clase:
+    ```ruby
+    IDENTIFIER_REGEX = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.freeze
+    ```
+  - En `#initialize`, después de capturar `@table_name` y `@primary_key`:
+    ```ruby
+    validate_identifier!(:table_name, @table_name)
+    validate_identifier!(:primary_key, @primary_key)
+    ```
+  - Agregar método privado:
+    ```ruby
+    def validate_identifier!(name, value)
+      return if IDENTIFIER_REGEX.match?(value.to_s)
+
+      raise DataDrain::ConfigurationError,
+            "#{name} '#{value}' no es un identificador SQL válido"
+    end
+    ```
+
+### 1.2 Implementar validación en FileIngestor
+
+- [ ] Editar `lib/data_drain/file_ingestor.rb`:
+  - Agregar misma constante o referenciar `Engine::IDENTIFIER_REGEX` (mejor: extraer a `DataDrain::Validations` módulo si vamos a tenerla en 2 clases)
+  - **Decisión:** extraer a módulo `lib/data_drain/validations.rb`:
+    ```ruby
+    module DataDrain
+      module Validations
+        IDENTIFIER_REGEX = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.freeze
+
+        module_function
+
+        def validate_identifier!(name, value)
+          return if IDENTIFIER_REGEX.match?(value.to_s)
+
+          raise DataDrain::ConfigurationError,
+                "#{name} '#{value}' no es un identificador SQL válido"
+        end
+      end
+    end
+    ```
+  - Require en `lib/data_drain.rb` después de `errors`
+  - En `Engine#initialize`: `Validations.validate_identifier!(:table_name, @table_name)`
+  - En `FileIngestor#initialize`: `Validations.validate_identifier!(:folder_name, @folder_name)`
+
+### 1.3 Tests
+
+- [ ] Agregar a `spec/data_drain/engine_spec.rb`:
+  ```ruby
+  describe "validación de identificadores" do
+    it "rechaza table_name con punto y coma" do
+      expect {
+        DataDrain::Engine.new(valid_options.merge(table_name: "x; DROP TABLE y"))
+      }.to raise_error(DataDrain::ConfigurationError, /table_name.*no es un identificador/)
+    end
+
+    it "rechaza primary_key con espacios" do
+      expect {
+        DataDrain::Engine.new(valid_options.merge(primary_key: "id desc"))
+      }.to raise_error(DataDrain::ConfigurationError)
+    end
+
+    it "acepta identificador válido con guión bajo y números" do
+      expect {
+        DataDrain::Engine.new(valid_options.merge(table_name: "my_table_2"))
+      }.not_to raise_error
+    end
+  end
+  ```
+- [ ] Crear `spec/data_drain/validations_spec.rb`:
+  ```ruby
+  RSpec.describe DataDrain::Validations do
+    describe ".validate_identifier!" do
+      it "no levanta para identificadores válidos" do
+        %w[users users_v2 _table TableName].each do |id|
+          expect { described_class.validate_identifier!(:x, id) }.not_to raise_error
+        end
+      end
+
+      it "levanta para identificadores inválidos" do
+        %w[1table table-name table.name].push("x; DROP", "").each do |id|
+          expect {
+            described_class.validate_identifier!(:x, id)
+          }.to raise_error(DataDrain::ConfigurationError)
+        end
+      end
+    end
+  end
+  ```
+
+### 1.4 Validación local
+
+- [ ] `bundle exec rspec spec/data_drain/validations_spec.rb spec/data_drain/engine_spec.rb`
+- [ ] `bundle exec rubocop lib/data_drain/validations.rb lib/data_drain/engine.rb lib/data_drain/file_ingestor.rb`
+
+### 1.5 Docs
+
+- [ ] Actualizar `skill/references/antipatrones.md` item 13: agregar "Ahora la gema valida `table_name` y `primary_key` con regex; `select_sql` y `where_clause` siguen siendo trusted (no se validan)".
+- [ ] Actualizar `skill/references/api-detallada.md` con nota sobre validación.
+- [ ] Actualizar `CLAUDE.md` sección "Convenciones críticas" con regla nueva.
+
+### 1.6 Commit
+
+- [ ] `git add lib/data_drain/validations.rb lib/data_drain/engine.rb lib/data_drain/file_ingestor.rb lib/data_drain.rb`
+- [ ] `git add spec/data_drain/validations_spec.rb spec/data_drain/engine_spec.rb`
+- [ ] `git add skill/ CLAUDE.md`
+- [ ] Commit: `feat(security): validar table_name/primary_key con regex (item 2)`
+
+### Checkpoint Fase 1
+
+- [ ] Tests verdes
+- [ ] Rubocop limpio
+- [ ] Coverage no bajó
+- [ ] Identificadores comunes (`users`, `my_table`) siguen funcionando
+
+---
+
+## Fase 2 — Tests baseline
+
+**Roadmap:** [Item 4 — parcial](../IMPROVEMENT_PLAN.md#item-4--cobertura-de-tests-p0-record-storage-gluerunner-observability)
+
+Tests cheap sin dependencias externas. Establecen base de cobertura.
+
+### 2.1 `configuration_spec.rb`
+
+- [ ] Crear `spec/data_drain/configuration_spec.rb`
+- [ ] Tests:
+  - Defaults correctos (`storage_mode == :local`, `batch_size == 5000`, etc.)
+  - `duckdb_connection_string` formato URI con `idle_in_transaction_session_timeout` interpolado
+  - `idle_in_transaction_session_timeout = 0` no se omite (se incluye en URI como `0`)
+- [ ] Validar: `bundle exec rspec spec/data_drain/configuration_spec.rb`
+
+### 2.2 `observability_spec.rb`
+
+- [ ] Crear `spec/data_drain/observability_spec.rb`
+- [ ] Crear clase de test:
+  ```ruby
+  class TestComponent
+    include DataDrain::Observability
+    attr_accessor :logger
+    def emit(level, event, meta = {}); safe_log(level, event, meta); end
+  end
+  ```
+- [ ] Tests:
+  - `safe_log` no-op si `@logger` nil
+  - Formato KV con `component=` `event=` primero
+  - Filtra `password`, `token`, `secret`, `api_key`, `auth` (versión actual; item 9 ampliará)
+  - `rescue StandardError` no propaga (logger que levanta)
+  - `exception_metadata` trunca a 200, escapa `"`
+  - `observability_name` extrae primer namespace en snake_case
+  - Funciona con `extend` (clase con `@logger` de clase)
+- [ ] Validar: `bundle exec rspec spec/data_drain/observability_spec.rb`
+
+### 2.3 `types/json_type_spec.rb`
+
+- [ ] Crear `spec/data_drain/types/json_type_spec.rb`
+- [ ] Tests:
+  - `cast(nil)` → nil
+  - `cast({"a" => 1})` → `{"a" => 1}`
+  - `cast([1,2,3])` → `[1,2,3]`
+  - `cast('{"a":1}')` → `{"a" => 1}`
+  - `cast("not json")` → `"not json"` (no levanta)
+- [ ] Validar
+
+### 2.4 `storage_spec.rb` (factory)
+
+- [ ] Crear `spec/data_drain/storage_spec.rb`
+- [ ] Tests:
+  - `Storage.adapter` con `:local` retorna `Local` instance
+  - `Storage.adapter` con `:s3` retorna `S3` instance
+  - `Storage.adapter` con `:foo` levanta `InvalidAdapterError`
+  - `Storage.adapter` cachea (misma instancia entre llamadas)
+  - `Storage.reset_adapter!` invalida cache
+  - Después de `reset_adapter!`, próxima llamada usa nuevo `storage_mode`
+- [ ] Validar
+
+### 2.5 Commit
+
+- [ ] `git add spec/data_drain/configuration_spec.rb spec/data_drain/observability_spec.rb spec/data_drain/types/ spec/data_drain/storage_spec.rb`
+- [ ] Commit: `test: cobertura baseline (Configuration, Observability, JsonType, Storage factory)`
+
+### Checkpoint Fase 2
+
+- [ ] `bundle exec rspec` corre todos los specs sin error
+- [ ] Coverage report sube ≥ 50%
+- [ ] Tiempo total de suite < 5s
+
+---
+
+## Fase 3 — Item 1: S3 credential_chain (P0)
+
+**Roadmap:** [Item 1](../IMPROVEMENT_PLAN.md#item-1--migrar-credenciales-s3-a-credential_chain-de-duckdb)
+
+### 3.1 Investigación previa
+
+- [ ] Verificar versión DuckDB en uso:
+  ```bash
+  bundle exec ruby -e "require 'duckdb'; puts DuckDB::LIBRARY_VERSION"
+  ```
+  Debe ser ≥ 0.10. Si no, bumpear `Gemfile`.
+- [ ] Probar manualmente `CREATE SECRET` en consola DuckDB:
+  ```bash
+  bin/console
+  > db = DuckDB::Database.open(":memory:"); conn = db.connect
+  > conn.query("INSTALL httpfs; LOAD httpfs;")
+  > conn.query("CREATE SECRET test (TYPE S3, PROVIDER credential_chain, REGION 'us-east-1');")
+  > conn.query("FROM duckdb_secrets();")
+  ```
+- [ ] Si AWS env vars (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) están seteadas, probar listar un bucket de prueba:
+  ```ruby
+  conn.query("FROM read_parquet('s3://your-test-bucket/path/*.parquet') LIMIT 1")
+  ```
+
+### 3.2 Refactor `Storage::S3#setup_duckdb`
+
+- [ ] Editar `lib/data_drain/storage/s3.rb`:
+  ```ruby
+  def setup_duckdb(connection)
+    connection.query("INSTALL httpfs; LOAD httpfs;")
+    create_s3_secret(connection)
+  end
+
+  private
+
+  def create_s3_secret(connection)
+    region = @config.aws_region
+    raise DataDrain::ConfigurationError, "aws_region es obligatorio para storage_mode=:s3" if region.nil?
+
+    safe_region = escape_sql(region)
+
+    if @config.aws_access_key_id && @config.aws_secret_access_key
+      connection.query(<<~SQL)
+        CREATE OR REPLACE SECRET data_drain_s3 (
+          TYPE S3,
+          KEY_ID '#{escape_sql(@config.aws_access_key_id)}',
+          SECRET '#{escape_sql(@config.aws_secret_access_key)}',
+          REGION '#{safe_region}'
+        );
+      SQL
+    else
+      connection.query(<<~SQL)
+        CREATE OR REPLACE SECRET data_drain_s3 (
+          TYPE S3,
+          PROVIDER credential_chain,
+          REGION '#{safe_region}'
+        );
+      SQL
+    end
+  end
+
+  # NOTA: aws_region también pasa por escape_sql (review big-pickle issue 1).
+  # Aunque AWS no permite `'` en region names, defendemos en profundidad.
+  def escape_sql(value)
+    value.to_s.gsub("'", "''")
+  end
+  ```
+
+### 3.3 Tests `storage/s3_spec.rb`
+
+- [ ] Crear `spec/data_drain/storage/s3_spec.rb`
+- [ ] Setup: usar `aws-sdk-s3` con `Aws::S3::Client.new(stub_responses: true)` para `destroy_partitions`
+- [ ] Mockear DuckDB connection (objeto que registra queries):
+  ```ruby
+  let(:duckdb_conn) do
+    queries = []
+    Class.new do
+      define_method(:query) { |q| queries << q }
+      define_method(:queries) { queries }
+    end.new
+  end
+  ```
+- [ ] Tests:
+  - `setup_duckdb` con `aws_access_key_id` seteado → emite `CREATE SECRET ... KEY_ID ... SECRET`
+  - `setup_duckdb` sin credenciales → emite `CREATE SECRET ... PROVIDER credential_chain`
+  - Sin `aws_region` levanta `ConfigurationError`
+  - `escape_sql` duplica comillas simples
+  - `aws_region` con `'` (caso patológico) también se escapa en el `CREATE SECRET` (no rompe SQL)
+  - `build_path` retorna `s3://...`
+  - `destroy_partitions` con stub de S3:
+    - prefix correcto
+    - regex matching
+    - delete_objects llamado en lotes de 1000 cuando hay > 1000
+    - retorna count
+
+### 3.4 Validación local
+
+- [ ] `bundle exec rspec spec/data_drain/storage/s3_spec.rb`
+- [ ] `bundle exec rubocop lib/data_drain/storage/s3.rb`
+
+### 3.5 Docs
+
+- [ ] Actualizar `skill/references/api-detallada.md` sección Storage::S3
+- [ ] Actualizar `skill/SKILL.md` glosario y FAQ (mencionar credential_chain como default)
+- [ ] Actualizar `README.md` sección Configuración: aclarar que `aws_access_key_id`/`aws_secret_access_key` son opcionales si IAM rol o env vars
+- [ ] Actualizar `CLAUDE.md` sección "Seguridad"
+
+### 3.6 Commit
+
+- [ ] `git add lib/data_drain/storage/s3.rb spec/data_drain/storage/s3_spec.rb`
+- [ ] `git add skill/ README.md CLAUDE.md`
+- [ ] Commit: `security(s3): migrar a CREATE SECRET con credential_chain (item 1)`
+
+### Checkpoint Fase 3
+
+- [ ] Tests S3 verdes (mockeados)
+- [ ] Test manual con bucket real (si hay): consulta de un Parquet vía `Record.where`
+- [ ] Coverage sube
+- [ ] Documentado backward-compat
+
+---
+
+## Fase 4 — Tests Storage::Local + GlueRunner
+
+### 4.1 `storage/local_spec.rb`
+
+- [ ] Crear `spec/data_drain/storage/local_spec.rb`
+- [ ] Usar `Dir.mktmpdir` por test para aislamiento
+- [ ] Tests:
+  - `prepare_export_path` crea directorio anidado
+  - `build_path` con/sin `partition_path`
+  - `destroy_partitions` con todas las keys → borra directorio específico
+  - `destroy_partitions` con keys parciales → wildcard glob
+  - `destroy_partitions` retorna count correcto
+  - `destroy_partitions` con pattern que no matchea → retorna 0
+
+### 4.2 `glue_runner_spec.rb`
+
+- [ ] Crear `spec/data_drain/glue_runner_spec.rb`
+- [ ] Usar `Aws::Glue::Client.new(stub_responses: true)` y stubs para `start_job_run`/`get_job_run`
+- [ ] Tests:
+  - SUCCEEDED inmediato → retorna `true`
+  - RUNNING → SUCCEEDED → retorna `true` (test con polling_interval bajísimo o stubear sleep)
+  - FAILED → levanta RuntimeError con mensaje
+  - STOPPED → idem
+  - TIMEOUT → idem
+  - `error_message` truncado a 200 chars + escape de `"`
+  - Logs emitidos: `glue_runner.start`, `glue_runner.polling`, `glue_runner.complete|failed`
+  - **Para evitar sleep real:** stubear `Kernel.sleep` o mover a `class << self; def polling_sleep(s); sleep s; end; end` y stubear
+
+### 4.3 Validación + commit
+
+- [ ] `bundle exec rspec spec/data_drain/storage/local_spec.rb spec/data_drain/glue_runner_spec.rb`
+- [ ] Commit: `test: cobertura Storage::Local y GlueRunner`
+
+### Checkpoint Fase 4
+
+- [ ] Coverage > 70%
+- [ ] Tiempo de suite < 10s
+
+---
+
+## Fase 5 — Item 3: `Record.disconnect!` + tests Record
+
+**Roadmap:** [Item 3](../IMPROVEMENT_PLAN.md#item-3--cleanup-de-conexión-duckdb-thread-local)
+
+### 5.1 Implementar `Record.disconnect!`
+
+- [ ] Editar `lib/data_drain/record.rb`:
+  ```ruby
+  # Cierra la conexión DuckDB del thread actual y limpia Thread.current.
+  # Idempotente: llamarlo varias veces no levanta.
+  #
+  # Útil en middlewares de Sidekiq/Puma para evitar memory leak en threads
+  # de larga vida.
+  #
+  # @return [void]
+  def self.disconnect!
+    entry = Thread.current.delete(:data_drain_duckdb)
+    return unless entry
+
+    entry[:conn]&.close
+    entry[:db]&.close
+  rescue StandardError
+    # silencio en cleanup
+  end
+  ```
+
+### 5.2 Tests `record_spec.rb`
+
+- [ ] Crear `spec/data_drain/record_spec.rb`
+- [ ] Definir clase de test:
+  ```ruby
+  class TestArchived < DataDrain::Record
+    self.bucket = "spec/fixtures"
+    self.folder_name = "test_archive"
+    self.partition_keys = [:year, :month]
+
+    attribute :id, :string
+    attribute :value, :integer
+    attribute :created_at, :datetime
+  end
+  ```
+- [ ] Generar fixtures Parquet en `spec/fixtures/test_archive/year=2026/month=3/data.parquet` usando DuckDB:
+  ```ruby
+  # spec/support/parquet_fixtures.rb
+  module ParquetFixtures
+    def self.generate!
+      path = "spec/fixtures/test_archive"
+      FileUtils.rm_rf(path)
+      db = DuckDB::Database.open(":memory:")
+      conn = db.connect
+      conn.query(<<~SQL)
+        COPY (
+          SELECT 'uuid-1' AS id, 100 AS value, TIMESTAMP '2026-03-01' AS created_at, 2026 AS year, 3 AS month
+          UNION ALL SELECT 'uuid-2', 200, TIMESTAMP '2026-03-15', 2026, 3
+        ) TO '#{path}' (FORMAT PARQUET, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE 1);
+      SQL
+    end
+  end
+  ```
+- [ ] **Orden de carga (review big-pickle issue 4):** `spec/support/*.rb` se carga vía `Dir[...].sort.each` (Fase 0.5) ANTES de los tests, pero el bloque `before(:suite)` que dispara fixtures debe registrarse en el spec_helper, no en el archivo de support. Hacerlo así:
+  ```ruby
+  # spec/spec_helper.rb (al final, después de Dir[...].sort.each)
+  RSpec.configure do |config|
+    config.before(:suite) do
+      ParquetFixtures.generate!  # genera fixtures Parquet
+      # Si hay setup global de DataDrain (configure), va antes de generate!
+    end
+  end
+  ```
+  Razón: si `ParquetFixtures.generate!` se invoca en `support/parquet_fixtures.rb` directamente, se ejecuta en tiempo de `require` (antes de cualquier `before(:suite)` de spec_helper). Manteniendo solo la definición del módulo en `support/` y el trigger en `spec_helper.rb`, garantizamos orden.
+- [ ] Tests:
+  - `.where(year: 2026, month: 3)` retorna 2 instancias
+  - `.where(year: 2026, month: 3, limit: 1)` retorna 1
+  - `.find("uuid-1", year: 2026, month: 3)` retorna instancia con value 100
+  - `.find("nonexistent", year: 2026, month: 3)` retorna nil
+  - `.find("foo' OR 1=1 --", year: 2026, month: 3)` retorna nil (sanitización)
+  - `.where(year: 2099, month: 12)` retorna `[]` (Parquet no existe, no levanta)
+  - `build_query_path` respeta orden `[:year, :month]` aunque kwargs sean `(month: 3, year: 2026)`
+  - `.connection` retorna instancia, segunda llamada en mismo thread retorna misma
+  - `.connection` en thread distinto retorna instancia distinta
+  - `.disconnect!` limpia `Thread.current[:data_drain_duckdb]`
+  - `.disconnect!` llamado dos veces no levanta
+  - Después de `.disconnect!`, `.connection` reabre
+
+### 5.3 Validación
+
+- [ ] `bundle exec rspec spec/data_drain/record_spec.rb`
+- [ ] `bundle exec rubocop lib/data_drain/record.rb`
+
+### 5.4 Docs
+
+- [ ] Actualizar `CLAUDE.md` sección "Conexiones thread-local" con snippet Sidekiq middleware:
+  ```ruby
+  # config/initializers/sidekiq.rb
+  Sidekiq.configure_server do |config|
+    config.server_middleware do |chain|
+      chain.add Class.new {
+        def call(_worker, _job, _queue)
+          yield
+        ensure
+          DataDrain::Record.disconnect!
+        end
+      }
+    end
+  end
+  ```
+- [ ] Actualizar `skill/references/api-detallada.md` sección Record.disconnect!
+- [ ] Actualizar `skill/references/antipatrones.md` item 12 (ahora hay forma correcta de cerrar)
+
+### 5.5 Commit
+
+- [ ] `git add lib/data_drain/record.rb spec/data_drain/record_spec.rb spec/support/parquet_fixtures.rb`
+- [ ] `git add CLAUDE.md skill/`
+- [ ] Commit: `feat(record): agregar Record.disconnect! para cleanup thread-local (item 3)`
+
+### Checkpoint Fase 5
+
+- [ ] Tests Record verdes
+- [ ] Fixtures Parquet generados en `before(:suite)`
+- [ ] Documentación de uso Sidekiq publicada
+
+---
+
+## Fase 6 — Tests Engine + FileIngestor
+
+Refuerzo y expansión de specs existentes.
+
+### 6.1 Engine
+
+- [ ] Revisar `spec/data_drain/engine_spec.rb`. Agregar:
+  - Test `pg_count == 0` → retorna `true` sin export ni purge, log `engine.skip_empty`
+  - Test `skip_export: true` → no llama `export_to_parquet`, sí llama `verify_integrity`
+  - Test `verify_integrity` retorna false → no llama `purge_from_postgres`, retorna false
+  - Test heartbeat: 100 lotes simulados → emite `engine.purge_heartbeat`
+  - Test `throttle_delay > 0` → llama sleep entre lotes (stubear Kernel.sleep)
+  - Test `idle_in_transaction_session_timeout = 0` se setea
+  - Test `idle_in_transaction_session_timeout = nil` no se setea
+
+### 6.2 FileIngestor
+
+- [ ] Revisar `spec/data_drain/file_ingestor_spec.rb`. Agregar:
+  - Test archivo no existe → retorna false, log `file_ingestor.file_not_found`
+  - Test count == 0 → cleanup + retorna true (con `delete_after_upload: true` borra)
+  - Test JSON → usa `read_json_auto`
+  - Test Parquet → usa `read_parquet`
+  - Test extensión no soportada → levanta `DataDrain::Error`
+  - Test `delete_after_upload: false` → archivo no se borra
+
+### 6.3 Validación + commit
+
+- [ ] `bundle exec rspec`
+- [ ] Coverage ≥ 80%
+- [ ] Commit: `test: expandir cobertura Engine y FileIngestor`
+
+### Checkpoint Fase 6
+
+- [ ] Coverage ≥ 80% líneas (criterio del item 4)
+- [ ] Tiempo suite total < 30s
+- [ ] No flakes en 3 corridas seguidas: `for i in 1 2 3; do bundle exec rspec || break; done`
+
+---
+
+## Fase 7 — Release
+
+### 7.1 Lint global
+
+- [ ] `bundle exec rubocop` sin ofensas en archivos modificados
+- [ ] Si rubocop reporta cosas en archivos NO tocados, dejar como están (regla: no flag código no tocado)
+
+### 7.2 Coverage final
+
+- [ ] `bundle exec rspec` y verificar `coverage/index.html`
+- [ ] Anotar % en CHANGELOG
+
+### 7.3 CHANGELOG
+
+- [ ] Editar `CHANGELOG.md`. Agregar al tope:
+  ```markdown
+  ## [0.2.0] - 2026-XX-XX
+
+  ### Security
+  - **BREAKING (preventivo):** `table_name` y `primary_key` se validan contra regex `\A[a-zA-Z_][a-zA-Z0-9_]*\z`. Identificadores con caracteres especiales (puntos, espacios, comillas) ahora levantan `DataDrain::ConfigurationError`. (item 2)
+  - Storage::S3 migra a `CREATE SECRET (TYPE S3, PROVIDER credential_chain)`. Si `aws_access_key_id`/`aws_secret_access_key` están seteados, se mantiene comportamiento explícito; si no, usa AWS credential chain (IAM roles, env vars, ~/.aws/credentials). (item 1)
+
+  ### Features
+  - `Record.disconnect!` cierra y limpia la conexión DuckDB thread-local. Recomendado en middlewares Sidekiq/Puma para evitar memory leak. Idempotente. (item 3)
+
+  ### Tests
+  - Cobertura 4 specs → ~XX specs (Record, Storage::Local, Storage::S3, GlueRunner, Observability, Configuration, JsonType, Validations).
+  - Cobertura líneas: ~XX% (medida con SimpleCov, mínimo 80%).
+  ```
+- [ ] Reemplazar fecha y porcentajes reales
+
+### 7.4 Bump de versión
+
+- [ ] Editar `lib/data_drain/version.rb`: `VERSION = "0.2.0"`
+- [ ] `bundle install` (actualiza Gemfile.lock)
+
+### 7.5 Skill regenerada
+
+- [ ] Invocar `skill-builder` en modo completo para regenerar `skill/` con cambios:
+  ```
+  Modo: completo (gem-release lo dispara automáticamente)
+  ```
+  O ejecutar manualmente actualizaciones de `skill/SKILL.md` y `references/`.
+
+### 7.6 Commit final del release
+
+- [ ] `git add CHANGELOG.md lib/data_drain/version.rb Gemfile.lock skill/`
+- [ ] Commit: `chore: release v0.2.0 — hardening de seguridad y testing`
+
+### 7.7 Tag y push
+
+- [ ] `git tag v0.2.0`
+- [ ] `git push origin feature/v0.2.0`
+- [ ] `git push origin v0.2.0`
+- [ ] Crear PR a `main` (vía `gh pr create`) con cuerpo basado en CHANGELOG
+
+### 7.8 Post-merge
+
+- [ ] Mergear PR
+- [ ] Si aplica: invocar skill `gem-release` para empaquetar
+- [ ] Actualizar `docs/IMPROVEMENT_PLAN.md` marcando items 1, 2, 3, 4 como `[x]`
+- [ ] Mover este plan a `docs/execution/archive/v0.2.0.md`
+
+---
+
+## Validación final del release
+
+- [ ] Tests verdes en CI (cuando exista, item 14) o local
+- [ ] Coverage ≥ 80%
+- [ ] Rubocop sin ofensas
+- [ ] CHANGELOG completo
+- [ ] Version bumped
+- [ ] Tag creado
+- [ ] PR mergeado
+- [ ] Items 1-4 marcados `[x]` en roadmap
+
+---
+
+## Plan B: si algún item se atasca
+
+| Si... | Entonces... |
+|-------|-------------|
+| Item 1 (S3 secret) requiere DuckDB > 1.4 | Bumpear `Gemfile` o documentar y postergar a v0.3.0 |
+| Tests Record requieren Postgres real | Marcar como `:integration`, skip en suite default |
+| Tests con `Aws::S3::Client.stub_responses` no soportan `list_objects_v2` paginado | Usar `WebMock` con respuestas XML reales de S3 |
+| Coverage no llega a 80% | Bajar umbral a 70% en este release, item 4 sigue abierto en v0.2.1 |
+| Rubocop versión actual reporta nuevas ofensas en código tocado | Fix puntual o `# rubocop:disable` con razón en comentario |
+
+---
+
+## Notas para el agente que ejecuta
+
+- **Cada commit debe ser autocontenido y atómico.** Si un cambio rompe tests, no commit.
+- **Antes de commit, correr `rspec` Y `rubocop`** para los archivos tocados.
+- **No crear archivos no listados** sin pedir confirmación al usuario.
+- **Si surge bloqueo, marcar el subtask como `[!]` y consultar al usuario** antes de tomar shortcut.
+- **No saltarse fases.** El orden está pensado para minimizar riesgo y maximizar cobertura.