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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.13.0
+Version: 0.14.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

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

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

{validibot_shared-0.13.0 → validibot_shared-0.14.0}/tests/test_evidence_manifest.py

@@ -16,6 +16,9 @@ What this file covers
    computation depends on.
 4. Optional fields default sensibly so producers can build a
    minimal Session-A manifest without populating Session-B fields.
+5. Artifact lineage fields are additive, evidence-safe projections:
+   hashes and stable IDs are allowed; private storage URIs are not part
+   of the public schema.
 """
 
 from __future__ import annotations
@@ -28,7 +31,10 @@ from validibot_shared.evidence import (
     ContractConstant,
     ContractSignalMapping,
     EvidenceManifest,
+    ManifestArtifactInputBinding,
+    ManifestArtifactLineageEdge,
     ManifestPayloadDigests,
+    ManifestProducedArtifact,
     ManifestRetentionInfo,
     StepValidatorRecord,
     WorkflowContractSnapshot,
@@ -167,6 +173,78 @@ class TestOptionalFields:
         assert manifest.schema_version == "validibot.evidence.v1"
 
 
+# ──────────────────────────────────────────────────────────────────────
+# Artifact lineage — produced artifacts, consumed file-port bindings, edges
+# ──────────────────────────────────────────────────────────────────────
+#
+# ADR-2026-07-06. These fields make step artifacts externally verifiable
+# without exposing producer-private storage paths. They are additive and
+# default-empty, so the evidence schema string remains ``validibot.evidence.v1``.
+
+
+class TestArtifactLineageFields:
+    def test_lineage_fields_default_to_empty(self):
+        """Older producers and runs without artifacts remain valid."""
+        manifest = EvidenceManifest(**_minimal_manifest_kwargs())
+
+        assert manifest.produced_artifacts == []
+        assert manifest.artifact_input_bindings == []
+        assert manifest.artifact_lineage_edges == []
+
+    def test_artifact_lineage_records_round_trip_without_storage_uris(self):
+        """The public projection keeps IDs/hashes but has no URI slot.
+
+        Storage URIs are internal deployment details. Evidence needs the durable
+        proof material: artifact id, producer/consumer coordinates, filenames,
+        and SHA-256 hashes.
+        """
+        produced = ManifestProducedArtifact(
+            artifact_id="artifact-1",
+            run_id="run-1",
+            step_run_id="step-run-1",
+            producer_step_id=10,
+            producer_step_key="build_model",
+            contract_key="generated_model",
+            filename="model.epjson",
+            sha256="a" * 64,
+        )
+        binding = ManifestArtifactInputBinding(
+            target_step_id=20,
+            target_step_key="simulate",
+            target_step_run_id="step-run-2",
+            target_port_key="primary_model",
+            source_scope="upstream_artifact",
+            source_artifact_id="artifact-1",
+            source_filename="model.epjson",
+            source_sha256="a" * 64,
+            producer_step_key="build_model",
+            producer_contract_key="generated_model",
+            resolved=True,
+        )
+        edge = ManifestArtifactLineageEdge(
+            source_artifact_id="artifact-1",
+            source_step_key="build_model",
+            source_contract_key="generated_model",
+            source_sha256="a" * 64,
+            target_step_key="simulate",
+            target_port_key="primary_model",
+            target_step_run_id="step-run-2",
+        )
+
+        manifest = EvidenceManifest(
+            **_minimal_manifest_kwargs(),
+            produced_artifacts=[produced],
+            artifact_input_bindings=[binding],
+            artifact_lineage_edges=[edge],
+        )
+        restored = EvidenceManifest.model_validate(manifest.model_dump(mode="json"))
+
+        assert restored == manifest
+        assert restored.schema_version == "validibot.evidence.v1"
+        assert not hasattr(restored.produced_artifacts[0], "storage_uri")
+        assert not hasattr(restored.artifact_input_bindings[0], "uri")
+
+
 # ──────────────────────────────────────────────────────────────────────
 # WorkflowContractSnapshot — constants, signal-mapping defs, definition hash
 # ──────────────────────────────────────────────────────────────────────

{validibot_shared-0.13.0 → validibot_shared-0.14.0}/validibot_shared/evidence/__init__.py

@@ -12,7 +12,10 @@ from validibot_shared.evidence.manifest import (
     ContractConstant,
     ContractSignalMapping,
     EvidenceManifest,
+    ManifestArtifactInputBinding,
+    ManifestArtifactLineageEdge,
     ManifestPayloadDigests,
+    ManifestProducedArtifact,
     ManifestRetentionInfo,
     StepValidatorRecord,
     WorkflowContractSnapshot,
@@ -23,7 +26,10 @@ __all__ = [
     "ContractConstant",
     "ContractSignalMapping",
     "EvidenceManifest",
+    "ManifestArtifactInputBinding",
+    "ManifestArtifactLineageEdge",
     "ManifestPayloadDigests",
+    "ManifestProducedArtifact",
     "ManifestRetentionInfo",
     "StepValidatorRecord",
     "WorkflowContractSnapshot",

{validibot_shared-0.13.0 → validibot_shared-0.14.0}/validibot_shared/evidence/manifest.py

@@ -267,6 +267,160 @@ class ManifestPayloadDigests(BaseModel):
     )
 
 
+class ManifestProducedArtifact(BaseModel):
+    """Public, durable projection of an artifact produced by a run step.
+
+    This deliberately omits storage locations (``storage_uri`` and
+    ``manifest_uri`` in the Django model / ArtifactRef). Evidence consumers need
+    stable identity, hashes, producer coordinates, and file descriptors; private
+    bucket paths stay inside the producer.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    artifact_id: str = Field(description="Producer-side Artifact primary key.")
+    run_id: str = Field(description="Run UUID that owns the artifact.")
+    step_run_id: str | None = Field(
+        default=None,
+        description="Step-run UUID/primary key that produced the artifact.",
+    )
+    producer_step_id: int | None = Field(
+        default=None,
+        description="Producer-side WorkflowStep primary key, if step-scoped.",
+    )
+    producer_step_key: str = Field(
+        default="",
+        description="Stable workflow-local key of the producer step.",
+    )
+    producer_step_name: str = Field(
+        default="",
+        description="Human-facing producer step name at run time.",
+    )
+    contract_key: str = Field(description="Stable artifact output contract key.")
+    item_key: str = Field(
+        default="",
+        description="Stable collection item key, empty for scalar artifact ports.",
+    )
+    filename: str = Field(default="", description="Original/public filename.")
+    label: str = Field(default="", description="Human-facing artifact label.")
+    role: str = Field(default="", description="Validator-facing artifact role.")
+    kind: str = Field(default="", description="Artifact kind.")
+    media_type: str = Field(default="", description="Media/MIME type.")
+    data_format: str = Field(default="", description="Domain data format.")
+    size_bytes: int | None = Field(default=None, description="Artifact byte size.")
+    sha256: str = Field(default="", description="SHA-256 of artifact bytes.")
+    manifest_sha256: str = Field(
+        default="",
+        description="SHA-256 of the validator output manifest, if present.",
+    )
+    producer_validator_type: str = Field(
+        default="",
+        description="Validator type that produced the artifact.",
+    )
+    producer_validator_version: str = Field(
+        default="",
+        description="Validator version that produced the artifact.",
+    )
+    producer_backend_image_digest: str = Field(
+        default="",
+        description="Backend image digest that produced the artifact.",
+    )
+    retention_class: str = Field(
+        default="",
+        description="Output-retention class attached to the artifact.",
+    )
+
+
+class ManifestArtifactInputBinding(BaseModel):
+    """Runtime file-port binding consumed by a step.
+
+    Each row records what artifact-like source satisfied a declared input port:
+    submitted file, workflow resource, or upstream artifact. URI-bearing runtime
+    traces are projected into filename/hash/ID fields only.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    target_step_id: int = Field(description="WorkflowStep primary key consuming it.")
+    target_step_key: str = Field(description="Stable key of the consumer step.")
+    target_step_name: str = Field(default="", description="Consumer step name.")
+    target_step_run_id: str = Field(default="", description="Consumer step-run id.")
+    target_port_key: str = Field(description="Declared artifact input port key.")
+    target_port_role: str = Field(default="", description="Backend-facing port role.")
+    target_envelope_channel: str = Field(
+        default="",
+        description="Envelope channel used by the port.",
+    )
+    source_scope: str = Field(
+        description="Runtime source scope used to resolve the binding.",
+    )
+    source_data_path: str = Field(
+        default="",
+        description="Runtime source path used to resolve the binding.",
+    )
+    resolved: bool = Field(description="Whether runtime resolution succeeded.")
+    used_default: bool = Field(
+        default=False,
+        description="Whether a default satisfied the input.",
+    )
+    source_artifact_id: str = Field(
+        default="",
+        description="Upstream Artifact id, for upstream_artifact bindings.",
+    )
+    source_submission_file_id: str = Field(
+        default="",
+        description="SubmissionInputFile id, for submitted artifact-port files.",
+    )
+    source_submission_id: str = Field(
+        default="",
+        description="Submission id for the primary submitted file, when used.",
+    )
+    source_resource_id: str = Field(
+        default="",
+        description="Workflow/resource id, for workflow_resource bindings.",
+    )
+    source_filename: str = Field(default="", description="Resolved source filename.")
+    source_media_type: str = Field(
+        default="",
+        description="Resolved source media type.",
+    )
+    source_data_format: str = Field(
+        default="",
+        description="Resolved source data format or resource type.",
+    )
+    source_size_bytes: int | None = Field(default=None)
+    source_sha256: str = Field(default="", description="Resolved source SHA-256.")
+    producer_step_key: str = Field(
+        default="",
+        description="Producer step key for upstream_artifact bindings.",
+    )
+    producer_contract_key: str = Field(
+        default="",
+        description="Producer artifact contract key for upstream_artifact bindings.",
+    )
+    error_message: str = Field(
+        default="",
+        description="Resolution error when resolved=false.",
+    )
+
+
+class ManifestArtifactLineageEdge(BaseModel):
+    """Explicit upstream-artifact edge from producer output to consumer input."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_artifact_id: str = Field(description="Produced Artifact id.")
+    source_step_key: str = Field(default="", description="Producer step key.")
+    source_contract_key: str = Field(
+        default="",
+        description="Producer artifact contract key.",
+    )
+    source_sha256: str = Field(default="", description="Produced artifact SHA-256.")
+    target_step_key: str = Field(description="Consumer step key.")
+    target_port_key: str = Field(description="Consumer artifact input port key.")
+    target_step_run_id: str = Field(default="", description="Consumer step-run id.")
+
+
 class EvidenceManifest(BaseModel):
     """Top-level evidence manifest for a single validation run.
 
@@ -321,6 +475,29 @@ class EvidenceManifest(BaseModel):
         default_factory=ManifestPayloadDigests,
         description="Session A: empty. Session B: input + output hashes.",
     )
+    produced_artifacts: list[ManifestProducedArtifact] = Field(
+        default_factory=list,
+        description=(
+            "Artifacts produced by this run, projected without private storage "
+            "URIs. Empty for runs with no artifacts or producers predating "
+            "artifact lineage evidence."
+        ),
+    )
+    artifact_input_bindings: list[ManifestArtifactInputBinding] = Field(
+        default_factory=list,
+        description=(
+            "Runtime artifact file-port inputs consumed by steps: submitted "
+            "files, workflow resources, and upstream artifacts."
+        ),
+    )
+    artifact_lineage_edges: list[ManifestArtifactLineageEdge] = Field(
+        default_factory=list,
+        description=(
+            "Producer artifact -> consumer port edges for upstream_artifact "
+            "bindings. Submitted files and workflow resources are recorded in "
+            "artifact_input_bindings but do not create producer-step edges."
+        ),
+    )
     # The auth channel that initiated the run.  Pinning it in the
     # manifest lets verifiers answer "what surface produced this
     # run?" without consulting the producer database (the run row
@@ -346,7 +523,10 @@ class EvidenceManifest(BaseModel):
 __all__ = [
     "SCHEMA_VERSION",
     "EvidenceManifest",
+    "ManifestArtifactInputBinding",
+    "ManifestArtifactLineageEdge",
     "ManifestPayloadDigests",
+    "ManifestProducedArtifact",
     "ManifestRetentionInfo",
     "StepValidatorRecord",
     "WorkflowContractSnapshot",