feat: add preflight validation workflow and centralize shared validators (#406)

`tooling/` is where the evaluation-report renderer will eventually
consolidate and where agent-friendly JSON and plain-text modes will
land. Keeping preflight rendering-free means render swaps never reach
into check code.

## UX

`safe-synthesizer run --validate ...` prints a Rich report grouped by
stage, with per-check status, severity-tagged issues, and a terminal
summary. Errors set exit code 1. Warnings are advisory. See
`docs/user-guide/running.md` and `docs/user-guide/troubleshooting.md`.

## Extending preflight

`docs/developer-guide/preflight-plugins.md` walks two end-to-end worked
examples (`DuplicateRowsCheck`, `GroupSkewCheck`), covers the `requires`
/ `enabled()` dependency model and issue-code conventions, and includes
a "Testing a check" section.

## Tests

- `tests/preflight/test_preflight.py`: per-check unit coverage.
- `tests/preflight/test_plugin_registration.py`: plugin surface,
reserved namespaces, crash isolation, dependency gating.
- `tests/preflight/test_registry_validation.py`: `build_registry` and
`_validate_registry` shape invariants.
- `tests/preflight/test_preflight_cli.py`: smoke coverage for the
`--validate` path.
- `tests/cli/test_run.py`: integration with `safe-synthesizer run`.

## Follow-ups

- `safe-synthesizer doctor`: a data-independent environment health
command that reuses the environment and config-only subset of the
registry. Plan drafted, implementation deferred.
- Plain, JSON, and agent-friendly render modes via
`tooling.modes.RenderMode`.

closes #332.

---------

Signed-off-by: Aaron Gonzales <aagonzales@nvidia.com>
Signed-off-by: Kendrick Boyd <kendrickb@nvidia.com>
Signed-off-by: aaron gonzales <aagonzales@nvidia.com>
Signed-off-by: aagonzales <aagonzales@nvidia.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Kendrick Boyd <kendrickb@nvidia.com>

Author: 3 people

.gitignore

@@ -73,8 +73,5 @@ docs/**/_snippets/**/*.tgz
 # this is sometimes used by wandb as a local path.
 wandb/
 
-# output from unsloth defaults to the local path
-unsloth_compiled_cache/
-
 # symbolic link to the nmp repo folder for uv dependency resolution.
 .nmp_repo

AGENTS.md

@@ -48,20 +48,22 @@ Source code lives in `src/nemo_safe_synthesizer/`:
 | `cli/` | Click CLI, main entry point |
 | `config/` | Pydantic parameter models, SafeSynthesizerParameters |
 | `configurator/` | Pydantic-to-Click mapping, Parameter types, validators |
-| `data_processing/` | Holdout, actions, assembler, records |
+| `data_processing/` | Holdout, actions, assembler, records, shared token budget (`budget.py`), shared column validators (`validation.py`) |
 | `evaluation/` | Evaluator, components (privacy, MI, AIA, PII replay), reports |
 | `generation/` | GeneratorBackend, VllmBackend, regex manager, batch gen |
 | `holdout/` | Train/test splitting |
 | `llm/` | Model loading, metadata, memory management |
 | `pii_replacer/` | NER-based PII detection and replacement |
 | `privacy/` | DP transformers (Opacus integration) |
 | `sdk/` | SafeSynthesizer builder, library_builder |
-| `training/` | TrainingBackend, HuggingFace backend |
+| `training/` | TrainingBackend, HuggingFace backend, timeseries_preprocessing (`timeseries_preprocessing.py`) |
 | `artifacts/` | Data quality checks, field analysis, metadata |
 | `observability.py` | CategoryLogger, TracedContext, structured logging |
 | `errors.py` | Error hierarchy: `SafeSynthesizerError` → `UserError` (`DataError`/`ParameterError` are also `ValueError`; `GenerationError` is also `RuntimeError`) and `InternalError` (also `RuntimeError`). See `diagnose-failures` skill |
 | `defaults.py` | Default settings, constants (`DEFAULT_ARTIFACTS_PATH`, `PSEUDO_GROUP_COLUMN`) |
 | `package_info.py` | Package version (uv-dynamic-versioning) |
+| `preflight/` | Pre-flight validation (runs against the training split produced by `Holdout`, not the full input). Package layout: `types` (dataclasses), `base` (`PreflightCheck` ABC hierarchy — `ConfigCheck`/`DataFrameCheck`/`MetadataCheck`/`AdvisoryCheck`), `registry` (`get_registry() -> PreflightRegistry`, plugin registration), `orchestrator` (`run_preflight`, `_run_registry` with dependency gating), `checks/` (15 granular core checks grouped by stage: `environment.py` for CONFIG, `dataframe.py` for DATAFRAME, `metadata.py` for METADATA, `advisory.py` for ADVISORY, plus `_helpers.py` shared helpers and public `preflight.helpers` for plugin authors). Rendering-free by design. |
+| `tooling/` | Internal rendering layer. Hosts `render_preflight_report` (Rich today; agentic/plain/JSON modes planned via `RenderMode`), `PreflightRenderContext`. Intended to absorb the evaluation report renderer and alternative output modes over time. |
 | `results.py` | Result compilation (`make_nss_results`, `make_nss_summary`) |
 | `utils.py` | Schema prompt creation, pattern matching helpers |