/** * 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; } 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; }