@duckcodeailabs/dql-agent 1.6.34 → 1.7.0

package/dist/answer-loop.js

@@ -16,6 +16,7 @@
  */
 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';
@@ -24,6 +25,8 @@ 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';
@@ -63,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'];
@@ -75,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 '';
@@ -166,6 +209,7 @@ export async function answer(input) {
     const trustLabelInfo = stampTrustLabel(result);
     return {
         ...publicResult,
+        domainContext: input.domainContext,
         intentDecision,
         trustLabelInfo,
         provenanceFooter: buildProvenanceFooter(result, trustLabelInfo),
@@ -188,7 +232,9 @@ export async function answer(input) {
         appliedSkills: result.appliedSkills ??
             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] : []),
                 ])),
@@ -219,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') {
@@ -251,16 +303,37 @@ 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 authorizedDomains = domainContextSearchDomains(input.domainContext);
     const inferredDomains = Array.from(new Set([
+        ...authorizedDomains,
+        ...questionDomainScope,
         ...(domain ? [domain] : []),
-        ...(input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.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,
@@ -276,13 +349,14 @@ async function runAnswerLoop(input) {
     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
@@ -370,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.
@@ -573,7 +697,7 @@ async function runAnswerLoop(input) {
             { 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 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));
@@ -589,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, input.semanticDriver),
+        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) ──────
@@ -904,7 +1051,7 @@ 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,
@@ -933,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',
@@ -943,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,
@@ -981,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:
@@ -1188,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) => ({
@@ -1535,12 +1759,26 @@ Rules:
    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.
+   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.
+   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,
@@ -1581,12 +1819,165 @@ 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.`;
+/**
+ * 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 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.`;
+    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