equiframe 0.12.4__py3-none-any.whl

equiframe/report_rendering.py

@@ -0,0 +1,366 @@
+"""Pure, bounded renderers for already disclosed comparison facts.
+
+No renderer reads an artifact, imports a notebook framework or executes user HTML.
+All three views consume the same sections, including evidence limitations. The
+standalone document adds a restrictive CSP; notebook fragments contain only
+escaped text and locally scoped, static markup/styles.
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from html import escape
+from unicodedata import category
+
+from equiframe.errors import ResourceLimitError
+from equiframe.report_types import ComparisonReport, ReportCount, ReportValue, ReportWitness
+
+
+@dataclass(frozen=True)
+class _Section:
+    title: str
+    headers: tuple[str, ...]
+    rows: tuple[tuple[str, ...], ...]
+    compact: bool = False
+
+
+@dataclass
+class _Output:
+    limit: int
+    parts: list[str] = field(default_factory=list)
+    size: int = 0
+
+    def write(self, fragment: str) -> None:
+        self.size += len(fragment.encode("utf-8"))
+        if self.size > self.limit:
+            raise ResourceLimitError("comparison report exceeds max_report_bytes")
+        self.parts.append(fragment)
+
+    def finish(self) -> str:
+        return "".join(self.parts)
+
+
+def _safe_text(value: str) -> str:
+    """Make terminal controls, bidi controls and line injection visible as escapes."""
+    result: list[str] = []
+    short = {"\n": "\\n", "\r": "\\r", "\t": "\\t", "\b": "\\b", "\f": "\\f"}
+    for char in value:
+        if char in short:
+            result.append(short[char])
+        elif category(char) in {"Cc", "Cf", "Cs", "Zl", "Zp"}:
+            number = ord(char)
+            result.append(f"\\u{number:04x}" if number <= 0xFFFF else f"\\U{number:08x}")
+        else:
+            result.append(char)
+    return "".join(result)
+
+
+def _html_text(value: str) -> str:
+    return escape(_safe_text(value), quote=True)
+
+
+def _boolean(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _roles(report: ComparisonReport) -> tuple[str, str]:
+    if report.reference == "expected":
+        return "Candidate (left)", "Expected (right)"
+    return "Peer (left)", "Peer (right)"
+
+
+def _count_label(name: str, report: ComparisonReport) -> str:
+    candidate, reference = _roles(report)
+    labels = {
+        "candidate_rows": f"{candidate} rows",
+        "reference_rows": f"{reference} rows",
+        "candidate_excess_occurrences": f"{candidate} excess occurrences",
+        "reference_excess_occurrences": f"{reference} excess occurrences",
+        "matched_rows": "Matched rows",
+        "difference_records": "Difference records",
+        "contract_violations": "Contract violation records",
+        "added_rows": "Added rows (left relative to right)",
+        "removed_rows": "Removed rows (left relative to right)",
+        "modified_rows": "Modified aligned rows",
+    }
+    return labels.get(name, name)
+
+
+def _count_value(count: ReportCount) -> str:
+    if count.precision == "unknown":
+        return "unknown"
+    if count.precision == "lower_bound":
+        return f"at least {count.value}"
+    if count.precision == "estimate":
+        return f"approximately {count.value}"
+    return str(count.value)
+
+
+def _column_labels(witness: ReportWitness, size: int, *, key: bool = False) -> tuple[str, ...]:
+    columns = witness.key_columns if key else witness.columns
+    if not key and witness.column is not None and size == 1:
+        return (witness.column,)
+    if len(columns) == size:
+        return columns
+    return tuple(f"Field {index + 1} (column unavailable)" for index in range(size))
+
+
+def _value_row(side: str, column: str, value: ReportValue) -> tuple[str, ...]:
+    return (
+        side,
+        column,
+        value.representation,
+        value.disclosure,
+        value.kind,
+        value.native_type if value.native_type is not None else "unavailable",
+        value.physical_type if value.physical_type is not None else "unavailable",
+    )
+
+
+def _witness_sections(report: ComparisonReport) -> Iterator[_Section]:
+    candidate, reference = _roles(report)
+    for number, witness in enumerate(report.examples, 1):
+        yield _Section(
+            f"Example {number}: location and reason",
+            ("Fact", "Value"),
+            (
+                ("Category", witness.category),
+                ("Code", witness.code),
+                ("Reason", witness.reason),
+                (
+                    f"{candidate} position (zero-based)",
+                    str(witness.position) if witness.position is not None else "unavailable",
+                ),
+                (
+                    f"{reference} position (zero-based)",
+                    str(witness.other_position)
+                    if witness.other_position is not None
+                    else "unavailable",
+                ),
+                ("Column", witness.column if witness.column is not None else "not specified"),
+                (
+                    f"{candidate} occurrences",
+                    str(witness.candidate_count)
+                    if witness.candidate_count is not None
+                    else "unavailable",
+                ),
+                (
+                    f"{reference} occurrences",
+                    str(witness.reference_count)
+                    if witness.reference_count is not None
+                    else "unavailable",
+                ),
+            ),
+            compact=True,
+        )
+        rows: list[tuple[str, ...]] = []
+        for side, values, key in (
+            ("Key", witness.key, True),
+            (candidate, witness.candidate, False),
+            (reference, witness.reference, False),
+        ):
+            labels = _column_labels(witness, len(values), key=key)
+            rows.extend(
+                _value_row(side, column, value)
+                for column, value in zip(labels, values, strict=True)
+            )
+        if rows:
+            yield _Section(
+                f"Example {number}: values and types",
+                ("Side", "Column", "Value", "Disclosure", "Kind", "Native type", "Physical type"),
+                tuple(rows),
+                compact=True,
+            )
+
+
+def _sections(report: ComparisonReport) -> Iterator[_Section]:
+    yield _Section(
+        "Verdict and coverage",
+        ("Fact", "Value"),
+        (
+            ("Verdict", report.state),
+            ("Evaluation complete", _boolean(report.complete)),
+            ("Scope", report.scope),
+            ("Reference role", report.reference),
+            (
+                "Interpretation",
+                (
+                    "Comparison against the declared expected output; "
+                    "its independence is not established"
+                )
+                if report.reference == "expected"
+                else "Agreement between peers does not establish independent correctness",
+            ),
+            ("Strategy", report.strategy),
+            ("Coverage", report.coverage),
+        ),
+    )
+    yield _Section(
+        "Reasons",
+        ("Reason",),
+        tuple((reason,) for reason in report.reasons) or (("No recorded reasons",),),
+    )
+    yield _Section("Next action", ("Action",), ((report.next_action,),))
+    yield _Section(
+        "Counts",
+        ("Measure", "Value", "Precision", "Unit"),
+        tuple(
+            (_count_label(count.name, report), _count_value(count), count.precision, count.unit)
+            for count in report.counts
+        )
+        or (("Counts", "unknown", "unknown", "not specified"),),
+    )
+    yield _Section(
+        "Displayed examples",
+        ("Fact", "Value"),
+        (
+            ("Included examples", str(report.evidence.included_examples)),
+            ("Available difference records", str(report.evidence.available_records)),
+            ("Display complete", _boolean(report.evidence.display_complete)),
+            ("Counting scope", "Difference records need not be distinct rows"),
+        ),
+    )
+    yield from _witness_sections(report)
+    yield _Section(
+        "Policies",
+        ("Policy", "Value"),
+        tuple((policy.name, policy.value) for policy in report.policies)
+        or (("Policy entries", "none recorded"),),
+    )
+    evidence = report.evidence
+    yield _Section(
+        "Evidence and limitations",
+        ("Fact", "Value"),
+        (
+            ("Evidence schema version", evidence.schema_version),
+            ("Evidence mode", evidence.mode),
+            ("Inspection", evidence.inspection),
+            ("Evaluation complete", _boolean(evidence.evaluation_complete)),
+            ("Counts final", _boolean(evidence.counts_final)),
+            ("Values withheld", _boolean(evidence.values_withheld)),
+            ("Metadata withheld", _boolean(evidence.metadata_withheld)),
+            ("Original evidence retention", evidence.raw_retention),
+            ("Report retention", evidence.report_retention),
+            ("Access", evidence.access),
+            ("Exhaustive evidence required", _boolean(evidence.required_exhaustive)),
+            ("Evidence requirements", evidence.acceptance),
+            ("Reproduction", evidence.reproduction),
+            ("Reproduction scope", evidence.reproduction_scope),
+        ),
+        compact=True,
+    )
+    if evidence.unmet_requirements:
+        yield _Section(
+            "Unmet evidence requirements",
+            ("Requirement",),
+            tuple((requirement,) for requirement in evidence.unmet_requirements),
+            compact=True,
+        )
+    options = report.options
+    yield _Section(
+        "Report disclosure and limits",
+        ("Setting", "Value"),
+        (
+            ("Mode", options.mode),
+            ("Include values", _boolean(options.include_values)),
+            ("Include metadata", _boolean(options.include_metadata)),
+            ("Redacted columns", str(options.redacted_column_count)),
+            ("Maximum examples", str(options.max_examples)),
+            ("Maximum value characters", str(options.max_value_chars)),
+            ("Maximum report bytes", str(options.max_report_bytes)),
+            ("Require exhaustive evidence", _boolean(options.require_exhaustive)),
+        ),
+        compact=True,
+    )
+    yield _Section(
+        "Identity",
+        ("Fact", "Value"),
+        (
+            ("Report schema version", report.schema_version),
+            ("Contract SHA-256", report.contract_sha256),
+            ("Comparison specification SHA-256", report.spec_sha256),
+        ),
+        compact=True,
+    )
+
+
+_STYLE = (
+    ".equiframe-report{font:14px system-ui,sans-serif;color:#172b3a;"
+    "background:#fff;max-width:1100px;padding:1rem;overflow-wrap:anywhere}"
+    ".equiframe-report h1{font-size:1.5rem}.equiframe-report h2{font-size:1.1rem}"
+    ".equiframe-report table{width:100%;border-collapse:collapse;margin:.6rem 0 1rem}"
+    ".equiframe-report .equiframe-facts{table-layout:fixed}"
+    ".equiframe-report .equiframe-facts th:first-child{width:25%}"
+    ".equiframe-report th,.equiframe-report td{padding:.4rem;border:1px solid #ccd5df;"
+    "text-align:left;vertical-align:top;white-space:pre-wrap}"
+    ".equiframe-report thead{background:#f0f4f7}.equiframe-report summary{"
+    "cursor:pointer;font-weight:bold;margin:.6rem 0}"
+    "@media print{.equiframe-report{max-width:none}}"
+)
+
+
+def _write_html(output: _Output, report: ComparisonReport, *, compact: bool) -> None:
+    output.write("<style>" + _STYLE + '</style><section class="equiframe-report">')
+    output.write("<h1>EquiFrame comparison</h1>")
+    for section in _sections(report):
+        collapsed = compact and section.compact
+        if collapsed:
+            output.write("<details><summary>" + _html_text(section.title) + "</summary>")
+        else:
+            output.write("<section><h2>" + _html_text(section.title) + "</h2>")
+        output.write(
+            '<table class="equiframe-facts"><thead><tr>'
+            if len(section.headers) == 2
+            else "<table><thead><tr>"
+        )
+        for header in section.headers:
+            output.write('<th scope="col">' + _html_text(header) + "</th>")
+        output.write("</tr></thead><tbody>")
+        for row in section.rows:
+            output.write("<tr>")
+            for index, cell in enumerate(row):
+                if index == 0 and len(section.headers) == 2:
+                    output.write('<th scope="row">' + _html_text(cell) + "</th>")
+                else:
+                    output.write("<td>" + _html_text(cell) + "</td>")
+            output.write("</tr>")
+        output.write("</tbody></table>" + ("</details>" if collapsed else "</section>"))
+    output.write("</section>")
+
+
+def render_comparison_text(report: ComparisonReport) -> str:
+    """Render all disclosed facts as plain text, escaping terminal control characters."""
+    report = ComparisonReport.model_validate(report)
+    output = _Output(report.options.max_report_bytes)
+    output.write("EquiFrame comparison\n")
+    for section in _sections(report):
+        output.write("\n" + _safe_text(section.title) + "\n")
+        if len(section.headers) > 2:
+            output.write(" | ".join(_safe_text(header) for header in section.headers) + "\n")
+        for row in section.rows:
+            separator = ": " if len(row) == 2 else " | "
+            output.write(separator.join(_safe_text(cell) for cell in row) + "\n")
+    return output.finish()
+
+
+def render_comparison_html(report: ComparisonReport) -> str:
+    """Render a standalone inert HTML document, or raise when its UTF-8 budget is exceeded."""
+    report = ComparisonReport.model_validate(report)
+    output = _Output(report.options.max_report_bytes)
+    output.write(
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
+        "style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'\">"
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        "<title>EquiFrame comparison</title></head><body>"
+    )
+    _write_html(output, report, compact=False)
+    output.write("</body></html>")
+    return output.finish()
+
+
+def render_comparison_notebook(report: ComparisonReport) -> str:
+    """Render a compact inert fragment without IO, JavaScript or optional dependencies."""
+    report = ComparisonReport.model_validate(report)
+    output = _Output(report.options.max_report_bytes)
+    _write_html(output, report, compact=True)
+    return output.finish()

equiframe/report_types.py

@@ -0,0 +1,294 @@
+"""Versioned, detached comparison views; disclosure never changes evaluation."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BeforeValidator, Field, model_validator
+from typing_extensions import Self
+
+from equiframe._base import (
+    FrozenModel,
+    NonNegativeInt,
+    PositiveInt,
+    _ExplicitOutcome,
+    strict_bool_literal,
+)
+from equiframe.comparison_types import ComparisonValue
+from equiframe.pipeline_types import EvidenceFile
+from equiframe.types import ComparisonState, Sha256
+
+EvidenceMode = Literal["diagnostic", "detail", "reproduction"]
+CountPrecision = Literal["exact", "lower_bound", "estimate", "unknown"]
+
+
+class ReportOptions(FrozenModel):
+    """Separate disclosure/inspection budgets; existing raw capture is unchanged.
+
+    Values, names and free-form producer text are withheld by default. Reproduction
+    exports require both disclosure opt-ins and cannot redact selected columns.
+    No setting grants operating-system permissions or deletes original evidence.
+    """
+
+    schema_version: Literal["1.0"] = "1.0"
+    mode: EvidenceMode = "diagnostic"
+    include_values: bool = False
+    include_metadata: bool = False
+    redact_columns: tuple[str, ...] = ()
+    max_examples: Annotated[int, Field(ge=0, le=10000)] = 20
+    max_value_chars: Annotated[int, Field(ge=16, le=1048576)] = 4096
+    max_report_bytes: PositiveInt = 2 * 1024 * 1024
+    max_evidence_bytes: PositiveInt = 64 * 1024 * 1024
+    max_records: Annotated[int, Field(gt=0, le=1000000)] = 100000
+    require_exhaustive: bool = False
+
+    @model_validator(mode="after")
+    def valid_disclosure(self) -> Self:
+        if len(set(self.redact_columns)) != len(self.redact_columns):
+            raise ValueError("redacted columns must be unique")
+        if self.mode == "reproduction" and (
+            not self.include_values or not self.include_metadata or self.redact_columns
+        ):
+            raise ValueError("reproduction requires values and metadata without column redaction")
+        return self
+
+
+class ReportViewPolicy(FrozenModel):
+    """Safe publication policy: column-redaction selectors never leave the builder."""
+
+    mode: EvidenceMode
+    include_values: bool
+    include_metadata: bool
+    redacted_column_count: NonNegativeInt
+    max_examples: NonNegativeInt
+    max_value_chars: PositiveInt
+    max_report_bytes: PositiveInt
+    require_exhaustive: bool
+
+
+class ReportCount(FrozenModel):
+    name: str
+    value: NonNegativeInt | None
+    precision: CountPrecision
+    unit: Literal["rows", "records", "occurrences"]
+
+    @model_validator(mode="after")
+    def known(self) -> Self:
+        if (self.value is None) != (self.precision == "unknown"):
+            raise ValueError("unknown counts omit their value; known counts require a value")
+        return self
+
+
+class ReportPolicy(FrozenModel):
+    name: str
+    value: str
+
+
+class ReportValue(FrozenModel):
+    disclosure: Literal["visible", "redacted", "omitted"]
+    kind: str
+    representation: str
+    native_type: str | None = None
+    physical_type: str | None = None
+    value: ComparisonValue | None = None
+
+    @model_validator(mode="after")
+    def visible_only(self) -> Self:
+        if (self.disclosure == "visible") != (self.value is not None):
+            raise ValueError("only visible values contain scalar evidence")
+        if self.disclosure != "visible" and self.representation != f"[{self.disclosure}]":
+            raise ValueError("withheld values require a fixed non-disclosing representation")
+        return self
+
+
+class ReportWitness(FrozenModel):
+    category: Literal["contract", "content", "schema"]
+    code: str
+    reason: str
+    position: NonNegativeInt | None
+    other_position: NonNegativeInt | None
+    column: str | None
+    columns: tuple[str, ...]
+    key_columns: tuple[str, ...]
+    key: tuple[ReportValue, ...]
+    candidate: tuple[ReportValue, ...]
+    reference: tuple[ReportValue, ...]
+    candidate_count: NonNegativeInt | None
+    reference_count: NonNegativeInt | None
+
+    @model_validator(mode="after")
+    def occurrence_counts(self) -> Self:
+        if self.category != "content" and (
+            self.candidate_count is not None or self.reference_count is not None
+        ):
+            raise ValueError("contract/schema records do not calculate occurrence counts")
+        if self.category == "content" and (
+            self.candidate_count is None or self.reference_count is None
+        ):
+            raise ValueError("content witnesses require recorded occurrence counts")
+        return self
+
+
+class ReportEvidenceManifest(FrozenModel):
+    schema_version: Literal["1.0"] = "1.0"
+    mode: EvidenceMode
+    inspection: Literal["result_only", "verified_differences"]
+    evaluation_complete: bool
+    counts_final: bool
+    available_records: NonNegativeInt
+    included_examples: NonNegativeInt
+    display_complete: bool
+    values_withheld: bool
+    metadata_withheld: bool
+    raw_retention: Literal["unchanged_in_original_comparison"] = "unchanged_in_original_comparison"
+    report_retention: Literal["until_caller_deletes"] = "until_caller_deletes"
+    access: Literal["caller_managed_local_storage_no_encryption"] = (
+        "caller_managed_local_storage_no_encryption"
+    )
+    required_exhaustive: bool
+    acceptance: Literal["satisfied", "not_satisfied"]
+    unmet_requirements: tuple[str, ...]
+    reproduction: Literal[
+        "not_requested", "requires_verified_export", "exported_materialized_inputs"
+    ]
+    reproduction_scope: Literal["materialized_comparison_only_no_transform_reexecution"] = (
+        "materialized_comparison_only_no_transform_reexecution"
+    )
+
+    @model_validator(mode="after")
+    def accepted(self) -> Self:
+        if (self.acceptance == "satisfied") != (not self.unmet_requirements):
+            raise ValueError("evidence acceptance must describe unmet requirements")
+        if self.included_examples > self.available_records:
+            raise ValueError("display examples exceed available records")
+        if self.display_complete != (self.included_examples == self.available_records):
+            raise ValueError("display completeness must agree with its record counts")
+        return self
+
+
+class ComparisonReport(_ExplicitOutcome, FrozenModel):
+    """One sanitized source for JSON, console, standalone HTML and notebooks.
+
+    Formatting this object performs no file IO, imports no notebook framework and
+    never evaluates a source. JSON is a view, not a serialized ComparisonResult.
+    """
+
+    _truth_value_guidance = (
+        "use assert_equivalent on the original ComparisonResult; a generated report is not approval"
+    )
+
+    schema_version: Literal["1.0"] = "1.0"
+    state: ComparisonState
+    complete: bool
+    scope: Literal["output_schema"] = "output_schema"
+    reference: Literal["peer", "expected"]
+    strategy: Literal["pending", "sequence", "key", "multiset", "matching"]
+    coverage: Literal["complete", "partial"]
+    contract_sha256: Sha256
+    spec_sha256: Sha256
+    counts: tuple[ReportCount, ...]
+    reasons: tuple[str, ...]
+    next_action: str
+    policies: tuple[ReportPolicy, ...]
+    examples: tuple[ReportWitness, ...]
+    evidence: ReportEvidenceManifest
+    options: ReportViewPolicy
+
+    @model_validator(mode="after")
+    def consistent(self) -> Self:
+        if (self.coverage == "complete") != self.complete:
+            raise ValueError("coverage must preserve comparison completeness")
+        if self.state in ("equivalent", "different") and not self.complete:
+            raise ValueError("an interrupted comparison cannot have a final verdict")
+        if self.evidence.evaluation_complete != self.complete:
+            raise ValueError("evidence must preserve evaluation completeness")
+        if self.evidence.counts_final != self.complete:
+            raise ValueError("count completeness must preserve evaluation completeness")
+        if self.evidence.mode != self.options.mode:
+            raise ValueError("evidence mode must agree with the view policy")
+        if self.evidence.required_exhaustive != self.options.require_exhaustive:
+            raise ValueError("evidence requirement must agree with the view policy")
+        counts = {count.name: count for count in self.counts}
+        if set(counts) != {
+            "candidate_rows",
+            "reference_rows",
+            "matched_rows",
+            "difference_records",
+            "contract_violations",
+            "added_rows",
+            "removed_rows",
+            "modified_rows",
+            "candidate_excess_occurrences",
+            "reference_excess_occurrences",
+        }:
+            raise ValueError("report requires the complete set of named counts")
+        if counts["difference_records"].value != self.evidence.available_records:
+            raise ValueError("record count must agree with the evidence manifest")
+        if self.state == "equivalent" and any(
+            counts[name].precision != "exact" or counts[name].value is None
+            for name in ("candidate_rows", "reference_rows", "matched_rows")
+        ):
+            raise ValueError("equivalent report requires known exact row counts")
+        if self.state == "equivalent" and (
+            self.evidence.available_records
+            or self.examples
+            or self.reasons
+            or counts["candidate_rows"].value != counts["reference_rows"].value
+            or counts["matched_rows"].value != counts["candidate_rows"].value
+        ):
+            raise ValueError("equivalent report requires complete matching without differences")
+        if self.state == "different" and not self.evidence.available_records:
+            raise ValueError("different report requires recorded differences")
+        if not self.complete and any(count.precision == "exact" for count in self.counts):
+            raise ValueError("partial evaluation cannot claim final exact counts")
+        if self.evidence.included_examples != len(self.examples):
+            raise ValueError("manifest must describe the actual displayed examples")
+        if len({count.name for count in self.counts}) != len(self.counts):
+            raise ValueError("count names must be unique")
+        for witness in self.examples:
+            if not self.options.include_metadata and any(
+                value.native_type is not None or value.physical_type is not None
+                for value in (*witness.key, *witness.candidate, *witness.reference)
+            ):
+                raise ValueError("disclosure policy forbids producer type metadata")
+            if not self.options.include_values and any(
+                value.disclosure == "visible"
+                for value in (*witness.key, *witness.candidate, *witness.reference)
+            ):
+                raise ValueError("disclosure policy forbids visible values")
+        return self
+
+    def to_text(self) -> str:
+        from equiframe.report_rendering import render_comparison_text
+
+        return render_comparison_text(self)
+
+    def to_html(self) -> str:
+        from equiframe.report_rendering import render_comparison_html
+
+        return render_comparison_html(self)
+
+    def _repr_html_(self) -> str:
+        from equiframe.report_rendering import render_comparison_notebook
+
+        return render_comparison_notebook(self)
+
+
+class ReportPublicationManifest(FrozenModel):
+    """Last-written success receipt for a closed report export inventory."""
+
+    schema_version: Literal["1.0"] = "1.0"
+    publication_complete: Annotated[Literal[True], BeforeValidator(strict_bool_literal)] = True
+    report_evidence: ReportEvidenceManifest
+    files: tuple[EvidenceFile, ...]
+
+    @model_validator(mode="after")
+    def unique_files(self) -> Self:
+        names = [item.path for item in self.files]
+        if len(names) != len(set(names)):
+            raise ValueError("report inventory paths must be unique")
+        if not {"report.json", "report.html", "report.txt"} <= set(names):
+            raise ValueError("report publication requires JSON, HTML and text")
+        if "evidence-manifest.json" in names:
+            raise ValueError("publication inventory must not include itself")
+        return self

equiframe/reporting.py

@@ -0,0 +1,26 @@
+"""Reports expose selected operational facts, never parameter values or exception messages."""
+
+from pathlib import Path
+
+from equiframe._document_io import write_document as _write_document
+from equiframe._report_format_v1 import pipeline_html_v1, pipeline_summary_v1
+from equiframe.evidence import publish_json
+from equiframe.pipeline_types import PipelineResult
+
+
+def pipeline_summary(result: PipelineResult) -> dict[str, object]:
+    """Current operational summary; persisted format 1.0 is separately frozen."""
+    return pipeline_summary_v1(result)
+
+
+def render_report(summary: dict[str, object]) -> str:
+    """Current presentation; escape values and preserve the existing 1.0 layout."""
+    return pipeline_html_v1(summary)
+
+
+def write_report(result: PipelineResult, directory: Path) -> None:
+    """Publish a new report directory; existing reports are never replaced."""
+    summary = pipeline_summary(result)
+    directory.mkdir(parents=True, exist_ok=False)
+    publish_json(summary, directory / "report.json")
+    _write_document(directory / "report.html", render_report(summary).encode("utf-8"))