@duckcodeailabs/dql-mcp 1.6.20 → 1.6.22

package/dist/tools/metadata.js

@@ -0,0 +1,122 @@
+/**
+ * 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 { resolveDbtManifestPath } from '@duckcodeailabs/dql-core';
+import { buildSchemaGrounding, loadDbtArtifacts, relationKeys, selectRelevantModels, validateSqlAgainstGrounding, } from '@duckcodeailabs/dql-agent';
+/** Load dbt artifacts for the project, or undefined when no manifest exists. */
+function loadArtifacts(ctx) {
+    const manifestPath = resolveDbtManifestPath(ctx.projectRoot);
+    if (!manifestPath)
+        return undefined;
+    try {
+        return loadDbtArtifacts(manifestPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+const NO_MANIFEST_HINT = 'No dbt manifest was found. Run `dbt compile`/`dbt build` (or `dql sync dbt`) so target/manifest.json exists.';
+// ─── search_metadata ──────────────────────────────────────────────────────────
+export const searchMetadataInput = {
+    query: z.string().describe('Natural-language request to find relevant tables for.'),
+    limit: z.number().int().min(1).max(40).optional().describe('Max tables to return (default 12).'),
+};
+export async function searchMetadata(ctx, args) {
+    const artifacts = loadArtifacts(ctx);
+    if (!artifacts)
+        return { tables: [], hint: NO_MANIFEST_HINT };
+    const topK = args.limit ?? 12;
+    const relevant = await selectRelevantModels(artifacts, args.query, { topK });
+    const grounding = buildSchemaGrounding(artifacts, relevant, { limit: topK });
+    return {
+        total: grounding.tables.length,
+        tables: grounding.tables.map((table) => ({
+            name: table.name,
+            qualifiedRelation: table.qualifiedRelation,
+            refForm: table.refForm ?? null,
+            kind: table.kind,
+            columnCount: table.columns.length,
+            certifiedBlock: table.certifiedBlock ?? false,
+        })),
+    };
+}
+// ─── get_table_schema ─────────────────────────────────────────────────────────
+export const getTableSchemaInput = {
+    table: z.string().describe('Model name, alias, or qualified relation (e.g. order_items or dev.order_items).'),
+};
+export function getTableSchema(ctx, args) {
+    const artifacts = loadArtifacts(ctx);
+    if (!artifacts)
+        return { found: false, hint: NO_MANIFEST_HINT };
+    // Ground the whole project so we can look up any relation and surface joins.
+    const grounding = buildSchemaGrounding(artifacts, undefined, { limit: 500 });
+    const keys = relationKeys(args.table);
+    const table = keys.map((key) => grounding.byKey.get(key)).find(Boolean);
+    if (!table) {
+        return {
+            found: false,
+            hint: `Table "${args.table}" was not found. Use search_metadata to discover available relations.`,
+        };
+    }
+    const joinKeys = grounding.joinKeys.filter((join) => join.leftRelation === table.qualifiedRelation || join.rightRelation === table.qualifiedRelation);
+    return {
+        found: true,
+        name: table.name,
+        qualifiedRelation: table.qualifiedRelation,
+        refForm: table.refForm ?? null,
+        kind: table.kind,
+        certifiedBlock: table.certifiedBlock ?? false,
+        columns: table.columns.map((column) => ({ name: column.name, type: column.type ?? null, description: column.description ?? null })),
+        joinKeys: joinKeys.map((join) => ({
+            leftRelation: join.leftRelation,
+            leftColumn: join.leftColumn,
+            rightRelation: join.rightRelation,
+            rightColumn: join.rightColumn,
+            reason: join.reason,
+        })),
+    };
+}
+// ─── validate_sql ─────────────────────────────────────────────────────────────
+export const validateSqlInput = {
+    sql: z.string().describe('A read-only SELECT/WITH query to validate against the dbt schema.'),
+    query: z
+        .string()
+        .optional()
+        .describe('Optional original request, used to scope the grounding to relevant tables.'),
+};
+export async function validateSql(ctx, args) {
+    const artifacts = loadArtifacts(ctx);
+    if (!artifacts) {
+        return { ok: false, code: 'no_schema', error: NO_MANIFEST_HINT, warnings: [] };
+    }
+    // Ground broadly (so a valid table is never wrongly flagged), optionally
+    // ordered by the original request.
+    const relevant = args.query ? await selectRelevantModels(artifacts, args.query, { topK: 500 }) : undefined;
+    const grounding = buildSchemaGrounding(artifacts, relevant, { limit: 500 });
+    const result = validateSqlAgainstGrounding(args.sql, grounding);
+    if (result.ok) {
+        return { ok: true, warnings: result.warnings, referencedRelations: result.referencedRelations };
+    }
+    return {
+        ok: false,
+        code: result.code,
+        error: result.error,
+        warnings: result.warnings,
+        referencedRelations: result.referencedRelations,
+        offending: result.offending ?? null,
+    };
+}
+//# sourceMappingURL=metadata.js.map

package/dist/tools/metadata.js.map

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

package/dist/tools/query-via-block.d.ts

@@ -1,8 +1,10 @@
 import { z } from 'zod';
+import type { InvariantResult } from '@duckcodeailabs/dql-governance';
 import type { DQLContext } from '../context.js';
 export declare const queryViaBlockInput: {
     name: z.ZodString;
     limit: z.ZodOptional<z.ZodNumber>;
+    question: z.ZodOptional<z.ZodString>;
     serverUrl: z.ZodOptional<z.ZodString>;
 };
 /**
@@ -13,18 +15,22 @@ export declare const queryViaBlockInput: {
 export declare function queryViaBlock(ctx: DQLContext, args: {
     name: string;
     limit?: number;
+    question?: string;
     serverUrl?: string;
 }): Promise<{
     error: string;
-    block?: undefined;
-    blockPath?: undefined;
-    rowCount?: undefined;
-    durationMs?: undefined;
-    columns?: undefined;
-    rows?: undefined;
+    routeReason?: undefined;
+    grainGate?: undefined;
+} | {
+    error: string;
+    routeReason: string;
+    grainGate: {
+        allow: false;
+        kind: import("@duckcodeailabs/dql-agent").GrainGateKind;
+        requestedGrain: string;
+        blockGrain: string;
+    };
 } | {
-    block: string;
-    blockPath: string;
     rowCount: number;
     durationMs: number | null;
     columns: {
@@ -32,6 +38,15 @@ export declare function queryViaBlock(ctx: DQLContext, args: {
         type?: string;
     }[];
     rows: unknown[];
+    invariantResults?: InvariantResult[] | undefined;
+    dataStateDetail?: string | undefined;
+    block: string;
+    blockPath: string;
+    trustLabel: string;
+    invariantViolation: boolean;
+    dataState: "fresh" | "stale" | "failed" | "unknown";
     error?: undefined;
+    routeReason?: undefined;
+    grainGate?: undefined;
 }>;
 //# sourceMappingURL=query-via-block.d.ts.map

package/dist/tools/query-via-block.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-via-block.d.ts","sourceRoot":"","sources":["../../src/tools/query-via-block.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,eAAO,MAAM,kBAAkB;;;;CAS9B,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;cA+D9B,MAAM;eAAS,MAAM;;;;GAiBlD"}
+{"version":3,"file":"query-via-block.d.ts","sourceRoot":"","sources":["../../src/tools/query-via-block.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAYtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,eAAO,MAAM,kBAAkB;;;;;CAe9B,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;cAuFjD,MAAM;eAAS,MAAM;;;;;;;;;;;;;GAmDlD"}

package/dist/tools/query-via-block.js

@@ -1,9 +1,15 @@
 import { z } from 'zod';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { buildAnalysisQuestionPlan, grainMatches, requestedGrainFromPlan, } from '@duckcodeailabs/dql-agent';
+import { composeEffectiveTrust, TRUST_QUALIFIER_INVARIANT_VIOLATED, } from '@duckcodeailabs/dql-core';
 export const queryViaBlockInput = {
     name: z.string().describe('Certified block to execute.'),
     limit: z.number().int().min(1).max(10000).optional().describe('Max rows to return.'),
+    question: z
+        .string()
+        .optional()
+        .describe('Original question this block is being served for. When provided, query_via_block re-checks the block grain against the requested grain (defense in depth) and refuses on a genuine grain mismatch.'),
     serverUrl: z
         .string()
         .optional()
@@ -23,6 +29,29 @@ export async function queryViaBlock(ctx, args) {
             error: `Block "${args.name}" is "${block.status ?? 'draft'}" — only certified blocks can be executed via MCP.`,
         };
     }
+    // Grain-gate defense in depth. When a question is provided, re-run the same
+    // grain check the router uses before serving this certified block. A genuine
+    // grain/entity mismatch is refused here even if the tool was called directly,
+    // so a near-miss certified block can never be served as a confidently-wrong
+    // governed answer. Behavior is unchanged when no question is supplied or when
+    // the block / question carries no clearly-extractable grain.
+    if (args.question) {
+        const plan = buildAnalysisQuestionPlan(args.question);
+        const requestedGrain = requestedGrainFromPlan(plan);
+        const gate = grainMatches(blockToGrainObject(block), requestedGrain);
+        if (!gate.allow) {
+            return {
+                error: `Block "${args.name}" failed the grain gate: ${gate.reason}. Refusing to serve a near-miss certified answer; generate SQL for the requested grain instead.`,
+                routeReason: gate.reason,
+                grainGate: {
+                    allow: gate.allow,
+                    kind: gate.kind,
+                    requestedGrain: gate.requestedGrainLabel,
+                    blockGrain: gate.blockGrainLabel,
+                },
+            };
+        }
+    }
     // v1.6 — DataLex contract enforcement (the wedge).
     // When a certified block declares datalex_contract, refuse the call if
     // the reference doesn't resolve in the project's loaded DataLex
@@ -76,13 +105,60 @@ export async function queryViaBlock(ctx, args) {
     if (payload.error)
         return { error: payload.error };
     const rows = payload.result?.rows ?? [];
+    // Invariant enforcement: the runtime evaluates the block's declared
+    // invariants against this run's result. A real violation downgrades the
+    // trust label even though the block is certified — "certified" means the
+    // logic was reviewed, not that today's data honors every stated guarantee.
+    const invariantResults = payload.invariantResults ?? [];
+    const invariantViolation = Boolean(payload.invariantViolation);
+    const declaredInvariants = block.invariants ?? [];
+    // Freshness-aware trust: "certified" is the logic axis; the data axis is the
+    // health of the block's upstream dbt models (last-run status + freshness),
+    // computed at build time into `block.dataState`. A certified block whose
+    // upstream failed/is stale is downgraded to "Certified · upstream failed" /
+    // "Certified · stale data". An invariant violation is a stronger signal, so
+    // it keeps the qualifier slot when both apply (composeEffectiveTrust honors
+    // the existing qualifier first). Missing run_results → undefined dataState →
+    // plain "Certified" (backward compatible).
+    const dataState = block.dataState;
+    const effectiveTrust = composeEffectiveTrust({
+        id: 'certified',
+        dataState,
+        existingQualifier: invariantViolation ? TRUST_QUALIFIER_INVARIANT_VIOLATED : undefined,
+    });
     return {
         block: args.name,
         blockPath: block.filePath,
+        trustLabel: effectiveTrust.display,
+        invariantViolation,
+        dataState: dataState ?? 'unknown',
+        ...(block.dataStateDetail
+            ? { dataStateDetail: block.dataStateDetail }
+            : {}),
+        ...(declaredInvariants.length > 0 || invariantResults.length > 0
+            ? { invariantResults }
+            : {}),
         rowCount: rows.length,
         durationMs: payload.result?.executionTime ?? null,
         columns: payload.result?.columns ?? [],
         rows: args.limit ? rows.slice(0, args.limit) : rows,
     };
 }
+/**
+ * Adapt a manifest block into the minimal `MetadataObject` shape the grain gate
+ * reads (it only inspects `payload.grain`, `payload.declaredOutputs`, and
+ * `payload.entities`).
+ */
+function blockToGrainObject(block) {
+    return {
+        objectKey: `dql:block:${block.name}`,
+        objectType: 'dql_block',
+        name: block.name,
+        payload: {
+            grain: block.grain,
+            declaredOutputs: block.declaredOutputs ?? [],
+            entities: block.entities ?? [],
+        },
+    };
+}
 //# sourceMappingURL=query-via-block.js.map

package/dist/tools/query-via-block.js.map

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

package/dist/tools/query-via-metadata.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { DQLContext } from '../context.js';
 import { type LocalContextPack } from '@duckcodeailabs/dql-agent';
+import type { DataLexConformance, DataLexRelationship, JoinPathResolution } from '@duckcodeailabs/dql-core';
 export declare const queryViaMetadataInput: {
     question: z.ZodString;
     proposedSql: z.ZodOptional<z.ZodString>;
@@ -70,6 +71,7 @@ export declare function queryViaMetadata(ctx: DQLContext, args: {
     reviewStatus: string;
     planningOnly: boolean;
     contextPack: LocalContextPack | undefined;
+    datalexJoinGuidance: DataLexJoinGuidance | undefined;
     routeDecision: import("@duckcodeailabs/dql-agent").MetadataRouteDecision | undefined;
     allowedSqlContext: import("@duckcodeailabs/dql-agent").MetadataAllowedSqlContext | undefined;
     selectedRelations: {
@@ -257,6 +259,7 @@ export declare function queryViaMetadata(ctx: DQLContext, args: {
     proposedSql: string;
     draftBlock: undefined;
     planningOnly?: undefined;
+    datalexJoinGuidance?: undefined;
     routeDecision?: undefined;
     allowedSqlContext?: undefined;
     selectedRelations?: undefined;
@@ -348,6 +351,7 @@ export declare function queryViaMetadata(ctx: DQLContext, args: {
         assumptions: string[];
     };
     contextPack: LocalContextPack | undefined;
+    datalexJoinGuidance: DataLexJoinGuidance | undefined;
     reason: string;
     proposedSql: string;
     draftBlock: {
@@ -457,6 +461,7 @@ export declare function queryViaMetadata(ctx: DQLContext, args: {
     validationWarnings: string[];
     reviewStatus?: undefined;
     planningOnly?: undefined;
+    datalexJoinGuidance?: undefined;
     routeDecision?: undefined;
     allowedSqlContext?: undefined;
     selectedRelations?: undefined;
@@ -550,6 +555,7 @@ export declare function queryViaMetadata(ctx: DQLContext, args: {
         assumptions: string[];
     };
     contextPack: LocalContextPack | undefined;
+    datalexJoinGuidance: DataLexJoinGuidance | undefined;
     reason: string;
     question: string;
     rowCount: number;
@@ -577,6 +583,54 @@ export declare function queryViaMetadata(ctx: DQLContext, args: {
     errorCode?: undefined;
     error?: undefined;
 }>;
+export interface DataLexJoinGuidance {
+    source: 'datalex_manifest';
+    note: string;
+    entities: Array<{
+        concept: string;
+        domain?: string;
+        canonicalKey?: string[];
+        physical: string[];
+    }>;
+    joins: Array<{
+        from: string;
+        to: string;
+        on?: string;
+        cardinality?: string;
+        fansOut: boolean;
+        guidance: string;
+    }>;
+    unresolved?: Array<{
+        from: string;
+        to: string;
+        reason: string;
+        message: string;
+    }>;
+}
+interface JoinGuidanceRegistry {
+    conformance(): DataLexConformance[];
+    relationships(): DataLexRelationship[];
+    joinPath(base: string, target: string, opts?: {
+        baseDomain?: string;
+        targetDomain?: string;
+    }): JoinPathResolution;
+}
+/**
+ * Build grain-safe join guidance from the DataLex manifest for the entities a
+ * Tier-2 question touches. This is what turns conformance + typed relationships
+ * into something the agent can act on BEFORE it writes SQL: the canonical key to
+ * join each business concept on, and — for each pair — whether joining one onto
+ * the other fans out (and therefore needs aggregation to stay grain-safe).
+ *
+ * `refs` are the tables/entities the agent thinks are involved; physical model
+ * names (`dim_customer`), physical entity names (`DimCustomer`), and concept
+ * names (`Customer`) all resolve. With none resolved we surface the whole
+ * (small) conformance map so the agent still sees the modeled joins.
+ *
+ * Returns undefined when no DataLex manifest is loaded — Tier-2 must keep working
+ * for projects that never adopted DataLex (graduated trust).
+ */
+export declare function buildDataLexJoinGuidance(registry: JoinGuidanceRegistry, refs: string[]): DataLexJoinGuidance | undefined;
 type MetadataResearchIntent = 'diagnose_change' | 'driver_breakdown' | 'segment_compare' | 'entity_drilldown' | 'anomaly_investigation' | 'trust_gap_review';
 type MetadataFollowUpContext = {
     kind: 'generic' | 'drilldown';

package/dist/tools/query-via-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-via-metadata.d.ts","sourceRoot":"","sources":["../../src/tools/query-via-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAEnC,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFjC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAsSsB,MAAM;4BAAc,MAAM;oCAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAAtD,MAAM;4BAAc,MAAM;oCAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAAtD,MAAM;4BAAc,MAAM;oCAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA5NrD,MAAM;oBAAc,MAAM;4BAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA4NvD,MAAM;4BAAc,MAAM;oCAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA5NrD,MAAM;oBAAc,MAAM;4BAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA4NvD,MAAM;4BAAc,MAAM;oCAAsB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cApIjD,MAAM;eAAS,MAAM;;;;;cAxFzB,MAAM;oBAAc,MAAM;4BAAsB,MAAM;;;;;;;;;;;;;GA+I/E;AAID,KAAK,sBAAsB,GACvB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,kBAAkB,GAClB,uBAAuB,GACvB,kBAAkB,CAAC;AAEvB,KAAK,uBAAuB,GAAG;IAC7B,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAwLF;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQnD"}
+{"version":3,"file":"query-via-metadata.d.ts","sourceRoot":"","sources":["../../src/tools/query-via-metadata.ts"],"names":[],"mappings":"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"}

package/dist/tools/query-via-metadata.js

@@ -89,6 +89,12 @@ export async function queryViaMetadata(ctx, args) {
     const intent = normalizeMetadataResearchIntent(args.intent, args.question);
     const contextPack = await buildTier2ContextPack(ctx.projectRoot, args.question, args.contextPackId, args.followUp);
     const hasInspectedContext = hasInspectedMetadataContext(contextPack);
+    // DataLex modeled join semantics (canonical keys + grain-safe orientation) for
+    // the entities this question touches. Undefined when no manifest is loaded.
+    const datalexJoinGuidance = buildDataLexJoinGuidance(ctx.datalexRegistry, [
+        ...(args.upstreamRefs ?? []),
+        ...(args.proposedEntity ? [args.proposedEntity] : []),
+    ]);
     const contextNeedsClarification = hasInspectedContext && contextPack?.routeDecision.route === 'clarify';
     if (contextNeedsClarification || !args.proposedSql?.trim()) {
         recordTier2QueryRun(ctx.projectRoot, {
@@ -104,6 +110,7 @@ export async function queryViaMetadata(ctx, args) {
             reviewStatus: 'none',
             planningOnly: true,
             contextPack,
+            datalexJoinGuidance,
             routeDecision: contextPack?.routeDecision,
             allowedSqlContext: contextPack?.allowedSqlContext,
             selectedRelations: contextPack?.retrievalDiagnostics.selectedRelations?.slice(0, 12) ?? [],
@@ -183,6 +190,7 @@ export async function queryViaMetadata(ctx, args) {
             trustStatus: metadataTrustStatus('draft_ready', intent, draftBlock, undefined, contextValidation.warnings),
             evidence: metadataEvidence(intent, args, { status: 'dry_run', draftBlock, validationWarnings: contextValidation.warnings }, contextPack),
             contextPack,
+            datalexJoinGuidance,
             reason: 'dryRun=true; SQL not executed. Returned proposal only.',
             proposedSql,
             draftBlock,
@@ -273,6 +281,7 @@ export async function queryViaMetadata(ctx, args) {
             validationWarnings: contextValidation.warnings,
         }, contextPack),
         contextPack,
+        datalexJoinGuidance,
         reason: 'no certified block matched the question; result derived from manifest + dbt schema',
         question: args.question,
         rowCount: rows.length,
@@ -287,6 +296,109 @@ export async function queryViaMetadata(ctx, args) {
             : undefined,
     };
 }
+/**
+ * Build grain-safe join guidance from the DataLex manifest for the entities a
+ * Tier-2 question touches. This is what turns conformance + typed relationships
+ * into something the agent can act on BEFORE it writes SQL: the canonical key to
+ * join each business concept on, and — for each pair — whether joining one onto
+ * the other fans out (and therefore needs aggregation to stay grain-safe).
+ *
+ * `refs` are the tables/entities the agent thinks are involved; physical model
+ * names (`dim_customer`), physical entity names (`DimCustomer`), and concept
+ * names (`Customer`) all resolve. With none resolved we surface the whole
+ * (small) conformance map so the agent still sees the modeled joins.
+ *
+ * Returns undefined when no DataLex manifest is loaded — Tier-2 must keep working
+ * for projects that never adopted DataLex (graduated trust).
+ */
+export function buildDataLexJoinGuidance(registry, refs) {
+    // Gate on conformance, NOT registry.isLoaded() — that's contracts-based, and a
+    // modeling-primary manifest carries conformance + relationships with zero
+    // contracts. No conformance (or no manifest) => no guidance; Tier-2 still runs.
+    const conformance = registry.conformance();
+    if (conformance.length === 0)
+        return undefined;
+    const conceptByKey = new Map();
+    for (const c of conformance) {
+        conceptByKey.set(c.concept.toLowerCase(), c);
+        for (const p of c.physical ?? []) {
+            if (p.entity)
+                conceptByKey.set(p.entity.toLowerCase(), c);
+            if (p.binding?.ref)
+                conceptByKey.set(p.binding.ref.toLowerCase(), c);
+        }
+    }
+    const involved = [];
+    const seen = new Set();
+    for (const ref of refs) {
+        const c = conceptByKey.get(String(ref ?? '').toLowerCase());
+        if (c && !seen.has(c.concept.toLowerCase())) {
+            seen.add(c.concept.toLowerCase());
+            involved.push(c);
+        }
+    }
+    // Scope to the involved concepts; with none resolved, fall back to the whole
+    // (bounded) conformance map so the agent still gets the modeled join keys.
+    const concepts = involved.length > 0 ? involved : conformance.slice(0, 12);
+    const entities = concepts.map((c) => ({
+        concept: c.concept,
+        domain: c.domain,
+        canonicalKey: c.canonical_key,
+        physical: (c.physical ?? [])
+            .map((p) => p.binding?.ref)
+            .filter((r) => Boolean(r)),
+    }));
+    const joins = [];
+    const unresolved = [];
+    for (let i = 0; i < concepts.length; i += 1) {
+        for (let j = i + 1; j < concepts.length; j += 1) {
+            const a = concepts[i];
+            const b = concepts[j];
+            let jp = registry.joinPath(a.concept, b.concept, {
+                baseDomain: a.domain,
+                targetDomain: b.domain,
+            });
+            // Prefer the non-fanning orientation (join the "one" side onto the "many"
+            // side, i.e. the dimension onto the fact) so the primary guidance is the
+            // grain-safe join; the fan-out direction is still called out in the text.
+            if (jp.ok && jp.fansOut) {
+                const flipped = registry.joinPath(b.concept, a.concept, {
+                    baseDomain: b.domain,
+                    targetDomain: a.domain,
+                });
+                if (flipped.ok && !flipped.fansOut)
+                    jp = flipped;
+            }
+            if (!jp.ok) {
+                if (jp.reason === 'ambiguous') {
+                    unresolved.push({ from: a.concept, to: b.concept, reason: jp.reason, message: jp.message });
+                }
+                // 'no_relationship' is expected for unrelated pairs — skip quietly.
+                continue;
+            }
+            const on = jp.base.column && jp.target.column
+                ? `${jp.base.entity}.${jp.base.column} = ${jp.target.entity}.${jp.target.column}`
+                : undefined;
+            joins.push({
+                from: jp.base.entity,
+                to: jp.target.entity,
+                on,
+                cardinality: jp.cardinality,
+                fansOut: jp.fansOut,
+                guidance: jp.fansOut
+                    ? `${jp.base.entity} ↔ ${jp.target.entity} is ${jp.cardinality}; either direction can multiply rows — aggregate to one grain (GROUP BY the canonical key) before joining.`
+                    : `Each ${jp.base.entity} has one ${jp.target.entity}: join ${jp.target.entity} onto ${jp.base.entity}${on ? ` on ${on}` : ''} without fan-out. Aggregating ${jp.base.entity} per ${jp.target.entity} fans out — GROUP BY the ${jp.target.entity} key.`,
+            });
+        }
+    }
+    return {
+        source: 'datalex_manifest',
+        note: 'Modeled join semantics from DataLex. Join each concept on its canonical key and respect fan-out to keep results grain-safe.',
+        entities,
+        joins: joins.slice(0, 25),
+        ...(unresolved.length > 0 ? { unresolved } : {}),
+    };
+}
 function normalizeMetadataResearchIntent(value, question) {
     if (value === 'diagnose_change'
         || value === 'driver_breakdown'