@duckcodeailabs/dql-agent 1.6.33 → 1.7.0

package/dist/answer-loop.js

@@ -14,22 +14,31 @@
  * 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 { domainContextSearchDomains } from './domain-context.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 { evaluateDbtFirstGeneratedSql } from './metadata/dbt-first-safety.js';
+import { planAnalyticalPath } from './metadata/analytical-policy.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
@@ -57,7 +66,7 @@ const EXECUTABLE_ARTIFACT_KINDS = ['block', 'dashboard', 'app', 'notebook'];
 // be cited, but they never produce the row-level answer to an analytical question,
 // so they must not terminate a data ask as a "certified answer" with no data.
 const NAVIGATION_ARTIFACT_KINDS = ['dashboard', 'app', 'notebook'];
-const BUSINESS_CONTEXT_KINDS = ['term', 'business_view'];
+const BUSINESS_CONTEXT_KINDS = ['term', 'business_view', 'domain', 'skill', 'relationship', 'contract', 'domain_export', 'domain_import', 'conformance', 'evaluation'];
 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'];
@@ -69,6 +78,46 @@ function refusalCodeForValidation(code) {
         return 'ambiguous';
     return 'model_declined';
 }
+/**
+ * An analytical-policy result is never a generic grounding gap. A missing
+ * relation/path can enter the bounded exploratory lane; every other result is
+ * an explicit governance boundary that the host must surface without retrying
+ * the same candidate or asking the user a misleading clarification question.
+ */
+function refusalCodeForAnalyticalPolicy(code, hasExploratoryCandidate = false) {
+    if (hasExploratoryCandidate || code === 'unbound_relation' || code === 'unplanned_join' || code === 'relationship_not_certified') {
+        return 'grounding_gap';
+    }
+    return 'policy_blocked';
+}
+/**
+ * The governed guard is intentionally strict. Only the two outcomes that mean
+ * "this repository has not modeled this join yet" may be handed to a host's
+ * exploratory lane. All other decisions are explicit governance/safety
+ * denials and must remain terminal in this loop.
+ */
+function exploratoryCandidateFromDbtFirstGuard(sql, decision) {
+    const reason = decision.code;
+    if (decision.safe || (reason !== 'unbound_relation' && reason !== 'unplanned_join' && reason !== 'relationship_not_certified')) {
+        return undefined;
+    }
+    // `unplanned_join` can also mean the model ignored an existing certified
+    // relationship plan. That is a governed-query error, not missing modeling,
+    // and must remain blocked. It is exploratory only when no plan was resolved.
+    if (decision.code === 'unplanned_join' && decision.relationshipIds.length > 0) {
+        return undefined;
+    }
+    return {
+        kind: 'dbt_grounded_exploration',
+        reason,
+        sql,
+        message: decision.message
+            ?? 'This query is grounded in dbt metadata but has no certified DQL relationship path yet.',
+        modeledEntityIds: decision.entities,
+        relationshipIds: decision.relationshipIds,
+        executionStatus: 'not_executed',
+    };
+}
 function formatOffendingValidationToken(offending) {
     if (!offending?.relation && !offending?.column)
         return '';
@@ -157,10 +206,13 @@ export async function answer(input) {
         },
         isFollowUp: Boolean(input.followUp),
     });
+    const trustLabelInfo = stampTrustLabel(result);
     return {
         ...publicResult,
+        domainContext: input.domainContext,
         intentDecision,
-        trustLabelInfo: stampTrustLabel(result),
+        trustLabelInfo,
+        provenanceFooter: buildProvenanceFooter(result, trustLabelInfo),
         cascade: publicResult.cascade ?? createCascadeAnswerResult({
             routeTier: chosenRoute.tier,
             label: chosenRoute.label,
@@ -178,7 +230,15 @@ 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,
+                modelAreaIds: input.domainContext?.modelAreaId ? [input.domainContext.modelAreaId] : [],
+                domains: Array.from(new Set([
+                    ...domainContextSearchDomains(input.domainContext),
+                    ...(input.domain ? [input.domain] : []),
+                    ...(input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : []),
+                ])),
+            }).map((s) => ({
                 id: s.id,
                 description: s.description,
             })),
@@ -205,6 +265,12 @@ function cascadeExecutionStatus(result) {
  */
 function deriveAiRoute(result, metricMatch) {
     if (result.kind === 'no_answer') {
+        if (result.exploratoryCandidate) {
+            return {
+                tier: 'no_answer',
+                label: 'Governed SQL stopped at missing relationship modeling; a DBT-grounded exploratory candidate is ready for bounded validation.',
+            };
+        }
         return { tier: 'no_answer', label: 'No governed answer — needs more context or review.' };
     }
     if (result.kind === 'certified') {
@@ -237,27 +303,60 @@ function deriveAiRoute(result, metricMatch) {
 }
 async function runAnswerLoop(input) {
     const { question, userId, domain, provider, kg, skills = [], blockHints = [] } = input;
+    // AGT-004: with no explicit domain selection, let direct question evidence
+    // establish a narrow prompt boundary before broad retrieval can introduce an
+    // unrelated domain. This is deliberately a prompt/retrieval preference, not
+    // an authorization decision; the final manifest guard remains authoritative.
+    const directQuestionEntityIds = input.manifest
+        ? inferAnalyticalEntityIds(question, [], input.manifest)
+        : [];
+    const directQuestionDomains = input.manifest?.modeling
+        ? Array.from(new Set(directQuestionEntityIds.map((id) => input.manifest.modeling.entities[id]?.domain).filter((value) => Boolean(value))))
+        : [];
+    const hasExplicitDomainScope = Boolean(input.domain || input.domainContext?.activeDomain);
+    const questionDomainScope = hasExplicitDomainScope ? [] : directQuestionDomains;
+    const promptContextPack = questionDomainScope.length > 0
+        ? scopeContextPackToQuestionDomains(input.contextPack, questionDomainScope, input.manifest)
+        : input.contextPack;
     // 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 authorizedDomains = domainContextSearchDomains(input.domainContext);
+    const inferredDomains = Array.from(new Set([
+        ...authorizedDomains,
+        ...questionDomainScope,
+        ...(domain ? [domain] : []),
+        ...(questionDomainScope.length === 0
+            ? (input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : [])
+            : []),
+    ]));
+    const selectedSkills = selectRelevantSkills(skills, question, {
+        userId: userId ?? null,
+        domains: inferredDomains,
+        modelAreaIds: input.domainContext?.modelAreaId ? [input.domainContext.modelAreaId] : [],
+    });
     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;
     const excludedArtifactIds = input.followUp?.kind === 'drilldown' && followUpSourceBlock
         ? new Set([followUpSourceBlock.nodeId])
         : undefined;
-    const executableArtifactHits = kg.search({ query: question, domain, kinds: EXECUTABLE_ARTIFACT_KINDS, limit: 10 });
-    const businessHits = kg.search({ query: question, domain, kinds: BUSINESS_CONTEXT_KINDS, limit: 10 });
+    const searchScope = authorizedDomains.length > 0 ? { domains: authorizedDomains } : { domain };
+    const executableArtifactHits = kg.search({ query: question, ...searchScope, kinds: EXECUTABLE_ARTIFACT_KINDS, limit: 10 });
+    const businessHits = kg.search({ query: question, ...searchScope, kinds: BUSINESS_CONTEXT_KINDS, limit: 10 });
     const artifactHits = mergeHits(executableArtifactHits, businessHits).slice(0, 12);
-    const semanticHits = kg.search({ query: question, domain, kinds: SEMANTIC_KINDS, limit: 12 });
-    const manifestHits = kg.search({ query: question, domain, kinds: MANIFEST_KINDS, limit: 12 });
+    const semanticHits = kg.search({ query: question, ...searchScope, kinds: SEMANTIC_KINDS, limit: 12 });
+    const manifestHits = kg.search({ query: question, ...searchScope, kinds: MANIFEST_KINDS, limit: 12 });
     const considered = mergeHits(artifactHits, semanticHits, manifestHits, kg.search({ query: question, domain, limit: 10 })).slice(0, 30);
-    const schemaContext = schemaContextWithAllowedSqlContext(input.schemaContext ?? [], input.contextPack);
+    const schemaContext = schemaContextWithAllowedSqlContext(schemaContextWithinQuestionScope(input.schemaContext ?? [], input.contextPack, promptContextPack), promptContextPack);
     const catalogRoute = input.contextPack?.routeDecision;
     const questionPlan = input.contextPack?.questionPlan?.requestedShape
         ? input.contextPack.questionPlan
@@ -272,6 +371,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 +396,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
@@ -322,30 +444,80 @@ async function runAnswerLoop(input) {
         if (NAVIGATION_ARTIFACT_KINDS.includes(artifactHit.node.kind)) {
             return objectNameInQuestion(question, artifactHit.node);
         }
-        // Cold questions fall through only on STRONG data-shape signals — bare
-        // measure/dimension words are normal in definition asks ("what is revenue
-        // health?") and must keep answering from the certified business context.
-        // "Strong" = outputs requested BEYOND the measure/dimension words themselves
-        // (e.g. product_name), explicit filters, or a top-N.
-        const requested = questionPlan.requestedShape;
-        const nonTrivialOutputs = requested.requiredOutputs.filter((output) => !requested.measures.includes(output) && !requested.dimensions.includes(output));
-        const strongShape = nonTrivialOutputs.length > 0
-            || requested.filters.length > 0
-            || Boolean(requested.topN);
-        return !strongShape;
+        // Terms, skills, domains, relationships, and business views are grounding
+        // documents, not executable data. They may terminate only when the user
+        // explicitly names the object in a definition request ("what is Revenue
+        // Health?"). A broad lexical match must never turn an analytical question
+        // into a no-data Certified answer merely because it starts with "what is".
+        return isBusinessDefinitionQuestion(question)
+            && objectNameInQuestion(question, artifactHit.node);
     })();
     if (artifactHit && businessContextTerminal) {
         let result;
         let executionError;
         if (artifactHit.node.kind === 'block' && input.executeCertifiedBlock) {
             try {
-                result = await input.executeCertifiedBlock(artifactHit.node);
+                result = await input.executeCertifiedBlock(artifactHit.node, { question });
                 result = trimResultToRequestedTopN(result, questionPlan);
             }
             catch (err) {
                 executionError = err instanceof Error ? err.message : String(err);
             }
         }
+        const missingParameters = /^I need values for:\s*(.+?)\.?$/i.exec(executionError ?? '')?.[1]
+            ?.split(',')
+            .map((value) => value.trim())
+            .filter(Boolean) ?? [];
+        if (missingParameters.length > 0) {
+            const text = `The certified block "${artifactHit.node.name}" needs ${missingParameters.join(', ')} before it can run. Please provide ${missingParameters.length === 1 ? 'that value' : 'those values'}; I will reuse the same certified block.`;
+            const citations = [{
+                    nodeId: artifactHit.node.nodeId,
+                    kind: artifactHit.node.kind,
+                    name: artifactHit.node.name,
+                    gitSha: artifactHit.node.gitSha,
+                    sourceTier: 'certified_artifact',
+                    provenance: artifactHit.node.provenance,
+                }];
+            const analysisPlan = buildAnalysisPlan({
+                question,
+                intent: 'clarify',
+                routeReason: 'A certified block matched, but a required values-only parameter is unresolved.',
+                selectedNodes: [artifactHit.node],
+                schemaContext,
+                assumptions: [`Required parameter values: ${missingParameters.join(', ')}.`],
+            });
+            return {
+                kind: 'no_answer',
+                sourceTier: 'certified_artifact',
+                certification: 'analyst_review_required',
+                reviewStatus: 'none',
+                confidence: 0.95,
+                text,
+                answer: text,
+                block: artifactHit.node,
+                executionError,
+                sourceCertifiedBlock: artifactHit.node.name,
+                contextPackId: input.contextPack?.id,
+                citations,
+                memoryContext: input.memoryContext,
+                analysisPlan,
+                evidence: buildNoAnswerEvidence({
+                    question,
+                    reason: text,
+                    artifactHits,
+                    businessHits,
+                    semanticHits,
+                    manifestHits,
+                    considered,
+                    memoryContext: input.memoryContext ?? [],
+                    analysisPlan,
+                    budgetTrace: cascadeBudgetTrace(repairBudgetState),
+                }),
+                contextPack: input.contextPack,
+                considered,
+                providerUsed: provider.name,
+            };
+        }
         const resultShapeWarnings = result ? validateAnswerResultShape(questionPlan, result).warnings : [];
         // When a certified block's execution was ATTEMPTED and FAILED, the answer
         // cannot wear the certified badge — a failed run has no data to stand behind.
@@ -429,8 +601,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,10 +676,28 @@ 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);
-    const contextNodes = mergeNodes(followUpSourceBlock && input.followUp?.kind === 'drilldown' ? [followUpSourceBlock] : [], (contextHits.length > 0 ? contextHits : considered.slice(0, 6)).map((h) => h.node));
+        ? 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)).filter((node) => questionDomainScope.length === 0 || !node.domain || questionDomainScope.includes(node.domain));
     const kgJoinPathHints = buildKgJoinPathHints(kg, contextNodes, questionPlan);
     const contextBlocks = contextNodes.filter((n) => n.kind === 'block');
     const contextBusiness = contextNodes.filter((n) => BUSINESS_CONTEXT_KINDS.includes(n.kind));
@@ -525,9 +713,32 @@ async function runAnswerLoop(input) {
     const skillsPrompt = buildSkillsPrompt(selectedSkills, userId ?? null);
     if (skillsPrompt)
         messages.push({ role: 'system', content: skillsPrompt });
+    const analyticalPlan = input.manifest
+        ? planAnalyticalPath(input.manifest, {
+            entityIds: inferAnalyticalEntityIds(question, contextNodes, input.manifest),
+            ownerDomain: input.domainContext?.activeDomain ?? input.domain,
+            purpose: input.domainContext?.purpose,
+            domainContext: input.domainContext,
+        })
+        : undefined;
+    const analyticalPlanPrompt = renderAnalyticalPlanPrompt(analyticalPlan);
+    if (analyticalPlanPrompt)
+        messages.push({ role: 'system', content: analyticalPlanPrompt });
+    if (questionDomainScope.length > 0) {
+        messages.push({
+            role: 'system',
+            content: [
+                'QUESTION DOMAIN BOUNDARY (authoritative for this generation):',
+                `The question is directly grounded in: ${questionDomainScope.join(', ')}.`,
+                'Use only relations and business context from those domains plus unscoped runtime/dbt relations supplied below.',
+                'Do not introduce, search for, or join another domain (including cross-domain acquisition/attribution paths) unless the user explicitly asks for that business concept or supplies a domain/purpose.',
+                'If the required relation is not modeled in this domain, prefer the bounded DBT-grounded exploratory candidate over an unrelated cross-domain relationship.',
+            ].join('\n'),
+        });
+    }
     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, promptContextPack, input.conversationSnapshot, kgJoinPathHints, promptBudget, input.semanticDriver),
     });
     messages.push({ role: 'user', content: question });
     // ── Tier 2: semantic-layer metrics + dimensions (governed hierarchy) ──────
@@ -611,14 +822,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 +879,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 +951,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 +996,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 +1030,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',
             };
         }
@@ -746,12 +1051,12 @@ async function runAnswerLoop(input) {
         || (input.contextPack?.allowedSqlContext?.relations.length ?? 0) > 0
         || (input.contextPack?.allowedSqlContext?.sourceBlockSql.length ?? 0) > 0
         || contextBlocks.length > 0;
-    if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext) {
+    if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext && analyticalPlan?.safe !== false) {
         try {
             proposed = await generateProposalWithOptionalTools({
                 provider,
                 messages: [...messages, { role: 'system', content: FORCE_JOIN_INSTRUCTION }],
-                tools: input.answerLoopTools,
+                tools: stageBTools,
                 questionPlan,
                 intent,
                 signal: input.signal,
@@ -775,9 +1080,11 @@ async function runAnswerLoop(input) {
         // every run and every surface — instead of passing through the model's varying
         // text. A genuinely context-less ask keeps the plain honest message.
         const declinedDespiteContext = wantsGeneratedData && hasGeneratableContext;
-        const text = declinedDespiteContext
-            ? 'I could not compose a governed query for this from the available tables and metrics. This usually needs a clearer join path or an explicit metric and grouping — name the specific measure and how to break it down, and I can generate a review-required draft.'
-            : parsed.text || 'No answer (the model declined to propose SQL).';
+        const text = analyticalPlan?.safe === false
+            ? analyticalPlan.message ?? 'DQL could not prove a safe analytical relationship path.'
+            : declinedDespiteContext
+                ? 'I could not compose a governed query for this from the available tables and metrics. This usually needs a clearer join path or an explicit metric and grouping — name the specific measure and how to break it down, and I can generate a review-required draft.'
+                : parsed.text || 'No answer (the model declined to propose SQL).';
         return {
             kind: 'no_answer',
             sourceTier: 'no_answer',
@@ -785,9 +1092,13 @@ async function runAnswerLoop(input) {
             reviewStatus: 'none',
             confidence: 0.1,
             text,
-            refusalCode: 'model_declined',
+            refusalCode: analyticalPlan?.safe === false
+                ? refusalCodeForAnalyticalPolicy(analyticalPlan.code)
+                : 'model_declined',
             refusalDetails: {
-                code: 'model_declined',
+                code: analyticalPlan?.safe === false
+                    ? analyticalPlan.code ?? 'unsafe_relationship'
+                    : 'model_declined',
                 message: text,
             },
             answer: text,
@@ -823,20 +1134,27 @@ async function runAnswerLoop(input) {
         && questionPlan.requestedShape.filters.length === 0
         && !questionPlan.requestedShape.topN;
     let contextValidation;
-    if (governedMetricAnswer) {
-        contextValidation = { ok: true, warnings: [] };
-    }
-    else {
-        const c = contextLedger.validateSql(parsed.sql, {
-            question,
-            intent,
-            filterValues: input.followUp?.filters,
-            trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
-        });
-        contextValidation = c.ok
-            ? { ok: true, warnings: c.warnings }
-            : { ok: false, code: c.code, error: c.error, warnings: c.warnings, offending: c.offending };
-    }
+    const initialValidation = contextLedger.validateSql(parsed.sql, {
+        question,
+        intent,
+        filterValues: input.followUp?.filters,
+        trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+    });
+    contextValidation = initialValidation.ok
+        ? { ok: true, warnings: initialValidation.warnings }
+        : {
+            ok: false,
+            code: initialValidation.code,
+            error: initialValidation.error,
+            warnings: initialValidation.warnings,
+            offending: initialValidation.offending,
+        };
+    // Semantic compilation owns metric meaning, but a later dimensional join can
+    // still make a compiled bare expression ambiguous at the warehouse binder.
+    // Revoke governed trust for an invalid composition so the bounded repair lane
+    // can qualify it and keep the repaired SQL review-required.
+    if (governedMetricAnswer && !contextValidation.ok)
+        governedMetricAnswer = false;
     // 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:
@@ -959,6 +1277,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({
@@ -1015,6 +1348,70 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
+    const dbtFirstJoinSafety = input.manifest
+        ? evaluateDbtFirstGeneratedSql(parsed.sql, input.manifest, input.domainContext?.purpose, input.domainContext)
+        : undefined;
+    if (dbtFirstJoinSafety && !dbtFirstJoinSafety.safe) {
+        const text = dbtFirstJoinSafety.message
+            ?? 'DQL could not prove this generated join from certified analytical relationships.';
+        const exploratoryCandidate = exploratoryCandidateFromDbtFirstGuard(parsed.sql, dbtFirstJoinSafety);
+        const analysisPlan = buildAnalysisPlan({
+            question,
+            intent,
+            routeReason: exploratoryCandidate
+                ? 'Governed relationship coverage is missing, so DQL prepared a bounded DBT-grounded exploratory candidate for host validation.'
+                : 'The generated SQL did not pass the governed relationship policy.',
+            selectedNodes: contextNodes,
+            schemaContext,
+            sql: parsed.sql,
+            suggestedViz: parsed.viz ?? 'table',
+            assumptions: [
+                ...contextValidation.warnings,
+                'DBT metadata is grounding evidence, not certified relationship proof.',
+            ],
+        });
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0.1,
+            text,
+            answer: text,
+            proposedSql: parsed.sql,
+            sql: parsed.sql,
+            ...(exploratoryCandidate ? { exploratoryCandidate } : {}),
+            refusalCode: refusalCodeForAnalyticalPolicy(dbtFirstJoinSafety.code, Boolean(exploratoryCandidate)),
+            refusalDetails: {
+                code: dbtFirstJoinSafety.code ?? 'unsafe_relationship',
+                message: text,
+            },
+            validationWarnings: [
+                ...contextValidation.warnings,
+                `DQL v3 relationship guard: ${dbtFirstJoinSafety.code ?? 'unsafe relationship'}.`,
+                ...(exploratoryCandidate
+                    ? ['A bounded DBT-grounded exploratory route may validate this missing modeled relationship; governed SQL was not executed.']
+                    : []),
+            ],
+            citations: [],
+            memoryContext: input.memoryContext,
+            analysisPlan,
+            evidence: buildNoAnswerEvidence({
+                question,
+                reason: text,
+                artifactHits,
+                businessHits,
+                semanticHits,
+                manifestHits,
+                considered,
+                memoryContext: input.memoryContext ?? [],
+                analysisPlan,
+            }),
+            contextPack: input.contextPack,
+            considered,
+            providerUsed: provider.name,
+        };
+    }
     const generatedCitations = [
         ...contextPackCitations(input.contextPack, 4),
         ...contextNodes.slice(0, 4).map((n) => ({
@@ -1239,26 +1636,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 +1711,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 +1756,35 @@ 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. Give every FROM
+   and JOIN relation an explicit short alias, and use only those exact aliases in
+   SELECT, ON, WHERE, GROUP BY, and ORDER BY. When a query reads more than one
+   relation, qualify every column reference with its exact relation alias; never
+   emit a bare column name. Include every requested output. Match the requested
+   result grain exactly: project and GROUP BY only the entities or dimensions the
+   user asked to compare. A category/value used only to filter the result is not
+   an additional output dimension. An entity ranking filtered to a category
+   value must return one row per requested entity, not one row per
+   entity-category-member pair.
 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.
+   fan-out (row-multiplying) joins. Treat lifetime, cumulative, balance,
+   snapshot, rate, ratio, average, and already-aggregated values as
+   non-additive across lower-grain joins: pre-aggregate at their native grain,
+   or use a grain-preserving value only when the owning entity remains in the
+   output. Never SUM the repeated parent value at child grain. If the question
+   requires allocating a parent value to children, ask for the allocation rule.
+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 +1793,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 +1819,173 @@ 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) {
+/**
+ * Produces the prompt-facing subset of a broad local context pack. Global
+ * records remain available, while a record explicitly owned by another domain
+ * cannot steer an otherwise single-domain question into its relationship path.
+ * This is not a security boundary; manifest/domain-context validation still
+ * happens after generation and at execution.
+ */
+function scopeContextPackToQuestionDomains(contextPack, domains, manifest) {
+    if (!contextPack || domains.length === 0)
+        return contextPack;
+    const allowedDomains = new Set(domains);
+    const relationDomains = manifestRelationDomains(manifest);
+    const objectDomain = (object) => object.domain ?? inferredManifestDomainForMetadataObject(object, relationDomains);
+    const objects = contextPack.objects.filter((object) => {
+        const domain = objectDomain(object);
+        return !domain || allowedDomains.has(domain);
+    });
+    const objectKeys = new Set(objects.map((object) => object.objectKey));
+    const relations = contextPack.allowedSqlContext.relations.filter((relation) => (!relation.objectKey || objectKeys.has(relation.objectKey))
+        && (!relationDomains.get(normalizeRelationKey(relation.relation))
+            || allowedDomains.has(relationDomains.get(normalizeRelationKey(relation.relation)))));
+    const relationKeys = new Set(relations.map((relation) => normalizeRelationKey(relation.relation)));
+    const selectedRelations = contextPack.retrievalDiagnostics.selectedRelations?.filter((relation) => relationKeys.has(normalizeRelationKey(relation.relation)));
+    const selectedJoinPaths = contextPack.retrievalDiagnostics.selectedJoinPaths?.filter((path) => relationKeys.has(normalizeRelationKey(path.leftRelation))
+        && relationKeys.has(normalizeRelationKey(path.rightRelation)));
+    return {
+        ...contextPack,
+        focusObjectKey: contextPack.focusObjectKey && objectKeys.has(contextPack.focusObjectKey)
+            ? contextPack.focusObjectKey
+            : objects[0]?.objectKey ?? null,
+        objects,
+        skills: contextPack.skills.filter((skill) => !skill.domain || allowedDomains.has(skill.domain)),
+        edges: contextPack.edges.filter((edge) => objectKeys.has(edge.fromKey) && objectKeys.has(edge.toKey)),
+        citations: contextPack.citations.filter((citation) => objectKeys.has(citation.objectKey)),
+        evidenceSummaries: contextPack.evidenceSummaries.filter((summary) => !summary.objectKey || objectKeys.has(summary.objectKey)),
+        evidenceRoles: contextPack.evidenceRoles.filter((role) => objectKeys.has(role.objectKey)),
+        allowedSqlContext: {
+            relations,
+            sourceBlockSql: contextPack.allowedSqlContext.sourceBlockSql.filter((source) => objectKeys.has(source.objectKey)),
+        },
+        retrievalDiagnostics: {
+            ...contextPack.retrievalDiagnostics,
+            selectedObjects: objects.length,
+            selectedEvidence: contextPack.retrievalDiagnostics.selectedEvidence.filter((evidence) => objectKeys.has(evidence.objectKey)),
+            selectedRelations,
+            selectedJoinPaths,
+            schemaShapeCandidates: contextPack.retrievalDiagnostics.schemaShapeCandidates?.filter((candidate) => objectKeys.has(candidate.objectKey)),
+            certifiedCandidateFits: contextPack.retrievalDiagnostics.certifiedCandidateFits.filter((candidate) => objectKeys.has(candidate.objectKey)),
+        },
+    };
+}
+function manifestRelationDomains(manifest) {
+    const domains = new Map();
+    if (!manifest?.modeling || !manifest.dbtProvenance)
+        return domains;
+    for (const entity of Object.values(manifest.modeling.entities)) {
+        const relation = manifest.dbtProvenance.nodes[entity.dbtUniqueId]?.relation;
+        if (relation && entity.domain)
+            domains.set(normalizeRelationKey(relation), entity.domain);
+    }
+    return domains;
+}
+function inferredManifestDomainForMetadataObject(object, relationDomains) {
+    const payload = object.payload ?? {};
+    const relation = typeof payload.relation === 'string' ? payload.relation : undefined;
+    if (relation) {
+        const direct = relationDomains.get(normalizeRelationKey(relation));
+        if (direct)
+            return direct;
+    }
+    const haystack = `${object.objectKey} ${object.name}`.toLowerCase();
+    for (const [relation, domain] of relationDomains) {
+        const model = relation.split('.').at(-1);
+        if (model && haystack.includes(model))
+            return domain;
+    }
+    return undefined;
+}
+/** Removes runtime tables that were explicitly present in, then excluded from, a broad context pack. */
+function schemaContextWithinQuestionScope(schemaContext, fullContextPack, scopedContextPack) {
+    if (!fullContextPack || fullContextPack === scopedContextPack)
+        return schemaContext;
+    const fullRelations = new Set(fullContextPack.allowedSqlContext.relations.map((relation) => normalizeRelationKey(relation.relation)));
+    const scopedRelations = new Set((scopedContextPack?.allowedSqlContext.relations ?? []).map((relation) => normalizeRelationKey(relation.relation)));
+    return schemaContext.filter((table) => {
+        const key = normalizeRelationKey(table.relation);
+        return !fullRelations.has(key) || scopedRelations.has(key);
+    });
+}
+export function inferAnalyticalEntityIds(question, contextNodes, manifest) {
+    if (manifest.manifestVersion !== 3 || !manifest.modeling || !manifest.dbtProvenance)
+        return [];
+    const normalizedQuestion = question.toLowerCase().replace(/[^a-z0-9]+/g, ' ');
+    const contextIds = new Set(contextNodes.map((node) => node.nodeId.toLowerCase()));
+    const entityIdentifierTokens = new Set(Object.values(manifest.modeling.entities).flatMap((entity) => entityIdentifierTokensForMatching(entity).map((token) => token.toLowerCase())));
+    const scored = Object.entries(manifest.modeling.entities).map(([key, entity]) => {
+        const dbt = manifest.dbtProvenance?.nodes[entity.dbtUniqueId];
+        const entityTokens = entityIdentifierTokensForMatching(entity);
+        // A backing dbt model may contain another entity's name (for example
+        // `dim_customer_acquisition`). Its `customer` token must not turn a plain
+        // customer question into an acquisition request. Only model tokens that are
+        // unique to this entity are supplemental lexical evidence.
+        const modelTokens = (dbt?.name ?? '')
+            .toLowerCase()
+            .replace(/^(fct|dim|stg)_/, '')
+            .split(/[^a-z0-9]+/)
+            .filter((token) => token.length > 2 && !entityIdentifierTokens.has(token));
+        const direct = entityTokens.some((token) => normalizedQuestion.includes(token))
+            || modelTokens.some((token) => normalizedQuestion.includes(token));
+        const inContext = contextIds.has(`entity:${entity.qualifiedId ?? entity.id}`.toLowerCase())
+            || contextIds.has(`dbt_model:${entity.dbtUniqueId}`.toLowerCase())
+            || contextNodes.some((node) => node.kind === 'dbt_model' && node.name === dbt?.name);
+        return { id: key, direct, inContext };
+    });
+    // AGT-004: context retrieval is useful for completing a clearly named model,
+    // but it must not manufacture a second entity merely because an unrelated
+    // cross-domain block ranked in the context window. That was how a Commerce
+    // product question reached Growth's attribution path. Prefer lexical evidence
+    // whenever the question names at least one modeled entity; use context-only
+    // inference solely as a fallback for genuinely indirect wording.
+    const direct = scored.filter((entry) => entry.direct);
+    const candidates = direct.length > 0 ? direct : scored.filter((entry) => entry.inContext);
+    return candidates
+        .sort((a, b) => Number(b.direct) - Number(a.direct) || a.id.localeCompare(b.id))
+        .slice(0, 5)
+        .map((entry) => entry.id);
+}
+function entityIdentifierTokensForMatching(entity) {
+    return [entity.localId ?? entity.id]
+        .flatMap((value) => value.toLowerCase().replace(/^(fct|dim|stg)_/, '').split(/[^a-z0-9]+/))
+        .filter((token) => token.length > 2 && token !== 'entity');
+}
+function renderAnalyticalPlanPrompt(plan) {
+    if (!plan || plan.entities.length < 2)
+        return undefined;
+    if (!plan.safe) {
+        return [
+            'DQL ANALYTICAL POLICY DECISION: BLOCKED.',
+            plan.message ?? 'No certified analytical relationship path is available.',
+            `Policy code: ${plan.code ?? 'unsafe_relationship'}.`,
+            'Do not invent a join from dbt lineage or shared column names. Return a clarification or refusal that asks for the missing relationship, export/import, or attribution policy.',
+        ].join('\n');
+    }
+    return [
+        'DQL CERTIFIED ANALYTICAL JOIN PLAN (authoritative):',
+        ...plan.edges.map((edge, index) => [
+            `${index + 1}. ${edge.fromEntity} (${edge.fromRelation ?? 'bound dbt model'}) -> ${edge.toEntity} (${edge.toRelation ?? 'bound dbt model'})`,
+            `   relationship=${edge.relationshipId}; keys=${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}; cardinality=${edge.cardinality}; fanout=${edge.fanout}`,
+            edge.importRefs.length ? `   imports=${edge.importRefs.join(', ')}` : '',
+        ].filter(Boolean).join('\n')),
+        'Use only these relationships and exact key pairs. dbt DAG lineage and same-named columns are not join authorization. Any different join must be refused.',
+    ].join('\n');
+}
+// 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 using explicit aliases for every relation and include every output the user requested. Preserve the metric at its native grain before joining to a lower-grain dimension. NEVER SUM a lifetime, cumulative, balance, snapshot, rate, ratio, or already-aggregated value after a one-to-many join. If the requested result retains the metric's owning entity, expose the native-grain value (or a grain-preserving MAX after deduplication) for each entity/dimension pair; if it asks to allocate that value to the child dimension, request the missing allocation policy instead of inventing one. Join ${def.table} to other grounded tables only along documented keys. State the join path, output grain, and whether each measure is an entity-level attribute or an allocated child-level measure. Reusing the governed definition keeps the answer consistent with the certified metric; if the semantic layer cannot authorize the requested dimensional composition, keep the result exploratory/review-required rather than claiming semantic provenance.`;
+}
+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 +2054,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 +3563,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 +3729,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 +3756,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 +3795,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 +3901,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 +3956,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