dsh-data-quality 0.1.3 → 0.3.0

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,

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

@@ -0,0 +1,98 @@
+/**
+ * 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: {
+    schemaVersion: { type: 'number', required: true },
+    dataset: { type: 'string', required: true },
+    rowCount: { type: 'number', required: true },
+    sampled: { type: 'boolean', required: true },
+    profiledRows: { type: 'number', required: true },
+    columnCount: { type: 'number', required: true },
+    duplicateRows: { type: 'number', required: true },
+    duplicateRate: { type: 'number', required: true },
+    duplicateSampleRowIndexes: { type: 'array', items: { type: 'number' }, required: true },
+    scorecard: {
+      type: 'object',
+      properties: {
+        overall: { oneOf: [{ type: 'number' }, { type: 'null' }], required: true },
+        weightedOverall: { oneOf: [{ type: 'number' }, { type: 'null' }], required: true },
+        dimensions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', enum: [...SCORECARD_DIMENSION_NAMES], required: true },
+              score: { oneOf: [{ type: 'number' }, { type: 'null' }], required: true },
+              note: { type: 'string', required: true },
+            },
+            additionalProperties: false,
+          },
+          required: true,
+        },
+      },
+      additionalProperties: false,
+      required: true,
+    },
+    encoding: {
+      type: 'object',
+      properties: {
+        bom: { oneOf: [{ type: 'string' }, { type: 'null' }], required: true },
+        validUtf8: { type: 'boolean', required: true },
+      },
+      additionalProperties: false,
+    },
+    generatedAt: { type: 'number', required: true },
+    reportKey: { type: 'string' },
+    columns: { type: 'array', items: COLUMN_PROFILE_SCHEMA, required: true },
+  },
+  additionalProperties: false,
+} 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,137 @@
+/**
+ * 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 { ProfileReport } from '../profile.ts'
+import { renderCleanHtml, renderProfileHtml, type CleanReportHtml } from '../report-html.ts'
+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[]
+  /** Self-contained offline HTML (present only when `format: html`). */
+  readonly html?: string
+}
+
+/** Render one stored report as a self-contained HTML document (profile/clean only). */
+function renderRecordHtml(record: StoredReport): string {
+  if (record.kind === 'profile') {
+    return renderProfileHtml(record.report as unknown as ProfileReport)
+  }
+  if (record.kind === 'clean' || record.kind === 'clean-diff') {
+    return renderCleanHtml(record.report as unknown as CleanReportHtml, record.dataset)
+  }
+  throw new Error(`data_report html format does not support kind "${record.kind}" (profile/clean only)`)
+}
+
+/** Project a stored report into the canonical value (the stored report is already lossless JSON). */
+function toView(record: 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).' },
+      format: { type: 'string', enum: ['json', 'html'], description: 'Output format. json (default) returns the report envelope(s); html renders one report as a self-contained offline HTML document (requires key; profile/clean only).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          key: { type: 'string' },
+          kind: { type: 'string', enum: [...REPORT_KINDS] },
+          records: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                key: { type: 'string', required: true },
+                kind: { type: 'string', enum: [...REPORT_KINDS], required: true },
+                at: { type: 'number', required: true },
+                dataset: { type: 'string', required: true },
+                report: { type: 'json', required: true },
+              },
+              additionalProperties: false,
+            },
+            required: true,
+          },
+          html: { type: 'string', description: 'Self-contained offline HTML (present only when format: html).' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const view = value as unknown as DataReportValue
+        if (view.html !== undefined) return [{ type: 'text', text: view.html }]
+        return [{ type: 'text', text: renderReportText(view) }]
+      },
+    },
+    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')
+      }
+      const format = (args.format ?? 'json') as 'json' | 'html'
+      if (hasKey) {
+        const record = await service.getReport(args.key as string)
+        return {
+          key: args.key as string,
+          records: [toView(record)],
+          ...(format === 'html' ? { html: renderRecordHtml(record) } : {}),
+        }
+      }
+      if (format === 'html') {
+        throw new Error('data_report html format requires key (exactly one report)')
+      }
+      const records = await service.listReports(args.kind 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,