dsh-data-quality 0.1.2 → 0.2.0

package/src/tools/profile-report-schema.ts

@@ -0,0 +1,97 @@
+/**
+ * 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'] as const
+
+/** One column card's schema. */
+export const COLUMN_PROFILE_SCHEMA = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', required: true },
+    inferredType: { type: 'string', enum: ['number', 'date', 'boolean', 'string', 'empty', 'mixed'], required: true },
+    missing: { type: 'number', required: true },
+    missingRate: { type: 'number', required: true },
+    unique: { type: 'number', required: true },
+    numeric: {
+      type: 'object',
+      properties: {
+        count: { type: 'number', required: true },
+        distinct: { type: 'number', required: true },
+        min: { type: 'number', required: true },
+        max: { type: 'number', required: true },
+        mean: { type: 'number', required: true },
+        median: { type: 'number', required: true },
+        p25: { type: 'number', required: true },
+        p75: { type: 'number', required: true },
+        outliers: { type: 'number', required: true },
+      },
+      additionalProperties: false,
+    },
+    topValues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          value: { type: 'string', required: true },
+          count: { type: 'number', required: true },
+        },
+        additionalProperties: false,
+      },
+    },
+    notes: { type: 'array', items: { type: 'string' }, required: true },
+  },
+  additionalProperties: false,
+} as const
+
+/** The full profile report's schema. */
+export const PROFILE_REPORT_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 },
+    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,
+} as const

package/src/tools/profile.ts

@@ -6,46 +6,10 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { DataQualityService } from '../service.ts'
-import { renderProfileText } from '../profile.ts'
+import { renderProfileText, type ProfileReport } from '../profile.ts'
+import { PROFILE_REPORT_SCHEMA } from './profile-report-schema.ts'
 import { workspaceOf } from './shared.ts'
 
-const COLUMN_PROFILE_SCHEMA = {
-  type: 'object',
-  properties: {
-    name: { type: 'string', required: true },
-    inferredType: { type: 'string', enum: ['number', 'date', 'boolean', 'string', 'empty', 'mixed'], required: true },
-    missing: { type: 'number', required: true },
-    missingRate: { type: 'number', required: true },
-    unique: { type: 'number', required: true },
-    numeric: {
-      type: 'object',
-      properties: {
-        min: { type: 'number', required: true },
-        max: { type: 'number', required: true },
-        mean: { type: 'number', required: true },
-        median: { type: 'number', required: true },
-        p25: { type: 'number', required: true },
-        p75: { type: 'number', required: true },
-        outliers: { type: 'number', required: true },
-      },
-      additionalProperties: false,
-    },
-    topValues: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          value: { type: 'string', required: true },
-          count: { type: 'number', required: true },
-        },
-        additionalProperties: false,
-      },
-    },
-    notes: { type: 'array', items: { type: 'string' }, required: true },
-  },
-  additionalProperties: false,
-} as const
-
 /**
  * Build the `data_profile` tool definition against a mounted service.
  * @param service - the mounted ctx.dataQuality implementation.
@@ -56,35 +20,23 @@ export function defineProfileTool(service: DataQualityService) {
     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: { type: 'string', required: true, description: 'Workspace-relative dataset path (.csv/.tsv/.json/.jsonl). JSON datasets must be an array of flat objects.' },
       sample: { type: 'number', description: 'Optional systematic sample size (every ceil(N/sample)-th row) for the column cards; row counts stay exact.' },
+      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,
-      },
-      render: (_args, value) => [{ type: 'text', text: renderProfileText(value) }],
+      schema: PROFILE_REPORT_SCHEMA,
+      render: (_args, value) => [{ type: 'text', text: renderProfileText(value as unknown as ProfileReport) }],
     },
     async execute(args, exec) {
       return service.profileDataset({
         dataset: args.path,
         sample: args.sample,
+        ...(args.industryPreset !== undefined ? { industryPreset: args.industryPreset } : {}),
         workspace: workspaceOf(exec),
         session: exec.agent?.session,
         signal: exec.signal,

package/src/tools/report.ts

@@ -0,0 +1,108 @@
+/**
+ * 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
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { DataQualityService } from '../service.ts'
+import type { ReportRecord, StoredReport } from '../store.ts'
+
+/** The report kinds a caller may query. */
+const REPORT_KINDS = ['profile', 'clean', 'clean-diff', 'verify', 'citations'] as const
+
+/** One stored report projected into the model-facing canonical value (report as lossless JSON). */
+interface ReportView {
+  readonly key: string
+  readonly kind: ReportRecord['kind']
+  readonly at: number
+  readonly dataset: string
+  readonly report: JsonValue
+}
+
+/** The canonical value the tool returns. */
+interface DataReportValue {
+  readonly key?: string
+  readonly kind?: ReportRecord['kind']
+  readonly records: ReportView[]
+}
+
+/** Project a stored report into the canonical value (the stored report is already lossless JSON). */
+function toView(record: StoredReport): ReportView {
+  return { key: record.key, kind: record.kind, at: record.at, dataset: record.dataset, report: record.report as unknown as JsonValue }
+}
+
+/** Human-readable report summary for the tool's Native render. */
+function renderReportText(value: DataReportValue): string {
+  const lines: string[] = []
+  if (value.key !== undefined) {
+    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.
+ */
+export function defineReportTool(service: DataQualityService) {
+  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).' },
+    },
+    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,
+          },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => [{ type: 'text', text: renderReportText(value as unknown as DataReportValue) }],
+    },
+    async execute(args, _exec): Promise<DataReportValue> {
+      const hasKey = args.key !== undefined
+      const hasKind = args.kind !== undefined
+      if (hasKey === hasKind) {
+        throw new Error('data_report needs exactly one of key/kind')
+      }
+      if (hasKey) {
+        const record = await service.getReport(args.key as string)
+        return { key: args.key as string, records: [toView(record)] }
+      }
+      const records = await service.listReports(args.kind as ReportRecord['kind'])
+      return { kind: args.kind as ReportRecord['kind'], records: records.map(toView) }
+    },
+  })
+}

package/src/tools/shared.ts

@@ -27,11 +27,30 @@ export function workspaceOf(exec: ToolExecution): string {
 /** Human-readable cleaning summary for the tool's Native render. */
 export function renderCleanText(report: CleanRunReport): string {
   const lines: string[] = []
-  lines.push(`Cleaned ${report.dataset}: ${report.inputRows} -> ${report.outputRows} rows over ${report.logs.length} rule(s)`)
+  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}`)
   }
-  if (report.outputPath !== undefined) {
+  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 !== undefined) {
+    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 !== undefined) {
     lines.push(`Wrote cleaned dataset to ${report.outputPath}`)
   } else {
     lines.push('No outputPath given: the source file was left untouched; preview below.')

package/src/tools/verify.ts

@@ -6,10 +6,44 @@
  */
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { DataQualityService, VerifyRule } from '../service.ts'
+import type { DataQualityService, VerifyExpectation, VerifyRule } from '../service.ts'
 import { renderVerifyText, type VerifyReport } from '../verify.ts'
 import { workspaceOf } from './shared.ts'
 
+const EXPECTATION_METRICS = ['rowCount', 'columnSum', 'columnMean', 'uniqueCount', 'nullCount'] as const
+
+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.',
+} as const
+
+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,
+  },
+} as const
+
 const VERIFY_RULE_SCHEMA = {
   type: 'array',
   items: {
@@ -103,11 +137,13 @@ export function defineVerifyTool(service: DataQualityService) {
     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: { type: 'string', required: true, description: 'Workspace-relative dataset path (.csv/.tsv/.json/.jsonl).' },
       rules: { ...VERIFY_RULE_SCHEMA, required: true },
+      expectations: { ...EXPECTATION_SCHEMA, description: 'Optional metric expectations to reconcile (rowCount/columnSum/columnMean/uniqueCount/nullCount).' },
     },
     output: {
       schema: {
@@ -145,6 +181,7 @@ export function defineVerifyTool(service: DataQualityService) {
             },
             required: true,
           },
+          expectations: { ...EXPECTATION_RESULT_SCHEMA, required: true },
         },
         additionalProperties: false,
       },
@@ -154,6 +191,7 @@ export function defineVerifyTool(service: DataQualityService) {
       return service.verifyDataset({
         dataset: args.path,
         rules: args.rules as unknown as readonly VerifyRule[],
+        ...(args.expectations !== undefined ? { expectations: args.expectations as unknown as readonly VerifyExpectation[] } : {}),
         workspace: workspaceOf(exec),
         session: exec.agent?.session,
         signal: exec.signal,

package/src/verify.ts

@@ -41,6 +41,45 @@ export class VerifyRuleError extends Error {
   }
 }
 
+/** The metrics a verification expectation can reconcile. */
+export type VerifyMetric = 'rowCount' | 'columnSum' | 'columnMean' | 'uniqueCount' | 'nullCount'
+
+/** One metric expectation: an expected value plus an optional relative tolerance. */
+export interface VerifyExpectation {
+  readonly metric: VerifyMetric
+  /** Required for every metric except `rowCount`. */
+  readonly column?: string
+  readonly expected: number
+  /** Optional relative tolerance in [0, 1]; falls back to the configured `defaultTolerance`. */
+  readonly tolerance?: number
+}
+
+/** One expectation's reconciliation outcome. */
+export interface VerifyExpectationResult {
+  readonly metric: VerifyMetric
+  /** Absent for `rowCount`. */
+  readonly column?: string
+  readonly expected: number
+  readonly actual: number
+  readonly tolerance: number
+  readonly passed: boolean
+}
+
+/** Raised for invalid expectations; `message` names the expectation index and reason. */
+export class VerifyExpectationError extends Error {
+  /**
+   * @param expectationIndex - index of the offending expectation in the request array.
+   * @param message - actionable human-readable detail.
+   */
+  constructor(
+    readonly expectationIndex: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'VerifyExpectationError'
+  }
+}
+
 /** One failing row's evidence (capped per rule by `evidenceRowLimit`). */
 export interface VerifyEvidenceRow {
   /** 0-based data row index. */
@@ -68,6 +107,8 @@ export interface VerifyReport {
   readonly passed: boolean
   readonly rowCount: number
   readonly rules: VerifyRuleResult[]
+  /** Metric-reconciliation outcomes (empty when no expectations were given). */
+  readonly expectations: VerifyExpectationResult[]
   /** Storage-domain key of the persisted report, when persistence is on (set by the provider). */
   readonly reportKey?: string
   /** Injected generation timestamp (epoch ms). */
@@ -123,19 +164,118 @@ function evaluate(
 
 const CROSS_OPS = ['<', '<=', '==', '!=', '>=', '>'] as const
 
+/** The metric ids, for validation and diagnostics. */
+const VERIFY_METRICS = ['rowCount', 'columnSum', 'columnMean', 'uniqueCount', 'nullCount'] as const
+
+/** Throw unless the expectation is well-formed (metric/column/tolerance). */
+function validateExpectation(table: Table, expectation: VerifyExpectation, index: number): void {
+  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 === undefined || 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 !== undefined) {
+    throw new VerifyExpectationError(index, `expectation ${index}: metric rowCount takes no column, got ${JSON.stringify(expectation.column)}`)
+  }
+  if (expectation.tolerance !== undefined && (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: Table, expectation: VerifyExpectation): number {
+  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 as string])) count += 1
+      }
+      return count
+    }
+    case 'uniqueCount': {
+      const distinct = new Set<string>()
+      for (const row of table.rows) {
+        const cell = row[expectation.column as string]
+        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 as string])
+        if (value === undefined) 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.
+ */
+export function verifyExpectations(
+  table: Table,
+  expectations: readonly VerifyExpectation[],
+  defaultTolerance: number,
+  signal?: AbortSignal,
+): VerifyExpectationResult[] {
+  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 !== undefined ? { 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).
  */
 export function verifyTable(
   table: Table,
   rules: readonly VerifyRule[],
-  options: { evidenceRowLimit: number; now: () => number; signal?: AbortSignal | undefined },
+  options: {
+    evidenceRowLimit: number
+    now: () => number
+    signal?: AbortSignal | undefined
+    expectations?: readonly VerifyExpectation[] | undefined
+    defaultTolerance?: number | undefined
+  },
 ): Omit<VerifyReport, 'dataset'> {
   if (rules.length === 0) {
     throw new VerifyRuleError(0, 'rules must be a non-empty array')
@@ -332,10 +472,12 @@ export function verifyTable(
     }
     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(),
   }
 }
@@ -354,6 +496,10 @@ export function renderVerifyText(report: VerifyReport): string {
       lines.push(`    … and ${rule.failedCount - rule.evidence.length} more failing row(s)`)
     }
   }
+  for (const expectation of report.expectations) {
+    const target = expectation.column !== undefined ? `${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')
 }
 

package/src/version.ts

@@ -5,4 +5,4 @@
  */
 
 /** The package version reported in persisted reports. */
-export const VERSION = '0.1.2'
+export const VERSION = '0.2.0'