data_drain 0.3.2 → 0.5.0

data/docs/execution/v0.5.0.md

@@ -0,0 +1,900 @@
+# Plan de Ejecución — v0.5.0
+
+**Feature:** Upload de scripts a S3 desde `GlueRunner`
+**Items del roadmap:** 37 (nuevo, follow-up post-roadmap)
+**Branch sugerido:** `feature/v0.5.0`
+**Base:** `main` (contiene v0.4.0)
+**Estado:** Pendiente de revisión (versión 2 tras review)
+**Última actualización:** 2026-04-15
+
+---
+
+## 1. Contexto
+
+Tras v0.4.0 la gema gestiona el ciclo de vida completo de Glue Jobs (`create_job`, `update_job`, `delete_job`, `ensure_job`), pero asume que el script PySpark ya está en S3 (decisión B1 del plan v0.4.0). El caller debe subirlo manualmente:
+
+```bash
+aws s3 cp scripts/glue/export.py s3://bucket/scripts/
+```
+
+**Problema observado en uso:** cada servicio que usa la gema repite el upload, duplica lógica y puede olvidar actualizar el script al cambiar código. El archivo `docs/glue_pyspark_example.py` ya existe como template reutilizable, pero no hay forma ergonómica de subirlo desde Ruby.
+
+**Solución:** agregar upload desde la gema usando el `Storage::S3` adapter existente (no crear cliente paralelo).
+
+---
+
+## 2. Decisión de diseño (re-aprobada tras review)
+
+### Opción A — `script_path` en `create_job`/`ensure_job` (RECOMENDADA)
+
+- Si se pasa `script_location:` (S3 path) → comportamiento actual, no hay upload.
+- Si se pasa `script_path:` (archivo local) + `script_bucket:` → la gema sube a S3 primero, luego crea el Job.
+- Si se pasan ambos → `DataDrain::ConfigurationError` (ambigüedad).
+- Si no se pasa ninguno → `ArgumentError` (requerido).
+
+```ruby
+# Uso actual (sin cambios)
+DataDrain::GlueRunner.create_job(
+  "my-job",
+  script_location: "s3://bucket/scripts/export.py",
+  role_arn: "arn:aws:iam::123:role/GlueRole"
+)
+
+# Uso nuevo
+DataDrain::GlueRunner.create_job(
+  "my-job",
+  script_path: "scripts/glue/export.py",
+  script_bucket: "my-bucket",
+  script_folder: "scripts",
+  role_arn: "arn:aws:iam::123:role/GlueRole"
+)
+# → Sube scripts/glue/export.py a s3://my-bucket/scripts/export.py
+# → Crea el Job apuntando a ese S3 path
+```
+
+### Review de agentes — v2 incorporado
+
+Revisión por **big-pickle** 2026-04-15 (`docs/execution/v0.5.0-OBSERVACIONES.md`). 8 observaciones verificadas contra código real de `main`:
+
+| # | Sev | Hallazgo | Estado |
+|---|-----|---------|--------|
+| 1 | Alta | `s3_client` existe en `Storage::S3`? | ✅ **Verificado — existe** en `storage/s3.rb:44`. Plan v2 lo reutiliza correctamente. Nota: el SDK acepta `nil` en `access_key_id`/`secret_access_key` y resuelve credential chain automáticamente. |
+| 2 | Alta | `changed_fields` incluye `script_location`? | ✅ **Verificado — sí**, vía `:command` key (línea 174-175 `glue_runner.rb`). `current.command.script_location != desired[:script_location]`. Plan v2 OK. |
+| 3 | Media | `Configuration#local_bucket` existe? | ✅ **Verificado — no existe**. Plan v2 pide `bucket` como arg explícito en `Storage::Local#upload_file`. Documentado. |
+| 4 | Baja | Paths Windows | Low risk (Glue corre en Linux). Test opcional no bloqueante. |
+| 5 | Media | IAM permisos mínimos no documentados | **Aplicado:** agregar sección "Permisos IAM mínimos" en Fase 5.1 (`docs/glue-jobs-lifecycle.md`). |
+| 6 | Baja | Error claro en modo :local | Ya cubierto por test "levanta ConfigurationError si storage_mode es :local" del plan v2. |
+| 7 | Info | content_type explícito `text/x-python` | OK. Más predecible que dejar que S3 infiera. |
+| 8 | Info | Concurrencia sin lock | **Aplicado:** documentar como limitación en Fase 5.1. Riesgo bajo (scripts chicos, rare concurrent writes en mismo path). |
+
+**Cambios materiales al plan v2:**
+- Fase 5.1 agrega sección "Permisos IAM mínimos" (obs 5)
+- Fase 5.1 agrega sección "Concurrencia" documentando limitación (obs 8)
+
+### 2da pasada de big-pickle — hallazgos rechazados
+
+Big-pickle hizo una segunda pasada expandiendo a 11 observaciones. 2 de ellas contienen errores factuales verificados y se rechazan:
+
+**❌ Obs 1 (2da pasada) — "SyntaxError en firma de `create_job`"**
+
+Big-pickle afirmó que esta firma es inválida en Ruby:
+
+    def self.create_job(job_name, role_arn:, script_location: nil, ...)
+
+Citó: *"required keyword argument cannot have a default value"*.
+
+**Rechazado:** Ruby permite mezclar required y optional kwargs libremente. El error citado aplica a un SOLO kwarg que intenta ser required y optional al mismo tiempo (`def foo(x:, x: 1)`), no a firmas con varios kwargs donde algunos son required y otros optional.
+
+Verificación:
+
+    $ ruby -e 'def test(a:, b: nil, c:, d: 1); "OK"; end; puts test(a: 1, c: 3)'
+    # => OK
+
+El plan mantiene `role_arn:` como required (sin default). `script_location:`, `script_path:`, etc. son optional con default `nil`. Sintaxis válida desde Ruby 2.0.
+
+**❌ Obs 6 (2da pasada) — "`spec/data_drain/storage/local_spec.rb` no existe"**
+
+Big-pickle afirmó que el archivo no existe y pidió crearlo.
+
+**Rechazado:** el archivo existe desde v0.2.0 (item 4, cobertura P0). Verificado:
+
+    $ ls spec/data_drain/storage/
+    local_spec.rb   s3_spec.rb
+
+Plan v2 agrega tests al archivo existente, no lo crea nuevo.
+
+**✅ Obs válidas (2da pasada):**
+
+- 2, 3: confirmaciones de obs 1, 2 de la 1ra pasada (ya aplicadas).
+- 4: ya aplicada en plan v2 (Storage::Local necesita directorio manual).
+- 5, 7, 8, 10, 11: info/OK, no requieren cambio.
+- 9: decisión discutible — `bytes` vs `byte_count`. Mantener `bytes` por convención AWS (ContentLength). Documentada como desviación consciente del spec Wispro.
+
+### Cambios vs plan original (v1)
+
+Cambios clave de v1 → v2:
+
+| Review finding | Cambio aplicado |
+|---------------|-----------------|
+| Plan v1 creaba `Aws::S3::Client.new` paralelo al Storage adapter | **v2 usa `Storage::S3` adapter existente** con `credential_chain` ya configurado |
+| Plan v1 usaba kwarg `bucket:` conflictivo con el de Engine/FileIngestor/Record | **v2 renombra a `script_bucket:`** para claridad |
+| Plan v1 no emitía logs estructurados | **v2 agrega `glue_runner.script_uploaded` + `script_upload_error`** |
+| Plan v1 decía "idempotente" pero `put_object` sobrescribe siempre | **v2 documenta como "overwrite always"**, opcional ETag check futuro |
+| Plan v1 mitigaba colisión de nombres solo con docs | **v2 permite `s3_filename:` override** (default basename) |
+| Plan v1 no tenía Plan B ni estimación | **v2 agrega ambos** |
+| Plan v1 no actualizaba `docs/glue_pyspark_example.py` | **v2 lo incluye** en Fase 5 |
+
+### Alternativas descartadas
+
+- **Método `upload_script` separado sin auto-wire a `create_job`** — requiere 2 pasos en caller; se ofrece también como API pública para casos independientes (ver Fase 2), pero `create_job` lo llama internamente cuando corresponde.
+- **Bucket global en `Configuration`** — acopla, el bucket puede variar por job. Descartado.
+- **Upload a `bucket/folder_name/` (reusar bucket del Data Lake)** — mezcla scripts con datos archivados. Mala separación.
+
+---
+
+## 3. API Propuesta
+
+### Nuevo en `Storage::S3` — `upload_file`
+
+Como primitiva genérica. Vive en el adapter, no en `GlueRunner`.
+
+```ruby
+# lib/data_drain/storage/s3.rb
+def upload_file(local_path, bucket, s3_key, content_type: nil)
+  # ...
+end
+```
+
+En `Storage::Local` se implementa como copy a disco (por consistencia de la interfaz; útil para tests locales). En `Storage::Base` abstracto.
+
+### Nuevo en `GlueRunner` — `upload_script`
+
+Wrapper semántico sobre `Storage.adapter.upload_file` con convenciones para scripts Python.
+
+```ruby
+DataDrain::GlueRunner.upload_script(
+  local_path:,              # Path local al archivo (String)
+  bucket:,                  # Bucket S3 destino (String)
+  folder: "scripts",        # Folder S3 (default: "scripts")
+  filename: nil             # Override del nombre S3 (default: basename)
+)
+# => "s3://bucket/scripts/filename.py"
+```
+
+**Comportamiento:**
+- Valida que `local_path` existe (`File.exist?`).
+- Delega a `Storage::S3.adapter#upload_file` con `content_type: "text/x-python"`.
+- Retorna el path S3 completo.
+- Emite `glue_runner.script_uploaded` con `local_path`, `s3_path`, `bytes`.
+- **No es idempotente en sentido estricto:** `put_object` sobrescribe siempre. Documentar.
+
+### Modificación — `create_job`
+
+Firma (nuevos params marcados con ⬆):
+
+```ruby
+def self.create_job(
+  job_name,
+  role_arn:,
+  script_location: nil,    # ⬆ ahora opcional (antes requerido)
+  script_path: nil,         # ⬆ nuevo
+  script_bucket: nil,       # ⬆ nuevo (requerido si script_path)
+  script_folder: "scripts", # ⬆ nuevo
+  script_filename: nil,     # ⬆ nuevo (override basename)
+  command_name: "glueetl",
+  default_arguments: {},
+  description: nil,
+  worker_type: nil,
+  number_of_workers: nil,
+  timeout: 2880,
+  max_retries: 0,
+  allocated_capacity: nil,
+  glue_version: nil
+)
+```
+
+**Lógica de resolución (helper privado):**
+
+```ruby
+# @api private
+def self.resolve_script_location(script_location:, script_path:, script_bucket:, script_folder:, script_filename:)
+  both_set = script_location && script_path
+  raise DataDrain::ConfigurationError, "provee script_location o script_path, no ambos" if both_set
+
+  return script_location if script_location
+  raise ArgumentError, "script_location o script_path es requerido" unless script_path
+  raise DataDrain::ConfigurationError, "script_path requiere script_bucket" unless script_bucket
+
+  upload_script(
+    local_path: script_path,
+    bucket: script_bucket,
+    folder: script_folder,
+    filename: script_filename
+  )
+end
+```
+
+Llamado al inicio de `create_job`:
+
+```ruby
+def self.create_job(job_name, role_arn:, script_location: nil, script_path: nil,
+                    script_bucket: nil, script_folder: "scripts", script_filename: nil,
+                    ...)
+  @logger = DataDrain.configuration.logger
+  DataDrain::Validations.validate_glue_name!(:job_name, job_name)
+
+  final_script_location = resolve_script_location(
+    script_location: script_location,
+    script_path: script_path,
+    script_bucket: script_bucket,
+    script_folder: script_folder,
+    script_filename: script_filename
+  )
+  # ... resto del método usa final_script_location
+end
+```
+
+### Modificación — `ensure_job`
+
+Misma firma extendida. Pasa los kwargs a `create_job`/`update_job` via passthrough (update_job no soporta `script_path` por ahora — ver Fase 3).
+
+---
+
+## 4. Implementación
+
+### 4.1 `Storage::Base#upload_file` (abstracto)
+
+**Archivo:** `lib/data_drain/storage/base.rb`
+
+```ruby
+# Sube un archivo local al storage.
+#
+# @param local_path [String]
+# @param bucket [String]
+# @param s3_key [String] key relativo (ej. "scripts/export.py")
+# @param content_type [String, nil]
+# @return [String] URI completo del archivo subido
+# @raise [NotImplementedError]
+def upload_file(local_path, bucket, s3_key, content_type: nil)
+  raise NotImplementedError, "#{self.class} debe implementar #upload_file"
+end
+```
+
+### 4.2 `Storage::S3#upload_file`
+
+**Archivo:** `lib/data_drain/storage/s3.rb`
+
+```ruby
+# @param local_path [String]
+# @param bucket [String]
+# @param s3_key [String]
+# @param content_type [String, nil]
+# @return [String] "s3://bucket/key"
+def upload_file(local_path, bucket, s3_key, content_type: nil)
+  client = s3_client  # ya existe, usa config cacheada
+
+  File.open(local_path, "rb") do |file|
+    params = { bucket: bucket, key: s3_key, body: file }
+    params[:content_type] = content_type if content_type
+    client.put_object(**params)
+  end
+
+  "s3://#{bucket}/#{s3_key}"
+end
+```
+
+**Nota:** reutiliza `s3_client` private method existente (desde v0.3.0) — usa `credential_chain` si corresponde.
+
+### 4.3 `Storage::Local#upload_file`
+
+**Archivo:** `lib/data_drain/storage/local.rb`
+
+```ruby
+# @param local_path [String]
+# @param bucket [String] Directorio destino
+# @param s3_key [String] Path relativo dentro del bucket
+# @param content_type [String, nil] Ignorado en modo local
+# @return [String] Path absoluto al archivo destino
+def upload_file(local_path, bucket, s3_key, _content_type: nil)
+  dest_path = File.join(bucket, s3_key)
+  FileUtils.mkdir_p(File.dirname(dest_path))
+  FileUtils.cp(local_path, dest_path)
+  dest_path
+end
+```
+
+Útil para tests en modo `:local` sin mockear S3.
+
+### 4.4 `GlueRunner.upload_script`
+
+**Archivo:** `lib/data_drain/glue_runner.rb`
+
+```ruby
+# Sube un script Python local al bucket S3 configurado y retorna el path S3.
+#
+# @param local_path [String] Ruta local al archivo.
+# @param bucket [String] Bucket S3 destino.
+# @param folder [String] Folder dentro del bucket. Default: "scripts".
+# @param filename [String, nil] Override del nombre en S3. Default: basename(local_path).
+# @return [String] S3 path del archivo subido (ej. "s3://bucket/scripts/export.py").
+# @raise [DataDrain::ConfigurationError] si local_path no existe.
+# @raise [Aws::S3::Errors::ServiceError] si el upload falla.
+#
+# @note NO es idempotente en sentido estricto. `put_object` sobrescribe siempre
+#   sin comparar contenido. Si dos callers suben el mismo path con contenido
+#   distinto, gana el último. Usar `filename:` distinto o versionar manualmente
+#   si necesitás coexistencia.
+def self.upload_script(local_path:, bucket:, folder: "scripts", filename: nil)
+  @logger = DataDrain.configuration.logger
+
+  unless File.exist?(local_path)
+    raise DataDrain::ConfigurationError,
+          "Script local '#{local_path}' no existe"
+  end
+
+  actual_filename = filename || File.basename(local_path)
+  s3_key = "#{folder.chomp("/")}/#{actual_filename}"
+  bytes = File.size(local_path)
+
+  adapter = DataDrain::Storage.adapter
+  unless adapter.is_a?(DataDrain::Storage::S3)
+    raise DataDrain::ConfigurationError,
+          "upload_script requiere storage_mode = :s3, actual: #{DataDrain.configuration.storage_mode}"
+  end
+
+  s3_path = adapter.upload_file(local_path, bucket, s3_key, content_type: "text/x-python")
+
+  safe_log(:info, "glue_runner.script_uploaded", {
+             local_path: local_path,
+             s3_path: s3_path,
+             bytes: bytes
+           })
+
+  s3_path
+rescue Aws::S3::Errors::ServiceError => e
+  safe_log(:error, "glue_runner.script_upload_error",
+           { local_path: local_path, bucket: bucket }.merge(exception_metadata(e)))
+  raise
+end
+```
+
+### 4.5 `GlueRunner.create_job` — signature + resolución
+
+Diff sobre el actual:
+
+```ruby
+def self.create_job(job_name, role_arn:, script_location: nil, script_path: nil,
+                    script_bucket: nil, script_folder: "scripts", script_filename: nil,
+                    command_name: "glueetl", default_arguments: {}, description: nil,
+                    worker_type: nil, number_of_workers: nil, timeout: 2880,
+                    max_retries: 0, allocated_capacity: nil, glue_version: nil)
+  @logger = DataDrain.configuration.logger
+  DataDrain::Validations.validate_glue_name!(:job_name, job_name)
+
+  final_script = resolve_script_location(
+    script_location: script_location,
+    script_path: script_path,
+    script_bucket: script_bucket,
+    script_folder: script_folder,
+    script_filename: script_filename
+  )
+
+  opts = {
+    name: job_name,
+    role: role_arn,
+    command: {
+      name: command_name,
+      python_version: "3",
+      script_location: final_script
+    }
+  }
+  # ... resto igual al actual ...
+```
+
+### 4.6 `GlueRunner.ensure_job` — passthrough
+
+Agregar mismos kwargs nuevos, pasarlos a `create_job`. **Limitación:** `update_job` no soporta `script_path` en esta versión (siempre usa `script_location` si se provee). Si el caller quiere actualizar el script en un job existente vía `ensure_job`, debe pasar `script_path:` — `ensure_job` internamente sube (via `upload_script`) y pasa el resultado a `update_job` como `script_location`. Esto requiere logic extra.
+
+**Decisión:** `ensure_job` sube el script también si recibe `script_path`, antes de comparar `changed_fields`. El `current.command.script_location` se compara contra el `script_location` resultante del upload.
+
+```ruby
+def self.ensure_job(job_name, role_arn:, script_location: nil, script_path: nil,
+                    script_bucket: nil, script_folder: "scripts", script_filename: nil,
+                    ...)
+  @logger = DataDrain.configuration.logger
+
+  final_script = resolve_script_location(
+    script_location: script_location,
+    script_path: script_path,
+    script_bucket: script_bucket,
+    script_folder: script_folder,
+    script_filename: script_filename
+  )
+
+  if job_exists?(job_name)
+    current = get_job(job_name)
+    desired = { ..., script_location: final_script, ... }
+    changed = changed_fields(desired, current)
+    # ...
+  else
+    create_job(job_name, role_arn: role_arn, script_location: final_script, ...)
+  end
+end
+```
+
+**Edge case:** si el caller llama `ensure_job` con `script_path:` varias veces con el mismo contenido, cada vez sube a S3 (no es idempotente el upload). Documentar en skill.
+
+### 4.7 Tests
+
+#### `spec/data_drain/storage/s3_spec.rb`
+
+```ruby
+describe "#upload_file" do
+  let(:temp_script) { Tempfile.new(["export", ".py"], binmode: true) }
+
+  before do
+    temp_script.write("# python content")
+    temp_script.close
+  end
+
+  after { temp_script.unlink }
+
+  it "sube el archivo a S3 y retorna el path completo" do
+    uploaded_params = nil
+    s3_client.stub_responses(:put_object, lambda { |context|
+      uploaded_params = context.params
+      {}
+    })
+
+    result = adapter.upload_file(temp_script.path, "my-bucket", "scripts/export.py",
+                                  content_type: "text/x-python")
+
+    expect(result).to eq("s3://my-bucket/scripts/export.py")
+    expect(uploaded_params[:bucket]).to eq("my-bucket")
+    expect(uploaded_params[:key]).to eq("scripts/export.py")
+    expect(uploaded_params[:content_type]).to eq("text/x-python")
+  end
+
+  it "omite content_type si no se provee" do
+    uploaded_params = nil
+    s3_client.stub_responses(:put_object, lambda { |context|
+      uploaded_params = context.params
+      {}
+    })
+
+    adapter.upload_file(temp_script.path, "my-bucket", "export.py")
+
+    expect(uploaded_params).not_to have_key(:content_type)
+  end
+end
+```
+
+#### `spec/data_drain/storage/local_spec.rb`
+
+```ruby
+describe "#upload_file" do
+  it "copia el archivo al destino local y retorna el path absoluto" do
+    Dir.mktmpdir do |tmpdir|
+      source = File.join(tmpdir, "source.py")
+      File.write(source, "# python")
+
+      dest_dir = File.join(tmpdir, "dest")
+      result = adapter.upload_file(source, dest_dir, "scripts/export.py")
+
+      expected = File.join(dest_dir, "scripts/export.py")
+      expect(result).to eq(expected)
+      expect(File.read(expected)).to eq("# python")
+    end
+  end
+end
+```
+
+#### `spec/data_drain/glue_runner_spec.rb`
+
+```ruby
+describe ".upload_script" do
+  let(:temp_script) { Tempfile.new(["export", ".py"], binmode: true) }
+
+  before do
+    temp_script.write("# python")
+    temp_script.close
+    DataDrain.configure { |c| c.storage_mode = :s3; c.aws_region = "us-east-1" }
+    DataDrain::Storage.reset_adapter!
+  end
+
+  after do
+    temp_script.unlink
+    DataDrain::Storage.reset_adapter!
+  end
+
+  it "sube el script y retorna S3 path" do
+    allow(DataDrain::Storage.adapter).to receive(:upload_file)
+      .and_return("s3://my-bucket/scripts/export.py")
+
+    result = described_class.upload_script(
+      local_path: temp_script.path,
+      bucket: "my-bucket",
+      folder: "scripts"
+    )
+
+    expect(result).to eq("s3://my-bucket/scripts/export.py")
+  end
+
+  it "usa filename override si se provee" do
+    expected_key = "scripts/custom_name.py"
+    expect(DataDrain::Storage.adapter).to receive(:upload_file)
+      .with(temp_script.path, "my-bucket", expected_key, content_type: "text/x-python")
+      .and_return("s3://my-bucket/#{expected_key}")
+
+    described_class.upload_script(
+      local_path: temp_script.path,
+      bucket: "my-bucket",
+      filename: "custom_name.py"
+    )
+  end
+
+  it "levanta ConfigurationError si local_path no existe" do
+    expect {
+      described_class.upload_script(local_path: "/nonexistent.py", bucket: "b")
+    }.to raise_error(DataDrain::ConfigurationError, /no existe/)
+  end
+
+  it "levanta ConfigurationError si storage_mode es :local" do
+    DataDrain.configure { |c| c.storage_mode = :local }
+    DataDrain::Storage.reset_adapter!
+
+    expect {
+      described_class.upload_script(local_path: temp_script.path, bucket: "b")
+    }.to raise_error(DataDrain::ConfigurationError, /storage_mode/)
+  end
+
+  it "emite glue_runner.script_uploaded con bytes + s3_path" do
+    allow(DataDrain::Storage.adapter).to receive(:upload_file)
+      .and_return("s3://my-bucket/scripts/export.py")
+
+    logs = capture_logs {
+      described_class.upload_script(local_path: temp_script.path, bucket: "my-bucket")
+    }
+    expect(logs.find { |l| l.include?("glue_runner.script_uploaded") }).to include("bytes=")
+  end
+
+  it "emite glue_runner.script_upload_error y propaga si falla" do
+    allow(DataDrain::Storage.adapter).to receive(:upload_file)
+      .and_raise(Aws::S3::Errors::ServiceError.new(nil, "AccessDenied"))
+
+    expect {
+      described_class.upload_script(local_path: temp_script.path, bucket: "b")
+    }.to raise_error(Aws::S3::Errors::ServiceError)
+  end
+end
+
+describe ".create_job" do
+  context "con script_path local" do
+    before do
+      allow(described_class).to receive(:upload_script)
+        .and_return("s3://my-bucket/scripts/export.py")
+      glue_client.stub_responses(:create_job, {})
+      glue_client.stub_responses(:get_job, { job: { name: "my-job" } })
+    end
+
+    it "sube script y crea job con script_location resultante" do
+      expect(described_class).to receive(:upload_script).with(
+        local_path: "scripts/glue/export.py",
+        bucket: "my-bucket",
+        folder: "scripts",
+        filename: nil
+      )
+
+      described_class.create_job(
+        "my-job",
+        role_arn: "arn:aws:iam::123:role/GlueRole",
+        script_path: "scripts/glue/export.py",
+        script_bucket: "my-bucket"
+      )
+    end
+  end
+
+  it "levanta ConfigurationError si script_path sin script_bucket" do
+    expect {
+      described_class.create_job(
+        "my-job",
+        role_arn: "arn:aws:iam::123:role/GlueRole",
+        script_path: "/local/script.py"
+      )
+    }.to raise_error(DataDrain::ConfigurationError, /script_bucket/)
+  end
+
+  it "levanta ConfigurationError si script_path y script_location ambos" do
+    expect {
+      described_class.create_job(
+        "my-job",
+        role_arn: "arn:aws:iam::123:role/GlueRole",
+        script_path: "/local/script.py",
+        script_location: "s3://b/s.py",
+        script_bucket: "b"
+      )
+    }.to raise_error(DataDrain::ConfigurationError, /no ambos/)
+  end
+
+  it "levanta ArgumentError si no se provee ni script_location ni script_path" do
+    expect {
+      described_class.create_job("my-job", role_arn: "arn:aws:iam::123:role/GlueRole")
+    }.to raise_error(ArgumentError, /requerido/)
+  end
+end
+
+describe ".ensure_job con script_path" do
+  # ... test passthrough completo ...
+end
+```
+
+---
+
+## 5. Docs
+
+### 5.1 `docs/glue-jobs-lifecycle.md`
+
+Agregar sección "Subir scripts locales (v0.5.0+)":
+
+```markdown
+## Subir scripts locales
+
+Desde v0.5.0 la gema puede subir scripts PySpark a S3 automáticamente. En lugar de:
+
+    # 1. Upload manual
+    # aws s3 cp scripts/glue/export.py s3://bucket/scripts/
+
+    # 2. Create job
+    DataDrain::GlueRunner.create_job(
+      "my-job",
+      script_location: "s3://bucket/scripts/export.py",
+      role_arn: "arn:aws:iam::123:role/GlueRole"
+    )
+
+Usar `script_path:` local:
+
+    DataDrain::GlueRunner.create_job(
+      "my-job",
+      script_path: "scripts/glue/export.py",  # local
+      script_bucket: "my-bucket",
+      script_folder: "scripts",
+      role_arn: "arn:aws:iam::123:role/GlueRole"
+    )
+    # → Sube a s3://my-bucket/scripts/export.py
+    # → Crea el job
+
+**`script_filename:`** opcional para override del nombre en S3 (default: basename).
+
+**Importante:** el upload **sobrescribe** cualquier archivo existente en el mismo path.
+No es idempotente en sentido estricto. Si varios callers usan el mismo `script_bucket`
++ `script_folder` + nombre, gana el último. Usar nombres únicos o buckets separados
+por servicio.
+
+### Concurrencia (limitación conocida)
+
+No hay lock distribuido. Si dos procesos llaman `upload_script` con el mismo destino
+simultáneamente, el último `put_object` en llegar a S3 gana. Para scripts PySpark
+esto es típicamente bajo riesgo (scripts son pequeños, rara vez hay writes
+concurrentes al mismo path). Si necesitás coordinación estricta:
+
+- Usar `filename:` con identificador único (hash del contenido, timestamp, run_id)
+- O lock externo (DynamoDB, Redis) antes de `upload_script`
+
+### Permisos IAM mínimos
+
+El IAM role/user que ejecuta `upload_script` necesita:
+
+    {
+      "Effect": "Allow",
+      "Action": ["s3:PutObject"],
+      "Resource": "arn:aws:s3:::my-bucket/scripts/*"
+    }
+
+Para usar con `create_job`/`ensure_job` también se necesitan los permisos de Glue
+(ver sección "Permisos Glue" al inicio de este documento) + permiso para que el
+IAM role del Glue Job pueda leer el script:
+
+    {
+      "Effect": "Allow",
+      "Action": ["s3:GetObject"],
+      "Resource": "arn:aws:s3:::my-bucket/scripts/*"
+    }
+
+(Este último en el role del Glue Job, no en el role de la aplicación Ruby.)
+
+### API standalone: `upload_script`
+
+Para casos donde solo querés subir (sin crear Job):
+
+    s3_path = DataDrain::GlueRunner.upload_script(
+      local_path: "scripts/glue/export.py",
+      bucket: "my-bucket",
+      folder: "scripts"
+    )
+    # => "s3://my-bucket/scripts/export.py"
+```
+
+### 5.2 `skill/SKILL.md` FAQ
+
+Agregar:
+
+```markdown
+### ¿Cómo subo un script Glue desde mi repo?
+
+Desde v0.5.0 podés usar `script_path:` en lugar de `script_location:`:
+
+    DataDrain::GlueRunner.ensure_job(
+      "my-export-job",
+      script_path: "scripts/glue/export.py",
+      script_bucket: "my-bucket",
+      script_folder: "scripts",
+      role_arn: ENV["GLUE_ROLE_ARN"]
+    )
+
+La gema sube el script a S3 usando el `Storage::S3` adapter existente
+(con `credential_chain` si tenés IAM role). **Requiere `storage_mode = :s3`**.
+Si `storage_mode = :local`, levanta `ConfigurationError`.
+
+**Overwrite:** cada invocación sobrescribe el archivo en S3. Útil para que
+el script siga al código del repo. Si necesitás versionar, usar `script_filename:`
+con hash o timestamp.
+```
+
+### 5.3 `skill/references/api-detallada.md`
+
+Agregar sección GlueRunner con los 3 métodos nuevos/modificados.
+
+### 5.4 `skill/references/eventos-telemetria.md`
+
+Agregar:
+
+```markdown
+### `glue_runner.script_uploaded`
+**Nivel:** INFO.
+**Campos:** `local_path`, `s3_path`, `bytes`.
+
+### `glue_runner.script_upload_error`
+**Nivel:** ERROR.
+**Campos:** `local_path`, `bucket`, `error_class`, `error_message`.
+**Consecuencia:** propaga el `Aws::S3::Errors::ServiceError`.
+```
+
+### 5.5 `docs/glue_pyspark_example.py`
+
+El docstring del archivo ya tiene un ejemplo de `ensure_job` con `script_location`. Agregar variante con `script_path`:
+
+```python
+"""
+# Opción moderna: script local subido por la gema (v0.5.0+)
+DataDrain::GlueRunner.ensure_job(
+  "my-export-job",
+  script_path: "docs/glue_pyspark_example.py",
+  script_bucket: "my-bucket",
+  script_folder: "scripts",
+  role_arn: "arn:aws:iam::123:role/GlueServiceRole",
+  worker_type: "G.1X",
+  number_of_workers: 10,
+  timeout: 1440
+)
+# → Sube este archivo a s3://my-bucket/scripts/glue_pyspark_example.py
+# → Crea el Job apuntando a ese path
+"""
+```
+
+### 5.6 README
+
+Agregar 3 líneas en la sección "Orquestación con AWS Glue" apuntando a docs detalle.
+
+### 5.7 CHANGELOG
+
+```markdown
+## [0.5.0] - 2026-04-XX
+
+### Features
+- `Storage::S3#upload_file` y `Storage::Local#upload_file` — primitiva para subir archivos al storage configurado. (item 37)
+- `GlueRunner.upload_script(local_path:, bucket:, folder:, filename:)` — sube script Python local a S3 usando el `Storage::S3` adapter existente. Emite `glue_runner.script_uploaded` (INFO) y `glue_runner.script_upload_error` (ERROR). (item 37)
+- `GlueRunner.create_job` y `GlueRunner.ensure_job` aceptan `script_path:` + `script_bucket:` + `script_folder:` + `script_filename:` para subir scripts locales automáticamente. Si se usa `script_location:`, comportamiento idéntico al anterior. (item 37)
+
+### Docs
+- `docs/glue-jobs-lifecycle.md` — sección "Subir scripts locales" con patrón completo.
+- `docs/glue_pyspark_example.py` — ejemplo de uso con `script_path`.
+
+### Notas
+- **Upload NO es idempotente en sentido estricto:** `put_object` sobrescribe siempre. Documentado.
+- `upload_script` requiere `storage_mode = :s3`. En `:local` levanta `ConfigurationError`.
+```
+
+---
+
+## 6. Estimación
+
+| Fase | Resumen | Estimación |
+|------|---------|------------|
+| 0 | Setup + marcar item 37 `[~]` en roadmap | 10min |
+| 1 | `Storage::Base#upload_file` abstract + specs | 30min |
+| 2 | `Storage::S3#upload_file` + specs | 1h |
+| 3 | `Storage::Local#upload_file` + specs | 30min |
+| 4 | `GlueRunner.upload_script` + specs (happy, error, storage_mode, bytes, filename) | 1.5h |
+| 5 | `resolve_script_location` helper + integrar en `create_job` y `ensure_job` + specs | 1.5h |
+| 6 | Docs (`glue-jobs-lifecycle.md`, SKILL FAQ, `api-detallada.md`, eventos, PySpark example, README) | 1-1.5h |
+| 7 | Release (CHANGELOG, version bump, tag) | 30min |
+
+**Total:** 6-7h, 1 día enfocado.
+
+**Breaking:** ninguno. `script_location:` sigue siendo aceptado; ahora es opcional en favor de `script_path:`. Callers existentes no tocan.
+
+---
+
+## 7. Plan B — escenarios de bloqueo
+
+| Si... | Entonces... |
+|-------|-------------|
+| `Storage::S3#upload_file` no logra abrir archivos binarios grandes (OOM) | Stream chunked con `Aws::S3::Client#upload_file` (multipart). No en scope v0.5.0 inicial, abrir como item 38 post-release. |
+| Permisos S3 faltantes (`s3:PutObject`) | Error AWS propagado, `glue_runner.script_upload_error` log. Caller ajusta IAM policy. Documentar set mínimo en skill. |
+| `content_type: "text/x-python"` rechazado por S3 | S3 acepta cualquier content_type. Si aparece issue, hacer opcional (default nil → S3 infiere). |
+| Glue Job existente apunta a S3 path y cambiar `script_path` a otro nombre deja archivo huérfano | Documentar. Opcional futuro: limpieza con `delete_object` al cambiar filename. |
+| `ensure_job` con `script_path` corre 2 veces seguidas → 2 uploads innecesarios | Aceptable en v0.5.0. Futuro (item 38): check ETag/MD5 antes de upload para short-circuit. |
+| Tests `put_object` con body=File stub no funciona correctamente | Usar `stub_responses` con lambda que inspecciona params, como en S3 specs de v0.3.1. |
+| `Storage::Local#upload_file` es "cheating" (copia local) sin sentido | Si molesta, dejarlo como `raise NotImplementedError` y que `upload_script` valide `storage_mode` estrictamente. No bloqueante. |
+
+---
+
+## 8. Orden de ejecución
+
+```
+Fase 0: setup
+   │
+   ▼
+Fase 1: Storage::Base#upload_file abstract
+   │
+   ▼
+Fase 2: Storage::S3#upload_file + tests
+   │
+   ▼
+Fase 3: Storage::Local#upload_file + tests
+   │
+   ▼
+Fase 4: GlueRunner.upload_script + tests (usa Storage adapter)
+   │
+   ▼
+Fase 5: resolve_script_location + integrar en create_job + ensure_job + tests
+   │
+   ▼
+Fase 6: Docs (lifecycle, SKILL, api, eventos, pyspark example, README)
+   │
+   ▼
+Fase 7: Release (CHANGELOG + bump + tag)
+```
+
+Cada fase cierra con `bundle exec rspec` + `bundle exec rubocop` verdes antes de avanzar.
+
+---
+
+## 9. Roadmap — items nuevos
+
+Agregar a `docs/IMPROVEMENT_PLAN.md` sección "Follow-ups post-roadmap":
+
+- **Item 37** (v0.5.0) — Upload de scripts a S3 desde `GlueRunner`. Primitiva `Storage::*#upload_file` + `GlueRunner.upload_script` + integración en `create_job`/`ensure_job` via `script_path:`.
+- **Item 38** (futuro) — `upload_script` idempotente con check ETag/MD5.
+- **Item 39** (futuro) — multipart upload para scripts grandes (>5MB).
+
+---
+
+## 10. Revisor debería verificar
+
+1. **¿El `Storage::S3#upload_file` reutiliza `s3_client` private existente?** (debe hacerlo, no crear client paralelo)
+2. **`script_bucket` no colisiona con `bucket` de Engine/FileIngestor/Record.** (renombre aplicado)
+3. **`glue_runner.script_uploaded` / `script_upload_error` siguen Wispro-Observability-Spec v1** (component/event primero, snake_case, `bytes` Integer, sin unidades)
+4. **`resolve_script_location` es `@api private`** con `private_class_method`
+5. **Tests cubren los 4 errores de validación** (script_path sin bucket, ambos seteados, ninguno seteado, local no existe)
+6. **`ensure_job` test con script_path** verifica passthrough y diff correcto post-upload
+7. **`docs/glue_pyspark_example.py` actualizado** con ejemplo script_path
+8. **No romper callers existentes:** `script_location:` sigue funcionando idéntico
+
+---
+
+## 11. Items relacionados
+
+- **v0.4.0 items 32-36** (Glue Jobs Lifecycle) — este feature extiende `create_job`/`ensure_job`.
+- **v0.3.0 item 6** (sandboxing Record) — no relacionado directamente, pero confirmar que `Storage::S3#upload_file` no rompe sandbox (no usa DuckDB, OK).
+- **Storage Adapter pattern** — establecido en v0.2.0. Este plan agrega nueva operación sin romper la interfaz.