@duckcodeailabs/dql-agent 1.6.21 → 1.6.23

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"}

package/dist/hints/store.js

@@ -0,0 +1,279 @@
+/**
+ * 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 { dirname } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { hintAppliesToScope, } from './types.js';
+import { defaultEmbeddingProvider, hybridRank, } from '../embeddings/provider.js';
+const require = createRequire(import.meta.url);
+let databaseCtor = null;
+function loadDatabase() {
+    databaseCtor ??= require('better-sqlite3');
+    return databaseCtor;
+}
+export class HintStore {
+    db;
+    constructor(dbPath) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+        const Database = loadDatabase();
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_hints (
+        id            TEXT PRIMARY KEY,
+        title         TEXT NOT NULL,
+        guidance      TEXT NOT NULL,
+        status        TEXT NOT NULL DEFAULT 'candidate',
+        metric        TEXT,
+        dbt_model     TEXT,
+        domain        TEXT,
+        dialect       TEXT,
+        term          TEXT,
+        block         TEXT,
+        trace_id      TEXT,
+        corrected_sql TEXT,
+        tags_json     TEXT NOT NULL DEFAULT '[]',
+        author        TEXT,
+        reviewer      TEXT,
+        supersedes    TEXT,
+        created_at    TEXT NOT NULL,
+        updated_at    TEXT NOT NULL,
+        source_path   TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_agent_hints_status ON agent_hints(status);
+      CREATE INDEX IF NOT EXISTS idx_agent_hints_metric ON agent_hints(metric);
+      CREATE INDEX IF NOT EXISTS idx_agent_hints_domain ON agent_hints(domain);
+      CREATE INDEX IF NOT EXISTS idx_agent_hints_model  ON agent_hints(dbt_model);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS agent_hints_fts USING fts5(
+        id UNINDEXED,
+        title,
+        guidance,
+        tags,
+        scope,
+        tokenize = 'porter unicode61'
+      );
+    `);
+    }
+    /** Replace the whole index from the Git-authoritative hint set. */
+    rebuild(hints) {
+        const insert = this.db.prepare(`
+      INSERT OR REPLACE INTO agent_hints (
+        id, title, guidance, status, metric, dbt_model, domain, dialect, term, block,
+        trace_id, corrected_sql, tags_json, author, reviewer, supersedes,
+        created_at, updated_at, source_path
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const insertFts = this.db.prepare(`
+      INSERT INTO agent_hints_fts (id, title, guidance, tags, scope)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const txn = this.db.transaction(() => {
+            this.db.prepare('DELETE FROM agent_hints_fts').run();
+            this.db.prepare('DELETE FROM agent_hints').run();
+            for (const hint of hints) {
+                this.insertRow(hint, insert, insertFts);
+            }
+        });
+        txn();
+    }
+    /** Upsert a single hint (keeps Git + SQLite in sync after a record/approve). */
+    upsert(hint) {
+        const insert = this.db.prepare(`
+      INSERT OR REPLACE INTO agent_hints (
+        id, title, guidance, status, metric, dbt_model, domain, dialect, term, block,
+        trace_id, corrected_sql, tags_json, author, reviewer, supersedes,
+        created_at, updated_at, source_path
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const insertFts = this.db.prepare(`
+      INSERT INTO agent_hints_fts (id, title, guidance, tags, scope)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const txn = this.db.transaction(() => {
+            this.db.prepare('DELETE FROM agent_hints_fts WHERE id = ?').run(hint.id);
+            this.insertRow(hint, insert, insertFts);
+        });
+        txn();
+    }
+    insertRow(hint, insert, insertFts) {
+        insert.run(hint.id, hint.title, hint.guidance, hint.status, hint.scope.metric ?? null, hint.scope.dbtModel ?? null, hint.scope.domain ?? null, hint.scope.dialect ?? null, hint.scope.term ?? null, hint.scope.block ?? null, hint.traceId ?? null, hint.correctedSql ?? null, JSON.stringify(hint.tags ?? []), hint.author ?? null, hint.reviewer ?? null, hint.supersedes ?? null, hint.createdAt, hint.updatedAt, hint.sourcePath ?? null);
+        insertFts.run(hint.id, hint.title, hint.guidance, (hint.tags ?? []).join(' '), scopeText(hint.scope));
+    }
+    get(id) {
+        const row = this.db.prepare('SELECT * FROM agent_hints WHERE id = ?').get(id);
+        return row ? rowToHint(row) : null;
+    }
+    list(status) {
+        const rows = (status
+            ? this.db.prepare('SELECT * FROM agent_hints WHERE status = ? ORDER BY updated_at DESC').all(status)
+            : this.db.prepare('SELECT * FROM agent_hints ORDER BY updated_at DESC').all());
+        return rows.map(rowToHint);
+    }
+    /**
+     * 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.
+     */
+    async searchApprovedHints(options) {
+        const { questionScope, limit = 6 } = options;
+        const sanitized = sanitizeFtsQuery(questionScope.text);
+        // FTS narrows the candidate set when there is searchable text; otherwise fall
+        // back to all approved hints (scope filter still applies as a hard gate).
+        const ftsRows = sanitized
+            ? this.db.prepare(`
+          SELECT h.*, bm25(agent_hints_fts) AS rank
+          FROM agent_hints_fts AS f
+          JOIN agent_hints AS h ON h.id = f.id
+          WHERE agent_hints_fts MATCH ?
+            AND h.status = 'approved'
+          ORDER BY rank
+          LIMIT ?
+        `).all(sanitized, Math.max(limit * 4, 24))
+            : this.db.prepare(`
+          SELECT h.*, 0 AS rank
+          FROM agent_hints AS h
+          WHERE h.status = 'approved'
+          ORDER BY updated_at DESC
+          LIMIT ?
+        `).all(Math.max(limit * 4, 24));
+        // Hard scope gate: drop any hint whose scope does not apply to the question.
+        const scoped = ftsRows
+            .map((row) => {
+            const hint = rowToHint(row);
+            const verdict = hintAppliesToScope(hint.scope, questionScope);
+            const ftsScore = row.rank ? 1 / (1 + Math.max(0, row.rank)) : 0.01;
+            return { hint, verdict, ftsScore };
+        })
+            .filter((entry) => entry.verdict.applies);
+        if (scoped.length === 0)
+            return [];
+        // Hybrid rank (Part B). alpha defaults to 0 → pure FTS5 ordering.
+        const ranked = await hybridRank(questionScope.text, scoped.map((entry) => ({
+            item: entry,
+            text: `${entry.hint.title} ${entry.hint.guidance} ${(entry.hint.tags ?? []).join(' ')}`,
+            ftsScore: entry.ftsScore,
+        })), {
+            alpha: options.alpha ?? 0,
+            provider: options.embeddingProvider ?? defaultEmbeddingProvider(),
+        });
+        return ranked.slice(0, limit).map((entry) => ({
+            hint: entry.item.hint,
+            score: entry.score,
+            scopeReason: entry.item.verdict.reason,
+            snippet: undefined,
+        }));
+    }
+    /** Approved hints whose scopes overlap (surfaced as conflicts for review). */
+    conflictingApprovedHints() {
+        const approved = this.list('approved');
+        const pairs = [];
+        for (let i = 0; i < approved.length; i += 1) {
+            for (let j = i + 1; j < approved.length; j += 1) {
+                const a = approved[i];
+                const b = approved[j];
+                if (a.supersedes === b.id || b.supersedes === a.id)
+                    continue;
+                if (scopesShareConstraint(a.scope, b.scope))
+                    pairs.push([a, b]);
+            }
+        }
+        return pairs;
+    }
+    close() {
+        this.db.close();
+    }
+}
+function scopesShareConstraint(a, b) {
+    const fields = ['metric', 'dbtModel', 'domain', 'dialect', 'term', 'block'];
+    let shared = false;
+    for (const field of fields) {
+        const av = a[field];
+        const bv = b[field];
+        if (av && bv) {
+            if (av.trim().toLowerCase() !== bv.trim().toLowerCase())
+                return false;
+            shared = true;
+        }
+    }
+    return shared;
+}
+function scopeText(scope) {
+    return [scope.metric, scope.dbtModel, scope.domain, scope.dialect, scope.term, scope.block]
+        .filter(Boolean)
+        .join(' ');
+}
+function rowToHint(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        guidance: row.guidance,
+        status: row.status,
+        scope: {
+            metric: row.metric ?? undefined,
+            dbtModel: row.dbt_model ?? undefined,
+            domain: row.domain ?? undefined,
+            dialect: row.dialect ?? undefined,
+            term: row.term ?? undefined,
+            block: row.block ?? undefined,
+        },
+        traceId: row.trace_id ?? undefined,
+        correctedSql: row.corrected_sql ?? undefined,
+        tags: safeJSON(row.tags_json, []),
+        author: row.author ?? undefined,
+        reviewer: row.reviewer ?? undefined,
+        supersedes: row.supersedes ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function safeJSON(raw, fallback) {
+    if (!raw)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+const STOP_WORDS = new Set([
+    'a', 'about', 'above', 'after', 'again', 'against', 'all', 'am', 'an', 'and', 'any', 'are', 'as', 'at',
+    'be', 'because', 'been', 'before', 'being', 'below', 'between', 'both', 'but', 'by',
+    'can', 'could', 'current', 'did', 'do', 'does', 'doing', 'down', 'during',
+    'each', 'explain', 'few', 'find', 'for', 'from', 'further',
+    'get', 'give',
+    'had', 'has', 'have', 'having', 'he', 'her', 'here', 'hers', 'herself', 'him', 'himself', 'his', 'how',
+    'i', 'if', 'in', 'into', 'is', 'it', 'its', 'itself',
+    'just',
+    'me', 'more', 'most', 'my', 'myself',
+    'no', 'nor', 'not', 'now',
+    'of', 'off', 'on', 'once', 'only', 'or', 'other', 'our', 'ours', 'ourselves', 'out', 'over', 'own',
+    'please',
+    'query',
+    'same', 'she', 'should', 'show', 'so', 'some', 'sql', 'such',
+    'than', 'that', 'the', 'their', 'theirs', 'them', 'themselves', 'then', 'there', 'these', 'they', 'this', 'those', 'through', 'to', 'too',
+    'under', 'until', 'up', 'using',
+    'very',
+    'was', 'we', 'were', 'what', 'when', 'where', 'which', 'while', 'who', 'whom', 'why', 'will', 'with', 'would',
+    'you', 'your', 'yours', 'yourself', 'yourselves',
+]);
+function sanitizeFtsQuery(raw) {
+    return raw
+        .split(/\s+/)
+        .map((t) => t.replace(/[^\p{L}\p{N}_]/gu, ''))
+        .filter((t) => t.length > 1 && !STOP_WORDS.has(t.toLowerCase()))
+        .slice(0, 48)
+        .map((t) => `"${t}"`)
+        .join(' OR ');
+}
+//# sourceMappingURL=store.js.map

package/dist/hints/store.js.map

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

package/dist/hints/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Scoped correction memory ("mini Hint Graph") types.
+ *
+ * When an analyst corrects a Tier-2 generated answer, that knowledge is captured
+ * as a scoped, approved-only, Git-versioned **hint**. Hints never override
+ * certified routing — they are folded into the agent's context AFTER certified
+ * artifacts, semantic context, and graph anchors, and only when `approved`.
+ *
+ * Source of truth = Git:
+ *   - `.dql/traces/*.trace.json`  — raw correction traces (what was wrong + the fix)
+ *   - `.dql/hints/*.hint.yaml`     — candidate/approved/rejected hints
+ *   - `.dql/reviews/*.review.yaml` — human review decisions
+ *
+ * `.dql/cache/agent-kg.sqlite` carries a rebuildable FTS index of approved hints
+ * (Git authoritative; SQLite is just a fast scoped lookup).
+ */
+/**
+ * The scope an individual hint applies within. A hint is only eligible for a
+ * question when EVERY field it declares matches the question's resolved scope.
+ * Fields left undefined are wildcards (do not constrain).
+ */
+export interface HintScope {
+    /** Metric / KPI name, e.g. "revenue" or "active_users". */
+    metric?: string;
+    /** dbt model the hint is about, e.g. "fct_orders". */
+    dbtModel?: string;
+    /** Business domain, e.g. "growth". */
+    domain?: string;
+    /** Warehouse SQL dialect, e.g. "duckdb", "snowflake", "bigquery". */
+    dialect?: string;
+    /** Optional business term the hint refines. */
+    term?: string;
+    /** Optional certified block the hint relates to (objectKey or block name). */
+    block?: string;
+}
+export type HintStatus = 'candidate' | 'approved' | 'rejected';
+/**
+ * A raw correction trace recorded when a Tier-2 generated answer is corrected.
+ * This is the immutable evidence a hint is later derived from.
+ */
+export interface CorrectionTrace {
+    /** Stable id, e.g. `trace_xxx`. */
+    id: string;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** The original analyst question. */
+    question: string;
+    /** Scope the question resolved to (used to scope the derived hint). */
+    scope: HintScope;
+    /** What the Tier-2 draft answered (SQL and/or prose) that was wrong. */
+    wrongAnswer: string;
+    /** The analyst's correction (corrected SQL, rule, or guidance). */
+    correction: string;
+    /** Optional free-text rationale from the analyst. */
+    rationale?: string;
+    /** Who recorded the correction. */
+    author?: string;
+    /** contextPackId / blockId the correction was anchored to, when known. */
+    anchorObjectKey?: string;
+    /** id of the hint derived from this trace, once created. */
+    derivedHintId?: string;
+}
+/**
+ * A scoped correction hint. Becomes usable in future draft generation only when
+ * `status === 'approved'`. Stored in Git (`.dql/hints/<id>.hint.yaml`) and
+ * indexed in SQLite for scoped retrieval.
+ */
+export interface Hint {
+    /** Stable id, e.g. `hint_xxx`. */
+    id: string;
+    /** Short title surfaced to reviewers and as a citation label. */
+    title: string;
+    /** The guidance the agent should apply within scope (plain language / rule). */
+    guidance: string;
+    /** The scope this hint applies within. */
+    scope: HintScope;
+    /** Lifecycle state. Approved-only is enforced at retrieval. */
+    status: HintStatus;
+    /** Trace this hint was derived from, for provenance. */
+    traceId?: string;
+    /** Optional canonical corrected SQL the hint endorses. */
+    correctedSql?: string;
+    /** Free-text searchable keywords. */
+    tags?: string[];
+    /** Who authored the candidate hint. */
+    author?: string;
+    /** Who approved/rejected (set by the review). */
+    reviewer?: string;
+    /** ISO-8601. */
+    createdAt: string;
+    /** ISO-8601. */
+    updatedAt: string;
+    /** id of the hint this one supersedes (for conflict resolution). */
+    supersedes?: string;
+}
+/** Human review decision recorded in `.dql/reviews/<id>.review.yaml`. */
+export interface HintReview {
+    id: string;
+    hintId: string;
+    decision: 'approved' | 'rejected';
+    reviewer: string;
+    note?: string;
+    createdAt: string;
+}
+/** A hint matched for a question, with its FTS relevance + scope match reason. */
+export interface ScopedHintMatch {
+    hint: Hint;
+    /** Higher is better. Combines FTS/embedding relevance. */
+    score: number;
+    /** Plain-language scope match explanation, e.g. "metric=revenue, domain=growth". */
+    scopeReason: string;
+    /** Snippet from the FTS match, if any. */
+    snippet?: string;
+}
+/**
+ * Resolve a question's scope from the route/context. Any field left undefined is
+ * treated as "unconstrained" (wildcards in hints still match).
+ */
+export interface QuestionScope {
+    metric?: string;
+    dbtModel?: string;
+    domain?: string;
+    dialect?: string;
+    term?: string;
+    block?: string;
+    /** Free-text keywords used for FTS search (typically the question). */
+    text: string;
+}
+/**
+ * Does a hint's scope apply to the question's resolved scope?
+ *
+ * Semantics: a hint scope field constrains ONLY when the hint declares it. For
+ * each declared field, the question must declare the same value (case-insensitive).
+ * If the question does not declare a field the hint constrains, the hint does
+ * NOT apply (we never apply a narrower-than-known hint to an unknown context),
+ * EXCEPT `dialect`, which applies when the question's dialect is unknown (so a
+ * project-wide dialect hint is not silently dropped before a warehouse is wired).
+ *
+ * Undeclared hint fields are wildcards and never block a match.
+ */
+export declare function hintAppliesToScope(scope: HintScope, question: QuestionScope): {
+    applies: boolean;
+    reason: string;
+};
+/** Two hints conflict when their scopes overlap on the same concept. */
+export declare function hintsConflict(a: Hint, b: Hint): boolean;
+//# sourceMappingURL=types.d.ts.map

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

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