🧭 LAS PIEZAS — el atlas de la arquitectura

Qué es esto y en qué se diferencia de todo lo demás.

docs/architecture/*-approach.md son planes: qué vamos a hacer y por qué.
sustrato-NN.md son fotos: cómo estaba todo un día concreto.
Esto es otra cosa: el estado VIVO de cada pieza, una por documento.

Un approach caduca cuando se ejecuta. Una foto se congela. Una pieza se
actualiza — y por eso lleva versión, fecha de última medición y un historial.

1 · Por qué una pieza por documento

Hasta ahora, para saber «cómo funcionan los grants» había que leer §7·sexies de un approach, §12 de un sustrato y tres runbooks. La información existía y no estaba localizada, que operativamente es casi lo mismo que no tenerla.

⇒ Una pieza = un documento = una respuesta a «¿qué es esto y en qué estado está?»

Y una regla que hace que no se pudra: cada pieza declara su última medición con el comando que la produjo. Una pieza sin fecha de medición es una opinión con formato.

2 · El atlas

Pieza	Qué gobierna	Estado	Doc
⭐ GRANTS	Quién puede tocar qué objeto — la retícula	🏁 v1.0 · aplicando	GRANTS.md
⭐⭐ INDEX-CATALOG	El plano de control — el tercer vértice del tridente	🏁 v2.0 · los 24 módulos leídos	INDEX-CATALOG.md
⭐ JUNCTION	La puerta: compone, autoriza y despacha	🏁 v1.0 · las 5 capas	JUNCTION.md
⭐ ICEBERG-FACE	La cara REST gobernada: quién entra al catálogo	⚠️ v1.0 · viva, gobierna 1 de 4 carriles	ICEBERG-FACE.md
⭐ COMPUTE	Dónde se ejecuta el SQL — cluster, motores, puente	🏁 v1.0 · las 5 capas	COMPUTE.md
⭐⭐ DATA-STORAGE	El plano de bytes — el único sitio donde el dato ocupa espacio	⚠️ v1.2 · vivo · sin colchón de recuperación real	DATA-STORAGE.md
⭐⭐ CATALOG-STORE	Quién guarda la verdad de una tabla y dónde se serializa el commit	⚠️ v1.0 · las 5 capas · ⛔ sin recuperación real	CATALOG-STORE.md
TAGS	Las etiquetas gobernadas — el sustantivo de la política	⛔ no existe	`TAGS.md`
ROW-POLICY	Filtro de fila · máscara de columna · proyección	⛔ no existe	`ROW-POLICY.md`
CONTRACT	El contrato de activo (ODCS) que nace en la ingesta	⛔ no existe	`CONTRACT.md`
⭐ INGESTION	De la fuente al bucket — el principio del flujo	⚠️ v1.0 · trazada · paradigma anterior	INGESTION.md
ONTOLOGY	Tipos, acciones y la proyección a grafo	⚠️ legacy, se rehace	`ONTOLOGY.md`

Leyenda: 🏁 en producción y medido · ⏳ existe y falta documentarlo · ⛔ no existe todavía · ⚠️ existe y hay que rehacerlo.

⭐ Y una lectura transversal de todas ellas: ../architecture/repaso-paradigma-e2e.md — los seis patrones de inmadurez que se repiten entre piezas, el sustrato legacy con nombre, y dónde encaja (y dónde no) cambiar de catálogo.

3 · Cómo se escribe una pieza

⛔ No hay plantilla, y es deliberado. Cada pieza del stack tiene su propia naturaleza: una retícula de permisos, un formato de fichero, un motor de cómputo y un flujo de ingesta no se explican con la misma forma. Forzarlas a un molde común produce secciones vacías rellenas por obligación — que es ruido con aspecto de rigor.

Lo que sí es obligatorio, y es poco:


Una cabecera	versión · estado · fecha de la última medición
⭐ Una imagen limpia de su naturaleza	qué es, y qué no es. Sobria: la forma antes que el detalle
Cada hecho con su comando	lo que no lo lleva va marcado como pendiente u opinión
Un historial	una línea por versión — y la versión sube cuando cambia la naturaleza, no cuando cambia un número

Todo lo demás —diagramas, tablas, secciones— lo decide la pieza, según lo que haya que explicar de ella.

⭐ La única sección que conviene repetir en todas: «qué NO es». La mayoría de los errores caros de esta arquitectura vinieron de confundir una pieza con otra —medir la base de datos y llamarla Index, contar como propia una capacidad que sólo estaba en el folleto—. Y muchas piezas casan entre sí: decir dónde termina cada una es lo que evita que se solapen en silencio.

4 · Cómo se relaciona con el resto

docs/piezas/           ← el ESTADO VIVO de cada pieza        (esto)
docs/architecture/
  index-gobernanza-mapa.md   ← la DEFINICIÓN DE HECHO: dónde estamos vs el estándar
  *-approach.md              ← los PLANES: qué vamos a hacer
  sustrato-NN.md             ← las FOTOS congeladas
docs/runbooks/               ← los PROCEDIMIENTOS: cómo se opera

⚠️ Y la regla de precedencia, para cuando discrepen: manda la pieza sobre cómo funciona algo hoy · manda el mapa sobre dónde estamos frente al estándar · manda el sustrato sobre qué era verdad en su fecha · el approach nunca manda sobre los hechos: describe intención.