@duckcodeailabs/dql-agent 1.6.21 → 1.6.22

package/dist/metadata/catalog.js

@@ -15,6 +15,8 @@ import { buildKGFromManifest, buildKGFromSemanticLayer } from '../kg/build.js';
 import { buildBlockBusinessFingerprint, buildBlockSqlFingerprints } from './block-fingerprints.js';
 import { buildAnalysisQuestionPlan, certifiedApplicabilityForObject, scoreAllowedSqlRelationWithAnalysisPlan, scoreMetadataObjectWithAnalysisPlan, sortAllowedSqlContextForAnalysisPlan, } from './analysis-planner.js';
 import { extractSimpleSelectShape, sourceSqlShapeColumns } from './sql-shape.js';
+import { grainMatches, requestedGrainFromPlan, } from './grain-gate.js';
+import { retrieveScopedHints } from '../hints/retrieval.js';
 const require = createRequire(import.meta.url);
 let databaseCtor = null;
 function loadDatabase() {
@@ -169,6 +171,7 @@ export async function buildLocalContextPack(projectRoot, request) {
             limit: request.limit ?? 120,
         });
         const conflicts = buildCandidateConflicts(reranked.ranked);
+        const compileConflicts = catalog.compileConflicts();
         const routeDecision = planContextPackRoute({
             request,
             objects,
@@ -177,7 +180,17 @@ export async function buildLocalContextPack(projectRoot, request) {
             diagnostics,
             trustLabel,
             questionPlan,
+            compileConflicts,
+            rankedObjects: reranked.ranked,
         });
+        // Approved scoped correction hints — folded in AFTER certified routing so
+        // they never override a certified answer. On the `certified` route we still
+        // surface in-scope hints as advisory context, but never to change the route.
+        const questionScope = deriveQuestionScope(request, questionPlan, objects, routeDecision);
+        const hintResult = await retrieveScopedHints(projectRoot, {
+            questionScope,
+            limit: 6,
+        }).catch(() => ({ applied: [], conflicts: [] }));
         const payload = {
             id: '',
             question: request.question,
@@ -197,6 +210,8 @@ export async function buildLocalContextPack(projectRoot, request) {
             allowedSqlContext,
             missingContext: routeDecision.missingContext,
             conflicts,
+            appliedHints: hintResult.applied,
+            hintConflicts: hintResult.conflicts,
             retrievalDiagnostics: {
                 strategy: 'sqlite_fts',
                 selectedObjects: objects.length,
@@ -309,12 +324,16 @@ export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer) {
             edges.set(key, normalized);
     }
     addProjectDiagnostics(manifest, semanticLayer, diagnostics);
+    const compileConflicts = (manifest.diagnostics ?? [])
+        .filter((diagnostic) => diagnostic.kind === 'conflict' && Boolean(diagnostic.conflict))
+        .map((diagnostic) => diagnostic.conflict);
     const snapshot = {
         projectRoot,
         manifest,
         objects: Array.from(objects.values()).sort((a, b) => a.objectKey.localeCompare(b.objectKey)),
         edges: Array.from(edges.values()).sort((a, b) => `${a.edgeType}|${a.fromKey}|${a.toKey}`.localeCompare(`${b.edgeType}|${b.fromKey}|${b.toKey}`)),
         diagnostics,
+        compileConflicts,
         generatedAt: new Date().toISOString(),
         fingerprint: '',
     };
@@ -514,6 +533,7 @@ export class MetadataCatalog {
             setState.run('source_fingerprint_count', String(sourceFingerprints.length));
             setState.run('domain_shard_count', String(domainShards.length));
             setState.run('diagnostics_json', JSON.stringify(snapshot.diagnostics));
+            setState.run('compile_conflicts_json', JSON.stringify(snapshot.compileConflicts ?? []));
             setState.run('manifest_generated_at', snapshot.manifest.generatedAt);
         });
         txn();
@@ -738,6 +758,14 @@ export class MetadataCatalog {
             filePath: row.file_path ?? undefined,
         }));
     }
+    /** Structured compile-time trust conflicts persisted with the last rebuild. */
+    compileConflicts() {
+        const raw = this.state('compile_conflicts_json');
+        if (!raw)
+            return [];
+        const parsed = safeJson(raw, null);
+        return Array.isArray(parsed) ? parsed : [];
+    }
     sourceFingerprints(limit = 500) {
         const rows = this.db.prepare(`
       SELECT source_path, fingerprint, object_count, updated_at
@@ -1459,8 +1487,71 @@ function addProjectDiagnostics(manifest, semanticLayer, diagnostics) {
         });
     }
 }
+/**
+ * Resolve the question's scope (metric / dbt model / domain / term / block) for
+ * scoped-hint matching. Drawn from the route's chosen objects + question plan so
+ * a hint only applies inside the same metric/model/domain it was approved for.
+ * Dialect is intentionally left undefined here (unknown at this layer); the hint
+ * scope matcher tolerates an unknown question dialect.
+ */
+function deriveQuestionScope(request, questionPlan, objects, routeDecision) {
+    const focusKey = routeDecision.exactObjectKey ?? request.focusObjectKey;
+    const focus = focusKey ? objects.find((object) => object.objectKey === focusKey) : undefined;
+    const topByType = (type) => objects.find((object) => object.objectType === type);
+    const metricObject = (focus && (focus.objectType === 'semantic_metric' || focus.objectType === 'dql_block') ? focus : undefined) ??
+        topByType('semantic_metric');
+    const dbtObject = topByType('dbt_model');
+    const metric = firstNonEmpty(metricObject?.objectType === 'semantic_metric' ? metricObject.name : undefined, questionPlan.metricTerms[0]);
+    const domain = firstNonEmpty(focus?.domain, metricObject?.domain, dbtObject?.domain, ...objects.map((o) => o.domain));
+    const dbtModel = dbtObject?.name;
+    const block = focus?.objectType === 'dql_block' ? focus.name : undefined;
+    const term = focus?.objectType === 'dql_term' ? focus.name : topByType('dql_term')?.name;
+    return {
+        metric: lowerOrUndef(metric),
+        dbtModel: lowerOrUndef(dbtModel),
+        domain: lowerOrUndef(domain),
+        term: lowerOrUndef(term),
+        block,
+        text: request.question,
+    };
+}
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        if (value && value.trim().length > 0)
+            return value;
+    }
+    return undefined;
+}
+function lowerOrUndef(value) {
+    return value ? value.trim().toLowerCase() : undefined;
+}
 function planContextPackRoute(input) {
     const intent = input.request.intent ?? input.questionPlan.routeIntent ?? classifyMetadataIntent(input.request.question, input.request.followUp);
+    // Conflict route (additive, evaluated first): if the question's top governed
+    // candidates include BOTH sides of a compile-time trust conflict, refuse to
+    // silently pick one. Surface both definitions + owners + a disambiguation
+    // prompt. Only fires when both conflicting sides are actually among the
+    // selected candidates for THIS question, so non-conflicting asks are
+    // unaffected even when a conflict exists elsewhere in the project.
+    const routeConflict = pickRouteConflict(input.compileConflicts ?? [], input.rankedObjects ?? [], input.objects);
+    if (routeConflict) {
+        const selectedEvidenceForConflict = input.evidenceRoles.slice(0, 16);
+        return {
+            route: 'conflict',
+            intent,
+            reason: `Two certified ${routeConflict.objectType}s claim "${routeConflict.concept}" but disagree (${routeConflict.reason}). DQL refuses to guess which is authoritative.`,
+            trustLabel: 'conflict',
+            reviewStatus: 'conflict',
+            selectedEvidence: selectedEvidenceForConflict,
+            missingContext: [{
+                    kind: 'metadata',
+                    severity: 'blocking',
+                    message: routeConflict.prompt,
+                }],
+            followUps: [routeConflict.prompt],
+            routeConflict,
+        };
+    }
     const applicabilityByKey = certifiedApplicabilities(input.objects, input.questionPlan);
     const exactByApplicability = [...applicabilityByKey.values()]
         .filter((item) => item.kind === 'exact_answer' || item.kind === 'safe_parameterized')
@@ -1477,7 +1568,35 @@ function planContextPackRoute(input) {
     const exactExampleMatch = exact ? hasExactExampleQuestion(input.request.question, exact) : false;
     const missingContext = buildMissingContext(input.request, intent, input.objects, input.allowedSqlContext);
     const selectedEvidence = input.evidenceRoles.slice(0, 16);
-    if (exact && (certifiedApplicability?.kind === 'exact_answer'
+    // Grain / contract gate (refinement of the existing certified→generated
+    // demotion). The candidate certified block is only served at Tier 1 when its
+    // declared grain actually satisfies the question's requested grain. An
+    // explicit example/name match bypasses the gate — the user is naming the
+    // block directly, so grain is implicitly accepted.
+    const requestedGrain = requestedGrainFromPlan(input.questionPlan);
+    const grainGate = exact && !exactExampleMatch && intent !== 'definition_lookup'
+        ? grainMatches(exact, requestedGrain)
+        : undefined;
+    const grainGateInfo = exact && grainGate
+        ? {
+            blockObjectKey: exact.objectKey,
+            blockName: exact.name,
+            allow: grainGate.allow,
+            kind: grainGate.kind,
+            requestedGrain: grainGate.requestedGrainLabel,
+            blockGrain: grainGate.blockGrainLabel,
+            reason: grainGate.reason,
+        }
+        : undefined;
+    // A genuine grain/entity mismatch demotes the candidate to Tier 2 — but only
+    // when generated SQL is actually possible. If nothing else can answer, we do
+    // not strand the user; the existing certified fallback still applies (and
+    // query_via_block enforces the gate defensively at execution time).
+    const canGenerateFromContext = input.allowedSqlContext.relations.length > 0 ||
+        input.allowedSqlContext.sourceBlockSql.length > 0 ||
+        input.objects.some((object) => object.objectType.startsWith('semantic_'));
+    const grainGateDemotes = Boolean(grainGate && !grainGate.allow && canGenerateFromContext);
+    if (!grainGateDemotes && exact && (certifiedApplicability?.kind === 'exact_answer'
         || certifiedApplicability?.kind === 'safe_parameterized'
         || intent === 'exact_certified_lookup'
         || intent === 'definition_lookup'
@@ -1487,6 +1606,8 @@ function planContextPackRoute(input) {
             route: 'certified',
             intent,
             reason: `Certified ${exact.objectType.replace(/_/g, ' ')} "${exact.name}" exactly matches the requested artifact, definition, or direct KPI grain.`,
+            routeReason: grainGateInfo?.reason,
+            grainGate: grainGateInfo,
             trustLabel: 'certified',
             reviewStatus: 'certified',
             exactObjectKey: exact.objectKey,
@@ -1496,6 +1617,26 @@ function planContextPackRoute(input) {
             followUps: buildMetadataFollowUps(intent, input.allowedSqlContext),
         };
     }
+    // Grain-gated demotion: the best certified candidate is close but answers a
+    // different grain. Serve Tier 2 (generated from context) with the block kept
+    // as context only, instead of a confidently-wrong governed answer.
+    if (grainGateDemotes && exact && grainGate) {
+        return {
+            route: 'generated_sql',
+            intent: isGeneratedMetadataIntent(intent) ? intent : 'ad_hoc_ranking',
+            reason: `Certified block "${exact.name}" is close but answers a different grain than the question, so it is context only and SQL is generated for the requested grain.`,
+            routeReason: grainGate.reason,
+            grainGate: grainGateInfo,
+            trustLabel: input.trustLabel === 'certified' ? 'mixed' : input.trustLabel,
+            reviewStatus: 'draft_ready',
+            certifiedApplicability: certifiedApplicability
+                ? { ...certifiedApplicability, kind: 'context_only' }
+                : contextApplicability,
+            selectedEvidence,
+            missingContext,
+            followUps: buildMetadataFollowUps(isGeneratedMetadataIntent(intent) ? intent : 'ad_hoc_ranking', input.allowedSqlContext),
+        };
+    }
     if (intent === 'trust_gap_review') {
         if (input.objects.length === 0) {
             return clarifyDecision(intent, input.trustLabel, selectedEvidence, [{
@@ -2200,9 +2341,28 @@ function buildAllowedSqlContext(objects, edges) {
             name: object.name,
             status: object.status,
             sql: String(object.payload?.sql ?? ''),
+            description: typeof object.payload?.description === 'string' ? object.payload.description : undefined,
+            exampleQuestion: firstExampleQuestion(object.payload?.examples),
+            grain: typeof object.payload?.grain === 'string' ? object.payload.grain : undefined,
         })),
     };
 }
+// Pull the first natural-language example question off a block payload so the
+// certified block can serve as a question→SQL few-shot exemplar.
+function firstExampleQuestion(examples) {
+    if (!Array.isArray(examples))
+        return undefined;
+    for (const example of examples) {
+        if (typeof example === 'string' && example.trim())
+            return example.trim();
+        if (example && typeof example === 'object') {
+            const question = example.question;
+            if (typeof question === 'string' && question.trim())
+                return question.trim();
+        }
+    }
+    return undefined;
+}
 function buildSelectedJoinPaths(allowedSqlContext) {
     const relations = allowedSqlContext.relations
         .filter((relation) => relation.columns.some((column) => isJoinKeyColumnForCatalog(column.name)))
@@ -3028,6 +3188,53 @@ function buildCandidateConflicts(ranked) {
 function isGovernedCandidate(row) {
     return row.status === 'certified' || row.status === 'approved';
 }
+/**
+ * Select a compile-time trust conflict to route on, but only when BOTH of its
+ * sides appear among the question's top candidates. This keeps the conflict
+ * route scoped to questions the conflicting pair actually answers — a conflict
+ * elsewhere in the project never hijacks an unrelated question.
+ */
+function pickRouteConflict(compileConflicts, rankedObjects, fallbackObjects) {
+    if (compileConflicts.length === 0)
+        return undefined;
+    // Names of the top candidate objects for this question (bounded — only the
+    // strongest matches count as "top candidates").
+    const topNames = new Set();
+    const ordered = rankedObjects.length > 0
+        ? rankedObjects.slice(0, 12).map((item) => item.row)
+        : fallbackObjects.slice(0, 12);
+    for (const row of ordered) {
+        const norm = normalizeConflictName(row.name);
+        if (norm)
+            topNames.add(norm);
+    }
+    for (const conflict of compileConflicts) {
+        const sideNames = conflict.sides.map((side) => normalizeConflictName(side.name)).filter(Boolean);
+        if (sideNames.length < 2)
+            continue;
+        const presentSides = sideNames.filter((name) => topNames.has(name));
+        if (presentSides.length < 2)
+            continue;
+        return {
+            objectType: conflict.objectType,
+            concept: conflict.concept,
+            reason: conflict.reason,
+            prompt: conflict.prompt,
+            sides: conflict.sides.map((side) => ({
+                name: side.name,
+                owner: side.owner,
+                domain: side.domain,
+                filePath: side.filePath,
+                definition: side.definition,
+                businessRules: side.businessRules,
+            })),
+        };
+    }
+    return undefined;
+}
+function normalizeConflictName(value) {
+    return (value ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
 function tokenize(text) {
     return Array.from(new Set(text.toLowerCase().replace(/[^a-z0-9_ ]+/g, ' ').split(/\s+/).filter((term) => term.length >= 3))).slice(0, 24);
 }