@duckcodeailabs/dql-mcp 1.6.21 → 1.6.22

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8BpE,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,oBAAoB,QAmBT,CAAC;AAEzB,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,SAAS,CAoI/E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8CpE,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,oBAAoB,QAiCkB,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,SAAS,CA0L/E"}

package/dist/server.js

@@ -11,6 +11,8 @@ import { queryViaMetadata, queryViaMetadataInput } from './tools/query-via-metad
 import { listProposals, listProposalsInput } from './tools/list-proposals.js';
 import { feedbackRecord, feedbackRecordInput, inspectMetadataContext, inspectMetadataContextInput, kgSearch, kgSearchInput, } from './tools/kg.js';
 import { askDql, askDqlInput, buildDqlApp, buildDqlAppInput, buildDqlBlock, buildDqlBlockInput, inspectDqlProject, inspectDqlProjectInput, } from './tools/workflows.js';
+import { approveHint, approveHintInput, listHints, listHintsInput, recordCorrection, recordCorrectionInput, } from './tools/hints.js';
+import { getTableSchema, getTableSchemaInput, searchMetadata, searchMetadataInput, validateSql, validateSqlInput, } from './tools/metadata.js';
 export const DQL_MCP_INSTRUCTIONS = 'DQL is a governed analytics MCP server. Start each session with ' +
     '`inspect_dql_project`; route every analytics question through `ask_dql` ' +
     'before writing SQL. It returns the safe route, trust label, certified ' +
@@ -25,11 +27,25 @@ export const DQL_MCP_INSTRUCTIONS = 'DQL is a governed analytics MCP server. Sta
     '`uncertified: true`, the trust status, and draft path verbatim.\n' +
     'Tier 3 missing context: if metadata does not identify a safe table, metric, ' +
     'dimension, or grain, refuse and ask for what is missing.\n' +
+    'Trust labels are one canonical vocabulary: Certified, Reviewed, ' +
+    'AI-Generated, Insufficient-Context, Conflict (a base label plus an optional ' +
+    'qualifier, e.g. "Certified · invariant violated"). Report the trust label ' +
+    'verbatim and never upgrade it.\n' +
+    'Conflict route: when two certified terms or blocks claim the same concept ' +
+    'but disagree, `ask_dql` returns route `conflict` with BOTH definitions and ' +
+    'owners. Present both sides and ask the user which is authoritative — never ' +
+    'silently pick one.\n' +
     'Use `build_dql_block` for reusable draft blocks, `build_dql_app` for app ' +
     'drafts with certified tiles plus review-only gaps, `certify` for governance, ' +
     '`lineage_impact` for dependencies, `kg_search` for the knowledge graph, and ' +
     '`feedback_record` for answer quality. Never present generated SQL or draft ' +
-    'output as certified.';
+    'output as certified.\n' +
+    'Correction memory: when an analyst corrects a Tier-2 answer, call ' +
+    '`record_correction` with the scope (metric/dbt model/domain/dialect). It ' +
+    'creates a scoped CANDIDATE hint that is NOT used until a human runs ' +
+    '`approve_hint`. Approved hints are folded into matching future Tier-2 drafts ' +
+    'AFTER certified routing (never overriding certified answers) and are cited. ' +
+    'Use `list_hints` to review pending corrections.';
 export function createDQLMCPServer(options = {}) {
     const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd());
     const ctx = new DQLContext({ projectRoot, dqlVersion: options.version });
@@ -57,7 +73,7 @@ export function createDQLMCPServer(options = {}) {
         inputSchema: queryViaBlockInput,
     }, async (args) => wrap(await queryViaBlock(ctx, args)));
     server.registerTool('query_via_metadata', {
-        description: 'Tier-2 of graduated trust. Use when no certified block exactly answers the requested grain, including why-changed diagnostics, named customer/user/account filters, rankings, breakdowns, comparisons, anomalies, and drill-throughs. Call inspect_metadata_context first; pass its contextPackId when available. If proposedSql is omitted, this returns the catalog route plan, allowed SQL context, and missing context. If proposedSql is supplied, it must be one read-only SELECT/WITH query using only inspected relations/columns. The runtime executes a bounded preview, returns `uncertified: true` plus trustStatus/evidence, and saves a draft block under the local draft queue. Surface the `uncertified` flag and review path verbatim.',
+        description: 'Tier-2 of graduated trust. Use when no certified block exactly answers the requested grain, including why-changed diagnostics, named customer/user/account filters, rankings, breakdowns, comparisons, anomalies, and drill-throughs. Call inspect_metadata_context first; pass its contextPackId when available. If proposedSql is omitted, this returns the catalog route plan, allowed SQL context, and missing context. When the question spans entities, the response also includes `datalexJoinGuidance` from the DataLex model: the canonical key to join each business concept on, and which joins fan out — follow it so generated SQL stays grain-safe (don\'t double-count). If proposedSql is supplied, it must be one read-only SELECT/WITH query using only inspected relations/columns. The runtime executes a bounded preview, returns `uncertified: true` plus trustStatus/evidence, and saves a draft block under the local draft queue. Surface the `uncertified` flag and review path verbatim.',
         inputSchema: queryViaMetadataInput,
     }, async (args) => wrap(await queryViaMetadata(ctx, args)));
     server.registerTool('list_proposals', {
@@ -73,11 +89,35 @@ export function createDQLMCPServer(options = {}) {
         inputSchema: suggestBlockInput,
     }, async (args) => wrap(await suggestBlock(ctx, args)));
     server.registerTool('kg_search', { description: 'Search the agent knowledge graph (FTS5) over terms, business views, blocks, metrics, dimensions, dashboards, apps, notebooks, and dbt/source metadata.', inputSchema: kgSearchInput }, async (args) => wrap(await kgSearch(ctx, args)));
+    server.registerTool('search_metadata', {
+        description: 'Grounded-SQL retrieval: rank dbt tables relevant to a request and return each table\'s fully-qualified warehouse relation (database.schema.table) and {{ ref() }} form. Use before writing SQL so you reference the REAL relation, never a bare model name.',
+        inputSchema: searchMetadataInput,
+    }, async (args) => wrap(await searchMetadata(ctx, args)));
+    server.registerTool('get_table_schema', {
+        description: 'Return the qualified relation, {{ ref() }} form, real columns + types, and inferred join keys for a dbt table (by model name, alias, or qualified relation).',
+        inputSchema: getTableSchemaInput,
+    }, async (args) => wrap(getTableSchema(ctx, args)));
+    server.registerTool('validate_sql', {
+        description: 'Validate that a read-only SELECT/WITH query references ONLY relations and columns that exist in the dbt schema. Returns the precise offending table/column on a miss so you can correct it.',
+        inputSchema: validateSqlInput,
+    }, async (args) => wrap(await validateSql(ctx, args)));
     server.registerTool('inspect_metadata_context', {
         description: 'Build the local SQLite metadata context pack for a question. Use before Tier-2 SQL generation to inspect certified blocks, semantic metrics, DQL terms/views, dbt/warehouse objects, lineage edges, diagnostics, selected evidence, rejected candidates, and trust labels.',
         inputSchema: inspectMetadataContextInput,
     }, async (args) => wrap(await inspectMetadataContext(ctx, args)));
     server.registerTool('feedback_record', { description: 'Record thumbs-up/down feedback on an answer; feeds self-learning + promotion suggestions.', inputSchema: feedbackRecordInput }, async (args) => wrap(feedbackRecord(ctx, args)));
+    server.registerTool('record_correction', {
+        description: 'Capture an analyst correction of a Tier-2 generated answer as a scoped, Git-versioned CANDIDATE hint (not used until approved). Writes a trace + hint under .dql/ and reindexes the local cache.',
+        inputSchema: recordCorrectionInput,
+    }, async (args) => wrap(recordCorrection(ctx, args)));
+    server.registerTool('approve_hint', {
+        description: 'Human review of a candidate correction hint. Approving makes the scoped hint usable in future Tier-2 drafts (after certified routing, never overriding it). Updates .dql/ and the local index.',
+        inputSchema: approveHintInput,
+    }, async (args) => wrap(approveHint(ctx, args)));
+    server.registerTool('list_hints', {
+        description: 'List scoped correction hints (optionally filtered by status/domain/metric) for review. Approved hints are the ones folded into future answers.',
+        inputSchema: listHintsInput,
+    }, async (args) => wrap(listHints(ctx, args)));
     return server;
 }
 function wrap(result) {

package/dist/server.js.map

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

package/dist/tools/hints.d.ts

@@ -0,0 +1,150 @@
+/**
+ * MCP tools for scoped correction memory ("mini Hint Graph").
+ *
+ * `record_correction` — capture a Tier-2 correction as a Git trace + candidate
+ *                       hint (NOT used until approved).
+ * `approve_hint`      — human review: approve/reject a candidate hint. Approval
+ *                       is the only path that makes a hint usable in retrieval.
+ * `list_hints`        — list hints (optionally filtered by status) for review.
+ *
+ * Source of truth is Git (`.dql/hints`, `.dql/traces`, `.dql/reviews`); SQLite
+ * (`.dql/cache/agent-kg.sqlite`) is reindexed automatically on every write.
+ */
+import { z } from 'zod';
+import type { DQLContext } from '../context.js';
+export declare const recordCorrectionInput: {
+    question: z.ZodString;
+    wrongAnswer: z.ZodString;
+    correction: z.ZodString;
+    scope: z.ZodObject<{
+        metric: z.ZodOptional<z.ZodString>;
+        dbtModel: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        dialect: z.ZodOptional<z.ZodString>;
+        term: z.ZodOptional<z.ZodString>;
+        block: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        term?: string | undefined;
+        block?: string | undefined;
+        metric?: string | undefined;
+        domain?: string | undefined;
+        dbtModel?: string | undefined;
+        dialect?: string | undefined;
+    }, {
+        term?: string | undefined;
+        block?: string | undefined;
+        metric?: string | undefined;
+        domain?: string | undefined;
+        dbtModel?: string | undefined;
+        dialect?: string | undefined;
+    }>;
+    rationale: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    correctedSql: z.ZodOptional<z.ZodString>;
+    hintTitle: z.ZodOptional<z.ZodString>;
+    hintGuidance: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    anchorObjectKey: z.ZodOptional<z.ZodString>;
+};
+export declare function recordCorrection(ctx: DQLContext, args: {
+    question: string;
+    wrongAnswer: string;
+    correction: string;
+    scope: {
+        metric?: string;
+        dbtModel?: string;
+        domain?: string;
+        dialect?: string;
+        term?: string;
+        block?: string;
+    };
+    rationale?: string;
+    author?: string;
+    correctedSql?: string;
+    hintTitle?: string;
+    hintGuidance?: string;
+    tags?: string[];
+    anchorObjectKey?: string;
+}): {
+    ok: boolean;
+    traceId: string;
+    hintId: string;
+    status: import("@duckcodeailabs/dql-agent").HintStatus;
+    note: string;
+    hint: {
+        id: string;
+        title: string;
+        status: import("@duckcodeailabs/dql-agent").HintStatus;
+        guidance: string;
+        scope: import("@duckcodeailabs/dql-agent").HintScope;
+        correctedSql: string | undefined;
+        traceId: string | undefined;
+        author: string | undefined;
+        reviewer: string | undefined;
+        updatedAt: string;
+    };
+};
+export declare const approveHintInput: {
+    hintId: z.ZodString;
+    decision: z.ZodEnum<["approved", "rejected"]>;
+    reviewer: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+};
+export declare function approveHint(ctx: DQLContext, args: {
+    hintId: string;
+    decision: 'approved' | 'rejected';
+    reviewer: string;
+    note?: string;
+}): {
+    ok: boolean;
+    error: string;
+    hintId?: undefined;
+    status?: undefined;
+    reviewId?: undefined;
+    note?: undefined;
+    hint?: undefined;
+} | {
+    ok: boolean;
+    hintId: string;
+    status: import("@duckcodeailabs/dql-agent").HintStatus;
+    reviewId: string;
+    note: string;
+    hint: {
+        id: string;
+        title: string;
+        status: import("@duckcodeailabs/dql-agent").HintStatus;
+        guidance: string;
+        scope: import("@duckcodeailabs/dql-agent").HintScope;
+        correctedSql: string | undefined;
+        traceId: string | undefined;
+        author: string | undefined;
+        reviewer: string | undefined;
+        updatedAt: string;
+    };
+    error?: undefined;
+};
+export declare const listHintsInput: {
+    status: z.ZodOptional<z.ZodEnum<["candidate", "approved", "rejected"]>>;
+    domain: z.ZodOptional<z.ZodString>;
+    metric: z.ZodOptional<z.ZodString>;
+};
+export declare function listHints(ctx: DQLContext, args: {
+    status?: 'candidate' | 'approved' | 'rejected';
+    domain?: string;
+    metric?: string;
+}): {
+    count: number;
+    hints: {
+        id: string;
+        title: string;
+        status: import("@duckcodeailabs/dql-agent").HintStatus;
+        guidance: string;
+        scope: import("@duckcodeailabs/dql-agent").HintScope;
+        correctedSql: string | undefined;
+        traceId: string | undefined;
+        author: string | undefined;
+        reviewer: string | undefined;
+        updatedAt: string;
+    }[];
+};
+//# sourceMappingURL=hints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hints.d.ts","sourceRoot":"","sources":["../../src/tools/hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAkBhD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYjC,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;;;;;;;;;;;;;;;;;;EAyBF;AAED,eAAO,MAAM,gBAAgB;;;;;CAK5B,CAAC;AAEF,wBAAgB,WAAW,CACzB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,GAAG,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B7F;AAED,eAAO,MAAM,cAAc;;;;CAI1B,CAAC;AAEF,wBAAgB,SAAS,CACvB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;EAU3F"}

package/dist/tools/hints.js

@@ -0,0 +1,128 @@
+/**
+ * MCP tools for scoped correction memory ("mini Hint Graph").
+ *
+ * `record_correction` — capture a Tier-2 correction as a Git trace + candidate
+ *                       hint (NOT used until approved).
+ * `approve_hint`      — human review: approve/reject a candidate hint. Approval
+ *                       is the only path that makes a hint usable in retrieval.
+ * `list_hints`        — list hints (optionally filtered by status) for review.
+ *
+ * Source of truth is Git (`.dql/hints`, `.dql/traces`, `.dql/reviews`); SQLite
+ * (`.dql/cache/agent-kg.sqlite`) is reindexed automatically on every write.
+ */
+import { z } from 'zod';
+import { getHintFromGit, listHintsFromGit, recordCorrectionTrace, reviewHint, } from '@duckcodeailabs/dql-agent';
+const scopeSchema = {
+    metric: z.string().optional().describe('Metric / KPI the hint is about, e.g. "revenue".'),
+    dbtModel: z.string().optional().describe('dbt model the hint is about, e.g. "fct_orders".'),
+    domain: z.string().optional().describe('Business domain, e.g. "growth".'),
+    dialect: z.string().optional().describe('Warehouse SQL dialect, e.g. "duckdb", "snowflake".'),
+    term: z.string().optional().describe('Business term the hint refines.'),
+    block: z.string().optional().describe('Certified block the hint relates to.'),
+};
+export const recordCorrectionInput = {
+    question: z.string().describe('The analyst question the Tier-2 answer was for.'),
+    wrongAnswer: z.string().describe('The generated answer/SQL that was wrong.'),
+    correction: z.string().describe('The analyst correction: corrected SQL, rule, or guidance.'),
+    scope: z.object(scopeSchema).describe('Scope the correction applies within. A hint only applies inside its scope.'),
+    rationale: z.string().optional().describe('Why the original answer was wrong.'),
+    author: z.string().optional().describe('Who recorded the correction.'),
+    correctedSql: z.string().optional().describe('Optional canonical corrected SQL to endorse.'),
+    hintTitle: z.string().optional().describe('Override the derived hint title.'),
+    hintGuidance: z.string().optional().describe('Override the hint guidance (defaults to the correction).'),
+    tags: z.array(z.string()).optional().describe('Searchable keywords.'),
+    anchorObjectKey: z.string().optional().describe('contextPackId / blockId the correction anchored to.'),
+};
+export function recordCorrection(ctx, args) {
+    const { trace, hint } = recordCorrectionTrace(ctx.projectRoot, {
+        question: args.question,
+        scope: args.scope,
+        wrongAnswer: args.wrongAnswer,
+        correction: args.correction,
+        rationale: args.rationale,
+        author: args.author,
+        correctedSql: args.correctedSql,
+        hintTitle: args.hintTitle,
+        hintGuidance: args.hintGuidance,
+        tags: args.tags,
+        anchorObjectKey: args.anchorObjectKey,
+    });
+    return {
+        ok: true,
+        traceId: trace.id,
+        hintId: hint.id,
+        status: hint.status,
+        note: 'Recorded as a CANDIDATE hint. It is NOT used in answers until approved via `approve_hint`. ' +
+            'Both the trace and hint are written under .dql/ and should be committed to Git.',
+        hint: summarizeHint(hint),
+    };
+}
+export const approveHintInput = {
+    hintId: z.string().describe('Id of the candidate hint to review.'),
+    decision: z.enum(['approved', 'rejected']).describe('Approve (usable in retrieval) or reject.'),
+    reviewer: z.string().describe('Who is reviewing.'),
+    note: z.string().optional().describe('Optional review note.'),
+};
+export function approveHint(ctx, args) {
+    const existing = getHintFromGit(ctx.projectRoot, args.hintId);
+    if (!existing) {
+        return { ok: false, error: `Hint ${args.hintId} not found under .dql/hints/.` };
+    }
+    const result = reviewHint(ctx.projectRoot, {
+        hintId: args.hintId,
+        decision: args.decision,
+        reviewer: args.reviewer,
+        note: args.note,
+    });
+    if (!result) {
+        return { ok: false, error: `Could not review hint ${args.hintId}.` };
+    }
+    return {
+        ok: true,
+        hintId: result.hint.id,
+        status: result.hint.status,
+        reviewId: result.review.id,
+        note: result.hint.status === 'approved'
+            ? 'Approved. This scoped hint will now be folded into matching Tier-2 drafts (after certified routing). Commit the updated .dql/ files to Git.'
+            : 'Rejected. This hint will not be used. Commit the updated .dql/ files to Git.',
+        hint: summarizeHint(result.hint),
+    };
+}
+export const listHintsInput = {
+    status: z.enum(['candidate', 'approved', 'rejected']).optional().describe('Filter by lifecycle status.'),
+    domain: z.string().optional().describe('Filter to a single domain scope.'),
+    metric: z.string().optional().describe('Filter to a single metric scope.'),
+};
+export function listHints(ctx, args) {
+    let hints = listHintsFromGit(ctx.projectRoot);
+    if (args.status)
+        hints = hints.filter((hint) => hint.status === args.status);
+    if (args.domain)
+        hints = hints.filter((hint) => eq(hint.scope.domain, args.domain));
+    if (args.metric)
+        hints = hints.filter((hint) => eq(hint.scope.metric, args.metric));
+    return {
+        count: hints.length,
+        hints: hints.map(summarizeHint),
+    };
+}
+function summarizeHint(hint) {
+    return {
+        id: hint.id,
+        title: hint.title,
+        status: hint.status,
+        guidance: hint.guidance,
+        scope: hint.scope,
+        correctedSql: hint.correctedSql,
+        traceId: hint.traceId,
+        author: hint.author,
+        reviewer: hint.reviewer,
+        updatedAt: hint.updatedAt,
+    };
+}
+function eq(a, b) {
+    if (a === undefined || b === undefined)
+        return false;
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+//# sourceMappingURL=hints.js.map

package/dist/tools/hints.js.map

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

package/dist/tools/lineage-impact.d.ts

@@ -5,11 +5,15 @@ export declare const lineageImpactInput: {
     upstreamDepth: z.ZodOptional<z.ZodNumber>;
     downstreamDepth: z.ZodOptional<z.ZodNumber>;
     paths: z.ZodOptional<z.ZodBoolean>;
+    recert: z.ZodOptional<z.ZodBoolean>;
+    nonSemantic: z.ZodOptional<z.ZodBoolean>;
 };
 export declare function lineageImpact(ctx: DQLContext, args: {
     focus: string;
     upstreamDepth?: number;
     downstreamDepth?: number;
     paths?: boolean;
+    recert?: boolean;
+    nonSemantic?: boolean;
 }): Record<string, unknown>;
 //# sourceMappingURL=lineage-impact.d.ts.map

package/dist/tools/lineage-impact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lineage-impact.d.ts","sourceRoot":"","sources":["../../src/tools/lineage-impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,eAAO,MAAM,kBAAkB;;;;;CAQ9B,CAAC;AAEF,wBAAgB,aAAa,CAC3B,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,2BA+BF"}
+{"version":3,"file":"lineage-impact.d.ts","sourceRoot":"","sources":["../../src/tools/lineage-impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,eAAO,MAAM,kBAAkB;;;;;;;CAuB9B,CAAC;AAEF,wBAAgB,aAAa,CAC3B,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,2BAyDF"}

package/dist/tools/lineage-impact.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { queryLineage, queryCompleteLineagePaths } from '@duckcodeailabs/dql-core';
+import { queryLineage, queryCompleteLineagePaths, computeImpact, } from '@duckcodeailabs/dql-core';
 export const lineageImpactInput = {
     focus: z.string().describe('Node id ("block:revenue") or bare name — resolved against the lineage graph.'),
     upstreamDepth: z.number().int().min(0).max(20).optional(),
@@ -8,6 +8,17 @@ export const lineageImpactInput = {
         .boolean()
         .optional()
         .describe('When true, include full source→leaf paths (slower on large graphs).'),
+    recert: z
+        .boolean()
+        .optional()
+        .describe('When true, treat `focus` as a changed block and return the re-cert impact: ' +
+        'full transitive downstream, invalidated cross-domain edges, domainTrust delta, ' +
+        'and the certified artifacts that require re-certification.'),
+    nonSemantic: z
+        .boolean()
+        .optional()
+        .describe('When true with `recert`, treats the change as non-semantic (description/comment/tag only) ' +
+        'so no re-cert is required. Default false (conservative: assume semantic).'),
 };
 export function lineageImpact(ctx, args) {
     const graph = ctx.lineageGraph;
@@ -34,6 +45,30 @@ export function lineageImpact(ctx, args) {
             response.layerSummary = paths.layerSummary;
         }
     }
+    // Re-cert impact: treat the focal block as changed and compute the
+    // downstream invalidation + required re-cert list. Mirrors the
+    // `dql diff --impact` CLI gate, surfaced structurally for agents.
+    if (args.recert) {
+        const blockName = result.focalNode.type === 'block'
+            ? result.focalNode.name
+            : result.focalNode.id.replace(/^block:/, '');
+        const changed = {
+            name: blockName,
+            verdict: args.nonSemantic ? 'non-semantic' : 'semantic',
+            changedFields: [],
+            structural: false,
+        };
+        const impact = computeImpact(graph, [changed]);
+        response.impact = {
+            changedBlocks: impact.changedBlocks,
+            semanticChanges: impact.semanticChanges,
+            downstream: impact.downstream,
+            crossDomainImpacts: impact.crossDomainImpacts,
+            requiresRecert: impact.requiresRecert,
+            domainTrustDelta: impact.domainTrustDelta,
+            hasCertifiedInvalidation: impact.hasCertifiedInvalidation,
+        };
+    }
     return response;
 }
 function formatPath(path) {

package/dist/tools/lineage-impact.js.map

@@ -1 +1 @@
-{"version":3,"file":"lineage-impact.js","sourceRoot":"","sources":["../../src/tools/lineage-impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAGnF,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8EAA8E,CAAC;IAC1G,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACzD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC3D,KAAK,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CAAC,qEAAqE,CAAC;CACnF,CAAC;AAEF,MAAM,UAAU,aAAa,CAC3B,GAAe,EACf,IAKC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC;IAC/B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE;QACjC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,oBAAoB,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,QAAQ,GAA4B;QACxC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM;QACpC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM;QACpC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK;KAC1B,CAAC;IAEF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACpE,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC7D,QAAQ,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACjE,QAAQ,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,UAAU,CAAC,IAAoF;IACtG,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QAC/D,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"lineage-impact.js","sourceRoot":"","sources":["../../src/tools/lineage-impact.ts"],"names":[],"mappings":"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"}

package/dist/tools/metadata.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Grounded-SQL metadata tools (spec 15.5) — thin wrappers over the dbt catalog
+ * + the shared sql-grounding so EXTERNAL agents look up the same context the
+ * notebook build path uses:
+ *
+ *   - `search_metadata`   — rank dbt tables relevant to a request, with their
+ *                           qualified relation + {{ ref() }} form.
+ *   - `get_table_schema`  — the qualified relation, {{ ref() }} form, real
+ *                           columns + types, and join keys for a table.
+ *   - `validate_sql`      — validate a SQL string references ONLY known
+ *                           relations/columns, returning the precise miss.
+ *
+ * All three load dbt artifacts read-only and never write. They degrade
+ * gracefully (a clear hint) when no dbt manifest is present.
+ */
+import { z } from 'zod';
+import type { DQLContext } from '../context.js';
+export declare const searchMetadataInput: {
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+};
+export declare function searchMetadata(ctx: DQLContext, args: {
+    query: string;
+    limit?: number;
+}): Promise<{
+    tables: never[];
+    hint: string;
+    total?: undefined;
+} | {
+    total: number;
+    tables: {
+        name: string;
+        qualifiedRelation: string;
+        refForm: string | null;
+        kind: "source" | "model";
+        columnCount: number;
+        certifiedBlock: boolean;
+    }[];
+    hint?: undefined;
+}>;
+export declare const getTableSchemaInput: {
+    table: z.ZodString;
+};
+export declare function getTableSchema(ctx: DQLContext, args: {
+    table: string;
+}): {
+    found: boolean;
+    hint: string;
+    name?: undefined;
+    qualifiedRelation?: undefined;
+    refForm?: undefined;
+    kind?: undefined;
+    certifiedBlock?: undefined;
+    columns?: undefined;
+    joinKeys?: undefined;
+} | {
+    found: boolean;
+    name: string;
+    qualifiedRelation: string;
+    refForm: string | null;
+    kind: "source" | "model";
+    certifiedBlock: boolean;
+    columns: {
+        name: string;
+        type: string | null;
+        description: string | null;
+    }[];
+    joinKeys: {
+        leftRelation: string;
+        leftColumn: string;
+        rightRelation: string;
+        rightColumn: string;
+        reason: string;
+    }[];
+    hint?: undefined;
+};
+export declare const validateSqlInput: {
+    sql: z.ZodString;
+    query: z.ZodOptional<z.ZodString>;
+};
+export declare function validateSql(ctx: DQLContext, args: {
+    sql: string;
+    query?: string;
+}): Promise<{
+    ok: boolean;
+    code: string;
+    error: string;
+    warnings: never[];
+    referencedRelations?: undefined;
+    offending?: undefined;
+} | {
+    ok: boolean;
+    warnings: string[];
+    referencedRelations: string[];
+    code?: undefined;
+    error?: undefined;
+    offending?: undefined;
+} | {
+    ok: boolean;
+    code: import("@duckcodeailabs/dql-agent").GroundingValidationCode;
+    error: string;
+    warnings: string[];
+    referencedRelations: string[];
+    offending: {
+        relation?: string;
+        column?: string;
+    } | null;
+}>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/tools/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAkBhD,eAAO,MAAM,mBAAmB;;;CAG/B,CAAC;AAEF,wBAAsB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;GAiB5F;AAID,eAAO,MAAM,mBAAmB;;CAE/B,CAAC;AAEF,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCtE;AAID,eAAO,MAAM,gBAAgB;;;CAM5B,CAAC;AAEF,wBAAsB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;GAqBvF"}