Saltar a contenido

SOURCE-003 Promote Core Write Path Technical Review

Fecha local: 2026-06-15

Estado: TECHNICAL REVIEW PASS / WRITE PATH BLOCKED / SIN ESCRITURA CORE

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-WRITE-PATH-TECHNICAL-REVIEW.md

1. Objetivo

Revisar tecnicamente la ruta write preparada para:

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

La revision no escribe datos. No modifica Python, no modifica RAW, no carga CORE, no ejecuta confirmaciones completas, no genera CSV, no ejecuta runner, no ejecuta rollback real 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 inicial limpio
git rev-parse HEAD inicial 197c0877ed59f68d6fb6597ff27e689b1d35d2bd
git rev-parse origin/main inicial 197c0877ed59f68d6fb6597ff27e689b1d35d2bd
ultimo commit inicial 197c087 tools: prepare source 003 promote core write path
decision SAFE POINT PASS

3. Archivos revisados

Archivo Impacto de la revision
scripts/source_003_importer.py Verifica constantes, parser, gate promote-core, rama --execute, plan futuro de escritura, consultas read-only y ausencia de escritura CORE activa.
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-PROMOTE-CORE-WRITE-PATH-IMPLEMENTATION-001.md Contrasta la implementacion preparada y bloqueada del write path futuro.
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-PROMOTE-CORE-EXECUTE-GATE-TECHNICAL-REVIEW.md Contrasta el review tecnico previo del gate --execute.
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-PROMOTE-CORE-LOCAL-DEV-EXECUTION-GATE.md Contrasta requisitos futuros de local-dev, fingerprint, transaccion, rollback/rebuild y post-checks.
docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CORE-DDL-LOCAL-DEV-FORWARD-001.md Contrasta que CORE existe vacia con 66 columnas y row_count = 0.

4. Hallazgos

Check Observado Esperado Resultado
promote-core DRY_RUN DRY_RUN PASS
promote-core --execute BLOCKED BLOCKED PASS
promote-core --execute --confirm-local-dev BLOCKED por confirmaciones incompletas BLOCKED PASS
write_path_enabled false false PASS
INSERT/COPY/UPDATE/DELETE activo en promote-core no activo no activo PASS
RAW source business_observer.raw_source_003_sales_items RAW correcta PASS
CORE target business_observer.core_source_003_sales_items 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 obligatorio y aprobado en dry-run obligatorio PASS
postgres-sandbox no observado; bloqueado si aparece marcador prohibido PASS
transaccion futura documentada en future_transaction_plan documentada PASS
rollback/rebuild documentado y no habilitado documentado PASS
post-check futuro CORE batch rows 1886 1886 PASS
data_written false false PASS
sync_enabled false false PASS

Fingerprint DB observado en promote-core dry-run:

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 sin --execute ejecuta validate-prepared y consultas SELECT read-only para fingerprint, existencia de tablas, conteos, columnas y duplicados. La salida observada queda en DRY_RUN:

json { "result": "DRY_RUN", "raw_batch_rows": 1886, "core_row_count": 0, "candidate_rows": 1886, "target_columns": 66, "duplicates_core": 0, "db_write": false, "sql_write": false, "data_written": false, "sync_enabled": false }

promote-core --execute entra primero en validate_promote_core_execute_confirmations(args) y retorna BLOCKED. Con confirmaciones faltantes, lista cada flag requerido. Si en una tarea futura se entregaran todas las confirmaciones, el codigo actual igualmente agrega el bloqueo:

text promote-core --execute bloqueado: escritura CORE no implementada

La rama --execute no llama a inspect_promote_core_db_read_only(), no llama a run_psql_scalar(), no llama a run_psql_script() y mantiene:

json { "db_touched": false, "db_write": false, "sql_executed": false, "sql_write": false, "data_written": false, "sync_enabled": false }

La busqueda de operaciones SQL muestra que el INSERT activo pertenece a load-raw, no a promote-core. En promote-core, las operaciones INSERT, COPY, UPDATE y DELETE aparecen solo como acciones bloqueadas o plan futuro documentado.

6. Write path futuro observado

details.future_write_path declara:

  • write_path_prepared = true;
  • write_path_enabled = false;
  • execution_status = BLOCKED_UNTIL_SEPARATE_WRITE_APPROVAL;
  • DB permitida openclaw_business_observer_dev;
  • RAW source business_observer.raw_source_003_sales_items;
  • CORE target business_observer.core_source_003_sales_items;
  • batch autorizado 1827f887-9499-4579-b4f3-234d54f41f7f;
  • expected_raw_batch_rows = 1886;
  • expected_core_initial_row_count = 0;
  • expected_promote_rows = 1886;
  • expected_core_target_columns = 66;
  • expected_core_post_check_batch_rows = 1886;
  • fingerprint DB obligatorio;
  • bloqueo de postgres-sandbox;
  • bloqueo por batch duplicado CORE;
  • preservacion obligatoria de source_row_hash y line_key;
  • timestamps gobernados por DB o timestamp transaccional futuro;
  • rollback/rebuild documentado pero deshabilitado.

7. Confirmaciones requeridas

El gate actual exige estas confirmaciones para una solicitud --execute:

powershell --confirm-local-dev --confirm-promote-core-local-dev --confirm-target-database openclaw_business_observer_dev --confirm-source-table business_observer.raw_source_003_sales_items --confirm-target-table business_observer.core_source_003_sales_items --confirm-batch 1827f887-9499-4579-b4f3-234d54f41f7f --confirm-raw-row-count 1886 --confirm-core-empty --confirm-core-initial-row-count 0 --confirm-candidate-rows 1886 --confirm-target-columns 66 --confirm-duplicates-core 0 --confirm-db-fingerprint "::1/128:5432|openclaw_business_observer_dev|postgres|PostgreSQL 15.15, compiled by Visual C++ build 1944, 64-bit"

No se ejecutaron confirmaciones completas en esta revision.

8. Riesgos y limites

  • La ruta write real de promote-core --execute no esta implementada; esta preparada y bloqueada.
  • El plan futuro menciona INSERT y UPDATE solo como operaciones futuras, no como ruta activa.
  • La politica final de update, invalidacion e idempotencia debe cerrarse en la tarea separada de ejecucion local-dev.
  • Produccion no cuenta con gate operativo, backup/restore, observabilidad, controles de drift, aprobacion de sync diaria ni plan de rollback productivo.
  • La revision valida promote-core; no habilita ni revisa ejecucion de load-raw.

9. 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; codigo 3 esperado normalizado para la revision
python scripts/source_003_importer.py promote-core --execute --confirm-local-dev PASS, BLOCKED; codigo 3 esperado normalizado para la revision
git diff --check PASS
.venv-portal\Scripts\mkdocs.exe build --strict PASS

10. Decision

text APTO PARA EJECUTAR PROMOTE-CORE LOCAL-DEV EN TAREA SEPARADA NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA

La ruta preparada es apta como base tecnica para una tarea separada de ejecucion local-dev controlada, porque el estado actual preserva DRY_RUN y BLOCKED, no escribe CORE, no modifica RAW y mantiene data_written=false y sync_enabled=false.