Curated context

Before the model writes any SQL, it reads background material — context. dst's context is curated: hand-picked and deliberately small. It is the semantic model (the files that describe your tables and metrics), the governed definitions (what your business terms mean), and the certified-definition pages a lens selects. A lens is dst's unit of scope; it picks which of those files apply.

The opposite is dumping: pointing the model at the whole catalog, the auto-generated data dictionary, everything you have. A data dictionary teaches the model enough to compute a plausible answer. It says nothing about which computation is the approved one, so the model decides that itself. Select the context instead, and the approved computation is the one it has.

dst does not force the choice. A lens can select a handful of assets or everything you have; both are legitimate starting points. The point is that context is a variable you can see and test: too much context, too little context, and the wrong context are three different failure modes, and the testing engine is how you find out which one you have. Curate, measure, adjust.

How the machinery enforces it

• The semantic model goes into the prompt whole. dst never gambles on a search step that might miss the facts the SQL must bind to. The lens is the primary means of keeping context accurate and manageable: it scopes the model to what the use case needs. dst does not truncate — the one cap in the serializer is the first five common_questions per entity. (A lens with metrics generates in two tiers, and the cheap first tier renders a reduced form of the model; see What the model sees.)
• Certified-definition pages are selected, not dumped. Pages marked usage_mode: auto are always in context. Pages marked search are included only when a simple word-overlap check says they match the question, and at most six of them. The item caps are managed defaults, not knobs. The semantic model always rides whole, so the caps only bound the certified-definition extras; keeping them fixed keeps prompts small and behavior stable across installs. What you tune is the judgment — what the lens selects — and the tests tell you whether it worked.

How curated context is authored

An entity file describes one table. Its fields teach judgment, not just structure: grain ("one row per closed deal"), use_cases (when to use the table and when to avoid it), common_questions, how joins multiply rows, and metric filters — conditions added to the WHERE clause automatically whenever that metric is computed.

# semantic/entities/deals.yaml (excerpt)
grain: one row per closed deal
use_cases:
  - Use for bookings, deal counts, deal sizes, and new-vs-existing business questions.
  - Avoid for commission or payout questions - payouts carries what reps earned.

Definitions (semantic/definitions/<term>.md) are small markdown files: a header plus prose. A definition can carry an enforceable sql_expr — the exact SQL expression for the term. A contested term can be marked status: ambiguous, with its possible meanings listed. That turns guessing into asking (see Clarification & refusal). Per-metric certified-definition pages carry the verified end of the curated layer: a definition plus a value a human actually ran and checked.

How curated context is selected

The lens selects; nothing flows in by default. select.definitions starts empty on purpose — you name the terms you want. Every selected term also helps route questions to the lens, so shared vocabulary must not spill into every lens automatically.

The wrong answers this closes are rarely obvious errors. They are plausible: test accounts counted as customers, two eras of invoices never combined, the same row counted twice because old versions were kept. Curated context and certified answers carry the facts that decide those cases.