Core concepts

Building autonomous AI requires a new vocabulary. You cannot describe a deterministic, agent-ready data pipeline using legacy BI terminology. These are the fundamental concepts that power the Colrows autonomous semantic compiler.

Concept Area	Core Primitive	Why It Matters for AI
Logic	Metric Resolution	Eliminates manual metric drift
Security	Compile-time Authorization	Prevents unauthorized inference
Accuracy	Deterministic SQL	Removes model hallucination risk
Resilience	Signal-based Monitoring	Provides self-healing schema support

Compile-then-execute

Colrows treats every request - whether it arrives as natural language, SQL, or an agent tool call - as a program to be compiled, not as a string to be templated. The compiler runs four deterministic stages:

Four stages of the Colrows pipeline. — A request becomes a proof, then a plan, then dialect-perfect SQL.

Each stage is isolated. Context resolution finds the governed assets a request needs - metrics, datasets, terms, verified queries, join paths, and stored values - and only current, valid versions are eligible. AI may draft the SQL from that context, or an agent may supply SQL or pick a verified query, but the draft is never trusted as-is: before it runs, it is checked as read-only SQL, against the caller's data access, and against the query cost guard. The secure executor then applies row access, column access, and masking rules.

The benefit of this strict staging is straightforward: problems surface before execution. A query the caller may not run, or one that breaks the cost limits, is refused with an explainable error - not at the warehouse, after a 4-minute scan.

The semantic graph

The Consensus semantic layer is implemented as a typed, versioned, directed graph. Every curated asset - tables, columns, table relationships, category sets, semantic datasets, metrics, verified queries, business terms, business entities, events, actions, categories, and relationships - is a first-class, typed record. Edges encode structure such as HAS_COLUMN, FOREIGN_KEY, APPLIES_TO, DEPENDS_ON, and USES_TABLE.

A graph that connects customer, order, refund, net revenue, time-window constraint, region policy, and analyst persona around a central Consensus semantic graph. — A simplified slice of a real semantic graph. Concepts, metrics, events, and policies all share the same structural substrate.

Three properties of the graph are load-bearing:

Typed - every node has a known kind, and reasoning is structural, not string-based.
Versioned - changes never overwrite prior definitions. Each change creates a new semantic state, which makes point-in-time reproducibility a free property of the system.
Multi-scope - assets belong to your organization and most are tied to a datasource. An asset has organization scope by default, and a persona-scoped variant (available for business terms) replaces the organization version for that persona.

Metrics as state, not queries

In most platforms a metric is a SQL fragment: a SUM(...) FROM ... WHERE ... stored under a friendly name. Colrows treats a metric as derived semantic state - a continuously interpretable representation of business reality that any agent or query can reason over.

A metric like Net Revenue doesn't merely encode how to compute a number. It encodes:

Business meaning - what Net Revenue is, and how it differs from Gross Revenue or Bookings.
Valid grain - the level at which the metric is well-defined (per order, per invoice, per customer per day).
Dependencies - the exact Semantic Dataset versions and business terms it is built on.
Guidance and examples - rules for how the metric can be filtered, grouped, or compared, and questions it does and does not answer.
Downstream impact - which verified queries, cached SQL, and other assets depend on it.

The practical effect: when an agent observes that Net Revenue dropped, it can reason semantically - distinguishing volume-driven decline from refund-driven erosion - because those relationships are explicit in the metric's state, not buried in a CTE.

Join path proof

When a question spans several tables, Colrows does not guess a join from column names at query time. Joins come only from governed Table Relationships, each recording its join columns and operators, its cardinality, and per-side optionality. Path resolution is a bounded traversal over those relationships:

Only tables the caller can access, in the requested datasource, are considered.
Search depth is bounded (3 hops by default, at most 6), and cycles are excluded - a path never revisits a table.
Every edge carries its cardinality, with a FAN_OUT_RISK warning for joins that are not one-to-one and CARDINALITY_UNKNOWN when it was never proven.

If more than one path connects the tables, the result is flagged ambiguous; if none does, it reports NO_JOIN_PATH. Ambiguity is surfaced, never silently resolved.

Why this matters.

The single largest source of bad numbers in enterprise BI is the silent join - the warehouse cheerfully runs a query against a relationship the analyst didn't intend. Compile-time proof is the only way to make that class of error unreachable.

Multi-vector embeddings

Colrows does not represent an asset with a single embedding. Every asset is embedded as several vectors:

Label vectors - one for the asset's name and one for each synonym, which improves recall when natural language drifts (e.g., "lapse" vs. "churn").
Description vectors - built from the canonical, governed description. A metric's also carries its grain, guidance, and usage examples; a verified query adds one for each alternate question.

Vectors are used for candidate identification; each hit is reloaded and checked against the current record, its validity, and the caller's access before it is returned. Embeddings are never the source of truth.

Compile-time governance

Most data platforms enforce policy after a query has been generated - by masking columns, filtering rows, or denying results. Colrows checks policy before execution: semantic search and definition reads return only assets the caller may access, and every query is checked against data access policies before it reaches the warehouse.

Diagram showing post-hoc masking versus Colrows' compile-time approach where policy shapes the semantic subgraph before planning. — Policy shapes the subgraph. Unauthorized plans are never generated.

Access rules (RBAC and ABAC) decide what a user or group can read; row conditions and column rules are applied by the secure executor, and masking rules govern the values returned. Without an applicable allow rule, access is denied. Audit becomes a side effect of normal execution: every query run lands in the audit trail, and an agent execution also records its datasource, query kind and hash, verified query version, and semantic revision.

Autonomous maintenance

The semantic graph is maintained by a coordinated set of background pipelines:

Discovery - scanners and knowledge pipelines read schemas, profiles, query history, analytics platforms, and documents, and propose tables, relationships, category sets, descriptions, and business terms.
Validation - every asset is checked against the current catalog; one that fails is marked invalid and kept out of runtime until repaired.
Learning - answered questions are captured as SQL resolutions in a semantic resolution cache, with references to the assets they used, so proven SQL can be reused while it stays current.
Monitoring - semantic drift is caught through change records: metadata scans detect schema evolution, profile scans refresh stale profiles, and each change drives dependent assets, projections, and cached SQL back into a consistent state.

Point-in-time reproducibility

Because the graph is versioned, every earlier version of every asset stays readable. AI answers record the metrics, business terms, tables, and verified queries they used, with versions, and agent executions record the verified query version and the datasource's semantic revision. So you can always see which definitions produced a number. This is non-negotiable for regulators, but it's also useful for engineers debugging a number that "moved" between Monday and Wednesday.

Vocabulary cheat sheet

Term	What it means in Colrows
Concept	A typed semantic asset - metric, business term, business entity, event, dataset.
Anchor	The physical table or column a semantic asset is bound to, such as a business entity's primary table or the tables a term applies to.
Scope	Who an asset version applies to - the whole organization, or one persona.
Persona	A role defined for your organization; a persona-scoped asset variant overrides the organization version for that persona.
Constraint	A rule that limits how an asset or query may be used - metric grain and guidance, join cardinality, or an access policy (RBAC, ABAC, row and column rules).
Plan	The SQL to run - drafted by AI, supplied by an agent, or taken from a verified query - once it has passed validation.
Trace	The audit record of a single compile-then-execute run.

Terminology defines strategy.

If you call it a "dashboarding tool," you will build a dashboard. If you call it a "semantic compiler," you will build an autonomous AI backbone. Fix the Context, Not the Model.

See these concepts in practice

The primitives above aren't abstract - they power real autonomous systems. Explore:

SaaS Architecture Deep-Dive - how compile-then-execute works end-to-end
Text-to-SQL Accuracy Cliff - why deterministic compilation matters for accuracy