dsh-data-quality 0.1.0

package/src/profile.ts

@@ -0,0 +1,250 @@
+/**
+ * Deterministic dataset profiling: per-column type inference, missingness,
+ * cardinality, numeric distribution, IQR outlier counts, and duplicate-row
+ * detection. Pure functions over a parsed {@link Table} — no clock, no RNG,
+ * no I/O; `generatedAt` is injected by the caller.
+ * @module dsh-data-quality/profile
+ */
+
+import { isMissing, parseBoolean, parseDate, parseNumeric, sampleRows, throwIfAborted, type Row, type Table } from './dataset.ts'
+
+/** Inferred column type from parsed cell classes. */
+export type InferredType = 'number' | 'date' | 'boolean' | 'string' | 'empty' | 'mixed'
+
+/** Numeric distribution of one numeric column. */
+export interface NumericProfile {
+  readonly min: number
+  readonly max: number
+  readonly mean: number
+  readonly median: number
+  readonly p25: number
+  readonly p75: number
+  /** Values outside `[p25 - 1.5*IQR, p75 + 1.5*IQR]`. */
+  readonly outliers: number
+}
+
+/** One column's profile card. */
+export interface ColumnProfile {
+  readonly name: string
+  readonly inferredType: InferredType
+  /** Missing cells over the profiled rows. */
+  readonly missing: number
+  /** `missing / profiledRows` (0 when the column has no rows). */
+  readonly missingRate: number
+  /** Distinct non-missing values over the profiled rows. */
+  readonly unique: number
+  /** Numeric distribution; present only for `number` columns with values. */
+  readonly numeric?: NumericProfile
+  /** Up to 5 most frequent values for low-cardinality (<= 10 distinct) string/boolean columns. */
+  topValues?: Array<{ readonly value: string; readonly count: number }>
+  /** Suspicion notes, e.g. mixed-type composition. */
+  notes: string[]
+}
+
+/** The full profile report (also the persisted and tool-returned value). */
+export interface ProfileReport {
+  readonly dataset: string
+  readonly rowCount: number
+  /** Whether column cards describe a systematic sample rather than every row. */
+  readonly sampled: boolean
+  /** Rows the column cards were computed over. */
+  readonly profiledRows: number
+  readonly columnCount: number
+  /** Rows whose full content duplicates an earlier row (over ALL rows). */
+  readonly duplicateRows: number
+  columns: ColumnProfile[]
+  /** Storage-domain key of the persisted report, when persistence is on (set by the provider). */
+  readonly reportKey?: string
+  /** Injected generation timestamp (epoch ms). */
+  readonly generatedAt: number
+}
+
+/** Round to 6 significant digits for stable, readable report numbers. */
+function round6(value: number): number {
+  return Number(value.toPrecision(6))
+}
+
+/** Linear-interpolation quantile over an ascending-sorted array. */
+function quantile(sorted: readonly number[], q: number): number {
+  const index = (sorted.length - 1) * q
+  const low = Math.floor(index)
+  const high = Math.ceil(index)
+  const lower = sorted[low] as number
+  const upper = sorted[high] as number
+  return lower + (upper - lower) * (index - low)
+}
+
+/** Compute the numeric distribution of already-parsed values. */
+export function numericProfile(values: readonly number[]): NumericProfile | undefined {
+  if (values.length === 0) return undefined
+  const sorted = [...values].sort((a, b) => a - b)
+  const sum = sorted.reduce((acc, value) => acc + value, 0)
+  const p25 = quantile(sorted, 0.25)
+  const p75 = quantile(sorted, 0.75)
+  const iqr = p75 - p25
+  const lowFence = p25 - 1.5 * iqr
+  const highFence = p75 + 1.5 * iqr
+  const outliers = iqr === 0 ? 0 : sorted.filter((value) => value < lowFence || value > highFence).length
+  return {
+    min: round6(sorted[0] as number),
+    max: round6(sorted[sorted.length - 1] as number),
+    mean: round6(sum / sorted.length),
+    median: round6(quantile(sorted, 0.5)),
+    p25: round6(p25),
+    p75: round6(p75),
+    outliers,
+  }
+}
+
+/** Count rows whose full content duplicates an earlier row (first occurrence is not counted). */
+export function countDuplicateRows(table: Table, signal?: AbortSignal): number {
+  const seen = new Set<string>()
+  let duplicates = 0
+  for (const [index, row] of table.rows.entries()) {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const key = JSON.stringify(table.columns.map((column) => row[column] ?? null))
+    if (seen.has(key)) {
+      duplicates += 1
+    } else {
+      seen.add(key)
+    }
+  }
+  return duplicates
+}
+
+/** Profile one column over the given rows. */
+function profileColumn(rows: readonly Row[], column: string, signal?: AbortSignal): ColumnProfile {
+  let missing = 0
+  let numbers = 0
+  let dates = 0
+  let booleans = 0
+  let strings = 0
+  const numericValues: number[] = []
+  const distinct = new Set<string>()
+  const frequencies = new Map<string, number>()
+  for (const [index, row] of rows.entries()) {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const cell = row[column]
+    if (isMissing(cell)) {
+      missing += 1
+      continue
+    }
+    const text = typeof cell === 'string' ? cell : JSON.stringify(cell)
+    distinct.add(text)
+    frequencies.set(text, (frequencies.get(text) ?? 0) + 1)
+    const numeric = parseNumeric(cell)
+    if (numeric !== undefined) {
+      numbers += 1
+      numericValues.push(numeric)
+      continue
+    }
+    if (parseDate(cell) !== undefined) {
+      dates += 1
+      continue
+    }
+    if (parseBoolean(cell) !== undefined) {
+      booleans += 1
+      continue
+    }
+    strings += 1
+  }
+
+  const present = rows.length - missing
+  const notes: string[] = []
+  let inferredType: InferredType
+  if (present === 0) {
+    inferredType = 'empty'
+  } else if (numbers === present) {
+    inferredType = 'number'
+  } else if (dates === present) {
+    inferredType = 'date'
+  } else if (booleans === present) {
+    inferredType = 'boolean'
+  } else if (strings === present) {
+    inferredType = 'string'
+  } else {
+    inferredType = 'mixed'
+    const parts = [
+      numbers > 0 ? `${numbers} numeric` : undefined,
+      dates > 0 ? `${dates} date` : undefined,
+      booleans > 0 ? `${booleans} boolean` : undefined,
+      strings > 0 ? `${strings} string` : undefined,
+    ].filter((part) => part !== undefined)
+    notes.push(`mixed types among ${present} present values: ${parts.join(', ')}`)
+  }
+
+  const profile: ColumnProfile = {
+    name: column,
+    inferredType,
+    missing,
+    missingRate: rows.length === 0 ? 0 : round6(missing / rows.length),
+    unique: distinct.size,
+    notes,
+  }
+  const numeric = inferredType === 'number' ? numericProfile(numericValues) : undefined
+  const topValues =
+    (inferredType === 'string' || inferredType === 'boolean') && distinct.size > 0 && distinct.size <= 10
+      ? [...frequencies.entries()]
+          .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+          .slice(0, 5)
+          .map(([value, count]) => ({ value, count }))
+      : undefined
+  return {
+    ...profile,
+    ...(numeric !== undefined ? { numeric } : {}),
+    ...(topValues !== undefined ? { topValues } : {}),
+  }
+}
+
+/**
+ * Profile a parsed table. Column cards are computed over a deterministic
+ * systematic sample when `sample` is given; row counts and duplicate counts
+ * always cover the full table.
+ * @param table - the parsed dataset.
+ * @param options - dataset label, optional sample size, injected timestamp, abort signal.
+ * @returns the profile report.
+ */
+export function profileTable(
+  table: Table,
+  options: { dataset: string; sample?: number | undefined; generatedAt: number; signal?: AbortSignal | undefined },
+): ProfileReport {
+  throwIfAborted(options.signal)
+  const profiled = options.sample === undefined ? table.rows : sampleRows(table.rows, options.sample)
+  const columns = table.columns.map((column) => profileColumn(profiled, column, options.signal))
+  const duplicateRows = countDuplicateRows(table, options.signal)
+  return {
+    dataset: options.dataset,
+    rowCount: table.rows.length,
+    sampled: profiled.length !== table.rows.length,
+    profiledRows: profiled.length,
+    columnCount: table.columns.length,
+    duplicateRows,
+    columns,
+    generatedAt: options.generatedAt,
+  }
+}
+
+/** Human-readable profile summary for the tool's Native render. */
+export function renderProfileText(report: ProfileReport): string {
+  const lines: string[] = []
+  lines.push(`Profile of ${report.dataset}: ${report.rowCount} rows x ${report.columnCount} columns` +
+    (report.sampled ? ` (column cards over a systematic sample of ${report.profiledRows} rows)` : ''))
+  if (report.duplicateRows > 0) lines.push(`Duplicate rows: ${report.duplicateRows}`)
+  for (const column of report.columns) {
+    const parts = [`${column.name}: ${column.inferredType}`]
+    if (column.missing > 0) parts.push(`missing ${column.missing} (${(column.missingRate * 100).toFixed(1)}%)`)
+    parts.push(`unique ${column.unique}`)
+    if (column.numeric !== undefined) {
+      parts.push(
+        `min ${column.numeric.min}, p25 ${column.numeric.p25}, median ${column.numeric.median}, p75 ${column.numeric.p75}, max ${column.numeric.max}, mean ${column.numeric.mean}` +
+          (column.numeric.outliers > 0 ? `, ${column.numeric.outliers} IQR outliers` : ''),
+      )
+    }
+    if (column.topValues !== undefined) {
+      parts.push(`top: ${column.topValues.map((entry) => `${JSON.stringify(entry.value)} x${entry.count}`).join(', ')}`)
+    }
+    for (const note of column.notes) parts.push(`note: ${note}`)
+    lines.push(`- ${parts.join('; ')}`)
+  }
+  return lines.join('\n')
+}

package/src/provider-local.ts

@@ -0,0 +1,194 @@
+/**
+ * The local deterministic Provider of the `ctx.dataQuality` seam: orchestrates
+ * dataset loading, the pure engines, durable report persistence, and the
+ * adaptive `data-quality/*` session events. All computation is TypeScript in
+ * this process — no model arithmetic, no external processes.
+ * @module dsh-data-quality/provider-local
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+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 { 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 { truncateRow } from './present.ts'
+import {
+  DataQualityService,
+  type CitationCheckRequest,
+  type CitationCheckResult,
+  type CleanRequest,
+  type CleanRunReport,
+  type ProfileRequest,
+  type VerifyRequest,
+} from './service.ts'
+import type { ProfileReport } from './profile.ts'
+import type { VerifyReport } from './verify.ts'
+import type { Session } from '@deepseek-ai/dsh-session'
+
+/** Provider construction dependencies. */
+export interface ProviderDeps {
+  /** Report persistence; absent when `storeReports` is off. */
+  readonly store?: ReportStore | undefined
+  /** Injected clock — the single time source for reports and freshness defaults. */
+  readonly now: () => number
+}
+
+/**
+ * The local deterministic `dataQuality` implementation. Mounted by the plugin
+ * entry; third-party plugins consume it through `ctx.dataQuality`.
+ */
+export class LocalDataQualityService extends DataQualityService {
+  private readonly config: ResolvedConfig
+  private readonly deps: ProviderDeps
+
+  /**
+   * @param ctx - the plugin context.
+   * @param config - the resolved plugin config.
+   * @param deps - store handle plus the injected clock.
+   */
+  constructor(ctx: Context, config: ResolvedConfig, deps: ProviderDeps) {
+    super(ctx)
+    this.config = config
+    this.deps = deps
+  }
+
+  /** The absolute root for service-level calls without a session workspace. */
+  serviceRoot(): string {
+    return this.config.workspaceRoot !== '' ? path.resolve(this.config.workspaceRoot) : process.cwd()
+  }
+
+  /** Persist one report when persistence is on; returns the storage key. */
+  private async persist(kind: ReportRecord['kind'], dataset: string, report: Record<string, unknown>): Promise<string | undefined> {
+    const store = this.deps.store
+    if (store === undefined) return undefined
+    const record: ReportRecord = { kind, at: this.deps.now(), dataset, report }
+    const key = reportKeyOf(record)
+    await store.put({ ...record })
+    return key
+  }
+
+  /** Emit the adaptive session event when the call carries a session. */
+  emitEvent(session: Session | undefined, kind: 'profile' | 'clean' | 'verify', dataset: string, reportKey: string | undefined, summary: { rows: number; columns?: number; rules?: number; failedRules?: number; passed?: boolean }): void {
+    if (session === undefined) return
+    appendDataQualityEvent(session, `data-quality/${kind}`, {
+      kind,
+      dataset,
+      ...(reportKey !== undefined ? { reportKey } : {}),
+      summary,
+    })
+  }
+
+  /** @inheritdoc DataQualityService.profileDataset */
+  override async profileDataset(request: ProfileRequest): Promise<ProfileReport> {
+    throwIfAborted(request.signal)
+    const absolute = resolveWorkspacePath(request.workspace, request.dataset, this.config)
+    const table = await loadTable(absolute, this.config, request.signal)
+    const report = profileTable(table, {
+      dataset: request.dataset,
+      sample: request.sample,
+      generatedAt: this.deps.now(),
+      signal: request.signal,
+    })
+    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 })
+    return { ...report, ...(reportKey !== undefined ? { reportKey } : {}) }
+  }
+
+  /** @inheritdoc DataQualityService.cleanDataset */
+  override async cleanDataset(request: CleanRequest): Promise<CleanRunReport> {
+    throwIfAborted(request.signal)
+    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) {
+      const outputAbsolute = resolveWorkspacePath(request.workspace, request.outputPath, this.config)
+      if (outputAbsolute === absolute) {
+        throw new Error(`outputPath ${JSON.stringify(request.outputPath)} would overwrite the input dataset; choose a different path`)
+      }
+      const ext = path.extname(outputAbsolute).toLowerCase()
+      const text = ext === '.csv' || ext === '.tsv'
+        ? serializeDelimited(result.columns, result.rows, ext === '.csv' ? ',' : '\t')
+        : ext === '.jsonl'
+          ? `${result.rows.map((row) => JSON.stringify(row)).join('\n')}\n`
+          : `${JSON.stringify(result.rows, null, 2)}\n`
+      await mkdir(path.dirname(outputAbsolute), { recursive: true })
+      throwIfAborted(request.signal)
+      await writeFile(outputAbsolute, text, 'utf8')
+      writtenPath = request.outputPath
+    }
+
+    const generatedAt = this.deps.now()
+    const reportKey = await this.persist('clean', request.dataset, {
+      dataset: request.dataset,
+      inputRows: result.inputRows,
+      outputRows: result.outputRows,
+      logs: result.logs,
+      ...(writtenPath !== undefined ? { outputPath: writtenPath } : {}),
+      generatedAt,
+    } 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,
+      logs: result.logs,
+      preview: { columns: result.columns, rows: previewRows },
+      ...(writtenPath !== undefined ? { outputPath: writtenPath } : {}),
+      ...(reportKey !== undefined ? { reportKey } : {}),
+      generatedAt,
+    }
+  }
+
+  /** @inheritdoc DataQualityService.verifyDataset */
+  override async verifyDataset(request: VerifyRequest): Promise<VerifyReport> {
+    throwIfAborted(request.signal)
+    const absolute = resolveWorkspacePath(request.workspace, request.dataset, this.config)
+    const table = await loadTable(absolute, this.config, request.signal)
+    const outcome = verifyTable(table, request.rules, {
+      evidenceRowLimit: this.config.evidenceRowLimit,
+      now: this.deps.now,
+      signal: request.signal,
+    })
+    const report: VerifyReport = { dataset: request.dataset, ...outcome }
+    const failedRules = report.rules.filter((rule) => !rule.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,
+    })
+    return { ...report, ...(reportKey !== undefined ? { reportKey } : {}) }
+  }
+
+  /** @inheritdoc DataQualityService.verifyCitations */
+  override async verifyCitations(request: CitationCheckRequest): Promise<CitationCheckResult> {
+    const absolute = resolveWorkspacePath(this.serviceRoot(), request.dataset, this.config)
+    const document = await loadDocument(absolute, this.config)
+    const result = checkCitations(document, request.citations, this.config.defaultTolerance)
+    const verified = result.results.filter((entry) => entry.status === 'verified').length
+    const mismatched = result.results.filter((entry) => entry.status === 'mismatch').length
+    const notFound = result.results.filter((entry) => entry.status === 'not-found').length
+    const unverifiable = result.results.filter((entry) => entry.status === 'unverifiable').length
+    await this.persist('citations', request.dataset, {
+      dataset: request.dataset,
+      checked: result.results.length,
+      verified,
+      mismatched,
+      notFound,
+      unverifiable,
+      results: result.results,
+      generatedAt: this.deps.now(),
+    } as unknown as Record<string, unknown>)
+    return result
+  }
+}

package/src/service.ts

@@ -0,0 +1,172 @@
+/**
+ * Service Definition of the `dsh-data-quality` capability seam: the
+ * `ctx.dataQuality` surface other plugins may optionally consume, plus the
+ * internal request/report types the local Provider and the tool Consumers
+ * share. The {@link CitationCheckRequest} / {@link CitationCheckResult}
+ * citation contract is FROZEN for cross-plugin consumers — change it only
+ * with a coordinated ecosystem migration.
+ * @module dsh-data-quality/service
+ */
+
+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 { ProfileReport } from './profile.ts'
+import type { VerifyReport, VerifyRule } from './verify.ts'
+
+export interface CitationCheckRequest {
+  /** Workspace-relative path of the source dataset snapshot (CSV/JSON). */
+  dataset: string
+  /** Citations to verify against the dataset. */
+  citations: Array<{
+    /** Stable id chosen by the caller, echoed back in results. */
+    id: string
+    /** JSON-path-ish locator, e.g. "rows[3].nav" or "summary.annualReturn". */
+    path: string
+    /** The value as cited in the document. */
+    value: number | string
+    /** Optional relative tolerance for numeric comparison, e.g. 0.01 = 1%. */
+    tolerance?: number
+  }>
+}
+export interface CitationCheckResult {
+  results: Array<{
+    id: string
+    status: 'verified' | 'mismatch' | 'not-found' | 'unverifiable'
+    /** Actual value found at path, when found. */
+    actual?: number | string
+    /** Human-readable evidence note. */
+    note?: string
+  }>
+}
+
+/** Profile request through the service layer (tools pass the session workspace). */
+export interface ProfileRequest {
+  /** Workspace-relative dataset path. */
+  readonly dataset: string
+  /** Optional deterministic systematic sample size for column cards. */
+  readonly sample?: number | undefined
+  /** Absolute workspace root the dataset resolves inside. */
+  readonly workspace: string
+  /** Calling session (receives the `data-quality/profile` event), when any. */
+  readonly session?: Session | undefined
+  /** Cancellation from the tool call. */
+  readonly signal?: AbortSignal | undefined
+}
+
+/** Clean request through the service layer. */
+export interface CleanRequest {
+  /** Workspace-relative dataset path. */
+  readonly dataset: string
+  /** Non-empty declarative cleaning rule list, applied in order. */
+  readonly rules: readonly CleanRule[]
+  /** Workspace-relative output path; omitted = no disk write, preview only. */
+  readonly outputPath?: string | undefined
+  /** Absolute workspace root the dataset resolves inside. */
+  readonly workspace: string
+  /** Calling session (receives the `data-quality/clean` event), when any. */
+  readonly session?: Session | undefined
+  /** Cancellation from the tool call. */
+  readonly signal?: AbortSignal | undefined
+}
+
+/** Verify request through the service layer. */
+export interface VerifyRequest {
+  /** Workspace-relative dataset path. */
+  readonly dataset: string
+  /** Non-empty declarative verification rule list. */
+  readonly rules: readonly VerifyRule[]
+  /** Absolute workspace root the dataset resolves inside. */
+  readonly workspace: string
+  /** Calling session (receives the `data-quality/verify` event), when any. */
+  readonly session?: Session | undefined
+  /** Cancellation from the tool call. */
+  readonly signal?: AbortSignal | undefined
+}
+
+/** The value a clean run returns (tool canonical value minus presentation). */
+export interface CleanRunReport {
+  readonly dataset: string
+  readonly inputRows: number
+  readonly outputRows: number
+  readonly logs: CleanRuleLog[]
+  /** First `evidenceRowLimit` cleaned rows for inspection (display-truncated). */
+  readonly preview: { readonly columns: string[]; readonly rows: Array<Record<string, JsonValue>> }
+  /** Workspace-relative output path when the run wrote a file. */
+  readonly outputPath?: string
+  /** Storage-domain key of the persisted report, when persistence is on. */
+  readonly reportKey?: string
+  readonly generatedAt: number
+}
+
+/** The value a verifyCitation call persists (report envelope kind `citations`). */
+export interface CitationCheckPersisted {
+  readonly dataset: string
+  readonly checked: number
+  readonly verified: number
+  readonly mismatched: number
+  readonly notFound: number
+  readonly unverifiable: number
+  readonly results: CitationCheckResult['results']
+  readonly generatedAt: number
+}
+
+/**
+ * The `ctx.dataQuality` service. The local Provider implements deterministic
+ * TypeScript computation; Consumers (the three tools and third-party plugins)
+ * never re-implement the math.
+ */
+export abstract class DataQualityService extends Service {
+  /**
+   * Register as `dataQuality` on the context.
+   * @param ctx - the plugin context.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'dataQuality')
+  }
+
+  /**
+   * Frozen cross-plugin contract: verify document citations against a dataset
+   * snapshot. The dataset resolves against the configured service workspace
+   * root (`workspaceRoot`, defaulting to the harness launch directory).
+   * @param request - dataset path plus citations.
+   * @returns one result per citation, ids echoed.
+   */
+  abstract verifyCitations(request: CitationCheckRequest): Promise<CitationCheckResult>
+
+  /**
+   * Profile a workspace dataset (row/column counts, inferred types,
+   * missingness, cardinality, numeric distribution, suspected anomalies).
+   * @param request - dataset path, optional sample size, workspace root.
+   * @returns the profile report.
+   */
+  abstract profileDataset(request: ProfileRequest): Promise<ProfileReport>
+
+  /**
+   * Apply declarative cleaning rules to a workspace dataset. The source file
+   * is never overwritten; without `outputPath` nothing touches the disk.
+   * @param request - dataset path, ordered rules, optional output path, workspace root.
+   * @returns the cleaned preview plus the per-rule audit log.
+   */
+  abstract cleanDataset(request: CleanRequest): Promise<CleanRunReport>
+
+  /**
+   * Apply declarative verification rules to a workspace dataset. A failing
+   * dataset is a normal result (`passed: false`), never a thrown error.
+   * @param request - dataset path, rules, workspace root.
+   * @returns the verify report.
+   */
+  abstract verifyDataset(request: VerifyRequest): Promise<VerifyReport>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Deterministic data profiling / cleaning / verification, when the dsh-data-quality bundle is mounted. */
+    dataQuality: DataQualityService
+  }
+}
+
+/** Re-exports so consumers pull the whole seam vocabulary from one module. */
+export type { CleanResult, CleanRule, CleanRuleLog } from './clean.ts'
+export type { ProfileReport } from './profile.ts'
+export type { VerifyReport, VerifyRule } from './verify.ts'

package/src/store.ts

@@ -0,0 +1,74 @@
+/**
+ * Durable report storage over the harness storage domain. The `data_quality`
+ * domain keeps one record per profile/clean/verify/citations run, keyed by an
+ * injected timestamp plus a path fingerprint, so reports survive a restart
+ * and stay queryable without touching the session log.
+ * @module dsh-data-quality/store
+ */
+
+import z from 'zod'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+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']),
+  at: z.number().int().nonnegative(),
+  dataset: z.string(),
+  report: z.record(z.string(), z.unknown()),
+})
+
+/** One persisted report record. */
+export interface ReportRecord {
+  readonly kind: 'profile' | 'clean' | 'verify' | 'citations'
+  /** Injected run timestamp (epoch ms). */
+  readonly at: number
+  /** Workspace-relative dataset path as the caller gave it. */
+  readonly dataset: string
+  /** The full run report (profile/clean/verify/citations shape by `kind`). */
+  readonly report: Record<string, unknown>
+}
+
+/** The `dsh-data-quality` storage-domain declaration. */
+export const dataQualityDomainSpec = defineDomain({
+  name: 'data_quality',
+  version: 1,
+  tables: {
+    reports: domainTable<string, ReportRecord>(reportRecordSchema),
+  },
+})
+
+/** Handle over the reports table with deterministic key construction. */
+export interface ReportStore {
+  /**
+   * Persist one run report.
+   * @param record - the report envelope (kind/dataset/at/report).
+   * @returns the storage key the record was written under.
+   */
+  put(record: ReportRecord): Promise<string>
+  /**
+   * Read one persisted report.
+   * @param key - the key {@link put} returned.
+   * @returns the record, or `undefined` when absent.
+   */
+  get(key: string): ReportRecord | undefined
+}
+
+/** Pad to two digits for the key timestamp. */
+function pad2(value: number): string {
+  return String(value).padStart(2, '0')
+}
+
+/**
+ * Build the storage key for one run: `YYYYMMDDHHmmssSSS-<kind>-<pathFp>`.
+ * UTC digits keep the key timezone-independent and filename-safe everywhere.
+ * @param record - the report envelope.
+ * @returns the deterministic key.
+ */
+export function reportKeyOf(record: ReportRecord): string {
+  const date = new Date(record.at)
+  const stamp =
+    `${date.getUTCFullYear()}${pad2(date.getUTCMonth() + 1)}${pad2(date.getUTCDate())}` +
+    `${pad2(date.getUTCHours())}${pad2(date.getUTCMinutes())}${pad2(date.getUTCSeconds())}${String(date.getUTCMilliseconds()).padStart(3, '0')}`
+  return `${stamp}-${record.kind}-${pathFingerprint(record.dataset)}`
+}