@duckcodeailabs/dql-agent 1.11.10 → 1.12.1

package/dist/hints/graph.js

@@ -0,0 +1,222 @@
+import { analyzeSqlReferences } from '@duckcodeailabs/dql-core';
+const HIGH_SIGNAL_EDGE_KINDS = new Set([
+    'belongs_to_domain',
+    'refines_metric',
+    'uses_dbt_model',
+    'refines_term',
+    'relates_to_block',
+]);
+/**
+ * Materialize a hint's typed graph connections from governed scope,
+ * dependencies, lifecycle provenance, and parsed corrected SQL.
+ */
+export function buildHintGraphEdges(hint) {
+    const edges = new Map();
+    const add = (edge) => {
+        edges.set(`${edge.kind}\0${edge.targetId}`, edge);
+    };
+    for (const edge of scopeEdges(hint.id, hint.scope))
+        add(edge);
+    for (const dependency of hint.dependencies ?? []) {
+        add({
+            hintId: hint.id,
+            kind: dependencyEdgeKind(dependency.kind),
+            targetId: normalizeTargetId(dependency.id),
+            targetKind: dependency.kind,
+            targetName: dependency.name,
+            fingerprint: dependency.fingerprint,
+            source: 'dependency',
+        });
+    }
+    if (hint.correctedSql?.trim()) {
+        const analysis = analyzeSqlReferences(hint.correctedSql, hint.scope.dialect);
+        const internalRelations = new Set([...analysis.ctes, ...analysis.derivedRelations].map(normalizeRelation));
+        for (const relation of analysis.tables) {
+            const normalizedRelation = normalizeRelation(relation);
+            add({
+                hintId: hint.id,
+                kind: 'uses_relation',
+                targetId: `relation:${normalizedRelation}`,
+                targetKind: 'relation',
+                targetName: relation,
+                source: 'corrected_sql',
+            });
+        }
+        for (const column of analysis.columns) {
+            if (!column.relation || column.outputAliasReference)
+                continue;
+            const normalizedRelation = normalizeRelation(column.relation);
+            if (internalRelations.has(normalizedRelation))
+                continue;
+            const normalizedColumn = normalizeName(column.column);
+            add({
+                hintId: hint.id,
+                kind: 'uses_column',
+                targetId: `column:${normalizedRelation}.${normalizedColumn}`,
+                targetKind: 'column',
+                targetName: `${column.relation}.${column.column}`,
+                source: 'corrected_sql',
+            });
+        }
+    }
+    if (hint.traceId) {
+        add({
+            hintId: hint.id,
+            kind: 'derived_from',
+            targetId: `trace:${normalizeName(hint.traceId)}`,
+            targetKind: 'trace',
+            targetName: hint.traceId,
+            source: 'lifecycle',
+        });
+    }
+    if (hint.evaluationId) {
+        add({
+            hintId: hint.id,
+            kind: 'validated_by',
+            targetId: `evaluation:${normalizeName(hint.evaluationId)}`,
+            targetKind: 'evaluation',
+            targetName: hint.evaluationId,
+            source: 'lifecycle',
+        });
+    }
+    if (hint.supersedes) {
+        add({
+            hintId: hint.id,
+            kind: 'supersedes',
+            targetId: `hint:${normalizeName(hint.supersedes)}`,
+            targetKind: 'hint',
+            targetName: hint.supersedes,
+            source: 'lifecycle',
+        });
+    }
+    return [...edges.values()].sort((left, right) => left.kind.localeCompare(right.kind) || left.targetId.localeCompare(right.targetId));
+}
+/** Graph targets resolved for a new question. */
+export function questionHintGraphTargetIds(scope) {
+    const targets = new Set();
+    for (const edge of scopeEdges('__question__', scope))
+        targets.add(edge.targetId);
+    for (const relation of scope.relations ?? []) {
+        targets.add(`relation:${normalizeRelation(relation)}`);
+    }
+    for (const column of scope.columns ?? []) {
+        const normalized = normalizeQualifiedColumn(column);
+        if (normalized)
+            targets.add(`column:${normalized}`);
+    }
+    return targets;
+}
+/**
+ * High-signal targets may recall a hint even when wording differs. Relation and
+ * column edges deliberately only rank/explain a recalled hint: schema overlap
+ * alone is too broad to make a correction applicable.
+ */
+export function highSignalHintGraphTargetIds(scope) {
+    const targets = new Set();
+    for (const edge of scopeEdges('__question__', scope)) {
+        if (HIGH_SIGNAL_EDGE_KINDS.has(edge.kind))
+            targets.add(edge.targetId);
+    }
+    return targets;
+}
+export function describeHintGraphOverlap(edges, targets) {
+    const matched = edges.filter((edge) => targets.has(edge.targetId));
+    if (matched.length === 0)
+        return undefined;
+    const grouped = new Map();
+    for (const edge of matched) {
+        const values = grouped.get(edge.targetKind) ?? [];
+        if (!values.includes(edge.targetName))
+            values.push(edge.targetName);
+        grouped.set(edge.targetKind, values);
+    }
+    return [...grouped.entries()]
+        .map(([kind, names]) => `${kind}=${names.slice(0, 4).join(', ')}`)
+        .join('; ');
+}
+export function hintGraphOverlapScore(edges, targets) {
+    let score = 0;
+    for (const edge of edges) {
+        if (!targets.has(edge.targetId))
+            continue;
+        score += edgeWeight(edge.kind);
+    }
+    return Math.min(score, 0.85);
+}
+function scopeEdges(hintId, scope) {
+    const edges = [];
+    const add = (kind, targetKind, value) => {
+        if (!value?.trim())
+            return;
+        edges.push({
+            hintId,
+            kind,
+            targetId: `${targetKind}:${normalizeName(value)}`,
+            targetKind,
+            targetName: value,
+            source: 'scope',
+        });
+    };
+    add('belongs_to_domain', 'domain', scope.domain);
+    add('refines_metric', 'metric', scope.metric);
+    add('uses_dbt_model', 'dbt_model', scope.dbtModel);
+    add('refines_term', 'term', scope.term);
+    add('relates_to_block', 'block', scope.block);
+    add('uses_dialect', 'dialect', scope.dialect);
+    if ('metrics' in scope) {
+        for (const metric of scope.metrics ?? [])
+            add('refines_metric', 'metric', metric);
+        for (const model of scope.dbtModels ?? [])
+            add('uses_dbt_model', 'dbt_model', model);
+    }
+    return edges;
+}
+function dependencyEdgeKind(kind) {
+    if (kind === 'domain')
+        return 'belongs_to_domain';
+    if (kind === 'metric')
+        return 'refines_metric';
+    if (kind === 'dbt_model')
+        return 'uses_dbt_model';
+    if (kind === 'relation')
+        return 'uses_relation';
+    if (kind === 'term')
+        return 'refines_term';
+    if (kind === 'block')
+        return 'relates_to_block';
+    return 'depends_on';
+}
+function edgeWeight(kind) {
+    if (kind === 'refines_metric' || kind === 'relates_to_block')
+        return 0.3;
+    if (kind === 'belongs_to_domain' || kind === 'uses_dbt_model' || kind === 'refines_term')
+        return 0.22;
+    if (kind === 'uses_relation')
+        return 0.12;
+    if (kind === 'uses_column')
+        return 0.06;
+    if (kind === 'uses_dialect')
+        return 0.03;
+    return 0;
+}
+function normalizeTargetId(value) {
+    const [kind, ...rest] = value.split(':');
+    return rest.length > 0
+        ? `${normalizeName(kind)}:${normalizeName(rest.join(':'))}`
+        : normalizeName(value);
+}
+function normalizeQualifiedColumn(value) {
+    const normalized = value.replace(/["`\[\]]/g, '').trim().toLowerCase();
+    const parts = normalized.split('.').filter(Boolean);
+    if (parts.length < 2)
+        return undefined;
+    const column = parts.pop();
+    return `${parts.join('.')}.${column}`;
+}
+function normalizeRelation(value) {
+    return value.replace(/["`\[\]]/g, '').trim().toLowerCase();
+}
+function normalizeName(value) {
+    return value.trim().toLowerCase();
+}
+//# sourceMappingURL=graph.js.map

package/dist/hints/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/hints/graph.ts"],"names":[],"mappings":"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"}

package/dist/hints/lifecycle.d.ts

@@ -0,0 +1,107 @@
+import { type RecordCorrectionTraceInput, type RecordCorrectionTraceResult, type ReviewHintResult } from './git-store.js';
+import type { HintDependency, HintEvaluation, HintEvaluationCheck, HintScope, Hint, CorrectionTrace } from './types.js';
+export interface GovernedHintContext {
+    snapshotId: string;
+    dependencies: HintDependency[];
+    checks: HintEvaluationCheck[];
+    evidence: string[];
+}
+export type ResolveGovernedHintContext = (input: {
+    projectRoot: string;
+    question: string;
+    correctedSql?: string;
+    scope: HintScope;
+    snapshotId?: string;
+}) => Promise<GovernedHintContext>;
+export interface GovernedHintExecutionResult {
+    columns: unknown[];
+    rows: unknown[];
+    rowCount: number;
+    sql?: string;
+    executionReceipt?: unknown;
+}
+export type ExecuteGovernedHintSql = (sql: string, options: {
+    rowLimit: number;
+    question: string;
+}) => Promise<GovernedHintExecutionResult>;
+export interface RecordGovernedCorrectionInput extends Omit<RecordCorrectionTraceInput, 'failedRoute' | 'evidence' | 'snapshotId' | 'requiredEvaluation' | 'dependencies' | 'lifecycleErrors'> {
+    failedRoute?: string;
+    evidence?: string[];
+    snapshotId?: string;
+    requiredEvaluation?: string;
+}
+export interface ReviewGovernedHintInput {
+    hintId: string;
+    decision: 'approved' | 'rejected';
+    reviewer: string;
+    note?: string;
+    snapshotId?: string;
+    rowLimit?: number;
+    executeSql?: ExecuteGovernedHintSql;
+    resolveContext?: ResolveGovernedHintContext;
+}
+export interface ReviewGovernedHintResult extends ReviewHintResult {
+    evaluation?: HintEvaluation;
+}
+export interface GovernedHintInspection {
+    hint: Hint;
+    trace?: CorrectionTrace;
+    evaluation?: HintEvaluation;
+    currentSnapshotId: string;
+    snapshotCurrent: boolean;
+    dependenciesCurrent: boolean;
+    driftedDependencies: HintDependency[];
+    checks: HintEvaluationCheck[];
+    state: 'current' | 'stale' | 'invalid' | 'unverified';
+}
+export interface EditGovernedHintCandidateInput {
+    hintId: string;
+    title?: string;
+    guidance?: string;
+    correctedSql?: string;
+    scope?: HintScope;
+    snapshotId?: string;
+    resolveContext?: ResolveGovernedHintContext;
+}
+/**
+ * Shared correction capture path for the notebook API, CLI runtime, and MCP.
+ * Capture remains permissive: unsafe or unresolved corrections are retained as
+ * candidates with lifecycle errors, but can never pass approval.
+ */
+export declare function recordGovernedCorrection(projectRoot: string, input: RecordGovernedCorrectionInput, resolveContext?: ResolveGovernedHintContext): Promise<RecordCorrectionTraceResult>;
+/**
+ * Do not let a SQL-only correction silently become the reusable lesson. Older
+ * clients may omit `hintGuidance`, so preserve a human-written correction when
+ * one exists and otherwise derive a conservative, reviewable instruction.
+ */
+export declare function deriveCorrectionGuidance(input: Pick<RecordGovernedCorrectionInput, 'question' | 'scope' | 'correction' | 'correctedSql' | 'hintGuidance'>): string;
+/**
+ * Shared fail-closed review path. A v3 approval always creates a fresh
+ * evaluation artifact, so a failed attempt remains reviewable and retryable.
+ */
+export declare function reviewGovernedHint(projectRoot: string, input: ReviewGovernedHintInput): Promise<ReviewGovernedHintResult | null>;
+/** CTX-005 / API-003: read-only live inspection used by review surfaces and lifecycle decisions. */
+export declare function inspectGovernedHint(projectRoot: string, input: {
+    hintId: string;
+    snapshotId?: string;
+    resolveContext?: ResolveGovernedHintContext;
+}): Promise<GovernedHintInspection | null>;
+/** CTX-005 / E2E-001: explicit edit revalidates provenance and clears prior evaluation state. */
+export declare function editGovernedHintCandidate(projectRoot: string, input: EditGovernedHintCandidateInput): Promise<Hint | null>;
+/** CTX-005: reopen an applied/retired hint as a non-retrievable candidate against current context. */
+export declare function reopenGovernedHint(projectRoot: string, input: {
+    hintId: string;
+    reviewer: string;
+    note?: string;
+    snapshotId?: string;
+    resolveContext?: ResolveGovernedHintContext;
+}): Promise<ReviewHintResult | null>;
+/** Resolve current SQL authorization and content-addressed dependencies. */
+export declare function resolveGovernedHintContext(input: {
+    projectRoot: string;
+    question: string;
+    correctedSql?: string;
+    scope: HintScope;
+    snapshotId?: string;
+}): Promise<GovernedHintContext>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/hints/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/hints/lifecycle.ts"],"names":[],"mappings":"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"}