@duckcodeailabs/dql-agent 1.11.10 → 1.12.0

package/dist/metadata/catalog.js

@@ -20,6 +20,7 @@ import { extractSimpleSelectShape, sourceSqlShapeColumns } from './sql-shape.js'
 import { grainMatches, requestedGrainFromPlan, } from './grain-gate.js';
 import { certifiedFitAllowsTier1, certifiedTerminationVerdict, evaluateCertifiedBlockFit, } from './block-fit.js';
 import { retrieveScopedHints } from '../hints/retrieval.js';
+import { currentHintDependencyFingerprints } from '../hints/dependencies.js';
 import { buildFtsMatch } from '../memory/fts-query.js';
 import { cosineSimilarity, envEmbeddingProvider, HashedTokenEmbeddingProvider, } from '../embeddings/provider.js';
 import { projectEmbeddingProvider } from '../embeddings/project-embeddings.js';
@@ -721,11 +722,16 @@ export async function buildLocalContextPack(projectRoot, request) {
         // 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 questionScope = deriveQuestionScope(request, questionPlan, objects, routeDecision, allowedSqlContext);
         const hintResult = await retrieveScopedHints(projectRoot, {
             questionScope,
             limit: 6,
-        }).catch(() => ({ applied: [], conflicts: [] }));
+            currentSnapshotId: catalog.state('fingerprint'),
+            currentDependencies: currentHintDependencyFingerprints({
+                objects,
+                relations: allowedSqlContext.relations,
+            }),
+        }).catch(() => ({ applied: [], conflicts: [], excluded: [] }));
         const knowledgeLens = buildKnowledgeLens(catalog, effectiveDomainContext, selectedSkills);
         const domainBriefing = buildDomainBriefing(catalog, effectiveDomainContext);
         const payload = {
@@ -753,6 +759,7 @@ export async function buildLocalContextPack(projectRoot, request) {
             conflicts,
             appliedHints: hintResult.applied,
             hintConflicts: hintResult.conflicts,
+            hintExclusions: hintResult.excluded,
             retrievalDiagnostics: {
                 strategy: usedFullCatalog ? 'full_catalog' : 'sqlite_fts',
                 lanes: snapshotRetrieval.lanes,
@@ -2278,11 +2285,21 @@ export class MetadataCatalog {
         const capturedAt = snapshot.capturedAt ?? new Date().toISOString();
         const normalizedTables = normalizeRuntimeSchemaTables(snapshot.tables).slice(0, 10_000);
         const cleanSnapshot = {
+            version: 1,
+            generationId: snapshot.generationId,
+            scopeFingerprint: snapshot.scopeFingerprint,
+            connectionId: snapshot.connectionId,
+            status: snapshot.status ?? 'ready',
             source: snapshot.source,
             capturedAt,
+            observedTarget: normalizeRuntimeSchemaObservedTarget(snapshot.observedTarget),
+            scopes: normalizeRuntimeSchemaScopes(snapshot.scopes),
+            queryCount: boundedRuntimeSchemaNumber(snapshot.queryCount),
+            durationMs: boundedRuntimeSchemaNumber(snapshot.durationMs),
+            truncated: snapshot.truncated === true || undefined,
             tables: normalizedTables,
         };
-        const id = `schema_${Date.parse(capturedAt) || Date.now()}`;
+        const id = snapshot.generationId?.trim() || `schema_${Date.parse(capturedAt) || Date.now()}`;
         const insertSnapshot = this.db.prepare(`
       INSERT OR REPLACE INTO runtime_schema_snapshots (
         id, source, payload_json, captured_at
@@ -2325,6 +2342,10 @@ export class MetadataCatalog {
             setState.run('runtime_value_index_captured_at', capturedAt);
             setState.run('runtime_schema_table_count', String(normalizedTables.length));
             setState.run('runtime_schema_index_captured_at', capturedAt);
+            setState.run('runtime_schema_generation_id', id);
+            if (cleanSnapshot.scopeFingerprint) {
+                setState.run('runtime_schema_scope_fingerprint', cleanSnapshot.scopeFingerprint);
+            }
         });
         txn();
         return cleanSnapshot;
@@ -2989,6 +3010,10 @@ function addRawDbtCatalogObject(input) {
             schema,
             materialized: rawDbtMaterialization(input.node),
             dependsOn: rawDbtDependsOn(input.node),
+            // dbt's checksum changes with the model/source definition. Persist it in
+            // the governed object so Hint Graph dependency fingerprints detect SQL
+            // edits even when relation names and columns stay the same.
+            checksum: input.node.checksum,
             tags: metadataStringArray(input.node.tags),
             catalogOnly: existing ? undefined : true,
             columnCompleteness,
@@ -3762,7 +3787,7 @@ function addProjectDiagnostics(manifest, semanticLayer, diagnostics) {
  * 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) {
+function deriveQuestionScope(request, questionPlan, objects, routeDecision, allowedSqlContext) {
     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);
@@ -3784,6 +3809,13 @@ function deriveQuestionScope(request, questionPlan, objects, routeDecision) {
         domain: lowerOrUndef(domain),
         term: lowerOrUndef(term),
         block,
+        relations: allowedSqlContext.relations
+            .map((relation) => relation.relation)
+            .filter(Boolean)
+            .slice(0, 80),
+        columns: allowedSqlContext.relations
+            .flatMap((relation) => relation.columns.map((column) => `${relation.relation}.${column.name}`))
+            .slice(0, 320),
         text: request.question,
     };
 }
@@ -5580,6 +5612,7 @@ function runtimeSchemaTableObject(table, snapshotSource, capturedAt) {
         sourceSystem: snapshotSource ?? table.source ?? 'runtime schema snapshot',
         payload: compactObject({
             relation,
+            catalogOrDatabase: table.catalogOrDatabase,
             schema: table.schema,
             columnCompleteness: 'complete',
             columns: table.columns,
@@ -5935,6 +5968,7 @@ function normalizeRuntimeSchemaTables(tables) {
         const current = byRelation.get(key);
         const normalized = {
             relation,
+            catalogOrDatabase: table.catalogOrDatabase,
             schema: table.schema,
             name: table.name ?? relation.split('.').at(-1) ?? relation,
             description: table.description,
@@ -5967,11 +6001,59 @@ function safeRuntimeSchemaSnapshot(value) {
     if (!Array.isArray(record.tables))
         return null;
     return {
+        version: 1,
+        generationId: stringValue(record.generationId),
+        scopeFingerprint: stringValue(record.scopeFingerprint),
+        connectionId: stringValue(record.connectionId),
+        status: record.status === 'partial' || record.status === 'stale' ? record.status : 'ready',
         source: stringValue(record.source),
         capturedAt: stringValue(record.capturedAt),
+        observedTarget: normalizeRuntimeSchemaObservedTarget(record.observedTarget),
+        scopes: normalizeRuntimeSchemaScopes(record.scopes),
+        queryCount: boundedRuntimeSchemaNumber(record.queryCount),
+        durationMs: boundedRuntimeSchemaNumber(record.durationMs),
+        truncated: record.truncated === true || undefined,
         tables: normalizeRuntimeSchemaTables(record.tables),
     };
 }
+function normalizeRuntimeSchemaObservedTarget(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const driver = stringValue(record.driver);
+    if (!driver)
+        return undefined;
+    return {
+        driver,
+        accountOrWorkspace: stringValue(record.accountOrWorkspace),
+        role: stringValue(record.role),
+        warehouse: stringValue(record.warehouse),
+        defaultCatalogOrDatabase: stringValue(record.defaultCatalogOrDatabase),
+        defaultSchema: stringValue(record.defaultSchema),
+    };
+}
+function normalizeRuntimeSchemaScopes(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const scopes = value.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return [];
+        const record = entry;
+        const catalogOrDatabase = stringValue(record.catalogOrDatabase);
+        if (!catalogOrDatabase)
+            return [];
+        const schemas = Array.isArray(record.schemas)
+            ? Array.from(new Set(record.schemas.map(stringValue).filter((item) => Boolean(item))))
+            : [];
+        return [{ catalogOrDatabase, schemas }];
+    });
+    return scopes.length > 0 ? scopes : undefined;
+}
+function boundedRuntimeSchemaNumber(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+        return undefined;
+    return Math.min(Number.MAX_SAFE_INTEGER, Math.floor(value));
+}
 function metadataRuntimeColumns(value) {
     if (!Array.isArray(value))
         return [];