dsh-data-quality 0.1.0

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "dsh-data-quality",
+  "version": "0.1.0",
+  "description": "Deterministic data profiling, cleaning, and verification for DeepSeek Harness: a ctx.dataQuality capability seam (Service Definition / local Provider / tool Consumers) with data_profile, data_clean, and data_verify model tools, a frozen cross-plugin verifyCitations contract, durable reports in a storage domain, and data-quality/* session events on hosts that support them.",
+  "author": "dsh-data-quality contributors",
+  "private": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "README.zh.md",
+    "README.es.md",
+    "README.pt.md",
+    "README.hi.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dshWorkshop": {
+    "schema": "omdsh-workshop-package/v1",
+    "type": "plugin",
+    "integration": {
+      "protocol": "harness-profile",
+      "artifact": "cordis.patch.yml"
+    },
+    "install": {
+      "mode": "transactional",
+      "adapter": "profile-bundle",
+      "failurePolicy": "generation-rollback",
+      "touchesCurrentBeforeActivation": false
+    },
+    "lifecycle": {
+      "activation": "restart-profile",
+      "dispose": "supported"
+    },
+    "permissions": [
+      "filesystem:read",
+      "filesystem:write",
+      "session:read",
+      "session:write",
+      "native-code:none"
+    ],
+    "compatibility": {
+      "dshVersions": [
+        "0.1.0-rc.6"
+      ]
+    },
+    "capability": {
+      "id": "data-quality",
+      "kind": "data-tooling",
+      "invocation": "mount the dsh-data-quality bundle row",
+      "expected": "provides ctx.dataQuality (verifyCitations + profile/clean/verify service methods), registers the data_profile / data_clean / data_verify tools, and persists reports to the data_quality storage domain"
+    },
+    "evidence": {
+      "install": null,
+      "failureIsolation": null,
+      "hotReload": null,
+      "remove": null
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "data-quality",
+    "data-cleaning",
+    "data-profiling",
+    "data-verification"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.0"
+  },
+  "dependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis-plugin-include": "1.0.6",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-json": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@types/node": "^22.19.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "oxlint": "0.18.1",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "node scripts/prepare.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "typecheck:ci": "tsc -p tsconfig.ci.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint",
+    "prepare": "node scripts/prepare.mjs",
+    "verify:self-contained": "node scripts/verify-self-contained.mjs",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "verify:readme-sync": "node scripts/check-readme-sync.mjs",
+    "pack:check": "node scripts/prepare.mjs && pnpm pack"
+  },
+  "license": "Apache-2.0"
+}

package/src/clean.ts

@@ -0,0 +1,382 @@
+/**
+ * Declarative cleaning rules over a parsed {@link Table}: dedupe, fill-missing,
+ * coerce-type, normalize-unit, trim, and map-values. Pure and deterministic —
+ * rules apply in array order, each seeing the previous rule's output; every
+ * rule logs how many rows it affected. Unknown columns and invalid rule
+ * parameters fail loud.
+ * @module dsh-data-quality/clean
+ */
+
+import { isMissing, parseBoolean, parseDate, parseNumeric, throwIfAborted, type Cell, type Row, type Table } from './dataset.ts'
+
+/** One declarative cleaning rule (discriminated on `rule`). */
+export type CleanRule =
+  | { readonly rule: 'dedupe'; readonly columns?: readonly string[] }
+  | {
+      readonly rule: 'fill-missing'
+      readonly column: string
+      readonly strategy: 'constant' | 'mean' | 'median' | 'forward'
+      readonly value?: string | number
+    }
+  | { readonly rule: 'coerce-type'; readonly column: string; readonly to: 'number' | 'date' | 'boolean' }
+  | { readonly rule: 'normalize-unit'; readonly column: string; readonly factors: Readonly<Record<string, number>> }
+  | { readonly rule: 'trim'; readonly columns?: readonly string[] }
+  | {
+      readonly rule: 'map-values'
+      readonly column: string
+      readonly map: Readonly<Record<string, string>>
+      readonly else?: 'keep' | 'missing'
+    }
+
+/** Raised for invalid rules or unknown columns; `message` names the rule index and reason. */
+export class CleanRuleError extends Error {
+  /**
+   * @param ruleIndex - index of the offending rule in the request array.
+   * @param message - actionable human-readable detail.
+   */
+  constructor(
+    readonly ruleIndex: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'CleanRuleError'
+  }
+}
+
+/** Per-rule audit entry. */
+export interface CleanRuleLog {
+  readonly ruleIndex: number
+  readonly rule: CleanRule['rule']
+  /** Rows the rule changed (removed, filled, coerced, rewritten, or trimmed). */
+  readonly affectedRows: number
+  /** Extra detail, e.g. coerce failure counts. */
+  readonly detail: string
+}
+
+/** The cleaning outcome: cleaned table plus the per-rule audit log. */
+export interface CleanResult {
+  readonly columns: string[]
+  readonly rows: Row[]
+  readonly logs: CleanRuleLog[]
+  readonly inputRows: number
+  readonly outputRows: number
+}
+
+/** Assert `column` exists; every rule validates its columns before touching data. */
+function requireColumn(columns: readonly string[], column: string, ruleIndex: number): void {
+  if (!columns.includes(column)) {
+    throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: unknown column ${JSON.stringify(column)} (columns: ${columns.join(', ')})`)
+  }
+}
+
+/** Assert every selected column exists. */
+function requireColumns(columns: readonly string[], selected: readonly string[], ruleIndex: number): void {
+  for (const column of selected) requireColumn(columns, column, ruleIndex)
+}
+
+/** dedupe: keep the first row of each key group; later duplicates are removed. */
+function applyDedupe(table: Table, rule: Extract<CleanRule, { rule: 'dedupe' }>, ruleIndex: number, signal?: AbortSignal): { table: Table; log: CleanRuleLog } {
+  const selected = rule.columns ?? table.columns
+  requireColumns(table.columns, selected, ruleIndex)
+  const seen = new Set<string>()
+  const rows: Row[] = []
+  let removed = 0
+  for (const [index, row] of table.rows.entries()) {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const key = JSON.stringify(selected.map((column) => row[column] ?? null))
+    if (seen.has(key)) {
+      removed += 1
+      continue
+    }
+    seen.add(key)
+    rows.push(row)
+  }
+  return {
+    table: { columns: table.columns, rows },
+    log: { ruleIndex, rule: 'dedupe', affectedRows: removed, detail: `removed ${removed} duplicate row(s) by [${selected.join(', ')}]` },
+  }
+}
+
+/** fill-missing: constant / mean / median / forward fill of missing cells in one column. */
+function applyFillMissing(table: Table, rule: Extract<CleanRule, { rule: 'fill-missing' }>, ruleIndex: number, signal?: AbortSignal): { table: Table; log: CleanRuleLog } {
+  requireColumn(table.columns, rule.column, ruleIndex)
+  let fill: Cell | undefined
+  let detail: string
+  switch (rule.strategy) {
+    case 'constant': {
+      if (rule.value === undefined) {
+        throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: fill-missing strategy "constant" requires a value`)
+      }
+      fill = rule.value
+      detail = `filled with constant ${JSON.stringify(rule.value)}`
+      break
+    }
+    case 'mean':
+    case 'median': {
+      const values = table.rows.map((row) => parseNumeric(row[rule.column])).filter((value) => value !== undefined).sort((a, b) => a - b)
+      if (values.length === 0) {
+        throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: fill-missing strategy "${rule.strategy}" needs at least one numeric value in column ${JSON.stringify(rule.column)}`)
+      }
+      const computed = rule.strategy === 'mean'
+        ? values.reduce((acc, value) => acc + value, 0) / values.length
+        : values.length % 2 === 1
+          ? (values[(values.length - 1) / 2] as number)
+          : ((values[values.length / 2 - 1] as number) + (values[values.length / 2] as number)) / 2
+      fill = computed
+      detail = `filled with ${rule.strategy} ${computed}`
+      break
+    }
+    case 'forward': {
+      fill = undefined
+      detail = 'filled with the previous non-missing value'
+      break
+    }
+  }
+  let filled = 0
+  let previous: Cell | undefined
+  const rows = table.rows.map((row, index) => {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const cell = row[rule.column]
+    if (!isMissing(cell)) {
+      previous = cell ?? null
+      return row
+    }
+    const replacement = rule.strategy === 'forward' ? previous : fill
+    if (replacement === undefined) return row
+    filled += 1
+    return { ...row, [rule.column]: replacement }
+  })
+  return {
+    table: { columns: table.columns, rows },
+    log: { ruleIndex, rule: 'fill-missing', affectedRows: filled, detail: `${detail}; ${filled} row(s) filled` },
+  }
+}
+
+/** coerce-type: rewrite one column to number / ISO date / boolean; failures become missing and are counted. */
+function applyCoerceType(table: Table, rule: Extract<CleanRule, { rule: 'coerce-type' }>, ruleIndex: number, signal?: AbortSignal): { table: Table; log: CleanRuleLog } {
+  requireColumn(table.columns, rule.column, ruleIndex)
+  let coerced = 0
+  let failed = 0
+  const failureExamples: string[] = []
+  const rows = table.rows.map((row, index) => {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const cell = row[rule.column]
+    if (isMissing(cell)) return row
+    let value: Cell | undefined
+    switch (rule.to) {
+      case 'number': {
+        const numeric = parseNumeric(cell)
+        value = numeric === undefined ? undefined : numeric
+        break
+      }
+      case 'date': {
+        const epoch = parseDate(cell)
+        if (epoch === undefined) {
+          value = undefined
+        } else {
+          const date = new Date(epoch)
+          value = date.getUTCHours() === 0 && date.getUTCMinutes() === 0 && date.getUTCSeconds() === 0
+            ? date.toISOString().slice(0, 10)
+            : date.toISOString()
+        }
+        break
+      }
+      case 'boolean': {
+        const bool = parseBoolean(cell)
+        value = bool === undefined ? undefined : String(bool)
+        break
+      }
+    }
+    if (value === undefined) {
+      failed += 1
+      if (failureExamples.length < 3) failureExamples.push(JSON.stringify(cell))
+      return { ...row, [rule.column]: null }
+    }
+    coerced += 1
+    return { ...row, [rule.column]: value }
+  })
+  const detail = `${coerced} value(s) coerced to ${rule.to}` +
+    (failed > 0 ? `; ${failed} failure(s) set to missing (e.g. ${failureExamples.join(', ')})` : '')
+  return {
+    table: { columns: table.columns, rows },
+    log: { ruleIndex, rule: 'coerce-type', affectedRows: coerced, detail },
+  }
+}
+
+/** normalize-unit: strip a unit suffix and multiply by its factor (e.g. 万 -> 1e4). */
+function applyNormalizeUnit(table: Table, rule: Extract<CleanRule, { rule: 'normalize-unit' }>, ruleIndex: number, signal?: AbortSignal): { table: Table; log: CleanRuleLog } {
+  requireColumn(table.columns, rule.column, ruleIndex)
+  const entries = Object.entries(rule.factors)
+  if (entries.length === 0) {
+    throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: normalize-unit requires a non-empty factors map`)
+  }
+  for (const [suffix, factor] of entries) {
+    if (suffix === '') throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: normalize-unit suffixes must not be empty`)
+    if (!Number.isFinite(factor) || factor <= 0) {
+      throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: factor for ${JSON.stringify(suffix)} must be a positive finite number, got ${String(factor)}`)
+    }
+  }
+  // Longest suffix first so "亿万" style prefixes cannot shadow longer units.
+  const ordered = [...entries].sort((a, b) => b[0].length - a[0].length)
+  let normalized = 0
+  let skipped = 0
+  const rows = table.rows.map((row, index) => {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const cell = row[rule.column]
+    if (isMissing(cell)) return row
+    const plain = parseNumeric(cell)
+    if (plain !== undefined) {
+      normalized += 1
+      return { ...row, [rule.column]: plain }
+    }
+    if (typeof cell === 'string') {
+      const text = cell.trim()
+      for (const [suffix, factor] of ordered) {
+        if (!text.endsWith(suffix)) continue
+        const numeric = parseNumeric(text.slice(0, text.length - suffix.length))
+        if (numeric === undefined) continue
+        normalized += 1
+        return { ...row, [rule.column]: numeric * factor }
+      }
+    }
+    skipped += 1
+    return row
+  })
+  const detail = `${normalized} value(s) normalized to base units` + (skipped > 0 ? `; ${skipped} unparseable value(s) left unchanged` : '')
+  return {
+    table: { columns: table.columns, rows },
+    log: { ruleIndex, rule: 'normalize-unit', affectedRows: normalized, detail },
+  }
+}
+
+/** trim: strip leading/trailing whitespace of string cells in the selected columns. */
+function applyTrim(table: Table, rule: Extract<CleanRule, { rule: 'trim' }>, ruleIndex: number, signal?: AbortSignal): { table: Table; log: CleanRuleLog } {
+  const selected = rule.columns ?? table.columns
+  requireColumns(table.columns, selected, ruleIndex)
+  let trimmed = 0
+  const rows = table.rows.map((row, index) => {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    let changed = false
+    const next = { ...row }
+    for (const column of selected) {
+      const cell = next[column]
+      if (typeof cell !== 'string') continue
+      const value = cell.trim()
+      if (value !== cell) {
+        next[column] = value
+        changed = true
+      }
+    }
+    if (changed) trimmed += 1
+    return changed ? next : row
+  })
+  return {
+    table: { columns: table.columns, rows },
+    log: { ruleIndex, rule: 'trim', affectedRows: trimmed, detail: `trimmed whitespace in [${selected.join(', ')}] for ${trimmed} row(s)` },
+  }
+}
+
+/** map-values: exact-match enum mapping; unmapped values follow the `else` policy. */
+function applyMapValues(table: Table, rule: Extract<CleanRule, { rule: 'map-values' }>, ruleIndex: number, signal?: AbortSignal): { table: Table; log: CleanRuleLog } {
+  requireColumn(table.columns, rule.column, ruleIndex)
+  const elsePolicy = rule.else ?? 'keep'
+  let mapped = 0
+  let unmapped = 0
+  const rows = table.rows.map((row, index) => {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const cell = row[rule.column]
+    if (isMissing(cell)) return row
+    const key = typeof cell === 'string' ? cell : typeof cell === 'object' && cell !== null ? JSON.stringify(cell) : String(cell)
+    const replacement = rule.map[key]
+    if (replacement !== undefined) {
+      mapped += 1
+      return { ...row, [rule.column]: replacement }
+    }
+    if (elsePolicy === 'missing') {
+      unmapped += 1
+      return { ...row, [rule.column]: null }
+    }
+    unmapped += 1
+    return row
+  })
+  const detail = `${mapped} value(s) mapped` + (unmapped > 0 ? `; ${unmapped} unmapped value(s) ${elsePolicy === 'missing' ? 'set to missing' : 'kept'}` : '')
+  return {
+    table: { columns: table.columns, rows },
+    log: { ruleIndex, rule: 'map-values', affectedRows: mapped, detail },
+  }
+}
+
+/**
+ * Apply cleaning rules in array order; each rule sees the previous output.
+ * @param table - the parsed dataset.
+ * @param rules - non-empty rule list.
+ * @param options - abort signal.
+ * @returns the cleaned table plus the per-rule audit log.
+ */
+export function applyCleanRules(table: Table, rules: readonly CleanRule[], options: { signal?: AbortSignal | undefined } = {}): CleanResult {
+  if (rules.length === 0) {
+    throw new CleanRuleError(0, 'rules must be a non-empty array')
+  }
+  let current: Table = { columns: [...table.columns], rows: table.rows.map((row) => ({ ...row })) }
+  const logs: CleanRuleLog[] = []
+  for (const [ruleIndex, rule] of rules.entries()) {
+    throwIfAborted(options.signal)
+    let step: { table: Table; log: CleanRuleLog }
+    switch (rule.rule) {
+      case 'dedupe':
+        step = applyDedupe(current, rule, ruleIndex, options.signal)
+        break
+      case 'fill-missing':
+        step = applyFillMissing(current, rule, ruleIndex, options.signal)
+        break
+      case 'coerce-type':
+        step = applyCoerceType(current, rule, ruleIndex, options.signal)
+        break
+      case 'normalize-unit':
+        step = applyNormalizeUnit(current, rule, ruleIndex, options.signal)
+        break
+      case 'trim':
+        step = applyTrim(current, rule, ruleIndex, options.signal)
+        break
+      case 'map-values':
+        step = applyMapValues(current, rule, ruleIndex, options.signal)
+        break
+      default:
+        throw new CleanRuleError(ruleIndex, `rule ${ruleIndex}: unknown rule type ${JSON.stringify((rule as CleanRule).rule)}`)
+    }
+    current = step.table
+    logs.push(step.log)
+  }
+  return {
+    columns: current.columns,
+    rows: current.rows,
+    logs,
+    inputRows: table.rows.length,
+    outputRows: current.rows.length,
+  }
+}
+
+/**
+ * Serialize a table back to CSV/TSV text with RFC-4180 quoting (used when a
+ * clean run writes an output file). Numbers and booleans render via `String`;
+ * missing cells render empty.
+ * @param columns - column order.
+ * @param rows - rows to serialize.
+ * @param delimiter - field delimiter.
+ * @returns the file text (LF newlines, trailing newline).
+ */
+export function serializeDelimited(columns: readonly string[], rows: readonly Row[], delimiter: string): string {
+  const encode = (cell: Cell | undefined): string => {
+    if (isMissing(cell)) return ''
+    const text = typeof cell === 'string' ? cell : typeof cell === 'object' && cell !== null ? JSON.stringify(cell) : String(cell)
+    if (text.includes(delimiter) || text.includes('"') || text.includes('\n') || text.includes('\r')) {
+      return `"${text.replace(/"/gu, '""')}"`
+    }
+    return text
+  }
+  const lines = [columns.map((column) => encode(column)).join(delimiter)]
+  for (const row of rows) {
+    lines.push(columns.map((column) => encode(row[column])).join(delimiter))
+  }
+  return `${lines.join('\n')}\n`
+}

package/src/config.ts

@@ -0,0 +1,104 @@
+/**
+ * Config schema and resolution for `dsh-data-quality`. Every tunable is a
+ * validated {@link Config} field changeable from cordis.yml; the resolution
+ * step validates bounds so misconfiguration fails loud at mount.
+ * @module dsh-data-quality/config
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+/** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
+export interface Config {
+  /** Master switch; `false` mounts nothing. */
+  enabled?: boolean
+  /** Hard row cap per dataset load. */
+  maxRows?: number
+  /** Hard file-size cap in MiB per dataset load. */
+  maxFileSizeMB?: number
+  /** Default relative tolerance for numeric citation comparison. */
+  defaultTolerance?: number
+  /** Cap on evidence rows (verify) and preview rows (clean) in one result. */
+  evidenceRowLimit?: number
+  /** Extensions accepted as datasets (dot-prefixed, lowercase). */
+  allowedExtensions?: string[]
+  /** Absolute root for service-level calls without a session workspace; empty = process launch directory. */
+  workspaceRoot?: string
+  /** Persist reports to the `data_quality` storage domain. */
+  storeReports?: boolean
+}
+
+/** Fully resolved config handed to the runtime. */
+export interface ResolvedConfig {
+  readonly enabled: boolean
+  readonly maxRows: number
+  readonly maxFileSizeMB: number
+  readonly defaultTolerance: number
+  readonly evidenceRowLimit: number
+  readonly allowedExtensions: readonly string[]
+  readonly workspaceRoot: string
+  readonly storeReports: boolean
+}
+
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export const Config: z<Config> = z.object({
+  enabled: z.boolean().default(true),
+  maxRows: z.number().default(200_000),
+  maxFileSizeMB: z.number().default(64),
+  defaultTolerance: z.number().default(1e-9),
+  evidenceRowLimit: z.number().default(20),
+  allowedExtensions: z.array(z.string()).default(['.csv', '.tsv', '.json', '.jsonl']),
+  workspaceRoot: z.string().default(''),
+  storeReports: z.boolean().default(true),
+})
+
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name: string, value: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`)
+  }
+}
+
+/** Throw unless `value` is a finite number in `[min, max]`. */
+function assertFiniteRange(name: string, value: number, min: number, max: number): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`)
+  }
+}
+
+/**
+ * Validate raw values and fill explicit defaults. Invalid bounds throw here —
+ * misconfiguration fails loud at mount even without the Schemastery loader.
+ * @param config - raw (possibly partial) plugin config.
+ * @returns the fully resolved config.
+ */
+export function resolveConfig(config: Config = {}): ResolvedConfig {
+  const maxRows = config.maxRows ?? 200_000
+  assertPositiveInt('maxRows', maxRows)
+  const maxFileSizeMB = config.maxFileSizeMB ?? 64
+  assertFiniteRange('maxFileSizeMB', maxFileSizeMB, Number.MIN_VALUE, 1024)
+  const defaultTolerance = config.defaultTolerance ?? 1e-9
+  assertFiniteRange('defaultTolerance', defaultTolerance, 0, 1)
+  const evidenceRowLimit = config.evidenceRowLimit ?? 20
+  assertPositiveInt('evidenceRowLimit', evidenceRowLimit)
+
+  const allowedExtensions = (config.allowedExtensions ?? ['.csv', '.tsv', '.json', '.jsonl']).map((ext) => {
+    if (!/^\.[a-z0-9]+$/u.test(ext)) {
+      throw new TypeError(`allowedExtensions entries must be dot-prefixed lowercase extensions, got ${JSON.stringify(ext)}`)
+    }
+    return ext
+  })
+  if (allowedExtensions.length === 0) {
+    throw new TypeError('allowedExtensions must not be empty')
+  }
+
+  return {
+    enabled: config.enabled ?? true,
+    maxRows,
+    maxFileSizeMB,
+    defaultTolerance,
+    evidenceRowLimit,
+    allowedExtensions,
+    workspaceRoot: config.workspaceRoot ?? '',
+    storeReports: config.storeReports ?? true,
+  }
+}