feat(compliance): add regulatory compliance report generators

Add an additive `freshdata.compliance` module that maps a CleanReport's
actions to five named regulatory control frameworks and emits standards-grade
audit artifacts:

- 21 CFR §11.10(e): time-stamped, attributable, non-obscuring change log
- GDPR Article 30 (record of processing) + Article 17 (erasure log)
- ALCOA+ data-integrity attestation
- SOX-404 transformation-control evidence pack
- HIPAA Safe Harbor 18-identifier coverage (45 CFR §164.514(b)(2))

The entry point `generate_compliance_report(report, frameworks, config=...)`
returns a ComplianceBundle exposing to_dict/to_json/to_frame/summary; each
framework report carries passed/warnings/errors and a non-negotiable advisory
caveat.

The existing public API is untouched. A normalization adapter maps the real
`Action.step` vocabulary onto the frameworks' concepts; optional `dataframe=`
and `enterprise_result=` arguments enrich the artifacts with inferred column
roles (infer_roles), the 0-100 Data Trust Score, and PII-masking / fuzzy-
cluster lineage, degrading gracefully when those are not supplied.

The 21 CFR audit's treatment of normalising rewrites is configurable via
`ComplianceConfig.strict_cfr_normalization` (default False keeps lossless
normalisations non-obscuring; True treats any rewrite without a retained
pre-image as obscuring, failing the gate).

Tests: tests/test_compliance/ (40 tests). Full suite green; total coverage
94.95% (gate 93%). ruff + mypy clean.

Developed with AI tooling assistance.

Author: JohnnyWilson16

CHANGELOG.md

@@ -7,6 +7,18 @@ adheres to [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- New `freshdata.compliance` subpackage that maps a `CleanReport` onto regulatory
+  control frameworks and emits standards-grade audit artifacts via
+  `generate_compliance_report(report, frameworks=[...]) -> ComplianceBundle`.
+  Five frameworks ship: `21cfr_11` (21 CFR §11.10(e) audit trail), `gdpr_30`
+  (Article 30 + 17), `alcoa_plus` (ALCOA+ data integrity), `sox_404`
+  (transformation controls), and `hipaa_safe_harbor` (18-identifier coverage).
+  Reports are purely additive and report-only (never mutate the input). Optional
+  `dataframe=` recovers column roles/missing ratios via `infer_roles`, and
+  `enterprise_result=` folds in the Data Trust Score, PII-masking events, and
+  clustering lineage. `ComplianceConfig.strict_cfr_normalization` (default
+  `False`) toggles whether lossless normalising rewrites count as obscuring for
+  the 21 CFR gate.
 - Four new domain validator packs: `healthcare` (FHIR/US Core — `Patient`,
   `Observation`, `Encounter` with `fhir_resource=`/auto-detection), `education`
   (Ed-Fi), `agriculture` (ADAPT, with area/yield unit coercion), and `media`

docs/api-reference.md

@@ -61,3 +61,13 @@ The `freshdata.enterprise` subpackage is documented in the
 ```python
 from freshdata.enterprise import clean_enterprise, EnterpriseConfig
 ```
+
+## Compliance
+
+The `freshdata.compliance` subpackage maps a `CleanReport` onto regulatory control
+frameworks; it is documented in the [compliance reports guide](compliance.md).
+Import its symbols lazily:
+
+```python
+from freshdata.compliance import generate_compliance_report, ComplianceConfig
+```

docs/compliance.md

@@ -0,0 +1,141 @@
+---
+title: Compliance reports
+description: >-
+  Map a freshdata CleanReport onto regulatory control frameworks — 21 CFR Part 11,
+  GDPR, ALCOA+, SOX-404, and HIPAA Safe Harbor — and emit standards-grade audit
+  artifacts.
+keywords: compliance report python, 21 cfr part 11 audit trail, gdpr article 30, hipaa safe harbor, sox 404 data controls, alcoa+
+---
+
+# Compliance reports
+
+The `freshdata.compliance` subpackage turns a [`CleanReport`](cleaning-engine.md)
+into a regulatory audit artifact. Each *generator* maps the transformations
+freshdata applied — imputations, outlier handling, normalisations, deduplication,
+PII masking — onto a named control framework and emits a structured report you can
+attach to a data-governance workflow.
+
+The generators are **purely additive**: they never mutate the input report or
+DataFrame. They read what freshdata already recorded and re-express it against a
+framework's controls.
+
+!!! warning "Report generation, not certification"
+    A compliance artifact **supports** a compliance workflow; it does not
+    **constitute** a legal determination of compliance. Every report carries a
+    verbatim caveat ([`GENERAL_CAVEAT`](#caveat)) to that effect, and review by a
+    qualified compliance professional is required.
+
+## Quickstart
+
+```python
+import freshdata as fd
+from freshdata.compliance import generate_compliance_report, ComplianceConfig
+
+cleaned, report = fd.clean(df, return_report=True)
+
+bundle = generate_compliance_report(
+    report,
+    frameworks=["21cfr_11", "hipaa_safe_harbor"],
+    config=ComplianceConfig(operator_id="svc-1", retention_days=2555),
+    dataframe=df,            # optional: recovers column roles + missing ratios
+)
+
+bundle.summary()
+# {'21cfr_11': {'passed': True, 'warnings': [], 'errors': []},
+#  'hipaa_safe_harbor': {'passed': True, 'warnings': [...], 'errors': []}}
+
+bundle["hipaa_safe_harbor"].passed     # -> True / False
+print(bundle.to_json())                # full audit artifact as JSON
+```
+
+`generate_compliance_report` also accepts an enterprise result directly:
+`generate_compliance_report(enterprise_result, frameworks=[...])` (or
+`report` exposing `clean_report` + `trust_after`) folds in the embedded report
+and trust/mask data automatically.
+
+## Frameworks
+
+Pass one or more of these keys in `frameworks=`:
+
+| Key | Framework | What it documents |
+| --- | --- | --- |
+| `21cfr_11` | 21 CFR §11.10(e) | A tamper-evident audit trail: one entry per action, each marked non-obscuring (a pre-image was retained or the change cannot hide prior data). |
+| `gdpr_30` | GDPR Article 30 + Article 17 | Record of processing activities plus erasure (right-to-be-forgotten) evidence. |
+| `alcoa_plus` | ALCOA+ | Data-integrity attributes (Attributable, Legible, Contemporaneous, Original, Accurate, +). |
+| `sox_404` | SOX-404 transformation control | Internal-control evidence over data transformations, gated on the Data Trust Score. |
+| `hipaa_safe_harbor` | HIPAA Safe Harbor | Coverage of the 18 Safe Harbor identifiers, flagging any that remain unmasked. |
+
+Unknown keys raise `ValueError` listing the valid keys.
+
+## Configuration
+
+`ComplianceConfig` carries the caller-supplied context; every field has a sensible
+default, so `ComplianceConfig()` is valid. The most useful knobs:
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `operator_id` | `None` (`"system"`) | Operator recorded on each 21 CFR audit entry. |
+| `retention_days` | `2555` (7 years) | Retention period stamped on audit entries. |
+| `masked_columns` | `[]` | Columns known to be PII-masked (report-only path; merged with any enterprise mask report). |
+| `trust_score` | `None` | 0–100 trust score for the SOX / 21 CFR gates when no enterprise result is supplied. |
+| `fail_on_hipaa_gap` | `False` | Raise [`ComplianceGapError`](#errors) instead of warning when Safe Harbor gaps remain. |
+| `strict_cfr_normalization` | `False` | See below. |
+| `controller_name` / `controller_contact` / `processing_purpose` / `legal_basis` / `data_subject_categories` | — | GDPR Article 30 record fields. |
+
+### `strict_cfr_normalization`
+
+Controls how the 21 CFR audit classifies *normalising rewrites* (whitespace
+trims, sentinel canonicalisation):
+
+- **`False` (default)** — these lossless normalisations are treated as
+  **non-obscuring**: trimming `"  Ann "` to `"Ann"` cannot hide prior information,
+  so the gate stays green. Only genuine value rewrites with no retained pre-image
+  (outlier capping, fuzzy clustering) fail the gate.
+- **`True`** — any rewrite that did not retain a pre-image, *including*
+  normalisation, is treated as **obscuring**: the entry's
+  `original_value_class` becomes `"not_captured"`, `non_obscuring_guarantee`
+  becomes `False`, a warning is emitted, and the gate fails. Use this when your SOP
+  requires an independently recorded pre-image for every value change.
+
+## Richer evidence
+
+Two optional, keyword-only arguments add evidence when available:
+
+- **`dataframe=`** — the source frame. Recovers per-column roles and missing
+  ratios via [`freshdata.infer_roles`](api-reference.md), sharpening the HIPAA and
+  ALCOA reports.
+- **`enterprise_result=`** — an [enterprise](feature-overview.md) result supplying
+  the 0–100 Data Trust Score, PII-masking events, and fuzzy-clustering lineage.
+
+## Output
+
+`generate_compliance_report` returns a `ComplianceBundle` — a mapping of framework
+key to `FrameworkReport`:
+
+| On `ComplianceBundle` | Returns |
+| --- | --- |
+| `bundle.summary()` | `{key: {"passed", "warnings", "errors"}}` for a quick gate check. |
+| `bundle[key]` | The `FrameworkReport` for one framework. |
+| `key in bundle`, `len(bundle)`, `list(bundle)` | Membership, count, and the framework keys. |
+| `bundle.to_dict()` / `bundle.to_json(indent=2)` | The full artifact as a dict / JSON string. |
+| `bundle.to_frame()` | All reports flattened into a single `pandas.DataFrame`. |
+
+Each `FrameworkReport` exposes `framework_key`, `framework_name`, `passed` (bool),
+`warnings`, `errors`, and `data` (the framework-specific payload, e.g. the 21 CFR
+`audit_entries` or the HIPAA identifier coverage), plus its own `to_dict()`,
+`to_json()`, and `to_frame()`.
+
+## Errors {#errors}
+
+- `ValueError` — an unknown framework key was requested.
+- `ComplianceGapError` — HIPAA Safe Harbor gaps remain **and**
+  `config.fail_on_hipaa_gap=True`. Otherwise gaps surface as warnings on the
+  report and `passed` is `False`.
+
+## Caveat {#caveat}
+
+Every report embeds `GENERAL_CAVEAT` (importable from `freshdata.compliance`)
+unless a framework defines its own verbatim caveat. It states plainly that the
+artifact documents freshdata's transformations and their mapping to the named
+control framework, but is not a certified compliance system and does not
+constitute a legal determination — professional review is required.

docs/feature-overview.md

@@ -48,6 +48,14 @@ print(result.quality.to_markdown())
 assert result.passed_gate
 ```
 
+## Compliance reports
+
+The `freshdata.compliance` subpackage turns a `CleanReport` into a regulatory
+audit artifact, mapping freshdata's transformations onto named control
+frameworks — 21 CFR Part 11, GDPR (Art. 30/17), ALCOA+, SOX-404, and HIPAA Safe
+Harbor. The generators are purely additive and report-only. See the
+[compliance reports guide](compliance.md).
+
 ## Polars support
 
 ```python

mkdocs.yml

@@ -106,6 +106,7 @@ nav:
       - Cleaning engine: cleaning-engine.md
       - Data profiling: data-profiling.md
       - Feature overview: feature-overview.md
+      - Compliance reports: compliance.md
   - Examples: examples.md
   - Benchmarks: benchmarks.md
   - API Reference: api-reference.md

src/freshdata/__init__.py

@@ -30,6 +30,10 @@
 from .profile import ColumnProfile, Profile
 from .report import Action, CleanReport
 
+# Compliance report generators (additive — Phase 1 roadmap). Light import:
+# only stdlib + pandas at load; the enterprise layer is touched lazily at call time.
+from .compliance import ComplianceBundle, ComplianceConfig, generate_compliance_report
+
 __version__ = "1.0.0"
 
 __all__ = [
@@ -40,13 +44,16 @@
     "Cleaner",
     "ColumnPlan",
     "ColumnProfile",
+    "ComplianceBundle",
+    "ComplianceConfig",
     "ExplainReport",
     "Profile",
     "__version__",
     "clean",
     "compare_clean",
     "compare_plans",
     "explain_clean",
+    "generate_compliance_report",
     "infer_roles",
     "profile",
     "suggest_plan",

src/freshdata/compliance/_21cfr11.py

@@ -0,0 +1,106 @@
+"""21 CFR §11.10(e) — computer-generated, time-stamped audit trails."""
+
+from __future__ import annotations
+
+from ._adapter import ComplianceContext, NormalizedAction
+from ._base import (
+    GENERAL_CAVEAT,
+    ComplianceConfig,
+    FrameworkReport,
+    new_entry_id,
+)
+
+FRAMEWORK_KEY = "21cfr_11"
+FRAMEWORK_NAME = "21 CFR §11.10(e)"
+
+#: Verbatim regulatory text the audit trail is designed to satisfy.
+CONTROL_TEXT = (
+    "Use of computer-generated, time-stamped audit trails to independently "
+    "record the date and time of operator entries and actions that create, "
+    "modify, or delete electronic records. Record changes shall not obscure "
+    "previously recorded information and computer-generated audit trails shall "
+    "be retained for a period at least as long as that required for the subject "
+    "electronic records."
+)
+
+
+def _is_obscuring(action: NormalizedAction, *, strict: bool) -> bool:
+    """Whether an action could obscure previously recorded information.
+
+    Deletions are inherently non-obscuring once logged, and imputation/
+    structural/intentional-mask changes retain (or never had) a prior value. A
+    value overwrite with no retained pre-image (``not_captured``) always
+    obscures. Normalising rewrites (whitespace trim, sentinel canonicalisation)
+    obscure only when ``strict`` is set.
+    """
+    if action.record_action_type == "DELETE":
+        return False
+    if action.original_basis == "not_captured":
+        return True
+    return strict and action.original_basis == "normalized"
+
+
+def generate_21cfr11(ctx: ComplianceContext, config: ComplianceConfig) -> FrameworkReport:
+    """Emit a session header plus one audit entry per normalized action."""
+    operator_id = config.operator_id or "system"
+    strict = config.strict_cfr_normalization
+    warnings: list[str] = []
+    audit_entries: list[dict] = []
+
+    for action in ctx.actions:
+        obscuring = _is_obscuring(action, strict=strict)
+        audit_entries.append(
+            {
+                "entry_id": new_entry_id("CFR11"),
+                "session_id": ctx.session_id,
+                "timestamp_utc": ctx.timestamp,
+                "system_actor": config.system_actor,
+                "operator_id": operator_id,
+                "record_action_type": action.record_action_type,
+                "column_affected": action.column,
+                "column_role": action.column_role,
+                "rows_affected": action.row_count,
+                "original_value_class": "not_captured" if obscuring else "preserved",
+                "original_value_basis": action.original_basis,
+                "change_description": action.rationale or action.description,
+                "risk_level": action.risk,
+                "confidence": action.confidence,
+                "non_obscuring_guarantee": not obscuring,
+                "retention_days": config.retention_days,
+            }
+        )
+        # A MODIFY that overwrote an existing value without retaining a pre-image
+        # is the only way the audit trail could obscure prior information.
+        if obscuring:
+            warnings.append(
+                f"{action.record_action_type} on {action.column!r} did not retain a "
+                f"pre-image ({action.action_type}); prior value not independently recorded."
+            )
+
+    session_header = {
+        "session_id": ctx.session_id,
+        "session_start_utc": ctx.timestamp,
+        "system_actor": config.system_actor,
+        "operator_id": operator_id,
+        "total_actions": len(audit_entries),
+        "data_trust_score": ctx.trust_score,
+        "framework": FRAMEWORK_NAME,
+        "retention_days": config.retention_days,
+    }
+
+    passed = not warnings
+    data = {
+        "regulation": "21 CFR §11.10(e)",
+        "control_text": CONTROL_TEXT,
+        "session_header": session_header,
+        "audit_entries": audit_entries,
+        "caveat": GENERAL_CAVEAT,
+    }
+    return FrameworkReport(
+        framework_key=FRAMEWORK_KEY,
+        framework_name=FRAMEWORK_NAME,
+        passed=passed,
+        warnings=warnings,
+        errors=[],
+        data=data,
+    )