@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

package/dist/agentic/business-explanation.js

@@ -0,0 +1,130 @@
+/**
+ * Answering "what does this mean?" from governed metadata, without SQL.
+ *
+ * A definitional question — "what does the top_customers block measure?", "how
+ * is revenue defined here?" — is routed to `converse` today, which replies
+ * conversationally with NO governed evidence attached. So the product knows the
+ * answer (it has the description, the owner, the grain, the outputs, the
+ * certification status) and does not use it, which is the shape of the
+ * complaint that Ask AI cannot explain business context.
+ *
+ * This composes the explanation deterministically from what the catalog already
+ * holds. No provider, no warehouse: the facts are all in the object, and a model
+ * paraphrasing them can only add drift.
+ */
+const CERTIFIED_STATUSES = new Set(['certified', 'approved']);
+function stringField(payload, key) {
+    const value = payload?.[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function stringList(payload, key) {
+    const value = payload?.[key];
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        if (typeof entry === 'string')
+            return entry;
+        if (entry && typeof entry === 'object') {
+            const name = entry.name;
+            return typeof name === 'string' ? name : '';
+        }
+        return '';
+    })
+        .filter((entry) => Boolean(entry));
+}
+/** How a reader should weigh this object, in plain words. */
+function trustSentence(object) {
+    const status = object.status?.toLowerCase() ?? '';
+    if (CERTIFIED_STATUSES.has(status)) {
+        return object.owner
+            ? `It is certified and owned by ${object.owner}.`
+            : 'It is certified.';
+    }
+    if (status === 'draft')
+        return 'It is a draft — not certified, so treat the numbers as provisional.';
+    if (object.objectType.startsWith('dbt:') || object.objectType.startsWith('dbt_')) {
+        return 'This comes from the dbt project rather than a certified DQL block, so it describes the model, not an approved business definition.';
+    }
+    return status ? `Status: ${status}.` : 'It has no certification status recorded.';
+}
+/**
+ * Compose an explanation of one governed object.
+ *
+ * Returns `null` when there is nothing beyond a bare name to say. A confident
+ * paragraph assembled from an empty description is worse than falling through
+ * to the normal cascade: it reads like an answer and carries no information.
+ */
+export function explainObject(object) {
+    const parts = [];
+    const label = object.fullName ?? object.name;
+    const description = object.description?.trim();
+    const guidance = stringField(object.payload, 'llmContext');
+    if (!description && !guidance)
+        return null;
+    parts.push(`**${label}** — ${description ?? guidance}`);
+    const grain = stringField(object.payload, 'grain');
+    if (grain)
+        parts.push(`Reported at ${grain} grain.`);
+    const outputs = stringList(object.payload, 'declaredOutputs');
+    const resolvedOutputs = outputs.length > 0 ? outputs : stringList(object.payload, 'outputs');
+    if (resolvedOutputs.length > 0)
+        parts.push(`Returns: ${resolvedOutputs.join(', ')}.`);
+    const dimensions = stringList(object.payload, 'dimensions');
+    if (dimensions.length > 0)
+        parts.push(`Can be broken down by: ${dimensions.join(', ')}.`);
+    // Authored guidance is the one field written FOR a reader deciding whether to
+    // use this, so it earns its own line when a description already led.
+    if (description && guidance && guidance !== description)
+        parts.push(`When to use it: ${guidance}`);
+    if (object.domain)
+        parts.push(`Domain: ${object.domain}.`);
+    parts.push(trustSentence(object));
+    return {
+        text: parts.join('\n\n'),
+        citations: [object.objectKey],
+        governed: CERTIFIED_STATUSES.has(object.status?.toLowerCase() ?? ''),
+    };
+}
+/**
+ * Pick the object a definitional question is about, then explain it.
+ *
+ * Matching is by NAME MENTION, not relevance rank: "what does top_customers
+ * measure?" is asking about a specific artifact, and answering about a merely
+ * similar one would be a different question confidently answered. When nothing
+ * is named, return null and let the cascade run — guessing the subject of a
+ * definition is exactly the failure this is meant to avoid.
+ */
+export function composeBusinessExplanation(question, objects) {
+    const lower = question.toLowerCase();
+    const named = objects.filter((object) => {
+        for (const candidate of [object.name, object.fullName]) {
+            if (!candidate)
+                continue;
+            const bare = candidate.toLowerCase();
+            if (bare.length < 3)
+                continue;
+            if (lower.includes(bare))
+                return true;
+            const spaced = bare.replace(/[_.]+/g, ' ');
+            if (spaced.length > 3 && lower.includes(spaced))
+                return true;
+        }
+        return false;
+    });
+    if (named.length === 0)
+        return null;
+    // Prefer the most specific mention, then the most trustworthy artifact: a
+    // certified block explains a concept better than the raw dbt model beneath it.
+    const best = [...named].sort((left, right) => {
+        const leftName = (left.fullName ?? left.name).length;
+        const rightName = (right.fullName ?? right.name).length;
+        const leftCertified = CERTIFIED_STATUSES.has(left.status?.toLowerCase() ?? '') ? 1 : 0;
+        const rightCertified = CERTIFIED_STATUSES.has(right.status?.toLowerCase() ?? '') ? 1 : 0;
+        return rightCertified - leftCertified
+            || rightName - leftName
+            || left.objectKey.localeCompare(right.objectKey);
+    })[0];
+    return explainObject(best);
+}
+//# sourceMappingURL=business-explanation.js.map

package/dist/agentic/business-explanation.js.map

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

package/dist/agentic/identifier-ledger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The identifier ledger — provenance for every name that reaches executed SQL.
+ *
+ * A semantic-layer-mediated agent reached 94.15% on Spider2-snow where frontier
+ * models score 17–21% unaided, and the rule doing most of that work is not a
+ * better prompt: only identifiers LIFTED FROM A COMPILER OUTPUT may appear in
+ * executed SQL. Everything else is a guess wearing a plausible name.
+ *
+ * The static equivalent already exists — `validateSqlAgainstLocalContext` checks
+ * SQL against the context pack's allowed relations. The ledger is its dynamic
+ * half: inside a loop the set of PROVEN identifiers grows with every tool
+ * observation, so what counts as admissible at step 5 is not what it was at
+ * step 1.
+ *
+ * Division of labour, deliberately: the validator EXTRACTS references from SQL
+ * (it owns the dialect handling, CTE scoping, and alias resolution); the ledger
+ * only adjudicates where each reference came from. Re-implementing extraction
+ * here would fork a parser that has already absorbed a lot of hard-won cases.
+ */
+/** Where an identifier was proven. Ordered loosely by strength of evidence. */
+export type IdentifierSource = 'compiler' | 'preview' | 'schema_tool' | 'catalog';
+export interface AdmittedIdentifier {
+    identifier: string;
+    source: IdentifierSource;
+    /** The tool call / receipt that proves it, for the audit trail. */
+    receiptId: string;
+}
+export interface LedgerAdjudication {
+    ok: boolean;
+    /** References that no observation admitted. */
+    unadmitted: string[];
+    /**
+     * Closest admitted identifier per unadmitted reference. The dominant failure
+     * mode is a plausible-but-wrong column name, so handing the model the exact
+     * correction is worth far more than telling it that something was wrong.
+     */
+    nearest: Record<string, string>;
+}
+/** Damerau-Levenshtein distance, for "did you mean" corrections. */
+export declare function editDistance(left: string, right: string): number;
+export declare class IdentifierLedger {
+    private readonly admitted;
+    /**
+     * Record identifiers proven by one observation.
+     *
+     * Admission is append-only and always carries a receipt: an identifier with no
+     * traceable source is exactly what this class exists to keep out of SQL.
+     */
+    admit(source: IdentifierSource, identifiers: readonly string[], receiptId: string): void;
+    isAdmitted(identifier: string, options?: {
+        requireObserved?: boolean;
+    }): boolean;
+    size(): number;
+    entries(): AdmittedIdentifier[];
+    /** The closest admitted identifier, when one is close enough to suggest. */
+    nearestAdmitted(identifier: string): string | undefined;
+    /**
+     * Adjudicate the references a validator extracted from candidate SQL.
+     *
+     * Returns a report, never a throw: an unadmitted identifier is a correctable
+     * observation to feed back into the loop, not a terminal refusal. That
+     * distinction is the whole point — the old pipeline turned this into a
+     * `grounding_gap` and stopped.
+     */
+    adjudicate(references: {
+        relations?: readonly string[];
+        columns?: readonly string[];
+    }, options?: {
+        requireObserved?: boolean;
+    }): LedgerAdjudication;
+    /** One line of feedback the model can act on directly. */
+    static renderCorrection(adjudication: LedgerAdjudication): string | undefined;
+}
+//# sourceMappingURL=identifier-ledger.d.ts.map

package/dist/agentic/identifier-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier-ledger.d.ts","sourceRoot":"","sources":["../../src/agentic/identifier-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,SAAS,GACT,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,+CAA+C;IAC/C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAmBD,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBhE;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAaxF,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO;IAMpF,IAAI,IAAI,MAAM;IAId,OAAO,IAAI,kBAAkB,EAAE;IAI/B,4EAA4E;IAC5E,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAcvD;;;;;;;OAOG;IACH,UAAU,CACR,UAAU,EAAE;QAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAC1E,OAAO,GAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1C,kBAAkB;IAarB,0DAA0D;IAC1D,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS;CAS9E"}

package/dist/agentic/identifier-ledger.js

@@ -0,0 +1,151 @@
+/**
+ * The identifier ledger — provenance for every name that reaches executed SQL.
+ *
+ * A semantic-layer-mediated agent reached 94.15% on Spider2-snow where frontier
+ * models score 17–21% unaided, and the rule doing most of that work is not a
+ * better prompt: only identifiers LIFTED FROM A COMPILER OUTPUT may appear in
+ * executed SQL. Everything else is a guess wearing a plausible name.
+ *
+ * The static equivalent already exists — `validateSqlAgainstLocalContext` checks
+ * SQL against the context pack's allowed relations. The ledger is its dynamic
+ * half: inside a loop the set of PROVEN identifiers grows with every tool
+ * observation, so what counts as admissible at step 5 is not what it was at
+ * step 1.
+ *
+ * Division of labour, deliberately: the validator EXTRACTS references from SQL
+ * (it owns the dialect handling, CTE scoping, and alias resolution); the ledger
+ * only adjudicates where each reference came from. Re-implementing extraction
+ * here would fork a parser that has already absorbed a lot of hard-won cases.
+ */
+/** Case-insensitive qualified identity. Qualifiers remain part of authority. */
+function normalizeIdentifier(value) {
+    return value
+        .trim()
+        .split('.')
+        .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+        .filter(Boolean)
+        .join('.');
+}
+/** Last segment of a dotted identifier (`db.schema.orders` → `orders`). */
+function leafOf(value) {
+    const normalized = normalizeIdentifier(value);
+    const parts = normalized.split('.').filter(Boolean);
+    return parts[parts.length - 1] ?? normalized;
+}
+/** Damerau-Levenshtein distance, for "did you mean" corrections. */
+export function editDistance(left, right) {
+    if (left === right)
+        return 0;
+    const rows = left.length + 1;
+    const cols = right.length + 1;
+    const grid = Array.from({ length: rows }, () => new Array(cols).fill(0));
+    for (let i = 0; i < rows; i += 1)
+        grid[i][0] = i;
+    for (let j = 0; j < cols; j += 1)
+        grid[0][j] = j;
+    for (let i = 1; i < rows; i += 1) {
+        for (let j = 1; j < cols; j += 1) {
+            const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+            let best = Math.min(grid[i - 1][j] + 1, grid[i][j - 1] + 1, grid[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && left[i - 1] === right[j - 2] && left[i - 2] === right[j - 1]) {
+                best = Math.min(best, grid[i - 2][j - 2] + 1);
+            }
+            grid[i][j] = best;
+        }
+    }
+    return grid[rows - 1][cols - 1];
+}
+export class IdentifierLedger {
+    admitted = new Map();
+    /**
+     * Record identifiers proven by one observation.
+     *
+     * Admission is append-only and always carries a receipt: an identifier with no
+     * traceable source is exactly what this class exists to keep out of SQL.
+     */
+    admit(source, identifiers, receiptId) {
+        for (const raw of identifiers) {
+            if (!raw || typeof raw !== 'string')
+                continue;
+            const key = normalizeIdentifier(raw);
+            if (!key)
+                continue;
+            const existing = this.admitted.get(key);
+            // Keep the strongest provenance rather than the most recent one.
+            if (!existing || sourceRank(source) > sourceRank(existing.source)) {
+                this.admitted.set(key, { identifier: raw, source, receiptId });
+            }
+        }
+    }
+    isAdmitted(identifier, options = {}) {
+        const key = normalizeIdentifier(identifier);
+        const entry = this.admitted.get(key);
+        return Boolean(entry && (!options.requireObserved || entry.source !== 'catalog'));
+    }
+    size() {
+        return this.admitted.size;
+    }
+    entries() {
+        return [...this.admitted.values()];
+    }
+    /** The closest admitted identifier, when one is close enough to suggest. */
+    nearestAdmitted(identifier) {
+        const needle = leafOf(identifier);
+        let best;
+        for (const entry of this.admitted.values()) {
+            const distance = editDistance(needle, leafOf(entry.identifier));
+            if (!best || distance < best.distance)
+                best = { identifier: entry.identifier, distance };
+        }
+        if (!best)
+            return undefined;
+        // Only suggest a genuine near-miss. A distant "correction" reads as a
+        // confident wrong answer and sends the model further off course.
+        const tolerance = Math.max(2, Math.floor(needle.length / 3));
+        return best.distance <= tolerance ? best.identifier : undefined;
+    }
+    /**
+     * Adjudicate the references a validator extracted from candidate SQL.
+     *
+     * Returns a report, never a throw: an unadmitted identifier is a correctable
+     * observation to feed back into the loop, not a terminal refusal. That
+     * distinction is the whole point — the old pipeline turned this into a
+     * `grounding_gap` and stopped.
+     */
+    adjudicate(references, options = {}) {
+        const unadmitted = [];
+        const nearest = {};
+        for (const reference of [...(references.relations ?? []), ...(references.columns ?? [])]) {
+            if (!reference || this.isAdmitted(reference, options))
+                continue;
+            if (unadmitted.includes(reference))
+                continue;
+            unadmitted.push(reference);
+            const suggestion = this.nearestAdmitted(reference);
+            if (suggestion)
+                nearest[reference] = suggestion;
+        }
+        return { ok: unadmitted.length === 0, unadmitted, nearest };
+    }
+    /** One line of feedback the model can act on directly. */
+    static renderCorrection(adjudication) {
+        if (adjudication.ok)
+            return undefined;
+        const parts = adjudication.unadmitted.map((reference) => {
+            const suggestion = adjudication.nearest[reference];
+            return suggestion ? `${reference} (did you mean ${suggestion}?)` : reference;
+        });
+        return `These identifiers were never returned by a tool, so they cannot be executed: ${parts.join(', ')}. `
+            + 'Use only names that appeared in a compile, preview, or schema result.';
+    }
+}
+function sourceRank(source) {
+    switch (source) {
+        case 'compiler': return 4;
+        case 'preview': return 3;
+        case 'schema_tool': return 2;
+        case 'catalog': return 1;
+        default: return 0;
+    }
+}
+//# sourceMappingURL=identifier-ledger.js.map

package/dist/agentic/identifier-ledger.js.map

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

package/dist/agentic/ledger-tools.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Ledger enforcement over a tool loop.
+ *
+ * The rule that carries most of the 94.15%-on-Spider2 result is not a better
+ * prompt: only identifiers LIFTED FROM A TOOL OUTPUT may appear in executed SQL.
+ * Prompting for it does not work — a model asked to "only use real columns" will
+ * still invent `customer_tier` when the schema says `service_tier`, because the
+ * invented name is more plausible than the real one.
+ *
+ * So it is enforced structurally. Every tool result is harvested into an
+ * {@link IdentifierLedger} as the loop runs, and the SQL the model finally
+ * proposes is adjudicated against what was actually observed. A violation comes
+ * back as a correction naming the nearest observed identifier — not as a
+ * refusal, which is what the old pipeline turned it into.
+ */
+import type { AgentToolDefinition } from '../providers/types.js';
+import { IdentifierLedger, type IdentifierSource } from './identifier-ledger.js';
+export declare function evidenceSourceForTool(toolName: string): IdentifierSource;
+/**
+ * Pull identifiers out of an arbitrary tool result.
+ *
+ * Deliberately structural rather than a schema per tool: the tool set grows, and
+ * a harvester that silently misses a new tool's output would quietly re-open the
+ * hole this class exists to close — every unharvested name becomes an
+ * "unadmitted" false alarm on correct SQL.
+ *
+ * Bounded in depth and count so a large preview cannot turn one observation into
+ * a pathological walk.
+ */
+export declare function harvestIdentifiers(output: unknown, limit?: number): string[];
+/**
+ * Wrap tools so every observation feeds the ledger.
+ *
+ * The wrapper is transparent: it returns the tool's own output untouched and
+ * never fails the call. A harvesting bug must not break a working tool — the
+ * worst case is a name that goes unadmitted and surfaces as a correction, which
+ * the loop can recover from.
+ */
+export declare function withLedgerHarvest(tools: readonly AgentToolDefinition[], ledger: IdentifierLedger, onObservation?: (event: {
+    tool: string;
+    admitted: number;
+}) => void): AgentToolDefinition[];
+/**
+ * The explore-then-compose discipline, as a system message.
+ *
+ * Mirrors the two phases that produced the 94% result: establish real names
+ * first, then assemble over only those names.
+ */
+export declare const ANALYST_TOOL_POLICY: string;
+/**
+ * Adjudicate proposed SQL against what the loop actually observed.
+ *
+ * Returns a correction to feed back, or `undefined` when everything checks out.
+ * Never throws and never refuses: an unadmitted identifier is a fixable mistake,
+ * and the old pipeline turning it into a terminal `grounding_gap` is precisely
+ * the dead end being removed.
+ */
+export declare function adjudicateProposedSql(ledger: IdentifierLedger, references: {
+    relations?: readonly string[];
+    columns?: readonly string[];
+}): {
+    ok: true;
+} | {
+    ok: false;
+    correction: string;
+    unadmitted: string[];
+};
+//# sourceMappingURL=ledger-tools.d.ts.map

package/dist/agentic/ledger-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-tools.d.ts","sourceRoot":"","sources":["../../src/agentic/ledger-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAyBjF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAExE;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAAM,GAAG,MAAM,EAAE,CAsEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,MAAM,EAAE,gBAAgB,EACxB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,GAClE,mBAAmB,EAAE,CAevB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAgBpB,CAAC;AAEb;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACzE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAWxE"}

package/dist/agentic/ledger-tools.js

@@ -0,0 +1,198 @@
+import { IdentifierLedger } from './identifier-ledger.js';
+/**
+ * Where each tool's output sits on the evidence scale.
+ *
+ * A compiler emitting SQL is the strongest claim that a name exists; a catalog
+ * search only says something was INDEXED under that name, which is a weaker
+ * thing entirely — a stale index still returns rows.
+ */
+const TOOL_EVIDENCE = {
+    compile_semantic_query: 'compiler',
+    compile_governed_query: 'compiler',
+    preview_query: 'preview',
+    sample_notebook_dataset: 'preview',
+    execute_local_analysis: 'preview',
+    get_table_schema: 'schema_tool',
+    describe_notebook_dataset: 'schema_tool',
+    inspect_metadata_context: 'schema_tool',
+    list_notebook_datasets: 'schema_tool',
+    scan_manifest: 'catalog',
+    search_semantic_layer: 'catalog',
+    search_metadata: 'catalog',
+    check_compatibility: 'catalog',
+};
+export function evidenceSourceForTool(toolName) {
+    return TOOL_EVIDENCE[toolName] ?? 'catalog';
+}
+/** Keys whose STRING values name a relation or column. */
+const IDENTIFIER_KEYS = new Set([
+    'relation', 'table', 'tableName', 'fullName', 'qualifiedName', 'name',
+    'column', 'columnName', 'dimension', 'metric', 'measure', 'resolvedName',
+]);
+/** Keys whose ARRAY values are lists of identifiers or column records. */
+const IDENTIFIER_LIST_KEYS = new Set([
+    'columns', 'relations', 'tables', 'dimensions', 'metrics', 'measures',
+    'compatibleDimensions', 'outputs', 'groupBy', 'selectedColumns',
+]);
+/**
+ * Pull identifiers out of an arbitrary tool result.
+ *
+ * Deliberately structural rather than a schema per tool: the tool set grows, and
+ * a harvester that silently misses a new tool's output would quietly re-open the
+ * hole this class exists to close — every unharvested name becomes an
+ * "unadmitted" false alarm on correct SQL.
+ *
+ * Bounded in depth and count so a large preview cannot turn one observation into
+ * a pathological walk.
+ */
+export function harvestIdentifiers(output, limit = 500) {
+    const found = [];
+    const seen = new Set();
+    const push = (value) => {
+        if (typeof value !== 'string')
+            return;
+        const trimmed = value.trim();
+        // A SQL string or a sentence is not an identifier. Bare-ish names only.
+        if (!trimmed || trimmed.length > 128 || /\s/.test(trimmed))
+            return;
+        if (seen.has(trimmed) || found.length >= limit)
+            return;
+        seen.add(trimmed);
+        found.push(trimmed);
+    };
+    const walk = (node, depth) => {
+        if (found.length >= limit || depth > 6 || node === null || node === undefined)
+            return;
+        if (Array.isArray(node)) {
+            for (const entry of node) {
+                // A bare string inside an identifier list is itself an identifier.
+                if (typeof entry === 'string')
+                    push(entry);
+                else
+                    walk(entry, depth + 1);
+            }
+            return;
+        }
+        if (typeof node !== 'object')
+            return;
+        const record = node;
+        // Schema/preview tools commonly return `{ relation, columns: [{ name }] }`.
+        // Preserve that ownership in the ledger.  A bare `id` is not an execution
+        // identity: it could belong to any relation in the same result.
+        const relation = [record.relation, record.table, record.fullName, record.qualifiedName]
+            .find((value) => typeof value === 'string' && value.trim().length > 0)
+            ?.trim();
+        const ownedColumnKeys = new Set(['columns', 'selectedColumns', 'outputs']);
+        if (relation) {
+            for (const key of ['columns', 'selectedColumns', 'outputs']) {
+                const values = record[key];
+                if (!Array.isArray(values))
+                    continue;
+                for (const entry of values) {
+                    const column = typeof entry === 'string'
+                        ? entry
+                        : entry && typeof entry === 'object'
+                            ? [
+                                entry.column,
+                                entry.name,
+                                entry.columnName,
+                            ].find((value) => typeof value === 'string')
+                            : undefined;
+                    if (column && !/\s/.test(column))
+                        push(`${relation}.${column}`);
+                }
+            }
+        }
+        for (const [key, value] of Object.entries(record)) {
+            if (IDENTIFIER_KEYS.has(key))
+                push(value);
+            if (IDENTIFIER_LIST_KEYS.has(key) && Array.isArray(value)) {
+                // Relation-shaped schema and preview payloads were already harvested
+                // above as `relation.column`. Re-admitting their bare column leaves
+                // would let one table authorize the same leaf on another table.
+                if (relation && ownedColumnKeys.has(key))
+                    continue;
+                for (const entry of value) {
+                    if (typeof entry === 'string')
+                        push(entry);
+                    else
+                        walk(entry, depth + 1);
+                }
+                continue;
+            }
+            walk(value, depth + 1);
+        }
+    };
+    walk(output, 0);
+    return found;
+}
+/**
+ * Wrap tools so every observation feeds the ledger.
+ *
+ * The wrapper is transparent: it returns the tool's own output untouched and
+ * never fails the call. A harvesting bug must not break a working tool — the
+ * worst case is a name that goes unadmitted and surfaces as a correction, which
+ * the loop can recover from.
+ */
+export function withLedgerHarvest(tools, ledger, onObservation) {
+    return tools.map((tool, index) => ({
+        ...tool,
+        run: async (args) => {
+            const output = await tool.run(args);
+            try {
+                const identifiers = harvestIdentifiers(output);
+                ledger.admit(evidenceSourceForTool(tool.name), identifiers, `${tool.name}#${index}`);
+                onObservation?.({ tool: tool.name, admitted: identifiers.length });
+            }
+            catch {
+                // Never let harvesting break a tool that worked.
+            }
+            return output;
+        },
+    }));
+}
+/**
+ * The explore-then-compose discipline, as a system message.
+ *
+ * Mirrors the two phases that produced the 94% result: establish real names
+ * first, then assemble over only those names.
+ */
+export const ANALYST_TOOL_POLICY = [
+    'Work in two phases.',
+    '',
+    'EXPLORE — establish what actually exists before writing any SQL:',
+    '  · search for the governed metrics and dimensions the question needs',
+    '  · check compatibility before assuming a breakdown is reachable; when it is not,',
+    '    the tool tells you which dimensions ARE reachable — use one of those rather',
+    '    than stopping',
+    '  · compile a governed query and read back the identifiers it returns',
+    '',
+    'COMPOSE — assemble the final query using ONLY names a tool returned to you.',
+    'Every table and column in executed SQL must have appeared in a compile, preview,',
+    'or schema result. Preserve the qualified relation.column identity returned by the tool;',
+    'a bare leaf is not enough when multiple relations can contain the same name. A name that merely looks plausible is the single most common',
+    'way these queries go wrong: if you need a column you have not seen, inspect it',
+    'first rather than guessing its spelling.',
+].join('\n');
+/**
+ * Adjudicate proposed SQL against what the loop actually observed.
+ *
+ * Returns a correction to feed back, or `undefined` when everything checks out.
+ * Never throws and never refuses: an unadmitted identifier is a fixable mistake,
+ * and the old pipeline turning it into a terminal `grounding_gap` is precisely
+ * the dead end being removed.
+ */
+export function adjudicateProposedSql(ledger, references) {
+    // Catalog retrieval narrows tool search but is never execution evidence. A
+    // generated statement must name identifiers a compiler, preview, or schema
+    // observation actually returned during this invocation.
+    const verdict = ledger.adjudicate(references, { requireObserved: true });
+    if (verdict.ok)
+        return { ok: true };
+    return {
+        ok: false,
+        unadmitted: verdict.unadmitted,
+        correction: IdentifierLedger.renderCorrection(verdict) ?? 'Some identifiers were never observed.',
+    };
+}
+//# sourceMappingURL=ledger-tools.js.map