@duckcodeailabs/dql-agent 1.6.32 → 1.6.34

package/dist/answer-loop.js

@@ -14,22 +14,28 @@
  * step. Tests can mock the provider with a canned response and exercise the
  * full pipeline.
  */
-import { buildSkillBlockHints, buildSkillsPrompt, selectRelevantSkills } from './skills/loader.js';
+import { describeDialectForPrompt, } from '@duckcodeailabs/dql-core';
+import { buildSkillBlockHints, buildSkillMetricHints, buildSkillsPrompt, expandQuestionWithSkillVocabulary, selectRelevantSkills } from './skills/loader.js';
 import { deriveGeneratedDraftSlug, renderGeneratedSqlDqlArtifact } from './metadata/drafts.js';
 import { buildAnalysisQuestionPlan } from './metadata/analysis-planner.js';
 import { certifiedFitAllowsTier1, evaluateCertifiedBlockFit } from './metadata/block-fit.js';
-import { buildGovernedMetricFirstSql, matchSemanticMetric, resolveGovernedMetricSql } from './metadata/metric-match.js';
+import { buildGovernedMetricFirstSql, matchSemanticMetric, resolveGovernedMetricDefinition, resolveGovernedMetricSql } from './metadata/metric-match.js';
 import { decideAgentAction } from './intent-controller.js';
 import { createContextLedger } from './grounding/context-ledger.js';
 import { validateAnswerResultShape } from './answer-shape.js';
+import { fanoutWarningsForSql } from './metadata/grain-ledger.js';
+import { planCertifiedAdaptation } from './metadata/block-adapt.js';
 import { compactSqlSnippet, extractSimpleSelectShape, selectExpressionOutputName, } from './metadata/sql-shape.js';
 import { composeSemanticQueryForQuestion, composeSemanticQueryFromMembers } from './semantic-bridge/compose.js';
+import { runAgenticToolLoop } from './agentic/tool-loop.js';
+import { buildSemanticStageTools } from './agentic/toolset.js';
+import { deriveAgenticTrust } from './agentic/answer-contract.js';
 import { selectSemanticMembersViaLlm } from './semantic-bridge/member-select.js';
 import { normalizeValueIndexText } from './grounding/value-index.js';
 import { cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, } from './cascade/cascade.js';
 import { shouldClarifyBeforeGeneration } from './cascade/triage.js';
 import { stampTrustLabel } from './trust/stamp.js';
-import { QUICK_PROMPT_CONTEXT_BUDGET, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, promptContextBudgetForQuestion, proposalToolBudgetForQuestion, recordLaneRepair, } from './cascade/budgets.js';
+import { QUICK_PROMPT_CONTEXT_BUDGET, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, deepAlternativeCountForQuestion, promptContextBudgetForQuestion, proposalToolBudgetForQuestion, recordLaneRepair, } from './cascade/budgets.js';
 /**
  * Physical column names whose sampled runtime values include `value`. Used by the
  * semantic bridge to bind a filter literal to the dimension that actually carries
@@ -157,10 +163,12 @@ export async function answer(input) {
         },
         isFollowUp: Boolean(input.followUp),
     });
+    const trustLabelInfo = stampTrustLabel(result);
     return {
         ...publicResult,
         intentDecision,
-        trustLabelInfo: stampTrustLabel(result),
+        trustLabelInfo,
+        provenanceFooter: buildProvenanceFooter(result, trustLabelInfo),
         cascade: publicResult.cascade ?? createCascadeAnswerResult({
             routeTier: chosenRoute.tier,
             label: chosenRoute.label,
@@ -178,7 +186,13 @@ export async function answer(input) {
         // 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) => ({
+            selectRelevantSkills(input.skills ?? [], input.question, {
+                userId: input.userId ?? null,
+                domains: Array.from(new Set([
+                    ...(input.domain ? [input.domain] : []),
+                    ...(input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : []),
+                ])),
+            }).map((s) => ({
                 id: s.id,
                 description: s.description,
             })),
@@ -240,11 +254,22 @@ async function runAnswerLoop(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 inferredDomains = Array.from(new Set([
+        ...(domain ? [domain] : []),
+        ...(input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : []),
+    ]));
+    const selectedSkills = selectRelevantSkills(skills, question, {
+        userId: userId ?? null,
+        domains: inferredDomains,
+    });
     const effectiveBlockHints = Array.from(new Set([
         ...blockHints,
-        ...buildSkillBlockHints(skills, userId ?? null),
+        // Only selected skills may influence block ranking. Previously a preferred
+        // block from any active but unrelated domain skill could jump to the front.
+        ...buildSkillBlockHints(selectedSkills, userId ?? null),
     ]));
+    const effectiveMetricHints = buildSkillMetricHints(selectedSkills, userId ?? null);
+    const semanticQuestion = expandQuestionWithSkillVocabulary(question, selectedSkills, userId ?? null);
     const followUpSourceBlock = input.followUp?.sourceBlockName
         ? kg.getNode(`block:${input.followUp.sourceBlockName}`)
         : null;
@@ -272,6 +297,19 @@ async function runAnswerLoop(input) {
         schemaContext,
     });
     let intent = catalogRoute ? agentIntentFromCatalogRoute(catalogRoute) : fallbackIntent;
+    // Resolve a governed metric before accepting a catalog-proposed certified
+    // block. Catalog token overlap can call a generic word such as "total" an
+    // exact block match (for example total tax → total revenue); the metric match
+    // is the precise measure signal that prevents that wrong Tier-1 shortcut.
+    const semanticMetricNodes = collectMetricCandidates(semanticHits, considered, kg);
+    for (const metric of effectiveMetricHints) {
+        const node = kg.getNode(`metric:${metric}`);
+        if (node && !semanticMetricNodes.some((candidate) => candidate.nodeId === node.nodeId))
+            semanticMetricNodes.push(node);
+    }
+    let semanticMetricMatch = await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
+        measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
+    }).catch(() => null);
     // Stage 1: certified artifact match. Blocks can be executed; dashboards,
     // Apps, and notebooks are returned as governed citations/navigation targets.
     const drilldownCertifiedHit = input.followUp?.kind === 'drilldown'
@@ -284,19 +322,29 @@ async function runAnswerLoop(input) {
             kg,
         })
         : null;
-    const artifactHit = drilldownCertifiedHit ?? (shouldUseCertifiedRoute(catalogRoute, intent)
+    const shouldTryCertifiedRoute = shouldUseCertifiedRoute(catalogRoute, intent);
+    const catalogCertifiedHit = shouldTryCertifiedRoute
         ? certifiedHitFromContextPack(input.contextPack, kg)
-            ?? pickCertifiedArtifact({
-                artifactHits,
-                executableArtifactHits,
-                businessHits,
-                question,
-                questionPlan,
-                blockHints: input.followUp?.kind === 'drilldown' ? [] : effectiveBlockHints,
-                excludedArtifactIds,
-                kg,
-            })
-        : null);
+        : null;
+    const unsafeCatalogCertifiedHit = catalogCertifiedHit?.node.kind === 'block' && semanticMetricMatch
+        && !hasCertifiedNodeFit(question, questionPlan, catalogCertifiedHit.node)
+        ? null
+        : catalogCertifiedHit;
+    const fallbackCertifiedHit = shouldTryCertifiedRoute ? pickCertifiedArtifact({
+        artifactHits,
+        executableArtifactHits,
+        businessHits,
+        question,
+        questionPlan,
+        blockHints: input.followUp?.kind === 'drilldown' ? [] : effectiveBlockHints,
+        excludedArtifactIds,
+        kg,
+    }) : null;
+    let artifactHit = drilldownCertifiedHit ?? unsafeCatalogCertifiedHit
+        ?? (catalogCertifiedHit ? null : fallbackCertifiedHit);
+    // Certified remains first when it actually covers the question. If the
+    // retrieved block does not fit but a governed semantic metric does, never
+    // let the broad catalog match pre-empt Lane 2.
     // A certified TERM / BUSINESS VIEW is documentation, not data: it can be the
     // terminal answer only for a definition-style question with no data ask. A
     // question that requests a data shape (dimensions/measures/outputs/top-N) or
@@ -429,8 +477,6 @@ async function runAnswerLoop(input) {
     // 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);
     const clarifyBeforeGeneration = shouldClarifyBeforeGeneration({
         intent,
         routeDecision: catalogRoute,
@@ -506,9 +552,27 @@ async function runAnswerLoop(input) {
     const matchedMetricHit = semanticMetricMatch
         ? [{ node: semanticMetricMatch.metric, score: Math.max(semanticMetricMatch.score, CERTIFIED_HIT_THRESHOLD) }]
         : [];
+    // Reserve prompt slots per source instead of appending semantic hits LAST and
+    // truncating the whole list to 14 — the old behavior dropped semantic-model hits
+    // out of the generation prompt entirely whenever artifact/business hits filled
+    // the budget first, so even a question a semantic metric could answer never saw
+    // the metric. Each group gets a guaranteed minimum; leftover budget is filled
+    // round-robin. See interleaveContextHits.
     const contextHits = activeTier === 'semantic_layer'
-        ? [...matchedMetricHit, ...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...semanticHits, ...manifestHits].slice(0, 14)
-        : [...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...manifestHits].slice(0, 14);
+        ? interleaveContextHits([
+            { hits: matchedMetricHit, reserve: matchedMetricHit.length },
+            { hits: semanticHits, reserve: 5 },
+            { hits: trustedArtifactContext, reserve: 3 },
+            { hits: reviewRequiredArtifactHits, reserve: 2 },
+            { hits: businessHits.slice(0, 4), reserve: 2 },
+            { hits: manifestHits, reserve: 2 },
+        ], 14)
+        : interleaveContextHits([
+            { hits: trustedArtifactContext, reserve: 5 },
+            { hits: reviewRequiredArtifactHits, reserve: 3 },
+            { hits: businessHits.slice(0, 4), reserve: 3 },
+            { hits: manifestHits, reserve: 3 },
+        ], 14);
     const contextNodes = mergeNodes(followUpSourceBlock && input.followUp?.kind === 'drilldown' ? [followUpSourceBlock] : [], (contextHits.length > 0 ? contextHits : considered.slice(0, 6)).map((h) => h.node));
     const kgJoinPathHints = buildKgJoinPathHints(kg, contextNodes, questionPlan);
     const contextBlocks = contextNodes.filter((n) => n.kind === 'block');
@@ -527,7 +591,7 @@ async function runAnswerLoop(input) {
         messages.push({ role: 'system', content: skillsPrompt });
     messages.push({
         role: 'system',
-        content: renderContextPrompt(contextBlocks, contextBusiness, contextOther, activeTier, input.memoryContext ?? [], input.extraContext, input.followUp, schemaContext, intent, input.contextPack, input.conversationSnapshot, kgJoinPathHints, promptBudget),
+        content: renderContextPrompt(contextBlocks, contextBusiness, contextOther, activeTier, input.memoryContext ?? [], input.extraContext, input.followUp, schemaContext, intent, input.contextPack, input.conversationSnapshot, kgJoinPathHints, promptBudget, input.semanticDriver),
     });
     messages.push({ role: 'user', content: question });
     // ── Tier 2: semantic-layer metrics + dimensions (governed hierarchy) ──────
@@ -611,14 +675,55 @@ async function runAnswerLoop(input) {
         contextPack: input.contextPack,
         schemaContext,
     });
+    // W2.2 — certified-block adaptation lane. When a certified block is context-only
+    // ONLY because the question adds exactly one filter whose value maps to a column
+    // the block already outputs, adapt the certified SQL (wrap + filter its result)
+    // instead of regenerating from scratch. It executes through the governed path
+    // (pre-validated, since the wrapper only restricts an already-certified result)
+    // and is labeled BELOW certified. Falls through to generation on any miss.
+    let certifiedAdaptation;
+    if (!semanticBridgeAnswer && !metricFirst && input.executeGeneratedSql) {
+        const fit = input.contextPack?.routeDecision?.blockFit;
+        const sourceBlock = input.contextPack?.allowedSqlContext?.sourceBlockSql?.[0];
+        if (fit && sourceBlock?.sql) {
+            const shape = extractSimpleSelectShape(sourceBlock.sql);
+            const blockOutputs = shape
+                ? shape.selectExpressions.map((expression) => selectExpressionOutputName(expression)).filter((name) => Boolean(name))
+                : [];
+            certifiedAdaptation = planCertifiedAdaptation({
+                blockFit: fit,
+                certifiedSql: sourceBlock.sql,
+                blockName: sourceBlock.name,
+                blockOutputs,
+                resolveFilterColumn: (value) => resolveFilterValueColumns(value, schemaContext),
+            }) ?? undefined;
+        }
+    }
     let proposed = '';
     let parsed;
     const proposalToolCalls = [...semanticBridgeToolCalls];
+    // Stage-B toolset: the host's warehouse/validation tools PLUS the answer loop's
+    // own governed semantic tools (search_semantic_layer, compile_semantic_query,
+    // scan_manifest), so tool-driven generation can compile governed SQL itself and
+    // grep the live graph — across every provider (native or text-protocol). Every
+    // governed compile is recorded so the answer can be labeled governed, not
+    // hand-written, downstream (deriveAgenticTrust).
+    const compiledSemanticRecords = [];
+    const stageBTools = [
+        ...(input.answerLoopTools ?? []),
+        ...buildSemanticStageTools({
+            semanticLayer: input.semanticLayer,
+            kg,
+            driver: input.semanticDriver,
+            tableMapping: input.semanticTableMapping,
+            onCompiled: (record) => compiledSemanticRecords.push(record),
+        }),
+    ];
     if (semanticBridgeAnswer) {
         governedMetricAnswer = true;
         parsed = {
             sql: semanticBridgeAnswer.sql,
-            text: `Answered from governed semantic metric${semanticBridgeAnswer.metrics.length === 1 ? '' : 's'} ${semanticBridgeAnswer.metrics.join(', ')}${semanticBridgeAnswer.dimensions.length > 0 ? ` by ${semanticBridgeAnswer.dimensions.join(', ')}` : ''}. This result is uncertified until reviewed and promoted.`,
+            text: `Answered from governed semantic metric${semanticBridgeAnswer.metrics.length === 1 ? '' : 's'} ${semanticBridgeAnswer.metrics.join(', ')}${semanticBridgeAnswer.dimensions.length > 0 ? ` by ${semanticBridgeAnswer.dimensions.join(', ')}` : ''}. The semantic compiler owns this query; saving it as a reusable certified block still requires review.`,
             viz: semanticBridgeAnswer.dimensions.length === 0 && !semanticBridgeAnswer.timeDimension ? 'single_value' : undefined,
         };
     }
@@ -627,16 +732,39 @@ async function runAnswerLoop(input) {
         governedMetricAnswer = true;
         parsed = {
             sql: metricFirst.sql,
-            text: `Answered from the governed metric ${metricFirst.metric.name}${metricFirst.dimensions.length > 0 ? ` by ${metricFirst.dimensions.join(', ')}` : ''}. This result is uncertified until reviewed and promoted.`,
+            text: `Answered from the governed metric ${metricFirst.metric.name}${metricFirst.dimensions.length > 0 ? ` by ${metricFirst.dimensions.join(', ')}` : ''}. The semantic definition owns the calculation; reusable block certification remains a separate review.`,
             viz: metricFirst.dimensions.length === 0 ? 'single_value' : undefined,
         };
     }
+    else if (certifiedAdaptation) {
+        // Pre-validated governed path (the wrapper only restricts a certified result).
+        governedMetricAnswer = true;
+        parsed = {
+            sql: certifiedAdaptation.sql,
+            text: certifiedAdaptation.provenance,
+        };
+    }
     else {
+        // Tier 2.5 — METRIC-ANCHORED generation. A governed metric matched this question,
+        // but its semantic definition couldn't compose the exact requested shape (typically
+        // the breakdown needs a join the semantic layer doesn't own — e.g. a location-grain
+        // tax metric asked for "by product"). Rather than throw the metric away and let the
+        // model reinvent the aggregation from scratch, inject the metric's CERTIFIED
+        // definition as a required building block, so the generated SQL reuses the trusted
+        // measure and only generates the join/grouping around it. Keeps the number
+        // consistent with the governed metric. Degrades to plain generation when the metric
+        // has no resolvable definition. The grain ledger + validation still gate the output.
+        const metricAnchor = semanticMetricMatch && input.semanticLayer
+            ? resolveGovernedMetricDefinition(semanticMetricMatch.metric, semanticMetricNodes, input.semanticLayer)
+            : undefined;
+        const generationMessages = metricAnchor
+            ? [...messages, { role: 'system', content: metricAnchorInstruction(metricAnchor.metric.name, metricAnchor.def) }]
+            : messages;
         try {
             proposed = await generateProposalWithOptionalTools({
                 provider,
-                messages,
-                tools: input.answerLoopTools,
+                messages: generationMessages,
+                tools: stageBTools,
                 questionPlan,
                 intent,
                 signal: input.signal,
@@ -676,6 +804,35 @@ async function runAnswerLoop(input) {
             };
         }
         parsed = parseProposal(proposed);
+        // Surface the tier choice (WS3): when generation was anchored on a governed
+        // metric, say so, so the answer reads as "reused the certified measure" rather
+        // than an opaque hand-written query.
+        if (metricAnchor && parsed.sql) {
+            const anchorNote = `Computed using the governed metric ${metricAnchor.metric.name}'s certified definition, joined to add the requested breakdown. Review-required (not itself certified).`;
+            parsed = { ...parsed, text: parsed.text ? `${parsed.text}\n\n${anchorNote}` : anchorNote };
+        }
+        // Stage-B governed promotion: when the model drove compile_semantic_query and
+        // adopted its output VERBATIM (deriveAgenticTrust — exact match only), the SQL
+        // is governed semantic SQL the compiler owns and already validated, not
+        // hand-written. Treat it like the deterministic governed path: skip the
+        // hallucination guard (governedMetricAnswer) and note the provenance. Any edit
+        // to the compiled SQL falls back to generated/review-required by construction.
+        if (!governedMetricAnswer && parsed.sql) {
+            const trust = deriveAgenticTrust(parsed.sql, compiledSemanticRecords);
+            if (trust.tier === 'semantic_metric' && trust.compiled) {
+                governedMetricAnswer = true;
+                const compiled = trust.compiled;
+                const governedNote = `Answered from governed semantic metric${compiled.metrics.length === 1 ? '' : 's'} ${compiled.metrics.join(', ')}${compiled.dimensions.length > 0 ? ` by ${compiled.dimensions.join(', ')}` : ''} (compiled via the semantic layer). Reusable block certification remains a separate review.`;
+                parsed = { ...parsed, text: parsed.text ? `${parsed.text}\n\n${governedNote}` : governedNote };
+                proposalToolCalls.push({
+                    name: 'compile_semantic_query',
+                    status: 'checked',
+                    inputSummary: `metrics: ${compiled.metrics.join(', ')}${compiled.dimensions.length ? `; by ${compiled.dimensions.join(', ')}` : ''}`,
+                    outputSummary: 'Model-selected semantic members compiled to governed SQL',
+                    order: proposalToolCalls.length + 1,
+                });
+            }
+        }
     }
     let deepCandidateResult;
     let deepCandidateExecutionError;
@@ -692,6 +849,7 @@ async function runAnswerLoop(input) {
             executeGeneratedSql: input.executeGeneratedSql,
             signal: input.signal,
             reasoningEffort: input.reasoningEffort,
+            maxAlternatives: deepAlternativeCountForQuestion(questionPlan, intent),
         });
         if (selection.selected) {
             proposed = selection.selected.raw;
@@ -725,7 +883,7 @@ async function runAnswerLoop(input) {
             parsed = {
                 sql: resolved.sql,
                 text: parsed.text ||
-                    `Answered from the governed metric ${resolved.metric.name}. This result is uncertified until reviewed and promoted.`,
+                    `Answered from the governed metric ${resolved.metric.name}. The semantic definition owns the calculation; reusable block certification remains a separate review.`,
                 viz: parsed.viz ?? 'single_value',
             };
         }
@@ -751,7 +909,7 @@ async function runAnswerLoop(input) {
             proposed = await generateProposalWithOptionalTools({
                 provider,
                 messages: [...messages, { role: 'system', content: FORCE_JOIN_INSTRUCTION }],
-                tools: input.answerLoopTools,
+                tools: stageBTools,
                 questionPlan,
                 intent,
                 signal: input.signal,
@@ -959,6 +1117,21 @@ async function runAnswerLoop(input) {
             // Repair is best-effort — the refusal below stays the honest fallback.
         }
     }
+    // W1.3 — deterministic, warn-only fan-out check. When the generated SQL aggregates
+    // an additive measure across a one-to-many join (grain ledger knows the keys), the
+    // number can silently double-count. Surface a caution so it is reviewed. This never
+    // blocks: it only appends to warnings, and it is conservative (no key data ⇒ no flag).
+    if (contextValidation.ok && parsed.sql && input.contextPack?.objects?.length) {
+        try {
+            const fanoutWarnings = fanoutWarningsForSql(parsed.sql, input.contextPack.objects);
+            if (fanoutWarnings.length > 0) {
+                contextValidation = { ok: true, warnings: [...contextValidation.warnings, ...fanoutWarnings] };
+            }
+        }
+        catch {
+            // Fan-out detection is advisory; any failure must not affect the answer.
+        }
+    }
     if (!contextValidation.ok) {
         const text = `I could not safely prepare this review-required DQL artifact from the inspected context. The SQL preview failed validation: ${contextValidation.error}`;
         const analysisPlan = buildAnalysisPlan({
@@ -1239,26 +1412,32 @@ async function runAnswerLoop(input) {
         ? { ...dqlArtifact, sourcePath: dqlArtifact.sourcePath ?? draftBlock.path }
         : dqlArtifact;
     const sourceCertifiedBlock = followUpSourceBlock?.name ?? input.followUp?.sourceBlockName;
-    const trustExplanation = generatedTrustExplanation({
-        followUp: input.followUp,
-        sourceCertifiedBlock,
-        draftBlock,
-    });
+    const trustExplanation = governedMetricAnswer
+        ? undefined
+        : generatedTrustExplanation({
+            followUp: input.followUp,
+            sourceCertifiedBlock,
+            draftBlock,
+        });
     const cleanedSummary = cleanGeneratedSummary(parsed.text);
     const generatedText = [partialShapeWarning, trustExplanation, cleanedSummary]
         .filter(Boolean)
         .join('\n\n');
-    const semanticMetricCertification = governedMetricAnswer && activeTier === 'semantic_layer'
+    // A metric can be resolved directly from the loaded semantic layer even if
+    // the small metadata pack happened to contain only dbt objects.  The answer
+    // is still compiler-owned semantic SQL in that case; do not accidentally
+    // downgrade its route/trust to generated SQL because of retrieval order.
+    const semanticMetricCertification = governedMetricAnswer
         ? semanticMetricMatch?.metric.certification
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     return {
         kind: 'uncertified',
-        sourceTier: activeTier,
-        certification: 'ai_generated',
-        reviewStatus: 'draft_ready',
+        sourceTier: governedMetricAnswer ? 'semantic_layer' : activeTier,
+        certification: governedMetricAnswer ? 'governed' : 'ai_generated',
+        reviewStatus: governedMetricAnswer ? 'governed' : 'draft_ready',
         semanticMetricCertification,
-        confidence: certifiedMetricAnswer ? 0.8 : governedMetricAnswer && activeTier === 'semantic_layer' ? 0.72 : 0.55,
+        confidence: certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
         text: generatedText,
         answer: generatedText,
         proposedSql: parsed.sql,
@@ -1308,7 +1487,7 @@ async function runAnswerLoop(input) {
         providerUsed: provider.name,
         // Carry the governed metric match so the exit point can name a
         // `semantic_metric` route (spec 17, part C).
-        _semanticMetricMatch: governedMetricAnswer && activeTier === 'semantic_layer' ? semanticMetricMatch ?? undefined : undefined,
+        _semanticMetricMatch: governedMetricAnswer ? semanticMetricMatch ?? undefined : undefined,
     };
 }
 function trimResultToRequestedTopN(result, plan) {
@@ -1353,13 +1532,21 @@ Rules:
    separate SQL code fence when using JSON. The optional "dql" object is
    metadata for the deterministic draft-DQL renderer; do not hand-write a full
    DQL block.
+   Design the SELECT for a business reader: prefer a joined/display name, label,
+   title, or business value over raw *_id, *_uuid, *_key, or technical codes.
+   Alias calculated outputs with clear business names. Include identifiers only
+   when the question asks for them or no readable field exists.
 4. In summary, state your QUERY PLAN first: the grain (one row per WHAT), the
    measures and how they aggregate, the dimensions/filters, and the exact join
    path + join keys between the grounded tables. Then make the SQL match that
    plan — an explicit grain and join path prevents wrong-grain answers and
    fan-out (row-multiplying) joins.
-5. Use a visualization type from this list in the "viz" JSON field: line, bar,
-   area, pie, single_value, table, pivot, kpi.
+5. Choose a visualization deliberately in the "viz" JSON field: use single_value
+   or kpi for one aggregate, line/area only for an ordered time series, bar for a
+   categorical comparison, grouped-bar for multiple measures by one category,
+   scatter for two continuous measures, and table when the result is not chartable.
+   Do not default to bar. The runtime validates this preference against returned
+   rows before displaying it.
 6. NEVER fabricate column names that are not present in the supplied schema,
    dbt metadata, or certified source SQL shape context. If a requested filter
    value is supplied as a matched value, prefer the table and column that
@@ -1368,15 +1555,19 @@ Rules:
    Do NOT use dbt/Jinja macros such as {{ ref(...) }} or {{ source(...) }} in
    proposed SQL. Do not emit INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, COPY,
    PRAGMA, SET, or multiple statements.
-8. If the schema is insufficient to answer, say so explicitly and ask a
-   clarifying question instead of guessing. But a MULTI-ENTITY question ("top
-   customers who bought the top products", "accounts with the most overdue
-   invoices") is NOT insufficient context when the grounded tables and a join
-   route between them are supplied (see any "Knowledge graph join routes"
-   section). In that case you MUST compose the joined SELECT that answers it
-   directly — never refuse it or offer to show the parts as separate datasets.
-   Reserve the clarifying question for a genuinely absent table, column, or join
-   key.
+8. If the schema is insufficient, DISCOVER before you decline: use
+   search_metadata to find candidate relations, get_table_schema to confirm a
+   relation's real columns and inferred join keys, and expand_context for a
+   relation you already know by name. Only ask a clarifying question once those
+   come up empty AND the question is genuinely ambiguous — never decline just
+   because the initially supplied context pack didn't already include the table.
+   A MULTI-ENTITY question ("top customers who bought the top products", "accounts
+   with the most overdue invoices") is NOT insufficient context when the grounded
+   tables and a join route between them are supplied (see any "Knowledge graph
+   join routes" section) or discoverable via the tools above. In that case you
+   MUST compose the joined SELECT that answers it directly — never refuse it or
+   offer to show the parts as separate datasets. Reserve the clarifying question
+   for a genuinely absent table, column, or join key.
 9. Write directly to the analyst. Do not say "the user is asking", "the user
    requested", "I will generate", or describe internal routing. State the
    answer, the certified context used, the DQL artifact expectation, and the
@@ -1390,7 +1581,20 @@ Rules:
 // combined dataset — show them separately" refusal into the join the user asked
 // for, while still allowing an honest refusal if context is truly missing.
 const FORCE_JOIN_INSTRUCTION = `Your previous attempt declined to produce SQL. Re-read the supplied schema, metadata, and any "Knowledge graph join routes": this question CAN be answered by joining the grounded tables along their documented keys. Do NOT refuse, and do NOT suggest showing the datasets separately — compose ONE read-only SELECT/WITH that joins the relevant tables to answer it directly, following the JSON contract from rule 3. State the grain and the exact join path in the summary. Only if a required table, column, or join key is truly absent from the supplied context may you still ask a clarifying question.`;
-function renderContextPrompt(blocks, businessContext, others, activeTier, memoryContext, extraContext, followUp, schemaContext = [], intent = 'ad_hoc_analysis', contextPack, conversationSnapshot, kgJoinPathHints = [], budget = QUICK_PROMPT_CONTEXT_BUDGET) {
+// Metric-anchored generation (Tier 2.5): a governed metric matched the question but
+// the semantic layer couldn't compose the exact shape. Reuse the metric's CERTIFIED
+// definition as the measure rather than reinventing it, so the number stays consistent
+// with the governed metric — only the join/grouping around it is generated.
+function metricAnchorInstruction(metricName, def) {
+    return `A GOVERNED metric matched this question, but the semantic layer could not compose the exact requested shape on its own (the breakdown likely needs a join the metric's table does not own). You MUST compute the measure using this certified definition — do NOT redefine, rename, or approximate it:\n  metric "${metricName}": ${def.expr}   (defined over ${def.table})\nCompose ONE read-only SELECT/WITH that computes exactly this expression as the measure, joining ${def.table} to the other grounded tables along their documented keys to add the requested dimensions, then GROUP BY those dimensions. State the join path and grain in the summary. Reusing the governed definition keeps the answer consistent with the certified metric; only fall back to redefining the measure if ${def.table} genuinely cannot be joined to the requested breakdown.`;
+}
+function renderContextPrompt(blocks, businessContext, others, activeTier, memoryContext, extraContext, followUp, schemaContext = [], intent = 'ad_hoc_analysis', contextPack, conversationSnapshot, kgJoinPathHints = [], budget = QUICK_PROMPT_CONTEXT_BUDGET, driver) {
+    // W1.5 — dialect conventions so the model writes warehouse-correct SQL
+    // (quoting, row-limiting, date functions) instead of a DuckDB/Postgres default
+    // that fails on Snowflake/BigQuery/etc. Only emitted when a driver is known.
+    const dialectSection = driver
+        ? `\n\n## SQL dialect\n\n${describeDialectForPrompt(driver)}`
+        : '';
     const intentSection = `## Routing intent\n\nintent: ${intent}\n${intent === 'exact_certified_lookup'
         ? 'Use a certified artifact only if it exactly answers the question.'
         : 'Prepare a review-required DQL artifact with a SQL preview for this question. Certified blocks are trusted context, not a reason to answer the wrong grain.'}`;
@@ -1459,7 +1663,7 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
     const contextPackSection = contextPack
         ? `\n\n## Local metadata context pack\n\n${renderContextPackForPrompt(contextPack, budget)}`
         : '';
-    return `${intentSection}${budgetSection}\n\n${blockSection}${businessSection}${otherSection}${kgJoinSection}${schemaSection}${contextPackSection}${memorySection}${hintsSection}${conversationSection}${extraSection}${followUpSection}`;
+    return `${intentSection}${budgetSection}${dialectSection}\n\n${blockSection}${businessSection}${otherSection}${kgJoinSection}${schemaSection}${contextPackSection}${memorySection}${hintsSection}${conversationSection}${extraSection}${followUpSection}`;
 }
 function buildKgJoinPathHints(kg, nodes, questionPlan) {
     const candidates = nodes
@@ -2968,25 +3172,29 @@ async function generateProposalWithOptionalTools(input) {
         signal: input.signal,
         reasoningEffort: input.reasoningEffort,
     };
-    if (!input.provider.generateWithTools || tools.length === 0) {
+    // No tools → plain generation (nothing for the loop to drive).
+    if (tools.length === 0) {
         return input.provider.generate(input.messages, options);
     }
     const toolBudget = proposalToolBudgetForQuestion(input.questionPlan, input.intent, {
         analysisDepth: input.analysisDepth,
         reasoningEffort: input.reasoningEffort,
     });
-    const toolPolicy = {
-        role: 'system',
-        content: [
-            'You may use the supplied DQL tools to inspect semantic members, certified context, metadata context, and bounded repair options.',
-            `Tool budget for this question: ${toolBudget.maxToolCalls} call(s) (${toolBudget.effortClass}: ${toolBudget.reason}). Stop as soon as a lane can answer.`,
-            'Prefer semantic compile before deep warehouse search when the semantic layer contains the requested metric/dimensions/time grain.',
-            'Use context expansion only to repair a named, known relation/column gap; do not loop on the same failed context.',
-            'Final response must be a single ```json fenced object with summary, sql, viz, outputs, and optional dql metadata fields.',
-        ].join('\n'),
-    };
-    return input.provider.generateWithTools([...input.messages, toolPolicy], tools, {
+    const toolPolicy = [
+        'You may use the supplied DQL tools to inspect semantic members, certified context, metadata context, and bounded repair options.',
+        `Tool budget for this question: ${toolBudget.maxToolCalls} call(s) (${toolBudget.effortClass}: ${toolBudget.reason}). Stop as soon as a lane can answer.`,
+        'Prefer a governed semantic compile (search_semantic_layer → compile_semantic_query) over hand-written SQL when the semantic layer contains the requested metric/dimensions/time grain.',
+        'When the supplied context is missing a table, column, or join key, DISCOVER it with `search_metadata` (find candidate relations) then `get_table_schema` (confirm real columns + inferred join keys) before declining. Use `search_project_files` for a bounded live source grep when indexed retrieval missed an identifier; use `scan_manifest` for cached graph objects; do not loop on the same failed context.',
+        'When unsure a relation/column exists, validate a composed query with `validate_sql` rather than guessing.',
+        'Final response must be a single ```json fenced object with summary, sql, viz, outputs, and optional dql metadata fields.',
+    ].join('\n');
+    // runAgenticToolLoop drives the loop over ANY provider: native tool use where the
+    // provider implements generateWithTools (Claude/OpenAI), and an equivalent text
+    // protocol otherwise (subscription-CLI passthrough, Ollama). This is what gives
+    // every provider — not just the two API ones — a real tool-driven Stage B.
+    return runAgenticToolLoop(input.provider, [...input.messages], tools, {
         ...options,
+        toolPolicy,
         maxToolCalls: toolBudget.maxToolCalls,
         onToolCall: (event) => {
             const sink = input.toolCalls;
@@ -3130,8 +3338,14 @@ async function generateDeepAlternativeProposals(input) {
         'Create a fourth candidate by DECOMPOSITION: break the question into sub-questions, solve each as a CTE, then compose the final SELECT — avoiding assumptions hidden in the first candidate.',
     ];
     const temperatures = [0.2, 0.35, 0.5];
-    const out = [];
-    for (const [index, instruction] of variants.entries()) {
+    // How many diverse alternatives to generate is set by the question SHAPE (S1):
+    // a lightweight 1-candidate agreement check for join/breakdown shapes, the full
+    // 3-candidate vote for deep-research, none for a single-table lookup. The
+    // generations are independent, so they run in PARALLEL — the deep vote's
+    // wall-clock cost is one generation, not the serial sum of all of them.
+    const count = Math.max(0, Math.min(input.maxAlternatives ?? variants.length, variants.length));
+    const selected = variants.slice(0, count);
+    const results = await Promise.all(selected.map(async (instruction, index) => {
         try {
             const raw = await input.provider.generate([
                 ...input.messages,
@@ -3151,14 +3365,14 @@ async function generateDeepAlternativeProposals(input) {
                 reasoningEffort: input.reasoningEffort,
                 temperature: temperatures[index] ?? 0.4,
             });
-            if (raw.trim())
-                out.push(raw);
+            return raw.trim() ? raw : '';
         }
         catch {
             // Alternative candidates are opportunistic; the initial candidate remains.
+            return '';
         }
-    }
-    return out;
+    }));
+    return results.filter((raw) => raw.trim());
 }
 function cloneParsedProposal(proposal) {
     return {
@@ -3190,6 +3404,7 @@ function evidenceToolCallFromEvent(event, order) {
         inputSummary: summarizeEvidencePayload(event.input),
         outputSummary: summarizeEvidencePayload(event.output),
         order,
+        ...(typeof event.durationMs === 'number' ? { durationMs: event.durationMs } : {}),
     };
 }
 function summarizeEvidencePayload(value, maxLength = 700) {
@@ -3295,6 +3510,40 @@ function certifiedFreshnessCaveat(artifact) {
             return undefined;
     }
 }
+function provenanceSourceTierLabel(tier) {
+    switch (tier) {
+        case 'certified_artifact': return 'Certified block';
+        case 'semantic_layer': return 'Governed semantic metric';
+        case 'business_context': return 'Business context';
+        case 'dbt_manifest': return 'Generated SQL';
+        default: return undefined;
+    }
+}
+/**
+ * Anthropic-style provenance footer: one line telling a stakeholder WHERE the
+ * answer came from (source tier), how much to trust it, who owns the source, and
+ * whether the underlying data is current. Built once at the single exit from the
+ * finished answer; omitted for no-answer outcomes.
+ */
+export function buildProvenanceFooter(result, trust) {
+    if (result.kind === 'no_answer')
+        return undefined;
+    const parts = [];
+    const tierLabel = provenanceSourceTierLabel(result.sourceTier);
+    if (tierLabel)
+        parts.push(`Source: ${tierLabel}`);
+    if (trust?.display)
+        parts.push(`Trust: ${trust.display}`);
+    if (result.block?.owner)
+        parts.push(`Owner: ${result.block.owner}`);
+    const freshness = result.block?.dataState === 'stale' ? 'stale — verify currency'
+        : result.block?.dataState === 'failed' ? 'upstream run failed'
+            : result.block?.dataState === 'fresh' ? 'current'
+                : undefined;
+    if (freshness)
+        parts.push(`Data: ${freshness}`);
+    return parts.length > 0 ? parts.join(' · ') : undefined;
+}
 function mergeHits(...groups) {
     const byId = new Map();
     for (const group of groups) {
@@ -3316,6 +3565,53 @@ function mergeNodes(...groups) {
     }
     return Array.from(byId.values());
 }
+/**
+ * Merge prioritized hit groups into a single deduped list under a total budget,
+ * giving each group a guaranteed minimum number of slots. Pass 1 takes up to
+ * `reserve` from each group in priority order; pass 2 fills any remaining budget
+ * round-robin from each group's leftovers. This prevents a high-priority group
+ * from starving a lower one out of the prompt entirely (the semantic-hit
+ * truncation bug) while still honoring priority for the reserved slots.
+ */
+function interleaveContextHits(groups, budget) {
+    const seen = new Set();
+    const out = [];
+    const cursors = groups.map(() => 0);
+    const take = (hit) => {
+        if (out.length >= budget || seen.has(hit.node.nodeId))
+            return false;
+        seen.add(hit.node.nodeId);
+        out.push(hit);
+        return true;
+    };
+    // Pass 1: reserved minimums, in priority order.
+    groups.forEach((group, gi) => {
+        let taken = 0;
+        while (cursors[gi] < group.hits.length && taken < group.reserve && out.length < budget) {
+            if (take(group.hits[cursors[gi]]))
+                taken += 1;
+            cursors[gi] += 1;
+        }
+    });
+    // Pass 2: round-robin fill from leftovers until the budget is exhausted.
+    let progressed = true;
+    while (out.length < budget && progressed) {
+        progressed = false;
+        for (let gi = 0; gi < groups.length && out.length < budget; gi += 1) {
+            const group = groups[gi];
+            while (cursors[gi] < group.hits.length) {
+                const before = out.length;
+                take(group.hits[cursors[gi]]);
+                cursors[gi] += 1;
+                if (out.length > before) {
+                    progressed = true;
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
 /**
  * Candidate metric KG nodes for semantic-metric matching (spec 17, part C).
  * Starts with the FTS semantic + considered hits, then folds in EVERY metric