0pt/src/quality/quality-types.ts

/**
 * src/quality/quality-types.ts
 * =============================
 * Types for 0pt's Data Quality capability (Master-DoD §10 Data quality:
 * rule registry, runs, results, issues, scores, trend, rule versioning,
 * product-supplied rules).
 *
 * IMPORTANT HISTORY: this repo once carried FABRICATED claims that a
 * quality-check service existed (see CLAUDE.md + docs/P0_DATASET_QUALITY_FLOW.md,
 * which is the explicit target spec). THIS module is the first real
 * implementation — anything it cannot do is stated, not implied.
 *
 * Expectations are serialized in Great Expectations' canonical JSON shape
 * (`expectation_type` + `kwargs`) so a rule authored here can be executed
 * verbatim by a GE backend (0pt-motor's Python engine, Master-DoD §11 DQ)
 * AND by the local TypeScript engine for the supported core subset. The GE
 * suite is the interchange format; the local engine is honest about which
 * expectation types it supports (unsupported ⇒ must delegate, never fake).
 */

/** GE-compatible expectation (interchange shape). */
export interface QualityExpectation {
  /** Great Expectations expectation type, e.g. "expect_column_values_to_not_be_null". */
  expectation_type: string;
  kwargs: Record<string, unknown>;
}

export type QualitySeverity = "info" | "warning" | "error" | "critical";

export interface DataQualityRule {
  rule_id: string;
  tenant_id: string;
  project_id: string;
  /** Dataset the rule targets; product-supplied rules set their own dataset ids. */
  dataset_id: string;
  name: string;
  expectation: QualityExpectation;
  severity: QualitySeverity;
  /** Monotonic rule version — bumped on every mutation (§10 rule versioning). */
  version: number;
  status: "active" | "disabled" | "superseded";
  /** Which product supplied the rule ("0pt" | "vehiq" | ...). */
  supplied_by: string;
  created_at: string;
  updated_at?: string;
}

export interface CreateQualityRuleInput {
  rule_id: string;
  tenant_id: string;
  project_id: string;
  dataset_id: string;
  name: string;
  expectation: QualityExpectation;
  severity?: QualitySeverity;
  supplied_by?: string;
}

/** One executed expectation within a run. */
export interface DataQualityResult {
  rule_id: string;
  rule_version: number;
  success: boolean;
  /** Fraction of evaluated rows/elements that passed (1 for table-level checks that pass). */
  pass_ratio: number;
  evaluated_count: number;
  unexpected_count: number;
  /** Up to 20 sample unexpected values (never full rows — PII minimization). */
  unexpected_samples: unknown[];
  /** Engine that executed the expectation. */
  executed_by: "0pt-local" | "great_expectations";
}

/** An issue opened for a failed rule (human-review handoff). */
export interface DataQualityIssue {
  issue_id: string;
  run_id: string;
  rule_id: string;
  rule_version: number;
  tenant_id: string;
  dataset_id: string;
  severity: QualitySeverity;
  status: "open" | "acknowledged" | "resolved" | "wont_fix";
  summary: string;
  created_at: string;
}

export type QualityRunStatus = "running" | "succeeded" | "failed" | "delegated";

export interface DataQualityRun {
  run_id: string;
  tenant_id: string;
  project_id: string;
  dataset_id: string;
  /** Dataset version under test, when versioned. */
  dataset_version?: number;
  status: QualityRunStatus;
  results: DataQualityResult[];
  /** Overall score 0..100 (severity-weighted pass ratio). */
  score?: number;
  started_at: string;
  finished_at?: string;
  correlation_id?: string;
  /** N0D job id when execution was delegated to the GE backend. */
  delegated_job_id?: string;
}

/** One point of the §10 trend series. */
export interface QualityTrendPoint {
  run_id: string;
  dataset_id: string;
  score: number;
  finished_at: string;
}