A finality rule is filename-discriminated from a guardrail: both live under
contracts/guardrails/, but only files named finality-*.yaml load as FinalityRule. Everything else in that directory loads as Guardrail.
contracts/metrics/*.yaml: MetricBinding
A metric binding is what turns a name like
revenue into something the compiler can actually run. metric is the name callers ask for, canonical is the recipe for computing it, and owner/aliases/examples exist to keep the binding discoverable and accountable rather than a bare formula nobody can trace back to a person or a prior query. status: deprecated lets you keep an old binding around for history without it competing for a name a newer binding now owns.
Ambiguity rule: if a requested name matches zero or more than one active binding, the compiler returns a structured AMBIGUOUS/UNRESOLVED error rather than guessing.
canonical (CanonicalRef): one shape per kind
kind selects a compilation strategy, and each kind needs a different subset of the fields below. Missing a required field for the chosen kind raises a located error at load time rather than failing later at query time. Most metrics are single, a direct pointer at one measure on one source. The other kinds exist for shapes a plain source-and-measure pair can’t express on its own: ratio and weighted_avg combine two other metrics after they’re each aggregated independently, semi_additive handles point-in-time values like balances that can’t just be summed across every dimension, distinct_count and percentile recompute their value at whatever grain the query asks for instead of pre-aggregating, cumulative turns an additive measure into a running total, offset reads another metric at an earlier period, derived combines metrics with arithmetic, conversion counts the events of one metric that follow the events of another for the same entity, and opaque is the escape hatch for a measure that’s only trustworthy at the exact grain it was computed at.
Full field list on
CanonicalRef:
Numerator parts
A ratio may declare the disjoint metrics that sum up to its numerator. This matters when the numerator contains the denominator, such as a result rate where costs are booked negative:result_rate is 1 + costs / revenue in disguise. canonic never derives this overlap from the data or the contract structure. numerator_parts is allowed on ratio (parts of numerator) and weighted_avg (parts of weighted_sum), and is returned by resolve_metric, describe_metric and the composition block of a query.
Validation rejects a declaration when:
- it is set on a kind other than
ratioorweighted_avg, - it lists fewer than two parts, or one part twice,
- a part does not resolve to an active metric of
kind: single, - a part reads a source that is not reachable from the source of the numerator.
Cumulative metrics
Acumulative binding is a running total: “revenue to date”, “sign-ups so far”. It names one additive measure and the dimensions to accumulate along.
order_by, so the same metric answers “running total overall” and “running total per channel”:
Aggregate first, accumulate last. The measure is aggregated to the requested dimensions like a
single metric, so joins, fanout handling, tenancy, population_filter and guardrails apply unchanged. The running total is a window over the aggregated rows, from the first order tuple to the current one. Order dimensions sort ascending with NULL last on every dialect.
Filters and history (history)
history decides whether rows that a query filter on the order columns excludes still count towards the total.
exclude(default): every query filter narrows the rows before aggregation, as for any metric. A query withorder_date >= '2026-03-01'returns a running total that starts at zero in March. Any filter is accepted.include: each query filter is classified by the physical columns it reads.- A filter that reads no order column (e.g.
channel = 'online') narrows the rows before aggregation. - A filter that reads only order columns (e.g.
order_date >= '2026-03-01') is a visibility filter. It picks which order tuples are shown, and the total still runs from the first row of data: the March row carries everything since the first order, not just March’s own revenue. A coarse bucket is shown when at least one of its rows matches. - A filter that reads both is rejected with
UNSUPPORTED_MEASURE. Split it into one filter per kind.
- A filter that reads no order column (e.g.
include when the number means “so far, ever”, such as customers to date or an account balance. population_filter is never a visibility filter. It defines the population and always applies before accumulation.
Gaps (on_gap)
A gap is an order tuple one partition has data for and another does not.
skip(default): only tuples with data produce a row. The running total stays correct across the gap, it is just not shown.fill_observed: every partition gets a row for every order tuple observed in the data, carrying its total forward. A partition starts at its own first observed tuple, never earlier, since a zero before the first record would be a fabricated number. A tuple with no data in any partition is still absent. The compiler adds a warning, because the row count can grow to observed tuples times partitions.
NULL before its partition’s first row.
Trailing windows and period to date
window turns the running total into a trailing window, grain_to_date into a total that restarts at the start of each period:
window: 7 days covers the day and the six days before it, and grain_to_date: month covers the first of the month up to the day. A day without rows of its own still has a value while its window holds data. A day whose window holds nothing has no row, and NULL next to another metric. Month, quarter and year windows clamp to the end of the month on every dialect: one month before 31 March is 28 or 29 February.
Output grain. order_by names the axis, one date or timestamp column. The query may group by the order dimension or by any other dimension on the same column, such as order_month or a week label, as long as it covers a day or more. Under a coarser grain, period_agg picks which day represents a bucket: its last day (last), its first day (first) or the mean over its days (average). The days run from the first day with data until the last window that still reaches data has passed, and never past as_of (or today), so the current month is represented by its latest day.
Filters. A window always reads its full lookback. A filter that reads only the order column, and a time_range on it, decide which days are shown: with order_date >= '2026-03-01', the value on 1 March still includes the last days of February. A filter on any other column narrows the rows as usual, and one that reads both is rejected with UNSUPPORTED_MEASURE. history therefore stays at its default, and on_gap: fill_observed is not needed, since every day is already there.
Validation. At write time, measure must be additive and use sum, count, min or max. Every order_by entry must resolve to a dimension reachable from source, of type date, timestamp, int, decimal or float. Strings are rejected, since their order depends on the engine’s collation. Two order dimensions over the same column (order_day and order_month over order_date) are rejected too, since the finer one already decides the order. With window, grain_to_date or a period_agg other than last, order_by must name exactly one dimension backed by one date or timestamp column, the window must be a day or longer, window and grain_to_date exclude each other, and grain_to_date may not be finer than a grain the order dimension declares. A cumulative metric cannot be a ratio or weighted_avg component.
Out of scope for now: a complete calendar series for the unbounded running total (fill_calendar), windows shorter than a day, and finality on a cumulative metric. A query that combines a cumulative metric with a metric under a finality rule is rejected with UNSUPPORTED_MEASURE.
Offset and derived metrics
Anoffset reads another metric at an earlier period. A derived metric combines metrics with arithmetic. Together they express period-over-period comparisons:
order_month shows the month the moved rows fall in, so a month, a week or a week label all compare like with like. A filter is read in output time: order_date >= '2026-01-01' on revenue_last_year selects the rows from 2025-01-01 on. population_filter, guardrails, tenant predicates and finality read the stored column, since they describe rows, not periods. The result lists the filters that were moved under metadata.offset, and warns when the query neither groups nor filters by the time column, since a total over all rows does not move.
The base may be any kind except opaque and a cumulative metric with window, grain_to_date or period_agg. A shifted ratio shifts both components. time_dimension is resolved per source the base reads, the way a requested dimension is.
Derived arithmetic. expr may use the input names, numbers, + - * /, parentheses, and COALESCE, NULLIF, ABS, ROUND, LEAST and GREATEST. Each input is computed as if it were requested alone, including its own guardrails, and the arithmetic is applied to its finished value per output row: a ratio already divided, a running total already accumulated. An input with no row is NULL there, so write COALESCE(costs, 0) to read it as zero. Inputs may be of any kind, derived and offset included, which is also how a ratio of two ratios is written. A ratio component still has to be single or distinct_count.
Validation. At write time, base and every input must resolve to an active metric, expr must read exactly its inputs and only what is listed above, there may be no cycle, and time_dimension must resolve to one date or timestamp column from every source the base reads. Two offsets combine only on the same column. decompose refuses both kinds.
Conversion metrics
Aconversion metric counts the events of one metric that follow the events of another for the same entity, such as rentals paid within five days of pickup or visits that lead to a purchase within a week:
window later, the bound included, with every constant property equal. Each conversion event counts once, for the latest matching base event. Base events at the same instant are ordered by the requested dimension values. conversions is the conversion metric over the attributed events, grouped by the dimension values of their base events, and 0 where the base metric has a row but nothing converted. conversion_rate divides that by the base metric queried alone.
The base side owns the query. Requested dimensions, filters and time_range apply to the base events. The conversion events keep only their metric’s population_filter, guardrails and tenant predicates, so a payment after the end of the queried range still counts for a rental inside it. A condition inside a measure expression does not narrow the events, only what the metric counts. Use a population_filter on the metric to narrow them.
Validation. At write time, both metrics must resolve to active single or distinct_count metrics, a single conversion metric must sum or count, and the entity, the times and the constant properties must name a column, or a dimension backed by one column, of their side’s own source. A window shorter than a day needs timestamps on both sides. A conversion cannot be a ratio component or the base of an offset, but it can be an input of a derived. At query time, a dimension or filter that fans out the base source is refused with FANOUT_UNSAFE, since a repeated base event would count its conversions under one of its values at random. decompose refuses the kind.
deprecated_alternatives[] (DeprecatedAlternative)
examples[] (Example)
contracts/guardrails/*.yaml: Guardrail
A guardrail attaches a rule to either a specific
(source, measure) pair or a whole metric, chosen by which shape you fill in under applies_to. Which fields besides kind are required depends entirely on that kind: a mandatory_filter needs filter, a restrict_source needs restrict_to and context, a min_trust needs level and context, a required_dimension needs dimension. severity decides how hard the rule bites: for restrict_source, min_trust, and required_dimension, error stops the query outright while warn lets it through with a warnings[] entry instead. mandatory_filter has no “block” action to gate, its predicate is always injected, and severity: warn there only adds the warnings[] entry. rationale is what actually gets shown to whoever hit the block (or the warning), so it’s worth writing for a person, not just as a code comment.
Guardrails and knowledge
Each entry ofguardrails_fired in the query metadata carries predicate, the filter or constraint the guardrail applied, and knowledge_refs, the ids of the knowledge pages that explain it. An agent reads them with read_knowledge_page instead of guessing a search term.
A page is listed when its sl_refs name an entity the guardrail reads: the guarded measure, a column of its filter (or the dimension declared on that column), or its dimension. A bare source in sl_refs does not match, because it would match every guardrail on that source. Setting knowledge_refs on the guardrail replaces this inference with exactly the pages you name. Only global pages that the caller’s role may read are returned, and an id that does not match a readable page is dropped. The ids are sorted.
contracts/guardrails/finality-*.yaml: FinalityRule
realizations[] (Realization)
A finality rule exists for a metric that can be served from more than one physical realization of the same data, typically a slower, fully-reconciled table and a faster, real-time one.
realizations lists each candidate source along with its role, final or provisional, and coalescing is the expression that decides which realization actually backs a given time window in the result. board_only_final is the piece that ties this to a guardrail: pair it with a restrict_source guardrail so a sensitive context (board reporting, say) only ever sees the final realization, never the faster but not-yet-settled one.
contracts/assertions/*.yaml: Assertion
expect (AssertionExpect)
An assertion is a known-good query paired with the answer it should produce, usually sourced from a finance close or another trusted report.
query is run through the exact same compiler path a real caller would hit, so an assertion tests the whole stack, not just the metric definition in isolation. source_of_truth matters more than it looks: it’s the thing that lets a reviewer trust the expected value in the first place, an assertion with no traceable origin is just a number someone typed in.
canonic assert runs every assertion through the compiler and gates on the result. canonic query --harness runs matching assertions inline against a single query.
contracts/policies/tenancy.yaml: TenancyPolicy
See Tenancy & access control for the concepts behind this file. At most one per project. Its presence is the feature switch for row-level tenant isolation.
scoped_sources[] (ScopedSource)
Validation rules, enforced at load time with a file+line location:
scoped_sourcesandshared_sourcesmust be disjoint: a source name appearing in both fails validation.tenancy_for(source)is total over every source in the project once this file is present: a source reachable by a query but declared in neither list isUndeclared, governed byundeclared_sourcerather than treated as unrestricted.
contracts/policies/roles.yaml: RolePolicy
See Tenancy & access control for the two runtime gaps (dimensions enforcement, knowledge.allow_tags defaults) that matter when authoring this file.
roles{} (RoleDef): one entry per role name
AllowDenyPolicy (metrics/dimensions): allow: null (default) is unrestricted subject to deny. allow: [] is a deliberate allow-nothing. "*" in allow is the explicit wildcard. deny always wins over allow.
masking[] (MaskingRule)
Validation rules, enforced at load time with a file+line location:
default_role, if set, must name a role declared inroles.inherits, if set, must resolve to a declared role and the resulting chain must be acyclic: a role that (directly or transitively) inherits from itself fails validation.inheritsis single-parent field-level override, not list-merge: a role that explicitly authors a field (even to an empty list) replaces the parent’s value for that field wholesale. A field left untouched inherits the parent’s value unchanged.