From 4af5f7226d303b7b0ff5324bc73d602e75e4254c Mon Sep 17 00:00:00 2001
From: tzzrgit <git@tzr.systems>
Date: Mon, 22 Dec 2025 11:54:34 +0100
Subject: [PATCH] Add bloque structure and Merkle proof to README

- Documents block structure with id field
- Shows contenedor.bloque section added on consolidation
- Explains Merkle proof for verification
- Adds visual diagram of Merkle tree
- Links to contratos-comunes schema
---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/README.md b/README.md
index fc9b0ea..675ccf0 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,7 @@ ALFRED/JARED (OK) ─────┘       │
 ```json
 {
   "numero": 127,
+  "id": "sha256-bloque",
   "hash_anterior": "def456...",
   "merkle_root": "789abc...",
   "validado_at": "2025-12-22T00:00:00Z",
@@ -52,6 +53,63 @@ ALFRED/JARED (OK) ─────┘       │
 }
 ```
 
+## Estructura del Contenedor en FELDMAN
+
+Cuando un registro se consolida, FELDMAN anade la seccion `bloque` al contenedor (ver [esquema completo](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/06-contenedor-schema.md)):
+
+```json
+{
+  "bloque": {
+    "id": "sha256-bloque",
+    "numero": 127,
+    "registro_hash": "sha256-este-registro",
+    "merkle_proof": ["sha256-1", "sha256-2", "sha256-3"]
+  },
+
+  "estado": {
+    "actual": "en_feldman_bloque",
+    "historial": [
+      {"paso": "clara", "entrada": "...", "salida": "..."},
+      {"paso": "mason", "entrada": "...", "salida": "..."},
+      {"paso": "feldman_cola", "entrada": "...", "salida": "..."},
+      {"paso": "feldman_bloque", "entrada": "...", "procesado_por": "feldman-service"}
+    ]
+  }
+}
+```
+
+### Campos del bloque
+
+| Campo | Tipo | Descripcion |
+|-------|------|-------------|
+| `id` | SHA-256 | Hash del bloque completo |
+| `numero` | Int | Numero secuencial del bloque |
+| `registro_hash` | SHA-256 | Hash de este registro especifico |
+| `merkle_proof` | Array | Prueba de inclusion en el arbol Merkle |
+
+### Verificacion
+
+Con `merkle_proof` se puede verificar que un registro pertenece a un bloque sin tener acceso a todos los registros del bloque.
+
+```
+              merkle_root
+                  │
+         ┌───────┴───────┐
+         │               │
+      hash_ab         hash_cd
+         │               │
+    ┌────┴────┐     ┌────┴────┐
+    │         │     │         │
+  reg_a     reg_b reg_c     reg_d
+```
+
+### Inmutabilidad
+
+- Una vez consolidado, el registro es **inmutable**
+- `estado.actual` cambia a `en_feldman_bloque`
+- La seccion `bloque` se anade y nunca cambia
+- El hash del registro se incluye en el arbol Merkle
+
 ## Arquitectura
 
 Ver documentación completa en [contratos-comunes/architecture](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/04-feldman.md)