version:0.1 doc:governance updated:2026

Guardrails

This page describes the runtime's semantic boundaries rather than a broad policy and approvals system. The repo's real strength is clear planner-backed guardrails around query construction and execution.

Strongly supported

graph-first package authoring
guided discovery through discover, inspect, plan, and build-options
safe fact-to-dimension traversal and ambiguous-path rejection
supported mixed-grain rewrites
historical attribute slicing with temporal-validity joins
event-count conversion metrics for the supported execution model
explainable validation, planning, and SQL lowering

Scope boundary

Semantic Rails is a semantic layer, not an ELT tool. The shipped surface is model relations, semantic joins, segments, metrics, supported predicates, compile/explain output, and package checks. A generalized pipeline for arbitrary derived relations, chained SQL, materialization orchestration, or unrestricted nested predicates is not part of the runtime contract.

Supported with explicit guardrails

Area	What works	How it fails when unsafe
Mixed grain	Planner-owned leaf rewrites for supported shapes	`MIXED_GRAIN_INVALID` or `REWRITE_NOT_SUPPORTED`
Temporal roles	Multiple clocks when bindings stay compatible	`INVALID_TEMPORAL_ROLE` or `INCOMPATIBLE_TEMPORAL_ROLE`
Metric predicates	Supported contextual and entity-only cases	`PREDICATE_SCOPE_UNSAFE` and related predicate errors
Conversions	Supported event-count model	`CONVERSION_NOT_SUPPORTED` for richer unsupported shapes

Limits

DuckDB is the zero-setup local execution backend; Snowflake execution is supported through Snow CLI or the optional native connector when a connection is configured. The other supported warehouses connect through their native connectors the same way.
metric_predicate is scoped to supported contextual and entity-only predicate shapes.
Path ranking is deterministic; it is not a fully costed planner.
Managed cloud execution-on-behalf is not part of the local runtime contract.
The API-key and request-context layer is a runtime shim, not JWT/JWKS, tenant administration, or billing.
Managed acceleration, result caching, materialization refresh, and cost-aware acceleration selection remain future work.
No managed materialization, caching, or relation-pipeline runtime - execution is the warehouse's job. Anything beyond shipped semantic primitives is out of scope, not roadmap.
The repo does not ship a broader action orchestration system.

When hard failures are expected

common blocked cases

- alias token matches multiple semantic objects
- multiple non-equivalent paths remain valid
- selected aggregation is not legal for the measure
- requested time role is invalid for the selected metric or measure
- grouped or filtered context would smear a predicate
- conversion shape falls outside the supported event-count model
- request requires arbitrary chained SQL or an unmodeled materialization boundary (out of scope per the experimental boundary above)
- no valid-values source exists for the requested dimension

A blocked query is often the correct product behavior. The site is deliberately explicit about this rather than promising silent fallback magic.

What guardrails do not cover yet

Declared value domain vs warehouse coverage. valid-values returns the authored value_domain / valid_values set for a dimension. The runtime does not currently warn when the declared domain is broader than the data — a dimension can advertise five categories while the warehouse only contains two. A filter on one of the missing values returns an empty result with no diagnostic. Treat the declared domain as the authoring contract, not a guarantee of warehouse coverage.
Unknown top-level field names in package YAML. schema_strict: true rejects legacy authoring forms and unknown values for typed fields, but may not reject unknown top-level field names — typos like dimentions: can be silently dropped. Cross-check the catalog after parsing.

Continue to API Reference for the public routes and representative request shapes that sit on top of these guardrails.