@duckcodeailabs/dql-agent 1.6.31 → 1.6.32

package/dist/conversation/working-state.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Deterministic conversation working state: the entities / measures / dimensions /
+ * filters "in play" across turns, plus explicit topic-relation classification
+ * (continuation | refinement | shift | return).
+ *
+ * This replaces regex guesswork with state: a topic SHIFT deterministically
+ * clears carried filters (stale-context protection), and a RETURN to a prior
+ * topic restores its filters and source block.
+ */
+import type { ConversationTurn } from './session-store.js';
+export type TopicRelation = 'continuation' | 'refinement' | 'shift' | 'return';
+export interface ConversationTopicFrame {
+    topicKey: string;
+    filters: string[];
+    sourceCertifiedBlock?: string;
+    contextPackId?: string;
+    measures: string[];
+    dimensions: string[];
+}
+export interface ConversationWorkingState {
+    entities: string[];
+    measures: string[];
+    dimensions: string[];
+    filters: Array<{
+        value: string;
+        sourceTurnId: string;
+    }>;
+    timeframe?: string;
+    limit?: number;
+    sourceCertifiedBlock?: string;
+    lastContextPackId?: string;
+    lastResultColumns?: string[];
+    lastResultDimensionValues?: Record<string, string[]>;
+    /** Normalized entity+measure key of the CURRENT topic, for shift detection. */
+    topicKey?: string;
+    /** Small ring of prior topics so a "return" can restore filters/block. */
+    priorTopics?: ConversationTopicFrame[];
+}
+export declare function emptyWorkingState(): ConversationWorkingState;
+export declare function parseWorkingState(raw: Record<string, unknown> | undefined): ConversationWorkingState;
+/**
+ * Fold a completed turn into the working state and classify how it relates to
+ * the ongoing topic. Pure and deterministic — safe to re-run.
+ */
+export declare function reduceWorkingState(prev: ConversationWorkingState, turn: ConversationTurn): {
+    state: ConversationWorkingState;
+    topicRelation: TopicRelation;
+};
+//# sourceMappingURL=working-state.d.ts.map

package/dist/conversation/working-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-state.d.ts","sourceRoot":"","sources":["../../src/conversation/working-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACrD,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACxC;AAgBD,wBAAgB,iBAAiB,IAAI,wBAAwB,CAE5D;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,wBAAwB,CAkBpG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,wBAAwB,EAC9B,IAAI,EAAE,gBAAgB,GACrB;IAAE,KAAK,EAAE,wBAAwB,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,CA4EnE"}

package/dist/conversation/working-state.js

@@ -0,0 +1,249 @@
+/**
+ * Deterministic conversation working state: the entities / measures / dimensions /
+ * filters "in play" across turns, plus explicit topic-relation classification
+ * (continuation | refinement | shift | return).
+ *
+ * This replaces regex guesswork with state: a topic SHIFT deterministically
+ * clears carried filters (stale-context protection), and a RETURN to a prior
+ * topic restores its filters and source block.
+ */
+const MAX_TERMS = 12;
+const MAX_FILTERS = 16;
+const MAX_PRIOR_TOPICS = 4;
+export function emptyWorkingState() {
+    return { entities: [], measures: [], dimensions: [], filters: [] };
+}
+export function parseWorkingState(raw) {
+    if (!raw)
+        return emptyWorkingState();
+    return {
+        entities: stringArray(raw.entities),
+        measures: stringArray(raw.measures),
+        dimensions: stringArray(raw.dimensions),
+        filters: filterArray(raw.filters),
+        timeframe: optionalString(raw.timeframe),
+        limit: typeof raw.limit === 'number' ? raw.limit : undefined,
+        sourceCertifiedBlock: optionalString(raw.sourceCertifiedBlock),
+        lastContextPackId: optionalString(raw.lastContextPackId),
+        lastResultColumns: raw.lastResultColumns ? stringArray(raw.lastResultColumns) : undefined,
+        lastResultDimensionValues: stringRecord(raw.lastResultDimensionValues),
+        topicKey: optionalString(raw.topicKey),
+        priorTopics: Array.isArray(raw.priorTopics)
+            ? raw.priorTopics.map(parseTopicFrame).filter((frame) => Boolean(frame)).slice(0, MAX_PRIOR_TOPICS)
+            : undefined,
+    };
+}
+/**
+ * Fold a completed turn into the working state and classify how it relates to
+ * the ongoing topic. Pure and deterministic — safe to re-run.
+ */
+export function reduceWorkingState(prev, turn) {
+    const shape = shapeFromTurn(turn);
+    const newKey = topicKeyFor(shape);
+    const relation = classifyTopicRelation(prev, shape, newKey);
+    if (relation === 'shift') {
+        // Stale-context protection: a new topic starts with a CLEAN filter slate.
+        // The outgoing topic is remembered so a later "return" can restore it.
+        const priorTopics = prev.topicKey
+            ? [frameFromState(prev), ...(prev.priorTopics ?? [])].slice(0, MAX_PRIOR_TOPICS)
+            : prev.priorTopics;
+        return {
+            topicRelation: relation,
+            state: {
+                entities: shape.entities.slice(0, MAX_TERMS),
+                measures: shape.measures.slice(0, MAX_TERMS),
+                dimensions: shape.dimensions.slice(0, MAX_TERMS),
+                filters: shape.filters.map((value) => ({ value, sourceTurnId: turn.id })).slice(0, MAX_FILTERS),
+                timeframe: shape.timeframe,
+                limit: shape.limit,
+                sourceCertifiedBlock: turn.sourceCertifiedBlock,
+                lastContextPackId: turn.contextPackId,
+                lastResultColumns: turn.result?.columns,
+                lastResultDimensionValues: turn.result?.dimensionValues,
+                topicKey: newKey || undefined,
+                priorTopics,
+            },
+        };
+    }
+    if (relation === 'return') {
+        const returned = (prev.priorTopics ?? []).find((frame) => overlaps(frame.topicKey, newKey) >= 0.5);
+        const remaining = (prev.priorTopics ?? []).filter((frame) => frame !== returned);
+        const currentFrame = prev.topicKey ? [frameFromState(prev)] : [];
+        return {
+            topicRelation: relation,
+            state: {
+                entities: merge(shape.entities, returned?.topicKey.split('|') ?? []),
+                measures: merge(shape.measures, returned?.measures ?? []),
+                dimensions: merge(shape.dimensions, returned?.dimensions ?? []),
+                filters: [
+                    ...(returned?.filters ?? []).map((value) => ({ value, sourceTurnId: turn.id })),
+                    ...shape.filters.map((value) => ({ value, sourceTurnId: turn.id })),
+                ].slice(0, MAX_FILTERS),
+                timeframe: shape.timeframe ?? prev.timeframe,
+                limit: shape.limit ?? prev.limit,
+                sourceCertifiedBlock: turn.sourceCertifiedBlock ?? returned?.sourceCertifiedBlock,
+                lastContextPackId: turn.contextPackId ?? returned?.contextPackId,
+                lastResultColumns: turn.result?.columns ?? prev.lastResultColumns,
+                lastResultDimensionValues: turn.result?.dimensionValues ?? prev.lastResultDimensionValues,
+                topicKey: returned?.topicKey ?? newKey ?? prev.topicKey,
+                priorTopics: [...currentFrame, ...remaining].slice(0, MAX_PRIOR_TOPICS),
+            },
+        };
+    }
+    // continuation / refinement: accumulate.
+    return {
+        topicRelation: relation,
+        state: {
+            entities: merge(prev.entities, shape.entities),
+            measures: merge(prev.measures, shape.measures),
+            dimensions: merge(prev.dimensions, shape.dimensions),
+            filters: mergeFilters(prev.filters, shape.filters.map((value) => ({ value, sourceTurnId: turn.id }))),
+            timeframe: shape.timeframe ?? prev.timeframe,
+            limit: shape.limit ?? prev.limit,
+            sourceCertifiedBlock: turn.sourceCertifiedBlock ?? prev.sourceCertifiedBlock,
+            lastContextPackId: turn.contextPackId ?? prev.lastContextPackId,
+            lastResultColumns: turn.result?.columns ?? prev.lastResultColumns,
+            lastResultDimensionValues: turn.result?.dimensionValues ?? prev.lastResultDimensionValues,
+            topicKey: prev.topicKey && newKey && prev.topicKey !== newKey
+                ? mergeTopicKeys(prev.topicKey, newKey)
+                : prev.topicKey ?? newKey ?? undefined,
+            priorTopics: prev.priorTopics,
+        },
+    };
+}
+function classifyTopicRelation(prev, shape, newKey) {
+    if (!prev.topicKey)
+        return 'continuation';
+    if (!newKey) {
+        // No topical signal in the new turn: filters/limit-only turns narrow the
+        // current topic (refinement); a bare deictic follow-up just continues it.
+        return shape.filters.length > 0 || shape.limit !== undefined ? 'refinement' : 'continuation';
+    }
+    const overlap = overlaps(prev.topicKey, newKey);
+    if (overlap >= 0.5)
+        return 'continuation';
+    if (overlap > 0)
+        return 'refinement';
+    const returned = (prev.priorTopics ?? []).some((frame) => overlaps(frame.topicKey, newKey) >= 0.5);
+    if (returned)
+        return 'return';
+    // Zero overlap with the current topic: filters/limit-only turns are refinements;
+    // a turn with its own entities/measures is a genuine shift.
+    if (shape.entities.length === 0 && shape.measures.length === 0)
+        return 'refinement';
+    return 'shift';
+}
+function shapeFromTurn(turn) {
+    const contract = turn.contract ?? {};
+    const topN = contract.topN;
+    return {
+        entities: stringArray(contract.entities),
+        measures: stringArray(contract.measures),
+        dimensions: stringArray(contract.dimensions),
+        filters: stringArray(contract.filters),
+        timeframe: optionalString(contract.timeframe),
+        limit: typeof topN === 'number'
+            ? topN
+            : topN && typeof topN === 'object' && typeof topN.n === 'number'
+                ? topN.n
+                : undefined,
+    };
+}
+function topicKeyFor(shape) {
+    return Array.from(new Set([
+        ...shape.entities.map(normalizeTerm),
+        ...shape.measures.map(normalizeTerm),
+    ].filter(Boolean))).sort().join('|');
+}
+/** Jaccard overlap of two topic keys ('|'-joined normalized term sets). */
+function overlaps(a, b) {
+    const setA = new Set(a.split('|').filter(Boolean));
+    const setB = new Set(b.split('|').filter(Boolean));
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    let shared = 0;
+    for (const term of setA)
+        if (setB.has(term))
+            shared += 1;
+    return shared / (setA.size + setB.size - shared);
+}
+function frameFromState(state) {
+    return {
+        topicKey: state.topicKey ?? '',
+        filters: state.filters.map((filter) => filter.value),
+        sourceCertifiedBlock: state.sourceCertifiedBlock,
+        contextPackId: state.lastContextPackId,
+        measures: state.measures,
+        dimensions: state.dimensions,
+    };
+}
+function parseTopicFrame(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const topicKey = optionalString(record.topicKey);
+    if (!topicKey)
+        return undefined;
+    return {
+        topicKey,
+        filters: stringArray(record.filters),
+        sourceCertifiedBlock: optionalString(record.sourceCertifiedBlock),
+        contextPackId: optionalString(record.contextPackId),
+        measures: stringArray(record.measures),
+        dimensions: stringArray(record.dimensions),
+    };
+}
+function mergeTopicKeys(a, b) {
+    return Array.from(new Set([...a.split('|'), ...b.split('|')].filter(Boolean))).sort().slice(0, 8).join('|');
+}
+function merge(a, b) {
+    return Array.from(new Set([...a, ...b].map(normalizeTerm).filter(Boolean))).slice(0, MAX_TERMS);
+}
+function mergeFilters(prev, next) {
+    const seen = new Set();
+    const out = [];
+    for (const filter of [...prev, ...next]) {
+        const key = filter.value.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(filter);
+    }
+    return out.slice(0, MAX_FILTERS);
+}
+function normalizeTerm(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_ ]+/g, '').replace(/s$/, '').trim();
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+}
+function filterArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return [];
+        const record = item;
+        const filterValue = optionalString(record.value);
+        if (!filterValue)
+            return [];
+        return [{ value: filterValue, sourceTurnId: optionalString(record.sourceTurnId) ?? '' }];
+    });
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function stringRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const values = stringArray(raw);
+        if (values.length > 0)
+            out[key] = values;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+//# sourceMappingURL=working-state.js.map

package/dist/conversation/working-state.js.map

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

package/dist/embeddings/provider.d.ts

@@ -36,6 +36,68 @@ export declare class HashedTokenEmbeddingProvider implements EmbeddingProvider {
 }
 /** The safe default provider: deterministic + offline. */
 export declare function defaultEmbeddingProvider(): EmbeddingProvider;
+/** Minimal fetch signature so the OpenAI provider stays dependency-free and testable. */
+export type EmbeddingFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface OpenAIEmbeddingOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    dimensions?: number;
+    fetchImpl?: EmbeddingFetch;
+}
+/**
+ * Real embeddings via an OpenAI-compatible `/embeddings` endpoint (dependency-free
+ * over fetch). Opt-in: only constructed when an API key is configured. Falls back
+ * to the hashed provider at the resolver level when unavailable, so offline and
+ * un-keyed projects keep working deterministically.
+ */
+export declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    readonly id: string;
+    readonly dimensions: number;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: OpenAIEmbeddingOptions);
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Content-hash cache around any provider so repeated texts (block example
+ * questions, metric labels) are embedded once. Bounded LRU-ish by insertion order.
+ */
+export declare class CachingEmbeddingProvider implements EmbeddingProvider {
+    readonly id: string;
+    readonly dimensions: number;
+    private readonly inner;
+    private readonly cache;
+    private readonly maxEntries;
+    constructor(inner: EmbeddingProvider, maxEntries?: number);
+    embed(texts: string[]): Promise<number[][]>;
+    private put;
+}
+export interface EmbeddingResolveOptions {
+    /** API key for an OpenAI-compatible embeddings endpoint. */
+    openaiApiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    fetchImpl?: EmbeddingFetch;
+}
+/**
+ * Pick the best available embedding provider: a real OpenAI-compatible embedder
+ * when an API key is configured (wrapped in a content-hash cache), else the safe
+ * deterministic hashed-token provider. This is the single place config chooses an
+ * embedder, so retrieval/matching call sites just call resolveEmbeddingProvider().
+ */
+export declare function resolveEmbeddingProvider(options?: EmbeddingResolveOptions): EmbeddingProvider;
 export interface HybridRankItem<T> {
     item: T;
     /** Text the item is embedded/searched on. */

package/dist/embeddings/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/embeddings/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;CAC7C;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAYjE;AAQD;;;;;;GAMG;AACH,qBAAa,4BAA6B,YAAW,iBAAiB;IACpE,QAAQ,CAAC,EAAE,qBAAqB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,SAAM;IAItB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAIjD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAejC;AAQD,0DAA0D;AAC1D,wBAAgB,wBAAwB,IAAI,iBAAiB,CAE5D;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAC;IACR,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAiB5B"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/embeddings/provider.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/provider.js

@@ -74,6 +74,104 @@ function hashToken(token) {
 export function defaultEmbeddingProvider() {
     return new HashedTokenEmbeddingProvider();
 }
+/**
+ * Real embeddings via an OpenAI-compatible `/embeddings` endpoint (dependency-free
+ * over fetch). Opt-in: only constructed when an API key is configured. Falls back
+ * to the hashed provider at the resolver level when unavailable, so offline and
+ * un-keyed projects keep working deterministically.
+ */
+export class OpenAIEmbeddingProvider {
+    id;
+    dimensions;
+    apiKey;
+    model;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.model = options.model ?? 'text-embedding-3-small';
+        this.baseUrl = (options.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+        this.dimensions = options.dimensions ?? 1536;
+        this.id = `openai:${this.model}`;
+        this.fetchImpl = options.fetchImpl ?? ((url, init) => fetch(url, init));
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const response = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` },
+            body: JSON.stringify({ model: this.model, input: texts }),
+        });
+        if (!response.ok)
+            throw new Error(`Embedding request failed (${response.status})`);
+        const payload = await response.json();
+        const rows = payload.data ?? [];
+        // Preserve request order via the returned index.
+        const out = new Array(texts.length).fill(null).map(() => []);
+        rows.forEach((row, i) => {
+            const index = typeof row.index === 'number' ? row.index : i;
+            out[index] = row.embedding ?? [];
+        });
+        return out;
+    }
+}
+/**
+ * Content-hash cache around any provider so repeated texts (block example
+ * questions, metric labels) are embedded once. Bounded LRU-ish by insertion order.
+ */
+export class CachingEmbeddingProvider {
+    id;
+    dimensions;
+    inner;
+    cache = new Map();
+    maxEntries;
+    constructor(inner, maxEntries = 4096) {
+        this.inner = inner;
+        this.id = `cached:${inner.id}`;
+        this.dimensions = inner.dimensions;
+        this.maxEntries = maxEntries;
+    }
+    async embed(texts) {
+        const missing = [];
+        const keys = texts.map((text) => {
+            const key = createHash('sha1').update(text).digest('hex');
+            if (!this.cache.has(key))
+                missing.push({ text, key });
+            return key;
+        });
+        if (missing.length > 0) {
+            const vectors = await this.inner.embed(missing.map((entry) => entry.text));
+            missing.forEach((entry, i) => this.put(entry.key, vectors[i] ?? []));
+        }
+        return keys.map((key) => this.cache.get(key) ?? []);
+    }
+    put(key, vector) {
+        this.cache.set(key, vector);
+        if (this.cache.size > this.maxEntries) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+    }
+}
+/**
+ * Pick the best available embedding provider: a real OpenAI-compatible embedder
+ * when an API key is configured (wrapped in a content-hash cache), else the safe
+ * deterministic hashed-token provider. This is the single place config chooses an
+ * embedder, so retrieval/matching call sites just call resolveEmbeddingProvider().
+ */
+export function resolveEmbeddingProvider(options = {}) {
+    if (options.openaiApiKey) {
+        return new CachingEmbeddingProvider(new OpenAIEmbeddingProvider({
+            apiKey: options.openaiApiKey,
+            ...(options.model ? { model: options.model } : {}),
+            ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        }));
+    }
+    return defaultEmbeddingProvider();
+}
 /**
  * Blend FTS5 relevance with embedding cosine similarity. When `alpha` is 0 (the
  * default) this is a pure pass-through of the FTS ordering — FTS5 stays the safe

package/dist/embeddings/provider.js.map

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

package/dist/grounding/context-ledger.d.ts

@@ -0,0 +1,30 @@
+import type { LocalContextPack, MetadataAgentIntent, RuntimeSchemaTable } from '../metadata/catalog.js';
+import { type SqlContextValidationResult } from '../metadata/sql-context-validation.js';
+import { type GroundingValidationResult, type RelationResolution, type SchemaGrounding } from '../metadata/sql-grounding.js';
+import { type GroundingExpansionResult } from './regrounding.js';
+export interface ContextLedgerInput {
+    contextPack?: LocalContextPack;
+    schemaContext?: RuntimeSchemaTable[];
+}
+export interface ContextLedgerSqlValidationOptions {
+    question?: string;
+    intent?: MetadataAgentIntent | string;
+    filterValues?: string[];
+    trustedFilterValues?: string[];
+}
+export interface ContextLedgerExpansionResult {
+    ledger: ContextLedger;
+    notes: string[];
+}
+export declare class ContextLedger {
+    readonly contextPack?: LocalContextPack;
+    readonly schemaContext: RuntimeSchemaTable[];
+    readonly grounding?: SchemaGrounding;
+    constructor(input?: ContextLedgerInput);
+    qualifySql(sql: string): RelationResolution;
+    validateSql(sql: string, options?: ContextLedgerSqlValidationOptions): SqlContextValidationResult;
+    validateRuntimeGrounding(sql: string): GroundingValidationResult | undefined;
+    withExpansion(expansion: GroundingExpansionResult | undefined): ContextLedgerExpansionResult;
+}
+export declare function createContextLedger(input?: ContextLedgerInput): ContextLedger;
+//# sourceMappingURL=context-ledger.d.ts.map

package/dist/grounding/context-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-ledger.d.ts","sourceRoot":"","sources":["../../src/grounding/context-ledger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAIL,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,kBAAkB,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;gBAEzB,KAAK,GAAE,kBAAuB;IAM1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB;IAK3C,WAAW,CACT,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,iCAAsC,GAC9C,0BAA0B;IAO7B,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IAI5E,aAAa,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,GAAG,4BAA4B;CAU7F;AAED,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,kBAAuB,GAAG,aAAa,CAEjF"}

package/dist/grounding/context-ledger.js

@@ -0,0 +1,54 @@
+import { validateSqlAgainstLocalContext, } from '../metadata/sql-context-validation.js';
+import { buildGroundingFromRuntimeRelations, resolveRelationsInSql, validateSqlAgainstGrounding, } from '../metadata/sql-grounding.js';
+import { applyGroundingExpansion, } from './regrounding.js';
+export class ContextLedger {
+    contextPack;
+    schemaContext;
+    grounding;
+    constructor(input = {}) {
+        this.contextPack = input.contextPack;
+        this.schemaContext = input.schemaContext ?? [];
+        this.grounding = buildRuntimeGrounding(this.schemaContext);
+    }
+    qualifySql(sql) {
+        if (!this.grounding)
+            return { sql, rewrites: [] };
+        return resolveRelationsInSql(sql, this.grounding, { prefer: 'qualified' });
+    }
+    validateSql(sql, options = {}) {
+        return validateSqlAgainstLocalContext(sql, this.contextPack, {
+            ...options,
+            runtimeSchema: this.schemaContext,
+        });
+    }
+    validateRuntimeGrounding(sql) {
+        return this.grounding ? validateSqlAgainstGrounding(sql, this.grounding) : undefined;
+    }
+    withExpansion(expansion) {
+        const merged = applyGroundingExpansion(this.contextPack, this.schemaContext, expansion);
+        return {
+            ledger: new ContextLedger({
+                contextPack: merged.contextPack,
+                schemaContext: merged.schemaContext,
+            }),
+            notes: merged.notes,
+        };
+    }
+}
+export function createContextLedger(input = {}) {
+    return new ContextLedger(input);
+}
+function buildRuntimeGrounding(schemaContext) {
+    if (schemaContext.length === 0)
+        return undefined;
+    return buildGroundingFromRuntimeRelations(schemaContext.map((table) => ({
+        relation: table.relation,
+        name: table.name,
+        columns: table.columns.map((column) => ({
+            name: column.name,
+            type: column.type,
+            description: column.description,
+        })),
+    })));
+}
+//# sourceMappingURL=context-ledger.js.map

package/dist/grounding/context-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-ledger.js","sourceRoot":"","sources":["../../src/grounding/context-ledger.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,8BAA8B,GAE/B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,2BAA2B,GAI5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,uBAAuB,GAExB,MAAM,kBAAkB,CAAC;AAmB1B,MAAM,OAAO,aAAa;IACf,WAAW,CAAoB;IAC/B,aAAa,CAAuB;IACpC,SAAS,CAAmB;IAErC,YAAY,QAA4B,EAAE;QACxC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7D,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAClD,OAAO,qBAAqB,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,WAAW,CACT,GAAW,EACX,UAA6C,EAAE;QAE/C,OAAO,8BAA8B,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE;YAC3D,GAAG,OAAO;YACV,aAAa,EAAE,IAAI,CAAC,aAAa;SAClC,CAAC,CAAC;IACL,CAAC;IAED,wBAAwB,CAAC,GAAW;QAClC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,2BAA2B,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvF,CAAC;IAED,aAAa,CAAC,SAA+C;QAC3D,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QACxF,OAAO;YACL,MAAM,EAAE,IAAI,aAAa,CAAC;gBACxB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,aAAa,EAAE,MAAM,CAAC,aAAa;aACpC,CAAC;YACF,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,QAA4B,EAAE;IAChE,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,qBAAqB,CAAC,aAAmC;IAChE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACjD,OAAO,kCAAkC,CACvC,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACtC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAC,CAAC;KACJ,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC"}