@duckcodeailabs/dql-agent 1.6.20 → 1.6.22

package/dist/propose/dbt-artifacts.js

@@ -0,0 +1,320 @@
+/**
+ * Read-only readers for dbt build artifacts used by `dql propose`.
+ *
+ * These parse the raw JSON shapes that dbt writes to `target/`:
+ *   - `manifest.json`        — models, sources, depends_on, tags, schema, description
+ *   - `catalog.json`         — column names + types (from the warehouse)
+ *   - `semantic_manifest.json` (or manifest.json semantic nodes) — metrics/dimensions
+ *   - `run_results.json`     — per-node execution records (used for run-frequency ranking)
+ *
+ * We deliberately do NOT reuse the manifest builder's `importDbtManifest`: that
+ * function is private and tightly coupled to a full DQL project scan (it walks
+ * the DQL-referenced anchor set). `dql propose` runs *before* a DQL layer
+ * exists, so it reads the dbt artifacts directly. The field shapes mirror those
+ * the builder consumes, so the two stay aligned.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Build the fully-qualified warehouse relation for a node from its
+ * `database` / `schema` / relation-name fields. Returns the most-qualified
+ * dotted form available (`db.schema.name` → `schema.name` → `name`) so a
+ * `FROM` clause always references the REAL relation, never a bare model name.
+ */
+export function buildQualifiedRelation(parts) {
+    return [parts.database, parts.schema, parts.name]
+        .map((part) => (typeof part === 'string' ? part.trim() : ''))
+        .filter((part) => part.length > 0)
+        .join('.');
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return value;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Derive the `models/<folder>/...` segment from a node path, e.g. `marts`. */
+function folderFromPath(path) {
+    if (!path)
+        return undefined;
+    const normalized = path.replace(/\\/g, '/');
+    const match = normalized.match(/(?:^|\/)models\/([^/]+)\//);
+    if (match)
+        return match[1];
+    // No `models/` prefix (e.g. already relative) — take the leading segment.
+    const parts = normalized.split('/').filter(Boolean);
+    return parts.length > 1 ? parts[0] : undefined;
+}
+/** Best-effort domain label from a dbt model node. */
+function domainFromNode(node, folder) {
+    const meta = asRecord(node.meta);
+    const config = asRecord(node.config);
+    const configMeta = asRecord(config.meta);
+    const fqn = Array.isArray(node.fqn) ? node.fqn : [];
+    return firstString(meta.domain, meta.group, configMeta.domain, configMeta.group, config.group, folder && folder !== 'marts' && folder !== 'staging' && folder !== 'intermediate' ? folder : undefined, fqn.length > 1 ? fqn[1] : undefined);
+}
+function readColumns(node) {
+    const columns = asRecord(node.columns);
+    const out = [];
+    for (const [key, raw] of Object.entries(columns)) {
+        const col = asRecord(raw);
+        const name = firstString(col.name, key);
+        if (!name)
+            continue;
+        out.push({
+            name,
+            type: firstString(col.data_type),
+            description: firstString(col.description),
+        });
+    }
+    return out;
+}
+/**
+ * Load all dbt artifacts that live alongside `manifest.json` (same `target/`
+ * directory). Only `manifest.json` is required; the rest are optional and the
+ * loader degrades gracefully when they are missing.
+ */
+export function loadDbtArtifacts(manifestPath) {
+    const manifest = readJson(manifestPath);
+    if (!manifest) {
+        throw new Error(`Could not read or parse dbt manifest at ${manifestPath}`);
+    }
+    const targetDir = manifestPath.replace(/[\\/][^\\/]+$/, '');
+    const projectName = firstString(asRecord(manifest.metadata).project_name);
+    const models = [];
+    const sources = [];
+    const exposures = [];
+    for (const [uniqueId, raw] of Object.entries(asRecord(manifest.nodes))) {
+        const node = asRecord(raw);
+        if (node.resource_type !== 'model')
+            continue;
+        // `name` is the logical model name (used by `{{ ref() }}`); `alias` is the
+        // warehouse relation name. They are usually equal, but when an `alias` is
+        // declared the qualified relation must use it, not the model name.
+        const modelName = firstString(node.name);
+        const alias = firstString(node.alias);
+        const name = alias ?? modelName;
+        if (!name)
+            continue;
+        const refName = modelName ?? name;
+        const schema = firstString(node.schema);
+        const database = firstString(node.database);
+        const path = firstString(node.original_file_path, node.path);
+        const folder = folderFromPath(path);
+        const dependsOn = Array.isArray(asRecord(node.depends_on).nodes)
+            ? asRecord(node.depends_on).nodes.filter((n) => typeof n === 'string')
+            : [];
+        models.push({
+            uniqueId,
+            name,
+            resourceType: 'model',
+            schema,
+            database,
+            alias: alias && alias !== modelName ? alias : undefined,
+            qualifiedRelation: buildQualifiedRelation({ database, schema, name }),
+            refForm: `{{ ref('${refName}') }}`,
+            description: firstString(node.description),
+            materialized: firstString(asRecord(node.config).materialized),
+            tags: Array.isArray(node.tags) ? node.tags.map(String) : [],
+            folder,
+            domainHint: domainFromNode(node, folder),
+            dependsOn,
+            columns: readColumns(node),
+            meta: asRecord(node.meta),
+            config: asRecord(node.config),
+            path,
+        });
+    }
+    for (const [uniqueId, raw] of Object.entries(asRecord(manifest.sources))) {
+        const node = asRecord(raw);
+        const identifier = firstString(node.identifier, node.name);
+        if (!identifier)
+            continue;
+        const schema = firstString(node.schema);
+        const database = firstString(node.database);
+        const sourceName = firstString(node.source_name);
+        sources.push({
+            uniqueId,
+            name: identifier,
+            resourceType: 'source',
+            schema,
+            database,
+            qualifiedRelation: buildQualifiedRelation({ database, schema, name: identifier }),
+            refForm: sourceName ? `{{ source('${sourceName}', '${firstString(node.name) ?? identifier}') }}` : undefined,
+            description: firstString(node.description),
+            tags: Array.isArray(node.tags) ? node.tags.map(String) : [],
+        });
+    }
+    for (const [uniqueId, raw] of Object.entries(asRecord(manifest.exposures))) {
+        const node = asRecord(raw);
+        const dependsOn = Array.isArray(asRecord(node.depends_on).nodes)
+            ? asRecord(node.depends_on).nodes.filter((n) => typeof n === 'string')
+            : [];
+        exposures.push({
+            uniqueId,
+            name: firstString(node.name) ?? uniqueId,
+            dependsOn,
+        });
+    }
+    return {
+        projectName,
+        models,
+        sources,
+        exposures,
+        catalogColumns: loadCatalog(join(targetDir, 'catalog.json')),
+        runCounts: loadRunResults(join(targetDir, 'run_results.json')),
+        ...loadSemantic(manifest, join(targetDir, 'semantic_manifest.json')),
+    };
+}
+/** catalog.json carries warehouse-resolved column types keyed by node uniqueId. */
+function loadCatalog(catalogPath) {
+    const out = new Map();
+    if (!existsSync(catalogPath))
+        return out;
+    const catalog = readJson(catalogPath);
+    if (!catalog)
+        return out;
+    for (const [uniqueId, raw] of Object.entries(asRecord(catalog.nodes))) {
+        const node = asRecord(raw);
+        const columns = asRecord(node.columns);
+        const cols = [];
+        for (const [key, colRaw] of Object.entries(columns)) {
+            const col = asRecord(colRaw);
+            const name = firstString(col.name, key);
+            if (!name)
+                continue;
+            cols.push({ name, type: firstString(col.type), description: firstString(col.comment) });
+        }
+        if (cols.length > 0)
+            out.set(uniqueId, cols);
+    }
+    return out;
+}
+/** run_results.json lists one result per executed node; count occurrences. */
+function loadRunResults(runResultsPath) {
+    const out = new Map();
+    if (!existsSync(runResultsPath))
+        return out;
+    const runResults = readJson(runResultsPath);
+    if (!runResults)
+        return out;
+    const results = Array.isArray(runResults.results) ? runResults.results : [];
+    for (const raw of results) {
+        const result = asRecord(raw);
+        const uniqueId = firstString(result.unique_id);
+        if (!uniqueId)
+            continue;
+        out.set(uniqueId, (out.get(uniqueId) ?? 0) + 1);
+    }
+    return out;
+}
+/**
+ * Load semantic metric references, preferring `semantic_manifest.json` and
+ * falling back to semantic nodes embedded in `manifest.json`. Returns a flag so
+ * the caller can decide whether to attempt metric-wrapper drafts.
+ */
+function loadSemantic(manifest, semanticManifestPath) {
+    let source = null;
+    if (existsSync(semanticManifestPath)) {
+        source = readJson(semanticManifestPath);
+    }
+    // `semantic_manifest.json` carries metrics/semantic_models as ARRAYS, while
+    // the inline `manifest.json` carries them as keyed RECORDS — normalize both to
+    // a flat list of nodes so the loader works on either source.
+    const metricsList = collectionValues(source?.metrics ?? manifest.metrics);
+    const semanticModelsList = collectionValues(source?.semantic_models ?? manifest.semantic_models);
+    // measure name -> model name, so a metric referencing a measure can resolve a
+    // model. A semantic model's underlying dbt model is the alias in its
+    // `node_relation` (MetricFlow shape), else its `name`. Also collect the
+    // measure's agg + expr so a metric can build real aggregation SQL.
+    const measureToModel = new Map();
+    const measureMeta = new Map();
+    const semanticModels = new Map();
+    for (const raw of semanticModelsList) {
+        const semanticModel = asRecord(raw);
+        const modelName = firstString(asRecord(semanticModel.node_relation).alias, semanticModel.name);
+        if (!modelName)
+            continue;
+        const entities = (Array.isArray(semanticModel.entities) ? semanticModel.entities : [])
+            .map((e) => asRecord(e));
+        const entityNames = entities
+            .map((e) => firstString(e.expr, e.name))
+            .filter((v) => Boolean(v));
+        const primaryEntity = firstString(...entities.filter((e) => e.type === 'primary').map((e) => firstString(e.expr, e.name) ?? ''));
+        const dimensions = (Array.isArray(semanticModel.dimensions) ? semanticModel.dimensions : [])
+            .map((d) => asRecord(d));
+        const dimensionNames = dimensions
+            .map((d) => firstString(d.name))
+            .filter((v) => Boolean(v));
+        const timeDimensions = dimensions
+            .filter((d) => d.type === 'time')
+            .map((d) => firstString(d.name))
+            .filter((v) => Boolean(v));
+        semanticModels.set(modelName, {
+            model: modelName,
+            dimensions: dimensionNames,
+            primaryEntity: primaryEntity || undefined,
+            entities: entityNames,
+            timeDimensions,
+        });
+        for (const measureRaw of Array.isArray(semanticModel.measures) ? semanticModel.measures : []) {
+            const measure = asRecord(measureRaw);
+            const measureName = firstString(measure.name);
+            if (!measureName)
+                continue;
+            measureToModel.set(measureName, modelName);
+            measureMeta.set(measureName, {
+                agg: firstString(measure.agg),
+                expr: firstString(measure.expr),
+            });
+        }
+    }
+    const semanticMetrics = [];
+    for (const raw of metricsList) {
+        const metric = asRecord(raw);
+        const name = firstString(metric.name);
+        if (!name)
+            continue;
+        const typeParams = asRecord(metric.type_params);
+        // `type_params.measure` is sometimes a string, sometimes an object { name }.
+        const measure = firstString(typeParams.measure, asRecord(typeParams.measure).name);
+        const meta = measure ? measureMeta.get(measure) : undefined;
+        semanticMetrics.push({
+            name,
+            description: firstString(metric.description),
+            model: measure ? measureToModel.get(measure) : undefined,
+            measure,
+            agg: meta?.agg,
+            expr: meta?.expr,
+            metricType: firstString(metric.type),
+        });
+    }
+    return {
+        hasSemantic: semanticMetrics.length > 0 || semanticModelsList.length > 0,
+        semanticMetrics,
+        semanticModels,
+    };
+}
+/** Flatten a metrics/semantic_models collection that may be an array OR a record. */
+function collectionValues(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === 'object')
+        return Object.values(value);
+    return [];
+}
+//# sourceMappingURL=dbt-artifacts.js.map

package/dist/propose/dbt-artifacts.js.map

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

package/dist/propose/edit-block.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Edit-an-existing-block (spec 17, part A).
+ *
+ * The create path always writes a NEW deduped draft. Users also need to MODIFY
+ * one specific block — add a missed table/column, change the grain — and have it
+ * update the SAME file. `editBlock` loads the block at `blockPath`, asks the
+ * model for the UPDATED block applying the user's change, re-grounds/validates
+ * the SQL via spec-15, and writes the result BACK to the same path. It NEVER
+ * forks a new draft.
+ *
+ * Locked principle (AI drafts, humans certify): the block's status is preserved.
+ * A draft stays `draft`; an already-certified block stays `certified` (the human
+ * must re-certify after an edit). We never silently downgrade or auto-certify.
+ */
+/** Block metadata + SQL loaded from an existing `.dql` file. */
+export interface LoadedBlock {
+    /** Absolute path on disk. */
+    absPath: string;
+    /** Path exactly as supplied by the caller (project-relative or absolute). */
+    requestedPath: string;
+    name: string;
+    blockType: 'semantic' | 'custom';
+    domain?: string;
+    owner?: string;
+    status?: string;
+    description?: string;
+    grain?: string;
+    pattern?: string;
+    entities?: string[];
+    outputs?: string[];
+    tags?: string[];
+    llmContext?: string;
+    invariants?: string[];
+    sourceSystems?: string[];
+    /** The block's current SQL body (raw, with `{{ ref() }}` intact). */
+    sql: string;
+    /** The full original file text (so non-modeled content can be preserved). */
+    rawFile: string;
+}
+/** Parse the existing block file into its SQL + governance metadata. */
+export declare function loadBlockForEdit(projectRoot: string, blockPath: string): LoadedBlock;
+/**
+ * The status the edited block should carry (spec 17, part A locked principle).
+ * Certified stays certified (human must re-certify); everything else stays as-is
+ * or defaults to `draft`. We never auto-certify and never downgrade.
+ */
+export declare function resolveEditedStatus(original?: string): string;
+export interface EditedBlockFields {
+    name: string;
+    blockType: 'semantic' | 'custom';
+    status: string;
+    domain?: string;
+    owner?: string;
+    description?: string;
+    grain?: string;
+    pattern?: string;
+    entities?: string[];
+    outputs?: string[];
+    tags?: string[];
+    llmContext?: string;
+    invariants?: string[];
+    sourceSystems?: string[];
+    sql: string;
+}
+/**
+ * Render the edited block back to canonical DQL text. Preserves name, owner,
+ * domain, grain, and status; updates the SQL + any modeled metadata. A small
+ * header notes the in-place edit (no review verdict is asserted — the human
+ * re-certifies).
+ */
+export declare function renderEditedBlock(fields: EditedBlockFields): string;
+/** Write the edited block back to its original path. Returns the path written. */
+export declare function writeEditedBlock(absPath: string, content: string): string;
+//# sourceMappingURL=edit-block.d.ts.map

package/dist/propose/edit-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-block.d.ts","sourceRoot":"","sources":["../../src/propose/edit-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,UAAU,GAAG,QAAQ,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAuCpF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,UAAU,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;CACb;AAmBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAiCnE;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzE"}

package/dist/propose/edit-block.js

@@ -0,0 +1,133 @@
+/**
+ * Edit-an-existing-block (spec 17, part A).
+ *
+ * The create path always writes a NEW deduped draft. Users also need to MODIFY
+ * one specific block — add a missed table/column, change the grain — and have it
+ * update the SAME file. `editBlock` loads the block at `blockPath`, asks the
+ * model for the UPDATED block applying the user's change, re-grounds/validates
+ * the SQL via spec-15, and writes the result BACK to the same path. It NEVER
+ * forks a new draft.
+ *
+ * Locked principle (AI drafts, humans certify): the block's status is preserved.
+ * A draft stays `draft`; an already-certified block stays `certified` (the human
+ * must re-certify after an edit). We never silently downgrade or auto-certify.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { Parser } from '@duckcodeailabs/dql-core';
+function resolveAbs(projectRoot, blockPath) {
+    return isAbsolute(blockPath) ? blockPath : join(projectRoot, blockPath);
+}
+/** Parse the existing block file into its SQL + governance metadata. */
+export function loadBlockForEdit(projectRoot, blockPath) {
+    const absPath = resolveAbs(projectRoot, blockPath);
+    if (!existsSync(absPath)) {
+        throw new Error(`Block file not found for edit: ${blockPath}`);
+    }
+    const rawFile = readFileSync(absPath, 'utf-8');
+    const ast = new Parser(rawFile, blockPath).parse();
+    const block = ast.statements.find((stmt) => stmt.kind === 'BlockDecl');
+    if (!block) {
+        throw new Error(`No block declaration found in ${blockPath}`);
+    }
+    const asStr = (v) => typeof v === 'string' && v.trim() ? v.trim() : undefined;
+    const asArr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+    const query = block.query;
+    return {
+        absPath,
+        requestedPath: blockPath,
+        name: asStr(block.name) ?? 'block',
+        blockType: block.blockType === 'semantic' ? 'semantic' : 'custom',
+        domain: asStr(block.domain),
+        owner: asStr(block.owner),
+        status: asStr(block.status),
+        description: asStr(block.description),
+        grain: asStr(block.grain),
+        pattern: asStr(block.pattern),
+        entities: asArr(block.entities),
+        outputs: asArr(block.outputs),
+        tags: asArr(block.tags),
+        llmContext: asStr(block.llmContext),
+        invariants: asArr(block.invariants),
+        sourceSystems: asArr(block.sourceSystems),
+        sql: (query?.rawSQL ?? '').trim(),
+        rawFile,
+    };
+}
+/**
+ * The status the edited block should carry (spec 17, part A locked principle).
+ * Certified stays certified (human must re-certify); everything else stays as-is
+ * or defaults to `draft`. We never auto-certify and never downgrade.
+ */
+export function resolveEditedStatus(original) {
+    const status = (original ?? '').trim().toLowerCase();
+    if (status === 'certified')
+        return 'certified';
+    if (status)
+        return status;
+    return 'draft';
+}
+function escapeString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function stringArrayLine(name, values) {
+    if (!values || values.length === 0)
+        return '';
+    return `\n  ${name} = [${values.map((v) => `"${escapeString(v)}"`).join(', ')}]`;
+}
+function indent(text, spaces) {
+    const pad = ' '.repeat(spaces);
+    return text
+        .split('\n')
+        .map((line) => (line.length > 0 ? pad + line : line))
+        .join('\n');
+}
+/**
+ * Render the edited block back to canonical DQL text. Preserves name, owner,
+ * domain, grain, and status; updates the SQL + any modeled metadata. A small
+ * header notes the in-place edit (no review verdict is asserted — the human
+ * re-certifies).
+ */
+export function renderEditedBlock(fields) {
+    const lines = [`block "${escapeString(fields.name)}" {`];
+    lines.push(`  type = "${fields.blockType}"`);
+    if (fields.domain)
+        lines.push(`  domain = "${escapeString(fields.domain)}"`);
+    lines.push(`  status = "${escapeString(fields.status)}"`);
+    if (fields.description)
+        lines.push(`  description = "${escapeString(fields.description)}"`);
+    if (fields.owner)
+        lines.push(`  owner = "${escapeString(fields.owner)}"`);
+    if (fields.pattern)
+        lines.push(`  pattern = "${escapeString(fields.pattern)}"`);
+    if (fields.grain)
+        lines.push(`  grain = "${escapeString(fields.grain)}"`);
+    const arrays = [
+        stringArrayLine('entities', fields.entities),
+        stringArrayLine('outputs', fields.outputs),
+        stringArrayLine('sourceSystems', fields.sourceSystems),
+        stringArrayLine('tags', fields.tags),
+        stringArrayLine('invariants', fields.invariants),
+    ].join('');
+    if (fields.llmContext)
+        lines.push(`  llmContext = "${escapeString(fields.llmContext)}"`);
+    const body = [
+        '// dql-format: 1',
+        `// Updated in place by AI build (edit mode). status preserved as "${fields.status}".`,
+        `// AI drafts, humans certify — review the change${fields.status === 'certified' ? ', then re-certify this block.' : '.'}`,
+        lines.join('\n') + arrays,
+        '',
+        '  query = """',
+        indent(fields.sql, 4),
+        '  """',
+        '}',
+        '',
+    ];
+    return body.join('\n');
+}
+/** Write the edited block back to its original path. Returns the path written. */
+export function writeEditedBlock(absPath, content) {
+    writeFileSync(absPath, content, 'utf-8');
+    return absPath;
+}
+//# sourceMappingURL=edit-block.js.map

package/dist/propose/edit-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-block.js","sourceRoot":"","sources":["../../src/propose/edit-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AA4BlD,SAAS,UAAU,CAAC,WAAmB,EAAE,SAAiB;IACxD,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAC1E,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,SAAiB;IACrE,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,kCAAkC,SAAS,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAE,IAA0B,CAAC,IAAI,KAAK,WAAW,CAE/E,CAAC;IACd,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,iCAAiC,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,CAAU,EAAsB,EAAE,CAC/C,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,MAAM,KAAK,GAAG,CAAC,CAAU,EAAwB,EAAE,CACjD,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAwC,CAAC;IAE7D,OAAO;QACL,OAAO;QACP,aAAa,EAAE,SAAS;QACxB,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO;QAClC,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;QACjE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;QAC3B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;QACzB,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;QAC3B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;QACrC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;QACzB,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC/B,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;QAC7B,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;QACvB,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;QACnC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;QACnC,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC;QACzC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACjC,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,MAAM,MAAM,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrD,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAC/C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,OAAO,OAAO,CAAC;AACjB,CAAC;AAoBD,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,MAA4B;IACjE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9C,OAAO,OAAO,IAAI,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACnF,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SACpD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IACzD,MAAM,KAAK,GAAa,CAAC,UAAU,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,eAAe,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7E,KAAK,CAAC,IAAI,CAAC,eAAe,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC5F,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1E,IAAI,MAAM,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChF,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG;QACb,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC;QAC5C,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;QAC1C,eAAe,CAAC,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC;QACtD,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC;QACpC,eAAe,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,CAAC;KACjD,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACX,IAAI,MAAM,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAEzF,MAAM,IAAI,GAAG;QACX,kBAAkB;QAClB,qEAAqE,MAAM,CAAC,MAAM,IAAI;QACtF,mDACE,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,GACpE,EAAE;QACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM;QACzB,EAAE;QACF,eAAe;QACf,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;QACrB,OAAO;QACP,GAAG;QACH,EAAE;KACH,CAAC;IACF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAe;IAC/D,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACzC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/propose/enrich.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Optional AI enrichment for proposed draft blocks.
+ *
+ * Principle (spec 13): **structure deterministic, content AI-optional.** The
+ * propose engine (`propose.ts`) is fully deterministic — classification, grain,
+ * outputs, SQL, ranking, selection. This module is the *only* place an LLM is
+ * used, and only to improve human-facing *content* — `description`, `llmContext`,
+ * and example questions — for the bounded set the human approved.
+ *
+ * It is best-effort and isolated: every call has a timeout, any failure (no
+ * provider, network, bad JSON, timeout) returns `null` and the caller keeps the
+ * deterministic dbt-derived content. The engine consumes the result as plain
+ * data (`ProposeOptions.enrichedBySlug`); it never calls a provider itself.
+ */
+import type { AgentProvider } from '../providers/types.js';
+export interface EnrichFacts {
+    slug: string;
+    model: string;
+    domain: string;
+    /** dbt model description, when present. */
+    description?: string;
+    grain?: string;
+    pattern: string;
+    /** Output column names. */
+    columns: string[];
+    entities: string[];
+    /** Semantic metric the model backs, when any. */
+    metric?: string;
+}
+export interface EnrichedContent {
+    description?: string;
+    llmContext?: string;
+    examples?: string[];
+}
+export interface EnrichOptions {
+    /** Per-call timeout in ms (default 25s — local models are slow). */
+    timeoutMs?: number;
+    /** Max concurrent provider calls (default 4). */
+    concurrency?: number;
+}
+/** Enrich a single proposal. Best-effort: returns null on any failure/timeout. */
+export declare function enrichProposal(facts: EnrichFacts, provider: AgentProvider, options?: EnrichOptions): Promise<EnrichedContent | null>;
+/**
+ * Enrich many proposals with bounded concurrency. Always resolves (best-effort);
+ * proposals that fail simply stay deterministic. Keyed by slug.
+ */
+export declare function enrichProposals(items: EnrichFacts[], provider: AgentProvider, options?: EnrichOptions): Promise<Map<string, EnrichedContent>>;
+//# sourceMappingURL=enrich.d.ts.map

package/dist/propose/enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.d.ts","sourceRoot":"","sources":["../../src/propose/enrich.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2ED,kFAAkF;AAClF,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAcjC;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,WAAW,EAAE,EACpB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAavC"}