La superficie di query (OSL-SQL)

POST /osl/query è l’unico endpoint di consumo. Analitica strutturata, metriche, retrieval vettoriale governato e attraversamento del grafo si esprimono tutti qui — non impari cinque superfici per leggere un dominio.

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

Il body è una di tre forme mutuamente esclusive (mescolarle è 400 E0513); tutte e tre passano per la stessa cucitura governata e condividono un unico request_id:

Body	Cos’è
{ "osql": "…" }	OSL-SQL — il dialetto SQL semantico (la superficie canonica)
{ "sql": "…" }	Un SELECT grezzo di sola lettura sull’allowlist del tenant (lo slice SQL)
{ "metrics": […], "group_by": […], … }	Query di metriche in stile MetricFlow

Un endpoint, un'algebra

Il /osl/query unificato sostituisce i vecchi endpoint /osl/retrieve, /osl/joint/resolve e /osl/traverse (ora eliminati). Ognuno è una forma di OSL-SQL. È ciò che rende letteralmente vero “OSL è il solo strato di consumo”.

OSL-SQL

osql è un dialetto SQL semantico. Nomina solo oggetti semantici — osl.entities.<model> e le colonne dichiarate, oppure le table function RETRIEVE(...) / TRAVERSE(...). Non nomina mai una tabella fisica o una colonna grezza.

L’abbassamento è il confine di sicurezza

Il motore fa il parsing di osql (via sqlglot, dialetto trino) e lo abbassa a un IR di operatori chiuso — la scala deterministica su cui il modello di governance applica l’enforcement. L’abbassamento è totale e default-deny: qualsiasi costrutto che non si abbassa a un nodo IR noto viene rifiutato.

Lower(), non il parser, non l'allowlist

• L’allowlist SQL è invariata — non le si insegna mai ad accettare table function. RETRIEVE/TRAVERSE non la raggiungono mai come SQL; si abbassano a nodi IR smistati verso resolver governati.
• Solo il sottoalbero puramente strutturale viene serializzato verso Trino, nominando solo iceberg.curated.*. Quella gamba è governata dalla stessa cucitura, verbatim, di un {sql} scritto a mano — così la prova di sicurezza lo copre senza modifiche.
• Vietati ovunque: window function, CTE, LATERAL/UNNEST/PIVOT, subquery correlate, funzioni non in allowlist, più di una gamba con table function, una table function annidata dentro uno scalare. Tutti → 400 E0511.

Le cinque forme

lower() classifica ogni query in esattamente una forma e ne valida la grammatica:

Strutturata

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

Si abbassa a to_trino() → la cucitura SQL governata. I join tra entità strutturate sono consentiti solo come equijoin su chiave sigillata (vedi sotto).

RETRIEVE

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

Si abbassa allo store Lance governato + retrieval. Una colonna nuda passa così com’è; un <op>(col) nel SELECT è un operatore di proiezione.

TRAVERSE

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

Si abbassa all’attraversamento L2 governato a partire dalle chiavi ancora (salto dopo salto, cardinalità limitata + dedup).

Joint (record)

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

La forma “record” entity-first: colonne strutturate + evidenza Lance + attributi derivati per le chiavi date, in un’unica risoluzione.

Cross-modale

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 relazione è un filtro”: RETRIEVE viene eseguito per primo, le sue chiavi pre-filtrano la gamba strutturale, poi un hash join in-cella sulla chiave sigillata. Vedi sotto.

R3 è inesprimibile, non bloccato

L’unico nodo cross-relazionale è un equijoin il cui ON è un’uguaglianza scalare su una chiave di entità sigillata (le entity_key_columns del modello, o il campo scalar_indexed di un facet) su entrambe le gambe. Qualsiasi altro JOIN … ON → 400 E0514.

Non c’è sintassi che passi un secondo argomento relazionale a un operatore di similarità o LLM — un join semantico relazione×relazione in query time (il non-goal R3) è una proprietà strutturale della grammatica, non una blocklist da mantenere.

Il join cross-modale, eseguito

X JOIN RETRIEVE(...) ON X.k = R.k non è un join relazionale di due tabelle fisiche. Viene eseguito così:

1. RETRIEVE (governato) → passages, ciascuno con la propria chiave denormalizzata.
2. Gate in chiaro → i valori delle chiavi, oppure rifiuta (403 E0515).
3. Pre-filtro strutturato: … WHERE k IN (<keys>) → to_trino → SQL governato (la lista IN è costruita con la conversione di literal di sqlglot — a prova di injection).
4. Hash join in-cella sulla chiave sigillata, proiettando le colonne di ciascuna gamba.

Gate cross-modale fail-closed (E0515)

Prima di leggere la gamba strutturale, il motore dimostra che la chiave di join è in chiaro per il soggetto nella gamba RETRIEVE — deciso solo dall’output governato osservabile (redacted_fields / la sentinella ⟦redacted⟧ / l’assenza), mai dallo snapshot delle policy. Una chiave mascherata non correla mai con una chiave in chiaro di un passage.

Operatori di proiezione

Nella forma RETRIEVE, <op>(col) nel SELECT è un operatore di proiezione (RFC 0004). Sono mappe unarie — mai un join.

Classe	Operatori	Gira su	Se manca
Encoder (deterministico)	SIMILARITY, CLASSIFY, TAG, RANK, DEDUP, OUTLIER, CLUSTER	Sugli embedding già presenti nel chunk	—
Decoder (inferenza) richiede LLM	EXTRACT, SUMMARIZE, SCORE, GENERATE, COMPLETE	Un backend LLM	503 E0521

Sicurezza d'accesso preservata

Una proiezione opera su input già governato, quindi non può mai ampliare l’accesso. Le op encoder sono deterministiche; le op decoder sono non deterministiche (è inferenza, non una violazione). Un’op generativa il cui output non supera la validazione → 400 E0522.

Body SQL grezzo e MetricFlow

{ "sql": "<SELECT>" } è un SELECT di sola lettura validato contro l’allowlist del tenant con il punto di applicazione delle policy applicato (row filter + projection dallo snapshot composto). { "metrics": …, "group_by": … } segue la semantica di MetricFlow. Entrambi condividono la stessa cucitura governata di osql.

Stato della risoluzione MetricFlow

Il resolver MetricFlow → SQL è ancora pianificato; un body con metrics ma senza sql/osql restituisce 422 E1001. Lo slice SQL governato ({sql}) e osql sono implementato.

Codici di stato

Codice	Significato
200	Successo
400	Malformato / fuori grammatica (E0511), oggetto non dichiarato (E0512), il body mescola forme (E0513), JOIN non su chiave sigillata (E0514), sql vuoto (E0246)
403	Deny del PDP (E2101/E2102), chiave cross-modale non in chiaro (E0515), oggetto fuori dall’allowlist (E0512)
422	Valido ma non risolvibile — es. MetricFlow non ancora implementato (E1001)
503	Manca lo snapshot del PDP (E2001, fail-closed), op decoder senza backend LLM (E0521)
502	Fallimento di esecuzione di Trino (E0510)

Vedi Errori e codici di stato per l’envelope completo.

Accesso e capacitàCome la catena di delega, le concessioni e le versioni di oscuramento di un soggetto decidono cosa una query può vedere — fail-closed per costruzione.

Stato della spec

La superficie OSL-SQL è l’RFC 0005 (Status: Draft, 2026-07-02); il planner, l’executor e tutte e cinque le forme sono implementati. L’RFC 0002 (semantic_match) è Superseded — il retrieval è ora la sorgente di relazione RETRIEVE, non un predicato WHERE.