Saltar a contenido

SOURCE-003 Load Raw Local Dev Execution Gate

Fecha local: 2026-06-15

Estado: GATE DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LOAD-RAW-LOCAL-DEV-EXECUTION-GATE.md

1. Objetivo

Definir documentalmente el gate obligatorio para una futura implementacion y ejecucion controlada local-dev de:

powershell python scripts/source_003_importer.py load-raw --execute

Este documento no implementa el comando, no ejecuta el comando, no modifica Python, no toca PostgreSQL, no genera CSV y no carga datos.

2. Safe point

Control Resultado
workspace C:\APV\openclawai
rama main
git status --short --branch inicial ## main...origin/main
git rev-parse HEAD inicial cd171d81a888dd2ac886eab6035be62be23629c0
git rev-parse origin/main inicial cd171d81a888dd2ac886eab6035be62be23629c0
ultimo commit observado cd171d8 docs: review source 003 load raw safe mode
decision SAFE POINT PASS

3. Alcance permitido

El gate aplica solo a una tarea futura separada de implementacion local-dev.

Control Valor obligatorio
database permitida openclaw_business_observer_dev
schema business_observer
tabla destino business_observer.raw_source_003_sales_items
tenant alpuntodeventa
source SOURCE-003
batch permitido 1827f887-9499-4579-b4f3-234d54f41f7f
filas esperadas 1886
columnas prepared CSV 83
columnas destino RAW 84
row_count RAW inicial 0
fecha del batch piloto 2026-06-09

El gate no habilita produccion, sync diaria, carga masiva, OpenClaw executor, runner, VPS, Docker, NPM, Portainer, push ni deploy.

4. Preconditions obligatorias

Antes de implementar cualquier escritura futura deben pasar todas estas precondiciones:

  • main limpio y alineado con origin/main;
  • tarea futura con autorizacion humana explicita para implementar escritura;
  • scripts/source_003_importer.py revisado antes de tocarlo;
  • load-raw --execute aun bloqueado al inicio de la tarea futura;
  • validate-prepared en PASS;
  • prepared CSV historico existente, validado y fuera de Git;
  • generated CSV existente, validado y fuera de Git;
  • ambos CSV con 1886 filas, 83 columnas, fecha unica 2026-06-09, record_status = active, batch exacto 1827f887-9499-4579-b4f3-234d54f41f7f, line_key no vacio y source_row_hash no vacio;
  • sha256 prepared historico: 3f16a957a79fc84d4ca37930988287cb81f05166210d057fcf8b45007f184afe;
  • sha256 generated: 6fb44d9870a567e728df9bbdcc6b83279d84791bd732626c9e19ccf3a28dc903;
  • comparacion prepared vs generated aceptada como REPRODUCIBLE ESTRUCTURAL ACEPTADO, con diferencia esperada solo en id;
  • tabla RAW existente en openclaw_business_observer_dev;
  • business_observer.raw_source_003_sales_items con 84 columnas;
  • row_count inicial de la tabla RAW igual a 0;
  • fingerprint DB observado y aprobado antes de escribir;
  • politica de idempotencia aprobada;
  • rollback por batch documentado y probado en dry-run o revision separada;
  • evidencia minima definida antes de ejecutar.

Si falta una sola precondicion, el futuro comando debe terminar en BLOCKED o FAIL antes de escribir.

5. Fingerprint DB obligatorio

La futura implementacion debe bloquear cualquier escritura si no puede probar el fingerprint exacto de la DB local-dev autorizada.

Fingerprint aprobado vigente:

text ::1/128:5432|openclaw_business_observer_dev|postgres|PostgreSQL 15.15, compiled by Visual C++ build 1944, 64-bit

Reglas:

  • el fingerprint debe calcularse en la misma sesion que escribira;
  • current_database() debe ser openclaw_business_observer_dev;
  • el target efectivo debe ser business_observer.raw_source_003_sales_items;
  • si el fingerprint no coincide, resultado BLOCKED;
  • si la DB observada no coincide, resultado BLOCKED;
  • si la tabla no existe o no tiene 84 columnas, resultado FAIL;
  • si row_count inicial no es 0, resultado BLOCKED salvo politica de idempotencia aprobada y documentada para ese caso.

6. Flags de autorizacion futuros

--execute no alcanza por si solo. La futura CLI debe exigir confirmaciones exactas y redundantes.

Flags minimos requeridos:

powershell python scripts/source_003_importer.py load-raw --execute ` --tenant-id alpuntodeventa ` --source-id SOURCE-003 ` --target-database openclaw_business_observer_dev ` --target-table business_observer.raw_source_003_sales_items ` --sync-batch-id 1827f887-9499-4579-b4f3-234d54f41f7f ` --expected-rows 1886 ` --expected-destination-columns 84 ` --expected-prepared-sha256 3f16a957a79fc84d4ca37930988287cb81f05166210d057fcf8b45007f184afe ` --expected-generated-sha256 6fb44d9870a567e728df9bbdcc6b83279d84791bd732626c9e19ccf3a28dc903 ` --expected-db-fingerprint "<fingerprint-aprobado>" ` --i-understand-this-writes-local-dev-raw ` --i-confirm-raw-table-is-empty ` --i-confirm-rollback-by-batch-is-approved

Reglas:

  • los valores deben compararse por igualdad exacta;
  • no aceptar defaults silenciosos para DB, tabla, batch, filas, hashes ni fingerprint en modo --execute;
  • no aceptar comodines, prefijos ni aliases;
  • no permitir --execute desde jobs automaticos o scheduler;
  • mantener sync_enabled=false.

7. Validaciones pre-write

Antes de cualquier COPY, INSERT o UPDATE, la futura implementacion debe validar:

  • SAFE POINT de repo y commit registrado;
  • archivos prepared historico y generated existen;
  • ambos CSV estan fuera de Git;
  • ambos CSV tienen sha256 esperado;
  • ambos CSV tienen 1886 filas;
  • ambos CSV tienen 83 columnas;
  • batch unico exacto;
  • fecha unica 2026-06-09;
  • record_status = active;
  • 0 filas con line_key vacio;
  • 0 filas con source_row_hash vacio;
  • 0 duplicados criticos por tenant_id + line_key;
  • prepared vs generated con estructura aceptada;
  • DB fingerprint aprobado;
  • tabla destino correcta;
  • columnas destino 84;
  • row_count inicial 0;
  • grants y owner compatibles con el DDL aprobado;
  • writer sin DELETE;
  • PUBLIC sin privilegios;
  • transaccion iniciada y ON_ERROR_STOP equivalente activo;
  • logs preparados sin secretos.

8. Transaccion esperada

La escritura futura debe ser atomica.

text BEGIN validar fingerprint DB en la sesion bloquear si current_database() != openclaw_business_observer_dev bloquear si target != business_observer.raw_source_003_sales_items crear staging temporal o area controlada de carga cargar CSV validado a staging validar row_count staging = 1886 validar batch staging exacto validar line_key/source_row_hash no vacios validar duplicados internos insertar o mergear hacia RAW segun politica aprobada validar RAW pre-commit COMMIT solo si todos los checks pasan ROLLBACK ante cualquier fallo previo al commit

Reglas duras:

  • no escribir directo sin staging o validacion intermedia;
  • no hacer COMMIT si algun conteo, hash, batch, columna o fingerprint falla;
  • no ejecutar TRUNCATE;
  • no ejecutar DELETE dentro de load-raw;
  • no modificar batches ajenos;
  • no promover a core o mart;
  • no activar sync diaria.

9. Validaciones post-write

Despues de escribir y antes del COMMIT, la futura implementacion debe validar:

  • filas RAW para el batch = 1886;
  • filas RAW totales esperadas = 1886 si la tabla estaba vacia;
  • tenant_id = alpuntodeventa;
  • source_id o metadata equivalente = SOURCE-003, si aplica;
  • sync_batch_id exacto;
  • record_status = active;
  • 0 line_key vacios;
  • 0 source_row_hash vacios;
  • 0 duplicados por clave logica aprobada;
  • 84 columnas destino disponibles;
  • checks y constraints sin violaciones;
  • loaded_at informado;
  • hashes de evidencia preservados en logs;
  • flags finales: db_write=true, sql_write=true, data_written=true, rollback_executed=false, sync_enabled=false.

Si una validacion post-write falla antes del commit, debe ejecutarse ROLLBACK transaccional y el resultado debe ser FAIL.

10. Rollback por batch

El rollback de datos commiteados no debe vivir dentro de load-raw.

Comando futuro separado esperado:

powershell python scripts/source_003_importer.py rollback-batch --execute

Reglas:

  • rollback solo por tenant_id + source_id + sync_batch_id;
  • fingerprint DB obligatorio;
  • batch exacto obligatorio;
  • conteo esperado obligatorio;
  • aprobacion humana separada;
  • evidencia antes y despues;
  • bloquear si hay dependencias en core, mart, reportes o sync posterior;
  • prohibido TRUNCATE;
  • prohibido borrar batches ajenos;
  • prohibido rollback automatico desde load-raw.

11. Reintento e idempotencia

La politica futura debe evitar duplicacion y reintentos ambiguos.

Caso Resultado esperado
tabla RAW vacia y batch validado puede escribir si todos los gates pasan
mismo batch, mismo contenido ya cargado PASS_IDEMPOTENT o BLOCKED, segun politica aprobada
mismo batch, contenido distinto BLOCKED
batch ya existe con conteo distinto BLOCKED
tenant_id + sync_batch_id + line_key duplicado BLOCKED o merge gobernado antes de escribir
source_row_hash cambia para la misma linea BLOCKED salvo politica explicita de versionado
fallo antes de commit ROLLBACK transaccional y reintento permitido tras evidencia
fallo despues de commit no reintentar sin auditoria y posible rollback-batch separado

La primera implementacion recomendada para este batch piloto es conservadora: si el batch ya existe en RAW, bloquear y exigir decision humana.

12. Evidencia minima requerida

La tarea futura de implementacion/ejecucion debe registrar como minimo:

  • SAFE POINT inicial y final;
  • comando exacto ejecutado, sin secretos;
  • commit inicial;
  • operador o aprobacion humana;
  • ruta de prepared historico;
  • ruta de generated CSV;
  • sha256 esperados y observados;
  • row count y column count de CSV;
  • batch, tenant, source y fecha;
  • fingerprint DB esperado y observado;
  • DB, schema y tabla destino;
  • row_count RAW antes;
  • columnas RAW observadas;
  • validaciones pre-write;
  • detalle de staging;
  • filas insertadas/actualizadas/ignoradas;
  • validaciones post-write;
  • decision COMMIT o ROLLBACK;
  • flags de auditoria;
  • git diff --check;
  • .venv-portal\Scripts\mkdocs.exe build --strict;
  • commit documental posterior.

Los logs no deben imprimir passwords, tokens, connection strings completas ni secretos.

13. Criterio PASS/FAIL

PASS solo es valido si:

  • todas las precondiciones pasan;
  • fingerprint DB coincide;
  • DB y tabla son las autorizadas;
  • row_count inicial RAW es 0;
  • CSV prepared/generated estan validados;
  • se escriben exactamente 1886 filas;
  • la tabla destino mantiene 84 columnas;
  • todas las validaciones post-write pasan antes del commit;
  • hay COMMIT unico y trazado;
  • no se activa sync;
  • evidencia minima completa queda documentada.

FAIL aplica si:

  • ocurre error tecnico o de validacion antes del commit;
  • staging o RAW no concilian;
  • se ejecuta rollback transaccional por falla;
  • falta evidencia requerida.

BLOCKED aplica si:

  • falta autorizacion humana;
  • falta flag exacto;
  • fingerprint DB no coincide;
  • DB/tabla/batch/hashes no coinciden;
  • RAW no esta vacia y no hay politica idempotente aprobada;
  • se intenta produccion, VPS, Docker, runner, sync diaria o scheduler.

14. Riesgos

  • interpretar un DRY_RUN como permiso de escritura;
  • confundir tabla piloto con RAW final;
  • duplicar el batch 1827f887-9499-4579-b4f3-234d54f41f7f;
  • aceptar drift entre prepared historico y generated fuera de la diferencia conocida de id;
  • escribir con fingerprint DB incorrecto;
  • hacer commit parcial;
  • implementar rollback demasiado amplio;
  • avanzar a produccion o sync diaria sin contrato operativo.

15. Decision

text GATE DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO APTO PARA IMPLEMENTAR LOAD-RAW --EXECUTE EN TAREA FUTURA LOCAL-DEV NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA

La tabla RAW local-dev existe vacia y el safe mode previo esta revisado, por lo que este gate deja documentadas las condiciones minimas para una futura implementacion controlada de load-raw --execute. Esa futura tarea debe abrir un SAFE POINT nuevo y pedir autorizacion explicita antes de modificar Python o tocar PostgreSQL.