@duckcodeailabs/dql-agent 1.6.20 → 1.6.22

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

package/dist/hints/types.js

@@ -0,0 +1,92 @@
+/**
+ * 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).
+ */
+/**
+ * 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 function hintAppliesToScope(scope, question) {
+    const matched = [];
+    const constrainedFields = [
+        ['metric', 'metric'],
+        ['dbtModel', 'dbtModel'],
+        ['domain', 'domain'],
+        ['term', 'term'],
+        ['block', 'block'],
+    ];
+    for (const [hintField, qField] of constrainedFields) {
+        const want = scope[hintField];
+        if (want === undefined || want === '')
+            continue; // wildcard
+        const have = question[qField];
+        if (have === undefined || have === '') {
+            return { applies: false, reason: `hint requires ${hintField}=${want} but question scope is unknown` };
+        }
+        if (!eqScope(want, have)) {
+            return { applies: false, reason: `hint ${hintField}=${want} ≠ question ${String(have)}` };
+        }
+        matched.push(`${hintField}=${want}`);
+    }
+    // Dialect: constrain when both sides know it; tolerate unknown question dialect.
+    if (scope.dialect && scope.dialect !== '') {
+        if (question.dialect && question.dialect !== '') {
+            if (!eqScope(scope.dialect, question.dialect)) {
+                return { applies: false, reason: `hint dialect=${scope.dialect} ≠ question ${question.dialect}` };
+            }
+            matched.push(`dialect=${scope.dialect}`);
+        }
+        // else: dialect unknown for the question — do not block; note advisory match.
+    }
+    return {
+        applies: true,
+        reason: matched.length > 0 ? matched.join(', ') : 'project-wide hint (no scope constraints)',
+    };
+}
+/** Two hints conflict when their scopes overlap on the same concept. */
+export function hintsConflict(a, b) {
+    if (a.id === b.id)
+        return false;
+    if (a.supersedes === b.id || b.supersedes === a.id)
+        return false; // explicit resolution
+    return scopesOverlap(a.scope, b.scope);
+}
+function scopesOverlap(a, b) {
+    const fields = ['metric', 'dbtModel', 'domain', 'dialect', 'term', 'block'];
+    let sharedConstraint = false;
+    for (const field of fields) {
+        const av = a[field];
+        const bv = b[field];
+        if (av && bv) {
+            if (!eqScope(av, bv))
+                return false; // disjoint on a declared field → no overlap
+            sharedConstraint = true;
+        }
+    }
+    // Overlap only when they actually share at least one declared, equal field.
+    return sharedConstraint;
+}
+function eqScope(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+//# sourceMappingURL=types.js.map

package/dist/hints/types.js.map

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

package/dist/index.d.ts

@@ -11,10 +11,24 @@ import type { DQLManifest } from "@duckcodeailabs/dql-core";
 export { KGStore } from "./kg/sqlite-fts.js";
 export type { KGNode, KGEdge, KGNodeKind, KGSearchHit, KGFeedbackRow, KGSearchOptions, } from "./kg/types.js";
 export { buildKGFromManifest, buildKGFromSemanticLayer } from "./kg/build.js";
-export { activeSkills, buildSkillBlockHints, loadSkills, parseSkill, buildSkillsPrompt, } from "./skills/loader.js";
-export type { Skill, SkillLoadResult } from "./skills/loader.js";
+export { activeSkills, buildSkillBlockHints, loadSkills, parseSkill, renderSkill, buildSkillsPrompt, selectRelevantSkills, writeSkill, upsertSkill, deleteSkill, skillsDir, skillPath, } from "./skills/loader.js";
+export type { Skill, SkillLoadResult, WriteSkillInput, SelectRelevantSkillsOptions, } from "./skills/loader.js";
+export { seedDefaultSkills } from "./skills/defaults.js";
+export type { SeedDefaultSkillsOptions, SeedDefaultSkillsResult, } from "./skills/defaults.js";
 export { answer, parseProposal } from "./answer-loop.js";
-export type { AgentAnalysisPlan, AgentAnswer, AgentCitation, AgentFollowUpContext, AgentJoinPath, AgentIntent, AgentResultPayload, AgentSchemaColumn, AgentSchemaTable, AnswerKind, AnswerLoopInput, } from "./answer-loop.js";
+export { decideAgentAction, looksLikeComposeApp, looksLikeFollowUp, type AgentAction, type IntentDecision, type IntentDecisionInput, type IntentSignals, } from "./intent-controller.js";
+export { AgentRunEngine, AGENT_RUN_ESCALATION_MAP, createDeterministicAgentRunPlanner, defaultSuccessCriteria, FileAgentRunStore, InMemoryAgentRunStore, defaultAgentRunStorePath, selectRoute, } from "./agent-run-engine.js";
+export type { FileAgentRunStoreOptions } from "./agent-run-engine.js";
+export type { AgentRouteExecutionContext, AgentRouteExecutor, AgentRouteExecutorResult, AgentRun, AgentRunArtifact, AgentRunArtifactKind, AgentRunAudience, AgentRunEngineOptions, AgentRunEvaluation, AgentRunEvaluationSeverity, AgentRunEvent, AgentRunExecutors, AgentRunGate, AgentRunGateContext, AgentRunGates, AgentRunNextAction, AgentRunPlan, AgentRunPlanInput, AgentRunPlanner, AgentRunPlanSource, AgentRunPlannedStep, AgentRunReplanDecision, AgentRunReplanInput, AgentRunRepairAction, AgentRunRequest, AgentRunRequestedMode, AgentRunRoute, AgentRunSelectedObject, AgentRunStatus, AgentRunStep, AgentRunStepStatus, AgentRunStopReason, AgentRunStore, AgentRunTrustState, } from "./agent-run-engine.js";
+export { defaultAgentRunGates } from "./agent-run-gates.js";
+export { narrateResult, type NarrateInput, type NarrateItem, type NarrateResult, type NarrateResultData, type NarrateCompletion, type NarrateOptions, } from "./narrate.js";
+export { createLlmAgentRunPlanner, type AgentRunPlannerCompletion, type LlmAgentRunPlannerOptions, } from "./agent-run-planner.js";
+export { planApp, type AppPlan as AgentAppPlan, type AppPlanSection, type AppPlanFilter as AgentAppPlanFilter, type PlanBlock, } from "./app-planner.js";
+export { planResearch, type ResearchPlan, type ResearchStep, type ResearchFollowUp, } from "./research-loop.js";
+export { loadSemanticMetrics } from "./propose/build-from-prompt.js";
+export type { AgentAnalysisPlan, AgentAnswer, AgentCitation, AgentFollowUpContext, AgentJoinPath, AgentIntent, AgentResultPayload, AgentSchemaColumn, AgentSchemaTable, AnswerKind, AnswerLoopInput, AiRoute, AiRouteTier, } from "./answer-loop.js";
+export { matchSemanticMetric } from "./metadata/metric-match.js";
+export type { MetricMatch, MatchSemanticMetricOptions } from "./metadata/metric-match.js";
 export { APP_BUILDER_SKILLS, planAppFromPrompt, validateAppPlan, generateAppFromPlan, } from "./app-builder.js";
 export type { AppBuilderSkill, AppBuilderSkillId, AppPlan, AppPlanAnalysisIntent, AppPlanFilter, AppPlanFollowUpAction, AppPlanPage, AppPlanTile, AppPlanTileKind, AppPlanTileRole, AppPlanTrustState, AppPlanValidationIssue, AppPlanValidationResult, GeneratedAppPackage, GenerateAppFromPlanOptions, PlanAppFromPromptInput, } from "./app-builder.js";
 export { MemoryStore, defaultMemoryPath, ensureDefaultMemoryFiles, } from "./memory/sqlite-memory.js";
@@ -24,12 +38,35 @@ export { buildBlockBusinessFingerprint, buildBlockSqlFingerprints, fingerprintSq
 export type { BlockBusinessFingerprint, BlockSqlFingerprints, BuildBlockBusinessFingerprintInput, } from "./metadata/block-fingerprints.js";
 export { buildAnalysisQuestionPlan, certifiedApplicabilityForObject, scoreAllowedSqlRelationWithAnalysisPlan, scoreMetadataObjectWithAnalysisPlan, sortAllowedSqlContextForAnalysisPlan, } from "./metadata/analysis-planner.js";
 export type { AnalysisEntityMention, AnalysisQuestionMode, AnalysisQuestionPlan, AllowedSqlRelationScore, CertifiedApplicabilityKind, CertifiedBlockApplicability, } from "./metadata/analysis-planner.js";
+export { grainMatches, requestedGrainFromPlan, } from "./metadata/grain-gate.js";
+export type { GrainGateKind, GrainGateResult, RequestedGrain, } from "./metadata/grain-gate.js";
 export { validateSqlAgainstLocalContext, } from "./metadata/sql-context-validation.js";
-export { deriveGeneratedDraftSlug, upsertGeneratedDraft, } from "./metadata/drafts.js";
-export type { BuildLocalContextPackRequest, EnsureMetadataCatalogOptions, EnsureMetadataCatalogResult, DqlContextPack, LocalContextPack, MetadataCandidateConflict, MetadataDiagnostic, MetadataEdge, MetadataAgentIntent, MetadataAllowedSqlContext, MetadataAnswerRoute, MetadataEvidenceRole, MetadataFollowUpContext, MetadataMissingContext, MetadataObject, MetadataRouteDecision, MetadataDomainShard, MetadataSourceFingerprint, MetadataSnapshot, MetadataTrustLabel, PlanAgentAnswerResult, QueryRunSummary, RuntimeSchemaSnapshot, RuntimeSchemaTable, RuntimeSchemaColumn, } from "./metadata/catalog.js";
+export { buildSchemaGrounding, buildGroundingFromRuntimeRelations, renderGroundingForPrompt, resolveRelationsInSql, validateSqlAgainstGrounding, relationKeys, } from "./metadata/sql-grounding.js";
+export type { SchemaGrounding, GroundedTable, GroundedColumn, GroundedJoinKey, BuildSchemaGroundingOptions, RuntimeRelationInput, RelationResolution, GroundingValidationCode, GroundingValidationResult, } from "./metadata/sql-grounding.js";
+export { selectRelevantModels } from "./metadata/sql-retrieval.js";
+export type { SelectRelevantModelsOptions } from "./metadata/sql-retrieval.js";
+export { deriveGeneratedDraftSlug, deriveSemanticDraftName, upsertGeneratedDraft, } from "./metadata/drafts.js";
+export type { SemanticDraftNameInput } from "./metadata/drafts.js";
+export { persistOwner, readPersistedOwner, resolveLocalOwner, } from "./metadata/identity.js";
+export type { ResolveOwnerOptions } from "./metadata/identity.js";
+export { propose, proposePlan, buildProposePreview, buildFromPrompt, loadDbtArtifacts, upsertProposedDraft, renderProposedDraft, blockSlug, resolveProposeConfig, DEFAULT_PROPOSE_CONFIG, classifyModel, resolveDomain, enrichProposal, enrichProposals, } from "./propose/index.js";
+export type { ProposeOptions, ProposeSummary, ProposalResult, ProposalInference, ProposalRanking, ProposedPattern, ProposePlan, ProposePlanOptions, ProposePlanDomain, ProposePlanCandidate, ProposePreviewOptions, BuildFromPromptOptions, BuildFromPromptContext, BuildFromPromptResult, BuildCellResult, BuildBlockResult, BuildMode, BuildRoute, CertifierVerdict, ProposeConfig, ProposeConfigInput, Classification, ClassificationResult, ProposedDraftRecord, WrittenDraft, DbtArtifacts, DbtModelNode, DbtSourceNode, DbtColumn, EnrichFacts, EnrichedContent, EnrichOptions, ReflectableDraft, ExecutionProbe, BlockReflection, ReflectionFix, } from "./propose/index.js";
+export { reflectAndReviseBlock } from "./propose/index.js";
+export type { BuildLocalContextPackRequest, EnsureMetadataCatalogOptions, EnsureMetadataCatalogResult, DqlContextPack, LocalContextPack, MetadataCandidateConflict, MetadataDiagnostic, MetadataEdge, MetadataAgentIntent, MetadataAllowedSqlContext, MetadataAnswerRoute, MetadataEvidenceRole, MetadataFollowUpContext, MetadataMissingContext, MetadataObject, MetadataRouteDecision, GrainGateRouteInfo, MetadataDomainShard, MetadataSourceFingerprint, MetadataSnapshot, MetadataTrustLabel, PlanAgentAnswerResult, QueryRunSummary, RuntimeSchemaSnapshot, RuntimeSchemaTable, RuntimeSchemaColumn, } from "./metadata/catalog.js";
 export type { SqlContextValidationCode, SqlContextValidationOptions, SqlContextValidationResult, } from "./metadata/sql-context-validation.js";
 export type { GeneratedDraftBlock, GeneratedDraftRecord, } from "./metadata/drafts.js";
-export { ClaudeProvider, OpenAIProvider, GeminiProvider, OllamaProvider, pickProvider, buildProvider, } from "./providers/index.js";
+export { HintStore, } from "./hints/store.js";
+export type { SearchApprovedHintsOptions, } from "./hints/store.js";
+export { recordCorrectionTrace, reviewHint, reindexHints, listHintsFromGit, getHintFromGit, writeHintFile, readHintFile, hintsDir, tracesDir, reviewsDir, defaultHintIndexPath, } from "./hints/git-store.js";
+export type { RecordCorrectionTraceInput, RecordCorrectionTraceResult, ReviewHintInput, ReviewHintResult, } from "./hints/git-store.js";
+export { retrieveScopedHints, } from "./hints/retrieval.js";
+export type { AppliedHint, HintRetrievalResult, RetrieveScopedHintsOptions, } from "./hints/retrieval.js";
+export { hintAppliesToScope, hintsConflict, } from "./hints/types.js";
+export type { CorrectionTrace, Hint, HintReview, HintScope, HintStatus, QuestionScope, ScopedHintMatch, } from "./hints/types.js";
+export { HashedTokenEmbeddingProvider, defaultEmbeddingProvider, cosineSimilarity, hybridRank, } from "./embeddings/provider.js";
+export type { EmbeddingProvider, HybridRankItem, HybridRankOptions, HybridRanked, } from "./embeddings/provider.js";
+export type { AppliedContextHint, } from "./metadata/catalog.js";
+export { ClaudeProvider, OpenAIProvider, GeminiProvider, OllamaProvider, pickProvider, buildProvider, normalizeAnthropicBaseUrl, normalizeGeminiBaseUrl, } from "./providers/index.js";
 export type { AgentProvider, AgentMessage, ProviderName, ProviderRunOptions, } from "./providers/index.js";
 /**
  * Default location for the agent's SQLite KG file.