@duckcodeailabs/dql-core 1.6.21 → 1.6.22

package/dist/manifest/dbt-freshness.js

@@ -0,0 +1,264 @@
+/**
+ * Freshness-aware trust — read dbt run artifacts (READ-ONLY) and fold data
+ * health into the effective trust of certified blocks.
+ *
+ * "Certified" means the *logic* was reviewed. It says nothing about whether the
+ * *data* behind a block is fresh: an upstream dbt model may have failed its last
+ * run, or be past its freshness window. This module reads dbt's own artifacts —
+ * `run_results.json` (last-run status/time per model) and, when present, the
+ * source-freshness output — and derives a {@link DbtDataState} per dbt node. It
+ * then rolls those up to each certified block's transitive dbt upstreams so a
+ * surface can render "Certified · stale data" / "Certified · upstream failed".
+ *
+ * We never run dbt or query the warehouse — we only parse files dbt produced.
+ * Everything degrades to `unknown` (which surfaces as the plain "Certified"
+ * label) when an artifact is missing or unparseable, so this is fully additive.
+ *
+ * Kept in a dedicated module so `manifest/builder.ts` only needs a couple of
+ * call sites, keeping its diff minimal and merge-clean with the sibling
+ * `outputContract`/`drift` change.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Worst-first ordering used when rolling many upstream states into one. */
+const STATE_SEVERITY = {
+    failed: 3,
+    stale: 2,
+    unknown: 1,
+    fresh: 0,
+};
+/** Return the worse (higher-severity) of two data states. */
+export function worseDataState(a, b) {
+    return STATE_SEVERITY[a] >= STATE_SEVERITY[b] ? a : b;
+}
+/**
+ * Resolve and read dbt's `run_results.json` (and source-freshness output, when
+ * a separate `sources.json` sits beside it) from the directory holding the dbt
+ * `manifest.json`. Returns an empty index — never throws — when nothing is
+ * found or the file cannot be parsed.
+ *
+ * dbt writes both `manifest.json` and `run_results.json` into the same
+ * `target/` directory, so we look beside `manifestPath`.
+ */
+export function loadDbtRunState(manifestPath) {
+    const targetDir = dirname(manifestPath);
+    const byUniqueId = new Map();
+    const runResultsPath = join(targetDir, 'run_results.json');
+    let foundPath;
+    if (existsSync(runResultsPath)) {
+        try {
+            const raw = JSON.parse(readFileSync(runResultsPath, 'utf-8'));
+            const generatedAt = raw?.metadata?.generated_at;
+            const results = Array.isArray(raw?.results) ? raw.results : [];
+            for (const result of results) {
+                const uniqueId = result?.unique_id;
+                if (!uniqueId)
+                    continue;
+                byUniqueId.set(uniqueId, runStateFromRunResult(result, generatedAt));
+            }
+            if (results.length > 0)
+                foundPath = runResultsPath;
+        }
+        catch {
+            // Unparseable artifact — degrade silently to "unknown" everywhere.
+        }
+    }
+    // Optional source-freshness output. dbt's `source freshness` command writes a
+    // `sources.json` beside the manifest; fold any stale/error verdicts in. This
+    // overrides/augments run-result state for source nodes only.
+    const sourcesPath = join(targetDir, 'sources.json');
+    if (existsSync(sourcesPath)) {
+        try {
+            const raw = JSON.parse(readFileSync(sourcesPath, 'utf-8'));
+            const results = Array.isArray(raw?.results) ? raw.results : [];
+            for (const result of results) {
+                const uniqueId = result?.unique_id;
+                if (!uniqueId)
+                    continue;
+                const freshness = freshnessFromSourceResult(result);
+                if (!freshness)
+                    continue;
+                const existing = byUniqueId.get(uniqueId);
+                byUniqueId.set(uniqueId, {
+                    dataState: existing
+                        ? worseDataState(existing.dataState, freshness.dataState)
+                        : freshness.dataState,
+                    lastRunStatus: existing?.lastRunStatus,
+                    lastRunCompletedAt: existing?.lastRunCompletedAt,
+                    freshnessStatus: freshness.freshnessStatus,
+                    maxLoadedAt: freshness.maxLoadedAt,
+                });
+            }
+            if (results.length > 0)
+                foundPath = foundPath ?? sourcesPath;
+        }
+        catch {
+            // Ignore — freshness is best-effort.
+        }
+    }
+    return { byUniqueId, runResultsPath: foundPath };
+}
+/** Map one `run_results.json` entry to a {@link DbtRunState}. */
+function runStateFromRunResult(result, generatedAt) {
+    const status = result?.status;
+    // Prefer the precise per-node execute completion time from `timing`; fall back
+    // to the artifact's `generated_at` so we always carry *some* "as of" time.
+    const timing = Array.isArray(result?.timing) ? result.timing : [];
+    const executeCompletedAt = timing.find((t) => t?.name === 'execute')?.completed_at;
+    return {
+        dataState: dataStateFromRunStatus(status),
+        lastRunStatus: status,
+        lastRunCompletedAt: executeCompletedAt ?? generatedAt,
+    };
+}
+/**
+ * dbt run statuses: model runs report `success` | `error` | `skipped`; tests
+ * report `pass` | `fail` | `warn` | `error`. A failed or skipped upstream means
+ * the data may be missing or wrong → `failed`. Success → `fresh`. Anything
+ * unrecognized → `unknown` (no opinion).
+ */
+function dataStateFromRunStatus(status) {
+    switch (status) {
+        case 'success':
+        case 'pass':
+            return 'fresh';
+        case 'error':
+        case 'fail':
+        case 'skipped':
+        case 'runtime error':
+            return 'failed';
+        default:
+            return 'unknown';
+    }
+}
+/** Map one source-freshness result to a freshness state. */
+function freshnessFromSourceResult(result) {
+    const status = result?.status ?? result?.criteria?.status;
+    const maxLoadedAt = result?.max_loaded_at ?? result?.criteria?.max_loaded_at;
+    switch (status) {
+        case 'pass':
+            return { dataState: 'fresh', freshnessStatus: status, maxLoadedAt };
+        case 'warn':
+        case 'error':
+            // A freshness warn/error means the data is past its window: stale, not a
+            // hard run failure.
+            return { dataState: 'stale', freshnessStatus: status, maxLoadedAt };
+        case 'runtime error':
+            return { dataState: 'failed', freshnessStatus: status, maxLoadedAt };
+        default:
+            return status ? { dataState: 'unknown', freshnessStatus: status, maxLoadedAt } : undefined;
+    }
+}
+/**
+ * Compute each certified block's effective `dataState` from the health of its
+ * transitive dbt upstreams, mutating blocks additively in place.
+ *
+ * Resolution: a block's `tableDependencies` name dbt models/sources; we resolve
+ * each to a `sources[...]` entry that carries a `dbtModel.uniqueId`, then walk
+ * upstream through the dbt DAG (`edges`: source → target uniqueId) collecting
+ * every reachable node's run state. The block's `dataState` is the worst state
+ * among them. Blocks with no resolvable dbt upstream are left untouched.
+ *
+ * Only acts when a run-results artifact was actually read — without it every
+ * node is `unknown` and we leave blocks alone so nothing regresses to a noisy
+ * "· data freshness unknown" qualifier.
+ */
+export function applyBlockDataState(blocks, sources, dbtDag, runState) {
+    if (runState.byUniqueId.size === 0)
+        return;
+    // uniqueId -> upstream uniqueIds (reverse of edges' source→target direction;
+    // an edge {source, target} means target depends on source).
+    const upstream = new Map();
+    for (const edge of dbtDag?.edges ?? []) {
+        const list = upstream.get(edge.target) ?? [];
+        list.push(edge.source);
+        upstream.set(edge.target, list);
+    }
+    // table name -> dbt uniqueId, via the sources map. Block table refs may be
+    // schema-qualified (`dev.customers`) while the dbt-model source is named bare
+    // (`customers`), so index every alias: the source name plus the model's
+    // bare / schema-qualified / db-qualified names derived from its dbt metadata.
+    const tableToUniqueId = new Map();
+    const addTableKey = (key, uid) => {
+        if (!key)
+            return;
+        const k = key.toLowerCase();
+        if (!tableToUniqueId.has(k))
+            tableToUniqueId.set(k, uid);
+    };
+    for (const source of Object.values(sources)) {
+        const dm = source.dbtModel;
+        if (!dm?.uniqueId)
+            continue;
+        addTableKey(source.name, dm.uniqueId);
+        const bare = dm.uniqueId.split('.').pop();
+        addTableKey(bare, dm.uniqueId);
+        if (dm.schema && bare)
+            addTableKey(`${dm.schema}.${bare}`, dm.uniqueId);
+        if (dm.database && dm.schema && bare)
+            addTableKey(`${dm.database}.${dm.schema}.${bare}`, dm.uniqueId);
+    }
+    // A node's own state, or `undefined` when dbt produced no run/freshness result
+    // for it (e.g. raw sources never "run"). Unstated nodes are NEUTRAL — being in
+    // a block's lineage must not drag it to "unknown" just because a source has no
+    // run record.
+    const stateFor = (uid) => runState.byUniqueId.get(uid)?.dataState;
+    // Memoised worst KNOWN state over the transitive upstream closure of a node.
+    const closureCache = new Map();
+    const worstUpstream = (uid, seen = new Set()) => {
+        if (closureCache.has(uid))
+            return closureCache.get(uid);
+        if (seen.has(uid))
+            return stateFor(uid);
+        seen.add(uid);
+        let worst = stateFor(uid);
+        for (const up of upstream.get(uid) ?? []) {
+            const s = worstUpstream(up, seen);
+            if (s !== undefined)
+                worst = worst === undefined ? s : worseDataState(worst, s);
+        }
+        closureCache.set(uid, worst);
+        return worst;
+    };
+    for (const block of Object.values(blocks)) {
+        const upstreamUids = [];
+        for (const table of block.tableDependencies ?? []) {
+            const lower = table.toLowerCase();
+            const uid = tableToUniqueId.get(lower) ?? tableToUniqueId.get(lower.split('.').pop() ?? lower);
+            if (uid)
+                upstreamUids.push(uid);
+        }
+        if (upstreamUids.length === 0)
+            continue;
+        let worst;
+        let worstUid;
+        for (const uid of upstreamUids) {
+            const state = worstUpstream(uid);
+            if (state === undefined)
+                continue;
+            if (worst === undefined || STATE_SEVERITY[state] > STATE_SEVERITY[worst]) {
+                worst = state;
+                worstUid = uid;
+            }
+        }
+        if (worst === undefined)
+            continue;
+        block.dataState = worst;
+        block.dataStateDetail = describeBlockDataState(worst, worstUid, runState);
+    }
+}
+function describeBlockDataState(state, worstUid, runState) {
+    if (state === 'fresh')
+        return 'All upstream dbt models are fresh (last run succeeded).';
+    const node = worstUid ? runState.byUniqueId.get(worstUid) : undefined;
+    const shortName = worstUid?.split('.').pop();
+    switch (state) {
+        case 'failed':
+            return `Upstream dbt model${shortName ? ` "${shortName}"` : ''} last run failed${node?.lastRunStatus ? ` (status: ${node.lastRunStatus})` : ''}.`;
+        case 'stale':
+            return `Upstream data${shortName ? ` from "${shortName}"` : ''} is past its freshness window${node?.freshnessStatus ? ` (freshness: ${node.freshnessStatus})` : ''}.`;
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=dbt-freshness.js.map

package/dist/manifest/dbt-freshness.js.map

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

package/dist/manifest/domain-writer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Domain declaration writer (spec 17, part B).
+ *
+ * `scanDomains` reads first-class `domain "<Name>" { ... }` declarations and
+ * `dql doctor` warns when a used domain has no such declaration — but until now
+ * there was no way to AUTHOR one. This module emits a `domain` declaration in
+ * the EXACT format the parser (`parseDomainDecl`) + `scanDomains` accept, and
+ * resolves the canonical on-disk location for it.
+ *
+ * Convention (matches `scanDomains` + the "domain-first folders" test):
+ *   domains/<slug>/domain.dql      ← when a domain folder exists or is chosen
+ *   domains/<slug>/domain.dql      ← created if absent (the writer makes the dir)
+ *
+ * A domain authored here is `name`, `owner`, `boundedContext`, `sourceSystems`,
+ * `description`. `reviewCadence` is included with a sensible default so the
+ * doctor's "missing reviewCadence" warning is also satisfied.
+ */
+/** A domain authored through the writer (spec 17, part B). */
+export interface DomainInput {
+    name: string;
+    owner?: string;
+    boundedContext?: string;
+    sourceSystems?: string[];
+    description?: string;
+    /** Optional review cadence; defaults to "quarterly" so doctor stays quiet. */
+    reviewCadence?: string;
+}
+export interface WrittenDomain {
+    /** Project-relative path of the written `domain.dql`. */
+    path: string;
+    /** Absolute path on disk. */
+    absPath: string;
+    /** The folder slug under `domains/`. */
+    slug: string;
+}
+/** Normalize a domain name/id into a folder slug under `domains/`. */
+export declare function domainFolderSlug(value: string): string;
+/**
+ * Render a first-class `domain` declaration that `scanDomains` reads back. The
+ * field order + syntax mirror the parser's accepted set so a round-trip is
+ * lossless for the authored fields.
+ */
+export declare function renderDomainDeclaration(domain: DomainInput): string;
+/**
+ * Resolve the canonical `domains/<slug>/domain.dql` path for a domain. Honors an
+ * EXISTING `domain.dql` anywhere under `domains/<slug>/` (so a PUT/DELETE finds
+ * the file `scanDomains` actually read), else falls back to the canonical path.
+ */
+export declare function resolveDomainDeclPath(projectRoot: string, nameOrSlug: string): {
+    absPath: string;
+    relativePath: string;
+    slug: string;
+};
+/**
+ * Write (create or overwrite) a first-class domain declaration. Returns the path
+ * written. The folder is created so subsequent block authoring can place blocks
+ * under `domains/<slug>/blocks/`.
+ */
+export declare function writeDomainDeclaration(projectRoot: string, domain: DomainInput): WrittenDomain;
+/**
+ * Delete a domain declaration file. Returns true when a file was removed. Only
+ * the declaration `.dql` is removed — authored blocks/terms under the folder are
+ * left untouched.
+ */
+export declare function deleteDomainDeclaration(projectRoot: string, nameOrSlug: string): boolean;
+//# sourceMappingURL=domain-writer.d.ts.map

package/dist/manifest/domain-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-writer.d.ts","sourceRoot":"","sources":["../../src/manifest/domain-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQtD;AAOD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAWnE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOzD;AAkBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,aAAa,CAQ9F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAKxF"}

package/dist/manifest/domain-writer.js

@@ -0,0 +1,114 @@
+/**
+ * Domain declaration writer (spec 17, part B).
+ *
+ * `scanDomains` reads first-class `domain "<Name>" { ... }` declarations and
+ * `dql doctor` warns when a used domain has no such declaration — but until now
+ * there was no way to AUTHOR one. This module emits a `domain` declaration in
+ * the EXACT format the parser (`parseDomainDecl`) + `scanDomains` accept, and
+ * resolves the canonical on-disk location for it.
+ *
+ * Convention (matches `scanDomains` + the "domain-first folders" test):
+ *   domains/<slug>/domain.dql      ← when a domain folder exists or is chosen
+ *   domains/<slug>/domain.dql      ← created if absent (the writer makes the dir)
+ *
+ * A domain authored here is `name`, `owner`, `boundedContext`, `sourceSystems`,
+ * `description`. `reviewCadence` is included with a sensible default so the
+ * doctor's "missing reviewCadence" warning is also satisfied.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+function escapeString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** Normalize a domain name/id into a folder slug under `domains/`. */
+export function domainFolderSlug(value) {
+    return (value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'domain');
+}
+function stringArrayField(name, values) {
+    if (!values || values.length === 0)
+        return '';
+    return `\n  ${name} = [${values.map((v) => `"${escapeString(v)}"`).join(', ')}]`;
+}
+/**
+ * Render a first-class `domain` declaration that `scanDomains` reads back. The
+ * field order + syntax mirror the parser's accepted set so a round-trip is
+ * lossless for the authored fields.
+ */
+export function renderDomainDeclaration(domain) {
+    const reviewCadence = domain.reviewCadence?.trim() || 'quarterly';
+    const lines = [`domain "${escapeString(domain.name)}" {`];
+    if (domain.owner)
+        lines.push(`  owner = "${escapeString(domain.owner)}"`);
+    if (domain.boundedContext)
+        lines.push(`  boundedContext = "${escapeString(domain.boundedContext)}"`);
+    lines.push(`  reviewCadence = "${escapeString(reviewCadence)}"`);
+    let body = lines.join('\n');
+    body += stringArrayField('sourceSystems', domain.sourceSystems);
+    if (domain.description)
+        body += `\n  description = "${escapeString(domain.description)}"`;
+    body += '\n}\n';
+    return body;
+}
+/**
+ * Resolve the canonical `domains/<slug>/domain.dql` path for a domain. Honors an
+ * EXISTING `domain.dql` anywhere under `domains/<slug>/` (so a PUT/DELETE finds
+ * the file `scanDomains` actually read), else falls back to the canonical path.
+ */
+export function resolveDomainDeclPath(projectRoot, nameOrSlug) {
+    const slug = domainFolderSlug(nameOrSlug);
+    const domainDir = join(projectRoot, 'domains', slug);
+    // Prefer an existing declaration file (any `*.dql` that declares this domain).
+    const existing = findExistingDomainFile(domainDir);
+    const absPath = existing ?? join(domainDir, 'domain.dql');
+    return { absPath, relativePath: relative(projectRoot, absPath), slug };
+}
+/** Find an existing `.dql` file under a domain folder that declares a domain. */
+function findExistingDomainFile(domainDir) {
+    if (!existsSync(domainDir))
+        return undefined;
+    try {
+        for (const entry of readdirSync(domainDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.dql'))
+                continue;
+            const file = join(domainDir, entry.name);
+            const source = readFileSync(file, 'utf-8');
+            if (/(^|\n)\s*domain\s+"/.test(source))
+                return file;
+        }
+    }
+    catch {
+        // Best-effort.
+    }
+    return undefined;
+}
+/**
+ * Write (create or overwrite) a first-class domain declaration. Returns the path
+ * written. The folder is created so subsequent block authoring can place blocks
+ * under `domains/<slug>/blocks/`.
+ */
+export function writeDomainDeclaration(projectRoot, domain) {
+    if (!domain.name || !domain.name.trim()) {
+        throw new Error('writeDomainDeclaration requires a non-empty domain name.');
+    }
+    const { absPath, relativePath, slug } = resolveDomainDeclPath(projectRoot, domain.name);
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, renderDomainDeclaration(domain), 'utf-8');
+    return { path: relativePath, absPath, slug };
+}
+/**
+ * Delete a domain declaration file. Returns true when a file was removed. Only
+ * the declaration `.dql` is removed — authored blocks/terms under the folder are
+ * left untouched.
+ */
+export function deleteDomainDeclaration(projectRoot, nameOrSlug) {
+    const { absPath } = resolveDomainDeclPath(projectRoot, nameOrSlug);
+    if (!existsSync(absPath))
+        return false;
+    rmSync(absPath, { force: true });
+    return true;
+}
+//# sourceMappingURL=domain-writer.js.map

package/dist/manifest/domain-writer.js.map

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

package/dist/manifest/index.d.ts

@@ -1,3 +1,6 @@
 export { buildManifest, collectInputFiles, loadProjectConfig, resolveDataLexManifestPath, resolveDbtManifestPath, type ManifestBuildOptions, type DbtImportFilters, } from './builder.js';
-export type { DQLManifest, ManifestBlock, ManifestTerm, ManifestBusinessView, ManifestNotebook, ManifestNotebookCell, ManifestMetric, ManifestDimension, ManifestSource, ManifestLineage, ManifestLineageNode, ManifestLineageEdge, ManifestDbtImport, ManifestDiagnostic, ManifestApp, ManifestDashboard, } from './types.js';
+export { detectOutputDrift } from './output-drift.js';
+export { writeDomainDeclaration, deleteDomainDeclaration, renderDomainDeclaration, resolveDomainDeclPath, domainFolderSlug, type DomainInput, type WrittenDomain, } from './domain-writer.js';
+export { loadDbtRunState, applyBlockDataState, worseDataState, type DbtRunStateIndex, } from './dbt-freshness.js';
+export type { DQLManifest, ManifestBlock, ManifestDomain, ManifestTerm, ManifestBusinessView, ManifestNotebook, ManifestNotebookCell, ManifestMetric, ManifestDimension, ManifestSource, ManifestLineage, ManifestLineageNode, ManifestLineageEdge, ManifestDbtImport, ManifestDiagnostic, ManifestConflictDetail, ManifestConflictSide, ManifestDriftDetail, ManifestApp, ManifestDashboard, DbtDataState, DbtRunState, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/manifest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,WAAW,EACX,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/manifest/index.js

@@ -1,3 +1,6 @@
 // Manifest — DQL project compilation artifact
 export { buildManifest, collectInputFiles, loadProjectConfig, resolveDataLexManifestPath, resolveDbtManifestPath, } from './builder.js';
+export { detectOutputDrift } from './output-drift.js';
+export { writeDomainDeclaration, deleteDomainDeclaration, renderDomainDeclaration, resolveDomainDeclPath, domainFolderSlug, } from './domain-writer.js';
+export { loadDbtRunState, applyBlockDataState, worseDataState, } from './dbt-freshness.js';
 //# sourceMappingURL=index.js.map

package/dist/manifest/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,GAGvB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,GAGvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,GAGjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,GAEf,MAAM,oBAAoB,CAAC"}

package/dist/manifest/output-drift.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Output-contract drift detection.
+ *
+ * DQL composition is intentionally unbounded freeform `ref()` between blocks.
+ * The cost of that freedom: when a child block changes its output columns, a
+ * parent that `ref()`s it can break *silently*. We do not restrict composition
+ * — instead we make drift *visible*.
+ *
+ * This pass compares the columns a parent block references on a `ref()`'d child
+ * (extracted from the parent's SQL) against the child's current `outputContract`
+ * (its actual output schema). A referenced column that is missing/renamed
+ * produces a `kind: 'drift'`, `severity: 'warning'` diagnostic naming the
+ * parent, the child, and the drifted column. It never fails the build, and
+ * additive changes (the child gaining new columns) produce no warning.
+ *
+ * Non-goals (explicitly rejected — see the feature spec):
+ *   - Hard compile-time parent→child binding / failing the build.
+ *   - Runtime enforcement.
+ */
+import type { ManifestBlock, ManifestDiagnostic } from './types.js';
+/**
+ * Detect output-contract drift across all blocks. For each parent block that
+ * `ref()`s a child block and references one of its columns, warn when that
+ * column is no longer in the child's `outputContract`.
+ *
+ * Conservative on every axis: unknown child schemas, unparseable parent SQL,
+ * and ambiguous (multi-source, unqualified) column references all yield no
+ * warning rather than a false positive — see `extractRefColumnUsage`.
+ */
+export declare function detectOutputDrift(blocks: Record<string, ManifestBlock>): ManifestDiagnostic[];
+//# sourceMappingURL=output-drift.d.ts.map

package/dist/manifest/output-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-drift.d.ts","sourceRoot":"","sources":["../../src/manifest/output-drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA4BpE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,kBAAkB,EAAE,CA0C7F"}

package/dist/manifest/output-drift.js

@@ -0,0 +1,97 @@
+/**
+ * Output-contract drift detection.
+ *
+ * DQL composition is intentionally unbounded freeform `ref()` between blocks.
+ * The cost of that freedom: when a child block changes its output columns, a
+ * parent that `ref()`s it can break *silently*. We do not restrict composition
+ * — instead we make drift *visible*.
+ *
+ * This pass compares the columns a parent block references on a `ref()`'d child
+ * (extracted from the parent's SQL) against the child's current `outputContract`
+ * (its actual output schema). A referenced column that is missing/renamed
+ * produces a `kind: 'drift'`, `severity: 'warning'` diagnostic naming the
+ * parent, the child, and the drifted column. It never fails the build, and
+ * additive changes (the child gaining new columns) produce no warning.
+ *
+ * Non-goals (explicitly rejected — see the feature spec):
+ *   - Hard compile-time parent→child binding / failing the build.
+ *   - Runtime enforcement.
+ */
+import { extractRefColumnUsage } from '../lineage/column-lineage.js';
+/** Case-insensitive column-name key for comparing referenced vs. declared columns. */
+function columnKey(name) {
+    return name.trim().toLowerCase();
+}
+/**
+ * The set of columns a child block guarantees, derived from its
+ * `outputContract`. Returns `null` when the child's output schema is unknown
+ * (no contract, or a contract that includes a star/unresolved entry) — in that
+ * case we cannot tell a real rename from an unparsed projection, so we stay
+ * silent rather than emit a false positive.
+ */
+function knownChildColumns(child) {
+    const contract = child.outputContract;
+    if (!contract || contract.length === 0)
+        return null;
+    const names = new Set();
+    for (const entry of contract) {
+        const name = entry.name?.trim();
+        // A `*` / wildcard contract entry means the schema is open — we can't
+        // distinguish a renamed column from a still-present one.
+        if (!name || name === '*' || name.endsWith('.*'))
+            return null;
+        names.add(columnKey(name));
+    }
+    return names;
+}
+/**
+ * Detect output-contract drift across all blocks. For each parent block that
+ * `ref()`s a child block and references one of its columns, warn when that
+ * column is no longer in the child's `outputContract`.
+ *
+ * Conservative on every axis: unknown child schemas, unparseable parent SQL,
+ * and ambiguous (multi-source, unqualified) column references all yield no
+ * warning rather than a false positive — see `extractRefColumnUsage`.
+ */
+export function detectOutputDrift(blocks) {
+    const diagnostics = [];
+    for (const parent of Object.values(blocks)) {
+        if (!parent.sql || !(parent.refDependencies?.length))
+            continue;
+        const usages = extractRefColumnUsage(parent.sql);
+        if (usages.length === 0)
+            continue;
+        for (const usage of usages) {
+            const child = blocks[usage.block];
+            if (!child)
+                continue; // unresolved ref — handled elsewhere as a resolve diagnostic
+            if (child.name === parent.name)
+                continue; // self-reference, ignore
+            const childColumns = knownChildColumns(child);
+            if (!childColumns)
+                continue; // child schema unknown — cannot judge drift
+            const available = (child.outputContract ?? []).map((c) => c.name);
+            for (const referenced of usage.columns) {
+                if (childColumns.has(columnKey(referenced)))
+                    continue;
+                diagnostics.push({
+                    kind: 'drift',
+                    filePath: parent.filePath,
+                    severity: 'warning',
+                    message: `block "${parent.name}" references column "${referenced}" on ref("${child.name}"), ` +
+                        `but "${child.name}" no longer outputs it` +
+                        (available.length > 0 ? ` (current outputs: ${available.join(', ')})` : '') +
+                        `. The child's output contract drifted — update the reference or restore the column.`,
+                    drift: {
+                        parentBlock: parent.name,
+                        childBlock: child.name,
+                        column: referenced,
+                        availableColumns: available,
+                    },
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=output-drift.js.map

package/dist/manifest/output-drift.js.map

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