dsh-data-quality 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-19
+
+### Added
+
+- The `ctx.dataQuality` capability seam (Service Definition / local deterministic Provider / tool Consumers) with the frozen cross-plugin `verifyCitations(request)` contract for document-number ↔ dataset checks (verified / mismatch / not-found / unverifiable, relative-tolerance numeric comparison).
+- `data_profile` tool: deterministic dataset profiling (row/column counts, inferred types, missing rates, unique counts, numeric distributions, IQR outliers, mixed-type notes, duplicate-row counts) over workspace CSV/TSV/JSON/JSONL, with optional systematic sampling.
+- `data_clean` tool: ordered declarative cleaning rules (`dedupe`, `fill-missing`, `coerce-type`, `normalize-unit`, `trim`, `map-values`) with a per-rule audit log; the source file is never overwritten and cleaned output writes only inside the workspace.
+- `data_verify` tool: declarative verification rules (`not-null`, `unique`, `range`, `regex`, `enum`, `cross-column`, `freshness`) with capped failing-row evidence; overall failure is a normal `passed: false` result, never a tool error.
+- Durable report persistence to the `data_quality` storage domain (keyed by run timestamp + dataset fingerprint), adaptive `data-quality/profile|clean|verify` session events on hosts that can carry them safely, fail-loud Schemastery config, and workspace-confined path resolution (escape + extension + size + row guards).

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.es.md

@@ -0,0 +1,181 @@
+# dsh-data-quality
+
+**Perfilado, limpieza y verificación de datos deterministas para DeepSeek Harness.**
+
+Todo el cálculo es TypeScript puro dentro del proceso del harness — el modelo nunca hace las cuentas. Una costura de capacidad `ctx.dataQuality` (Service Definition / Provider local / Consumers de herramientas) expone tres herramientas para el modelo más un contrato congelado de verificación de citas entre plugins.
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+## Compatibility
+
+| Componente | Versión |
+|---|---|
+| DeepSeek Harness | `0.1.0-rc.6` (dependencias peer fijadas) |
+| Node.js | `^22.19.0 \|\| >=24.0.0` |
+| Gestor de paquetes | `pnpm@11.7.0` |
+| Plataforma | Windows / macOS / Linux (plugin solo de host) |
+
+## What you get
+
+- **Servicio `ctx.dataQuality`** — un servicio Cordis que otros plugins pueden consumir opcionalmente (`inject = ['dataQuality']`). Además de las tres operaciones sobre datasets detrás de las herramientas, implementa el contrato congelado `verifyCitations(request)`: verifica que los números/cadenas citados en un documento coincidan con una instantánea del dataset, con comparación numérica por tolerancia relativa y estados `verified` / `mismatch` / `not-found` / `unverifiable`.
+- **Herramienta `data_profile`** — perfilado de datasets: conteos de filas/columnas, tipos de columna inferidos (number/date/boolean/string/empty/mixed), tasas de valores faltantes, conteos de valores únicos, distribuciones numéricas (min/max/mean/median/p25/p75), conteo de valores atípicos IQR, notas de sospecha por tipos mixtos y conteo de filas duplicadas de la tabla completa. Muestreo sistemático determinista opcional para archivos grandes.
+- **Herramienta `data_clean`** — reglas declarativas de limpieza en orden: `dedupe` (por grupo de columnas), `fill-missing` (constant/mean/median/forward), `coerce-type` (number/date/boolean; los fallos se cuentan y quedan como faltantes), `normalize-unit` (p. ej. sufijos 万/亿 a unidades base), `trim`, `map-values` (mapeo de enumeraciones). Devuelve un registro de auditoría por regla más una vista previa acotada; solo escribe el dataset limpio cuando se indica `outputPath` y nunca sobrescribe el origen.
+- **Herramienta `data_verify`** — reglas declarativas de verificación: `not-null`, `unique`, `range`, `regex`, `enum`, `cross-column` (p. ej. `startDate < endDate`), `freshness` (columna de fecha dentro de N días de una fecha de referencia). pass/fail por regla con evidencia acotada de filas fallidas; un fallo global es un resultado normal `passed: false`, no un error de herramienta.
+- **Informes duraderos** — cada ejecución de perfilado/limpieza/verificación/citas persiste en el dominio de almacenamiento `data_quality` (backend JSON), con clave de marca de tiempo más huella de la ruta del dataset; la clave se devuelve como `reportKey` en los resultados.
+- **Eventos de sesión** — en hosts que los soportan con seguridad, las ejecuciones añaden eventos `data-quality/profile` / `data-quality/clean` / `data-quality/verify` (con la marca `ignorable` donde se admite). En 0.1.0-rc.6 el append se omite por diseño — el informe del dominio de almacenamiento es siempre la copia duradera (véase «Known limitations»).
+
+## Quick start
+
+### Canal npm
+
+```sh
+dsh plugin --profile web add dsh-data-quality
+```
+
+### Canal tarball (no requiere permiso de compilación)
+
+```sh
+pnpm pack                                  # produce dsh-data-quality-<version>.tgz
+dsh plugin --profile web add ./dsh-data-quality-<version>.tgz
+```
+
+### Canal git
+
+```sh
+dsh plugin --profile web add github:YOUR_ORG/dsh-data-quality#<commit-sha>
+```
+
+El primer `add` falla porque pnpm bloquea la compilación `prepare` del paquete; copia la clave exacta que pnpm imprimió en el `pnpm-workspace.yaml` del perfil y vuelve a ejecutar:
+
+```yaml
+allowBuilds:
+  'dsh-data-quality': true
+```
+
+Reinicia el perfil tras instalar (los bundles se activan al reiniciar). Luego pide al agente, en un workspace que contenga un CSV:
+
+> Perfila `holdings.csv`, luego límpialo recortando espacios, deduplicando por `fund_code` y normalizando las unidades 万/亿 de la columna `holding_value`; finalmente verifica que `fund_code` sea único y no nulo.
+
+## Install & uninstall
+
+```sh
+dsh plugin --profile web add dsh-data-quality      # instalar (npm) — o las formas anteriores
+dsh plugin --profile web remove dsh-data-quality   # desinstalar
+```
+
+## Configuration
+
+Todas las claves son opcionales (se muestran los valores por defecto); los valores inválidos fallan ruidosamente al cargar. Cada clave se puede cambiar desde `cordis.yml` (el bundle incluye `cordis.patch.yml` con los mismos valores).
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Interruptor maestro; `false` no monta nada. |
+| `maxRows` | `200000` | Tope duro de filas por carga; entradas mayores se rechazan ruidosamente (usa el parámetro `sample` de la herramienta). |
+| `maxFileSizeMB` | `64` | Tope duro de tamaño de archivo en MiB por carga. |
+| `defaultTolerance` | `1e-9` | Tolerancia relativa por defecto para la comparación numérica de citas cuando la cita omite `tolerance`. |
+| `evidenceRowLimit` | `20` | Tope de filas de evidencia (verify) y de vista previa (clean) en un resultado. |
+| `allowedExtensions` | `['.csv', '.tsv', '.json', '.jsonl']` | Extensiones aceptadas como datasets. |
+| `workspaceRoot` | `""` | Raíz absoluta para llamadas a nivel de SERVICIO (p. ej. `verifyCitations`) sin workspace de sesión; vacío = directorio de arranque del proceso del harness. Las herramientas siempre usan el cwd del workspace de la sesión. |
+| `storeReports` | `true` | Persistir los informes en el dominio de almacenamiento `data_quality` y devolver `reportKey`. |
+
+## Tools & surfaces
+
+### `data_profile({ path, sample? })`
+
+Perfila un dataset del workspace. `path` es relativo al workspace (`.csv`/`.tsv`/`.json`/`.jsonl`; JSON debe ser un array de objetos planos). `sample` toma cada `ceil(N/sample)`-ésima fila para las tarjetas de columna (determinista; los conteos de filas siguen siendo exactos). Devuelve el informe estructurado y renderiza un resumen legible por columna.
+
+### `data_clean({ path, rules, outputPath? })`
+
+Aplica `rules` en orden de array; cada regla ve la salida de la anterior. Referencia de reglas:
+
+| Regla | Campos extra | Semántica |
+|---|---|---|
+| `dedupe` | `columns?` | Elimina filas cuya combinación de columnas clave duplica una fila anterior (se conserva la primera; todas las columnas si se omite). |
+| `fill-missing` | `column`, `strategy`, `value?` | Rellena faltantes: `constant` (requiere `value`), `mean`/`median` (columnas numéricas), `forward` (valor anterior no faltante). |
+| `coerce-type` | `column`, `to` | Convierte a `number`/`date` (ISO)/`boolean`; los fallos quedan como faltantes y se cuentan. |
+| `normalize-unit` | `column`, `factors` | Quita el sufijo de unidad y multiplica (`{"万": 10000, "亿": 100000000}`); los numéricos planos también se convierten. |
+| `trim` | `columns?` | Recorta espacios en celdas de texto (todas las columnas si se omite). |
+| `map-values` | `column`, `map`, `else?` | Mapeo por coincidencia exacta; los valores no mapeados se conservan (`keep`, por defecto) o quedan `missing`. |
+
+El archivo de origen **nunca** se sobrescribe. Con `outputPath` el dataset limpio se escribe allí (confinado al workspace, formato por extensión); sin él la ejecución es solo vista previa.
+
+### `data_verify({ path, rules })`
+
+Evalúa reglas de verificación. Referencia de reglas:
+
+| Regla | Campos extra | Semántica |
+|---|---|---|
+| `not-null` | `column` | Fallan las celdas faltantes (null/vacío/solo espacios). |
+| `unique` | `columns` | Falla cada fila cuya combinación clave se repite (los faltantes participan). |
+| `range` | `column`, `min?`, `max?` | Fallan celdas faltantes/no parseables y valores fuera de los límites inclusivos (se requiere al menos un límite). |
+| `regex` | `column`, `pattern`, `flags?` | Fallan celdas faltantes o que no coinciden (regex JS completa). |
+| `enum` | `column`, `values` | Fallan celdas cuyo texto recortado no está en la lista. |
+| `cross-column` | `left`, `op`, `rightColumn?`, `value?` | Compara por fila: numérico si ambos lados parsean, fechas como épocas, cadenas solo para `==`/`!=` (exactamente uno de `rightColumn`/`value`). |
+| `freshness` | `column`, `maxAgeDays`, `asOf?` | Fallan fechas más viejas que `maxAgeDays` antes de `asOf` (por defecto: ahora); no parseable/faltante falla. |
+
+Una celda faltante hace fallar toda regla que la lee. La evidencia se limita a `evidenceRowLimit` filas fallidas por regla.
+
+### `ctx.dataQuality` (para otros plugins)
+
+```ts
+const result = await ctx.dataQuality.verifyCitations({
+  dataset: 'holdings.csv',          // se resuelve contra workspaceRoot
+  citations: [
+    { id: 'c1', path: 'rows[3].nav', value: 1.234, tolerance: 0.01 },
+    { id: 'c2', path: 'summary.annualReturn', value: '12.34%' },
+  ],
+})
+// result.results[i] = { id, status: 'verified' | 'mismatch' | 'not-found' | 'unverifiable', actual?, note? }
+```
+
+Los localizadores recorren el documento del dataset: CSV/TSV cargan como `{ columns, rows }` (así `rows[3].nav` resuelve), JSON es el valor parseado, JSONL el array de líneas parseadas. Los números comparan con tolerancia relativa (`|a-b| <= tolerance * max(|a|, |b|)`); una celda de texto CSV que parsea numéricamente compara como número; las cadenas comparan exactas; los pares de tipos incomparables son `unverifiable`. El servicio también expone `profileDataset` / `cleanDataset` / `verifyDataset` (las mismas operaciones que llaman las herramientas).
+
+## Permissions & data
+
+- **Lee** archivos de dataset del workspace (solo extensiones permitidas).
+- **Escribe** solo: el archivo de salida de `data_clean` (`outputPath` explícito, confinado al workspace, nunca la entrada) y los informes del dominio de almacenamiento `data_quality` en el directorio de datos del harness.
+- **Sin red, sin credenciales, sin procesos externos** — todo el parseo y la estadística son TypeScript en proceso.
+- Los informes pueden contener valores de celda de muestra de tus datasets (acotados por `evidenceRowLimit` y el truncado de presentación); el registro de sesión registra argumentos y resultados de herramientas como siempre.
+
+## Security boundaries
+
+- **Confinamiento de rutas** — las rutas de dataset y salida deben resolverse dentro del workspace de sesión (`verifyCitations` usa `workspaceRoot`); se rechazan escapes `..` y rutas absolutas fuera de la raíz, y ambos lados se normalizan antes de comparar (seguro con barras de Windows).
+- **Trabajo acotado** — las guardas `maxRows` / `maxFileSizeMB` rechazan entradas sobredimensionadas ruidosamente; las señales de aborto cancelan cargas largas a mitad de camino.
+- **Sin sobrescritura** — `data_clean` rechaza un `outputPath` igual a la ruta de entrada.
+- **Cálculo determinista** — misma entrada, misma salida; el único reloj es el inyectado para los valores por defecto de `freshness` y las marcas de tiempo de informes.
+
+## Known limitations
+
+- **Los eventos de sesión son adaptativos.** 0.1.0-rc.6 no tiene superficie de registro de eventos de sesión para plugins y su `Session.append` no puede estampar la marca `ignorable`, así que añadir un tipo `data-quality/*` desconocido haría ilegible el registro de sesión al restaurarlo. Por eso el plugin solo añade cuando el host conoce el vocabulario o soporta el flag `ignorable`; en rc.6 el informe del dominio de almacenamiento es el registro duradero.
+- **Dialecto CSV** — coma/tab con comillas RFC-4180, fila de cabecera obligatoria, líneas en blanco omitidas; sin autodetección de delimitador ni líneas de comentario.
+- **El parseo de tipos es estricto** — los números no llevan separadores de miles; las fechas son `YYYY-MM-DD` / `YYYY/MM/DD` / datetimes estilo ISO (UTC); los booleanos son `true/false/yes/no/1/0`. Todo lo demás se perfila como `string`/`mixed` — límpialo con `coerce-type` si es intencionado.
+- **JSON debe ser tabular para las herramientas** (array de objetos planos); `verifyCitations` recorre documentos JSON arbitrarios.
+- **Sin detección de anomalías por ML, sin enmascarado de PII, sin bases de datos, sin SQL** — solo notas de sospecha basadas en reglas.
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build
+pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm run verify:readme-sync && pnpm pack
+```
+
+- Las pruebas ejecutan vitest contra los `Context`/`Session`/`ToolRuntime`/dominio de almacenamiento REALES de los peers 0.1.0-rc.6 (sin mocks de servicios escritos a mano) más specs de motor puros; cada regla de limpieza/verificación tiene casos positivos y negativos, y `verifyCitations` cubre los cuatro estados.
+- `scripts/loader-runner.mjs` arranca la composición real del Loader y ejecuta la cadena perfilar → limpiar → verificar contra `fixtures/` sin clave de API.
+- Release: `node scripts/release.mjs <x.y.z>` (nunca hace push; el tag dispara `release.yml`).
+
+## Topics
+
+`dsh` · `dsh-plugin` · `deepseek-harness` · `cordis` · `data-quality` · `data-cleaning` · `data-profiling` · `data-verification`
+
+## Contributors
+
+Mantenido por los contribuidores de dsh-data-quality. Issues y pull requests son bienvenidos cuando el repositorio sea público.
+
+## PerryLink DSH Plugin Family
+
+Este plugin sigue las convenciones de ingeniería compartidas de la familia DSH: empaquetado con manifiesto bundle (`dsh.bundle` + `cordis.patch.yml`), READMEs en cinco idiomas con verificación de sincronía, configuración Schemastery de fallo ruidoso, cobertura vitest con servicios reales y la cadena de tres flujos CI/compat/release.
+
+## License
+
+Apache-2.0 — véase [LICENSE](LICENSE) y [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/README.hi.md

@@ -0,0 +1,181 @@
+# dsh-data-quality
+
+**DeepSeek Harness के लिए निर्धारणात्मक (deterministic) डेटा प्रोफ़ाइलिंग, क्लीनिंग और सत्यापन।**
+
+सारी गणना harness प्रक्रिया के अंदर शुद्ध TypeScript है — मॉडल कभी हिसाब नहीं करता। `ctx.dataQuality` क्षमता सीम (Service Definition / लोकल Provider / टूल Consumer) तीन मॉडल टूल और एक जमे हुए क्रॉस-प्लगिन उद्धरण सत्यापन अनुबंध को उजागर करती है।
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+## Compatibility
+
+| घटक | संस्करण |
+|---|---|
+| DeepSeek Harness | `0.1.0-rc.6` (peer dependencies पिन) |
+| Node.js | `^22.19.0 \|\| >=24.0.0` |
+| पैकेज मैनेजर | `pnpm@11.7.0` |
+| प्लेटफ़ॉर्म | Windows / macOS / Linux (केवल होस्ट प्लगिन) |
+
+## What you get
+
+- **`ctx.dataQuality` सेवा** — एक Cordis सेवा जिसे अन्य प्लगिन वैकल्पिक रूप से उपभोग कर सकते हैं (`inject = ['dataQuality']`)। टूल्स के पीछे की तीन डेटासेट क्रियाओं के अलावा, यह जमा हुआ `verifyCitations(request)` अनुबंध लागू करती है: दस्तावेज़ में उद्धृत संख्याएँ/स्ट्रिंग डेटासेट स्नैपशॉट से मेल खाती हैं या नहीं — सापेक्ष सहिष्णुता संख्यात्मक तुलना और `verified` / `mismatch` / `not-found` / `unverifiable` स्थितियों के साथ।
+- **`data_profile` टूल** — डेटासेट प्रोफ़ाइलिंग: पंक्ति/स्तंभ गिनती, अनुमानित स्तंभ प्रकार (number/date/boolean/string/empty/mixed), अनुपस्थिति दर, अद्वितीय मान संख्या, संख्यात्मक वितरण (min/max/mean/median/p25/p75), IQR आउटलायर गिनती, मिश्रित-प्रकार संदेह टिप्पणियाँ, और पूरी तालिका की डुप्लिकेट पंक्ति गिनती। बड़ी फ़ाइलों के लिए वैकल्पिक निर्धारणात्मक व्यवस्थित प्रतिचयन।
+- **`data_clean` टूल** — क्रमबद्ध घोषणात्मक क्लीनिंग नियम: `dedupe` (स्तंभ समूह से), `fill-missing` (constant/mean/median/forward), `coerce-type` (number/date/boolean; विफलताएँ गिनी जाती हैं और अनुपस्थित बन जाती हैं), `normalize-unit` (जैसे 万/亿 प्रत्यय को आधार इकाई में), `trim`, `map-values` (एनुम मैपिंग)। प्रति-नियम ऑडिट लॉग और सीमित पूर्वावलोकन लौटाता है; केवल `outputPath` दिए जाने पर साफ़ डेटासेट लिखता है और मूल फ़ाइल को कभी अधिलेखित नहीं करता।
+- **`data_verify` टूल** — घोषणात्मक सत्यापन नियम: `not-null`, `unique`, `range`, `regex`, `enum`, `cross-column` (जैसे `startDate < endDate`), `freshness` (संदर्भ तिथि से N दिनों के भीतर तिथि स्तंभ)। प्रति-नियम pass/fail और सीमित असफल-पंक्ति साक्ष्य; समग्र असफलता सामान्य `passed: false` परिणाम है, टूल त्रुटि नहीं।
+- **टिकाऊ रिपोर्ट** — हर प्रोफ़ाइल/क्लीन/सत्यापन/उद्धरण रन `data_quality` स्टोरेज डोमेन (JSON बैकएंड) में सहेजा जाता है, कुंजी = रन टाइमस्टैम्प + डेटासेट-पथ फ़िंगरप्रिंट; कुंजी टूल परिणामों में `reportKey` के रूप में लौटती है।
+- **सत्र ईवेंट** — जिन होस्ट पर सुरक्षित रूप से संभव है, रन `data-quality/profile` / `data-quality/clean` / `data-quality/verify` ईवेंट जोड़ते हैं (जहाँ समर्थित हो वहाँ `ignorable` चिह्न सहित)। 0.1.0-rc.6 पर append जानबूझकर छोड़ा जाता है — स्टोरेज-डोमेन रिपोर्ट हमेशा टिकाऊ प्रति होती है (देखें «Known limitations»)।
+
+## Quick start
+
+### npm चैनल
+
+```sh
+dsh plugin --profile web add dsh-data-quality
+```
+
+### Tarball चैनल (बिल्ड अनुमति की ज़रूरत नहीं)
+
+```sh
+pnpm pack                                  # dsh-data-quality-<version>.tgz बनाता है
+dsh plugin --profile web add ./dsh-data-quality-<version>.tgz
+```
+
+### Git चैनल
+
+```sh
+dsh plugin --profile web add github:YOUR_ORG/dsh-data-quality#<commit-sha>
+```
+
+पहला `add` असफल होगा क्योंकि pnpm पैकेज का `prepare` बिल्ड रोकता है; pnpm द्वारा छपी सटीक कुंजी को प्रोफ़ाइल की `pnpm-workspace.yaml` में कॉपी करके फिर चलाएँ:
+
+```yaml
+allowBuilds:
+  'dsh-data-quality': true
+```
+
+इंस्टॉल के बाद प्रोफ़ाइल पुनः आरंभ करें (bundle पुनः आरंभ पर सक्रिय होते हैं)। फिर CSV वाले वर्कस्पेस में एजेंट से कहें:
+
+> `holdings.csv` को प्रोफ़ाइल करें, फिर व्हाइटस्पेस छाँटकर, `fund_code` पर डुप्लिकेट हटाकर और `holding_value` कॉलम की 万/亿 इकाइयाँ सामान्य करके क्लीन करें; अंत में सत्यापित करें कि `fund_code` अद्वितीय और गैर-रिक्त है।
+
+## Install & uninstall
+
+```sh
+dsh plugin --profile web add dsh-data-quality      # इंस्टॉल (npm) — या ऊपर के तरीके
+dsh plugin --profile web remove dsh-data-quality   # अनइंस्टॉल
+```
+
+## Configuration
+
+सभी कुंजियाँ वैकल्पिक हैं (डिफ़ॉल्ट दिखाए गए); अमान्य मान लोड समय पर ठोस रूप से असफल होते हैं। हर कुंजी `cordis.yml` से बदली जा सकती है (bundle में समान डिफ़ॉल्ट वाली `cordis.patch.yml` आती है)।
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `true` | मास्टर स्विच; `false` कुछ भी माउंट नहीं करता। |
+| `maxRows` | `200000` | प्रति लोड कठोर पंक्ति सीमा; बड़े इनपुट ठोस रूप से अस्वीकृत (टूल का `sample` पैरामीटर उपयोग करें)। |
+| `maxFileSizeMB` | `64` | प्रति लोड कठोर फ़ाइल-आकार सीमा (MiB)। |
+| `defaultTolerance` | `1e-9` | उद्धरण `tolerance` न दे तो संख्यात्मक तुलना की डिफ़ॉल्ट सापेक्ष सहिष्णुता। |
+| `evidenceRowLimit` | `20` | एक परिणाम में असफल-पंक्ति साक्ष्य (verify) और पूर्वावलोकन पंक्तियों (clean) की सीमा। |
+| `allowedExtensions` | `['.csv', '.tsv', '.json', '.jsonl']` | डेटासेट के रूप में स्वीकृत एक्सटेंशन। |
+| `workspaceRoot` | `""` | SERVICE-स्तरीय कॉल (जैसे `verifyCitations`) के लिए निरपेक्ष रूट जिनके पास सत्र वर्कस्पेस नहीं है; रिक्त = harness प्रक्रिया का आरंभ निर्देशिका। टूल कॉल हमेशा सत्र वर्कस्पेस cwd उपयोग करती हैं। |
+| `storeReports` | `true` | रन रिपोर्ट `data_quality` स्टोरेज डोमेन में सहेजें और `reportKey` लौटाएँ। |
+
+## Tools & surfaces
+
+### `data_profile({ path, sample? })`
+
+वर्कस्पेस डेटासेट प्रोफ़ाइल करता है। `path` वर्कस्पेस-सापेक्ष (`.csv`/`.tsv`/`.json`/`.jsonl`; JSON सपाट ऑब्जेक्ट की सरणी होनी चाहिए)। `sample` स्तंभ कार्ड के लिए हर `ceil(N/sample)`-वीं पंक्ति लेता है (निर्धारणात्मक; पंक्ति गिनती सटीक रहती है)। संरचित रिपोर्ट लौटाता है; मानव-पठनीय प्रति-स्तंभ सारांश रेंडर करता है।
+
+### `data_clean({ path, rules, outputPath? })`
+
+`rules` को सरणी क्रम में लागू करता है; हर नियम पिछले का आउटपुट देखता है। नियम संदर्भ:
+
+| नियम | अतिरिक्त फ़ील्ड | अर्थ |
+|---|---|---|
+| `dedupe` | `columns?` | कुंजी-स्तंभ संयोजन पिछली पंक्ति से डुप्लिकेट हो तो पंक्ति हटाएँ (पहली रखी जाती है; छोड़ने पर सभी स्तंभ)। |
+| `fill-missing` | `column`, `strategy`, `value?` | अनुपस्थित भरें: `constant` (`value` चाहिए), `mean`/`median` (संख्यात्मक स्तंभ), `forward` (पिछला गैर-अनुपस्थित)। |
+| `coerce-type` | `column`, `to` | `number`/`date` (ISO)/`boolean` में बदलें; विफलताएँ अनुपस्थित बनती हैं और गिनी जाती हैं। |
+| `normalize-unit` | `column`, `factors` | इकाई प्रत्यय हटाकर गुणा करें (`{"万": 10000, "亿": 100000000}`); साधारण संख्याएँ भी बदलती हैं। |
+| `trim` | `columns?` | स्ट्रिंग सेल की व्हाइटस्पेस छाँटें (छोड़ने पर सभी स्तंभ)। |
+| `map-values` | `column`, `map`, `else?` | सटीक-मिलान मैपिंग; अनमैप्ड मान रहते हैं (`keep`, डिफ़ॉल्ट) या `missing` बनते हैं। |
+
+मूल फ़ाइल **कभी** अधिलेखित नहीं होती। `outputPath` देने पर साफ़ डेटासेट वहाँ लिखा जाता है (वर्कस्पेस-सीमित, एक्सटेंशन से प्रारूप); बिना उसके रन केवल पूर्वावलोकन है।
+
+### `data_verify({ path, rules })`
+
+सत्यापन नियम मूल्यांकन करता है। नियम संदर्भ:
+
+| नियम | अतिरिक्त फ़ील्ड | अर्थ |
+|---|---|---|
+| `not-null` | `column` | अनुपस्थित सेल (null/रिक्त/केवल-व्हाइटस्पेस) असफल। |
+| `unique` | `columns` | जिन पंक्तियों का कुंजी संयोजन दोहरता है वे सब असफल (अनुपस्थित भी भाग लेता है)। |
+| `range` | `column`, `min?`, `max?` | अनुपस्थित/अपार्स योग्य सेल और समावेशी सीमा से बाहर मान असफल (कम से कम एक सीमा आवश्यक)। |
+| `regex` | `column`, `pattern`, `flags?` | अनुपस्थित या मेल न खाने वाली सेल असफल (पूर्ण JS regex)। |
+| `enum` | `column`, `values` | छँटा हुआ टेक्स्ट सूची में न हो तो असफल। |
+| `cross-column` | `left`, `op`, `rightColumn?`, `value?` | प्रति-पंक्ति तुलना: दोनों पार्स हों तो संख्यात्मक, तिथियाँ एपोक से, स्ट्रिंग केवल `==`/`!=` (`rightColumn`/`value` में से ठीक एक)। |
+| `freshness` | `column`, `maxAgeDays`, `asOf?` | `asOf` से `maxAgeDays` दिन पुरानी तिथियाँ असफल (डिफ़ॉल्ट: अभी); अपार्स योग्य/अनुपस्थित असफल। |
+
+अनुपस्थित सेल उसे पढ़ने वाले हर नियम को असफल करती है। साक्ष्य प्रति-नियम `evidenceRowLimit` असफल पंक्तियों तक सीमित है।
+
+### `ctx.dataQuality` (अन्य प्लगिन के लिए)
+
+```ts
+const result = await ctx.dataQuality.verifyCitations({
+  dataset: 'holdings.csv',          // workspaceRoot के विरुद्ध हल
+  citations: [
+    { id: 'c1', path: 'rows[3].nav', value: 1.234, tolerance: 0.01 },
+    { id: 'c2', path: 'summary.annualReturn', value: '12.34%' },
+  ],
+})
+// result.results[i] = { id, status: 'verified' | 'mismatch' | 'not-found' | 'unverifiable', actual?, note? }
+```
+
+लोकेटर डेटासेट दस्तावेज़ पर चलते हैं: CSV/TSV `{ columns, rows }` के रूप में लोड होते हैं (इसलिए `rows[3].nav` हल होता है), JSON पार्स किया गया मान है, JSONL पार्स की गई पंक्तियों की सरणी। संख्याएँ सापेक्ष सहिष्णुता से तुलना करती हैं (`|a-b| <= tolerance * max(|a|, |b|)`); संख्यात्मक रूप से पार्स होने वाली CSV स्ट्रिंग सेल संख्या की तरह तुलना करती है; स्ट्रिंग सटीक तुलना करती हैं; असंगत प्रकार-युग्म `unverifiable` हैं। सेवा `profileDataset` / `cleanDataset` / `verifyDataset` भी उजागर करती है (वही क्रियाएँ जो टूल कॉल करते हैं)।
+
+## Permissions & data
+
+- **पढ़ता है** वर्कस्पेस डेटासेट फ़ाइलें (केवल अनुमत एक्सटेंशन)।
+- **लिखता है** केवल: `data_clean` की आउटपुट फ़ाइल (स्पष्ट `outputPath`, वर्कस्पेस-सीमित, कभी इनपुट नहीं) और harness डेटा निर्देशिका के `data_quality` स्टोरेज डोमेन की रिपोर्ट।
+- **कोई नेटवर्क नहीं, कोई क्रेडेंशियल नहीं, कोई बाहरी प्रक्रिया नहीं** — सारा पार्सिंग और सांख्यिकी इन-प्रोसेस TypeScript है।
+- रिपोर्ट में आपके डेटासेट के नमूना सेल मान हो सकते हैं (`evidenceRowLimit` और डिस्प्ले ट्रंकेशन से सीमित); सत्र लॉग सामान्य रूप से टूल तर्क और परिणाम रिकॉर्ड करता है।
+
+## Security boundaries
+
+- **पथ सीमांकन** — डेटासेट और आउटपुट पथ सत्र वर्कस्पेस के भीतर हल होने चाहिए (`verifyCitations` `workspaceRoot` उपयोग करता है); `..` एस्केप और रूट से बाहर के निरपेक्ष पथ अस्वीकृत, तुलना से पहले दोनों पक्ष सामान्यीकृत (Windows स्लैश-सुरक्षित)।
+- **सीमित कार्य** — `maxRows` / `maxFileSizeMB` गार्ड अधिक बड़े इनपुट को ठोस रूप से अस्वीकार करते हैं; abort सिग्नल लंबे लोड को बीच में रोकते हैं।
+- **कोई अधिलेखन नहीं** — `data_clean` इनपुट पथ के समान `outputPath` अस्वीकार करता है।
+- **निर्धारणात्मक गणना** — समान इनपुट, समान आउटपुट; एकमात्र घड़ी `freshness` डिफ़ॉल्ट और रिपोर्ट टाइमस्टैम्प के लिए इंजेक्ट की गई है।
+
+## Known limitations
+
+- **सत्र ईवेंट अनुकूली हैं।** 0.1.0-rc.6 में प्लगिन सत्र-ईवेंट पंजीकरण सतह नहीं है और उसका `Session.append` `ignorable` चिह्न नहीं लगा सकता; अज्ञात `data-quality/*` प्रकार जोड़ने से सत्र लॉग पुनः स्थापना पर अस्वीकार हो जाएगा। इसलिए प्लगिन केवल तब जोड़ता है जब होस्ट शब्दावली जानता हो या `ignorable` append फ़्लैग समर्थित हो; rc.6 पर स्टोरेज-डोमेन रिपोर्ट ही टिकाऊ रिकॉर्ड है।
+- **CSV बोली** — RFC-4180 उद्धरण के साथ अल्पविराम/टैब, हेडर पंक्ति आवश्यक, रिक्त पंक्तियाँ छोड़ी जाती हैं; डिलीमीटर स्व-पहचान या टिप्पणी पंक्तियाँ नहीं।
+- **प्रकार पार्सिंग सख़्त है** — संख्याओं में सहस्र विभाजक नहीं; तिथियाँ `YYYY-MM-DD` / `YYYY/MM/DD` / ISO-शैली datetime (UTC); बूलियन `true/false/yes/no/1/0`। बाक़ी सब `string`/`mixed` प्रोफ़ाइल होता है — इरादा हो तो `coerce-type` से क्लीन करें।
+- **टूल के लिए JSON तालिकीय होना चाहिए** (सपाट ऑब्जेक्ट की सरणी); `verifyCitations` मनमाने JSON दस्तावेज़ों पर चलता है।
+- **कोई ML विसंगति पहचान नहीं, कोई PII मास्किंग नहीं, कोई डेटाबेस नहीं, कोई SQL नहीं** — केवल नियम-आधारित संदेह टिप्पणियाँ।
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build
+pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm run verify:readme-sync && pnpm pack
+```
+
+- टेस्ट 0.1.0-rc.6 peers के वास्तविक `Context`/`Session`/`ToolRuntime`/स्टोरेज डोमेन के विरुद्ध vitest चलाते हैं (हाथ से लिखे सेवा mock नहीं) और शुद्ध इंजन specs; हर क्लीन/सत्यापन नियम के सकारात्मक और नकारात्मक केस हैं, और `verifyCitations` चारों स्थितियों को कवर करता है।
+- `scripts/loader-runner.mjs` वास्तविक Loader संयोजन बूट करता है और API कुंजी के बिना `fixtures/` पर प्रोफ़ाइल → क्लीन → सत्यापन श्रृंखला चलाता है।
+- रिलीज़: `node scripts/release.mjs <x.y.z>` (कभी push नहीं; टैग `release.yml` ट्रिगर करता है)।
+
+## Topics
+
+`dsh` · `dsh-plugin` · `deepseek-harness` · `cordis` · `data-quality` · `data-cleaning` · `data-profiling` · `data-verification`
+
+## Contributors
+
+dsh-data-quality योगदानकर्ताओं द्वारा रखरखाव। रिपॉजिटरी सार्वजनिक होने पर issues और pull requests स्वागत योग्य हैं।
+
+## PerryLink DSH Plugin Family
+
+यह प्लगिन साझा DSH परिवार इंजीनियरिंग परिपाटियों का पालन करता है: bundle-मैनिफ़ेस्ट पैकेजिंग (`dsh.bundle` + `cordis.patch.yml`), सिंक जाँच से बंधे पाँच-भाषा README, ठोस-असफल Schemastery कॉन्फ़िगरेशन, वास्तविक-सेवा vitest कवरेज, और तीन-वर्कफ़्लो CI/compat/release श्रृंखला।
+
+## License
+
+Apache-2.0 — देखें [LICENSE](LICENSE) और [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)।