@duckcodeailabs/dql-agent 1.6.21 → 1.6.22

package/dist/app-planner.js

@@ -0,0 +1,145 @@
+/**
+ * App planner (P1) — turn a business goal into a planned decision surface, not a
+ * keyword-ranked grid of blocks.
+ *
+ * Given a goal ("revenue by region"), the planner decomposes it into the questions
+ * an app should answer (the headline number, its trend, breakdowns), matches each
+ * to a governed metric + certified block, derives the shared filters that let one
+ * control refresh every tile, writes a narrative, and reports COVERAGE + GAPS
+ * (questions with no certified block — what the reflect-before-certify loop should
+ * draft). Deterministic + offline; the metric match reuses the spec-17 matcher.
+ */
+import { matchSemanticMetric } from './metadata/metric-match.js';
+const TIME_DIM_RE = /(_at$|_date$|_time$|_ts$|^date$|^month$|^week$|^day$|ordered_at|created)/i;
+const NUMERIC_CONTROL_RE = /(top[_-]?n|limit|count|number|amount|year|season|score)/i;
+/** Classify a dimension into the dashboard control kind the filter engine renders. */
+function classifyControl(dimension) {
+    if (TIME_DIM_RE.test(dimension))
+        return 'daterange';
+    if (NUMERIC_CONTROL_RE.test(dimension))
+        return 'number';
+    // A categorical dimension renders as a dropdown the filter-options endpoint fills.
+    return 'select';
+}
+function humanize(name) {
+    return name.replace(/[_.]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/** Pull explicit "by <dimension>" requests from the goal. */
+function extractRequestedDimensions(goal) {
+    const dims = [];
+    const re = /\bby\s+([a-z_][a-z0-9_]*)/gi;
+    let m;
+    while ((m = re.exec(goal.toLowerCase()))) {
+        const d = m[1];
+        if (d && d !== 'the' && !dims.includes(d))
+            dims.push(d);
+    }
+    return dims;
+}
+/** Blocks that wrap this governed metric (so we know which tiles can cover it). */
+function blocksForMetric(blocks, metric) {
+    if (!metric)
+        return [];
+    const wanted = metric.toLowerCase();
+    const leaf = wanted.split('.').pop();
+    return blocks.filter((b) => {
+        const ref = (b.metricRef ?? '').toLowerCase();
+        return ref === wanted || ref.split('.').pop() === leaf;
+    });
+}
+/** A time dimension available on the metric's backing blocks, if any. */
+function findTimeDimension(blocks) {
+    for (const block of blocks) {
+        for (const f of [...(block.allowedFilters ?? []), ...(block.dimensions ?? [])]) {
+            if (TIME_DIM_RE.test(f))
+                return f;
+        }
+    }
+    return undefined;
+}
+/** Non-time filterable dimensions across the metric's blocks. */
+function categoricalDimensions(blocks) {
+    const out = [];
+    for (const block of blocks) {
+        for (const f of block.allowedFilters ?? []) {
+            if (!TIME_DIM_RE.test(f) && !out.includes(f))
+                out.push(f);
+        }
+    }
+    return out;
+}
+function coverSection(question, kind, metric, dimension, metricBlocks) {
+    // A block covers the section when it wraps the metric and (for a breakdown) the
+    // dimension is one of its declared filters.
+    const block = metricBlocks.find((b) => !dimension || (b.allowedFilters ?? []).includes(dimension) || (b.dimensions ?? []).includes(dimension));
+    return { question, kind, metric, dimension, blockName: block?.name, covered: Boolean(block) };
+}
+/**
+ * Plan an app from a business goal. Reuses the governed-metric matcher to anchor
+ * the plan on a real metric, then decomposes into KPI + trend + breakdown sections,
+ * maps each to a certified block, and reports coverage + gaps.
+ */
+export async function planApp(input) {
+    // Anchor on a metric that ALREADY has certified blocks to build from (so the app
+    // is assemblable), falling back to the best overall match when none is backed —
+    // the unbacked match then surfaces as a gap the build-and-certify loop fills.
+    const backedNames = new Set(input.blocks
+        .map((b) => b.metricRef?.toLowerCase())
+        .filter((ref) => Boolean(ref))
+        .flatMap((ref) => [ref, ref.split('.').pop() ?? ref]));
+    const backedMetrics = input.metrics.filter((m) => backedNames.has(m.name.toLowerCase()) || backedNames.has(m.name.toLowerCase().split('.').pop() ?? ''));
+    const match = (backedMetrics.length > 0 ? await matchSemanticMetric(input.goal, backedMetrics).catch(() => null) : null) ??
+        (await matchSemanticMetric(input.goal, input.metrics).catch(() => null));
+    const metricName = match?.metric.name;
+    const label = humanize(metricName ?? input.goal).slice(0, 60) || 'metric';
+    const metricBlocks = blocksForMetric(input.blocks, metricName);
+    const sections = [];
+    // 1) Headline KPI — the metric overall.
+    sections.push(coverSection(`Total ${label}`, 'kpi', metricName, undefined, metricBlocks));
+    // 2) Trend — the metric over a time dimension, when one is available.
+    const timeDim = findTimeDimension(metricBlocks);
+    if (timeDim) {
+        sections.push(coverSection(`${label} over time`, 'trend', metricName, timeDim, metricBlocks));
+    }
+    // 3) Breakdowns — by the requested dimensions, else the top available categoricals.
+    const requested = extractRequestedDimensions(input.goal).filter((d) => !TIME_DIM_RE.test(d));
+    const available = categoricalDimensions(metricBlocks);
+    const breakdownDims = (requested.length > 0 ? requested : available).slice(0, 3);
+    for (const dim of breakdownDims) {
+        sections.push(coverSection(`${label} by ${humanize(dim)}`, 'breakdown', metricName, dim, metricBlocks));
+    }
+    const sharedFilters = Array.from(new Set(sections.map((s) => s.dimension).filter((d) => Boolean(d))));
+    const covered = sections.filter((s) => s.covered).length;
+    const gaps = sections.filter((s) => !s.covered).map((s) => s.question);
+    const dimsText = sharedFilters.map(humanize).join(', ');
+    // Global filter bar (P3): one control per shared dimension, with the EXPLICIT set
+    // of covered tiles it refreshes (a covered section whose backing block declares the
+    // dimension). A control that refreshes nothing flags a filter waiting on a block.
+    const blockByName = new Map(metricBlocks.map((b) => [b.name, b]));
+    const declaresFilter = (section, dim) => {
+        const block = section.blockName ? blockByName.get(section.blockName) : undefined;
+        if (!block)
+            return false;
+        return (block.allowedFilters ?? []).includes(dim) || (block.dimensions ?? []).includes(dim);
+    };
+    const globalFilters = sharedFilters.map((dimension) => ({
+        dimension,
+        control: classifyControl(dimension),
+        refreshes: sections
+            .filter((s) => s.covered && declaresFilter(s, dimension))
+            .map((s) => s.question),
+    }));
+    return {
+        title: `${label} overview`,
+        narrative: `Tracks ${label}: the headline number` +
+            (timeDim ? ', its trend over time' : '') +
+            (sharedFilters.length > 0 ? `, and a breakdown by ${dimsText}.` : '.') +
+            ` One filter set refreshes every tile.`,
+        sections,
+        sharedFilters,
+        globalFilters,
+        gaps,
+        coverage: sections.length > 0 ? covered / sections.length : 0,
+    };
+}
+//# sourceMappingURL=app-planner.js.map

package/dist/app-planner.js.map

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

package/dist/embeddings/provider.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+export interface EmbeddingProvider {
+    /** Provider id, surfaced in diagnostics, e.g. "hashed-token-v1". */
+    readonly id: string;
+    /** Vector dimensionality. */
+    readonly dimensions: number;
+    /** Embed a batch of texts. Must be deterministic for the default provider. */
+    embed(texts: string[]): Promise<number[][]>;
+}
+/** Cosine similarity in [-1, 1]; 0 for degenerate vectors. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * 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 declare class HashedTokenEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "hashed-token-v1";
+    readonly dimensions: number;
+    constructor(dimensions?: number);
+    embed(texts: string[]): Promise<number[][]>;
+    embedOne(text: string): number[];
+}
+/** The safe default provider: deterministic + offline. */
+export declare function defaultEmbeddingProvider(): EmbeddingProvider;
+export interface HybridRankItem<T> {
+    item: T;
+    /** Text the item is embedded/searched on. */
+    text: string;
+    /** FTS/BM25-derived relevance in [0, 1] (higher better). */
+    ftsScore: number;
+}
+export interface HybridRankOptions {
+    /**
+     * Weight on the vector-similarity component in [0, 1]. 0 = pure FTS5 (the safe
+     * default). The blended score is `(1 - alpha) * fts + alpha * cosine01`.
+     */
+    alpha?: number;
+    provider?: EmbeddingProvider;
+}
+export interface HybridRanked<T> {
+    item: T;
+    ftsScore: number;
+    vectorScore: number;
+    score: number;
+}
+/**
+ * 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 declare function hybridRank<T>(query: string, items: HybridRankItem<T>[], options?: HybridRankOptions): Promise<HybridRanked<T>[]>;
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +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"}

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