dsh-data-quality 0.1.2 → 0.2.0

package/src/provider-local.ts

@@ -12,10 +12,12 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { ResolvedConfig } from './config.ts'
 import { loadDocument, loadTable, resolveWorkspacePath, throwIfAborted } from './dataset.ts'
 import { applyCleanRules, serializeDelimited } from './clean.ts'
+import { computeCleanContract, computeCleanProfileDiff } from './contract.ts'
 import { profileTable } from './profile.ts'
 import { checkCitations, verifyTable } from './verify.ts'
 import { appendDataQualityEvent } from './events.ts'
-import { reportKeyOf, type ReportRecord, type ReportStore } from './store.ts'
+import { isValidReportKey, reportKeyOf, type ReportRecord, type ReportStore, type StoredReport } from './store.ts'
+import { resolveIndustryPreset } from './presets.ts'
 import { truncateRow } from './present.ts'
 import {
   DataQualityService,
@@ -73,7 +75,7 @@ export class LocalDataQualityService extends DataQualityService {
   }
 
   /** Emit the adaptive session event when the call carries a session. */
-  emitEvent(session: Session | undefined, kind: 'profile' | 'clean' | 'verify', dataset: string, reportKey: string | undefined, summary: { rows: number; columns?: number; rules?: number; failedRules?: number; passed?: boolean }): void {
+  emitEvent(session: Session | undefined, kind: 'profile' | 'clean' | 'verify', dataset: string, reportKey: string | undefined, summary: { rows: number; columns?: number; rules?: number; failedRules?: number; passed?: boolean; expectations?: number; failedExpectations?: number }): void {
     if (session === undefined) return
     appendDataQualityEvent(session, `data-quality/${kind}`, {
       kind,
@@ -88,11 +90,15 @@ export class LocalDataQualityService extends DataQualityService {
     throwIfAborted(request.signal)
     const absolute = resolveWorkspacePath(request.workspace, request.dataset, this.config)
     const table = await loadTable(absolute, this.config, request.signal)
+    const declaredSchema = request.industryPreset === undefined ? undefined : resolveIndustryPreset(request.industryPreset).columns
     const report = profileTable(table, {
       dataset: request.dataset,
       sample: request.sample,
       generatedAt: this.deps.now(),
       signal: request.signal,
+      duplicateSampleLimit: this.config.evidenceRowLimit,
+      declaredSchema,
+      scorecardWeights: this.config.scorecardWeights,
     })
     const reportKey = await this.persist('profile', request.dataset, report as unknown as Record<string, unknown>)
     this.emitEvent(request.session, 'profile', request.dataset, reportKey, { rows: report.rowCount, columns: report.columnCount })
@@ -102,12 +108,13 @@ export class LocalDataQualityService extends DataQualityService {
   /** @inheritdoc DataQualityService.cleanDataset */
   override async cleanDataset(request: CleanRequest): Promise<CleanRunReport> {
     throwIfAborted(request.signal)
+    const dryRun = request.dryRun === true
     const absolute = resolveWorkspacePath(request.workspace, request.dataset, this.config)
     const table = await loadTable(absolute, this.config, request.signal)
     const result = applyCleanRules(table, request.rules, { signal: request.signal })
 
     let writtenPath: string | undefined
-    if (request.outputPath !== undefined) {
+    if (!dryRun && request.outputPath !== undefined) {
       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`)
@@ -125,29 +132,95 @@ export class LocalDataQualityService extends DataQualityService {
     }
 
     const generatedAt = this.deps.now()
+    // The contract summary is part of the model-visible canonical value, so it
+    // must also be part of the durable report (model-visible ⟺ logged).
+    const contract = computeCleanContract(result, request.rules, { signal: request.signal })
+    const outputTable = {
+      columns: result.columns,
+      rows: result.rows,
+      ...(table.encoding !== undefined ? { encoding: table.encoding } : {}),
+    }
+    // The before/after profile diff preview is the expected diff in a dry run
+    // and the durable audit artifact (separate `clean-diff` record) otherwise.
+    const diff = computeCleanProfileDiff(table, outputTable, {
+      dataset: request.dataset,
+      generatedAt,
+      scorecardWeights: this.config.scorecardWeights,
+      signal: request.signal,
+    })
+    // The preview is part of the model-visible canonical value, so it must
+    // also be part of the durable report: otherwise the clean result's preview
+    // could not be reconstructed from the session log (model-visible ⟺ logged).
+    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, undefined, { 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 !== undefined ? { outputPath: writtenPath } : {}),
       generatedAt,
     } as unknown as Record<string, unknown>)
+    await this.persist('clean-diff', request.dataset, diff as unknown as Record<string, unknown>)
     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,
+      dryRun: false,
       logs: result.logs,
-      preview: { columns: result.columns, rows: previewRows },
+      contract,
+      preview,
       ...(writtenPath !== undefined ? { outputPath: writtenPath } : {}),
       ...(reportKey !== undefined ? { reportKey } : {}),
       generatedAt,
     }
   }
 
+  /** @inheritdoc DataQualityService.getReport */
+  override async getReport(key: string): Promise<StoredReport> {
+    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 === undefined) {
+      throw new Error('report storage is disabled (storeReports is false); no persisted reports to read')
+    }
+    const record = store.get(key)
+    if (record === undefined) {
+      throw new Error(`no persisted report found for reportKey ${JSON.stringify(key)}`)
+    }
+    return { key, ...record }
+  }
+
+  /** @inheritdoc DataQualityService.listReports */
+  override async listReports(kind: ReportRecord['kind']): Promise<StoredReport[]> {
+    const store = this.deps.store
+    if (store === undefined) {
+      throw new Error('report storage is disabled (storeReports is false); no persisted reports to read')
+    }
+    return store.list(kind)
+  }
+
   /** @inheritdoc DataQualityService.verifyDataset */
   override async verifyDataset(request: VerifyRequest): Promise<VerifyReport> {
     throwIfAborted(request.signal)
@@ -157,15 +230,20 @@ export class LocalDataQualityService extends DataQualityService {
       evidenceRowLimit: this.config.evidenceRowLimit,
       now: this.deps.now,
       signal: request.signal,
+      expectations: request.expectations,
+      defaultTolerance: this.config.defaultTolerance,
     })
     const report: VerifyReport = { 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 as unknown as Record<string, unknown>)
     this.emitEvent(request.session, 'verify', request.dataset, reportKey, {
       rows: report.rowCount,
       rules: report.rules.length,
       failedRules,
       passed: report.passed,
+      expectations: report.expectations.length,
+      failedExpectations,
     })
     return { ...report, ...(reportKey !== undefined ? { reportKey } : {}) }
   }

package/src/scorecard.ts

@@ -0,0 +1,244 @@
+/**
+ * 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
+ */
+
+import { isMissing, parseBoolean, parseDateCell, parseNumeric, throwIfAborted, type Table } from './dataset.ts'
+import type { InferredType } from './profile.ts'
+
+/** The six scorecard dimension ids, in report order. */
+export type ScorecardDimensionName = 'completeness' | 'uniqueness' | 'validity' | 'consistency' | 'timeliness' | 'accuracy'
+
+/** One scorecard dimension: a 0..1 rate, or `null` when it cannot be determined. */
+export interface ScorecardDimension {
+  readonly name: ScorecardDimensionName
+  /** Rate in [0, 1] rounded to 6 significant digits; `null` = cannot be determined (never fabricated). */
+  readonly score: number | null
+  /** Human-readable definition and verdict. */
+  readonly note: string
+}
+
+/** The six-dimension quality scorecard (also the profile report's `scorecard` field). */
+export interface DataQualityScorecard {
+  readonly dimensions: ScorecardDimension[]
+  /** Unweighted mean of the determinable (non-null) dimension scores; `null` when none are determinable. */
+  readonly overall: number | null
+  /** Weighted mean over the determinable dimensions; `null` when none are determinable or all their weights are 0. */
+  readonly weightedOverall: number | null
+}
+
+/** Per-column aggregation for one full-table pass. */
+interface ColumnStats {
+  present: number
+  number: number
+  date: number
+  boolean: number
+  string: number
+  /** Format-label frequency for consistency. */
+  formats: Map<string, number>
+}
+
+/** Round to 6 significant digits (mirrors the profile report's rounding). */
+function round6(value: number): number {
+  return Number(value.toPrecision(6))
+}
+
+/** Increment a format-label counter. */
+function bump(formats: Map<string, number>, tag: string): void {
+  formats.set(tag, (formats.get(tag) ?? 0) + 1)
+}
+
+/** Inferred column type from the full-table class counts (mirrors `profileColumn`). */
+function inferType(stats: ColumnStats): InferredType {
+  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: number, denominator: number): string {
+  return `${numerator}/${denominator}`
+}
+
+/** Build one determinable dimension with its ratio note. */
+function dimension(name: ScorecardDimensionName, score: number, numerator: number, denominator: number): ScorecardDimension {
+  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.
+ */
+export function computeScorecard(
+  table: Table,
+  options: {
+    now: number
+    duplicateRows: number
+    declaredSchema?: Readonly<Record<string, InferredType>> | undefined
+    weights?: Readonly<Record<ScorecardDimensionName, number>> | undefined
+    signal?: AbortSignal | undefined
+  },
+): DataQualityScorecard {
+  throwIfAborted(options.signal)
+  const stats = new Map<string, ColumnStats>()
+  for (const column of table.columns) {
+    stats.set(column, { present: 0, number: 0, date: 0, boolean: 0, string: 0, formats: 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) as ColumnStats
+      if (isMissing(cell)) {
+        missingCells += 1
+        continue
+      }
+      columnStats.present += 1
+      const numeric = parseNumeric(cell)
+      if (numeric !== undefined) {
+        columnStats.number += 1
+        bump(columnStats.formats, 'number')
+        continue
+      }
+      const date = parseDateCell(cell)
+      if (date !== undefined) {
+        columnStats.date += 1
+        bump(columnStats.formats, date.format)
+        dateCells += 1
+        if (date.epoch > options.now) futureDateCells += 1
+        continue
+      }
+      if (parseBoolean(cell) !== undefined) {
+        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
+    // Validity = conformance to the column's dominant TYPE class; consistency
+    // below measures dominant FORMAT (so a date column with mixed YYYY-MM-DD /
+    // YYYY/MM/DD formats stays valid but inconsistent).
+    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 completeness: ScorecardDimension =
+    totalCells === 0
+      ? { name: 'completeness', score: null, note: 'undetermined: no cells' }
+      : dimension('completeness', round6(1 - missingCells / totalCells), presentCells, totalCells)
+
+  const uniqueness: ScorecardDimension =
+    table.rows.length === 0
+      ? { name: 'uniqueness', score: null, note: 'undetermined: no rows' }
+      : dimension('uniqueness', round6(1 - options.duplicateRows / table.rows.length), table.rows.length - options.duplicateRows, table.rows.length)
+
+  const validity: ScorecardDimension =
+    presentCells === 0
+      ? { name: 'validity', score: null, note: 'undetermined: no present cells' }
+      : dimension('validity', round6(1 - invalidCells / presentCells), presentCells - invalidCells, presentCells)
+
+  const consistency: ScorecardDimension =
+    presentCells === 0
+      ? { name: 'consistency', score: null, note: 'undetermined: no present cells' }
+      : dimension('consistency', round6(consistentCells / presentCells), consistentCells, presentCells)
+
+  const timeliness: ScorecardDimension =
+    dateCells === 0
+      ? { name: 'timeliness', score: null, note: 'undetermined: no date cells' }
+      : dimension('timeliness', round6(1 - futureDateCells / dateCells), dateCells - futureDateCells, dateCells)
+
+  const accuracy = computeAccuracy(stats, table, options.declaredSchema)
+
+  const dimensions = [completeness, uniqueness, validity, consistency, timeliness, accuracy]
+  const scores = dimensions.map((entry) => entry.score).filter((score): score is number => score !== null)
+  const overall = scores.length === 0 ? null : round6(scores.reduce((sum, score) => sum + score, 0) / scores.length)
+  const weightedOverall = computeWeightedOverall(dimensions, options.weights)
+  return { dimensions, overall, weightedOverall }
+}
+
+/** Weighted mean over determinable dimensions (weights default to 1; validated non-negative by config). */
+function computeWeightedOverall(
+  dimensions: readonly ScorecardDimension[],
+  weights: Readonly<Record<ScorecardDimensionName, number>> | undefined,
+): number | null {
+  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(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: ReadonlyMap<string, ColumnStats>,
+  table: Table,
+  declaredSchema: Readonly<Record<string, InferredType>> | undefined,
+): ScorecardDimension {
+  if (declaredSchema === undefined || 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: string[] = []
+  for (const column of table.columns) {
+    const declared = declaredSchema[column]
+    if (declared === undefined) continue
+    checked += 1
+    const inferred = inferType(stats.get(column) as ColumnStats)
+    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(matched / checked),
+    note: `${matched}/${checked} columns match their declared type` + (mismatches.length > 0 ? `; mismatches: ${mismatches.join(', ')}` : ''),
+  }
+}

package/src/service.ts

@@ -11,8 +11,10 @@
 import { Service, type Context } from '@deepseek-ai/cordis'
 import type { JsonValue, Session } from '@deepseek-ai/dsh-session'
 import type { CleanRule, CleanRuleLog } from './clean.ts'
+import type { CleanContractSummary, CleanProfileDiff } from './contract.ts'
 import type { ProfileReport } from './profile.ts'
-import type { VerifyReport, VerifyRule } from './verify.ts'
+import type { VerifyExpectation, VerifyReport, VerifyRule } from './verify.ts'
+import type { ReportRecord, StoredReport } from './store.ts'
 
 export interface CitationCheckRequest {
   /** Workspace-relative path of the source dataset snapshot (CSV/JSON). */
@@ -46,6 +48,8 @@ export interface ProfileRequest {
   readonly dataset: string
   /** Optional deterministic systematic sample size for column cards. */
   readonly sample?: number | undefined
+  /** Optional industry preset id; its expected columns feed the scorecard's declared schema. */
+  readonly industryPreset?: string | undefined
   /** Absolute workspace root the dataset resolves inside. */
   readonly workspace: string
   /** Calling session (receives the `data-quality/profile` event), when any. */
@@ -62,6 +66,8 @@ export interface CleanRequest {
   readonly rules: readonly CleanRule[]
   /** Workspace-relative output path; omitted = no disk write, preview only. */
   readonly outputPath?: string | undefined
+  /** Dry run: no file written, no report persisted; returns the plan + expected contract/diff preview. */
+  readonly dryRun?: boolean | undefined
   /** Absolute workspace root the dataset resolves inside. */
   readonly workspace: string
   /** Calling session (receives the `data-quality/clean` event), when any. */
@@ -76,6 +82,8 @@ export interface VerifyRequest {
   readonly dataset: string
   /** Non-empty declarative verification rule list. */
   readonly rules: readonly VerifyRule[]
+  /** Optional metric expectations to reconcile (rowCount/columnSum/columnMean/uniqueCount/nullCount). */
+  readonly expectations?: readonly VerifyExpectation[] | undefined
   /** Absolute workspace root the dataset resolves inside. */
   readonly workspace: string
   /** Calling session (receives the `data-quality/verify` event), when any. */
@@ -89,9 +97,15 @@ export interface CleanRunReport {
   readonly dataset: string
   readonly inputRows: number
   readonly outputRows: number
+  /** Whether this was a dry run (no file written, no report persisted). */
+  readonly dryRun: boolean
   readonly logs: CleanRuleLog[]
+  /** Pre-delivery contract validation summary (dedupe/uniqueness/non-null/type/decision regressions). */
+  readonly contract: CleanContractSummary
   /** First `evidenceRowLimit` cleaned rows for inspection (display-truncated). */
   readonly preview: { readonly columns: string[]; readonly rows: Array<Record<string, JsonValue>> }
+  /** Expected before/after profile diff preview; present only for dry runs. */
+  readonly diffPreview?: CleanProfileDiff
   /** Workspace-relative output path when the run wrote a file. */
   readonly outputPath?: string
   /** Storage-domain key of the persisted report, when persistence is on. */
@@ -157,6 +171,22 @@ export abstract class DataQualityService extends Service {
    * @returns the verify report.
    */
   abstract verifyDataset(request: VerifyRequest): Promise<VerifyReport>
+
+  /**
+   * Read one persisted report by its storage key. The key is validated
+   * against the deterministic report-key format (path-safe) and a missing
+   * record fails loud.
+   * @param key - the storage report key.
+   * @returns the stored report (with its key).
+   */
+  abstract getReport(key: string): Promise<StoredReport>
+
+  /**
+   * List every persisted report of one kind, ordered by key (chronological).
+   * @param kind - the report kind.
+   * @returns the stored reports (empty when none match).
+   */
+  abstract listReports(kind: ReportRecord['kind']): Promise<StoredReport[]>
 }
 
 declare module '@deepseek-ai/cordis' {
@@ -168,5 +198,7 @@ declare module '@deepseek-ai/cordis' {
 
 /** Re-exports so consumers pull the whole seam vocabulary from one module. */
 export type { CleanResult, CleanRule, CleanRuleLog } from './clean.ts'
+export type { CleanContractSummary, CleanProfileDiff } from './contract.ts'
 export type { ProfileReport } from './profile.ts'
-export type { VerifyReport, VerifyRule } from './verify.ts'
+export type { VerifyReport, VerifyRule, VerifyExpectation, VerifyExpectationResult, VerifyMetric } from './verify.ts'
+export type { ReportRecord, StoredReport } from './store.ts'

package/src/store.ts

@@ -12,7 +12,7 @@ import { pathFingerprint } from './dataset.ts'
 
 /** Zod schema of one persisted report record (durable-boundary validation). */
 export const reportRecordSchema = z.object({
-  kind: z.enum(['profile', 'clean', 'verify', 'citations']),
+  kind: z.enum(['profile', 'clean', 'verify', 'citations', 'clean-diff']),
   at: z.number().int().nonnegative(),
   dataset: z.string(),
   report: z.record(z.string(), z.unknown()),
@@ -20,7 +20,7 @@ export const reportRecordSchema = z.object({
 
 /** One persisted report record. */
 export interface ReportRecord {
-  readonly kind: 'profile' | 'clean' | 'verify' | 'citations'
+  readonly kind: 'profile' | 'clean' | 'verify' | 'citations' | 'clean-diff'
   /** Injected run timestamp (epoch ms). */
   readonly at: number
   /** Workspace-relative dataset path as the caller gave it. */
@@ -29,6 +29,12 @@ export interface ReportRecord {
   readonly report: Record<string, unknown>
 }
 
+/** A persisted report plus its storage key (the query surface's return value). */
+export interface StoredReport extends ReportRecord {
+  /** The storage key the record was written under. */
+  readonly key: string
+}
+
 /** The `dsh-data-quality` storage-domain declaration. */
 export const dataQualityDomainSpec = defineDomain({
   name: 'data_quality',
@@ -52,6 +58,26 @@ export interface ReportStore {
    * @returns the record, or `undefined` when absent.
    */
   get(key: string): ReportRecord | undefined
+  /**
+   * Snapshot of every record of one kind, ordered by key (chronological).
+   * @param kind - the report kind.
+   * @returns the stored reports (empty when none match).
+   */
+  list(kind: ReportRecord['kind']): StoredReport[]
+}
+
+/** 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.
+ */
+export function isValidReportKey(key: string): boolean {
+  return REPORT_KEY_PATTERN.test(key)
 }
 
 /** Pad to two digits for the key timestamp. */

package/src/tools/clean.ts

@@ -7,6 +7,7 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { CleanRule, CleanRunReport, DataQualityService } from '../service.ts'
+import { PROFILE_REPORT_SCHEMA } from './profile-report-schema.ts'
 import { renderCleanText, workspaceOf } from './shared.ts'
 
 const STRING_MAP_SCHEMA = { type: 'json' } as const
@@ -91,12 +92,13 @@ export function defineCleanTool(service: DataQualityService) {
     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: { 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).' },
+      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: {
       schema: {
@@ -105,9 +107,20 @@ export function defineCleanTool(service: DataQualityService) {
           dataset: { type: 'string', required: true },
           inputRows: { type: 'number', required: true },
           outputRows: { 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: {
@@ -122,6 +135,67 @@ export function defineCleanTool(service: DataQualityService) {
             },
             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: {
@@ -141,6 +215,7 @@ export function defineCleanTool(service: DataQualityService) {
         dataset: args.path,
         rules: args.rules as unknown as readonly CleanRule[],
         ...(args.outputPath !== undefined ? { outputPath: args.outputPath } : {}),
+        ...(args.dryRun !== undefined ? { dryRun: args.dryRun } : {}),
         workspace: workspaceOf(exec),
         session: exec.agent?.session,
         signal: exec.signal,