SOURCE-003 Load Raw Write Path Technical Review

Fecha local: 2026-06-15

Estado: REVISION TECNICA WRITE PATH PASS / SIN CARGA

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

1. Objetivo

Revisar tecnicamente la ruta write preparada para:

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

La revision no ejecuto confirmaciones completas, no ejecuto INSERT, COPY, UPDATE, DELETE, no escribio DB, no cargo datos, no genero CSV, no invoco runner, no ejecuto rollback real y no toco VPS, Docker, OpenClaw, NPM ni Portainer.

La query de autoridad de ventas:

text docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql

no fue modificada.

2. Safe point

Control	Resultado
workspace	C:\APV\openclawai
rama	main
git rev-parse HEAD inicial	c29ee43254ff7f38b84ac2b7edc0b7279c7eb440
git rev-parse origin/main inicial	c29ee43254ff7f38b84ac2b7edc0b7279c7eb440
ultimo commit inicial	c29ee43 tools: prepare source 003 load raw write path
decision	SAFE POINT PASS

3. Archivos revisados

Archivo	Resultado
scripts/source_003_importer.py	load-raw conserva DRY_RUN; load-raw --execute conserva BLOCKED; no hay ruta activa de escritura real.
SOURCE-003-LOAD-RAW-WRITE-PATH-IMPLEMENTATION-001.md	Documenta ruta futura preparada, confirmaciones, transaccion futura, rollback documental y bloqueos.
SOURCE-003-LOAD-RAW-EXECUTE-GATE-TECHNICAL-REVIEW.md	Confirma gate previo --execute bloqueado y safe mode read-only.
SOURCE-003-LOAD-RAW-LOCAL-DEV-EXECUTION-GATE.md	Define precondiciones futuras para una escritura local-dev controlada.
SOURCE-003-RAW-DDL-LOCAL-DEV-FORWARD-001.md	Confirma tabla RAW creada vacia en local-dev, 84 columnas, owner/grants y row_count = 0.

4. Hallazgos tecnicos

Check	Resultado	Evidencia
load-raw default	PASS	Devuelve result = DRY_RUN, dry_run_only = true, read_only = true.
load-raw --execute sin confirmaciones	PASS	Devuelve result = BLOCKED, exit code 3, db_touched=false, sql_executed=false.
ruta write accidental	PASS	El gate actual no ejecuta INSERT, COPY, UPDATE, DELETE, TRUNCATE, COMMIT, runner ni rollback.
confirmaciones completas requeridas	PASS	Exige flags exactos para local-dev, tenant, source, DB, tabla, batch, RAW empty, rows, columnas, hashes y fingerprint.
DB permitida	PASS	openclaw_business_observer_dev.
tabla destino	PASS	business_observer.raw_source_003_sales_items.
batch	PASS	1827f887-9499-4579-b4f3-234d54f41f7f.
RAW row_count inicial	PASS	Observado 0, esperado 0.
expected rows	PASS	1886.
target columns	PASS	84.
prepared/generated CSV	PASS	Ambos existen, estan fuera de Git, tienen 1886 filas, 83 columnas, hashes esperados y comparacion REPRODUCIBLE ESTRUCTURAL ACEPTADO.
loaded_at gobernado	PASS	Politica: DB-side default o statement_timestamp() transaccional; el CSV no es autoridad. DDL define loaded_at timestamptz NOT NULL DEFAULT now().
batch duplicado bloqueado	PASS	La ruta futura documentada debe bloquear si el batch autorizado ya existe en RAW antes de escribir.
fingerprint obligatorio	PASS	load-raw valida fingerprint aprobado; --execute exige --confirm-db-fingerprint.
postgres-sandbox prohibido	PASS	El gate detecta marcadores postgres-sandbox y bloquea; documentos lo excluyen.
transaccion futura	PASS	Documentada con BEGIN, staging/control intermedio, pre/post-checks, COMMIT solo si todo pasa.
rollback documentado	PASS	ROLLBACK transaccional ante falla pre-commit y rollback-batch futuro separado; no se ejecuto rollback real.
produccion / sync diaria	PASS	No habilitado; sync_enabled=false; produccion y scheduler fuera de alcance.

5. Evidencia operativa observada

load-raw:

json { "result": "DRY_RUN", "db_touched": true, "db_write": false, "sql_executed": true, "sql_write": false, "data_written": false, "sync_enabled": false, "candidate_rows": 1886, "target_database": "openclaw_business_observer_dev", "target_table": "business_observer.raw_source_003_sales_items" }

RAW read-only:

Control	Observado	Esperado	Resultado
fingerprint	::1/128:5432|openclaw_business_observer_dev|postgres|PostgreSQL 15.15, compiled by Visual C++ build 1944, 64-bit	aprobado	PASS
database	openclaw_business_observer_dev	openclaw_business_observer_dev	PASS
tabla existe	true	true	PASS
row_count	0	0	PASS
columnas	84	84	PASS

load-raw --execute sin confirmaciones:

json { "result": "BLOCKED", "db_touched": false, "db_write": false, "sql_executed": false, "sql_write": false, "data_written": false, "sync_enabled": false, "confirmation_gate": { "status": "BLOCKED", "postgres_sandbox_blocked": false } }

Confirmaciones completas no ejecutadas. Se verifico solo el bloqueo por confirmaciones faltantes.

6. Riesgos

• load-raw en DRY_RUN toca DB con consultas read-only para validar fingerprint, tabla, row_count y columnas. Esto es esperado y no representa escritura.
• La ruta write esta preparada a nivel de contrato/payload, pero sigue intencionalmente deshabilitada. La tarea de ejecucion local-dev debe ser separada, con nuevo safe point y autorizacion explicita.
• La primera ejecucion real debe volver a validar que RAW sigue con row_count = 0; si el batch ya existe o aparece drift, debe bloquear.
• No existe alcance productivo ni operativo para sync diaria, scheduler, runner productivo, OpenClaw executor o rollback automatico.

7. Validaciones ejecutadas

Validacion	Resultado
python -m py_compile scripts/source_003_importer.py	PASS, exit code 0
python scripts/source_003_importer.py --help	PASS, exit code 0
python scripts/source_003_importer.py load-raw	PASS, resultado DRY_RUN, exit code 0
python scripts/source_003_importer.py load-raw --execute	PASS, resultado esperado BLOCKED, exit code 3
python scripts/source_003_importer.py dry-run	PASS, exit code 0
git diff --check	PASS, exit code 0
.venv-portal\Scripts\mkdocs.exe build --strict	PASS, exit code 0

8. Decision

text APTO PARA EJECUTAR LOAD-RAW LOCAL-DEV EN TAREA SEPARADA NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA

La ruta write preparada para load-raw --execute queda tecnicamente revisada. El estado actual es apto para una tarea futura separada de ejecucion local-dev, siempre que se ejecuten nuevamente todos los gates, confirmaciones, prechecks y evidencias requeridas antes de cualquier escritura.