📒 PIEZA · CATALOG-STORE — quién guarda la verdad de una tabla

Qué es

Es la pieza que hace que el lakehouse sea un lakehouse: sin ella, R2 es una carpeta con Parquet dentro.

Qué NO es

• ⛔ No es la cara. ICEBERG-FACE es nuestro endpoint REST que autoriza y reenvía; esto es a quién reenvía. La cara pregunta «¿puede este motor?»; el catálogo responde «ésta es la tabla».
• ⛔ No es Index. Index gobierna; el catálogo registra. El invariante que los separa es literal y físico: son dos Postgres distintos, en dos proveedores distintos — Index vive en Supabase, esto en Railway. Index nunca serializa escrituras.
• ⛔ No es el storage. DATA-STORAGE guarda los bytes. Este guarda qué bytes cuentan, y es donde ocurre lo que el storage no puede hacer: la atomicidad.
• No es nuestro código. Es Lakekeeper, Apache-2.0, desplegado tal cual. Lo nuestro son las decisiones de configuración — y ésas sí son de esta pieza.

Capa 1 · El sustrato

El proceso

curl -s https://heroic-victory-production-41dd.up.railway.app/health        # 200, sin token
curl -sH "Authorization: Bearer $TOK" …/management/v1/info

⚠️ Ese authz-backend: openfga merece un aviso ahora y una capa entera después (capa 4): es el interruptor de Lakekeeper, no el de Carbon. Que estén los dos y se llamen casi igual es exactamente cómo se lee mal el estado de un sistema.

Su base de datos

npx @railway/cli variables -s lakekeeper --kv | grep PG_DATABASE_URL   # host, sin credenciales

⭐⭐ Qué guarda de verdad — y no es «un puntero»

La frase que llevamos meses repitiendo es «el catálogo guarda un puntero por tabla, y el commit es un compare-and-swap sobre él». Medido, es más que eso.

tabular.metadata_location  ← el puntero, sí existe: s3://…/metadata/00003-….json

…pero al lado, la metadata de Iceberg está descompuesta en tablas relacionales:

Y la prueba de que no es una caché: la columna table.metadata es un jsonb vacío en las 194 filas. Si esto fuera un índice sobre el fichero, el blob estaría ahí. No está: la forma normalizada es la única forma que hay dentro.

El tamaño, y lo que dice

El registro pesa casi lo mismo que el dato registrado. No invalida la tesis —el catálogo crece con el número de tablas y de snapshots, no con las filas, y por eso un commit de 1 TB y uno de 1 KB le cuestan lo mismo— pero la afina:

Y eso enlaza con la retención: expirar snapshots no libera un byte de R2, pero sí encoge esto — que es, de las dos cosas, la que hoy está creciendo de verdad.

Capa 2 · El commit

① Dónde está el CAS — no donde lo buscábamos

Buscando el contador de versión que esperábamos encontrar en la tabla, aparece esto:

version : bigint   →  namespace · project · role · warehouse · generic_table
                      ⛔ NO existe en `table` ni en `tabular`

⇒ El bloqueo optimista con contador es para los objetos de gobierno del catálogo, no para las tablas. Lo que un commit de tabla mueve es otra cosa:

table_refs   PK (warehouse_id, table_id, table_ref_name)   →  snapshot_id
             179 refs `main`  +  2 ramas propias  ⭐

El «puntero» del que llevamos hablando es esta fila — la cabeza de la rama — y no el metadata_location. El CAS es el requirement de la spec Iceberg (assert-ref-snapshot-id) contrastado contra ese snapshot_id dentro de una transacción de Postgres. De ahí sale la propiedad que nos importa: un commit de 1 TB y uno de 1 KB cuestan lo mismo, porque lo que se compara y se escribe es un bigint.

② ⭐⭐ Quién manda, el fichero o la fila — resuelto

La capa 1 dejó la pregunta abierta y no se responde leyendo el esquema. Se responde poniendo las dos representaciones al lado:

npx tsx scripts/storage/diferencial-metadata.ts main.default ds_3f5ac26dea1f4fe8b4de094ec117487d

fichero en R2     31.255 B comprimidos → 238.046 B
respuesta REST                           238.046 B
¿idénticos byte a byte?  NO
primera divergencia en el byte 31.430 de 238.046:
  fichero  : …"snapshots":[{"snapshot-id":7863807021007333307,…
  respuesta: …"snapshots":[{"snapshot-id":2707857736196207888,…

Misma longitud, mismo contenido hasta el byte 31.430, y a partir de ahí el array de snapshots en otro orden. Y el control que lo cierra — cinco loadTable seguidos sobre la misma tabla:

llamada 1..5 : len=240.683 en las cinco · mismos tres primeros snapshots · CINCO HASHES DISTINTOS

Y tiene tres consecuencias prácticas, todas de la clase que muerde tarde:

③ La trampa de los 64 bits, reproducida sin querer

El primer intento de este diferencial comparó los dos lados con JSON.parse y dio todos los campos iguales. Lo eran: estaban mal los dos igual.

current-snapshot-id      827198859338249909
lo que JSON.parse deja:  827198859338249900   ⛔ MUTILADO

Los snapshot-id de Iceberg son enteros de 64 bits y en JS todo número es un double. Ésta es la causa exacta de los CatalogCommitConflicts sin concurrencia alguna que costaron el bloqueo de escritura: el motor commiteaba afirmando un id redondeado, y el CAS de §① —que compara un bigint— decía que no.

⇒ Por eso lib/governance/lossless-json.ts existe, y por eso el script permanente compara texto crudo. La trampa no está documentada por prudencia: está documentada porque volvió a picar hoy.

④ La idempotencia que el catálogo ofrece — y que no usa nadie

// GET /v1/config → overrides
{"idempotency-key-lifetime": "PT30M"}

idempotency_record   PK (warehouse_id, idempotency_key)   →  0 filas

El catálogo trae el mecanismo estándar para que un reintento no commitee dos veces, lo anuncia en su /v1/config, y su tabla está vacía: ningún cliente nuestro manda la clave. (Lo que sí hay en el repo con ese nombre es la idempotencia del executor, de otra capa y otro problema.)

⑤ El commit de varias tablas existe

POST /v1/{prefix}/transactions/commit está entre los 25 endpoints que declara (§capa 5). La documentación general decía que Lakekeeper no lo tenía; gana el endpoint. Hoy no lo usa nadie: el replace de la ingesta consigue su atomicidad con una Transaction de PyIceberg sobre una tabla —delete-all + add_files, dos snapshots y un solo commit_table— que es un CAS único.

Y el reintento está declarado en la tabla, no en el cliente: commit.retry.* en 83 de las 188 tablas (las nacidas por _create_native_table).

Capa 3 · El ciclo de vida

① Las tres colas, y cuál de ellas trabaja

SELECT queue_name, status, count(*) FROM task_log GROUP BY 1,2;

Y task_config está vacía: no hay configuración por warehouse ni por cola. Todo el ciclo de vida del catálogo corre con los valores por defecto, sin que nadie lo haya decidido.

Lo que hay en cola ahora mismo — y es lo que interesa:

tabular_expiration · scheduled · 2026-08-13T13:10 · task_data: { deletion_kind: 'purge' }   × 6

② ⭐⭐ El catálogo SÍ borra bytes — y esto corrige a DATA-STORAGE

La pieza del plano de bytes afirmó que «Lakekeeper tiene prohibido emitir DELETE contra R2» apoyándose en push-s3-delete-disabled: true. Es falso, y se comprueba con las 14 expiraciones que ya se ejecutaron: se listan sus prefijos en el bucket.

CONTROL POSITIVO · una tabla viva      683 obj · 4.867 KB   CONSERVA BYTES
las 14 que tabular_expiration ejecutó    0 obj              0 de 14 conservan bytes

14 de 14 sin un solo objeto, con control positivo al lado. Y descartada la explicación alternativa: en el repo no hay ninguna ruta que borre objetos de R2 salvo dos gates que limpian su propio prefijo de sondeo, y ninguno tocó estas tablas.

⇒ La imagen correcta del borrado: hay exactamente una vía que libera bytes, y es DROP con purga. push-s3-delete-disabled no significa «no borra».

③ ⛔⛔ La ventana de 7 días está vacía

El delete-profile es soft/604.800 s: durante siete días el catálogo dice que una tabla borrada se puede recuperar. Es el único colchón que tenemos — no hay Fail-safe como en Snowflake. Se comprueba igual, sobre las 6 que expiran mañana:

las 6 en BORRADO BLANDO (purga programada 2026-08-13)
   0 obj · 0 de 6 conservan bytes

Es el reverso exacto del riesgo de los dos pasos que ya conocíamos. Sabíamos que dropear sin borrar deja bytes huérfanos; esto es lo contrario y es peor: borrar los bytes a mano deja al registro prometiendo una recuperación que no puede cumplir, y sin ninguna señal de que no puede.

Y mañana a las 13:10 la purga correrá contra objetos que ya no están.

④ Qué cancela una expiración — el borrado blando sí es reversible en el catálogo

Las 2 canceladas del 2026-08-10 son la misma tabla dos veces: ds_ce4901bb… y ds_ce4901bb…__w1old. Es el ciclo de reparación W1 —drop sin purga, renombrar, recuperar—: recuperar o renombrar cancela la tarea programada.

⇒ El mecanismo de vuelta atrás funciona; lo que no existe es lo que devolvería los bytes.

⑤ Las dos ramas propias son TAGS, y son del JOP

carbon-precomp-f3a67bae-…   retention {"type":"tag"}   main.test.ds_38b26211…
carbon-precomp-afee2b56-…   retention {"type":"tag"}   main.test.ds_38b26211…
                            ambas creadas el 2026-08-10T14:51:54.572Z, `updated_at` NULL

Las crea services/ml-runner/app/routers/lakehouse.py:771 — tag = f"carbon-precomp-{body.operation_id}" — el verbo compensate. Y el tag no es decorativo: PyIceberg excluye de la expiración los snapshots con tag, así que la promesa de que un estado compensado sobrevive no descansa en una convención sino en el motor.

⑥ Lo que no tiene cola en absoluto

Capa 4 · Quién entra

① Ocho sujetos, y ni un solo rol

curl -sH "Authorization: Bearer $TOK" …/management/v1/user   # 8
curl -sH "Authorization: Bearer $TOK" …/management/v1/role   # {"roles":[]}

roles: []. No hay ninguna indirección: cada permiso es una arista directa sujeto → warehouse. Con la consecuencia práctica de siempre — revocarle el acceso a un servicio no es una operación, son trece, una por warehouse.

Y hay tres cuentas sin nada asignado. …-ml-runner es un fósil: el servicio ya ni siquiera lleva credencial de catálogo en su entorno (0 coincidencias), porque dejó de ser el escritor. Nadie la dio de baja.

② La retícula: cuatro verbos y un patrón repetido nueve veces

warehouse-writer     create · describe · modify
operator             create · describe · modify
index-catalog        create · describe · modify · select     ← la cara
duck-server                                        select

Idéntico en 9 de los 13 warehouses. Y resuelve la rareza que dejó la capa 3 —«¿por qué el writer tiene modify y no select?»— con una prueba en vivo: el writer recibe credencial de storage igualmente.

loadTable CON delegación     operator: 200 +llave    writer: 200 +llave    duck: 200 +llave

⇒ select no es «poder leer el dato»: el acceso al dato lo abre tanto select como modify. Lo que la retícula separa de verdad es quien sólo consulta (select) de quien además escribe (modify) — y el nombre invita a leerlo mal.

③ ⭐⭐ Aplica de verdad — medido con control positivo y negativo

authz-backend: openfga es una configuración. Que aplique es otra cosa, y se pregunta lo mismo con tres identidades distintas:

prueba                                  operator    warehouse-writer   duck-server
listNamespaces           (compartido)   200         200                200
loadTable metadata       (compartido)   200         200                200
loadTable con delegación (compartido)   200 +llave  200 +llave         200 +llave
listar warehouses                       200         200                200
ver los USUARIOS         (servidor)     200         403                403     ⭐

El 403 es el primer corte real: la asignación de servidor —operator, que sólo tiene una cuenta— está aplicando. Y el corte a nivel de warehouse se ve en los cuatro que no tienen a nadie dentro:

warehouse                                       operator   writer   duck
lakehouse                        (control +)    200        200      200
carbon-prod-w-cccc70a5…                         200        404      404
carbon-prod-w-7b500f4d…                         200        404      404
carbon-prod-w-ec14e3cc…                         200        404      404
carbon-prod-w-0936227f…                         200        404      404

④ ⛔⛔ Los cuatro warehouses a los que apunta Index están desiertos

Los cuatro del 404 son exactamente los cuatro de la discrepancia de DATA-STORAGE: aquellos a los que apunta el warehouse_id de Index. Su única asignación es operator: ownership.

⑤ Los cabos sueltos

Capa 5 · El contrato

① Lo que declara, y la trampa que lleva dentro

// GET /v1/config?warehouse=lakehouse
"overrides": { "uri": "https://…railway.app/catalog", "idempotency-key-lifetime": "PT30M" },
"defaults":  { "prefix": "4fb824d4-…", "rest-page-size": "100", "s3.delete-enabled": "false" },
"endpoints": [ …25… ]

La distinción no es cosmética: overrides manda sobre lo que el cliente tenga configurado; defaults sólo rellena huecos. Y en overrides va uri.

② La cara cubre 13 de 25 — y falla cerrada

routeCatalogRequest reconoce 13 operaciones. Lo que el catálogo ofrece y la cara no enruta:

Lo no enrutado se rechaza, no se reenvía:

if (!routed) return 404 'operación no gobernada: ${método} /v1/${ruta}'

Eso está bien —fallar cerrado es la decisión correcta— y tiene un precio que conviene decir en voz alta: la puerta es más estrecha que el catálogo, y las capacidades que hoy usamos de las bloqueadas (renombrar, registrar) funcionan porque van por fuera de ella. No falta la capacidad: falta por la puerta.

③ endpoints: [] — no declaramos nada

La spec REST usa ese campo desde 1.6 para que el cliente sepa qué pedir. El nuestro está vacío, así que un motor moderno sólo puede descubrir por ensayo y error… y todos los errores son 404. Declararlo con las 13 reales es barato y convierte un misterio en un contrato.

④ La paginación: a una tabla del corte

rest-page-size: 100          main.default: 99 tablas
con ?pageSize=10  →  next-page-token: SÍ, hay más

La paginación funciona y el catálogo la anuncia. El censo de DATA-STORAGE no la seguía: una tabla más en main.default y habría truncado en silencio — el mismo fallo que ya cometió al recorrer un solo warehouse, esperando a repetirse.

⇒ Arreglado hoy (censo-plano-bytes.ts sigue el next-page-token), con el mismo resultado: 188.

⑤ Capacidades completas y sin estrenar

⑥ Qué de todo esto nos ata

Lo que falta — con su gate

Historial