equiframe 0.12.4__py3-none-any.whl

equiframe/eda/models.py

@@ -0,0 +1,239 @@
+"""Version 1.0 diagnostics; independent of migration and verification formats."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field, model_validator
+from typing_extensions import Self
+
+from equiframe._base import FrozenModel, Identifier, NonNegativeInt, Text, _ExplicitOutcome
+from equiframe.types import Sha256
+
+Name = Annotated[str, Field(min_length=1)]
+
+
+class Source(FrozenModel):
+    path: Text
+    format: Literal["parquet", "csv", "arrow"] = "parquet"
+    snapshot_id: Text
+    expected_sha256: Sha256 | None = None
+    expected_bytes: NonNegativeInt | None = None
+    manifest_path: Text | None = None
+    manifest_sha256: Sha256 | None = None
+    delimiter: Annotated[str, Field(min_length=1, max_length=1)] = ","
+
+    @model_validator(mode="after")
+    def manifest_pair(self) -> Self:
+        if (self.manifest_path is None) != (self.manifest_sha256 is None):
+            raise ValueError("manifest path and externally trusted SHA-256 required together")
+        return self
+
+
+class Resources(FrozenModel):
+    memory_mb: Annotated[int, Field(ge=16, le=65536)] = 512
+    threads: Annotated[int, Field(ge=1, le=64)] = 1
+    timeout_seconds: Annotated[float, Field(gt=0)] = 300.0
+    temp_disk_mb: Annotated[int, Field(ge=1)] = 256
+    max_input_bytes: Annotated[int, Field(gt=0)] = 512 * 1024 * 1024
+    max_rows: Annotated[int, Field(ge=0)] = 10_000_000
+    max_columns: Annotated[int, Field(ge=1, le=1000)] = 256
+    max_groups: Annotated[int, Field(ge=1, le=1000)] = 100
+    examples: Annotated[int, Field(ge=0, le=100)] = 10
+    top_categories: Annotated[int, Field(ge=1, le=100)] = 10
+    histogram_bins: Annotated[int, Field(ge=1, le=100)] = 20
+    chart_rows: Annotated[int, Field(ge=0, le=1000)] = 200
+    max_report_bytes: Annotated[int, Field(ge=1)] = 32 * 1024 * 1024
+
+
+class Conversion(FrozenModel):
+    column: Name
+    target: Identifier
+    kind: Literal["decimal", "integer", "date", "timestamp"]
+    empty: Literal["invalid", "missing"] = "invalid"
+    precision: Annotated[int, Field(ge=1, le=38)] = 38
+    scale: Annotated[int, Field(ge=0, le=18)] = 6
+
+    @model_validator(mode="after")
+    def scale_fits(self) -> Self:
+        if self.scale > self.precision:
+            raise ValueError("scale exceeds precision")
+        return self
+
+
+class KeyRule(FrozenModel):
+    columns: tuple[Name, ...]
+    incomplete: Literal["exclude", "include", "reject"] = "exclude"
+    empty_is_missing: bool = True
+    require_unique: bool = False
+
+    @model_validator(mode="after")
+    def columns_unique(self) -> Self:
+        if not self.columns or len(set(self.columns)) != len(self.columns):
+            raise ValueError("key requires distinct nonempty columns")
+        return self
+
+
+class NumericRule(FrozenModel):
+    column: Name
+    groups: tuple[Name, ...] = ()
+    monetary: bool = False
+    currency_column: Name | None = None
+    unit: Text | None = None
+    outliers: Literal["iqr", "mad", "none"] = "iqr"
+    multiplier: Annotated[float, Field(gt=0)] = 1.5
+    min_support: Annotated[int, Field(ge=2)] = 5
+
+    @model_validator(mode="after")
+    def monetary_groups(self) -> Self:
+        if len(set(self.groups)) != len(self.groups):
+            raise ValueError("group columns must be distinct")
+        if self.monetary and (
+            self.currency_column is None or self.currency_column not in self.groups
+        ):
+            raise ValueError("money requires explicit currency grouping")
+        return self
+
+
+class EdaConfig(FrozenModel):
+    schema_version: Literal["1.0"] = "1.0"
+    rules_id: Identifier = "generic"
+    rules_revision: Annotated[int, Field(ge=1)] = 1
+    identifiers: tuple[Name, ...] = ()
+    conversions: tuple[Conversion, ...] = ()
+    keys: tuple[KeyRule, ...] = ()
+    numeric: tuple[NumericRule, ...] = ()
+    percentiles: tuple[Annotated[float, Field(ge=0, le=1)], ...] = (0.25, 0.5, 0.75)
+    stddev: Literal["population", "sample"] = "population"
+    charts: bool = False
+    resources: Resources = Field(default_factory=Resources)
+
+    @model_validator(mode="after")
+    def conversions_unique(self) -> Self:
+        if len({c.column for c in self.conversions}) != len(self.conversions):
+            raise ValueError("one explicit conversion per source column")
+        if len({c.target.casefold() for c in self.conversions}) != len(self.conversions):
+            raise ValueError("derived column names must be distinct")
+        if {i.casefold() for i in self.identifiers} & {
+            c.column.casefold() for c in self.conversions
+        }:
+            raise ValueError("identifiers retain their original representation")
+        if len(set(self.percentiles)) != len(self.percentiles):
+            raise ValueError("percentiles must be distinct")
+        return self
+
+
+class ColumnProfile(FrozenModel):
+    name: Name
+    physical_type: Text
+    rows: NonNegativeInt
+    nulls: NonNegativeInt
+    nan: NonNegativeInt
+    empty: NonNegativeInt
+    zero: NonNegativeInt
+    nonfinite: NonNegativeInt
+    valid: NonNegativeInt
+    distinct_present: NonNegativeInt
+    null_rate: float | None
+    empty_rate: float | None
+    nan_rate: float | None
+    frequencies: tuple[dict[str, object], ...]
+
+
+class DuplicateProfile(FrozenModel):
+    columns: tuple[Name, ...]
+    denominator: NonNegativeInt
+    incomplete_rows: NonNegativeInt = 0
+    policy: Text
+    repeated_groups: NonNegativeInt
+    involved_rows: NonNegativeInt
+    excess_rows: NonNegativeInt
+    excess_rate: float | None
+    examples: tuple[dict[str, object], ...]
+
+
+class Finding(FrozenModel):
+    code: Identifier
+    severity: Literal["observation", "rule_violation", "not_evaluable"]
+    column: str | None = None
+    count: NonNegativeInt | None = None
+    denominator: NonNegativeInt | None = None
+    reason: Text
+    examples: tuple[dict[str, object], ...] = ()
+
+
+class EdaResult(_ExplicitOutcome, FrozenModel):
+    _truth_value_guidance = "inspect .state; EDA never establishes equivalence or publication"
+    schema_version: Literal["1.0"] = "1.0"
+    run_id: Identifier
+    producer_version: Text
+    snapshot_id: Text
+    state: Literal["completed", "not_evaluable", "failed", "cancelled"]
+    reason: Text | None
+    elapsed_seconds: Annotated[float, Field(ge=0)]
+    calculation_elapsed_seconds: Annotated[float, Field(ge=0)] = 0.0
+    chart_state: Literal["completed", "not_requested", "not_evaluable", "failed"] = "not_requested"
+    chart_reason: str | None = None
+    source: Source
+    source_sha256: Sha256 | None
+    source_unchanged: bool | None
+    snapshot_complete: bool = False
+    config_sha256: Sha256
+    rows: NonNegativeInt | None
+    columns: tuple[ColumnProfile, ...] = ()
+    duplicates: tuple[DuplicateProfile, ...] = ()
+    conversions: tuple[dict[str, object], ...] = ()
+    numeric: tuple[dict[str, object], ...] = ()
+    findings: tuple[Finding, ...] = ()
+    environment: dict[str, str]
+    limits: tuple[Text, ...]
+    evidence_links: tuple[dict[str, str], ...] = ()
+
+    @model_validator(mode="after")
+    def completed_capture(self) -> Self:
+        if self.state == "completed" and (
+            not self.snapshot_complete
+            or self.rows is None
+            or self.source_sha256 is None
+            or self.source_unchanged is not True
+        ):
+            raise ValueError("completed diagnostics require full verified unchanged capture")
+        return self
+
+
+class ResultFile(FrozenModel):
+    path: Name
+    bytes: NonNegativeInt
+    sha256: Sha256
+
+    @model_validator(mode="after")
+    def relative_member(self) -> Self:
+        if (
+            self.path.startswith("/")
+            or "\\" in self.path
+            or ":" in self.path
+            or any(p in ("", ".", "..") for p in self.path.split("/"))
+        ):
+            raise ValueError("result member must be a normalized relative path")
+        return self
+
+
+class EdaManifest(FrozenModel):
+    schema_version: Literal["1.0"] = "1.0"
+    kind: Literal["equiframe.eda"] = "equiframe.eda"
+    run_id: Identifier
+    state: Literal["completed", "not_evaluable", "failed", "cancelled"]
+    files: tuple[ResultFile, ...]
+
+    @model_validator(mode="after")
+    def closed_names(self) -> Self:
+        names = [f.path for f in self.files]
+        if len(set(names)) != len(names) or "manifest.json" in names:
+            raise ValueError("manifest must list unique members and exclude itself")
+        if not {
+            "summary.json",
+            "source.json",
+            "config.json",
+            "findings.json",
+            "report.html",
+        } <= set(names):
+            raise ValueError("EDA manifest lacks required diagnostic documents")
+        return self

equiframe/errors.py

@@ -0,0 +1,83 @@
+"""Stable API error codes and printable JSON paths; issues omit rejected inputs."""
+
+import json
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    code: str
+    location: tuple[str | int, ...]
+    message: str
+
+    @property
+    def path(self) -> str:
+        path = "$"
+        for part in self.location:
+            if isinstance(part, int):
+                path += f"[{part}]"
+            elif part.isidentifier():
+                path += "." + part
+            else:
+                path += "[" + json.dumps(part, ensure_ascii=True) + "]"
+        return path
+
+
+class EquiFrameError(Exception):
+    code = "equiframe_error"
+
+
+class ContractValidationError(EquiFrameError):
+    code = "invalid_contract"
+
+    def __init__(self, issues: tuple[ValidationIssue, ...]) -> None:
+        self.issues = issues
+        super().__init__("\n".join(f"{item.path}: {item.message} [{item.code}]" for item in issues))
+
+
+class SchemaVersionError(ContractValidationError):
+    code = "unsupported_schema_version"
+
+
+class ContractParseError(ContractValidationError):
+    code = "invalid_json"
+
+
+class ContractIOError(EquiFrameError):
+    code = "contract_io_error"
+
+
+class InvalidExecutionInput(EquiFrameError):
+    code = "invalid_execution_input"
+
+
+class CapabilityError(InvalidExecutionInput):
+    code = "unsupported_capability"
+
+
+class MissingDependencyError(CapabilityError):
+    code = "missing_optional_dependency"
+
+
+class ArtifactIntegrityError(InvalidExecutionInput):
+    code = "artifact_integrity_error"
+
+
+class ArtifactIOError(EquiFrameError):
+    code = "artifact_io_error"
+
+
+class ExecutionCancelled(EquiFrameError):
+    code = "execution_cancelled"
+
+
+class ExecutionTimeout(EquiFrameError):
+    code = "execution_timeout"
+
+
+class ResourceLimitError(EquiFrameError):
+    code = "resource_limit"
+
+
+class NativeEngineError(EquiFrameError):
+    code = "native_engine_error"

equiframe/evidence.py

@@ -0,0 +1,375 @@
+"""Exclusive evidence publication, chained events and verification without executing code."""
+
+import hashlib
+import json
+import os
+from datetime import datetime
+from datetime import timezone as _timezone
+from pathlib import Path
+from typing import Literal, TypeVar
+
+from pydantic import BaseModel
+
+from equiframe._base import FrozenModel, Identifier, NonNegativeInt, Text
+from equiframe._document_io import write_document as _write_document
+from equiframe._regular_io import absolute_path, open_regular_file, regular_directory, regular_files
+from equiframe.errors import ArtifactIntegrityError, ArtifactIOError, ResourceLimitError
+from equiframe.local import local_path
+from equiframe.pipeline_types import EvidenceFile, PipelineResult
+from equiframe.types import ArtifactRef, Sha256
+
+UTC = _timezone.utc
+_ModelT = TypeVar("_ModelT", bound=BaseModel)
+
+MAX_DOCUMENT_BYTES = 64 * 1024 * 1024
+
+
+class _EnvironmentManifest(FrozenModel):
+    """The persisted pipeline environment is versioned evidence, not opaque JSON.
+
+    These fields were emitted by the original 1.0 writer. Reading checks their
+    format, without requiring the reader's packages or platform to match them.
+    """
+
+    schema_version: Literal["1.0"]
+    python: str
+    system: str
+    machine: str
+    packages: dict[str, str]
+
+
+def canonical_bytes(value: object) -> bytes:
+    return json.dumps(
+        value, sort_keys=True, ensure_ascii=True, allow_nan=False, separators=(",", ":")
+    ).encode("utf-8")
+
+
+def _pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON member")
+        result[key] = value
+    return result
+
+
+def _constant(value: str) -> None:
+    raise ValueError("nonstandard JSON number")
+
+
+def parse_json(data: bytes) -> object:
+    return json.loads(data.decode("utf-8"), object_pairs_hook=_pairs, parse_constant=_constant)
+
+
+def load_json(model: type[_ModelT], path: Path) -> _ModelT:
+    with open_regular_file(path) as stream:
+        data = stream.read(MAX_DOCUMENT_BYTES + 1)
+    if len(data) > MAX_DOCUMENT_BYTES:
+        raise ResourceLimitError("JSON document exceeds the 64 MiB budget")
+    parse_json(data)
+    return model.model_validate_json(data)
+
+
+def publish_json(value: BaseModel | dict[str, object], path: Path) -> None:
+    if isinstance(value, BaseModel):
+        value = type(value).model_validate(value).model_dump(mode="json")
+    _write_document(path, canonical_bytes(value) + b"\n")
+
+
+class EvidenceEvent(FrozenModel):
+    schema_version: Literal["1.0"] = "1.0"
+    sequence: NonNegativeInt
+    timestamp: Text
+    operation_id: Identifier
+    stage: Identifier
+    state: Identifier
+    code: Identifier
+    previous_sha256: Sha256
+    sha256: Sha256
+
+
+class EventJournal:
+    """One writer per unique operation; each event is flushed before work continues."""
+
+    def __init__(self, directory: Path, operation_id: str) -> None:
+        self.path = directory / "events.jsonl"
+        self.operation_id = operation_id
+        self.count = 0
+        self.head = "0" * 64
+        with self.path.open("xb"):
+            pass
+
+    def emit(self, stage: str, state: str, code: str) -> None:
+        payload = {
+            "schema_version": "1.0",
+            "sequence": self.count,
+            "timestamp": datetime.now(UTC).isoformat(),
+            "operation_id": self.operation_id,
+            "stage": stage,
+            "state": state,
+            "code": code,
+            "previous_sha256": self.head,
+        }
+        digest = hashlib.sha256(canonical_bytes(payload)).hexdigest()
+        event = EvidenceEvent.model_validate({**payload, "sha256": digest})
+        with self.path.open("ab") as stream:
+            stream.write(canonical_bytes(event.model_dump(mode="json")) + b"\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        self.head = digest
+        self.count += 1
+
+
+def verify_events(path: Path, *, operation_id: str) -> tuple[EvidenceEvent, ...]:
+    head = "0" * 64
+    events: list[EvidenceEvent] = []
+    with open_regular_file(path) as stream:
+        total = 0
+        while raw := stream.readline(1024 * 1024 + 1):
+            total += len(raw)
+            if len(raw) > 1024 * 1024 or total > MAX_DOCUMENT_BYTES:
+                raise ResourceLimitError("event journal exceeds verification budget")
+            if not raw.endswith(b"\n"):
+                raise ArtifactIntegrityError("truncated evidence event")
+            parse_json(raw)
+            event = EvidenceEvent.model_validate_json(raw)
+            payload = event.model_dump(mode="json", exclude={"sha256"})
+            if (
+                event.sequence != len(events)
+                or event.previous_sha256 != head
+                or event.operation_id != operation_id
+                or hashlib.sha256(canonical_bytes(payload)).hexdigest() != event.sha256
+            ):
+                raise ArtifactIntegrityError("event chain integrity mismatch")
+            head = event.sha256
+            events.append(event)
+    return tuple(events)
+
+
+def describe_file(path: Path, directory: Path) -> EvidenceFile:
+    path = absolute_path(path)
+    root = regular_directory(directory).resolve()
+    if not path.resolve().is_relative_to(root) or path.is_symlink():
+        raise ArtifactIntegrityError("evidence file escapes its operation directory")
+    digest = hashlib.sha256()
+    size = 0
+    with open_regular_file(path) as stream:
+        while block := stream.read(1024 * 1024):
+            digest.update(block)
+            size += len(block)
+    return EvidenceFile(
+        path=path.relative_to(root).as_posix(), sha256=digest.hexdigest(), size_bytes=size
+    )
+
+
+def inventory(directory: Path) -> tuple[EvidenceFile, ...]:
+    return tuple(describe_file(path, directory) for path in regular_files(directory))
+
+
+def verify_files(directory: Path, files: tuple[EvidenceFile, ...]) -> None:
+    for item in files:
+        path = directory / item.path
+        try:
+            observed = describe_file(path, directory)
+        except (OSError, ArtifactIOError) as error:
+            raise ArtifactIntegrityError("evidence file is missing or unreadable") from error
+        if observed != item:
+            raise ArtifactIntegrityError("evidence SHA-256 or size mismatch")
+
+
+def _verify_pipeline_artifacts(directory: Path, result: PipelineResult) -> None:
+    """Bind captured artifact references to the verified operation inventory.
+
+    Comparison sources keep the original table/execution as provenance, which
+    may belong to another operation. Their captured ``data`` snapshots, rather
+    than those external original references, are the evidence owned here.
+    """
+    root = directory.resolve()
+    listed = {item.path: item for item in result.evidence}
+    references: list[ArtifactRef] = []
+    if result.execution is not None:
+        for table in (
+            *result.execution.inputs,
+            *((result.execution.output,) if result.execution.output else ()),
+        ):
+            references.append(table.data)
+            if table.index:
+                references.append(table.index)
+    if result.rules is not None:
+        references.extend(
+            check.findings
+            for check in (*result.rules.preconditions, *result.rules.rules)
+            if check.findings is not None
+        )
+    if result.profile is not None:
+        references.extend(result.profile.metadata.artifacts)
+    if result.comparison is not None:
+        references.append(result.comparison.differences)
+        references.extend(
+            source.data
+            for source in (result.comparison.left, result.comparison.right)
+            if source is not None
+        )
+    for reference in references:
+        try:
+            artifact = local_path(reference).resolve()
+        except Exception as error:
+            raise ArtifactIntegrityError("captured evidence requires a local artifact") from error
+        if not artifact.is_relative_to(root):
+            raise ArtifactIntegrityError("captured artifact escapes its operation directory")
+        item = listed.get(artifact.relative_to(root).as_posix())
+        if item is None:
+            raise ArtifactIntegrityError("captured artifact is missing from the evidence inventory")
+        if (reference.sha256, reference.size_bytes) != (item.sha256, item.size_bytes):
+            raise ArtifactIntegrityError("captured artifact reference contradicts its inventory")
+
+
+def read_pipeline(path: Path, *, verify: bool = True) -> PipelineResult:
+    """Read a manifest; only explicit False skips byte and journal verification."""
+    if type(verify) is not bool:
+        raise TypeError("verify must be a bool; only explicit False skips integrity checks")
+    path = path / "manifest.json" if path.is_dir() else path
+    result = load_json(PipelineResult, path)
+    if verify:
+        directory = path.parent
+        verify_files(directory, result.evidence)
+        actual = {
+            item.relative_to(directory).as_posix()
+            for item in directory.rglob("*")
+            if item.is_file() and item != path
+        }
+        if actual != {item.path for item in result.evidence}:
+            raise ArtifactIntegrityError("operation files contradict the final evidence inventory")
+        _verify_pipeline_artifacts(directory, result)
+        required = {
+            "events.jsonl",
+            "pipeline.json",
+            "environment.json",
+            "report.json",
+            "report.html",
+        }
+        if not required <= {item.path for item in result.evidence}:
+            raise ArtifactIntegrityError("final manifest is missing required evidence")
+        load_json(_EnvironmentManifest, directory / "environment.json")
+        events = verify_events(directory / "events.jsonl", operation_id=result.pipeline_id)
+        if (
+            len(events) != result.event_count
+            or not events
+            or events[-1].sha256 != result.event_head_sha256
+            or events[0].stage != "pipeline"
+            or events[0].state != "started"
+            or events[-1].stage != "pipeline"
+            or events[-1].state != "finished"
+        ):
+            raise ArtifactIntegrityError("final journal does not match its manifest")
+        if load_json(type(result.spec), directory / "pipeline.json") != result.spec:
+            raise ArtifactIntegrityError("persisted pipeline configuration mismatch")
+        terminal = tuple(
+            (event.stage, event.state, event.code)
+            for event in events
+            if event.stage != "pipeline" and event.state != "started"
+        )
+        if terminal != tuple((stage.stage, stage.state, stage.code) for stage in result.stages):
+            raise ArtifactIntegrityError("journal stage outcomes contradict the final result")
+        listed = {item.path for item in result.evidence}
+        for name, value in (
+            ("execution", result.execution),
+            ("rules", result.rules),
+            ("profile", result.profile),
+            ("detection", result.detection),
+            ("comparison", result.comparison),
+            ("hybrid", result.hybrid),
+        ):
+            if value is not None and (
+                name + ".json" not in listed
+                or load_json(type(value), directory / (name + ".json")) != value
+            ):
+                raise ArtifactIntegrityError("persisted component contradicts the final result")
+        if result.detection_requested:
+            from equiframe.detector_types import DetectorBundle, detector_fingerprint
+
+            if "detector-bundle.json" not in listed:
+                raise ArtifactIntegrityError("requested detector bundle is missing")
+            bundle = load_json(DetectorBundle, directory / "detector-bundle.json")
+            if (
+                result.detection is not None
+                and result.detection.bundle_sha256 != detector_fingerprint(bundle)
+            ):
+                raise ArtifactIntegrityError("detector bundle does not match the scored bundle")
+            if result.detection is not None:
+                from equiframe.preprocessing import transform_profiles
+                from equiframe.profile_types import profile_digest
+
+                if result.detection.scores.fit_sha256 != detector_fingerprint(bundle.fit):
+                    raise ArtifactIntegrityError("scored fit fingerprint mismatch")
+                if result.detection.scores.matrix_sha256 is not None:
+                    if not (result.profile is not None):
+                        raise AssertionError("Internal invariant check failed.")
+                    matrix = transform_profiles(bundle.fit.preprocessor, (result.profile.vector,))
+                    if result.detection.scores.matrix_sha256 != profile_digest(
+                        matrix.model_dump(mode="json")
+                    ):
+                        raise ArtifactIntegrityError("scored matrix does not belong to the profile")
+        from equiframe._report_format_v1 import pipeline_html_v1, pipeline_summary_v1
+
+        summary = pipeline_summary_v1(result)
+        if parse_json((directory / "report.json").read_bytes()) != summary or (
+            (directory / "report.html").read_bytes() != pipeline_html_v1(summary).encode("utf8")
+        ):
+            raise ArtifactIntegrityError("report contradicts the final result")
+    return result
+
+
+def inspect_evidence(directory: Path) -> dict[str, object]:
+    """An interrupted operation remains inspectable but can never claim completion."""
+    if (directory / "migration.json").exists():
+        from equiframe.migration import migration_summary, read_migration
+
+        migrated = read_migration(directory)
+        return {
+            **migration_summary(migrated),
+            "finalized": True,
+            "events": migrated.event_count,
+            "files": len(migrated.evidence),
+        }
+    if (directory / "reduction.json").exists():
+        from equiframe.reduction import read_reduction
+
+        reduced = read_reduction(directory)
+        return {
+            "reduction_id": reduced.reduction_id,
+            "finalized": True,
+            "complete": reduced.status in ("reduced", "unchanged"),
+            "status": reduced.status,
+            "evaluations": reduced.evaluations,
+            "minimality": reduced.minimality,
+            "files": len(reduced.evidence),
+        }
+    if (directory / "manifest.json").exists():
+        result = read_pipeline(directory)
+        return {
+            "pipeline_id": result.pipeline_id,
+            "finalized": True,
+            "complete": result.complete,
+            "exit_code": result.exit_code,
+            "events": result.event_count,
+            "files": len(result.evidence),
+        }
+    events = verify_events(directory / "events.jsonl", operation_id=directory.name)
+    if directory.name.startswith("migration_"):
+        return {
+            "migration_id": directory.name,
+            "finalized": False,
+            "complete": False,
+            "exit_code": 3,
+            "events": len(events),
+            "last_stage": events[-1].stage if events else None,
+        }
+    return {
+        "pipeline_id": directory.name,
+        "finalized": False,
+        "complete": False,
+        "exit_code": 3,
+        "events": len(events),
+        "last_stage": events[-1].stage if events else None,
+    }