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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.9.2
+Version: 0.10.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
@@ -26,8 +26,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: pydantic<3.0,>=2.13
 Provides-Extra: dev
-Requires-Dist: pytest==9.0.3; extra == 'dev'
-Requires-Dist: ruff==0.15.15; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: ruff==0.15.18; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.9.2"
+version = "0.10.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"]
 
 [project.optional-dependencies]
-dev = ["pytest==9.0.3", "ruff==0.15.15"]
+dev = ["pytest==9.1.1", "ruff==0.15.18"]
 
 [project.urls]
 Homepage = "https://validibot.com"

{validibot_shared-0.9.2 → validibot_shared-0.10.0}/tests/test_evidence_manifest.py

@@ -25,6 +25,8 @@ from pydantic import ValidationError
 
 from validibot_shared.evidence import (
     SCHEMA_VERSION,
+    ContractConstant,
+    ContractSignalMapping,
     EvidenceManifest,
     ManifestPayloadDigests,
     ManifestRetentionInfo,
@@ -165,6 +167,116 @@ class TestOptionalFields:
         assert manifest.schema_version == "validibot.evidence.v1"
 
 
+# ──────────────────────────────────────────────────────────────────────
+# WorkflowContractSnapshot — constants, signal-mapping defs, definition hash
+# ──────────────────────────────────────────────────────────────────────
+#
+# ADR-2026-06-18. These three fields are additive and optional: a producer
+# predating them (or a workflow with none) leaves them empty, and the schema
+# stays ``validibot.evidence.v1``. Recording constants + signal-mapping
+# *definitions* + the definition hash is the transparency half of the constants
+# feature — it lets EVERY run (not just Pro-signed ones) carry "checked against
+# these constants". Resolved ``s.*`` values are deliberately NOT here (they are
+# submission-derived and retention-gated); only the definition is.
+
+
+class TestWorkflowContractPrimitives:
+    def test_new_fields_default_to_empty(self):
+        """A producer predating this change (or a bare workflow) leaves them empty.
+
+        Back-compat is the whole reason these are additive-optional: an older
+        manifest that never set them must still validate.
+        """
+        snap = WorkflowContractSnapshot(allowed_file_types=["json"])
+        assert snap.constants == []
+        assert snap.signal_mappings == []
+        assert snap.workflow_definition_hash == ""
+
+    def test_constant_value_is_preserved_verbatim(self):
+        """A NUMBER constant's decimal string is stored exactly (no float coercion).
+
+        The attested precision (``"0.40"``) must survive into the snapshot, or the
+        credential's "checked against c.energy_price = 0.40" claim would drift
+        from the value actually recorded.
+        """
+        snap = WorkflowContractSnapshot(
+            constants=[
+                ContractConstant(
+                    name="energy_price",
+                    data_type="NUMBER",
+                    value="0.40",
+                ),
+                ContractConstant(
+                    name="allowed_currencies",
+                    data_type="LIST",
+                    value=["EUR", "GBP"],
+                ),
+            ],
+        )
+        assert snap.constants[0].value == "0.40"
+        assert snap.constants[1].value == ["EUR", "GBP"]
+
+    def test_signal_mapping_records_definition_not_value(self):
+        """The snapshot carries a signal's DEFINITION, never a resolved value.
+
+        Publishing ``source_path``/``on_missing``/``default`` is safe; a resolved
+        ``s.*`` value is submission-derived and must not appear in the
+        always-publishable contract.
+        """
+        snap = WorkflowContractSnapshot(
+            signal_mappings=[
+                ContractSignalMapping(
+                    name="reported_total",
+                    source_path="$.total",
+                    on_missing="error",
+                ),
+            ],
+        )
+        mapping = snap.signal_mappings[0]
+        assert mapping.name == "reported_total"
+        assert mapping.source_path == "$.total"
+        # There is no place to smuggle a resolved value in — the model has no
+        # such field.
+        assert not hasattr(mapping, "resolved_value")
+
+    def test_primitives_survive_json_round_trip(self):
+        """The fields serialize and re-validate identically (canonical evidence).
+
+        The manifest is hashed and signed as JSON, so the new fields must
+        round-trip through ``model_dump``/``model_validate`` unchanged.
+        """
+        snap = WorkflowContractSnapshot(
+            constants=[ContractConstant(name="p", data_type="NUMBER", value="0.40")],
+            signal_mappings=[ContractSignalMapping(name="t", source_path="$.t")],
+            workflow_definition_hash="sha256:deadbeef",
+        )
+        restored = WorkflowContractSnapshot.model_validate(
+            snap.model_dump(mode="json"),
+        )
+        assert restored == snap
+
+    def test_additive_fields_preserve_v1_schema(self):
+        """A manifest carrying constants still reports schema_version v1.
+
+        Additive optional fields preserve v1 per the module's own policy;
+        bumping SCHEMA_VERSION here would be wrong.
+        """
+        manifest = EvidenceManifest(
+            **{
+                **_minimal_manifest_kwargs(),
+                "workflow_contract": WorkflowContractSnapshot(
+                    allowed_file_types=["json"],
+                    constants=[
+                        ContractConstant(name="p", data_type="NUMBER", value="0.40"),
+                    ],
+                    workflow_definition_hash="sha256:abc",
+                ),
+            },
+        )
+        assert manifest.schema_version == "validibot.evidence.v1"
+        assert manifest.workflow_contract.constants[0].name == "p"
+
+
 # ──────────────────────────────────────────────────────────────────────
 # StepValidatorRecord — semantic_digest can be None for legacy validators
 # ──────────────────────────────────────────────────────────────────────

{validibot_shared-0.9.2 → validibot_shared-0.10.0}/validibot_shared/__init__.py

@@ -9,6 +9,8 @@ from validibot_shared.evidence import (
     SCHEMA_VERSION as EVIDENCE_SCHEMA_VERSION,
 )
 from validibot_shared.evidence import (
+    ContractConstant,
+    ContractSignalMapping,
     EvidenceManifest,
     ManifestPayloadDigests,
     ManifestRetentionInfo,
@@ -26,6 +28,8 @@ from validibot_shared.shacl.envelopes import (
 
 __all__ = [
     "EVIDENCE_SCHEMA_VERSION",
+    "ContractConstant",
+    "ContractSignalMapping",
     "EnergyPlusSimulationLogs",
     "EnergyPlusSimulationMetrics",
     "EnergyPlusSimulationOutputs",

{validibot_shared-0.9.2 → validibot_shared-0.10.0}/validibot_shared/evidence/__init__.py

@@ -9,6 +9,8 @@ manifest without pulling in the application stack.
 
 from validibot_shared.evidence.manifest import (
     SCHEMA_VERSION,
+    ContractConstant,
+    ContractSignalMapping,
     EvidenceManifest,
     ManifestPayloadDigests,
     ManifestRetentionInfo,
@@ -18,6 +20,8 @@ from validibot_shared.evidence.manifest import (
 
 __all__ = [
     "SCHEMA_VERSION",
+    "ContractConstant",
+    "ContractSignalMapping",
     "EvidenceManifest",
     "ManifestPayloadDigests",
     "ManifestRetentionInfo",

{validibot_shared-0.9.2 → validibot_shared-0.10.0}/validibot_shared/evidence/manifest.py

@@ -49,7 +49,7 @@ file in the export bundle.
 
 from __future__ import annotations
 
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -110,6 +110,44 @@ class StepValidatorRecord(BaseModel):
     )
 
 
+class ContractConstant(BaseModel):
+    """A workflow Constant (the ``c.*`` namespace) recorded in the contract.
+
+    A Constant (ADR-2026-06-18) is a workflow-defined *fixed literal*, so its
+    name **and value** are always safe to publish in the contract snapshot —
+    unlike a resolved ``s.*`` signal value, which is submission-derived and must
+    stay in the retention-gated run record. ``value`` is the stored form: a
+    canonical decimal *string* for NUMBER (so ``"0.40"`` keeps its precision), a
+    ``str`` for STRING, a ``bool`` for BOOLEAN, and a ``list``/``dict`` for
+    LIST/OBJECT.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    data_type: str = ""
+    value: Any = None
+
+
+class ContractSignalMapping(BaseModel):
+    """A workflow signal-mapping *definition* recorded in the contract.
+
+    The workflow-defined config for an ``s.<name>`` signal — NOT its resolved
+    runtime value. Publishing the definition (how the signal is sourced) is safe
+    and lets a verifier see the contract; the *resolved* value is
+    submission-derived and belongs only in the retention-gated run record
+    (ADR-2026-06-18).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    source_path: str = ""
+    on_missing: str = ""
+    default_value: Any = None
+    data_type: str = ""
+
+
 class WorkflowContractSnapshot(BaseModel):
     """Frozen snapshot of the workflow's launch-contract fields.
 
@@ -139,6 +177,38 @@ class WorkflowContractSnapshot(BaseModel):
     agent_public_discovery: bool = False
     agent_access_enabled: bool = False
 
+    # ── Workflow contract primitives (ADR-2026-06-18) ────────────────────────
+    # Additive, optional fields — the schema stays ``validibot.evidence.v1``
+    # (additive changes preserve v1 by the policy documented at the top of this
+    # module; a bump would be wrong here). Producers that predate this change
+    # simply leave them empty, and older consumers ignore unknown-to-them fields.
+    constants: list[ContractConstant] = Field(
+        default_factory=list,
+        description=(
+            "Workflow Constants (c.* namespace) with their fixed values — the "
+            "named thresholds this run was judged against. Empty for workflows "
+            "with no constants or for producers predating this field."
+        ),
+    )
+    signal_mappings: list[ContractSignalMapping] = Field(
+        default_factory=list,
+        description=(
+            "Workflow signal-mapping DEFINITIONS (name + source_path + "
+            "on_missing + default + type) — never resolved s.* runtime values, "
+            "which are submission-derived and retention-gated."
+        ),
+    )
+    workflow_definition_hash: str = Field(
+        default="",
+        description=(
+            "The workflow-definition digest (e.g. 'sha256:...') covering the "
+            "semantic contract — constants, signal-mapping definitions, and "
+            "per-step validator + effective-ruleset + assertions. Lets a "
+            "verifier confirm the run's contract matches a claimed version. "
+            "Empty for producers predating this field."
+        ),
+    )
+
 
 class ManifestRetentionInfo(BaseModel):
     """Retention class + applied-redaction summary.