@duckcodeailabs/dql-agent 1.6.20 → 1.6.22

package/dist/embeddings/provider.js

@@ -0,0 +1,105 @@
+/**
+ * Pluggable semantic retrieval (Part B).
+ *
+ * `EmbeddingProvider` is the interface real providers (a local model, an API)
+ * plug into. The DEFAULT provider is a deterministic, offline, hashed-token
+ * vector — NO heavy model dependency is added. FTS5/BM25 remains the safe
+ * default ranker; hybrid ranking blends FTS relevance with cosine similarity
+ * from the configured provider.
+ *
+ * Determinism matters: the default provider must produce identical vectors for
+ * identical text so tests are stable offline.
+ */
+import { createHash } from 'node:crypto';
+/** Cosine similarity in [-1, 1]; 0 for degenerate vectors. */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+const TOKEN_RE = /[\p{L}\p{N}_]+/gu;
+function tokenize(text) {
+    return (text.toLowerCase().match(TOKEN_RE) ?? []).filter((t) => t.length > 1);
+}
+/**
+ * Deterministic, dependency-free embedding via the hashing trick: each token is
+ * hashed to a bucket and a sign; counts accumulate into a fixed-width vector,
+ * then the vector is L2-normalised. Captures lexical overlap so semantically
+ * similar (shared-token) texts score higher under cosine similarity — enough to
+ * make hybrid ranking testable offline without any model.
+ */
+export class HashedTokenEmbeddingProvider {
+    id = 'hashed-token-v1';
+    dimensions;
+    constructor(dimensions = 256) {
+        this.dimensions = Math.max(16, dimensions);
+    }
+    async embed(texts) {
+        return texts.map((text) => this.embedOne(text));
+    }
+    embedOne(text) {
+        const vec = new Array(this.dimensions).fill(0);
+        for (const token of tokenize(text)) {
+            const h = hashToken(token);
+            const bucket = h % this.dimensions;
+            const sign = (h >>> 8) % 2 === 0 ? 1 : -1;
+            vec[bucket] += sign;
+        }
+        // L2 normalise so cosine reduces to a dot product and magnitudes are comparable.
+        let norm = 0;
+        for (const v of vec)
+            norm += v * v;
+        norm = Math.sqrt(norm);
+        if (norm === 0)
+            return vec;
+        return vec.map((v) => v / norm);
+    }
+}
+function hashToken(token) {
+    const digest = createHash('sha1').update(token).digest();
+    // First 4 bytes as an unsigned int.
+    return ((digest[0] << 24) | (digest[1] << 16) | (digest[2] << 8) | digest[3]) >>> 0;
+}
+/** The safe default provider: deterministic + offline. */
+export function defaultEmbeddingProvider() {
+    return new HashedTokenEmbeddingProvider();
+}
+/**
+ * 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
+ * default and embeddings are strictly additive/opt-in.
+ */
+export async function hybridRank(query, items, options = {}) {
+    const alpha = clamp01(options.alpha ?? 0);
+    if (alpha === 0 || items.length === 0) {
+        return items
+            .map((entry) => ({ item: entry.item, ftsScore: entry.ftsScore, vectorScore: 0, score: entry.ftsScore }))
+            .sort((a, b) => b.score - a.score);
+    }
+    const provider = options.provider ?? defaultEmbeddingProvider();
+    const [queryVec, ...itemVecs] = await provider.embed([query, ...items.map((entry) => entry.text)]);
+    return items
+        .map((entry, index) => {
+        const cosine = cosineSimilarity(queryVec, itemVecs[index] ?? []);
+        const cosine01 = (cosine + 1) / 2; // map [-1,1] → [0,1]
+        const score = (1 - alpha) * entry.ftsScore + alpha * cosine01;
+        return { item: entry.item, ftsScore: entry.ftsScore, vectorScore: cosine01, score };
+    })
+        .sort((a, b) => b.score - a.score);
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}
+//# sourceMappingURL=provider.js.map

package/dist/embeddings/provider.js.map

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

package/dist/hints/git-store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Git-authoritative store for scoped correction memory.
+ *
+ * Files (the source of truth, consistent with DQL):
+ *   - `.dql/traces/<id>.trace.json`  — correction traces
+ *   - `.dql/hints/<id>.hint.yaml`     — candidate / approved / rejected hints
+ *   - `.dql/reviews/<id>.review.yaml` — human review decisions
+ *
+ * `.dql/cache/agent-kg.sqlite` is a rebuildable index (see {@link HintStore}).
+ *
+ * The lifecycle:
+ *   recordCorrectionTrace() → derives a `candidate` hint
+ *   reviewHint('approved') → flips status to `approved`, writes the review,
+ *                            and reindexes SQLite
+ * Approved-only is enforced at retrieval; nothing here auto-applies a hint.
+ */
+import type { CorrectionTrace, Hint, HintReview, HintScope } from './types.js';
+export declare function tracesDir(projectRoot: string): string;
+export declare function hintsDir(projectRoot: string): string;
+export declare function reviewsDir(projectRoot: string): string;
+export declare function defaultHintIndexPath(projectRoot: string): string;
+export interface RecordCorrectionTraceInput {
+    question: string;
+    scope: HintScope;
+    wrongAnswer: string;
+    correction: string;
+    rationale?: string;
+    author?: string;
+    anchorObjectKey?: string;
+    /** Override the derived candidate hint's title. */
+    hintTitle?: string;
+    /** Override the derived candidate hint's guidance (defaults to the correction). */
+    hintGuidance?: string;
+    correctedSql?: string;
+    tags?: string[];
+}
+export interface RecordCorrectionTraceResult {
+    trace: CorrectionTrace;
+    hint: Hint;
+}
+/**
+ * Record a Tier-2 correction as a Git trace + a derived **candidate** hint.
+ * The hint is NOT usable until reviewed/approved.
+ */
+export declare function recordCorrectionTrace(projectRoot: string, input: RecordCorrectionTraceInput): RecordCorrectionTraceResult;
+export declare function hintFilePath(projectRoot: string, hintId: string): string;
+export declare function writeHintFile(projectRoot: string, hint: Hint): void;
+export declare function readHintFile(path: string, sourcePath?: string): Hint | null;
+export declare function listHintsFromGit(projectRoot: string): Hint[];
+export declare function getHintFromGit(projectRoot: string, hintId: string): Hint | null;
+export interface ReviewHintInput {
+    hintId: string;
+    decision: 'approved' | 'rejected';
+    reviewer: string;
+    note?: string;
+}
+export interface ReviewHintResult {
+    hint: Hint;
+    review: HintReview;
+}
+/**
+ * Approve or reject a candidate hint. Writes the review record, flips the hint
+ * file's status, and reindexes SQLite. Approval is the ONLY path that makes a
+ * hint usable in normal retrieval.
+ */
+export declare function reviewHint(projectRoot: string, input: ReviewHintInput): ReviewHintResult | null;
+/** Rebuild the SQLite hint index from the Git-authoritative files. */
+export declare function reindexHints(projectRoot: string, indexPath?: string): number;
+//# sourceMappingURL=git-store.d.ts.map

package/dist/hints/git-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-store.d.ts","sourceRoot":"","sources":["../../src/hints/git-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,OAAO,KAAK,EACV,eAAe,EACf,IAAI,EACJ,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAC;AAMpB,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErD;AACD,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpD;AACD,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAYD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,0BAA0B,GAChC,2BAA2B,CA6C7B;AAID,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAsBnE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiC3E;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,CAW5D;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAG/E;AAID,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CA+B/F;AAID,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,SAAoC,GAAG,MAAM,CASvG"}

package/dist/hints/git-store.js

@@ -0,0 +1,244 @@
+/**
+ * Git-authoritative store for scoped correction memory.
+ *
+ * Files (the source of truth, consistent with DQL):
+ *   - `.dql/traces/<id>.trace.json`  — correction traces
+ *   - `.dql/hints/<id>.hint.yaml`     — candidate / approved / rejected hints
+ *   - `.dql/reviews/<id>.review.yaml` — human review decisions
+ *
+ * `.dql/cache/agent-kg.sqlite` is a rebuildable index (see {@link HintStore}).
+ *
+ * The lifecycle:
+ *   recordCorrectionTrace() → derives a `candidate` hint
+ *   reviewHint('approved') → flips status to `approved`, writes the review,
+ *                            and reindexes SQLite
+ * Approved-only is enforced at retrieval; nothing here auto-applies a hint.
+ */
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from 'node:fs';
+import * as yaml from 'js-yaml';
+import { HintStore } from './store.js';
+const TRACES_DIR = ['.dql', 'traces'];
+const HINTS_DIR = ['.dql', 'hints'];
+const REVIEWS_DIR = ['.dql', 'reviews'];
+export function tracesDir(projectRoot) {
+    return join(projectRoot, ...TRACES_DIR);
+}
+export function hintsDir(projectRoot) {
+    return join(projectRoot, ...HINTS_DIR);
+}
+export function reviewsDir(projectRoot) {
+    return join(projectRoot, ...REVIEWS_DIR);
+}
+export function defaultHintIndexPath(projectRoot) {
+    return join(projectRoot, '.dql', 'cache', 'agent-kg.sqlite');
+}
+function genId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Record a Tier-2 correction as a Git trace + a derived **candidate** hint.
+ * The hint is NOT usable until reviewed/approved.
+ */
+export function recordCorrectionTrace(projectRoot, input) {
+    const traceId = genId('trace');
+    const hintId = genId('hint');
+    const createdAt = nowIso();
+    const trace = {
+        id: traceId,
+        createdAt,
+        question: input.question,
+        scope: cleanScope(input.scope),
+        wrongAnswer: input.wrongAnswer,
+        correction: input.correction,
+        rationale: input.rationale,
+        author: input.author,
+        anchorObjectKey: input.anchorObjectKey,
+        derivedHintId: hintId,
+    };
+    const hint = {
+        id: hintId,
+        title: input.hintTitle?.trim() || deriveTitle(input.question, input.scope),
+        guidance: (input.hintGuidance ?? input.correction).trim(),
+        scope: cleanScope(input.scope),
+        status: 'candidate',
+        traceId,
+        correctedSql: input.correctedSql,
+        tags: input.tags,
+        author: input.author,
+        createdAt,
+        updatedAt: createdAt,
+    };
+    mkdirSync(tracesDir(projectRoot), { recursive: true });
+    mkdirSync(hintsDir(projectRoot), { recursive: true });
+    writeFileSync(join(tracesDir(projectRoot), `${traceId}.trace.json`), `${JSON.stringify(trace, null, 2)}\n`, 'utf-8');
+    writeHintFile(projectRoot, hint);
+    // Index the candidate so review/dev mode can find it (status gate keeps it out
+    // of normal retrieval).
+    reindexHints(projectRoot);
+    return { trace, hint };
+}
+// --- Hints ------------------------------------------------------------------
+export function hintFilePath(projectRoot, hintId) {
+    return join(hintsDir(projectRoot), `${hintId}.hint.yaml`);
+}
+export function writeHintFile(projectRoot, hint) {
+    mkdirSync(hintsDir(projectRoot), { recursive: true });
+    const doc = {
+        id: hint.id,
+        title: hint.title,
+        guidance: hint.guidance,
+        status: hint.status,
+        scope: cleanScope(hint.scope),
+        traceId: hint.traceId,
+        correctedSql: hint.correctedSql,
+        tags: hint.tags,
+        author: hint.author,
+        reviewer: hint.reviewer,
+        supersedes: hint.supersedes,
+        createdAt: hint.createdAt,
+        updatedAt: hint.updatedAt,
+    };
+    writeFileSync(hintFilePath(projectRoot, hint.id), yaml.dump(stripUndefined(doc), { lineWidth: 100, noRefs: true }), 'utf-8');
+}
+export function readHintFile(path, sourcePath) {
+    try {
+        const raw = yaml.load(readFileSync(path, 'utf-8'));
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const scope = (raw.scope ?? {});
+        const hint = {
+            id: String(raw.id ?? ''),
+            title: String(raw.title ?? ''),
+            guidance: String(raw.guidance ?? ''),
+            status: raw.status ?? 'candidate',
+            scope: {
+                metric: strOrUndef(scope.metric),
+                dbtModel: strOrUndef(scope.dbtModel),
+                domain: strOrUndef(scope.domain),
+                dialect: strOrUndef(scope.dialect),
+                term: strOrUndef(scope.term),
+                block: strOrUndef(scope.block),
+            },
+            traceId: strOrUndef(raw.traceId),
+            correctedSql: strOrUndef(raw.correctedSql),
+            tags: Array.isArray(raw.tags) ? raw.tags.map(String) : undefined,
+            author: strOrUndef(raw.author),
+            reviewer: strOrUndef(raw.reviewer),
+            supersedes: strOrUndef(raw.supersedes),
+            createdAt: String(raw.createdAt ?? nowIso()),
+            updatedAt: String(raw.updatedAt ?? nowIso()),
+            sourcePath,
+        };
+        if (!hint.id)
+            return null;
+        return hint;
+    }
+    catch {
+        return null;
+    }
+}
+export function listHintsFromGit(projectRoot) {
+    const dir = hintsDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const hints = [];
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.hint.yaml'))
+            continue;
+        const path = join(dir, file);
+        const hint = readHintFile(path, path);
+        if (hint)
+            hints.push(hint);
+    }
+    return hints.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export function getHintFromGit(projectRoot, hintId) {
+    const path = hintFilePath(projectRoot, hintId);
+    return existsSync(path) ? readHintFile(path, path) : null;
+}
+/**
+ * Approve or reject a candidate hint. Writes the review record, flips the hint
+ * file's status, and reindexes SQLite. Approval is the ONLY path that makes a
+ * hint usable in normal retrieval.
+ */
+export function reviewHint(projectRoot, input) {
+    const hint = getHintFromGit(projectRoot, input.hintId);
+    if (!hint)
+        return null;
+    const reviewId = genId('review');
+    const createdAt = nowIso();
+    const review = {
+        id: reviewId,
+        hintId: input.hintId,
+        decision: input.decision,
+        reviewer: input.reviewer,
+        note: input.note,
+        createdAt,
+    };
+    mkdirSync(reviewsDir(projectRoot), { recursive: true });
+    writeFileSync(join(reviewsDir(projectRoot), `${reviewId}.review.yaml`), yaml.dump(stripUndefined({ ...review }), { lineWidth: 100, noRefs: true }), 'utf-8');
+    const updated = {
+        ...hint,
+        status: input.decision,
+        reviewer: input.reviewer,
+        updatedAt: createdAt,
+    };
+    writeHintFile(projectRoot, updated);
+    reindexHints(projectRoot);
+    return { hint: updated, review };
+}
+// --- Index ------------------------------------------------------------------
+/** Rebuild the SQLite hint index from the Git-authoritative files. */
+export function reindexHints(projectRoot, indexPath = defaultHintIndexPath(projectRoot)) {
+    const hints = listHintsFromGit(projectRoot);
+    const store = new HintStore(indexPath);
+    try {
+        store.rebuild(hints);
+        return hints.length;
+    }
+    finally {
+        store.close();
+    }
+}
+// --- helpers ----------------------------------------------------------------
+function deriveTitle(question, scope) {
+    const scopeBits = [scope.metric, scope.dbtModel, scope.domain].filter(Boolean).join('/');
+    const q = question.trim().replace(/\s+/g, ' ').slice(0, 60);
+    return scopeBits ? `Correction for ${scopeBits}: ${q}` : `Correction: ${q}`;
+}
+function cleanScope(scope) {
+    return {
+        metric: strOrUndef(scope.metric),
+        dbtModel: strOrUndef(scope.dbtModel),
+        domain: strOrUndef(scope.domain),
+        dialect: strOrUndef(scope.dialect),
+        term: strOrUndef(scope.term),
+        block: strOrUndef(scope.block),
+    };
+}
+function strOrUndef(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const str = String(value).trim();
+    return str.length > 0 ? str : undefined;
+}
+function stripUndefined(obj) {
+    const out = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === undefined)
+            continue;
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const nested = stripUndefined(value);
+            if (Object.keys(nested).length > 0)
+                out[key] = nested;
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=git-store.js.map

package/dist/hints/git-store.js.map

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

package/dist/hints/retrieval.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Fold approved scoped hints into the agent's context, AFTER certified routing.
+ *
+ * Retrieval order (extended, not replaced):
+ *   certified artifacts → semantic context → graph anchors → APPROVED HINTS → Tier-2 draft.
+ *
+ * Approved-only is hard-enforced here: only `status === 'approved'` hints are
+ * ever returned in normal mode. A hint is applied only within its declared
+ * scope (metric / dbt model / domain / dialect / term / block).
+ */
+import type { QuestionScope } from './types.js';
+import type { EmbeddingProvider } from '../embeddings/provider.js';
+export interface AppliedHint {
+    hintId: string;
+    title: string;
+    guidance: string;
+    scopeReason: string;
+    score: number;
+    correctedSql?: string;
+    traceId?: string;
+}
+export interface HintRetrievalResult {
+    /** Approved, scoped hints to fold in as advisory context (cited). */
+    applied: AppliedHint[];
+    /** Approved hints whose scopes overlap and disagree — surfaced for review. */
+    conflicts: Array<{
+        hintIds: [string, string];
+        titles: [string, string];
+        reason: string;
+    }>;
+}
+export interface RetrieveScopedHintsOptions {
+    questionScope: QuestionScope;
+    limit?: number;
+    /**
+     * Hybrid-rank weight. Defaults to 0 (pure FTS5, the safe default). Anything
+     * >0 blends the deterministic embedding similarity in.
+     */
+    alpha?: number;
+    embeddingProvider?: EmbeddingProvider;
+    indexPath?: string;
+}
+/**
+ * Retrieve approved scoped hints from the SQLite index. Returns an empty result
+ * (no error) when the index does not exist yet or no hints match — keeping the
+ * whole feature additive and backward-compatible.
+ */
+export declare function retrieveScopedHints(projectRoot: string, options: RetrieveScopedHintsOptions): Promise<HintRetrievalResult>;
+//# sourceMappingURL=retrieval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../src/hints/retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,8EAA8E;IAC9E,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,mBAAmB,CAAC,CA8B9B"}

package/dist/hints/retrieval.js

@@ -0,0 +1,60 @@
+/**
+ * Fold approved scoped hints into the agent's context, AFTER certified routing.
+ *
+ * Retrieval order (extended, not replaced):
+ *   certified artifacts → semantic context → graph anchors → APPROVED HINTS → Tier-2 draft.
+ *
+ * Approved-only is hard-enforced here: only `status === 'approved'` hints are
+ * ever returned in normal mode. A hint is applied only within its declared
+ * scope (metric / dbt model / domain / dialect / term / block).
+ */
+import { existsSync } from 'node:fs';
+import { defaultHintIndexPath } from './git-store.js';
+import { HintStore } from './store.js';
+/**
+ * Retrieve approved scoped hints from the SQLite index. Returns an empty result
+ * (no error) when the index does not exist yet or no hints match — keeping the
+ * whole feature additive and backward-compatible.
+ */
+export async function retrieveScopedHints(projectRoot, options) {
+    const indexPath = options.indexPath ?? defaultHintIndexPath(projectRoot);
+    if (!existsSync(indexPath))
+        return { applied: [], conflicts: [] };
+    const store = new HintStore(indexPath);
+    try {
+        const matches = await store.searchApprovedHints({
+            questionScope: options.questionScope,
+            limit: options.limit ?? 6,
+            alpha: options.alpha,
+            embeddingProvider: options.embeddingProvider,
+        });
+        const applied = matches.map(toAppliedHint);
+        // Surface conflicts only among the hints we actually applied, so unrelated
+        // overlaps elsewhere in the project do not noise up an answer.
+        const appliedIds = new Set(applied.map((hint) => hint.hintId));
+        const conflicts = store
+            .conflictingApprovedHints()
+            .filter(([a, b]) => appliedIds.has(a.id) || appliedIds.has(b.id))
+            .map(([a, b]) => ({
+            hintIds: [a.id, b.id],
+            titles: [a.title, b.title],
+            reason: `Approved hints "${a.title}" and "${b.title}" overlap on scope and may disagree; review which is authoritative.`,
+        }));
+        return { applied, conflicts };
+    }
+    finally {
+        store.close();
+    }
+}
+function toAppliedHint(match) {
+    return {
+        hintId: match.hint.id,
+        title: match.hint.title,
+        guidance: match.hint.guidance,
+        scopeReason: match.scopeReason,
+        score: match.score,
+        correctedSql: match.hint.correctedSql,
+        traceId: match.hint.traceId,
+    };
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/hints/retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../../src/hints/retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAiCvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAmB,EACnB,OAAmC;IAEnC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACzE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAElE,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,mBAAmB,CAAC;YAC9C,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;SAC7C,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAE3C,2EAA2E;QAC3E,+DAA+D;QAC/D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,KAAK;aACpB,wBAAwB,EAAE;aAC1B,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aAChE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAChB,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAqB;YACzC,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAqB;YAC9C,MAAM,EAAE,mBAAmB,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,KAAK,qEAAqE;SACzH,CAAC,CAAC,CAAC;QAEN,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAChC,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAsB;IAC3C,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE;QACrB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;QACvB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;QAC7B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;QACrC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;KAC5B,CAAC;AACJ,CAAC"}

package/dist/hints/store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SQLite index for scoped correction hints.
+ *
+ * Git is the source of truth (`.dql/hints/*.hint.yaml`); this is a rebuildable
+ * FTS5 index living in the SAME file as the KG (`.dql/cache/agent-kg.sqlite`),
+ * extending the existing store rather than introducing a second cache file.
+ * Approved-only is enforced at the retrieval boundary (`searchApprovedHints`).
+ */
+import { type Hint, type HintStatus, type QuestionScope, type ScopedHintMatch } from './types.js';
+import { type EmbeddingProvider } from '../embeddings/provider.js';
+export interface SearchApprovedHintsOptions {
+    questionScope: QuestionScope;
+    limit?: number;
+    /** Hybrid-rank knobs (Part B). alpha=0 keeps pure FTS5 (the safe default). */
+    alpha?: number;
+    embeddingProvider?: EmbeddingProvider;
+}
+export declare class HintStore {
+    private db;
+    constructor(dbPath: string);
+    private initSchema;
+    /** Replace the whole index from the Git-authoritative hint set. */
+    rebuild(hints: Hint[]): void;
+    /** Upsert a single hint (keeps Git + SQLite in sync after a record/approve). */
+    upsert(hint: Hint): void;
+    private insertRow;
+    get(id: string): Hint | null;
+    list(status?: HintStatus): Hint[];
+    /**
+     * Retrieve APPROVED hints that apply to a question's scope. This is the only
+     * retrieval entry point used outside review/dev mode — draft/candidate hints
+     * are never returned here.
+     */
+    searchApprovedHints(options: SearchApprovedHintsOptions): Promise<ScopedHintMatch[]>;
+    /** Approved hints whose scopes overlap (surfaced as conflicts for review). */
+    conflictingApprovedHints(): Array<[Hint, Hint]>;
+    close(): void;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/hints/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAEL,KAAK,IAAI,EAET,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AAUnC,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAoB;gBAElB,MAAM,EAAE,MAAM;IAQ1B,OAAO,CAAC,UAAU;IAuClB,mEAAmE;IACnE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAsB5B,gFAAgF;IAChF,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAmBxB,OAAO,CAAC,SAAS;IAmCjB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAK5B,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,EAAE;IAOjC;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IA0D1F,8EAA8E;IAC9E,wBAAwB,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAc/C,KAAK,IAAI,IAAI;CAGd"}