validibot-shared 0.4.4__tar.gz → 0.5.1__tar.gz

{validibot_shared-0.4.4 → validibot_shared-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.4.4
+Version: 0.5.1
 Summary: Shared library for data interchange between Validibot and validator containers
 Project-URL: Homepage, https://validibot.com
 Project-URL: Documentation, https://docs.validibot.com
@@ -24,10 +24,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: pydantic==2.13.3
+Requires-Dist: pydantic<3.0,>=2.13
 Provides-Extra: dev
-Requires-Dist: pytest==9.0.2; extra == 'dev'
-Requires-Dist: ruff==0.14.8; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">

{validibot_shared-0.4.4 → validibot_shared-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.4.4"
+version = "0.5.1"
 description = "Shared library for data interchange between Validibot and validator containers"
 readme = "README.md"
 license = { text = "MIT" }
@@ -32,10 +32,10 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Scientific/Engineering",
 ]
-dependencies = ["pydantic==2.13.3"]
+dependencies = ["pydantic>=2.13,<3.0"]
 
 [project.optional-dependencies]
-dev = ["pytest==9.0.2", "ruff==0.14.8"]
+dev = ["pytest==9.0.3", "ruff==0.15.12"]
 
 [project.urls]
 Homepage = "https://validibot.com"

validibot_shared-0.5.1/tests/test_evidence_manifest.py

@@ -0,0 +1,160 @@
+"""Tests for ``validibot_shared.evidence`` schema (validibot.evidence.v1).
+
+ADR-2026-04-27 Phase 4 Session A: pin the schema's contract at the
+shared-package boundary. The Validibot Django app is one consumer;
+external verifiers (validibot-pro, third-party tools) are others.
+These tests verify the shape stays stable across releases.
+
+What this file covers
+=====================
+
+1. ``schema_version`` is pinned to ``validibot.evidence.v1`` and
+   rejected if other values are passed (Literal type-narrows).
+2. The model rejects unknown top-level keys (``extra="forbid"``).
+3. Frozen Pydantic models — instances cannot be mutated after
+   construction, which is the property the producer's hash
+   computation depends on.
+4. Optional fields default sensibly so producers can build a
+   minimal Session-A manifest without populating Session-B fields.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from validibot_shared.evidence import (
+    SCHEMA_VERSION,
+    EvidenceManifest,
+    ManifestPayloadDigests,
+    ManifestRetentionInfo,
+    StepValidatorRecord,
+    WorkflowContractSnapshot,
+)
+
+
+def _minimal_manifest_kwargs():
+    """Build the smallest set of kwargs that produces a valid manifest."""
+    return {
+        "run_id": "abc-123",
+        "workflow_id": 1,
+        "workflow_slug": "compliance",
+        "workflow_version": "1.0",
+        "org_id": 42,
+        "executed_at": "2026-05-02T12:00:00+00:00",
+        "status": "SUCCEEDED",
+        "workflow_contract": WorkflowContractSnapshot(
+            allowed_file_types=["json"],
+        ),
+        "retention": ManifestRetentionInfo(retention_class="STORE_30_DAYS"),
+    }
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Schema version contract
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestSchemaVersion:
+    def test_default_schema_version_is_v1(self):
+        manifest = EvidenceManifest(**_minimal_manifest_kwargs())
+        assert manifest.schema_version == "validibot.evidence.v1"
+
+    def test_schema_version_constant_matches(self):
+        assert SCHEMA_VERSION == "validibot.evidence.v1"
+
+    def test_rejects_other_schema_versions(self):
+        """Literal narrowing — passing a non-v1 string fails validation."""
+        with pytest.raises(ValidationError):
+            EvidenceManifest(
+                **_minimal_manifest_kwargs(),
+                schema_version="validibot.evidence.v2",
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Strict shape (extra="forbid") and frozen instances
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestStrictShape:
+    def test_unknown_top_level_keys_rejected(self):
+        """Producers can't accidentally smuggle in undocumented data."""
+        with pytest.raises(ValidationError):
+            EvidenceManifest(
+                **_minimal_manifest_kwargs(),
+                extra_undeclared_field="oops",
+            )
+
+    def test_manifest_is_frozen(self):
+        """Instances cannot be mutated post-construction.
+
+        The hash producers compute over canonical JSON depends on
+        the fact that you can't tweak a field after the model is
+        built. ``frozen=True`` enforces that at the Pydantic level.
+        """
+        manifest = EvidenceManifest(**_minimal_manifest_kwargs())
+        with pytest.raises(ValidationError):
+            manifest.run_id = "tampered"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Optional fields and defaults (Session A vs Session B distinction)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestOptionalFields:
+    def test_payload_digests_defaults_to_all_none(self):
+        """Session A: producers leave digests empty."""
+        manifest = EvidenceManifest(**_minimal_manifest_kwargs())
+        assert manifest.payload_digests.input_sha256 is None
+        assert manifest.payload_digests.output_envelope_sha256 is None
+
+    def test_session_b_can_populate_digests(self):
+        """Session B's redaction path drops in real hashes."""
+        manifest = EvidenceManifest(
+            **_minimal_manifest_kwargs(),
+            payload_digests=ManifestPayloadDigests(
+                input_sha256="a" * 64,
+                output_envelope_sha256="b" * 64,
+            ),
+        )
+        assert manifest.payload_digests.input_sha256 == "a" * 64
+
+    def test_input_schema_optional(self):
+        """Workflows without structured input contract leave it None."""
+        manifest = EvidenceManifest(**_minimal_manifest_kwargs())
+        assert manifest.input_schema is None
+
+    def test_steps_default_to_empty_list(self):
+        """A workflow with no steps still produces a valid manifest."""
+        manifest = EvidenceManifest(**_minimal_manifest_kwargs())
+        assert manifest.steps == []
+
+
+# ──────────────────────────────────────────────────────────────────────
+# StepValidatorRecord — semantic_digest can be None for legacy validators
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestStepValidatorRecord:
+    def test_semantic_digest_optional(self):
+        """Custom validators with no digest -> None in the manifest."""
+        record = StepValidatorRecord(
+            step_id=1,
+            step_order=0,
+            validator_slug="custom-validator",
+            validator_version="1.0",
+        )
+        assert record.validator_semantic_digest is None
+
+    def test_records_are_frozen(self):
+        """Step records cannot be mutated after construction."""
+        record = StepValidatorRecord(
+            step_id=1,
+            step_order=0,
+            validator_slug="x",
+            validator_version="1.0",
+        )
+        with pytest.raises(ValidationError):
+            record.validator_slug = "tampered"

validibot_shared-0.5.1/validibot_shared/__init__.py

@@ -0,0 +1,32 @@
+"""Shared domain models and utilities for Validibot."""
+
+from validibot_shared.energyplus.models import (
+    EnergyPlusSimulationLogs,
+    EnergyPlusSimulationMetrics,
+    EnergyPlusSimulationOutputs,
+)
+from validibot_shared.evidence import (
+    SCHEMA_VERSION as EVIDENCE_SCHEMA_VERSION,
+)
+from validibot_shared.evidence import (
+    EvidenceManifest,
+    ManifestPayloadDigests,
+    ManifestRetentionInfo,
+    StepValidatorRecord,
+    WorkflowContractSnapshot,
+)
+from validibot_shared.fmu.models import FMUProbeResult, FMUVariableMeta
+
+__all__ = [
+    "EVIDENCE_SCHEMA_VERSION",
+    "EnergyPlusSimulationLogs",
+    "EnergyPlusSimulationMetrics",
+    "EnergyPlusSimulationOutputs",
+    "EvidenceManifest",
+    "FMUProbeResult",
+    "FMUVariableMeta",
+    "ManifestPayloadDigests",
+    "ManifestRetentionInfo",
+    "StepValidatorRecord",
+    "WorkflowContractSnapshot",
+]

validibot_shared-0.5.1/validibot_shared/evidence/__init__.py

@@ -0,0 +1,26 @@
+"""Evidence-manifest schemas (``validibot.evidence.vN``).
+
+Public API for both the Validibot Django app (which generates
+manifests when validation runs complete) and the Pro / external
+verifiers (which sign / verify them). The schemas are intentionally
+storage-agnostic and Django-free so any consumer can validate a
+manifest without pulling in the application stack.
+"""
+
+from validibot_shared.evidence.manifest import (
+    SCHEMA_VERSION,
+    EvidenceManifest,
+    ManifestPayloadDigests,
+    ManifestRetentionInfo,
+    StepValidatorRecord,
+    WorkflowContractSnapshot,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "EvidenceManifest",
+    "ManifestPayloadDigests",
+    "ManifestRetentionInfo",
+    "StepValidatorRecord",
+    "WorkflowContractSnapshot",
+]

validibot_shared-0.5.1/validibot_shared/evidence/manifest.py

@@ -0,0 +1,237 @@
+"""Pydantic schema for validibot evidence manifests (``validibot.evidence.v1``).
+
+ADR-2026-04-27 (Validibot Trust ADR), Phase 4: every completed
+validation run produces a manifest documenting "these are the rules
+and inputs run X was operating under." The manifest is the data
+structure that makes evidence bundles, signed credentials, and
+external verification possible.
+
+Why this lives in ``validibot-shared``
+======================================
+
+The manifest is the contract between *manifest producers* (the
+Validibot Django app) and *verifiers* (the validibot-pro signing /
+verification flow, or any external party that receives an exported
+bundle). Pinning the schema in the shared package:
+
+1. Lets external verifiers depend on a single PyPI package without
+   pulling in the Django stack.
+2. Keeps producer and verifier locked to the same version of the
+   shape — additive changes preserve v1 by policy; breaking changes
+   require a v2 module beside this one.
+
+Schema versioning policy
+========================
+
+The string ``validibot.evidence.v1`` in :data:`SCHEMA_VERSION` is the
+*compatibility contract*. Additive changes (new optional fields,
+loosened validators) preserve v1. Removing or renaming fields, or
+tightening a validator in a way that rejects previously-valid input,
+requires a v2 module placed alongside this one (``manifest_v2.py``).
+
+What's in the schema (Phase 4 phasing)
+======================================
+
+Session A (this module): identity, workflow contract snapshot,
+validator metadata per step, input contract, retention class, and
+schema slots for fields Sessions B + C will populate.
+
+Session B (deferred): the ``payload_digests`` slot gets populated
+with input + output hashes; ``retention.redactions_applied`` lists
+fields stripped under retention policy. The schema shape itself
+does not change, only the values landing in optional fields.
+
+Session C (deferred): credentials sign the canonical-JSON bytes of
+this manifest externally. The signature does NOT live inside the
+manifest — verifiers receive the manifest + a separate signature
+file in the export bundle.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# The string consumers parse to know what manifest shape to expect.
+# Bump only on breaking changes; additive changes stay v1.
+SCHEMA_VERSION = "validibot.evidence.v1"
+
+
+class StepValidatorRecord(BaseModel):
+    """Per-step validator identity at run time.
+
+    Pinned values: a step's validator is referenced by foreign key
+    on the application side, but the *meaning* of that reference
+    depends on the validator's ``semantic_digest`` at run time. We
+    snapshot the digest into the manifest so future verifiers can
+    prove "the validator behind this step had digest D when this run
+    executed."
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    step_id: int = Field(
+        description="Producer-side WorkflowStep primary key at run time."
+    )
+    step_order: int = Field(description="Execution position (lower = earlier).")
+    validator_slug: str = Field(description="Validator's stable slug.")
+    validator_version: str = Field(description="Validator's version string.")
+    # Optional because custom org validators have empty digests by
+    # design (no ValidatorConfig to hash). Producers' auditors flag
+    # this as a coverage gap.
+    validator_semantic_digest: str | None = Field(
+        default=None,
+        description=(
+            "SHA-256 hex of the validator's semantic config. None for "
+            "custom validators that aren't synced from a "
+            "ValidatorConfig — the manifest documents the absence so "
+            "verifiers know to expect a legacy-versioning gap there."
+        ),
+    )
+
+
+class WorkflowContractSnapshot(BaseModel):
+    """Frozen snapshot of the workflow's launch-contract fields.
+
+    These are the fields that determine *what the workflow does*
+    when it runs (file types accepted, retention policy, agent
+    publication state). Pinning them in the manifest lets a future
+    verifier answer "what rules was this run operating under?"
+    without consulting the live producer database (which may have
+    moved on to a newer workflow version).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    allowed_file_types: list[str] = Field(default_factory=list)
+    data_retention: str = ""
+    output_retention: str = ""
+    agent_billing_mode: str = ""
+    agent_price_cents: int | None = None
+    agent_max_launches_per_hour: int | None = None
+    agent_public_discovery: bool = False
+    agent_access_enabled: bool = False
+
+
+class ManifestRetentionInfo(BaseModel):
+    """Retention class + applied-redaction summary.
+
+    Session A populates ``retention_class`` from the workflow's
+    ``data_retention`` so consumers know what the run agreed to.
+    Session B will populate ``redactions_applied`` with the list of
+    fields the retention policy stripped before serialisation. For
+    Session A the field is empty.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    retention_class: str = Field(
+        description=(
+            "Workflow data-retention setting at run time "
+            "(e.g. 'DO_NOT_STORE', 'STORE_30_DAYS')."
+        ),
+    )
+    redactions_applied: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Names of manifest fields that were redacted under this "
+            "retention class. Session A leaves this empty; Session B "
+            "fills it in when the redaction policy lands."
+        ),
+    )
+
+
+class ManifestPayloadDigests(BaseModel):
+    """Hashes of the run's payload data.
+
+    Session A leaves these as None — the field exists in the schema
+    so consumers can write code that handles both the Session A
+    ("not yet computed") and Session B ("populated from the run's
+    submission and output envelope") cases without a v2 bump.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    input_sha256: str | None = Field(
+        default=None,
+        description=(
+            "SHA-256 hex of the submission's primary file bytes at run "
+            "time. Always present in Session B — even when "
+            "DO_NOT_STORE purges the bytes themselves, the hash is "
+            "the immutable proof the run consumed input matching it."
+        ),
+    )
+    output_envelope_sha256: str | None = Field(
+        default=None,
+        description=(
+            "SHA-256 hex of the canonical output envelope JSON. None "
+            "for runs whose retention policy excludes outputs."
+        ),
+    )
+
+
+class EvidenceManifest(BaseModel):
+    """Top-level evidence manifest for a single validation run.
+
+    The canonical JSON form of this model — produced by serialising
+    the dict from ``model_dump(mode="json")`` via ``json.dumps`` with
+    ``sort_keys=True`` and ``separators=(",",":")`` — is what gets
+    hashed and persisted by the producer.
+
+    Producers store ``SHA-256(canonical_json_bytes)`` alongside the
+    file. Tampering with the manifest after persistence is detectable
+    via re-fetch + re-hash.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: Literal["validibot.evidence.v1"] = Field(
+        default=SCHEMA_VERSION,
+        description="Pinned schema-version string. Verifiers reject other values.",
+    )
+    run_id: str = Field(description="Producer-side run UUID (hex string).")
+    workflow_id: int = Field(description="Workflow primary key at run time.")
+    workflow_slug: str = Field(description="Workflow slug at run time.")
+    workflow_version: str = Field(description="Workflow version at run time.")
+    org_id: int = Field(description="Organization primary key that owned the run.")
+    executed_at: str = Field(
+        description=(
+            "ISO 8601 UTC timestamp of run completion. String rather "
+            "than datetime so canonical-JSON bytes are stable across "
+            "Python versions and timezone-aware/naïve serialisation "
+            "differences."
+        ),
+    )
+    status: str = Field(
+        description=("Run status at completion (SUCCEEDED / FAILED / CANCELED)."),
+    )
+    workflow_contract: WorkflowContractSnapshot
+    steps: list[StepValidatorRecord] = Field(
+        default_factory=list,
+        description="Per-step validator records, ordered by step.order.",
+    )
+    input_schema: dict | None = Field(
+        default=None,
+        description=(
+            "Workflow's structured input contract (canonical JSON Schema) "
+            "at run time. None when the workflow has no structured input "
+            "contract. The schema itself is the contract; the input "
+            "hash in payload_digests is the proof of conformance."
+        ),
+    )
+    retention: ManifestRetentionInfo
+    payload_digests: ManifestPayloadDigests = Field(
+        default_factory=ManifestPayloadDigests,
+        description="Session A: empty. Session B: input + output hashes.",
+    )
+
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "EvidenceManifest",
+    "ManifestPayloadDigests",
+    "ManifestRetentionInfo",
+    "StepValidatorRecord",
+    "WorkflowContractSnapshot",
+]

validibot_shared-0.4.4/validibot_shared/__init__.py

@@ -1,16 +0,0 @@
-"""Shared domain models and utilities for Simple Validations."""
-
-from validibot_shared.energyplus.models import (
-    EnergyPlusSimulationLogs,
-    EnergyPlusSimulationMetrics,
-    EnergyPlusSimulationOutputs,
-)
-from validibot_shared.fmu.models import FMUProbeResult, FMUVariableMeta
-
-__all__ = [
-    "EnergyPlusSimulationLogs",
-    "EnergyPlusSimulationMetrics",
-    "EnergyPlusSimulationOutputs",
-    "FMUProbeResult",
-    "FMUVariableMeta",
-]