The query surface (OSL-SQL)

POST /osl/query is the single consumption endpoint. Structured analytics, metrics, governed vector retrieval and graph traversal are all expressed here — you don’t learn five surfaces to read a domain.

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

The body is one of three mutually-exclusive shapes (mixing them is 400 E0513); all three go through the same governed seam and share one request_id:

Body	What it is
{ "osql": "…" }	OSL-SQL — the semantic SQL dialect (the canonical surface)
{ "sql": "…" }	A raw read-only SELECT over the tenant allowlist (the SQL slice)
{ "metrics": […], "group_by": […], … }	MetricFlow-style metrics query (single-model simple metrics today)

One endpoint, one algebra

The unified /osl/query replaces the old /osl/retrieve, /osl/joint/resolve and /osl/traverse endpoints (now deleted). Each is a form of OSL-SQL. This is what makes “OSL is the sole consumption layer” literally true.

OSL-SQL

osql is a semantic SQL dialect. It names only semantic objects — osl.entities.<model> and declared columns, or the table functions RETRIEVE(...) / TRAVERSE(...). It never names a physical table or a raw column.

The lowering is the security boundary

The engine parses osql (via sqlglot, trino dialect) and lowers it to a closed operator IR — the deterministic ladder the governance model enforces over. Lowering is total and default-deny: any construct that does not lower to a known IR node is refused.

Lower(), not the parser, not the allowlist

• The SQL allowlist is unchanged — it is never taught to accept table functions. RETRIEVE/TRAVERSE never reach it as SQL; they lower to IR nodes dispatched to governed resolvers.
• Only the pure-structural subtree is serialized to Trino, naming only iceberg.curated.*. That leg is governed by the same seam, verbatim, as a hand-written {sql} — so the safety proof covers it without change.
• Forbidden anywhere: window functions, CTEs, LATERAL/UNNEST/PIVOT, correlated subqueries, non-allowlisted functions, more than one table-function leg, a table function nested inside a scalar. All → 400 E0511.

The five forms

lower() classifies each query into exactly one form and validates its grammar:

Structured

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

Lowers to to_trino() → the governed SQL seam. Joins between structured entities are allowed only as a sealed-key equijoin (see below).

RETRIEVE

SELECT text, source,
       SIMILARITY(text, 'churn risk') AS churn_similarity
FROM RETRIEVE(facet => 'meeting_transcripts',
              query => 'european equity exposure',
              top_k => 5)

Lowers to the governed Lance store + retrieval. A bare column passes through; an <op>(col) in the SELECT is a projection operator. The raw score used to rank the retrieval is not projectable and never served — a derived similarity must be computed explicitly (and aliased) to appear in the output.

TRAVERSE

SELECT invoice_id, amount_eur
FROM TRAVERSE(anchor_model => 'customer',
              target_model => 'invoice',
              keys         => ('c-anna', 'c-bruno'))

Lowers to the governed L2 traversal from the anchor keys (hop-by-hop, bounded cardinality + dedup).

Joint (record)

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

The entity-first “record” form: structured columns + Lance evidence + derived attributes for the given keys, in one resolution.

Cross-modal

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

“The relation is a filter”: RETRIEVE runs first, its keys prefilter the structural leg, then an in-cell hash join on the sealed key. See below.

R3 is inexpressible, not blocked

The only cross-relational node is an equijoin whose ON is a scalar equality on a sealed entity key on both legs — for a JointEntity leg the ON must use its declared primary_key, and the correlated facet field must be a declared, scalar-indexed metadata field. Any other JOIN … ON → 400 E0514.

There is no syntax that hands a second relational argument to a similarity or LLM operator — a relation×relation semantic join at query time (the non-goal R3) is a structural property of the grammar, not a blocklist to maintain.

The cross-modal join, executed

X JOIN RETRIEVE(...) ON X.k = R.k is not a relational join of two physical tables. It runs as:

1. RETRIEVE (governed) → passages, each carrying its denormalized key.
2. Cleartext gate → the key values, or refuse (403 E0515).
3. Structured prefilter: … WHERE k IN (<keys>) → to_trino → governed SQL (the IN-list is built with sqlglot literal conversion — injection-safe).
4. In-cell hash join on the sealed key, projecting each leg’s columns.

Fail-closed cross-modal gate (E0515)

Before reading the structural leg, the engine proves the join key is cleartext for the subject in the RETRIEVE leg — decided only from observable governed output (redacted_fields / the ⟦redacted⟧ sentinel / absence), never from the policy snapshot. A masked key never correlates with a cleartext passage key.

Projection operators

In the RETRIEVE form, <op>(col) in the SELECT is a projection operator (RFC 0004). They are unary maps — never a join.

Class	Operators	Runs	If missing
Encoder (deterministic)	SIMILARITY, CLASSIFY, TAG, RANK, DEDUP, OUTLIER, CLUSTER	On embeddings already in the chunk	—
Decoder (inference) needs LLM	EXTRACT, SUMMARIZE, SCORE, GENERATE, COMPLETE	An LLM backend	503 E0521

Access-safety preserved

A projection operates on already-governed input, so it can never expand access. Encoder ops are deterministic; decoder ops are non-deterministic (that’s inference, not a breach). A generative op whose output fails validation → 400 E0522.

Raw SQL & MetricFlow bodies

{ "sql": "<SELECT>" } is a read-only SELECT validated against the tenant allowlist with the policy enforcement point applied (row filters + projection from the composed snapshot). { "metrics": …, "group_by": … } follows MetricFlow semantics. Both share the same governed seam as osql.

MetricFlow resolution status

The MetricFlow body resolves an honest subset today: one or more simple metrics backed by measures of the same SemanticModel, local dimensions in group_by, where filters as {field, op, value}, order_by and limit. saved_query, ratio/cumulative/derived/conversion metrics, time grains and multi-model resolution return a resolvable E1002/E1004 — they are never partially executed. The governed SQL slice ({sql}) and osql are shipped.

Status codes

Code	Meaning
200	Success
400	Malformed / out-of-grammar (E0511), non-declared object (E0512), body mixes shapes (E0513), non-sealed-key JOIN (E0514), empty sql (E0246)
403	PDP deny (E2101/E2102), cross-modal key not cleartext (E0515), object outside allowlist (E0512)
422	Valid but unresolvable — e.g. MetricFlow not yet implemented (E1001)
503	PDP snapshot missing (E2001, fail-closed), decoder op with no LLM backend (E0521)
502	Trino execution failure (E0510)

See Errors & status codes for the full envelope.

Access & capabilitiesHow a subject's delegation chain, grants and redaction versions decide what a query can see — fail-closed by construction.

Spec status

The OSL-SQL surface is normative in SPEC §8.9, designed in RFC 0005 (Status: Accepted — the reference-engine rollout is implemented). The planner, executor and all five forms are live; a validate-without-execute mode is available as {osql, explain: true}. RFC 0002 (semantic_match) is Superseded — retrieval is now the RETRIEVE relation source, not a WHERE-predicate.