@duckcodeailabs/dql-agent 1.6.21 → 1.6.22

package/dist/answer-loop.d.ts

@@ -14,6 +14,7 @@
  * step. Tests can mock the provider with a canned response and exercise the
  * full pipeline.
  */
+import { type ResolvedTrustLabel } from '@duckcodeailabs/dql-core';
 import type { KGStore } from './kg/sqlite-fts.js';
 import type { KGNode, KGSearchHit } from './kg/types.js';
 import type { AgentProvider } from './providers/types.js';
@@ -21,8 +22,22 @@ import type { Skill } from './skills/loader.js';
 import type { AgentMemory } from './memory/sqlite-memory.js';
 import type { LocalContextPack, MetadataAgentIntent } from './metadata/catalog.js';
 import type { GeneratedDraftBlock } from './metadata/drafts.js';
+import { type MetricMatch } from './metadata/metric-match.js';
+import { type IntentDecision } from './intent-controller.js';
 export type AnswerKind = 'certified' | 'uncertified' | 'no_answer';
 export type AnswerSourceTier = 'certified_artifact' | 'business_context' | 'semantic_layer' | 'dbt_manifest' | 'no_answer';
+/**
+ * The chosen route, surfaced on EVERY AI result (spec 17, part C) so the UI can
+ * show "where the answer came from". `tier` is the coarse route bucket; `ref`
+ * names the governed artifact/metric used (e.g. `cumulative_revenue`); `label`
+ * is a ready-to-render sentence.
+ */
+export type AiRouteTier = 'certified_block' | 'semantic_metric' | 'generated_sql' | 'business_context' | 'no_answer';
+export interface AiRoute {
+    tier: AiRouteTier;
+    label: string;
+    ref?: string;
+}
 export type AnswerCertification = 'certified' | 'ai_generated' | 'analyst_review_required';
 export type AnswerReviewStatus = 'none' | 'draft_ready' | 'analyst_review_required' | 'certified';
 export type AgentIntent = MetadataAgentIntent | 'ad_hoc_analysis' | 'drillthrough';
@@ -157,6 +172,12 @@ export interface AgentAnswer {
     certification?: AnswerCertification;
     reviewStatus?: AnswerReviewStatus;
     confidence?: number;
+    /**
+     * P0 intent controller — the high-level action the agent decided this turn
+     * deserves (answer / clarify / investigate / compose_app) with a rationale.
+     * Advisory: callers route on it (compose_app → app build, investigate → research).
+     */
+    intentDecision?: IntentDecision;
     /** Final answer text (NL summary). */
     text: string;
     /** Alias for UI envelopes. */
@@ -177,7 +198,15 @@ export interface AgentAnswer {
     draftBlockId?: string;
     draftBlock?: GeneratedDraftBlock;
     promoteCommand?: string;
+    /** Legacy free-form trust label string, retained for backward compatibility. */
     trustLabel?: string;
+    /**
+     * Canonical trust label (base + optional qualifier) drawn from the one shared
+     * vocabulary in dql-core, derived from this answer's source tier and review
+     * state. Lets every surface render the same label set as the MCP answer
+     * contract and the UI badge.
+     */
+    trustLabelInfo?: ResolvedTrustLabel;
     sourceCertifiedBlock?: string;
     contextPackId?: string;
     validationWarnings?: string[];
@@ -185,6 +214,8 @@ export interface AgentAnswer {
     citations: AgentCitation[];
     /** Relevant local memory supplied as advisory context. */
     memoryContext?: AgentMemory[];
+    /** Approved Hint-Graph corrections that were applied to this answer (for transparency). */
+    appliedHints?: LocalContextPack['appliedHints'];
     /** Evidence path connecting the question to metadata, SQL/block execution, and review state. */
     evidence?: AgentEvidence;
     /** Business-facing plan the agent used to answer the question. */
@@ -195,6 +226,24 @@ export interface AgentAnswer {
     contextPack?: LocalContextPack;
     /** Top KG hits the loop considered, useful for the UI's "we considered" panel. */
     considered: KGSearchHit[];
+    /** The Skills that shaped this answer (selected, not all), for transparency. */
+    appliedSkills?: Array<{
+        id: string;
+        description?: string;
+    }>;
+    /**
+     * The chosen route (spec 17, part C). Surfaced on every result so the UI can
+     * show which tier answered (certified block, governed semantic metric,
+     * generated SQL, business context, or an honest refusal). Computed once at the
+     * single exit point in `answer()`.
+     */
+    route?: AiRoute;
+    /**
+     * Internal: the governed metric the semantic tier matched (spec 17, part C).
+     * Used only to build `route` at the `answer()` exit point; not part of the
+     * stable public payload.
+     */
+    _semanticMetricMatch?: MetricMatch;
 }
 export interface AgentResultPayload {
     columns: unknown[];

package/dist/answer-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"answer-loop.d.ts","sourceRoot":"","sources":["../src/answer-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"answer-loop.d.ts","sourceRoot":"","sources":["../src/answer-loop.ts"],"names":[],"mappings":"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"}

package/dist/answer-loop.js

@@ -14,8 +14,12 @@
  * step. Tests can mock the provider with a canned response and exercise the
  * full pipeline.
  */
-import { buildSkillBlockHints, buildSkillsPrompt } from './skills/loader.js';
+import { composeEffectiveTrust, } from '@duckcodeailabs/dql-core';
+import { buildSkillBlockHints, buildSkillsPrompt, selectRelevantSkills } from './skills/loader.js';
+import { matchSemanticMetric, resolveGovernedMetricSql } from './metadata/metric-match.js';
+import { decideAgentAction } from './intent-controller.js';
 import { validateSqlAgainstLocalContext } from './metadata/sql-context-validation.js';
+import { buildGroundingFromRuntimeRelations, resolveRelationsInSql, validateSqlAgainstGrounding } from './metadata/sql-grounding.js';
 import { compactSqlSnippet, extractSimpleSelectShape, selectExpressionOutputName, } from './metadata/sql-shape.js';
 const CERTIFIED_HIT_THRESHOLD = 0.18;
 const HARD_NEGATIVE_RATIO = 0.5;
@@ -24,8 +28,112 @@ const BUSINESS_CONTEXT_KINDS = ['term', 'business_view'];
 const ARTIFACT_KINDS = [...EXECUTABLE_ARTIFACT_KINDS, ...BUSINESS_CONTEXT_KINDS];
 const SEMANTIC_KINDS = ['metric', 'dimension', 'measure', 'entity', 'semantic_model', 'saved_query'];
 const MANIFEST_KINDS = ['dbt_model', 'dbt_source'];
+/**
+ * Map an answer-loop result's source tier + certification + review state to a
+ * canonical trust-label id from the one shared vocabulary in dql-core.
+ * Additive and lenient — keeps the legacy `trustLabel` string untouched.
+ */
+function canonicalTrustLabelId(result) {
+    if (result.kind === 'no_answer')
+        return 'insufficient_context';
+    if (result.certification === 'certified' || result.kind === 'certified')
+        return 'certified';
+    if (result.sourceTier === 'business_context' && result.reviewStatus === 'certified')
+        return 'reviewed';
+    if (result.certification === 'ai_generated' ||
+        result.certification === 'analyst_review_required' ||
+        result.reviewStatus === 'analyst_review_required' ||
+        result.reviewStatus === 'draft_ready') {
+        return 'ai_generated';
+    }
+    return 'insufficient_context';
+}
 export async function answer(input) {
+    const result = await runAnswerLoop(input);
+    // Attach the canonical trust label once, at the single exit point, so every
+    // return site inside runAnswerLoop stays untouched and backward compatible.
+    // Freshness-aware trust: for a certified answer, fold the source block's data
+    // health (stale/failed upstream) into the label so it reads "Certified ·
+    // stale data" / "Certified · upstream failed". Non-certified or fresh answers
+    // are unaffected.
+    const id = canonicalTrustLabelId(result);
+    const dataState = id === 'certified'
+        ? (result.block?.dataState)
+        : undefined;
+    const { _semanticMetricMatch, ...publicResult } = result;
+    const chosenRoute = result.route ?? deriveAiRoute(result, _semanticMetricMatch);
+    // P0 — record the high-level action this turn warranted, so callers can route
+    // (compose_app → app build, investigate → research) and the UI can show the
+    // agent's reasoning. Computed once at the single exit from the finished answer.
+    const tier = chosenRoute?.tier;
+    const intentDecision = decideAgentAction({
+        question: input.question,
+        intent: tier === 'no_answer' ? 'clarify' : 'ad_hoc_ranking',
+        signals: {
+            certifiedScore: tier === 'certified_block' ? 0.9 : 0,
+            metricScore: tier === 'semantic_metric' ? 0.9 : 0,
+            hasRetrieval: (result.considered?.length ?? 0) > 0,
+            missingContext: tier === 'no_answer' ? ['Need a clearer business object, measure, or grain before answering.'] : [],
+        },
+        isFollowUp: Boolean(input.followUp),
+    });
+    return {
+        ...publicResult,
+        intentDecision,
+        trustLabelInfo: composeEffectiveTrust({ id, dataState }),
+        // Stamp the SELECTED skills that shaped the answer (transparency). Computed
+        // here so every return site inside runAnswerLoop stays untouched.
+        appliedSkills: result.appliedSkills ??
+            selectRelevantSkills(input.skills ?? [], input.question, { userId: input.userId ?? null }).map((s) => ({
+                id: s.id,
+                description: s.description,
+            })),
+        // Stamp the chosen route once, at the single exit point, so every return
+        // site inside runAnswerLoop stays untouched (spec 17, part C).
+        route: chosenRoute,
+    };
+}
+/**
+ * Derive the UI-facing route from a finished answer (spec 17, part C). The
+ * semantic-metric tier is named explicitly when the loop matched a governed
+ * metric; otherwise the route is mapped from the answer's source tier / kind.
+ */
+function deriveAiRoute(result, metricMatch) {
+    if (result.kind === 'no_answer') {
+        return { tier: 'no_answer', label: 'No governed answer — needs more context or review.' };
+    }
+    if (result.kind === 'certified') {
+        if (result.sourceTier === 'business_context') {
+            const ref = result.citations[0]?.name;
+            return {
+                tier: 'business_context',
+                label: ref ? `Answered from certified business context ${ref}` : 'Answered from certified business context',
+                ref,
+            };
+        }
+        const ref = result.sourceCertifiedBlock ?? result.block?.name ?? result.citations[0]?.name;
+        return {
+            tier: 'certified_block',
+            label: ref ? `Answered from certified block ${ref}` : 'Answered from a certified block',
+            ref,
+        };
+    }
+    // Uncertified: a governed metric matched → semantic_metric; else generated SQL.
+    if (result.sourceTier === 'semantic_layer' && metricMatch) {
+        return {
+            tier: 'semantic_metric',
+            label: `Answered from metric ${metricMatch.metric.name}`,
+            ref: metricMatch.metric.name,
+        };
+    }
+    return { tier: 'generated_sql', label: 'Answered with generated SQL (review required).' };
+}
+async function runAnswerLoop(input) {
     const { question, userId, domain, provider, kg, skills = [], blockHints = [] } = input;
+    // Select the RELEVANT skills (not all) for this question; keep pinned project
+    // skills (SQL conventions). Block hints still come from the full set so a
+    // preferred-block mapping is never lost.
+    const selectedSkills = selectRelevantSkills(skills, question, { userId: userId ?? null });
     const effectiveBlockHints = Array.from(new Set([
         ...blockHints,
         ...buildSkillBlockHints(skills, userId ?? null),
@@ -148,7 +256,16 @@ export async function answer(input) {
             providerUsed: provider.name,
         };
     }
-    if (intent === 'clarify' || catalogRoute?.route === 'clarify') {
+    // Spec 17, part C — SEMANTIC-METRIC MATCHING. Must run BEFORE the clarify
+    // short-circuit: FTS alone misses clear metric questions ("total revenue" never
+    // literally names a metric), so a clarify route would otherwise refuse a question
+    // a governed metric can answer. Match by name + synonyms + measure family + hybrid
+    // rank over the FTS semantic hits, then ALL metric KG nodes (revenue ⇄
+    // cumulative_revenue). Certified-first is still preserved (checked above).
+    const semanticMetricNodes = collectMetricCandidates(semanticHits, considered, kg);
+    let semanticMetricMatch = await matchSemanticMetric(question, semanticMetricNodes).catch(() => null);
+    // Clarify only when there is ALSO no confident governed-metric match.
+    if ((intent === 'clarify' || catalogRoute?.route === 'clarify') && !semanticMetricMatch) {
         const text = composeCatalogClarificationText(question, catalogRoute) ?? composeClarificationText(question, considered, schemaContext);
         const analysisPlan = buildAnalysisPlan({
             question,
@@ -189,19 +306,27 @@ export async function answer(input) {
     }
     // Stage 2/3: generate only after certified artifacts miss. Semantic context
     // wins over raw dbt manifest context; memory is appended last as advisory.
-    const activeTier = sourceTierFromContextPack(input.contextPack) ?? (semanticHits.length > 0
-        ? 'semantic_layer'
-        : manifestHits.length > 0
-            ? 'dbt_manifest'
-            : 'dbt_manifest');
+    // A confident metric match forces the semantic tier even when FTS returned no
+    // semantic hits, so the governed metric (not refusal) answers the question.
+    const activeTier = sourceTierFromContextPack(input.contextPack)
+        ?? (semanticHits.length > 0 || semanticMetricMatch
+            ? 'semantic_layer'
+            : manifestHits.length > 0
+                ? 'dbt_manifest'
+                : 'dbt_manifest');
     const reviewRequiredArtifactHits = artifactHits
         .filter((hit) => hit.score >= CERTIFIED_HIT_THRESHOLD && !isCertifiedHit(hit, kg))
         .slice(0, 4);
     const trustedArtifactContext = rankGeneratedContextHits(executableArtifactHits.filter((hit) => !excludedArtifactIds?.has(hit.node.nodeId)), schemaContext, question)
         .filter((hit) => !excludedArtifactIds?.has(hit.node.nodeId))
         .slice(0, 5);
+    // When a governed metric matched (spec 17, part C), pin it at the front of the
+    // semantic context so the generated SQL is grounded on the metric definition.
+    const matchedMetricHit = semanticMetricMatch
+        ? [{ node: semanticMetricMatch.metric, score: Math.max(semanticMetricMatch.score, CERTIFIED_HIT_THRESHOLD) }]
+        : [];
     const contextHits = activeTier === 'semantic_layer'
-        ? [...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...semanticHits, ...manifestHits].slice(0, 14)
+        ? [...matchedMetricHit, ...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...semanticHits, ...manifestHits].slice(0, 14)
         : [...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...manifestHits].slice(0, 14);
     const contextNodes = mergeNodes(followUpSourceBlock && input.followUp?.kind === 'drilldown' ? [followUpSourceBlock] : [], (contextHits.length > 0 ? contextHits : considered.slice(0, 6)).map((h) => h.node));
     const contextBlocks = contextNodes.filter((n) => n.kind === 'block');
@@ -210,7 +335,7 @@ export async function answer(input) {
     const messages = [
         { role: 'system', content: SYSTEM_PROMPT },
     ];
-    const skillsPrompt = buildSkillsPrompt(skills, userId ?? null);
+    const skillsPrompt = buildSkillsPrompt(selectedSkills, userId ?? null);
     if (skillsPrompt)
         messages.push({ role: 'system', content: skillsPrompt });
     messages.push({
@@ -267,6 +392,35 @@ export async function answer(input) {
         }
         parsed = parseProposal(proposed);
     }
+    // True when `parsed.sql` was synthesized deterministically from a governed
+    // semantic-layer metric (not the LLM). Such SQL is trusted and grounded against
+    // the runtime schema, so it skips the hallucination-guard context validation
+    // that exists to catch model-invented relations/columns.
+    let governedMetricAnswer = false;
+    if (!parsed.sql) {
+        // Spec 17, part C — if a governed metric matched confidently but the model
+        // declined SQL, answer from the metric definition (deterministic, offline)
+        // rather than refusing. The semantic tier is the governed answer here. A
+        // derived MetricFlow metric (e.g. `revenue`) often carries no executable
+        // definition itself — its `table:`/`sql:` live on the backing measure node
+        // (`order_item.revenue`). resolveGovernedMetricSql resolves a thin metric to
+        // that synthesizable sibling so the route lands on a real number, not refusal.
+        const resolved = activeTier === 'semantic_layer' && semanticMetricMatch
+            ? resolveGovernedMetricSql(semanticMetricMatch.metric, semanticMetricNodes)
+            : undefined;
+        if (resolved) {
+            // Point the match at the metric we actually answered from so the route
+            // badge, citation, and carrier all reflect the executable definition used.
+            semanticMetricMatch = { ...semanticMetricMatch, metric: resolved.metric };
+            governedMetricAnswer = true;
+            parsed = {
+                sql: resolved.sql,
+                text: parsed.text ||
+                    `Answered from the governed metric ${resolved.metric.name}. This result is uncertified until reviewed and promoted.`,
+                viz: parsed.viz ?? 'single_value',
+            };
+        }
+    }
     if (!parsed.sql) {
         const text = parsed.text || 'No answer (the model declined to propose SQL).';
         return {
@@ -294,11 +448,69 @@ export async function answer(input) {
             providerUsed: provider.name,
         };
     }
-    const contextValidation = validateSqlAgainstLocalContext(parsed.sql, input.contextPack, {
-        question,
-        intent,
-        filterValues: input.followUp?.filters,
-    });
+    // Shared grounding (spec 15): deterministically qualify any bare relation the
+    // model emitted to its real warehouse relation from the runtime schema BEFORE
+    // governance validation. Same resolver the build path uses — one grounding,
+    // no weak path. `allowedSqlContext` relations are already qualified.
+    let grounding;
+    if (parsed.sql && schemaContext.length > 0) {
+        grounding = buildGroundingFromRuntimeRelations(schemaContext.map((table) => ({
+            relation: table.relation,
+            name: table.name,
+            columns: table.columns.map((column) => ({ name: column.name, type: column.type, description: column.description })),
+        })));
+        parsed.sql = resolveRelationsInSql(parsed.sql, grounding, { prefer: 'qualified' }).sql;
+    }
+    // Validation gate. Governed metric SQL synthesized from the semantic layer is
+    // already trusted (deterministic + grounded); model SQL is validated against the
+    // inspected context to catch hallucinated relations/columns.
+    const semanticMetricRoute = activeTier === 'semantic_layer' && Boolean(semanticMetricMatch);
+    let contextValidation;
+    if (governedMetricAnswer) {
+        contextValidation = { ok: true, warnings: [] };
+    }
+    else {
+        const c = validateSqlAgainstLocalContext(parsed.sql, input.contextPack, {
+            question,
+            intent,
+            filterValues: input.followUp?.filters,
+        });
+        contextValidation = c.ok
+            ? { ok: true, warnings: c.warnings }
+            : { ok: false, error: c.error, warnings: c.warnings };
+    }
+    // Spec 17, part C — semantic-metric route recovery. A metric question is often
+    // catalog-routed to clarify, leaving a thin contextPack that rejects otherwise-valid
+    // SQL. Rather than refuse, recover in two steps:
+    //   1) Re-judge the model's own SQL against the RUNTIME grounding. If it references
+    //      real relations/columns it is valid (the contextPack rejection was a false
+    //      negative) — keep the model SQL so a precise answer like `count(*) FROM orders`
+    //      stands instead of guessing a measure.
+    //   2) Otherwise fall back to a CLEAN governed-metric definition (direct or exact
+    //      leaf-measure; no fuzzy family guess that could answer the wrong measure).
+    if (!contextValidation.ok && semanticMetricRoute && semanticMetricMatch) {
+        const grounded = grounding ? validateSqlAgainstGrounding(parsed.sql, grounding) : undefined;
+        if (grounded?.ok) {
+            contextValidation = { ok: true, warnings: grounded.warnings };
+        }
+        else {
+            const recovered = resolveGovernedMetricSql(semanticMetricMatch.metric, semanticMetricNodes);
+            if (recovered) {
+                semanticMetricMatch = { ...semanticMetricMatch, metric: recovered.metric };
+                parsed.sql = grounding
+                    ? resolveRelationsInSql(recovered.sql, grounding, { prefer: 'qualified' }).sql
+                    : recovered.sql;
+                parsed.viz = parsed.viz ?? 'single_value';
+                parsed.text = parsed.text
+                    || `Answered from the governed metric ${recovered.metric.name}. This result is uncertified until reviewed and promoted.`;
+                governedMetricAnswer = true;
+                contextValidation = {
+                    ok: true,
+                    warnings: ['Generated SQL failed context validation; answered from the governed metric definition instead.'],
+                };
+            }
+        }
+    }
     if (!contextValidation.ok) {
         const text = `I could not safely prepare this generated SQL from the inspected context. ${contextValidation.error}`;
         const analysisPlan = buildAnalysisPlan({
@@ -514,6 +726,9 @@ export async function answer(input) {
         contextPack: input.contextPack,
         considered,
         providerUsed: localProposal ? 'schema_planner' : provider.name,
+        // Carry the governed metric match so the exit point can name a
+        // `semantic_metric` route (spec 17, part C).
+        _semanticMetricMatch: activeTier === 'semantic_layer' ? semanticMetricMatch ?? undefined : undefined,
     };
 }
 const SYSTEM_PROMPT = `You are the DQL Analytics Agent.
@@ -590,6 +805,17 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
             .map((m) => `- ${m.scope}${m.scopeId ? `:${m.scopeId}` : ''} \`${m.title}\` (${m.source}, confidence ${m.confidence}): ${m.content}`)
             .join('\n')}`
         : '';
+    // Approved, scope-matched correction hints from the Hint Graph. These are
+    // human-reviewed lessons (often from a prior wrong→right SQL correction), so
+    // they carry more weight than advisory memory when generating SQL — but they
+    // still must NOT override a certified artifact that already answers exactly.
+    const appliedHints = contextPack?.appliedHints ?? [];
+    const hintsSection = appliedHints.length > 0
+        ? `\n\n## Applied governed hints (human-approved corrections)\n\nReviewed, scope-matched corrections from your team. Apply them when generating SQL to avoid known mistakes; they refine generated SQL but MUST NOT override a certified artifact that already answers the question.\n${appliedHints
+            .slice(0, 6)
+            .map((h) => `- \`${h.title}\`: ${h.guidance}${h.correctedSql ? `\n  corrected SQL pattern: ${h.correctedSql.replace(/\s+/g, ' ').trim().slice(0, 240)}` : ''}`)
+            .join('\n')}`
+        : '';
     const extraSection = extraContext?.trim()
         ? `\n\n## Current notebook/app context\n\nThis context may help interpret the user's request, but it MUST NOT override certified artifacts, semantic metrics, dbt metadata, or generated SQL validation.\n\n${extraContext.trim()}`
         : '';
@@ -599,7 +825,7 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
     const contextPackSection = contextPack
         ? `\n\n## Local metadata context pack\n\n${renderContextPackForPrompt(contextPack)}`
         : '';
-    return `${intentSection}\n\n${blockSection}${businessSection}${otherSection}${schemaSection}${contextPackSection}${memorySection}${extraSection}${followUpSection}`;
+    return `${intentSection}\n\n${blockSection}${businessSection}${otherSection}${schemaSection}${contextPackSection}${memorySection}${hintsSection}${extraSection}${followUpSection}`;
 }
 function renderContextPackForPrompt(contextPack) {
     const questionPlan = contextPack.questionPlan
@@ -718,14 +944,19 @@ function renderSourceBlockSqlContext(contextPack) {
                 .join(', ')
             : '';
         const snippet = compactSqlSnippet(source.sql, 280);
+        // Pair each certified block's SQL with the natural-language question it
+        // answers so it reads as a question→SQL few-shot exemplar (DAIL-SQL).
+        const anchorRaw = source.exampleQuestion ?? source.description;
+        const anchor = anchorRaw ? anchorRaw.replace(/\s+/g, ' ').trim().slice(0, 160) : '';
         return [
-            `- ${source.name}${source.status ? ` (${source.status})` : ''}`,
+            `- ${source.name}${source.status ? ` (${source.status})` : ''}${source.grain ? ` — grain: ${source.grain}` : ''}`,
+            anchor ? `  answers: ${anchor}` : '',
             shape?.relation ? `  relation: ${shape.relation}` : '',
             projectedColumns ? `  projected columns: ${projectedColumns}` : '',
             snippet ? `  sql: ${snippet}` : '',
         ].filter(Boolean).join('\n');
     });
-    return `Certified source SQL shape context:\n${lines.join('\n')}`;
+    return `## Worked examples from certified blocks (few-shot patterns)\n\nThese certified blocks already answer similar questions. Learn their join paths, grain, and filters and ADAPT them to the question — do not copy blindly, and do not relabel generated SQL as certified.\n${lines.join('\n')}`;
 }
 function contextPackCitations(contextPack, limit) {
     if (!contextPack)
@@ -2789,9 +3020,30 @@ function composeCertifiedAnswer(artifact, question, result, executionError) {
             : artifact.kind === 'block'
                 ? 'Governed execution was not requested by this host.'
                 : `Matched certified ${artifact.kind.replace('_', ' ')} context.`;
+    // Freshness-aware trust: the block's logic is certified, but its upstream
+    // data may be stale or its last dbt run may have failed. Caveat the answer so
+    // a consumer can weigh it — "certified" is not the same as "fresh".
+    const freshnessCaveat = certifiedFreshnessCaveat(artifact);
     return `Outcome: Reuse certified block\n\nAnswered by certified ${artifact.kind.replace('_', ' ')} **${artifact.name}**${tag}.\n\n${desc ? `${desc}\n\n${resultText}` : resultText}`
+        + (freshnessCaveat ? `\n\n${freshnessCaveat}` : '')
         + `\n\n_Question:_ ${question}`;
 }
+/**
+ * Build a one-line data-freshness caveat for a certified answer, or `undefined`
+ * when the upstream data is fresh / un-instrumented. Stale and failed upstreams
+ * are surfaced so a certified-but-stale answer is never presented as if its data
+ * were current.
+ */
+function certifiedFreshnessCaveat(artifact) {
+    switch (artifact.dataState) {
+        case 'failed':
+            return `⚠️ Data caveat: an upstream dbt model's last run failed, so this certified result may be missing or out of date.${artifact.dataStateDetail ? ` ${artifact.dataStateDetail}` : ''}`;
+        case 'stale':
+            return `⚠️ Data caveat: upstream data is past its freshness window, so this certified result may be stale.${artifact.dataStateDetail ? ` ${artifact.dataStateDetail}` : ''}`;
+        default:
+            return undefined;
+    }
+}
 function mergeHits(...groups) {
     const byId = new Map();
     for (const group of groups) {
@@ -2813,6 +3065,29 @@ function mergeNodes(...groups) {
     }
     return Array.from(byId.values());
 }
+/**
+ * Candidate metric KG nodes for semantic-metric matching (spec 17, part C).
+ * Starts with the FTS semantic + considered hits, then folds in EVERY metric
+ * node from the KG so a confident measure-family match is found even when FTS
+ * surfaced no metric at all (the "total revenue" miss). Bounded for safety.
+ */
+function collectMetricCandidates(semanticHits, considered, kg) {
+    const byId = new Map();
+    for (const hit of [...semanticHits, ...considered]) {
+        if (hit.node.kind === 'metric')
+            byId.set(hit.node.nodeId, hit.node);
+    }
+    try {
+        for (const node of kg.getNodesByKind('metric', 200)) {
+            if (!byId.has(node.nodeId))
+                byId.set(node.nodeId, node);
+        }
+    }
+    catch {
+        // Best-effort: a KG without a getNodesByKind still matches the FTS hits.
+    }
+    return Array.from(byId.values());
+}
 function buildCertifiedEvidence(input) {
     const businessContextAssets = uniqueAssets(input.businessHits
         .map((hit) => hit.node)