SOURCE-003 Raw Layer Contract¶

Fecha local: 2026-06-15

Estado: CONTRATO RAW 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-RAW-LAYER-CONTRACT.md

1. Proposito¶

Definir documentalmente el contrato formal de la capa raw para SOURCE-003 / SGC Ventas / Tabla 2 V2.

La capa raw es la evidencia primaria gobernada del origen. Debe preservar lo observado en el origen autorizado, con metadata tecnica suficiente para trazabilidad, idempotencia, validacion, deduplicacion y rollback futuro por batch.

Este contrato se ubica dentro de la arquitectura objetivo:

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

Este documento no implementa tablas, no crea DDL, no ejecuta SQL, no toca PostgreSQL, no ejecuta runner, no genera CSV y no carga datos.

2. Que conserva del origen¶

La capa raw debe conservar:

filas observadas desde el snapshot, query o fuente autorizada;
columnas originales relevantes del resultset Tabla 2 V2;
valores sin reinterpretacion semantica de negocio;
metadata de origen: sistema, objeto, version de query y fecha de extraccion;
identidad tecnica de fila por source_row_hash;
evidencia de batch por sync_batch_id;
estado de registro por record_status;
timestamps de extraccion y carga;
trazabilidad suficiente para reproducir prepared CSV y reconciliar contra core futuro.

La capa raw no corrige negocio. No decide vendedor, canal, margen, ownership, territorio, KPI ni recomendacion comercial final.

3. Raw Snapshot, Prepared CSV y Raw Table Futura¶

Concepto	Definicion	Estado actual
`raw snapshot`	Archivo congelado del origen o resultset autorizado. Es evidencia local y no versionada si contiene datos reales.	Existe para `SOURCE-003` como snapshot congelado.
`prepared CSV`	Artefacto reproducible desde `raw`, con columnas destino, metadata, hashes y validaciones previas a carga controlada.	Existe para piloto; vive fuera de Git.
`raw table futura`	Tabla futura para persistir evidencia cruda gobernada antes de promocion a `core`.	No implementada.

Regla de interpretacion:

raw snapshot es evidencia de entrada;
prepared CSV es transformacion reproducible y validada;
raw table futura sera persistencia gobernada de evidencia, si se aprueba;
ninguna de las tres capas habilita por si misma sync diaria, carga masiva, produccion final ni OpenClaw executor.

4. Columnas minimas esperadas¶

La futura capa raw para SOURCE-003 debe contemplar como minimo:

Grupo	Columnas minimas
Identidad tenant	`tenant_id`
Origen	`source_system`, `source_object`, `source_query_version`
Batch	`sync_batch_id`
Trazabilidad temporal	`extracted_at`, `loaded_at`
Hash	`source_row_hash`
Estado	`record_status`
Identidad de linea	`line_key` o equivalente aprobado para `SOURCE-003`
Evidencia de negocio	columnas reales del resultset `Tabla 2 V2` preservadas segun diccionario vigente

Columnas de negocio vigentes para referencia documental:

Tabla 2 V2 tiene 68 columnas reales inventariadas;
el prepared CSV piloto tiene 83 columnas por metadata y columnas tecnicas;
el batch piloto validado tiene 1886 filas para la fecha 2026-06-09.

Este contrato no cierra todavia el DDL de una raw table. Solo fija el contrato minimo que esa tabla debera respetar si se implementa.

5. Metadata obligatoria¶

La capa raw debe exigir la siguiente metadata obligatoria:

Campo	Obligatorio	Proposito
`tenant_id`	Si	Aislamiento multi-tenant. Para este contrato: `alpuntodeventa`.
`source_system`	Si	Sistema o snapshot autorizado de origen.
`source_object`	Si	Objeto de negocio o resultset observado. Para este caso: `SOURCE-003 / Tabla 2 V2`.
`source_query_version`	Si	Version documental de la query o autoridad usada.
`source_row_hash`	Si	Hash canonico de la fila fuente para cambio, idempotencia y conciliacion.
`sync_batch_id`	Si	Identificador de corrida/batch gobernado.
`extracted_at`	Si	Momento en que el origen fue extraido o congelado.
`loaded_at`	Si	Momento de carga futura a raw table, si se implementa.
`record_status`	Si	Estado funcional de la fila dentro del batch.

Valores documentados para el piloto vigente:

tenant_id = alpuntodeventa;
source_query_version = SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2;
sync_batch_id = 1827f887-9499-4579-b4f3-234d54f41f7f;
record_status = active;
fecha de negocio validada: 2026-06-09;
filas validadas: 1886.

6. Estrategia de batch¶

Cada extraccion o carga futura debe tener un sync_batch_id unico y documentado.

Reglas:

un batch representa una corrida gobernada, no una tabla completa;
todo batch debe declarar tenant, fuente, objeto, version de query, ventana, hash esperado, conteo esperado y operador o contexto de aprobacion;
los batches deben ser comparables entre si por fecha, ventana, source_row_hash y conteos;
un batch no debe mezclar tenants, fuentes, objetos o versiones de query;
una carga parcial debe quedar bloqueada o documentada como falla, nunca como cierre verde silencioso.

Para SOURCE-003, por ser fuente viva, el batch futuro no debe asumir que una fecha ya cargada queda inmutable durante la ventana operativa.

7. Idempotencia¶

La idempotencia futura debe apoyarse como minimo en:

tenant_id;
source_system;
source_object;
source_query_version;
sync_batch_id;
source_row_hash;
line_key o identidad de linea aprobada.

Reglas:

reintentar el mismo batch no debe duplicar filas;
un mismo sync_batch_id con distinto contenido debe quedar BLOCKED;
un mismo contenido con distinto batch debe poder compararse antes de promover a core;
id tecnico o surrogate key no debe usarse como unica identidad funcional;
cambios de contenido deben detectarse por source_row_hash, no por posicion fisica del CSV ni por timestamp de carga.

8. Deduplicacion¶

La deduplicacion debe ocurrir antes de cualquier carga futura a raw table y antes de cualquier promocion a core.

Reglas minimas:

detectar duplicados por tenant_id + line_key cuando line_key aplique;
detectar duplicados por combinacion de metadata fuente y hash cuando no haya identidad de linea suficiente;
bloquear duplicados dentro del mismo batch;
bloquear conflictos entre batch nuevo y batch ya cargado si no existe regla de reemplazo aprobada;
registrar evidencia de duplicados esperados, si alguna excepcion futura se autoriza.

Para el piloto actual, la evidencia validada mantiene 0 duplicados en tenant_id + line_key.

9. Validaciones minimas¶

Antes de aceptar un batch raw futuro deben pasar como minimo:

ruta Windows existente y fuera de Git si contiene datos reales;
hash sha256 esperado del snapshot o artefacto;
cantidad de filas esperada;
columnas esperadas segun diccionario vigente;
tenant_id unico y correcto;
source_system, source_object y source_query_version exactos;
sync_batch_id unico y esperado;
extracted_at informado;
record_status informado y dentro de valores permitidos;
source_row_hash no vacio;
line_key no vacio cuando aplique;
0 duplicados en identidad de linea esperada;
ventana de fechas dentro del alcance aprobado;
conciliaciones basicas de importes, CMV y conteos cuando existan referencias.

Un PASS de validacion raw o prepared no habilita escritura, carga masiva, sync diaria ni produccion final.

10. Errores esperados¶

Error	Ejemplo	Resultado esperado
Hash distinto	El snapshot observado no coincide con sha256 esperado.	`FAIL`
Columnas incompatibles	Faltan columnas reales o cambia el orden esperado sin decision.	`FAIL`
Batch inconsistente	`sync_batch_id` no coincide con el batch autorizado.	`BLOCKED`
Metadata incompleta	Falta `source_query_version`, `extracted_at` o `source_row_hash`.	`FAIL`
Duplicados	Repeticion de `tenant_id + line_key` en el batch.	`FAIL`
Ventana invalida	Fechas fuera del alcance aprobado.	`BLOCKED`
Fuente viva con drift	Conteos o importes cambiaron contra evidencia congelada.	`BLOCKED`
Ruta insegura	Archivo inexistente, versionado en Git o path Windows no validado.	`FAIL`
Estado no permitido	`record_status` vacio o fuera de catalogo aprobado.	`FAIL`

Ante error, no debe ejecutarse rollback automatico. El resultado debe quedar documentado y cualquier rollback futuro debe abrir gate propio.

11. Rollback por batch¶

El rollback futuro de la capa raw solo puede ser por batch.

Reglas obligatorias:

exigir tenant_id;
exigir sync_batch_id;
exigir source_system;
exigir source_object;
exigir source_query_version;
exigir conteo esperado de filas a afectar;
exigir aprobacion humana separada;
ejecutar solo con fingerprint DB aprobado si toca PostgreSQL;
prohibir TRUNCATE;
prohibir borrado sin filtro completo de batch;
bloquear si existen dependencias ya promovidas a core o mart sin plan de reversa documentado.

Rollback no significa restaurar produccion. Significa revertir una corrida especifica y trazable bajo un gate propio.

12. Relacion Raw -> Core¶

La relacion futura entre raw y core debe seguir estas reglas:

raw preserva evidencia;
core normaliza entidades de negocio;
core no debe leer directamente un snapshot ambiguo si existe una raw table aprobada;
toda promocion raw -> core debe preservar trazabilidad hacia sync_batch_id, source_query_version y source_row_hash;
reglas de negocio como ownership, territorio, canal, KPI o estado analitico deben vivir en core o capas derivadas, no en raw;
si una fila desaparece de una fuente viva, debe evaluarse missing_from_source o estado equivalente, no hard delete automatico.

raw no es el modelo final del negocio. Es la evidencia que permite construir el modelo final con auditoria.

13. Que NO habilita¶

Este contrato no habilita:

sync diaria;
carga masiva;
produccion final;
OpenClaw executor;
scheduler;
runner en modo escritura;
generacion de CSV;
carga a PostgreSQL;
creacion de tablas;
DDL;
DML;
ejecucion SQL;
rollback real;
deploy;
push.

14. Bloqueos preservados¶

Quedan preservados:

PostgreSQL no tocado;
SQL no ejecutado;
DB no modificada;
runner no ejecutado;
CSV no generado;
datos no cargados;
VPS, Docker, OpenClaw y NPM no tocados;
clientes y productos siguen no iniciados en runtime;
cualquier sync futura requiere contratos core, mart, importer, executor, gates, observabilidad, idempotencia, rollback y secretos.

15. Relacion con documentos vigentes¶

Documentos base:

BUSINESS-OBSERVER-DATA-LAYERS-ARCHITECTURE.md;
SOURCE-003-PYTHON-IMPORTER-CONTRACT.md;
SOURCE-003-PYTHON-IMPORTER-SKELETON-001.md;
SOURCE-003-IMPORTER-GENERATE-PREPARED-001.md;
SOURCE-003-IMPORTER-VALIDATE-PREPARED-001.md;
SOURCE-003-PILOT-LOAD-EXECUTION-002.md;
SOURCE-003-TABLA2-COLUMN-DICTIONARY.md;
SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md.

Lectura vigente:

piloto dedicado SOURCE-003 en verde;
1886 filas cargadas en el piloto historico;
batch 1827f887-9499-4579-b4f3-234d54f41f7f;
prepared CSV validado fuera de Git;
importer seguro con inspect-source, generate-prepared y validate-prepared;
sync diaria, carga masiva, produccion final y OpenClaw executor bloqueados.

16. Decision¶

text CONTRATO RAW DOCUMENTADO / NO IMPLEMENTADO

El contrato formal de la capa raw para SOURCE-003 queda documentado como base de evidencia para el flujo futuro raw -> prepared CSV -> core -> mart.

No se implementa tabla raw, no se crea DDL, no se toca PostgreSQL, no se ejecuta SQL, no se ejecuta runner, no se genera CSV, no se cargan datos y no se habilita sync diaria, carga masiva, produccion final ni OpenClaw executor.