🏛️ Warehouse — Reorganización a modelo Unity-Catalog (Visión + Approach)

1. La visión en una frase

El dato vive en el Warehouse; el documento vive en Project & Files.

Todo lo tabular (datasets) y no-estructurado gobernado (media → volumes), más credentials, connections, permisos, linaje y gobernanza, se organiza en un catálogo real tipo Unity Catalog. Las definiciones y documentos que autoran las building blocks (notebooks, notepads, dashboards, recetas de pipeline/workflow, ontología, definición de modelo) se quedan en Project & Files.

2. Los dos planos

El criterio del split: DATO vs. DOCUMENTO — no "quién lo produjo"

Trampa a evitar: "todos los outputs de las building blocks van a Files" es incorrecto. El output tabular de un pipeline / notebook / modelo es un dato → va al Warehouse como Dataset. Su receta/definición → Files.

3. La jerarquía (DECIDIDA)

Workspace            = Metastore   (frontera de tenant — ya existe)
  └─ Catalog         CREABLE, varios por workspace (equipo / dominio / entorno)   ◄─ modelo Multi-Catalog
       └─ Schema     ← un Project actual mapea aquí   (= namespace Iceberg)
            ├─ Dataset   ← tabla / datos (reutiliza el vocabulario actual)
            └─ Volume    ← media sets / items de media (no-estructurado gobernado)

  Governance / Credentials / Connections / Permisos / Lineage  ─ anclados a nivel de Catalog (cascada ↓)
  Shares received (EDC / Delta-sharing-like)                    ─ hermano del árbol

Por qué "Catalog" y no un nombre inventado: no es un préstamo de Databricks — es la verdad técnica del substrato. Lakekeeper ES un Iceberg REST catalog, y el modelo Iceberg ya es Catalog → Namespace → Table. Nombrar el contenedor top "Catalog" le pone a la capa de producto el nombre que la capa de almacenamiento ya tiene. Mapea 1:1:

4. Estado actual — la "chapuza" (grounded)

Hoy un dataset ES un file, y el "catálogo" del Warehouse es el árbol de carpetas re-proyectado:

• Derivación del árbol: app/api/dataspace/catalog/route.ts:44 → GROUP BY project_id. Los "proyectos" y "datasets" del Warehouse son literalmente la estructura de project_files, agrupada por la FK datasets.project_id. La posición la dicta la carpeta, no un schema.
• Namespace: hardcodeado a 'datasets' (WarehouseTab.tsx:210 default; checksum-client.ts:49; contrato en consumption-contract.ts:154). No hay jerarquía de namespace.
• Landing de dataset synceado: el usuario elige un output folder en Data Connection (dataset-writer.ts:746 lee output_folder de la metadata de credencial), y el ingest crea dos filas atómicas (app/api/datasets/ingest/route.ts:115-150): un project_files type='dataset' bajo esa carpeta + una fila datasets colgada por file_id.
• Media sets: patrón idéntico (lib/projects/fileBackedDatasetUpload.ts:121-172): project_files type='media_set' + fila datasets service='media_set' + los ficheros como manifest en dataset_rows.

Veredicto: un dataset = artefacto project_files en una carpeta + fila de metadata. Su lugar en el catálogo es folder-driven, no schema-driven. Eso es lo contrario del modelo UC de las capturas de Databricks (Catalog → Schema → Table/Volume, con Credentials/Connections/Permissions de primera clase).

5. Gap vs. Unity Catalog (~29% del modelo hoy)

Lo bueno: el plano de datos ya está catalog-ready — el tridente le dio a cada dataset identidad Iceberg real (namespace + snapshot) independiente del file. Lo que falta es el control-plane de organización y gobernanza encima, que vive en PG (PG = plano de control; R2+Lakekeeper = plano de datos).

6. Modelo de datos objetivo (BORRADOR — se refina por fase)

-- Contenedor top, creable, múltiple por workspace
catalogs (
  id, workspace_id, name, comment, owner_id,
  created_at, updated_at,
  UNIQUE (workspace_id, name)
)

-- Agrupación; un Project actual migra a un Schema
schemas (
  id, catalog_id → catalogs.id, name, comment, owner_id,
  legacy_project_id,            -- puente al project_files actual
  created_at, updated_at,
  UNIQUE (catalog_id, name)
)

-- El dataset gana su posición de catálogo (bridge: nullable al principio)
datasets.schema_id → schemas.id          -- backfill desde project_id
-- project_files/file_id se mantiene como PUNTERO LEGACY detrás de flag

-- Media governado
volumes (
  id, schema_id → schemas.id, name, kind ('media'|'file'),
  storage_ref, comment, created_at,
  UNIQUE (schema_id, name)
)

-- Registro central (sustituye secretos dispersos / env vars)
storage_credentials (id, workspace_id, name, provider, secret_ref, ...)
external_locations  (id, credential_id → storage_credentials.id, url_prefix, ...)
connections         (id, workspace_id, name, type, credential_id, config, ...)

-- El modelo GRANT (fase tardía — reemplaza el enforcement RLS-tenancy)
grants (id, principal_type, principal_id, object_type, object_id, privilege, ...)

Namespace Iceberg objetivo: de datasets.ds_{id} (fijo) → {catalog}.{schema}.ds_{id} (Lakekeeper soporta namespaces multi-nivel). El namespace pasa a ser derivado de la jerarquía, no una constante.

7. El linchpin: desacoplar el Dataset del project_files

Es LA pieza. Hoy el dato es un file; el Warehouse debe volverse autoritativo: el catálogo (catalog.schema.dataset) posiciona el dato, y la carpeta deja de ser su identidad.

Estrategia = seam / bridge detrás de flags (mismo método que el tridente, source-of-truth.md):

1. Se crean catalogs/schemas y se siembra 1 catalog default (main) por workspace.
2. Cada project existente se migra a un schema dentro de main (schemas.legacy_project_id).
3. datasets.schema_id se backfillea desde project_id.
4. El árbol del Warehouse gana el nivel Catalog, leyendo del nuevo modelo (derivado del legacy al principio).
5. El project_files queda como puntero legacy detrás de flag; se drena cuando el catálogo es fuente única.
6. El picker "output folder" de Data Connection se sustituye por "catalog.schema".

Multi-Catalog no implica big-bang: se empieza con el main sembrado y se crean más catalogs a futuro.

8. Approach por fases (BORRADOR)

Cada fase: seam-first, detrás de flags, project_files como puntero legacy hasta el drenaje.

Coordinación: hay una migración del tridente en curso (pipeline.output nativo, fase 2d — ver port-migration.md). W0-W1 son ortogonales (organización, no I/O), pero el cambio de namespace de W1 debe coordinarse con el write-path nativo.

9. Decisiones abiertas (a madurar)

• Frontera exacta Workspace = Metastore: ¿un metastore por org o por workspace? ¿catalogs compartibles entre workspaces?
• RLS → GRANT: cómo migrar el enforcement sin downtime; convivencia temporal RLS+GRANT.
• Views / Functions como objetos de catálogo (UC los tiene; Carbon no) — ¿en scope?
• Delta Sharing propio vs. seguir en EDC para el share cross-org.
• Credential vending para motores externos (del dataspace-router.md) — ¿converge aquí?
• Zero-copy EDC (Fase 5 del track dataspace) vs. copia actual.
• Modelos: en UC son objeto de catálogo (catalog.schema.model). ¿Se unifica ml_model_registry bajo el Warehouse o se queda en Files como "definición"?

10. Registro de decisiones