data_drain 0.2.2 → 0.3.1

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

@@ -0,0 +1,1111 @@
+# Plan de Ejecución — v0.3.0
+
+**Release objetivo:** v0.3.0 — Refactor y observabilidad avanzada
+**Items del roadmap:** 10, 20, 5, 11b, 6 ([ver IMPROVEMENT_PLAN.md](../IMPROVEMENT_PLAN.md))
+**Branch sugerido:** `feature/v0.3.0`
+**Base:** `main` (contiene v0.2.2)
+**Estado:** No iniciado
+**Última actualización:** 2026-04-15
+
+---
+
+## Contexto
+
+v0.2.x cerró P0 (seguridad + testing) e P1 cheap (validaciones + timeout Glue + filtros + docs PG). v0.3.0 se enfoca en **refactor del path crítico (`Engine#call`)** para desbloquear features que lo extienden (VACUUM, warning purga lenta) sin reintroducir complejidad ciclomática. Incluye también el sandboxing final de DuckDB.
+
+**Items:**
+
+| Item | Resumen | Estimación | Tipo |
+|------|---------|------------|------|
+| 10 | Refactor `Engine#call` (CC=13 → ~5) | 4-6h | `refactor` |
+| 20 | Limpiar `rubocop:disable` en `lib/` agregados en v0.2.0 | 3-4h | `refactor` |
+| 5 | `vacuum_after_purge` opcional post-purga | 3-4h | `feat` `perf` |
+| 11b | Warning runtime de purga lenta sin avance | 3-4h | `feat` `perf` |
+| 6 | Sandboxing de `Record.connection` | 2-3h | `security` |
+
+**Total estimado:** 15-21h, 2-3 días enfocados.
+
+**Breaking:** ninguno (refactor interno + features opt-in).
+
+**Excluidos intencionalmente** (se mueven a v0.3.1):
+- Items 12-19, 22-24 (calidad/DX/CI)
+- Mejoras de tests y YARD coverage
+
+---
+
+## Review de agentes — incorporado
+
+Revisión por **big-pickle** 2026-04-15 (`docs/execution/v0.3.0-OBSERVACIONES.md`). 6 observaciones + 4 preguntas abiertas, todas incorporadas:
+
+| Obs | Severidad | Resolución | Ubicación |
+|-----|-----------|-----------|-----------|
+| 1: Dependencia Item 10 → 20 tight | Media | Checkpoint explícito de entrada validando API de `@durations`/`timed`/`purge_loop` | Fase 2.0 |
+| 2: `purge_loop` no retorna `total_deleted` | **Alta** | Refactor explícito en sub-step 1.3 antes de avanzar a item 5 | Fase 1.3 + 1.4 |
+| 3: Timecop require/return duplicado | Baja | Centralizado `require "timecop"` + `Timecop.return` en `spec_helper.rb` | Fase 0.3 |
+| 4: Bug en `vacuum_if_needed` (rescue sin `dead_before`) | Media | `engine.vacuum_error` incluye `dead_tuples_before` y `duration_s` parcial | Fase 3.2 + test 3.3 |
+| 5: `lock_configuration` + S3 ambiguo | Media | Investigación prescriptiva con 3 tests en `bin/console` pre-implementación | Fase 5.1 |
+| 6: CC post-Fase 1 no se reconfirma | Baja | Checkpoint 2.0 valida CC ≤ 5 antes de refactor FileIngestor | Fase 2.0 |
+
+**Respuestas a preguntas abiertas:**
+
+1. **¿`lock_configuration` + S3 es real o teórico?** — TBD. Fase 5.1 lo descarta o confirma antes de implementar.
+2. **Scope fallback si el timeline se estira** — priorizar en orden: 10 > 20 > 5 > 11b > 6. Si se corta, parar en 5 (VACUUM es el feature más solicitado).
+3. **Tests integration A (mocks) o B (`:integration` tagged)?** — Opción A. Mantiene consistencia con suite actual (CI DuckDB-only).
+4. **Coordinación con Gemini** — no trabaja en paralelo actualmente en esta gema. Si aparece, revisar `feedback_gemini_collaboration.md` (source= duplicado, orden de campos, include vs extend).
+
+---
+
+## Orden de ejecución y dependencias
+
+```
+Fase 0: setup branch + baseline
+   │
+   ▼
+Fase 1: Item 10 (refactor Engine#call) ──► FUNDACIÓN
+   │                                         extrae step_count, step_export,
+   │                                         step_verify, step_purge, timed helper
+   ▼
+Fase 2: Item 20 (cleanup rubocop:disable) ──► follow-up natural de 10
+   │                                         engine/file_ingestor/record/s3
+   ▼
+Fase 3: Item 5 (VACUUM post-purga) ──────────► extiende step_purge
+   │                                            nuevo evento engine.vacuum_complete
+   ▼
+Fase 4: Item 11b (warning purga lenta) ──────► extiende step_purge loop
+   │                                            Timecop por riesgo 3 big-pickle
+   ▼
+Fase 5: Item 6 (sandboxing Record) ──────────► isolated
+   │                                            SET lock_configuration=true
+   ▼
+Fase 6: Release (CHANGELOG, version bump, tag)
+```
+
+**Razonamiento:**
+- Item 10 primero: establece `step_*` + `timed`. Items 5 y 11b se apoyan en `step_purge` extraído.
+- Item 20 inmediato después: aprovecha contexto fresco del refactor para limpiar disables. Evita acumular deuda visible.
+- Item 5 y 11b en serie: ambos tocan purge path, mejor secuenciales para simplificar tests.
+- Item 6 al final: isolated en `Record`, no bloquea nada.
+
+---
+
+## Pre-requisitos (Fase 0)
+
+### 0.1 Verificar entorno
+
+- [ ] `git checkout main && git pull`
+- [ ] Versión actual en `lib/data_drain/version.rb` = `"0.2.2"`
+- [ ] `bundle exec rspec` pasa (~113 specs, coverage ≥ 80%)
+- [ ] `bundle exec rubocop lib/` sin ofensas
+- [ ] CI verde en main (Ruby 3.4.4)
+
+### 0.2 Crear branch
+
+- [ ] `git checkout -b feature/v0.3.0`
+
+### 0.3 Agregar Timecop al Gemfile + centralizar en spec_helper (item 11b)
+
+Big-pickle señaló en review de v0.2.2 (ClickUp 86b9dka0c) que el mock directo de `Process.clock_gettime` puede ser flakey. Para item 11b (que depende intensamente de timing) usar Timecop como primary tool.
+
+**Observación 3 de big-pickle:** centralizar el `require "timecop"` y `Timecop.return` en `spec_helper.rb` para evitar setup duplicado y flakes por estado residual entre tests.
+
+- [ ] Agregar al `Gemfile`:
+  ```ruby
+  group :test do
+    gem "simplecov", require: false
+    gem "timecop", require: false
+  end
+  ```
+- [ ] `bundle install`
+- [ ] Editar `spec/spec_helper.rb`, agregar:
+  ```ruby
+  require "timecop"
+
+  RSpec.configure do |config|
+    config.after(:each) do
+      Timecop.return  # garantiza reset entre tests, aunque el test falle
+    end
+  end
+  ```
+- [ ] Tests de item 11b usan `Timecop.travel(...)` directo sin `require "timecop"` local ni `Timecop.return` manual — el helper global lo hace.
+- [ ] Commit: `chore: add timecop, centralizar en spec_helper (item 11b)`
+
+### 0.4 Decidir política de tests integration
+
+Items 5 y 11b se benefician de tests contra Postgres real. Decidir antes de arrancar:
+
+- [ ] **Opción A (recomendada):** mockear todo (PG::Connection + PG::Result), usar mocks elaborados. Pros: CI sigue en DuckDB-only. Contras: tests frágiles vs comportamiento real PG.
+- [ ] **Opción B:** marcar tests con `:integration`, skipear por default (ya hay convención del plan v0.2.2), correr manualmente o con Postgres service container en CI.
+
+Si se elige B:
+- [ ] Verificar que `spec/spec_helper.rb` tenga la convención `:integration` (según v0.2.2 Fase 0.4).
+- [ ] Documentar en README sección "Contribuir" cómo correr tests integration.
+
+**Decisión propuesta:** A (mocks). Mantiene consistencia con suite actual.
+
+### Checkpoint Fase 0
+
+- [ ] Branch creado
+- [ ] Timecop disponible
+- [ ] Política de tests integration definida
+- [ ] Baseline verde
+
+---
+
+## Fase 1 — Item 10: Refactor `Engine#call` (CC=13 → ~5)
+
+**Roadmap:** [Item 10](../IMPROVEMENT_PLAN.md#item-10--refactor-enginecall-cc13--5)
+
+### Contexto
+
+`Engine#call` tiene CC=13 (alta). Mezcla setup, conteo, export condicional, verify, purge y logging granular. Difícil de testear en aislamiento. `rubocop:disable Metrics/ClassLength, AbcSize, MethodLength` es workaround.
+
+**Objetivo:** extraer `step_count`, `step_export`, `step_verify`, `step_purge` como métodos privados con timing acumulado en `@durations` hash. `#call` queda como pipeline lineal CC≤5.
+
+### 1.1 Refactor estructural
+
+- [ ] Editar `lib/data_drain/engine.rb`. Reemplazar `#call` actual por:
+  ```ruby
+  def call
+    @durations = {}
+    start_time = monotonic
+    log_start
+
+    setup_duckdb
+    return skip_empty(start_time) if step_count.zero?
+
+    step_export unless @skip_export
+    return integrity_failed(start_time) unless step_verify
+
+    step_purge
+    log_complete(start_time)
+    true
+  end
+  ```
+
+- [ ] Agregar métodos privados:
+  ```ruby
+  # @api private
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  # @api private
+  def timed(step_name)
+    t = monotonic
+    result = yield
+    @durations[step_name] = monotonic - t
+    result
+  end
+
+  # @api private
+  def log_start
+    safe_log(:info, "engine.start",
+             { table: @table_name, start_date: @start_date.to_date, end_date: @end_date.to_date })
+  end
+
+  # @api private
+  def step_count
+    @pg_count = timed(:db_query) { get_postgres_count }
+    @pg_count
+  end
+
+  # @api private
+  def skip_empty(start_time)
+    duration = monotonic - start_time
+    safe_log(:info, "engine.skip_empty", {
+      table: @table_name,
+      duration_s: duration.round(2),
+      db_query_duration_s: @durations.fetch(:db_query, 0).round(2)
+    })
+    true
+  end
+
+  # @api private
+  def step_export
+    safe_log(:info, "engine.export_start", { table: @table_name, count: @pg_count })
+    timed(:export) { export_to_parquet }
+  end
+
+  # @api private
+  def step_verify
+    timed(:integrity) { verify_integrity }
+  end
+
+  # @api private
+  def step_purge
+    timed(:purge) { purge_from_postgres }
+  end
+
+  # @api private
+  def log_complete(start_time)
+    duration = monotonic - start_time
+    safe_log(:info, "engine.complete", {
+      table: @table_name,
+      duration_s: duration.round(2),
+      db_query_duration_s: @durations.fetch(:db_query, 0).round(2),
+      export_duration_s: @durations.fetch(:export, 0).round(2),
+      integrity_duration_s: @durations.fetch(:integrity, 0).round(2),
+      purge_duration_s: @durations.fetch(:purge, 0).round(2),
+      count: @pg_count
+    })
+  end
+
+  # @api private
+  def integrity_failed(start_time)
+    duration = monotonic - start_time
+    safe_log(:error, "engine.integrity_error", {
+      table: @table_name,
+      duration_s: duration.round(2),
+      count: @pg_count
+    })
+    false
+  end
+  ```
+
+- [ ] Quitar el `# rubocop:disable Metrics/ClassLength, Metrics/AbcSize, Metrics/MethodLength, Naming/AccessorMethodName` de arriba de la clase.
+- [ ] Mantener `export_to_parquet`, `verify_integrity`, `purge_from_postgres`, `base_where_sql`, `setup_duckdb`, `get_postgres_count` tal cual (ya son privados y testeados).
+
+### 1.2 Validación de equivalencia
+
+**Critical:** los eventos emitidos deben ser idénticos en campos, orden y valores al comportamiento anterior de v0.2.2.
+
+- [ ] Crear test de equivalencia que capture todos los logs emitidos en un flujo happy path y compare con snapshot conocido:
+  ```ruby
+  # spec/data_drain/engine_refactor_spec.rb
+  RSpec.describe DataDrain::Engine, "refactor step extraction" do
+    # ... setup mocks ...
+
+    it "emite los mismos eventos en el mismo orden que v0.2.2" do
+      expected_events = %w[
+        engine.start
+        engine.export_start
+        engine.integrity_check
+        engine.purge_start
+        engine.complete
+      ]
+
+      emitted = capture_events { engine.call }
+      expect(emitted.map { |e| e[:event] }).to eq(expected_events)
+    end
+
+    it "engine.complete incluye todas las métricas granulares" do
+      event = capture_events { engine.call }.last
+      expect(event[:fields]).to include(
+        :duration_s, :db_query_duration_s, :export_duration_s,
+        :integrity_duration_s, :purge_duration_s, :count
+      )
+    end
+  end
+  ```
+
+### 1.3 Refactor explícito de `purge_from_postgres` para retornar `total_deleted`
+
+**Observación 2 de big-pickle (ALTA):** el `purge_from_postgres` actual (v0.2.2) NO retorna `total_deleted` — el loop termina con `break if count.zero?` que retorna `nil`. Esto bloquea a Fase 3 (item 5) que necesita el valor.
+
+**Acción:** refactorizar como sub-step explícito aquí, no diferirlo.
+
+- [ ] En `lib/data_drain/engine.rb`, `purge_from_postgres`:
+  - Extraer el loop interno a método privado `purge_loop(conn) → Integer`:
+    ```ruby
+    # @api private
+    # @param conn [PG::Connection]
+    # @return [Integer] total de filas borradas
+    def purge_loop(conn)
+      batches_processed = 0
+      total_deleted = 0
+
+      loop do
+        sql = build_delete_sql
+        result = conn.exec(sql)
+        count = result.cmd_tuples
+        break if count.zero?
+
+        batches_processed += 1
+        total_deleted += count
+
+        emit_heartbeat_if_due(batches_processed, total_deleted)
+        sleep(@config.throttle_delay) if @config.throttle_delay.positive?
+      end
+
+      total_deleted
+    end
+
+    # @api private
+    def emit_heartbeat_if_due(batches_processed, total_deleted)
+      return unless (batches_processed % 100).zero?
+
+      safe_log(:info, "engine.purge_heartbeat", {
+        table: @table_name,
+        batches_processed_count: batches_processed,
+        rows_deleted_count: total_deleted
+      })
+    end
+
+    # @api private
+    def build_delete_sql
+      <<~SQL
+        DELETE FROM #{@table_name}
+        WHERE #{@primary_key} IN (
+          SELECT #{@primary_key} FROM #{@table_name}
+          WHERE #{base_where_sql}
+          LIMIT #{@config.batch_size}
+        )
+      SQL
+    end
+    ```
+  - `purge_from_postgres` queda como orquestador:
+    ```ruby
+    def purge_from_postgres
+      safe_log(:info, "engine.purge_start", { table: @table_name, batch_size: @config.batch_size })
+      conn = open_pg_connection
+      apply_session_timeout(conn)
+
+      purge_loop(conn)  # retorna total_deleted (se usa en Fase 3 item 5)
+    ensure
+      conn&.close
+    end
+    ```
+
+### 1.4 Test de equivalencia para `purge_loop`
+
+- [ ] Agregar en `spec/data_drain/engine_spec.rb`:
+  ```ruby
+  describe "#purge_loop (refactor)" do
+    it "retorna total_deleted (suma de cmd_tuples por lote)" do
+      allow(mock_pg_result).to receive(:cmd_tuples).and_return(100, 50, 0)
+      allow(mock_pg_conn).to receive(:exec).with(/DELETE/).and_return(mock_pg_result)
+
+      engine.send(:setup_for_purge)  # helper si es necesario
+      total = engine.send(:purge_loop, mock_pg_conn)
+      expect(total).to eq(150)
+    end
+  end
+  ```
+
+### 1.5 Validación rubocop
+
+- [ ] `bundle exec rubocop lib/data_drain/engine.rb` — sin ofensas, sin disables.
+- [ ] CC de `#call` ≤ 5 (medido con `rubocop --only Metrics/CyclomaticComplexity lib/data_drain/engine.rb`).
+- [ ] CC de `#purge_from_postgres` también ≤ 5 tras extracción.
+
+### 1.6 Commit
+
+- [ ] `git add lib/data_drain/engine.rb spec/data_drain/engine_spec.rb spec/data_drain/engine_refactor_spec.rb`
+- [ ] Commit: `refactor(engine): extraer step_* + purge_loop retorna total_deleted (item 10)`
+
+### Checkpoint Fase 1
+
+- [ ] CC de `Engine#call` ≤ 5
+- [ ] `rubocop:disable` eliminado de `engine.rb`
+- [ ] Eventos emitidos idénticos (test de equivalencia pasa)
+- [ ] Tests existentes siguen pasando sin cambios
+- [ ] Coverage no bajó
+
+---
+
+## Fase 2 — Item 20: Limpiar `rubocop:disable` restantes en `lib/`
+
+**Roadmap:** [Item 20](../IMPROVEMENT_PLAN.md#item-20--limpiar-rubocopdisable-en-lib-agregados-en-v020)
+
+### 2.0 Checkpoint de entrada (observaciones 1 y 6 big-pickle)
+
+**No arrancar Fase 2 sin confirmar estos invariantes de Fase 1:**
+
+- [ ] CC real de `Engine#call` ≤ 5. Verificar:
+  ```bash
+  bundle exec rubocop --only Metrics/CyclomaticComplexity lib/data_drain/engine.rb
+  ```
+  Si CC salió > 5 en la práctica (ej. 7-8), detener y ajustar Fase 1 antes de avanzar.
+- [ ] API de `@durations` hash confirmada con keys: `:db_query`, `:export`, `:integrity`, `:purge`.
+- [ ] API de `timed(step_name)` confirmada:
+  ```ruby
+  timed(:db_query) { yield_result }
+  # ejecuta yield, mide monotonic, guarda @durations[:db_query] = duration, retorna yield_result
+  ```
+- [ ] `purge_loop` retorna `total_deleted` (Integer).
+
+Si alguno falla → volver a Fase 1 y ajustar. El refactor de FileIngestor depende de esta API.
+
+### Contexto
+
+v0.2.0 agregó `rubocop:disable` en 4 archivos. Engine ya limpio tras Fase 1. Faltan:
+- `lib/data_drain/file_ingestor.rb`: `Metrics/AbcSize, CyclomaticComplexity, PerceivedComplexity, MethodLength`
+- `lib/data_drain/record.rb`: `Metrics/AbcSize, MethodLength`
+- `lib/data_drain/storage/s3.rb`: `Metrics/AbcSize, CyclomaticComplexity, MethodLength`
+
+### 2.1 FileIngestor#call refactor
+
+Similar a Engine#call, extraer `step_validate_file`, `step_count_source`, `step_export`, `step_cleanup` (nombres tentativos) y `timed` helper reutilizable.
+
+- [ ] Considerar extraer `timed` a mixin o módulo si Engine y FileIngestor lo comparten (evita duplicación). Opciones:
+  - **Opción A:** `include Observability::Timing` con `timed` + `monotonic` como métodos compartidos.
+  - **Opción B:** dejar `timed` duplicado en cada clase. Simple pero DRY violation.
+  - **Opción C:** extraer a `DataDrain::Timing` módulo puro (no mixin).
+
+  **Decisión propuesta:** A. Ya hay precedente con `Observability`.
+
+- [ ] Crear `lib/data_drain/observability/timing.rb`:
+  ```ruby
+  module DataDrain
+    module Observability
+      module Timing
+        private
+
+        def monotonic
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        def timed(step_name)
+          t = monotonic
+          result = yield
+          @durations ||= {}
+          @durations[step_name] = monotonic - t
+          result
+        end
+      end
+    end
+  end
+  ```
+
+- [ ] En `Engine` y `FileIngestor`: `include Observability::Timing`. Quitar definiciones locales.
+
+- [ ] Refactor `FileIngestor#call` análogo a Engine. Dividir en step_* methods.
+
+### 2.2 Record refactor
+
+- [ ] `Record#execute_and_instantiate` tiene `Metrics/AbcSize, MethodLength`. Revisar si se puede simplificar con guard clause:
+  ```ruby
+  def execute_and_instantiate(sql, columns)
+    @logger = DataDrain.configuration.logger
+    result = connection.query(sql)
+    result.map { |row| new(columns.zip(row).to_h) }
+  rescue DuckDB::Error => e
+    safe_log(:warn, "record.parquet_not_found", exception_metadata(e))
+    []
+  end
+  ```
+  (Mueve el `begin/rescue` al nivel del método con `rescue` pendiente. Más limpio.)
+- [ ] Quitar `rubocop:disable` de `record.rb`.
+
+### 2.3 Storage::S3 refactor
+
+- [ ] `Storage::S3#destroy_partitions` tiene AbcSize/CyclomaticComplexity. Extraer:
+  - `build_destroy_pattern(partition_keys, partitions)` → regex + prefix
+  - `collect_matching_objects(client, bucket, prefix, pattern_regex)` → array
+- [ ] Resultado: `#destroy_partitions` queda como pipeline de 3 llamados.
+- [ ] Quitar `rubocop:disable` de `s3.rb`.
+
+### 2.4 Validación global
+
+- [ ] `bundle exec rubocop lib/` — 0 ofensas, 0 disables `Metrics/*` en todo el `lib/`.
+- [ ] `grep -r "rubocop:disable Metrics" lib/` retorna vacío.
+- [ ] `bundle exec rspec` verde.
+- [ ] Coverage estable o sube.
+
+### 2.5 Commits (granulares)
+
+- [ ] `refactor(observability): extraer Timing mixin (item 20)`
+- [ ] `refactor(file_ingestor): extraer step_* methods (item 20)`
+- [ ] `refactor(record): guard clause en execute_and_instantiate (item 20)`
+- [ ] `refactor(storage/s3): extraer build_destroy_pattern + collect_matching_objects (item 20)`
+
+### Checkpoint Fase 2
+
+- [ ] 0 `rubocop:disable Metrics/*` en `lib/`
+- [ ] Tests verdes
+- [ ] Coverage estable
+- [ ] `Observability::Timing` reusable
+
+---
+
+## Fase 3 — Item 5: `vacuum_after_purge` opcional
+
+**Roadmap:** [Item 5](../IMPROVEMENT_PLAN.md#item-5--vacuum-analyze-opcional-post-purga)
+
+### Contexto
+
+Purgar millones de rows deja dead tuples. Sin VACUUM, el espacio no se libera y seq scans recorren páginas vacías. Agregar opción `config.vacuum_after_purge = false` (default).
+
+**Importante:** VACUUM NO se puede ejecutar dentro de transacción. Debe correr con autocommit. La conexión `PG.connect` de `purge_from_postgres` está en autocommit por default, así que OK.
+
+### 3.1 Agregar opción a Configuration
+
+- [ ] Editar `lib/data_drain/configuration.rb`:
+  ```ruby
+  attr_accessor :storage_mode, :aws_region,
+                :aws_access_key_id, :aws_secret_access_key,
+                :db_host, :db_port, :db_user, :db_pass, :db_name,
+                :batch_size, :throttle_delay, :logger, :limit_ram, :tmp_directory,
+                :idle_in_transaction_session_timeout,
+                :vacuum_after_purge  # ← NUEVO
+
+  def initialize
+    # ... existente ...
+    @vacuum_after_purge = false  # ← default opt-in
+  end
+  ```
+
+### 3.2 Implementar VACUUM en Engine
+
+- [ ] En `lib/data_drain/engine.rb`, extender `purge_from_postgres` (ya refactorizado por Fase 1). Dentro del `ensure` actual, antes de `conn&.close`:
+  ```ruby
+  def purge_from_postgres
+    safe_log(:info, "engine.purge_start", { table: @table_name, batch_size: @config.batch_size })
+    conn = open_pg_connection
+    apply_session_timeout(conn)
+
+    total_deleted = purge_loop(conn)
+
+    vacuum_if_needed(conn, total_deleted)
+  ensure
+    conn&.close
+  end
+
+  private
+
+  # @api private
+  #
+  # Bug fix observación 4 big-pickle: dead_before debe estar disponible en el
+  # rescue para poder reportarlo con el error. Se mide ANTES del begin pero
+  # se incluye tanto en complete como en error.
+  def vacuum_if_needed(conn, total_deleted)
+    return unless @config.vacuum_after_purge
+    return if total_deleted.zero?
+
+    vacuum_start = monotonic
+    dead_before = fetch_dead_tuple_count(conn)
+
+    begin
+      conn.exec("VACUUM ANALYZE #{@table_name};")
+    rescue PG::Error => e
+      safe_log(:warn, "engine.vacuum_error", {
+        table: @table_name,
+        dead_tuples_before: dead_before,
+        rows_deleted_count: total_deleted,
+        duration_s: (monotonic - vacuum_start).round(2)
+      }.merge(exception_metadata(e)))
+      return
+    end
+
+    dead_after = fetch_dead_tuple_count(conn)
+    vacuum_duration = monotonic - vacuum_start
+
+    safe_log(:info, "engine.vacuum_complete", {
+      table: @table_name,
+      duration_s: vacuum_duration.round(2),
+      dead_tuples_before: dead_before,
+      dead_tuples_after: dead_after,
+      rows_deleted_count: total_deleted
+    })
+  end
+
+  # @api private
+  def fetch_dead_tuple_count(conn)
+    result = conn.exec_params(
+      "SELECT n_dead_tup FROM pg_stat_user_tables WHERE relname = $1",
+      [@table_name]
+    )
+    result.first&.dig("n_dead_tup")&.to_i || 0
+  rescue PG::Error
+    -1  # -1 señala "no se pudo medir"
+  end
+  ```
+
+- [ ] Nota: `purge_loop` debe retornar `total_deleted`. Refactorizar si no lo hace.
+
+### 3.3 Tests
+
+- [ ] Agregar a `spec/data_drain/engine_spec.rb`:
+  ```ruby
+  describe "VACUUM post-purge" do
+    it "no ejecuta VACUUM cuando vacuum_after_purge es false (default)" do
+      engine = described_class.new(base_options.merge(table_name: "versions"))
+      # ... mocks ...
+      expect(mock_pg_conn).not_to receive(:exec).with(/VACUUM/)
+      engine.call
+    end
+
+    it "ejecuta VACUUM ANALYZE cuando vacuum_after_purge es true y total_deleted > 0" do
+      DataDrain.configure { |c| c.vacuum_after_purge = true }
+      engine = described_class.new(base_options.merge(table_name: "versions"))
+      # ... mocks para que purge borre 100 rows ...
+      expect(mock_pg_conn).to receive(:exec).with(/VACUUM ANALYZE versions/)
+      # ... mock pg_stat_user_tables ...
+      engine.call
+    end
+
+    it "no ejecuta VACUUM si total_deleted es 0" do
+      DataDrain.configure { |c| c.vacuum_after_purge = true }
+      # ... mocks con cmd_tuples = 0 desde el primer lote ...
+      expect(mock_pg_conn).not_to receive(:exec).with(/VACUUM/)
+    end
+
+    it "emite engine.vacuum_complete con dead_tuples_before/after" do
+      # ... verifica log con fields correctos ...
+    end
+
+    it "captura PG::Error y loguea engine.vacuum_error sin levantar" do
+      DataDrain.configure { |c| c.vacuum_after_purge = true }
+      allow(mock_pg_conn).to receive(:exec).with(/VACUUM/)
+        .and_raise(PG::Error, "lock timeout")
+      expect(engine.call).to be true
+      # ... verifica log warning ...
+    end
+
+    # Observación 4 big-pickle: dead_before ya estaba medido cuando VACUUM falla
+    it "engine.vacuum_error incluye dead_tuples_before y rows_deleted_count" do
+      DataDrain.configure { |c| c.vacuum_after_purge = true }
+      # mock fetch_dead_tuple_count → 500 (pre-VACUUM)
+      # mock VACUUM → raise PG::Error
+      logs = capture_logs { engine.call }
+      error_log = logs.find { |l| l.include?("engine.vacuum_error") }
+      expect(error_log).to include("dead_tuples_before=500")
+      expect(error_log).to include("rows_deleted_count=")
+    end
+  end
+  ```
+
+### 3.4 Docs
+
+- [ ] `skill/references/eventos-telemetria.md` — agregar `engine.vacuum_complete` y `engine.vacuum_error`.
+- [ ] `skill/references/api-detallada.md` — Configuration table: agregar `vacuum_after_purge` (Boolean, default `false`).
+- [ ] `skill/references/postgres-tuning.md` — actualizar sección "VACUUM ANALYZE post-purga" explicando que ahora hay opción automática. Link al config.
+- [ ] `README.md` — en el bloque de configuración agregar:
+  ```ruby
+  config.vacuum_after_purge = false  # true: VACUUM ANALYZE tras cada purge
+  ```
+
+### 3.5 Commit
+
+- [ ] Commit: `feat(engine): vacuum_after_purge opcional post-purge (item 5)`
+
+### Checkpoint Fase 3
+
+- [ ] Default `false` mantiene backward-compat.
+- [ ] Con `true` ejecuta VACUUM ANALYZE solo si hubo deletes.
+- [ ] PG::Error no rompe el flujo (warn + continue).
+- [ ] Log `engine.vacuum_complete` con métricas.
+
+---
+
+## Fase 4 — Item 11b: Warning runtime de purga lenta
+
+**Roadmap:** [Item 11b](../IMPROVEMENT_PLAN.md#item-11b--warning-runtime-de-purga-lenta-sin-avance)
+
+### Contexto
+
+`engine.purge_heartbeat` se emite cada 100 lotes. Si un lote tarda 5 minutos (índice faltante, lock contention), no hay alerta hasta el lote 100 (que podría ser horas).
+
+**Importante:** Usar Timecop (agregado en Fase 0.3) para tests. Big-pickle señaló en review v0.2.2 que mock directo de `Process.clock_gettime` es flakey.
+
+### 4.1 Agregar opciones a Configuration
+
+- [ ] Editar `lib/data_drain/configuration.rb`:
+  ```ruby
+  attr_accessor ...,
+                :slow_batch_threshold_s,    # ← NUEVO
+                :slow_batch_alert_after     # ← NUEVO
+
+  def initialize
+    ...
+    @slow_batch_threshold_s = 30
+    @slow_batch_alert_after = 5
+  end
+  ```
+
+### 4.2 Implementar warning en purge_loop
+
+- [ ] Refactor `Engine#purge_loop` (ya extraído en Fase 1) para medir timing por lote:
+  ```ruby
+  # @api private
+  def purge_loop(conn)
+    batches_processed = 0
+    total_deleted = 0
+    slow_batch_streak = 0
+
+    loop do
+      batch_start = monotonic
+      result = conn.exec(build_delete_sql)
+      batch_duration = monotonic - batch_start
+      count = result.cmd_tuples
+      break if count.zero?
+
+      batches_processed += 1
+      total_deleted += count
+
+      slow_batch_streak = handle_batch_timing(
+        batch_duration, count, slow_batch_streak
+      )
+
+      emit_heartbeat_if_due(batches_processed, total_deleted)
+
+      sleep(@config.throttle_delay) if @config.throttle_delay.positive?
+    end
+
+    total_deleted
+  end
+
+  # @api private
+  def handle_batch_timing(batch_duration, count, streak)
+    if batch_duration > @config.slow_batch_threshold_s
+      streak += 1
+      safe_log(:warn, "engine.slow_batch", {
+        table: @table_name,
+        batch_duration_s: batch_duration.round(2),
+        batch_size: count,
+        streak: streak,
+        threshold_s: @config.slow_batch_threshold_s
+      })
+
+      if streak == @config.slow_batch_alert_after
+        safe_log(:warn, "engine.purge_degraded", {
+          table: @table_name,
+          consecutive_slow_batches: streak,
+          hint: "considerar índice composite o particionamiento (ver postgres-tuning.md)"
+        })
+      end
+      streak
+    else
+      0  # reset streak
+    end
+  end
+  ```
+
+### 4.3 Tests con Timecop
+
+- [ ] Agregar a `spec/data_drain/engine_spec.rb` (Timecop ya está en spec_helper, Timecop.return en after(:each) global):
+  ```ruby
+  describe "warning de purga lenta" do
+    it "emite engine.slow_batch cuando batch excede threshold" do
+      DataDrain.configure do |c|
+        c.slow_batch_threshold_s = 5
+        c.slow_batch_alert_after = 3
+      end
+
+      engine = described_class.new(base_options.merge(table_name: "versions"))
+      # ... mocks ...
+
+      call_count = 0
+      allow(mock_pg_result).to receive(:cmd_tuples) do
+        call_count += 1
+        call_count <= 2 ? 100 : 0
+      end
+
+      allow(mock_pg_conn).to receive(:exec).with(/DELETE/) do
+        Timecop.travel(Time.now + 10)  # simular 10s por lote
+        mock_pg_result
+      end
+
+      logs = capture_logs { engine.call }
+      expect(logs).to include(match(/engine.slow_batch/))
+    end
+
+    it "emite engine.purge_degraded tras N lotes lentos consecutivos" do
+      DataDrain.configure do |c|
+        c.slow_batch_threshold_s = 5
+        c.slow_batch_alert_after = 3
+      end
+
+      # ... simular 3 lotes lentos consecutivos ...
+      logs = capture_logs { engine.call }
+      expect(logs.select { |l| l.include?("engine.purge_degraded") }.size).to eq(1)
+    end
+
+    it "resetea streak si un lote es rápido" do
+      # ... 2 lotes lentos, 1 rápido, 2 lentos ...
+      # NO debería emitir purge_degraded porque streak se reseteó
+    end
+
+    it "thresholds configurables via Configuration" do
+      # ...
+    end
+  end
+  ```
+
+### 4.4 Docs
+
+- [ ] `skill/references/eventos-telemetria.md` — agregar `engine.slow_batch` (WARN) y `engine.purge_degraded` (WARN).
+- [ ] `skill/references/api-detallada.md` — Configuration table agregar `slow_batch_threshold_s` (Integer, default `30`) y `slow_batch_alert_after` (Integer, default `5`).
+- [ ] `skill/references/postgres-tuning.md` — mencionar que DataDrain ahora alerta automáticamente si detecta purga lenta, link a sección "Índice recomendado".
+
+### 4.5 Commit
+
+- [ ] Commit: `feat(engine): warning runtime de purga lenta sin avance (item 11b)`
+
+### Checkpoint Fase 4
+
+- [ ] Thresholds configurables con defaults razonables.
+- [ ] Streak se resetea con lote rápido.
+- [ ] `purge_degraded` emite una sola vez por streak.
+- [ ] Tests usan Timecop (no mocks frágiles).
+
+---
+
+## Fase 5 — Item 6: Sandboxing de `Record.connection`
+
+**Roadmap:** [Item 6](../IMPROVEMENT_PLAN.md#item-6--sandboxing-de-recordconnection)
+
+### Contexto
+
+`Record.connection` es read-only por diseño. Aplicar `SET lock_configuration=true` post-setup reduce blast radius si alguien intenta ejecutar SQL malicioso vía `where_clause` (improbable hoy pero defensa en profundidad).
+
+**Riesgo:** `lock_configuration=true` congela TODAS las configs de la conexión. Si después se intenta cambiar `s3_*` o cargar otra extensión, falla. Actualmente el setup carga httpfs + SECRET antes del lock, así que OK.
+
+### 5.1 Investigación previa — PRE-REQUISITO (observación 5 big-pickle)
+
+**No implementar 5.2 sin completar esta investigación.** El Plan B contempla que `lock_configuration` rompa httpfs/S3 en runtime; esto debe descartarse antes.
+
+Ejecutar los 3 tests en `bin/console`:
+
+- [ ] **Test 1: lock no afecta httpfs ya cargado**
+  ```ruby
+  # bin/console
+  db = DuckDB::Database.open(":memory:"); conn = db.connect
+  conn.query("INSTALL httpfs; LOAD httpfs;")
+  conn.query("SET lock_configuration=true;")
+
+  # Debería funcionar:
+  conn.query("SELECT 1;")  # → [[1]]
+
+  # Debería FALLAR (esperado):
+  begin
+    conn.query("SET memory_limit='1KB';")
+    puts "ERROR: lock no funcionó"
+  rescue DuckDB::Error => e
+    puts "OK: lock rechaza SET (#{e.message})"
+  end
+  ```
+
+- [ ] **Test 2: lock no afecta secrets ya creados**
+  ```ruby
+  db = DuckDB::Database.open(":memory:"); conn = db.connect
+  conn.query("INSTALL httpfs; LOAD httpfs;")
+  conn.query("CREATE SECRET test_secret (TYPE S3, PROVIDER credential_chain, REGION 'us-east-1');")
+  conn.query("SET lock_configuration=true;")
+
+  # Verificar que el secret sigue disponible:
+  result = conn.query("FROM duckdb_secrets();").to_a
+  puts "Secrets post-lock: #{result.size}"  # Debe ser ≥ 1
+  ```
+
+- [ ] **Test 3: read_parquet(s3://...) funciona post-lock** (requiere credenciales AWS válidas)
+  ```ruby
+  # Solo si hay un bucket de prueba
+  # conn.query("FROM read_parquet('s3://your-test-bucket/path/*.parquet') LIMIT 1;")
+  # Si falla con error de auth → problema de credenciales, no del lock
+  # Si falla con error de lock → bloqueante, ajustar código (ver punto siguiente)
+  ```
+
+- [ ] **Documentar resultados:**
+  > Test 1 (SET rechazado post-lock): _______________
+  > Test 2 (secrets preservados): _______________
+  > Test 3 (read_parquet S3): _______________
+
+**Plan según resultados:**
+
+| Escenario | Acción |
+|-----------|--------|
+| Todos los tests OK | Proceder con 5.2 implementación unconditional |
+| Test 3 falla por lock | Ajustar: aplicar lock solo si `storage_mode == :local`, documentar limitación S3 en CLAUDE.md y SKILL.md |
+| Test 2 falla (secrets rotos) | **STOP** — diseñar alternativa (ej. lock via SET scope=session en lugar de global) |
+
+### 5.2 Implementar
+
+- [ ] Editar `lib/data_drain/record.rb` en `self.connection`, después de `DataDrain::Storage.adapter.setup_duckdb(conn)`:
+  ```ruby
+  def self.connection
+    Thread.current[:data_drain_duckdb] ||= begin
+      db = DuckDB::Database.open(":memory:")
+      conn = db.connect
+
+      config = DataDrain.configuration
+      conn.query("SET max_memory='#{config.limit_ram}';") if config.limit_ram.present?
+      conn.query("SET temp_directory='#{config.tmp_directory}'") if config.tmp_directory.present?
+
+      DataDrain::Storage.adapter.setup_duckdb(conn)
+
+      # Sandboxing: congelar config post-setup (item 6 v0.3.0)
+      # NO afecta secrets ni extensiones ya cargadas — solo previene SETs futuros.
+      conn.query("SET lock_configuration=true;")
+
+      { db: db, conn: conn }
+    end
+    Thread.current[:data_drain_duckdb][:conn]
+  end
+  ```
+
+### 5.3 Tests
+
+- [ ] Agregar a `spec/data_drain/record_spec.rb`:
+  ```ruby
+  describe "sandboxing (item 6)" do
+    after { described_class.disconnect! }
+
+    it "aplica lock_configuration=true tras setup" do
+      conn = record_class.connection
+      expect {
+        conn.query("SET memory_limit='1KB';")
+      }.to raise_error(DuckDB::Error, /lock/i)
+    end
+
+    it "permite queries de lectura tras lock" do
+      expect {
+        record_class.where(year: 2026, month: 3)
+      }.not_to raise_error
+    end
+
+    it "S3 (httpfs) sigue funcionando tras lock" do
+      # Skip si no hay fixture S3 o mockear
+      # Requiere setup de S3 antes del lock, verificar que no rompe
+      skip "requiere fixture S3 real" unless ENV["TEST_S3"]
+      # ...
+    end
+  end
+  ```
+
+### 5.4 Edge case: reconnect tras `disconnect!`
+
+Cuando se llama `Record.disconnect!` y luego se hace una query, se reinicia el setup. El lock se aplica de nuevo. Test:
+
+- [ ] Agregar:
+  ```ruby
+  it "reaplica lock_configuration tras reconnect" do
+    record_class.connection
+    record_class.disconnect!
+    conn = record_class.connection  # reconnect
+
+    expect {
+      conn.query("SET memory_limit='1KB';")
+    }.to raise_error(DuckDB::Error, /lock/i)
+  end
+  ```
+
+### 5.5 Docs
+
+- [ ] `CLAUDE.md` — sección "Seguridad" agregar nota sobre `lock_configuration` en Record.
+- [ ] `skill/references/api-detallada.md` — Record.connection: mencionar que la conexión está sandboxed.
+- [ ] `skill/references/antipatrones.md` — nuevo antipatrón: "No intentar cambiar config DuckDB en la conexión de Record — está locked. Para configs distintas, crear conexión efímera (Engine/FileIngestor sí pueden)."
+
+### 5.6 Commit
+
+- [ ] Commit: `security(record): sandboxing con lock_configuration=true (item 6)`
+
+### Checkpoint Fase 5
+
+- [ ] Lock aplicado tras setup.
+- [ ] Read queries siguen funcionando.
+- [ ] S3 queries (httpfs) siguen funcionando.
+- [ ] Reconnect post-`disconnect!` reaplica lock.
+
+---
+
+## Fase 6 — Release
+
+### 6.1 Lint global
+
+- [ ] `bundle exec rubocop lib/` — 0 ofensas, 0 `rubocop:disable Metrics/*`.
+- [ ] `bundle exec rspec` — todo verde, coverage ≥ 80%.
+- [ ] CI verde en branch.
+
+### 6.2 CHANGELOG
+
+- [ ] Editar `CHANGELOG.md`, agregar al tope:
+  ```markdown
+  ## [0.3.0] - 2026-XX-XX
+
+  ### Refactor
+  - `Engine#call` refactorizado: extraídos `step_count`, `step_export`, `step_verify`,
+    `step_purge` como métodos privados con `timed` helper. CC bajó de 13 a 5. Eventos
+    emitidos idénticos al comportamiento anterior. (item 10)
+  - Extraído `DataDrain::Observability::Timing` mixin compartido entre Engine y
+    FileIngestor. (item 20)
+  - `FileIngestor#call` refactorizado análogo a Engine. (item 20)
+  - Eliminados todos los `# rubocop:disable Metrics/*` en `lib/`. (item 20)
+
+  ### Features
+  - `config.vacuum_after_purge = false` (default). Si `true`, ejecuta `VACUUM ANALYZE`
+    post-purga cuando hubo deletes. Emite `engine.vacuum_complete` con dead_tuples
+    antes/después y duración. Errores PG se capturan como `engine.vacuum_error` WARN.
+    (item 5)
+  - `config.slow_batch_threshold_s = 30` y `config.slow_batch_alert_after = 5`.
+    Detecta lotes de purga lentos. Emite `engine.slow_batch` WARN por cada lote
+    lento, `engine.purge_degraded` WARN una vez por streak. Incluye hint a docs de
+    tuning. (item 11b)
+
+  ### Security
+  - `Record.connection` aplica `SET lock_configuration=true` post-setup. Congela
+    cualquier SET futuro sobre la conexión (defensa en profundidad). NO afecta
+    secrets ni extensiones ya cargadas. (item 6)
+
+  ### Telemetry nueva
+  - `engine.vacuum_complete`, `engine.vacuum_error`, `engine.slow_batch`,
+    `engine.purge_degraded`.
+
+  ### Tests
+  - Coverage se mantiene ≥ 80%.
+  - Nuevo test de equivalencia para Engine (eventos idénticos pre/post refactor).
+  - Timecop agregado para tests de timing (item 11b).
+  ```
+
+### 6.3 Bump versión
+
+- [ ] `lib/data_drain/version.rb`: `VERSION = "0.3.0"`
+- [ ] `bundle install` (actualiza `Gemfile.lock`)
+
+### 6.4 Actualizar roadmap
+
+- [ ] `docs/IMPROVEMENT_PLAN.md`: items 5, 6, 10, 11b, 20 → `[x]`.
+- [ ] Actualizar "Última actualización".
+
+### 6.5 Commit release
+
+- [ ] Commit: `chore: release v0.3.0 — refactor y observabilidad avanzada`
+
+### 6.6 PR + merge + tag
+
+- [ ] `git push origin feature/v0.3.0`
+- [ ] `gh pr create` con título `v0.3.0: refactor Engine + VACUUM + warning purga + sandboxing`
+- [ ] Esperar CI verde
+- [ ] Mergear
+- [ ] Tag: `git tag v0.3.0 && git push origin v0.3.0`
+
+### 6.7 Post-merge
+
+- [ ] Archivar plan: `git mv docs/execution/v0.3.0.md docs/execution/archive/v0.3.0.md`
+- [ ] Commit: `chore: archive v0.3.0 plan, mark items 5/6/10/11b/20 [x]`
+
+---
+
+## Validación final
+
+- [ ] CI verde en main tras merge
+- [ ] Coverage ≥ 80%
+- [ ] 0 `rubocop:disable Metrics/*` en `lib/`
+- [ ] Tag v0.3.0 creado
+- [ ] 5 items marcados `[x]` en roadmap
+- [ ] Plan archivado
+- [ ] CHANGELOG actualizado
+
+---
+
+## Plan B — escenarios de bloqueo
+
+| Si... | Entonces... |
+|-------|-------------|
+| Item 10 rompe tests existentes por cambio de orden de eventos | Revisar test de equivalencia; ajustar el orden de `safe_log` calls |
+| Item 20 refactor de FileIngestor#call es más costoso de lo esperado | Dividir en sub-release v0.3.0.1 |
+| Item 5 tests mockeados de `pg_stat_user_tables` son frágiles | Marcar tests con `:integration` y correr con Postgres real manualmente |
+| Item 11b tests con Timecop siguen flakey en CI | Aumentar tolerancia en assertions, usar `Time.travel` con offsets grandes |
+| Item 6 `lock_configuration` rompe httpfs/S3 en runtime | Mover el lock a solo cuando `storage_mode == :local`; documentar limitación |
+| Coverage baja de 80% tras refactor | Agregar tests para nuevos métodos privados `step_*` via `send(:step_count)` etc. |
+
+---
+
+## Notas para el agente que ejecuta
+
+- **Fase 1 es la más invasiva.** Tests de equivalencia son críticos para no romper consumidores que dependen del formato de logs.
+- **Commits granulares**: dentro de Fase 2, cada archivo refactoreado = 1 commit. Facilita bisect si algo rompe.
+- **Cada fase cierra con verde**: rspec + rubocop antes del siguiente paso.
+- **Observabilidad crítica**: los eventos nuevos (`vacuum_complete`, `slow_batch`, `purge_degraded`) deben respetar el estándar Wispro-Observability-Spec v1 (keys snake_case, `_s` Float, `_count` Integer, sin unidades en valores).
+- **No tocar** `skip_export`, `verify_integrity`, `base_where_sql`, `setup_duckdb`, `get_postgres_count`, `export_to_parquet`. Ya están probados y no necesitan refactor.
+- **Coordinación con Gemini**: si trabaja en paralelo, verificar antes de consolidar (`source=`, orden de campos en logs, `include` vs `extend`, etc. — ver `feedback_gemini_collaboration.md`).