validibot-shared 0.12.0__tar.gz → 0.13.0__tar.gz

{validibot_shared-0.12.0 → validibot_shared-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.12.0
+Version: 0.13.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
@@ -28,7 +28,7 @@ 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.20; extra == 'dev'
+Requires-Dist: ruff==0.15.21; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -167,11 +167,46 @@ Supporting models include:
 | Class | Purpose |
 |-------|---------|
 | `InputFileItem` | File reference with URI, MIME type, and role |
+| `ResourceFileItem` | Managed auxiliary file reference with URI and resource type |
 | `ValidatorInfo` | Validator identification (ID, type, version) |
 | `ExecutionContext` | Callback URL, execution bundle URI, 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 by future optional `port_key` when
+available, not by assuming `input_files[0]` forever.
+
+`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
 
@@ -204,9 +239,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

{validibot_shared-0.12.0 → validibot_shared-0.13.0}/README.md

@@ -134,11 +134,46 @@ Supporting models include:
 | Class | Purpose |
 |-------|---------|
 | `InputFileItem` | File reference with URI, MIME type, and role |
+| `ResourceFileItem` | Managed auxiliary file reference with URI and resource type |
 | `ValidatorInfo` | Validator identification (ID, type, version) |
 | `ExecutionContext` | Callback URL, execution bundle URI, 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 by future optional `port_key` when
+available, not by assuming `input_files[0]` forever.
+
+`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 +206,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

{validibot_shared-0.12.0 → validibot_shared-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.12.0"
+version = "0.13.0"
 description = "Shared library for data interchange between Validibot and validator containers"
 readme = "README.md"
 license = { text = "MIT" }
@@ -37,7 +37,7 @@ classifiers = [
 dependencies = ["pydantic>=2.13,<3.0", "defusedxml>=0.7.1,<0.8"]
 
 [project.optional-dependencies]
-dev = ["pytest==9.1.1", "ruff==0.15.20"]
+dev = ["pytest==9.1.1", "ruff==0.15.21"]
 
 [project.urls]
 Homepage = "https://validibot.com"

validibot_shared-0.13.0/tests/test_artifacts.py

@@ -0,0 +1,101 @@
+"""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,
+        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://")
+
+
+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.13.0/tests/test_canonicalization.py

@@ -0,0 +1,100 @@
+"""Tests for shared RFC 8785 / JCS canonicalization helpers.
+
+The workflow-definition hash and Pro credential signing path both depend on
+these helpers producing stable bytes from the same logical JSON. Keeping these
+tests in ``validibot-shared`` pins the contract at the package boundary used by
+community evidence producers, commercial signing code, and third-party
+verifiers.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import BaseModel, ConfigDict
+
+from validibot_shared.canonicalization import (
+    canonicalize_dict,
+    canonicalize_model,
+    sha256_hex_for_dict,
+    sha256_hex_for_model,
+)
+
+UNSAFE_INTEGER = 9007199254740993
+
+
+class SampleSchema(BaseModel):
+    """Small frozen schema matching the credential-builder model pattern."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    alpha: str
+    beta: int
+    gamma: str | None = None
+
+
+# ── RFC 8785 ordering and scalar handling ───────────────────────────────────
+# These tests protect the cross-language JSON contract that hashes/signatures
+# depend on: same logical object, same canonical bytes everywhere.
+
+
+def test_dict_keys_are_sorted_recursively() -> None:
+    """Object keys must be sorted at every level of the JSON tree."""
+    result = canonicalize_dict(
+        {"outer_z": {"inner_b": 2, "inner_a": 1}, "outer_a": 0},
+    )
+    decoded = result.decode("utf-8")
+    assert decoded.index('"outer_a"') < decoded.index('"outer_z"')
+    assert decoded.index('"inner_a"') < decoded.index('"inner_b"')
+
+
+def test_large_integer_is_preserved_exactly() -> None:
+    """Integers larger than 2**53 must not be rounded through ``float``.
+
+    Credential signatures may include large identifiers or nonces. If JCS casts
+    them to IEEE-754 doubles, the canonical bytes silently change and a
+    standards-compliant verifier computes a different digest.
+    """
+    result = canonicalize_dict({"n": UNSAFE_INTEGER})
+    assert result == b'{"n":9007199254740993}'
+    assert b"9007199254740992" not in result
+
+
+def test_bool_still_serializes_as_json_literals() -> None:
+    """``bool`` must remain JSON ``true``/``false`` despite subclassing ``int``."""
+    assert canonicalize_dict({"yes": True, "no": False}) == (b'{"no":false,"yes":true}')
+
+
+def test_unicode_strings_are_preserved() -> None:
+    """Non-ASCII text must round-trip through canonical bytes unchanged."""
+    result = canonicalize_dict({"name": "Prüfung", "description": "日本語テスト"})
+    parsed = json.loads(result)
+    assert parsed["name"] == "Prüfung"
+    assert parsed["description"] == "日本語テスト"
+
+
+# ── Pydantic integration and digest wrappers ────────────────────────────────
+# Producers build Pydantic models, while external verifiers often reconstruct
+# plain dictionaries. Both paths must canonicalize to identical bytes.
+
+
+def test_model_produces_same_bytes_as_equivalent_dict() -> None:
+    """Pydantic model dumping must match an equivalent JSON dictionary."""
+    schema = SampleSchema(alpha="hello", beta=42, gamma=None)
+    plain = {"alpha": "hello", "beta": 42, "gamma": None}
+    assert canonicalize_model(schema) == canonicalize_dict(plain)
+
+
+def test_sha256_for_dict_matches_manual_hash() -> None:
+    """The dict digest helper must hash the canonical byte preimage exactly."""
+    data = {"key": "value", "number": 7}
+    expected = hashlib.sha256(canonicalize_dict(data)).hexdigest()
+    assert sha256_hex_for_dict(data) == expected
+
+
+def test_sha256_for_model_matches_manual_hash() -> None:
+    """The model digest helper must hash the canonical byte preimage exactly."""
+    schema = SampleSchema(alpha="test", beta=99, gamma="yes")
+    expected = hashlib.sha256(canonicalize_model(schema)).hexdigest()
+    assert sha256_hex_for_model(schema) == expected

{validibot_shared-0.12.0 → validibot_shared-0.13.0}/tests/test_validations_envelopes.py

@@ -9,6 +9,7 @@ from validibot_shared.validations.envelopes import (
     ExecutionContext,
     InputFileItem,
     MessageLocation,
+    ResourceFileItem,
     Severity,
     SupportedMimeType,
     ValidationCallback,
@@ -51,9 +52,35 @@ def test_validation_input_envelope_defaults_schema_version():
 
     assert envelope.schema_version == "validibot.input.v1"
     assert envelope.input_files[0].role == "primary-model"
+    assert envelope.input_files[0].port_key is None
     assert envelope.inputs == {}
 
 
+def test_input_file_item_accepts_optional_port_key():
+    """InputFileItem should carry declared file-port identity when available."""
+    item = InputFileItem(
+        name="model.idf",
+        mime_type=SupportedMimeType.ENERGYPLUS_IDF,
+        role="primary-model",
+        port_key="primary_model",
+        uri="gs://bucket/model.idf",
+    )
+
+    assert item.port_key == "primary_model"
+
+
+def test_resource_file_item_accepts_optional_port_key():
+    """ResourceFileItem should carry declared file-port identity when available."""
+    item = ResourceFileItem(
+        id="resource-1",
+        type="energyplus_weather",
+        port_key="weather_file",
+        uri="gs://bucket/weather.epw",
+    )
+
+    assert item.port_key == "weather_file"
+
+
 def test_input_file_item_forbids_extra_fields():
     """InputFileItem should forbid extra fields."""
     with pytest.raises(ValidationError):

{validibot_shared-0.12.0 → validibot_shared-0.13.0}/validibot_shared/__init__.py

@@ -1,5 +1,11 @@
 """Shared domain models and utilities for Validibot."""
 
+from validibot_shared.canonicalization import (
+    canonicalize_dict,
+    canonicalize_model,
+    sha256_hex_for_dict,
+    sha256_hex_for_model,
+)
 from validibot_shared.energyplus.models import (
     EnergyPlusSimulationLogs,
     EnergyPlusSimulationMetrics,
@@ -30,6 +36,8 @@ __all__ = [
     "EVIDENCE_SCHEMA_VERSION",
     "ContractConstant",
     "ContractSignalMapping",
+    "canonicalize_dict",
+    "canonicalize_model",
     "EnergyPlusSimulationLogs",
     "EnergyPlusSimulationMetrics",
     "EnergyPlusSimulationOutputs",
@@ -43,6 +51,8 @@ __all__ = [
     "SHACLOutputEnvelope",
     "SHACLOutputs",
     "SHACLSparqlAssertionSpec",
+    "sha256_hex_for_dict",
+    "sha256_hex_for_model",
     "StepValidatorRecord",
     "WorkflowContractSnapshot",
 ]

validibot_shared-0.13.0/validibot_shared/_vendor/__init__.py

@@ -0,0 +1 @@
+"""Vendored compatibility code used by ``validibot_shared`` internals."""

validibot_shared-0.13.0/validibot_shared/_vendor/jcs.py

@@ -0,0 +1,191 @@
+"""
+Vendored RFC 8785 JSON Canonicalization Scheme (JCS) implementation.
+
+Vendored from: jcs 0.2.1 (https://pypi.org/project/jcs/)
+Original author: WebPKI.org (http://webpki.org)
+License: Apache License, Version 2.0
+
+Copyright 2006-2019 WebPKI.org (http://webpki.org).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+This file combines _jcs.py and ntoj.py from the original package
+into a single module for simplicity.  The public API is the single
+``canonicalize(obj)`` function.
+"""
+
+from __future__ import annotations
+
+import re
+
+# ---------------------------------------------------------------------------
+# ntoj: Convert Python float/int into an ES6/V8-compatible JSON string
+# ---------------------------------------------------------------------------
+
+
+def _convert_to_es6_format(value):
+    """Convert a Python number to its ES6/V8 canonical string representation.
+
+    This handles the tricky parts of RFC 8785 number serialization:
+    no trailing zeros, no positive sign, specific exponent formatting,
+    and special handling for zero and small/large values.
+    """
+    fvalue = float(value)
+
+    # Zero is a special case.  Handles "-0" as well.
+    if fvalue == 0:
+        return "0"
+
+    py_double = str(fvalue)
+
+    # Catch "inf" and "nan" values
+    if "n" in py_double:
+        msg = f"Invalid JSON number: {py_double}"
+        raise ValueError(msg)
+
+    # Save sign separately
+    py_sign = ""
+    if py_double.startswith("-"):
+        py_sign = "-"
+        py_double = py_double[1:]
+
+    # Extract exponent if present
+    py_exp_str = ""
+    py_exp_val = 0
+    q = py_double.find("e")
+    if q > 0:
+        py_exp_str = py_double[q:]
+        if py_exp_str[2:3] == "0":
+            # Suppress leading zero on exponents
+            py_exp_str = py_exp_str[:2] + py_exp_str[3:]
+        py_double = py_double[:q]
+        py_exp_val = int(py_exp_str[1:])
+
+    # Split number into first + dot + last
+    py_first = py_double
+    py_dot = ""
+    py_last = ""
+    q = py_double.find(".")
+    if q > 0:
+        py_dot = "."
+        py_first = py_double[:q]
+        py_last = py_double[q + 1 :]
+
+    # Always remove trailing .0
+    if py_last == "0":
+        py_dot = ""
+        py_last = ""
+
+    if 0 < py_exp_val < 21:
+        # Integers shown as-is with up to 21 digits
+        py_first += py_last
+        py_last = ""
+        py_dot = ""
+        py_exp_str = ""
+        q = py_exp_val - len(py_first)
+        while q >= 0:
+            q -= 1
+            py_first += "0"
+    elif -7 < py_exp_val < 0:
+        # Small numbers shown as 0.etc with e-6 as lower limit
+        py_last = py_first + py_last
+        py_first = "0"
+        py_dot = "."
+        py_exp_str = ""
+        q = py_exp_val
+        while q < -1:
+            q += 1
+            py_last = "0" + py_last
+
+    return py_sign + py_first + py_dot + py_last + py_exp_str
+
+
+# ---------------------------------------------------------------------------
+# _jcs: JCS-compatible JSON encoder
+# ---------------------------------------------------------------------------
+
+_ESCAPE = re.compile(r'[\x00-\x1f\\"\b\f\n\r\t]')
+_ESCAPE_DCT = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+for _i in range(0x20):
+    _ESCAPE_DCT.setdefault(chr(_i), f"\\u{_i:04x}")
+
+
+def _encode_basestring(s):
+    """Return a JSON representation of a Python string (non-ASCII preserved)."""
+
+    def replace(match):
+        return _ESCAPE_DCT[match.group(0)]
+
+    return '"' + _ESCAPE.sub(replace, s) + '"'
+
+
+def _serialize(obj):
+    """Recursively serialize a Python object to a JCS-canonical JSON string.
+
+    Keys are sorted by UTF-16BE byte order per RFC 8785 §3.2.3.
+    """
+    if isinstance(obj, str):
+        return _encode_basestring(obj)
+    if obj is None:
+        return "null"
+    if obj is True:
+        return "true"
+    if obj is False:
+        return "false"
+    if isinstance(obj, int):
+        # RFC 8785 §3.2.2.3 mandates that JSON integers be emitted as their
+        # exact decimal literal.  We must NOT route ``int`` through the ES6
+        # number formatter, because that helper begins ``float(value)`` which
+        # loses precision for any integer whose magnitude exceeds 2**53
+        # (the largest exactly-representable IEEE-754 double).  Corrupting the
+        # value here would silently break cross-language canonical-hash
+        # reproducibility (e.g. signature verification against a non-Python
+        # signer).  ``str(int)`` already yields the canonical literal: no
+        # leading zeros, a single optional ``-`` sign, and no ``+``/exponent.
+        # ``bool`` is handled above (it is a subclass of ``int``) so it never
+        # reaches this branch and still serializes as ``true``/``false``.
+        return str(obj)
+    if isinstance(obj, float):
+        return _convert_to_es6_format(obj)
+    if isinstance(obj, (list, tuple)):
+        return "[" + ",".join(_serialize(v) for v in obj) + "]"
+    if isinstance(obj, dict):
+        items = sorted(obj.items(), key=lambda kv: kv[0].encode("utf-16-be"))
+        return (
+            "{"
+            + ",".join(_encode_basestring(k) + ":" + _serialize(v) for k, v in items)
+            + "}"
+        )
+    msg = f"Object of type '{type(obj).__name__}' is not JSON serializable"
+    raise TypeError(msg)
+
+
+def canonicalize(obj: object) -> bytes:
+    """Serialize a Python object to RFC 8785 canonical JSON bytes.
+
+    Args:
+        obj: A JSON-serializable Python object (dict, list, str,
+            int, float, bool, None).
+
+    Returns:
+        UTF-8 encoded canonical JSON bytes.
+    """
+    return _serialize(obj).encode("utf-8")

validibot_shared-0.13.0/validibot_shared/canonicalization.py

@@ -0,0 +1,57 @@
+"""RFC 8785 / JCS canonical JSON helpers shared across Validibot packages.
+
+The evidence manifest producer, workflow-definition digest, and Pro credential
+signing path all need the same deterministic byte representation. Keeping the
+canonicalizer in ``validibot-shared`` gives community evidence producers,
+commercial signing code, and third-party verifiers one portable contract instead
+of a Pro-owned implementation detail.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from pydantic import BaseModel
+
+from validibot_shared._vendor.jcs import canonicalize as _jcs_canonicalize
+
+
+def canonicalize_dict(data: dict[str, Any]) -> bytes:
+    """Canonicalize a plain dictionary via RFC 8785 / JCS.
+
+    Args:
+        data: A JSON-serializable dictionary.
+
+    Returns:
+        Canonical UTF-8 encoded JSON bytes per RFC 8785.
+    """
+    return _jcs_canonicalize(data)
+
+
+def sha256_hex_for_dict(data: dict[str, Any]) -> str:
+    """Compute the SHA-256 hex digest of a plain dict's canonical bytes."""
+    return hashlib.sha256(canonicalize_dict(data)).hexdigest()
+
+
+def canonicalize_model(schema_obj: BaseModel) -> bytes:
+    """Canonicalize a Pydantic model via ``model_dump(mode="json")`` + JCS.
+
+    ``mode="json"`` converts UUIDs, datetimes, and other Pydantic-native values
+    to JSON-compatible scalars before canonicalization. ``by_alias=True`` keeps
+    wire aliases such as ``@context`` intact.
+    """
+    return canonicalize_dict(schema_obj.model_dump(mode="json", by_alias=True))
+
+
+def sha256_hex_for_model(schema_obj: BaseModel) -> str:
+    """Compute the SHA-256 hex digest of a Pydantic model's canonical bytes."""
+    return hashlib.sha256(canonicalize_model(schema_obj)).hexdigest()
+
+
+__all__ = [
+    "canonicalize_dict",
+    "canonicalize_model",
+    "sha256_hex_for_dict",
+    "sha256_hex_for_model",
+]

validibot_shared-0.13.0/validibot_shared/validations/artifacts.py

@@ -0,0 +1,155 @@
+"""Shared artifact references and file-port contract vocabulary.
+
+These schemas are control-plane objects. They describe files, resources, and
+artifact references that Django materializes into validator envelopes; they do
+not contain file bytes or Django workflow models.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+ARTIFACT_REF_SCHEMA_VERSION = "validibot.artifact_ref.v1"
+
+
+class ArtifactKind(str, Enum):
+    """Storage-backed artifact kind."""
+
+    FILE = "file"
+    DIRECTORY = "directory"
+    ARCHIVE = "archive"
+    DATASET = "dataset"
+    REPORT = "report"
+    LOG = "log"
+    OTHER = "other"
+
+
+class StepIODirection(str, Enum):
+    """Whether a step port is consumed or produced."""
+
+    INPUT = "input"
+    OUTPUT = "output"
+
+
+class StepIOMedium(str, Enum):
+    """Whether a step port carries a JSON value or artifact reference."""
+
+    VALUE = "value"
+    ARTIFACT = "artifact"
+
+
+class EnvelopeChannel(str, Enum):
+    """Wire-level envelope location for a resolved file port."""
+
+    INPUT_FILES = "input_files"
+    RESOURCE_FILES = "resource_files"
+    OUTPUT_ARTIFACTS = "output_artifacts"
+
+
+class BindingSourceScope(str, Enum):
+    """Source scopes available to file-port and value bindings."""
+
+    SUBMISSION_PAYLOAD = "submission_payload"
+    SUBMISSION_METADATA = "submission_metadata"
+    SUBMISSION_FILE = "submission_file"
+    UPSTREAM_STEP = "upstream_step"
+    UPSTREAM_ARTIFACT = "upstream_artifact"
+    SIGNAL = "signal"
+    CONSTANT = "constant"
+    WORKFLOW_RESOURCE = "workflow_resource"
+    SYSTEM = "system"
+
+
+class DefaultSourceStrategy(str, Enum):
+    """Automatic or suggested source-selection behavior for a file port."""
+
+    SUBMITTED_FILE_FIRST = "submitted_file_first"
+    SUBMITTED_FILE_THEN_DEFAULT_RESOURCE = "submitted_file_then_default_resource"
+    WORKFLOW_RESOURCE_DEFAULT = "workflow_resource_default"
+    UPSTREAM_ARTIFACT_SUGGESTION = "upstream_artifact_suggestion"
+    MANUAL = "manual"
+    NONE = "none"
+
+
+class FilePortContract(BaseModel):
+    """Shared description of a file-like step input or output port."""
+
+    contract_key: str = Field(
+        description="Stable Validibot port key, e.g. primary_model."
+    )
+    label: str = Field(default="", description="Human-facing port label.")
+    direction: StepIODirection = Field(description="Whether this port is input/output.")
+    io_medium: StepIOMedium = Field(
+        default=StepIOMedium.ARTIFACT,
+        description="File ports carry artifact references.",
+    )
+    envelope_channel: EnvelopeChannel = Field(
+        description="Envelope channel this port renders into."
+    )
+    role: str = Field(
+        default="",
+        description="Backend-facing role for input_files or output artifacts.",
+    )
+    resource_type: str = Field(
+        default="",
+        description="Backend-facing resource type for resource_files.",
+    )
+    artifact_kind: ArtifactKind = Field(
+        default=ArtifactKind.FILE,
+        description="Expected kind for artifact references.",
+    )
+    min_items: int = Field(default=0, ge=0, description="Minimum item count.")
+    max_items: int | None = Field(
+        default=1,
+        ge=1,
+        description="Maximum item count; None means deliberately unbounded.",
+    )
+    accepted_data_formats: list[str] = Field(default_factory=list)
+    accepted_media_types: list[str] = Field(default_factory=list)
+    allowed_source_scopes: list[BindingSourceScope] = Field(default_factory=list)
+    default_source_strategy: DefaultSourceStrategy = DefaultSourceStrategy.NONE
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"extra": "forbid"}
+
+
+class ArtifactRef(BaseModel):
+    """Small JSON-safe pointer to a run-scoped artifact."""
+
+    schema_version: Literal["validibot.artifact_ref.v1"] = ARTIFACT_REF_SCHEMA_VERSION
+
+    artifact_id: str
+    run_id: str
+    step_run_id: str
+    producer_step_key: str
+
+    contract_key: str
+    name: str
+    role: str = ""
+    kind: ArtifactKind = ArtifactKind.FILE
+
+    media_type: str = ""
+    data_format: str = ""
+    filename: str = ""
+    size_bytes: int | None = None
+    sha256: str = ""
+
+    uri: str = Field(
+        default="",
+        description="Internal storage URI; not a public download URL.",
+    )
+    manifest_uri: str = ""
+    manifest_sha256: str = ""
+
+    producer_validator_type: str = ""
+    producer_validator_version: str = ""
+    producer_backend_image_digest: str = ""
+
+    retention_class: str = ""
+    labels: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"extra": "forbid"}

{validibot_shared-0.12.0 → validibot_shared-0.13.0}/validibot_shared/validations/envelopes.py

@@ -205,6 +205,14 @@ class InputFileItem(BaseModel):
         description="Validator-specific role (e.g., 'primary-model', 'config')",
     )
 
+    port_key: str | None = Field(
+        default=None,
+        description=(
+            "Declared Validibot file-port key that produced this envelope item "
+            "(e.g., 'primary_model'). Optional for backwards-compatible rollout."
+        ),
+    )
+
     uri: str = Field(
         description="Storage URI to the file (gs:// or file:// for self-hosted)"
     )
@@ -232,6 +240,14 @@ class ResourceFileItem(BaseModel):
         description="Resource type (e.g., 'weather', 'library', 'config')"
     )
 
+    port_key: str | None = Field(
+        default=None,
+        description=(
+            "Declared Validibot file-port key that produced this resource item "
+            "(e.g., 'weather_file'). Optional for backwards-compatible rollout."
+        ),
+    )
+
     uri: str = Field(
         description="Storage URI to the file (gs:// or file:// for self-hosted)"
     )