dsh-data-quality 0.1.0

package/lib/index.js

@@ -0,0 +1,2458 @@
+import z from "@deepseek-ai/schemastery";
+import z$1 from "zod";
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+import { mkdir, open, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { KNOWN_SESSION_EVENT_TYPES } from "@deepseek-ai/dsh-session";
+import { Service } from "@deepseek-ai/cordis";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/config.ts
+/**
+* Config schema and resolution for `dsh-data-quality`. Every tunable is a
+* validated {@link Config} field changeable from cordis.yml; the resolution
+* step validates bounds so misconfiguration fails loud at mount.
+* @module dsh-data-quality/config
+*/
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+const Config = z.object({
+	enabled: z.boolean().default(true),
+	maxRows: z.number().default(2e5),
+	maxFileSizeMB: z.number().default(64),
+	defaultTolerance: z.number().default(1e-9),
+	evidenceRowLimit: z.number().default(20),
+	allowedExtensions: z.array(z.string()).default([
+		".csv",
+		".tsv",
+		".json",
+		".jsonl"
+	]),
+	workspaceRoot: z.string().default(""),
+	storeReports: z.boolean().default(true)
+});
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name, value) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`);
+}
+/** Throw unless `value` is a finite number in `[min, max]`. */
+function assertFiniteRange(name, value, min, max) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`);
+}
+/**
+* Validate raw values and fill explicit defaults. Invalid bounds throw here —
+* misconfiguration fails loud at mount even without the Schemastery loader.
+* @param config - raw (possibly partial) plugin config.
+* @returns the fully resolved config.
+*/
+function resolveConfig(config = {}) {
+	const maxRows = config.maxRows ?? 2e5;
+	assertPositiveInt("maxRows", maxRows);
+	const maxFileSizeMB = config.maxFileSizeMB ?? 64;
+	assertFiniteRange("maxFileSizeMB", maxFileSizeMB, Number.MIN_VALUE, 1024);
+	const defaultTolerance = config.defaultTolerance ?? 1e-9;
+	assertFiniteRange("defaultTolerance", defaultTolerance, 0, 1);
+	const evidenceRowLimit = config.evidenceRowLimit ?? 20;
+	assertPositiveInt("evidenceRowLimit", evidenceRowLimit);
+	const allowedExtensions = (config.allowedExtensions ?? [
+		".csv",
+		".tsv",
+		".json",
+		".jsonl"
+	]).map((ext) => {
+		if (!/^\.[a-z0-9]+$/u.test(ext)) throw new TypeError(`allowedExtensions entries must be dot-prefixed lowercase extensions, got ${JSON.stringify(ext)}`);
+		return ext;
+	});
+	if (allowedExtensions.length === 0) throw new TypeError("allowedExtensions must not be empty");
+	return {
+		enabled: config.enabled ?? true,
+		maxRows,
+		maxFileSizeMB,
+		defaultTolerance,
+		evidenceRowLimit,
+		allowedExtensions,
+		workspaceRoot: config.workspaceRoot ?? "",
+		storeReports: config.storeReports ?? true
+	};
+}
+//#endregion
+//#region src/dataset.ts
+/**
+* Dataset loading for `dsh-data-quality`: workspace-confined path resolution,
+* size/row guards, and deterministic parsers for CSV/TSV/JSON/JSONL. All
+* parsing is hand-rolled (no external runtime dependencies) and bounded by
+* the resolved config; oversized inputs reject loudly with actionable hints.
+* @module dsh-data-quality/dataset
+*/
+/** Raised for every user-facing dataset failure; `code` is stable for tests and tooling. */
+var DatasetError = class extends Error {
+	code;
+	/**
+	* @param code - stable machine-readable reason.
+	* @param message - actionable human-readable detail.
+	*/
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "DatasetError";
+	}
+};
+/**
+* Resolve `requested` inside `root`, rejecting escapes and disallowed
+* extensions. Both sides go through `path.resolve` before comparison so
+* Windows backslash/forward-slash mixes never defeat the containment check.
+* @param root - absolute workspace root.
+* @param requested - the caller-supplied path (relative to root, or absolute inside root).
+* @param config - resolved config (extension allowlist).
+* @returns the normalized absolute path inside `root`.
+*/
+function resolveWorkspacePath(root, requested, config) {
+	if (requested.trim() === "") throw new DatasetError("path-escape", "dataset path must not be empty");
+	const resolvedRoot = path.resolve(root);
+	const resolved = path.resolve(resolvedRoot, requested);
+	if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) throw new DatasetError("path-escape", `path ${JSON.stringify(requested)} resolves outside the workspace root ${JSON.stringify(resolvedRoot)}`);
+	const ext = path.extname(resolved).toLowerCase();
+	if (!config.allowedExtensions.includes(ext)) throw new DatasetError("extension-denied", `extension ${JSON.stringify(ext)} is not in allowedExtensions (${config.allowedExtensions.join(", ")})`);
+	return resolved;
+}
+/**
+* Short deterministic fingerprint of a dataset path, used in storage keys.
+* @param datasetPath - the workspace-relative dataset path as callers gave it.
+* @returns an 8-hex-char fingerprint.
+*/
+function pathFingerprint(datasetPath) {
+	return createHash("sha256").update(datasetPath).digest("hex").slice(0, 8);
+}
+/** Assert the abort signal has not fired; throws the signal reason otherwise. */
+function throwIfAborted(signal) {
+	if (signal?.aborted === true) throw signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("operation aborted");
+}
+/**
+* Read a dataset file under the size cap.
+* @param absolutePath - normalized absolute path (from {@link resolveWorkspacePath}).
+* @param config - resolved config (size cap).
+* @param signal - optional abort signal honored around the read.
+* @returns the UTF-8 text.
+*/
+async function readDatasetText(absolutePath, config, signal) {
+	throwIfAborted(signal);
+	let info;
+	try {
+		info = await stat(absolutePath);
+	} catch {
+		throw new DatasetError("not-found", `dataset file not found: ${absolutePath}`);
+	}
+	if (!info.isFile()) throw new DatasetError("not-found", `dataset path is not a file: ${absolutePath}`);
+	const capBytes = config.maxFileSizeMB * 1024 * 1024;
+	if (info.size > capBytes) throw new DatasetError("too-large", `dataset is ${(info.size / 1024 / 1024).toFixed(1)} MiB, above the ${config.maxFileSizeMB} MiB cap; split the file or raise maxFileSizeMB`);
+	const handle = await open(absolutePath, "r");
+	try {
+		throwIfAborted(signal);
+		return await handle.readFile("utf8");
+	} finally {
+		await handle.close();
+	}
+}
+/**
+* Parse CSV/TSV text (RFC-4180-style: quoted fields, `""` escapes, CRLF/LF).
+* The first record is the header; short records pad with `null`, long records
+* fail loud. An empty field parses as `null` (missing).
+* @param text - file text.
+* @param delimiter - field delimiter (`,` or tab).
+* @param config - resolved config (row cap).
+* @param signal - optional abort signal, checked per 1024-record stride.
+* @returns the parsed table.
+*/
+function parseDelimited(text, delimiter, config, signal) {
+	const records = [];
+	let field = "";
+	let record = [];
+	let inQuotes = false;
+	const pushField = () => {
+		record.push(field);
+		field = "";
+	};
+	const pushRecord = () => {
+		pushField();
+		if (record.length === 1 && record[0] === "") {
+			record = [];
+			field = "";
+			return;
+		}
+		records.push(record);
+		record = [];
+		if (records.length % 1024 === 0) throwIfAborted(signal);
+		if (records.length - 1 > config.maxRows) throw new DatasetError("too-many-rows", `dataset exceeds the ${config.maxRows} row cap; use the sample parameter or raise maxRows`);
+	};
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index];
+		if (inQuotes) {
+			if (char === "\"") {
+				if (text[index + 1] === "\"") {
+					field += "\"";
+					index += 2;
+					continue;
+				}
+				inQuotes = false;
+				index += 1;
+				continue;
+			}
+			field += char;
+			index += 1;
+			continue;
+		}
+		if (char === "\"") {
+			inQuotes = true;
+			index += 1;
+			continue;
+		}
+		if (char === delimiter) {
+			pushField();
+			index += 1;
+			continue;
+		}
+		if (char === "\r") {
+			index += 1;
+			continue;
+		}
+		if (char === "\n") {
+			pushRecord();
+			index += 1;
+			continue;
+		}
+		field += char;
+		index += 1;
+	}
+	if (field !== "" || record.length > 0) pushRecord();
+	const header = records[0];
+	if (header === void 0 || header.length === 1 && header[0] === "") throw new DatasetError("malformed", "dataset has no header row");
+	const columns = header.map((name) => name.trim());
+	if (columns.some((name) => name === "")) throw new DatasetError("malformed", "header contains an empty column name");
+	if (new Set(columns).size !== columns.length) throw new DatasetError("malformed", "header contains duplicate column names");
+	const rows = [];
+	for (let i = 1; i < records.length; i++) {
+		const cells = records[i];
+		if (cells.length > columns.length) throw new DatasetError("malformed", `row ${i + 1} has ${cells.length} fields but the header has ${columns.length}`);
+		const out = {};
+		for (let c = 0; c < columns.length; c++) {
+			const raw = cells[c];
+			out[columns[c]] = raw === void 0 || raw === "" ? null : raw;
+		}
+		rows.push(out);
+	}
+	return {
+		columns,
+		rows
+	};
+}
+/**
+* Parse a JSON or JSONL text into a tabular dataset. JSON must be an array of
+* flat objects; JSONL is one object per line. Non-scalar cell values are kept
+* as-is (engines treat them as non-scalar).
+* @param text - file text.
+* @param extension - `.json` or `.jsonl`.
+* @param config - resolved config (row cap).
+* @param signal - optional abort signal.
+* @returns the parsed table.
+*/
+function parseJsonTable(text, extension, config, signal) {
+	const values = extension === ".jsonl" ? parseJsonLines(text) : parseJsonDocument(text);
+	const items = Array.isArray(values) ? values : [values];
+	if (items.length > config.maxRows) throw new DatasetError("too-many-rows", `dataset exceeds the ${config.maxRows} row cap; use the sample parameter or raise maxRows`);
+	const rows = [];
+	const columns = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, item] of items.entries()) {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		if (typeof item !== "object" || item === null || Array.isArray(item)) throw new DatasetError("not-tabular", `row ${index + 1} is not a flat object; profiling/cleaning/verification need a tabular dataset (array of objects)`);
+		const row = item;
+		for (const key of Object.keys(row)) if (!seen.has(key)) {
+			seen.add(key);
+			columns.push(key);
+		}
+		rows.push(row);
+	}
+	return {
+		columns,
+		rows: rows.map((row) => normalizeRow(row, columns))
+	};
+}
+/** Fill absent columns with `null` so every row carries every column. */
+function normalizeRow(row, columns) {
+	const out = {};
+	for (const column of columns) {
+		const value = row[column];
+		out[column] = value === void 0 ? null : value;
+	}
+	return out;
+}
+/** Parse one JSON document; failures become a loud malformed error. */
+function parseJsonDocument(text) {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw new DatasetError("malformed", `invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/** Parse JSONL (one JSON value per non-empty line); failures name the line. */
+function parseJsonLines(text) {
+	const out = [];
+	const lines = text.split(/\r?\n/u);
+	for (const [index, line] of lines.entries()) {
+		if (line.trim() === "") continue;
+		try {
+			out.push(JSON.parse(line));
+		} catch {
+			throw new DatasetError("malformed", `invalid JSON on line ${index + 1}`);
+		}
+	}
+	return out;
+}
+/**
+* Load a tabular dataset from a file already resolved inside the workspace.
+* @param absolutePath - normalized absolute dataset path.
+* @param config - resolved config.
+* @param signal - optional abort signal.
+* @returns the parsed table.
+*/
+async function loadTable(absolutePath, config, signal) {
+	const text = await readDatasetText(absolutePath, config, signal);
+	const ext = path.extname(absolutePath).toLowerCase();
+	throwIfAborted(signal);
+	if (ext === ".csv") return parseDelimited(text, ",", config, signal);
+	if (ext === ".tsv") return parseDelimited(text, "	", config, signal);
+	return parseJsonTable(text, ext, config, signal);
+}
+/**
+* Load a dataset as a citation-checkable document root: CSV/TSV become
+* `{ columns, rows }` (so `rows[3].nav` resolves), JSON is the parsed value,
+* JSONL is the array of parsed lines.
+* @param absolutePath - normalized absolute dataset path.
+* @param config - resolved config.
+* @param signal - optional abort signal.
+* @returns the document root.
+*/
+async function loadDocument(absolutePath, config, signal) {
+	const ext = path.extname(absolutePath).toLowerCase();
+	if (ext === ".json") return {
+		kind: "json",
+		value: parseJsonDocument(await readDatasetText(absolutePath, config, signal))
+	};
+	if (ext === ".jsonl") return {
+		kind: "json",
+		value: parseJsonLines(await readDatasetText(absolutePath, config, signal))
+	};
+	const table = await loadTable(absolutePath, config, signal);
+	return {
+		kind: "table",
+		columns: table.columns,
+		rows: table.rows
+	};
+}
+/**
+* Deterministic systematic sample: every `ceil(total / count)`-th row from
+* index 0. No clock, no RNG — the same input always yields the same sample.
+* @param rows - full row list.
+* @param count - requested sample size.
+* @returns the sampled rows (identity when `count >= rows.length`).
+*/
+function sampleRows(rows, count) {
+	if (!Number.isSafeInteger(count) || count <= 0) throw new DatasetError("malformed", `sample must be a positive integer, got ${String(count)}`);
+	if (count >= rows.length) return rows;
+	const stride = Math.ceil(rows.length / count);
+	const out = [];
+	for (let i = 0; i < rows.length; i += stride) out.push(rows[i]);
+	return out;
+}
+/**
+* Missingness: `null`, `undefined`, or a string empty after trimming. A
+* whitespace-only cell counts as missing even before any `trim` clean rule.
+* @param cell - the cell to test (`undefined` when the column is absent).
+* @returns whether the cell is missing.
+*/
+function isMissing(cell) {
+	if (cell === null || cell === void 0) return true;
+	if (typeof cell === "string") return cell.trim() === "";
+	return false;
+}
+/** Strict full-string numeric parse (no thousands separators, no unit suffixes). */
+function parseNumeric(cell) {
+	if (typeof cell === "number") return Number.isFinite(cell) ? cell : void 0;
+	if (typeof cell !== "string") return void 0;
+	const text = cell.trim();
+	if (text === "") return void 0;
+	if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/u.test(text)) return void 0;
+	const value = Number(text);
+	return Number.isFinite(value) ? value : void 0;
+}
+const DATE_PATTERNS = [
+	/^(\d{4})-(\d{1,2})-(\d{1,2})$/u,
+	/^(\d{4})\/(\d{1,2})\/(\d{1,2})$/u,
+	/^(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?$/u
+];
+/**
+* Deterministic date parse to epoch milliseconds. Accepts `YYYY-MM-DD`,
+* `YYYY/MM/DD`, and ISO-like datetimes (date-only forms read as UTC midnight).
+* Calendar-invalid dates (e.g. 2025-13-40) reject. Returns `undefined` when
+* the cell is not a recognized date.
+* @param cell - the cell to parse (`undefined` when the column is absent).
+* @returns epoch milliseconds, or `undefined`.
+*/
+function parseDate(cell) {
+	if (typeof cell !== "string") return void 0;
+	const text = cell.trim();
+	for (const pattern of DATE_PATTERNS) {
+		const match = pattern.exec(text);
+		if (match === null) continue;
+		const year = Number(match[1]);
+		const month = Number(match[2]);
+		const day = Number(match[3]);
+		const hour = Number(match[4] ?? 0);
+		const minute = Number(match[5] ?? 0);
+		const second = Number(match[6] ?? 0);
+		if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) return void 0;
+		const epoch = Date.UTC(year, month - 1, day, hour, minute, second);
+		const check = new Date(epoch);
+		if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day) return void 0;
+		return epoch;
+	}
+}
+/** Boolean parse: true/false/yes/no/1/0, case-insensitive. */
+function parseBoolean(cell) {
+	if (typeof cell === "boolean") return cell;
+	if (typeof cell !== "string") return void 0;
+	const text = cell.trim().toLowerCase();
+	if (text === "true" || text === "yes" || text === "1") return true;
+	if (text === "false" || text === "no" || text === "0") return false;
+}
+//#endregion
+//#region src/store.ts
+/**
+* Durable report storage over the harness storage domain. The `data_quality`
+* domain keeps one record per profile/clean/verify/citations run, keyed by an
+* injected timestamp plus a path fingerprint, so reports survive a restart
+* and stay queryable without touching the session log.
+* @module dsh-data-quality/store
+*/
+/** Zod schema of one persisted report record (durable-boundary validation). */
+const reportRecordSchema = z$1.object({
+	kind: z$1.enum([
+		"profile",
+		"clean",
+		"verify",
+		"citations"
+	]),
+	at: z$1.number().int().nonnegative(),
+	dataset: z$1.string(),
+	report: z$1.record(z$1.string(), z$1.unknown())
+});
+/** The `dsh-data-quality` storage-domain declaration. */
+const dataQualityDomainSpec = defineDomain({
+	name: "data_quality",
+	version: 1,
+	tables: { reports: domainTable(reportRecordSchema) }
+});
+/** Pad to two digits for the key timestamp. */
+function pad2(value) {
+	return String(value).padStart(2, "0");
+}
+/**
+* Build the storage key for one run: `YYYYMMDDHHmmssSSS-<kind>-<pathFp>`.
+* UTC digits keep the key timezone-independent and filename-safe everywhere.
+* @param record - the report envelope.
+* @returns the deterministic key.
+*/
+function reportKeyOf(record) {
+	const date = new Date(record.at);
+	return `${`${date.getUTCFullYear()}${pad2(date.getUTCMonth() + 1)}${pad2(date.getUTCDate())}${pad2(date.getUTCHours())}${pad2(date.getUTCMinutes())}${pad2(date.getUTCSeconds())}${String(date.getUTCMilliseconds()).padStart(3, "0")}`}-${record.kind}-${pathFingerprint(record.dataset)}`;
+}
+//#endregion
+//#region src/clean.ts
+/**
+* Declarative cleaning rules over a parsed {@link Table}: dedupe, fill-missing,
+* coerce-type, normalize-unit, trim, and map-values. Pure and deterministic —
+* rules apply in array order, each seeing the previous rule's output; every
+* rule logs how many rows it affected. Unknown columns and invalid rule
+* parameters fail loud.
+* @module dsh-data-quality/clean
+*/
+/** Raised for invalid rules or unknown columns; `message` names the rule index and reason. */
+var CleanRuleError = class extends Error {
+	ruleIndex;
+	/**
+	* @param ruleIndex - index of the offending rule in the request array.
+	* @param message - actionable human-readable detail.
+	*/
+	constructor(ruleIndex, message) {
+		super(message);
+		this.ruleIndex = ruleIndex;
+		this.name = "CleanRuleError";
+	}
+};
+/** Assert `column` exists; every rule validates its columns before touching data. */
+function requireColumn$1(columns, column, ruleIndex) {
+	if (!columns.includes(column)) throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: unknown column ${JSON.stringify(column)} (columns: ${columns.join(", ")})`);
+}
+/** Assert every selected column exists. */
+function requireColumns(columns, selected, ruleIndex) {
+	for (const column of selected) requireColumn$1(columns, column, ruleIndex);
+}
+/** dedupe: keep the first row of each key group; later duplicates are removed. */
+function applyDedupe(table, rule, ruleIndex, signal) {
+	const selected = rule.columns ?? table.columns;
+	requireColumns(table.columns, selected, ruleIndex);
+	const seen = /* @__PURE__ */ new Set();
+	const rows = [];
+	let removed = 0;
+	for (const [index, row] of table.rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const key = JSON.stringify(selected.map((column) => row[column] ?? null));
+		if (seen.has(key)) {
+			removed += 1;
+			continue;
+		}
+		seen.add(key);
+		rows.push(row);
+	}
+	return {
+		table: {
+			columns: table.columns,
+			rows
+		},
+		log: {
+			ruleIndex,
+			rule: "dedupe",
+			affectedRows: removed,
+			detail: `removed ${removed} duplicate row(s) by [${selected.join(", ")}]`
+		}
+	};
+}
+/** fill-missing: constant / mean / median / forward fill of missing cells in one column. */
+function applyFillMissing(table, rule, ruleIndex, signal) {
+	requireColumn$1(table.columns, rule.column, ruleIndex);
+	let fill;
+	let detail;
+	switch (rule.strategy) {
+		case "constant":
+			if (rule.value === void 0) throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: fill-missing strategy "constant" requires a value`);
+			fill = rule.value;
+			detail = `filled with constant ${JSON.stringify(rule.value)}`;
+			break;
+		case "mean":
+		case "median": {
+			const values = table.rows.map((row) => parseNumeric(row[rule.column])).filter((value) => value !== void 0).sort((a, b) => a - b);
+			if (values.length === 0) throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: fill-missing strategy "${rule.strategy}" needs at least one numeric value in column ${JSON.stringify(rule.column)}`);
+			const computed = rule.strategy === "mean" ? values.reduce((acc, value) => acc + value, 0) / values.length : values.length % 2 === 1 ? values[(values.length - 1) / 2] : (values[values.length / 2 - 1] + values[values.length / 2]) / 2;
+			fill = computed;
+			detail = `filled with ${rule.strategy} ${computed}`;
+			break;
+		}
+		case "forward":
+			fill = void 0;
+			detail = "filled with the previous non-missing value";
+	}
+	let filled = 0;
+	let previous;
+	const rows = table.rows.map((row, index) => {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const cell = row[rule.column];
+		if (!isMissing(cell)) {
+			previous = cell ?? null;
+			return row;
+		}
+		const replacement = rule.strategy === "forward" ? previous : fill;
+		if (replacement === void 0) return row;
+		filled += 1;
+		return {
+			...row,
+			[rule.column]: replacement
+		};
+	});
+	return {
+		table: {
+			columns: table.columns,
+			rows
+		},
+		log: {
+			ruleIndex,
+			rule: "fill-missing",
+			affectedRows: filled,
+			detail: `${detail}; ${filled} row(s) filled`
+		}
+	};
+}
+/** coerce-type: rewrite one column to number / ISO date / boolean; failures become missing and are counted. */
+function applyCoerceType(table, rule, ruleIndex, signal) {
+	requireColumn$1(table.columns, rule.column, ruleIndex);
+	let coerced = 0;
+	let failed = 0;
+	const failureExamples = [];
+	const rows = table.rows.map((row, index) => {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const cell = row[rule.column];
+		if (isMissing(cell)) return row;
+		let value;
+		switch (rule.to) {
+			case "number": {
+				const numeric = parseNumeric(cell);
+				value = numeric === void 0 ? void 0 : numeric;
+				break;
+			}
+			case "date": {
+				const epoch = parseDate(cell);
+				if (epoch === void 0) value = void 0;
+				else {
+					const date = new Date(epoch);
+					value = date.getUTCHours() === 0 && date.getUTCMinutes() === 0 && date.getUTCSeconds() === 0 ? date.toISOString().slice(0, 10) : date.toISOString();
+				}
+				break;
+			}
+			case "boolean": {
+				const bool = parseBoolean(cell);
+				value = bool === void 0 ? void 0 : String(bool);
+				break;
+			}
+		}
+		if (value === void 0) {
+			failed += 1;
+			if (failureExamples.length < 3) failureExamples.push(JSON.stringify(cell));
+			return {
+				...row,
+				[rule.column]: null
+			};
+		}
+		coerced += 1;
+		return {
+			...row,
+			[rule.column]: value
+		};
+	});
+	const detail = `${coerced} value(s) coerced to ${rule.to}` + (failed > 0 ? `; ${failed} failure(s) set to missing (e.g. ${failureExamples.join(", ")})` : "");
+	return {
+		table: {
+			columns: table.columns,
+			rows
+		},
+		log: {
+			ruleIndex,
+			rule: "coerce-type",
+			affectedRows: coerced,
+			detail
+		}
+	};
+}
+/** normalize-unit: strip a unit suffix and multiply by its factor (e.g. 万 -> 1e4). */
+function applyNormalizeUnit(table, rule, ruleIndex, signal) {
+	requireColumn$1(table.columns, rule.column, ruleIndex);
+	const entries = Object.entries(rule.factors);
+	if (entries.length === 0) throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: normalize-unit requires a non-empty factors map`);
+	for (const [suffix, factor] of entries) {
+		if (suffix === "") throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: normalize-unit suffixes must not be empty`);
+		if (!Number.isFinite(factor) || factor <= 0) throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: factor for ${JSON.stringify(suffix)} must be a positive finite number, got ${String(factor)}`);
+	}
+	const ordered = [...entries].sort((a, b) => b[0].length - a[0].length);
+	let normalized = 0;
+	let skipped = 0;
+	const rows = table.rows.map((row, index) => {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const cell = row[rule.column];
+		if (isMissing(cell)) return row;
+		const plain = parseNumeric(cell);
+		if (plain !== void 0) {
+			normalized += 1;
+			return {
+				...row,
+				[rule.column]: plain
+			};
+		}
+		if (typeof cell === "string") {
+			const text = cell.trim();
+			for (const [suffix, factor] of ordered) {
+				if (!text.endsWith(suffix)) continue;
+				const numeric = parseNumeric(text.slice(0, text.length - suffix.length));
+				if (numeric === void 0) continue;
+				normalized += 1;
+				return {
+					...row,
+					[rule.column]: numeric * factor
+				};
+			}
+		}
+		skipped += 1;
+		return row;
+	});
+	const detail = `${normalized} value(s) normalized to base units` + (skipped > 0 ? `; ${skipped} unparseable value(s) left unchanged` : "");
+	return {
+		table: {
+			columns: table.columns,
+			rows
+		},
+		log: {
+			ruleIndex,
+			rule: "normalize-unit",
+			affectedRows: normalized,
+			detail
+		}
+	};
+}
+/** trim: strip leading/trailing whitespace of string cells in the selected columns. */
+function applyTrim(table, rule, ruleIndex, signal) {
+	const selected = rule.columns ?? table.columns;
+	requireColumns(table.columns, selected, ruleIndex);
+	let trimmed = 0;
+	const rows = table.rows.map((row, index) => {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		let changed = false;
+		const next = { ...row };
+		for (const column of selected) {
+			const cell = next[column];
+			if (typeof cell !== "string") continue;
+			const value = cell.trim();
+			if (value !== cell) {
+				next[column] = value;
+				changed = true;
+			}
+		}
+		if (changed) trimmed += 1;
+		return changed ? next : row;
+	});
+	return {
+		table: {
+			columns: table.columns,
+			rows
+		},
+		log: {
+			ruleIndex,
+			rule: "trim",
+			affectedRows: trimmed,
+			detail: `trimmed whitespace in [${selected.join(", ")}] for ${trimmed} row(s)`
+		}
+	};
+}
+/** map-values: exact-match enum mapping; unmapped values follow the `else` policy. */
+function applyMapValues(table, rule, ruleIndex, signal) {
+	requireColumn$1(table.columns, rule.column, ruleIndex);
+	const elsePolicy = rule.else ?? "keep";
+	let mapped = 0;
+	let unmapped = 0;
+	const rows = table.rows.map((row, index) => {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const cell = row[rule.column];
+		if (isMissing(cell)) return row;
+		const key = typeof cell === "string" ? cell : typeof cell === "object" && cell !== null ? JSON.stringify(cell) : String(cell);
+		const replacement = rule.map[key];
+		if (replacement !== void 0) {
+			mapped += 1;
+			return {
+				...row,
+				[rule.column]: replacement
+			};
+		}
+		if (elsePolicy === "missing") {
+			unmapped += 1;
+			return {
+				...row,
+				[rule.column]: null
+			};
+		}
+		unmapped += 1;
+		return row;
+	});
+	const detail = `${mapped} value(s) mapped` + (unmapped > 0 ? `; ${unmapped} unmapped value(s) ${elsePolicy === "missing" ? "set to missing" : "kept"}` : "");
+	return {
+		table: {
+			columns: table.columns,
+			rows
+		},
+		log: {
+			ruleIndex,
+			rule: "map-values",
+			affectedRows: mapped,
+			detail
+		}
+	};
+}
+/**
+* Apply cleaning rules in array order; each rule sees the previous output.
+* @param table - the parsed dataset.
+* @param rules - non-empty rule list.
+* @param options - abort signal.
+* @returns the cleaned table plus the per-rule audit log.
+*/
+function applyCleanRules(table, rules, options = {}) {
+	if (rules.length === 0) throw new CleanRuleError(0, "rules must be a non-empty array");
+	let current = {
+		columns: [...table.columns],
+		rows: table.rows.map((row) => ({ ...row }))
+	};
+	const logs = [];
+	for (const [ruleIndex, rule] of rules.entries()) {
+		throwIfAborted(options.signal);
+		let step;
+		switch (rule.rule) {
+			case "dedupe":
+				step = applyDedupe(current, rule, ruleIndex, options.signal);
+				break;
+			case "fill-missing":
+				step = applyFillMissing(current, rule, ruleIndex, options.signal);
+				break;
+			case "coerce-type":
+				step = applyCoerceType(current, rule, ruleIndex, options.signal);
+				break;
+			case "normalize-unit":
+				step = applyNormalizeUnit(current, rule, ruleIndex, options.signal);
+				break;
+			case "trim":
+				step = applyTrim(current, rule, ruleIndex, options.signal);
+				break;
+			case "map-values":
+				step = applyMapValues(current, rule, ruleIndex, options.signal);
+				break;
+			default: throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: unknown rule type ${JSON.stringify(rule.rule)}`);
+		}
+		current = step.table;
+		logs.push(step.log);
+	}
+	return {
+		columns: current.columns,
+		rows: current.rows,
+		logs,
+		inputRows: table.rows.length,
+		outputRows: current.rows.length
+	};
+}
+/**
+* Serialize a table back to CSV/TSV text with RFC-4180 quoting (used when a
+* clean run writes an output file). Numbers and booleans render via `String`;
+* missing cells render empty.
+* @param columns - column order.
+* @param rows - rows to serialize.
+* @param delimiter - field delimiter.
+* @returns the file text (LF newlines, trailing newline).
+*/
+function serializeDelimited(columns, rows, delimiter) {
+	const encode = (cell) => {
+		if (isMissing(cell)) return "";
+		const text = typeof cell === "string" ? cell : typeof cell === "object" && cell !== null ? JSON.stringify(cell) : String(cell);
+		if (text.includes(delimiter) || text.includes("\"") || text.includes("\n") || text.includes("\r")) return `"${text.replace(/"/gu, "\"\"")}"`;
+		return text;
+	};
+	const lines = [columns.map((column) => encode(column)).join(delimiter)];
+	for (const row of rows) lines.push(columns.map((column) => encode(row[column])).join(delimiter));
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/profile.ts
+/**
+* Deterministic dataset profiling: per-column type inference, missingness,
+* cardinality, numeric distribution, IQR outlier counts, and duplicate-row
+* detection. Pure functions over a parsed {@link Table} — no clock, no RNG,
+* no I/O; `generatedAt` is injected by the caller.
+* @module dsh-data-quality/profile
+*/
+/** Round to 6 significant digits for stable, readable report numbers. */
+function round6(value) {
+	return Number(value.toPrecision(6));
+}
+/** Linear-interpolation quantile over an ascending-sorted array. */
+function quantile(sorted, q) {
+	const index = (sorted.length - 1) * q;
+	const low = Math.floor(index);
+	const high = Math.ceil(index);
+	const lower = sorted[low];
+	return lower + (sorted[high] - lower) * (index - low);
+}
+/** Compute the numeric distribution of already-parsed values. */
+function numericProfile(values) {
+	if (values.length === 0) return void 0;
+	const sorted = [...values].sort((a, b) => a - b);
+	const sum = sorted.reduce((acc, value) => acc + value, 0);
+	const p25 = quantile(sorted, .25);
+	const p75 = quantile(sorted, .75);
+	const iqr = p75 - p25;
+	const lowFence = p25 - 1.5 * iqr;
+	const highFence = p75 + 1.5 * iqr;
+	const outliers = iqr === 0 ? 0 : sorted.filter((value) => value < lowFence || value > highFence).length;
+	return {
+		min: round6(sorted[0]),
+		max: round6(sorted[sorted.length - 1]),
+		mean: round6(sum / sorted.length),
+		median: round6(quantile(sorted, .5)),
+		p25: round6(p25),
+		p75: round6(p75),
+		outliers
+	};
+}
+/** Count rows whose full content duplicates an earlier row (first occurrence is not counted). */
+function countDuplicateRows(table, signal) {
+	const seen = /* @__PURE__ */ new Set();
+	let duplicates = 0;
+	for (const [index, row] of table.rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const key = JSON.stringify(table.columns.map((column) => row[column] ?? null));
+		if (seen.has(key)) duplicates += 1;
+		else seen.add(key);
+	}
+	return duplicates;
+}
+/** Profile one column over the given rows. */
+function profileColumn(rows, column, signal) {
+	let missing = 0;
+	let numbers = 0;
+	let dates = 0;
+	let booleans = 0;
+	let strings = 0;
+	const numericValues = [];
+	const distinct = /* @__PURE__ */ new Set();
+	const frequencies = /* @__PURE__ */ new Map();
+	for (const [index, row] of rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const cell = row[column];
+		if (isMissing(cell)) {
+			missing += 1;
+			continue;
+		}
+		const text = typeof cell === "string" ? cell : JSON.stringify(cell);
+		distinct.add(text);
+		frequencies.set(text, (frequencies.get(text) ?? 0) + 1);
+		const numeric = parseNumeric(cell);
+		if (numeric !== void 0) {
+			numbers += 1;
+			numericValues.push(numeric);
+			continue;
+		}
+		if (parseDate(cell) !== void 0) {
+			dates += 1;
+			continue;
+		}
+		if (parseBoolean(cell) !== void 0) {
+			booleans += 1;
+			continue;
+		}
+		strings += 1;
+	}
+	const present = rows.length - missing;
+	const notes = [];
+	let inferredType;
+	if (present === 0) inferredType = "empty";
+	else if (numbers === present) inferredType = "number";
+	else if (dates === present) inferredType = "date";
+	else if (booleans === present) inferredType = "boolean";
+	else if (strings === present) inferredType = "string";
+	else {
+		inferredType = "mixed";
+		const parts = [
+			numbers > 0 ? `${numbers} numeric` : void 0,
+			dates > 0 ? `${dates} date` : void 0,
+			booleans > 0 ? `${booleans} boolean` : void 0,
+			strings > 0 ? `${strings} string` : void 0
+		].filter((part) => part !== void 0);
+		notes.push(`mixed types among ${present} present values: ${parts.join(", ")}`);
+	}
+	const profile = {
+		name: column,
+		inferredType,
+		missing,
+		missingRate: rows.length === 0 ? 0 : round6(missing / rows.length),
+		unique: distinct.size,
+		notes
+	};
+	const numeric = inferredType === "number" ? numericProfile(numericValues) : void 0;
+	const topValues = (inferredType === "string" || inferredType === "boolean") && distinct.size > 0 && distinct.size <= 10 ? [...frequencies.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)).slice(0, 5).map(([value, count]) => ({
+		value,
+		count
+	})) : void 0;
+	return {
+		...profile,
+		...numeric !== void 0 ? { numeric } : {},
+		...topValues !== void 0 ? { topValues } : {}
+	};
+}
+/**
+* Profile a parsed table. Column cards are computed over a deterministic
+* systematic sample when `sample` is given; row counts and duplicate counts
+* always cover the full table.
+* @param table - the parsed dataset.
+* @param options - dataset label, optional sample size, injected timestamp, abort signal.
+* @returns the profile report.
+*/
+function profileTable(table, options) {
+	throwIfAborted(options.signal);
+	const profiled = options.sample === void 0 ? table.rows : sampleRows(table.rows, options.sample);
+	const columns = table.columns.map((column) => profileColumn(profiled, column, options.signal));
+	const duplicateRows = countDuplicateRows(table, options.signal);
+	return {
+		dataset: options.dataset,
+		rowCount: table.rows.length,
+		sampled: profiled.length !== table.rows.length,
+		profiledRows: profiled.length,
+		columnCount: table.columns.length,
+		duplicateRows,
+		columns,
+		generatedAt: options.generatedAt
+	};
+}
+/** Human-readable profile summary for the tool's Native render. */
+function renderProfileText(report) {
+	const lines = [];
+	lines.push(`Profile of ${report.dataset}: ${report.rowCount} rows x ${report.columnCount} columns` + (report.sampled ? ` (column cards over a systematic sample of ${report.profiledRows} rows)` : ""));
+	if (report.duplicateRows > 0) lines.push(`Duplicate rows: ${report.duplicateRows}`);
+	for (const column of report.columns) {
+		const parts = [`${column.name}: ${column.inferredType}`];
+		if (column.missing > 0) parts.push(`missing ${column.missing} (${(column.missingRate * 100).toFixed(1)}%)`);
+		parts.push(`unique ${column.unique}`);
+		if (column.numeric !== void 0) parts.push(`min ${column.numeric.min}, p25 ${column.numeric.p25}, median ${column.numeric.median}, p75 ${column.numeric.p75}, max ${column.numeric.max}, mean ${column.numeric.mean}` + (column.numeric.outliers > 0 ? `, ${column.numeric.outliers} IQR outliers` : ""));
+		if (column.topValues !== void 0) parts.push(`top: ${column.topValues.map((entry) => `${JSON.stringify(entry.value)} x${entry.count}`).join(", ")}`);
+		for (const note of column.notes) parts.push(`note: ${note}`);
+		lines.push(`- ${parts.join("; ")}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/verify.ts
+/**
+* Declarative verification rules over a parsed {@link Table} (not-null,
+* unique, range, regex, enum, cross-column, freshness) plus the frozen
+* citation-checking semantics for `ctx.dataQuality.verifyCitations`. Pure and
+* deterministic: the freshness clock is injected, numeric comparison never
+* uses raw `===`, and evidence rows are capped by config.
+* @module dsh-data-quality/verify
+*/
+/** Raised for invalid rules; `message` names the rule index and reason. */
+var VerifyRuleError = class extends Error {
+	ruleIndex;
+	/**
+	* @param ruleIndex - index of the offending rule in the request array.
+	* @param message - actionable human-readable detail.
+	*/
+	constructor(ruleIndex, message) {
+		super(message);
+		this.ruleIndex = ruleIndex;
+		this.name = "VerifyRuleError";
+	}
+};
+/** Assert `column` exists. */
+function requireColumn(columns, column, ruleIndex) {
+	if (!columns.includes(column)) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: unknown column ${JSON.stringify(column)} (columns: ${columns.join(", ")})`);
+}
+/** The trimmed string form used for regex/enum/cross-column string comparison. */
+function textOf(cell) {
+	if (typeof cell === "string") return cell.trim();
+	if (cell === null || cell === void 0) return "";
+	if (typeof cell === "object") return JSON.stringify(cell);
+	return String(cell);
+}
+/** Run one per-row predicate and collect capped evidence. */
+function evaluate(table, ruleIndex, ruleName, columns, predicate, evidenceRowLimit, signal) {
+	let failedCount = 0;
+	const evidence = [];
+	for (const [rowIndex, row] of table.rows.entries()) {
+		if (rowIndex % 1024 === 0) throwIfAborted(signal);
+		if (predicate(row)) continue;
+		failedCount += 1;
+		if (evidence.length < evidenceRowLimit) {
+			const values = {};
+			for (const column of columns) values[column] = row[column] ?? null;
+			evidence.push({
+				rowIndex,
+				values
+			});
+		}
+	}
+	return {
+		ruleIndex,
+		rule: ruleName,
+		passed: failedCount === 0,
+		failedCount,
+		checkedCount: table.rows.length,
+		evidence
+	};
+}
+const CROSS_OPS = [
+	"<",
+	"<=",
+	"==",
+	"!=",
+	">=",
+	">"
+];
+/**
+* Apply verification rules over a parsed table. A missing cell fails every
+* rule that reads it. The overall `passed` is the conjunction of rule passes;
+* a failing dataset is a normal result, never a thrown error.
+* @param table - the parsed dataset.
+* @param rules - non-empty rule list.
+* @param options - evidence cap, injected clock for `freshness`, abort signal.
+* @returns the verify report (without the dataset label; the caller adds it).
+*/
+function verifyTable(table, rules, options) {
+	if (rules.length === 0) throw new VerifyRuleError(0, "rules must be a non-empty array");
+	const results = [];
+	for (const [ruleIndex, rule] of rules.entries()) {
+		throwIfAborted(options.signal);
+		let result;
+		switch (rule.rule) {
+			case "not-null":
+				requireColumn(table.columns, rule.column, ruleIndex);
+				result = evaluate(table, ruleIndex, rule.rule, [rule.column], (row) => !isMissing(row[rule.column]), options.evidenceRowLimit, options.signal);
+				break;
+			case "unique": {
+				if (rule.columns.length === 0) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: unique requires at least one column`);
+				for (const column of rule.columns) requireColumn(table.columns, column, ruleIndex);
+				const counts = /* @__PURE__ */ new Map();
+				for (const row of table.rows) {
+					const key = JSON.stringify(rule.columns.map((column) => row[column] ?? null));
+					counts.set(key, (counts.get(key) ?? 0) + 1);
+				}
+				result = evaluate(table, ruleIndex, rule.rule, rule.columns, (row) => (counts.get(JSON.stringify(rule.columns.map((column) => row[column] ?? null))) ?? 0) === 1, options.evidenceRowLimit, options.signal);
+				break;
+			}
+			case "range":
+				requireColumn(table.columns, rule.column, ruleIndex);
+				if (rule.min === void 0 && rule.max === void 0) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: range requires at least one of min/max`);
+				result = evaluate(table, ruleIndex, rule.rule, [rule.column], (row) => {
+					const value = parseNumeric(row[rule.column]);
+					if (value === void 0) return false;
+					if (rule.min !== void 0 && value < rule.min) return false;
+					if (rule.max !== void 0 && value > rule.max) return false;
+					return true;
+				}, options.evidenceRowLimit, options.signal);
+				break;
+			case "regex": {
+				requireColumn(table.columns, rule.column, ruleIndex);
+				let pattern;
+				try {
+					pattern = new RegExp(rule.pattern, rule.flags ?? "");
+				} catch (error) {
+					throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: invalid regex ${JSON.stringify(rule.pattern)}: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				result = evaluate(table, ruleIndex, rule.rule, [rule.column], (row) => {
+					const cell = row[rule.column];
+					if (isMissing(cell)) return false;
+					pattern.lastIndex = 0;
+					return pattern.test(textOf(cell));
+				}, options.evidenceRowLimit, options.signal);
+				break;
+			}
+			case "enum": {
+				requireColumn(table.columns, rule.column, ruleIndex);
+				if (rule.values.length === 0) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: enum requires a non-empty values array`);
+				const allowed = new Set(rule.values);
+				result = evaluate(table, ruleIndex, rule.rule, [rule.column], (row) => {
+					const cell = row[rule.column];
+					if (isMissing(cell)) return false;
+					return allowed.has(textOf(cell));
+				}, options.evidenceRowLimit, options.signal);
+				break;
+			}
+			case "cross-column": {
+				requireColumn(table.columns, rule.left, ruleIndex);
+				if (!CROSS_OPS.includes(rule.op)) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: unsupported op ${JSON.stringify(rule.op)}`);
+				const hasColumn = rule.rightColumn !== void 0;
+				if (hasColumn === (rule.value !== void 0)) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: cross-column needs exactly one of rightColumn/value`);
+				if (hasColumn) requireColumn(table.columns, rule.rightColumn, ruleIndex);
+				const columns = hasColumn ? [rule.left, rule.rightColumn] : [rule.left];
+				result = evaluate(table, ruleIndex, rule.rule, columns, (row) => {
+					const left = row[rule.left];
+					const right = hasColumn ? row[rule.rightColumn] : rule.value;
+					if (isMissing(left) || isMissing(right)) return false;
+					const leftNum = parseNumeric(left);
+					const rightNum = parseNumeric(right);
+					if (leftNum !== void 0 && rightNum !== void 0) switch (rule.op) {
+						case "<": return leftNum < rightNum;
+						case "<=": return leftNum <= rightNum;
+						case ">": return leftNum > rightNum;
+						case ">=": return leftNum >= rightNum;
+						case "==": return Math.abs(leftNum - rightNum) <= 1e-12 * Math.max(Math.abs(leftNum), Math.abs(rightNum), 1);
+						case "!=": return Math.abs(leftNum - rightNum) > 1e-12 * Math.max(Math.abs(leftNum), Math.abs(rightNum), 1);
+					}
+					const leftDate = parseDate(left);
+					const rightDate = parseDate(right);
+					if (leftDate !== void 0 && rightDate !== void 0) switch (rule.op) {
+						case "<": return leftDate < rightDate;
+						case "<=": return leftDate <= rightDate;
+						case ">": return leftDate > rightDate;
+						case ">=": return leftDate >= rightDate;
+						case "==": return leftDate === rightDate;
+						case "!=": return leftDate !== rightDate;
+					}
+					const leftText = textOf(left);
+					const rightText = textOf(right);
+					if (rule.op === "==") return leftText === rightText;
+					if (rule.op === "!=") return leftText !== rightText;
+					return false;
+				}, options.evidenceRowLimit, options.signal);
+				break;
+			}
+			case "freshness": {
+				requireColumn(table.columns, rule.column, ruleIndex);
+				if (!Number.isFinite(rule.maxAgeDays) || rule.maxAgeDays <= 0) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: freshness maxAgeDays must be a positive number, got ${String(rule.maxAgeDays)}`);
+				let asOf;
+				if (rule.asOf !== void 0) {
+					const parsed = parseDate(rule.asOf);
+					if (parsed === void 0) throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: freshness asOf is not a recognized date: ${JSON.stringify(rule.asOf)}`);
+					asOf = parsed;
+				} else asOf = options.now();
+				const maxAgeMs = rule.maxAgeDays * 864e5;
+				result = evaluate(table, ruleIndex, rule.rule, [rule.column], (row) => {
+					const epoch = parseDate(row[rule.column]);
+					if (epoch === void 0) return false;
+					return asOf - epoch <= maxAgeMs;
+				}, options.evidenceRowLimit, options.signal);
+				break;
+			}
+			default: throw new VerifyRuleError(ruleIndex, `rule ${ruleIndex}: unknown rule type ${JSON.stringify(rule.rule)}`);
+		}
+		results.push(result);
+	}
+	return {
+		passed: results.every((result) => result.passed),
+		rowCount: table.rows.length,
+		rules: results,
+		generatedAt: options.now()
+	};
+}
+/** Human-readable verify summary for the tool's Native render. */
+function renderVerifyText(report) {
+	const lines = [];
+	lines.push(`Verification of ${report.dataset}: ${report.passed ? "PASSED" : "FAILED"} (${report.rowCount} rows, ${report.rules.length} rules)`);
+	for (const rule of report.rules) {
+		lines.push(`- [${rule.passed ? "pass" : "FAIL"}] rule ${rule.ruleIndex} (${rule.rule}): ${rule.failedCount}/${rule.checkedCount} row(s) failed`);
+		for (const row of rule.evidence) {
+			const cells = Object.entries(row.values).map(([column, value]) => `${column}=${JSON.stringify(value)}`).join(", ");
+			lines.push(`    row ${row.rowIndex}: ${cells}`);
+		}
+		if (rule.failedCount > rule.evidence.length) lines.push(`    … and ${rule.failedCount - rule.evidence.length} more failing row(s)`);
+	}
+	return lines.join("\n");
+}
+/**
+* Parse a JSON-path-ish locator (`rows[3].nav`, `summary.annualReturn`,
+* `[0].value`) into walk segments. Throws on unparsable input.
+* @param locator - the citation's path string.
+* @returns ordered walk segments.
+*/
+function parseLocator(locator) {
+	if (locator.trim() === "") throw new Error("citation path must not be empty");
+	const segments = [];
+	for (const part of locator.split(".")) {
+		const match = /^([A-Za-z0-9_$-]*)((?:\[\d+\])*)$/u.exec(part);
+		if (match === null || match[1] === "" && match[2] === "") throw new Error(`unparsable citation path segment ${JSON.stringify(part)} in ${JSON.stringify(locator)}`);
+		const indices = [...(match[2] ?? "").matchAll(/\[(\d+)\]/gu)].map((index) => Number(index[1]));
+		segments.push({
+			key: match[1] === "" ? void 0 : match[1],
+			indices
+		});
+	}
+	return segments;
+}
+/** Sentinel for a failed locator walk (distinguishable from an actual `undefined` value). */
+const NOT_FOUND = Symbol("not-found");
+/** Walk the document root along the parsed locator; returns {@link NOT_FOUND} when any step misses. */
+function walkLocator(root, segments) {
+	let current = root.kind === "table" ? {
+		columns: root.columns,
+		rows: root.rows
+	} : root.value;
+	for (const segment of segments) {
+		if (segment.key !== void 0) {
+			if (typeof current !== "object" || current === null || Array.isArray(current)) return NOT_FOUND;
+			if (!Object.prototype.hasOwnProperty.call(current, segment.key)) return NOT_FOUND;
+			current = current[segment.key];
+		}
+		for (const index of segment.indices) {
+			if (!Array.isArray(current) || index >= current.length) return NOT_FOUND;
+			current = current[index];
+		}
+	}
+	return current;
+}
+/** Relative-tolerance numeric comparison (never raw `===` on floats). */
+function numericClose(actual, cited, tolerance) {
+	return Math.abs(actual - cited) <= tolerance * Math.max(Math.abs(actual), Math.abs(cited), Number.MIN_VALUE);
+}
+/** Display form of a located value for evidence notes (`undefined` when it cannot be rendered). */
+function displayActual(located) {
+	if (typeof located === "string") return located;
+	if (typeof located === "number" || typeof located === "boolean") return String(located);
+	if (located === null) return "null";
+	const rendered = JSON.stringify(located);
+	return typeof rendered === "string" ? rendered : void 0;
+}
+/**
+* The frozen citation-checking semantics: locate each citation's `path` in the
+* dataset document, then compare. Numbers compare with relative `tolerance`
+* (falling back to `defaultTolerance`); strings compare exactly. A missing
+* location is `not-found`; an incomparable actual/cited type pair is
+* `unverifiable`.
+* @param root - the loaded dataset document.
+* @param citations - citations to check.
+* @param defaultTolerance - configured fallback relative tolerance.
+* @returns one result per citation, ids echoed.
+*/
+function checkCitations(root, citations, defaultTolerance) {
+	const results = [];
+	for (const citation of citations) {
+		let located;
+		try {
+			located = walkLocator(root, parseLocator(citation.path));
+		} catch (error) {
+			results.push({
+				id: citation.id,
+				status: "not-found",
+				note: `path ${JSON.stringify(citation.path)} is not a valid locator: ${error instanceof Error ? error.message : String(error)}`
+			});
+			continue;
+		}
+		if (located === NOT_FOUND) {
+			results.push({
+				id: citation.id,
+				status: "not-found",
+				note: `nothing found at ${JSON.stringify(citation.path)}`
+			});
+			continue;
+		}
+		if (typeof citation.value === "number") {
+			const actualNumber = typeof located === "number" ? located : parseNumeric(located);
+			if (actualNumber === void 0) {
+				const display = displayActual(located);
+				results.push({
+					id: citation.id,
+					status: "unverifiable",
+					...display !== void 0 ? { actual: display } : {},
+					note: `value at ${JSON.stringify(citation.path)} is not numeric and cannot be compared to ${citation.value}`
+				});
+				continue;
+			}
+			const tolerance = citation.tolerance ?? defaultTolerance;
+			if (numericClose(actualNumber, citation.value, tolerance)) results.push({
+				id: citation.id,
+				status: "verified",
+				actual: actualNumber,
+				note: `within relative tolerance ${tolerance}`
+			});
+			else results.push({
+				id: citation.id,
+				status: "mismatch",
+				actual: actualNumber,
+				note: `cited ${citation.value} differs from actual ${actualNumber} beyond relative tolerance ${tolerance}`
+			});
+			continue;
+		}
+		if (typeof located === "string") {
+			if (located === citation.value) results.push({
+				id: citation.id,
+				status: "verified",
+				actual: located
+			});
+			else results.push({
+				id: citation.id,
+				status: "mismatch",
+				actual: located,
+				note: `cited ${JSON.stringify(citation.value)} != actual ${JSON.stringify(located)}`
+			});
+			continue;
+		}
+		const display = displayActual(located);
+		results.push({
+			id: citation.id,
+			status: "unverifiable",
+			...display !== void 0 ? { actual: display } : {},
+			note: `value at ${JSON.stringify(citation.path)} is ${typeof located}, not comparable to cited string`
+		});
+	}
+	return { results };
+}
+//#endregion
+//#region src/events.ts
+/**
+* The `data-quality/*` session-event vocabulary and its adaptive append gate.
+* The vocabulary is declared on `SessionEventMap` for type-checked payloads;
+* the runtime gate decides per host whether appending is safe:
+*
+* - Hosts whose known-type set already covers the vocabulary (a future harness
+*   that adopts these events) append plainly.
+* - Hosts with an `ignorable` append option (the master-build
+*   `Session.append(type, data, { ignorable: true })` contract) append with the
+*   marker, so builds that do not know the type skip the event on restore.
+* - 0.1.0-rc.6 hosts have neither a registration surface nor the `ignorable`
+*   append flag; appending an unknown type there would make the persistence
+*   coordinator refuse the session log on restore, so the append is skipped
+*   and the storage-domain report remains the durable copy.
+* @module dsh-data-quality/events
+*/
+/** The event type vocabulary this plugin appends. */
+const DATA_QUALITY_EVENT_TYPES = [
+	"data-quality/profile",
+	"data-quality/clean",
+	"data-quality/verify"
+];
+/**
+* Append one `data-quality/*` event when the host can carry it safely; skip
+* silently otherwise (the storage-domain report is always the durable copy).
+* The `ignorable` probe reads the UNBOUND method's source (a `.bind()` result
+* reports `[native code]`): the rc.6 build contains no `ignorable` handling
+* while the master build references the flag by name; property names survive
+* minification, so the probe fails safe (skips) rather than corrupting a log.
+* @param session - the calling session.
+* @param type - the event type.
+* @param data - the payload.
+*/
+function appendDataQualityEvent(session, type, data) {
+	if (KNOWN_SESSION_EVENT_TYPES.has(type)) {
+		session.append(type, data);
+		return;
+	}
+	const append = session.append;
+	if (Function.prototype.toString.call(append).includes("ignorable")) append.call(session, type, data, { ignorable: true });
+}
+//#endregion
+//#region src/present.ts
+/** Maximum characters one cell contributes to a tool-facing row payload. */
+const MAX_CELL_TEXT = 120;
+/**
+* Truncate one cell for display: long strings are cut with an ellipsis
+* marker; non-strings pass through.
+* @param cell - the cell to bound.
+* @returns the display-safe cell.
+*/
+function truncateCell(cell) {
+	if (typeof cell === "string" && cell.length > 120) return `${cell.slice(0, 120)}…`;
+	return cell;
+}
+/**
+* Truncate every string cell of one row.
+* @param row - the row to bound.
+* @returns a display-safe copy.
+*/
+function truncateRow(row) {
+	const out = {};
+	for (const [key, value] of Object.entries(row)) out[key] = truncateCell(value);
+	return out;
+}
+//#endregion
+//#region src/service.ts
+/**
+* Service Definition of the `dsh-data-quality` capability seam: the
+* `ctx.dataQuality` surface other plugins may optionally consume, plus the
+* internal request/report types the local Provider and the tool Consumers
+* share. The {@link CitationCheckRequest} / {@link CitationCheckResult}
+* citation contract is FROZEN for cross-plugin consumers — change it only
+* with a coordinated ecosystem migration.
+* @module dsh-data-quality/service
+*/
+/**
+* The `ctx.dataQuality` service. The local Provider implements deterministic
+* TypeScript computation; Consumers (the three tools and third-party plugins)
+* never re-implement the math.
+*/
+var DataQualityService = class extends Service {
+	/**
+	* Register as `dataQuality` on the context.
+	* @param ctx - the plugin context.
+	*/
+	constructor(ctx) {
+		super(ctx, "dataQuality");
+	}
+};
+//#endregion
+//#region src/provider-local.ts
+/**
+* The local deterministic Provider of the `ctx.dataQuality` seam: orchestrates
+* dataset loading, the pure engines, durable report persistence, and the
+* adaptive `data-quality/*` session events. All computation is TypeScript in
+* this process — no model arithmetic, no external processes.
+* @module dsh-data-quality/provider-local
+*/
+/**
+* The local deterministic `dataQuality` implementation. Mounted by the plugin
+* entry; third-party plugins consume it through `ctx.dataQuality`.
+*/
+var LocalDataQualityService = class extends DataQualityService {
+	config;
+	deps;
+	/**
+	* @param ctx - the plugin context.
+	* @param config - the resolved plugin config.
+	* @param deps - store handle plus the injected clock.
+	*/
+	constructor(ctx, config, deps) {
+		super(ctx);
+		this.config = config;
+		this.deps = deps;
+	}
+	/** The absolute root for service-level calls without a session workspace. */
+	serviceRoot() {
+		return this.config.workspaceRoot !== "" ? path.resolve(this.config.workspaceRoot) : process.cwd();
+	}
+	/** Persist one report when persistence is on; returns the storage key. */
+	async persist(kind, dataset, report) {
+		const store = this.deps.store;
+		if (store === void 0) return void 0;
+		const record = {
+			kind,
+			at: this.deps.now(),
+			dataset,
+			report
+		};
+		const key = reportKeyOf(record);
+		await store.put({ ...record });
+		return key;
+	}
+	/** Emit the adaptive session event when the call carries a session. */
+	emitEvent(session, kind, dataset, reportKey, summary) {
+		if (session === void 0) return;
+		appendDataQualityEvent(session, `data-quality/${kind}`, {
+			kind,
+			dataset,
+			...reportKey !== void 0 ? { reportKey } : {},
+			summary
+		});
+	}
+	/** @inheritdoc DataQualityService.profileDataset */
+	async profileDataset(request) {
+		throwIfAborted(request.signal);
+		const report = profileTable(await loadTable(resolveWorkspacePath(request.workspace, request.dataset, this.config), this.config, request.signal), {
+			dataset: request.dataset,
+			sample: request.sample,
+			generatedAt: this.deps.now(),
+			signal: request.signal
+		});
+		const reportKey = await this.persist("profile", request.dataset, report);
+		this.emitEvent(request.session, "profile", request.dataset, reportKey, {
+			rows: report.rowCount,
+			columns: report.columnCount
+		});
+		return {
+			...report,
+			...reportKey !== void 0 ? { reportKey } : {}
+		};
+	}
+	/** @inheritdoc DataQualityService.cleanDataset */
+	async cleanDataset(request) {
+		throwIfAborted(request.signal);
+		const absolute = resolveWorkspacePath(request.workspace, request.dataset, this.config);
+		const result = applyCleanRules(await loadTable(absolute, this.config, request.signal), request.rules, { signal: request.signal });
+		let writtenPath;
+		if (request.outputPath !== void 0) {
+			const outputAbsolute = resolveWorkspacePath(request.workspace, request.outputPath, this.config);
+			if (outputAbsolute === absolute) throw new Error(`outputPath ${JSON.stringify(request.outputPath)} would overwrite the input dataset; choose a different path`);
+			const ext = path.extname(outputAbsolute).toLowerCase();
+			const text = ext === ".csv" || ext === ".tsv" ? serializeDelimited(result.columns, result.rows, ext === ".csv" ? "," : "	") : ext === ".jsonl" ? `${result.rows.map((row) => JSON.stringify(row)).join("\n")}\n` : `${JSON.stringify(result.rows, null, 2)}\n`;
+			await mkdir(path.dirname(outputAbsolute), { recursive: true });
+			throwIfAborted(request.signal);
+			await writeFile(outputAbsolute, text, "utf8");
+			writtenPath = request.outputPath;
+		}
+		const generatedAt = this.deps.now();
+		const reportKey = await this.persist("clean", request.dataset, {
+			dataset: request.dataset,
+			inputRows: result.inputRows,
+			outputRows: result.outputRows,
+			logs: result.logs,
+			...writtenPath !== void 0 ? { outputPath: writtenPath } : {},
+			generatedAt
+		});
+		this.emitEvent(request.session, "clean", request.dataset, reportKey, {
+			rows: result.outputRows,
+			columns: result.columns.length,
+			rules: result.logs.length
+		});
+		const previewRows = result.rows.slice(0, this.config.evidenceRowLimit).map((row) => truncateRow(row));
+		return {
+			dataset: request.dataset,
+			inputRows: result.inputRows,
+			outputRows: result.outputRows,
+			logs: result.logs,
+			preview: {
+				columns: result.columns,
+				rows: previewRows
+			},
+			...writtenPath !== void 0 ? { outputPath: writtenPath } : {},
+			...reportKey !== void 0 ? { reportKey } : {},
+			generatedAt
+		};
+	}
+	/** @inheritdoc DataQualityService.verifyDataset */
+	async verifyDataset(request) {
+		throwIfAborted(request.signal);
+		const outcome = verifyTable(await loadTable(resolveWorkspacePath(request.workspace, request.dataset, this.config), this.config, request.signal), request.rules, {
+			evidenceRowLimit: this.config.evidenceRowLimit,
+			now: this.deps.now,
+			signal: request.signal
+		});
+		const report = {
+			dataset: request.dataset,
+			...outcome
+		};
+		const failedRules = report.rules.filter((rule) => !rule.passed).length;
+		const reportKey = await this.persist("verify", request.dataset, report);
+		this.emitEvent(request.session, "verify", request.dataset, reportKey, {
+			rows: report.rowCount,
+			rules: report.rules.length,
+			failedRules,
+			passed: report.passed
+		});
+		return {
+			...report,
+			...reportKey !== void 0 ? { reportKey } : {}
+		};
+	}
+	/** @inheritdoc DataQualityService.verifyCitations */
+	async verifyCitations(request) {
+		const result = checkCitations(await loadDocument(resolveWorkspacePath(this.serviceRoot(), request.dataset, this.config), this.config), request.citations, this.config.defaultTolerance);
+		const verified = result.results.filter((entry) => entry.status === "verified").length;
+		const mismatched = result.results.filter((entry) => entry.status === "mismatch").length;
+		const notFound = result.results.filter((entry) => entry.status === "not-found").length;
+		const unverifiable = result.results.filter((entry) => entry.status === "unverifiable").length;
+		await this.persist("citations", request.dataset, {
+			dataset: request.dataset,
+			checked: result.results.length,
+			verified,
+			mismatched,
+			notFound,
+			unverifiable,
+			results: result.results,
+			generatedAt: this.deps.now()
+		});
+		return result;
+	}
+};
+//#endregion
+//#region src/tools/shared.ts
+/**
+* Shared helpers for the three data-quality model tools: session workspace
+* resolution and a compact cleaning-run text render. Kept presentation-only;
+* computation lives in the engines and the provider.
+* @module dsh-data-quality/tools-shared
+*/
+/**
+* The absolute workspace root a tool call resolves dataset paths against: the
+* calling agent's per-session cwd (mirroring the official fs tools). Non-agent
+* calls fail loud — there is no honest workspace to confine paths to.
+* @param exec - the tool-execution context.
+* @returns the absolute workspace root.
+*/
+function workspaceOf(exec) {
+	const cwd = exec.agent?.session.header.cwd;
+	if (cwd === void 0) throw new Error("data-quality tools require an agent-owned session workspace");
+	return path.resolve(cwd);
+}
+/** Human-readable cleaning summary for the tool's Native render. */
+function renderCleanText(report) {
+	const lines = [];
+	lines.push(`Cleaned ${report.dataset}: ${report.inputRows} -> ${report.outputRows} rows over ${report.logs.length} rule(s)`);
+	for (const log of report.logs) lines.push(`- rule ${log.ruleIndex} (${log.rule}): ${log.affectedRows} row(s) affected; ${log.detail}`);
+	if (report.outputPath !== void 0) lines.push(`Wrote cleaned dataset to ${report.outputPath}`);
+	else lines.push("No outputPath given: the source file was left untouched; preview below.");
+	if (report.preview.rows.length > 0) {
+		lines.push(`Preview (first ${report.preview.rows.length} row(s)):`);
+		for (const row of report.preview.rows) {
+			const cells = report.preview.columns.map((column) => `${column}=${JSON.stringify(row[column] ?? null)}`).join(", ");
+			lines.push(`  ${cells}`);
+		}
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/tools/profile.ts
+/**
+* The `data_profile` model tool: deterministic dataset profiling through
+* `ctx.dataQuality.profileDataset` — never model arithmetic.
+* @module dsh-data-quality/tools/profile
+*/
+const COLUMN_PROFILE_SCHEMA = {
+	type: "object",
+	properties: {
+		name: {
+			type: "string",
+			required: true
+		},
+		inferredType: {
+			type: "string",
+			enum: [
+				"number",
+				"date",
+				"boolean",
+				"string",
+				"empty",
+				"mixed"
+			],
+			required: true
+		},
+		missing: {
+			type: "number",
+			required: true
+		},
+		missingRate: {
+			type: "number",
+			required: true
+		},
+		unique: {
+			type: "number",
+			required: true
+		},
+		numeric: {
+			type: "object",
+			properties: {
+				min: {
+					type: "number",
+					required: true
+				},
+				max: {
+					type: "number",
+					required: true
+				},
+				mean: {
+					type: "number",
+					required: true
+				},
+				median: {
+					type: "number",
+					required: true
+				},
+				p25: {
+					type: "number",
+					required: true
+				},
+				p75: {
+					type: "number",
+					required: true
+				},
+				outliers: {
+					type: "number",
+					required: true
+				}
+			},
+			additionalProperties: false
+		},
+		topValues: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					value: {
+						type: "string",
+						required: true
+					},
+					count: {
+						type: "number",
+						required: true
+					}
+				},
+				additionalProperties: false
+			}
+		},
+		notes: {
+			type: "array",
+			items: { type: "string" },
+			required: true
+		}
+	},
+	additionalProperties: false
+};
+/**
+* Build the `data_profile` tool definition against a mounted service.
+* @param service - the mounted ctx.dataQuality implementation.
+* @returns the tool definition to register.
+*/
+function defineProfileTool(service) {
+	return defineTool({
+		name: "data_profile",
+		description: [
+			"Profile a workspace CSV/TSV/JSON/JSONL dataset with deterministic TypeScript computation (no mental math).",
+			"Returns row/column counts, inferred column types, missing rates, unique counts, numeric distributions (min/max/mean/median/p25/p75), IQR outlier counts, mixed-type suspicion notes, and duplicate-row counts.",
+			"Column cards cover every row by default; pass sample for a deterministic systematic sample on large files. Datasets above the configured row/size caps are rejected — use sample or raise the caps. The full report persists to the data_quality storage domain (reportKey in the result)."
+		].join("\n"),
+		parameters: {
+			path: {
+				type: "string",
+				required: true,
+				description: "Workspace-relative dataset path (.csv/.tsv/.json/.jsonl). JSON datasets must be an array of flat objects."
+			},
+			sample: {
+				type: "number",
+				description: "Optional systematic sample size (every ceil(N/sample)-th row) for the column cards; row counts stay exact."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					dataset: {
+						type: "string",
+						required: true
+					},
+					rowCount: {
+						type: "number",
+						required: true
+					},
+					sampled: {
+						type: "boolean",
+						required: true
+					},
+					profiledRows: {
+						type: "number",
+						required: true
+					},
+					columnCount: {
+						type: "number",
+						required: true
+					},
+					duplicateRows: {
+						type: "number",
+						required: true
+					},
+					generatedAt: {
+						type: "number",
+						required: true
+					},
+					reportKey: { type: "string" },
+					columns: {
+						type: "array",
+						items: COLUMN_PROFILE_SCHEMA,
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderProfileText(value)
+			}]
+		},
+		async execute(args, exec) {
+			return service.profileDataset({
+				dataset: args.path,
+				sample: args.sample,
+				workspace: workspaceOf(exec),
+				session: exec.agent?.session,
+				signal: exec.signal
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/clean.ts
+/**
+* The `data_clean` model tool: declarative cleaning rules through
+* `ctx.dataQuality.cleanDataset`. The source file is never overwritten;
+* without `outputPath` the run is preview-only.
+* @module dsh-data-quality/tools/clean
+*/
+const STRING_MAP_SCHEMA = { type: "json" };
+const CLEAN_RULE_SCHEMA = {
+	type: "array",
+	items: { oneOf: [
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "dedupe",
+					required: true
+				},
+				columns: {
+					type: "array",
+					items: { type: "string" },
+					description: "Key columns; all columns when omitted."
+				}
+			},
+			additionalProperties: false,
+			description: "Remove rows whose key-column values duplicate an earlier row (first occurrence kept)."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "fill-missing",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				strategy: {
+					type: "string",
+					enum: [
+						"constant",
+						"mean",
+						"median",
+						"forward"
+					],
+					required: true
+				},
+				value: {
+					oneOf: [{ type: "string" }, { type: "number" }],
+					description: "Required for strategy \"constant\"."
+				}
+			},
+			additionalProperties: false,
+			description: "Fill missing cells: a constant, the column mean/median (numeric columns), or the previous non-missing value."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "coerce-type",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				to: {
+					type: "string",
+					enum: [
+						"number",
+						"date",
+						"boolean"
+					],
+					required: true
+				}
+			},
+			additionalProperties: false,
+			description: "Coerce cells to number / ISO date / boolean; failures become missing and are counted in the log."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "normalize-unit",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				factors: {
+					...STRING_MAP_SCHEMA,
+					description: "Unit suffix to multiplier, e.g. {\"万\": 10000, \"亿\": 100000000}."
+				}
+			},
+			additionalProperties: false,
+			description: "Strip a unit suffix and multiply by its factor; plain numeric values convert too."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "trim",
+					required: true
+				},
+				columns: {
+					type: "array",
+					items: { type: "string" },
+					description: "Columns to trim; all columns when omitted."
+				}
+			},
+			additionalProperties: false,
+			description: "Trim leading/trailing whitespace of string cells."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "map-values",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				map: {
+					...STRING_MAP_SCHEMA,
+					description: "Exact-match value mapping, e.g. {\"Y\": \"yes\", \"N\": \"no\"}."
+				},
+				else: {
+					type: "string",
+					enum: ["keep", "missing"],
+					description: "Policy for unmapped values (default keep)."
+				}
+			},
+			additionalProperties: false,
+			description: "Map enum values by exact match."
+		}
+	] },
+	description: "Ordered cleaning rules; each rule sees the previous rule's output."
+};
+/**
+* Build the `data_clean` tool definition against a mounted service.
+* @param service - the mounted ctx.dataQuality implementation.
+* @returns the tool definition to register.
+*/
+function defineCleanTool(service) {
+	return defineTool({
+		name: "data_clean",
+		description: [
+			"Apply declarative cleaning rules to a workspace CSV/TSV/JSON/JSONL dataset with deterministic TypeScript computation (no mental math).",
+			"Rules apply in array order: dedupe (by column group), fill-missing (constant/mean/median/forward), coerce-type (number/date/boolean; failures counted and set to missing), normalize-unit (e.g. 万/亿 suffixes to base units), trim (whitespace), map-values (enum mapping).",
+			"The source file is NEVER overwritten. Without outputPath the run is preview-only; with outputPath the cleaned dataset is written there (workspace-confined, .csv/.tsv/.json/.jsonl). Returns the per-rule audit log (affected rows per rule) plus a bounded preview. The full report persists to the data_quality storage domain (reportKey)."
+		].join("\n"),
+		parameters: {
+			path: {
+				type: "string",
+				required: true,
+				description: "Workspace-relative dataset path (.csv/.tsv/.json/.jsonl)."
+			},
+			rules: {
+				...CLEAN_RULE_SCHEMA,
+				required: true
+			},
+			outputPath: {
+				type: "string",
+				description: "Optional workspace-relative output path for the cleaned dataset (must differ from path)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					dataset: {
+						type: "string",
+						required: true
+					},
+					inputRows: {
+						type: "number",
+						required: true
+					},
+					outputRows: {
+						type: "number",
+						required: true
+					},
+					generatedAt: {
+						type: "number",
+						required: true
+					},
+					outputPath: { type: "string" },
+					reportKey: { type: "string" },
+					logs: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								ruleIndex: {
+									type: "number",
+									required: true
+								},
+								rule: {
+									type: "string",
+									enum: [
+										"dedupe",
+										"fill-missing",
+										"coerce-type",
+										"normalize-unit",
+										"trim",
+										"map-values"
+									],
+									required: true
+								},
+								affectedRows: {
+									type: "number",
+									required: true
+								},
+								detail: {
+									type: "string",
+									required: true
+								}
+							},
+							additionalProperties: false
+						},
+						required: true
+					},
+					preview: {
+						type: "object",
+						properties: {
+							columns: {
+								type: "array",
+								items: { type: "string" },
+								required: true
+							},
+							rows: {
+								type: "array",
+								items: { type: "json" },
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderCleanText(value)
+			}]
+		},
+		async execute(args, exec) {
+			return service.cleanDataset({
+				dataset: args.path,
+				rules: args.rules,
+				...args.outputPath !== void 0 ? { outputPath: args.outputPath } : {},
+				workspace: workspaceOf(exec),
+				session: exec.agent?.session,
+				signal: exec.signal
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/verify.ts
+/**
+* The `data_verify` model tool: declarative verification rules through
+* `ctx.dataQuality.verifyDataset`. A failing dataset is a normal result
+* (`passed: false` with evidence), never a tool error.
+* @module dsh-data-quality/tools/verify
+*/
+const VERIFY_RULE_SCHEMA = {
+	type: "array",
+	items: { oneOf: [
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "not-null",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				}
+			},
+			additionalProperties: false,
+			description: "Fail rows where the column is missing (null/empty/whitespace)."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "unique",
+					required: true
+				},
+				columns: {
+					type: "array",
+					items: { type: "string" },
+					required: true,
+					description: "Key columns; every row whose key repeats fails."
+				}
+			},
+			additionalProperties: false,
+			description: "Fail rows whose key-column combination appears more than once."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "range",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				min: { type: "number" },
+				max: { type: "number" }
+			},
+			additionalProperties: false,
+			description: "Fail rows where the numeric cell is missing, unparseable, or outside [min, max] (inclusive; at least one bound required)."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "regex",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				pattern: {
+					type: "string",
+					required: true
+				},
+				flags: {
+					type: "string",
+					description: "Optional JS regex flags, e.g. \"i\"."
+				}
+			},
+			additionalProperties: false,
+			description: "Fail rows where the cell is missing or does not match the pattern (full JS regex semantics)."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "enum",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true
+				},
+				values: {
+					type: "array",
+					items: { type: "string" },
+					required: true
+				}
+			},
+			additionalProperties: false,
+			description: "Fail rows where the trimmed cell text is not one of the allowed values."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "cross-column",
+					required: true
+				},
+				left: {
+					type: "string",
+					required: true,
+					description: "Left column name."
+				},
+				op: {
+					type: "string",
+					enum: [
+						"<",
+						"<=",
+						"==",
+						"!=",
+						">=",
+						">"
+					],
+					required: true
+				},
+				rightColumn: {
+					type: "string",
+					description: "Compare against another column…"
+				},
+				value: {
+					oneOf: [{ type: "number" }, { type: "string" }],
+					description: "…or against this literal (exactly one of rightColumn/value)."
+				}
+			},
+			additionalProperties: false,
+			description: "Compare two columns (e.g. startDate < endDate) or a column against a literal. Numeric when both sides parse, string equality for ==/!= otherwise."
+		},
+		{
+			type: "object",
+			properties: {
+				rule: {
+					type: "string",
+					const: "freshness",
+					required: true
+				},
+				column: {
+					type: "string",
+					required: true,
+					description: "Date column (YYYY-MM-DD, YYYY/MM/DD, or ISO datetime)."
+				},
+				maxAgeDays: {
+					type: "number",
+					required: true,
+					description: "Fail rows whose date is older than this many days before asOf."
+				},
+				asOf: {
+					type: "string",
+					description: "Reference date; defaults to the current date."
+				}
+			},
+			additionalProperties: false,
+			description: "Fail rows whose date cell is missing, unparseable, or older than maxAgeDays before asOf."
+		}
+	] },
+	description: "Verification rules; a missing cell fails every rule that reads it."
+};
+/**
+* Build the `data_verify` tool definition against a mounted service.
+* @param service - the mounted ctx.dataQuality implementation.
+* @returns the tool definition to register.
+*/
+function defineVerifyTool(service) {
+	return defineTool({
+		name: "data_verify",
+		description: [
+			"Verify a workspace CSV/TSV/JSON/JSONL dataset against declarative quality rules with deterministic TypeScript computation (no mental math).",
+			"Rules: not-null, unique (column group), range (numeric bounds), regex, enum, cross-column (e.g. startDate < endDate), freshness (date column within N days of asOf). A missing cell fails every rule that reads it.",
+			"Returns per-rule pass/fail with capped failing-row evidence. Overall failure is a NORMAL result with passed: false — not a tool error. The full report persists to the data_quality storage domain (reportKey)."
+		].join("\n"),
+		parameters: {
+			path: {
+				type: "string",
+				required: true,
+				description: "Workspace-relative dataset path (.csv/.tsv/.json/.jsonl)."
+			},
+			rules: {
+				...VERIFY_RULE_SCHEMA,
+				required: true
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					dataset: {
+						type: "string",
+						required: true
+					},
+					passed: {
+						type: "boolean",
+						required: true
+					},
+					rowCount: {
+						type: "number",
+						required: true
+					},
+					generatedAt: {
+						type: "number",
+						required: true
+					},
+					reportKey: { type: "string" },
+					rules: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								ruleIndex: {
+									type: "number",
+									required: true
+								},
+								rule: {
+									type: "string",
+									enum: [
+										"not-null",
+										"unique",
+										"range",
+										"regex",
+										"enum",
+										"cross-column",
+										"freshness"
+									],
+									required: true
+								},
+								passed: {
+									type: "boolean",
+									required: true
+								},
+								failedCount: {
+									type: "number",
+									required: true
+								},
+								checkedCount: {
+									type: "number",
+									required: true
+								},
+								evidence: {
+									type: "array",
+									items: {
+										type: "object",
+										properties: {
+											rowIndex: {
+												type: "number",
+												required: true
+											},
+											values: {
+												type: "json",
+												required: true
+											}
+										},
+										additionalProperties: false
+									},
+									required: true
+								}
+							},
+							additionalProperties: false
+						},
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderVerifyText(value)
+			}]
+		},
+		async execute(args, exec) {
+			return service.verifyDataset({
+				dataset: args.path,
+				rules: args.rules,
+				workspace: workspaceOf(exec),
+				session: exec.agent?.session,
+				signal: exec.signal
+			});
+		}
+	});
+}
+//#endregion
+//#region src/version.ts
+/**
+* Plugin version, kept in one place so `scripts/release.mjs` can stamp it and
+* reports can name their generator.
+* @module dsh-data-quality/version
+*/
+/** The package version reported in persisted reports. */
+const VERSION = "0.1.0";
+//#endregion
+//#region src/index.ts
+const name = "data-quality";
+/** The three model tools and the durable report domain. */
+const inject = ["tools", "storageDomain"];
+/**
+* Mount the seam: resolve config (fail loud), open the report domain, publish
+* `ctx.dataQuality`, and register the three tools. With `enabled: false` the
+* plugin registers nothing and stays inert.
+* @param ctx - the plugin context (host).
+* @param config - raw plugin config.
+*/
+async function apply(ctx, config = {}) {
+	const resolved = resolveConfig(config);
+	const logger = ctx.logger("data-quality");
+	if (!resolved.enabled) {
+		logger.info("disabled: enabled is false — no service or tools are mounted");
+		return;
+	}
+	let store;
+	let domain;
+	if (resolved.storeReports) {
+		domain = await ctx.storageDomain.open(dataQualityDomainSpec);
+		const reports = domain.table("reports");
+		store = {
+			put: async (record) => {
+				const key = reportKeyOf(record);
+				await reports.put(key, record);
+				return key;
+			},
+			get: (key) => reports.get(key)
+		};
+	}
+	const service = new LocalDataQualityService(ctx, resolved, {
+		store,
+		now: Date.now
+	});
+	ctx.tools.register(defineProfileTool(service));
+	ctx.tools.register(defineCleanTool(service));
+	ctx.tools.register(defineVerifyTool(service));
+	logger.info(`dsh-data-quality ${VERSION} mounted: ctx.dataQuality + data_profile/data_clean/data_verify`);
+	if (domain !== void 0) {
+		const handle = domain;
+		ctx.effect(() => async () => {
+			await handle.close();
+		});
+	}
+}
+//#endregion
+export { Config, DATA_QUALITY_EVENT_TYPES, DataQualityService, DatasetError, LocalDataQualityService, MAX_CELL_TEXT, VERSION, appendDataQualityEvent, apply, applyCleanRules, checkCitations, dataQualityDomainSpec, inject, isMissing, loadDocument, loadTable, name, parseBoolean, parseDate, parseDelimited, parseJsonTable, parseLocator, parseNumeric, profileTable, renderProfileText, renderVerifyText, reportKeyOf, reportRecordSchema, resolveConfig, resolveWorkspacePath, sampleRows, serializeDelimited, truncateCell, truncateRow, verifyTable };