La superficie de consultas (OSL-SQL)

POST /osl/query es el único endpoint de consumo. La analítica estructurada, las métricas, el retrieval vectorial gobernado y la travesía de grafos se expresan todos aquí — no aprendes cinco superficies para leer un dominio.

POST /osl/query
Authorization: Bearer <jwt>           # attested delegation chain, see Authentication
Content-Type: application/json

El body es una de tres formas mutuamente excluyentes (mezclarlas es 400 E0513); las tres pasan por la misma costura gobernada y comparten un mismo request_id:

Body	Qué es
{ "osql": "…" }	OSL-SQL — el dialecto de SQL semántico (la superficie canónica)
{ "sql": "…" }	Un SELECT crudo de solo lectura sobre el allowlist del tenant (el slice de SQL)
{ "metrics": […], "group_by": […], … }	Consulta de métricas al estilo MetricFlow

Un endpoint, un álgebra

El /osl/query unificado reemplaza los antiguos endpoints /osl/retrieve, /osl/joint/resolve y /osl/traverse (ahora eliminados). Cada uno es una forma de OSL-SQL. Esto es lo que hace literalmente cierto que “OSL es la única capa de consumo”.

OSL-SQL

osql es un dialecto de SQL semántico. Nombra solo objetos semánticos — osl.entities.<model> y columnas declaradas, o las funciones de tabla RETRIEVE(...) / TRAVERSE(...). Nunca nombra una tabla física ni una columna cruda.

El lowering es la frontera de seguridad

El motor parsea osql (vía sqlglot, dialecto trino) y lo reduce a un IR de operadores cerrado — la escalera determinista sobre la que aplica el modelo de gobernanza. El lowering es total y default-deny: cualquier construcción que no reduzca a un nodo IR conocido se rechaza.

Lower(), no el parser, no el allowlist

• El allowlist de SQL no cambia — nunca se le enseña a aceptar funciones de tabla. RETRIEVE/TRAVERSE nunca lo alcanzan como SQL; reducen a nodos IR despachados a resolvers gobernados.
• Solo el subárbol puramente estructural se serializa a Trino, nombrando solo iceberg.curated.*. Esa pierna está gobernada por la misma costura, literalmente, que un {sql} escrito a mano — así que la prueba de seguridad la cubre sin cambios.
• Prohibido en cualquier sitio: funciones de ventana, CTEs, LATERAL/UNNEST/PIVOT, subconsultas correlacionadas, funciones fuera del allowlist, más de una pierna de función de tabla, una función de tabla anidada dentro de un escalar. Todo → 400 E0511.

Las cinco formas

lower() clasifica cada consulta en exactamente una forma y valida su gramática:

Estructurada

SELECT segment, COUNT(*) AS n
FROM osl.entities.Customer
WHERE country IN ('ES','FR','DE')
GROUP BY segment
ORDER BY n DESC
LIMIT 100

Reduce a to_trino() → la costura de SQL gobernada. Los joins entre entidades estructuradas solo se permiten como un equijoin de clave sellada (ver abajo).

RETRIEVE

SELECT SUMMARIZE(text) AS summary, score
FROM RETRIEVE(facet => 'meeting_transcripts',
              query => 'european equity exposure',
              top_k => 5)

Reduce al store Lance gobernado + retrieval. Una columna desnuda pasa tal cual; un <op>(col) en el SELECT es un operador de proyección.

TRAVERSE

SELECT concepto, amount_eur
FROM TRAVERSE(anchor => 'customer',
              target => 'orders',
              keys   => ('c-anna', 'c-bruno'))

Reduce a la travesía L2 gobernada desde las claves ancla (salto a salto, cardinalidad acotada + dedup).

Joint (registro)

SELECT name, segment, recent_meeting_topics
FROM osl.entities.Customer
WHERE customer_id IN ('9c1e…f04a', 'e4f8…2a91')

La forma “registro” orientada a entidad: columnas estructuradas + evidencia Lance

• atributos derivados para las claves dadas, en una sola resolución.

Cross-modal

SELECT x.segment, r.text, r.score
FROM osl.entities.Customer x
JOIN RETRIEVE(facet => 'meeting_transcripts',
              query => 'churn risk') r
  ON x.customer_id = r.customer_id

“La relación es un filtro”: RETRIEVE corre primero, sus claves prefiltran la pierna estructural, luego un hash join en la celda sobre la clave sellada. Ver abajo.

R3 es inexpresable, no bloqueada

El único nodo cross-relacional es un equijoin cuyo ON es una igualdad escalar sobre una clave de entidad sellada (las entity_key_columns del modelo, o el campo scalar_indexed de una faceta) en ambas piernas. Cualquier otro JOIN … ON → 400 E0514.

No hay sintaxis que pase un segundo argumento relacional a un operador de similitud o de LLM — un join semántico relación×relación en query time (el no-objetivo R3) es una propiedad estructural de la gramática, no una blocklist que mantener.

El join cross-modal, ejecutado

X JOIN RETRIEVE(...) ON X.k = R.k no es un join relacional de dos tablas físicas. Corre así:

1. RETRIEVE (gobernado) → passages, cada uno con su clave desnormalizada.
2. Compuerta en claro → los valores de la clave, o rechazo (403 E0515).
3. Prefiltro estructurado: … WHERE k IN (<keys>) → to_trino → SQL gobernado (la lista IN se construye con conversión de literales de sqlglot — a prueba de inyección).
4. Hash join en la celda sobre la clave sellada, proyectando las columnas de cada pierna.

Compuerta cross-modal fail-closed (E0515)

Antes de leer la pierna estructural, el motor prueba que la clave de join está en claro para el sujeto en la pierna RETRIEVE — decidido solo a partir de la salida gobernada observable (redacted_fields / el centinela ⟦redacted⟧ / la ausencia), nunca del snapshot de política. Una clave enmascarada nunca correlaciona con una clave de passage en claro.

Operadores de proyección

En la forma RETRIEVE, un <op>(col) en el SELECT es un operador de proyección (RFC 0004). Son mapas unarios — nunca un join.

Clase	Operadores	Se ejecuta en	Si falta
Encoder (determinista)	SIMILARITY, CLASSIFY, TAG, RANK, DEDUP, OUTLIER, CLUSTER	Sobre los embeddings ya presentes en el chunk	—
Decoder (inferencia) necesita LLM	EXTRACT, SUMMARIZE, SCORE, GENERATE, COMPLETE	Un backend LLM	503 E0521

Seguridad de acceso preservada

Una proyección opera sobre una entrada ya gobernada, así que nunca puede ampliar el acceso. Las ops encoder son deterministas; las ops decoder son no deterministas (eso es inferencia, no una brecha). Una op generativa cuya salida falla la validación → 400 E0522.

Bodies de SQL crudo y MetricFlow

{ "sql": "<SELECT>" } es un SELECT de solo lectura validado contra el allowlist del tenant con el punto de aplicación de política aplicado (filtros de filas + proyección del snapshot compuesto). { "metrics": …, "group_by": … } sigue la semántica de MetricFlow. Ambos comparten la misma costura gobernada que osql.

Estado de la resolución MetricFlow

El resolver de MetricFlow → SQL sigue planificado; un body con metrics pero sin sql/osql devuelve 422 E1001. El slice de SQL gobernado ({sql}) y osql están implementado.

Códigos de estado

Código	Significado
200	Éxito
400	Malformada / fuera de gramática (E0511), objeto no declarado (E0512), el body mezcla formas (E0513), JOIN sin clave sellada (E0514), sql vacío (E0246)
403	Deny del PDP (E2101/E2102), clave cross-modal no en claro (E0515), objeto fuera del allowlist (E0512)
422	Válida pero no resoluble — p. ej. MetricFlow aún no implementado (E1001)
503	Falta el snapshot del PDP (E2001, fail-closed), op decoder sin backend LLM (E0521)
502	Fallo de ejecución de Trino (E0510)

Ver Errores y códigos de estado para el envelope completo.

Acceso y capacidadesCómo la cadena de delegación de un sujeto, sus grants y las versiones de redacción deciden qué puede ver una consulta — fail-closed por construcción.

Estado de la spec

La superficie OSL-SQL es la RFC 0005 (Status: Draft, 2026-07-02); el planificador, el ejecutor y las cinco formas están implementados. La RFC 0002 (semantic_match) está reemplazada — el retrieval es ahora la fuente de relación RETRIEVE, no un predicado WHERE.