validibot-shared 0.14.0__tar.gz → 0.16.0__tar.gz

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.14.0
+Version: 0.16.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
@@ -166,8 +166,8 @@ Supporting models include:
 
 | Class | Purpose |
 |-------|---------|
-| `InputFileItem` | File reference with URI, MIME type, and role |
-| `ResourceFileItem` | Managed auxiliary file reference with URI and resource type |
+| `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 |
 | `ValidationMessage` | Individual finding (error, warning, info) |
@@ -199,8 +199,10 @@ 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 by future optional `port_key` when
-available, not by assuming `input_files[0]` forever.
+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
@@ -256,6 +258,7 @@ validibot_shared/
 ```python
 from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     OrganizationInfo,
@@ -284,12 +287,21 @@ 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/",
+        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.14.0 → validibot_shared-0.16.0}/README.md

@@ -133,8 +133,8 @@ Supporting models include:
 
 | Class | Purpose |
 |-------|---------|
-| `InputFileItem` | File reference with URI, MIME type, and role |
-| `ResourceFileItem` | Managed auxiliary file reference with URI and resource type |
+| `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 |
 | `ValidationMessage` | Individual finding (error, warning, info) |
@@ -166,8 +166,10 @@ 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 by future optional `port_key` when
-available, not by assuming `input_files[0]` forever.
+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
@@ -223,6 +225,7 @@ validibot_shared/
 ```python
 from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     OrganizationInfo,
@@ -251,12 +254,21 @@ 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/",
+        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.14.0 → validibot_shared-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.14.0"
+version = "0.16.0"
 description = "Shared library for data interchange between Validibot and validator containers"
 readme = "README.md"
 license = { text = "MIT" }

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/tests/test_artifacts.py

@@ -37,6 +37,7 @@ def test_artifact_ref_serializes_as_json_safe_control_plane_object():
         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",
@@ -50,6 +51,28 @@ def test_artifact_ref_serializes_as_json_safe_control_plane_object():
     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():

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/tests/test_energyplus_envelopes.py

@@ -10,6 +10,7 @@ from validibot_shared.energyplus.envelopes import (
     EnergyPlusOutputs,
 )
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     SupportedMimeType,
@@ -41,11 +42,18 @@ def _base_input_envelope_kwargs():
                 mime_type=SupportedMimeType.ENERGYPLUS_IDF,
                 role="primary-model",
                 uri="gs://bucket/model.idf",
+                size_bytes=123,
+                sha256="1" * 64,
+                storage_version="1700000000000000",
             )
         ],
         "context": ExecutionContext(
             callback_url="https://example.com/callback",
             execution_bundle_uri="gs://bucket/run-1/",
+            execution_attempt_id="attempt-1",
+            step_run_id="step-run-1",
+            attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+            expected_output_uri="gs://bucket/run-1/output.json",
             timeout_seconds=600,
             tags=["smoke"],
         ),
@@ -125,6 +133,11 @@ def test_energyplus_output_envelope_accepts_typed_outputs():
     """EnergyPlusOutputEnvelope should accept typed outputs."""
     envelope = EnergyPlusOutputEnvelope(
         run_id="run-2",
+        step_run_id="step-run-2",
+        execution_attempt_id="attempt-2",
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        input_envelope_sha256="a" * 64,
+        output_uri="gs://bucket/run-2/output.json",
         validator={
             "id": "val-1",
             "type": ValidatorType.ENERGYPLUS,

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/tests/test_fmu_envelopes.py

@@ -9,7 +9,11 @@ from validibot_shared.fmu.envelopes import (
     FMUSimulationConfig,
     build_fmu_input_envelope,
 )
-from validibot_shared.validations.envelopes import ExecutionContext, ValidatorType
+from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
+    ExecutionContext,
+    ValidatorType,
+)
 
 # Test constants
 TEST_EXECUTION_SECONDS = 2.5
@@ -25,6 +29,10 @@ def _base_kwargs():
         "context": ExecutionContext(
             callback_url="https://example.com/cb",
             execution_bundle_uri="gs://bucket/run-123/",
+            execution_attempt_id="attempt-123",
+            step_run_id="step-run-123",
+            attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+            expected_output_uri="gs://bucket/run-123/output.json",
         ),
     }
 
@@ -90,9 +98,15 @@ def test_build_fmu_input_envelope_constructs_expected_payload():
         step_id="step-1",
         step_name="Simulate",
         fmu_uri="gs://bucket/model.fmu",
+        fmu_size_bytes=456,
+        fmu_sha256="1" * 64,
+        fmu_storage_version="1700000000000000",
         input_values={"u1": 1.0},
         callback_url="https://example.com/callback",
         execution_bundle_uri="gs://bucket/run-1/",
+        execution_attempt_id="attempt-1",
+        step_run_id="step-run-1",
+        expected_output_uri="gs://bucket/run-1/output.json",
         output_variables=["y"],
     )
 

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/tests/test_schematron_envelopes.py

@@ -24,6 +24,7 @@ from validibot_shared.schematron.envelopes import (
     build_schematron_input_envelope,
 )
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     SupportedMimeType,
     ValidationStatus,
     ValidatorType,
@@ -121,6 +122,11 @@ def test_engine_failure_shapes_round_trip():
     ):
         envelope = SchematronOutputEnvelope(
             run_id="run-1",
+            step_run_id="step-run-1",
+            execution_attempt_id="attempt-1",
+            attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+            input_envelope_sha256="a" * 64,
+            output_uri="gs://bucket/run-1/output.json",
             validator={"id": "v1", "type": ValidatorType.SCHEMATRON, "version": "1"},
             status=status,
             timing={},
@@ -190,9 +196,15 @@ def test_build_schematron_input_envelope_assembles_the_xml_submission():
         step_id="step-1",
         step_name="Peppol rules",
         submission_uri="gs://bucket/run-1/submission.xml",
+        submission_size_bytes=321,
+        submission_sha256="1" * 64,
+        submission_storage_version="1700000000000000",
         inputs=_inputs(),
         callback_url="https://example.com/callback",
         execution_bundle_uri="gs://bucket/run-1/",
+        execution_attempt_id="attempt-1",
+        step_run_id="step-run-1",
+        expected_output_uri="gs://bucket/run-1/output.json",
     )
 
     assert isinstance(envelope, SchematronInputEnvelope)

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/tests/test_shacl_envelopes.py

@@ -13,8 +13,8 @@ We therefore assert three things:
    (Django serializes the input; the container serializes the output).
 2. ``extra="forbid"`` is honoured so a drifting producer/consumer fails loudly
    rather than silently dropping fields across the trust boundary.
-3. The ``SHACLOutputs`` signal fields stay aligned with what Django's
-   ``extract_output_signals`` expects (the ``o.*`` catalog keys).
+3. The ``SHACLOutputs`` output-value fields stay aligned with what Django's
+   ``extract_output_values`` expects (the ``o.*`` catalog keys).
 """
 
 import pytest
@@ -31,13 +31,14 @@ from validibot_shared.shacl.envelopes import (
     mime_type_for_rdf_format,
 )
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     SupportedMimeType,
     ValidationStatus,
     ValidatorType,
 )
 
-# The o.* signal keys Django's SHACL catalog declares. If SHACLOutputs ever
+# The o.* output-value keys Django's SHACL catalog declares. If SHACLOutputs ever
 # drops one of these, the Django extractor would silently lose a CEL signal —
 # this list is the canary.
 EXPECTED_SIGNAL_KEYS = {
@@ -65,6 +66,10 @@ def _base_kwargs():
         "context": ExecutionContext(
             callback_url="https://example.com/cb",
             execution_bundle_uri="gs://bucket/run-123/",
+            execution_attempt_id="attempt-123",
+            step_run_id="step-run-123",
+            attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+            expected_output_uri="gs://bucket/run-123/output.json",
         ),
     }
 
@@ -154,9 +159,15 @@ def test_build_shacl_input_envelope_constructs_expected_payload():
         step_id="step-1",
         step_name="Validate graph",
         submission_uri="gs://bucket/submission.jsonld",
+        submission_size_bytes=789,
+        submission_sha256="1" * 64,
+        submission_storage_version="1700000000000000",
         inputs=inputs,
         callback_url="https://example.com/callback",
         execution_bundle_uri="gs://bucket/run-1/",
+        execution_attempt_id="attempt-1",
+        step_run_id="step-run-1",
+        expected_output_uri="gs://bucket/run-1/output.json",
         skip_callback=True,
     )
 
@@ -197,21 +208,21 @@ def test_sparql_assertion_spec_defaults():
 
 
 # ── Output envelope ─────────────────────────────────────────────────────────
-# The output envelope is what the container writes back. Its signal fields feed
+# The output envelope is what the container writes back. Its output-value fields feed
 # Django's CEL/Basic assertion evaluation; its assertion tallies are folded into
 # the final AssertionStats.
 
 
 def test_shacl_outputs_signal_keys_cover_catalog():
-    """Every catalog signal key must exist as a field on ``SHACLOutputs``.
+    """Every catalog output-value key must exist as a field on ``SHACLOutputs``.
 
-    Django's ``extract_output_signals`` reads these keys off the envelope; a
+    Django's ``extract_output_values`` reads these keys off the envelope; a
     missing field here would surface as a null CEL signal at runtime with no
     error. This test pins the alignment at the contract layer.
     """
     field_names = set(SHACLOutputs.model_fields)
     missing = EXPECTED_SIGNAL_KEYS - field_names
-    assert not missing, f"SHACLOutputs missing signal fields: {missing}"
+    assert not missing, f"SHACLOutputs missing output-value fields: {missing}"
 
 
 def test_shacl_output_envelope_round_trips():
@@ -223,6 +234,11 @@ def test_shacl_output_envelope_round_trips():
     """
     envelope = SHACLOutputEnvelope(
         run_id="run-123",
+        step_run_id="step-run-123",
+        execution_attempt_id="attempt-123",
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        input_envelope_sha256="a" * 64,
+        output_uri="gs://bucket/run-123/output.json",
         validator={"id": "val-1", "type": ValidatorType.SHACL, "version": "1"},
         status=ValidationStatus.FAILED_VALIDATION,
         timing={},
@@ -259,6 +275,11 @@ def test_shacl_output_envelope_allows_none_outputs():
     """
     envelope = SHACLOutputEnvelope(
         run_id="run-123",
+        step_run_id="step-run-123",
+        execution_attempt_id="attempt-123",
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        input_envelope_sha256="a" * 64,
+        output_uri="gs://bucket/run-123/output.json",
         validator={"id": "val-1", "type": ValidatorType.SHACL, "version": "1"},
         status=ValidationStatus.FAILED_RUNTIME,
         timing={},

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/tests/test_validations_envelopes.py

@@ -5,13 +5,16 @@ from datetime import UTC, datetime
 import pytest
 from pydantic import ValidationError
 
+from validibot_shared.canonicalization import sha256_hex_for_model
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     MessageLocation,
     ResourceFileItem,
     Severity,
     SupportedMimeType,
+    ValidationArtifact,
     ValidationCallback,
     ValidationInputEnvelope,
     ValidationMessage,
@@ -37,15 +40,33 @@ def _base_input_envelope_kwargs():
                 mime_type=SupportedMimeType.ENERGYPLUS_IDF,
                 role="primary-model",
                 uri="gs://bucket/model.idf",
+                size_bytes=123,
+                sha256="1" * 64,
+                storage_version="1700000000000000",
             )
         ],
         "context": ExecutionContext(
             callback_url="https://example.com/callback",
             execution_bundle_uri="gs://bucket/run-42/",
+            execution_attempt_id="attempt-42",
+            step_run_id="step-run-42",
+            attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+            expected_output_uri="gs://bucket/run-42/output.json",
         ),
     }
 
 
+def _output_identity_kwargs():
+    """Return the immutable execution-attempt identity required on outputs."""
+    return {
+        "step_run_id": "step-run-99",
+        "execution_attempt_id": "attempt-99",
+        "attempt_contract_version": ATTEMPT_CONTRACT_VERSION,
+        "input_envelope_sha256": "a" * 64,
+        "output_uri": "gs://bucket/run-99/output.json",
+    }
+
+
 def test_validation_input_envelope_defaults_schema_version():
     """ValidationInputEnvelope should have default schema version."""
     envelope = ValidationInputEnvelope(**_base_input_envelope_kwargs())
@@ -56,6 +77,49 @@ def test_validation_input_envelope_defaults_schema_version():
     assert envelope.inputs == {}
 
 
+def test_strict_attempt_fixture_has_the_cross_repo_canonical_digest():
+    """All producers and consumers must hash the same attempt fixture bytes."""
+    envelope = ValidationInputEnvelope(
+        run_id="run-fixture",
+        validator={
+            "id": "validator-fixture",
+            "type": ValidatorType.FMU,
+            "version": "1",
+        },
+        org={"id": "org-fixture", "name": "Fixture Org"},
+        workflow={
+            "id": "workflow-fixture",
+            "step_id": "step-fixture",
+            "step_name": "Fixture Step",
+        },
+        input_files=[
+            {
+                "name": "model.fmu",
+                "mime_type": SupportedMimeType.FMU,
+                "role": "fmu",
+                "port_key": "fmu_model",
+                "uri": "gs://fixture/runs/run-fixture/model.fmu",
+                "size_bytes": 12,
+                "sha256": "1" * 64,
+                "storage_version": "1700000000000000",
+            },
+        ],
+        inputs={"alpha": 1},
+        context={
+            "execution_attempt_id": "attempt-fixture",
+            "step_run_id": "step-run-fixture",
+            "attempt_contract_version": ATTEMPT_CONTRACT_VERSION,
+            "expected_output_uri": "gs://fixture/runs/run-fixture/output.json",
+            "execution_bundle_uri": "gs://fixture/runs/run-fixture/",
+            "skip_callback": True,
+        },
+    )
+
+    assert sha256_hex_for_model(envelope) == (
+        "e17c5dae05c58f4d6034806e3f5e7a7602013d03f27ec811a97a9fc49f9d88d5"
+    )
+
+
 def test_input_file_item_accepts_optional_port_key():
     """InputFileItem should carry declared file-port identity when available."""
     item = InputFileItem(
@@ -64,6 +128,9 @@ def test_input_file_item_accepts_optional_port_key():
         role="primary-model",
         port_key="primary_model",
         uri="gs://bucket/model.idf",
+        size_bytes=123,
+        sha256="1" * 64,
+        storage_version="1700000000000000",
     )
 
     assert item.port_key == "primary_model"
@@ -73,9 +140,13 @@ def test_resource_file_item_accepts_optional_port_key():
     """ResourceFileItem should carry declared file-port identity when available."""
     item = ResourceFileItem(
         id="resource-1",
+        name="weather.epw",
         type="energyplus_weather",
         port_key="weather_file",
         uri="gs://bucket/weather.epw",
+        size_bytes=456,
+        sha256="2" * 64,
+        storage_version="1700000000000001",
     )
 
     assert item.port_key == "weather_file"
@@ -89,10 +160,81 @@ def test_input_file_item_forbids_extra_fields():
             mime_type=SupportedMimeType.ENERGYPLUS_IDF,
             role="primary-model",
             uri="gs://bucket/model.idf",
+            size_bytes=123,
+            sha256="1" * 64,
+            storage_version="1700000000000000",
             extra_field="not-allowed",
         )
 
 
+@pytest.mark.parametrize("missing", ["size_bytes", "sha256", "storage_version"])
+def test_input_file_item_requires_every_integrity_field(missing):
+    """A producer cannot emit a weaker file contract by omitting identity."""
+    payload = {
+        "name": "model.idf",
+        "mime_type": SupportedMimeType.ENERGYPLUS_IDF,
+        "role": "primary-model",
+        "uri": "gs://bucket/model.idf",
+        "size_bytes": 123,
+        "sha256": "1" * 64,
+        "storage_version": "1700000000000000",
+    }
+    payload.pop(missing)
+
+    with pytest.raises(ValidationError):
+        InputFileItem(**payload)
+
+
+@pytest.mark.parametrize("name", ["", ".", "..", "../model.idf", "a/b.idf", "a\\b.idf"])
+def test_file_item_names_must_be_safe_leaf_names(name):
+    """Logical names cannot redirect backend materialization outside its workspace."""
+    with pytest.raises(ValidationError):
+        InputFileItem(
+            name=name,
+            mime_type=SupportedMimeType.ENERGYPLUS_IDF,
+            uri="gs://bucket/model.idf",
+            size_bytes=123,
+            sha256="1" * 64,
+            storage_version="1700000000000000",
+        )
+
+
+def test_file_item_rejects_malformed_integrity_values():
+    """Negative sizes, non-SHA digests, and empty versions fail at parsing."""
+    with pytest.raises(ValidationError):
+        InputFileItem(
+            name="model.idf",
+            mime_type=SupportedMimeType.ENERGYPLUS_IDF,
+            uri="gs://bucket/model.idf",
+            size_bytes=-1,
+            sha256="not-a-sha256",
+            storage_version="",
+        )
+
+
+def test_validation_artifact_requires_byte_and_storage_identity():
+    """Output artifacts use the same mandatory integrity contract as inputs."""
+    artifact = ValidationArtifact(
+        name="report.csv",
+        type="timeseries-csv",
+        mime_type="text/csv",
+        uri="gs://bucket/outputs/report.csv",
+        size_bytes=456,
+        sha256="2" * 64,
+        storage_version="1700000000000001",
+    )
+
+    assert artifact.size_bytes == 456
+    assert artifact.sha256 == "2" * 64
+
+    with pytest.raises(ValidationError):
+        ValidationArtifact(
+            name="report.csv",
+            type="timeseries-csv",
+            uri="gs://bucket/outputs/report.csv",
+        )
+
+
 def test_validation_message_location_optional_fields():
     """MessageLocation should support optional fields."""
     location = MessageLocation(
@@ -114,6 +256,7 @@ def test_validation_output_envelope_defaults_and_status_enum():
 
     envelope = ValidationOutputEnvelope(
         run_id="run-99",
+        **_output_identity_kwargs(),
         validator={
             "id": "val-1",
             "type": ValidatorType.ENERGYPLUS,
@@ -136,6 +279,7 @@ def test_validation_output_envelope_rejects_invalid_status():
     with pytest.raises(ValidationError):
         ValidationOutputEnvelope(
             run_id="run-100",
+            **_output_identity_kwargs(),
             validator={
                 "id": "val-1",
                 "type": ValidatorType.ENERGYPLUS,

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/energyplus/envelopes.py

@@ -81,9 +81,9 @@ class EnergyPlusInputs(BaseModel):
     Using a typed Pydantic model provides compile-time type checking and
     runtime validation of all configuration parameters.
 
-    Note: The validator always returns a fixed set of output signals defined
+    Note: The validator always returns a fixed set of output values defined
     in its catalog. Users don't need to specify which outputs they want -
-    they get all defined signals and write assertions against the ones they
+    they get all defined outputs and write assertions against the ones they
     care about.
     """
 

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/energyplus/models.py

@@ -47,12 +47,12 @@ class EnergyPlusSimulationMetrics(BaseModel):
     """
     Extracted EnergyPlus simulation metrics.
 
-    These are the core output signals extracted from EnergyPlus simulation results.
-    Field names here are the canonical EnergyPlus signal names expected by core
-    Validibot. The core Django app maps these names to SignalDefinition rows.
+    These are the core output values extracted from EnergyPlus simulation results.
+    Field names here are the canonical EnergyPlus output names expected by core
+    Validibot. The core Django app maps these names to StepIODefinition rows.
 
     The validator extracts these values from the EnergyPlus SQL database
-    (eplusout.sql) and they become available as output signals for assertions.
+    (eplusout.sql) and they become available as output values for assertions.
     """
 
     model_config = ConfigDict(extra="forbid")

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/fmu/envelopes.py

@@ -19,6 +19,7 @@ from typing import Any
 from pydantic import BaseModel, Field
 
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     SupportedMimeType,
@@ -128,9 +129,15 @@ def build_fmu_input_envelope(
     step_id: str,
     step_name: str | None,
     fmu_uri: str,
+    fmu_size_bytes: int,
+    fmu_sha256: str,
+    fmu_storage_version: str,
     input_values: dict[str, Any],
     callback_url: str,
     execution_bundle_uri: str,
+    execution_attempt_id: str,
+    step_run_id: str,
+    expected_output_uri: str,
     simulation: FMUSimulationConfig | None = None,
     output_variables: list[str] | None = None,
 ) -> FMUInputEnvelope:
@@ -146,6 +153,9 @@ def build_fmu_input_envelope(
         step_id: Workflow step ID
         step_name: Optional step name
         fmu_uri: FMU storage URI (gs://... or local path in dev)
+        fmu_size_bytes: Expected exact FMU size and streaming ceiling
+        fmu_sha256: Expected SHA-256 of the FMU bytes
+        fmu_storage_version: Immutable provider version for the FMU object
         input_values: Resolved inputs keyed by native FMU variable name
         callback_url: URL to POST callback
         execution_bundle_uri: Base URI/path for this run's files
@@ -160,6 +170,9 @@ def build_fmu_input_envelope(
             mime_type=SupportedMimeType.FMU,
             role="fmu",
             uri=fmu_uri,
+            size_bytes=fmu_size_bytes,
+            sha256=fmu_sha256,
+            storage_version=fmu_storage_version,
         )
     ]
 
@@ -170,6 +183,10 @@ def build_fmu_input_envelope(
     )
 
     context = ExecutionContext(
+        execution_attempt_id=execution_attempt_id,
+        step_run_id=step_run_id,
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        expected_output_uri=expected_output_uri,
         callback_url=callback_url,
         execution_bundle_uri=execution_bundle_uri,
     )

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/fmu/models.py

@@ -2,7 +2,7 @@
 FMU probe result models.
 
 These models define the contract for FMU probing operations - extracting
-metadata from modelDescription.xml. Probe results feed into SignalDefinition
+metadata from modelDescription.xml. Probe results feed into StepIODefinition
 rows in the core Django app.
 
 Probing is done in-process in the Django worker (not in containers) since

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/schematron/envelopes.py

@@ -30,6 +30,7 @@ from __future__ import annotations
 from pydantic import BaseModel, Field
 
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     SupportedMimeType,
@@ -125,9 +126,9 @@ class SchematronFinding(BaseModel):
 class SchematronOutputs(BaseModel):
     """Schematron results: engine status, SVRL summary, and provenance.
 
-    The signal fields (``passed`` … ``engine``) mirror the catalog entries in
+    The output-value fields (``passed`` … ``engine``) mirror the catalog entries in
     the Django Schematron ``ValidatorConfig`` — Django's
-    ``extract_output_signals`` pulls exactly those keys for CEL assertion
+    ``extract_output_values`` pulls exactly those keys for CEL assertion
     evaluation.
 
     D9 contract: when ``engine_status != "ok"`` the run never evaluated the
@@ -153,7 +154,7 @@ class SchematronOutputs(BaseModel):
         ),
     )
 
-    # ── o.* signals (must stay aligned with the ValidatorConfig catalog) ──
+    # ── o.* output values (must stay aligned with the ValidatorConfig catalog) ──
     passed: bool | None = Field(
         default=None,
         description=(
@@ -241,9 +242,15 @@ def build_schematron_input_envelope(
     step_id: str,
     step_name: str | None,
     submission_uri: str,
+    submission_size_bytes: int,
+    submission_sha256: str,
+    submission_storage_version: str,
     inputs: SchematronInputs,
     callback_url: str,
     execution_bundle_uri: str,
+    execution_attempt_id: str,
+    step_run_id: str,
+    expected_output_uri: str,
     callback_id: str | None = None,
     skip_callback: bool = False,
 ) -> SchematronInputEnvelope:
@@ -255,6 +262,9 @@ def build_schematron_input_envelope(
         org_id / org_name: Organization identity.
         workflow_id / step_id / step_name: Workflow context.
         submission_uri: Storage URI for the XML submission (gs:// or file://).
+        submission_size_bytes: Expected exact submission size and byte ceiling.
+        submission_sha256: Expected SHA-256 of the XML submission.
+        submission_storage_version: Immutable provider version for the object.
         inputs: Fully-resolved ``SchematronInputs`` (inline rules + limits).
         callback_url: URL the container POSTs to on completion.
         execution_bundle_uri: Base URI for this run's bundle.
@@ -267,10 +277,17 @@ def build_schematron_input_envelope(
             mime_type=SupportedMimeType.APPLICATION_XML,
             role="primary-model",
             uri=submission_uri,
+            size_bytes=submission_size_bytes,
+            sha256=submission_sha256,
+            storage_version=submission_storage_version,
         ),
     ]
 
     context = ExecutionContext(
+        execution_attempt_id=execution_attempt_id,
+        step_run_id=step_run_id,
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        expected_output_uri=expected_output_uri,
         callback_id=callback_id,
         callback_url=callback_url,
         execution_bundle_uri=execution_bundle_uri,

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/shacl/envelopes.py

@@ -15,7 +15,7 @@ These schemas define the contract between Django and the SHACL container:
   the database (rulesets, ``RulesetAssertion`` rows, settings) before dispatch —
   the container receives only this serialized boundary.
 - **Output envelope**: the SHACL findings (as ``ValidationMessage`` rows), the
-  ``o.*`` signal dict (for CEL/Basic output assertions evaluated back in Django),
+  ``o.*`` output-value dict (for CEL/Basic output assertions evaluated back in Django),
   the serialized ``sh:ValidationReport`` for evidence download, and the
   container-side SPARQL-ASK assertion counts (folded into the final assertion
   totals by ``AdvancedValidator.post_execute_validate``).
@@ -31,6 +31,7 @@ from typing import Any
 from pydantic import BaseModel, Field
 
 from validibot_shared.validations.envelopes import (
+    ATTEMPT_CONTRACT_VERSION,
     ExecutionContext,
     InputFileItem,
     SupportedMimeType,
@@ -192,11 +193,11 @@ class SHACLFinding(BaseModel):
 
 
 class SHACLOutputs(BaseModel):
-    """SHACL validation results and the ``o.*`` signal dict.
+    """SHACL validation results and the ``o.*`` output-value dict.
 
-    The signal fields (``parse_ok`` … ``shacl_total_count``) mirror the catalog
+    The output-value fields (``parse_ok`` … ``shacl_total_count``) mirror the catalog
     entries declared in the Django SHACL ``ValidatorConfig`` — Django's
-    ``extract_output_signals`` pulls exactly those keys for CEL/Basic assertion
+    ``extract_output_values`` pulls exactly those keys for CEL/Basic assertion
     evaluation. The remaining fields carry evidence (the serialized report) and
     the container-side SPARQL-ASK assertion counts.
     """
@@ -212,7 +213,7 @@ class SHACLOutputs(BaseModel):
         ),
     )
 
-    # ── o.* signals (must stay aligned with the SHACL ValidatorConfig catalog) ──
+    # ── o.* output values (must stay aligned with the SHACL ValidatorConfig catalog) ──
     parse_ok: bool = Field(description="Whether the submitted RDF parsed.")
     parse_serialization: str = Field(description="rdflib format used to parse.")
     triple_count: int = Field(default=0, ge=0)
@@ -289,9 +290,15 @@ def build_shacl_input_envelope(
     step_id: str,
     step_name: str | None,
     submission_uri: str,
+    submission_size_bytes: int,
+    submission_sha256: str,
+    submission_storage_version: str,
     inputs: SHACLInputs,
     callback_url: str,
     execution_bundle_uri: str,
+    execution_attempt_id: str,
+    step_run_id: str,
+    expected_output_uri: str,
     callback_id: str | None = None,
     skip_callback: bool = False,
 ) -> SHACLInputEnvelope:
@@ -303,6 +310,9 @@ def build_shacl_input_envelope(
         org_id / org_name: Organization identity.
         workflow_id / step_id / step_name: Workflow context.
         submission_uri: Storage URI for the RDF submission (gs:// or file://).
+        submission_size_bytes: Expected exact submission size and byte ceiling.
+        submission_sha256: Expected SHA-256 of the RDF submission.
+        submission_storage_version: Immutable provider version for the object.
         inputs: Fully-resolved ``SHACLInputs`` (shapes/ontology/settings/asks).
         callback_url: URL the container POSTs to on completion.
         execution_bundle_uri: Base URI for this run's bundle.
@@ -315,10 +325,17 @@ def build_shacl_input_envelope(
             mime_type=mime_type_for_rdf_format(inputs.rdf_format),
             role="primary-model",
             uri=submission_uri,
+            size_bytes=submission_size_bytes,
+            sha256=submission_sha256,
+            storage_version=submission_storage_version,
         ),
     ]
 
     context = ExecutionContext(
+        execution_attempt_id=execution_attempt_id,
+        step_run_id=step_run_id,
+        attempt_contract_version=ATTEMPT_CONTRACT_VERSION,
+        expected_output_uri=expected_output_uri,
         callback_id=callback_id,
         callback_url=callback_url,
         execution_bundle_uri=execution_bundle_uri,

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/validations/artifacts.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from enum import Enum
 from typing import Any, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 ARTIFACT_REF_SCHEMA_VERSION = "validibot.artifact_ref.v1"
 
@@ -134,11 +134,12 @@ class ArtifactRef(BaseModel):
     media_type: str = ""
     data_format: str = ""
     filename: str = ""
-    size_bytes: int | None = None
-    sha256: str = ""
+    size_bytes: int = Field(ge=0)
+    sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    storage_version: str = Field(min_length=1, max_length=512)
 
     uri: str = Field(
-        default="",
+        min_length=1,
         description="Internal storage URI; not a public download URL.",
     )
     manifest_uri: str = ""
@@ -153,3 +154,18 @@ class ArtifactRef(BaseModel):
     metadata: dict[str, Any] = Field(default_factory=dict)
 
     model_config = {"extra": "forbid"}
+
+    @field_validator("name")
+    @classmethod
+    def _validate_safe_name(cls, value: str) -> str:
+        """Artifact refs carry logical names, never materialization paths."""
+        if (
+            not value
+            or value in {".", ".."}
+            or "/" in value
+            or "\\" in value
+            or "\x00" in value
+        ):
+            msg = f"Artifact name must be a safe logical leaf name: {value!r}"
+            raise ValueError(msg)
+        return value

{validibot_shared-0.14.0 → validibot_shared-0.16.0}/validibot_shared/validations/envelopes.py

@@ -117,7 +117,9 @@ from datetime import datetime  # noqa: TC003
 from enum import Enum
 from typing import Any, Literal
 
-from pydantic import BaseModel, Field, HttpUrl
+from pydantic import BaseModel, Field, HttpUrl, field_validator
+
+ATTEMPT_CONTRACT_VERSION = "validibot.attempt.v1"
 
 # ==============================================================================
 # Shared Enums
@@ -186,7 +188,52 @@ class SupportedMimeType(str, Enum):
     RDF_N_QUADS = "application/n-quads"
 
 
-class InputFileItem(BaseModel):
+def _safe_leaf_name(value: str) -> str:
+    """Return ``value`` when it is one safe logical filename.
+
+    Storage URIs carry provider paths; item names are deliberately only leaf
+    names so a backend can materialize them below its own attempt workspace.
+    """
+    if (
+        not value
+        or value in {".", ".."}
+        or "/" in value
+        or "\\" in value
+        or "\x00" in value
+    ):
+        msg = f"File item name must be a safe logical leaf name: {value!r}"
+        raise ValueError(msg)
+    return value
+
+
+class IntegrityBoundFile(BaseModel):
+    """Required byte identity shared by every file-bearing envelope item.
+
+    ``size_bytes`` is both the expected exact length and the runtime's hard
+    streaming ceiling. ``sha256`` identifies the bytes the producer committed
+    to. ``storage_version`` pins the provider-specific immutable object
+    identity (for example a GCS generation or ``sha256:<digest>`` for an
+    attempt-local read-only file).
+    """
+
+    size_bytes: int = Field(
+        ge=0,
+        description="Expected exact file size and hard streaming ceiling.",
+    )
+    sha256: str = Field(
+        pattern=r"^[0-9a-f]{64}$",
+        description="Lowercase SHA-256 hex digest of the exact file bytes.",
+    )
+    storage_version: str = Field(
+        min_length=1,
+        max_length=512,
+        description="Provider-specific immutable object/version identity.",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+class InputFileItem(IntegrityBoundFile):
     """
     A user-submitted file input for the validator.
 
@@ -196,7 +243,7 @@ class InputFileItem(BaseModel):
     Note: Auxiliary files like weather files are in resource_files, not input_files.
     """
 
-    name: str = Field(description="Human-readable name of the file")
+    name: str = Field(description="Safe logical leaf name of the file")
 
     mime_type: SupportedMimeType = Field(description="MIME type of the file")
 
@@ -209,7 +256,7 @@ class InputFileItem(BaseModel):
         default=None,
         description=(
             "Declared Validibot file-port key that produced this envelope item "
-            "(e.g., 'primary_model'). Optional for backwards-compatible rollout."
+            "(e.g., 'primary_model')."
         ),
     )
 
@@ -217,10 +264,14 @@ class InputFileItem(BaseModel):
         description="Storage URI to the file (gs:// or file:// for self-hosted)"
     )
 
-    model_config = {"extra": "forbid"}
+    @field_validator("name")
+    @classmethod
+    def _validate_safe_name(cls, value: str) -> str:
+        """Reject paths so runtimes choose the destination directory."""
+        return _safe_leaf_name(value)
 
 
-class ResourceFileItem(BaseModel):
+class ResourceFileItem(IntegrityBoundFile):
     """
     A resource file needed by the validator.
 
@@ -236,6 +287,8 @@ class ResourceFileItem(BaseModel):
 
     id: str = Field(description="Resource file UUID from Django database")
 
+    name: str = Field(description="Safe logical leaf name of the resource")
+
     type: str = Field(
         description="Resource type (e.g., 'weather', 'library', 'config')"
     )
@@ -244,7 +297,7 @@ class ResourceFileItem(BaseModel):
         default=None,
         description=(
             "Declared Validibot file-port key that produced this resource item "
-            "(e.g., 'weather_file'). Optional for backwards-compatible rollout."
+            "(e.g., 'weather_file')."
         ),
     )
 
@@ -252,6 +305,12 @@ class ResourceFileItem(BaseModel):
         description="Storage URI to the file (gs:// or file:// for self-hosted)"
     )
 
+    @field_validator("name")
+    @classmethod
+    def _validate_safe_name(cls, value: str) -> str:
+        """Reject resource names that could escape the runtime workspace."""
+        return _safe_leaf_name(value)
+
     model_config = {"extra": "forbid"}
 
 
@@ -326,6 +385,25 @@ class ExecutionContext(BaseModel):
     4. Respect timeout constraints (timeout_seconds)
     """
 
+    execution_attempt_id: str = Field(
+        min_length=1,
+        description="ExecutionAttempt UUID selected by the trusted application.",
+    )
+
+    step_run_id: str = Field(
+        min_length=1,
+        description="ValidationStepRun identity this attempt executes.",
+    )
+
+    attempt_contract_version: Literal["validibot.attempt.v1"] = Field(
+        description="Strict attempt I/O contract version.",
+    )
+
+    expected_output_uri: str = Field(
+        min_length=1,
+        description="Exact output-envelope identity selected before dispatch.",
+    )
+
     callback_id: str | None = Field(
         default=None,
         description=(
@@ -498,10 +576,10 @@ class ValidationMetric(BaseModel):
     model_config = {"extra": "forbid"}
 
 
-class ValidationArtifact(BaseModel):
+class ValidationArtifact(IntegrityBoundFile):
     """A file artifact produced by the validator."""
 
-    name: str = Field(description="Artifact name")
+    name: str = Field(description="Safe logical artifact leaf name")
 
     type: str = Field(
         description=(
@@ -517,9 +595,11 @@ class ValidationArtifact(BaseModel):
         description="Storage URI to the artifact (gs:// or file:// for self-hosted)"
     )
 
-    size_bytes: int | None = Field(default=None, description="File size in bytes")
-
-    model_config = {"extra": "forbid"}
+    @field_validator("name")
+    @classmethod
+    def _validate_safe_name(cls, value: str) -> str:
+        """Reject artifact names that could be interpreted as paths."""
+        return _safe_leaf_name(value)
 
 
 class RawOutputs(BaseModel):
@@ -617,6 +697,30 @@ class ValidationOutputEnvelope(BaseModel):
 
     run_id: str = Field(description="Unique run identifier (matches input)")
 
+    step_run_id: str = Field(
+        min_length=1,
+        description="ValidationStepRun identity echoed from the input contract.",
+    )
+
+    execution_attempt_id: str = Field(
+        min_length=1,
+        description="ExecutionAttempt identity echoed from the input contract.",
+    )
+
+    attempt_contract_version: Literal["validibot.attempt.v1"] = Field(
+        description="Strict attempt I/O contract version echoed from input.",
+    )
+
+    input_envelope_sha256: str = Field(
+        pattern=r"^[0-9a-f]{64}$",
+        description="Canonical SHA-256 of the exact parsed input envelope.",
+    )
+
+    output_uri: str = Field(
+        min_length=1,
+        description="Exact output-envelope URI selected by the input contract.",
+    )
+
     validator: ValidatorInfo
 
     status: ValidationStatus