validibot-shared 0.10.0__tar.gz → 0.17.0__tar.gz

{validibot_shared-0.10.0 → validibot_shared-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.10.0
+Version: 0.17.0
 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,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: defusedxml<0.8,>=0.7.1
 Requires-Dist: pydantic<3.0,>=2.13
 Provides-Extra: dev
 Requires-Dist: pytest==9.1.1; extra == 'dev'
-Requires-Dist: ruff==0.15.18; extra == 'dev'
+Requires-Dist: ruff==0.15.21; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -165,12 +166,49 @@ Supporting models include:
 
 | Class | Purpose |
 |-------|---------|
-| `InputFileItem` | File reference with URI, MIME type, and role |
+| `InputFileItem` | File reference with URI, MIME type, role, exact size, SHA-256, and immutable storage version |
+| `ResourceFileItem` | Managed auxiliary file reference with safe name, URI, resource type, and byte identity |
 | `ValidatorInfo` | Validator identification (ID, type, version) |
-| `ExecutionContext` | Callback URL, execution bundle URI, timeout |
+| `ExecutionContext` | Attempt identity, callback nonce commitment, bundle URI, and timeout |
 | `ValidationMessage` | Individual finding (error, warning, info) |
 | `ValidationMetric` | Named numeric metric with optional unit |
 | `ValidationArtifact` | Output file reference (reports, logs, etc.) |
+| `ArtifactRef` | Indexed run artifact reference for workflow/evidence control planes |
+| `FilePortContract` | Shared file-port vocabulary for declared validator file inputs/outputs |
+
+### Designing File Inputs
+
+The shared envelope exposes file inputs as `input_files` and `resource_files`.
+Validator authors should still design those files as **declared ports** in the
+core platform.
+
+A file port answers:
+
+- what the file means to the validator (`primary_model`, `weather_file`,
+  `data_graph`, `xml_document`, `schema_file`, `fmu_model`);
+- how many files are valid (`1..1`, `0..1`, or a future collection);
+- which envelope channel it renders into (`input_files` or `resource_files`);
+- which backend role/type it uses (`primary-model`, `weather`, `fmu`,
+  `data-graph`);
+- which formats and MIME types are accepted;
+- whether the source may be a submitted file, workflow resource, upstream
+  artifact, or signal containing an artifact reference.
+
+Keep small configuration in typed `inputs`. Use file/resource/artifact ports
+for bytes. For example, EnergyPlus timestep settings belong in
+`EnergyPlusInputs`; the IDF/epJSON model and EPW weather file belong in file
+ports rendered to `input_files` / `resource_files`.
+
+Backends should read files by role and `port_key` when available, not by
+assuming `input_files[0]` forever. Every file item commits to an exact size,
+SHA-256, and provider-specific immutable storage version; runtimes must verify
+those fields while streaming before a validator parses or executes the bytes.
+
+`ArtifactRef` and `FilePortContract` live in
+`validibot_shared.validations.artifacts`. `InputFileItem` and
+`ResourceFileItem` also accept an optional `port_key` so a backend or evidence
+builder can correlate an envelope item back to the declared Validibot port
+without relying only on backend role/type strings.
 
 ### Typed Subclassing Pattern
 
@@ -203,9 +241,14 @@ validibot_shared/
 ├── energyplus/           # EnergyPlus-specific models and envelopes
 │   ├── models.py         # Simulation output models (metrics, results)
 │   └── envelopes.py      # Typed envelope subclasses
-└── fmu/                  # FMU-specific models
-    ├── models.py         # Probe result models
-    └── envelopes.py      # FMU envelope subclasses
+├── fmu/                  # FMU-specific models
+│   ├── models.py         # Probe/simulation result models
+│   └── envelopes.py      # FMU envelope subclasses
+├── shacl/                # SHACL isolated-backend envelopes
+│   └── envelopes.py      # SHACL inputs/outputs and builder
+└── schematron/           # Schematron isolated-backend envelopes
+    ├── envelopes.py      # Schematron inputs/outputs and builder
+    └── svrl.py           # SVRL parsing helpers
 ```
 
 ## Usage Examples
@@ -213,8 +256,12 @@ validibot_shared/
 ### Creating an Input Envelope
 
 ```python
+import secrets
+
+from validibot_shared.canonicalization import compute_callback_nonce_commitment
 from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     OrganizationInfo,
@@ -224,6 +271,8 @@ from validibot_shared.validations.envelopes import (
     WorkflowInfo,
 )
 
+callback_nonce = secrets.token_urlsafe(32)
+
 envelope = EnergyPlusInputEnvelope(
     run_id="run-123",
     validator=ValidatorInfo(
@@ -243,12 +292,24 @@ envelope = EnergyPlusInputEnvelope(
             mime_type=SupportedMimeType.ENERGYPLUS_IDF,
             role="primary-model",
             uri="gs://bucket/model.idf",
+            size_bytes=12345,
+            sha256="0123456789abcdef" * 4,
+            storage_version="1700000000000000",
         ),
     ],
     inputs=EnergyPlusInputs(timestep_per_hour=4),
     context=ExecutionContext(
         callback_url="https://api.example.com/callback",
-        execution_bundle_uri="gs://bucket/run-123/",
+        callback_id="execution-attempt-attempt-123",
+        callback_nonce=callback_nonce,
+        callback_nonce_commitment=compute_callback_nonce_commitment(callback_nonce),
+        execution_bundle_uri="gs://bucket/runs/org-123/run-123/attempts/attempt-123/",
+        execution_attempt_id="attempt-123",
+        step_run_id="step-run-789",
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        expected_output_uri=(
+            "gs://bucket/runs/org-123/run-123/attempts/attempt-123/output.json"
+        ),
     ),
 )
 

{validibot_shared-0.10.0 → validibot_shared-0.17.0}/README.md

@@ -133,12 +133,49 @@ Supporting models include:
 
 | Class | Purpose |
 |-------|---------|
-| `InputFileItem` | File reference with URI, MIME type, and role |
+| `InputFileItem` | File reference with URI, MIME type, role, exact size, SHA-256, and immutable storage version |
+| `ResourceFileItem` | Managed auxiliary file reference with safe name, URI, resource type, and byte identity |
 | `ValidatorInfo` | Validator identification (ID, type, version) |
-| `ExecutionContext` | Callback URL, execution bundle URI, timeout |
+| `ExecutionContext` | Attempt identity, callback nonce commitment, bundle URI, and timeout |
 | `ValidationMessage` | Individual finding (error, warning, info) |
 | `ValidationMetric` | Named numeric metric with optional unit |
 | `ValidationArtifact` | Output file reference (reports, logs, etc.) |
+| `ArtifactRef` | Indexed run artifact reference for workflow/evidence control planes |
+| `FilePortContract` | Shared file-port vocabulary for declared validator file inputs/outputs |
+
+### Designing File Inputs
+
+The shared envelope exposes file inputs as `input_files` and `resource_files`.
+Validator authors should still design those files as **declared ports** in the
+core platform.
+
+A file port answers:
+
+- what the file means to the validator (`primary_model`, `weather_file`,
+  `data_graph`, `xml_document`, `schema_file`, `fmu_model`);
+- how many files are valid (`1..1`, `0..1`, or a future collection);
+- which envelope channel it renders into (`input_files` or `resource_files`);
+- which backend role/type it uses (`primary-model`, `weather`, `fmu`,
+  `data-graph`);
+- which formats and MIME types are accepted;
+- whether the source may be a submitted file, workflow resource, upstream
+  artifact, or signal containing an artifact reference.
+
+Keep small configuration in typed `inputs`. Use file/resource/artifact ports
+for bytes. For example, EnergyPlus timestep settings belong in
+`EnergyPlusInputs`; the IDF/epJSON model and EPW weather file belong in file
+ports rendered to `input_files` / `resource_files`.
+
+Backends should read files by role and `port_key` when available, not by
+assuming `input_files[0]` forever. Every file item commits to an exact size,
+SHA-256, and provider-specific immutable storage version; runtimes must verify
+those fields while streaming before a validator parses or executes the bytes.
+
+`ArtifactRef` and `FilePortContract` live in
+`validibot_shared.validations.artifacts`. `InputFileItem` and
+`ResourceFileItem` also accept an optional `port_key` so a backend or evidence
+builder can correlate an envelope item back to the declared Validibot port
+without relying only on backend role/type strings.
 
 ### Typed Subclassing Pattern
 
@@ -171,9 +208,14 @@ validibot_shared/
 ├── energyplus/           # EnergyPlus-specific models and envelopes
 │   ├── models.py         # Simulation output models (metrics, results)
 │   └── envelopes.py      # Typed envelope subclasses
-└── fmu/                  # FMU-specific models
-    ├── models.py         # Probe result models
-    └── envelopes.py      # FMU envelope subclasses
+├── fmu/                  # FMU-specific models
+│   ├── models.py         # Probe/simulation result models
+│   └── envelopes.py      # FMU envelope subclasses
+├── shacl/                # SHACL isolated-backend envelopes
+│   └── envelopes.py      # SHACL inputs/outputs and builder
+└── schematron/           # Schematron isolated-backend envelopes
+    ├── envelopes.py      # Schematron inputs/outputs and builder
+    └── svrl.py           # SVRL parsing helpers
 ```
 
 ## Usage Examples
@@ -181,8 +223,12 @@ validibot_shared/
 ### Creating an Input Envelope
 
 ```python
+import secrets
+
+from validibot_shared.canonicalization import compute_callback_nonce_commitment
 from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     OrganizationInfo,
@@ -192,6 +238,8 @@ from validibot_shared.validations.envelopes import (
     WorkflowInfo,
 )
 
+callback_nonce = secrets.token_urlsafe(32)
+
 envelope = EnergyPlusInputEnvelope(
     run_id="run-123",
     validator=ValidatorInfo(
@@ -211,12 +259,24 @@ envelope = EnergyPlusInputEnvelope(
             mime_type=SupportedMimeType.ENERGYPLUS_IDF,
             role="primary-model",
             uri="gs://bucket/model.idf",
+            size_bytes=12345,
+            sha256="0123456789abcdef" * 4,
+            storage_version="1700000000000000",
         ),
     ],
     inputs=EnergyPlusInputs(timestep_per_hour=4),
     context=ExecutionContext(
         callback_url="https://api.example.com/callback",
-        execution_bundle_uri="gs://bucket/run-123/",
+        callback_id="execution-attempt-attempt-123",
+        callback_nonce=callback_nonce,
+        callback_nonce_commitment=compute_callback_nonce_commitment(callback_nonce),
+        execution_bundle_uri="gs://bucket/runs/org-123/run-123/attempts/attempt-123/",
+        execution_attempt_id="attempt-123",
+        step_run_id="step-run-789",
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        expected_output_uri=(
+            "gs://bucket/runs/org-123/run-123/attempts/attempt-123/output.json"
+        ),
     ),
 )
 

{validibot_shared-0.10.0 → validibot_shared-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.10.0"
+version = "0.17.0"
 description = "Shared library for data interchange between Validibot and validator containers"
 readme = "README.md"
 license = { text = "MIT" }
@@ -34,10 +34,10 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Scientific/Engineering",
 ]
-dependencies = ["pydantic>=2.13,<3.0"]
+dependencies = ["pydantic>=2.13,<3.0", "defusedxml>=0.7.1,<0.8"]
 
 [project.optional-dependencies]
-dev = ["pytest==9.1.1", "ruff==0.15.18"]
+dev = ["pytest==9.1.1", "ruff==0.15.21"]
 
 [project.urls]
 Homepage = "https://validibot.com"

validibot_shared-0.17.0/tests/test_artifacts.py

@@ -0,0 +1,124 @@
+"""Tests for shared artifact references and file-port contracts.
+
+These schemas form the cross-repo contract between Django, validator
+backends, evidence builders, and future UI/API projections. The tests focus
+on JSON shape stability and enum serialization because those are the pieces
+that must remain portable across repos.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from validibot_shared.validations.artifacts import (
+    ArtifactKind,
+    ArtifactRef,
+    BindingSourceScope,
+    DefaultSourceStrategy,
+    EnvelopeChannel,
+    FilePortContract,
+    StepIODirection,
+    StepIOMedium,
+)
+
+
+def test_artifact_ref_serializes_as_json_safe_control_plane_object():
+    """ArtifactRef should carry lineage metadata without embedding bytes."""
+    ref = ArtifactRef(
+        artifact_id="artifact-1",
+        run_id="run-1",
+        step_run_id="step-run-1",
+        producer_step_key="build_model",
+        contract_key="generated_model",
+        name="model.epjson",
+        role="primary-model",
+        kind=ArtifactKind.FILE,
+        media_type="application/vnd.energyplus.epjson",
+        data_format="energyplus_epjson",
+        filename="model.epjson",
+        size_bytes=1234,
+        sha256="a" * 64,
+        storage_version="1700000000000000",
+        uri="gs://bucket/runs/run-1/model.epjson",
+        producer_validator_type="BUILDINGSYNC_TO_ENERGYPLUS",
+        producer_validator_version="1",
+        producer_backend_image_digest="repo/image@sha256:" + "b" * 64,
+        retention_class="standard",
+    )
+
+    dumped = ref.model_dump(mode="json")
+
+    assert dumped["schema_version"] == "validibot.artifact_ref.v1"
+    assert dumped["kind"] == "file"
+    assert dumped["producer_step_key"] == "build_model"
+    assert dumped["uri"].startswith("gs://")
+    assert dumped["storage_version"] == "1700000000000000"
+
+
+@pytest.mark.parametrize("missing", ["size_bytes", "sha256", "storage_version", "uri"])
+def test_artifact_ref_requires_complete_storage_identity(missing):
+    """Artifact consumers must never receive a partial or mutable file pointer."""
+    payload = {
+        "artifact_id": "artifact-1",
+        "run_id": "run-1",
+        "step_run_id": "step-run-1",
+        "producer_step_key": "build_model",
+        "contract_key": "generated_model",
+        "name": "model.epjson",
+        "size_bytes": 1234,
+        "sha256": "a" * 64,
+        "storage_version": "1700000000000000",
+        "uri": "gs://bucket/runs/run-1/model.epjson",
+    }
+    payload.pop(missing)
+
+    with pytest.raises(ValidationError):
+        ArtifactRef(**payload)
+
+
+def test_file_port_contract_serializes_shared_vocabulary():
+    """File-port contracts should expose stable enum values to every repo."""
+    contract = FilePortContract(
+        contract_key="primary_model",
+        label="Primary Model",
+        direction=StepIODirection.INPUT,
+        io_medium=StepIOMedium.ARTIFACT,
+        envelope_channel=EnvelopeChannel.INPUT_FILES,
+        role="primary-model",
+        artifact_kind=ArtifactKind.FILE,
+        min_items=1,
+        max_items=1,
+        accepted_data_formats=["energyplus_idf", "energyplus_epjson"],
+        accepted_media_types=[
+            "application/vnd.energyplus.idf",
+            "application/vnd.energyplus.epjson",
+        ],
+        allowed_source_scopes=[
+            BindingSourceScope.SUBMISSION_FILE,
+            BindingSourceScope.UPSTREAM_ARTIFACT,
+            BindingSourceScope.SIGNAL,
+        ],
+        default_source_strategy=DefaultSourceStrategy.SUBMITTED_FILE_FIRST,
+    )
+
+    dumped = contract.model_dump(mode="json")
+
+    assert dumped["contract_key"] == "primary_model"
+    assert dumped["io_medium"] == "artifact"
+    assert dumped["envelope_channel"] == "input_files"
+    assert dumped["allowed_source_scopes"] == [
+        "submission_file",
+        "upstream_artifact",
+        "signal",
+    ]
+    assert dumped["default_source_strategy"] == "submitted_file_first"
+
+
+def test_file_port_contract_rejects_extra_fields():
+    """The contract should stay explicit rather than absorbing typos."""
+    with pytest.raises(ValidationError):
+        FilePortContract(
+            contract_key="primary_model",
+            direction=StepIODirection.INPUT,
+            envelope_channel=EnvelopeChannel.INPUT_FILES,
+            unknown=True,
+        )

validibot_shared-0.17.0/tests/test_callback_nonce_contract.py

@@ -0,0 +1,144 @@
+"""Tests for the strict callback nonce portion of the attempt contract.
+
+Asynchronous validator callbacks need both delivery idempotency and proof that
+the sender received the exact input envelope for one execution attempt. The
+callback ID supplies the first property; the per-attempt nonce supplies the
+second. These tests keep raw secrets out of model representations, require a
+matching public commitment, preserve synchronous no-callback operation, and
+reject the older attempt-v1 contract instead of silently accepting weaker
+authentication.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from validibot_shared.canonicalization import compute_callback_nonce_commitment
+from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
+    ExecutionContext,
+    ValidationCallback,
+    ValidationOutputEnvelope,
+    ValidationStatus,
+)
+
+CALLBACK_NONCE = "A" * 43
+CALLBACK_COMMITMENT = compute_callback_nonce_commitment(CALLBACK_NONCE)
+
+
+def _context_kwargs() -> dict[str, object]:
+    """Return the non-secret fields required by one asynchronous attempt."""
+    return {
+        "execution_attempt_id": "attempt-1",
+        "step_run_id": "step-run-1",
+        "attempt_contract_version": ATTEMPT_CONTRACT_VERSION,
+        "expected_output_uri": "gs://bucket/attempt-1/output.json",
+        "callback_url": "https://example.com/callback",
+        "execution_bundle_uri": "gs://bucket/attempt-1/",
+    }
+
+
+def test_async_context_requires_callback_id_and_nonce_pair() -> None:
+    """An enabled callback must not validate with only public routing metadata."""
+    with pytest.raises(ValidationError, match="callback_id is required"):
+        ExecutionContext(**_context_kwargs())
+
+    with pytest.raises(ValidationError, match="required when callbacks are enabled"):
+        ExecutionContext(
+            **_context_kwargs(),
+            callback_id="execution-attempt-attempt-1",
+        )
+
+
+def test_context_requires_nonce_and_commitment_together() -> None:
+    """Neither half of the binding is meaningful without its matching partner."""
+    with pytest.raises(ValidationError, match="must be provided together"):
+        ExecutionContext(
+            **_context_kwargs(),
+            callback_id="execution-attempt-attempt-1",
+            callback_nonce=CALLBACK_NONCE,
+        )
+
+
+def test_context_rejects_commitment_unrelated_to_nonce() -> None:
+    """A mismatched commitment must fail before an envelope can be dispatched."""
+    with pytest.raises(ValidationError, match="does not match"):
+        ExecutionContext(
+            **_context_kwargs(),
+            callback_id="execution-attempt-attempt-1",
+            callback_nonce=CALLBACK_NONCE,
+            callback_nonce_commitment="0" * 64,
+        )
+
+
+def test_async_context_accepts_matching_pair_without_displaying_secret() -> None:
+    """A valid pair binds dispatch while keeping ordinary diagnostics redacted."""
+    context = ExecutionContext(
+        **_context_kwargs(),
+        callback_id="execution-attempt-attempt-1",
+        callback_nonce=CALLBACK_NONCE,
+        callback_nonce_commitment=CALLBACK_COMMITMENT,
+    )
+
+    assert context.callback_nonce_commitment == CALLBACK_COMMITMENT
+    assert CALLBACK_NONCE not in repr(context)
+
+
+def test_sync_context_does_not_require_an_unused_callback_secret() -> None:
+    """Local synchronous execution remains valid when callback delivery is skipped."""
+    context = ExecutionContext(
+        **_context_kwargs(),
+        callback_id="execution-attempt-attempt-1",
+        skip_callback=True,
+    )
+
+    assert context.callback_nonce is None
+    assert context.callback_nonce_commitment is None
+
+
+def test_attempt_v1_is_rejected_after_the_strict_contract_cutover() -> None:
+    """Mixed runtime versions must fail explicitly instead of losing nonce fields."""
+    with pytest.raises(ValidationError, match="validibot.attempt.v2"):
+        ExecutionContext(
+            **(
+                _context_kwargs() | {"attempt_contract_version": "validibot.attempt.v1"}
+            ),
+            callback_id="execution-attempt-attempt-1",
+            callback_nonce=CALLBACK_NONCE,
+            callback_nonce_commitment=CALLBACK_COMMITMENT,
+        )
+
+
+def test_callback_payload_transports_secret_without_displaying_it() -> None:
+    """The backend must send the nonce, while ordinary repr output stays redacted."""
+    callback = ValidationCallback(
+        run_id="run-1",
+        callback_id="execution-attempt-attempt-1",
+        callback_nonce=CALLBACK_NONCE,
+        status=ValidationStatus.SUCCESS,
+        result_uri="gs://bucket/attempt-1/output.json",
+    )
+
+    assert callback.model_dump()["callback_nonce"] == CALLBACK_NONCE
+    assert CALLBACK_NONCE not in repr(callback)
+
+
+def test_callback_payload_rejects_missing_or_short_nonce() -> None:
+    """A callback without a full-strength attempt secret is not authenticated."""
+    base = {
+        "run_id": "run-1",
+        "callback_id": "execution-attempt-attempt-1",
+        "status": ValidationStatus.SUCCESS,
+        "result_uri": "gs://bucket/attempt-1/output.json",
+    }
+
+    with pytest.raises(ValidationError, match="callback_nonce"):
+        ValidationCallback(**base)
+    with pytest.raises(ValidationError, match="at least 43 characters"):
+        ValidationCallback(**base, callback_nonce="too-short")
+
+
+def test_output_envelope_has_no_callback_secret_field() -> None:
+    """Public results must never expose the live secret used for callback auth."""
+    assert "callback_nonce" not in ValidationOutputEnvelope.model_fields