📇 PIEZA · INDEX-CATALOG — el plano de control

Qué es

R2            los bytes Parquet          ← no sabe de nadie
Lakekeeper    los punteros Iceberg       ← el CAS del commit
⭐ INDEX      quién existe · quién puede · qué se escribió · quién tocó · bajo qué regla

El invariante que lo define

Un catálogo Iceberg sabe qué tablas hay y dónde están sus ficheros. No sabe de inquilinos, ni de roles, ni de por qué se escribió algo, ni de quién lo leyó, ni de qué regla de retención rige. Eso es Index.

Qué NO es

• ⛔ No es la base de datos que lo aloja. Index Catalog son 15 tablas y 6,5 MB — el 1,21 % del Postgres donde vive. brain_embeddings, chat_sessions y los 27.042 objects del plano ontológico no son Index.
• No es el catálogo de registro. El commit lo serializa Lakekeeper; Index nunca serializa escrituras (invariante nº4).
• No es un servicio. Es un esquema + 4.668 líneas en lib/governance/ que consultan la puerta, la cara y el escritor.
• No aplica por sí mismo. Es la fuente; quien impide son la cara y Junction.

Los cinco pilares, y su estado real

Las cifras de C3, cada una con su unidad

privilege_grants        248 filas   ← los GRANTS (privilegio × securable × catalog role)
principal_grants        413 filas   ← la VISTA aplanada (principal × rol × grant)
   de ellas, de usuario  45
sujetos `user` distintos  12

⚠️ Son unidades distintas y no se suman. (Corrección: una versión anterior de esta pieza decía «380 grants», que era 368 + 12 — el conteo de la vista antes de la derivación más el número de sujetos. Dos magnitudes diferentes sumadas como si fueran la misma.)

C2, medido de verdad — no por la existencia de su variable

total 4.558 · últimas 24 h: 470 · últimos 7 días: 4.474
más reciente: 2026-08-12 11:14
por desenlace:    ok = 4.102   ·   ⭐ denied = 456
por superficie:   iceberg-rest = 3.338 · storage-vending = 1.137 · plan-auditor = 83

⭐⭐ Tres cosas que sólo se ven con este detalle:

1. 456 denegaciones registradas. La gobernanza no sólo se declara: deja rastro de lo que impidió.
2. Emite desde TRES superficies, no una: la cara Iceberg, el vending de almacenamiento (1.137 — la acuñación de credencial también deja asiento) y el propio auditor del plan (83, en shadow: mide y anota).
3. ⭐ La tabla ya tiene columna policy_id. El cruce «qué se usó / bajo qué política» está pre-cableado — esperando a que C1 tenga filas.

⚠️ (Y la lección de método: la versión anterior daba C2 por «encendido» porque ENABLE_ACCESS_EVENTS existía en Vercel. Es el mismo error que esta arquitectura ya tiene catalogado — available = cableado ≠ funcionando. Lo que lo prueba son los 470 eventos de hoy, no la variable.)

⭐⭐ Y el patrón que comparten todos: puro + I/O, separados

policy.ts       (PURO: resolvedor de herencia)   ·  policy-queries.ts     (Postgres)
privilege.ts    (PURO: vocabulario + decisión)   ·  privilege-queries.ts  (Postgres)
membership-grants.ts (PURO: la proyección)       ·  …-queries.ts          (Postgres)

«No toca la base de datos, no importa el cliente, no hace I/O. El resolvedor es una función de (cadena de securables, adjuntos) → políticas efectivas, y por eso se puede probar exhaustivamente sin infraestructura.»

⇒ La decisión de gobernanza es código puro y probado; la persistencia es un detalle. Es la propiedad más fuerte de la pieza — y lo que haría barato mudar el almacén.

C1 · La política — construida, heredable, y sin una sola fila

Lo que colapsó, y por qué importa. Antes de C1 la «política» estaba esparcida en cinco superficies que no compartían forma, no se heredaban y no aplicaban nada:

retention_policies (0) · egress_policies (0) · credential_egress_policies (0)
file_access_grants (2, «y su propia cabecera dice que no aplica»)
tier-policy.ts (una constante en un fichero que sólo lee un componente de UI)

⇒ La forma de Apache Polaris las colapsa en UNA primitiva: política tipada + adjunta a un securable + resolución que hereda por la cadena workspace › catalog › schema › dataset.

⛔ Pero los siete tipos que existen NO son de acceso

export type PolicyType =
  | 'retention' | 'snapshot_expiry' | 'compaction' | 'orphan_cleanup'
  | 'egress'    | 'tier_expectation' | 'custom'

Todos son de mantenimiento y ciclo de vida. ⛔ No hay row_filter ni column_mask. La primitiva de política existe, hereda y está probada — y la política de datos no está entre sus tipos.

⭐ Y la semántica de combinación ya está resuelta (override — gana el más específico — «no existen dos ventanas de retención vigentes a la vez»), que es justo la decisión que una política de celda tendría que tomar al revés: las de celda se ACUMULAN, no se sobreescriben.

C4 · El plano de control existe entero — y devuelve 404

management-api.ts calca la Management API del estándar y declara ocho recursos:

principal-roles · principal-role-members · catalog-roles · catalog-role-bindings
grants · policies · policy-attachments · usage

curl https://app.paladio.io/api/management/v1/grants     # → 404
curl https://app.paladio.io/api/management/v1/policies   # → 404

Porque ENABLE_INDEX_MANAGEMENT_API no está puesto: la ruta contesta «plano de control no habilitado».

⇒ ⛔ Hoy la única forma de administrar Index es SQL directo o un script. Y eso es exactamente lo que bloquea «que el cliente defina sus roles» — la superficie del cliente no es un desarrollo pendiente: es un interruptor apagado sobre una API que ya está escrita.

Los siete módulos que faltaban por estudiar

(Estudio hecho el 2026-08-12. 1.096 líneas leídas.)

⭐⭐⭐ El trío del VENDING — y reencuadra un hallazgo anterior

storage-vending.ts · el motivo. Hasta que existió, «cada motor llevaba una llave de R2 estática y de todo el bucket en su entorno: leía los bytes de todos los inquilinos, se autorizara lo que se autorizara arriba».

Y por qué lo hacemos nosotros y no Lakekeeper: su vending contra R2 está roto —lakekeeper#1630: la Temp-Credentials API de R2 no soporta sus actions—. Lo que no está roto es la API de R2 llamada directamente.

credential-vending.ts · la máquina, como superficie propia. Antes acuñar era «un efecto secundario de loadTable»; ahora es el patrón token vending machine de AWS — «credencial para el inquilino T, sobre P, para hacer O» — y loadTable es un cliente más. Es la primera vez que TABLE_WRITE_DATA decide algo.

⭐⭐⭐ Y aquí está el hallazgo que reencuadra la cara

⇒ ICEBERG-FACE medía el síntoma; esto es la causa. La ingesta no esquiva la cara por descuido de configuración: era la única forma de que funcionara, y mode: 'auto' —donde el modo lo decide el PRIVILEGIO, no la operación— es lo que lo arregla. «El mínimo privilegio no se relaja: se calcula bien.»

Dos cosas que el módulo dice en voz alta en vez de disimular

r2-local-sign.ts · acuñar sin llamar a nadie.

                    API de R2        firmado LOCAL
latencia            100-300 ms       ≈ 1 ms (en proceso)
cuota               consume          NO consume
acota por prefijo   sí               sí
acota por acciones  no               🔴 tampoco (medido)

⭐ El presupuesto es la razón de fondo: la REST API de Cloudflare admite 1.200 peticiones cada 5 minutos POR CUENTA, compartidas por todo. «Poner eso en el camino de cada escritura es atar el rendimiento de la plataforma a una cuota ajena.»

🔴 Y la promesa que no se cumplió: la doc de R2 anuncia actions —la lista explícita de operaciones S3— como exclusiva del firmado local, y era lo que lo acercaba a una session policy de AWS. Medido: R2 la rechaza en las cinco variantes probadas (InvalidArgument: X-Amz-Security-Token). Queda el preset scope, y basta.

⚠️ Y una consecuencia que hay que no olvidar: el accessKeyId es el del token padre. No es una fuga —sin sessionToken da SignatureDoesNotMatch— pero significa que en los logs de R2 todos los accesos se ven iguales.

Los otros cuatro

write-claim.ts · por qué las transacciones se quedaban colgadas. ratify busca el snapshot cuyo carbon.operation-id sea el id de la txn del ledger; la cara firmaba con un uuid propio. Nunca casaban ⇒ «las transacciones se quedan open para siempre, que es el estado medido: 20 colgadas, la más vieja del 01-08».

⚠️ Y no se propaga la cabecera, que era lo obvio, porque se midió y no funciona: «Spark fija las cabeceras del catálogo al CREAR la sesión, no por petición, y la sesión es caliente y compartida por inquilino (recrearla cuesta el 47× de sesión fría)». ⇒ el pool de sesiones de COMPUTE es lo que impide propagar la firma. Dos piezas que parecían independientes están atadas.

schema-reconcile.ts · Index guarda su PROPIA copia del esquema (datasets.schema, column_count, dataset_schema_versions) «y de ella comen los pickers de datos, el linaje, la UI del Warehouse y la ontología». Medido: esa copia sólo se escribía al nacer la tabla o desde los caminos de ingesta — ninguno es el editor SQL.

lossless-json.ts · el bug de 64 bits, con su medida.

Lakekeeper manda : current-snapshot-id = 2624199754595337768
Node JSON.parse  : current-snapshot-id = 2624199754595337700   ← destruido

No lanza. No avisa. Los últimos dígitos simplemente cambian. Y el síntoma aparecía tres capas más abajo y sin nombrar la causa: CommitFailedException: CatalogCommitConflicts — un conflicto de concurrencia donde no había concurrencia.

policy-queries.ts · lo único de C1 que habla con Postgres, y su regla: «la cadena se RESUELVE contra la BD; no se deriva de nombres ni se asume».

Y los cinco últimos — la imagen ya está completa

(1.074 líneas más. Con esto, los 24 módulos leídos.)

access-event.ts · la telemetría que no puede tumbar el producto.

Por eso nada lanza hacia fuera: recordAccessEvent es síncrono, no devuelve promesa que esperar, y «su peor caso es descontar un evento en un contador».

buffer acotado   BUFFER_LIMIT = 500   ← al llenarse DESCARTA y CUENTA (`dropped`)
vaciado          FLUSH_AT = 100       ← dispara sin esperar al siguiente tick

⭐ «Perder telemetría es aceptable; crecer sin límite en el proceso no.»

⚠️ Y una guarda que su propia prueba destapó: sin el cerrojo de «vaciado en curso», BUFFER_LIMIT era código muerto — flush hace el splice antes del primer await, o sea de forma síncrona, así que el buffer se vaciaba al tocar el umbral y jamás llegaba al tope.

Y tres decisiones de contenido que valen más que la mecánica:

catalog-tenant.ts · cómo un motor declara en nombre de quién pregunta. La cara sacaba el inquilino del nombre del namespace, y eso estaba roto: los namespaces vivos son main.default y main.test —«el canary opaco nunca se encendió»— así que toda operación de namespace devolvía 403. Y hay un caso que ninguna forma de nombre arregla: listNamespaces (el SHOW SCHEMAS de cualquier motor) no lleva namespace.

⭐ La solución no es nuestra: es de la spec. El prefix de Iceberg REST — el motor pide /v1/config?warehouse=w_<ws>, la cara le devuelve el prefix, y desde ahí todas sus rutas lo llevan. Lakekeeper lo usa para su warehouse-id; nosotros para el inquilino. ⇒ el inquilino viaja en TODAS las operaciones, listNamespaces incluida.

catalog-names.ts · y aquí Unity nos corrige un detalle de diseño. Hasta el 2026-08-10 el nombre lógico sólo existía en Index y la cara exponía ds_<uuid> como nombre de tabla. Funcionaba porque duck-server lo resolvía con su propio AST — «y dejó de funcionar en cuanto entró un segundo motor»: Spark recibía SELECT * FROM diets y contestaba TABLE_OR_VIEW_NOT_FOUND.

Y el argumento que lo cierra: traducir en la capa de arriba obliga a repetirlo una vez por motor y otra por superficie.

table-materialise.ts · por qué materializa la CARA y no la puerta. El approach lo planteó al revés, y al hacerlo apareció el motivo: la puerta no tiene el esquema — está dentro del DDL, así que habría que parsear SQL en la puerta, «que es lo que este repo evita en todas partes: el destino se DECLARA, no se parsea».

La cara lo recibe ya estructurado, en el body del createTable. Cero parseo.

motor → createTable {name:"ventas", schema:{…}}
  cara → resuelve el schema de Index desde el namespace (main.test → schema `test`)
       → CREA el dataset en Index                      ⇒ uuid
       → reescribe el body con name: ds_<uuid>
       → reenvía a Lakekeeper

management-api.ts · y el invariante que justifica que existan DOS APIs.

El plano de control de Index era Next, es decir una API propietaria — justo lo que ese invariante prohíbe. C4 lo calca de la Management API de Polaris, y fija la separación como invariante:

la API de DATOS    nunca muta gobernanza
la API de CONTROL  nunca sirve datos

«No es estética: son dos superficies con perfiles de riesgo, de latencia y de auditoría distintos. Mezclarlas es cómo un GET acaba pudiendo conceder un permiso.»

⭐⭐⭐ De qué DEPENDE Index para existir

Y aquí está el punto de inflexión de esta pieza:

                    ┌──────────────────────────────────────┐
   INDEX CATALOG ──▶│ el CATÁLOGO DE REGISTRO (hoy Lakekeeper) │
   (la autoridad)   │  · el nombre → puntero de metadata     │
                    │  · el CAS del commit  ← la ATOMICIDAD  │
                    └──────────────────────────────────────┘

Index no puede existir solo. Sabe quién puede y bajo qué regla, pero no sabe dónde están los ficheros ni puede serializar un commit. Esa mitad la pone el catálogo de registro — y por eso la conversación de Lakekeeper ↔ Gravitino es una conversación sobre Index, no sobre una pieza de infraestructura ajena.

⚠️ Y las dos mitades viven separadas por un océano: Index en us-east-1 (Supabase), el catálogo en Railway, el cómputo en europe-west1 (mapa §8·quater·bis).

Frente a Unity Catalog / Snowflake Horizon — qué tenemos y qué falta

Lo que falta — con su gate

Historial