SOURCE-003 Promote Core Local Dev Execution Gate¶

Fecha local: 2026-06-15

Estado: GATE PROMOTE-CORE 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-PROMOTE-CORE-LOCAL-DEV-EXECUTION-GATE.md

1. Objetivo¶

Definir documentalmente el gate futuro para:

powershell python scripts/source_003_importer.py promote-core --execute

Este gate solo disena las condiciones para una futura implementacion local-dev. No implementa Python, no ejecuta el importer, no toca PostgreSQL, no ejecuta SQL, no escribe en CORE, no modifica RAW, no carga datos, no genera CSV y no habilita runner, VPS, Docker, OpenClaw, NPM, Portainer, push ni deploy.

2. Safe point documental¶

Control	Resultado
workspace	`C:\APV\openclawai`
rama	`main`
`git status --short` inicial	limpio
`git rev-parse HEAD` inicial	`ab71f58c2e4c0f6f9650edaa549cd6f821b096a9`
ultimo commit inicial	`ab71f58 docs: review source 003 promote core safe mode`
decision	`SAFE POINT PASS`

3. Documentos base leidos¶

scripts/source_003_importer.py
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-PROMOTE-CORE-SAFE-MODE-TECHNICAL-REVIEW.md
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-IMPORTER-PROMOTE-CORE-PLAN.md
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CORE-DDL-LOCAL-DEV-FORWARD-001.md
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LOAD-RAW-LOCAL-DEV-POST-EXECUTION-REVIEW.md

4. Alcance permitido¶

El futuro promote-core --execute solo puede operar bajo estas constantes:

Control	Valor obligatorio
DB permitida	`openclaw_business_observer_dev`
schema	`business_observer`
RAW source	`business_observer.raw_source_003_sales_items`
CORE target	`business_observer.core_source_003_sales_items`
batch permitido	`1827f887-9499-4579-b4f3-234d54f41f7f`
RAW batch rows requeridas	`1886`
CORE row_count inicial requerido	`0`
filas esperadas a promover	`1886`
columnas CORE destino	`66`
tenant_id	`alpuntodeventa`
source_id	`SOURCE-003`

Queda prohibido usar business_observer.source_003_sales_items como origen de promocion. Esa tabla sigue siendo antecedente piloto, no fuente RAW gobernada.

5. Fingerprint DB obligatorio¶

El comando futuro debe bloquear cualquier escritura si no puede probar el fingerprint DB antes de escribir.

Fingerprint local-dev aprobado para este gate:

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

Reglas:

current_database() debe ser openclaw_business_observer_dev;
el fingerprint observado debe coincidir exactamente con una lista aprobada;
si el host, puerto, usuario, version o DB cambian, resultado BLOCKED;
el fingerprint debe quedar en la salida JSON y en la evidencia minima;
no se permite inferir local-dev solo por nombre de variable o .env.

6. postgres-sandbox prohibido¶

postgres-sandbox queda prohibido para promote-core --execute.

El comando futuro debe inspeccionar, como minimo, valores de entorno y conexion relacionados con PGHOST, PGDATABASE, APV_LOCAL_POSTGRES_ADMIN_* y APV_BO_LOCAL_POSTGRES_*.

Si aparece postgres-sandbox en host, DB, ruta, variable o metadata de conexion, el resultado debe ser BLOCKED antes de cualquier SQL de escritura.

7. Confirmaciones futuras requeridas¶

El futuro modo write debe exigir confirmaciones explicitas. Sin todas ellas, el resultado debe ser BLOCKED y db_write=false.

Flags candidatos requeridos:

powershell --confirm-local-dev --confirm-write-local-dev --confirm-tenant-id alpuntodeventa --confirm-source-id SOURCE-003 --confirm-target-database openclaw_business_observer_dev --confirm-raw-source business_observer.raw_source_003_sales_items --confirm-core-target business_observer.core_source_003_sales_items --confirm-batch 1827f887-9499-4579-b4f3-234d54f41f7f --confirm-raw-batch-rows 1886 --confirm-core-empty --confirm-core-initial-row-count 0 --confirm-promote-row-count 1886 --confirm-core-columns 66 --confirm-db-fingerprint "<fingerprint aprobado>"

Reglas:

los valores deben coincidir exactamente;
no se aceptan confirmaciones parciales;
no se aceptan defaults silenciosos para batch, DB, RAW o CORE;
las confirmaciones deben aparecer en salida JSON sin secretos;
cualquier mismatch debe bloquear antes de preparar escritura.

8. Transformacion RAW -> CORE¶

La promocion futura debe transformar evidencia RAW a registros CORE normalizados, sin enriquecer con otras fuentes ni calcular MART.

Mapeo minimo obligatorio:

RAW	CORE
`tenant_id`	`tenant_id`
`sync_batch_id`	`sync_batch_id`
`line_key`	`line_key`
`line_sequence`	`line_sequence`
`source_row_hash`	`source_row_hash`
`source_system`	`source_system`
`source_object`	`source_object`
`source_query_version`	`source_query_version`
`extracted_at`	`extracted_at`
`loaded_at`	`raw_loaded_at`
fecha comercial RAW	`business_date`
hora RAW	`document_time_raw`; `document_time` si convierte
comprobante RAW	`document_type`, `document_number`, `document_status`, `document_internal_type`, `document_internal_number`, `document_label`
cliente RAW	`customer_code`, `customer_name`, `customer_tax_id`, `customer_status_raw`
producto RAW	`sku`, `product_name`, `brand`, `supplier_code`, `supplier_name`
vendedor/canal RAW	`seller_code`, `seller_name`, `channel_raw`, `channel_normalized`
cantidades RAW	`quantity`, `unit_quantity`, `package_quantity`
importes RAW	`unit_price`, `gross_amount`, `net_amount`, `discount_rate_pct`, `discount_amount`, `tax_rate_pct`, `tax_amount`, `iibb_amount`, `vat_amount`, `cost_amount`, `contribution_amount`
entrega RAW	`route_sheet_raw`, `delivery_address_raw`, `delivery_city_raw`, `delivery_province_raw`, `delivery_driver_code`, `delivery_driver_name`, `logistic_zone_raw`
`record_status`	`core_record_status`

Columnas tecnicas CORE obligatorias:

id generado en forma deterministica o gobernada por el importer futuro;
promoted_at, created_at, updated_at resueltos por DB o politica transaccional documentada;
last_seen_at, missing_from_source, valid_from, valid_to;
quality_status, quality_notes, created_by, updated_by.

Reglas de transformacion:

aplicar trim lateral a textos;
convertir vacios sin valor semantico a NULL solo en columnas nullable;
preservar codigos como texto canonico;
convertir fecha a date y hora a time solo si el valor es valido;
usar numeric, nunca float, para cantidades e importes;
no inventar channel_normalized sin catalogo aprobado;
no corregir importes sin regla documentada;
no hacer hard delete;
no construir MART ni KPIs agregados.

9. Reglas de idempotencia¶

El futuro promote-core --execute debe ser idempotente por batch y por linea.

Reglas obligatorias:

reintentar el mismo batch con el mismo contenido no duplica registros;
inserted + updated + unchanged + blocked = 1886;
si CORE esta vacia, la promocion esperada inicial es inserted = 1886;
si el batch ya fue promovido con mismos hashes, debe reportar unchanged = 1886 o BLOCKED segun decision implementada, pero nunca duplicar;
si existe tenant_id + line_key con distinto source_row_hash, debe quedar BLOCKED salvo que exista politica aprobada de update/invalidacion;
toda escritura debe quedar trazable por tenant_id, sync_batch_id, line_key y source_row_hash.

La clave logica vigente es:

text tenant_id + line_key

La clave de promocion por batch vigente es:

text tenant_id + sync_batch_id + line_key

10. Bloqueo por batch duplicado¶

Antes de escribir, el comando futuro debe verificar si el batch permitido ya existe en CORE.

Debe bloquear si:

sync_batch_id distinto del batch autorizado;
existen filas CORE para el batch autorizado y no se esta ejecutando un modo explicito de verificacion idempotente;
existen filas CORE para el batch autorizado con conteo distinto de 1886;
existen filas CORE para el batch autorizado con hashes distintos de RAW;
existen duplicados por tenant_id + sync_batch_id + line_key;
existe conflicto por tenant_id + line_key contra otro batch sin politica aprobada de reemplazo.

El bloqueo por batch duplicado debe ocurrir antes de cualquier INSERT o UPDATE.

11. Transaccion esperada¶

La promocion futura debe ejecutarse en una unica transaccion controlada:

BEGIN
fingerprint DB y bloqueo postgres-sandbox
validaciones pre-write
staging transaccional o CTE gobernado desde RAW
plan de cambios esperado
escritura CORE si y solo si todos los checks pasan
validaciones post-write dentro de la misma transaccion
COMMIT si todo queda en PASS
ROLLBACK ante cualquier FAIL o BLOCKED

Reglas:

ON_ERROR_STOP o equivalente debe estar activo;
no se permite autocommit para escrituras;
no se permite TRUNCATE;
no se permite DELETE para rollback normal;
los errores deben dejar data_written=false si hubo rollback efectivo;
la salida JSON debe informar transaction_committed y rollback_executed.

12. Validaciones pre-write¶

Checks obligatorios antes de cualquier escritura:

Check	Esperado
DB observada	`openclaw_business_observer_dev`
fingerprint	coincide con aprobado
`postgres-sandbox`	no observado
RAW source existe	`true`
CORE target existe	`true`
RAW batch rows	`1886`
RAW total rows para este gate	`1886`
CORE row_count inicial	`0`
CORE columnas	`66`
`tenant_id` unico RAW	`alpuntodeventa`
`source_row_hash` vacios RAW	`0`
`line_key` vacios RAW	`0`
`loaded_at` nulos RAW	`0`
duplicados RAW por `tenant_id + line_key`	`0`
duplicados CORE por clave aprobada	`0`
filas candidatas RAW -> CORE	`1886`
conversiones fecha/hora/numeric	sin errores
`quality_status` esperado	`valid`, `warning` o `blocked`
plan de cambios	calculado antes de escribir

Si cualquier check falla, resultado FAIL o BLOCKED sin escritura.

13. Validaciones post-write¶

Checks obligatorios despues de escribir y antes de COMMIT:

Check	Esperado
filas CORE del batch	`1886`
filas afectadas	`inserted + updated + unchanged = 1886`
`blocked`	`0`
`tenant_id` unico CORE	`alpuntodeventa`
`sync_batch_id` unico CORE	`1827f887-9499-4579-b4f3-234d54f41f7f`
`line_key` vacios CORE	`0`
`source_row_hash` vacios CORE	`0`
duplicados CORE por `tenant_id + line_key`	`0`
duplicados CORE por `tenant_id + sync_batch_id + line_key`	`0`
`promoted_at` nulos	`0`
`raw_loaded_at` nulos	`0`
cantidades conciliadas RAW vs CORE	`PASS`
importes conciliados RAW vs CORE	`PASS`
conteos por `business_date`	conciliados contra RAW
auditabilidad CORE -> RAW	`PASS`
`sync_enabled`	`false`

Si un post-check falla, debe ejecutarse ROLLBACK y el resultado debe ser FAIL, no PASS.

14. Rollback / rebuild por batch¶

El rollback futuro de CORE debe estar disenado antes de habilitar escritura.

Reglas obligatorias:

exigir tenant_id = alpuntodeventa;
exigir sync_batch_id exacto;
exigir conteo esperado de filas a afectar;
exigir fingerprint DB aprobado;
exigir confirmacion humana separada;
prohibir TRUNCATE;
prohibir borrados sin filtro completo de batch;
bloquear rollback si MART ya depende del batch sin plan de rebuild;
preferir invalidacion logica con core_record_status, valid_to o missing_from_source antes que borrar evidencia;
dejar evidencia de invalidated, replaced, unchanged y blocked.

Rebuild por batch candidato:

aislar o invalidar registros CORE del batch;
reconstruir desde business_observer.raw_source_003_sales_items;
aplicar solo transformaciones CORE aprobadas;
reconciliar conteos, claves, cantidades, importes y hashes;
dejar evidencia antes de habilitar cualquier MART.

15. Evidencia minima¶

La tarea futura que implemente o ejecute promote-core --execute debe dejar, como minimo:

SAFE POINT inicial y final;
comando exacto ejecutado sin secretos;
confirmaciones recibidas;
fingerprint DB observado;
evidencia de bloqueo postgres-sandbox;
RAW source, CORE target y batch;
conteos pre-write;
plan de cambios esperado;
conteos post-write;
resumen de inserted, updated, unchanged, blocked;
estado de transaccion: committed o rollback;
salida JSON del importer;
git diff --check;
build estricto de MkDocs si se modifica documentacion;
conclusion explicita sobre produccion y sync diaria.

16. Criterio PASS / FAIL / BLOCKED¶

PASS solo es valido si:

todas las confirmaciones coinciden;
fingerprint DB coincide;
no aparece postgres-sandbox;
RAW batch rows = 1886;
CORE row_count inicial = 0;
filas promovidas o idempotentes = 1886;
CORE queda sin duplicados y con trazabilidad completa;
post-checks pasan dentro de la transaccion;
sync_enabled=false;
no se toca produccion.

FAIL corresponde cuando:

una validacion tecnica falla;
hay conversiones invalidas;
los conteos o conciliaciones no cierran;
la transaccion debe revertirse por error.

BLOCKED corresponde cuando:

faltan confirmaciones;
el fingerprint no coincide;
aparece postgres-sandbox;
el batch no es el autorizado;
el batch ya existe en CORE sin politica idempotente aprobada;
hay conflicto de hash o clave;
el alcance intenta produccion, sync diaria, runner, VPS, Docker, OpenClaw, NPM, Portainer, push o deploy.

17. Riesgos y limites¶

promote-core --execute no esta implementado.
CORE existe vacia en local-dev, pero eso no habilita escritura.
La politica exacta de updated vs invalidacion debe cerrarse al implementar.
channel_normalized requiere catalogo aprobado; sin catalogo debe quedar NULL o warning, no inventado.
contribution_amount conserva semantica de margen pendiente.
Produccion no tiene gate de entorno, backup/restore, RLS, observabilidad ni operacion aprobada.
La sync diaria sigue bloqueada porque SOURCE-003 es fuente viva y requiere ventana movil, drift controlado y estrategia operativa separada.

18. Prohibiciones preservadas¶

En este gate queda prohibido:

modificar Python;
tocar PostgreSQL;
ejecutar SQL;
escribir en CORE;
modificar RAW;
cargar datos;
generar CSV;
ejecutar runner;
usar VPS, Docker, OpenClaw, NPM o Portainer;
push o deploy.

19. Conclusion¶

text GATE PROMOTE-CORE DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO APTO PARA IMPLEMENTAR promote-core --execute LOCAL-DEV EN TAREA FUTURA NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA

El gate queda apto documentalmente para una futura tarea separada de implementacion local-dev de:

powershell python scripts/source_003_importer.py promote-core --execute

No habilita escritura actual, produccion, sync diaria, MART, runner, deploy ni automatizacion.