dsh-data-quality 0.1.3 → 0.3.0

package/lib/index.js

@@ -4,6 +4,7 @@ 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 { TextDecoder } from "node:util";
 import { KNOWN_SESSION_EVENT_TYPES } from "@deepseek-ai/dsh-session";
 import { Service } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -14,6 +15,15 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 * step validates bounds so misconfiguration fails loud at mount.
 * @module dsh-data-quality/config
 */
+/** The six scorecard dimension ids, in report order (kept in sync with `scorecard.ts`). */
+const SCORECARD_DIMENSIONS = [
+	"completeness",
+	"uniqueness",
+	"validity",
+	"consistency",
+	"timeliness",
+	"accuracy"
+];
 /** Schemastery schema: the loader validates and fills defaults before `apply`. */
 const Config = z.object({
 	enabled: z.boolean().default(true),
@@ -28,7 +38,22 @@ const Config = z.object({
 		".jsonl"
 	]),
 	workspaceRoot: z.string().default(""),
-	storeReports: z.boolean().default(true)
+	storeReports: z.boolean().default(true),
+	scorecardWeights: z.object({
+		completeness: z.number().default(1),
+		uniqueness: z.number().default(1),
+		validity: z.number().default(1),
+		consistency: z.number().default(1),
+		timeliness: z.number().default(1),
+		accuracy: z.number().default(1)
+	}).default({
+		completeness: 1,
+		uniqueness: 1,
+		validity: 1,
+		consistency: 1,
+		timeliness: 1,
+		accuracy: 1
+	})
 });
 /** Throw unless `value` is a positive safe integer. */
 function assertPositiveInt(name, value) {
@@ -63,6 +88,7 @@ function resolveConfig(config = {}) {
 		return ext;
 	});
 	if (allowedExtensions.length === 0) throw new TypeError("allowedExtensions must not be empty");
+	const scorecardWeights = resolveScorecardWeights(config.scorecardWeights);
 	return {
 		enabled: config.enabled ?? true,
 		maxRows,
@@ -71,9 +97,20 @@ function resolveConfig(config = {}) {
 		evidenceRowLimit,
 		allowedExtensions,
 		workspaceRoot: config.workspaceRoot ?? "",
-		storeReports: config.storeReports ?? true
+		storeReports: config.storeReports ?? true,
+		scorecardWeights
 	};
 }
+/** Resolve scorecard weights, filling defaults and rejecting non-negative violations loudly. */
+function resolveScorecardWeights(weights = {}) {
+	const out = {};
+	for (const dimension of SCORECARD_DIMENSIONS) {
+		const value = weights[dimension] ?? 1;
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new TypeError(`scorecardWeights.${dimension} must be a non-negative finite number, got ${String(value)}`);
+		out[dimension] = value;
+	}
+	return out;
+}
 //#endregion
 //#region src/dataset.ts
 /**
@@ -127,13 +164,40 @@ 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.
+* Detect a UTF-8 byte-order mark and validate the byte sequence. Invalid
+* UTF-8 is a data-quality finding the profile reports (`validUtf8: false`)
+* rather than a structural error that blocks the read — the decoded text
+* keeps U+FFFD replacement characters so the profile can still run.
+* @param buffer - raw file bytes.
+* @returns the encoding metadata.
+*/
+function detectEncoding(buffer) {
+	const bom = buffer.length >= 3 && buffer[0] === 239 && buffer[1] === 187 && buffer[2] === 191 ? "utf-8" : null;
+	const body = bom === "utf-8" ? buffer.subarray(3) : buffer;
+	let validUtf8 = true;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(body);
+	} catch {
+		validUtf8 = false;
+	}
+	return {
+		bom,
+		validUtf8
+	};
+}
+/** Decode file bytes, stripping a UTF-8 BOM and preserving replacement characters for invalid bytes. */
+function decodeUtf8Text(buffer, encoding) {
+	const body = encoding.bom === "utf-8" ? buffer.subarray(3) : buffer;
+	return new TextDecoder("utf-8").decode(body);
+}
+/**
+* Read a dataset file under the size cap, detecting its encoding.
 * @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.
+* @returns the decoded UTF-8 text plus its encoding metadata.
 */
-async function readDatasetText(absolutePath, config, signal) {
+async function readDatasetFile(absolutePath, config, signal) {
 	throwIfAborted(signal);
 	let info;
 	try {
@@ -147,7 +211,12 @@ async function readDatasetText(absolutePath, config, signal) {
 	const handle = await open(absolutePath, "r");
 	try {
 		throwIfAborted(signal);
-		return await handle.readFile("utf8");
+		const buffer = await handle.readFile();
+		const encoding = detectEncoding(buffer);
+		return {
+			text: decodeUtf8Text(buffer, encoding),
+			encoding
+		};
 	} finally {
 		await handle.close();
 	}
@@ -316,12 +385,21 @@ function parseJsonLines(text) {
 * @returns the parsed table.
 */
 async function loadTable(absolutePath, config, signal) {
-	const text = await readDatasetText(absolutePath, config, signal);
+	const { text, encoding } = await readDatasetFile(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);
+	if (ext === ".csv") return {
+		...parseDelimited(text, ",", config, signal),
+		encoding
+	};
+	if (ext === ".tsv") return {
+		...parseDelimited(text, "	", config, signal),
+		encoding
+	};
+	return {
+		...parseJsonTable(text, ext, config, signal),
+		encoding
+	};
 }
 /**
 * Load a dataset as a citation-checkable document root: CSV/TSV become
@@ -334,14 +412,20 @@ async function loadTable(absolutePath, config, signal) {
 */
 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))
-	};
+	if (ext === ".json") {
+		const { text } = await readDatasetFile(absolutePath, config, signal);
+		return {
+			kind: "json",
+			value: parseJsonDocument(text)
+		};
+	}
+	if (ext === ".jsonl") {
+		const { text } = await readDatasetFile(absolutePath, config, signal);
+		return {
+			kind: "json",
+			value: parseJsonLines(text)
+		};
+	}
 	const table = await loadTable(absolutePath, config, signal);
 	return {
 		kind: "table",
@@ -390,18 +474,17 @@ const DATE_PATTERNS = [
 	/^(\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) {
+/** Deterministic date-format labels in {@link DATE_PATTERNS} order. */
+const DATE_FORMATS = [
+	"iso-date",
+	"slash-date",
+	"datetime"
+];
+/** Parse one date cell to its epoch plus format; `undefined` when unrecognized. */
+function parseDateCellInternal(cell) {
 	if (typeof cell !== "string") return void 0;
 	const text = cell.trim();
-	for (const pattern of DATE_PATTERNS) {
+	for (const [index, pattern] of DATE_PATTERNS.entries()) {
 		const match = pattern.exec(text);
 		if (match === null) continue;
 		const year = Number(match[1]);
@@ -414,9 +497,43 @@ function parseDate(cell) {
 		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;
+		const format = DATE_FORMATS[index];
+		if (format === void 0) return void 0;
+		return {
+			epoch,
+			format
+		};
 	}
 }
+/**
+* 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) {
+	return parseDateCellInternal(cell)?.epoch;
+}
+/**
+* Parse one date cell to its epoch plus source format label.
+* @param cell - the cell to parse (`undefined` when the column is absent).
+* @returns the parsed date, or `undefined` when the cell is not a recognized date.
+*/
+function parseDateCell(cell) {
+	return parseDateCellInternal(cell);
+}
+/**
+* The format label of a recognized date cell (`iso-date` / `slash-date` /
+* `datetime`); `undefined` when the cell is not a recognized date. Used to
+* measure a date column's format consistency.
+* @param cell - the cell to inspect (`undefined` when the column is absent).
+* @returns the source format label, or `undefined`.
+*/
+function dateFormatOf(cell) {
+	return parseDateCellInternal(cell)?.format;
+}
 /** Boolean parse: true/false/yes/no/1/0, case-insensitive. */
 function parseBoolean(cell) {
 	if (typeof cell === "boolean") return cell;
@@ -440,7 +557,8 @@ const reportRecordSchema = z$1.object({
 		"profile",
 		"clean",
 		"verify",
-		"citations"
+		"citations",
+		"clean-diff"
 	]),
 	at: z$1.number().int().nonnegative(),
 	dataset: z$1.string(),
@@ -452,6 +570,18 @@ const dataQualityDomainSpec = defineDomain({
 	version: 1,
 	tables: { reports: domainTable(reportRecordSchema) }
 });
+/** Well-formed report-key shape: `<17-digit timestamp>-<kind>-<8-hex fingerprint>`. */
+const REPORT_KEY_PATTERN = /^\d{17}-(?:profile|clean|verify|citations|clean-diff)-[0-9a-f]{8}$/u;
+/**
+* Whether `key` is a well-formed, path-safe storage report key. Rejects any
+* key with separators, traversal, or unexpected characters before it can be
+* handed to the storage backend.
+* @param key - candidate report key.
+* @returns whether the key matches the deterministic report-key format.
+*/
+function isValidReportKey(key) {
+	return REPORT_KEY_PATTERN.test(key);
+}
 /** Pad to two digits for the key timestamp. */
 function pad2(value) {
 	return String(value).padStart(2, "0");
@@ -842,6 +972,215 @@ function serializeDelimited(columns, rows, delimiter) {
 	return `${lines.join("\n")}\n`;
 }
 //#endregion
+//#region src/scorecard.ts
+/**
+* DAMA-style six-dimension quality scorecard over a parsed {@link Table}.
+* Pure and deterministic: every rate derives from one full-table pass, the
+* only clock is the injected `now`, and no dimension fabricates a score it
+* cannot defend — `accuracy` stays `null` (undetermined) without a declared
+* schema and `timeliness` stays `null` without date cells.
+* @module dsh-data-quality/scorecard
+*/
+/** Round to 6 significant digits (mirrors the profile report's rounding). */
+function round6$1(value) {
+	return Number(value.toPrecision(6));
+}
+/** Increment a format-label counter. */
+function bump(formats, tag) {
+	formats.set(tag, (formats.get(tag) ?? 0) + 1);
+}
+/** Inferred column type from the full-table class counts (mirrors `profileColumn`). */
+function inferType(stats) {
+	if (stats.present === 0) return "empty";
+	if (stats.number === stats.present) return "number";
+	if (stats.date === stats.present) return "date";
+	if (stats.boolean === stats.present) return "boolean";
+	if (stats.string === stats.present) return "string";
+	return "mixed";
+}
+/** Format the `value / total` ratio as a plain `note` fragment. */
+function ratioNote(numerator, denominator) {
+	return `${numerator}/${denominator}`;
+}
+/** Build one determinable dimension with its ratio note. */
+function dimension(name, score, numerator, denominator) {
+	return {
+		name,
+		score,
+		note: ratioNote(numerator, denominator)
+	};
+}
+/**
+* Compute the six-dimension scorecard over a full table:
+* - `completeness` — non-empty cell rate.
+* - `uniqueness` — unique full-row content rate (`1 - duplicateRows / rowCount`).
+* - `validity` — present cells conforming to their column's inferred type.
+* - `consistency` — present cells in their column's dominant format (a date
+*   column's unified `YYYY-MM-DD` vs `YYYY/MM/DD` vs datetime ratio).
+* - `timeliness` — date cells not future-dated relative to the injected `now`.
+* - `accuracy` — declared-schema agreement (limited definition); `null`
+*   (undetermined) without a declared schema — never fabricated.
+* @param table - the parsed dataset (full table, not the sampled cards).
+* @param options - injected clock, duplicate-row count, optional declared schema, optional weights, abort signal.
+* @returns the scorecard.
+*/
+function computeScorecard(table, options) {
+	throwIfAborted(options.signal);
+	const stats = /* @__PURE__ */ new Map();
+	for (const column of table.columns) stats.set(column, {
+		present: 0,
+		number: 0,
+		date: 0,
+		boolean: 0,
+		string: 0,
+		formats: /* @__PURE__ */ new Map()
+	});
+	let missingCells = 0;
+	let dateCells = 0;
+	let futureDateCells = 0;
+	for (const [index, row] of table.rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(options.signal);
+		for (const column of table.columns) {
+			const cell = row[column];
+			const columnStats = stats.get(column);
+			if (isMissing(cell)) {
+				missingCells += 1;
+				continue;
+			}
+			columnStats.present += 1;
+			if (parseNumeric(cell) !== void 0) {
+				columnStats.number += 1;
+				bump(columnStats.formats, "number");
+				continue;
+			}
+			const date = parseDateCell(cell);
+			if (date !== void 0) {
+				columnStats.date += 1;
+				bump(columnStats.formats, date.format);
+				dateCells += 1;
+				if (date.epoch > options.now) futureDateCells += 1;
+				continue;
+			}
+			if (parseBoolean(cell) !== void 0) {
+				columnStats.boolean += 1;
+				bump(columnStats.formats, "boolean");
+				continue;
+			}
+			columnStats.string += 1;
+			bump(columnStats.formats, typeof cell === "string" ? "string" : "json");
+		}
+	}
+	const totalCells = table.rows.length * table.columns.length;
+	let presentCells = 0;
+	let invalidCells = 0;
+	let consistentCells = 0;
+	for (const [, columnStats] of stats) {
+		presentCells += columnStats.present;
+		const dominantClass = Math.max(columnStats.number, columnStats.date, columnStats.boolean, columnStats.string);
+		invalidCells += columnStats.present - dominantClass;
+		if (columnStats.present === 0) continue;
+		let dominant = 0;
+		for (const count of columnStats.formats.values()) if (count > dominant) dominant = count;
+		consistentCells += dominant;
+	}
+	const dimensions = [
+		totalCells === 0 ? {
+			name: "completeness",
+			score: null,
+			note: "undetermined: no cells"
+		} : dimension("completeness", round6$1(1 - missingCells / totalCells), presentCells, totalCells),
+		table.rows.length === 0 ? {
+			name: "uniqueness",
+			score: null,
+			note: "undetermined: no rows"
+		} : dimension("uniqueness", round6$1(1 - options.duplicateRows / table.rows.length), table.rows.length - options.duplicateRows, table.rows.length),
+		presentCells === 0 ? {
+			name: "validity",
+			score: null,
+			note: "undetermined: no present cells"
+		} : dimension("validity", round6$1(1 - invalidCells / presentCells), presentCells - invalidCells, presentCells),
+		presentCells === 0 ? {
+			name: "consistency",
+			score: null,
+			note: "undetermined: no present cells"
+		} : dimension("consistency", round6$1(consistentCells / presentCells), consistentCells, presentCells),
+		dateCells === 0 ? {
+			name: "timeliness",
+			score: null,
+			note: "undetermined: no date cells"
+		} : dimension("timeliness", round6$1(1 - futureDateCells / dateCells), dateCells - futureDateCells, dateCells),
+		computeAccuracy(stats, table, options.declaredSchema)
+	];
+	const scores = dimensions.map((entry) => entry.score).filter((score) => score !== null);
+	return {
+		dimensions,
+		overall: scores.length === 0 ? null : round6$1(scores.reduce((sum, score) => sum + score, 0) / scores.length),
+		weightedOverall: computeWeightedOverall(dimensions, options.weights)
+	};
+}
+/** Weighted mean over determinable dimensions (weights default to 1; validated non-negative by config). */
+function computeWeightedOverall(dimensions, weights) {
+	let weightedSum = 0;
+	let weightTotal = 0;
+	for (const entry of dimensions) {
+		if (entry.score === null) continue;
+		const weight = weights?.[entry.name] ?? 1;
+		weightedSum += weight * entry.score;
+		weightTotal += weight;
+	}
+	return weightTotal === 0 ? null : round6$1(weightedSum / weightTotal);
+}
+/**
+* Limited `accuracy` definition: agreement between the full-table inferred
+* type of each declared column and the declared type. Without a declared
+* schema (or an external truth source) the dimension is `null` (undetermined)
+* — accuracy is never fabricated.
+*/
+function computeAccuracy(stats, table, declaredSchema) {
+	if (declaredSchema === void 0 || Object.keys(declaredSchema).length === 0) return {
+		name: "accuracy",
+		score: null,
+		note: "undetermined: no declared schema or external truth to compare against; accuracy is never fabricated"
+	};
+	let checked = 0;
+	let matched = 0;
+	const mismatches = [];
+	for (const column of table.columns) {
+		const declared = declaredSchema[column];
+		if (declared === void 0) continue;
+		checked += 1;
+		const inferred = inferType(stats.get(column));
+		if (inferred === declared) matched += 1;
+		else mismatches.push(`${column}: declared ${declared}, inferred ${inferred}`);
+	}
+	if (checked === 0) return {
+		name: "accuracy",
+		score: null,
+		note: "undetermined: declared schema covers none of the dataset columns"
+	};
+	return {
+		name: "accuracy",
+		score: round6$1(matched / checked),
+		note: `${matched}/${checked} columns match their declared type` + (mismatches.length > 0 ? `; mismatches: ${mismatches.join(", ")}` : "")
+	};
+}
+//#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.3.0";
+/**
+* Version of the persisted report schema. Bump it whenever a report's
+* canonical shape changes in a way old consumers cannot read (the durable
+* `data_quality` records keep their own `schemaVersion` so a future reader
+* can detect and reject an incompatible record instead of misreading it).
+*/
+const REPORT_SCHEMA_VERSION = 1;
+//#endregion
 //#region src/profile.ts
 /**
 * Deterministic dataset profiling: per-column type inference, missingness,
@@ -850,6 +1189,8 @@ function serializeDelimited(columns, rows, delimiter) {
 * no I/O; `generatedAt` is injected by the caller.
 * @module dsh-data-quality/profile
 */
+/** Fallback duplicate-sample cap for direct engine use; the provider always passes the configured `evidenceRowLimit`. */
+const DEFAULT_DUPLICATE_SAMPLE_LIMIT = 20;
 /** Round to 6 significant digits for stable, readable report numbers. */
 function round6(value) {
 	return Number(value.toPrecision(6));
@@ -874,6 +1215,8 @@ function numericProfile(values) {
 	const highFence = p75 + 1.5 * iqr;
 	const outliers = iqr === 0 ? 0 : sorted.filter((value) => value < lowFence || value > highFence).length;
 	return {
+		count: sorted.length,
+		distinct: new Set(sorted).size,
 		min: round6(sorted[0]),
 		max: round6(sorted[sorted.length - 1]),
 		mean: round6(sum / sorted.length),
@@ -883,17 +1226,43 @@ function numericProfile(values) {
 		outliers
 	};
 }
-/** Count rows whose full content duplicates an earlier row (first occurrence is not counted). */
-function countDuplicateRows(table, signal) {
+/** Deterministic sha256 key of one row's full content (columns in table order). */
+function rowContentKey(table, row) {
+	return createHash("sha256").update(JSON.stringify(table.columns.map((column) => row[column] ?? null))).digest("hex");
+}
+/**
+* Detect full-content duplicate rows with a bounded sample of their 0-based
+* indexes. The first occurrence of each content is never counted; later rows
+* with identical full content are duplicates.
+* @param table - the parsed dataset.
+* @param options - sample cap and optional abort signal.
+* @returns the duplicate count, rate, and capped sample indexes.
+*/
+function detectDuplicateRows(table, options) {
+	if (!Number.isSafeInteger(options.sampleLimit) || options.sampleLimit <= 0) throw new TypeError(`sampleLimit must be a positive safe integer, got ${String(options.sampleLimit)}`);
 	const seen = /* @__PURE__ */ new Set();
 	let duplicates = 0;
+	const duplicateSampleRowIndexes = [];
 	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);
+		if (index % 1024 === 0) throwIfAborted(options.signal);
+		const key = rowContentKey(table, row);
+		if (seen.has(key)) {
+			duplicates += 1;
+			if (duplicateSampleRowIndexes.length < options.sampleLimit) duplicateSampleRowIndexes.push(index);
+		} else seen.add(key);
 	}
-	return duplicates;
+	return {
+		duplicateRows: duplicates,
+		duplicateRate: table.rows.length === 0 ? 0 : round6(duplicates / table.rows.length),
+		duplicateSampleRowIndexes
+	};
+}
+/** Count rows whose full content duplicates an earlier row (first occurrence is not counted). */
+function countDuplicateRows(table, signal) {
+	return detectDuplicateRows(table, {
+		sampleLimit: 1,
+		signal
+	}).duplicateRows;
 }
 /** Profile one column over the given rows. */
 function profileColumn(rows, column, signal) {
@@ -980,14 +1349,29 @@ 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);
+	const detection = detectDuplicateRows(table, {
+		sampleLimit: options.duplicateSampleLimit ?? DEFAULT_DUPLICATE_SAMPLE_LIMIT,
+		signal: options.signal
+	});
+	const scorecard = computeScorecard(table, {
+		now: options.generatedAt,
+		duplicateRows: detection.duplicateRows,
+		declaredSchema: options.declaredSchema,
+		weights: options.scorecardWeights,
+		signal: options.signal
+	});
 	return {
+		schemaVersion: 1,
 		dataset: options.dataset,
 		rowCount: table.rows.length,
 		sampled: profiled.length !== table.rows.length,
 		profiledRows: profiled.length,
 		columnCount: table.columns.length,
-		duplicateRows,
+		duplicateRows: detection.duplicateRows,
+		duplicateRate: detection.duplicateRate,
+		duplicateSampleRowIndexes: detection.duplicateSampleRowIndexes,
+		scorecard,
+		...table.encoding !== void 0 ? { encoding: table.encoding } : {},
 		columns,
 		generatedAt: options.generatedAt
 	};
@@ -996,19 +1380,167 @@ function profileTable(table, options) {
 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}`);
+	if (report.duplicateRows > 0) lines.push(`Duplicate rows: ${report.duplicateRows} (${(report.duplicateRate * 100).toFixed(1)}%)` + (report.duplicateSampleRowIndexes.length > 0 ? `; sample row indexes: ${report.duplicateSampleRowIndexes.join(", ")}` : ""));
 	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.numeric !== void 0) parts.push(`count ${column.numeric.count}, distinct ${column.numeric.distinct}, 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("; ")}`);
 	}
+	if (report.encoding !== void 0) lines.push(`Encoding: UTF-8${report.encoding.bom === "utf-8" ? " (BOM)" : ""}${report.encoding.validUtf8 ? "" : " (INVALID UTF-8)"}`);
+	const overall = report.scorecard.overall;
+	const weighted = report.scorecard.weightedOverall;
+	lines.push(`Scorecard (overall ${overall === null ? "undetermined" : `${(overall * 100).toFixed(1)}%`}, weighted ${weighted === null ? "undetermined" : `${(weighted * 100).toFixed(1)}%`}):`);
+	for (const dimension of report.scorecard.dimensions) {
+		const value = dimension.score === null ? "undetermined" : `${(dimension.score * 100).toFixed(1)}%`;
+		lines.push(`  ${dimension.name}: ${value} (${dimension.note})`);
+	}
 	return lines.join("\n");
 }
 //#endregion
+//#region src/contract.ts
+/**
+* Delivery contract for `data_clean`: a deterministic pre-delivery validation
+* summary (primary-key/type/dedupe row-count comparison plus uniqueness and
+* non-null regression) and the clean before/after profile diff report. Pure —
+* no I/O, no clock, no RNG; timestamps are injected.
+* @module dsh-data-quality/contract
+*/
+/** Count missing cells in one column of the cleaned output. */
+function countMissing(rows, column, signal) {
+	let count = 0;
+	for (const [index, row] of rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		if (isMissing(row[column])) count += 1;
+	}
+	return count;
+}
+/** Count present cells in one column that still fail to parse as the requested type. */
+function countNonConforming(rows, column, to, signal) {
+	let count = 0;
+	for (const [index, row] of rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(signal);
+		const cell = row[column];
+		if (isMissing(cell)) continue;
+		if (!(to === "number" ? parseNumeric(cell) !== void 0 : to === "date" ? parseDate(cell) !== void 0 : parseBoolean(cell) !== void 0)) count += 1;
+	}
+	return count;
+}
+/**
+* Compute the pre-delivery contract summary from a cleaning run: dedupe
+* before/after row counts, the dedupe key's uniqueness regression, and the
+* non-null/type regressions over the columns the rules targeted.
+* @param result - the cleaning outcome (input/output rows plus cleaned rows).
+* @param rules - the ordered rules that produced `result`.
+* @param options - optional abort signal.
+* @returns the contract summary.
+*/
+function computeCleanContract(result, rules, options = {}) {
+	const dedupeRule = rules.find((rule) => rule.rule === "dedupe");
+	const dedupeColumns = dedupeRule === void 0 ? null : [...dedupeRule.columns ?? result.columns];
+	const keyColumns = dedupeColumns ?? result.columns;
+	const seen = /* @__PURE__ */ new Set();
+	let remainingDuplicateRows = 0;
+	for (const [index, row] of result.rows.entries()) {
+		if (index % 1024 === 0) throwIfAborted(options.signal);
+		const key = JSON.stringify(keyColumns.map((column) => row[column] ?? null));
+		if (seen.has(key)) remainingDuplicateRows += 1;
+		else seen.add(key);
+	}
+	const remainingMissing = rules.filter((rule) => rule.rule === "fill-missing").map((rule) => {
+		const fill = rule;
+		return {
+			column: fill.column,
+			count: countMissing(result.rows, fill.column, options.signal)
+		};
+	});
+	const typeConformance = rules.filter((rule) => rule.rule === "coerce-type").map((rule) => {
+		const coerce = rule;
+		return {
+			column: coerce.column,
+			to: coerce.to,
+			invalidCount: countNonConforming(result.rows, coerce.column, coerce.to, options.signal)
+		};
+	});
+	const columnDecisions = traceColumnDecisions(result, rules);
+	return {
+		inputRows: result.inputRows,
+		outputRows: result.outputRows,
+		removedRows: result.inputRows - result.outputRows,
+		dedupeColumns,
+		uniqueKeys: remainingDuplicateRows === 0,
+		remainingDuplicateRows,
+		remainingMissing,
+		typeConformance,
+		columnDecisions
+	};
+}
+/** The columns a single rule targets (single-column rules target one column; trim/dedupe may target many). */
+function ruleColumns(rule, allColumns) {
+	switch (rule.rule) {
+		case "fill-missing":
+		case "coerce-type":
+		case "normalize-unit":
+		case "map-values": return [rule.column];
+		case "trim":
+		case "dedupe": return [...rule.columns ?? allColumns];
+		default: return [];
+	}
+}
+/** Build the per-column decision trace: strategies + affected rows, in dataset column order. */
+function traceColumnDecisions(result, rules) {
+	const byColumn = /* @__PURE__ */ new Map();
+	for (const [index, rule] of rules.entries()) {
+		const log = result.logs[index];
+		if (log === void 0) continue;
+		for (const column of ruleColumns(rule, result.columns)) {
+			const list = byColumn.get(column) ?? [];
+			list.push({
+				strategy: rule.rule,
+				affectedRows: log.affectedRows
+			});
+			byColumn.set(column, list);
+		}
+	}
+	return result.columns.filter((column) => byColumn.has(column)).map((column) => ({
+		column,
+		decisions: byColumn.get(column)
+	}));
+}
+/**
+* Build the clean before/after profile diff: two full {@link ProfileReport}
+* snapshots (input and cleaned output) under one envelope. Reuses the profile
+* engine so the scorecard and duplicate detection stay consistent across the
+* whole plugin.
+* @param input - the input dataset.
+* @param output - the cleaned dataset.
+* @param options - dataset label, injected timestamp, optional weights, optional abort signal.
+* @returns the diff report.
+*/
+function computeCleanProfileDiff(input, output, options) {
+	const before = profileTable(input, {
+		dataset: options.dataset,
+		generatedAt: options.generatedAt,
+		scorecardWeights: options.scorecardWeights,
+		signal: options.signal
+	});
+	const after = profileTable(output, {
+		dataset: options.dataset,
+		generatedAt: options.generatedAt,
+		scorecardWeights: options.scorecardWeights,
+		signal: options.signal
+	});
+	return {
+		dataset: options.dataset,
+		before,
+		after,
+		generatedAt: options.generatedAt
+	};
+}
+//#endregion
 //#region src/verify.ts
 /**
 * Declarative verification rules over a parsed {@link Table} (not-null,
@@ -1031,6 +1563,19 @@ var VerifyRuleError = class extends Error {
 		this.name = "VerifyRuleError";
 	}
 };
+/** Raised for invalid expectations; `message` names the expectation index and reason. */
+var VerifyExpectationError = class extends Error {
+	expectationIndex;
+	/**
+	* @param expectationIndex - index of the offending expectation in the request array.
+	* @param message - actionable human-readable detail.
+	*/
+	constructor(expectationIndex, message) {
+		super(message);
+		this.expectationIndex = expectationIndex;
+		this.name = "VerifyExpectationError";
+	}
+};
 /** 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(", ")})`);
@@ -1076,13 +1621,90 @@ const CROSS_OPS = [
 	">=",
 	">"
 ];
+/** The metric ids, for validation and diagnostics. */
+const VERIFY_METRICS = [
+	"rowCount",
+	"columnSum",
+	"columnMean",
+	"uniqueCount",
+	"nullCount"
+];
+/** Throw unless the expectation is well-formed (metric/column/tolerance). */
+function validateExpectation(table, expectation, index) {
+	if (!VERIFY_METRICS.includes(expectation.metric)) throw new VerifyExpectationError(index, `expectation ${index}: unknown metric ${JSON.stringify(expectation.metric)} (expected one of ${VERIFY_METRICS.join(", ")})`);
+	if (expectation.metric !== "rowCount") {
+		if (expectation.column === void 0 || expectation.column === "") throw new VerifyExpectationError(index, `expectation ${index}: metric ${expectation.metric} requires a column`);
+		if (!table.columns.includes(expectation.column)) throw new VerifyExpectationError(index, `expectation ${index}: unknown column ${JSON.stringify(expectation.column)} (columns: ${table.columns.join(", ")})`);
+	} else if (expectation.column !== void 0) throw new VerifyExpectationError(index, `expectation ${index}: metric rowCount takes no column, got ${JSON.stringify(expectation.column)}`);
+	if (expectation.tolerance !== void 0 && (typeof expectation.tolerance !== "number" || !Number.isFinite(expectation.tolerance) || expectation.tolerance < 0 || expectation.tolerance > 1)) throw new VerifyExpectationError(index, `expectation ${index}: tolerance must be a finite number in [0, 1], got ${String(expectation.tolerance)}`);
+}
+/** Compute the deterministic actual value of one expectation's metric. */
+function metricValueOf(table, expectation) {
+	switch (expectation.metric) {
+		case "rowCount": return table.rows.length;
+		case "nullCount": {
+			let count = 0;
+			for (const row of table.rows) if (isMissing(row[expectation.column])) count += 1;
+			return count;
+		}
+		case "uniqueCount": {
+			const distinct = /* @__PURE__ */ new Set();
+			for (const row of table.rows) {
+				const cell = row[expectation.column];
+				if (isMissing(cell)) continue;
+				distinct.add(typeof cell === "string" ? cell : JSON.stringify(cell));
+			}
+			return distinct.size;
+		}
+		case "columnSum":
+		case "columnMean": {
+			let sum = 0;
+			let count = 0;
+			for (const row of table.rows) {
+				const value = parseNumeric(row[expectation.column]);
+				if (value === void 0) continue;
+				sum += value;
+				count += 1;
+			}
+			return expectation.metric === "columnSum" ? sum : count === 0 ? 0 : sum / count;
+		}
+	}
+}
+/**
+* Reconcile each expectation against its deterministic actual value. A
+* mismatch is a normal `passed: false` result, never a thrown error; invalid
+* metrics, columns, and tolerances fail loud.
+* @param table - the parsed dataset.
+* @param expectations - the expectations to reconcile.
+* @param defaultTolerance - configured fallback relative tolerance.
+* @param signal - optional abort signal.
+* @returns one outcome per expectation.
+*/
+function verifyExpectations(table, expectations, defaultTolerance, signal) {
+	return expectations.map((expectation, index) => {
+		throwIfAborted(signal);
+		validateExpectation(table, expectation, index);
+		const actual = metricValueOf(table, expectation);
+		const tolerance = expectation.tolerance ?? defaultTolerance;
+		const passed = numericClose(actual, expectation.expected, tolerance);
+		return {
+			metric: expectation.metric,
+			...expectation.column !== void 0 ? { column: expectation.column } : {},
+			expected: expectation.expected,
+			actual,
+			tolerance,
+			passed
+		};
+	});
+}
 /**
 * 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.
+* rule that reads it. The overall `passed` is the conjunction of rule passes
+* and expectation 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.
+* @param options - evidence cap, injected clock for `freshness`, optional expectations, default tolerance, abort signal.
 * @returns the verify report (without the dataset label; the caller adds it).
 */
 function verifyTable(table, rules, options) {
@@ -1205,10 +1827,12 @@ function verifyTable(table, rules, options) {
 		}
 		results.push(result);
 	}
+	const expectations = verifyExpectations(table, options.expectations ?? [], options.defaultTolerance ?? 1e-9, options.signal);
 	return {
-		passed: results.every((result) => result.passed),
+		passed: results.every((result) => result.passed) && expectations.every((expectation) => expectation.passed),
 		rowCount: table.rows.length,
 		rules: results,
+		expectations,
 		generatedAt: options.now()
 	};
 }
@@ -1224,6 +1848,10 @@ function renderVerifyText(report) {
 		}
 		if (rule.failedCount > rule.evidence.length) lines.push(`    … and ${rule.failedCount - rule.evidence.length} more failing row(s)`);
 	}
+	for (const expectation of report.expectations) {
+		const target = expectation.column !== void 0 ? `${expectation.metric}(${expectation.column})` : expectation.metric;
+		lines.push(`- [${expectation.passed ? "pass" : "FAIL"}] expectation ${target}: actual ${expectation.actual} vs expected ${expectation.expected} (tolerance ${expectation.tolerance})`);
+	}
 	return lines.join("\n");
 }
 /**
@@ -1409,6 +2037,131 @@ function appendDataQualityEvent(session, type, data) {
 	if (Function.prototype.toString.call(append).includes("ignorable")) append.call(session, type, data, { ignorable: true });
 }
 //#endregion
+//#region src/presets.ts
+/** The built-in industry preset registry. */
+const INDUSTRY_PRESETS = {
+	retail: {
+		id: "retail",
+		label: "Retail",
+		columns: {
+			order_id: "string",
+			sku: "string",
+			quantity: "number",
+			unit_price: "number",
+			revenue: "number",
+			order_date: "date",
+			customer_id: "string"
+		}
+	},
+	saas: {
+		id: "saas",
+		label: "SaaS",
+		columns: {
+			account_id: "string",
+			plan: "string",
+			seats: "number",
+			mrr: "number",
+			signup_date: "date",
+			churned: "boolean"
+		}
+	},
+	fund: {
+		id: "fund",
+		label: "Fund",
+		columns: {
+			fund_code: "string",
+			fund_name: "string",
+			nav: "number",
+			nav_date: "date",
+			holding_value: "number",
+			currency: "string"
+		}
+	},
+	"real-estate": {
+		id: "real-estate",
+		label: "Real estate",
+		columns: {
+			property_id: "string",
+			listing_price: "number",
+			area_sqm: "number",
+			bedrooms: "number",
+			list_date: "date",
+			city: "string"
+		}
+	},
+	"e-commerce": {
+		id: "e-commerce",
+		label: "E-commerce",
+		columns: {
+			order_id: "string",
+			product_id: "string",
+			quantity: "number",
+			price: "number",
+			order_date: "date",
+			status: "string"
+		}
+	},
+	healthcare: {
+		id: "healthcare",
+		label: "Healthcare",
+		columns: {
+			patient_id: "string",
+			admission_date: "date",
+			discharge_date: "date",
+			age: "number",
+			diagnosis: "string",
+			cost: "number"
+		}
+	},
+	logistics: {
+		id: "logistics",
+		label: "Logistics",
+		columns: {
+			shipment_id: "string",
+			origin: "string",
+			destination: "string",
+			weight_kg: "number",
+			shipped_date: "date",
+			delivered: "boolean"
+		}
+	},
+	manufacturing: {
+		id: "manufacturing",
+		label: "Manufacturing",
+		columns: {
+			part_id: "string",
+			quantity: "number",
+			unit_cost: "number",
+			produced_date: "date",
+			defect: "boolean"
+		}
+	},
+	energy: {
+		id: "energy",
+		label: "Energy",
+		columns: {
+			meter_id: "string",
+			reading: "number",
+			unit: "string",
+			reading_date: "date",
+			consumption: "number"
+		}
+	}
+};
+/** The preset ids, for diagnostics and documentation. */
+const INDUSTRY_PRESET_IDS = Object.keys(INDUSTRY_PRESETS);
+/**
+* Resolve an industry preset id to its registry entry, failing loud on an
+* unknown id.
+* @param id - the requested preset id.
+* @returns the preset.
+*/
+function resolveIndustryPreset(id) {
+	const preset = INDUSTRY_PRESETS[id];
+	if (preset === void 0) throw new Error(`unknown industryPreset ${JSON.stringify(id)}; choose one of: ${INDUSTRY_PRESET_IDS.join(", ")}`);
+	return preset;
+}
+//#endregion
 //#region src/present.ts
 /** Maximum characters one cell contributes to a tool-facing row payload. */
 const MAX_CELL_TEXT = 120;
@@ -1514,11 +2267,16 @@ var LocalDataQualityService = class extends DataQualityService {
 	/** @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), {
+		const table = await loadTable(resolveWorkspacePath(request.workspace, request.dataset, this.config), this.config, request.signal);
+		const declaredSchema = request.industryPreset === void 0 ? void 0 : resolveIndustryPreset(request.industryPreset).columns;
+		const report = profileTable(table, {
 			dataset: request.dataset,
 			sample: request.sample,
 			generatedAt: this.deps.now(),
-			signal: request.signal
+			signal: request.signal,
+			duplicateSampleLimit: this.config.evidenceRowLimit,
+			declaredSchema,
+			scorecardWeights: this.config.scorecardWeights
 		});
 		const reportKey = await this.persist("profile", request.dataset, report);
 		this.emitEvent(request.session, "profile", request.dataset, reportKey, {
@@ -1533,10 +2291,12 @@ var LocalDataQualityService = class extends DataQualityService {
 	/** @inheritdoc DataQualityService.cleanDataset */
 	async cleanDataset(request) {
 		throwIfAborted(request.signal);
+		const dryRun = request.dryRun === true;
 		const absolute = resolveWorkspacePath(request.workspace, request.dataset, this.config);
-		const result = applyCleanRules(await loadTable(absolute, this.config, request.signal), request.rules, { signal: request.signal });
+		const table = await loadTable(absolute, this.config, request.signal);
+		const result = applyCleanRules(table, request.rules, { signal: request.signal });
 		let writtenPath;
-		if (request.outputPath !== void 0) {
+		if (!dryRun && 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();
@@ -1547,19 +2307,51 @@ var LocalDataQualityService = class extends DataQualityService {
 			writtenPath = request.outputPath;
 		}
 		const generatedAt = this.deps.now();
+		const contract = computeCleanContract(result, request.rules, { signal: request.signal });
+		const diff = computeCleanProfileDiff(table, {
+			columns: result.columns,
+			rows: result.rows,
+			...table.encoding !== void 0 ? { encoding: table.encoding } : {}
+		}, {
+			dataset: request.dataset,
+			generatedAt,
+			scorecardWeights: this.config.scorecardWeights,
+			signal: request.signal
+		});
 		const preview = {
 			columns: result.columns,
 			rows: result.rows.slice(0, this.config.evidenceRowLimit).map((row) => truncateRow(row))
 		};
+		if (dryRun) {
+			this.emitEvent(request.session, "clean", request.dataset, void 0, {
+				rows: result.outputRows,
+				columns: result.columns.length,
+				rules: result.logs.length
+			});
+			return {
+				dataset: request.dataset,
+				inputRows: result.inputRows,
+				outputRows: result.outputRows,
+				dryRun: true,
+				logs: result.logs,
+				contract,
+				preview,
+				diffPreview: diff,
+				generatedAt
+			};
+		}
 		const reportKey = await this.persist("clean", request.dataset, {
 			dataset: request.dataset,
 			inputRows: result.inputRows,
 			outputRows: result.outputRows,
+			dryRun: false,
 			logs: result.logs,
+			contract,
 			preview,
 			...writtenPath !== void 0 ? { outputPath: writtenPath } : {},
 			generatedAt
 		});
+		await this.persist("clean-diff", request.dataset, diff);
 		this.emitEvent(request.session, "clean", request.dataset, reportKey, {
 			rows: result.outputRows,
 			columns: result.columns.length,
@@ -1569,32 +2361,57 @@ var LocalDataQualityService = class extends DataQualityService {
 			dataset: request.dataset,
 			inputRows: result.inputRows,
 			outputRows: result.outputRows,
+			dryRun: false,
 			logs: result.logs,
+			contract,
 			preview,
 			...writtenPath !== void 0 ? { outputPath: writtenPath } : {},
 			...reportKey !== void 0 ? { reportKey } : {},
 			generatedAt
 		};
 	}
+	/** @inheritdoc DataQualityService.getReport */
+	async getReport(key) {
+		if (!isValidReportKey(key)) throw new Error(`invalid reportKey ${JSON.stringify(key)}: expected the deterministic <timestamp>-<kind>-<fingerprint> format`);
+		const store = this.deps.store;
+		if (store === void 0) throw new Error("report storage is disabled (storeReports is false); no persisted reports to read");
+		const record = store.get(key);
+		if (record === void 0) throw new Error(`no persisted report found for reportKey ${JSON.stringify(key)}`);
+		return {
+			key,
+			...record
+		};
+	}
+	/** @inheritdoc DataQualityService.listReports */
+	async listReports(kind) {
+		const store = this.deps.store;
+		if (store === void 0) throw new Error("report storage is disabled (storeReports is false); no persisted reports to read");
+		return store.list(kind);
+	}
 	/** @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
+			signal: request.signal,
+			expectations: request.expectations,
+			defaultTolerance: this.config.defaultTolerance
 		});
 		const report = {
 			dataset: request.dataset,
 			...outcome
 		};
 		const failedRules = report.rules.filter((rule) => !rule.passed).length;
+		const failedExpectations = report.expectations.filter((expectation) => !expectation.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
+			passed: report.passed,
+			expectations: report.expectations.length,
+			failedExpectations
 		});
 		return {
 			...report,
@@ -1622,48 +2439,22 @@ var LocalDataQualityService = class extends DataQualityService {
 	}
 };
 //#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
-*/
+//#region src/tools/profile-report-schema.ts
 /**
-* 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
+* Shared JSON-Schema spec for the profile report's canonical value, reused by
+* `data_profile` (its output) and `data_clean` (the `diffPreview` before/after
+* snapshots). One source of truth so the two tools never drift.
+* @module dsh-data-quality/tools-profile-report-schema
 */
+const SCORECARD_DIMENSION_NAMES = [
+	"completeness",
+	"uniqueness",
+	"validity",
+	"consistency",
+	"timeliness",
+	"accuracy"
+];
+/** One column card's schema. */
 const COLUMN_PROFILE_SCHEMA = {
 	type: "object",
 	properties: {
@@ -1698,6 +2489,14 @@ const COLUMN_PROFILE_SCHEMA = {
 		numeric: {
 			type: "object",
 			properties: {
+				count: {
+					type: "number",
+					required: true
+				},
+				distinct: {
+					type: "number",
+					required: true
+				},
 				min: {
 					type: "number",
 					required: true
@@ -1754,6 +2553,167 @@ const COLUMN_PROFILE_SCHEMA = {
 	},
 	additionalProperties: false
 };
+/** The full profile report's schema. */
+const PROFILE_REPORT_SCHEMA = {
+	type: "object",
+	properties: {
+		schemaVersion: {
+			type: "number",
+			required: true
+		},
+		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
+		},
+		duplicateRate: {
+			type: "number",
+			required: true
+		},
+		duplicateSampleRowIndexes: {
+			type: "array",
+			items: { type: "number" },
+			required: true
+		},
+		scorecard: {
+			type: "object",
+			properties: {
+				overall: {
+					oneOf: [{ type: "number" }, { type: "null" }],
+					required: true
+				},
+				weightedOverall: {
+					oneOf: [{ type: "number" }, { type: "null" }],
+					required: true
+				},
+				dimensions: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								enum: [...SCORECARD_DIMENSION_NAMES],
+								required: true
+							},
+							score: {
+								oneOf: [{ type: "number" }, { type: "null" }],
+								required: true
+							},
+							note: {
+								type: "string",
+								required: true
+							}
+						},
+						additionalProperties: false
+					},
+					required: true
+				}
+			},
+			additionalProperties: false,
+			required: true
+		},
+		encoding: {
+			type: "object",
+			properties: {
+				bom: {
+					oneOf: [{ type: "string" }, { type: "null" }],
+					required: true
+				},
+				validUtf8: {
+					type: "boolean",
+					required: true
+				}
+			},
+			additionalProperties: false
+		},
+		generatedAt: {
+			type: "number",
+			required: true
+		},
+		reportKey: { type: "string" },
+		columns: {
+			type: "array",
+			items: COLUMN_PROFILE_SCHEMA,
+			required: true
+		}
+	},
+	additionalProperties: false
+};
+//#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 = [];
+	const mode = report.dryRun ? "Dry-run plan for" : "Cleaned";
+	lines.push(`${mode} ${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}`);
+	const contract = report.contract;
+	const keyLabel = contract.dedupeColumns === null ? "full rows" : `[${contract.dedupeColumns.join(", ")}]`;
+	lines.push(`Contract: ${contract.inputRows} -> ${contract.outputRows} rows (${contract.removedRows} removed); uniqueness ${contract.uniqueKeys ? "OK" : "VIOLATED"} over ${keyLabel}${contract.remainingDuplicateRows > 0 ? ` (${contract.remainingDuplicateRows} duplicate row(s) remain)` : ""}`);
+	for (const entry of contract.remainingMissing) lines.push(`- non-null regression: ${entry.column} still has ${entry.count} missing cell(s)`);
+	for (const entry of contract.typeConformance) lines.push(`- type regression: ${entry.column} (${entry.to}) has ${entry.invalidCount} non-conforming cell(s)`);
+	for (const entry of contract.columnDecisions) {
+		const decisions = entry.decisions.map((decision) => `${decision.strategy} (${decision.affectedRows} row(s))`).join(", ");
+		lines.push(`- column ${entry.column}: ${decisions}`);
+	}
+	if (report.diffPreview !== void 0) lines.push(`Diff preview: ${report.diffPreview.before.rowCount} -> ${report.diffPreview.after.rowCount} rows; duplicates ${report.diffPreview.before.duplicateRows} -> ${report.diffPreview.after.duplicateRows}`);
+	if (report.dryRun) lines.push("Dry run: no output file written and no report persisted; plan/preview above.");
+	else 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
+*/
 /**
 * Build the `data_profile` tool definition against a mounted service.
 * @param service - the mounted ctx.dataQuality implementation.
@@ -1764,8 +2724,8 @@ function defineProfileTool(service) {
 		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)."
+			"Returns row/column counts, inferred column types, missing rates, unique counts, numeric distributions (count/distinct/min/max/mean/median/p25/p75), IQR outlier counts, mixed-type suspicion notes, sha256 duplicate-row detection (rate + sample indexes), file encoding (BOM/UTF-8 validity), and a weighted DAMA six-dimension scorecard.",
+			"Pass industryPreset (retail/saas/fund/real-estate/e-commerce/healthcare/logistics/manufacturing/energy) to compare the dataset against that industry's expected columns, making the scorecard accuracy dimension determinable. 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: {
@@ -1776,49 +2736,25 @@ function defineProfileTool(service) {
 			sample: {
 				type: "number",
 				description: "Optional systematic sample size (every ceil(N/sample)-th row) for the column cards; row counts stay exact."
+			},
+			industryPreset: {
+				type: "string",
+				enum: [
+					"retail",
+					"saas",
+					"fund",
+					"real-estate",
+					"e-commerce",
+					"healthcare",
+					"logistics",
+					"manufacturing",
+					"energy"
+				],
+				description: "Optional industry preset id; its expected columns feed the scorecard accuracy dimension."
 			}
 		},
 		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
-			},
+			schema: PROFILE_REPORT_SCHEMA,
 			render: (_args, value) => [{
 				type: "text",
 				text: renderProfileText(value)
@@ -1828,6 +2764,7 @@ function defineProfileTool(service) {
 			return service.profileDataset({
 				dataset: args.path,
 				sample: args.sample,
+				...args.industryPreset !== void 0 ? { industryPreset: args.industryPreset } : {},
 				workspace: workspaceOf(exec),
 				session: exec.agent?.session,
 				signal: exec.signal
@@ -1995,7 +2932,7 @@ function defineCleanTool(service) {
 		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)."
+			"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, the pre-delivery contract summary (with per-column decision trace), and a bounded preview. Pass dryRun: true to skip the write and get the cleaning plan plus the expected contract/diff preview instead. The full report persists to the data_quality storage domain (reportKey)."
 		].join("\n"),
 		parameters: {
 			path: {
@@ -2010,6 +2947,10 @@ function defineCleanTool(service) {
 			outputPath: {
 				type: "string",
 				description: "Optional workspace-relative output path for the cleaned dataset (must differ from path)."
+			},
+			dryRun: {
+				type: "boolean",
+				description: "When true, do not write any output file; return the cleaning plan and expected contract/diff preview instead (default false)."
 			}
 		},
 		output: {
@@ -2028,12 +2969,38 @@ function defineCleanTool(service) {
 						type: "number",
 						required: true
 					},
+					dryRun: {
+						type: "boolean",
+						required: true
+					},
 					generatedAt: {
 						type: "number",
 						required: true
 					},
 					outputPath: { type: "string" },
 					reportKey: { type: "string" },
+					diffPreview: {
+						type: "object",
+						properties: {
+							dataset: {
+								type: "string",
+								required: true
+							},
+							before: {
+								...PROFILE_REPORT_SCHEMA,
+								required: true
+							},
+							after: {
+								...PROFILE_REPORT_SCHEMA,
+								required: true
+							},
+							generatedAt: {
+								type: "number",
+								required: true
+							}
+						},
+						additionalProperties: false
+					},
 					logs: {
 						type: "array",
 						items: {
@@ -2068,6 +3035,117 @@ function defineCleanTool(service) {
 						},
 						required: true
 					},
+					contract: {
+						type: "object",
+						properties: {
+							inputRows: {
+								type: "number",
+								required: true
+							},
+							outputRows: {
+								type: "number",
+								required: true
+							},
+							removedRows: {
+								type: "number",
+								required: true
+							},
+							dedupeColumns: {
+								oneOf: [{
+									type: "array",
+									items: { type: "string" }
+								}, { type: "null" }],
+								required: true
+							},
+							uniqueKeys: {
+								type: "boolean",
+								required: true
+							},
+							remainingDuplicateRows: {
+								type: "number",
+								required: true
+							},
+							remainingMissing: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										column: {
+											type: "string",
+											required: true
+										},
+										count: {
+											type: "number",
+											required: true
+										}
+									},
+									additionalProperties: false
+								},
+								required: true
+							},
+							typeConformance: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										column: {
+											type: "string",
+											required: true
+										},
+										to: {
+											type: "string",
+											enum: [
+												"number",
+												"date",
+												"boolean"
+											],
+											required: true
+										},
+										invalidCount: {
+											type: "number",
+											required: true
+										}
+									},
+									additionalProperties: false
+								},
+								required: true
+							},
+							columnDecisions: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										column: {
+											type: "string",
+											required: true
+										},
+										decisions: {
+											type: "array",
+											items: {
+												type: "object",
+												properties: {
+													strategy: {
+														type: "string",
+														required: true
+													},
+													affectedRows: {
+														type: "number",
+														required: true
+													}
+												},
+												additionalProperties: false
+											},
+											required: true
+										}
+									},
+									additionalProperties: false
+								},
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					},
 					preview: {
 						type: "object",
 						properties: {
@@ -2098,6 +3176,7 @@ function defineCleanTool(service) {
 				dataset: args.path,
 				rules: args.rules,
 				...args.outputPath !== void 0 ? { outputPath: args.outputPath } : {},
+				...args.dryRun !== void 0 ? { dryRun: args.dryRun } : {},
 				workspace: workspaceOf(exec),
 				session: exec.agent?.session,
 				signal: exec.signal
@@ -2113,6 +3192,74 @@ function defineCleanTool(service) {
 * (`passed: false` with evidence), never a tool error.
 * @module dsh-data-quality/tools/verify
 */
+const EXPECTATION_METRICS = [
+	"rowCount",
+	"columnSum",
+	"columnMean",
+	"uniqueCount",
+	"nullCount"
+];
+const EXPECTATION_SCHEMA = {
+	type: "array",
+	items: {
+		type: "object",
+		properties: {
+			metric: {
+				type: "string",
+				enum: [...EXPECTATION_METRICS],
+				required: true,
+				description: "Metric to reconcile: rowCount/columnSum/columnMean/uniqueCount/nullCount."
+			},
+			column: {
+				type: "string",
+				description: "Required for every metric except rowCount."
+			},
+			expected: {
+				type: "number",
+				required: true,
+				description: "The expected value to reconcile against."
+			},
+			tolerance: {
+				type: "number",
+				description: "Optional relative tolerance in [0, 1]; defaults to defaultTolerance."
+			}
+		},
+		additionalProperties: false,
+		description: "Reconcile a deterministic computed metric against an expected value with relative tolerance."
+	},
+	description: "Optional metric expectations; each yields passed true or passed false with actual/expected/tolerance detail."
+};
+const EXPECTATION_RESULT_SCHEMA = {
+	type: "array",
+	items: {
+		type: "object",
+		properties: {
+			metric: {
+				type: "string",
+				enum: [...EXPECTATION_METRICS],
+				required: true
+			},
+			column: { type: "string" },
+			expected: {
+				type: "number",
+				required: true
+			},
+			actual: {
+				type: "number",
+				required: true
+			},
+			tolerance: {
+				type: "number",
+				required: true
+			},
+			passed: {
+				type: "boolean",
+				required: true
+			}
+		},
+		additionalProperties: false
+	}
+};
 const VERIFY_RULE_SCHEMA = {
 	type: "array",
 	items: { oneOf: [
@@ -2290,7 +3437,8 @@ function defineVerifyTool(service) {
 		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)."
+			"Optional expectations reconcile deterministic metrics (rowCount/columnSum/columnMean/uniqueCount/nullCount) against expected values with relative tolerance; a mismatch is a normal passed: false with actual/expected/tolerance detail, never a tool error.",
+			"Returns per-rule pass/fail with capped failing-row evidence plus the expectation outcomes. 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: {
@@ -2301,6 +3449,10 @@ function defineVerifyTool(service) {
 			rules: {
 				...VERIFY_RULE_SCHEMA,
 				required: true
+			},
+			expectations: {
+				...EXPECTATION_SCHEMA,
+				description: "Optional metric expectations to reconcile (rowCount/columnSum/columnMean/uniqueCount/nullCount)."
 			}
 		},
 		output: {
@@ -2380,6 +3532,10 @@ function defineVerifyTool(service) {
 							additionalProperties: false
 						},
 						required: true
+					},
+					expectations: {
+						...EXPECTATION_RESULT_SCHEMA,
+						required: true
 					}
 				},
 				additionalProperties: false
@@ -2393,6 +3549,7 @@ function defineVerifyTool(service) {
 			return service.verifyDataset({
 				dataset: args.path,
 				rules: args.rules,
+				...args.expectations !== void 0 ? { expectations: args.expectations } : {},
 				workspace: workspaceOf(exec),
 				session: exec.agent?.session,
 				signal: exec.signal
@@ -2401,18 +3558,320 @@ function defineVerifyTool(service) {
 	});
 }
 //#endregion
-//#region src/version.ts
+//#region src/report-html.ts
+/** Escape text for safe embedding in an HTML document. */
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/** Render a 0..1 rate as a percentage string, or `—` when undetermined. */
+function pct(score) {
+	return score === null ? "—" : `${(score * 100).toFixed(1)}%`;
+}
+/** The shared document shell: inline CSS + inline JS, no external requests. */
+function shell(title, body, script) {
+	return [
+		"<!doctype html>",
+		"<html lang=\"en\">",
+		"<head>",
+		"<meta charset=\"utf-8\">",
+		`<title>${escapeHtml(title)}</title>`,
+		"<style>",
+		"  :root { --ink: #1a1f2e; --muted: #6b7280; --line: #e5e7eb; --accent: #0f766e; --fail: #b91c1c; --warn: #b45309; --pass: #15803d; }",
+		"  * { box-sizing: border-box; }",
+		"  body { margin: 0; padding: 24px; font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif; color: var(--ink); background: #f8fafc; }",
+		"  header { margin-bottom: 20px; }",
+		"  h1 { font-size: 20px; margin: 0 0 4px; }",
+		"  .meta { color: var(--muted); font-size: 12px; }",
+		"  section { background: #fff; border: 1px solid var(--line); border-radius: 8px; padding: 16px 20px; margin-bottom: 16px; }",
+		"  h2 { font-size: 15px; margin: 0 0 12px; }",
+		"  table { border-collapse: collapse; width: 100%; font-size: 13px; }",
+		"  th, td { text-align: left; padding: 6px 10px; border-top: 1px solid var(--line); vertical-align: top; }",
+		"  th { color: var(--muted); font-weight: 600; }",
+		"  .score-cell { font-variant-numeric: tabular-nums; }",
+		"  .dim-fail { color: var(--fail); font-weight: 600; }",
+		"  .dim-warn { color: var(--warn); }",
+		"  .dim-pass { color: var(--pass); }",
+		"  .dim-undetermined { color: var(--muted); }",
+		"  button { cursor: pointer; font: inherit; }",
+		"</style>",
+		"</head>",
+		"<body>",
+		body,
+		"<script>",
+		script,
+		"<\/script>",
+		"</body>",
+		"</html>",
+		""
+	].join("\n");
+}
+/** The DAMA six-dimension scorecard section. */
+function scorecardSection(report) {
+	const rows = report.scorecard.dimensions.map((dimension) => {
+		const cls = dimension.score === null ? "dim-undetermined" : dimension.score >= .9 ? "dim-pass" : dimension.score >= .7 ? "dim-warn" : "dim-fail";
+		return `<tr><td>${escapeHtml(dimension.name)}</td><td class="score-cell ${cls}">${pct(dimension.score)}</td><td>${escapeHtml(dimension.note)}</td></tr>`;
+	}).join("\n");
+	const overall = report.scorecard.overall;
+	const weighted = report.scorecard.weightedOverall;
+	return [
+		"<section>",
+		"<h2>DAMA six-dimension quality scorecard</h2>",
+		"<table>",
+		"<thead><tr><th>Dimension</th><th>Score</th><th>Note</th></tr></thead>",
+		"<tbody>",
+		rows,
+		"</tbody>",
+		"</table>",
+		`<p class="meta" id="summary-text">overall ${pct(overall)} · weighted ${pct(weighted)}</p>`,
+		"</section>"
+	].join("\n");
+}
+/** The per-column profile summary table. */
+function columnsSection(report) {
+	return [
+		"<section>",
+		"<h2>Column profile</h2>",
+		"<table>",
+		"<thead><tr><th>Column</th><th>Type</th><th>Missing</th><th>Missing rate</th><th>Unique</th><th>Numeric distribution</th><th>Top values</th><th>Notes</th></tr></thead>",
+		"<tbody>",
+		report.columns.map((column) => {
+			const numeric = column.numeric;
+			const numericCell = numeric === void 0 ? "—" : `min ${numeric.min} · p25 ${numeric.p25} · median ${numeric.median} · p75 ${numeric.p75} · max ${numeric.max} · mean ${numeric.mean}${numeric.outliers > 0 ? ` · ${numeric.outliers} IQR outliers` : ""}`;
+			const top = column.topValues === void 0 ? "—" : column.topValues.map((entry) => `${escapeHtml(entry.value)} ×${entry.count}`).join(", ");
+			const notes = column.notes.length === 0 ? "" : `<p class="meta">${column.notes.map(escapeHtml).join("; ")}</p>`;
+			return [
+				"<tr>",
+				`<td>${escapeHtml(column.name)}</td>`,
+				`<td>${escapeHtml(column.inferredType)}</td>`,
+				`<td class="score-cell">${column.missing}</td>`,
+				`<td class="score-cell">${(column.missingRate * 100).toFixed(1)}%</td>`,
+				`<td class="score-cell">${column.unique}</td>`,
+				`<td>${numericCell}</td>`,
+				`<td>${top}</td>`,
+				`<td>${notes}</td>`,
+				"</tr>"
+			].join("");
+		}).join("\n"),
+		"</tbody>",
+		"</table>",
+		"</section>"
+	].join("\n");
+}
 /**
-* Plugin version, kept in one place so `scripts/release.mjs` can stamp it and
-* reports can name their generator.
-* @module dsh-data-quality/version
+* Render a profile report as a self-contained offline HTML document.
+* @param report - the profile report (already persisted/returned by data_profile).
+* @returns the complete single-file HTML.
 */
-/** The package version reported in persisted reports. */
-const VERSION = "0.1.3";
+function renderProfileHtml(report) {
+	const body = [
+		"<header>",
+		`<h1>Data profile: ${escapeHtml(report.dataset)}</h1>`,
+		`<p class="meta">${report.rowCount} rows × ${report.columnCount} columns · generated ${new Date(report.generatedAt).toISOString()} · schema v1 · report ${report.reportKey ?? "(unpersisted)"}</p>`,
+		"<button id=\"copy-summary\" type=\"button\">Copy summary</button>",
+		"</header>",
+		scorecardSection(report),
+		columnsSection(report)
+	].join("\n");
+	const script = [
+		"const button = document.getElementById('copy-summary');",
+		"if (button) {",
+		"  button.addEventListener(\"click\", () => {",
+		"    const text = document.getElementById(\"summary-text\");",
+		"    if (text && navigator.clipboard) navigator.clipboard.writeText(text.textContent || \"\");",
+		"  });",
+		"}"
+	].join("\n");
+	return shell(`Data profile: ${report.dataset}`, body, script);
+}
+/** The per-rule cleaning summary table (for clean/clean-diff reports). */
+function cleaningSection(report) {
+	const rows = report.logs.map((log) => {
+		return `<tr><td>${escapeHtml(log.rule)}</td><td class="score-cell">${log.affectedRows}</td><td>${escapeHtml(log.detail)}</td></tr>`;
+	}).join("\n");
+	const removed = report.inputRows - report.outputRows;
+	return [
+		"<section>",
+		"<h2>Cleaning summary</h2>",
+		`<p class="meta" id="summary-text">input ${report.inputRows} rows · output ${report.outputRows} rows · removed ${removed} rows</p>`,
+		"<table>",
+		"<thead><tr><th>Rule</th><th>Affected rows</th><th>Detail</th></tr></thead>",
+		"<tbody>",
+		rows,
+		"</tbody>",
+		"</table>",
+		"</section>"
+	].join("\n");
+}
+/**
+* Render a clean report as a self-contained offline HTML document (the
+* per-rule cleaning summary table).
+* @param report - the clean report (logs + input/output row counts).
+* @param dataset - the dataset label for the document title.
+* @returns the complete single-file HTML.
+*/
+function renderCleanHtml(report, dataset) {
+	const body = [
+		"<header>",
+		`<h1>Cleaning report: ${escapeHtml(dataset)}</h1>`,
+		`<p class="meta">schema v1</p>`,
+		"</header>",
+		cleaningSection(report)
+	].join("\n");
+	return shell(`Cleaning report: ${dataset}`, body, "// no interactive behavior needed; everything renders without external requests\n");
+}
+//#endregion
+//#region src/tools/report.ts
+/**
+* The `data_report` model tool: read persisted profile/clean-diff reports
+* back from the `data_quality` storage domain, by exact `reportKey` or by
+* `kind`. Deterministic read-only consumption — no model arithmetic.
+* @module dsh-data-quality/tools/report
+*/
+/** The report kinds a caller may query. */
+const REPORT_KINDS = [
+	"profile",
+	"clean",
+	"clean-diff",
+	"verify",
+	"citations"
+];
+/** Render one stored report as a self-contained HTML document (profile/clean only). */
+function renderRecordHtml(record) {
+	if (record.kind === "profile") return renderProfileHtml(record.report);
+	if (record.kind === "clean" || record.kind === "clean-diff") return renderCleanHtml(record.report, record.dataset);
+	throw new Error(`data_report html format does not support kind "${record.kind}" (profile/clean only)`);
+}
+/** Project a stored report into the canonical value (the stored report is already lossless JSON). */
+function toView(record) {
+	return {
+		key: record.key,
+		kind: record.kind,
+		at: record.at,
+		dataset: record.dataset,
+		report: record.report
+	};
+}
+/** Human-readable report summary for the tool's Native render. */
+function renderReportText(value) {
+	const lines = [];
+	if (value.key !== void 0) lines.push(value.records.length === 0 ? `No report for ${value.key}` : `Report ${value.key}`);
+	else lines.push(`Reports of kind ${value.kind ?? ""} (${value.records.length})`);
+	for (const record of value.records) lines.push(`- ${record.key} [${record.kind}] ${record.dataset} @ ${new Date(record.at).toISOString()}`);
+	return lines.join("\n");
+}
+/**
+* Build the `data_report` tool definition against a mounted service.
+* @param service - the mounted ctx.dataQuality implementation.
+* @returns the tool definition to register.
+*/
+function defineReportTool(service) {
+	return defineTool({
+		name: "data_report",
+		description: [
+			"Read persisted data-quality reports back from the data_quality storage domain (deterministic, read-only).",
+			"Pass key (the exact reportKey a prior run returned) to fetch one report, or kind to list every persisted report of that kind, ordered chronologically. Exactly one of key/kind.",
+			"Returns the report envelope(s): kind, dataset, timestamp, and the full stored report (profile/clean/clean-diff/verify/citations). Missing keys and unknown kinds fail loudly."
+		].join("\n"),
+		parameters: {
+			key: {
+				type: "string",
+				description: "Exact storage reportKey (e.g. 20260819000000000-profile-1a2b3c4d); fetches that one report."
+			},
+			kind: {
+				type: "string",
+				enum: [...REPORT_KINDS],
+				description: "Report kind to list (profile/clean/clean-diff/verify/citations)."
+			},
+			format: {
+				type: "string",
+				enum: ["json", "html"],
+				description: "Output format. json (default) returns the report envelope(s); html renders one report as a self-contained offline HTML document (requires key; profile/clean only)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					kind: {
+						type: "string",
+						enum: [...REPORT_KINDS]
+					},
+					records: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								key: {
+									type: "string",
+									required: true
+								},
+								kind: {
+									type: "string",
+									enum: [...REPORT_KINDS],
+									required: true
+								},
+								at: {
+									type: "number",
+									required: true
+								},
+								dataset: {
+									type: "string",
+									required: true
+								},
+								report: {
+									type: "json",
+									required: true
+								}
+							},
+							additionalProperties: false
+						},
+						required: true
+					},
+					html: {
+						type: "string",
+						description: "Self-contained offline HTML (present only when format: html)."
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const view = value;
+				if (view.html !== void 0) return [{
+					type: "text",
+					text: view.html
+				}];
+				return [{
+					type: "text",
+					text: renderReportText(view)
+				}];
+			}
+		},
+		async execute(args, _exec) {
+			const hasKey = args.key !== void 0;
+			if (hasKey === (args.kind !== void 0)) throw new Error("data_report needs exactly one of key/kind");
+			const format = args.format ?? "json";
+			if (hasKey) {
+				const record = await service.getReport(args.key);
+				return {
+					key: args.key,
+					records: [toView(record)],
+					...format === "html" ? { html: renderRecordHtml(record) } : {}
+				};
+			}
+			if (format === "html") throw new Error("data_report html format requires key (exactly one report)");
+			const records = await service.listReports(args.kind);
+			return {
+				kind: args.kind,
+				records: records.map(toView)
+			};
+		}
+	});
+}
 //#endregion
 //#region src/index.ts
 const name = "data-quality";
-/** The three model tools and the durable report domain. */
+/** The four model tools and the durable report domain. */
 const inject = ["tools", "storageDomain"];
 /**
 * Mount the seam: resolve config (fail loud), open the report domain, publish
@@ -2439,7 +3898,11 @@ async function apply(ctx, config = {}) {
 				await reports.put(key, record);
 				return key;
 			},
-			get: (key) => reports.get(key)
+			get: (key) => reports.get(key),
+			list: (kind) => [...reports.entries()].filter(([, record]) => record.kind === kind).sort(([keyA], [keyB]) => keyA < keyB ? -1 : keyA > keyB ? 1 : 0).map(([key, record]) => ({
+				key,
+				...record
+			}))
 		};
 	}
 	const service = new LocalDataQualityService(ctx, resolved, {
@@ -2449,7 +3912,8 @@ async function apply(ctx, config = {}) {
 	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`);
+	ctx.tools.register(defineReportTool(service));
+	logger.info(`dsh-data-quality ${VERSION} mounted: ctx.dataQuality + data_profile/data_clean/data_verify/data_report`);
 	if (domain !== void 0) {
 		const handle = domain;
 		ctx.effect(() => async () => {
@@ -2458,4 +3922,4 @@ async function apply(ctx, config = {}) {
 	}
 }
 //#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 };
+export { Config, DATA_QUALITY_EVENT_TYPES, DataQualityService, DatasetError, INDUSTRY_PRESETS, INDUSTRY_PRESET_IDS, LocalDataQualityService, MAX_CELL_TEXT, REPORT_SCHEMA_VERSION, VERSION, VerifyExpectationError, appendDataQualityEvent, apply, applyCleanRules, checkCitations, computeCleanContract, computeCleanProfileDiff, computeScorecard, countDuplicateRows, dataQualityDomainSpec, dateFormatOf, detectDuplicateRows, detectEncoding, inject, isMissing, isValidReportKey, loadDocument, loadTable, name, numericProfile, parseBoolean, parseDate, parseDateCell, parseDelimited, parseJsonTable, parseLocator, parseNumeric, profileTable, readDatasetFile, renderCleanHtml, renderProfileHtml, renderProfileText, renderVerifyText, reportKeyOf, reportRecordSchema, resolveConfig, resolveIndustryPreset, resolveWorkspacePath, sampleRows, serializeDelimited, truncateCell, truncateRow, verifyExpectations, verifyTable };