@duckcodeailabs/dql-agent 1.6.20 → 1.6.22

package/dist/metadata/identity.js

@@ -0,0 +1,147 @@
+/**
+ * Local OSS owner identity (spec 14, part C).
+ *
+ * A new DRAFT block must never be born with a "Missing owner" Certifier strike
+ * just because the OSS user never passed `--owner`. We resolve a sensible
+ * default owner ONCE and persist it, then stamp it across every draft-creating
+ * path (propose, generate, enrichment, /api/ai/build) when no explicit owner is
+ * supplied.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. Persisted owner — `dql.config.json` `identity.owner`, else `.dql/local`.
+ *   2. git `user.email` (project-local, then global).
+ *   3. `$USER` / `$USERNAME` / OS user — `<user>@local`.
+ *   4. `guest@local` (guaranteed non-empty fallback).
+ *
+ * This module is deterministic and offline — it never calls a provider. The git
+ * lookup is best-effort and degrades silently when git is absent or the repo has
+ * no configured email.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Where the resolved owner is cached when `dql.config.json` is unavailable. */
+const LOCAL_OWNER_PATH = ['.dql', 'local', 'owner'];
+function nonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** Read a persisted owner from `dql.config.json` `identity.owner`, else `.dql/local/owner`. */
+export function readPersistedOwner(projectRoot) {
+    const configPath = join(projectRoot, 'dql.config.json');
+    if (existsSync(configPath)) {
+        try {
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const owner = nonEmpty(typeof raw.identity?.owner === 'string' ? raw.identity.owner : undefined);
+            if (owner)
+                return owner;
+        }
+        catch {
+            // Malformed config is not fatal — fall through to the local cache.
+        }
+    }
+    const localPath = join(projectRoot, ...LOCAL_OWNER_PATH);
+    if (existsSync(localPath)) {
+        try {
+            return nonEmpty(readFileSync(localPath, 'utf-8'));
+        }
+        catch {
+            // Unreadable cache — fall through.
+        }
+    }
+    return undefined;
+}
+/** Best-effort git `user.email` (project-local first, then global). Never throws. */
+function gitUserEmail(projectRoot) {
+    const run = (args) => {
+        try {
+            const out = execFileSync('git', args, {
+                cwd: projectRoot,
+                encoding: 'utf-8',
+                timeout: 3000,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return nonEmpty(out);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return run(['config', 'user.email']) ?? run(['config', '--global', 'user.email']);
+}
+/** `$USER` / OS user → `<user>@local`, else undefined. */
+function osUserOwner() {
+    const fromEnv = nonEmpty(process.env.USER) ?? nonEmpty(process.env.USERNAME);
+    if (fromEnv)
+        return `${fromEnv}@local`;
+    try {
+        const name = nonEmpty(userInfo().username);
+        if (name)
+            return `${name}@local`;
+    }
+    catch {
+        // userInfo can throw on exotic platforms — ignore.
+    }
+    return undefined;
+}
+/**
+ * Persist the owner into `dql.config.json` `identity.owner` when the config
+ * exists; otherwise cache it under `.dql/local/owner`. Best-effort — a failure to
+ * persist never blocks the caller (the owner is still returned).
+ */
+export function persistOwner(projectRoot, owner) {
+    const value = nonEmpty(owner);
+    if (!value)
+        return;
+    const configPath = join(projectRoot, 'dql.config.json');
+    if (existsSync(configPath)) {
+        try {
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const identity = (raw.identity && typeof raw.identity === 'object'
+                ? raw.identity
+                : {});
+            if (identity.owner === value)
+                return; // already current — no rewrite.
+            identity.owner = value;
+            raw.identity = identity;
+            writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n', 'utf-8');
+            return;
+        }
+        catch {
+            // Fall through to the local cache when the config cannot be rewritten.
+        }
+    }
+    try {
+        const localPath = join(projectRoot, ...LOCAL_OWNER_PATH);
+        mkdirSync(dirname(localPath), { recursive: true });
+        writeFileSync(localPath, value + '\n', 'utf-8');
+    }
+    catch {
+        // Caching is advisory; a read-only filesystem must not break resolution.
+    }
+}
+/**
+ * Resolve the default local OSS owner. Always returns a non-empty string. When
+ * an explicit owner is given it wins (and is persisted); otherwise the first
+ * persisted/derived value is used and persisted for reuse.
+ */
+export function resolveLocalOwner(projectRoot, options = {}) {
+    const persist = options.persist !== false;
+    const explicit = nonEmpty(options.explicit);
+    if (explicit) {
+        if (persist)
+            persistOwner(projectRoot, explicit);
+        return explicit;
+    }
+    const persisted = readPersistedOwner(projectRoot);
+    if (persisted)
+        return persisted;
+    const resolved = gitUserEmail(projectRoot) ?? osUserOwner() ?? 'guest@local';
+    if (persist)
+        persistOwner(projectRoot, resolved);
+    return resolved;
+}
+//# sourceMappingURL=identity.js.map

package/dist/metadata/identity.js.map

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

package/dist/metadata/metric-match.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Semantic-metric matching (spec 17, part C).
+ *
+ * The answer-loop already has a `semantic_layer` tier in its route order
+ * (certified → business_context → semantic_layer → dbt_manifest → generated →
+ * refuse). The miss it fixes here: matching a clear metric question to a governed
+ * metric was purely string-based (FTS token overlap), so "what is our total
+ * revenue" did not connect to a revenue-family metric like `cumulative_revenue`,
+ * `food_revenue`, or `lifetime_spend` — no metric is literally named "revenue" —
+ * and the loop refused instead of routing to the semantic tier.
+ *
+ * `matchSemanticMetric` ranks candidate metric KG nodes against the question
+ * using:
+ *   - a synonym/family expansion of the question's measure terms (revenue ⇄
+ *     spend/sales/income/arr; orders ⇄ purchases; ...), and of each metric's
+ *     searchable text (name + synonyms + label + description + tags),
+ *   - lexical token overlap blended through the spec-11 `hybridRank`
+ *     (alpha defaults to 0 → pure lexical, offline-stable for tests),
+ *   - a strong boost when a measure FAMILY (e.g. "revenue") is shared between
+ *     the question and the metric, which is what makes "total revenue" reach the
+ *     revenue family even though the exact word never appears in a metric name.
+ *
+ * It returns the single best metric only when the score clears a confidence
+ * threshold, so genuinely ad-hoc questions ("median order value by region")
+ * still fall through to generated SQL, and questions with no measure at all
+ * still refuse honestly.
+ */
+import { type EmbeddingProvider } from '../embeddings/provider.js';
+import type { KGNode } from '../kg/types.js';
+/** The measure families a metric KG node resolves to (revenue, orders, ...). */
+export declare function metricFamilies(metric: KGNode): Set<string>;
+export interface MetricMatch {
+    metric: KGNode;
+    /** Blended relevance in [0, 1]. */
+    score: number;
+    /** The shared measure family that justified the match, if any. */
+    family?: string;
+}
+export interface MatchSemanticMetricOptions {
+    /**
+     * Confidence threshold. A match below this is treated as "no confident metric"
+     * so ad-hoc questions still fall through to generated SQL. Default 0.34.
+     */
+    threshold?: number;
+    /** Vector-similarity weight; 0 (default) = offline-stable pure lexical. */
+    alpha?: number;
+    provider?: EmbeddingProvider;
+}
+/**
+ * Pick the single best governed metric for a question, or `null` when no metric
+ * clears the confidence bar. Deterministic + offline by default (alpha=0).
+ *
+ * Scoring per candidate metric:
+ *   base   = lexical token overlap fraction (question content tokens present in
+ *            the metric's searchable text), in [0, 1]
+ *   family = +0.6 when the question and metric share a measure family
+ *   name   = +0.25 when a question content token appears in the metric NAME
+ *            (so "food revenue" prefers `food_revenue` over `drink_revenue`)
+ * The blended FTS score is fed to `hybridRank` so spec-11 embeddings can refine
+ * it when a provider/alpha is supplied.
+ */
+export declare function matchSemanticMetric(question: string, metrics: KGNode[], options?: MatchSemanticMetricOptions): Promise<MetricMatch | null>;
+/**
+ * Parse a metric KG node's governed definition: the aggregate `sql:` expression
+ * and its `table:` relation, stored on `llmContext`. Returns undefined when the
+ * `sql:` is not an aggregate expression (a bare metric-name reference) or there is
+ * no table — those are not directly executable.
+ */
+export declare function parseMetricDefinition(metric: KGNode): {
+    expr: string;
+    table: string;
+} | undefined;
+/**
+ * Deterministic, offline-safe governed SQL for a matched metric (spec 17, part C):
+ * a single read-only `SELECT <expr> AS <alias> FROM <table>` synthesised from the
+ * metric's governed definition. Returns undefined when the definition is too thin
+ * to execute, preserving honest refusal.
+ */
+export declare function metricToGovernedSql(metric: KGNode): string | undefined;
+/**
+ * Resolve a matched metric to executable governed SQL. dbt's semantic layer splits
+ * a metric from its measure: a derived MetricFlow metric (e.g. `revenue`, type=simple
+ * over measure `revenue`) carries no `table:`/`sql:` of its own — the aggregate lives
+ * on the backing measure node (`order_item.revenue` → `SUM(product_price)` over
+ * `order_items`). When the matched metric is itself synthesizable we use it directly;
+ * otherwise we fall back to a sibling whose LEAF name matches (`revenue` ⇒
+ * `<model>.revenue`). No fuzzy family guessing — precise resolution or nothing.
+ */
+export declare function resolveGovernedMetricSql(metric: KGNode, pool: KGNode[]): {
+    sql: string;
+    metric: KGNode;
+} | undefined;
+//# sourceMappingURL=metric-match.d.ts.map

package/dist/metadata/metric-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-match.d.ts","sourceRoot":"","sources":["../../src/metadata/metric-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAwC,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACzG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AA0F7C,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAE1D;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAyD7B;AAOD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMjG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,GACb;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAW7C"}

package/dist/metadata/metric-match.js

@@ -0,0 +1,233 @@
+/**
+ * Semantic-metric matching (spec 17, part C).
+ *
+ * The answer-loop already has a `semantic_layer` tier in its route order
+ * (certified → business_context → semantic_layer → dbt_manifest → generated →
+ * refuse). The miss it fixes here: matching a clear metric question to a governed
+ * metric was purely string-based (FTS token overlap), so "what is our total
+ * revenue" did not connect to a revenue-family metric like `cumulative_revenue`,
+ * `food_revenue`, or `lifetime_spend` — no metric is literally named "revenue" —
+ * and the loop refused instead of routing to the semantic tier.
+ *
+ * `matchSemanticMetric` ranks candidate metric KG nodes against the question
+ * using:
+ *   - a synonym/family expansion of the question's measure terms (revenue ⇄
+ *     spend/sales/income/arr; orders ⇄ purchases; ...), and of each metric's
+ *     searchable text (name + synonyms + label + description + tags),
+ *   - lexical token overlap blended through the spec-11 `hybridRank`
+ *     (alpha defaults to 0 → pure lexical, offline-stable for tests),
+ *   - a strong boost when a measure FAMILY (e.g. "revenue") is shared between
+ *     the question and the metric, which is what makes "total revenue" reach the
+ *     revenue family even though the exact word never appears in a metric name.
+ *
+ * It returns the single best metric only when the score clears a confidence
+ * threshold, so genuinely ad-hoc questions ("median order value by region")
+ * still fall through to generated SQL, and questions with no measure at all
+ * still refuse honestly.
+ */
+import { defaultEmbeddingProvider, hybridRank } from '../embeddings/provider.js';
+const TOKEN_RE = /[\p{L}\p{N}_]+/gu;
+/** Stopwords that should never count toward a measure/metric match. */
+const STOPWORDS = new Set([
+    'what', 'whats', 'is', 'are', 'was', 'were', 'the', 'a', 'an', 'our', 'my', 'we',
+    'of', 'for', 'in', 'on', 'to', 'by', 'and', 'or', 'show', 'me', 'give', 'tell',
+    'how', 'much', 'many', 'this', 'that', 'these', 'those', 'do', 'does', 'did',
+    'total', 'overall', 'current', 'all', 'per', 'each', 'value', 'amount', 'number',
+    'count', 'sum', 'average', 'avg', 'get', 'find', 'whole', 'entire',
+]);
+/**
+ * Measure synonym families. Each family maps a canonical measure to the set of
+ * words that signal it. A question and a metric "share a family" when any word
+ * from the question and any word from the metric resolve to the same family.
+ */
+const MEASURE_FAMILIES = {
+    revenue: ['revenue', 'revenues', 'sales', 'income', 'turnover', 'earnings', 'gmv', 'arr', 'mrr', 'bookings', 'topline'],
+    spend: ['spend', 'spending', 'spent', 'cost', 'costs', 'expense', 'expenses', 'cogs'],
+    profit: ['profit', 'profits', 'margin', 'margins', 'gross', 'net', 'ebitda'],
+    orders: ['order', 'orders', 'purchase', 'purchases', 'transaction', 'transactions', 'checkout', 'checkouts'],
+    customers: ['customer', 'customers', 'user', 'users', 'account', 'accounts', 'buyer', 'buyers', 'shopper', 'shoppers'],
+    churn: ['churn', 'churned', 'attrition', 'cancel', 'cancellation', 'cancellations', 'logo'],
+    retention: ['retention', 'retained', 'renewal', 'renewals'],
+    quantity: ['quantity', 'units', 'volume', 'qty'],
+    aov: ['aov', 'basket'],
+};
+/**
+ * Row/record-listing intent. A question asking to ENUMERATE rows or identifiers
+ * ("list the 5 most recent orders with their ids") is not a metric question even
+ * though it names a measure entity ("orders") — it wants raw rows, so it should
+ * fall through to grounded generated SQL, not a governed aggregate. Conservative:
+ * only the clearest listing signals, so true aggregate questions ("how many
+ * orders", "total revenue", "average order value") are never suppressed.
+ */
+const ROW_REQUEST_RE = /\b(list|listing|rows?|records?|individual|line[\s-]?items?|ids?)\b/i;
+const RECENCY_RE = /\b(most\s+recent|latest|newest|oldest|last\s+\d+)\b/i;
+function looksLikeRowRequest(question) {
+    return ROW_REQUEST_RE.test(question) || RECENCY_RE.test(question);
+}
+function tokenize(text) {
+    return (text.toLowerCase().match(TOKEN_RE) ?? []).filter((t) => t.length > 1);
+}
+/** Content tokens (stopwords stripped) used for measure/family signal. */
+function contentTokens(text) {
+    return tokenize(text).filter((t) => !STOPWORDS.has(t));
+}
+/** The measure families a set of words resolves to. */
+function familiesFor(words) {
+    const set = new Set(words);
+    const families = new Set();
+    for (const [family, members] of Object.entries(MEASURE_FAMILIES)) {
+        if (members.some((member) => set.has(member)))
+            families.add(family);
+    }
+    return families;
+}
+/** Searchable text for a metric KG node: name, synonyms, label, description, tags. */
+function metricSearchText(metric) {
+    return [
+        metric.name,
+        metric.name.replace(/[_.]+/g, ' '),
+        metric.description ?? '',
+        metric.llmContext ?? '',
+        ...(metric.tags ?? []),
+    ]
+        .filter(Boolean)
+        .join(' ');
+}
+/**
+ * Text used ONLY for measure-FAMILY detection: the metric's name + description +
+ * tags, but NOT its `llmContext`. The llmContext carries `table:`/`sql:` lines, so
+ * including it wrongly assigns a metric to the family of its backing TABLE (a
+ * `tax_paid` measure on the `orders` table would falsely read as the "orders"
+ * family). Family must reflect what the metric MEASURES, i.e. its name/label.
+ */
+function metricFamilyText(metric) {
+    return [metric.name, metric.name.replace(/[_.]+/g, ' '), metric.description ?? '', ...(metric.tags ?? [])]
+        .filter(Boolean)
+        .join(' ');
+}
+/** The measure families a metric KG node resolves to (revenue, orders, ...). */
+export function metricFamilies(metric) {
+    return familiesFor(contentTokens(metricFamilyText(metric)));
+}
+/**
+ * Pick the single best governed metric for a question, or `null` when no metric
+ * clears the confidence bar. Deterministic + offline by default (alpha=0).
+ *
+ * Scoring per candidate metric:
+ *   base   = lexical token overlap fraction (question content tokens present in
+ *            the metric's searchable text), in [0, 1]
+ *   family = +0.6 when the question and metric share a measure family
+ *   name   = +0.25 when a question content token appears in the metric NAME
+ *            (so "food revenue" prefers `food_revenue` over `drink_revenue`)
+ * The blended FTS score is fed to `hybridRank` so spec-11 embeddings can refine
+ * it when a provider/alpha is supplied.
+ */
+export async function matchSemanticMetric(question, metrics, options = {}) {
+    const candidates = metrics.filter((m) => m.kind === 'metric');
+    if (candidates.length === 0)
+        return null;
+    // A row/record-listing question wants raw rows, not a governed aggregate —
+    // let it fall through to grounded generated SQL even if it names a measure.
+    if (looksLikeRowRequest(question))
+        return null;
+    const threshold = options.threshold ?? 0.34;
+    const qContent = new Set(contentTokens(question));
+    if (qContent.size === 0)
+        return null;
+    const qFamilies = familiesFor(qContent);
+    // A measure question must carry at least one content word OR a measure family;
+    // a bare "what is this" carries neither and should not match a metric.
+    const items = candidates.map((metric) => {
+        const text = metricSearchText(metric).toLowerCase();
+        const nameTokens = new Set(tokenize(metric.name));
+        // Family is derived from the metric's name/label only (not its `table:`), so a
+        // measure is never mis-assigned to the family of the relation it sits on.
+        const metricFams = familiesFor(contentTokens(metricFamilyText(metric)));
+        let overlap = 0;
+        let nameHit = 0;
+        for (const token of qContent) {
+            if (text.includes(token))
+                overlap += 1;
+            if (nameTokens.has(token))
+                nameHit += 1;
+        }
+        const lexical = overlap / qContent.size;
+        // Fraction of question content tokens present in the metric NAME — this is
+        // what separates `food_revenue` from `cumulative_revenue` for "food revenue".
+        const nameFraction = nameHit / qContent.size;
+        let sharedFamily;
+        for (const family of qFamilies) {
+            if (metricFams.has(family)) {
+                sharedFamily = family;
+                break;
+            }
+        }
+        // Blend the signals on a fixed budget so no single component saturates the
+        // clamp and hides a more specific name match.
+        const familyBoost = sharedFamily ? 0.45 : 0;
+        const fts = clamp01(0.35 * lexical + familyBoost + 0.35 * nameFraction);
+        return { metric, text: metricSearchText(metric), ftsScore: fts, family: sharedFamily };
+    });
+    const ranked = await hybridRank(question, items.map((entry) => ({ item: entry, text: entry.text, ftsScore: entry.ftsScore })), { alpha: options.alpha ?? 0, provider: options.provider ?? (options.alpha ? defaultEmbeddingProvider() : undefined) });
+    const best = ranked[0];
+    if (!best || best.score < threshold)
+        return null;
+    return { metric: best.item.metric, score: best.score, family: best.item.family };
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * Parse a metric KG node's governed definition: the aggregate `sql:` expression
+ * and its `table:` relation, stored on `llmContext`. Returns undefined when the
+ * `sql:` is not an aggregate expression (a bare metric-name reference) or there is
+ * no table — those are not directly executable.
+ */
+export function parseMetricDefinition(metric) {
+    const context = metric.llmContext ?? '';
+    const expr = context.match(/(?:^|\n)\s*sql:\s*(.+?)\s*(?:\n|$)/i)?.[1]?.trim();
+    const table = context.match(/(?:^|\n)\s*table:\s*(.+?)\s*(?:\n|$)/i)?.[1]?.trim();
+    if (!expr || !table || !/[()]/.test(expr))
+        return undefined;
+    return { expr, table };
+}
+/**
+ * Deterministic, offline-safe governed SQL for a matched metric (spec 17, part C):
+ * a single read-only `SELECT <expr> AS <alias> FROM <table>` synthesised from the
+ * metric's governed definition. Returns undefined when the definition is too thin
+ * to execute, preserving honest refusal.
+ */
+export function metricToGovernedSql(metric) {
+    const def = parseMetricDefinition(metric);
+    if (!def)
+        return undefined;
+    const alias = metric.name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '') || 'metric_value';
+    return `SELECT ${def.expr} AS ${alias}\nFROM ${def.table}`;
+}
+/**
+ * Resolve a matched metric to executable governed SQL. dbt's semantic layer splits
+ * a metric from its measure: a derived MetricFlow metric (e.g. `revenue`, type=simple
+ * over measure `revenue`) carries no `table:`/`sql:` of its own — the aggregate lives
+ * on the backing measure node (`order_item.revenue` → `SUM(product_price)` over
+ * `order_items`). When the matched metric is itself synthesizable we use it directly;
+ * otherwise we fall back to a sibling whose LEAF name matches (`revenue` ⇒
+ * `<model>.revenue`). No fuzzy family guessing — precise resolution or nothing.
+ */
+export function resolveGovernedMetricSql(metric, pool) {
+    const direct = metricToGovernedSql(metric);
+    if (direct)
+        return { sql: direct, metric };
+    const leaf = metric.name.split('.').pop()?.toLowerCase();
+    if (!leaf)
+        return undefined;
+    const leafSibling = pool
+        .filter((node) => node.nodeId !== metric.nodeId && node.name.split('.').pop()?.toLowerCase() === leaf)
+        .sort((a, b) => a.name.length - b.name.length)
+        .find((node) => metricToGovernedSql(node));
+    if (leafSibling)
+        return { sql: metricToGovernedSql(leafSibling), metric: leafSibling };
+    return undefined;
+}
+//# sourceMappingURL=metric-match.js.map

package/dist/metadata/metric-match.js.map

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

package/dist/metadata/sql-grounding.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared SQL grounding (spec 15) — ONE grounding for BOTH the governed
+ * answer-loop and the AI build engine. There is no "weak path".
+ *
+ * The grounding takes dbt artifacts (+ an optional set of relevant model names)
+ * and produces, for each table:
+ *   - the REAL qualified warehouse relation (`database.schema.alias`, e.g.
+ *     `dev.order_items`) — never a bare model name,
+ *   - the `{{ ref('<model>') }}` form for governed BLOCK SQL,
+ *   - real columns + types (catalog.json preferred, manifest YAML fallback),
+ *   - JOIN KEYS inferred from dbt `depends_on` and shared `*_id` / `*_key`
+ *     columns,
+ *   - a `certifiedBlock` flag (reserved for callers that pass certified models).
+ *
+ * On top of the grounding sit two deterministic, offline-safe primitives the
+ * build path was missing:
+ *   - `resolveRelationsInSql` — rewrites any bare / unqualified table name to
+ *     its real qualified relation (model name OR alias → `db.schema.alias`),
+ *   - `validateSqlAgainstGrounding` — flags any table or column the generated
+ *     SQL references that is not in the grounding.
+ *
+ * Both are pure string/AST helpers so they work with no provider and never
+ * crash the offline path.
+ */
+import type { DbtArtifacts } from '../propose/dbt-artifacts.js';
+/** A single grounded table the model is allowed to reference. */
+export interface GroundedColumn {
+    name: string;
+    type?: string;
+    description?: string;
+}
+export interface GroundedTable {
+    /** Logical model / source name (what `{{ ref() }}` uses). */
+    name: string;
+    /** Real qualified warehouse relation, e.g. `dev.order_items`. */
+    qualifiedRelation: string;
+    /** `{{ ref('<model>') }}` (models) or `{{ source(...) }}` (sources) form. */
+    refForm?: string;
+    /** Resolved columns with types. */
+    columns: GroundedColumn[];
+    /** 'model' | 'source'. */
+    kind: 'model' | 'source';
+    /** dbt uniqueId (for join-key inference and citations). */
+    uniqueId: string;
+    /** True when this table is backed by a certified DQL block. */
+    certifiedBlock?: boolean;
+}
+/** A join key the model can use to connect two grounded relations. */
+export interface GroundedJoinKey {
+    leftRelation: string;
+    leftColumn: string;
+    rightRelation: string;
+    rightColumn: string;
+    reason: string;
+}
+export interface SchemaGrounding {
+    tables: GroundedTable[];
+    joinKeys: GroundedJoinKey[];
+    /** Lower-cased lookup: bare name / alias / qualified relation → GroundedTable. */
+    byKey: Map<string, GroundedTable>;
+}
+export interface BuildSchemaGroundingOptions {
+    /** Cap on tables included in the grounding (top-K from retrieval). */
+    limit?: number;
+    /** Model/relation names that are backed by certified DQL blocks. */
+    certifiedModelNames?: Iterable<string>;
+}
+/** Lower-cased keys a relation can be referenced by (qualified, last 2, bare). */
+export declare function relationKeys(relation: string): string[];
+/**
+ * Build the shared schema grounding for a set of dbt models (+ sources).
+ * `relevantModels`, when provided, restricts/orders the grounding to the
+ * retrieval-selected relations; otherwise all models are grounded (capped).
+ */
+export declare function buildSchemaGrounding(artifacts: DbtArtifacts | undefined, relevantModels?: Iterable<string> | undefined, options?: BuildSchemaGroundingOptions): SchemaGrounding;
+/** A pre-qualified runtime relation (the answer-loop's schema context shape). */
+export interface RuntimeRelationInput {
+    /** Already-qualified relation, e.g. `dev.order_items`. */
+    relation: string;
+    /** Bare table name. */
+    name?: string;
+    columns: Array<{
+        name: string;
+        type?: string;
+        description?: string;
+    }>;
+}
+/**
+ * Build a `SchemaGrounding` from already-qualified runtime relations (the
+ * answer-loop receives these from the host as `schemaContext` /
+ * `allowedSqlContext`, so the relations are already real warehouse relations).
+ * This lets the governed answer-loop reuse the SAME resolver + validator as the
+ * build path without re-reading dbt artifacts. No join-key inference here —
+ * the answer-loop already renders join paths from its context pack.
+ */
+export declare function buildGroundingFromRuntimeRelations(relations: RuntimeRelationInput[]): SchemaGrounding;
+export interface RelationResolution {
+    /** SQL with bare / unqualified table names rewritten to qualified relations. */
+    sql: string;
+    /** Each rewrite applied, e.g. order_items → dev.order_items. */
+    rewrites: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Deterministically rewrite any bare / unqualified table name in `FROM` /
+ * `JOIN` clauses to its real qualified relation from the grounding. Maps both
+ * the model name and its alias to `database.schema.alias`. Already-qualified
+ * relations that match the grounding are left untouched.
+ *
+ * For BLOCK SQL the caller may request the `{{ ref() }}` form instead of the
+ * qualified relation via `prefer: 'ref'`.
+ */
+export declare function resolveRelationsInSql(sql: string, grounding: SchemaGrounding, options?: {
+    prefer?: 'qualified' | 'ref';
+}): RelationResolution;
+export type GroundingValidationCode = 'unknown_relation' | 'unknown_column' | 'unsafe_sql' | 'unparseable';
+export type GroundingValidationResult = {
+    ok: true;
+    warnings: string[];
+    referencedRelations: string[];
+} | {
+    ok: false;
+    code: GroundingValidationCode;
+    error: string;
+    warnings: string[];
+    referencedRelations: string[];
+    /** The specific table/column that failed, for a targeted repair re-prompt. */
+    offending?: {
+        relation?: string;
+        column?: string;
+    };
+};
+/**
+ * Validate that generated SQL references ONLY relations and columns present in
+ * the shared grounding. Read-only safety is enforced too (no DML/DDL). Returns
+ * a precise `offending` token so the build path can re-prompt the model with
+ * the exact miss.
+ */
+export declare function validateSqlAgainstGrounding(sql: string, grounding: SchemaGrounding): GroundingValidationResult;
+/**
+ * Render the grounding as a prompt block. Each table is presented as BOTH its
+ * qualified relation AND its `{{ ref() }}` form with real columns+types, plus
+ * the inferred join keys. The convention line tells the model how to reference
+ * relations for the given target (CELL → qualified; BLOCK → `{{ ref() }}`).
+ */
+export declare function renderGroundingForPrompt(grounding: SchemaGrounding, target?: 'cell' | 'block' | 'answer'): string;
+//# sourceMappingURL=sql-grounding.d.ts.map

package/dist/metadata/sql-grounding.d.ts.map

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