SOURCE-003 Promote Core Safe Mode Technical Review¶

Fecha local: 2026-06-15

Estado: TECHNICAL REVIEW PASS / SAFE MODE VALIDADO / SIN ESCRITURA

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-SAFE-MODE-TECHNICAL-REVIEW.md

1. Objetivo¶

Revisar tecnicamente el safe mode de:

powershell python scripts/source_003_importer.py promote-core

antes de preparar una ruta real RAW -> CORE en local-dev.

Esta revision no escribe en CORE, no modifica RAW, no ejecuta confirmaciones de promote-core --execute, no carga datos, no modifica Python, no genera CSV, no ejecuta runner y no toca VPS, Docker, OpenClaw, NPM, Portainer, push ni deploy.

2. Safe point¶

Control	Resultado
workspace	`C:\APV\openclawai`
rama	`main`
`git status --short --branch` inicial	`## main...origin/main`
`git rev-parse HEAD` inicial	`71a9995b50705d74a26c53e8408beec8454f1ec5`
`git rev-parse origin/main` inicial	`71a9995b50705d74a26c53e8408beec8454f1ec5`
ultimo commit inicial	`71a9995 tools: add source 003 promote core safe mode`
decision	`SAFE POINT PASS`

3. Archivos revisados¶

Archivo	Impacto de la revision
`scripts/source_003_importer.py`	Verifica comportamiento real de `promote-core`, guards de DB, fingerprint, RAW/CORE y bloqueo de escritura.
`docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-IMPORTER-PROMOTE-CORE-SAFE-MODE-001.md`	Contrasta evidencia de implementacion safe mode y resultados esperados.
`docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-IMPORTER-PROMOTE-CORE-PLAN.md`	Contrasta plan documental RAW -> CORE y precondiciones.
`docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CORE-DDL-LOCAL-DEV-FORWARD-001.md`	Confirma CORE target creada vacia en local-dev con `66` columnas.
`docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LOAD-RAW-LOCAL-DEV-POST-EXECUTION-REVIEW.md`	Confirma RAW local-dev con batch autorizado de `1886` filas.

4. Hallazgos¶

Check	Observado	Esperado	Resultado
`promote-core`	`DRY_RUN`	`DRY_RUN`	`PASS`
`promote-core --execute`	`BLOCKED`	`BLOCKED`	`PASS`
RAW source	`business_observer.raw_source_003_sales_items`	tabla RAW correcta	`PASS`
CORE target	`business_observer.core_source_003_sales_items`	tabla CORE correcta	`PASS`
RAW batch rows	`1886`	`1886`	`PASS`
CORE row_count	`0`	`0`	`PASS`
candidate_rows	`1886`	`1886`	`PASS`
target_columns	`66`	`66`	`PASS`
duplicates_core	`0`	`0`	`PASS`
fingerprint DB	aprobado y obligatorio	obligatorio	`PASS`
postgres-sandbox	no observado	prohibido	`PASS`
`db_write`	`false`	`false`	`PASS`
`data_written`	`false`	`false`	`PASS`
`sync_enabled`	`false`	`false`	`PASS`
INSERT/COPY/UPDATE/DELETE activo en `promote-core`	no activo	no activo	`PASS`

Fingerprint DB observado:

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

5. Evidencia tecnica¶

promote-core ejecuta validate-prepared y luego consultas SELECT read-only para fingerprint, catalogo, conteos RAW/CORE, columnas CORE y duplicados CORE. No construye ni ejecuta sentencias de escritura en esta ruta.

Puntos relevantes del codigo:

inspect_promote_core_db_read_only() usa SELECT json_build_object(...) para fingerprint y checks de tablas.
promote_core_safe_mode() bloquea inmediatamente --execute.
promote_core_safe_mode() agrega errores claros si falla DB read-only, fingerprint, RAW table, RAW batch rows, CORE table, CORE row_count, candidate_rows, target_columns o duplicates CORE.
postgres_sandbox_markers() bloquea el uso de postgres-sandbox si aparece en variables relevantes del entorno local.

Resultado resumido de python scripts/source_003_importer.py promote-core:

json { "command": "promote-core", "result": "DRY_RUN", "db_touched": true, "db_write": false, "sql_executed": true, "sql_write": false, "data_written": false, "sync_enabled": false, "raw_batch_rows": 1886, "core_row_count": 0, "candidate_rows": 1886, "target_columns": 66, "duplicates_core": 0, "raw_source_table": "business_observer.raw_source_003_sales_items", "core_target_table": "business_observer.core_source_003_sales_items" }

Resultado resumido de python scripts/source_003_importer.py promote-core --execute:

json { "command": "promote-core", "result": "BLOCKED", "db_touched": false, "db_write": false, "sql_executed": false, "sql_write": false, "data_written": false, "sync_enabled": false, "problems": [ "promote-core --execute bloqueado: safe mode sin escrituras" ] }

6. Riesgos y limites¶

promote-core todavia no implementa escritura real RAW -> CORE; solo valida precondiciones.
La ruta write futura requiere diseno separado de transformaciones, idempotencia por batch, estrategia de update/unchanged/blocked, rollback o rebuild CORE y validaciones post-escritura.
La salida DRY_RUN toca DB solo para lecturas SELECT; no es apta para produccion ni sync diaria.
El codigo contiene una ruta write para load-raw, ya existente y separada. Esta revision valida que promote-core no active esa ruta ni invoque runner.

7. Errores claros ante precondiciones faltantes¶

El comando reporta problemas explicitos para:

DB read-only no disponible;
fingerprint DB no aprobado;
uso de postgres-sandbox;
validate-prepared fuera de PASS;
database observada distinta de openclaw_business_observer_dev;
tabla RAW ausente;
RAW batch rows distinto de 1886;
tabla CORE ausente;
CORE row_count distinto de 0;
candidate_rows distinto de 1886;
target_columns distinto de 66;
duplicates CORE distinto de 0;
promote-core --execute solicitado.

8. Validaciones ejecutadas¶

Validacion	Resultado
`python -m py_compile scripts/source_003_importer.py`	`PASS`
`python scripts/source_003_importer.py --help`	`PASS`
`python scripts/source_003_importer.py promote-core`	`PASS`, `DRY_RUN`
`python scripts/source_003_importer.py promote-core --execute`	`PASS`, `BLOCKED`, exit code `3` esperado
`git diff --check`	`PASS`
`.venv-portal\Scripts\mkdocs.exe build --strict`	`PASS`

9. Conclusion¶

text APTO PARA DISEÑAR RUTA WRITE PROMOTE-CORE LOCAL-DEV NO APTO PARA PRODUCCIÓN NO APTO PARA SYNC DIARIA

El safe mode de promote-core queda tecnicamente validado para avanzar al diseno de una futura ruta write local-dev separada, con nuevos gates de autorizacion. No habilita escritura en CORE, modificacion de RAW, produccion ni sync diaria.