SOURCE-003 Python Importer Contract¶

Fecha local: 2026-06-15

Estado: CONTRATO IMPORTER DOCUMENTADO / NO IMPLEMENTADO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-PYTHON-IMPORTER-CONTRACT.md

1. Proposito¶

Definir el contrato documental del futuro Python importer formal para SOURCE-003, alineado con la arquitectura objetivo:

text raw -> prepared CSV -> core -> mart -> Python importer/runner -> OpenClaw executor -> sync futura

El importer futuro debe convertir el flujo ya validado en un pipeline gobernado, observable, idempotente y trazable. No reemplaza todavia la sync diaria, no habilita produccion y no autoriza cargas nuevas.

Este documento no implementa importer, no modifica scripts Python, no ejecuta SQL, no toca PostgreSQL, no genera CSV y no ejecuta runner.

2. Relacion con capas¶

Capa	Responsabilidad para `SOURCE-003`	Estado
`raw`	Preservar copia fiel del origen autorizado, snapshot o query aprobada, con evidencia de hash, extraccion y fuente.	Parcial por snapshots congelados.
`prepared CSV`	Artefacto reproducible fuera de Git, con `83` columnas destino, hashes, batch, `line_key` y validaciones locales.	Existe para piloto; generador documentado.
`core`	Modelo normalizado futuro con claves canonicas, reglas de calidad y trazabilidad estable.	No formalizado para produccion.
`mart`	Capa analitica futura para KPIs, dashboards, reportes, recomendaciones y vistas de negocio.	No materializada.
`Python importer`	Futuro componente que gobernara cargas desde artefactos validados hacia `raw` o `core`, segun contrato explicito.	No implementado.
`Python runner`	Capa de ejecucion controlada de gates, SQL autorizado y verificaciones. `PASS` read-only no habilita escritura.	Piloto documentado con escrituras bloqueadas.
`OpenClaw executor`	Futuro disparador gobernado por allowlist, gate y operador humano.	No habilitado.
`sync futura`	Operacion posterior, idempotente, observable y aprobada separadamente.	Bloqueada.

Lectura operativa:

el generator cubre raw -> prepared CSV;
el importer futuro cubrira promocion gobernada de artefactos ya validados;
el runner seguira siendo el ejecutor controlado de gates y comandos autorizados;
OpenClaw podra disparar solamente comandos permitidos por contrato, sin decidir autonomamente.

3. Comandos futuros sugeridos¶

Los nombres siguientes son contractuales y no implican implementacion actual.

Comando	Proposito	Escritura permitida
`inspect-source`	Inspeccionar fuente autorizada, metadata, autoridad de query, hash esperado y ventana.	No
`generate-prepared`	Coordinar generacion reproducible de prepared CSV desde `raw`, sin DB.	No
`validate-prepared`	Validar estructura, conteos, hash, batch, duplicados, nulos criticos y conciliaciones del CSV.	No
`load-raw`	Cargar evidencia cruda o preparada hacia capa `raw`, solo con gate humano y batch autorizado.	Solo futuro
`promote-core`	Promover datos validados desde `raw` hacia `core`, con reglas de calidad y trazabilidad.	Solo futuro
`build-mart`	Construir o refrescar capa analitica desde `core`, sin leer origen crudo salvo excepcion documentada.	Solo futuro
`status`	Verificar salud de batch, artefactos, tablas y ultimas decisiones, preferentemente read-only.	No
`rollback-batch`	Revertir un batch especifico con filtros completos y aprobacion separada.	Solo futuro

Reglas de CLI futura:

todo comando debe aceptar --tenant-id alpuntodeventa;
todo comando que escriba debe exigir --execute y confirmaciones exactas;
los comandos read-only deben exponer resultado PASS, FAIL o BLOCKED;
status no debe reinterpretarse como permiso de load, promote ni rollback;
el importer debe poder emitir salida humana y salida JSON opcional.

4. Gates obligatorios¶

Ningun comando de escritura futuro puede avanzar sin todos los gates aplicables.

Gate	Requisito minimo
SAFE POINT	Rama, limpieza de worktree, HEAD esperado y ultimo commit revisados antes de ejecutar.
Source authority	Fuente, query version, snapshot o authority file aprobados y documentados.
CSV/hash	Archivo fuera de Git, ruta Windows validada, sha256 exacto, filas, columnas y conciliaciones aprobadas.
Fingerprint DB	Host, port, database, user y fingerprint runtime coinciden contra evidencia aprobada.
Batch	`batch_id`/`sync_batch_id`, ventana, tenant, source metadata y conteos exactos.
Aprobacion humana	Confirmacion explicita antes de cualquier escritura, carga, promocion, mart build o rollback.

Bloqueos duros:

si falta un gate, el resultado debe ser BLOCKED;
si hay drift de hash, conteo, columnas o fingerprint, la escritura debe abortar antes de tocar DB;
un PASS read-only nunca habilita escritura por arrastre;
un gate de carga no habilita rollback; rollback requiere gate propio.

5. Entradas¶

Entradas documentales minimas del importer futuro:

tenant_id = alpuntodeventa;
source_id = SOURCE-003;
source_system, por ejemplo snapshot:SOURCE-003-SNAPSHOT-001;
source_object = SOURCE-003 / Tabla 2 V2;
source_query_version, actualmente SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2 para el piloto;
ruta Windows del raw snapshot o artefacto preparado;
sha256 esperado del raw y del prepared CSV;
batch_id o sync_batch_id autorizado;
ventana de fechas aprobada;
entorno destino aprobado;
fingerprint DB esperado si el comando toca DB;
operador humano o contexto de aprobacion.

El importer no debe inferir tenant, entorno, batch ni fuente desde defaults silenciosos cuando exista riesgo de escritura.

6. Salidas¶

Salidas esperadas:

resumen legible con comando, resultado, tenant, source, batch, ventana y artefactos;
exit codes estables para PASS, FAIL, BLOCKED y error de entorno;
JSON opcional para automatizacion futura;
evidencia documental apta para copiar a docs de ejecucion;
logs seguros sin secretos;
referencia a archivos usados, hashes observados y hashes esperados;
flags de auditoria para distinguir lectura, intento de contacto DB, escritura real, rollback y errores.

Campos JSON sugeridos:

json { "command": "validate-prepared", "result": "PASS", "tenant_id": "alpuntodeventa", "source_id": "SOURCE-003", "batch_id": "1827f887-9499-4579-b4f3-234d54f41f7f", "rows": 1886, "columns": 83, "postgresql_touched": false, "write_executed": false, "rollback_executed": false }

7. Idempotencia¶

Identidad minima:

batch_id o sync_batch_id identifica la corrida gobernada;
source_row_hash identifica el contenido canonico de la fila fuente;
line_key identifica la linea de negocio para deduplicacion;
(tenant_id, line_key) sigue siendo identidad logica aprobada para el piloto;
id es surrogate key tecnica y no debe ser la base funcional de conciliacion, rollback ni deduplicacion.

Reglas:

reintentar un comando read-only debe ser seguro;
reintentar una carga con el mismo batch debe detectar duplicados antes de escribir;
reintentar una promocion a core debe comparar source_row_hash y reglas de estado;
los duplicados en (tenant_id, line_key) bloquean carga;
colisiones entre batch nuevo y datos existentes deben resolverse por gate, no por overwrite automatico;
no se permite hard delete como respuesta automatica a desaparicion de fuente viva.

8. Logs y auditoria¶

Los logs del importer futuro deben:

no imprimir passwords, tokens, connection strings completas ni variables sensibles;
registrar operador, tenant, comando, batch, ventana, fuente y resultado;
registrar rutas de artefactos sin exponer secretos;
registrar hashes esperados y observados;
registrar si hubo contacto DB, probe de fingerprint, SQL ejecutado, escritura ejecutada o rollback ejecutado;
producir evidencia documental por batch;
distinguir BLOCKED funcional de error tecnico;
ser monotonicamente honestos: si se intento tocar DB, un handler posterior no puede volver ese flag a false.

Evidencia minima por batch:

comando ejecutado;
SAFE POINT;
source authority;
artefactos y hashes;
fingerprint DB si aplica;
validaciones previas;
resultado;
validaciones posteriores si hubo escritura;
decision y bloqueos preservados.

9. Errores¶

Categorias contractuales:

Categoria	Ejemplos	Resultado
`validation_error`	Hash distinto, columnas incorrectas, duplicados, nulos criticos, fecha fuera de ventana.	`FAIL`
`blocked_by_gate`	Falta aprobacion humana, SAFE POINT no coincide, modo escritura no autorizado.	`BLOCKED`
`environment_error`	`psql` no disponible, variables requeridas ausentes, ruta Windows inexistente.	`FAIL`
`fingerprint_mismatch`	DB real no coincide con host, port, database, user o fingerprint esperado.	`BLOCKED`
`batch_conflict`	Batch ya cargado, duplicados existentes o conteos incompatibles.	`BLOCKED`
`runtime_error`	Falla inesperada durante comando autorizado.	`FAIL`

Ante cualquier error posterior a una escritura autorizada, el importer no debe ejecutar rollback automatico. Debe detenerse, registrar evidencia y exigir un gate separado de rollback-batch.

10. Rollback¶

Rollback permitido solo por batch y solo en una tarea futura aprobada.

Reglas obligatorias:

usar rollback-batch;
exigir SAFE POINT nuevo;
exigir aprobacion humana explicita y separada;
exigir fingerprint DB;
exigir tenant_id, batch_id, source_system, source_object, source_query_version y ventana;
nunca usar TRUNCATE;
nunca hacer rollback automatico por una falla de carga;
abortar si el conteo afectado no coincide con el conteo esperado;
registrar evidencia antes y despues.

Criterios de seguridad:

el rollback debe afectar un unico batch autorizado;
no debe borrar datos de otros tenants, otros batches ni otras fuentes;
si hay mezcla de batches o estado ambiguo, debe quedar BLOCKED;
si la tabla contiene datos posteriores dependientes, el rollback debe detenerse hasta revisar dependencias core y mart.

11. Relacion con OpenClaw¶

OpenClaw futuro puede actuar solamente como executor gobernado.

Reglas:

no decide autonomamente cargas, promociones, sync ni rollback;
no ejecuta sync sin gate;
no saltea aprobacion humana;
solo puede invocar comandos allowlist;
debe registrar operador, tenant, comando, batch, entorno, resultado y evidencia;
no puede pasar argumentos arbitrarios fuera del contrato;
debe tratar status como observacion, no como permiso de escritura.

Allowlist inicial sugerida para OpenClaw futuro:

inspect-source;
validate-prepared;
status.

Allowlist futura con gate reforzado:

generate-prepared;
load-raw;
promote-core;
build-mart;
rollback-batch.

12. Bloqueos vigentes¶

Este contrato preserva los bloqueos vigentes:

sync diaria bloqueada;
carga masiva bloqueada;
produccion final bloqueada;
clientes no iniciados en runtime;
productos no iniciados en runtime;
OpenClaw executor no habilitado;
scheduler no habilitado;
importer formal no implementado;
nuevas tablas, migraciones y SQL fuera de alcance;
runner en modo escritura bloqueado salvo nuevo gate explicito;
push y deploy fuera de alcance.

13. Relacion con documentos vigentes¶

Documentos base:

BUSINESS-OBSERVER-DATA-LAYERS-ARCHITECTURE.md;
SOURCE-003-PREPARED-CSV-PYTHON-GENERATOR-001.md;
SOURCE-003-PILOT-LOAD-PYTHON-RUNNER-001.md;
SOURCE-003-RUNNER-STATUS-DB-001.md;
SOURCE-003-PILOT-LOAD-PREPARED-CSV-001.md;
SOURCE-003-DEDICATED-DB-PILOT-LOAD-GATE.md.

Lectura vigente:

piloto dedicado SOURCE-003 en verde;
1886 filas del batch 1827f887-9499-4579-b4f3-234d54f41f7f;
CSV preparado validado fuera de Git;
runner status read-only validado con PASS;
ningun PASS read-only habilita escritura.

14. Decision¶

text CONTRATO IMPORTER DOCUMENTADO / NO IMPLEMENTADO

El contrato del futuro Python importer formal para SOURCE-003 queda documentado como capa de gobierno entre artefactos validados, runner, OpenClaw executor futuro y sync futura.

No se implementa importer, no se modifica Python, no se toca PostgreSQL, no se ejecuta SQL, no se ejecuta runner, no se genera CSV, no se cargan datos y no se habilita produccion.